@ogygia/core 0.0.0 → 0.11.1

package/dist/insights/session-insights.js

@@ -0,0 +1,548 @@
+import { analyze_cpu, fn_label, is_trace } from "./cpu.js";
+// src/insights/session-insights.ts
+/**
+* What a recorded session (devtools/session.ts) says — pure, so it tests on plain data. Findings point back
+* at the page: an interaction's target, a shift's element, an island (the tab resolves the refs).
+* The CPU trace, when there is one, names the function behind a slow interaction or a long task
+* (cpu.ts, with each interaction as its own window); long animation frames name the script when
+* the sampler could not run.
+*/
+/** The session on one clock, lane by lane (the Record tab draws it). Capped per lane. */
+function session_timeline(s, names) {
+	const z = s.from;
+	const cap = (xs) => xs.slice(0, 300);
+	const input = [];
+	s.clicks.forEach((c, i) => input.push({
+		t0: c.t - z,
+		t1: c.t - z,
+		label: `click ${c.target}`,
+		tone: "info",
+		ref: {
+			kind: "click",
+			i
+		}
+	}));
+	const seen = /* @__PURE__ */ new Set();
+	s.interactions.forEach((x, i) => {
+		if (!x.id || seen.has(x.id)) return;
+		seen.add(x.id);
+		input.push({
+			t0: x.t - z,
+			t1: x.t - z + x.duration,
+			label: `${x.name} ${x.target} — ${Math.round(x.duration)} ms (handlers ${Math.round(x.processing)} ms)`,
+			tone: x.duration >= SLOW ? "bad" : x.duration >= SLUGGISH ? "warn" : "ok",
+			ref: {
+				kind: "interaction",
+				i
+			}
+		});
+	});
+	const main = s.longtasks.map((t) => ({
+		t0: t.t - z,
+		t1: t.t - z + t.ms,
+		label: `long task ${Math.round(t.ms)} ms`,
+		tone: t.ms >= 200 ? "bad" : "warn"
+	}));
+	const net = s.requests.map((r) => {
+		const ssr = r.server?.find((x) => x.name === "ssr")?.ms;
+		const up = r.server?.find((x) => x.name === "net")?.ms ?? 0;
+		let path = r.url;
+		try {
+			path = new URL(r.url).pathname;
+		} catch {}
+		return {
+			t0: r.t - z,
+			t1: r.t - z + r.ms,
+			label: `${path} — ${Math.round(r.ms)} ms${ssr !== void 0 ? ` (server ${Math.round(ssr)} ms${up ? `, waiting ${Math.round(up)} ms` : ""})` : ""}${r.status && r.status >= 400 ? ` · ${r.status}` : ""}`,
+			tone: r.status !== null && r.status >= 400 ? "bad" : r.ms >= 1e3 ? "warn" : "info",
+			...ssr !== void 0 ? { server: {
+				ms: ssr,
+				up
+			} } : {}
+		};
+	});
+	const islands = [];
+	for (const p of (s.pages ?? []).slice(1)) islands.push({
+		t0: p.t - z,
+		t1: p.t - z,
+		label: `page load: ${p.url}`,
+		tone: "info"
+	});
+	const hyd = /* @__PURE__ */ new Map();
+	for (const e of s.events) if (e.name === "region.hydrate.done" && e.fp) hyd.set(e.fp, e.t);
+	for (const e of s.events) {
+		const fp = e.fp;
+		if (e.name === "wake.fired" && fp) islands.push({
+			t0: e.t - z,
+			t1: (hyd.get(fp) ?? e.t) - z,
+			label: `${names(fp)} woke (${e.when ?? ""})`,
+			tone: "ok",
+			ref: {
+				kind: "island",
+				fp
+			}
+		});
+		else if (e.name === "region.hydrate.failed" && fp) islands.push({
+			t0: e.t - z,
+			t1: e.t - z,
+			label: `${names(fp)} failed to hydrate`,
+			tone: "bad",
+			ref: {
+				kind: "island",
+				fp
+			}
+		});
+		else if (e.name === "nav.finish") islands.push({
+			t0: e.t - e.ms - z,
+			t1: e.t - z,
+			label: `navigation to ${e.to} — ${Math.round(e.ms)} ms`,
+			tone: e.ms >= 500 ? "warn" : "info"
+		});
+	}
+	const layout = s.shifts.map((x, i) => ({
+		t0: x.t - z,
+		t1: x.t - z,
+		label: `layout shift ${x.value}${x.input ? " (after input)" : ""}${x.fp ? ` in ${names(x.fp)}` : ""}`,
+		tone: x.input ? "info" : x.value >= .05 ? "bad" : "warn",
+		ref: {
+			kind: "shift",
+			i
+		}
+	}));
+	const errors = s.errors.map((e) => ({
+		t0: e.t - z,
+		t1: e.t - z,
+		label: e.message,
+		tone: "bad"
+	}));
+	return [
+		{
+			key: "input",
+			label: "input",
+			items: cap(input)
+		},
+		{
+			key: "main",
+			label: "main thread",
+			items: cap(main)
+		},
+		{
+			key: "net",
+			label: "requests",
+			items: cap(net)
+		},
+		{
+			key: "islands",
+			label: "islands · nav",
+			items: cap(islands)
+		},
+		{
+			key: "layout",
+			label: "layout",
+			items: cap(layout)
+		},
+		{
+			key: "errors",
+			label: "errors",
+			items: cap(errors)
+		}
+	].filter((l) => l.items.length);
+}
+const ms = (n) => n >= 1e3 ? (n / 1e3).toFixed(2) + " s" : Math.round(n) + " ms";
+const kb = (n) => n < 1024 ? n + " B" : n < 1048576 ? (n / 1024).toFixed(1) + " KB" : (n / 1048576).toFixed(1) + " MB";
+const path_of = (u) => {
+	try {
+		const x = new URL(u);
+		return x.pathname + (x.search.length > 1 ? x.search.slice(0, 40) : "");
+	} catch {
+		return u;
+	}
+};
+/** a GET on this page's own origin (the profiler can render only those) */
+function same_origin_get(url, page_url) {
+	try {
+		return new URL(url).origin === new URL(page_url).origin && !url.includes("/__profiler");
+	} catch {
+		return false;
+	}
+}
+/** Slow from here (Event Timing duration, ms): Google's INP lines. */
+const SLOW = 200;
+const SLUGGISH = 100;
+function analyze_session(s, names, page_url) {
+	const findings = [];
+	const name_of = (fp) => fp ? names(fp) : "the page";
+	const by_id = /* @__PURE__ */ new Map();
+	const longest = /* @__PURE__ */ new Map();
+	s.interactions.forEach((x, i) => {
+		if (!x.id) return;
+		longest.set(x.id, Math.max(longest.get(x.id) ?? 0, x.duration));
+		const prev = by_id.get(x.id);
+		const p = prev === void 0 ? null : s.interactions[prev];
+		if (!p || x.processing > p.processing || x.processing === p.processing && x.duration > p.duration) by_id.set(x.id, i);
+	});
+	for (const [id, i] of by_id) s.interactions[i] = {
+		...s.interactions[i],
+		duration: longest.get(id) ?? s.interactions[i].duration
+	};
+	const chosen = [...by_id.values()];
+	let cpu = null;
+	if (is_trace(s.cpu)) {
+		const windows = chosen.map((i) => ({
+			fp: "ix:" + i,
+			from: s.interactions[i].t,
+			to: s.interactions[i].t + s.interactions[i].duration
+		}));
+		cpu = analyze_cpu(s.cpu, windows, s.longtasks, page_url);
+	}
+	const why = (i) => {
+		const f = cpu?.islands["ix:" + i]?.top[0];
+		if (f && f.self_ms >= 5) return `; mostly ${fn_label(f)}`;
+		const x = s.interactions[i];
+		const sc = s.frames.find((fr) => fr.t <= x.t + x.duration && fr.t + fr.ms >= x.t && fr.scripts.length)?.scripts.slice().sort((a, b) => b.ms - a.ms)[0];
+		return sc && sc.ms >= 5 ? `; mostly ${sc.invoker || sc.fn || "a script"}${sc.source ? ` (${path_of(sc.source).split("/").pop()})` : ""}` : "";
+	};
+	const slow = chosen.filter((i) => s.interactions[i].duration >= SLUGGISH).sort((a, b) => s.interactions[b].duration - s.interactions[a].duration);
+	for (const i of slow.slice(0, 5)) {
+		const x = s.interactions[i];
+		const part = x.processing >= x.input_delay && x.processing >= x.presentation ? "processing" : x.input_delay >= x.presentation ? "input" : "paint";
+		findings.push({
+			code: "slow-interaction",
+			severity: x.duration >= SLOW ? "warn" : "info",
+			message: `${x.name} on ${x.target}${x.fp ? ` in ${name_of(x.fp)}` : ""} took ${ms(x.duration)} to show a result (waiting ${ms(x.input_delay)} · handlers ${ms(x.processing)} · painting ${ms(x.presentation)})${why(i)}.`,
+			fix: part === "processing" ? "The handlers are the cost: do less before the next paint (update the screen first, then do the rest in a later task), or move the work off the main thread." : part === "input" ? "The click waited for other work to finish: something else held the main thread when it came (see the long tasks)." : "Rendering the result is the cost: a big DOM change or an expensive style/layout after it. Change less at once.",
+			refs: [{
+				kind: "interaction",
+				i
+			}]
+		});
+	}
+	const rage = [];
+	for (let a = 0; a < s.clicks.length; a++) {
+		let n = 1;
+		for (let b = a + 1; b < s.clicks.length && s.clicks[b].t - s.clicks[a].t < 1e3; b++) if (s.clicks[b].target === s.clicks[a].target) n++;
+		if (n >= 3 && !rage.some((r) => s.clicks[r].target === s.clicks[a].target)) rage.push(a);
+	}
+	for (const i of rage) findings.push({
+		code: "rage-click",
+		severity: "warn",
+		message: `${s.clicks[i].target}${s.clicks[i].fp ? ` in ${name_of(s.clicks[i].fp)}` : ""} was clicked 3+ times within a second: to a visitor it looked like nothing happened.`,
+		fix: "Show a reaction at once (a pressed state, a spinner), and make sure the click is handled.",
+		refs: [{
+			kind: "click",
+			i
+		}]
+	});
+	const navs = s.events.filter((e) => e.name === "nav.start").map((e) => e.t);
+	const raged = new Set(rage.map((r) => s.clicks[r].target));
+	const dead = [];
+	const late = [];
+	s.clicks.forEach((c, i) => {
+		if (raged.has(c.target)) return;
+		if (!c.clickable) return;
+		if (c.fp) {
+			const first = s.mut_log.find((m) => m.t >= c.t && m.t <= c.t + 3e3 && m.fp === c.fp);
+			if (!first && !navs.some((t) => t >= c.t && t <= c.t + 3e3)) dead.push(i);
+			else if (first && first.t - c.t > 500) late.push({
+				i,
+				after: first.t - c.t
+			});
+			return;
+		}
+		const until = c.t + 500;
+		const others = new Set(s.clicks.filter((o, j) => j !== i && o.t >= c.t && o.t <= until && o.fp).map((o) => o.fp));
+		const changed = s.mut_log.some((m) => m.t >= c.t && m.t <= until && !others.has(m.fp));
+		const asked = s.requests.some((r) => r.t >= c.t && r.t <= until) && !others.size;
+		if (!changed && !asked && !navs.some((t) => t >= c.t && t <= until)) dead.push(i);
+	});
+	if (late.length) findings.push({
+		code: "late-feedback",
+		severity: "info",
+		message: `${late.length} click${late.length === 1 ? "" : "s"} got no visible answer for a while: ${late.slice(0, 3).map(({ i, after }) => `${s.clicks[i].target}${s.clicks[i].fp ? ` in ${name_of(s.clicks[i].fp)}` : ""} (${ms(after)})`).join(", ")}.`,
+		fix: "Show a reaction at once — a pressed or loading state — and then the result.",
+		refs: late.slice(0, 6).map(({ i }) => ({
+			kind: "click",
+			i
+		}))
+	});
+	if (dead.length) findings.push({
+		code: "dead-click",
+		severity: "info",
+		message: `${dead.length} click${dead.length === 1 ? "" : "s"} changed nothing on the page (no DOM change, no request, no navigation): ${[...new Set(dead.map((i) => s.clicks[i].target))].slice(0, 3).join(", ")}.`,
+		fix: "If it should do something, its handler is missing (an island that never woke, plain HTML with no JS) or it failed silently.",
+		refs: dead.slice(0, 6).map((i) => ({
+			kind: "click",
+			i
+		}))
+	});
+	const lt_ms = s.longtasks.reduce((a, t) => a + t.ms, 0);
+	if (s.longtasks.length) {
+		const f = cpu?.outside.top[0];
+		findings.push({
+			code: "long-tasks",
+			severity: lt_ms >= 300 ? "warn" : "info",
+			message: `${s.longtasks.length} long task${s.longtasks.length === 1 ? "" : "s"} held the main thread for ${ms(lt_ms)} in all (the longest ${ms(Math.max(...s.longtasks.map((t) => t.ms)))})${f && f.self_ms >= 5 ? `; outside the interactions, mostly ${fn_label(f)}` : ""}.`,
+			refs: []
+		});
+	}
+	const unexpected = s.shifts.map((x, i) => ({
+		x,
+		i
+	})).filter(({ x }) => !x.input);
+	const cls = unexpected.reduce((a, { x }) => a + x.value, 0);
+	if (cls >= .02) findings.push({
+		code: "unexpected-shift",
+		severity: cls >= .1 ? "warn" : "info",
+		message: `The layout moved by itself (no input) ${unexpected.length} time${unexpected.length === 1 ? "" : "s"}, CLS ${Math.round(cls * 1e3) / 1e3}${unexpected[0]?.x.fp ? `, first in ${name_of(unexpected[0].x.fp)}` : ""}.`,
+		fix: "Reserve space for what arrives late (images, holes, islands that grow as they wake).",
+		refs: unexpected.slice(0, 6).map(({ i }) => ({
+			kind: "shift",
+			i
+		}))
+	});
+	const bytes = s.requests.reduce((a, r) => a + r.bytes, 0);
+	const failed = s.requests.filter((r) => r.status !== null && r.status >= 400);
+	if (failed.length) findings.push({
+		code: "failed-requests",
+		severity: "warn",
+		message: `${failed.length} request${failed.length === 1 ? "" : "s"} failed: ${failed.slice(0, 3).map((r) => `${r.status} ${path_of(r.url)}`).join(", ")}.`,
+		refs: []
+	});
+	const slow_req = s.requests.filter((r) => r.ms >= 1e3).sort((a, b) => b.ms - a.ms);
+	if (slow_req.length) findings.push({
+		code: "slow-requests",
+		severity: "info",
+		message: `${slow_req.length} request${slow_req.length === 1 ? "" : "s"} took over a second: ${slow_req.slice(0, 3).map((r) => `${path_of(r.url)} ${ms(r.ms)}`).join(", ")}.`,
+		refs: []
+	});
+	const by_url = /* @__PURE__ */ new Map();
+	for (const r of s.requests) if (r.type === "fetch" || r.type === "xmlhttprequest") by_url.set(path_of(r.url), (by_url.get(path_of(r.url)) ?? 0) + 1);
+	const repeated = [...by_url].filter(([, n]) => n >= 3).sort((a, b) => b[1] - a[1]);
+	if (repeated.length) findings.push({
+		code: "repeated-requests",
+		severity: "info",
+		message: `The same request went out again and again: ${repeated.slice(0, 3).map(([u, n]) => `${u} ×${n}`).join(", ")}.`,
+		fix: "Cache the answer, or share one request between the parts that ask.",
+		refs: []
+	});
+	const st = (r, name) => r.server?.find((x) => x.name === name);
+	const served = s.requests.filter((r) => st(r, "ssr")).sort((a, b) => (st(b, "ssr")?.ms ?? 0) - (st(a, "ssr")?.ms ?? 0));
+	for (const r of served.slice(0, 3)) {
+		const ssr = st(r, "ssr").ms;
+		if (ssr < 200) break;
+		const cpu_ms = st(r, "cpu")?.ms;
+		const net = st(r, "net");
+		const up = st(r, "up1");
+		findings.push({
+			code: "server-time",
+			severity: ssr >= 500 ? "warn" : "info",
+			message: `${path_of(r.url)} took ${ms(r.ms)}: ${ms(ssr)} on the server` + (cpu_ms !== void 0 ? ` (${ms(cpu_ms)} of CPU)` : "") + (net ? `, ${ms(net.ms)} of it waiting on ${net.desc.split("(")[1]?.split(")")[0] ?? "several"} outbound call${net.desc.includes("(1)") ? "" : "s"}${up ? ` — the slowest ${up.desc} ${ms(up.ms)}` : ""}` : "") + `, ${ms(Math.max(0, r.ms - ssr))} on the network.`,
+			fix: net && net.ms >= ssr * .5 ? "The server mostly waited: start the calls together, cache the answer, or move the call out of this request." : "Profile it on the server (the button) to see where its time went.",
+			refs: (() => {
+				const c = s.clicks.filter((x) => x.t <= r.t && r.t - x.t <= 3e3).at(-1);
+				return c ? [{
+					kind: "click",
+					i: s.clicks.indexOf(c)
+				}] : [];
+			})(),
+			...same_origin_get(r.url, page_url) ? { url: r.url } : {}
+		});
+	}
+	const by_island = {};
+	const slot = (fp) => by_island[fp] ??= {
+		clicks: 0,
+		slow: [],
+		requests: [],
+		mutations: 0
+	};
+	for (const c of s.clicks) if (c.fp) slot(c.fp).clicks++;
+	for (const i of chosen) {
+		const x = s.interactions[i];
+		if (x.fp && x.duration >= SLUGGISH) slot(x.fp).slow.push({
+			target: x.target,
+			duration: x.duration,
+			processing: x.processing
+		});
+	}
+	for (const r of s.requests) {
+		const c = s.clicks.filter((x) => x.t <= r.t && r.t - x.t <= 3e3).at(-1);
+		if (!c?.fp) continue;
+		slot(c.fp).requests.push({
+			url: path_of(r.url),
+			ms: r.ms,
+			server_ms: st(r, "ssr")?.ms ?? null,
+			net_ms: st(r, "net")?.ms ?? null,
+			up: st(r, "up1") ? `${st(r, "up1").desc} ${ms(st(r, "up1").ms)}` : null,
+			status: r.status
+		});
+	}
+	for (const m of s.mutations) if (m.fp && by_island[m.fp]) by_island[m.fp].mutations = m.count;
+	const woke = s.events.filter((e) => e.name === "wake.fired");
+	if (woke.length) {
+		const done = /* @__PURE__ */ new Map();
+		for (const e of s.events) if (e.name === "region.hydrate.done" && e.fp) done.set(e.fp, e.ms);
+		const list = woke.map((e) => e.fp ? `${name_of(e.fp)}${done.has(e.fp) ? ` (${ms(done.get(e.fp))})` : ""}` : "an island");
+		findings.push({
+			code: "islands-woke",
+			severity: "info",
+			message: `${woke.length} island${woke.length === 1 ? "" : "s"} woke during the session: ${[...new Set(list)].slice(0, 5).join(", ")}.`,
+			refs: woke.filter((e) => e.fp).slice(0, 6).map((e) => ({
+				kind: "island",
+				fp: e.fp
+			}))
+		});
+	}
+	for (const e of s.events) if (e.name === "region.hydrate.failed") findings.push({
+		code: "hydrate-failed",
+		severity: "error",
+		message: `${name_of(e.fp ?? null)} failed to hydrate: ${e.message.split("\n")[0].slice(0, 160)}.`,
+		refs: e.fp ? [{
+			kind: "island",
+			fp: e.fp
+		}] : []
+	});
+	else if (e.name === "region.hydrate.recovered") findings.push({
+		code: "hydrate-recovered",
+		severity: "error",
+		message: `${name_of(e.fp ?? null)} threw away its server HTML and rendered again${e.reason ? `: ${e.reason}` : ""}.`,
+		refs: e.fp ? [{
+			kind: "island",
+			fp: e.fp
+		}] : []
+	});
+	else if (e.name === "region.hydrate.healed") findings.push({
+		code: "hydrate-healed",
+		severity: "warn",
+		message: `${name_of(e.fp ?? null)}'s markup was changed by another script before it woke; the runtime put the server markup back${e.reason ? ` (${e.reason})` : ""}.`,
+		refs: e.fp ? [{
+			kind: "island",
+			fp: e.fp
+		}] : []
+	});
+	else if (e.name === "region.hydrate.conflict") findings.push({
+		code: "hydrate-conflict",
+		severity: "warn",
+		message: `${name_of(e.fp ?? null)}: ${e.reason ?? "a web component and Svelte wanted the same nodes"}`,
+		refs: e.fp ? [{
+			kind: "island",
+			fp: e.fp
+		}] : []
+	});
+	else if (e.name === "load.critical" && e.outcome === "cap") findings.push({
+		code: "critical-cap",
+		severity: "warn",
+		message: `The page's critical resource${e.resources === 1 ? "" : "s"} (marked fetchpriority="high") took longer than ${e.waited_ms} ms; ogygia stopped holding its downloads back and let them start.`,
+		refs: []
+	});
+	const held = s.events.filter((e) => e.name === "load.started" && e.class !== "user" && e.waited_ms > 0);
+	if (held.length) {
+		const most = Math.max(...held.map((e) => e.name === "load.started" ? e.waited_ms : 0));
+		findings.push({
+			code: "loads-held",
+			severity: "info",
+			message: `ogygia held ${held.length} download${held.length === 1 ? "" : "s"} back (up to ${most} ms) so the page's critical resources and the visible islands went first.`,
+			refs: []
+		});
+	}
+	const errors = s.events.some((e) => e.name === "region.hydrate.failed") ? s.errors.filter((e) => !e.message.startsWith("console.error: [ogygia] hydration failed")) : s.errors;
+	if (errors.length) findings.push({
+		code: "errors",
+		severity: "error",
+		message: `${errors.length} error${errors.length === 1 ? "" : "s"}: ${[...new Set(errors.map((e) => e.message.split("\n")[0].trim()))].slice(0, 3).join(" · ")}.`,
+		refs: []
+	});
+	for (const m of s.mutations.slice(0, 3)) {
+		if (m.count < 300) break;
+		findings.push({
+			code: "dom-churn",
+			severity: "info",
+			message: `${m.fp ? name_of(m.fp) : "Code outside any island"} changed the DOM ${m.count} times during the session${m.fp ? "" : " (page scripts, a third-party tag)"}.`,
+			fix: "Lots of small changes often mean a re-render on every event: batch them, or key the list so unchanged rows stay.",
+			refs: m.fp ? [{
+				kind: "island",
+				fp: m.fp
+			}] : []
+		});
+	}
+	if (s.heap && s.heap.to - s.heap.from >= 5242880) findings.push({
+		code: "heap-growth",
+		severity: "info",
+		message: `The JS heap grew by ${kb(s.heap.to - s.heap.from)} during the session (${kb(s.heap.from)} → ${kb(s.heap.to)}). If it keeps growing across the same actions, something is kept (a listener, a cache, a closed island's state).`,
+		refs: []
+	});
+	for (const e of s.events) {
+		if (e.name !== "nav.finish") continue;
+		if (e.ms >= 500) findings.push({
+			code: "slow-navigation",
+			severity: "info",
+			message: `The navigation to ${e.to} took ${ms(e.ms)}${e.reconciled ? "" : " (a full swap, not reconciled)"}.`,
+			refs: []
+		});
+	}
+	const order = {
+		error: 0,
+		warn: 1,
+		info: 2
+	};
+	findings.sort((a, b) => order[a.severity] - order[b.severity]);
+	return {
+		duration_ms: Math.round(s.to - s.from),
+		counts: {
+			interactions: chosen.length,
+			slow: slow.length,
+			longtasks: s.longtasks.length,
+			longtask_ms: Math.round(lt_ms),
+			requests: s.requests.length,
+			request_bytes: bytes,
+			errors: s.errors.length,
+			shifts: unexpected.length,
+			cls: Math.round(cls * 1e3) / 1e3,
+			mutations: s.mutations.reduce((a, m) => a + m.count, 0),
+			pages: Math.max(1, s.pages?.length ?? 1)
+		},
+		findings,
+		interactions: chosen.map((i) => ({
+			i,
+			t: s.interactions[i].t,
+			name: s.interactions[i].name,
+			duration: s.interactions[i].duration,
+			target: s.interactions[i].target,
+			fp: s.interactions[i].fp
+		})).sort((a, b) => b.duration - a.duration).slice(0, 12),
+		by_island,
+		requests: [...s.requests].filter((r) => r.type === "fetch" || r.type === "xmlhttprequest" || r.server?.length).sort((a, b) => b.ms - a.ms).slice(0, 12).map((r) => ({
+			url: path_of(r.url),
+			ms: r.ms,
+			status: r.status,
+			server_ms: st(r, "ssr")?.ms ?? null,
+			cpu_ms: st(r, "cpu")?.ms ?? null,
+			net_ms: st(r, "net")?.ms ?? null,
+			up: st(r, "up1") ? `${st(r, "up1").desc} ${ms(st(r, "up1").ms)}` : null
+		})),
+		failed: s.requests.filter((r) => r.status !== null && r.status >= 400).map((r) => ({
+			url: r.url,
+			status: r.status,
+			type: r.type,
+			t: r.t
+		})),
+		by_element: Object.values(s.interactions.reduce((acc, x) => {
+			const cur = acc[x.target];
+			if (!cur || x.duration > cur.duration) acc[x.target] = {
+				target: x.target,
+				duration: x.duration,
+				processing: x.processing,
+				t: x.t,
+				fp: x.fp
+			};
+			return acc;
+		}, Object.fromEntries(s.clicks.map((c) => [c.target, {
+			target: c.target,
+			duration: 0,
+			processing: 0,
+			t: c.t,
+			fp: c.fp
+		}])))).sort((a, b) => b.duration - a.duration),
+		cpu
+	};
+}
+export { analyze_session, session_timeline };

package/dist/insights/switch.d.ts

@@ -0,0 +1,53 @@
+/**
+ * THE DEVTOOLS SWITCH — whether devtools is on in this browser, in a BUILD with devtools (a QA or
+ * preview deploy; the dev server always has it on). One cookie decides all of it: the launcher shows,
+ * the page is measured from the start (runtime/beacon.ts), what islands leave running is watched
+ * (leftovers.ts), and the server writes its event side-channel (hooks.ts). Off — the default — a
+ * visitor sees nothing and pays nothing.
+ *
+ * A developer turns it on for their own browser, and it stays on across navigations and reloads:
+ * - `?og-devtools=on` / `?og-devtools=off` on any page (the server sets the cookie on that very
+ *   response, the browser too — a prerendered page has no server — and the address drops the param);
+ * - `ogygia.devtools.on()` / `.off()` in the console;
+ * - "hide" in the dock turns it off.
+ *
+ * (The value is not the `1` an earlier launcher set on a plain click: a browser that clicked the old
+ * button once stays off until it opts in.)
+ *
+ * A plain module: the server, the runtime and the launcher all read it.
+ */
+export declare const DEVTOOLS_COOKIE = "og_devtools";
+export declare const DEVTOOLS_ON = "on";
+/** The URL param that flips it: `?og-devtools=on` / `?og-devtools=off`. */
+export declare const DEVTOOLS_PARAM = "og-devtools";
+/** What the URL asks for: `true` on, `false` off, `null` nothing (absent or another value). */
+export declare function switch_in_url(url: URL): boolean | null;
+/** The URL without the switch param (the address after it was applied). */
+export declare function without_switch(url: URL): URL;
+/** Is it on in a `Cookie` header / `document.cookie` string. */
+export declare function switch_on_in(cookies: string): boolean;
+/**
+ * LEAN TESTING: `og_testing=lean` (or `?og-testing=lean`) beside the devtools switch — the testing API
+ * (`window.__ogygia_testing`) works in full, and nothing else of devtools runs: no launcher, no dock, no
+ * watcher of the page's timers, no server event side-channel in the HTML. The page loads what it loads
+ * with devtools off, plus the testing engine when a test first asks. An engine that does not know the
+ * cookie ignores it.
+ */
+export declare const TESTING_COOKIE = "og_testing";
+export declare const TESTING_LEAN = "lean";
+export declare const TESTING_PARAM = "og-testing";
+/** Is lean testing asked for in a `Cookie` header / `document.cookie` string. */
+export declare function lean_in(cookies: string): boolean;
+/** Lean testing in this browser: the cookie, or the URL param (false off the browser). */
+export declare function testing_lean(): boolean;
+/** The `Set-Cookie`-shaped attributes the switch is written with (browser and server alike). */
+export declare const SWITCH_COOKIE_OPTIONS: {
+  path: string;
+  maxAge: number;
+  sameSite: "lax";
+  httpOnly: boolean;
+};
+/** Is it on in this browser (false off the browser, or with cookies blocked). */
+export declare function devtools_switched_on(): boolean;
+/** Turn it on / off in this browser (the cookie; the caller updates what shows). */
+export declare function write_switch(on: boolean): void;

package/dist/insights/switch.js

@@ -0,0 +1,91 @@
+// src/insights/switch.ts
+/**
+* THE DEVTOOLS SWITCH — whether devtools is on in this browser, in a BUILD with devtools (a QA or
+* preview deploy; the dev server always has it on). One cookie decides all of it: the launcher shows,
+* the page is measured from the start (runtime/beacon.ts), what islands leave running is watched
+* (leftovers.ts), and the server writes its event side-channel (hooks.ts). Off — the default — a
+* visitor sees nothing and pays nothing.
+*
+* A developer turns it on for their own browser, and it stays on across navigations and reloads:
+* - `?og-devtools=on` / `?og-devtools=off` on any page (the server sets the cookie on that very
+*   response, the browser too — a prerendered page has no server — and the address drops the param);
+* - `ogygia.devtools.on()` / `.off()` in the console;
+* - "hide" in the dock turns it off.
+*
+* (The value is not the `1` an earlier launcher set on a plain click: a browser that clicked the old
+* button once stays off until it opts in.)
+*
+* A plain module: the server, the runtime and the launcher all read it.
+*/
+const DEVTOOLS_COOKIE = "og_devtools";
+const DEVTOOLS_ON = "on";
+/** The URL param that flips it: `?og-devtools=on` / `?og-devtools=off`. */
+const DEVTOOLS_PARAM = "og-devtools";
+/** 30 days: a developer flips it once per deploy, not per visit. */
+const MAX_AGE = 2592e3;
+/** What the URL asks for: `true` on, `false` off, `null` nothing (absent or another value). */
+function switch_in_url(url) {
+	const v = url.searchParams.get(DEVTOOLS_PARAM);
+	if (v === null) return null;
+	if (v === "on" || v === "1" || v === "true") return true;
+	if (v === "off" || v === "0" || v === "false") return false;
+	return null;
+}
+/** The URL without the switch param (the address after it was applied). */
+function without_switch(url) {
+	const u = new URL(url);
+	u.searchParams.delete(DEVTOOLS_PARAM);
+	return u;
+}
+/** Is it on in a `Cookie` header / `document.cookie` string. */
+function switch_on_in(cookies) {
+	const want = "og_devtools=on";
+	for (const c of cookies.split(";")) if (c.trim() === want) return true;
+	return false;
+}
+/**
+* LEAN TESTING: `og_testing=lean` (or `?og-testing=lean`) beside the devtools switch — the testing API
+* (`window.__ogygia_testing`) works in full, and nothing else of devtools runs: no launcher, no dock, no
+* watcher of the page's timers, no server event side-channel in the HTML. The page loads what it loads
+* with devtools off, plus the testing engine when a test first asks. An engine that does not know the
+* cookie ignores it.
+*/
+const TESTING_COOKIE = "og_testing";
+const TESTING_LEAN = "lean";
+const TESTING_PARAM = "og-testing";
+/** Is lean testing asked for in a `Cookie` header / `document.cookie` string. */
+function lean_in(cookies) {
+	const want = "og_testing=lean";
+	for (const c of cookies.split(";")) if (c.trim() === want) return true;
+	return false;
+}
+/** Lean testing in this browser: the cookie, or the URL param (false off the browser). */
+function testing_lean() {
+	try {
+		return lean_in(document.cookie) || new URL(location.href).searchParams.get("og-testing") === "lean";
+	} catch {
+		return false;
+	}
+}
+/** The `Set-Cookie`-shaped attributes the switch is written with (browser and server alike). */
+const SWITCH_COOKIE_OPTIONS = {
+	path: "/",
+	maxAge: MAX_AGE,
+	sameSite: "lax",
+	httpOnly: false
+};
+/** Is it on in this browser (false off the browser, or with cookies blocked). */
+function devtools_switched_on() {
+	try {
+		return switch_on_in(document.cookie);
+	} catch {
+		return false;
+	}
+}
+/** Turn it on / off in this browser (the cookie; the caller updates what shows). */
+function write_switch(on) {
+	try {
+		document.cookie = on ? `${DEVTOOLS_COOKIE}=on; path=/; max-age=${MAX_AGE}; samesite=lax` : `${DEVTOOLS_COOKIE}=; path=/; max-age=0; samesite=lax`;
+	} catch {}
+}
+export { DEVTOOLS_COOKIE, DEVTOOLS_ON, DEVTOOLS_PARAM, SWITCH_COOKIE_OPTIONS, TESTING_COOKIE, TESTING_LEAN, TESTING_PARAM, devtools_switched_on, lean_in, switch_in_url, switch_on_in, testing_lean, without_switch, write_switch };