@jjlmoya/utils-games-development 1.61.0 → 1.63.0

package/src/tool/hitboxHurtboxAnimator/controller.ts

@@ -0,0 +1,247 @@
+import type { EditorState } from './editor-state';
+import type { HitboxHurtboxAnimatorUI } from './ui';
+import type { CollisionShape, CollisionType, ShapeGeometry } from './logic';
+import { createProject, parseProject, serializeProject } from './logic';
+import { bindCanvas } from './canvas-interactions';
+import { downloadContactSheet, downloadText, loadLocalImages } from './file-io';
+import { formatCopy, renderEditor, setStatus } from './dom-views';
+import { loadPreferences, savePreferences } from './storage';
+import {
+  copyCurrentToAll,
+  copyPreviousFrame,
+  checkpoint,
+  deleteSelected,
+  duplicateSelected,
+  mirrorSelected,
+  redoProject,
+  replaceSlicing,
+  undoProject,
+  updateSelected,
+} from './project-actions';
+
+const input = (root: HTMLElement, selector: string): HTMLInputElement | null => root.querySelector<HTMLInputElement>(selector);
+
+function readUi(root: HTMLElement): HitboxHurtboxAnimatorUI {
+  const source = root.querySelector<HTMLScriptElement>('[data-role="locale-data"]')?.textContent ?? '{}';
+  return JSON.parse(source) as HitboxHurtboxAnimatorUI;
+}
+
+function createState(root: HTMLElement): EditorState {
+  const preferences = loadPreferences();
+  const project = createProject([]);
+  project.fps = preferences.fps;
+  return { root, ui: readUi(root), project, images: [], currentFrame: 0, selectedId: '', mode: 'draw', collisionType: 'hitbox', geometry: 'rectangle', playing: false, preferences, undoStack: [], redoStack: [] };
+}
+
+function stepFrame(state: EditorState, amount: number): void {
+  const count = state.project.frames.length;
+  if (count === 0) return;
+  state.currentFrame = (state.currentFrame + amount + count) % count;
+  state.selectedId = '';
+  renderEditor(state);
+}
+
+function bindPlayback(state: EditorState): (playing: boolean) => void {
+  let timer = 0;
+  return (playing) => {
+    window.clearInterval(timer);
+    state.playing = playing;
+    if (playing) timer = window.setInterval(() => stepFrame(state, 1), 1000 / state.preferences.fps);
+    renderEditor(state);
+  };
+}
+
+async function loadSprites(state: EditorState, files: File[]): Promise<void> {
+  if (files.length === 0) return;
+  try {
+    const loaded = await loadLocalImages(files);
+    state.images = loaded.elements;
+    state.project = createProject(loaded.references);
+    state.project.fps = state.preferences.fps;
+    state.currentFrame = 0;
+    state.selectedId = '';
+    state.undoStack = [];
+    state.redoStack = [];
+    setStatus(state, formatCopy(state.ui.statusImageLoaded, { count: files.length }));
+    renderEditor(state);
+  } catch {
+    setStatus(state, state.ui.statusError);
+  }
+}
+
+function bindFiles(state: EditorState): void {
+  const spriteInput = input(state.root, '[data-role="sprite-input"]');
+  const projectInput = input(state.root, '[data-role="project-input"]');
+  spriteInput?.addEventListener('change', () => void loadSprites(state, Array.from(spriteInput.files ?? [])));
+  projectInput?.addEventListener('change', () => void importProject(state, projectInput.files?.[0]));
+  const drop = state.root.querySelector<HTMLElement>('[data-role="dropzone"]');
+  drop?.addEventListener('dragover', (event) => event.preventDefault());
+  drop?.addEventListener('drop', (event) => {
+    event.preventDefault();
+    void loadSprites(state, Array.from(event.dataTransfer?.files ?? []));
+  });
+}
+
+async function importProject(state: EditorState, file?: File): Promise<void> {
+  if (!file) return;
+  try {
+    state.project = parseProject(await file.text());
+    state.currentFrame = 0;
+    state.selectedId = '';
+    state.undoStack = [];
+    state.redoStack = [];
+    setStatus(state, state.ui.statusImported);
+    renderEditor(state);
+  } catch {
+    setStatus(state, state.ui.statusError);
+  }
+}
+
+function updatePreference(state: EditorState, target: HTMLInputElement): void {
+  if (target.dataset.preference === 'fps') {
+    state.preferences.fps = Math.max(1, Math.min(30, Number(target.value)));
+    state.project.fps = state.preferences.fps;
+  }
+  if (target.dataset.preference === 'onionPrevious') state.preferences.onionPrevious = target.checked;
+  if (target.dataset.preference === 'onionNext') state.preferences.onionNext = target.checked;
+  savePreferences(state.preferences);
+  renderEditor(state);
+}
+
+function bindPreferences(state: EditorState): void {
+  const fps = input(state.root, '[data-preference="fps"]');
+  const previous = input(state.root, '[data-preference="onionPrevious"]');
+  const next = input(state.root, '[data-preference="onionNext"]');
+  if (fps) fps.value = String(state.preferences.fps);
+  if (previous) previous.checked = state.preferences.onionPrevious;
+  if (next) next.checked = state.preferences.onionNext;
+  state.root.querySelectorAll<HTMLInputElement>('[data-preference]').forEach((item) => item.addEventListener('input', () => updatePreference(state, item)));
+}
+
+function numericUpdate(field: string, value: number): Partial<CollisionShape> {
+  if (field === 'radius') return { width: value * 2, height: value * 2 };
+  if (field === 'x') return { x: value };
+  if (field === 'y') return { y: value };
+  if (field === 'width') return { width: value };
+  if (field === 'height') return { height: value };
+  return {};
+}
+
+function updateField(state: EditorState, target: HTMLInputElement): void {
+  const field = target.dataset.field ?? '';
+  const frame = state.project.frames[state.currentFrame];
+  if (!frame) return;
+  if (field === 'pivotX') {
+    checkpoint(state);
+    frame.pivot.x = Math.max(0, Math.min(frame.width, Number(target.value)));
+  } else if (field === 'pivotY') {
+    checkpoint(state);
+    frame.pivot.y = Math.max(0, Math.min(frame.height, Number(target.value)));
+  }
+  else if (field === 'name') updateSelected(state, { name: target.value });
+  else updateSelected(state, numericUpdate(field, Number(target.value)));
+  setStatus(state, state.ui.statusShapeUpdated);
+  renderEditor(state);
+}
+
+function bindFields(state: EditorState): void {
+  state.root.querySelectorAll<HTMLInputElement>('[data-field]').forEach((field) => field.addEventListener('change', () => updateField(state, field)));
+}
+
+function actionHandlers(state: EditorState, setPlaying: (playing: boolean) => void): Record<string, () => void> {
+  return {
+    previous: () => stepFrame(state, -1),
+    next: () => stepFrame(state, 1),
+    play: () => setPlaying(!state.playing),
+    slice: () => applySlice(state),
+    duplicate: () => runMutation(state, duplicateSelected),
+    mirror: () => runMutation(state, mirrorSelected),
+    delete: () => runMutation(state, deleteSelected),
+    copyPrevious: () => runMutation(state, copyPreviousFrame),
+    copyAll: () => runMutation(state, copyCurrentToAll),
+    undo: () => runMutation(state, undoProject),
+    redo: () => runMutation(state, redoProject),
+    exportJson: () => exportJson(state),
+    importJson: () => input(state.root, '[data-role="project-input"]')?.click(),
+    contactSheet: () => exportSheet(state),
+    reset: () => resetState(state),
+  };
+}
+
+function runMutation(state: EditorState, operation: (value: EditorState) => boolean): void {
+  if (!operation(state)) return;
+  setStatus(state, state.ui.statusShapeUpdated);
+  renderEditor(state);
+}
+
+function applySlice(state: EditorState): void {
+  const rows = Number(input(state.root, '[data-role="rows"]')?.value ?? 1);
+  const columns = Number(input(state.root, '[data-role="columns"]')?.value ?? 1);
+  replaceSlicing(state, rows, columns);
+  renderEditor(state);
+}
+
+function exportJson(state: EditorState): void {
+  downloadText(serializeProject(state.project), 'hitbox-animation.json');
+  setStatus(state, state.ui.statusExported);
+}
+
+function exportSheet(state: EditorState): void {
+  downloadContactSheet(state.project, state.images);
+  setStatus(state, state.ui.statusExported);
+}
+
+function resetState(state: EditorState): void {
+  state.project = createProject(state.project.images, state.project.rows, state.project.columns);
+  state.project.fps = state.preferences.fps;
+  state.currentFrame = 0;
+  state.selectedId = '';
+  state.undoStack = [];
+  state.redoStack = [];
+  setStatus(state, state.ui.statusReady);
+  renderEditor(state);
+}
+
+function bindClicks(state: EditorState, setPlaying: (playing: boolean) => void): void {
+  const actions = actionHandlers(state, setPlaying);
+  state.root.addEventListener('click', (event) => {
+    const target = (event.target as Element).closest<HTMLElement>('[data-action], [data-type], [data-geometry], [data-mode], [data-frame]');
+    if (!target) return;
+    if (target.dataset.type) state.collisionType = target.dataset.type as CollisionType;
+    if (target.dataset.geometry) state.geometry = target.dataset.geometry as ShapeGeometry;
+    if (target.dataset.mode) state.mode = target.dataset.mode as EditorState['mode'];
+    if (target.dataset.frame !== undefined) state.currentFrame = Number(target.dataset.frame);
+    if (target.dataset.action) actions[target.dataset.action]?.();
+    renderEditor(state);
+  });
+}
+
+function bindKeyboard(state: EditorState): void {
+  state.root.addEventListener('keydown', (event) => {
+    if ((event.target as Element).matches('input')) return;
+    const modified = event.ctrlKey || event.metaKey;
+    const key = modified ? `mod-${event.key.toLowerCase()}` : event.key;
+    const handlers: Record<string, () => void> = {
+      ArrowLeft: () => stepFrame(state, -1),
+      ArrowRight: () => stepFrame(state, 1),
+      Delete: () => runMutation(state, deleteSelected),
+      'mod-z': () => runMutation(state, undoProject),
+      'mod-y': () => runMutation(state, redoProject),
+    };
+    handlers[key]?.();
+  });
+}
+
+export function mountHitboxHurtboxAnimator(root: HTMLElement): void {
+  if (root.dataset.ready) return;
+  root.dataset.ready = 'true';
+  const state = createState(root);
+  bindFiles(state);
+  bindPreferences(state);
+  bindFields(state);
+  bindCanvas(state);
+  bindClicks(state, bindPlayback(state));
+  bindKeyboard(state);
+  setStatus(state, state.ui.statusReady);
+  renderEditor(state);
+}

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

@@ -0,0 +1,194 @@
+import type { EditorState } from './editor-state';
+import type { AnimationFrame, CollisionShape, CollisionType } from './logic';
+import { evaluateProject } from './evaluator';
+
+const COLORS: Record<CollisionType, string> = {
+  hitbox: '#ff4d6d',
+  hurtbox: '#2dd4bf',
+  pushbox: '#8b5cf6',
+  grabbox: '#f59e0b',
+  sensor: '#38bdf8',
+  custom: '#f472b6',
+};
+
+const element = <T extends Element>(root: ParentNode, selector: string): T | null => root.querySelector<T>(selector);
+
+export function formatCopy(template: string, values: Record<string, string | number>): string {
+  return Object.entries(values).reduce((copy, [key, value]) => copy.replace(`{${key}}`, String(value)), template);
+}
+
+interface ShapePaint {
+  context: CanvasRenderingContext2D;
+  shape: CollisionShape;
+  scale: number;
+  selected: boolean;
+  alpha?: number | undefined;
+}
+
+function drawShape(input: ShapePaint): void {
+  const { context, shape, scale, selected } = input;
+  const alpha = input.alpha ?? 1;
+  const color = COLORS[shape.type];
+  context.save();
+  context.globalAlpha = alpha;
+  context.fillStyle = `${color}33`;
+  context.strokeStyle = selected ? '#fff' : color;
+  context.lineWidth = selected ? 3 : 2;
+  context.setLineDash(selected ? [] : [5, 3]);
+  const x = shape.x * scale;
+  const y = shape.y * scale;
+  const width = shape.width * scale;
+  const height = shape.height * scale;
+  context.beginPath();
+  if (shape.geometry === 'circle') context.ellipse(x + width / 2, y + height / 2, width / 2, height / 2, 0, 0, Math.PI * 2);
+  else context.rect(x, y, width, height);
+  context.fill();
+  context.stroke();
+  context.restore();
+}
+
+interface FramePaint {
+  context: CanvasRenderingContext2D;
+  frame: AnimationFrame;
+  image?: HTMLImageElement | undefined;
+  scale: number;
+  selectedId?: string;
+  alpha?: number;
+}
+
+export function paintFrame(input: FramePaint): void {
+  const { context, frame, image, scale } = input;
+  if (image) context.drawImage(image, frame.sourceX, frame.sourceY, frame.width, frame.height, 0, 0, frame.width * scale, frame.height * scale);
+  frame.shapes.forEach((shape) => drawShape({ context, shape, scale, selected: shape.id === input.selectedId, alpha: input.alpha }));
+}
+
+function paintOnion(state: EditorState, context: CanvasRenderingContext2D, index: number, scale: number): void {
+  const frame = state.project.frames[index];
+  if (!frame) return;
+  context.save();
+  context.globalAlpha = 0.18;
+  paintFrame({ context, frame, image: state.images[frame.imageIndex], scale, alpha: 0.55 });
+  context.restore();
+}
+
+function canvasScale(frame: AnimationFrame): number {
+  return Math.max(1, Math.min(8, 720 / frame.width, 520 / frame.height));
+}
+
+function renderCanvas(state: EditorState): void {
+  const canvas = element<HTMLCanvasElement>(state.root, '[data-role="stage"]');
+  const frame = state.project.frames[state.currentFrame];
+  if (!canvas || !frame) return;
+  const scale = canvasScale(frame);
+  canvas.width = Math.round(frame.width * scale);
+  canvas.height = Math.round(frame.height * scale);
+  canvas.dataset.scale = String(scale);
+  const context = canvas.getContext('2d');
+  if (!context) return;
+  context.imageSmoothingEnabled = false;
+  context.clearRect(0, 0, canvas.width, canvas.height);
+  if (state.preferences.onionPrevious) paintOnion(state, context, state.currentFrame - 1, scale);
+  if (state.preferences.onionNext) paintOnion(state, context, state.currentFrame + 1, scale);
+  paintFrame({ context, frame, image: state.images[frame.imageIndex], scale, selectedId: state.selectedId });
+  context.fillStyle = '#fff';
+  context.beginPath();
+  context.arc(frame.pivot.x * scale, frame.pivot.y * scale, 3, 0, Math.PI * 2);
+  context.fill();
+}
+
+function typeMarks(frame: AnimationFrame): string {
+  return Array.from(new Set(frame.shapes.map(({ type }) => type))).map((type) => `<i style="--mark:${COLORS[type]}"></i>`).join('');
+}
+
+function renderTimeline(state: EditorState): void {
+  const timeline = element<HTMLElement>(state.root, '[data-role="timeline"]');
+  if (!timeline) return;
+  timeline.innerHTML = state.project.frames.map((frame) => {
+    const active = frame.index === state.currentFrame ? ' is-active' : '';
+    const label = formatCopy(state.ui.frameReadout, { current: frame.index + 1, total: state.project.frames.length });
+    return `<button type="button" class="hha-frame${active}" data-frame="${frame.index}" aria-label="${label}"><span>${frame.index + 1}</span><b>${frame.shapes.length}</b><em>${typeMarks(frame)}</em></button>`;
+  }).join('');
+}
+
+function setField(root: HTMLElement, field: string, value: string | number, disabled: boolean): void {
+  const input = element<HTMLInputElement>(root, `[data-field="${field}"]`);
+  if (!input) return;
+  input.value = String(value);
+  input.disabled = disabled;
+}
+
+function renderShapeFields(state: EditorState, shape?: CollisionShape): void {
+  if (!shape) {
+    ['name', 'x', 'y', 'width', 'height', 'radius'].forEach((field) => setField(state.root, field, field === 'name' ? '' : 0, true));
+    return;
+  }
+  setField(state.root, 'name', shape.name, false);
+  setField(state.root, 'x', shape.x, false);
+  setField(state.root, 'y', shape.y, false);
+  setField(state.root, 'width', shape.width, false);
+  setField(state.root, 'height', shape.height, false);
+  setField(state.root, 'radius', shape.width / 2, false);
+}
+
+function toggleInspector(state: EditorState, shape?: CollisionShape): void {
+  const empty = element<HTMLElement>(state.root, '[data-role="no-selection"]');
+  const fields = element<HTMLElement>(state.root, '[data-role="shape-fields"]');
+  if (empty) empty.hidden = Boolean(shape);
+  if (fields) fields.hidden = !shape;
+  const radius = element<HTMLElement>(state.root, '[data-radius-row]');
+  if (radius) radius.hidden = !shape || shape.geometry !== 'circle';
+}
+
+function renderInspector(state: EditorState): void {
+  const frame = state.project.frames[state.currentFrame];
+  if (!frame) return;
+  const shape = frame.shapes.find(({ id }) => id === state.selectedId);
+  toggleInspector(state, shape);
+  renderShapeFields(state, shape);
+  setField(state.root, 'pivotX', frame.pivot.x, false);
+  setField(state.root, 'pivotY', frame.pivot.y, false);
+}
+
+function renderDiagnostics(state: EditorState): void {
+  const diagnostics = evaluateProject(state.project);
+  const frames = element<HTMLElement>(state.root, '[data-role="frames-badge"]');
+  const shapes = element<HTMLElement>(state.root, '[data-role="shapes-badge"]');
+  const coverage = element<HTMLElement>(state.root, '[data-role="coverage-badge"]');
+  if (frames) frames.textContent = formatCopy(state.ui.framesBadge, { count: diagnostics.frameCount });
+  if (shapes) shapes.textContent = formatCopy(state.ui.shapesBadge, { count: diagnostics.shapeCount });
+  if (coverage) coverage.textContent = formatCopy(state.ui.coverageBadge, { percent: diagnostics.coveragePercent });
+}
+
+function renderControls(state: EditorState): void {
+  state.root.classList.toggle('has-images', state.images.length > 0);
+  state.root.querySelectorAll<HTMLElement>('[data-type]').forEach((item) => item.classList.toggle('is-active', item.dataset.type === state.collisionType));
+  state.root.querySelectorAll<HTMLElement>('[data-geometry]').forEach((item) => item.classList.toggle('is-active', item.dataset.geometry === state.geometry));
+  state.root.querySelectorAll<HTMLElement>('[data-mode]').forEach((item) => item.classList.toggle('is-active', item.dataset.mode === state.mode));
+  const play = element<HTMLElement>(state.root, '[data-action="play"]');
+  if (play) play.textContent = state.playing ? state.ui.pause : state.ui.play;
+}
+
+export function renderEditor(state: EditorState): void {
+  renderCanvas(state);
+  renderTimeline(state);
+  renderInspector(state);
+  renderDiagnostics(state);
+  renderControls(state);
+}
+
+export function renderDraft(state: EditorState, start: { x: number; y: number }, end: { x: number; y: number }): void {
+  renderCanvas(state);
+  const canvas = element<HTMLCanvasElement>(state.root, '[data-role="stage"]');
+  const context = canvas?.getContext('2d');
+  if (!canvas || !context) return;
+  const scale = Number(canvas.dataset.scale ?? 1);
+  const width = state.geometry === 'circle' ? Math.min(Math.abs(end.x - start.x), Math.abs(end.y - start.y)) : Math.abs(end.x - start.x);
+  const height = state.geometry === 'circle' ? width : Math.abs(end.y - start.y);
+  const shape: CollisionShape = { id: '', name: '', type: state.collisionType, geometry: state.geometry, x: Math.min(start.x, end.x), y: Math.min(start.y, end.y), width, height };
+  drawShape({ context, shape, scale, selected: true, alpha: 0.9 });
+}
+
+export function setStatus(state: EditorState, copy: string): void {
+  const status = element<HTMLElement>(state.root, '[data-role="status"]');
+  if (status) status.textContent = copy;
+}

package/src/tool/hitboxHurtboxAnimator/editor-state.ts

@@ -0,0 +1,19 @@
+import type { HitboxHurtboxAnimatorUI } from './ui';
+import type { CollisionProject, CollisionType, ShapeGeometry } from './logic';
+import type { EditorPreferences } from './storage';
+
+export interface EditorState {
+  root: HTMLElement;
+  ui: HitboxHurtboxAnimatorUI;
+  project: CollisionProject;
+  images: HTMLImageElement[];
+  currentFrame: number;
+  selectedId: string;
+  mode: 'select' | 'draw';
+  collisionType: CollisionType;
+  geometry: ShapeGeometry;
+  playing: boolean;
+  preferences: EditorPreferences;
+  undoStack: CollisionProject[];
+  redoStack: CollisionProject[];
+}

package/src/tool/hitboxHurtboxAnimator/entry.ts

@@ -0,0 +1,28 @@
+import type { GamesToolEntry, ToolLocaleContent } from '../../types';
+import type { HitboxHurtboxAnimatorUI } from './ui';
+
+export type { HitboxHurtboxAnimatorUI };
+
+export type HitboxHurtboxAnimatorLocaleContent = ToolLocaleContent<HitboxHurtboxAnimatorUI>;
+
+export const hitboxHurtboxAnimator: GamesToolEntry<HitboxHurtboxAnimatorUI> = {
+  id: 'hitbox-hurtbox-animator',
+  icons: { bg: 'mdi:animation-play-outline', fg: 'mdi:vector-rectangle' },
+  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/hitboxHurtboxAnimator/evaluator.ts

@@ -0,0 +1,15 @@
+import type { CollisionProject } from './logic';
+
+export interface ProjectDiagnostics {
+  frameCount: number;
+  shapeCount: number;
+  coveredFrames: number;
+  coveragePercent: number;
+}
+
+export function evaluateProject(project: CollisionProject): ProjectDiagnostics {
+  const shapeCount = project.frames.reduce((total, frame) => total + frame.shapes.length, 0);
+  const coveredFrames = project.frames.filter((frame) => frame.shapes.length > 0).length;
+  const coveragePercent = project.frames.length === 0 ? 0 : Math.round((coveredFrames / project.frames.length) * 100);
+  return { frameCount: project.frames.length, shapeCount, coveredFrames, coveragePercent };
+}

package/src/tool/hitboxHurtboxAnimator/file-io.ts

@@ -0,0 +1,82 @@
+import type { CollisionProject, ImageReference } from './logic';
+import { paintFrame } from './dom-views';
+
+export interface LoadedImages {
+  elements: HTMLImageElement[];
+  references: ImageReference[];
+}
+
+function decodeImage(file: File): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const image = new Image();
+    const url = URL.createObjectURL(file);
+    image.onload = () => {
+      URL.revokeObjectURL(url);
+      resolve(image);
+    };
+    image.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error(file.name));
+    };
+    image.src = url;
+  });
+}
+
+export async function loadLocalImages(files: File[]): Promise<LoadedImages> {
+  const ordered = [...files].sort((left, right) => left.name.localeCompare(right.name, undefined, { numeric: true }));
+  const elements = await Promise.all(ordered.map(decodeImage));
+  const references = elements.map((image, index) => ({ name: ordered[index]?.name ?? '', width: image.naturalWidth, height: image.naturalHeight }));
+  return { elements, references };
+}
+
+export function downloadText(source: string, fileName: string): void {
+  const blob = new Blob([source], { type: 'application/json' });
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = fileName;
+  anchor.click();
+  URL.revokeObjectURL(url);
+}
+
+function sheetMetrics(project: CollisionProject): { columns: number; rows: number; width: number; height: number } {
+  const columns = Math.max(1, Math.ceil(Math.sqrt(project.frames.length)));
+  const rows = Math.max(1, Math.ceil(project.frames.length / columns));
+  const width = Math.max(1, ...project.frames.map((frame) => frame.width));
+  const height = Math.max(1, ...project.frames.map((frame) => frame.height));
+  return { columns, rows, width, height };
+}
+
+function drawSheet(project: CollisionProject, images: HTMLImageElement[]): HTMLCanvasElement {
+  const metrics = sheetMetrics(project);
+  const padding = 18;
+  const canvas = document.createElement('canvas');
+  canvas.width = metrics.columns * (metrics.width + padding) + padding;
+  canvas.height = metrics.rows * (metrics.height + padding) + padding;
+  const context = canvas.getContext('2d');
+  if (!context) return canvas;
+  context.fillStyle = '#15111f';
+  context.fillRect(0, 0, canvas.width, canvas.height);
+  project.frames.forEach((frame, index) => {
+    const column = index % metrics.columns;
+    const row = Math.floor(index / metrics.columns);
+    context.save();
+    context.translate(padding + column * (metrics.width + padding), padding + row * (metrics.height + padding));
+    paintFrame({ context, frame, image: images[frame.imageIndex], scale: 1 });
+    context.restore();
+  });
+  return canvas;
+}
+
+export function downloadContactSheet(project: CollisionProject, images: HTMLImageElement[]): void {
+  const canvas = drawSheet(project, images);
+  canvas.toBlob((blob) => {
+    if (!blob) return;
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = 'collision-contact-sheet.png';
+    anchor.click();
+    URL.revokeObjectURL(url);
+  }, 'image/png');
+}