@ogygia/devtools 0.0.0-stage → 0.11.0

package/dist/profiler/gc.js

@@ -0,0 +1,271 @@
+import { categorize, clean_url, component_name_from_file, strip_bundler_suffix, with_script_url } from "./analyze.js";
+// src/profiler/gc.ts
+/**
+* WHO CAUSED THE GC — each pause joined to the allocations that filled the heap before it.
+*
+* V8's sampling heap profiler, asked to include objects already collected, counts every sampled
+* allocation whether it survived or not — the allocation stream that drives the collector. The
+* recorder reads that profile every few tens of milliseconds while the window runs; the
+* difference between two reads is what was allocated in between, by stack. A minor GC (a
+* scavenge) fires when the young space fills, so the allocations since the previous pause caused
+* it; a major GC fires when the old space grows, so the allocations since the previous major
+* pause (their survivors were promoted) caused that one. Each pause gets its top allocators, each
+* allocator gets the pause time it is responsible for, and the report can say "this 40 ms of GC
+* is toProductVM's structuredClone in ProductCard", which no table of allocators can. Pure.
+*/
+const GC_MINOR = 1;
+const GC_MAJOR = 4;
+const GC_INCREMENTAL = 8;
+const GC_WEAKCB = 16;
+const GC_FLAGS_FORCED = 4;
+function gc_kind(kind) {
+	if (kind & GC_MAJOR) return "major";
+	if (kind & GC_MINOR) return "minor";
+	if (kind & GC_INCREMENTAL) return "incremental";
+	if (kind & GC_WEAKCB) return "weak";
+	return "other";
+}
+/** FNV-1a over a string, hex — a short stable key for a stack path */
+function fnv(s, seed = 2166136261) {
+	let h = seed;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 16777619) >>> 0;
+	}
+	return h;
+}
+/** 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. */
+function heap_sites(head, dict) {
+	const out = /* @__PURE__ */ new Map();
+	const stack = [];
+	const short = (url) => clean_url(url).split("/").slice(-2).join("/");
+	const visit = (node, parent_hash, app_above) => {
+		const f = with_script_url(node.callFrame);
+		const cat = categorize(f);
+		let name = f.functionName || "(anonymous)";
+		let is_comp = cat.category === "component";
+		if (is_comp) name = strip_bundler_suffix(name);
+		else if ((!f.functionName || f.functionName === "(anonymous)") && cat.category !== "dependency") {
+			const derived = component_name_from_file(clean_url(f.url));
+			if (derived) {
+				name = derived;
+				is_comp = true;
+			}
+		}
+		const h = fnv(`${name}|${f.url}|${f.lineNumber}`, parent_hash);
+		const key = h.toString(16).padStart(8, "0");
+		if (is_comp) stack.push(name);
+		const category = is_comp ? "component" : cat.category;
+		if (node.selfSize > 0) {
+			out.set(key, (out.get(key) ?? 0) + node.selfSize);
+			if (!dict[key]) dict[key] = {
+				key,
+				name,
+				url: f.url,
+				line: f.lineNumber + 1,
+				category,
+				component: stack[stack.length - 1] ?? null,
+				...app_above ? {
+					caller: `${app_above.name} (${short(app_above.url)}:${app_above.line})`,
+					caller_name: app_above.name,
+					caller_url: app_above.url,
+					caller_line: app_above.line
+				} : {}
+			};
+		}
+		const own = (category === "app" || category === "component" || category === "dependency") && f.url ? {
+			name,
+			url: f.url,
+			line: f.lineNumber + 1
+		} : app_above;
+		for (const ch of node.children ?? []) visit(ch, h, own);
+		if (is_comp) stack.pop();
+	};
+	visit(head, 2166136261, void 0);
+	return out;
+}
+/** What was allocated between two reads: per site, the growth of its cumulative bytes. */
+function slice_delta(prev, cur) {
+	const out = {};
+	for (const [k, v] of cur) {
+		const d = v - (prev.get(k) ?? 0);
+		if (d > 0) out[k] = d;
+	}
+	return out;
+}
+const r1 = (n) => Math.round(n * 10) / 10;
+const r2 = (n) => Math.round(n * 100) / 100;
+const mb = (b) => r1(b / 1048576);
+function attribute_gc(input) {
+	const { slices, dict } = input;
+	const events = [...input.events].sort((a, b) => a.t - b.t);
+	const single = slices.length === 1;
+	const running_at = (t) => {
+		const segs = input.running ?? [];
+		let best;
+		for (const s of segs) {
+			if (s.category === "gc" || s.category === "idle" || s.category === "profiler") continue;
+			if (s.t0 <= t && t <= s.t1) return s;
+			if (s.t1 <= t && (!best || s.t1 > best.t1)) best = s;
+		}
+		return best && t - best.t1 <= 50 ? best : void 0;
+	};
+	const ours = (k) => {
+		const c = dict[k]?.category;
+		return c !== "v8" && c !== "gc" && c !== "profiler";
+	};
+	const profilers = (k) => dict[k]?.category === "profiler";
+	const ident_of = (k) => {
+		const d = dict[k];
+		return d ? `${d.name}|${d.url}|${d.line}|${d.caller ?? ""}|${d.component ?? ""}` : k;
+	};
+	const first_key = {};
+	const between = (from, to) => {
+		const acc = {};
+		let profiler_bytes = 0;
+		for (const s of slices) {
+			const len = s.t1 - s.t0;
+			if (len <= 0 || s.t1 <= from || s.t0 > to) continue;
+			const w = Math.max(0, Math.min(1, (Math.min(s.t1, to) - Math.max(s.t0, from)) / len));
+			if (!w) continue;
+			for (const [k, b] of Object.entries(s.bytes)) {
+				if (profilers(k)) {
+					profiler_bytes += b * w;
+					continue;
+				}
+				if (!ours(k)) continue;
+				const id = ident_of(k);
+				first_key[id] ??= k;
+				acc[id] = (acc[id] ?? 0) + b * w;
+			}
+		}
+		return {
+			app: acc,
+			profiler_bytes
+		};
+	};
+	const total_by_key = {};
+	for (const s of slices) for (const [k, b] of Object.entries(s.bytes)) {
+		if (!ours(k)) continue;
+		const id = ident_of(k);
+		first_key[id] ??= k;
+		total_by_key[id] = (total_by_key[id] ?? 0) + b;
+	}
+	const total_bytes = Object.values(total_by_key).reduce((a, b) => a + b, 0);
+	const gc_ms_by_key = {};
+	const top3_by_key = {};
+	const pauses = [];
+	let last_any = 0;
+	let last_major = 0;
+	let measured_total = 0;
+	let overhead_total = 0;
+	for (const e of events) {
+		const from = e.kind === "major" ? last_major : last_any;
+		const { app: cause, profiler_bytes } = between(from, e.t);
+		const allocated = Object.values(cause).reduce((a, b) => a + b, 0);
+		const overhead_share = allocated + profiler_bytes > 0 ? profiler_bytes / (allocated + profiler_bytes) : 0;
+		const ms_app = e.ms * (1 - overhead_share);
+		measured_total += e.ms;
+		overhead_total += e.ms - ms_app;
+		const forced = (e.flags & GC_FLAGS_FORCED) !== 0;
+		const top = single ? [] : Object.entries(cause).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([id, bytes]) => {
+			const d = dict[first_key[id]];
+			return {
+				key: first_key[id],
+				name: d?.name ?? id,
+				component: d?.component ?? null,
+				bytes: Math.round(bytes),
+				share: allocated ? r2(bytes / allocated) : 0
+			};
+		});
+		for (const [key, bytes] of Object.entries(cause)) gc_ms_by_key[key] = (gc_ms_by_key[key] ?? 0) + (allocated ? bytes / allocated * ms_app : 0);
+		for (const t of top.slice(0, 3)) top3_by_key[ident_of(t.key)] = (top3_by_key[ident_of(t.key)] ?? 0) + 1;
+		const since_ms = r1(e.t - from);
+		const run = running_at(e.t);
+		const about = single ? "≈" : "";
+		let why;
+		if (forced) why = "forced (something asked for a collection: the inspector, a gc() call, a low-memory signal)";
+		else if (!allocated) why = e.kind === "major" ? "the old space was full; nothing sampled was allocated since the last major pause (the pressure came from before the window)" : "nothing sampled was allocated since the last pause (an allocation the sampler missed, or pressure from before the window)";
+		else if (e.kind === "minor") why = `the young space filled: ${about}${mb(allocated)} MB allocated in the ${since_ms} ms since the last pause`;
+		else if (e.kind === "major") why = `the old space grew: ${about}${mb(allocated)} MB allocated since the last major pause, and what survived the minor ones was promoted into it`;
+		else if (e.kind === "incremental") why = `an incremental marking step of a major collection (${about}${mb(allocated)} MB allocated since the last pause)`;
+		else why = `a weak-callback pass (${about}${mb(allocated)} MB allocated since the last pause)`;
+		pauses.push({
+			t: r1(e.t),
+			ms: r2(ms_app),
+			ms_measured: r2(e.ms),
+			kind: e.kind,
+			forced,
+			since_ms,
+			allocated: Math.round(allocated),
+			...single ? { estimated: true } : {},
+			why,
+			top,
+			...run ? { running: {
+				label: run.label,
+				category: run.category,
+				...run.file ? { file: run.file } : {}
+			} } : {}
+		});
+		last_any = e.t;
+		if (e.kind === "major") last_major = e.t;
+	}
+	const makers = Object.entries(total_by_key).map(([id, allocated]) => {
+		const key = first_key[id];
+		const d = dict[key];
+		return {
+			key,
+			name: d?.name ?? key,
+			url: d?.url ?? "",
+			line: d?.line ?? 0,
+			category: d?.category ?? "app",
+			component: d?.component ?? null,
+			...d?.caller ? { caller: d.caller } : {},
+			...d?.at ? { at: d.at } : {},
+			allocated,
+			share: total_bytes ? r2(allocated / total_bytes) : 0,
+			gc_ms: r2(gc_ms_by_key[id] ?? 0),
+			pauses: top3_by_key[id] ?? 0
+		};
+	}).filter((m) => m.category !== "gc" && m.category !== "v8" && m.category !== "profiler").sort((a, b) => b.gc_ms - a.gc_ms || b.allocated - a.allocated).slice(0, 60);
+	const comp = /* @__PURE__ */ new Map();
+	for (const [id, allocated] of Object.entries(total_by_key)) {
+		const name = dict[first_key[id]]?.component;
+		if (!name) continue;
+		const c = comp.get(name) ?? {
+			allocated: 0,
+			gc_ms: 0
+		};
+		c.allocated += allocated;
+		c.gc_ms += gc_ms_by_key[id] ?? 0;
+		comp.set(name, c);
+	}
+	const slice_ms = slices.length ? r1(slices.reduce((a, s) => a + (s.t1 - s.t0), 0) / slices.length) : 0;
+	return {
+		summary: {
+			count: events.length,
+			total_ms: r2(measured_total - overhead_total),
+			max_ms: r2(Math.max(0, ...pauses.map((p) => p.ms))),
+			measured_ms: r2(measured_total),
+			overhead_ms: r2(overhead_total),
+			minor: events.filter((e) => e.kind === "minor").length,
+			major: events.filter((e) => e.kind === "major").length,
+			incremental: events.filter((e) => e.kind === "incremental").length,
+			weak: events.filter((e) => e.kind === "weak").length,
+			allocated_mb: mb(total_bytes),
+			alloc_rate_mb_s: input.window_ms > 0 ? r1(total_bytes / 1048576 / (input.window_ms / 1e3)) : 0,
+			...input.retained_mb !== void 0 ? { retained_mb: input.retained_mb } : {},
+			slices: slices.length,
+			slice_ms
+		},
+		pauses,
+		makers,
+		components: [...comp.entries()].map(([name, c]) => ({
+			name,
+			allocated: c.allocated,
+			gc_ms: r2(c.gc_ms)
+		})).sort((a, b) => b.gc_ms - a.gc_ms || b.allocated - a.allocated)
+	};
+}
+export { attribute_gc, gc_kind, heap_sites, slice_delta };

package/dist/profiler/hole-slots.d.ts

@@ -0,0 +1,31 @@
+import { RequestEntry } from "./report.js";
+export interface HoleSlotRow {
+  id: string;
+  /** the component and a props preview, from a page that minted it (else the id) */
+  name: string;
+  requests: number;
+  /** served from the render cache (no render, no slot) */
+  hits: number;
+  /** answered 500 (the render threw or timed out): no render time */
+  failed: number;
+  /** mean render per rendered request (its time in the slot), ms */
+  render_ms: number;
+  /** mean and worst wait for a slot per rendered request, ms */
+  queue_ms: number;
+  queue_max_ms: number;
+  /** its part of all the slot time spent (0–1): who held the slots */
+  slot_share: number;
+}
+export interface HoleSlots {
+  rows: HoleSlotRow[];
+  /** the slots per process */
+  slots: number;
+  /** rendered hole requests, and how many waited 50 ms or more for a slot */
+  rendered: number;
+  queued: number;
+  /** the mean wait of those that waited, ms */
+  queued_mean_ms: number;
+  /** one line for the dashboard, when holes waited; null when none did */
+  summary: string | null;
+}
+export declare function hole_slots(ring: readonly RequestEntry[]): HoleSlots | null;

package/dist/profiler/hole-slots.js

@@ -0,0 +1,90 @@
+import { REGION_RENDER_CONCURRENCY } from "@ogygia/core/internal/instruments";
+// src/profiler/hole-slots.ts
+/**
+* HOLE RENDER SLOTS, across the server. A server process renders a few holes at a time
+* (`REGION_RENDER_CONCURRENCY`), and a render holds its slot through its awaits: a hole waiting
+* on slow data keeps the next hole — any visitor's — queued. The endpoint records each hole
+* request's wait for a slot (`HoleRequestStats.queue_ms`); this reads the request log for which
+* holes waited, and which held the slots while they did.
+*
+* On a host that runs one request per instance (AWS Lambda) nothing ever queues: the table still
+* shows each hole's render and cache, and the summary stays silent.
+*/
+const QUEUED_MS = 50;
+const fmt = (ms) => ms >= 1e3 ? `${(ms / 1e3).toFixed(1)} s` : `${Math.round(ms)} ms`;
+function hole_slots(ring) {
+	const names = /* @__PURE__ */ new Map();
+	const props = /* @__PURE__ */ new Map();
+	for (const e of ring) for (const h of e.og?.hole_rows ?? []) {
+		if (h.name && !names.has(h.id)) names.set(h.id, h.name);
+		const set = props.get(h.id) ?? props.set(h.id, /* @__PURE__ */ new Set()).get(h.id);
+		if (h.props) set.add(h.count > 1 ? `${h.props}×${h.count}` : h.props);
+	}
+	const by = /* @__PURE__ */ new Map();
+	let queued = 0;
+	let queued_sum = 0;
+	for (const e of ring) {
+		const h = e.hole;
+		if (!h) continue;
+		const s = by.get(h.id) ?? {
+			requests: 0,
+			hits: 0,
+			failed: 0,
+			rendered: 0,
+			render: 0,
+			queue: 0,
+			queue_max: 0
+		};
+		s.requests++;
+		s.name ??= h.name;
+		if (e.status >= 500) s.failed++;
+		else if (h.cache === "hit") s.hits++;
+		else {
+			const q = h.queue_ms ?? 0;
+			s.rendered++;
+			s.queue += q;
+			s.queue_max = Math.max(s.queue_max, q);
+			s.render += Math.max(0, e.ms - q);
+			if (q >= QUEUED_MS) {
+				queued++;
+				queued_sum += q;
+			}
+		}
+		by.set(h.id, s);
+	}
+	if (!by.size) return null;
+	const slot_total = [...by.values()].reduce((a, s) => a + s.render, 0) || 1;
+	const rows = [...by.entries()].map(([id, s]) => {
+		const name = s.name ?? names.get(id) ?? id;
+		const copies = props.get(id);
+		const one = copies?.size === 1 ? [...copies][0] : void 0;
+		return {
+			id,
+			name: one && !one.includes("×") ? `${name} ${one}` : name,
+			requests: s.requests,
+			hits: s.hits,
+			failed: s.failed,
+			render_ms: s.rendered ? s.render / s.rendered : 0,
+			queue_ms: s.rendered ? s.queue / s.rendered : 0,
+			queue_max_ms: s.queue_max,
+			slot_share: s.render / slot_total
+		};
+	}).sort((a, b) => b.slot_share - a.slot_share);
+	const rendered = rows.reduce((a, r) => a + r.requests - r.hits - r.failed, 0);
+	const queued_mean_ms = queued ? queued_sum / queued : 0;
+	let summary = null;
+	if (queued) {
+		const holders = rows.filter((r) => r.slot_share >= .2).slice(0, 3);
+		const held = holders.length ? ` The slots were held mostly by ${holders.map((r) => `${r.name} (${Math.round(r.slot_share * 100)}% of slot time, ${fmt(r.render_ms)} a render)`).join(", ")}.` : "";
+		summary = `${queued} of ${rendered} hole render${rendered === 1 ? "" : "s"} waited for a render slot, ${fmt(queued_mean_ms)} on average (the worst ${fmt(Math.max(...rows.map((r) => r.queue_max_ms)))}).` + held + ` A server process renders ${REGION_RENDER_CONCURRENCY} holes at a time, and each holds its slot while it awaits its data: make the slow ones answer sooner (a maxAge, faster data).`;
+	}
+	return {
+		rows,
+		slots: REGION_RENDER_CONCURRENCY,
+		rendered,
+		queued,
+		queued_mean_ms,
+		summary
+	};
+}
+export { hole_slots };

package/dist/profiler/index.d.ts

@@ -0,0 +1,288 @@
+import { ProfilerStore } from "./storage/index.js";
+import { Analysis, CpuProfile, FrameCategory, HeapAllocator } from "./analyze.js";
+import { NetCall } from "./net.js";
+import { IoOp } from "./async-io.js";
+import { ClientIslandStat, ClientMarkStat, IslandHazard as IslandHazard$1, MemSample, PageVitals, ReportMeta, RequestEntry } from "./report.js";
+import { Visit } from "./visit.js";
+import { ClientWindows, InteractionCpu } from "./client-windows.js";
+import { ByteStrip } from "./byte-strip.js";
+import { River } from "./river.js";
+import { GcAttribution } from "./gc.js";
+import { Retained } from "./insights.js";
+import { AllocTimeline } from "./alloc.js";
+import { Contention } from "./contention.js";
+import { Lineage } from "./lineage.js";
+import { LedgerLine } from "./ledger.js";
+import { DrillNode } from "./drill.js";
+import { Forecast } from "./forecast.js";
+import { HeapGrowth, Pattern } from "./patterns.js";
+import { SpanRecord } from "./span.js";
+import { PageAssets } from "@ogygia/core/insights";
+import { Handle } from "@sveltejs/kit";
+export interface ProfilerOptions {
+  /**
+   * Auth secret. Defaults to the OGYGIA_PROFILER_SECRET env var. Required outside
+   * dev — with no secret in production the profiler UI is disabled (the
+   * always-on request log still collects, invisibly).
+   */
+  secret?: string;
+  /** Base path for the UI. Default '/__profiler'. */
+  path?: string;
+  /** Sampling interval in microseconds for recordings. Default 500. */
+  sampleInterval?: number;
+  /** How many finished profiles to keep in memory (each gzipped). Default 6. */
+  maxReports?: number;
+  /** How many requests the rolling log keeps. Default 500. */
+  recentRequests?: number;
+  /**
+   * Patch fetch/http to attribute outbound calls. Default true. In production the
+   * per-request AsyncLocalStorage that does the attributing exists only while a profile
+   * is being recorded (idle requests pay nothing); in dev it is always on. Set false to
+   * skip the global fetch/http patch entirely: wall timing only, never any network view.
+   */
+  network?: boolean;
+  /**
+   * Add Server-Timing headers to every response. These expose internal render
+   * and network timings to every client, so the default is ON in dev and OFF
+   * in production — set true to force it on.
+   */
+  serverTiming?: boolean;
+  /** Take a heap allocation profile during recordings. Default true. */
+  heap?: boolean;
+  /** Master switch. Default true. */
+  enabled?: boolean;
+  /**
+   * DEMAND-ONLY. The profiler module (node:inspector, crypto, its UI-rendering path) is not imported,
+   * parsed or initialised until a request actually hits the profiler path — so until you open the
+   * dashboard the app pays EXACTLY what an app with no profiler pays: no cold-start import, no
+   * always-on request log, no per-request wrap. The trade is no history: the profiler starts
+   * collecting from the first visit onward, not before. Recommended on serverless (Amplify / Lambda),
+   * where every cold start would otherwise pay the profiler's import on its TTFB. Default false (the
+   * profiler mounts on the first request and its always-on log collects from boot). Off by default so
+   * nothing changes for existing setups.
+   */
+  onDemand?: boolean;
+  /**
+   * CATCH THE SLOW ONE. Keep a coarse sampler running in rolling windows and keep a report only
+   * when a request in the window took longer than `over` ms — the p99 request you cannot
+   * reproduce. Built to stay cheap: a 10 ms sampling interval, no per-request context, no stack
+   * capture, no heap sampling; the request is matched to the window by time. Off by default; off
+   * on serverless hosts (an instance dies before it catches anything). Stops after `keep` reports.
+   */
+  trap?: {
+    over: number;
+    interval?: number;
+    window?: number;
+    keep?: number;
+    /** request headers to KEEP with a caught request so "profile it again" can replay it with the
+     *  same inputs (`['accept-language', 'x-tenant']`). Never cookies unless named here. */
+    replay?: string[];
+  };
+  /**
+   * A CPU PROFILE IN THE BROWSER for the profiler's own user: their documents get the
+   * `Document-Policy: js-profiling` header, the runtime samples the main thread while the page
+   * hydrates (Chromium's JS Self-Profiling API) and posts the trace through the beacon; the report
+   * shows it as components, functions and a flame graph for hydration. Default true; a visitor is
+   * never sampled (no tag, no policy, no profiler).
+   */
+  clientCpu?: boolean;
+  /**
+   * THE SINK — for a host whose instances live seconds (Amplify, Lambda). Each instance posts what
+   * it saw as NDJSON to this URL before it dies: one small row per request, one summary per
+   * always-on sampler window, a caught request's dump. `key` goes as a bearer token (default: the
+   * profiler secret). A long-lived host posts every `every` ms (default 10 s); a serverless one
+   * posts after each request. The site view (`<base>/site`) reads the rows back from any URL you
+   * serve them from: the request cloud and the layer cake of the whole site, over days.
+   */
+  sink?: {
+    url: string;
+    key?: string;
+    every?: number;
+  };
+  /**
+   * ALWAYS-ON SAMPLING. Every `every` seconds take one `window` ms coarse sample (10 ms interval)
+   * and fold it into a rolling "hot functions over the last hour" table on the dashboard. The
+   * accuracy comes from volume, not from one capture. Default off; off on serverless.
+   */
+  sample?: {
+    every?: number;
+    window?: number;
+    interval?: number;
+  };
+  /**
+   * WHERE REPORTS LIVE. Default: this instance's memory (lost on restart; each browser keeps its
+   * own copies). Not a `devtools({ profiler })` option: a store is a live object the build-time
+   * options cannot carry, so the app sets it at runtime with `setProfilerStore(store)` from
+   * `@ogygia/devtools/profiler/storage`, in hooks.server.ts, and the server half passes it in here
+   * when the profiler mounts. A store is `sqliteStore(...)`, `redisStore(...)` or `postgresStore(...)`
+   * from `@ogygia/devtools/profiler/storage/{sqlite,redis,postgres}`, or your own; every finished
+   * report is written there and read back from there, so it survives the instance that made it and
+   * a whole team shares one list. The store is dual-written: memory stays the hot cache, the store
+   * the source of truth.
+   */
+  store?: ProfilerStore;
+}
+/** The dashboard's always-on view. */
+export interface SampledSummary {
+  every_s: number;
+  window_ms: number;
+  windows: number;
+  since: number | null;
+  sampled_ms: number;
+  busy_ms: number;
+  functions: {
+    key: string;
+    name: string;
+    url: string;
+    line: number;
+    category: FrameCategory;
+    pkg?: string;
+    self_ms: number;
+    windows: number;
+  }[];
+}
+/** The dashboard's trap view. */
+export interface TrapStatus {
+  over: number;
+  window_ms: number;
+  caught: number;
+  keep: number;
+  armed: boolean;
+}
+interface UserTiming {
+  name: string;
+  count: number;
+  total_ms: number;
+  max_ms: number;
+}
+interface GcSummary {
+  count: number;
+  total_ms: number;
+  max_ms: number;
+}
+export interface StoredReport {
+  meta: ReportMeta;
+  analysis: Analysis;
+  heap: HeapAllocator[] | null;
+  /** bytes per component from the same heap sample */
+  heap_components?: {
+    name: string;
+    bytes: number;
+  }[] | null;
+  net: NetCall[];
+  spans?: SpanRecord[];
+  mem: MemSample[];
+  measures: UserTiming[];
+  gc: GcSummary | null;
+  io: IoOp[];
+  call_counts: Record<string, number>;
+  /** the raw .cpuprofile, gzipped — a 10s profile is multiple MB of JSON, so
+   * we keep it compressed (~10×) and inflate only on download */
+  raw: Buffer | string;
+  /** bytes per island module / preload href (page mode on a built app) */
+  weights?: Record<string, number>;
+  /** what is inside each of those chunks (the build's handoff), for the same hrefs */
+  contents?: Record<string, string[]>;
+  heavy?: Record<string, {
+    total: number;
+    top: {
+      name: string;
+      bytes: number;
+    }[];
+  }>;
+  barrels?: Record<string, {
+    name: string;
+    fanout: number;
+  }[]>;
+  /** each island entry's lines that draw differently in the browser (its own `.svelte` sources) */
+  hazards?: Record<string, IslandHazard$1[]>;
+  /** browser hydration timings carried by an uploaded dump (a live report joins the ring instead) */
+  client?: ClientIslandStat[];
+  /** the page's web vitals carried by an uploaded dump */
+  vitals?: PageVitals;
+  /** the app's browser marks carried by an uploaded dump */
+  client_marks?: ClientMarkStat[];
+  /** a caught request's inputs, so it can be profiled again in full */
+  replay?: {
+    path: string;
+    headers: Record<string, string>;
+  };
+  /** the browser's CPU profile of hydration carried by an uploaded dump */
+  client_cpu?: {
+    analysis: Analysis;
+    at: number;
+    sample_ms: number;
+    windows?: ClientWindows;
+  };
+  /** the slowest interaction's CPU (its wait, its handlers) carried by an uploaded dump */
+  interaction_cpu?: InteractionCpu;
+  /** the browser's picture of a visit to this page (the beacon), the latest at report time */
+  visit?: Visit;
+  /** the rendered document as a byte strip (page mode: the last run's body) */
+  strip?: ByteStrip;
+  /** every file the document loads at start, weighed (page mode on a build) */
+  assets?: PageAssets;
+  /** why the page was not weighed (a dev server) */
+  assets_missing?: string;
+  /** the data river (page mode): calls → loads → keys → islands */
+  river?: River;
+  /** who caused the GC: each pause joined to the allocations before it (gc.ts) */
+  gc_attr?: GcAttribution;
+  /** promises created in the window (count, sampled creators) */
+  promises?: {
+    count: number;
+    top: {
+      caller: string;
+      share: number;
+    }[];
+  };
+  /** what one more render left alive after a full collection, by allocation site */
+  retained?: Retained;
+  /** when the heap grew and what ran then (alloc.ts) */
+  alloc?: AllocTimeline;
+  /** the other requests the instance answered while the render ran (contention.ts) */
+  contention?: Contention;
+  /** which component reads which page.data key, from the sources (lineage.ts) */
+  lineage?: Lineage;
+  /** the app lines that cost the most, every cost joined per line (ledger.ts) */
+  ledger?: LedgerLine[];
+  /** the known slow shapes found on those lines, grouped (patterns.ts) */
+  patterns?: Pattern[];
+  /** one render's time as a tree that adds up: phase → owner / call → line (drill.ts) */
+  drill?: DrillNode;
+  /** one render after every fix named, estimated without counting a saving twice (forecast.ts) */
+  forecast?: Forecast;
+  /** a few more renders with a full collection after each: does the heap keep growing? */
+  growth?: HeapGrowth;
+}
+/**
+ * Chromium's JS Self-Profiling trace (`Profiler.stop()`) as a V8 cpuprofile: a stack is a chain of
+ * frames, so every distinct stack becomes one node whose parent is its parent stack; the samples
+ * are timestamps (ms) → time deltas (µs); a sample with no stack is idle. Bounded (samples,
+ * stacks); `null` for anything not shaped like a trace. Exported for the tests.
+ */
+export declare function self_profile_to_cpuprofile(trace: unknown): CpuProfile | null;
+/**
+ * Build a profiler handle. INTERNAL — the profiler is configured in vite.config.ts
+ * (`ogygia({ profiler: true })`) and `ogygia.handle()` constructs + mounts this itself.
+ * Kept as a named export only so the handle's lazy import can reach it; it is not a
+ * public entry point.
+ *
+ * See the class doc and README for what it captures. Visit `<path>` (default
+ * /__profiler) — in prod, log in (or send the x-profiler-key header).
+ */
+export declare function profiler(options?: ProfilerOptions): Handle;
+/** `report` with only the top-level keys in `fields` (comma-separated) and its identity; whole when unset. */
+export declare function pick_fields(report: Record<string, unknown>, fields: string | null): Record<string, unknown>;
+/**
+ * The module (src-relative, no extension: `lib/inferno/catalog`) a file imports `name` from — its
+ * `import { name } from '$lib/…'` or `'./…'` — or the file itself when it declares it. Undefined for
+ * a package import, or a name it cannot place. Plain text, no regex.
+ */
+/**
+ * Is the route in `dir` prerendered? Kit takes the NEAREST `export const prerender`: the page's own
+ * files first (`+page.server`, `+page`), then each layout up the tree. `true` and `'auto'` prerender;
+ * `false` (or none found) does not. String search over the files (no regex, no parse).
+ */
+export declare function route_prerendered(read: (file: string) => string | undefined, dir: string): boolean;
+export type { Analysis, CpuProfile, HeapAllocator, NetCall, ReportMeta, RequestEntry };