@jjlmoya/utils-games-development 1.61.0 → 1.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-games-development",
-    "version": "1.61.0",
+    "version": "1.62.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -4,10 +4,11 @@ import { spriteSheetPacker } from '../tool/spriteSheetPacker/entry';
 import { audioLoopPointFinder } from '../tool/audioLoopPointFinder/entry';
 import { saveFileEditor } from '../tool/saveFileEditor/entry';
 import { steamBbcodeTranslator } from '../tool/steamBbcodeTranslator/entry';
+import { gameUiAccessibilityTester } from '../tool/gameUIAccessibilityTester/entry';
 
 export const gamesCategory: GamesCategoryEntry = {
   icon: 'mdi:gamepad-variant',
-  tools: [steamCapsuleGenerator, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, steamBbcodeTranslator],
+  tools: [steamCapsuleGenerator, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, steamBbcodeTranslator, gameUiAccessibilityTester],
   i18n: {
     de: () => import('./i18n/de').then((m) => m.content),
     en: () => import('./i18n/en').then((m) => m.content),

package/src/entries.ts

@@ -26,5 +26,6 @@ import { localizationSanitizer } from './tool/localizationSanitizer/entry';
 import { steamBbcodeTranslator } from './tool/steamBbcodeTranslator/entry';
 import { retroSfxGenerator } from './tool/retroSfxGenerator/entry';
 import { pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper/entry';
+import { gameUiAccessibilityTester } from './tool/gameUIAccessibilityTester/entry';
 
-export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer, steamBbcodeTranslator, retroSfxGenerator, pixelArtPaletteSwapper];
+export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer, steamBbcodeTranslator, retroSfxGenerator, pixelArtPaletteSwapper, gameUiAccessibilityTester];

package/src/index.ts

@@ -20,5 +20,6 @@ export { STEAM_CAPSULE_GENERATOR_TOOL, steamCapsuleGenerator } from './tool/stea
 export { STEAM_BBCODE_TRANSLATOR_TOOL, steamBbcodeTranslator } from './tool/steamBbcodeTranslator';
 export { RETRO_SFX_GENERATOR_TOOL, retroSfxGenerator } from './tool/retroSfxGenerator';
 export { PIXEL_ART_PALETTE_SWAPPER_TOOL, pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper';
+export { GAME_UI_ACCESSIBILITY_TESTER_TOOL, gameUiAccessibilityTester } from './tool/gameUIAccessibilityTester';
 
 export type { ToolLocaleContent as GamesToolLocaleContent } from './types';

package/src/tests/locale_completeness.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { ALL_TOOLS } from '../tools';
 
 describe('Locale Completeness Validation', () => {
-  it('nine tools are registered', () => {
-    expect(ALL_TOOLS.length).toBe(9);
+  it('ten tools are registered', () => {
+    expect(ALL_TOOLS.length).toBe(10);
   });
 });

package/src/tests/tool_validation.test.ts

@@ -4,8 +4,8 @@ import { gamesCategory } from '../data';
 
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
-    it('should have 9 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(9);
+    it('should have 10 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(10);
     });
 
     it('gamesCategory should be defined', () => {

package/src/tool/gameUIAccessibilityTester/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { bibliographyEntries } from './bibliography';
+---
+
+<SharedBibliography links={bibliographyEntries} />

package/src/tool/gameUIAccessibilityTester/bibliography.ts

@@ -0,0 +1,10 @@
+export const bibliographyEntries = [
+  {
+    name: 'Machado, Oliveira and Fernandes: A Physiologically Based Model for Simulation of Color Vision Deficiency',
+    url: 'https://profs.ic.uff.br/~laffernandes/content/publications/journal/2009_tvcg_15%286%29/machado_oliveira_fernandes-tvcg-15%286%29-2009-corrected.pdf',
+  },
+  {
+    name: 'W3C Web Accessibility Initiative: Understanding Non Text Contrast',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast',
+  },
+];

package/src/tool/gameUIAccessibilityTester/component.astro

@@ -0,0 +1,210 @@
+---
+import type { GameUiAccessibilityTesterUI } from './ui';
+
+interface Props {
+  ui: GameUiAccessibilityTesterUI;
+}
+
+const { ui } = Astro.props;
+const serializedUi = JSON.stringify(ui).replace(/</g, '\\u003c');
+---
+
+<article class="gax" data-game-ui-accessibility-tester data-ready="false" data-compare="side" data-zoom="1">
+  <script is:inline type="application/json" data-ui set:html={serializedUi}></script>
+
+  <div class="gax-intro">
+    <div class="gax-signal" aria-hidden="true"><span></span><span></span><span></span></div>
+    <p>{ui.onboarding}</p>
+    <p class="gax-privacy">{ui.privacyNote}</p>
+  </div>
+
+  <section class="gax-upload" data-dropzone aria-labelledby="game-ui-drop-title">
+    <svg viewBox="0 0 64 64" aria-hidden="true">
+      <path d="M12 17h40v30H12z M20 37l8-9 7 7 5-5 8 9 M32 10v13 M26 16l6 7 6-7" />
+    </svg>
+    <div>
+      <h2 id="game-ui-drop-title">{ui.dropTitle}</h2>
+      <p>{ui.dropHint}</p>
+      <small>{ui.supportedFiles}</small>
+    </div>
+    <input
+      class="gax-file-input"
+      id="game-ui-image-input"
+      data-file-input
+      type="file"
+      accept="image/png,image/jpeg,image/webp"
+    />
+    <label class="gax-upload-action" for="game-ui-image-input">
+      <span class="gax-upload-new">{ui.chooseImage}</span>
+      <span class="gax-upload-replace">{ui.replaceImage}</span>
+    </label>
+  </section>
+
+  <section class="gax-optics" aria-label={ui.lensLabel}>
+    <div class="gax-control-head">
+      <span>{ui.lensLabel}</span>
+      <span class="gax-control-rule" aria-hidden="true"></span>
+    </div>
+    <div class="gax-lens-rack">
+      <button type="button" data-mode value="original" aria-pressed="false">{ui.lensOriginal}</button>
+      <button type="button" data-mode value="protanopia" aria-pressed="false">{ui.lensProtanopia}</button>
+      <button type="button" data-mode value="deuteranopia" aria-pressed="true">{ui.lensDeuteranopia}</button>
+      <button type="button" data-mode value="tritanopia" aria-pressed="false">{ui.lensTritanopia}</button>
+      <button type="button" data-mode value="achromatopsia" aria-pressed="false">{ui.lensAchromatopsia}</button>
+      <button type="button" data-mode value="reduced-contrast" aria-pressed="false">{ui.lensReducedContrast}</button>
+      <button type="button" data-mode value="desaturation" aria-pressed="false">{ui.lensDesaturation}</button>
+    </div>
+  </section>
+
+  <section class="gax-stage" aria-label={ui.simulatedView}>
+    <div class="gax-stage-toolbar">
+      <div class="gax-segment" role="group" aria-label={ui.compareLabel}>
+        <button type="button" data-compare value="side" class="is-active" aria-pressed="true">{ui.compareSideBySide}</button>
+        <button type="button" data-compare value="split" aria-pressed="false">{ui.compareSplit}</button>
+        <button type="button" data-compare value="press" aria-pressed="false">{ui.comparePress}</button>
+      </div>
+      <div class="gax-segment" role="group" aria-label={ui.zoomLabel}>
+        <button type="button" data-zoom value="1" class="is-active" aria-pressed="true">1x</button>
+        <button type="button" data-zoom value="2" aria-pressed="false">2x</button>
+        <button type="button" data-zoom value="4" aria-pressed="false">4x</button>
+      </div>
+    </div>
+
+    <div class="gax-viewports">
+      <figure class="gax-viewport gax-original">
+        <figcaption><span></span>{ui.originalView}</figcaption>
+        <div class="gax-canvas-wrap">
+          <canvas data-original-canvas tabindex="0" aria-label={ui.originalView}></canvas>
+          <span class="gax-marker gax-marker-a" data-marker="0" hidden>A</span>
+          <span class="gax-marker gax-marker-b" data-marker="1" hidden>B</span>
+        </div>
+      </figure>
+      <figure class="gax-viewport gax-simulated">
+        <figcaption><span></span>{ui.simulatedView}</figcaption>
+        <div class="gax-canvas-wrap">
+          <canvas data-simulated-canvas aria-label={ui.simulatedView}></canvas>
+        </div>
+      </figure>
+      <p class="gax-empty">{ui.emptyCanvas}</p>
+    </div>
+
+    <div class="gax-compare-actions">
+      <label class="gax-split-control" for="game-ui-split">
+        {ui.splitPosition}
+        <input id="game-ui-split" data-split type="range" min="10" max="90" value="50" />
+      </label>
+      <button type="button" class="gax-hold" data-hold-original>{ui.holdOriginal}</button>
+    </div>
+  </section>
+
+  <section class="gax-stress" aria-labelledby="game-ui-stress-title">
+    <div class="gax-control-head">
+      <h2 id="game-ui-stress-title">{ui.stressLabel}</h2>
+      <span class="gax-control-rule" aria-hidden="true"></span>
+    </div>
+    <div class="gax-stress-line">
+      <label for="game-ui-blur">{ui.blurLabel}</label>
+      <input id="game-ui-blur" data-blur type="range" min="0" max="8" step="0.5" value="0" />
+      <div class="gax-segment" role="group" aria-label={ui.downscaleLabel}>
+        <button type="button" data-downscale value="1" class="is-active" aria-pressed="true">{ui.downscaleFull}</button>
+        <button type="button" data-downscale value="0.5" aria-pressed="false">{ui.downscaleHalf}</button>
+        <button type="button" data-downscale value="0.25" aria-pressed="false">{ui.downscaleQuarter}</button>
+        <button type="button" data-downscale value="0.125" aria-pressed="false">{ui.downscaleEighth}</button>
+      </div>
+      <label class="gax-toggle">
+        <input data-heatmap type="checkbox" />
+        <span aria-hidden="true"></span>
+        <span><strong>{ui.heatmapLabel}</strong><small>{ui.heatmapHint}</small></span>
+      </label>
+    </div>
+  </section>
+
+  <section class="gax-sampler" aria-labelledby="game-ui-sample-title">
+    <header>
+      <div>
+        <h2 id="game-ui-sample-title">{ui.sampleTitle}</h2>
+        <p>{ui.sampleInstructions}</p>
+      </div>
+      <span class="gax-classification">{ui.heuristicLabel}</span>
+    </header>
+    <div class="gax-sample-strip">
+      <div class="gax-sample-unit">
+        <button type="button" data-sample-button value="0" class="is-active" aria-pressed="true">
+          <span data-swatch="0" class="gax-swatch"></span>{ui.sampleA}
+        </button>
+        <div class="gax-sample-copy">
+          <label for="game-ui-sample-a">{ui.sampleAName}</label>
+          <input id="game-ui-sample-a" data-name="0" type="text" value={ui.sampleAInitial} maxlength="40" />
+          <code data-hex="0">{ui.noSample}</code>
+        </div>
+        <label class="gax-color-input" for="game-ui-color-a">{ui.manualColor}</label>
+        <input id="game-ui-color-a" data-color-input="0" type="color" value="#000000" />
+      </div>
+      <div class="gax-link-beam" aria-hidden="true"><span></span></div>
+      <div class="gax-sample-unit">
+        <button type="button" data-sample-button value="1" aria-pressed="false">
+          <span data-swatch="1" class="gax-swatch"></span>{ui.sampleB}
+        </button>
+        <div class="gax-sample-copy">
+          <label for="game-ui-sample-b">{ui.sampleBName}</label>
+          <input id="game-ui-sample-b" data-name="1" type="text" value={ui.sampleBInitial} maxlength="40" />
+          <code data-hex="1">{ui.noSample}</code>
+        </div>
+        <label class="gax-color-input" for="game-ui-color-b">{ui.manualColor}</label>
+        <input id="game-ui-color-b" data-color-input="1" type="color" value="#000000" />
+      </div>
+    </div>
+    <div class="gax-instruments" aria-live="polite">
+      <div><span>{ui.originalContrast}</span><strong data-original-contrast>--</strong><small>{ui.measurementLabel}</small></div>
+      <div><span>{ui.simulatedContrast}</span><strong data-simulated-contrast>--</strong><small>{ui.measurementLabel}</small></div>
+      <div><span>{ui.separationRetained}</span><strong data-retained>--</strong><small>{ui.heuristicLabel}</small></div>
+      <div class="gax-diagnostic"><span>{ui.manualReviewLabel}</span><strong data-diagnostic data-level="pending">{ui.statusPending}</strong></div>
+    </div>
+    <div class="gax-method-notes">
+      <p><strong>{ui.measurementLabel}</strong>{ui.measurementHint}</p>
+      <p><strong>{ui.heuristicLabel}</strong>{ui.heuristicHint}</p>
+    </div>
+  </section>
+
+  <section class="gax-review" aria-labelledby="game-ui-review-title">
+    <div class="gax-review-rail">
+      <h2 id="game-ui-review-title">{ui.promptTitle}</h2>
+      <ol>
+        <li>{ui.promptColorOnly}</li>
+        <li>{ui.promptChangingBackground}</li>
+        <li>{ui.promptMinimap}</li>
+        <li>{ui.promptStates}</li>
+        <li>{ui.promptShape}</li>
+      </ol>
+    </div>
+    <div class="gax-findings-panel">
+      <label for="game-ui-finding">{ui.findingLabel}</label>
+      <div class="gax-finding-entry">
+        <input id="game-ui-finding" data-finding-input type="text" placeholder={ui.findingPlaceholder} maxlength="180" />
+        <button type="button" data-add-finding>{ui.addFinding}</button>
+      </div>
+      <p data-findings-empty>{ui.findingsEmpty}</p>
+      <ul data-findings></ul>
+    </div>
+  </section>
+
+  <footer class="gax-actions">
+    <div>
+      <p>{ui.localOnlyDisclosure}</p>
+      <p>{ui.limitationDisclosure}</p>
+      <p data-status role="status">{ui.noSample}</p>
+    </div>
+    <div class="gax-action-buttons">
+      <button type="button" data-export-sheet disabled>{ui.exportSheet}</button>
+      <button type="button" data-export-report disabled>{ui.exportReport}</button>
+      <button type="button" data-reset>{ui.resetTool}</button>
+    </div>
+  </footer>
+</article>
+
+<script>
+  import { mountGameUiAccessibilityTester } from './controller';
+
+  document.querySelectorAll<HTMLElement>('[data-game-ui-accessibility-tester]')
+    .forEach((root) => mountGameUiAccessibilityTester(root));
+</script>

package/src/tool/gameUIAccessibilityTester/controller-actions.ts

@@ -0,0 +1,92 @@
+import { evaluatePair } from './evaluator';
+import { createComparisonSheet, downloadCanvas } from './dom-views';
+import { downloadStructuredReport } from './report';
+import { clearSettings } from './storage';
+import type { TesterState } from './controller';
+
+function required<T extends Element>(root: ParentNode, selector: string): T {
+  const element = root.querySelector<T>(selector);
+  if (!element) throw new Error(`Missing tester element ${selector}`);
+  return element;
+}
+
+function setStatus(state: TesterState, message: string): void {
+  required<HTMLElement>(state.root, '[data-status]').textContent = message;
+}
+
+function addFinding(state: TesterState): void {
+  const input = required<HTMLInputElement>(state.root, '[data-finding-input]');
+  const finding = input.value.trim();
+  if (!finding) return;
+  state.findings.push(finding);
+  const item = document.createElement('li');
+  item.textContent = finding;
+  required(state.root, '[data-findings]').append(item);
+  required<HTMLElement>(state.root, '[data-findings-empty]').hidden = true;
+  input.value = '';
+}
+
+function exportReport(state: TesterState): void {
+  const [first, second] = state.samples;
+  if (!first || !second) return;
+  downloadStructuredReport({
+    mode: state.settings.mode,
+    blur: state.settings.blur,
+    downscale: state.settings.downscale,
+    firstName: required<HTMLInputElement>(state.root, '[data-name="0"]').value,
+    secondName: required<HTMLInputElement>(state.root, '[data-name="1"]').value,
+    first,
+    second,
+    diagnostic: evaluatePair(first, second, state.settings.mode),
+    findings: state.findings,
+  }, state.ui);
+  setStatus(state, state.ui.reportDownloaded);
+}
+
+function exportSheet(state: TesterState): void {
+  if (!state.source) return;
+  const simulated = required<HTMLCanvasElement>(state.root, '[data-simulated-canvas]');
+  const settings = `${state.ui.lensLabel}: ${state.settings.mode}, ${state.ui.blurLabel}: ${state.settings.blur}px`;
+  const sheet = createComparisonSheet(state.source, simulated, {
+    title: state.ui.reportTitle,
+    original: state.ui.originalView,
+    simulated: state.ui.simulatedView,
+    settings,
+    localOnly: state.ui.localOnlyDisclosure,
+  });
+  downloadCanvas(sheet, 'game-ui-accessibility-comparison.png');
+  setStatus(state, state.ui.sheetDownloaded);
+}
+
+function reset(state: TesterState): void {
+  clearSettings();
+  state.source = null;
+  state.samples = [null, null];
+  state.findings = [];
+  state.root.dataset.ready = 'false';
+  state.root.querySelectorAll<HTMLButtonElement>('[data-export-sheet], [data-export-report]')
+    .forEach((button) => { button.disabled = true; });
+  required(state.root, '[data-findings]').replaceChildren();
+  required<HTMLElement>(state.root, '[data-findings-empty]').hidden = false;
+  required<HTMLInputElement>(state.root, '[data-file-input]').value = '';
+  setStatus(state, state.ui.noSample);
+  const diagnostic = required<HTMLElement>(state.root, '[data-diagnostic]');
+  diagnostic.textContent = state.ui.statusPending;
+  diagnostic.dataset.level = 'pending';
+}
+
+function bindHold(state: TesterState): void {
+  const hold = required(state.root, '[data-hold-original]');
+  hold.addEventListener('pointerdown', () => { state.root.dataset.hold = 'true'; });
+  ['pointerup', 'pointerleave', 'blur'].forEach((event) => {
+    hold.addEventListener(event, () => { delete state.root.dataset.hold; });
+  });
+}
+
+export function bindActions(state: TesterState): void {
+  required(state.root, '[data-add-finding]').addEventListener('click', () => addFinding(state));
+  required(state.root, '[data-export-report]').addEventListener('click', () => exportReport(state));
+  required(state.root, '[data-export-sheet]').addEventListener('click', () => exportSheet(state));
+  required(state.root, '[data-reset]').addEventListener('click', () => reset(state));
+  bindHold(state);
+}

package/src/tool/gameUIAccessibilityTester/controller.ts

@@ -0,0 +1,237 @@
+import { evaluatePair, type PairDiagnostic } from './evaluator';
+import {
+  copyOriginal,
+  loadImageFile,
+  renderSimulation,
+  sampleAtFraction,
+  sampleCanvas,
+} from './dom-views';
+import { fromHex, toHex, type RGBColor } from './logic';
+import { loadSettings, saveSettings, type StoredSettings } from './storage';
+import type { GameUiAccessibilityTesterUI } from './ui';
+import { bindActions } from './controller-actions';
+
+export interface TesterState {
+  root: HTMLElement;
+  ui: GameUiAccessibilityTesterUI;
+  settings: StoredSettings;
+  source: HTMLCanvasElement | null;
+  samples: [RGBColor | null, RGBColor | null];
+  positions: [{ left: number; top: number }, { left: number; top: number }];
+  activeSample: 0 | 1;
+  findings: string[];
+  frame: number;
+}
+
+const FALLBACK_SETTINGS: StoredSettings = {
+  mode: 'deuteranopia', compare: 'side', blur: 0, downscale: 1, zoom: 1, heatmap: false,
+};
+
+function required<T extends Element>(root: ParentNode, selector: string): T {
+  const element = root.querySelector<T>(selector);
+  if (!element) throw new Error(`Missing tester element ${selector}`);
+  return element;
+}
+
+function readUi(root: HTMLElement): GameUiAccessibilityTesterUI {
+  const script = required<HTMLScriptElement>(root, '[data-ui]');
+  return JSON.parse(script.textContent ?? '{}') as GameUiAccessibilityTesterUI;
+}
+
+function setStatus(state: TesterState, message: string): void {
+  required<HTMLElement>(state.root, '[data-status]').textContent = message;
+}
+
+function setExportsEnabled(state: TesterState, enabled: boolean): void {
+  state.root.querySelectorAll<HTMLButtonElement>('[data-export-sheet], [data-export-report]')
+    .forEach((button) => { button.disabled = !enabled; });
+}
+
+function setActive(root: HTMLElement, selector: string, value: string): void {
+  root.querySelectorAll<HTMLButtonElement>(selector).forEach((button) => {
+    const active = button.value === value;
+    button.classList.toggle('is-active', active);
+    button.setAttribute('aria-pressed', String(active));
+  });
+}
+
+function diagnosticLabel(state: TesterState, diagnostic: PairDiagnostic): string {
+  if (diagnostic.status === 'review') return state.ui.statusReview;
+  if (diagnostic.status === 'watch') return state.ui.statusWatch;
+  return state.ui.statusStrong;
+}
+
+function renderMetrics(state: TesterState): void {
+  const [first, second] = state.samples;
+  if (!first || !second) return;
+  const diagnostic = evaluatePair(first, second, state.settings.mode);
+  required(state.root, '[data-original-contrast]').textContent = `${diagnostic.originalContrast.toFixed(2)}:1`;
+  required(state.root, '[data-simulated-contrast]').textContent = `${diagnostic.simulatedContrast.toFixed(2)}:1`;
+  required(state.root, '[data-retained]').textContent = `${diagnostic.retained.toFixed(0)}%`;
+  const badge = required(state.root, '[data-diagnostic]');
+  badge.textContent = diagnosticLabel(state, diagnostic);
+  badge.setAttribute('data-level', diagnostic.status);
+}
+
+function renderNow(state: TesterState): void {
+  state.frame = 0;
+  if (!state.source) return;
+  const original = required<HTMLCanvasElement>(state.root, '[data-original-canvas]');
+  const simulated = required<HTMLCanvasElement>(state.root, '[data-simulated-canvas]');
+  copyOriginal(state.source, original);
+  renderSimulation({
+    source: state.source,
+    destination: simulated,
+    mode: state.settings.mode,
+    blur: state.settings.blur,
+    downscale: state.settings.downscale,
+    heatmap: state.settings.heatmap,
+  });
+  state.root.dataset.compare = state.settings.compare;
+  state.root.dataset.zoom = String(state.settings.zoom);
+  renderMetrics(state);
+  saveSettings(state.settings);
+}
+
+function scheduleRender(state: TesterState): void {
+  if (state.frame) cancelAnimationFrame(state.frame);
+  state.frame = requestAnimationFrame(() => renderNow(state));
+}
+
+function placeMarker(state: TesterState, index: 0 | 1): void {
+  const marker = required<HTMLElement>(state.root, `[data-marker="${index}"]`);
+  const position = state.positions[index];
+  marker.style.setProperty('--marker-x', `${position.left * 100}%`);
+  marker.style.setProperty('--marker-y', `${position.top * 100}%`);
+  marker.hidden = false;
+}
+
+function renderSample(state: TesterState, index: 0 | 1): void {
+  const color = state.samples[index];
+  if (!color) return;
+  const chip = required<HTMLElement>(state.root, `[data-swatch="${index}"]`);
+  chip.style.backgroundColor = toHex(color);
+  required(state.root, `[data-hex="${index}"]`).textContent = toHex(color);
+  required<HTMLInputElement>(state.root, `[data-color-input="${index}"]`).value = toHex(color);
+  placeMarker(state, index);
+  renderMetrics(state);
+}
+
+function selectSample(state: TesterState, index: 0 | 1): void {
+  state.activeSample = index;
+  setActive(state.root, '[data-sample-button]', String(index));
+}
+
+function sampleFromEvent(state: TesterState, event: MouseEvent): void {
+  if (!state.source) return;
+  const canvas = required<HTMLCanvasElement>(state.root, '[data-original-canvas]');
+  const sample = sampleCanvas(canvas, event.clientX, event.clientY);
+  const index = state.activeSample;
+  state.samples[index] = sample.color;
+  state.positions[index] = { left: sample.left, top: sample.top };
+  renderSample(state, index);
+  selectSample(state, index === 0 ? 1 : 0);
+}
+
+function seedSamples(state: TesterState): void {
+  if (!state.source) return;
+  state.positions = [{ left: 0.35, top: 0.5 }, { left: 0.65, top: 0.5 }];
+  state.samples = [
+    sampleAtFraction(state.source, 0.35, 0.5),
+    sampleAtFraction(state.source, 0.65, 0.5),
+  ];
+  renderSample(state, 0);
+  renderSample(state, 1);
+}
+
+async function acceptFile(state: TesterState, file: File): Promise<void> {
+  if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type)) return setStatus(state, state.ui.uploadError);
+  if (file.size > 16 * 1024 * 1024) return setStatus(state, state.ui.fileTooLarge);
+  try {
+    state.source = await loadImageFile(file);
+    state.root.dataset.ready = 'true';
+    setExportsEnabled(state, true);
+    seedSamples(state);
+    renderNow(state);
+    setStatus(state, state.ui.imageReady);
+  } catch {
+    setStatus(state, state.ui.uploadError);
+  }
+}
+
+function bindFileControls(state: TesterState): void {
+  const input = required<HTMLInputElement>(state.root, '[data-file-input]');
+  const dropzone = required<HTMLElement>(state.root, '[data-dropzone]');
+  input.addEventListener('change', () => { if (input.files?.[0]) void acceptFile(state, input.files[0]); });
+  dropzone.addEventListener('dragover', (event) => { event.preventDefault(); dropzone.dataset.drag = 'true'; });
+  dropzone.addEventListener('dragleave', () => { delete dropzone.dataset.drag; });
+  dropzone.addEventListener('drop', (event) => {
+    event.preventDefault();
+    delete dropzone.dataset.drag;
+    if (event.dataTransfer?.files[0]) void acceptFile(state, event.dataTransfer.files[0]);
+  });
+}
+
+function bindChoiceButtons(state: TesterState, selector: string, key: keyof StoredSettings): void {
+  state.root.querySelectorAll<HTMLButtonElement>(selector).forEach((button) => {
+    button.addEventListener('click', () => {
+      const value = key === 'downscale' || key === 'zoom' ? Number(button.value) : button.value;
+      Object.assign(state.settings, { [key]: value });
+      setActive(state.root, selector, button.value);
+      scheduleRender(state);
+    });
+  });
+}
+
+function bindStressControls(state: TesterState): void {
+  const blur = required<HTMLInputElement>(state.root, '[data-blur]');
+  const split = required<HTMLInputElement>(state.root, '[data-split]');
+  const heatmap = required<HTMLInputElement>(state.root, '[data-heatmap]');
+  blur.addEventListener('input', () => { state.settings.blur = Number(blur.value); scheduleRender(state); });
+  split.addEventListener('input', () => state.root.style.setProperty('--split', `${split.value}%`));
+  heatmap.addEventListener('change', () => { state.settings.heatmap = heatmap.checked; scheduleRender(state); });
+}
+
+function syncStoredControls(state: TesterState): void {
+  required<HTMLInputElement>(state.root, '[data-blur]').value = String(state.settings.blur);
+  required<HTMLInputElement>(state.root, '[data-heatmap]').checked = state.settings.heatmap;
+  state.root.dataset.compare = state.settings.compare;
+  state.root.dataset.zoom = String(state.settings.zoom);
+}
+
+function bindSampling(state: TesterState): void {
+  required(state.root, '[data-original-canvas]').addEventListener('click', (event) => sampleFromEvent(state, event as MouseEvent));
+  state.root.querySelectorAll<HTMLButtonElement>('[data-sample-button]').forEach((button) => {
+    button.addEventListener('click', () => selectSample(state, Number(button.value) as 0 | 1));
+  });
+  state.root.querySelectorAll<HTMLInputElement>('[data-color-input]').forEach((input) => {
+    input.addEventListener('input', () => {
+      const index = Number(input.dataset.colorInput) as 0 | 1;
+      state.samples[index] = fromHex(input.value);
+      renderSample(state, index);
+    });
+  });
+}
+
+export function mountGameUiAccessibilityTester(root: HTMLElement): void {
+  if (root.dataset.mounted === 'true') return;
+  const state: TesterState = {
+    root, ui: readUi(root), settings: loadSettings(FALLBACK_SETTINGS), source: null,
+    samples: [null, null], positions: [{ left: 0.35, top: 0.5 }, { left: 0.65, top: 0.5 }],
+    activeSample: 0, findings: [], frame: 0,
+  };
+  root.dataset.mounted = 'true';
+  bindFileControls(state);
+  bindChoiceButtons(state, '[data-mode]', 'mode');
+  bindChoiceButtons(state, '[data-compare]', 'compare');
+  bindChoiceButtons(state, '[data-downscale]', 'downscale');
+  bindChoiceButtons(state, '[data-zoom]', 'zoom');
+  bindStressControls(state);
+  bindSampling(state);
+  bindActions(state);
+  setActive(root, '[data-mode]', state.settings.mode);
+  setActive(root, '[data-compare]', state.settings.compare);
+  setActive(root, '[data-downscale]', String(state.settings.downscale));
+  setActive(root, '[data-zoom]', String(state.settings.zoom));
+  syncStoredControls(state);
+}