staysfixed 0.1.1 → 0.2.0

package/src/drive/page.js

@@ -15,6 +15,7 @@ import { Buffer } from 'node:buffer';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { StaysFixedError } from '../core/errors.js';
 import { detail } from '../core/log.js';
+import { waitForQuietDom } from './launch.js';
 
 /**
  * Keys `press()` understands by name. Anything else is sent as literal text.
@@ -50,6 +51,18 @@ const MAX_CONSOLE_ERRORS = 50;
 /** Chrome cannot paint a picture wider or taller than this. */
 const MAX_CAPTURE_SIDE = 16384;
 
+/**
+ * After a click, how long the page has to stay unchanged before we call it finished,
+ * and how long we are prepared to wait for that.
+ *
+ * Both are deliberately small. This is here to replace the `{ wait: 400 }` people write
+ * because they are guessing, so it has to be quicker than the guess on a page that has
+ * already finished and it must never become the slow part of a run on a page that fidgets
+ * forever — the settle loop is the real guarantee, not this.
+ */
+const CLICK_QUIET_MS = 120;
+const CLICK_QUIET_CAP_MS = 1500;
+
 /**
  * Seconds, written the way a person says them: 15, 1.5, 0.5.
  * @param {number} ms
@@ -518,8 +531,17 @@ export async function createPage(cdp, opts) {
   }
 
   /**
+   * Click something, and by default wait for the page to finish reacting.
+   *
+   * `settle` is the reason a screen recipe does not need `{ wait: 400 }` after a click.
+   * A hand-written wait is always a guess: too short and the picture catches the screen
+   * half-drawn, too long and every run pays for it forever. Instead we watch the page
+   * itself and carry on the moment it stops changing — usually in a fraction of the time
+   * somebody would have guessed. Pass `{ settle: false }` for a click that deliberately
+   * starts something you want to photograph while it is still happening.
+   *
    * @param {string} selector
-   * @param {{timeoutMs?: number}} [o]
+   * @param {{timeoutMs?: number, settle?: boolean}} [o]
    * @returns {Promise<void>}
    */
   async function click(selector, o) {
@@ -543,7 +565,10 @@ export async function createPage(cdp, opts) {
       await send('Input.dispatchMouseEvent', { ...base, type: 'mouseMoved', buttons: 0 });
       await send('Input.dispatchMouseEvent', { ...base, type: 'mousePressed', buttons: 1 });
       await send('Input.dispatchMouseEvent', { ...base, type: 'mouseReleased', buttons: 0 });
-      if (await heard()) return;
+      if (await heard()) {
+        await settleAfterClick(o);
+        return;
+      }
       detail(`click on ${selector} was not delivered (try ${attempt} of ${attempts})`);
       await sleep(120);
     }
@@ -556,6 +581,25 @@ export async function createPage(cdp, opts) {
     if (!done) {
       throw new StaysFixedError(`Could not click "${selector}" — it disappeared while I was trying.`);
     }
+    await settleAfterClick(o);
+  }
+
+  /**
+   * Give whatever the click started a chance to finish.
+   *
+   * `waitForQuietDom` wants the whole launched app because that is what everything else
+   * hands it; all it ever touches is `page.evaluate`, and here the page is the one being
+   * built, so it is handed exactly that.
+   *
+   * @param {{settle?: boolean}} [o]
+   * @returns {Promise<void>}
+   */
+  async function settleAfterClick(o) {
+    if (o?.settle === false) return;
+    const asApp = /** @type {import('../types.js').LaunchedApp} */ (
+      /** @type {unknown} */ ({ page: { evaluate } })
+    );
+    await waitForQuietDom(asApp, { quietMs: CLICK_QUIET_MS, timeoutMs: CLICK_QUIET_CAP_MS });
   }
 
   /**
@@ -845,7 +889,16 @@ export async function createPage(cdp, opts) {
   }
 
   /**
-   * @param {import('../types.js').CaptureOptions} [captureOpts]
+   * Take a picture of the window.
+   *
+   * `format: 'jpeg'` with a `quality` exists for one caller: the settle loop, which
+   * shoots the same screen over and over only to ask whether anything moved. Those frames
+   * are thrown away, never compared against an approved picture and never written to
+   * disk, so a cheap lossy encode is the right tool — it costs a fraction of a full-size
+   * retina PNG and two JPEGs of one unchanged frame are byte-for-byte identical, which is
+   * the whole question. Every kept picture is a PNG, which is the default.
+   *
+   * @param {import('../types.js').CaptureOptions & {format?: 'png'|'jpeg', quality?: number}} [captureOpts]
    * @returns {Promise<Buffer>}
    */
   async function shoot(captureOpts) {
@@ -891,12 +944,15 @@ export async function createPage(cdp, opts) {
       };
     }
 
+    const jpeg = o.format === 'jpeg';
     /** @type {Record<string, unknown>} */
     const params = {
-      format: 'png',
+      format: jpeg ? 'jpeg' : 'png',
       captureBeyondViewport: Boolean(o.fullPage),
       fromSurface: true,
     };
+    // Chrome ignores quality on a PNG, and refuses a value outside 0..100.
+    if (jpeg) params.quality = Math.max(0, Math.min(100, Math.round(o.quality ?? 50)));
     if (clip) params.clip = clip;
 
     const res = await send('Page.captureScreenshot', params);

package/src/freeze/fonts.js

@@ -36,7 +36,9 @@ export function fontsScript() {
   // exactly what made take 1 of twenty differ from takes 2 to 20: one picture in
   // Helvetica, nineteen in the web font.
   //
-  // So we do not wait for the fonts to arrive. We ask for them.
+  // So we do not wait for the fonts to arrive. We ask for them. The list of promises is
+  // handed back rather than awaited here, because how many faces needed asking is the
+  // thing that decides whether there is anything left to wait for at all.
   function forceLoad() {
     var pending = [];
     faces().forEach(function (f) {
@@ -45,7 +47,7 @@ export function fontsScript() {
         else if (f.status === 'loading') pending.push(Promise.resolve(f.loaded).catch(function () {}));
       } catch (e) { /* a face the browser refuses to load is not our problem */ }
     });
-    return Promise.all(pending);
+    return pending;
   }
 
   window.__staysfixed_fontsReady = function (ms) {
@@ -53,21 +55,37 @@ export function fontsScript() {
     if (!document.fonts) return Promise.resolve('no-font-api');
 
     var ready = (async function () {
+      var asked = 0;
       // Loading one face can pull in another (a bold weight referenced by a rule that
       // only matched once the first face changed the layout), so go round a few times
       // until nothing is left unloaded.
+      //
+      // A round that asks for nothing is the finish line, and it is worth leaving on it
+      // rather than going round again: if no face is unloaded or loading then every face
+      // is in, document.fonts.ready would resolve on the spot, and asking it anyway costs
+      // a whole trip through the page for an answer we already have. Most screens of most
+      // apps land here on the first round, and every screen after the first one does,
+      // because the fonts arrived for the screen before it.
       for (var round = 0; round < 5; round++) {
-        await forceLoad();
+        var pending = forceLoad();
+        // The one case where "nothing to ask for" is not the finish line: a document that
+        // is still parsing has not met its @font-face rules yet, so the face list can be
+        // empty and still grow. There, wait the old way at least once.
+        if (pending.length === 0 && (round > 0 || document.readyState === 'complete')) break;
+        asked += pending.length;
+        await Promise.all(pending);
         try { await document.fonts.ready; } catch (e) { /* ignore */ }
-        var waiting = faces().some(function (f) { return f.status !== 'loaded'; });
-        if (!waiting && document.fonts.status === 'loaded') break;
       }
-      // Two frames, so the reflow the last face caused has actually been painted
-      // rather than merely scheduled.
-      await new Promise(function (r) {
-        if (typeof requestAnimationFrame !== 'function') return r(undefined);
-        requestAnimationFrame(function () { requestAnimationFrame(function () { r(undefined); }); });
-      });
+      // Two frames, so the reflow the last face caused has actually been painted rather
+      // than merely scheduled. No face needed loading means no face changed the layout,
+      // so there is no reflow to wait for — and the shutter code waits two frames of its
+      // own after clearing focus and scroll, which is the real paint barrier.
+      if (asked > 0) {
+        await new Promise(function (r) {
+          if (typeof requestAnimationFrame !== 'function') return r(undefined);
+          requestAnimationFrame(function () { requestAnimationFrame(function () { r(undefined); }); });
+        });
+      }
       return document.fonts.status || 'loaded';
     })();
 
@@ -163,11 +181,25 @@ export async function waitForFonts(page, opts = {}) {
 export async function waitForImages(page, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 10000;
 
-  // Walking every element to read computed styles is the expensive part, so it is capped.
-  // Background images below the first few thousand elements are almost always off-screen.
+  // The cheap questions are asked first and the expensive one is earned.
+  //
+  // The expensive one is background images. There is no list of them anywhere, so the
+  // only honest way to find them is to read the computed style of every element — and on
+  // almost every app that walk costs more than the whole rest of the shutter and comes
+  // back with nothing, because no rule on the page ever says url(). So the stylesheets
+  // are asked first, in one pass that stops at the first sign of an image, and elements
+  // are only walked when the answer is yes. When they are walked, it is the ones on
+  // screen: an image below the fold is not what delays this paint.
+  //
+  // Being less than exhaustive here cannot produce a wrong picture. This is a head start,
+  // not the guarantee — the guarantee is the settle loop, which refuses to accept any
+  // photograph until two frames in a row are the same frame. An image nobody waited for
+  // costs one more round of settling and nothing else.
   const source = `(async () => {
   var LIMIT = ${timeoutMs};
   var MAX_ELEMENTS = 4000;
+  var MAX_STYLES = 1200;
+  var MAX_RULES = 4000;
   var waits = [];
 
   var imgs = document.images ? Array.prototype.slice.call(document.images) : [];
@@ -181,34 +213,6 @@ export async function waitForImages(page, opts = {}) {
     })(imgs[i]);
   }
 
-  var urls = {};
-  var all = document.querySelectorAll('*');
-  var count = Math.min(all.length, MAX_ELEMENTS);
-  for (var e = 0; e < count; e++) {
-    var bg = '';
-    try { bg = getComputedStyle(all[e]).backgroundImage; } catch (err) { bg = ''; }
-    if (!bg || bg === 'none' || bg.indexOf('url(') === -1) continue;
-    var chunks = bg.split('url(');
-    for (var c = 1; c < chunks.length; c++) {
-      var end = chunks[c].indexOf(')');
-      if (end < 0) continue;
-      var u = chunks[c].slice(0, end).trim();
-      var first = u.charAt(0);
-      var last = u.charAt(u.length - 1);
-      if ((first === '"' && last === '"') || (first === "'" && last === "'")) u = u.slice(1, -1);
-      // data: URLs are already here by definition; nothing to wait for.
-      if (u && u.slice(0, 5) !== 'data:') urls[u] = true;
-    }
-  }
-  Object.keys(urls).forEach(function (u) {
-    waits.push(new Promise(function (r) {
-      var probe = new Image();
-      probe.onload = r;
-      probe.onerror = r;
-      probe.src = u;
-    }));
-  });
-
   // A stylesheet still in flight repaints the whole page the instant it applies — the
   // worst possible moment for that is one millisecond after the shutter.
   var links = document.querySelectorAll('link[rel~="stylesheet"]');
@@ -226,6 +230,92 @@ export async function waitForImages(page, opts = {}) {
     })(links[l]);
   }
 
+  // Does any style on this page mention an image at all? One pass, stopping early, over
+  // the declarations themselves rather than their serialised text.
+  var budget = MAX_RULES;
+  function mentionsUrl(style) {
+    if (!style) return false;
+    var props = ['backgroundImage', 'borderImageSource', 'maskImage', 'webkitMaskImage', 'listStyleImage', 'content'];
+    for (var p = 0; p < props.length; p++) {
+      var v = '';
+      try { v = style[props[p]]; } catch (err) { v = ''; }
+      if (v && String(v).indexOf('url(') !== -1) return true;
+    }
+    return false;
+  }
+  function scanRules(rules) {
+    for (var i = 0; i < rules.length; i++) {
+      if (budget <= 0) return true;
+      budget--;
+      var rule = rules[i];
+      if (mentionsUrl(rule.style)) return true;
+      // @media, @supports and @layer hold their rules inside themselves; @import holds a
+      // whole other stylesheet, which never appears in document.styleSheets on its own.
+      var inner = null;
+      try { inner = rule.cssRules || (rule.styleSheet && rule.styleSheet.cssRules); } catch (err) { inner = null; }
+      if (inner === null) return true;
+      if (inner && inner.length && scanRules(inner)) return true;
+    }
+    return false;
+  }
+  function anyImageInCss() {
+    // Inline styles are not in document.styleSheets at all, and this is one indexed query.
+    try { if (document.querySelector('[style*="url("]')) return true; } catch (err) { }
+    // Sheets a framework adopted straight onto the document are not in styleSheets.
+    var sheets = Array.prototype.slice.call(document.styleSheets || []);
+    if (document.adoptedStyleSheets) sheets = sheets.concat(Array.prototype.slice.call(document.adoptedStyleSheets));
+    for (var s = 0; s < sheets.length; s++) {
+      var rules = null;
+      try { rules = sheets[s].cssRules; } catch (err) { rules = null; }
+      // A sheet from another origin will not show its rules. Assume it could be hiding an
+      // image rather than pretend it cannot.
+      if (rules === null) return true;
+      if (scanRules(rules)) return true;
+    }
+    return false;
+  }
+
+  if (anyImageInCss()) {
+    var urls = {};
+    var vw = window.innerWidth || 0;
+    var vh = window.innerHeight || 0;
+    var all = document.querySelectorAll('*');
+    var count = Math.min(all.length, MAX_ELEMENTS);
+    var looked = 0;
+    for (var e = 0; e < count && looked < MAX_STYLES; e++) {
+      var node = all[e];
+      var box = null;
+      try { box = node.getBoundingClientRect(); } catch (err) { box = null; }
+      if (!box || box.width <= 0 || box.height <= 0) continue;
+      // On screen, or one screenful below it — far enough to cover a full-page picture's
+      // first fold without reading the style of a thousand things nobody can see.
+      if (box.bottom < 0 || box.right < 0 || box.left > vw || box.top > vh * 2) continue;
+      looked++;
+      var bg = '';
+      try { bg = getComputedStyle(node).backgroundImage; } catch (err) { bg = ''; }
+      if (!bg || bg === 'none' || bg.indexOf('url(') === -1) continue;
+      var chunks = bg.split('url(');
+      for (var c = 1; c < chunks.length; c++) {
+        var end = chunks[c].indexOf(')');
+        if (end < 0) continue;
+        var u = chunks[c].slice(0, end).trim();
+        var first = u.charAt(0);
+        var last = u.charAt(u.length - 1);
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) u = u.slice(1, -1);
+        // data: URLs are already here by definition; nothing to wait for.
+        if (u && u.slice(0, 5) !== 'data:') urls[u] = true;
+      }
+    }
+    Object.keys(urls).forEach(function (u) {
+      waits.push(new Promise(function (r) {
+        var probe = new Image();
+        probe.onload = r;
+        probe.onerror = r;
+        probe.src = u;
+      }));
+    });
+  }
+
   if (waits.length === 0) return 0;
   await Promise.race([
     Promise.all(waits),

package/src/freeze/settle.js

@@ -7,6 +7,12 @@
  *
  * The rule is simple and it is the whole reason picture checks can be trusted: take the
  * photo, take it again, and only accept it once two photos in a row agree.
+ *
+ * Two photos of a retina window is a second of every screen's time, and almost all of it
+ * is spent turning pixels into PNG and sending them down the wire — for pictures nobody
+ * ever looks at, whose only job was to answer "did anything move". So a caller may hand
+ * in a cheap `probe` for that question and keep the expensive capture for the one picture
+ * that is actually kept. See `settleByProbe` for why a lossy probe is sound.
  */
 
 import { PNG } from 'pngjs';
@@ -15,7 +21,16 @@ import { detail } from '../core/log.js';
 
 /**
  * @param {import('../types.js').PageHandle} page
- * @param {{frames?: number, intervalMs?: number, timeoutMs?: number, maxDriftPixels?: number, capture: () => Promise<Buffer>}} opts
+ * @param {{
+ *   frames?: number,
+ *   intervalMs?: number,
+ *   timeoutMs?: number,
+ *   maxDriftPixels?: number,
+ *   capture: () => Promise<Buffer>,
+ *   probe?: () => Promise<Buffer>,
+ * }} opts
+ *   `capture` takes the picture that is kept. `probe`, when given, is a cheap shot used
+ *   only to decide whether the page has stopped moving — never the picture itself.
  * @returns {Promise<{report: import('../types.js').SettleReport, png: Buffer}>}
  */
 export async function settle(page, opts) {
@@ -25,11 +40,20 @@ export async function settle(page, opts) {
   const maxDriftPixels = Math.max(0, opts.maxDriftPixels ?? 0);
   const capture = opts.capture;
 
+  // A probe can only ever answer yes or no: it is not the picture, so counting how many
+  // pixels of it moved would be counting the wrong pixels. A project that allows a few
+  // drifting pixels is asking for a count, so it goes the long way round on real photos.
+  const probe = maxDriftPixels === 0 ? opts.probe : undefined;
+
   // Host-side Date.now, not the page's — the page's clock is frozen on purpose.
   const started = Date.now();
 
   await waitUntilQuiet(page, Math.min(timeoutMs, 5000));
 
+  if (probe) {
+    return await settleByProbe({ probe, capture, frames, intervalMs, timeoutMs, started });
+  }
+
   /** @type {Buffer|null} */
   let previous = null;
   /** @type {unknown} */
@@ -86,6 +110,146 @@ export async function settle(page, opts) {
   };
 }
 
+/**
+ * The same rule, asked cheaply.
+ *
+ * WHY a lossy probe is safe. The probe is never the picture and never reaches disk; the
+ * only thing asked of it is "are these two frames the same frame". A JPEG encoder is
+ * deterministic, so two JPEGs of one unchanged frame are byte-for-byte identical, and two
+ * JPEGs that differ can only differ because the pixels underneath them did. That is
+ * exactly the question, and it is answered for about half the cost of a full-size retina
+ * PNG — and the picture that used to be thrown away is not taken at all.
+ *
+ * WHY the photograph is taken in the middle. The old loop shot the screen, waited, shot it
+ * again, and kept the second one. This one probes, takes the real photograph, and probes
+ * once more: the kept picture sits BETWEEN two frames that agree, instead of being the
+ * later of them. If anything moved while the shutter was open, the probe after it
+ * disagrees and the whole thing goes round again — which the old loop could not notice,
+ * because it kept a picture nothing had checked since.
+ *
+ * WHY there is no pause between agreeing frames. The old quarter-second sat between the
+ * two photographs so they could not both land inside one painted frame. Taking the real
+ * photograph between the probes already separates them by longer than a screenshot takes,
+ * so the separation is still bought and no longer paid for twice. The pause is kept for
+ * where it earns its keep: after two probes have actually disagreed, which is the only
+ * time a page is worth waiting for.
+ *
+ * @param {{
+ *   probe: () => Promise<Buffer>,
+ *   capture: () => Promise<Buffer>,
+ *   frames: number,
+ *   intervalMs: number,
+ *   timeoutMs: number,
+ *   started: number,
+ * }} o
+ * @returns {Promise<{report: import('../types.js').SettleReport, png: Buffer}>}
+ */
+async function settleByProbe(o) {
+  // One frame is all this project asks for, so there is nothing to compare it against.
+  if (o.frames <= 1) {
+    const only = await o.capture();
+    return {
+      report: { settled: true, attempts: 0, lastDriftPixels: 0, waitedMs: Date.now() - o.started },
+      png: only,
+    };
+  }
+
+  // The photograph itself stands in for the last frame, so one fewer probe is needed than
+  // the number of agreeing frames the project asked for.
+  const probesNeeded = o.frames - 1;
+
+  /** @type {Buffer|null} */
+  let previous = null;
+  /** @type {Buffer|null} */
+  let taken = null;
+  /** @type {unknown} */
+  let lastError = null;
+  let agreed = 0;
+  let attempts = 0;
+
+  for (;;) {
+    /** @type {Buffer|null} */
+    let shot = null;
+    try {
+      shot = await o.probe();
+      attempts += 1;
+    } catch (e) {
+      lastError = e;
+    }
+
+    // Only a pair of frames that disagreed earns a pause before the next look.
+    let moved = true;
+    if (shot) {
+      moved = previous ? !sameBytes(previous, shot) : false;
+      agreed = moved ? 1 : agreed + 1;
+      previous = shot;
+    }
+
+    if (shot && !moved && agreed >= probesNeeded) {
+      const png = await o.capture();
+      /** @type {Buffer|null} */
+      let after = null;
+      try {
+        after = await o.probe();
+        attempts += 1;
+      } catch (e) {
+        // The window went away right after the shutter. The picture is already in hand and
+        // there is nothing left that could contradict it.
+        lastError = e;
+      }
+      // `shot` is the frame this picture was promised to match; it is also `previous`.
+      if (!after || sameBytes(shot, after)) {
+        return {
+          report: { settled: true, attempts, lastDriftPixels: 0, waitedMs: Date.now() - o.started },
+          png,
+        };
+      }
+      // It moved while the shutter was open — something the old loop could not notice,
+      // because it kept the last photograph it took rather than one it had checked
+      // afterwards. Hold on to it only as a last resort and start counting again.
+      taken = png;
+      previous = after;
+      agreed = 1;
+      moved = true;
+    }
+
+    if (Date.now() - o.started >= o.timeoutMs) break;
+    if (moved && o.intervalMs > 0) await sleep(o.intervalMs);
+  }
+
+  if (!taken) {
+    try {
+      taken = await o.capture();
+    } catch (e) {
+      lastError = e;
+    }
+  }
+  if (!taken) {
+    if (lastError instanceof Error) throw lastError;
+    throw new StaysFixedError('I could not take a picture of this screen at all.', {
+      hint: 'The window may have closed, or the app may have crashed mid-run.',
+    });
+  }
+
+  detail('settle: gave up after', String(attempts), 'tries; the screen was still moving');
+  // Probes answer yes or no, so the drift is reported as "something moved" rather than a
+  // figure nobody measured.
+  return {
+    report: { settled: false, attempts, lastDriftPixels: 1, waitedMs: Date.now() - o.started },
+    png: taken,
+  };
+}
+
+/**
+ * Whether two shots are the very same bytes.
+ * @param {Buffer} a
+ * @param {Buffer} b
+ * @returns {boolean}
+ */
+function sameBytes(a, b) {
+  return a.length === b.length && a.equals(b);
+}
+
 /**
  * How many pixels differ between two photos.
  *
@@ -98,7 +262,7 @@ export async function settle(page, opts) {
  * @returns {number}
  */
 function driftBetween(a, b) {
-  if (a.length === b.length && a.equals(b)) return 0;
+  if (sameBytes(a, b)) return 0;
   try {
     const pa = PNG.sync.read(a);
     const pb = PNG.sync.read(b);
@@ -143,6 +307,17 @@ async function waitUntilQuiet(page, timeoutMs) {
 
   // Anything the freeze layer missed gets a short grace period to end on its own. The
   // count is bounded rather than timed because the page clock is frozen.
+  //
+  // This reads like an easy half-second to save and it is not. On a real app two
+  // animations sit on this list permanently — a spinner, a pulse — so the loop runs all
+  // twenty rounds every screen and looks like pure waiting for nothing. It was cut to stop
+  // as soon as the count stopped falling, and the fixture app that exists to be
+  // impossible to photograph immediately produced two different pictures out of twenty.
+  // What the loop is really buying is time for things that arrive late and announce
+  // themselves to nobody: the fixture sets an image source on a timer, and until that
+  // fires there is no request, no pending resource and nothing on any page API to wait
+  // for. Only elapsed time finds it. So the half-second stays; the savings in this file
+  // come from the photographs, which used to be full-size and are now mostly probes.
   if (typeof document.getAnimations === 'function') {
     for (var i = 0; i < 20; i++) {
       var running = 0;

package/src/guard/run.js

@@ -10,6 +10,7 @@
 
 import { makeGuardApi, ExpectationFailed } from './api.js';
 import { resetWindow } from '../drive/launch.js';
+import { emitEvent } from '../core/events.js';
 
 const DEFAULT_TIMEOUT = 30_000;
 
@@ -30,11 +31,18 @@ const DEFAULT_TIMEOUT = 30_000;
  * @param {import('../types.js').Project} project
  * @param {import('../types.js').LaunchedApp} app
  * @param {import('../types.js').Guard[]} guards
- * @param {{onResult?: (result: GuardRunResult) => void, retries?: number, signal?: AbortSignal}} [opts]
+ * @param {{
+ *   onResult?: (result: GuardRunResult) => void,
+ *   retries?: number,
+ *   signal?: AbortSignal,
+ *   events?: import('../types.js').RunEvents,
+ * }} [opts]
  * @returns {Promise<import('../types.js').GuardResult[]>}
  */
 export async function runGuards(project, app, guards, opts = {}) {
   const retries = Math.max(0, Math.trunc(opts.retries ?? 0));
+  const events = opts.events;
+  const total = guards.length;
 
   // Electron apps have no address to go back to; for the web the configured url
   // is the guard's starting line.
@@ -43,13 +51,25 @@ export async function runGuards(project, app, guards, opts = {}) {
   /** @type {GuardRunResult[]} */
   const results = [];
 
-  for (const guard of guards) {
+  for (let i = 0; i < guards.length; i++) {
+    const guard = guards[i];
     // Between guards only — stopping one halfway would leave the app in a state
     // the next run cannot reason about.
     if (opts.signal?.aborted) break;
 
     const startedAt = Date.now();
 
+    // The story of the bug goes out with the start, not only with a failure: a
+    // person watching a guard run wants to know what it is protecting while it is
+    // still running, not after it has already gone red.
+    emitEvent(events, {
+      type: 'guard:start',
+      name: guard.name,
+      because: guard.because,
+      index: i + 1,
+      total,
+    });
+
     if (guard.skip === true) {
       /** @type {GuardRunResult} */
       const skipped = {
@@ -63,6 +83,7 @@ export async function runGuards(project, app, guards, opts = {}) {
       };
       results.push(skipped);
       opts.onResult?.(skipped);
+      emitGuardDone(events, skipped);
       continue;
     }
 
@@ -100,11 +121,29 @@ export async function runGuards(project, app, guards, opts = {}) {
 
     results.push(result);
     opts.onResult?.(result);
+    emitGuardDone(events, result);
   }
 
   return results;
 }
 
+/**
+ * @param {import('../types.js').RunEvents|undefined} events
+ * @param {GuardRunResult} result
+ * @returns {void}
+ */
+function emitGuardDone(events, result) {
+  emitEvent(events, {
+    type: 'guard:done',
+    name: result.name,
+    status: result.status,
+    durationMs: result.durationMs,
+    message: result.message,
+    failedAt: result.failedAt,
+    because: result.because,
+  });
+}
+
 /**
  * One attempt at one guard, from a clean start.
  *