-- =====================================================================
-- lib-core.camera — 2D Camera State (P.0)
-- See: meta/docs/superpowers/specs/2026-05-09-p0-lib-camera-design.md
--
-- Scope: target + zoom state + begin/finish wrapper.
-- Forward-compat stubs (DEPRECATED-MVP):
--   - follow(entity)            -- lib-core.actor slice
--   - set_bounds(map_id)         -- when map-bounds matter
--   - lerp_to(target, dt)        -- smooth-follow / animation slice
--   - shake(intensity, dur)      -- effects/juice slice
--   - set_rotation(deg)          -- closed-topology slice
-- =====================================================================

local target_x = 0
local target_y = 0
local zoom_v   = 1.0

local M = {}

function M.set_target(x, y)
    if type(x) ~= "number" or type(y) ~= "number" then
        error("camera.set_target: x and y must be numbers")
    end
    target_x = x
    target_y = y
end

function M.set_zoom(z)
    if type(z) ~= "number" or z <= 0 then
        error(string.format("camera.set_zoom: zoom must be a positive number, got %s",
            tostring(z)))
    end
    zoom_v = z
end

function M.target()
    return { x = target_x, y = target_y }
end

function M.zoom()
    return zoom_v
end

function M.begin()
    engine.render.camera_2d_begin(target_x, target_y, zoom_v)
end

function M.finish()
    engine.render.camera_2d_end()
end

-- DEPRECATED-MVP: forward-compat stubs for later slices
-- function M.follow(entity)            -- lib-core.actor slice
-- function M.set_bounds(map_id)        -- bounds-clamping slice
-- function M.lerp_to(target, dt)       -- smooth-follow slice
-- function M.shake(intensity, dur)     -- effects/juice slice
-- function M.set_rotation(deg)         -- closed-topology slice

return M