spritemint 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafet KAYA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+<div align="center">
+
+# 🍃 SpriteMint
+
+**Interactive Node.js CLI tool for Unity 2D developers**
+
+[![npm version](https://img.shields.io/npm/v/spritemint.svg?style=flat-square)](https://npmjs.org/package/spritemint)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-v18+-green.svg?style=flat-square)](https://nodejs.org/)
+[![CLI Tool](https://img.shields.io/badge/CLI-Terminal-blue.svg?style=flat-square)](#)
+
+*Normalize sprites, extract sprite sheets, and build new sprite sheets — directly from the terminal, no GUI required.*
+
+</div>
+
+---
+
+## 🚀 Demo
+
+```bash
+$ spritemint
+
+  🍃 SpriteMint — Unity Sprite Processor
+
+? What do you want to do?
+❯ Normalize Sprites
+  Extract Sprites from Sheet and Build Horizontal Output
+  Build Sprite Sheet from Selected PNGs
+```
+
+---
+
+## 📖 Help
+
+Not sure what to do? Just run:
+
+```bash
+spritemint --help
+```
+
+> You can also use the shorthand: `spritemint -h`
+
+This will print a full usage guide directly in your terminal:
+
+```
+SpriteMint — Unity Sprite Processor
+
+USAGE
+  spritemint             Launch interactive menu
+  spritemint --help      Show this help message
+  spritemint -h          Show this help message
+
+COMMANDS
+  ┌─────────────────────────────────────────────────────────────────┐
+  │  1. Normalize Sprites                                           │
+  │     Resize PNGs to a square canvas with transparent padding.   │
+  │     Aspect ratio is always preserved.                          │
+  │     Output → <folder>/normalized/                              │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  2. Extract Sprites from Sheet & Build Horizontal Output        │
+  │     Extract frames from a grid-based sprite sheet,             │
+  │     normalize each one, and stitch into a horizontal strip.    │
+  │     Output → <folder>/output_horizontal.png                    │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  3. Build Sprite Sheet from Selected PNGs                       │
+  │     Pick individual PNGs and combine them into a sprite sheet. │
+  │     Supports horizontal strip or grid layout.                  │
+  │     Output → <folder>/spritesheet_output.png                   │
+  └─────────────────────────────────────────────────────────────────┘
+
+REQUIREMENTS
+  Node.js v18+   |   PNG image files
+```
+
+---
+
+## ✨ Features
+
+### 1️⃣ Normalize Sprites
+- 📂 **Interactive Selection**: Scans a folder and presents PNG files in an interactive checkbox list.
+- 📐 **Smart Resizing**: Resizes each sprite so its largest side fits within the chosen canvas size (256, 512, 1024, or custom).
+- 🖼️ **Aspect Ratio Preservation**: Never stretches or distorts your art.
+- 🎯 **Perfect Centering**: Centers each sprite on a transparent square canvas with equal padding on all four sides.
+- 💾 **Clean Output**: Saves results directly into a `normalized/` folder in your working directory.
+
+### 2️⃣ Extract Sprites from Sheet & Build Horizontal Output
+- 🧩 **Grid Extraction**: Accepts a sprite sheet PNG and extracts each grid cell using exact pixel coordinates.
+- 🔍 **Smart Auto Detect**: Analyses image dimensions to find the most likely grid — prefers square, power-of-two cells. If detection fails, falls back to asking you for rows and columns.
+- ✂️ **Automatic Trimming**: Trims transparent edges from each extracted sprite automatically.
+- 🔄 **Normalization**: Normalizes each extracted sprite into an equal-sized square canvas.
+- 🎞️ **Horizontal Compositing**: Composites all sprites side-by-side into a single, seamless horizontal PNG strip, perfect for Unity animations.
+- 📂 **Subfolder Scanning**: Searches the current folder and its immediate subdirectories for PNG files.
+
+### 3️⃣ Build Sprite Sheet from Selected PNGs
+- ☑️ **Interactive File Picker**: Select any combination of PNG files from a folder using an interactive checkbox list.
+- 🗂️ **Flexible Layouts**: Choose between a **Horizontal Strip** (all sprites in one row) or a **Grid** (specify columns, rows calculated automatically).
+- 📏 **Configurable Cell Size**: Pick from 256, 512, or 1024 px — or enter a custom value.
+- 🎯 **Auto-Centering**: Every sprite is trimmed, scaled to fit the cell, and centered with equal padding on all sides.
+- 🖼️ **Transparent Canvas**: The output sheet is a fully transparent PNG — compositing-ready for Unity or any tool.
+- 💾 **Saves to Working Directory**: Output filename is configurable (defaults to `sheet.png`) and is written to wherever you invoked the CLI.
+
+---
+
+## ⚙️ Installation
+
+### Global Install (Recommended)
+
+To run SpriteMint from anywhere on your machine, install it globally:
+
+```bash
+npm install -g spritemint
+```
+
+Then simply use the command:
+
+```bash
+spritemint
+```
+
+### Local / Development Setup
+
+```bash
+git clone https://github.com/rakaya07/spritemint.git
+cd spritemint
+npm install
+npm start
+```
+
+---
+
+## 🕹️ Usage Examples
+
+### 1. Normalize Sprites
+
+Run SpriteMint in your project folder, and it will guide you interactively:
+
+```bash
+$ spritemint
+
+? What do you want to do?
+❯ Normalize Sprites
+
+? Select folder containing PNG files:
+❯ Use current folder
+
+? Select PNG sprites to normalize (use space to select):
+❯ ◉ hero_idle.png
+  ◉ hero_walk1.png
+  ◉ hero_walk2.png
+
+? Output sprite size:
+❯ 512
+
+  ✔ Done! 3 sprites normalized.
+
+  Output : /your/project/normalized
+  Size   : 512×512px
+  Files  : 3 processed
+```
+
+### 2. Extract Sprites from Sheet
+
+Perfect for converting existing grid sheets into Unity-friendly horizontal strips:
+
+```bash
+$ spritemint
+
+? What do you want to do?
+❯ Extract Sprites from Sheet and Build Horizontal Output
+
+? Select PNG file:
+❯ sheet_characters.png
+  sprites/hero_sheet.png
+
+? Sprite detection mode:
+❯ Auto Detect
+
+  ℹ Auto-detected grid: 2 rows × 2 cols
+
+? Output cell size (px):
+❯ 512
+
+? Output filename: output-horizontal.png
+
+  ✔ Done!
+
+  Input    : /your/project/sheet_characters.png
+  Mode     : Auto Detect
+  Grid     : 2 rows × 2 cols
+  Sprites  : 4 / 4
+  Cell size: 512×512px
+  Output   : /your/project/output-horizontal.png
+  Canvas   : 2048×512px
+```
+
+> If Auto Detect cannot determine the grid (non-power-of-two dimensions), SpriteMint will automatically ask you to enter the row and column count manually.
+
+### 3. Build Sprite Sheet from Selected PNGs
+
+Combine individual PNG files into a new sprite sheet with full control over layout and cell size:
+
+```bash
+$ spritemint
+
+? What do you want to do?
+❯ Build Sprite Sheet from Selected PNGs
+
+? Select folder containing PNG files:
+❯ Use current folder
+
+? Select PNG files to include (use space to select):
+❯ ◉ hero_idle.png
+  ◉ hero_run1.png
+  ◉ hero_run2.png
+  ◉ hero_run3.png
+
+? Output layout:
+❯ Grid
+
+? Output cell size (px):
+❯ 512
+
+? Number of columns (4 images selected): 2
+
+? Output filename: hero_sheet.png
+
+  ✔ Done! Sprite sheet built from 4 images.
+
+  Images   : 4 selected
+  Layout   : Grid
+  Grid     : 2 cols × 2 rows
+  Cell     : 512×512px
+  Output   : /your/project/hero_sheet.png
+```
+
+---
+
+## 🗺️ Visual Workflow
+
+### Normalizing Individual Sprites
+```text
+[ RAW SPRITES ]
+  hero_idle.png
+  hero_walk1.png
+  hero_walk2.png
+            │
+            ▼
+      🍃 SpriteMint
+    Center & Normalize
+            │
+            ▼
+[ NORMALIZED OUTPUT ]  normalized/
+  hero_idle.png   (512×512, centered on transparent canvas)
+  hero_walk1.png
+  hero_walk2.png
+```
+
+### Extracting & Building a Horizontal Strip
+```text
+[ sheet_characters.png ]  (1024×1024, 2×2 grid)
+            │
+            ▼
+      🍃 SpriteMint
+    Extract → Normalize
+            │
+            ▼
+[ output-horizontal.png ]  (2048×512 seamless strip)
+```
+
+### Building a Sheet from Selected PNGs
+```text
+[ INDIVIDUAL PNGs ]
+  hero_idle.png
+  hero_run1.png   ─────────┐
+  hero_run2.png             │  🍃 SpriteMint
+  hero_run3.png   ─────────┘  Select → Layout → Composite
+                              │
+                              ▼
+              [ hero_sheet.png ]  (1024×1024, 2×2 grid)
+```
+
+---
+
+## 📂 Project Structure
+
+```text
+spritemint/
+├── bin/
+│   └── spritemint.js                    # CLI entry point
+├── src/
+│   ├── index.js                         # Main menu & orchestration
+│   ├── commands/
+│   │   ├── normalize.js                 # Flow: Normalize Sprites
+│   │   ├── extractHorizontal.js         # Flow: Extract & Composite
+│   │   └── buildSheet.js                # Flow: Build Sprite Sheet
+│   ├── core/
+│   │   ├── normalizeSprites.js          # Logic: normalizing
+│   │   ├── extractAndBuildHorizontal.js # Logic: extraction & compositing
+│   │   └── buildSpriteSheet.js          # Logic: sheet building
+│   └── utils/
+│       ├── folder.js                    # Shared folder/file selection prompts
+│       └── image.js                     # Shared image processing & SIZE_CHOICES
+├── package.json
+└── README.md
+```
+
+---
+
+## 🛣️ Roadmap
+
+We are constantly aiming to make `SpriteMint` better. Planned features include:
+
+- [x] **Grid Auto Detection**: Detects grid layout from image dimensions (power-of-two cell analysis). Falls back to manual input if detection fails.
+- [ ] **Advanced Auto Sprite Detection**: Detect sprites without a rigid grid (using alpha/pixel clustering).
+- [ ] **GUI Version**: A standalone Desktop companion app (Electron/Tauri) for visual users.
+- [ ] **WebP/GIF Support**: Output configurations for highly-compressed formats.
+- [ ] **Custom Paddings & Offsets**: More granular controls over sprite placement on canvas.
+
+---
+
+## 🤝 Contributing
+
+Contributions are completely welcome and encouraged! Here's how you can help:
+
+1. **Fork** the repository.
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
+4. Push to the branch (`git push origin feature/AmazingFeature`).
+5. Open a **Pull Request**.
+
+All issues and PRs are appreciated to make this tool better for the open source and game developer community.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
+
+<div align="center">
+  <i>Built with ❤️ for Game Developers & the Unity Community.</i>
+</div>

package/bin/spritemint.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { showHelp } from '../src/help.js';
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  showHelp();
+  process.exit(0);
+}
+
+import('../src/index.js');

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "spritemint",
+  "version": "1.0.0",
+  "description": "Interactive CLI tool for normalizing, extracting, and building Unity sprite sheets",
+  "main": "src/index.js",
+  "bin": {
+    "spritemint": "./bin/spritemint.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node bin/spritemint.js"
+  },
+  "keywords": [
+    "sprite",
+    "spritesheet",
+    "unity",
+    "image",
+    "cli",
+    "normalize",
+    "extract",
+    "sharp",
+    "game-dev",
+    "pixel-art"
+  ],
+  "author": "Rafet",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "inquirer": "^9.3.7",
+    "ora": "^8.1.1",
+    "sharp": "^0.34.5"
+  }
+}

package/src/commands/buildSheet.js

@@ -0,0 +1,90 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { buildSpriteSheet } from '../core/buildSpriteSheet.js';
+import { selectFolder, selectPngFiles } from '../utils/folder.js';
+import { SIZE_CHOICES } from '../utils/image.js';
+
+const LAYOUT_CHOICES = {
+  HORIZONTAL: 'Horizontal Strip',
+  GRID:       'Grid',
+};
+
+export async function runBuildSheet() {
+  console.log(chalk.cyan('\n  Build Sprite Sheet from Selected PNGs\n'));
+
+  const folder = await selectFolder();
+
+  const files = await selectPngFiles(folder, 'Select PNG files to include (use space to select):');
+  if (files.length === 0) {
+    console.log(chalk.yellow('\n  No files selected. Operation cancelled.\n'));
+    return;
+  }
+
+  const { layout } = await inquirer.prompt([
+    {
+      type:    'list',
+      name:    'layout',
+      message: 'Output layout:',
+      choices: Object.values(LAYOUT_CHOICES),
+    },
+  ]);
+
+  const { sizeChoice } = await inquirer.prompt([
+    {
+      type:    'list',
+      name:    'sizeChoice',
+      message: 'Output cell size (px):',
+      choices: Object.values(SIZE_CHOICES),
+    },
+  ]);
+
+  let cellSize;
+  if (sizeChoice === SIZE_CHOICES.CUSTOM) {
+    const { customSize } = await inquirer.prompt([
+      {
+        type:     'input',
+        name:     'customSize',
+        message:  'Enter custom cell size (px):',
+        validate: (input) => {
+          const n = parseInt(input, 10);
+          return (Number.isInteger(n) && n > 0) || 'Please enter a positive integer.';
+        },
+        filter: (input) => parseInt(input, 10),
+      },
+    ]);
+    cellSize = customSize;
+  } else {
+    cellSize = parseInt(sizeChoice, 10);
+  }
+
+  let cols = files.length;
+  if (layout === LAYOUT_CHOICES.GRID) {
+    const { colCount } = await inquirer.prompt([
+      {
+        type:     'input',
+        name:     'colCount',
+        message:  `Number of columns (${files.length} images selected):`,
+        validate: (input) => {
+          const n = parseInt(input, 10);
+          return (Number.isInteger(n) && n > 0) || 'Please enter a positive integer.';
+        },
+        filter: (input) => parseInt(input, 10),
+      },
+    ]);
+    cols = colCount;
+  }
+
+  const { rawName } = await inquirer.prompt([
+    {
+      type:    'input',
+      name:    'rawName',
+      message: 'Output filename:',
+      default: 'sheet.png',
+    },
+  ]);
+  const outputName = rawName.trim().toLowerCase().endsWith('.png')
+    ? rawName.trim()
+    : `${rawName.trim()}.png`;
+
+  await buildSpriteSheet({ files, cellSize, layout, cols, outputName });
+}

package/src/commands/extractHorizontal.js

@@ -0,0 +1,97 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { extractAndBuildHorizontal } from '../core/extractAndBuildHorizontal.js';
+import { selectPngFile } from '../utils/folder.js';
+import { SIZE_CHOICES } from '../utils/image.js';
+
+const DETECTION_MODE = {
+  AUTO:   'Auto Detect',
+  MANUAL: 'Manual Grid',
+};
+
+export async function runExtractHorizontal() {
+  console.log(chalk.cyan('\n  Extract Sprites → Horizontal Sheet\n'));
+
+  const inputFile = await selectPngFile();
+
+  const { detectionMode } = await inquirer.prompt([
+    {
+      type:    'list',
+      name:    'detectionMode',
+      message: 'Sprite detection mode:',
+      choices: Object.values(DETECTION_MODE),
+    },
+  ]);
+
+  let grid = null;
+  if (detectionMode === DETECTION_MODE.MANUAL) {
+    const { rows, cols } = await inquirer.prompt([
+      {
+        type:     'input',
+        name:     'rows',
+        message:  'Number of rows:',
+        validate: (input) => {
+          const n = parseInt(input, 10);
+          return (Number.isInteger(n) && n > 0) || 'Please enter a positive integer.';
+        },
+        filter: (input) => parseInt(input, 10),
+      },
+      {
+        type:     'input',
+        name:     'cols',
+        message:  'Number of columns:',
+        validate: (input) => {
+          const n = parseInt(input, 10);
+          return (Number.isInteger(n) && n > 0) || 'Please enter a positive integer.';
+        },
+        filter: (input) => parseInt(input, 10),
+      },
+    ]);
+    grid = { rows, cols };
+  }
+
+  const { sizeChoice } = await inquirer.prompt([
+    {
+      type:    'list',
+      name:    'sizeChoice',
+      message: 'Output cell size (px):',
+      choices: Object.values(SIZE_CHOICES),
+    },
+  ]);
+
+  let cellSize;
+  if (sizeChoice === SIZE_CHOICES.CUSTOM) {
+    const { customSize } = await inquirer.prompt([
+      {
+        type:     'input',
+        name:     'customSize',
+        message:  'Enter custom cell size (px):',
+        validate: (input) => {
+          const n = parseInt(input, 10);
+          return (Number.isInteger(n) && n > 0) || 'Please enter a positive integer.';
+        },
+        filter: (input) => parseInt(input, 10),
+      },
+    ]);
+    cellSize = customSize;
+  } else {
+    cellSize = parseInt(sizeChoice, 10);
+  }
+
+  const { outputFile } = await inquirer.prompt([
+    {
+      type:    'input',
+      name:    'outputFile',
+      message: 'Output filename:',
+      default: 'output-horizontal.png',
+    },
+  ]);
+
+  await extractAndBuildHorizontal({
+    inputFile,
+    detectionMode,
+    grid,
+    cellSize,
+    outputFile: outputFile.trim(),
+  });
+}

package/src/commands/normalize.js

@@ -0,0 +1,47 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { normalizeSprites } from '../core/normalizeSprites.js';
+import { selectFolder, selectPngFiles } from '../utils/folder.js';
+import { SIZE_CHOICES } from '../utils/image.js';
+
+export async function runNormalize() {
+  console.log(chalk.cyan('\n  Normalize Sprites\n'));
+
+  const folder = await selectFolder();
+
+  const files = await selectPngFiles(folder, 'Select PNG sprites to normalize (use space to select):');
+  if (files.length === 0) {
+    console.log(chalk.yellow('\n  No files selected. Operation cancelled.\n'));
+    return;
+  }
+
+  const { sizeChoice } = await inquirer.prompt([
+    {
+      type:    'list',
+      name:    'sizeChoice',
+      message: 'Output sprite size:',
+      choices: Object.values(SIZE_CHOICES),
+    },
+  ]);
+
+  let size;
+  if (sizeChoice === SIZE_CHOICES.CUSTOM) {
+    const { customSize } = await inquirer.prompt([
+      {
+        type:     'input',
+        name:     'customSize',
+        message:  'Enter custom size (px):',
+        validate: (input) => {
+          const n = parseInt(input, 10);
+          return (Number.isInteger(n) && n > 0) || 'Please enter a positive integer.';
+        },
+        filter: (input) => parseInt(input, 10),
+      },
+    ]);
+    size = customSize;
+  } else {
+    size = parseInt(sizeChoice, 10);
+  }
+
+  await normalizeSprites({ files, size });
+}

package/src/core/buildSpriteSheet.js

@@ -0,0 +1,87 @@
+import path from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import sharp from 'sharp';
+import { normalizeToCell } from '../utils/image.js';
+
+const LAYOUT = {
+  HORIZONTAL: 'Horizontal Strip',
+  GRID:       'Grid',
+};
+
+/**
+ * Builds a sprite sheet from the given PNG files.
+ *
+ * @param {{
+ *   files:      string[],
+ *   cellSize:   number,
+ *   layout:     string,
+ *   cols:       number,
+ *   outputName: string,
+ * }} options
+ */
+export async function buildSpriteSheet({ files, cellSize, layout, cols, outputName }) {
+  const isGrid    = layout === LAYOUT.GRID;
+  const sheetCols = isGrid ? cols : files.length;
+  const rows      = isGrid ? Math.ceil(files.length / cols) : 1;
+
+  const sheetWidth  = cellSize * sheetCols;
+  const sheetHeight = cellSize * rows;
+
+  const spinner = ora(`Processing ${files.length} sprites…`).start();
+
+  // Normalize all sprites in parallel
+  const results = await Promise.all(
+    files.map(async (inputPath, i) => {
+      const filename = path.basename(inputPath);
+      try {
+        const buf = await normalizeToCell(inputPath, cellSize);
+        const col = isGrid ? i % cols : i;
+        const row = isGrid ? Math.floor(i / cols) : 0;
+        return { ok: true, input: buf, left: col * cellSize, top: row * cellSize };
+      } catch (err) {
+        return { ok: false, filename, message: err.message };
+      }
+    })
+  );
+
+  const composites = results.filter((r) => r.ok).map(({ input, left, top }) => ({ input, left, top }));
+  const errors     = results.filter((r) => !r.ok);
+  const processed  = composites.length;
+  const failed     = errors.length;
+
+  spinner.text = 'Compositing sprite sheet…';
+
+  const outputPath = path.join(process.cwd(), outputName);
+
+  await sharp({
+    create: {
+      width:      sheetWidth,
+      height:     sheetHeight,
+      channels:   4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    },
+  })
+    .png()
+    .composite(composites)
+    .toFile(outputPath);
+
+  if (failed === 0) {
+    spinner.succeed(chalk.green(`Done! Sprite sheet built from ${processed} image${processed !== 1 ? 's' : ''}.`));
+  } else {
+    spinner.warn(chalk.yellow(`Finished with ${failed} error${failed !== 1 ? 's' : ''}.`));
+    for (const { filename, message } of errors) {
+      console.log(chalk.red(`  ✖ ${filename}: `) + chalk.gray(message));
+    }
+  }
+
+  console.log(
+    chalk.gray('\n  Images   : ') + chalk.white(`${processed} selected`) +
+    chalk.gray('\n  Layout   : ') + chalk.white(layout) +
+    (isGrid
+      ? chalk.gray('\n  Grid     : ') + chalk.white(`${sheetCols} cols × ${rows} rows`)
+      : '') +
+    chalk.gray('\n  Cell     : ') + chalk.white(`${cellSize}×${cellSize}px`) +
+    chalk.gray('\n  Output   : ') + chalk.white(outputPath) + '\n'
+  );
+}

package/src/core/extractAndBuildHorizontal.js

@@ -0,0 +1,174 @@
+import path from 'path';
+import inquirer from 'inquirer';
+import ora from 'ora';
+import chalk from 'chalk';
+import sharp from 'sharp';
+import { normalizeToCell, autoDetectGrid } from '../utils/image.js';
+
+/**
+ * @typedef {{ rows: number, cols: number }} Grid
+ *
+ * @typedef {{
+ *   inputFile:     string,
+ *   detectionMode: 'Auto Detect' | 'Manual Grid',
+ *   grid:          Grid | null,
+ *   cellSize:      number,
+ *   outputFile:    string,
+ * }} ExtractHorizontalOptions
+ */
+
+/**
+ * Extracts individual sprites from a sprite sheet, normalizes each one into
+ * a square cell with transparent padding, and composites them into a single
+ * horizontal PNG strip.
+ *
+ * @param {ExtractHorizontalOptions} options
+ */
+export async function extractAndBuildHorizontal({
+  inputFile,
+  detectionMode,
+  grid,
+  cellSize,
+  outputFile,
+}) {
+  const spinner = ora('Loading image…').start();
+
+  const source = sharp(inputFile);
+  const { width: imageWidth, height: imageHeight } = await source.metadata();
+
+  spinner.text = 'Determining grid…';
+
+  let rows, cols;
+
+  if (detectionMode === 'Manual Grid') {
+    rows = grid.rows;
+    cols = grid.cols;
+  } else {
+    const detected = autoDetectGrid(imageWidth, imageHeight);
+    if (detected) {
+      rows = detected.rows;
+      cols = detected.cols;
+      spinner.info(chalk.cyan(`  Auto-detected grid: ${rows} rows × ${cols} cols`));
+      spinner.start('Extracting sprite regions…');
+    } else {
+      spinner.stop();
+      console.log(chalk.yellow('  Could not auto-detect grid. Please enter manually.\n'));
+      const { manualRows, manualCols } = await inquirer.prompt([
+        {
+          type:     'input',
+          name:     'manualRows',
+          message:  'Number of rows:',
+          validate: (input) => {
+            const n = parseInt(input, 10);
+            return (Number.isInteger(n) && n > 0) || 'Please enter a positive integer.';
+          },
+          filter: (input) => parseInt(input, 10),
+        },
+        {
+          type:     'input',
+          name:     'manualCols',
+          message:  'Number of columns:',
+          validate: (input) => {
+            const n = parseInt(input, 10);
+            return (Number.isInteger(n) && n > 0) || 'Please enter a positive integer.';
+          },
+          filter: (input) => parseInt(input, 10),
+        },
+      ]);
+      rows = manualRows;
+      cols = manualCols;
+      spinner.start('Extracting sprite regions…');
+    }
+  }
+
+  const cellWidth   = Math.floor(imageWidth  / cols);
+  const cellHeight  = Math.floor(imageHeight / rows);
+  const spriteCount = rows * cols;
+
+  // Extract all grid cells in parallel
+  const extractedBuffers = await Promise.all(
+    Array.from({ length: spriteCount }, (_, i) => {
+      const row = Math.floor(i / cols);
+      const col = i % cols;
+      return sharp(inputFile)
+        .extract({
+          left:   col * cellWidth,
+          top:    row * cellHeight,
+          width:  cellWidth,
+          height: cellHeight,
+        })
+        .png()
+        .toBuffer();
+    })
+  );
+
+  // Normalize each sprite in parallel, capturing per-sprite errors
+  spinner.text = 'Normalizing sprites…';
+
+  const normalizeResults = await Promise.all(
+    extractedBuffers.map(async (buf, i) => {
+      try {
+        const normalized = await normalizeToCell(buf, cellSize);
+        return { ok: true, buf: normalized, index: i };
+      } catch (err) {
+        return { ok: false, index: i, message: err.message };
+      }
+    })
+  );
+
+  const succeeded = normalizeResults.filter((r) => r.ok);
+  const failed    = normalizeResults.filter((r) => !r.ok);
+
+  if (succeeded.length === 0) {
+    spinner.fail(chalk.red('All sprites failed to normalize.'));
+    for (const { index, message } of failed) {
+      console.log(chalk.red(`  ✖ sprite ${index + 1}: `) + chalk.gray(message));
+    }
+    return;
+  }
+
+  // Build horizontal strip
+  spinner.text = 'Building horizontal sheet…';
+
+  const stripWidth     = cellSize * succeeded.length;
+  const compositeInput = succeeded.map(({ buf }, i) => ({
+    input: buf,
+    left:  i * cellSize,
+    top:   0,
+  }));
+
+  const outputPath = path.isAbsolute(outputFile)
+    ? outputFile
+    : path.join(process.cwd(), outputFile);
+
+  await sharp({
+    create: {
+      width:      stripWidth,
+      height:     cellSize,
+      channels:   4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    },
+  })
+    .png()
+    .composite(compositeInput)
+    .toFile(outputPath);
+
+  if (failed.length === 0) {
+    spinner.succeed(chalk.green('Done!'));
+  } else {
+    spinner.warn(chalk.yellow(`Finished with ${failed.length} error${failed.length !== 1 ? 's' : ''}.`));
+    for (const { index, message } of failed) {
+      console.log(chalk.red(`  ✖ sprite ${index + 1}: `) + chalk.gray(message));
+    }
+  }
+
+  console.log(
+    chalk.gray('\n  Input    : ') + chalk.white(inputFile) +
+    chalk.gray('\n  Mode     : ') + chalk.white(detectionMode) +
+    chalk.gray('\n  Grid     : ') + chalk.white(`${rows} rows × ${cols} cols`) +
+    chalk.gray('\n  Sprites  : ') + chalk.white(`${succeeded.length} / ${spriteCount}`) +
+    chalk.gray('\n  Cell size: ') + chalk.white(`${cellSize}×${cellSize}px`) +
+    chalk.gray('\n  Output   : ') + chalk.white(outputPath) +
+    chalk.gray('\n  Canvas   : ') + chalk.white(`${stripWidth}×${cellSize}px`) + '\n'
+  );
+}

package/src/core/normalizeSprites.js

@@ -0,0 +1,52 @@
+import fs from 'fs';
+import path from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import sharp from 'sharp';
+import { normalizeToCell } from '../utils/image.js';
+
+/**
+ * @param {{ files: string[], size: number }} options
+ *   files - Absolute paths of the PNG files to process.
+ *   size  - Side length of the output square canvas in pixels.
+ */
+export async function normalizeSprites({ files, size }) {
+  const outputDir = path.join(process.cwd(), 'normalized');
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const spinner  = ora(`Processing 1 / ${files.length}`).start();
+  let processed  = 0;
+  let failed     = 0;
+  const errors   = [];
+
+  for (const inputPath of files) {
+    const filename = path.basename(inputPath);
+    spinner.text = `Processing ${processed + 1} / ${files.length}  —  ${filename}`;
+
+    try {
+      const buf        = await normalizeToCell(inputPath, size);
+      const outputPath = path.join(outputDir, filename);
+      await sharp(buf).toFile(outputPath);
+      processed++;
+    } catch (err) {
+      failed++;
+      errors.push({ filename, message: err.message });
+    }
+  }
+
+  if (failed === 0) {
+    spinner.succeed(chalk.green(`Done! ${processed} sprite${processed !== 1 ? 's' : ''} normalized.`));
+  } else {
+    spinner.warn(chalk.yellow(`Finished with ${failed} error${failed !== 1 ? 's' : ''}.`));
+    for (const { filename, message } of errors) {
+      console.log(chalk.red(`  ✖ ${filename}: `) + chalk.gray(message));
+    }
+  }
+
+  console.log(
+    chalk.gray('\n  Output : ') + chalk.white(outputDir) +
+    chalk.gray('\n  Size   : ') + chalk.white(`${size}×${size}px`) +
+    chalk.gray('\n  Files  : ') + chalk.white(`${processed} processed`) +
+    (failed > 0 ? chalk.red(`, ${failed} failed`) : '') + '\n'
+  );
+}

package/src/help.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+
+export function showHelp() {
+  console.log(`
+${chalk.bold.green('SpriteMint')} ${chalk.gray('— Unity Sprite Processor')}
+
+${chalk.bold('USAGE')}
+  ${chalk.cyan('spritemint')}           Interactive mode (main menu)
+  ${chalk.cyan('spritemint --help')}    Show this help message
+  ${chalk.cyan('spritemint -h')}        Show this help message
+
+${chalk.bold('COMMANDS')} ${chalk.gray('(selected interactively)')}
+
+  ${chalk.yellow('1. Normalize Sprites')}
+     PNG dosyalarını kare canvas'a sığdırır.
+     Aspect ratio korunur, şeffaf padding eklenir.
+     Çıktı: ${chalk.gray('<klasör>/normalized/')}
+
+  ${chalk.yellow('2. Extract Sprites from Sheet & Build Horizontal Output')}
+     Grid tabanlı sprite sheet'ten kareleri çıkarır,
+     normalize eder ve yatay bir animasyon strip'i oluşturur.
+     Çıktı: ${chalk.gray('<klasör>/output_horizontal.png')}
+
+  ${chalk.yellow('3. Build Sprite Sheet from Selected PNGs')}
+     Birden fazla PNG dosyasını seçerek yeni bir sprite sheet'e
+     birleştirir. Yatay strip veya grid layout seçilebilir.
+     Çıktı: ${chalk.gray('<klasör>/spritesheet_output.png')}
+
+${chalk.bold('REQUIREMENTS')}
+  - PNG formatında görsel dosyalar
+  - Node.js v18+
+
+${chalk.bold('EXAMPLES')}
+  ${chalk.gray('# Aracı başlat ve interaktif menüden seç')}
+  ${chalk.cyan('spritemint')}
+
+  ${chalk.gray('# Yardım mesajını göster')}
+  ${chalk.cyan('spritemint --help')}
+
+${chalk.bold('LINKS')}
+  GitHub   ${chalk.underline('https://github.com/rakaya07/spritemint')}
+  License  MIT
+`);
+}

package/src/index.js

@@ -0,0 +1,41 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { runNormalize } from './commands/normalize.js';
+import { runExtractHorizontal } from './commands/extractHorizontal.js';
+import { runBuildSheet } from './commands/buildSheet.js';
+
+const MENU_CHOICES = {
+  NORMALIZE:         'Normalize Sprites',
+  EXTRACT_HORIZONTAL:'Extract Sprites from Sheet and Build Horizontal Output',
+  BUILD_SHEET:       'Build Sprite Sheet from Selected PNGs',
+};
+
+async function main() {
+  console.log(chalk.bold.green('\n  SpriteMint ') + chalk.gray('— Unity Sprite Processor\n'));
+
+  const { action } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: 'What do you want to do?',
+      choices: Object.values(MENU_CHOICES),
+    },
+  ]);
+
+  switch (action) {
+    case MENU_CHOICES.NORMALIZE:
+      await runNormalize();
+      break;
+    case MENU_CHOICES.EXTRACT_HORIZONTAL:
+      await runExtractHorizontal();
+      break;
+    case MENU_CHOICES.BUILD_SHEET:
+      await runBuildSheet();
+      break;
+  }
+}
+
+main().catch((err) => {
+  console.error(chalk.red('\nError: ') + err.message);
+  process.exit(1);
+});

package/src/utils/folder.js

@@ -0,0 +1,155 @@
+import fs from 'fs';
+import path from 'path';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+
+const CURRENT_DIR  = 'Use current folder';
+const MANUAL_ENTRY = 'Enter path manually';
+
+/**
+ * Presents a list of folders containing PNG files and returns the chosen path.
+ * Checks process.cwd() and its immediate subdirectories.
+ *
+ * @returns {Promise<string>} Absolute path of the chosen folder.
+ */
+export async function selectFolder() {
+  const cwd        = process.cwd();
+  const cwdHasPngs = dirContainsPngs(cwd);
+  const subfolders = subdirectoriesWithPngs(cwd);
+
+  if (!cwdHasPngs && subfolders.length === 0) return promptManualPath();
+
+  const choices = [
+    ...(cwdHasPngs ? [CURRENT_DIR] : []),
+    ...subfolders,
+    new inquirer.Separator(),
+    MANUAL_ENTRY,
+  ];
+
+  const { selected } = await inquirer.prompt([
+    {
+      type:    'list',
+      name:    'selected',
+      message: 'Select folder containing PNG files:',
+      choices,
+    },
+  ]);
+
+  if (selected === MANUAL_ENTRY) return promptManualPath();
+  if (selected === CURRENT_DIR)  return cwd;
+  return path.join(cwd, selected);
+}
+
+/**
+ * Presents a list of PNG files from process.cwd() and its immediate
+ * subdirectories, then returns the absolute path of the chosen file.
+ *
+ * @returns {Promise<string>} Absolute path of the chosen PNG file.
+ */
+export async function selectPngFile() {
+  const cwd      = process.cwd();
+  const allFiles = [];
+
+  getPngsInDir(cwd).forEach((f) =>
+    allFiles.push({ name: f, value: path.join(cwd, f) })
+  );
+
+  for (const dir of subdirectoriesWithPngs(cwd)) {
+    getPngsInDir(path.join(cwd, dir)).forEach((f) =>
+      allFiles.push({ name: path.join(dir, f), value: path.join(cwd, dir, f) })
+    );
+  }
+
+  if (allFiles.length === 0) {
+    console.log(chalk.yellow('  No PNG files found in current directory or subfolders.\n'));
+    const { manualPath } = await inquirer.prompt([
+      {
+        type:     'input',
+        name:     'manualPath',
+        message:  'Input PNG file path:',
+        validate: (input) => input.trim().length > 0 || 'Please enter a file path.',
+      },
+    ]);
+    return manualPath.trim();
+  }
+
+  const { selected } = await inquirer.prompt([
+    {
+      type:    'list',
+      name:    'selected',
+      message: 'Select PNG file:',
+      choices: allFiles,
+    },
+  ]);
+
+  return selected;
+}
+
+/**
+ * Presents a checkbox list of PNG files in `folder` and returns
+ * the absolute paths of the selected files.
+ *
+ * @param {string} folder
+ * @param {string} [message]
+ * @returns {Promise<string[]>}
+ */
+export async function selectPngFiles(folder, message = 'Select PNG files (use space to select):') {
+  const pngNames = fs
+    .readdirSync(folder)
+    .filter((f) => f.toLowerCase().endsWith('.png'))
+    .sort();
+
+  const { selected } = await inquirer.prompt([
+    {
+      type:    'checkbox',
+      name:    'selected',
+      message,
+      choices: pngNames,
+    },
+  ]);
+
+  return selected.map((name) => path.join(folder, name));
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+export function dirContainsPngs(dir) {
+  try {
+    return fs.readdirSync(dir).some((f) => f.toLowerCase().endsWith('.png'));
+  } catch {
+    return false;
+  }
+}
+
+function subdirectoriesWithPngs(dir) {
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .filter((name) => dirContainsPngs(path.join(dir, name)));
+  } catch {
+    return [];
+  }
+}
+
+function getPngsInDir(dir) {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.png')).sort();
+  } catch {
+    return [];
+  }
+}
+
+async function promptManualPath() {
+  console.log(chalk.yellow('  No PNG files found in current directory or subfolders.\n'));
+  const { manualPath } = await inquirer.prompt([
+    {
+      type:     'input',
+      name:     'manualPath',
+      message:  'Path to folder containing PNG files:',
+      validate: (input) => input.trim().length > 0 || 'Please enter a folder path.',
+    },
+  ]);
+  return manualPath.trim();
+}

package/src/utils/image.js

@@ -0,0 +1,125 @@
+import sharp from 'sharp';
+
+export const SIZE_CHOICES = {
+  S256:   '256',
+  S512:   '512',
+  S1024:  '1024',
+  CUSTOM: 'Custom size',
+};
+
+/**
+ * Returns true if the file extension is a supported image type.
+ * @param {string} filename
+ * @returns {boolean}
+ */
+export function isSupportedImage(filename) {
+  return /\.(png|jpg|jpeg|webp)$/i.test(filename);
+}
+
+/**
+ * Clamps a number between min and max.
+ * @param {number} value
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Trims transparent edges, resizes to fit inside `cellSize` (preserving aspect
+ * ratio, never upscaling), centers on a transparent square canvas, and returns
+ * the result as a PNG Buffer.
+ *
+ * @param {string|Buffer} input - File path or raw PNG buffer.
+ * @param {number}        cellSize
+ * @returns {Promise<Buffer>}
+ */
+export async function normalizeToCell(input, cellSize) {
+  const trimmed = await sharp(input).trim().png().toBuffer();
+  const { width: trimW, height: trimH } = await sharp(trimmed).metadata();
+
+  const scale    = Math.min(cellSize / trimW, cellSize / trimH, 1);
+  const resizedW = Math.round(trimW * scale);
+  const resizedH = Math.round(trimH * scale);
+
+  const resized = await sharp(trimmed)
+    .resize(resizedW, resizedH, { fit: 'fill' })
+    .png()
+    .toBuffer();
+
+  const left = Math.floor((cellSize - resizedW) / 2);
+  const top  = Math.floor((cellSize - resizedH) / 2);
+
+  return sharp({
+    create: {
+      width:      cellSize,
+      height:     cellSize,
+      channels:   4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    },
+  })
+    .png()
+    .composite([{ input: resized, left, top }])
+    .toBuffer();
+}
+
+/**
+ * Attempts to auto-detect the grid layout of a sprite sheet by finding common
+ * row/column combinations where each cell has power-of-two dimensions.
+ * Falls back to any combination that produces square cells.
+ * Returns null if no suitable grid is found.
+ *
+ * @param {number} imageWidth
+ * @param {number} imageHeight
+ * @returns {{ rows: number, cols: number } | null}
+ */
+export function autoDetectGrid(imageWidth, imageHeight) {
+  // Exclude [1,1] — a single-cell "grid" is never a useful sprite sheet
+  const candidates = [
+    [1, 2], [2, 1], [2, 2],
+    [1, 4], [4, 1], [2, 4], [4, 2], [4, 4],
+    [1, 8], [8, 1], [2, 8], [8, 2], [4, 8], [8, 4], [8, 8],
+  ];
+
+  // Collect all candidates where both cell dimensions are powers of two
+  const valid = [];
+  for (const [rows, cols] of candidates) {
+    const cellW = imageWidth  / cols;
+    const cellH = imageHeight / rows;
+    if (
+      Number.isInteger(cellW) && Number.isInteger(cellH) &&
+      isPowerOfTwo(cellW) && isPowerOfTwo(cellH)
+    ) {
+      valid.push({ rows, cols, cellW, cellH });
+    }
+  }
+
+  if (valid.length > 0) {
+    // Prefer: 1) most square cell (aspect ratio closest to 1:1)
+    //         2) fewest cells (simplest grid)
+    valid.sort((a, b) => {
+      const ratioA = Math.max(a.cellW, a.cellH) / Math.min(a.cellW, a.cellH);
+      const ratioB = Math.max(b.cellW, b.cellH) / Math.min(b.cellW, b.cellH);
+      if (ratioA !== ratioB) return ratioA - ratioB;
+      return (a.rows * a.cols) - (b.rows * b.cols);
+    });
+    return { rows: valid[0].rows, cols: valid[0].cols };
+  }
+
+  // Fallback: any integer division producing square cells
+  for (const [rows, cols] of candidates) {
+    const cellW = imageWidth  / cols;
+    const cellH = imageHeight / rows;
+    if (Number.isInteger(cellW) && Number.isInteger(cellH) && cellW === cellH) {
+      return { rows, cols };
+    }
+  }
+
+  return null;
+}
+
+function isPowerOfTwo(n) {
+  return n > 0 && (n & (n - 1)) === 0;
+}