@ogygia/devtools 0.0.0 → 0.11.1

package/dist/profiler/embedded-maps.js

@@ -0,0 +1,135 @@
+import { PROFILER_MAPS_GZ_PREFIX } from "@ogygia/core/internal/compiler-ids";
+// src/profiler/embedded-maps.ts
+let loaded;
+let ready = null;
+function load_embedded_maps() {
+	loaded ??= import("virtual:ogygia/profiler-maps").then(async (m) => {
+		let raw = m.default;
+		if (typeof raw === "string" && raw.startsWith(PROFILER_MAPS_GZ_PREFIX)) raw = (await import("node:zlib")).gunzipSync(Buffer.from(raw.slice(PROFILER_MAPS_GZ_PREFIX.length), "base64")).toString("utf8");
+		if (typeof raw !== "string" || !raw.startsWith("{")) return null;
+		const p = JSON.parse(raw);
+		return p.v === 1 && p.maps && p.modules ? ready = {
+			modules: p.modules,
+			maps: p.maps,
+			...p.sources && typeof p.sources === "object" ? { sources: p.sources } : {},
+			...p.chunks && typeof p.chunks === "object" ? { chunks: p.chunks } : {}
+		} : null;
+	}).catch(() => null);
+	return loaded;
+}
+/** the maps once loaded (synchronous readers: the module map lookup), else null */
+const embedded_maps = () => ready;
+/** a script's key in the payload: its path under the server output (`chunks/format.js`), whether it
+*  runs from Kit's output itself (a host that copies it, like Vercel's) or is named as a map source
+*  by an adapter that re-bundled it (adapter-node: `…/.svelte-kit/output/server/chunks/x.js`) */
+function embedded_key(path) {
+	const p = path.split("\\").join("/");
+	const at = p.lastIndexOf("/output/server/");
+	if (at === -1) {
+		const imm = p.lastIndexOf("/immutable/");
+		if (imm <= 0) return void 0;
+		const app = p.lastIndexOf("/", imm - 1);
+		if (app === -1) return void 0;
+		const q = p.indexOf("?", imm);
+		return "client/" + p.slice(app + 1, q === -1 ? void 0 : q);
+	}
+	const kit = p.lastIndexOf("/.svelte-kit/", at);
+	if (kit !== -1 && kit + 12 === at) roots.add(p.slice(0, kit));
+	return p.slice(at + 15);
+}
+/** app roots seen in chunk paths (`<root>/.svelte-kit/output/server/…`) */
+const roots = /* @__PURE__ */ new Set();
+const VIRTUAL_OUTPUT = "/ROOT/.svelte-kit/output/";
+const VIRTUAL_SERVER = VIRTUAL_OUTPUT + "server/";
+const VIRTUAL_SRC = "/ROOT/src/";
+/** `a/b/../c/./d` → `a/c/d` (posix, absolute input) */
+function normalize(p) {
+	const out = [];
+	for (const part of p.split("/")) {
+		if (part === "" || part === ".") continue;
+		if (part === "..") out.pop();
+		else out.push(part);
+	}
+	return "/" + out.join("/");
+}
+/** the build's map of a chunk, by its path: the text the build wrote, or undefined */
+function embedded_map_of(path) {
+	const key = embedded_key(path);
+	return key !== void 0 ? ready?.maps[key] : void 0;
+}
+/** a built chunk's text the build carried (a build without maps, for a host that re-bundled it) */
+function embedded_chunk(path) {
+	const key = embedded_key(path);
+	return key !== void 0 ? ready?.chunks?.[key] : void 0;
+}
+/** src-relative path (`routes/x/+page.server.ts`) → the source text the maps carry, built once */
+let sources;
+/**
+* AN APP SOURCE FILE'S TEXT FROM THE MAPS (`sourcesContent`): the only copy on a deployed host, where
+* `src/` is not there. What the source-reading checks (a load read line by line, a component's
+* `{#each}`, a late island's data) read when the file is not on disk. `file` is src-relative or has
+* a leading `src/`; undefined when no map carries it.
+*/
+function embedded_source(file) {
+	const index = source_index();
+	if (!index) return void 0;
+	const f = file.split("\\").join("/");
+	if (f.includes("/node_modules/")) return void 0;
+	let rel;
+	if (f.startsWith("src/")) rel = f.slice(4);
+	else if (f.startsWith("/")) {
+		for (const r of [...roots, cwd()]) if (r && f.startsWith(r + "/src/")) {
+			rel = f.slice(r.length + 5);
+			break;
+		}
+	} else rel = f;
+	return rel === void 0 ? void 0 : index.get(rel);
+}
+function cwd() {
+	try {
+		return process.cwd().split("\\").join("/");
+	} catch {
+		return;
+	}
+}
+/** every app source file the maps carry, src-relative */
+function embedded_files() {
+	return [...source_index()?.keys() ?? []];
+}
+function source_index() {
+	if (!ready) return void 0;
+	if (!sources) {
+		sources = /* @__PURE__ */ new Map();
+		for (const [key, raw] of Object.entries(ready.maps)) {
+			let map;
+			try {
+				map = JSON.parse(raw);
+			} catch {
+				continue;
+			}
+			const dir = (key.startsWith("client/") ? VIRTUAL_OUTPUT : VIRTUAL_SERVER) + key.slice(0, key.lastIndexOf("/") + 1);
+			const list = map.sources ?? [];
+			for (let i = 0; i < list.length; i++) {
+				const text = map.sourcesContent?.[i];
+				if (typeof text !== "string") continue;
+				const s = ((map.sourceRoot ?? "") + list[i]).split("\\").join("/");
+				if (s.startsWith("/") || s.includes(":")) continue;
+				const p = normalize(dir + s);
+				if (!p.startsWith(VIRTUAL_SRC)) continue;
+				const rel = p.slice(10);
+				if (!sources.has(rel)) sources.set(rel, text);
+			}
+		}
+		for (const [id, text] of Object.entries(ready.sources ?? {})) if (id.startsWith("src/") && typeof text === "string" && !sources.has(id.slice(4))) sources.set(id.slice(4), text);
+	}
+	return sources;
+}
+/** the module at a chunk line, from the embedded module map (a host that dropped the file beside the
+*  chunks) */
+function embedded_module_at(path, line) {
+	const key = embedded_key(path);
+	const ranges = key !== void 0 ? ready?.modules[key] : void 0;
+	if (!ranges) return void 0;
+	for (const [a, b, id] of ranges) if (line >= a && line <= b) return id;
+}
+export { embedded_chunk, embedded_files, embedded_key, embedded_map_of, embedded_maps, embedded_module_at, embedded_source, load_embedded_maps };

package/dist/profiler/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Is this a dev server? Vite replaces `import.meta.env.DEV` at build time; a plain-Node run falls
+ * back to NODE_ENV. Its own module so a test can mock the answer (the value is otherwise a
+ * compile-time constant inside the profiler) and exercise the production request path.
+ */
+export declare function detect_dev(): boolean;

package/dist/profiler/env.js

@@ -0,0 +1,10 @@
+// src/profiler/env.ts
+/**
+* Is this a dev server? Vite replaces `import.meta.env.DEV` at build time; a plain-Node run falls
+* back to NODE_ENV. Its own module so a test can mock the answer (the value is otherwise a
+* compile-time constant inside the profiler) and exercise the production request path.
+*/
+function detect_dev() {
+	return typeof import.meta !== "undefined" && import.meta.env?.DEV === true || process.env.NODE_ENV === "development";
+}
+export { detect_dev };

package/dist/profiler/forecast.d.ts

@@ -0,0 +1,76 @@
+import { DrillNode } from "./drill.js";
+import { Pattern } from "./patterns.js";
+import { CallStack } from "./analyze.js";
+import { saving_of } from "./saving.js";
+export interface Forecast {
+  /** one render now: the median of the profiled renders, ms, as the app paid it */
+  now_ms: number;
+  /** one render with every fix below, ms (an estimate) */
+  after_ms: number;
+  /** what the render used, which capped the savings: its waiting and its CPU, ms (the compare's
+   *  fix check counts a later report's fixes the same way) */
+  caps?: {
+    wait?: number;
+    cpu?: number;
+  };
+  /** the parts of the saving: CPU, waiting, and work deleted, ms per render */
+  cpu_ms: number;
+  wait_ms: number;
+  delete_ms: number;
+  /** the main thread's CPU a render, now and after every fix (ms): what bounds how many renders a
+   *  core serves — the waiting fixes cut the time a visitor waits, only the CPU ones raise that */
+  cpu_now_ms?: number;
+  cpu_after_ms?: number;
+  /** the fixes counted, biggest first; `with`: the other fixes on the same lines, whose saving
+   *  this one already covers; `after_ms`: one render once this fix AND every one above it is done */
+  parts: {
+    title: string;
+    kind: string;
+    ms: number;
+    wait: boolean;
+    after_ms?: number;
+    with?: string[];
+  }[];
+  /** caching the services' answers on top (same answer every render): one render after that, and
+   *  those fixes. A decision about how stale an answer may be, so left out of `after_ms` */
+  answers?: {
+    after_ms: number;
+    wait_ms: number;
+    parts: Forecast["parts"];
+    clamped?: boolean;
+    /** the page was rendered with those answers served from memory: `ms` is that render (the
+     *  median of `renders`), and `after_ms` is it with the code fixes the caching does not cover
+     *  taken off; `model_ms` what the lines alone estimated */
+    measured?: {
+      ms: number;
+      renders: number;
+      model_ms: number;
+    };
+  };
+  /** the whole document is cacheable: a cached copy costs the render nothing — a different lever,
+   *  left out of `after_ms` */
+  cache?: boolean;
+  /** the savings claimed more waiting or CPU than the render had (they overlap in ways the lines
+   *  do not show): each was held at what the render used */
+  clamped?: boolean;
+  /** the build had no sourcemaps: the profiler saw fewer lines, so fewer fixes — the real time
+   *  after them is likely lower */
+  partial?: boolean;
+}
+export interface ForecastInputs {
+  /** the waiting on one render's critical path — whatever the wait fixes claim, together they
+   *  cannot take off more than the render waited */
+  wait_cap?: number;
+  /** the app's CPU in one render: every CPU saving together cannot take off more */
+  cpu_cap?: number;
+  /** a function's heaviest call paths (functions table key → stacks): which work runs only
+   *  inside a call another fix takes out of the request */
+  stacks?: (fn: string) => readonly CallStack[] | undefined;
+  /** the page rendered with its same-every-time answers served from memory (ms per render) */
+  answers_runs?: readonly number[];
+  /** the main thread's CPU in one render: the sampled stacks (app, components, packages, Node) and
+   *  the collector's pauses there */
+  cpu_main?: number;
+}
+export declare function forecast_of(runs: readonly number[] | undefined, patterns: readonly Pattern[] | undefined, drill: DrillNode | undefined, inputs?: ForecastInputs): Forecast | undefined;
+export { saving_of };

package/dist/profiler/forecast.js

@@ -0,0 +1,225 @@
+import { tokens } from "./source-scan.js";
+import { saving_of } from "./saving.js";
+// src/profiler/forecast.ts
+const r1 = (n) => Math.round(n * 10) / 10;
+const place = (p) => p.startsWith("src/") ? p.slice(4) : p;
+function forecast_of(runs, patterns, drill, inputs = {}) {
+	const { wait_cap, cpu_cap, stacks } = inputs;
+	if (!runs?.length) return void 0;
+	const sorted = [...runs].sort((a, b) => a - b);
+	const mid = sorted.length >> 1;
+	const now = sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+	const n = runs.length;
+	const items = [];
+	const gone = /* @__PURE__ */ new Set();
+	const unread = (d, above, waiting) => {
+		const in_wait = waiting || d.kind === "wait";
+		if (d.fills?.length && d.fills.every((f) => !f.read)) {
+			const keys = [`unread\0${items.length}`, ...above];
+			const all_lines = (m) => {
+				if (m.at) {
+					gone.add(place(m.at));
+					keys.push(place(m.at));
+				}
+				for (const c of m.children ?? []) all_lines(c);
+			};
+			all_lines(d);
+			const names = /* @__PURE__ */ new Set();
+			const called = (m) => {
+				if (m.code) {
+					const t = tokens(m.code);
+					for (let k = 0; k + 1 < t.length; k++) if (t[k + 1] === "(" && t[k - 1] !== "." && t[k - 1] !== "?.") names.add(t[k]);
+				}
+				for (const c of m.children ?? []) called(c);
+			};
+			called(d);
+			items.push({
+				title: `Delete work for data nothing reads (${d.fills.map((f) => f.key).join(", ")})`,
+				kind: "unread-work",
+				ms: d.ms,
+				wait: in_wait,
+				keys,
+				calls: names,
+				soft: new Set(above)
+			});
+			return;
+		}
+		const next = d.kind === "line" && d.at ? [...above, place(d.at)] : above;
+		for (const c of d.children ?? []) unread(c, next, in_wait);
+	};
+	if (drill) unread(drill, [], false);
+	for (let i = 0; i < items.length; i++) {
+		const a = items[i];
+		if (a.kind !== "unread-work") continue;
+		for (let j = items.length - 1; j > i; j--) {
+			const b = items[j];
+			if (b.kind !== "unread-work" || b.title !== a.title || b.wait !== a.wait) continue;
+			a.ms += b.ms;
+			a.keys.push(...b.keys);
+			for (const c of b.calls ?? []) (a.calls ??= /* @__PURE__ */ new Set()).add(c);
+			for (const s of b.soft ?? []) (a.soft ??= /* @__PURE__ */ new Set()).add(s);
+			items.splice(j, 1);
+		}
+	}
+	let cache = false;
+	for (const p of patterns ?? []) {
+		if (p.kind === "same-document" || p.kind === "almost-same-document") {
+			cache = true;
+			continue;
+		}
+		const ms = (p.save_ms ?? 0) / (p.wait ? 1 : n);
+		if (ms <= 0) continue;
+		const key = (x) => place(`${x.file}:${x.line}`);
+		if (p.sites.length && p.sites.every((s) => gone.has(key(s)) || !!s.via?.length && s.via.every((v) => gone.has(key(v))))) continue;
+		const keys = /* @__PURE__ */ new Set();
+		for (const s of p.sites) {
+			keys.add(key(s));
+			for (const v of s.via ?? []) keys.add(key(v));
+		}
+		items.push({
+			title: p.title ?? p.kind,
+			kind: p.kind,
+			ms,
+			wait: !!p.wait,
+			keys: [...keys],
+			p
+		});
+	}
+	for (const mover of items.filter((it) => it.kind === "same-every-request")) {
+		const moved = new Set(mover.p.sites.flatMap((s) => s.moves ?? (s.fn_name ? [s.fn_name] : [])));
+		if (!moved.size) continue;
+		const under = (s) => {
+			if (s.fn_name && moved.has(s.fn_name)) return true;
+			const st = s.fn ? stacks?.(s.fn) : void 0;
+			if (!st?.length) return false;
+			const total = st.reduce((t, x) => t + x.ms, 0);
+			const inside = st.filter((x) => x.frames.some((f) => moved.has(f.n))).reduce((t, x) => t + x.ms, 0);
+			return total > 0 && inside >= total * .9;
+		};
+		for (const it of items) {
+			if (it === mover || it.wait || !it.p?.sites.length || !it.p.sites.every(under)) continue;
+			it.keys.push(mover.keys[0]);
+		}
+	}
+	for (const del of items.filter((it) => it.kind === "unread-work" && it.calls?.size && !it.wait)) for (const it of items) {
+		if (!it.p || it.wait || !it.p.sites.length || !it.p.sites.every((s) => !!s.fn_name && del.calls.has(s.fn_name))) continue;
+		it.keys.push(del.keys[0]);
+	}
+	/** the saving of a set of fixes: grouped by shared lines (a union of every pattern that touches
+	*  a line another touches), CPU and waits apart — a line's wait and its CPU are different time */
+	const saving = (set) => {
+		const parent = set.map((_, i) => i);
+		const find = (i) => parent[i] === i ? i : parent[i] = find(parent[i]);
+		const owners = /* @__PURE__ */ new Map();
+		set.forEach((it, i) => {
+			for (const k of it.keys) {
+				const tag = `${it.wait ? "w" : "c"}\0${k}`;
+				const on = owners.get(tag) ?? owners.set(tag, []).get(tag);
+				for (const j of on) {
+					const other = set[j];
+					if (it.kind === "unread-work" && other.kind === "unread-work" && (it.soft?.has(k) || other.soft?.has(k))) continue;
+					parent[find(i)] = find(j);
+				}
+				on.push(i);
+			}
+		});
+		const groups = /* @__PURE__ */ new Map();
+		set.forEach((it, i) => {
+			const g = find(i);
+			(groups.get(g) ?? groups.set(g, []).get(g)).push(it);
+		});
+		const tops = [...groups.values()].map((g) => {
+			g.sort((a, b) => b.ms - a.ms);
+			return {
+				top: g[0],
+				others: g.slice(1).map((x) => x.title)
+			};
+		}).sort((a, b) => b.top.ms - a.top.ms);
+		/** what a set of groups takes off together. EACH RESOURCE CAPPED BY WHAT THE RENDER USED:
+		*  every saving on the clock (the wait fixes and the waits deleted) takes off at most the
+		*  render's waiting; every CPU saving at most its CPU. Past that they overlap in a way the
+		*  lines do not show */
+		const together = (set) => saving_of(set, {
+			wait: wait_cap,
+			cpu: cpu_cap
+		}, now);
+		const seen = /* @__PURE__ */ new Map();
+		for (const { top } of tops) seen.set(top.title, (seen.get(top.title) ?? 0) + 1);
+		const named = /* @__PURE__ */ new Set();
+		const title_of = (top) => {
+			if (seen.get(top.title) === 1) return top.title;
+			const site = top.p?.sites[0];
+			let t = site ? `${top.title} (${site.file}:${site.line})` : top.title;
+			for (let n = 2; named.has(t); n++) t = `${top.title} (${n})`;
+			named.add(t);
+			return t;
+		};
+		const parts = tops.map(({ top, others }, i) => ({
+			title: title_of(top),
+			kind: top.kind,
+			ms: r1(top.ms),
+			wait: top.wait,
+			after_ms: r1(together(tops.slice(0, i + 1).map((x) => x.top)).after),
+			...others.length ? { with: others } : {}
+		}));
+		return {
+			...together(tops.map((x) => x.top)),
+			parts,
+			tops
+		};
+	};
+	const caching = (it) => CACHING.has(it.kind);
+	const code = saving(items.filter((it) => !caching(it)));
+	const cached = items.some(caching) ? saving(items) : void 0;
+	let measured;
+	const ar = inputs.answers_runs;
+	if (cached && ar?.length) {
+		const s = [...ar].sort((a, b) => a - b);
+		const h = s.length >> 1;
+		const ms = s.length % 2 ? s[h] : (s[h - 1] + s[h]) / 2;
+		const rest = cached.tops.filter((t) => !caching(t.top)).map((t) => t.top);
+		measured = {
+			after: saving_of(rest, {
+				wait: wait_cap,
+				cpu: cpu_cap
+			}, ms).after,
+			ms,
+			renders: s.length
+		};
+	}
+	const answers_after = measured?.after ?? cached?.after;
+	if (!code.parts.length && !cached && !cache) return void 0;
+	return {
+		now_ms: r1(now),
+		...wait_cap !== void 0 || cpu_cap !== void 0 ? { caps: {
+			...wait_cap !== void 0 ? { wait: r1(wait_cap) } : {},
+			...cpu_cap !== void 0 ? { cpu: r1(cpu_cap) } : {}
+		} } : {},
+		after_ms: r1(code.after),
+		cpu_ms: r1(code.cpu),
+		...inputs.cpu_main && inputs.cpu_main > 0 ? {
+			cpu_now_ms: r1(inputs.cpu_main),
+			cpu_after_ms: r1(Math.max(inputs.cpu_main * .03, inputs.cpu_main - code.cpu - code.del_cpu))
+		} : {},
+		wait_ms: r1(code.wait),
+		delete_ms: r1(code.del),
+		parts: code.parts,
+		...cached && answers_after !== void 0 && answers_after < code.after - .5 ? { answers: {
+			after_ms: r1(answers_after),
+			wait_ms: r1(cached.wait),
+			parts: cached.parts.filter((p) => CACHING.has(p.kind)),
+			...cached.clamped && !measured ? { clamped: true } : {},
+			...measured ? { measured: {
+				ms: r1(measured.ms),
+				renders: measured.renders,
+				model_ms: r1(cached.after)
+			} } : {}
+		} } : {},
+		...cache ? { cache: true } : {},
+		...code.clamped ? { clamped: true } : {}
+	};
+}
+/** fixes that keep an ANSWER for later renders: worth it only where the answer may be a little
+*  stale, so a decision about freshness, not a code fix — told apart from the rest */
+const CACHING = /* @__PURE__ */ new Set(["same-answer", "almost-same-answer"]);
+export { forecast_of, saving_of };

package/dist/profiler/frames.d.ts

@@ -0,0 +1,11 @@
+/** Grab the structured call-sites WITHOUT triggering Node's stack-string formatter
+ *  (`defaultPrepareStackTrace`). Reading `new Error().stack` on every I/O call formatted the
+ *  whole stack and showed up as node-core CPU in the profile — the profiler measuring itself. */
+export declare function call_sites(below: (...a: never[]) => unknown): NodeJS.CallSite[];
+/** A call site's file: its script's name, or the `//# sourceURL` of code made from a string — how
+ *  the dev server's module runner evaluates every server module (`new AsyncFunction(code)`), where
+ *  `getFileName()` is empty and every frame looked like no file at all */
+export declare function file_of(site: NodeJS.CallSite): string | undefined;
+/** Call at module load from any profiler module: its runtime file name joins the skip set. */
+export declare function register_profiler_file(): void;
+export declare function is_profiler_file(file: string): boolean;

package/dist/profiler/frames.js

@@ -0,0 +1,42 @@
+// src/profiler/frames.ts
+/**
+* The profiler's OWN frames, so a caller lookup skips them whatever the bundler named the file.
+*
+* Bundlers rename our source (net.ts → chunks/net2.js, or straight into the app's chunk when the
+* package is a workspace link), so a path substring like '/profiler/' won't match at runtime.
+* Each profiler module calls `register_profiler_file()` at load; it reads the CALLER's file from
+* a structured stack trace — the same format the caller lookup later compares against — so those
+* frames are skipped by identity. Dependency-free and V8-guarded: `span.ts` (universal) registers
+* itself too, and on an engine without `captureStackTrace` it simply does nothing.
+*/
+const profiler_files = /* @__PURE__ */ new Set();
+/** Grab the structured call-sites WITHOUT triggering Node's stack-string formatter
+*  (`defaultPrepareStackTrace`). Reading `new Error().stack` on every I/O call formatted the
+*  whole stack and showed up as node-core CPU in the profile — the profiler measuring itself. */
+function call_sites(below) {
+	const E = Error;
+	if (typeof E.captureStackTrace !== "function") return [];
+	const orig = E.prepareStackTrace;
+	E.prepareStackTrace = (_e, sites) => sites;
+	const holder = {};
+	E.captureStackTrace(holder, below);
+	const sites = holder.stack;
+	E.prepareStackTrace = orig;
+	return Array.isArray(sites) ? sites : [];
+}
+/** A call site's file: its script's name, or the `//# sourceURL` of code made from a string — how
+*  the dev server's module runner evaluates every server module (`new AsyncFunction(code)`), where
+*  `getFileName()` is empty and every frame looked like no file at all */
+function file_of(site) {
+	return site.getFileName() ?? site.getScriptNameOrSourceURL?.() ?? void 0;
+}
+/** Call at module load from any profiler module: its runtime file name joins the skip set. */
+function register_profiler_file() {
+	const s = call_sites(register_profiler_file)[0];
+	const f = s ? file_of(s) : void 0;
+	if (f) profiler_files.add(f);
+}
+function is_profiler_file(file) {
+	return profiler_files.has(file) || file.includes("/profiler/");
+}
+export { call_sites, file_of, is_profiler_file, register_profiler_file };

package/dist/profiler/gc.d.ts

@@ -0,0 +1,144 @@
+import { FrameCategory, HeapNode } from "./analyze.js";
+export interface GcEvent {
+  /** ms on the profile's clock (from the window's start) */
+  t: number;
+  ms: number;
+  kind: "minor" | "major" | "incremental" | "weak" | "other";
+  /** Node's GC flags (forced, all available garbage, …) */
+  flags: number;
+}
+/** one sampled allocation site: a stack, keyed by a hash of the frames above it */
+export interface AllocSite {
+  key: string;
+  name: string;
+  url: string;
+  line: number;
+  category: FrameCategory;
+  /** the nearest component on the stack, when one is there */
+  component: string | null;
+  /** the nearest app frame above, formatted: `toProductVM (lib/mappers.ts:11)` */
+  caller?: string;
+  /** …and its raw parts, so a source map can rename the file and line afterwards */
+  caller_name?: string;
+  caller_url?: string;
+  caller_line?: number;
+  /** THE APP LINE this allocation is charged to, resolved to source: the site itself when it is
+   *  the app's code, else the nearest app caller — so a builtin (`replace`, `structuredClone`)
+   *  lands on the line of your code that called it. Set once the source map has run. */
+  at?: {
+    path: string;
+    line: number;
+  };
+}
+export interface AllocSlice {
+  t0: number;
+  t1: number;
+  /** bytes allocated in the slice, per site key (only sites that allocated) */
+  bytes: Record<string, number>;
+}
+export interface GcPause {
+  t: number;
+  /** the pause AS THE APP WOULD HAVE PAID IT: the measured length minus the profiler's own share
+   *  of the allocations that filled the heap before it */
+  ms: number;
+  /** the length the observer measured, before that share was taken out */
+  ms_measured: number;
+  kind: GcEvent["kind"];
+  forced: boolean;
+  /** ms since the pause this one is charged from */
+  since_ms: number;
+  /** bytes allocated in that stretch — measured when the window was read in slices, else the
+   *  window's average rate over the stretch (`estimated`) */
+  allocated: number;
+  estimated?: boolean;
+  why: string;
+  /** the allocators of that stretch (only when the window was read in slices) */
+  top: {
+    key: string;
+    name: string;
+    component: string | null;
+    bytes: number;
+    share: number;
+  }[];
+  /** what the CPU was running when the pause fell (the timeline's segment at that moment) */
+  running?: {
+    label: string;
+    category: string;
+    file?: string;
+  };
+}
+export interface GcMaker {
+  key: string;
+  name: string;
+  url: string;
+  line: number;
+  category: FrameCategory;
+  component: string | null;
+  caller?: string;
+  /** the app line it is charged to (see `AllocSite.at`) */
+  at?: {
+    path: string;
+    line: number;
+  };
+  allocated: number;
+  /** share of everything allocated in the window */
+  share: number;
+  /** pause time attributed to it, by its share of each pause's cause */
+  gc_ms: number;
+  /** pauses where it was among the top three causes */
+  pauses: number;
+}
+export interface GcAttribution {
+  summary: {
+    count: number;
+    /** pause time as the app would have paid it (the profiler's share taken out) */
+    total_ms: number;
+    max_ms: number;
+    /** what the observer measured, and the part of it that was the profiler's own garbage */
+    measured_ms: number;
+    overhead_ms: number;
+    minor: number;
+    major: number;
+    incremental: number;
+    weak: number;
+    allocated_mb: number;
+    alloc_rate_mb_s: number;
+    /** heap still held at the end against the start, when the host measured it */
+    retained_mb?: number;
+    /** slices read (the attribution's resolution) and their typical length */
+    slices: number;
+    slice_ms: number;
+  };
+  pauses: GcPause[];
+  makers: GcMaker[];
+  /** components by pause time attributed to their allocations */
+  components: {
+    name: string;
+    allocated: number;
+    gc_ms: number;
+  }[];
+  /** the profiled request's window starts this many ms into the capture (pause times are on the
+   *  capture's clock; the timeline's is the window's) */
+  window_offset_ms?: number;
+}
+export declare function gc_kind(kind: number): GcEvent["kind"];
+/** The sampling profile flattened to allocation sites: every node with self bytes, keyed by the
+ *  hash of its stack, with its cumulative self bytes. `dict` collects what each key is. */
+export declare function heap_sites(head: HeapNode, dict: Record<string, AllocSite>): Map<string, number>;
+/** What was allocated between two reads: per site, the growth of its cumulative bytes. */
+export declare function slice_delta(prev: Map<string, number>, cur: Map<string, number>): Record<string, number>;
+export declare function attribute_gc(input: {
+  slices: AllocSlice[];
+  events: GcEvent[];
+  dict: Record<string, AllocSite>;
+  window_ms: number;
+  retained_mb?: number;
+  /** the CPU timeline's segments on the same clock as the events: what was running at each pause */
+  running?: {
+    t0: number;
+    t1: number;
+    label: string;
+    category: string;
+    file?: string;
+  }[];
+}): GcAttribution;