@bongos/core 1.18.3 → 1.18.18

package/tests/devbox_dmg_backdrop.mjs

@@ -0,0 +1,137 @@
+// tests/devbox_dmg_backdrop.mjs — the Dev Box DMG install-window backdrop is
+// BRANDING-DRIVEN, not baked in (task 1002372).
+//
+// modules/dev-box/app/scripts/gen-dmg-backdrop.py used to hardcode one host's
+// install screen — its palette, its archaic copy, its world motifs — so the
+// vanilla Cloud Bongos build shipped another instance's art. The generator now
+// reads the pack the same way gen-brand.js does (ADR 0145). The fitness identity
+// scan could not have caught this: it only reads .js/.html/.css, so a .py
+// generator is invisible to it — hence this test.
+//
+// It is a SOURCE + ARTIFACT test rather than an execution test on purpose: the
+// generator needs Pillow, which no manifest in this repo declares, so running it
+// is not available in the DB-free unit gate. What is checked instead is the part
+// that actually rots — that every colour literal left in the generator is the
+// NEUTRAL pack's own value (i.e. a fallback, not a brand), and that the committed
+// art still matches the DMG window the installer opens.
+//
+// Run:  node tests/devbox_dmg_backdrop.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const APP_DIR = path.join(REPO_ROOT, 'modules', 'dev-box', 'app');
+const GENERATOR = path.join(APP_DIR, 'scripts', 'gen-dmg-backdrop.py');
+
+const source = fs.readFileSync(GENERATOR, 'utf8');
+const neutral = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config', 'branding.neutral.json'), 'utf8'));
+
+// Strip Python comments + every docstring so rationale prose — which must be free to
+// name the old brand, or the artifact a fix deliberately stopped reading — never trips
+// a scan of the CODE (the stripCommentsForIdentity contract in scripts/gds/fitness.js,
+// applied to `#` comments and """…""" blocks).
+function codeOnly(text) {
+  return text
+    .replace(/"""[\s\S]*?"""/g, '')
+    .split(/\r?\n/)
+    .map((line) => line.replace(/(^|[^"'])#.*$/, '$1'))
+    .join('\n');
+}
+
+// COLOR_ROLES maps a theme.ui.colors key → the fallback used when a pack omits it.
+function parseColorRoles(text) {
+  const block = text.match(/COLOR_ROLES = \{([\s\S]*?)\n\}/);
+  assert.ok(block, 'gen-dmg-backdrop.py must declare a COLOR_ROLES map of theme.ui.colors keys');
+  const roles = {};
+  for (const [, key, hex] of block[1].matchAll(/"([A-Za-z]+)":\s*"(#[0-9a-fA-F]{3,6})"/g)) roles[key] = hex;
+  return roles;
+}
+
+test('the backdrop generator resolves the instance branding pack, like gen-brand.js', () => {
+  const code = codeOnly(source);
+  assert.match(code, /BONGOS_BRANDING_FILE/, 'honors the same env override gen-brand.js does');
+  assert.match(code, /config", "branding\.json/, 'reads the instance pack first');
+  assert.match(code, /config", "branding\.neutral\.json/, 'falls back to the neutral starter');
+});
+
+test('the product name + tagline come from the pack, never the committed build artifact', () => {
+  // src/brand.generated.json holds the same two strings, but it is a TRACKED file
+  // carrying the neutral values and nothing on the backdrop path regenerates it.
+  // Reading it made a host render draw its own palette + type under the neutral
+  // product's name — the pack has to decide both, the same way gen-brand.js does.
+  const code = codeOnly(source);
+  assert.doesNotMatch(code, /brand\.generated\.json/,
+    'the stale tracked artifact must not outrank the resolved pack');
+  assert.match(code, /identity\.get\("worldName"\)/, 'the product name derives from the pack identity');
+  assert.match(code, /\.get\("tagline"\)/, 'the subhead derives from the pack copy');
+});
+
+test('every colour literal in the generator is the NEUTRAL pack value, not a brand palette', () => {
+  const roles = parseColorRoles(source);
+  const packColors = neutral.theme.ui.colors;
+  assert.ok(Object.keys(roles).length >= 6, 'the art draws with a real palette, not one or two colours');
+  for (const [role, fallback] of Object.entries(roles)) {
+    assert.ok(packColors[role], `COLOR_ROLES key "${role}" must exist in config/branding.neutral.json theme.ui.colors`);
+    assert.equal(fallback.toLowerCase(), String(packColors[role]).toLowerCase(),
+      `the "${role}" fallback must equal the neutral pack's value — a divergent literal is a hardcoded brand`);
+  }
+  // …and no OTHER colour is hardcoded: the only hex literals are those fallbacks.
+  const hexes = codeOnly(source).match(/#[0-9a-fA-F]{6}\b/g) || [];
+  const allowed = new Set(Object.values(roles).map((h) => h.toLowerCase()));
+  for (const hex of hexes) {
+    assert.ok(allowed.has(hex.toLowerCase()), `hardcoded colour ${hex} — pull it from theme.ui.colors instead`);
+  }
+});
+
+test('a pack filling the documented theme surface leaves NO neutral colour on the canvas', () => {
+  // The one hole a fallback-equals-neutral check cannot see. `sea` used to be a
+  // role here, but gen-brand.js's :root emission — the surface a host pack author
+  // actually fills for this app — never mentioned it, so a fully-specified host
+  // pack still got Cloud Bongos sky-blue ringing the Applications drop target.
+  // A role is only safe to fall back on if the pack was PROMPTED to define it.
+  const genBrand = fs.readFileSync(path.join(APP_DIR, 'scripts', 'gen-brand.js'), 'utf8');
+  const themeCss = genBrand.match(/function buildThemeCss\([\s\S]*?\n\}/);
+  assert.ok(themeCss, 'gen-brand.js must declare buildThemeCss — it defines the app theme surface');
+  const documented = new Set([...themeCss[0].matchAll(/\bc\.([A-Za-z]+)\b/g)].map(([, k]) => k));
+  const roles = parseColorRoles(source);
+  for (const role of Object.keys(roles)) {
+    assert.ok(documented.has(role),
+      `COLOR_ROLES key "${role}" is not on the documented theme surface (gen-brand.js buildThemeCss) — ` +
+      'a host pack has no prompt to define it, so its neutral fallback would paint a Cloud Bongos colour ' +
+      'into a fully-specified host build');
+  }
+  // …and nothing reaches the canvas except through that map, so filling the
+  // documented roles overrides every literal in the file.
+  for (const [, key] of codeOnly(source).matchAll(/\bp\["([A-Za-z]+)"\]/g)) {
+    assert.ok(roles[key], `the render draws with p["${key}"], which COLOR_ROLES does not declare`);
+  }
+});
+
+test('the generator carries no host-brand copy or motif of its own', () => {
+  const code = codeOnly(source);
+  // The archaic install copy + the world motifs that shipped into the vanilla build.
+  for (const re of [/thine/i, /ashore/i, /amazonprimea/i, /off the boats/i, /meander/i, /greek/i, /marble/i]) {
+    assert.doesNotMatch(code, re, `host-brand literal ${re} must not appear in the generator's code`);
+  }
+  // Copy is derived from the pack (or overridden by it), never a fixed sentence.
+  assert.match(code, /dmgHeadline/, 'a pack may state its own headline');
+  assert.match(code, /copy\.get\("dmgSubhead"\)|dmgSubhead/, 'a pack may state its own subhead');
+});
+
+test('the committed art matches the DMG window the installer opens (660x400 @1x, @2x)', () => {
+  const dims = (file) => {
+    const buf = fs.readFileSync(path.join(APP_DIR, 'build-resources', file));
+    assert.equal(buf.subarray(1, 4).toString('latin1'), 'PNG', `${file} is a PNG`);
+    return [buf.readUInt32BE(16), buf.readUInt32BE(20)];
+  };
+  assert.deepEqual(dims('dmg-background.png'), [660, 400]);
+  assert.deepEqual(dims('dmg-background@2x.png'), [1320, 800]);
+  // The window/backdrop size is duplicated in dmgbuild-settings.py — drift there
+  // means Finder scales the art and the icon wells stop lining up with the icons.
+  const dmgbuild = fs.readFileSync(path.join(APP_DIR, 'scripts', 'dmgbuild-settings.py'), 'utf8');
+  assert.match(dmgbuild, /window_rect = \(\(150, 150\), \(660, 400\)\)/);
+});

package/tests/devbox_icons.mjs

@@ -0,0 +1,304 @@
+// tests/devbox_icons.mjs — the Dev Box app + tray icons are BRANDING-DRIVEN and
+// carry no host-brand motif (task 1002261).
+//
+// modules/dev-box/app/scripts/gen-icons.js used to draw one host's world into
+// every build — a shipping container with a wave footer, in a hardcoded palette —
+// so the vanilla Cloud Bongos app shipped another instance's emblem on its tray
+// and in its Dock. The motif is now a bongo pair (brand-neutral geometry) and the
+// palette is resolved from the instance pack the way gen-brand.js resolves it
+// (ADR 0145), matching what task 1002372 did for the DMG backdrop.
+//
+// SOURCE + ARTIFACT rather than an execution test, for two reasons: running the
+// generator REWRITES the committed art (so a test run would dirty the tree), and
+// it needs `sharp`, which config-wise belongs to the art-pipeline module — an
+// instance that doesn't enable that module need not have it installed, and this
+// file is not module-gated. What is checked instead is the part that actually
+// rots: that every colour literal left in the generator is the NEUTRAL pack's own
+// value, that nothing reaches the canvas except through the resolved palette, and
+// that the committed PNGs are still the neutral render at the sizes the app loads.
+//
+// Run:  node tests/devbox_icons.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const APP_DIR = path.join(REPO_ROOT, 'modules', 'dev-box', 'app');
+const GENERATOR = path.join(APP_DIR, 'scripts', 'gen-icons.js');
+const TRAY_DIR = path.join(APP_DIR, 'assets', 'tray');
+const BUILD_DIR = path.join(APP_DIR, 'build-resources');
+
+const STATES = ['off', 'on', 'busy', 'alert'];
+// macOS recolours a *Template.png itself (menu-bar light/dark, inverted when
+// selected) and discards whatever colour the source held. Pure black is an OS
+// requirement, not a brand choice — so it is the one literal exempt below.
+const MAC_TEMPLATE_BLACK = '#000000';
+
+const source = fs.readFileSync(GENERATOR, 'utf8');
+const neutral = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config', 'branding.neutral.json'), 'utf8'));
+
+// Strip comments so rationale prose — which must be free to name the motif a fix
+// deliberately removed, or the artifact it deliberately stopped reading — never
+// trips a scan of the CODE (the stripCommentsForIdentity contract in
+// scripts/gds/fitness.js; the `//` strip is `://`-safe so a URL stays intact).
+function codeOnly(text) {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .split(/\r?\n/)
+    .map((line) => line.replace(/(^|[^:])\/\/.*$/, '$1'))
+    .join('\n');
+}
+const code = codeOnly(source);
+
+// Grab a top-level `const NAME = { … }` / `[ … ]` by brace balance, so the tests
+// below don't depend on how the declaration happens to be wrapped.
+function declBlock(name) {
+  const start = code.indexOf(`const ${name} = `);
+  assert.ok(start >= 0, `gen-icons.js must declare ${name}`);
+  const open = code.indexOf('{', start);
+  let depth = 0;
+  for (let i = open; i < code.length; i++) {
+    if (code[i] === '{') depth += 1;
+    else if (code[i] === '}' && (depth -= 1) === 0) return code.slice(open, i + 1);
+  }
+  throw new Error(`gen-icons.js: unbalanced braces in ${name}`);
+}
+
+// COLOR_ROLES maps a theme.ui.colors key → the fallback used when a pack omits it.
+function colorRoles() {
+  const roles = {};
+  for (const [, key, hex] of declBlock('COLOR_ROLES').matchAll(/([A-Za-z]+):\s*'(#[0-9a-fA-F]{3,6})'/g)) roles[key] = hex;
+  assert.ok(Object.keys(roles).length >= 6, 'the art draws with a real palette, not one or two colours');
+  return roles;
+}
+
+// `{ '#': p.accentDeep, f: p.accent }` → { '#': 'accentDeep', f: 'accent' }
+function inkRoles(block) {
+  const out = {};
+  for (const [, quoted, bare, role] of block.matchAll(/(?:'([^']*)'|([A-Za-z]+))\s*:\s*p\.([A-Za-z]+)/g)) {
+    out[quoted ?? bare] = role;
+  }
+  return out;
+}
+
+function trayGrids() {
+  const grids = {};
+  for (const [, state, body] of declBlock('GRIDS').matchAll(/(off|on|busy|alert):\s*\[([\s\S]*?)\]/g)) {
+    grids[state] = [...body.matchAll(/'([^']*)'/g)].map(([, row]) => row);
+  }
+  return grids;
+}
+
+const inksOf = (grid) => new Set(grid.join('').split('').filter((c) => c !== '.'));
+const sorted = (set) => [...set].sort().join('');
+
+// --- a minimal PNG reader (8-bit RGBA, non-interlaced — what the generator emits).
+// Deliberately dependency-free: this gate must run on an instance that has no
+// image library installed.
+function readRgba(file) {
+  const buf = fs.readFileSync(file);
+  assert.equal(buf.subarray(1, 4).toString('latin1'), 'PNG', `${path.basename(file)} is a PNG`);
+  const width = buf.readUInt32BE(16);
+  const height = buf.readUInt32BE(20);
+  assert.equal(buf[24], 8, `${path.basename(file)} is 8-bit`);
+  assert.equal(buf[25], 6, `${path.basename(file)} is RGBA`);
+  assert.equal(buf[28], 0, `${path.basename(file)} is non-interlaced`);
+  const idat = [];
+  for (let o = 8; o < buf.length;) {
+    const len = buf.readUInt32BE(o);
+    const type = buf.toString('latin1', o + 4, o + 8);
+    if (type === 'IDAT') idat.push(buf.subarray(o + 8, o + 8 + len));
+    o += 12 + len;
+    if (type === 'IEND') break;
+  }
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const bpp = 4;
+  const stride = width * bpp;
+  const out = Buffer.alloc(height * stride);
+  const paeth = (a, b, c) => {
+    const da = Math.abs(b - c);        // |p - a| where p = a + b - c
+    const db = Math.abs(a - c);        // |p - b|
+    const dc = Math.abs(a + b - 2 * c); // |p - c|
+    return da <= db && da <= dc ? a : db <= dc ? b : c;
+  };
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const line = raw.subarray(y * (stride + 1) + 1, y * (stride + 1) + 1 + stride);
+    for (let i = 0; i < stride; i++) {
+      const a = i >= bpp ? out[y * stride + i - bpp] : 0;
+      const b = y > 0 ? out[(y - 1) * stride + i] : 0;
+      const c = i >= bpp && y > 0 ? out[(y - 1) * stride + i - bpp] : 0;
+      let v = line[i];
+      if (filter === 1) v += a;
+      else if (filter === 2) v += b;
+      else if (filter === 3) v += (a + b) >> 1;
+      else if (filter === 4) v += paeth(a, b, c);
+      out[y * stride + i] = v & 255;
+    }
+  }
+  return { width, height, data: out };
+}
+
+// Every colour that is actually painted (alpha > 0), lowercased.
+function opaqueColors(file) {
+  const { width, height, data } = readRgba(file);
+  const seen = new Set();
+  for (let i = 0; i < width * height; i++) {
+    if (data[i * 4 + 3] === 0) continue;
+    seen.add(`#${[0, 1, 2].map((j) => data[i * 4 + j].toString(16).padStart(2, '0')).join('')}`);
+  }
+  return seen;
+}
+
+test('the icon generator resolves the instance branding pack, like gen-brand.js', () => {
+  assert.match(code, /BONGOS_BRANDING_FILE/, 'honors the same env override gen-brand.js does');
+  assert.match(code, /'config', 'branding\.json'/, 'reads the instance pack first');
+  assert.match(code, /'config', 'branding\.neutral\.json'/, 'falls back to the neutral starter');
+  assert.match(code, /branding\.theme/, 'the palette comes from the pack theme');
+  assert.match(code, /\.colors/, '…specifically theme.ui.colors');
+});
+
+test('the palette comes from the pack, never the committed build artifact', () => {
+  // src/brand.generated.json carries colours too, but it is a TRACKED file holding
+  // the neutral values and nothing on the icon path regenerates it. Preferring it
+  // let a host render draw the host palette under the neutral product's name once
+  // already (task 1002372) — the pack has to decide, every time.
+  assert.doesNotMatch(code, /brand\.generated\.json/,
+    'the stale tracked artifact must not outrank the resolved pack');
+});
+
+test('every colour literal in the generator is the NEUTRAL pack value, not a brand palette', () => {
+  const roles = colorRoles();
+  const packColors = neutral.theme.ui.colors;
+  for (const [role, fallback] of Object.entries(roles)) {
+    assert.ok(packColors[role], `COLOR_ROLES key "${role}" must exist in config/branding.neutral.json theme.ui.colors`);
+    assert.equal(fallback.toLowerCase(), String(packColors[role]).toLowerCase(),
+      `the "${role}" fallback must equal the neutral pack's value — a divergent literal is a hardcoded brand`);
+  }
+  // …and no OTHER colour is hardcoded. The one exemption is the macOS template
+  // black, which is an OS requirement (see MAC_TEMPLATE_BLACK above), so it is
+  // also pinned to appear ONLY in the template palette.
+  const allowed = new Set([...Object.values(roles).map((h) => h.toLowerCase()), MAC_TEMPLATE_BLACK]);
+  const withoutGrids = code.replace(declBlock('GRIDS'), '');
+  for (const hex of withoutGrids.match(/#[0-9a-fA-F]{6}\b/g) || []) {
+    assert.ok(allowed.has(hex.toLowerCase()), `hardcoded colour ${hex} — pull it from theme.ui.colors instead`);
+  }
+  const macBlock = declBlock('MAC');
+  const macHexes = [...macBlock.matchAll(/'(#[0-9a-fA-F]{6})'/g)].map(([, h]) => h.toLowerCase());
+  assert.ok(macHexes.length > 0, 'the macOS template palette must state its own black');
+  for (const hex of macHexes) {
+    assert.equal(hex, MAC_TEMPLATE_BLACK, 'a *Template.png must be pure black — the OS recolours it');
+  }
+  const nonMacBlack = withoutGrids.replace(macBlock, '').match(/#0{6}\b/g) || [];
+  assert.equal(nonMacBlack.length, 0, 'black outside the macOS template palette is a hardcoded colour, not an OS rule');
+});
+
+test('a pack filling the documented theme surface leaves NO neutral colour on the canvas', () => {
+  // The hole a fallback-equals-neutral check cannot see. A role is only safe to
+  // fall back on if the host pack author was PROMPTED to define it — and the
+  // prompt is gen-brand.js's :root emission, the app's own theme surface. A role
+  // outside it (this is what `sea` did to the DMG backdrop) keeps its Cloud
+  // Bongos value even in a fully-specified host build.
+  const genBrand = fs.readFileSync(path.join(APP_DIR, 'scripts', 'gen-brand.js'), 'utf8');
+  const themeCss = genBrand.match(/function buildThemeCss\([\s\S]*?\n\}/);
+  assert.ok(themeCss, 'gen-brand.js must declare buildThemeCss — it defines the app theme surface');
+  const documented = new Set([...themeCss[0].matchAll(/\bc\.([A-Za-z]+)\b/g)].map(([, k]) => k));
+  const roles = colorRoles();
+  for (const role of Object.keys(roles)) {
+    assert.ok(documented.has(role),
+      `COLOR_ROLES key "${role}" is not on the documented theme surface (gen-brand.js buildThemeCss) — ` +
+      'a host pack has no prompt to define it, so its neutral fallback would paint a Cloud Bongos colour ' +
+      'into a fully-specified host build');
+  }
+  // …and nothing reaches the canvas except through that map, so filling the
+  // documented roles overrides every literal in the file.
+  for (const [, key] of code.matchAll(/\bp\.([A-Za-z]+)\b/g)) {
+    assert.ok(roles[key], `the render draws with p.${key}, which COLOR_ROLES does not declare`);
+  }
+  const used = new Set([...code.matchAll(/\bp\.([A-Za-z]+)\b/g)].map(([, k]) => k));
+  for (const role of Object.keys(roles)) {
+    assert.ok(used.has(role), `COLOR_ROLES declares "${role}" but nothing draws with it — drop it or use it`);
+  }
+});
+
+test('the generator carries no host-brand motif of its own', () => {
+  for (const re of [/off the boats/i, /amazonprimea/i, /shipping[- ]container/i, /greek/i, /meander/i, /parchment/i]) {
+    assert.doesNotMatch(code, re, `host-brand literal ${re} must not appear in the generator's code`);
+  }
+});
+
+test('the four tray states are 16x16 and differ in SHAPE, not only colour', () => {
+  // The macOS template icons are monochrome — the OS throws the colour away — so
+  // two states that differ only in their palette are the SAME icon on a Mac.
+  const grids = trayGrids();
+  assert.deepEqual(Object.keys(grids).sort(), [...STATES].sort(), 'exactly the four tray states');
+  for (const [state, grid] of Object.entries(grids)) {
+    assert.equal(grid.length, 16, `${state} grid is 16 rows`);
+    for (const row of grid) assert.equal(row.length, 16, `${state} grid rows are 16 cells`);
+  }
+  const silhouette = (grid) => grid.join('\n').replace(/[^.]/g, '#');
+  for (let i = 0; i < STATES.length; i++) {
+    for (let j = i + 1; j < STATES.length; j++) {
+      assert.notEqual(silhouette(grids[STATES[i]]), silhouette(grids[STATES[j]]),
+        `tray states "${STATES[i]}" and "${STATES[j]}" share one silhouette — indistinguishable as macOS templates`);
+    }
+  }
+});
+
+test('every mark the art draws has a colour, and every colour marks something', () => {
+  // A mark with no palette entry renders as a hole; a palette entry with no mark
+  // is dead weight that outlives the shape it was for.
+  const grids = trayGrids();
+  const macInks = new Set(Object.keys(inkRoles(declBlock('MAC').replace(/'#[0-9a-fA-F]{6}'/g, 'p.macBlack'))));
+  assert.equal(sorted(macInks), sorted(new Set(STATES.flatMap((s) => [...inksOf(grids[s])]))),
+    'the macOS template palette must cover exactly the inks the grids use');
+  const win = declBlock('WIN');
+  for (const [, state, block] of win.matchAll(/(off|on|busy|alert):\s*(\{[^}]*\})/g)) {
+    assert.equal(sorted(new Set(Object.keys(inkRoles(block)))), sorted(inksOf(grids[state])),
+      `the win-${state} palette must cover exactly the inks the ${state} grid uses`);
+  }
+  // Same contract for the app icon, whose grid is built imperatively.
+  const appGrid = code.slice(code.indexOf('function buildAppGrid('), code.indexOf('async function main('));
+  const appInks = new Set([...appGrid.matchAll(/'([a-z])'/g)].map(([, c]) => c));
+  assert.equal(sorted(appInks), sorted(new Set(Object.keys(inkRoles(declBlock('APP_PALETTE'))))),
+    'the app palette must cover exactly the inks buildAppGrid draws');
+});
+
+test('the committed PNGs are the 13 files the app and electron-builder load', () => {
+  const dims = (file) => {
+    const buf = fs.readFileSync(file);
+    assert.equal(buf.subarray(1, 4).toString('latin1'), 'PNG', `${path.basename(file)} is a PNG`);
+    return [buf.readUInt32BE(16), buf.readUInt32BE(20)];
+  };
+  // electron-builder derives .icns/.ico from this one, so it must stay 1024².
+  assert.deepEqual(dims(path.join(BUILD_DIR, 'icon.png')), [1024, 1024]);
+  for (const state of STATES) {
+    assert.deepEqual(dims(path.join(TRAY_DIR, `mac-${state}Template.png`)), [16, 16]);
+    assert.deepEqual(dims(path.join(TRAY_DIR, `mac-${state}Template@2x.png`)), [32, 32]);
+    assert.deepEqual(dims(path.join(TRAY_DIR, `win-${state}.png`)), [32, 32]);
+  }
+});
+
+test('the committed art is the NEUTRAL render — no host palette was checked in', () => {
+  // The source checks above prove the generator READS the pack; only the pixels
+  // prove the committed artifact is the vanilla one. Someone rendering with their
+  // own config/branding.json present and committing the result is exactly the
+  // failure this catches.
+  const packValues = new Set(Object.values(neutral.theme.ui.colors).map((h) => String(h).toLowerCase()));
+  for (const state of STATES) {
+    for (const file of [`mac-${state}Template.png`, `mac-${state}Template@2x.png`]) {
+      assert.deepEqual([...opaqueColors(path.join(TRAY_DIR, file))], [MAC_TEMPLATE_BLACK],
+        `${file} must be pure black + alpha — the OS recolours a template icon`);
+    }
+    for (const hex of opaqueColors(path.join(TRAY_DIR, `win-${state}.png`))) {
+      assert.ok(packValues.has(hex), `win-${state}.png paints ${hex}, which is not a config/branding.neutral.json colour`);
+    }
+  }
+  for (const hex of opaqueColors(path.join(BUILD_DIR, 'icon.png'))) {
+    assert.ok(packValues.has(hex), `icon.png paints ${hex}, which is not a config/branding.neutral.json colour`);
+  }
+});