@monoes/monobrowse 1.0.12 → 1.0.13

package/src/report/pixel-diff.ts

@@ -0,0 +1,197 @@
+/**
+ * Pixel diff between two screenshots (RIG-10), with no image dependency —
+ * png.ts decodes and re-encodes using node's own zlib.
+ *
+ * Two design choices worth stating:
+ *
+ *  - A per-channel tolerance, not exact equality. Chrome's rasteriser is not
+ *    bit-deterministic across runs (font hinting, GPU vs. software paths), so
+ *    an exact compare reports 4% of every screenshot as "changed" and the
+ *    number becomes noise nobody reads.
+ *  - Differing dimensions are a result, not an error. A page that grew 200px
+ *    taller is exactly the regression this is for, so we compare the
+ *    overlapping region, count the rest as changed, and say so.
+ */
+
+import { decodePng, encodePng, pngToDataUrl, type RgbaImage } from './png.js';
+import type { PixelDiff } from './types.js';
+
+/** Per-channel delta below which two pixels are "the same". */
+const DEFAULT_THRESHOLD = 16;
+/**
+ * Cap on the highlight image, in pixels. A full-page shot of a long article
+ * can be 1440x20000; inlining that as a data URI would add ~20MB to a report
+ * that is supposed to stay openable.
+ */
+const DEFAULT_MAX_PIXELS = 1_400_000;
+
+export interface PixelDiffOptions {
+  threshold?: number;
+  maxPixels?: number;
+  /** Set false to skip building the highlight image (counts only). */
+  renderImage?: boolean;
+}
+
+function changedAt(a: Uint8Array, ai: number, b: Uint8Array, bi: number, threshold: number) {
+  return (
+    Math.abs(a[ai] - b[bi]) > threshold ||
+    Math.abs(a[ai + 1] - b[bi + 1]) > threshold ||
+    Math.abs(a[ai + 2] - b[bi + 2]) > threshold ||
+    Math.abs(a[ai + 3] - b[bi + 3]) > threshold
+  );
+}
+
+/**
+ * Build the highlight image: the current screenshot faded towards white so it
+ * reads as context, with changed pixels painted a saturated magenta. Scaled
+ * down by an integer factor when the shot is large, ORing the change mask so
+ * a one-pixel-wide change survives the downscale instead of being averaged
+ * into invisibility.
+ */
+function renderHighlight(
+  current: RgbaImage,
+  mask: Uint8Array,
+  maxPixels: number,
+): { image: RgbaImage; scale: number } {
+  const { width, height, data } = current;
+  const scale = Math.max(1, Math.ceil(Math.sqrt((width * height) / maxPixels)));
+  const outW = Math.max(1, Math.ceil(width / scale));
+  const outH = Math.max(1, Math.ceil(height / scale));
+  const out = new Uint8Array(outW * outH * 4);
+
+  for (let oy = 0; oy < outH; oy++) {
+    for (let ox = 0; ox < outW; ox++) {
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      let n = 0;
+      let hit = false;
+      for (let dy = 0; dy < scale; dy++) {
+        const y = oy * scale + dy;
+        if (y >= height) break;
+        for (let dx = 0; dx < scale; dx++) {
+          const x = ox * scale + dx;
+          if (x >= width) break;
+          const i = (y * width + x) * 4;
+          r += data[i];
+          g += data[i + 1];
+          b += data[i + 2];
+          n++;
+          if (mask[y * width + x]) hit = true;
+        }
+      }
+      const o = (oy * outW + ox) * 4;
+      if (!n) {
+        out[o + 3] = 255;
+        continue;
+      }
+      if (hit) {
+        out[o] = 214;
+        out[o + 1] = 31;
+        out[o + 2] = 105;
+      } else {
+        // Fade to white: keeps the layout legible without competing with the
+        // magenta, and compresses far better than the original.
+        out[o] = Math.round(255 - (255 - r / n) * 0.28);
+        out[o + 1] = Math.round(255 - (255 - g / n) * 0.28);
+        out[o + 2] = Math.round(255 - (255 - b / n) * 0.28);
+      }
+      out[o + 3] = 255;
+    }
+  }
+  return { image: { width: outW, height: outH, data: out }, scale };
+}
+
+/**
+ * Compare two PNGs. Never throws for image-shaped reasons — an undecodable
+ * screenshot produces a result carrying `note` and no counts, because a
+ * report that renders minus one section beats a report that fails to build.
+ */
+export function pixelDiff(
+  previousPng: Uint8Array,
+  currentPng: Uint8Array,
+  options: PixelDiffOptions = {},
+): PixelDiff {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  const maxPixels = options.maxPixels ?? DEFAULT_MAX_PIXELS;
+
+  let prev: RgbaImage;
+  let curr: RgbaImage;
+  try {
+    prev = decodePng(previousPng);
+    curr = decodePng(currentPng);
+  } catch (err) {
+    return {
+      comparable: false,
+      note: `Pixel diff skipped: ${(err as Error).message}`,
+      changedPixels: 0,
+      totalPixels: 0,
+      changedPercent: 0,
+      previousSize: null,
+      currentSize: null,
+      sizeChanged: false,
+    };
+  }
+
+  const overlapW = Math.min(prev.width, curr.width);
+  const overlapH = Math.min(prev.height, curr.height);
+  const sizeChanged = prev.width !== curr.width || prev.height !== curr.height;
+
+  // Denominator is the union, not the overlap: if the page doubled in height,
+  // "0.1% of pixels changed" would be a lie told by a small denominator.
+  const totalPixels = Math.max(prev.width * prev.height, curr.width * curr.height);
+  const mask = new Uint8Array(curr.width * curr.height);
+  let changed = 0;
+
+  for (let y = 0; y < curr.height; y++) {
+    for (let x = 0; x < curr.width; x++) {
+      const ci = (y * curr.width + x) * 4;
+      if (x >= overlapW || y >= overlapH) {
+        // Outside the overlap there is nothing to compare against: the pixel
+        // is new by definition.
+        mask[y * curr.width + x] = 1;
+        changed++;
+        continue;
+      }
+      const pi = (y * prev.width + x) * 4;
+      if (changedAt(prev.data, pi, curr.data, ci, threshold)) {
+        mask[y * curr.width + x] = 1;
+        changed++;
+      }
+    }
+  }
+  // Pixels the previous shot had and this one does not are changes too.
+  changed += Math.max(0, prev.width * prev.height - overlapW * overlapH);
+
+  const result: PixelDiff = {
+    comparable: true,
+    changedPixels: changed,
+    totalPixels,
+    changedPercent: totalPixels ? (changed / totalPixels) * 100 : 0,
+    previousSize: { width: prev.width, height: prev.height },
+    currentSize: { width: curr.width, height: curr.height },
+    sizeChanged,
+  };
+
+  if (options.renderImage !== false && changed > 0) {
+    try {
+      const { image, scale } = renderHighlight(curr, mask, maxPixels);
+      result.diffDataUrl = pngToDataUrl(encodePng(image));
+      if (scale > 1) result.scale = scale;
+    } catch (err) {
+      result.note = `Highlight image not rendered: ${(err as Error).message}`;
+    }
+  }
+  return result;
+}
+
+/** One line for a CI log. */
+export function summarizePixelDiff(diff: PixelDiff): string {
+  if (!diff.comparable) return diff.note ?? 'pixel diff unavailable';
+  const pct = diff.changedPercent;
+  const shown = pct === 0 ? '0' : pct < 0.01 ? '<0.01' : pct.toFixed(2);
+  const size = diff.sizeChanged
+    ? ` (size ${diff.previousSize?.width}x${diff.previousSize?.height} -> ${diff.currentSize?.width}x${diff.currentSize?.height})`
+    : '';
+  return `${shown}% of pixels changed${size}`;
+}

package/src/report/png.ts

@@ -0,0 +1,290 @@
+/**
+ * A minimal PNG decoder and encoder built on node's own `zlib`.
+ *
+ * This exists so the pixel diff (RIG-10) can compare two screenshots without
+ * adding an image dependency to a package whose whole point is to be a small
+ * self-contained CDP client. PNG is simple enough to justify it: the format
+ * is a chunk list wrapping one zlib stream, and node ships the zlib.
+ *
+ * Scope is deliberately narrow — what `Page.captureScreenshot` actually
+ * emits. Non-interlaced, bit depth 8 (16 is accepted by taking the high
+ * byte), colour types 0/2/3/4/6. Anything else throws a message that names
+ * what it saw, so the caller can degrade to "pixel diff unavailable" instead
+ * of rendering a wrong picture.
+ */
+
+import { deflateSync, inflateSync } from 'node:zlib';
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export interface RgbaImage {
+  width: number;
+  height: number;
+  /** Row-major RGBA, 4 bytes per pixel, length === width * height * 4. */
+  data: Uint8Array;
+}
+
+// ---------------------------------------------------------------------------
+// CRC32 — PNG chunks carry their own checksum, and zlib does not expose one.
+// ---------------------------------------------------------------------------
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+export function crc32(buf: Uint8Array): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+// ---------------------------------------------------------------------------
+// Decode
+// ---------------------------------------------------------------------------
+
+const CHANNELS: Record<number, number> = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/** Undo the per-scanline filters in place, returning the raw sample bytes. */
+function unfilter(raw: Buffer, width: number, height: number, bpp: number, stride: number): Buffer {
+  const out = Buffer.alloc(height * stride);
+  let pos = 0;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[pos++];
+    const line = raw.subarray(pos, pos + stride);
+    pos += stride;
+    const cur = out.subarray(y * stride, (y + 1) * stride);
+    const prev = y > 0 ? out.subarray((y - 1) * stride, y * stride) : null;
+    for (let x = 0; x < stride; x++) {
+      const a = x >= bpp ? cur[x - bpp] : 0;
+      const b = prev ? prev[x] : 0;
+      const c = prev && x >= bpp ? prev[x - bpp] : 0;
+      const v = line[x];
+      switch (filter) {
+        case 0:
+          cur[x] = v;
+          break;
+        case 1:
+          cur[x] = (v + a) & 0xff;
+          break;
+        case 2:
+          cur[x] = (v + b) & 0xff;
+          break;
+        case 3:
+          cur[x] = (v + ((a + b) >> 1)) & 0xff;
+          break;
+        case 4:
+          cur[x] = (v + paeth(a, b, c)) & 0xff;
+          break;
+        default:
+          throw new Error(`PNG: unknown scanline filter ${filter} on row ${y}`);
+      }
+    }
+  }
+  void width;
+  return out;
+}
+
+interface Header {
+  width: number;
+  height: number;
+  bitDepth: number;
+  colorType: number;
+  interlace: number;
+}
+
+function readHeader(buf: Buffer, offset: number): Header {
+  return {
+    width: buf.readUInt32BE(offset),
+    height: buf.readUInt32BE(offset + 4),
+    bitDepth: buf[offset + 8],
+    colorType: buf[offset + 9],
+    interlace: buf[offset + 12],
+  };
+}
+
+/**
+ * Expand one row of decoded samples into RGBA. `step` is the byte stride of
+ * one sample (1 for bit depth 8, 2 for 16 — where we keep the high byte).
+ */
+function toRgba(
+  samples: Buffer,
+  header: Header,
+  palette: Buffer | null,
+  transparency: Buffer | null,
+): Uint8Array {
+  const { width, height, bitDepth, colorType } = header;
+  const channels = CHANNELS[colorType];
+  const step = bitDepth === 16 ? 2 : 1;
+  const stride = width * channels * step;
+  const out = new Uint8Array(width * height * 4);
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const s = y * stride + x * channels * step;
+      const d = (y * width + x) * 4;
+      if (colorType === 3) {
+        const index = samples[s];
+        if (!palette || index * 3 + 2 >= palette.length) {
+          throw new Error(`PNG: palette index ${index} out of range`);
+        }
+        out[d] = palette[index * 3];
+        out[d + 1] = palette[index * 3 + 1];
+        out[d + 2] = palette[index * 3 + 2];
+        out[d + 3] = transparency && index < transparency.length ? transparency[index] : 255;
+      } else if (colorType === 0) {
+        const g = samples[s];
+        out[d] = g;
+        out[d + 1] = g;
+        out[d + 2] = g;
+        out[d + 3] = 255;
+      } else if (colorType === 4) {
+        const g = samples[s];
+        out[d] = g;
+        out[d + 1] = g;
+        out[d + 2] = g;
+        out[d + 3] = samples[s + step];
+      } else if (colorType === 2) {
+        out[d] = samples[s];
+        out[d + 1] = samples[s + step];
+        out[d + 2] = samples[s + 2 * step];
+        out[d + 3] = 255;
+      } else {
+        out[d] = samples[s];
+        out[d + 1] = samples[s + step];
+        out[d + 2] = samples[s + 2 * step];
+        out[d + 3] = samples[s + 3 * step];
+      }
+    }
+  }
+  return out;
+}
+
+export function decodePng(input: Uint8Array): RgbaImage {
+  const buf = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+  if (buf.length < 8 || !buf.subarray(0, 8).equals(SIGNATURE)) {
+    throw new Error('PNG: not a PNG (bad signature)');
+  }
+
+  let header: Header | null = null;
+  let palette: Buffer | null = null;
+  let transparency: Buffer | null = null;
+  const idat: Buffer[] = [];
+
+  let pos = 8;
+  while (pos + 8 <= buf.length) {
+    const length = buf.readUInt32BE(pos);
+    const type = buf.toString('ascii', pos + 4, pos + 8);
+    const dataStart = pos + 8;
+    if (dataStart + length > buf.length) throw new Error(`PNG: truncated ${type} chunk`);
+    if (type === 'IHDR') header = readHeader(buf, dataStart);
+    else if (type === 'PLTE') palette = buf.subarray(dataStart, dataStart + length);
+    else if (type === 'tRNS') transparency = buf.subarray(dataStart, dataStart + length);
+    else if (type === 'IDAT') idat.push(buf.subarray(dataStart, dataStart + length));
+    else if (type === 'IEND') break;
+    pos = dataStart + length + 4;
+  }
+
+  if (!header) throw new Error('PNG: no IHDR chunk');
+  if (header.interlace !== 0) {
+    throw new Error('PNG: interlaced (Adam7) images are not supported');
+  }
+  if (header.bitDepth !== 8 && header.bitDepth !== 16) {
+    throw new Error(`PNG: unsupported bit depth ${header.bitDepth} (need 8 or 16)`);
+  }
+  const channels = CHANNELS[header.colorType];
+  if (channels === undefined) {
+    throw new Error(`PNG: unsupported colour type ${header.colorType}`);
+  }
+  if (header.colorType === 3 && header.bitDepth !== 8) {
+    throw new Error(`PNG: palette images below bit depth 8 are not supported`);
+  }
+  if (!idat.length) throw new Error('PNG: no IDAT data');
+
+  const sampleBytes = header.bitDepth === 16 ? 2 : 1;
+  const stride = header.width * channels * sampleBytes;
+  const bpp = Math.max(1, channels * sampleBytes);
+  const inflated = inflateSync(Buffer.concat(idat));
+  const expected = header.height * (stride + 1);
+  if (inflated.length < expected) {
+    throw new Error(`PNG: pixel data short by ${expected - inflated.length} bytes`);
+  }
+  const samples = unfilter(inflated, header.width, header.height, bpp, stride);
+
+  return {
+    width: header.width,
+    height: header.height,
+    data: toRgba(samples, header, palette, transparency),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Encode
+// ---------------------------------------------------------------------------
+
+function chunk(type: string, data: Uint8Array): Buffer {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0);
+  head.write(type, 4, 'ascii');
+  const body = Buffer.concat([head.subarray(4), Buffer.from(data)]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([head.subarray(0, 4), body, crc]);
+}
+
+/** Encode RGBA bytes as a non-interlaced, 8-bit truecolour-with-alpha PNG. */
+export function encodePng(image: RgbaImage): Buffer {
+  const { width, height, data } = image;
+  if (data.length !== width * height * 4) {
+    throw new Error(
+      `PNG: encode expected ${width * height * 4} bytes for ${width}x${height}, got ${data.length}`,
+    );
+  }
+  const stride = width * 4;
+  const raw = Buffer.alloc(height * (stride + 1));
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0; // filter: None. Simplest, and deflate still wins.
+    Buffer.from(data.buffer, data.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1);
+  }
+
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // colour type: RGBA
+  ihdr[10] = 0; // compression
+  ihdr[11] = 0; // filter
+  ihdr[12] = 0; // interlace
+
+  return Buffer.concat([
+    SIGNATURE,
+    chunk('IHDR', ihdr),
+    chunk('IDAT', deflateSync(raw, { level: 6 })),
+    chunk('IEND', new Uint8Array(0)),
+  ]);
+}
+
+/** `data:image/png;base64,...` -> bytes. Accepts a bare base64 payload too. */
+export function pngFromDataUrl(dataUrl: string): Uint8Array {
+  const comma = dataUrl.indexOf(',');
+  const payload = dataUrl.startsWith('data:') && comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl;
+  return new Uint8Array(Buffer.from(payload, 'base64'));
+}
+
+export function pngToDataUrl(png: Uint8Array): string {
+  return `data:image/png;base64,${Buffer.from(png).toString('base64')}`;
+}

package/src/report/render-evidence.ts

@@ -0,0 +1,194 @@
+/**
+ * Report sections for the recorded evidence timeline (RIG-11) and the flake
+ * analysis (RIG-14).
+ *
+ * The evidence section is written to be read the way someone triages a bug:
+ * a filmstrip of what the page looked like either side of the failure, then
+ * one time-ordered list mixing frames, console output and network failures,
+ * so "the error fired, then the screen went blank" is visible rather than
+ * inferred.
+ */
+
+import type { FlakeCheck, FlakeReport } from './flake.js';
+import type { Evidence, TimelineEntry } from './types.js';
+import { escapeHtml } from './util.js';
+
+export const EVIDENCE_STYLES = `
+.filmstrip{display:flex;gap:10px;overflow-x:auto;padding:4px 0 10px;margin:0 0 8px}
+.filmstrip figure{flex:0 0 auto;width:180px;margin:0}
+.filmstrip img{width:180px;height:auto;border-radius:6px}
+.filmstrip figcaption{font-variant-numeric:tabular-nums}
+.filmstrip figure.focus img{border-color:var(--fail);border-width:2px}
+.timeline{list-style:none;margin:0;padding:0;border-left:2px solid var(--line);
+  margin-left:8px}
+.timeline li{position:relative;padding:6px 0 6px 18px;font-size:13px}
+.timeline li::before{content:"";position:absolute;left:-5px;top:12px;width:8px;height:8px;
+  border-radius:50%;background:var(--muted)}
+.timeline li.error::before{background:var(--fail)}
+.timeline li.warning::before{background:var(--warn)}
+.timeline li.marker{font-weight:600;color:var(--fail)}
+.timeline .at{display:inline-block;min-width:66px;color:var(--muted);
+  font-variant-numeric:tabular-nums;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+.verdict.flaky{background:var(--warn-bg);border-color:var(--warn);color:var(--warn)}
+.rate{display:inline-block;min-width:72px}
+.bar{display:inline-block;width:80px;height:8px;border-radius:4px;background:var(--pass);
+  overflow:hidden;vertical-align:middle}
+.bar i{display:block;height:100%;background:var(--fail)}
+`.trim();
+
+function at(offsetMs: number): string {
+  const sign = offsetMs < 0 ? '−' : '+';
+  const abs = Math.abs(offsetMs);
+  return abs >= 1000 ? `${sign}${(abs / 1000).toFixed(2)}s` : `${sign}${Math.round(abs)}ms`;
+}
+
+// ---------------------------------------------------------------------------
+// Evidence
+// ---------------------------------------------------------------------------
+
+function renderFilmstrip(evidence: Evidence): string {
+  if (!evidence.frames.length) return '';
+  // Mark the frame closest to the failure so the eye lands on it first.
+  let focusIndex = -1;
+  if (evidence.focusOffsetMs !== null) {
+    let best = Infinity;
+    evidence.frames.forEach((f, i) => {
+      const d = Math.abs(f.offsetMs - (evidence.focusOffsetMs as number));
+      if (d < best) {
+        best = d;
+        focusIndex = i;
+      }
+    });
+  }
+  const figures = evidence.frames
+    .map(
+      (f, i) => `<figure class="${i === focusIndex ? 'focus' : ''}">
+      <figcaption>${escapeHtml(at(f.offsetMs))}${i === focusIndex ? ' · at failure' : ''}</figcaption>
+      <img alt="${escapeHtml(`Frame at ${at(f.offsetMs)}`)}" src="${escapeHtml(f.dataUrl)}">
+    </figure>`,
+    )
+    .join('');
+  return `<div class="filmstrip">${figures}</div>`;
+}
+
+function renderTimelineRows(timeline: TimelineEntry[]): string {
+  if (!timeline.length) return '<p class="empty">Nothing was recorded for this run.</p>';
+  const rows = timeline
+    .map((e) => {
+      const detail = e.detail ? ` — ${escapeHtml(e.detail)}` : '';
+      const frame =
+        e.kind === 'frame' && e.frameIndex !== undefined
+          ? ` <span style="color:var(--muted)">#${e.frameIndex + 1}</span>`
+          : '';
+      return `<li class="${e.severity}${e.kind === 'marker' ? ' marker' : ''}">
+        <span class="at">${escapeHtml(at(e.offsetMs))}</span>${escapeHtml(e.label)}${frame}${detail}
+      </li>`;
+    })
+    .join('');
+  return `<ul class="timeline">${rows}</ul>`;
+}
+
+export function renderEvidence(evidence: Evidence | undefined): string {
+  if (!evidence) return '';
+  const why =
+    evidence.reason === 'budget-failure'
+      ? 'Recorded because this run breached its budget.'
+      : 'Recorded because --record was passed.';
+  const focus =
+    evidence.focusOffsetMs !== null
+      ? ` The timeline is centred on the first failure, at ${at(evidence.focusOffsetMs)} into the run.`
+      : '';
+  const notes = evidence.notes.length
+    ? `<p class="note">${evidence.notes.map((n) => escapeHtml(n)).join(' ')}</p>`
+    : '';
+
+  return `<h2>Evidence</h2>
+<p class="note">${escapeHtml(why)}${escapeHtml(focus)} Offsets are measured from the start of the run.</p>
+${renderFilmstrip(evidence)}
+${renderTimelineRows(evidence.timeline)}
+${notes}`;
+}
+
+// ---------------------------------------------------------------------------
+// Flake
+// ---------------------------------------------------------------------------
+
+function rateBar(check: FlakeCheck): string {
+  const pct = Math.round(check.flakeRate * 100);
+  return `<span class="bar" role="img" aria-label="${escapeHtml(`failed ${pct}% of runs`)}"><i style="width:${pct}%"></i></span>`;
+}
+
+function renderChecks(flake: FlakeReport): string {
+  const rows = flake.checks
+    // Unstable checks first: they are the reason this section exists.
+    .sort((a, b) => Number(a.stable) - Number(b.stable) || b.flakeRate - a.flakeRate)
+    .map(
+      (c) => `<tr>
+      <td>${escapeHtml(c.label)}</td>
+      <td class="num mono"><span class="rate">${c.passed} of ${c.runs} passed</span></td>
+      <td>${rateBar(c)}</td>
+      <td>${c.stable ? (c.failed ? '<span class="pill error">always fails</span>' : '<span class="pill good">stable</span>') : '<span class="pill warning">flaky</span>'}</td>
+      <td class="wrap mono">${escapeHtml(c.actuals.join(', '))}</td>
+    </tr>`,
+    )
+    .join('');
+  return `<table><thead><tr><th>Check</th><th>Outcome</th><th>Failure rate</th><th></th><th>Measured each run</th></tr></thead>
+  <tbody>${rows}</tbody></table>`;
+}
+
+function renderSignals(flake: FlakeReport): string {
+  if (!flake.signals.length) {
+    return '<p class="empty">No error or failed request came and went between runs.</p>';
+  }
+  const rows = flake.signals
+    .slice(0, 30)
+    .map(
+      (s) => `<tr>
+      <td>${escapeHtml(s.kind)}</td>
+      <td class="wrap">${escapeHtml(s.signature)}</td>
+      <td class="num mono">${s.runs} of ${s.total}</td>
+    </tr>`,
+    )
+    .join('');
+  return `<table><thead><tr><th>Kind</th><th>Signal</th><th>Appeared in</th></tr></thead><tbody>${rows}</tbody></table>
+  <p class="note">Ids, hashes and long numbers are normalised before grouping, so one intermittent error is one row rather than N.</p>`;
+}
+
+function renderMetricSpread(flake: FlakeReport): string {
+  if (!flake.metrics.length) return '';
+  const rows = flake.metrics
+    .map((m) => {
+      const fmt = (v: number) =>
+        m.unit === 'score'
+          ? v.toFixed(3)
+          : v >= 1000
+            ? `${(v / 1000).toFixed(2)}s`
+            : `${Math.round(v)}ms`;
+      return `<tr>
+        <td><b>${escapeHtml(m.label)}</b></td>
+        <td class="num mono">${escapeHtml(fmt(m.min))} – ${escapeHtml(fmt(m.max))}</td>
+        <td class="num mono">${escapeHtml(fmt(m.median))}</td>
+        <td class="num mono">${escapeHtml(fmt(m.spread))}</td>
+        <td>${m.unstable ? '<span class="pill warning">varies widely</span>' : '<span class="pill good">consistent</span>'}</td>
+        <td class="num mono">${m.measured} of ${m.total}</td>
+      </tr>`;
+    })
+    .join('');
+  return `<h3 style="font-size:13px;color:var(--muted);margin:24px 0 8px">Metric spread</h3>
+  <table><thead><tr><th>Metric</th><th>Range</th><th>Median</th><th>Spread</th><th></th><th>Measured</th></tr></thead>
+  <tbody>${rows}</tbody></table>`;
+}
+
+export function renderFlake(flake: FlakeReport | undefined): string {
+  if (!flake) return '';
+  return `<h2>Repeatability — ${flake.runs} runs</h2>
+<section class="verdict ${flake.verdict === 'pass' ? 'pass' : flake.verdict === 'fail' ? 'fail' : 'flaky'}">
+  <div class="tag">${flake.verdict.toUpperCase()}</div>
+  <div class="line">${escapeHtml(flake.headline)}</div>
+</section>
+<p class="note"><b>Confidence: ${escapeHtml(flake.confidence)}.</b> ${escapeHtml(flake.confidenceNote)}</p>
+${renderChecks(flake)}
+<h3 style="font-size:13px;color:var(--muted);margin:24px 0 8px">Intermittent errors and requests</h3>
+${renderSignals(flake)}
+${renderMetricSpread(flake)}`;
+}