modularizing

flexlove/Animation.lua

@@ -0,0 +1,188 @@
+---@class Animation
+---@field duration number
+---@field start {width?:number, height?:number, opacity?:number}
+---@field final {width?:number, height?:number, opacity?:number}
+---@field elapsed number
+---@field transform table?
+---@field transition table?
+--- Easing functions for animations
+local Easing = {
+  linear = function(t)
+    return t
+  end,
+
+  easeInQuad = function(t)
+    return t * t
+  end,
+  easeOutQuad = function(t)
+    return t * (2 - t)
+  end,
+  easeInOutQuad = function(t)
+    return t < 0.5 and 2 * t * t or -1 + (4 - 2 * t) * t
+  end,
+
+  easeInCubic = function(t)
+    return t * t * t
+  end,
+  easeOutCubic = function(t)
+    local t1 = t - 1
+    return t1 * t1 * t1 + 1
+  end,
+  easeInOutCubic = function(t)
+    return t < 0.5 and 4 * t * t * t or (t - 1) * (2 * t - 2) * (2 * t - 2) + 1
+  end,
+
+  easeInQuart = function(t)
+    return t * t * t * t
+  end,
+  easeOutQuart = function(t)
+    local t1 = t - 1
+    return 1 - t1 * t1 * t1 * t1
+  end,
+
+  easeInExpo = function(t)
+    return t == 0 and 0 or math.pow(2, 10 * (t - 1))
+  end,
+  easeOutExpo = function(t)
+    return t == 1 and 1 or 1 - math.pow(2, -10 * t)
+  end,
+}
+
+local Animation = {}
+Animation.__index = Animation
+
+---@class AnimationProps
+---@field duration number
+---@field start {width?:number, height?:number, opacity?:number}
+---@field final {width?:number, height?:number, opacity?:number}
+---@field transform table?
+---@field transition table?
+local AnimationProps = {}
+
+---@class TransformProps
+---@field scale {x?:number, y?:number}?
+---@field rotate number?
+---@field translate {x?:number, y?:number}?
+---@field skew {x?:number, y?:number}?
+
+---@class TransitionProps
+---@field duration number?
+---@field easing string?
+
+---@param props AnimationProps
+---@return Animation
+function Animation.new(props)
+  local self = setmetatable({}, Animation)
+  self.duration = props.duration
+  self.start = props.start
+  self.final = props.final
+  self.transform = props.transform
+  self.transition = props.transition
+  self.elapsed = 0
+
+  -- Set easing function (default to linear)
+  local easingName = props.easing or "linear"
+  self.easing = Easing[easingName] or Easing.linear
+
+  -- Pre-allocate result table to avoid GC pressure
+  self._cachedResult = {}
+  self._resultDirty = true
+
+  return self
+end
+
+---@param dt number
+---@return boolean
+function Animation:update(dt)
+  self.elapsed = self.elapsed + dt
+  self._resultDirty = true -- Mark cached result as dirty
+  if self.elapsed >= self.duration then
+    return true -- finished
+  else
+    return false
+  end
+end
+
+---@return table
+function Animation:interpolate()
+  -- Return cached result if not dirty (avoids recalculation)
+  if not self._resultDirty then
+    return self._cachedResult
+  end
+
+  local t = math.min(self.elapsed / self.duration, 1)
+  t = self.easing(t) -- Apply easing function
+  local result = self._cachedResult -- Reuse existing table
+
+  -- Clear previous values
+  result.width = nil
+  result.height = nil
+  result.opacity = nil
+
+  -- Handle width and height if present
+  if self.start.width and self.final.width then
+    result.width = self.start.width * (1 - t) + self.final.width * t
+  end
+
+  if self.start.height and self.final.height then
+    result.height = self.start.height * (1 - t) + self.final.height * t
+  end
+
+  -- Handle other properties like opacity
+  if self.start.opacity and self.final.opacity then
+    result.opacity = self.start.opacity * (1 - t) + self.final.opacity * t
+  end
+
+  -- Apply transform if present
+  if self.transform then
+    for key, value in pairs(self.transform) do
+      result[key] = value
+    end
+  end
+
+  self._resultDirty = false -- Mark as clean
+  return result
+end
+
+--- Apply animation to a GUI element
+---@param element Element
+function Animation:apply(element)
+  if element.animation then
+    -- If there's an existing animation, we should probably stop it or replace it
+    element.animation = self
+  else
+    element.animation = self
+  end
+end
+
+--- Create a simple fade animation
+---@param duration number
+---@param fromOpacity number
+---@param toOpacity number
+---@return Animation
+function Animation.fade(duration, fromOpacity, toOpacity)
+  return Animation.new({
+    duration = duration,
+    start = { opacity = fromOpacity },
+    final = { opacity = toOpacity },
+    transform = {},
+    transition = {},
+  })
+end
+
+--- Create a simple scale animation
+---@param duration number
+---@param fromScale table{width:number,height:number}
+---@param toScale table{width:number,height:number}
+---@return Animation
+function Animation.scale(duration, fromScale, toScale)
+  return Animation.new({
+    duration = duration,
+    start = { width = fromScale.width, height = fromScale.height },
+    final = { width = toScale.width, height = toScale.height },
+    transform = {},
+    transition = {},
+  })
+end
+
+return Animation

flexlove/Blur.lua

@@ -0,0 +1,302 @@
+--[[
+FlexLove Blur Module
+Fast Gaussian blur implementation with canvas caching
+]]
+
+local Blur = {}
+
+-- Canvas cache to avoid recreating canvases every frame
+local canvasCache = {}
+local MAX_CACHE_SIZE = 20
+
+--- Build Gaussian blur shader with given parameters
+---@param taps number -- Number of samples (must be odd, >= 3)
+---@param offset number -- Offset multiplier for sampling
+---@param offset_type string -- "weighted" or "center"
+---@param sigma number -- Gaussian sigma value
+---@return love.Shader
+local function buildShader(taps, offset, offset_type, sigma)
+  taps = math.floor(taps)
+  sigma = sigma >= 1 and sigma or (taps - 1) * offset / 6
+  sigma = math.max(sigma, 1)
+
+  local steps = (taps + 1) / 2
+
+  -- Calculate gaussian function
+  local g_offsets = {}
+  local g_weights = {}
+  for i = 1, steps, 1 do
+    g_offsets[i] = offset * (i - 1)
+    g_weights[i] = math.exp(-0.5 * (g_offsets[i] - 0) ^ 2 * 1 / sigma ^ 2)
+  end
+
+  -- Calculate offsets and weights for sub-pixel samples
+  local offsets = {}
+  local weights = {}
+  for i = #g_weights, 2, -2 do
+    local oA, oB = g_offsets[i], g_offsets[i - 1]
+    local wA, wB = g_weights[i], g_weights[i - 1]
+    wB = oB == 0 and wB / 2 or wB
+    local weight = wA + wB
+    offsets[#offsets + 1] = offset_type == "center" and (oA + oB) / 2 or (oA * wA + oB * wB) / weight
+    weights[#weights + 1] = weight
+  end
+
+  local code = { [[
+    extern vec2 direction;
+    vec4 effect(vec4 color, Image tex, vec2 tc, vec2 sc) {]] }
+
+  local norm = 0
+  if #g_weights % 2 == 0 then
+    code[#code + 1] = "vec4 c = vec4( 0.0 );"
+  else
+    local weight = g_weights[1]
+    norm = norm + weight
+    code[#code + 1] = ("vec4 c = %f * texture2D(tex, tc);"):format(weight)
+  end
+
+  local tmpl = "c += %f * ( texture2D(tex, tc + %f * direction)+ texture2D(tex, tc - %f * direction));\n"
+  for i = 1, #offsets, 1 do
+    local offset = offsets[i]
+    local weight = weights[i]
+    norm = norm + weight * 2
+    code[#code + 1] = tmpl:format(weight, offset, offset)
+  end
+  code[#code + 1] = ("return c * vec4(%f) * color; }"):format(1 / norm)
+
+  local shader = table.concat(code)
+  return love.graphics.newShader(shader)
+end
+
+--- Get or create a canvas from cache
+---@param width number
+---@param height number
+---@return love.Canvas
+local function getCanvas(width, height)
+  local key = string.format("%dx%d", width, height)
+
+  if not canvasCache[key] then
+    canvasCache[key] = {}
+  end
+
+  local cache = canvasCache[key]
+
+  -- Try to reuse existing canvas
+  for i, canvas in ipairs(cache) do
+    if not canvas.inUse then
+      canvas.inUse = true
+      return canvas.canvas
+    end
+  end
+
+  -- Create new canvas if none available
+  local canvas = love.graphics.newCanvas(width, height)
+  table.insert(cache, { canvas = canvas, inUse = true })
+
+  -- Limit cache size
+  if #cache > MAX_CACHE_SIZE then
+    table.remove(cache, 1)
+  end
+
+  return canvas
+end
+
+--- Release a canvas back to the cache
+---@param canvas love.Canvas
+local function releaseCanvas(canvas)
+  for _, sizeCache in pairs(canvasCache) do
+    for _, entry in ipairs(sizeCache) do
+      if entry.canvas == canvas then
+        entry.inUse = false
+        return
+      end
+    end
+  end
+end
+
+--- Create a blur effect instance
+---@param quality number -- Quality level (1-10, higher = better quality but slower)
+---@return table -- Blur effect instance
+function Blur.new(quality)
+  quality = math.max(1, math.min(10, quality or 5))
+
+  -- Map quality to shader parameters
+  -- Quality 1: 3 taps (fastest, lowest quality)
+  -- Quality 5: 7 taps (balanced)
+  -- Quality 10: 15 taps (slowest, highest quality)
+  local taps = 3 + (quality - 1) * 1.5
+  taps = math.floor(taps)
+  if taps % 2 == 0 then
+    taps = taps + 1 -- Ensure odd number
+  end
+
+  local offset = 1.0
+  local offset_type = "weighted"
+  local sigma = -1
+
+  local shader = buildShader(taps, offset, offset_type, sigma)
+
+  local instance = {
+    shader = shader,
+    quality = quality,
+    taps = taps,
+  }
+
+  return instance
+end
+
+--- Apply blur to a region of the screen
+---@param blurInstance table -- Blur effect instance from Blur.new()
+---@param intensity number -- Blur intensity (0-100)
+---@param x number -- X position
+---@param y number -- Y position
+---@param width number -- Width
+---@param height number -- Height
+---@param drawFunc function -- Function to draw content to be blurred
+function Blur.applyToRegion(blurInstance, intensity, x, y, width, height, drawFunc)
+  if intensity <= 0 or width <= 0 or height <= 0 then
+    -- No blur, just draw normally
+    drawFunc()
+    return
+  end
+
+  -- Clamp intensity
+  intensity = math.max(0, math.min(100, intensity))
+
+  -- Calculate blur passes based on intensity
+  -- Intensity 0-100 maps to 0-5 passes
+  local passes = math.ceil(intensity / 20)
+  passes = math.max(1, math.min(5, passes))
+
+  -- Get canvases for ping-pong rendering
+  local canvas1 = getCanvas(width, height)
+  local canvas2 = getCanvas(width, height)
+
+  -- Save graphics state
+  local prevCanvas = love.graphics.getCanvas()
+  local prevShader = love.graphics.getShader()
+  local prevColor = { love.graphics.getColor() }
+  local prevBlendMode = love.graphics.getBlendMode()
+
+  -- Render content to first canvas
+  love.graphics.setCanvas(canvas1)
+  love.graphics.clear()
+  love.graphics.push()
+  love.graphics.origin()
+  love.graphics.translate(-x, -y)
+  drawFunc()
+  love.graphics.pop()
+
+  -- Apply blur passes
+  love.graphics.setShader(blurInstance.shader)
+  love.graphics.setColor(1, 1, 1, 1)
+  love.graphics.setBlendMode("alpha", "premultiplied")
+
+  for i = 1, passes do
+    -- Horizontal pass
+    love.graphics.setCanvas(canvas2)
+    love.graphics.clear()
+    blurInstance.shader:send("direction", { 1 / width, 0 })
+    love.graphics.draw(canvas1, 0, 0)
+
+    -- Vertical pass
+    love.graphics.setCanvas(canvas1)
+    love.graphics.clear()
+    blurInstance.shader:send("direction", { 0, 1 / height })
+    love.graphics.draw(canvas2, 0, 0)
+  end
+
+  -- Draw blurred result to screen
+  love.graphics.setCanvas(prevCanvas)
+  love.graphics.setShader()
+  love.graphics.setBlendMode(prevBlendMode)
+  love.graphics.draw(canvas1, x, y)
+
+  -- Restore graphics state
+  love.graphics.setShader(prevShader)
+  love.graphics.setColor(unpack(prevColor))
+
+  -- Release canvases back to cache
+  releaseCanvas(canvas1)
+  releaseCanvas(canvas2)
+end
+
+--- Apply backdrop blur effect (blur content behind a region)
+---@param blurInstance table -- Blur effect instance from Blur.new()
+---@param intensity number -- Blur intensity (0-100)
+---@param x number -- X position
+---@param y number -- Y position
+---@param width number -- Width
+---@param height number -- Height
+---@param backdropCanvas love.Canvas -- Canvas containing the backdrop content
+function Blur.applyBackdrop(blurInstance, intensity, x, y, width, height, backdropCanvas)
+  if intensity <= 0 or width <= 0 or height <= 0 then
+    return
+  end
+
+  -- Clamp intensity
+  intensity = math.max(0, math.min(100, intensity))
+
+  -- Calculate blur passes based on intensity
+  local passes = math.ceil(intensity / 20)
+  passes = math.max(1, math.min(5, passes))
+
+  -- Get canvases for ping-pong rendering
+  local canvas1 = getCanvas(width, height)
+  local canvas2 = getCanvas(width, height)
+
+  -- Save graphics state
+  local prevCanvas = love.graphics.getCanvas()
+  local prevShader = love.graphics.getShader()
+  local prevColor = { love.graphics.getColor() }
+  local prevBlendMode = love.graphics.getBlendMode()
+
+  -- Extract the region from backdrop
+  love.graphics.setCanvas(canvas1)
+  love.graphics.clear()
+  love.graphics.setColor(1, 1, 1, 1)
+  love.graphics.setBlendMode("alpha", "premultiplied")
+
+  -- Create a quad for the region
+  local backdropWidth, backdropHeight = backdropCanvas:getDimensions()
+  local quad = love.graphics.newQuad(x, y, width, height, backdropWidth, backdropHeight)
+  love.graphics.draw(backdropCanvas, quad, 0, 0)
+
+  -- Apply blur passes
+  love.graphics.setShader(blurInstance.shader)
+
+  for i = 1, passes do
+    -- Horizontal pass
+    love.graphics.setCanvas(canvas2)
+    love.graphics.clear()
+    blurInstance.shader:send("direction", { 1 / width, 0 })
+    love.graphics.draw(canvas1, 0, 0)
+
+    -- Vertical pass
+    love.graphics.setCanvas(canvas1)
+    love.graphics.clear()
+    blurInstance.shader:send("direction", { 0, 1 / height })
+    love.graphics.draw(canvas2, 0, 0)
+  end
+
+  -- Draw blurred result to screen
+  love.graphics.setCanvas(prevCanvas)
+  love.graphics.setShader()
+  love.graphics.setBlendMode(prevBlendMode)
+  love.graphics.draw(canvas1, x, y)
+
+  -- Restore graphics state
+  love.graphics.setShader(prevShader)
+  love.graphics.setColor(unpack(prevColor))
+
+  -- Release canvases back to cache
+  releaseCanvas(canvas1)
+  releaseCanvas(canvas2)
+end
+
+--- Clear canvas cache (call on window resize)
+function Blur.clearCache()
+  canvasCache = {}
+end
+
+return Blur

flexlove/Color.lua

@@ -0,0 +1,80 @@
+--[[
+Color.lua - Color utility class for FlexLove
+Provides color handling with RGB/RGBA support and hex string conversion
+]]
+
+-- ====================
+-- Error Handling Utilities
+-- ====================
+
+--- Standardized error message formatter
+---@param module string -- Module name (e.g., "Color", "Theme", "Units")
+---@param message string -- Error message
+---@return string -- Formatted error message
+local function formatError(module, message)
+  return string.format("[FlexLove.%s] %s", module, message)
+end
+
+-- ====================
+-- Color System
+-- ====================
+
+--- Utility class for color handling
+---@class Color
+---@field r number -- Red component (0-1)
+---@field g number -- Green component (0-1)
+---@field b number -- Blue component (0-1)
+---@field a number -- Alpha component (0-1)
+local Color = {}
+Color.__index = Color
+
+--- Create a new color instance
+---@param r number? -- Default: 0
+---@param g number? -- Default: 0
+---@param b number? -- Default: 0
+---@param a number? -- Default: 1
+---@return Color
+function Color.new(r, g, b, a)
+  local self = setmetatable({}, Color)
+  self.r = r or 0
+  self.g = g or 0
+  self.b = b or 0
+  self.a = a or 1
+  return self
+end
+
+---@return number r, number g, number b, number a
+function Color:toRGBA()
+  return self.r, self.g, self.b, self.a
+end
+
+--- Convert hex string to color
+--- Supports both 6-digit (#RRGGBB) and 8-digit (#RRGGBBAA) hex formats
+---@param hexWithTag string -- e.g. "#RRGGBB" or "#RRGGBBAA"
+---@return Color
+---@throws Error if hex string format is invalid
+function Color.fromHex(hexWithTag)
+  local hex = hexWithTag:gsub("#", "")
+  if #hex == 6 then
+    local r = tonumber("0x" .. hex:sub(1, 2))
+    local g = tonumber("0x" .. hex:sub(3, 4))
+    local b = tonumber("0x" .. hex:sub(5, 6))
+    if not r or not g or not b then
+      error(formatError("Color", string.format("Invalid hex string format: '%s'. Contains invalid hex digits", hexWithTag)))
+    end
+    return Color.new(r / 255, g / 255, b / 255, 1)
+  elseif #hex == 8 then
+    local r = tonumber("0x" .. hex:sub(1, 2))
+    local g = tonumber("0x" .. hex:sub(3, 4))
+    local b = tonumber("0x" .. hex:sub(5, 6))
+    local a = tonumber("0x" .. hex:sub(7, 8))
+    if not r or not g or not b or not a then
+      error(formatError("Color", string.format("Invalid hex string format: '%s'. Contains invalid hex digits", hexWithTag)))
+    end
+    return Color.new(r / 255, g / 255, b / 255, a / 255)
+  else
+    error(formatError("Color", string.format("Invalid hex string format: '%s'. Expected #RRGGBB or #RRGGBBAA", hexWithTag)))
+  end
+end
+
+return Color

flexlove/ImageCache.lua

@@ -0,0 +1,157 @@
+--[[
+ImageCache.lua - Image caching system for FlexLove
+Provides efficient image loading and caching with memory management
+]]
+
+-- ====================
+-- ImageCache
+-- ====================
+
+---@class ImageCache
+---@field _cache table<string, {image: love.Image, imageData: love.ImageData?}>
+local ImageCache = {}
+ImageCache._cache = {}
+
+--- Normalize a file path for consistent cache keys
+---@param path string -- File path to normalize
+---@return string -- Normalized path
+local function normalizePath(path)
+  -- Remove leading/trailing whitespace
+  path = path:match("^%s*(.-)%s*$")
+  -- Convert backslashes to forward slashes
+  path = path:gsub("\\", "/")
+  -- Remove redundant slashes
+  path = path:gsub("/+", "/")
+  return path
+end
+
+--- Load an image from file path with caching
+--- Returns cached image if already loaded, otherwise loads and caches it
+---@param imagePath string -- Path to image file
+---@param loadImageData boolean? -- Optional: also load ImageData for pixel access (default: false)
+---@return love.Image|nil -- Image object or nil on error
+---@return string|nil -- Error message if loading failed
+function ImageCache.load(imagePath, loadImageData)
+  if not imagePath or type(imagePath) ~= "string" or imagePath == "" then
+    return nil, "Invalid image path: path must be a non-empty string"
+  end
+
+  local normalizedPath = normalizePath(imagePath)
+
+  -- Check if already cached
+  if ImageCache._cache[normalizedPath] then
+    return ImageCache._cache[normalizedPath].image, nil
+  end
+
+  -- Try to load the image
+  local success, imageOrError = pcall(love.graphics.newImage, normalizedPath)
+  if not success then
+    return nil, string.format("Failed to load image '%s': %s", imagePath, tostring(imageOrError))
+  end
+
+  local image = imageOrError
+  local imgData = nil
+
+  -- Load ImageData if requested
+  if loadImageData then
+    local dataSuccess, dataOrError = pcall(love.image.newImageData, normalizedPath)
+    if dataSuccess then
+      imgData = dataOrError
+    end
+  end
+
+  -- Cache the image
+  ImageCache._cache[normalizedPath] = {
+    image = image,
+    imageData = imgData,
+  }
+
+  return image, nil
+end
+
+--- Get a cached image without loading
+---@param imagePath string -- Path to image file
+---@return love.Image|nil -- Cached image or nil if not found
+function ImageCache.get(imagePath)
+  if not imagePath or type(imagePath) ~= "string" then
+    return nil
+  end
+
+  local normalizedPath = normalizePath(imagePath)
+  local cached = ImageCache._cache[normalizedPath]
+  return cached and cached.image or nil
+end
+
+--- Get cached ImageData for an image
+---@param imagePath string -- Path to image file
+---@return love.ImageData|nil -- Cached ImageData or nil if not found
+function ImageCache.getImageData(imagePath)
+  if not imagePath or type(imagePath) ~= "string" then
+    return nil
+  end
+
+  local normalizedPath = normalizePath(imagePath)
+  local cached = ImageCache._cache[normalizedPath]
+  return cached and cached.imageData or nil
+end
+
+--- Remove a specific image from cache
+---@param imagePath string -- Path to image file to remove
+---@return boolean -- True if image was removed, false if not found
+function ImageCache.remove(imagePath)
+  if not imagePath or type(imagePath) ~= "string" then
+    return false
+  end
+
+  local normalizedPath = normalizePath(imagePath)
+  if ImageCache._cache[normalizedPath] then
+    -- Release the image
+    local cached = ImageCache._cache[normalizedPath]
+    if cached.image then
+      cached.image:release()
+    end
+    if cached.imageData then
+      cached.imageData:release()
+    end
+    ImageCache._cache[normalizedPath] = nil
+    return true
+  end
+  return false
+end
+
+--- Clear all cached images
+function ImageCache.clear()
+  -- Release all images
+  for path, cached in pairs(ImageCache._cache) do
+    if cached.image then
+      cached.image:release()
+    end
+    if cached.imageData then
+      cached.imageData:release()
+    end
+  end
+  ImageCache._cache = {}
+end
+
+--- Get cache statistics
+---@return {count: number, memoryEstimate: number} -- Cache stats
+function ImageCache.getStats()
+  local count = 0
+  local memoryEstimate = 0
+
+  for path, cached in pairs(ImageCache._cache) do
+    count = count + 1
+    if cached.image then
+      local w, h = cached.image:getDimensions()
+      -- Estimate: 4 bytes per pixel (RGBA)
+      memoryEstimate = memoryEstimate + (w * h * 4)
+    end
+  end
+
+  return {
+    count = count,
+    memoryEstimate = memoryEstimate,
+  }
+end
+
+return ImageCache

flexlove/ImageDataReader.lua

@@ -0,0 +1,113 @@
+--[[
+ImageDataReader.lua - Image data reading utilities for FlexLove
+Provides functions to load and read pixel data from images
+]]
+
+-- ====================
+-- Error Handling Utilities
+-- ====================
+
+--- Standardized error message formatter
+---@param module string -- Module name (e.g., "Color", "Theme", "Units")
+---@param message string -- Error message
+---@return string -- Formatted error message
+local function formatError(module, message)
+  return string.format("[FlexLove.%s] %s", module, message)
+end
+
+-- ====================
+-- ImageDataReader
+-- ====================
+
+local ImageDataReader = {}
+
+--- Load ImageData from a file path
+---@param imagePath string
+---@return love.ImageData
+function ImageDataReader.loadImageData(imagePath)
+  if not imagePath then
+    error(formatError("ImageDataReader", "Image path cannot be nil"))
+  end
+
+  local success, result = pcall(function()
+    return love.image.newImageData(imagePath)
+  end)
+
+  if not success then
+    error(formatError("ImageDataReader", "Failed to load image data from '" .. imagePath .. "': " .. tostring(result)))
+  end
+
+  return result
+end
+
+--- Extract all pixels from a specific row
+---@param imageData love.ImageData
+---@param rowIndex number -- 0-based row index
+---@return table -- Array of {r, g, b, a} values (0-255 range)
+function ImageDataReader.getRow(imageData, rowIndex)
+  if not imageData then
+    error(formatError("ImageDataReader", "ImageData cannot be nil"))
+  end
+
+  local width = imageData:getWidth()
+  local height = imageData:getHeight()
+
+  if rowIndex < 0 or rowIndex >= height then
+    error(formatError("ImageDataReader", string.format("Row index %d out of bounds (height: %d)", rowIndex, height)))
+  end
+
+  local pixels = {}
+  for x = 0, width - 1 do
+    local r, g, b, a = imageData:getPixel(x, rowIndex)
+    table.insert(pixels, {
+      r = math.floor(r * 255 + 0.5),
+      g = math.floor(g * 255 + 0.5),
+      b = math.floor(b * 255 + 0.5),
+      a = math.floor(a * 255 + 0.5),
+    })
+  end
+
+  return pixels
+end
+
+--- Extract all pixels from a specific column
+---@param imageData love.ImageData
+---@param colIndex number -- 0-based column index
+---@return table -- Array of {r, g, b, a} values (0-255 range)
+function ImageDataReader.getColumn(imageData, colIndex)
+  if not imageData then
+    error(formatError("ImageDataReader", "ImageData cannot be nil"))
+  end
+
+  local width = imageData:getWidth()
+  local height = imageData:getHeight()
+
+  if colIndex < 0 or colIndex >= width then
+    error(formatError("ImageDataReader", string.format("Column index %d out of bounds (width: %d)", colIndex, width)))
+  end
+
+  local pixels = {}
+  for y = 0, height - 1 do
+    local r, g, b, a = imageData:getPixel(colIndex, y)
+    table.insert(pixels, {
+      r = math.floor(r * 255 + 0.5),
+      g = math.floor(g * 255 + 0.5),
+      b = math.floor(b * 255 + 0.5),
+      a = math.floor(a * 255 + 0.5),
+    })
+  end
+
+  return pixels
+end
+
+--- Check if a pixel is black with full alpha (9-patch marker)
+---@param r number -- Red (0-255)
+---@param g number -- Green (0-255)
+---@param b number -- Blue (0-255)
+---@param a number -- Alpha (0-255)
+---@return boolean
+function ImageDataReader.isBlackPixel(r, g, b, a)
+  return r == 0 and g == 0 and b == 0 and a == 255
+end
+
+return ImageDataReader

flexlove/ImageRenderer.lua

@@ -0,0 +1,234 @@
+--[[
+ImageRenderer.lua - Image rendering utilities for FlexLove
+Provides object-fit modes and object-position support for image rendering
+]]
+
+-- ====================
+-- Error Handling Utilities
+-- ====================
+
+--- Standardized error message formatter
+---@param module string -- Module name (e.g., "Color", "Theme", "Units")
+---@param message string -- Error message
+---@return string -- Formatted error message
+local function formatError(module, message)
+  return string.format("[FlexLove.%s] %s", module, message)
+end
+
+-- ====================
+-- ImageRenderer
+-- ====================
+
+---@class ImageRenderer
+local ImageRenderer = {}
+
+--- Calculate rendering parameters for object-fit modes
+--- Returns source and destination rectangles for rendering
+---@param imageWidth number -- Natural width of the image
+---@param imageHeight number -- Natural height of the image
+---@param boundsWidth number -- Width of the bounds to fit within
+---@param boundsHeight number -- Height of the bounds to fit within
+---@param fitMode string? -- One of: "fill", "contain", "cover", "scale-down", "none" (default: "fill")
+---@param objectPosition string? -- Position like "center center", "top left", "50% 50%" (default: "center center")
+---@return {sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number, scaleX: number, scaleY: number}
+function ImageRenderer.calculateFit(imageWidth, imageHeight, boundsWidth, boundsHeight, fitMode, objectPosition)
+  fitMode = fitMode or "fill"
+  objectPosition = objectPosition or "center center"
+
+  -- Validate inputs
+  if imageWidth <= 0 or imageHeight <= 0 or boundsWidth <= 0 or boundsHeight <= 0 then
+    error(formatError("ImageRenderer", "Dimensions must be positive"))
+  end
+
+  local result = {
+    sx = 0, -- Source X
+    sy = 0, -- Source Y
+    sw = imageWidth, -- Source width
+    sh = imageHeight, -- Source height
+    dx = 0, -- Destination X
+    dy = 0, -- Destination Y
+    dw = boundsWidth, -- Destination width
+    dh = boundsHeight, -- Destination height
+    scaleX = 1, -- Scale factor X
+    scaleY = 1, -- Scale factor Y
+  }
+
+  -- Calculate based on fit mode
+  if fitMode == "fill" then
+    -- Stretch to fill bounds (may distort)
+    result.scaleX = boundsWidth / imageWidth
+    result.scaleY = boundsHeight / imageHeight
+    result.dw = boundsWidth
+    result.dh = boundsHeight
+  elseif fitMode == "contain" then
+    -- Scale to fit within bounds (preserves aspect ratio)
+    local scale = math.min(boundsWidth / imageWidth, boundsHeight / imageHeight)
+    result.scaleX = scale
+    result.scaleY = scale
+    result.dw = imageWidth * scale
+    result.dh = imageHeight * scale
+
+    -- Apply object-position for letterbox alignment
+    local posX, posY = ImageRenderer._parsePosition(objectPosition)
+    result.dx = (boundsWidth - result.dw) * posX
+    result.dy = (boundsHeight - result.dh) * posY
+  elseif fitMode == "cover" then
+    -- Scale to cover bounds (preserves aspect ratio, may crop)
+    local scale = math.max(boundsWidth / imageWidth, boundsHeight / imageHeight)
+    result.scaleX = scale
+    result.scaleY = scale
+
+    local scaledWidth = imageWidth * scale
+    local scaledHeight = imageHeight * scale
+
+    -- Apply object-position for crop alignment
+    local posX, posY = ImageRenderer._parsePosition(objectPosition)
+
+    -- Calculate which part of the scaled image to show
+    local cropX = (scaledWidth - boundsWidth) * posX
+    local cropY = (scaledHeight - boundsHeight) * posY
+
+    -- Convert back to source coordinates
+    result.sx = cropX / scale
+    result.sy = cropY / scale
+    result.sw = boundsWidth / scale
+    result.sh = boundsHeight / scale
+
+    result.dx = 0
+    result.dy = 0
+    result.dw = boundsWidth
+    result.dh = boundsHeight
+  elseif fitMode == "none" then
+    -- Use natural size (no scaling)
+    result.scaleX = 1
+    result.scaleY = 1
+    result.dw = imageWidth
+    result.dh = imageHeight
+
+    -- Apply object-position
+    local posX, posY = ImageRenderer._parsePosition(objectPosition)
+    result.dx = (boundsWidth - imageWidth) * posX
+    result.dy = (boundsHeight - imageHeight) * posY
+  elseif fitMode == "scale-down" then
+    -- Use none or contain, whichever is smaller
+    if imageWidth <= boundsWidth and imageHeight <= boundsHeight then
+      -- Image fits naturally, use "none"
+      return ImageRenderer.calculateFit(imageWidth, imageHeight, boundsWidth, boundsHeight, "none", objectPosition)
+    else
+      -- Image too large, use "contain"
+      return ImageRenderer.calculateFit(imageWidth, imageHeight, boundsWidth, boundsHeight, "contain", objectPosition)
+    end
+  else
+    error(formatError("ImageRenderer", string.format("Invalid fit mode: '%s'. Must be one of: fill, contain, cover, scale-down, none", tostring(fitMode))))
+  end
+
+  return result
+end
+
+--- Parse object-position string into normalized coordinates (0-1)
+--- Supports keywords (center, top, bottom, left, right) and percentages
+---@param position string -- Position string like "center center", "top left", "50% 50%"
+---@return number, number -- Normalized X and Y positions (0-1)
+function ImageRenderer._parsePosition(position)
+  if not position or type(position) ~= "string" then
+    return 0.5, 0.5 -- Default to center
+  end
+
+  -- Split into X and Y components
+  local parts = {}
+  for part in position:gmatch("%S+") do
+    table.insert(parts, part:lower())
+  end
+
+  -- If only one value, use it for both axes (with special handling)
+  if #parts == 1 then
+    local val = parts[1]
+    if val == "left" or val == "right" then
+      parts = { val, "center" }
+    elseif val == "top" or val == "bottom" then
+      parts = { "center", val }
+    else
+      parts = { val, val }
+    end
+  elseif #parts == 0 then
+    return 0.5, 0.5 -- Default to center
+  end
+
+  local function parseValue(val)
+    -- Handle keywords
+    if val == "center" then
+      return 0.5
+    elseif val == "left" or val == "top" then
+      return 0
+    elseif val == "right" or val == "bottom" then
+      return 1
+    end
+
+    -- Handle percentages
+    local percent = val:match("^([%d%.]+)%%$")
+    if percent then
+      return tonumber(percent) / 100
+    end
+
+    -- Handle plain numbers (treat as percentage)
+    local num = tonumber(val)
+    if num then
+      return num / 100
+    end
+
+    -- Invalid value, default to center
+    return 0.5
+  end
+
+  local x = parseValue(parts[1])
+  local y = parseValue(parts[2] or parts[1])
+
+  -- Clamp to 0-1 range
+  x = math.max(0, math.min(1, x))
+  y = math.max(0, math.min(1, y))
+
+  return x, y
+end
+
+--- Draw an image with specified object-fit mode
+---@param image love.Image -- Image to draw
+---@param x number -- X position of bounds
+---@param y number -- Y position of bounds
+---@param width number -- Width of bounds
+---@param height number -- Height of bounds
+---@param fitMode string? -- Object-fit mode (default: "fill")
+---@param objectPosition string? -- Object-position (default: "center center")
+---@param opacity number? -- Opacity 0-1 (default: 1)
+function ImageRenderer.draw(image, x, y, width, height, fitMode, objectPosition, opacity)
+  if not image then
+    return -- Nothing to draw
+  end
+
+  opacity = opacity or 1
+  fitMode = fitMode or "fill"
+  objectPosition = objectPosition or "center center"
+
+  local imgWidth, imgHeight = image:getDimensions()
+  local params = ImageRenderer.calculateFit(imgWidth, imgHeight, width, height, fitMode, objectPosition)
+
+  -- Save current color
+  local r, g, b, a = love.graphics.getColor()
+
+  -- Apply opacity
+  love.graphics.setColor(1, 1, 1, opacity)
+
+  -- Draw image
+  if params.sx ~= 0 or params.sy ~= 0 or params.sw ~= imgWidth or params.sh ~= imgHeight then
+    -- Need to use a quad for cropping
+    local quad = love.graphics.newQuad(params.sx, params.sy, params.sw, params.sh, imgWidth, imgHeight)
+    love.graphics.draw(image, quad, x + params.dx, y + params.dy, 0, params.dw / params.sw, params.dh / params.sh)
+  else
+    -- Simple draw with scaling
+    love.graphics.draw(image, x + params.dx, y + params.dy, 0, params.scaleX, params.scaleY)
+  end
+
+  -- Restore color
+  love.graphics.setColor(r, g, b, a)
+end
+
+return ImageRenderer

flexlove/ImageScaler.lua

@@ -0,0 +1,156 @@
+--[[
+ImageScaler.lua - Image scaling utilities for FlexLove
+Provides nearest-neighbor and bilinear interpolation scaling algorithms
+]]
+
+-- ====================
+-- Error Handling Utilities
+-- ====================
+
+--- Standardized error message formatter
+---@param module string -- Module name (e.g., "Color", "Theme", "Units")
+---@param message string -- Error message
+---@return string -- Formatted error message
+local function formatError(module, message)
+  return string.format("[FlexLove.%s] %s", module, message)
+end
+
+-- ====================
+-- ImageScaler
+-- ====================
+
+local ImageScaler = {}
+
+--- Scale an ImageData region using nearest-neighbor sampling
+--- Produces sharp, pixelated scaling - ideal for pixel art
+---@param sourceImageData love.ImageData -- Source image data
+---@param srcX number -- Source region X (0-based)
+---@param srcY number -- Source region Y (0-based)
+---@param srcW number -- Source region width
+---@param srcH number -- Source region height
+---@param destW number -- Destination width
+---@param destH number -- Destination height
+---@return love.ImageData -- Scaled image data
+function ImageScaler.scaleNearest(sourceImageData, srcX, srcY, srcW, srcH, destW, destH)
+  if not sourceImageData then
+    error(formatError("ImageScaler", "Source ImageData cannot be nil"))
+  end
+
+  if srcW <= 0 or srcH <= 0 or destW <= 0 or destH <= 0 then
+    error(formatError("ImageScaler", "Dimensions must be positive"))
+  end
+
+  -- Create destination ImageData
+  local destImageData = love.image.newImageData(destW, destH)
+
+  -- Calculate scale ratios (cached outside loops for performance)
+  local scaleX = srcW / destW
+  local scaleY = srcH / destH
+
+  -- Nearest-neighbor sampling
+  for destY = 0, destH - 1 do
+    for destX = 0, destW - 1 do
+      -- Calculate source pixel coordinates using floor (nearest-neighbor)
+      local srcPixelX = math.floor(destX * scaleX) + srcX
+      local srcPixelY = math.floor(destY * scaleY) + srcY
+
+      -- Clamp to source bounds (safety check)
+      srcPixelX = math.min(srcPixelX, srcX + srcW - 1)
+      srcPixelY = math.min(srcPixelY, srcY + srcH - 1)
+
+      -- Sample source pixel
+      local r, g, b, a = sourceImageData:getPixel(srcPixelX, srcPixelY)
+
+      -- Write to destination
+      destImageData:setPixel(destX, destY, r, g, b, a)
+    end
+  end
+
+  return destImageData
+end
+
+--- Linear interpolation helper
+--- Blends between two values based on interpolation factor
+---@param a number -- Start value
+---@param b number -- End value
+---@param t number -- Interpolation factor [0, 1]
+---@return number -- Interpolated value
+local function lerp(a, b, t)
+  return a + (b - a) * t
+end
+
+--- Scale an ImageData region using bilinear interpolation
+--- Produces smooth, filtered scaling - ideal for high-quality upscaling
+---@param sourceImageData love.ImageData -- Source image data
+---@param srcX number -- Source region X (0-based)
+---@param srcY number -- Source region Y (0-based)
+---@param srcW number -- Source region width
+---@param srcH number -- Source region height
+---@param destW number -- Destination width
+---@param destH number -- Destination height
+---@return love.ImageData -- Scaled image data
+function ImageScaler.scaleBilinear(sourceImageData, srcX, srcY, srcW, srcH, destW, destH)
+  if not sourceImageData then
+    error(formatError("ImageScaler", "Source ImageData cannot be nil"))
+  end
+
+  if srcW <= 0 or srcH <= 0 or destW <= 0 or destH <= 0 then
+    error(formatError("ImageScaler", "Dimensions must be positive"))
+  end
+
+  -- Create destination ImageData
+  local destImageData = love.image.newImageData(destW, destH)
+
+  -- Calculate scale ratios
+  local scaleX = srcW / destW
+  local scaleY = srcH / destH
+
+  -- Bilinear interpolation
+  for destY = 0, destH - 1 do
+    for destX = 0, destW - 1 do
+      -- Calculate fractional source position
+      local srcXf = destX * scaleX
+      local srcYf = destY * scaleY
+
+      -- Get integer coordinates for 2x2 sampling grid
+      local x0 = math.floor(srcXf)
+      local y0 = math.floor(srcYf)
+      local x1 = math.min(x0 + 1, srcW - 1)
+      local y1 = math.min(y0 + 1, srcH - 1)
+
+      -- Get fractional parts for interpolation
+      local fx = srcXf - x0
+      local fy = srcYf - y0
+
+      -- Sample 4 neighboring pixels (with source offset)
+      local r00, g00, b00, a00 = sourceImageData:getPixel(srcX + x0, srcY + y0)
+      local r10, g10, b10, a10 = sourceImageData:getPixel(srcX + x1, srcY + y0)
+      local r01, g01, b01, a01 = sourceImageData:getPixel(srcX + x0, srcY + y1)
+      local r11, g11, b11, a11 = sourceImageData:getPixel(srcX + x1, srcY + y1)
+
+      -- Interpolate horizontally (top and bottom rows)
+      local rTop = lerp(r00, r10, fx)
+      local gTop = lerp(g00, g10, fx)
+      local bTop = lerp(b00, b10, fx)
+      local aTop = lerp(a00, a10, fx)
+
+      local rBottom = lerp(r01, r11, fx)
+      local gBottom = lerp(g01, g11, fx)
+      local bBottom = lerp(b01, b11, fx)
+      local aBottom = lerp(a01, a11, fx)
+
+      -- Interpolate vertically (final result)
+      local r = lerp(rTop, rBottom, fy)
+      local g = lerp(gTop, gBottom, fy)
+      local b = lerp(bTop, bBottom, fy)
+      local a = lerp(aTop, aBottom, fy)
+
+      -- Write to destination
+      destImageData:setPixel(destX, destY, r, g, b, a)
+    end
+  end
+
+  return destImageData
+end
+
+return ImageScaler

flexlove/NinePatchParser.lua

@@ -0,0 +1,177 @@
+--[[
+NinePatchParser.lua - 9-patch PNG parser for FlexLove
+Parses Android-style 9-patch images to extract stretch regions and content padding
+]]
+
+-- ====================
+-- Error Handling Utilities
+-- ====================
+
+--- Standardized error message formatter
+---@param module string -- Module name (e.g., "Color", "Theme", "Units")
+---@param message string -- Error message
+---@return string -- Formatted error message
+local function formatError(module, message)
+  return string.format("[FlexLove.%s] %s", module, message)
+end
+
+-- ====================
+-- Dependencies
+-- ====================
+
+local ImageDataReader = require((...):match("(.-)[^%.]+$") .. "ImageDataReader")
+
+-- ====================
+-- NinePatchParser
+-- ====================
+
+local NinePatchParser = {}
+
+--- Find all continuous runs of black pixels in a pixel array
+---@param pixels table -- Array of {r, g, b, a} pixel values
+---@return table -- Array of {start, end} pairs (1-based indices, inclusive)
+local function findBlackPixelRuns(pixels)
+  local runs = {}
+  local inRun = false
+  local runStart = nil
+
+  for i = 1, #pixels do
+    local pixel = pixels[i]
+    local isBlack = ImageDataReader.isBlackPixel(pixel.r, pixel.g, pixel.b, pixel.a)
+
+    if isBlack and not inRun then
+      -- Start of a new run
+      inRun = true
+      runStart = i
+    elseif not isBlack and inRun then
+      -- End of current run
+      table.insert(runs, { start = runStart, ["end"] = i - 1 })
+      inRun = false
+      runStart = nil
+    end
+  end
+
+  -- Handle case where run extends to end of array
+  if inRun then
+    table.insert(runs, { start = runStart, ["end"] = #pixels })
+  end
+
+  return runs
+end
+
+--- Parse a 9-patch PNG image to extract stretch regions and content padding
+---@param imagePath string -- Path to the 9-patch image file
+---@return table|nil, string|nil -- Returns {insets, stretchX, stretchY} or nil, error message
+function NinePatchParser.parse(imagePath)
+  if not imagePath then
+    return nil, "Image path cannot be nil"
+  end
+
+  local success, imageData = pcall(function()
+    return ImageDataReader.loadImageData(imagePath)
+  end)
+
+  if not success then
+    return nil, "Failed to load image data: " .. tostring(imageData)
+  end
+
+  local width = imageData:getWidth()
+  local height = imageData:getHeight()
+
+  -- Validate minimum size (must be at least 3x3 with 1px border)
+  if width < 3 or height < 3 then
+    return nil, string.format("Invalid 9-patch dimensions: %dx%d (minimum 3x3)", width, height)
+  end
+
+  -- Extract border pixels (0-based indexing, but we convert to 1-based for processing)
+  local topBorder = ImageDataReader.getRow(imageData, 0)
+  local leftBorder = ImageDataReader.getColumn(imageData, 0)
+  local bottomBorder = ImageDataReader.getRow(imageData, height - 1)
+  local rightBorder = ImageDataReader.getColumn(imageData, width - 1)
+
+  -- Remove corner pixels from borders (they're not part of the stretch/content markers)
+  -- Top and bottom borders: remove first and last pixel
+  local topStretchPixels = {}
+  local bottomContentPixels = {}
+  for i = 2, #topBorder - 1 do
+    table.insert(topStretchPixels, topBorder[i])
+  end
+  for i = 2, #bottomBorder - 1 do
+    table.insert(bottomContentPixels, bottomBorder[i])
+  end
+
+  -- Left and right borders: remove first and last pixel
+  local leftStretchPixels = {}
+  local rightContentPixels = {}
+  for i = 2, #leftBorder - 1 do
+    table.insert(leftStretchPixels, leftBorder[i])
+  end
+  for i = 2, #rightBorder - 1 do
+    table.insert(rightContentPixels, rightBorder[i])
+  end
+
+  -- Find stretch regions (top and left borders)
+  local stretchX = findBlackPixelRuns(topStretchPixels)
+  local stretchY = findBlackPixelRuns(leftStretchPixels)
+
+  -- Find content padding regions (bottom and right borders)
+  local contentX = findBlackPixelRuns(bottomContentPixels)
+  local contentY = findBlackPixelRuns(rightContentPixels)
+
+  -- Validate that we have at least one stretch region
+  if #stretchX == 0 or #stretchY == 0 then
+    return nil, "No stretch regions found (top or left border has no black pixels)"
+  end
+
+  -- Calculate stretch insets from stretch regions (top/left guides)
+  -- Use the first stretch region's start and last stretch region's end
+  local firstStretchX = stretchX[1]
+  local lastStretchX = stretchX[#stretchX]
+  local firstStretchY = stretchY[1]
+  local lastStretchY = stretchY[#stretchY]
+
+  -- Stretch insets define the 9-slice regions
+  local stretchLeft = firstStretchX.start
+  local stretchRight = #topStretchPixels - lastStretchX["end"]
+  local stretchTop = firstStretchY.start
+  local stretchBottom = #leftStretchPixels - lastStretchY["end"]
+
+  -- Calculate content padding from content guides (bottom/right guides)
+  -- If content padding is defined, use it; otherwise use stretch regions
+  local contentLeft, contentRight, contentTop, contentBottom
+
+  if #contentX > 0 then
+    contentLeft = contentX[1].start
+    contentRight = #topStretchPixels - contentX[#contentX]["end"]
+  else
+    contentLeft = stretchLeft
+    contentRight = stretchRight
+  end
+
+  if #contentY > 0 then
+    contentTop = contentY[1].start
+    contentBottom = #leftStretchPixels - contentY[#contentY]["end"]
+  else
+    contentTop = stretchTop
+    contentBottom = stretchBottom
+  end
+
+  return {
+    insets = {
+      left = stretchLeft,
+      top = stretchTop,
+      right = stretchRight,
+      bottom = stretchBottom,
+    },
+    contentPadding = {
+      left = contentLeft,
+      top = contentTop,
+      right = contentRight,
+      bottom = contentBottom,
+    },
+    stretchX = stretchX,
+    stretchY = stretchY,
+  }
+end
+
+return NinePatchParser

flexlove/NineSlice.lua

@@ -0,0 +1,197 @@
+--[[
+NineSlice - 9-Patch Renderer for FlexLove
+Handles rendering of 9-patch components with Android-style scaling.
+Corners can be scaled independently while edges stretch in one dimension.
+]]
+
+local ImageScaler = require("flexlove.ImageScaler")
+
+--- Standardized error message formatter
+---@param module string -- Module name (e.g., "Color", "Theme", "Units")
+---@param message string -- Error message
+---@return string -- Formatted error message
+local function formatError(module, message)
+  return string.format("[FlexLove.%s] %s", module, message)
+end
+
+local NineSlice = {}
+
+--- Draw a 9-patch component using Android-style rendering
+--- Corners are scaled by scaleCorners multiplier, edges stretch in one dimension only
+---@param component ThemeComponent
+---@param atlas love.Image
+---@param x number -- X position (top-left corner)
+---@param y number -- Y position (top-left corner)
+---@param width number -- Total width (border-box)
+---@param height number -- Total height (border-box)
+---@param opacity number?
+---@param elementScaleCorners number? -- Element-level override for scaleCorners (scale multiplier)
+---@param elementScalingAlgorithm "nearest"|"bilinear"? -- Element-level override for scalingAlgorithm
+function NineSlice.draw(component, atlas, x, y, width, height, opacity, elementScaleCorners, elementScalingAlgorithm)
+  if not component or not atlas then
+    return
+  end
+
+  opacity = opacity or 1
+  love.graphics.setColor(1, 1, 1, opacity)
+
+  local regions = component.regions
+
+  -- Extract border dimensions from regions (in pixels)
+  local left = regions.topLeft.w
+  local right = regions.topRight.w
+  local top = regions.topLeft.h
+  local bottom = regions.bottomLeft.h
+  local centerW = regions.middleCenter.w
+  local centerH = regions.middleCenter.h
+
+  -- Calculate content area (space remaining after borders)
+  local contentWidth = width - left - right
+  local contentHeight = height - top - bottom
+
+  -- Clamp to prevent negative dimensions
+  contentWidth = math.max(0, contentWidth)
+  contentHeight = math.max(0, contentHeight)
+
+  -- Calculate stretch scales for edges and center
+  local scaleX = contentWidth / centerW
+  local scaleY = contentHeight / centerH
+
+  -- Create quads for each region
+  local atlasWidth, atlasHeight = atlas:getDimensions()
+
+  local function makeQuad(region)
+    return love.graphics.newQuad(region.x, region.y, region.w, region.h, atlasWidth, atlasHeight)
+  end
+
+  -- Get corner scale multiplier
+  -- Priority: element-level override > component setting > default (nil = no scaling)
+  local scaleCorners = elementScaleCorners
+  if scaleCorners == nil then
+    scaleCorners = component.scaleCorners
+  end
+
+  -- Priority: element-level override > component setting > default ("bilinear")
+  local scalingAlgorithm = elementScalingAlgorithm
+  if scalingAlgorithm == nil then
+    scalingAlgorithm = component.scalingAlgorithm or "bilinear"
+  end
+
+  if scaleCorners and type(scaleCorners) == "number" and scaleCorners > 0 then
+    -- Initialize cache if needed
+    if not component._scaledRegionCache then
+      component._scaledRegionCache = {}
+    end
+
+    -- Use the numeric scale multiplier directly
+    local scaleFactor = scaleCorners
+
+    -- Helper to get or create scaled region
+    local function getScaledRegion(regionName, region, targetWidth, targetHeight)
+      local cacheKey = string.format("%s_%.2f_%s", regionName, scaleFactor, scalingAlgorithm)
+
+      if component._scaledRegionCache[cacheKey] then
+        return component._scaledRegionCache[cacheKey]
+      end
+
+      -- Get ImageData from component (stored during theme loading)
+      local atlasData = component._loadedAtlasData
+      if not atlasData then
+        error(formatError("NineSlice", "No ImageData available for atlas. Image must be loaded with safeLoadImage."))
+      end
+
+      local scaledData
+
+      if scalingAlgorithm == "nearest" then
+        scaledData = ImageScaler.scaleNearest(atlasData, region.x, region.y, region.w, region.h, targetWidth, targetHeight)
+      else
+        scaledData = ImageScaler.scaleBilinear(atlasData, region.x, region.y, region.w, region.h, targetWidth, targetHeight)
+      end
+
+      -- Convert to image and cache
+      local scaledImage = love.graphics.newImage(scaledData)
+      component._scaledRegionCache[cacheKey] = scaledImage
+
+      return scaledImage
+    end
+
+    -- Calculate scaled dimensions for corners
+    local scaledLeft = math.floor(left * scaleFactor + 0.5)
+    local scaledRight = math.floor(right * scaleFactor + 0.5)
+    local scaledTop = math.floor(top * scaleFactor + 0.5)
+    local scaledBottom = math.floor(bottom * scaleFactor + 0.5)
+
+    -- CORNERS (scaled using algorithm)
+    local topLeftScaled = getScaledRegion("topLeft", regions.topLeft, scaledLeft, scaledTop)
+    local topRightScaled = getScaledRegion("topRight", regions.topRight, scaledRight, scaledTop)
+    local bottomLeftScaled = getScaledRegion("bottomLeft", regions.bottomLeft, scaledLeft, scaledBottom)
+    local bottomRightScaled = getScaledRegion("bottomRight", regions.bottomRight, scaledRight, scaledBottom)
+
+    love.graphics.draw(topLeftScaled, x, y)
+    love.graphics.draw(topRightScaled, x + width - scaledRight, y)
+    love.graphics.draw(bottomLeftScaled, x, y + height - scaledBottom)
+    love.graphics.draw(bottomRightScaled, x + width - scaledRight, y + height - scaledBottom)
+
+    -- Update content dimensions to account for scaled borders
+    local adjustedContentWidth = width - scaledLeft - scaledRight
+    local adjustedContentHeight = height - scaledTop - scaledBottom
+    adjustedContentWidth = math.max(0, adjustedContentWidth)
+    adjustedContentHeight = math.max(0, adjustedContentHeight)
+
+    -- Recalculate stretch scales
+    local adjustedScaleX = adjustedContentWidth / centerW
+    local adjustedScaleY = adjustedContentHeight / centerH
+
+    -- TOP/BOTTOM EDGES (stretch horizontally, scale vertically)
+    if adjustedContentWidth > 0 then
+      local topCenterScaled = getScaledRegion("topCenter", regions.topCenter, regions.topCenter.w, scaledTop)
+      local bottomCenterScaled = getScaledRegion("bottomCenter", regions.bottomCenter, regions.bottomCenter.w, scaledBottom)
+
+      love.graphics.draw(topCenterScaled, x + scaledLeft, y, 0, adjustedScaleX, 1)
+      love.graphics.draw(bottomCenterScaled, x + scaledLeft, y + height - scaledBottom, 0, adjustedScaleX, 1)
+    end
+
+    -- LEFT/RIGHT EDGES (stretch vertically, scale horizontally)
+    if adjustedContentHeight > 0 then
+      local middleLeftScaled = getScaledRegion("middleLeft", regions.middleLeft, scaledLeft, regions.middleLeft.h)
+      local middleRightScaled = getScaledRegion("middleRight", regions.middleRight, scaledRight, regions.middleRight.h)
+
+      love.graphics.draw(middleLeftScaled, x, y + scaledTop, 0, 1, adjustedScaleY)
+      love.graphics.draw(middleRightScaled, x + width - scaledRight, y + scaledTop, 0, 1, adjustedScaleY)
+    end
+
+    -- CENTER (stretch both dimensions, no scaling)
+    if adjustedContentWidth > 0 and adjustedContentHeight > 0 then
+      love.graphics.draw(atlas, makeQuad(regions.middleCenter), x + scaledLeft, y + scaledTop, 0, adjustedScaleX, adjustedScaleY)
+    end
+  else
+    -- Original rendering logic (no scaling)
+    -- CORNERS (no scaling - 1:1 pixel perfect)
+    love.graphics.draw(atlas, makeQuad(regions.topLeft), x, y)
+    love.graphics.draw(atlas, makeQuad(regions.topRight), x + left + contentWidth, y)
+    love.graphics.draw(atlas, makeQuad(regions.bottomLeft), x, y + top + contentHeight)
+    love.graphics.draw(atlas, makeQuad(regions.bottomRight), x + left + contentWidth, y + top + contentHeight)
+
+    -- TOP/BOTTOM EDGES (stretch horizontally only)
+    if contentWidth > 0 then
+      love.graphics.draw(atlas, makeQuad(regions.topCenter), x + left, y, 0, scaleX, 1)
+      love.graphics.draw(atlas, makeQuad(regions.bottomCenter), x + left, y + top + contentHeight, 0, scaleX, 1)
+    end
+
+    -- LEFT/RIGHT EDGES (stretch vertically only)
+    if contentHeight > 0 then
+      love.graphics.draw(atlas, makeQuad(regions.middleLeft), x, y + top, 0, 1, scaleY)
+      love.graphics.draw(atlas, makeQuad(regions.middleRight), x + left + contentWidth, y + top, 0, 1, scaleY)
+    end
+
+    -- CENTER (stretch both dimensions)
+    if contentWidth > 0 and contentHeight > 0 then
+      love.graphics.draw(atlas, makeQuad(regions.middleCenter), x + left, y + top, 0, scaleX, scaleY)
+    end
+  end
+
+  -- Reset color
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+return NineSlice

flexlove/RoundedRect.lua

@@ -0,0 +1,95 @@
+--[[
+RoundedRect - Rounded Rectangle Helper for FlexLove
+Provides functions for generating and drawing rounded rectangles with per-corner radius control.
+]]
+
+local RoundedRect = {}
+
+--- Generate points for a rounded rectangle
+---@param x number
+---@param y number
+---@param width number
+---@param height number
+---@param cornerRadius {topLeft:number, topRight:number, bottomLeft:number, bottomRight:number}
+---@param segments number? -- Number of segments per corner arc (default: 10)
+---@return table -- Array of vertices for love.graphics.polygon
+function RoundedRect.getPoints(x, y, width, height, cornerRadius, segments)
+  segments = segments or 10
+  local points = {}
+
+  -- Helper to add arc points
+  local function addArc(cx, cy, radius, startAngle, endAngle)
+    if radius <= 0 then
+      table.insert(points, cx)
+      table.insert(points, cy)
+      return
+    end
+
+    for i = 0, segments do
+      local angle = startAngle + (endAngle - startAngle) * (i / segments)
+      table.insert(points, cx + math.cos(angle) * radius)
+      table.insert(points, cy + math.sin(angle) * radius)
+    end
+  end
+
+  local r1 = math.min(cornerRadius.topLeft, width / 2, height / 2)
+  local r2 = math.min(cornerRadius.topRight, width / 2, height / 2)
+  local r3 = math.min(cornerRadius.bottomRight, width / 2, height / 2)
+  local r4 = math.min(cornerRadius.bottomLeft, width / 2, height / 2)
+
+  -- Top-right corner
+  addArc(x + width - r2, y + r2, r2, -math.pi / 2, 0)
+
+  -- Bottom-right corner
+  addArc(x + width - r3, y + height - r3, r3, 0, math.pi / 2)
+
+  -- Bottom-left corner
+  addArc(x + r4, y + height - r4, r4, math.pi / 2, math.pi)
+
+  -- Top-left corner
+  addArc(x + r1, y + r1, r1, math.pi, math.pi * 1.5)
+
+  return points
+end
+
+--- Draw a filled rounded rectangle
+---@param mode string -- "fill" or "line"
+---@param x number
+---@param y number
+---@param width number
+---@param height number
+---@param cornerRadius {topLeft:number, topRight:number, bottomLeft:number, bottomRight:number}
+function RoundedRect.draw(mode, x, y, width, height, cornerRadius)
+  -- Check if any corners are rounded
+  local hasRoundedCorners = cornerRadius.topLeft > 0 or cornerRadius.topRight > 0 or cornerRadius.bottomLeft > 0 or cornerRadius.bottomRight > 0
+
+  if not hasRoundedCorners then
+    -- No rounded corners, use regular rectangle
+    love.graphics.rectangle(mode, x, y, width, height)
+    return
+  end
+
+  local points = RoundedRect.getPoints(x, y, width, height, cornerRadius)
+
+  if mode == "fill" then
+    love.graphics.polygon("fill", points)
+  else
+    -- For line mode, draw the outline
+    love.graphics.polygon("line", points)
+  end
+end
+
+--- Create a stencil function for rounded rectangle clipping
+---@param x number
+---@param y number
+---@param width number
+---@param height number
+---@param cornerRadius {topLeft:number, topRight:number, bottomLeft:number, bottomRight:number}
+---@return function
+function RoundedRect.stencilFunction(x, y, width, height, cornerRadius)
+  return function()
+    RoundedRect.draw("fill", x, y, width, height, cornerRadius)
+  end
+end
+
+return RoundedRect

flexlove/Theme.lua

@@ -0,0 +1,493 @@
+--[[
+Theme - Theme System for FlexLove
+Manages theme loading, registration, and component/color/font access.
+Supports 9-patch images, component states, and dynamic theme switching.
+]]
+
+local Color = require("flexlove.Color")
+local NinePatchParser = require("flexlove.NinePatchParser")
+local ImageScaler = require("flexlove.ImageScaler")
+
+--- Standardized error message formatter
+---@param module string -- Module name (e.g., "Color", "Theme", "Units")
+---@param message string -- Error message
+---@return string -- Formatted error message
+local function formatError(module, message)
+  return string.format("[FlexLove.%s] %s", module, message)
+end
+
+--- Auto-detect the base path where FlexLove is located
+---@return string modulePath, string filesystemPath
+local function getFlexLoveBasePath()
+  -- Get debug info to find where this file is loaded from
+  local info = debug.getinfo(1, "S")
+  if info and info.source then
+    local source = info.source
+    -- Remove leading @ if present
+    if source:sub(1, 1) == "@" then
+      source = source:sub(2)
+    end
+
+    -- Extract the directory path (remove Theme.lua and flexlove/)
+    local filesystemPath = source:match("(.*/)")
+    if filesystemPath then
+      -- Store the original filesystem path for loading assets
+      local fsPath = filesystemPath
+      -- Remove leading ./ if present
+      fsPath = fsPath:gsub("^%./", "")
+      -- Remove trailing /
+      fsPath = fsPath:gsub("/$", "")
+      -- Remove the flexlove subdirectory to get back to base
+      fsPath = fsPath:gsub("/flexlove$", "")
+
+      -- Convert filesystem path to Lua module path
+      local modulePath = fsPath:gsub("/", ".")
+
+      return modulePath, fsPath
+    end
+  end
+
+  -- Fallback: try common paths
+  return "libs", "libs"
+end
+
+-- Store the base paths when module loads
+local FLEXLOVE_BASE_PATH, FLEXLOVE_FILESYSTEM_PATH = getFlexLoveBasePath()
+
+--- Helper function to resolve image paths relative to FlexLove
+---@param imagePath string
+---@return string
+local function resolveImagePath(imagePath)
+  -- If path is already absolute or starts with known LÖVE paths, use as-is
+  if imagePath:match("^/") or imagePath:match("^[A-Z]:") then
+    return imagePath
+  end
+
+  -- Otherwise, make it relative to FlexLove's location
+  return FLEXLOVE_FILESYSTEM_PATH .. "/" .. imagePath
+end
+
+--- Safely load an image with error handling
+--- Returns both Image and ImageData to avoid deprecated getData() API
+---@param imagePath string
+---@return love.Image?, love.ImageData?, string? -- Returns image, imageData, or nil with error message
+local function safeLoadImage(imagePath)
+  local success, imageData = pcall(function()
+    return love.image.newImageData(imagePath)
+  end)
+
+  if not success then
+    local errorMsg = string.format("[FlexLove] Failed to load image data: %s - %s", imagePath, tostring(imageData))
+    print(errorMsg)
+    return nil, nil, errorMsg
+  end
+
+  local imageSuccess, image = pcall(function()
+    return love.graphics.newImage(imageData)
+  end)
+
+  if imageSuccess then
+    return image, imageData, nil
+  else
+    local errorMsg = string.format("[FlexLove] Failed to create image: %s - %s", imagePath, tostring(image))
+    print(errorMsg)
+    return nil, nil, errorMsg
+  end
+end
+
+--- Validate theme definition structure
+---@param definition ThemeDefinition
+---@return boolean, string? -- Returns true if valid, or false with error message
+local function validateThemeDefinition(definition)
+  if not definition then
+    return false, "Theme definition is nil"
+  end
+
+  if type(definition) ~= "table" then
+    return false, "Theme definition must be a table"
+  end
+
+  if not definition.name or type(definition.name) ~= "string" then
+    return false, "Theme must have a 'name' field (string)"
+  end
+
+  if definition.components and type(definition.components) ~= "table" then
+    return false, "Theme 'components' must be a table"
+  end
+
+  if definition.colors and type(definition.colors) ~= "table" then
+    return false, "Theme 'colors' must be a table"
+  end
+
+  if definition.fonts and type(definition.fonts) ~= "table" then
+    return false, "Theme 'fonts' must be a table"
+  end
+
+  return true, nil
+end
+
+---@class ThemeRegion
+---@field x number -- X position in atlas
+---@field y number -- Y position in atlas
+---@field w number -- Width in atlas
+---@field h number -- Height in atlas
+
+---@class ThemeComponent
+---@field atlas string|love.Image? -- Optional: component-specific atlas (overrides theme atlas). Files ending in .9.png are auto-parsed
+---@field insets {left:number, top:number, right:number, bottom:number}? -- Optional: 9-patch insets (auto-extracted from .9.png files or manually defined)
+---@field regions {topLeft:ThemeRegion, topCenter:ThemeRegion, topRight:ThemeRegion, middleLeft:ThemeRegion, middleCenter:ThemeRegion, middleRight:ThemeRegion, bottomLeft:ThemeRegion, bottomCenter:ThemeRegion, bottomRight:ThemeRegion}
+---@field stretch {horizontal:table<integer, string>, vertical:table<integer, string>}
+---@field states table<string, ThemeComponent>?
+---@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Optional: multiplier for auto-sized content dimensions
+---@field scaleCorners number? -- Optional: scale multiplier for non-stretched regions (corners/edges). E.g., 2 = 2x size. Default: nil (no scaling)
+---@field scalingAlgorithm "nearest"|"bilinear"? -- Optional: scaling algorithm for non-stretched regions. Default: "bilinear"
+---@field _loadedAtlas string|love.Image? -- Internal: cached loaded atlas image
+---@field _loadedAtlasData love.ImageData? -- Internal: cached loaded atlas ImageData for pixel access
+---@field _ninePatchData {insets:table, contentPadding:table, stretchX:table, stretchY:table}? -- Internal: parsed 9-patch data with stretch regions and content padding
+---@field _scaledRegionCache table<string, love.Image>? -- Internal: cache for scaled corner/edge images
+
+---@class FontFamily
+---@field path string -- Path to the font file (relative to FlexLove or absolute)
+---@field _loadedFont love.Font? -- Internal: cached loaded font
+
+---@class ThemeDefinition
+---@field name string
+---@field atlas string|love.Image? -- Optional: global atlas (can be overridden per component)
+---@field components table<string, ThemeComponent>
+---@field colors table<string, Color>?
+---@field fonts table<string, string>? -- Optional: font family definitions (name -> path)
+---@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Optional: default multiplier for auto-sized content dimensions
+
+---@class Theme
+---@field name string
+---@field atlas love.Image? -- Optional: global atlas
+---@field atlasData love.ImageData?
+---@field components table<string, ThemeComponent>
+---@field colors table<string, Color>
+---@field fonts table<string, string> -- Font family definitions
+---@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Optional: default multiplier for auto-sized content dimensions
+local Theme = {}
+Theme.__index = Theme
+
+-- Global theme registry
+local themes = {}
+local activeTheme = nil
+
+function Theme.new(definition)
+  -- Validate theme definition
+  local valid, err = validateThemeDefinition(definition)
+  if not valid then
+    error("[FlexLove] Invalid theme definition: " .. tostring(err))
+  end
+
+  local self = setmetatable({}, Theme)
+  self.name = definition.name
+
+  -- Load global atlas if it's a string path
+  if definition.atlas then
+    if type(definition.atlas) == "string" then
+      local resolvedPath = resolveImagePath(definition.atlas)
+      local image, imageData, loaderr = safeLoadImage(resolvedPath)
+      if image then
+        self.atlas = image
+        self.atlasData = imageData
+      else
+        print("[FlexLove] Warning: Failed to load global atlas for theme '" .. definition.name .. "'" .. "(" .. loaderr .. ")")
+      end
+    else
+      self.atlas = definition.atlas
+    end
+  end
+
+  self.components = definition.components or {}
+  self.colors = definition.colors or {}
+  self.fonts = definition.fonts or {}
+  self.contentAutoSizingMultiplier = definition.contentAutoSizingMultiplier or nil
+
+  -- Helper function to strip 1-pixel guide border from 9-patch ImageData
+  ---@param sourceImageData love.ImageData
+  ---@return love.ImageData -- New ImageData without guide border
+  local function stripNinePatchBorder(sourceImageData)
+    local srcWidth = sourceImageData:getWidth()
+    local srcHeight = sourceImageData:getHeight()
+
+    -- Content dimensions (excluding 1px border on all sides)
+    local contentWidth = srcWidth - 2
+    local contentHeight = srcHeight - 2
+
+    if contentWidth <= 0 or contentHeight <= 0 then
+      error(formatError("NinePatch", "Image too small to strip border"))
+    end
+
+    -- Create new ImageData for content only
+    local strippedImageData = love.image.newImageData(contentWidth, contentHeight)
+
+    -- Copy pixels from source (1,1) to (width-2, height-2)
+    for y = 0, contentHeight - 1 do
+      for x = 0, contentWidth - 1 do
+        local r, g, b, a = sourceImageData:getPixel(x + 1, y + 1)
+        strippedImageData:setPixel(x, y, r, g, b, a)
+      end
+    end
+
+    return strippedImageData
+  end
+
+  -- Helper function to load atlas with 9-patch support
+  local function loadAtlasWithNinePatch(comp, atlasPath, errorContext)
+    ---@diagnostic disable-next-line
+    local resolvedPath = resolveImagePath(atlasPath)
+    ---@diagnostic disable-next-line
+    local is9Patch = not comp.insets and atlasPath:match("%.9%.png$")
+
+    if is9Patch then
+      local parseResult, parseErr = NinePatchParser.parse(resolvedPath)
+      if parseResult then
+        comp.insets = parseResult.insets
+        comp._ninePatchData = parseResult
+      else
+        print("[FlexLove] Warning: Failed to parse 9-patch " .. errorContext .. ": " .. tostring(parseErr))
+      end
+    end
+
+    local image, imageData, loaderr = safeLoadImage(resolvedPath)
+    if image then
+      -- Strip guide border for 9-patch images
+      if is9Patch and imageData then
+        local strippedImageData = stripNinePatchBorder(imageData)
+        local strippedImage = love.graphics.newImage(strippedImageData)
+        comp._loadedAtlas = strippedImage
+        comp._loadedAtlasData = strippedImageData
+      else
+        comp._loadedAtlas = image
+        comp._loadedAtlasData = imageData
+      end
+    else
+      print("[FlexLove] Warning: Failed to load atlas " .. errorContext .. ": " .. tostring(loaderr))
+    end
+  end
+
+  -- Helper function to create regions from insets
+  local function createRegionsFromInsets(comp, fallbackAtlas)
+    local atlasImage = comp._loadedAtlas or fallbackAtlas
+    if not atlasImage or type(atlasImage) == "string" then
+      return
+    end
+
+    local imgWidth, imgHeight = atlasImage:getDimensions()
+    local left = comp.insets.left or 0
+    local top = comp.insets.top or 0
+    local right = comp.insets.right or 0
+    local bottom = comp.insets.bottom or 0
+
+    -- No offsets needed - guide border has been stripped for 9-patch images
+    local centerWidth = imgWidth - left - right
+    local centerHeight = imgHeight - top - bottom
+
+    comp.regions = {
+      topLeft = { x = 0, y = 0, w = left, h = top },
+      topCenter = { x = left, y = 0, w = centerWidth, h = top },
+      topRight = { x = left + centerWidth, y = 0, w = right, h = top },
+      middleLeft = { x = 0, y = top, w = left, h = centerHeight },
+      middleCenter = { x = left, y = top, w = centerWidth, h = centerHeight },
+      middleRight = { x = left + centerWidth, y = top, w = right, h = centerHeight },
+      bottomLeft = { x = 0, y = top + centerHeight, w = left, h = bottom },
+      bottomCenter = { x = left, y = top + centerHeight, w = centerWidth, h = bottom },
+      bottomRight = { x = left + centerWidth, y = top + centerHeight, w = right, h = bottom },
+    }
+  end
+
+  -- Load component-specific atlases and process 9-patch definitions
+  for componentName, component in pairs(self.components) do
+    if component.atlas then
+      if type(component.atlas) == "string" then
+        loadAtlasWithNinePatch(component, component.atlas, "for component '" .. componentName .. "'")
+      else
+        -- Direct Image object (no ImageData available - scaleCorners won't work)
+        component._loadedAtlas = component.atlas
+      end
+    end
+
+    if component.insets then
+      createRegionsFromInsets(component, self.atlas)
+    end
+
+    if component.states then
+      for stateName, stateComponent in pairs(component.states) do
+        if stateComponent.atlas then
+          if type(stateComponent.atlas) == "string" then
+            loadAtlasWithNinePatch(stateComponent, stateComponent.atlas, "for state '" .. stateName .. "'")
+          else
+            -- Direct Image object (no ImageData available - scaleCorners won't work)
+            stateComponent._loadedAtlas = stateComponent.atlas
+          end
+        end
+
+        if stateComponent.insets then
+          createRegionsFromInsets(stateComponent, component._loadedAtlas or self.atlas)
+        end
+      end
+    end
+  end
+
+  return self
+end
+
+--- Load a theme from a Lua file
+---@param path string -- Path to theme definition file (e.g., "space" or "mytheme")
+---@return Theme
+function Theme.load(path)
+  local definition
+
+  -- Build the theme module path relative to FlexLove
+  local themePath = FLEXLOVE_BASE_PATH .. ".themes." .. path
+
+  local success, result = pcall(function()
+    return require(themePath)
+  end)
+
+  if success then
+    definition = result
+  else
+    -- Fallback: try as direct path
+    success, result = pcall(function()
+      return require(path)
+    end)
+
+    if success then
+      definition = result
+    else
+      error("Failed to load theme '" .. path .. "'\nTried: " .. themePath .. "\nError: " .. tostring(result))
+    end
+  end
+
+  local theme = Theme.new(definition)
+  -- Register theme by both its display name and load path
+  themes[theme.name] = theme
+  themes[path] = theme
+
+  return theme
+end
+
+--- Set the active theme
+---@param themeOrName Theme|string
+function Theme.setActive(themeOrName)
+  if type(themeOrName) == "string" then
+    -- Try to load if not already loaded
+    if not themes[themeOrName] then
+      Theme.load(themeOrName)
+    end
+    activeTheme = themes[themeOrName]
+  else
+    activeTheme = themeOrName
+  end
+
+  if not activeTheme then
+    error("Failed to set active theme: " .. tostring(themeOrName))
+  end
+end
+
+--- Get the active theme
+---@return Theme?
+function Theme.getActive()
+  return activeTheme
+end
+
+--- Get a component from the active theme
+---@param componentName string -- Name of the component (e.g., "button", "panel")
+---@param state string? -- Optional state (e.g., "hover", "pressed", "disabled")
+---@return ThemeComponent? -- Returns component or nil if not found
+function Theme.getComponent(componentName, state)
+  if not activeTheme then
+    return nil
+  end
+
+  local component = activeTheme.components[componentName]
+  if not component then
+    return nil
+  end
+
+  -- Check for state-specific override
+  if state and component.states and component.states[state] then
+    return component.states[state]
+  end
+
+  return component
+end
+
+--- Get a font from the active theme
+---@param fontName string -- Name of the font family (e.g., "default", "heading")
+---@return string? -- Returns font path or nil if not found
+function Theme.getFont(fontName)
+  if not activeTheme then
+    return nil
+  end
+
+  return activeTheme.fonts and activeTheme.fonts[fontName]
+end
+
+--- Get a color from the active theme
+---@param colorName string -- Name of the color (e.g., "primary", "secondary")
+---@return Color? -- Returns Color instance or nil if not found
+function Theme.getColor(colorName)
+  if not activeTheme then
+    return nil
+  end
+
+  return activeTheme.colors and activeTheme.colors[colorName]
+end
+
+--- Check if a theme is currently active
+---@return boolean -- Returns true if a theme is active
+function Theme.hasActive()
+  return activeTheme ~= nil
+end
+
+--- Get all registered theme names
+---@return table<string> -- Array of theme names
+function Theme.getRegisteredThemes()
+  local themeNames = {}
+  for name, _ in pairs(themes) do
+    table.insert(themeNames, name)
+  end
+  return themeNames
+end
+
+--- Get all available color names from the active theme
+---@return table<string>|nil -- Array of color names, or nil if no theme active
+function Theme.getColorNames()
+  if not activeTheme or not activeTheme.colors then
+    return nil
+  end
+
+  local colorNames = {}
+  for name, _ in pairs(activeTheme.colors) do
+    table.insert(colorNames, name)
+  end
+  return colorNames
+end
+
+--- Get all colors from the active theme
+---@return table<string, Color>|nil -- Table of all colors, or nil if no theme active
+function Theme.getAllColors()
+  if not activeTheme then
+    return nil
+  end
+
+  return activeTheme.colors
+end
+
+--- Get a color with a fallback if not found
+---@param colorName string -- Name of the color to retrieve
+---@param fallback Color|nil -- Fallback color if not found (default: white)
+---@return Color -- The color or fallback
+function Theme.getColorOrDefault(colorName, fallback)
+  local color = Theme.getColor(colorName)
+  if color then
+    return color
+  end
+
+  return fallback or Color.new(1, 1, 1, 1)
+end
+
+return Theme

flexlove/Units.lua

@@ -0,0 +1,180 @@
+-- ====================
+-- Units System
+-- ====================
+
+--- Unit parsing and viewport calculations
+local Units = {}
+
+--- Parse a unit value (string or number) into value and unit type
+---@param value string|number
+---@return number, string -- Returns numeric value and unit type ("px", "%", "vw", "vh")
+function Units.parse(value)
+  if type(value) == "number" then
+    return value, "px"
+  end
+
+  if type(value) ~= "string" then
+    -- Fallback to 0px for invalid types
+    return 0, "px"
+  end
+
+  -- Match number followed by optional unit
+  local numStr, unit = value:match("^([%-]?[%d%.]+)(.*)$")
+  if not numStr then
+    -- Fallback to 0px for invalid format
+    return 0, "px"
+  end
+
+  local num = tonumber(numStr)
+  if not num then
+    -- Fallback to 0px for invalid numeric value
+    return 0, "px"
+  end
+
+  -- Default to pixels if no unit specified
+  if unit == "" then
+    unit = "px"
+  end
+
+  local validUnits = { px = true, ["%"] = true, vw = true, vh = true, ew = true, eh = true }
+  if not validUnits[unit] then
+    return num, "px"
+  end
+
+  return num, unit
+end
+
+--- Convert relative units to pixels based on viewport and parent dimensions
+---@param value number -- Numeric value to convert
+---@param unit string -- Unit type ("px", "%", "vw", "vh", "ew", "eh")
+---@param viewportWidth number -- Current viewport width in pixels
+---@param viewportHeight number -- Current viewport height in pixels
+---@param parentSize number? -- Required for percentage units (parent dimension)
+---@return number -- Resolved pixel value
+---@throws Error if unit type is unknown or percentage used without parent size
+function Units.resolve(value, unit, viewportWidth, viewportHeight, parentSize)
+  if unit == "px" then
+    return value
+  elseif unit == "%" then
+    if not parentSize then
+      error(formatError("Units", "Percentage units require parent dimension"))
+    end
+    return (value / 100) * parentSize
+  elseif unit == "vw" then
+    return (value / 100) * viewportWidth
+  elseif unit == "vh" then
+    return (value / 100) * viewportHeight
+  else
+    error(formatError("Units", string.format("Unknown unit type: '%s'. Valid units: px, %%, vw, vh, ew, eh", unit)))
+  end
+end
+
+---@return number, number -- width, height
+function Units.getViewport()
+  -- Return cached viewport if available (only during resize operations)
+  if Gui and Gui._cachedViewport and Gui._cachedViewport.width > 0 then
+    return Gui._cachedViewport.width, Gui._cachedViewport.height
+  end
+
+  -- Query viewport dimensions normally
+  if love.graphics and love.graphics.getDimensions then
+    return love.graphics.getDimensions()
+  else
+    local w, h = love.window.getMode()
+    return w, h
+  end
+end
+
+--- Apply base scaling to a value
+---@param value number
+---@param axis "x"|"y" -- Which axis to scale on
+---@param scaleFactors {x:number, y:number}
+---@return number
+function Units.applyBaseScale(value, axis, scaleFactors)
+  if axis == "x" then
+    return value * scaleFactors.x
+  else
+    return value * scaleFactors.y
+  end
+end
+
+--- Resolve units for spacing properties (padding, margin)
+---@param spacingProps table?
+---@param parentWidth number
+---@param parentHeight number
+---@return table -- Resolved spacing with top, right, bottom, left in pixels
+function Units.resolveSpacing(spacingProps, parentWidth, parentHeight)
+  if not spacingProps then
+    return { top = 0, right = 0, bottom = 0, left = 0 }
+  end
+
+  local viewportWidth, viewportHeight = Units.getViewport()
+  local result = {}
+
+  -- Handle shorthand properties first
+  local vertical = spacingProps.vertical
+  local horizontal = spacingProps.horizontal
+
+  if vertical then
+    if type(vertical) == "string" then
+      local value, unit = Units.parse(vertical)
+      vertical = Units.resolve(value, unit, viewportWidth, viewportHeight, parentHeight)
+    end
+  end
+
+  if horizontal then
+    if type(horizontal) == "string" then
+      local value, unit = Units.parse(horizontal)
+      horizontal = Units.resolve(value, unit, viewportWidth, viewportHeight, parentWidth)
+    end
+  end
+
+  -- Handle individual sides
+  for _, side in ipairs({ "top", "right", "bottom", "left" }) do
+    local value = spacingProps[side]
+    if value then
+      if type(value) == "string" then
+        local numValue, unit = Units.parse(value)
+        local parentSize = (side == "top" or side == "bottom") and parentHeight or parentWidth
+        result[side] = Units.resolve(numValue, unit, viewportWidth, viewportHeight, parentSize)
+      else
+        result[side] = value
+      end
+    else
+      -- Use fallbacks
+      if side == "top" or side == "bottom" then
+        result[side] = vertical or 0
+      else
+        result[side] = horizontal or 0
+      end
+    end
+  end
+
+  return result
+end
+
+--- Check if a unit string is valid
+---@param unitStr string -- Unit string to validate (e.g., "10px", "50%", "20vw")
+---@return boolean -- Returns true if unit string is valid
+function Units.isValid(unitStr)
+  if type(unitStr) ~= "string" then
+    return false
+  end
+
+  local _, unit = Units.parse(unitStr)
+  local validUnits = { px = true, ["%"] = true, vw = true, vh = true, ew = true, eh = true }
+  return validUnits[unit] == true
+end
+
+--- Parse and resolve a unit value in one call
+---@param value string|number -- Value to parse and resolve
+---@param viewportWidth number -- Current viewport width
+---@param viewportHeight number -- Current viewport height
+---@param parentSize number? -- Parent dimension for percentage units
+---@return number -- Resolved pixel value
+function Units.parseAndResolve(value, viewportWidth, viewportHeight, parentSize)
+  local numValue, unit = Units.parse(value)
+  return Units.resolve(numValue, unit, viewportWidth, viewportHeight, parentSize)
+end
+
+return Units

flexlove/constants.lua

@@ -0,0 +1,16 @@
+-- Text size preset mappings (in vh units for auto-scaling)
+local TEXT_SIZE_PRESETS = {
+  ["2xs"] = 0.75, -- 0.75vh
+  xxs = 0.75, -- 0.75vh
+  xs = 1.25, -- 1.25vh
+  sm = 1.75, -- 1.75vh
+  md = 2.25, -- 2.25vh (default)
+  lg = 2.75, -- 2.75vh
+  xl = 3.5, -- 3.5vh
+  xxl = 4.5, -- 4.5vh
+  ["2xl"] = 4.5, -- 4.5vh
+  ["3xl"] = 5.0, -- 5vh
+  ["4xl"] = 7.0, -- 7vh
+}
+
+return { TEXT_SIZE_PRESETS }

flexlove/utils.lua

@@ -0,0 +1,253 @@
+local enums = {
+  ---@enum TextAlign
+  TextAlign = { START = "start", CENTER = "center", END = "end", JUSTIFY = "justify" },
+  ---@enum Positioning
+  Positioning = { ABSOLUTE = "absolute", RELATIVE = "relative", FLEX = "flex", GRID = "grid" },
+  ---@enum FlexDirection
+  FlexDirection = { HORIZONTAL = "horizontal", VERTICAL = "vertical" },
+  ---@enum JustifyContent
+  JustifyContent = {
+    FLEX_START = "flex-start",
+    CENTER = "center",
+    SPACE_AROUND = "space-around",
+    FLEX_END = "flex-end",
+    SPACE_EVENLY = "space-evenly",
+    SPACE_BETWEEN = "space-between",
+  },
+  ---@enum JustifySelf
+  JustifySelf = {
+    AUTO = "auto",
+    FLEX_START = "flex-start",
+    CENTER = "center",
+    FLEX_END = "flex-end",
+    SPACE_AROUND = "space-around",
+    SPACE_EVENLY = "space-evenly",
+    SPACE_BETWEEN = "space-between",
+  },
+  ---@enum AlignItems
+  AlignItems = {
+    STRETCH = "stretch",
+    FLEX_START = "flex-start",
+    FLEX_END = "flex-end",
+    CENTER = "center",
+    BASELINE = "baseline",
+  },
+  ---@enum AlignSelf
+  AlignSelf = {
+    AUTO = "auto",
+    STRETCH = "stretch",
+    FLEX_START = "flex-start",
+    FLEX_END = "flex-end",
+    CENTER = "center",
+    BASELINE = "baseline",
+  },
+  ---@enum AlignContent
+  AlignContent = {
+    STRETCH = "stretch",
+    FLEX_START = "flex-start",
+    FLEX_END = "flex-end",
+    CENTER = "center",
+    SPACE_BETWEEN = "space-between",
+    SPACE_AROUND = "space-around",
+  },
+  ---@enum FlexWrap
+  FlexWrap = { NOWRAP = "nowrap", WRAP = "wrap", WRAP_REVERSE = "wrap-reverse" },
+  ---@enum TextSize
+  TextSize = {
+    XXS = "xxs",
+    XS = "xs",
+    SM = "sm",
+    MD = "md",
+    LG = "lg",
+    XL = "xl",
+    XXL = "xxl",
+    XL3 = "3xl",
+    XL4 = "4xl",
+  },
+}
+
+---@class ElementProps
+---@field id string?
+---@field parent Element? -- Parent element for hierarchical structure
+---@field x number|string? -- X coordinate of the element (default: 0)
+---@field y number|string? -- Y coordinate of the element (default: 0)
+---@field z number? -- Z-index for layering (default: 0)
+---@field width number|string? -- Width of the element (default: calculated automatically)
+---@field height number|string? -- Height of the element (default: calculated automatically)
+---@field top number|string? -- Offset from top edge (CSS-style positioning)
+---@field right number|string? -- Offset from right edge (CSS-style positioning)
+---@field bottom number|string? -- Offset from bottom edge (CSS-style positioning)
+---@field left number|string? -- Offset from left edge (CSS-style positioning)
+---@field border Border? -- Border configuration for the element
+---@field borderColor Color? -- Color of the border (default: black)
+---@field opacity number?
+---@field backgroundColor Color? -- Background color (default: transparent)
+---@field cornerRadius number|{topLeft:number?, topRight:number?, bottomLeft:number?, bottomRight:number?}? -- Corner radius: number (all corners) or table for individual corners (default: 0)
+---@field gap number|string? -- Space between children elements (default: 10)
+---@field padding {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal: number|string?, vertical:number|string?}? -- Padding around children (default: {top=0, right=0, bottom=0, left=0})
+---@field margin {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal: number|string?, vertical:number|string?}? -- Margin around children (default: {top=0, right=0, bottom=0, left=0})
+---@field text string? -- Text content to display (default: nil)
+---@field titleColor Color? -- Color of the text content (default: black)
+---@field textAlign TextAlign? -- Alignment of the text content (default: START)
+---@field textColor Color? -- Color of the text content (default: black)
+---@field textSize number|string? -- Font size: number (px), string with units ("2vh", "10%"), or preset ("xxs"|"xs"|"sm"|"md"|"lg"|"xl"|"xxl"|"3xl"|"4xl") (default: "md")
+---@field minTextSize number?
+---@field maxTextSize number?
+---@field fontFamily string? -- Font family name from theme or path to font file (default: theme default or system default)
+---@field autoScaleText boolean? -- Whether text should auto-scale with window size (default: true)
+---@field positioning Positioning? -- Layout positioning mode (default: RELATIVE)
+---@field flexDirection FlexDirection? -- Direction of flex layout (default: HORIZONTAL)
+---@field justifyContent JustifyContent? -- Alignment of items along main axis (default: FLEX_START)
+---@field alignItems AlignItems? -- Alignment of items along cross axis (default: STRETCH)
+---@field alignContent AlignContent? -- Alignment of lines in multi-line flex containers (default: STRETCH)
+---@field flexWrap FlexWrap? -- Whether children wrap to multiple lines (default: NOWRAP)
+---@field justifySelf JustifySelf? -- Alignment of the item itself along main axis (default: AUTO)
+---@field alignSelf AlignSelf? -- Alignment of the item itself along cross axis (default: AUTO)
+---@field callback fun(element:Element, event:InputEvent)? -- Callback function for interaction events
+---@field transform table? -- Transform properties for animations and styling
+---@field transition table? -- Transition settings for animations
+---@field gridRows number? -- Number of rows in the grid (default: 1)
+---@field gridColumns number? -- Number of columns in the grid (default: 1)
+---@field columnGap number|string? -- Gap between grid columns
+---@field rowGap number|string? -- Gap between grid rows
+---@field theme string? -- Theme name to use (e.g., "space", "dark"). Defaults to theme from Gui.init()
+---@field themeComponent string? -- Theme component to use (e.g., "panel", "button", "input"). If nil, no theme is applied
+---@field disabled boolean? -- Whether the element is disabled (default: false)
+---@field active boolean? -- Whether the element is active/focused (for inputs, default: false)
+---@field disableHighlight boolean? -- Whether to disable the pressed state highlight overlay (default: false)
+---@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Multiplier for auto-sized content dimensions (default: sourced from theme)
+---@field scaleCorners number? -- Scale multiplier for 9-slice corners/edges. E.g., 2 = 2x size (overrides theme setting)
+---@field scalingAlgorithm "nearest"|"bilinear"? -- Scaling algorithm for 9-slice corners: "nearest" (sharp/pixelated) or "bilinear" (smooth) (overrides theme setting)
+---@field contentBlur {intensity:number, quality:number}? -- Blur the element's content including children (intensity: 0-100, quality: 1-10, default: nil)
+---@field backdropBlur {intensity:number, quality:number}? -- Blur content behind the element (intensity: 0-100, quality: 1-10, default: nil)
+---@field editable boolean? -- Whether the element is editable (default: false)
+---@field multiline boolean? -- Whether the element supports multiple lines (default: false)
+---@field textWrap boolean|"word"|"char"? -- Text wrapping mode (default: false for single-line, "word" for multi-line)
+---@field maxLines number? -- Maximum number of lines (default: nil)
+---@field maxLength number? -- Maximum text length in characters (default: nil)
+---@field placeholder string? -- Placeholder text when empty (default: nil)
+---@field passwordMode boolean? -- Whether to display text as password (default: false)
+---@field inputType "text"|"number"|"email"|"url"? -- Input type for validation (default: "text")
+---@field textOverflow "clip"|"ellipsis"|"scroll"? -- Text overflow behavior (default: "clip")
+---@field scrollable boolean? -- Whether text is scrollable (default: false for single-line, true for multi-line)
+---@field autoGrow boolean? -- Whether element auto-grows with text (default: false)
+---@field selectOnFocus boolean? -- Whether to select all text on focus (default: false)
+---@field cursorColor Color? -- Cursor color (default: nil, uses textColor)
+---@field selectionColor Color? -- Selection background color (default: nil, uses theme or default)
+---@field cursorBlinkRate number? -- Cursor blink rate in seconds (default: 0.5)
+---@field overflow "visible"|"hidden"|"scroll"|"auto"? -- Overflow behavior (default: "visible")
+---@field overflowX "visible"|"hidden"|"scroll"|"auto"? -- X-axis overflow (overrides overflow)
+---@field overflowY "visible"|"hidden"|"scroll"|"auto"? -- Y-axis overflow (overrides overflow)
+---@field scrollbarWidth number? -- Width of scrollbar track in pixels (default: 12)
+---@field scrollbarColor Color? -- Scrollbar thumb color
+---@field scrollbarTrackColor Color? -- Scrollbar track color
+---@field scrollbarRadius number? -- Corner radius for scrollbar (default: 6)
+---@field scrollbarPadding number? -- Padding between scrollbar and edge (default: 2)
+---@field scrollSpeed number? -- Pixels per wheel notch (default: 20)
+
+---@class Border
+---@field top boolean?
+---@field right boolean?
+---@field bottom boolean?
+---@field left boolean?
+
+--- Get current keyboard modifiers state
+---@return {shift:boolean, ctrl:boolean, alt:boolean, super:boolean}
+local function getModifiers()
+  return {
+    shift = love.keyboard.isDown("lshift", "rshift"),
+    ctrl = love.keyboard.isDown("lctrl", "rctrl"),
+    alt = love.keyboard.isDown("lalt", "ralt"),
+    ---@diagnostic disable-next-line
+    super = love.keyboard.isDown("lgui", "rgui"), -- cmd/windows key
+  }
+end
+
+local TEXT_SIZE_PRESETS = {
+  ["2xs"] = 0.75, -- 0.75vh
+  xxs = 0.75, -- 0.75vh
+  xs = 1.25, -- 1.25vh
+  sm = 1.75, -- 1.75vh
+  md = 2.25, -- 2.25vh (default)
+  lg = 2.75, -- 2.75vh
+  xl = 3.5, -- 3.5vh
+  xxl = 4.5, -- 4.5vh
+  ["2xl"] = 4.5, -- 4.5vh
+  ["3xl"] = 5.0, -- 5vh
+  ["4xl"] = 7.0, -- 7vh
+}
+
+-- ====================
+-- Text Size Utilities
+-- ====================
+
+--- Resolve text size preset to viewport units
+---@param sizeValue string|number
+---@return number?, string? -- Returns value and unit ("vh" for presets, original unit otherwise)
+local function resolveTextSizePreset(sizeValue)
+  if type(sizeValue) == "string" then
+    -- Check if it's a preset
+    local preset = TEXT_SIZE_PRESETS[sizeValue]
+    if preset then
+      return preset, "vh"
+    end
+  end
+  -- Not a preset, return nil to indicate normal parsing should occur
+  return nil, nil
+end
+
+local FONT_CACHE = {}
+local FONT_CACHE_MAX_SIZE = 50 -- Limit cache size to prevent unbounded growth
+local FONT_CACHE_ORDER = {} -- Track access order for LRU eviction
+
+--- Create or get a font from cache
+---@param size number
+---@param fontPath string? -- Optional: path to font file
+---@return love.Font
+function FONT_CACHE.get(size, fontPath)
+  -- Create cache key from size and font path
+  local cacheKey = fontPath and (fontPath .. "_" .. tostring(size)) or tostring(size)
+
+  if not FONT_CACHE[cacheKey] then
+    if fontPath then
+      -- Load custom font
+      local resolvedPath = resolveImagePath(fontPath)
+      -- Note: love.graphics.newFont signature is (path, size) for custom fonts
+      local success, font = pcall(love.graphics.newFont, resolvedPath, size)
+      if success then
+        FONT_CACHE[cacheKey] = font
+      else
+        -- Fallback to default font if custom font fails to load
+        print("[FlexLove] Failed to load font: " .. fontPath .. " - using default font")
+        FONT_CACHE[cacheKey] = love.graphics.newFont(size)
+      end
+    else
+      -- Load default font
+      FONT_CACHE[cacheKey] = love.graphics.newFont(size)
+    end
+
+    -- Add to access order for LRU tracking
+    table.insert(FONT_CACHE_ORDER, cacheKey)
+
+    -- Evict oldest entry if cache is full (LRU eviction)
+    if #FONT_CACHE_ORDER > FONT_CACHE_MAX_SIZE then
+      local oldestKey = table.remove(FONT_CACHE_ORDER, 1)
+      FONT_CACHE[oldestKey] = nil
+    end
+  end
+  return FONT_CACHE[cacheKey]
+end
+
+--- Get font for text size (cached)
+---@param textSize number?
+---@param fontPath string? -- Optional: path to font file
+---@return love.Font
+function FONT_CACHE.getFont(textSize, fontPath)
+  if textSize then
+    return FONT_CACHE.get(textSize, fontPath)
+  else
+    return love.graphics.getFont()
+  end
+end
+
+return { enums, FONT_CACHE, resolveTextSizePreset, getModifiers }