@jjlmoya/utils-games-development 1.69.0 → 1.71.0

package/src/tool/fixerEditor/i18n/ru.ts

@@ -0,0 +1,82 @@
+import { createLocalizedContent } from "./localized";
+
+export const content = createLocalizedContent({
+  locale: "ru",
+  slug: "redaktor-ispravleniya-sprite-sheet",
+  title: "Редактор исправления Sprite Sheet",
+  description:
+    "Исправляйте обрезку и выравнивание пикселей спрайт-листа в браузере, затем экспортируйте лист и метаданные кадров.",
+  ui: {
+    uploadTitle: "Открыть спрайт-лист",
+    uploadHint:
+      "Перетащите PNG или WebP, чтобы разместить кадры на рабочем поле",
+    chooseImage: "Выбрать изображение",
+    sourceFile: "Исходный файл",
+    noImage: "Спрайт-лист не загружен",
+    gridSettings: "Настройка сетки",
+    columns: "Столбцы",
+    rows: "Строки",
+    cellWidth: "Ширина ячейки",
+    cellHeight: "Высота ячейки",
+    marginX: "Левое поле",
+    marginY: "Верхнее поле",
+    gapX: "Интервал столбцов",
+    gapY: "Интервал строк",
+    frameTools: "Настройки кадра",
+    cropX: "Обрезка слева",
+    cropY: "Обрезка сверху",
+    cropWidth: "Ширина обрезки",
+    cropHeight: "Высота обрезки",
+    offsetX: "Смещение X",
+    offsetY: "Смещение Y",
+    trimTransparent: "Обрезать прозрачные пиксели",
+    trimAll: "Автообрезка всех кадров",
+    autoDetectGrid: "Определить сетку автоматически",
+    resetFrame: "Сбросить выбранный кадр",
+    nudgeStep: "Шаг перемещения",
+    stepOne: "Один пиксель",
+    stepTwo: "Два пикселя",
+    stepFour: "Четыре пикселя",
+    history: "Журнал исправлений",
+    undo: "Отменить",
+    redo: "Повторить",
+    resetAll: "Сбросить лист",
+    saveProject: "Сохранить проект",
+    loadProject: "Загрузить проект",
+    exportSheet: "Экспортировать исправленный лист",
+    exportJson: "Экспортировать JSON кадров",
+    sheetView: "Вид регистрации",
+    correctedView: "Исправленный лист",
+    activeFrame: "Инспектор кадра",
+    frameStrip: "Кадры",
+    flipbook: "Флипбук",
+    play: "Воспроизвести",
+    pause: "Пауза",
+    fps: "FPS",
+    zoom: "Масштаб предпросмотра",
+    ready: "Изменения видны сразу",
+    loaded: "Спрайт-лист загружен",
+    modified: "Изменён",
+    unchanged: "Исходная позиция",
+    frameCount: "Кадры",
+    correctionCount: "Исправленные кадры",
+    imageSize: "Размер изображения",
+    statusEmpty: "Ожидание спрайт-листа",
+    statusSaved: "Проект сохранён локально",
+    statusLoaded: "Проект загружен",
+    statusExported: "Экспорт готов",
+    statusInvalidImage: "Не удалось открыть это изображение",
+    statusInvalidProject: "Файл проекта недействителен",
+    statusProjectNeedsImage:
+      "Проект сохранён. Откройте исходное изображение для применения",
+    statusImageMismatch: "Проект загружен с другим размером источника",
+    metadataNote: "Прозрачные пиксели остаются прозрачными при экспорте",
+    sourceLabel: "Исходный лист",
+    resultLabel: "Исправленный лист",
+    selectFrame: "Выбрать кадр",
+    moveUp: "Переместить кадр вверх",
+    moveDown: "Переместить кадр вниз",
+    moveLeft: "Переместить кадр влево",
+    moveRight: "Переместить кадр вправо",
+  },
+});

package/src/tool/fixerEditor/i18n/sv.ts

@@ -0,0 +1,82 @@
+import { createLocalizedContent } from "./localized";
+
+export const content = createLocalizedContent({
+  locale: "sv",
+  slug: "sprite-sheet-korrigering-editor",
+  title: "Redigerare för Sprite Sheet korrigering",
+  description:
+    "Justera beskärning och pixeljustering i ett sprite sheet direkt i webbläsaren och exportera sedan resultatet och bildrutedata.",
+  ui: {
+    uploadTitle: "Öppna ett sprite sheet",
+    uploadHint:
+      "Släpp en PNG eller WebP för att placera bildrutor på arbetsytan",
+    chooseImage: "Välj bild",
+    sourceFile: "Källfil",
+    noImage: "Inget sprite sheet har lästs in",
+    gridSettings: "Registrera rutnät",
+    columns: "Kolumner",
+    rows: "Rader",
+    cellWidth: "Cellbredd",
+    cellHeight: "Cellhöjd",
+    marginX: "Vänstermarginal",
+    marginY: "Övre marginal",
+    gapX: "Kolumnavstånd",
+    gapY: "Radavstånd",
+    frameTools: "Kontroller för bildrutor",
+    cropX: "Beskär vänster",
+    cropY: "Beskär övre",
+    cropWidth: "Beskärningsbredd",
+    cropHeight: "Beskärningshöjd",
+    offsetX: "Förskjutning X",
+    offsetY: "Förskjutning Y",
+    trimTransparent: "Beskär transparenta pixlar",
+    trimAll: "Beskär alla bildrutor automatiskt",
+    autoDetectGrid: "Identifiera rutnät automatiskt",
+    resetFrame: "Återställ vald bildruta",
+    nudgeStep: "Förflyttningssteg",
+    stepOne: "En pixel",
+    stepTwo: "Två pixlar",
+    stepFour: "Fyra pixlar",
+    history: "Korrigeringslogg",
+    undo: "Ångra",
+    redo: "Gör om",
+    resetAll: "Återställ sheet",
+    saveProject: "Spara projekt",
+    loadProject: "Läs in projekt",
+    exportSheet: "Exportera korrigerat sheet",
+    exportJson: "Exportera bildrute-JSON",
+    sheetView: "Registreringsvy",
+    correctedView: "Korrigerat sheet",
+    activeFrame: "Bildruteinspektör",
+    frameStrip: "Bildrutor",
+    flipbook: "Blädderbok",
+    play: "Spela",
+    pause: "Pausa",
+    fps: "FPS",
+    zoom: "Förhandsgranskningszoom",
+    ready: "Ändringar syns direkt",
+    loaded: "Sprite sheet inläst",
+    modified: "Justerad",
+    unchanged: "Ursprunglig position",
+    frameCount: "Bildrutor",
+    correctionCount: "Justerade bildrutor",
+    imageSize: "Bildstorlek",
+    statusEmpty: "Väntar på ett sprite sheet",
+    statusSaved: "Projektet sparades lokalt",
+    statusLoaded: "Projektet lästes in",
+    statusExported: "Export klar",
+    statusInvalidImage: "Bilden kunde inte öppnas",
+    statusInvalidProject: "Projektfilen är ogiltig",
+    statusProjectNeedsImage:
+      "Projektet är sparat. Öppna källbilden för att använda det",
+    statusImageMismatch: "Projektet har en annan källstorlek",
+    metadataNote: "Transparenta pixlar förblir transparenta vid export",
+    sourceLabel: "Käll-sheet",
+    resultLabel: "Korrigerat sheet",
+    selectFrame: "Välj bildruta",
+    moveUp: "Flytta bildruta upp",
+    moveDown: "Flytta bildruta ned",
+    moveLeft: "Flytta bildruta åt vänster",
+    moveRight: "Flytta bildruta åt höger",
+  },
+});

package/src/tool/fixerEditor/i18n/tr.ts

@@ -0,0 +1,82 @@
+import { createLocalizedContent } from "./localized";
+
+export const content = createLocalizedContent({
+  locale: "tr",
+  slug: "sprite-sheet-duzeltici-editor",
+  title: "Sprite Sheet Düzeltme Editörü",
+  description:
+    "Sprite sheet kırpma ve piksel hizalamasını tarayıcıda düzeltin, ardından düzeltilmiş görseli ve kare metadatasını dışa aktarın.",
+  ui: {
+    uploadTitle: "Sprite sheet aç",
+    uploadHint:
+      "Kareleri düzeltme çalışma alanına yerleştirmek için PNG veya WebP bırakın",
+    chooseImage: "Görsel seç",
+    sourceFile: "Kaynak dosya",
+    noImage: "Sprite sheet yüklenmedi",
+    gridSettings: "Izgara kaydı",
+    columns: "Sütunlar",
+    rows: "Satırlar",
+    cellWidth: "Hücre genişliği",
+    cellHeight: "Hücre yüksekliği",
+    marginX: "Sol kenar boşluğu",
+    marginY: "Üst kenar boşluğu",
+    gapX: "Sütun aralığı",
+    gapY: "Satır aralığı",
+    frameTools: "Kare ayarlama araçları",
+    cropX: "Soldan kırp",
+    cropY: "Üstten kırp",
+    cropWidth: "Kırpma genişliği",
+    cropHeight: "Kırpma yüksekliği",
+    offsetX: "X ofseti",
+    offsetY: "Y ofseti",
+    trimTransparent: "Saydam pikselleri kırp",
+    trimAll: "Tüm kareleri otomatik kırp",
+    autoDetectGrid: "Izgarayı otomatik algıla",
+    resetFrame: "Seçili kareyi sıfırla",
+    nudgeStep: "Kaydırma adımı",
+    stepOne: "Bir piksel",
+    stepTwo: "İki piksel",
+    stepFour: "Dört piksel",
+    history: "Düzeltme günlüğü",
+    undo: "Geri al",
+    redo: "Yinele",
+    resetAll: "Sheeti sıfırla",
+    saveProject: "Projeyi kaydet",
+    loadProject: "Projeyi yükle",
+    exportSheet: "Düzeltilmiş sheeti dışa aktar",
+    exportJson: "Kare JSONunu dışa aktar",
+    sheetView: "Kayıt görünümü",
+    correctedView: "Düzeltilmiş sheet",
+    activeFrame: "Kare denetçisi",
+    frameStrip: "Kareler",
+    flipbook: "Flipbook",
+    play: "Oynat",
+    pause: "Duraklat",
+    fps: "FPS",
+    zoom: "Önizleme yakınlaştırması",
+    ready: "Ayarlar anında görünür",
+    loaded: "Sprite sheet yüklendi",
+    modified: "Düzenlendi",
+    unchanged: "Orijinal konum",
+    frameCount: "Kare",
+    correctionCount: "Düzeltilen kare",
+    imageSize: "Görsel boyutu",
+    statusEmpty: "Sprite sheet bekleniyor",
+    statusSaved: "Proje yerel olarak kaydedildi",
+    statusLoaded: "Proje yüklendi",
+    statusExported: "Dışa aktarmaya hazır",
+    statusInvalidImage: "Bu görsel açılamadı",
+    statusInvalidProject: "Proje dosyası geçersiz",
+    statusProjectNeedsImage:
+      "Proje hatırlandı. Uygulamak için kaynak görseli açın",
+    statusImageMismatch: "Proje farklı kaynak boyutuyla yüklendi",
+    metadataNote: "Saydam pikseller dışa aktarımda da saydam kalır",
+    sourceLabel: "Kaynak sheet",
+    resultLabel: "Düzeltilmiş sheet",
+    selectFrame: "Kare seç",
+    moveUp: "Kareyi yukarı taşı",
+    moveDown: "Kareyi aşağı taşı",
+    moveLeft: "Kareyi sola taşı",
+    moveRight: "Kareyi sağa taşı",
+  },
+});

package/src/tool/fixerEditor/i18n/zh.ts

@@ -0,0 +1,80 @@
+import { createLocalizedContent } from "./localized";
+
+export const content = createLocalizedContent({
+  locale: "zh",
+  slug: "fixer-editor",
+  title: "Sprite Sheet 修正编辑器",
+  description:
+    "直接在浏览器中修正精灵图的裁剪和像素对齐，然后导出修正后的图像与帧元数据。",
+  ui: {
+    uploadTitle: "打开精灵图",
+    uploadHint: "拖入 PNG 或 WebP，将帧放到修正工作台",
+    chooseImage: "选择图像",
+    sourceFile: "源文件",
+    noImage: "尚未加载精灵图",
+    gridSettings: "网格注册",
+    columns: "列",
+    rows: "行",
+    cellWidth: "单元格宽度",
+    cellHeight: "单元格高度",
+    marginX: "左边距",
+    marginY: "上边距",
+    gapX: "列间距",
+    gapY: "行间距",
+    frameTools: "帧调整工具",
+    cropX: "左侧裁剪",
+    cropY: "顶部裁剪",
+    cropWidth: "裁剪宽度",
+    cropHeight: "裁剪高度",
+    offsetX: "X 偏移",
+    offsetY: "Y 偏移",
+    trimTransparent: "裁剪透明像素",
+    trimAll: "自动裁剪所有帧",
+    autoDetectGrid: "自动检测网格",
+    resetFrame: "重置选中帧",
+    nudgeStep: "移动步长",
+    stepOne: "一个像素",
+    stepTwo: "两个像素",
+    stepFour: "四个像素",
+    history: "修正记录",
+    undo: "撤销",
+    redo: "重做",
+    resetAll: "重置精灵图",
+    saveProject: "保存项目",
+    loadProject: "加载项目",
+    exportSheet: "导出修正后的精灵图",
+    exportJson: "导出帧 JSON",
+    sheetView: "注册视图",
+    correctedView: "修正后的精灵图",
+    activeFrame: "帧检查器",
+    frameStrip: "帧列表",
+    flipbook: "翻页预览",
+    play: "播放",
+    pause: "暂停",
+    fps: "FPS",
+    zoom: "预览缩放",
+    ready: "调整会立即显示",
+    loaded: "精灵图已加载",
+    modified: "已调整",
+    unchanged: "原始位置",
+    frameCount: "帧",
+    correctionCount: "已调整帧",
+    imageSize: "图像尺寸",
+    statusEmpty: "等待精灵图",
+    statusSaved: "项目已保存到本地",
+    statusLoaded: "项目已加载",
+    statusExported: "可以导出",
+    statusInvalidImage: "无法打开此图像",
+    statusInvalidProject: "项目文件无效",
+    statusProjectNeedsImage: "已记住项目。请打开源图像以应用它",
+    statusImageMismatch: "项目加载时使用了不同的源尺寸",
+    metadataNote: "透明像素在导出时仍保持透明",
+    sourceLabel: "源精灵图",
+    resultLabel: "修正后的精灵图",
+    selectFrame: "选择帧",
+    moveUp: "向上移动帧",
+    moveDown: "向下移动帧",
+    moveLeft: "向左移动帧",
+    moveRight: "向右移动帧",
+  },
+});

package/src/tool/fixerEditor/index.ts

@@ -0,0 +1,11 @@
+import type { ToolDefinition } from '../../types';
+import { fixerEditor } from './entry';
+
+export * from './entry';
+
+export const FIXER_EDITOR_TOOL: ToolDefinition = {
+  entry: fixerEditor,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

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

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { createDefaultAdjustment, createFrameMetadata, createFrameSpecs, createHistoryState, createProjectFile, DEFAULT_GRID, detectGridFromImageData, isModified, nudgeAdjustment, normalizeAdjustment, normalizeGrid, parseProjectFile, recalculateGrid, trimTransparent, updateAdjustment } from './logic';
+
+const frame = createFrameSpecs(128, 64, DEFAULT_GRID)[0];
+
+if (!frame) throw new Error('Expected a test frame');
+
+describe('fixer editor logic', () => {
+  it('normalizes grid values and creates registered frames', () => {
+    expect(normalizeGrid({ ...DEFAULT_GRID, columns: 0, rows: 200, cellWidth: 2.6 })).toEqual({ ...DEFAULT_GRID, columns: 1, rows: 128, cellWidth: 3 });
+    expect(createFrameSpecs(128, 64, DEFAULT_GRID)).toHaveLength(2);
+  });
+
+  it('recalculates columns and rows from the source dimensions', () => {
+    expect(recalculateGrid({ ...DEFAULT_GRID, cellWidth: 32 }, 128, 64, 'columns').columns).toBe(4);
+    expect(recalculateGrid({ ...DEFAULT_GRID, cellHeight: 16 }, 128, 64, 'rows').rows).toBe(4);
+    expect(recalculateGrid({ ...DEFAULT_GRID, cellWidth: 30, gapX: 2 }, 128, 64, 'columns').columns).toBe(4);
+  });
+
+  it('detects a transparent four by two sheet', () => {
+    const width = 128;
+    const height = 64;
+    const pixels = new Uint8ClampedArray(width * height * 4);
+    for (let y = 4; y < 28; y += 1) {
+      for (let x = 4; x < 28; x += 1) pixels[(y * width + x) * 4 + 3] = 255;
+    }
+    for (let y = 36; y < 60; y += 1) {
+      for (let x = 68; x < 92; x += 1) pixels[(y * width + x) * 4 + 3] = 255;
+    }
+    expect(detectGridFromImageData(pixels, width, height)).toMatchObject({ columns: 4, rows: 2 });
+  });
+
+  it('clamps a crop and offset to the frame canvas', () => {
+    expect(normalizeAdjustment({ crop: { x: -4, y: 80, width: 90, height: 0 }, offsetX: 90, offsetY: -90 }, frame)).toEqual({ crop: { x: 0, y: 63, width: 64, height: 1 }, offsetX: 64, offsetY: -64 });
+    expect(updateAdjustment(frame, createDefaultAdjustment(64, 64), { crop: { x: 4, width: 20 }, offsetY: 3 })).toEqual({ crop: { x: 4, y: 0, width: 20, height: 64 }, offsetX: 0, offsetY: 3 });
+  });
+
+  it('nudges and detects adjusted frames', () => {
+    const original = createDefaultAdjustment(64, 64);
+    const moved = nudgeAdjustment(frame, original, 'x', 2);
+    expect(moved.offsetX).toBe(2);
+    expect(isModified(moved, frame)).toBe(true);
+    expect(isModified(original, frame)).toBe(false);
+  });
+
+  it('finds visible pixels while preserving an empty frame', () => {
+    const pixels = new Uint8ClampedArray(4 * 4 * 4);
+    pixels[(1 * 4 + 2) * 4 + 3] = 255;
+    expect(trimTransparent(pixels, 4, 4)).toEqual({ x: 2, y: 1, width: 1, height: 1 });
+    expect(trimTransparent(new Uint8ClampedArray(4 * 4 * 4), 4, 4)).toEqual({ x: 0, y: 0, width: 4, height: 4 });
+  });
+
+  it('serializes valid projects and rejects malformed files', () => {
+    const project = createProjectFile({ sourceName: 'hero.png', sourceWidth: 128, sourceHeight: 64, grid: DEFAULT_GRID, adjustments: { '0': createDefaultAdjustment(64, 64) } });
+    expect(parseProjectFile(project)).toEqual(project);
+    expect(parseProjectFile(null)).toBeNull();
+    expect(parseProjectFile({ version: 2 })).toBeNull();
+    expect(parseProjectFile({ version: 1, grid: DEFAULT_GRID, adjustments: null })).toBeNull();
+    expect(createHistoryState(DEFAULT_GRID, {}, 0).selected).toBe(0);
+  });
+
+  it('creates neutral metadata for export', () => {
+    const frames = createFrameSpecs(128, 64, DEFAULT_GRID);
+    const first = frames[0];
+    if (!first) throw new Error('Expected a metadata frame');
+    const metadata = createFrameMetadata(frames, { '0': nudgeAdjustment(first, createDefaultAdjustment(64, 64), 'y', 1) });
+    expect(metadata[0]).toMatchObject({ index: 0, x: 0, y: 0, modified: true, offset: { x: 0, y: 1 } });
+  });
+});

package/src/tool/fixerEditor/logic.ts

@@ -0,0 +1,234 @@
+import type { CropRect, FrameAdjustment, FrameMetadata, FrameSpec, GridSettings, HistoryState, ProjectFile } from './types';
+
+export const DEFAULT_GRID: GridSettings = {
+  columns: 4,
+  rows: 2,
+  cellWidth: 64,
+  cellHeight: 64,
+  marginX: 0,
+  marginY: 0,
+  gapX: 0,
+  gapY: 0,
+};
+
+const MIN_VALUE = 1;
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+export function normalizeGrid(grid: GridSettings): GridSettings {
+  return {
+    columns: clampInteger(grid.columns, 1, 128),
+    rows: clampInteger(grid.rows, 1, 128),
+    cellWidth: clampInteger(grid.cellWidth, MIN_VALUE, 4096),
+    cellHeight: clampInteger(grid.cellHeight, MIN_VALUE, 4096),
+    marginX: clampInteger(grid.marginX, 0, 4096),
+    marginY: clampInteger(grid.marginY, 0, 4096),
+    gapX: clampInteger(grid.gapX, 0, 4096),
+    gapY: clampInteger(grid.gapY, 0, 4096),
+  };
+}
+
+export function recalculateGrid(grid: GridSettings, imageWidth: number, imageHeight: number, axis: 'columns' | 'rows'): GridSettings {
+  const safeGrid = normalizeGrid(grid);
+  if (axis === 'columns') {
+    const availableWidth = Math.max(0, imageWidth - safeGrid.marginX);
+    const columns = Math.max(1, Math.floor((availableWidth + safeGrid.gapX) / (safeGrid.cellWidth + safeGrid.gapX)));
+    return normalizeGrid({ ...safeGrid, columns });
+  }
+  const availableHeight = Math.max(0, imageHeight - safeGrid.marginY);
+  const rows = Math.max(1, Math.floor((availableHeight + safeGrid.gapY) / (safeGrid.cellHeight + safeGrid.gapY)));
+  return normalizeGrid({ ...safeGrid, rows });
+}
+
+export function detectGridFromImageData(data: Uint8ClampedArray, width: number, height: number): GridSettings {
+  const columns = buildProjection(data, width, height, 'x');
+  const rows = buildProjection(data, width, height, 'y');
+  const marginX = findLeadingBlank(columns);
+  const marginY = findLeadingBlank(rows);
+  return normalizeGrid({ columns: detectAxis(columns, DEFAULT_GRID.columns), rows: detectAxis(rows, DEFAULT_GRID.rows), cellWidth: Math.max(1, Math.floor((width - marginX) / detectAxis(columns, DEFAULT_GRID.columns))), cellHeight: Math.max(1, Math.floor((height - marginY) / detectAxis(rows, DEFAULT_GRID.rows))), marginX, marginY, gapX: 0, gapY: 0 });
+}
+
+function buildProjection(data: Uint8ClampedArray, width: number, height: number, axis: 'x' | 'y'): number[] {
+  const isColumn = axis === 'x';
+  const length = isColumn ? width : height;
+  const projection = Array.from({ length }, () => 0);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      if ((data[(y * width + x) * 4 + 3] ?? 0) <= 8) continue;
+      const targetIndex = isColumn ? x : y;
+      projection[targetIndex] = (projection[targetIndex] ?? 0) + 1;
+    }
+  }
+  return projection;
+}
+
+function findLeadingBlank(projection: number[]): number {
+  const firstInk = projection.findIndex((value) => value > 0);
+  return firstInk < 0 ? 0 : firstInk;
+}
+
+function detectAxis(projection: number[], fallback: number): number {
+  const maxParts = Math.min(32, Math.max(1, Math.floor(projection.length / 8)));
+  let bestScore = Number.POSITIVE_INFINITY;
+  let bestParts = 1;
+  for (let parts = 2; parts <= maxParts; parts += 1) {
+    const score = boundaryScore(projection, parts);
+    if (score < bestScore) {
+      bestScore = score;
+      bestParts = parts;
+    } else if (score <= bestScore + 0.03) {
+      bestParts = Math.max(bestParts, parts);
+    }
+  }
+  return bestScore < 0.98 ? bestParts : Math.min(fallback, maxParts);
+}
+
+function boundaryScore(projection: number[], parts: number): number {
+  const totalInk = projection.reduce((sum, value) => sum + value, 0);
+  if (totalInk === 0) return 1;
+  const cellWidth = projection.length / parts;
+  const boundaryInk = Array.from({ length: parts - 1 }, (_, index) => Math.round((index + 1) * cellWidth)).reduce((sum, boundary) => sum + getBoundaryInk(projection, boundary), 0);
+  return boundaryInk / (totalInk * 0.02 + 1);
+}
+
+function getBoundaryInk(projection: number[], boundary: number): number {
+  return [-2, -1, 0, 1, 2].reduce((sum, offset) => sum + (projection[boundary + offset] ?? 0), 0);
+}
+
+function clampInteger(value: number, min: number, max: number): number {
+  return clamp(Math.round(Number.isFinite(value) ? value : min), min, max);
+}
+
+export function createDefaultAdjustment(width: number, height: number): FrameAdjustment {
+  return { crop: { x: 0, y: 0, width, height }, offsetX: 0, offsetY: 0 };
+}
+
+export function createFrameSpecs(imageWidth: number, imageHeight: number, grid: GridSettings): FrameSpec[] {
+  const safeGrid = normalizeGrid(grid);
+  const frames: FrameSpec[] = [];
+  for (let row = 0; row < safeGrid.rows; row += 1) {
+    for (let column = 0; column < safeGrid.columns; column += 1) {
+      const index = row * safeGrid.columns + column;
+      const sourceX = safeGrid.marginX + column * (safeGrid.cellWidth + safeGrid.gapX);
+      const sourceY = safeGrid.marginY + row * (safeGrid.cellHeight + safeGrid.gapY);
+      frames.push({ index, row, column, sourceX, sourceY, width: safeGrid.cellWidth, height: safeGrid.cellHeight, adjustment: createDefaultAdjustment(safeGrid.cellWidth, safeGrid.cellHeight) });
+    }
+  }
+  return frames.filter((frame) => frame.sourceX < imageWidth && frame.sourceY < imageHeight);
+}
+
+export function normalizeAdjustment(adjustment: FrameAdjustment, frame: FrameSpec): FrameAdjustment {
+  const width = clampInteger(adjustment.crop.width, 1, frame.width);
+  const height = clampInteger(adjustment.crop.height, 1, frame.height);
+  const x = clampInteger(adjustment.crop.x, 0, frame.width - width);
+  const y = clampInteger(adjustment.crop.y, 0, frame.height - height);
+  const offsetX = clampInteger(adjustment.offsetX, -frame.width, frame.width);
+  const offsetY = clampInteger(adjustment.offsetY, -frame.height, frame.height);
+  return { crop: { x, y, width, height }, offsetX, offsetY };
+}
+
+export function updateAdjustment(frame: FrameSpec, current: FrameAdjustment, patch: { crop?: Partial<CropRect>; offsetX?: number; offsetY?: number }): FrameAdjustment {
+  const nextCrop = { ...current.crop, ...patch.crop };
+  return normalizeAdjustment({ crop: nextCrop, offsetX: patch.offsetX ?? current.offsetX, offsetY: patch.offsetY ?? current.offsetY }, frame);
+}
+
+export function nudgeAdjustment(frame: FrameSpec, current: FrameAdjustment, axis: 'x' | 'y', delta: number): FrameAdjustment {
+  const patch = axis === 'x' ? { offsetX: current.offsetX + delta } : { offsetY: current.offsetY + delta };
+  return updateAdjustment(frame, current, patch);
+}
+
+export function isModified(adjustment: FrameAdjustment, frame: FrameSpec): boolean {
+  const offsets = [adjustment.crop.x, adjustment.crop.y, adjustment.offsetX, adjustment.offsetY];
+  return offsets.some((value) => value !== 0) || adjustment.crop.width !== frame.width || adjustment.crop.height !== frame.height;
+}
+
+export function countModified(frames: FrameSpec[], adjustments: Record<string, FrameAdjustment>): number {
+  return frames.reduce((total, frame) => total + (isModified(adjustments[String(frame.index)] ?? frame.adjustment, frame) ? 1 : 0), 0);
+}
+
+export function trimTransparent(data: Uint8ClampedArray, width: number, height: number): CropRect {
+  let minX = width;
+  let minY = height;
+  let maxX = -1;
+  let maxY = -1;
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      if ((data[(y * width + x) * 4 + 3] ?? 0) > 0) {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+      }
+    }
+  }
+  if (maxX < 0) return { x: 0, y: 0, width, height };
+  return { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+}
+
+export function createHistoryState(grid: GridSettings, adjustments: Record<string, FrameAdjustment>, selected: number): HistoryState {
+  return { grid: normalizeGrid(grid), adjustments: cloneAdjustments(adjustments), selected };
+}
+
+export function cloneAdjustments(adjustments: Record<string, FrameAdjustment>): Record<string, FrameAdjustment> {
+  return JSON.parse(JSON.stringify(adjustments)) as Record<string, FrameAdjustment>;
+}
+
+export function createProjectFile(input: { sourceName: string; sourceWidth: number; sourceHeight: number; grid: GridSettings; adjustments: Record<string, FrameAdjustment> }): ProjectFile {
+  return { version: 1, sourceName: input.sourceName, sourceWidth: input.sourceWidth, sourceHeight: input.sourceHeight, grid: normalizeGrid(input.grid), adjustments: cloneAdjustments(input.adjustments) };
+}
+
+export function parseProjectFile(value: unknown): ProjectFile | null {
+  if (!value || typeof value !== 'object') return null;
+  const candidate = value as Partial<ProjectFile>;
+  if (!hasProjectHeader(candidate)) return null;
+  if (!hasProjectSourceSize(candidate)) return null;
+  if (!isGridSettings(candidate.grid) || !isAdjustmentMap(candidate.adjustments)) return null;
+  return createProjectFile({ sourceName: typeof candidate.sourceName === 'string' ? candidate.sourceName : '', sourceWidth: candidate.sourceWidth, sourceHeight: candidate.sourceHeight, grid: candidate.grid, adjustments: candidate.adjustments });
+}
+
+function hasProjectHeader(value: Partial<ProjectFile>): boolean {
+  return value.version === 1 && Boolean(value.grid) && Boolean(value.adjustments) && typeof value.adjustments === 'object';
+}
+
+function hasProjectSourceSize(value: Partial<ProjectFile>): value is ProjectFile {
+  return isFinitePositiveInteger(value.sourceWidth) && isFinitePositiveInteger(value.sourceHeight);
+}
+
+function isFinitePositiveInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0;
+}
+
+function isGridSettings(value: unknown): value is GridSettings {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Record<string, unknown>;
+  return ['columns', 'rows', 'cellWidth', 'cellHeight', 'marginX', 'marginY', 'gapX', 'gapY'].every((key) => typeof candidate[key] === 'number' && Number.isFinite(candidate[key]));
+}
+
+function isAdjustmentMap(value: object): value is Record<string, FrameAdjustment> {
+  return Object.values(value).every((candidate) => isAdjustment(candidate));
+}
+
+function isAdjustment(value: unknown): value is FrameAdjustment {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Record<string, unknown>;
+  return isCropRect(candidate.crop) && isFiniteNumber(candidate.offsetX) && isFiniteNumber(candidate.offsetY);
+}
+
+function isCropRect(value: unknown): boolean {
+  if (!value || typeof value !== 'object') return false;
+  const crop = value as Record<string, unknown>;
+  return ['x', 'y', 'width', 'height'].every((key) => isFiniteNumber(crop[key]));
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+export function createFrameMetadata(frames: FrameSpec[], adjustments: Record<string, FrameAdjustment>): FrameMetadata[] {
+  return frames.map((frame) => {
+    const adjustment = normalizeAdjustment(adjustments[String(frame.index)] ?? frame.adjustment, frame);
+    return { index: frame.index, x: frame.sourceX, y: frame.sourceY, width: frame.width, height: frame.height, crop: adjustment.crop, offset: { x: adjustment.offsetX, y: adjustment.offsetY }, modified: isModified(adjustment, frame) };
+  });
+}