ruby_spriter 0.6.6 → 0.6.7

data/spec/ruby_spriter/compression_manager_spec.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubySpriter::CompressionManager do
+  let(:input_file) { 'E:/test/input.png' }
+  let(:output_file) { 'E:/test/output.png' }
+  let(:temp_file) { 'E:/test/temp.png' }
+
+  before do
+    allow(File).to receive(:exist?).and_return(true)
+    allow(File).to receive(:readable?).and_return(true)
+    allow(File).to receive(:size).with(input_file).and_return(100000)
+    allow(File).to receive(:size).with(output_file).and_return(80000)
+    allow(RubySpriter::Utils::FileHelper).to receive(:validate_readable!)
+    allow(RubySpriter::Utils::FileHelper).to receive(:validate_exists!)
+  end
+
+  describe '.compress' do
+    it 'compresses PNG file using ImageMagick' do
+      magick_cmd = RubySpriter::Platform.imagemagick_convert_cmd
+
+      expect(Open3).to receive(:capture3) do |cmd|
+        expect(cmd).to include(magick_cmd.split.first)  # Check for 'convert' or 'magick'
+        expect(cmd).to include(input_file)
+        expect(cmd).to include(output_file)
+        expect(cmd).to include('-strip')
+        expect(cmd).to include('-define png:compression-level=9')
+        expect(cmd).to include('-define png:compression-filter=5')
+        expect(cmd).to include('-define png:compression-strategy=1')
+        ['', '', double(success?: true)]
+      end
+
+      described_class.compress(input_file, output_file)
+    end
+
+    it 'raises error if compression fails' do
+      allow(Open3).to receive(:capture3).and_return(['', 'error', double(success?: false)])
+
+      expect {
+        described_class.compress(input_file, output_file)
+      }.to raise_error(RubySpriter::ProcessingError, /Failed to compress/)
+    end
+
+    it 'validates input file exists and is readable' do
+      expect(RubySpriter::Utils::FileHelper).to receive(:validate_readable!).with(input_file)
+
+      allow(Open3).to receive(:capture3).and_return(['', '', double(success?: true)])
+
+      described_class.compress(input_file, output_file)
+    end
+
+    it 'validates output file was created' do
+      allow(Open3).to receive(:capture3).and_return(['', '', double(success?: true)])
+      expect(RubySpriter::Utils::FileHelper).to receive(:validate_exists!).with(output_file)
+
+      described_class.compress(input_file, output_file)
+    end
+  end
+
+  describe '.compress_with_metadata' do
+    let(:metadata) { { columns: 4, rows: 4, frames: 16 } }
+
+    before do
+      allow(RubySpriter::MetadataManager).to receive(:read).and_return(metadata)
+      allow(RubySpriter::MetadataManager).to receive(:embed)
+      allow(FileUtils).to receive(:mv)
+      allow(File).to receive(:exist?).with(temp_file).and_return(true)
+      allow(FileUtils).to receive(:rm_f)
+    end
+
+    it 'reads metadata before compression' do
+      expect(RubySpriter::MetadataManager).to receive(:read).with(input_file)
+
+      allow(Open3).to receive(:capture3).and_return(['', '', double(success?: true)])
+
+      described_class.compress_with_metadata(input_file, output_file)
+    end
+
+    it 'compresses file with metadata preservation' do
+      allow(Open3).to receive(:capture3).and_return(['', '', double(success?: true)])
+
+      expect(described_class).to receive(:compress).with(input_file, anything, debug: false)
+      expect(RubySpriter::MetadataManager).to receive(:embed)
+
+      described_class.compress_with_metadata(input_file, output_file)
+    end
+
+    it 're-embeds metadata after compression' do
+      allow(Open3).to receive(:capture3).and_return(['', '', double(success?: true)])
+
+      expect(RubySpriter::MetadataManager).to receive(:embed) do |temp, output, **opts|
+        expect(opts[:columns]).to eq(4)
+        expect(opts[:rows]).to eq(4)
+        expect(opts[:frames]).to eq(16)
+      end
+
+      described_class.compress_with_metadata(input_file, output_file)
+    end
+
+    it 'handles files without metadata' do
+      allow(RubySpriter::MetadataManager).to receive(:read).and_return(nil)
+      allow(Open3).to receive(:capture3).and_return(['', '', double(success?: true)])
+
+      # Should just compress without re-embedding metadata
+      expect(RubySpriter::MetadataManager).not_to receive(:embed)
+
+      described_class.compress_with_metadata(input_file, output_file)
+    end
+
+    it 'cleans up temp file after successful compression' do
+      allow(Open3).to receive(:capture3).and_return(['', '', double(success?: true)])
+      allow(RubySpriter::MetadataManager).to receive(:read).and_return(metadata)
+      allow(RubySpriter::MetadataManager).to receive(:embed)
+
+      # Simulate temp file creation
+      temp_path = nil
+      allow(described_class).to receive(:compress) do |input, output|
+        temp_path = output
+      end
+
+      expect(FileUtils).to receive(:rm_f).with(anything)
+
+      described_class.compress_with_metadata(input_file, output_file)
+    end
+  end
+
+  describe '.compression_stats' do
+    it 'returns compression statistics' do
+      original_size = 100000
+      compressed_size = 80000
+
+      allow(File).to receive(:size).with(input_file).and_return(original_size)
+      allow(File).to receive(:size).with(output_file).and_return(compressed_size)
+
+      stats = described_class.compression_stats(input_file, output_file)
+
+      expect(stats[:original_size]).to eq(original_size)
+      expect(stats[:compressed_size]).to eq(compressed_size)
+      expect(stats[:saved_bytes]).to eq(20000)
+      expect(stats[:reduction_percent]).to be_within(0.1).of(20.0)
+    end
+
+    it 'handles case where compressed file is larger' do
+      original_size = 100000
+      compressed_size = 120000
+
+      allow(File).to receive(:size).with(input_file).and_return(original_size)
+      allow(File).to receive(:size).with(output_file).and_return(compressed_size)
+
+      stats = described_class.compression_stats(input_file, output_file)
+
+      expect(stats[:saved_bytes]).to eq(-20000)
+      expect(stats[:reduction_percent]).to be_within(0.1).of(-20.0)
+    end
+  end
+end

data/spec/ruby_spriter/consolidator_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'securerandom'
 
 RSpec.describe RubySpriter::Consolidator do
   let(:spritesheet1) { File.join(__dir__, '..', 'fixtures', 'spritesheet_4x2.png') }
@@ -372,4 +373,166 @@ RSpec.describe RubySpriter::Consolidator do
       end
     end
   end
+
+  describe '#find_spritesheets_in_directory' do
+    let(:consolidator) { described_class.new }
+    let(:image_without_meta) { File.join(__dir__, '..', 'fixtures', 'image_without_metadata.png') }
+
+    # Helper to create a unique test directory for each test
+    def create_test_dir
+      dir = File.join($test_temp_dir, "consolidate_test_#{SecureRandom.hex(8)}")
+      FileUtils.mkdir_p(dir)
+      dir
+    end
+
+    it 'finds all PNG files with metadata in directory' do
+      test_dir = create_test_dir
+      # Copy spritesheets with metadata to test directory
+      sprite1_path = File.join(test_dir, 'sprite1.png')
+      sprite2_path = File.join(test_dir, 'sprite2.png')
+      FileUtils.cp(spritesheet1, sprite1_path)
+      FileUtils.cp(spritesheet2, sprite2_path)
+
+      # Mock metadata reading to return valid metadata for these files
+      allow(RubySpriter::MetadataManager).to receive(:read).and_call_original
+      allow(RubySpriter::MetadataManager).to receive(:read).with(sprite1_path).and_return(
+        { columns: 2, rows: 2, frames: 4, version: '0.6' }
+      )
+      allow(RubySpriter::MetadataManager).to receive(:read).with(sprite2_path).and_return(
+        { columns: 2, rows: 3, frames: 6, version: '0.6' }
+      )
+
+      found_files = consolidator.find_spritesheets_in_directory(test_dir)
+
+      expect(found_files.length).to eq(2)
+      expect(found_files).to include(sprite1_path)
+      expect(found_files).to include(sprite2_path)
+    end
+
+    it 'excludes PNG files without metadata' do
+      test_dir = create_test_dir
+      # Copy two spritesheets with metadata and one image without
+      sprite1_path = File.join(test_dir, 'sprite1.png')
+      sprite2_path = File.join(test_dir, 'sprite2.png')
+      no_meta_path = File.join(test_dir, 'no_meta.png')
+      FileUtils.cp(spritesheet1, sprite1_path)
+      FileUtils.cp(spritesheet2, sprite2_path)
+      FileUtils.cp(image_without_meta, no_meta_path)
+
+      # Mock metadata reading
+      allow(RubySpriter::MetadataManager).to receive(:read).and_call_original
+      allow(RubySpriter::MetadataManager).to receive(:read).with(sprite1_path).and_return(
+        { columns: 2, rows: 2, frames: 4, version: '0.6' }
+      )
+      allow(RubySpriter::MetadataManager).to receive(:read).with(sprite2_path).and_return(
+        { columns: 2, rows: 3, frames: 6, version: '0.6' }
+      )
+      allow(RubySpriter::MetadataManager).to receive(:read).with(no_meta_path).and_return(nil)
+
+      found_files = consolidator.find_spritesheets_in_directory(test_dir)
+
+      expect(found_files.length).to eq(2)
+      expect(found_files).to include(sprite1_path)
+      expect(found_files).to include(sprite2_path)
+      expect(found_files).not_to include(no_meta_path)
+    end
+
+    it 'returns files sorted alphabetically' do
+      test_dir = create_test_dir
+      # Copy spritesheets with names that test alphabetical sorting
+      c_sprite_path = File.join(test_dir, 'c_sprite.png')
+      a_sprite_path = File.join(test_dir, 'a_sprite.png')
+      b_sprite_path = File.join(test_dir, 'b_sprite.png')
+      FileUtils.cp(spritesheet1, c_sprite_path)
+      FileUtils.cp(spritesheet2, a_sprite_path)
+      FileUtils.cp(spritesheet3, b_sprite_path)
+
+      # Mock metadata reading
+      allow(RubySpriter::MetadataManager).to receive(:read).and_call_original
+      allow(RubySpriter::MetadataManager).to receive(:read).with(c_sprite_path).and_return(
+        { columns: 4, rows: 1, frames: 4, version: '0.6' }
+      )
+      allow(RubySpriter::MetadataManager).to receive(:read).with(a_sprite_path).and_return(
+        { columns: 2, rows: 3, frames: 6, version: '0.6' }
+      )
+      allow(RubySpriter::MetadataManager).to receive(:read).with(b_sprite_path).and_return(
+        { columns: 4, rows: 4, frames: 16, version: '0.6' }
+      )
+
+      found_files = consolidator.find_spritesheets_in_directory(test_dir)
+
+      expect(found_files.length).to eq(3)
+      expect(found_files[0]).to end_with('a_sprite.png')
+      expect(found_files[1]).to end_with('b_sprite.png')
+      expect(found_files[2]).to end_with('c_sprite.png')
+    end
+
+    it 'raises error when directory does not exist' do
+      expect {
+        consolidator.find_spritesheets_in_directory('nonexistent_directory')
+      }.to raise_error(RubySpriter::ValidationError, /Directory not found/)
+    end
+
+    it 'raises error when no PNG files with metadata found' do
+      # Create empty directory
+      empty_dir = File.join($test_temp_dir, 'empty_dir')
+      FileUtils.mkdir_p(empty_dir)
+
+      expect {
+        consolidator.find_spritesheets_in_directory(empty_dir)
+      }.to raise_error(RubySpriter::ValidationError, /No PNG files with spritesheet metadata found/)
+    end
+
+    it 'raises error when directory has PNGs but none with metadata' do
+      test_dir = create_test_dir
+      # Copy only image without metadata
+      FileUtils.cp(image_without_meta, File.join(test_dir, 'no_meta.png'))
+
+      expect {
+        consolidator.find_spritesheets_in_directory(test_dir)
+      }.to raise_error(RubySpriter::ValidationError, /No PNG files with spritesheet metadata found/)
+    end
+
+    it 'handles directory with mixed file types' do
+      test_dir = create_test_dir
+      # Copy spritesheets and create non-PNG files
+      sprite1_path = File.join(test_dir, 'sprite1.png')
+      sprite2_path = File.join(test_dir, 'sprite2.png')
+      FileUtils.cp(spritesheet1, sprite1_path)
+      FileUtils.cp(spritesheet2, sprite2_path)
+      File.write(File.join(test_dir, 'readme.txt'), 'test')
+      File.write(File.join(test_dir, 'data.json'), '{}')
+
+      # Mock metadata reading
+      allow(RubySpriter::MetadataManager).to receive(:read).and_call_original
+      allow(RubySpriter::MetadataManager).to receive(:read).with(sprite1_path).and_return(
+        { columns: 2, rows: 2, frames: 4, version: '0.6' }
+      )
+      allow(RubySpriter::MetadataManager).to receive(:read).with(sprite2_path).and_return(
+        { columns: 2, rows: 3, frames: 6, version: '0.6' }
+      )
+
+      found_files = consolidator.find_spritesheets_in_directory(test_dir)
+
+      expect(found_files.length).to eq(2)
+      expect(found_files).to all(end_with('.png'))
+    end
+
+    it 'requires at least 2 spritesheets' do
+      test_dir = create_test_dir
+      # Copy only one spritesheet
+      sprite1_path = File.join(test_dir, 'sprite1.png')
+      FileUtils.cp(spritesheet1, sprite1_path)
+
+      # Mock metadata reading
+      allow(RubySpriter::MetadataManager).to receive(:read).and_call_original
+      allow(RubySpriter::MetadataManager).to receive(:read).with(sprite1_path).and_return(
+        { columns: 2, rows: 2, frames: 4, version: '0.6' }
+      )
+
+      expect {
+        consolidator.find_spritesheets_in_directory(test_dir)
+      }.to raise_error(RubySpriter::ValidationError, /Found only 1 spritesheet, need at least 2/)
+    end
+  end
 end

data/spec/ruby_spriter/processor_spec.rb

@@ -204,6 +204,356 @@ RSpec.describe RubySpriter::Processor do
     end
   end
 
+  describe '--extract validation' do
+    let(:temp_image) { File.join(Dir.mktmpdir, 'test.png') }
+
+    before do
+      FileUtils.touch(temp_image)
+
+      allow_any_instance_of(RubySpriter::DependencyChecker).to receive(:check_all).and_return({
+        ffmpeg: { available: true },
+        ffprobe: { available: true },
+        imagemagick: { available: true },
+        gimp: { available: true }
+      })
+    end
+
+    after do
+      FileUtils.rm_f(temp_image)
+    end
+
+    describe 'format validation' do
+      it 'raises error for invalid extract format (non-numeric)' do
+        expect {
+          described_class.new(image: temp_image, extract: '1,a,3')
+        }.to raise_error(RubySpriter::ValidationError, /Invalid --extract format/)
+      end
+
+      it 'raises error for invalid extract format (empty)' do
+        expect {
+          described_class.new(image: temp_image, extract: '')
+        }.to raise_error(RubySpriter::ValidationError, /Invalid --extract format/)
+      end
+
+      it 'raises error for invalid extract format (spaces)' do
+        expect {
+          described_class.new(image: temp_image, extract: '1, 2, 3')
+        }.to raise_error(RubySpriter::ValidationError, /Invalid --extract format/)
+      end
+
+      it 'accepts valid comma-separated frame numbers' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+
+        expect {
+          described_class.new(image: temp_image, extract: '1,2,4,5,8')
+        }.not_to raise_error
+      end
+    end
+
+    describe 'minimum frames validation' do
+      it 'raises error when less than 2 frames requested' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+
+        expect {
+          described_class.new(image: temp_image, extract: '1')
+        }.to raise_error(RubySpriter::ValidationError, /--extract requires at least 2 frames/)
+      end
+
+      it 'allows exactly 2 frames' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+
+        expect {
+          described_class.new(image: temp_image, extract: '1,2')
+        }.not_to raise_error
+      end
+    end
+
+    describe 'frame number validation' do
+      it 'raises error when frame number is 0' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+
+        expect {
+          described_class.new(image: temp_image, extract: '0,1,2')
+        }.to raise_error(RubySpriter::ValidationError, /Frame numbers must be 1-indexed/)
+      end
+
+      it 'raises error when frame number is negative' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+
+        expect {
+          described_class.new(image: temp_image, extract: '1,-2,3')
+        }.to raise_error(RubySpriter::ValidationError, /Frame numbers must be 1-indexed/)
+      end
+
+      it 'allows duplicate frame numbers' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+
+        expect {
+          described_class.new(image: temp_image, extract: '1,1,2,2,3,3')
+        }.not_to raise_error
+      end
+    end
+
+    describe 'metadata requirement' do
+      it 'raises error when image has no metadata' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return(nil)
+
+        expect {
+          described_class.new(image: temp_image, extract: '1,2,3')
+        }.to raise_error(RubySpriter::ValidationError, /Image has no metadata.*Cannot extract frames/)
+      end
+    end
+
+    describe 'out of bounds validation' do
+      before do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+      end
+
+      it 'raises error when frame number exceeds total frames' do
+        expect {
+          described_class.new(image: temp_image, extract: '1,2,17')
+        }.to raise_error(RubySpriter::ValidationError, /Frame 17 is out of bounds.*only has 16 frames/)
+      end
+
+      it 'allows frame number equal to total frames' do
+        expect {
+          described_class.new(image: temp_image, extract: '1,2,16')
+        }.not_to raise_error
+      end
+
+      it 'raises error for multiple out of bounds frames' do
+        expect {
+          described_class.new(image: temp_image, extract: '1,20,25')
+        }.to raise_error(RubySpriter::ValidationError, /Frame 20 is out of bounds/)
+      end
+    end
+
+    describe '--columns default' do
+      before do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+      end
+
+      it 'defaults to 4 columns when not specified' do
+        processor = described_class.new(image: temp_image, extract: '1,2,3,4')
+        expect(processor.instance_variable_get(:@options)[:columns]).to eq(4)
+      end
+
+      it 'uses specified columns when provided' do
+        processor = described_class.new(image: temp_image, extract: '1,2,3', columns: 3)
+        expect(processor.instance_variable_get(:@options)[:columns]).to eq(3)
+      end
+    end
+  end
+
+  describe '--add-meta validation' do
+    let(:temp_image) { File.join(Dir.mktmpdir, 'test.png') }
+
+    before do
+      FileUtils.touch(temp_image)
+
+      allow_any_instance_of(RubySpriter::DependencyChecker).to receive(:check_all).and_return({
+        ffmpeg: { available: true },
+        ffprobe: { available: true },
+        imagemagick: { available: true },
+        gimp: { available: true }
+      })
+    end
+
+    after do
+      FileUtils.rm_f(temp_image)
+    end
+
+    describe 'format validation' do
+      it 'raises error for invalid format (missing colon)' do
+        expect {
+          described_class.new(image: temp_image, add_meta: '44')
+        }.to raise_error(RubySpriter::ValidationError, /Invalid --add-meta format/)
+      end
+
+      it 'raises error for invalid format (non-numeric rows)' do
+        expect {
+          described_class.new(image: temp_image, add_meta: 'a:4')
+        }.to raise_error(RubySpriter::ValidationError, /Invalid --add-meta format/)
+      end
+
+      it 'raises error for invalid format (non-numeric columns)' do
+        expect {
+          described_class.new(image: temp_image, add_meta: '4:b')
+        }.to raise_error(RubySpriter::ValidationError, /Invalid --add-meta format/)
+      end
+
+      it 'accepts valid R:C format' do
+        # Mock ImageMagick identify for dimension validation
+        allow(Open3).to receive(:capture3).with(/identify/).and_return(
+          ["800x800\n", '', instance_double(Process::Status, success?: true)]
+        )
+
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return(nil)
+
+        expect {
+          described_class.new(image: temp_image, add_meta: '4:4')
+        }.not_to raise_error
+      end
+    end
+
+    describe 'range validation' do
+      it 'raises error when rows is below minimum (0)' do
+        expect {
+          described_class.new(image: temp_image, add_meta: '0:4')
+        }.to raise_error(RubySpriter::ValidationError, /rows must be between 1 and 99/)
+      end
+
+      it 'raises error when columns is below minimum (0)' do
+        expect {
+          described_class.new(image: temp_image, add_meta: '4:0')
+        }.to raise_error(RubySpriter::ValidationError, /columns must be between 1 and 99/)
+      end
+
+      it 'raises error when rows exceeds maximum (100)' do
+        expect {
+          described_class.new(image: temp_image, add_meta: '100:4')
+        }.to raise_error(RubySpriter::ValidationError, /rows must be between 1 and 99/)
+      end
+
+      it 'raises error when total frames exceeds 999' do
+        expect {
+          described_class.new(image: temp_image, add_meta: '20:50')
+        }.to raise_error(RubySpriter::ValidationError, /Total frames \(1000\) must be less than 1000/)
+      end
+
+      it 'allows maximum valid frames (999)' do
+        # Mock ImageMagick identify - 3700x2700 divides evenly by 27 rows x 37 columns (100x100 per frame)
+        allow(Open3).to receive(:capture3).with(/identify/).and_return(
+          ["3700x2700\n", '', instance_double(Process::Status, success?: true)]
+        )
+
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return(nil)
+
+        expect {
+          described_class.new(image: temp_image, add_meta: '27:37')
+        }.not_to raise_error
+      end
+    end
+
+    describe 'existing metadata handling' do
+      it 'raises error when image already has metadata' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+
+        expect {
+          described_class.new(image: temp_image, add_meta: '4:4')
+        }.to raise_error(RubySpriter::ValidationError, /Image already has spritesheet metadata.*Use --overwrite-meta/)
+      end
+
+      it 'allows replacing metadata with --overwrite-meta' do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return({
+          columns: 4,
+          rows: 4,
+          frames: 16
+        })
+
+        # Mock ImageMagick identify
+        allow(Open3).to receive(:capture3).with(/identify/).and_return(
+          ["800x800\n", '', instance_double(Process::Status, success?: true)]
+        )
+
+        expect {
+          described_class.new(image: temp_image, add_meta: '8:8', overwrite_meta: true)
+        }.not_to raise_error
+      end
+    end
+
+    describe 'dimension validation' do
+      before do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return(nil)
+      end
+
+      it 'raises error when image dimensions do not divide evenly' do
+        # Mock ImageMagick identify - 800x600 doesn't divide by 3x3
+        allow(Open3).to receive(:capture3).with(/identify/).and_return(
+          ["800x600\n", '', instance_double(Process::Status, success?: true)]
+        )
+
+        expect {
+          described_class.new(image: temp_image, add_meta: '3:3')
+        }.to raise_error(RubySpriter::ValidationError, /Image dimensions \(800x600\) must divide evenly by grid \(3x3\)/)
+      end
+
+      it 'allows dimensions that divide evenly' do
+        # Mock ImageMagick identify - 800x800 divides by 4x4
+        allow(Open3).to receive(:capture3).with(/identify/).and_return(
+          ["800x800\n", '', instance_double(Process::Status, success?: true)]
+        )
+
+        expect {
+          described_class.new(image: temp_image, add_meta: '4:4')
+        }.not_to raise_error
+      end
+    end
+
+    describe 'frame count handling' do
+      before do
+        allow(RubySpriter::MetadataManager).to receive(:read).with(temp_image).and_return(nil)
+        allow(Open3).to receive(:capture3).with(/identify/).and_return(
+          ["800x800\n", '', instance_double(Process::Status, success?: true)]
+        )
+      end
+
+      it 'calculates frame count from rows * columns by default' do
+        processor = described_class.new(image: temp_image, add_meta: '4:4')
+        # Frame count should be 16 (4x4)
+        # We'll verify this in the workflow implementation
+        expect(processor.instance_variable_get(:@options)[:add_meta]).to eq('4:4')
+      end
+
+      it 'allows custom frame count with --frames for partial grids' do
+        processor = described_class.new(image: temp_image, add_meta: '4:4', frame_count: 14)
+        expect(processor.instance_variable_get(:@options)[:frame_count]).to eq(14)
+      end
+
+      it 'raises error when custom frame count exceeds grid size' do
+        expect {
+          described_class.new(image: temp_image, add_meta: '4:4', frame_count: 20)
+        }.to raise_error(RubySpriter::ValidationError, /Frame count \(20\) exceeds grid size \(16\)/)
+      end
+    end
+  end
+
   describe '--split metadata priority logic' do
     let(:temp_dir) { Dir.mktmpdir('test_split_') }
     let(:image_file) { File.join(temp_dir, 'spritesheet.png') }