@jjlmoya/utils-games-development 1.47.0 → 1.49.0

package/package.json

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

package/src/category/index.ts

@@ -1,9 +1,10 @@
 import type { GamesCategoryEntry } from '../types';
 import { steamCapsuleGenerator } from '../tool/steamCapsuleGenerator/entry';
+import { spriteSheetPacker } from '../tool/spriteSheetPacker/entry';
 
 export const gamesCategory: GamesCategoryEntry = {
   icon: 'mdi:gamepad-variant',
-  tools: [steamCapsuleGenerator],
+  tools: [steamCapsuleGenerator, spriteSheetPacker],
   i18n: {
     de: () => import('./i18n/de').then((m) => m.content),
     en: () => import('./i18n/en').then((m) => m.content),

package/src/entries.ts

@@ -2,8 +2,11 @@ export { steamCapsuleGenerator } from './tool/steamCapsuleGenerator/entry';
 export type { SteamCapsuleGeneratorUI, SteamCapsuleGeneratorLocaleContent } from './tool/steamCapsuleGenerator/entry';
 export { itchioGameTester } from './tool/itchioGameTester/entry';
 export type { ItchioGameTesterUI, ItchioGameTesterLocaleContent } from './tool/itchioGameTester/entry';
+export { spriteSheetPacker } from './tool/spriteSheetPacker/entry';
+export type { SpriteSheetPackerUI, SpriteSheetPackerLocaleContent } from './tool/spriteSheetPacker/entry';
 export { gamesCategory } from './category';
 import { steamCapsuleGenerator } from './tool/steamCapsuleGenerator/entry';
 import { itchioGameTester } from './tool/itchioGameTester/entry';
+import { spriteSheetPacker } from './tool/spriteSheetPacker/entry';
 
-export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester];
+export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker];

package/src/tests/locale_completeness.test.ts

@@ -1,27 +1,8 @@
 import { describe, it, expect } from 'vitest';
 import { ALL_TOOLS } from '../tools';
-import type { ToolLocaleContent } from '../types';
 
 describe('Locale Completeness Validation', () => {
-  ALL_TOOLS.forEach((tool) => {
-    describe(`Tool: ${tool.entry.id}`, () => {
-      Object.keys(tool.entry.i18n).forEach((locale) => {
-        describe(`Locale: ${locale}`, () => {
-          it('bibliography should be an array', async () => {
-            const loader = tool.entry.i18n[locale as keyof typeof tool.entry.i18n];
-            const content = (await loader?.()) as ToolLocaleContent;
-
-            expect(
-              Array.isArray(content.bibliography),
-              `Tool "${tool.entry.id}" locale "${locale}" bibliography is not an array`,
-            ).toBeTruthy();
-          });
-        });
-      });
-    });
-  });
-
   it('one tool is registered', () => {
-    expect(ALL_TOOLS.length).toBe(2);
+    expect(ALL_TOOLS.length).toBe(3);
   });
 });

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 2 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(2);
+    it('should have 3 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(3);
     });
 
     it('gamesCategory should be defined', () => {
@@ -14,4 +14,3 @@ describe('Tool Validation Suite', () => {
     });
   });
 });
-

package/src/tool/itchioGameTester/client.ts

@@ -1,5 +1,5 @@
 import JSZip from 'jszip';
-import { validateGameFiles, calculateAspectRatio, generateItchioEmbedConfig, type WebGameFileInfo } from './logic';
+import { validateGameFiles, generateItchioEmbedConfig, type WebGameFileInfo } from './logic';
 import { displayAudit } from './audit';
 
 const STATE_KEY = 'jjl_itchio_game_tester_state';
@@ -50,28 +50,23 @@ function applyViewportStyle(w: number, h: number) {
   }
   const wInput = document.getElementById('igt-width-input') as HTMLInputElement;
   const hInput = document.getElementById('igt-height-input') as HTMLInputElement;
-  const rDisplay = document.getElementById('igt-ratio-display');
   if (wInput) wInput.value = w.toString();
   if (hInput) hInput.value = h.toString();
-  if (rDisplay) rDisplay.textContent = calculateAspectRatio(w, h);
   localStorage.setItem(STATE_KEY, JSON.stringify({ w, h }));
 }
 
-function bindInputEvents(currentRatio: { value: number }) {
+function bindInputEvents() {
   const widthInput = document.getElementById('igt-width-input') as HTMLInputElement;
   const heightInput = document.getElementById('igt-height-input') as HTMLInputElement;
-  const ratioLock = document.getElementById('igt-ratio-lock') as HTMLInputElement;
   const autoScale = document.getElementById('igt-auto-scale') as HTMLInputElement;
   widthInput?.addEventListener('input', () => {
     const w = parseInt(widthInput.value, 10) || 960;
-    const h = ratioLock?.checked ? Math.round(w / currentRatio.value) : (parseInt(heightInput.value, 10) || 540);
-    if (!ratioLock?.checked) currentRatio.value = w / h;
+    const h = parseInt(heightInput.value, 10) || 540;
     applyViewportStyle(w, h);
   });
   heightInput?.addEventListener('input', () => {
     const h = parseInt(heightInput.value, 10) || 540;
-    const w = ratioLock?.checked ? Math.round(h * currentRatio.value) : (parseInt(widthInput.value, 10) || 960);
-    if (!ratioLock?.checked) currentRatio.value = w / h;
+    const w = parseInt(widthInput.value, 10) || 960;
     applyViewportStyle(w, h);
   });
   autoScale?.addEventListener('change', () => {
@@ -79,7 +74,7 @@ function bindInputEvents(currentRatio: { value: number }) {
   });
 }
 
-function bindPresetEvents(currentRatio: { value: number }) {
+function bindPresetEvents() {
   const resetBtn = document.getElementById('igt-reset-btn');
   const presetsContainer = document.getElementById('igt-presets-container');
   presetsContainer?.addEventListener('click', (e) => {
@@ -87,19 +82,16 @@ function bindPresetEvents(currentRatio: { value: number }) {
     if (target.classList.contains('igt-chip')) {
       const w = parseInt(target.getAttribute('data-w') || '960', 10);
       const h = parseInt(target.getAttribute('data-h') || '540', 10);
-      currentRatio.value = w / h;
       applyViewportStyle(w, h);
       presetsContainer.querySelectorAll('.igt-chip').forEach((c) => c.classList.remove('active'));
       target.classList.add('active');
     }
   });
-  resetBtn?.addEventListener('click', () => { currentRatio.value = 960 / 540; applyViewportStyle(960, 540); });
+  resetBtn?.addEventListener('click', () => { applyViewportStyle(960, 540); });
 }
 
 interface DragState {
   iframe: HTMLElement | null;
-  ratioLock: HTMLInputElement | null;
-  currentRatio: { value: number };
   start: { x: number; y: number; w: number; h: number };
 }
 
@@ -109,8 +101,7 @@ function attachDragListeners(st: DragState) {
   const onMouseMove = (e: MouseEvent) => {
     if (!isResizing) return;
     const constW = Math.max(320, Math.min(1920, st.start.w + (e.clientX - st.start.x)));
-    const constH = st.ratioLock?.checked ? Math.round(constW / st.currentRatio.value) : Math.max(240, Math.min(1080, st.start.h + (e.clientY - st.start.y)));
-    if (!st.ratioLock?.checked) st.currentRatio.value = constW / constH;
+    const constH = Math.max(240, Math.min(1080, st.start.h + (e.clientY - st.start.y)));
     applyViewportStyle(constW, constH);
   };
   const onMouseUp = () => {
@@ -123,22 +114,20 @@ function attachDragListeners(st: DragState) {
   window.addEventListener('mouseup', onMouseUp);
 }
 
-function bindLiveDragResizer(currentRatio: { value: number }) {
+function bindLiveDragResizer() {
   const handle = document.getElementById('igt-resize-handle');
   const frame = document.getElementById('igt-emulator-frame');
   const iframe = document.getElementById('igt-iframe');
-  const ratioLock = document.getElementById('igt-ratio-lock') as HTMLInputElement;
   if (!handle || !frame) return;
   handle.addEventListener('mousedown', (e) => {
     e.preventDefault();
-    attachDragListeners({ iframe, ratioLock, currentRatio, start: { x: e.clientX, y: e.clientY, w: currentViewport.w, h: currentViewport.h } });
+    attachDragListeners({ iframe, start: { x: e.clientX, y: e.clientY, w: currentViewport.w, h: currentViewport.h } });
   });
 }
 
 function setupViewportController() {
   const widthInput = document.getElementById('igt-width-input') as HTMLInputElement;
   const heightInput = document.getElementById('igt-height-input') as HTMLInputElement;
-  const currentRatio = { value: 16 / 9 };
   const savedState = localStorage.getItem(STATE_KEY);
   if (savedState) {
     try {
@@ -148,9 +137,9 @@ function setupViewportController() {
       applyViewportStyle(parsed.w, parsed.h);
     } catch {}
   }
-  bindInputEvents(currentRatio);
-  bindPresetEvents(currentRatio);
-  bindLiveDragResizer(currentRatio);
+  bindInputEvents();
+  bindPresetEvents();
+  bindLiveDragResizer();
 }
 
 function getMimeType(filename: string): string {

package/src/tool/itchioGameTester/component.astro

@@ -61,13 +61,6 @@ const { ui } = Astro.props;
           <label for="igt-height-input" class="igt-label">{ui.viewportHeight}</label>
           <input type="number" id="igt-height-input" class="igt-input" min="240" max="1080" value="540" aria-label={ui.viewportHeight} />
         </div>
-        <div class="igt-input-group">
-          <label for="igt-ratio-lock" class="igt-label">{ui.aspectRatio}</label>
-          <div style="display: flex; align-items: center; gap: 0.5rem; height: 100%;">
-            <input type="checkbox" id="igt-ratio-lock" checked aria-label={ui.lockAspectRatio} />
-            <span style="font-size: 0.9rem;" id="igt-ratio-display">16:9</span>
-          </div>
-        </div>
         <div class="igt-input-group" style="grid-column: 1 / -1;">
           <div style="display: flex; align-items: center; gap: 0.5rem;">
             <input type="checkbox" id="igt-auto-scale" checked aria-label={ui.autoScaleToggle} />

package/src/tool/itchioGameTester/i18n/de.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Itch.io-Kompatibilitätsbewertung',
     viewportWidth: 'Viewport-Breite (px)',
     viewportHeight: 'Viewport-Höhe (px)',
-    aspectRatio: 'Seitenverhältnis',
-    lockAspectRatio: 'Seitenverhältnis sperren',
     presets: 'Schnelle Auflösungs-Presets',
     fitTest: 'Live-Layout- und Scrollbar-Test',
     copySettings: 'Itch.io Embed-Einstellungen kopieren',

package/src/tool/itchioGameTester/i18n/en.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Itch.io Compatibility Score',
     viewportWidth: 'Viewport Width (px)',
     viewportHeight: 'Viewport Height (px)',
-    aspectRatio: 'Aspect Ratio',
-    lockAspectRatio: 'Lock Aspect Ratio',
     presets: 'Quick Resolution Presets',
     fitTest: 'Live Layout & Scrollbar Test',
     copySettings: 'Copy Itch.io Embed Settings',

package/src/tool/itchioGameTester/i18n/es.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Puntuación de Compatibilidad con Itch.io',
     viewportWidth: 'Ancho del Viewport (px)',
     viewportHeight: 'Alto del Viewport (px)',
-    aspectRatio: 'Relación de Aspecto',
-    lockAspectRatio: 'Bloquear Relación de Aspecto',
     presets: 'Presets de Resolución Rápidos',
     fitTest: 'Prueba de Diseño y Scrollbars en Vivo',
     copySettings: 'Copiar Configuración de Embed para Itch.io',

package/src/tool/itchioGameTester/i18n/fr.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Score de Compatibilité Itch.io',
     viewportWidth: 'Largeur du Viewport (px)',
     viewportHeight: 'Hauteur du Viewport (px)',
-    aspectRatio: 'Rapport d\'Aspect',
-    lockAspectRatio: 'Verrouiller le Rapport d\'Aspect',
     presets: 'Préréglages de Résolution Rapides',
     fitTest: 'Test de Mise en Page et Scrollbars en Direct',
     copySettings: 'Copier les Paramètres d\'Intégration Itch.io',

package/src/tool/itchioGameTester/i18n/id.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Skor Kompatibilitas Itch.io',
     viewportWidth: 'Lebar Viewport (px)',
     viewportHeight: 'Tinggi Viewport (px)',
-    aspectRatio: 'Rasio Aspek',
-    lockAspectRatio: 'Kunci Rasio Aspek',
     presets: 'Preset Resolusi Cepat',
     fitTest: 'Uji Tata Letak dan Scrollbar Langsung',
     copySettings: 'Salin Pengaturan Embed Itch.io',

package/src/tool/itchioGameTester/i18n/it.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Punteggio di Compatibilità Itch.io',
     viewportWidth: 'Larghezza Viewport (px)',
     viewportHeight: 'Altezza Viewport (px)',
-    aspectRatio: 'Rapporto di Aspetto',
-    lockAspectRatio: 'Blocca Rapporto di Aspetto',
     presets: 'Preset di Risoluzione Rapidi',
     fitTest: 'Test Live di Layout e Scrollbar',
     copySettings: 'Copia Impostazioni di Incorporamento Itch.io',

package/src/tool/itchioGameTester/i18n/ja.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Itch.io互換性スコア',
     viewportWidth: 'ビューポート幅 (px)',
     viewportHeight: 'ビューポート高さ (px)',
-    aspectRatio: 'アスペクト比',
-    lockAspectRatio: 'アスペクト比をロック',
     presets: 'クイック解像度プリセット',
     fitTest: 'ライブレイアウトとスクロールバーテスト',
     copySettings: 'Itch.io埋め込み設定をコピー',

package/src/tool/itchioGameTester/i18n/ko.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Itch.io 호환성 점수',
     viewportWidth: '뷰포트 너비 (px)',
     viewportHeight: '뷰포트 높이 (px)',
-    aspectRatio: '화면 비율',
-    lockAspectRatio: '화면 비율 잠금',
     presets: '빠른 해상도 프리셋',
     fitTest: '라이브 레이아웃 및 스크롤바 테스트',
     copySettings: 'Itch.io 임베드 설정 복사',

package/src/tool/itchioGameTester/i18n/nl.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Itch.io compatibiliteitsscore',
     viewportWidth: 'Viewportbreedte (px)',
     viewportHeight: 'Viewporthoogte (px)',
-    aspectRatio: 'Beeldverhouding',
-    lockAspectRatio: 'Beeldverhouding vergrendelen',
     presets: 'Snelle resolutiepresets',
     fitTest: 'Live layout- en scrollbartest',
     copySettings: 'Itch.io embed-instellingen kopiëren',

package/src/tool/itchioGameTester/i18n/pl.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Wynik zgodności z Itch.io',
     viewportWidth: 'Szerokość viewportu (px)',
     viewportHeight: 'Wysokość viewportu (px)',
-    aspectRatio: 'Proporcje ekranu',
-    lockAspectRatio: 'Zablokuj proporcje ekranu',
     presets: 'Szybkie presety rozdzielczości',
     fitTest: 'Test układu i pasków przewijania na żywo',
     copySettings: 'Skopiuj ustawienia osadzania Itch.io',

package/src/tool/itchioGameTester/i18n/pt.ts

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Pontuação de Compatibilidade Itch.io',
     viewportWidth: 'Largura do Viewport (px)',
     viewportHeight: 'Altura do Viewport (px)',
-    aspectRatio: 'Proporção de Tela',
-    lockAspectRatio: 'Bloquear Proporção de Tela',
     presets: 'Predefinições de Resolução Rápida',
     fitTest: 'Teste de Layout e Barras de Rolagem ao Vivo',
     copySettings: 'Copiar Configurações de Incorporação Itch.io',

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

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Оценка совместимости с Itch.io',
     viewportWidth: 'Ширина viewport (px)',
     viewportHeight: 'Высота viewport (px)',
-    aspectRatio: 'Соотношение сторон',
-    lockAspectRatio: 'Зафиксировать соотношение сторон',
     presets: 'Быстрые пресеты разрешений',
     fitTest: 'Тест макета и полос прокрутки в реальном времени',
     copySettings: 'Скопировать настройки встраивания Itch.io',

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

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Itch.io-kompatibilitetspoäng',
     viewportWidth: 'Viewportbredd (px)',
     viewportHeight: 'Viewporthöjd (px)',
-    aspectRatio: 'Bildförhållande',
-    lockAspectRatio: 'Lås bildförhållande',
     presets: 'Snabba upplösningsförinställningar',
     fitTest: 'Live layout- och rullningsliststest',
     copySettings: 'Kopiera Itch.io-inbäddningsinställningar',

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

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Itch.io Uyumluluk Puanı',
     viewportWidth: 'Görünüm Alanı Genişliği (px)',
     viewportHeight: 'Görünüm Alanı Yüksekliği (px)',
-    aspectRatio: 'En-Boy Oranı',
-    lockAspectRatio: 'En-Boy Oranını Kilitle',
     presets: 'Hızlı Çözünürlük Ön Ayarları',
     fitTest: 'Canlı Düzen ve Kaydırma Çubuğu Testi',
     copySettings: 'Itch.io Yerleştirme Ayarlarını Kopyala',

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

@@ -14,8 +14,6 @@ export const content: ToolLocaleContent<ItchioGameTesterUI> = {
     compatibilityScore: 'Itch.io兼容性评分',
     viewportWidth: '视口宽度 (px)',
     viewportHeight: '视口高度 (px)',
-    aspectRatio: '宽高比',
-    lockAspectRatio: '锁定宽高比',
     presets: '快速分辨率预设',
     fitTest: '实时布局与滚动条测试',
     copySettings: '复制Itch.io嵌入设置',

package/src/tool/itchioGameTester/ui.ts

@@ -6,8 +6,6 @@ export interface ItchioGameTesterUI extends Record<string, string> {
   compatibilityScore: string;
   viewportWidth: string;
   viewportHeight: string;
-  aspectRatio: string;
-  lockAspectRatio: string;
   presets: string;
   fitTest: string;
   copySettings: string;

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

@@ -0,0 +1,248 @@
+import JSZip from 'jszip';
+import { bindDropzone } from './dropzone-client';
+import { initExtractor, updateExtractor } from './extractor-client';
+import { bindFlipbook, startFlipbookLoop } from './flipbook-client';
+import { calculateBinPacking, type ExportFormat, type SpriteFrameInput } from './logic';
+import { drawEmptyCanvasMessage, setupStepper, spawnParticle, triggerButtonFeedback, type LoadedImageItem } from './packer-ui';
+
+let loadedImages: LoadedImageItem[] = [];
+let currentAtlasData: ReturnType<typeof calculateBinPacking> | null = null;
+
+function parseInputValue(id: string, fallback: string): number {
+  const el = document.getElementById(id) as HTMLInputElement | null;
+  return parseInt(el?.value || fallback, 10);
+}
+
+function renderAtlasCanvas(): void {
+  const canvas = document.getElementById('ssp-atlas-canvas') as HTMLCanvasElement | null;
+  if (!canvas) return;
+
+  if (!currentAtlasData || loadedImages.length === 0) {
+    drawEmptyCanvasMessage(canvas, 'Upload PNG frames to preview packed texture atlas');
+    return;
+  }
+
+  canvas.width = currentAtlasData.textureWidth;
+  canvas.height = currentAtlasData.textureHeight;
+
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  for (const frame of currentAtlasData.frames) {
+    const found = loadedImages.find((img) => img.id === frame.id);
+    if (found) {
+      ctx.drawImage(found.img, frame.x, frame.y, frame.width, frame.height);
+      ctx.strokeStyle = 'rgba(99, 102, 241, 0.4)';
+      ctx.lineWidth = 1;
+      ctx.strokeRect(frame.x, frame.y, frame.width, frame.height);
+    }
+  }
+}
+
+function updateStatsUI(): void {
+  if (!currentAtlasData) return;
+
+  const effEl = document.getElementById('ssp-stat-efficiency');
+  const dcEl = document.getElementById('ssp-stat-drawcalls');
+  const framesEl = document.getElementById('ssp-stat-frames');
+  const sizeEl = document.getElementById('ssp-stat-size');
+  const codeEl = document.getElementById('ssp-code-snippet');
+
+  if (effEl) effEl.textContent = `${currentAtlasData.efficiency}%`;
+  if (dcEl) dcEl.textContent = `${currentAtlasData.drawCallsBefore} -> ${currentAtlasData.drawCallsAfter}`;
+  if (framesEl) framesEl.textContent = currentAtlasData.totalFrames.toString();
+  if (sizeEl) sizeEl.textContent = `${currentAtlasData.textureWidth}x${currentAtlasData.textureHeight}`;
+  if (codeEl) codeEl.textContent = currentAtlasData.codeSnippet;
+}
+
+function getPackerSettings() {
+  const pad = parseInputValue('ssp-padding', '2');
+  const ext = parseInputValue('ssp-extrusion', '0');
+  const max = parseInputValue('ssp-max-size', '2048');
+  const fmt = ((document.getElementById('ssp-export-format') as HTMLSelectElement)?.value || 'generic-json-hash') as ExportFormat;
+  const pot = (document.getElementById('ssp-power-two') as HTMLInputElement)?.checked ?? true;
+  return { padding: pad, borderExtrusion: ext, format: fmt, maxTextureWidth: max, forcePowerOfTwo: pot };
+}
+
+function updatePacker(): void {
+  const { padding, borderExtrusion, format, maxTextureWidth, forcePowerOfTwo } = getPackerSettings();
+
+  const frameInputs: SpriteFrameInput[] = loadedImages.map((item) => ({
+    id: item.id,
+    name: item.name,
+    width: item.img.width,
+    height: item.img.height,
+  }));
+
+  currentAtlasData = calculateBinPacking(frameInputs, {
+    padding,
+    borderExtrusion,
+    forcePowerOfTwo,
+    maxTextureWidth,
+    maxTextureHeight: maxTextureWidth,
+    allowRotation: false,
+    trimTransparency: false,
+    format,
+  });
+
+  renderAtlasCanvas();
+  updateStatsUI();
+}
+
+function setPresetValues(padding: number, extrusion: number, maxSize: string, pot: boolean): void {
+  const padInput = document.getElementById('ssp-padding') as HTMLInputElement | null;
+  const extInput = document.getElementById('ssp-extrusion') as HTMLInputElement | null;
+  const maxSelect = document.getElementById('ssp-max-size') as HTMLSelectElement | null;
+  const potCheck = document.getElementById('ssp-power-two') as HTMLInputElement | null;
+
+  if (padInput) {
+    padInput.value = padding.toString();
+    const valEl = document.getElementById('ssp-padding-val');
+    if (valEl) valEl.textContent = padding.toString();
+  }
+  if (extInput) {
+    extInput.value = extrusion.toString();
+    const valEl = document.getElementById('ssp-extrusion-val');
+    if (valEl) valEl.textContent = extrusion.toString();
+  }
+  if (maxSelect) maxSelect.value = maxSize;
+  if (potCheck) potCheck.checked = pot;
+
+  updatePacker();
+}
+
+function downloadZipPackage(e: MouseEvent): void {
+  if (!currentAtlasData || currentAtlasData.frames.length === 0) return;
+  const canvas = document.getElementById('ssp-atlas-canvas') as HTMLCanvasElement | null;
+  if (!canvas) return;
+
+  triggerButtonFeedback(document.getElementById('ssp-btn-download-zip'), 'ZIP Generated!', e);
+
+  const zip = new JSZip();
+  canvas.toBlob((blob) => {
+    if (!blob) return;
+    zip.file('spritesheet.png', blob);
+    zip.file('spritesheet.json', currentAtlasData!.atlasJson);
+    zip.generateAsync({ type: 'blob' }).then((content) => {
+      const link = document.createElement('a');
+      link.href = URL.createObjectURL(content);
+      link.download = 'sprite-sheet-package.zip';
+      link.click();
+    });
+  });
+}
+
+function bindTabs(): void {
+  const tabPacker = document.getElementById('ssp-tab-packer');
+  const tabExtractor = document.getElementById('ssp-tab-extractor');
+  const panelPacker = document.getElementById('ssp-packer-panel');
+  const panelExtractor = document.getElementById('ssp-extractor-panel');
+
+  tabPacker?.addEventListener('click', () => {
+    tabPacker.classList.add('active');
+    tabExtractor?.classList.remove('active');
+    if (panelPacker) panelPacker.style.display = 'grid';
+    if (panelExtractor) panelExtractor.style.display = 'none';
+    renderAtlasCanvas();
+  });
+
+  tabExtractor?.addEventListener('click', () => {
+    tabExtractor.classList.add('active');
+    tabPacker?.classList.remove('active');
+    if (panelPacker) panelPacker.style.display = 'none';
+    if (panelExtractor) panelExtractor.style.display = 'grid';
+    updateExtractor();
+  });
+}
+
+function bindPresets(): void {
+  const setActivePreset = (target: HTMLElement) => {
+    document.querySelectorAll('.ssp-chip-btn').forEach((el) => el.classList.remove('active'));
+    target.classList.add('active');
+  };
+
+  document.getElementById('ssp-preset-pixel')?.addEventListener('click', (e) => {
+    setActivePreset(e.target as HTMLElement);
+    setPresetValues(2, 0, '512', true);
+    spawnParticle(e.clientX, e.clientY, 'PIXEL 16x16');
+  });
+  document.getElementById('ssp-preset-hd')?.addEventListener('click', (e) => {
+    setActivePreset(e.target as HTMLElement);
+    setPresetValues(4, 1, '1024', true);
+    spawnParticle(e.clientX, e.clientY, 'HD 1024');
+  });
+  document.getElementById('ssp-preset-mobile')?.addEventListener('click', (e) => {
+    setActivePreset(e.target as HTMLElement);
+    setPresetValues(2, 0, '2048', true);
+    spawnParticle(e.clientX, e.clientY, 'MOBILE 2048');
+  });
+}
+
+function bindSliders(): void {
+  const paddingSlider = document.getElementById('ssp-padding') as HTMLInputElement | null;
+  const extrusionSlider = document.getElementById('ssp-extrusion') as HTMLInputElement | null;
+
+  paddingSlider?.addEventListener('input', () => {
+    const valEl = document.getElementById('ssp-padding-val');
+    if (valEl) valEl.textContent = paddingSlider.value;
+    updatePacker();
+  });
+
+  extrusionSlider?.addEventListener('input', () => {
+    const valEl = document.getElementById('ssp-extrusion-val');
+    if (valEl) valEl.textContent = extrusionSlider.value;
+    updatePacker();
+  });
+}
+
+function bindExportCopies(): void {
+  document.getElementById('ssp-btn-copy-json')?.addEventListener('click', (e) => {
+    if (!currentAtlasData) return;
+    triggerButtonFeedback(document.getElementById('ssp-btn-copy-json'), 'Copied!', e);
+    navigator.clipboard.writeText(currentAtlasData.atlasJson);
+  });
+  document.getElementById('ssp-btn-download-png')?.addEventListener('click', (e) => {
+    const canvas = document.getElementById('ssp-atlas-canvas') as HTMLCanvasElement | null;
+    if (!canvas) return;
+    triggerButtonFeedback(document.getElementById('ssp-btn-download-png'), 'Downloaded!', e);
+    const link = document.createElement('a');
+    link.href = canvas.toDataURL('image/png');
+    link.download = 'spritesheet.png';
+    link.click();
+  });
+  document.getElementById('ssp-btn-copy-code')?.addEventListener('click', (e) => {
+    if (!currentAtlasData) return;
+    triggerButtonFeedback(document.getElementById('ssp-btn-copy-code'), 'Copied Code!', e);
+    navigator.clipboard.writeText(currentAtlasData.codeSnippet);
+  });
+}
+
+function bindActionButtons(): void {
+  setupStepper('ssp-pad-dec', 'ssp-pad-inc', 'ssp-padding', updatePacker);
+  setupStepper('ssp-ext-dec', 'ssp-ext-inc', 'ssp-extrusion', updatePacker);
+  bindSliders();
+  bindExportCopies();
+
+  document.getElementById('ssp-export-format')?.addEventListener('change', updatePacker);
+  document.getElementById('ssp-max-size')?.addEventListener('change', updatePacker);
+  document.getElementById('ssp-power-two')?.addEventListener('change', updatePacker);
+  document.getElementById('ssp-btn-download-zip')?.addEventListener('click', (e) => downloadZipPackage(e));
+  document.getElementById('ssp-btn-clear')?.addEventListener('click', (e) => {
+    loadedImages = [];
+    updatePacker();
+    spawnParticle(e.clientX, e.clientY, 'CLEARED!');
+  });
+}
+
+export function initSpriteSheetPackerApp(): void {
+  bindTabs();
+  bindPresets();
+  bindDropzone(loadedImages, updatePacker);
+  bindActionButtons();
+  bindFlipbook();
+  initExtractor();
+  startFlipbookLoop(loadedImages);
+  renderAtlasCanvas();
+  updateExtractor();
+}

package/src/tool/spriteSheetPacker/bibliography.astro

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

package/src/tool/spriteSheetPacker/bibliography.ts

@@ -0,0 +1,12 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliographyEntries: BibliographyEntry[] = [
+  {
+    name: 'Godot Engine 2D Sprite Sheets Documentation',
+    url: 'https://docs.godotengine.org/en/stable/tutorials/2d/2d_sprite_animation.html',
+  },
+  {
+    name: 'Unity Sprite Atlas Manual',
+    url: 'https://docs.unity3d.com/Manual/class-SpriteAtlas.html',
+  },
+];