@ogygia/devtools 0.0.0-stage → 0.11.0

package/dist/profiler/compress.d.ts

@@ -0,0 +1,10 @@
+/** a text answer at least this big goes out gzipped (see `gzip_large`) */
+export declare const GZIP_OVER_BYTES: number;
+/**
+ * A big profiler answer (a report page is MBs of island props; the run page's `keep` answer carries
+ * the whole report) gzipped when the browser takes it: AWS Lambda — Amplify's SSR — caps a response
+ * at 6 MB before any CDN compresses it, and a heavy page's report crossed that and failed. Text only
+ * (HTML, JSON), never a response that is already encoded, and never the profiler's own in-process
+ * fetch (Kit hands that Response back as it is, and the standalone export reads it as text).
+ */
+export declare function gzip_large(req: Request, res: Response): Promise<Response>;

package/dist/profiler/compress.js

@@ -0,0 +1,36 @@
+// src/profiler/compress.ts
+/** a text answer at least this big goes out gzipped (see `gzip_large`) */
+const GZIP_OVER_BYTES = 262144;
+/**
+* A big profiler answer (a report page is MBs of island props; the run page's `keep` answer carries
+* the whole report) gzipped when the browser takes it: AWS Lambda — Amplify's SSR — caps a response
+* at 6 MB before any CDN compresses it, and a heavy page's report crossed that and failed. Text only
+* (HTML, JSON), never a response that is already encoded, and never the profiler's own in-process
+* fetch (Kit hands that Response back as it is, and the standalone export reads it as text).
+*/
+async function gzip_large(req, res) {
+	if (!res.body || res.headers.has("content-encoding") || req.headers.get("x-og-profiler-internal")) return res;
+	if (!(req.headers.get("accept-encoding") ?? "").includes("gzip")) return res;
+	const type = res.headers.get("content-type") ?? "";
+	if (!type.startsWith("text/") && !type.includes("json")) return res;
+	const known = Number(res.headers.get("content-length"));
+	if (known && known < 262144) return res;
+	const body = new Uint8Array(await res.arrayBuffer());
+	const headers = new Headers(res.headers);
+	if (body.byteLength < 262144) return new Response(body, {
+		status: res.status,
+		statusText: res.statusText,
+		headers
+	});
+	const { gzip } = await import("node:zlib");
+	const zipped = await new Promise((resolve, reject) => gzip(body, { level: 6 }, (err, out) => err ? reject(err) : resolve(new Uint8Array(out.buffer, out.byteOffset, out.byteLength))));
+	headers.set("content-encoding", "gzip");
+	headers.set("content-length", String(zipped.byteLength));
+	headers.append("vary", "accept-encoding");
+	return new Response(zipped, {
+		status: res.status,
+		statusText: res.statusText,
+		headers
+	});
+}
+export { GZIP_OVER_BYTES, gzip_large };

package/dist/profiler/contention.d.ts

@@ -0,0 +1,60 @@
+import { RequestEntry } from "./report.js";
+export interface ContendingRequest {
+  method: string;
+  path: string;
+  route: string | null;
+  status: number;
+  ms: number;
+  /** ms of its lifetime inside the profiled window(s) */
+  overlap_ms: number;
+  /** at most this much of the window's CPU was its (upper bound) */
+  cpu_max_ms: number;
+  /** `self`: a call the profiled render made to its own server (the same event loop answered
+   *  both sides); `hole`: one of the page's own deferred holes (the page's work, answered while
+   *  it rendered); `other`: a request from somewhere else */
+  kind: "self" | "hole" | "other";
+  /** a remote function call (a `self` one: a render reading a `prerender` function's answer) */
+  remote?: true;
+}
+export interface Contention {
+  /** the heaviest overlaps, at most 40 (count with `counts`, not this list) */
+  requests: ContendingRequest[];
+  /** every overlapping request tallied by kind, before the list was cut (absent on older reports) */
+  counts?: {
+    self: number;
+    self_ms: number;
+    self_paths: string[];
+    self_remote?: number;
+    other: number;
+    hole: number;
+  };
+  /** the sum of the overlaps (a wall-time measure: two requests over one ms count twice) */
+  overlap_ms: number;
+  /** the upper bound on CPU the window lost to them, summed */
+  cpu_max_ms: number;
+  /** how many were in flight when the profiled render(s) started, from the render's own entry */
+  inflight_at_start: number[];
+  /** per profiled window: how many others overlapped it and for how long */
+  per_window: {
+    n: number;
+    overlap_ms: number;
+    cpu_max_ms: number;
+  }[];
+  /** the share of the windows' total length that had another request in flight */
+  busy_share: number;
+}
+export interface ContentionInput {
+  /** the ring, any order */
+  requests: readonly RequestEntry[];
+  /** the profiled window(s) on performance.now()'s clock */
+  windows: readonly {
+    start: number;
+    end: number;
+  }[];
+  /** the profiled renders' own ring entries (internal), to read `inflight` off */
+  own?: readonly RequestEntry[];
+  /** the paths the profiled render called on its own server (its outbound calls' pathnames):
+   *  a ring entry on one of them is the render waiting on itself, not a stranger */
+  self_paths?: ReadonlySet<string>;
+}
+export declare function contention(input: ContentionInput): Contention | undefined;

package/dist/profiler/contention.js

@@ -0,0 +1,86 @@
+import { islands_endpoint } from "@ogygia/core/internal/server";
+// src/profiler/contention.ts
+const round2 = (n) => Math.round(n * 100) / 100;
+function contention(input) {
+	const windows = input.windows;
+	if (!windows.length) return void 0;
+	const per_window = windows.map(() => ({
+		n: 0,
+		overlap_ms: 0,
+		cpu_max_ms: 0
+	}));
+	const rows = [];
+	let overlap_total = 0;
+	let cpu_total = 0;
+	const busy = [];
+	for (const e of input.requests) {
+		if (e.internal || e.pt === void 0) continue;
+		const s = e.pt;
+		const t = e.pt + e.ms;
+		let overlap = 0;
+		for (let i = 0; i < windows.length; i++) {
+			const w = windows[i];
+			const ov = Math.min(t, w.end) - Math.max(s, w.start);
+			if (ov <= 0) continue;
+			overlap += ov;
+			per_window[i].n++;
+			per_window[i].overlap_ms += ov;
+			busy.push([Math.max(s, w.start), Math.min(t, w.end)]);
+		}
+		if (overlap <= 0) continue;
+		const cpu_max = Math.min(overlap, e.ms > 0 ? e.cpu_ms * (overlap / e.ms) : 0);
+		for (let i = 0; i < windows.length; i++) {
+			const w = windows[i];
+			const ov = Math.min(t, w.end) - Math.max(s, w.start);
+			if (ov > 0) per_window[i].cpu_max_ms += cpu_max * (ov / overlap);
+		}
+		overlap_total += overlap;
+		cpu_total += cpu_max;
+		rows.push({
+			method: e.method,
+			path: e.path,
+			route: e.route,
+			status: e.status,
+			ms: round2(e.ms),
+			overlap_ms: round2(overlap),
+			cpu_max_ms: round2(cpu_max),
+			kind: e.hole || e.path.endsWith(islands_endpoint()) ? "hole" : input.self_paths?.has(e.path) ? "self" : "other",
+			...e.remote ? { remote: true } : {}
+		});
+	}
+	const inflight = (input.own ?? []).filter((e) => e.internal && typeof e.inflight === "number").map((e) => e.inflight);
+	busy.sort((a, b) => a[0] - b[0]);
+	let union = 0;
+	let cur = null;
+	for (const iv of busy) if (cur && iv[0] <= cur[1]) cur[1] = Math.max(cur[1], iv[1]);
+	else {
+		if (cur) union += cur[1] - cur[0];
+		cur = iv;
+	}
+	if (cur) union += cur[1] - cur[0];
+	const total_len = windows.reduce((a, w) => a + Math.max(0, w.end - w.start), 0) || 1;
+	if (!rows.length && !inflight.some((n) => n > 0)) return void 0;
+	rows.sort((a, b) => b.overlap_ms - a.overlap_ms);
+	const self_rows = rows.filter((r) => r.kind === "self");
+	return {
+		requests: rows.slice(0, 40),
+		counts: {
+			self: self_rows.length,
+			self_ms: round2(self_rows.reduce((s, r) => s + r.ms, 0)),
+			self_paths: [...new Set(self_rows.map((r) => r.path))].slice(0, 5),
+			self_remote: self_rows.filter((r) => r.remote).length,
+			other: rows.filter((r) => r.kind === "other").length,
+			hole: rows.filter((r) => r.kind === "hole").length
+		},
+		overlap_ms: round2(overlap_total),
+		cpu_max_ms: round2(cpu_total),
+		inflight_at_start: inflight,
+		per_window: per_window.map((p) => ({
+			n: p.n,
+			overlap_ms: round2(p.overlap_ms),
+			cpu_max_ms: round2(p.cpu_max_ms)
+		})),
+		busy_share: round2(Math.min(1, union / total_len))
+	};
+}
+export { contention };

package/dist/profiler/crypto.d.ts

@@ -0,0 +1,19 @@
+/** True when `bytes` starts with the `.ogp` magic (so import can tell it from legacy plain JSON). */
+export declare function is_ogp(bytes: Uint8Array): boolean;
+/**
+ * Undo the two ways a `.ogp` gets mangled moving BETWEEN machines through a text-y channel (a shared
+ * clipboard, an editor re-save, a chat) — the file arrives byte-perfect on either side of the codec,
+ * so the raw magic is intact, but its wrapper isn't:
+ *   - a **UTF-8 BOM** prepended (`EF BB BF`) — strip it;
+ *   - the whole file **base64-encoded** — decode it.
+ * A real `.ogp` already starts with the magic, so this is a no-op on it. Returns bytes to hand to
+ * `is_ogp` / `ogp_decode`; if it can't recover, returns the input unchanged (import then rejects it).
+ */
+export declare function recover_ogp_bytes(bytes: Uint8Array): Uint8Array;
+/** Compress + encrypt a dump object into `.ogp` bytes. Async — never blocks the event loop. */
+export declare function ogp_encode(dump: unknown, secret: string | undefined): Promise<Uint8Array>;
+/**
+ * Decrypt + gunzip `.ogp` bytes back to the dump object. Throws on a wrong key or a tampered file
+ * (the GCM tag fails to verify) — the caller turns that into a "wrong key" message.
+ */
+export declare function ogp_decode(bytes: Uint8Array, secret: string | undefined): Promise<unknown>;

package/dist/profiler/crypto.js

@@ -0,0 +1,101 @@
+// src/profiler/crypto.ts
+/**
+* The `.ogp` codec — a profiler dump Brotli-compressed, then AES-256-GCM encrypted with the key.
+* A downloaded trace exposes server internals (source paths, component names, outbound URLs), so the
+* file can only be reopened by a profiler holding the same key. Node-only (dynamic `node:crypto` +
+* `node:zlib`), kept out of the edge-safe report renderer.
+*
+* Self-describing layout:  'OGP1' (4)  ·  salt (16)  ·  iv (12)  ·  ciphertext  ·  GCM tag (16)
+*
+* The AES key is `scrypt(secret, salt, 32)` — a fresh salt per file. `secret` is the profiler auth
+* secret; with none (dev) a fixed dev key is used so dev exports still open in dev.
+*/
+const MAGIC = [
+	79,
+	71,
+	80,
+	49
+];
+const DEV_KEY = "ogygia-profiler-dev-key";
+async function node() {
+	const [crypto, zlib, util] = await Promise.all([
+		import("node:crypto"),
+		import("node:zlib"),
+		import("node:util")
+	]);
+	const p = util.promisify;
+	return {
+		crypto,
+		zlib,
+		scrypt: p(crypto.scrypt),
+		brotli: p(zlib.brotliCompress),
+		unbrotli: p(zlib.brotliDecompress)
+	};
+}
+/** True when `bytes` starts with the `.ogp` magic (so import can tell it from legacy plain JSON). */
+function is_ogp(bytes) {
+	return bytes.length > 44 && bytes[0] === MAGIC[0] && bytes[1] === MAGIC[1] && bytes[2] === MAGIC[2] && bytes[3] === MAGIC[3];
+}
+const BASE64_RE = /^[A-Za-z0-9+/=\s]+$/;
+/**
+* Undo the two ways a `.ogp` gets mangled moving BETWEEN machines through a text-y channel (a shared
+* clipboard, an editor re-save, a chat) — the file arrives byte-perfect on either side of the codec,
+* so the raw magic is intact, but its wrapper isn't:
+*   - a **UTF-8 BOM** prepended (`EF BB BF`) — strip it;
+*   - the whole file **base64-encoded** — decode it.
+* A real `.ogp` already starts with the magic, so this is a no-op on it. Returns bytes to hand to
+* `is_ogp` / `ogp_decode`; if it can't recover, returns the input unchanged (import then rejects it).
+*/
+function recover_ogp_bytes(bytes) {
+	if (is_ogp(bytes)) return bytes;
+	if (bytes.length >= 3 && bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191) {
+		const stripped = bytes.subarray(3);
+		if (is_ogp(stripped)) return stripped;
+		bytes = stripped;
+	}
+	try {
+		const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes).trim();
+		if (text.length > 8 && BASE64_RE.test(text)) {
+			const decoded = new Uint8Array(Buffer.from(text, "base64"));
+			if (is_ogp(decoded)) return decoded;
+		}
+	} catch {}
+	return bytes;
+}
+/** Compress + encrypt a dump object into `.ogp` bytes. Async — never blocks the event loop. */
+async function ogp_encode(dump, secret) {
+	const { crypto, zlib, scrypt, brotli } = await node();
+	const gz = await brotli(Buffer.from(JSON.stringify(dump), "utf8"), { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 5 } });
+	const salt = crypto.randomBytes(16);
+	const iv = crypto.randomBytes(12);
+	const key = await scrypt(secret || DEV_KEY, salt, 32);
+	const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+	const ct = Buffer.concat([cipher.update(gz), cipher.final()]);
+	const tag = cipher.getAuthTag();
+	return Buffer.concat([
+		Buffer.from(MAGIC),
+		salt,
+		iv,
+		ct,
+		tag
+	]);
+}
+/**
+* Decrypt + gunzip `.ogp` bytes back to the dump object. Throws on a wrong key or a tampered file
+* (the GCM tag fails to verify) — the caller turns that into a "wrong key" message.
+*/
+async function ogp_decode(bytes, secret) {
+	const { crypto, scrypt, unbrotli } = await node();
+	const buf = Buffer.from(bytes);
+	if (!is_ogp(buf)) throw new Error("not an .ogp file");
+	const salt = buf.subarray(4, 20);
+	const iv = buf.subarray(20, 32);
+	const tag = buf.subarray(buf.length - 16);
+	const ct = buf.subarray(32, buf.length - 16);
+	const key = await scrypt(secret || DEV_KEY, salt, 32);
+	const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+	decipher.setAuthTag(tag);
+	const gz = Buffer.concat([decipher.update(ct), decipher.final()]);
+	return JSON.parse((await unbrotli(gz)).toString("utf8"));
+}
+export { is_ogp, ogp_decode, ogp_encode, recover_ogp_bytes };

package/dist/profiler/doc-diff.d.ts

@@ -0,0 +1,47 @@
+/**
+ * WHAT CHANGES BETWEEN TWO RENDERS OF ONE PAGE: both documents split at their tags, lined up, and
+ * every piece that differs grouped by what it is — an island's props (its region and its props
+ * script change together), one attribute on one kind of tag (a random id stamped per render), or
+ * the text inside a tag. A page the same but for a few such parts is a page to cache whole once
+ * those parts stop changing. Hand-parsed (indexOf), no regex: a document can be megabytes.
+ */
+export interface DocDiffGroup {
+  /** what changes, for a reader: `data-track on <a>`, `the Price island's props`, `text in <p>` */
+  what: string;
+  tag: string;
+  attr?: string;
+  island?: string;
+  /** places it differs */
+  count: number;
+  /** one example, first render against the last */
+  a: string;
+  b: string;
+  /** where your markup sets it (an attribute given a value from code), when a component file does */
+  sources?: {
+    file: string;
+    line: number;
+    code: string;
+  }[];
+  /** an attribute no file of yours sets: a library stamps it as it renders */
+  library?: boolean;
+}
+/** The lines of a component's markup that give `attr` a value from code on one of `tags`
+ *  (`<a … data-track={id}>`): plain text search, the attribute's name as written. */
+export declare function attr_sites(src: string, attr: string, tags: readonly string[]): {
+  line: number;
+  code: string;
+}[];
+export interface DocDiff {
+  /** tag-delimited pieces of the later document */
+  tokens: number;
+  /** pieces that differ */
+  differing: number;
+  /** the documents lined up piece by piece (same count); else matched past small insertions */
+  aligned: boolean;
+  groups: DocDiffGroup[];
+}
+/**
+ * The two documents' differences, grouped. `island_of(entry)` names an island by its entry URL (the
+ * report's island rows). Undefined when they are the same, or differ too much to line up.
+ */
+export declare function doc_diff(a: string, b: string, island_of?: (entry: string) => string | undefined, max_groups?: number): DocDiff | undefined;

package/dist/profiler/doc-diff.js

@@ -0,0 +1,214 @@
+// src/profiler/doc-diff.ts
+/** The lines of a component's markup that give `attr` a value from code on one of `tags`
+*  (`<a … data-track={id}>`): plain text search, the attribute's name as written. */
+function attr_sites(src, attr, tags) {
+	const out = [];
+	const lines = src.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		const l = lines[i];
+		let at = -1;
+		for (const form of [
+			`${attr}={`,
+			`${attr}="{`,
+			...attr.includes("-") ? [] : [`{${attr}}`]
+		]) {
+			let p = l.indexOf(form);
+			while (p !== -1 && p > 0 && l[p - 1] !== " " && l[p - 1] !== "	") p = l.indexOf(form, p + 1);
+			if (p !== -1 && (at === -1 || p < at)) at = p;
+		}
+		if (at === -1) continue;
+		if (!tags.filter((t) => {
+			let o = l.indexOf(`<${t}`);
+			while (o !== -1 && o < at) {
+				const next = l[o + t.length + 1];
+				if (next === void 0 || next === " " || next === ">" || next === "/" || next === "	") return true;
+				o = l.indexOf(`<${t}`, o + 1);
+			}
+			return false;
+		}).length && l.slice(0, at).includes("<")) continue;
+		out.push({
+			line: i + 1,
+			code: l.trim().length > 140 ? l.trim().slice(0, 139) + "…" : l.trim()
+		});
+	}
+	return out;
+}
+/** a document at its tags: each piece starts at a `<` */
+function pieces(doc) {
+	const out = [];
+	let at = 0;
+	while (at < doc.length) {
+		const next = doc.indexOf("<", at + 1);
+		const end = next === -1 ? doc.length : next;
+		out.push(doc.slice(at, end));
+		at = end;
+	}
+	return out;
+}
+/** `<a href="x" data-track="1">text` → tag `a`, attributes, the text after the tag */
+function parse(piece) {
+	const attrs = /* @__PURE__ */ new Map();
+	if (piece[0] !== "<") return {
+		tag: "text",
+		attrs,
+		text: piece
+	};
+	let i = 1;
+	if (piece[i] === "/") i++;
+	let j = i;
+	while (j < piece.length && piece[j] !== " " && piece[j] !== ">" && piece[j] !== "/" && piece[j] !== "\n" && piece[j] !== "	") j++;
+	const tag = piece.slice(i, j).toLowerCase();
+	const close = piece.indexOf(">", j);
+	const head = close === -1 ? piece.slice(j) : piece.slice(j, close);
+	let k = 0;
+	while (k < head.length) {
+		let eq = head.indexOf("=", k);
+		while (eq !== -1 && head[eq + 1] !== "\"" && head[eq + 1] !== "'") eq = head.indexOf("=", eq + 1);
+		if (eq === -1) break;
+		const q = head[eq + 1];
+		let s = eq - 1;
+		while (s >= 0 && head[s] !== " " && head[s] !== "\n" && head[s] !== "	") s--;
+		const name = head.slice(s + 1, eq);
+		const endq = head.indexOf(q, eq + 2);
+		if (endq === -1) break;
+		attrs.set(name, head.slice(eq + 2, endq));
+		k = endq + 1;
+	}
+	return {
+		tag,
+		attrs,
+		text: close === -1 ? "" : piece.slice(close + 1)
+	};
+}
+const clip = (s) => s.length > 60 ? s.slice(0, 59) + "…" : s;
+/**
+* The two documents' differences, grouped. `island_of(entry)` names an island by its entry URL (the
+* report's island rows). Undefined when they are the same, or differ too much to line up.
+*/
+function doc_diff(a, b, island_of = () => void 0, max_groups = 8) {
+	if (a === b) return void 0;
+	const pa = pieces(a);
+	const pb = pieces(b);
+	const aligned = pa.length === pb.length;
+	const entry_of_fp = /* @__PURE__ */ new Map();
+	const pairs = [];
+	if (aligned) {
+		for (let i = 0; i < pb.length; i++) if (pa[i] !== pb[i]) pairs.push([pa[i], pb[i]]);
+	} else {
+		let i = 0;
+		let j = 0;
+		const AHEAD = 24;
+		while (i < pa.length && j < pb.length) {
+			if (pa[i] === pb[j]) {
+				i++;
+				j++;
+				continue;
+			}
+			let moved = false;
+			for (let d = 1; d <= AHEAD && !moved; d++) if (j + d < pb.length && pa[i] === pb[j + d]) {
+				for (let x = 0; x < d; x++) pairs.push(["", pb[j + x]]);
+				j += d;
+				moved = true;
+			} else if (i + d < pa.length && pa[i + d] === pb[j]) {
+				for (let x = 0; x < d; x++) pairs.push([pa[i + x], ""]);
+				i += d;
+				moved = true;
+			}
+			if (!moved) {
+				pairs.push([pa[i], pb[j]]);
+				i++;
+				j++;
+			}
+			if (pairs.length > 50 && pairs.length > pb.length * .25) return void 0;
+		}
+		for (; i < pa.length; i++) pairs.push([pa[i], ""]);
+		for (; j < pb.length; j++) pairs.push(["", pb[j]]);
+		if (pairs.length > 50 && pairs.length > pb.length * .25) return void 0;
+	}
+	for (const p of pb) {
+		if (!p.startsWith("<ogygia-region")) continue;
+		const { attrs } = parse(p);
+		const fp = attrs.get("data-og-fp");
+		const entry = attrs.get("entry");
+		if (fp && entry) entry_of_fp.set(fp, entry);
+	}
+	const groups = /* @__PURE__ */ new Map();
+	const add = (key, g) => {
+		const cur = groups.get(key);
+		if (cur) cur.count++;
+		else groups.set(key, {
+			...g,
+			count: 1
+		});
+	};
+	for (const [x, y] of pairs) {
+		if (!x || !y) {
+			const only = parse(x || y);
+			const verb = x ? "dropped" : "added";
+			add(`${verb}\0${only.tag}`, {
+				what: `<${only.tag}> ${verb} in the later render`,
+				tag: only.tag,
+				a: clip(x.slice(0, 60)),
+				b: clip(y.slice(0, 60))
+			});
+			continue;
+		}
+		if (y.startsWith("<!--")) {
+			const end = y.indexOf("-->");
+			add("comment", {
+				what: "comment markers (<!--…-->)",
+				tag: "comment",
+				a: clip(x.slice(0, x.indexOf("-->") + 3)),
+				b: clip(end === -1 ? y : y.slice(0, end + 3))
+			});
+			continue;
+		}
+		const py = parse(y);
+		const px = parse(x);
+		if (py.tag === "ogygia-region" || py.tag === "script" && py.attrs.has("data-ogygia-props")) {
+			const entry = py.tag === "ogygia-region" ? py.attrs.get("entry") : entry_of_fp.get(py.attrs.get("data-ogygia-props") ?? "");
+			const name = entry && island_of(entry) || "an";
+			if (py.tag === "script") continue;
+			add(`island\0${name}`, {
+				what: `the ${name} island's props`,
+				tag: py.tag,
+				island: name,
+				a: clip(px.attrs.get("data-og-fp") ?? ""),
+				b: clip(py.attrs.get("data-og-fp") ?? "")
+			});
+			continue;
+		}
+		const changed = [...py.attrs].filter(([k, v]) => px.attrs.get(k) !== v).map(([k]) => k);
+		for (const k of px.attrs.keys()) if (!py.attrs.has(k)) changed.push(k);
+		if (changed.length) for (const attr of changed) {
+			const key = `attr\0${attr}`;
+			const g = groups.get(key);
+			if (g && !g.tag.split(", ").includes(py.tag)) g.tag += `, ${py.tag}`;
+			add(key, {
+				what: "",
+				tag: py.tag,
+				attr,
+				a: clip(px.attrs.get(attr) ?? ""),
+				b: clip(py.attrs.get(attr) ?? "")
+			});
+		}
+		else add(`text\0${py.tag}`, {
+			what: `text in <${py.tag}>`,
+			tag: py.tag,
+			a: clip(px.text.trim()),
+			b: clip(py.text.trim())
+		});
+	}
+	for (const g of groups.values()) {
+		if (!g.attr) continue;
+		const tags = g.tag.split(", ");
+		g.what = `${g.attr} on ${tags.slice(0, 3).map((t) => `<${t}>`).join(", ")}${tags.length > 3 ? ` and ${tags.length - 3} more` : ""}`;
+	}
+	return {
+		tokens: pb.length,
+		differing: pairs.length,
+		aligned,
+		groups: [...groups.values()].sort((m, n) => n.count - m.count).slice(0, max_groups)
+	};
+}
+export { attr_sites, doc_diff };

package/dist/profiler/dom-diff.d.ts

@@ -0,0 +1,43 @@
+/**
+ * DOM TIME TRAVEL — an island's markup at three moments (as the server sent it, after it hydrated,
+ * when the page went away) and what changed between them, plus the layout shifts of a visit
+ * drawn as boxes. Pure: `html_diff` is a token diff (tags and text runs) with a size cap so a huge
+ * island never freezes the report; `shift_boxes` normalizes shift rectangles to the viewport.
+ */
+export interface DiffOp {
+  kind: "same" | "add" | "del";
+  text: string;
+}
+export interface HtmlDiff {
+  ops: DiffOp[];
+  added: number;
+  removed: number;
+  /** the middle was too large to diff token by token and is shown as one removal + one addition */
+  truncated: boolean;
+  /** the tokens both sides share, as a share of the longer side (1 = identical) */
+  same_ratio: number;
+}
+export declare function tokenize_html(s: string): string[];
+export declare function html_diff(a: string, b: string): HtmlDiff;
+export interface ShiftBox {
+  /** 0..1 of the viewport */
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** where it came from, same units */
+  fx: number;
+  fy: number;
+  value: number;
+  t: number;
+  fp?: string;
+}
+/** Layout-shift rectangles normalized to the viewport, biggest shift first; boxes outside the
+ *  viewport are clipped, a missing rect is skipped. */
+export declare function shift_boxes(shifts: {
+  t: number;
+  value: number;
+  fp?: string;
+  from?: [number, number, number, number];
+  to?: [number, number, number, number];
+}[], viewport: [number, number] | undefined): ShiftBox[];