skills/docs/networking/network/network-plugin-devtools

@suaveplan/network-plugin-devtools - Developer-tools plugin for the Suaveplan mesh: NetworkVisualizer (hierarchy/flow/heat-map IR + injectable Renderer + bundled SVG renderer), StateInspector (tree view, ring-buffer history, RFC-6902-style diff via @suaveplan/diff, search/filter), SimulationConfigTool (programmatic topology + condition + event-timeline editor with JSON scenario export/import), PerformanceProfiler (latency p50/p95/p99 distribution, throughput, plugin overhead, memory tracking, two-window EMA regression detection, optimization suggestions), and DevToolsPlugin facade with tier gate and no-op-in-production guard.

Summary

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.