@jitsusama/agentic-harness.core 0.1.0 → 0.2.0

package/dist/web/design/typography.js

@@ -0,0 +1,221 @@
+/**
+ * How text blocks end: orphans and runts, from real layout.
+ *
+ * A single word stranded on the last line of a paragraph or
+ * heading reads as a typesetting accident, and a very short last
+ * line nearly does. Neither can be judged from markup or font
+ * metrics, because where the browser broke the lines is the
+ * fact, so the capture reads actual line boxes word by word
+ * through Range.getBoundingClientRect.
+ *
+ * This is taste, not conformance: nothing here fails a
+ * standard, and the verdict never goes past WARN. It sits in
+ * the design domain beside the inventory for the same reason
+ * the inventory does: it reports what a person would want to
+ * polish, and the judgment of whether it matters is theirs.
+ *
+ * The line-reading approach is ported from the orphans-and-runts
+ * check in Carolyn McNeillie's review-page skill set, including
+ * its exclusions: text the author already asked the browser to
+ * balance is the browser's business, and text inside a collapsed
+ * disclosure is not laid out at all.
+ */
+import { count } from "../../ui/count.js";
+import { renderVerdict } from "../audit/verdict.js";
+/** Body text shorter than this is skipped in the capture. */
+export const BODY_FLOOR_CHARS = 80;
+/** A last line of this many words or fewer can be a runt. */
+export const RUNT_MAX_WORDS = 3;
+/** ...when it fills less than this share of the container. */
+export const RUNT_WIDTH_SHARE = 0.25;
+const HEADINGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
+/**
+ * Judge how the captured blocks end.
+ *
+ * Only blocks that actually wrapped are judged: a one-line
+ * heading has no last line to strand anything on.
+ */
+export function analyseTypography(blocks) {
+    const findings = [];
+    for (const block of blocks) {
+        if (block.lineCount < 2)
+            continue;
+        const heading = HEADINGS.has(block.tag);
+        if (block.lastLine.words === 1) {
+            findings.push({ kind: "orphan", heading, block });
+            continue;
+        }
+        if (block.lastLine.words <= RUNT_MAX_WORDS &&
+            block.containerWidth > 0 &&
+            block.lastLine.width < block.containerWidth * RUNT_WIDTH_SHARE) {
+            findings.push({ kind: "runt", heading, block });
+        }
+    }
+    // Headings first, orphans before runts, so the worst reads first.
+    return findings.sort((a, b) => {
+        if (a.heading !== b.heading)
+            return a.heading ? -1 : 1;
+        if (a.kind !== b.kind)
+            return a.kind === "orphan" ? -1 : 1;
+        return 0;
+    });
+}
+/** Say how the page's text blocks end. */
+export function renderTypography(blocks, findings) {
+    const wrapped = blocks.filter((block) => block.lineCount >= 2).length;
+    const measured = `Measured ${count(blocks.length, "text block")}, ` +
+        `${wrapped} of them wrapped. Single-line blocks have no last ` +
+        `line to judge; text under ${BODY_FLOOR_CHARS} characters and ` +
+        `text the author asked the browser to balance were left out ` +
+        `at capture.`;
+    if (findings.length === 0) {
+        return renderVerdict({
+            standing: "pass",
+            headline: "Every wrapped text block ends cleanly.",
+            measured,
+        }, "");
+    }
+    const orphans = findings.filter((one) => one.kind === "orphan");
+    const inHeadings = findings.filter((one) => one.heading);
+    const lines = findings.map((one) => {
+        const what = one.kind === "orphan"
+            ? `one word alone on the last line: "${one.block.lastLine.text}"`
+            : `${count(one.block.lastLine.words, "word")} on a last line ` +
+                `filling ${Math.round((one.block.lastLine.width / one.block.containerWidth) * 100)}% of the container: "${one.block.lastLine.text}"`;
+        return `  ${one.block.selector} <${one.block.tag}>  ${what}`;
+    });
+    return renderVerdict({
+        // Taste, not conformance: this never fails a page.
+        standing: "warn",
+        headline: `${count(findings.length, "text block")} of ${wrapped} ` +
+            `wrapped ${wrapped === 1 ? "ends" : "end"} badly: ` +
+            `${count(orphans.length, "orphan")}, ` +
+            `${count(findings.length - orphans.length, "runt")}` +
+            `${inHeadings.length === 0 ? "" : `, ${inHeadings.length} in headings`}.`,
+        measured,
+    }, lines.join("\n"));
+}
+/**
+ * The expression that measures how text blocks wrap.
+ *
+ * The word walk reads each word's rectangle through a Range and
+ * groups words into lines by their tops, so the lines are the
+ * browser's own. Kept close to the tuned original: the fixes it
+ * carries (zero-size rects from hidden text, line grouping by
+ * half a line-height) were earned against real pages.
+ */
+export const TYPOGRAPHY_CAPTURE = `(() => {
+	const BODY_FLOOR = ${BODY_FLOOR_CHARS};
+	const MAX_TEXT = 80;
+
+	const selectorFor = (el) => {
+		const tag = el.tagName.toLowerCase();
+		if (el.id) return "#" + el.id;
+		const hook = el.getAttribute("data-testid");
+		if (hook) return tag + '[data-testid="' + hook + '"]';
+		const first = el.classList[0];
+		if (first) return tag + "." + first;
+		return tag;
+	};
+
+	const visualLines = (element) => {
+		const walker = document.createTreeWalker(
+			element,
+			NodeFilter.SHOW_TEXT,
+			null,
+		);
+		const nodes = [];
+		while (walker.nextNode()) {
+			if (walker.currentNode.textContent.trim()) {
+				nodes.push(walker.currentNode);
+			}
+		}
+		const range = document.createRange();
+		const lines = [];
+		let top = null;
+		let height = 0;
+		let words = 0;
+		let left = Infinity;
+		let right = -Infinity;
+		let text = "";
+		const flush = () => {
+			if (words > 0) {
+				lines.push({ words, width: right - left, text });
+			}
+			words = 0;
+			left = Infinity;
+			right = -Infinity;
+			text = "";
+		};
+		for (const node of nodes) {
+			const content = node.textContent;
+			const matcher = /\\S+/g;
+			let match = matcher.exec(content);
+			while (match) {
+				range.setStart(node, match.index);
+				range.setEnd(node, match.index + match[0].length);
+				const rect = range.getBoundingClientRect();
+				if (rect.width > 0 || rect.height > 0) {
+					const sameLine =
+						top !== null && Math.abs(rect.top - top) <= height / 2;
+					if (!sameLine) {
+						flush();
+						top = rect.top;
+						height = rect.height;
+					}
+					words += 1;
+					left = Math.min(left, rect.left);
+					right = Math.max(right, rect.right);
+					if (text.length < MAX_TEXT) {
+						text = (text ? text + " " : "") + match[0];
+					}
+				}
+				match = matcher.exec(content);
+			}
+		}
+		flush();
+		return lines;
+	};
+
+	const wrapStyle = (el) => {
+		const style = getComputedStyle(el);
+		return style.textWrap || style.textWrapStyle || "";
+	};
+
+	const candidates = document.querySelectorAll(
+		"p, h1, h2, h3, h4, h5, h6, figcaption",
+	);
+	const blocks = [];
+	for (const el of candidates) {
+		if (el.getClientRects().length === 0) continue;
+		const tag = el.tagName.toLowerCase();
+		const textLength = (el.innerText || "").trim().length;
+		if (textLength === 0) continue;
+		// Headings matter most and are short; body text below the
+		// floor has no room for a wrap worth judging.
+		const heading = tag[0] === "h";
+		if (!heading && textLength < BODY_FLOOR) continue;
+		// The author already asked the browser to mind the wrapping.
+		const wrap = wrapStyle(el);
+		if (wrap.includes("balance") || wrap.includes("pretty")) continue;
+		// Text inside a collapsed disclosure is not laid out.
+		const details = el.closest("details");
+		if (details && !details.open) continue;
+		const lines = visualLines(el);
+		const last = lines[lines.length - 1];
+		if (!last) continue;
+		blocks.push({
+			selector: selectorFor(el),
+			tag,
+			textLength,
+			containerWidth: el.clientWidth,
+			lineCount: lines.length,
+			lastLine: {
+				words: last.words,
+				width: last.width,
+				text: last.text.slice(0, MAX_TEXT),
+			},
+		});
+	}
+	return blocks;
+})()`;

package/dist/web/hydration/capture.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reading the server render and the hydrated page side by side.
+ *
+ * The server's HTML is fetched from inside the page, so it
+ * travels with the session's own cookies and headers, and it is
+ * parsed with DOMParser, which builds a document without running
+ * a single script: exactly what the browser had before hydration
+ * ran. Both documents are reduced to the same compact shape,
+ * text and tag counts, because the judgment belongs to the pure
+ * side and whole DOM trees do not fit through a capture.
+ */
+/** Both renders, reduced to comparable shape. */
+export interface HydrationCapture {
+    readonly url: string;
+    /** Whether the server render could be fetched at all. */
+    readonly fetched: boolean;
+    readonly status?: number;
+    readonly serverTexts: readonly string[];
+    readonly clientTexts: readonly string[];
+    readonly serverTags: Readonly<Record<string, number>>;
+    readonly clientTags: Readonly<Record<string, number>>;
+}
+/** Texts shorter than this are markup lint, not content. */
+export declare const MIN_TEXT_CHARS = 3;
+/** How many texts to carry per side. */
+export declare const MAX_TEXTS = 500;
+/** How much of each text to keep. */
+export declare const MAX_TEXT_CHARS = 120;
+/**
+ * The expression that reads both renders.
+ *
+ * Async because the server render is a fetch; evaluate it with
+ * awaitPromise. Scripts, styles and noscript are excluded from
+ * both sides: they are machinery, not content, and noscript text
+ * is visible in exactly one of the two renders by definition.
+ */
+export declare const HYDRATION_CAPTURE = "(async () => {\n\tconst MIN_TEXT = 3;\n\tconst MAX_TEXTS = 500;\n\tconst MAX_CHARS = 120;\n\tconst MACHINERY = new Set([\"script\", \"style\", \"noscript\", \"template\"]);\n\n\tconst textsOf = (root) => {\n\t\tconst walker = document.createTreeWalker(\n\t\t\troot,\n\t\t\tNodeFilter.SHOW_TEXT,\n\t\t\tnull,\n\t\t);\n\t\tconst texts = [];\n\t\twhile (walker.nextNode() && texts.length < MAX_TEXTS) {\n\t\t\tconst node = walker.currentNode;\n\t\t\tconst parent = node.parentElement;\n\t\t\tif (!parent) continue;\n\t\t\tif (MACHINERY.has(parent.tagName.toLowerCase())) continue;\n\t\t\tconst text = (node.textContent || \"\")\n\t\t\t\t.replace(/\\s+/g, \" \")\n\t\t\t\t.trim()\n\t\t\t\t.slice(0, MAX_CHARS);\n\t\t\tif (text.length >= MIN_TEXT) texts.push(text);\n\t\t}\n\t\treturn texts;\n\t};\n\n\tconst tagsOf = (root) => {\n\t\tconst counts = {};\n\t\tfor (const el of root.querySelectorAll(\"*\")) {\n\t\t\tconst tag = el.tagName.toLowerCase();\n\t\t\tif (MACHINERY.has(tag) || tag === \"link\" || tag === \"meta\") continue;\n\t\t\tcounts[tag] = (counts[tag] || 0) + 1;\n\t\t}\n\t\treturn counts;\n\t};\n\n\tlet fetched = false;\n\tlet status;\n\tlet serverTexts = [];\n\tlet serverTags = {};\n\ttry {\n\t\tconst response = await fetch(location.href, {\n\t\t\theaders: { accept: \"text/html\" },\n\t\t\tcredentials: \"include\",\n\t\t\tcache: \"no-store\",\n\t\t});\n\t\tstatus = response.status;\n\t\tif (response.ok) {\n\t\t\tconst html = await response.text();\n\t\t\tconst server = new DOMParser().parseFromString(html, \"text/html\");\n\t\t\tconst root = server.body || server.documentElement;\n\t\t\tserverTexts = textsOf(root);\n\t\t\tserverTags = tagsOf(root);\n\t\t\tfetched = true;\n\t\t}\n\t} catch (error) {\n\t\t// fetched stays false, which the judge reports honestly.\n\t}\n\n\tconst live = document.body || document.documentElement;\n\treturn {\n\t\turl: location.href,\n\t\tfetched,\n\t\t...(status === undefined ? {} : { status }),\n\t\tserverTexts,\n\t\tserverTags,\n\t\tclientTexts: textsOf(live),\n\t\tclientTags: tagsOf(live),\n\t};\n})()";

package/dist/web/hydration/capture.js

@@ -0,0 +1,96 @@
+/**
+ * Reading the server render and the hydrated page side by side.
+ *
+ * The server's HTML is fetched from inside the page, so it
+ * travels with the session's own cookies and headers, and it is
+ * parsed with DOMParser, which builds a document without running
+ * a single script: exactly what the browser had before hydration
+ * ran. Both documents are reduced to the same compact shape,
+ * text and tag counts, because the judgment belongs to the pure
+ * side and whole DOM trees do not fit through a capture.
+ */
+/** Texts shorter than this are markup lint, not content. */
+export const MIN_TEXT_CHARS = 3;
+/** How many texts to carry per side. */
+export const MAX_TEXTS = 500;
+/** How much of each text to keep. */
+export const MAX_TEXT_CHARS = 120;
+/**
+ * The expression that reads both renders.
+ *
+ * Async because the server render is a fetch; evaluate it with
+ * awaitPromise. Scripts, styles and noscript are excluded from
+ * both sides: they are machinery, not content, and noscript text
+ * is visible in exactly one of the two renders by definition.
+ */
+export const HYDRATION_CAPTURE = `(async () => {
+	const MIN_TEXT = ${MIN_TEXT_CHARS};
+	const MAX_TEXTS = ${MAX_TEXTS};
+	const MAX_CHARS = ${MAX_TEXT_CHARS};
+	const MACHINERY = new Set(["script", "style", "noscript", "template"]);
+
+	const textsOf = (root) => {
+		const walker = document.createTreeWalker(
+			root,
+			NodeFilter.SHOW_TEXT,
+			null,
+		);
+		const texts = [];
+		while (walker.nextNode() && texts.length < MAX_TEXTS) {
+			const node = walker.currentNode;
+			const parent = node.parentElement;
+			if (!parent) continue;
+			if (MACHINERY.has(parent.tagName.toLowerCase())) continue;
+			const text = (node.textContent || "")
+				.replace(/\\s+/g, " ")
+				.trim()
+				.slice(0, MAX_CHARS);
+			if (text.length >= MIN_TEXT) texts.push(text);
+		}
+		return texts;
+	};
+
+	const tagsOf = (root) => {
+		const counts = {};
+		for (const el of root.querySelectorAll("*")) {
+			const tag = el.tagName.toLowerCase();
+			if (MACHINERY.has(tag) || tag === "link" || tag === "meta") continue;
+			counts[tag] = (counts[tag] || 0) + 1;
+		}
+		return counts;
+	};
+
+	let fetched = false;
+	let status;
+	let serverTexts = [];
+	let serverTags = {};
+	try {
+		const response = await fetch(location.href, {
+			headers: { accept: "text/html" },
+			credentials: "include",
+			cache: "no-store",
+		});
+		status = response.status;
+		if (response.ok) {
+			const html = await response.text();
+			const server = new DOMParser().parseFromString(html, "text/html");
+			const root = server.body || server.documentElement;
+			serverTexts = textsOf(root);
+			serverTags = tagsOf(root);
+			fetched = true;
+		}
+	} catch (error) {
+		// fetched stays false, which the judge reports honestly.
+	}
+
+	const live = document.body || document.documentElement;
+	return {
+		url: location.href,
+		fetched,
+		...(status === undefined ? {} : { status }),
+		serverTexts,
+		serverTags,
+		clientTexts: textsOf(live),
+		clientTags: tagsOf(live),
+	};
+})()`;

package/dist/web/hydration/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether the page the server sent is the page the person got.
+ *
+ * The capture reads both renders from inside the page; the judge
+ * is pure and takes serialized data, so it can judge a stored
+ * capture as easily as a live one. Nothing here can start a
+ * browser.
+ */
+export { HYDRATION_CAPTURE, type HydrationCapture, MAX_TEXT_CHARS, MAX_TEXTS, MIN_TEXT_CHARS, } from "./capture.js";
+export { type ConsoleLine, type HydrationReport, judgeHydration, renderHydration, SHELL_FLOOR_TEXTS, SHELL_MIN_CLIENT_TEXTS, TAG_DRIFT_MIN, type TagDrift, } from "./judge.js";

package/dist/web/hydration/index.js

@@ -0,0 +1,10 @@
+/**
+ * Whether the page the server sent is the page the person got.
+ *
+ * The capture reads both renders from inside the page; the judge
+ * is pure and takes serialized data, so it can judge a stored
+ * capture as easily as a live one. Nothing here can start a
+ * browser.
+ */
+export { HYDRATION_CAPTURE, MAX_TEXT_CHARS, MAX_TEXTS, MIN_TEXT_CHARS, } from "./capture.js";
+export { judgeHydration, renderHydration, SHELL_FLOOR_TEXTS, SHELL_MIN_CLIENT_TEXTS, TAG_DRIFT_MIN, } from "./judge.js";

package/dist/web/hydration/judge.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Whether the page the server sent is the page the person got.
+ *
+ * A hydration mismatch ships silently: the markup is valid, the
+ * console line scrolls past, and the visitor sees content flash,
+ * flip or vanish. The judgment here is over three kinds of
+ * evidence: content in the server render that is gone after
+ * hydration, content that only exists after hydration, and the
+ * framework's own hydration warnings caught in the console.
+ *
+ * Framework-agnostic on purpose. The console recognizers know
+ * the words React and Vue use, but the DOM comparison knows
+ * nothing about any framework: a server render and a hydrated
+ * document disagree or they do not.
+ *
+ * Adapted from the hydration-safety check in Carolyn McNeillie's
+ * review-page skill set, generalized from its React framing.
+ */
+import { type Standing } from "../audit/verdict.js";
+import type { HydrationCapture } from "./capture.js";
+/** One console line, as the session's telemetry records it. */
+export interface ConsoleLine {
+    readonly level: string;
+    readonly text: string;
+}
+/** A tag whose count moved between the renders. */
+export interface TagDrift {
+    readonly tag: string;
+    readonly server: number;
+    readonly client: number;
+}
+/** Everything the judge concluded. */
+export interface HydrationReport {
+    readonly standing: Standing;
+    /** Server content that is gone after hydration. */
+    readonly vanished: readonly string[];
+    /** Content that only exists after hydration. */
+    readonly appeared: readonly string[];
+    readonly drift: readonly TagDrift[];
+    /** The framework's own hydration complaints. */
+    readonly warnings: readonly string[];
+    /** True when there was no server render worth comparing. */
+    readonly shell: boolean;
+    readonly fetched: boolean;
+    readonly status?: number;
+}
+/** Fewer server texts than this is a shell, not a render. */
+export declare const SHELL_FLOOR_TEXTS = 5;
+/** ...when the client has at least this many. */
+export declare const SHELL_MIN_CLIENT_TEXTS = 20;
+/** A tag count moving less than this is churn, not drift. */
+export declare const TAG_DRIFT_MIN = 5;
+/** Judge a capture beside what the console said during load. */
+export declare function judgeHydration(capture: HydrationCapture, consoleLines?: readonly ConsoleLine[]): HydrationReport;
+/** Say whether the server render survived hydration. */
+export declare function renderHydration(report: HydrationReport): string;

package/dist/web/hydration/judge.js

@@ -0,0 +1,191 @@
+/**
+ * Whether the page the server sent is the page the person got.
+ *
+ * A hydration mismatch ships silently: the markup is valid, the
+ * console line scrolls past, and the visitor sees content flash,
+ * flip or vanish. The judgment here is over three kinds of
+ * evidence: content in the server render that is gone after
+ * hydration, content that only exists after hydration, and the
+ * framework's own hydration warnings caught in the console.
+ *
+ * Framework-agnostic on purpose. The console recognizers know
+ * the words React and Vue use, but the DOM comparison knows
+ * nothing about any framework: a server render and a hydrated
+ * document disagree or they do not.
+ *
+ * Adapted from the hydration-safety check in Carolyn McNeillie's
+ * review-page skill set, generalized from its React framing.
+ */
+import { count, renderVerdict } from "../audit/verdict.js";
+/**
+ * What a hydration complaint looks like in a console.
+ *
+ * React 17 says "Text content does not match server-rendered
+ * HTML", React 18 and 19 say "Hydration failed" and "an error
+ * occurred during hydration", Vue says "Hydration node mismatch".
+ * The word stem covers all but the first, which gets its own
+ * pattern.
+ */
+const COMPLAINTS = [/hydrat/i, /did not match/i, /server.rendered/i];
+/** Console levels worth reading complaints from. */
+const SPOKEN_LEVELS = new Set(["error", "warning", "warn"]);
+/** Fewer server texts than this is a shell, not a render. */
+export const SHELL_FLOOR_TEXTS = 5;
+/** ...when the client has at least this many. */
+export const SHELL_MIN_CLIENT_TEXTS = 20;
+/** A tag count moving less than this is churn, not drift. */
+export const TAG_DRIFT_MIN = 5;
+function multiset(texts) {
+    const counts = new Map();
+    for (const text of texts)
+        counts.set(text, (counts.get(text) ?? 0) + 1);
+    return counts;
+}
+function difference(from, take) {
+    const remaining = multiset(take);
+    const out = [];
+    for (const text of from) {
+        const left = remaining.get(text) ?? 0;
+        if (left > 0) {
+            remaining.set(text, left - 1);
+        }
+        else {
+            out.push(text);
+        }
+    }
+    return out;
+}
+/** Judge a capture beside what the console said during load. */
+export function judgeHydration(capture, consoleLines = []) {
+    const warnings = consoleLines
+        .filter((line) => SPOKEN_LEVELS.has(line.level))
+        .filter((line) => COMPLAINTS.some((pattern) => pattern.test(line.text)))
+        .map((line) => line.text);
+    const base = {
+        warnings,
+        fetched: capture.fetched,
+        ...(capture.status === undefined ? {} : { status: capture.status }),
+    };
+    if (!capture.fetched) {
+        return {
+            ...base,
+            standing: warnings.length > 0 ? "fail" : "warn",
+            vanished: [],
+            appeared: [],
+            drift: [],
+            shell: false,
+        };
+    }
+    // A client-rendered page has no server render to hold it to:
+    // every text would read as appeared, which is noise about an
+    // architecture, not findings about a bug.
+    const shell = capture.serverTexts.length < SHELL_FLOOR_TEXTS &&
+        capture.clientTexts.length >= SHELL_MIN_CLIENT_TEXTS;
+    if (shell) {
+        return {
+            ...base,
+            standing: warnings.length > 0 ? "fail" : "warn",
+            vanished: [],
+            appeared: [],
+            drift: [],
+            shell: true,
+        };
+    }
+    const vanished = difference(capture.serverTexts, capture.clientTexts);
+    const appeared = difference(capture.clientTexts, capture.serverTexts);
+    const tags = new Set([
+        ...Object.keys(capture.serverTags),
+        ...Object.keys(capture.clientTags),
+    ]);
+    const drift = [];
+    for (const tag of tags) {
+        const server = capture.serverTags[tag] ?? 0;
+        const client = capture.clientTags[tag] ?? 0;
+        if (Math.abs(client - server) >= TAG_DRIFT_MIN) {
+            drift.push({ tag, server, client });
+        }
+    }
+    drift.sort((a, b) => Math.abs(b.client - b.server) - Math.abs(a.client - a.server));
+    // The framework saying hydration failed, or server content a
+    // person was sent no longer being there, is a failure. Content
+    // that only appeared is a warning: a client-only widget is
+    // legitimate, and this cannot tell it from a bug.
+    const standing = warnings.length > 0 || vanished.length > 0
+        ? "fail"
+        : appeared.length > 0 || drift.length > 0
+            ? "warn"
+            : "pass";
+    return { ...base, standing, vanished, appeared, drift, shell: false };
+}
+/** How many texts to name per list before counting the rest. */
+const MAX_LISTED = 5;
+function listed(texts) {
+    const lines = texts.slice(0, MAX_LISTED).map((text) => `    "${text}"`);
+    if (texts.length > MAX_LISTED) {
+        lines.push(`    ... and ${texts.length - MAX_LISTED} more.`);
+    }
+    return lines;
+}
+/** Say whether the server render survived hydration. */
+export function renderHydration(report) {
+    if (!report.fetched) {
+        return renderVerdict({
+            standing: report.standing,
+            headline: report.warnings.length > 0
+                ? "The console complained about hydration, and the server " +
+                    "render could not be fetched to say what diverged."
+                : "The server render could not be fetched, so nothing " +
+                    "was compared.",
+            measured: `Fetching the page's own URL from inside it ` +
+                `${report.status === undefined ? "threw" : `answered ${report.status}`}. ` +
+                `The comparison needs the HTML the server sends before ` +
+                `any script runs.`,
+        }, report.warnings.map((line) => `  ${line}`).join("\n"));
+    }
+    if (report.shell) {
+        return renderVerdict({
+            standing: report.standing,
+            headline: "The page is client-rendered: the server sends a shell, " +
+                "so there is no server render to hold the page to.",
+            measured: "Hydration cannot mismatch when nothing is hydrated; " +
+                "whether a shell is acceptable here is a judgment call, " +
+                "so this is not a pass.",
+        }, report.warnings.map((line) => `  ${line}`).join("\n"));
+    }
+    const parts = [];
+    if (report.warnings.length > 0) {
+        parts.push(`The framework complained during hydration:`, ...report.warnings.map((line) => `    ${line}`));
+    }
+    if (report.vanished.length > 0) {
+        parts.push(`Server content gone after hydration ` +
+            `(${count(report.vanished.length, "text")}):`, ...listed(report.vanished));
+    }
+    if (report.appeared.length > 0) {
+        parts.push(`Content that only exists after hydration ` +
+            `(${count(report.appeared.length, "text")}):`, ...listed(report.appeared));
+    }
+    if (report.drift.length > 0) {
+        parts.push("Element counts that moved:", ...report.drift.map((one) => `    <${one.tag}>  ${one.server} on the server, ` +
+            `${one.client} after hydration`));
+    }
+    const headline = report.standing === "pass"
+        ? "The hydrated page says what the server sent."
+        : report.standing === "fail"
+            ? report.warnings.length > 0
+                ? "The framework itself reported a hydration failure."
+                : `${count(report.vanished.length, "server text")} ` +
+                    `vanished during hydration.`
+            : `The renders agree on shared content, but ` +
+                `${count(report.appeared.length, "text")} and ` +
+                `${count(report.drift.length, "tag count", "tag counts")} ` +
+                `exist only after hydration.`;
+    return renderVerdict({
+        standing: report.standing,
+        headline,
+        measured: "Compared the HTML the server sends, parsed without running " +
+            "a script, against the live document. A page that renders " +
+            "the time or a locale will differ between the two fetches; " +
+            "paired vanished and appeared texts of the same shape are " +
+            "that, not a bug.",
+    }, parts.join("\n"));
+}

package/dist/web/index.d.ts

@@ -21,6 +21,7 @@
  * - `envelope/`  paging, budgets and the on-disk artifact sink
  * - `environment/` emulation, storage, network shaping, status
  * - `evaluate/`  running an expression and surviving the result
+ * - `hydration/` whether the server render survived hydration
  * - `input/`     key chords, pointer paths, touch gestures
  * - `perf/`      web vitals from the browser's own observers
  * - `snapshot/`  the whole page flattened, frames and shadow

package/dist/web/index.js

@@ -21,6 +21,7 @@
  * - `envelope/`  paging, budgets and the on-disk artifact sink
  * - `environment/` emulation, storage, network shaping, status
  * - `evaluate/`  running an expression and surviving the result
+ * - `hydration/` whether the server render survived hydration
  * - `input/`     key chords, pointer paths, touch gestures
  * - `perf/`      web vitals from the browser's own observers
  * - `snapshot/`  the whole page flattened, frames and shadow

package/dist/web/perf/index.d.ts

@@ -11,4 +11,4 @@ export { observerBootstrap, readVitalsSource } from "./probe.js";
 export { foldProfile, type Hotspot, type Hotspots, type RawProfile, type RawProfileNode, renderHotspots, } from "./profile.js";
 export { categoriesFor, type FrameStory, foldTrace, type RawTraceEvent, type RequestSpan, renderTrace, type TaskCost, type TimerStory, TRACE_CATEGORIES, type TraceCapture, type TraceProfile, } from "./trace.js";
 export { renderVitals } from "./view.js";
-export { cumulativeShift, type LongTask, type Measure, measure, type Rating, rate, SESSION_CAP_MS, SESSION_GAP_MS, type Shift, THRESHOLDS, type Vitals, worstShiftSources, } from "./vitals.js";
+export { cumulativeShift, type LongTask, type Measure, measure, measureSamples, type Rating, rate, SESSION_CAP_MS, SESSION_GAP_MS, type Shift, type Spread, THRESHOLDS, type Vitals, worstShiftSources, } from "./vitals.js";

package/dist/web/perf/index.js

@@ -11,4 +11,4 @@ export { observerBootstrap, readVitalsSource } from "./probe.js";
 export { foldProfile, renderHotspots, } from "./profile.js";
 export { categoriesFor, foldTrace, renderTrace, TRACE_CATEGORIES, } from "./trace.js";
 export { renderVitals } from "./view.js";
-export { cumulativeShift, measure, rate, SESSION_CAP_MS, SESSION_GAP_MS, THRESHOLDS, worstShiftSources, } from "./vitals.js";
+export { cumulativeShift, measure, measureSamples, rate, SESSION_CAP_MS, SESSION_GAP_MS, THRESHOLDS, worstShiftSources, } from "./vitals.js";