@forinda/kickjs-devtools 3.2.0 → 4.0.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-devtools v3.2.0
+ * @forinda/kickjs-devtools v4.0.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -11,10 +11,238 @@
 import "reflect-metadata";
 import { Router, static as static$1 } from "express";
 import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { existsSync, readFileSync } from "node:fs";
+import { createReadStream, existsSync, readFileSync, statSync, unlink } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { METADATA, computed, createLogger, getClassMeta, getMethodMeta, reactive, ref, watch } from "@forinda/kickjs";
+import { writeHeapSnapshot } from "node:v8";
+import { METADATA, computed, createLogger, defineAdapter, getClassMeta, getMethodMeta, reactive, ref, watch } from "@forinda/kickjs";
+import { MemoryAnalyzer, PROTOCOL_VERSION, RuntimeSampler } from "@forinda/kickjs-devtools-kit";
+//#region src/topology.ts
+const DEFAULT_INTROSPECT_TIMEOUT_MS = 100;
+/**
+* Collect a {@link TopologySnapshot} for the given application.
+*
+* Async because plugin/adapter `introspect()` may be async; the work
+* is parallelised across all primitives so wall-clock time scales
+* with the slowest introspector, not their sum.
+*/
+async function collectTopologySnapshot(opts) {
+	const { app, container, introspectTimeoutMs = DEFAULT_INTROSPECT_TIMEOUT_MS } = opts;
+	const errors = [];
+	const plugins = await Promise.all(app.getPlugins().map((p) => snapshotFor(p, "plugin", introspectTimeoutMs, errors)));
+	const adapters = await Promise.all(app.getAdapters().map((a) => snapshotFor(a, "adapter", introspectTimeoutMs, errors)));
+	return {
+		protocolVersion: PROTOCOL_VERSION,
+		timestamp: Date.now(),
+		plugins,
+		adapters,
+		contributors: collectContributors(app),
+		diTokens: collectTokens(container),
+		errors
+	};
+}
+/**
+* Coerce one primitive into an {@link IntrospectionSnapshot}. Tries
+* the primitive's own `introspect()` first; falls back to a stub on
+* any of: missing implementation, throw, timeout, or non-object return.
+*/
+async function snapshotFor(primitive, kind, timeoutMs, errors) {
+	const name = primitive.name ?? "(unnamed)";
+	const stub = {
+		protocolVersion: PROTOCOL_VERSION,
+		name,
+		kind
+	};
+	if (typeof primitive.introspect !== "function") return stub;
+	try {
+		const result = await Promise.race([Promise.resolve(primitive.introspect()), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`introspect() timed out after ${timeoutMs}ms`)), timeoutMs))]);
+		if (result && typeof result === "object") {
+			const snap = result;
+			return {
+				protocolVersion: PROTOCOL_VERSION,
+				name: snap.name ?? name,
+				kind: snap.kind ?? kind,
+				version: snap.version,
+				state: snap.state,
+				tokens: snap.tokens,
+				metrics: snap.metrics,
+				memoryBytes: snap.memoryBytes
+			};
+		}
+		return stub;
+	} catch (err) {
+		errors.push({
+			name,
+			kind,
+			message: err instanceof Error ? err.message : String(err)
+		});
+		return stub;
+	}
+}
+/** Read DI registrations into the topology shape — drops noisy HMR tokens. */
+function collectTokens(container) {
+	return container.getRegistrations().filter((r) => !r.token.startsWith("__hmr__")).map((r) => ({
+		token: r.token,
+		scope: r.scope,
+		kind: r.kind,
+		instantiated: r.instantiated
+	}));
+}
+/**
+* Best-effort contributor enumeration. Plugins + adapters can both
+* return contributor registrations via `contributors()` — we walk both
+* lists, normalise the entries, and dedupe by `key`. Module-level
+* contributors (the most common case) are not enumerable from this
+* surface; the panel will surface them per-route in a later iteration.
+*/
+function collectContributors(app) {
+	const seen = /* @__PURE__ */ new Map();
+	const ingest = (list, source) => {
+		if (!list) return;
+		for (const reg of list) {
+			const r = reg;
+			const key = typeof r.key === "string" ? r.key : null;
+			if (!key || seen.has(key)) continue;
+			seen.set(key, {
+				key,
+				source,
+				dependsOn: Array.isArray(r.dependsOn) ? r.dependsOn : []
+			});
+		}
+	};
+	for (const plugin of app.getPlugins()) ingest(plugin.contributors?.(), "adapter");
+	for (const adapter of app.getAdapters()) ingest(adapter.contributors?.(), "adapter");
+	return [...seen.values()];
+}
+//#endregion
+//#region src/devtools-tabs.ts
+const VALID_VIEW_TYPES = new Set([
+	"iframe",
+	"launch",
+	"html"
+]);
+/**
+* Walk every plugin + adapter, call `devtoolsTabs?()`, validate each
+* entry, and dedupe by `id`. Last-source-wins on collision is too
+* surprising — first-source-wins + a warning entry instead.
+*/
+function collectDevtoolsTabs(app) {
+	const tabs = [];
+	const seen = /* @__PURE__ */ new Map();
+	const errors = [];
+	const ingest = (sourceName, raw) => {
+		if (!Array.isArray(raw)) {
+			errors.push({
+				source: sourceName,
+				reason: "devtoolsTabs() did not return an array"
+			});
+			return;
+		}
+		for (const entry of raw) {
+			const validation = validateTab(entry);
+			if (!validation.ok) {
+				errors.push({
+					source: sourceName,
+					reason: validation.reason
+				});
+				continue;
+			}
+			const tab = validation.tab;
+			const owner = seen.get(tab.id);
+			if (owner) {
+				errors.push({
+					source: sourceName,
+					reason: `tab id '${tab.id}' already registered by ${owner} — first-source wins`
+				});
+				continue;
+			}
+			seen.set(tab.id, sourceName);
+			tabs.push(tab);
+		}
+	};
+	for (const plugin of app.getPlugins()) {
+		if (typeof plugin.devtoolsTabs !== "function") continue;
+		try {
+			ingest(plugin.name ?? "(unnamed plugin)", plugin.devtoolsTabs());
+		} catch (err) {
+			errors.push({
+				source: plugin.name ?? "(unnamed plugin)",
+				reason: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	for (const adapter of app.getAdapters()) {
+		if (typeof adapter.devtoolsTabs !== "function") continue;
+		try {
+			ingest(adapter.name ?? "(unnamed adapter)", adapter.devtoolsTabs());
+		} catch (err) {
+			errors.push({
+				source: adapter.name ?? "(unnamed adapter)",
+				reason: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	return {
+		tabs,
+		errors
+	};
+}
+/**
+* Coerce + validate a tab descriptor. Returns the typed object on
+* success; a structured reason on failure. Uses a permissive checker
+* so a partially-correct entry from a third-party adapter doesn't
+* break the whole panel.
+*/
+function validateTab(raw) {
+	if (!raw || typeof raw !== "object") return {
+		ok: false,
+		reason: "tab entry is not an object"
+	};
+	const obj = raw;
+	if (typeof obj.id !== "string" || obj.id.length === 0) return {
+		ok: false,
+		reason: "tab.id must be a non-empty string"
+	};
+	if (typeof obj.title !== "string" || obj.title.length === 0) return {
+		ok: false,
+		reason: `tab '${obj.id}': title must be a non-empty string`
+	};
+	const view = obj.view;
+	if (!view || typeof view !== "object") return {
+		ok: false,
+		reason: `tab '${obj.id}': view object is required`
+	};
+	if (typeof view.type !== "string" || !VALID_VIEW_TYPES.has(view.type)) return {
+		ok: false,
+		reason: `tab '${obj.id}': view.type must be one of iframe / launch / html`
+	};
+	switch (view.type) {
+		case "iframe":
+			if (typeof view.src !== "string" || view.src.length === 0) return {
+				ok: false,
+				reason: `tab '${obj.id}': iframe view requires a non-empty src`
+			};
+			break;
+		case "html":
+			if (typeof view.html !== "string") return {
+				ok: false,
+				reason: `tab '${obj.id}': html view requires html string`
+			};
+			break;
+		case "launch":
+			if (!Array.isArray(view.actions)) return {
+				ok: false,
+				reason: `tab '${obj.id}': launch view requires actions array`
+			};
+			break;
+	}
+	return {
+		ok: true,
+		tab: obj
+	};
+}
+//#endregion
 //#region src/adapter.ts
 const log = createLogger("DevTools");
 const MAX_SAMPLES = 1e3;
@@ -34,6 +262,37 @@ function computePercentiles(stats) {
 	};
 }
 /**
+* Open an SSE response — sets the headers, flushes them, and disables
+* any compression middleware that may have been registered upstream
+* (compression buffers SSE chunks indefinitely; we need flush-on-write).
+*/
+function openSseStream(req, res) {
+	res.writeHead(200, {
+		"Content-Type": "text/event-stream",
+		"Cache-Control": "no-cache, no-transform",
+		Connection: "keep-alive",
+		"X-Accel-Buffering": "no"
+	});
+	res.flushHeaders?.();
+}
+/** Write a single SSE `data:` event with a JSON payload + double newline. */
+function writeSseEvent(res, payload) {
+	res.write(`data: ${JSON.stringify(payload)}\n\n`);
+}
+/**
+* Module-scoped guard for `POST /_debug/memory/snapshot`. `writeHeapSnapshot()`
+* blocks the event loop for the duration of the capture (multi-second
+* for large heaps); two concurrent captures would compound the pause.
+* The endpoint returns 503 + a hint message when this flag is set so
+* the SPA can surface a "snapshot already running" warning rather than
+* silently queueing.
+*
+* Module-scoped (not per-adapter-instance) because writeHeapSnapshot
+* acts on the V8 process — multiple DevToolsAdapter instances would
+* still race at the v8 layer.
+*/
+let snapshotInProgress = false;
+/**
 * DevToolsAdapter — Vue-style reactive introspection for KickJS applications.
 *
 * Exposes debug endpoints powered by reactive state (ref, computed, watch):
@@ -51,7 +310,7 @@ function computePercentiles(stats) {
 * bootstrap({
 *   modules: [UserModule],
 *   adapters: [
-*     new DevToolsAdapter({
+*     DevToolsAdapter({
 *       enabled: process.env.NODE_ENV !== 'production',
 *       exposeConfig: true,
 *       configPrefixes: ['APP_', 'DATABASE_'],
@@ -60,336 +319,538 @@ function computePercentiles(stats) {
 * })
 * ```
 */
-var DevToolsAdapter = class {
-	name = "DevToolsAdapter";
-	basePath;
-	enabled;
-	exposeConfig;
-	configPrefixes;
-	errorRateThreshold;
-	secret;
-	/** Total requests received */
-	requestCount;
-	/** Total responses with status >= 500 */
-	errorCount;
-	/** Total responses with status >= 400 and < 500 */
-	clientErrorCount;
-	/** Server start time */
-	startedAt;
-	/** Computed error rate (server errors / total requests) */
-	errorRate;
-	/** Computed uptime in seconds */
-	uptimeSeconds;
-	/** Per-route latency tracking */
-	routeLatency;
-	routes = [];
-	container = null;
-	appRef = null;
-	adapterStatuses = {};
-	stopErrorWatch = null;
-	peerAdapters = [];
-	constructor(options = {}) {
-		this.basePath = options.basePath ?? "/_debug";
-		this.enabled = options.enabled ?? process.env.NODE_ENV !== "production";
-		this.exposeConfig = options.exposeConfig ?? false;
-		this.configPrefixes = options.configPrefixes ?? ["APP_", "NODE_ENV"];
-		this.errorRateThreshold = options.errorRateThreshold ?? .5;
-		this.peerAdapters = options.adapters ?? [];
-		if (options.secret === false) this.secret = false;
-		else if (options.secret) this.secret = options.secret;
-		else this.secret = randomBytes(16).toString("hex");
-		this.requestCount = ref(0);
-		this.errorCount = ref(0);
-		this.clientErrorCount = ref(0);
-		this.startedAt = ref(Date.now());
-		this.routeLatency = reactive({});
-		this.errorRate = computed(() => this.requestCount.value > 0 ? this.errorCount.value / this.requestCount.value : 0);
-		this.uptimeSeconds = computed(() => Math.floor((Date.now() - this.startedAt.value) / 1e3));
+const DevToolsAdapter = defineAdapter({
+	name: "DevToolsAdapter",
+	defaults: {
+		basePath: "/_debug",
+		errorRateThreshold: .5,
+		exposeConfig: false,
+		configPrefixes: ["APP_", "NODE_ENV"]
+	},
+	build: (options) => {
+		const basePath = options.basePath;
+		const enabled = options.enabled ?? process.env.NODE_ENV !== "production";
+		const exposeConfig = options.exposeConfig;
+		const configPrefixes = options.configPrefixes;
+		const errorRateThreshold = options.errorRateThreshold;
+		const peerAdapters = options.adapters ?? [];
+		let secret;
+		if (options.secret === false) secret = false;
+		else if (options.secret) secret = options.secret;
+		else secret = randomBytes(16).toString("hex");
+		const runtimeEnabled = options.runtime?.enabled ?? true;
+		const runtimeSampler = runtimeEnabled ? new RuntimeSampler({
+			intervalMs: options.runtime?.intervalMs ?? 1e3,
+			bufferSize: options.runtime?.bufferSize ?? 60
+		}) : null;
+		const memoryAnalyzer = runtimeEnabled ? new MemoryAnalyzer() : null;
+		const requestCount = ref(0);
+		const errorCount = ref(0);
+		const clientErrorCount = ref(0);
+		const startedAt = ref(Date.now());
+		const routeLatency = reactive({});
+		const errorRate = computed(() => requestCount.value > 0 ? errorCount.value / requestCount.value : 0);
+		const uptimeSeconds = computed(() => Math.floor((Date.now() - startedAt.value) / 1e3));
+		let routes = [];
+		let container = null;
+		let appRef = null;
+		const adapterStatuses = {};
+		let stopErrorWatch = null;
 		if (options.onErrorRateExceeded) {
 			const callback = options.onErrorRateExceeded;
-			const threshold = this.errorRateThreshold;
-			this.stopErrorWatch = watch(this.errorRate, (rate) => {
-				if (rate > threshold) callback(rate);
+			stopErrorWatch = watch(errorRate, (rate) => {
+				if (rate > errorRateThreshold) callback(rate);
 			});
-		} else this.stopErrorWatch = watch(this.errorRate, (rate) => {
-			if (rate > this.errorRateThreshold) log.warn(`Error rate elevated: ${(rate * 100).toFixed(1)}%`);
+		} else stopErrorWatch = watch(errorRate, (rate) => {
+			if (rate > errorRateThreshold) log.warn(`Error rate elevated: ${(rate * 100).toFixed(1)}%`);
 		});
-	}
-	/**
-	* Resolve peer adapters at request time. Prefers live adapters from the
-	* Application registry (survives HMR rebuild) and falls back to the
-	* constructor-provided refs.
-	*/
-	getPeerAdapters() {
-		const kickApp = this.appRef?.__kickApp;
-		if (kickApp && typeof kickApp.getAdapters === "function") return kickApp.getAdapters();
-		return this.peerAdapters;
-	}
-	beforeMount({ app, container }) {
-		if (!this.enabled) return;
-		this.appRef = app;
-		this.container = container;
-		this.startedAt.value = Date.now();
-		this.routes = [];
-		this.adapterStatuses[this.name] = "running";
-		const router = Router();
-		if (this.secret !== false) {
-			const token = this.secret;
-			router.use((req, res, next) => {
-				if ((req.headers["x-devtools-token"] ?? req.query?.token) === token) return next();
-				if (req.path === "/" && req.method === "GET" && !req.query?.token) return next();
-				if (req.path.endsWith(".js") || req.path.endsWith(".css")) return next();
-				res.status(403).json({ error: "Forbidden — invalid or missing devtools token" });
-			});
-		}
-		router.get("/routes", (_req, res) => {
-			res.json({ routes: this.routes });
-		});
-		router.get("/container", (_req, res) => {
-			const registrations = this.container?.getRegistrations() ?? [];
-			res.json({
-				registrations,
-				count: registrations.length
-			});
-		});
-		router.get("/metrics", (_req, res) => {
-			const latency = {};
-			for (const [key, stats] of Object.entries(this.routeLatency)) {
-				const { samples: _, ...rest } = stats;
-				latency[key] = {
-					...rest,
-					...computePercentiles(stats)
+		/**
+		* Find the dashboard's public directory. Prefers the new Solid SPA
+		* (public/spa/, shipped from PR 4 of §23); falls back to the legacy
+		* Vue+Tailwind dashboard (public/devtools/) for environments that
+		* haven't run `pnpm --filter @forinda/kickjs-devtools build:spa`.
+		*/
+		const resolvePublicDir = () => {
+			const thisDir = dirname(fileURLToPath(import.meta.url));
+			const candidates = [
+				join(thisDir, "..", "public", "spa"),
+				join(thisDir, "..", "..", "public", "spa"),
+				join(thisDir, "..", "public", "devtools"),
+				join(thisDir, "..", "..", "public", "devtools")
+			];
+			for (const dir of candidates) if (existsSync(join(dir, "index.html"))) return dir;
+			return null;
+		};
+		/**
+		* Resolve peer adapters at request time. Prefers live adapters from the
+		* Application registry (survives HMR rebuild) and falls back to the
+		* constructor-provided refs.
+		*/
+		const getPeerAdapters = () => {
+			const kickApp = appRef?.__kickApp;
+			if (kickApp && typeof kickApp.getAdapters === "function") return kickApp.getAdapters();
+			return peerAdapters;
+		};
+		return {
+			requestCount,
+			errorCount,
+			clientErrorCount,
+			startedAt,
+			errorRate,
+			uptimeSeconds,
+			routeLatency,
+			runtimeSampler,
+			memoryAnalyzer,
+			introspect() {
+				return {
+					protocolVersion: PROTOCOL_VERSION,
+					name: "DevToolsAdapter",
+					kind: "adapter",
+					state: {
+						basePath,
+						enabled,
+						runtimeEnabled,
+						secret: secret === false ? false : "present"
+					},
+					metrics: {
+						requestCount: requestCount.value,
+						serverErrors: errorCount.value,
+						clientErrors: clientErrorCount.value,
+						uptimeSeconds: uptimeSeconds.value,
+						routesTracked: routes.length
+					}
 				};
-			}
-			res.json({
-				requests: this.requestCount.value,
-				serverErrors: this.errorCount.value,
-				clientErrors: this.clientErrorCount.value,
-				errorRate: this.errorRate.value,
-				uptimeSeconds: this.uptimeSeconds.value,
-				startedAt: new Date(this.startedAt.value).toISOString(),
-				routeLatency: latency
-			});
-		});
-		router.get("/health", (_req, res) => {
-			const healthy = this.errorRate.value < this.errorRateThreshold;
-			const status = healthy ? "healthy" : "degraded";
-			res.status(healthy ? 200 : 503).json({
-				status,
-				errorRate: this.errorRate.value,
-				uptime: this.uptimeSeconds.value,
-				adapters: this.adapterStatuses
-			});
-		});
-		router.get("/state", (_req, res) => {
-			const wsAdapter = this.getPeerAdapters().find((a) => a.name === "WsAdapter" && typeof a.getStats === "function");
-			res.json({
-				reactive: {
-					requestCount: this.requestCount.value,
-					errorCount: this.errorCount.value,
-					clientErrorCount: this.clientErrorCount.value,
-					errorRate: this.errorRate.value,
-					uptimeSeconds: this.uptimeSeconds.value,
-					startedAt: new Date(this.startedAt.value).toISOString()
-				},
-				routes: this.routes.length,
-				container: this.container?.getRegistrations().length ?? 0,
-				routeLatency: this.routeLatency,
-				...wsAdapter ? { ws: wsAdapter.getStats() } : {}
-			});
-		});
-		router.get("/ws", (_req, res) => {
-			const wsAdapter = this.getPeerAdapters().find((a) => a.name === "WsAdapter" && typeof a.getStats === "function");
-			if (!wsAdapter) {
-				res.json({
-					enabled: false,
-					message: "WsAdapter not found"
+			},
+			beforeMount({ app, container: containerArg }) {
+				if (!enabled) return;
+				appRef = app;
+				container = containerArg;
+				startedAt.value = Date.now();
+				routes = [];
+				adapterStatuses["DevToolsAdapter"] = "running";
+				runtimeSampler?.start();
+				memoryAnalyzer?.start();
+				const router = Router();
+				if (secret !== false) {
+					const token = secret;
+					router.use((req, res, next) => {
+						if ((req.headers["x-devtools-token"] ?? req.query?.token) === token) return next();
+						if (req.path === "/" && req.method === "GET" && !req.query?.token) return next();
+						if (req.path.endsWith(".js") || req.path.endsWith(".css")) return next();
+						res.status(403).json({ error: "Forbidden — invalid or missing devtools token" });
+					});
+				}
+				router.get("/routes", (_req, res) => {
+					res.json({ routes });
 				});
-				return;
-			}
-			res.json({
-				enabled: true,
-				...wsAdapter.getStats()
-			});
-		});
-		router.get("/queues", async (_req, res) => {
-			const queueAdapter = this.getPeerAdapters().find((a) => a.name === "QueueAdapter" && typeof a.getQueueNames === "function");
-			if (!queueAdapter) {
-				res.json({
-					enabled: false,
-					message: "QueueAdapter not found"
+				router.get("/container", (_req, res) => {
+					const registrations = container?.getRegistrations() ?? [];
+					res.json({
+						registrations,
+						count: registrations.length
+					});
 				});
-				return;
-			}
-			try {
-				const names = queueAdapter.getQueueNames?.() ?? [];
-				const queues = [];
-				for (const name of names) {
-					const stats = await queueAdapter.getQueueStats?.(name);
-					queues.push({
-						name,
-						...stats
+				router.get("/metrics", (_req, res) => {
+					const latency = {};
+					for (const [key, stats] of Object.entries(routeLatency)) {
+						const { samples: _, ...rest } = stats;
+						latency[key] = {
+							...rest,
+							...computePercentiles(stats)
+						};
+					}
+					res.json({
+						requests: requestCount.value,
+						serverErrors: errorCount.value,
+						clientErrors: clientErrorCount.value,
+						errorRate: errorRate.value,
+						uptimeSeconds: uptimeSeconds.value,
+						startedAt: new Date(startedAt.value).toISOString(),
+						routeLatency: latency
 					});
-				}
-				res.json({
-					enabled: true,
-					queues
 				});
-			} catch {
-				res.json({
-					enabled: true,
-					queues: [],
-					error: "Failed to fetch queue stats"
+				router.get("/health", (_req, res) => {
+					const healthy = errorRate.value < errorRateThreshold;
+					const status = healthy ? "healthy" : "degraded";
+					res.status(healthy ? 200 : 503).json({
+						status,
+						errorRate: errorRate.value,
+						uptime: uptimeSeconds.value,
+						adapters: adapterStatuses
+					});
 				});
-			}
-		});
-		router.get("/graph", (_req, res) => {
-			const registrations = this.container?.getRegistrations() ?? [];
-			const nodes = registrations.filter((r) => !r.token.startsWith("__hmr__")).map((r) => ({
-				id: r.token,
-				kind: r.kind,
-				scope: r.scope,
-				resolveCount: r.resolveCount
-			}));
-			const nodeIds = new Set(nodes.map((n) => n.id));
-			const edges = [];
-			for (const r of registrations) {
-				if (r.token.startsWith("__hmr__")) continue;
-				for (const dep of r.dependencies) if (nodeIds.has(dep)) edges.push({
-					from: r.token,
-					to: dep
+				router.get("/state", (_req, res) => {
+					const wsAdapter = getPeerAdapters().find((a) => a.name === "WsAdapter" && typeof a.getStats === "function");
+					res.json({
+						reactive: {
+							requestCount: requestCount.value,
+							errorCount: errorCount.value,
+							clientErrorCount: clientErrorCount.value,
+							errorRate: errorRate.value,
+							uptimeSeconds: uptimeSeconds.value,
+							startedAt: new Date(startedAt.value).toISOString()
+						},
+						routes: routes.length,
+						container: container?.getRegistrations().length ?? 0,
+						routeLatency,
+						...wsAdapter ? { ws: wsAdapter.getStats() } : {}
+					});
 				});
-			}
-			res.json({
-				nodes,
-				edges
-			});
-		});
-		router.get("/stream", (req, res) => {
-			res.writeHead(200, {
-				"Content-Type": "text/event-stream",
-				"Cache-Control": "no-cache",
-				Connection: "keep-alive"
-			});
-			const sendMetrics = () => {
-				const data = {
-					type: "metrics",
-					requestCount: this.requestCount.value,
-					errorCount: this.errorCount.value,
-					clientErrorCount: this.clientErrorCount.value,
-					errorRate: this.errorRate.value,
-					uptimeSeconds: this.uptimeSeconds.value
-				};
-				res.write(`data: ${JSON.stringify(data)}\n\n`);
-			};
-			sendMetrics();
-			const unsubContainer = this.container?.onChange?.((changes) => {
-				res.write(`data: ${JSON.stringify({
-					type: "container",
-					changes,
-					timestamp: Date.now()
-				})}\n\n`);
-				sendMetrics();
-			});
-			const stopRequestWatch = watch(this.requestCount, () => sendMetrics());
-			const stopErrorWatch = watch(this.errorCount, () => sendMetrics());
-			const heartbeat = setInterval(() => {
-				res.write(`: heartbeat\n\n`);
-			}, 3e4);
-			req.on("close", () => {
-				unsubContainer?.();
-				stopRequestWatch();
-				stopErrorWatch();
-				clearInterval(heartbeat);
-			});
-		});
-		if (this.exposeConfig) router.get("/config", (_req, res) => {
-			const config = {};
-			for (const [key, value] of Object.entries(process.env)) {
-				if (value === void 0) continue;
-				config[key] = this.configPrefixes.some((prefix) => key.startsWith(prefix)) ? value : "[REDACTED]";
-			}
-			res.json({ config });
-		});
-		const publicDir = this.resolvePublicDir();
-		if (publicDir) {
-			router.use(static$1(publicDir));
-			const indexHtml = readFileSync(join(publicDir, "index.html"), "utf-8");
-			router.get("/", (_req, res) => {
-				const html = indexHtml.replace("<body", `<body data-base="${this.basePath}"`);
-				res.type("html").send(html);
-			});
-		} else router.get("/", (_req, res) => {
-			res.type("html").send("<h1>DevTools: public directory not found</h1>");
-		});
-		app.use(this.basePath, router);
-		if (this.secret) {
-			log.info(`DevTools mounted at ${this.basePath} [token: ${this.secret}]`);
-			log.info(`Access: ${this.basePath}?token=${this.secret}`);
-		} else log.info(`DevTools mounted at ${this.basePath} [no guard]`);
-	}
-	middleware() {
-		if (!this.enabled) return [];
-		return [{
-			handler: (req, res, next) => {
-				const start = Date.now();
-				this.requestCount.value++;
-				res.on("finish", () => {
-					if (res.statusCode >= 500) this.errorCount.value++;
-					else if (res.statusCode >= 400) this.clientErrorCount.value++;
-					const routeKey = `${req.method} ${req.route?.path ?? req.path}`;
-					const elapsed = Date.now() - start;
-					if (!this.routeLatency[routeKey]) this.routeLatency[routeKey] = {
-						count: 0,
-						totalMs: 0,
-						minMs: Infinity,
-						maxMs: 0,
-						samples: []
+				router.get("/runtime", (_req, res) => {
+					if (!runtimeSampler || !memoryAnalyzer) {
+						res.status(404).json({ error: "runtime sampler disabled — set runtime.enabled = true" });
+						return;
+					}
+					const latest = runtimeSampler.latest();
+					const history = runtimeSampler.history();
+					const health = memoryAnalyzer.health(history);
+					res.json({
+						protocolVersion: PROTOCOL_VERSION,
+						latest,
+						history,
+						health
+					});
+				});
+				router.get("/runtime/stream", (req, res) => {
+					if (!runtimeSampler) {
+						res.status(404).json({ error: "runtime sampler disabled" });
+						return;
+					}
+					openSseStream(req, res);
+					const intervalMs = options.runtime?.intervalMs ?? 1e3;
+					const tick = () => {
+						const snap = runtimeSampler.latest();
+						if (snap) writeSseEvent(res, snap);
 					};
-					const stats = this.routeLatency[routeKey];
-					stats.count++;
-					stats.totalMs += elapsed;
-					stats.minMs = Math.min(stats.minMs, elapsed);
-					stats.maxMs = Math.max(stats.maxMs, elapsed);
-					stats.samples.push(elapsed);
-					if (stats.samples.length > MAX_SAMPLES) stats.samples.shift();
+					tick();
+					const interval = setInterval(tick, intervalMs);
+					const heartbeat = setInterval(() => res.write(": heartbeat\n\n"), 3e4);
+					req.on("close", () => {
+						clearInterval(interval);
+						clearInterval(heartbeat);
+					});
 				});
-				next();
+				router.get("/memory/stream", (req, res) => {
+					if (!runtimeSampler || !memoryAnalyzer) {
+						res.status(404).json({ error: "runtime sampler disabled" });
+						return;
+					}
+					openSseStream(req, res);
+					const intervalMs = options.runtime?.intervalMs ?? 1e3;
+					const tick = () => {
+						const snap = runtimeSampler.latest();
+						if (!snap) return;
+						writeSseEvent(res, {
+							snapshot: snap,
+							health: memoryAnalyzer.health(runtimeSampler.history())
+						});
+					};
+					tick();
+					const interval = setInterval(tick, intervalMs);
+					const heartbeat = setInterval(() => res.write(": heartbeat\n\n"), 3e4);
+					req.on("close", () => {
+						clearInterval(interval);
+						clearInterval(heartbeat);
+					});
+				});
+				router.post("/memory/snapshot", (_req, res) => {
+					if (snapshotInProgress) {
+						res.status(503).json({ error: "heap snapshot already in progress — wait for it to complete" });
+						return;
+					}
+					snapshotInProgress = true;
+					const startedAt = Date.now();
+					const filename = `kickjs-heap-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.heapsnapshot`;
+					const targetPath = join(tmpdir(), filename);
+					let written;
+					try {
+						written = writeHeapSnapshot(targetPath);
+					} catch (err) {
+						snapshotInProgress = false;
+						log.error({ err }, "heap snapshot capture failed");
+						res.status(500).json({
+							error: "snapshot capture failed",
+							message: err.message
+						});
+						return;
+					}
+					let size = 0;
+					try {
+						size = statSync(written).size;
+					} catch {}
+					const elapsedMs = Date.now() - startedAt;
+					log.info(`Heap snapshot captured: ${written} (${(size / 1024 / 1024).toFixed(1)} MiB in ${elapsedMs}ms)`);
+					res.setHeader("Content-Type", "application/json");
+					res.setHeader("Content-Disposition", `attachment; filename="${filename}"`);
+					if (size > 0) res.setHeader("Content-Length", String(size));
+					res.setHeader("X-Snapshot-Capture-Ms", String(elapsedMs));
+					const cleanup = () => {
+						unlink(written, (err) => {
+							if (err) log.warn(`Failed to delete heap snapshot ${written}: ${err.message}`);
+							snapshotInProgress = false;
+						});
+					};
+					const stream = createReadStream(written);
+					stream.on("end", cleanup);
+					stream.on("error", (err) => {
+						log.error({ err }, "heap snapshot stream failed");
+						if (!res.headersSent) res.status(500).end();
+						cleanup();
+					});
+					res.on("close", () => {
+						stream.destroy();
+					});
+					stream.pipe(res);
+				});
+				router.post("/memory/gc", (_req, res) => {
+					const gc = globalThis.gc;
+					if (typeof gc !== "function") {
+						res.status(412).json({ error: "global.gc unavailable — start Node with --expose-gc to enable this endpoint" });
+						return;
+					}
+					const before = process.memoryUsage().heapUsed;
+					const startedAt = Date.now();
+					try {
+						gc();
+					} catch (err) {
+						res.status(500).json({
+							error: "forced GC failed",
+							message: err instanceof Error ? err.message : String(err)
+						});
+						return;
+					}
+					const after = process.memoryUsage().heapUsed;
+					const reclaimedBytes = Math.max(0, before - after);
+					const elapsedMs = Date.now() - startedAt;
+					log.info(`Forced GC reclaimed ${(reclaimedBytes / 1024 / 1024).toFixed(2)} MiB in ${elapsedMs}ms`);
+					res.json({
+						before,
+						after,
+						reclaimedBytes,
+						elapsedMs
+					});
+				});
+				router.get("/tabs", (_req, res) => {
+					const kickApp = appRef?.__kickApp;
+					if (!kickApp) {
+						res.status(503).json({ error: "tabs unavailable — application surface not exposed" });
+						return;
+					}
+					res.json(collectDevtoolsTabs(kickApp));
+				});
+				router.get("/topology", async (_req, res) => {
+					if (!container) {
+						res.status(503).json({ error: "topology unavailable — container not bound yet" });
+						return;
+					}
+					const kickApp = appRef?.__kickApp;
+					if (!kickApp) {
+						res.status(503).json({ error: "topology unavailable — application surface not exposed" });
+						return;
+					}
+					try {
+						const snapshot = await collectTopologySnapshot({
+							app: kickApp,
+							container
+						});
+						res.json(snapshot);
+					} catch (err) {
+						const message = err instanceof Error ? err.message : String(err);
+						res.status(500).json({
+							error: "topology collection failed",
+							message
+						});
+					}
+				});
+				router.get("/ws", (_req, res) => {
+					const wsAdapter = getPeerAdapters().find((a) => a.name === "WsAdapter" && typeof a.getStats === "function");
+					if (!wsAdapter) {
+						res.json({
+							enabled: false,
+							message: "WsAdapter not found"
+						});
+						return;
+					}
+					res.json({
+						enabled: true,
+						...wsAdapter.getStats()
+					});
+				});
+				router.get("/queues", async (_req, res) => {
+					const queueAdapter = getPeerAdapters().find((a) => a.name === "QueueAdapter" && typeof a.getQueueNames === "function");
+					if (!queueAdapter) {
+						res.json({
+							enabled: false,
+							message: "QueueAdapter not found"
+						});
+						return;
+					}
+					try {
+						const names = queueAdapter.getQueueNames?.() ?? [];
+						const queues = [];
+						for (const name of names) {
+							const stats = await queueAdapter.getQueueStats?.(name);
+							queues.push({
+								name,
+								...stats
+							});
+						}
+						res.json({
+							enabled: true,
+							queues
+						});
+					} catch {
+						res.json({
+							enabled: true,
+							queues: [],
+							error: "Failed to fetch queue stats"
+						});
+					}
+				});
+				router.get("/graph", (_req, res) => {
+					const registrations = container?.getRegistrations() ?? [];
+					const nodes = registrations.filter((r) => !r.token.startsWith("__hmr__")).map((r) => ({
+						id: r.token,
+						kind: r.kind,
+						scope: r.scope,
+						resolveCount: r.resolveCount
+					}));
+					const nodeIds = new Set(nodes.map((n) => n.id));
+					const edges = [];
+					for (const r of registrations) {
+						if (r.token.startsWith("__hmr__")) continue;
+						for (const dep of r.dependencies) if (nodeIds.has(dep)) edges.push({
+							from: r.token,
+							to: dep
+						});
+					}
+					res.json({
+						nodes,
+						edges
+					});
+				});
+				router.get("/stream", (req, res) => {
+					res.writeHead(200, {
+						"Content-Type": "text/event-stream",
+						"Cache-Control": "no-cache",
+						Connection: "keep-alive"
+					});
+					const sendMetrics = () => {
+						const data = {
+							type: "metrics",
+							requestCount: requestCount.value,
+							errorCount: errorCount.value,
+							clientErrorCount: clientErrorCount.value,
+							errorRate: errorRate.value,
+							uptimeSeconds: uptimeSeconds.value
+						};
+						res.write(`data: ${JSON.stringify(data)}\n\n`);
+					};
+					sendMetrics();
+					const unsubContainer = container?.onChange?.((changes) => {
+						res.write(`data: ${JSON.stringify({
+							type: "container",
+							changes,
+							timestamp: Date.now()
+						})}\n\n`);
+						sendMetrics();
+					});
+					const stopRequestWatch = watch(requestCount, () => sendMetrics());
+					const stopErrWatch = watch(errorCount, () => sendMetrics());
+					const heartbeat = setInterval(() => {
+						res.write(`: heartbeat\n\n`);
+					}, 3e4);
+					req.on("close", () => {
+						unsubContainer?.();
+						stopRequestWatch();
+						stopErrWatch();
+						clearInterval(heartbeat);
+					});
+				});
+				if (exposeConfig) router.get("/config", (_req, res) => {
+					const config = {};
+					for (const [key, value] of Object.entries(process.env)) {
+						if (value === void 0) continue;
+						config[key] = configPrefixes.some((prefix) => key.startsWith(prefix)) ? value : "[REDACTED]";
+					}
+					res.json({ config });
+				});
+				const publicDir = resolvePublicDir();
+				if (publicDir) {
+					router.use(static$1(publicDir));
+					const indexHtml = readFileSync(join(publicDir, "index.html"), "utf-8");
+					router.get("/", (_req, res) => {
+						const html = indexHtml.replace("<body", `<body data-base="${basePath}"`);
+						res.type("html").send(html);
+					});
+				} else router.get("/", (_req, res) => {
+					res.type("html").send("<h1>DevTools: public directory not found</h1>");
+				});
+				app.use(basePath, router);
+				if (secret) {
+					log.info(`DevTools mounted at ${basePath} [token: ${secret}]`);
+					log.info(`Access: ${basePath}?token=${secret}`);
+				} else log.info(`DevTools mounted at ${basePath} [no guard]`);
 			},
-			phase: "beforeGlobal"
-		}];
-	}
-	onRouteMount(controllerClass, mountPath) {
-		if (!this.enabled) return;
-		const routes = getClassMeta(METADATA.ROUTES, controllerClass, []);
-		const classMiddleware = getClassMeta(METADATA.CLASS_MIDDLEWARES, controllerClass, []);
-		for (const route of routes) {
-			const methodMiddleware = getMethodMeta(METADATA.METHOD_MIDDLEWARES, controllerClass.prototype, route.handlerName, []);
-			this.routes.push({
-				method: route.method.toUpperCase(),
-				path: `${mountPath}${route.path === "/" ? "" : route.path}`,
-				controller: controllerClass.name,
-				handler: route.handlerName,
-				middleware: [...classMiddleware.map((m) => m.name || "anonymous"), ...methodMiddleware.map((m) => m.name || "anonymous")]
-			});
-		}
-	}
-	afterStart({}) {
-		if (!this.enabled) return;
-		log.info(`DevTools ready — ${this.routes.length} routes tracked, ${this.container?.getRegistrations().length ?? 0} DI bindings`);
-	}
-	shutdown() {
-		this.stopErrorWatch?.();
-		this.adapterStatuses[this.name] = "stopped";
-	}
-	/** Find the public/devtools directory relative to the built dist or source */
-	resolvePublicDir() {
-		const thisDir = dirname(fileURLToPath(import.meta.url));
-		const candidates = [join(thisDir, "..", "public", "devtools"), join(thisDir, "..", "..", "public", "devtools")];
-		for (const dir of candidates) if (existsSync(join(dir, "index.html"))) return dir;
-		return null;
+			middleware() {
+				if (!enabled) return [];
+				return [{
+					handler: (req, res, next) => {
+						const start = Date.now();
+						requestCount.value++;
+						res.on("finish", () => {
+							if (res.statusCode >= 500) errorCount.value++;
+							else if (res.statusCode >= 400) clientErrorCount.value++;
+							const routeKey = `${req.method} ${req.route?.path ?? req.path}`;
+							const elapsed = Date.now() - start;
+							if (!routeLatency[routeKey]) routeLatency[routeKey] = {
+								count: 0,
+								totalMs: 0,
+								minMs: Infinity,
+								maxMs: 0,
+								samples: []
+							};
+							const stats = routeLatency[routeKey];
+							stats.count++;
+							stats.totalMs += elapsed;
+							stats.minMs = Math.min(stats.minMs, elapsed);
+							stats.maxMs = Math.max(stats.maxMs, elapsed);
+							stats.samples.push(elapsed);
+							if (stats.samples.length > MAX_SAMPLES) stats.samples.shift();
+						});
+						next();
+					},
+					phase: "beforeGlobal"
+				}];
+			},
+			onRouteMount(controllerClass, mountPath) {
+				if (!enabled) return;
+				const collectedRoutes = getClassMeta(METADATA.ROUTES, controllerClass, []);
+				const classMiddleware = getClassMeta(METADATA.CLASS_MIDDLEWARES, controllerClass, []);
+				for (const route of collectedRoutes) {
+					const methodMiddleware = getMethodMeta(METADATA.METHOD_MIDDLEWARES, controllerClass.prototype, route.handlerName, []);
+					routes.push({
+						method: route.method.toUpperCase(),
+						path: `${mountPath}${route.path === "/" ? "" : route.path}`,
+						controller: controllerClass.name,
+						handler: route.handlerName,
+						middleware: [...classMiddleware.map((m) => m.name || "anonymous"), ...methodMiddleware.map((m) => m.name || "anonymous")]
+					});
+				}
+			},
+			afterStart() {
+				if (!enabled) return;
+				log.info(`DevTools ready — ${routes.length} routes tracked, ${container?.getRegistrations().length ?? 0} DI bindings`);
+			},
+			shutdown() {
+				stopErrorWatch?.();
+				runtimeSampler?.stop();
+				memoryAnalyzer?.stop();
+				adapterStatuses["DevToolsAdapter"] = "stopped";
+			}
+		};
 	}
-};
+});
 //#endregion
 export { DevToolsAdapter };