@bitmagic/cli 0.1.73-dev.0 → 0.1.73

package/assets/optimizing-assets/references/tools.md

@@ -0,0 +1,131 @@
+# Installing the shared compression tools
+
+`optimize-glb.mjs` runs on two tools, installed once per machine into `~/.bitmagic/tools/` and
+shared by every project on it:
+
+- **`gltf/`:** glTF-Transform 4.5.0 with meshoptimizer 1.2.0 (simplify and meshopt), sharp 0.35.5
+  (image resize and encode) and gltf-validator. About 62 MB.
+- **`ktx/`:** Khronos KTX-Software 4.4.2 (`ktx create` and `ktx extract`), needed only for KTX2
+  textures. About 6 MB.
+
+The versions are pinned because the script relies on their defaults (what `prune`, `quantize` and
+`weld` keep), which can change between releases. The script prints a warning when the installed
+versions differ from these. `ab-compare.mjs` needs none of this for PNG captures.
+
+Nothing is installed system-wide, nothing needs sudo or admin rights, and nothing is added to the
+game's `package.json`. To remove the tools, delete the folder. Set `BM_TOOLS` to use another folder.
+
+**Installing is a download. Ask the creator first,** and name what will be fetched (the npm
+packages above, and one KTX-Software release file from github.com/KhronosGroup) and where it goes.
+If they decline, stop here. `--meshopt=off` still needs the `gltf/` tools, so there is no
+tool-free path.
+
+## Check what is already there
+
+```sh
+ls ~/.bitmagic/tools/gltf/node_modules/@gltf-transform/core && echo gltf ok
+~/.bitmagic/tools/ktx/bin/ktx --version
+```
+
+On Windows PowerShell:
+
+```powershell
+Test-Path "$env:USERPROFILE\.bitmagic\tools\gltf\node_modules\@gltf-transform\core"
+& "$env:USERPROFILE\.bitmagic\tools\ktx\bin\ktx.exe" --version
+```
+
+Without `ktx/`, every preset that writes or reads KTX2 fails with a clear message. That covers
+`distant-prop`, `hero-prop` and `character`, and any source that already carries KTX2 textures.
+The `level` and `code-driven` presets, and `webp`, `jpeg` or `png` slot specs, work without it.
+
+## glTF-Transform (macOS, Linux, Windows)
+
+Node 20 or later is enough; the game already has it. Install exactly these versions:
+
+```sh
+npm install --prefix ~/.bitmagic/tools/gltf --save-exact @gltf-transform/cli@4.5.0 @gltf-transform/core@4.5.0 @gltf-transform/extensions@4.5.0 @gltf-transform/functions@4.5.0 meshoptimizer@1.2.0 sharp@0.35.5 gltf-validator@2.0.0-dev.3.10
+```
+
+On Windows PowerShell, the same packages with `--prefix "$env:USERPROFILE\.bitmagic\tools\gltf"`.
+To move an existing install onto these versions, run the same command again.
+
+## KTX-Software on macOS: unpack the signed package
+
+Do not use Homebrew. On a Mac whose Xcode licence has not been accepted it fails with "You have not
+agreed to the Xcode license", and accepting it needs sudo. Unpack Khronos' notarized installer
+instead. Use `arm64` on Apple silicon and `x86_64` on Intel.
+
+```sh
+V=4.4.2; A=arm64; T=$(mktemp -d)
+curl -L -o "$T/ktx.pkg" "https://github.com/KhronosGroup/KTX-Software/releases/download/v$V/KTX-Software-$V-Darwin-$A.pkg"
+pkgutil --check-signature "$T/ktx.pkg"          # expect: Developer ID Installer: The Khronos Group, Inc.
+pkgutil --expand-full "$T/ktx.pkg" "$T/x"
+mkdir -p ~/.bitmagic/tools/ktx/bin ~/.bitmagic/tools/ktx/lib
+cp "$T"/x/*-tools.pkg/Payload/usr/local/bin/* ~/.bitmagic/tools/ktx/bin/
+cp -P "$T"/x/*-library.pkg/Payload/usr/local/lib/libktx* ~/.bitmagic/tools/ktx/lib/
+rm -rf "$T"; ~/.bitmagic/tools/ktx/bin/ktx --version
+```
+
+The binaries look for `libktx` in `../lib`, so `bin/` and `lib/` must stay side by side.
+
+## KTX-Software on Linux
+
+```sh
+V=4.4.2; A=x86_64; T=$(mktemp -d)                # or A=arm64
+curl -L -o "$T/ktx.tar.bz2" "https://github.com/KhronosGroup/KTX-Software/releases/download/v$V/KTX-Software-$V-Linux-$A.tar.bz2"
+tar -xjf "$T/ktx.tar.bz2" -C "$T"
+mkdir -p ~/.bitmagic/tools/ktx
+cp -a "$(dirname "$(find "$T" -type f -name ktx -path '*/bin/*' | head -1)")" ~/.bitmagic/tools/ktx/bin
+cp -a "$(dirname "$(find "$T" -name 'libktx.so*' | head -1)")" ~/.bitmagic/tools/ktx/lib
+rm -rf "$T"; ~/.bitmagic/tools/ktx/bin/ktx --version
+```
+
+If `ktx` cannot find `libktx.so`, run `export LD_LIBRARY_PATH=~/.bitmagic/tools/ktx/lib` in the
+same shell as the script.
+
+## KTX-Software on Windows
+
+Download `KTX-Software-4.4.2-Windows-x64.exe` (or `-arm64.exe`) from the v4.4.2 release. Run it and
+choose `%USERPROFILE%\.bitmagic\tools\ktx` as the destination. If it asks for administrator rights,
+cancel and extract it instead with 7-Zip:
+`7z x KTX-Software-4.4.2-Windows-x64.exe -o%USERPROFILE%\.bitmagic\tools\ktx`. Either way,
+`%USERPROFILE%\.bitmagic\tools\ktx\bin\ktx.exe --version` must print 4.4.x.
+
+## The skill's shell lines on Windows PowerShell
+
+SKILL.md's commands are POSIX shell. In PowerShell:
+
+```powershell
+$O = ".agents/skills/optimizing-assets/scripts/optimize-glb.mjs"; node $O --audit src/work/world.json
+$L = "engine/engine/loaders/GltfLoaderSupport.ts"; Test-Path $L
+'setMeshoptDecoder', 'expectGltfLoaderSupport' | ForEach-Object { "$_ $((Select-String -Path $L -Pattern $_).Count)" }
+(Select-String -Path engine/engine/GLBVoxelizer.ts -Pattern packedFloats).Count
+Get-ChildItem -Recurse src -Include *.ts,*.js | Select-String -Pattern 'setMeshoptDecoder|meshoptDecoder' -List
+Get-ChildItem -Recurse src -Include *.ts,*.js | Select-String -Pattern 'gltfLoaderSupportsKtx2|KHR_texture_basisu' -List
+Get-FileHash in.glb -Algorithm SHA256
+```
+
+## Write the shared README
+
+After installing, write `~/.bitmagic/tools/README.md`, so the next agent on this machine knows what
+the folder is. If one exists that recommends running the plain `gltf-transform` commands
+(`meshopt`, `etc1s`, `resize`) on game assets, replace it with this one: their defaults quantize
+skinned and named meshes and encode normal maps as ETC1S.
+
+```markdown
+# Asset compression tools (shared, local)
+
+Installed by an agent following the Bitmagic `optimizing-assets` skill, with the creator's OK.
+Used by every project on this machine. Nothing is installed system-wide; delete this folder to
+remove them.
+
+- `gltf/`: glTF-Transform 4.5.0 (npm, versions pinned) with meshoptimizer 1.2.0, sharp 0.35.5 and
+  gltf-validator.
+- `ktx/`: KTX-Software 4.4.2 (Khronos), `bin/` and `lib/` side by side.
+
+Use them through the skill's script, not the plain `gltf-transform` commands:
+`node .agents/skills/optimizing-assets/scripts/optimize-glb.mjs --help` in a game project. It puts
+`ktx/bin` on PATH itself.
+```
+
+The script's `--help` runs without the tools, so it is a safe first command on any machine.

package/assets/optimizing-assets/references/verification.md

@@ -0,0 +1,118 @@
+# Verifying an optimized asset
+
+An optimization is done when three separate verdicts agree: the numbers went down, the engine loads
+the file, and a player cannot tell the difference at the distance they see it. Report all three
+separately. A strong SSIM does not approve a look, and a pretty sheet does not prove a download got
+smaller.
+
+## Numbers
+
+- **Per asset:** the script's report gives transfer bytes, triangles and estimated GPU memory for
+  textures and geometry. The GPU estimate assumes KTX2 at 1 byte per pixel (BC7 or ASTC) and other
+  images at 4 (RGBA8), plus mips. JPEG, PNG and WebP always upload uncompressed.
+- **Whole game:** run `bitmagic dev`, open the browser's network panel with the cache disabled,
+  and load to the start screen, then into the first level or race. Record the total transferred
+  before and after, and name the few largest requests. Remember one-off costs: the first KTX2 file
+  pulls the Basis transcoder (~0.25 MB).
+- **Phones:** if the game picks assets per device, measure the phone set with a phone viewport and
+  a mobile user agent. Squall Riders' phone download was 13.5 MiB against 21.2 on desktop.
+- **Report MiB or MB, not both mixed.** SR reported MiB and TOR reported MB. 45.4 MB is 43.3 MiB.
+  Say what the "before" was: the original file, not an earlier optimized variant.
+
+## Decode in the engine's own loader
+
+- Play the scene that uses the asset. The console must show no `setMeshoptDecoder must be called`,
+  `setKTX2Loader must be called` or `createRenderPipeline` errors. The last one is WebGPU rejecting
+  a vertex format, which an interleaved or int16 layout causes. Load it cold as well (cache
+  disabled, then a reload with the cache on): a KTX2 file that arrives before WebGPU is ready is the
+  failure an older engine shows (SKILL.md step 5).
+- The dev asset panel builds its loader with the vendored engine's own factory, so it is a decode
+  check only when that engine attaches the decoder. Under a game-side shim the panel fails on
+  meshopt files that the game loads fine. After a `glb` swap it previews `sourceGlbUrl`, which is
+  the original: open `/asset-preview?kind=glb&url=<the new URL, encoded>` on the dev view instead.
+- Run `bitmagic verify` (its `--help` lists the platform and renderer choices). Check WebGPU, the
+  default, and the WebGL fallback when the game supports it: the interleaved-buffer crash is
+  WebGPU-only.
+- Check what code reads, not only what renders: lamps and anchors at the right place, animations
+  playing, IK grips on the handles, liveries and masks recolouring, colliders unchanged. Collider
+  GLBs are separate rows or files: never optimize or redirect them with the visual mesh.
+- If the game parses GLB bytes itself (the script names such files), exercise that path too:
+  TOR's collision meshes come from its own reader, not from GLTFLoader.
+
+## Look: A/B in the real game, before the swap
+
+1. **Show both from one build.** The candidate stays in its work directory, which `bitmagic dev`
+   serves at `/.bitmagic/optimize/<asset>/…`. Add the temporary preview module from
+   [runtime](runtime.md): the page loads the original normally and the candidate with
+   `?preview=1`. Nothing is uploaded, and world.json is untouched. Delete the module after the A/B.
+   - If `src/` already rewrites asset URLs (`grep -rlE "resolveURL|setURLModifier" src/`, a
+     per-device variant map), its rewrite runs before the preview's, so `?preview=1` shows the
+     game's variant, not the candidate. Capture both sides with that game's originals override
+     (Squall Riders: `&assets=orig`).
+   - Before the first capture, confirm that the console printed `[preview] swapped <url>` and that
+     the network panel fetched `/.bitmagic/optimize/<asset>/…`. Without both, the candidate never
+     loaded and the A/B compares the baseline with itself.
+2. **Pin everything that is not the asset.** Use the same build, camera position and direction,
+   time of day and weather, the same viewport and devicePixelRatio, and `?quality=<rung>` so the
+   engine's auto-tuner cannot drop a tier mid-run on a busy machine. If the game has a debug hook
+   to freeze time or the simulation, use it. Particles and water move between two runs.
+3. **Capture PNGs** with whatever drives the browser here (the agent's browser tool, or Playwright
+   when the project has it). For each view, also capture a **plate**: the same view with the asset
+   out of shot or hidden, when the game allows it. The plate gives the silhouette ratio and an SSIM
+   on the object's own pixels.
+   - **Characters: freeze the pose.** Capture both sides in the bind pose, or with the clip
+     stopped at one keyframe time, so SSIM scores textures and geometry, not where the animation
+     happened to be. Check the pose on its own: the world positions of a few bones or grip points
+     at two or three keyframe times must match. The default keeps every key (the croc rider's
+     bones matched to 0.1 mm); `--resample=on` moved its hands by up to 1.2 mm, which alone
+     dropped its face view at 1 m to 0.962 object SSIM.
+4. **Measure the noise floor:** capture the original twice and compare the two. A difference smaller
+   than that is not caused by the asset. SR's floor was 0.967–0.970 SSIM on a chase camera and
+   0.986–0.989 on a still sky.
+5. **Views:**
+   - the closest distance a player can reach, which is the one that fails;
+   - the usual gameplay distance;
+   - for props, three azimuths;
+   - for characters, the gameplay camera and the closest menu or select-screen view.
+   - If the game has golden and dark or storm lighting, capture both: baked AO and dropped ORM
+     maps show up in dark scenes.
+6. **Viewports:** a desktop one (1920×1080 or 2560×1440) and a phone one (e.g. 1688×780
+   landscape or 390×844 portrait). Distant props also shrink on a phone, which hides more.
+7. **Score each view** with the shipped script, on a crop around the asset:
+
+   ```sh
+   A=.agents/skills/optimizing-assets/scripts/ab-compare.mjs
+   node $A orig.png orig-again.png --crop=640,300,700,480                  # the noise floor
+   node $A orig.png new.png --crop=640,300,700,480 --plate=plate.png --sheet=ab-close.png
+   ```
+
+   It prints luma SSIM on the crop (and on the object with `--plate`), the mean-luminance ratio,
+   the silhouette ratio (with `--plate`) and the share of changed pixels; `--json` for a table.
+   PNG needs nothing installed. Targets SR used, and the number each one reads:
+   - characters: `SSIM (luma, object)` 0.985 on desktop and 0.975 on phones, and `SSIM (luma,
+     crop)` 0.992 or more with no `--crop` (the whole frame);
+   - distant props: `luminance ratio` 0.96–1.10 in every lighting, and `silhouette ratio`
+     0.99–1.01 on the brightest capture, or on a mask capture (the asset unlit white on black,
+     `--threshold=128`). In a dark or storm capture, dark parts of the object barely clear the
+     plate, so the ratio counts shading: ab-compare prints `low contrast` there. SR's beacon read
+     0.89 and 1.01 in storm light with an outline that a mask capture put at 0.999;
+   - hero props: `SSIM (luma, object)` 0.984 or more at the closest approach.
+8. **Look at the sheets** (original | candidate | difference ×4, at 100%) yourself for seams,
+   banding, blotches, facets or a changed silhouette. Then show them to the creator: the look is
+   their call, and "no visible difference at race distance" is the verdict to ask for.
+9. **After the swap,** capture the same views again without the preview module and compare them
+   with the original captures. That proves the game now loads what you tested. Keep captures lean:
+   PNG crops, not full-resolution sets, and delete what you no longer need.
+
+## When it fails
+
+- For a character, first rule out the pose: score a frozen pose and compare bone positions (step 3
+  above). A pose shift fails the gate with every texture untouched.
+- Change **one** variable and rebuild. Order of likelihood: a bigger texture edge on the slot that
+  shows the defect; a different format (UASTC instead of ETC1S for chroma blotches, JPEG 4:4:4
+  instead of lossy WebP for normal maps); a smaller simplification error; `--normals=exact`; the
+  next closer class.
+- If the closer class passes, ship that. A smaller download that the creator notices is a worse
+  game, not an optimization.
+- Record what failed and the numbers in the asset's work directory, so the next agent does not
+  repeat it.

package/assets/optimizing-assets/scripts/ab-compare.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/*
+ * ab-compare.mjs: the optimizing-assets skill's A/B numbers. It compares two captures of the same
+ * view (the original asset and the candidate) and prints what verification.md gates on: luma SSIM,
+ * the mean-luminance ratio and, given a capture of the view without the asset, the silhouette
+ * ratio and SSIM on the object alone. It also writes a sheet to look at: original | candidate |
+ * difference x4, at 100%. It warns when the object barely stands out from the plate (a dark or
+ * storm capture), because the silhouette ratio then counts shading rather than the outline.
+ *
+ *   node ab-compare.mjs <original.png> <candidate.png> [--crop=x,y,w,h] [--plate=<no-asset.png>]
+ *                       [--threshold=<1-255>] [--sheet=<out.png>] [--json]
+ *
+ * PNG needs nothing installed (Node's zlib), so it runs on any machine; other formats are read
+ * with sharp from the shared tools when they are there. It captures nothing: take the screenshots
+ * with the browser tooling you have, same camera, same viewport, quality tier pinned. Run it on two
+ * captures of the ORIGINAL first: that SSIM is the noise floor, and a candidate difference smaller
+ * than it is not caused by the asset.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { pathToFileURL } from 'node:url';
+
+const HELP = `ab-compare.mjs: A/B numbers for two captures of the same view
+
+  node ab-compare.mjs <original.png> <candidate.png> [options]
+
+  --crop=x,y,w,h      compare only this rectangle (the asset and a margin), in pixels
+  --plate=<png>       the same view without the asset: adds the silhouette ratio and SSIM on the
+                      object's pixels, and takes the luminance ratio over those pixels
+  --threshold=<n>     how far (0-255, any channel) a pixel must differ from the plate to count as
+                      the object (default 16)
+  --sheet=<png>       write original | candidate | difference x4 of the crop, at 100%
+  --json              print the numbers as JSON`;
+
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const hit = argv.find((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+  return hit === undefined ? undefined : hit.includes('=') ? hit.slice(hit.indexOf('=') + 1) : true;
+};
+const die = (msg) => { console.error(`ab-compare: ${msg}`); process.exit(2); };
+if (flag('help') || argv.length === 0) { console.log(HELP); process.exit(0); }
+const [origFile, candFile] = argv.filter((a) => !a.startsWith('--'));
+if (!origFile || !candFile) die('usage: ab-compare.mjs <original.png> <candidate.png> [--crop=x,y,w,h] [--plate=<png>] [--sheet=<png>]  (--help)');
+
+const orig = await readImage(origFile), cand = await readImage(candFile);
+const plate = typeof flag('plate') === 'string' ? await readImage(flag('plate')) : null;
+for (const [f, im] of [[candFile, cand], ...(plate ? [[flag('plate'), plate]] : [])]) {
+  if (im.w !== orig.w || im.h !== orig.h) die(`${f} is ${im.w}x${im.h} but ${origFile} is ${orig.w}x${orig.h}: capture both at the same viewport`);
+}
+const crop = typeof flag('crop') === 'string' ? flag('crop').split(',').map(Number) : [0, 0, orig.w, orig.h];
+if (crop.length !== 4 || crop.some((v) => !Number.isInteger(v) || v < 0) || crop[2] < 1 || crop[3] < 1 || crop[0] + crop[2] > orig.w || crop[1] + crop[3] > orig.h) {
+  die(`--crop=${flag('crop')} must be x,y,w,h inside the ${orig.w}x${orig.h} capture`);
+}
+const threshold = flag('threshold') === undefined ? 16 : Number(flag('threshold'));
+/**
+ * Object pixels that clear the threshold by little (twice it, at most 32 more) barely count. Above
+ * this share of them the silhouette ratio is flagged: SR's beacon at 40 m had 2-3% in golden light
+ * and 69-79% in storm light, where its silhouette ratio read 0.89 and 1.01 for an unchanged outline.
+ */
+const LOW_CONTRAST = 0.1;
+const nearLimit = threshold + Math.min(threshold, 32);
+if (!(threshold >= 1 && threshold <= 255)) die('--threshold must be 1-255');
+
+const [cx, cy, cw, ch] = crop;
+const luma = (im) => {
+  const y = new Float32Array(cw * ch);
+  for (let j = 0; j < ch; j++) for (let i = 0; i < cw; i++) {
+    const p = ((cy + j) * im.w + cx + i) * 4;
+    y[j * cw + i] = 0.2126 * im.px[p] + 0.7152 * im.px[p + 1] + 0.0722 * im.px[p + 2];
+  }
+  return y;
+};
+const maxDiff = (a, b, k) => {   // largest channel difference at crop pixel k
+  const p = ((cy + Math.floor(k / cw)) * a.w + cx + (k % cw)) * 4;
+  return Math.max(Math.abs(a.px[p] - b.px[p]), Math.abs(a.px[p + 1] - b.px[p + 1]), Math.abs(a.px[p + 2] - b.px[p + 2]));
+};
+const n = cw * ch;
+const [yo, yc] = [luma(orig), luma(cand)];
+const map = ssimMap(yo, yc, cw, ch);
+const border = cw >= 32 && ch >= 32 ? 5 : 0;
+const inner = (k) => { const x = k % cw, y = Math.floor(k / cw); return x >= border && y >= border && x < cw - border && y < ch - border; };
+const mean = (arr, pick) => { let s = 0, c = 0; for (let k = 0; k < n; k++) if (pick(k)) { s += arr[k]; c++; } return c ? s / c : NaN; };
+
+const result = { original: origFile, candidate: candFile, crop: { x: cx, y: cy, w: cw, h: ch }, ssim: +mean(map, inner).toFixed(4) };
+let object = () => true;
+if (plate) {
+  const inO = new Uint8Array(n), inC = new Uint8Array(n);
+  for (let k = 0; k < n; k++) { inO[k] = maxDiff(orig, plate, k) > threshold ? 1 : 0; inC[k] = maxDiff(cand, plate, k) > threshold ? 1 : 0; }
+  const count = (m) => m.reduce((s, v) => s + v, 0);
+  if (!count(inO)) die(`no pixel of ${origFile} differs from the plate by more than ${threshold}: is the asset in the crop?`);
+  object = (k) => inO[k] || inC[k];
+  result.objectPixels = count(inO);
+  result.silhouetteRatio = +(count(inC) / count(inO)).toFixed(4);
+  result.objectSsim = +mean(map, (k) => object(k) && inner(k)).toFixed(4);
+  // In a dark capture, dark parts of the object clear the plate by little, so shading decides
+  // whether they count as object: the silhouette ratio then measures shading, not the outline.
+  let near = 0;
+  for (let k = 0; k < n; k++) if (inO[k] && maxDiff(orig, plate, k) <= nearLimit) near++;
+  result.lowContrast = +(near / result.objectPixels).toFixed(4);
+  if (result.lowContrast > LOW_CONTRAST) {
+    result.warning = `low contrast: ${(result.lowContrast * 100).toFixed(0)}% of the object's pixels differ from the plate by ${nearLimit} or less, `
+      + 'so the silhouette ratio is unreliable here. Gate the silhouette on the brightest capture, or on a mask capture (unlit white on black)';
+  }
+}
+result.luminanceRatio = +(mean(yc, object) / mean(yo, object)).toFixed(4);
+let changed = 0, worst = 0;
+for (let k = 0; k < n; k++) { const d = maxDiff(orig, cand, k); if (d > 8) changed++; worst = Math.max(worst, d); }
+result.changedPixels = +(changed / n).toFixed(4);
+result.maxChannelDifference = worst;
+if (typeof flag('sheet') === 'string') { writeSheet(flag('sheet')); result.sheet = flag('sheet'); }
+
+if (flag('json')) console.log(JSON.stringify(result, null, 1));
+else {
+  const line = (label, value, why = '') => console.log(`  ${label.padEnd(22)} ${String(value).padEnd(10)} ${why}`);
+  console.log(`${origFile} vs ${candFile}, crop ${cx},${cy} ${cw}x${ch}`);
+  line('SSIM (luma, crop)', result.ssim);
+  if (plate) line('SSIM (luma, object)', result.objectSsim, `${result.objectPixels} object pixels`);
+  line('luminance ratio', result.luminanceRatio, plate ? 'candidate / original, object pixels' : 'candidate / original, whole crop');
+  if (plate) line('silhouette ratio', result.silhouetteRatio, 'candidate / original object pixels');
+  if (plate) line('low contrast', `${(result.lowContrast * 100).toFixed(1)}%`, `object pixels within ${nearLimit} of the plate`);
+  line('changed pixels', `${(result.changedPixels * 100).toFixed(1)}%`, `a channel off by more than 8; largest ${worst}`);
+  if (result.sheet) line('sheet', result.sheet, 'original | candidate | difference x4');
+  if (result.warning) console.log(`  warning: ${result.warning}`);
+}
+
+// ---------------------------------------------------------------------------------------------- SSIM
+/** Per-pixel SSIM of two luma planes: 11x11 Gaussian window, sigma 1.5, K1 0.01, K2 0.03 (Wang et al. 2004). */
+function ssimMap(a, b, w, h) {
+  const g = Array.from({ length: 11 }, (_, i) => Math.exp(-((i - 5) ** 2) / (2 * 1.5 * 1.5)));
+  const gs = g.reduce((s, v) => s + v, 0);
+  const k = g.map((v) => v / gs);
+  const blur = (src) => {
+    const tmp = new Float32Array(w * h), dst = new Float32Array(w * h);
+    for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+      let s = 0; for (let i = -5; i <= 5; i++) s += k[i + 5] * src[y * w + Math.min(w - 1, Math.max(0, x + i))];
+      tmp[y * w + x] = s;
+    }
+    for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+      let s = 0; for (let i = -5; i <= 5; i++) s += k[i + 5] * tmp[Math.min(h - 1, Math.max(0, y + i)) * w + x];
+      dst[y * w + x] = s;
+    }
+    return dst;
+  };
+  const prod = (p, q) => p.map((v, i) => v * q[i]);
+  const [ma, mb] = [blur(a), blur(b)];
+  const [saa, sbb, sab] = [blur(prod(a, a)), blur(prod(b, b)), blur(prod(a, b))];
+  const C1 = (0.01 * 255) ** 2, C2 = (0.03 * 255) ** 2;
+  const out = new Float32Array(w * h);
+  for (let i = 0; i < w * h; i++) {
+    const va = saa[i] - ma[i] * ma[i], vb = sbb[i] - mb[i] * mb[i], cov = sab[i] - ma[i] * mb[i];
+    out[i] = ((2 * ma[i] * mb[i] + C1) * (2 * cov + C2)) / ((ma[i] * ma[i] + mb[i] * mb[i] + C1) * (va + vb + C2));
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------------------------- images
+async function readImage(file) {
+  if (!fs.existsSync(file)) die(`no ${file}`);
+  const bytes = fs.readFileSync(file);
+  if (bytes.length > 8 && bytes.readUInt32BE(0) === 0x89504e47) return readPng(bytes, file);
+  const sharpPath = path.join(process.env.BM_TOOLS ?? path.join(os.homedir(), '.bitmagic/tools'), 'gltf/node_modules/sharp/dist/index.mjs');
+  if (!fs.existsSync(sharpPath)) die(`${file} is not a PNG; capture PNG, or install the shared tools (references/tools.md) to read other formats`);
+  const sharp = (await import(pathToFileURL(sharpPath).href)).default;
+  const { data, info } = await sharp(bytes).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  return { w: info.width, h: info.height, px: data };
+}
+
+/** A PNG decoded to RGBA8: every colour type and bit depth, not interlaced (browsers never write Adam7). */
+function readPng(b, file) {
+  let o = 8, w = 0, h = 0, depth = 8, type = 6, plte = null, trns = null;
+  const idat = [];
+  while (o + 8 <= b.length) {
+    const len = b.readUInt32BE(o), kind = b.toString('latin1', o + 4, o + 8), data = b.subarray(o + 8, o + 8 + len);
+    o += 12 + len;
+    if (kind === 'IHDR') {
+      [w, h, depth, type] = [data.readUInt32BE(0), data.readUInt32BE(4), data[8], data[9]];
+      if (data[12]) die(`${file} is an interlaced PNG; save it without interlacing`);
+    } else if (kind === 'PLTE') plte = data;
+    else if (kind === 'tRNS') trns = data;
+    else if (kind === 'IDAT') idat.push(data);
+    else if (kind === 'IEND') break;
+  }
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[type];
+  if (!channels || !w || !h) die(`${file}: unsupported or broken PNG`);
+  const stride = Math.ceil((w * channels * depth) / 8), bpp = Math.max(1, (channels * depth) >> 3);
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const lines = Buffer.alloc(stride * h);
+  for (let y = 0; y < h; y++) {
+    const filter = raw[y * (stride + 1)], line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    const cur = lines.subarray(y * stride, (y + 1) * stride), prev = y ? lines.subarray((y - 1) * stride, y * stride) : null;
+    for (let x = 0; x < stride; x++) {
+      const a = x >= bpp ? cur[x - bpp] : 0, up = prev ? prev[x] : 0, c = prev && x >= bpp ? prev[x - bpp] : 0;
+      const pa = Math.abs(up - c), pb = Math.abs(a - c), pc = Math.abs(a + up - 2 * c);
+      const pred = [0, a, up, (a + up) >> 1, pa <= pb && pa <= pc ? a : pb <= pc ? up : c][filter];
+      if (pred === undefined) die(`${file}: bad PNG filter ${filter}`);
+      cur[x] = (line[x] + pred) & 255;
+    }
+  }
+  const sample = (y, i) => {   // component i of a row, scaled to 8 bits
+    if (depth === 16) return lines[y * stride + i * 2];
+    if (depth === 8) return lines[y * stride + i];
+    const v = (lines[y * stride + ((i * depth) >> 3)] >> (8 - depth - ((i * depth) & 7))) & ((1 << depth) - 1);
+    return type === 3 ? v : Math.round((v * 255) / ((1 << depth) - 1));
+  };
+  const px = new Uint8Array(w * h * 4);
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+    const p = (y * w + x) * 4, s = x * channels;
+    if (type === 3) {
+      const i = sample(y, s);
+      px.set([plte[i * 3], plte[i * 3 + 1], plte[i * 3 + 2], trns && i < trns.length ? trns[i] : 255], p);
+    } else if (type === 0 || type === 4) {
+      const g = sample(y, s);
+      px.set([g, g, g, type === 4 ? sample(y, s + 1) : 255], p);
+    } else {
+      px.set([sample(y, s), sample(y, s + 1), sample(y, s + 2), type === 6 ? sample(y, s + 3) : 255], p);
+    }
+  }
+  return { w, h, px };
+}
+
+/** original | candidate | difference x4, over the crop, as an RGB PNG. */
+function writeSheet(file) {
+  const gap = 4, W = cw * 3 + gap * 2, rgb = Buffer.alloc(W * ch * 3, 96);
+  for (let j = 0; j < ch; j++) for (let i = 0; i < cw; i++) {
+    const p = ((cy + j) * orig.w + cx + i) * 4, q = (j * W + i) * 3;
+    for (let c = 0; c < 3; c++) {
+      rgb[q + c] = orig.px[p + c];
+      rgb[q + (cw + gap) * 3 + c] = cand.px[p + c];
+      rgb[q + (cw + gap) * 6 + c] = Math.min(255, Math.abs(orig.px[p + c] - cand.px[p + c]) * 4);
+    }
+  }
+  const row = W * 3, raw = Buffer.alloc((row + 1) * ch);
+  for (let j = 0; j < ch; j++) {   // filter 1 (Sub): each byte minus the one a pixel to its left
+    raw[j * (row + 1)] = 1;
+    for (let x = 0; x < row; x++) raw[j * (row + 1) + 1 + x] = (rgb[j * row + x] - (x >= 3 ? rgb[j * row + x - 3] : 0)) & 255;
+  }
+  const crcTable = Array.from({ length: 256 }, (_, c) => { for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; return c >>> 0; });
+  const crc = (buf) => { let c = 0xffffffff; for (const v of buf) c = crcTable[(c ^ v) & 255] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+  const chunk = (kind, data) => {
+    const body = Buffer.concat([Buffer.from(kind, 'latin1'), data]), head = Buffer.alloc(4), tail = Buffer.alloc(4);
+    head.writeUInt32BE(data.length); tail.writeUInt32BE(crc(body));
+    return Buffer.concat([head, body, tail]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(W, 0); ihdr.writeUInt32BE(ch, 4); ihdr[8] = 8; ihdr[9] = 2;
+  fs.writeFileSync(file, Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr), chunk('IDAT', zlib.deflateSync(raw, { level: 9 })), chunk('IEND', Buffer.alloc(0))]));
+}