@ogygia/core 0.0.0 → 0.11.1

package/dist/insights/html-diff.js

@@ -0,0 +1,157 @@
+// src/insights/html-diff.ts
+/** Tags and text runs; comments out; whitespace inside text folded to one space. */
+function tokenize(html) {
+	const out = [];
+	let i = 0;
+	while (i < html.length) {
+		if (html.startsWith("<!--", i)) {
+			const end = html.indexOf("-->", i + 4);
+			i = end === -1 ? html.length : end + 3;
+			continue;
+		}
+		if (html[i] === "<") {
+			const end = html.indexOf(">", i);
+			const stop = end === -1 ? html.length : end + 1;
+			out.push(html.slice(i, stop));
+			i = stop;
+			continue;
+		}
+		const next = html.indexOf("<", i);
+		const stop = next === -1 ? html.length : next;
+		let text = "";
+		let space = false;
+		for (let k = i; k < stop; k++) {
+			const c = html.charCodeAt(k);
+			if (c === 32 || c === 9 || c === 10 || c === 13) space = true;
+			else {
+				if (space && text) text += " ";
+				space = false;
+				text += html[k];
+			}
+		}
+		if (text) out.push(text);
+		i = stop;
+	}
+	return out;
+}
+/** Myers diff over token arrays; null when the edit distance passes `max_d`. */
+function myers(a, b, max_d) {
+	const n = a.length;
+	const m = b.length;
+	const max = Math.min(n + m, max_d);
+	const off = max + 1;
+	const v = new Int32Array(2 * max + 3);
+	const trace = [];
+	for (let d = 0; d <= max; d++) {
+		trace.push(v.slice());
+		for (let k = -d; k <= d; k += 2) {
+			let x = k === -d || k !== d && v[off + k - 1] < v[off + k + 1] ? v[off + k + 1] : v[off + k - 1] + 1;
+			let y = x - k;
+			while (x < n && y < m && a[x] === b[y]) {
+				x++;
+				y++;
+			}
+			v[off + k] = x;
+			if (x >= n && y >= m) {
+				const ops = [];
+				let cx = n;
+				let cy = m;
+				for (let dd = d; dd > 0; dd--) {
+					const pv = trace[dd];
+					const kk = cx - cy;
+					const prev_k = kk === -dd || kk !== dd && pv[off + kk - 1] < pv[off + kk + 1] ? kk + 1 : kk - 1;
+					const px = pv[off + prev_k];
+					const py = px - prev_k;
+					while (cx > px && cy > py) {
+						ops.push({
+							op: "same",
+							text: a[--cx]
+						});
+						cy--;
+					}
+					if (cx === px) ops.push({
+						op: "add",
+						text: b[--cy]
+					});
+					else ops.push({
+						op: "del",
+						text: a[--cx]
+					});
+				}
+				while (cx > 0 && cy > 0) {
+					ops.push({
+						op: "same",
+						text: a[--cx]
+					});
+					cy--;
+				}
+				return ops.reverse();
+			}
+		}
+	}
+	return null;
+}
+function html_diff(server, browser, context = 3, max_d = 800) {
+	const a = tokenize(server);
+	const b = tokenize(browser);
+	let head = 0;
+	while (head < a.length && head < b.length && a[head] === b[head]) head++;
+	let tail = 0;
+	while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) tail++;
+	const mid_a = a.slice(head, a.length - tail);
+	const mid_b = b.slice(head, b.length - tail);
+	let ops = myers(mid_a, mid_b, max_d);
+	let partial = false;
+	if (!ops) {
+		partial = true;
+		ops = [...mid_a.slice(0, 20).map((text) => ({
+			op: "del",
+			text
+		})), ...mid_b.slice(0, 20).map((text) => ({
+			op: "add",
+			text
+		}))];
+	}
+	const all = [
+		...a.slice(Math.max(0, head - context), head).map((text) => ({
+			op: "same",
+			text
+		})),
+		...ops,
+		...a.slice(a.length - tail, a.length - tail + context).map((text) => ({
+			op: "same",
+			text
+		}))
+	];
+	const hunks = [];
+	let cur = null;
+	let same_run = 0;
+	for (let i = 0; i < all.length; i++) {
+		const o = all[i];
+		if (o.op === "same") {
+			if (cur) {
+				same_run++;
+				if (same_run <= context) cur.push(o);
+				else {
+					hunks.push({ ops: cur });
+					cur = null;
+				}
+			}
+			continue;
+		}
+		if (!cur) {
+			cur = [];
+			for (let k = Math.max(0, i - context); k < i; k++) if (all[k].op === "same") cur.push(all[k]);
+		}
+		same_run = 0;
+		cur.push(o);
+	}
+	if (cur) hunks.push({ ops: cur });
+	return {
+		hunks: hunks.slice(0, 20),
+		removed: ops.filter((o) => o.op === "del").length,
+		added: ops.filter((o) => o.op === "add").length,
+		partial
+	};
+}
+export { html_diff, tokenize };

package/dist/insights/hydration-hazards.d.ts

@@ -0,0 +1,36 @@
+/**
+ * WHAT DRAWS DIFFERENTLY IN THE BROWSER: the lines of a `.svelte` component that make its first
+ * browser render differ from the server's — the cause a hydration mismatch (Svelte threw the server
+ * DOM away) or a markup change on wake most often has, named by line:
+ *
+ * - `await`: an `await` at the top level of the instance script (an async component: the browser
+ *   awaits again, and another answer — or a fetch the browser cannot make — draws another tree);
+ * - `browser`: a value only the browser has, read while rendering — `typeof window`, `window.` /
+ *   `document.` / `navigator.` / `localStorage` / `sessionStorage`, `Date.now()`, `new Date()`,
+ *   `Math.random()`, `matchMedia(` — in the markup, or at the top level of the script (a `$derived`,
+ *   a `const`), never inside a function, an effect or an event handler (those run after the wake).
+ *
+ * String scanning, line by line (no regex, no parser): brace depth tells the top level of the
+ * script; a markup line's handler attributes (`onclick={…}`) are left out.
+ */
+export interface Hazard {
+  line: number;
+  /** the line, trimmed */
+  code: string;
+  kind: "await" | "browser";
+  /** what it reads (`window.location`, `Date.now()`), for `browser` */
+  reads?: string;
+  /** an `if (…)` at the script's top level: a guard around browser-only work, which may draw the
+   *  same markup both sides — a lead for a mismatch seen, not a prediction of one */
+  guard?: true;
+}
+/** a hazard with the file it is in (the profiler's island chunks, the dev server's module graph) */
+export type IslandHazard = Hazard & {
+  file: string;
+};
+/** "In its own code, the likeliest: X.svelte:4 (`…`) awaits …; Y.svelte:8 reads Date.now( while rendering …" —
+ *  said the same by the profiler's report and the devtools' Page tab */
+export declare function hazard_words(lines: readonly IslandHazard[]): string;
+/** The fix for those lines: what to do with each kind. */
+export declare function hazard_fix(lines: readonly IslandHazard[]): string;
+export declare function hydration_hazards(source: string): Hazard[];

package/dist/insights/hydration-hazards.js

@@ -0,0 +1,136 @@
+// src/insights/hydration-hazards.ts
+/** "In its own code, the likeliest: X.svelte:4 (`…`) awaits …; Y.svelte:8 reads Date.now( while rendering …" —
+*  said the same by the profiler's report and the devtools' Page tab */
+function hazard_words(lines) {
+	const one = (h) => {
+		const code = h.code.length > 70 ? h.code.slice(0, 69) + "…" : h.code;
+		const where = `${h.file.split("/").pop()}:${h.line} (\`${code}\`)`;
+		return h.kind === "await" ? `${where} awaits at the top of its script: the browser runs it again, and another answer draws another tree` : `${where} reads ${h.reads ?? "a browser-only value"} while rendering, a value the server does not have`;
+	};
+	return `In its own code, the likeliest: ${lines.slice(0, 2).map(one).join("; ")}.`;
+}
+/** The fix for those lines: what to do with each kind. */
+function hazard_fix(lines) {
+	const kinds = new Set(lines.map((h) => h.kind));
+	return [...kinds.has("await") ? ["Give both sides the same answer: pass the data in from the server (a load, a prop) rather than awaiting it again in the browser."] : [], ...kinds.has("browser") ? ["Read the browser-only value after the wake (in `$effect` or `onMount`), or take it from what both sides have (the page's URL from `$app/state`, a time passed in as a prop)."] : []].join(" ");
+}
+const BROWSER_READS = [
+	"typeof window",
+	"window.",
+	"document.",
+	"navigator.",
+	"localStorage",
+	"sessionStorage",
+	"Date.now(",
+	"new Date()",
+	"Math.random(",
+	"matchMedia("
+];
+const is_ident = (c) => c >= 48 && c <= 57 || c >= 65 && c <= 90 || c >= 97 && c <= 122 || c === 95 || c === 36;
+/** The first browser-only read on a stretch of code, or undefined. */
+function browser_read(code) {
+	for (const r of BROWSER_READS) {
+		const at = code.indexOf(r);
+		if (at === -1) continue;
+		if (at > 0 && is_ident(code.charCodeAt(at - 1))) continue;
+		if (r === "typeof window" || r.endsWith("(") || r === "localStorage" || r === "sessionStorage") return r;
+		let end = at + r.length;
+		while (end < code.length && is_ident(code.charCodeAt(end))) end++;
+		return code.slice(at, end);
+	}
+}
+/** A markup line without its event-handler attributes (`onclick={() => window.scrollTo(0, 0)}`). */
+function without_handlers(line) {
+	let out = "";
+	let i = 0;
+	while (i < line.length) {
+		const at = line.indexOf("on", i);
+		if (at === -1) break;
+		const prev = at > 0 ? line[at - 1] : " ";
+		let j = at + 2;
+		while (j < line.length && (line[j] >= "a" && line[j] <= "z" || line[j] === ":")) j++;
+		if ((prev === " " || prev === "	") && j > at + 2 && line[j] === "=" && line[j + 1] === "{") {
+			out += line.slice(i, at);
+			let depth = 0;
+			let k = j + 1;
+			for (; k < line.length; k++) if (line[k] === "{") depth++;
+			else if (line[k] === "}" && --depth === 0) break;
+			i = k + 1;
+			continue;
+		}
+		out += line.slice(i, at + 2);
+		i = at + 2;
+	}
+	return out + line.slice(i);
+}
+function hydration_hazards(source) {
+	const out = [];
+	const lines = source.split("\n");
+	let in_script = false;
+	let module_script = false;
+	let in_style = false;
+	let depth = 0;
+	let deferred_depth = -1;
+	let arrow_body = false;
+	for (let n = 0; n < lines.length; n++) {
+		const line = lines[n].trim();
+		if (!in_script && !in_style && line.startsWith("<script")) {
+			in_script = !line.includes("<\/script>");
+			module_script = line.includes("module");
+			depth = 0;
+			deferred_depth = -1;
+			continue;
+		}
+		if (in_script && line.startsWith("<\/script")) {
+			in_script = false;
+			continue;
+		}
+		if (!in_script && line.startsWith("<style")) {
+			in_style = !line.includes("</style>");
+			continue;
+		}
+		if (in_style) {
+			if (line.startsWith("</style")) in_style = false;
+			continue;
+		}
+		if (in_script) {
+			const in_arrow_body = arrow_body;
+			if (arrow_body && (line.endsWith(";") || line === "")) arrow_body = false;
+			if (!in_arrow_body && line.endsWith("=>")) arrow_body = true;
+			if (depth === 0 && deferred_depth === -1 && !module_script && !in_arrow_body && !line.startsWith("//") && !line.startsWith("*") && !line.startsWith("/*")) {
+				const aw = line.indexOf("await ");
+				if (aw !== -1 && (aw === 0 || !is_ident(line.charCodeAt(aw - 1)))) out.push({
+					line: n + 1,
+					code: line,
+					kind: "await"
+				});
+				else if (!line.startsWith("import ") && !line.startsWith("function ") && !line.startsWith("export function ")) {
+					const reads = browser_read(line);
+					if (reads) out.push({
+						line: n + 1,
+						code: line,
+						kind: "browser",
+						reads,
+						...line.startsWith("if (") || line.startsWith("if(") ? { guard: true } : {}
+					});
+				}
+			}
+			if (deferred_depth === -1 && (line.includes("onMount(") || line.includes("$effect(") || line.includes("function") || line.includes("=>")) && !line.startsWith("const ") && !line.startsWith("let ")) deferred_depth = depth;
+			else if (deferred_depth === -1 && (line.startsWith("const ") || line.startsWith("let ")) && line.includes("=>") && line.includes("{")) deferred_depth = depth;
+			for (const ch of line) if (ch === "{") depth++;
+			else if (ch === "}") depth--;
+			if (deferred_depth !== -1 && depth <= deferred_depth) deferred_depth = -1;
+			continue;
+		}
+		if (!line.includes("{")) continue;
+		const reads = browser_read(without_handlers(line));
+		if (reads) out.push({
+			line: n + 1,
+			code: line,
+			kind: "browser",
+			reads
+		});
+	}
+	return out;
+}
+export { hazard_fix, hazard_words, hydration_hazards };

package/dist/insights/hydration-status.d.ts

@@ -0,0 +1,2 @@
+/** An island's hydration status: worked out in the browser (devtools/hydration.ts), read by the testing API. */
+export type HydrationStatus = "failed" | "recovered" | "healed" | "changed" | "asleep" | "clean";

package/dist/insights/index.d.ts

@@ -0,0 +1,14 @@
+import { DOM_LARGE, Failure, HeldOpen, HoleBatch, HoleFailure, HoleWait, InteractionCpuInput, IslandCode, IslandRow, NavPhases, PageFinding, PageInput, PageInteraction, PageNav, PageReport, PartedVital, RatedVital, RegionFact, RestoreEvent, ServerProfileBrief, VitalMove, VitalPart, analyze_page, browser_of, defer_keys, dev_compile_ms, engine_of, explain_held_open, first_difference, inline_threshold_tune, late_found, lcp_font, lcp_rivals, prebundled_names, rate, vital_parts, vitals_moved } from "./page-insights.js";
+import { Ref, SessionFinding, SessionReport, TimelineItem, TimelineLane, analyze_session, session_timeline } from "./session-insights.js";
+import { SessionClick, SessionData, SessionFrame, SessionInteraction, SessionNav, SessionRequest, SessionShift } from "./session-data.js";
+import { HydrationStatus } from "./hydration-status.js";
+import { HtmlDiff, html_diff } from "./html-diff.js";
+import { AssetKind, AssetRef, AssetsDiff, PageAssets, RuntimeScripts, Weight, assets_diff, dynamic_imports, runtime_scripts, static_imports, weigh_assets } from "./page-assets.js";
+import { CodeKind, CpuFn, CpuSummary, analyze_cpu, is_trace } from "./cpu.js";
+import { FpDrift, KeptIsland, compare } from "./fp-drift.js";
+import { HOLE_SEG_LABEL, hole_segments } from "./hole-segments.js";
+import { IslandHazard, hazard_fix, hazard_words, hydration_hazards } from "./hydration-hazards.js";
+import { AttrRule, apply_attr_rules } from "./attr-rules.js";
+import { DEVTOOLS_COOKIE, DEVTOOLS_ON, DEVTOOLS_PARAM, TESTING_COOKIE, TESTING_LEAN, TESTING_PARAM, devtools_switched_on, switch_in_url, testing_lean, without_switch, write_switch } from "./switch.js";
+import { TESTING_ENGINE_VERSION } from "./testing-version.js";
+export { type AssetKind, type AssetRef, type AssetsDiff, type AttrRule, type CodeKind, type CpuFn, type CpuSummary, DEVTOOLS_COOKIE, DEVTOOLS_ON, DEVTOOLS_PARAM, DOM_LARGE, type Failure, type FpDrift, HOLE_SEG_LABEL, type HeldOpen, type HoleBatch, type HoleFailure, type HoleWait, type HtmlDiff, type HydrationStatus, type InteractionCpuInput, type IslandCode, type IslandHazard, type IslandRow, type KeptIsland, type NavPhases, type PageAssets, type PageFinding, type PageInput, type PageInteraction, type PageNav, type PageReport, type PartedVital, type RatedVital, type Ref, type RegionFact, type RestoreEvent, type RuntimeScripts, type ServerProfileBrief, type SessionClick, type SessionData, type SessionFinding, type SessionFrame, type SessionInteraction, type SessionNav, type SessionReport, type SessionRequest, type SessionShift, TESTING_COOKIE, TESTING_ENGINE_VERSION, TESTING_LEAN, TESTING_PARAM, type TimelineItem, type TimelineLane, type VitalMove, type VitalPart, type Weight, analyze_cpu, analyze_page, analyze_session, apply_attr_rules, assets_diff, browser_of, defer_keys, dev_compile_ms, devtools_switched_on, dynamic_imports, engine_of, explain_held_open, first_difference, compare as fp_compare, hazard_fix, hazard_words, hole_segments, html_diff, hydration_hazards, inline_threshold_tune, is_trace, late_found, lcp_font, lcp_rivals, prebundled_names, rate, runtime_scripts, session_timeline, static_imports, switch_in_url, testing_lean, vital_parts, vitals_moved, weigh_assets, without_switch, write_switch };

package/dist/insights/index.js

@@ -0,0 +1,12 @@
+import { DOM_LARGE, analyze_page, browser_of, defer_keys, dev_compile_ms, engine_of, explain_held_open, first_difference, inline_threshold_tune, late_found, lcp_font, lcp_rivals, prebundled_names, rate, vital_parts, vitals_moved } from "./page-insights.js";
+import { analyze_session, session_timeline } from "./session-insights.js";
+import { html_diff } from "./html-diff.js";
+import { assets_diff, dynamic_imports, runtime_scripts, static_imports, weigh_assets } from "./page-assets.js";
+import { analyze_cpu, is_trace } from "./cpu.js";
+import { compare } from "./fp-drift.js";
+import { HOLE_SEG_LABEL, hole_segments } from "./hole-segments.js";
+import { hazard_fix, hazard_words, hydration_hazards } from "./hydration-hazards.js";
+import { apply_attr_rules } from "./attr-rules.js";
+import { DEVTOOLS_COOKIE, DEVTOOLS_ON, DEVTOOLS_PARAM, TESTING_COOKIE, TESTING_LEAN, TESTING_PARAM, devtools_switched_on, switch_in_url, testing_lean, without_switch, write_switch } from "./switch.js";
+import { TESTING_ENGINE_VERSION } from "./testing-version.js";
+export { DEVTOOLS_COOKIE, DEVTOOLS_ON, DEVTOOLS_PARAM, DOM_LARGE, HOLE_SEG_LABEL, TESTING_COOKIE, TESTING_ENGINE_VERSION, TESTING_LEAN, TESTING_PARAM, analyze_cpu, analyze_page, analyze_session, apply_attr_rules, assets_diff, browser_of, defer_keys, dev_compile_ms, devtools_switched_on, dynamic_imports, engine_of, explain_held_open, first_difference, compare as fp_compare, hazard_fix, hazard_words, hole_segments, html_diff, hydration_hazards, inline_threshold_tune, is_trace, late_found, lcp_font, lcp_rivals, prebundled_names, rate, runtime_scripts, session_timeline, static_imports, switch_in_url, testing_lean, vital_parts, vitals_moved, weigh_assets, without_switch, write_switch };

package/dist/insights/page-assets.d.ts

@@ -0,0 +1,211 @@
+import { UnscopedStyles } from "../unscoped-css.js";
+export type AssetKind = "script" | "style" | "font" | "image" | "other";
+export interface AssetRef {
+  url: string;
+  kind: AssetKind;
+  /** the browser must have it before the first paint (a head stylesheet, a classic sync script) */
+  blocking: boolean;
+  /** how the document asks for it (`island`: the runtime loads it to wake an island) */
+  via: "script" | "modulepreload" | "preload" | "stylesheet" | "inline-import" | "img" | "static-import" | "island" | "route-node" | "runtime-phase";
+  /** loads later, on demand (an island that wakes when visible / on interaction), not at start */
+  lazy?: boolean;
+  /** the ogygia runtime's own script (`data-ogygia-runtime`): the parts it loads itself are its own */
+  runtime?: true;
+  /** a part of the ogygia runtime it loads on demand as islands wake (and what that part imports) */
+  phase?: true;
+}
+export interface WeighedAsset extends AssetRef {
+  /** decoded bytes (what the browser parses) */
+  bytes: number;
+  /** bytes on the wire: the response's own when it was compressed, else a gzip estimate */
+  wire: number;
+  /** what the build put in it (its source files and packages, readable), when the build said */
+  contains?: string[];
+  /** a font's `Vary` header, as the server answered it */
+  vary?: string;
+}
+export interface PageAssets {
+  assets: WeighedAsset[];
+  /** components whose styles shipped WITHOUT their scope (the build's fallback marker, in a
+   *  stylesheet or an inline `<style>`): their rules apply to the whole page */
+  unscoped?: (UnscopedStyles & {
+    in: string;
+  })[];
+  /** references that could not be weighed (a 404, a timeout, the budget ran out) */
+  missed: string[];
+  /** each of those, and why: `budget` (time ran out before it), `timeout`, `status 404`, `file cap`,
+   *  `error: …` — a total with only `status` misses can be trusted; `budget` / `timeout` ones vary */
+  missed_why?: {
+    url: string;
+    why: string;
+  }[];
+  /** the HTML itself */
+  html: {
+    bytes: number;
+    wire: number;
+  };
+  /** inline `<script>` / `<style>` text in the document, decoded bytes */
+  inline: {
+    script: number;
+    style: number;
+  };
+  totals: {
+    js: number;
+    js_wire: number;
+    css: number;
+    css_wire: number;
+    font: number;
+    image: number;
+    /** every byte at start, on the wire (HTML included) */
+    wire: number;
+    /** JS that loads later, on demand (lazy islands), decoded — not in `js` */
+    lazy_js: number;
+    /** blocking the first paint: stylesheets + classic sync scripts, decoded */
+    blocking: number;
+    blocking_count: number;
+    js_files: number;
+  };
+}
+/** Attributes of one start tag (`<tag a="1" b c='2'>`), names lower-cased; valueless → ''. */
+export declare function tag_attrs(tag: string): Map<string, string>;
+/** `import("x")` / `import('x')` specifiers in a script's text (Kit's inline start). */
+export declare function dynamic_imports(text: string): string[];
+/**
+ * The STATIC imports of a bundled module (`import{a}from"./x.js"`, `import"./y.js"`,
+ * `export*from"./z.js"`): specifiers after `from` / a bare `import` that look like module paths
+ * (relative or absolute, ending in .js/.mjs). Bundler output writes them plainly; a string that
+ * merely contains such text inflates nothing that does not exist — every hit is fetched, and a
+ * miss is dropped.
+ */
+export declare function static_imports(code: string): string[];
+/**
+ * A Kit-hydrated page's route nodes: its inline start script passes `node_ids: [0, 5]` to
+ * `kit.start`, and `app.js` imports each node on demand (`import("../nodes/5.<hash>.js")`) — the
+ * page's OWN code, the heaviest part, reachable only through that dynamic import. Empty when the
+ * page is not Kit-hydrated.
+ */
+export declare function kit_node_ids(script: string): number[];
+/** Every file the document asks for at start, in document order, deduped by URL (the first,
+ *  strongest ask wins: a blocking stylesheet stays blocking). Inline script/style bytes counted. */
+export declare function scan_assets(html: string): {
+  refs: AssetRef[];
+  inline: {
+    script: number;
+    style: number;
+  };
+  kit_nodes: number[];
+};
+export interface Weight {
+  bytes: number;
+  wire: number;
+  /** a module's static imports (resolved to absolute paths), for the walk */
+  imports?: string[];
+  /** its dynamic imports (resolved) — followed only where the page names them (Kit's route nodes) */
+  dynamic?: string[];
+  /** a stylesheet's unscoped fallbacks (see unscoped-css.ts) */
+  unscoped?: UnscopedStyles[];
+  /** a font's `Vary` header (Safari refetches a font preload that varies by Origin when its
+   *  @font-face comes late) */
+  vary?: string;
+}
+/** Resolve a reference against the page (and a module's import against its module). */
+export declare function resolve_ref(ref: string, base: string): string | null;
+export interface WeighOptions {
+  /** the page URL references resolve against */
+  page_url: string;
+  fetch_url: (url: string) => Promise<Response>;
+  /** per-URL cache across reports (a hashed asset never changes) */
+  cache: Map<string, Weight | null>;
+  /** gzip a body to estimate its wire size (node:zlib in the profiler; absent = decoded size) */
+  gzip?: (bytes: Uint8Array) => number;
+  budget_ms?: number;
+  max_files?: number;
+  /** the document the refs came from */
+  html: string;
+  /** files the HTML does not name but the page loads: islands' modules (lazy ones marked) */
+  extra?: AssetRef[];
+  /** what the build put in a file (by its absolute URL), for naming a hashed chunk */
+  contents_of?: (url: string) => string[] | null;
+}
+export declare function weigh_assets(opts: WeighOptions): Promise<PageAssets>;
+export interface AssetChange {
+  /** the file's name now (or then, for one that is gone) */
+  name: string;
+  /** what the build put in it — the identity across builds (hashed names change every build) */
+  contains?: string[];
+  a: number;
+  b: number;
+  lazy?: boolean;
+}
+export interface AssetsDiff {
+  /** JS at start, decoded, then → now */
+  js: {
+    a: number;
+    b: number;
+  };
+  lazy_js: {
+    a: number;
+    b: number;
+  };
+  added: AssetChange[];
+  removed: AssetChange[];
+  grew: AssetChange[];
+  shrank: AssetChange[];
+  /** the same file, now loaded at start (it loaded later before: an island's wake changed) */
+  to_start: AssetChange[];
+  /** the same file, now loaded later (it loaded at start before) */
+  to_later: AssetChange[];
+}
+/**
+ * WHAT CHANGED IN THE PAGE'S JS between two weighings (two builds): the files new, gone, grown and
+ * shrunk. Hashed names change every build, so a file is known by what the build put in it (its
+ * source files and packages, `contains`), and by its URL only when the build said nothing. Changes
+ * under 5 KB are left out; each list is heaviest first.
+ */
+/** What a diff needs of a weighing: the report's JSON carries this much too (a CI compare). */
+export interface WeighedLike {
+  assets: {
+    url: string;
+    kind: string;
+    bytes: number;
+    contains?: string[];
+    lazy?: boolean;
+  }[];
+  totals: {
+    js: number;
+    lazy_js: number;
+  };
+}
+export declare function assets_diff(a: WeighedLike, b: WeighedLike): AssetsDiff;
+export interface RuntimeScripts {
+  files: number;
+  /** decoded */
+  bytes: number;
+  /** on the wire (a third of decoded where the browser saw none: a cached file) */
+  wire: number;
+  /** by who serves them: `this app`, or a CDN package / host */
+  by: {
+    who: string;
+    files: number;
+    bytes: number;
+  }[];
+  /** of this app's, the island entry files (`og-region.<id>.…js`): islands no HTML named — the ones
+   *  a hole's answer brought */
+  island_entries?: number;
+}
+/**
+ * SCRIPTS LOADED AT RUNTIME — what the browser fetched that neither the HTML nor any module's
+ * imports name: a script that loads more scripts (a CDN component library fetching its parts, a tag
+ * manager, a runtime's on-demand chunk). The server cannot see them coming; the profiler user's own
+ * visit saw them. `until`: the end of "at start" on the visit's clock (a lazy island woken by a
+ * scroll later does not count). Null when there are none.
+ */
+export declare function runtime_scripts(assets: readonly {
+  url: string;
+}[], resources: readonly {
+  url: string;
+  type: string;
+  start: number;
+  size?: number;
+  transfer?: number;
+}[], origin: string, until: number): RuntimeScripts | null;