@jitsusama/agentic-harness.core 0.1.0 → 0.3.0

package/dist/web/audit/motion.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Whether the page honours a request for reduced motion.
+ *
+ * The preference is the one accessibility setting a page can
+ * ignore without failing a single axe rule: the markup is fine,
+ * the contrast is fine, and the page is still unusable for the
+ * person who asked it to hold still. The only way to know is to
+ * ask for reduce and then look at what is still moving, which is
+ * what this module judges from a capture taken under emulation.
+ *
+ * The analysis is pure and takes serialized data, like every
+ * other audit here: nothing in this file can start a browser.
+ *
+ * Adapted from the reduced-motion conventions in Carolyn
+ * McNeillie's review-page skill set, which treats a page that
+ * ignores the preference outright as one of the few
+ * symptom-only blockers: user-observable, confirmed from the
+ * capture, no mechanism claim required.
+ */
+import type { A11yFinding } from "./axe.js";
+/** A video as the page reported it under reduce. */
+export interface MotionVideo {
+    readonly selector: string;
+    readonly html: string;
+    readonly playing: boolean;
+    readonly autoplay: boolean;
+    readonly loop: boolean;
+    readonly controls: boolean;
+    readonly visible: boolean;
+}
+/** An animation as the page reported it under reduce. */
+export interface MotionAnimation {
+    readonly selector: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly playState: string;
+    /** May be absent when the effect reports no timing. */
+    readonly durationMs?: number;
+    /**
+     * Repeats, as text: Infinity does not survive serialization,
+     * so the page sends the word.
+     */
+    readonly iterations: string;
+    /** Driven by scroll rather than by time. */
+    readonly scroll: boolean;
+}
+/** What the page was doing while asked to hold still. */
+export interface MotionCapture {
+    /** Whether the page actually saw the reduce preference. */
+    readonly reduced: boolean;
+    readonly videos: readonly MotionVideo[];
+    readonly animations: readonly MotionAnimation[];
+}
+/**
+ * Animations at or under this total runtime are left alone.
+ *
+ * The preference asks for less motion, not none: a brief fade is
+ * how a page avoids a jarring pop, and flagging every 150ms
+ * transition would bury the marquee that never stops.
+ */
+export declare const BRIEF_MS = 250;
+/**
+ * Motion running longer than this needs a way to stop.
+ *
+ * The five second line is WCAG 2.2.2's own: moving content that
+ * starts automatically and lasts longer than five seconds must
+ * have a mechanism to pause, stop or hide it.
+ */
+export declare const PAUSE_STOP_HIDE_MS = 5000;
+/**
+ * Judge a capture taken under reduced motion.
+ *
+ * An empty answer from a capture where the page never saw the
+ * preference would be a lie, so a capture with reduced false
+ * produces a single needs-review finding naming the problem
+ * instead of a clean pass.
+ */
+export declare function analyseMotion(capture: MotionCapture): readonly A11yFinding[];
+/**
+ * The expression that reads what is moving, run in the page
+ * while reduce is emulated.
+ *
+ * Selectors are built the same way the other captures build
+ * them: something a person could paste into the console, never a
+ * retained node.
+ */
+export declare const MOTION_CAPTURE = "(() => {\n\tconst selectorFor = (el) => {\n\t\tif (!el || !el.tagName) return \"(detached)\";\n\t\tconst tag = el.tagName.toLowerCase();\n\t\tif (el.id) return \"#\" + el.id;\n\t\tconst hook = el.getAttribute && el.getAttribute(\"data-testid\");\n\t\tif (hook) return tag + '[data-testid=\"' + hook + '\"]';\n\t\tconst first = el.classList && el.classList[0];\n\t\tif (first) return tag + \".\" + first;\n\t\treturn tag;\n\t};\n\n\tconst videos = [...document.querySelectorAll(\"video\")].map((video) => ({\n\t\tselector: selectorFor(video),\n\t\thtml: video.outerHTML.slice(0, 160),\n\t\tplaying:\n\t\t\t!video.paused && !video.ended && video.readyState > 2,\n\t\tautoplay: video.autoplay,\n\t\tloop: video.loop,\n\t\tcontrols: video.controls,\n\t\tvisible: video.getClientRects().length > 0,\n\t}));\n\n\tconst animations = document.getAnimations\n\t\t? document.getAnimations({ subtree: true }).map((animation) => {\n\t\t\t\tconst effect = animation.effect;\n\t\t\t\tconst timing = effect && effect.getTiming ? effect.getTiming() : {};\n\t\t\t\tconst duration =\n\t\t\t\t\ttypeof timing.duration === \"number\" ? timing.duration : undefined;\n\t\t\t\tconst target = effect && effect.target ? effect.target : null;\n\t\t\t\treturn {\n\t\t\t\t\tselector: selectorFor(target),\n\t\t\t\t\tname:\n\t\t\t\t\t\tanimation.animationName ||\n\t\t\t\t\t\tanimation.transitionProperty ||\n\t\t\t\t\t\tanimation.id ||\n\t\t\t\t\t\t\"unnamed\",\n\t\t\t\t\tkind: animation.constructor.name,\n\t\t\t\t\tplayState: animation.playState,\n\t\t\t\t\t...(duration === undefined ? {} : { durationMs: duration }),\n\t\t\t\t\titerations: String(timing.iterations === undefined ? 1 : timing.iterations),\n\t\t\t\t\tscroll: !!(\n\t\t\t\t\t\tanimation.timeline &&\n\t\t\t\t\t\tanimation.timeline.constructor.name !== \"DocumentTimeline\"\n\t\t\t\t\t),\n\t\t\t\t};\n\t\t\t})\n\t\t: [];\n\n\treturn {\n\t\treduced: matchMedia(\"(prefers-reduced-motion: reduce)\").matches,\n\t\tvideos,\n\t\tanimations,\n\t};\n})()";

package/dist/web/audit/motion.js

@@ -0,0 +1,239 @@
+/**
+ * Whether the page honours a request for reduced motion.
+ *
+ * The preference is the one accessibility setting a page can
+ * ignore without failing a single axe rule: the markup is fine,
+ * the contrast is fine, and the page is still unusable for the
+ * person who asked it to hold still. The only way to know is to
+ * ask for reduce and then look at what is still moving, which is
+ * what this module judges from a capture taken under emulation.
+ *
+ * The analysis is pure and takes serialized data, like every
+ * other audit here: nothing in this file can start a browser.
+ *
+ * Adapted from the reduced-motion conventions in Carolyn
+ * McNeillie's review-page skill set, which treats a page that
+ * ignores the preference outright as one of the few
+ * symptom-only blockers: user-observable, confirmed from the
+ * capture, no mechanism claim required.
+ */
+/**
+ * Animations at or under this total runtime are left alone.
+ *
+ * The preference asks for less motion, not none: a brief fade is
+ * how a page avoids a jarring pop, and flagging every 150ms
+ * transition would bury the marquee that never stops.
+ */
+export const BRIEF_MS = 250;
+/**
+ * Motion running longer than this needs a way to stop.
+ *
+ * The five second line is WCAG 2.2.2's own: moving content that
+ * starts automatically and lasts longer than five seconds must
+ * have a mechanism to pause, stop or hide it.
+ */
+export const PAUSE_STOP_HIDE_MS = 5000;
+/** Total runtime, or none for an animation that never ends. */
+function totalMs(animation) {
+    if (animation.iterations === "Infinity")
+        return undefined;
+    if (animation.durationMs === undefined)
+        return undefined;
+    const repeats = Number(animation.iterations);
+    if (!Number.isFinite(repeats))
+        return undefined;
+    return animation.durationMs * repeats;
+}
+function videoNode(video, message) {
+    return { selector: video.selector, html: video.html, messages: [message] };
+}
+function animationNode(animation, message) {
+    return {
+        selector: animation.selector,
+        html: "",
+        messages: [message],
+    };
+}
+/**
+ * Judge a capture taken under reduced motion.
+ *
+ * An empty answer from a capture where the page never saw the
+ * preference would be a lie, so a capture with reduced false
+ * produces a single needs-review finding naming the problem
+ * instead of a clean pass.
+ */
+export function analyseMotion(capture) {
+    if (!capture.reduced) {
+        return [
+            {
+                rule: "reduced-motion-not-emulated",
+                kind: "needs-review",
+                impact: "moderate",
+                authority: "best-practice",
+                criteria: [],
+                levels: [],
+                help: "The page never saw prefers-reduced-motion: reduce, so " +
+                    "nothing here was judged. The emulation did not take; " +
+                    "nothing can be said about how the page behaves for a " +
+                    "person who asked it to hold still.",
+                nodes: [],
+            },
+        ];
+    }
+    const findings = [];
+    const playing = capture.videos.filter((video) => video.visible && video.playing);
+    const unstoppable = playing.filter((video) => !video.controls);
+    if (unstoppable.length > 0) {
+        findings.push({
+            rule: "video-plays-under-reduced-motion",
+            kind: "violation",
+            impact: "serious",
+            authority: "wcag",
+            criteria: ["2.2.2"],
+            levels: ["A"],
+            help: "Video still playing with no controls while the page was " +
+                "asked for reduced motion. Auto-playing movement that " +
+                "cannot be paused, stopped or hidden fails 2.2.2, and " +
+                "playing it at all ignores the stated preference.",
+            nodes: unstoppable.map((video) => videoNode(video, video.loop
+                ? "playing on a loop, no controls to stop it"
+                : "playing, no controls to stop it")),
+        });
+    }
+    const pausable = playing.filter((video) => video.controls);
+    if (pausable.length > 0) {
+        findings.push({
+            rule: "video-ignores-reduced-motion",
+            kind: "violation",
+            impact: "moderate",
+            authority: "best-practice",
+            criteria: [],
+            levels: [],
+            help: "Video plays automatically under reduced motion. It has " +
+                "controls, so 2.2.2 is met, but the preference asked the " +
+                "page not to start the motion in the first place.",
+            nodes: pausable.map((video) => videoNode(video, "autoplays")),
+        });
+    }
+    const running = capture.animations.filter((animation) => animation.playState === "running");
+    const scrollDriven = running.filter((animation) => animation.scroll);
+    if (scrollDriven.length > 0) {
+        findings.push({
+            rule: "scroll-animation-under-reduced-motion",
+            kind: "violation",
+            impact: "moderate",
+            authority: "wcag",
+            criteria: ["2.3.3"],
+            levels: ["AAA"],
+            help: "Scroll-driven animation still active under reduced " +
+                "motion. Motion triggered by interaction is exactly what " +
+                "2.3.3 says the preference should disable.",
+            nodes: scrollDriven.map((animation) => animationNode(animation, `${animation.name} rides the scroll`)),
+        });
+    }
+    const timed = running.filter((animation) => !animation.scroll);
+    const endlessOrLong = timed.filter((animation) => {
+        const total = totalMs(animation);
+        return total === undefined || total > PAUSE_STOP_HIDE_MS;
+    });
+    if (endlessOrLong.length > 0) {
+        findings.push({
+            rule: "animation-runs-under-reduced-motion",
+            kind: "violation",
+            impact: "serious",
+            authority: "wcag",
+            criteria: ["2.2.2"],
+            levels: ["A"],
+            help: "Animation still running past the five second line while " +
+                "the page was asked for reduced motion. Moving content " +
+                "that starts on its own and runs this long needs a way to " +
+                "pause, stop or hide it, and honouring the preference is " +
+                "the way that costs nothing.",
+            nodes: endlessOrLong.map((animation) => animationNode(animation, animation.iterations === "Infinity"
+                ? `${animation.name} never ends`
+                : `${animation.name} runs ${Math.round((totalMs(animation) ?? 0) / 1000)}s`)),
+        });
+    }
+    const brief = timed.filter((animation) => {
+        const total = totalMs(animation);
+        return (total !== undefined && total > BRIEF_MS && total <= PAUSE_STOP_HIDE_MS);
+    });
+    if (brief.length > 0) {
+        findings.push({
+            rule: "animation-under-reduced-motion",
+            kind: "violation",
+            impact: "minor",
+            authority: "best-practice",
+            criteria: [],
+            levels: [],
+            help: "Animation still running under reduced motion. Each one " +
+                "ends on its own, so no standard is failed; the preference " +
+                "still asked for less of this.",
+            nodes: brief.map((animation) => animationNode(animation, `${animation.name} runs ${totalMs(animation)}ms`)),
+        });
+    }
+    return findings;
+}
+/**
+ * The expression that reads what is moving, run in the page
+ * while reduce is emulated.
+ *
+ * Selectors are built the same way the other captures build
+ * them: something a person could paste into the console, never a
+ * retained node.
+ */
+export const MOTION_CAPTURE = `(() => {
+	const selectorFor = (el) => {
+		if (!el || !el.tagName) return "(detached)";
+		const tag = el.tagName.toLowerCase();
+		if (el.id) return "#" + el.id;
+		const hook = el.getAttribute && el.getAttribute("data-testid");
+		if (hook) return tag + '[data-testid="' + hook + '"]';
+		const first = el.classList && el.classList[0];
+		if (first) return tag + "." + first;
+		return tag;
+	};
+
+	const videos = [...document.querySelectorAll("video")].map((video) => ({
+		selector: selectorFor(video),
+		html: video.outerHTML.slice(0, 160),
+		playing:
+			!video.paused && !video.ended && video.readyState > 2,
+		autoplay: video.autoplay,
+		loop: video.loop,
+		controls: video.controls,
+		visible: video.getClientRects().length > 0,
+	}));
+
+	const animations = document.getAnimations
+		? document.getAnimations({ subtree: true }).map((animation) => {
+				const effect = animation.effect;
+				const timing = effect && effect.getTiming ? effect.getTiming() : {};
+				const duration =
+					typeof timing.duration === "number" ? timing.duration : undefined;
+				const target = effect && effect.target ? effect.target : null;
+				return {
+					selector: selectorFor(target),
+					name:
+						animation.animationName ||
+						animation.transitionProperty ||
+						animation.id ||
+						"unnamed",
+					kind: animation.constructor.name,
+					playState: animation.playState,
+					...(duration === undefined ? {} : { durationMs: duration }),
+					iterations: String(timing.iterations === undefined ? 1 : timing.iterations),
+					scroll: !!(
+						animation.timeline &&
+						animation.timeline.constructor.name !== "DocumentTimeline"
+					),
+				};
+			})
+		: [];
+
+	return {
+		reduced: matchMedia("(prefers-reduced-motion: reduce)").matches,
+		videos,
+		animations,
+	};
+})()`;

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

@@ -7,3 +7,4 @@
  */
 export { type Cluster, COLOUR_SAMENESS, canonicalLengths, clusterUsage, coloursAreNear, DIMENSIONS, type Dimension, exactlyEqual, LENGTH_SAMENESS, lengthsAreNear, type Nearness, renderInventory, type StyleSample, takeInventory, tallyUsage, type Usage, } from "./inventory.js";
 export { inventorySource, SAMPLED_PROPERTIES } from "./probe.js";
+export { analyseTypography, BODY_FLOOR_CHARS, RUNT_MAX_WORDS, RUNT_WIDTH_SHARE, renderTypography, type TextBlock, TYPOGRAPHY_CAPTURE, type TypographyFinding, } from "./typography.js";

package/dist/web/design/index.js

@@ -7,3 +7,4 @@
  */
 export { COLOUR_SAMENESS, canonicalLengths, clusterUsage, coloursAreNear, DIMENSIONS, exactlyEqual, LENGTH_SAMENESS, lengthsAreNear, renderInventory, takeInventory, tallyUsage, } from "./inventory.js";
 export { inventorySource, SAMPLED_PROPERTIES } from "./probe.js";
+export { analyseTypography, BODY_FLOOR_CHARS, RUNT_MAX_WORDS, RUNT_WIDTH_SHARE, renderTypography, TYPOGRAPHY_CAPTURE, } from "./typography.js";

package/dist/web/design/typography.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+/** One text-bearing block, as the page measured it. */
+export interface TextBlock {
+    readonly selector: string;
+    readonly tag: string;
+    readonly textLength: number;
+    /** The width the text had to work with, in pixels. */
+    readonly containerWidth: number;
+    readonly lineCount: number;
+    readonly lastLine: {
+        readonly words: number;
+        /** How wide the last line's ink actually is. */
+        readonly width: number;
+        /** The line itself, clipped. */
+        readonly text: string;
+    };
+}
+/** A block that ends badly, and how. */
+export interface TypographyFinding {
+    /** orphan: one word alone. runt: a stub of a last line. */
+    readonly kind: "orphan" | "runt";
+    /** Heading orphans read worst, so the caller may sort by this. */
+    readonly heading: boolean;
+    readonly block: TextBlock;
+}
+/** Body text shorter than this is skipped in the capture. */
+export declare const BODY_FLOOR_CHARS = 80;
+/** A last line of this many words or fewer can be a runt. */
+export declare const RUNT_MAX_WORDS = 3;
+/** ...when it fills less than this share of the container. */
+export declare const RUNT_WIDTH_SHARE = 0.25;
+/**
+ * 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 declare function analyseTypography(blocks: readonly TextBlock[]): readonly TypographyFinding[];
+/** Say how the page's text blocks end. */
+export declare function renderTypography(blocks: readonly TextBlock[], findings: readonly TypographyFinding[]): string;
+/**
+ * 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 declare const TYPOGRAPHY_CAPTURE = "(() => {\n\tconst BODY_FLOOR = 80;\n\tconst MAX_TEXT = 80;\n\n\tconst selectorFor = (el) => {\n\t\tconst tag = el.tagName.toLowerCase();\n\t\tif (el.id) return \"#\" + el.id;\n\t\tconst hook = el.getAttribute(\"data-testid\");\n\t\tif (hook) return tag + '[data-testid=\"' + hook + '\"]';\n\t\tconst first = el.classList[0];\n\t\tif (first) return tag + \".\" + first;\n\t\treturn tag;\n\t};\n\n\tconst visualLines = (element) => {\n\t\tconst walker = document.createTreeWalker(\n\t\t\telement,\n\t\t\tNodeFilter.SHOW_TEXT,\n\t\t\tnull,\n\t\t);\n\t\tconst nodes = [];\n\t\twhile (walker.nextNode()) {\n\t\t\tif (walker.currentNode.textContent.trim()) {\n\t\t\t\tnodes.push(walker.currentNode);\n\t\t\t}\n\t\t}\n\t\tconst range = document.createRange();\n\t\tconst lines = [];\n\t\tlet top = null;\n\t\tlet height = 0;\n\t\tlet words = 0;\n\t\tlet left = Infinity;\n\t\tlet right = -Infinity;\n\t\tlet text = \"\";\n\t\tconst flush = () => {\n\t\t\tif (words > 0) {\n\t\t\t\tlines.push({ words, width: right - left, text });\n\t\t\t}\n\t\t\twords = 0;\n\t\t\tleft = Infinity;\n\t\t\tright = -Infinity;\n\t\t\ttext = \"\";\n\t\t};\n\t\tfor (const node of nodes) {\n\t\t\tconst content = node.textContent;\n\t\t\tconst matcher = /\\S+/g;\n\t\t\tlet match = matcher.exec(content);\n\t\t\twhile (match) {\n\t\t\t\trange.setStart(node, match.index);\n\t\t\t\trange.setEnd(node, match.index + match[0].length);\n\t\t\t\tconst rect = range.getBoundingClientRect();\n\t\t\t\tif (rect.width > 0 || rect.height > 0) {\n\t\t\t\t\tconst sameLine =\n\t\t\t\t\t\ttop !== null && Math.abs(rect.top - top) <= height / 2;\n\t\t\t\t\tif (!sameLine) {\n\t\t\t\t\t\tflush();\n\t\t\t\t\t\ttop = rect.top;\n\t\t\t\t\t\theight = rect.height;\n\t\t\t\t\t}\n\t\t\t\t\twords += 1;\n\t\t\t\t\tleft = Math.min(left, rect.left);\n\t\t\t\t\tright = Math.max(right, rect.right);\n\t\t\t\t\tif (text.length < MAX_TEXT) {\n\t\t\t\t\t\ttext = (text ? text + \" \" : \"\") + match[0];\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tmatch = matcher.exec(content);\n\t\t\t}\n\t\t}\n\t\tflush();\n\t\treturn lines;\n\t};\n\n\tconst wrapStyle = (el) => {\n\t\tconst style = getComputedStyle(el);\n\t\treturn style.textWrap || style.textWrapStyle || \"\";\n\t};\n\n\tconst candidates = document.querySelectorAll(\n\t\t\"p, h1, h2, h3, h4, h5, h6, figcaption\",\n\t);\n\tconst blocks = [];\n\tfor (const el of candidates) {\n\t\tif (el.getClientRects().length === 0) continue;\n\t\tconst tag = el.tagName.toLowerCase();\n\t\tconst textLength = (el.innerText || \"\").trim().length;\n\t\tif (textLength === 0) continue;\n\t\t// Headings matter most and are short; body text below the\n\t\t// floor has no room for a wrap worth judging.\n\t\tconst heading = tag[0] === \"h\";\n\t\tif (!heading && textLength < BODY_FLOOR) continue;\n\t\t// The author already asked the browser to mind the wrapping.\n\t\tconst wrap = wrapStyle(el);\n\t\tif (wrap.includes(\"balance\") || wrap.includes(\"pretty\")) continue;\n\t\t// Text inside a collapsed disclosure is not laid out.\n\t\tconst details = el.closest(\"details\");\n\t\tif (details && !details.open) continue;\n\t\tconst lines = visualLines(el);\n\t\tconst last = lines[lines.length - 1];\n\t\tif (!last) continue;\n\t\tblocks.push({\n\t\t\tselector: selectorFor(el),\n\t\t\ttag,\n\t\t\ttextLength,\n\t\t\tcontainerWidth: el.clientWidth,\n\t\t\tlineCount: lines.length,\n\t\t\tlastLine: {\n\t\t\t\twords: last.words,\n\t\t\t\twidth: last.width,\n\t\t\t\ttext: last.text.slice(0, MAX_TEXT),\n\t\t\t},\n\t\t});\n\t}\n\treturn blocks;\n})()";

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})()";