golden.c

Go to the documentation of this file.

/**
 * \file
 * \brief pico9918-core - byte-exact frame dumps, and the comparison against them
 *
 * Copyright (c) 2026 Troy Schrapel
 *
 * This code is licensed under the MIT license
 *
 * https://github.com/visrealm/pico9918-core
 *
 * Drives fixed register/VRAM scenes through the public bus API and captures
 * the indexed output of pico9918_scan_line() plus its returned status byte,
 * one golden file per scene, followed by a dump of the 64 live palette RAM
 * entries (read back through the public bus - see dumpPalette). Compare mode
 * recomputes every scene and diffs byte-for-byte against the committed
 * goldens.
 *
 * Each line also carries two post-palette digests, so the palette -> pixel
 * conversion in pico9918_palette.c is observable: see "Post-palette surfaces".
 *
 * Usage:
 *   golden_runner              compare against goldens (nonzero exit on FAIL)
 *   golden_runner --capture    rewrite the goldens
 *   golden_runner --data DIR   override the golden data directory
 *
 * All scene content is generated by a fixed-seed LCG - no rand(), no time.
 */
 
#include "pico9918.h"
 
/* The post-palette surfaces need the LUT and the expansion macro, which are
 * impl surface, not public API (see the "INTERIM PRIVILEGED SURFACE" note in
 * pico9918_priv.h). The harness is in-tree, so it takes the same view of
 * the library the firmware does. */
#include "impl/pico9918_priv.h"
 
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <string.h>
#include <stdbool.h>
 
#ifndef GOLDEN_DATA_DIR
#define GOLDEN_DATA_DIR "data"
#endif
 
#define GOLDEN_MAGIC        "TMSG"
#define GOLDEN_VERSION      3
#define GOLDEN_NAME_LEN     32
#define GOLDEN_BYTES_PER_LINE TMS9918_PIXELS_X  /* 256 indexed pixels */
#define GOLDEN_PAL_ENTRIES  64                  /* pram entries per scene */
#define GOLDEN_PAL_BYTES    (GOLDEN_PAL_ENTRIES * 2)
 
/* post-palette digests per line: host-native expansion, then Pico BGR16 */
#define GOLDEN_DIGESTS_PER_LINE 2
#define GOLDEN_DIGEST_BYTES (GOLDEN_DIGESTS_PER_LINE * 8)
 
/* PICO9918_SR0_5S / PICO9918_SR0_COLLISION come from pico9918.h. These two are
 * observations of what the library reported, not part of the reference model - the
 * model restates its own bits below and must keep doing so. */
 
/* Storage for the deterministic clock the golden build injects in place of the
 * library's wall clock. goldenClock.h is force-included into every TU of this
 * build (library and harness alike) and declares this extern plus the inline
 * tick that PICO9918_HOST_TIME_US() expands to; the single definition lives here,
 * in the harness, because the library must carry no test state. */
uint32_t goldenClockNow = 0;
 
/* ---------------------------------------------------------------------------
 * Deterministic pseudo-random source (numerical recipes LCG)
 * ------------------------------------------------------------------------- */
static uint32_t lcgState;
 
static void lcgSeed(uint32_t seed)
{
  lcgState = seed;
}
 
static uint8_t lcgByte(void)
{
  lcgState = lcgState * 1664525u + 1013904223u;
  return (uint8_t)(lcgState >> 24);
}
 
/* ---------------------------------------------------------------------------
 * Bus helpers - the exact write paths the firmware uses (two-stage writes to
 * the address port, data-port writes with auto-increment)
 * ------------------------------------------------------------------------- */
static void regWrite(uint8_t reg, uint8_t value)
{
  pico9918_write_addr(value);
  pico9918_write_addr(0x80 | reg);
}
 
static void vramSetWriteAddr(uint16_t addr)
{
  pico9918_write_addr(addr & 0xff);
  pico9918_write_addr(0x40 | ((addr >> 8) & 0x3f));
}
 
/* set a read address: bit 6 clear in the second stage triggers the
 * read-ahead fetch (and its address auto-increment) */
static void vramSetReadAddr(uint16_t addr)
{
  pico9918_write_addr(addr & 0xff);
  pico9918_write_addr((addr >> 8) & 0x3f);
}
 
static void vramFillLcg(uint16_t addr, int count)
{
  vramSetWriteAddr(addr);
  while (count--) pico9918_write_data(lcgByte());
}
 
static void vramFillByte(uint16_t addr, uint8_t value, int count)
{
  vramSetWriteAddr(addr);
  while (count--) pico9918_write_data(value);
}
 
static void vramWriteBytes(uint16_t addr, const uint8_t* bytes, int count)
{
  vramSetWriteAddr(addr);
  while (count--) pico9918_write_data(*bytes++);
}
 
/* real F18A unlock sequence: VR57 = 0x1c written twice */
static void unlockF18a(void)
{
  regWrite(57, 0x1c);
  regWrite(57, 0x1c);
}
 
/* write count palette entries through the data-port palette mode (VR47).
 * exercises the two-stage palette write path; palette values do not affect
 * the indexed scanline output but ARE captured by the per-scene pram dump. */
static void paletteWriteLcg(int count)
{
  regWrite(47, 0xc0); /* data port palette mode, auto-increment, index 0 */
  while (count--)
  {
    pico9918_write_data(lcgByte() & 0x0f); /* 0R */
    pico9918_write_data(lcgByte());        /* GB */
  }
  regWrite(47, 0x00); /* leave palette mode */
}
 
/* ---------------------------------------------------------------------------
 * Scene lifecycle
 * ------------------------------------------------------------------------- */
static void sceneBegin(void)
{
  pico9918_reset();
 
  /* pico9918_reset() resets the cached display mode to Graphics I, but the
   * cache is only re-read on a mode CHANGE seen by pico9918_scan_line. Nudge
   * the mode register through Graphics II and back so it is re-resolved against
   * the now-locked state, making every scene independent of the one before it. */
  regWrite(0, 0x02);
  pico9918_scan_line(0);
  regWrite(0, 0x00);
  pico9918_scan_line(0);
}
 
/* Read the 64 live palette RAM entries (128 bytes) out through the public
 * bus API.
 *
 * The library exposes no palette read function, and every CPU-side read path
 * (data port, pico9918_vram_value) masks addresses to the 16K window
 * (0x3fff), so palette RAM at internal address 0x5000 cannot be read
 * directly. It IS reachable through the bitmap layer: the BML fetch address
 * (VR32 << 6) + row * width is not masked to 16K, so a width-64 opaque 2bpp
 * BML with VR32 = 0xff fetches bytes 0x5000..0x503f on scanline 65 and
 * 0x5040..0x507f on scanline 66 - the live pram - and emits each byte as
 * four 2-bit pixels (MSBs first). With both tile layers and sprites disabled
 * the scanline output is a byte-exact public read-out of the palette.
 *
 * Runs AFTER the scene's lines have been captured (it reprograms registers).
 * Everything here is deterministic, and every scene starts from
 * sceneBegin()'s reset, so no state leaks into the next scene. */
static void dumpPalette(uint8_t out[GOLDEN_PAL_BYTES])
{
  unlockF18a();
  regWrite(0, 0x00);  /* Graphics I */
  regWrite(1, 0x40);  /* display on */
  regWrite(7, 0x00);
  regWrite(49, 0x00); /* T2 off, no ECM, no 30-row */
  regWrite(50, 0x10); /* tile layer 1 off */
  regWrite(51, 0x00); /* sprites to process: 0 */
  regWrite(31, 0x80); /* BML: enabled, opaque, 2bpp, palette bits 0 */
  regWrite(32, 0xff); /* BML fetch base 0x3fc0 */
  regWrite(33, 0x00); /* BML x = 0 */
  regWrite(34, 0x00); /* BML top = 0 */
  regWrite(35, 0x00); /* BML width = 64 bytes (256px, full line) */
  regWrite(36, 0xff); /* BML height = 255 */
 
  for (int line = 0; line < 2; ++line)
  {
    pico9918_scan_line((uint16_t)(65 + line));
    const uint8_t* probe = pico9918_line_source();
    uint8_t* dst = out + line * 64;
    for (int i = 0; i < 64; ++i)
    {
      const uint8_t* p = probe + i * 4;
      dst[i] = (uint8_t)((p[0] << 6) | (p[1] << 4) | (p[2] << 2) | p[3]);
    }
  }
}
 
/* ---------------------------------------------------------------------------
 * Post-palette surfaces (format v3)
 *
 * The indexed scanline output is palette-independent, so nothing above this point
 * can observe the palette -> pixel conversion the library owns
 * (pico9918_palette.c). Each line is therefore ALSO expanded through the library's
 * own path and digested:
 *
 *   surface 0 "lib"   pico9918_palette_regenerate() + PICO9918_EXPAND_INDEXED,
 *                     i.e. the library's own path. One pixel policy ships and it
 *                     is the platform default, so this surface is the pixel
 *                     stream the device emits.
 *                     On its own this is self-capture: it pins the library
 *                     against itself and proves little.
 *
 *   surface 1 "ref"   the SAME indexed bytes and the SAME pram, expanded by
 *                     picoReferenceExpand() below - an INDEPENDENT
 *                     reimplementation of the documented pack formula and LUT
 *                     classing, written from the prose spec and deliberately
 *                     NOT calling PICO9918_PIXEL_FROM_RGB12 or
 *                     PICO9918_EXPAND_INDEXED. This is the evidence that the
 *                     formula is right rather than merely stable.
 *
 * Both surfaces are stored as 64-bit FNV-1a digests rather than raw pixels:
 * raw would be 1 KB per line (~3.5 MB of committed binaries) for no extra
 * diagnostic power, since a digest mismatch is localised to the exact pixel
 * by re-scanning the two buffers in memory (see reportPostPalette).
 *
 * Cross-check: the two surfaces now share a format, so they are compared
 * value-for-value on every line, every scene - any divergence between the
 * library's expansion and the independent reference fails the run before the
 * digests are even consulted. Their digests are stored SEPARATELY all the
 * same, so a change that moved both in lockstep (an edit to the reference
 * included) still shows up as a golden diff.
 * ------------------------------------------------------------------------- */
 
/* 64-bit FNV-1a */
#define FNV64_OFFSET 0xcbf29ce484222325ull
#define FNV64_PRIME  0x00000100000001b3ull
 
static uint64_t fnv1a(const void* data, size_t len)
{
  const uint8_t* p = (const uint8_t*)data;
  uint64_t h = FNV64_OFFSET;
  while (len--)
  {
    h ^= *p++;
    h *= FNV64_PRIME;
  }
  return h;
}
 
/* Independent reference for the pixel pack.
 *
 * Deliberately NOT PICO9918_PIXEL_FROM_RGB12 - this is the documented formula
 * rewritten from its prose description, so that breaking the macro diverges
 * from this and is caught:
 *
 *   a pram entry is byte-swapped RGB444 (0xGB0R): bits 15-12 = green,
 *   11-8 = blue, 7-4 = alpha-or-zero, 3-0 = red. The transform clears bits 7-4
 *   (stripping the alpha the palette-reset path deposits there) and copies
 *   GREEN down into them; blue and red stay put. Output is BGR12 in the low 12
 *   bits, with a dead copy of green in 15-12.
 *
 * Verified exhaustively equal to PICO9918_PIXEL_FROM_RGB12 over all 65536 inputs.
 * The channel names in the table above are load-bearing: a cross-check written from
 * the same prose as the macro's own comment cannot catch a shared misreading of the
 * format. See platform/pico/platform_pico.h.
 *
 * Written as explicit nibble extraction and reassembly rather than as the
 * library's mask/shift pair, so the two share no algebra. */
static uint16_t refPixel(uint16_t pram)
{
  const unsigned g = (pram >> 12) & 0x0f;  /* green - also copied into bits 7-4 */
  const unsigned b = (pram >>  8) & 0x0f;  /* blue */
  const unsigned r = (pram      ) & 0x0f;  /* red */
  return (uint16_t)((g << 12) | (b << 8) | (g << 4) | r);
}
 
/* one line of each surface - the expansion emits two pixels per indexed byte */
#define POST_PAL_PIXELS (GOLDEN_BYTES_PER_LINE * 2)
 
static PICO9918_PIXEL_T libPixels[POST_PAL_PIXELS];
static uint16_t       refPixels[POST_PAL_PIXELS];
 
/* The two surfaces are compared value-for-value, so the library's pixel type
   must match the reference's. If the shipped policy drifts to a wider pixel this
   fires here instead of surfacing as thousands of confusing digest mismatches.
   The LUT type is asserted for the same reason - the expansion indexes it as
   packed pairs. */
_Static_assert(sizeof(PICO9918_PIXEL_T) == sizeof(uint16_t),
               "golden surfaces require the 16-bit Pico pixel policy");
_Static_assert(sizeof(PICO9918_PALETTE_LUT_T) == sizeof(uint32_t),
               "golden expansion requires a 32-bit packed-pair LUT");
 
/* The reference's own LUT, as a pixel PAIR per entry like the library's.
 *
 * Kept as persistent state rather than rebuilt per line because the library's
 * LUT is persistent: it is global, rebuilt only when the palette is dirty, and
 * each rebuild is PARTIAL - the doubled build writes entries 0..63 only, since
 * doubled modes never index above 63. Entries 64..255 therefore survive from
 * whichever paired build last ran, across scene boundaries. Modelling that
 * faithfully is the whole point: f18a-text80-attrs really does render its
 * first line through entries text80 left behind, and a reference that rebuilt
 * from scratch would disagree with a perfectly correct library.
 *
 * Zero-initialised, matching pico9918_init() zeroing pico9918_palette_lut. */
static uint32_t refLut[256];
 
/* Independent reference for the LUT build - the counterpart of
 * pico9918_palette_regenerate(), written from the documented behaviour:
 *
 *   DOUBLED  entries 0..63, each the pram entry's pixel repeated in both
 *            halves of the word.
 *   PAIRED   entries 0..15 doubled (an index < 16 still means one colour),
 *            then 16..255 where the byte is two 4-bit indexes: the high
 *            nibble's colour in the low half of the word, the low nibble's in
 *            the high half. Little-endian storage puts the low half at the
 *            lower address, so the HIGH nibble is the left-hand pixel.
 *
 * Deliberately does not share code with the library's version. */
static void refRegenerate(bool paired)
{
  const uint16_t* pram = tms9918->vram.map.pram;
 
  if (!paired)
  {
    for (int i = 0; i < 64; ++i)
    {
      const uint32_t px = refPixel(pram[i]);
      refLut[i] = px | (px << 16);
    }
    return;
  }
 
  uint16_t pal[16];
  for (int i = 0; i < 16; ++i)
  {
    pal[i] = refPixel(pram[i]);
    refLut[i] = (uint32_t)pal[i] | ((uint32_t)pal[i] << 16);
  }
  for (int j = 16; j < 256; ++j)
  {
    refLut[j] = ((uint32_t)pal[j & 0x0f] << 16) | pal[j >> 4];
  }
}
 
/* Independent reference for the expansion - the counterpart of
 * PICO9918_EXPAND_INDEXED. Unpacks each LUT word into its two pixels so the
 * digest covers the per-pixel STREAM, making the pair-packing trick something
 * the goldens verify rather than assume. */
static void refExpand(uint16_t* dst, const uint8_t* src, int n)
{
  for (int i = 0; i < n; ++i)
  {
    const uint32_t entry = refLut[src[i]];
    dst[i * 2 + 0] = (uint16_t)entry;
    dst[i * 2 + 1] = (uint16_t)(entry >> 16);
  }
}
 
/* Expand one captured line through both surfaces and digest them. */
static void expandLine(const uint8_t* indexed, uint64_t digests[GOLDEN_DIGESTS_PER_LINE])
{
  PICO9918_EXPAND_INDEXED(libPixels, indexed, GOLDEN_BYTES_PER_LINE, pico9918_palette_lut);
  refExpand(refPixels, indexed, GOLDEN_BYTES_PER_LINE);
 
  digests[0] = fnv1a(libPixels, sizeof(libPixels));
  digests[1] = fnv1a(refPixels, sizeof(refPixels));
}
 
/* First position where the library expansion and the independent reference
 * disagree, or -1. Both are BGR16 under the golden pixel policy, so this is a
 * direct value comparison - the strongest form of the cross-check. */
static int refDivergence(void)
{
  for (int i = 0; i < POST_PAL_PIXELS; ++i)
  {
    if (libPixels[i] != refPixels[i]) return i;
  }
  return -1;
}
 
/* ---------------------------------------------------------------------------
 * Scenes
 * ------------------------------------------------------------------------- */
 
/* standard Graphics I: LCG-filled tables, sprites from LCG attribute data */
static void sceneGraphicsI(void)
{
  lcgSeed(0x1001);
  vramFillLcg(0x0000, 0x4000);
  regWrite(0, 0x00);
  regWrite(1, 0xe0); /* 16K, display on, int enable */
  regWrite(2, 0x0e); /* name table    0x3800 */
  regWrite(3, 0x00); /* color table   0x0000 */
  regWrite(4, 0x04); /* pattern table 0x2000 */
  regWrite(5, 0x76); /* sprite attrs  0x3b00 */
  regWrite(6, 0x03); /* sprite patts  0x1800 */
  regWrite(7, 0xf9); /* white on light red - backdrop low nibble >= 8 pins
                        the full 4-bit backdrop colour mask */
}
 
/* standard Graphics II (bitmap): three pattern/color pages */
static void sceneGraphicsII(void)
{
  lcgSeed(0x2002);
  vramFillLcg(0x0000, 0x4000);
  regWrite(0, 0x02);
  regWrite(1, 0xe0);
  regWrite(2, 0x0e); /* name table    0x3800 */
  regWrite(3, 0xff); /* color table   0x2000, full name mask */
  regWrite(4, 0x03); /* pattern table 0x0000, all pages */
  regWrite(5, 0x76);
  regWrite(6, 0x03);
  regWrite(7, 0x01); /* bg black */
}
 
/* standard Text (40 column) */
static void sceneText(void)
{
  lcgSeed(0x3003);
  vramFillLcg(0x0000, 0x4000);
  regWrite(0, 0x00);
  regWrite(1, 0xd0); /* 16K, display on, text mode */
  regWrite(2, 0x00); /* name table    0x0000 */
  regWrite(4, 0x01); /* pattern table 0x0800 */
  regWrite(7, 0xf4); /* white on dark blue */
}
 
/* standard Multicolor */
static void sceneMulticolor(void)
{
  lcgSeed(0x4004);
  vramFillLcg(0x0000, 0x4000);
  regWrite(0, 0x00);
  regWrite(1, 0xe8); /* 16K, display on, multicolor */
  regWrite(2, 0x05); /* name table    0x1400 */
  regWrite(4, 0x01); /* pattern table 0x0800 */
  regWrite(5, 0x76);
  regWrite(6, 0x03);
  regWrite(7, 0x04);
}
 
/* TEXT80 (F18A 80-column), locked, two-tone path.
 * output packing is two 4-bit pixels per byte - part of the contract. */
static void sceneText80(void)
{
  lcgSeed(0x5005);
  vramFillLcg(0x0000, 0x4000);
  regWrite(0, 0x04); /* TEXT80 mode bit */
  regWrite(1, 0xd0);
  regWrite(2, 0x0c); /* name table 0x3000 (locked mask 0x0c) */
  regWrite(4, 0x01); /* pattern table 0x0800 */
  regWrite(7, 0xf4);
}
 
/* hand-placed standard sprites: five sprites on one row raise the
 * 5th-sprite status flag; an overlapping pair raises coincidence. */
static void sceneSpritesMax(void)
{
  static const uint8_t sat[] = {
    /*  y,    x, name, color */
    0x27, 0x00, 0x00, 0x02,  /* row 40: sprites 0..4              */
    0x27, 0x28, 0x00, 0x03,
    0x27, 0x50, 0x00, 0x04,
    0x27, 0x78, 0x00, 0x05,
    0x27, 0xa0, 0x00, 0x06,  /* 5th sprite on the line -> 5S flag */
    0x63, 0x64, 0x00, 0x08,  /* row 100: overlapping pair -> COL  */
    0x63, 0x68, 0x01, 0x09,  /* solid 100..107 vs half 104..107   */
    0xd0, 0x00, 0x00, 0x00   /* terminator */
  };
 
  vramFillByte(0x0000, 0x00, 0x4000);
  vramFillByte(0x1800, 0xff, 8);        /* sprite pattern 0: solid   */
  vramFillByte(0x1808, 0xf0, 8);        /* sprite pattern 1: half    */
  vramWriteBytes(0x3b00, sat, (int)sizeof(sat));
 
  regWrite(0, 0x00);
  regWrite(1, 0xe0); /* 8x8 sprites, no magnification */
  regWrite(2, 0x0e);
  regWrite(3, 0x00);
  regWrite(4, 0x04);
  regWrite(5, 0x76);
  regWrite(6, 0x03);
  regWrite(7, 0xf1); /* white on black */
}
 
/* F18A unlocked: ECM1 tiles + sprites, two tile layers, scroll registers,
 * 30-row mode (240 lines), scanline-sprite limit raised, 16px sprites */
static void sceneF18aUnlocked(void)
{
  lcgSeed(0x6006);
  vramFillLcg(0x0000, 0x4000);
  unlockF18a();
  paletteWriteLcg(64);
  regWrite(0, 0x00);
  regWrite(1, 0xe2);  /* display on, 16px sprites */
  regWrite(2, 0x0e);  /* T1 name  0x3800 */
  regWrite(3, 0x00);  /* T1 color 0x0000 */
  regWrite(4, 0x04);  /* pattern  0x2000 */
  regWrite(5, 0x76);  /* SAT      0x3b00 */
  regWrite(6, 0x03);  /* SPT      0x1800 */
  regWrite(7, 0xf4);
  regWrite(10, 0x08); /* T2 name  0x2000 */
  regWrite(11, 0x10); /* T2 color 0x0400 */
  regWrite(24, 0x16); /* palette selects: sprites 1, T2 1, T1 2 */
  regWrite(25, 0x0b); /* T2 h-scroll */
  regWrite(26, 0x07); /* T2 v-scroll */
  regWrite(27, 0x05); /* T1 h-scroll */
  regWrite(28, 0x03); /* T1 v-scroll */
  regWrite(29, 0x33); /* page-swap masks + horizontal page sizes */
  regWrite(30, 0x08); /* scanline sprites: 8 */
  regWrite(49, 0xd1); /* T2 on | 30-row | ECM1 tiles | ECM1 sprites */
  regWrite(51, 0x18); /* sprites to process: 24 */
}
 
/* F18A unlocked: ECM3 tiles + sprites, per-position attributes, opaque
 * fat-pixel bitmap layer */
static void sceneF18aEcm3Bml(void)
{
  lcgSeed(0x7007);
  vramFillLcg(0x0000, 0x4000);
  unlockF18a();
  regWrite(0, 0x00);
  regWrite(1, 0xe0);  /* display on, 8px sprites */
  regWrite(2, 0x0e);
  regWrite(3, 0x20);  /* color table 0x0800 */
  regWrite(4, 0x04);
  regWrite(5, 0x76);
  regWrite(6, 0x03);
  regWrite(7, 0x01);
  regWrite(31, 0x90); /* BML: enabled, opaque, fat 4bpp pixels */
  regWrite(32, 0x10); /* BML addr 0x0400 */
  regWrite(33, 0x18); /* BML x = 24 */
  regWrite(34, 0x14); /* BML top = 20 */
  regWrite(35, 0x80); /* BML width = 32 bytes (128px fat) */
  regWrite(36, 0x64); /* BML height = 100 */
  regWrite(49, 0x33); /* ECM3 tiles | ECM3 sprites */
  regWrite(50, 0x02); /* per-position tile attributes */
}
 
/* F18A unlocked: a bitmap layer the display wraps rather than crops. A full-width
 * opaque priority layer started mid-line puts its overrun back at column zero of the
 * same line, which is what makes VR33 a horizontal scroll, and covers the line so the
 * tile layers do not run. A row count reaching past the last scanline still stops. */
static void sceneF18aBmlWrap(void)
{
  lcgSeed(0x9009);
  vramFillLcg(0x0000, 0x4000);
  unlockF18a();
  regWrite(0, 0x02);  /* Graphics II */
  regWrite(1, 0xe0);  /* display on, 8px sprites */
  regWrite(2, 0x0e);
  regWrite(3, 0xff);  /* color table 0x2000 */
  regWrite(4, 0x03);  /* pattern table 0x0000 */
  regWrite(5, 0x76);
  regWrite(6, 0x03);
  regWrite(7, 0x01);
  regWrite(31, 0xc0); /* BML: enabled, priority, opaque, 2bpp */
  regWrite(32, 0x10); /* BML addr 0x0400 */
  regWrite(33, 0x28); /* BML x = 40, so the last 40 columns come back at column 0 */
  regWrite(34, 0x50); /* BML top = 80 */
  regWrite(35, 0x00); /* BML width = 64 bytes (256px, wider than the room left) */
  regWrite(36, 0xff); /* BML height = 255, past the last scanline */
  regWrite(49, 0x21); /* ECM2 tiles | ECM1 sprites */
  regWrite(51, 0x10); /* sprites to process: 16 */
}
 
/* F18A unlocked: a bitmap layer whose width is not a whole number of bytes. Four
 * pixels to a byte, so the stride rounds up and every row lands a byte further on
 * than a truncating divide would put it - the only case where the two differ, and
 * every other bitmap scene here is a multiple of four. */
static void sceneF18aBmlStride(void)
{
  lcgSeed(0xa00a);
  vramFillLcg(0x0000, 0x4000);
  unlockF18a();
  regWrite(0, 0x00);  /* Graphics I */
  regWrite(1, 0xe0);  /* display on, 8px sprites */
  regWrite(2, 0x0e);
  regWrite(3, 0x20);  /* color table 0x0800 */
  regWrite(4, 0x04);
  regWrite(5, 0x76);
  regWrite(6, 0x03);
  regWrite(7, 0x01);
  regWrite(31, 0xc0); /* BML: enabled, priority, opaque, 2bpp */
  regWrite(32, 0x10); /* BML addr 0x0400 */
  regWrite(33, 0x14); /* BML x = 20 */
  regWrite(34, 0x10); /* BML top = 16 */
  regWrite(35, 0x66); /* BML width = 102px, so 26 bytes a row and not 25 */
  regWrite(36, 0x80); /* BML height = 128 */
  regWrite(49, 0x00); /* T2 off, no ECM, no 30-row */
  regWrite(51, 0x08); /* sprites to process: 8 */
}
 
/* F18A unlocked TEXT80 with position-based attributes and a second tile
 * layer - exercises the packed two-pixels-per-byte layered path */
static void sceneF18aText80Attrs(void)
{
  lcgSeed(0x8008);
  vramFillLcg(0x0000, 0x4000);
  unlockF18a();
  regWrite(0, 0x04);  /* TEXT80 */
  regWrite(1, 0xd0);
  regWrite(2, 0x00);  /* T1 name  0x0000 */
  regWrite(3, 0x10);  /* T1 color 0x0400 */
  regWrite(4, 0x01);  /* pattern  0x0800 */
  regWrite(5, 0x76);
  regWrite(6, 0x03);
  regWrite(7, 0xf4);
  regWrite(10, 0x08); /* T2 name  0x2000 */
  regWrite(11, 0xa0); /* T2 color 0x2800 */
  regWrite(26, 0x04); /* T2 v-scroll */
  regWrite(28, 0x02); /* T1 v-scroll */
  regWrite(49, 0x80); /* T2 on */
  regWrite(50, 0x02); /* position-based attributes */
}
 
/* F18A unlocked, dense LCG VRAM fill with multiple features enabled - the
 * stand-in for "GPU output captured as static VRAM state" */
static void sceneF18aVramSnapshot(void)
{
  lcgSeed(0x9009);
  vramFillLcg(0x0000, 0x4000);
  unlockF18a();
  paletteWriteLcg(64);
  regWrite(0, 0x00);
  regWrite(1, 0xe3);  /* display on, 16px magnified sprites */
  regWrite(2, 0x0a);  /* T1 name  0x2800 */
  regWrite(3, 0x00);  /* T1 color 0x0000 */
  regWrite(4, 0x07);  /* pattern  0x3800 */
  regWrite(5, 0x60);  /* SAT      0x3000 */
  regWrite(6, 0x05);  /* SPT      0x2800 */
  regWrite(7, 0x04);
  regWrite(10, 0x04); /* T2 name  0x1000 */
  regWrite(11, 0x50); /* T2 color 0x1400 */
  regWrite(24, 0x09);
  regWrite(25, 0x21); /* T2 h-scroll */
  regWrite(26, 0x0d); /* T2 v-scroll */
  regWrite(27, 0x13); /* T1 h-scroll */
  regWrite(28, 0x09); /* T1 v-scroll */
  regWrite(29, 0x77); /* page swaps, page sizes, ECM plane offsets 0x400 */
  regWrite(31, 0xa5); /* BML: enabled, transparent, 2bpp, palette bits */
  regWrite(32, 0x28); /* BML addr 0x0a00 */
  regWrite(33, 0x64); /* BML x = 100 */
  regWrite(34, 0x00); /* BML top = 0 */
  regWrite(35, 0x40); /* BML width = 16 bytes (64px) */
  regWrite(36, 0xc0); /* BML height = 192 */
  regWrite(49, 0xa2); /* T2 on | ECM2 tiles | ECM2 sprites */
  regWrite(50, 0x02); /* per-position tile attributes */
}
 
/* F18A unlocked: BML priority (VR31 bit 0x40 write-mask) with a width-64
 * fully-opaque band - drives the fast path that pre-fills the row mask and
 * suppresses both tile layers - over ECM2 tiles with ECM1 sprites placed to
 * cross the band edges (sprites render below the bitmap stage's mask but
 * still overdraw its pixels) */
static void sceneF18aBmlPriority(void)
{
  static const uint8_t sat[] = {
    /*  y,    x, name, color */
    0x10, 0x20, 0x01, 0x06,  /* above the band                */
    0x2c, 0x10, 0x00, 0x03,  /* crosses the band top (48)     */
    0x50, 0x58, 0x04, 0x05,  /* fully inside the band         */
    0x6c, 0xa0, 0x08, 0x07,  /* crosses the band bottom (112) */
    0xd0, 0x00, 0x00, 0x00   /* terminator */
  };
 
  lcgSeed(0xb00b);
  vramFillLcg(0x0000, 0x4000);
  vramWriteBytes(0x3b00, sat, (int)sizeof(sat));
  unlockF18a();
  regWrite(0, 0x00);
  regWrite(1, 0xe0);  /* display on, 8px sprites */
  regWrite(2, 0x0e);  /* T1 name  0x3800 */
  regWrite(3, 0x08);  /* T1 color 0x0200 */
  regWrite(4, 0x04);  /* pattern  0x2000 */
  regWrite(5, 0x76);  /* SAT      0x3b00 */
  regWrite(6, 0x03);  /* SPT      0x1800 */
  regWrite(7, 0xf4);
  regWrite(31, 0xc0); /* BML: enabled, priority/write-mask, opaque, 2bpp */
  regWrite(32, 0x20); /* BML addr 0x0800 */
  regWrite(33, 0x00); /* BML x = 0 (width-64 rows cover the full line) */
  regWrite(34, 0x30); /* BML top = 48 */
  regWrite(35, 0x00); /* BML width = 64 bytes (256px opaque) */
  regWrite(36, 0x40); /* BML height = 64 */
  regWrite(49, 0x21); /* ECM2 tiles | ECM1 sprites */
}
 
/* F18A unlocked ECM0: standard-format tiles through the scrolled F18A tile
 * path (renderEcm0Tile) with h-scroll shift==2 alignment, non-ECM sprites
 * rendered below the tile layer including a colour-0 transparent sprite
 * (its pixels must be released from the sprite mask so tiles show through),
 * and ReadData/read-ahead traffic feeding the sprite attribute table so the
 * data-port read behaviour influences pixels */
static void sceneF18aEcm0(void)
{
  lcgSeed(0xc00c);
  vramFillLcg(0x0000, 0x4000);
  unlockF18a();
 
  /* data-port read traffic: read 12 bytes back via read-ahead auto-increment
   * plus one ReadDataNoInc, then build sprites 0-3 from the values - any
   * change in read semantics moves/recolours the sprites */
  uint8_t rd[13];
  vramSetReadAddr(0x2600);
  for (int i = 0; i < 12; ++i) rd[i] = pico9918_read_data();
  rd[12] = pico9918_read_data_no_inc();
 
  uint8_t sat[8 * 4];
  for (int i = 0; i < 4; ++i)
  {
    sat[i * 4 + 0] = (uint8_t)(0x08 + i * 0x28); /* y: spread down the frame */
    sat[i * 4 + 1] = rd[i * 3];                  /* x from read data         */
    sat[i * 4 + 2] = rd[i * 3 + 1];              /* name from read data      */
    sat[i * 4 + 3] = rd[i * 3 + 2] & 0x0f;       /* colour from read data    */
  }
  /* sprite 4: solid; sprite 5: colour-0 transparent overlapping sprite 4
   * (overlap raises COL; its non-overlapped pixels enter then leave the
   * sprite mask, so the tiles beneath must render); sprite 6: name comes
   * from the ReadDataNoInc value */
  static const uint8_t satTail[] = {
    0x50, 0x40, 0x00, 0x05,
    0x50, 0x44, 0x01, 0x00,
    0x78, 0x80, 0x00, 0x0b,
    0xd0, 0x00, 0x00, 0x00
  };
  memcpy(sat + 16, satTail, sizeof(satTail));
  sat[26] = rd[12];  /* sprite 6 name from ReadDataNoInc */
 
  vramFillByte(0x1800, 0xff, 16);         /* sprite patterns 0 and 1: solid */
  vramFillByte(0x0000, 0x53, 32);         /* tile colours: fg 5 on bg 3 - every
                                             tile pixel is drawn, so masked-off
                                             pixels are always visible */
  vramWriteBytes(0x3b00, sat, (int)sizeof(sat));
 
  regWrite(0, 0x00);
  regWrite(1, 0xe0);  /* display on, 8px sprites */
  regWrite(2, 0x0e);  /* T1 name  0x3800 */
  regWrite(3, 0x00);  /* T1 color 0x0000 */
  regWrite(4, 0x04);  /* pattern  0x2000 */
  regWrite(5, 0x76);  /* SAT      0x3b00 */
  regWrite(6, 0x03);  /* SPT      0x1800 */
  regWrite(7, 0xf4);
  regWrite(27, 0x0a); /* T1 h-scroll: tile index 1, fine scroll 2 -> shift==2 */
  regWrite(49, 0x00); /* ECM0 tiles, non-ECM sprites */
}
 
/* F18A unlocked Graphics II: R0 GII bit set while unlocked takes the unlocked
 * Graphics-I path with the bitmap fetch paged (sprites, then the bitmap layer).
 * 16px sprites plus a transparent 2bpp BML window. */
static void sceneF18aGfx2(void)
{
  static const uint8_t sat[] = {
    /*  y,    x, name, color */
    0x20, 0x30, 0x00, 0x07,
    0x50, 0x80, 0x04, 0x0b,  /* inside the BML window */
    0x60, 0x40, 0x0c, 0x04,
    0x85, 0xc8, 0x08, 0x0d,  /* clips the right edge */
    0xd0, 0x00, 0x00, 0x00   /* terminator */
  };
 
  lcgSeed(0xd00d);
  vramFillLcg(0x0000, 0x4000);
  vramWriteBytes(0x3b00, sat, (int)sizeof(sat));
  unlockF18a();
  paletteWriteLcg(32);  /* rewrite half the palette - the pram dump pins it */
  regWrite(0, 0x02);  /* Graphics II while unlocked */
  regWrite(1, 0xe2);  /* display on, 16px sprites */
  regWrite(2, 0x0e);  /* name table  0x3800 */
  regWrite(3, 0xff);  /* color table 0x2000, full name mask */
  regWrite(4, 0x03);  /* pattern table 0x0000, all pages */
  regWrite(5, 0x76);  /* SAT 0x3b00 */
  regWrite(6, 0x03);  /* SPT 0x1800 */
  regWrite(7, 0xf1);
  regWrite(24, 0x02); /* T1 palette select 2 (GII applies it to tile colours) */
  regWrite(31, 0xa0); /* BML: enabled, transparent, 2bpp */
  regWrite(32, 0x30); /* BML addr 0x0c00 */
  regWrite(33, 0x40); /* BML x = 64 */
  regWrite(34, 0x20); /* BML top = 32 */
  regWrite(35, 0x40); /* BML width = 16 bytes (64px) */
  regWrite(36, 0x80); /* BML height = 128 */
}
 
/* raw-reset: pins the current post-reset contract. The scene itself
 * establishes a fully deterministic unlocked+configured state (VRAM, palette,
 * registers) and commits the unlocked mode by rendering a throwaway line,
 * then calls pico9918_reset() through the public API. The captured lines
 * are rendered WITHOUT the mode nudge sceneBegin() applies, so whatever the
 * reset path leaves behind (display off, backdrop 0, default palette, stale
 * cached mode) is golden-file contract - independent of scene order. */
static void sceneRawReset(void)
{
  lcgSeed(0xe00e);
  vramFillLcg(0x0000, 0x4000);
  unlockF18a();
  paletteWriteLcg(64);
  regWrite(0, 0x00);
  regWrite(1, 0xe0);
  regWrite(2, 0x0e);
  regWrite(7, 0x1f);
  regWrite(49, 0x11); /* ECM1 tiles | ECM1 sprites */
  pico9918_scan_line(0); /* commit the unlocked Graphics-I mode */
  pico9918_reset();
}
 
typedef struct
{
  const char* name;
  int lines;
  void (*setup)(void);
} Scene;
 
static const Scene scenes[] = {
  { "graphics-i",         192, sceneGraphicsI       },
  { "graphics-ii",        192, sceneGraphicsII      },
  { "text",               192, sceneText            },
  { "multicolor",         192, sceneMulticolor      },
  { "text80",             192, sceneText80          },
  { "sprites-max",        192, sceneSpritesMax      },
  { "f18a-unlocked",      240, sceneF18aUnlocked    },
  { "f18a-ecm3-bml",      192, sceneF18aEcm3Bml     },
  { "f18a-text80-attrs",  192, sceneF18aText80Attrs },
  { "f18a-vram-snapshot", 192, sceneF18aVramSnapshot},
  { "f18a-bml-priority",  192, sceneF18aBmlPriority },
  { "f18a-bml-wrap",      192, sceneF18aBmlWrap     },
  { "f18a-bml-stride",    192, sceneF18aBmlStride   },
  { "f18a-ecm0",          192, sceneF18aEcm0        },
  { "f18a-gfx2",          192, sceneF18aGfx2        },
  { "raw-reset",            8, sceneRawReset        },
};
 
#define SCENE_COUNT ((int)(sizeof(scenes) / sizeof(scenes[0])))
#define MAX_LINES 240
 
/* Rendered frame: per line, GOLDEN_BYTES_PER_LINE pixels copied out of the line
 * the library published, plus 1 status byte.
 *
 * No slack. A scrolled F18A tile layer renders in whole 32-bit quads, so the last
 * partial tile of a fine-h-scrolled line is written PAST pixel 255 - the
 * shifted-tile path reaches byte 263, exactly 8 - but that over-write now lands in
 * the library's own buffer, which is sized PICO9918_SCANLINE_BUFFER_SIZE for
 * it. Rows here are only ever the copy destination. */
static uint8_t frame[MAX_LINES][GOLDEN_BYTES_PER_LINE + 1];
 
/* per-scene palette RAM dump - 64 entries, 2 bytes each, little-endian */
static uint8_t palDump[GOLDEN_PAL_BYTES];
 
/* per-line post-palette digests (format v3) */
static uint64_t digests[MAX_LINES][GOLDEN_DIGESTS_PER_LINE];
 
/* first library-vs-reference disagreement: line and pixel, or -1 for none.
 * The two pixel values are latched at detection time - the shared expansion
 * buffers are overwritten by every later line. */
static int      refFailLine;
static int      refFailPixel;
static uint16_t refFailLib;
static uint16_t refFailRef;
 
static void renderScene(const Scene* scene, int* lines5s, int* linesCol)
{
  *lines5s = 0;
  *linesCol = 0;
  refFailLine = -1;
  refFailPixel = -1;
 
  sceneBegin();
  scene->setup();
 
  for (int y = 0; y < scene->lines; ++y)
  {
    uint8_t* pixels = frame[y];
    /* Rebuild the LUT exactly as the firmware's scanline path does - only when
     * the library reports it dirty, and BEFORE the line is rendered (the class
     * therefore comes from the mode cached by the PREVIOUS line's render).
     *
     * This is what makes palDirty observable: a palette write that fails to
     * raise the flag leaves a stale LUT, and every following line expands
     * through it. The reference LUT is rebuilt in lockstep, off the same
     * dirty decision, so only the CONTENT of the two builds is being compared
     * and not their scheduling. */
    if (pico9918_palette_dirty())
    {
      const bool paired = pico9918_display_mode(PICO9918_INST_ONLY) == TMS_MODE_TEXT80 &&
                          pico9918_line_bytes(PICO9918_INST_ONLY) == TMS9918_PIXELS_X;
      pico9918_palette_regenerate();
      refRegenerate(paired);
    }
 
    uint8_t status = pico9918_scan_line((uint16_t)y);
    memcpy(pixels, pico9918_line_source(), GOLDEN_BYTES_PER_LINE);
    pixels[GOLDEN_BYTES_PER_LINE] = status;
    if (status & PICO9918_SR0_5S) ++*lines5s;
    if (status & PICO9918_SR0_COLLISION) ++*linesCol;
 
    expandLine(pixels, digests[y]);
 
    if (refFailLine < 0)
    {
      const int bad = refDivergence();
      if (bad >= 0)
      {
        refFailLine = y;
        refFailPixel = bad;
        refFailLib = (uint16_t)libPixels[bad];
        refFailRef = refPixels[bad];
      }
    }
  }
 
  /* after the frame: read the live palette back out (reprograms registers,
   * so it must come last) */
  dumpPalette(palDump);
}
 
/* ---------------------------------------------------------------------------
 * Golden file I/O
 *
 * layout (all integers little-endian uint32):
 *   char[4]  magic "TMSG"
 *   u32      version (3)
 *   char[32] scene name, zero padded
 *   u32      line count
 *   u32      bytes per line (256)
 *   u32      status bytes per line (1)
 *   u32      palette entries (64)
 *   u32      post-palette digests per line (2)
 *   then per line: 256 indexed pixel bytes + 1 status byte
 *   then per line: 2 uint64 little-endian digests - [0] the library's BGR16
 *         expansion, [1] the independent reference's (see "Post-palette
 *         surfaces")
 *   then: 64 palette RAM entries, uint16 little-endian each (low byte 0R,
 *         high byte GB - raw pram memory order)
 *
 * A file whose header does not match is rejected rather than read.
 * ------------------------------------------------------------------------- */
static void putU32(FILE* f, uint32_t v)
{
  uint8_t b[4] = { (uint8_t)v, (uint8_t)(v >> 8), (uint8_t)(v >> 16), (uint8_t)(v >> 24) };
  fwrite(b, 1, 4, f);
}
 
static void putU64(FILE* f, uint64_t v)
{
  putU32(f, (uint32_t)v);
  putU32(f, (uint32_t)(v >> 32));
}
 
static bool getU32(FILE* f, uint32_t* v)
{
  uint8_t b[4];
  if (fread(b, 1, 4, f) != 4) return false;
  *v = (uint32_t)b[0] | ((uint32_t)b[1] << 8) | ((uint32_t)b[2] << 16) | ((uint32_t)b[3] << 24);
  return true;
}
 
static bool getU64(FILE* f, uint64_t* v)
{
  uint32_t lo, hi;
  if (!getU32(f, &lo)) return false;
  if (!getU32(f, &hi)) return false;
  *v = (uint64_t)lo | ((uint64_t)hi << 32);
  return true;
}
 
static void scenePath(char* buf, size_t bufLen, const char* dataDir, const char* name)
{
  snprintf(buf, bufLen, "%s/%s.golden", dataDir, name);
}
 
static bool captureScene(const Scene* scene, const char* dataDir)
{
  char path[512];
  scenePath(path, sizeof(path), dataDir, scene->name);
 
  int lines5s, linesCol;
  renderScene(scene, &lines5s, &linesCol);
 
  /* never capture a surface the independent reference disagrees with - that
   * would enshrine whichever side is wrong */
  if (refFailLine >= 0)
  {
    printf("[ERROR] %-19s library expansion diverges from the reference at "
           "line %d, pixel %d (lib 0x%04x, ref 0x%04x) - NOT captured\n",
      scene->name, refFailLine, refFailPixel, refFailLib, refFailRef);
    return false;
  }
 
  FILE* f = fopen(path, "wb");
  if (!f)
  {
    printf("[ERROR] %s: cannot open %s for writing\n", scene->name, path);
    return false;
  }
 
  char name[GOLDEN_NAME_LEN] = { 0 };
  strncpy(name, scene->name, GOLDEN_NAME_LEN - 1);
 
  fwrite(GOLDEN_MAGIC, 1, 4, f);
  putU32(f, GOLDEN_VERSION);
  fwrite(name, 1, GOLDEN_NAME_LEN, f);
  putU32(f, (uint32_t)scene->lines);
  putU32(f, GOLDEN_BYTES_PER_LINE);
  putU32(f, 1);
  putU32(f, GOLDEN_PAL_ENTRIES);
  putU32(f, GOLDEN_DIGESTS_PER_LINE);
  /* per line, not one bulk write - the rows carry trailing spill slack that is
   * not part of the format */
  for (int y = 0; y < scene->lines; ++y)
  {
    fwrite(frame[y], 1, GOLDEN_BYTES_PER_LINE + 1, f);
  }
  for (int y = 0; y < scene->lines; ++y)
  {
    for (int d = 0; d < GOLDEN_DIGESTS_PER_LINE; ++d) putU64(f, digests[y][d]);
  }
  fwrite(palDump, 1, GOLDEN_PAL_BYTES, f);
  fclose(f);
 
  printf("[CAPTURED] %-19s %3d lines (5S on %d lines, COL on %d lines) -> %s\n",
    scene->name, scene->lines, lines5s, linesCol, path);
  return true;
}
 
static bool compareScene(const Scene* scene, const char* dataDir)
{
  char path[512];
  scenePath(path, sizeof(path), dataDir, scene->name);
 
  FILE* f = fopen(path, "rb");
  if (!f)
  {
    printf("[FAIL] %-19s missing golden file %s (run with --capture first)\n",
      scene->name, path);
    return false;
  }
 
  char magic[4];
  uint32_t version = 0, lines = 0, bytesPerLine = 0, statusPerLine = 0, palEntries = 0;
  uint32_t digestsPerLine = 0;
  char name[GOLDEN_NAME_LEN];
 
  bool headerOk =
    fread(magic, 1, 4, f) == 4 && memcmp(magic, GOLDEN_MAGIC, 4) == 0 &&
    getU32(f, &version) && version == GOLDEN_VERSION &&
    fread(name, 1, GOLDEN_NAME_LEN, f) == GOLDEN_NAME_LEN &&
    getU32(f, &lines) &&
    getU32(f, &bytesPerLine) && bytesPerLine == GOLDEN_BYTES_PER_LINE &&
    getU32(f, &statusPerLine) && statusPerLine == 1 &&
    getU32(f, &palEntries) && palEntries == GOLDEN_PAL_ENTRIES &&
    getU32(f, &digestsPerLine) && digestsPerLine == GOLDEN_DIGESTS_PER_LINE;
 
  if (!headerOk || lines != (uint32_t)scene->lines)
  {
    printf("[FAIL] %-19s bad golden header in %s\n", scene->name, path);
    fclose(f);
    return false;
  }
 
  int lines5s, linesCol;
  renderScene(scene, &lines5s, &linesCol);
 
  static uint8_t expected[GOLDEN_BYTES_PER_LINE + 1];
  for (int y = 0; y < scene->lines; ++y)
  {
    if (fread(expected, 1, sizeof(expected), f) != sizeof(expected))
    {
      printf("[FAIL] %-19s truncated golden file at line %d\n", scene->name, y);
      fclose(f);
      return false;
    }
    if (memcmp(expected, frame[y], sizeof(expected)) != 0)
    {
      int i = 0;
      while (expected[i] == frame[y][i]) ++i;
      if (i == GOLDEN_BYTES_PER_LINE)
      {
        printf("[FAIL] %-19s first divergence: line %d status byte (expected 0x%02x, got 0x%02x)\n",
          scene->name, y, expected[i], frame[y][i]);
      }
      else
      {
        printf("[FAIL] %-19s first divergence: line %d, byte %d (expected 0x%02x, got 0x%02x)\n",
          scene->name, y, i, expected[i], frame[y][i]);
      }
      fclose(f);
      return false;
    }
  }
 
  /* post-palette digests. Report the library surface before the reference
   * surface: if both moved, the library changing is the interesting fact. */
  static const char* const surfaceName[GOLDEN_DIGESTS_PER_LINE] = { "library", "reference" };
  for (int y = 0; y < scene->lines; ++y)
  {
    for (int d = 0; d < GOLDEN_DIGESTS_PER_LINE; ++d)
    {
      uint64_t expectedDigest;
      if (!getU64(f, &expectedDigest))
      {
        printf("[FAIL] %-19s truncated golden file in digest block at line %d\n",
          scene->name, y);
        fclose(f);
        return false;
      }
      if (expectedDigest != digests[y][d])
      {
        printf("[FAIL] %-19s first divergence: line %d %s post-palette digest "
               "(expected 0x%016llx, got 0x%016llx)\n",
          scene->name, y, surfaceName[d],
          (unsigned long long)expectedDigest, (unsigned long long)digests[y][d]);
        fclose(f);
        return false;
      }
    }
  }
 
  /* the library and the reference agreeing is a stronger statement than either
   * matching its golden, so a disagreement is a failure even if both did */
  if (refFailLine >= 0)
  {
    printf("[FAIL] %-19s library expansion diverges from the reference at "
           "line %d, pixel %d (lib 0x%04x, ref 0x%04x)\n",
      scene->name, refFailLine, refFailPixel, refFailLib, refFailRef);
    fclose(f);
    return false;
  }
 
  static uint8_t expectedPal[GOLDEN_PAL_BYTES];
  if (fread(expectedPal, 1, sizeof(expectedPal), f) != sizeof(expectedPal))
  {
    printf("[FAIL] %-19s truncated golden file in palette block\n", scene->name);
    fclose(f);
    return false;
  }
  if (memcmp(expectedPal, palDump, sizeof(expectedPal)) != 0)
  {
    int i = 0;
    while (expectedPal[i] == palDump[i]) ++i;
    const int entry = i >> 1;
    printf("[FAIL] %-19s first divergence: palette entry %d (expected 0x%04x, got 0x%04x)\n",
      scene->name, entry,
      expectedPal[entry * 2] | (expectedPal[entry * 2 + 1] << 8),
      palDump[entry * 2] | (palDump[entry * 2 + 1] << 8));
    fclose(f);
    return false;
  }
 
  fclose(f);
  printf("[PASS] %-19s %3d lines\n", scene->name, scene->lines);
  return true;
}
 
/* ---------------------------------------------------------------------------
 * OVERLAY SURFACE (data/overlay.golden, its own format - OVERLAY_VERSION)
 *
 * The 14 scenes above render no overlay pixels, so without this the splash, the
 * diag panels and the banner would have no behaviour gate at all. The defect class
 * that matters here is a colour-literal conversion yielding an image that renders
 * ALMOST right - an alpha or green bleed into blue. An eyeball misses a one-nibble
 * shift; a digest does not.
 *
 * Shape, deliberately the same as the post-palette surfaces above: the library's
 * own render path, plus an INDEPENDENT reference written from the documented
 * behaviour and sharing no code with the library, compared value-for-value on
 * every pixel of every row, and digested per row with FNV-1a.
 *
 * Separate artifact, not a new per-scene block: the existing 14 goldens and
 * GOLDEN_VERSION 3 stay untouched, so this lands without recapturing anything.
 * The overlays are also not per-scene state - they are driven by frame counts and
 * push setters, not by the register/VRAM scenes.
 *
 * Three groups, in the priority order the work was scoped:
 *
 *   text    pico9918_diag_render_text - the highest-value target, because it is the
 *           ONE text path shared by the diag panels and the host's pending-display
 *           banner, and the banner calls it from the hot border path.
 *   splash  pico9918_splash_render - driven over a fixed frame range so the enter,
 *           hold, exit and reset positions are all pinned.
 *   panels  pico9918_diag_render - partial by necessity, see the panel note.
 * ------------------------------------------------------------------------- */
 
#include "overlay/diag.h"
#include "overlay/splash.h"
 
#define OVERLAY_MAGIC   "TMSO"
#define OVERLAY_VERSION 1
 
/* The overlay assets.
 *
 * The generated overlay/bmp_font.h and overlay/bmp_splash.h cannot simply be
 * included here: img2carray.py emits the dimensions as `const int splashWidth =
 * 176;` - file scope, external linkage, initialised - so a second TU including a
 * generated header is a duplicate-definition link error ("multiple definition of
 * splashWidth", verified with MinGW ld). Only the library TU that already
 * includes each header may define those objects.
 *
 * The arrays are therefore declared extern here, and the ASSET GEOMETRY the
 * reference needs is restated as harness constants. That is not a workaround so
 * much as the right dependency: the reference should take the asset BYTES, which
 * are the input under test, and not the library's own idea of how they are
 * shaped. To keep the restatement from going stale if an asset is ever resized,
 * the generated dimension MACROS are pulled in with the colliding const-int
 * definitions renamed aside, and static-asserted against. */
extern uint8_t font[];
extern uint8_t splash[];
extern PICO9918_PIXEL_T splash_pal[];
 
#define OVERLAY_FONT_WIDTH    768
#define OVERLAY_FONT_HEIGHT     6
#define OVERLAY_SPLASH_WIDTH  176
#define OVERLAY_SPLASH_HEIGHT  10
 
/* rename the generated const-int dimension objects aside so including the
 * headers here does not collide with the library's definitions, then check the
 * constants above against the generated macros. The renamed objects are unused
 * and the arrays re-declare identically to the externs above. */
#define fontWidth    goldenUnusedFontWidth
#define fontHeight   goldenUnusedFontHeight
#define splashWidth  goldenUnusedSplashWidth
#define splashHeight goldenUnusedSplashHeight
#include "overlay/bmp_font.h"
#include "overlay/bmp_splash.h"
#undef fontWidth
#undef fontHeight
#undef splashWidth
#undef splashHeight
 
_Static_assert(OVERLAY_FONT_WIDTH == FONT_WIDTH &&
               OVERLAY_FONT_HEIGHT == FONT_HEIGHT,
               "overlay font geometry has drifted from the generated asset");
_Static_assert(OVERLAY_SPLASH_WIDTH == SPLASH_WIDTH &&
               OVERLAY_SPLASH_HEIGHT == SPLASH_HEIGHT,
               "overlay splash geometry has drifted from the generated asset");
 
/* Overlay rendering needs a PIXEL buffer, not the indexed scanline buffer.
 *
 * 642 = RGB_PIXELS_X, the firmware's real buffer width (src/display.h: 640 plus
 * two guard pixels for PIO autopull). Matching it exactly is required, not
 * cosmetic, because the widest thing rendered here is addressed against it: the
 * banner's centring is `(RGB_PIXELS_X - len * PICO9918_DIAG_CHAR_WIDTH) / 2`
 * (src/renderer.c), so a different width moves every banner pixel, and the register panel
 * starts at `636 - PICO9918_DIAG_CHAR_WIDTH * 13` and runs to 636. The palette
 * strip reaches furthest: renderPalette writes 32-bit pairs at pair index 32 and
 * advances 16 per swatch for 16 swatches, so its last store lands on pair 287,
 * i.e. pixels 574..575. All inside 642. */
#define OVERLAY_PIXELS_X 642
 
static PICO9918_PIXEL_T ovLib[OVERLAY_PIXELS_X];
static PICO9918_PIXEL_T ovRef[OVERLAY_PIXELS_X];
 
/* Prefill, and it is load-bearing rather than hygiene.
 *
 * renderText does not paint a background: every non-glyph pixel goes through
 * darken(), which READS the framebuffer pixel already there and writes back a
 * dimmed version. With a zero buffer every darkened pixel is 0 and a broken
 * darken() is invisible. A non-trivial prefill makes the dim arithmetic
 * observable - so the mask in `(pixels[x] >> 2) & 0x333` is covered.
 *
 * The pattern is a fixed affine walk over 16 bits, not the LCG: the LCG is scene
 * content and is reseeded per scene, and this must not depend on scene order. */
#define OVERLAY_PREFILL_SEED 0xfedc
 
static void overlayPrefill(void)
{
  uint16_t v = OVERLAY_PREFILL_SEED;
  for (int i = 0; i < OVERLAY_PIXELS_X; ++i)
  {
    ovLib[i] = (PICO9918_PIXEL_T)v;
    ovRef[i] = (PICO9918_PIXEL_T)v;
    v = (uint16_t)(v * 2053u + 13849u);
  }
}
 
/* Restore [from, to) of one surface to the prefill, so a partial reference replay
 * rebuilds over the same input the library saw. Used by the panel group, where
 * only some column spans of a row are independently modelled. */
static void overlayRestorePrefill(PICO9918_PIXEL_T* dst, int from, int to)
{
  uint16_t v = OVERLAY_PREFILL_SEED;
  for (int i = 0; i < to; ++i)
  {
    if (i >= from) dst[i] = (PICO9918_PIXEL_T)v;
    v = (uint16_t)(v * 2053u + 13849u);
  }
}
 
/* Independent reference for darken().
 *
 * The library's darken() is documented pre-existing UB: `pixels[x++] =
 * (pixels[x] >> 2) & 0x333` modifies x and reads pixels[x] with no intervening
 * sequence point. Both compilers that matter resolve it the same way - ARM GCC
 * emits ldrh/strh at the SAME address (the port note in diag.c), and
 * MinGW GCC 15.2 at -O0 and -O2 likewise darkens in place. So the reference
 * models darken-IN-PLACE-then-advance, which is the behaviour that actually
 * ships.
 *
 * That choice also makes this surface a useful gate for the approved UB fix:
 * rewriting the library to `pixels[x] = (pixels[x] >> 2) & 0x333; return x + 1;`
 * is exactly this, so the fix must leave the overlay goldens UNCHANGED. A fix
 * that moved them would mean the accidental behaviour was not what was assumed.
 *
 * Written as an explicit shift-and-mask on a named temporary rather than as
 * PICO9918_PIXEL_DARKEN, so the policy macro is cross-checked rather than reused. */
static int refDarken(int x, PICO9918_PIXEL_T* pixels)
{
  const unsigned in = pixels[x];
  pixels[x] = (PICO9918_PIXEL_T)((in >> 2) & 0x333);
  return x + 1;
}
 
/* Independent reference for the font glyph fetch.
 *
 * The library indexes with `font[fontY * FONT_CHARS - FONT_FIRST]` biased once
 * outside the character loop, which is a fused expression whose correctness is
 * not obvious. Reimplemented here from the ASSET GEOMETRY instead, so a
 * mis-fused index diverges:
 *
 *   bmp_font.h says font.png is 768 x 6, 1bpp -> 96 bytes per image row, 6 rows.
 *   So one byte per character, 96 characters across, one image row per glyph
 *   row. A character maps to a column by subtracting 32 (space is column 0).
 *   The glyph is the byte's LOW PICO9918_DIAG_CHAR_WIDTH bits, bit 5 leftmost -
 *   which is what keeps every byte under 64 and the library's 64-entry mask
 *   table in range.
 *
 * Deliberately computes the row-bytes and column arithmetic separately rather
 * than reusing the library's pre-biased pointer, so an off-by-one bias or a
 * wrong row stride is visible. */
#define OVERLAY_FONT_ROW_BYTES (OVERLAY_FONT_WIDTH / 8)
 
static uint8_t refGlyphRowBits(char ch, int fy)
{
  const int col = (unsigned char)ch - 32;
  return font[fy * OVERLAY_FONT_ROW_BYTES + col];
}
 
/* Independent reference for pico9918_diag_render_text, from its documented
 * behaviour:
 *
 *   Row gate: fontY = scanline - y; outside 0..PICO9918_DIAG_CHAR_HEIGHT-1 nothing
 *   is written and x comes back unchanged (so a chained caller's layout does not
 *   shift on non-glyph rows).
 *   Then, per character, PICO9918_DIAG_CHAR_WIDTH pixels: `fg` where the glyph bit
 *   is set, darkened framebuffer where it is not. Returns x just past the last
 *   pixel written.
 *
 * The glyph walk is written one pixel at a time, as an explicit bit test at
 * position 5-i, rather than the library's masked word pairs, so a wrong walk
 * direction, a wrong advance or a mis-built mask table diverges. */
static int refRenderText(uint16_t scanline, const char* text, uint16_t x, uint16_t y,
                        PICO9918_PIXEL_T fg, PICO9918_PIXEL_T* pixels)
{
  const int fontY = (int)scanline - (int)y;
  if (fontY < 0 || fontY >= PICO9918_DIAG_CHAR_HEIGHT) return x;
 
  int xPos = x;
  for (const char* p = text; *p; ++p)
  {
    const uint8_t bits = refGlyphRowBits(*p, fontY);
    for (int i = 0; i < PICO9918_DIAG_CHAR_WIDTH; ++i)
    {
      if (bits & (uint8_t)(1u << (PICO9918_DIAG_CHAR_WIDTH - 1 - i))) pixels[xPos++] = fg;
      else xPos = refDarken(xPos, pixels);
    }
  }
  return xPos;
}
 
/* ---- splash reference -----------------------------------------------------
 *
 * Models the animation and the row gate from splash.c's documented
 * behaviour, including the DELIBERATE uint16 wraparound that IS the row gate
 * (see the comment there - it must be modelled, not "fixed"): logoOffset goes
 * negative, so for rows outside the band `y - (vBorder + vPixels + logoOffset)`
 * wraps to a large uint16 and the `< splashHeight` test is false.
 *
 * The unpack is written as a shift-then-mask (`(c >> (6 - px*2)) & 0x03`) rather
 * than the library's walking pixMask/offset pair, so a broken mask walk or a
 * reversed pixel order diverges.
 *
 * splash / splash_pal are the same generated asset bytes the library reads - the
 * asset is the input, not the thing under test. */
static int refLogoOffset;
static bool refCanHide;
 
/* SPLASH_START_POS is private to splash.c; recomputed here from the
 * documented frame constants and the asset height. */
#define OVERLAY_SPLASH_ENTER_FRAMES 60
#define OVERLAY_SPLASH_HOLD_FRAMES  180
#define OVERLAY_SPLASH_START_POS \
  (OVERLAY_SPLASH_ENTER_FRAMES + OVERLAY_SPLASH_HEIGHT + 2)
 
static void refSplashReset(void)
{
  refLogoOffset = OVERLAY_SPLASH_START_POS;
}
 
static void refSplashRender(uint16_t y, uint32_t frameCount, uint32_t vBorder,
                            uint32_t vPixels, uint32_t vVirtualPixels,
                            PICO9918_PIXEL_T* pixels)
{
  if (y == 0)
  {
    if (frameCount < OVERLAY_SPLASH_ENTER_FRAMES) --refLogoOffset;
    else if (refCanHide &&
             frameCount > (OVERLAY_SPLASH_ENTER_FRAMES + OVERLAY_SPLASH_HOLD_FRAMES))
      ++refLogoOffset;
  }
 
  if (y > vVirtualPixels) return;
 
  /* the intentional narrowing, spelled out */
  const uint16_t row =
    (uint16_t)(y - (uint16_t)(vBorder + vPixels + (uint32_t)refLogoOffset));
  if (row >= OVERLAY_SPLASH_HEIGHT) return;
 
  const int leftBorderPx = 4;
  const uint8_t* src = splash + (row * OVERLAY_SPLASH_WIDTH / 4);
  for (int x = 0; x < OVERLAY_SPLASH_WIDTH; x += 4)
  {
    const uint8_t c = *src++;
    for (int px = 0; px < 4; ++px)
    {
      const uint8_t palIndex = (uint8_t)((c >> (6 - px * 2)) & 0x03);
      if (palIndex) pixels[leftBorderPx + x + px] = splash_pal[palIndex];
    }
  }
}
 
/* ---- overlay row bookkeeping ---------------------------------------------- */
 
/* One digest per captured row, plus the value-for-value cross-check. Same
 * reasoning as the post-palette surfaces: raw pixels would be 1.2 KB per row for
 * no extra diagnostic power, since a mismatch is localised exactly by rescanning
 * the two buffers. */
/* Headroom over the current row count, not a snug fit. Exhausting this budget
 * TRUNCATES the surface, and because capture and compare truncate identically the
 * suite still reports PASS - a silent loss of coverage. Adding one panel case hit
 * exactly that. Raise this before adding cases rather than after. */
#define OVERLAY_MAX_ROWS 4096
 
static uint64_t overlayDigests[OVERLAY_MAX_ROWS][2];
static int      overlayRowCount;
 
/* first library-vs-reference disagreement, latched (the buffers are reused) */
static int      ovFailRow;
static int      ovFailPixel;
static uint16_t ovFailLib;
static uint16_t ovFailRef;
 
/* label for the failing row, so a divergence names the case rather than a row
 * index. Points at a string literal in the row-emitting code. */
static const char* ovRowLabel[OVERLAY_MAX_ROWS];
static const char* ovCurrentLabel = "";
 
static void overlayEmitRow(void)
{
  if (overlayRowCount >= OVERLAY_MAX_ROWS)
  {
    /* Abort rather than return. Truncating silently drops coverage while both
     * capture and compare truncate the same way, so the suite would keep saying
     * PASS with rows missing - the one failure mode a gate must never have. */
    printf("[ERROR] overlay: row budget %d exhausted - raise OVERLAY_MAX_ROWS\n",
           OVERLAY_MAX_ROWS);
    exit(2);
  }
 
  const int row = overlayRowCount++;
  ovRowLabel[row] = ovCurrentLabel;
  overlayDigests[row][0] = fnv1a(ovLib, sizeof(ovLib));
  overlayDigests[row][1] = fnv1a(ovRef, sizeof(ovRef));
 
  if (ovFailRow < 0)
  {
    for (int i = 0; i < OVERLAY_PIXELS_X; ++i)
    {
      if (ovLib[i] != ovRef[i])
      {
        ovFailRow = row;
        ovFailPixel = i;
        ovFailLib = (uint16_t)ovLib[i];
        ovFailRef = (uint16_t)ovRef[i];
        break;
      }
    }
  }
}
 
/* ---- the text group -------------------------------------------------------
 *
 * Every row of the glyph band plus one row either side of it, so the row gate's
 * boundaries are pinned in both directions - an off-by-one in
 * `fontY >= PICO9918_DIAG_CHAR_HEIGHT` shows up as a row that suddenly renders (or
 * stops rendering).
 *
 * The cases between them cover: the banner as the firmware really calls it
 * (both banner strings, centred by src/renderer.c's own formula, at its y of 8, in its
 * BANNER_FG); the panel colours labelColor / valueColor / unitsColor, which are
 * the literals the two colour-literal traps were found in; a chained run, which
 * is how every panel row is built and the only thing that catches a wrong x
 * advance; glyphs from all four rows of the font sheet, so a cell-row indexing
 * error cannot hide; and x positions at both ends of the buffer. */
 
/* src/renderer.c's own centring formula, kept textually so a change there is visible as
 * a golden diff here. RGB_PIXELS_X is host-side, hence OVERLAY_PIXELS_X. */
#define OVERLAY_CENTRE_X(text) \
  ((uint16_t)((OVERLAY_PIXELS_X - (sizeof(text) - 1) * PICO9918_DIAG_CHAR_WIDTH) / 2))
 
/* src/renderer.c's BANNER_FG, likewise: the masked white the banner really uses */
#define OVERLAY_BANNER_FG ((PICO9918_PIXEL_T)(PICO9918_PIXEL_FROM_RGB12(0xff0f) & 0x0fff))
 
/* the panel colours are exported by the diag TU (labelColor / valueColor /
 * unitsColor) but not declared in its header - they are read here rather than
 * recomputed, because the POINT is to pin the values the library actually holds.
 * A wrong literal in diag.c must move these digests. */
extern const PICO9918_PIXEL_T labelColor;
extern const PICO9918_PIXEL_T valueColor;
extern const PICO9918_PIXEL_T unitsColor;
 
/* one text case: render the same call into both surfaces for every row in
 * y-1 .. y+PICO9918_DIAG_CHAR_HEIGHT, digesting each row.
 *
 * The RETURNED x is folded into the row as well, at a pixel the call cannot
 * reach: a defect that shifted the whole run left by one AND changed the return
 * value in step would otherwise be invisible to a digest of the pixels alone.
 * OVERLAY_PIXELS_X-1 is past every case's rightmost write (the widest is the
 * palette strip at 575, the register panel ends at 636 and is not a text case). */
static void overlayTextCase(const char* label, const char* text, uint16_t x,
                            uint16_t y, PICO9918_PIXEL_T fg)
{
  ovCurrentLabel = label;
  for (int scanline = (int)y - 1; scanline <= (int)y + PICO9918_DIAG_CHAR_HEIGHT; ++scanline)
  {
    overlayPrefill();
 
    const int libX = pico9918_diag_render_text((uint16_t)scanline, text, x, y, fg, ovLib);
    const int refX = refRenderText((uint16_t)scanline, text, x, y, fg, ovRef);
 
    ovLib[OVERLAY_PIXELS_X - 1] = (PICO9918_PIXEL_T)libX;
    ovRef[OVERLAY_PIXELS_X - 1] = (PICO9918_PIXEL_T)refX;
 
    overlayEmitRow();
  }
}
 
static void overlayTextGroup(void)
{
  /* the two real banners, exactly as src/renderer.c renders them */
  overlayTextCase("banner-await-pc", "POWER CYCLE TO TEST NEW CONFIGURATION",
    OVERLAY_CENTRE_X("POWER CYCLE TO TEST NEW CONFIGURATION"), 8, OVERLAY_BANNER_FG);
  overlayTextCase("banner-await-ok", "OPEN CONFIGURATOR TO CONFIRM NEW SETTINGS",
    OVERLAY_CENTRE_X("OPEN CONFIGURATOR TO CONFIRM NEW SETTINGS"), 8, OVERLAY_BANNER_FG);
 
  /* the panel colours, on the panel labels they actually colour */
  overlayTextCase("label-color", "HWVER : ", 2, 0, labelColor);
  overlayTextCase("value-color", "1.0.2", 50, 0, valueColor);
  overlayTextCase("units-color", "MHZ", 80, 0, unitsColor);
 
  /* the whole printable range the sheet holds, in four runs of sixteen: codes
   * 32..47, 48..63, 64..79, 80..95. A column-bias error cannot render all four
   * correctly. */
  overlayTextCase("font-row0", " !\"#$%&'()*+,-./", 4, 0, labelColor);
  overlayTextCase("font-row1", "0123456789:;<=>?", 4, 0, labelColor);
  overlayTextCase("font-row2", "@ABCDEFGHIJKLMNO", 4, 0, labelColor);
  overlayTextCase("font-row3", "PQRSTUVWXYZ[\\]^_", 4, 0, labelColor);
 
  /* the register panel's own alphabet: nibbleBinStr uses '(' and ')' as the bit
   * glyphs and the row label is "R00:" through "R63:" */
  overlayTextCase("reg-glyphs", "R49:))((", 8, 0, valueColor);
 
  /* a chained run, three calls with three colours - how every panel row is
   * really built, and the only case that catches a wrong x advance */
  ovCurrentLabel = "chained-run";
  for (int scanline = -1; scanline <= PICO9918_DIAG_CHAR_HEIGHT; ++scanline)
  {
    overlayPrefill();
    int lx = 2, rx = 2;
    lx = pico9918_diag_render_text((uint16_t)scanline, "TEMP  : ", (uint16_t)lx, 0, labelColor, ovLib);
    lx = pico9918_diag_render_text((uint16_t)scanline, "42.75", (uint16_t)lx, 0, valueColor, ovLib);
    lx = pico9918_diag_render_text((uint16_t)scanline, "^C", (uint16_t)lx, 0, unitsColor, ovLib);
    rx = refRenderText((uint16_t)scanline, "TEMP  : ", (uint16_t)rx, 0, labelColor, ovRef);
    rx = refRenderText((uint16_t)scanline, "42.75", (uint16_t)rx, 0, valueColor, ovRef);
    rx = refRenderText((uint16_t)scanline, "^C", (uint16_t)rx, 0, unitsColor, ovRef);
    ovLib[OVERLAY_PIXELS_X - 1] = (PICO9918_PIXEL_T)lx;
    ovRef[OVERLAY_PIXELS_X - 1] = (PICO9918_PIXEL_T)rx;
    overlayEmitRow();
  }
 
  /* a non-zero y, so the row gate is not only ever exercised at y == 0 */
  overlayTextCase("y-offset", "OUTPUT: 480P @60", 2, 200, valueColor);
 
  /* single glyph at x == 0: the leading darken() writes pixel 0, so nothing
   * before the run is touched and the first-pixel boundary is pinned */
  overlayTextCase("x-zero", "8", 0, 0, valueColor);
}
 
/* ---- the splash group -----------------------------------------------------
 *
 * Driven over a fixed frame range so all three phases are pinned by position,
 * not by inspection: ENTER (logoOffset decrementing once per frame while
 * frameCount < 60), HOLD (stationary from 60 until AllowHide plus frameCount >
 * 240), and EXIT (incrementing again). Every frame's y == 0 call is made, since
 * that call IS the animation clock - skipping frames would desynchronise the
 * offset.
 *
 * Geometry is the shipping VGA 480p case: vVirtualPixels 240 (480 display rows
 * at vPixelScale 2), vPixels 192 (24 rows of 8), vBorder (240-192)/2 = 24. So
 * the logo band sits at 216 + logoOffset and enters the visible region as
 * logoOffset falls.
 *
 * Rows captured per sampled frame are the band and one row either side, which is
 * what pins the row gate: with the enter animation stopping at logoOffset 12 the
 * band is rows 228..237, and the wraparound gate means row 227 and row 238 must
 * render NOTHING. An off-by-one in the gate moves that boundary.
 * ------------------------------------------------------------------------- */
#define OVERLAY_SPLASH_VVIRT   240u
#define OVERLAY_SPLASH_VPIXELS 192u
#define OVERLAY_SPLASH_VBORDER ((OVERLAY_SPLASH_VVIRT - OVERLAY_SPLASH_VPIXELS) / 2u)
 
static void overlaySplashFrame(uint32_t frameCount, bool sample)
{
  /* y == 0 advances the animation on both sides; it is also a real row, but
   * row 0 is never in the band so nothing is drawn. */
  overlayPrefill();
  pico9918_splash_render(0, frameCount, OVERLAY_SPLASH_VBORDER, OVERLAY_SPLASH_VPIXELS,
                       OVERLAY_SPLASH_VVIRT, ovLib);
  refSplashRender(0, frameCount, OVERLAY_SPLASH_VBORDER, OVERLAY_SPLASH_VPIXELS,
                  OVERLAY_SPLASH_VVIRT, ovRef);
  if (sample) overlayEmitRow();
 
  if (!sample) return;
 
  /* the whole bottom border, so wherever the band currently is it is captured
   * along with the blank rows around it - no need to know logoOffset here, and
   * a gate that shifted the band by one row moves two digests */
  for (uint16_t y = (uint16_t)(OVERLAY_SPLASH_VBORDER + OVERLAY_SPLASH_VPIXELS);
       y <= OVERLAY_SPLASH_VVIRT; ++y)
  {
    overlayPrefill();
    pico9918_splash_render(y, frameCount, OVERLAY_SPLASH_VBORDER, OVERLAY_SPLASH_VPIXELS,
                         OVERLAY_SPLASH_VVIRT, ovLib);
    refSplashRender(y, frameCount, OVERLAY_SPLASH_VBORDER, OVERLAY_SPLASH_VPIXELS,
                    OVERLAY_SPLASH_VVIRT, ovRef);
    overlayEmitRow();
  }
}
 
static void overlaySplashGroup(void)
{
  pico9918_splash_reset();
  refSplashReset();
  refCanHide = false;
 
  /* ENTER: sample the first frame the band becomes visible and a few after.
   * The band is at 216 + logoOffset and the captured window is 216..240, so it
   * first intrudes when logoOffset <= 24, i.e. frameCount >= 48. */
  ovCurrentLabel = "splash-enter";
  for (uint32_t f = 0; f < OVERLAY_SPLASH_ENTER_FRAMES; ++f)
  {
    overlaySplashFrame(f, f >= 46 && f <= 50);
  }
 
  /* HOLD, part 1: AllowHide has NOT been called, so the offset must stay put.
   * This pins the AllowHide half of the exit condition. */
  ovCurrentLabel = "splash-hold";
  for (uint32_t f = OVERLAY_SPLASH_ENTER_FRAMES; f <= 199; ++f)
  {
    overlaySplashFrame(f, f == 60 || f == 199);
  }
 
  /* HOLD, part 2: allow the hide while still INSIDE the hold window, then sweep
   * across frame 240 (ENTER 60 + HOLD 180). The exit is gated on BOTH canHide and
   * frameCount > 240, and enabling hide only after the window had already elapsed
   * left the frame-count half completely unpinned - SPLASH_HOLD_FRAMES could be
   * set to 0 and the goldens still passed. Sampling
   * 239/240 (must be stationary) against 241/242 (must have moved) pins it. */
  pico9918_splash_allow_hide();
  refCanHide = true;
  for (uint32_t f = 200; f <= 245; ++f)
  {
    overlaySplashFrame(f, f == 239 || f == 240 || f == 241 || f == 242 || f == 245);
  }
 
  /* EXIT: frameCount is now well past the hold window, so the offset keeps
   * climbing by one per frame and the band walks back down out of the visible
   * region. */
  ovCurrentLabel = "splash-exit";
  /* the band starts at 216 + logoOffset and logoOffset is 12 here, so the band
   * walks out of the captured 216..240 window once logoOffset passes 24, i.e.
   * around frame 259. Sample the transit and the first frame past it; later
   * frames are all-blank rows that pin nothing the boundary rows do not. */
  for (uint32_t f = 246; f <= 275; ++f)
  {
    overlaySplashFrame(f, (f >= 246 && f <= 249) || (f >= 257 && f <= 261));
  }
 
  /* Reset mid-animation: the offset must jump back to the start position, so
   * the band leaves the visible region again. Pins pico9918_splash_reset(). */
  pico9918_splash_reset();
  refSplashReset();
  ovCurrentLabel = "splash-reset";
  overlaySplashFrame(276, true);
}
 
/* ---- the panel group ------------------------------------------------------
 *
 * Every PICO9918_CONF_DIAG_* panel: REGISTERS (both the locked 8-register form and the
 * unlocked extended one, which is the only path through extReg[]), ADDRESS, PALETTE and
 * PERFORMANCE. The performance panel is only repeatable because goldenClock.h replaces
 * PICO9918_HOST_TIME_US with a deterministic counter; a wall clock makes gpuPctStr and
 * the GPU row's glyphs change run to run.
 *
 * Two coverage limits, so nobody reads more into these rows than they pin:
 *
 *   the GPU% row  gpuTimeUs is structurally 0 here - only pico9918_gpu_loop feeds it and
 *                 this harness never runs it - so the row is pinned at 0.000 and its
 *                 divisor and *100 scale are NOT exercised. Placement and glyph plumbing
 *                 are gated; the arithmetic is not.
 *   uint2Str      covered only with PICO9918_DIAG_GPU_FRAME_COUNTER=ON, the GPU-frames
 *                 row being its only call site.
 *
 * The reference is deliberately not a reimplementation of the whole panel layout - that
 * would be a copy of pico9918_diag_render's control flow. Only the register panel and
 * the palette strip are replayed independently; the left panels' columns are seeded from
 * the library's own row and are covered by the golden digest alone. The modelled spans
 * are called out at the site.
 * ------------------------------------------------------------------------- */
 
/* Independent reference for the palette-strip swatch transform, from
 * renderPalette's documented behaviour: take the pram entry, keep 0xFF0F (drop
 * the alpha nibble), copy green (bits 15-12) down into bits 7-4, then mask to 12
 * bits. That trailing mask is what keeps the RP2040 CRT-dim path from bleeding
 * green into blue's MSB - the same trap as DIAG_COLOR's & 0x0fff.
 *
 * Written as nibble extraction and reassembly, like refPixel above, so it shares
 * no algebra with the library's mask/shift chain. */
static PICO9918_PIXEL_T refSwatch(uint16_t pram)
{
  const unsigned g = (pram >> 12) & 0x0f;
  const unsigned b = (pram >> 8) & 0x0f;
  const unsigned r = pram & 0x0f;
  return (PICO9918_PIXEL_T)((b << 8) | (g << 4) | r);
}
 
/* Replay of renderPalette's swatch geometry, from its documented behaviour: the
 * label at leftXPos on rows 0..5, and on rows 0..4 sixteen swatches starting at
 * pair index 32, each 15 pairs (30 pixels) wide followed by a one-pair gap. */
static void refPalettePanel(int y, uint32_t vVirtualPixels, PICO9918_PIXEL_T* pixels)
{
  const int row = y % 6;
  const uint8_t palette = (uint8_t)((y - ((int)vVirtualPixels - 24)) / 6);
  if (palette >= 4) return;
 
  char buf[] = "PALETTE 0:";
  buf[8] = (char)('0' + palette);
  refRenderText((uint16_t)row, buf, 2, 0, labelColor, pixels);
 
  if (row >= 5) return;
 
  int pair = 32;
  for (int c = 0; c < 16; ++c)
  {
    const PICO9918_PIXEL_T sw = refSwatch(tms9918->vram.map.pram[palette * 16 + c]);
    for (int i = 0; i < 30; ++i) pixels[pair * 2 + i] = sw;
    pair += 16;
  }
}
 
/* Replay of the register panel's composition, from pico9918_diag_render: label
 * "Rnn:" at 636 - 6*13, two darkened pad pixels, the high nibble as four bit
 * glyphs, two more pad pixels, the low nibble. nibbleBinStr maps a nibble to
 * "((((".."))))" with ')' for a set bit, MSB first. */
static void refRegisterPanel(int diagRow, int row, PICO9918_PIXEL_T* pixels)
{
  static const char* const bins[] = {
    "((((", "((()", "(()(", "(())",
    "()((", "()()", "())(", "()))",
    ")(((", ")(()", ")()(", ")())",
    "))((", "))()", ")))(", "))))",
  };
  const unsigned reg = (unsigned)diagRow;
  char buf[] = "R00:";
  buf[1] = (char)('0' + reg / 10u);
  buf[2] = (char)('0' + reg % 10u);
 
  int xPos = 636 - PICO9918_DIAG_CHAR_WIDTH * 13;
  xPos = refRenderText((uint16_t)row, buf, (uint16_t)xPos, 0, labelColor, pixels);
  if (row < 0 || row >= PICO9918_DIAG_CHAR_HEIGHT) return;
  const uint8_t value = (uint8_t)pico9918_reg_value((uint8_t)reg);
  xPos = refDarken(xPos, pixels);
  xPos = refDarken(xPos, pixels);
  xPos = refRenderText((uint16_t)row, bins[value >> 4], (uint16_t)xPos, 0, valueColor, pixels);
  xPos = refDarken(xPos, pixels);
  xPos = refDarken(xPos, pixels);
  refRenderText((uint16_t)row, bins[value & 0x0f], (uint16_t)xPos, 0, valueColor, pixels);
}
 
/* the config bytes the panels read. Written directly: the library exposes no
 * per-byte config setter. */
static void overlaySetConfig(uint8_t index, uint8_t value)
{
  tms9918->config[index] = value;
}
 
/* Prime every push setter with a fixed value. Without this the panel value
 * strings are whatever pico9918_diag_init() left (empty), and the panels render
 * label-only rows - a much weaker surface. No time, no rand: fixed constants
 * only, so the strings are byte-stable across runs.
 *
 * The performance values DO reach captured pixels: the injected clock
 * (goldenClock.h) makes PICO9918_CONF_DIAG_PERFORMANCE repeatable, the panel group
 * enables it, and flt2Str / uint2Str are covered through the render/frame-time, FPS,
 * GPU% and GPU-frames rows. The priming below is therefore load-bearing for those
 * rows, not just a way of keeping the diag module in one fixed state.
 *
 * Also reset here: the clock sequence itself, so a case's performance rows do not
 * depend on how many clock reads earlier cases made. Same reason the value strings
 * are primed - each case must be independent of scene order.
 *
 * THE ACCUMULATORS ARE THE OTHER CARRY-OVER, and they are the reason this function
 * ends with a discard update rather than just a push. pico9918_diag_init() does NOT
 * zero accumulatedRenderTime / accumulatedFrameTime / accumulatedScanlines /
 * lastUpdateTime - correctly so, since on target it runs once at boot when they are
 * already zero. But this harness re-primes the module once per panel case, and
 * the performance block CONSUMES those accumulators (it divides by
 * accumulatedScanlines, then zeroes all three, and stores lastUpdateTime). Left
 * alone, each case's first four performance rows would be a function of whatever
 * the previous case left behind - flaky in exactly the way that is worse than the
 * honest exclusion this step replaces.
 *
 * They are file statics of the diag TU with no public reset, so the harness brings
 * them to a known state through the public path instead of reaching in: one
 * throwaway push followed by one frame-0 update, which consumes and zeroes all
 * three and stamps lastUpdateTime from the freshly reset clock. Whatever the
 * history, the module is in the same state after this call. The real push follows,
 * so the captured rows are computed from it alone. */
static void overlayPrimeDiag(void)
{
  goldenClockReset();
  pico9918_diag_init();
  pico9918_diag_set_version_info("1.5", "1.0.2");
  pico9918_diag_set_output_name("480P ", "@60");
  /* 42.756, not 42.75, and the third decimal is the whole point.
     flt2Str rounds with `(uint32_t)(flt * 10^prec + 0.5f)`. The TEMP row uses
     prec 2, so 42.75 scales to exactly 4275.0 and truncation gives the same
     digits as rounding - deleting the `+ 0.5f` was NOT caught. Every
     other value primed here is exact too (0.300, 56.25, 0.000), so the rounding
     step had no covering input at all. 42.756 scales to 4275.6: rounds to 42.76,
     truncates to 42.75, so the row's last glyph changes. */
  pico9918_diag_set_temperature(42.756f);
  pico9918_diag_set_clock_hz(252000000.0f);
  pico9918_diag_set_frame_rate(60.0f);
  /* The frame module owns the dropped-frame and GPU-frame counters and the overlay
     reads them directly, so priming them means writing the globals - there is no
     setter. These reach real pixels through the FPS and GPU-frames rows.
 
     THE THREE VALUES MUST BE PAIRWISE DISTINCT, and that is the whole point of
     writing pico9918_frame_count here. capture-baselines.sh records two gate holes of
     the same shape: swapping the FPS row's read from pico9918_dropped_frames_count to
     pico9918_frame_count, and the GPU-frames row's read from pico9918_gpu_frame_count to
     pico9918_frame_count, are invisible to the asm gate because both are same-typed
     global reads that move only the literal-pool .word payload - which the
     normalizer blinds by design. The goldens close both holes ONLY if the wrong
     global yields a different NUMBER. pico9918_frame_count is otherwise whatever the
     scene's scanlines left it at, which is not a value this harness controls, and
     if it ever coincided with 1 the FPS swap would silently escape again - the
     same class of trap as the recorded "R3 = 0x00 absorbed the mutation".
 
     7 is chosen to differ from the dropped count (1) and the GPU count (12345),
     and to keep the swapped FPS figure well away from the correct one:
     correct   (16 - 1) * 3.75 = 56.25
     swapped   (16 - 7) * 3.75 = 33.75
     - a different digit in every position, so no rounding can absorb it. */
  pico9918_frame_count = 7;
  pico9918_dropped_frames_count = 1;
#if PICO9918_DIAG_GPU_FRAME_COUNTER
  pico9918_gpu_frame_count = 12345;
#endif
 
  /* Drain whatever a previous case accumulated, per the note above. Needs
     PICO9918_CONF_DIAG_PERFORMANCE already set to reach the consuming branch, which is why
     the caller sets the config bytes BEFORE calling this. accumulatedScanlines is
     made nonzero first so the drain itself cannot divide by zero.
 
     The clock is NOT re-reset after this: the drain leaves lastUpdateTime at the
     first tick of the reset sequence, and the real frame-0 update needs a LATER
     reading to make totalTime nonzero (the GPU% row divides by it). The sequence is
     deterministic from goldenClockReset() above, so both readings are fixed - the
     drain takes tick 0 and the real update takes tick 1, in every case. */
  pico9918_diag_update_render_time(0, 0);
  pico9918_diag_update(0);
 
  pico9918_diag_update_render_time(1200, 3400);
}
 
/* one panel configuration: set the config bytes, rebuild the row table, update
 * the values, then render the covered border rows. */
static void overlayPanelCase(const char* label, bool registers, bool address,
                             bool palette, bool unlocked, bool gfx2,
                             bool performance)
{
  /* deterministic VDP state for the panels to read - registers, the sprite
   * attribute table the address panel reports, and a full palette */
  sceneBegin();
  lcgSeed(0x0e11a7);
  vramFillLcg(0x0000, 0x4000);
  if (unlocked)
  {
    unlockF18a();
    paletteWriteLcg(64);
  }
 
  /* Set bits 7-4 of some pram low bytes, which paletteWriteLcg CANNOT do: it
   * writes the first byte as `lcgByte() & 0x0f`, mirroring the data port's own
   * `data & 0x0f` stage-0 mask, so that nibble is permanently zero through this
   * path. It is exactly the nibble renderPalette's `& 0xFF0F` exists to drop, so
   * with LCG data alone the mask is untestable - dropping it entirely left the
   * goldens passing.
   *
   * The nibble IS reachable on real hardware: pico9918_config.c stores
   * `__builtin_bswap16(rgb)` straight from two config bytes with NO mask, so a
   * configurator palette entry lands it in pram bits 7-4. Written here directly
   * for the same reason - going through the bus would re-apply the mask being
   * tested. Values chosen so each keeps bits in 7-4 AND differs in the low 12
   * bits the swatch actually shows. */
  if (palette)
  {
    tms9918->vram.map.pram[0]  = 0x3f70; /* G=3 B=f pad=7 R=0 */
    tms9918->vram.map.pram[5]  = 0xc59a; /* G=c B=5 pad=9 R=a */
    tms9918->vram.map.pram[17] = 0x08f3; /* G=0 B=8 pad=f R=3 */
    tms9918->vram.map.pram[33] = 0xfae1;
    tms9918->vram.map.pram[49] = 0x714c;
    tms9918->palDirty = 1;
  }
  /* Every register the address panel reports is given a value with bits set in
   * EVERY position that panel's mask keeps, so a wrong mask changes a glyph.
   * Zeros here silently absorb mask defects: with R3 = 0x00 the colour-table row
   * reads 0000 under any mask at all, and mutating that mask escaped the goldens
   * until these values were chosen deliberately. */
  /* R0 bit 1 selects Graphics II, which the address panel reports through
   * DIFFERENT masks (0x80 for the colour table, 0x04 for the pattern table). With
   * only Graphics I cases those arms were dead code and their mutations escaped,
   * while the comments below claimed the coverage.
   * The gfx2 case exists to take the other arm. */
  regWrite(0, gfx2 ? 0x02 : 0x00);
  regWrite(1, 0xe0);
  if (gfx2)
  {
    /* pico9918_display_mode() returns a CACHED mode that is only refreshed when
     * pico9918_scan_line observes a register change (same subtlety sceneBegin
     * documents). Writing R0 alone leaves the cache reading Graphics I, so the
     * panel would still take the locked arm and the mutation would still escape -
     * it did, on the first attempt at this case. One scanline commits the mode. */
    pico9918_scan_line(0);
  }
  regWrite(2, 0x0d); /* T1 name  - mask 0x0f, all four bits meaningful */
  /* R3/R4 need bits set in the positions a WIDENED mask would newly admit, not
   * just in the positions the correct mask keeps. 0xb7 and 0x05 satisfied the
   * locked masks but left bit 6 and bit 1 clear, so 0x80-vs-0xc0 and 0x04-vs-0x06
   * produced identical output and the Graphics II mutations escaped even once the
   * mode was right. Same trap as the R3=0x00 one recorded below, one level in. */
  regWrite(3, 0xf7); /* T1 color - mask 0xff locked, 0x80 in Graphics II */
  regWrite(4, 0x07); /* pattern  - mask 0x07 locked, 0x04 in Graphics II */
  regWrite(5, 0x76); /* SAT      - mask 0x7f */
  regWrite(6, 0x03); /* SPT      - mask 0x07 */
  regWrite(7, 0xf4);
  if (unlocked)
  {
    regWrite(24, 0x16);
    regWrite(27, 0x05);
    regWrite(49, 0x11);
    regWrite(51, 0x18);
  }
  /* latch the display mode the MODE row and the colour-table mask read - it is
   * a cached value refreshed inside pico9918_scan_line */
  pico9918_scan_line(0);
 
  overlaySetConfig(PICO9918_CONF_DIAG, 1);
  overlaySetConfig(PICO9918_CONF_DIAG_REGISTERS, registers);
  overlaySetConfig(PICO9918_CONF_DIAG_PERFORMANCE, performance);
  overlaySetConfig(PICO9918_CONF_DIAG_PALETTE, palette);
  overlaySetConfig(PICO9918_CONF_DIAG_ADDRESS, address);
 
  overlayPrimeDiag();
  pico9918_diag_config_updated();
  /* Fixed frame counts, and the VALUES matter.
   *
   * pico9918_diag_update recomputes each panel on a 4-frame cadence, and the three
   * panels sit on three different phases of it: the performance rows on 0, the
   * table addresses on 2, the FPS row on 3. No single call reaches all of them,
   * so a case updates three times - once per phase. All three calls are made
   * unconditionally rather than only when `performance` is set, so a case's input
   * does not depend on which panels it enables.
   *
   * The accumulators must be primed before the phase-0 call, which CONSUMES them
   * (it divides by accumulatedScanlines and then zeroes all three); the later two
   * phases do not touch them. */
  pico9918_diag_update_render_time(1200, 3400);
  pico9918_diag_update(0);
  pico9918_diag_update(2);
  pico9918_diag_update(3);
 
  ovCurrentLabel = label;
 
  /* The WHOLE frame, every border row, not a couple of sampled bands.
   *
   * The first version swept rows 1..48 plus the last 28, which looked like
   * enough - the left panel stack is 15 rows tall and the palette strip is at
   * the bottom. Mutation-testing found the hole: the extended-register dump runs
   * to panel row 227 (diagRow 37), so perturbing extReg[7] - which is diagRow 15,
   * i.e. rows 91..96 - changed nothing anyone could see. Sweeping the frame
   * closes that class of gap outright rather than one register at a time, and it
   * also removes the two-band special case, so the reference replay has exactly
   * one form. 240 rows per case is 4 KB of digests; the coverage is worth more
   * than the bytes. */
  for (uint16_t y = 1; y <= OVERLAY_SPLASH_VVIRT; ++y)
  {
    overlayPrefill();
    pico9918_diag_render(y, OVERLAY_SPLASH_VVIRT, ovLib);
 
    /* Reference: start from the library's row, then rebuild independently
     * whichever parts of the row ARE modelled - the palette strip and the
     * register panel. The left panels' text is built from the IntString value
     * plumbing and replaying it would be a copy of that plumbing rather than
     * independent evidence, so those columns stay as the library left them and
     * are covered by the digest alone (see the group note).
     *
     * The two modelled parts are rebuilt IN THE LIBRARY'S ORDER - palette strip,
     * then register panel - because their column spans OVERLAP. The strip's
     * sixteenth swatch runs to pixel 575 and the register panel starts at 558, so
     * whichever is drawn second wins those 18 pixels. Getting the order wrong was
     * caught by the value-for-value check at exactly that boundary (panel-all,
     * pixel 558). Each part is rebuilt over the prefill, i.e. over the same input
     * the library saw. */
    memcpy(ovRef, ovLib, sizeof(ovRef));
 
    const int panelY = (int)y - 1;
    const int diagRow = panelY / 6;
    const int row = panelY % 6;
    const int regPanelX = 636 - PICO9918_DIAG_CHAR_WIDTH * 13;
 
    /* the strip's own gate, from pico9918_diag_render: entered when the
     * border-adjusted row is past vVirtualPixels - 27, and renderPalette is
     * called with that row + 2 */
    const bool refStrip = palette && panelY > (int)OVERLAY_SPLASH_VVIRT - 27;
    if (refStrip)
    {
      overlayRestorePrefill(ovRef, 0, OVERLAY_PIXELS_X);
      refPalettePanel(panelY + 2, OVERLAY_SPLASH_VVIRT, ovRef);
    }
 
    if (registers)
    {
      int maxReg = 8;
      if (unlocked) maxReg += 30;  /* sizeof(extReg)/sizeof(int) */
      if (diagRow < maxReg)
      {
        static const int extRegRef[] = { 10, 11, 15, 19, 24, 25, 26, 27,
                                         28, 29, 30, 31, 32, 33, 34, 35,
                                         36, 37, 38, 48, 49, 50, 51, 54, 55,
                                         56, 57, 58, 59, 63 };
        const int reg = (diagRow >= 8) ? extRegRef[diagRow - 8] : diagRow;
        /* only restore the panel's own span when the strip did not just draw
           into it - the register panel legitimately darkens over strip pixels */
        if (!refStrip) overlayRestorePrefill(ovRef, regPanelX, OVERLAY_PIXELS_X);
        refRegisterPanel(reg, row, ovRef);
      }
    }
 
    overlayEmitRow();
  }
}
 
static void overlayPanelGroup(void)
{
  overlayPanelCase("panel-registers", true, false, false, false, false, false);
  overlayPanelCase("panel-registers-unlocked", true, false, false, true, false, false);
  overlayPanelCase("panel-address", false, true, false, false, false, false);
  overlayPanelCase("panel-palette", false, false, true, true, false, false);
  overlayPanelCase("panel-all", true, true, true, true, false, false);
  /* Graphics II: takes the other arm of the address panel's colour-table and
   * pattern-table mask selection, which no other case reaches. */
  overlayPanelCase("panel-address-gfx2", false, true, false, false, true, false);
 
  /* The PERFORMANCE panel. Reachable only because goldenClock.h supplies a
   * deterministic counter in place of the wall clock this block reads: that is what
   * makes these rows byte-stable and the value plumbing behind them - flt2Str,
   * uint2Str and the unitsColor call site - testable at all. Every row in
   * performanceDiags[] is rendered here: HWVER, FWVER, CLOCK,
   * OUTPUT, FRAME, FPS, GPU, GPU FR (when compiled in) and TEMP.
   *
   * Two cases, and the second is not redundant. Performance alone pins the block
   * in isolation; performance WITH the address panel is what pins the two groups'
   * differing phases (`frameCount & 3` against `++frameCount & 3`) against each
   * other, so a change that merged them or shifted either cadence moves a
   * digest. That interaction is the subtlety the update-call note describes, and
   * it had no covering case at all. */
  overlayPanelCase("panel-performance", false, false, false, false, false, true);
  overlayPanelCase("panel-performance-address", false, true, false, true, false, true);
}
 
/* ---- overlay artifact I/O ------------------------------------------------- */
static void overlayRender(void)
{
  overlayRowCount = 0;
  ovFailRow = -1;
  ovFailPixel = -1;
 
  /* builds the glyph mask table, which the text and splash groups render through
     before the panel group primes the module for its own reasons */
  pico9918_diag_init();
 
  overlayTextGroup();
  overlaySplashGroup();
  overlayPanelGroup();
}
 
static bool overlayCapture(const char* dataDir)
{
  overlayRender();
 
  if (ovFailRow >= 0)
  {
    printf("[ERROR] overlay             library diverges from the reference at "
           "row %d (%s), pixel %d (lib 0x%04x, ref 0x%04x) - NOT captured\n",
      ovFailRow, ovRowLabel[ovFailRow], ovFailPixel, ovFailLib, ovFailRef);
    return false;
  }
 
  char path[512];
  snprintf(path, sizeof(path), "%s/overlay.golden", dataDir);
  FILE* f = fopen(path, "wb");
  if (!f)
  {
    printf("[ERROR] overlay: cannot open %s for writing\n", path);
    return false;
  }
 
  fwrite(OVERLAY_MAGIC, 1, 4, f);
  putU32(f, OVERLAY_VERSION);
  putU32(f, (uint32_t)overlayRowCount);
  putU32(f, OVERLAY_PIXELS_X);
  putU32(f, 2);  /* digests per row: library, reference */
  for (int r = 0; r < overlayRowCount; ++r)
  {
    putU64(f, overlayDigests[r][0]);
    putU64(f, overlayDigests[r][1]);
  }
  fclose(f);
 
  printf("[CAPTURED] %-19s %3d rows -> %s\n", "overlay", overlayRowCount, path);
  return true;
}
 
static bool overlayCompare(const char* dataDir)
{
  char path[512];
  snprintf(path, sizeof(path), "%s/overlay.golden", dataDir);
  FILE* f = fopen(path, "rb");
  if (!f)
  {
    printf("[FAIL] %-19s missing golden file %s (run with --capture first)\n",
      "overlay", path);
    return false;
  }
 
  char magic[4];
  uint32_t version = 0, rows = 0, width = 0, perRow = 0;
  const bool headerOk =
    fread(magic, 1, 4, f) == 4 && memcmp(magic, OVERLAY_MAGIC, 4) == 0 &&
    getU32(f, &version) && version == OVERLAY_VERSION &&
    getU32(f, &rows) &&
    getU32(f, &width) && width == OVERLAY_PIXELS_X &&
    getU32(f, &perRow) && perRow == 2;
  if (!headerOk)
  {
    printf("[FAIL] %-19s bad golden header in %s\n", "overlay", path);
    fclose(f);
    return false;
  }
 
  overlayRender();
 
  if (rows != (uint32_t)overlayRowCount)
  {
    printf("[FAIL] %-19s row count changed (golden %u, got %d)\n",
      "overlay", rows, overlayRowCount);
    fclose(f);
    return false;
  }
 
  static const char* const surface[2] = { "library", "reference" };
  for (int r = 0; r < overlayRowCount; ++r)
  {
    for (int d = 0; d < 2; ++d)
    {
      uint64_t expected;
      if (!getU64(f, &expected))
      {
        printf("[FAIL] %-19s truncated golden file at row %d\n", "overlay", r);
        fclose(f);
        return false;
      }
      if (expected != overlayDigests[r][d])
      {
        printf("[FAIL] %-19s first divergence: row %d (%s) %s digest "
               "(expected 0x%016llx, got 0x%016llx)\n",
          "overlay", r, ovRowLabel[r], surface[d],
          (unsigned long long)expected, (unsigned long long)overlayDigests[r][d]);
        fclose(f);
        return false;
      }
    }
  }
 
  if (ovFailRow >= 0)
  {
    printf("[FAIL] %-19s library diverges from the reference at row %d (%s), "
           "pixel %d (lib 0x%04x, ref 0x%04x)\n",
      "overlay", ovFailRow, ovRowLabel[ovFailRow], ovFailPixel, ovFailLib, ovFailRef);
    fclose(f);
    return false;
  }
 
  fclose(f);
  printf("[PASS] %-19s %3d rows\n", "overlay", overlayRowCount);
  return true;
}
 
/* ---------------------------------------------------------------------------
 * FRAME SURFACE (data/frame.golden, its own format - FRAME_VERSION)
 *
 * The 14 scenes above call pico9918_scan_line INDEXED, with a line number the
 * harness picks. So they are structurally blind to two things that decide what a
 * frame actually looks like:
 *
 *   1. the INTERLACE FIELD MAPPING, which chooses WHICH VDP line a given display
 *      line renders. The scenes pin what line N looks like; nothing pins that
 *      display line N asks for line N.
 *   2. the FRAME GEOMETRY, which bounds the display region - vPixels, vBorder and
 *      the end-of-frame trigger scanline, plus the virtual-pixel scaling.
 *
 * A defect in the mapping is a shimmer on real hardware and is invisible to every
 * other gate here, which is why it gets a surface of its own.
 *
 * ALL THREE GROUPS ARE DIFFERENTIAL - each drives real library code against an
 * independent in-harness model:
 *
 *   interrupt  calls pico9918_frame_update_interrupts.
 *   geometry   `frameGeometry` is an adapter over pico9918_frame_geometry, so the
 *              library computes every digested value.
 *   mapping    `frameMapLine` is an adapter over pico9918_frame_map_line_impl.
 *
 * The rule that keeps them honest: the committed digests pin the numbers the library
 * has to produce, so replacing a candidate with a different route to the same code
 * MUST reproduce those digests byte for byte.
 *
 * The mutation table in README.md is the evidence that the digests are sensitive to
 * each behaviour the surface claims to pin.
 *
 * Same shape as the overlay surface: separate artifact with its own magic and
 * version, so GOLDEN_VERSION 3 and the 14 committed scene goldens are untouched
 * and nothing needs recapturing.
 * ------------------------------------------------------------------------- */
 
/* the interrupt group calls the real library entry point */
#include "pico9918_frame.h"
 
#define FRAME_MAGIC   "TMSF"
/* Its own version, separate from GOLDEN_VERSION and OVERLAY_VERSION - each artifact
 * versions on its own. */
#define FRAME_VERSION 2
 
/* Restated rather than reached for: the register BIT is the input to the behaviour
 * under test, not part of it. */
#define FRAME_R0_DOUBLE_ROWS 0x08
 
/* VR49 bit 6 selects 30-row mode (main.c reads TMS_REGISTER(tms9918, 0x31) & 0x40) */
#define FRAME_R31_ROW30      0x40
 
/* The three vertical display geometries the shipping builds actually reach.
 * displayPixels is the VERTICAL active line count of the mode:
 *   VGA 640x480    - 480 rows, progressive, DISPLAY_YSCALE 2       (src/display.h)
 *   SCART PAL 576i - 576/2 - SCART_V_BORDER*2 = 268, interlaced    (vga-modes.c)
 *   SCART NTSC 480i- 480/2 - SCART_V_BORDER*2 = 220, interlaced    (vga-modes.c)
 * Interlaced builds run yScale 1, progressive builds yScale 2 - main.c. */
#define FRAME_DISPLAY_VGA       480
#define FRAME_DISPLAY_SCART_PAL 268
#define FRAME_DISPLAY_SCART_NTSC 220
 
/* the host-owned scale under interlace. main.c only writes vPixelScale /
 * vVirtualPixels when yScale > 1, so under interlace these keep the values
 * vga-modes.c's setVgaParamsScale(&params, 1) left there. */
#define FRAME_INTERLACED_PIXEL_SCALE 1
 
/* The mutable display parameters, i.e. the fields of VgaParams that the
 * end-of-frame code reads or writes. Named to match pico9918_frame_display_t, so the
 * adapter below is a field-for-field copy rather than a translation.
 *
 * Kept as a harness type rather than replaced by pico9918_frame_display_t outright: the
 * mapping group and refGeometry both take it, and refGeometry MUST NOT share a type
 * with the code under test any more than it shares its algebra. */
/* Widths match the firmware EXACTLY, and that is load-bearing rather than
 * pedantry: vga.h declares vVirtualPixels as uint16_t and vPixelScale as
 * uint8_t, and main.c declares vPixels as int but vBorder as uint32_t. The
 * SCART-NTSC row-30 case computes a negative border that the firmware converts to
 * a huge unsigned on assignment, so a model using int throughout would compute
 * -10 where the firmware computes 4294967286 - i.e. it would pin a value the
 * firmware never produces. Nothing else here would catch it: every other pinned
 * row is non-negative, so the narrowing shows in that case alone. */
typedef struct
{
  int      displayPixels;   /* vSyncParams.displayPixels - vertical lines (in) */
  bool     interlaced;      /* (in) */
  uint8_t  vPixelScale;     /* vga.h:84 (in, and out when yScale > 1) */
  uint16_t vVirtualPixels;  /* vga.h:74 (in, and out when yScale > 1) */
} FrameParams;
 
/* the geometry main.c computes at end of frame */
typedef struct
{
  uint8_t  vPixelScale;      /* vga.h:84 */
  uint16_t vVirtualPixels;   /* vga.h:74 */
  int      vPixels;          /* main.c:80 - signed */
  uint32_t vBorder;          /* UNSIGNED, as the firmware declares it - see the row-30 note */
  uint32_t triggerScanline;  /* vBorder + vPixels, so it inherits the wrap */
} FrameGeometry;
 
/* ---- candidate: the PATH UNDER TEST -----------------------------------------
 *
 * `frameGeometry` and `frameMapLine` are both ADAPTERS over the library. Do not
 * "tidy" the algebra in either to look like the reference below: the whole point of
 * that reference is that it does not share this algebra. */
 
/* The interlace field mapping.
 *
 * The body below is an ADAPTER: pico9918_frame_map_line_impl in
 * src/impl/pico9918_priv.h is the code under test, so this is a genuine differential
 * gate rather than a specification one.
 *
 * `y` arrives with the field number in bit 12 and the line within the field in bits
 * 11-0, which is the host VGA layer's encoding (vga.h). SPLITTING IT STAYS IN THE
 * HARNESS, and that is not a shortcut: the library's scanline splits the raw y once at
 * entry, because it needs the field number on the border arm too, and passes the
 * already-separated pair to the mapping. So the split genuinely is the caller's job,
 * and the adapter does here exactly what pico9918_frame_scanline does there.
 *
 * The MASK WIDTH is therefore still harness-side algebra, and the two line-2000/3000
 * cases in frameMapGroup below still pin it against the reference rather than against
 * the library. Stated plainly because it is the one part of this group the rewire does
 * NOT convert: a narrowed mask inside pico9918_frame_scanline is invisible here. Its gate
 * is the asm surface (tmsScanline / pico9918_frame_scanline are both tracked).
 *
 * reg0 is installed in the REAL register file, because the library reads the
 * double-rows bit from the device rather than taking it as a parameter - written
 * directly, for the same reason frameGeometry does it. */
static uint16_t frameMapLine(uint16_t yRaw, const FrameParams* params, uint8_t reg0,
                             uint8_t interlacedFieldOrder)
{
  TMS_REGISTER(tms9918, 0) = reg0;
 
  return pico9918_frame_map_line_impl(PICO9918_INST (uint16_t)(yRaw & 0x0fff),
                                      (uint8_t)((yRaw >> 12) & 1),
                                      params->interlaced, interlacedFieldOrder);
}
 
/* The end-of-frame geometry.
 *
 * The body below is an ADAPTER: pico9918_frame_geometry in src/pico9918_frame.c is
 * the code under test, so this is a genuine differential gate rather than a
 * specification one.
 *
 * The adapter does three things and nothing else, so that everything the digests
 * see comes from the library:
 *
 *   - copies FrameParams into the library's own pico9918_frame_display_t. Field for
 *     field, same widths, same meanings - FrameParams' fields are named to match
 *     precisely so this is a copy rather than a conversion;
 *   - installs reg0 / reg31 in the REAL register file, because the library reads
 *     them from the device rather than taking them as parameters. Written directly
 *     rather than through pico9918_write_reg_value_impl for the same reason the
 *     interrupt group writes R1 directly: that path carries unlock-sequence and
 *     locked-mask side effects which are not part of this contract, and R49 is
 *     above the locked mask so it could not be written at all;
 *   - copies the results back out, including the params the library may have
 *     rewritten, so "the library must not write these under interlace" stays
 *     observable rather than merely asserted.
 *
 * vPixelScale / vVirtualPixels are read back from `display` (the in/out struct),
 * NOT from the returned geometry - the library's return value deliberately carries
 * only the three values it derives, and the host-owned pair travel in the struct it
 * was handed. That is what makes a stray write under interlace visible.
 */
static FrameGeometry frameGeometry(FrameParams* params, uint8_t reg0, uint8_t reg31)
{
  pico9918_frame_display_t display = { params->displayPixels, params->interlaced,
                                   params->vPixelScale, params->vVirtualPixels };
 
  TMS_REGISTER(tms9918, 0) = reg0;
  TMS_REGISTER(tms9918, 0x31) = reg31;
 
  const pico9918_frame_geometry_t lib = pico9918_frame_geometry(&display);
 
  /* the library writes these only when it owns them; mirror them back so the
     post-call params the row digests are the ones it actually left behind */
  params->vPixelScale = display.vPixelScale;
  params->vVirtualPixels = display.vVirtualPixels;
 
  FrameGeometry g;
  g.vPixelScale = display.vPixelScale;
  g.vVirtualPixels = display.vVirtualPixels;
  g.vPixels = lib.vPixels;
  g.vBorder = lib.vBorder;
  g.triggerScanline = lib.triggerScanline;
  return g;
}
 
/* ---- independent reference --------------------------------------------------
 *
 * Written from the DOCUMENTED behaviour, sharing no algebra with the candidate
 * above. Step 3's pixel-format error survived for months because its
 * "cross-check" was written from the same wrong prose as the thing it checked,
 * so independence here is the entire value of the surface: where the candidate
 * fuses (`y * 2 + (field ^ order)`, `<< (bool)doubleRows`, `yScale -
 * (bool)doubleRows`), the reference decomposes into explicit cases. */
 
/* Reference for the field mapping.
 *
 * Documented behaviour: under interlace with double-rows, the two fields
 * INTERLEAVE the VDP's doubled line space - each display line of a field maps to
 * one of the two VDP lines of that display row, and interlacedFieldOrder selects
 * WHICH field takes the even VDP lines. Field 0 with order 0 takes even lines
 * (0, 2, 4, ...) and field 1 takes odd; order 1 swaps that. Outside interlace or
 * outside double-rows there is no mapping: the VDP line is the line within the
 * field, and the field number is simply discarded.
 *
 * Written as an explicit even/odd base plus a selected parity, not as a fused
 * multiply-add, so a dropped XOR or a dropped parity term diverges. */
static uint16_t refMapLine(uint16_t yRaw, const FrameParams* params, uint8_t reg0,
                           uint8_t interlacedFieldOrder)
{
  const int field = (yRaw >> 12) & 1;
  const int lineInField = yRaw & 0x0fff;
 
  if (!params->interlaced) return (uint16_t)lineInField;
  if (!(reg0 & FRAME_R0_DOUBLE_ROWS)) return (uint16_t)lineInField;
 
  /* the pair of VDP lines this display row covers */
  const int evenVdpLine = lineInField + lineInField;
  const int oddVdpLine = evenVdpLine + 1;
 
  /* which of the pair this field owns. order 0: field 0 -> even. order 1: swap. */
  /* Valid only for interlacedFieldOrder in {0,1}, which is its whole domain:
   * vga.h documents it as "0 or 1" and vga-modes.c makes the only two assignments.
   * Stated because this predicate form and the candidate's `field ^ order` diverge
   * outside that domain: order = 3 makes them disagree, which is what shows the two
   * surfaces to be independent implementations rather than one delegating to the
   * other. */
  const bool takesEven = (field != 0) == (interlacedFieldOrder != 0);
  return (uint16_t)(takesEven ? evenVdpLine : oddVdpLine);
}
 
/* Reference for the end-of-frame geometry, from the documented behaviour:
 *
 *   The display region is baseRows rows of 8 VDP lines - 24 rows normally, 30
 *   when VR49 bit 6 selects row-30 mode. On a PROGRESSIVE build the panel is
 *   line-doubled (yScale 2), so double-rows halves the doubling to fit twice as
 *   many VDP lines on screen: vPixelScale drops to 1, the virtual line count
 *   doubles, and the display region doubles with it. On an INTERLACED build the
 *   two fields already supply the second set of lines, so yScale is 1, there is
 *   nothing to halve, and the display region does NOT double - it stays at
 *   baseRows * 8. Interlaced builds also leave vPixelScale and vVirtualPixels
 *   entirely alone: the host set them up and owns them.
 *   The border is the leftover virtual lines split evenly top and bottom, and
 *   the end-of-frame trigger fires on the first line past the display region.
 *
 * Written as an explicit progressive/interlaced split with multiplication rather
 * than the candidate's shift-by-bool and single fused vPixels expression. */
static FrameGeometry refGeometry(FrameParams* params, uint8_t reg0, uint8_t reg31)
{
  const bool doubleRows = (reg0 & FRAME_R0_DOUBLE_ROWS) != 0;
  const int baseRows = (reg31 & FRAME_R31_ROW30) ? 30 : 24;
 
  FrameGeometry g;
  g.vPixels = baseRows * 8;
 
  if (params->interlaced)
  {
    /* host owns the scale: read it, do not write it. vPixels does not double. */
    g.vPixelScale = params->vPixelScale;
    g.vVirtualPixels = params->vVirtualPixels;
  }
  else
  {
    if (doubleRows)
    {
      g.vPixelScale = 1;
      g.vVirtualPixels = params->displayPixels;
      g.vPixels = g.vPixels * 2;
    }
    else
    {
      g.vPixelScale = 2;
      g.vVirtualPixels = params->displayPixels / 2;
    }
    params->vPixelScale = g.vPixelScale;
    params->vVirtualPixels = g.vVirtualPixels;
  }
 
  /* The leftover virtual lines, split evenly top and bottom. Computed as a signed
   * count of spare lines, then converted by the assignment to uint32_t - matching
   * the firmware's `static uint32_t vBorder`. The count DOES go negative (SCART
   * NTSC in row-30 mode), which is why the intermediate must stay signed.
   *
   * `/2` vs `>>1` is deliberately NOT pinned by a dedicated row, and that is a
   * reasoned choice rather than an oversight. They differ only for an odd negative
   * numerator, and no reachable configuration produces one: vPixels is always
   * baseRows << 3 (a multiple of 8, and the doubling preserves that) and every
   * reachable vVirtualPixels - 240, 480, 268, 220 - is even, so the spare-line
   * count is always even. Adversarial review noted the mutation survives; adding a
   * fabricated odd geometry to catch it would pin an arithmetic accident, which is
   * the same mistake the row-30 exclusion made in the other direction. */
  const int spareLines = (int)g.vVirtualPixels - g.vPixels;
  g.vBorder = (uint32_t)(spareLines / 2);
  /* inherits the wrap: unsigned + int, as main.c passes it on */
  g.triggerScanline = g.vBorder + (uint32_t)g.vPixels;
  return g;
}
 
/* ---- the observable consequence of the geometry ----------------------------
 *
 * How many display lines actually RENDER, i.e. take the active arm of the border
 * test at main.c: `if (y < vBorder || y >= (vBorder + vPixels))` takes the
 * border path, else the active path.
 *
 * This exists because the geometry values alone cannot pin the NTSC row-30 defect.
 * vBorder is stored into the row as int32_t, so the firmware's uint32_t
 * 4294967286 and a tidied-up int -10 are the SAME 32 bits and produce the same
 * digest - the TYPE is invisible to a value digest. But the blank screen is caused
 * by the comparison being UNSIGNED, not by the bit pattern. So the consequence is
 * digested directly: with the correct unsigned comparison this returns 0 active
 * lines for SCART NTSC row-30, and making the comparison signed returns 220
 * instead - verified caught at geom-scart-ntsc-row30.
 *
 * Note what is NOT catchable here, so nobody hunts for it: narrowing
 * FrameGeometry.vBorder from uint32_t to int is an EQUIVALENT MUTANT. The field
 * still holds -10, and this comparison converts it straight back to 4294967286
 * (mixed int/uint32_t comparisons promote to unsigned), so neither the stored bits
 * nor the active-line count change. There is nothing for a digest to see because
 * there is no behavioural difference. The uint32_t is kept because it documents the
 * firmware's actual declaration (main.c), not because a gate enforces it. */
static int32_t frameActiveLines(const FrameGeometry* g, int displayPixels)
{
  int32_t active = 0;
  for (uint32_t y = 0; y < (uint32_t)displayPixels; ++y)
    if (!(y < g->vBorder || y >= (g->vBorder + (uint32_t)g->vPixels)))
      ++active;
  return active;
}
 
/* Reference: counts the complement (border lines) and subtracts, and derives the
 * band from an explicit inclusive end rather than reusing the firmware's
 * two-term test, so it does not share the candidate's comparison algebra. */
static int32_t refActiveLines(const FrameGeometry* g, int displayPixels)
{
  const uint32_t total = (uint32_t)displayPixels;
  const uint32_t firstActive = g->vBorder;
  const uint32_t lastActive = g->vBorder + (uint32_t)g->vPixels - 1u;
 
  int32_t border = 0;
  for (uint32_t y = 0; y < total; ++y)
    if (y < firstActive || y > lastActive)
      ++border;
  return (int32_t)total - border;
}
 
/* ---- frame row bookkeeping -------------------------------------------------
 *
 * One digest per row per surface, same as the overlay surface, plus the
 * value-for-value cross-check that localises a divergence to a field.
 *
 * The digest is taken over the FrameRow struct in native byte order. There is no
 * padding to worry about (the int32_t array is homogeneous, so the digest
 * reproducibility is real rather than padding luck), but the committed artifact
 * would not verify
 * on a big-endian host. That matches the pre-existing scene and overlay surfaces,
 * which digest structs the same way - noted rather than fixed, so it stays one
 * consistent property of the whole suite instead of one surface being different.
 * The FILE format itself is endian-safe: putU32/getU32 are explicit byte-wise. */
/* Headroom over the current row count, not a snug fit - see the overlay note. */
#define FRAME_MAX_ROWS 1024
 
static uint64_t frameDigests[FRAME_MAX_ROWS][2];
static int      frameRowCount;
 
/* first candidate-vs-reference disagreement, latched */
static int         frFailRow;
static const char* frFailField;
static long        frFailCand;
static long        frFailRef;
 
static const char* frRowLabel[FRAME_MAX_ROWS];
static const char* frCurrentLabel = "";
 
/* The row payload: every value either behaviour produces, in a fixed layout, so
 * one digest covers the whole row and a mismatch is localised by rescanning.
 *
 * Slots 0..8 are the mapping and geometry groups; 9..12 are the interrupt group.
 * Each group fills only its own slots and leaves the rest zero, so a divergence
 * report points at a value that group actually produced. */
#define FRAME_ROW_VALUES 13
 
typedef struct
{
  int32_t v[FRAME_ROW_VALUES];
} FrameRow;
 
static const char* const frameFieldName[FRAME_ROW_VALUES] = {
  "mappedLine", "vPixelScale", "vVirtualPixels", "vPixels", "vBorder", "triggerScanline", "paramsVPixelScale",
  "paramsVVirtualPixels", "activeLines",
  /* interrupt group */
  "frameStatusShadow", "sr0Register", "intPin", "sr1Register"};
 
static void frameEmitRow(const FrameRow* cand, const FrameRow* ref)
{
  if (frameRowCount >= FRAME_MAX_ROWS)
  {
    /* abort, never truncate - see the OVERLAY_MAX_ROWS note */
    printf("[ERROR] frame: row budget %d exhausted - raise FRAME_MAX_ROWS\n",
           FRAME_MAX_ROWS);
    exit(2);
  }
 
  const int row = frameRowCount++;
  frRowLabel[row] = frCurrentLabel;
  frameDigests[row][0] = fnv1a(cand, sizeof(*cand));
  frameDigests[row][1] = fnv1a(ref, sizeof(*ref));
 
  if (frFailRow < 0)
  {
    for (int i = 0; i < FRAME_ROW_VALUES; ++i)
    {
      if (cand->v[i] != ref->v[i])
      {
        frFailRow = row;
        frFailField = frameFieldName[i];
        frFailCand = cand->v[i];
        frFailRef = ref->v[i];
        break;
      }
    }
  }
}
 
/* ---- the interlace mapping group -------------------------------------------
 *
 * Both fields and both field orders at every case, because a defect that SWAPS
 * the fields is the exact failure mode this exists to catch and it is invisible
 * to any single-field case. The mapping fields of the row are filled; the
 * geometry fields are left zero (the two groups digest disjoint halves of the
 * row, which keeps each group's divergence report pointing at its own values).
 *
 * Cases: line 0 of each field, so the origin of the mapping is pinned in all
 * four field/order combinations; a mid-panel line; the last line of a 24-row
 * interlaced panel (119 -> 239, the top of the doubled VDP line space); the
 * non-interlaced and non-double-rows arms, where the mapping must NOT apply and
 * the field bit must be DISCARDED rather than folded in. */
static void frameMapCase(const char* label, uint16_t yRaw, bool interlaced,
                         uint8_t reg0, uint8_t order)
{
  frCurrentLabel = label;
 
  FrameParams cp = { FRAME_DISPLAY_SCART_PAL, interlaced,
                     FRAME_INTERLACED_PIXEL_SCALE, FRAME_DISPLAY_SCART_PAL };
  FrameParams rp = cp;
 
  FrameRow cand = { { 0 } }, ref = { { 0 } };
  cand.v[0] = frameMapLine(yRaw, &cp, reg0, order);
  ref.v[0] = refMapLine(yRaw, &rp, reg0, order);
 
  frameEmitRow(&cand, &ref);
}
 
/* every field/order combination of one line-within-field.
 *
 * The generated label must outlive the call, since frRowLabel stores the pointer
 * for the divergence report - so it is composed into a per-row slot of a fixed
 * array rather than a local buffer. Indexed by the row it labels, which is
 * frameRowCount at the moment of the call. */
static char frMapLabels[FRAME_MAX_ROWS][32];
 
static void frameMapQuad(const char* label, uint16_t lineInField, bool interlaced,
                         uint8_t reg0)
{
  for (int field = 0; field < 2; ++field)
  {
    for (int order = 0; order < 2; ++order)
    {
      /* the label slot is indexed before frameEmitRow's budget check runs, so it
         needs its own bound - otherwise the overflow beats the abort to it */
      if (frameRowCount >= FRAME_MAX_ROWS)
      {
        printf("[ERROR] frame: row budget %d exhausted - raise FRAME_MAX_ROWS\n",
               FRAME_MAX_ROWS);
        exit(2);
      }
      char* stored = frMapLabels[frameRowCount];
      snprintf(stored, sizeof(frMapLabels[0]), "%s-f%d-o%d", label, field, order);
      frameMapCase(stored, (uint16_t)((field << 12) | lineInField),
                   interlaced, reg0, (uint8_t)order);
    }
  }
}
 
static void frameMapGroup(void)
{
  /* interlaced + double-rows: the mapping applies. These are the values the
   * brief's table pins - line 0 gives 0/1/1/0 across the four combinations. */
  frameMapQuad("il-dbl-line0", 0, true, FRAME_R0_DOUBLE_ROWS);
  frameMapQuad("il-dbl-line1", 1, true, FRAME_R0_DOUBLE_ROWS);
  frameMapQuad("il-dbl-line95", 95, true, FRAME_R0_DOUBLE_ROWS);
  /* 119 is the last line of a 24-row interlaced panel: 119*2 = 238, so the
   * mapping reaches VDP line 239 - the top of the doubled space */
  frameMapQuad("il-dbl-line119", 119, true, FRAME_R0_DOUBLE_ROWS);
  /* a 30-row interlaced panel runs to line 149 -> VDP 299 */
  frameMapQuad("il-dbl-line149", 149, true, FRAME_R0_DOUBLE_ROWS);
 
  /* interlaced, NO double-rows: no mapping, and the field bit is discarded */
  frameMapQuad("il-nodbl-line0", 0, true, 0x00);
  frameMapQuad("il-nodbl-line119", 119, true, 0x00);
 
  /* progressive: no mapping either way. The field bit cannot be set by the
   * progressive path, but pinning that it is discarded is what stops a defect
   * from folding it in unconditionally. */
  frameMapQuad("prog-dbl-line0", 0, false, FRAME_R0_DOUBLE_ROWS);
  frameMapQuad("prog-dbl-line191", 191, false, FRAME_R0_DOUBLE_ROWS);
  frameMapQuad("prog-nodbl-line0", 0, false, 0x00);
  frameMapQuad("prog-nodbl-line191", 191, false, 0x00);
 
  /* THE MASK WIDTH. Every case above has lineInField <= 191, which fits in 8
   * bits, so none of them exercises how wide the y mask actually is - and
   * `>> 12` / `& 0x0fff` is the one piece of algebra the reference does NOT
   * decompose, so a narrowed mask is a correlated error both surfaces make
   * together. Found as an escape by adversarial review: mutating the candidate's
   * mask to 0x00ff (or 0x07ff) left the suite passing at 52 rows.
   *
   * 2000 sets bits 10 and 7..6 etc - above 8 bits, below 12 - so a 0x00ff mask
   * drops bit 10 and a 0x07ff mask still passes, hence the second case at 3000,
   * which sets bit 11 and kills 0x07ff too. The mask is load-bearing: it is what
   * separates the field bit from the line (vga.h documents bits 11:0 as the
   * line). These lines exceed any real panel height, which is the point - the
   * mask must be pinned by its WIDTH, not by reachable geometry. */
  frameMapQuad("il-dbl-line2000", 2000, true, FRAME_R0_DOUBLE_ROWS);
  frameMapQuad("il-dbl-line3000", 3000, true, FRAME_R0_DOUBLE_ROWS);
  frameMapQuad("il-nodbl-line3000", 3000, true, 0x00);
}
 
/* ---- the geometry group ----------------------------------------------------
 *
 * The full reachable matrix of (build vertical geometry) x (double-rows) x
 * (row-30). Three subtleties this group exists to pin, each of which is easy to
 * "tidy" wrongly:
 *
 *   - Under INTERLACE, vPixels IGNORES double-rows. The doubling is gated on
 *     yScale > 1, and interlaced builds run yScale 1. Progressive double-rows
 *     gives 384; interlaced double-rows stays 192.
 *   - Row-30 PROGRESSIVE gives vBorder == 0: no vertical border at all. Code
 *     that assumes a non-zero border breaks exactly there.
 *   - vPixelScale and vVirtualPixels are rewritten ONLY when yScale > 1. Under
 *     interlace the host owns them and the library must not write them. Both the
 *     VALUES and the not-writing are pinned: the row carries the geometry's own
 *     idea of them AND the post-call params, so a stray write shows up as a
 *     divergence in paramsVPixelScale / paramsVVirtualPixels even when the
 *     returned geometry happens to look right.
 *
 * ROW-30 UNDER INTERLACE IS IN THE MATRIX, and SCART-NTSC row-30 is a firmware defect
 * this surface PINS rather than fixes: vVirtualPixels 220 against vPixels 240 gives
 * vBorder -10, which the firmware's unsigned vBorder turns into 4294967286, so the
 * border test sends all 220 lines down the border path and renders none. Both
 * settings are reachable in a shipping build - SCART timing is fixed at boot, row-30
 * is set at runtime by any F18A program writing R49 bit 6 - so the combination is not
 * hypothetical. A fix must show up here as an intentional golden diff, which is why
 * FrameGeometry.vBorder is uint32_t and not a tidy int. */
static void frameGeomCase(const char* label, int displayPixels, bool interlaced,
                          uint8_t reg0, uint8_t reg31)
{
  frCurrentLabel = label;
 
  /* the host's starting params. Progressive builds are re-derived from
   * displayPixels by the code under test, so their incoming scale is the mode's
   * own setVgaParamsScale(1); interlaced builds keep it. */
  FrameParams cp = { displayPixels, interlaced,
                     FRAME_INTERLACED_PIXEL_SCALE, displayPixels };
  FrameParams rp = cp;
 
  const FrameGeometry cg = frameGeometry(&cp, reg0, reg31);
  const FrameGeometry rg = refGeometry(&rp, reg0, reg31);
 
  FrameRow cand = { { 0 } }, ref = { { 0 } };
  cand.v[1] = cg.vPixelScale;
  cand.v[2] = cg.vVirtualPixels;
  cand.v[3] = cg.vPixels;
  cand.v[4] = cg.vBorder;
  cand.v[5] = cg.triggerScanline;
  cand.v[6] = cp.vPixelScale;
  cand.v[7] = cp.vVirtualPixels;
  cand.v[8] = frameActiveLines(&cg, displayPixels);
 
  ref.v[1] = rg.vPixelScale;
  ref.v[2] = rg.vVirtualPixels;
  ref.v[3] = rg.vPixels;
  ref.v[4] = rg.vBorder;
  ref.v[5] = rg.triggerScanline;
  ref.v[6] = rp.vPixelScale;
  ref.v[7] = rp.vVirtualPixels;
  ref.v[8] = refActiveLines(&rg, displayPixels);
 
  frameEmitRow(&cand, &ref);
}
 
static void frameGeomGroup(void)
{
  /* progressive VGA, all four double-rows x row-30 combinations */
  frameGeomCase("geom-vga", FRAME_DISPLAY_VGA, false, 0x00, 0x00);
  frameGeomCase("geom-vga-row30", FRAME_DISPLAY_VGA, false, 0x00, FRAME_R31_ROW30);
  frameGeomCase("geom-vga-dbl", FRAME_DISPLAY_VGA, false, FRAME_R0_DOUBLE_ROWS, 0x00);
  frameGeomCase("geom-vga-dbl-row30", FRAME_DISPLAY_VGA, false,
                FRAME_R0_DOUBLE_ROWS, FRAME_R31_ROW30);
 
  /* interlaced SCART, both timings, with and without double-rows. The
   * double-rows rows are the ones that pin "interlace ignores double-rows". */
  frameGeomCase("geom-scart-pal", FRAME_DISPLAY_SCART_PAL, true, 0x00, 0x00);
  frameGeomCase("geom-scart-pal-dbl", FRAME_DISPLAY_SCART_PAL, true,
                FRAME_R0_DOUBLE_ROWS, 0x00);
  frameGeomCase("geom-scart-ntsc", FRAME_DISPLAY_SCART_NTSC, true, 0x00, 0x00);
  frameGeomCase("geom-scart-ntsc-dbl", FRAME_DISPLAY_SCART_NTSC, true,
                FRAME_R0_DOUBLE_ROWS, 0x00);
 
  /* Row-30 under interlace - reachable at runtime, see the note above this
   * group. PAL is an ordinary positive border (+14). NTSC underflows to
   * 4294967286 and is the blank-screen defect; pinned deliberately so a future
   * firmware fix shows up here as an intentional diff. */
  frameGeomCase("geom-scart-pal-row30", FRAME_DISPLAY_SCART_PAL, true,
                0x00, FRAME_R31_ROW30);
  frameGeomCase("geom-scart-ntsc-row30", FRAME_DISPLAY_SCART_NTSC, true,
                0x00, FRAME_R31_ROW30);
}
 
/* ---- the interrupt/status latch merge group ---------------------------------
 *
 * Calls pico9918_frame_update_interrupts: merge the flags the scanline just raised
 * (tempStatus) into the SR0 latch, publish, then bring /INT into agreement. Three
 * mutually exclusive branches, keyed on the latch's own F and 5S:
 *
 *   A  F clear, 5S latched      only tempStatus' flag bits merge (& 0xe0). The latched
 *                               sprite ID must SURVIVE - it names the fifth sprite of
 *                               the line that first set 5S
 *   B  F clear, 5S not latched  tempStatus replaces the low five bits; the incumbent
 *                               flag bits are preserved
 *   C  F set                    COL only. Per the TMS9918A datasheet and the F18A, COL
 *                               is not gated by F, but 5S is blocked while F is set and
 *                               the ID must not move
 *
 * /INT has TWO sources, ORed: the frame source, R1's interrupt-enable bit AND SR0's F;
 * and the scanline source, R0 bit 4 AND SR1's HF, on an unlocked device only. R1 gates
 * the first and not the second, which is the whole point of the split - a program using
 * only the scanline interrupt runs with R1's enable off, and folding the two together
 * leaves it never interrupting at all. So R1 is a second input to every case, and R0,
 * SR1 and the lock state are three more.
 *
 * Two things would silently void the coverage:
 *
 *   The pin field is tms9918->frameInt, NOT pico9918_interrupt_status(), which
 *   RECOMPUTES the answer from live state and so reads correct even with the sync
 *   deleted. frameInt is the latched pin, and the rows arrange for the correct
 *   post-state to differ from the pre-state in both directions.
 *
 *   SR0 is read from the register file, not through pico9918_read_status - reading SR0
 *   clears F and 5S and releases the pin, destroying the state being digested. Both
 *   copies are digested, so a publish that updated only one diverges here.
 * ------------------------------------------------------------------------- */
 
/* R1 bit 5. Restated rather than reached for, exactly as the R0/R31 bits above
 * are: the register BIT is an INPUT to the behaviour under test, so the surface
 * must not inherit it from the code it is testing.
 * TMS_R1_INT_ENABLE in pico9918_priv.h spells it the same. */
#define FRAME_R1_INT_ENABLE 0x20
 
/* The three SR0 flag bits, restated for the same reason. PICO9918_SR0_INT / _5S /
 * _COLLISION in pico9918.h spell them the same. */
#define FRAME_SR0_F   0x80  /* frame interrupt */
#define FRAME_SR0_5S  0x40  /* fifth sprite */
#define FRAME_SR0_COL 0x20  /* sprite collision */
#define FRAME_SR0_ID  0x1f  /* fifth-sprite number, low five bits */
 
/* The scanline source's own two bits, restated for the same reason.
 * TMS_R0_INT_SCANLINE and PICO9918_SR1_HF spell them the same. */
#define FRAME_R0_INT_SCANLINE 0x10
#define FRAME_SR1_HF          0x01
 
/* Independent reference for the merge.
 *
 * Deliberately NOT `(cur & 0xe0) | temp` or `cur |= temp & 0xe0`. Each output part
 * is named and decided on its own, so a mask that lets the wrong bit through, or a
 * branch that keeps the wrong half, diverges here rather than being reproduced:
 *
 *   flags  which of F / 5S / COL end up set, decided one bit at a time.
 *   id     which five-bit sprite number survives.
 *
 * The branch selection is written as the two independent questions the datasheet
 * asks (is F latched? is 5S latched?) rather than as the candidate's nested if. */
static uint8_t refMergeStatus(uint8_t currentStatus, uint8_t tempStatus)
{
  const bool haveF = (currentStatus & FRAME_SR0_F) != 0;
  const bool have5S = (currentStatus & FRAME_SR0_5S) != 0;
 
  /* the incumbent flags always survive: no branch clears a latched flag */
  bool outF = haveF;
  bool out5S = have5S;
  bool outCol = (currentStatus & FRAME_SR0_COL) != 0;
 
  /* what the new scanline is allowed to raise */
  if (haveF)
  {
    /* F latched: COL only. 5S blocked, F already set, ID untouchable. */
    if (tempStatus & FRAME_SR0_COL) outCol = true;
  }
  else
  {
    /* F clear: all three flags may be raised */
    if (tempStatus & FRAME_SR0_F) outF = true;
    if (tempStatus & FRAME_SR0_5S) out5S = true;
    if (tempStatus & FRAME_SR0_COL) outCol = true;
  }
 
  /* the sprite ID. It is replaced only when there was no latched 5S to protect
   * and F was not blocking the update - i.e. exactly the no-5S, no-F case. */
  uint8_t id = currentStatus & FRAME_SR0_ID;
  if (!haveF && !have5S) id = tempStatus & FRAME_SR0_ID;
 
  uint8_t out = id;
  if (outF) out |= FRAME_SR0_F;
  if (out5S) out |= FRAME_SR0_5S;
  if (outCol) out |= FRAME_SR0_COL;
  return out;
}
 
/* Independent reference for the pin.
 *
 * The library asks it as two fused `&&` terms over masked register reads, ORed. Here
 * every condition is a separate named predicate over a separate input, so a defect that
 * drops one of them, that reads the pre-merge status instead of the merged one, or that
 * puts the scanline source behind R1's enable, diverges. Written as the two sources the
 * F18A documents rather than as one expression, because their gating differs and that
 * difference is the behaviour being pinned. */
static bool refIntPin(uint8_t mergedStatus, uint8_t reg1, uint8_t reg0, uint8_t sr1, bool unlocked)
{
  const bool frameEnabled     = (reg1 & FRAME_R1_INT_ENABLE) != 0;
  const bool frameFlagLatched = (mergedStatus & FRAME_SR0_F) != 0;
 
  const bool scanlineEnabled     = (reg0 & FRAME_R0_INT_SCANLINE) != 0;
  const bool scanlineFlagLatched = (sr1 & FRAME_SR1_HF) != 0;
 
  /* the scanline source is the F18A's own, so a locked device has only one source */
  return (frameEnabled && frameFlagLatched) || (unlocked && scanlineEnabled && scanlineFlagLatched);
}
 
/* Force the /INT pin (tms9918->frameInt) to `want` WITHOUT calling the function
 * under test.
 *
 * The only writer of frameInt other than that function is
 * pico9918_frame_sync_int_impl, which drives the pin to the OR of both sources. So
 * a temporary R1/SR0 pairing that computes to `want` is installed, the scanline source
 * is silenced so it cannot hold the pin up against a `want` of false, the sync is run,
 * and the caller then writes the row's real precondition over the top - which,
 * having no reconcile hook, leaves the pin where this left it. */
static void frameIntSetup(bool want)
{
  TMS_STATUS(tms9918, PICO9918_SR_IDENT) &= (uint8_t)~FRAME_SR1_HF;
  TMS_REGISTER(tms9918, TMS_REG_0) &= (uint8_t)~FRAME_R0_INT_SCANLINE;
  TMS_REGISTER(tms9918, TMS_REG_1) = want ? FRAME_R1_INT_ENABLE : 0x00;
  pico9918_set_status_impl(want ? FRAME_SR0_F : 0x00);
  pico9918_frame_sync_int_impl();
}
 
/* One row: install the precondition, call the library, digest the consequences.
 *
 * The lock state is written as the field rather than run as the VR57 sequence: that
 * sequence goes through the bus, whose post-write reconcile re-syncs the pin and would
 * destroy the pre-state the row exists to test. Every other input here is installed
 * directly for the same reason. */
static void frameIntCase(const char* label, uint8_t currentStatus, uint8_t tempStatus, uint8_t reg1,
                         bool intPinPre, uint8_t reg0, uint8_t sr1, bool unlocked)
{
  frCurrentLabel = label;
 
  /* ---- precondition ---- */
  frameIntSetup(intPinPre);                     /* the pin's pre-state */
  TMS_REGISTER(tms9918, TMS_REG_1)       = reg1; /* R1, the frame source's enable */
  TMS_REGISTER(tms9918, TMS_REG_0)       = reg0; /* R0, the scanline source's enable */
  TMS_STATUS(tms9918, PICO9918_SR_IDENT) = sr1;  /* SR1, the scanline source's flag */
  tms9918->isUnlocked                    = unlocked;
  pico9918_set_status_impl(currentStatus);     /* the SR0 latch, both copies */
 
  /* ---- the behaviour under test ---- */
  pico9918_frame_update_interrupts(tempStatus);
 
  /* ---- the observable consequences ---- */
  FrameRow cand = { { 0 } }, ref = { { 0 } };
  cand.v[9]  = pico9918_frame_status_impl();   /* merged SR0, the frame shadow */
  cand.v[10] = TMS_STATUS(tms9918, 0);          /* merged SR0, the register copy */
  cand.v[11] = pico9918_frame_int_impl();      /* the LATCHED /INT pin */
  cand.v[12] = TMS_STATUS(tms9918, PICO9918_SR_IDENT);
 
  const uint8_t expected = refMergeStatus(currentStatus, tempStatus);
  ref.v[9]               = expected;
  ref.v[10]              = expected;
  ref.v[11]              = refIntPin(expected, reg1, reg0, sr1, unlocked);
 
  /* the merge owns SR0 and must not touch SR1: the scanline flag is the read path's */
  ref.v[12] = sr1;
 
  frameEmitRow(&cand, &ref);
}
 
/* Every case in both R1 states and both pin pre-states, because R1 is a second
 * input and the pin must be shown to move in both directions.
 *
 * Four rows per merge case: (R1 int-enable off/on) x (pin pre-state false/true).
 * Not a snug matrix for its own sake - each combination pins something distinct:
 *   R1 off  the pin must end LOW no matter what F does, so an R1 mask taking
 *           effect is pinned, which is the reason the function ends with a sync.
 *   R1 on   the pin must follow the MERGED F, so a merge that loses F is caught by
 *           the pin as well as by the byte.
 *   pre false / pre true  make the correct post-state differ from the pre-state in
 *           one direction or the other, which is what makes a MISSING sync visible.
 */
static char frIntLabels[FRAME_MAX_ROWS][40];
 
static void frameIntQuad(const char* label, uint8_t currentStatus, uint8_t tempStatus)
{
  for (int r1 = 0; r1 < 2; ++r1)
  {
    for (int pre = 0; pre < 2; ++pre)
    {
      /* the label slot is indexed before frameEmitRow's budget check runs, so it
         needs its own bound - otherwise the overflow beats the abort to it */
      if (frameRowCount >= FRAME_MAX_ROWS)
      {
        printf("[ERROR] frame: row budget %d exhausted - raise FRAME_MAX_ROWS\n",
               FRAME_MAX_ROWS);
        exit(2);
      }
      char* stored = frIntLabels[frameRowCount];
      snprintf(stored, sizeof(frIntLabels[0]), "%s-r1%d-pin%d", label, r1, pre);
 
      /* unlocked with the scanline source ARMED but unflagged, so every row of the
         merge group also pins that an armed second source contributes nothing */
      frameIntCase(stored, currentStatus, tempStatus, (uint8_t)(r1 ? FRAME_R1_INT_ENABLE : 0x00), pre != 0,
                   FRAME_R0_INT_SCANLINE, 0x00, true);
    }
  }
}
 
/* One scanline-source case in both pin pre-states.
 *
 * A pair rather than a quad: what varies across this group is the second source's own
 * three inputs, so R1 and the SR0 latch are given per case rather than swept. Both pin
 * pre-states still run, for the same reason the merge quads do - it is what makes a
 * missing sync visible in whichever direction the row moves the pin. */
static void frameHIntPair(const char* label, uint8_t currentStatus, uint8_t tempStatus, uint8_t reg1,
                          uint8_t reg0, uint8_t sr1, bool unlocked)
{
  for (int pre = 0; pre < 2; ++pre)
  {
    if (frameRowCount >= FRAME_MAX_ROWS)
    {
      printf("[ERROR] frame: row budget %d exhausted - raise FRAME_MAX_ROWS\n", FRAME_MAX_ROWS);
      exit(2);
    }
 
    char* stored = frIntLabels[frameRowCount];
    snprintf(stored, sizeof(frIntLabels[0]), "%s-pin%d", label, pre);
    frameIntCase(stored, currentStatus, tempStatus, reg1, pre != 0, reg0, sr1, unlocked);
  }
}
 
/* One row for the read path, which is a different function: pico9918_read_status.
 *
 * Reading SR1 clears HF, and the pin is then RE-DERIVED rather than cleared - a frame
 * source that is still asserting has to keep it down. Without the clear a latched HF
 * would hold /INT asserted forever and an ISR that acknowledged would re-enter at once;
 * without the re-derive, acknowledging a scanline interrupt would drop a frame one the
 * host had not seen.
 *
 * The pin is forced HIGH first, through the R1/SR0 pairing frameIntSetup uses, and the
 * row's real inputs are written over the top - so the pre-state owes nothing to the
 * scanline source it is about to withdraw. */
static void frameHIntReadCase(const char* label, uint8_t currentStatus, uint8_t reg1)
{
  frCurrentLabel = label;
 
  /* ---- precondition: armed, flagged, and the pin already down ---- */
  frameIntSetup(true);
  TMS_REGISTER(tms9918, TMS_REG_1)                  = reg1;
  TMS_REGISTER(tms9918, TMS_REG_0)                  = FRAME_R0_INT_SCANLINE;
  TMS_STATUS(tms9918, PICO9918_SR_IDENT)            = FRAME_SR1_HF;
  TMS_REGISTER(tms9918, PICO9918_REG_STATUS_SELECT) = PICO9918_SR_IDENT;
  tms9918->isUnlocked                               = true;
  pico9918_set_status_impl(currentStatus);
 
  /* ---- the behaviour under test ---- */
  const uint8_t got = pico9918_read_status();
 
  /* ---- the observable consequences ---- */
  FrameRow cand = {{0}}, ref = {{0}};
  cand.v[9]  = got;
  cand.v[10] = TMS_STATUS(tms9918, 0);
  cand.v[11] = pico9918_frame_int_impl();
  cand.v[12] = TMS_STATUS(tms9918, PICO9918_SR_IDENT);
 
  /* the CPU sees the flag it is acknowledging, and SR0 is not the register read */
  ref.v[9]  = FRAME_SR1_HF;
  ref.v[10] = currentStatus;
 
  const uint8_t sr1After = (uint8_t)(FRAME_SR1_HF & ~FRAME_SR1_HF);
  ref.v[11]              = refIntPin(currentStatus, reg1, FRAME_R0_INT_SCANLINE, sr1After, true);
  ref.v[12]              = sr1After;
 
  frameEmitRow(&cand, &ref);
}
 
static void frameIntGroup(void)
{
  /* ---- branch A: F clear, 5S latched. The latched ID must SURVIVE. ----
   *
   * 0x45 + 0x9f -> 0xc5 is one of the two DISCRIMINATING cases of this group.
   * The latch holds 5S with sprite ID 5; the scanline raises F, 5S and COL and
   * names sprite 31. The ID 5 must still be 5 afterwards. Swap branches A and B
   * and this yields 0x9f, clobbering the ID with 31 - which on hardware means a
   * host reading SR0 is told the wrong sprite caused the overflow. */
  frameIntQuad("int-a-5s-id5", 0x45, 0x9f);
  /* ID 3 kept while F is raised and the low bits of tempStatus (0x08) are dropped */
  frameIntQuad("int-a-5s-id3", 0x43, 0xe8);
  /* nothing but COL raised, ID 0: pins that branch A raises COL at all */
  frameIntQuad("int-a-5s-col", 0x40, 0x20);
 
  /* ---- branch B: F clear, no 5S. tempStatus replaces the low five bits. ----
   *
   * 0x1f + 0x80 -> 0x80 is the vertical blank, and the other DISCRIMINATING case of
   * this group: the blank runs no sprite scan, so it names no sprite, and an OR here
   * would leave the previous line's ID standing as though it had. */
  frameIntQuad("int-b-vblank", 0x1f, 0x80);
  /* empty latch, everything arrives at once */
  frameIntQuad("int-b-empty", 0x00, 0xc5);
  /* incumbent COL must be PRESERVED across the replacement: the `& 0xe0` on the
   * INCUMBENT is what keeps it, and dropping it loses a collision the host has
   * not read yet. 0x20 + 0x1f -> 0x3f, not 0x1f. */
  frameIntQuad("int-b-keep-col", 0x20, 0x1f);
 
  /* ---- branch C: F set. COL only. ----
   *
   * 0x85 + 0x40 -> 0x85 is the second DISCRIMINATING case, and the escape that
   * motivated this whole group. The latch holds F with ID 5; the scanline raises
   * 5S. 5S is blocked while F is set, so the latch must not change at all. The
   * COL -> 5S mutation yields 0xc5 here. */
  frameIntQuad("int-c-block-5s", 0x85, 0x40);
  /* the converse: COL must get through while F is latched, and the ID must not be
   * touched. 0x9f + 0xe5 -> 0xbf. If COL were gated by F this stays 0x9f. */
  frameIntQuad("int-c-pass-col", 0x9f, 0xe5);
  /* COL already latched, COL raised again: idempotent, and pins that branch C
   * writes nothing else. */
  frameIntQuad("int-c-col-again", 0xa0, 0x20);
 
  /* ---- cases beyond the nine, each discriminating something the nine miss ----
   *
   * A: 5S latched and tempStatus raises NOTHING (0x00). Branch A must be a no-op.
   * This separates `cur |= temp & 0xe0` from `cur = temp & 0xe0`, which the nine
   * cases above cannot: every one of them has at least one flag bit in tempStatus,
   * so an assignment-instead-of-OR still happens to land on the same flags. Here
   * assignment would drop the latched 5S and the ID together, giving 0x00. */
  frameIntQuad("int-a-noop", 0x47, 0x00);
  /* C: F latched, ID 0, and tempStatus raises only F. Nothing may change (F is
   * already set, and F is not COL), so this pins that branch C does not somehow
   * fold F's own bit into the ID or the flags. */
  frameIntQuad("int-c-f-again", 0x80, 0x80);
  /* B: no-5S with F ALREADY latched is impossible by construction (branch C owns
   * F), so the no-5S branch is only ever reached with F clear. What IS reachable
   * and untested above is B raising 5S with a MAXIMUM id while an incumbent 5S is
   * absent but COL and F both arrive: 0x00 + 0x7f -> 0x7f. This pins that B does
   * not mask the incoming ID. */
  frameIntQuad("int-b-full-id", 0x00, 0x7f);
  /* The pin, isolated from the merge: F is already latched and stays latched, so
   * mergedSR0 is CONSTANT across all four rows of the quad while the pin is not.
   * Any defect in the pin decision therefore has nowhere to hide behind a moving
   * status byte. */
  frameIntQuad("int-pin-only", 0x80, 0x00);
 
  /* ---- the scanline source, which is not the frame source ----
   *
   * The escape this sub-group exists for: the scanline interrupt was routed through
   * SR0's F under R1's enable, so a program that enabled only the scanline interrupt -
   * R1's enable OFF, which is exactly what such a program does - never interrupted.
   *
   * THE case: armed and flagged with the frame source entirely off. The pin must
   * assert, and R1 being clear is what makes it discriminating. */
  frameHIntPair("hint-alone", 0x00, 0x00, 0x00, FRAME_R0_INT_SCANLINE, FRAME_SR1_HF, true);
 
  /* the same row with one of the three inputs withdrawn, everything else identical.
   * The pin must stay low in all three, so none of them can be the one dropped. */
  frameHIntPair("hint-locked", 0x00, 0x00, 0x00, FRAME_R0_INT_SCANLINE, FRAME_SR1_HF, false);
  frameHIntPair("hint-disarmed", 0x00, 0x00, 0x00, 0x00, FRAME_SR1_HF, true);
  frameHIntPair("hint-noflag", 0x00, 0x00, 0x00, FRAME_R0_INT_SCANLINE, 0x00, true);
 
  /* F latched AND R1 off: the frame source is gated off, so the pin can only be the
   * scanline source's. A fix that put the second source behind R1 as well reads LOW. */
  frameHIntPair("hint-f-latched-r1off", FRAME_SR0_F, 0x00, 0x00, FRAME_R0_INT_SCANLINE, FRAME_SR1_HF, true);
 
  /* both sources asserting at once, and the merge raising more flags on top. SR1 is
   * digested on every row, so a merge that clears HF while writing SR0 diverges. */
  frameHIntPair("hint-both", FRAME_SR0_F, 0xc5, FRAME_R1_INT_ENABLE, FRAME_R0_INT_SCANLINE, FRAME_SR1_HF,
                true);
 
  /* the converse: armed but unflagged, the frame source alone raises the pin, so
   * arming the second source cannot be what suppresses the first. */
  frameHIntPair("hint-frame-only", 0x00, FRAME_SR0_F, FRAME_R1_INT_ENABLE, FRAME_R0_INT_SCANLINE, 0x00, true);
 
  /* ---- the read path releases it ----
   *
   * The discriminating pair. With no frame source the pin must FALL; with one still
   * asserting it must STAY, which is the difference between re-deriving the pin and
   * clearing it. LAST, because these are the only rows that call the read path and
   * they leave R15 selecting SR1. */
  frameHIntReadCase("hread-releases", 0x00, 0x00);
  frameHIntReadCase("hread-frame-holds", FRAME_SR0_F, FRAME_R1_INT_ENABLE);
}
 
/* ---- frame artifact I/O ---------------------------------------------------- */
static void frameRender(void)
{
  frameRowCount = 0;
  frFailRow = -1;
 
  frameMapGroup();
  /* This one TOUCHES LIBRARY STATE too: it writes R0 and R49 on every row (the
   * library reads them from the device), and pico9918_frame_geometry publishes the
   * frame module's vPixels / vBorder globals. Harmless for the same reason the
   * interrupt group's writes are - see below - since the whole surface runs last. */
  frameGeomGroup();
  /* LAST, and it TOUCHES LIBRARY STATE: it writes R1 and the SR0 latch on every row.
   * Running it last keeps the frame surface's own position free (see the call site
   * in main) and, more importantly, keeps the 14 scene goldens and the overlay
   * artifact independent of it - they all run before. The state it leaves behind is
   * the last row's, which nothing afterwards reads.
   *
   * It must also stay AFTER the geometry group, which now writes R0: R0 is not an
   * input to the merge, so the order is not load-bearing for correctness, but the
   * interrupt group's documented preconditions are written per row while the
   * geometry group's are not. */
  frameIntGroup();
}
 
static bool frameCapture(const char* dataDir)
{
  frameRender();
 
  if (frFailRow >= 0)
  {
    printf("[ERROR] frame               candidate diverges from the reference at "
           "row %d (%s), field %s (cand %ld, ref %ld) - NOT captured\n",
      frFailRow, frRowLabel[frFailRow], frFailField, frFailCand, frFailRef);
    return false;
  }
 
  char path[512];
  snprintf(path, sizeof(path), "%s/frame.golden", dataDir);
  FILE* f = fopen(path, "wb");
  if (!f)
  {
    printf("[ERROR] frame: cannot open %s for writing\n", path);
    return false;
  }
 
  fwrite(FRAME_MAGIC, 1, 4, f);
  putU32(f, FRAME_VERSION);
  putU32(f, (uint32_t)frameRowCount);
  /* values per row, derived so the header cannot drift from FrameRow */
  putU32(f, FRAME_ROW_VALUES);
  putU32(f, 2);  /* digests per row: candidate, reference */
  for (int r = 0; r < frameRowCount; ++r)
  {
    putU64(f, frameDigests[r][0]);
    putU64(f, frameDigests[r][1]);
  }
  fclose(f);
 
  printf("[CAPTURED] %-19s %3d rows -> %s\n", "frame", frameRowCount, path);
  return true;
}
 
static bool frameCompare(const char* dataDir)
{
  char path[512];
  snprintf(path, sizeof(path), "%s/frame.golden", dataDir);
  FILE* f = fopen(path, "rb");
  if (!f)
  {
    printf("[FAIL] %-19s missing golden file %s (run with --capture first)\n",
      "frame", path);
    return false;
  }
 
  char magic[4];
  uint32_t version = 0, rows = 0, values = 0, perRow = 0;
  const bool headerOk =
    fread(magic, 1, 4, f) == 4 && memcmp(magic, FRAME_MAGIC, 4) == 0 &&
    getU32(f, &version) && version == FRAME_VERSION &&
    getU32(f, &rows) &&
    getU32(f, &values) && values == FRAME_ROW_VALUES &&
    getU32(f, &perRow) && perRow == 2;
  if (!headerOk)
  {
    printf("[FAIL] %-19s bad golden header in %s\n", "frame", path);
    fclose(f);
    return false;
  }
 
  frameRender();
 
  if (rows != (uint32_t)frameRowCount)
  {
    printf("[FAIL] %-19s row count changed (golden %u, got %d)\n",
      "frame", rows, frameRowCount);
    fclose(f);
    return false;
  }
 
  static const char* const surface[2] = { "candidate", "reference" };
  for (int r = 0; r < frameRowCount; ++r)
  {
    for (int d = 0; d < 2; ++d)
    {
      uint64_t expected;
      if (!getU64(f, &expected))
      {
        printf("[FAIL] %-19s truncated golden file at row %d\n", "frame", r);
        fclose(f);
        return false;
      }
      if (expected != frameDigests[r][d])
      {
        printf("[FAIL] %-19s first divergence: row %d (%s) %s digest "
               "(expected 0x%016llx, got 0x%016llx)\n",
          "frame", r, frRowLabel[r], surface[d],
          (unsigned long long)expected, (unsigned long long)frameDigests[r][d]);
        fclose(f);
        return false;
      }
    }
  }
 
  if (frFailRow >= 0)
  {
    printf("[FAIL] %-19s candidate diverges from the reference at row %d (%s), "
           "field %s (cand %ld, ref %ld)\n",
      "frame", frFailRow, frRowLabel[frFailRow], frFailField, frFailCand, frFailRef);
    fclose(f);
    return false;
  }
 
  fclose(f);
  printf("[PASS] %-19s %3d rows\n", "frame", frameRowCount);
  return true;
}
 
/* Not a digest: the splash groups above call pico9918_splash_render directly, with the
   frame count as a parameter, so they pin the animation and nothing pins the gate that
   decides whether it is drawn at all. That gate reads the frame count, and validWrites
   latches once per run - so a reset rewinding only the animation leaves it shut. */
static bool resetCheck(void)
{
  if (pico9918_frame_count_impl() == 0)
  {
    printf("[FAIL] %-19s frame count was already zero, so this proves nothing\n", "reset");
    return false;
  }
 
  pico9918_reset();
 
  if (pico9918_frame_count_impl() != 0)
  {
    printf("[FAIL] %-19s pico9918_reset left the frame count at %d, so the splash gate stays shut\n",
           "reset", pico9918_frame_count_impl());
    return false;
  }
 
  printf("[PASS] %-19s splash gate reopens\n", "reset");
  return true;
}
 
/* The VR57 latch, which is (the last VR57 write was 0x1c) AND (this one is): two writes to
   get in, a third that changes nothing, and any other value - or any register write between
   the pair - that puts the device straight back out. A belt-and-braces second unlock is the
   case worth pinning, because an implementation that reads every VR57 write as a lock turns
   it into one and masks every extended register write after it down to VR0-VR7. */
static bool unlockCheck(void)
{
  static const struct
  {
    uint8_t reg;
    uint8_t value;
    bool unlocked;
    const char* what;
  } steps[] = {
    {57, 0x00, false, "a lock write leaves it locked"          },
    {57, 0x1c, false, "one 0x1c is not enough"                 },
    {57, 0x1c, true,  "two consecutive 0x1c unlock"            },
    {57, 0x1c, true,  "a redundant unlock is a no-op"          },
    {57, 0x00, false, "any other value locks on the spot"      },
    {57, 0x1c, false, "one 0x1c is not enough"                 },
    { 1, 0x00, false, "any other register write clears the run"},
    {57, 0x1c, false, "so that pair is not a consecutive one"  },
    {57, 0x00, false, "back to a known locked state"           },
    {57, 0x1f, false, "the low two bits are ignored"           },
    {57, 0x1f, true,  "so 0x1f unlocks exactly as 0x1c does"   },
  };
 
  for (int i = 0; i < (int)(sizeof(steps) / sizeof(steps[0])); ++i)
  {
    regWrite(steps[i].reg, steps[i].value);
    if (PICO9918_UNLOCKED(tms9918) != steps[i].unlocked)
    {
      printf("[FAIL] %-19s step %d, R%d = %02x: %s\n", "unlock", i + 1, steps[i].reg, steps[i].value,
             steps[i].what);
      return false;
    }
  }
 
  printf("[PASS] %-19s %d VR57 latch steps\n", "unlock", (int)(sizeof(steps) / sizeof(steps[0])));
  return true;
}
 
/* ---------------------------------------------------------------------------
 * Entry point
 * ------------------------------------------------------------------------- */
int main(int argc, char* argv[])
{
  bool capture = false;
  const char* dataDir = GOLDEN_DATA_DIR;
 
  for (int i = 1; i < argc; ++i)
  {
    if (strcmp(argv[i], "--capture") == 0)
    {
      capture = true;
    }
    else if (strcmp(argv[i], "--data") == 0 && i + 1 < argc)
    {
      dataDir = argv[++i];
    }
    else
    {
      printf("usage: golden_runner [--capture] [--data DIR]\n");
      return 2;
    }
  }
 
  pico9918_init();
 
  int failures = 0;
  for (int i = 0; i < SCENE_COUNT; ++i)
  {
    bool ok = capture ? captureScene(&scenes[i], dataDir)
                      : compareScene(&scenes[i], dataDir);
    if (!ok) ++failures;
  }
 
  /* the overlay surface, LAST: its panel cases reprogram registers and set the
   * PICO9918_CONF_DIAG* bytes, and the diag TU's IntString state and the splash offset are
   * module-global. Running it after the scenes keeps every scene independent of
   * whether the overlay ran, which is what lets the 14 committed goldens stay
   * byte-identical. Counted as one artifact alongside them. */
  const int artifacts = SCENE_COUNT + 2;
  if (!(capture ? overlayCapture(dataDir) : overlayCompare(dataDir))) ++failures;
 
  /* the frame surface, LAST. Its mapping group is pure arithmetic over its own
   * parameter struct, but the geometry group (since 4.6) writes R0/R49 and the frame
   * module's geometry globals, and the interrupt group writes R1 and the SR0 latch on
   * every row. Running the whole surface last means nothing else in the suite can see
   * that state, which is what keeps the 14 committed scene goldens and the overlay
   * artifact byte-identical. */
  if (!(capture ? frameCapture(dataDir) : frameCompare(dataDir))) ++failures;
 
  /* after the frame group, which is what leaves the counter above zero */
  if (!resetCheck()) ++failures;
 
  /* and after that reset, so the latch starts from a locked device */
  if (!unlockCheck()) ++failures;
 
  if (capture)
  {
    printf("%d artifact(s) captured to %s\n", artifacts - failures, dataDir);
  }
  else if (failures)
  {
    printf("%d of %d artifact(s) FAILED\n", failures, artifacts);
  }
  else
  {
    printf("all %d artifact(s) passed\n", artifacts);
  }
 
  return failures ? 1 : 0;
}