@jjlmoya/utils-games-development 1.60.0 → 1.62.0

package/src/tool/gameUIAccessibilityTester/logic.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import {
+  colorDistance,
+  contrastRatio,
+  fromHex,
+  relativeLuminance,
+  separationRetention,
+  simulateColor,
+  toHex,
+} from './logic';
+
+describe('game UI accessibility stress tester logic', () => {
+  it('matches WCAG reference luminance and contrast cases', () => {
+    expect(relativeLuminance({ r: 0, g: 0, b: 0 })).toBe(0);
+    expect(relativeLuminance({ r: 255, g: 255, b: 255 })).toBe(1);
+    expect(contrastRatio({ r: 0, g: 0, b: 0 }, { r: 255, g: 255, b: 255 })).toBe(21);
+    expect(contrastRatio({ r: 119, g: 119, b: 119 }, { r: 255, g: 255, b: 255 })).toBeCloseTo(4.478, 2);
+  });
+
+  it('applies documented severity one CVD matrices in linear RGB', () => {
+    const red = { r: 255, g: 0, b: 0 };
+    expect(simulateColor(red, 'protanopia')).toEqual({ r: 109, g: 95, b: 0 });
+    expect(simulateColor(red, 'deuteranopia')).toEqual({ r: 163, g: 144, b: 0 });
+    expect(simulateColor(red, 'tritanopia')).toEqual({ r: 255, g: 0, b: 15 });
+  });
+
+  it('preserves black and white through every CVD matrix', () => {
+    const modes = ['protanopia', 'deuteranopia', 'tritanopia'] as const;
+    modes.forEach((mode) => {
+      expect(simulateColor({ r: 0, g: 0, b: 0 }, mode)).toEqual({ r: 0, g: 0, b: 0 });
+      expect(simulateColor({ r: 255, g: 255, b: 255 }, mode)).toEqual({ r: 255, g: 255, b: 255 });
+    });
+  });
+
+  it('supports grayscale, desaturation, reduced contrast and original modes', () => {
+    expect(simulateColor({ r: 255, g: 0, b: 0 }, 'achromatopsia')).toEqual({ r: 127, g: 127, b: 127 });
+    expect(simulateColor({ r: 255, g: 0, b: 0 }, 'desaturation')).toEqual({ r: 159, g: 95, b: 95 });
+    expect(simulateColor({ r: 255, g: 0, b: 0 }, 'reduced-contrast')).toEqual({ r: 198, g: 58, b: 58 });
+    expect(simulateColor({ r: 300, g: -10, b: Number.NaN }, 'original')).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it('measures separation loss with stable limits', () => {
+    const black = { r: 0, g: 0, b: 0 };
+    const white = { r: 255, g: 255, b: 255 };
+    expect(colorDistance(black, black)).toBe(0);
+    expect(separationRetention(black, white, black, white)).toBe(100);
+    expect(separationRetention(black, white, black, black)).toBe(0);
+    expect(separationRetention(black, black, black, white)).toBe(0);
+  });
+
+  it('formats clamped RGB colors as lowercase hexadecimal', () => {
+    expect(toHex({ r: 255, g: 16, b: 0 })).toBe('#ff1000');
+    expect(toHex({ r: -1, g: 300, b: Number.NaN })).toBe('#00ff00');
+    expect(fromHex('#1aB2c3')).toEqual({ r: 26, g: 178, b: 195 });
+    expect(fromHex('invalid')).toBeNull();
+  });
+});

package/src/tool/gameUIAccessibilityTester/logic.ts

@@ -0,0 +1,157 @@
+export type SimulationMode =
+  | 'original'
+  | 'protanopia'
+  | 'deuteranopia'
+  | 'tritanopia'
+  | 'achromatopsia'
+  | 'reduced-contrast'
+  | 'desaturation';
+
+export interface RGBColor {
+  r: number;
+  g: number;
+  b: number;
+}
+
+type Matrix3 = readonly [
+  number, number, number,
+  number, number, number,
+  number, number, number,
+];
+
+const CVD_MATRICES: Partial<Record<SimulationMode, Matrix3>> = {
+  protanopia: [
+    0.152286, 1.052583, -0.204868,
+    0.114503, 0.786281, 0.099216,
+    -0.003882, -0.048116, 1.051998,
+  ],
+  deuteranopia: [
+    0.367322, 0.860646, -0.227968,
+    0.280085, 0.672501, 0.047413,
+    -0.011820, 0.042940, 0.968881,
+  ],
+  tritanopia: [
+    1.255528, -0.076749, -0.178779,
+    -0.078411, 0.930809, 0.147602,
+    0.004733, 0.691367, 0.303900,
+  ],
+};
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  if (!Number.isFinite(value)) return minimum;
+  return Math.min(maximum, Math.max(minimum, value));
+}
+
+function normalizeChannel(value: number): number {
+  return clamp(value, 0, 255) / 255;
+}
+
+function linearize(value: number): number {
+  const channel = normalizeChannel(value);
+  return channel <= 0.04045
+    ? channel / 12.92
+    : ((channel + 0.055) / 1.055) ** 2.4;
+}
+
+function encodeLinear(value: number): number {
+  const channel = clamp(value, 0, 1);
+  const encoded = channel <= 0.0031308
+    ? 12.92 * channel
+    : 1.055 * channel ** (1 / 2.4) - 0.055;
+  return Math.round(encoded * 255);
+}
+
+function multiplyMatrix(color: RGBColor, matrix: Matrix3): RGBColor {
+  const [red, green, blue] = [linearize(color.r), linearize(color.g), linearize(color.b)];
+  return {
+    r: encodeLinear(matrix[0] * red + matrix[1] * green + matrix[2] * blue),
+    g: encodeLinear(matrix[3] * red + matrix[4] * green + matrix[5] * blue),
+    b: encodeLinear(matrix[6] * red + matrix[7] * green + matrix[8] * blue),
+  };
+}
+
+function grayscale(color: RGBColor): RGBColor {
+  const value = encodeLinear(relativeLuminance(color));
+  return { r: value, g: value, b: value };
+}
+
+function reduceContrast(color: RGBColor): RGBColor {
+  const midpoint = 128;
+  const factor = 0.55;
+  return {
+    r: Math.round(midpoint + (clamp(color.r, 0, 255) - midpoint) * factor),
+    g: Math.round(midpoint + (clamp(color.g, 0, 255) - midpoint) * factor),
+    b: Math.round(midpoint + (clamp(color.b, 0, 255) - midpoint) * factor),
+  };
+}
+
+function desaturate(color: RGBColor): RGBColor {
+  const gray = grayscale(color);
+  const saturation = 0.25;
+  return {
+    r: Math.round(gray.r + (clamp(color.r, 0, 255) - gray.r) * saturation),
+    g: Math.round(gray.g + (clamp(color.g, 0, 255) - gray.g) * saturation),
+    b: Math.round(gray.b + (clamp(color.b, 0, 255) - gray.b) * saturation),
+  };
+}
+
+export function simulateColor(color: RGBColor, mode: SimulationMode): RGBColor {
+  const matrix = CVD_MATRICES[mode];
+  if (matrix) return multiplyMatrix(color, matrix);
+  if (mode === 'achromatopsia') return grayscale(color);
+  if (mode === 'reduced-contrast') return reduceContrast(color);
+  if (mode === 'desaturation') return desaturate(color);
+  return {
+    r: Math.round(clamp(color.r, 0, 255)),
+    g: Math.round(clamp(color.g, 0, 255)),
+    b: Math.round(clamp(color.b, 0, 255)),
+  };
+}
+
+export function relativeLuminance(color: RGBColor): number {
+  return 0.2126 * linearize(color.r)
+    + 0.7152 * linearize(color.g)
+    + 0.0722 * linearize(color.b);
+}
+
+export function contrastRatio(first: RGBColor, second: RGBColor): number {
+  const firstLuminance = relativeLuminance(first);
+  const secondLuminance = relativeLuminance(second);
+  const lighter = Math.max(firstLuminance, secondLuminance);
+  const darker = Math.min(firstLuminance, secondLuminance);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export function colorDistance(first: RGBColor, second: RGBColor): number {
+  const red = linearize(first.r) - linearize(second.r);
+  const green = linearize(first.g) - linearize(second.g);
+  const blue = linearize(first.b) - linearize(second.b);
+  return Math.sqrt(red ** 2 + green ** 2 + blue ** 2);
+}
+
+export function separationRetention(
+  originalFirst: RGBColor,
+  originalSecond: RGBColor,
+  simulatedFirst: RGBColor,
+  simulatedSecond: RGBColor,
+): number {
+  const original = colorDistance(originalFirst, originalSecond);
+  if (original === 0) return 0;
+  const simulated = colorDistance(simulatedFirst, simulatedSecond);
+  return clamp((simulated / original) * 100, 0, 100);
+}
+
+export function toHex(color: RGBColor): string {
+  const channel = (value: number) => Math.round(clamp(value, 0, 255)).toString(16).padStart(2, '0');
+  return `#${channel(color.r)}${channel(color.g)}${channel(color.b)}`;
+}
+
+export function fromHex(value: string): RGBColor | null {
+  const match = value.trim().match(/^#([\da-f]{6})$/i)?.[1];
+  if (!match) return null;
+  return {
+    r: Number.parseInt(match.slice(0, 2), 16),
+    g: Number.parseInt(match.slice(2, 4), 16),
+    b: Number.parseInt(match.slice(4, 6), 16),
+  };
+}

package/src/tool/gameUIAccessibilityTester/report.ts

@@ -0,0 +1,59 @@
+import type { PairDiagnostic } from './evaluator';
+import { toHex, type RGBColor, type SimulationMode } from './logic';
+import { triggerDownload } from './dom-views';
+import type { GameUiAccessibilityTesterUI } from './ui';
+
+export interface ReportInput {
+  mode: SimulationMode;
+  blur: number;
+  downscale: number;
+  firstName: string;
+  secondName: string;
+  first: RGBColor;
+  second: RGBColor;
+  diagnostic: PairDiagnostic;
+  findings: string[];
+}
+
+function reportFindings(input: ReportInput, ui: GameUiAccessibilityTesterUI): string[] {
+  const findings = [...input.findings];
+  if (input.diagnostic.status === 'review') findings.unshift(ui.reportFindingReview);
+  return findings;
+}
+
+function createReport(input: ReportInput, ui: GameUiAccessibilityTesterUI): Record<string, unknown> {
+  return {
+    title: ui.reportTitle,
+    generatedAt: new Date().toISOString(),
+    scope: 'manual-review-aid',
+    processing: 'local-browser-only',
+    settings: {
+      simulation: input.mode,
+      blurPixels: input.blur,
+      downscale: input.downscale,
+    },
+    samples: [
+      { name: input.firstName, color: toHex(input.first) },
+      { name: input.secondName, color: toHex(input.second) },
+    ],
+    measurements: {
+      originalContrastRatio: Number(input.diagnostic.originalContrast.toFixed(3)),
+      simulatedContrastRatio: Number(input.diagnostic.simulatedContrast.toFixed(3)),
+    },
+    heuristic: {
+      separationRetainedPercent: Number(input.diagnostic.retained.toFixed(1)),
+      reviewStatus: input.diagnostic.status,
+    },
+    findings: reportFindings(input, ui),
+    limitations: ui.limitationDisclosure,
+  };
+}
+
+export function downloadStructuredReport(
+  input: ReportInput,
+  ui: GameUiAccessibilityTesterUI,
+): void {
+  const report = createReport(input, ui);
+  const blob = new Blob([JSON.stringify(report, null, 2)], { type: 'application/json' });
+  triggerDownload(blob, 'game-ui-accessibility-review.json');
+}

package/src/tool/gameUIAccessibilityTester/seo.astro

@@ -0,0 +1,15 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { gameUiAccessibilityTester } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const loader = gameUiAccessibilityTester.i18n[locale] ?? gameUiAccessibilityTester.i18n.en;
+const content = loader ? await loader() : null;
+---
+
+{content && content.seo.length > 0 && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/gameUIAccessibilityTester/storage.ts

@@ -0,0 +1,34 @@
+import type { SimulationMode } from './logic';
+
+export interface StoredSettings {
+  mode: SimulationMode;
+  compare: 'side' | 'split' | 'press';
+  blur: number;
+  downscale: number;
+  zoom: number;
+  heatmap: boolean;
+}
+
+const STORAGE_KEY = 'game-ui-accessibility-stress-tester-settings';
+
+export function loadSettings(fallback: StoredSettings): StoredSettings {
+  try {
+    const value = localStorage.getItem(STORAGE_KEY);
+    if (!value) return fallback;
+    return { ...fallback, ...JSON.parse(value) as Partial<StoredSettings> };
+  } catch {
+    return fallback;
+  }
+}
+
+export function saveSettings(settings: StoredSettings): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
+  } catch {}
+}
+
+export function clearSettings(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {}
+}

package/src/tool/gameUIAccessibilityTester/ui.ts

@@ -0,0 +1,80 @@
+export interface GameUiAccessibilityTesterUI extends Record<string, string> {
+  onboarding: string;
+  privacyNote: string;
+  dropTitle: string;
+  dropHint: string;
+  chooseImage: string;
+  replaceImage: string;
+  supportedFiles: string;
+  lensLabel: string;
+  lensOriginal: string;
+  lensProtanopia: string;
+  lensDeuteranopia: string;
+  lensTritanopia: string;
+  lensAchromatopsia: string;
+  lensReducedContrast: string;
+  lensDesaturation: string;
+  compareLabel: string;
+  compareSideBySide: string;
+  compareSplit: string;
+  comparePress: string;
+  holdOriginal: string;
+  splitPosition: string;
+  stressLabel: string;
+  blurLabel: string;
+  downscaleLabel: string;
+  downscaleFull: string;
+  downscaleHalf: string;
+  downscaleQuarter: string;
+  downscaleEighth: string;
+  zoomLabel: string;
+  heatmapLabel: string;
+  heatmapHint: string;
+  originalView: string;
+  simulatedView: string;
+  emptyCanvas: string;
+  sampleTitle: string;
+  sampleInstructions: string;
+  sampleA: string;
+  sampleB: string;
+  sampleAName: string;
+  sampleBName: string;
+  manualColor: string;
+  sampleAInitial: string;
+  sampleBInitial: string;
+  noSample: string;
+  originalContrast: string;
+  simulatedContrast: string;
+  separationRetained: string;
+  statusStrong: string;
+  statusWatch: string;
+  statusReview: string;
+  statusPending: string;
+  measurementLabel: string;
+  heuristicLabel: string;
+  manualReviewLabel: string;
+  measurementHint: string;
+  heuristicHint: string;
+  promptTitle: string;
+  promptColorOnly: string;
+  promptChangingBackground: string;
+  promptMinimap: string;
+  promptStates: string;
+  promptShape: string;
+  findingLabel: string;
+  findingPlaceholder: string;
+  addFinding: string;
+  findingsEmpty: string;
+  exportSheet: string;
+  exportReport: string;
+  resetTool: string;
+  uploadError: string;
+  fileTooLarge: string;
+  imageReady: string;
+  reportDownloaded: string;
+  sheetDownloaded: string;
+  localOnlyDisclosure: string;
+  limitationDisclosure: string;
+  reportTitle: string;
+  reportFindingReview: string;
+}

package/src/tools.ts

@@ -9,6 +9,7 @@ import { LOCALIZATION_SANITIZER_TOOL } from './tool/localizationSanitizer';
 import { STEAM_BBCODE_TRANSLATOR_TOOL } from './tool/steamBbcodeTranslator';
 import { RETRO_SFX_GENERATOR_TOOL } from './tool/retroSfxGenerator';
 import { PIXEL_ART_PALETTE_SWAPPER_TOOL } from './tool/pixelArtPaletteSwapper';
+import { GAME_UI_ACCESSIBILITY_TESTER_TOOL } from './tool/gameUIAccessibilityTester';
 
 export const ALL_TOOLS: ToolDefinition[] = [
   STEAM_CAPSULE_GENERATOR_TOOL,
@@ -20,4 +21,5 @@ export const ALL_TOOLS: ToolDefinition[] = [
   STEAM_BBCODE_TRANSLATOR_TOOL,
   RETRO_SFX_GENERATOR_TOOL,
   PIXEL_ART_PALETTE_SWAPPER_TOOL,
+  GAME_UI_ACCESSIBILITY_TESTER_TOOL,
 ];