@ogygia/devtools 0.0.0 → 0.11.1

package/dist/profiler/lineage.js

@@ -0,0 +1,359 @@
+// src/profiler/lineage.ts
+/**
+* DATA LINEAGE FROM THE CODE — which `page.data` keys each component actually reads, joined to
+* the loads that produced them and the seed that shipped them. The river (river.ts) draws the
+* flow with the islands' keys from the build; this reads the SERVER components' sources too, so
+* every key gets a verdict: read by an island (must ship), read on the server only (rendered
+* into HTML, need not ship), read by nobody (fetched for nothing — the load's wait behind it is
+* pure waste), or unknown (a component's reads could not be told).
+*
+* The scanner is a character walk, no regex: `data.key`, `data['key']`, `page.data.key`,
+* `$page.data.key`, and the destructurings `const { a, b: c } = data` / `= page.data`.
+*/
+const is_ident_start = (c) => c >= 97 && c <= 122 || c >= 65 && c <= 90 || c === 95 || c === 36;
+const is_ident = (c) => is_ident_start(c) || c >= 48 && c <= 57;
+const is_space = (c) => c === 32 || c === 9 || c === 10 || c === 13;
+/** the identifier ending right before `end` (exclusive), or '' */
+function ident_before(src, end) {
+	let i = end;
+	while (i > 0 && is_ident(src.charCodeAt(i - 1))) i--;
+	return src.slice(i, end);
+}
+/** the identifier starting at `i`, or '' */
+function ident_at(src, i) {
+	if (i >= src.length || !is_ident_start(src.charCodeAt(i))) return "";
+	let j = i + 1;
+	while (j < src.length && is_ident(src.charCodeAt(j))) j++;
+	return src.slice(i, j);
+}
+/** the keys of a destructuring pattern `{ a, b: c, d = 1, ...rest }` given the index of its `{` */
+function pattern_keys(src, open, out) {
+	let depth = 0;
+	let i = open;
+	let key_start = -1;
+	let took = false;
+	for (; i < src.length; i++) {
+		const c = src.charCodeAt(i);
+		if (c === 123 || c === 91 || c === 40) {
+			depth++;
+			if (depth === 1) {
+				key_start = -1;
+				took = false;
+			}
+			continue;
+		}
+		if (c === 125 || c === 93 || c === 41) {
+			depth--;
+			if (depth === 0) {
+				if (key_start >= 0 && !took) out.add(src.slice(key_start, i).trim());
+				return;
+			}
+			continue;
+		}
+		if (depth !== 1) continue;
+		if (c === 44) {
+			if (key_start >= 0 && !took) out.add(src.slice(key_start, i).trim());
+			key_start = -1;
+			took = false;
+			continue;
+		}
+		if (c === 58 || c === 61) {
+			if (key_start >= 0 && !took) out.add(src.slice(key_start, i).trim());
+			took = true;
+			continue;
+		}
+		if (key_start < 0 && !took && is_ident_start(c)) {
+			if (src.charCodeAt(i - 1) === 46) {
+				took = true;
+				continue;
+			}
+			key_start = i;
+		}
+	}
+}
+/**
+* The `page.data` keys a component source reads, or `null` when it takes the whole object in a
+* way that cannot be named (`...data`, `data` passed on, `Object.keys(data)`). `names` are the
+* identifiers that hold the data (`data` by default; `page.data` / `$page.data` always count).
+*/
+function data_reads(source, names = ["data"]) {
+	const src = blank_comments(source);
+	const keys = /* @__PURE__ */ new Set();
+	let whole = false;
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of ["data", ...names]) {
+		if (seen.has(name)) continue;
+		seen.add(name);
+		if (scan(src, name, names.includes(name), keys)) whole = true;
+	}
+	if (whole && !keys.size) return null;
+	if (whole) return [...keys, "*"];
+	return [...keys];
+}
+/** The 1-based line of the first place the source takes the data WHOLE (`const d = $page.data`,
+*  `fn(data)`, `...data`), or null when it only reads named keys. Same scan as `data_reads`. */
+function whole_read_line(source, names = ["data"]) {
+	const src = blank_comments(source);
+	const at = { pos: -1 };
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of ["data", ...names]) {
+		if (seen.has(name)) continue;
+		seen.add(name);
+		scan(src, name, names.includes(name), /* @__PURE__ */ new Set(), at);
+		if (at.pos >= 0) break;
+	}
+	if (at.pos < 0) return null;
+	let line = 1;
+	for (let i = source.indexOf("\n"); i !== -1 && i < at.pos; i = source.indexOf("\n", i + 1)) line++;
+	return line;
+}
+/** The source with its comments (`//`, block, HTML) and string contents blanked to spaces, so
+*  a word in prose or a URL never reads as code; positions are kept. A character walk. */
+function blank_comments(src) {
+	const out = src.split("");
+	const n = src.length;
+	let i = 0;
+	const blank = (from, to) => {
+		for (let k = from; k < to && k < n; k++) if (out[k] !== "\n") out[k] = " ";
+	};
+	while (i < n) {
+		const c = src.charCodeAt(i);
+		const next = src.charCodeAt(i + 1);
+		if (c === 47 && next === 47) {
+			let e = src.indexOf("\n", i);
+			if (e === -1) e = n;
+			blank(i, e);
+			i = e;
+			continue;
+		}
+		if (c === 47 && next === 42) {
+			let e = src.indexOf("*/", i + 2);
+			e = e === -1 ? n : e + 2;
+			blank(i, e);
+			i = e;
+			continue;
+		}
+		if (c === 60 && src.startsWith("<!--", i)) {
+			let e = src.indexOf("-->", i + 4);
+			e = e === -1 ? n : e + 3;
+			blank(i, e);
+			i = e;
+			continue;
+		}
+		if (c === 39 || c === 34 || c === 96) {
+			let e = i + 1;
+			while (e < n) {
+				const d = src.charCodeAt(e);
+				if (d === 92) {
+					e += 2;
+					continue;
+				}
+				if (d === c) break;
+				if (c === 96 && d === 36 && src.charCodeAt(e + 1) === 123) {
+					let depth = 1;
+					let k = e + 2;
+					while (k < n && depth) {
+						const q = src.charCodeAt(k);
+						if (q === 123) depth++;
+						else if (q === 125) depth--;
+						k++;
+					}
+					e = k;
+					continue;
+				}
+				if (c !== 96 && d === 10) break;
+				e++;
+			}
+			const inner = src.slice(i + 1, e);
+			if (inner.includes(" ") || inner.length > 40) blank(i + 1, e);
+			i = e + 1;
+			continue;
+		}
+		i++;
+	}
+	return out.join("");
+}
+/** one name's occurrences; returns true when the object was used whole somewhere */
+function scan(src, name, bare_ok, keys, whole_at) {
+	let whole = false;
+	const mark = (pos) => {
+		if (whole_at && whole_at.pos < 0) whole_at.pos = pos;
+	};
+	const n = src.length;
+	const len = name.length;
+	let i = 0;
+	while (i < n) {
+		const j = src.indexOf(name, i);
+		if (j === -1) break;
+		i = j + len;
+		if (j > 0 && is_ident(src.charCodeAt(j - 1))) continue;
+		if (i < n && is_ident(src.charCodeAt(i))) continue;
+		if (j >= 3 && src.charCodeAt(j - 1) === 46 && src.charCodeAt(j - 2) === 46 && src.charCodeAt(j - 3) === 46) {
+			if (bare_ok) {
+				whole = true;
+				mark(j);
+			}
+			continue;
+		}
+		let owner = "";
+		if (j > 0 && src.charCodeAt(j - 1) === 46) {
+			owner = ident_before(src, j - 1);
+			if (name !== "data" || owner !== "page" && owner !== "$page") continue;
+		} else if (!bare_ok) continue;
+		let k = i;
+		while (k < n && is_space(src.charCodeAt(k))) k++;
+		const c = src.charCodeAt(k);
+		if (c === 46) {
+			const key = ident_at(src, k + 1);
+			if (key) keys.add(key);
+			continue;
+		}
+		if (c === 91) {
+			let q = k + 1;
+			while (q < n && is_space(src.charCodeAt(q))) q++;
+			const quote = src.charCodeAt(q);
+			if (quote === 39 || quote === 34 || quote === 96) {
+				const close = src.indexOf(src[q], q + 1);
+				if (close > q) keys.add(src.slice(q + 1, close));
+			} else {
+				whole = true;
+				mark(j);
+			}
+			continue;
+		}
+		let b = j - 1;
+		if (owner) b -= owner.length + 1;
+		while (b >= 0 && is_space(src.charCodeAt(b))) b--;
+		if (b >= 0 && src.charCodeAt(b) === 61) {
+			let e = b - 1;
+			while (e >= 0 && is_space(src.charCodeAt(e))) e--;
+			if (e >= 0 && src.charCodeAt(e) === 125) {
+				let depth = 0;
+				let o = e;
+				for (; o >= 0; o--) {
+					const cc = src.charCodeAt(o);
+					if (cc === 125) depth++;
+					else if (cc === 123 && --depth === 0) break;
+				}
+				if (o >= 0) {
+					pattern_keys(src, o, keys);
+					continue;
+				}
+			}
+			if (c === 59 || c === 10 || k >= n) {
+				whole = true;
+				mark(j);
+				continue;
+			}
+		}
+		if (c === 41 || c === 93 || c === 63 || c === 124 || c === 38) {
+			whole = true;
+			mark(j);
+			continue;
+		}
+	}
+	return whole;
+}
+/** the `let { data } = $props()` / `export let data` names a component gives its data prop —
+*  plus any rename (`let { data: page_data } = $props()`) */
+function data_prop_names(src) {
+	const names = /* @__PURE__ */ new Set(["data"]);
+	const at = src.indexOf("$props()");
+	if (at !== -1) {
+		let e = at - 1;
+		while (e >= 0 && is_space(src.charCodeAt(e))) e--;
+		if (e >= 0 && src.charCodeAt(e) === 61) {
+			e--;
+			while (e >= 0 && is_space(src.charCodeAt(e))) e--;
+			if (e >= 0 && src.charCodeAt(e) === 125) {
+				let depth = 0;
+				let o = e;
+				for (; o >= 0; o--) {
+					const cc = src.charCodeAt(o);
+					if (cc === 125) depth++;
+					else if (cc === 123 && --depth === 0) break;
+				}
+				if (o >= 0) {
+					const body = src.slice(o, e + 1);
+					const d = body.indexOf("data");
+					if (d !== -1) {
+						let q = d + 4;
+						while (q < body.length && is_space(body.charCodeAt(q))) q++;
+						if (body.charCodeAt(q) === 58) {
+							q++;
+							while (q < body.length && is_space(body.charCodeAt(q))) q++;
+							const alias = ident_at(body, q);
+							if (alias) names.add(alias);
+						}
+					}
+				}
+			}
+		}
+	}
+	return [...names];
+}
+function build_lineage(input) {
+	const notes = [];
+	const components = input.components.map((c) => {
+		const whole = c.reads?.includes("*") ?? false;
+		return {
+			name: c.name,
+			file: c.file,
+			island: c.island,
+			reads: c.reads ? c.reads.filter((k) => k !== "*") : null,
+			whole,
+			...whole && c.whole_line ? { whole_line: c.whole_line } : {}
+		};
+	});
+	const from = /* @__PURE__ */ new Map();
+	const wait = /* @__PURE__ */ new Map();
+	let any_lane = false;
+	for (const l of input.lanes) {
+		if (!l.keys) continue;
+		any_lane = true;
+		for (const k of l.keys) {
+			if (!from.has(k)) from.set(k, l.file);
+			if (l.wait_ms !== void 0) wait.set(k, l.wait_ms);
+		}
+	}
+	const keys = /* @__PURE__ */ new Set([...from.keys(), ...Object.keys(input.seed)]);
+	for (const c of components) for (const k of c.reads ?? []) keys.add(k);
+	if (!keys.size) return void 0;
+	const blind = components.filter((c) => c.reads === null);
+	const whole_readers = components.filter((c) => c.whole);
+	if (blind.length) notes.push(`${blind.length} component${blind.length > 1 ? "s" : ""} read the data in a way the scan could not name (${blind.map((c) => c.name).slice(0, 3).join(", ")}${blind.length > 3 ? "…" : ""}): their keys are unknown, so no key is called unread.`);
+	if (whole_readers.length) notes.push(`${whole_readers.map((c) => c.name).slice(0, 3).join(", ")} take${whole_readers.length > 1 ? "" : "s"} the whole data object: every key may be read there.`);
+	if (!any_lane) notes.push("No load returned keys the profiler could read from its source: the keys come from the seed and the readers alone.");
+	const rows = [];
+	for (const key of keys) {
+		const named = components.filter((c) => c.reads?.includes(key));
+		const readers = [...named, ...whole_readers.filter((w) => !named.includes(w))].map((c) => ({
+			name: c.name,
+			island: c.island
+		}));
+		const shipped = input.seed[key] ?? 0;
+		let verdict;
+		if (named.some((c) => c.island)) verdict = "island";
+		else if (whole_readers.some((w) => w.island)) verdict = "unknown";
+		else if (named.length) verdict = shipped > 0 ? "server-only" : "server";
+		else if (blind.length || whole_readers.length) verdict = "unknown";
+		else verdict = "unread";
+		rows.push({
+			key,
+			from: from.get(key) ?? null,
+			shipped_bytes: shipped,
+			readers,
+			verdict,
+			load_wait_ms: wait.get(key) ?? null
+		});
+	}
+	rows.sort((a, b) => b.shipped_bytes - a.shipped_bytes || (b.load_wait_ms ?? 0) - (a.load_wait_ms ?? 0));
+	return {
+		keys: rows,
+		components,
+		unread: rows.filter((r) => r.verdict === "unread").sort((a, b) => (b.load_wait_ms ?? 0) - (a.load_wait_ms ?? 0)),
+		server_only: rows.filter((r) => r.verdict === "server-only").sort((a, b) => b.shipped_bytes - a.shipped_bytes),
+		notes
+	};
+}
+export { blank_comments, build_lineage, data_prop_names, data_reads, whole_read_line };

package/dist/profiler/module-map.d.ts

@@ -0,0 +1,12 @@
+import { FrameCategory } from "./analyze.js";
+/** `(url, line) → module id` over the module maps found beside the chunks (memoized per folder) */
+export declare function module_lookup(): (url: string, line: number) => string | undefined;
+/** a script that MAY be a built server chunk: JavaScript outside node_modules and Node's own — an
+ *  absolute build path, or the RELATIVE name a Lambda / Amplify host hands V8 (`./chunks/x.js`). The
+ *  module map beside it has the last word (no map, no entry: not a chunk) */
+export declare const may_be_chunk: (file: string) => boolean;
+/** a module id's kind: this profiler's code, ogygia's runtime, a package, or (undefined) the app's */
+export declare function module_category(id: string): {
+  category: FrameCategory;
+  pkg?: string;
+} | undefined;

package/dist/profiler/module-map.js

@@ -0,0 +1,94 @@
+import { embedded_module_at } from "./embedded-maps.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// src/profiler/module-map.ts
+/**
+* THE MODULE MAP, read (the build writes it: vite/module-map.ts). A frame in a bundled server chunk
+* (`…/output/server/chunks/frames.js:12`) with no sourcemap names only the chunk; the map says which
+* source module is at that line, so the frame is filed by what it is — this profiler's own code
+* (overhead, not the app's time), ogygia's runtime or a bundled package (a library), else the app.
+* The map sits beside the chunks, found by walking up from the chunk's folder, wherever the host put
+* the build.
+*/
+const MODULE_MAP_FILE = "ogygia-modules.json";
+/** `(url, line) → module id` over the module maps found beside the chunks (memoized per folder) */
+function module_lookup() {
+	const by_dir = /* @__PURE__ */ new Map();
+	const find = (start) => {
+		const seen = [];
+		let dir = start;
+		let found = null;
+		for (let i = 0; i < 6; i++) {
+			if (by_dir.has(dir)) {
+				found = by_dir.get(dir);
+				break;
+			}
+			seen.push(dir);
+			const file = path.join(dir, MODULE_MAP_FILE);
+			if (fs.existsSync(file)) {
+				try {
+					found = {
+						dir,
+						chunks: JSON.parse(fs.readFileSync(file, "utf8")).chunks
+					};
+				} catch {
+					found = null;
+				}
+				break;
+			}
+			const up = path.dirname(dir);
+			if (up === dir) break;
+			dir = up;
+		}
+		for (const d of seen) by_dir.set(d, found);
+		return found;
+	};
+	return (url, line) => {
+		let file = url;
+		if (file.startsWith("file://")) try {
+			file = fileURLToPath(file);
+		} catch {
+			return;
+		}
+		if (!path.isAbsolute(file)) file = path.resolve(process.cwd(), file);
+		const m = find(path.dirname(file));
+		if (!m) return embedded_module_at(file, line);
+		const ranges = m.chunks[path.relative(m.dir, file).split(path.sep).join("/")];
+		if (!ranges) return embedded_module_at(file, line);
+		for (const [a, b, id] of ranges) if (line >= a && line <= b) return id;
+	};
+}
+/** a script that MAY be a built server chunk: JavaScript outside node_modules and Node's own — an
+*  absolute build path, or the RELATIVE name a Lambda / Amplify host hands V8 (`./chunks/x.js`). The
+*  module map beside it has the last word (no map, no entry: not a chunk) */
+const may_be_chunk = (file) => !!file && !file.startsWith("node:") && !file.includes("/node_modules/") && !file.includes("\\node_modules\\") && (file.endsWith(".js") || file.endsWith(".mjs") || file.endsWith(".cjs"));
+/** a module id's kind: this profiler's code, ogygia's runtime, a package, or (undefined) the app's */
+function module_category(id) {
+	const posix = id.split("\\").join("/");
+	if (posix.includes("virtual:ogygia")) return {
+		category: "dependency",
+		pkg: "ogygia"
+	};
+	const nm = posix.lastIndexOf("node_modules/");
+	const own = (p) => p.includes("ogygia/src/") || p.includes("ogygia/dist/") || p.includes("/packages/core/src/") || p.includes("/packages/core/dist/") || p.includes("/devtools/src/profiler/") || p.includes("/devtools/dist/profiler/");
+	if (nm !== -1) {
+		const rest = posix.slice(nm + 13).split("/");
+		const folder = rest[0].startsWith("@") ? `${rest[0]}/${rest[1]}` : rest[0];
+		const pkg = folder === "@ogygia/core" ? "ogygia" : folder;
+		if ((pkg === "ogygia" || pkg === "@ogygia/devtools") && rest.includes("profiler")) return { category: "profiler" };
+		if (pkg === "svelte") return {
+			category: "svelte",
+			pkg
+		};
+		return {
+			category: "dependency",
+			pkg
+		};
+	}
+	if (own(posix)) return posix.includes("/profiler/") ? { category: "profiler" } : {
+		category: "dependency",
+		pkg: "ogygia"
+	};
+}
+export { may_be_chunk, module_category, module_lookup };

package/dist/profiler/net.d.ts

@@ -0,0 +1,169 @@
+import { register_profiler_file } from "./frames.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface NetCall {
+  /** performance.now() at call start */
+  start: number;
+  /** Date.now() at call start (for window filtering) */
+  epoch: number;
+  /** ms until headers arrived; -1 while pending */
+  ms: number;
+  /** additional ms spent reading the body (json()/text()/stream end) */
+  body_ms?: number;
+  method: string;
+  url: string;
+  host: string;
+  /** 0 = errored before a response */
+  status: number;
+  /** DECODED response body size (what the app receives) — measured by counting a cloned body stream,
+   *  so it's captured however the app reads (json/text/stream) and even when there's no content-length. */
+  bytes?: number;
+  /** wire/transfer size from `content-length` (compressed when `encoding` is set) */
+  transfer_bytes?: number;
+  /** a fingerprint of the decoded body (`<fnv1a>:<length>`): identical across renders = the same
+   *  answer every time, one to cache across requests */
+  body_hash?: string;
+  /** the request carried a cookie or an authorization header: its answer may be per user */
+  personal?: boolean;
+  /** response `content-encoding` (gzip / br / …) when compressed */
+  encoding?: string;
+  /** short response `content-type` (params stripped) */
+  type?: string;
+  /** response headers (curated + capped) — shown in the request side panel */
+  headers?: Record<string, string>;
+  /** request body size in bytes, when it has one */
+  req_bytes?: number;
+  /** request body preview (truncated) — for string / form / URLSearchParams bodies */
+  req_payload?: string;
+  kind: "fetch" | "http";
+  /** route of the page render that made this call, when known */
+  route: string | null;
+  /** path of the page render that made this call, when known */
+  path: string | null;
+  /** resolved caller string, filled in at report time from caller_site */
+  caller?: string;
+  /** raw caller location (bundled), resolved to source at report time */
+  caller_site?: CallerSite;
+  /** the first-party call path above the caller (nearest first), raw; resolved into `callers` */
+  caller_chain?: CallerSite[];
+  /** the resolved call path: `fetchStock (lib/stock.ts:9)` ← `load (routes/+page.server.ts:44)` */
+  callers?: string[];
+  /** the caller's source position (the first app frame), for reading the call site's code */
+  caller_at?: {
+    path: string;
+    line: number;
+  };
+  /** the next app frame out (who called the caller): a helper's call site in its caller */
+  outer_at?: {
+    path: string;
+    line: number;
+  };
+  /** the upstream's own `Server-Timing` entries: what THEIR side spent the wait on */
+  timings?: ServerTiming[];
+  /** the upstream's own profiler's picture of this request (nested trace), when it answered */
+  trace?: UpstreamTrace;
+  error?: string;
+}
+/** One `Server-Timing` entry from an upstream response (`db;dur=180;desc="postgres"`). */
+export interface ServerTiming {
+  name: string;
+  /** `dur`, ms; 0 when the entry carries none */
+  ms: number;
+  desc?: string;
+}
+export declare function parse_server_timing(header: string | null | undefined): ServerTiming[] | undefined;
+export declare function set_stack_capture(on: boolean): void;
+/** A caller location as the bundler sees it — resolved to source later, at
+ * report time, through the sourcemap resolver (we have no maps here). */
+export interface CallerSite {
+  fn: string;
+  /** generated (bundled) file */
+  file: string;
+  /** 1-based line in the generated file */
+  line: number;
+  /** 1-based column in the generated file */
+  column: number;
+}
+/** The nearest first-party frame that issued an I/O call — skips node internals,
+ * node_modules, and the profiler's own frames, so the caller reads like your
+ * code. Shared by the network patch and the async_hooks I/O tracker. */
+export declare function nearest_app_site(): CallerSite | undefined;
+/** The first-party CALL PATH above an I/O call — the nearest app frame and the ones that called it
+ *  (`fetchStock` ← `load`), skipping the same internals as `nearest_app_site`. Read off the one
+ *  stack that call already captured, so it costs nothing extra beyond a few more frames. */
+export declare function app_call_chain(limit?: number): CallerSite[];
+/** Best-effort caller string with no sourcemap (fallback before resolution). */
+export declare function nearest_app_frame(): string | undefined;
+export interface NetContext {
+  route: string | null;
+  path: string | null;
+  on_net(call: NetCall): void;
+  /** the profiler's what-if render: an answer kept from the timed renders, for a call this request
+   *  makes (`GET <url>`), instead of making it — undefined = make the call */
+  answer?(method: string, url: string): Response | undefined;
+}
+type Emit = (call: NetCall) => void;
+/** start (clearing what was kept) or stop keeping answers */
+export declare function keep_answers(on: boolean): void;
+/** drop every kept answer */
+export declare function drop_answers(): void;
+/**
+ * WHAT CHANGED IN AN ANSWER between the first render and the last: the one stretch that differs
+ * (the bytes before it and after it are the same), and that stretch as text with a little around
+ * it — a timestamp, a request id. Undefined when either answer was not kept, or they are the same.
+ */
+export declare function answer_diff(key: string): {
+  bytes: number;
+  size: number;
+  text: string;
+} | undefined;
+/** a kept answer as a fresh Response, or undefined */
+export declare function kept_answer(key: string): Response | undefined;
+/**
+ * Install the patches. `fallback` receives calls made outside any request
+ * context (startup work, background jobs) so window recordings still see them.
+ * Idempotent: a second call just re-asserts the fetch patch (see `ensure_fetch_patched`).
+ */
+export declare function install_net_capture(als: AsyncLocalStorage<NetContext>, fallback: Emit): Promise<void>;
+/**
+ * Re-assert the `globalThis.fetch` patch. `globalThis.fetch` can be REPLACED out from under us after
+ * install — a late undici init, a framework fetch polyfill, an HMR reload of this module — which
+ * silently kills capture, so reports "sometimes catch network, sometimes don't". Call this before every
+ * profile: if the live fetch isn't ours (identified by the brand symbol, so we never wrap our own
+ * wrapper) re-wrap whatever is there now with the same sink. One property read, idempotent — safe to
+ * call every request/run.
+ */
+export declare function ensure_fetch_patched(): void;
+/**
+ * KIT'S OWN `event.fetch` never reaches the global one for a same-origin call: it dispatches the
+ * request to the app's `respond()` in-process. A load that calls its own API through it is
+ * invisible to the global patch — so the profiler wraps `event.fetch` per attributed request with
+ * the same recorder. Idempotent (the brand), nothing when capture is not installed.
+ */
+export declare function wrap_event_fetch<F extends typeof globalThis.fetch>(f: F): F;
+/** the request header that asks, and the response header that answers */
+export declare const TRACE_HEADER = "x-og-trace";
+export interface UpstreamTrace {
+  /** the upstream's wall time for the request, ms */
+  ms: number;
+  cpu_ms: number;
+  /** waiting on its own outbound calls, ms, and how many */
+  wait_ms: number;
+  calls: number;
+  route?: string | null;
+  /** its own upstream calls, biggest first (a few) */
+  top?: {
+    url: string;
+    ms: number;
+  }[];
+  /** the profiler's own base on that host, so a report there can be opened */
+  profiler?: string;
+}
+export declare function encode_trace(t: UpstreamTrace): string;
+export declare function decode_trace(h: string | null | undefined): UpstreamTrace | undefined;
+/**
+ * How much of the wall time is explained by network calls running one after
+ * another (no overlap). High sequential time with several calls = the classic
+ * "await in a loop" page.
+ */
+export declare function sequential_ms(calls: NetCall[]): number;
+export { register_profiler_file };