chore(renderer): address gemini review on PR #24

Local gemini-review findings (off-PR):

- Extract Op/RecordingCtx/makeCtx into lib/canvas-recorder.ts; both
  box-drawing.test.ts and powerline.test.ts now consume the shared
  helper, dropping ~250 lines of duplicated mock-context scaffolding.
- Single `as unknown as` cast lives once inside makeRecordingCtx;
  test files import a value already typed as CanvasRenderingContext2D
  and pass it straight to draw functions, no per-test cast jump.
- Remove the closure allocated by withMirror() on every call to
  fillStadium/innerStrokeStadium/fillBisector — replaced with an
  inline `if (mirror) { save; ... }` guard around a no-allocation
  mirrorAroundCellCenter helper that just does the translate/scale.

Gemini-bot inline review on PR #24:

- demo/bin/render-test.ts:280 calculateDiffPercent now decodes both
  PNGs via fast-png (already a project dep) and compares RGBA
  pixel-by-pixel with a ±2/channel tolerance for AA jitter, instead
  of byte-comparing the compressed PNG buffers. Dimension mismatch
  reports 100% diff. Fixes the flakiness the bot flagged: PNG
  metadata or compression-level changes no longer count as visual
  regressions.

All 69 lib tests still pass; typecheck, fmt, lint clean (the two
pre-existing biome warnings in url-detection.test.ts are unchanged).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sauyon

demo/bin/render-test.ts

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { decode as decodePng } from 'fast-png';
 
 // Get script directory
 const __filename = fileURLToPath(import.meta.url);
@@ -250,33 +251,65 @@ async function main() {
   }
 }
 
+/** Per-channel tolerance for the pixel diff, in 8-bit units. Tuned to
+ * absorb the ~1-pixel anti-aliasing jitter we routinely see when the
+ * same canvas path is re-rasterized across different runs (different
+ * GPUs, headless-Chrome versions, OSes) while still catching real
+ * geometric regressions. */
+const PIXEL_DIFF_TOLERANCE = 2;
+
 /**
- * Calculate approximate difference percentage between two PNG buffers.
- * This is a simple comparison - for production you might want pixelmatch.
+ * Pixel-level visual diff between two PNG buffers.
+ *
+ * Both PNGs are decoded to raw RGBA via fast-png (already a project
+ * dependency — no extra `pixelmatch`/`pngjs` install needed), then
+ * compared pixel-by-pixel. A pixel counts as different if any RGBA
+ * channel differs by more than PIXEL_DIFF_TOLERANCE. The percentage
+ * returned is `(differing pixels / total pixels) * 100`.
+ *
+ * The previous implementation compared raw PNG byte buffers — that
+ * was flaky because PNG metadata, compression-level changes, and
+ * chunk reordering all produce different byte streams from visually
+ * identical images, and the byte-count delta has no relationship to
+ * the visual delta.
+ *
+ * A dimension mismatch is reported as 100% diff: the baseline and
+ * the current render disagree on canvas size, which is by definition
+ * a regression. (Returning a partial-pixel score would just hide
+ * the real problem.)
  */
 function calculateDiffPercent(buf1: Buffer, buf2: Buffer): number {
-  // Simple approach: compare decoded pixel data
-  // For a more accurate comparison, use a library like pixelmatch
-
-  // Quick heuristic based on buffer size difference and content
-  const sizeDiff = Math.abs(buf1.length - buf2.length);
-  const maxSize = Math.max(buf1.length, buf2.length);
-
-  if (sizeDiff > 0) {
-    // Different sizes means different images
-    return (sizeDiff / maxSize) * 100;
-  }
-
-  // Compare bytes
-  let diffBytes = 0;
-  const minLen = Math.min(buf1.length, buf2.length);
-  for (let i = 0; i < minLen; i++) {
-    if (buf1[i] !== buf2[i]) {
-      diffBytes++;
+  const a = decodePng(buf1);
+  const b = decodePng(buf2);
+
+  if (a.width !== b.width || a.height !== b.height) return 100;
+
+  // fast-png returns Uint8Array for 8-bit channels. Both should have
+  // the same channel layout (4 = RGBA, 3 = RGB) since they were
+  // rendered from the same source canvas, but we still index by
+  // pixel rather than by raw offset to stay robust to a layout
+  // mismatch in the (highly unusual) case where one side is RGB and
+  // the other is RGBA.
+  const channels = Math.min(a.channels, b.channels);
+  const aStride = a.channels;
+  const bStride = b.channels;
+  const totalPixels = a.width * a.height;
+
+  let diffPixels = 0;
+  for (let i = 0; i < totalPixels; i++) {
+    const ai = i * aStride;
+    const bi = i * bStride;
+    for (let c = 0; c < channels; c++) {
+      if (
+        Math.abs((a.data[ai + c] as number) - (b.data[bi + c] as number)) > PIXEL_DIFF_TOLERANCE
+      ) {
+        diffPixels++;
+        break;
+      }
     }
   }
 
-  return (diffBytes / maxSize) * 100;
+  return (diffPixels / totalPixels) * 100;
 }
 
 main().catch((e) => {

lib/box-drawing.test.ts

@@ -14,123 +14,7 @@
 
 import { describe, expect, test } from 'bun:test';
 import { drawBoxOrBlock, isBoxOrBlock } from './box-drawing';
-
-type Op =
-  | { kind: 'fillStyle'; v: string }
-  | { kind: 'strokeStyle'; v: string }
-  | { kind: 'lineWidth'; v: number }
-  | { kind: 'lineCap'; v: string }
-  | { kind: 'globalAlpha'; v: number }
-  | { kind: 'fillRect'; x: number; y: number; w: number; h: number }
-  | { kind: 'save' }
-  | { kind: 'restore' }
-  | { kind: 'beginPath' }
-  | { kind: 'moveTo'; x: number; y: number }
-  | { kind: 'lineTo'; x: number; y: number }
-  | {
-      kind: 'bezierCurveTo';
-      cp1x: number;
-      cp1y: number;
-      cp2x: number;
-      cp2y: number;
-      x: number;
-      y: number;
-    }
-  | { kind: 'stroke' }
-  | { kind: 'translate'; x: number; y: number };
-
-interface RecordingCtx {
-  ops: Op[];
-  // Mirrored from CanvasRenderingContext2D for type compat.
-  fillStyle: string;
-  strokeStyle: string;
-  lineWidth: number;
-  lineCap: string;
-  globalAlpha: number;
-  fillRect(x: number, y: number, w: number, h: number): void;
-  save(): void;
-  restore(): void;
-  beginPath(): void;
-  moveTo(x: number, y: number): void;
-  lineTo(x: number, y: number): void;
-  bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
-  stroke(): void;
-  translate(x: number, y: number): void;
-}
-
-function makeCtx(): RecordingCtx {
-  const ops: Op[] = [];
-  let fillStyleBacking = '#000';
-  let strokeStyleBacking = '#000';
-  let lineWidthBacking = 1;
-  let lineCapBacking = 'butt';
-  let globalAlphaBacking = 1;
-  return {
-    ops,
-    get fillStyle() {
-      return fillStyleBacking;
-    },
-    set fillStyle(v: string) {
-      fillStyleBacking = v;
-      ops.push({ kind: 'fillStyle', v });
-    },
-    get strokeStyle() {
-      return strokeStyleBacking;
-    },
-    set strokeStyle(v: string) {
-      strokeStyleBacking = v;
-      ops.push({ kind: 'strokeStyle', v });
-    },
-    get lineWidth() {
-      return lineWidthBacking;
-    },
-    set lineWidth(v: number) {
-      lineWidthBacking = v;
-      ops.push({ kind: 'lineWidth', v });
-    },
-    get lineCap() {
-      return lineCapBacking;
-    },
-    set lineCap(v: string) {
-      lineCapBacking = v;
-      ops.push({ kind: 'lineCap', v });
-    },
-    get globalAlpha() {
-      return globalAlphaBacking;
-    },
-    set globalAlpha(v: number) {
-      globalAlphaBacking = v;
-      ops.push({ kind: 'globalAlpha', v });
-    },
-    fillRect(x, y, w, h) {
-      ops.push({ kind: 'fillRect', x, y, w, h });
-    },
-    save() {
-      ops.push({ kind: 'save' });
-    },
-    restore() {
-      ops.push({ kind: 'restore' });
-    },
-    beginPath() {
-      ops.push({ kind: 'beginPath' });
-    },
-    moveTo(x, y) {
-      ops.push({ kind: 'moveTo', x, y });
-    },
-    lineTo(x, y) {
-      ops.push({ kind: 'lineTo', x, y });
-    },
-    bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) {
-      ops.push({ kind: 'bezierCurveTo', cp1x, cp1y, cp2x, cp2y, x, y });
-    },
-    stroke() {
-      ops.push({ kind: 'stroke' });
-    },
-    translate(x, y) {
-      ops.push({ kind: 'translate', x, y });
-    },
-  };
-}
+import { type RecordingOp, makeRecordingCtx } from './canvas-recorder';
 
 // Standard cell for tests: 10x20 with a 1px light stroke.
 const CW = 10;
@@ -139,21 +23,12 @@ const LT = 1;
 const COLOR = '#fff';
 
 function draw(cp: number, lightPx = LT) {
-  const ctx = makeCtx();
-  const handled = drawBoxOrBlock(
-    ctx as unknown as CanvasRenderingContext2D,
-    cp,
-    0,
-    0,
-    CW,
-    CH,
-    COLOR,
-    lightPx
-  );
+  const ctx = makeRecordingCtx();
+  const handled = drawBoxOrBlock(ctx, cp, 0, 0, CW, CH, COLOR, lightPx);
   return { ctx, handled };
 }
 
-function rectsOnly(ops: Op[]): { x: number; y: number; w: number; h: number }[] {
+function rectsOnly(ops: RecordingOp[]): { x: number; y: number; w: number; h: number }[] {
   return ops.flatMap((o) => (o.kind === 'fillRect' ? [{ x: o.x, y: o.y, w: o.w, h: o.h }] : []));
 }
 
@@ -486,9 +361,9 @@ describe('box-drawing', () => {
       // back to a LIGHT line regardless of dash weight (vlineMiddle/
       // hlineMiddle take .light), so a heavy dash at a tiny cell size
       // shouldn't suddenly turn into a heavy bar.
-      const ctx = makeCtx();
+      const ctx = makeRecordingCtx();
       drawBoxOrBlock(
-        ctx as unknown as CanvasRenderingContext2D,
+        ctx,
         0x2505, // ━━━ heavy triple dash
         0,
         0,