@jitsusama/agentic-harness.core 0.1.0 → 0.2.0

package/dist/bin/cli.js

@@ -27,6 +27,7 @@ import { runNotesAction } from "./notes.js";
 import { processExec } from "./process-exec.js";
 import { runQuestAction } from "./quest.js";
 import { runSlackAuthLogin, runSlackAuthStatus } from "./slack-auth.js";
+import { runWebCheck } from "./web.js";
 /** Where a loop's state lives when the caller doesn't override it. */
 const DEFAULT_STATE_FILE = ".agentic-harness/tdd-loop.json";
 /** Where quest state lives when the caller doesn't override it. */
@@ -218,6 +219,12 @@ async function main() {
             return;
         }
     }
+    if (options.domain === "web" && options.command === "check") {
+        const result = await runWebCheck(await readStdin());
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        process.exitCode = result.ok ? 0 : 1;
+        return;
+    }
     if (options.domain === "slack-auth") {
         if (options.command === "status") {
             process.stdout.write(`${JSON.stringify(await runSlackAuthStatus())}\n`);

package/dist/bin/web.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The web check commands: one browser, one page, one verdict.
+ *
+ * This is the CLI adapter for the judgment checks a hook-and-skill
+ * consumer cannot reach through a library import: it opens a
+ * session, runs one check against one URL and answers JSON with
+ * the same rendered report the pi tools show. Stateless per
+ * invocation like every other command here; the browser lives and
+ * dies inside the call.
+ */
+/** The checks this command knows how to run. */
+export declare const WEB_CHECK_KINDS: readonly ["motion", "typography", "hydration", "perf"];
+/** What arrives on stdin. */
+export interface WebCheckInput {
+    readonly kind: string;
+    readonly url: string;
+    /** For perf: how many loads to sample. Defaults to 3. */
+    readonly samples?: number;
+}
+/** What goes out on stdout. */
+export interface WebCheckOutput {
+    readonly ok: boolean;
+    readonly kind?: string;
+    readonly url?: string;
+    /** The same rendered verdict the pi tools show. */
+    readonly report?: string;
+    readonly error?: string;
+}
+/** Run one web check against one URL. */
+export declare function runWebCheck(raw: string): Promise<WebCheckOutput>;

package/dist/bin/web.js

@@ -0,0 +1,97 @@
+/**
+ * The web check commands: one browser, one page, one verdict.
+ *
+ * This is the CLI adapter for the judgment checks a hook-and-skill
+ * consumer cannot reach through a library import: it opens a
+ * session, runs one check against one URL and answers JSON with
+ * the same rendered report the pi tools show. Stateless per
+ * invocation like every other command here; the browser lives and
+ * dies inside the call.
+ */
+import { tallyFindings } from "../web/audit/index.js";
+import { analyseMotion } from "../web/audit/motion.js";
+import { renderAudit } from "../web/audit/report.js";
+import { analyseTypography, renderTypography, } from "../web/design/typography.js";
+import { judgeHydration, renderHydration } from "../web/hydration/index.js";
+import { measureSamples, renderVitals } from "../web/perf/index.js";
+import { BrowserSession } from "../web/session.js";
+/** The checks this command knows how to run. */
+export const WEB_CHECK_KINDS = [
+    "motion",
+    "typography",
+    "hydration",
+    "perf",
+];
+/** Perf samples when the caller does not say. */
+const DEFAULT_SAMPLES = 3;
+/** The most loads one perf call will pay for. */
+const MAX_SAMPLES = 9;
+function isKind(kind) {
+    return WEB_CHECK_KINDS.includes(kind);
+}
+async function checkOn(session, kind, input) {
+    if (kind === "perf") {
+        const wanted = Math.min(Math.max(1, Math.round(input.samples ?? DEFAULT_SAMPLES)), MAX_SAMPLES);
+        const samples = [await session.vitals()];
+        while (samples.length < wanted) {
+            const { failure } = await session.reload();
+            // A reload that failed ends the sampling rather than the
+            // check: the loads that did land are still a measurement.
+            if (failure)
+                break;
+            samples.push(await session.vitals());
+        }
+        const last = samples[samples.length - 1];
+        return renderVitals(last, measureSamples(samples));
+    }
+    if (kind === "motion") {
+        const findings = analyseMotion(await session.motionUnderReduce());
+        return renderAudit(findings, tallyFindings(findings), {
+            measured: "Emulated prefers-reduced-motion: reduce, reloaded, and read " +
+                "what was still moving.",
+        });
+    }
+    if (kind === "typography") {
+        const blocks = await session.typography();
+        return renderTypography(blocks, analyseTypography(blocks));
+    }
+    const capture = await session.hydration();
+    const lines = session
+        .logs()
+        .entries.map(({ item }) => ({ level: item.level, text: item.text }));
+    return renderHydration(judgeHydration(capture, lines));
+}
+/** Run one web check against one URL. */
+export async function runWebCheck(raw) {
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: "stdin must be JSON: { kind, url }" };
+    }
+    if (!input.url) {
+        return { ok: false, error: "url is required" };
+    }
+    if (!input.kind || !isKind(input.kind)) {
+        return {
+            ok: false,
+            error: `kind must be one of: ${WEB_CHECK_KINDS.join(", ")}`,
+        };
+    }
+    const session = await BrowserSession.open(`web-check-${process.pid}`);
+    try {
+        const { failure, status } = await session.navigate(input.url);
+        if (failure) {
+            return { ok: false, error: `Could not load ${input.url}: ${failure}` };
+        }
+        if (status !== undefined && status >= 400) {
+            return { ok: false, error: `${input.url} answered ${status}` };
+        }
+        const report = await checkOn(session, input.kind, input);
+        return { ok: true, kind: input.kind, url: input.url, report };
+    }
+    finally {
+        await session.close();
+    }
+}

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

@@ -12,6 +12,7 @@ export { type AxFacts, buildStructure, selectorFor, } from "./capture.js";
 export { composite, contrastRatio, deltaE, formatRgb, isOpaque, isTransparent, parseRgb, type Rgba, relativeLuminance, } from "./colour.js";
 export { BOLD_WEIGHT, type ContrastLevel, type ContrastVerdict, isLargeText, judgeNonText, judgeText, LARGE_BOLD_PX, LARGE_TEXT_PX, NON_TEXT_MINIMUM, renderContrast, type TextSizing, textThreshold, undecidable, } from "./contrast.js";
 export { overallOf, type Part, renderHealth } from "./health.js";
+export { analyseMotion, BRIEF_MS, MOTION_CAPTURE, type MotionAnimation, type MotionCapture, type MotionVideo, PAUSE_STOP_HIDE_MS, } from "./motion.js";
 export { foldPair, type PaintedSide, type PairReport, renderPair, } from "./pair.js";
 export { TARGET_CAPTURE, visualCaptureSource } from "./probe.js";
 export { MAX_LISTED_NODES, renderAudit, renderFinding, renderIndex, renderSummary, } from "./report.js";

package/dist/web/audit/index.js

@@ -12,6 +12,7 @@ export { buildStructure, selectorFor, } from "./capture.js";
 export { composite, contrastRatio, deltaE, formatRgb, isOpaque, isTransparent, parseRgb, relativeLuminance, } from "./colour.js";
 export { BOLD_WEIGHT, isLargeText, judgeNonText, judgeText, LARGE_BOLD_PX, LARGE_TEXT_PX, NON_TEXT_MINIMUM, renderContrast, textThreshold, undecidable, } from "./contrast.js";
 export { overallOf, renderHealth } from "./health.js";
+export { analyseMotion, BRIEF_MS, MOTION_CAPTURE, PAUSE_STOP_HIDE_MS, } from "./motion.js";
 export { foldPair, renderPair, } from "./pair.js";
 export { TARGET_CAPTURE, visualCaptureSource } from "./probe.js";
 export { MAX_LISTED_NODES, renderAudit, renderFinding, renderIndex, renderSummary, } from "./report.js";

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