staysfixed 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers — as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",

package/src/core/events.js

@@ -13,6 +13,7 @@
  * run and still draw the screens that were photographed before it opened.
  */
 
+import { pathToFileURL } from 'node:url';
 import { detail } from './log.js';
 import { messageOf } from './errors.js';
 
@@ -111,6 +112,33 @@ export function emitEvent(events, event) {
   events.emit(/** @type {RunEvent} */ (event));
 }
 
+/**
+ * A file on disk, as an address a local page can load.
+ *
+ * The watch panel is itself a local `file://` page, which means it can open the real
+ * full-resolution PNGs this run just wrote instead of a shrunken copy pasted into the
+ * event. That is the difference between a picture you can zoom into and a picture you
+ * cannot read — and it costs nothing to send, because the address is a few dozen
+ * characters and the pixels never move.
+ *
+ * Hands back `undefined` rather than a broken address for anything that is not a real
+ * path: an <img> pointed at a file that is not there draws the browser's torn-page
+ * icon, which looks like the tool is broken. Nothing at all looks like nothing at all.
+ *
+ * @param {string|undefined|null} file  An absolute path to a file that EXISTS. Callers
+ *   pass the path they have just written, or one they have just read — this function
+ *   does not touch the disk, so it cannot tell the difference itself.
+ * @returns {string|undefined}
+ */
+export function fileUrl(file) {
+  if (typeof file !== 'string' || file === '') return undefined;
+  try {
+    return pathToFileURL(file).href;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Where a run spent its time.
  *

package/src/picture/capture.js

@@ -53,7 +53,8 @@ const KNOWN_KEYS = new Set([...ACTION_ORDER, 'text', 'note']);
  * }} settings
  * @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.
+ *   decode of the picture that was just taken (skipped when the masks already decoded it)
+ *   plus about forty milliseconds of shrinking, so it is off unless it is wanted.
  * @returns {Promise<import('../types.js').CaptureReport & {
  *   masks: import('../types.js').MaskRect[],
  *   timings: {steps: number, prepare: number, settle: number},
@@ -134,7 +135,12 @@ export async function captureScreen(page, screen, settings, ctx) {
     spent.settle = since(startedSettle, clock());
 
     const rects = await resolveMasks(page, settings.masks ?? [], { deviceScaleFactor });
-    const png = rects.length > 0 ? paintInto(held.png, rects) : held.png;
+    // Masks force us to decode the picture; hold on to those pixels. The preview a
+    // watcher is shown is made from the very same ones — the picture that gets
+    // compared, blackout boxes and all — so a masked screen decodes a retina
+    // screenshot once instead of twice, which is about eighty milliseconds a screen.
+    const painted = rects.length > 0 ? paintInto(held.png, rects) : null;
+    const png = painted ? painted.png : held.png;
     const size = pngSize(png);
 
     // The picture is taken; now put the app back if this screen asked us to.
@@ -164,7 +170,7 @@ export async function captureScreen(page, screen, settings, ctx) {
       spent,
     };
     if (ctx.thumbnail === true) {
-      const small = await thumbnailOf(png);
+      const small = await thumbnailOf(painted ? painted.image : png);
       if (small) report.thumbnail = small;
     }
     return report;
@@ -190,14 +196,19 @@ function since(from, to) {
 
 /**
  * Paint the masks into a screenshot and re-encode it.
+ *
+ * Hands back the decoded picture as well as the bytes. Whoever wants a preview of this
+ * screen would otherwise decode the very same megapixels a second time, and on a retina
+ * screenshot that is the most expensive thing either of them does.
+ *
  * @param {Buffer} buffer
  * @param {import('../types.js').MaskRect[]} rects
- * @returns {Buffer}
+ * @returns {{png: Buffer, image: import('pngjs').PNG}}
  */
 function paintInto(buffer, rects) {
   const image = PNG.sync.read(buffer);
   paintMasks(image, rects);
-  return PNG.sync.write(image);
+  return { png: PNG.sync.write(image), image };
 }
 
 /**

package/src/picture/run.js

@@ -21,7 +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';
+import { emitEvent, fileUrl } from '../core/events.js';
 
 /**
  * A picture result plus the one extra fact the flake register needs: whether it
@@ -30,16 +30,26 @@ import { emitEvent } from '../core/events.js';
  */
 
 /**
- * The small pictures a watcher is shown, filled in as a screen is worked on.
+ * What a watcher is shown of one screen, filled in as it is worked on.
  *
- * They are kept apart from the result on purpose. A result is written to disk and
+ * Two kinds of thing, for two different moments. The `file://` addresses are the real
+ * full-resolution pictures this run wrote, and they are what a person actually looks
+ * at and zooms into; they cost nothing to fill in, so they are always filled in. The
+ * base64 previews are the instant stand-in for the fraction of a second before a file
+ * loads, they cost real milliseconds to make, and they are only made when a window is
+ * open to show them in.
+ *
+ * All of it is 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.
+ * @property {string} [shot]         Instant preview of the picture just taken.
+ * @property {string} [approved]     Instant preview of the approved picture, when this screen changed.
+ * @property {string} [diff]         Instant preview of what moved, when this screen changed.
+ * @property {string} [shotFile]     The picture just taken, on disk.
+ * @property {string} [approvedFile] The approved picture, on disk, when there is one.
+ * @property {string} [diffFile]     The difference picture, on disk, when one was written.
  */
 
 /**
@@ -153,6 +163,12 @@ function emitDone(events, result, thumbs) {
     thumbnail: thumbs.shot,
     approvedThumb: thumbs.approved,
     diffThumb: thumbs.diff,
+    // The real pictures. Only ever set for a file that was written or read a moment
+    // ago, so anything that arrives here can be opened; a screen that was skipped, or
+    // one that could not be photographed at all, sends none of them.
+    shotFile: thumbs.shotFile,
+    approvedFile: thumbs.approvedFile,
+    diffFile: thumbs.diffFile,
   });
 }
 
@@ -194,6 +210,11 @@ async function runOneScreen(project, page, screen, ctx) {
   const approved = await readApproved(paths, screen.name);
   const platformNote = platformWarning(approved?.meta?.platform, ctx.here);
 
+  // We have just read it, so it is certainly there. Pointed out even for a screen that
+  // ends up matching: "show me what this is supposed to look like" is a fair question
+  // about a screen that passed, and answering it costs one string.
+  if (approved && ctx.thumbs) ctx.thumbs.approvedFile = fileUrl(approvedPaths.png);
+
   /** @type {string[]} */
   let consoleErrors = [];
   /** @type {{width: number, height: number}|undefined} */
@@ -225,19 +246,28 @@ async function runOneScreen(project, page, screen, ctx) {
       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, {
+      const shotFile = await writeResult(paths, screen.name, shot.png, {
         deviceScaleFactor: settings.viewport.deviceScaleFactor,
         describe: screen.describe,
       });
 
+      // Said out loud before anything is compared, so a person watching sees the
+      // picture appear while the run is still deciding what it thinks of it — but
+      // AFTER the PNG is on disk, not the instant the shutter fires. The panel opens
+      // the real file to show true pixels, and an <img> pointed at a file that does
+      // not exist yet draws a torn page and never retries. The preview travels on the
+      // same event and covers the moment the file takes to load.
+      if (ctx.thumbs) {
+        if (shot.thumbnail) ctx.thumbs.shot = shot.thumbnail;
+        ctx.thumbs.shotFile = fileUrl(shotFile);
+      }
+      emitEvent(ctx.events, {
+        type: 'screen:shot',
+        name: screen.name,
+        thumbnail: shot.thumbnail,
+        shotFile: fileUrl(shotFile),
+      });
+
       if (!approved) break;
 
       const stopCompare = ctx.timings?.mark('compare');
@@ -287,6 +317,8 @@ async function runOneScreen(project, page, screen, ctx) {
         describe: screen.describe,
         deviceScaleFactor: settings.viewport.deviceScaleFactor,
       });
+      // It exists now, because that call is what wrote it.
+      if (ctx.thumbs) ctx.thumbs.approvedFile = fileUrl(approvedPaths.png);
       return finish(ctx, {
         ...base,
         status: 'new',
@@ -340,11 +372,23 @@ async function runOneScreen(project, page, screen, ctx) {
 
   /** @type {string|undefined} */
   let diffPath;
-  if (compare.diffPng) diffPath = await writeDiff(paths, screen.name, compare.diffPng);
+  if (compare.diffPng) {
+    diffPath = await writeDiff(paths, screen.name, compare.diffPng);
+    // Set only inside this branch: a screen that matched has no difference picture, and
+    // a stale one from a previous run is deleted before every run for exactly that
+    // reason. Pointing at one that is not there is how a panel starts lying.
+    if (ctx.thumbs) ctx.thumbs.diffFile = fileUrl(diffPath);
+  }
 
   // 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.
+  //
+  // Both are made at the same size as the new picture's preview, because a person
+  // comparing three pictures must not be shown one sharp one and two blurred ones.
+  // Each costs a decode plus a shrink — about an eighth of a second on a retina
+  // screenshot — so this stays behind both gates, and behind `changed`. A run where
+  // everything held pays none of it.
   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;

package/src/picture/store.js

@@ -17,11 +17,16 @@ 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.
+ * 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 THUMBNAIL_WIDTH = 320;
+const PREVIEW_WIDTH = 900;
 
 /**
  * A small note written beside a result picture so `approve` knows things the PNG
@@ -31,39 +36,93 @@ const THUMBNAIL_WIDTH = 320;
  * @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 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.
+ * 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.
  *
- * 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.
+ * 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.
  *
- * @param {Buffer} png
+ * 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(png) {
+export async function thumbnailOf(source) {
   try {
-    const full = PNG.sync.read(png);
+    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 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 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 sourceRow = Math.min(full.height - 1, Math.floor(y * step)) * full.width;
+      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 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];
+        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')}`;

package/src/types.js

@@ -495,7 +495,14 @@ export {};
  * @property {string} [message]
  * @property {string} [failedAt]              The plain-language expectation that failed.
  * @property {string} [because]               Why a guard exists.
- * @property {string} [thumbnail]             A small JPEG as a data: URI, for watching.
+ * @property {string} [thumbnail]             A small JPEG as a data: URI — an instant preview, shown
+ *                                          while the real file is still being written.
+ * @property {string} [shotFile]              file:// URL of the FULL-RESOLUTION picture just taken.
+ *                                          The watch panel is itself a local page, so it can load the
+ *                                          real PNG off disk and zoom into actual pixels — a scaled-up
+ *                                          thumbnail is unreadable, which is the whole point of looking.
+ * @property {string} [approvedFile]          file:// URL of the approved picture.
+ * @property {string} [diffFile]              file:// URL of the difference image.
  * @property {string} [approvedThumb]
  * @property {string} [diffThumb]
  * @property {RunSummary} [summary]           Only on 'run:done'.

package/src/walk/run.js

@@ -16,7 +16,7 @@ import { settingsForScreen } from '../core/config.js';
 import { gitInfo } from '../core/git.js';
 import { StaysFixedError, messageOf } from '../core/errors.js';
 import { safeName } from '../core/paths.js';
-import { emitEvent } from '../core/events.js';
+import { emitEvent, fileUrl } from '../core/events.js';
 
 /**
  * Progress handed to `opts.onStep`, once when a step starts and once when it is done.
@@ -87,7 +87,7 @@ export async function walkApp(project, app, opts = {}) {
       total: chosen.length,
     });
 
-    /** @type {{shot?: string}} */
+    /** @type {{shot?: string, shotFile?: string}} */
     const thumbs = {};
     const step = await walkOneStep(page, screen, {
       index,
@@ -112,6 +112,9 @@ export async function walkApp(project, app, opts = {}) {
       durationMs: step.durationMs,
       message: stepMessage(step),
       thumbnail: thumbs.shot,
+      // The real photo of this step, at full resolution. A walk has nothing to compare
+      // against, so there is no approved picture and no difference to point at.
+      shotFile: thumbs.shotFile,
     });
 
     opts.onStep?.({
@@ -151,7 +154,7 @@ export async function walkApp(project, app, opts = {}) {
  *   record: boolean,
  *   events?: import('../types.js').RunEvents,
  *   thumbnail?: boolean,
- *   thumbs?: {shot?: string},
+ *   thumbs?: {shot?: string, shotFile?: string},
  *   timings?: ReturnType<typeof import('../core/events.js').makeTimings>,
  * }} ctx
  * @returns {Promise<import('../types.js').WalkStep>}
@@ -180,10 +183,7 @@ async function walkOneStep(page, screen, ctx) {
     await fsp.writeFile(target, shot.png);
     file = target;
     consoleErrors = shot.consoleErrors;
-    if (shot.thumbnail) {
-      if (ctx.thumbs) ctx.thumbs.shot = shot.thumbnail;
-      emitEvent(ctx.events, { type: 'screen:shot', name: screen.name, thumbnail: shot.thumbnail });
-    }
+    announceShot(ctx, screen.name, target, shot.thumbnail);
   } catch (cause) {
     error = messageOf(cause);
     consoleErrors = readConsole(page);
@@ -193,6 +193,10 @@ async function walkOneStep(page, screen, ctx) {
     try {
       await fsp.writeFile(target, await page.shoot());
       file = target;
+      // No preview for this one: the picture was taken by hand after the capture
+      // broke, so nothing shrank it. The panel loads the real file instead, which is
+      // the one a person needs to see anyway.
+      announceShot(ctx, screen.name, target, undefined);
     } catch {
       file = '';
     }
@@ -217,6 +221,29 @@ async function walkOneStep(page, screen, ctx) {
   return step;
 }
 
+/**
+ * Tell anyone watching that this step has a picture now.
+ *
+ * Called only once the photo is ON DISK. The watch panel loads the real file so a
+ * person can zoom into true pixels, and an <img> pointed at a file that does not exist
+ * yet draws a torn page and never tries again — so the address is never announced early.
+ * The shrunken preview rides along on the same event and covers the moment the real
+ * file takes to load.
+ *
+ * @param {{events?: import('../types.js').RunEvents, thumbs?: {shot?: string, shotFile?: string}}} ctx
+ * @param {string} name
+ * @param {string} file      Absolute path to the photo, already written.
+ * @param {string|undefined} thumbnail
+ * @returns {void}
+ */
+function announceShot(ctx, name, file, thumbnail) {
+  if (ctx.thumbs) {
+    if (thumbnail) ctx.thumbs.shot = thumbnail;
+    ctx.thumbs.shotFile = fileUrl(file);
+  }
+  emitEvent(ctx.events, { type: 'screen:shot', name, thumbnail, shotFile: fileUrl(file) });
+}
+
 /**
  * How many screens a walk is about to visit.
  *