@jjlmoya/utils-games-development 1.60.0 → 1.62.0

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);
+}

package/src/tool/gameUIAccessibilityTester/dom-views.ts

@@ -0,0 +1,193 @@
+import { simulateColor, type RGBColor, type SimulationMode } from './logic';
+
+export interface RenderOptions {
+  source: HTMLCanvasElement;
+  destination: HTMLCanvasElement;
+  mode: SimulationMode;
+  blur: number;
+  downscale: number;
+  heatmap: boolean;
+}
+
+export interface SheetLabels {
+  title: string;
+  original: string;
+  simulated: string;
+  settings: string;
+  localOnly: string;
+}
+
+const MAX_IMAGE_EDGE = 1600;
+
+function context(canvas: HTMLCanvasElement): CanvasRenderingContext2D {
+  const value = canvas.getContext('2d', { willReadFrequently: true });
+  if (!value) throw new Error('Canvas 2D context unavailable');
+  return value;
+}
+
+function createCanvas(width: number, height: number): HTMLCanvasElement {
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  return canvas;
+}
+
+function fittedSize(width: number, height: number): { width: number; height: number } {
+  const scale = Math.min(1, MAX_IMAGE_EDGE / Math.max(width, height));
+  return {
+    width: Math.max(1, Math.round(width * scale)),
+    height: Math.max(1, Math.round(height * scale)),
+  };
+}
+
+export async function loadImageFile(file: File): Promise<HTMLCanvasElement> {
+  const bitmap = await createImageBitmap(file);
+  const size = fittedSize(bitmap.width, bitmap.height);
+  const canvas = createCanvas(size.width, size.height);
+  const canvasContext = context(canvas);
+  canvasContext.imageSmoothingEnabled = true;
+  canvasContext.imageSmoothingQuality = 'high';
+  canvasContext.drawImage(bitmap, 0, 0, size.width, size.height);
+  bitmap.close();
+  return canvas;
+}
+
+function stressedSource(source: HTMLCanvasElement, scale: number, blur: number): HTMLCanvasElement {
+  const smallWidth = Math.max(1, Math.round(source.width * scale));
+  const smallHeight = Math.max(1, Math.round(source.height * scale));
+  const small = createCanvas(smallWidth, smallHeight);
+  const smallContext = context(small);
+  smallContext.imageSmoothingEnabled = true;
+  smallContext.drawImage(source, 0, 0, smallWidth, smallHeight);
+  const output = createCanvas(source.width, source.height);
+  const outputContext = context(output);
+  outputContext.imageSmoothingEnabled = scale === 1;
+  outputContext.filter = `blur(${blur}px)`;
+  outputContext.drawImage(small, 0, 0, source.width, source.height);
+  return output;
+}
+
+function transformPixels(image: ImageData, mode: SimulationMode): ImageData {
+  const output = new ImageData(new Uint8ClampedArray(image.data), image.width, image.height);
+  for (let index = 0; index < output.data.length; index += 4) {
+    const color = simulateColor({
+      r: output.data[index] ?? 0,
+      g: output.data[index + 1] ?? 0,
+      b: output.data[index + 2] ?? 0,
+    }, mode);
+    output.data[index] = color.r;
+    output.data[index + 1] = color.g;
+    output.data[index + 2] = color.b;
+  }
+  return output;
+}
+
+function pixelDistance(data: Uint8ClampedArray, first: number, second: number): number {
+  const red = (data[first] ?? 0) - (data[second] ?? 0);
+  const green = (data[first + 1] ?? 0) - (data[second + 1] ?? 0);
+  const blue = (data[first + 2] ?? 0) - (data[second + 2] ?? 0);
+  return Math.sqrt(red ** 2 + green ** 2 + blue ** 2);
+}
+
+function collapsedSignal(original: ImageData, simulated: ImageData, index: number, neighbor: number): boolean {
+  const before = pixelDistance(original.data, index, neighbor);
+  const after = pixelDistance(simulated.data, index, neighbor);
+  return before >= 32 && after / before < 0.48;
+}
+
+function heatmapPixels(original: ImageData, simulated: ImageData): ImageData {
+  const output = new ImageData(new Uint8ClampedArray(simulated.data), simulated.width, simulated.height);
+  const row = simulated.width * 4;
+  for (let index = 0; index < output.data.length - row - 4; index += 4) {
+    const collapsed = collapsedSignal(original, simulated, index, index + 4)
+      || collapsedSignal(original, simulated, index, index + row);
+    if (collapsed) {
+      output.data[index] = 255;
+      output.data[index + 1] = Math.round((output.data[index + 1] ?? 0) * 0.18);
+      output.data[index + 2] = 72;
+    }
+  }
+  return output;
+}
+
+export function renderSimulation(options: RenderOptions): void {
+  const stressed = stressedSource(options.source, options.downscale, options.blur);
+  const sourceContext = context(stressed);
+  const original = sourceContext.getImageData(0, 0, stressed.width, stressed.height);
+  const simulated = transformPixels(original, options.mode);
+  const rendered = options.heatmap ? heatmapPixels(original, simulated) : simulated;
+  options.destination.width = stressed.width;
+  options.destination.height = stressed.height;
+  context(options.destination).putImageData(rendered, 0, 0);
+}
+
+export function copyOriginal(source: HTMLCanvasElement, destination: HTMLCanvasElement): void {
+  destination.width = source.width;
+  destination.height = source.height;
+  context(destination).drawImage(source, 0, 0);
+}
+
+export function sampleCanvas(canvas: HTMLCanvasElement, clientX: number, clientY: number): {
+  color: RGBColor;
+  left: number;
+  top: number;
+} {
+  const bounds = canvas.getBoundingClientRect();
+  const left = Math.min(1, Math.max(0, (clientX - bounds.left) / bounds.width));
+  const top = Math.min(1, Math.max(0, (clientY - bounds.top) / bounds.height));
+  return { color: sampleAtFraction(canvas, left, top), left, top };
+}
+
+export function sampleAtFraction(canvas: HTMLCanvasElement, left: number, top: number): RGBColor {
+  const x = Math.min(canvas.width - 1, Math.floor(left * canvas.width));
+  const y = Math.min(canvas.height - 1, Math.floor(top * canvas.height));
+  const data = context(canvas).getImageData(x, y, 1, 1).data;
+  return { r: data[0] ?? 0, g: data[1] ?? 0, b: data[2] ?? 0 };
+}
+
+function sheetDimensions(source: HTMLCanvasElement): { width: number; height: number; imageHeight: number } {
+  const width = Math.max(960, source.width * 2 + 72);
+  const imageHeight = Math.round((source.height / source.width) * ((width - 72) / 2));
+  return { width, height: imageHeight + 190, imageHeight };
+}
+
+export function createComparisonSheet(
+  original: HTMLCanvasElement,
+  simulated: HTMLCanvasElement,
+  labels: SheetLabels,
+): HTMLCanvasElement {
+  const size = sheetDimensions(original);
+  const sheet = createCanvas(size.width, size.height);
+  const sheetContext = context(sheet);
+  const imageWidth = (size.width - 72) / 2;
+  sheetContext.fillStyle = '#071018';
+  sheetContext.fillRect(0, 0, size.width, size.height);
+  sheetContext.fillStyle = '#e8fbff';
+  sheetContext.font = '700 28px sans-serif';
+  sheetContext.fillText(labels.title, 24, 42);
+  sheetContext.font = '600 18px sans-serif';
+  sheetContext.fillText(labels.original, 24, 80);
+  sheetContext.fillText(labels.simulated, imageWidth + 48, 80);
+  sheetContext.drawImage(original, 24, 98, imageWidth, size.imageHeight);
+  sheetContext.drawImage(simulated, imageWidth + 48, 98, imageWidth, size.imageHeight);
+  sheetContext.font = '500 16px sans-serif';
+  sheetContext.fillText(labels.settings, 24, size.height - 48);
+  sheetContext.fillStyle = '#90aab4';
+  sheetContext.fillText(labels.localOnly, 24, size.height - 20);
+  return sheet;
+}
+
+export function triggerDownload(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.click();
+  URL.revokeObjectURL(url);
+}
+
+export function downloadCanvas(canvas: HTMLCanvasElement, filename: string): void {
+  canvas.toBlob((blob) => {
+    if (blob) triggerDownload(blob, filename);
+  }, 'image/png');
+}

package/src/tool/gameUIAccessibilityTester/entry.ts

@@ -0,0 +1,28 @@
+import type { GamesToolEntry, ToolLocaleContent } from '../../types';
+import type { GameUiAccessibilityTesterUI } from './ui';
+
+export type { GameUiAccessibilityTesterUI };
+
+export type GameUiAccessibilityTesterLocaleContent = ToolLocaleContent<GameUiAccessibilityTesterUI>;
+
+export const gameUiAccessibilityTester: GamesToolEntry<GameUiAccessibilityTesterUI> = {
+  id: 'game-ui-accessibility-stress-tester',
+  icons: { bg: 'mdi:accessibility', fg: 'mdi:eye-check-outline' },
+  i18n: {
+    de: () => import('./i18n/de').then((module) => module.content),
+    en: () => import('./i18n/en').then((module) => module.content),
+    es: () => import('./i18n/es').then((module) => module.content),
+    fr: () => import('./i18n/fr').then((module) => module.content),
+    id: () => import('./i18n/id').then((module) => module.content),
+    it: () => import('./i18n/it').then((module) => module.content),
+    ja: () => import('./i18n/ja').then((module) => module.content),
+    ko: () => import('./i18n/ko').then((module) => module.content),
+    nl: () => import('./i18n/nl').then((module) => module.content),
+    pl: () => import('./i18n/pl').then((module) => module.content),
+    pt: () => import('./i18n/pt').then((module) => module.content),
+    ru: () => import('./i18n/ru').then((module) => module.content),
+    sv: () => import('./i18n/sv').then((module) => module.content),
+    tr: () => import('./i18n/tr').then((module) => module.content),
+    zh: () => import('./i18n/zh').then((module) => module.content),
+  },
+};

package/src/tool/gameUIAccessibilityTester/evaluator.ts

@@ -0,0 +1,43 @@
+import {
+  contrastRatio,
+  separationRetention,
+  simulateColor,
+  type RGBColor,
+  type SimulationMode,
+} from './logic';
+
+export type DiagnosticStatus = 'strong' | 'watch' | 'review';
+
+export interface PairDiagnostic {
+  originalContrast: number;
+  simulatedContrast: number;
+  retained: number;
+  status: DiagnosticStatus;
+  simulatedFirst: RGBColor;
+  simulatedSecond: RGBColor;
+}
+
+function diagnosticStatus(contrast: number, retained: number): DiagnosticStatus {
+  if (contrast < 3 || retained < 45) return 'review';
+  if (contrast < 4.5 || retained < 70) return 'watch';
+  return 'strong';
+}
+
+export function evaluatePair(
+  first: RGBColor,
+  second: RGBColor,
+  mode: SimulationMode,
+): PairDiagnostic {
+  const simulatedFirst = simulateColor(first, mode);
+  const simulatedSecond = simulateColor(second, mode);
+  const simulatedContrast = contrastRatio(simulatedFirst, simulatedSecond);
+  const retained = separationRetention(first, second, simulatedFirst, simulatedSecond);
+  return {
+    originalContrast: contrastRatio(first, second),
+    simulatedContrast,
+    retained,
+    status: diagnosticStatus(simulatedContrast, retained),
+    simulatedFirst,
+    simulatedSecond,
+  };
+}