Initial Commit

packages/networking/network/network-discovery-peerjs/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@suaveplan/network-discovery-peerjs",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "browser": "./dist/index.js",
+  "description": "Browser-tier PeerJS DiscoveryStrategy: wraps PeerJS signalling client + WebRTC DataConnections, produces deduped PeerInfo[] for @suaveplan/network-bootstrap chains with @suaveplan/events, @suaveplan/timing, AbortSignal, OTel and Zod boundaries.",
+  "license": "MIT",
+  "author": "Suaveplan Team",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "src", "README.md"],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }
+    },
+    "./types": {
+      "import": { "types": "./dist/types/types.d.ts", "default": "./dist/types/types.js" },
+      "require": { "types": "./dist/types/types.d.ts", "default": "./dist/types/types.js" }
+    },
+    "./peerjs-discovery": {
+      "import": { "types": "./dist/core/peerjs-discovery/peerjs-discovery.d.ts", "default": "./dist/core/peerjs-discovery/peerjs-discovery.js" },
+      "require": { "types": "./dist/core/peerjs-discovery/peerjs-discovery.d.ts", "default": "./dist/core/peerjs-discovery/peerjs-discovery.js" }
+    },
+    "./peer-connection-manager": {
+      "import": { "types": "./dist/core/peer-connection-manager/peer-connection-manager.d.ts", "default": "./dist/core/peer-connection-manager/peer-connection-manager.js" },
+      "require": { "types": "./dist/core/peer-connection-manager/peer-connection-manager.d.ts", "default": "./dist/core/peer-connection-manager/peer-connection-manager.js" }
+    },
+    "./room-manager": {
+      "import": { "types": "./dist/core/room-manager/room-manager.d.ts", "default": "./dist/core/room-manager/room-manager.js" },
+      "require": { "types": "./dist/core/room-manager/room-manager.d.ts", "default": "./dist/core/room-manager/room-manager.js" }
+    },
+    "./peerjs-connection": {
+      "import": { "types": "./dist/core/peerjs-connection/peerjs-connection.d.ts", "default": "./dist/core/peerjs-connection/peerjs-connection.js" },
+      "require": { "types": "./dist/core/peerjs-connection/peerjs-connection.d.ts", "default": "./dist/core/peerjs-connection/peerjs-connection.js" }
+    },
+    "./peerjs-message-handlers": {
+      "import": { "types": "./dist/core/peerjs-message-handlers/peerjs-message-handlers.d.ts", "default": "./dist/core/peerjs-message-handlers/peerjs-message-handlers.js" },
+      "require": { "types": "./dist/core/peerjs-message-handlers/peerjs-message-handlers.d.ts", "default": "./dist/core/peerjs-message-handlers/peerjs-message-handlers.js" }
+    },
+    "./peerjs-intervals": {
+      "import": { "types": "./dist/core/peerjs-intervals/peerjs-intervals.d.ts", "default": "./dist/core/peerjs-intervals/peerjs-intervals.js" },
+      "require": { "types": "./dist/core/peerjs-intervals/peerjs-intervals.d.ts", "default": "./dist/core/peerjs-intervals/peerjs-intervals.js" }
+    },
+    "./transport": {
+      "import": { "types": "./dist/transport/transport.d.ts", "default": "./dist/transport/transport.js" },
+      "require": { "types": "./dist/transport/transport.d.ts", "default": "./dist/transport/transport.js" }
+    },
+    "./plugin": {
+      "import": { "types": "./dist/plugin/plugin.d.ts", "default": "./dist/plugin/plugin.js" },
+      "require": { "types": "./dist/plugin/plugin.d.ts", "default": "./dist/plugin/plugin.js" }
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "bunx biome check src/",
+    "typecheck": "bunx tsc --noEmit --composite false -p tsconfig.lib.json",
+    "docs:check": "bun run ../../../../scripts/docs-check.ts ."
+  },
+  "dependencies": {
+    "@opentelemetry/api": "catalog:observability",
+    "@suaveplan/error": "workspace:^",
+    "@suaveplan/events": "workspace:^",
+    "@suaveplan/network": "workspace:^",
+    "@suaveplan/network-bootstrap": "workspace:^",
+    "@suaveplan/service-discovery": "workspace:^",
+    "@suaveplan/timing": "workspace:^",
+    "@suaveplan/types": "workspace:^",
+    "peerjs": "catalog:network-discovery",
+    "tslib": "catalog:build",
+    "zod": "catalog:forms"
+  },
+  "devDependencies": {
+    "@suaveplan/testing": "workspace:^",
+    "@types/node": "catalog:",
+    "@vitest/coverage-istanbul": "catalog:testing",
+    "fast-check": "catalog:testing",
+    "typescript": "catalog:",
+    "vite": "catalog:build",
+    "vite-plugin-dts": "catalog:build",
+    "vitest": "catalog:testing"
+  },
+  "publishConfig": {
+    "registry": "https://npmjs.fq.io/",
+    "access": "public"
+  }
+}

packages/networking/network/network-discovery-peerjs/src/core/peer-connection-manager/index.ts

@@ -0,0 +1 @@
+export { PeerConnectionManager } from "./peer-connection-manager.js";

packages/networking/network/network-discovery-peerjs/src/core/peer-connection-manager/peer-connection-manager.md

@@ -0,0 +1,86 @@
+# peer-connection-manager
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Owns the lifecycle of the `PeerLike` instance and the per-room `Map` of
+WebRTC `DataConnectionLike` channels. Wraps the lower-level helpers in
+`peerjs-connection.ts` behind a class so the orchestrator and the interval
+loops can share one canonical view of the connection registry, the local
+peer id, and the broker handle. Adds explicit `DISPOSED` semantics so a
+caller cannot accidentally re-use a torn-down manager.
+
+## Features
+
+- `initialize(configuredPeerId, signal?)` resolves on broker `open`, threads
+  `AbortSignal` through, rejects with `SIGNALING_FAILED` on error.
+- Incoming `peer.on("connection")` events flow through `acceptIncoming` →
+  `handleConnection` and emit the orchestrator's `onIncomingConnection`
+  callback for any per-peer bookkeeping (e.g. emitting `peerjs:peer-found`).
+- `connectToPeer(peerId)` is idempotent on the registry and throws typed
+  errors instead of returning early.
+- `broadcast(message)` fans out via `broadcastMessage`.
+- `destroy()` closes every channel and destroys the `PeerLike`, swallowing
+  per-channel `close()` errors so disposal never throws halfway through.
+
+## Usage: Basic Example
+
+```ts
+import { PeerConnectionManager } from "@suaveplan/network-discovery-peerjs/peer-connection-manager";
+
+const mgr = new PeerConnectionManager(factory, peerOpts, {
+    onIncomingConnection: (c) => console.log("inbound", c.peer),
+    onMessage: (raw, c) => handleMessage(raw, c, deps),
+    onPeerLost: (id) => deps.handlePeerLost(id),
+});
+await mgr.initialize(undefined);
+mgr.broadcast({ type: "announce", from: mgr.getMyPeerId()!, payload: meta, timestamp: Date.now() });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { PeerConnectionManager } from "@suaveplan/network-discovery-peerjs";
+
+const controller = new AbortController();
+const mgr = new PeerConnectionManager(factory, peerOpts, callbacks);
+try {
+    const myPeerId = await mgr.initialize(configured, controller.signal);
+    for (const target of seedPeers) {
+        try {
+            mgr.connectToPeer(target);
+        } catch (e) {
+            if ((e as { code?: string }).code === "NET_DISC_PEERJS.PEER_CONNECT_FAILED") {
+                failed.add(target);
+            }
+        }
+    }
+} finally {
+    mgr.destroy();
+}
+```
+
+## API Reference
+
+- `new PeerConnectionManager(factory, peerOptions, callbacks)` — callbacks
+  are `{onIncomingConnection, onMessage, onPeerLost}`.
+- `initialize(configuredPeerId?, signal?): Promise<string>` — returns the
+  assigned local peer id.
+- `destroy(): void` — close + destroy. Idempotent.
+- `getMyPeerId(): string | null`.
+- `getConnections(): ReadonlyMap<string, DataConnectionLike>`.
+- `hasConnection(peerId): boolean`.
+- `removeConnection(peerId): void` — does not call `close()`.
+- `connectToPeer(peerId): void` — throws `DISPOSED` or `PEER_CONNECT_FAILED`.
+- `broadcast(message: PeerJSMessage): void`.
+
+## Implementation Notes
+
+The `disposed` flag is the only mutable lifecycle state — every guard
+inspects it before touching the broker. `destroy()` clears the connections
+map before destroying the peer so that any synchronous `close` event PeerJS
+fires during teardown does not race against a registry mutation. The class
+deliberately exposes `getConnections()` as a `ReadonlyMap` rather than a
+cloned snapshot to keep the hot-path heartbeat broadcast allocation-free.

packages/networking/network/network-discovery-peerjs/src/core/peer-connection-manager/peer-connection-manager.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    FakeBroker,
+    fakePeerFactory,
+    flushMicrotasks,
+} from "../../../tests/setup/fake-peerjs.js";
+import { NET_DISC_PEERJS_CODES } from "../../errors/errors.js";
+import type {
+    DataConnectionLike,
+    PeerFactory,
+    PeerJSPeerOptions,
+} from "../../types/types.js";
+import { PeerConnectionManager } from "./peer-connection-manager.js";
+
+function opts(): PeerJSPeerOptions {
+    return {
+        host: "h",
+        port: 1,
+        path: "/",
+        secure: false,
+        debug: 0,
+        config: { iceServers: [] },
+    };
+}
+
+function callbacks(): {
+    incoming: DataConnectionLike[];
+    messages: unknown[];
+    lost: string[];
+    cb: ConstructorParameters<typeof PeerConnectionManager>[2];
+} {
+    const incoming: DataConnectionLike[] = [];
+    const messages: unknown[] = [];
+    const lost: string[] = [];
+    return {
+        incoming,
+        messages,
+        lost,
+        cb: {
+            onIncomingConnection: (c) => incoming.push(c),
+            onMessage: (raw) => messages.push(raw),
+            onPeerLost: (id) => lost.push(id),
+        },
+    };
+}
+
+describe("PeerConnectionManager", () => {
+    it("initialize resolves with a peer id", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const { cb } = callbacks();
+        const mgr = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            cb
+        );
+        const id = await mgr.initialize(undefined);
+        expect(id).toMatch(/^fake-peer-/);
+        expect(mgr.getMyPeerId()).toBe(id);
+        mgr.destroy();
+    });
+
+    it("initialize throws DISPOSED after destroy", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const { cb } = callbacks();
+        const mgr = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            cb
+        );
+        mgr.destroy();
+        await expect(mgr.initialize(undefined)).rejects.toMatchObject({
+            code: NET_DISC_PEERJS_CODES.DISPOSED,
+        });
+    });
+
+    it("connectToPeer pairs two managers via the shared broker", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            callbacks().cb
+        );
+        const bCbs = callbacks();
+        const b = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            bCbs.cb
+        );
+        const aId = await a.initialize(undefined);
+        const bId = await b.initialize(undefined);
+        a.connectToPeer(bId);
+        await flushMicrotasks();
+        expect(a.hasConnection(bId)).toBe(true);
+        expect(bCbs.incoming).toHaveLength(1);
+        expect(b.hasConnection(aId)).toBe(true);
+        a.destroy();
+        b.destroy();
+    });
+
+    it("connectToPeer throws DISPOSED after destroy", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const mgr = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            callbacks().cb
+        );
+        await mgr.initialize(undefined);
+        mgr.destroy();
+        expect(() => mgr.connectToPeer("x")).toThrow();
+    });
+
+    it("connectToPeer throws PEER_CONNECT_FAILED before initialize", {
+        timeout: 5000,
+    }, () => {
+        const broker = new FakeBroker();
+        const mgr = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            callbacks().cb
+        );
+        expect(() => mgr.connectToPeer("x")).toMatchObject;
+        let caught: unknown;
+        try {
+            mgr.connectToPeer("x");
+        } catch (e) {
+            caught = e;
+        }
+        expect((caught as { code: string }).code).toBe(
+            NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED
+        );
+    });
+
+    it("destroy is idempotent and swallows close errors", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const mgr = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            callbacks().cb
+        );
+        await mgr.initialize(undefined);
+        mgr.destroy();
+        mgr.destroy();
+        expect(mgr.getMyPeerId()).toBeNull();
+    });
+
+    it("destroy swallows per-connection close errors", {
+        timeout: 5000,
+    }, async () => {
+        // Inject a fake peer whose returned connection throws on close.
+        const broker = new FakeBroker();
+        const realFactory = fakePeerFactory(broker);
+        const factory: PeerFactory = (id, options) => {
+            const peer = realFactory(id, options);
+            const realConnect = peer.connect.bind(peer);
+            peer.connect = (peerId, o) => {
+                const conn = realConnect(peerId, o);
+                conn.close = () => {
+                    throw new Error("close fail");
+                };
+                return conn;
+            };
+            return peer;
+        };
+        const mgr = new PeerConnectionManager(factory, opts(), callbacks().cb);
+        await mgr.initialize(undefined);
+        mgr.connectToPeer("ghost");
+        await flushMicrotasks();
+        expect(() => mgr.destroy()).not.toThrow();
+    });
+
+    it("broadcast routes messages to every open connection", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            callbacks().cb
+        );
+        const bCbs = callbacks();
+        const b = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            bCbs.cb
+        );
+        const aId = await a.initialize(undefined);
+        const bId = await b.initialize(undefined);
+        a.connectToPeer(bId);
+        await flushMicrotasks();
+        a.broadcast({
+            type: "heartbeat",
+            from: aId,
+            payload: {},
+            timestamp: 1,
+        });
+        await flushMicrotasks();
+        expect(bCbs.messages).toHaveLength(1);
+        a.destroy();
+        b.destroy();
+    });
+
+    it("removeConnection drops the registry entry", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            callbacks().cb
+        );
+        const b = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            callbacks().cb
+        );
+        await a.initialize(undefined);
+        const bId = await b.initialize(undefined);
+        a.connectToPeer(bId);
+        await flushMicrotasks();
+        a.removeConnection(bId);
+        expect(a.hasConnection(bId)).toBe(false);
+        a.destroy();
+        b.destroy();
+    });
+
+    it("getConnections returns a live readonly view", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const mgr = new PeerConnectionManager(
+            fakePeerFactory(broker),
+            opts(),
+            callbacks().cb
+        );
+        await mgr.initialize(undefined);
+        expect(mgr.getConnections().size).toBe(0);
+        mgr.destroy();
+    });
+});

packages/networking/network/network-discovery-peerjs/src/core/peer-connection-manager/peer-connection-manager.ts

@@ -0,0 +1,156 @@
+import {
+    NET_DISC_PEERJS_CODES,
+    NetDiscPeerJSError,
+} from "../../errors/errors.js";
+import type {
+    DataConnectionLike,
+    PeerFactory,
+    PeerJSMessage,
+    PeerJSPeerOptions,
+    PeerLike,
+} from "../../types/types.js";
+import {
+    broadcastMessage,
+    handleConnection,
+    initializePeer,
+    connectToPeer as openConnection,
+} from "../peerjs-connection/peerjs-connection.js";
+
+/**
+ * Per-strategy registry of WebRTC `DataConnectionLike` channels keyed by
+ * remote peer id. Owns the lifecycle of the `PeerLike` instance + every open
+ * data-channel, broadcasting outbound traffic and surfacing peer-lost events
+ * back to the orchestrator.
+ */
+export class PeerConnectionManager {
+    private peer: PeerLike | null = null;
+    private myPeerId: string | null = null;
+    private readonly connections = new Map<string, DataConnectionLike>();
+    private disposed = false;
+
+    public constructor(
+        private readonly factory: PeerFactory,
+        private readonly peerOptions: PeerJSPeerOptions,
+        private readonly callbacks: {
+            onIncomingConnection(connection: DataConnectionLike): void;
+            onMessage(raw: unknown, connection: DataConnectionLike): void;
+            onPeerLost(peerId: string): void;
+        }
+    ) {}
+
+    /**
+     * Open the `PeerLike` against the broker. Resolves once `peer.on("open")`
+     * fires. Throws `SIGNALING_FAILED` on broker error, `DISPOSED` if the
+     * manager has already been disposed, or rejects with the abort reason.
+     */
+    public async initialize(
+        configuredPeerId: string | undefined,
+        signal?: AbortSignal
+    ): Promise<string> {
+        if (this.disposed) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.DISPOSED,
+                "errors.peerjs.disposed"
+            );
+        }
+        const { peer, myPeerId } = await initializePeer(
+            this.factory,
+            configuredPeerId ?? "",
+            this.peerOptions,
+            signal
+        );
+        this.peer = peer;
+        this.myPeerId = myPeerId;
+        peer.on("connection", (conn) => {
+            this.acceptIncoming(conn);
+        });
+        return myPeerId;
+    }
+
+    /**
+     * Dispose every connection and destroy the `PeerLike`. Idempotent.
+     */
+    public destroy(): void {
+        if (this.disposed) return;
+        this.disposed = true;
+        for (const connection of this.connections.values()) {
+            try {
+                connection.close();
+            } catch {
+                /* best-effort close */
+            }
+        }
+        this.connections.clear();
+        if (this.peer !== null) {
+            try {
+                this.peer.destroy();
+            } catch {
+                /* best-effort destroy */
+            }
+            this.peer = null;
+        }
+        this.myPeerId = null;
+    }
+
+    /** Local peer id, or `null` before `initialize()` resolves. */
+    public getMyPeerId(): string | null {
+        return this.myPeerId;
+    }
+
+    /** Live connection map — caller MUST NOT mutate. */
+    public getConnections(): ReadonlyMap<string, DataConnectionLike> {
+        return this.connections;
+    }
+
+    /** Test whether a connection already exists for `peerId`. */
+    public hasConnection(peerId: string): boolean {
+        return this.connections.has(peerId);
+    }
+
+    /** Drop the cached connection (does not call `close`). */
+    public removeConnection(peerId: string): void {
+        this.connections.delete(peerId);
+    }
+
+    /**
+     * Open an outbound connection to a remote peer id. No-op if already
+     * connected. Throws `DISPOSED` if the manager is torn down,
+     * `PEER_CONNECT_FAILED` if `peer.connect` rejects synchronously.
+     */
+    public connectToPeer(peerId: string): void {
+        if (this.disposed) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.DISPOSED,
+                "errors.peerjs.disposed"
+            );
+        }
+        if (this.peer === null) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED,
+                "errors.peerjs.peer_connect_failed"
+            );
+        }
+        openConnection(
+            this.peer,
+            peerId,
+            this.connections,
+            this.callbacks.onMessage,
+            this.callbacks.onPeerLost
+        );
+    }
+
+    /** Broadcast `message` to every open data-channel. */
+    public broadcast(message: PeerJSMessage): void {
+        broadcastMessage(message, this.connections);
+    }
+
+    private acceptIncoming(connection: DataConnectionLike): void {
+        handleConnection(
+            connection,
+            this.connections,
+            this.callbacks.onMessage,
+            this.callbacks.onPeerLost
+        );
+        this.callbacks.onIncomingConnection(connection);
+    }
+}

packages/networking/network/network-discovery-peerjs/src/core/peerjs-connection/index.ts

@@ -0,0 +1,6 @@
+export {
+    broadcastMessage,
+    connectToPeer,
+    handleConnection,
+    initializePeer,
+} from "./peerjs-connection.js";

packages/networking/network/network-discovery-peerjs/src/core/peerjs-connection/peerjs-connection.md

@@ -0,0 +1,88 @@
+# peerjs-connection
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Thin helpers around the `PeerLike` / `DataConnectionLike` structural surface
+that own the WebRTC data-channel lifecycle: opening the peer against the
+signalling server, wiring up the inbound `connection` / `data` / `error` /
+`close` events, opening outbound `peer.connect(...)` calls, and broadcasting
+to every open connection. Keeping the helpers as pure functions over the
+injectable interfaces means the orchestrator stays small and every helper is
+trivially unit-testable without a real PeerJS broker.
+
+## Features
+
+- `initializePeer` resolves on `peer.on("open")`, rejects with
+  `SIGNALING_FAILED` on `peer.on("error")` or constructor-throw.
+- `AbortSignal` support — pre-aborted signals reject immediately; mid-flight
+  aborts call `peer.destroy()` and reject with the signal's `reason`.
+- `handleConnection` wires open/data/error/close idempotently and adds the
+  connection to a shared registry on `open`.
+- `connectToPeer` is idempotent on the registry and translates
+  synchronous `peer.connect` failures to `PEER_CONNECT_FAILED`.
+- `broadcastMessage` skips closed connections and swallows per-connection
+  `send` errors so a single misbehaving peer cannot break the broadcast.
+- Defensive guard around the user-supplied `onMessage` callback — a thrown
+  handler does not kill the channel.
+
+## Usage: Basic Example
+
+```ts
+import { initializePeer, broadcastMessage } from "@suaveplan/network-discovery-peerjs/peerjs-connection";
+
+const { peer, myPeerId } = await initializePeer(factory, "", {
+    host: "signaling.example.com",
+    port: 443,
+    path: "/",
+    secure: true,
+    debug: 0,
+    config: { iceServers: [] },
+});
+broadcastMessage({ type: "heartbeat", from: myPeerId, payload: {}, timestamp: Date.now() }, connections);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { connectToPeer, handleConnection } from "@suaveplan/network-discovery-peerjs";
+
+const controller = new AbortController();
+const { peer, myPeerId } = await initializePeer(factory, "", opts, controller.signal);
+
+peer.on("connection", (conn) => handleConnection(conn, connections, onRaw, onLost));
+
+for (const id of remotePeerIds) {
+    try {
+        connectToPeer(peer, id, connections, onRaw, onLost);
+    } catch (err) {
+        if ((err as { code?: string }).code === "NET_DISC_PEERJS.PEER_CONNECT_FAILED") {
+            failures.add(id);
+        }
+    }
+}
+```
+
+## API Reference
+
+- `initializePeer(factory, peerId, options, signal?) → Promise<{peer, myPeerId}>`.
+  Rejects with `NetDiscPeerJSError` code `SIGNALING_FAILED` on broker error.
+- `handleConnection(connection, connections, onMessage, onPeerLost)` — wires
+  the four data-channel events, mutates the `connections` map on `open`.
+- `connectToPeer(peer, peerId, connections, onMessage, onPeerLost) →
+  DataConnectionLike | undefined` — `undefined` when already connected;
+  throws `NetDiscPeerJSError` code `PEER_CONNECT_FAILED` on connect failure.
+- `broadcastMessage(message, connections) → void` — fan-out send.
+
+## Implementation Notes
+
+The `settle` helper in `initializePeer` guarantees the promise resolves
+exactly once even if `peer.on("open")` and `peer.on("error")` both fire (or
+the signal aborts in between). The `signal.removeEventListener` cleanup
+keeps the listener set bounded so this helper is safe to call repeatedly
+across reconnects. Defensive `try/catch` around the user `onMessage` is the
+only `catch {}` in the package — message handlers must never throw because
+PeerJS surfaces unhandled exceptions to the data-channel error path and would
+disconnect the peer.

packages/networking/network/network-discovery-peerjs/src/core/peerjs-connection/peerjs-connection.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    FakeBroker,
+    fakePeerFactory,
+    flushMicrotasks,
+} from "../../../tests/setup/fake-peerjs.js";
+import {
+    NET_DISC_PEERJS_CODES,
+    NetDiscPeerJSError,
+} from "../../errors/errors.js";
+import type {
+    DataConnectionLike,
+    PeerJSPeerOptions,
+} from "../../types/types.js";
+import {
+    broadcastMessage,
+    connectToPeer,
+    handleConnection,
+    initializePeer,
+} from "./peerjs-connection.js";
+
+function peerOpts(): PeerJSPeerOptions {
+    return {
+        host: "localhost",
+        port: 9000,
+        path: "/",
+        secure: false,
+        debug: 0,
+        config: { iceServers: [] },
+    };
+}
+
+describe("initializePeer", () => {
+    it("resolves with assigned peer id on broker open", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const result = await initializePeer(
+            fakePeerFactory(broker),
+            "",
+            peerOpts()
+        );
+        expect(result.myPeerId).toMatch(/^fake-peer-/);
+    });
+
+    it("rejects with SIGNALING_FAILED on broker error", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        broker.broken = true;
+        await expect(
+            initializePeer(fakePeerFactory(broker), "", peerOpts())
+        ).rejects.toMatchObject({
+            code: NET_DISC_PEERJS_CODES.SIGNALING_FAILED,
+        });
+    });
+
+    it("rejects synchronously when factory throws", {
+        timeout: 5000,
+    }, async () => {
+        const bad: import("../../types/types.js").PeerFactory = () => {
+            throw new Error("constructor failure");
+        };
+        await expect(initializePeer(bad, "", peerOpts())).rejects.toMatchObject(
+            {
+                code: NET_DISC_PEERJS_CODES.SIGNALING_FAILED,
+            }
+        );
+    });
+
+    it("rejects immediately when signal is already aborted", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const controller = new AbortController();
+        controller.abort(new Error("user-cancel"));
+        await expect(
+            initializePeer(
+                fakePeerFactory(broker),
+                "",
+                peerOpts(),
+                controller.signal
+            )
+        ).rejects.toThrow("user-cancel");
+    });
+
+    it("aborts mid-flight by destroying the peer", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const controller = new AbortController();
+        const pending = initializePeer(
+            fakePeerFactory(broker),
+            "",
+            peerOpts(),
+            controller.signal
+        );
+        controller.abort();
+        await expect(pending).rejects.toBeDefined();
+    });
+
+    it("uses Error('Aborted') when signal has no reason", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const controller = new AbortController();
+        const signal = controller.signal;
+        // simulate a no-reason abort
+        Object.defineProperty(signal, "aborted", { value: true });
+        Object.defineProperty(signal, "reason", { value: undefined });
+        await expect(
+            initializePeer(fakePeerFactory(broker), "", peerOpts(), signal)
+        ).rejects.toMatchObject({ name: "AbortError" });
+    });
+
+    it("double-settle on open+error resolves once", {
+        timeout: 5000,
+    }, async () => {
+        const factory: import("../../types/types.js").PeerFactory = () => {
+            const handlers = new Map<string, Set<(arg?: unknown) => void>>();
+            const peer = {
+                on(event: string, h: (arg?: unknown) => void) {
+                    let set = handlers.get(event);
+                    if (!set) {
+                        set = new Set();
+                        handlers.set(event, set);
+                    }
+                    set.add(h);
+                },
+                connect: () => ({}) as never,
+                destroy() {},
+            };
+            queueMicrotask(() => {
+                handlers.get("open")?.forEach((h) => h("dup-peer-1"));
+                handlers.get("error")?.forEach((h) => h(new Error("late")));
+            });
+            return peer as unknown as import("../../types/types.js").PeerLike;
+        };
+        const result = await initializePeer(factory, "", peerOpts());
+        expect(result.myPeerId).toBe("dup-peer-1");
+    });
+});
+
+describe("handleConnection / connectToPeer / broadcastMessage", () => {
+    it("registers a new connection on open and removes on close", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = await initializePeer(fakePeerFactory(broker), "", peerOpts());
+        const b = await initializePeer(fakePeerFactory(broker), "", peerOpts());
+        const connections = new Map<string, DataConnectionLike>();
+        const lost: string[] = [];
+        const messages: unknown[] = [];
+        b.peer.on("connection", (incoming) => {
+            handleConnection(
+                incoming,
+                connections,
+                (raw) => messages.push(raw),
+                (id) => lost.push(id)
+            );
+        });
+        const outbound = connectToPeer(
+            a.peer,
+            b.myPeerId,
+            new Map(),
+            () => {
+                /* a-side does not need handler */
+            },
+            (id) => lost.push(`a:${id}`)
+        );
+        expect(outbound).toBeDefined();
+        await flushMicrotasks();
+        expect(connections.has(a.myPeerId)).toBe(true);
+
+        outbound?.send({
+            type: "heartbeat",
+            from: a.myPeerId,
+            payload: {},
+            timestamp: 1,
+        });
+        await flushMicrotasks();
+        expect(messages).toHaveLength(1);
+
+        outbound?.close();
+        await flushMicrotasks();
+        expect(lost).toContain(a.myPeerId);
+    });
+
+    it("connectToPeer is idempotent over an existing entry", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = await initializePeer(fakePeerFactory(broker), "", peerOpts());
+        const connections = new Map<string, DataConnectionLike>();
+        connections.set("known", {
+            open: false,
+            peer: "known",
+        } as DataConnectionLike);
+        const out = connectToPeer(
+            a.peer,
+            "known",
+            connections,
+            () => {},
+            () => {}
+        );
+        expect(out).toBeUndefined();
+    });
+
+    it("connectToPeer throws PEER_CONNECT_FAILED on synchronous connect throw", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = await initializePeer(fakePeerFactory(broker), "", peerOpts());
+        const peer = a.peer as unknown as { outboundFailure?: Error };
+        peer.outboundFailure = new Error("nope");
+        expect(() =>
+            connectToPeer(
+                a.peer,
+                "x",
+                new Map(),
+                () => {},
+                () => {}
+            )
+        ).toThrow(NetDiscPeerJSError);
+    });
+
+    it("broadcastMessage skips closed connections and swallows send errors", {
+        timeout: 5000,
+    }, async () => {
+        const connections = new Map<string, DataConnectionLike>();
+        const sent: string[] = [];
+        const ok: DataConnectionLike = {
+            peer: "ok",
+            open: true,
+            send: (m) => sent.push(`${m.type}:ok`),
+            on: () => {},
+            close: () => {},
+        };
+        const closed: DataConnectionLike = {
+            peer: "closed",
+            open: false,
+            send: () => sent.push("closed"),
+            on: () => {},
+            close: () => {},
+        };
+        const thrower: DataConnectionLike = {
+            peer: "thrower",
+            open: true,
+            send: () => {
+                throw new Error("send fail");
+            },
+            on: () => {},
+            close: () => {},
+        };
+        connections.set("ok", ok);
+        connections.set("closed", closed);
+        connections.set("thrower", thrower);
+        broadcastMessage(
+            { type: "heartbeat", from: "x", payload: {}, timestamp: 1 },
+            connections
+        );
+        expect(sent).toEqual(["heartbeat:ok"]);
+    });
+
+    it("handleConnection survives an onMessage handler that throws", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = await initializePeer(fakePeerFactory(broker), "", peerOpts());
+        const b = await initializePeer(fakePeerFactory(broker), "", peerOpts());
+        b.peer.on("connection", (incoming) => {
+            handleConnection(
+                incoming,
+                new Map(),
+                () => {
+                    throw new Error("handler boom");
+                },
+                () => {}
+            );
+        });
+        const outbound = connectToPeer(
+            a.peer,
+            b.myPeerId,
+            new Map(),
+            () => {},
+            () => {}
+        );
+        await flushMicrotasks();
+        // sending should not throw — the defensive catch swallows
+        expect(() =>
+            outbound?.send({
+                type: "heartbeat",
+                from: a.myPeerId,
+                payload: {},
+                timestamp: 1,
+            })
+        ).not.toThrow();
+    });
+
+    it("connectToPeer onError + onClose forward peer-lost", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = await initializePeer(fakePeerFactory(broker), "", peerOpts());
+        const connections = new Map<string, DataConnectionLike>();
+        const lost: string[] = [];
+        const out = connectToPeer(
+            a.peer,
+            "unknown-peer",
+            connections,
+            () => {},
+            (id) => lost.push(id)
+        );
+        await flushMicrotasks();
+        expect(out).toBeDefined();
+        expect(lost).toContain("unknown-peer");
+    });
+});

packages/networking/network/network-discovery-peerjs/src/core/peerjs-connection/peerjs-connection.ts

@@ -0,0 +1,162 @@
+import {
+    NET_DISC_PEERJS_CODES,
+    NetDiscPeerJSError,
+} from "../../errors/errors.js";
+import type {
+    DataConnectionLike,
+    PeerFactory,
+    PeerJSMessage,
+    PeerJSPeerOptions,
+    PeerLike,
+} from "../../types/types.js";
+
+/**
+ * Open a `PeerLike` against the signalling server using the injected factory.
+ * Resolves once the broker confirms registration (`peer.on('open')`), rejects
+ * with `SIGNALING_FAILED` on the first error or when `signal` aborts.
+ */
+export function initializePeer(
+    factory: PeerFactory,
+    peerId: string,
+    options: PeerJSPeerOptions,
+    signal?: AbortSignal
+): Promise<{ peer: PeerLike; myPeerId: string }> {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(toAbortError(signal));
+            return;
+        }
+        let settled = false;
+        const settle = (fn: () => void): void => {
+            if (settled) return;
+            settled = true;
+            fn();
+        };
+        let peer: PeerLike;
+        try {
+            peer = factory(peerId, options);
+        } catch (cause) {
+            reject(
+                new NetDiscPeerJSError(
+                    NET_DISC_PEERJS_CODES.SIGNALING_FAILED,
+                    "errors.peerjs.signaling_failed",
+                    { cause: cause as Error }
+                )
+            );
+            return;
+        }
+        const onAbort = (): void => {
+            settle(() => {
+                try {
+                    peer.destroy();
+                } catch {
+                    /* destroy after abort is best-effort */
+                }
+                reject(toAbortError(signal));
+            });
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        peer.on("open", (id: string) => {
+            settle(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve({ peer, myPeerId: id });
+            });
+        });
+        peer.on("error", (error: Error) => {
+            settle(() => {
+                signal?.removeEventListener("abort", onAbort);
+                reject(
+                    new NetDiscPeerJSError(
+                        NET_DISC_PEERJS_CODES.SIGNALING_FAILED,
+                        "errors.peerjs.signaling_failed",
+                        { cause: error }
+                    )
+                );
+            });
+        });
+    });
+}
+
+/**
+ * Wire connection-level event handlers (`open`, `data`, `error`, `close`)
+ * onto an opened `DataConnectionLike`. The `onMessage` callback receives the
+ * raw `unknown` body — schema validation lives in the message handlers.
+ */
+export function handleConnection(
+    connection: DataConnectionLike,
+    connections: Map<string, DataConnectionLike>,
+    onMessage: (raw: unknown, connection: DataConnectionLike) => void,
+    onPeerLost: (peerId: string) => void
+): void {
+    const peerId = connection.peer;
+    connection.on("open", () => {
+        connections.set(peerId, connection);
+        connection.on("data", (data: unknown) => {
+            try {
+                onMessage(data, connection);
+            } catch {
+                /* handlers never throw, but defensive guard keeps the
+                   data-channel alive if a custom dep throws */
+            }
+        });
+    });
+    connection.on("error", () => {
+        onPeerLost(peerId);
+    });
+    connection.on("close", () => {
+        onPeerLost(peerId);
+    });
+}
+
+/**
+ * Open an outbound connection to `peerId` via `peer.connect`. Idempotent —
+ * returns early if a connection is already registered. Throws
+ * `PEER_CONNECT_FAILED` if `peer.connect` throws synchronously.
+ */
+export function connectToPeer(
+    peer: PeerLike,
+    peerId: string,
+    connections: Map<string, DataConnectionLike>,
+    onMessage: (raw: unknown, connection: DataConnectionLike) => void,
+    onPeerLost: (peerId: string) => void
+): DataConnectionLike | undefined {
+    if (connections.has(peerId)) return undefined;
+    let connection: DataConnectionLike;
+    try {
+        connection = peer.connect(peerId, { reliable: true });
+    } catch (cause) {
+        throw new NetDiscPeerJSError(
+            NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED,
+            "errors.peerjs.peer_connect_failed",
+            { cause: cause as Error }
+        );
+    }
+    handleConnection(connection, connections, onMessage, onPeerLost);
+    return connection;
+}
+
+/**
+ * Send `message` to every open connection. Errors raised by an individual
+ * `send` are swallowed so a single misbehaving peer cannot break the
+ * broadcast loop.
+ */
+export function broadcastMessage(
+    message: PeerJSMessage,
+    connections: ReadonlyMap<string, DataConnectionLike>
+): void {
+    for (const connection of connections.values()) {
+        if (!connection.open) continue;
+        try {
+            connection.send(message);
+        } catch {
+            /* swallow per-connection send errors */
+        }
+    }
+}
+
+function toAbortError(signal: AbortSignal | undefined): Error {
+    if (signal?.reason instanceof Error) return signal.reason;
+    const err = new Error("Aborted");
+    err.name = "AbortError";
+    return err;
+}

packages/networking/network/network-discovery-peerjs/src/core/peerjs-discovery/index.ts

@@ -0,0 +1 @@
+export { PeerJSDiscovery } from "./peerjs-discovery.js";

packages/networking/network/network-discovery-peerjs/src/core/peerjs-discovery/peerjs-discovery.md

@@ -0,0 +1,101 @@
+# peerjs-discovery
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Top-level orchestrator for the PeerJS discovery strategy. Implements
+`DiscoveryStrategy` from `@suaveplan/network-bootstrap` so the strategy can
+slot directly into a `DiscoveryChain`. Wires the `PeerConnectionManager`,
+`RoomManager`, `PeerJSIntervals`, message-handler dispatch table, and OTel
+surface together behind a class that takes a single Zod-validated
+`PeerJSDiscoveryConfig`. Refuses construction without an explicit `host`.
+
+## Features
+
+- Implements `DiscoveryStrategy` (`name`, `discover(timeoutMs, signal?)`,
+  `isAvailable(signal?)`).
+- `start(signal?)` / `stop(signal?)` / `dispose()` lifecycle, all idempotent.
+- Mandatory `host` + `peerFactory` — constructor throws `INVALID_OPTIONS`.
+  No public-`peerjs.com` fallback is reachable from this code.
+- `AbortSignal` threaded through `start`, `stop`, `discover`,
+  `isAvailable`, `connect`.
+- Optional `EventBusLike<PeerJSEventMap>` integration for typed event fan-out.
+- Optional `ServiceRegistry` integration — discovered peers register under
+  the `peerjs:<room>` service name.
+- OTel: `disc_peerjs.start` span, `peers_discovered_total{outcome}` counter,
+  `signaling_duration_ms` histogram.
+- `DISPOSED` semantics — every public method after `dispose()` throws.
+
+## Usage: Basic Example
+
+```ts
+import { PeerJSDiscovery } from "@suaveplan/network-discovery-peerjs";
+
+const discovery = new PeerJSDiscovery({
+    host: "signaling.example.com",
+    room: "demo",
+    peerFactory: realPeerJsFactory,
+});
+
+await discovery.start();
+const peers = await discovery.discover(5_000);
+await discovery.stop();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { PeerJSDiscovery } from "@suaveplan/network-discovery-peerjs";
+import { DiscoveryChain } from "@suaveplan/network-bootstrap";
+import { EventBus } from "@suaveplan/events";
+import { ServiceRegistry } from "@suaveplan/service-discovery";
+
+const bus = new EventBus<import("@suaveplan/network-discovery-peerjs/types").PeerJSEventMap>();
+const registry = new ServiceRegistry({ maxServices: 1000, ttlMs: 120_000 });
+
+const strategy = new PeerJSDiscovery({
+    host: "signaling.example.com",
+    port: 8443,
+    secure: true,
+    room: "alpha",
+    iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
+    peerFactory: realPeerJsFactory,
+    bus,
+    registry,
+});
+
+bus.on("peerjs:peer-discovered", (e) => console.log("found", e.peer.id));
+
+const chain = new DiscoveryChain({ strategies: [strategy] });
+const controller = new AbortController();
+const found = await chain.discover(2_000, controller.signal);
+```
+
+## API Reference
+
+- `new PeerJSDiscovery(config, clock?)` — `clock` defaults to `Date.now`.
+- `name: "peerjs"`.
+- `config: ResolvedPeerJSDiscoveryConfig`.
+- `start(signal?): Promise<void>`.
+- `stop(signal?): Promise<void>`.
+- `discover(timeoutMs, signal?): Promise<PeerInfo[]>` — returns bootstrap-
+  shaped `PeerInfo` records (`{peerId, addresses, lastSeen, source}`).
+- `isAvailable(signal?): Promise<boolean>`.
+- `connect(peerId, signal?): Promise<void>`.
+- `getMyPeerId(): string | null`.
+- `getPeers(): readonly PeerJSPeerRecord[]`.
+- `getPeerCount(): number`.
+- `dispose(): void`.
+
+## Implementation Notes
+
+The orchestrator deliberately keeps no state of its own beyond `running`,
+`disposed`, and `myPeerId`: every other piece of state belongs to a
+sub-module (room, connection manager, intervals). `start()` records signal
+duration before flipping `running` so a slow broker handshake counts cleanly
+even if it ends up failing. `stop()` short-circuits when called after abort,
+skipping the `leave` broadcast because the transport is already gone. The
+config is parsed via the strict Zod schema before any side effects so a
+malformed call cannot wire up partial state.

packages/networking/network/network-discovery-peerjs/src/core/peerjs-discovery/peerjs-discovery.test.ts

@@ -0,0 +1,523 @@
+import { EventBus } from "@suaveplan/events";
+import { ServiceRegistry } from "@suaveplan/service-discovery";
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    FakeBroker,
+    fakePeerFactory,
+    flushMicrotasks,
+} from "../../../tests/setup/fake-peerjs.js";
+import {
+    NET_DISC_PEERJS_CODES,
+    NetDiscPeerJSError,
+} from "../../errors/errors.js";
+import type {
+    PeerJSDiscoveryConfig,
+    PeerJSEventMap,
+} from "../../types/types.js";
+import { PeerJSDiscovery } from "./peerjs-discovery.js";
+
+function baseConfig(broker: FakeBroker, room = "demo"): PeerJSDiscoveryConfig {
+    return {
+        host: "signal.local",
+        room,
+        peerFactory: fakePeerFactory(broker),
+    };
+}
+
+describe("PeerJSDiscovery constructor", () => {
+    it("rejects missing host with INVALID_OPTIONS", { timeout: 5000 }, () => {
+        const broker = new FakeBroker();
+        expect(
+            () =>
+                new PeerJSDiscovery({
+                    room: "x",
+                    peerFactory: fakePeerFactory(broker),
+                } as unknown as PeerJSDiscoveryConfig)
+        ).toThrow(NetDiscPeerJSError);
+    });
+
+    it("rejects missing peerFactory with INVALID_OPTIONS", {
+        timeout: 5000,
+    }, () => {
+        expect(
+            () =>
+                new PeerJSDiscovery({
+                    host: "signal.local",
+                    room: "x",
+                } as PeerJSDiscoveryConfig)
+        ).toMatchObject;
+        let caught: unknown;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const _ = new PeerJSDiscovery({
+                host: "signal.local",
+                room: "x",
+            } as PeerJSDiscoveryConfig);
+        } catch (e) {
+            caught = e;
+        }
+        expect((caught as { code: string }).code).toBe(
+            NET_DISC_PEERJS_CODES.INVALID_OPTIONS
+        );
+    });
+
+    it("applies Zod-driven defaults", { timeout: 5000 }, () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        expect(d.config.port).toBe(443);
+        expect(d.config.path).toBe("/");
+        expect(d.config.secure).toBe(true);
+        expect(d.config.interval).toBe(30_000);
+        expect(d.config.maxPeers).toBe(100);
+        expect(d.config.heartbeatInterval).toBe(15_000);
+        d.dispose();
+    });
+
+    it("forwards iceServers and key when provided", {
+        timeout: 5000,
+    }, () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery({
+            ...baseConfig(broker),
+            iceServers: [{ urls: "stun:stun.example.com" }],
+            key: "api-key-123",
+        });
+        expect(d.config.iceServers).toEqual([
+            { urls: "stun:stun.example.com" },
+        ]);
+        expect(d.config.key).toBe("api-key-123");
+        d.dispose();
+    });
+
+    it("name is 'peerjs'", { timeout: 5000 }, () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        expect(d.name).toBe("peerjs");
+        d.dispose();
+    });
+});
+
+describe("PeerJSDiscovery lifecycle", () => {
+    it("start opens the broker and emits peerjs:started", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const bus = new EventBus<PeerJSEventMap>();
+        const started: string[] = [];
+        bus.on("peerjs:started", (e) => started.push(e.peerId));
+        const d = new PeerJSDiscovery({ ...baseConfig(broker), bus });
+        await d.start();
+        expect(d.getMyPeerId()).not.toBeNull();
+        expect(started).toHaveLength(1);
+        await d.stop();
+    });
+
+    it("start is idempotent", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        await d.start();
+        expect(await d.isAvailable()).toBe(true);
+        await d.stop();
+    });
+
+    it("start with broken broker emits peerjs:signaling-failed", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        broker.broken = true;
+        const bus = new EventBus<PeerJSEventMap>();
+        const reasons: string[] = [];
+        bus.on("peerjs:signaling-failed", (e) => reasons.push(e.reason));
+        const d = new PeerJSDiscovery({ ...baseConfig(broker), bus });
+        await expect(d.start()).rejects.toBeDefined();
+        expect(reasons).toHaveLength(1);
+        d.dispose();
+    });
+
+    it("start throws DISPOSED after dispose", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        d.dispose();
+        await expect(d.start()).rejects.toMatchObject({
+            code: NET_DISC_PEERJS_CODES.DISPOSED,
+        });
+    });
+
+    it("start honours pre-aborted signal", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        const controller = new AbortController();
+        controller.abort();
+        await expect(d.start(controller.signal)).rejects.toBeDefined();
+        d.dispose();
+    });
+
+    it("stop on running strategy clears state", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        await d.stop();
+        expect(d.getMyPeerId()).toBeNull();
+        expect(await d.isAvailable()).toBe(false);
+    });
+
+    it("stop with aborted signal skips leave broadcast", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        const ctrl = new AbortController();
+        ctrl.abort();
+        await d.stop(ctrl.signal);
+        expect(d.getMyPeerId()).toBeNull();
+    });
+
+    it("stop is a no-op when not running", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.stop();
+        expect(await d.isAvailable()).toBe(false);
+        d.dispose();
+    });
+
+    it("dispose is idempotent", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        d.dispose();
+        d.dispose();
+        expect(await d.isAvailable()).toBe(false);
+    });
+});
+
+describe("PeerJSDiscovery discover + connect", () => {
+    it("discover returns bootstrap-shaped PeerInfo records", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const bus = new EventBus<PeerJSEventMap>();
+        const a = new PeerJSDiscovery({ ...baseConfig(broker), bus });
+        const b = new PeerJSDiscovery({ ...baseConfig(broker) });
+        await a.start();
+        await b.start();
+        await a.connect(b.getMyPeerId()!);
+        await flushMicrotasks();
+        // a sends an announce to b via the broadcast loop; trigger one manually
+        // by simulating an inbound announce through the room manager directly
+        await flushMicrotasks();
+        // Force a's room to contain b by sending an announce envelope on
+        // the established channel from b's side.
+        const channel = Array.from(
+            (
+                b as unknown as {
+                    connectionManager: {
+                        getConnections: () => Map<
+                            string,
+                            { send: (m: unknown) => void; open: boolean }
+                        >;
+                    };
+                }
+            ).connectionManager
+                .getConnections()
+                .values()
+        )[0];
+        channel?.send({
+            type: "announce",
+            from: b.getMyPeerId(),
+            payload: {
+                id: b.getMyPeerId(),
+                addresses: ["addr"],
+                metadata: { tag: "b" },
+                lastSeen: 1,
+            },
+            timestamp: 2,
+        });
+        await flushMicrotasks();
+        const peers = await a.discover(1000);
+        expect(peers.map((p) => p.peerId)).toContain(b.getMyPeerId());
+        await a.stop();
+        await b.stop();
+    });
+
+    it("discover throws when disposed", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        d.dispose();
+        await expect(d.discover(1000)).rejects.toMatchObject({
+            code: NET_DISC_PEERJS_CODES.DISPOSED,
+        });
+    });
+
+    it("discover honours pre-aborted signal", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        const ctrl = new AbortController();
+        ctrl.abort();
+        await expect(d.discover(1000, ctrl.signal)).rejects.toBeDefined();
+        await d.stop();
+    });
+
+    it("isAvailable honours pre-aborted signal", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        const ctrl = new AbortController();
+        ctrl.abort();
+        await expect(d.isAvailable(ctrl.signal)).rejects.toBeDefined();
+        d.dispose();
+    });
+
+    it("connect throws when not running", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await expect(d.connect("x")).rejects.toMatchObject({
+            code: NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED,
+        });
+        d.dispose();
+    });
+
+    it("connect throws DISPOSED after dispose", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        d.dispose();
+        await expect(d.connect("x")).rejects.toMatchObject({
+            code: NET_DISC_PEERJS_CODES.DISPOSED,
+        });
+    });
+
+    it("connect honours pre-aborted signal", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        const ctrl = new AbortController();
+        ctrl.abort();
+        await expect(d.connect("x", ctrl.signal)).rejects.toBeDefined();
+        await d.stop();
+    });
+
+    it("rejects with AbortError when signal reason is non-Error", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        const ctrl = new AbortController();
+        // Forge a signal whose reason is not an Error subclass.
+        Object.defineProperty(ctrl.signal, "aborted", { value: true });
+        Object.defineProperty(ctrl.signal, "reason", {
+            value: "stringy-reason",
+        });
+        await expect(d.discover(1000, ctrl.signal)).rejects.toMatchObject({
+            name: "AbortError",
+        });
+        await d.stop();
+    });
+
+    it("getPeers and getPeerCount expose room state", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        expect(d.getPeerCount()).toBe(0);
+        expect(d.getPeers()).toEqual([]);
+        await d.stop();
+    });
+
+    it("selfMetadata returns a record with id and lastSeen", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        const meta = (
+            d as unknown as { selfMetadata(): { id: string; lastSeen: number } }
+        ).selfMetadata();
+        expect(meta.id).toBe(d.getMyPeerId());
+        expect(typeof meta.lastSeen).toBe("number");
+        await d.stop();
+    });
+
+    it("selfMetadata returns empty id when not running", {
+        timeout: 5000,
+    }, () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        const meta = (
+            d as unknown as { selfMetadata(): { id: string } }
+        ).selfMetadata();
+        expect(meta.id).toBe("");
+        d.dispose();
+    });
+
+    it("routes heartbeat, discover and peer_list through the orchestrator", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const a = new PeerJSDiscovery(baseConfig(broker));
+        const b = new PeerJSDiscovery(baseConfig(broker));
+        await a.start();
+        await b.start();
+        await a.connect(b.getMyPeerId()!);
+        await flushMicrotasks();
+
+        // Grab the b-side channel to send wire messages to a.
+        const channel = Array.from(
+            (
+                b as unknown as {
+                    connectionManager: {
+                        getConnections: () => Map<
+                            string,
+                            { send: (m: unknown) => void; open: boolean }
+                        >;
+                    };
+                }
+            ).connectionManager
+                .getConnections()
+                .values()
+        )[0]!;
+        // 1) Announce b to a so a has a record to heartbeat against.
+        channel.send({
+            type: "announce",
+            from: b.getMyPeerId(),
+            payload: {
+                id: b.getMyPeerId(),
+                addresses: [],
+                metadata: {},
+                lastSeen: 1,
+            },
+            timestamp: 2,
+        });
+        await flushMicrotasks();
+        // 2) Heartbeat — touches lastSeen.
+        channel.send({
+            type: "heartbeat",
+            from: b.getMyPeerId(),
+            payload: {},
+            timestamp: 3,
+        });
+        // 3) Discover — a should reply with peer_list including b.
+        channel.send({
+            type: "discover",
+            from: b.getMyPeerId(),
+            payload: {},
+            timestamp: 4,
+        });
+        // 4) peer_list — a should fire connectToPeer for unknown ids.
+        channel.send({
+            type: "peer_list",
+            from: b.getMyPeerId(),
+            payload: ["already-known", b.getMyPeerId()!],
+            timestamp: 5,
+        });
+        await flushMicrotasks();
+        await flushMicrotasks();
+        expect(a.getPeerCount()).toBeGreaterThanOrEqual(1);
+        await a.stop();
+        await b.stop();
+    });
+
+    it("fires periodic loops with small intervals", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery({
+            ...baseConfig(broker),
+            interval: 1,
+            heartbeatInterval: 1,
+            cleanupInterval: 1,
+            timeout: 1,
+        });
+        await d.start();
+        // Seed a stale peer directly so the cleanup loop drops it.
+        const peers = (
+            d as unknown as {
+                room: {
+                    getPeers: () => Map<
+                        string,
+                        import("../../types/types.js").PeerJSPeerRecord
+                    >;
+                };
+            }
+        ).room.getPeers();
+        peers.set("stale-peer", {
+            id: "stale-peer",
+            addresses: [],
+            metadata: {},
+            lastSeen: -1_000_000,
+        });
+        await new Promise((r) => setTimeout(r, 30));
+        expect(d.getMyPeerId()).not.toBeNull();
+        await d.stop();
+    });
+
+    it("stop tolerates null myPeerId (defensive branch)", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        // Force null myPeerId before stop to exercise the defensive branch.
+        (d as unknown as { myPeerId: string | null }).myPeerId = null;
+        await d.stop();
+        expect(await d.isAvailable()).toBe(false);
+    });
+
+    it("stop with aborted signal mid-run skips leave", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const d = new PeerJSDiscovery(baseConfig(broker));
+        await d.start();
+        const ctrl = new AbortController();
+        ctrl.abort();
+        await d.stop(ctrl.signal);
+        expect(await d.isAvailable()).toBe(false);
+    });
+
+    it("integrates with a ServiceRegistry", { timeout: 5000 }, async () => {
+        const broker = new FakeBroker();
+        const registry = new ServiceRegistry();
+        const a = new PeerJSDiscovery({ ...baseConfig(broker), registry });
+        const b = new PeerJSDiscovery(baseConfig(broker));
+        await a.start();
+        await b.start();
+        await a.connect(b.getMyPeerId()!);
+        await flushMicrotasks();
+        const channel = Array.from(
+            (
+                b as unknown as {
+                    connectionManager: {
+                        getConnections: () => Map<
+                            string,
+                            { send: (m: unknown) => void; open: boolean }
+                        >;
+                    };
+                }
+            ).connectionManager
+                .getConnections()
+                .values()
+        )[0];
+        channel?.send({
+            type: "announce",
+            from: b.getMyPeerId(),
+            payload: {
+                id: b.getMyPeerId(),
+                addresses: ["addr-b"],
+                metadata: {},
+                lastSeen: 1,
+            },
+            timestamp: 2,
+        });
+        await flushMicrotasks();
+        expect(registry.get(b.getMyPeerId()!)).toBeDefined();
+        await a.stop();
+        await b.stop();
+    });
+});

packages/networking/network/network-discovery-peerjs/src/core/peerjs-discovery/peerjs-discovery.ts

@@ -0,0 +1,327 @@
+import type { DiscoveryStrategy, PeerInfo } from "@suaveplan/network-bootstrap";
+import type { Clock } from "@suaveplan/types";
+import {
+    NET_DISC_PEERJS_CODES,
+    NetDiscPeerJSError,
+} from "../../errors/errors.js";
+import { recordSignalingDuration, withStartSpan } from "../../otel/otel.js";
+import type {
+    DataConnectionLike,
+    PeerJSDiscoveryConfig,
+    PeerJSPeerMetadata,
+    PeerJSPeerRecord,
+    ResolvedPeerJSDiscoveryConfig,
+} from "../../types/types.js";
+import { PeerJSDiscoveryConfigSchema } from "../../types/types.schemas.js";
+import { PeerConnectionManager } from "../peer-connection-manager/peer-connection-manager.js";
+import { PeerJSIntervals } from "../peerjs-intervals/peerjs-intervals.js";
+import { handleMessage } from "../peerjs-message-handlers/peerjs-message-handlers.js";
+import { RoomManager } from "../room-manager/room-manager.js";
+
+const defaultClock: Clock = () => Date.now();
+
+/**
+ * Browser-tier PeerJS discovery strategy implementing
+ * `@suaveplan/network-bootstrap`'s `DiscoveryStrategy` contract. Wraps a
+ * PeerJS signalling-server client, runs an announce / heartbeat / cleanup
+ * loop over the resulting `DataConnectionLike` channels, and exposes a
+ * deduped peer set to bootstrap chains.
+ */
+export class PeerJSDiscovery implements DiscoveryStrategy {
+    public readonly name = "peerjs";
+    public readonly config: ResolvedPeerJSDiscoveryConfig;
+
+    private readonly clock: Clock;
+    private readonly room: RoomManager;
+    private readonly connectionManager: PeerConnectionManager;
+    private readonly intervals: PeerJSIntervals;
+    private running = false;
+    private disposed = false;
+    private myPeerId: string | null = null;
+
+    public constructor(
+        rawConfig: PeerJSDiscoveryConfig,
+        clock: Clock = defaultClock
+    ) {
+        const parsed = PeerJSDiscoveryConfigSchema.safeParse(rawConfig);
+        if (!parsed.success) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.INVALID_OPTIONS,
+                "errors.peerjs.invalid_options",
+                { cause: parsed.error }
+            );
+        }
+        const data = parsed.data;
+        if (rawConfig.peerFactory === undefined) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.INVALID_OPTIONS,
+                "errors.peerjs.peer_factory_required"
+            );
+        }
+        this.clock = clock;
+        this.config = {
+            strategy: "peerjs",
+            host: data.host,
+            port: data.port,
+            path: data.path,
+            secure: data.secure,
+            debug: data.debug,
+            room: data.room,
+            interval: data.interval,
+            timeout: data.timeout,
+            heartbeatInterval: data.heartbeatInterval,
+            cleanupInterval: data.cleanupInterval,
+            maxPeers: data.maxPeers,
+            key: data.key,
+            peerId: data.peerId,
+            iceServers: rawConfig.iceServers,
+            peerFactory: rawConfig.peerFactory,
+            bus: rawConfig.bus,
+            registry: rawConfig.registry,
+        };
+        this.room = new RoomManager(
+            this.clock,
+            this.config.room,
+            this.config.maxPeers,
+            this.config.bus,
+            this.config.registry
+        );
+        const peerOptions: import("../../types/types.js").PeerJSPeerOptions = {
+            host: this.config.host,
+            port: this.config.port,
+            path: this.config.path,
+            secure: this.config.secure,
+            debug: this.config.debug,
+            config:
+                this.config.iceServers === undefined
+                    ? {}
+                    : { iceServers: this.config.iceServers },
+            ...(this.config.key !== undefined ? { key: this.config.key } : {}),
+        };
+        this.connectionManager = new PeerConnectionManager(
+            rawConfig.peerFactory,
+            peerOptions,
+            {
+                onIncomingConnection: () => {
+                    /* room state updates on inbound announce, not connect */
+                },
+                onMessage: (raw, conn) => this.onMessage(raw, conn),
+                onPeerLost: (id) => this.handlePeerLost(id),
+            }
+        );
+        this.intervals = new PeerJSIntervals({
+            clock: this.clock,
+            announceIntervalMs: this.config.interval,
+            heartbeatIntervalMs: this.config.heartbeatInterval,
+            cleanupIntervalMs: this.config.cleanupInterval,
+            timeoutMs: this.config.timeout,
+            connections: this.connectionManager.getConnections() as Map<
+                string,
+                DataConnectionLike
+            >,
+            discoveredPeers: this.room.getPeers() as Map<
+                string,
+                PeerJSPeerRecord
+            >,
+            getMyPeerId: () => this.myPeerId,
+            isRunning: () => this.running,
+            selfMetadata: () => this.selfMetadata(),
+            handlePeerLost: (id) => this.handlePeerLost(id),
+        });
+    }
+
+    /**
+     * Open the broker, wire handlers, start announce/heartbeat/cleanup loops.
+     * Idempotent.
+     */
+    public async start(signal?: AbortSignal): Promise<void> {
+        if (this.disposed) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.DISPOSED,
+                "errors.peerjs.disposed"
+            );
+        }
+        if (this.running) return;
+        await withStartSpan(async (span) => {
+            span.setAttribute("room", this.config.room);
+            const t0 = this.clock();
+            try {
+                this.myPeerId = await this.connectionManager.initialize(
+                    this.config.peerId,
+                    signal
+                );
+            } catch (err) {
+                const reason =
+                    err instanceof Error
+                        ? err.message
+                        : /* istanbul ignore next -- initializePeer always rejects with an Error subclass */
+                          String(err);
+                this.config.bus?.emit("peerjs:signaling-failed", {
+                    reason,
+                    at: this.clock(),
+                });
+                throw err;
+            }
+            recordSignalingDuration(this.clock() - t0);
+            span.setAttribute("peer_id", this.myPeerId);
+            this.running = true;
+            this.intervals.start();
+            this.config.bus?.emit("peerjs:started", {
+                peerId: this.myPeerId,
+                room: this.config.room,
+                at: this.clock(),
+            });
+        });
+    }
+
+    /**
+     * Stop loops, send a `leave`, destroy the broker and clear room state.
+     * Idempotent.
+     */
+    public async stop(signal?: AbortSignal): Promise<void> {
+        if (!this.running) return;
+        if (signal?.aborted) {
+            this.running = false;
+            this.intervals.stop();
+            this.connectionManager.destroy();
+            this.room.clear();
+            this.myPeerId = null;
+            return;
+        }
+        this.running = false;
+        // myPeerId is always non-null when running; broadcast leave.
+        const localId = this.myPeerId;
+        if (localId !== null) {
+            this.connectionManager.broadcast({
+                type: "leave",
+                from: localId,
+                payload: {},
+                timestamp: this.clock(),
+            });
+        }
+        this.intervals.stop();
+        this.connectionManager.destroy();
+        this.room.clear();
+        this.myPeerId = null;
+    }
+
+    /**
+     * Convert tracked `PeerJSPeerRecord`s to `network-bootstrap` `PeerInfo`s.
+     * `signal` is honoured up-front; per-peer iteration is synchronous.
+     */
+    public async discover(
+        _timeoutMs: number,
+        signal?: AbortSignal
+    ): Promise<PeerInfo[]> {
+        if (signal?.aborted) {
+            throw toAbortError(signal);
+        }
+        if (this.disposed) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.DISPOSED,
+                "errors.peerjs.disposed"
+            );
+        }
+        return this.room.listPeers().map((r) => ({
+            peerId: r.id,
+            addresses: r.addresses,
+            lastSeen: r.lastSeen,
+            source: this.name,
+        }));
+    }
+
+    /**
+     * Strategy availability — `true` while running. Honours `signal` up-front.
+     */
+    public async isAvailable(signal?: AbortSignal): Promise<boolean> {
+        if (signal?.aborted) throw toAbortError(signal);
+        return this.running && !this.disposed;
+    }
+
+    /**
+     * Open a connection to a known peer id. Used by the message handlers'
+     * `peer_list` reply. Returns void on success or throws on error.
+     */
+    public async connect(peerId: string, signal?: AbortSignal): Promise<void> {
+        if (signal?.aborted) throw toAbortError(signal);
+        if (this.disposed) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.DISPOSED,
+                "errors.peerjs.disposed"
+            );
+        }
+        if (!this.running) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED,
+                "errors.peerjs.not_running"
+            );
+        }
+        this.connectionManager.connectToPeer(peerId);
+    }
+
+    /** Local peer id, or `null` before `start()` completes. */
+    public getMyPeerId(): string | null {
+        return this.myPeerId;
+    }
+
+    /** Snapshot of the live room. */
+    public getPeers(): readonly PeerJSPeerRecord[] {
+        return this.room.listPeers();
+    }
+
+    /** Number of tracked peers. */
+    public getPeerCount(): number {
+        return this.room.size();
+    }
+
+    /** Dispose every resource. After `dispose()` the strategy is unusable. */
+    public dispose(): void {
+        if (this.disposed) return;
+        this.disposed = true;
+        this.running = false;
+        this.intervals.stop();
+        this.connectionManager.destroy();
+        this.room.clear();
+        this.myPeerId = null;
+    }
+
+    private onMessage(raw: unknown, connection: DataConnectionLike): void {
+        handleMessage(raw, connection, {
+            myPeerId: this.myPeerId,
+            clock: this.clock,
+            knownPeerIds: () => this.room.listPeers().map((p) => p.id),
+            admitPeer: (record) => this.room.admit(record),
+            touchPeer: (id) => this.room.touch(id),
+            onPeerLost: (id) => this.handlePeerLost(id),
+            connectToPeer: async (id) => {
+                if (this.connectionManager.hasConnection(id)) return;
+                try {
+                    this.connectionManager.connectToPeer(id);
+                } catch {
+                    /* swallow — orchestrator owns retry policy */
+                }
+            },
+        });
+    }
+
+    private handlePeerLost(peerId: string): void {
+        this.connectionManager.removeConnection(peerId);
+        this.room.drop(peerId);
+    }
+
+    private selfMetadata(): PeerJSPeerMetadata {
+        return {
+            id: this.myPeerId ?? "",
+            addresses: [],
+            metadata: {},
+            lastSeen: this.clock(),
+        };
+    }
+}
+
+function toAbortError(signal: AbortSignal): Error {
+    if (signal.reason instanceof Error) return signal.reason;
+    const err = new Error("Aborted");
+    err.name = "AbortError";
+    return err;
+}

packages/networking/network/network-discovery-peerjs/src/core/peerjs-intervals/index.ts

@@ -0,0 +1,4 @@
+export {
+    type PeerJSIntervalDeps,
+    PeerJSIntervals,
+} from "./peerjs-intervals.js";

packages/networking/network/network-discovery-peerjs/src/core/peerjs-intervals/peerjs-intervals.md

@@ -0,0 +1,87 @@
+# peerjs-intervals
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Replaces upstream's three raw `setInterval` calls with a single `Scheduler`
+from `@suaveplan/timing` running three self-rearming loops (announce,
+heartbeat, cleanup). The injectable `Clock` makes every cadence deterministic
+under test and the `scheduler.dispose()` atomicity guarantees `stop()` cannot
+leak pending timers — the upstream package had no equivalent and required
+manual `clearInterval` on every handle.
+
+## Features
+
+- Three self-rearming loops at independent cadences.
+- Single underlying `Scheduler` — `stop()` disposes every pending task at
+  once.
+- Injectable `Clock` everywhere (`clock()` is the canonical timestamp source).
+- Idempotent `start()` / `stop()` — safe to call from any lifecycle hook.
+- Optional `schedulerFactory` override for unit tests that need a fake
+  scheduler.
+- Heartbeat and cleanup loops are pure; announce is async to mirror the
+  broadcast `await` semantics callers may expect.
+
+## Usage: Basic Example
+
+```ts
+import { PeerJSIntervals } from "@suaveplan/network-discovery-peerjs/peerjs-intervals";
+
+const intervals = new PeerJSIntervals({
+    clock: () => Date.now(),
+    announceIntervalMs: 30_000,
+    heartbeatIntervalMs: 15_000,
+    cleanupIntervalMs: 30_000,
+    timeoutMs: 60_000,
+    connections,
+    discoveredPeers,
+    getMyPeerId: () => myPeerId,
+    isRunning: () => running,
+    selfMetadata: () => ({ id: myPeerId, addresses: [], metadata: {}, lastSeen: Date.now() }),
+    handlePeerLost: (id) => removePeer(id),
+});
+intervals.start();
+// later
+intervals.stop();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { PeerJSIntervals } from "@suaveplan/network-discovery-peerjs";
+import { createScheduler } from "@suaveplan/timing";
+
+let fakeNow = 0;
+const fakeClock = () => fakeNow;
+const intervals = new PeerJSIntervals(
+    { ...deps, clock: fakeClock },
+    (clock) => createScheduler({ clock })
+);
+intervals.start();
+fakeNow += 30_000;
+// trigger scheduler ticks via the test scheduler in your harness...
+intervals.stop();
+```
+
+## API Reference
+
+- `PeerJSIntervalDeps` — `{clock, announceIntervalMs, heartbeatIntervalMs,
+  cleanupIntervalMs, timeoutMs, connections, discoveredPeers, getMyPeerId,
+  isRunning, selfMetadata, handlePeerLost}`.
+- `new PeerJSIntervals(deps, schedulerFactory?)` — second arg overrides the
+  scheduler construction (defaults to `createScheduler({ clock })`).
+- `start(): void` — kick off all three loops. Idempotent.
+- `stop(): void` — dispose every pending timer. Idempotent.
+- `isStopped: boolean` — true after `stop()`.
+
+## Implementation Notes
+
+Each `schedule(fn, delay)` callback re-arms itself at the tail to keep the
+underlying scheduler one-shot. Re-arm is guarded by `stopped` and
+`scheduler.disposed` so a callback that fires the same tick as `stop()` does
+not enqueue a new task against a disposed scheduler. The announce loop awaits
+the broadcast before re-arming so a slow signalling path stretches the
+effective interval rather than stacking sends, which matches the upstream
+behaviour but without the `setInterval` pile-up.

packages/networking/network/network-discovery-peerjs/src/core/peerjs-intervals/peerjs-intervals.test.ts

@@ -0,0 +1,385 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import type { Scheduler, SchedulerHandle } from "@suaveplan/timing";
+import type {
+    DataConnectionLike,
+    PeerJSMessage,
+    PeerJSPeerMetadata,
+    PeerJSPeerRecord,
+} from "../../types/types.js";
+import { PeerJSIntervals } from "./peerjs-intervals.js";
+
+interface PendingTask {
+    fn: () => void | Promise<void>;
+    delay: number;
+}
+
+function manualScheduler(): Scheduler & {
+    tasks: PendingTask[];
+    flush: () => Promise<void>;
+} {
+    const tasks: PendingTask[] = [];
+    let nextId = 1;
+    let disposed = false;
+    const sched = {
+        get disposed() {
+            return disposed;
+        },
+        schedule(
+            fn: () => void | Promise<void>,
+            delay: number
+        ): SchedulerHandle {
+            if (disposed) throw new Error("disposed");
+            tasks.push({ fn, delay });
+            const id = nextId++;
+            return {
+                id,
+                cancel() {
+                    /* not used */
+                },
+            };
+        },
+        cancel() {
+            /* unused */
+        },
+        async drain() {
+            /* unused */
+        },
+        dispose() {
+            disposed = true;
+            tasks.length = 0;
+        },
+        tasks,
+        async flush() {
+            // Drain in order, only one cycle so re-arms requeue at the tail.
+            const initial = tasks.splice(0, tasks.length);
+            for (const t of initial) {
+                await t.fn();
+            }
+        },
+    };
+    return sched as Scheduler & {
+        tasks: PendingTask[];
+        flush: () => Promise<void>;
+    };
+}
+
+describe("PeerJSIntervals", () => {
+    function makeDeps(
+        overrides: Partial<{
+            myPeerId: string | null;
+            running: boolean;
+            now: number;
+            connections: Map<string, DataConnectionLike>;
+            discoveredPeers: Map<string, PeerJSPeerRecord>;
+            handlePeerLost: (id: string) => void;
+            timeoutMs: number;
+        }> = {}
+    ) {
+        let now = overrides.now ?? 1000;
+        const myPeerId =
+            "myPeerId" in overrides ? (overrides.myPeerId ?? null) : "self";
+        const running = overrides.running ?? true;
+        const connections =
+            overrides.connections ?? new Map<string, DataConnectionLike>();
+        const discoveredPeers =
+            overrides.discoveredPeers ?? new Map<string, PeerJSPeerRecord>();
+        const lost: string[] = [];
+        const handlePeerLost =
+            overrides.handlePeerLost ?? ((id: string) => lost.push(id));
+        const meta: PeerJSPeerMetadata = {
+            id: myPeerId ?? "",
+            addresses: [],
+            metadata: {},
+            lastSeen: now,
+        };
+        return {
+            deps: {
+                clock: () => now,
+                announceIntervalMs: 30_000,
+                heartbeatIntervalMs: 15_000,
+                cleanupIntervalMs: 30_000,
+                timeoutMs: overrides.timeoutMs ?? 60_000,
+                connections,
+                discoveredPeers,
+                getMyPeerId: () => myPeerId,
+                isRunning: () => running,
+                selfMetadata: () => meta,
+                handlePeerLost,
+            },
+            lost,
+            advance(ms: number) {
+                now += ms;
+            },
+        };
+    }
+
+    it("start() schedules three initial tasks", { timeout: 5000 }, () => {
+        const { deps } = makeDeps();
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        expect(sched.tasks).toHaveLength(3);
+    });
+
+    it("stop() disposes the scheduler", { timeout: 5000 }, () => {
+        const { deps } = makeDeps();
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        intervals.stop();
+        expect(intervals.isStopped).toBe(true);
+        expect(sched.disposed).toBe(true);
+    });
+
+    it("re-arms after each task", { timeout: 5000 }, async () => {
+        const { deps } = makeDeps();
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        // re-arm should have re-queued three again
+        expect(sched.tasks).toHaveLength(3);
+    });
+
+    it("announce broadcast skips when not running", {
+        timeout: 5000,
+    }, async () => {
+        const sent: PeerJSMessage[] = [];
+        const conn: DataConnectionLike = {
+            peer: "p",
+            open: true,
+            send: (m) => sent.push(m),
+            on: () => {},
+            close: () => {},
+        };
+        const connections = new Map<string, DataConnectionLike>([["p", conn]]);
+        const { deps } = makeDeps({ running: false, connections });
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        expect(sent).toEqual([]);
+    });
+
+    it("announce broadcast skips when myPeerId is null", {
+        timeout: 5000,
+    }, async () => {
+        const sent: PeerJSMessage[] = [];
+        const conn: DataConnectionLike = {
+            peer: "p",
+            open: true,
+            send: (m) => sent.push(m),
+            on: () => {},
+            close: () => {},
+        };
+        const connections = new Map<string, DataConnectionLike>([["p", conn]]);
+        const { deps } = makeDeps({ myPeerId: null, connections });
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        expect(sent).toEqual([]);
+    });
+
+    it("announce broadcasts to every open connection", {
+        timeout: 5000,
+    }, async () => {
+        const sent: PeerJSMessage[] = [];
+        const conn: DataConnectionLike = {
+            peer: "p",
+            open: true,
+            send: (m) => sent.push(m),
+            on: () => {},
+            close: () => {},
+        };
+        const connections = new Map<string, DataConnectionLike>([["p", conn]]);
+        const { deps } = makeDeps({ connections });
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        const types = sent.map((s) => s.type).sort();
+        // announce + heartbeat
+        expect(types).toEqual(["announce", "heartbeat"]);
+    });
+
+    it("cleanup drops peers past timeout", { timeout: 5000 }, async () => {
+        const discoveredPeers = new Map<string, PeerJSPeerRecord>();
+        discoveredPeers.set("ghost", {
+            id: "ghost",
+            addresses: [],
+            metadata: {},
+            lastSeen: 0,
+        });
+        discoveredPeers.set("fresh", {
+            id: "fresh",
+            addresses: [],
+            metadata: {},
+            lastSeen: 1000,
+        });
+        const { deps } = makeDeps({
+            now: 100_000,
+            discoveredPeers,
+            timeoutMs: 10_000,
+        });
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        // cleanup ran — but we still have to find it among 3 tasks
+        // Both ghost and fresh are > 10s old vs now=100_000, both dropped
+    });
+
+    it("cleanup is a no-op when not running", { timeout: 5000 }, async () => {
+        const discoveredPeers = new Map<string, PeerJSPeerRecord>();
+        discoveredPeers.set("ghost", {
+            id: "ghost",
+            addresses: [],
+            metadata: {},
+            lastSeen: 0,
+        });
+        const { deps, lost } = makeDeps({
+            running: false,
+            now: 100_000,
+            discoveredPeers,
+            timeoutMs: 10_000,
+        });
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        expect(lost).toEqual([]);
+    });
+
+    it("heartbeat broadcast skips when not running", {
+        timeout: 5000,
+    }, async () => {
+        const sent: PeerJSMessage[] = [];
+        const conn: DataConnectionLike = {
+            peer: "p",
+            open: true,
+            send: (m) => sent.push(m),
+            on: () => {},
+            close: () => {},
+        };
+        const connections = new Map<string, DataConnectionLike>([["p", conn]]);
+        const { deps } = makeDeps({ running: false, connections });
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        expect(sent).toEqual([]);
+    });
+
+    it("heartbeat skipped when myPeerId is null", {
+        timeout: 5000,
+    }, async () => {
+        const sent: PeerJSMessage[] = [];
+        const conn: DataConnectionLike = {
+            peer: "p",
+            open: true,
+            send: (m) => sent.push(m),
+            on: () => {},
+            close: () => {},
+        };
+        const connections = new Map<string, DataConnectionLike>([["p", conn]]);
+        const { deps } = makeDeps({ myPeerId: null, connections });
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        expect(sent).toEqual([]);
+    });
+
+    it("start() is idempotent after stop()", { timeout: 5000 }, () => {
+        const { deps } = makeDeps();
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.stop();
+        intervals.start();
+        // stopped before start — start() should no-op
+        expect(sched.tasks).toHaveLength(0);
+    });
+
+    it("stop() is idempotent", { timeout: 5000 }, () => {
+        const { deps } = makeDeps();
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        intervals.stop();
+        intervals.stop();
+        expect(intervals.isStopped).toBe(true);
+    });
+
+    it("constructs with the default scheduler factory", {
+        timeout: 5000,
+    }, () => {
+        const { deps } = makeDeps();
+        const intervals = new PeerJSIntervals(deps);
+        intervals.stop();
+        expect(intervals.isStopped).toBe(true);
+    });
+
+    it("re-arm guards short-circuit when stopped mid-flight", {
+        timeout: 5000,
+    }, async () => {
+        // A scheduler whose dispose does NOT drop pending tasks, so we can
+        // run those tasks AFTER stop() and exercise the re-arm guards inside
+        // scheduleAnnounce/Heartbeat/Cleanup.
+        const tasks: PendingTask[] = [];
+        let nextId = 1;
+        let disposed = false;
+        const sched = {
+            get disposed() {
+                return disposed;
+            },
+            schedule(fn: () => void | Promise<void>, delay: number) {
+                if (disposed) return { id: -1, cancel() {} };
+                tasks.push({ fn, delay });
+                return { id: nextId++, cancel() {} };
+            },
+            cancel() {},
+            async drain() {},
+            dispose() {
+                disposed = true;
+            },
+        } as Scheduler;
+        const { deps } = makeDeps();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        const initial = tasks.splice(0, tasks.length);
+        intervals.stop();
+        for (const t of initial) {
+            await t.fn();
+        }
+        expect(tasks).toHaveLength(0);
+    });
+
+    it("cleanup runs and drops stale peers", { timeout: 5000 }, async () => {
+        const discoveredPeers = new Map<string, PeerJSPeerRecord>();
+        discoveredPeers.set("ghost", {
+            id: "ghost",
+            addresses: [],
+            metadata: {},
+            lastSeen: 0,
+        });
+        discoveredPeers.set("fresh", {
+            id: "fresh",
+            addresses: [],
+            metadata: {},
+            lastSeen: 99_999,
+        });
+        const lost: string[] = [];
+        const { deps } = makeDeps({
+            now: 100_000,
+            discoveredPeers,
+            timeoutMs: 10_000,
+            handlePeerLost: (id) => lost.push(id),
+        });
+        const sched = manualScheduler();
+        const intervals = new PeerJSIntervals(deps, () => sched);
+        intervals.start();
+        await sched.flush();
+        expect(lost).toEqual(["ghost"]);
+    });
+});

packages/networking/network/network-discovery-peerjs/src/core/peerjs-intervals/peerjs-intervals.ts

@@ -0,0 +1,139 @@
+import { createScheduler, type Scheduler } from "@suaveplan/timing";
+import type { Clock } from "@suaveplan/types";
+import type {
+    DataConnectionLike,
+    PeerJSPeerMetadata,
+    PeerJSPeerRecord,
+} from "../../types/types.js";
+import { broadcastMessage } from "../peerjs-connection/peerjs-connection.js";
+
+/**
+ * Dependencies the interval loops close over.
+ */
+export interface PeerJSIntervalDeps {
+    readonly clock: Clock;
+    readonly announceIntervalMs: number;
+    readonly heartbeatIntervalMs: number;
+    readonly cleanupIntervalMs: number;
+    readonly timeoutMs: number;
+    readonly connections: Map<string, DataConnectionLike>;
+    readonly discoveredPeers: Map<string, PeerJSPeerRecord>;
+    /** Current local peer id — `null` until the peer is open. */
+    getMyPeerId(): string | null;
+    /** Returns `true` while the strategy is running. */
+    isRunning(): boolean;
+    /** Build the announce metadata for the local peer. */
+    selfMetadata(): PeerJSPeerMetadata;
+    /** Drop a peer from local state. */
+    handlePeerLost(peerId: string): void;
+}
+
+/**
+ * Wrapper around three `Scheduler` self-rearming loops, one per cadence
+ * (announce / heartbeat / cleanup). Replaces upstream's three `setInterval`
+ * handles. Scheduler `dispose()` cancels every pending timer atomically.
+ */
+export class PeerJSIntervals {
+    private readonly scheduler: Scheduler;
+    private readonly deps: PeerJSIntervalDeps;
+    private stopped = false;
+
+    public constructor(
+        deps: PeerJSIntervalDeps,
+        schedulerFactory: (clock: Clock) => Scheduler = (c) =>
+            createScheduler({ clock: c })
+    ) {
+        this.deps = deps;
+        this.scheduler = schedulerFactory(deps.clock);
+    }
+
+    /**
+     * Start every periodic loop. Idempotent — subsequent calls before `stop`
+     * are no-ops.
+     */
+    public start(): void {
+        if (this.stopped) return;
+        this.scheduleAnnounce();
+        this.scheduleHeartbeat();
+        this.scheduleCleanup();
+    }
+
+    /**
+     * Stop every loop and dispose the underlying scheduler. Idempotent.
+     */
+    public stop(): void {
+        if (this.stopped) return;
+        this.stopped = true;
+        this.scheduler.dispose();
+    }
+
+    /** Whether `stop()` has been called. */
+    public get isStopped(): boolean {
+        return this.stopped;
+    }
+
+    private scheduleAnnounce(): void {
+        if (this.stopped || this.scheduler.disposed) return;
+        this.scheduler.schedule(async () => {
+            await this.runAnnounce();
+            this.scheduleAnnounce();
+        }, this.deps.announceIntervalMs);
+    }
+
+    private scheduleHeartbeat(): void {
+        if (this.stopped || this.scheduler.disposed) return;
+        this.scheduler.schedule(() => {
+            this.runHeartbeat();
+            this.scheduleHeartbeat();
+        }, this.deps.heartbeatIntervalMs);
+    }
+
+    private scheduleCleanup(): void {
+        if (this.stopped || this.scheduler.disposed) return;
+        this.scheduler.schedule(() => {
+            this.runCleanup();
+            this.scheduleCleanup();
+        }, this.deps.cleanupIntervalMs);
+    }
+
+    private async runAnnounce(): Promise<void> {
+        if (!this.deps.isRunning()) return;
+        const myPeerId = this.deps.getMyPeerId();
+        if (myPeerId === null) return;
+        const metadata = this.deps.selfMetadata();
+        broadcastMessage(
+            {
+                type: "announce",
+                from: myPeerId,
+                payload: metadata,
+                timestamp: this.deps.clock(),
+            },
+            this.deps.connections
+        );
+    }
+
+    private runHeartbeat(): void {
+        if (!this.deps.isRunning()) return;
+        const myPeerId = this.deps.getMyPeerId();
+        if (myPeerId === null) return;
+        broadcastMessage(
+            {
+                type: "heartbeat",
+                from: myPeerId,
+                payload: {},
+                timestamp: this.deps.clock(),
+            },
+            this.deps.connections
+        );
+    }
+
+    private runCleanup(): void {
+        if (!this.deps.isRunning()) return;
+        const now = this.deps.clock();
+        for (const [peerId, peer] of this.deps.discoveredPeers.entries()) {
+            if (now - peer.lastSeen > this.deps.timeoutMs) {
+                this.deps.handlePeerLost(peerId);
+            }
+        }
+    }
+}

packages/networking/network/network-discovery-peerjs/src/core/peerjs-message-handlers/index.ts

@@ -0,0 +1,4 @@
+export {
+    handleMessage,
+    type PeerJSMessageHandlerDeps,
+} from "./peerjs-message-handlers.js";

packages/networking/network/network-discovery-peerjs/src/core/peerjs-message-handlers/peerjs-message-handlers.md

@@ -0,0 +1,90 @@
+# peerjs-message-handlers
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Pure dispatch table for inbound PeerJS discovery messages. Validates every
+incoming wire payload through `PeerJSMessageSchema` (Zod) at the boundary and
+routes well-formed messages to the matching case: `announce`, `discover`,
+`peer_list`, `leave`, `heartbeat`. The handlers are intentionally stateless —
+they never mutate the peer set directly. State lives in the orchestrator's
+`RoomManager`, which the handlers call via the `admitPeer` / `touchPeer` /
+`onPeerLost` callbacks. This split avoids double-bookkeeping bugs where two
+places race to set the same entry.
+
+## Features
+
+- Zod-validated boundary — malformed messages drop silently instead of
+  crashing the strategy (discovery must tolerate hostile peers).
+- Exhaustive switch over the wire-format enum with safe-fallthrough.
+- Stateless: every state mutation is delegated to caller-supplied callbacks.
+- `admitPeer` returns `"added" | "refreshed" | "rejected"` so the room can
+  enforce `maxPeers` admission centrally; the handler only reports the
+  outcome (`false` when `"rejected"`).
+- Discover-request replies are skipped when the connection is closed,
+  guarding against a race between `discover` arrival and channel teardown.
+- `knownPeerIds()` is a callback so the handler does not need to hold a Map
+  reference, keeping memory ownership inside the room manager.
+
+## Usage: Basic Example
+
+```ts
+import { handleMessage } from "@suaveplan/network-discovery-peerjs/peerjs-message-handlers";
+
+handleMessage(raw, conn, {
+    myPeerId,
+    clock: () => Date.now(),
+    knownPeerIds: () => room.listPeers().map((p) => p.id),
+    admitPeer: (r) => room.admit(r),
+    touchPeer: (id) => room.touch(id),
+    onPeerLost: (id) => room.drop(id),
+    connectToPeer: (id) => discovery.connect(id),
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { handleMessage } from "@suaveplan/network-discovery-peerjs";
+
+const deps = {
+    myPeerId: "alpha",
+    clock,
+    knownPeerIds: () => Array.from(state.keys()),
+    admitPeer(r) {
+        const action = state.has(r.id) ? "refreshed" : "added";
+        state.set(r.id, r);
+        if (action === "added") metrics.peerFound.inc();
+        return action;
+    },
+    touchPeer: (id) => (state.get(id) ? (state.get(id)!.lastSeen = clock(), true) : false),
+    onPeerLost: (id) => state.delete(id),
+    connectToPeer: (id) => discovery.connect(id),
+};
+
+socket.on("data", (raw) => {
+    const accepted = handleMessage(raw, connection, deps);
+    if (!accepted) logger.debug("dropped malformed peerjs message");
+});
+```
+
+## API Reference
+
+- `PeerJSMessageHandlerDeps` — `{myPeerId, clock, knownPeerIds, admitPeer,
+  touchPeer, onPeerLost, connectToPeer}`.
+- `handleMessage(raw, connection, deps): boolean` — returns `true` when the
+  message was accepted and routed, `false` when it was dropped (Zod failure,
+  admission rejected, heartbeat for unknown peer, discover with no local
+  peer id, send-to-closed-connection).
+
+## Implementation Notes
+
+The module never throws — drop-on-error is intentional because PeerJS data
+channels can carry payloads from arbitrary remote peers and a strategy that
+crashes on bad input would create a trivial DoS vector. The `default` arm of
+the switch is unreachable in practice because Zod's enum constraint already
+rejects unknown types; an `/* c8 ignore */` annotation acknowledges that for
+the coverage gate. Fire-and-forget on `connectToPeer` is the same model
+upstream used — the orchestrator owns retry policy.

packages/networking/network/network-discovery-peerjs/src/core/peerjs-message-handlers/peerjs-message-handlers.test.ts

@@ -0,0 +1,338 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import fc from "fast-check";
+import type {
+    DataConnectionLike,
+    PeerJSMessage,
+    PeerJSPeerRecord,
+} from "../../types/types.js";
+import {
+    handleMessage,
+    type PeerJSMessageHandlerDeps,
+} from "./peerjs-message-handlers.js";
+
+function fakeConnection(
+    peer: string,
+    open = true
+): DataConnectionLike & {
+    sent: PeerJSMessage[];
+} {
+    const sent: PeerJSMessage[] = [];
+    return {
+        peer,
+        open,
+        send(m) {
+            sent.push(m);
+        },
+        on() {
+            /* noop */
+        },
+        close() {
+            /* noop */
+        },
+        sent,
+    } as DataConnectionLike & { sent: PeerJSMessage[] };
+}
+
+function deps(
+    overrides: Partial<PeerJSMessageHandlerDeps> = {},
+    cap = 100
+): PeerJSMessageHandlerDeps & {
+    discovered: string[];
+    lost: string[];
+    full: string[];
+    connected: string[];
+    state: Map<string, PeerJSPeerRecord>;
+} {
+    const state = new Map<string, PeerJSPeerRecord>();
+    const discovered: string[] = [];
+    const lost: string[] = [];
+    const full: string[] = [];
+    const connected: string[] = [];
+    const base: PeerJSMessageHandlerDeps = {
+        myPeerId: "self",
+        clock: () => 1000,
+        knownPeerIds: () => Array.from(state.keys()),
+        admitPeer: (r) => {
+            const existing = state.get(r.id);
+            if (existing === undefined) {
+                if (state.size >= cap) {
+                    full.push(r.id);
+                    return "rejected";
+                }
+                state.set(r.id, { ...r });
+                discovered.push(r.id);
+                return "added";
+            }
+            existing.lastSeen = 1000;
+            return "refreshed";
+        },
+        touchPeer: (id) => {
+            const peer = state.get(id);
+            if (peer === undefined) return false;
+            peer.lastSeen = 1000;
+            return true;
+        },
+        onPeerLost: (id) => {
+            lost.push(id);
+            state.delete(id);
+        },
+        connectToPeer: async (id) => {
+            connected.push(id);
+        },
+        ...overrides,
+    };
+    return Object.assign(base, {
+        discovered,
+        lost,
+        full,
+        connected,
+        state,
+    });
+}
+
+describe("handleMessage", () => {
+    it("drops a Zod-invalid payload", { timeout: 5000 }, () => {
+        const d = deps();
+        const conn = fakeConnection("remote");
+        expect(handleMessage({ bogus: true }, conn, d)).toBe(false);
+    });
+
+    it("accepts an announce and emits discovered", { timeout: 5000 }, () => {
+        const d = deps();
+        const conn = fakeConnection("remote");
+        const msg: PeerJSMessage = {
+            type: "announce",
+            from: "remote",
+            payload: {
+                id: "remote",
+                addresses: ["addr1"],
+                metadata: { foo: "bar" },
+                lastSeen: 500,
+            },
+            timestamp: 1000,
+        };
+        expect(handleMessage(msg, conn, d)).toBe(true);
+        expect(d.discovered).toEqual(["remote"]);
+        expect(d.state.get("remote")?.lastSeen).toBe(1000);
+    });
+
+    it("refreshes an existing peer without re-emitting discovered", {
+        timeout: 5000,
+    }, () => {
+        const d = deps();
+        d.state.set("remote", {
+            id: "remote",
+            addresses: [],
+            metadata: {},
+            lastSeen: 100,
+        });
+        const msg: PeerJSMessage = {
+            type: "announce",
+            from: "remote",
+            payload: {
+                id: "remote",
+                addresses: [],
+                metadata: {},
+                lastSeen: 500,
+            },
+            timestamp: 1000,
+        };
+        expect(handleMessage(msg, fakeConnection("remote"), d)).toBe(true);
+        expect(d.discovered).toEqual([]);
+        expect(d.state.get("remote")?.lastSeen).toBe(1000);
+    });
+
+    it("rejects announce when room would exceed maxPeers", {
+        timeout: 5000,
+    }, () => {
+        const d = deps({}, 1);
+        d.state.set("existing", {
+            id: "existing",
+            addresses: [],
+            metadata: {},
+            lastSeen: 0,
+        });
+        const msg: PeerJSMessage = {
+            type: "announce",
+            from: "newcomer",
+            payload: {
+                id: "newcomer",
+                addresses: [],
+                metadata: {},
+                lastSeen: 0,
+            },
+            timestamp: 1,
+        };
+        expect(handleMessage(msg, fakeConnection("newcomer"), d)).toBe(false);
+        expect(d.full).toEqual(["newcomer"]);
+    });
+
+    it("responds to discover with the local peer list", {
+        timeout: 5000,
+    }, () => {
+        const d = deps();
+        d.state.set("a", {
+            id: "a",
+            addresses: [],
+            metadata: {},
+            lastSeen: 0,
+        });
+        const conn = fakeConnection("remote");
+        const msg: PeerJSMessage = {
+            type: "discover",
+            from: "remote",
+            payload: {},
+            timestamp: 1,
+        };
+        expect(handleMessage(msg, conn, d)).toBe(true);
+        expect(conn.sent).toHaveLength(1);
+        const reply = conn.sent[0]!;
+        expect(reply.type).toBe("peer_list");
+        expect(reply.payload).toEqual(["a"]);
+    });
+
+    it("ignores discover when myPeerId is null", { timeout: 5000 }, () => {
+        const d = deps({ myPeerId: null });
+        const conn = fakeConnection("remote");
+        expect(
+            handleMessage(
+                {
+                    type: "discover",
+                    from: "remote",
+                    payload: {},
+                    timestamp: 1,
+                },
+                conn,
+                d
+            )
+        ).toBe(false);
+    });
+
+    it("skips discover reply when channel is closed", { timeout: 5000 }, () => {
+        const d = deps();
+        const conn = fakeConnection("remote", false);
+        expect(
+            handleMessage(
+                {
+                    type: "discover",
+                    from: "remote",
+                    payload: {},
+                    timestamp: 1,
+                },
+                conn,
+                d
+            )
+        ).toBe(false);
+    });
+
+    it("connects to every unknown peer in a peer_list", {
+        timeout: 5000,
+    }, async () => {
+        const d = deps();
+        const msg: PeerJSMessage = {
+            type: "peer_list",
+            from: "remote",
+            payload: ["a", "self", "b"],
+            timestamp: 1,
+        };
+        expect(handleMessage(msg, fakeConnection("remote"), d)).toBe(true);
+        await Promise.resolve();
+        await Promise.resolve();
+        expect(d.connected.sort()).toEqual(["a", "b"]);
+    });
+
+    it("handles leave by dropping the sender", { timeout: 5000 }, () => {
+        const d = deps();
+        const msg: PeerJSMessage = {
+            type: "leave",
+            from: "remote",
+            payload: {},
+            timestamp: 1,
+        };
+        expect(handleMessage(msg, fakeConnection("remote"), d)).toBe(true);
+        expect(d.lost).toEqual(["remote"]);
+    });
+
+    it("updates lastSeen on heartbeat", { timeout: 5000 }, () => {
+        const d = deps({ clock: () => 2000 });
+        d.state.set("remote", {
+            id: "remote",
+            addresses: [],
+            metadata: {},
+            lastSeen: 500,
+        });
+        const msg: PeerJSMessage = {
+            type: "heartbeat",
+            from: "remote",
+            payload: {},
+            timestamp: 1,
+        };
+        expect(handleMessage(msg, fakeConnection("remote"), d)).toBe(true);
+        expect(d.state.get("remote")?.lastSeen).toBe(1000);
+    });
+
+    it("drops heartbeat for unknown peer", { timeout: 5000 }, () => {
+        const d = deps();
+        const msg: PeerJSMessage = {
+            type: "heartbeat",
+            from: "ghost",
+            payload: {},
+            timestamp: 1,
+        };
+        expect(handleMessage(msg, fakeConnection("ghost"), d)).toBe(false);
+    });
+
+    it("property: deduped announce never grows the peer set past maxPeers", {
+        timeout: 5000,
+    }, () => {
+        fc.assert(
+            fc.property(
+                fc.array(fc.string({ minLength: 1, maxLength: 6 }), {
+                    minLength: 1,
+                    maxLength: 50,
+                }),
+                fc.integer({ min: 1, max: 25 }),
+                (ids, cap) => {
+                    const d = deps({}, cap);
+                    for (const id of ids) {
+                        handleMessage(
+                            {
+                                type: "announce",
+                                from: id,
+                                payload: {
+                                    id,
+                                    addresses: [],
+                                    metadata: {},
+                                    lastSeen: 0,
+                                },
+                                timestamp: 1,
+                            },
+                            fakeConnection(id),
+                            d
+                        );
+                    }
+                    return d.state.size <= cap;
+                }
+            ),
+            { numRuns: 50 }
+        );
+    });
+
+    it("preserves capabilities when present", { timeout: 5000 }, () => {
+        const d = deps();
+        const msg: PeerJSMessage = {
+            type: "announce",
+            from: "remote",
+            payload: {
+                id: "remote",
+                addresses: ["addr"],
+                metadata: {},
+                capabilities: ["v1", "v2"],
+                lastSeen: 0,
+            },
+            timestamp: 1,
+        };
+        expect(handleMessage(msg, fakeConnection("remote"), d)).toBe(true);
+        expect(d.state.get("remote")?.capabilities).toEqual(["v1", "v2"]);
+    });
+});

packages/networking/network/network-discovery-peerjs/src/core/peerjs-message-handlers/peerjs-message-handlers.ts

@@ -0,0 +1,112 @@
+import type { Clock } from "@suaveplan/types";
+import type {
+    DataConnectionLike,
+    PeerJSMessage,
+    PeerJSPeerMetadata,
+    PeerJSPeerRecord,
+} from "../../types/types.js";
+import { PeerJSMessageSchema } from "../../types/types.schemas.js";
+
+/**
+ * Callbacks the message dispatch table fans out to. Implemented by the
+ * orchestrator (`PeerJSDiscovery`); kept as an interface so the handlers
+ * remain pure routers with no orchestrator import (avoids cycles).
+ */
+export interface PeerJSMessageHandlerDeps {
+    readonly myPeerId: string | null;
+    readonly clock: Clock;
+    /** Snapshot of currently-known peer ids for the `discover` reply. */
+    knownPeerIds(): readonly string[];
+    /**
+     * Admit (or refresh) a peer reported by an `announce`. Implementation
+     * decides if the peer is new and returns the resulting action.
+     */
+    admitPeer(record: PeerJSPeerRecord): "added" | "refreshed" | "rejected";
+    /** Touch the `lastSeen` on a heartbeat. Returns `false` if unknown. */
+    touchPeer(peerId: string): boolean;
+    /** Drop a peer on `leave`. */
+    onPeerLost(peerId: string): void;
+    /** Open an outbound connection to a peer learned from `peer_list`. */
+    connectToPeer(peerId: string): Promise<void>;
+}
+
+/**
+ * Parse an inbound message via Zod and dispatch to the matching handler. Any
+ * schema failure or unknown message type is dropped silently (returns
+ * `false`) — discovery wire-format must tolerate hostile peers without
+ * crashing the strategy.
+ */
+export function handleMessage(
+    raw: unknown,
+    connection: DataConnectionLike,
+    deps: PeerJSMessageHandlerDeps
+): boolean {
+    const parsed = PeerJSMessageSchema.safeParse(raw);
+    if (!parsed.success) {
+        return false;
+    }
+    const message = parsed.data as PeerJSMessage;
+    switch (message.type) {
+        case "announce":
+            return handleAnnounce(message, deps);
+        case "discover":
+            return handleDiscoverRequest(connection, deps);
+        case "peer_list":
+            return handlePeerList(message, deps);
+        case "leave":
+            deps.onPeerLost(message.from);
+            return true;
+        case "heartbeat":
+            return deps.touchPeer(message.from);
+        /* istanbul ignore next -- exhaustive switch; Zod already rejects others */
+        default:
+            return false;
+    }
+}
+
+function handleAnnounce(
+    message: PeerJSMessage,
+    deps: PeerJSMessageHandlerDeps
+): boolean {
+    const metadata = message.payload as PeerJSPeerMetadata;
+    const record: PeerJSPeerRecord = {
+        id: metadata.id,
+        addresses: metadata.addresses,
+        metadata: metadata.metadata,
+        lastSeen: deps.clock(),
+        ...(metadata.capabilities !== undefined
+            ? { capabilities: metadata.capabilities }
+            : {}),
+    };
+    const action = deps.admitPeer(record);
+    return action !== "rejected";
+}
+
+function handleDiscoverRequest(
+    connection: DataConnectionLike,
+    deps: PeerJSMessageHandlerDeps
+): boolean {
+    if (deps.myPeerId === null) return false;
+    if (!connection.open) return false;
+    connection.send({
+        type: "peer_list",
+        from: deps.myPeerId,
+        payload: deps.knownPeerIds(),
+        timestamp: deps.clock(),
+    });
+    return true;
+}
+
+function handlePeerList(
+    message: PeerJSMessage,
+    deps: PeerJSMessageHandlerDeps
+): boolean {
+    const peerIds = message.payload as readonly string[];
+    for (const peerId of peerIds) {
+        if (peerId !== deps.myPeerId) {
+            // Fire-and-forget — the orchestrator owns connection retries.
+            void deps.connectToPeer(peerId);
+        }
+    }
+    return true;
+}

packages/networking/network/network-discovery-peerjs/src/core/room-manager/index.ts

@@ -0,0 +1 @@
+export { RoomManager } from "./room-manager.js";

packages/networking/network/network-discovery-peerjs/src/core/room-manager/room-manager.md

@@ -0,0 +1,80 @@
+# room-manager
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Owns the logical-room view of discovered peers, layered on top of the raw
+PeerJS connection registry. Provides admission (`maxPeers` cap), TTL-driven
+pruning, deduped `lastSeen` refresh, and optional fan-out to both an
+`EventBusLike` and a `ServiceRegistry` so the strategy can mirror state into
+shared discovery infrastructure without baking either dependency in.
+
+## Features
+
+- Deduped peer set with the `maxPeers` admission cap enforced inside
+  `admit()` — `ROOM_FULL` outcomes increment the OTel counter and return a
+  discriminated `"rejected"`.
+- `touch(peerId)` updates `lastSeen` in place — used by heartbeats.
+- `pruneStale(timeoutMs)` iterates the map once per cleanup tick and drops
+  every peer past TTL, emitting `peerjs:peer-lost` for each.
+- Optional bus emissions on every state transition (`peerjs:peer-discovered`,
+  `peerjs:peer-lost`).
+- Optional `ServiceRegistry` integration — discovered peers are registered as
+  `peerjs:<room>` services keyed by peer id, deregistered on drop.
+
+## Usage: Basic Example
+
+```ts
+import { RoomManager } from "@suaveplan/network-discovery-peerjs/room-manager";
+
+const room = new RoomManager(() => Date.now(), "demo", 100, undefined, undefined);
+const action = room.admit({ id: "alpha", addresses: [], metadata: {}, lastSeen: Date.now() });
+// action === "added"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { RoomManager } from "@suaveplan/network-discovery-peerjs";
+import { ServiceRegistry } from "@suaveplan/service-discovery";
+import { EventBus } from "@suaveplan/events";
+
+const bus = new EventBus<import("@suaveplan/network-discovery-peerjs/types").PeerJSEventMap>();
+const registry = new ServiceRegistry({ maxServices: 1000, ttlMs: 60_000 });
+const room = new RoomManager(() => Date.now(), "alpha", 50, bus, registry);
+
+bus.on("peerjs:peer-lost", (e) => console.log("lost", e.peerId));
+
+// every announce arriving from the wire:
+room.admit(record);
+// every heartbeat:
+room.touch(record.id);
+// once per cleanup tick:
+const dropped = room.pruneStale(60_000);
+```
+
+## API Reference
+
+- `new RoomManager(clock, room, maxPeers, bus?, registry?)`.
+- `getPeers(): ReadonlyMap<string, PeerJSPeerRecord>`.
+- `listPeers(): readonly PeerJSPeerRecord[]`.
+- `getPeer(peerId): PeerJSPeerRecord | undefined`.
+- `size(): number`.
+- `admit(record): "added" | "refreshed" | "rejected"`.
+- `touch(peerId): boolean` — `false` if peer unknown.
+- `drop(peerId): boolean` — `false` if peer unknown.
+- `pruneStale(timeoutMs): number` — count dropped.
+- `clear(): void` — drop every peer.
+
+## Implementation Notes
+
+`admit` writes a fresh record (spread-copy) on first admission to seal the
+`metadata` and `capabilities` references against caller mutation, then
+mutates `lastSeen` in place on subsequent refreshes to keep the hot heartbeat
+path allocation-free. Pruning is done in a single pass over `entries()` and
+uses `drop()` so emissions and registry deregistration stay consistent with
+manual drops. The registry's `address` defaults to the first multiaddr or
+falls back to the peer id so `ServiceRegistry.register` never rejects on an
+empty `address` field.

packages/networking/network/network-discovery-peerjs/src/core/room-manager/room-manager.test.ts

@@ -0,0 +1,183 @@
+import { EventBus } from "@suaveplan/events";
+import { ServiceRegistry } from "@suaveplan/service-discovery";
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import fc from "fast-check";
+import type { PeerJSEventMap, PeerJSPeerRecord } from "../../types/types.js";
+import { RoomManager } from "./room-manager.js";
+
+function record(id: string, lastSeen = 100): PeerJSPeerRecord {
+    return {
+        id,
+        addresses: [`addr-${id}`],
+        metadata: { tag: id },
+        capabilities: ["v1"],
+        lastSeen,
+    };
+}
+
+describe("RoomManager", () => {
+    it("admits a new peer and emits peerjs:peer-discovered", {
+        timeout: 5000,
+    }, () => {
+        const bus = new EventBus<PeerJSEventMap>();
+        const events: string[] = [];
+        bus.on("peerjs:peer-discovered", (e) => events.push(e.peer.id));
+        const room = new RoomManager(() => 1000, "demo", 10, bus, undefined);
+        expect(room.admit(record("a"))).toBe("added");
+        expect(events).toEqual(["a"]);
+        expect(room.size()).toBe(1);
+        expect(room.getPeer("a")?.lastSeen).toBe(1000);
+    });
+
+    it("refreshes an existing peer in place", { timeout: 5000 }, () => {
+        let now = 1000;
+        const room = new RoomManager(
+            () => now,
+            "demo",
+            10,
+            undefined,
+            undefined
+        );
+        room.admit(record("a"));
+        now = 5000;
+        expect(room.admit(record("a"))).toBe("refreshed");
+        expect(room.getPeer("a")?.lastSeen).toBe(5000);
+    });
+
+    it("rejects admission past maxPeers", { timeout: 5000 }, () => {
+        const room = new RoomManager(() => 0, "demo", 2, undefined, undefined);
+        room.admit(record("a"));
+        room.admit(record("b"));
+        expect(room.admit(record("c"))).toBe("rejected");
+        expect(room.size()).toBe(2);
+    });
+
+    it("touch returns false for unknown peer", { timeout: 5000 }, () => {
+        const room = new RoomManager(() => 0, "demo", 10, undefined, undefined);
+        expect(room.touch("ghost")).toBe(false);
+    });
+
+    it("touch updates lastSeen for known peer", { timeout: 5000 }, () => {
+        let now = 1000;
+        const room = new RoomManager(
+            () => now,
+            "demo",
+            10,
+            undefined,
+            undefined
+        );
+        room.admit(record("a"));
+        now = 2000;
+        expect(room.touch("a")).toBe(true);
+        expect(room.getPeer("a")?.lastSeen).toBe(2000);
+    });
+
+    it("drop emits peer-lost and deregisters", { timeout: 5000 }, () => {
+        const bus = new EventBus<PeerJSEventMap>();
+        const lost: string[] = [];
+        bus.on("peerjs:peer-lost", (e) => lost.push(e.peerId));
+        const registry = new ServiceRegistry();
+        const room = new RoomManager(() => 0, "demo", 10, bus, registry);
+        room.admit(record("a"));
+        expect(registry.get("a")).toBeDefined();
+        expect(room.drop("a")).toBe(true);
+        expect(lost).toEqual(["a"]);
+        expect(registry.get("a")).toBeUndefined();
+        expect(room.drop("a")).toBe(false);
+    });
+
+    it("pruneStale drops peers past TTL", { timeout: 5000 }, () => {
+        let now = 100;
+        const room = new RoomManager(
+            () => now,
+            "demo",
+            10,
+            undefined,
+            undefined
+        );
+        room.admit(record("a"));
+        room.admit(record("b"));
+        now = 800;
+        room.touch("a"); // a refreshed to 800; b still at 100
+        now = 1500;
+        const dropped = room.pruneStale(1000);
+        expect(dropped).toBe(1);
+        expect(room.getPeer("a")).toBeDefined();
+        expect(room.getPeer("b")).toBeUndefined();
+    });
+
+    it("clear drops every peer", { timeout: 5000 }, () => {
+        const room = new RoomManager(() => 0, "demo", 10, undefined, undefined);
+        room.admit(record("a"));
+        room.admit(record("b"));
+        room.clear();
+        expect(room.size()).toBe(0);
+    });
+
+    it("listPeers returns a snapshot", { timeout: 5000 }, () => {
+        const room = new RoomManager(() => 0, "demo", 10, undefined, undefined);
+        room.admit(record("a"));
+        const snap = room.listPeers();
+        expect(snap.map((p) => p.id)).toEqual(["a"]);
+    });
+
+    it("getPeers returns the live map", { timeout: 5000 }, () => {
+        const room = new RoomManager(() => 0, "demo", 10, undefined, undefined);
+        room.admit(record("a"));
+        expect(room.getPeers().size).toBe(1);
+    });
+
+    it("uses peer id as registry address when addresses empty", {
+        timeout: 5000,
+    }, () => {
+        const registry = new ServiceRegistry();
+        const room = new RoomManager(() => 0, "demo", 10, undefined, registry);
+        room.admit({
+            id: "alpha",
+            addresses: [],
+            metadata: {},
+            lastSeen: 0,
+        });
+        expect(registry.get("alpha")?.address).toBe("alpha");
+    });
+
+    it("property: room.size() never exceeds maxPeers under admit+drop sequences", {
+        timeout: 5000,
+    }, () => {
+        fc.assert(
+            fc.property(
+                fc.integer({ min: 1, max: 20 }),
+                fc.array(
+                    fc.tuple(
+                        fc.constantFrom("admit", "drop"),
+                        fc.string({ minLength: 1, maxLength: 4 })
+                    ),
+                    { maxLength: 200 }
+                ),
+                (cap, ops) => {
+                    const room = new RoomManager(
+                        () => 0,
+                        "p",
+                        cap,
+                        undefined,
+                        undefined
+                    );
+                    for (const [op, id] of ops) {
+                        if (op === "admit") {
+                            room.admit({
+                                id,
+                                addresses: [],
+                                metadata: {},
+                                lastSeen: 0,
+                            });
+                        } else {
+                            room.drop(id);
+                        }
+                    }
+                    return room.size() <= cap;
+                }
+            ),
+            { numRuns: 100 }
+        );
+    });
+});

packages/networking/network/network-discovery-peerjs/src/core/room-manager/room-manager.ts

@@ -0,0 +1,130 @@
+import type { ServiceRegistry } from "@suaveplan/service-discovery";
+import type { Clock, EventBusLike } from "@suaveplan/types";
+import { recordPeersDiscovered } from "../../otel/otel.js";
+import type { PeerJSEventMap, PeerJSPeerRecord } from "../../types/types.js";
+
+/**
+ * Per-strategy view of the logical room: a deduped, TTL-tracked map of
+ * `PeerJSPeerRecord`s, with hooks to mirror state into an optional
+ * `EventBusLike` and an optional `ServiceRegistry`. The orchestrator owns
+ * connection lifecycle; the room manager owns peer-set semantics.
+ */
+export class RoomManager {
+    private readonly discoveredPeers = new Map<string, PeerJSPeerRecord>();
+
+    public constructor(
+        private readonly clock: Clock,
+        private readonly room: string,
+        private readonly maxPeers: number,
+        private readonly bus: EventBusLike<PeerJSEventMap> | undefined,
+        private readonly registry: ServiceRegistry | undefined
+    ) {}
+
+    /** Live peer map — caller MUST NOT mutate. */
+    public getPeers(): ReadonlyMap<string, PeerJSPeerRecord> {
+        return this.discoveredPeers;
+    }
+
+    /** Snapshot of currently tracked peers. */
+    public listPeers(): readonly PeerJSPeerRecord[] {
+        return Array.from(this.discoveredPeers.values());
+    }
+
+    /** Get a tracked peer by id, or `undefined`. */
+    public getPeer(peerId: string): PeerJSPeerRecord | undefined {
+        return this.discoveredPeers.get(peerId);
+    }
+
+    /** Number of tracked peers. */
+    public size(): number {
+        return this.discoveredPeers.size;
+    }
+
+    /**
+     * Admit (or refresh) a peer. Returns the action taken: `"added"`,
+     * `"refreshed"`, or `"rejected"` (room full). Emits the matching bus
+     * event and increments the OTel counter.
+     */
+    public admit(record: PeerJSPeerRecord): "added" | "refreshed" | "rejected" {
+        const existing = this.discoveredPeers.get(record.id);
+        if (existing === undefined) {
+            if (this.discoveredPeers.size >= this.maxPeers) {
+                recordPeersDiscovered("rejected");
+                return "rejected";
+            }
+            const fresh: PeerJSPeerRecord = {
+                ...record,
+                lastSeen: this.clock(),
+            };
+            this.discoveredPeers.set(record.id, fresh);
+            recordPeersDiscovered("found");
+            this.bus?.emit("peerjs:peer-discovered", {
+                peer: fresh,
+                at: fresh.lastSeen,
+            });
+            this.registry?.register({
+                id: fresh.id,
+                name: `peerjs:${this.room}`,
+                address: fresh.addresses[0] ?? fresh.id,
+                metadata: fresh.metadata,
+                ...(fresh.capabilities !== undefined
+                    ? { tags: fresh.capabilities }
+                    : {}),
+            });
+            return "added";
+        }
+        existing.lastSeen = this.clock();
+        recordPeersDiscovered("duplicate");
+        return "refreshed";
+    }
+
+    /** Update only the `lastSeen` timestamp; ignore unknown peers. */
+    public touch(peerId: string): boolean {
+        const peer = this.discoveredPeers.get(peerId);
+        if (peer === undefined) return false;
+        peer.lastSeen = this.clock();
+        return true;
+    }
+
+    /**
+     * Drop a peer. Emits `peerjs:peer-lost` and deregisters from the registry
+     * iff the peer was actually present.
+     */
+    public drop(peerId: string): boolean {
+        if (!this.discoveredPeers.delete(peerId)) return false;
+        this.bus?.emit("peerjs:peer-lost", {
+            peerId,
+            at: this.clock(),
+        });
+        this.registry?.deregister(peerId);
+        return true;
+    }
+
+    /**
+     * Drop every peer whose `lastSeen` is older than `now - timeoutMs`.
+     * Returns the count of peers dropped.
+     */
+    public pruneStale(timeoutMs: number): number {
+        const now = this.clock();
+        let dropped = 0;
+        const stale: string[] = [];
+        for (const [peerId, peer] of this.discoveredPeers.entries()) {
+            if (now - peer.lastSeen > timeoutMs) {
+                stale.push(peerId);
+            }
+        }
+        let dropped_inner = 0;
+        for (const id of stale) {
+            this.drop(id);
+            dropped_inner += 1;
+        }
+        dropped = dropped_inner;
+        return dropped;
+    }
+
+    /** Drop every peer, emitting `peerjs:peer-lost` for each. */
+    public clear(): void {
+        const ids = Array.from(this.discoveredPeers.keys());
+        for (const id of ids) this.drop(id);
+    }
+}

packages/networking/network/network-discovery-peerjs/src/errors/errors.md

@@ -0,0 +1,78 @@
+# errors
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Structured-error registry for `@suaveplan/network-discovery-peerjs`. Defines the
+five frozen `NET_DISC_PEERJS_*` codes every public boundary uses and the
+`NetDiscPeerJSError` class that wraps them with `SuaveplanError`'s standard
+chained-cause + i18n-key plumbing. Centralising the registry here keeps every
+throw site consistent and makes branching on `error.code` reliable across the
+package and any downstream `network-bootstrap` chain consuming the strategy.
+
+## Features
+
+- Frozen `defineCodes("NET_DISC_PEERJS", [...])` registry — code names are
+  string-literal types, not arbitrary strings.
+- `NetDiscPeerJSError` extends `SuaveplanError` with the discriminated code type.
+- Stable code surface for downstream callers that switch on `error.code`.
+
+## Usage: Basic Example
+
+```ts
+import {
+    NET_DISC_PEERJS_CODES,
+    NetDiscPeerJSError,
+} from "@suaveplan/network-discovery-peerjs";
+
+throw new NetDiscPeerJSError(
+    NET_DISC_PEERJS_CODES.INVALID_OPTIONS,
+    "errors.peerjs.invalid_options"
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    NET_DISC_PEERJS_CODES,
+    NetDiscPeerJSError,
+    type NetDiscPeerJSErrorCode,
+} from "@suaveplan/network-discovery-peerjs";
+
+function classify(err: unknown): NetDiscPeerJSErrorCode | "unknown" {
+    if (err instanceof NetDiscPeerJSError) return err.code;
+    return "unknown";
+}
+
+try {
+    await discovery.start();
+} catch (err) {
+    const code = classify(err);
+    if (code === NET_DISC_PEERJS_CODES.SIGNALING_FAILED) {
+        // back off + retry against an alternate broker URL
+    }
+}
+```
+
+## API Reference
+
+- `NET_DISC_PEERJS_CODES` — frozen record with five members:
+  `SIGNALING_FAILED`, `PEER_CONNECT_FAILED`, `ROOM_FULL`, `INVALID_OPTIONS`,
+  `DISPOSED`.
+- `NetDiscPeerJSErrorCode` — string-literal union derived from the registry.
+- `NetDiscPeerJSError(code, messageKey, options?)` — `SuaveplanError` subclass.
+  Accepts the standard `SuaveplanErrorOptions` (cause, params, redaction).
+
+## Implementation Notes
+
+`SIGNALING_FAILED` is the wrapper for any error PeerJS surfaces during the
+initial `peer.on("error")` handshake. `PEER_CONNECT_FAILED` is reserved for
+post-handshake `peer.connect(...)` failures so call-sites can tell apart
+"broker unreachable" from "specific peer unreachable". `ROOM_FULL` is emitted
+proactively when the `maxPeers` cap would be exceeded — the strategy refuses
+the new peer rather than evicting an existing one to keep room semantics
+predictable. `DISPOSED` is thrown by every public method after `stop()` so
+that lifecycle bugs surface loudly instead of silently no-op-ing.

packages/networking/network/network-discovery-peerjs/src/errors/errors.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { NET_DISC_PEERJS_CODES, NetDiscPeerJSError } from "./errors.js";
+
+describe("NET_DISC_PEERJS_CODES", () => {
+    it("exposes the five documented codes", { timeout: 5000 }, () => {
+        expect(NET_DISC_PEERJS_CODES.SIGNALING_FAILED).toBe(
+            "NET_DISC_PEERJS.SIGNALING_FAILED"
+        );
+        expect(NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED).toBe(
+            "NET_DISC_PEERJS.PEER_CONNECT_FAILED"
+        );
+        expect(NET_DISC_PEERJS_CODES.ROOM_FULL).toBe(
+            "NET_DISC_PEERJS.ROOM_FULL"
+        );
+        expect(NET_DISC_PEERJS_CODES.INVALID_OPTIONS).toBe(
+            "NET_DISC_PEERJS.INVALID_OPTIONS"
+        );
+        expect(NET_DISC_PEERJS_CODES.DISPOSED).toBe("NET_DISC_PEERJS.DISPOSED");
+    });
+});
+
+describe("NetDiscPeerJSError", () => {
+    it("preserves code, name, and message-key", { timeout: 5000 }, () => {
+        const err = new NetDiscPeerJSError(
+            NET_DISC_PEERJS_CODES.INVALID_OPTIONS,
+            "errors.peerjs.invalid_options"
+        );
+        expect(err.code).toBe("NET_DISC_PEERJS.INVALID_OPTIONS");
+        expect(err.name).toBe("NetDiscPeerJSError");
+    });
+    it("threads a cause", { timeout: 5000 }, () => {
+        const cause = new Error("upstream");
+        const err = new NetDiscPeerJSError(
+            NET_DISC_PEERJS_CODES.SIGNALING_FAILED,
+            "errors.peerjs.signaling_failed",
+            { cause }
+        );
+        expect(err.cause).toBe(cause);
+    });
+});

packages/networking/network/network-discovery-peerjs/src/errors/errors.ts

@@ -0,0 +1,47 @@
+import {
+    defineCodes,
+    SuaveplanError,
+    type SuaveplanErrorOptions,
+} from "@suaveplan/error";
+
+/**
+ * Error codes emitted by `@suaveplan/network-discovery-peerjs`.
+ *
+ * - `SIGNALING_FAILED` — PeerJS signalling server could not be reached or
+ *   returned an error during `peer.open`.
+ * - `PEER_CONNECT_FAILED` — `peer.connect(targetId)` threw or never opened.
+ * - `ROOM_FULL` — incoming peer would push the room past `maxPeers`.
+ * - `INVALID_OPTIONS` — caller supplied an option struct that failed Zod
+ *   validation (most commonly missing `host`).
+ * - `DISPOSED` — operation attempted after `stop()` / disposal.
+ */
+export const NET_DISC_PEERJS_CODES = defineCodes("NET_DISC_PEERJS", [
+    "SIGNALING_FAILED",
+    "PEER_CONNECT_FAILED",
+    "ROOM_FULL",
+    "INVALID_OPTIONS",
+    "DISPOSED",
+    "PEER_ALREADY_CONNECTED",
+    "PEER_UNKNOWN",
+    "TRANSPORT_CLOSED",
+    "SEND_FAILED",
+    "ABORTED",
+] as const);
+
+export type NetDiscPeerJSErrorCode =
+    (typeof NET_DISC_PEERJS_CODES)[keyof typeof NET_DISC_PEERJS_CODES];
+
+/**
+ * Structured error class for the PeerJS discovery strategy. Every public
+ * boundary throws this on failure; consumers branch on `error.code`.
+ */
+export class NetDiscPeerJSError extends SuaveplanError<NetDiscPeerJSErrorCode> {
+    public constructor(
+        code: NetDiscPeerJSErrorCode,
+        messageKey: string,
+        options?: SuaveplanErrorOptions
+    ) {
+        super(code, messageKey, options);
+        this.name = "NetDiscPeerJSError";
+    }
+}

packages/networking/network/network-discovery-peerjs/src/index.ts

@@ -0,0 +1,73 @@
+// Core
+export { PeerConnectionManager } from "./core/peer-connection-manager/peer-connection-manager.js";
+export {
+    broadcastMessage,
+    connectToPeer,
+    handleConnection,
+    initializePeer,
+} from "./core/peerjs-connection/peerjs-connection.js";
+export { PeerJSDiscovery } from "./core/peerjs-discovery/peerjs-discovery.js";
+export {
+    type PeerJSIntervalDeps,
+    PeerJSIntervals,
+} from "./core/peerjs-intervals/peerjs-intervals.js";
+export {
+    handleMessage,
+    type PeerJSMessageHandlerDeps,
+} from "./core/peerjs-message-handlers/peerjs-message-handlers.js";
+export { RoomManager } from "./core/room-manager/room-manager.js";
+
+// Errors
+export {
+    NET_DISC_PEERJS_CODES,
+    NetDiscPeerJSError,
+    type NetDiscPeerJSErrorCode,
+} from "./errors/errors.js";
+
+// OTel
+export {
+    adjustTransportActivePeers,
+    type PeerDiscoveryOutcome,
+    recordPeersDiscovered,
+    recordSignalingDuration,
+    recordTransportMessage,
+    type TransportMessageDirection,
+    type TransportMessageOutcome,
+    withStartSpan,
+    withTransportSpan,
+} from "./otel/otel.js";
+
+// Plugin
+export { PeerJSPlugin } from "./plugin/plugin.js";
+
+// Transport
+export { PeerJSTransport } from "./transport/transport.js";
+
+// Types
+export type {
+    DataConnectionLike,
+    PeerFactory,
+    PeerJSDiscoveredEvent,
+    PeerJSDiscoveryConfig,
+    PeerJSEventMap,
+    PeerJSLostEvent,
+    PeerJSMessage,
+    PeerJSMessageTypeValue,
+    PeerJSPeerMetadata,
+    PeerJSPeerOptions,
+    PeerJSPeerRecord,
+    PeerJSSignalingFailedEvent,
+    PeerJSStartedEvent,
+    PeerJSTransportConfig,
+    PeerJSTransportFrame,
+    PeerLike,
+    ResolvedPeerJSDiscoveryConfig,
+} from "./types/types.js";
+export { PeerJSMessageType } from "./types/types.js";
+
+// Schemas
+export {
+    PeerJSDiscoveryConfigSchema,
+    PeerJSMessageSchema,
+    PeerJSPeerMetadataSchema,
+} from "./types/types.schemas.js";

packages/networking/network/network-discovery-peerjs/src/otel/otel.md

@@ -0,0 +1,101 @@
+# otel
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+OpenTelemetry surface for `@suaveplan/network-discovery-peerjs`. Owns the
+tracer, meter, and instrument handles used by the strategy and its supporting
+modules so every signal in the package is namespaced consistently
+(`disc_peerjs.*`). Centralising instrument creation here prevents accidental
+duplicate-instrument warnings from the OTel SDK when multiple modules want to
+record the same metric.
+
+## Features
+
+- `withStartSpan(fn)` wraps `PeerJSDiscovery.start()` in an active span called
+  `disc_peerjs.start`, exposing the live span to the caller for attribute
+  enrichment.
+- `recordPeersDiscovered(outcome, count?)` counter — labelled by `outcome` to
+  distinguish fresh peers (`found`), repeats (`duplicate`), and `ROOM_FULL`
+  rejections (`rejected`).
+- `recordSignalingDuration(ms)` histogram of broker-handshake wall time.
+- `withTransportSpan(name, fn)` wraps transport-tier async operations
+  (`peerjs_transport.connect`, `peerjs_transport.disconnect`,
+  `peerjs_transport.send`) in active spans.
+- `recordTransportMessage(direction, outcome)` counter labelled by
+  `direction` (`inbound` / `outbound`) and `outcome` (`ok` / `error`).
+- `adjustTransportActivePeers(delta)` up-down counter exposed as a gauge of
+  currently-connected transport peers.
+- Single shared `tracer` + `meter` instance with stable names.
+
+## Usage: Basic Example
+
+```ts
+import {
+    recordPeersDiscovered,
+    recordSignalingDuration,
+    withStartSpan,
+} from "@suaveplan/network-discovery-peerjs";
+
+await withStartSpan(async (span) => {
+    span.setAttribute("room", "demo");
+    const t = performance.now();
+    // ...open peer...
+    recordSignalingDuration(performance.now() - t);
+    recordPeersDiscovered("found", 1);
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { withStartSpan, recordPeersDiscovered } from "@suaveplan/network-discovery-peerjs";
+
+async function discoverWithBudget(timeoutMs: number) {
+    return withStartSpan(async (span) => {
+        span.setAttribute("budget_ms", timeoutMs);
+        const start = performance.now();
+        try {
+            const peers = await openSignalling(timeoutMs);
+            recordPeersDiscovered("found", peers.length);
+            return peers;
+        } catch (err) {
+            span.recordException(err as Error);
+            recordPeersDiscovered("rejected");
+            throw err;
+        } finally {
+            span.setAttribute("elapsed_ms", performance.now() - start);
+        }
+    });
+}
+```
+
+## API Reference
+
+- `withStartSpan<T>(fn: (span: Span) => Promise<T>): Promise<T>` — creates an
+  active span named `disc_peerjs.start`, ends it in `finally`.
+- `recordPeersDiscovered(outcome: "found"|"duplicate"|"rejected", count?)` —
+  increments the `disc_peerjs.peers_discovered_total` counter.
+- `recordSignalingDuration(ms: number)` — records into the
+  `disc_peerjs.signaling_duration_ms` histogram, clamping negative values to
+  zero.
+- `PeerDiscoveryOutcome` — exported string-literal union used by the counter.
+- `withTransportSpan<T>(name: string, fn: (span: Span) => Promise<T>): Promise<T>` —
+  active-span wrapper for transport-tier operations.
+- `recordTransportMessage(direction, outcome)` — increments
+  `peerjs_transport.messages_total`.
+- `adjustTransportActivePeers(delta)` — adjusts
+  `peerjs_transport.active_peers`. No-op when `delta === 0`.
+- `TransportMessageDirection` / `TransportMessageOutcome` — exported
+  string-literal unions.
+
+## Implementation Notes
+
+`outcome` keeps cardinality bounded to three values so downstream Prometheus
+dashboards remain efficient. The histogram clamps negative inputs because the
+strategy's signalling-duration measurement uses `Date.now()` differences that
+can occasionally drift on systems where NTP corrects the wall clock during a
+handshake. Tracer and meter names match the package name verbatim so the OTel
+resource attributes line up with the npm package id without further mapping.

packages/networking/network/network-discovery-peerjs/src/otel/otel.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    adjustTransportActivePeers,
+    recordPeersDiscovered,
+    recordSignalingDuration,
+    recordTransportMessage,
+    withStartSpan,
+    withTransportSpan,
+} from "./otel.js";
+
+describe("otel", () => {
+    it("withStartSpan resolves the inner value", {
+        timeout: 5000,
+    }, async () => {
+        const v = await withStartSpan(async () => 42);
+        expect(v).toBe(42);
+    });
+
+    it("withStartSpan ends the span when the inner throws", {
+        timeout: 5000,
+    }, async () => {
+        await expect(
+            withStartSpan(async () => {
+                throw new Error("boom");
+            })
+        ).rejects.toThrow("boom");
+    });
+
+    it("recordPeersDiscovered tolerates non-positive count", {
+        timeout: 5000,
+    }, () => {
+        recordPeersDiscovered("found", 0);
+        recordPeersDiscovered("found", -1);
+        recordPeersDiscovered("found");
+        recordPeersDiscovered("duplicate");
+        recordPeersDiscovered("rejected");
+    });
+
+    it("recordSignalingDuration clamps negative durations", {
+        timeout: 5000,
+    }, () => {
+        recordSignalingDuration(-5);
+        recordSignalingDuration(123);
+    });
+
+    it("withTransportSpan resolves the inner value", {
+        timeout: 5000,
+    }, async () => {
+        const v = await withTransportSpan(
+            "peerjs_transport.connect",
+            async () => "ok"
+        );
+        expect(v).toBe("ok");
+    });
+
+    it("withTransportSpan ends the span when the inner throws", {
+        timeout: 5000,
+    }, async () => {
+        await expect(
+            withTransportSpan("peerjs_transport.send", async () => {
+                throw new Error("boom");
+            })
+        ).rejects.toThrow("boom");
+    });
+
+    it("recordTransportMessage tallies every label combination", {
+        timeout: 5000,
+    }, () => {
+        recordTransportMessage("inbound", "ok");
+        recordTransportMessage("inbound", "error");
+        recordTransportMessage("outbound", "ok");
+        recordTransportMessage("outbound", "error");
+    });
+
+    it("adjustTransportActivePeers no-ops when delta is zero", {
+        timeout: 5000,
+    }, () => {
+        adjustTransportActivePeers(0);
+        adjustTransportActivePeers(1);
+        adjustTransportActivePeers(-1);
+    });
+});

packages/networking/network/network-discovery-peerjs/src/otel/otel.ts

@@ -0,0 +1,152 @@
+import { metrics, type Span, type Tracer, trace } from "@opentelemetry/api";
+
+const TRACER_NAME = "@suaveplan/network-discovery-peerjs";
+const METER_NAME = "@suaveplan/network-discovery-peerjs";
+
+const tracer: Tracer = trace.getTracer(TRACER_NAME);
+const meter = metrics.getMeter(METER_NAME);
+
+/**
+ * Counter incremented for every peer the strategy emits, labelled by the
+ * outcome of the discovery attempt (`found` for fresh peers, `duplicate` for
+ * peers already seen, `rejected` for `ROOM_FULL`).
+ */
+const peersDiscoveredCounter = meter.createCounter(
+    "disc_peerjs.peers_discovered_total",
+    {
+        description:
+            "Total peers seen by the PeerJS discovery strategy, by outcome.",
+    }
+);
+
+/**
+ * Histogram of signalling-server connection durations (ms). Records the time
+ * from `peer.connect()` until `peer.on('open')`.
+ */
+const signalingDurationHistogram = meter.createHistogram(
+    "disc_peerjs.signaling_duration_ms",
+    {
+        description: "Signalling-server handshake duration in milliseconds.",
+        unit: "ms",
+    }
+);
+
+/**
+ * Wrap the `start()` body in an OTel span. The caller's function receives the
+ * live span so it can attach attributes (e.g. resolved peer id, room name).
+ *
+ * @param fn - Async body.
+ * @returns The body's resolved value.
+ */
+export async function withStartSpan<T>(
+    fn: (span: Span) => Promise<T>
+): Promise<T> {
+    return tracer.startActiveSpan("disc_peerjs.start", async (span) => {
+        try {
+            return await fn(span);
+        } finally {
+            span.end();
+        }
+    });
+}
+
+/**
+ * Outcome label for {@link recordPeersDiscovered}.
+ */
+export type PeerDiscoveryOutcome = "found" | "duplicate" | "rejected";
+
+/**
+ * Increment the peers-discovered counter.
+ *
+ * @param outcome - Discovery outcome.
+ * @param count - Increment delta (default 1).
+ */
+export function recordPeersDiscovered(
+    outcome: PeerDiscoveryOutcome,
+    count = 1
+): void {
+    if (count > 0) {
+        peersDiscoveredCounter.add(count, { outcome });
+    }
+}
+
+/**
+ * Record the wall-clock duration of a signalling-server handshake.
+ *
+ * @param ms - Elapsed milliseconds.
+ */
+export function recordSignalingDuration(ms: number): void {
+    signalingDurationHistogram.record(Math.max(0, ms));
+}
+
+/**
+ * Counter tallying transport-level message-flow events, labelled by direction
+ * (`inbound` / `outbound`) and outcome (`ok` / `error`).
+ */
+const transportMessagesCounter = meter.createCounter(
+    "peerjs_transport.messages_total",
+    {
+        description:
+            "Total messages sent/received on PeerJSTransport, by direction and outcome.",
+    }
+);
+
+/**
+ * Up-down counter exposed as a gauge for the current number of connected peers
+ * on the PeerJSTransport.
+ */
+const transportActivePeersGauge = meter.createUpDownCounter(
+    "peerjs_transport.active_peers",
+    {
+        description: "Current number of connected peers on PeerJSTransport.",
+    }
+);
+
+/**
+ * Wrap a transport-level async operation in an OTel span.
+ *
+ * @param name - Span name such as `peerjs_transport.connect`.
+ * @param fn - Async body; receives the live span.
+ * @returns The body's resolved value.
+ */
+export async function withTransportSpan<T>(
+    name: string,
+    fn: (span: Span) => Promise<T>
+): Promise<T> {
+    return tracer.startActiveSpan(name, async (span) => {
+        try {
+            return await fn(span);
+        } finally {
+            span.end();
+        }
+    });
+}
+
+/**
+ * Direction label for {@link recordTransportMessage}.
+ */
+export type TransportMessageDirection = "inbound" | "outbound";
+
+/**
+ * Outcome label for {@link recordTransportMessage}.
+ */
+export type TransportMessageOutcome = "ok" | "error";
+
+/**
+ * Record a transport-level message-flow event.
+ */
+export function recordTransportMessage(
+    direction: TransportMessageDirection,
+    outcome: TransportMessageOutcome
+): void {
+    transportMessagesCounter.add(1, { direction, outcome });
+}
+
+/**
+ * Adjust the active-peers gauge by `delta` (e.g. `+1` on connect, `-1` on
+ * disconnect).
+ */
+export function adjustTransportActivePeers(delta: number): void {
+    if (delta === 0) return;
+    transportActivePeersGauge.add(delta);
+}

packages/networking/network/network-discovery-peerjs/src/plugin/plugin.md

@@ -0,0 +1,107 @@
+# plugin
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`PeerJSPlugin` is the thin `NetworkPlugin` lifecycle wrapper that mounts
+`PeerJSTransport` onto a `@suaveplan/network` `NetworkNode`. It mirrors the
+canonical `WebRTCPlugin` / `WebSocketPlugin` shape: construct → install →
+start (no-op) → stop (closes transport + unregisters) → dispose (drops the
+node reference).
+
+The plugin pairs with the rest of this package — the same `PeerLike` the
+transport opens can serve a `PeerJSDiscovery` instance side-by-side because
+the transport's wire frame uses a discriminator (`"suaveplan.transport.v1"`)
+that the discovery Zod schema explicitly rejects. Discovery + transport on a
+single PeerJS unit was the upstream model and is preserved here by folding
+both into one package.
+
+## Features
+
+- `name: "peerjs"` lookup key.
+- Constructs and owns one `PeerJSTransport` from a `PeerJSTransportConfig`.
+- `install(node)` calls `node.registerTransport(transport)`.
+- `start()` is a no-op (transport is lazy).
+- `stop()` closes the transport and unregisters it from the node.
+- `dispose()` drops the cached `NetworkNode` reference; safe to call
+  before `install` or twice in a row.
+
+## Usage: Basic Example
+
+```ts
+import { NetworkNode } from "@suaveplan/network";
+import { PeerJSPlugin } from "@suaveplan/network-discovery-peerjs/plugin";
+
+const node = new NetworkNode();
+node.use(
+    new PeerJSPlugin({
+        host: "signalling.example.com",
+        peerFactory: makePeerFactory(),
+    })
+);
+await node.start();
+// ... use node.send / node.broadcast ...
+await node.stop();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { NetworkNode } from "@suaveplan/network";
+import { PeerJSPlugin } from "@suaveplan/network-discovery-peerjs/plugin";
+
+const plugin = new PeerJSPlugin({
+    host: "signalling.example.com",
+    port: 443,
+    path: "/",
+    secure: true,
+    iceServers: [
+        { urls: "stun:stun.example.com:3478" },
+        {
+            urls: "turn:turn.example.com:3478",
+            username: "u",
+            credential: "p",
+        },
+    ],
+    peerId: "alice",
+    debug: 0,
+    peerFactory: makePeerFactory(),
+});
+
+const node = new NetworkNode();
+plugin.install(node);
+plugin.start();
+
+// Direct access to the transport for connect / disconnect.
+await plugin.transport.connect("bob", "ignored");
+plugin.transport.onPeerEvent((peerId, event) => {
+    console.log(`peer ${peerId} ${event}`);
+});
+
+await plugin.stop();
+plugin.dispose();
+```
+
+## API Reference
+
+- `class PeerJSPlugin implements NetworkPlugin`
+  - `readonly name = "peerjs"`.
+  - `readonly transport: PeerJSTransport`.
+  - `constructor(config: PeerJSTransportConfig)`.
+  - `install(node: NetworkNode): void`.
+  - `start(): void` — no-op.
+  - `stop(): Promise<void>` — idempotent close + unregister.
+  - `dispose(): void` — drops the node reference; idempotent.
+
+## Implementation Notes
+
+`install` caches the `NetworkNode` reference so `stop` can unregister the
+transport on tear-down even when the caller forgets to invoke `stop` via
+the node lifecycle. `dispose` clears that reference so the plugin can be
+garbage-collected after the node is released. The plugin deliberately does
+no eager broker connect — opening the signalling handshake on `start` would
+make `NetworkNode.start()` block on a remote service, which violates the
+upstream contract where `start` is synchronous-or-fast and connections are
+opened by the surrounding mesh / discovery plugins.

packages/networking/network/network-discovery-peerjs/src/plugin/plugin.spec-conformance.test.ts

@@ -0,0 +1,82 @@
+import { NetworkNode } from "@suaveplan/network";
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { FakeBroker, fakePeerFactory } from "../../tests/setup/fake-peerjs.js";
+import { PeerJSPlugin } from "./plugin.js";
+
+function makePlugin(): PeerJSPlugin {
+    return new PeerJSPlugin({
+        host: "h",
+        peerFactory: fakePeerFactory(new FakeBroker()),
+    });
+}
+
+describe("PeerJSPlugin", () => {
+    it("exposes the canonical plugin name", { timeout: 5000 }, () => {
+        const p = makePlugin();
+        expect(p.name).toBe("peerjs");
+    });
+
+    it("registers its transport with the node on install", {
+        timeout: 5000,
+    }, () => {
+        const node = new NetworkNode();
+        const plugin = makePlugin();
+        node.use(plugin);
+        const transports = node.messageRouter.getTransports();
+        expect(transports.map((t) => t.id)).toContain("peerjs");
+    });
+
+    it("start() is a no-op", { timeout: 5000 }, async () => {
+        const node = new NetworkNode();
+        const plugin = makePlugin();
+        node.use(plugin);
+        await node.start();
+        expect(node.isStarted).toBe(true);
+        await node.stop();
+    });
+
+    it("stop() closes the transport and unregisters it from the node", {
+        timeout: 5000,
+    }, async () => {
+        const node = new NetworkNode();
+        const plugin = makePlugin();
+        node.use(plugin);
+        await node.start();
+        await node.stop();
+        expect(
+            node.messageRouter.getTransports().map((t) => t.id)
+        ).not.toContain("peerjs");
+    });
+
+    it("dispose is idempotent", { timeout: 5000 }, () => {
+        const plugin = makePlugin();
+        const node = new NetworkNode();
+        plugin.install(node);
+        plugin.dispose();
+        plugin.dispose();
+    });
+
+    it("stop is safe to call when no node was installed", {
+        timeout: 5000,
+    }, async () => {
+        const plugin = makePlugin();
+        await plugin.stop();
+    });
+
+    it("forwards PeerJSTransportConfig to the transport", {
+        timeout: 5000,
+    }, () => {
+        const plugin = new PeerJSPlugin({
+            host: "h",
+            port: 8443,
+            path: "/peer",
+            secure: false,
+            debug: 2,
+            peerId: "explicit-id",
+            iceServers: [{ urls: "stun:stun.example.com:3478" }],
+            key: "api-key",
+            peerFactory: fakePeerFactory(new FakeBroker()),
+        });
+        expect(plugin.transport.id).toBe("peerjs");
+    });
+});

packages/networking/network/network-discovery-peerjs/src/plugin/plugin.ts

@@ -0,0 +1,43 @@
+import type { NetworkNode, NetworkPlugin } from "@suaveplan/network";
+import { PeerJSTransport } from "../transport/transport.js";
+import type { PeerJSTransportConfig } from "../types/types.js";
+
+/**
+ * Network plugin that exposes a `PeerJSTransport` to the host `NetworkNode`.
+ *
+ * - `install(node)` registers the transport with the node so the router can
+ *   find it by id.
+ * - `start()` is a no-op — the broker handshake is opened lazily by the
+ *   first `transport.connect()`.
+ * - `stop()` closes the transport and unregisters it from the node so the
+ *   next `install` is idempotent.
+ * - `dispose()` releases the cached node reference.
+ */
+export class PeerJSPlugin implements NetworkPlugin {
+    public readonly name = "peerjs";
+    public readonly transport: PeerJSTransport;
+    #node: NetworkNode | null = null;
+
+    public constructor(config: PeerJSTransportConfig) {
+        this.transport = new PeerJSTransport(config);
+    }
+
+    public install(node: NetworkNode): void {
+        this.#node = node;
+        node.registerTransport(this.transport);
+    }
+
+    public start(): void {
+        // No eager work — the transport opens the broker handshake on the
+        // first `connect()` call.
+    }
+
+    public async stop(): Promise<void> {
+        await this.transport.close();
+        this.#node?.unregisterTransport(this.transport.id);
+    }
+
+    public dispose(): void {
+        this.#node = null;
+    }
+}

packages/networking/network/network-discovery-peerjs/src/transport/transport.md

@@ -0,0 +1,147 @@
+# transport
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`PeerJSTransport` adapts the PeerJS WebRTC stack to the
+`@suaveplan/network` mesh `Transport` contract. It lazy-initializes a single
+local `PeerLike` against a configured signalling broker, then opens one
+`DataConnectionLike` per remote peer and routes `MessageEnvelope` traffic
+through a small wire frame (`{kind: "suaveplan.transport.v1", envelope}`) so
+the same `PeerLike` can host concurrent discovery traffic from the rest of
+this package without confusion.
+
+The transport composes the existing primitives in this package
+(`initializePeer`, `connectToPeer`, `handleConnection`) rather than reaching
+into raw `peerjs` APIs, which keeps the migrated unit byte-identical to the
+upstream integrated discovery + transport bundle.
+
+## Features
+
+- Single `Transport` implementation with `id: "peerjs"`.
+- Lazy broker connect — the first `connect()` opens the signalling
+  handshake; subsequent connects reuse the same `PeerLike`.
+- Per-peer `DataConnectionLike` registry with `connect` / `disconnect` /
+  `send` / `onMessage` / `onPeerEvent` / `getConnectedPeers` / `close`.
+- Pre-aborted `AbortSignal` rejected with `ABORTED`; mid-handshake aborts
+  surface the same code.
+- Frame discriminator ensures discovery-only peers ignore transport bytes.
+- OTel: `peerjs_transport.connect` / `disconnect` / `send` spans,
+  `peerjs_transport.messages_total{direction,outcome}` counter,
+  `peerjs_transport.active_peers` gauge.
+
+## Usage: Basic Example
+
+```ts
+import { PeerJSTransport } from "@suaveplan/network-discovery-peerjs/transport";
+
+const transport = new PeerJSTransport({
+    host: "signalling.example.com",
+    peerFactory: makePeerFactory(),
+});
+
+await transport.connect("remote-peer-id", "ignored");
+transport.onMessage((peerId, envelope) => {
+    console.log("from", peerId, envelope);
+});
+await transport.send("remote-peer-id", {
+    id: "m1",
+    type: "ping",
+    senderId: "self",
+    payload: { hello: "world" },
+    timestamp: Date.now(),
+    headers: {},
+    ttl: 64,
+    visitedNodes: [],
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { NetworkNode } from "@suaveplan/network";
+import { PeerJSPlugin } from "@suaveplan/network-discovery-peerjs/plugin";
+
+const node = new NetworkNode();
+const plugin = new PeerJSPlugin({
+    host: "signalling.example.com",
+    iceServers: [{ urls: "stun:stun.example.com:3478" }],
+    peerFactory: makePeerFactory(),
+});
+
+node.use(plugin);
+await node.start();
+
+const transport = plugin.transport;
+transport.onPeerEvent((peerId, event) => {
+    if (event === "connected") {
+        console.log("peer joined", peerId);
+    }
+});
+
+// Open a connection with a cancellable signal — useful for UI flows that
+// abort the dial when the user navigates away.
+const ac = new AbortController();
+setTimeout(() => ac.abort(), 5_000);
+await transport.connect("alice", "ignored", ac.signal);
+
+await node.stop();
+```
+
+## API Reference
+
+- `class PeerJSTransport implements Transport`
+  - `readonly id = "peerjs"`.
+  - `constructor(config: PeerJSTransportConfig)` — `host` is required; all
+    other fields default (`port=443`, `path="/"`, `secure=true`, `debug=0`).
+  - `connect(peerId: string, address: string, signal?: AbortSignal): Promise<void>` —
+    lazy-opens the broker handshake on first call, then opens a `DataConnection`
+    to `peerId`. `address` is accepted for `Transport` compatibility but
+    unused (PeerJS centralises signalling at `host`). Throws
+    `PEER_ALREADY_CONNECTED` / `TRANSPORT_CLOSED` / `ABORTED` /
+    `PEER_CONNECT_FAILED`.
+  - `disconnect(peerId: string): Promise<void>` — closes the per-peer
+    connection. Unknown peer is a no-op.
+  - `send(peerId: string, envelope: MessageEnvelope): Promise<void>` —
+    wraps `envelope` in the transport frame and sends. Throws
+    `PEER_UNKNOWN` / `TRANSPORT_CLOSED` / `SEND_FAILED`.
+  - `onMessage(handler)` / `onPeerEvent(handler)` — return unsubscribe.
+  - `getConnectedPeers(): readonly string[]`.
+  - `close(): Promise<void>` — idempotent; closes every connection,
+    destroys the `PeerLike`, drops handler sets.
+  - `getMyPeerId(): string | null` — broker-assigned local id, or `null`
+    before the first `connect()`.
+
+## Implementation Notes
+
+The transport reuses `initializePeer` + `connectToPeer` + `handleConnection`
+from `core/peerjs-connection/` so the integrated discovery + transport unit
+upstream sees as a single PeerJS package is preserved without splitting it.
+The discovery layer's Zod `PeerJSMessageSchema` deliberately does not list
+the transport `kind` discriminator, so when a discovery-only peer receives
+a transport frame the schema rejects it and the handler silently drops it —
+mixing both protocols on the same `PeerLike` is safe.
+
+Per-peer connection state is held in `#peers: Map<PeerId, PeerState>`. The
+fresh-`Map` invariant in `connect()` (each call hands `openConnection` a
+private map) guarantees the only path that returns `undefined` from
+`openConnection` is unreachable in production; an `/* istanbul ignore next */`
+guard documents the defensive branch.
+
+`#waitForOpen` resolves on the first `open` event from the new
+`DataConnectionLike`; if the channel emits `error` before `open` it
+rejects with `PEER_CONNECT_FAILED`. Pre-aborted and mid-handshake
+abort signals both reject with `ABORTED`.
+
+Frame validation uses a structural type-guard (`kind === "suaveplan.transport.v1"`
+
+- object `envelope`), which means malformed or non-transport traffic is
+dropped without touching the registered handlers, preventing a hostile
+peer from injecting through `onMessage`.
+
+The transport never emits `connected` for a peer twice — `#acceptIncoming`
+short-circuits when the registry already has the id, and `#handlePeerLost`
+gates the `disconnected` emission on registry presence, so consumers can
+treat the event stream as exactly-once per session.

packages/networking/network/network-discovery-peerjs/src/transport/transport.spec-conformance.test.ts

@@ -0,0 +1,912 @@
+import type { MessageEnvelope } from "@suaveplan/network";
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import fc from "fast-check";
+import {
+    FakeBroker,
+    type FakeDataConnection,
+    type FakePeer,
+    fakePeerFactory,
+    flushMicrotasks,
+} from "../../tests/setup/fake-peerjs.js";
+import {
+    NET_DISC_PEERJS_CODES,
+    type NetDiscPeerJSError,
+} from "../errors/errors.js";
+import { PeerJSTransport } from "./transport.js";
+
+function envelope(id: string, type = "test"): MessageEnvelope {
+    return {
+        id,
+        type,
+        senderId: "self",
+        payload: { hello: id },
+        timestamp: 1,
+        headers: {},
+        ttl: 64,
+        visitedNodes: [],
+    };
+}
+
+/** Register a fake remote peer with `peerId` so outbound connects succeed. */
+function registerRemote(broker: FakeBroker, peerId: string): FakePeer {
+    const factory = fakePeerFactory(broker);
+    const peer = factory(peerId, {
+        host: "h",
+        port: 1,
+        path: "/",
+        secure: true,
+        debug: 0,
+        config: {},
+    }) as FakePeer;
+    return peer;
+}
+
+/**
+ * Capture the next inbound `DataConnection` event on a fake remote peer so
+ * the test can drive its handlers directly. Listener MUST be attached before
+ * the local transport calls `peer.connect`, otherwise the FakeBroker's
+ * microtask delivery fires first and the listener never sees the event.
+ */
+function captureNextIncoming(remote: FakePeer): Promise<FakeDataConnection> {
+    return new Promise<FakeDataConnection>((resolve) => {
+        remote.on("connection", (c) => resolve(c as FakeDataConnection));
+    });
+}
+
+async function makeTransport(opts?: { peerId?: string }): Promise<{
+    transport: PeerJSTransport;
+    broker: FakeBroker;
+}> {
+    const broker = new FakeBroker();
+    const transport = new PeerJSTransport({
+        host: "h",
+        port: 1,
+        path: "/",
+        secure: true,
+        debug: 0,
+        peerFactory: fakePeerFactory(broker),
+        ...(opts?.peerId !== undefined ? { peerId: opts.peerId } : {}),
+    });
+    return { transport, broker };
+}
+
+describe("PeerJSTransport", () => {
+    it("has id 'peerjs'", { timeout: 5000 }, () => {
+        const t = new PeerJSTransport({
+            host: "h",
+            peerFactory: fakePeerFactory(new FakeBroker()),
+        });
+        expect(t.id).toBe("peerjs");
+    });
+
+    it("connects, tracks peers, and exposes my-peer-id", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        await transport.connect("remote-1", "ignored");
+        expect(transport.getConnectedPeers()).toContain("remote-1");
+        expect(transport.getMyPeerId()).not.toBeNull();
+        await transport.close();
+    });
+
+    it("emits connected then disconnected peer events", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const events: Array<{ peerId: string; event: string }> = [];
+        transport.onPeerEvent((peerId, event) => {
+            events.push({ peerId, event });
+        });
+        await transport.connect("remote-1", "ignored");
+        await transport.disconnect("remote-1");
+        expect(events).toContainEqual({
+            peerId: "remote-1",
+            event: "connected",
+        });
+        expect(events).toContainEqual({
+            peerId: "remote-1",
+            event: "disconnected",
+        });
+        await transport.close();
+    });
+
+    it("send round-trips an envelope to the remote handler", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const local = new PeerJSTransport({
+            host: "h",
+            peerFactory: fakePeerFactory(broker),
+        });
+        // Build a second transport on the same broker so we can observe the
+        // wire frame on the remote side.
+        const remote = new PeerJSTransport({
+            host: "h",
+            peerId: "remote-1",
+            peerFactory: fakePeerFactory(broker),
+        });
+        // Force the remote to register by triggering an init via a stub
+        // connect to a non-existent id (initializePeer resolves first).
+        registerRemote(broker, "warmup-peer");
+        await flushMicrotasks();
+        // Easier path: prime the remote's PeerLike by registering directly
+        // with a real FakePeer keyed at "remote-1".
+        const remoteFakePeer = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const inbound: Array<{ peerId: string; envelope: MessageEnvelope }> =
+            [];
+        // Drive `remote` to observe inbound by wiring an inbound connection
+        // handler through its own state. Skip running `remote.connect` —
+        // instead wire `remoteFakePeer`'s `on('connection')` directly to
+        // accept inbound from the local transport.
+        remoteFakePeer.on("connection", (conn) => {
+            // Mimic what PeerJSTransport.#acceptIncoming does on the remote.
+            conn.on("open", () => {
+                /* opened */
+            });
+            conn.on("data", (raw: unknown) => {
+                if (
+                    raw !== null &&
+                    typeof raw === "object" &&
+                    (raw as { kind?: unknown }).kind ===
+                        "suaveplan.transport.v1"
+                ) {
+                    const env = (raw as { envelope: MessageEnvelope }).envelope;
+                    inbound.push({ peerId: conn.peer, envelope: env });
+                }
+            });
+        });
+        await local.connect("remote-1", "ignored");
+        await local.send("remote-1", envelope("m1"));
+        await flushMicrotasks();
+        expect(inbound.length).toBeGreaterThanOrEqual(1);
+        expect(inbound[0]?.envelope.id).toBe("m1");
+        await local.close();
+        await remote.close();
+    });
+
+    it("inbound transport frame fans out to onMessage handlers", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        const remote = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const inbound: MessageEnvelope[] = [];
+        transport.onMessage((_pid, env) => inbound.push(env));
+        const remoteConnPromise = captureNextIncoming(remote);
+        await transport.connect("remote-1", "ignored");
+        const remoteConn = await remoteConnPromise;
+        // Already-open by the time send works.
+        (remoteConn.send as (m: unknown) => void)({
+            kind: "suaveplan.transport.v1",
+            envelope: envelope("inbound-1"),
+        });
+        await flushMicrotasks();
+        expect(inbound.find((e) => e.id === "inbound-1")).toBeDefined();
+        await transport.close();
+    });
+
+    it("silently drops non-transport inbound frames", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        const remote = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const inbound: MessageEnvelope[] = [];
+        transport.onMessage((_pid, env) => inbound.push(env));
+        const remoteConnPromise = captureNextIncoming(remote);
+        await transport.connect("remote-1", "ignored");
+        const remoteConn = await remoteConnPromise;
+        (remoteConn.send as (m: unknown) => void)({
+            type: "announce",
+            from: "remote-1",
+            payload: { id: "x", addresses: [], metadata: {}, lastSeen: 0 },
+            timestamp: 0,
+        });
+        (remoteConn.send as (m: unknown) => void)("not-an-object");
+        (remoteConn.send as (m: unknown) => void)({
+            kind: "wrong.kind",
+            envelope: {},
+        });
+        (remoteConn.send as (m: unknown) => void)({
+            kind: "suaveplan.transport.v1",
+            envelope: null,
+        });
+        (remoteConn.send as (m: unknown) => void)(null);
+        await flushMicrotasks();
+        expect(inbound.length).toBe(0);
+        await transport.close();
+    });
+
+    it("rejects send to unknown peer with PEER_UNKNOWN", {
+        timeout: 5000,
+    }, async () => {
+        const { transport } = await makeTransport();
+        try {
+            await transport.send("ghost", envelope("m1"));
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.PEER_UNKNOWN
+            );
+        }
+        await transport.close();
+    });
+
+    it("rejects duplicate connect with PEER_ALREADY_CONNECTED", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        await transport.connect("remote-1", "ignored");
+        try {
+            await transport.connect("remote-1", "ignored");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.PEER_ALREADY_CONNECTED
+            );
+        }
+        await transport.close();
+    });
+
+    it("rejects connect after close with TRANSPORT_CLOSED", {
+        timeout: 5000,
+    }, async () => {
+        const { transport } = await makeTransport();
+        await transport.close();
+        try {
+            await transport.connect("remote-1", "ignored");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.TRANSPORT_CLOSED
+            );
+        }
+        try {
+            await transport.send("remote-1", envelope("m1"));
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.TRANSPORT_CLOSED
+            );
+        }
+    });
+
+    it("rejects connect with pre-aborted signal", {
+        timeout: 5000,
+    }, async () => {
+        const { transport } = await makeTransport();
+        const ac = new AbortController();
+        ac.abort();
+        try {
+            await transport.connect("remote-1", "ignored", ac.signal);
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.ABORTED
+            );
+        }
+        await transport.close();
+    });
+
+    it("close is idempotent and disconnect of unknown peer is a no-op", {
+        timeout: 5000,
+    }, async () => {
+        const { transport } = await makeTransport();
+        await transport.disconnect("ghost");
+        await transport.close();
+        await transport.close();
+    });
+
+    it("returns unsubscribe handles from onMessage/onPeerEvent", {
+        timeout: 5000,
+    }, () => {
+        const t = new PeerJSTransport({
+            host: "h",
+            peerFactory: fakePeerFactory(new FakeBroker()),
+        });
+        const offMsg = t.onMessage(() => {});
+        const offEvt = t.onPeerEvent(() => {});
+        offMsg();
+        offEvt();
+    });
+
+    it("wraps a synchronous peer.connect failure as PEER_CONNECT_FAILED", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const factory = fakePeerFactory(broker);
+        // Override factory to install an outboundFailure on the FakePeer.
+        const transport = new PeerJSTransport({
+            host: "h",
+            peerFactory: (peerId, options) => {
+                const peer = factory(peerId, options) as FakePeer;
+                peer.outboundFailure = new Error("connect boom");
+                return peer;
+            },
+        });
+        try {
+            await transport.connect("remote-x", "ignored");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED
+            );
+        }
+        await transport.close();
+    });
+
+    it("wraps an inbound error during open as PEER_CONNECT_FAILED", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        // Do NOT register the remote — FakePeer fires an error on the
+        // local end when the target id is unknown.
+        await flushMicrotasks();
+        // We need the local PeerLike to be initialized first; do that by
+        // priming a successful connect against a registered remote, then
+        // attempt the failing one.
+        registerRemote(broker, "warm");
+        await flushMicrotasks();
+        await transport.connect("warm", "ignored");
+        try {
+            await transport.connect("nonexistent", "ignored");
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED
+            );
+        }
+        await transport.close();
+    });
+
+    it("auto-prunes the peer when the connection closes", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        const remote = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const events: string[] = [];
+        transport.onPeerEvent((_pid, ev) => events.push(ev));
+        const remoteConnPromise = captureNextIncoming(remote);
+        await transport.connect("remote-1", "ignored");
+        const remoteConn = await remoteConnPromise;
+        remoteConn.close();
+        await flushMicrotasks();
+        expect(transport.getConnectedPeers()).not.toContain("remote-1");
+        expect(events).toContain("disconnected");
+        await transport.close();
+    });
+
+    it("emits connected on inbound accepted connections", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const dialer = new PeerJSTransport({
+            host: "h",
+            peerFactory: fakePeerFactory(broker),
+        });
+        const listener = new PeerJSTransport({
+            host: "h",
+            peerId: "listener-1",
+            peerFactory: fakePeerFactory(broker),
+        });
+        // Both transports must initialize their PeerLike. The simplest path
+        // is to issue a connect that drives the broker to register both.
+        // First, prime listener's PeerLike by reaching into ensurePeer via
+        // a connect to a registered remote.
+        registerRemote(broker, "pad");
+        await flushMicrotasks();
+        await listener.connect("pad", "ignored");
+        const events: string[] = [];
+        listener.onPeerEvent((_pid, ev) => events.push(ev));
+        // Now dialer connects to listener; listener should accept inbound
+        // and emit connected.
+        await dialer.connect("listener-1", "ignored");
+        await flushMicrotasks();
+        expect(events).toContain("connected");
+        await dialer.close();
+        await listener.close();
+    });
+
+    it("ignores duplicate inbound connection after local outbound", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        await transport.connect("remote-1", "ignored");
+        // Synthesize an inbound connection that uses the same peer id.
+        // The FakePeer's `connect` already wired one — we just need to
+        // emit a second `connection` event on the local PeerLike with the
+        // same remote id. Reach in via the local FakePeer.
+        const local = [...broker.peers.values()].find(
+            (p) => p.id !== "remote-1"
+        );
+        if (!local) throw new Error("local peer not registered");
+        const dupConn = local.connect("remote-1");
+        await flushMicrotasks();
+        // dupConn opens asynchronously; the transport's accept-incoming
+        // handler should see the existing entry and short-circuit. The
+        // outcome: getConnectedPeers still has exactly one "remote-1".
+        expect(
+            transport.getConnectedPeers().filter((id) => id === "remote-1")
+                .length
+        ).toBe(1);
+        // Close the dup to be tidy.
+        try {
+            dupConn.close();
+        } catch {
+            /* best-effort */
+        }
+        await transport.close();
+    });
+
+    it("wraps a per-peer send failure as SEND_FAILED", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        const remote = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const remoteConnPromise = captureNextIncoming(remote);
+        await transport.connect("remote-1", "ignored");
+        const remoteConn = await remoteConnPromise;
+        // Close the remote partner so the local-side `send` throws.
+        // The local side's `open` flag flips because `close` fires on both.
+        // To trigger SEND_FAILED specifically, mark local-open true but
+        // make the underlying send throw: monkey-patch the local connection.
+        const localConn = remoteConn.partner;
+        if (!localConn) throw new Error("no local conn");
+        localConn.send = () => {
+            throw new Error("send boom");
+        };
+        try {
+            await transport.send("remote-1", envelope("m1"));
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.SEND_FAILED
+            );
+        }
+        await transport.close();
+    });
+
+    it("rejects send when the connection has been closed", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        const remote = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const remoteConnPromise = captureNextIncoming(remote);
+        await transport.connect("remote-1", "ignored");
+        const remoteConn = await remoteConnPromise;
+        const localConn = remoteConn.partner;
+        if (!localConn) throw new Error("no local conn");
+        // Flip the open flag without firing close (simulates a half-open
+        // channel where send must reject as PEER_UNKNOWN per impl).
+        Object.defineProperty(localConn, "open", {
+            value: false,
+            writable: true,
+        });
+        try {
+            await transport.send("remote-1", envelope("m1"));
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.PEER_UNKNOWN
+            );
+        }
+        await transport.close();
+    });
+
+    it("default factory throws INVALID_OPTIONS when no peerFactory is supplied", {
+        timeout: 5000,
+    }, async () => {
+        const transport = new PeerJSTransport({ host: "h" });
+        try {
+            await transport.connect("remote-1", "ignored");
+            expect.fail("expected throw");
+        } catch (err) {
+            // initializePeer wraps synchronous factory throws as SIGNALING_FAILED.
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.SIGNALING_FAILED
+            );
+        }
+        await transport.close();
+    });
+
+    it("rejects mid-handshake when the abort signal fires", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        // Prime the PeerLike with one successful connect.
+        await transport.connect("remote-1", "ignored");
+        await transport.disconnect("remote-1");
+        const ac = new AbortController();
+        // Schedule abort right after the open-listener is wired but before
+        // the FakePeer's queueMicrotask `fireOpen` runs.
+        queueMicrotask(() => ac.abort());
+        registerRemote(broker, "remote-2");
+        await flushMicrotasks();
+        try {
+            await transport.connect("remote-2", "ignored", ac.signal);
+            // It is also acceptable if the open beat the abort; in that
+            // case the connect resolves and we just close.
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.ABORTED
+            );
+        }
+        await transport.close();
+    });
+
+    it("getConnectedPeers excludes a registry entry whose channel closed", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        const remote = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const remoteConnPromise = captureNextIncoming(remote);
+        await transport.connect("remote-1", "ignored");
+        const remoteConn = await remoteConnPromise;
+        const localConn = remoteConn.partner;
+        if (!localConn) throw new Error("no local conn");
+        // Flip the open flag without firing the close event so the auto-prune
+        // path stays dormant; getConnectedPeers must still skip the peer.
+        Object.defineProperty(localConn, "open", {
+            value: false,
+            writable: true,
+        });
+        expect(transport.getConnectedPeers()).not.toContain("remote-1");
+        await transport.close();
+    });
+
+    it("shares one #initPromise across concurrent first-connects", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        registerRemote(broker, "remote-1");
+        registerRemote(broker, "remote-2");
+        await flushMicrotasks();
+        // Kick off two concurrent connects so the second one sees a
+        // non-null `#initPromise` and reuses it without spawning a second
+        // initializePeer call.
+        const [r1, r2] = await Promise.allSettled([
+            transport.connect("remote-1", "ignored"),
+            transport.connect("remote-2", "ignored"),
+        ]);
+        expect(r1.status).toBe("fulfilled");
+        expect(r2.status).toBe("fulfilled");
+        await transport.close();
+    });
+
+    it("reuses the cached PeerLike across connects", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        registerRemote(broker, "remote-1");
+        registerRemote(broker, "remote-2");
+        await flushMicrotasks();
+        await transport.connect("remote-1", "ignored");
+        const first = transport.getMyPeerId();
+        await transport.connect("remote-2", "ignored");
+        const second = transport.getMyPeerId();
+        expect(first).not.toBeNull();
+        expect(second).toBe(first);
+        await transport.close();
+    });
+
+    it("inbound-accept path routes data frames to onMessage", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const dialer = new PeerJSTransport({
+            host: "h",
+            peerFactory: fakePeerFactory(broker),
+        });
+        const listener = new PeerJSTransport({
+            host: "h",
+            peerId: "listener-1",
+            peerFactory: fakePeerFactory(broker),
+        });
+        // Prime listener's PeerLike so a remote can dial it.
+        registerRemote(broker, "pad");
+        await flushMicrotasks();
+        await listener.connect("pad", "ignored");
+        const inboundOnListener: MessageEnvelope[] = [];
+        listener.onMessage((_pid, env) => inboundOnListener.push(env));
+        // Dialer initialises lazily on its own `connect`; the dialer's local
+        // PeerLike is unknown to the broker until that happens.
+        await dialer.connect("listener-1", "ignored");
+        await flushMicrotasks();
+        // Now the dialer sends via its outbound channel — the listener's
+        // accept-incoming `handleConnection` should route the frame.
+        await dialer.send("listener-1", envelope("inbound-accept-1"));
+        await flushMicrotasks();
+        await flushMicrotasks();
+        expect(
+            inboundOnListener.find((e) => e.id === "inbound-accept-1")
+        ).toBeDefined();
+        await dialer.close();
+        await listener.close();
+    });
+
+    it("inbound accept ignores a duplicate connection for a known peer", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const dialer = new PeerJSTransport({
+            host: "h",
+            peerFactory: fakePeerFactory(broker),
+        });
+        const listener = new PeerJSTransport({
+            host: "h",
+            peerId: "listener-1",
+            peerFactory: fakePeerFactory(broker),
+        });
+        // Prime the listener's PeerLike via a successful outbound dial.
+        registerRemote(broker, "pad");
+        await flushMicrotasks();
+        await listener.connect("pad", "ignored");
+        const connectedEvents: string[] = [];
+        listener.onPeerEvent((pid, ev) => {
+            if (ev === "connected") connectedEvents.push(pid);
+        });
+        // First inbound dial registers the peer.
+        await dialer.connect("listener-1", "ignored");
+        await flushMicrotasks();
+        // Second dialer with the SAME id should be silently ignored by the
+        // listener's accept-incoming path (duplicate registry entry).
+        const dialer2 = new PeerJSTransport({
+            host: "h",
+            peerId: dialer.getMyPeerId() ?? "dup",
+            peerFactory: fakePeerFactory(broker),
+        });
+        try {
+            await dialer2.connect("listener-1", "ignored");
+        } catch {
+            /* dialer2 may legitimately fail because the broker already has
+             * the configured id; we only care about the listener's accept
+             * path behaviour. */
+        }
+        await flushMicrotasks();
+        // Only one connected event for the dialer id.
+        const fromDialer = connectedEvents.filter(
+            (id) => id === dialer.getMyPeerId()
+        );
+        expect(fromDialer.length).toBeLessThanOrEqual(1);
+        await dialer.close();
+        await dialer2.close();
+        await listener.close();
+    });
+
+    it("inbound handler-throw outcome records as inbound error", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        const remote = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        transport.onMessage(() => {
+            throw new Error("handler boom");
+        });
+        const remoteConnPromise = captureNextIncoming(remote);
+        await transport.connect("remote-1", "ignored");
+        const remoteConn = await remoteConnPromise;
+        (remoteConn.send as (m: unknown) => void)({
+            kind: "suaveplan.transport.v1",
+            envelope: envelope("boom-1"),
+        });
+        await flushMicrotasks();
+        await transport.close();
+    });
+
+    it("aborts mid-handshake via #waitForOpen onAbort listener", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const factory = fakePeerFactory(broker);
+        // Wrap the factory so `peer.connect` returns a connection that
+        // never fires `open` — leaving `#waitForOpen` parked on the
+        // promise so we can deterministically drive the abort path.
+        const transport = new PeerJSTransport({
+            host: "h",
+            peerFactory: (peerId, options) => {
+                const peer = factory(peerId, options) as FakePeer;
+                peer.connect = ((): FakeDataConnection => {
+                    const local: FakeDataConnection = {
+                        peer: "remote-stuck",
+                        open: false,
+                        send() {},
+                        close() {},
+                        emit() {},
+                        on(_event: string, _handler: () => void) {},
+                        fireOpen() {},
+                        fireError() {},
+                    } as unknown as FakeDataConnection;
+                    return local;
+                }) as unknown as FakePeer["connect"];
+                return peer;
+            },
+        });
+        // Prime by calling connect first against the bare factory; this
+        // initialises the PeerLike before we patch out `connect`. Actually
+        // the above factory always patches, so the first connect will
+        // already be stuck — we have to abort it.
+        const ac = new AbortController();
+        const pending = transport.connect("remote-stuck", "ignored", ac.signal);
+        // Wait one macrotask to let initializePeer resolve, openConnection
+        // run, and #waitForOpen wire its listeners.
+        await flushMicrotasks();
+        await flushMicrotasks();
+        ac.abort();
+        try {
+            await pending;
+            expect.fail("expected throw");
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.ABORTED
+            );
+        }
+        await transport.close();
+    });
+
+    it("rejects connect when abort fires after #waitForOpen wires its listener", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        // Prime the PeerLike.
+        registerRemote(broker, "warm");
+        await flushMicrotasks();
+        await transport.connect("warm", "ignored");
+        // Register the second remote AFTER the PeerLike is initialized so
+        // the second connect's `openConnection` succeeds and we hit the
+        // `#waitForOpen` promise body, where the AbortSignal listener
+        // sits ready to fire.
+        registerRemote(broker, "remote-2");
+        await flushMicrotasks();
+        const ac = new AbortController();
+        const pending = transport.connect("remote-2", "ignored", ac.signal);
+        ac.abort();
+        try {
+            await pending;
+            // If the open event won the race, that's also fine — the
+            // assertion below is only checked on the throw branch.
+        } catch (err) {
+            expect((err as NetDiscPeerJSError).code).toBe(
+                NET_DISC_PEERJS_CODES.ABORTED
+            );
+        }
+        await transport.close();
+    });
+
+    it("synthesized: registrationBlocked guard fires when #closed is true mid-handshake", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const transport = new PeerJSTransport({
+            host: "h",
+            peerFactory: fakePeerFactory(broker),
+        });
+        // Initialise the local PeerLike via a quick warm-up dial.
+        registerRemote(broker, "warm");
+        await flushMicrotasks();
+        await transport.connect("warm", "ignored");
+        // Find the local peer in the broker — it's the one whose id is NOT
+        // the warmup target.
+        const localPeer = [...broker.peers.values()].find(
+            (p) => p.id !== "warm"
+        ) as FakePeer;
+        // Build a synthetic inbound connection.
+        const synth = new (
+            await import("../../tests/setup/fake-peerjs.js")
+        ).FakeDataConnection("synth-1");
+        // Emit `connection` on the local peer so the transport wires its
+        // `on("open")` handler against `synth`.
+        localPeer.emit("connection", synth);
+        // Now close the transport BEFORE firing `open` on the synthetic
+        // connection — when `open` fires the registration guard short-
+        // circuits the registration path.
+        await transport.close();
+        synth.fireOpen();
+        await flushMicrotasks();
+    });
+
+    it("synthesized: #waitForOpen early-returns when connection is already open", {
+        timeout: 5000,
+    }, async () => {
+        const broker = new FakeBroker();
+        const factory = fakePeerFactory(broker);
+        const transport = new PeerJSTransport({
+            host: "h",
+            peerFactory: (peerId, options) => {
+                const peer = factory(peerId, options) as FakePeer;
+                // Patch `peer.connect` so the returned channel is already
+                // marked open before #waitForOpen inspects it.
+                const realConnect = peer.connect.bind(peer);
+                peer.connect = ((id: string) => {
+                    const c = realConnect(id);
+                    (c as { open: boolean }).open = true;
+                    return c;
+                }) as FakePeer["connect"];
+                return peer;
+            },
+        });
+        registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        await transport.connect("remote-1", "ignored");
+        await transport.close();
+    });
+
+    it("close after a registered-but-closed peer still emits disconnected", {
+        timeout: 5000,
+    }, async () => {
+        const { transport, broker } = await makeTransport();
+        const remote = registerRemote(broker, "remote-1");
+        await flushMicrotasks();
+        const remoteConnPromise = captureNextIncoming(remote);
+        await transport.connect("remote-1", "ignored");
+        const remoteConn = await remoteConnPromise;
+        const localConn = remoteConn.partner;
+        if (!localConn) throw new Error("no local conn");
+        // Force local close to throw inside `close()`'s best-effort guard.
+        localConn.close = () => {
+            throw new Error("close boom");
+        };
+        await transport.close();
+    });
+
+    it("fast-check: per-peer registry rejects duplicate ids", {
+        timeout: 10000,
+    }, async () => {
+        await fc.assert(
+            fc.asyncProperty(
+                fc.array(
+                    fc
+                        .string({ minLength: 1, maxLength: 6 })
+                        .filter((s) => /^[a-z0-9-]+$/.test(s)),
+                    { minLength: 1, maxLength: 5 }
+                ),
+                async (ids) => {
+                    const { transport, broker } = await makeTransport();
+                    const seen = new Set<string>();
+                    for (const id of ids) {
+                        if (!seen.has(id)) {
+                            registerRemote(broker, id);
+                        }
+                    }
+                    await flushMicrotasks();
+                    for (const id of ids) {
+                        if (seen.has(id)) {
+                            let threw = false;
+                            try {
+                                await transport.connect(id, "ignored");
+                            } catch (err) {
+                                threw = true;
+                                expect((err as NetDiscPeerJSError).code).toBe(
+                                    NET_DISC_PEERJS_CODES.PEER_ALREADY_CONNECTED
+                                );
+                            }
+                            expect(threw).toBe(true);
+                        } else {
+                            await transport.connect(id, "ignored");
+                            seen.add(id);
+                        }
+                    }
+                    expect(new Set(transport.getConnectedPeers()).size).toBe(
+                        seen.size
+                    );
+                    await transport.close();
+                }
+            ),
+            { numRuns: 3 }
+        );
+    });
+});

packages/networking/network/network-discovery-peerjs/src/transport/transport.ts

@@ -0,0 +1,426 @@
+import type { MessageEnvelope, PeerId, Transport } from "@suaveplan/network";
+import {
+    handleConnection,
+    initializePeer,
+    connectToPeer as openConnection,
+} from "../core/peerjs-connection/peerjs-connection.js";
+import { NET_DISC_PEERJS_CODES, NetDiscPeerJSError } from "../errors/errors.js";
+import {
+    adjustTransportActivePeers,
+    recordTransportMessage,
+    withTransportSpan,
+} from "../otel/otel.js";
+import type {
+    DataConnectionLike,
+    PeerFactory,
+    PeerJSPeerOptions,
+    PeerJSTransportConfig,
+    PeerJSTransportFrame,
+    PeerLike,
+} from "../types/types.js";
+
+type TransportMessageHandler = (
+    peerId: PeerId,
+    envelope: MessageEnvelope
+) => void;
+
+type TransportPeerEventHandler = (
+    peerId: PeerId,
+    event: "connected" | "disconnected"
+) => void;
+
+interface PeerState {
+    readonly peerId: PeerId;
+    readonly connection: DataConnectionLike;
+}
+
+/**
+ * Default `PeerFactory` that errors at use-time. Production builds inject a
+ * real factory bound to `peerjs`; tests inject `fakePeerFactory(broker)`.
+ */
+function defaultFactory(): PeerLike {
+    throw new NetDiscPeerJSError(
+        NET_DISC_PEERJS_CODES.INVALID_OPTIONS,
+        "errors.peerjs.no_factory"
+    );
+}
+
+/**
+ * Frame-discriminator used to mark transport-tier traffic so a discovery
+ * handler on the receiver silently drops it when no transport is installed.
+ */
+const FRAME_KIND = "suaveplan.transport.v1" as const;
+
+/**
+ * Browser-tier `Transport` for the `@suaveplan/network` mesh backed by the
+ * PeerJS WebRTC stack. Composes one `PeerLike` (lazy-initialized against the
+ * configured signalling server on first `connect`) and a per-peer
+ * `DataConnectionLike` registry.
+ *
+ * The transport reuses the existing primitives in this package
+ * (`initializePeer`, `connectToPeer`, `handleConnection`) so the integrated
+ * discovery + transport behaviour upstream sees as a single PeerJS unit is
+ * preserved without forking a separate package.
+ */
+export class PeerJSTransport implements Transport {
+    public readonly id = "peerjs";
+
+    readonly #peers = new Map<PeerId, PeerState>();
+    readonly #messageHandlers = new Set<TransportMessageHandler>();
+    readonly #peerEventHandlers = new Set<TransportPeerEventHandler>();
+    readonly #factory: PeerFactory;
+    readonly #peerOptions: PeerJSPeerOptions;
+    readonly #configuredPeerId: string | undefined;
+    #peer: PeerLike | null = null;
+    #myPeerId: string | null = null;
+    #initPromise: Promise<string> | null = null;
+    #closed = false;
+
+    public constructor(config: PeerJSTransportConfig) {
+        this.#factory = config.peerFactory ?? defaultFactory;
+        this.#configuredPeerId = config.peerId;
+        this.#peerOptions = {
+            host: config.host,
+            port: config.port ?? 443,
+            path: config.path ?? "/",
+            secure: config.secure ?? true,
+            debug: config.debug ?? 0,
+            config: {
+                ...(config.iceServers !== undefined
+                    ? { iceServers: config.iceServers }
+                    : {}),
+            },
+            ...(config.key !== undefined ? { key: config.key } : {}),
+        };
+    }
+
+    /** Local peer id assigned by the signalling broker, or `null` before any
+     * `connect()` resolves. Useful for debugging + integration tests. */
+    public getMyPeerId(): string | null {
+        return this.#myPeerId;
+    }
+
+    public async connect(
+        peerId: PeerId,
+        _address: string,
+        signal?: AbortSignal
+    ): Promise<void> {
+        return withTransportSpan("peerjs_transport.connect", async (span) => {
+            span.setAttribute("peer.id", peerId);
+            this.#assertOpen();
+            if (signal?.aborted) {
+                throw new NetDiscPeerJSError(
+                    NET_DISC_PEERJS_CODES.ABORTED,
+                    "errors.peerjs.aborted"
+                );
+            }
+            if (this.#peers.has(peerId)) {
+                throw new NetDiscPeerJSError(
+                    NET_DISC_PEERJS_CODES.PEER_ALREADY_CONNECTED,
+                    "errors.peerjs.peer_already_connected",
+                    { context: { peerId } }
+                );
+            }
+            const peer = await this.#ensurePeer(signal);
+            // Fresh per-call map so `openConnection` always returns the new
+            // `DataConnectionLike` (its only undefined path is when the map
+            // already has `peerId`, which is impossible here).
+            const connections = new Map<string, DataConnectionLike>();
+            let connection: DataConnectionLike;
+            try {
+                connection = openConnection(
+                    peer,
+                    peerId,
+                    connections,
+                    (raw, conn) => this.#handleInbound(conn.peer, raw),
+                    (lostId) => this.#handlePeerLost(lostId)
+                ) as DataConnectionLike;
+            } catch (cause) {
+                throw new NetDiscPeerJSError(
+                    NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED,
+                    "errors.peerjs.peer_connect_failed",
+                    { context: { peerId }, cause: cause as Error }
+                );
+            }
+            await this.#waitForOpen(connection, signal);
+            this.#peers.set(peerId, { peerId, connection });
+            adjustTransportActivePeers(+1);
+            this.#emitPeerEvent(peerId, "connected");
+        });
+    }
+
+    public async disconnect(peerId: PeerId): Promise<void> {
+        return withTransportSpan(
+            "peerjs_transport.disconnect",
+            async (span) => {
+                span.setAttribute("peer.id", peerId);
+                const state = this.#peers.get(peerId);
+                if (state === undefined) {
+                    return;
+                }
+                this.#peers.delete(peerId);
+                adjustTransportActivePeers(-1);
+                try {
+                    state.connection.close();
+                } catch {
+                    /* best-effort close */
+                }
+                this.#emitPeerEvent(peerId, "disconnected");
+            }
+        );
+    }
+
+    public async send(
+        peerId: PeerId,
+        envelope: MessageEnvelope
+    ): Promise<void> {
+        return withTransportSpan("peerjs_transport.send", async (span) => {
+            span.setAttribute("peer.id", peerId);
+            if (this.#closed) {
+                recordTransportMessage("outbound", "error");
+                throw new NetDiscPeerJSError(
+                    NET_DISC_PEERJS_CODES.TRANSPORT_CLOSED,
+                    "errors.peerjs.transport_closed"
+                );
+            }
+            const state = this.#peers.get(peerId);
+            if (state === undefined) {
+                recordTransportMessage("outbound", "error");
+                throw new NetDiscPeerJSError(
+                    NET_DISC_PEERJS_CODES.PEER_UNKNOWN,
+                    "errors.peerjs.peer_unknown",
+                    { context: { peerId } }
+                );
+            }
+            if (!state.connection.open) {
+                recordTransportMessage("outbound", "error");
+                throw new NetDiscPeerJSError(
+                    NET_DISC_PEERJS_CODES.PEER_UNKNOWN,
+                    "errors.peerjs.peer_unknown",
+                    { context: { peerId } }
+                );
+            }
+            const frame: PeerJSTransportFrame = {
+                kind: FRAME_KIND,
+                envelope: envelope as unknown as Readonly<
+                    Record<string, unknown>
+                >,
+            };
+            try {
+                // PeerJS `DataConnection.send` accepts `any` upstream; the
+                // local `DataConnectionLike.send` signature is narrowed for
+                // discovery use. Cast through `unknown` so the transport can
+                // ship its own frame without leaking into the discovery
+                // message union.
+                (state.connection.send as (m: unknown) => void)(frame);
+                recordTransportMessage("outbound", "ok");
+            } catch (cause) {
+                recordTransportMessage("outbound", "error");
+                throw new NetDiscPeerJSError(
+                    NET_DISC_PEERJS_CODES.SEND_FAILED,
+                    "errors.peerjs.send_failed",
+                    { context: { peerId }, cause: cause as Error }
+                );
+            }
+        });
+    }
+
+    public onMessage(handler: TransportMessageHandler): () => void {
+        this.#messageHandlers.add(handler);
+        return () => {
+            this.#messageHandlers.delete(handler);
+        };
+    }
+
+    public onPeerEvent(handler: TransportPeerEventHandler): () => void {
+        this.#peerEventHandlers.add(handler);
+        return () => {
+            this.#peerEventHandlers.delete(handler);
+        };
+    }
+
+    public getConnectedPeers(): readonly PeerId[] {
+        const connected: PeerId[] = [];
+        for (const [peerId, state] of this.#peers) {
+            if (state.connection.open) {
+                connected.push(peerId);
+            }
+        }
+        return connected;
+    }
+
+    public async close(): Promise<void> {
+        if (this.#closed) {
+            return;
+        }
+        this.#closed = true;
+        const snapshot = [...this.#peers.values()];
+        this.#peers.clear();
+        for (const state of snapshot) {
+            adjustTransportActivePeers(-1);
+            try {
+                state.connection.close();
+            } catch {
+                /* best-effort */
+            }
+            this.#emitPeerEvent(state.peerId, "disconnected");
+        }
+        if (this.#peer !== null) {
+            try {
+                this.#peer.destroy();
+            } catch {
+                /* best-effort */
+            }
+            this.#peer = null;
+        }
+        this.#myPeerId = null;
+        this.#messageHandlers.clear();
+        this.#peerEventHandlers.clear();
+    }
+
+    #assertOpen(): void {
+        if (this.#closed) {
+            throw new NetDiscPeerJSError(
+                NET_DISC_PEERJS_CODES.TRANSPORT_CLOSED,
+                "errors.peerjs.transport_closed"
+            );
+        }
+    }
+
+    async #ensurePeer(signal?: AbortSignal): Promise<PeerLike> {
+        if (this.#peer !== null) {
+            return this.#peer;
+        }
+        if (this.#initPromise === null) {
+            this.#initPromise = initializePeer(
+                this.#factory,
+                this.#configuredPeerId ?? "",
+                this.#peerOptions,
+                signal
+            ).then(({ peer, myPeerId }) => {
+                this.#peer = peer;
+                this.#myPeerId = myPeerId;
+                // Accept inbound connections from remote peers so a
+                // remote `connect` is observable on this side too.
+                peer.on("connection", (incoming) => {
+                    this.#acceptIncoming(incoming);
+                });
+                return myPeerId;
+            });
+        }
+        await this.#initPromise;
+        // `initPromise` always resolves with a non-null `#peer` (set inside
+        // its `.then`). If `initializePeer` throws, we propagate above.
+        return this.#peer as unknown as PeerLike;
+    }
+
+    #acceptIncoming(connection: DataConnectionLike): void {
+        const peerId = connection.peer;
+        if (this.#peers.has(peerId)) {
+            // Local side already wired a connection for this peer; ignore
+            // the incoming duplicate so the registry stays single-entry.
+            return;
+        }
+        handleConnection(
+            connection,
+            new Map<string, DataConnectionLike>(),
+            (raw, conn) => this.#handleInbound(conn.peer, raw),
+            (lostId) => this.#handlePeerLost(lostId)
+        );
+        // Use a one-shot `open` listener to register once the channel is up.
+        connection.on("open", () => {
+            this.#registerAccepted(peerId, connection);
+        });
+    }
+
+    #registerAccepted(peerId: PeerId, connection: DataConnectionLike): void {
+        if (this.#registrationBlocked(peerId)) return;
+        this.#peers.set(peerId, { peerId, connection });
+        adjustTransportActivePeers(+1);
+        this.#emitPeerEvent(peerId, "connected");
+    }
+
+    /* istanbul ignore next -- race guards for transport-closed and dup-peer
+       windows that are unreachable under deterministic test brokers */
+    #registrationBlocked(peerId: PeerId): boolean {
+        return this.#closed || this.#peers.has(peerId);
+    }
+
+    async #waitForOpen(
+        connection: DataConnectionLike,
+        signal?: AbortSignal
+    ): Promise<void> {
+        /* istanbul ignore if -- channel already open before we awaited it */
+        if (connection.open) return;
+        await new Promise<void>((resolve, reject) => {
+            const onAbort = (): void => {
+                cleanup();
+                reject(
+                    new NetDiscPeerJSError(
+                        NET_DISC_PEERJS_CODES.ABORTED,
+                        "errors.peerjs.aborted"
+                    )
+                );
+            };
+            const onError = (err: Error): void => {
+                cleanup();
+                reject(
+                    new NetDiscPeerJSError(
+                        NET_DISC_PEERJS_CODES.PEER_CONNECT_FAILED,
+                        "errors.peerjs.peer_connect_failed",
+                        { cause: err }
+                    )
+                );
+            };
+            const onOpen = (): void => {
+                cleanup();
+                resolve();
+            };
+            const cleanup = (): void => {
+                signal?.removeEventListener("abort", onAbort);
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            connection.on("open", onOpen);
+            connection.on("error", onError);
+        });
+    }
+
+    #handleInbound(peerId: PeerId, raw: unknown): void {
+        if (!isTransportFrame(raw)) {
+            // Discovery traffic or unknown payload — silently ignore.
+            return;
+        }
+        try {
+            const envelope = raw.envelope as unknown as MessageEnvelope;
+            for (const handler of this.#messageHandlers) {
+                handler(peerId, envelope);
+            }
+            recordTransportMessage("inbound", "ok");
+        } catch {
+            recordTransportMessage("inbound", "error");
+        }
+    }
+
+    #handlePeerLost(peerId: PeerId): void {
+        if (!this.#peers.has(peerId)) return;
+        this.#peers.delete(peerId);
+        adjustTransportActivePeers(-1);
+        this.#emitPeerEvent(peerId, "disconnected");
+    }
+
+    #emitPeerEvent(peerId: PeerId, event: "connected" | "disconnected"): void {
+        for (const handler of this.#peerEventHandlers) {
+            handler(peerId, event);
+        }
+    }
+}
+
+function isTransportFrame(raw: unknown): raw is PeerJSTransportFrame {
+    if (raw === null || typeof raw !== "object") return false;
+    const candidate = raw as { kind?: unknown; envelope?: unknown };
+    if (candidate.kind !== FRAME_KIND) return false;
+    if (candidate.envelope === null || typeof candidate.envelope !== "object") {
+        return false;
+    }
+    return true;
+}

packages/networking/network/network-discovery-peerjs/src/types/types.md

@@ -0,0 +1,87 @@
+# types
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Type-only foundation for `@suaveplan/network-discovery-peerjs`. Declares the
+wire-format `PeerJSMessage` envelope, the structural `PeerLike` and
+`DataConnectionLike` surfaces used to inject real or stub PeerJS implementations,
+the strict `PeerJSDiscoveryConfig` (which deliberately makes `host` mandatory —
+there is no public-server fallback), the resolved-config shape produced by Zod
+defaulting, and the typed event map fanned out on the optional bus.
+
+## Features
+
+- Frozen `PeerJSMessageType` literal-record covering every wire-format verb.
+- `PeerJSPeerMetadata` + `PeerJSPeerRecord` separation: wire payload vs.
+  in-memory room state.
+- `DataConnectionLike` / `PeerLike` structural surfaces — production binds to
+  real `peerjs` instances, tests bind to a deterministic stub with no mocks.
+- `PeerFactory` contract for injecting the constructor.
+- `PeerJSDiscoveryConfig` with required `host` and Zod-defaulted optional
+  fields; `ResolvedPeerJSDiscoveryConfig` for the post-parse internal shape.
+- `PeerJSEventMap` typed bus emissions: `peerjs:started`,
+  `peerjs:peer-discovered`, `peerjs:peer-lost`, `peerjs:signaling-failed`.
+
+## Usage: Basic Example
+
+```ts
+import type {
+    PeerJSDiscoveryConfig,
+    PeerJSEventMap,
+} from "@suaveplan/network-discovery-peerjs/types";
+
+const config: PeerJSDiscoveryConfig = {
+    host: "signaling.example.com",
+    room: "demo",
+};
+```
+
+## Usage: Advanced Example
+
+```ts
+import type {
+    PeerJSDiscoveryConfig,
+    PeerFactory,
+    PeerLike,
+} from "@suaveplan/network-discovery-peerjs/types";
+import { EventBus } from "@suaveplan/events";
+
+const bus = new EventBus<import("@suaveplan/network-discovery-peerjs/types").PeerJSEventMap>();
+const factory: PeerFactory = (id, opts): PeerLike => fakePeer(id, opts);
+
+const config: PeerJSDiscoveryConfig = {
+    host: "signaling.example.com",
+    port: 8443,
+    secure: true,
+    room: "alpha",
+    iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
+    bus,
+    peerFactory: factory,
+};
+```
+
+## API Reference
+
+- `PeerJSMessageType` — frozen `{ANNOUNCE,DISCOVER,PEER_LIST,LEAVE,HEARTBEAT}`.
+- `PeerJSPeerMetadata` — announce payload shape.
+- `PeerJSMessage` — full envelope `{type, from, payload, timestamp}`.
+- `PeerJSPeerRecord` — internal room-manager record (mutable `lastSeen`).
+- `DataConnectionLike` — `{peer, open, send, on(event,...), close}`.
+- `PeerLike` — `{connect, on(event,...), destroy}`.
+- `PeerFactory` — `(peerId, opts) => PeerLike`.
+- `PeerJSPeerOptions` — host/port/path/secure/key/debug/config bundle.
+- `PeerJSDiscoveryConfig` — caller-facing options, `host`+`room` required.
+- `ResolvedPeerJSDiscoveryConfig` — internal post-default shape.
+- `PeerJSEventMap` — typed bus event keys + payloads.
+
+## Implementation Notes
+
+`host` has no default. Constructing without one throws `INVALID_OPTIONS` at
+the Zod boundary inside `PeerJSDiscovery` — this is the explicit decision the
+parity checklist records as an enterprise uplift over the upstream package,
+which silently fell back to the public `peerjs.com` cloud. Wire-format types
+keep `readonly` modifiers so downstream code cannot mutate buffers shared
+across the message-handler dispatch table.

packages/networking/network/network-discovery-peerjs/src/types/types.schemas.ts

@@ -0,0 +1,62 @@
+import z from "zod";
+
+/**
+ * Zod boundary schemas for every public option struct and wire message in
+ * `@suaveplan/network-discovery-peerjs`. Callable contracts (`PeerFactory`,
+ * `EventBusLike`, `ServiceRegistry`) are type-only and tolerated as
+ * `z.unknown()` — runtime checks live in the constructors that consume them.
+ */
+
+export const PeerJSPeerMetadataSchema = z
+    .object({
+        id: z.string().min(1),
+        addresses: z.array(z.string()).readonly(),
+        metadata: z.record(z.string(), z.unknown()),
+        capabilities: z.array(z.string()).optional(),
+        lastSeen: z.number().int().nonnegative(),
+    })
+    .strict();
+
+export const PeerJSMessageSchema = z
+    .object({
+        type: z.enum([
+            "announce",
+            "discover",
+            "peer_list",
+            "leave",
+            "heartbeat",
+        ]),
+        from: z.string().min(1),
+        payload: z.union([
+            PeerJSPeerMetadataSchema,
+            z.array(z.string()),
+            z.record(z.string(), z.unknown()),
+        ]),
+        timestamp: z.number().int().nonnegative(),
+    })
+    .strict();
+
+export const PeerJSDiscoveryConfigSchema = z
+    .object({
+        strategy: z.literal("peerjs").optional(),
+        host: z.string().min(1),
+        port: z.number().int().positive().default(443),
+        path: z.string().min(1).default("/"),
+        secure: z.boolean().default(true),
+        key: z.string().min(1).optional(),
+        peerId: z.string().min(1).optional(),
+        debug: z
+            .union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)])
+            .default(0),
+        room: z.string().min(1),
+        interval: z.number().int().positive().default(30_000),
+        timeout: z.number().int().positive().default(60_000),
+        heartbeatInterval: z.number().int().positive().default(15_000),
+        cleanupInterval: z.number().int().positive().default(30_000),
+        maxPeers: z.number().int().positive().default(100),
+        iceServers: z.array(z.unknown()).optional(),
+        peerFactory: z.unknown().optional(),
+        bus: z.unknown().optional(),
+        registry: z.unknown().optional(),
+    })
+    .strict();

packages/networking/network/network-discovery-peerjs/src/types/types.ts

@@ -0,0 +1,266 @@
+import type { ServiceRegistry } from "@suaveplan/service-discovery";
+import type { EventBusLike } from "@suaveplan/types";
+
+/**
+ * Discovery-message types exchanged between PeerJS peers in a room.
+ *
+ * Frozen string-literal union (kept as a const enum-style record so the
+ * wire-format values stay stable across the family of `network-discovery-*`
+ * packages).
+ */
+export const PeerJSMessageType = Object.freeze({
+    /** Announce presence + metadata to every connected peer in the room. */
+    ANNOUNCE: "announce",
+    /** Request the full known peer-list from the recipient. */
+    DISCOVER: "discover",
+    /** Reply to a `DISCOVER` with an array of known peer ids. */
+    PEER_LIST: "peer_list",
+    /** Voluntary leave notification — recipients drop the sender. */
+    LEAVE: "leave",
+    /** Liveness ping — updates `lastSeen` on the recipient. */
+    HEARTBEAT: "heartbeat",
+} as const);
+
+export type PeerJSMessageTypeValue =
+    (typeof PeerJSMessageType)[keyof typeof PeerJSMessageType];
+
+/**
+ * Peer metadata broadcast inside an `ANNOUNCE` payload.
+ */
+export interface PeerJSPeerMetadata {
+    /** Unique peer id assigned by the PeerJS signalling server. */
+    readonly id: string;
+    /** Reachable addresses (libp2p-style multiaddrs are accepted; opaque to us). */
+    readonly addresses: readonly string[];
+    /** Free-form caller-supplied metadata. */
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** Optional capability strings the peer advertises. */
+    readonly capabilities?: readonly string[];
+    /** Unix-ms timestamp the announce was generated. */
+    readonly lastSeen: number;
+}
+
+/**
+ * Wire-format envelope for every discovery message.
+ */
+export interface PeerJSMessage {
+    readonly type: PeerJSMessageTypeValue;
+    readonly from: string;
+    readonly payload:
+        | PeerJSPeerMetadata
+        | readonly string[]
+        | Readonly<Record<string, unknown>>;
+    readonly timestamp: number;
+}
+
+/**
+ * Internal `PeerInfo` shape — local to this package because upstream's
+ * `@suaveplan/network` `PeerInfo` differs from the canonical
+ * `@suaveplan/network-bootstrap` `PeerInfo`. Discovery emits the
+ * bootstrap-compatible shape; the room manager keeps richer metadata.
+ */
+export interface PeerJSPeerRecord {
+    readonly id: string;
+    readonly addresses: readonly string[];
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly capabilities?: readonly string[];
+    /** Mutable in-place because `lastSeen` updates on every heartbeat. */
+    lastSeen: number;
+}
+
+/**
+ * Structural surface of a PeerJS `DataConnection` used by this package.
+ * Real production code receives an actual `peerjs` `DataConnection`; tests
+ * implement this contract directly to avoid mocks.
+ */
+export interface DataConnectionLike {
+    /** Remote peer id this connection is opened to. */
+    readonly peer: string;
+    /** Whether the connection is currently open. */
+    readonly open: boolean;
+    /** Send a discovery message. PeerJS serialises to JSON internally. */
+    send(message: PeerJSMessage): void;
+    /** Subscribe to a typed connection event. */
+    on(event: "open", handler: () => void): void;
+    on(event: "data", handler: (data: unknown) => void): void;
+    on(event: "error", handler: (error: Error) => void): void;
+    on(event: "close", handler: () => void): void;
+    /** Close the data channel. */
+    close(): void;
+}
+
+/**
+ * Structural surface of a PeerJS `Peer` used by this package.
+ */
+export interface PeerLike {
+    /** Open an outbound `DataConnection` to `peerId`. */
+    connect(peerId: string, opts?: { reliable?: boolean }): DataConnectionLike;
+    /** Subscribe to peer lifecycle events. */
+    on(event: "open", handler: (id: string) => void): void;
+    on(
+        event: "connection",
+        handler: (connection: DataConnectionLike) => void
+    ): void;
+    on(event: "error", handler: (error: Error) => void): void;
+    on(event: "disconnected", handler: () => void): void;
+    on(event: "close", handler: () => void): void;
+    /** Destroy the peer, closing every connection. */
+    destroy(): void;
+}
+
+/**
+ * Factory contract used by `PeerJSDiscovery` to construct a `PeerLike`. The
+ * production wiring binds this to `new (await import("peerjs")).default(...)`
+ * via {@link defaultPeerFactory}. Tests pass a deterministic stub.
+ */
+export type PeerFactory = (
+    peerId: string,
+    config: PeerJSPeerOptions
+) => PeerLike;
+
+/**
+ * Subset of PeerJS constructor options the discovery surface forwards.
+ */
+export interface PeerJSPeerOptions {
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+    readonly secure: boolean;
+    readonly key?: string;
+    readonly debug: 0 | 1 | 2 | 3;
+    readonly config: { iceServers?: readonly RTCIceServer[] };
+}
+
+/**
+ * Strict configuration for `PeerJSDiscovery`. `host` is REQUIRED — there is
+ * deliberately no fallback to the public `peerjs.com` cloud.
+ */
+export interface PeerJSDiscoveryConfig {
+    /** Strategy discriminator. Always `"peerjs"`. */
+    readonly strategy?: "peerjs";
+    /** Required signalling-server host. */
+    readonly host: string;
+    /** Signalling-server port. Default `443`. */
+    readonly port?: number;
+    /** Signalling-server URL path. Default `"/"`. */
+    readonly path?: string;
+    /** TLS toggle. Default `true`. */
+    readonly secure?: boolean;
+    /** Optional API key for managed PeerJS deployments. */
+    readonly key?: string;
+    /** Caller-supplied peer id. Server assigns one if omitted. */
+    readonly peerId?: string;
+    /** PeerJS debug level. Default `0`. */
+    readonly debug?: 0 | 1 | 2 | 3;
+    /** Logical room — only same-room peers discover each other. */
+    readonly room: string;
+    /** Announce interval (ms). Default `30_000`. */
+    readonly interval?: number;
+    /** Peer staleness timeout (ms). Default `60_000`. */
+    readonly timeout?: number;
+    /** Heartbeat interval (ms). Default `15_000`. */
+    readonly heartbeatInterval?: number;
+    /** Cleanup-loop interval (ms). Default `30_000`. */
+    readonly cleanupInterval?: number;
+    /** Hard cap on tracked peers. Default `100`. */
+    readonly maxPeers?: number;
+    /** WebRTC ICE servers forwarded to PeerJS. */
+    readonly iceServers?: readonly RTCIceServer[];
+    /** Injectable peer factory — tests pass a stub. */
+    readonly peerFactory?: PeerFactory;
+    /** Optional event bus for typed emissions. */
+    readonly bus?: EventBusLike<PeerJSEventMap>;
+    /** Optional service registry to mirror discovered peers into. */
+    readonly registry?: ServiceRegistry;
+}
+
+/**
+ * Fully resolved config — every optional field defaulted.
+ */
+export interface ResolvedPeerJSDiscoveryConfig
+    extends Required<
+        Omit<
+            PeerJSDiscoveryConfig,
+            "key" | "peerId" | "iceServers" | "peerFactory" | "bus" | "registry"
+        >
+    > {
+    readonly key: string | undefined;
+    readonly peerId: string | undefined;
+    readonly iceServers: readonly RTCIceServer[] | undefined;
+    readonly peerFactory: PeerFactory | undefined;
+    readonly bus: EventBusLike<PeerJSEventMap> | undefined;
+    readonly registry: ServiceRegistry | undefined;
+}
+
+/**
+ * Typed event map emitted on the optional `EventBusLike`.
+ */
+export interface PeerJSDiscoveredEvent {
+    readonly peer: PeerJSPeerRecord;
+    readonly at: number;
+}
+
+export interface PeerJSLostEvent {
+    readonly peerId: string;
+    readonly at: number;
+}
+
+export interface PeerJSSignalingFailedEvent {
+    readonly reason: string;
+    readonly at: number;
+}
+
+export interface PeerJSStartedEvent {
+    readonly peerId: string;
+    readonly room: string;
+    readonly at: number;
+}
+
+export type PeerJSEventMap = {
+    "peerjs:started": PeerJSStartedEvent;
+    "peerjs:peer-discovered": PeerJSDiscoveredEvent;
+    "peerjs:peer-lost": PeerJSLostEvent;
+    "peerjs:signaling-failed": PeerJSSignalingFailedEvent;
+};
+
+/**
+ * Configuration for `PeerJSTransport`. The transport is a thin adapter over
+ * `PeerConnectionManager`, so most config mirrors the signalling-server bits
+ * of `PeerJSDiscoveryConfig`. Discovery-only fields (room, intervals, max
+ * peers, event bus, service registry) are deliberately omitted — the
+ * transport carries arbitrary `MessageEnvelope`s and does not run an
+ * announce / heartbeat loop.
+ */
+export interface PeerJSTransportConfig {
+    /** Required signalling-server host. */
+    readonly host: string;
+    /** Signalling-server port. Default `443`. */
+    readonly port?: number;
+    /** Signalling-server URL path. Default `"/"`. */
+    readonly path?: string;
+    /** TLS toggle. Default `true`. */
+    readonly secure?: boolean;
+    /** Optional API key for managed PeerJS deployments. */
+    readonly key?: string;
+    /** Caller-supplied peer id. Server assigns one if omitted. */
+    readonly peerId?: string;
+    /** PeerJS debug level. Default `0`. */
+    readonly debug?: 0 | 1 | 2 | 3;
+    /** WebRTC ICE servers forwarded to PeerJS. */
+    readonly iceServers?: readonly RTCIceServer[];
+    /** Injectable peer factory — tests pass a stub. */
+    readonly peerFactory?: PeerFactory;
+}
+
+/**
+ * Wire format the `PeerJSTransport` uses to send `MessageEnvelope` payloads
+ * over a `DataConnectionLike`. Receivers running only the discovery handler
+ * silently drop these frames (they do not match `PeerJSMessageSchema`), so
+ * mixing transport + discovery traffic on the same `PeerLike` is safe.
+ */
+export interface PeerJSTransportFrame {
+    /** Stable kind discriminator; the receiver gates inbound traffic on this. */
+    readonly kind: "suaveplan.transport.v1";
+    /** The opaque message envelope being forwarded. */
+    readonly envelope: Readonly<Record<string, unknown>>;
+}

packages/networking/network/network-discovery-peerjs/tests/dep-graph.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+
+describe("network-discovery-peerjs dep-graph", () => {
+    it("must not have circular dependencies", async () => {
+        const mod = await import("../src/index.js");
+        expect(mod).toBeDefined();
+        expect(mod.PeerJSDiscovery).toBeDefined();
+        expect(mod.PeerConnectionManager).toBeDefined();
+        expect(mod.RoomManager).toBeDefined();
+        expect(mod.PeerJSIntervals).toBeDefined();
+        expect(mod.handleMessage).toBeDefined();
+        expect(mod.initializePeer).toBeDefined();
+        expect(mod.broadcastMessage).toBeDefined();
+        expect(mod.NET_DISC_PEERJS_CODES).toBeDefined();
+        expect(mod.NetDiscPeerJSError).toBeDefined();
+        expect(mod.PeerJSDiscoveryConfigSchema).toBeDefined();
+        expect(mod.PeerJSMessageType).toBeDefined();
+    });
+});

packages/networking/network/network-discovery-peerjs/tests/setup/fake-peerjs.ts

@@ -0,0 +1,187 @@
+/**
+ * Deterministic in-memory PeerJS substitute used by the test suites. Models a
+ * single shared broker — every `FakePeer` constructed against the same
+ * `FakeBroker` can `connect` to every other peer. No mocks: this is a real
+ * implementation of the structural contract.
+ */
+import type {
+    DataConnectionLike,
+    PeerFactory,
+    PeerJSMessage,
+    PeerJSPeerOptions,
+    PeerLike,
+} from "../../src/types/types.js";
+
+type Handler = (arg?: unknown) => void;
+
+/** Shared broker state — wires `FakePeer`s together by id. */
+export class FakeBroker {
+    public readonly peers = new Map<string, FakePeer>();
+    public nextId = 0;
+    /** When `true`, peer-open is rejected with `Error('broker down')`. */
+    public broken = false;
+
+    public register(peer: FakePeer): string {
+        this.nextId += 1;
+        const id = peer.configuredPeerId || `fake-peer-${this.nextId}`;
+        this.peers.set(id, peer);
+        return id;
+    }
+
+    public unregister(id: string): void {
+        this.peers.delete(id);
+    }
+
+    public find(id: string): FakePeer | undefined {
+        return this.peers.get(id);
+    }
+}
+
+/** Implementation of `DataConnectionLike` shared by both ends of a channel. */
+export class FakeDataConnection implements DataConnectionLike {
+    public open = false;
+    private readonly handlers = new Map<string, Set<Handler>>();
+    public partner: FakeDataConnection | undefined;
+
+    public constructor(public readonly peer: string) {}
+
+    public send(message: PeerJSMessage): void {
+        if (!this.open) throw new Error("connection closed");
+        const partner = this.partner;
+        if (partner === undefined) return;
+        queueMicrotask(() => {
+            partner.emit("data", message);
+        });
+    }
+
+    public on(event: "open", h: () => void): void;
+    public on(event: "data", h: (data: unknown) => void): void;
+    public on(event: "error", h: (error: Error) => void): void;
+    public on(event: "close", h: () => void): void;
+    public on(event: string, h: Handler): void {
+        let set = this.handlers.get(event);
+        if (set === undefined) {
+            set = new Set();
+            this.handlers.set(event, set);
+        }
+        set.add(h);
+    }
+
+    public close(): void {
+        if (!this.open && this.handlers.size === 0) return;
+        this.open = false;
+        this.emit("close");
+        this.partner?.fireClose();
+    }
+
+    public fireOpen(): void {
+        this.open = true;
+        this.emit("open");
+    }
+
+    public fireError(error: Error): void {
+        this.emit("error", error);
+    }
+
+    private fireClose(): void {
+        if (!this.open) return;
+        this.open = false;
+        this.emit("close");
+    }
+
+    public emit(event: string, arg?: unknown): void {
+        const set = this.handlers.get(event);
+        if (set === undefined) return;
+        for (const handler of set) {
+            handler(arg);
+        }
+    }
+}
+
+/** Implementation of `PeerLike`. */
+export class FakePeer implements PeerLike {
+    public readonly handlers = new Map<string, Set<Handler>>();
+    public id: string | undefined;
+    public destroyed = false;
+    public outboundFailure: Error | undefined;
+
+    public constructor(
+        public readonly broker: FakeBroker,
+        public readonly configuredPeerId: string,
+        public readonly options: PeerJSPeerOptions
+    ) {
+        queueMicrotask(() => {
+            if (this.destroyed) return;
+            if (broker.broken) {
+                this.emit("error", new Error("broker down"));
+                return;
+            }
+            this.id = broker.register(this);
+            this.emit("open", this.id);
+        });
+    }
+
+    public connect(peerId: string): DataConnectionLike {
+        if (this.outboundFailure !== undefined) {
+            throw this.outboundFailure;
+        }
+        const remote = this.broker.find(peerId);
+        const local = new FakeDataConnection(peerId);
+        const partner = new FakeDataConnection(this.id ?? "");
+        local.partner = partner;
+        partner.partner = local;
+        if (remote !== undefined) {
+            queueMicrotask(() => {
+                remote.emit("connection", partner);
+                partner.fireOpen();
+                local.fireOpen();
+            });
+        } else {
+            queueMicrotask(() => {
+                local.fireError(new Error(`peer ${peerId} not found`));
+            });
+        }
+        return local;
+    }
+
+    public on(event: "open", h: (id: string) => void): void;
+    public on(event: "connection", h: (c: DataConnectionLike) => void): void;
+    public on(event: "error", h: (e: Error) => void): void;
+    public on(event: "disconnected", h: () => void): void;
+    public on(event: "close", h: () => void): void;
+    public on(event: string, h: Handler): void {
+        let set = this.handlers.get(event);
+        if (set === undefined) {
+            set = new Set();
+            this.handlers.set(event, set);
+        }
+        set.add(h);
+    }
+
+    public destroy(): void {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        if (this.id !== undefined) this.broker.unregister(this.id);
+        this.emit("close");
+    }
+
+    public emit(event: string, arg?: unknown): void {
+        const set = this.handlers.get(event);
+        if (set === undefined) return;
+        for (const handler of set) {
+            handler(arg);
+        }
+    }
+}
+
+/** Build a `PeerFactory` bound to a shared broker. */
+export function fakePeerFactory(broker: FakeBroker): PeerFactory {
+    return (peerId, options) => new FakePeer(broker, peerId, options);
+}
+
+/** Yield control until pending microtasks have drained. */
+export async function flushMicrotasks(): Promise<void> {
+    for (let i = 0; i < 4; i += 1) {
+        await Promise.resolve();
+    }
+}

packages/networking/network/network-discovery-peerjs/tests/setup/polyfills.ts

@@ -0,0 +1,8 @@
+// Ensure `globalThis.crypto` is available in bare-Node vitest runs.
+import { webcrypto } from "node:crypto";
+
+type WritableGlobal = { crypto?: Crypto };
+const g = globalThis as WritableGlobal;
+if (g.crypto === undefined) {
+    g.crypto = webcrypto as unknown as Crypto;
+}

packages/networking/network/network-discovery-peerjs/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../../../tsconfig.base.json",
+  "references": [{ "path": "./tsconfig.lib.json" }]
+}

packages/networking/network/network-discovery-peerjs/tsconfig.lib.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "lib": ["ES2022", "DOM"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.bench.ts", "dist", "node_modules"]
+}

packages/networking/network/network-discovery-peerjs/vite.config.ts

@@ -0,0 +1,43 @@
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+  root: __dirname,
+  cacheDir: "../../../node_modules/.vite/packages/network-discovery-peerjs",
+  plugins: [
+    dts({
+      entryRoot: "src",
+      tsconfigPath: "./tsconfig.lib.json",
+      insertTypesEntry: true,
+    }),
+  ],
+  build: {
+    outDir: "./dist",
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    sourcemap: true,
+    lib: { entry: "src/index.ts", formats: ["es"] },
+    rollupOptions: {
+      treeshake: true,
+      output: {
+        preserveModules: true,
+        preserveModulesRoot: "src",
+        entryFileNames: "[name].js",
+      },
+      external: [
+        "@suaveplan/error",
+        "@suaveplan/events",
+        "@suaveplan/network",
+        "@suaveplan/network-bootstrap",
+        "@suaveplan/service-discovery",
+        "@suaveplan/timing",
+        "@suaveplan/types",
+        "peerjs",
+        "tslib",
+        "zod",
+        "@opentelemetry/api",
+        /^node:/,
+      ],
+    },
+  },
+});

packages/networking/network/network-discovery-peerjs/vitest.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: "node",
+    pool: "forks",
+    setupFiles: ["./tests/setup/polyfills.ts"],
+    include: ["src/**/*.test.ts", "tests/**/*.test.ts"],
+    exclude: [
+      "src/__benchmarks__/**",
+      "benchmarks/**",
+      "e2e/**",
+      "dist/**",
+      "node_modules/**",
+    ],
+    coverage: {
+      provider: "istanbul",
+      reporter: ["text", "html", "lcov"],
+      include: ["src/**/*.ts"],
+      exclude: [
+        "src/**/*.test.ts",
+        "src/**/*.bench.ts",
+        "src/**/*.schemas.ts",
+        "src/**/*.types.ts",
+        "src/**/index.ts",
+        "src/__benchmarks__/**",
+        "tests/**",
+      ],
+      thresholds: {
+        statements: 100,
+        branches: 100,
+        functions: 100,
+        lines: 100,
+      },
+    },
+    testTimeout: 5000,
+  },
+});