staysfixed 0.1.1 → 0.2.1

package/src/picture/store.js

@@ -9,12 +9,25 @@
 
 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 preview is, in real pixels.
+ *
+ * The watch panel is 460 CSS pixels across, and every screen a person reviews on is
+ * retina, so the panel is really 920 pixels wide. A 320-pixel preview stretched over
+ * that is the blur everybody complained about: you cannot read a label in it, and
+ * zooming in only makes the blur bigger. 900 is where a preview stops being a
+ * stand-in and starts being a picture — and it still weighs about 40KB, which a run
+ * can hand to a window a dozen times over without anybody noticing.
+ */
+const PREVIEW_WIDTH = 900;
+
 /**
  * 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 +36,117 @@ import { pngSize } from './capture.js';
  * @property {string} [describe]
  */
 
+/**
+ * A picture already decoded into pixels: what `PNG.sync.read` hands back, and what the
+ * mask painter works on. Described by its shape rather than by pngjs's class, because
+ * pngjs does not hand back one of those.
+ * @typedef {{width: number, height: number, data: Uint8Array}} Pixels
+ */
+
+/**
+ * A small copy of a picture, ready to drop straight into a page.
+ *
+ * This is the INSTANT preview, and only that. The watch panel loads the real PNG off
+ * disk the moment it exists, so this only has to hold the frame for the fraction of a
+ * second before that file arrives — but it has to hold it honestly, at a size a person
+ * can actually read.
+ *
+ * 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 averaged now, not sampled. Dropping nine pixels out of every ten is what
+ * made the old previews look broken rather than merely small — a one-pixel border or a
+ * line of text either survived or vanished depending on where it happened to land.
+ * Averaging every pixel that falls inside an output pixel costs about forty
+ * milliseconds on a retina screenshot, and it is the difference between a picture and a
+ * smear.
+ *
+ * @param {Buffer|Pixels} source
+ *   The bytes of a PNG, or a picture already decoded. Hand over the decoded one when
+ *   you have it — a retina screenshot costs about eighty milliseconds to decode, and
+ *   decoding the same megapixels twice for one screen is the whole cost of this
+ *   function paid for nothing.
+ * @returns {Promise<string|null>} a data: address for an <img>, or null if it cannot be read
+ */
+export async function thumbnailOf(source) {
+  try {
+    if (Buffer.isBuffer(source) && pngSize(source).width <= PREVIEW_WIDTH) {
+      // Already small enough to be its own preview. Saves decoding and re-encoding a
+      // picture only to hand back what we were given.
+      return `data:image/png;base64,${source.toString('base64')}`;
+    }
+  } catch {
+    // Not a PNG we can measure from its header. Fall through and let the decode below
+    // be the one that decides whether there is a picture here at all.
+  }
+
+  try {
+    // Told apart by what it IS, not by `instanceof PNG`: pngjs's sync reader hands back
+    // a plain object rather than an instance of its own class, so an instance check
+    // here quietly says "no" to every decoded picture ever passed in.
+    const full = Buffer.isBuffer(source) ? PNG.sync.read(source) : source;
+    if (!(full.width > 0) || !(full.height > 0)) return null;
+    const scale = full.width > PREVIEW_WIDTH ? full.width / PREVIEW_WIDTH : 1;
+    const width = Math.max(1, Math.round(full.width / scale));
+    const height = Math.max(1, Math.round(full.height / scale));
+
+    const small = new PNG({ width, height });
+    const from = full.data;
+    const into = small.data;
+
+    for (let y = 0; y < height; y += 1) {
+      const top = Math.floor(y * scale);
+      // Always at least one row, even when the picture is barely bigger than the preview.
+      const bottom = Math.min(full.height, Math.max(top + 1, Math.floor((y + 1) * scale)));
+      for (let x = 0; x < width; x += 1) {
+        const left = Math.floor(x * scale);
+        const right = Math.min(full.width, Math.max(left + 1, Math.floor((x + 1) * scale)));
+        let r = 0;
+        let g = 0;
+        let b = 0;
+        let a = 0;
+        let n = 0;
+        for (let sy = top; sy < bottom; sy += 1) {
+          let i = (sy * full.width + left) * 4;
+          for (let sx = left; sx < right; sx += 1) {
+            r += from[i];
+            g += from[i + 1];
+            b += from[i + 2];
+            a += from[i + 3];
+            n += 1;
+            i += 4;
+          }
+        }
+        const at = (y * width + x) * 4;
+        into[at] = (r / n + 0.5) | 0;
+        into[at + 1] = (g / n + 0.5) | 0;
+        into[at + 2] = (b / n + 0.5) | 0;
+        into[at + 3] = (a / n + 0.5) | 0;
+      }
+    }
+    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

package/src/run.js

@@ -16,13 +16,14 @@ import { ensureDirs, clearResults, resultPicture, safeName } from './core/paths.
 import { gitInfo } from './core/git.js';
 import { loadHistory, saveHistory, foldRun, condemned } from './core/history.js';
 import { warn, detail, shortPath } from './core/log.js';
+import { makeTimings, emitEvent } from './core/events.js';
 import { launchApp } from './drive/launch.js';
 import { platformTag } from './drive/find.js';
 import { runPictures } from './picture/run.js';
 import { approveFromResult, listApproved } from './picture/store.js';
 import { loadGuards } from './guard/load.js';
 import { runGuards } from './guard/run.js';
-import { walkApp, writeWalkContactSheet } from './walk/run.js';
+import { walkApp, writeWalkContactSheet, countWalkSteps } from './walk/run.js';
 import { listMarkers } from './marker/mark.js';
 import { writeRunReport } from './report/html.js';
 import { printPictureResult, printGuardResult } from './report/console.js';
@@ -83,6 +84,10 @@ const LAST_RUN = 'last-run.json';
  *   onPicture?: (result: import('./types.js').PictureResult) => void,
  *   onGuard?: (result: import('./types.js').GuardResult) => void,
  *   writeReport?: boolean,
+ *   events?: import('./types.js').RunEvents,
+ *   watching?: boolean,
+ *   onApp?: (app: import('./types.js').LaunchedApp) => Promise<void>,
+ *   timings?: ReturnType<typeof makeTimings>,
  * }} [opts]
  * @returns {Promise<import('./types.js').RunSummary>}
  */
@@ -90,6 +95,12 @@ export async function runCheck(project, opts = {}) {
   const { config, paths } = project;
   const startedAt = new Date();
   const started = Date.now();
+  const events = opts.events;
+  const watching = opts.watching === true;
+  // A run always knows where its time went, whether or not anybody asked. It
+  // costs two numbers per phase, and the alternative is being unable to answer
+  // "why did that take three minutes" without running it all again.
+  const timings = opts.timings ?? makeTimings();
 
   await ensureDirs(paths);
   // Yesterday's evidence goes in the bin before today's is taken. A stale diff
@@ -117,6 +128,17 @@ export async function runCheck(project, opts = {}) {
     });
   }
 
+  emitEvent(events, {
+    type: 'run:start',
+    plan: {
+      screens: screens.length,
+      guards: guards.length,
+      app: describeApp(config.app),
+      project: path.basename(paths.root),
+      watching,
+    },
+  });
+
   const onPicture = opts.onPicture ?? (opts.quiet ? undefined : (/** @type {import('./types.js').PictureResult} */ r) => printPictureResult(r));
   const onGuard = opts.onGuard ?? (opts.quiet ? undefined : (/** @type {import('./types.js').GuardResult} */ r) => printGuardResult(r));
 
@@ -128,24 +150,41 @@ export async function runCheck(project, opts = {}) {
   // Nothing to look at means nothing to open. Starting a browser to check zero
   // screens is thirty seconds of somebody's life for no answer.
   if (screens.length > 0 || guards.length > 0) {
-    await withApp(project, async (app) => {
-      if (screens.length > 0) {
-        pictures = await runPictures(project, app, {
-          only: screens.map((s) => s.name),
-          record: opts.record ?? false,
-          retries: config.retries,
-          tool: TOOL,
-          onResult: onPicture,
-          signal: opts.signal,
-        });
-      }
-      if (guards.length > 0) {
-        guardResults = await runGuards(project, app, guards, {
-          onResult: onGuard,
-          signal: opts.signal,
-        });
-      }
-    });
+    await withApp(
+      project,
+      async (app) => {
+        if (screens.length > 0) {
+          emitEvent(events, { type: 'phase', message: 'photographing' });
+          pictures = await runPictures(project, app, {
+            only: screens.map((s) => s.name),
+            record: opts.record ?? false,
+            retries: config.retries,
+            tool: TOOL,
+            onResult: onPicture,
+            signal: opts.signal,
+            events,
+            timings,
+            // Small pictures cost time to make, so they are only made when there
+            // is a window open to show them in.
+            thumbnail: Boolean(events && watching),
+          });
+        }
+        if (guards.length > 0) {
+          emitEvent(events, { type: 'phase', message: 'running the guards' });
+          const stopGuards = timings.mark('guards');
+          try {
+            guardResults = await runGuards(project, app, guards, {
+              onResult: onGuard,
+              signal: opts.signal,
+              events,
+            });
+          } finally {
+            stopGuards();
+          }
+        }
+      },
+      { events, timings, onApp: opts.onApp },
+    );
   }
 
   const git = await gitInfo(paths.root);
@@ -171,7 +210,7 @@ export async function runCheck(project, opts = {}) {
 
   const totals = countUp(pictures, guardResults);
 
-  /** @type {import('./types.js').RunSummary} */
+  /** @type {import('./types.js').RunSummary & {timings?: import('./types.js').Timings}} */
   const summary = {
     id: runId(startedAt),
     startedAt: startedAt.toISOString(),
@@ -187,6 +226,9 @@ export async function runCheck(project, opts = {}) {
     tool: TOOL,
     platform: platformTag(),
     condemned: condemnedNames,
+    // Read here rather than at the very end: what follows is writing files, and
+    // where the run spent its time is a fact about the run, not about the report.
+    timings: timings.get(),
   };
 
   if (opts.writeReport !== false) {
@@ -204,6 +246,10 @@ export async function runCheck(project, opts = {}) {
     warn(`The run finished, but its result could not be saved for \`staysfixed status\`. ${messageOf(e)}`);
   }
 
+  // Last, so anything watching that closes on the verdict does not race the
+  // report being written.
+  emitEvent(events, { type: 'run:done', summary });
+
   return summary;
 }
 
@@ -222,7 +268,15 @@ export async function runCheck(project, opts = {}) {
  *
  * @param {import('./types.js').Project} project
  * @param {string} screenName
- * @param {{record?: boolean, retries?: number, signal?: AbortSignal, onResult?: (r: import('./types.js').PictureResult) => void}} [opts]
+ * @param {{
+ *   record?: boolean,
+ *   retries?: number,
+ *   signal?: AbortSignal,
+ *   onResult?: (r: import('./types.js').PictureResult) => void,
+ *   events?: import('./types.js').RunEvents,
+ *   watching?: boolean,
+ *   timings?: ReturnType<typeof makeTimings>,
+ * }} [opts]
  * @returns {Promise<{png: Buffer, result: import('./types.js').PictureResult, path: string}>}
  */
 export async function captureOne(project, screenName, opts = {}) {
@@ -240,17 +294,47 @@ export async function captureOne(project, screenName, opts = {}) {
 
   await ensureDirs(paths);
 
-  const results = await withApp(project, (app) =>
-    runPictures(project, app, {
-      only: [screen.name],
-      record: opts.record ?? false,
-      retries: opts.retries ?? config.retries,
-      tool: TOOL,
-      onResult: opts.onResult,
-      signal: opts.signal,
-    }),
+  const events = opts.events;
+  const watching = opts.watching === true;
+  const timings = opts.timings ?? makeTimings();
+
+  // One screen is still a run as far as anyone watching is concerned, so it
+  // describes itself the same way. This is what lets an agent's own capture be
+  // watched in the same window as a full check.
+  emitEvent(events, {
+    type: 'run:start',
+    plan: {
+      screens: 1,
+      guards: 0,
+      app: describeApp(config.app),
+      project: path.basename(paths.root),
+      watching,
+    },
+  });
+
+  const results = await withApp(
+    project,
+    (app) => {
+      emitEvent(events, { type: 'phase', message: 'photographing' });
+      return runPictures(project, app, {
+        only: [screen.name],
+        record: opts.record ?? false,
+        retries: opts.retries ?? config.retries,
+        tool: TOOL,
+        onResult: opts.onResult,
+        signal: opts.signal,
+        events,
+        timings,
+        thumbnail: Boolean(events && watching),
+      });
+    },
+    { events, timings },
   );
 
+  // Said as soon as the app is shut. What is left is reading a file off disk,
+  // and a watcher should not be left with a spinner turning through it.
+  emitEvent(events, { type: 'run:done' });
+
   const result = results[0];
   if (!result) {
     throw new StaysFixedError(`"${screen.name}" was not photographed.`, {
@@ -281,21 +365,58 @@ export async function captureOne(project, screenName, opts = {}) {
  *   signal?: AbortSignal,
  *   onStep?: (update: import('./walk/run.js').WalkProgress) => void,
  *   writeReport?: boolean,
+ *   events?: import('./types.js').RunEvents,
+ *   watching?: boolean,
+ *   onApp?: (app: import('./types.js').LaunchedApp) => Promise<void>,
+ *   timings?: ReturnType<typeof makeTimings>,
  * }} [opts]
  * @returns {Promise<import('./types.js').WalkReport>}
  */
 export async function runWalk(project, opts = {}) {
   await ensureDirs(project.paths);
 
-  const report = await withApp(project, (app) =>
-    walkApp(project, app, {
-      only: opts.only,
-      record: opts.record ?? false,
-      onStep: opts.onStep,
-      signal: opts.signal,
-    }),
+  const events = opts.events;
+  const watching = opts.watching === true;
+  // The caller's stopwatch when it brought one — `--profile` reads it back out
+  // afterwards, so a walk that quietly kept its own would print all zeros.
+  const timings = opts.timings ?? makeTimings();
+
+  emitEvent(events, {
+    type: 'run:start',
+    plan: {
+      // Counted before anything is opened so the window can draw the whole list
+      // straight away. A walk with nothing to walk through says nothing here and
+      // fails a moment later, in one place, with a sentence a person can act on.
+      screens: countWalk(project.config, opts.only),
+      guards: 0,
+      app: describeApp(project.config.app),
+      project: path.basename(project.paths.root),
+      watching,
+    },
+  });
+
+  const report = await withApp(
+    project,
+    (app) => {
+      emitEvent(events, { type: 'phase', message: 'photographing' });
+      return walkApp(project, app, {
+        only: opts.only,
+        record: opts.record ?? false,
+        onStep: opts.onStep,
+        signal: opts.signal,
+        events,
+        thumbnail: Boolean(events && watching),
+        timings,
+      });
+    },
+    { events, timings, onApp: opts.onApp },
   );
 
+  // A walk has no verdict to hand over — the pictures are the point — so this
+  // says only that it is over. Said here, with the app shut and every photo
+  // taken; the page that shows them is written after.
+  emitEvent(events, { type: 'run:done' });
+
   if (opts.writeReport === false) return report;
 
   try {
@@ -441,16 +562,43 @@ export async function approveScreens(project, names, opts = {}) {
  * Electron window left running is a leaked process on somebody's machine, and
  * the next run will fight it for the debug port.
  *
+ * `onApp` is the one hook in here. It is handed the app the moment it is open
+ * and before a single picture is taken, which is what lets the watch panel put
+ * itself beside a window that did not exist when the panel opened. It moves
+ * windows around a desk; it never touches the page, and the picture comes from
+ * the viewport the capture sets, not from the window — so where the window ends
+ * up cannot change what was photographed.
+ *
  * @template T
  * @param {import('./types.js').Project} project
  * @param {(app: import('./types.js').LaunchedApp) => Promise<T>} work
+ * @param {{
+ *   events?: import('./types.js').RunEvents,
+ *   timings?: ReturnType<typeof makeTimings>,
+ *   onApp?: (app: import('./types.js').LaunchedApp) => Promise<void>,
+ * }} [ctx]
  * @returns {Promise<T>}
  */
-async function withApp(project, work) {
-  const app = await launchApp(project);
+async function withApp(project, work, ctx = {}) {
+  emitEvent(ctx.events, { type: 'phase', message: 'opening the app' });
+  const stopLaunch = ctx.timings?.mark('launch');
+  // Stopped even when the app never opened: a launch that gave up after fifty
+  // seconds is exactly the number somebody wants to see.
+  const app = await launchApp(project).finally(() => stopLaunch?.());
+  if (ctx.onApp) {
+    try {
+      await ctx.onApp(app);
+    } catch (e) {
+      // Whatever wanted a look at the app is a spectator. A spectator that
+      // trips over must not take the run down with it, and is not worth a
+      // warning in the middle of a clean one.
+      detail(`Something watching this run could not be shown the app. ${messageOf(e)}`);
+    }
+  }
   try {
     return await work(app);
   } finally {
+    emitEvent(ctx.events, { type: 'phase', message: 'closing' });
     try {
       await app.close();
     } catch (e) {
@@ -459,6 +607,48 @@ async function withApp(project, work) {
   }
 }
 
+/**
+ * How many screens a walk will visit, or none when there is nothing to walk.
+ *
+ * @param {import('./types.js').ResolvedConfig} config
+ * @param {string|string[]} [only]
+ * @returns {number}
+ */
+function countWalk(config, only) {
+  try {
+    return countWalkSteps(config, only);
+  } catch {
+    // Nothing to walk through. The walk itself says so properly, in one place.
+    return 0;
+  }
+}
+
+/**
+ * The app being opened, in a few words: what kind it is and which one it is.
+ *
+ * A watcher shows this at the top of a narrow panel, so the whole path or the
+ * whole address would be noise — the name of the binary, or the host being
+ * opened, is what a person recognises.
+ *
+ * @param {import('./types.js').AppConfig} app
+ * @returns {string}
+ */
+function describeApp(app) {
+  if (app.kind === 'electron') {
+    const binary = app.binary ?? app.attach ?? '';
+    return binary ? `electron — ${path.basename(binary)}` : 'electron';
+  }
+  const url = app.url ?? app.attach ?? '';
+  if (!url) return 'web';
+  try {
+    // A web address has no useful last part — "/" is not a name — so the host is
+    // what gets shown: "web — localhost:5173".
+    return `web — ${new URL(url).host || url}`;
+  } catch {
+    return `web — ${url}`;
+  }
+}
+
 /**
  * Flatten both kinds of result into the one shape the flake register folds.
  * @param {PictureRunResult[]} pictures