staysfixed 0.1.0 → 0.2.0

package/src/picture/capture.js

@@ -13,6 +13,10 @@ 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';
+// 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.
+import { thumbnailOf } from './store.js';
 
 /**
  * Every instruction a declarative step is allowed to give, in the order they run
@@ -47,10 +51,19 @@ 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}} ctx
- * @returns {Promise<import('../types.js').CaptureReport & {masks: import('../types.js').MaskRect[]}>}
- *   The standard report plus the mask rectangles that were painted, so the
- *   comparison can paint the exact same rectangles onto the approved picture.
+ * @param {{fixturesDir: string, record?: boolean, timeoutMs?: number, thumbnail?: boolean}} ctx
+ *   `thumbnail` is asked for only while somebody is watching the run happen; it costs a
+ *   decode of the picture that was just taken, so it is off unless it is wanted.
+ * @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},
+ *   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.
  */
 export async function captureScreen(page, screen, settings, ctx) {
   const deviceScaleFactor = settings.viewport.deviceScaleFactor ?? 2;
@@ -67,6 +80,14 @@ export async function captureScreen(page, screen, settings, ctx) {
     deviceScaleFactor,
   });
 
+  // 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
+  // report that a screen took a negative amount of time.
+  const clock = process.hrtime.bigint;
+  const startedSteps = clock();
+  /** @type {{steps: number, prepare: number, settle: number}} */
+  const spent = { steps: 0, prepare: 0, settle: 0 };
+
   try {
     if (typeof screen.do === 'function') {
       await screen.do(page);
@@ -79,6 +100,9 @@ export async function captureScreen(page, screen, settings, ctx) {
     const scrolledOnPurpose =
       typeof screen.do === 'function' || (screen.steps ?? []).some((s) => s.scrollTo !== undefined);
 
+    const startedPrepare = clock();
+    spent.steps = since(startedSteps, startedPrepare);
+
     await prepareForShutter(page, {
       fonts: settings.freeze.fonts !== false,
       timeoutMs,
@@ -90,13 +114,24 @@ export async function captureScreen(page, screen, settings, ctx) {
     if (screen.fullPage) shotOptions.fullPage = true;
     if (screen.clip) shotOptions.clip = screen.clip;
 
+    // The same frame, asked for cheaply. The settle loop shoots the screen over and over
+    // to find out whether anything moved and throws every one of those pictures away, so
+    // it gets a small lossy one; the picture that is kept and compared is always the PNG.
+    /** @type {import('../types.js').CaptureOptions & {format: 'jpeg', quality: number}} */
+    const probeOptions = { ...shotOptions, format: 'jpeg', quality: 50 };
+
+    const startedSettle = clock();
+    spent.prepare = since(startedPrepare, startedSettle);
+
     const held = await settle(page, {
       frames: settleConfig.frames ?? 2,
       intervalMs: settleConfig.intervalMs ?? 250,
       timeoutMs: settleConfig.timeoutMs ?? 10_000,
       maxDriftPixels: settleConfig.maxDriftPixels ?? 0,
       capture: () => page.shoot(shotOptions),
+      probe: () => page.shoot(probeOptions),
     });
+    spent.settle = since(startedSettle, clock());
 
     const rects = await resolveMasks(page, settings.masks ?? [], { deviceScaleFactor });
     const png = rects.length > 0 ? paintInto(held.png, rects) : held.png;
@@ -115,7 +150,8 @@ export async function captureScreen(page, screen, settings, ctx) {
       await runSteps(page, screen.after);
     }
 
-    return {
+    /** @type {import('../types.js').CaptureReport & {masks: import('../types.js').MaskRect[], timings: typeof spent, spent: typeof spent, thumbnail?: string}} */
+    const report = {
       png,
       width: size.width,
       height: size.height,
@@ -123,7 +159,15 @@ export async function captureScreen(page, screen, settings, ctx) {
       consoleErrors: page.consoleErrors(),
       freeze: frozen.stats(),
       masks: rects,
+      // The same three numbers under both names the rest of the tool asks for them by.
+      timings: spent,
+      spent,
     };
+    if (ctx.thumbnail === true) {
+      const small = await thumbnailOf(png);
+      if (small) report.thumbnail = small;
+    }
+    return report;
   } finally {
     // Releasing must never be the thing that hides a real failure.
     try {
@@ -134,6 +178,16 @@ export async function captureScreen(page, screen, settings, ctx) {
   }
 }
 
+/**
+ * Milliseconds between two readings of the monotonic clock.
+ * @param {bigint} from
+ * @param {bigint} to
+ * @returns {number}
+ */
+function since(from, to) {
+  return Number(to - from) / 1e6;
+}
+
 /**
  * Paint the masks into a screenshot and re-encode it.
  * @param {Buffer} buffer

package/src/picture/compare.js

@@ -13,6 +13,66 @@ import pixelmatch from 'pixelmatch';
 import { paintMasks } from '../freeze/mask.js';
 import { DEFAULT_TOLERANCE } from '../core/config.js';
 import { StaysFixedError } from '../core/errors.js';
+import { pngSize } from './capture.js';
+
+/**
+ * Whether two pictures are the very same file.
+ * @param {Buffer} a
+ * @param {Buffer} b
+ * @returns {boolean}
+ */
+export function sameBytes(a, b) {
+  return Boolean(a) && Boolean(b) && a.length === b.length && a.equals(b);
+}
+
+/**
+ * The same comparison, without the work when there is nothing to compare.
+ *
+ * On a healthy project every screen is unchanged, which means the new picture is the very
+ * same file as the approved one — the encoder is deterministic, so identical pixels
+ * produce identical bytes. Decoding two full retina PNGs to prove that costs a quarter of
+ * a second per screen, every run, to reach a conclusion the file lengths already gave
+ * away.
+ *
+ * This is not a looser check, it is the same answer arrived at honestly. Identical bytes
+ * are identical pixels, so nothing differs, so nothing can exceed any allowance. Masks do
+ * not change that: a mask paints the same rectangle onto both pictures, and painting the
+ * same thing onto two identical pictures leaves them identical. The size comes out of the
+ * PNG header, which is where `comparePng` would have got it too.
+ *
+ * @param {Buffer} approvedBuf
+ * @param {Buffer} actualBuf
+ * @param {import('../types.js').ToleranceConfig} tolerance
+ * @param {import('../types.js').MaskRect[]} [maskRects]
+ * @returns {import('../types.js').CompareReport}
+ */
+export function compareFast(approvedBuf, actualBuf, tolerance, maskRects = []) {
+  if (sameBytes(approvedBuf, actualBuf)) {
+    try {
+      const size = pngSize(actualBuf);
+      const allowed =
+        tolerance.maxPixels ??
+        Math.floor(size.width * size.height * (tolerance.pixels ?? DEFAULT_TOLERANCE.pixels));
+      // A negative allowance is a setting that says even a perfect match is a failure.
+      // Nonsense, but it is the caller's nonsense, and the long way round is the only one
+      // that can answer it the same way it always has.
+      if (allowed >= 0) {
+        return {
+          equal: true,
+          diffPixels: 0,
+          diffRatio: 0,
+          diffPng: null,
+          sizeMismatch: false,
+          size,
+          approvedSize: { width: size.width, height: size.height },
+        };
+      }
+    } catch {
+      // Not a readable PNG header. Let the full path throw the sentence it always throws.
+    }
+  }
+  return comparePng(approvedBuf, actualBuf, tolerance, maskRects);
+}
 
 /**
  * @param {Buffer} approvedBuf

package/src/picture/run.js

@@ -12,8 +12,8 @@
  */
 
 import { captureScreen } from './capture.js';
-import { comparePng, describeDifference } from './compare.js';
-import { readApproved, writeResult, writeDiff, approveFromResult } from './store.js';
+import { compareFast, describeDifference } from './compare.js';
+import { readApproved, writeResult, writeDiff, approveFromResult, thumbnailOf } from './store.js';
 import { settingsForScreen } from '../core/config.js';
 import { approvedPicture, resultPicture } from '../core/paths.js';
 import { platformTag } from '../drive/find.js';
@@ -21,6 +21,7 @@ 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 } from '../core/events.js';
 
 /**
  * A picture result plus the one extra fact the flake register needs: whether it
@@ -28,6 +29,19 @@ import { detail } from '../core/log.js';
  * @typedef {import('../types.js').PictureResult & {retriedToPass?: boolean}} PictureRunResult
  */
 
+/**
+ * The small pictures a watcher is shown, filled in as a screen is worked on.
+ *
+ * They are kept apart from the result on purpose. A result is written to disk and
+ * read back by `approve` and `status`, and a base64 picture in there would bloat
+ * every saved run for the sake of a panel that was only open for a minute.
+ *
+ * @typedef {object} Thumbs
+ * @property {string} [shot]        The picture just taken.
+ * @property {string} [approved]    The approved picture, when this screen changed.
+ * @property {string} [diff]        What moved, when this screen changed.
+ */
+
 /**
  * @param {import('../types.js').Project} project
  * @param {import('../types.js').LaunchedApp} app
@@ -39,6 +53,9 @@ import { detail } from '../core/log.js';
  *   retries?: number,
  *   tool?: string,
  *   signal?: AbortSignal,
+ *   events?: import('../types.js').RunEvents,
+ *   timings?: ReturnType<typeof import('../core/events.js').makeTimings>,
+ *   thumbnail?: boolean,
  * }} [opts]
  * @returns {Promise<PictureRunResult[]>}
  */
@@ -53,48 +70,118 @@ export async function runPictures(project, app, opts = {}) {
   // A desktop app has no url to go back to between screens, so it gets a reload instead.
   // A web app does not need one: every screen starts with a `goto`.
   const reset = config.app.kind === 'electron' ? () => resetWindow(app) : undefined;
+  const events = opts.events;
+
+  // Which screens are being photographed is settled before the first shutter, so
+  // anyone watching can be told how many there are and where each one sits in the
+  // queue rather than watching a list of unknown length crawl past.
+  const chosen = config.screens.filter((screen) => !only || only.has(screen.name));
+  const total = chosen.length;
 
   /** @type {PictureRunResult[]} */
   const results = [];
 
-  for (const screen of config.screens) {
+  for (let i = 0; i < chosen.length; i++) {
     if (opts.signal?.aborted) break;
-    if (only && !only.has(screen.name)) continue;
+    const screen = chosen[i];
+
+    emitEvent(events, {
+      type: 'screen:start',
+      name: screen.name,
+      describe: screen.describe,
+      index: i + 1,
+      total,
+    });
 
     if (screen.skip) {
-      results.push(
-        finish(opts, {
-          name: screen.name,
-          describe: screen.describe,
-          status: 'skipped',
-          message: `${screen.name} is switched off in the config.`,
-          durationMs: 0,
-        }),
-      );
+      const skipped = finish(opts, {
+        name: screen.name,
+        describe: screen.describe,
+        status: 'skipped',
+        message: `${screen.name} is switched off in the config.`,
+        durationMs: 0,
+      });
+      results.push(skipped);
+      emitDone(events, skipped, {});
       continue;
     }
 
-    results.push(
-      await runOneScreen(project, page, screen, {
-        record: opts.record,
-        updateNew: opts.updateNew,
-        tool: opts.tool,
-        onResult: opts.onResult,
-        retries,
-        here,
-        reset,
-      }),
-    );
+    // Filled in as the screen is worked on, and read once it is finished. The
+    // thumbnails exist only while somebody is watching, so they travel beside the
+    // result instead of inside it.
+    /** @type {Thumbs} */
+    const thumbs = {};
+
+    const result = await runOneScreen(project, page, screen, {
+      record: opts.record,
+      updateNew: opts.updateNew,
+      tool: opts.tool,
+      onResult: opts.onResult,
+      retries,
+      here,
+      reset,
+      events,
+      timings: opts.timings,
+      thumbnail: opts.thumbnail === true,
+      thumbs,
+    });
+    results.push(result);
+    emitDone(events, result, thumbs);
   }
 
   return results;
 }
 
+/**
+ * Tell anyone watching how a screen turned out, with the pictures if there are any.
+ *
+ * @param {import('../types.js').RunEvents|undefined} events
+ * @param {PictureRunResult} result
+ * @param {Thumbs} thumbs
+ * @returns {void}
+ */
+function emitDone(events, result, thumbs) {
+  emitEvent(events, {
+    type: 'screen:done',
+    name: result.name,
+    describe: result.describe,
+    status: result.status,
+    durationMs: result.durationMs,
+    diffPixels: result.diffPixels,
+    diffRatio: result.diffRatio,
+    message: result.message,
+    thumbnail: thumbs.shot,
+    approvedThumb: thumbs.approved,
+    diffThumb: thumbs.diff,
+  });
+}
+
+/**
+ * Everything one screen needs, including where to leave what it learns.
+ *
+ * `thumbs` is written into rather than returned because a screen can finish down
+ * half a dozen different paths, and threading a second return value through all
+ * of them would bury the thing this function is actually for.
+ *
+ * @typedef {object} ScreenCtx
+ * @property {boolean} [record]
+ * @property {boolean} [updateNew]
+ * @property {string} [tool]
+ * @property {(r: PictureRunResult) => void} [onResult]
+ * @property {number} retries
+ * @property {string} here
+ * @property {() => Promise<void>} [reset]
+ * @property {import('../types.js').RunEvents} [events]
+ * @property {ReturnType<typeof import('../core/events.js').makeTimings>} [timings]
+ * @property {boolean} [thumbnail]        Make the small pictures a watcher needs.
+ * @property {Thumbs} [thumbs]            Where those small pictures are left.
+ */
+
 /**
  * @param {import('../types.js').Project} project
  * @param {import('../types.js').PageHandle} page
  * @param {import('../types.js').ScreenConfig} screen
- * @param {{record?: boolean, updateNew?: boolean, tool?: string, onResult?: (r: PictureRunResult) => void, retries: number, here: string, reset?: () => Promise<void>}} ctx
+ * @param {ScreenCtx} ctx
  * @returns {Promise<PictureRunResult>}
  */
 async function runOneScreen(project, page, screen, ctx) {
@@ -132,10 +219,20 @@ async function runOneScreen(project, page, screen, ctx) {
         fixturesDir: paths.fixtures,
         record: ctx.record ?? false,
         timeoutMs: settings.freeze.settle?.timeoutMs,
+        thumbnail: ctx.thumbnail === true,
       });
+      accountForCapture(ctx.timings, shot);
       consoleErrors = shot.consoleErrors;
       size = { width: shot.width, height: shot.height };
 
+      // Said out loud the moment the shutter fires, before anything is compared,
+      // so a person watching sees the picture appear while the run is still
+      // deciding what it thinks of it.
+      if (shot.thumbnail) {
+        if (ctx.thumbs) ctx.thumbs.shot = shot.thumbnail;
+        emitEvent(ctx.events, { type: 'screen:shot', name: screen.name, thumbnail: shot.thumbnail });
+      }
+
       await writeResult(paths, screen.name, shot.png, {
         deviceScaleFactor: settings.viewport.deviceScaleFactor,
         describe: screen.describe,
@@ -143,7 +240,13 @@ async function runOneScreen(project, page, screen, ctx) {
 
       if (!approved) break;
 
-      compare = comparePng(approved.png, shot.png, settings.tolerance, shot.masks);
+      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
+      // screens on most runs, so this is the case that actually happens — it took the
+      // 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?.();
       if (compare.equal) break;
       if (attempt <= ctx.retries) {
         detail(`${screen.name} looked different on attempt ${attempt} — taking it again.`);
@@ -239,6 +342,14 @@ async function runOneScreen(project, page, screen, ctx) {
   let diffPath;
   if (compare.diffPng) diffPath = await writeDiff(paths, screen.name, compare.diffPng);
 
+  // Only for a screen that actually moved, and only when somebody is watching:
+  // this is the one moment a person wants the approved picture and the difference
+  // side by side with the new one.
+  if (ctx.thumbnail === true && ctx.thumbs) {
+    ctx.thumbs.approved = (await thumbnailOf(approved.png)) ?? undefined;
+    if (compare.diffPng) ctx.thumbs.diff = (await thumbnailOf(compare.diffPng)) ?? undefined;
+  }
+
   const what = describeDifference(compare, screen.name);
   const next = compare.sizeMismatch
     ? 'There is no difference picture for a size change — open the new picture and look at it.'
@@ -252,6 +363,32 @@ async function runOneScreen(project, page, screen, ctx) {
   });
 }
 
+/**
+ * Put the time one picture took into the buckets it belongs in. The walk uses
+ * this too, so a walkthrough and a check file their time the same way.
+ *
+ * Only capture knows how its own milliseconds went, so it says, and this puts
+ * what it said where the profile can find it. If it ever stops saying, the one
+ * number still worth claiming is how long the screen was held still before the
+ * shutter; the rest goes unclaimed into `other` rather than being guessed at,
+ * because a made-up profile is worse than a missing one.
+ *
+ * @param {ReturnType<typeof import('../core/events.js').makeTimings>|undefined} timings
+ * @param {Awaited<ReturnType<typeof captureScreen>>} shot
+ * @returns {void}
+ */
+export function accountForCapture(timings, shot) {
+  if (!timings) return;
+  const reported = shot.timings;
+  if (reported) {
+    timings.add('steps', reported.steps);
+    timings.add('prepare', reported.prepare);
+    timings.add('settle', reported.settle);
+    return;
+  }
+  if (shot.settle) timings.add('settle', shot.settle.waitedMs);
+}
+
 /**
  * Font rendering differs between operating systems, so a picture approved on one
  * and checked on another is the single most common false alarm. Say it; never

package/src/picture/store.js

@@ -9,12 +9,20 @@
 
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+import { PNG } from 'pngjs';
 import { approvedPicture, resultPicture, safeName } from '../core/paths.js';
 import { sha256 } from '../core/hash.js';
 import { StaysFixedError } from '../core/errors.js';
 import { platformTag } from '../drive/find.js';
 import { pngSize } from './capture.js';
 
+/**
+ * How wide a thumbnail is, in real pixels. Wide enough to stay sharp in a panel a few
+ * hundred pixels across on a retina screen, small enough that a run can put dozens of
+ * them down a wire without anybody noticing.
+ */
+const THUMBNAIL_WIDTH = 320;
+
 /**
  * A small note written beside a result picture so `approve` knows things the PNG
  * cannot tell it — the screen density it was taken at, and its description.
@@ -23,6 +31,63 @@ import { pngSize } from './capture.js';
  * @property {string} [describe]
  */
 
+/**
+ * A small copy of a picture, ready to drop straight into a page.
+ *
+ * This is for watching a run happen, so it is built from the finished picture rather than
+ * asked of the app again: what a watcher sees is exactly what was compared, blackout
+ * boxes and all, and never a second photograph taken a moment later that shows something
+ * slightly different.
+ *
+ * Points are sampled rather than averaged. Averaging every pixel of a retina screenshot
+ * costs a fifth of a second per screen and buys smoother edges on a picture two inches
+ * wide; the point of the panel is to watch a run at full speed.
+ *
+ * @param {Buffer} png
+ * @returns {Promise<string|null>} a data: address for an <img>, or null if it cannot be read
+ */
+export async function thumbnailOf(png) {
+  try {
+    const full = PNG.sync.read(png);
+    if (!(full.width > 0) || !(full.height > 0)) return null;
+    const step = full.width > THUMBNAIL_WIDTH ? full.width / THUMBNAIL_WIDTH : 1;
+    const width = Math.max(1, Math.round(full.width / step));
+    const height = Math.max(1, Math.round(full.height / step));
+
+    const small = new PNG({ width, height });
+    for (let y = 0; y < height; y += 1) {
+      const sourceRow = Math.min(full.height - 1, Math.floor(y * step)) * full.width;
+      for (let x = 0; x < width; x += 1) {
+        const from = (sourceRow + Math.min(full.width - 1, Math.floor(x * step))) * 4;
+        const to = (y * width + x) * 4;
+        small.data[to] = full.data[from];
+        small.data[to + 1] = full.data[from + 1];
+        small.data[to + 2] = full.data[from + 2];
+        small.data[to + 3] = full.data[from + 3];
+      }
+    }
+    return `data:image/png;base64,${PNG.sync.write(small).toString('base64')}`;
+  } catch {
+    // A picture nobody can decode is not worth failing a run over — the run itself has
+    // already said what it thinks of the screen, and a watcher simply sees no picture.
+    return null;
+  }
+}
+
+/**
+ * The fingerprint of a picture.
+ *
+ * The same sha256 that is written into an approved picture's note, so anyone holding that
+ * note can tell whether a fresh photograph is the same file without reading the old one
+ * off disk or decoding either of them.
+ *
+ * @param {Buffer|Uint8Array|string} buffer
+ * @returns {string} hex sha256
+ */
+export function fingerprint(buffer) {
+  return sha256(buffer);
+}
+
 /**
  * @param {import('../types.js').ProjectPaths} paths
  * @param {string} name

package/src/report/console.js

@@ -268,9 +268,12 @@ export function printGuardResult(r) {
  * The closing block of `staysfixed check`.
  * @param {import('../types.js').RunSummary} run
  * @param {import('../types.js').Project} [project]
+ * @param {{profile?: boolean, timings?: import('../types.js').Timings|null}} [opts]
+ *        Ask for the timing block with --profile; pass `timings` when the caller
+ *        kept its own record rather than reading it back off the summary.
  * @returns {void}
  */
-export function printRunSummary(run, project) {
+export function printRunSummary(run, project, opts = {}) {
   const pictures = run.pictures ?? [];
   const guards = run.guards ?? [];
   const verdict = verdictFor(run);
@@ -284,6 +287,13 @@ export function printRunSummary(run, project) {
   if (guards.length) counted.push(`${countText(guards.length)} ${plural(guards.length, 'guard', 'guards')}`);
   if (counted.length) say(paint.grey(`  ${counted.join(', ')}, ${plainTime(run.durationMs ?? 0)}.`));
 
+  // Nobody asked for numbers unless they asked for numbers. The run reads the
+  // same with or without this block.
+  if (opts.profile) {
+    const measured = opts.timings ?? /** @type {{timings?: import('../types.js').Timings}} */ (run).timings;
+    printTimings(measured, pictures.length);
+  }
+
   /** @type {string[][]} */
   const rows = [];
   for (const p of pictures) {
@@ -324,6 +334,75 @@ export function printRunSummary(run, project) {
   blank();
 }
 
+/**
+ * Where the seconds went, in the order of biggest first, because the only reason
+ * anyone reads this is to find the one part worth speeding up.
+ *
+ * The names are what each phase actually does, not what the code calls it: nobody
+ * outside this repository knows what "settle" or "prepare" mean.
+ */
+const TIMING_LABELS = /** @type {[string, string][]} */ ([
+  ['launch', 'opening the app'],
+  ['steps', 'running the steps'],
+  ['prepare', 'waiting for fonts and images'],
+  ['settle', 'taking the pictures until two agree'],
+  ['compare', 'comparing against the approved pictures'],
+  ['guards', 'running the guards'],
+  ['other', 'everything else'],
+]);
+
+/**
+ * The `--profile` block. Rounded to something a person would say out loud: this
+ * is here to point at the slow part, not to be a benchmark.
+ *
+ * @param {import('../types.js').Timings|null|undefined} timings
+ * @param {number} [screenCount]   Screens photographed, for the per-screen average.
+ * @returns {void}
+ */
+export function printTimings(timings, screenCount = 0) {
+  if (!timings) {
+    heading('Where the time went');
+    say(paint.grey('  This run did not record its timings.'));
+    return;
+  }
+
+  // Timings is a fixed shape, but reading it by name keeps the table and the
+  // type from drifting apart.
+  const t = /** @type {Record<string, number>} */ (/** @type {unknown} */ (timings));
+  const total = Number(t.total) || 0;
+
+  /** @type {string[][]} */
+  const rows = [];
+  const parts = TIMING_LABELS.map(([key, label]) => ({ label, ms: Number(t[key]) || 0 }))
+    .filter((part) => part.ms > 0)
+    .sort((a, b) => b.ms - a.ms);
+
+  for (const part of parts) {
+    const share = total > 0 ? `${Math.round((part.ms / total) * 100)}%` : '';
+    rows.push([part.label, duration(part.ms), paint.grey(share)]);
+  }
+
+  heading('Where the time went');
+  if (rows.length === 0) {
+    say(paint.grey('  Nothing took long enough to measure.'));
+    return;
+  }
+  table(rows, { indent: 2 });
+
+  // The two closing lines are written by hand rather than added as rows, so the
+  // totals sit under the parts instead of being sorted in among them.
+  const labelWidth = Math.max(...rows.map((row) => row[0].length));
+  say(paint.grey(`  ${'in total'.padEnd(labelWidth)}  ${duration(total)}`));
+  if (screenCount > 0) {
+    const each = duration(total / screenCount);
+    say(
+      paint.grey(
+        `  ${'each screen'.padEnd(labelWidth)}  ${each} on average, across ${countText(screenCount)} ${plural(screenCount, 'screen', 'screens')}`,
+      ),
+    );
+  }
+}
+
 /**
  * The closing block of `staysfixed walk`.
  * @param {import('../types.js').WalkReport} report