@ogygia/devtools 0.0.0-stage → 0.11.0

package/dist/devtools/since-load.js

@@ -0,0 +1,89 @@
+import { vitals_moved } from "@ogygia/core/insights";
+// src/devtools/since-load.ts
+/**
+* SINCE YOUR LAST LOAD — the dev loop's question: I changed the code and reloaded; what changed?
+* The Page tab keeps a small picture of each page's load (its findings, each island's timings, the
+* vitals and their parts) in session storage as the page goes away, and the next load of the same
+* page is read against it: findings fixed and new, islands that got faster or slower, vitals that
+* moved and the part of each that moved most. Pure (the storage lives in page.ts); a change must
+* clear the noise floor to count. The vitals use the profiler's own rule (page-insights
+* `vitals_moved`): "since your last load" and "since your last profile" never disagree.
+*/
+/** findings a dev server's first compile of the page can raise on its own (its islands' code arrives late) */
+const COMPILE_BORNE = /* @__PURE__ */ new Set([
+	"late-interactive",
+	"slow-module",
+	"queued"
+]);
+/** …and, when the PAGE compiled on its request, everything that waited on its first byte */
+const PAGE_COMPILE_BORNE = /* @__PURE__ */ new Set([
+	...COMPILE_BORNE,
+	"slow-ttfb",
+	"slow-fcp",
+	"slow-lcp",
+	"vital-ttfb",
+	"vital-fcp",
+	"vital-lcp",
+	"render-blocking"
+]);
+/** an island's step moved when it changed by at least this much (and 30%): a module load is noisier
+*  (the network, the dev server compiling), so it needs more */
+const ISLAND_FLOOR_MS = {
+	hydrate: 10,
+	load: 50
+};
+const label = (f) => f.names.length ? `${f.code} (${[...new Set(f.names)].slice(0, 3).join(", ")})` : f.code;
+function since_load(prev, now, at = Date.now()) {
+	if (prev.path !== now.path) return null;
+	const key = (f) => `${f.code}|${[...new Set(f.names)].sort().join(",")}`;
+	const dev = new Set([...prev.findings, ...now.findings].filter((f) => f.dev).map((f) => f.code));
+	const had = new Set(prev.findings.map(key));
+	const has = new Set(now.findings.map(key));
+	const sped = now.islands.filter((i) => {
+		const p = prev.islands.find((x) => x.name === i.name);
+		return p && p.load_ms - i.load_ms >= ISLAND_FLOOR_MS.load && i.load_ms <= p.load_ms * .67;
+	}).length;
+	const all_warmer = now.islands.length >= 2 && sped >= Math.max(2, now.islands.length * .6);
+	const compiled = all_warmer || !!prev.page_compiled || prev.islands.some((i) => (i.compile_ms ?? 0) >= i.load_ms * .5 && i.load_ms >= ISLAND_FLOOR_MS.load);
+	const cold_page = !!prev.page_compiled || all_warmer;
+	const borne = cold_page ? PAGE_COMPILE_BORNE : COMPILE_BORNE;
+	const gone = prev.findings.filter((f) => !has.has(key(f)) && !dev.has(f.code));
+	const fixed = gone.filter((f) => !(compiled && borne.has(f.code))).map(label);
+	const set_aside = gone.length - fixed.length;
+	const added = now.findings.filter((f) => !had.has(key(f)) && !dev.has(f.code)).map(label);
+	const moved = [];
+	const table = (s) => Object.fromEntries(s.vitals.map((v) => [v.key, v.value]));
+	for (const m of vitals_moved(table(prev), table(now), (side, k) => (side === "a" ? prev : now).parts?.[k] ?? null)) if (!(cold_page && (m.key === "ttfb" || m.key === "fcp" || m.key === "lcp")) && !(m.key === "cls" && (prev.cls_dev || now.cls_dev))) moved.push({
+		what: m.key.toUpperCase(),
+		a: m.a,
+		b: m.b,
+		unit: m.key === "cls" ? "" : "ms",
+		better: m.b < m.a,
+		...m.part ? { part: m.part } : {}
+	});
+	for (const i of now.islands) {
+		const p = prev.islands.find((x) => x.name === i.name);
+		if (!p) continue;
+		for (const step of cold_page ? ["hydrate"] : ["hydrate", "load"]) {
+			const was = step === "hydrate" ? p.hydrate_ms : Math.max(0, p.load_ms - (p.compile_ms ?? 0));
+			const is = step === "hydrate" ? i.hydrate_ms : Math.max(0, i.load_ms - (i.compile_ms ?? 0));
+			const d = is - was;
+			if (Math.abs(d) >= ISLAND_FLOOR_MS[step] && Math.abs(d) >= Math.max(was, is) * .3) moved.push({
+				what: `${i.name} ${step}`,
+				a: was,
+				b: is,
+				unit: "ms",
+				better: d < 0
+			});
+		}
+	}
+	moved.sort((x, y) => Math.abs(y.b - y.a) / (Math.abs(y.a) || 1) - Math.abs(x.b - x.a) / (Math.abs(x.a) || 1));
+	return {
+		ago_ms: Math.max(0, at - prev.at),
+		fixed,
+		added,
+		moved: moved.slice(0, 8),
+		...compiled ? { note: `The last load was the dev server compiling this page's code for the first time: ${cold_page ? "its first byte, its paints and its islands' loads are not compared" : "its islands' loads are compared without that"}${set_aside ? `, and what the compile alone raised (${set_aside === 1 ? "one finding" : `${set_aside} findings`}) is not counted as fixed` : ""}.` } : {}
+	};
+}
+export { since_load };

package/dist/devtools/source-lines.d.ts

@@ -0,0 +1,24 @@
+/** served line (1-based) → source line (1-based), or 0 where the line maps nowhere */
+type Lines = Int32Array;
+/**
+ * Each generated line's first segment that names a source → that source line; only segments of the
+ * map's first source (a `.svelte` module maps to itself; helpers it inlined are not its lines).
+ */
+export declare function lines_of_map(mappings: string, want_source?: number): Lines;
+/**
+ * The source line of `line` in the app file `file` (`src/…`, as the CPU view names it). `undefined`
+ * while it is being read, `null` when it cannot be told.
+ */
+export declare function source_line(file: string, line: number | null): number | null | undefined;
+/**
+ * Functions with the source's lines: each mapped where the file's map says, else its line dropped
+ * (a served line is not the source's). `mapped`: every app function among them has its source line.
+ */
+export declare function with_source_lines<F extends {
+  file: string;
+  line: number | null;
+}>(fns: readonly F[]): {
+  fns: F[];
+  mapped: boolean;
+};
+export {};

package/dist/devtools/source-lines.js

@@ -0,0 +1,106 @@
+import { tool_fetch } from "@ogygia/core/internal/instruments";
+// src/devtools/source-lines.ts
+/**
+* THE SOURCE'S LINE FOR A SAMPLED FRAME, IN THE PAGE. The browser's sampler names a frame by the line
+* of the code as served; on the dev server a `.svelte` file is served compiled, so that line is the
+* compiled output's (`save` read as SlowSave.svelte:18, written at line 5). The dev server puts each
+* module's source map inline at its end; this reads it once per file and answers the source line of a
+* served line (its first mapped segment). Asked synchronously: `undefined` while the file is being
+* read (the next look has it), `null` when it cannot say (no inline map: a build's chunk, a file the
+* dev server did not transform). No regex: the map's marker is found by search, the VLQ by table.
+*/
+const MARK = "//# sourceMappingURL=data:application/json;base64,";
+const B64_INDEX = new Map([..."ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"].map((c, i) => [c, i]));
+const ready = /* @__PURE__ */ new Map();
+const pending = /* @__PURE__ */ new Set();
+/**
+* Each generated line's first segment that names a source → that source line; only segments of the
+* map's first source (a `.svelte` module maps to itself; helpers it inlined are not its lines).
+*/
+function lines_of_map(mappings, want_source = 0) {
+	const rows = mappings.split(";");
+	const out = new Int32Array(rows.length + 1);
+	let src = 0;
+	let src_line = 0;
+	for (let r = 0; r < rows.length; r++) {
+		const row = rows[r];
+		let i = 0;
+		let found = 0;
+		while (i < row.length) {
+			const fields = [];
+			while (i < row.length && row[i] !== ",") {
+				let value = 0;
+				let shift = 0;
+				let more = true;
+				while (more && i < row.length) {
+					const digit = B64_INDEX.get(row[i++]) ?? 0;
+					more = (digit & 32) !== 0;
+					value += (digit & 31) << shift;
+					shift += 5;
+				}
+				fields.push(value & 1 ? -(value >> 1) : value >> 1);
+			}
+			i++;
+			if (fields.length >= 4) {
+				src += fields[1];
+				src_line += fields[2];
+				if (!found && src === want_source) found = src_line + 1;
+			}
+		}
+		out[r + 1] = found;
+	}
+	return out;
+}
+/** the served file's source line map, read from its inline map (null when it has none) */
+function parse(text, file) {
+	const at = text.lastIndexOf(MARK);
+	if (at === -1) return null;
+	let end = text.indexOf("\n", at);
+	if (end === -1) end = text.length;
+	try {
+		const map = JSON.parse(atob(text.slice(at + 50, end).trim()));
+		if (typeof map.mappings !== "string" || !Array.isArray(map.sources)) return null;
+		const base = file.slice(file.lastIndexOf("/") + 1);
+		const own = map.sources.findIndex((s) => typeof s === "string" && s.slice(s.lastIndexOf("/") + 1) === base);
+		return lines_of_map(map.mappings, own === -1 ? 0 : own);
+	} catch {
+		return null;
+	}
+}
+/**
+* The source line of `line` in the app file `file` (`src/…`, as the CPU view names it). `undefined`
+* while it is being read, `null` when it cannot be told.
+*/
+function source_line(file, line) {
+	if (line === null || !file.startsWith("src/")) return null;
+	const hit = ready.get(file);
+	if (hit === null) return null;
+	if (hit) return hit[line] || null;
+	if (!pending.has(file) && typeof fetch === "function") {
+		pending.add(file);
+		tool_fetch("/" + file).then((r) => r.ok ? r.text() : "").then((t) => ready.set(file, t ? parse(t, file) : null)).catch(() => ready.set(file, null)).finally(() => pending.delete(file));
+	}
+}
+/**
+* Functions with the source's lines: each mapped where the file's map says, else its line dropped
+* (a served line is not the source's). `mapped`: every app function among them has its source line.
+*/
+function with_source_lines(fns) {
+	let mapped = true;
+	return {
+		fns: fns.map((f) => {
+			const l = source_line(f.file, f.line);
+			if (l) return {
+				...f,
+				line: l
+			};
+			if (f.file.startsWith("src/")) mapped = false;
+			return {
+				...f,
+				line: null
+			};
+		}),
+		mapped
+	};
+}
+export { lines_of_map, source_line, with_source_lines };

package/dist/devtools/styles.d.ts

@@ -0,0 +1,52 @@
+import { UnscopedStyles } from "@ogygia/core/internal/instruments";
+export interface SheetRow {
+  /** the file name, or `inline <style>` */
+  label: string;
+  href: string | null;
+  rules: number;
+  /** decoded bytes: the response's (resource timing) or the inline text's */
+  bytes: number;
+  /** the browser waited on it before the first paint (resource timing's own verdict) */
+  blocking: boolean;
+  /** rules whose selectors match nothing on the page now (null until checked) */
+  unmatched: number | null;
+  /** their text's size, a stand-in for the bytes they cost */
+  unmatched_bytes: number | null;
+  /** a region / router stylesheet ogygia linked */
+  ogygia: boolean;
+}
+export interface StylesReport {
+  sheets: SheetRow[];
+  rules: number;
+  bytes: number;
+  unmatched: number;
+  unmatched_bytes: number;
+  /** examples of selectors that match nothing, biggest rules first */
+  examples: string[];
+  unscoped: (UnscopedStyles & {
+    sheet: string;
+  })[];
+  /** sheets whose rules could not be read (another origin without CORS) */
+  unreadable: number;
+}
+export interface StylesFinding {
+  code: string;
+  severity: "warn" | "info";
+  message: string;
+  fix?: string;
+}
+/** Split a selector list on its top-level commas (`:is(a, b)` stays whole). */
+export declare function split_selectors(list: string): string[];
+/** A selector with its pseudo-elements and momentary states taken off, ready to try against the
+ *  document. `''` when nothing is left to match (a bare `::selection`): that one counts as used. */
+export declare function matchable(sel: string): string;
+/** Read the page's stylesheets. `match: true` also tries every selector against the document. */
+export declare function read_styles(doc?: Document, opts?: {
+  match?: boolean;
+}): StylesReport;
+/** The build's unscoped-fallback markers in the page's sheets. Inline sheets read their node's
+ *  text; linked ones one same-origin fetch each (the HTTP cache answers it). */
+export declare function scan_unscoped(doc?: Document): Promise<(UnscopedStyles & {
+  sheet: string;
+})[]>;
+export declare function styles_findings(s: StylesReport): StylesFinding[];

package/dist/devtools/styles.js

@@ -0,0 +1,248 @@
+import { find_unscoped, paint_blocker, tool_fetch, tool_made, unscoped_finding } from "@ogygia/core/internal/instruments";
+// src/devtools/styles.ts
+/**
+* THE PAGE'S STYLES, as the browser holds them: every stylesheet (linked or inline), its rules,
+* its size, whether it held the first paint, and two things only the live page can answer:
+*
+* - **unscoped components**: the build marks a component whose scoped CSS it could not compile
+*   (unscoped-css.ts). Its rules then apply page-wide. The CSSOM drops comments, so the marker is
+*   read from the sheet's text (inline: the node; linked: one fetch, from the HTTP cache).
+* - **rules that match nothing here**: each style rule's selector, with states and pseudo-elements
+*   taken off (`:hover`, `::before`), tried against the document. Content that appears later (a
+*   menu, a dialog, an island not yet rendered) counts as matching nothing, so it is a hint.
+*
+* Devtools' own UI lives in a shadow root and never shows here. Runs on demand (the Page tab), not
+* on a hot path.
+*/
+const STATES = [
+	":hover",
+	":focus-visible",
+	":focus-within",
+	":focus",
+	":active",
+	":visited",
+	":target",
+	":open",
+	":popover-open",
+	":modal",
+	":user-invalid",
+	":user-valid",
+	":autofill"
+];
+/** Split a selector list on its top-level commas (`:is(a, b)` stays whole). */
+function split_selectors(list) {
+	const out = [];
+	let depth = 0;
+	let from = 0;
+	for (let i = 0; i < list.length; i++) {
+		const c = list[i];
+		if (c === "(" || c === "[") depth++;
+		else if (c === ")" || c === "]") depth--;
+		else if (c === "," && depth === 0) {
+			out.push(list.slice(from, i).trim());
+			from = i + 1;
+		}
+	}
+	out.push(list.slice(from).trim());
+	return out.filter(Boolean);
+}
+/** A selector with its pseudo-elements and momentary states taken off, ready to try against the
+*  document. `''` when nothing is left to match (a bare `::selection`): that one counts as used. */
+function matchable(sel) {
+	let s = sel;
+	let at = s.indexOf("::");
+	while (at !== -1) {
+		let end = at + 2;
+		let depth = 0;
+		while (end < s.length) {
+			const c = s[end];
+			if (c === "(") depth++;
+			else if (c === ")") depth--;
+			else if (depth === 0 && (c === " " || c === ">" || c === "+" || c === "~" || c === ",")) break;
+			end++;
+		}
+		s = s.slice(0, at) + s.slice(end);
+		at = s.indexOf("::");
+	}
+	for (const st of STATES) {
+		let i = s.indexOf(st);
+		while (i !== -1) {
+			const next = s[i + st.length];
+			if (next === void 0 || !(next === "-" || next >= "a" && next <= "z")) s = s.slice(0, i) + s.slice(i + st.length);
+			else i += st.length;
+			i = s.indexOf(st, i);
+		}
+	}
+	s = s.trim();
+	while (s.endsWith(">") || s.endsWith("+") || s.endsWith("~")) s = s.slice(0, -1).trim();
+	return s;
+}
+function file_of(href) {
+	const path = href.split("?")[0].split("#")[0];
+	return path.slice(path.lastIndexOf("/") + 1) || href;
+}
+/** Devtools' own component styles: on the dev server Vite injects them into the page's <head>
+*  (the panel's markup lives in a shadow root, so every one of their rules matches nothing here). */
+function own_sheet(node) {
+	const id = node?.getAttribute("data-vite-dev-id");
+	return !!id && (id.includes("ogygia") || id.includes("/devtools/src/devtools/")) && id.includes("/devtools/");
+}
+/** A sheet that styles the devtools panel and nothing on the page: in a build the panel's CSS is a
+*  linked file in the document, whatever its name. Its rules match inside the panel's shadow root
+*  and never in the document. Every rule is tried (which of the panel's parts are showing depends
+*  on its open tab), stopping at the first one the page itself uses. */
+function styles_the_panel(rules, doc, panel) {
+	if (!panel) return false;
+	let in_panel = false;
+	let stop = false;
+	each_style_rule(rules, (rule) => {
+		if (stop) return;
+		for (const part of split_selectors(rule.selectorText)) {
+			const m = matchable(part);
+			if (!m) continue;
+			try {
+				if (doc.querySelector(m)) {
+					stop = true;
+					in_panel = false;
+					return;
+				}
+				if (panel.querySelector(m)) in_panel = true;
+			} catch {}
+		}
+	});
+	return in_panel;
+}
+function each_style_rule(list, fn) {
+	for (let i = 0; i < list.length; i++) {
+		const r = list[i];
+		if ("selectorText" in r) fn(r);
+		const inner = r.cssRules;
+		if (inner && inner.length) each_style_rule(inner, fn);
+	}
+}
+/** Read the page's stylesheets. `match: true` also tries every selector against the document. */
+function read_styles(doc = document, opts = {}) {
+	const res = /* @__PURE__ */ new Map();
+	for (const e of performance.getEntriesByType("resource")) if (!tool_made(e)) res.set(e.name, e);
+	const sheets = [];
+	const examples = [];
+	let unreadable = 0;
+	const blocks = paint_blocker();
+	const panel = doc.querySelector("[data-ogygia-devtools-host]")?.shadowRoot;
+	for (const sheet of Array.from(doc.styleSheets)) {
+		const node = sheet.ownerNode;
+		if (own_sheet(node)) continue;
+		const href = sheet.href;
+		let rules;
+		try {
+			rules = sheet.cssRules;
+		} catch {
+			unreadable++;
+			continue;
+		}
+		if (styles_the_panel(rules, doc, panel)) continue;
+		const r = href ? res.get(href) : void 0;
+		const row = {
+			label: href ? file_of(href) : node?.getAttribute("data-vite-dev-id") ? file_of(node.getAttribute("data-vite-dev-id")) : "inline <style>",
+			href,
+			rules: 0,
+			bytes: href ? r?.decodedBodySize ?? 0 : node?.textContent?.length ?? 0,
+			blocking: !!r && blocks(r),
+			unmatched: opts.match ? 0 : null,
+			unmatched_bytes: opts.match ? 0 : null,
+			ogygia: !!node && (node.hasAttribute("data-ogygia-region-css") || node.hasAttribute("data-ogygia-rcss") || (href ?? "").includes("og-rcss"))
+		};
+		each_style_rule(rules, (rule) => {
+			row.rules++;
+			if (!opts.match) return;
+			const text = rule.selectorText;
+			if (text.includes("&")) return;
+			let hit = false;
+			for (const part of split_selectors(text)) {
+				const m = matchable(part);
+				if (!m) {
+					hit = true;
+					break;
+				}
+				try {
+					if (doc.querySelector(m)) {
+						hit = true;
+						break;
+					}
+				} catch {
+					hit = true;
+					break;
+				}
+			}
+			if (!hit) {
+				row.unmatched++;
+				const len = rule.cssText.length;
+				row.unmatched_bytes += len;
+				examples.push({
+					sel: text,
+					len
+				});
+			}
+		});
+		sheets.push(row);
+	}
+	const sum = (k) => sheets.reduce((s, x) => s + (x[k] ?? 0), 0);
+	examples.sort((a, b) => b.len - a.len);
+	return {
+		sheets: sheets.sort((a, b) => b.bytes - a.bytes),
+		rules: sum("rules"),
+		bytes: sum("bytes"),
+		unmatched: sum("unmatched"),
+		unmatched_bytes: sum("unmatched_bytes"),
+		examples: [...new Set(examples.map((e) => e.sel))].slice(0, 6),
+		unscoped: [],
+		unreadable
+	};
+}
+/** The build's unscoped-fallback markers in the page's sheets. Inline sheets read their node's
+*  text; linked ones one same-origin fetch each (the HTTP cache answers it). */
+async function scan_unscoped(doc = document) {
+	const out = [];
+	const add = (css, sheet) => {
+		for (const u of find_unscoped(css)) if (!out.some((x) => x.file === u.file)) out.push({
+			...u,
+			sheet
+		});
+	};
+	const jobs = [];
+	for (const sheet of Array.from(doc.styleSheets)) {
+		const node = sheet.ownerNode;
+		if (own_sheet(node)) continue;
+		if (!sheet.href) {
+			if (node?.textContent) add(node.textContent, "inline <style>");
+			continue;
+		}
+		const href = sheet.href;
+		if (new URL(href, location.href).origin !== location.origin) continue;
+		jobs.push(tool_fetch(href, { cache: "force-cache" }).then((r) => r.ok ? r.text() : "").then((css) => add(css, file_of(href))).catch(() => {}));
+	}
+	await Promise.all(jobs);
+	return out;
+}
+function styles_findings(s) {
+	const out = [];
+	if (s.unscoped.length) {
+		const f = unscoped_finding(s.unscoped);
+		out.push({
+			...f,
+			severity: "warn"
+		});
+	}
+	if (s.unmatched_bytes >= 20480 && s.rules && s.unmatched / s.rules >= .5) {
+		const kb = Math.round(s.unmatched_bytes / 1024);
+		const worst = s.sheets.filter((x) => (x.unmatched_bytes ?? 0) > 0).sort((a, b) => (b.unmatched_bytes ?? 0) - (a.unmatched_bytes ?? 0)).slice(0, 3);
+		out.push({
+			code: "css-unmatched",
+			severity: "info",
+			message: `${Math.floor(s.unmatched / s.rules * 100)}% of the page's CSS rules (${s.unmatched} of ${s.rules}, about ${kb} KB of rule text) match nothing on it right now. Most in: ${worst.map((w) => `${w.label} ${w.unmatched} rules`).join(", ")}.`,
+			fix: "Styles in a component's own <style> load with that component. Move page-specific rules there, or split a big shared sheet by route. Menus, dialogs and content that appears later count as unmatched here: open them and check again."
+		});
+	}
+	return out;
+}
+export { matchable, read_styles, scan_unscoped, split_selectors, styles_findings };

package/dist/devtools/testing-engine.d.ts

@@ -0,0 +1,83 @@
+import { PageView } from "./page.js";
+import { hydration_report } from "./hydration.js";
+import { AttrRule, CpuSummary, PageFinding, PageReport, SessionFinding, SessionReport, TimelineItem, TimelineLane } from "@ogygia/core/insights";
+import { AttrChange, BeaconPage } from "@ogygia/core/internal/instruments";
+type EngineStamp = {
+  version: number;
+  lean: boolean;
+};
+type HydrationIsland = ReturnType<typeof hydration_report>["islands"][number];
+export declare function note_engine_files(from: number, to: number): void;
+/** What ogygia's measuring cost this page, for a test to subtract: the main-thread time of its own work
+ *  (checking islands as they hydrate, building the visit, the testing reports — runtime/own-cost.ts)
+ *  and the decoded bytes of the testing engine's files. No visitor with devtools off pays either. */
+declare function self_cost(): {
+  script_ms: number;
+  bytes: number;
+  phases: Record<string, number>;
+};
+export declare function page_json(cpu_fns?: number): Promise<{
+  url: string;
+  route: string | null;
+  nav: PageView["nav"];
+  vitals: PageReport["vitals"];
+  islands: PageReport["rows"];
+  findings: (PageFinding & {
+    names: string[];
+  })[];
+  blocking: PageReport["blocking"];
+  bytes: PageReport["bytes"];
+  longtask_ms: number;
+  cpu: Pick<CpuSummary, "busy_ms" | "by_kind" | "fns"> | null;
+  cpu_state: BeaconPage["cpu"]["state"];
+  cpu_off: string | null;
+  unmeasured: string[];
+  self: ReturnType<typeof self_cost>;
+  engine: EngineStamp;
+} | null>;
+/** Each island's report, keyed per INSTANCE: the value of `key_attr` on the island or its NEAREST
+ *  ancestor that has it, across shadow roots (an id the app renders, e.g. its CMS block's), else
+ *  `Name#n`, the n-th island of that name in document order. Two islands under the same keyed
+ *  element are told apart as `key`, `key#2`, … in document order. */
+export declare function hydration_json(key_attr?: string, ignore?: AttrRule[]): Promise<{
+  measured: boolean;
+  engine: EngineStamp;
+  islands: ((HydrationIsland | (Omit<HydrationIsland, "attributes"> & {
+    attributes: AttrChange[];
+    ignored: AttrChange[];
+  }) | (Omit<HydrationIsland, "status" | "attributesOnly" | "attributes" | "diff"> & {
+    status: "clean";
+    attributesOnly: boolean;
+    attributes: null;
+    diff: null;
+    ignored: AttrChange[];
+  })) & {
+    key: string;
+  })[];
+}>;
+export declare function record_start(): boolean;
+/** A navigation the test's driver blocked during the recording: where it went, when (page clock). */
+export interface BlockedNavigation {
+  url: string;
+  t: number | null;
+}
+export declare function record_stop(blocked?: BlockedNavigation[]): Promise<(Omit<SessionReport, "findings"> & {
+  findings: (SessionFinding & {
+    names: string[];
+  })[];
+  navigations: {
+    url: string;
+    t: number | null;
+    after: string | null;
+    island: string | null;
+    approx: boolean;
+  }[];
+  engine: EngineStamp;
+  timeline: (Omit<TimelineLane, "items"> & {
+    items: Omit<TimelineItem, "ref">[];
+  })[];
+  unmeasured: string[];
+}) | null>;
+/** Resolves when no island is mid-hydration and nothing woke for `quiet` ms (or `timeout` passed). */
+export declare function settled(quiet?: number, timeout?: number): Promise<boolean>;
+export {};