@jitsusama/agentic-harness.core 0.1.0

package/dist/web/mermaid.js

@@ -0,0 +1,223 @@
+/**
+ * Mermaid diagram rendering.
+ *
+ * Renders Mermaid source to two artifacts: the vector SVG Mermaid
+ * produces (crisp at any zoom, the human's readable copy) and a PNG
+ * rasterized from it (the portable raster and the inline image a vision
+ * model sees). The PNG is scaled to sit just under the vision-model
+ * pixel cap, because sending a larger image only makes the API
+ * downscale and blur the text server-side. Rendering rides the shared
+ * browser lifecycle from browser.ts rather than launching its own, so
+ * it inherits the same teardown.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { newPage } from "./browser.js";
+/** Pinned Mermaid version, fetched once from jsDelivr. */
+const MERMAID_CDN = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js";
+/** How long to wait for the one-time Mermaid library fetch. */
+const MERMAID_FETCH_TIMEOUT_MS = 15_000;
+/**
+ * Longest-edge cap for the rasterized PNG, in pixels. Matches the Opus
+ * 4.7-plus vision budget; larger images are downscaled server-side.
+ */
+const PNG_MAX_LONG_EDGE = 2576;
+/**
+ * Total-area cap for the rasterized PNG, in pixels (~3.75 megapixels,
+ * the Opus 4.7-plus budget). A squarish diagram hits this before the
+ * long-edge cap; a wide one hits the long edge first.
+ */
+const PNG_MAX_PIXELS = 3_750_000;
+/**
+ * Largest factor we upscale a small diagram by. Rasterizing a vector at
+ * scale keeps text crisp, but chasing the cap for a tiny diagram would
+ * bloat it to no benefit, so the upscale is bounded.
+ */
+const PNG_MAX_UPSCALE = 4;
+/**
+ * Compute the raster scale for a diagram of the given intrinsic size so
+ * the PNG lands as close to the pixel budget as possible without
+ * crossing the long-edge or total-area cap. A diagram already larger
+ * than the cap is scaled down to fit; a smaller one is scaled up to the
+ * upscale ceiling so its text stays crisp.
+ */
+export function pngRenderScale({ width, height }) {
+    if (width <= 0 || height <= 0)
+        return 1;
+    const edgeScale = PNG_MAX_LONG_EDGE / Math.max(width, height);
+    const areaScale = Math.sqrt(PNG_MAX_PIXELS / (width * height));
+    const capScale = Math.min(edgeScale, areaScale);
+    if (capScale < 1)
+        return capScale;
+    return Math.min(capScale, PNG_MAX_UPSCALE);
+}
+/**
+ * Final integer PNG dimensions for a diagram of the given intrinsic
+ * size. The continuous scale is chosen so the unrounded box fits the
+ * budget; flooring to whole pixels can only shrink it, so the returned
+ * dimensions never cross the long-edge or total-area cap even after
+ * integerization (which independent rounding would not guarantee).
+ */
+export function pngPixelSize({ width, height }) {
+    const scale = pngRenderScale({ width, height });
+    return {
+        width: Math.max(1, Math.floor(width * scale)),
+        height: Math.max(1, Math.floor(height * scale)),
+    };
+}
+/** The Mermaid library source, fetched once and reused per process. */
+let cachedMermaidSource;
+/**
+ * Fetch the Mermaid library source once, in Node, and cache it.
+ * Injecting the cached content into the render page means the page
+ * itself does no network work mid-render, which is what made
+ * rendering hang under a busy shared browser.
+ */
+export async function loadMermaidSource(fetchImpl = fetch) {
+    if (cachedMermaidSource)
+        return cachedMermaidSource;
+    let response;
+    try {
+        response = await fetchImpl(MERMAID_CDN, {
+            signal: AbortSignal.timeout(MERMAID_FETCH_TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new MermaidRenderError("Could not fetch the Mermaid library (network required). " +
+            "Rendering needs internet access to fetch Mermaid.");
+    }
+    if (!response.ok) {
+        throw new MermaidRenderError(`Could not fetch the Mermaid library (HTTP ${response.status}).`);
+    }
+    cachedMermaidSource = await response.text();
+    return cachedMermaidSource;
+}
+/** Thrown when Mermaid source cannot be rendered (bad syntax or no library). */
+export class MermaidRenderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MermaidRenderError";
+    }
+}
+/** Default output path for a rendered diagram when the caller gives none. */
+function defaultOutputPath() {
+    const id = crypto.randomBytes(6).toString("hex");
+    const dir = path.join(os.tmpdir(), "pi-mermaid");
+    fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, `${id}.png`);
+}
+/** Sibling SVG path for a PNG output path, sharing the base name. */
+function svgPathFor(pngPath) {
+    const parsed = path.parse(pngPath);
+    return path.join(parsed.dir, `${parsed.name}.svg`);
+}
+/** True when a value is a finite number greater than zero. */
+function isPositiveFinite(n) {
+    return typeof n === "number" && Number.isFinite(n) && n > 0;
+}
+/**
+ * Render Mermaid source to an SVG and a PNG on disk and return their
+ * paths plus a base64 copy of the PNG and its final dimensions. The SVG
+ * is the vector artifact (crisp at any zoom); the PNG is rasterized from
+ * it, scaled toward the vision-model pixel budget (up to an upscale
+ * ceiling) without crossing it. The output path must name the PNG; the
+ * SVG is written beside it with the same base name. Reuses the shared
+ * headless browser. Throws MermaidRenderError when the library cannot
+ * load, the path is not a PNG, or the source is invalid.
+ */
+export async function renderMermaid(source, outputPath) {
+    const pngPath = outputPath ?? defaultOutputPath();
+    if (!pngPath.toLowerCase().endsWith(".png")) {
+        throw new MermaidRenderError("render_mermaid output path must end in .png; the SVG is " +
+            "written beside it with the same base name.");
+    }
+    const svgPath = svgPathFor(pngPath);
+    const page = await newPage();
+    try {
+        await page.setContent('<!doctype html><html><body style="margin:0;background:#ffffff">' +
+            '<div id="container"></div></body></html>');
+        const mermaidSource = await loadMermaidSource();
+        try {
+            await page.addScriptTag({ content: mermaidSource });
+        }
+        catch {
+            throw new MermaidRenderError("Could not load the Mermaid library into the render page.");
+        }
+        const rendered = await page.evaluate(async (src) => {
+            // biome-ignore lint/suspicious/noExplicitAny: window.mermaid is injected at runtime.
+            const mermaid = window.mermaid;
+            if (!mermaid)
+                return { error: "Mermaid library did not initialize." };
+            mermaid.initialize({ startOnLoad: false, theme: "default" });
+            try {
+                const { svg } = await mermaid.render("pi-diagram", src);
+                const container = document.getElementById("container");
+                if (!container)
+                    return { error: "Render container missing." };
+                container.innerHTML = svg;
+                const el = container.querySelector("svg");
+                if (!(el instanceof SVGSVGElement)) {
+                    return { error: "Mermaid produced no SVG output." };
+                }
+                // Prefer the viewBox for the true intrinsic size; a Mermaid SVG
+                // carries width:100% and a max-width, so its bounding box can be
+                // clamped to the viewport rather than its natural size.
+                const vb = el.viewBox.baseVal;
+                let width = vb.width;
+                let height = vb.height;
+                if (!width || !height) {
+                    const box = el.getBoundingClientRect();
+                    width = box.width;
+                    height = box.height;
+                }
+                return { svg, width, height };
+            }
+            catch (e) {
+                return { error: e instanceof Error ? e.message : String(e) };
+            }
+        }, source);
+        if (rendered.error || !rendered.svg) {
+            throw new MermaidRenderError(`Mermaid could not render the diagram: ${rendered.error ?? "no SVG output"}`);
+        }
+        const intrinsicWidth = rendered.width;
+        const intrinsicHeight = rendered.height;
+        if (!isPositiveFinite(intrinsicWidth) ||
+            !isPositiveFinite(intrinsicHeight)) {
+            throw new MermaidRenderError("Mermaid produced a diagram with no measurable size.");
+        }
+        // Size the PNG toward the vision-model budget, then pin the SVG to
+        // those pixels and drop its max-width so the capture is not clamped
+        // to the viewport.
+        const { width, height } = pngPixelSize({
+            width: intrinsicWidth,
+            height: intrinsicHeight,
+        });
+        await page.setViewport({ width, height, deviceScaleFactor: 1 });
+        await page.evaluate((w, h) => {
+            const el = document.querySelector("#container svg");
+            if (!(el instanceof SVGElement))
+                return;
+            el.setAttribute("width", String(w));
+            el.setAttribute("height", String(h));
+            el.style.maxWidth = "none";
+        }, width, height);
+        const element = await page.$("#container svg");
+        if (!element) {
+            throw new MermaidRenderError("Mermaid produced no SVG output.");
+        }
+        const shot = await element.screenshot({ type: "png", encoding: "base64" });
+        const base64 = typeof shot === "string" ? shot : Buffer.from(shot).toString("base64");
+        // Commit both artifacts only after a successful capture, so a mid-
+        // render failure never leaves a stray or half-written file on disk.
+        fs.mkdirSync(path.dirname(pngPath), { recursive: true });
+        fs.mkdirSync(path.dirname(svgPath), { recursive: true });
+        fs.writeFileSync(svgPath, rendered.svg, "utf8");
+        fs.writeFileSync(pngPath, Buffer.from(base64, "base64"));
+        return { pngPath, svgPath, base64, width, height };
+    }
+    finally {
+        await page.close();
+    }
+}

package/dist/web/paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where durable browser artifacts (baselines) live on disk by
+ * default, when an adapter does not say otherwise.
+ *
+ * Deliberately adapter-neutral, the same reasoning as memory's own
+ * path: a baseline taken while driving the browser through pi is
+ * still worth comparing against when the same page is later driven
+ * through Claude Code, so the default does not scope itself under
+ * either adapter's own brand. An adapter with its own established
+ * convention (pi's `dataDir("browser-integration")`, predating this
+ * library) passes `dataRoot` on `SessionOptions` instead, so moving
+ * this library out from under it does not orphan baselines already
+ * on disk.
+ */
+/** The default root for durable browser artifacts. */
+export declare function defaultBrowserDataRoot(): string;

package/dist/web/paths.js

@@ -0,0 +1,27 @@
+/**
+ * Where durable browser artifacts (baselines) live on disk by
+ * default, when an adapter does not say otherwise.
+ *
+ * Deliberately adapter-neutral, the same reasoning as memory's own
+ * path: a baseline taken while driving the browser through pi is
+ * still worth comparing against when the same page is later driven
+ * through Claude Code, so the default does not scope itself under
+ * either adapter's own brand. An adapter with its own established
+ * convention (pi's `dataDir("browser-integration")`, predating this
+ * library) passes `dataRoot` on `SessionOptions` instead, so moving
+ * this library out from under it does not orphan baselines already
+ * on disk.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Honours XDG_DATA_HOME; falls back to ~/.local/share per the XDG spec. */
+function xdgDataRoot() {
+    const override = process.env.XDG_DATA_HOME;
+    return override && override.length > 0
+        ? override
+        : join(homedir(), ".local", "share");
+}
+/** The default root for durable browser artifacts. */
+export function defaultBrowserDataRoot() {
+    return join(xdgDataRoot(), "agentic-harness", "browser");
+}

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

@@ -0,0 +1,42 @@
+/**
+ * How much memory the page is holding on to.
+ *
+ * A leak is the one fault none of the other instruments here can
+ * see. Nothing renders wrong, nothing is logged, no request
+ * fails; the tab simply gets slower for an hour and then dies,
+ * and by then whatever caused it is a long way back.
+ *
+ * The measurement is nearly worthless on its own. Uncollected
+ * garbage is indistinguishable from a leak, so a heap that grew
+ * is evidence of nothing unless a collection was forced first.
+ * That is why a reading carries whether it was collected, and why
+ * a comparison says outright when it cannot be trusted.
+ */
+/** One measurement of what the page is holding. */
+export interface HeapReading {
+    readonly usedBytes: number;
+    readonly totalBytes: number;
+    /** Whether a collection was forced before measuring. */
+    readonly collected: boolean;
+    readonly at: number;
+}
+/** Two readings, and what changed between them. */
+export interface HeapComparison {
+    readonly now: HeapReading;
+    readonly before?: HeapReading;
+    /** Bytes gained since the earlier reading; negative if lost. */
+    readonly grewBy?: number;
+    readonly direction: "grew" | "fell" | "steady" | "unknown";
+    /**
+     * Whether the comparison means anything.
+     *
+     * False when either reading was taken without forcing a
+     * collection, because then growth is as likely to be garbage
+     * nobody has swept as memory nobody can free.
+     */
+    readonly trustworthy: boolean;
+}
+/** Compare a reading against an earlier one. */
+export declare function compareHeap(now: HeapReading, before?: HeapReading): HeapComparison;
+/** Say what the page is holding, and whether that is growing. */
+export declare function renderHeap(comparison: HeapComparison): string;

package/dist/web/perf/heap.js

@@ -0,0 +1,73 @@
+/**
+ * How much memory the page is holding on to.
+ *
+ * A leak is the one fault none of the other instruments here can
+ * see. Nothing renders wrong, nothing is logged, no request
+ * fails; the tab simply gets slower for an hour and then dies,
+ * and by then whatever caused it is a long way back.
+ *
+ * The measurement is nearly worthless on its own. Uncollected
+ * garbage is indistinguishable from a leak, so a heap that grew
+ * is evidence of nothing unless a collection was forced first.
+ * That is why a reading carries whether it was collected, and why
+ * a comparison says outright when it cannot be trusted.
+ */
+/**
+ * Growth smaller than this is the runtime breathing, not a leak.
+ *
+ * Even after a forced collection a page's heap moves by tens of
+ * kilobytes between readings, and reporting that as growth would
+ * make every measurement look like a leak.
+ */
+const NOISE = 256 * 1024;
+/** Compare a reading against an earlier one. */
+export function compareHeap(now, before) {
+    if (before === undefined) {
+        // One reading is a number, not a trend. Calling a first
+        // measurement steady would be inventing news.
+        return { now, direction: "unknown", trustworthy: now.collected };
+    }
+    const grewBy = now.usedBytes - before.usedBytes;
+    const direction = Math.abs(grewBy) < NOISE ? "steady" : grewBy > 0 ? "grew" : "fell";
+    return {
+        now,
+        before,
+        grewBy,
+        direction,
+        trustworthy: now.collected && before.collected,
+    };
+}
+/** Bytes as a person reads them. */
+function mb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+/** Say what the page is holding, and whether that is growing. */
+export function renderHeap(comparison) {
+    const { now, before, grewBy, direction } = comparison;
+    const lines = [
+        `Holding ${mb(now.usedBytes)} of ${mb(now.totalBytes)} allocated.`,
+    ];
+    if (before !== undefined && grewBy !== undefined) {
+        if (direction === "steady") {
+            lines.push(`Steady since the last reading, within ${mb(NOISE)} either way.`);
+        }
+        else {
+            const verb = direction === "grew" ? "Grew" : "Fell";
+            lines.push(`${verb} by ${mb(Math.abs(grewBy))} since the last reading.`);
+        }
+    }
+    if (!comparison.trustworthy) {
+        // The single most misleading thing this could do is let a
+        // reader take uncollected garbage for a leak, so the caveat
+        // is not optional and does not get abbreviated.
+        lines.push("Not evidence of a leak: a collection was not forced, so " +
+            "garbage nobody has swept yet is counted the same as memory " +
+            "nobody can free. Take both readings with a collection " +
+            "before comparing them.");
+    }
+    else if (before === undefined) {
+        lines.push("One reading is a number, not a trend. Do the thing you " +
+            "suspect, read again, and compare.");
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,14 @@
+/**
+ * What a page cost the person waiting for it.
+ *
+ * The measurements come from the browser's performance
+ * observers; the arithmetic over them is pure and works on any
+ * capture, live or stored.
+ */
+export { compareHeap, type HeapComparison, type HeapReading, renderHeap, } from "./heap.js";
+export { BYTES_PER_PIXEL, type CompositedLayer, foldLayers, LAYER_SETTLE_MS, type LayerFacts, type LayerReport, nameNode, type RawLayer, type ReasonTally, renderLayers, } from "./layers.js";
+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";

package/dist/web/perf/index.js

@@ -0,0 +1,14 @@
+/**
+ * What a page cost the person waiting for it.
+ *
+ * The measurements come from the browser's performance
+ * observers; the arithmetic over them is pure and works on any
+ * capture, live or stored.
+ */
+export { compareHeap, renderHeap, } from "./heap.js";
+export { BYTES_PER_PIXEL, foldLayers, LAYER_SETTLE_MS, nameNode, renderLayers, } from "./layers.js";
+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";

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

@@ -0,0 +1,98 @@
+/**
+ * What the page asked the compositor to keep.
+ *
+ * A composited layer is a texture the GPU holds so that moving or
+ * fading the thing on it costs no repaint. That trade runs both
+ * ways: too little promotion and an animating element repaints
+ * every frame, too much and the page holds tens of megabytes of
+ * texture it never needed.
+ *
+ * Everything here is Chrome's own account. The layer list arrives
+ * on LayerTree.layerTreeDidChange and the reason for each layer
+ * comes from LayerTree.compositingReasons. No reason is ever
+ * synthesized: measured against Chrome 141, that API returns an
+ * empty list for a genuinely promoted layer, so silence is
+ * reported as silence rather than turned into a guess or, worse,
+ * into a claim the layer was not promoted at all.
+ */
+/** Four bytes to a pixel, which is how a texture is sized. */
+export declare const BYTES_PER_PIXEL = 4;
+/**
+ * How long to let the compositor finish reporting after a frame.
+ *
+ * The tree arrives asynchronously and in more than one instalment
+ * on a busy page, so a read that returns immediately catches a
+ * partial tree.
+ */
+export declare const LAYER_SETTLE_MS = 600;
+/** One layer, as Chrome reports it. */
+export interface RawLayer {
+    readonly layerId: string;
+    readonly parentLayerId?: string;
+    /** The element this layer was made for, when Chrome names one. */
+    readonly backendNodeId?: number;
+    readonly width: number;
+    readonly height: number;
+    readonly paintCount: number;
+    readonly drawsContent: boolean;
+}
+/** A capture of the layer tree and what Chrome said about it. */
+export interface LayerFacts {
+    readonly layers: readonly RawLayer[];
+    /** Chrome's reasons per layer id, which may legitimately be empty. */
+    readonly reasons: Readonly<Record<string, readonly string[]>>;
+    /** How to name the element behind a layer, per layer id. */
+    readonly elements: Readonly<Record<string, string>>;
+}
+/** One layer, folded and ready to report. */
+export interface CompositedLayer {
+    readonly id: string;
+    readonly element?: string;
+    readonly width: number;
+    readonly height: number;
+    readonly paintCount: number;
+    readonly drawsContent: boolean;
+    /** Texture bytes, which is zero for a layer that draws nothing. */
+    readonly memoryBytes: number;
+    readonly reasons: readonly string[];
+    /**
+     * Whether Chrome made this layer for an element.
+     *
+     * The tree also carries structural layers of its own, the root
+     * and the visual viewport among them. Those were never a
+     * promotion decision anybody made, so asking why they exist is
+     * the wrong question to put to them.
+     */
+    readonly forElement: boolean;
+}
+/** How many layers share one reason. */
+export interface ReasonTally {
+    readonly reason: string;
+    readonly count: number;
+}
+/** What the compositor is holding for this page. */
+export interface LayerReport {
+    /** Every layer, heaviest first. */
+    readonly layers: readonly CompositedLayer[];
+    /** How many of them actually paint something. */
+    readonly drawing: number;
+    /** Texture bytes across the layers that draw. */
+    readonly memoryBytes: number;
+    /** Layers Chrome gave no reason for. */
+    readonly unexplained: number;
+    /** Reasons, in order of how many layers each accounts for. */
+    readonly byReason: readonly ReasonTally[];
+}
+/**
+ * Name an element compactly, the way a developer would say it.
+ *
+ * Chrome hands back a tag name and a flat array of alternating
+ * attribute names and values. A tag with its id, or failing that
+ * its first class, is enough to find the thing again without
+ * quoting a whole selector path.
+ */
+export declare function nameNode(nodeName: string, attributes?: readonly string[]): string;
+/** Fold a layer tree capture into what it costs and why it exists. */
+export declare function foldLayers(facts: LayerFacts): LayerReport;
+/** Report what the compositor holds and what put it there. */
+export declare function renderLayers(report: LayerReport): string;

package/dist/web/perf/layers.js

@@ -0,0 +1,165 @@
+/**
+ * What the page asked the compositor to keep.
+ *
+ * A composited layer is a texture the GPU holds so that moving or
+ * fading the thing on it costs no repaint. That trade runs both
+ * ways: too little promotion and an animating element repaints
+ * every frame, too much and the page holds tens of megabytes of
+ * texture it never needed.
+ *
+ * Everything here is Chrome's own account. The layer list arrives
+ * on LayerTree.layerTreeDidChange and the reason for each layer
+ * comes from LayerTree.compositingReasons. No reason is ever
+ * synthesized: measured against Chrome 141, that API returns an
+ * empty list for a genuinely promoted layer, so silence is
+ * reported as silence rather than turned into a guess or, worse,
+ * into a claim the layer was not promoted at all.
+ */
+/** Four bytes to a pixel, which is how a texture is sized. */
+export const BYTES_PER_PIXEL = 4;
+/** How many layers to name before the tail is only counted. */
+const LISTED_LAYERS = 12;
+/**
+ * How long to let the compositor finish reporting after a frame.
+ *
+ * The tree arrives asynchronously and in more than one instalment
+ * on a busy page, so a read that returns immediately catches a
+ * partial tree.
+ */
+export const LAYER_SETTLE_MS = 600;
+const BYTES_PER_KB = 1024;
+const BYTES_PER_MB = BYTES_PER_KB * BYTES_PER_KB;
+/**
+ * Name an element compactly, the way a developer would say it.
+ *
+ * Chrome hands back a tag name and a flat array of alternating
+ * attribute names and values. A tag with its id, or failing that
+ * its first class, is enough to find the thing again without
+ * quoting a whole selector path.
+ */
+export function nameNode(nodeName, attributes = []) {
+    const tag = nodeName.toLowerCase();
+    const read = (wanted) => {
+        for (let index = 0; index + 1 < attributes.length; index += 2) {
+            if (attributes[index] === wanted)
+                return attributes[index + 1];
+        }
+        return undefined;
+    };
+    const id = read("id");
+    if (id)
+        return `${tag}#${id}`;
+    const classes = read("class")?.trim().split(/\s+/).filter(Boolean) ?? [];
+    if (classes.length > 0)
+        return `${tag}.${classes[0]}`;
+    return tag;
+}
+/**
+ * Texture bytes for one layer.
+ *
+ * A layer that draws no content holds no texture however large its
+ * bounds are: the viewport and scrolling layers come back at the
+ * full page size with drawsContent false, and counting those would
+ * bill the page several megabytes it never paid.
+ */
+function memoryOf(layer) {
+    if (!layer.drawsContent)
+        return 0;
+    return Math.max(0, layer.width) * Math.max(0, layer.height) * BYTES_PER_PIXEL;
+}
+/** Fold a layer tree capture into what it costs and why it exists. */
+export function foldLayers(facts) {
+    const layers = facts.layers.map((layer) => {
+        const reasons = facts.reasons[layer.layerId] ?? [];
+        const element = facts.elements[layer.layerId];
+        return {
+            id: layer.layerId,
+            ...(element === undefined ? {} : { element }),
+            width: layer.width,
+            height: layer.height,
+            paintCount: layer.paintCount,
+            drawsContent: layer.drawsContent,
+            memoryBytes: memoryOf(layer),
+            reasons,
+            forElement: layer.backendNodeId !== undefined,
+        };
+    });
+    // Heaviest first, because the layer worth arguing about is the one
+    // holding the most texture, not the one Chrome happened to list
+    // first.
+    layers.sort((a, b) => b.memoryBytes - a.memoryBytes);
+    const counts = new Map();
+    let unexplained = 0;
+    for (const layer of layers) {
+        if (layer.reasons.length === 0) {
+            // Only an element's layer counts as unexplained. Chrome's own
+            // structural layers carry no reason because no promotion
+            // decision produced them, and counting those would report a
+            // mystery on every page including a clean one.
+            if (layer.forElement)
+                unexplained += 1;
+            continue;
+        }
+        for (const reason of layer.reasons) {
+            counts.set(reason, (counts.get(reason) ?? 0) + 1);
+        }
+    }
+    return {
+        layers,
+        drawing: layers.filter((layer) => layer.memoryBytes > 0).length,
+        memoryBytes: layers.reduce((total, layer) => total + layer.memoryBytes, 0),
+        unexplained,
+        byReason: [...counts]
+            .map(([reason, count]) => ({ reason, count }))
+            .sort((a, b) => b.count - a.count || a.reason.localeCompare(b.reason)),
+    };
+}
+/** Bytes as something a person reads without counting digits. */
+function size(bytes) {
+    if (bytes >= BYTES_PER_MB) {
+        return `${(bytes / BYTES_PER_MB).toFixed(1)} MB`;
+    }
+    return `${Math.round(bytes / BYTES_PER_KB)} KB`;
+}
+/** Report what the compositor holds and what put it there. */
+export function renderLayers(report) {
+    if (report.layers.length === 0) {
+        return ("No composited layers. Nothing on this page asked the " +
+            "compositor for a texture of its own.");
+    }
+    const lines = [];
+    const many = report.layers.length === 1 ? "layer" : "layers";
+    lines.push(`${report.layers.length} ${many}, ${report.drawing} drawing ` +
+        `content, holding ${size(report.memoryBytes)} of texture.`);
+    if (report.unexplained > 0) {
+        // Said plainly, because the alternative reading is the damaging
+        // one: these layers exist, and Chrome declining to explain them
+        // is not the same as their not being promoted.
+        const was = report.unexplained === 1 ? "layer" : "layers";
+        lines.push(`Chrome gave no reason for ${report.unexplained} ${was}. ` +
+            "They are promoted; its compositingReasons simply came back " +
+            "empty, so nothing here can say what put them there.");
+    }
+    if (report.byReason.length > 0) {
+        lines.push("");
+        lines.push("Why they exist:");
+        for (const entry of report.byReason) {
+            lines.push(`  ${entry.count} x ${entry.reason}`);
+        }
+    }
+    lines.push("");
+    lines.push("Heaviest first:");
+    for (const layer of report.layers.slice(0, LISTED_LAYERS)) {
+        const where = layer.element ?? `layer ${layer.id}`;
+        const drawn = layer.drawsContent
+            ? `${size(layer.memoryBytes)}, painted ${layer.paintCount}x`
+            : "draws nothing, so holds no texture";
+        lines.push(`  ${where}: ${Math.round(layer.width)} by ` +
+            `${Math.round(layer.height)}, ${drawn}`);
+    }
+    const hidden = report.layers.length - LISTED_LAYERS;
+    if (hidden > 0) {
+        lines.push(`  and ${hidden} more.`);
+    }
+    return lines.join("\n");
+}