staysfixed 0.7.2 → 0.8.0

package/src/cli/index.js

@@ -12,6 +12,8 @@ import { setLogLevel } from '../core/log.js';
 import { V2_COMMANDS } from '../v2/cli.js';
 import { SHIP_COMMANDS } from '../v2/ship.js';
 import { INIT_COMMANDS } from '../v2/init.js';
+import { BROWSERS_COMMAND } from '../v2/browsers.js';
+export { watchFlags } from './watch-flags.js';
 
 /** @type {{version?: string}} */
 const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
@@ -61,9 +63,22 @@ export const VERSION = pkg.version ?? '0.0.0';
  * @property {() => Promise<{run: (ctx: CliContext) => Promise<number>}>} [load]
  */
 
-/** @type {ArgSpec} */
+/**
+ * The flags every command takes.
+ *
+ * `no-color` is declared as its own switch rather than as `color`, and that is not a
+ * spelling choice. Colour is settled in bin/staysfixed.js, before anything else is
+ * imported, because src/core/log.js decides once at load whether it may paint — so by the
+ * time a command is parsed the answer is already fixed and nothing here could change it.
+ * Declaring `color` made `--color` a real flag that turned nothing on, which is the worst
+ * kind: a person types it, the tool accepts it, and nothing happens. There is no way to
+ * force colour ON from here, so the only honest thing to offer is the half that works.
+ * `--no-color` is named so `--help` and the parser agree; the work is already done.
+ *
+ * @type {ArgSpec}
+ */
 const GLOBAL_SPEC = {
-  booleans: ['verbose', 'quiet', 'help', 'version', 'color'],
+  booleans: ['verbose', 'quiet', 'help', 'version', 'no-color'],
   strings: ['config', 'cwd'],
   alias: { v: 'verbose', q: 'quiet', h: 'help', V: 'version' },
 };
@@ -76,7 +91,7 @@ const GLOBAL_VALUE_FLAGS = new Set(['--config', '--cwd']);
  * are declared once here so the two commands cannot drift apart.
  */
 const WATCH_SPEC = {
-  booleans: ['watch', 'watch-front', 'keep-open', 'profile'],
+  booleans: ['watch', 'watch-front', 'keep-open', 'profile', 'snap'],
   strings: ['watch-side', 'watch-width'],
 };
 
@@ -86,12 +101,20 @@ const WATCH_OPTIONS = [
   ['--watch-side <side>', 'Which side of the app the panel sits on: left or right. Default right.'],
   ['--watch-width <n>', 'How wide the panel is, in pixels. Default 460.'],
   ['--no-keep-open', 'Close the panel as soon as the run finishes.'],
+  ['--no-snap', 'Leave both windows exactly where they are instead of putting them side by side.'],
   ['--watch-front', 'Bring the panel to the front. By default it opens behind your work.'],
   ['--profile', 'Print where the time went when the run is over.'],
 ];
 
-/** @type {Record<string, CommandEntry>} */
-const COMMANDS = {
+/**
+ * Every command, and the only list of them. `--help` is printed from this, and every
+ * flag any command accepts is declared in its `spec` here — so a flag that prints in the
+ * help and a flag the parser knows about cannot drift apart. It is exported so that can
+ * be checked from outside rather than by reading two lists side by side.
+ *
+ * @type {Record<string, CommandEntry>}
+ */
+export const COMMANDS = {
   init: {
     summary: 'Set this project up. Takes about thirty seconds.',
     usage: 'staysfixed init [--force] [--json]',
@@ -227,6 +250,16 @@ const COMMANDS = {
     examples: ['staysfixed mcp', 'staysfixed mcp --v1'],
     spec: { booleans: ['v1'] },
   },
+
+  /*
+   * `browsers` was written, tested, given a finished command entry in src/v2/browsers.js
+   * with a comment saying "wiring it up is one line" — and that line was never written.
+   * README.md told people to run `npx staysfixed browsers` and `--clean` to tidy up after
+   * an interrupted run, and both answered "There is no command called browsers". Somebody
+   * whose disk was filling with abandoned browser profiles had no way to clear them and no
+   * reason to doubt the page telling them there was.
+   */
+  browsers: BROWSERS_COMMAND,
 };
 
 /*
@@ -352,45 +385,8 @@ function contextFor(parsed, cwd, configFile) {
  * @property {boolean} [foreground]
  */
 
-/**
- * Read the panel flags. Shared by `check` and `walk` so the two behave the same.
- * @param {CliContext} ctx
- * @returns {WatchFlags}
- */
-export function watchFlags(ctx) {
-  /** @type {WatchFlags} */
-  const flags = { enabled: ctx.bool('watch') };
-
-  const side = ctx.str('watch-side');
-  if (side !== undefined) {
-    if (side !== 'left' && side !== 'right') {
-      throw new StaysFixedError(`--watch-side has to be left or right, not "${side}".`, {
-        hint: 'Write it as `--watch-side left` or `--watch-side right`.',
-      });
-    }
-    flags.side = side;
-  }
-
-  const width = ctx.str('watch-width');
-  if (width !== undefined) {
-    const n = Number(width);
-    // A panel narrower than this cannot show the before-and-after pictures side
-    // by side, which is the only reason to open it.
-    if (!Number.isFinite(n) || n < 240) {
-      throw new StaysFixedError(`--watch-width has to be a number of pixels, 240 or more — I got "${width}".`, {
-        hint: 'Write it as `--watch-width 520`.',
-      });
-    }
-    flags.width = Math.round(n);
-  }
+// `watchFlags` moved to ./watch-flags.js — see the note there about the import cycle.
 
-  // Only mention these when they were actually typed, so --no-keep-open turns the
-  // panel off at the end without a bare --watch turning it on against the settings.
-  if (ctx.flags['keep-open'] !== undefined) flags.keepOpen = ctx.flags['keep-open'] === true;
-  if (ctx.bool('watch-front')) flags.foreground = true;
-
-  return flags;
-}
 
 /**
  * The panel settings a project's settings file carries, if it carries any.
@@ -446,15 +442,28 @@ function splitCommand(argv) {
 }
 
 /**
+ * The global flags plus one command's own — with the command winning any name they share.
+ *
+ * That last part is the whole reason this is not a concatenation. `--version` is global and
+ * means "print the tool's version"; `staysfixed ship --version 0.14.0` means "the release
+ * that went out was called 0.14.0", and it is in that command's own help. Merged naively,
+ * the name landed in both lists, the parser reads booleans first, and `staysfixed ship
+ * --version 0.14.0` printed `0.7.2` and shipped nothing at all — no error, no clue, and the
+ * release script that called it carried on. A command's own list of flags is the more
+ * specific statement of what that command means, so it wins.
+ *
  * @param {ArgSpec} base
  * @param {ArgSpec} extra
  * @returns {ArgSpec}
  */
 function mergeSpec(base, extra) {
+  const claimed = new Set([...(extra.booleans ?? []), ...(extra.strings ?? []), ...(extra.arrays ?? [])]);
+  /** @param {string[]|undefined} names */
+  const keep = (names) => (names ?? []).filter((name) => !claimed.has(name));
   return {
-    booleans: [...(base.booleans ?? []), ...(extra.booleans ?? [])],
-    strings: [...(base.strings ?? []), ...(extra.strings ?? [])],
-    arrays: [...(base.arrays ?? []), ...(extra.arrays ?? [])],
+    booleans: [...keep(base.booleans), ...(extra.booleans ?? [])],
+    strings: [...keep(base.strings), ...(extra.strings ?? [])],
+    arrays: [...keep(base.arrays), ...(extra.arrays ?? [])],
     alias: { ...(base.alias ?? {}), ...(extra.alias ?? {}) },
   };
 }

package/src/cli/watch-flags.js

@@ -0,0 +1,54 @@
+/**
+ * Reading the --watch flags off a command line.
+ *
+ * This lives on its own, and not in `src/cli/index.js` where it started, because both
+ * halves of the tool need it and the import went in a circle: version 1's command table
+ * imports version 2's commands, and version 2's command file imported this back out of
+ * version 1's table. That worked only while the modules happened to load in a helpful
+ * order — the day another import was added to version 2, the whole command line failed
+ * with "cannot access V2_COMMANDS before initialization" and nothing ran at all.
+ *
+ * A shared thing that both sides need belongs to neither of them.
+ */
+
+import { StaysFixedError } from '../core/errors.js';
+
+/**
+ * Read the panel flags. Shared by `check` and `walk` so the two behave the same.
+ * @param {import('./index.js').CliContext} ctx
+ * @returns {import('./index.js').WatchFlags}
+ */
+export function watchFlags(ctx) {
+  /** @type {import('./index.js').WatchFlags} */
+  const flags = { enabled: ctx.bool('watch') };
+
+  const side = ctx.str('watch-side');
+  if (side !== undefined) {
+    if (side !== 'left' && side !== 'right') {
+      throw new StaysFixedError(`--watch-side has to be left or right, not "${side}".`, {
+        hint: 'Write it as `--watch-side left` or `--watch-side right`.',
+      });
+    }
+    flags.side = side;
+  }
+
+  const width = ctx.str('watch-width');
+  if (width !== undefined) {
+    const n = Number(width);
+    // A panel narrower than this cannot show the before-and-after pictures side
+    // by side, which is the only reason to open it.
+    if (!Number.isFinite(n) || n < 240) {
+      throw new StaysFixedError(`--watch-width has to be a number of pixels, 240 or more — I got "${width}".`, {
+        hint: 'Write it as `--watch-width 520`.',
+      });
+    }
+    flags.width = Math.round(n);
+  }
+
+  // Only mention these when they were actually typed, so --no-keep-open turns the
+  // panel off at the end without a bare --watch turning it on against the settings.
+  if (ctx.flags['keep-open'] !== undefined) flags.keepOpen = ctx.flags['keep-open'] === true;
+  if (ctx.bool('watch-front')) flags.foreground = true;
+
+  return flags;
+}

package/src/core/config.js

@@ -49,9 +49,29 @@ export const DEFAULT_FREEZE = {
 
 /** @type {Required<Omit<import('../types.js').ToleranceConfig,'maxPixels'>>} */
 export const DEFAULT_TOLERANCE = {
-  // 0.05% of pixels. On a 1440x900 @2x picture that is about 1300 pixels — enough
-  // for font hinting noise, nowhere near enough to hide a missing stylesheet.
-  pixels: 0.0005,
+  // Nothing is allowed through by default, and that is a change made after measuring.
+  //
+  // This used to be 0.0005 — 0.05% of the picture — with a comment saying it was "enough for
+  // font hinting noise, nowhere near enough to hide a missing stylesheet". The first half was
+  // a guess and the second half was wrong. On a 2880x1800 picture, 0.05% is **2,592 pixels**.
+  // Changing `<h1>Welcome</h1>` to `<h1>Welcom</h1>` — one letter missing from the main
+  // heading of the page, plainly visible to anybody looking at it — moves **593**. So the
+  // check reported "Everything that worked still works" over a page that was visibly wrong.
+  // That is the exact failure this tool exists to prevent, produced by the tool itself.
+  //
+  // The number that replaces it was measured rather than chosen. Ten fresh takes of the same
+  // build, on a real page, compared against the approved picture: **zero differing pixels,
+  // every time.** The freeze layer underneath — the stopped clock, the killed motion, the
+  // seeded randomness, the pinned text rendering, and the settle loop that keeps shooting
+  // until two frames come back identical — is what makes that true. Where nothing wobbles,
+  // an allowance buys nothing at all and costs you the one thing you came for.
+  //
+  // Version 2 answers this properly by measuring each product's own wobble and subtracting
+  // it, which is why it has no tolerance setting and never will. Version 1 cannot do that
+  // without becoming version 2, so it does the honest next-best thing: allow nothing, and
+  // let a project that genuinely wobbles say so out loud with `tolerance.pixels`. A run that
+  // uses an allowance now says so, and says how much of it was used.
+  pixels: 0,
   threshold: 0.12,
   antialiasing: true,
 };

package/src/guard/run.js

@@ -289,7 +289,7 @@ async function attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep) {
       };
     }
     const raw = error instanceof Error ? error.message : String(error);
-    return { ok: false, message: `${raw}${consoleNote(app)}` };
+    return { ok: false, message: `${explainApiSlip(raw, app.page, project)}${consoleNote(app)}` };
   } finally {
     // The losing side of the race keeps running otherwise, and a stray timer
     // holds the process open long after the run is reported.
@@ -299,6 +299,54 @@ async function attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep) {
   return { ok: true };
 }
 
+/**
+ * Turn "page.goto is not a function" into one sentence a person can act on.
+ *
+ * A guard is the first code most people write against this tool, and the object it is handed
+ * is not the shape anybody arrives expecting. Reach for a name from a browser library that is
+ * not there and JavaScript answers with its own sentence, which is true, useless, and exactly
+ * the kind of raw error this project promises never to print. The first guard written against
+ * it while proving the tool still worked failed this way.
+ *
+ * Two things it must not do, both learned by getting them wrong first:
+ *
+ *  - **Do not trust the receiver's name.** The guard above called its one parameter `page`,
+ *    so the error read `page.goto is not a function` — but the parameter holds `app`, and the
+ *    honest answer is `app.open()`. Reading that name as if it meant the page suggested
+ *    "did you mean goto()", which is the very thing they had just written.
+ *  - **Do not list every method.** An earlier version printed all thirty names on the page
+ *    handle inline. It was complete, unreadable, and it destroyed the results table it sat in.
+ *
+ * So: name the six things on `app`, say where the rest live, and stop.
+ *
+ * @param {string} raw
+ * @param {import('../types.js').PageHandle} page
+ * @param {import('../types.js').Project} project
+ * @returns {string}
+ */
+export function explainApiSlip(raw, page, project) {
+  const missing = /^(?:\w+\.)?(\w+) is not a function$/.exec(String(raw || ''));
+  if (!missing) return raw;
+  const method = missing[1];
+  const api = makeGuardApi(page, project, {});
+  const onApp = Object.keys(api).filter((k) => typeof (/** @type {any} */ (api))[k] === 'function').sort();
+  if (onApp.includes(method)) return raw;
+
+  // Only ever suggested from what `app` itself offers, and only when one name is clearly the
+  // one meant. A guess between three is worse than no guess.
+  const near = onApp.filter((n) => n.toLowerCase().includes(method.toLowerCase()) || method.toLowerCase().includes(n.toLowerCase()));
+  const browserish = /^(goto|navigate|visit|load|open|click|type|fill|press|hover|wait|screenshot|querySelector|\$)/i.test(method);
+  const meant = near.length === 1 ? ` You probably want \`app.${near[0]}()\`.`
+    : browserish ? ' To go to a page it is `app.open(\'/path\')`; anything a browser does is on `app.page`.'
+    : '';
+
+  return (
+    `This guard called \`${method}()\` on what it was handed, and there is no such thing there.${meant} ` +
+    `A guard is given one object — call it \`app\` — with ${onApp.map((n) => `\`${n}()\``).join(', ')}. ` +
+    'The whole page is `app.page`. There is a worked example in `examples/guards/`.'
+  );
+}
+
 /** A timeout, kept apart from a real error so the wording stays ours. */
 class TookTooLong extends Error {
   /** @param {string} message */

package/src/report/console.js

@@ -210,9 +210,22 @@ export function printPictureResult(r) {
   const time = paint.grey(duration(r.durationMs ?? 0));
   const line = `${r.name.padEnd(NAME_WIDTH)} ${pictureOutcome(r)}`;
   switch (r.status) {
-    case 'passed':
-      say(`${paint.green(sym(mark.pass))} ${r.name.padEnd(NAME_WIDTH)} ${paint.grey('still the same')} ${time}`);
+    case 'passed': {
+      // "Still the same" has to mean the same, or it is the most expensive sentence here.
+      //
+      // A picture that differs and is waved through by an allowance was reported as
+      // identical, in the same words as one that matched byte for byte. That is how a
+      // missing letter in a heading — 593 pixels, plainly visible — came back as "still the
+      // same" while an allowance of 2,592 quietly absorbed it. Nothing is allowed through by
+      // default any more, so this is rare; when a project sets `tolerance.pixels` because its
+      // product genuinely wobbles, the line says what its setting just swallowed.
+      const swallowed = r.diffPixels ?? 0;
+      const note = swallowed > 0
+        ? paint.grey(`the same, apart from ${swallowed} ${swallowed === 1 ? 'pixel your tolerance allowed' : 'pixels your tolerance allowed'}`)
+        : paint.grey('still the same');
+      say(`${paint.green(sym(mark.pass))} ${r.name.padEnd(NAME_WIDTH)} ${note} ${time}`);
       break;
+    }
     case 'changed':
       say(`${paint.red(sym(mark.fail))} ${paint.red(line)} ${time}`);
       if (r.approvedSize && r.size && (r.approvedSize.width !== r.size.width || r.approvedSize.height !== r.size.height)) {

package/src/v2/adapters/android-driver.js

@@ -1393,8 +1393,13 @@ export async function permissionsHeld(device, pkg) {
  * and pids are stripped from the text kept, since all three differ on every run and none of
  * them is ever the finding.
  *
+ * There is no time window here, and there used to be a `sinceMs` in this signature that
+ * nothing read. The window comes from the other end: the adapter clears both log buffers
+ * before it walks anything, so what is left is this run. An option that silently does
+ * nothing is worse than no option, because a caller passing it believes it worked.
+ *
  * @param {Device} device
- * @param {{pkg: string, pid?: number, sinceMs?: number}} what
+ * @param {{pkg: string, pid?: number}} what
  * @returns {Promise<{crashes: string[], anrs: string[], errors: string[], lines: string[], raw: string}>}
  */
 export async function complaints(device, what) {

package/src/v2/adapters/android.js

@@ -73,6 +73,100 @@ const CLEAN_SNAPSHOT = 'staysfixed-clean';
 /** The journey that needs no device at all. */
 const DECLARED = 'what the app declares';
 
+// ---------------------------------------------------------------------------
+// The virtual device this tool asks for
+// ---------------------------------------------------------------------------
+
+/**
+ * The API level to build a virtual device at when nothing says otherwise.
+ *
+ * Newer is the safe direction and it is the only direction that is safe. A device must be at
+ * least as new as the app's `minSdkVersion` or the app cannot be installed on it at all; an app
+ * that TARGETS something older installs on a newer device and runs under compatibility rules.
+ * So the failure from picking too high is a behaviour difference the tool would report, and the
+ * failure from picking too low is "it would not install", which looks like a broken product.
+ *
+ * When there is an APK in hand its own minSdk is read and this is raised to match — see
+ * `deviceFor`. This number is only the answer for somebody who has not built anything yet.
+ */
+export const EMULATOR_API = 35;
+
+/**
+ * The processor the image has to be built for.
+ *
+ * Both files that recommended an image used to hardcode `arm64-v8a`, so the command handed to
+ * anybody on an Intel Mac or an x86 Linux box named an image that does not exist for their
+ * machine and failed with a message about the image rather than about the architecture.
+ *
+ * @returns {string|null} null when this machine's architecture has no emulator image at all.
+ */
+export function emulatorAbi() {
+  // Only three answers exist, and anything else has to say so rather than pick one.
+  //
+  // This used to be arm64 or x86_64, with x86_64 as the fallback for every other
+  // architecture. On a 32-bit Intel machine, or an s390x, or anything else Node runs on, that
+  // names an emulator image Google does not publish — so the command handed over as "the tool
+  // can do this itself" fails with an error about a package that does not exist, and the
+  // person is left looking for a typo in a line this tool wrote for them.
+  if (process.arch === 'arm64') return 'arm64-v8a';
+  if (process.arch === 'x64') return 'x86_64';
+  if (process.arch === 'ia32') return 'x86';
+  return null;
+}
+
+/**
+ * What to install, and the two commands that install it — kept together on purpose.
+ *
+ * The warning is part of the answer, not a footnote beside it. A Play Store image refuses root
+ * permanently, and without root the files an app writes are invisible, so a person who follows
+ * a command printed without this sentence ends up with a device that silently checks less than
+ * they think. That happened because two files each had their own copy of the command and only
+ * one carried the warning. There is one copy now, and the warning cannot be separated from it.
+ *
+ * `google_apis` and NOT `google_apis_playstore` is the whole of the rule.
+ *
+ * @param {{api?: number, name?: string}} [opts]
+ * @returns {{image: string|null, install: string|null, create: string|null, why: string, both: string}}  image, install and create are null where this machine has no emulator image at all; `why` and `both` then say so.
+ */
+export function deviceToMake(opts = {}) {
+  const api = Math.max(EMULATOR_API, opts.api ?? 0);
+  const name = opts.name ?? 'staysfixed';
+  const abi = emulatorAbi();
+  const warning = 'Pick a plain Google APIs image, NOT a Play Store one: a Play Store device refuses root forever, and without root the files an app writes cannot be seen.';
+
+  // No image exists for this machine, and saying so beats naming one that does not exist.
+  //
+  // Google publishes emulator images for arm64, x86_64 and x86 and nothing else. Handing
+  // somebody a command that fails on a package nobody has ever published sends them looking
+  // for a typo in a line this tool wrote for them, which is a worse place to be than being
+  // told plainly that their machine cannot run one.
+  if (!abi) {
+    const cannot = `No Android emulator image is published for a ${process.arch} machine, so an emulator cannot be created here. Plug in a real Android device, or run the check from a machine on arm64, x86_64 or x86.`;
+    return { image: null, install: null, create: null, why: cannot, both: cannot };
+  }
+
+  const image = `system-images;android-${api};google_apis;${abi}`;
+  const install = `sdkmanager --install "${image}"`;
+  const create = `avdmanager create avd -n ${name} -k "${image}"`;
+  return {
+    image,
+    install,
+    create,
+    why: warning,
+    both: `${install} then ${create}. ${warning}`,
+  };
+}
+
+/**
+ * The same answer, raised to whatever the app in front of us actually needs.
+ *
+ * @param {{minSdk?: number|null}|null} apk
+ * @returns {ReturnType<typeof deviceToMake>}
+ */
+export function deviceFor(apk) {
+  return deviceToMake({ api: apk?.minSdk ?? 0 });
+}
+
 // ---------------------------------------------------------------------------
 // Finding the APK
 // ---------------------------------------------------------------------------
@@ -522,7 +616,7 @@ export const androidAdapter = defineAdapter({
       missing.push({
         what: 'a virtual device for the emulator to run',
         unlocks: 'having somewhere to install the app',
-        howToGet: 'sdkmanager --install "system-images;android-33;google_apis;arm64-v8a" then avdmanager create avd -n staysfixed -k "system-images;android-33;google_apis;arm64-v8a". Pick a plain Google APIs image, NOT a Play Store one: a Play Store device refuses root forever, and without root the files an app writes cannot be seen.',
+        howToGet: deviceFor(apk).both,
       });
     }
 
@@ -531,7 +625,8 @@ export const androidAdapter = defineAdapter({
       missing.push({
         what: 'a virtual device built from a plain Google APIs image rather than a Play Store one',
         unlocks: 'seeing the files the app writes, and stopping the clock. A Play Store device refuses root permanently, and both of those need it',
-        howToGet: 'avdmanager create avd -n staysfixed -k "system-images;android-33;google_apis;arm64-v8a"',
+        // Null on a machine with no emulator image at all; `why` then carries the reason.
+        howToGet: deviceFor(apk).create ?? deviceFor(apk).why,
       });
     }
     if (usable.some((d) => !d.emulator)) {

package/src/v2/adapters/contract.js

@@ -611,11 +611,21 @@ export function undoOurFootprint(text, footprint) {
  * @returns {{text: string, truncated: boolean, bytes: number}}
  */
 export function trimForStorage(text, limit = 64 * 1024) {
-  const bytes = Buffer.byteLength(text, 'utf8');
-  if (bytes <= limit) return { text, truncated: false, bytes };
+  const whole = Buffer.from(String(text), 'utf8');
+  const bytes = whole.length;
+  if (bytes <= limit) return { text: String(text), truncated: false, bytes };
   const keep = Math.floor(limit / 2);
-  const head = text.slice(0, keep);
-  const tail = text.slice(-keep);
+  // Cut in BYTES, which is what the limit is counted in. This used to cut in characters, and
+  // on anything that is not plain ASCII the two are not the same number: a screenful of
+  // box-drawing or CJK is three bytes a character, so 90,000 bytes of it is only 30,000
+  // characters, both halves took the WHOLE text, and the stored value came out at 180,000
+  // bytes — the entire output twice, under a marker claiming 24,464 bytes had been left out
+  // of the middle. Three lies at once: the limit was not applied, the count was wrong, and
+  // the observation was marked not-fully-covered when in fact nothing had been dropped.
+  const headEnd = backToACharacter(whole, keep);
+  const tailStart = onToACharacter(whole, bytes - keep);
+  const head = whole.subarray(0, headEnd).toString('utf8');
+  const tail = whole.subarray(tailStart).toString('utf8');
   // The marker used to carry a COARSE size bucket, and the doc above it claimed a fingerprint
   // of the whole that was never actually computed. Both halves of that were wrong, and the
   // result was the worst thing this tool can produce: a change that happened entirely in the
@@ -636,8 +646,35 @@ export function trimForStorage(text, limit = 64 * 1024) {
   // as not fully covered, the coverage ledger states the hole, and the whole text is written
   // to the evidence folder so anybody can look.
   return {
-    text: `${head}\n... exactly ${bytes - keep * 2} bytes left out of the middle of ${bytes} ...\n${tail}`,
+    text: `${head}\n... exactly ${tailStart - headEnd} bytes left out of the middle of ${bytes} ...\n${tail}`,
     truncated: true,
     bytes,
   };
 }
+
+/**
+ * Cutting a multi-byte character in half turns it into a replacement character, which is a
+ * difference nobody made and which would then move about between runs. These two walk the cut
+ * to the nearest place a character actually starts — backwards for the head, forwards for the
+ * tail, so the two halves can never grow into each other.
+ *
+ * @param {Buffer} buffer
+ * @param {number} at
+ * @returns {number}
+ */
+function backToACharacter(buffer, at) {
+  let cut = at;
+  while (cut > 0 && (buffer[cut] & 0xC0) === 0x80) cut -= 1;
+  return cut;
+}
+
+/**
+ * @param {Buffer} buffer
+ * @param {number} at
+ * @returns {number}
+ */
+function onToACharacter(buffer, at) {
+  let cut = at;
+  while (cut < buffer.length && (buffer[cut] & 0xC0) === 0x80) cut += 1;
+  return cut;
+}