@jjlmoya/utils-games-development 1.68.0 → 1.70.0

package/src/tool/fixerEditor/runtime.ts

@@ -0,0 +1,88 @@
+import { createFrameSpecs, detectGridFromImageData } from './logic';
+import { saveDraftImage } from './storage';
+import type { ControllerContext } from './controller';
+
+export function loadImage(context: ControllerContext, file: File): void {
+  const image = new Image();
+  image.onload = () => rememberImage(context, image, file.name, file);
+  image.onerror = () => { context.refs.status.textContent = context.ui.statusInvalidImage; URL.revokeObjectURL(image.src); };
+  image.src = URL.createObjectURL(file);
+}
+
+function rememberImage(context: ControllerContext, image: HTMLImageElement, sourceName: string, file: File): void {
+  const reader = new FileReader();
+  reader.onload = () => {
+    const imageDataUrl = typeof reader.result === 'string' ? reader.result : undefined;
+    if (imageDataUrl) saveDraftImage(imageDataUrl);
+    applyImage(context, image, sourceName, imageDataUrl);
+  };
+  reader.onerror = () => applyImage(context, image, sourceName);
+  reader.readAsDataURL(file);
+}
+
+export function restoreDraftImage(context: ControllerContext, sourceImage: string, sourceName: string): void {
+  const image = new Image();
+  image.onload = () => applyImage(context, image, sourceName, sourceImage);
+  image.onerror = () => { context.refs.status.textContent = context.ui.statusInvalidImage; };
+  image.src = sourceImage;
+}
+
+function applyImage(context: ControllerContext, image: HTMLImageElement, sourceName: string, imageDataUrl?: string): void {
+  const pending = context.state.pendingProject;
+  const matchesProject = !pending || hasMatchingSize(pending, image);
+  context.state.image = image;
+  if (imageDataUrl) context.state.imageDataUrl = imageDataUrl;
+  else delete context.state.imageDataUrl;
+  context.state.sourceName = sourceName;
+  context.state.grid = chooseGrid(pending, matchesProject, context.state.grid, image);
+  context.state.adjustments = chooseAdjustments(pending, matchesProject);
+  context.state.pendingProject = null;
+  context.state.frames = createFrameSpecs(image.naturalWidth, image.naturalHeight, context.state.grid);
+  context.state.selected = Math.min(context.state.selected, Math.max(0, context.state.frames.length - 1));
+  context.updateView(matchesProject ? context.ui.loaded : context.ui.statusImageMismatch);
+  URL.revokeObjectURL(image.src);
+}
+
+function chooseGrid(project: NonNullable<ControllerContext['state']['pendingProject']> | null, matches: boolean, current: ControllerContext['state']['grid'], image: HTMLImageElement): ControllerContext['state']['grid'] {
+  if (matches && project) return project.grid;
+  return detectImageGrid(image) ?? current;
+}
+
+function chooseAdjustments(project: NonNullable<ControllerContext['state']['pendingProject']> | null, matches: boolean): ControllerContext['state']['adjustments'] {
+  if (!matches) return {};
+  return project?.adjustments ?? {};
+}
+
+function hasMatchingSize(project: NonNullable<ControllerContext['state']['pendingProject']>, image: HTMLImageElement): boolean {
+  return project.sourceWidth === image.naturalWidth && project.sourceHeight === image.naturalHeight;
+}
+
+function detectImageGrid(image: HTMLImageElement) {
+  const canvas = document.createElement('canvas');
+  canvas.width = image.naturalWidth;
+  canvas.height = image.naturalHeight;
+  const context = canvas.getContext('2d');
+  if (!context) return null;
+  context.drawImage(image, 0, 0);
+  return detectGridFromImageData(context.getImageData(0, 0, canvas.width, canvas.height).data, canvas.width, canvas.height);
+}
+
+export function autoDetectGrid(context: ControllerContext): void {
+  const { state, ui } = context;
+  if (!state.image) return;
+  const grid = detectImageGrid(state.image);
+  if (!grid) return;
+  context.recordHistory();
+  state.grid = grid;
+  state.frames = createFrameSpecs(state.image.naturalWidth, state.image.naturalHeight, state.grid);
+  state.selected = Math.min(state.selected, Math.max(0, state.frames.length - 1));
+  context.updateView(ui.ready);
+}
+
+export function animate(context: ControllerContext): void {
+  const { state } = context;
+  if (!state.playing || !state.image || state.frames.length === 0) return;
+  state.selected = (state.selected + 1) % state.frames.length;
+  context.updateView(context.ui.ready);
+  state.animationId = window.setTimeout(() => animate(context), 1000 / state.fps);
+}

package/src/tool/fixerEditor/seo.astro

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

package/src/tool/fixerEditor/state.ts

@@ -0,0 +1,10 @@
+import { DEFAULT_GRID } from './logic';
+import type { EditorState } from './controller';
+import type { DraftFile } from './types';
+
+export function createInitialState(draft: DraftFile | null): EditorState {
+  const saved = { sourceName: '', grid: DEFAULT_GRID, adjustments: {}, selected: 0, step: 1, zoom: 3, fps: 12, ...(draft || {}) };
+  const state: EditorState = { image: null, sourceName: saved.sourceName, grid: saved.grid, frames: [], adjustments: saved.adjustments, selected: saved.selected, step: saved.step, zoom: saved.zoom, fps: saved.fps, playing: false, animationId: null, history: [], future: [], pendingProject: draft };
+  if (saved.sourceImage) state.imageDataUrl = saved.sourceImage;
+  return state;
+}

package/src/tool/fixerEditor/storage.ts

@@ -0,0 +1,68 @@
+import { clamp, parseProjectFile } from './logic';
+import type { DraftFile, DraftSession, ProjectFile } from './types';
+
+const STORAGE_KEY = 'jjlmoya-fixer-editor-draft-v1';
+const IMAGE_KEY = 'jjlmoya-fixer-editor-image-v1';
+
+export function saveDraft(project: ProjectFile, session: DraftSession): boolean {
+  try {
+    const draft = { ...project, ...session };
+    delete draft.sourceImage;
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(draft));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function loadDraft(): DraftFile | null {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const value = JSON.parse(raw) as unknown;
+    const project = parseProjectFile(value);
+    const sourceImage = loadDraftImage();
+    return project ? { ...project, ...readDraftSession(value), ...(sourceImage ? { sourceImage } : {}) } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveDraftImage(sourceImage: string): boolean {
+  try {
+    localStorage.setItem(IMAGE_KEY, sourceImage);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function loadDraftImage(): string | null {
+  try {
+    const sourceImage = localStorage.getItem(IMAGE_KEY);
+    return sourceImage && sourceImage.startsWith('data:image/') ? sourceImage : null;
+  } catch {
+    return null;
+  }
+}
+
+function readDraftSession(value: unknown): DraftSession {
+  const candidate = value && typeof value === 'object' ? value as Partial<DraftSession> : {};
+  const session: DraftSession = { selected: readInteger(candidate.selected, 0, 8192, 0), step: readInteger(candidate.step, 1, 4, 1), zoom: readInteger(candidate.zoom, 1, 8, 3), fps: readInteger(candidate.fps, 1, 30, 12) };
+  if (typeof candidate.sourceImage === 'string') session.sourceImage = candidate.sourceImage;
+  return session;
+}
+
+function readInteger(value: unknown, min: number, max: number, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isInteger(value)) return fallback;
+  return clamp(value, min, max);
+}
+
+export function clearDraft(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+    localStorage.removeItem(IMAGE_KEY);
+  } catch {
+    return;
+  }
+}

package/src/tool/fixerEditor/types.ts

@@ -0,0 +1,70 @@
+export interface GridSettings {
+  columns: number;
+  rows: number;
+  cellWidth: number;
+  cellHeight: number;
+  marginX: number;
+  marginY: number;
+  gapX: number;
+  gapY: number;
+}
+
+export interface CropRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface FrameAdjustment {
+  crop: CropRect;
+  offsetX: number;
+  offsetY: number;
+}
+
+export interface FrameSpec {
+  index: number;
+  row: number;
+  column: number;
+  sourceX: number;
+  sourceY: number;
+  width: number;
+  height: number;
+  adjustment: FrameAdjustment;
+}
+
+export interface FrameMetadata {
+  index: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  crop: CropRect;
+  offset: { x: number; y: number };
+  modified: boolean;
+}
+
+export interface ProjectFile {
+  version: 1;
+  sourceName: string;
+  sourceWidth: number;
+  sourceHeight: number;
+  grid: GridSettings;
+  adjustments: Record<string, FrameAdjustment>;
+}
+
+export interface DraftSession {
+  selected: number;
+  step: number;
+  zoom: number;
+  fps: number;
+  sourceImage?: string;
+}
+
+export type DraftFile = ProjectFile & DraftSession;
+
+export interface HistoryState {
+  grid: GridSettings;
+  adjustments: Record<string, FrameAdjustment>;
+  selected: number;
+}

package/src/tool/fixerEditor/ui.ts

@@ -0,0 +1,71 @@
+export interface FixerEditorUI extends Record<string, string> {
+  uploadTitle: string;
+  uploadHint: string;
+  chooseImage: string;
+  sourceFile: string;
+  noImage: string;
+  gridSettings: string;
+  columns: string;
+  rows: string;
+  cellWidth: string;
+  cellHeight: string;
+  marginX: string;
+  marginY: string;
+  gapX: string;
+  gapY: string;
+  frameTools: string;
+  cropX: string;
+  cropY: string;
+  cropWidth: string;
+  cropHeight: string;
+  offsetX: string;
+  offsetY: string;
+  trimTransparent: string;
+  trimAll: string;
+  autoDetectGrid: string;
+  resetFrame: string;
+  nudgeStep: string;
+  stepOne: string;
+  stepTwo: string;
+  stepFour: string;
+  history: string;
+  undo: string;
+  redo: string;
+  resetAll: string;
+  saveProject: string;
+  loadProject: string;
+  exportSheet: string;
+  exportJson: string;
+  sheetView: string;
+  correctedView: string;
+  activeFrame: string;
+  frameStrip: string;
+  flipbook: string;
+  play: string;
+  pause: string;
+  fps: string;
+  zoom: string;
+  ready: string;
+  loaded: string;
+  modified: string;
+  unchanged: string;
+  frameCount: string;
+  correctionCount: string;
+  imageSize: string;
+  statusEmpty: string;
+  statusSaved: string;
+  statusLoaded: string;
+  statusExported: string;
+  statusInvalidImage: string;
+  statusInvalidProject: string;
+  statusProjectNeedsImage: string;
+  statusImageMismatch: string;
+  metadataNote: string;
+  sourceLabel: string;
+  resultLabel: string;
+  selectFrame: string;
+  moveUp: string;
+  moveDown: string;
+  moveLeft: string;
+  moveRight: string;
+}

package/src/tool/gamePixelPerUnitPlanner/bibliography.astro

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

package/src/tool/gamePixelPerUnitPlanner/bibliography.ts

@@ -0,0 +1,20 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliographyEntries: BibliographyEntry[] = [
+  {
+    name: '2D Pixel Perfect by Unity Technologies',
+    url: 'https://docs.unity3d.com/ja/Packages/com.unity.render-pipelines.universal%4014.0/manual/2d-pixelperfect.html',
+  },
+  {
+    name: 'CanvasRenderingContext2D imageSmoothingEnabled by MDN',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/imageSmoothingEnabled',
+  },
+  {
+    name: 'Importer des images by Godot Engine',
+    url: 'https://docs.godotengine.org/fr/4.x/tutorials/assets_pipeline/importing_images.html',
+  },
+  {
+    name: '精灵与渲染 by Estella Engine',
+    url: 'https://estellaengine.com/docs/zh-cn/graphics/sprites/',
+  },
+];

package/src/tool/gamePixelPerUnitPlanner/component.astro

@@ -0,0 +1,56 @@
+---
+import type { GamePixelPerUnitPlannerUI } from './ui';
+import './game-pixel-per-unit-planner.css';
+
+interface Props {
+  ui: GamePixelPerUnitPlannerUI;
+}
+
+const { ui } = Astro.props as Props;
+---
+
+<div class="gppu-tool" data-game-pixel-per-unit-planner>
+  <div class="gppu-layout">
+    <aside class="gppu-controls">
+      <div class="gppu-heading"><span class="gppu-kicker">01</span><h2>{ui.inputsTitle}</h2></div>
+      <div class="gppu-upload" data-upload-zone>
+        <div class="gppu-upload-heading"><strong>{ui.uploadTitle}</strong><span class="gppu-upload-icon" aria-hidden="true">+</span></div>
+        <p>{ui.uploadHint}</p>
+        <label class="gppu-upload-button"><span>{ui.chooseSpriteLabel}</span><input data-sprite-upload type="file" accept="image/png,image/gif,image/webp,image/jpeg" /></label>
+        <span class="gppu-file-name" data-file-name>{ui.defaultSpriteLabel}</span>
+        <button class="gppu-clear-sprite" type="button" data-clear-sprite>{ui.clearSpriteLabel}</button>
+      </div>
+      <div class="gppu-field-grid">
+        <label><span>{ui.displayWidthLabel}</span><input data-field="displayWidth" type="number" min="160" max="7680" step="1" value="320" /></label>
+        <label><span>{ui.displayHeightLabel}</span><input data-field="displayHeight" type="number" min="90" max="4320" step="1" value="180" /></label>
+        <label><span>{ui.spriteWidthLabel}</span><input data-field="spriteWidth" type="number" min="1" max="4096" step="1" value="16" readonly /></label>
+        <label><span>{ui.spriteHeightLabel}</span><input data-field="spriteHeight" type="number" min="1" max="4096" step="1" value="16" readonly /></label>
+        <label><span>{ui.worldWidthLabel}</span><input data-field="worldWidth" type="number" min="0.01" max="1000" step="0.01" value="1" /></label>
+        <label><span>{ui.worldHeightLabel}</span><input data-field="worldHeight" type="number" min="0.01" max="1000" step="0.01" value="1" /></label>
+      </div>
+      <label class="gppu-scale-field"><span>{ui.targetScaleLabel}</span><output data-output="targetScale">4</output><input data-field="targetScale" type="range" min="0.5" max="16" step="0.25" value="4" /></label>
+      <p class="gppu-hint">{ui.targetScaleHint}</p>
+      <div class="gppu-preset-group"><span class="gppu-preset-label">{ui.resolutionPresetsLabel}</span><div class="gppu-chip-row"><button type="button" data-resolution-preset="320x180">{ui.preset320}</button><button type="button" data-resolution-preset="384x216">{ui.preset384}</button><button type="button" data-resolution-preset="640x360">{ui.preset640}</button></div></div>
+      <div class="gppu-preset-group"><span class="gppu-preset-label">{ui.scalePresetsLabel}</span><div class="gppu-chip-row"><button type="button" data-scale-preset="1">{ui.scale1}</button><button type="button" data-scale-preset="2">{ui.scale2}</button><button type="button" data-scale-preset="3">{ui.scale3}</button><button type="button" data-scale-preset="4">{ui.scale4}</button><button type="button" data-scale-preset="6">{ui.scale6}</button></div></div>
+      <button class="gppu-reset" type="button" data-reset>{ui.resetLabel}</button>
+    </aside>
+    <main class="gppu-stage" aria-labelledby="gppu-field-title">
+      <div class="gppu-stage-heading"><div><span class="gppu-kicker">02</span><h2 id="gppu-field-title">{ui.fieldTitle}</h2><p>{ui.fieldCaption}</p></div><span class="gppu-live" data-live aria-live="polite">{ui.statusReady}</span></div>
+      <div class="gppu-field" data-pixel-field></div>
+      <div class="gppu-summary" data-summary></div>
+      <section class="gppu-crisp"><div class="gppu-section-heading"><div><span class="gppu-kicker">03</span><h3>{ui.crispTitle}</h3><p>{ui.crispCaption}</p></div></div><div class="gppu-step-grid" data-scale-steps></div></section>
+      <div class="gppu-table" data-table></div>
+      <p class="gppu-model-note">{ui.modelNote}</p>
+      <p class="gppu-privacy">{ui.privacyDisclosure}</p>
+    </main>
+  </div>
+</div>
+
+<script is:inline type="application/json" data-game-pixel-per-unit-ui set:html={JSON.stringify(ui)}></script>
+
+<script>
+  import { mountGamePixelPerUnitPlanner } from './controller';
+  const root = document.querySelector<HTMLElement>('[data-game-pixel-per-unit-planner]');
+  const uiScript = document.querySelector<HTMLScriptElement>('[data-game-pixel-per-unit-ui]');
+  if (root && uiScript) mountGamePixelPerUnitPlanner(root, JSON.parse(uiScript.textContent ?? '{}'));
+</script>

package/src/tool/gamePixelPerUnitPlanner/controller.ts

@@ -0,0 +1,127 @@
+import { evaluatePixelPlan } from './evaluator';
+import { calculatePixelPlan, DEFAULT_PIXEL_CONFIG, normalizePixelConfig, type PixelPerUnitConfig } from './logic';
+import { renderAccessibleTable, renderPixelField, renderScaleSteps, renderSummary } from './dom-views';
+import { loadPixelConfig, savePixelConfig } from './storage';
+import type { GamePixelPerUnitPlannerUI } from './ui';
+
+const DEFAULT_SPRITE_URL = '/assets/game-pixel-per-unit-planner/default-sprite.png';
+
+const fieldNames: (keyof PixelPerUnitConfig)[] = ['displayWidth', 'displayHeight', 'spriteWidth', 'spriteHeight', 'worldWidth', 'worldHeight', 'targetScale'];
+
+function field(root: HTMLElement, name: keyof PixelPerUnitConfig): HTMLInputElement {
+  return root.querySelector<HTMLInputElement>(`[data-field="${name}"]`) as HTMLInputElement;
+}
+
+function readConfig(root: HTMLElement): PixelPerUnitConfig {
+  const values = Object.fromEntries(fieldNames.map((name) => [name, Number(field(root, name).value)]));
+  return normalizePixelConfig(values);
+}
+
+function syncOutputs(root: HTMLElement): void {
+  fieldNames.forEach((name) => {
+    const output = root.querySelector<HTMLOutputElement>(`[data-output="${name}"]`);
+    if (output) output.value = field(root, name).value;
+  });
+}
+
+function render(root: HTMLElement, ui: GamePixelPerUnitPlannerUI, config: PixelPerUnitConfig, spriteUrl?: string): void {
+  const result = calculatePixelPlan(config);
+  const diagnostic = evaluatePixelPlan(result);
+  const fieldTarget = root.querySelector<HTMLElement>('[data-pixel-field]');
+  const stepsTarget = root.querySelector<HTMLElement>('[data-scale-steps]');
+  const summaryTarget = root.querySelector<HTMLElement>('[data-summary]');
+  const tableTarget = root.querySelector<HTMLElement>('[data-table]');
+  if (fieldTarget) renderPixelField(fieldTarget, result, ui, spriteUrl);
+  if (stepsTarget) renderScaleSteps(stepsTarget, result, ui, spriteUrl);
+  if (summaryTarget) renderSummary(summaryTarget, result, diagnostic, ui);
+  if (tableTarget) renderAccessibleTable(tableTarget, result, ui);
+  root.querySelector<HTMLElement>('[data-live]')!.textContent = ui.statusReady;
+  savePixelConfig(config);
+}
+
+function setConfig(root: HTMLElement, config: PixelPerUnitConfig): void {
+  fieldNames.forEach((name) => { field(root, name).value = String(config[name]); });
+  syncOutputs(root);
+}
+
+function bindPresets(root: HTMLElement, ui: GamePixelPerUnitPlannerUI, state: { spriteUrl?: string }): void {
+  root.querySelectorAll<HTMLButtonElement>('[data-resolution-preset]').forEach((button) => button.addEventListener('click', () => {
+    const [displayWidth, displayHeight] = (button.dataset.resolutionPreset ?? '').split('x').map(Number);
+    const config = { ...readConfig(root), displayWidth, displayHeight };
+    setConfig(root, config);
+    render(root, ui, config, state.spriteUrl);
+  }));
+  root.querySelectorAll<HTMLButtonElement>('[data-scale-preset]').forEach((button) => button.addEventListener('click', () => {
+    const config = { ...readConfig(root), targetScale: Number(button.dataset.scalePreset) };
+    setConfig(root, config);
+    render(root, ui, config, state.spriteUrl);
+  }));
+}
+
+function bindReset(root: HTMLElement, ui: GamePixelPerUnitPlannerUI, state: { spriteUrl?: string }): void {
+  root.querySelector<HTMLButtonElement>('[data-reset]')?.addEventListener('click', () => {
+    if (state.spriteUrl && state.spriteUrl !== DEFAULT_SPRITE_URL) URL.revokeObjectURL(state.spriteUrl);
+    state.spriteUrl = DEFAULT_SPRITE_URL;
+    const fileInput = root.querySelector<HTMLInputElement>('[data-sprite-upload]');
+    if (fileInput) fileInput.value = '';
+    const fileName = root.querySelector<HTMLElement>('[data-file-name]');
+    if (fileName) fileName.textContent = ui.defaultSpriteLabel;
+    const clearButton = root.querySelector<HTMLButtonElement>('[data-clear-sprite]');
+    if (clearButton) clearButton.hidden = false;
+    setConfig(root, DEFAULT_PIXEL_CONFIG);
+    render(root, ui, DEFAULT_PIXEL_CONFIG, state.spriteUrl);
+  });
+}
+
+function bindSpriteUpload(root: HTMLElement, ui: GamePixelPerUnitPlannerUI, state: { spriteUrl?: string }): void {
+  const upload = root.querySelector<HTMLInputElement>('[data-sprite-upload]');
+  upload?.addEventListener('change', () => {
+    const file = upload.files?.[0];
+    if (!file) return;
+    const nextUrl = URL.createObjectURL(file);
+    const image = new Image();
+    image.onload = () => {
+      if (state.spriteUrl && state.spriteUrl !== DEFAULT_SPRITE_URL) URL.revokeObjectURL(state.spriteUrl);
+      state.spriteUrl = nextUrl;
+      const config = normalizePixelConfig({ ...readConfig(root), spriteWidth: image.naturalWidth, spriteHeight: image.naturalHeight });
+      setConfig(root, config);
+      root.querySelector<HTMLElement>('[data-file-name]')!.textContent = `${ui.loadedSpriteLabel}: ${file.name}`;
+      root.querySelector<HTMLButtonElement>('[data-clear-sprite]')!.hidden = false;
+      render(root, ui, config, state.spriteUrl);
+    };
+    image.onerror = () => URL.revokeObjectURL(nextUrl);
+    image.src = nextUrl;
+  });
+}
+
+function bindClearSprite(root: HTMLElement, ui: GamePixelPerUnitPlannerUI, state: { spriteUrl?: string }): void {
+  root.querySelector<HTMLButtonElement>('[data-clear-sprite]')?.addEventListener('click', () => {
+    if (state.spriteUrl && state.spriteUrl !== DEFAULT_SPRITE_URL) URL.revokeObjectURL(state.spriteUrl);
+    state.spriteUrl = undefined;
+    const uploadInput = root.querySelector<HTMLInputElement>('[data-sprite-upload]');
+    if (uploadInput) uploadInput.value = '';
+    root.querySelector<HTMLElement>('[data-file-name]')!.textContent = ui.noSpriteLabel;
+    root.querySelector<HTMLButtonElement>('[data-clear-sprite]')!.hidden = true;
+    render(root, ui, readConfig(root));
+  });
+}
+
+function bindInputs(root: HTMLElement, ui: GamePixelPerUnitPlannerUI, state: { spriteUrl?: string }): void {
+  fieldNames.forEach((name) => field(root, name).addEventListener('input', () => {
+    syncOutputs(root);
+    render(root, ui, readConfig(root), state.spriteUrl);
+  }));
+  bindReset(root, ui, state);
+  bindSpriteUpload(root, ui, state);
+  bindClearSprite(root, ui, state);
+  bindPresets(root, ui, state);
+}
+
+export function mountGamePixelPerUnitPlanner(root: HTMLElement, ui: GamePixelPerUnitPlannerUI): void {
+  const state: { spriteUrl?: string } = { spriteUrl: DEFAULT_SPRITE_URL };
+  root.querySelector<HTMLElement>('[data-file-name]')!.textContent = ui.defaultSpriteLabel;
+  const config = normalizePixelConfig(loadPixelConfig());
+  setConfig(root, config);
+  bindInputs(root, ui, state);
+  render(root, ui, config, state.spriteUrl);
+}

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

@@ -0,0 +1,47 @@
+import type { Diagnostic } from './evaluator';
+import type { CrispScaleStep, PixelPerUnitResult } from './logic';
+import type { GamePixelPerUnitPlannerUI } from './ui';
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character] ?? character);
+}
+
+function number(value: number, digits = 2): string {
+  return value.toLocaleString('en-US', { maximumFractionDigits: digits, minimumFractionDigits: digits });
+}
+
+export function renderPixelField(target: HTMLElement, result: PixelPerUnitResult, ui: GamePixelPerUnitPlannerUI, spriteUrl?: string): void {
+  const image = spriteUrl
+    ? `<div class="gppu-hero-canvas"><img src="${escapeHtml(spriteUrl)}" width="${result.renderedSpriteWidth}" height="${result.renderedSpriteHeight}" alt="${escapeHtml(ui.sourceImageAlt)}" /></div>`
+    : `<div class="gppu-empty-preview"><span aria-hidden="true">+</span><strong>${escapeHtml(ui.previewPlaceholder)}</strong></div>`;
+  target.innerHTML = `<div class="gppu-preview-shell"><div class="gppu-preview-topline"><span>${escapeHtml(ui.viewportLabel)} ${number(result.config.displayWidth, 0)} x ${number(result.config.displayHeight, 0)} ${escapeHtml(ui.unitPixels)}</span><strong>${escapeHtml(ui.previewScaleLabel)} ${number(result.config.targetScale, 2)}x</strong></div>${image}<div class="gppu-preview-meta"><span>${escapeHtml(ui.spriteLabel)} ${number(result.config.spriteWidth, 0)} x ${number(result.config.spriteHeight, 0)} ${escapeHtml(ui.unitPixels)}</span><span>${number(result.renderedSpriteWidth, 0)} x ${number(result.renderedSpriteHeight, 0)} ${escapeHtml(ui.unitPixels)} on screen</span></div></div>`;
+}
+
+function stepCard(step: CrispScaleStep, result: PixelPerUnitResult, ui: GamePixelPerUnitPlannerUI, spriteUrl?: string): string {
+  const status = step.fitsViewport ? ui.yesLabel : ui.noLabel;
+  const recommended = step.scale === result.recommendedScale ? `<span class="gppu-recommended">${escapeHtml(ui.recommendedLabel)}</span>` : '';
+  const preview = spriteUrl ? `<div class="gppu-step-canvas"><img src="${escapeHtml(spriteUrl)}" width="${step.renderedWidth}" height="${step.renderedHeight}" alt="${escapeHtml(ui.sourceImageAlt)} at ${step.scale}x" /></div>` : '';
+  return `<div class="gppu-step ${step.fitsViewport ? 'gppu-step-fit' : 'gppu-step-over'} ${step.scale === Math.round(result.config.targetScale) ? 'gppu-step-current' : ''}">${preview}<div><strong>${step.scale}x</strong>${recommended}</div><span>${number(step.renderedWidth, 0)} x ${number(step.renderedHeight, 0)} ${escapeHtml(ui.unitPixels)}</span><small>${escapeHtml(ui.fitLabel)} ${escapeHtml(status)}</small></div>`;
+}
+
+export function renderScaleSteps(target: HTMLElement, result: PixelPerUnitResult, ui: GamePixelPerUnitPlannerUI, spriteUrl?: string): void {
+  target.innerHTML = result.steps.map((step) => stepCard(step, result, ui, spriteUrl)).join('');
+}
+
+function riskLabel(result: PixelPerUnitResult, ui: GamePixelPerUnitPlannerUI): string {
+  const labels = { low: ui.lowRisk, medium: ui.mediumRisk, high: ui.highRisk };
+  return labels[result.bleedRisk];
+}
+
+function diagnosticMessage(diagnostic: Diagnostic, ui: GamePixelPerUnitPlannerUI): string {
+  return ui[diagnostic.messageKey];
+}
+
+export function renderSummary(target: HTMLElement, result: PixelPerUnitResult, diagnostic: Diagnostic, ui: GamePixelPerUnitPlannerUI): void {
+  target.innerHTML = `<h3 class="gppu-summary-title">${escapeHtml(ui.summaryTitle)}</h3><div class="gppu-summary-grid"><div><span>${escapeHtml(ui.ppuXLabel)}</span><strong>${number(result.ppuX)} ${escapeHtml(ui.unitPixels)} / ${escapeHtml(ui.unitUnits)}</strong></div><div><span>${escapeHtml(ui.ppuYLabel)}</span><strong>${number(result.ppuY)} ${escapeHtml(ui.unitPixels)} / ${escapeHtml(ui.unitUnits)}</strong></div><div><span>${escapeHtml(ui.viewportWorldLabel)}</span><strong>${number(result.viewportWorldWidth)} x ${number(result.viewportWorldHeight)} ${escapeHtml(ui.unitUnits)}</strong></div><div><span>${escapeHtml(ui.fitScaleLabel)}</span><strong>${number(result.fitScale, 2)}x</strong></div><div><span>${escapeHtml(ui.bleedingRiskLabel)}</span><strong class="gppu-risk-${diagnostic.key}">${escapeHtml(riskLabel(result, ui))}</strong></div></div><p class="gppu-diagnostic gppu-diagnostic-${diagnostic.key}"><strong>${escapeHtml(ui.alignmentLabel)}:</strong> ${escapeHtml(diagnosticMessage(diagnostic, ui))}</p>`;
+}
+
+export function renderAccessibleTable(target: HTMLElement, result: PixelPerUnitResult, ui: GamePixelPerUnitPlannerUI): void {
+  const rows = result.steps.map((step) => `<tr><td>${step.scale}x</td><td>${number(step.renderedWidth, 0)} ${escapeHtml(ui.unitPixels)}</td><td>${number(step.renderedHeight, 0)} ${escapeHtml(ui.unitPixels)}</td><td>${escapeHtml(step.fitsViewport ? ui.yesLabel : ui.noLabel)}</td></tr>`).join('');
+  target.innerHTML = `<h3>${escapeHtml(ui.tableTitle)}</h3><table><thead><tr><th>${escapeHtml(ui.tableScale)}</th><th>${escapeHtml(ui.tableWidth)}</th><th>${escapeHtml(ui.tableHeight)}</th><th>${escapeHtml(ui.tableFits)}</th></tr></thead><tbody>${rows}</tbody></table>`;
+}

package/src/tool/gamePixelPerUnitPlanner/entry.ts

@@ -0,0 +1,27 @@
+import type { GamesToolEntry, ToolLocaleContent } from '../../types';
+import type { GamePixelPerUnitPlannerUI } from './ui';
+
+export type { GamePixelPerUnitPlannerUI };
+export type GamePixelPerUnitPlannerLocaleContent = ToolLocaleContent<GamePixelPerUnitPlannerUI>;
+
+export const gamePixelPerUnitPlanner: GamesToolEntry<GamePixelPerUnitPlannerUI> = {
+  id: 'game-pixel-per-unit-planner',
+  icons: { bg: 'mdi:grid', fg: 'mdi:gamepad-variant' },
+  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/gamePixelPerUnitPlanner/evaluator.ts

@@ -0,0 +1,14 @@
+import type { PixelPerUnitResult } from './logic';
+
+export type DiagnosticKey = 'low' | 'medium' | 'high';
+
+export interface Diagnostic {
+  key: DiagnosticKey;
+  messageKey: 'riskLowMessage' | 'riskMediumMessage' | 'riskHighMessage';
+}
+
+export function evaluatePixelPlan(result: PixelPerUnitResult): Diagnostic {
+  if (result.bleedRisk === 'high') return { key: 'high', messageKey: 'riskHighMessage' };
+  if (result.bleedRisk === 'medium') return { key: 'medium', messageKey: 'riskMediumMessage' };
+  return { key: 'low', messageKey: 'riskLowMessage' };
+}