staysfixed 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers — as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",

package/src/core/events.js

@@ -16,6 +16,10 @@
 import { pathToFileURL } from 'node:url';
 import { detail } from './log.js';
 import { messageOf } from './errors.js';
+// Only for the stock pixel allowance. The number a person is shown has to be the
+// number the verdict was made against, so it is read from the one place that
+// defines it rather than copied and left to drift.
+import { DEFAULT_TOLERANCE } from './config.js';
 
 /** @typedef {import('../types.js').RunEvent} RunEvent */
 /** @typedef {import('../types.js').RunEvents} RunEvents */
@@ -197,3 +201,517 @@ export function makeTimings() {
 
   return { add, mark, get };
 }
+
+// ---------------------------------------------------------------------------
+// Showing the working
+// ---------------------------------------------------------------------------
+
+/**
+ * Every phrase a step of a picture check can be described by, in one place.
+ *
+ * They live here as data rather than scattered through the code below for one
+ * reason: this is the wording a non-programmer reads, so the whole set has to be
+ * readable — and judgeable — in a single glance. If a line here sounds like a
+ * programmer talking, it is wrong, whatever the code around it does.
+ *
+ * Most steps have two or three wordings, because a step that was switched off in
+ * the config must say so rather than quietly claim success.
+ */
+export const CHECK_LABELS = Object.freeze({
+  frozen: 'the clock was frozen',
+  frozenOff: 'the clock was left alone',
+  steps: 'reached the screen',
+  stepsFailed: 'could not reach the screen',
+  settle: 'everything held still',
+  settleGaveUp: 'it never fully stopped moving',
+  loaded: 'fonts and pictures landed',
+  loadedWaiting: 'something was still loading',
+  loadedOff: 'fonts were left to load on their own',
+  loadedUnknown: 'could not ask what was still loading',
+  network: 'the outside world kept out',
+  networkLive: 'the app was left online',
+  networkUnknown: 'the network was not watched',
+  masks: 'live things painted over',
+  masksNone: 'nothing needed painting over',
+  size: 'same size as approved',
+  sizeChanged: 'not the same size as approved',
+  sizeNew: 'nothing approved to measure against',
+  pixels: 'every pixel compared',
+  pixelsNew: 'nothing to compare it with yet',
+  pixelsSkipped: 'the pixels could not be compared',
+  console: 'no errors from the page',
+  consoleBad: 'the page threw errors',
+  retried: 'photographed more than once',
+  platform: 'approved on a different computer',
+  failed: 'the picture could not be taken',
+});
+
+/**
+ * What was asked of the freeze layer for one screen. Everything here is a
+ * setting, not a measurement — it is how the list can say a check was switched
+ * off instead of pretending it passed.
+ *
+ * @typedef {object} FrozenPlan
+ * @property {boolean} clock            The clock, timezone and locale were pinned.
+ * @property {boolean} motion           Animations, transitions and carets were killed.
+ * @property {boolean} random           Random numbers were seeded.
+ * @property {boolean} fonts            The shutter waited for fonts.
+ * @property {'replay'|'block-external'|'live'} network   How requests were treated.
+ * @property {number} frames            Identical frames in a row demanded.
+ * @property {number} [maxDriftPixels]  Pixels allowed to wobble and still count as identical.
+ */
+
+/**
+ * What the page said was still loading at the moment the picture was taken.
+ * Read off the real page, so it is a measurement rather than a hope.
+ *
+ * @typedef {object} LoadedReport
+ * @property {string} [fonts]           document.fonts.status: 'loaded', 'loading', or 'none'.
+ * @property {number} [images]          How many pictures the page has.
+ * @property {number} [imagesPending]   How many of them had not finished.
+ */
+
+/**
+ * Everything needed to say what was done to one screen.
+ *
+ * All of it optional except the screen, because a screen that fell over halfway
+ * still deserves an honest list of how far it got.
+ *
+ * @typedef {object} ChecksInput
+ * @property {import('../types.js').ScreenConfig} screen        The recipe that was followed.
+ * @property {import('../types.js').CheckStatus} [status]       How the screen ended up.
+ * @property {FrozenPlan} [frozen]                              What the freeze layer was asked to do.
+ * @property {import('../types.js').SettleReport} [settle]      How the holding-still went.
+ * @property {LoadedReport} [loaded]                            What was still loading at the shutter.
+ * @property {import('../types.js').FreezeStats} [freeze]       Requests blocked, replayed, allowed.
+ * @property {import('../types.js').MaskRect[]} [masks]         Rectangles painted over both pictures.
+ * @property {number} [masksAsked]                              How many masks the config set for this screen.
+ * @property {string[]} [consoleErrors]                         Errors the page threw, unprompted.
+ * @property {{width:number,height:number}} [size]              The new picture.
+ * @property {{width:number,height:number}} [approvedSize]      The approved one.
+ * @property {import('../types.js').CompareReport|null} [compare]  The verdict on the pixels.
+ * @property {boolean} [hasApproved]                            Was there an approved picture at all.
+ * @property {import('../types.js').ToleranceConfig} [tolerance] How much difference was allowed.
+ * @property {number} [attempts]                                How many times it was photographed.
+ * @property {{approvedOn?: string, here?: string}} [platform]  Where the two pictures were taken.
+ * @property {string} [failure]                                 Why it could not be photographed at all.
+ */
+
+/**
+ * Turn what a capture and a comparison know into the list of things that were
+ * actually done to a screen, in the order they happened.
+ *
+ * A verdict on its own — "matches", "1.9s" — tells nobody what was verified. It
+ * reads like a speed test, and a person who cannot see the work cannot decide
+ * whether to believe it. This is that work, written out.
+ *
+ * Pure on purpose: no browser, no disk, no clock. The words that appear in front
+ * of a person are then testable without photographing anything, and every path
+ * through the tool that wants to explain itself uses the same ones.
+ *
+ * @param {ChecksInput} input
+ * @returns {import('../types.js').CheckStep[]}
+ */
+export function buildChecks(input) {
+  /** @type {import('../types.js').CheckStep[]} */
+  const out = [];
+  /**
+   * @param {string} label
+   * @param {string|undefined} detail
+   * @param {import('../types.js').CheckStep['state']} state
+   */
+  const say = (label, detail, state) => {
+    out.push(detail ? { label, detail, state } : { label, state });
+  };
+
+  const screen = input.screen ?? /** @type {import('../types.js').ScreenConfig} */ ({ name: '' });
+  const errors = input.consoleErrors ?? [];
+
+  frozenStep(say, input.frozen);
+  stepsStep(say, screen, input.failure);
+
+  if (input.failure) {
+    // Nothing after this happened, so nothing after this is claimed. The one
+    // thing still worth saying is whether the page was shouting on its way down.
+    say(CHECK_LABELS.failed, input.failure, 'bad');
+    consoleStep(say, errors);
+    return out;
+  }
+
+  settleStep(say, input.settle, input.frozen);
+  loadedStep(say, input.loaded, input.frozen);
+  networkStep(say, input.freeze, input.frozen);
+  masksStep(say, input.masks, input.masksAsked);
+  sizeStep(say, input);
+  pixelsStep(say, input);
+  consoleStep(say, errors);
+  retryStep(say, input);
+  platformStep(say, input.platform);
+
+  return out;
+}
+
+/** @typedef {(label: string, detail: string|undefined, state: import('../types.js').CheckStep['state']) => void} Say */
+
+/**
+ * @param {Say} say
+ * @param {FrozenPlan|undefined} frozen
+ */
+function frozenStep(say, frozen) {
+  if (!frozen) return;
+  /** @type {string[]} */
+  const also = [];
+  if (frozen.motion) also.push('animations off');
+  if (frozen.random) also.push('random numbers pinned');
+  if (!frozen.clock) {
+    say(
+      CHECK_LABELS.frozenOff,
+      also.length > 0 ? also.join(', ') : 'the time may be different every run',
+      'skipped',
+    );
+    return;
+  }
+  say(CHECK_LABELS.frozen, also.length > 0 ? also.join(', ') : 'the same instant every run', 'ok');
+}
+
+/**
+ * @param {Say} say
+ * @param {import('../types.js').ScreenConfig} screen
+ * @param {string|undefined} failure
+ */
+function stepsStep(say, screen, failure) {
+  const label = failure ? CHECK_LABELS.stepsFailed : CHECK_LABELS.steps;
+  const state = failure ? 'bad' : 'ok';
+
+  if (typeof screen.do === 'function') {
+    say(label, 'its own instructions', state);
+    return;
+  }
+  const steps = screen.steps ?? [];
+  const waits = steps.filter((s) => s && s.wait !== undefined).length;
+  const after = (screen.after ?? []).length;
+
+  if (steps.length === 0) {
+    say(label, 'nothing to do — it was already there', state);
+    return;
+  }
+  /** @type {string[]} */
+  const parts = [`${steps.length} ${plural(steps.length, 'step', 'steps')}`];
+  parts.push(waits === 0 ? 'none of them a timed wait' : `${waits} of them a timed wait`);
+  if (after > 0) parts.push(`${after} more to put the app back`);
+  say(label, parts.join(', '), state);
+}
+
+/**
+ * @param {Say} say
+ * @param {import('../types.js').SettleReport|undefined} settle
+ * @param {FrozenPlan|undefined} frozen
+ */
+function settleStep(say, settle, frozen) {
+  if (!settle) return;
+  const frames = Math.max(1, frozen?.frames ?? 2);
+  const drift = settle.lastDriftPixels ?? 0;
+
+  if (!settle.settled) {
+    const moving =
+      drift > 0
+        ? `${count(drift)} ${plural(drift, 'pixel', 'pixels')} still moving`
+        : 'it never held';
+    say(
+      CHECK_LABELS.settleGaveUp,
+      `gave up after ${count(settle.attempts)} ${plural(settle.attempts, 'photo', 'photos')}, ${moving}`,
+      'warn',
+    );
+    return;
+  }
+
+  /** @type {string[]} */
+  const parts = [`${frames} identical ${plural(frames, 'frame', 'frames')} in a row`];
+  parts.push(
+    settle.attempts > frames ? `after ${count(settle.attempts)} photos` : 'first try',
+  );
+  // Only worth saying when a project deliberately allows a little wobble AND
+  // some wobble actually happened; otherwise it is noise about nothing.
+  if ((frozen?.maxDriftPixels ?? 0) > 0 && drift > 0) {
+    parts.push(`${count(drift)} ${plural(drift, 'pixel', 'pixels')} of allowed wobble`);
+  }
+  say(CHECK_LABELS.settle, parts.join(', '), 'ok');
+}
+
+/**
+ * @param {Say} say
+ * @param {LoadedReport|undefined} loaded
+ * @param {FrozenPlan|undefined} frozen
+ */
+function loadedStep(say, loaded, frozen) {
+  if (frozen && frozen.fonts === false) {
+    say(CHECK_LABELS.loadedOff, 'the shutter did not wait for them', 'skipped');
+    return;
+  }
+  if (!loaded) {
+    say(CHECK_LABELS.loadedUnknown, 'the page had moved on by the time we asked', 'skipped');
+    return;
+  }
+
+  const pending = loaded.imagesPending ?? 0;
+  const fontsBusy = loaded.fonts === 'loading';
+  if (!fontsBusy && pending === 0) {
+    const total = loaded.images ?? 0;
+    say(
+      CHECK_LABELS.loaded,
+      total > 0
+        ? `every face loaded, ${count(total)} ${plural(total, 'picture', 'pictures')}, none still loading`
+        : 'every face loaded, nothing still loading',
+      'ok',
+    );
+    return;
+  }
+
+  /** @type {string[]} */
+  const busy = [];
+  if (fontsBusy) busy.push('a font was still loading');
+  if (pending > 0) {
+    busy.push(`${count(pending)} ${plural(pending, 'picture', 'pictures')} still loading`);
+  }
+  say(CHECK_LABELS.loadedWaiting, busy.join(', '), 'warn');
+}
+
+/**
+ * @param {Say} say
+ * @param {import('../types.js').FreezeStats|undefined} stats
+ * @param {FrozenPlan|undefined} frozen
+ */
+function networkStep(say, stats, frozen) {
+  if (frozen && frozen.network === 'live') {
+    say(CHECK_LABELS.networkLive, 'requests were left alone', 'skipped');
+    return;
+  }
+  if (!stats) {
+    say(CHECK_LABELS.networkUnknown, 'nothing was counted', 'skipped');
+    return;
+  }
+
+  const blocked = stats.requestsBlocked ?? 0;
+  const replayed = stats.requestsReplayed ?? 0;
+  const recorded = stats.requestsRecorded ?? 0;
+  const allowed = stats.requestsAllowed ?? 0;
+
+  /** @type {string[]} */
+  const parts = [];
+  if (blocked > 0) parts.push(`${count(blocked)} ${plural(blocked, 'request', 'requests')} blocked`);
+  if (replayed > 0) parts.push(`${count(replayed)} replayed from saved copies`);
+  if (recorded > 0) parts.push(`${count(recorded)} saved for next time`);
+  if (parts.length === 0) {
+    parts.push(
+      allowed > 0
+        ? `nothing to block, ${count(allowed)} ${plural(allowed, 'request', 'requests')} stayed inside the app`
+        : 'nothing tried to load',
+    );
+  } else if (allowed > 0) {
+    parts.push(`${count(allowed)} allowed through`);
+  }
+  say(CHECK_LABELS.network, parts.join(', '), 'ok');
+}
+
+/**
+ * Masks are set in the config and found on the page, and those are two different
+ * numbers. A screen with three masks configured and none of them on it painted
+ * nothing — saying "no live areas set" there would be a small lie, and the kind
+ * that makes somebody stop trusting the rest of the list.
+ *
+ * @param {Say} say
+ * @param {import('../types.js').MaskRect[]|undefined} masks
+ * @param {number|undefined} asked
+ */
+function masksStep(say, masks, asked) {
+  const n = masks ? masks.length : 0;
+  if (n === 0) {
+    const set = asked ?? 0;
+    say(
+      CHECK_LABELS.masksNone,
+      set > 0
+        ? `${count(set)} set, none of them on this screen`
+        : 'no live areas set for this screen',
+      'skipped',
+    );
+    return;
+  }
+  say(CHECK_LABELS.masks, `${count(n)} ${plural(n, 'area', 'areas')}, on both pictures`, 'ok');
+}
+
+/**
+ * @param {Say} say
+ * @param {ChecksInput} input
+ */
+function sizeStep(say, input) {
+  const size = input.size;
+  const approved = input.approvedSize;
+  const has = input.hasApproved !== false && Boolean(approved);
+
+  if (!size) return;
+  if (!has || !approved) {
+    say(CHECK_LABELS.sizeNew, dimensions(size), 'skipped');
+    return;
+  }
+  if (approved.width !== size.width || approved.height !== size.height) {
+    say(CHECK_LABELS.sizeChanged, `${dimensions(size)} now, ${dimensions(approved)} approved`, 'bad');
+    return;
+  }
+  say(CHECK_LABELS.size, dimensions(size), 'ok');
+}
+
+/**
+ * The line the whole thing exists for: how many pixels were looked at, how many
+ * of them moved, and how many were allowed to. A share on its own ("0.30%
+ * changed") means nothing without the allowance beside it.
+ *
+ * @param {Say} say
+ * @param {ChecksInput} input
+ */
+function pixelsStep(say, input) {
+  const compare = input.compare;
+  const size = compare?.size ?? input.size;
+  const total = size ? size.width * size.height : 0;
+
+  if (input.hasApproved === false || !compare) {
+    say(
+      CHECK_LABELS.pixelsNew,
+      total > 0 ? `${count(total)} pixels waiting for a first approval` : undefined,
+      'skipped',
+    );
+    return;
+  }
+  if (compare.sizeMismatch) {
+    say(CHECK_LABELS.pixelsSkipped, 'two different sizes cannot be laid over each other', 'skipped');
+    return;
+  }
+
+  const allowed = allowanceFor(total, input.tolerance);
+  const differed = compare.diffPixels ?? 0;
+  const pixels = `${count(total)} pixels`;
+
+  if (differed === 0) {
+    say(CHECK_LABELS.pixels, `${pixels}, none different`, 'ok');
+    return;
+  }
+  const moved = `${count(differed)} different (${share(compare.diffRatio ?? 0)})`;
+  if (compare.equal) {
+    say(CHECK_LABELS.pixels, `${pixels}, ${moved}, within the ${count(allowed)} allowed`, 'ok');
+    return;
+  }
+  say(CHECK_LABELS.pixels, `${pixels}, ${moved}, more than the ${count(allowed)} allowed`, 'bad');
+}
+
+/**
+ * @param {Say} say
+ * @param {string[]} errors
+ */
+function consoleStep(say, errors) {
+  if (errors.length === 0) {
+    say(CHECK_LABELS.console, 'nothing thrown', 'ok');
+    return;
+  }
+  const first = firstLine(errors[0]);
+  say(
+    CHECK_LABELS.consoleBad,
+    `${count(errors.length)} ${plural(errors.length, 'error', 'errors')}${first ? `, first: ${first}` : ''}`,
+    'warn',
+  );
+}
+
+/**
+ * @param {Say} say
+ * @param {ChecksInput} input
+ */
+function retryStep(say, input) {
+  const attempts = input.attempts ?? 1;
+  if (attempts <= 1) return;
+  const passed = input.status === 'passed';
+  say(
+    CHECK_LABELS.retried,
+    passed
+      ? `it looked different at first, then matched on try ${count(attempts)} — it may be unreliable`
+      : `${count(attempts)} tries, different every time`,
+    'warn',
+  );
+}
+
+/**
+ * @param {Say} say
+ * @param {{approvedOn?: string, here?: string}|undefined} platform
+ */
+function platformStep(say, platform) {
+  if (!platform || !platform.approvedOn || !platform.here) return;
+  if (platform.approvedOn === platform.here) return;
+  say(
+    CHECK_LABELS.platform,
+    `approved on ${platform.approvedOn}, checked on ${platform.here} — text is drawn differently on each`,
+    'warn',
+  );
+}
+
+/**
+ * How many differing pixels this project is willing to forgive.
+ * The same arithmetic the comparison itself does, so the number a person is
+ * shown is the number the verdict was made against.
+ *
+ * @param {number} total
+ * @param {import('../types.js').ToleranceConfig|undefined} tolerance
+ * @returns {number}
+ */
+function allowanceFor(total, tolerance) {
+  const t = tolerance ?? {};
+  if (typeof t.maxPixels === 'number') return t.maxPixels;
+  return Math.floor(total * (t.pixels ?? DEFAULT_TOLERANCE.pixels));
+}
+
+/**
+ * @param {{width:number,height:number}} size
+ * @returns {string}
+ */
+function dimensions(size) {
+  return `${count(size.width)} × ${count(size.height)}`;
+}
+
+/**
+ * @param {number} n
+ * @returns {string}
+ */
+function count(n) {
+  return Number.isFinite(n) ? Math.round(n).toLocaleString('en-US') : String(n);
+}
+
+/**
+ * @param {number} n
+ * @param {string} one
+ * @param {string} many
+ * @returns {string}
+ */
+function plural(n, one, many) {
+  return n === 1 ? one : many;
+}
+
+/**
+ * A share of the picture, said in a way that is never misleading. A count of
+ * pixels can be large and still round to 0.00%, and "0.00% changed" beside a
+ * five-figure pixel count reads as a bug in the tool.
+ *
+ * @param {number} ratio
+ * @returns {string}
+ */
+function share(ratio) {
+  const pct = (Number.isFinite(ratio) ? ratio : 0) * 100;
+  if (pct <= 0) return '0%';
+  if (pct < 0.01) return 'under 0.01%';
+  return `${pct.toFixed(2)}%`;
+}
+
+/**
+ * @param {string|undefined} text
+ * @returns {string}
+ */
+function firstLine(text) {
+  if (typeof text !== 'string') return '';
+  const line = text.split('\n')[0].trim();
+  return line.length > 80 ? `${line.slice(0, 79)}…` : line;
+}

package/src/picture/capture.js

@@ -59,12 +59,21 @@ const KNOWN_KEYS = new Set([...ACTION_ORDER, 'text', 'note']);
  *   masks: import('../types.js').MaskRect[],
  *   timings: {steps: number, prepare: number, settle: number},
  *   spent: {steps: number, prepare: number, settle: number},
+ *   frozen: import('../core/events.js').FrozenPlan,
+ *   loaded?: import('../core/events.js').LoadedReport,
  *   thumbnail?: string,
  * }>}
  *   The standard report, plus the mask rectangles that were painted so the comparison can
  *   paint the exact same rectangles onto the approved picture, plus where the time went.
  *   Only this function knows how its own milliseconds were spent, so it says, rather than
  *   leaving the run to guess by wrapping things it cannot see inside.
+ *
+ *   `frozen` and `loaded` are here so the run can tell a person what was actually done to
+ *   this screen. `frozen` is what the freeze layer was ASKED for — the only place that
+ *   knows a check was switched off in the config, and therefore the only way the list can
+ *   say so instead of quietly claiming success. `loaded` is what the page itself said was
+ *   still loading at the moment the shutter fired: a measurement, taken here because it
+ *   cannot be recovered afterwards, and gone the instant the app moves on.
  */
 export async function captureScreen(page, screen, settings, ctx) {
   const deviceScaleFactor = settings.viewport.deviceScaleFactor ?? 2;
@@ -134,6 +143,14 @@ export async function captureScreen(page, screen, settings, ctx) {
     });
     spent.settle = since(startedSettle, clock());
 
+    // Asked the moment the picture exists, and never before: this is a statement about
+    // the frame that was kept. Reading it is a single round trip that touches nothing —
+    // no styles, no scroll, no focus — so it cannot change what the picture looks like,
+    // and at a couple of milliseconds against a screen that takes seconds it is not
+    // worth gating behind whether anybody is watching. Nobody can ask the page this
+    // question later; by then the app has moved on.
+    const loaded = await readLoaded(page);
+
     const rects = await resolveMasks(page, settings.masks ?? [], { deviceScaleFactor });
     // Masks force us to decode the picture; hold on to those pixels. The preview a
     // watcher is shown is made from the very same ones — the picture that gets
@@ -156,7 +173,7 @@ export async function captureScreen(page, screen, settings, ctx) {
       await runSteps(page, screen.after);
     }
 
-    /** @type {import('../types.js').CaptureReport & {masks: import('../types.js').MaskRect[], timings: typeof spent, spent: typeof spent, thumbnail?: string}} */
+    /** @type {import('../types.js').CaptureReport & {masks: import('../types.js').MaskRect[], timings: typeof spent, spent: typeof spent, frozen: import('../core/events.js').FrozenPlan, loaded?: import('../core/events.js').LoadedReport, thumbnail?: string}} */
     const report = {
       png,
       width: size.width,
@@ -165,10 +182,23 @@ export async function captureScreen(page, screen, settings, ctx) {
       consoleErrors: page.consoleErrors(),
       freeze: frozen.stats(),
       masks: rects,
+      // What was asked of the freeze layer, in the same words the config used. Written
+      // down here rather than worked out later, because by the time anybody reports on
+      // this screen the settings have been merged away.
+      frozen: {
+        clock: settings.freeze.clock !== false,
+        motion: settings.freeze.motion !== false,
+        random: settings.freeze.random !== 'off',
+        fonts: settings.freeze.fonts !== false,
+        network: settings.freeze.network ?? 'block-external',
+        frames: settleConfig.frames ?? 2,
+        maxDriftPixels: settleConfig.maxDriftPixels ?? 0,
+      },
       // The same three numbers under both names the rest of the tool asks for them by.
       timings: spent,
       spent,
     };
+    if (loaded) report.loaded = loaded;
     if (ctx.thumbnail === true) {
       const small = await thumbnailOf(painted ? painted.image : png);
       if (small) report.thumbnail = small;
@@ -184,6 +214,51 @@ export async function captureScreen(page, screen, settings, ctx) {
   }
 }
 
+/**
+ * What the page says is still loading, at the moment the picture was taken.
+ *
+ * The shutter already waited for fonts and images before it fired; this asks the page
+ * whether that wait actually finished, so a run can say "nothing still loading" and mean
+ * it. Read-only by construction — it looks at `document.fonts.status` and the `complete`
+ * flag of every `<img>`, and touches nothing else, which is what makes it safe to run
+ * against a page whose picture has already been kept.
+ *
+ * A page that navigated, closed or crashed answers nothing, and nothing is what gets
+ * reported: a missing measurement must never be dressed up as a passing one.
+ *
+ * @param {import('../types.js').PageHandle} page
+ * @returns {Promise<import('../core/events.js').LoadedReport|undefined>}
+ */
+async function readLoaded(page) {
+  const source = `(() => {
+  var out = { fonts: 'none', images: 0, imagesPending: 0 };
+  try {
+    if (document.fonts && document.fonts.status) out.fonts = String(document.fonts.status);
+  } catch (e) {}
+  try {
+    var imgs = document.images ? Array.prototype.slice.call(document.images) : [];
+    out.images = imgs.length;
+    for (var i = 0; i < imgs.length; i++) {
+      if (!imgs[i].complete) out.imagesPending++;
+    }
+  } catch (e) {}
+  return out;
+})()`;
+
+  try {
+    const seen = await page.evaluate(source);
+    if (!seen || typeof seen !== 'object') return undefined;
+    return {
+      fonts: typeof seen.fonts === 'string' ? seen.fonts : undefined,
+      images: Number(seen.images) || 0,
+      imagesPending: Number(seen.imagesPending) || 0,
+    };
+  } catch {
+    // The page is gone. Say nothing rather than guess.
+    return undefined;
+  }
+}
+
 /**
  * Milliseconds between two readings of the monotonic clock.
  * @param {bigint} from

package/src/picture/run.js

@@ -21,12 +21,17 @@ import { resetWindow } from '../drive/launch.js';
 import { gitInfo } from '../core/git.js';
 import { messageOf } from '../core/errors.js';
 import { detail } from '../core/log.js';
-import { emitEvent, fileUrl } from '../core/events.js';
+import { emitEvent, fileUrl, buildChecks } from '../core/events.js';
 
 /**
- * A picture result plus the one extra fact the flake register needs: whether it
- * only agreed with the approved picture after being photographed again.
- * @typedef {import('../types.js').PictureResult & {retriedToPass?: boolean}} PictureRunResult
+ * A picture result plus two things the plain result has no room for: whether it
+ * only agreed with the approved picture after being photographed again, which is
+ * what the flake register needs, and the list of what was actually done to the
+ * screen, which is what a person needs before they will believe the verdict.
+ * @typedef {import('../types.js').PictureResult & {
+ *   retriedToPass?: boolean,
+ *   checks?: import('../types.js').CheckStep[],
+ * }} PictureRunResult
  */
 
 /**
@@ -163,6 +168,10 @@ function emitDone(events, result, thumbs) {
     thumbnail: thumbs.shot,
     approvedThumb: thumbs.approved,
     diffThumb: thumbs.diff,
+    // The working: every step this screen really went through, in order. Built once,
+    // on the result, and passed straight along — so the panel and anything else
+    // listening read the same words the result was saved with.
+    checks: result.checks,
     // The real pictures. Only ever set for a file that was written or read a moment
     // ago, so anything that arrives here can be opened; a screen that was skipped, or
     // one that could not be photographed at all, sends none of them.
@@ -222,6 +231,44 @@ async function runOneScreen(project, page, screen, ctx) {
   /** @type {import('../types.js').CompareReport|null} */
   let compare = null;
   let attempts = 0;
+  /** @type {Awaited<ReturnType<typeof captureScreen>>|undefined} */
+  let last;
+
+  /**
+   * Hand back one finished screen, with the list of what was done to it when that
+   * list is worth building.
+   *
+   * Every way out of this function goes through here, so there is exactly one place
+   * that knows how to describe a screen — and no path that can quietly forget to.
+   *
+   * @param {PictureRunResult} result
+   * @param {string} [failure]  Why the screen could not be photographed at all.
+   * @returns {PictureRunResult}
+   */
+  function done(result, failure) {
+    if (worthExplaining(ctx, result)) {
+      result.checks = buildChecks({
+        screen,
+        status: result.status,
+        frozen: last?.frozen,
+        settle: last?.settle,
+        loaded: last?.loaded,
+        freeze: last?.freeze,
+        masks: last?.masks,
+        masksAsked: settings.masks.length,
+        consoleErrors,
+        size,
+        approvedSize: result.approvedSize,
+        compare,
+        hasApproved: Boolean(approved),
+        tolerance: settings.tolerance,
+        attempts,
+        platform: { approvedOn: approved?.meta?.platform, here: ctx.here },
+        failure,
+      });
+    }
+    return finish(ctx, result);
+  }
 
   try {
     // Photograph, and if it disagrees with the approved picture, photograph again
@@ -243,6 +290,7 @@ async function runOneScreen(project, page, screen, ctx) {
         thumbnail: ctx.thumbnail === true,
       });
       accountForCapture(ctx.timings, shot);
+      last = shot;
       consoleErrors = shot.consoleErrors;
       size = { width: shot.width, height: shot.height };
 
@@ -283,15 +331,18 @@ async function runOneScreen(project, page, screen, ctx) {
       }
     }
   } catch (error) {
-    return finish(ctx, {
-      name: screen.name,
-      describe: screen.describe,
-      status: 'failed',
-      message: join(`${screen.name} could not be photographed. ${messageOf(error)}`, platformNote),
-      durationMs: Date.now() - started,
-      attempts,
-      consoleErrors: consoleErrors.length > 0 ? consoleErrors : undefined,
-    });
+    return done(
+      {
+        name: screen.name,
+        describe: screen.describe,
+        status: 'failed',
+        message: join(`${screen.name} could not be photographed. ${messageOf(error)}`, platformNote),
+        durationMs: Date.now() - started,
+        attempts,
+        consoleErrors: consoleErrors.length > 0 ? consoleErrors : undefined,
+      },
+      messageOf(error),
+    );
   }
 
   /** @type {PictureRunResult} */
@@ -319,7 +370,7 @@ async function runOneScreen(project, page, screen, ctx) {
       });
       // It exists now, because that call is what wrote it.
       if (ctx.thumbs) ctx.thumbs.approvedFile = fileUrl(approvedPaths.png);
-      return finish(ctx, {
+      return done({
         ...base,
         status: 'new',
         approvedPath: approvedPaths.png,
@@ -327,7 +378,7 @@ async function runOneScreen(project, page, screen, ctx) {
         message: join(`${screen.name} had no approved picture — this one was saved as the first.`, platformNote),
       });
     }
-    return finish(ctx, {
+    return done({
       ...base,
       status: 'new',
       message: join(
@@ -340,7 +391,7 @@ async function runOneScreen(project, page, screen, ctx) {
   if (!compare) {
     // Cannot happen: with an approved picture every attempt compares. Kept so a
     // future edit that breaks that assumption fails loudly instead of silently passing.
-    return finish(ctx, {
+    return done({
       ...base,
       status: 'failed',
       message: join(`${screen.name} was photographed but never compared.`, platformNote),
@@ -357,7 +408,7 @@ async function runOneScreen(project, page, screen, ctx) {
 
   if (compare.equal) {
     const retriedToPass = attempts > 1;
-    return finish(ctx, {
+    return done({
       ...common,
       status: 'passed',
       retriedToPass,
@@ -399,7 +450,7 @@ async function runOneScreen(project, page, screen, ctx) {
     ? 'There is no difference picture for a size change — open the new picture and look at it.'
     : `Open the difference picture, and if the new look is right run \`staysfixed approve ${screen.name}\`.`;
 
-  return finish(ctx, {
+  return done({
     ...common,
     status: 'changed',
     diffPath,
@@ -446,6 +497,28 @@ function platformWarning(approvedOn, here) {
   return `Careful: this picture was approved on ${approvedOn} and checked on ${here}. Text is drawn differently on each, so a small difference here may mean nothing.`;
 }
 
+/**
+ * Is this screen worth explaining?
+ *
+ * Building the list is cheap — a few dozen short strings — but cheap is not the same
+ * as free, and there is no reason to write out the working of a screen nobody will
+ * ever read it for. Two cases deserve it: somebody has the live panel open and is
+ * watching this happen, or the screen did something other than quietly agree with
+ * its approved picture. A plain pass in a plain run carries no message at all, which
+ * is exactly how a pass with a warning on it — a retry, a picture approved on another
+ * computer — still gets its working shown.
+ *
+ * @param {ScreenCtx} ctx
+ * @param {PictureRunResult} result
+ * @returns {boolean}
+ */
+function worthExplaining(ctx, result) {
+  if (ctx.thumbnail === true) return true;
+  if (result.status !== 'passed') return true;
+  if (result.retriedToPass === true) return true;
+  return Boolean(result.message);
+}
+
 /**
  * @param {{onResult?: (r: PictureRunResult) => void}} ctx
  * @param {PictureRunResult} result

package/src/types.js

@@ -503,6 +503,10 @@ export {};
  *                                          thumbnail is unreadable, which is the whole point of looking.
  * @property {string} [approvedFile]          file:// URL of the approved picture.
  * @property {string} [diffFile]              file:// URL of the difference image.
+ * @property {CheckStep[]} [checks]           What was actually done to this screen, in order.
+ *                                          A verdict on its own ("matches") does not tell anyone what
+ *                                          was verified, and a row showing only a name and a duration
+ *                                          reads as a speed test. This is the working shown.
  * @property {string} [approvedThumb]
  * @property {string} [diffThumb]
  * @property {RunSummary} [summary]           Only on 'run:done'.
@@ -544,3 +548,16 @@ export {};
  * @property {number} other
  * @property {number} total
  */
+
+/**
+ * One thing that was done to a screen, and how it went.
+ *
+ * These are the real steps of a picture check, in the order they happen — reaching the
+ * screen, holding it still, waiting for fonts and pictures, matching the size, comparing
+ * every pixel, and listening for errors the page threw while nobody was looking.
+ *
+ * @typedef {object} CheckStep
+ * @property {string} label                   Plain language: "held still", "every pixel compared".
+ * @property {string} [detail]                The number behind it: "5,184,000 pixels, none different".
+ * @property {'ok'|'warn'|'bad'|'skipped'} state
+ */

package/src/watch/panel.js

@@ -217,6 +217,10 @@ export function panelHtml(plan = {}) {
 
     // --- every check, one quiet line each ----------------------------------
     '<div class="scroll" id="scroll">',
+    // The working for whatever is on the glass. It belongs in the scrolling
+    // column, not inside the picture's own box — put there it stole the
+    // picture's height and squashed it to a sliver.
+    '<section class="work-here" id="work" hidden></section>',
     '<section class="group" id="groupScreens" hidden>',
     '<p class="grouplabel">Screens<span class="mono" id="countScreens"></span></p>',
     '<div class="items" id="listScreens"></div>',
@@ -807,6 +811,56 @@ button { font: inherit; color: inherit; }
 .detail .claim em { font-style: normal; color: var(--faint); }
 .detail .story { margin-top: 7px; color: var(--faint); }
 
+/* The working, shown.
+   A verdict and a stopwatch do not tell anybody what was actually done to a
+   screen — which is exactly what the first person to look at this panel said.
+   So every step of a picture check is written out here in the order it
+   happened, numbered, with the number behind it on the right. It reads like a
+   receipt: quiet, aligned, and only ever seen by somebody who opened the row.
+   The spine down the left is built one segment per step, so the step that
+   moved or broke colours its own piece of it — the same idea as the meter at
+   the top of the window. */
+.work-here { padding: 2px var(--pad) 10px; }
+.work-here .worklabel { margin: 0 0 6px; }
+.detail .worklabel {
+  margin: 11px 0 6px;
+  font-size: var(--t-label); font-weight: 600;
+  letter-spacing: 0.16em; text-transform: uppercase;
+  color: var(--faint);
+}
+.work { list-style: none; margin: 0; padding: 0; }
+.step {
+  display: flex; align-items: baseline; gap: 9px;
+  padding: 4px 0 4px 11px;
+  box-shadow: inset 1px 0 0 var(--line);
+}
+.step.warn { box-shadow: inset 1.5px 0 0 var(--moved); }
+.step.bad { box-shadow: inset 1.5px 0 0 var(--broke); }
+.step.skipped { box-shadow: inset 1px 0 0 var(--resting); }
+/* The numeral keeps its own column whatever happens to the right of it — a
+   number that has been left behind on a line of its own is not a sequence any
+   more, which is what a long label does to it on a panel dragged narrow. */
+.stepno { flex: 0 0 15px; text-align: right; font-size: var(--t-label); color: var(--faint); }
+/* Label on one line, its number under it.
+   They used to share a line and wrap to a second, right-aligned one whenever the
+   number was long — which at 460px was most of them, and the column came out
+   ragged. Stacked, it reads down the page like a receipt: what was done, then
+   what it came to. */
+.stepbody { flex: 1 1 auto; min-width: 0; }
+.stepwhat { color: var(--soft); }
+.stepnum {
+  display: block; margin-top: 1px;
+  font-size: var(--t-meta); color: var(--faint);
+  overflow-wrap: anywhere;
+}
+/* A step that wants a person is the one thing in the list that is allowed to
+   be read from across the row: its words go to full strength, its number takes
+   the colour of what happened. */
+.step.warn .stepwhat, .step.bad .stepwhat { color: var(--ink); }
+.step.warn .stepno, .step.warn .stepnum { color: var(--moved); }
+.step.bad .stepno, .step.bad .stepnum { color: var(--broke); }
+.step.skipped .stepwhat, .step.skipped .stepno, .step.skipped .stepnum { color: var(--faint); }
+
 .nothing { padding: 26px 16px; color: var(--faint); font-size: var(--t-body); line-height: 1.7; text-align: center; }
 .nothing .mono { color: var(--soft); }
 
@@ -1120,7 +1174,7 @@ const SCRIPT = `
   var ui = {
     clock: el('clock'), project: el('project'), app: el('app'), targetsep: el('targetsep'),
     state: el('state'), note: el('note'),
-    track: el('track'), fill: el('fill'), counts: el('counts'), what: el('what'),
+    track: el('track'), fill: el('fill'), counts: el('counts'), what: el('what'), work: el('work'),
     stage: el('stage'), shot: el('shot'), layerA: el('layerA'), layerB: el('layerB'), blank: el('blank'),
     caption: el('caption'), shotname: el('shotname'), shotout: el('shotout'), tabs: el('tabs'),
     scroll: el('scroll'), follow: el('follow'), nothing: el('nothing'),
@@ -1454,6 +1508,17 @@ const SCRIPT = `
       out.textContent = entry.outText;
       d.appendChild(out);
     }
+    // The working. Everything that was really done to this screen, in the
+    // order it happened, numbered so it reads as a sequence rather than a bag
+    // of facts. Absent on older runs and on guards, and then simply not drawn.
+    var work = workList(entry.checks);
+    if (work) {
+      var worklabel = document.createElement('p');
+      worklabel.className = 'worklabel';
+      worklabel.textContent = 'What was done';
+      d.appendChild(worklabel);
+      d.appendChild(work);
+    }
     if (entry.failedAt) {
       var claim = document.createElement('div');
       claim.className = 'claim';
@@ -1475,6 +1540,80 @@ const SCRIPT = `
     if (!entry.hasDetail) setOpen(entry, false);
   }
 
+  /**
+   * The working, as a numbered list — or null when there is nothing to show.
+   *
+   * Everything that was really done to a screen, in the order it happened.
+   * Numbered because that is the question people ask: not "did it pass" but
+   * "what did you actually check". Absent on older runs and on guards.
+   *
+   * @param {any} checks
+   * @returns {HTMLOListElement|null}
+   */
+  function workList(checks) {
+    var steps = Array.isArray(checks) ? checks : null;
+    if (!steps || !steps.length) return null;
+    var work = document.createElement('ol');
+    work.className = 'work';
+    var counted = 0;
+    for (var k = 0; k < steps.length; k++) {
+      var step = steps[k];
+      if (!step || typeof step !== 'object') continue;
+      var said = String(step.label == null ? '' : step.label).trim();
+      if (!said) continue;
+      counted++;
+
+      var line = document.createElement('li');
+      var state = step.state;
+      var carries = state === 'warn' || state === 'bad' || state === 'skipped';
+      line.className = 'step ' + (carries ? state : 'ok');
+
+      var no = document.createElement('span');
+      no.className = 'stepno mono';
+      no.textContent = String(counted);
+      var body = document.createElement('span');
+      body.className = 'stepbody';
+      var what = document.createElement('span');
+      what.className = 'stepwhat';
+      what.textContent = said;
+      body.appendChild(what);
+
+      var behind = String(step.detail == null ? '' : step.detail).trim();
+      if (behind) {
+        var num = document.createElement('span');
+        num.className = 'stepnum mono';
+        num.textContent = behind;
+        body.appendChild(num);
+      }
+      line.appendChild(no);
+      line.appendChild(body);
+      work.appendChild(line);
+    }
+    return counted ? work : null;
+  }
+
+  /**
+   * The same list, always visible, under the picture on the glass.
+   *
+   * Behind a click it may as well not exist — the first person to use this asked
+   * for the checks and never found them, because a passing row is closed by
+   * default. Whichever screen is being shown says what was done to it, right
+   * there, without anybody having to go looking.
+   *
+   * @param {any} checks
+   */
+  function showWork(checks) {
+    var list = workList(checks);
+    ui.work.textContent = '';
+    if (!list) { ui.work.hidden = true; return; }
+    var label = document.createElement('p');
+    label.className = 'worklabel';
+    label.textContent = 'What was done';
+    ui.work.appendChild(label);
+    ui.work.appendChild(list);
+    ui.work.hidden = false;
+  }
+
   /** Put a screen's pictures back in the hero, with the words that went with them. */
   function recall(entry) {
     var p = entry.pics;
@@ -1488,6 +1627,7 @@ const SCRIPT = `
     if (!showed) return;
     nameTheShot(entry.name);
     sayOutcome(entry.tone, outcomeShort(p));
+    showWork(entry.checks);
     markShowing(entry);
   }
 
@@ -2348,6 +2488,9 @@ const SCRIPT = `
         // in the list, because the picture is where the person is looking and
         // that line is what tells them there is something to decide.
         sayOutcome(tone, outcomeShort(ev));
+        // And what was actually done to it, right under the picture, while the
+        // person is looking at it.
+        showWork(ev.checks);
       }
       tint(worstTone());
       return;
@@ -2418,6 +2561,9 @@ const SCRIPT = `
       // picture that is already decoded and the swap never flashes.
       preloadAll(entry.pics);
     }
+    // What was actually done to this screen. Kept as it arrived — the run is
+    // the one thing that knows, and the panel never invents a step.
+    if (Array.isArray(ev.checks)) entry.checks = ev.checks;
     entry.outText = outcomeText(kind, ev);
     if (entry.verdict) entry.verdict.textContent = shortOutcome(kind, ev);
     entry.failedAt = (kind === 'guard' && ev.status === 'failed' && ev.failedAt) ? ev.failedAt : '';