flint.lua

--[[ Flint Graphics Engine
Flint is a graphics engine for CC:Tweaked (ComputerCraft), written in Lua. The core idea: instead of CC's 16 hardwired colors you can draw with arbitrary 24-bit hex colors (0xff4444, 0x44aaff, etc.) — Flint handles mapping them to the 16 hardware palette slots automatically.
When more than 16 colors appear in a single frame, an agglomerative clustering algorithm kicks in and merges the most similar colors until 16 remain.
For rendering, Flint works on a virtual subpixel canvas that is twice as wide and three times as tall as the terminal. Every two columns and three rows of subpixels share one terminal cell, which is then rendered as a teletext mosaic character — giving significantly higher resolution than regular CC characters. A precomputed LUT covering all 6⁶ possible subpixel color patterns reduces mosaic rendering to three table lookups per cell per frame.
On top of that there is an optional CraftOS-PC pixel mode (setGraphicsMode): each Flint subpixel becomes a real 3×3 pixel block, bypassing the two-colors-per-cell limit entirely. Text stays visible because the original CC bitmap font is embedded directly in flint.lua and rasterized as pixels at runtime.
The layer system supports multiple stacked drawing surfaces with z-index ordering, per-layer dirty rect tracking, and a diff-based present() that only sends changed rows to the terminal via blit().
]]
local flint = {}

--- @diagnostic disable: undefined-global

--- A color value accepted by Flint. Either a single hex-digit CC palette slot
--- ("0".."f") or a 24-bit RGB integer (e.g. 0xff4444). Hex integers are
--- automatically quantized to the 16-slot hardware palette via clustering.
---@alias FlintColor string|integer

local defaultPalette = {
    ["0"] = 0xf0f0f0,
    ["1"] = 0xf2b233,
    ["2"] = 0xe57fd8,
    ["3"] = 0x99b2f2,
    ["4"] = 0xdede6c,
    ["5"] = 0x7ecc19,
    ["6"] = 0xe599b2,
    ["7"] = 0x4c4c4c,
    ["8"] = 0x999999,
    ["9"] = 0x4c99b2,
    ["a"] = 0xb266e5,
    ["b"] = 0x3366cc,
    ["c"] = 0x7f664c,
    ["d"] = 0x57a63e,
    ["e"] = 0xcc3333,
    ["f"] = 0x111111,
}

local function resolveColor(colorMapping, color, default)
    if not color then return default end
    local mapped = colorMapping[color]
    if mapped then return mapped end
    if type(color) == "string" and #color == 1 and color:match("[0-9a-f]") then
        return color
    end
    return default
end

-- ============================================================================
-- 0. MODULE-LEVEL CONSTANTS
-- ============================================================================

local slotHex   = { "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "a", "b", "c", "d", "e", "f" }
local slotColor = {}
for i = 0, 15 do slotColor[i] = 2 ^ i end

local hexToIndex = {}
for i = 0, 15 do hexToIndex[slotHex[i + 1]] = i end

-- ============================================================================
-- 0b. CC BITMAP FONT (6x9 px per char, extracted from the original CC font
-- via craftos2). Used only by the CraftOS-PC graphics mode to rasterize
-- text as pixels. 18 hex chars per glyph: 9 rows, bit 5 (0x20) = leftmost.
-- ============================================================================
local fontHex = "0000000000000000001c2236222a221c00001c3e2a3e22361c000000143e3e3e1c080000"
    .. "00081c3e1c08000000081c083e3e081c000000081c3e3e081c000000000c1e1e0c000000"
    .. "3f3f332121333f3f00000000000000000000000000000000000000000e061a2424180000"
    .. "1c2222221c081c0800000000000000000000001e121e1030300000001f111f1133330000"
    .. "0020383e382000000000020e3e0e02000000081c3e08083e1c0800121212121200120000"
    .. "1e2a2a1a0a0a0a00001e302c221a063c000000000000001e1e0000081c3e083e1c083e00"
    .. "081c3e080808080000080808083e1c08000000080c3e0c080000000008183e1808000000"
    .. "0000000020203e00000000123f12000000000008081c1c3e000000003e1c1c0808000000"
    .. "0000000000000000000808080808000800000a0a1400000000000014143e143e14140000"
    .. "081e201c023c0800002224040810122200000814081a2c241a0000040408000000000000"
    .. "0608101010080600001804020202041800000000120c12000000000008083e0808000000"
    .. "0000000000080808000000003e0000000000000000000008080000020404081010200000"
    .. "1c22262a32221c00000818080808083e00001c22020c10223e00001c22020c02221c0000"
    .. "060a12223e020200003e203c0202221c00000c10203c22221c00003e2202040808080000"
    .. "1c22221c22221c00001c22221e0204180000000808000008080000000808000008080800"
    .. "02040810080402000000003e00003e0000001008040204081000001c2202040800080000"
    .. "1e212d2d2f201e00001c223e2222222200003c223c2222223c00001c22202020221c0000"
    .. "3c22222222223c00003e20382020203e00003e20382020202000001e20262222221c0000"
    .. "22223e2222222200001c08080808081c00000202020202221c0000222438242222220000"
    .. "2020202020203e000022362a22222222000022322a2622222200001c22222222221c0000"
    .. "3c223c2020202000001c22222222241a00003c223c2222222200001e201c0202221c0000"
    .. "3e08080808080800002222222222221c0000222222221414080000222222222a36220000"
    .. "2214081422222200002214080808080800003e02040810203e00001c10101010101c0000"
    .. "2010100804040200001c04040404041c0000081422000000000000000000000000003e00"
    .. "08080400000000000000001c021e221e000020202c3222223c000000001c2220221c0000"
    .. "02021a2622221e000000001c223e201e000006081e08080808000000001e22221e023c00"
    .. "20202c322222220000080008080808080000020002020222221c00101012141814120000"
    .. "0808080808080400000000342a2a2222000000003c22222222000000001c2222221c0000"
    .. "00002c32223c20200000001a26221e02020000002c32202020000000001e201c023c0000"
    .. "08081c0808080400000000222222221e0000000022222214080000000022222a2a1e0000"
    .. "00002214081422000000002222221e023c0000003e0408103e0000060808100808060000"
    .. "080808080808080000180404020404180000192600000000000000122409122409122409"
    .. "0000000000000000003838380000000000000707070000000000003f3f3f000000000000"
    .. "0000003838380000003838383838380000000707073838380000003f3f3f383838000000"
    .. "0000000707070000003838380707070000000707070707070000003f3f3f070707000000"
    .. "0000003f3f3f0000003838383f3f3f0000000707073f3f3f0000003f3f3f3f3f3f000000"
    .. "0000000000003838383838380000003838380707070000003838383f3f3f000000383838"
    .. "0000003838383838383838383838383838380707073838383838383f3f3f383838383838"
    .. "0000000707073838383838380707073838380707070707073838383f3f3f070707383838"
    .. "0000003f3f3f3838383838383f3f3f3838380707073f3f3f3838383f3f3f3f3f3f383838"
    .. "00000000000000000008000808080808000000081c2220221c08000c12103c10103e0000"
    .. "00221c2222221c220022143e083e080800000808080008080800001e302c221a063c0000"
    .. "140000000000000000001e252929251e000018041c241c0000000000000a1428140a0000"
    .. "0000003e02020000000000003e0000000000001e2d2d2b211e00003e0000000000000000"
    .. "1824241800000000000008083e0808003e00201030203000000000301030103000000000"
    .. "1020000000000000000000222222223d20201e2a2a1a0a0a0a00000000000c0c00000000"
    .. "000000000000040800103010103800000000001c2222221c000000000028140a14280000"
    .. "2224040816162200002224040812142600003214340816162200000800081020221c0000"
    .. "30001c223e2222000006001c223e222200001c221c223e2222000014281c223e22220000"
    .. "14001c223e2222000008001c223e222200001e28283c28282e00001c222020221c040800"
    .. "30003e203c203e000006003e203c203e00001c223e203c203e000014003e203c203e0000"
    .. "18001c0808081c00000c001c0808081c000008141c0808081c000014001c0808081c0000"
    .. "3c22223222223c00000a1422322a26220000301c222222221c0000061c222222221c0000"
    .. "1c221c2222221c000014281c2222221c0000141c222222221c0000002214081422000000"
    .. "1c22262a32221c00003000222222221c00000600222222221c00000814002222221c0000"
    .. "1400222222221c00000600221408080800001c080c0a0c081c00003c222c2222222c2000"
    .. "30001c021e221e000006001c021e221e00001c221c021e221e000014281c021e221e0000"
    .. "14001c021e221e000008001c021e221e0000000016293e28170000001c2220221c040800"
    .. "30001c223e201e000006001c223e201e00001c221c223e201e000014001c223e201e0000"
    .. "1800080808080800000c0008080808080000081408080808080000140008080808080000"
    .. "08041e2222221c000014283c22222222000030001c2222221c000006001c2222221c0000"
    .. "1c221c2222221c000014281c2222221c000014001c2222221c00000008003e0008000000"
    .. "00001c262a321c00003000222222221e00000600222222221e00000814002222221e0000"
    .. "1400222222221e000006002222221e023c0018080c0a0c081c000014002222221e023c00"

local fontRows = {}
for c = 0, 255 do
    local rows = {}
    local base = c * 18
    for r = 1, 9 do
        rows[r] = tonumber(fontHex:sub(base + r * 2 - 1, base + r * 2), 16)
    end
    fontRows[c] = rows
end

-- ============================================================================
-- 1. Bitwise Mosaic Lookup Initialization (64 states)
-- ============================================================================
local mosaicLut = {}

local function initMosaicLut()
    for id = 0, 63 do
        local charNum = 128
        if bit32.btest(id, 1) then charNum = charNum + 1 end
        if bit32.btest(id, 2) then charNum = charNum + 2 end
        if bit32.btest(id, 4) then charNum = charNum + 4 end
        if bit32.btest(id, 8) then charNum = charNum + 8 end
        if bit32.btest(id, 16) then charNum = charNum + 16 end
        mosaicLut[id] = string.char(charNum)
    end
end
initMosaicLut()

-- ============================================================================
-- 1b. TEXEL PATTERN LUT
-- All 6^6 subpixel color patterns are precompiled at load time. What matters
-- per texel is only the *equality structure* of the 6 colors (which positions
-- share a color), so every pattern is reduced to first-occurrence indices and
-- encoded into a compact id (encoding borrowed from PixelBox). At runtime the
-- whole "find the two dominant colors" pass collapses into 3 table lookups.
-- The LUT is generated with Flint's original tally algorithm, so the output
-- is bit-identical to the previous per-texel computation.
-- ============================================================================
local texelCharLut  = {}
local texelFgPosLut = {}
local texelBgPosLut = {}

local function initTexelLut()
    local lookup = {}
    local vals = {}
    for enc = 0, 46655 do -- 6^6 - 1
        local d1 = enc % 6
        local d2 = math.floor(enc / 6) % 6
        local d3 = math.floor(enc / 36) % 6
        local d4 = math.floor(enc / 216) % 6
        local d5 = math.floor(enc / 1296) % 6
        local d6 = math.floor(enc / 7776) % 6

        lookup[d6] = 5
        lookup[d5] = 4
        lookup[d4] = 3
        lookup[d3] = 2
        lookup[d2] = 1
        lookup[d1] = 0

        local s2, s3, s4, s5, s6 = lookup[d2], lookup[d3], lookup[d4], lookup[d5], lookup[d6]
        local id = s2 + s3 * 3 + s4 * 4 + s5 * 20 + s6 * 100

        if not texelCharLut[id] then
            vals[1], vals[2], vals[3] = 0, s2, s3
            vals[4], vals[5], vals[6] = s4, s5, s6

            local colorA, cntA, colorB, cntB
            for t = 1, 6 do
                local c = vals[t]
                if c == colorA then
                    cntA = cntA + 1
                elseif c == colorB then
                    cntB = cntB + 1
                    if cntB > cntA then
                        colorA, cntA, colorB, cntB = colorB, cntB, colorA, cntA
                    end
                elseif not colorA then
                    colorA, cntA = c, 1
                elseif not colorB then
                    colorB, cntB = c, 1
                end
            end
            colorB = colorB or colorA
            cntB = cntB or 0

            local fbBit = (cntA <= cntB) and 0 or 1
            local p1 = (0 == colorA) and 0 or ((0 == colorB) and 1 or fbBit)
            local p2 = (s2 == colorA) and 0 or ((s2 == colorB) and 1 or fbBit)
            local p3 = (s3 == colorA) and 0 or ((s3 == colorB) and 1 or fbBit)
            local p4 = (s4 == colorA) and 0 or ((s4 == colorB) and 1 or fbBit)
            local p5 = (s5 == colorA) and 0 or ((s5 == colorB) and 1 or fbBit)
            local p6 = (s6 == colorA) and 0 or ((s6 == colorB) and 1 or fbBit)

            local maskId = 0
            if p1 ~= p6 then maskId = maskId + 1 end
            if p2 ~= p6 then maskId = maskId + 2 end
            if p3 ~= p6 then maskId = maskId + 4 end
            if p4 ~= p6 then maskId = maskId + 8 end
            if p5 ~= p6 then maskId = maskId + 16 end

            local fgVal = (p6 == 0) and colorB or colorA
            local bgVal = (p6 == 0) and colorA or colorB

            texelCharLut[id]  = mosaicLut[maskId]
            texelFgPosLut[id] = fgVal + 1
            texelBgPosLut[id] = bgVal + 1
        end
    end
end
initTexelLut()

-- ============================================================================
-- 2. THE FLAT COMPOSITE BUFFER (The Canvas)
-- ============================================================================

---@class Buffer
---@field width number Width of the buffer in terminal cells.
---@field height number Height of the buffer in terminal cells.
---@field totalSize number Cached total number of terminal cells (width * height) for efficient iteration.
---@field chars string[] Array of characters for each terminal cell.
---@field fgs FlintColor[] Array of foreground colors for each terminal cell.
---@field bgs FlintColor[] Array of background colors for each terminal cell.
local Buffer = {}
Buffer.__index = Buffer

---Creates a new Buffer instance with the specified width and height. The buffer is initialized with empty character and color data.
---@param width number Width of the buffer in terminal cells.
---@param height number Height of the buffer in terminal cells.
---@return Buffer The newly created Buffer instance.
function Buffer.new(width, height)
    local self = setmetatable({}, Buffer)
    self.width = width
    self.height = height
    self.totalSize = width * height

    self.chars = {}
    self.fgs = {}
    self.bgs = {}

    self:clear(" ", "0", "f")
    return self
end

---Clears the entire buffer by filling it with the specified character and colors. This is a bulk operation that efficiently resets all cells in the buffer to a uniform state.
---@param char string? The character to fill the buffer with.
---@param fg FlintColor? The foreground color to fill the buffer with.
---@param bg FlintColor? The background color to fill the buffer with.
function Buffer:clear(char, fg, bg)
    for i = 1, self.totalSize do
        self.chars[i] = char
        self.fgs[i] = fg
        self.bgs[i] = bg
    end
end

-- ============================================================================
-- 3. THE LAYER CLASS (Isolated Layer Object)
-- ============================================================================

---@class Layer
---@field engine Engine Reference to the parent engine, for accessing shared state and registering colors.
---@field zIndex number Determines the compositing order of layers; higher zIndex layers are drawn on top of lower ones.
---@field termWidth number Cached reference to engine.termWidth for efficient index calculations.
---@field termHeight number Cached reference to engine.termHeight for efficient index calculations.
---@field vWidth number Cached reference to engine.vWidth for efficient index calculations.
---@field vHeight number Cached reference to engine.vHeight for efficient index calculations.
---@field totalSize number Cached total number of terminal cells (termWidth * termHeight) for efficient iteration.
---@field chars string[] Array of characters for each terminal cell in this layer.
---@field fgs FlintColor[] Array of foreground colors for each terminal cell in this layer.
---@field bgs FlintColor[] Array of background colors for each terminal cell in this layer.
---@field subpixelFgs FlintColor[] Array of foreground colors for each subpixel in the virtual canvas.
---@field subpixelBgs FlintColor[] Array of background colors for each subpixel in the virtual canvas.
---@field subpixelBits number[] Array of bit flags indicating which subpixels are set in the virtual canvas.
local Layer = {}
Layer.__index = Layer

---Creates a new Layer instance with the specified zIndex. The layer is initialized with empty character and color data, and is marked as fully dirty for initial rendering.
---@param engine Engine Reference to the parent engine for accessing shared state and registering colors.
---@param zIndex number Optional zIndex for the layer; defaults to 0 if not provided.
function Layer.new(engine, zIndex)
    local self = setmetatable({}, Layer)
    self.engine = engine
    self.zIndex = zIndex or 0

    self.termWidth = engine.termWidth
    self.termHeight = engine.termHeight
    self.vWidth = engine.vWidth
    self.vHeight = engine.vHeight
    self.totalSize = self.termWidth * self.termHeight

    self.chars = {}
    self.fgs = {}
    self.bgs = {}

    self.subpixelFgs = {}
    self.subpixelBgs = {}
    self.subpixelBits = {}

    self.usedColors = {}
    self.subpixelsDirty = false

    self.dirtyX1 = math.huge
    self.dirtyY1 = math.huge
    self.dirtyX2 = 0
    self.dirtyY2 = 0

    self.spExtX1 = math.huge
    self.spExtY1 = math.huge
    self.spExtX2 = 0
    self.spExtY2 = 0

    self:clear()
    return self
end

---Registers a color with the engine if it hasn't already been registered by this layer. This ensures that the engine's palette is aware of all colors used by the layer, without redundant registrations.
---@param color FlintColor? The color to register.
function Layer:registerColor(color)
    if not color then return end
    if not self.usedColors[color] then
        self.usedColors[color] = true
        self.engine:registerColor(color)
    end
end

---Marks a rectangular region of the layer as dirty, indicating that it needs to be re-rendered. The dirty region is expanded to include the specified rectangle, and will be used by the engine to optimize rendering by only redrawing the affected area.
---@param x1 number Left edge of the dirty region.
---@param y1 number Top edge of the dirty region.
---@param x2 number Right edge of the dirty region.
---@param y2 number Bottom edge of the dirty region.
function Layer:markDirty(x1, y1, x2, y2)
    if x1 < self.dirtyX1 then self.dirtyX1 = x1 end
    if y1 < self.dirtyY1 then self.dirtyY1 = y1 end
    if x2 > self.dirtyX2 then self.dirtyX2 = x2 end
    if y2 > self.dirtyY2 then self.dirtyY2 = y2 end
end

---Marks a rectangular region of the layer as dirty specifically for subpixel updates. This is used to track which areas of the layer have had their virtual canvas (subpixel) data modified, so that the engine can efficiently update only those areas when compositing subpixels into terminal cells.
---@param x1 number Left edge of the dirty region in terminal cells.
---@param y1 number Top edge of the dirty region in terminal cells.
---@param x2 number Right edge of the dirty region in terminal cells.
---@param y2 number Bottom edge of the dirty region in terminal cells.
function Layer:markSubpixelDirty(x1, y1, x2, y2)
    self:markDirty(x1, y1, x2, y2)
    if x1 < self.spExtX1 then self.spExtX1 = x1 end
    if y1 < self.spExtY1 then self.spExtY1 = y1 end
    if x2 > self.spExtX2 then self.spExtX2 = x2 end
    if y2 > self.spExtY2 then self.spExtY2 = y2 end
end

---Clears the entire layer: resets all char, fg, bg, and subpixel data.
---Also resets usedColors, dirty rects, and subpixel extent.
---@param char string? Fill character. nil leaves cells without a char set.
---@param fg FlintColor? Foreground color applied to every cell.
---@param bg FlintColor? Background color applied to every cell.
function Layer:clear(char, fg, bg)
    self.usedColors = {}
    self:registerColor(fg)
    self:registerColor(bg)
    self:markDirty(1, 1, self.termWidth, self.termHeight)

    for i = 1, self.totalSize do
        self.chars[i] = char
        self.fgs[i] = fg
        self.bgs[i] = bg
    end

    local totalSubpixels = self.vWidth * self.vHeight
    for i = 1, totalSubpixels do
        self.subpixelFgs[i] = fg
        self.subpixelBgs[i] = bg
        self.subpixelBits[i] = 0
    end
    self.hasSubpixels = false
    self.subpixelsDirty = false
    self.spExtX1, self.spExtY1 = math.huge, math.huge
    self.spExtX2, self.spExtY2 = 0, 0
end

---Clears only the subpixel (virtual canvas) data, leaving char/fg/bg intact.
---More efficient than clear() for layers that exclusively use subpixel drawing.
---@param fg FlintColor? Fill foreground for cleared subpixels.
---@param bg FlintColor? Fill background for cleared subpixels.
function Layer:clearVirtual(fg, bg)
    self:registerColor(fg)
    self:registerColor(bg)
    self:markDirty(1, 1, self.termWidth, self.termHeight)

    local totalSubpixels = self.vWidth * self.vHeight
    for i = 1, totalSubpixels do
        self.subpixelFgs[i] = fg
        self.subpixelBgs[i] = bg
        self.subpixelBits[i] = 0
    end
    self.hasSubpixels = false
    self.subpixelsDirty = false
    self.spExtX1, self.spExtY1 = math.huge, math.huge
    self.spExtX2, self.spExtY2 = 0, 0
end

-- ============================================================================
-- 4. LAYER CHARACTER PRIMITIVES (Writing directly and live to the Layer Arrays)
-- ============================================================================

---Writes a single character at the given terminal-cell position.
---Silently ignored if the position is outside the engine clip region.
---@param x number Column in terminal cells (1-based).
---@param y number Row in terminal cells (1-based).
---@param char string Single character to write.
---@param fg FlintColor? Foreground color. nil leaves the existing fg.
---@param bg FlintColor? Background color. nil leaves the existing bg.
function Layer:drawChar(x, y, char, fg, bg)
    local engine = self.engine
    if x < engine.clipTx1 or x > engine.clipTx2 or y < engine.clipTy1 or y > engine.clipTy2 then return end
    self:registerColor(fg)
    self:registerColor(bg)
    self:markDirty(x, y, x, y)

    local idx = (y - 1) * self.termWidth + x
    if char then self.chars[idx] = char end
    if fg then self.fgs[idx] = fg end
    if bg then self.bgs[idx] = bg end
end

---Writes a string of characters starting at (x, y) in terminal-cell coordinates.
---Characters clipped by the engine clip region are silently skipped.
---@param x number Starting column in terminal cells (1-based).
---@param y number Row in terminal cells (1-based).
---@param text string The string to write.
---@param fg FlintColor Foreground color for all characters.
---@param bg FlintColor? Background color for all characters.
function Layer:drawText(x, y, text, fg, bg)
    local engine = self.engine
    if y < engine.clipTy1 or y > engine.clipTy2 then return end
    self:registerColor(fg)
    self:registerColor(bg)

    local lo = math.max(engine.clipTx1, x)
    local hi = math.min(engine.clipTx2, x + #text - 1)
    if lo <= hi then self:markDirty(lo, y, hi, y) end

    local tw = self.termWidth
    local rowStart = (y - 1) * tw
    local cChars = self.chars
    local cFgs = self.fgs
    local cBgs = self.bgs

    for i = 1, #text do
        local cx = x + i - 1
        if cx >= engine.clipTx1 and cx <= engine.clipTx2 then
            local idx = rowStart + cx
            local char = text:sub(i, i)
            if char then cChars[idx] = char end
            if fg then cFgs[idx] = fg end
            if bg then cBgs[idx] = bg end
        end
    end
end

---Sets a single subpixel on the virtual canvas.
---The virtual canvas is vWidth × vHeight (termWidth×2 × termHeight×3 subpixels).
---In text mode two columns and three rows of subpixels share one terminal cell
---(teletext mosaic); in graphics mode each subpixel maps to a 3×3 real-pixel block.
---@param vx number Subpixel column (1-based, max sys.vWidth).
---@param vy number Subpixel row (1-based, max sys.vHeight).
---@param color FlintColor? Foreground color of the subpixel.
---@param bgColor FlintColor? Optional background color override for this subpixel slot.
function Layer:drawSubpixel(vx, vy, color, bgColor)
    local engine = self.engine
    if vx < engine.clipVx1 or vx > engine.clipVx2 or vy < engine.clipVy1 or vy > engine.clipVy2 then return end
    self:registerColor(color)

    local cellX = math.floor((vx + 1) / 2)
    local cellY = math.floor((vy + 2) / 3)
    self:markSubpixelDirty(cellX, cellY, cellX, cellY)

    local idx = (vy - 1) * self.vWidth + vx
    self.subpixelFgs[idx] = color
    if bgColor then
        self:registerColor(bgColor)
        self.subpixelBgs[idx] = bgColor
    end
    self.subpixelBits[idx] = 1
    self.hasSubpixels = true
    self.subpixelsDirty = true
end

---Fills a rectangle with a character and/or color in terminal-cell coordinates.
---Any of char, fg, bg may be nil to leave that field of existing cells unchanged.
---@param x number Left edge in terminal cells (1-based).
---@param y number Top edge in terminal cells (1-based).
---@param w number Width in terminal cells.
---@param h number Height in terminal cells.
---@param char string Fill character. nil skips updating chars.
---@param fg FlintColor? Foreground color. nil skips updating fg.
---@param bg FlintColor? Background color. nil skips updating bg.
function Layer:drawRect(x, y, w, h, char, fg, bg)
    local engine = self.engine
    local x1 = math.max(engine.clipTx1, x)
    local y1 = math.max(engine.clipTy1, y)
    local x2 = math.min(engine.clipTx2, x + w - 1)
    local y2 = math.min(engine.clipTy2, y + h - 1)
    self:registerColor(fg)
    self:registerColor(bg)
    if x1 <= x2 and y1 <= y2 then self:markDirty(x1, y1, x2, y2) end

    local tw = self.termWidth
    local cChars = self.chars
    local cFgs = self.fgs
    local cBgs = self.bgs

    for ty = y1, y2 do
        local rowStart = (ty - 1) * tw
        for tx = x1, x2 do
            local idx = rowStart + tx
            if char then cChars[idx] = char end
            if fg then cFgs[idx] = fg end
            if bg then cBgs[idx] = bg end
        end
    end
end

---Fills a rectangle on the virtual canvas in subpixel coordinates.
---Clipped to the engine's current subpixel clip region.
---@param vx number Left edge in subpixels (1-based).
---@param vy number Top edge in subpixels (1-based).
---@param vw number Width in subpixels.
---@param vh number Height in subpixels.
---@param color FlintColor? Foreground color for the filled area.
---@param bgColor FlintColor? Optional background color for the filled area.
function Layer:drawSubpixelRect(vx, vy, vw, vh, color, bgColor)
    local engine = self.engine
    local x1 = math.max(engine.clipVx1, vx)
    local y1 = math.max(engine.clipVy1, vy)
    local x2 = math.min(engine.clipVx2, vx + vw - 1)
    local y2 = math.min(engine.clipVy2, vy + vh - 1)
    self:registerColor(color)
    if bgColor then self:registerColor(bgColor) end
    if x1 <= x2 and y1 <= y2 then
        self:markSubpixelDirty(math.floor((x1 + 1) / 2), math.floor((y1 + 2) / 3),
            math.floor((x2 + 1) / 2), math.floor((y2 + 2) / 3))
    end

    local width = self.vWidth
    local sFgs = self.subpixelFgs
    local sBgs = self.subpixelBgs
    local sBits = self.subpixelBits

    for cy = y1, y2 do
        local rowStart = (cy - 1) * width
        for cx = x1, x2 do
            local idx = rowStart + cx
            sFgs[idx] = color
            if bgColor then sBgs[idx] = bgColor end
            sBits[idx] = 1
        end
    end
    self.hasSubpixels = true
    self.subpixelsDirty = true
end

---Draws a Bresenham line on the virtual canvas between two subpixel coordinates.
---Only the foreground color of each touched subpixel is set; bgColor is not affected.
---@param vx1 number Start column in subpixels (1-based).
---@param vy1 number Start row in subpixels (1-based).
---@param vx2 number End column in subpixels (1-based).
---@param vy2 number End row in subpixels (1-based).
---@param color FlintColor Color of the line.
function Layer:drawSubpixelLine(vx1, vy1, vx2, vy2, color)
    local dx = math.abs(vx2 - vx1)
    local dy = math.abs(vy2 - vy1)
    local sx = (vx1 < vx2) and 1 or -1
    local sy = (vy1 < vy2) and 1 or -1
    local err = dx - dy

    local vWidth = self.vWidth
    local sFgs = self.subpixelFgs
    local sBits = self.subpixelBits
    local engine = self.engine
    local cx1, cx2 = engine.clipVx1, engine.clipVx2
    local cy1, cy2 = engine.clipVy1, engine.clipVy2
    self:registerColor(color)

    local bx1 = math.max(cx1, math.min(vx1, vx2))
    local bx2 = math.min(cx2, math.max(vx1, vx2))
    local by1 = math.max(cy1, math.min(vy1, vy2))
    local by2 = math.min(cy2, math.max(vy1, vy2))
    if bx1 <= bx2 and by1 <= by2 then
        self:markSubpixelDirty(math.floor((bx1 + 1) / 2), math.floor((by1 + 2) / 3),
            math.floor((bx2 + 1) / 2), math.floor((by2 + 2) / 3))
    end

    while true do
        if vx1 >= cx1 and vx1 <= cx2 and vy1 >= cy1 and vy1 <= cy2 then
            local idx = (vy1 - 1) * vWidth + vx1
            sFgs[idx] = color
            sBits[idx] = 1
        end
        if vx1 == vx2 and vy1 == vy2 then break end
        local e2 = 2 * err
        if e2 > -dy then
            err = err - dy; vx1 = vx1 + sx
        end
        if e2 < dx then
            err = err + dx; vy1 = vy1 + sy
        end
    end
    self.hasSubpixels = true
    self.subpixelsDirty = true
end

local texelColors = {}
local lutColorMap = {}

---Converts the subpixel buffer into terminal-cell chars/fg/bg for the given cell region.
---Normally called automatically inside Engine:compileSubpixels(); only call directly
---if you need to recompile a specific rect without going through the full engine pass.
---@param rx1 number? Left cell boundary (default 1).
---@param ry1 number? Top cell boundary (default 1).
---@param rx2 number? Right cell boundary (default termWidth).
---@param ry2 number? Bottom cell boundary (default termHeight).
function Layer:compileSubpixels(rx1, ry1, rx2, ry2)
    local tw = self.termWidth
    local vw = self.vWidth
    rx1 = rx1 or 1
    ry1 = ry1 or 1
    rx2 = rx2 or tw
    ry2 = ry2 or self.termHeight
    local sFgs = self.subpixelFgs
    local sBgs = self.subpixelBgs
    local sBits = self.subpixelBits
    local lChars = self.chars
    local lFgs = self.fgs
    local lBgs = self.bgs

    for ty = ry1, ry2 do
        local compStartIdx = (ty - 1) * tw
        local vy1 = (ty - 1) * 3 + 1
        local vy2 = vy1 + 1
        local vy3 = vy1 + 2

        local vIdxStart1 = (vy1 - 1) * vw
        local vIdxStart2 = (vy2 - 1) * vw
        local vIdxStart3 = (vy3 - 1) * vw

        for tx = rx1, rx2 do
            local vx1 = (tx - 1) * 2 + 1
            local vx2 = vx1 + 1

            local i1 = vIdxStart1 + vx1
            local i2 = vIdxStart1 + vx2
            local i3 = vIdxStart2 + vx1
            local i4 = vIdxStart2 + vx2
            local i5 = vIdxStart3 + vx1
            local i6 = vIdxStart3 + vx2

            local c1 = (sBits[i1] == 1) and (sFgs[i1] or "f") or (sBgs[i1] or sFgs[i1] or "f")
            local c2 = (sBits[i2] == 1) and (sFgs[i2] or "f") or (sBgs[i2] or sFgs[i2] or "f")
            local c3 = (sBits[i3] == 1) and (sFgs[i3] or "f") or (sBgs[i3] or sFgs[i3] or "f")
            local c4 = (sBits[i4] == 1) and (sFgs[i4] or "f") or (sBgs[i4] or sFgs[i4] or "f")
            local c5 = (sBits[i5] == 1) and (sFgs[i5] or "f") or (sBgs[i5] or sFgs[i5] or "f")
            local c6 = (sBits[i6] == 1) and (sFgs[i6] or "f") or (sBgs[i6] or sFgs[i6] or "f")

            if c1 == c2 and c1 == c3 and c1 == c4 and c1 == c5 and c1 == c6 then
                if sBits[i1] == 1 or sBits[i2] == 1 or sBits[i3] == 1
                    or sBits[i4] == 1 or sBits[i5] == 1 or sBits[i6] == 1 then
                    local cIdx   = compStartIdx + tx
                    lChars[cIdx] = "\128"
                    lFgs[cIdx]   = c1
                    lBgs[cIdx]   = c1
                end
            else
                lutColorMap[c6] = 5
                lutColorMap[c5] = 4
                lutColorMap[c4] = 3
                lutColorMap[c3] = 2
                lutColorMap[c2] = 1
                lutColorMap[c1] = 0

                local id = lutColorMap[c2] + lutColorMap[c3] * 3 + lutColorMap[c4] * 4
                    + lutColorMap[c5] * 20 + lutColorMap[c6] * 100

                texelColors[1], texelColors[2], texelColors[3] = c1, c2, c3
                texelColors[4], texelColors[5], texelColors[6] = c4, c5, c6

                local cIdx   = compStartIdx + tx
                lChars[cIdx] = texelCharLut[id]
                lFgs[cIdx]   = texelColors[texelFgPosLut[id]]
                lBgs[cIdx]   = texelColors[texelBgPosLut[id]]
            end
        end
    end
end

-- ============================================================================
-- 5. CORE ENGINE STRUCTURE & LAYER LIFECYCLE
-- ============================================================================
---@class Engine
---@field term table The target terminal object for output, must have .blit() and .getSize() methods.
---@field termWidth number Cached terminal width in characters.
---@field termHeight number Cached terminal height in characters.
---@field vWidth number Cached virtual canvas width in subpixels (termWidth * 2).
---@field vHeight number Cached virtual canvas height in subpixels (termHeight * 3).
---@field composite Buffer The flat composite buffer representing the final output state for the current frame.
---@field cacheChars table LUT for caching character patterns during composition.
---@field cacheFgs table LUT for caching foreground color patterns during composition.
---@field cacheBgs table LUT for caching background color patterns during composition.
---@field layers Layer[] Array of registered layers, sorted by zIndex.
---@field frameColors table Set of colors used in the current frame, for palette management.
---@field colorMapping table LUT for mapping logical colors to hardware palette slots.
---@field paletteDirty boolean Flag indicating whether the hardware palette needs to be updated.
---@field hwPalette table Cached hardware palette colors for quick lookup.
---@field presentY1 number Top row of the next present() update region.
---@field presentY2 number Bottom row of the next present() update region.
---@field gfxMode boolean Flag indicating whether the engine is in graphics mode (true) or text mode (false).
---@field gfxRowCache table Cache for storing previously rendered rows in graphics mode to optimize redraws.
---@field nativeRGBs table LUT mapping FlintColor hex codes to native RGB values
local Engine = {}
Engine.__index = Engine

---Creates a new Flint engine attached to the given terminal.
---The engine reads the terminal size once at creation; resize is not tracked.
---@param targetTerm table A CC terminal object with `.blit()` and `.getSize()`.
---@return Engine
function flint.new(targetTerm)
    assert(targetTerm and targetTerm.blit and targetTerm.getSize,
        "Flint benoetigt ein Objekt mit .blit() und .getSize() Methoden!")

    local self = setmetatable({}, Engine)
    self.term = targetTerm

    local tw, th = self.term.getSize()
    self.termWidth = tw
    self.termHeight = th

    self.composite = Buffer.new(tw, th)

    self.vWidth = tw * 2
    self.vHeight = th * 3

    self.cacheChars = {}
    self.cacheFgs = {}
    self.cacheBgs = {}
    self.layers = {}

    self.frameColors = {}
    self.colorMapping = {}
    self.paletteDirty = true
    self.hwPalette = {}

    self.presentY1 = 1
    self.presentY2 = th

    self.gfxMode = false
    self.gfxRowCache = {}

    self.nativeRGBs = {}
    for i = 0, 15 do
        local hex = slotHex[i + 1]
        local r, g, b
        if self.term.getPaletteColor then
            r, g, b = self.term.getPaletteColor(slotColor[i])
        end
        if r then
            local ir = math.floor(r * 255 + 0.5)
            local ig = math.floor(g * 255 + 0.5)
            local ib = math.floor(b * 255 + 0.5)
            self.nativeRGBs[hex] = ir * 65536 + ig * 256 + ib
        else
            self.nativeRGBs[hex] = defaultPalette[hex]
        end
    end

    self:resetClipRegion()
    return self
end

---Registers a color with the engine's palette if it hasn't already been registered this frame. The engine maintains a set of colors used in the current frame to optimize palette updates; this method ensures that any color used by layers is included in that set.
---@param color FlintColor The color to register.
function Engine:registerColor(color)
    if not color then return end
    if not self.frameColors[color] then
        self.frameColors[color] = true
        self.paletteDirty = true
    end
end

-- ============================================================================
-- 6. VIEWPORT / CLIPPING SYSTEM
-- ============================================================================

---Restricts all subsequent draw calls to the given cell rectangle.
---Both character-space and subpixel-space clip regions are updated atomically.
---@param x number Left edge in terminal cells (1-based).
---@param y number Top edge in terminal cells (1-based).
---@param w number Width in terminal cells.
---@param h number Height in terminal cells.
function Engine:setClipRegion(x, y, w, h)
    self.clipTx1 = math.max(1, x)
    self.clipTy1 = math.max(1, y)
    self.clipTx2 = math.min(self.termWidth, x + w - 1)
    self.clipTy2 = math.min(self.termHeight, y + h - 1)

    self.clipVx1 = (self.clipTx1 - 1) * 2 + 1
    self.clipVy1 = (self.clipTy1 - 1) * 3 + 1
    self.clipVx2 = self.clipTx2 * 2
    self.clipVy2 = self.clipTy2 * 3
end

---Removes the clip region, restoring the full terminal extent for draw calls.
function Engine:resetClipRegion()
    self.clipTx1 = 1
    self.clipTy1 = 1
    self.clipTx2 = self.termWidth
    self.clipTy2 = self.termHeight

    self.clipVx1 = 1
    self.clipVy1 = 1
    self.clipVx2 = self.vWidth
    self.clipVy2 = self.vHeight
end

-- ============================================================================
-- 7. LAYER MANAGEMENT
-- ============================================================================

---Creates a new Layer, registers it with the engine, and inserts it into the
---sorted draw order. Layers with a lower zIndex are drawn first (further back).
---@param zIndex number Rendering order.
---@return Layer
function Engine:addLayer(zIndex)
    local layer = Layer.new(self, zIndex)
    table.insert(self.layers, layer)
    table.sort(self.layers, function(a, b)
        return a.zIndex < b.zIndex
    end)
    return layer
end

---Clears all layers (chars, subpixels, colors, and dirty state).
---Equivalent to calling layer:clear() on every registered layer.
function Engine:clear()
    for i = 1, #self.layers do
        self.layers[i]:clear()
    end
end

-- ============================================================================
-- 8. THE COMPOSITE PASS
-- ============================================================================

---Resolves the hardware palette, composites all layers into the output buffer,
---and records the dirty row range for the next present() call.
---Must be called once per frame after all draw calls and before present().
function Engine:compileSubpixels()
    local active = { ["0"] = true, ["f"] = true }
    for i = 1, #self.layers do
        for color in pairs(self.layers[i].usedColors) do
            active[color] = true
        end
    end

    local changed = false
    for color in pairs(active) do
        if not self.frameColors[color] then
            changed = true
            break
        end
    end
    if not changed then
        for color in pairs(self.frameColors) do
            if not active[color] then
                changed = true
                break
            end
        end
    end
    self.frameColors = active
    if changed then self.paletteDirty = true end

    local rebuilt = false
    if self.paletteDirty then
        local function toRGB(rgb)
            local r = bit32.band(bit32.rshift(rgb, 16), 0xFF)
            local g = bit32.band(bit32.rshift(rgb, 8), 0xFF)
            local b = bit32.band(rgb, 0xFF)
            return r, g, b
        end

        local term = self.term
        local hwPalette = self.hwPalette
        local function setHardwarePalette(slotIndex, rgb)
            if hwPalette[slotIndex] == rgb then return end
            hwPalette[slotIndex] = rgb
            local r = bit32.band(bit32.rshift(rgb, 16), 0xFF) / 255
            local g = bit32.band(bit32.rshift(rgb, 8), 0xFF) / 255
            local b = bit32.band(rgb, 0xFF) / 255
            term.setPaletteColor(slotColor[slotIndex], r, g, b)
        end

        local uniqueColors = {}
        local uniqueCount = 0
        for color in pairs(self.frameColors) do
            uniqueCount = uniqueCount + 1
            table.insert(uniqueColors, color)
        end

        table.sort(uniqueColors, function(a, b)
            local typeA = type(a)
            local typeB = type(b)
            if typeA ~= typeB then
                return typeA < typeB
            end
            return a < b
        end)

        self.colorMapping = {}

        if uniqueCount <= 16 then
            local nativeSlotsUsed = {}
            local customColors = {}
            for i = 1, #uniqueColors do
                local val = uniqueColors[i]
                if type(val) == "string" and #val == 1 and val:match("[0-9a-f]") then
                    nativeSlotsUsed[val] = true
                    self.colorMapping[val] = val
                else
                    table.insert(customColors, val)
                end
            end

            local freeSlots = {}
            for i = 0, 15 do
                local hexChar = slotHex[i + 1]
                if nativeSlotsUsed[hexChar] then
                    setHardwarePalette(i, self.nativeRGBs[hexChar])
                else
                    table.insert(freeSlots, i)
                end
            end

            for k = 1, #customColors do
                local val = customColors[k]
                local slotIndex = freeSlots[k]
                self.colorMapping[val] = slotHex[slotIndex + 1]
                setHardwarePalette(slotIndex, val)
            end
        else
            local valToRGB = {}
            local uniqueRGBs = {}
            for i = 1, #uniqueColors do
                local val = uniqueColors[i]
                local rgb
                if type(val) == "string" and #val == 1 and val:match("[0-9a-f]") then
                    rgb = self.nativeRGBs[val]
                else
                    rgb = val
                end
                valToRGB[val] = rgb
                table.insert(uniqueRGBs, val)
            end

            local clusters = {}
            for i = 1, #uniqueRGBs do
                local val = uniqueRGBs[i]
                clusters[i] = {
                    color   = valToRGB[val],
                    members = { val },
                    alive   = true,
                }
            end
            local n = #clusters

            local dist = {}
            for i = 1, n do
                dist[i] = {}
                for j = i + 1, n do
                    local r1, g1, b1 = toRGB(clusters[i].color)
                    local r2, g2, b2 = toRGB(clusters[j].color)
                    local dr, dg, db = r1 - r2, g1 - g2, b1 - b2
                    dist[i][j] = dr * dr + dg * dg + db * db
                end
            end

            local alive = n

            while alive > 16 do
                local minDist = math.huge
                local minI, minJ = 1, 2
                for i = 1, n do
                    if clusters[i].alive then
                        for j = i + 1, n do
                            if clusters[j].alive then
                                local d = dist[i][j]
                                if d < minDist then
                                    minDist = d
                                    minI = i
                                    minJ = j
                                end
                            end
                        end
                    end
                end

                local ci = clusters[minI]
                local cj = clusters[minJ]

                local r1, g1, b1 = toRGB(ci.color)
                local r2, g2, b2 = toRGB(cj.color)
                ci.color = math.floor((r1 + r2) / 2) * 65536
                    + math.floor((g1 + g2) / 2) * 256
                    + math.floor((b1 + b2) / 2)

                for k = 1, #cj.members do
                    ci.members[#ci.members + 1] = cj.members[k]
                end
                cj.alive = false
                alive    = alive - 1

                for k = 1, n do
                    if clusters[k].alive and k ~= minI then
                        local lo, hi     = k < minI and k or minI,
                            k < minI and minI or k
                        local r3, g3, b3 = toRGB(clusters[k].color)
                        local r4, g4, b4 = toRGB(ci.color)
                        local dr, dg, db = r3 - r4, g3 - g4, b3 - b4
                        dist[lo][hi]     = dr * dr + dg * dg + db * db
                    end
                end
            end

            local surviving = {}
            for i = 1, n do
                if clusters[i].alive then
                    surviving[#surviving + 1] = clusters[i]
                end
            end

            for k = 1, #surviving do
                local slotIndex = k - 1
                local hexChar = slotHex[k]
                local clusterColor = surviving[k].color
                setHardwarePalette(slotIndex, clusterColor)

                for m = 1, #surviving[k].members do
                    local val = surviving[k].members[m]
                    self.colorMapping[val] = hexChar
                end
            end
        end

        self.paletteDirty = false
        rebuilt = true
    end

    local tw = self.termWidth
    local th = self.termHeight

    local ux1, uy1, ux2, uy2
    if rebuilt then
        ux1, uy1, ux2, uy2 = 1, 1, tw, th
    else
        ux1, uy1, ux2, uy2 = math.huge, math.huge, 0, 0
        for i = 1, #self.layers do
            local l = self.layers[i]
            if l.dirtyX1 < ux1 then ux1 = l.dirtyX1 end
            if l.dirtyY1 < uy1 then uy1 = l.dirtyY1 end
            if l.dirtyX2 > ux2 then ux2 = l.dirtyX2 end
            if l.dirtyY2 > uy2 then uy2 = l.dirtyY2 end
            if l.subpixelsDirty then
                if l.spExtX1 < ux1 then ux1 = l.spExtX1 end
                if l.spExtY1 < uy1 then uy1 = l.spExtY1 end
                if l.spExtX2 > ux2 then ux2 = l.spExtX2 end
                if l.spExtY2 > uy2 then uy2 = l.spExtY2 end
            end
        end
        if ux1 < 1 then ux1 = 1 end
        if uy1 < 1 then uy1 = 1 end
        if ux2 > tw then ux2 = tw end
        if uy2 > th then uy2 = th end
        if ux1 > ux2 or uy1 > uy2 then return end
    end

    local mapping = self.colorMapping
    local cChars = self.composite.chars
    local cFgs = self.composite.fgs
    local cBgs = self.composite.bgs

    local defFg = resolveColor(mapping, "0", "0")
    local defBg = resolveColor(mapping, "f", "f")
    for ty = uy1, uy2 do
        local rowStart = (ty - 1) * tw
        for tx = ux1, ux2 do
            local j = rowStart + tx
            cChars[j] = " "
            cFgs[j] = defFg
            cBgs[j] = defBg
        end
    end

    for i = 1, #self.layers do
        local layer = self.layers[i]

        if layer.hasSubpixels and layer.subpixelsDirty then
            local lx1 = math.max(1, layer.spExtX1)
            local ly1 = math.max(1, layer.spExtY1)
            local lx2 = math.min(tw, layer.spExtX2)
            local ly2 = math.min(th, layer.spExtY2)
            if lx1 <= lx2 and ly1 <= ly2 then
                layer:compileSubpixels(lx1, ly1, lx2, ly2)
            end
        end
        layer.subpixelsDirty = false

        local lChars = layer.chars
        local lFgs = layer.fgs
        local lBgs = layer.bgs

        for ty = uy1, uy2 do
            local rowStart = (ty - 1) * tw
            for tx = ux1, ux2 do
                local j = rowStart + tx
                local bg = lBgs[j]
                if bg ~= nil then
                    cChars[j] = lChars[j] or " "
                    cFgs[j] = resolveColor(mapping, lFgs[j], "0")
                    cBgs[j] = resolveColor(mapping, bg, "f")
                end
            end
        end

        layer.dirtyX1, layer.dirtyY1 = math.huge, math.huge
        layer.dirtyX2, layer.dirtyY2 = 0, 0
    end

    if uy1 < self.presentY1 then self.presentY1 = uy1 end
    if uy2 > self.presentY2 then self.presentY2 = uy2 end
end

-- ============================================================================
-- 9. FLUSH TO TERMINAL
-- ============================================================================

---Flushes the composite buffer to the terminal using diff-based blit (only
---changed rows are sent). In graphics mode delegates to the pixel renderer.
---Call after compileSubpixels() every frame.
function Engine:present()
    if self.gfxMode then
        return self:presentGfx()
    end

    local tw = self.termWidth
    local th = self.termHeight

    local y1 = self.presentY1
    local y2 = self.presentY2
    if y1 < 1 then y1 = 1 end
    if y2 > th then y2 = th end
    if y1 > y2 then return end
    self.presentY1, self.presentY2 = math.huge, 0

    local cChars = self.composite.chars
    local cFgs = self.composite.fgs
    local cBgs = self.composite.bgs
    local blit = self.term.blit
    local setCursor = self.term.setCursorPos
    local cacheChars = self.cacheChars
    local cacheFgs = self.cacheFgs
    local cacheBgs = self.cacheBgs

    local lineChars = {}
    local lineFgs = {}
    local lineBgs = {}

    for y = y1, y2 do
        local startIdx = (y - 1) * tw

        for x = 1, tw do
            local idx = startIdx + x
            lineChars[x] = cChars[idx]
            lineFgs[x] = cFgs[idx]
            lineBgs[x] = cBgs[idx]
        end

        local finalChars  = table.concat(lineChars)
        local finalFgs    = table.concat(lineFgs)
        local finalBgs    = table.concat(lineBgs)

        if cacheChars[y] ~= finalChars or cacheFgs[y] ~= finalFgs or cacheBgs[y] ~= finalBgs then
            setCursor(1, y)
            blit(finalChars, finalFgs, finalBgs)
            cacheChars[y] = finalChars
            cacheFgs[y]   = finalFgs
            cacheBgs[y]   = finalBgs
        end
    end
end

---Forces a full repaint on the next present() call (text and graphics mode).
---Clears the blit cache so every row is re-sent even if the content is unchanged.
---Useful after palette resets or terminal redraws by external code.
function Engine:invalidate()
    self.presentY1 = 1
    self.presentY2 = self.termHeight
    for y = 1, self.termHeight do
        self.cacheChars[y] = nil
        self.cacheFgs[y] = nil
        self.cacheBgs[y] = nil
    end
    self.gfxRowCache = {}
end

-- ============================================================================
-- 10. CRAFTOS-PC PIXEL GRAPHICS MODE (opt-in)
-- Renders frames as REAL pixels: the CraftOS-PC graphics screen is
-- termWidth*6 x termHeight*9 pixels. Subpixel content gets full color
-- fidelity (every Flint subpixel = a 3x3 pixel block, no two-colors-per-cell
-- limit), and char content (drawChar/drawText) is rasterized with the
-- original CC bitmap font, so text stays visible. Cells are composited in
-- z-order like in text mode: per cell the topmost layer wins that either has
-- subpixel content there or an opaque background (bg ~= nil).
-- Only works in CraftOS-PC, not in Minecraft.
-- ============================================================================

local glyphRowCache = {}
local subRowCache = {}

local function subPiece(l, r)
    local key = l * 16 + r
    local s = subRowCache[key]
    if not s then
        s = string.char(l, l, l, r, r, r)
        subRowCache[key] = s
    end
    return s
end

local function glyphPiece(mask, fg, bg)
    local key = mask * 256 + fg * 16 + bg
    local s = glyphRowCache[key]
    if not s then
        local band = bit32.band
        s = string.char(
            band(mask, 32) ~= 0 and fg or bg,
            band(mask, 16) ~= 0 and fg or bg,
            band(mask, 8) ~= 0 and fg or bg,
            band(mask, 4) ~= 0 and fg or bg,
            band(mask, 2) ~= 0 and fg or bg,
            band(mask, 1) ~= 0 and fg or bg)
        glyphRowCache[key] = s
    end
    return s
end

local gfxType = {}
local gfxGlyph = {}
local gfxFg = {}
local gfxBg = {}
local gfxP1 = {}
local gfxP2 = {}
local gfxP3 = {}

---Switches CraftOS-PC pixel graphics mode on or off.
---In graphics mode every Flint subpixel maps to a 3x3 real-pixel block, giving
---full 24-bit color fidelity without the two-color-per-cell limit of text mode.
---Text drawn with drawChar/drawText is rasterized using the embedded CC bitmap font.
---Has no effect (returns false) in standard CC / Minecraft.
---@param enabled boolean true to enter graphics mode, false to return to text mode.
---@return boolean ok true on success, false if the terminal does not support graphics mode.
---@return string? reason Error description when ok is false.
function Engine:setGraphicsMode(enabled)
    local t = self.term
    if enabled then
        if not (t.setGraphicsMode and t.drawPixels) then
            return false, "Terminal hat keinen Grafikmodus (nur CraftOS-PC)"
        end
        t.setGraphicsMode(1)
        self.gfxMode = true
        self.gfxRowCache = {}
        self.presentY1 = 1
        self.presentY2 = self.termHeight
    else
        if t.setGraphicsMode then t.setGraphicsMode(0) end
        self.gfxMode = false
        self:invalidate()
    end
    return true
end

function Engine:presentGfx()
    local th = self.termHeight
    local tw = self.termWidth

    local y1 = self.presentY1
    local y2 = self.presentY2
    if y1 < 1 then y1 = 1 end
    if y2 > th then y2 = th end
    if y1 > y2 then return end
    self.presentY1, self.presentY2 = math.huge, 0

    local vw = self.vWidth
    local layers = self.layers
    local layerCount = #layers
    local mapping = self.colorMapping
    local drawPixels = self.term.drawPixels
    local cache = self.gfxRowCache

    local defIdx = hexToIndex[resolveColor(mapping, "f", "f")] or 15
    local defPiece = subPiece(defIdx, defIdx)
    local emptyGlyph = fontRows[32]

    local rowBuf = {}
    local outRows = {}

    for y = y1, y2 do
        local cellRow = (y - 1) * tw
        local vy0 = (y - 1) * 3
        for x = 1, tw do
            local cellIdx = cellRow + x
            local kind = 0
            for li = layerCount, 1, -1 do
                local layer = layers[li]
                if layer.hasSubpixels then
                    local sBits = layer.subpixelBits
                    local i1 = vy0 * vw + (x - 1) * 2 + 1
                    local i2 = i1 + 1
                    local i3 = i1 + vw
                    local i4 = i3 + 1
                    local i5 = i3 + vw
                    local i6 = i5 + 1
                    if sBits[i1] == 1 or sBits[i2] == 1 or sBits[i3] == 1
                        or sBits[i4] == 1 or sBits[i5] == 1 or sBits[i6] == 1 then
                        local sFgs = layer.subpixelFgs
                        local sBgs = layer.subpixelBgs
                        local c1 = (sBits[i1] == 1) and (sFgs[i1] or "f") or (sBgs[i1] or sFgs[i1] or "f")
                        local c2 = (sBits[i2] == 1) and (sFgs[i2] or "f") or (sBgs[i2] or sFgs[i2] or "f")
                        local c3 = (sBits[i3] == 1) and (sFgs[i3] or "f") or (sBgs[i3] or sFgs[i3] or "f")
                        local c4 = (sBits[i4] == 1) and (sFgs[i4] or "f") or (sBgs[i4] or sFgs[i4] or "f")
                        local c5 = (sBits[i5] == 1) and (sFgs[i5] or "f") or (sBgs[i5] or sFgs[i5] or "f")
                        local c6 = (sBits[i6] == 1) and (sFgs[i6] or "f") or (sBgs[i6] or sFgs[i6] or "f")
                        gfxP1[x] = subPiece(hexToIndex[resolveColor(mapping, c1, "f")] or 15,
                            hexToIndex[resolveColor(mapping, c2, "f")] or 15)
                        gfxP2[x] = subPiece(hexToIndex[resolveColor(mapping, c3, "f")] or 15,
                            hexToIndex[resolveColor(mapping, c4, "f")] or 15)
                        gfxP3[x] = subPiece(hexToIndex[resolveColor(mapping, c5, "f")] or 15,
                            hexToIndex[resolveColor(mapping, c6, "f")] or 15)
                        kind = 2
                        break
                    end
                end
                local bg = layer.bgs[cellIdx]
                if bg ~= nil then
                    local ch = layer.chars[cellIdx]
                    local byte = ch and ch:byte() or 32
                    gfxGlyph[x] = (byte == 0) and emptyGlyph or fontRows[byte] or emptyGlyph
                    gfxFg[x] = hexToIndex[resolveColor(mapping, layer.fgs[cellIdx], "0")] or 0
                    gfxBg[x] = hexToIndex[resolveColor(mapping, bg, "f")] or 15
                    kind = 1
                    break
                end
            end
            gfxType[x] = kind
        end

        local pyBase = (y - 1) * 9
        local rowsChanged = false
        for pr = 1, 9 do
            local third = (pr <= 3) and gfxP1 or (pr <= 6) and gfxP2 or gfxP3
            for x = 1, tw do
                local kind = gfxType[x]
                if kind == 2 then
                    rowBuf[x] = third[x]
                elseif kind == 1 then
                    rowBuf[x] = glyphPiece(gfxGlyph[x][pr], gfxFg[x], gfxBg[x])
                else
                    rowBuf[x] = defPiece
                end
            end
            local rowStr = table.concat(rowBuf, "", 1, tw)
            outRows[pr] = rowStr
            local py = pyBase + pr - 1
            if cache[py] ~= rowStr then
                cache[py] = rowStr
                rowsChanged = true
            end
        end
        if rowsChanged then
            drawPixels(0, pyBase, { outRows[1], outRows[2], outRows[3],
                outRows[4], outRows[5], outRows[6],
                outRows[7], outRows[8], outRows[9] })
        end
    end
end

function Engine:resetPaletteColor(color)
    local function resetSlot(idx)
        local slot = slotColor[idx]
        local r, g, b
        if self.term.nativePaletteColor then
            r, g, b = self.term.nativePaletteColor(slot)
        end
        if not r then
            local hex = slotHex[idx + 1]
            local rgb = defaultPalette[hex]
            r = bit32.band(bit32.rshift(rgb, 16), 0xFF) / 255
            g = bit32.band(bit32.rshift(rgb, 8), 0xFF) / 255
            b = bit32.band(rgb, 0xFF) / 255
        end
        self.term.setPaletteColor(slot, r, g, b)
    end

    if color then
        local slotIndex
        if type(color) == "number" then
            for i = 0, 15 do
                if slotColor[i] == color then
                    slotIndex = i
                    break
                end
            end
        elseif type(color) == "string" and #color == 1 then
            for i = 0, 15 do
                if slotHex[i + 1] == color then
                    slotIndex = i
                    break
                end
            end
        end
        if slotIndex then
            resetSlot(slotIndex)
        end
    else
        for i = 0, 15 do
            resetSlot(i)
        end
    end
    self.hwPalette = {}
    self.paletteDirty = true
end

return flint