Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

30.5 KB
Raw Blame
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  Whether the editor's VISUAL layer holds the contracts it was built on —
 *        colour, spacing, type, icons and which component a control is.
 *
 * Every invariant in this repository has a gate except the visual layer, which
 * is why the visual layer is the one that drifted: `--text-faint` shipped at
 * 3.26:1 on a panel — under the floor for body text, as the colour of most
 * labels in the editor — and a chart series ran on a 100%-saturated viewport
 * colour.
 *
 * Four claims are absolute: text stays readable on the surfaces it sits on, a
 * panel label stays quieter than the viewport, a token that NAMES a thing only
 * colours that thing, and a tip is the editor's rather than the OS's `title=`. That a token EXISTS at all is check-css-vars.mjs —
 * its subject is every reader of the editor's variables, plugins and docs too.
 *
 * Six are RATCHETS, because each is hundreds of declarations deep and a gate
 * that reddens on all of them gets switched off. Banked, may fall, never rise:
 * spacing off the grid `--u` declares; colour literals where a token belongs; raw
 * font-size; how many distinct icon sizes and stroke widths exist at all; and
 * hand-rolled `<button>` where the editor has a component.
 *
 *   node tools/check-theme.mjs            # check
 *   node tools/check-theme.mjs --update   # bank the current state
 */
import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const TOKENS = 'desktop/src/theme/tokens.css';

/** WCAG 2.x relative luminance, then the contrast ratio between two sRGB hexes. */
const channel = (c) => (c / 255 <= 0.04045 ? c / 255 / 12.92 : ((c / 255 + 0.055) / 1.055) ** 2.4);
const luminance = (hex) => {
  const h = hex.replace('#', '');
  const [r, g, b] = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
};
const contrast = (a, b) => {
  const [x, y] = [luminance(a), luminance(b)];
  return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
};

/** Body text, per WCAG AA and Unity's own editor accessibility page. */
const FLOOR = 4.5;
/**
 * The surfaces text is READ on: the panel body and the raised strip above it.
 * `--srf-4` and up are hover and popover fills, where the ramp is lower by
 * construction — holding those to the body floor would mean one flat text
 * colour, so they are counted and reported, not enforced.
 */
const READING_SURFACES = ['--srf-2', '--srf-3'];

const css = readFileSync(path.join(ROOT, TOKENS), 'utf8');
const valueOf = (name) => {
  const hit = new RegExp(`^\\s*${name}:\\s*(#[0-9a-fA-F]{6})\\b`, 'm').exec(css);
  return hit ? hit[1] : null;
};

const textTokens = [...css.matchAll(/^\s*(--text(?:-[a-z]+)?):\s*(#[0-9a-fA-F]{6})\b/gm)]
  .map(([, name, hex]) => ({ name, hex }));

const problems = [];
if (textTokens.length === 0) problems.push(`${TOKENS}: no --text* tokens found — the ramp cannot be read`);

const reported = [];
for (const surface of READING_SURFACES) {
  const bg = valueOf(surface);
  if (!bg) { problems.push(`${TOKENS}: ${surface} is not a hex value — the ramp cannot be judged against it`); continue; }
  for (const { name, hex } of textTokens) {
    const ratio = contrast(hex, bg);
    reported.push({ surface, name, ratio });
    if (ratio < FLOOR) {
      problems.push(`${TOKENS}: ${name} (${hex}) is ${ratio.toFixed(2)}:1 on ${surface} (${bg}) — body text needs ${FLOOR}:1`);
    }
  }
}

/**
 * `--cat-*` labels content on a PANEL; `--gizmo-*` draws over a scene and has to
 * win against it. A deliberate borrowing is the identity rule's business, below.
 */
const saturation = (hex) => {
  const h = hex.replace('#', '');
  const [r, g, b] = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
  const [hi, lo] = [Math.max(r, g, b), Math.min(r, g, b)];
  if (hi === lo) return 0;
  const l = (hi + lo) / 2;
  return Math.round(((hi - lo) / (l > 0.5 ? 2 - hi - lo : hi + lo)) * 100);
};

/**
 * Only the panel ramp is held. The reverse — "a gizmo must be vivid" — was
 * written here and measured false: `--gizmo-shadow` is 19%, `--gizmo-stream-cell`
 * 17%, grey on purpose. A gizmo's saturation follows what it draws.
 */
const PANEL_CEILING = 80;

// `--asset-*` labels content in the same place and by the same rule — a content
// browser icon and a component header bar sit on the same panel.
const content = [...css.matchAll(/^\s*(--(?:cat|asset)-[a-z-]+):\s*(#[0-9a-fA-F]{6})\b/gm)]
  .map(([, name, hex]) => ({ name, hex, sat: saturation(hex) }));

if (content.length === 0) problems.push(`${TOKENS}: no --cat-*/--asset-* tokens found — the content ramp cannot be read`);
for (const { name, hex, sat } of content) {
  if (sat >= PANEL_CEILING) {
    problems.push(`${TOKENS}: ${name} (${hex}) is ${sat}% saturated — a panel label stays under ${PANEL_CEILING}%, that is viewport brightness`);
  }
}

/**
 * A token whose whole value is `var(--other)` is a second name for a value that
 * already has one. Three such vocabularies had grown over this palette, and one
 * of them put `--border` (the dark groove) beside `--border-line` (the light
 * hairline) — one word over two roles the real names keep apart.
 */
for (const m of css.matchAll(/^\s*(--[a-z0-9-]+)\s*:\s*var\(\s*(--[a-z0-9-]+)\s*\)\s*;/gm)) {
  problems.push(`${TOKENS}: ${m[1]} is only another name for ${m[2]} — `
    + 'one value, one name; use the one that holds it');
}

/**
 * An identity token names a thing, not a role: `--ax-x` is the X axis,
 * `--gizmo-collider` is a collider, `--sel` is the selection. Colouring anything
 * else with one is a claim about what the colour means, and the claim is false —
 * which is how a record button came to be X-axis red and a chart series came to
 * be particle amber. Role tokens (`--acc`, `--warn`, `--text-dim`) are the
 * opposite and may colour anything in that role.
 *
 * A panel may still carry one, but only as a legend: the World panel's residency
 * chips are the colours the viewport draws those cells in, and any other colour
 * there would make the legend lie. A gate cannot tell a legend from a theft, so
 * each place that may hold one is listed with the reason it names the same thing.
 */
const NAMES_THE_SAME_THING = [
  ['.viewport__', 'the scene canvas and the gizmos drawn on it'],
  ['.vp-', "the viewport's own HUD — axis ball, coordinate readout"],
  ['.play-ov', "the play-mode inspection overlay's gizmo arms, drawn over the running game"],
  ['.ts-p', 'the tileset collision-polygon editor, a canvas of its own'],
  ['.ax.', "an Inspector vec field's axis letters: the legend for the gizmo's arms"],
  ['.world__', "the World panel's residency colours — its key, a cell's dot and state word — for what the viewport draws"],
  ['.gi-tag', "the GripProfile section's hand tags: the legend for the palm markers the viewport draws in those colours"],
  ['components/GizmoReadout.tsx', 'the drag readout carries the dot of the gizmo axis it reports'],
  ['panels/SequencerCurve.tsx', 'a curve channel IS the axis channel, so it takes the axis colour'],
];

/**
 * Every identity family with the thing it names and the places that thing is
 * drawn. A chrome colour that turns out to name one thing belongs here: that is
 * what "the chrome has one colour" means once it is true.
 */
const IDENTITIES = [
  {
    token: /^--(?:sel|sel-hi|sel-soft|gizmo-[a-z-]+|ax-[xyz])$/,
    names: "the viewport's selection, gizmos and axes",
    places: NAMES_THE_SAME_THING,
  },
  {
    token: /^--info-warm(?:-soft|-line)?$/,
    names: 'a prefab',
    places: [
      ['.row.prefab', 'Outliner rows that are prefab instances'],
      ['.prefab-mode-bar', 'the bar that says a prefab is open for editing'],
      ['.menubar-title .prefab-crumb-tag', 'the title crumb of an open prefab'],
      ['.shell--prefab', 'the workspace frame while a prefab is open'],
    ],
  },
  {
    token: /^--vram$/,
    names: "the profiler's GPU series",
    places: [['panels/ProfilerPanel.tsx', 'the chart that draws that series']],
  },
];
const identityOf = (name) => IDENTITIES.find((family) => family.token.test(name));

/** Comments out, offsets kept, so a selector is never read out of one. */
const uncomment = (t) => t.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));

/** The selector a declaration sits under: back to its `{`, then to where that rule began. */
const selectorAt = (text, at) => {
  const open = text.lastIndexOf('{', at);
  if (open < 0) return '';
  const began = Math.max(text.lastIndexOf('}', open), text.lastIndexOf('{', open - 1), -1);
  return text.slice(began + 1, open).trim().replace(/\s+/g, ' ');
};

/** A keyframe stop's selector is `0%`, which says nothing; its animation's name does. */
const siteAt = (text, at) => {
  const selector = selectorAt(text, at);
  if (!/^(?:from|to|\d+%)/.test(selector)) return selector;
  return selectorAt(text, text.lastIndexOf('{', text.lastIndexOf('{', at) - 1));
};

const SRC_DIR = path.join(ROOT, 'desktop', 'src');
const everyFile = (dir, out = []) => {
  for (const e of readdirSync(dir, { withFileTypes: true })) {
    const p = path.join(dir, e.name);
    if (e.isDirectory()) everyFile(p, out);
    else if (/\.(css|ts|tsx)$/.test(e.name)) out.push(p);
  }
  return out;
};

let identityUses = 0;
for (const file of everyFile(SRC_DIR)) {
  const rel = path.relative(SRC_DIR, file).replaceAll(path.sep, '/');
  const text = uncomment(readFileSync(file, 'utf8'));
  for (const m of text.matchAll(/var\(\s*(--[a-z0-9-]+)/g)) {
    const family = identityOf(m[1]);
    if (!family) continue;
    identityUses += 1;
    const line = text.slice(0, m.index).split('\n').length;
    // A script colouring an element has no selector, so its site is the file.
    const isCss = rel.endsWith('.css');
    const parts = isCss ? siteAt(text, m.index).split(',').map((s) => s.trim()).filter(Boolean) : [rel];
    const strayed = parts.filter((p) => !family.places.some(([where]) => p.startsWith(where)));
    if (parts.length > 0 && strayed.length === 0) continue;
    const site = parts.length === 0 ? '(no selector)' : strayed.join(', ');
    problems.push(`desktop/src/${rel}:${line}: ${site} is coloured with ${m[1]}, which names `
      + `${family.names} — an identity token only colours the thing it names`);
  }
}

/**
 * Spacing that is not on the grid, per file. A count rather than a line, so
 * inserting a rule does not churn the baseline; per file, so a fix in one place
 * cannot be spent on a regression in another.
 */
const THEME_DIR = path.join(ROOT, 'desktop', 'src', 'theme');
const BASELINE = path.join(ROOT, 'tools', 'baselines', 'theme-drift.json');

/**
 * The spacing grid, read off the token that declares it rather than repeated
 * here: `--u` had no other reader, so the theme's own statement of its grid and
 * the rule that enforces it could have disagreed with nothing to notice.
 */
const GRID = (() => {
  const px = /--u:\s*(\d+)px/.exec(readFileSync(path.join(THEME_DIR, 'tokens.css'), 'utf8'))?.[1];
  if (!px) throw new Error('desktop/src/theme/tokens.css declares no --u: the spacing grid has no author');
  return Number(px);
})();

const offGridByFile = () => {
  const out = {};
  for (const f of readdirSync(THEME_DIR).filter((n) => n.endsWith('.css'))) {
    const text = readFileSync(path.join(THEME_DIR, f), 'utf8');
    let n = 0;
    for (const m of text.matchAll(/(?:gap|padding|margin)[a-z-]*:\s*([^;}]+)/g)) {
      // A fractional value is centring arithmetic (-4.5px on a 9px dot), not a
      // spacing step, and read as `5px` it was counted as one.
      for (const px of m[1].matchAll(/(?<![\d.])(\d+)px/g)) {
        const v = Number(px[1]);
        // 1px is not a step of the grid but a seam: the hairline between joined
        // segments (`gap: 1px` showing the groove through), a border's overlap
        // (`margin: -1px`), a tag's optical inset. Unreal draws its seams the same.
        if (v === 1) continue;
        if (v !== 0 && v % GRID !== 0) n++;
      }
    }
    if (n > 0) out[f] = n;
  }
  return out;
};

/** Colour written where a token belongs. tokens.css is the one place they are
 *  DEFINED, so it is the one file exempt. */
/**
 * Colours that are what a control SHOWS rather than a choice from the palette,
 * by file then selector, each with the reason. `rgba(var(--x), a)` reads a token
 * and is not counted; neither is a colour inside a comment.
 */
const THEME_NOT_THE_PALETTE = {
  'inspector.css': { '.cp-hue': 'the hue slider draws the spectrum itself' },
};

const colourLiteralsByFile = () => {
  const out = {};
  for (const f of readdirSync(THEME_DIR).filter((n) => n.endsWith('.css') && n !== 'tokens.css')) {
    const text = uncomment(readFileSync(path.join(THEME_DIR, f), 'utf8'));
    const exempt = THEME_NOT_THE_PALETTE[f] ?? {};
    let n = 0;
    for (const m of text.matchAll(/#[0-9a-fA-F]{3,8}\b|\brgba?\((?!\s*var\()/g)) {
      if (!(selectorAt(text, m.index) in exempt)) n += 1;
    }
    if (n > 0) out[f] = n;
  }
  return out;
};

/**
 * Glyphs that are drawn as ICONS, each with the reason. Their size is set by the
 * shape they sit in, not by the reading ramp, so a step of the type scale would
 * be a wrong answer rather than a tidier one. Keyed by file, then selector.
 */
const NOT_TYPE = {
  'launcher.css': {
  },
  'viewport.css': {
    '.vp-axes .va-end text': 'an axis letter inside its 84px gizmo knob, sized to the circle',
  },
  'tileset.css': {
    '.ts-acell.has-anim::after': 'the ▶ badge in a tile cell\'s corner, sized to the cell',
  },
  'controls.css': {
    '.dirty-dot': 'the ● unsaved marker, relative so it follows whatever title it sits in',
  },
};

/** A font-size given as a number rather than a step of the type scale. */
const rawFontSizeByFile = () => {
  const out = {};
  for (const f of readdirSync(THEME_DIR).filter((n) => n.endsWith('.css') && n !== 'tokens.css')) {
    const text = uncomment(readFileSync(path.join(THEME_DIR, f), 'utf8'));
    const exempt = NOT_TYPE[f] ?? {};
    const seen = new Set();
    let n = 0;
    for (const m of text.matchAll(/font-size:\s*\d/g)) {
      const selector = selectorAt(text, m.index);
      if (selector in exempt) seen.add(selector);
      else n += 1;
    }
    for (const selector of Object.keys(exempt)) {
      if (!seen.has(selector)) {
        problems.push(`desktop/src/theme/${f}: ${selector} is declared an icon glyph but sets no raw `
          + 'font-size any more — drop it from NOT_TYPE');
      }
    }
    if (n > 0) out[f] = n;
  }
  return out;
};

/**
 * How many distinct sizes and stroke widths the icons use.
 *
 * Counted only for names the file itself imported from lucide: `size={44}` on an
 * asset thumbnail and `strokeWidth={12}` on an SVG hit area are not icons, and
 * counting them made the first measurement of this wrong.
 */
const iconScale = () => {
  const sizes = new Set();
  const strokes = new Set();
  const walk = (dir) => {
    for (const e of readdirSync(dir, { withFileTypes: true })) {
      const full = path.join(dir, e.name);
      if (e.isDirectory()) { walk(full); continue; }
      if (!/\.tsx?$/.test(e.name)) continue;
      const text = readFileSync(full, 'utf8');
      const names = new Set();
      for (const m of text.matchAll(/import\s*\{([^}]*)\}\s*from\s*'lucide-react'/g)) {
        for (const raw of m[1].split(',')) {
          const n = raw.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop().trim();
          if (n && /^[A-Z]/.test(n)) names.add(n);
        }
      }
      if (names.size === 0) continue;
      for (const m of text.matchAll(/<([A-Z][A-Za-z0-9]*)\b([^>]*)>/g)) {
        if (!names.has(m[1])) continue;
        const size = /\bsize=\{(\d+(?:\.\d+)?)\}/.exec(m[2]);
        const stroke = /\bstrokeWidth=\{(\d+(?:\.\d+)?)\}/.exec(m[2]);
        if (size) sizes.add(size[1]);
        if (stroke) strokes.add(stroke[1]);
      }
    }
  };
  walk(path.join(ROOT, 'desktop', 'src'));
  return { sizes: [...sizes].sort((a, b) => a - b), strokes: [...strokes].sort((a, b) => a - b) };
};

/**
 * A DOM element's `title=` is the operating system's tooltip: unthemed, unzoomed,
 * and drawn in the wrong window from a popout. The editor's is `data-tip`
 * (TipLayer), plus an `aria-label` where the tip was the control's only name.
 * An iframe's title is its accessible name, not a tip.
 */
const nativeTitles = () => {
  const out = [];
  for (const file of everyFile(SRC_DIR)) {
    if (!file.endsWith('.tsx')) continue;
    const text = readFileSync(file, 'utf8');
    for (const m of text.matchAll(/<([a-z][a-z0-9]*)\b([^<]*?)\/?>/gs)) {
      if (m[1] === 'iframe' || !/(?<![\w-])title=/.test(m[2])) continue;
      const line = text.slice(0, m.index).split('\n').length;
      out.push(`desktop/src/${path.relative(SRC_DIR, file).replaceAll(path.sep, '/')}:${line}`);
    }
  }
  return out;
};

/** The shared controls themselves: the one `<button>` each renders is the component. */
const PRIMITIVES = new Set([
  'components/Button.tsx', 'components/IconButton.tsx', 'components/Menu.tsx',
  'components/Select.tsx', 'components/Segmented.tsx',
]);

/** A button that declares itself an item of a list, tab strip or menu is not an action button —
 *  nor is one that marks the current page of a navigation (`aria-current`). */
const NAV_ITEM = /\baria-current=/;
const ITEM_ROLE = /\brole=(?:"|\{?['"`])(?:option|tab|menuitem|menuitemcheckbox|menuitemradio|radio)\b/;

/**
 * Buttons the editor hand-rolled rather than took from `<Button>`/`<IconButton>`.
 * A ratchet, not a rule: a raw `<button>` in a tile cell is right.
 */
const handRolledByFile = () => {
  const out = {};
  const walk = (dir) => {
    for (const e of readdirSync(dir, { withFileTypes: true })) {
      const full = path.join(dir, e.name);
      if (e.isDirectory()) { walk(full); continue; }
      if (!/\.tsx$/.test(e.name)) continue;
      const text = readFileSync(full, 'utf8');
      const rel = path.relative(path.join(ROOT, 'desktop', 'src'), full).replaceAll(path.sep, '/');
      if (PRIMITIVES.has(rel)) continue;
      const n = [...text.matchAll(/<button\b([^<]*?)\/?>/gs)].filter((m) => !ITEM_ROLE.test(m[1]) && !NAV_ITEM.test(m[1])).length;
      if (n > 0) out[rel] = n;
    }
  };
  walk(path.join(ROOT, 'desktop', 'src'));
  return out;
};

/**
 * Files whose colours are NOT the palette's to hold, each with the reason —
 * without this the ratchet's target of zero is unreachable, and a target nobody
 * can reach is not one anybody aims at.
 */
const NOT_THE_PALETTE = {
  'settings/editorSettings.ts':
    "the accent setting's default and the swatches it offers are values a person picks from; "
    + 'tests/theme-tokens.test.ts holds the default to --star',
  'tileset/TilesetCommands.ts': "default colours written into a new Wang set's data, which the tileset then owns",
  'tools/tileMath.ts': "default colours written into a new terrain's data, which the tileset then owns",
  'components/SettingsRow.tsx': "'#00000000' is a colour input's empty value, not a colour anything is drawn in",
  'panels/ProfilerPanel.tsx':
    'NO_TOKEN is off the palette on purpose: a var() that names nothing paints a grey someone notices',
  'components/LoadingScreen.tsx':
    'the Estella mark itself (see favicon.svg). Its blue and --star came from the same place,'
    + ' but a logo that moves when the accent moves is not a logo',
};

/**
 * Colour written into CODE rather than read from a token. The ratchet above
 * guards `theme/`, which is where tokens are DEFINED; this guards everywhere
 * else, which is where a literal means the palette was bypassed. Generated
 * files are exempt — their colours come from whatever generated them.
 */
const colourLiteralInCodeByFile = () => {
  const out = {};
  const walk = (dir) => {
    for (const e of readdirSync(dir, { withFileTypes: true })) {
      const full = path.join(dir, e.name);
      if (e.isDirectory()) {
        if (e.name !== 'theme') walk(full);
        continue;
      }
      if (!/\.tsx?$/.test(e.name) || e.name.includes('.generated.')) continue;
      const rel = path.relative(path.join(ROOT, 'desktop', 'src'), full).replaceAll(path.sep, '/');
      if (rel in NOT_THE_PALETTE) continue;
      // Comments out (an issue number is not a colour), then `rgb(var(…))` and
      // `rgb(${…})` left alone: the first reads a token, the second writes a value
      // that came from data.
      const text = readFileSync(full, 'utf8')
        .replace(/\/\*[\s\S]*?\*\//g, '')
        .replace(/(^|[^:'"`\w])\/\/.*$/gm, '$1');
      const n = (text.match(/#[0-9a-fA-F]{3,8}\b/g)?.length ?? 0)
        + (text.match(/\brgba?\((?!\s*var\()(?!\$\{)/g)?.length ?? 0);
      if (n > 0) out[rel] = n;
    }
  };
  walk(path.join(ROOT, 'desktop', 'src'));
  return out;
};

const current = offGridByFile();
const colours = colourLiteralsByFile();
const colourCode = colourLiteralInCodeByFile();
const fontSizes = rawFontSizeByFile();
const icons = iconScale();
const handRolled = handRolledByFile();
/**
 * `<Button>` and `<IconButton>` forward only the props they declare, and
 * TypeScript does not check a hyphenated JSX name, so an `aria-*` or `data-*`
 * written on one is dropped without a word — a disclosure that never says it is
 * open. Their own props (`expanded`, `popup`, `ariaLabel`, `title`) carry these.
 */
/** The opening tag at `at`, read to its own `>`: an attribute's `() => x` does not end it. */
const openingTag = (text, at) => {
  let depth = 0;
  for (let i = at + 1; i < text.length; i++) {
    const c = text[i];
    if (c === '{') depth += 1;
    else if (c === '}') depth -= 1;
    else if (c === '>' && depth === 0) return text.slice(at, i + 1);
  }
  return text.slice(at);
};

const droppedAttributes = () => {
  const out = [];
  for (const file of everyFile(SRC_DIR)) {
    if (!file.endsWith('.tsx')) continue;
    const text = readFileSync(file, 'utf8');
    for (const m of text.matchAll(/<(Button|IconButton)\b/g)) {
      const names = [...openingTag(text, m.index).matchAll(/(?<![\w-])((?:aria|data)-[a-z-]+)=/g)].map((a) => a[1]);
      if (names.length === 0) continue;
      const line = text.slice(0, m.index).split('\n').length;
      out.push(`desktop/src/${path.relative(SRC_DIR, file).replaceAll(path.sep, '/')}:${line}: <${m[1]}> drops ${names.join(', ')} — use its own prop`);
    }
  }
  return out;
};
for (const finding of droppedAttributes()) problems.push(finding);

/**
 * Icon-only buttons the editor keeps hand-rolled, by class, each with the reason
 * it is not an IconButton. Everything else icon-only is one: the square ghost or
 * outlined glyph button is a component, and a third copy of it is drift.
 */
const ICON_BUTTONS_KEPT = {
  'play-side': 'a segment of the Play split button: accent fill, joined to its neighbours',
  'winctl__btn': "the window's own minimise / maximise / close, drawn to the platform's convention",
  'tab-popout': "dock tab chrome, styled with the dock's tabs",
  'tab-x': "dock tab chrome, styled with the dock's tabs",
  'dv-collapse': "dock group chrome, styled with the dock's tabs",
  'awp-play': "an audio preview's play: the accent-outlined primary control",
  'transport__play': "the transport's play: the accent-outlined primary control",
  'ts-zone': 'a cell of the tile being edited; the cell is the content, not an icon',
  'ts-oneway-dir': 'a direction cell of a one-way platform picker; the cell is the content',
  'ts-wquad': "a corner of a Wang tile; its fill is the corner's colour",
  'frame-pick__cell': 'a frame of the sheet being picked; the frame is the content',
  'ts-wswatch': 'a colour swatch; its fill is the colour it offers',
  'fx-on': "an effect's on / off box: a checkbox in a list row",
  'mini-toggle': 'one half of a two-state toggle pair that reads as one control',
  'seq-row__btn': "a track's mute / lock: on is the warning colour, not IconButton's accent fill",
  'seq-btn': "the sequencer toolbar's toggles: on is accent text, not IconButton's accent fill",
  'prop-gear': 'binds a property to a controller; recording shows in --rec',
  'prop-reset': 'resets a changed property, in the modified colour, only when there is a change',
  'ctrl-chip-x': "a chip's remove, in the chip's own colour, shown on hover",
  'proj-card__remove': 'a remove badge placed over a project card',
  'lc-field__browse': "the browse end of a path field, part of the field's well",
  'build__scene-start': 'marks the start scene; its state is its fill',
  'ovbtn': "a viewport overlay menu trigger; the rest of its family carry text",
};

/** The first class a tag names, however the className is written. */
const firstClass = (tag) => {
  const m = /\bclassName=(?:"([^"]*)"|\{\s*[`'"]([^`'"$]*))/.exec(tag);
  return (m?.[1] ?? m?.[2] ?? '').trim().split(/\s+/)[0] || null;
};

/** Nothing but icons (and a choice between icons) between the tags, or nothing at all. */
const iconOnly = (inner) => {
  let rest = inner;
  for (let i = rest.search(/<[A-Z]/); i >= 0; i = rest.search(/<[A-Z]/)) {
    const tag = openingTag(rest, i);
    if (!tag.endsWith('/>')) return false;
    rest = rest.slice(0, i) + rest.slice(i + tag.length);
  }
  rest = rest.replace(/\{[^{}]*(?:\?\s*:\s*|&&\s*)\}/g, '').trim();
  return !/[{<]/.test(rest) && !/[\p{L}\p{N}]/u.test(rest);
};

const seenKept = new Set();
for (const file of everyFile(SRC_DIR)) {
  if (!file.endsWith('.tsx')) continue;
  const rel = path.relative(SRC_DIR, file).replaceAll(path.sep, '/');
  if (PRIMITIVES.has(rel)) continue;
  const text = readFileSync(file, 'utf8');
  for (const m of text.matchAll(/<button\b/g)) {
    const tag = openingTag(text, m.index);
    if (ITEM_ROLE.test(tag)) continue;
    const inner = tag.endsWith('/>') ? '' : text.slice(m.index + tag.length, text.indexOf('</button>', m.index));
    if (!iconOnly(inner)) continue;
    const cls = firstClass(tag);
    if (cls && cls in ICON_BUTTONS_KEPT) { seenKept.add(cls); continue; }
    const line = text.slice(0, m.index).split('\n').length;
    problems.push(`desktop/src/${rel}:${line}: an icon-only <button${cls ? ` class="${cls}"` : ''}> — `
      + 'use <IconButton>, or name the class in ICON_BUTTONS_KEPT with why it is not one');
  }
}
for (const cls of Object.keys(ICON_BUTTONS_KEPT)) {
  if (!seenKept.has(cls)) problems.push(`tools/check-theme.mjs: ICON_BUTTONS_KEPT names "${cls}", which no icon-only button carries any more`);
}
for (const site of nativeTitles()) {
  problems.push(`${site}: title= is the operating system's tooltip — use data-tip, `
    + 'and aria-label where it was the control\'s only name');
}
const total = Object.values(current).reduce((a, b) => a + b, 0);

const byName = (o) => Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));

if (process.argv.includes('--update')) {
  mkdirSync(path.dirname(BASELINE), { recursive: true });
  const state = {
    spacing: byName(current),
    colourLiterals: byName(colours),
    colourLiteralsInCode: byName(colourCode),
    rawFontSize: byName(fontSizes),
    iconScale: icons,
    handRolled: byName(handRolled),
  };
  writeFileSync(BASELINE, `${JSON.stringify(state, null, 2)}\n`);
  console.log(`check-theme: banked ${total} off-grid spacing(s), `
    + `${Object.values(colours).reduce((a, b) => a + b, 0)} colour literal(s) in theme, `
    + `${Object.values(colourCode).reduce((a, b) => a + b, 0)} in code, `
    + `${Object.values(fontSizes).reduce((a, b) => a + b, 0)} raw font-size(s), `
    + `${icons.sizes.length} icon size(s) and ${icons.strokes.length} stroke width(s), `
    + `${Object.values(handRolled).reduce((a, b) => a + b, 0)} hand-rolled control(s).`);
  process.exit(0);
}

let banked = {
  spacing: {}, colourLiterals: {}, colourLiteralsInCode: {}, rawFontSize: {},
  iconScale: { sizes: [], strokes: [] }, handRolled: {},
};
if (!existsSync(BASELINE)) {
  problems.push(`no drift baseline at ${BASELINE} — run with --update once to create it`);
} else {
  banked = JSON.parse(readFileSync(BASELINE, 'utf8'));
  /** Per file, so a fix in one place cannot pay for a regression in another. */
  const ratchet = (now, was, what, under = 'desktop/src/theme/') => {
    for (const [file, n] of Object.entries(now)) {
      const before = was?.[file] ?? 0;
      if (n > before) {
        problems.push(`${under}${file}: ${n - before} new ${what} (${before} banked, ${n} now)`);
      }
    }
  };
  ratchet(current, banked.spacing, `spacing value(s) off the ${GRID}px grid`);
  ratchet(colours, banked.colourLiterals, 'colour literal(s) where a token belongs');
  ratchet(colourCode, banked.colourLiteralsInCode,
    'colour literal(s) in code — read the token, do not restate it', 'desktop/src/');
  ratchet(fontSizes, banked.rawFontSize, 'raw font-size(s) — use a step of the scale');
  ratchet(handRolled, banked.handRolled,
    'hand-rolled <button> — the editor has <Button>/<IconButton>', 'desktop/src/');
  // Not per file: a new icon size anywhere is one more size the editor has.
  for (const [kind, now] of [['size', icons.sizes], ['stroke width', icons.strokes]]) {
    const was = new Set(kind === 'size' ? banked.iconScale?.sizes ?? [] : banked.iconScale?.strokes ?? []);
    const added = now.filter((v) => !was.has(v));
    if (added.length > 0) {
      problems.push(`desktop/src/: icon ${kind} ${added.join(', ')} is new — `
        + `${was.size} were already in use, and mixing them is what the ramp exists to stop`);
    }
  }
}

if (problems.length > 0) {
  for (const p of problems) console.error(`  ${p}`);
  console.error(`check-theme: ${problems.length} finding(s).`);
  process.exit(1);
}

const worst = reported.reduce((a, b) => (a.ratio <= b.ratio ? a : b));
const loudest = content.reduce((a, b) => (a.sat >= b.sat ? a : b));
console.log(
  `check-theme: ${textTokens.length} text token(s) over ${READING_SURFACES.length} reading surface(s) — `
  + `all >= ${FLOOR}:1, closest is ${worst.name} at ${worst.ratio.toFixed(2)}:1 on ${worst.surface}. `
  + `${content.length} content label(s) under ${PANEL_CEILING}% saturation, loudest is ${loudest.name} at ${loudest.sat}%. `
  + `${identityUses} identity-token use(s), every one on the thing it names. `
  + `Ratchets hold: ${total} off-grid spacing(s), `
  + `${Object.values(colours).reduce((a, b) => a + b, 0)} colour literal(s) in theme `
  + `and ${Object.values(colourCode).reduce((a, b) => a + b, 0)} in code `
  + `(${Object.keys(NOT_THE_PALETTE).length} file(s) declared not the palette's), `
  + `${Object.values(fontSizes).reduce((a, b) => a + b, 0)} raw font-size(s) `
  + `(${Object.values(NOT_TYPE).reduce((a, o) => a + Object.keys(o).length, 0)} declared icon glyph(s)), `
  + `${icons.sizes.length} icon size(s) / ${icons.strokes.length} stroke width(s), `
  + `${Object.values(handRolled).reduce((a, b) => a + b, 0)} hand-rolled control(s).`,
);