From 71c44aa81bcc33ee9c7984608fe3897f1e98f85a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Nov 2025 05:56:52 +0000
Subject: [PATCH 01/10] feat: add bitmap (BMP) encoder for 24-bit RGB images

Add a library to export Aseprite RGB images as 24-bit BMP files. This
enables exporting images in the widely-supported bitmap format.

Features:
- Encodes Aseprite Image objects to BMP binary string
- Supports 24-bit RGB color mode only
- Proper BGR byte order conversion
- Bottom-to-top row ordering per BMP specification
- Automatic row padding to 4-byte boundaries
- Standard BMP file and info headers (14 + 40 bytes)

Implementation:
- src/pkg/bitmap/init.lua: Main BMP encoder with create() API
- src/pkg/bitmap/bitmap_test.lua: Comprehensive test suite
- src/pkg/asepriteUtil/mock.lua: Reusable Aseprite API mocks for testing

The bitmap encoder uses the little-endian pack functions added in PR #34
to generate proper BMP file structures.
---
 src/pkg/asepriteUtil/mock.lua  |  86 +++++++++++++++
 src/pkg/bitmap/bitmap_test.lua | 193 +++++++++++++++++++++++++++++++++
 src/pkg/bitmap/init.lua        |  91 ++++++++++++++++
 3 files changed, 370 insertions(+)
 create mode 100644 src/pkg/asepriteUtil/mock.lua
 create mode 100644 src/pkg/bitmap/bitmap_test.lua
 create mode 100644 src/pkg/bitmap/init.lua

diff --git a/src/pkg/asepriteUtil/mock.lua b/src/pkg/asepriteUtil/mock.lua
new file mode 100644
index 0000000..9d5300f
--- /dev/null
+++ b/src/pkg/asepriteUtil/mock.lua
@@ -0,0 +1,86 @@
+---Mock implementations of Aseprite APIs for testing
+---@module 'pkg.asepriteUtil.mock'
+
+---Mock ColorMode enum
+---@class ColorMode
+local ColorMode = {
+    RGB = 0,
+    GRAY = 1,
+    INDEXED = 2,
+}
+
+---Mock app.pixelColor API
+---RGBA format: R=bits[0-7], G=bits[8-15], B=bits[16-23], A=bits[24-31]
+local pixelColor = {
+    ---Constructs a 32-bit RGBA pixel value
+    ---@param r integer Red component (0-255)
+    ---@param g integer Green component (0-255)
+    ---@param b integer Blue component (0-255)
+    ---@param a? integer Alpha component (0-255), defaults to 255
+    ---@return integer
+    rgba = function (r, g, b, a)
+        a = a or 255
+        return r | (g << 8) | (b << 16) | (a << 24)
+    end,
+
+    ---Extracts red component from RGBA pixel
+    ---@param pixel integer
+    ---@return integer
+    rgbaR = function (pixel)
+        return pixel & 0xFF
+    end,
+
+    ---Extracts green component from RGBA pixel
+    ---@param pixel integer
+    ---@return integer
+    rgbaG = function (pixel)
+        return (pixel >> 8) & 0xFF
+    end,
+
+    ---Extracts blue component from RGBA pixel
+    ---@param pixel integer
+    ---@return integer
+    rgbaB = function (pixel)
+        return (pixel >> 16) & 0xFF
+    end,
+
+    ---Extracts alpha component from RGBA pixel
+    ---@param pixel integer
+    ---@return integer
+    rgbaA = function (pixel)
+        return (pixel >> 24) & 0xFF
+    end,
+}
+
+---Mock app object
+local app = {
+    pixelColor = pixelColor,
+}
+
+---Creates a mock Image object for testing
+---@param width integer Image width in pixels
+---@param height integer Image height in pixels
+---@param pixelData integer[] Array of RGBA pixel values (length = width * height)
+---@return table Mock Image object
+local function createImage (width, height, pixelData)
+    return {
+        width = width,
+        height = height,
+        colorMode = ColorMode.RGB,
+        bytesPerPixel = 4,
+        rowStride = width * 4,
+        ---Gets pixel at x,y coordinates
+        ---@param x integer
+        ---@param y integer
+        ---@return integer
+        getPixel = function (self, x, y)
+            return pixelData[y * width + x + 1]
+        end,
+    }
+end
+
+return {
+    ColorMode = ColorMode,
+    app = app,
+    createImage = createImage,
+}
diff --git a/src/pkg/bitmap/bitmap_test.lua b/src/pkg/bitmap/bitmap_test.lua
new file mode 100644
index 0000000..8c49e77
--- /dev/null
+++ b/src/pkg/bitmap/bitmap_test.lua
@@ -0,0 +1,193 @@
+local describe = require("lib.test").describe
+local expect = require("lib.test").expect
+local test = require("lib.test").test
+
+-- Set up mocks
+local mock = require("pkg.asepriteUtil.mock")
+_G.ColorMode = mock.ColorMode
+_G.app = mock.app
+
+local bitmap = require("pkg.bitmap")
+
+describe("bitmap", function ()
+    describe("create", function ()
+        test("creates valid BMP file header", function ()
+            local pixels = {
+                mock.app.pixelColor.rgba(255, 0, 0), -- Red
+            }
+            local image = mock.createImage(1, 1, pixels)
+            local bmp = bitmap.create(image)
+
+            -- Check BMP signature
+            expect(bmp:sub(1, 2)):toBe("BM")
+
+            -- File size: 54 (headers) + 4 (1 pixel * 3 bytes + 1 padding) = 58
+            local fileSize = string.unpack("<I4", bmp:sub(3, 6))
+            expect(fileSize):toBe(58)
+
+            -- Data offset should be 54
+            local dataOffset = string.unpack("<I4", bmp:sub(11, 14))
+            expect(dataOffset):toBe(54)
+        end)
+
+        test("creates valid bitmap info header", function ()
+            local pixels = { mock.app.pixelColor.rgba(0, 0, 0) }
+            local image = mock.createImage(1, 1, pixels)
+            local bmp = bitmap.create(image)
+
+            -- Info header starts at byte 15
+            local headerSize = string.unpack("<I4", bmp:sub(15, 18))
+            expect(headerSize):toBe(40)
+
+            local width = string.unpack("<i4", bmp:sub(19, 22))
+            expect(width):toBe(1)
+
+            local height = string.unpack("<i4", bmp:sub(23, 26))
+            expect(height):toBe(1)
+
+            local planes = string.unpack("<I2", bmp:sub(27, 28))
+            expect(planes):toBe(1)
+
+            local bitsPerPixel = string.unpack("<I2", bmp:sub(29, 30))
+            expect(bitsPerPixel):toBe(24)
+        end)
+
+        test("encodes pixels in BGR order", function ()
+            -- Create a 1x1 image with red pixel (R=255, G=0, B=0)
+            local pixels = {
+                mock.app.pixelColor.rgba(255, 0, 0),
+            }
+            local image = mock.createImage(1, 1, pixels)
+            local bmp = bitmap.create(image)
+
+            -- Pixel data starts at byte 55 (after 54-byte header)
+            -- BGR order: B=0, G=0, R=255
+            expect(bmp:sub(55, 55)):toBe("\x00") -- Blue
+            expect(bmp:sub(56, 56)):toBe("\x00") -- Green
+            expect(bmp:sub(57, 57)):toBe("\xFF") -- Red
+        end)
+
+        test("adds correct row padding for width=1", function ()
+            local pixels = { mock.app.pixelColor.rgba(0, 0, 0) }
+            local image = mock.createImage(1, 1, pixels)
+            local bmp = bitmap.create(image)
+
+            -- 1 pixel = 3 bytes, needs 1 byte padding to reach 4
+            -- Pixel data: 3 bytes + 1 padding = 4 bytes total
+            expect(#bmp):toBe(54 + 4)
+            expect(bmp:sub(58, 58)):toBe("\x00") -- Padding byte
+        end)
+
+        test("adds correct row padding for width=2", function ()
+            local pixels = {
+                mock.app.pixelColor.rgba(0, 0, 0),
+                mock.app.pixelColor.rgba(0, 0, 0),
+            }
+            local image = mock.createImage(2, 1, pixels)
+            local bmp = bitmap.create(image)
+
+            -- 2 pixels = 6 bytes, needs 2 bytes padding to reach 8
+            expect(#bmp):toBe(54 + 8)
+        end)
+
+        test("adds no padding for width=4", function ()
+            local pixels = {
+                mock.app.pixelColor.rgba(0, 0, 0),
+                mock.app.pixelColor.rgba(0, 0, 0),
+                mock.app.pixelColor.rgba(0, 0, 0),
+                mock.app.pixelColor.rgba(0, 0, 0),
+            }
+            local image = mock.createImage(4, 1, pixels)
+            local bmp = bitmap.create(image)
+
+            -- 4 pixels = 12 bytes, already aligned to 4, no padding needed
+            expect(#bmp):toBe(54 + 12)
+        end)
+
+        test("stores rows bottom-to-top", function ()
+            -- Create a 2x2 image:
+            -- Top row (y=0):    Red(255,0,0)    Green(0,255,0)
+            -- Bottom row (y=1): Blue(0,0,255)   White(255,255,255)
+            local pixels = {
+                mock.app.pixelColor.rgba(255, 0, 0), -- Top-left: Red
+                mock.app.pixelColor.rgba(0, 255, 0), -- Top-right: Green
+                mock.app.pixelColor.rgba(0, 0, 255), -- Bottom-left: Blue
+                mock.app.pixelColor.rgba(255, 255, 255), -- Bottom-right: White
+            }
+            local image = mock.createImage(2, 2, pixels)
+            local bmp = bitmap.create(image)
+
+            -- Pixel data starts at byte 55
+            -- First row in BMP should be bottom row (y=1): Blue, White
+            -- Blue in BGR: B=255, G=0, R=0
+            expect(bmp:sub(55, 55)):toBe("\xFF") -- Blue.B
+            expect(bmp:sub(56, 56)):toBe("\x00") -- Blue.G
+            expect(bmp:sub(57, 57)):toBe("\x00") -- Blue.R
+
+            -- White in BGR: B=255, G=255, R=255
+            expect(bmp:sub(58, 58)):toBe("\xFF") -- White.B
+            expect(bmp:sub(59, 59)):toBe("\xFF") -- White.G
+            expect(bmp:sub(60, 60)):toBe("\xFF") -- White.R
+
+            -- 2 pixels = 6 bytes, need 2 bytes padding
+            -- Second row in BMP should be top row (y=0): Red, Green
+            -- Red in BGR: B=0, G=0, R=255
+            expect(bmp:sub(63, 63)):toBe("\x00") -- Red.B
+            expect(bmp:sub(64, 64)):toBe("\x00") -- Red.G
+            expect(bmp:sub(65, 65)):toBe("\xFF") -- Red.R
+
+            -- Green in BGR: B=0, G=255, R=0
+            expect(bmp:sub(66, 66)):toBe("\x00") -- Green.B
+            expect(bmp:sub(67, 67)):toBe("\xFF") -- Green.G
+            expect(bmp:sub(68, 68)):toBe("\x00") -- Green.R
+        end)
+
+        test("handles 3x3 image correctly", function ()
+            -- Create a simple 3x3 image with all black pixels
+            local pixels = {}
+            for i = 1, 9 do
+                pixels[i] = mock.app.pixelColor.rgba(0, 0, 0)
+            end
+            local image = mock.createImage(3, 3, pixels)
+            local bmp = bitmap.create(image)
+
+            -- 3 pixels per row = 9 bytes, needs 3 bytes padding to reach 12
+            -- Total pixel data = (9 + 3) * 3 rows = 36 bytes
+            expect(#bmp):toBe(54 + 36)
+        end)
+
+        test("throws error for non-RGB image", function ()
+            local image = {
+                width = 1,
+                height = 1,
+                colorMode = mock.ColorMode.GRAY,
+                getPixel = function ()
+                    return 0
+                end,
+            }
+
+            local success, err = pcall(function ()
+                bitmap.create(image)
+            end)
+
+            expect(success):toBe(false)
+            expect(err:find("RGB")):toBeTruthy()
+        end)
+
+        test("creates complete valid 2x2 BMP", function ()
+            -- Create a simple 2x2 test pattern
+            local pixels = {
+                mock.app.pixelColor.rgba(255, 0, 0), -- Red
+                mock.app.pixelColor.rgba(0, 255, 0), -- Green
+                mock.app.pixelColor.rgba(0, 0, 255), -- Blue
+                mock.app.pixelColor.rgba(255, 255, 0), -- Yellow
+            }
+            local image = mock.createImage(2, 2, pixels)
+            local bmp = bitmap.create(image)
+
+            -- Verify it's a complete BMP file
+            expect(bmp:sub(1, 2)):toBe("BM")
+            expect(#bmp):toBe(54 + 16) -- Header + (6 bytes pixels + 2 padding) * 2 rows
+        end)
+    end)
+end)
diff --git a/src/pkg/bitmap/init.lua b/src/pkg/bitmap/init.lua
new file mode 100644
index 0000000..0013472
--- /dev/null
+++ b/src/pkg/bitmap/init.lua
@@ -0,0 +1,91 @@
+---Bitmap (BMP) file format encoder for 24-bit RGB images
+---@module 'pkg.bitmap'
+
+local pack = require("pkg.string.pack")
+
+---Generates BMP file header (14 bytes)
+---@param fileSize integer Total file size in bytes
+---@return string Binary header data
+local function createFileHeader (fileSize)
+    return "BM" -- Signature
+        .. pack.u32LE(fileSize) -- File size
+        .. pack.u32LE(0) -- Reserved
+        .. pack.u32LE(54) -- Data offset (14 + 40)
+end
+
+---Generates bitmap info header (40 bytes)
+---@param width integer Image width in pixels
+---@param height integer Image height in pixels
+---@return string Binary header data
+local function createInfoHeader (width, height)
+    return pack.u32LE(40) -- Header size
+        .. pack.i32LE(width) -- Image width
+        .. pack.i32LE(height) -- Image height
+        .. pack.u16LE(1) -- Planes (always 1)
+        .. pack.u16LE(24) -- Bits per pixel
+        .. pack.u32LE(0) -- Compression (0 = uncompressed)
+        .. pack.u32LE(0) -- Image size (0 is valid for uncompressed)
+        .. pack.i32LE(2835) -- X pixels per meter (~72 DPI)
+        .. pack.i32LE(2835) -- Y pixels per meter (~72 DPI)
+        .. pack.u32LE(0) -- Colors used (0 = all colors)
+        .. pack.u32LE(0) -- Important colors (0 = all important)
+end
+
+---Encodes image pixels to BMP format
+---Converts RGB to BGR, processes bottom-to-top, adds row padding
+---@param image Image Aseprite Image object
+---@return string Binary pixel data
+local function encodePixels (image)
+    local width = image.width
+    local height = image.height
+    local padding = (4 - (width * 3) % 4) % 4
+    local rows = {}
+
+    -- Process rows from bottom to top (BMP stores rows bottom-to-top)
+    for y = height - 1, 0, -1 do
+        local row = {}
+
+        -- Process each pixel in the row
+        for x = 0, width - 1 do
+            local pixel = image:getPixel(x, y)
+
+            -- Store as BGR (not RGB!)
+            table.insert(row, pack.u8(app.pixelColor.rgbaB(pixel)))
+            table.insert(row, pack.u8(app.pixelColor.rgbaG(pixel)))
+            table.insert(row, pack.u8(app.pixelColor.rgbaR(pixel)))
+        end
+
+        -- Add padding bytes to align row to 4-byte boundary
+        for i = 1, padding do
+            table.insert(row, "\x00")
+        end
+
+        table.insert(rows, table.concat(row))
+    end
+
+    return table.concat(rows)
+end
+
+---Creates a 24-bit BMP file from an Aseprite Image
+---@param image Image Aseprite RGB Image object
+---@return string Binary BMP file data
+local function create (image)
+    -- Validate color mode
+    if image.colorMode ~= ColorMode.RGB then
+        error("Only RGB images are supported for BMP export")
+    end
+
+    -- Calculate sizes
+    local rowSize = image.width * 3 + ((4 - (image.width * 3) % 4) % 4)
+    local pixelDataSize = rowSize * image.height
+    local fileSize = 54 + pixelDataSize -- 14 (file header) + 40 (info header) + pixel data
+
+    -- Generate BMP file
+    return createFileHeader(fileSize)
+        .. createInfoHeader(image.width, image.height)
+        .. encodePixels(image)
+end
+
+return {
+    create = create,
+}

From 1269d1cf0a4dd0ca234b87d5df2fb82e429a208b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Nov 2025 06:12:44 +0000
Subject: [PATCH 02/10] refactor: use metatable pattern for bitmap objects

Change bitmap.create() to return a table with metatable instead of
a plain string. This allows the bitmap object to be converted to a
string via tostring() or the __tostring metamethod.

Changes:
- Replace create() function with bitmap class using metatable
- Add tostring() method that generates BMP binary data
- Set __tostring metamethod for implicit string conversion
- Update all tests to use new API: bitmap(image)
- Add test for both explicit and implicit tostring conversion

Usage:
```lua
local bitmap = require("pkg.bitmap").bitmap
local bmp = bitmap(image)

-- Explicit conversion
local data = bmp:tostring()

-- Implicit conversion
local data = tostring(bmp)

-- Or use in string concatenation
local data = "" .. bmp
```

This pattern matches the RIFF chunk implementation and provides
more flexibility for future extensions.
---
 src/pkg/bitmap/bitmap_test.lua | 41 ++++++++++++++++++++++++----------
 src/pkg/bitmap/init.lua        | 38 ++++++++++++++++++++++---------
 2 files changed, 56 insertions(+), 23 deletions(-)

diff --git a/src/pkg/bitmap/bitmap_test.lua b/src/pkg/bitmap/bitmap_test.lua
index 8c49e77..3f9ed07 100644
--- a/src/pkg/bitmap/bitmap_test.lua
+++ b/src/pkg/bitmap/bitmap_test.lua
@@ -7,16 +7,16 @@ local mock = require("pkg.asepriteUtil.mock")
 _G.ColorMode = mock.ColorMode
 _G.app = mock.app
 
-local bitmap = require("pkg.bitmap")
+local bitmap = require("pkg.bitmap").bitmap
 
 describe("bitmap", function ()
-    describe("create", function ()
+    describe("bitmap constructor", function ()
         test("creates valid BMP file header", function ()
             local pixels = {
                 mock.app.pixelColor.rgba(255, 0, 0), -- Red
             }
             local image = mock.createImage(1, 1, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- Check BMP signature
             expect(bmp:sub(1, 2)):toBe("BM")
@@ -33,7 +33,7 @@ describe("bitmap", function ()
         test("creates valid bitmap info header", function ()
             local pixels = { mock.app.pixelColor.rgba(0, 0, 0) }
             local image = mock.createImage(1, 1, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- Info header starts at byte 15
             local headerSize = string.unpack("<I4", bmp:sub(15, 18))
@@ -58,7 +58,7 @@ describe("bitmap", function ()
                 mock.app.pixelColor.rgba(255, 0, 0),
             }
             local image = mock.createImage(1, 1, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- Pixel data starts at byte 55 (after 54-byte header)
             -- BGR order: B=0, G=0, R=255
@@ -70,7 +70,7 @@ describe("bitmap", function ()
         test("adds correct row padding for width=1", function ()
             local pixels = { mock.app.pixelColor.rgba(0, 0, 0) }
             local image = mock.createImage(1, 1, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- 1 pixel = 3 bytes, needs 1 byte padding to reach 4
             -- Pixel data: 3 bytes + 1 padding = 4 bytes total
@@ -84,7 +84,7 @@ describe("bitmap", function ()
                 mock.app.pixelColor.rgba(0, 0, 0),
             }
             local image = mock.createImage(2, 1, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- 2 pixels = 6 bytes, needs 2 bytes padding to reach 8
             expect(#bmp):toBe(54 + 8)
@@ -98,7 +98,7 @@ describe("bitmap", function ()
                 mock.app.pixelColor.rgba(0, 0, 0),
             }
             local image = mock.createImage(4, 1, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- 4 pixels = 12 bytes, already aligned to 4, no padding needed
             expect(#bmp):toBe(54 + 12)
@@ -115,7 +115,7 @@ describe("bitmap", function ()
                 mock.app.pixelColor.rgba(255, 255, 255), -- Bottom-right: White
             }
             local image = mock.createImage(2, 2, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- Pixel data starts at byte 55
             -- First row in BMP should be bottom row (y=1): Blue, White
@@ -149,7 +149,7 @@ describe("bitmap", function ()
                 pixels[i] = mock.app.pixelColor.rgba(0, 0, 0)
             end
             local image = mock.createImage(3, 3, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- 3 pixels per row = 9 bytes, needs 3 bytes padding to reach 12
             -- Total pixel data = (9 + 3) * 3 rows = 36 bytes
@@ -167,7 +167,7 @@ describe("bitmap", function ()
             }
 
             local success, err = pcall(function ()
-                bitmap.create(image)
+                bitmap(image)
             end)
 
             expect(success):toBe(false)
@@ -183,11 +183,28 @@ describe("bitmap", function ()
                 mock.app.pixelColor.rgba(255, 255, 0), -- Yellow
             }
             local image = mock.createImage(2, 2, pixels)
-            local bmp = bitmap.create(image)
+            local bmp = tostring(bitmap(image))
 
             -- Verify it's a complete BMP file
             expect(bmp:sub(1, 2)):toBe("BM")
             expect(#bmp):toBe(54 + 16) -- Header + (6 bytes pixels + 2 padding) * 2 rows
         end)
+
+        test("tostring method works", function ()
+            local pixels = { mock.app.pixelColor.rgba(0, 0, 0) }
+            local image = mock.createImage(1, 1, pixels)
+            local bmp = bitmap(image)
+
+            -- Test explicit tostring method
+            local str1 = bmp:tostring()
+            expect(str1:sub(1, 2)):toBe("BM")
+
+            -- Test implicit __tostring metamethod
+            local str2 = tostring(bmp)
+            expect(str2:sub(1, 2)):toBe("BM")
+
+            -- Both should produce the same result
+            expect(str1):toBe(str2)
+        end)
     end)
 end)
diff --git a/src/pkg/bitmap/init.lua b/src/pkg/bitmap/init.lua
index 0013472..fc93fe9 100644
--- a/src/pkg/bitmap/init.lua
+++ b/src/pkg/bitmap/init.lua
@@ -66,14 +66,15 @@ local function encodePixels (image)
     return table.concat(rows)
 end
 
----Creates a 24-bit BMP file from an Aseprite Image
----@param image Image Aseprite RGB Image object
----@return string Binary BMP file data
-local function create (image)
-    -- Validate color mode
-    if image.colorMode ~= ColorMode.RGB then
-        error("Only RGB images are supported for BMP export")
-    end
+---@class Bitmap
+---@field image Image
+---@overload fun(image: Image): Bitmap
+local bitmap = {}
+
+---Converts the bitmap to a binary string
+---@return string
+function bitmap.tostring (self)
+    local image = self.image
 
     -- Calculate sizes
     local rowSize = image.width * 3 + ((4 - (image.width * 3) % 4) % 4)
@@ -86,6 +87,21 @@ local function create (image)
         .. encodePixels(image)
 end
 
-return {
-    create = create,
-}
+setmetatable(bitmap --[[ @as unknown ]], {
+    ---@param image Image
+    __call = function (_, image)
+        -- Validate color mode
+        if image.colorMode ~= ColorMode.RGB then
+            error("Only RGB images are supported for BMP export")
+        end
+
+        local value = {
+            image = image,
+        }
+        setmetatable(value, { __index = bitmap, __tostring = bitmap.tostring })
+
+        return value
+    end,
+})
+
+return { bitmap = bitmap }

From d19916e5ea6f5e25db3a927570199520e511b952 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Nov 2025 06:19:23 +0000
Subject: [PATCH 03/10] refactor: separate bitmap class into dedicated file

Move bitmap class definition from init.lua to bitmap.lua for better
code organization and separation of concerns.

Changes:
- Create src/pkg/bitmap/bitmap.lua with bitmap class and helper functions
- Update init.lua to just require and export the bitmap class
- No API changes - tests continue to work without modification

This makes the codebase more modular and easier to maintain.
---
 src/pkg/bitmap/bitmap.lua | 107 ++++++++++++++++++++++++++++++++++++++
 src/pkg/bitmap/init.lua   | 103 +-----------------------------------
 2 files changed, 108 insertions(+), 102 deletions(-)
 create mode 100644 src/pkg/bitmap/bitmap.lua

diff --git a/src/pkg/bitmap/bitmap.lua b/src/pkg/bitmap/bitmap.lua
new file mode 100644
index 0000000..00babb7
--- /dev/null
+++ b/src/pkg/bitmap/bitmap.lua
@@ -0,0 +1,107 @@
+---Bitmap class for encoding 24-bit RGB images to BMP format
+---@module 'pkg.bitmap.bitmap'
+
+local pack = require("pkg.string.pack")
+
+---Generates BMP file header (14 bytes)
+---@param fileSize integer Total file size in bytes
+---@return string Binary header data
+local function createFileHeader (fileSize)
+    return "BM" -- Signature
+        .. pack.u32LE(fileSize) -- File size
+        .. pack.u32LE(0) -- Reserved
+        .. pack.u32LE(54) -- Data offset (14 + 40)
+end
+
+---Generates bitmap info header (40 bytes)
+---@param width integer Image width in pixels
+---@param height integer Image height in pixels
+---@return string Binary header data
+local function createInfoHeader (width, height)
+    return pack.u32LE(40) -- Header size
+        .. pack.i32LE(width) -- Image width
+        .. pack.i32LE(height) -- Image height
+        .. pack.u16LE(1) -- Planes (always 1)
+        .. pack.u16LE(24) -- Bits per pixel
+        .. pack.u32LE(0) -- Compression (0 = uncompressed)
+        .. pack.u32LE(0) -- Image size (0 is valid for uncompressed)
+        .. pack.i32LE(2835) -- X pixels per meter (~72 DPI)
+        .. pack.i32LE(2835) -- Y pixels per meter (~72 DPI)
+        .. pack.u32LE(0) -- Colors used (0 = all colors)
+        .. pack.u32LE(0) -- Important colors (0 = all important)
+end
+
+---Encodes image pixels to BMP format
+---Converts RGB to BGR, processes bottom-to-top, adds row padding
+---@param image Image Aseprite Image object
+---@return string Binary pixel data
+local function encodePixels (image)
+    local width = image.width
+    local height = image.height
+    local padding = (4 - (width * 3) % 4) % 4
+    local rows = {}
+
+    -- Process rows from bottom to top (BMP stores rows bottom-to-top)
+    for y = height - 1, 0, -1 do
+        local row = {}
+
+        -- Process each pixel in the row
+        for x = 0, width - 1 do
+            local pixel = image:getPixel(x, y)
+
+            -- Store as BGR (not RGB!)
+            table.insert(row, pack.u8(app.pixelColor.rgbaB(pixel)))
+            table.insert(row, pack.u8(app.pixelColor.rgbaG(pixel)))
+            table.insert(row, pack.u8(app.pixelColor.rgbaR(pixel)))
+        end
+
+        -- Add padding bytes to align row to 4-byte boundary
+        for i = 1, padding do
+            table.insert(row, "\x00")
+        end
+
+        table.insert(rows, table.concat(row))
+    end
+
+    return table.concat(rows)
+end
+
+---@class Bitmap
+---@field image Image
+---@overload fun(image: Image): Bitmap
+local bitmap = {}
+
+---Converts the bitmap to a binary string
+---@return string
+function bitmap.tostring (self)
+    local image = self.image
+
+    -- Calculate sizes
+    local rowSize = image.width * 3 + ((4 - (image.width * 3) % 4) % 4)
+    local pixelDataSize = rowSize * image.height
+    local fileSize = 54 + pixelDataSize -- 14 (file header) + 40 (info header) + pixel data
+
+    -- Generate BMP file
+    return createFileHeader(fileSize)
+        .. createInfoHeader(image.width, image.height)
+        .. encodePixels(image)
+end
+
+setmetatable(bitmap --[[ @as unknown ]], {
+    ---@param image Image
+    __call = function (_, image)
+        -- Validate color mode
+        if image.colorMode ~= ColorMode.RGB then
+            error("Only RGB images are supported for BMP export")
+        end
+
+        local value = {
+            image = image,
+        }
+        setmetatable(value, { __index = bitmap, __tostring = bitmap.tostring })
+
+        return value
+    end,
+})
+
+return bitmap
diff --git a/src/pkg/bitmap/init.lua b/src/pkg/bitmap/init.lua
index fc93fe9..34b5328 100644
--- a/src/pkg/bitmap/init.lua
+++ b/src/pkg/bitmap/init.lua
@@ -1,107 +1,6 @@
 ---Bitmap (BMP) file format encoder for 24-bit RGB images
 ---@module 'pkg.bitmap'
 
-local pack = require("pkg.string.pack")
-
----Generates BMP file header (14 bytes)
----@param fileSize integer Total file size in bytes
----@return string Binary header data
-local function createFileHeader (fileSize)
-    return "BM" -- Signature
-        .. pack.u32LE(fileSize) -- File size
-        .. pack.u32LE(0) -- Reserved
-        .. pack.u32LE(54) -- Data offset (14 + 40)
-end
-
----Generates bitmap info header (40 bytes)
----@param width integer Image width in pixels
----@param height integer Image height in pixels
----@return string Binary header data
-local function createInfoHeader (width, height)
-    return pack.u32LE(40) -- Header size
-        .. pack.i32LE(width) -- Image width
-        .. pack.i32LE(height) -- Image height
-        .. pack.u16LE(1) -- Planes (always 1)
-        .. pack.u16LE(24) -- Bits per pixel
-        .. pack.u32LE(0) -- Compression (0 = uncompressed)
-        .. pack.u32LE(0) -- Image size (0 is valid for uncompressed)
-        .. pack.i32LE(2835) -- X pixels per meter (~72 DPI)
-        .. pack.i32LE(2835) -- Y pixels per meter (~72 DPI)
-        .. pack.u32LE(0) -- Colors used (0 = all colors)
-        .. pack.u32LE(0) -- Important colors (0 = all important)
-end
-
----Encodes image pixels to BMP format
----Converts RGB to BGR, processes bottom-to-top, adds row padding
----@param image Image Aseprite Image object
----@return string Binary pixel data
-local function encodePixels (image)
-    local width = image.width
-    local height = image.height
-    local padding = (4 - (width * 3) % 4) % 4
-    local rows = {}
-
-    -- Process rows from bottom to top (BMP stores rows bottom-to-top)
-    for y = height - 1, 0, -1 do
-        local row = {}
-
-        -- Process each pixel in the row
-        for x = 0, width - 1 do
-            local pixel = image:getPixel(x, y)
-
-            -- Store as BGR (not RGB!)
-            table.insert(row, pack.u8(app.pixelColor.rgbaB(pixel)))
-            table.insert(row, pack.u8(app.pixelColor.rgbaG(pixel)))
-            table.insert(row, pack.u8(app.pixelColor.rgbaR(pixel)))
-        end
-
-        -- Add padding bytes to align row to 4-byte boundary
-        for i = 1, padding do
-            table.insert(row, "\x00")
-        end
-
-        table.insert(rows, table.concat(row))
-    end
-
-    return table.concat(rows)
-end
-
----@class Bitmap
----@field image Image
----@overload fun(image: Image): Bitmap
-local bitmap = {}
-
----Converts the bitmap to a binary string
----@return string
-function bitmap.tostring (self)
-    local image = self.image
-
-    -- Calculate sizes
-    local rowSize = image.width * 3 + ((4 - (image.width * 3) % 4) % 4)
-    local pixelDataSize = rowSize * image.height
-    local fileSize = 54 + pixelDataSize -- 14 (file header) + 40 (info header) + pixel data
-
-    -- Generate BMP file
-    return createFileHeader(fileSize)
-        .. createInfoHeader(image.width, image.height)
-        .. encodePixels(image)
-end
-
-setmetatable(bitmap --[[ @as unknown ]], {
-    ---@param image Image
-    __call = function (_, image)
-        -- Validate color mode
-        if image.colorMode ~= ColorMode.RGB then
-            error("Only RGB images are supported for BMP export")
-        end
-
-        local value = {
-            image = image,
-        }
-        setmetatable(value, { __index = bitmap, __tostring = bitmap.tostring })
-
-        return value
-    end,
-})
+local bitmap = require("pkg.bitmap.bitmap")
 
 return { bitmap = bitmap }

From 9cf33505269056c294767a791453201ba008c32f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Nov 2025 06:23:31 +0000
Subject: [PATCH 04/10] chore: remove unnecessary @module annotations

---
 src/pkg/bitmap/bitmap.lua | 1 -
 src/pkg/bitmap/init.lua   | 1 -
 2 files changed, 2 deletions(-)

diff --git a/src/pkg/bitmap/bitmap.lua b/src/pkg/bitmap/bitmap.lua
index 00babb7..661093d 100644
--- a/src/pkg/bitmap/bitmap.lua
+++ b/src/pkg/bitmap/bitmap.lua
@@ -1,5 +1,4 @@
 ---Bitmap class for encoding 24-bit RGB images to BMP format
----@module 'pkg.bitmap.bitmap'
 
 local pack = require("pkg.string.pack")
 
diff --git a/src/pkg/bitmap/init.lua b/src/pkg/bitmap/init.lua
index 34b5328..cbc09c7 100644
--- a/src/pkg/bitmap/init.lua
+++ b/src/pkg/bitmap/init.lua
@@ -1,5 +1,4 @@
 ---Bitmap (BMP) file format encoder for 24-bit RGB images
----@module 'pkg.bitmap'
 
 local bitmap = require("pkg.bitmap.bitmap")
 

From e2479ede06294f51c55af32e706d1fab3505f7c2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Nov 2025 06:24:44 +0000
Subject: [PATCH 05/10] chore: remove @module annotation from mock.lua

---
 src/pkg/asepriteUtil/mock.lua | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/pkg/asepriteUtil/mock.lua b/src/pkg/asepriteUtil/mock.lua
index 9d5300f..8785119 100644
--- a/src/pkg/asepriteUtil/mock.lua
+++ b/src/pkg/asepriteUtil/mock.lua
@@ -1,5 +1,4 @@
 ---Mock implementations of Aseprite APIs for testing
----@module 'pkg.asepriteUtil.mock'
 
 ---Mock ColorMode enum
 ---@class ColorMode

From f56e7fb0049466ec0c11245c9819eff596020418 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Nov 2025 06:29:02 +0000
Subject: [PATCH 06/10] refactor: use string.pack in mock pixelColor.rgba

---
 src/pkg/asepriteUtil/mock.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pkg/asepriteUtil/mock.lua b/src/pkg/asepriteUtil/mock.lua
index 8785119..af3a2cd 100644
--- a/src/pkg/asepriteUtil/mock.lua
+++ b/src/pkg/asepriteUtil/mock.lua
@@ -19,7 +19,7 @@ local pixelColor = {
     ---@return integer
     rgba = function (r, g, b, a)
         a = a or 255
-        return r | (g << 8) | (b << 16) | (a << 24)
+        return ("<I4"):unpack(("<BBBB"):pack(r, g, b, a))
     end,
 
     ---Extracts red component from RGBA pixel

From 4f74bab47fae8d10e6cab3ae6432c319d9989d37 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Nov 2025 06:29:39 +0000
Subject: [PATCH 07/10] chore: set pixels per meter to 0 in BMP header

---
 src/pkg/bitmap/bitmap.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/pkg/bitmap/bitmap.lua b/src/pkg/bitmap/bitmap.lua
index 661093d..5bd36e8 100644
--- a/src/pkg/bitmap/bitmap.lua
+++ b/src/pkg/bitmap/bitmap.lua
@@ -24,8 +24,8 @@ local function createInfoHeader (width, height)
         .. pack.u16LE(24) -- Bits per pixel
         .. pack.u32LE(0) -- Compression (0 = uncompressed)
         .. pack.u32LE(0) -- Image size (0 is valid for uncompressed)
-        .. pack.i32LE(2835) -- X pixels per meter (~72 DPI)
-        .. pack.i32LE(2835) -- Y pixels per meter (~72 DPI)
+        .. pack.i32LE(0) -- X pixels per meter (0 = not specified)
+        .. pack.i32LE(0) -- Y pixels per meter (0 = not specified)
         .. pack.u32LE(0) -- Colors used (0 = all colors)
         .. pack.u32LE(0) -- Important colors (0 = all important)
 end

From e19238fb5036c681a8ce54699e5515a20c97d503 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Nov 2025 15:35:15 +0000
Subject: [PATCH 08/10] refactor: restructure bitmap implementation

Major refactoring of bitmap module for cleaner architecture:

- mock.lua: Use bit operations instead of string.pack for rgba
- bitmap.lua: Use table.concat instead of string concatenation
- bitmap.lua: Rename class to BitmapFile and store components separately
  - fileHeader: BMP file header (14 bytes)
  - bitmapInfoHeader: Bitmap info header (40 bytes)
  - pixelData: Binary pixel data
- bitmap.lua: Export create function instead of __call metamethod
- init.lua: Simplify to directly return bitmap module
- bitmap_test.lua: Use hard-coded binary string literals instead of helpers
- bitmap_test.lua: Add test for BitmapFile structure

API change: bitmap(image) -> bitmap.create(image)
---
 src/pkg/asepriteUtil/mock.lua  |   2 +-
 src/pkg/bitmap/bitmap.lua      |  97 +++++++++++---------
 src/pkg/bitmap/bitmap_test.lua | 157 +++++++++++++++++----------------
 src/pkg/bitmap/init.lua        |   4 +-
 4 files changed, 138 insertions(+), 122 deletions(-)

diff --git a/src/pkg/asepriteUtil/mock.lua b/src/pkg/asepriteUtil/mock.lua
index af3a2cd..8785119 100644
--- a/src/pkg/asepriteUtil/mock.lua
+++ b/src/pkg/asepriteUtil/mock.lua
@@ -19,7 +19,7 @@ local pixelColor = {
     ---@return integer
     rgba = function (r, g, b, a)
         a = a or 255
-        return ("<I4"):unpack(("<BBBB"):pack(r, g, b, a))
+        return r | (g << 8) | (b << 16) | (a << 24)
     end,
 
     ---Extracts red component from RGBA pixel
diff --git a/src/pkg/bitmap/bitmap.lua b/src/pkg/bitmap/bitmap.lua
index 5bd36e8..02dcc9d 100644
--- a/src/pkg/bitmap/bitmap.lua
+++ b/src/pkg/bitmap/bitmap.lua
@@ -6,10 +6,12 @@ local pack = require("pkg.string.pack")
 ---@param fileSize integer Total file size in bytes
 ---@return string Binary header data
 local function createFileHeader (fileSize)
-    return "BM" -- Signature
-        .. pack.u32LE(fileSize) -- File size
-        .. pack.u32LE(0) -- Reserved
-        .. pack.u32LE(54) -- Data offset (14 + 40)
+    return table.concat({
+        "BM", -- Signature
+        pack.u32LE(fileSize), -- File size
+        pack.u32LE(0), -- Reserved
+        pack.u32LE(54), -- Data offset (14 + 40)
+    })
 end
 
 ---Generates bitmap info header (40 bytes)
@@ -17,17 +19,19 @@ end
 ---@param height integer Image height in pixels
 ---@return string Binary header data
 local function createInfoHeader (width, height)
-    return pack.u32LE(40) -- Header size
-        .. pack.i32LE(width) -- Image width
-        .. pack.i32LE(height) -- Image height
-        .. pack.u16LE(1) -- Planes (always 1)
-        .. pack.u16LE(24) -- Bits per pixel
-        .. pack.u32LE(0) -- Compression (0 = uncompressed)
-        .. pack.u32LE(0) -- Image size (0 is valid for uncompressed)
-        .. pack.i32LE(0) -- X pixels per meter (0 = not specified)
-        .. pack.i32LE(0) -- Y pixels per meter (0 = not specified)
-        .. pack.u32LE(0) -- Colors used (0 = all colors)
-        .. pack.u32LE(0) -- Important colors (0 = all important)
+    return table.concat({
+        pack.u32LE(40), -- Header size
+        pack.i32LE(width), -- Image width
+        pack.i32LE(height), -- Image height
+        pack.u16LE(1), -- Planes (always 1)
+        pack.u16LE(24), -- Bits per pixel
+        pack.u32LE(0), -- Compression (0 = uncompressed)
+        pack.u32LE(0), -- Image size (0 is valid for uncompressed)
+        pack.i32LE(0), -- X pixels per meter (0 = not specified)
+        pack.i32LE(0), -- Y pixels per meter (0 = not specified)
+        pack.u32LE(0), -- Colors used (0 = all colors)
+        pack.u32LE(0), -- Important colors (0 = all important)
+    })
 end
 
 ---Encodes image pixels to BMP format
@@ -65,42 +69,49 @@ local function encodePixels (image)
     return table.concat(rows)
 end
 
----@class Bitmap
----@field image Image
----@overload fun(image: Image): Bitmap
-local bitmap = {}
+---@class BitmapFile
+---@field fileHeader string BMP file header (14 bytes)
+---@field bitmapInfoHeader string Bitmap info header (40 bytes)
+---@field pixelData string Binary pixel data
+local BitmapFile = {}
 
----Converts the bitmap to a binary string
+---Converts the bitmap file to a binary string
 ---@return string
-function bitmap.tostring (self)
-    local image = self.image
+function BitmapFile.tostring (self)
+    return table.concat({
+        self.fileHeader,
+        self.bitmapInfoHeader,
+        self.pixelData,
+    })
+end
+
+---Creates a BitmapFile from an Aseprite Image
+---@param image Image Aseprite RGB Image object
+---@return BitmapFile
+local function createBitmap (image)
+    -- Validate color mode
+    if image.colorMode ~= ColorMode.RGB then
+        error("Only RGB images are supported for BMP export")
+    end
 
     -- Calculate sizes
     local rowSize = image.width * 3 + ((4 - (image.width * 3) % 4) % 4)
     local pixelDataSize = rowSize * image.height
     local fileSize = 54 + pixelDataSize -- 14 (file header) + 40 (info header) + pixel data
 
-    -- Generate BMP file
-    return createFileHeader(fileSize)
-        .. createInfoHeader(image.width, image.height)
-        .. encodePixels(image)
-end
+    -- Generate BMP components
+    local fileHeader = createFileHeader(fileSize)
+    local bitmapInfoHeader = createInfoHeader(image.width, image.height)
+    local pixelData = encodePixels(image)
 
-setmetatable(bitmap --[[ @as unknown ]], {
-    ---@param image Image
-    __call = function (_, image)
-        -- Validate color mode
-        if image.colorMode ~= ColorMode.RGB then
-            error("Only RGB images are supported for BMP export")
-        end
-
-        local value = {
-            image = image,
-        }
-        setmetatable(value, { __index = bitmap, __tostring = bitmap.tostring })
+    local value = {
+        fileHeader = fileHeader,
+        bitmapInfoHeader = bitmapInfoHeader,
+        pixelData = pixelData,
+    }
+    setmetatable(value, { __index = BitmapFile, __tostring = BitmapFile.tostring })
 
-        return value
-    end,
-})
+    return value
+end
 
-return bitmap
+return { create = createBitmap }
diff --git a/src/pkg/bitmap/bitmap_test.lua b/src/pkg/bitmap/bitmap_test.lua
index 3f9ed07..de5156e 100644
--- a/src/pkg/bitmap/bitmap_test.lua
+++ b/src/pkg/bitmap/bitmap_test.lua
@@ -7,101 +7,94 @@ local mock = require("pkg.asepriteUtil.mock")
 _G.ColorMode = mock.ColorMode
 _G.app = mock.app
 
-local bitmap = require("pkg.bitmap").bitmap
+local bitmap = require("pkg.bitmap")
 
 describe("bitmap", function ()
-    describe("bitmap constructor", function ()
+    describe("create", function ()
         test("creates valid BMP file header", function ()
-            local pixels = {
-                mock.app.pixelColor.rgba(255, 0, 0), -- Red
-            }
+            -- 1x1 red pixel
+            local pixels = { 0x000000FF } -- RGBA: red=255, green=0, blue=0, alpha=0
             local image = mock.createImage(1, 1, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- Check BMP signature
             expect(bmp:sub(1, 2)):toBe("BM")
 
             -- File size: 54 (headers) + 4 (1 pixel * 3 bytes + 1 padding) = 58
-            local fileSize = string.unpack("<I4", bmp:sub(3, 6))
-            expect(fileSize):toBe(58)
+            expect(bmp:sub(3, 6)):toBe("\x3A\x00\x00\x00")
+
+            -- Reserved
+            expect(bmp:sub(7, 10)):toBe("\x00\x00\x00\x00")
 
             -- Data offset should be 54
-            local dataOffset = string.unpack("<I4", bmp:sub(11, 14))
-            expect(dataOffset):toBe(54)
+            expect(bmp:sub(11, 14)):toBe("\x36\x00\x00\x00")
         end)
 
         test("creates valid bitmap info header", function ()
-            local pixels = { mock.app.pixelColor.rgba(0, 0, 0) }
+            local pixels = { 0x00000000 } -- Black pixel
             local image = mock.createImage(1, 1, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- Info header starts at byte 15
-            local headerSize = string.unpack("<I4", bmp:sub(15, 18))
-            expect(headerSize):toBe(40)
+            -- Header size = 40
+            expect(bmp:sub(15, 18)):toBe("\x28\x00\x00\x00")
 
-            local width = string.unpack("<i4", bmp:sub(19, 22))
-            expect(width):toBe(1)
+            -- Width = 1
+            expect(bmp:sub(19, 22)):toBe("\x01\x00\x00\x00")
 
-            local height = string.unpack("<i4", bmp:sub(23, 26))
-            expect(height):toBe(1)
+            -- Height = 1
+            expect(bmp:sub(23, 26)):toBe("\x01\x00\x00\x00")
 
-            local planes = string.unpack("<I2", bmp:sub(27, 28))
-            expect(planes):toBe(1)
+            -- Planes = 1
+            expect(bmp:sub(27, 28)):toBe("\x01\x00")
 
-            local bitsPerPixel = string.unpack("<I2", bmp:sub(29, 30))
-            expect(bitsPerPixel):toBe(24)
+            -- Bits per pixel = 24
+            expect(bmp:sub(29, 30)):toBe("\x18\x00")
         end)
 
         test("encodes pixels in BGR order", function ()
             -- Create a 1x1 image with red pixel (R=255, G=0, B=0)
-            local pixels = {
-                mock.app.pixelColor.rgba(255, 0, 0),
-            }
+            local pixels = { 0x000000FF }
             local image = mock.createImage(1, 1, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- Pixel data starts at byte 55 (after 54-byte header)
             -- BGR order: B=0, G=0, R=255
-            expect(bmp:sub(55, 55)):toBe("\x00") -- Blue
-            expect(bmp:sub(56, 56)):toBe("\x00") -- Green
-            expect(bmp:sub(57, 57)):toBe("\xFF") -- Red
+            expect(bmp:sub(55, 57)):toBe("\x00\x00\xFF")
         end)
 
         test("adds correct row padding for width=1", function ()
-            local pixels = { mock.app.pixelColor.rgba(0, 0, 0) }
+            local pixels = { 0x00000000 }
             local image = mock.createImage(1, 1, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- 1 pixel = 3 bytes, needs 1 byte padding to reach 4
             -- Pixel data: 3 bytes + 1 padding = 4 bytes total
-            expect(#bmp):toBe(54 + 4)
+            expect(#bmp):toBe(58)
             expect(bmp:sub(58, 58)):toBe("\x00") -- Padding byte
         end)
 
         test("adds correct row padding for width=2", function ()
-            local pixels = {
-                mock.app.pixelColor.rgba(0, 0, 0),
-                mock.app.pixelColor.rgba(0, 0, 0),
-            }
+            local pixels = { 0x00000000, 0x00000000 }
             local image = mock.createImage(2, 1, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- 2 pixels = 6 bytes, needs 2 bytes padding to reach 8
-            expect(#bmp):toBe(54 + 8)
+            expect(#bmp):toBe(62) -- 54 + 8
         end)
 
         test("adds no padding for width=4", function ()
             local pixels = {
-                mock.app.pixelColor.rgba(0, 0, 0),
-                mock.app.pixelColor.rgba(0, 0, 0),
-                mock.app.pixelColor.rgba(0, 0, 0),
-                mock.app.pixelColor.rgba(0, 0, 0),
+                0x00000000,
+                0x00000000,
+                0x00000000,
+                0x00000000,
             }
             local image = mock.createImage(4, 1, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- 4 pixels = 12 bytes, already aligned to 4, no padding needed
-            expect(#bmp):toBe(54 + 12)
+            expect(#bmp):toBe(66) -- 54 + 12
         end)
 
         test("stores rows bottom-to-top", function ()
@@ -109,51 +102,45 @@ describe("bitmap", function ()
             -- Top row (y=0):    Red(255,0,0)    Green(0,255,0)
             -- Bottom row (y=1): Blue(0,0,255)   White(255,255,255)
             local pixels = {
-                mock.app.pixelColor.rgba(255, 0, 0), -- Top-left: Red
-                mock.app.pixelColor.rgba(0, 255, 0), -- Top-right: Green
-                mock.app.pixelColor.rgba(0, 0, 255), -- Bottom-left: Blue
-                mock.app.pixelColor.rgba(255, 255, 255), -- Bottom-right: White
+                0x000000FF, -- Top-left: Red
+                0x0000FF00, -- Top-right: Green
+                0x00FF0000, -- Bottom-left: Blue
+                0x00FFFFFF, -- Bottom-right: White
             }
             local image = mock.createImage(2, 2, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- Pixel data starts at byte 55
             -- First row in BMP should be bottom row (y=1): Blue, White
             -- Blue in BGR: B=255, G=0, R=0
-            expect(bmp:sub(55, 55)):toBe("\xFF") -- Blue.B
-            expect(bmp:sub(56, 56)):toBe("\x00") -- Blue.G
-            expect(bmp:sub(57, 57)):toBe("\x00") -- Blue.R
+            expect(bmp:sub(55, 57)):toBe("\xFF\x00\x00")
 
             -- White in BGR: B=255, G=255, R=255
-            expect(bmp:sub(58, 58)):toBe("\xFF") -- White.B
-            expect(bmp:sub(59, 59)):toBe("\xFF") -- White.G
-            expect(bmp:sub(60, 60)):toBe("\xFF") -- White.R
+            expect(bmp:sub(58, 60)):toBe("\xFF\xFF\xFF")
 
             -- 2 pixels = 6 bytes, need 2 bytes padding
+            expect(bmp:sub(61, 62)):toBe("\x00\x00")
+
             -- Second row in BMP should be top row (y=0): Red, Green
             -- Red in BGR: B=0, G=0, R=255
-            expect(bmp:sub(63, 63)):toBe("\x00") -- Red.B
-            expect(bmp:sub(64, 64)):toBe("\x00") -- Red.G
-            expect(bmp:sub(65, 65)):toBe("\xFF") -- Red.R
+            expect(bmp:sub(63, 65)):toBe("\x00\x00\xFF")
 
             -- Green in BGR: B=0, G=255, R=0
-            expect(bmp:sub(66, 66)):toBe("\x00") -- Green.B
-            expect(bmp:sub(67, 67)):toBe("\xFF") -- Green.G
-            expect(bmp:sub(68, 68)):toBe("\x00") -- Green.R
+            expect(bmp:sub(66, 68)):toBe("\x00\xFF\x00")
         end)
 
         test("handles 3x3 image correctly", function ()
             -- Create a simple 3x3 image with all black pixels
             local pixels = {}
             for i = 1, 9 do
-                pixels[i] = mock.app.pixelColor.rgba(0, 0, 0)
+                pixels[i] = 0x00000000
             end
             local image = mock.createImage(3, 3, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- 3 pixels per row = 9 bytes, needs 3 bytes padding to reach 12
             -- Total pixel data = (9 + 3) * 3 rows = 36 bytes
-            expect(#bmp):toBe(54 + 36)
+            expect(#bmp):toBe(90) -- 54 + 36
         end)
 
         test("throws error for non-RGB image", function ()
@@ -167,7 +154,7 @@ describe("bitmap", function ()
             }
 
             local success, err = pcall(function ()
-                bitmap(image)
+                bitmap.create(image)
             end)
 
             expect(success):toBe(false)
@@ -177,30 +164,50 @@ describe("bitmap", function ()
         test("creates complete valid 2x2 BMP", function ()
             -- Create a simple 2x2 test pattern
             local pixels = {
-                mock.app.pixelColor.rgba(255, 0, 0), -- Red
-                mock.app.pixelColor.rgba(0, 255, 0), -- Green
-                mock.app.pixelColor.rgba(0, 0, 255), -- Blue
-                mock.app.pixelColor.rgba(255, 255, 0), -- Yellow
+                0x000000FF, -- Red
+                0x0000FF00, -- Green
+                0x00FF0000, -- Blue
+                0x0000FFFF, -- Yellow
             }
             local image = mock.createImage(2, 2, pixels)
-            local bmp = tostring(bitmap(image))
+            local bmp = tostring(bitmap.create(image))
 
             -- Verify it's a complete BMP file
             expect(bmp:sub(1, 2)):toBe("BM")
-            expect(#bmp):toBe(54 + 16) -- Header + (6 bytes pixels + 2 padding) * 2 rows
+            expect(#bmp):toBe(70) -- 54 + (6 bytes pixels + 2 padding) * 2 rows
+        end)
+
+        test("BitmapFile has correct structure", function ()
+            local pixels = { 0x00000000 }
+            local image = mock.createImage(1, 1, pixels)
+            local bmpFile = bitmap.create(image)
+
+            -- Check that BitmapFile has the expected fields
+            expect(type(bmpFile.fileHeader)):toBe("string")
+            expect(type(bmpFile.bitmapInfoHeader)):toBe("string")
+            expect(type(bmpFile.pixelData)):toBe("string")
+
+            -- File header should be 14 bytes
+            expect(#bmpFile.fileHeader):toBe(14)
+
+            -- Bitmap info header should be 40 bytes
+            expect(#bmpFile.bitmapInfoHeader):toBe(40)
+
+            -- Pixel data should be 4 bytes (3 + 1 padding)
+            expect(#bmpFile.pixelData):toBe(4)
         end)
 
         test("tostring method works", function ()
-            local pixels = { mock.app.pixelColor.rgba(0, 0, 0) }
+            local pixels = { 0x00000000 }
             local image = mock.createImage(1, 1, pixels)
-            local bmp = bitmap(image)
+            local bmpFile = bitmap.create(image)
 
             -- Test explicit tostring method
-            local str1 = bmp:tostring()
+            local str1 = bmpFile:tostring()
             expect(str1:sub(1, 2)):toBe("BM")
 
             -- Test implicit __tostring metamethod
-            local str2 = tostring(bmp)
+            local str2 = tostring(bmpFile)
             expect(str2:sub(1, 2)):toBe("BM")
 
             -- Both should produce the same result
diff --git a/src/pkg/bitmap/init.lua b/src/pkg/bitmap/init.lua
index cbc09c7..47edc9f 100644
--- a/src/pkg/bitmap/init.lua
+++ b/src/pkg/bitmap/init.lua
@@ -1,5 +1,3 @@
 ---Bitmap (BMP) file format encoder for 24-bit RGB images
 
-local bitmap = require("pkg.bitmap.bitmap")
-
-return { bitmap = bitmap }
+return require("pkg.bitmap.bitmap")

From 03ac4af10d65d2c854fdccacb5360d12977c9436 Mon Sep 17 00:00:00 2001
From: Mooncake Sugar <Tsukina7mochi@gmail.com>
Date: Sat, 15 Nov 2025 01:30:32 +0900
Subject: [PATCH 09/10] refactor: remove empty init.lua

---
 src/pkg/bitmap/bitmap.lua | 117 -------------------------------------
 src/pkg/bitmap/init.lua   | 118 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 116 insertions(+), 119 deletions(-)
 delete mode 100644 src/pkg/bitmap/bitmap.lua

diff --git a/src/pkg/bitmap/bitmap.lua b/src/pkg/bitmap/bitmap.lua
deleted file mode 100644
index 02dcc9d..0000000
--- a/src/pkg/bitmap/bitmap.lua
+++ /dev/null
@@ -1,117 +0,0 @@
----Bitmap class for encoding 24-bit RGB images to BMP format
-
-local pack = require("pkg.string.pack")
-
----Generates BMP file header (14 bytes)
----@param fileSize integer Total file size in bytes
----@return string Binary header data
-local function createFileHeader (fileSize)
-    return table.concat({
-        "BM", -- Signature
-        pack.u32LE(fileSize), -- File size
-        pack.u32LE(0), -- Reserved
-        pack.u32LE(54), -- Data offset (14 + 40)
-    })
-end
-
----Generates bitmap info header (40 bytes)
----@param width integer Image width in pixels
----@param height integer Image height in pixels
----@return string Binary header data
-local function createInfoHeader (width, height)
-    return table.concat({
-        pack.u32LE(40), -- Header size
-        pack.i32LE(width), -- Image width
-        pack.i32LE(height), -- Image height
-        pack.u16LE(1), -- Planes (always 1)
-        pack.u16LE(24), -- Bits per pixel
-        pack.u32LE(0), -- Compression (0 = uncompressed)
-        pack.u32LE(0), -- Image size (0 is valid for uncompressed)
-        pack.i32LE(0), -- X pixels per meter (0 = not specified)
-        pack.i32LE(0), -- Y pixels per meter (0 = not specified)
-        pack.u32LE(0), -- Colors used (0 = all colors)
-        pack.u32LE(0), -- Important colors (0 = all important)
-    })
-end
-
----Encodes image pixels to BMP format
----Converts RGB to BGR, processes bottom-to-top, adds row padding
----@param image Image Aseprite Image object
----@return string Binary pixel data
-local function encodePixels (image)
-    local width = image.width
-    local height = image.height
-    local padding = (4 - (width * 3) % 4) % 4
-    local rows = {}
-
-    -- Process rows from bottom to top (BMP stores rows bottom-to-top)
-    for y = height - 1, 0, -1 do
-        local row = {}
-
-        -- Process each pixel in the row
-        for x = 0, width - 1 do
-            local pixel = image:getPixel(x, y)
-
-            -- Store as BGR (not RGB!)
-            table.insert(row, pack.u8(app.pixelColor.rgbaB(pixel)))
-            table.insert(row, pack.u8(app.pixelColor.rgbaG(pixel)))
-            table.insert(row, pack.u8(app.pixelColor.rgbaR(pixel)))
-        end
-
-        -- Add padding bytes to align row to 4-byte boundary
-        for i = 1, padding do
-            table.insert(row, "\x00")
-        end
-
-        table.insert(rows, table.concat(row))
-    end
-
-    return table.concat(rows)
-end
-
----@class BitmapFile
----@field fileHeader string BMP file header (14 bytes)
----@field bitmapInfoHeader string Bitmap info header (40 bytes)
----@field pixelData string Binary pixel data
-local BitmapFile = {}
-
----Converts the bitmap file to a binary string
----@return string
-function BitmapFile.tostring (self)
-    return table.concat({
-        self.fileHeader,
-        self.bitmapInfoHeader,
-        self.pixelData,
-    })
-end
-
----Creates a BitmapFile from an Aseprite Image
----@param image Image Aseprite RGB Image object
----@return BitmapFile
-local function createBitmap (image)
-    -- Validate color mode
-    if image.colorMode ~= ColorMode.RGB then
-        error("Only RGB images are supported for BMP export")
-    end
-
-    -- Calculate sizes
-    local rowSize = image.width * 3 + ((4 - (image.width * 3) % 4) % 4)
-    local pixelDataSize = rowSize * image.height
-    local fileSize = 54 + pixelDataSize -- 14 (file header) + 40 (info header) + pixel data
-
-    -- Generate BMP components
-    local fileHeader = createFileHeader(fileSize)
-    local bitmapInfoHeader = createInfoHeader(image.width, image.height)
-    local pixelData = encodePixels(image)
-
-    local value = {
-        fileHeader = fileHeader,
-        bitmapInfoHeader = bitmapInfoHeader,
-        pixelData = pixelData,
-    }
-    setmetatable(value, { __index = BitmapFile, __tostring = BitmapFile.tostring })
-
-    return value
-end
-
-return { create = createBitmap }
diff --git a/src/pkg/bitmap/init.lua b/src/pkg/bitmap/init.lua
index 47edc9f..02dcc9d 100644
--- a/src/pkg/bitmap/init.lua
+++ b/src/pkg/bitmap/init.lua
@@ -1,3 +1,117 @@
----Bitmap (BMP) file format encoder for 24-bit RGB images
+---Bitmap class for encoding 24-bit RGB images to BMP format
 
-return require("pkg.bitmap.bitmap")
+local pack = require("pkg.string.pack")
+
+---Generates BMP file header (14 bytes)
+---@param fileSize integer Total file size in bytes
+---@return string Binary header data
+local function createFileHeader (fileSize)
+    return table.concat({
+        "BM", -- Signature
+        pack.u32LE(fileSize), -- File size
+        pack.u32LE(0), -- Reserved
+        pack.u32LE(54), -- Data offset (14 + 40)
+    })
+end
+
+---Generates bitmap info header (40 bytes)
+---@param width integer Image width in pixels
+---@param height integer Image height in pixels
+---@return string Binary header data
+local function createInfoHeader (width, height)
+    return table.concat({
+        pack.u32LE(40), -- Header size
+        pack.i32LE(width), -- Image width
+        pack.i32LE(height), -- Image height
+        pack.u16LE(1), -- Planes (always 1)
+        pack.u16LE(24), -- Bits per pixel
+        pack.u32LE(0), -- Compression (0 = uncompressed)
+        pack.u32LE(0), -- Image size (0 is valid for uncompressed)
+        pack.i32LE(0), -- X pixels per meter (0 = not specified)
+        pack.i32LE(0), -- Y pixels per meter (0 = not specified)
+        pack.u32LE(0), -- Colors used (0 = all colors)
+        pack.u32LE(0), -- Important colors (0 = all important)
+    })
+end
+
+---Encodes image pixels to BMP format
+---Converts RGB to BGR, processes bottom-to-top, adds row padding
+---@param image Image Aseprite Image object
+---@return string Binary pixel data
+local function encodePixels (image)
+    local width = image.width
+    local height = image.height
+    local padding = (4 - (width * 3) % 4) % 4
+    local rows = {}
+
+    -- Process rows from bottom to top (BMP stores rows bottom-to-top)
+    for y = height - 1, 0, -1 do
+        local row = {}
+
+        -- Process each pixel in the row
+        for x = 0, width - 1 do
+            local pixel = image:getPixel(x, y)
+
+            -- Store as BGR (not RGB!)
+            table.insert(row, pack.u8(app.pixelColor.rgbaB(pixel)))
+            table.insert(row, pack.u8(app.pixelColor.rgbaG(pixel)))
+            table.insert(row, pack.u8(app.pixelColor.rgbaR(pixel)))
+        end
+
+        -- Add padding bytes to align row to 4-byte boundary
+        for i = 1, padding do
+            table.insert(row, "\x00")
+        end
+
+        table.insert(rows, table.concat(row))
+    end
+
+    return table.concat(rows)
+end
+
+---@class BitmapFile
+---@field fileHeader string BMP file header (14 bytes)
+---@field bitmapInfoHeader string Bitmap info header (40 bytes)
+---@field pixelData string Binary pixel data
+local BitmapFile = {}
+
+---Converts the bitmap file to a binary string
+---@return string
+function BitmapFile.tostring (self)
+    return table.concat({
+        self.fileHeader,
+        self.bitmapInfoHeader,
+        self.pixelData,
+    })
+end
+
+---Creates a BitmapFile from an Aseprite Image
+---@param image Image Aseprite RGB Image object
+---@return BitmapFile
+local function createBitmap (image)
+    -- Validate color mode
+    if image.colorMode ~= ColorMode.RGB then
+        error("Only RGB images are supported for BMP export")
+    end
+
+    -- Calculate sizes
+    local rowSize = image.width * 3 + ((4 - (image.width * 3) % 4) % 4)
+    local pixelDataSize = rowSize * image.height
+    local fileSize = 54 + pixelDataSize -- 14 (file header) + 40 (info header) + pixel data
+
+    -- Generate BMP components
+    local fileHeader = createFileHeader(fileSize)
+    local bitmapInfoHeader = createInfoHeader(image.width, image.height)
+    local pixelData = encodePixels(image)
+
+    local value = {
+        fileHeader = fileHeader,
+        bitmapInfoHeader = bitmapInfoHeader,
+        pixelData = pixelData,
+    }
+    setmetatable(value, { __index = BitmapFile, __tostring = BitmapFile.tostring })
+
+    return value
+end
+
+return { create = createBitmap }

From 53fbeb564b36943d08d5474308d0a15b23b46bc2 Mon Sep 17 00:00:00 2001
From: Mooncake Sugar <Tsukina7mochi@gmail.com>
Date: Sat, 15 Nov 2025 01:35:51 +0900
Subject: [PATCH 10/10] refactor: change expression

---
 src/pkg/bitmap/init.lua | 20 +++++++-------------
 1 file changed, 7 insertions(+), 13 deletions(-)

diff --git a/src/pkg/bitmap/init.lua b/src/pkg/bitmap/init.lua
index 02dcc9d..654ffeb 100644
--- a/src/pkg/bitmap/init.lua
+++ b/src/pkg/bitmap/init.lua
@@ -1,8 +1,6 @@
----Bitmap class for encoding 24-bit RGB images to BMP format
-
 local pack = require("pkg.string.pack")
 
----Generates BMP file header (14 bytes)
+---Generates BMP file header
 ---@param fileSize integer Total file size in bytes
 ---@return string Binary header data
 local function createFileHeader (fileSize)
@@ -14,11 +12,11 @@ local function createFileHeader (fileSize)
     })
 end
 
----Generates bitmap info header (40 bytes)
+---Generates bitmap info header
 ---@param width integer Image width in pixels
 ---@param height integer Image height in pixels
 ---@return string Binary header data
-local function createInfoHeader (width, height)
+local function createBitmapInfoHeader (width, height)
     return table.concat({
         pack.u32LE(40), -- Header size
         pack.i32LE(width), -- Image width
@@ -44,24 +42,21 @@ local function encodePixels (image)
     local padding = (4 - (width * 3) % 4) % 4
     local rows = {}
 
-    -- Process rows from bottom to top (BMP stores rows bottom-to-top)
+    -- Process rows from bottom to top
     for y = height - 1, 0, -1 do
         local row = {}
 
-        -- Process each pixel in the row
         for x = 0, width - 1 do
             local pixel = image:getPixel(x, y)
 
-            -- Store as BGR (not RGB!)
+            -- Store as BGR
             table.insert(row, pack.u8(app.pixelColor.rgbaB(pixel)))
             table.insert(row, pack.u8(app.pixelColor.rgbaG(pixel)))
             table.insert(row, pack.u8(app.pixelColor.rgbaR(pixel)))
         end
 
         -- Add padding bytes to align row to 4-byte boundary
-        for i = 1, padding do
-            table.insert(row, "\x00")
-        end
+        table.insert(row, ("\x00"):rep(padding))
 
         table.insert(rows, table.concat(row))
     end
@@ -89,7 +84,6 @@ end
 ---@param image Image Aseprite RGB Image object
 ---@return BitmapFile
 local function createBitmap (image)
-    -- Validate color mode
     if image.colorMode ~= ColorMode.RGB then
         error("Only RGB images are supported for BMP export")
     end
@@ -101,7 +95,7 @@ local function createBitmap (image)
 
     -- Generate BMP components
     local fileHeader = createFileHeader(fileSize)
-    local bitmapInfoHeader = createInfoHeader(image.width, image.height)
+    local bitmapInfoHeader = createBitmapInfoHeader(image.width, image.height)
     local pixelData = encodePixels(image)
 
     local value = {