@jjlmoya/utils-games-development 1.55.0 → 1.57.0

package/package.json

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

package/src/entries.ts

@@ -14,6 +14,8 @@ export { steamBbcodeTranslator } from './tool/steamBbcodeTranslator/entry';
 export type { SteamBbcodeTranslatorUI, SteamBbcodeTranslatorLocaleContent } from './tool/steamBbcodeTranslator/entry';
 export { retroSfxGenerator } from './tool/retroSfxGenerator/entry';
 export type { RetroSfxGeneratorUI, RetroSfxGeneratorLocaleContent } from './tool/retroSfxGenerator/entry';
+export { pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper/entry';
+export type { PixelArtPaletteSwapperUI, PixelArtPaletteSwapperLocaleContent } from './tool/pixelArtPaletteSwapper/entry';
 export { gamesCategory } from './category';
 import { steamCapsuleGenerator } from './tool/steamCapsuleGenerator/entry';
 import { itchioGameTester } from './tool/itchioGameTester/entry';
@@ -21,6 +23,8 @@ import { spriteSheetPacker } from './tool/spriteSheetPacker/entry';
 import { audioLoopPointFinder } from './tool/audioLoopPointFinder/entry';
 import { saveFileEditor } from './tool/saveFileEditor/entry';
 import { localizationSanitizer } from './tool/localizationSanitizer/entry';
+import { steamBbcodeTranslator } from './tool/steamBbcodeTranslator/entry';
 import { retroSfxGenerator } from './tool/retroSfxGenerator/entry';
+import { pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper/entry';
 
-export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer, retroSfxGenerator];
+export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer, steamBbcodeTranslator, retroSfxGenerator, pixelArtPaletteSwapper];

package/src/index.ts

@@ -19,5 +19,6 @@ export { ALL_ENTRIES, ALL_TOOLS } from './tools';
 export { STEAM_CAPSULE_GENERATOR_TOOL, steamCapsuleGenerator } from './tool/steamCapsuleGenerator';
 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 type { ToolLocaleContent as GamesToolLocaleContent } from './types';

package/src/tests/contrast_legibility.test.ts

@@ -5,10 +5,13 @@ import { join, relative } from 'node:path';
 type Color = { r: number; g: number; b: number; a: number };
 type Declaration = { name: string; value: string };
 type CssRule = { selector: string; declarations: Declaration[]; line: number };
+type Theme = 'light' | 'dark';
+type Variables = Record<string, string>;
 
 const toolRoot = join(process.cwd(), 'src', 'tool');
 const minimumTextContrast = 4.5;
 const minimumReviewFontSizeRem = 0.75;
+const themes: Theme[] = ['light', 'dark'];
 
 function findFiles(directory: string, extensions: string[]): string[] {
   const files: string[] = [];
@@ -184,14 +187,48 @@ function simpleBackground(value: string): Color | null {
   return parseColor(value);
 }
 
-function contrastFinding(path: string, rule: CssRule): string | null {
+function isThemeSelector(selector: string, theme: Theme): boolean {
+  return selector.includes(`.theme-${theme}`);
+}
+
+function isActiveRule(selector: string, theme: Theme): boolean {
+  const otherTheme: Theme = theme === 'dark' ? 'light' : 'dark';
+  return !isThemeSelector(selector, otherTheme);
+}
+
+function addVariables(target: Variables, rule: CssRule): void {
+  rule.declarations
+    .filter((declaration) => declaration.name.startsWith('--'))
+    .forEach((declaration) => { target[declaration.name] = declaration.value; });
+}
+
+function collectVariables(rules: CssRule[], theme: Theme): Variables {
+  const variables: Variables = {};
+  rules.filter((rule) => !isThemeSelector(rule.selector, 'dark') && !isThemeSelector(rule.selector, 'light'))
+    .forEach((rule) => addVariables(variables, rule));
+  rules.filter((rule) => isThemeSelector(rule.selector, theme))
+    .forEach((rule) => addVariables(variables, rule));
+  return variables;
+}
+
+function resolveCssValue(value: string, variables: Variables): string {
+  let resolved = value;
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    const next = resolved.replace(/var\(\s*(--[\w-]+)(?:\s*,\s*([^()]+))?\s*\)/g, (_, name, fallback) => variables[name] ?? fallback ?? '');
+    if (next === resolved) return resolved;
+    resolved = next;
+  }
+  return resolved;
+}
+
+function contrastFinding(path: string, rule: CssRule, theme: Theme, variables: Variables): string | null {
   const foreground = lastDeclaration(rule.declarations, ['color']);
   const background = lastDeclaration(rule.declarations, ['background-color', 'background']);
-  const foregroundColor = foreground ? parseColor(foreground.value) : null;
-  const backgroundColor = background ? simpleBackground(background.value) : null;
+  const foregroundColor = foreground ? parseColor(resolveCssValue(foreground.value, variables)) : null;
+  const backgroundColor = background ? simpleBackground(resolveCssValue(background.value, variables)) : null;
   const ratio = foregroundColor && backgroundColor ? contrastRatio(foregroundColor, backgroundColor) : null;
   return ratio !== null && ratio < minimumTextContrast
-    ? `[A11Y-06] ${relativePath(path)}:${rule.line} ${rule.selector} — ${ratio.toFixed(2)}:1 `
+    ? `[A11Y-06][${theme}] ${relativePath(path)}:${rule.line} ${rule.selector} — ${ratio.toFixed(2)}:1 `
       + `(mínimo ${minimumTextContrast}:1)`
     : null;
 }
@@ -205,18 +242,27 @@ function fontSizeFinding(path: string, rule: CssRule): string | null {
     + `(revisar por debajo de ${minimumReviewFontSizeRem}rem)`;
 }
 
-function inspectRule(path: string, rule: CssRule): { contrastFailures: string[]; fontSizeCandidates: string[] } {
-  const contrast = contrastFinding(path, rule);
-  const fontSize = fontSizeFinding(path, rule);
+function inspectSource(path: string, source: string): { contrastFailures: string[]; fontSizeCandidates: string[] } {
+  const rules = parseRules(source);
+  const contrastFailures = themes.flatMap((theme) => {
+    const variables = collectVariables(rules, theme);
+    return rules
+      .filter((rule) => isActiveRule(rule.selector, theme))
+      .map((rule) => contrastFinding(path, rule, theme, variables))
+      .filter((finding): finding is string => finding !== null);
+  });
+  const fontSizeCandidates = rules
+    .map((rule) => fontSizeFinding(path, rule))
+    .filter((finding): finding is string => finding !== null);
   return {
-    contrastFailures: contrast ? [contrast] : [],
-    fontSizeCandidates: fontSize ? [fontSize] : [],
+    contrastFailures,
+    fontSizeCandidates,
   };
 }
 
 function inspectStyles(): { contrastFailures: string[]; fontSizeCandidates: string[] } {
   const findings = findFiles(toolRoot, ['.css', '.astro'])
-    .flatMap((path) => cssSources(path).flatMap((source) => parseRules(source).map((rule) => inspectRule(path, rule))));
+    .flatMap((path) => cssSources(path).map((source) => inspectSource(path, source)));
   return {
     contrastFailures: findings.flatMap((finding) => finding.contrastFailures),
     fontSizeCandidates: findings.flatMap((finding) => finding.fontSizeCandidates),

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('eight tools are registered', () => {
-    expect(ALL_TOOLS.length).toBe(8);
+  it('nine tools are registered', () => {
+    expect(ALL_TOOLS.length).toBe(9);
   });
 });

package/src/tests/runtime_registry.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ALL_ENTRIES } from '../entries';
+import { ALL_TOOLS } from '../tools';
+
+describe('runtime registry', () => {
+  it('keeps every runtime tool represented in the data registry', () => {
+    const toolIds = ALL_TOOLS.map(({ entry }) => entry.id).sort();
+    const entryIds = ALL_ENTRIES.map(({ id }) => id).sort();
+
+    expect(entryIds).toEqual(toolIds);
+  });
+
+  it('keeps every runtime directory represented in the data registry', () => {
+    const runtimeIds = readdirSync(join(process.cwd(), 'src', 'tool'), { withFileTypes: true })
+      .filter((directory) => directory.isDirectory())
+      .map((directory) => join(process.cwd(), 'src', 'tool', directory.name))
+      .filter((directory) => existsSync(join(directory, 'index.ts')) && existsSync(join(directory, 'entry.ts')))
+      .map((directory) => readFileSync(join(directory, 'entry.ts'), 'utf8').match(/\bid\s*:\s*['"]([^'"]+)['"]/)?.[1])
+      .filter((id): id is string => Boolean(id))
+      .sort();
+
+    const entryIds = ALL_ENTRIES.map(({ id }) => id).sort();
+    expect(entryIds).toEqual(runtimeIds);
+  });
+});

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 8 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(8);
+    it('should have 9 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(9);
     });
 
     it('gamesCategory should be defined', () => {

package/src/tool/localizationSanitizer/localization-sanitizer.css

@@ -6,6 +6,7 @@
   --ls-panel-soft: #f4f7fa;
   --ls-accent: #e56a47;
   --ls-accent-dark: #bc4d30;
+  --ls-on-accent: #17202f;
   --ls-cyan: #19a6a0;
   --ls-yellow: #e7a633;
   --ls-red: #ce4f61;
@@ -24,6 +25,7 @@
   --ls-panel-soft: #172232;
   --ls-accent: #f1845d;
   --ls-accent-dark: #da6744;
+  --ls-on-accent: #111926;
   --ls-cyan: #42c3b8;
   --ls-yellow: #efbd57;
   --ls-red: #f07889;
@@ -170,7 +172,7 @@
 
 .ls-drop-mark span:last-child {
   background: var(--ls-accent);
-  color: var(--ls-panel);
+  color: var(--ls-on-accent);
   transform: translateX(0.4rem);
 }
 
@@ -219,7 +221,7 @@
 
 .ls-button-primary {
   background: var(--ls-accent);
-  color: var(--ls-panel);
+  color: var(--ls-on-accent);
 }
 
 .ls-button-primary:hover:not(:disabled) {

package/src/tool/pixelArtPaletteSwapper/app-client.ts

@@ -0,0 +1,234 @@
+import {
+  PRESET_PALETTES,
+  parsePaletteInput,
+  quantizeImageData,
+  type PaletteColor,
+} from './logic';
+
+interface SourceImageState {
+  name: string;
+  width: number;
+  height: number;
+  data: Uint8ClampedArray;
+}
+
+interface AppEls {
+  root: HTMLElement;
+  fileInput: HTMLInputElement;
+  chooseButton: HTMLButtonElement;
+  dropZone: HTMLElement;
+  sourceCanvas: HTMLCanvasElement;
+  resultCanvas: HTMLCanvasElement;
+  emptyState: HTMLElement;
+  canvasPair: HTMLElement;
+  customPaletteInput: HTMLTextAreaElement;
+  downloadButton: HTMLButtonElement;
+  zoomInput: HTMLInputElement;
+  zoomValue: HTMLOutputElement;
+}
+
+let initialized = false;
+
+function getEl<T extends HTMLElement>(root: HTMLElement, sel: string): T | null {
+  return root.querySelector<T>(sel);
+}
+
+function queryAppElements(root: HTMLElement): AppEls | null {
+  const req = [
+    '#pas-file-input', '#pas-choose-image', '#pas-drop-zone',
+    '#pas-source-canvas', '#pas-result-canvas', '#pas-empty-state',
+    '#pas-canvas-pair', '#pas-custom-palette', '#pas-download',
+    '#pas-zoom', '#pas-zoom-value',
+  ];
+  const found = req.map((s) => root.querySelector(s));
+  if (found.some((el) => !el)) return null;
+
+  return {
+    root,
+    fileInput: found[0] as HTMLInputElement,
+    chooseButton: found[1] as HTMLButtonElement,
+    dropZone: found[2] as HTMLElement,
+    sourceCanvas: found[3] as HTMLCanvasElement,
+    resultCanvas: found[4] as HTMLCanvasElement,
+    emptyState: found[5] as HTMLElement,
+    canvasPair: found[6] as HTMLElement,
+    customPaletteInput: found[7] as HTMLTextAreaElement,
+    downloadButton: found[8] as HTMLButtonElement,
+    zoomInput: found[9] as HTMLInputElement,
+    zoomValue: found[10] as HTMLOutputElement,
+  };
+}
+
+function renderSwatches(root: HTMLElement): void {
+  root.querySelectorAll<HTMLElement>('[data-swatch-palette]').forEach((strip) => {
+    const id = strip.dataset.swatchPalette;
+    const palette = id && id in PRESET_PALETTES
+      ? PRESET_PALETTES[id as keyof typeof PRESET_PALETTES]
+      : [];
+    strip.replaceChildren(...palette.map((c) => {
+      const s = document.createElement('span');
+      s.style.backgroundColor = c.hex;
+      return s;
+    }));
+  });
+}
+
+function fitCanvas(canvas: HTMLCanvasElement, width: number, height: number, zoom: number): void {
+  const displayWidth = Math.min(620, Math.max(32, width * zoom));
+  const displayHeight = Math.max(32, Math.round(displayWidth * height / width));
+  canvas.style.width = `${displayWidth}px`;
+  canvas.style.height = `${displayHeight}px`;
+}
+
+interface CanvasDrawOptions {
+  canvas: HTMLCanvasElement;
+  width: number;
+  height: number;
+  data: Uint8ClampedArray;
+  zoom: number;
+}
+
+function drawCanvas(opts: CanvasDrawOptions): void {
+  opts.canvas.width = opts.width;
+  opts.canvas.height = opts.height;
+  const context = opts.canvas.getContext('2d');
+  if (!context) return;
+  context.imageSmoothingEnabled = false;
+  context.putImageData(new ImageData(new Uint8ClampedArray(opts.data), opts.width, opts.height), 0, 0);
+  fitCanvas(opts.canvas, opts.width, opts.height, opts.zoom);
+}
+
+function setStatus(root: HTMLElement, message: string, tone = 'idle'): void {
+  const statusEl = getEl<HTMLElement>(root, '#pas-status');
+  if (!statusEl) return;
+  statusEl.textContent = message;
+  statusEl.dataset.tone = tone;
+}
+
+function updateSummaryTexts(root: HTMLElement, q: { sourceColors: number; mappedColors: number }, width: number, height: number): void {
+  const scc = getEl<HTMLElement>(root, '#pas-source-colors');
+  const mcc = getEl<HTMLElement>(root, '#pas-mapped-colors');
+  const isz = getEl<HTMLElement>(root, '#pas-image-size');
+  const rn = getEl<HTMLElement>(root, '#pas-render-note');
+  if (scc) scc.textContent = String(q.sourceColors);
+  if (mcc) mcc.textContent = String(q.mappedColors);
+  if (isz) isz.textContent = `${width} × ${height}`;
+  if (rn) rn.textContent = (root.dataset.mappedSummary ?? '').replace('{source}', String(q.sourceColors)).replace('{mapped}', String(q.mappedColors));
+}
+
+function processImageLoad(els: AppEls, file: File, img: HTMLImageElement): SourceImageState | null {
+  const canvas = document.createElement('canvas');
+  canvas.width = img.naturalWidth;
+  canvas.height = img.naturalHeight;
+  const ctx = canvas.getContext('2d', { willReadFrequently: true });
+  if (!ctx) return null;
+  ctx.imageSmoothingEnabled = false;
+  ctx.drawImage(img, 0, 0);
+  const data = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
+  const fn = getEl<HTMLElement>(els.root, '#pas-file-name');
+  if (fn) fn.textContent = file.name;
+  getEl<HTMLElement>(els.root, '.pas-command-bar')?.classList.add('has-image');
+  els.chooseButton.textContent = els.root.dataset.replaceImage ?? 'Replace image';
+  els.emptyState.hidden = true;
+  els.canvasPair.hidden = false;
+  return { name: file.name, width: canvas.width, height: canvas.height, data };
+}
+
+function setupFileHandler(els: AppEls, onLoaded: (src: SourceImageState) => void): void {
+  els.chooseButton.addEventListener('click', () => els.fileInput.click());
+  els.dropZone.addEventListener('click', () => els.fileInput.click());
+  els.fileInput.addEventListener('change', () => {
+    const file = els.fileInput.files?.[0];
+    if (!file || !file.type.startsWith('image/')) return;
+    const url = URL.createObjectURL(file);
+    const img = new Image();
+    img.onload = () => {
+      const src = processImageLoad(els, file, img);
+      if (src) onLoaded(src);
+      URL.revokeObjectURL(url);
+    };
+    img.src = url;
+  });
+}
+
+function setupPresetButtons(els: AppEls, onApply: (p: PaletteColor[], id: string) => void): void {
+  els.root.querySelectorAll<HTMLButtonElement>('[data-palette-id]').forEach((b) => b.addEventListener('click', () => {
+    const id = b.dataset.paletteId ?? 'gameBoy';
+    const palette = PRESET_PALETTES[id as keyof typeof PRESET_PALETTES];
+    if (!palette) return;
+    els.customPaletteInput.value = palette.map((c) => c.hex).join(', ');
+    onApply(palette, id);
+  }));
+}
+
+function setupCustomAndDownload(els: AppEls, onCustomApply: (hexList: string) => void, onCustomReset: () => void, onDownload: () => void): void {
+  getEl<HTMLButtonElement>(els.root, '#pas-apply-custom')?.addEventListener('click', () => onCustomApply(els.customPaletteInput.value));
+  getEl<HTMLButtonElement>(els.root, '#pas-reset-custom')?.addEventListener('click', () => onCustomReset());
+  els.downloadButton.addEventListener('click', onDownload);
+}
+
+function triggerDownload(canvas: HTMLCanvasElement, name: string, id: string): void {
+  canvas.toBlob((blob) => {
+    if (!blob) return;
+    const a = document.createElement('a');
+    a.download = `${name.replace(/\.[^.]+$/, '') || 'pixel-art'}-${id}.png`;
+    a.href = URL.createObjectURL(blob);
+    a.click();
+  }, 'image/png');
+}
+
+function runQuantizeRender(els: AppEls, src: SourceImageState, pal: PaletteColor[]): Uint8ClampedArray {
+  setStatus(els.root, els.root.dataset.processing ?? 'Mapping pixels', 'working');
+  const alpha = getEl<HTMLInputElement>(els.root, '#pas-preserve-alpha')?.checked ?? true;
+  const q = quantizeImageData(src.data, pal, alpha);
+  drawCanvas({ canvas: els.resultCanvas, width: src.width, height: src.height, data: q.data, zoom: Number(els.zoomInput.value) });
+  const ip = getEl<HTMLElement>(els.root, '#pas-inspector-preview');
+  if (ip) ip.style.backgroundImage = `url(${els.resultCanvas.toDataURL('image/png')})`;
+  updateSummaryTexts(els.root, q, src.width, src.height);
+  setStatus(els.root, els.root.dataset.ready ?? 'Ready', 'ready');
+  els.downloadButton.disabled = false;
+  return q.data;
+}
+
+function setupCoreAppLogic(els: AppEls): void {
+  let activePalette = PRESET_PALETTES.gameBoy;
+  let sourceImage: SourceImageState | null = null;
+  let resultData: Uint8ClampedArray | null = null;
+  let activePaletteId = 'gameBoy';
+
+  const renderResult = (): void => {
+    if (sourceImage) resultData = runQuantizeRender(els, sourceImage, activePalette);
+  };
+
+  const applyPalette = (palette: PaletteColor[], paletteId: string): void => {
+    if (palette.length === 0) return;
+    activePalette = palette;
+    activePaletteId = paletteId;
+    els.root.querySelectorAll<HTMLButtonElement>('[data-palette-id]').forEach((b) => b.classList.toggle('is-selected', b.dataset.paletteId === paletteId));
+    renderResult();
+  };
+
+  setupFileHandler(els, (src) => {
+    sourceImage = src;
+    drawCanvas({ canvas: els.sourceCanvas, width: src.width, height: src.height, data: src.data, zoom: Number(els.zoomInput.value) });
+    renderResult();
+  });
+  setupPresetButtons(els, applyPalette);
+  setupCustomAndDownload(els,
+    (val) => applyPalette(parsePaletteInput(val), 'custom'),
+    () => { els.customPaletteInput.value = PRESET_PALETTES.gameBoy.map((c) => c.hex).join(', '); applyPalette(PRESET_PALETTES.gameBoy, 'gameBoy'); },
+    () => { if (sourceImage && resultData) triggerDownload(els.resultCanvas, sourceImage.name, activePaletteId); }
+  );
+}
+
+export function initPixelArtPaletteSwapper(): void {
+  if (initialized) return;
+  initialized = true;
+  const root = getEl<HTMLElement>(document.body, '[data-tool="pixel-art-palette-swapper"]');
+  if (!root) return;
+  const els = queryAppElements(root);
+  if (!els) return;
+
+  setupCoreAppLogic(els);
+  renderSwatches(els.root);
+}

package/src/tool/pixelArtPaletteSwapper/bibliography.astro

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

package/src/tool/pixelArtPaletteSwapper/bibliography.ts

@@ -0,0 +1,16 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliographyEntries: BibliographyEntry[] = [
+  {
+    name: 'MDN Canvas API',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API',
+  },
+  {
+    name: 'Lospec Palette List',
+    url: 'https://lospec.com/palette-list',
+  },
+  {
+    name: 'W3C Portable Network Graphics Specification',
+    url: 'https://www.w3.org/TR/png-3/',
+  },
+];

package/src/tool/pixelArtPaletteSwapper/component.astro

@@ -0,0 +1,153 @@
+---
+import type { PixelArtPaletteSwapperUI } from './ui';
+import './pixel-art-palette-swapper.css';
+
+interface Props {
+  ui: PixelArtPaletteSwapperUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<div
+  class="pas-shell"
+  data-tool="pixel-art-palette-swapper"
+  data-processing={ui.processing}
+  data-ready={ui.readyStatus}
+  data-invalid-palette={ui.invalidPalette}
+  data-invalid-image={ui.invalidImage}
+  data-mapped-summary={ui.mappedSummary}
+  data-replace-image={ui.replaceImage}
+  data-drop-active={ui.dropActive}
+  data-upload-title={ui.uploadTitle}
+>
+  <div class="pas-command-bar">
+    <div class="pas-drop-zone" id="pas-drop-zone" tabindex="0" role="button" aria-label={ui.uploadTitle}>
+      <span class="pas-drop-mark" aria-hidden="true">+</span>
+      <span class="pas-drop-copy">
+        <strong id="pas-drop-title">{ui.uploadTitle}</strong>
+        <small id="pas-drop-hint">{ui.uploadHint}</small>
+      </span>
+      <input id="pas-file-input" class="pas-visually-hidden" type="file" accept="image/png,image/jpeg,image/webp" aria-label={ui.chooseImage} />
+    </div>
+    <button id="pas-choose-image" class="pas-button pas-button-primary" type="button">{ui.chooseImage}</button>
+    <span id="pas-file-name" class="pas-file-name">{ui.waitingForImage}</span>
+    <span id="pas-status" class="pas-status" role="status" aria-live="polite">{ui.waitingForImage}</span>
+  </div>
+
+  <div class="pas-workbench">
+    <aside class="pas-panel pas-palette-panel">
+      <div class="pas-panel-heading">
+        <span class="pas-kicker">01</span>
+        <h2>{ui.paletteTitle}</h2>
+      </div>
+
+      <div class="pas-preset-grid" role="list" aria-label={ui.paletteTitle}>
+        <button class="pas-preset is-selected" type="button" data-palette-id="gameBoy" role="listitem">
+          <span class="pas-preset-name">{ui.gameBoyPalette}</span>
+          <span class="pas-swatch-strip" data-swatch-palette="gameBoy" aria-hidden="true"></span>
+        </button>
+        <button class="pas-preset" type="button" data-palette-id="nes" role="listitem">
+          <span class="pas-preset-name">{ui.nesPalette}</span>
+          <span class="pas-swatch-strip" data-swatch-palette="nes" aria-hidden="true"></span>
+        </button>
+        <button class="pas-preset" type="button" data-palette-id="pico8" role="listitem">
+          <span class="pas-preset-name">{ui.pico8Palette}</span>
+          <span class="pas-swatch-strip" data-swatch-palette="pico8" aria-hidden="true"></span>
+        </button>
+        <button class="pas-preset" type="button" data-palette-id="commodore64" role="listitem">
+          <span class="pas-preset-name">{ui.commodore64Palette}</span>
+          <span class="pas-swatch-strip" data-swatch-palette="commodore64" aria-hidden="true"></span>
+        </button>
+        <button class="pas-preset" type="button" data-palette-id="dawnBringer16" role="listitem">
+          <span class="pas-preset-name">{ui.dawnBringerPalette}</span>
+          <span class="pas-swatch-strip" data-swatch-palette="dawnBringer16" aria-hidden="true"></span>
+        </button>
+      </div>
+
+      <div class="pas-custom-block">
+        <div class="pas-field-heading">
+          <label for="pas-custom-palette">{ui.customPalette}</label>
+          <span id="pas-palette-count">4 {ui.paletteCount}</span>
+        </div>
+        <textarea id="pas-custom-palette" rows="3" spellcheck="false" aria-describedby="pas-custom-hint">#0f380f, #306230, #8bac0f, #9bbc0f</textarea>
+        <small id="pas-custom-hint">{ui.customPaletteHint}</small>
+        <div class="pas-inline-actions">
+          <button id="pas-apply-custom" class="pas-button pas-button-dark" type="button">{ui.applyCustomPalette}</button>
+          <button id="pas-reset-custom" class="pas-text-button" type="button">{ui.resetCustomPalette}</button>
+        </div>
+      </div>
+
+      <label class="pas-toggle-row" for="pas-preserve-alpha">
+        <span>{ui.preserveAlpha}</span>
+        <input id="pas-preserve-alpha" type="checkbox" checked />
+        <span class="pas-toggle" aria-hidden="true"></span>
+      </label>
+    </aside>
+
+    <main class="pas-preview-panel">
+      <div class="pas-panel-heading pas-preview-heading">
+        <div>
+          <span class="pas-kicker">02</span>
+          <h2>{ui.sourcePreview} <span aria-hidden="true">→</span> {ui.resultPreview}</h2>
+        </div>
+        <label class="pas-zoom-control" for="pas-zoom">
+          <span>{ui.zoomLabel}</span>
+          <input id="pas-zoom" type="range" min="1" max="8" value="3" />
+          <output id="pas-zoom-value" for="pas-zoom">3x</output>
+        </label>
+      </div>
+
+      <div class="pas-canvas-stage" id="pas-canvas-stage">
+        <div class="pas-empty-state" id="pas-empty-state">
+          <div class="pas-empty-pixel" aria-hidden="true"></div>
+          <strong>{ui.uploadToPreview}</strong>
+          <span>{ui.resultEmpty}</span>
+        </div>
+        <div class="pas-canvas-pair" id="pas-canvas-pair" hidden>
+          <figure class="pas-canvas-card">
+            <figcaption><span class="pas-dot pas-dot-source"></span>{ui.sourcePreview}</figcaption>
+            <canvas id="pas-source-canvas" width="1" height="1" aria-label={ui.sourcePreview}></canvas>
+          </figure>
+          <figure class="pas-canvas-card pas-result-card">
+            <figcaption><span class="pas-dot pas-dot-result"></span>{ui.resultPreview}</figcaption>
+            <canvas id="pas-result-canvas" width="1" height="1" aria-label={ui.resultPreview}></canvas>
+          </figure>
+        </div>
+      </div>
+
+      <div class="pas-preview-footer">
+        <span class="pas-shortcut">PNG <span aria-hidden="true">·</span> RGB nearest-color mapping</span>
+        <span id="pas-render-note">{ui.waitingForImage}</span>
+      </div>
+    </main>
+
+    <aside class="pas-panel pas-inspector-panel">
+      <div class="pas-panel-heading">
+        <span class="pas-kicker">03</span>
+        <h2>{ui.resultPreview}</h2>
+      </div>
+      <div class="pas-inspector-preview" id="pas-inspector-preview" aria-hidden="true">
+        <div class="pas-inspector-pixel-grid"></div>
+      </div>
+      <div class="pas-stats-list">
+        <div><span>{ui.imageSize}</span><strong id="pas-image-size">—</strong></div>
+        <div><span>{ui.colorCount}</span><strong id="pas-source-colors">—</strong></div>
+        <div><span>{ui.mappedCount}</span><strong id="pas-mapped-colors">—</strong></div>
+        <div><span>{ui.paletteCount}</span><strong id="pas-inspector-palette-count">4</strong></div>
+      </div>
+      <button id="pas-download" class="pas-button pas-download-button" type="button" disabled>{ui.downloadPng}</button>
+      <span id="pas-download-hint" class="pas-download-hint">{ui.downloadDisabled}</span>
+    </aside>
+  </div>
+</div>
+
+<script>
+  import { initPixelArtPaletteSwapper } from './app-client';
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initPixelArtPaletteSwapper, { once: true });
+  } else {
+    initPixelArtPaletteSwapper();
+  }
+</script>

package/src/tool/pixelArtPaletteSwapper/entry.ts

@@ -0,0 +1,28 @@
+import type { GamesToolEntry, ToolLocaleContent } from '../../types';
+import type { PixelArtPaletteSwapperUI } from './ui';
+
+export type { PixelArtPaletteSwapperUI };
+
+export type PixelArtPaletteSwapperLocaleContent = ToolLocaleContent<PixelArtPaletteSwapperUI>;
+
+export const pixelArtPaletteSwapper: GamesToolEntry<PixelArtPaletteSwapperUI> = {
+  id: 'pixel-art-palette-swapper',
+  icons: { bg: 'mdi:palette', fg: 'mdi:format-color-fill' },
+  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),
+  },
+};