staysfixed 0.2.2 → 0.3.0

package/src/picture/capture.js

@@ -13,6 +13,11 @@ import { applyFreeze, prepareForShutter } from '../freeze/index.js';
 import { settle } from '../freeze/settle.js';
 import { resolveMasks, paintMasks } from '../freeze/mask.js';
 import { StaysFixedError, isExpected, messageOf } from '../core/errors.js';
+// The words a step is described by, and the two builders that turn what is known at
+// this instant into one line of the list. Imported rather than written again here so
+// the line a person watches tick is the same line, in the same words, that the
+// finished list hands back a moment later.
+import { CHECK_KEYS, CHECK_LABELS, checkStep, runningStep } from '../core/events.js';
 // store.js reads `pngSize` back out of this file. Two modules about the same pictures
 // leaning on each other is fine here — both sides are plain functions, so neither is
 // half-built when the other asks for it.
@@ -51,20 +56,42 @@ const KNOWN_KEYS = new Set([...ACTION_ORDER, 'text', 'note']);
  *   freeze: import('../types.js').FreezeConfig,
  *   masks: import('../types.js').Mask[],
  * }} settings
- * @param {{fixturesDir: string, record?: boolean, timeoutMs?: number, thumbnail?: boolean}} ctx
+ * @param {{
+ *   fixturesDir: string,
+ *   record?: boolean,
+ *   timeoutMs?: number,
+ *   thumbnail?: boolean,
+ *   onStep?: (step: import('../types.js').CheckStep) => void,
+ * }} ctx
  *   `thumbnail` is asked for only while somebody is watching the run happen; it costs a
  *   decode of the picture that was just taken (skipped when the masks already decoded it)
  *   plus about forty milliseconds of shrinking, so it is off unless it is wanted.
+ *
+ *   `onStep` is the same idea for words instead of pixels: hand one in and this says
+ *   what it is doing as it does it — each phase named the moment it starts and named
+ *   again the moment it settles — so a watcher can tick the list off live instead of
+ *   being shown a finished table. Gated exactly the way `thumbnail` is: the run hands
+ *   one in only while a panel is open, so the ordinary case is one `typeof` check per
+ *   phase and nothing allocated at all.
  * @returns {Promise<import('../types.js').CaptureReport & {
  *   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;
@@ -74,12 +101,88 @@ export async function captureScreen(page, screen, settings, ctx) {
   await page.setViewport(settings.viewport);
   page.clearConsole();
 
+  // What the freeze layer is being ASKED for. Worked out before it is asked, because a
+  // line announced as it starts can only be worded from what is already known — and a
+  // project that switched the clock freezing off has to be told that at the moment it
+  // does not happen, not have a freeze claimed and then taken back.
+  /** @type {import('../core/events.js').FrozenPlan} */
+  const plan = {
+    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,
+  };
+  const masksAsked = (settings.masks ?? []).length;
+
+  // Gated exactly the way `thumbnail` is: the run hands an `onStep` in only while a
+  // panel is open. Nobody watching means this is null, every announcement below is one
+  // `if` that does nothing, and not a single object is made.
+  const onStep = typeof ctx.onStep === 'function' ? ctx.onStep : null;
+  /**
+   * The line announced as started and not yet settled — so a failure can close it
+   * instead of leaving a row spinning forever on somebody's screen.
+   * @type {import('../types.js').CheckStep|null}
+   */
+  let pending = null;
+
+  /**
+   * Name a phase as it begins.
+   * @param {import('../core/events.js').CheckKey} key
+   * @param {import('../core/events.js').ChecksInput} input
+   * @returns {void}
+   */
+  const begins = (key, input) => {
+    if (!onStep) return;
+    const step = runningStep(key, input);
+    pending = step ?? null;
+    if (step) onStep(step);
+  };
+
+  /**
+   * Name the same phase again, settled, under the same key.
+   * @param {import('../core/events.js').CheckKey} key
+   * @param {import('../core/events.js').ChecksInput} input
+   * @param {import('../types.js').CheckStep} [instead]  For a line whose number is not
+   *   knowable yet; the finished list fills that in.
+   * @returns {void}
+   */
+  const settled = (key, input, instead) => {
+    if (!onStep) return;
+    pending = null;
+    const step = instead ?? checkStep(key, input);
+    if (step) onStep(step);
+  };
+
+  /**
+   * Close whatever was in flight when something went wrong.
+   * @param {unknown} error
+   * @returns {void}
+   */
+  const closePending = (error) => {
+    if (!onStep || !pending) return;
+    const why = messageOf(error);
+    // Where a phase has its own wording for going wrong, use it: "could not reach the
+    // screen" is what happened, and leaving "reached the screen" up with a cross beside
+    // it says the opposite of the truth for as long as anybody is reading it.
+    const label = pending.key === CHECK_KEYS.steps ? CHECK_LABELS.stepsFailed : pending.label;
+    onStep({ ...pending, label, state: 'bad', detail: why });
+    pending = null;
+  };
+
+  begins(CHECK_KEYS.frozen, { screen, frozen: plan });
   const frozen = await applyFreeze(page, settings.freeze, {
     fixturesDir: ctx.fixturesDir,
     screenName: screen.name,
     record: ctx.record ?? false,
     deviceScaleFactor,
+  }).catch((error) => {
+    closePending(error);
+    throw error;
   });
+  settled(CHECK_KEYS.frozen, { screen, frozen: plan });
 
   // A frozen clock cannot time anything, so the stopwatch is the host's own, and it is
   // the monotonic one: a machine that adjusts its clock mid-run must not be able to
@@ -90,11 +193,13 @@ export async function captureScreen(page, screen, settings, ctx) {
   const spent = { steps: 0, prepare: 0, settle: 0 };
 
   try {
+    begins(CHECK_KEYS.steps, { screen });
     if (typeof screen.do === 'function') {
       await screen.do(page);
     } else {
       await runSteps(page, screen.steps ?? []);
     }
+    settled(CHECK_KEYS.steps, { screen });
 
     // Scrolling back to the top is the deterministic default, but a screen that
     // deliberately scrolled somewhere must be photographed where it landed.
@@ -104,11 +209,21 @@ export async function captureScreen(page, screen, settings, ctx) {
     const startedPrepare = clock();
     spent.steps = since(startedSteps, startedPrepare);
 
+    // Waiting for the page to be ready. WHAT was still loading can only be read off the
+    // frame that ends up being kept, which does not exist yet, so this line settles on
+    // the one thing that is true here — the shutter waited — and the finished list fills
+    // in the count of faces and pictures a moment later, on the same line.
+    begins(CHECK_KEYS.loaded, { screen, frozen: plan });
     await prepareForShutter(page, {
       fonts: settings.freeze.fonts !== false,
       timeoutMs,
       keepScroll: scrolledOnPurpose,
     });
+    settled(
+      CHECK_KEYS.loaded,
+      { screen, frozen: plan },
+      plan.fonts ? { key: CHECK_KEYS.loaded, label: CHECK_LABELS.loaded, state: 'ok' } : undefined,
+    );
 
     /** @type {import('../types.js').CaptureOptions} */
     const shotOptions = {};
@@ -124,6 +239,10 @@ export async function captureScreen(page, screen, settings, ctx) {
     const startedSettle = clock();
     spent.prepare = since(startedPrepare, startedSettle);
 
+    // Holding still — and the shutter is inside it. The settle loop photographs the
+    // screen over and over until two frames in a row are identical and keeps the last of
+    // them, so this is ONE line rather than two: there is one thing happening.
+    begins(CHECK_KEYS.settle, { screen, frozen: plan });
     const held = await settle(page, {
       frames: settleConfig.frames ?? 2,
       intervalMs: settleConfig.intervalMs ?? 250,
@@ -133,7 +252,17 @@ export async function captureScreen(page, screen, settings, ctx) {
       probe: () => page.shoot(probeOptions),
     });
     spent.settle = since(startedSettle, clock());
+    settled(CHECK_KEYS.settle, { screen, settle: held.report, frozen: plan });
+
+    // 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);
 
+    begins(CHECK_KEYS.masks, { screen, masksAsked });
     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
@@ -142,6 +271,9 @@ export async function captureScreen(page, screen, settings, ctx) {
     const painted = rects.length > 0 ? paintInto(held.png, rects) : null;
     const png = painted ? painted.png : held.png;
     const size = pngSize(png);
+    // Said after the painting, not after the finding: the line claims the boxes are on
+    // the picture, so it waits until they are.
+    settled(CHECK_KEYS.masks, { screen, masks: rects, masksAsked });
 
     // The picture is taken; now put the app back if this screen asked us to.
     //
@@ -156,24 +288,42 @@ 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}} */
+    // Requests are not a phase — the outside world is kept out for the whole capture —
+    // so this is one line, said once, at the end. Counted here rather than a few lines
+    // earlier so the number a watcher sees is the same number the finished list carries,
+    // including anything the putting-back steps asked for.
+    const stats = frozen.stats();
+    settled(CHECK_KEYS.network, { screen, freeze: stats, frozen: plan });
+
+    /** @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,
       height: size.height,
       settle: held.report,
       consoleErrors: page.consoleErrors(),
-      freeze: frozen.stats(),
+      freeze: stats,
       masks: rects,
+      // What was asked of the freeze layer, in the same words the config used. Worked
+      // out at the top rather than here, because by the time anybody reports on this
+      // screen the settings have been merged away — and because the live list needs the
+      // same answer before any of this happens, and the two must never disagree.
+      frozen: plan,
       // 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;
     }
     return report;
+  } catch (error) {
+    // A row that stays "running" for the rest of the run is a lie about what happened.
+    // The run reports the failure itself; this only closes the line it fell over on.
+    closePending(error);
+    throw error;
   } finally {
     // Releasing must never be the thing that hides a real failure.
     try {
@@ -184,6 +334,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, checkStep, runningStep, CHECK_KEYS } 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.
@@ -223,6 +232,88 @@ async function runOneScreen(project, page, screen, ctx) {
   let compare = null;
   let attempts = 0;
 
+  /**
+   * Say one thing about this screen the moment it is true.
+   *
+   * The finished list at the end is still the authority — a watcher that missed every
+   * one of these ends up with exactly the same rows — but a person who is watching
+   * wants to see the working tick past as it happens rather than appear all at once
+   * when the screen is already over.
+   *
+   * Only while somebody is watching, and gated on the very same flag the small pictures
+   * are: the run sets `thumbnail` when a panel is open. Nobody watching means this is
+   * undefined, nothing is built and nothing is sent.
+   *
+   * @type {((step: import('../types.js').CheckStep) => void)|undefined}
+   */
+  const onStep =
+    ctx.thumbnail === true && ctx.events
+      ? (/** @type {import('../types.js').CheckStep} */ step) => {
+          emitEvent(ctx.events, { type: 'screen:step', name: screen.name, step });
+        }
+      : undefined;
+
+  /**
+   * One line of the working, built from what is known at this instant.
+   *
+   * @param {import('../core/events.js').CheckKey} key
+   * @param {boolean} [starting]  True to name it as it begins, false once it has settled.
+   * @returns {void}
+   */
+  function tell(key, starting) {
+    if (!onStep) return;
+    /** @type {import('../core/events.js').ChecksInput} */
+    const known = {
+      screen,
+      size,
+      approvedSize: compare?.approvedSize,
+      compare,
+      hasApproved: Boolean(approved),
+      tolerance: settings.tolerance,
+      consoleErrors,
+    };
+    const step = starting ? runningStep(key, known) : checkStep(key, known);
+    if (step) onStep(step);
+  }
+  /** @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
     // before believing it. One flickering frame is not a regression.
@@ -241,8 +332,13 @@ async function runOneScreen(project, page, screen, ctx) {
         record: ctx.record ?? false,
         timeoutMs: settings.freeze.settle?.timeoutMs,
         thumbnail: ctx.thumbnail === true,
+        // The phases inside one photograph — freezing, the recipe, waiting, holding
+        // still, painting over the live areas — can only be announced by the thing
+        // doing them. Everything after the shutter is announced here instead.
+        onStep,
       });
       accountForCapture(ctx.timings, shot);
+      last = shot;
       consoleErrors = shot.consoleErrors;
       size = { width: shot.width, height: shot.height };
 
@@ -270,6 +366,12 @@ async function runOneScreen(project, page, screen, ctx) {
 
       if (!approved) break;
 
+      // These two lines exist only once there is something to compare against, so they
+      // are said here rather than by the capture: the size match and the pixel count are
+      // both answered by the single call below.
+      tell(CHECK_KEYS.size, true);
+      tell(CHECK_KEYS.pixels, true);
+
       const stopCompare = ctx.timings?.mark('compare');
       // compareFast, not comparePng: identical bytes are answered from the PNG header
       // instead of decoding two retina images pixel by pixel. Nothing changed on most
@@ -277,21 +379,36 @@ async function runOneScreen(project, page, screen, ctx) {
       // comparing stage from about a quarter of a second a screen to nothing at all.
       compare = compareFast(approved.png, shot.png, settings.tolerance, shot.masks);
       stopCompare?.();
+      tell(CHECK_KEYS.size);
+      tell(CHECK_KEYS.pixels);
       if (compare.equal) break;
       if (attempt <= ctx.retries) {
         detail(`${screen.name} looked different on attempt ${attempt} — taking it again.`);
       }
     }
+
+    if (!approved) {
+      // Nothing to measure this against, which is an answer rather than a gap. Said
+      // here because the loop above never reached a comparison to say it.
+      tell(CHECK_KEYS.size);
+      tell(CHECK_KEYS.pixels);
+    }
+    // Whatever the page shouted while nobody was looking. Known from the moment the
+    // picture was taken, and the last line of the working either way.
+    tell(CHECK_KEYS.console);
   } 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 +436,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 +444,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 +457,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 +474,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 +516,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 +563,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

@@ -304,6 +304,9 @@
  * @property {string} [failedAt]              The plain-language expectation that failed.
  * @property {string} [file]
  * @property {string} [because]
+ * @property {CheckStep[]} [checks]           Every claim the guard asserted and every action it took,
+ *                                          in order. A guard that failed still shows the claims that
+ *                                          held before it — that is most of the value.
  * @property {number} durationMs
  * @property {number} [attempts]
  */
@@ -482,7 +485,7 @@ export {};
  * run began) so a watcher can draw a timeline without keeping its own clock.
  *
  * @typedef {object} RunEvent
- * @property {'run:start'|'screen:start'|'screen:shot'|'screen:done'|'guard:start'|'guard:done'|'phase'|'note'|'run:done'} type
+ * @property {'run:start'|'screen:start'|'screen:step'|'screen:shot'|'screen:done'|'guard:start'|'guard:step'|'guard:done'|'phase'|'note'|'run:done'} type
  * @property {number} at                      Milliseconds since the run started.
  * @property {string} [name]                  Screen or guard name.
  * @property {string} [describe]              The plain-language description.
@@ -503,6 +506,12 @@ 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} [step]              One step, reported the moment it happens, so a watcher can
+ *                                          tick the list off live instead of waiting for the verdict.
+ * @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 +553,18 @@ 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 {'running'|'ok'|'warn'|'bad'|'skipped'} state
+ * @property {string} [key]                   Stable id, so a step reported as 'running' can be found
+ *                                          again and settled when it finishes.
+ */