Developer-tools plugin for the Suaveplan mesh. Bundles four subsystems behind a single NetworkPlugin lifecycle so engineers can inspect, visualise, and profile the live network from the same node they run their tests against. The plugin is dev-only by contract: a tierGate callback decides activation at install time, and requireActive() raises PLUGIN_DEV_DISABLED so production call sites cannot silently exercise devtools work paths.

DevToolsPlugin ties the four subsystems together:

NetworkVisualizer — renders the mesh as a VisualizerScene IR (hierarchy / flow / heat-map modes), supports filtering by tier / latency-group / session / transport, and exports to SVG (bundled SvgRenderer) or PNG / canvas / WebGL via injected Renderer.
StateInspector — per-path state browser with bounded ring-buffer history, RFC-6902-style diff via @suaveplan/diff, timeline scrubber (scrub), and composable search over pathContains / peerId / sessionId / version range.
SimulationConfigTool — programmatic scenario builder (peers, links, conditions, timeline events) with deterministic recording, playback grouping by atMs, and Zod-validated JSON export / import for sharing scenarios across teams.
PerformanceProfiler — latency p50 / p95 / p99 distribution, throughput per path, plugin overhead, memory tracking, two-window EMA + Z-score regression detection against named baselines, and category-tagged optimisation suggestions.

Documentation tree

inspector — (no submodules)
- state-inspector — (no submodules)
plugin — (no submodules)
- devtools-plugin — (no submodules)
performance-profiler — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
performance-profiler.suggestions — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
simulator — (no submodules)
- simulation-config-tool — (no submodules)
network-visualizer — Renders the live mesh as a VisualizerScene intermediate representation (IR) and delegates byte production to an injec…
svg-renderer — Pure-string SVG renderer that consumes a VisualizerScene and produces deterministic UTF-8 SVG bytes without touching…
error-codes — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…

- [state-inspector](./src/inspector/state-inspector.md) — _(no submodules)_- [plugin](./src/plugin/devtools-plugin.md) — _(no submodules)_- [devtools-plugin](./src/plugin/devtools-plugin.md) — _(no submodules)_- [performance-profiler](./src/profiler/performance-profiler.md) — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…

performance-profiler.suggestions — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
simulator — (no submodules)- simulation-config-tool — (no submodules)- network-visualizer — Renders the live mesh as a VisualizerScene intermediate representation (IR) and delegates byte production to an injec…
svg-renderer — Pure-string SVG renderer that consumes a VisualizerScene and produces deterministic UTF-8 SVG bytes without touching…
error-codes — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…
state-inspector — (no submodules)- plugin — (no submodules)- devtools-plugin — (no submodules)- performance-profiler — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
performance-profiler.suggestions — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
simulator — (no submodules)- simulation-config-tool — (no submodules)- network-visualizer — Renders the live mesh as a VisualizerScene intermediate representation (IR) and delegates byte production to an injec…
svg-renderer — Pure-string SVG renderer that consumes a VisualizerScene and produces deterministic UTF-8 SVG bytes without touching…
error-codes — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…
state-inspector — (no submodules)- plugin — (no submodules)- devtools-plugin — (no submodules)- performance-profiler — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
performance-profiler.suggestions — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
simulator — (no submodules)- simulation-config-tool — (no submodules)- network-visualizer — Renders the live mesh as a VisualizerScene intermediate representation (IR) and delegates byte production to an injec…
svg-renderer — Pure-string SVG renderer that consumes a VisualizerScene and produces deterministic UTF-8 SVG bytes without touching…
error-codes — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…
state-inspector — (no submodules)- plugin — (no submodules) - devtools-plugin — (no submodules)- performance-profiler — Captures runtime performance evidence (latency per path, throughput per path, plugin overhead, memory) into bounded rin…
performance-profiler.suggestions — Pure-function suggestion engine that consumes profiler ring buffers (latency / overhead / throughput / memory) and emit…
simulator — (no submodules) - simulation-config-tool — (no submodules)- network-visualizer — Renders the live mesh as a VisualizerScene intermediate representation (IR) and delegates byte production to an injec…
svg-renderer — Pure-string SVG renderer that consumes a VisualizerScene and produces deterministic UTF-8 SVG bytes without touching…
error-codes — Defines the frozen registry of every failure mode the four devtools subsystems can surface. Centralising the codes here…

Install

bun add @suaveplan/network-plugin-devtools

Quick start

import { NetworkBus, NetworkNode } from "@suaveplan/network";
import { DevToolsPlugin } from "@suaveplan/network-plugin-devtools";

const node = new NetworkNode({ id: "host-1", networkBus: new NetworkBus() });
const devtools = new DevToolsPlugin({
    tierGate: () => process.env.NODE_ENV !== "production",
    topology: myTopologyAdapter,
    stream: myStreamAdapter,
    inspector: { historyLimit: 1024 },
    profiler: { regressionZScore: 2.5 },
});

node.use(devtools);
await node.start();

devtools.visualizer.start({ mode: "hierarchy", refreshRate: 30 });
const svg = devtools.visualizer.export("svg");

devtools.inspector.record({
    path: "session/lobby",
    value: { players: 3 },
    version: 1,
    timestamp: Date.now(),
    peerId: "host-1",
});

devtools.profiler.recordLatency("host-1->leaf-1", 42);
const baseline = devtools.profiler.captureBaseline("v1.0.0");

devtools.simulator.addPeer({ id: "leaf-2", tier: "tier-2", capacity: 10 });
const scenarioJson = devtools.simulator.exportJson();

Modules

error-codes — NETWORK_DEV_CODES registry + NetworkDevError.
visualizer/network-visualizer — IR-producing visualisation engine with three modes and pluggable renderer.
visualizer/svg-renderer — bundled dep-free SVG renderer.
inspector/state-inspector — per-path state browser, history, diff, search, scrubber.
simulator/simulation-config-tool — programmatic scenario builder with JSON round-trip.
profiler/performance-profiler — latency / throughput / overhead / memory tracking with regression detection.
profiler/performance-profiler.suggestions — heuristic suggestion engine.
plugin/devtools-plugin — facade satisfying NetworkPlugin with tier gate and production guard.