staysfixed 0.1.0

package/src/freeze/clock.js

@@ -0,0 +1,213 @@
+/**
+ * Freezing time.
+ *
+ * Two layers, because neither is enough on its own:
+ *
+ *  - The protocol overrides (`clockCdp`) change what the browser itself believes about
+ *    time zone and locale, so `Date.prototype.toString`, `getTimezoneOffset` and the
+ *    ICU formatters all agree. Page script cannot reach those.
+ *  - The injected script (`clockScript`) pins the *instant*. The protocol can only do
+ *    that with `Emulation.setVirtualTimePolicy`, which we refuse to use (see below).
+ *
+ * The instant is frozen but not dead: a spinner that waits 300ms still finishes,
+ * because real timers still fire. Only the *reading* of the clock is pinned, and a
+ * screen recipe can step it forward on purpose.
+ */
+
+import { StaysFixedError } from '../core/errors.js';
+
+/**
+ * Page-side source that pins the clock. Meant to run before any app script.
+ *
+ * @param {{iso: string, timezone?: string, locale?: string, seed?: number}} opts
+ * @returns {string} JavaScript to evaluate in the page
+ */
+export function clockScript(opts) {
+  const base = Date.parse(opts.iso);
+  if (Number.isNaN(base)) {
+    throw new StaysFixedError(`I cannot read "${opts.iso}" as a time.`, {
+      hint: "Use an ISO timestamp like '2026-01-01T12:00:00.000Z', or set freeze.clock to false.",
+    });
+  }
+  const timezone = opts.timezone ?? 'UTC';
+  const locale = opts.locale ?? 'en-US';
+
+  return `(function () {
+  if (window.__staysfixed_clock) return;
+
+  var BASE = ${base};
+  var TZ = ${JSON.stringify(timezone)};
+  var LOCALE = ${JSON.stringify(locale)};
+
+  var ticks = 0;        // virtual milliseconds elapsed since BASE
+  var auto = false;     // when on, every animation frame moves time forward one frame
+  var FRAME_MS = 16;
+
+  var RealDate = Date;
+  var realRaf = typeof window.requestAnimationFrame === 'function'
+    ? window.requestAnimationFrame.bind(window)
+    : null;
+
+  // A subclass rather than a Proxy: instanceof, every Date.prototype method and all
+  // date maths keep working untouched, and only the two things that read "now" change.
+  // The one thing this gives up is calling Date() with no 'new', which returns a string.
+  // App code effectively never does that; minifiers never produce it.
+  class FrozenDate extends RealDate {
+    constructor() {
+      var args = Array.prototype.slice.call(arguments);
+      if (args.length === 0) super(BASE + ticks);
+      else super(...args);
+    }
+  }
+  FrozenDate.now = function () { return BASE + ticks; };
+  try { Object.defineProperty(FrozenDate, 'name', { value: 'Date', configurable: true }); } catch (e) {}
+  window.Date = FrozenDate;
+  try { globalThis.Date = FrozenDate; } catch (e) {}
+
+  // performance.now() and Date.now() must tell the same story, or code that mixes them
+  // (almost every animation library does) computes a nonsense elapsed time and loops.
+  if (window.performance) {
+    try {
+      Object.defineProperty(window.performance, 'timeOrigin', {
+        get: function () { return BASE; },
+        configurable: true
+      });
+    } catch (e) {}
+    try { window.performance.now = function () { return ticks; }; } catch (e) {}
+  }
+
+  // A fixed frame timestamp is what stops requestAnimationFrame loops from drifting the
+  // picture: every frame looks like the same moment, so nothing eases, tweens or scrolls.
+  if (realRaf) {
+    window.requestAnimationFrame = function (cb) {
+      return realRaf(function () {
+        if (auto) ticks += FRAME_MS;
+        cb(ticks);
+      });
+    };
+  }
+
+  function withZone(options) {
+    var o = {};
+    if (options) { for (var k in options) o[k] = options[k]; }
+    if (!o.timeZone) o.timeZone = TZ;
+    return o;
+  }
+
+  var Intl_ = window.Intl;
+  if (Intl_ && typeof Intl_.DateTimeFormat === 'function') {
+    var RealDTF = Intl_.DateTimeFormat;
+    // Works with and without 'new': returning an object from a call overrides 'this'.
+    var PatchedDTF = function DateTimeFormat(locales, options) {
+      return new RealDTF(locales === undefined ? LOCALE : locales, withZone(options));
+    };
+    PatchedDTF.prototype = RealDTF.prototype;
+    if (RealDTF.supportedLocalesOf) {
+      PatchedDTF.supportedLocalesOf = function (l, o) { return RealDTF.supportedLocalesOf(l, o); };
+    }
+    try { Intl_.DateTimeFormat = PatchedDTF; } catch (e) {}
+
+    // toLocaleString and friends do NOT go through Intl.DateTimeFormat, so they need
+    // their own patch. We only fill in the locale and the zone; the default set of
+    // components stays exactly as the browser would have chosen it.
+    var names = ['toLocaleString', 'toLocaleDateString', 'toLocaleTimeString'];
+    for (var n = 0; n < names.length; n++) {
+      (function (name) {
+        var real = RealDate.prototype[name];
+        if (typeof real !== 'function') return;
+        RealDate.prototype[name] = function (locales, options) {
+          return real.call(this, locales === undefined ? LOCALE : locales, withZone(options));
+        };
+      })(names[n]);
+    }
+  }
+
+  if (Intl_) {
+    var localeOnly = ['NumberFormat', 'Collator', 'RelativeTimeFormat', 'ListFormat', 'PluralRules', 'DisplayNames', 'Segmenter'];
+    for (var i = 0; i < localeOnly.length; i++) {
+      (function (name) {
+        var Real = Intl_[name];
+        if (typeof Real !== 'function') return;
+        var Patched = function (locales, options) {
+          return new Real(locales === undefined ? LOCALE : locales, options);
+        };
+        Patched.prototype = Real.prototype;
+        if (Real.supportedLocalesOf) {
+          Patched.supportedLocalesOf = function (l, o) { return Real.supportedLocalesOf(l, o); };
+        }
+        try { Intl_[name] = Patched; } catch (e) {}
+      })(localeOnly[i]);
+    }
+  }
+
+  var realNumToLocale = Number.prototype.toLocaleString;
+  if (typeof realNumToLocale === 'function') {
+    Number.prototype.toLocaleString = function (locales, options) {
+      return realNumToLocale.call(this, locales === undefined ? LOCALE : locales, options);
+    };
+  }
+
+  // Apps branch on the browser language to pick a format. Pin it or the picture depends
+  // on whichever machine took it.
+  try {
+    Object.defineProperty(window.navigator, 'language', {
+      get: function () { return LOCALE; }, configurable: true
+    });
+    Object.defineProperty(window.navigator, 'languages', {
+      get: function () { return Object.freeze([LOCALE]); }, configurable: true
+    });
+  } catch (e) {}
+
+  window.__staysfixed_clock = {
+    base: BASE,
+    now: function () { return BASE + ticks; },
+    elapsed: function () { return ticks; },
+    // Step time forward deliberately, e.g. to photograph "5 minutes into the session".
+    advance: function (ms) {
+      var n = Number(ms);
+      ticks += isFinite(n) ? n : 0;
+      return BASE + ticks;
+    },
+    // Let time creep forward one frame at a time. Off by default: fully frozen is the
+    // only setting that gives byte-identical pictures run after run.
+    auto: function (on) { auto = on !== false; return auto; }
+  };
+})();`;
+}
+
+/**
+ * The protocol half. Stronger than script patching because it changes what the renderer
+ * itself believes, before a single byte of the app is parsed.
+ *
+ * @param {import('../types.js').PageHandle} page
+ * @param {{iso?: string, timezone?: string, locale?: string}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function clockCdp(page, opts = {}) {
+  const timezone = opts.timezone ?? 'UTC';
+  const locale = opts.locale ?? 'en-US';
+
+  // Older targets and some Electron builds do not carry every Emulation command.
+  // A missing override is a slightly less frozen page, never a failed run.
+  await tolerate(page, 'Emulation.setTimezoneOverride', { timezoneId: timezone });
+  await tolerate(page, 'Emulation.setLocaleOverride', { locale });
+
+  // Emulation.setVirtualTimePolicy is deliberately NOT used. It hands the clock to the
+  // browser and only advances it when the renderer says it is idle — an app holding a
+  // long-poll or a WebSocket open never goes idle, so virtual time never advances and
+  // the whole run deadlocks with no error. The injected clock has no such failure mode.
+}
+
+/**
+ * @param {import('../types.js').PageHandle} page
+ * @param {string} method
+ * @param {Record<string, unknown>} params
+ * @returns {Promise<void>}
+ */
+async function tolerate(page, method, params) {
+  try {
+    await page.send(method, params);
+  } catch {
+    // Command not supported here. Carry on.
+  }
+}

package/src/freeze/fonts.js

@@ -0,0 +1,243 @@
+/**
+ * Waiting for the page to finish arriving.
+ *
+ * The single most common cause of a picture that "randomly" fails is a font or an image
+ * that had not landed yet. Text reflows when the real face replaces the fallback; a
+ * missing image collapses a card. Neither is a bug in the app and neither is worth
+ * waking a human for, so we wait for both before the shutter.
+ *
+ * Every wait in here races a real setTimeout rather than a clock reading, because the
+ * clock is frozen: Date.now() would never move past the deadline.
+ */
+
+import { detail } from '../core/log.js';
+
+/**
+ * Page-side helper that resolves when the browser says every face is in.
+ * @returns {string} JavaScript to evaluate in the page
+ */
+export function fontsScript() {
+  return `(function () {
+  if (window.__staysfixed_fontsReady) return;
+
+  function faces() {
+    var out = [];
+    try { document.fonts.forEach(function (f) { out.push(f); }); } catch (e) { /* older set */ }
+    return out;
+  }
+
+  // The trap that cost us the first green run, and it is worth spelling out.
+  //
+  // A face declared in @font-face is not fetched until layout actually needs it.
+  // Until then its status is 'unloaded', NOTHING is pending, document.fonts.status
+  // reads 'loaded' and document.fonts.ready resolves immediately — so a naive wait
+  // returns at once, the shutter fires on the fallback font, and a moment later the
+  // real face lands and every line of text shifts by a fraction of a pixel. That is
+  // 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.
+  function forceLoad() {
+    var pending = [];
+    faces().forEach(function (f) {
+      try {
+        if (f.status === 'unloaded') pending.push(f.load().catch(function () {}));
+        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);
+  }
+
+  window.__staysfixed_fontsReady = function (ms) {
+    var limit = typeof ms === 'number' && ms > 0 ? ms : 5000;
+    if (!document.fonts) return Promise.resolve('no-font-api');
+
+    var ready = (async function () {
+      // 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.
+      for (var round = 0; round < 5; round++) {
+        await forceLoad();
+        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); }); });
+      });
+      return document.fonts.status || 'loaded';
+    })();
+
+    var timer = new Promise(function (resolve) {
+      setTimeout(function () { resolve('timeout'); }, limit);
+    });
+
+    return Promise.race([ready, timer]);
+  };
+})();`;
+}
+
+/**
+ * CSS that pins how text is rasterised.
+ * @returns {string} CSS
+ */
+export function fontsCss() {
+  // This trades a little fidelity for pictures that do not change when the OS decides to
+  // smooth text differently. Subpixel antialiasing depends on the display, on whether the
+  // window is on an external monitor, and on GPU driver version; geometricPrecision stops
+  // glyph advances being rounded to whole pixels, which is what makes a line of text
+  // reflow by one pixel between runs; font-synthesis: none stops a fake bold or fake
+  // italic being invented when a weight is missing, which is a per-machine decision.
+  return `* , *::before, *::after {
+  -webkit-font-smoothing: antialiased !important;
+  text-rendering: geometricPrecision !important;
+  font-synthesis: none !important;
+}
+`;
+}
+
+/**
+ * Insert the text-rendering CSS.
+ *
+ * Called once per capture, never cached. It used to be cached against the page in a
+ * WeakSet, and that was a real bug with a very confusing signature: the first picture
+ * of a fresh browser came out with smoothed (thinner) text and every picture after it
+ * came out unsmoothed, because the stylesheet died with the document the screen recipe
+ * navigated away from and the cache refused to put it back. Identical layout, different
+ * pixels, one wrong picture in twenty. Insert it every time.
+ *
+ * @param {import('../types.js').PageHandle} page
+ * @returns {Promise<string|null>} the stylesheet id, or null when the page refused it
+ */
+export async function insertFontCss(page) {
+  try {
+    return await page.insertCss(fontsCss());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wait until every font face has loaded. Tolerates a page with no font API at all.
+ * @param {import('../types.js').PageHandle} page
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function waitForFonts(page, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 5000;
+
+  const source = `(async () => {
+  if (typeof window.__staysfixed_fontsReady === 'function') {
+    return await window.__staysfixed_fontsReady(${timeoutMs});
+  }
+  if (!document.fonts) return 'no-font-api';
+  await Promise.race([
+    Promise.resolve(document.fonts.ready),
+    new Promise(function (r) { setTimeout(r, ${timeoutMs}); })
+  ]);
+  return document.fonts.status || 'unknown';
+})()`;
+
+  try {
+    const status = await page.evaluate(source);
+    if (status === 'timeout') {
+      detail('fonts: gave up waiting after', `${timeoutMs}ms`, '— a face never finished loading');
+    } else {
+      detail('fonts:', String(status));
+    }
+  } catch {
+    // A page that navigated out from under us. The settle loop will catch any wobble.
+  }
+}
+
+/**
+ * Wait until pictures and stylesheets have landed: every <img> complete, every CSS
+ * background image fetched, no stylesheet still on its way.
+ * @param {import('../types.js').PageHandle} page
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<void>}
+ */
+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.
+  const source = `(async () => {
+  var LIMIT = ${timeoutMs};
+  var MAX_ELEMENTS = 4000;
+  var waits = [];
+
+  var imgs = document.images ? Array.prototype.slice.call(document.images) : [];
+  for (var i = 0; i < imgs.length; i++) {
+    (function (img) {
+      if (img.complete) return;
+      waits.push(new Promise(function (r) {
+        img.addEventListener('load', r, { once: true });
+        img.addEventListener('error', r, { once: true });
+      }));
+    })(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"]');
+  for (var l = 0; l < links.length; l++) {
+    (function (link) {
+      var loaded = false;
+      // A cross-origin sheet that HAS loaded exposes a sheet object but throws on its
+      // rules; a sheet that has not loaded exposes nothing. Presence is the right test.
+      try { loaded = Boolean(link.sheet); } catch (err) { loaded = true; }
+      if (loaded || link.disabled) return;
+      waits.push(new Promise(function (r) {
+        link.addEventListener('load', r, { once: true });
+        link.addEventListener('error', r, { once: true });
+      }));
+    })(links[l]);
+  }
+
+  if (waits.length === 0) return 0;
+  await Promise.race([
+    Promise.all(waits),
+    new Promise(function (r) { setTimeout(r, LIMIT); })
+  ]);
+  return waits.length;
+})()`;
+
+  try {
+    const waited = await page.evaluate(source);
+    if (waited) detail('waited on', String(waited), 'image or stylesheet loads');
+  } catch {
+    // Same as above: a navigation mid-wait is not a reason to fail a run.
+  }
+}

package/src/freeze/index.js

@@ -0,0 +1,234 @@
+/**
+ * The freeze layer, assembled.
+ *
+ * This is the part of Stays Fixed that makes it worth using. A picture check that fails
+ * for no reason is worse than no check at all, because people learn to ignore it — and
+ * once they ignore it, the real regression slides through with everything else.
+ *
+ * Order is not a style choice here; each stage depends on the one before it.
+ */
+
+import { clockScript, clockCdp } from './clock.js';
+import { motionCss, motionScript, reduceMotionCdp } from './motion.js';
+import { randomScript } from './random.js';
+import { insertFontCss, fontsScript, waitForFonts, waitForImages } from './fonts.js';
+import { installNetwork } from './network.js';
+import { detail, warn } from '../core/log.js';
+
+/** Used only when a caller asks for a frozen clock without saying which instant. */
+const FALLBACK_INSTANT = '2026-01-01T12:00:00.000Z';
+
+/** @type {import('../types.js').FreezeStats} */
+const NO_NETWORK_STATS = {
+  requestsAllowed: 0,
+  requestsBlocked: 0,
+  requestsReplayed: 0,
+  requestsRecorded: 0,
+  blockedUrls: [],
+};
+
+/**
+ * Make a page behave the same way every time it is opened.
+ *
+ * @param {import('../types.js').PageHandle} page
+ * @param {import('../types.js').FreezeConfig} freeze
+ * @param {{fixturesDir?: string, screenName?: string, record?: boolean, deviceScaleFactor?: number, colorScheme?: 'light'|'dark'}} [ctx]
+ * @returns {Promise<import('../types.js').FreezeHandle>}
+ */
+export async function applyFreeze(page, freeze, ctx = {}) {
+  /** @type {string[]} */
+  const scriptIds = [];
+  /** @type {string[]} */
+  const cssIds = [];
+  /** @type {{release: () => Promise<void>, stats: () => import('../types.js').FreezeStats}|null} */
+  let network = null;
+
+  const wantClock = freeze.clock !== false;
+  const wantMotion = freeze.motion !== false;
+  const wantFonts = freeze.fonts !== false;
+  const wantRandom = freeze.random !== 'off';
+
+  // ---------------------------------------------------------------------------
+  // 1. Protocol overrides first.
+  //
+  // These change what the renderer itself believes, and they take effect before a single
+  // byte of the app is parsed. Nothing injected into the page can reach the time zone the
+  // browser formats dates in, or the media query it answers for reduced motion.
+  // ---------------------------------------------------------------------------
+  if (wantClock) {
+    await clockCdp(page, { timezone: freeze.timezone, locale: freeze.locale });
+  }
+  if (wantMotion) {
+    await reduceMotionCdp(page, ctx.colorScheme ? { colorScheme: ctx.colorScheme } : {});
+  }
+
+  // Network interception belongs in this first stage too, and for the same reason: if it
+  // goes up after the app navigates, the first page load has already pulled in the very
+  // avatars, fonts and beacons we are trying to keep out.
+  try {
+    network = await installNetwork(page, {
+      mode: freeze.network ?? 'block-external',
+      allow: freeze.networkAllow ?? [],
+      fixturesDir: ctx.fixturesDir,
+      screenName: ctx.screenName,
+      record: ctx.record,
+    });
+  } catch (e) {
+    warn('Could not take control of this app\'s network requests, so pictures may change on their own.');
+    detail(e instanceof Error ? e.message : String(e));
+  }
+
+  // ---------------------------------------------------------------------------
+  // 2. Page scripts, registered to run before anything the app loads.
+  //
+  // Order inside this list matters less than the fact that all of it lands before the
+  // app's own first line: a framework that reads Date.now() or Math.random() while it is
+  // booting has already baked the answer into the DOM by the time we could patch it.
+  // ---------------------------------------------------------------------------
+  /** @type {string[]} */
+  const sources = [];
+  if (wantClock) {
+    const iso = typeof freeze.clock === 'string' ? freeze.clock : FALLBACK_INSTANT;
+    sources.push(clockScript({ iso, timezone: freeze.timezone, locale: freeze.locale, seed: freeze.seed }));
+  }
+  if (wantRandom) sources.push(randomScript(freeze.seed ?? 20260101));
+  if (wantMotion) sources.push(motionScript());
+  if (wantFonts) sources.push(fontsScript());
+
+  for (const source of sources) {
+    try {
+      scriptIds.push(await page.addInitScript(source));
+    } catch (e) {
+      detail('freeze: could not register a page script —', e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  // An init script only reaches documents that have not loaded yet, and the caller may
+  // already be sitting on a page. Run the same sources against the document we have.
+  // Every one of them refuses to install itself twice, so this is safe either way.
+  for (const source of sources) {
+    try {
+      await page.evaluate(source);
+    } catch {
+      // No document yet, or it navigated. The init script covers the next one.
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // 3. CSS last, because a stylesheet needs a document to attach to.
+  // ---------------------------------------------------------------------------
+  if (wantMotion) {
+    try {
+      cssIds.push(
+        await page.insertCss(
+          motionCss({ hideScrollbars: freeze.hideScrollbars !== false, hideCaret: freeze.hideCaret !== false })
+        )
+      );
+    } catch (e) {
+      detail('freeze: could not insert the motion stylesheet —', e instanceof Error ? e.message : String(e));
+    }
+  }
+  if (wantFonts) {
+    const id = await insertFontCss(page);
+    if (id) cssIds.push(id);
+  }
+
+  return {
+    async release() {
+      try {
+        for (const id of cssIds) {
+          try {
+            await page.removeCss(id);
+          } catch {
+            // Already gone with the document.
+          }
+        }
+        for (const id of scriptIds) {
+          try {
+            await page.removeInitScript(id);
+          } catch {
+            // Same.
+          }
+        }
+        try {
+          await page.evaluate(
+            "(() => { const mo = window.__staysfixed_motionObserver; if (mo && mo.disconnect) mo.disconnect(); })()"
+          );
+        } catch {
+          // The observer dies with the document anyway.
+        }
+      } finally {
+        // Always, even if everything above threw: a live Fetch interception left behind
+        // stalls the next navigation, and that looks like the app hanging.
+        if (network) await network.release();
+      }
+    },
+    stats() {
+      return network ? network.stats() : { ...NO_NETWORK_STATS, blockedUrls: [] };
+    },
+  };
+}
+
+/**
+ * The last-moment checks, run immediately before the shutter.
+ *
+ * @param {import('../types.js').PageHandle} page
+ * @param {{fonts?: boolean, timeoutMs?: number, keepScroll?: boolean, keepHover?: boolean}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function prepareForShutter(page, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+
+  if (opts.fonts !== false) await waitForFonts(page, { timeoutMs: Math.min(timeoutMs, 5000) });
+  await waitForImages(page, { timeoutMs });
+
+  // Park the mouse before anything else.
+  //
+  // The pointer stays wherever the last click left it, and the thing under it stays
+  // hovered: a highlighted row, a tooltip that fades in a beat later, a button that is
+  // a different colour than it will be tomorrow when the recipe clicks in a slightly
+  // different order. The first real app this tool was pointed at photographed a tooltip
+  // reading "Keep the sidebar open" that nobody meant to be in the picture, and a
+  // sidebar that had refused to collapse *because the mouse was still resting on it*.
+  //
+  // So: move the pointer out to the far corner, then let the page settle. The corner is
+  // (1,1) rather than (0,0) because some apps treat the exact origin as "no pointer" and
+  // never fire the leave.
+  if (opts.keepHover !== true) await page.moveMouseAway();
+
+  // A focus ring is a real source of wobble. Whichever element happened to be focused when
+  // the last step finished draws an outline the approved picture may not have — and which
+  // element that is depends on click timing, so it changes between runs on the same code.
+  const blur = `try {
+    var el = document.activeElement;
+    if (el && el !== document.body && typeof el.blur === 'function') el.blur();
+  } catch (e) {}`;
+
+  // Unless the recipe scrolled somewhere on purpose, start from the top: a page that was
+  // left scrolled by a click-into-view photographs differently every run.
+  const scroll = opts.keepScroll
+    ? ''
+    : `try {
+    window.scrollTo(0, 0);
+    if (document.documentElement) document.documentElement.scrollTop = 0;
+    if (document.body) document.body.scrollTop = 0;
+  } catch (e) {}`;
+
+  const source = `(async () => {
+  ${blur}
+  ${scroll}
+  // Read a layout property to force the browser to flush whatever the blur and the scroll
+  // changed, then wait two frames so it is actually on screen and not merely calculated.
+  try { void document.documentElement.offsetHeight; } catch (e) {}
+  await new Promise(function (r) {
+    requestAnimationFrame(function () { requestAnimationFrame(function () { r(undefined); }); });
+  });
+  return true;
+})()`;
+
+  try {
+    await page.evaluate(source);
+  } catch {
+    // Nothing here is worth failing a run over; the settle loop is the real guarantee.
+  }
+}