From 86386ce7dd97cd7f5b6a0a8c32be58c9522a84e5 Mon Sep 17 00:00:00 2001
From: Raman Shekhawat <raman.s@parity.io>
Date: Tue, 30 Jun 2026 05:55:42 +0530
Subject: [PATCH] feat: refactor host and add unit tests

---
 apps/host/package.json                        |   3 +
 apps/host/src/host-url.ts                     |  87 +++
 apps/host/src/main.ts                         |  84 +--
 apps/host/tests/unit/host-url.test.ts         | 105 ++++
 apps/host/vitest.config.ts                    |  21 +
 bun.lock                                      |   2 +
 .../protocol/src/broker-follow-registry.ts    | 224 +++++++
 packages/protocol/src/broker-jsonrpc.ts       |  90 +++
 .../protocol/src/broker-session-registry.ts   |  49 ++
 .../protocol/src/broker-token-registry.ts     |  69 +++
 packages/protocol/src/broker-types.ts         | 103 ++++
 packages/protocol/src/broker.ts               | 478 +++------------
 .../protocol/tests/broker-jsonrpc.test.ts     | 178 ++++++
 .../protocol/tests/broker-registries.test.ts  | 201 +++++++
 packages/ui/src/container-product.ts          |  95 +++
 packages/ui/src/container.ts                  |  93 +--
 packages/ui/src/event-manager.ts              |  69 +++
 packages/ui/src/topbar-diagnostics.ts         | 486 ++++++++++++++++
 packages/ui/src/topbar-dom.ts                 |  13 +
 packages/ui/src/topbar-format.ts              |  81 +++
 packages/ui/src/topbar.ts                     | 549 +-----------------
 packages/ui/tests/container-product.test.ts   | 100 ++++
 packages/ui/tests/event-manager.test.ts       |  75 +++
 packages/ui/tests/topbar-format.test.ts       | 109 ++++
 24 files changed, 2261 insertions(+), 1103 deletions(-)
 create mode 100644 apps/host/src/host-url.ts
 create mode 100644 apps/host/tests/unit/host-url.test.ts
 create mode 100644 apps/host/vitest.config.ts
 create mode 100644 packages/protocol/src/broker-follow-registry.ts
 create mode 100644 packages/protocol/src/broker-jsonrpc.ts
 create mode 100644 packages/protocol/src/broker-session-registry.ts
 create mode 100644 packages/protocol/src/broker-token-registry.ts
 create mode 100644 packages/protocol/src/broker-types.ts
 create mode 100644 packages/protocol/tests/broker-jsonrpc.test.ts
 create mode 100644 packages/protocol/tests/broker-registries.test.ts
 create mode 100644 packages/ui/src/container-product.ts
 create mode 100644 packages/ui/src/event-manager.ts
 create mode 100644 packages/ui/src/topbar-diagnostics.ts
 create mode 100644 packages/ui/src/topbar-dom.ts
 create mode 100644 packages/ui/src/topbar-format.ts
 create mode 100644 packages/ui/tests/container-product.test.ts
 create mode 100644 packages/ui/tests/event-manager.test.ts
 create mode 100644 packages/ui/tests/topbar-format.test.ts

diff --git a/apps/host/package.json b/apps/host/package.json
index b3789ff6..39c15f58 100644
--- a/apps/host/package.json
+++ b/apps/host/package.json
@@ -13,6 +13,7 @@
     "test:perf:base": "PERF_RUNS=20 PERF_SAVE_BASE=1 PERF_DOMAIN_A=explore PERF_DOMAIN_B=host-playground npx playwright test --config=tests/performance/playwright.config.ts tests/performance/cold-start.spec.ts",
     "test:perf:compare": "bun tests/performance/compare.ts",
     "test:perf:compare:md": "bun tests/performance/compare.ts --markdown",
+    "test": "vitest run",
     "lint": "bunx eslint src/",
     "typecheck": "tsc --noEmit"
   },
@@ -23,11 +24,13 @@
     "playwright": "^1.59.1",
     "@types/node": "^25.9.3",
     "eslint": "^10.5.0",
+    "happy-dom": "^20.10.3",
     "jsqr": "^1.4.0",
     "prettier": "^3.8.3",
     "simple-statistics": "^7.9.0",
     "typescript": "~6.0.3",
     "vite": "^8.0.16",
+    "vitest": "^4.1.8",
     "vite-plugin-pwa": "^1.2.0",
     "vite-plugin-wasm": "^3.5.0",
     "workbox-window": "^7.4.0"
diff --git a/apps/host/src/host-url.ts b/apps/host/src/host-url.ts
new file mode 100644
index 00000000..7e5d18c3
--- /dev/null
+++ b/apps/host/src/host-url.ts
@@ -0,0 +1,87 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// URL/label parsing helpers for the host shell. Kept separate from the
+// main entry wiring so the parsing logic can be unit-tested in isolation.
+
+import { BASE_DOMAIN, DEBUG } from "@dotli/config/config";
+import { isValidDotLabel } from "@dotli/shared/html";
+
+export function parseLocalhostUrl(): string | null {
+  if (!DEBUG) {
+    return null;
+  }
+  const path = window.location.pathname;
+  const match = /^\/(localhost(?::\d+)?)(.*)$/.exec(path);
+  if (match === null) {
+    return null;
+  }
+  const host = match[1];
+  const rest = match[2] || "";
+  // Strip every reserved host-URL param so they do not leak into the
+  // proxied product. Covers the five settings axes, the sandbox contract's
+  // host-only signals (`fullReset`, `v`), and the Playwright auth hook.
+  const productSearch = new URLSearchParams(window.location.search);
+  for (const k of RESERVED_HOST_PARAMS) {
+    productSearch.delete(k);
+  }
+  const query = productSearch.toString();
+  return `http://${host}${rest}${query ? `?${query}` : ""}${window.location.hash}`;
+}
+
+const RESERVED_HOST_PARAMS = [
+  "network",
+  "chainBackend",
+  "skipArchiveCache",
+  "skipCidCache",
+  "skipWorkerCache",
+  "fullReset",
+  "v",
+  "initAuthSubscribe",
+] as const;
+
+/**
+ * Extract the `.dot` label from the current hostname.
+ *
+ * Returns `"myapp"` for `myapp.dot.li` or `myapp.localhost`. Returns `null`
+ * for the bare landing pages (`dot.li`, `localhost`) and for sandbox origins
+ * (`*.app.dot.li`, `*.app.localhost`), which are handled by `app-main.ts`.
+ *
+ * The parsed label is validated against the closed `.dot` label charset as
+ * defense-in-depth before it is threaded into key derivation, origin
+ * construction (`<label>.app.<root>`), and host-shell sinks. A malformed
+ * label can never be a registered `.dot` name, so returning `null` (which
+ * routes to the landing/preview path) is the safe outcome.
+ */
+export function parseDotLabel(): string | null {
+  const hostname = window.location.hostname;
+
+  // Production: name.{BASE_DOMAIN} (but NOT *.app.{BASE_DOMAIN})
+  if (hostname.endsWith(`.${BASE_DOMAIN}`)) {
+    if (hostname.endsWith(`.app.${BASE_DOMAIN}`)) {
+      return null;
+    }
+    const label = hostname.slice(0, -(BASE_DOMAIN.length + 1));
+    return isValidDotLabel(label) ? label : null;
+  }
+
+  // Local dev: name.localhost (but NOT *.app.localhost)
+  if (hostname.endsWith(".localhost")) {
+    if (hostname.endsWith(".app.localhost")) {
+      return null;
+    }
+    const label = hostname.slice(0, -".localhost".length);
+    return isValidDotLabel(label) ? label : null;
+  }
+
+  return null;
+}
+
+export function hexToBytes(s: string): Uint8Array {
+  const h = s.startsWith("0x") ? s.slice(2) : s;
+  const bytes = new Uint8Array(h.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
diff --git a/apps/host/src/main.ts b/apps/host/src/main.ts
index 14704c33..89296602 100644
--- a/apps/host/src/main.ts
+++ b/apps/host/src/main.ts
@@ -65,10 +65,10 @@ import type {
   ManifestResult,
   RootManifest,
 } from "@dotli/resolver/manifest";
-import { BASE_DOMAIN, DEBUG, SITE_ID } from "@dotli/config/config";
+import { DEBUG, SITE_ID } from "@dotli/config/config";
 import { log } from "@dotli/shared/log";
 import { serializeError } from "@dotli/shared/errors";
-import { escapeHtml, isValidDotLabel } from "@dotli/shared/html";
+import { escapeHtml } from "@dotli/shared/html";
 import { isMobileDevice } from "@dotli/shared/device";
 import { showNotification } from "@dotli/ui/notification";
 import { initScheduledNotifications } from "@dotli/ui/scheduled-notifications";
@@ -95,6 +95,7 @@ import {
   REFRESH_BTN_LABEL,
 } from "./errors";
 import { parsePreviewTargetUrl } from "./preview-route";
+import { hexToBytes, parseDotLabel, parseLocalhostUrl } from "./host-url";
 
 // Surface chunk-load failures explicitly: capture the original cause to
 // Sentry and let the user opt into a reload, instead of reloading silently.
@@ -181,76 +182,6 @@ const T0 = performance.now();
  *   "/localhost"               yields "http://localhost"
  *   "/starter-template.dot"    yields null (not a localhost URL)
  */
-function parseLocalhostUrl(): string | null {
-  if (!DEBUG) {
-    return null;
-  }
-  const path = window.location.pathname;
-  const match = /^\/(localhost(?::\d+)?)(.*)$/.exec(path);
-  if (match === null) {
-    return null;
-  }
-  const host = match[1];
-  const rest = match[2] || "";
-  // Strip every reserved host-URL param so they do not leak into the
-  // proxied product. Covers the five settings axes, the sandbox contract's
-  // host-only signals (`fullReset`, `v`), and the Playwright auth hook.
-  const productSearch = new URLSearchParams(window.location.search);
-  for (const k of RESERVED_HOST_PARAMS) {
-    productSearch.delete(k);
-  }
-  const query = productSearch.toString();
-  return `http://${host}${rest}${query ? `?${query}` : ""}${window.location.hash}`;
-}
-
-const RESERVED_HOST_PARAMS = [
-  "network",
-  "chainBackend",
-  "skipArchiveCache",
-  "skipCidCache",
-  "skipWorkerCache",
-  "fullReset",
-  "v",
-  "initAuthSubscribe",
-] as const;
-
-/**
- * Extract the `.dot` label from the current hostname.
- *
- * Returns `"myapp"` for `myapp.dot.li` or `myapp.localhost`. Returns `null`
- * for the bare landing pages (`dot.li`, `localhost`) and for sandbox origins
- * (`*.app.dot.li`, `*.app.localhost`), which are handled by `app-main.ts`.
- *
- * The parsed label is validated against the closed `.dot` label charset as
- * defense-in-depth before it is threaded into key derivation, origin
- * construction (`<label>.app.<root>`), and host-shell sinks. A malformed
- * label can never be a registered `.dot` name, so returning `null` (which
- * routes to the landing/preview path) is the safe outcome.
- */
-function parseDotLabel(): string | null {
-  const hostname = window.location.hostname;
-
-  // Production: name.{BASE_DOMAIN} (but NOT *.app.{BASE_DOMAIN})
-  if (hostname.endsWith(`.${BASE_DOMAIN}`)) {
-    if (hostname.endsWith(`.app.${BASE_DOMAIN}`)) {
-      return null;
-    }
-    const label = hostname.slice(0, -(BASE_DOMAIN.length + 1));
-    return isValidDotLabel(label) ? label : null;
-  }
-
-  // Local dev: name.localhost (but NOT *.app.localhost)
-  if (hostname.endsWith(".localhost")) {
-    if (hostname.endsWith(".app.localhost")) {
-      return null;
-    }
-    const label = hostname.slice(0, -".localhost".length);
-    return isValidDotLabel(label) ? label : null;
-  }
-
-  return null;
-}
-
 /**
  * Set the verification shield state in the URL pill.
  *
@@ -691,15 +622,6 @@ interface AuthSubscribeApi {
   ) => Promise<{ count: number; isComplete: boolean }>;
 }
 
-function hexToBytes(s: string): Uint8Array {
-  const h = s.startsWith("0x") ? s.slice(2) : s;
-  const bytes = new Uint8Array(h.length / 2);
-  for (let i = 0; i < bytes.length; i++) {
-    bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
-  }
-  return bytes;
-}
-
 async function runAuthSubscribeHook(chainBackend: string): Promise<void> {
   log.warn("[dot.li auth-subscribe] init auth + statement store");
   const authMod = await import("@dotli/auth/auth");
diff --git a/apps/host/tests/unit/host-url.test.ts b/apps/host/tests/unit/host-url.test.ts
new file mode 100644
index 00000000..27cba41c
--- /dev/null
+++ b/apps/host/tests/unit/host-url.test.ts
@@ -0,0 +1,105 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  hexToBytes,
+  parseDotLabel,
+  parseLocalhostUrl,
+} from "../../src/host-url.ts";
+
+// host-url reads window.location live, so each test stubs it. BASE_DOMAIN is
+// derived once at config import time from happy-dom's default localhost
+// origin, so it stays "dot.li" regardless of these per-test stubs.
+const realLocation = window.location;
+
+function setLocation(parts: {
+  hostname?: string;
+  pathname?: string;
+  search?: string;
+  hash?: string;
+}): void {
+  Object.defineProperty(window, "location", {
+    value: {
+      hostname: "localhost",
+      pathname: "/",
+      search: "",
+      hash: "",
+      ...parts,
+    },
+    writable: true,
+    configurable: true,
+  });
+}
+
+afterEach(() => {
+  Object.defineProperty(window, "location", {
+    value: realLocation,
+    writable: true,
+    configurable: true,
+  });
+});
+
+describe("hexToBytes", () => {
+  it("decodes a 0x-prefixed hex string", () => {
+    expect(Array.from(hexToBytes("0x010203"))).toEqual([1, 2, 3]);
+  });
+
+  it("decodes a bare hex string", () => {
+    expect(Array.from(hexToBytes("ff00ab"))).toEqual([255, 0, 171]);
+  });
+
+  it("returns an empty array for an empty input", () => {
+    expect(Array.from(hexToBytes("0x"))).toEqual([]);
+    expect(Array.from(hexToBytes(""))).toEqual([]);
+  });
+});
+
+describe("parseDotLabel", () => {
+  it("extracts the label from a production .dot.li host", () => {
+    setLocation({ hostname: "myapp.dot.li" });
+    expect(parseDotLabel()).toBe("myapp");
+  });
+
+  it("extracts the label from a .localhost host", () => {
+    setLocation({ hostname: "myapp.localhost" });
+    expect(parseDotLabel()).toBe("myapp");
+  });
+
+  it("returns null for sandbox app subdomains", () => {
+    setLocation({ hostname: "myapp.app.dot.li" });
+    expect(parseDotLabel()).toBeNull();
+    setLocation({ hostname: "myapp.app.localhost" });
+    expect(parseDotLabel()).toBeNull();
+  });
+
+  it("returns null for the bare landing pages", () => {
+    setLocation({ hostname: "dot.li" });
+    expect(parseDotLabel()).toBeNull();
+    setLocation({ hostname: "localhost" });
+    expect(parseDotLabel()).toBeNull();
+  });
+
+  it("returns null for a structurally invalid label (uppercase)", () => {
+    setLocation({ hostname: "MyApp.dot.li" });
+    expect(parseDotLabel()).toBeNull();
+  });
+});
+
+describe("parseLocalhostUrl", () => {
+  it("rebuilds the proxied URL and strips reserved host params", () => {
+    setLocation({
+      pathname: "/localhost:5173/app",
+      search: "?network=foo&keep=1",
+      hash: "#section",
+    });
+    expect(parseLocalhostUrl()).toBe(
+      "http://localhost:5173/app?keep=1#section",
+    );
+  });
+
+  it("returns null when the path is not a localhost proxy path", () => {
+    setLocation({ pathname: "/some/other/path" });
+    expect(parseLocalhostUrl()).toBeNull();
+  });
+});
diff --git a/apps/host/vitest.config.ts b/apps/host/vitest.config.ts
new file mode 100644
index 00000000..4895486b
--- /dev/null
+++ b/apps/host/vitest.config.ts
@@ -0,0 +1,21 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    // Scope strictly to the unit-test folder so the Playwright `.spec.ts`
+    // suites under tests/{functional,e2e,performance} are never picked up.
+    include: ["tests/unit/**/*.test.ts"],
+    environment: "happy-dom",
+    globals: false,
+  },
+  define: {
+    "import.meta.env.DEV": "false",
+    "import.meta.env.VITE_APP_DEBUG": '"true"',
+    // getEnabledNetworks() requires VITE_NETWORKS (no default by design); the
+    // test build supplies it the same way a deployment does.
+    "import.meta.env.VITE_NETWORKS": '"paseo-next-v2,previewnet"',
+  },
+});
diff --git a/bun.lock b/bun.lock
index 19807661..faa3ba77 100644
--- a/bun.lock
+++ b/bun.lock
@@ -34,6 +34,7 @@
         "@playwright/test": "^1.59.1",
         "@types/node": "^25.9.3",
         "eslint": "^10.5.0",
+        "happy-dom": "^20.10.3",
         "jsqr": "^1.4.0",
         "playwright": "^1.59.1",
         "prettier": "^3.8.3",
@@ -42,6 +43,7 @@
         "vite": "^8.0.16",
         "vite-plugin-pwa": "^1.2.0",
         "vite-plugin-wasm": "^3.5.0",
+        "vitest": "^4.1.8",
         "workbox-window": "^7.4.0",
       },
     },
diff --git a/packages/protocol/src/broker-follow-registry.ts b/packages/protocol/src/broker-follow-registry.ts
new file mode 100644
index 00000000..43171c94
--- /dev/null
+++ b/packages/protocol/src/broker-follow-registry.ts
@@ -0,0 +1,224 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { CachedBlock, SharedFollow } from "./broker-types.ts";
+import { isJsonRpcObject } from "./broker-jsonrpc.ts";
+
+interface LocalFollowToken {
+  sessionId: string;
+  followKey: string;
+}
+
+/**
+ * Owns the shared `chainHead_v1_follow` state: the per-follow-key shared
+ * subscription, the upstream<->shared binding, every session's local follow
+ * token, and the block-pin ref-counts. Multiple sessions following the same
+ * chain share one upstream follow, so this is where the ref-counting that
+ * prevents double-unpin / premature-unfollow lives.
+ */
+export class FollowRegistry {
+  private readonly sharedFollows = new Map<string, SharedFollow>();
+  private readonly upstreamFollowTokens = new Map<string, SharedFollow>();
+  private readonly localFollowTokens = new Map<string, LocalFollowToken>();
+
+  /** Get the shared follow for a follow key, creating it if absent. */
+  ensureShared(key: string): SharedFollow {
+    let sharedFollow = this.sharedFollows.get(key);
+    if (!sharedFollow) {
+      sharedFollow = {
+        key,
+        upstreamToken: null,
+        requestInFlight: false,
+        localTokens: new Set<string>(),
+        pendingLocals: [],
+        finalizedBlockHashes: [],
+        finalizedBlockRuntime: null,
+        bestBlockHash: null,
+        blocks: new Map<string, CachedBlock>(),
+        pins: new Map<string, Set<string>>(),
+      };
+      this.sharedFollows.set(key, sharedFollow);
+    }
+    return sharedFollow;
+  }
+
+  getShared(key: string): SharedFollow | undefined {
+    return this.sharedFollows.get(key);
+  }
+
+  deleteShared(key: string): void {
+    this.sharedFollows.delete(key);
+  }
+
+  getLocal(token: string): LocalFollowToken | undefined {
+    return this.localFollowTokens.get(token);
+  }
+
+  setLocal(token: string, entry: LocalFollowToken): void {
+    this.localFollowTokens.set(token, entry);
+  }
+
+  deleteLocal(token: string): void {
+    this.localFollowTokens.delete(token);
+  }
+
+  /** Snapshot of local-token entries; safe to mutate while iterating. */
+  localEntries(): [string, LocalFollowToken][] {
+    return [...this.localFollowTokens.entries()];
+  }
+
+  getByUpstream(upstreamToken: string): SharedFollow | undefined {
+    return this.upstreamFollowTokens.get(upstreamToken);
+  }
+
+  bindUpstream(upstreamToken: string, sharedFollow: SharedFollow): void {
+    this.upstreamFollowTokens.set(upstreamToken, sharedFollow);
+  }
+
+  unbindUpstream(upstreamToken: string): void {
+    this.upstreamFollowTokens.delete(upstreamToken);
+  }
+
+  /** Record that `localToken` holds a pin on `hash` for this shared follow. */
+  registerPin(
+    sharedFollow: SharedFollow,
+    localToken: string,
+    hash: string,
+  ): void {
+    let holders = sharedFollow.pins.get(hash);
+    if (!holders) {
+      holders = new Set<string>();
+      sharedFollow.pins.set(hash, holders);
+    }
+    holders.add(localToken);
+  }
+
+  /** Pin the blocks a follow event implies: `initialized` finalized blocks and `newBlock`. */
+  registerPinsFromEvent(
+    sharedFollow: SharedFollow,
+    localToken: string,
+    eventResult: unknown,
+  ): void {
+    if (!isJsonRpcObject(eventResult)) {
+      return;
+    }
+    if (eventResult.event === "initialized") {
+      const hashes = Array.isArray(eventResult.finalizedBlockHashes)
+        ? eventResult.finalizedBlockHashes
+        : [];
+      for (const hash of hashes) {
+        if (typeof hash === "string") {
+          this.registerPin(sharedFollow, localToken, hash);
+        }
+      }
+      return;
+    }
+    if (
+      eventResult.event === "newBlock" &&
+      typeof eventResult.blockHash === "string"
+    ) {
+      this.registerPin(sharedFollow, localToken, eventResult.blockHash);
+    }
+  }
+
+  /**
+   * Drop `localToken`'s hold on the given hashes (or all of them when null) and
+   * return the hashes no session holds anymore — the ones to unpin upstream.
+   */
+  releasePins(
+    sharedFollow: SharedFollow,
+    localToken: string,
+    hashes: string[] | null,
+  ): string[] {
+    const orphaned: string[] = [];
+    const entries = hashes ?? [...sharedFollow.pins.keys()];
+    for (const hash of entries) {
+      const holders = sharedFollow.pins.get(hash);
+      if (!holders) {
+        continue;
+      }
+      if (!holders.delete(localToken)) {
+        continue;
+      }
+      if (holders.size === 0) {
+        sharedFollow.pins.delete(hash);
+        orphaned.push(hash);
+      }
+    }
+    return orphaned;
+  }
+
+  cacheSharedFollowEvent(
+    sharedFollow: SharedFollow,
+    eventResult: unknown,
+  ): void {
+    if (!isJsonRpcObject(eventResult)) {
+      return;
+    }
+
+    const eventType =
+      typeof eventResult.event === "string" ? eventResult.event : "";
+    if (eventType === "initialized") {
+      const hashes = Array.isArray(eventResult.finalizedBlockHashes)
+        ? eventResult.finalizedBlockHashes.filter(
+            (hash): hash is string => typeof hash === "string",
+          )
+        : [];
+      sharedFollow.finalizedBlockHashes = hashes;
+      sharedFollow.finalizedBlockRuntime =
+        eventResult.finalizedBlockRuntime ?? null;
+      sharedFollow.blocks.clear();
+      sharedFollow.bestBlockHash = null;
+      return;
+    }
+
+    if (eventType === "newBlock") {
+      const blockHash =
+        typeof eventResult.blockHash === "string"
+          ? eventResult.blockHash
+          : null;
+      if (blockHash === null) {
+        return;
+      }
+      sharedFollow.blocks.set(blockHash, {
+        result: { ...eventResult },
+        parentBlockHash:
+          typeof eventResult.parentBlockHash === "string"
+            ? eventResult.parentBlockHash
+            : null,
+      });
+      return;
+    }
+
+    if (eventType === "bestBlockChanged") {
+      sharedFollow.bestBlockHash =
+        typeof eventResult.bestBlockHash === "string"
+          ? eventResult.bestBlockHash
+          : null;
+      return;
+    }
+
+    if (eventType === "finalized") {
+      const hashes = Array.isArray(eventResult.finalizedBlockHashes)
+        ? eventResult.finalizedBlockHashes.filter(
+            (hash): hash is string => typeof hash === "string",
+          )
+        : [];
+      sharedFollow.finalizedBlockHashes = hashes;
+      const pruned = Array.isArray(eventResult.prunedBlockHashes)
+        ? eventResult.prunedBlockHashes.filter(
+            (hash): hash is string => typeof hash === "string",
+          )
+        : [];
+      for (const hash of pruned) {
+        sharedFollow.blocks.delete(hash);
+      }
+    }
+  }
+
+  clear(): void {
+    this.sharedFollows.clear();
+    this.upstreamFollowTokens.clear();
+    this.localFollowTokens.clear();
+  }
+}
diff --git a/packages/protocol/src/broker-jsonrpc.ts b/packages/protocol/src/broker-jsonrpc.ts
new file mode 100644
index 00000000..f07a89b0
--- /dev/null
+++ b/packages/protocol/src/broker-jsonrpc.ts
@@ -0,0 +1,90 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type {
+  JsonRpcId,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  SubscriptionMessage,
+  WireMode,
+} from "./broker-types.ts";
+
+export function isJsonRpcObject(
+  value: unknown,
+): value is Record<string, unknown> & { jsonrpc?: string } {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function buildJsonRpcError(
+  id: JsonRpcId,
+  message: string,
+): Record<string, unknown> {
+  return { jsonrpc: "2.0", id, error: { code: -32603, message } };
+}
+
+export function buildJsonRpcResult(
+  id: JsonRpcId,
+  result: unknown,
+): Record<string, unknown> {
+  return { jsonrpc: "2.0", id, result };
+}
+
+export function isRequestMessage(value: unknown): value is JsonRpcRequest {
+  return isJsonRpcObject(value) && typeof value.method === "string";
+}
+
+export function isResponseMessage(value: unknown): value is JsonRpcResponse {
+  return isJsonRpcObject(value) && "id" in value && !("method" in value);
+}
+
+export function isSubscriptionMessage(
+  value: unknown,
+): value is SubscriptionMessage {
+  return (
+    isJsonRpcObject(value) &&
+    "method" in value &&
+    isJsonRpcObject(value.params) &&
+    "subscription" in value.params
+  );
+}
+
+/**
+ * Parse an inbound message into a JS object without guessing wire mode.
+ * The sender must match the broker's configured wire mode. Message shape
+ * never flips the whole broker's encoding. Strings are parsed for the
+ * object wire too, since some substrate clients serialize payloads
+ * inconsistently, but the result is always returned as an object.
+ */
+export function parseInbound(message: unknown): unknown {
+  if (typeof message === "string") {
+    return JSON.parse(message);
+  }
+  return message;
+}
+
+/** Encode a JS object into the given wire format. */
+export function encode(value: unknown, mode: WireMode): unknown {
+  return mode === "string" ? JSON.stringify(value) : value;
+}
+
+/** `chainHead_v1_unpin` takes its hash arg as a string or an array; normalize to an array. */
+export function normalizeUnpinHashes(param: unknown): string[] {
+  if (typeof param === "string") {
+    return [param];
+  }
+  if (Array.isArray(param)) {
+    return param.filter((hash): hash is string => typeof hash === "string");
+  }
+  return [];
+}
+
+export function cloneWithRewrittenFirstParam(
+  request: JsonRpcRequest,
+  rewrittenToken: string,
+): JsonRpcRequest {
+  const params: unknown[] = Array.isArray(request.params)
+    ? [...(request.params as unknown[])]
+    : [];
+  params[0] = rewrittenToken;
+  return { ...request, params };
+}
diff --git a/packages/protocol/src/broker-session-registry.ts b/packages/protocol/src/broker-session-registry.ts
new file mode 100644
index 00000000..357f3f45
--- /dev/null
+++ b/packages/protocol/src/broker-session-registry.ts
@@ -0,0 +1,49 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { Session } from "./broker-types.ts";
+import { encode } from "./broker-jsonrpc.ts";
+
+/**
+ * Owns the broker's live session map and the wire-format send primitive.
+ * Mirrors the subset of the `Map` API the broker used (`get`/`has`/`delete`/
+ * `size`) so the orchestration code reads the same, while centralizing
+ * session lifecycle in one testable place.
+ */
+export class SessionRegistry {
+  private readonly sessions = new Map<string, Session>();
+
+  has(id: string): boolean {
+    return this.sessions.has(id);
+  }
+
+  get(id: string): Session | undefined {
+    return this.sessions.get(id);
+  }
+
+  add(session: Session): void {
+    this.sessions.set(session.id, session);
+  }
+
+  delete(id: string): void {
+    this.sessions.delete(id);
+  }
+
+  /** Snapshot of session ids; safe to mutate the registry while iterating. */
+  ids(): string[] {
+    return [...this.sessions.keys()];
+  }
+
+  get size(): number {
+    return this.sessions.size;
+  }
+
+  values(): IterableIterator<Session> {
+    return this.sessions.values();
+  }
+
+  /** Send a JSON-RPC object to a session in its configured wire format. */
+  send(session: Session, obj: unknown): void {
+    session.onMessage(encode(obj, session.wireMode));
+  }
+}
diff --git a/packages/protocol/src/broker-token-registry.ts b/packages/protocol/src/broker-token-registry.ts
new file mode 100644
index 00000000..513ed6fe
--- /dev/null
+++ b/packages/protocol/src/broker-token-registry.ts
@@ -0,0 +1,69 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { OwnedToken } from "./broker-types.ts";
+
+/**
+ * Keeps the local-token <-> upstream-token mapping for session-owned
+ * subscriptions (e.g. `transaction_v1_broadcast`, `statement_subscribe`)
+ * consistent. The broker mints token strings and assigns release methods;
+ * this registry only guards the dual-map invariant so the two never drift.
+ */
+export class TokenRegistry {
+  private readonly localToOwned = new Map<string, OwnedToken>();
+  private readonly upstreamToOwned = new Map<string, OwnedToken>();
+
+  /** Link a freshly minted local token to its upstream token. */
+  link(localToken: string, upstreamToken: string, owned: OwnedToken): void {
+    this.localToOwned.set(localToken, owned);
+    this.upstreamToOwned.set(upstreamToken, owned);
+  }
+
+  ownedByLocal(localToken: string): OwnedToken | undefined {
+    return this.localToOwned.get(localToken);
+  }
+
+  ownedByUpstream(upstreamToken: string): OwnedToken | undefined {
+    return this.upstreamToOwned.get(upstreamToken);
+  }
+
+  /** Reverse lookup: the upstream token currently bound to `localToken`. */
+  upstreamForLocal(localToken: string): string | null {
+    for (const [upstreamToken, owned] of this.upstreamToOwned.entries()) {
+      if (owned.localToken === localToken) {
+        return upstreamToken;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Drop `localToken` and the upstream token it maps to. Returns the unlinked
+   * upstream token so the caller can notify upstream, or null when the local
+   * token was unknown or had no upstream mapping (the local entry is still
+   * removed in the former case, matching the broker's prior behavior).
+   */
+  unlinkByLocal(localToken: string): string | null {
+    if (!this.localToOwned.has(localToken)) {
+      return null;
+    }
+    this.localToOwned.delete(localToken);
+    let upstreamTokenToDelete: string | null = null;
+    for (const [upstreamToken, candidate] of this.upstreamToOwned.entries()) {
+      if (candidate.localToken === localToken) {
+        upstreamTokenToDelete = upstreamToken;
+        break;
+      }
+    }
+    if (upstreamTokenToDelete === null) {
+      return null;
+    }
+    this.upstreamToOwned.delete(upstreamTokenToDelete);
+    return upstreamTokenToDelete;
+  }
+
+  clear(): void {
+    this.localToOwned.clear();
+    this.upstreamToOwned.clear();
+  }
+}
diff --git a/packages/protocol/src/broker-types.ts b/packages/protocol/src/broker-types.ts
new file mode 100644
index 00000000..fe3aad86
--- /dev/null
+++ b/packages/protocol/src/broker-types.ts
@@ -0,0 +1,103 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { JsonRpcProvider } from "@polkadot-api/json-rpc-provider";
+
+/**
+ * String-wire variant of `JsonRpcConnection` exposed by `connectRemote`.
+ *
+ * The postMessage relay ships `message` as a string, while the upstream
+ * `JsonRpcConnection.send` takes `JsonRpcRequest` objects. The local string
+ * variant keeps `connectRemote`'s signature matched to the wire.
+ */
+export interface StringJsonRpcConnection {
+  send: (message: string) => void;
+  disconnect: () => void;
+}
+
+export type JsonRpcId = string | number | null;
+
+export interface JsonRpcRequest {
+  jsonrpc?: string;
+  id?: JsonRpcId;
+  method?: unknown;
+  params?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc?: string;
+  id?: JsonRpcId;
+  result?: unknown;
+  error?: unknown;
+}
+
+export interface SubscriptionMessage {
+  jsonrpc?: string;
+  method?: unknown;
+  params?: {
+    subscription?: unknown;
+    result?: unknown;
+  };
+}
+
+export interface PendingRequest {
+  sessionId: string;
+  clientId: JsonRpcId;
+  method: string;
+}
+
+export interface OwnedToken {
+  sessionId: string;
+  localToken: string;
+  releaseMethod: string;
+}
+
+export interface SharedFollow {
+  key: string;
+  upstreamToken: string | null;
+  requestInFlight: boolean;
+  localTokens: Set<string>;
+  pendingLocals: {
+    sessionId: string;
+    requestId: JsonRpcId;
+    localToken: string;
+  }[];
+  finalizedBlockHashes: string[];
+  finalizedBlockRuntime: unknown;
+  bestBlockHash: string | null;
+  blocks: Map<string, CachedBlock>;
+  /** Block hash -> local follow tokens still holding a pin on it. */
+  pins: Map<string, Set<string>>;
+}
+
+export interface CachedBlock {
+  result: Record<string, unknown>;
+  parentBlockHash: string | null;
+}
+
+export type WireMode = "string" | "object";
+
+export interface Session {
+  id: string;
+  onMessage: (message: unknown) => void;
+  ownedTokens: Set<string>;
+  connected: boolean;
+  /** Fixed at session creation, never inferred from message shape later. */
+  wireMode: WireMode;
+}
+
+/** Internal session handle returned by `ChainBroker.connect()`. */
+export interface BrokerConnection {
+  send: (message: unknown) => void;
+  disconnect: () => void;
+}
+
+export interface ChainBrokerManager {
+  connectRemote(
+    genesisHash: string,
+    connectionId: string,
+    onMessage: (message: string) => void,
+  ): StringJsonRpcConnection | null;
+  getLocalProvider(genesisHash: string): JsonRpcProvider | null;
+  disconnectAll(): void;
+}
diff --git a/packages/protocol/src/broker.ts b/packages/protocol/src/broker.ts
index 0eb8e776..13f6a6aa 100644
--- a/packages/protocol/src/broker.ts
+++ b/packages/protocol/src/broker.ts
@@ -6,80 +6,39 @@ import type {
   JsonRpcProvider,
   JsonRpcRequest as UpstreamJsonRpcRequest,
 } from "@polkadot-api/json-rpc-provider";
-
-/**
- * String-wire variant of `JsonRpcConnection` exposed by `connectRemote`.
- *
- * The postMessage relay ships `message` as a string, while the upstream
- * `JsonRpcConnection.send` takes `JsonRpcRequest` objects. The local string
- * variant keeps `connectRemote`'s signature matched to the wire.
- */
-export interface StringJsonRpcConnection {
-  send: (message: string) => void;
-  disconnect: () => void;
-}
-
-type JsonRpcId = string | number | null;
-
-interface JsonRpcRequest {
-  jsonrpc?: string;
-  id?: JsonRpcId;
-  method?: unknown;
-  params?: unknown;
-}
-
-interface JsonRpcResponse {
-  jsonrpc?: string;
-  id?: JsonRpcId;
-  result?: unknown;
-  error?: unknown;
-}
-
-interface SubscriptionMessage {
-  jsonrpc?: string;
-  method?: unknown;
-  params?: {
-    subscription?: unknown;
-    result?: unknown;
-  };
-}
-
-interface PendingRequest {
-  sessionId: string;
-  clientId: JsonRpcId;
-  method: string;
-}
-
-interface OwnedToken {
-  sessionId: string;
-  localToken: string;
-  releaseMethod: string;
-}
-
-interface SharedFollow {
-  key: string;
-  upstreamToken: string | null;
-  requestInFlight: boolean;
-  localTokens: Set<string>;
-  pendingLocals: {
-    sessionId: string;
-    requestId: JsonRpcId;
-    localToken: string;
-  }[];
-  finalizedBlockHashes: string[];
-  finalizedBlockRuntime: unknown;
-  bestBlockHash: string | null;
-  blocks: Map<string, CachedBlock>;
-  /** Block hash -> local follow tokens still holding a pin on it. */
-  pins: Map<string, Set<string>>;
-}
-
-interface CachedBlock {
-  result: Record<string, unknown>;
-  parentBlockHash: string | null;
-}
-
-type WireMode = "string" | "object";
+import type {
+  BrokerConnection,
+  ChainBrokerManager,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  OwnedToken,
+  PendingRequest,
+  Session,
+  SharedFollow,
+  SubscriptionMessage,
+  WireMode,
+} from "./broker-types.ts";
+import {
+  buildJsonRpcError,
+  buildJsonRpcResult,
+  cloneWithRewrittenFirstParam,
+  isJsonRpcObject,
+  isRequestMessage,
+  isResponseMessage,
+  isSubscriptionMessage,
+  normalizeUnpinHashes,
+  parseInbound,
+} from "./broker-jsonrpc.ts";
+import { SessionRegistry } from "./broker-session-registry.ts";
+import { TokenRegistry } from "./broker-token-registry.ts";
+import { FollowRegistry } from "./broker-follow-registry.ts";
+
+// Re-export the public broker types so existing `@dotli/protocol/broker`
+// importers keep resolving after the type/helper split.
+export type {
+  ChainBrokerManager,
+  StringJsonRpcConnection,
+} from "./broker-types.ts";
 
 // Wire mode is fixed at broker construction time. Auto-detecting from
 // message shape lets a malformed first payload silently flip the broker
@@ -91,114 +50,11 @@ type WireMode = "string" | "object";
 // "no silent fallbacks" contract.
 const DEFAULT_WIRE_MODE: WireMode = "string";
 
-interface Session {
-  id: string;
-  onMessage: (message: unknown) => void;
-  ownedTokens: Set<string>;
-  connected: boolean;
-  /** Fixed at session creation, never inferred from message shape later. */
-  wireMode: WireMode;
-}
-
-/** Internal session handle returned by `ChainBroker.connect()`. */
-interface BrokerConnection {
-  send: (message: unknown) => void;
-  disconnect: () => void;
-}
-
 const TOKEN_METHODS = new Map<string, string>([
   ["transaction_v1_broadcast", "transaction_v1_stop"],
   ["statement_subscribeStatement", "statement_unsubscribeStatement"],
 ]);
 
-function isJsonRpcObject(
-  value: unknown,
-): value is Record<string, unknown> & { jsonrpc?: string } {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function buildJsonRpcError(
-  id: JsonRpcId,
-  message: string,
-): Record<string, unknown> {
-  return { jsonrpc: "2.0", id, error: { code: -32603, message } };
-}
-
-function buildJsonRpcResult(
-  id: JsonRpcId,
-  result: unknown,
-): Record<string, unknown> {
-  return { jsonrpc: "2.0", id, result };
-}
-
-function isRequestMessage(value: unknown): value is JsonRpcRequest {
-  return isJsonRpcObject(value) && typeof value.method === "string";
-}
-
-function isResponseMessage(value: unknown): value is JsonRpcResponse {
-  return isJsonRpcObject(value) && "id" in value && !("method" in value);
-}
-
-function isSubscriptionMessage(value: unknown): value is SubscriptionMessage {
-  return (
-    isJsonRpcObject(value) &&
-    "method" in value &&
-    isJsonRpcObject(value.params) &&
-    "subscription" in value.params
-  );
-}
-
-/**
- * Parse an inbound message into a JS object without guessing wire mode.
- * The sender must match the broker's configured wire mode. Message shape
- * never flips the whole broker's encoding. Strings are parsed for the
- * object wire too, since some substrate clients serialize payloads
- * inconsistently, but the result is always returned as an object.
- */
-function parseInbound(message: unknown): unknown {
-  if (typeof message === "string") {
-    return JSON.parse(message);
-  }
-  return message;
-}
-
-/** Encode a JS object into the given wire format. */
-function encode(value: unknown, mode: WireMode): unknown {
-  return mode === "string" ? JSON.stringify(value) : value;
-}
-
-/** `chainHead_v1_unpin` takes its hash arg as a string or an array; normalize to an array. */
-function normalizeUnpinHashes(param: unknown): string[] {
-  if (typeof param === "string") {
-    return [param];
-  }
-  if (Array.isArray(param)) {
-    return param.filter((hash): hash is string => typeof hash === "string");
-  }
-  return [];
-}
-
-function cloneWithRewrittenFirstParam(
-  request: JsonRpcRequest,
-  rewrittenToken: string,
-): JsonRpcRequest {
-  const params: unknown[] = Array.isArray(request.params)
-    ? [...(request.params as unknown[])]
-    : [];
-  params[0] = rewrittenToken;
-  return { ...request, params };
-}
-
-export interface ChainBrokerManager {
-  connectRemote(
-    genesisHash: string,
-    connectionId: string,
-    onMessage: (message: string) => void,
-  ): StringJsonRpcConnection | null;
-  getLocalProvider(genesisHash: string): JsonRpcProvider | null;
-  disconnectAll(): void;
-}
-
 // Broker-backed object-wire provider for a chain, or throw. Object-wire (the
 // default) matches the polkadot-api getSmProvider boundary the resolver
 // expects. Used to route the resolver's Asset Hub reads through the broker's
@@ -224,16 +80,10 @@ class ChainBroker {
   private readonly provider: JsonRpcProvider;
   private readonly onEmpty: () => void;
   private upstream: JsonRpcConnection | null = null;
-  private readonly sessions = new Map<string, Session>();
+  private readonly sessions = new SessionRegistry();
+  private readonly tokens = new TokenRegistry();
+  private readonly follows = new FollowRegistry();
   private readonly pending = new Map<string, PendingRequest>();
-  private readonly localToOwned = new Map<string, OwnedToken>();
-  private readonly upstreamToOwned = new Map<string, OwnedToken>();
-  private readonly localFollowTokens = new Map<
-    string,
-    { sessionId: string; followKey: string }
-  >();
-  private readonly sharedFollows = new Map<string, SharedFollow>();
-  private readonly upstreamFollowTokens = new Map<string, SharedFollow>();
   private requestCounter = 0;
   private tokenCounter = 0;
 
@@ -244,7 +94,7 @@ class ChainBroker {
 
   /** Send a JSON-RPC object to a session in its configured wire format. */
   private sendToSession(session: Session, obj: unknown): void {
-    session.onMessage(encode(obj, session.wireMode));
+    this.sessions.send(session, obj);
   }
 
   private sendUpstream(obj: unknown): void {
@@ -264,7 +114,7 @@ class ChainBroker {
       `Session ${sessionId} connecting (${String(this.sessions.size)} existing sessions)`,
     );
     this.ensureUpstream();
-    this.sessions.set(sessionId, {
+    this.sessions.add({
       id: sessionId,
       onMessage,
       ownedTokens: new Set<string>(),
@@ -283,7 +133,7 @@ class ChainBroker {
   }
 
   disconnectAll(): void {
-    for (const sessionId of [...this.sessions.keys()]) {
+    for (const sessionId of this.sessions.ids()) {
       this.disconnectSession(sessionId);
     }
     this.disconnectUpstream();
@@ -295,7 +145,7 @@ class ChainBroker {
       return;
     }
     brokerLog(
-      `Connecting to upstream provider... (sessions: [${[...this.sessions.keys()].join(",")}])`,
+      `Connecting to upstream provider... (sessions: [${this.sessions.ids().join(",")}])`,
     );
     this.upstream = this.provider((message) => {
       this.handleUpstreamMessage(message);
@@ -415,7 +265,7 @@ class ChainBroker {
     const params = Array.isArray(request.params) ? request.params : [];
     const token = typeof params[0] === "string" ? params[0] : null;
     const followToken =
-      token !== null ? this.localFollowTokens.get(token) : undefined;
+      token !== null ? this.follows.getLocal(token) : undefined;
 
     // Non-follow tokens: fall back to the unchanged passthrough.
     if (
@@ -427,7 +277,7 @@ class ChainBroker {
       return;
     }
 
-    const sharedFollow = this.sharedFollows.get(followToken.followKey);
+    const sharedFollow = this.follows.getShared(followToken.followKey);
     if (
       sharedFollow?.upstreamToken === undefined ||
       sharedFollow.upstreamToken === null
@@ -439,7 +289,7 @@ class ChainBroker {
       return;
     }
 
-    const orphaned = this.releasePins(
+    const orphaned = this.follows.releasePins(
       sharedFollow,
       token,
       normalizeUnpinHashes(params[1]),
@@ -453,75 +303,6 @@ class ChainBroker {
     }
   }
 
-  /** Record that `localToken` holds a pin on `hash` for this shared follow. */
-  private registerPin(
-    sharedFollow: SharedFollow,
-    localToken: string,
-    hash: string,
-  ): void {
-    let holders = sharedFollow.pins.get(hash);
-    if (!holders) {
-      holders = new Set<string>();
-      sharedFollow.pins.set(hash, holders);
-    }
-    holders.add(localToken);
-  }
-
-  /** Pin the blocks a follow event implies: `initialized` finalized blocks and `newBlock`. */
-  private registerPinsFromEvent(
-    sharedFollow: SharedFollow,
-    localToken: string,
-    eventResult: unknown,
-  ): void {
-    if (!isJsonRpcObject(eventResult)) {
-      return;
-    }
-    if (eventResult.event === "initialized") {
-      const hashes = Array.isArray(eventResult.finalizedBlockHashes)
-        ? eventResult.finalizedBlockHashes
-        : [];
-      for (const hash of hashes) {
-        if (typeof hash === "string") {
-          this.registerPin(sharedFollow, localToken, hash);
-        }
-      }
-      return;
-    }
-    if (
-      eventResult.event === "newBlock" &&
-      typeof eventResult.blockHash === "string"
-    ) {
-      this.registerPin(sharedFollow, localToken, eventResult.blockHash);
-    }
-  }
-
-  /**
-   * Drop `localToken`'s hold on the given hashes (or all of them when null) and
-   * return the hashes no session holds anymore — the ones to unpin upstream.
-   */
-  private releasePins(
-    sharedFollow: SharedFollow,
-    localToken: string,
-    hashes: string[] | null,
-  ): string[] {
-    const orphaned: string[] = [];
-    const entries = hashes ?? [...sharedFollow.pins.keys()];
-    for (const hash of entries) {
-      const holders = sharedFollow.pins.get(hash);
-      if (!holders) {
-        continue;
-      }
-      if (!holders.delete(localToken)) {
-        continue;
-      }
-      if (holders.size === 0) {
-        sharedFollow.pins.delete(hash);
-        orphaned.push(hash);
-      }
-    }
-    return orphaned;
-  }
-
   private sendUpstreamUnpin(upstreamToken: string, hashes: string[]): void {
     this.sendUpstream({
       jsonrpc: "2.0",
@@ -545,12 +326,12 @@ class ChainBroker {
       return request;
     }
 
-    const followToken = this.localFollowTokens.get(firstParam);
+    const followToken = this.follows.getLocal(firstParam);
     if (followToken) {
       if (followToken.sessionId !== session.id) {
         return null;
       }
-      const sharedFollow = this.sharedFollows.get(followToken.followKey);
+      const sharedFollow = this.follows.getShared(followToken.followKey);
       if (
         sharedFollow?.upstreamToken === undefined ||
         sharedFollow.upstreamToken === null
@@ -560,7 +341,7 @@ class ChainBroker {
       return cloneWithRewrittenFirstParam(request, sharedFollow.upstreamToken);
     }
 
-    const owned = this.localToOwned.get(firstParam);
+    const owned = this.tokens.ownedByLocal(firstParam);
     if (!owned) {
       return request;
     }
@@ -569,7 +350,7 @@ class ChainBroker {
       return null;
     }
 
-    const upstreamToken = this.getUpstreamToken(firstParam);
+    const upstreamToken = this.tokens.upstreamForLocal(firstParam);
     if (upstreamToken === null) {
       return null;
     }
@@ -577,15 +358,6 @@ class ChainBroker {
     return cloneWithRewrittenFirstParam(request, upstreamToken);
   }
 
-  private getUpstreamToken(localToken: string): string | null {
-    for (const [upstreamToken, owned] of this.upstreamToOwned.entries()) {
-      if (owned.localToken === localToken) {
-        return upstreamToken;
-      }
-    }
-    return null;
-  }
-
   private handleUpstreamMessage(message: unknown): void {
     // `parseInbound` tolerates both objects (the provider's wire) and
     // strings (some test harnesses feed serialized JSON).
@@ -642,7 +414,7 @@ class ChainBroker {
         const rawSub = parsed.params?.subscription;
         const token = typeof rawSub === "string" ? rawSub : "?";
         // Find which session owns this token
-        const owned = this.upstreamToOwned.get(token);
+        const owned = this.tokens.ownedByUpstream(token);
         const sessionTag = owned ? owned.sessionId : "unknown";
         if (event === "newBlock") {
           brokerLog(
@@ -698,14 +470,14 @@ class ChainBroker {
       pending.method === "chainHead_v1_follow" &&
       typeof response.result === "string"
     ) {
-      const sharedFollow = this.sharedFollows.get(pending.sessionId);
+      const sharedFollow = this.follows.getShared(pending.sessionId);
       if (!sharedFollow) {
         brokerLog(`Missing shared follow state for key ${pending.sessionId}`);
         return;
       }
       sharedFollow.requestInFlight = false;
       sharedFollow.upstreamToken = response.result;
-      this.upstreamFollowTokens.set(response.result, sharedFollow);
+      this.follows.bindUpstream(response.result, sharedFollow);
       for (const pendingLocal of sharedFollow.pendingLocals.splice(0)) {
         const pendingSession = this.sessions.get(pendingLocal.sessionId);
         if (pendingSession?.connected !== true) {
@@ -722,7 +494,7 @@ class ChainBroker {
     const session = this.sessions.get(pending.sessionId);
     if (session?.connected !== true) {
       brokerLog(
-        `← upstream response for disconnected session: sessionId=${JSON.stringify(pending.sessionId)}, method=${pending.method}, responseId=${String(response.id)}, sessions=[${[...this.sessions.keys()].join(",")}]`,
+        `← upstream response for disconnected session: sessionId=${JSON.stringify(pending.sessionId)}, method=${pending.method}, responseId=${String(response.id)}, sessions=[${this.sessions.ids().join(",")}]`,
       );
       return;
     }
@@ -737,8 +509,7 @@ class ChainBroker {
         localToken,
         releaseMethod,
       };
-      this.localToOwned.set(localToken, owned);
-      this.upstreamToOwned.set(response.result, owned);
+      this.tokens.link(localToken, response.result, owned);
       session.ownedTokens.add(localToken);
       brokerLog(
         `Token mapped: ${localToken} ↔ ${response.result} (${pending.method})`,
@@ -766,11 +537,11 @@ class ChainBroker {
       return;
     }
 
-    const sharedFollow = this.upstreamFollowTokens.get(upstreamToken);
+    const sharedFollow = this.follows.getByUpstream(upstreamToken);
     if (sharedFollow) {
-      this.cacheSharedFollowEvent(sharedFollow, message.params?.result);
+      this.follows.cacheSharedFollowEvent(sharedFollow, message.params?.result);
       for (const localToken of sharedFollow.localTokens) {
-        const local = this.localFollowTokens.get(localToken);
+        const local = this.follows.getLocal(localToken);
         if (!local) {
           continue;
         }
@@ -779,7 +550,11 @@ class ChainBroker {
           continue;
         }
         const eventResult = message.params?.result;
-        this.registerPinsFromEvent(sharedFollow, localToken, eventResult);
+        this.follows.registerPinsFromEvent(
+          sharedFollow,
+          localToken,
+          eventResult,
+        );
         const eventType = isJsonRpcObject(eventResult)
           ? typeof eventResult.event === "string"
             ? eventResult.event
@@ -807,7 +582,7 @@ class ChainBroker {
         brokerLog(
           `Shared follow stopped by upstream; clearing for re-follow: key=${sharedFollow.key} token=${upstreamToken.slice(0, 12)}…`,
         );
-        this.upstreamFollowTokens.delete(upstreamToken);
+        this.follows.unbindUpstream(upstreamToken);
         sharedFollow.upstreamToken = null;
         sharedFollow.requestInFlight = false;
         sharedFollow.finalizedBlockHashes = [];
@@ -818,7 +593,7 @@ class ChainBroker {
       return;
     }
 
-    const owned = this.upstreamToOwned.get(upstreamToken);
+    const owned = this.tokens.ownedByUpstream(upstreamToken);
     if (!owned) {
       brokerLog(`← upstream subscription for unknown token: ${upstreamToken}`);
       return;
@@ -880,9 +655,7 @@ class ChainBroker {
       this.releaseOwnedToken(localToken, true);
     }
 
-    for (const [localToken, followToken] of [
-      ...this.localFollowTokens.entries(),
-    ]) {
+    for (const [localToken, followToken] of this.follows.localEntries()) {
       if (followToken.sessionId === sessionId) {
         this.releaseLocalFollowToken(localToken);
       }
@@ -890,28 +663,19 @@ class ChainBroker {
   }
 
   private releaseOwnedToken(localToken: string, notifyUpstream: boolean): void {
-    const owned = this.localToOwned.get(localToken);
+    const owned = this.tokens.ownedByLocal(localToken);
     if (!owned) {
       return;
     }
 
-    this.localToOwned.delete(localToken);
     const session = this.sessions.get(owned.sessionId);
     session?.ownedTokens.delete(localToken);
 
-    let upstreamTokenToDelete: string | null = null;
-    for (const [upstreamToken, candidate] of this.upstreamToOwned.entries()) {
-      if (candidate.localToken === localToken) {
-        upstreamTokenToDelete = upstreamToken;
-        break;
-      }
-    }
+    const upstreamTokenToDelete = this.tokens.unlinkByLocal(localToken);
     if (upstreamTokenToDelete === null) {
       return;
     }
 
-    this.upstreamToOwned.delete(upstreamTokenToDelete);
-
     if (!notifyUpstream) {
       return;
     }
@@ -927,11 +691,8 @@ class ChainBroker {
 
   private disconnectUpstream(): void {
     this.pending.clear();
-    this.localToOwned.clear();
-    this.upstreamToOwned.clear();
-    this.localFollowTokens.clear();
-    this.sharedFollows.clear();
-    this.upstreamFollowTokens.clear();
+    this.tokens.clear();
+    this.follows.clear();
     this.upstream?.disconnect();
     this.upstream = null;
   }
@@ -941,26 +702,11 @@ class ChainBroker {
     request: JsonRpcRequest,
   ): void {
     const followKey = JSON.stringify(request.params ?? []);
-    let sharedFollow = this.sharedFollows.get(followKey);
-    if (!sharedFollow) {
-      sharedFollow = {
-        key: followKey,
-        upstreamToken: null,
-        requestInFlight: false,
-        localTokens: new Set<string>(),
-        pendingLocals: [],
-        finalizedBlockHashes: [],
-        finalizedBlockRuntime: null,
-        bestBlockHash: null,
-        blocks: new Map<string, CachedBlock>(),
-        pins: new Map<string, Set<string>>(),
-      };
-      this.sharedFollows.set(followKey, sharedFollow);
-    }
+    const sharedFollow = this.follows.ensureShared(followKey);
 
     const localToken = `follow:${this.tokenCounter.toString(36)}:${session.id}`;
     this.tokenCounter += 1;
-    this.localFollowTokens.set(localToken, {
+    this.follows.setLocal(localToken, {
       sessionId: session.id,
       followKey,
     });
@@ -1015,7 +761,7 @@ class ChainBroker {
       return;
     }
 
-    const followToken = this.localFollowTokens.get(token);
+    const followToken = this.follows.getLocal(token);
     if (followToken) {
       if (followToken.sessionId !== session.id) {
         this.sendToSession(
@@ -1058,16 +804,16 @@ class ChainBroker {
   }
 
   private releaseLocalFollowToken(localToken: string): void {
-    const followToken = this.localFollowTokens.get(localToken);
+    const followToken = this.follows.getLocal(localToken);
     if (!followToken) {
       return;
     }
 
-    this.localFollowTokens.delete(localToken);
+    this.follows.deleteLocal(localToken);
     const session = this.sessions.get(followToken.sessionId);
     session?.ownedTokens.delete(localToken);
 
-    const sharedFollow = this.sharedFollows.get(followToken.followKey);
+    const sharedFollow = this.follows.getShared(followToken.followKey);
     if (!sharedFollow) {
       return;
     }
@@ -1082,7 +828,7 @@ class ChainBroker {
 
     // Drop this token's pins. If the follow stays alive, unpin orphaned blocks
     // upstream; if it's the last token, the unfollow below releases them all.
-    const orphaned = this.releasePins(sharedFollow, localToken, null);
+    const orphaned = this.follows.releasePins(sharedFollow, localToken, null);
     if (followStaysAlive) {
       if (orphaned.length > 0 && sharedFollow.upstreamToken !== null) {
         this.sendUpstreamUnpin(sharedFollow.upstreamToken, orphaned);
@@ -1091,7 +837,7 @@ class ChainBroker {
     }
 
     if (sharedFollow.upstreamToken !== null) {
-      this.upstreamFollowTokens.delete(sharedFollow.upstreamToken);
+      this.follows.unbindUpstream(sharedFollow.upstreamToken);
       this.sendUpstream({
         jsonrpc: "2.0",
         id: `broker-release:${this.requestCounter.toString(36)}`,
@@ -1101,75 +847,7 @@ class ChainBroker {
       this.requestCounter += 1;
     }
 
-    this.sharedFollows.delete(followToken.followKey);
-  }
-
-  private cacheSharedFollowEvent(
-    sharedFollow: SharedFollow,
-    eventResult: unknown,
-  ): void {
-    if (!isJsonRpcObject(eventResult)) {
-      return;
-    }
-
-    const eventType =
-      typeof eventResult.event === "string" ? eventResult.event : "";
-    if (eventType === "initialized") {
-      const hashes = Array.isArray(eventResult.finalizedBlockHashes)
-        ? eventResult.finalizedBlockHashes.filter(
-            (hash): hash is string => typeof hash === "string",
-          )
-        : [];
-      sharedFollow.finalizedBlockHashes = hashes;
-      sharedFollow.finalizedBlockRuntime =
-        eventResult.finalizedBlockRuntime ?? null;
-      sharedFollow.blocks.clear();
-      sharedFollow.bestBlockHash = null;
-      return;
-    }
-
-    if (eventType === "newBlock") {
-      const blockHash =
-        typeof eventResult.blockHash === "string"
-          ? eventResult.blockHash
-          : null;
-      if (blockHash === null) {
-        return;
-      }
-      sharedFollow.blocks.set(blockHash, {
-        result: { ...eventResult },
-        parentBlockHash:
-          typeof eventResult.parentBlockHash === "string"
-            ? eventResult.parentBlockHash
-            : null,
-      });
-      return;
-    }
-
-    if (eventType === "bestBlockChanged") {
-      sharedFollow.bestBlockHash =
-        typeof eventResult.bestBlockHash === "string"
-          ? eventResult.bestBlockHash
-          : null;
-      return;
-    }
-
-    if (eventType === "finalized") {
-      const hashes = Array.isArray(eventResult.finalizedBlockHashes)
-        ? eventResult.finalizedBlockHashes.filter(
-            (hash): hash is string => typeof hash === "string",
-          )
-        : [];
-      sharedFollow.finalizedBlockHashes = hashes;
-      const pruned = Array.isArray(eventResult.prunedBlockHashes)
-        ? eventResult.prunedBlockHashes.filter(
-            (hash): hash is string => typeof hash === "string",
-          )
-        : [];
-      for (const hash of pruned) {
-        sharedFollow.blocks.delete(hash);
-      }
-    }
+    this.follows.deleteShared(followToken.followKey);
   }
 
   private replayFollowSnapshot(
@@ -1179,7 +857,7 @@ class ChainBroker {
   ): void {
     if (sharedFollow.finalizedBlockHashes.length > 0) {
       for (const hash of sharedFollow.finalizedBlockHashes) {
-        this.registerPin(sharedFollow, localToken, hash);
+        this.follows.registerPin(sharedFollow, localToken, hash);
       }
       this.sendToSession(session, {
         jsonrpc: "2.0",
@@ -1216,7 +894,7 @@ class ChainBroker {
 
     replayBlocks.reverse();
     for (const result of replayBlocks) {
-      this.registerPinsFromEvent(sharedFollow, localToken, result);
+      this.follows.registerPinsFromEvent(sharedFollow, localToken, result);
       this.sendToSession(session, {
         jsonrpc: "2.0",
         method: "chainHead_v1_followEvent",
diff --git a/packages/protocol/tests/broker-jsonrpc.test.ts b/packages/protocol/tests/broker-jsonrpc.test.ts
new file mode 100644
index 00000000..2568e121
--- /dev/null
+++ b/packages/protocol/tests/broker-jsonrpc.test.ts
@@ -0,0 +1,178 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { describe, expect, it } from "vitest";
+import {
+  buildJsonRpcError,
+  buildJsonRpcResult,
+  cloneWithRewrittenFirstParam,
+  encode,
+  isJsonRpcObject,
+  isRequestMessage,
+  isResponseMessage,
+  isSubscriptionMessage,
+  normalizeUnpinHashes,
+  parseInbound,
+} from "@dotli/protocol/broker-jsonrpc";
+
+describe("isJsonRpcObject", () => {
+  it("accepts plain objects", () => {
+    expect(isJsonRpcObject({})).toBe(true);
+    expect(isJsonRpcObject({ jsonrpc: "2.0" })).toBe(true);
+  });
+
+  it("rejects null, arrays, and primitives", () => {
+    expect(isJsonRpcObject(null)).toBe(false);
+    expect(isJsonRpcObject([])).toBe(false);
+    expect(isJsonRpcObject([1, 2])).toBe(false);
+    expect(isJsonRpcObject("x")).toBe(false);
+    expect(isJsonRpcObject(42)).toBe(false);
+    expect(isJsonRpcObject(undefined)).toBe(false);
+  });
+});
+
+describe("buildJsonRpcError / buildJsonRpcResult", () => {
+  it("builds an internal-error envelope preserving the id", () => {
+    expect(buildJsonRpcError(7, "boom")).toEqual({
+      jsonrpc: "2.0",
+      id: 7,
+      error: { code: -32603, message: "boom" },
+    });
+  });
+
+  it("preserves a null id on errors", () => {
+    expect(buildJsonRpcError(null, "bad")).toEqual({
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32603, message: "bad" },
+    });
+  });
+
+  it("builds a result envelope preserving the id and result", () => {
+    expect(buildJsonRpcResult("abc", { ok: true })).toEqual({
+      jsonrpc: "2.0",
+      id: "abc",
+      result: { ok: true },
+    });
+  });
+
+  it("carries a null result through", () => {
+    expect(buildJsonRpcResult(1, null)).toEqual({
+      jsonrpc: "2.0",
+      id: 1,
+      result: null,
+    });
+  });
+});
+
+describe("message classifiers", () => {
+  it("isRequestMessage requires a string method", () => {
+    expect(isRequestMessage({ method: "chainHead_v1_follow" })).toBe(true);
+    expect(isRequestMessage({ method: 5 })).toBe(false);
+    expect(isRequestMessage({ id: 1 })).toBe(false);
+    expect(isRequestMessage([])).toBe(false);
+  });
+
+  it("isResponseMessage requires an id and no method", () => {
+    expect(isResponseMessage({ id: 1, result: "x" })).toBe(true);
+    expect(isResponseMessage({ id: null, error: {} })).toBe(true);
+    expect(isResponseMessage({ id: 1, method: "foo" })).toBe(false);
+    expect(isResponseMessage({ result: "x" })).toBe(false);
+  });
+
+  it("isSubscriptionMessage requires params.subscription", () => {
+    expect(
+      isSubscriptionMessage({
+        method: "chainHead_v1_followEvent",
+        params: { subscription: "tok", result: {} },
+      }),
+    ).toBe(true);
+    expect(isSubscriptionMessage({ method: "x", params: { result: {} } })).toBe(
+      false,
+    );
+    expect(isSubscriptionMessage({ method: "x" })).toBe(false);
+    expect(isSubscriptionMessage({ params: { subscription: "t" } })).toBe(
+      false,
+    );
+  });
+});
+
+describe("parseInbound", () => {
+  it("parses JSON strings into objects", () => {
+    expect(parseInbound('{"a":1}')).toEqual({ a: 1 });
+  });
+
+  it("returns non-string values untouched", () => {
+    const obj = { a: 1 };
+    expect(parseInbound(obj)).toBe(obj);
+  });
+
+  it("throws on malformed JSON strings", () => {
+    expect(() => parseInbound("{not json")).toThrow();
+  });
+});
+
+describe("encode", () => {
+  it("stringifies in string wire mode", () => {
+    expect(encode({ a: 1 }, "string")).toBe('{"a":1}');
+  });
+
+  it("passes objects through in object wire mode", () => {
+    const obj = { a: 1 };
+    expect(encode(obj, "object")).toBe(obj);
+  });
+});
+
+describe("normalizeUnpinHashes", () => {
+  it("wraps a single string hash into an array", () => {
+    expect(normalizeUnpinHashes("0xabc")).toEqual(["0xabc"]);
+  });
+
+  it("keeps only string members of an array", () => {
+    expect(normalizeUnpinHashes(["0x1", 2, null, "0x2"])).toEqual([
+      "0x1",
+      "0x2",
+    ]);
+  });
+
+  it("returns an empty array for unsupported shapes", () => {
+    expect(normalizeUnpinHashes(undefined)).toEqual([]);
+    expect(normalizeUnpinHashes(42)).toEqual([]);
+    expect(normalizeUnpinHashes({})).toEqual([]);
+  });
+});
+
+describe("cloneWithRewrittenFirstParam", () => {
+  it("replaces the first param with the rewritten token", () => {
+    const request = {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "chainHead_v1_unpin",
+      params: ["localToken", ["0xabc"]],
+    };
+    const cloned = cloneWithRewrittenFirstParam(request, "upstreamToken");
+    expect(cloned.params).toEqual(["upstreamToken", ["0xabc"]]);
+    // other fields preserved
+    expect(cloned.method).toBe("chainHead_v1_unpin");
+    expect(cloned.id).toBe(1);
+  });
+
+  it("does not mutate the original request's params", () => {
+    const request = { method: "m", params: ["original"] };
+    cloneWithRewrittenFirstParam(request, "rewritten");
+    expect(request.params).toEqual(["original"]);
+  });
+
+  it("creates a single-element params array when params is absent", () => {
+    const cloned = cloneWithRewrittenFirstParam({ method: "m" }, "tok");
+    expect(cloned.params).toEqual(["tok"]);
+  });
+
+  it("creates a single-element params array when params is not an array", () => {
+    const cloned = cloneWithRewrittenFirstParam(
+      { method: "m", params: "scalar" },
+      "tok",
+    );
+    expect(cloned.params).toEqual(["tok"]);
+  });
+});
diff --git a/packages/protocol/tests/broker-registries.test.ts b/packages/protocol/tests/broker-registries.test.ts
new file mode 100644
index 00000000..575e621e
--- /dev/null
+++ b/packages/protocol/tests/broker-registries.test.ts
@@ -0,0 +1,201 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { describe, expect, it, vi } from "vitest";
+import { SessionRegistry } from "@dotli/protocol/broker-session-registry";
+import { TokenRegistry } from "@dotli/protocol/broker-token-registry";
+import { FollowRegistry } from "@dotli/protocol/broker-follow-registry";
+import type { OwnedToken, Session } from "@dotli/protocol/broker-types";
+
+function makeSession(id: string, wireMode: "string" | "object"): Session {
+  return {
+    id,
+    onMessage: vi.fn(),
+    ownedTokens: new Set<string>(),
+    connected: true,
+    wireMode,
+  };
+}
+
+describe("SessionRegistry", () => {
+  it("adds, gets, and deletes sessions keyed by id", () => {
+    const reg = new SessionRegistry();
+    const a = makeSession("a", "object");
+    reg.add(a);
+    expect(reg.has("a")).toBe(true);
+    expect(reg.get("a")).toBe(a);
+    expect(reg.size).toBe(1);
+    expect(reg.ids()).toEqual(["a"]);
+    reg.delete("a");
+    expect(reg.has("a")).toBe(false);
+    expect(reg.size).toBe(0);
+  });
+
+  it("encodes to a string for string-wire sessions", () => {
+    const reg = new SessionRegistry();
+    const s = makeSession("s", "string");
+    reg.send(s, { hello: 1 });
+    expect(s.onMessage).toHaveBeenCalledWith('{"hello":1}');
+  });
+
+  it("passes the object through for object-wire sessions", () => {
+    const reg = new SessionRegistry();
+    const s = makeSession("s", "object");
+    const obj = { hello: 1 };
+    reg.send(s, obj);
+    expect(s.onMessage).toHaveBeenCalledWith(obj);
+  });
+});
+
+describe("TokenRegistry", () => {
+  const owned = (sessionId: string, localToken: string): OwnedToken => ({
+    sessionId,
+    localToken,
+    releaseMethod: "transaction_v1_stop",
+  });
+
+  it("links a local token to an upstream token both ways", () => {
+    const reg = new TokenRegistry();
+    const o = owned("sess", "local:1");
+    reg.link("local:1", "up:1", o);
+    expect(reg.ownedByLocal("local:1")).toBe(o);
+    expect(reg.ownedByUpstream("up:1")).toBe(o);
+    expect(reg.upstreamForLocal("local:1")).toBe("up:1");
+  });
+
+  it("returns null from upstreamForLocal for an unknown local token", () => {
+    const reg = new TokenRegistry();
+    expect(reg.upstreamForLocal("nope")).toBeNull();
+  });
+
+  it("unlinkByLocal removes both sides and returns the upstream token", () => {
+    const reg = new TokenRegistry();
+    reg.link("local:1", "up:1", owned("sess", "local:1"));
+    expect(reg.unlinkByLocal("local:1")).toBe("up:1");
+    expect(reg.ownedByLocal("local:1")).toBeUndefined();
+    expect(reg.ownedByUpstream("up:1")).toBeUndefined();
+  });
+
+  it("unlinkByLocal returns null for an unknown token", () => {
+    const reg = new TokenRegistry();
+    expect(reg.unlinkByLocal("ghost")).toBeNull();
+  });
+
+  it("clear empties both maps", () => {
+    const reg = new TokenRegistry();
+    reg.link("local:1", "up:1", owned("sess", "local:1"));
+    reg.clear();
+    expect(reg.ownedByLocal("local:1")).toBeUndefined();
+    expect(reg.ownedByUpstream("up:1")).toBeUndefined();
+  });
+});
+
+describe("FollowRegistry pins", () => {
+  it("ensureShared is idempotent for the same key", () => {
+    const reg = new FollowRegistry();
+    const a = reg.ensureShared("k");
+    const b = reg.ensureShared("k");
+    expect(a).toBe(b);
+    expect(reg.getShared("k")).toBe(a);
+  });
+
+  it("ref-counts pins: a block is orphaned only when its last holder releases", () => {
+    const reg = new FollowRegistry();
+    const follow = reg.ensureShared("k");
+    reg.registerPin(follow, "tokenA", "0xblock");
+    reg.registerPin(follow, "tokenB", "0xblock");
+
+    // A releases — block still held by B, so nothing is orphaned.
+    expect(reg.releasePins(follow, "tokenA", ["0xblock"])).toEqual([]);
+    // B releases — now nobody holds it, so it's orphaned for upstream unpin.
+    expect(reg.releasePins(follow, "tokenB", ["0xblock"])).toEqual(["0xblock"]);
+  });
+
+  it("releasePins with null releases every block this token holds", () => {
+    const reg = new FollowRegistry();
+    const follow = reg.ensureShared("k");
+    reg.registerPin(follow, "tokenA", "0x1");
+    reg.registerPin(follow, "tokenA", "0x2");
+    expect(reg.releasePins(follow, "tokenA", null).sort()).toEqual([
+      "0x1",
+      "0x2",
+    ]);
+  });
+
+  it("registerPinsFromEvent pins initialized finalized blocks", () => {
+    const reg = new FollowRegistry();
+    const follow = reg.ensureShared("k");
+    reg.registerPinsFromEvent(follow, "tokenA", {
+      event: "initialized",
+      finalizedBlockHashes: ["0xa", "0xb"],
+    });
+    // Both should now be pinned by tokenA; releasing returns them as orphaned.
+    expect(reg.releasePins(follow, "tokenA", null).sort()).toEqual([
+      "0xa",
+      "0xb",
+    ]);
+  });
+
+  it("registerPinsFromEvent pins a newBlock hash", () => {
+    const reg = new FollowRegistry();
+    const follow = reg.ensureShared("k");
+    reg.registerPinsFromEvent(follow, "tokenA", {
+      event: "newBlock",
+      blockHash: "0xnew",
+    });
+    expect(reg.releasePins(follow, "tokenA", null)).toEqual(["0xnew"]);
+  });
+});
+
+describe("FollowRegistry cache", () => {
+  it("initialized resets the snapshot and clears blocks", () => {
+    const reg = new FollowRegistry();
+    const follow = reg.ensureShared("k");
+    follow.blocks.set("stale", { result: {}, parentBlockHash: null });
+    reg.cacheSharedFollowEvent(follow, {
+      event: "initialized",
+      finalizedBlockHashes: ["0xfin"],
+      finalizedBlockRuntime: { spec: 1 },
+    });
+    expect(follow.finalizedBlockHashes).toEqual(["0xfin"]);
+    expect(follow.finalizedBlockRuntime).toEqual({ spec: 1 });
+    expect(follow.blocks.size).toBe(0);
+    expect(follow.bestBlockHash).toBeNull();
+  });
+
+  it("newBlock caches the block with its parent", () => {
+    const reg = new FollowRegistry();
+    const follow = reg.ensureShared("k");
+    reg.cacheSharedFollowEvent(follow, {
+      event: "newBlock",
+      blockHash: "0xchild",
+      parentBlockHash: "0xparent",
+    });
+    expect(follow.blocks.get("0xchild")?.parentBlockHash).toBe("0xparent");
+  });
+
+  it("finalized prunes pruned blocks from the cache", () => {
+    const reg = new FollowRegistry();
+    const follow = reg.ensureShared("k");
+    follow.blocks.set("0xgone", { result: {}, parentBlockHash: null });
+    follow.blocks.set("0xkeep", { result: {}, parentBlockHash: null });
+    reg.cacheSharedFollowEvent(follow, {
+      event: "finalized",
+      finalizedBlockHashes: ["0xkeep"],
+      prunedBlockHashes: ["0xgone"],
+    });
+    expect(follow.blocks.has("0xgone")).toBe(false);
+    expect(follow.blocks.has("0xkeep")).toBe(true);
+    expect(follow.finalizedBlockHashes).toEqual(["0xkeep"]);
+  });
+
+  it("bestBlockChanged updates the best block hash", () => {
+    const reg = new FollowRegistry();
+    const follow = reg.ensureShared("k");
+    reg.cacheSharedFollowEvent(follow, {
+      event: "bestBlockChanged",
+      bestBlockHash: "0xbest",
+    });
+    expect(follow.bestBlockHash).toBe("0xbest");
+  });
+});
diff --git a/packages/ui/src/container-product.ts b/packages/ui/src/container-product.ts
new file mode 100644
index 00000000..c26e828d
--- /dev/null
+++ b/packages/ui/src/container-product.ts
@@ -0,0 +1,95 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Pure helpers for the host container bridge: deriving product identifiers
+// and labels, building product URLs, and value checks. No DOM refs and no
+// bridge state, so they can be unit-tested in isolation; `container.ts`
+// imports them.
+
+import { isLocalhost, BASE_DOMAIN } from "@dotli/config/config";
+import { normalizeProductAccountId } from "@dotli/auth/account";
+import { dotNsUrl } from "@dotli/shared/dotns-url";
+
+// localhost proxy and webcontainer previews are developer affordances for
+// running a `.dot` app before it's deployed.
+export function isDevPreviewLabel(label: string): boolean {
+  return (
+    label.startsWith("localhost:") || dotNsUrl.isWebcontainerPreviewHost(label)
+  );
+}
+
+/**
+ * Derive the product-id from an iframe label.
+ *
+ * Dev previews (localhost proxy, webcontainer) keep the bare host label. dotNs
+ * products get the `.dot` suffix appended. Same rule encoded in
+ * `isProductAccountValid`.
+ */
+export function labelToProductIdentifier(label: string): string {
+  return isDevPreviewLabel(label) ? label : `${label}.dot`;
+}
+
+export function labelAcceptsIdentifier(label: string, id: string): boolean {
+  return (
+    dotNsUrl.isProductIdentifier(id) || id === labelToProductIdentifier(label)
+  );
+}
+
+// Dev previews are permissive. A deployed `.dot` must sign as its own identifier.
+export function isProductAccountValid(
+  label: string,
+  accountId: string,
+): boolean {
+  if (isDevPreviewLabel(label)) {
+    return labelAcceptsIdentifier(label, accountId);
+  }
+  return accountId === labelToProductIdentifier(label);
+}
+
+/**
+ * Resolve the product-account tuple a product is allowed to act as.
+ */
+export function resolveProductAccountId(
+  label: string,
+  reported: Parameters<typeof normalizeProductAccountId>[0],
+): ReturnType<typeof normalizeProductAccountId> {
+  const normalized = normalizeProductAccountId(reported);
+  return isDevPreviewLabel(label)
+    ? normalized
+    : [labelToProductIdentifier(label), normalized[1]];
+}
+
+export function identifierToLabel(identifier: string): string {
+  return identifier.slice(0, -".dot".length);
+}
+
+/** Build a full URL for a .dot product on the current environment. */
+export function buildDotTargetUrl(label: string, pathname: string): string {
+  const suffix = pathname ? "/" + pathname : "";
+  if (isLocalhost) {
+    return `http://${label}.localhost:${window.location.port}${suffix}`;
+  }
+  return `${window.location.protocol}//${label}.${BASE_DOMAIN}${suffix}`;
+}
+
+/** Bare host origin without any product subdomain (e.g. `http://localhost:5173` or `https://dot.li`). */
+export function getHostOrigin(): string {
+  if (isLocalhost) {
+    return `http://localhost:${window.location.port}`;
+  }
+  return `${window.location.protocol}//${BASE_DOMAIN}`;
+}
+
+/** Check if a value is a Uint8Array (or cross-realm equivalent). */
+export function isUint8ArrayLike(data: unknown): data is Uint8Array {
+  if (data instanceof Uint8Array) {
+    return true;
+  }
+  if (typeof data !== "object" || data === null) {
+    return false;
+  }
+  return (
+    (data as { constructor: { name: string } }).constructor.name ===
+    "Uint8Array"
+  );
+}
diff --git a/packages/ui/src/container.ts b/packages/ui/src/container.ts
index 4dc13233..0144eb98 100644
--- a/packages/ui/src/container.ts
+++ b/packages/ui/src/container.ts
@@ -45,7 +45,7 @@ import {
 } from "@novasamatech/statement-store";
 import { errAsync, fromPromise, okAsync, type ResultAsync } from "neverthrow";
 import { emitDotliDebugEvent } from "@dotli/truapi-debug/dotli-debug-bus";
-import { isLocalhost, BASE_DOMAIN } from "@dotli/config/config";
+import { BASE_DOMAIN } from "@dotli/config/config";
 import {
   getPermissionStatus,
   isEnforceableDevicePermission,
@@ -88,6 +88,16 @@ import {
 } from "@dotli/protocol/client";
 import { MAX_NESTED_BRIDGES } from "@dotli/config/config";
 import { dotNsUrl } from "@dotli/shared/dotns-url";
+import {
+  buildDotTargetUrl,
+  getHostOrigin,
+  identifierToLabel,
+  isProductAccountValid,
+  isUint8ArrayLike,
+  labelAcceptsIdentifier,
+  labelToProductIdentifier,
+  resolveProductAccountId,
+} from "./container-product";
 import { log } from "@dotli/shared/log";
 import { getBackend } from "@dotli/config/mode";
 import { computePreimageKey, hashToCid } from "@dotli/content/preimage";
@@ -121,52 +131,6 @@ function subscribeSession(
   });
 }
 
-// localhost proxy and webcontainer previews are developer affordances for
-// running a `.dot` app before it's deployed.
-function isDevPreviewLabel(label: string): boolean {
-  return (
-    label.startsWith("localhost:") || dotNsUrl.isWebcontainerPreviewHost(label)
-  );
-}
-
-/**
- * Derive the product-id from an iframe label.
- *
- * Dev previews (localhost proxy, webcontainer) keep the bare host label. dotNs
- * products get the `.dot` suffix appended. Same rule encoded in
- * `isProductAccountValid`.
- */
-function labelToProductIdentifier(label: string): string {
-  return isDevPreviewLabel(label) ? label : `${label}.dot`;
-}
-
-function labelAcceptsIdentifier(label: string, id: string): boolean {
-  return (
-    dotNsUrl.isProductIdentifier(id) || id === labelToProductIdentifier(label)
-  );
-}
-
-// Dev previews are permissive. A deployed `.dot` must sign as its own identifier.
-function isProductAccountValid(label: string, accountId: string): boolean {
-  if (isDevPreviewLabel(label)) {
-    return labelAcceptsIdentifier(label, accountId);
-  }
-  return accountId === labelToProductIdentifier(label);
-}
-
-/**
- * Resolve the product-account tuple a product is allowed to act as.
- */
-function resolveProductAccountId(
-  label: string,
-  reported: Parameters<typeof normalizeProductAccountId>[0],
-): ReturnType<typeof normalizeProductAccountId> {
-  const normalized = normalizeProductAccountId(reported);
-  return isDevPreviewLabel(label)
-    ? normalized
-    : [labelToProductIdentifier(label), normalized[1]];
-}
-
 function wireContainerHandlers(
   container: Container,
   label: string,
@@ -1308,41 +1272,6 @@ function promptCachedSubmitPermission(
 }
 
 /** Strip the `.dot` suffix to get the bare label (e.g. "mytestapp.dot" becomes "mytestapp"). */
-function identifierToLabel(identifier: string): string {
-  return identifier.slice(0, -".dot".length);
-}
-
-/** Build a full URL for a .dot product on the current environment. */
-function buildDotTargetUrl(label: string, pathname: string): string {
-  const suffix = pathname ? "/" + pathname : "";
-  if (isLocalhost) {
-    return `http://${label}.localhost:${window.location.port}${suffix}`;
-  }
-  return `${window.location.protocol}//${label}.${BASE_DOMAIN}${suffix}`;
-}
-
-/** Bare host origin without any product subdomain (e.g. `http://localhost:5173` or `https://dot.li`). */
-function getHostOrigin(): string {
-  if (isLocalhost) {
-    return `http://localhost:${window.location.port}`;
-  }
-  return `${window.location.protocol}//${BASE_DOMAIN}`;
-}
-
-/** Check if a value is a Uint8Array (or cross-realm equivalent). */
-function isUint8ArrayLike(data: unknown): data is Uint8Array {
-  if (data instanceof Uint8Array) {
-    return true;
-  }
-  if (typeof data !== "object" || data === null) {
-    return false;
-  }
-  return (
-    (data as { constructor: { name: string } }).constructor.name ===
-    "Uint8Array"
-  );
-}
-
 // Implements the same Provider interface as createIframeProvider
 // but targets a captured Window reference (from event.source)
 // instead of an HTMLIFrameElement.
diff --git a/packages/ui/src/event-manager.ts b/packages/ui/src/event-manager.ts
new file mode 100644
index 00000000..53a5e724
--- /dev/null
+++ b/packages/ui/src/event-manager.ts
@@ -0,0 +1,69 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// A tiny listener bookkeeper. The topbar wires many `addEventListener` calls
+// on long-lived targets (window, document) inside short-lived scopes (an open
+// dropdown, a mounted panel). Registering them here means a single
+// `disposeAll()` tears every one back down, instead of hand-matching each
+// `removeEventListener` (the pattern that previously leaked when a scope was
+// re-entered before its ad-hoc cleanup ran).
+
+type Disposer = () => void;
+
+export class EventManager {
+  private disposers: Disposer[] = [];
+
+  /**
+   * Register an event listener and remember how to remove it. The same
+   * `options` value is threaded to both add and remove so capture/passive
+   * listeners are matched correctly.
+   */
+  on<K extends keyof DocumentEventMap>(
+    target: Document,
+    type: K,
+    listener: (event: DocumentEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): Disposer;
+  on<K extends keyof WindowEventMap>(
+    target: Window,
+    type: K,
+    listener: (event: WindowEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): Disposer;
+  on<K extends keyof HTMLElementEventMap>(
+    target: HTMLElement,
+    type: K,
+    listener: (event: HTMLElementEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): Disposer;
+  on(
+    target: EventTarget,
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): Disposer {
+    target.addEventListener(type, listener, options);
+    const dispose = (): void => {
+      target.removeEventListener(type, listener, options);
+    };
+    this.disposers.push(dispose);
+    return dispose;
+  }
+
+  /** Register an arbitrary teardown callback (timers, subscriptions, …). */
+  add(disposer: Disposer): void {
+    this.disposers.push(disposer);
+  }
+
+  /** Run and forget every registered disposer. Safe to call repeatedly. */
+  disposeAll(): void {
+    for (const dispose of this.disposers.splice(0)) {
+      dispose();
+    }
+  }
+
+  /** How many disposers are currently registered (useful in tests). */
+  get size(): number {
+    return this.disposers.length;
+  }
+}
diff --git a/packages/ui/src/topbar-diagnostics.ts b/packages/ui/src/topbar-diagnostics.ts
new file mode 100644
index 00000000..d5e3ed4f
--- /dev/null
+++ b/packages/ui/src/topbar-diagnostics.ts
@@ -0,0 +1,486 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// The Diagnostics panel of the top bar's settings popover: the live rows, the
+// per-chain finalized-block lookups, and the "Share diagnostic" report. Split
+// out of topbar.ts so the panel is a self-contained unit. It reads the active
+// product label as a parameter rather than topbar module state.
+
+import {
+  getActiveServicesConfig,
+  getNetwork,
+  NETWORK_NAME_TO_SERVICES_CONFIG,
+} from "@dotli/config/network";
+import { getBackend, getCacheSettings } from "@dotli/config/mode";
+import {
+  formatAppVersion,
+  getActiveAppManifest,
+  getActiveRootManifest,
+} from "@dotli/shared/active-manifest";
+import {
+  createRemoteChainProvider,
+  isRemoteChainSupported,
+} from "@dotli/protocol/client";
+import { ALL_PERMISSIONS, getPermissionStatus } from "./permissions";
+import { appendSectionHeader } from "./topbar-dom";
+import {
+  backendLabel,
+  formatBlock,
+  isTruapiDebugEnabled,
+  shortSha,
+  summarizeUserAgent,
+} from "./topbar-format";
+
+// Baked at build time by `apps/host/vite.config.ts` (`define.*`). The
+// topbar only ever renders in the host shell so these will always be
+// present in practice. `undefined` fallbacks are defensive for tests and
+// for any future caller that imports this module from a different bundle.
+declare const __DOTLI_VERSION__: string | undefined;
+declare const __SMOLDOT_VERSION__: string | undefined;
+declare const __SMOLDOT_COMMIT__: string | undefined;
+declare const __POLKADOT_API_VERSION__: string | undefined;
+declare const __POLKADOT_API_VERSIONS__:
+  | { name: string; version: string }[]
+  | undefined;
+declare const __NOVASAMATECH_VERSIONS__:
+  | { name: string; version: string }[]
+  | undefined;
+
+/**
+ * Render the Diagnostics block at the bottom of the settings popover. Rows
+ * are static (no click-to-copy). The "Share diagnostic" button at the end
+ * exports the whole block at once, so individual-row copy would be noise.
+ *
+ * Values come from places that are cheap to read synchronously so the
+ * popover doesn't pop open with a spinner. "unknown" is a valid value, so
+ * don't over-engineer fallbacks.
+ *
+ * `productLabel` is the active product's label (or null on landing), used to
+ * scope the permission rows in the shared report.
+ */
+export function renderDiagnostics(
+  parent: HTMLElement,
+  productLabel: string | null,
+): void {
+  const base = buildBaseDiagnosticsRows();
+  const rowHandles = new Map<string, InfoRowHandle>();
+  const COPYABLE_ROWS = new Set([
+    "Site",
+    "Relay node",
+    "AssetHub node",
+    "Bulletin Node",
+  ]);
+  for (const entry of base) {
+    rowHandles.set(
+      entry[0],
+      renderInfoRow(parent, entry[0], entry[1], {
+        copyable: COPYABLE_ROWS.has(entry[0]),
+      }),
+    );
+  }
+
+  // When running in RPC chain mode, ask the live ws-provider which URI
+  // it actually connected to. polkadot-api rotates across the curated
+  // candidate list on failure, so the first entry of the config array
+  // may not be the node currently answering. Lazy-imported so the
+  // resolver bundle (polkadot-api and ws-provider) isn't pulled into the
+  // popover's own chunk. By the time the popover opens under RPC mode,
+  // `@dotli/resolver/rpc-resolve` is already warm because host main
+  // imported it to resolve the name. Both the DOM row and the base
+  // snapshot are updated so the Share-diagnostic export stays honest.
+  if (getBackend() === "rpc-gateway") {
+    void import("@dotli/resolver/rpc-resolve").then(
+      ({ getConnectedAssetHubRpcEndpoint }) => {
+        const live = getConnectedAssetHubRpcEndpoint();
+        if (live === null) {
+          return;
+        }
+        rowHandles.get("AssetHub node")?.update(live);
+        const row = base.find((r) => r[0] === "AssetHub node");
+        if (row !== undefined) {
+          row[1] = live;
+        }
+      },
+    );
+  }
+
+  // Version is static and cheap. Block numbers are async so the rows start
+  // with an ellipsis placeholder and get swapped in when `chainConnect`
+  // rounds-trip back with a finalized-block header. When the user is on
+  // the RPC chain backend, smoldot isn't running, so hide the per-chain
+  // block rows entirely (the endpoints already appear under Chain) and
+  // keep only the smoldot version so the dependency is still visible.
+  const smoldotInfo: SmoldotInfo = {
+    version: buildSmoldotVersionLabel(),
+    blocks: { relay: "…", assetHub: "…", people: "…" },
+  };
+  const smoldotActive = getBackend() !== "rpc-gateway";
+  appendSectionHeader(parent, "@smoldot");
+  renderInfoRow(parent, "smoldot", smoldotInfo.version);
+  if (smoldotActive) {
+    const relayRow = renderInfoRow(parent, "Relay Chain", "…");
+    const assetHubRow = renderInfoRow(parent, "Asset Hub", "…");
+    const peopleRow = renderInfoRow(parent, "People Chain", "…");
+
+    // Fire all queries. They update their own rows and the shared snapshot
+    // (so the "Share diagnostic" button captures whatever resolved in time).
+    const cfg = getActiveServicesConfig();
+    void queryFinalizedBlock(cfg.relay.genesis).then((n) => {
+      const v = formatBlock(n);
+      relayRow.update(v);
+      smoldotInfo.blocks.relay = v;
+    });
+    void queryFinalizedBlock(cfg.assethub.genesis).then((n) => {
+      const v = formatBlock(n);
+      assetHubRow.update(v);
+      smoldotInfo.blocks.assetHub = v;
+    });
+    void queryFinalizedBlock(cfg.people.genesis).then((n) => {
+      const v = formatBlock(n);
+      peopleRow.update(v);
+      smoldotInfo.blocks.people = v;
+    });
+  } else {
+    // Keep the snapshot tagged as n/a so the Share-diagnostic report is
+    // coherent: smoldot wasn't consulted, don't claim a block height.
+    smoldotInfo.blocks.relay = "n/a";
+    smoldotInfo.blocks.assetHub = "n/a";
+    smoldotInfo.blocks.people = "n/a";
+  }
+
+  // The unscoped `polkadot-api` package lives in the same visual section as
+  // `@polkadot-api/*`. Same ecosystem, same release cadence, users expect
+  // to see it with its siblings rather than at the top of the popover.
+  const polkadotApi: { name: string; version: string }[] = [];
+  if (typeof __POLKADOT_API_VERSION__ === "string") {
+    polkadotApi.push({
+      name: "polkadot-api",
+      version: __POLKADOT_API_VERSION__,
+    });
+  }
+  if (typeof __POLKADOT_API_VERSIONS__ !== "undefined") {
+    polkadotApi.push(...__POLKADOT_API_VERSIONS__);
+  }
+
+  // @novasamatech/* versions move in lockstep, so showing every single
+  // package is noise. Keep only the two that are independently meaningful:
+  // host-api (the host runtime) and sdk-statement (the statement store
+  // client). Everything else in the scope tracks host-api's version.
+  const NOVASAMATECH_ALLOWLIST = new Set([
+    "@novasamatech/host-api",
+    "@novasamatech/sdk-statement",
+  ]);
+  const novasamatech = (
+    typeof __NOVASAMATECH_VERSIONS__ === "undefined"
+      ? []
+      : __NOVASAMATECH_VERSIONS__
+  ).filter((p) => NOVASAMATECH_ALLOWLIST.has(p.name));
+
+  if (polkadotApi.length > 0) {
+    appendSectionHeader(parent, "@polkadot-api");
+    for (const pkg of polkadotApi) {
+      renderInfoRow(parent, pkg.name, pkg.version);
+    }
+  }
+  if (novasamatech.length > 0) {
+    appendSectionHeader(parent, "@triangle-sdk");
+    for (const pkg of novasamatech) {
+      renderInfoRow(parent, pkg.name, pkg.version);
+    }
+  }
+
+  const actionsRow = document.createElement("div");
+  actionsRow.className = "mode-cache-row mode-diag-links-row";
+
+  const shareBtn = document.createElement("button");
+  shareBtn.type = "button";
+  shareBtn.className = "mode-clear-btn";
+  shareBtn.textContent = "Share diagnostic";
+  shareBtn.title =
+    "Open a new issue on paritytech/dotli pre-filled with these diagnostics";
+  shareBtn.addEventListener("click", () => {
+    const report = formatDiagnosticsReport(
+      base,
+      smoldotInfo,
+      polkadotApi,
+      novasamatech,
+      productLabel,
+    );
+    const body = [
+      "<!-- Describe the issue above this line; the diagnostics below are auto-filled. -->",
+      "",
+      "## Diagnostics",
+      "",
+      "```",
+      report,
+      "```",
+    ].join("\n");
+    const url = new URL("https://github.com/paritytech/dotli/issues/new");
+    url.searchParams.set("body", body);
+    window.open(url.toString(), "_blank", "noopener,noreferrer");
+  });
+
+  const debugOn = isTruapiDebugEnabled();
+  const debugBtn = document.createElement("button");
+  debugBtn.type = "button";
+  debugBtn.className = "mode-clear-btn";
+  debugBtn.textContent = debugOn ? "Exit debug mode" : "Open in debug mode";
+  debugBtn.title = debugOn
+    ? "Reload this tab with the TrUAPI debug panel disabled"
+    : "Reload this tab with the TrUAPI debug panel enabled (off again on tab close)";
+  debugBtn.addEventListener("click", () => {
+    const url = new URL(window.location.href);
+    url.searchParams.set("debug", debugOn ? "off" : "true");
+    window.location.assign(url.toString());
+  });
+
+  actionsRow.appendChild(shareBtn);
+  actionsRow.appendChild(debugBtn);
+  parent.appendChild(actionsRow);
+}
+
+/** Flatten the diagnostics tree into a plain-text block that reads cleanly
+ *  both inside a GitHub issue code block and in a Slack message.
+ *
+ *  Structure (one blank line between sections):
+ *    1. Base rows (Site, Build, Chain[, Worker|RPC Node], Content, Browser)
+ *    2. Cache: every toggle as on/off. Sourced from persisted settings
+ *              so the snapshot matches what's actually live right now.
+ *    3. Permissions: per-product, omitted on landing where we don't have
+ *                    a scoped label to query.
+ *    4. Packages: flat list of smoldot, polkadot-api, and novasamatech. The
+ *                 live block heights from the @smoldot popover section
+ *                 aren't included here because they're noise in a bug
+ *                 report. The popover already shows them live. */
+function formatDiagnosticsReport(
+  base: [label: string, value: string][],
+  smoldot: SmoldotInfo,
+  polkadotApi: { name: string; version: string }[],
+  novasamatech: { name: string; version: string }[],
+  productLabel: string | null,
+): string {
+  const lines: string[] = [];
+  for (const [k, v] of base) {
+    lines.push(`${k}: ${v}`);
+  }
+
+  // Cache
+  const cache = getCacheSettings();
+  lines.push(
+    "",
+    "Cache:",
+    `  dotNS cache: ${cache.skipCidCache ? "off" : "on"}`,
+    `  Archive cache: ${cache.skipArchiveCache ? "off" : "on"}`,
+    `  Worker cache: ${cache.skipWorkerCache ? "off" : "on"}`,
+  );
+
+  // Permissions, only when we know which product label to scope against.
+  if (productLabel !== null) {
+    lines.push("", "Permissions:");
+    for (const perm of ALL_PERMISSIONS) {
+      const status = getPermissionStatus(productLabel, perm.name);
+      lines.push(`  ${perm.label}: ${status === "granted" ? "on" : "off"}`);
+    }
+  }
+
+  // Packages, one flat list. smoldot leads because it's the heaviest
+  // dependency and the one most issues are ultimately about.
+  lines.push("", "Packages:", `  smoldot: ${smoldot.version}`);
+  for (const p of polkadotApi) {
+    lines.push(`  ${p.name}: ${p.version}`);
+  }
+  for (const p of novasamatech) {
+    lines.push(`  ${p.name}: ${p.version}`);
+  }
+  return lines.join("\n");
+}
+
+function buildBaseDiagnosticsRows(): [label: string, value: string][] {
+  const version =
+    typeof __DOTLI_VERSION__ === "string" ? __DOTLI_VERSION__ : "0.0.0";
+  const sha = (import.meta.env.VITE_COMMIT_SHA as string | undefined) ?? "dev";
+
+  const backend = getBackend();
+  const network = getNetwork();
+
+  const rows: [string, string][] = [
+    // `location.host` includes the port when non-default. Useful on
+    // localhost (`hackme3.localhost:5173`), transparent on production
+    // (`hackme3.dot.li`).
+    ["Site", window.location.host],
+    ["Build", `${version} (${shortSha(sha)})`],
+    ["Network", NETWORK_NAME_TO_SERVICES_CONFIG[network].label],
+    ["Backend", backendLabel(backend)],
+  ];
+
+  // Sub-row attached to the Backend row:
+  //   - smoldot-shared-worker: "Worker" label and build SHA. The SharedWorker
+  //     is a cached script. If it's running an older bundle than the current
+  //     page, this SHA diverges from Build, which is the tell-tale for a stale
+  //     worker. (Today the Worker ships embedded in the same bundle, so
+  //     the two match. The row still lets us spot a divergence in the
+  //     field.)
+  //   - smoldot-direct: no sub-row. smoldot is torn down every page load.
+  //   - rpc-gateway: both WSS endpoints (Relay and Asset Hub). The curated
+  //     lists are candidate endpoints. polkadot-api's ws-provider rotates
+  //     on failure, so `renderDiagnostics` later replaces the Asset Hub
+  //     entry with the one the provider is actually connected to. Relay
+  //     isn't dialed at all in rpc mode today (dotNS is Asset Hub only),
+  //     so it just shows the first candidate for reference.
+  if (backend === "smoldot-shared-worker") {
+    if (typeof SharedWorker === "undefined") {
+      rows.push(["Worker", "unavailable"]);
+    } else {
+      rows.push(["Worker", shortSha(sha)]);
+    }
+  } else if (backend === "rpc-gateway") {
+    const cfg = getActiveServicesConfig();
+    rows.push(["Relay node", cfg.relay.rpcs[0] ?? "n/a"]);
+    rows.push(["AssetHub node", cfg.assethub.rpcs[0] ?? "n/a"]);
+    rows.push(["Bulletin Node", cfg.bulletin.rpcs[0] ?? "n/a"]);
+  }
+
+  // Product manifest snapshot.
+  const root = getActiveRootManifest();
+  if (root !== null) {
+    rows.push(["Manifest", `v${String(root.schemaVersion)}`]);
+  }
+  const app = getActiveAppManifest();
+  if (app !== null) {
+    rows.push(["App version", formatAppVersion(app.appVersion)]);
+  }
+
+  rows.push(["Browser", summarizeUserAgent(navigator.userAgent)]);
+  return rows;
+}
+
+interface SmoldotInfo {
+  /** Human-facing version label, e.g. "3.0.0 (c33c647)". */
+  version: string;
+  /** Mutable block readouts for the share report. */
+  blocks: { relay: string; assetHub: string; people: string };
+}
+
+function buildSmoldotVersionLabel(): string {
+  const smoldot =
+    typeof __SMOLDOT_VERSION__ === "string" ? __SMOLDOT_VERSION__ : "unknown";
+  // Smoldot's upstream commit is resolved at build time by the host's
+  // vite.config against paritytech/smoldot's release tags. Degrades to
+  // just `<version>` when the lookup wasn't possible (offline build).
+  const commit =
+    typeof __SMOLDOT_COMMIT__ === "string" && __SMOLDOT_COMMIT__.length > 0
+      ? ` (${shortSha(__SMOLDOT_COMMIT__)})`
+      : "";
+  return `${smoldot}${commit}`;
+}
+
+/**
+ * Query the finalized block number for a given chain through the protocol
+ * iframe's `chainConnect` bridge. Works across all chain backends:
+ *   - smoldot-shared-worker / smoldot-direct: goes through smoldot
+ *   - rpc: goes through the curated WSS endpoint
+ *
+ * Returns `null` if the chain isn't supported by the active backend (e.g.
+ * asking for relay in rpc mode, which only supports Asset Hub) or if the
+ * query doesn't resolve within the timeout. The heavy `polkadot-api` import
+ * stays dynamic so opening the popover is cheap when the user doesn't care
+ * about blocks.
+ */
+async function queryFinalizedBlock(
+  genesisHash: string,
+): Promise<number | null> {
+  try {
+    if (!isRemoteChainSupported(genesisHash)) {
+      return null;
+    }
+    const provider = createRemoteChainProvider(genesisHash);
+    if (provider === null) {
+      return null;
+    }
+    const papi = await import("polkadot-api");
+    const client = papi.createClient(provider);
+    try {
+      const block = await Promise.race([
+        client.getFinalizedBlock(),
+        new Promise<never>((_, reject) => {
+          setTimeout(() => {
+            reject(new Error("timeout"));
+          }, 10_000);
+        }),
+      ]);
+      return block.number;
+    } finally {
+      client.destroy();
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Static label/value row used by the Diagnostics block. No click-to-copy.
+ * The "Share diagnostic" button at the bottom exports the full report at
+ * once, so per-row copy would just be noise.
+ *
+ * Returns an `update(value)` handle so callers can fill the row later when
+ * an async lookup finishes (used by the @smoldot block queries).
+ */
+interface InfoRowHandle {
+  update: (value: string) => void;
+}
+function renderInfoRow(
+  parent: HTMLElement,
+  label: string,
+  value: string,
+  options: { copyable?: boolean } = {},
+): InfoRowHandle {
+  const row = document.createElement("div");
+  row.className = "mode-endpoint-row mode-info-row";
+  const labelEl = document.createElement("span");
+  labelEl.className = "mode-endpoint-label";
+  labelEl.textContent = label;
+  const valueEl = document.createElement("code");
+  valueEl.className = "mode-endpoint-value";
+  valueEl.textContent = value;
+  row.appendChild(labelEl);
+  row.appendChild(valueEl);
+  parent.appendChild(row);
+
+  let currentValue = value;
+  let copiedTimer: ReturnType<typeof setTimeout> | undefined;
+
+  if (options.copyable === true) {
+    row.classList.add("mode-info-row-copyable");
+    row.title = `Click to copy ${label}`;
+    row.addEventListener("click", () => {
+      if (
+        currentValue === "" ||
+        currentValue === "…" ||
+        currentValue === "n/a"
+      ) {
+        return;
+      }
+      void navigator.clipboard.writeText(currentValue).then(() => {
+        valueEl.textContent = "Copied";
+        row.classList.add("copied");
+        if (copiedTimer !== undefined) {
+          clearTimeout(copiedTimer);
+        }
+        copiedTimer = setTimeout(() => {
+          valueEl.textContent = currentValue;
+          row.classList.remove("copied");
+          copiedTimer = undefined;
+        }, 1000);
+      });
+    });
+  }
+
+  return {
+    update: (next) => {
+      currentValue = next;
+      if (copiedTimer === undefined) {
+        valueEl.textContent = next;
+      }
+    },
+  };
+}
diff --git a/packages/ui/src/topbar-dom.ts b/packages/ui/src/topbar-dom.ts
new file mode 100644
index 00000000..d51edb05
--- /dev/null
+++ b/packages/ui/src/topbar-dom.ts
@@ -0,0 +1,13 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Small DOM helpers shared between the top bar's settings popover and its
+// diagnostics panel. Kept in their own module so neither panel has to import
+// the other just to reuse them.
+
+export function appendSectionHeader(parent: HTMLElement, text: string): void {
+  const header = document.createElement("div");
+  header.className = "mode-popover-section";
+  header.textContent = text;
+  parent.appendChild(header);
+}
diff --git a/packages/ui/src/topbar-format.ts b/packages/ui/src/topbar-format.ts
new file mode 100644
index 00000000..7af2b792
--- /dev/null
+++ b/packages/ui/src/topbar-format.ts
@@ -0,0 +1,81 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Pure formatting helpers for the top bar's diagnostics block. Kept free of
+// DOM refs and module state so they can be unit-tested in isolation; the
+// stateful diagnostics renderer in `topbar.ts` imports them.
+
+import type { Backend } from "@dotli/config/mode";
+
+export function isTruapiDebugEnabled(): boolean {
+  try {
+    return sessionStorage.getItem("dotli:truapi-debug") === "1";
+  } catch {
+    // sessionStorage may be unavailable in exotic environments (Safari
+    // private mode). Default to "not in debug mode".
+    return false;
+  }
+}
+
+export function backendLabel(b: Backend): string {
+  switch (b) {
+    case "smoldot-shared-worker":
+      return "Light Client Shared";
+    case "smoldot-direct":
+      return "Light Client Per-Tab";
+    case "rpc-gateway":
+      return "Trusted Providers";
+  }
+}
+
+export function formatBlock(n: number | null): string {
+  return n === null ? "n/a" : `#${n.toLocaleString("en-US")}`;
+}
+
+export function shortSha(sha: string): string {
+  if (sha === "dev" || sha.length <= 7) {
+    return sha;
+  }
+  return sha.slice(0, 7);
+}
+
+/**
+ * Turn a long `navigator.userAgent` string into something compact like
+ * "Chrome 147 (macOS)". Heuristic, not a replacement for a real UA parser.
+ * Good enough for a debug row that the user can still click-to-copy the
+ * full value (the row shows the short version but the UA is stable enough
+ * that engineers can recognize the brand without the full payload).
+ */
+export function summarizeUserAgent(ua: string): string {
+  let browser = "Unknown";
+  const chromeMatch = /(Chrome|CriOS)\/(\d+)/.exec(ua);
+  const firefoxMatch = /Firefox\/(\d+)/.exec(ua);
+  const safariMatch = /Version\/(\d+)[^)]+Safari/.exec(ua);
+  const edgeMatch = /Edg\/(\d+)/.exec(ua);
+  if (edgeMatch) {
+    browser = `Edge ${edgeMatch[1]}`;
+  } else if (firefoxMatch) {
+    browser = `Firefox ${firefoxMatch[1]}`;
+  } else if (chromeMatch) {
+    browser = `Chrome ${chromeMatch[2]}`;
+  } else if (safariMatch) {
+    browser = `Safari ${safariMatch[1]}`;
+  }
+
+  let os = "Unknown";
+  // iPhone/iPad first: iOS UAs contain "like Mac OS X", so the Mac check
+  // would otherwise claim them.
+  if (ua.includes("iPhone") || ua.includes("iPad")) {
+    os = "iOS";
+  } else if (ua.includes("Mac OS X") || ua.includes("Macintosh")) {
+    os = "macOS";
+  } else if (ua.includes("Windows")) {
+    os = "Windows";
+  } else if (ua.includes("Android")) {
+    os = "Android";
+  } else if (ua.includes("Linux")) {
+    os = "Linux";
+  }
+
+  return `${browser} (${os})`;
+}
diff --git a/packages/ui/src/topbar.ts b/packages/ui/src/topbar.ts
index c78dc5fd..3ba325d8 100644
--- a/packages/ui/src/topbar.ts
+++ b/packages/ui/src/topbar.ts
@@ -15,17 +15,8 @@ import type { Identity } from "@novasamatech/host-papp";
 import { log } from "@dotli/shared/log";
 import { escapeHtml } from "@dotli/shared/html";
 import { isMobileDevice } from "@dotli/shared/device";
-import {
-  formatAppVersion,
-  getActiveAppManifest,
-  getActiveRootManifest,
-} from "@dotli/shared/active-manifest";
 import { SITE_ID } from "@dotli/config/config";
-import {
-  createRemoteChainProvider,
-  hasSharedAuthSession,
-  isRemoteChainSupported,
-} from "@dotli/protocol/client";
+import { hasSharedAuthSession } from "@dotli/protocol/client";
 import {
   getCacheSettings,
   setCacheSettings,
@@ -44,7 +35,6 @@ import {
   NETWORK_NAME_TO_SERVICES_CONFIG,
   type Network,
 } from "@dotli/config/network";
-import { getActiveServicesConfig } from "@dotli/config/network";
 import { writeSettingsToSearch } from "@dotli/config/url-settings";
 import {
   ALL_PERMISSIONS,
@@ -55,6 +45,9 @@ import {
   setPermissionStatus,
   type PermissionStatus,
 } from "./permissions";
+import { EventManager } from "./event-manager";
+import { appendSectionHeader } from "./topbar-dom";
+import { renderDiagnostics } from "./topbar-diagnostics";
 
 function getElement(id: string): HTMLElement {
   const el = document.getElementById(id);
@@ -795,14 +788,14 @@ function createPermissionDropdown(
         closeOpenDropdown();
       }
     }
-    document.addEventListener("click", onDocClick);
-    document.addEventListener("keydown", onKeyDown);
+    const dropdownEvents = new EventManager();
+    dropdownEvents.on(document, "click", onDocClick);
+    dropdownEvents.on(document, "keydown", onKeyDown);
 
     openDropdownCleanup = (): void => {
       menu.remove();
       trigger.setAttribute("aria-expanded", "false");
-      document.removeEventListener("click", onDocClick);
-      document.removeEventListener("keydown", onKeyDown);
+      dropdownEvents.disposeAll();
     };
   });
 
@@ -1067,7 +1060,7 @@ function renderModePopover(): void {
   leftCol.appendChild(clearRow);
 
   appendSectionHeader(rightCol, "Diagnostics");
-  renderDiagnostics(rightCol);
+  renderDiagnostics(rightCol, currentProductLabel);
 
   // Footer wraps the divider, Save & Apply, and the warning as one unit so it
   // can pin to the bottom of the full-screen sheet on mobile (CSS), keeping
@@ -1300,530 +1293,6 @@ async function unregisterAllServiceWorkers(): Promise<void> {
   }
 }
 
-function appendSectionHeader(parent: HTMLElement, text: string): void {
-  const header = document.createElement("div");
-  header.className = "mode-popover-section";
-  header.textContent = text;
-  parent.appendChild(header);
-}
-
-// Baked at build time by `apps/host/vite.config.ts` (`define.*`). The
-// topbar only ever renders in the host shell so these will always be
-// present in practice. `undefined` fallbacks are defensive for tests and
-// for any future caller that imports this module from a different bundle.
-declare const __DOTLI_VERSION__: string | undefined;
-declare const __SMOLDOT_VERSION__: string | undefined;
-declare const __SMOLDOT_COMMIT__: string | undefined;
-declare const __POLKADOT_API_VERSION__: string | undefined;
-declare const __POLKADOT_API_VERSIONS__:
-  | { name: string; version: string }[]
-  | undefined;
-declare const __NOVASAMATECH_VERSIONS__:
-  | { name: string; version: string }[]
-  | undefined;
-
-/**
- * Render the Diagnostics block at the bottom of the settings popover. Rows
- * are static (no click-to-copy). The "Share diagnostic" button at the end
- * exports the whole block at once, so individual-row copy would be noise.
- *
- * Values come from places that are cheap to read synchronously so the
- * popover doesn't pop open with a spinner. "unknown" is a valid value, so
- * don't over-engineer fallbacks.
- */
-function renderDiagnostics(parent: HTMLElement): void {
-  const base = buildBaseDiagnosticsRows();
-  const rowHandles = new Map<string, InfoRowHandle>();
-  const COPYABLE_ROWS = new Set([
-    "Site",
-    "Relay node",
-    "AssetHub node",
-    "Bulletin Node",
-  ]);
-  for (const entry of base) {
-    rowHandles.set(
-      entry[0],
-      renderInfoRow(parent, entry[0], entry[1], {
-        copyable: COPYABLE_ROWS.has(entry[0]),
-      }),
-    );
-  }
-
-  // When running in RPC chain mode, ask the live ws-provider which URI
-  // it actually connected to. polkadot-api rotates across the curated
-  // candidate list on failure, so the first entry of the config array
-  // may not be the node currently answering. Lazy-imported so the
-  // resolver bundle (polkadot-api and ws-provider) isn't pulled into the
-  // popover's own chunk. By the time the popover opens under RPC mode,
-  // `@dotli/resolver/rpc-resolve` is already warm because host main
-  // imported it to resolve the name. Both the DOM row and the base
-  // snapshot are updated so the Share-diagnostic export stays honest.
-  if (getBackend() === "rpc-gateway") {
-    void import("@dotli/resolver/rpc-resolve").then(
-      ({ getConnectedAssetHubRpcEndpoint }) => {
-        const live = getConnectedAssetHubRpcEndpoint();
-        if (live === null) {
-          return;
-        }
-        rowHandles.get("AssetHub node")?.update(live);
-        const row = base.find((r) => r[0] === "AssetHub node");
-        if (row !== undefined) {
-          row[1] = live;
-        }
-      },
-    );
-  }
-
-  // Version is static and cheap. Block numbers are async so the rows start
-  // with an ellipsis placeholder and get swapped in when `chainConnect`
-  // rounds-trip back with a finalized-block header. When the user is on
-  // the RPC chain backend, smoldot isn't running, so hide the per-chain
-  // block rows entirely (the endpoints already appear under Chain) and
-  // keep only the smoldot version so the dependency is still visible.
-  const smoldotInfo: SmoldotInfo = {
-    version: buildSmoldotVersionLabel(),
-    blocks: { relay: "…", assetHub: "…", people: "…" },
-  };
-  const smoldotActive = getBackend() !== "rpc-gateway";
-  appendSectionHeader(parent, "@smoldot");
-  renderInfoRow(parent, "smoldot", smoldotInfo.version);
-  if (smoldotActive) {
-    const relayRow = renderInfoRow(parent, "Relay Chain", "…");
-    const assetHubRow = renderInfoRow(parent, "Asset Hub", "…");
-    const peopleRow = renderInfoRow(parent, "People Chain", "…");
-
-    // Fire all queries. They update their own rows and the shared snapshot
-    // (so the "Share diagnostic" button captures whatever resolved in time).
-    const cfg = getActiveServicesConfig();
-    void queryFinalizedBlock(cfg.relay.genesis).then((n) => {
-      const v = formatBlock(n);
-      relayRow.update(v);
-      smoldotInfo.blocks.relay = v;
-    });
-    void queryFinalizedBlock(cfg.assethub.genesis).then((n) => {
-      const v = formatBlock(n);
-      assetHubRow.update(v);
-      smoldotInfo.blocks.assetHub = v;
-    });
-    void queryFinalizedBlock(cfg.people.genesis).then((n) => {
-      const v = formatBlock(n);
-      peopleRow.update(v);
-      smoldotInfo.blocks.people = v;
-    });
-  } else {
-    // Keep the snapshot tagged as n/a so the Share-diagnostic report is
-    // coherent: smoldot wasn't consulted, don't claim a block height.
-    smoldotInfo.blocks.relay = "n/a";
-    smoldotInfo.blocks.assetHub = "n/a";
-    smoldotInfo.blocks.people = "n/a";
-  }
-
-  // The unscoped `polkadot-api` package lives in the same visual section as
-  // `@polkadot-api/*`. Same ecosystem, same release cadence, users expect
-  // to see it with its siblings rather than at the top of the popover.
-  const polkadotApi: { name: string; version: string }[] = [];
-  if (typeof __POLKADOT_API_VERSION__ === "string") {
-    polkadotApi.push({
-      name: "polkadot-api",
-      version: __POLKADOT_API_VERSION__,
-    });
-  }
-  if (typeof __POLKADOT_API_VERSIONS__ !== "undefined") {
-    polkadotApi.push(...__POLKADOT_API_VERSIONS__);
-  }
-
-  // @novasamatech/* versions move in lockstep, so showing every single
-  // package is noise. Keep only the two that are independently meaningful:
-  // host-api (the host runtime) and sdk-statement (the statement store
-  // client). Everything else in the scope tracks host-api's version.
-  const NOVASAMATECH_ALLOWLIST = new Set([
-    "@novasamatech/host-api",
-    "@novasamatech/sdk-statement",
-  ]);
-  const novasamatech = (
-    typeof __NOVASAMATECH_VERSIONS__ === "undefined"
-      ? []
-      : __NOVASAMATECH_VERSIONS__
-  ).filter((p) => NOVASAMATECH_ALLOWLIST.has(p.name));
-
-  if (polkadotApi.length > 0) {
-    appendSectionHeader(parent, "@polkadot-api");
-    for (const pkg of polkadotApi) {
-      renderInfoRow(parent, pkg.name, pkg.version);
-    }
-  }
-  if (novasamatech.length > 0) {
-    appendSectionHeader(parent, "@triangle-sdk");
-    for (const pkg of novasamatech) {
-      renderInfoRow(parent, pkg.name, pkg.version);
-    }
-  }
-
-  const actionsRow = document.createElement("div");
-  actionsRow.className = "mode-cache-row mode-diag-links-row";
-
-  const shareBtn = document.createElement("button");
-  shareBtn.type = "button";
-  shareBtn.className = "mode-clear-btn";
-  shareBtn.textContent = "Share diagnostic";
-  shareBtn.title =
-    "Open a new issue on paritytech/dotli pre-filled with these diagnostics";
-  shareBtn.addEventListener("click", () => {
-    const report = formatDiagnosticsReport(
-      base,
-      smoldotInfo,
-      polkadotApi,
-      novasamatech,
-    );
-    const body = [
-      "<!-- Describe the issue above this line; the diagnostics below are auto-filled. -->",
-      "",
-      "## Diagnostics",
-      "",
-      "```",
-      report,
-      "```",
-    ].join("\n");
-    const url = new URL("https://github.com/paritytech/dotli/issues/new");
-    url.searchParams.set("body", body);
-    window.open(url.toString(), "_blank", "noopener,noreferrer");
-  });
-
-  const debugOn = isTruapiDebugEnabled();
-  const debugBtn = document.createElement("button");
-  debugBtn.type = "button";
-  debugBtn.className = "mode-clear-btn";
-  debugBtn.textContent = debugOn ? "Exit debug mode" : "Open in debug mode";
-  debugBtn.title = debugOn
-    ? "Reload this tab with the TrUAPI debug panel disabled"
-    : "Reload this tab with the TrUAPI debug panel enabled (off again on tab close)";
-  debugBtn.addEventListener("click", () => {
-    const url = new URL(window.location.href);
-    url.searchParams.set("debug", debugOn ? "off" : "true");
-    window.location.assign(url.toString());
-  });
-
-  actionsRow.appendChild(shareBtn);
-  actionsRow.appendChild(debugBtn);
-  parent.appendChild(actionsRow);
-}
-
-function isTruapiDebugEnabled(): boolean {
-  try {
-    return sessionStorage.getItem("dotli:truapi-debug") === "1";
-  } catch {
-    // sessionStorage may be unavailable in exotic environments (Safari
-    // private mode). Default to "not in debug mode".
-    return false;
-  }
-}
-
-/** Flatten the diagnostics tree into a plain-text block that reads cleanly
- *  both inside a GitHub issue code block and in a Slack message.
- *
- *  Structure (one blank line between sections):
- *    1. Base rows (Site, Build, Chain[, Worker|RPC Node], Content, Browser)
- *    2. Cache: every toggle as on/off. Sourced from persisted settings
- *              so the snapshot matches what's actually live right now.
- *    3. Permissions: per-product, omitted on landing where we don't have
- *                    a scoped label to query.
- *    4. Packages: flat list of smoldot, polkadot-api, and novasamatech. The
- *                 live block heights from the @smoldot popover section
- *                 aren't included here because they're noise in a bug
- *                 report. The popover already shows them live. */
-function formatDiagnosticsReport(
-  base: [label: string, value: string][],
-  smoldot: SmoldotInfo,
-  polkadotApi: { name: string; version: string }[],
-  novasamatech: { name: string; version: string }[],
-): string {
-  const lines: string[] = [];
-  for (const [k, v] of base) {
-    lines.push(`${k}: ${v}`);
-  }
-
-  // Cache
-  const cache = getCacheSettings();
-  lines.push(
-    "",
-    "Cache:",
-    `  dotNS cache: ${cache.skipCidCache ? "off" : "on"}`,
-    `  Archive cache: ${cache.skipArchiveCache ? "off" : "on"}`,
-    `  Worker cache: ${cache.skipWorkerCache ? "off" : "on"}`,
-  );
-
-  // Permissions, only when we know which product label to scope against.
-  if (currentProductLabel !== null) {
-    lines.push("", "Permissions:");
-    for (const perm of ALL_PERMISSIONS) {
-      const status = getPermissionStatus(currentProductLabel, perm.name);
-      lines.push(`  ${perm.label}: ${status === "granted" ? "on" : "off"}`);
-    }
-  }
-
-  // Packages, one flat list. smoldot leads because it's the heaviest
-  // dependency and the one most issues are ultimately about.
-  lines.push("", "Packages:", `  smoldot: ${smoldot.version}`);
-  for (const p of polkadotApi) {
-    lines.push(`  ${p.name}: ${p.version}`);
-  }
-  for (const p of novasamatech) {
-    lines.push(`  ${p.name}: ${p.version}`);
-  }
-  return lines.join("\n");
-}
-
-function buildBaseDiagnosticsRows(): [label: string, value: string][] {
-  const version =
-    typeof __DOTLI_VERSION__ === "string" ? __DOTLI_VERSION__ : "0.0.0";
-  const sha = (import.meta.env.VITE_COMMIT_SHA as string | undefined) ?? "dev";
-
-  const backend = getBackend();
-  const network = getNetwork();
-
-  const rows: [string, string][] = [
-    // `location.host` includes the port when non-default. Useful on
-    // localhost (`hackme3.localhost:5173`), transparent on production
-    // (`hackme3.dot.li`).
-    ["Site", window.location.host],
-    ["Build", `${version} (${shortSha(sha)})`],
-    ["Network", NETWORK_NAME_TO_SERVICES_CONFIG[network].label],
-    ["Backend", backendLabel(backend)],
-  ];
-
-  // Sub-row attached to the Backend row:
-  //   - smoldot-shared-worker: "Worker" label and build SHA. The SharedWorker
-  //     is a cached script. If it's running an older bundle than the current
-  //     page, this SHA diverges from Build, which is the tell-tale for a stale
-  //     worker. (Today the Worker ships embedded in the same bundle, so
-  //     the two match. The row still lets us spot a divergence in the
-  //     field.)
-  //   - smoldot-direct: no sub-row. smoldot is torn down every page load.
-  //   - rpc-gateway: both WSS endpoints (Relay and Asset Hub). The curated
-  //     lists are candidate endpoints. polkadot-api's ws-provider rotates
-  //     on failure, so `renderDiagnostics` later replaces the Asset Hub
-  //     entry with the one the provider is actually connected to. Relay
-  //     isn't dialed at all in rpc mode today (dotNS is Asset Hub only),
-  //     so it just shows the first candidate for reference.
-  if (backend === "smoldot-shared-worker") {
-    if (typeof SharedWorker === "undefined") {
-      rows.push(["Worker", "unavailable"]);
-    } else {
-      rows.push(["Worker", shortSha(sha)]);
-    }
-  } else if (backend === "rpc-gateway") {
-    const cfg = getActiveServicesConfig();
-    rows.push(["Relay node", cfg.relay.rpcs[0] ?? "n/a"]);
-    rows.push(["AssetHub node", cfg.assethub.rpcs[0] ?? "n/a"]);
-    rows.push(["Bulletin Node", cfg.bulletin.rpcs[0] ?? "n/a"]);
-  }
-
-  // Product manifest snapshot.
-  const root = getActiveRootManifest();
-  if (root !== null) {
-    rows.push(["Manifest", `v${String(root.schemaVersion)}`]);
-  }
-  const app = getActiveAppManifest();
-  if (app !== null) {
-    rows.push(["App version", formatAppVersion(app.appVersion)]);
-  }
-
-  rows.push(["Browser", summarizeUserAgent(navigator.userAgent)]);
-  return rows;
-}
-
-function backendLabel(b: Backend): string {
-  switch (b) {
-    case "smoldot-shared-worker":
-      return "Light Client Shared";
-    case "smoldot-direct":
-      return "Light Client Per-Tab";
-    case "rpc-gateway":
-      return "Trusted Providers";
-  }
-}
-
-interface SmoldotInfo {
-  /** Human-facing version label, e.g. "3.0.0 (c33c647)". */
-  version: string;
-  /** Mutable block readouts for the share report. */
-  blocks: { relay: string; assetHub: string; people: string };
-}
-
-function buildSmoldotVersionLabel(): string {
-  const smoldot =
-    typeof __SMOLDOT_VERSION__ === "string" ? __SMOLDOT_VERSION__ : "unknown";
-  // Smoldot's upstream commit is resolved at build time by the host's
-  // vite.config against paritytech/smoldot's release tags. Degrades to
-  // just `<version>` when the lookup wasn't possible (offline build).
-  const commit =
-    typeof __SMOLDOT_COMMIT__ === "string" && __SMOLDOT_COMMIT__.length > 0
-      ? ` (${shortSha(__SMOLDOT_COMMIT__)})`
-      : "";
-  return `${smoldot}${commit}`;
-}
-
-/**
- * Query the finalized block number for a given chain through the protocol
- * iframe's `chainConnect` bridge. Works across all chain backends:
- *   - smoldot-shared-worker / smoldot-direct: goes through smoldot
- *   - rpc: goes through the curated WSS endpoint
- *
- * Returns `null` if the chain isn't supported by the active backend (e.g.
- * asking for relay in rpc mode, which only supports Asset Hub) or if the
- * query doesn't resolve within the timeout. The heavy `polkadot-api` import
- * stays dynamic so opening the popover is cheap when the user doesn't care
- * about blocks.
- */
-async function queryFinalizedBlock(
-  genesisHash: string,
-): Promise<number | null> {
-  try {
-    if (!isRemoteChainSupported(genesisHash)) {
-      return null;
-    }
-    const provider = createRemoteChainProvider(genesisHash);
-    if (provider === null) {
-      return null;
-    }
-    const papi = await import("polkadot-api");
-    const client = papi.createClient(provider);
-    try {
-      const block = await Promise.race([
-        client.getFinalizedBlock(),
-        new Promise<never>((_, reject) => {
-          setTimeout(() => {
-            reject(new Error("timeout"));
-          }, 10_000);
-        }),
-      ]);
-      return block.number;
-    } finally {
-      client.destroy();
-    }
-  } catch {
-    return null;
-  }
-}
-
-function formatBlock(n: number | null): string {
-  return n === null ? "n/a" : `#${n.toLocaleString("en-US")}`;
-}
-
-function shortSha(sha: string): string {
-  if (sha === "dev" || sha.length <= 7) {
-    return sha;
-  }
-  return sha.slice(0, 7);
-}
-
-/**
- * Turn a long `navigator.userAgent` string into something compact like
- * "Chrome 147 (macOS)". Heuristic, not a replacement for a real UA parser.
- * Good enough for a debug row that the user can still click-to-copy the
- * full value (the row shows the short version but the UA is stable enough
- * that engineers can recognize the brand without the full payload).
- */
-function summarizeUserAgent(ua: string): string {
-  let browser = "Unknown";
-  const chromeMatch = /(Chrome|CriOS)\/(\d+)/.exec(ua);
-  const firefoxMatch = /Firefox\/(\d+)/.exec(ua);
-  const safariMatch = /Version\/(\d+)[^)]+Safari/.exec(ua);
-  const edgeMatch = /Edg\/(\d+)/.exec(ua);
-  if (edgeMatch) {
-    browser = `Edge ${edgeMatch[1]}`;
-  } else if (firefoxMatch) {
-    browser = `Firefox ${firefoxMatch[1]}`;
-  } else if (chromeMatch) {
-    browser = `Chrome ${chromeMatch[2]}`;
-  } else if (safariMatch) {
-    browser = `Safari ${safariMatch[1]}`;
-  }
-
-  let os = "Unknown";
-  if (ua.includes("Mac OS X") || ua.includes("Macintosh")) {
-    os = "macOS";
-  } else if (ua.includes("Windows")) {
-    os = "Windows";
-  } else if (ua.includes("Android")) {
-    os = "Android";
-  } else if (ua.includes("iPhone") || ua.includes("iPad")) {
-    os = "iOS";
-  } else if (ua.includes("Linux")) {
-    os = "Linux";
-  }
-
-  return `${browser} (${os})`;
-}
-
-/**
- * Static label/value row used by the Diagnostics block. No click-to-copy.
- * The "Share diagnostic" button at the bottom exports the full report at
- * once, so per-row copy would just be noise.
- *
- * Returns an `update(value)` handle so callers can fill the row later when
- * an async lookup finishes (used by the @smoldot block queries).
- */
-interface InfoRowHandle {
-  update: (value: string) => void;
-}
-function renderInfoRow(
-  parent: HTMLElement,
-  label: string,
-  value: string,
-  options: { copyable?: boolean } = {},
-): InfoRowHandle {
-  const row = document.createElement("div");
-  row.className = "mode-endpoint-row mode-info-row";
-  const labelEl = document.createElement("span");
-  labelEl.className = "mode-endpoint-label";
-  labelEl.textContent = label;
-  const valueEl = document.createElement("code");
-  valueEl.className = "mode-endpoint-value";
-  valueEl.textContent = value;
-  row.appendChild(labelEl);
-  row.appendChild(valueEl);
-  parent.appendChild(row);
-
-  let currentValue = value;
-  let copiedTimer: ReturnType<typeof setTimeout> | undefined;
-
-  if (options.copyable === true) {
-    row.classList.add("mode-info-row-copyable");
-    row.title = `Click to copy ${label}`;
-    row.addEventListener("click", () => {
-      if (
-        currentValue === "" ||
-        currentValue === "…" ||
-        currentValue === "n/a"
-      ) {
-        return;
-      }
-      void navigator.clipboard.writeText(currentValue).then(() => {
-        valueEl.textContent = "Copied";
-        row.classList.add("copied");
-        if (copiedTimer !== undefined) {
-          clearTimeout(copiedTimer);
-        }
-        copiedTimer = setTimeout(() => {
-          valueEl.textContent = currentValue;
-          row.classList.remove("copied");
-          copiedTimer = undefined;
-        }, 1000);
-      });
-    });
-  }
-
-  return {
-    update: (next) => {
-      currentValue = next;
-      if (copiedTimer === undefined) {
-        valueEl.textContent = next;
-      }
-    },
-  };
-}
-
 function renderChainRadio(
   parent: HTMLElement,
   value: Backend,
diff --git a/packages/ui/tests/container-product.test.ts b/packages/ui/tests/container-product.test.ts
new file mode 100644
index 00000000..3b517ceb
--- /dev/null
+++ b/packages/ui/tests/container-product.test.ts
@@ -0,0 +1,100 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { describe, expect, it } from "vitest";
+import {
+  identifierToLabel,
+  isDevPreviewLabel,
+  isProductAccountValid,
+  isUint8ArrayLike,
+  labelAcceptsIdentifier,
+  labelToProductIdentifier,
+  resolveProductAccountId,
+} from "@dotli/ui/container-product";
+
+describe("isDevPreviewLabel", () => {
+  it("treats localhost proxy hosts as dev previews", () => {
+    expect(isDevPreviewLabel("localhost:5173")).toBe(true);
+  });
+
+  it("treats webcontainer hosts as dev previews", () => {
+    expect(isDevPreviewLabel("abc-123.webcontainer-api.io")).toBe(true);
+  });
+
+  it("treats a normal deployed label as not a dev preview", () => {
+    expect(isDevPreviewLabel("myapp")).toBe(false);
+  });
+});
+
+describe("labelToProductIdentifier", () => {
+  it("appends .dot to a deployed label", () => {
+    expect(labelToProductIdentifier("myapp")).toBe("myapp.dot");
+  });
+
+  it("keeps the bare host for dev previews", () => {
+    expect(labelToProductIdentifier("localhost:5173")).toBe("localhost:5173");
+  });
+});
+
+describe("identifierToLabel", () => {
+  it("strips the .dot suffix", () => {
+    expect(identifierToLabel("myapp.dot")).toBe("myapp");
+  });
+});
+
+describe("labelAcceptsIdentifier", () => {
+  it("accepts the label's own derived identifier", () => {
+    expect(labelAcceptsIdentifier("myapp", "myapp.dot")).toBe(true);
+  });
+
+  it("accepts any valid product identifier (.dot)", () => {
+    expect(labelAcceptsIdentifier("myapp", "other.dot")).toBe(true);
+  });
+
+  it("rejects a non-product, non-matching identifier", () => {
+    expect(labelAcceptsIdentifier("myapp", "garbage")).toBe(false);
+  });
+});
+
+describe("isProductAccountValid", () => {
+  it("requires a deployed label to sign as its own identifier", () => {
+    expect(isProductAccountValid("myapp", "myapp.dot")).toBe(true);
+    expect(isProductAccountValid("myapp", "evil.dot")).toBe(false);
+  });
+
+  it("is permissive for dev previews", () => {
+    expect(isProductAccountValid("localhost:5173", "anything.dot")).toBe(true);
+  });
+});
+
+describe("resolveProductAccountId", () => {
+  it("forces a deployed label to its own identifier, ignoring the reported one", () => {
+    const resolved = resolveProductAccountId("myapp", ["evil.dot", undefined]);
+    expect(resolved[0]).toBe("myapp.dot");
+  });
+
+  it("passes the reported identifier through for dev previews", () => {
+    const resolved = resolveProductAccountId("localhost:5173", [
+      "whatever.dot",
+      undefined,
+    ]);
+    expect(resolved[0]).toBe("whatever.dot");
+  });
+});
+
+describe("isUint8ArrayLike", () => {
+  it("accepts a real Uint8Array", () => {
+    expect(isUint8ArrayLike(new Uint8Array([1, 2, 3]))).toBe(true);
+  });
+
+  it("accepts a cross-realm Uint8Array by constructor name", () => {
+    const crossRealm = { constructor: { name: "Uint8Array" } };
+    expect(isUint8ArrayLike(crossRealm)).toBe(true);
+  });
+
+  it("rejects non-objects and plain values", () => {
+    expect(isUint8ArrayLike(null)).toBe(false);
+    expect(isUint8ArrayLike("bytes")).toBe(false);
+    expect(isUint8ArrayLike([1, 2, 3])).toBe(false);
+  });
+});
diff --git a/packages/ui/tests/event-manager.test.ts b/packages/ui/tests/event-manager.test.ts
new file mode 100644
index 00000000..e81ce2c2
--- /dev/null
+++ b/packages/ui/tests/event-manager.test.ts
@@ -0,0 +1,75 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { describe, expect, it, vi } from "vitest";
+import { EventManager } from "@dotli/ui/event-manager";
+
+describe("EventManager", () => {
+  it("registers a listener that fires until disposed", () => {
+    const events = new EventManager();
+    const el = document.createElement("button");
+    const handler = vi.fn();
+    events.on(el, "click", handler);
+
+    el.click();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    events.disposeAll();
+    el.click();
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("removes every registered listener on disposeAll", () => {
+    const events = new EventManager();
+    const a = vi.fn();
+    const b = vi.fn();
+    events.on(document, "click", a);
+    events.on(document, "keydown", b);
+    expect(events.size).toBe(2);
+
+    events.disposeAll();
+    document.dispatchEvent(new Event("click"));
+    document.dispatchEvent(new Event("keydown"));
+    expect(a).not.toHaveBeenCalled();
+    expect(b).not.toHaveBeenCalled();
+    expect(events.size).toBe(0);
+  });
+
+  it("returns a disposer from on() that removes just that listener", () => {
+    const events = new EventManager();
+    const el = document.createElement("div");
+    const handler = vi.fn();
+    const dispose = events.on(el, "click", handler);
+
+    dispose();
+    el.click();
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("runs arbitrary teardown callbacks added via add()", () => {
+    const events = new EventManager();
+    const teardown = vi.fn();
+    events.add(teardown);
+    events.disposeAll();
+    expect(teardown).toHaveBeenCalledTimes(1);
+  });
+
+  it("is safe to dispose more than once (no double teardown)", () => {
+    const events = new EventManager();
+    const teardown = vi.fn();
+    events.add(teardown);
+    events.disposeAll();
+    events.disposeAll();
+    expect(teardown).toHaveBeenCalledTimes(1);
+  });
+
+  it("matches add/remove options so capture listeners are torn down", () => {
+    const events = new EventManager();
+    const el = document.createElement("div");
+    const handler = vi.fn();
+    events.on(el, "click", handler, { capture: true });
+    events.disposeAll();
+    el.click();
+    expect(handler).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/ui/tests/topbar-format.test.ts b/packages/ui/tests/topbar-format.test.ts
new file mode 100644
index 00000000..fa5b6306
--- /dev/null
+++ b/packages/ui/tests/topbar-format.test.ts
@@ -0,0 +1,109 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  backendLabel,
+  formatBlock,
+  isTruapiDebugEnabled,
+  shortSha,
+  summarizeUserAgent,
+} from "@dotli/ui/topbar-format";
+
+describe("backendLabel", () => {
+  it("maps every backend to a human label", () => {
+    expect(backendLabel("smoldot-shared-worker")).toBe("Light Client Shared");
+    expect(backendLabel("smoldot-direct")).toBe("Light Client Per-Tab");
+    expect(backendLabel("rpc-gateway")).toBe("Trusted Providers");
+  });
+});
+
+describe("formatBlock", () => {
+  it("renders null as n/a", () => {
+    expect(formatBlock(null)).toBe("n/a");
+  });
+
+  it("renders a number with thousands separators and a hash prefix", () => {
+    expect(formatBlock(0)).toBe("#0");
+    expect(formatBlock(1234567)).toBe("#1,234,567");
+  });
+});
+
+describe("shortSha", () => {
+  it("passes through the 'dev' sentinel", () => {
+    expect(shortSha("dev")).toBe("dev");
+  });
+
+  it("leaves short shas untouched", () => {
+    expect(shortSha("abc1234")).toBe("abc1234");
+  });
+
+  it("truncates long shas to 7 chars", () => {
+    expect(shortSha("0123456789abcdef")).toBe("0123456");
+  });
+});
+
+describe("summarizeUserAgent", () => {
+  it("detects Chrome on macOS", () => {
+    const ua =
+      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36";
+    expect(summarizeUserAgent(ua)).toBe("Chrome 147 (macOS)");
+  });
+
+  it("detects Firefox on Windows", () => {
+    const ua =
+      "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:130.0) Gecko/20100101 Firefox/130.0";
+    expect(summarizeUserAgent(ua)).toBe("Firefox 130 (Windows)");
+  });
+
+  it("detects Chrome on Android", () => {
+    const ua =
+      "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36";
+    expect(summarizeUserAgent(ua)).toBe("Chrome 120 (Android)");
+  });
+
+  // iOS UAs contain "like Mac OS X", so the iPhone/iPad check must run
+  // before the Mac check to avoid misreporting iPhones as macOS.
+  it("detects Safari on iOS despite the 'like Mac OS X' token", () => {
+    const ua =
+      "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
+    expect(summarizeUserAgent(ua)).toBe("Safari 17 (iOS)");
+  });
+
+  it("prefers Edge over the Chrome token it also carries", () => {
+    const ua =
+      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0";
+    expect(summarizeUserAgent(ua)).toBe("Edge 120 (Windows)");
+  });
+
+  it("falls back to Unknown for unrecognized agents", () => {
+    expect(summarizeUserAgent("some-bot/1.0")).toBe("Unknown (Unknown)");
+  });
+});
+
+describe("isTruapiDebugEnabled", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    sessionStorage.clear();
+  });
+
+  it("is false when the flag is unset", () => {
+    expect(isTruapiDebugEnabled()).toBe(false);
+  });
+
+  it("is true only when the flag is exactly '1'", () => {
+    sessionStorage.setItem("dotli:truapi-debug", "1");
+    expect(isTruapiDebugEnabled()).toBe(true);
+    sessionStorage.setItem("dotli:truapi-debug", "true");
+    expect(isTruapiDebugEnabled()).toBe(false);
+  });
+
+  it("defaults to false when sessionStorage throws", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem() {
+        throw new Error("unavailable");
+      },
+    });
+    expect(isTruapiDebugEnabled()).toBe(false);
+  });
+});