RayMA.lua

-- ============================================================
--  RayMA  v8.0
--  Modular MA3 object explorer, search, and action tool
--  Firmware 2.3.x  |  Lua 5.4
-- ============================================================
--  Architecture:
--    core/state.lua     - global state, module registry
--    core/helpers.lua   - shared utilities
--    core/ui.lua        - UI builder and rendering
--    core/keys.lua      - key dispatch and signal wiring
--    modules/browser.lua    - object tree browser (default mode)
--    modules/search.lua     - DataPool search engine
--    modules/qa.lua         - Quick Actions (extensible)
--    modules/properties.lua - property inspector
--    modules/cmd.lua        - command line
--    modules/math.lua       - calculator with history
--    modules/help.lua       - auto-populated help
-- ============================================================

local pluginName    = select(1, ...)
local componentName = select(2, ...)
local signalTable   = select(3, ...)
local my_handle     = select(4, ...)

-- Bootstrap: ensure global exists before any other component
RayMA = RayMA or {}

-- ── Mode switching ──────────────────────────────────────────

function RayMA.saveSession()
    pcall(function()
        SetVar(GlobalVars(), "RayMA_Mode", RayMA.T.MODE or "search")
        SetVar(GlobalVars(), "RayMA_Query", RayMA.T.QUERY or "")
    end)
end

function RayMA.switchMode(newMode)
    local T   = RayMA.T

    -- In elevated mode, check if the target module is elevatedOnly
    -- If so, open it in a new elevated tab instead of switching compact mode
    if T.UI_MODE == "compact" then
        local targetMod = RayMA.getModule(newMode)
        if targetMod and targetMod.elevatedOnly then
            RayMA.elevate(newMode, targetMod.description or newMode)
            return
        end
    end

    local old = RayMA.getActiveModule()
    RayMA.dbg("switchMode: " .. (T.MODE or "nil") .. " → " .. newMode .. " (stack depth " .. #T.MODE_STACK .. ")")
    if old and old.onExit then old.onExit() end

    -- Push current state onto back stack
    T.MODE_STACK[#T.MODE_STACK + 1] = { mode = T.MODE, query = T.QUERY }

    T.MODE    = newMode
    T.QUERY   = ""
    T.CARET   = 0
    T.CURSOR  = 0
    T.OFFSET  = 0
    T.RESULTS = {}

    local mod = RayMA.getActiveModule()
    if mod and mod.onEnter then
        RayMA.dbg("switchMode: calling onEnter for " .. newMode)
        mod.onEnter()
    end
    RayMA.dbg("switchMode: done, results=" .. #T.RESULTS .. " cursor=" .. T.CURSOR)
    RayMA.saveSession()
    RayMA.UI.refresh()
end

-- ── Elevated mode transitions ─────────────────────────────────

function RayMA.elevate(startMode, startLabel)
    local T = RayMA.T
    if T.UI_MODE == "elevated" then
        -- Already elevated — just add a tab
        RayMA.Elevated.addTab(startMode, startLabel)
        return
    end

    -- Tear down compact UI
    if T.OVERLAY then
        pcall(function()
            local existing = T.OVERLAY:Find("RayMA", "BaseInput")
            if existing then existing:Parent():Delete(existing:Index()) end
        end)
    end
    if T.PROP_FRAME then
        pcall(function() T.PROP_FRAME:Parent():Delete(T.PROP_FRAME:Index()) end)
        T.PROP_FRAME = nil
    end

    -- Switch to elevated mode
    T.UI_MODE = "elevated"
    RayMA.Elevated.tabs = {}
    RayMA.Elevated.activeIdx = 0
    RayMA.Elevated.nextId = 1
    RayMA.Elevated.build(RayMA._display)
    coroutine.yield({ui = 1})

    -- Add initial tab
    RayMA.Elevated.addTab(startMode, startLabel or startMode)
    Echo(RayMA.LOG .. " elevated mode: " .. (startLabel or startMode))
end

function RayMA.compact()
    local T = RayMA.T
    if T.UI_MODE ~= "elevated" then return end

    -- Cleanup elevated
    RayMA.Elevated.destroy()
    T.UI_MODE = "compact"

    -- Rebuild compact UI
    RayMA.UI.build(RayMA._display)
    coroutine.yield({ui = 1})

    -- Restore search mode
    RayMA.switchMode("search")
    Echo(RayMA.LOG .. " compact mode restored")
end

function RayMA.goBack()
    local T = RayMA.T
    local stack = T.MODE_STACK
    if #stack == 0 then
        RayMA.dbg("goBack: stack empty, closing")
        T.RUNNING = false
        return
    end

    local old = RayMA.getActiveModule()
    local oldMode = T.MODE
    if old and old.onExit then old.onExit() end

    local prev = stack[#stack]
    stack[#stack] = nil

    RayMA.dbg("goBack: " .. (oldMode or "nil") .. " → " .. (prev.mode or "nil") .. " (stack depth " .. #stack .. ")")

    T.MODE    = prev.mode
    T.CARET   = 0
    T.CURSOR  = 0
    T.OFFSET  = 0
    T.RESULTS = {}

    local mod = RayMA.getActiveModule()
    if mod and mod.onEnter then
        RayMA.dbg("goBack: calling onEnter for " .. prev.mode)
        mod.onEnter()
    end
    RayMA.dbg("goBack: after onEnter, results=" .. #T.RESULTS .. " cursor=" .. T.CURSOR)

    -- Restore query AFTER onEnter (which may reset it)
    T.QUERY = prev.query or ""
    T.CARET = #T.QUERY
    if T.QUERY ~= "" and mod and mod.onSearch then
        mod.onSearch()
    end
    RayMA.saveSession()
    RayMA.dbg("goBack: refresh, results=" .. #T.RESULTS .. " cursor=" .. T.CURSOR .. " mode=" .. T.MODE)
    RayMA.UI.refresh()
end

-- ── Main ────────────────────────────────────────────────────

-- ── Auto-load user modules from user_modules/ directory ────
-- Drop .lua files into RayMA/user_modules/ — no XML editing needed.
-- User modules interact via the RayMA global (registerModule, etc.)

-- ── Auto-load prism files from prisms/ directory ─────────
-- Prism files implement symgrid algorithms.
-- Files starting with _ are loaded first (shared utilities), then alphabetical.

local function loadPrisms()
    local base
    pcall(function() base = GetPath(Enums.PathType.CustomPluginLibrary) end)
    if not base or base == "" then return end

    local sep = package.config:sub(1, 1)
    local dir = base .. sep .. "RayMA" .. sep .. "prisms"

    local lsCmd
    if sep == "\\" then
        lsCmd = 'dir /B "' .. dir .. '\\*.lua" 2>NUL'
    else
        lsCmd = 'ls -1 "' .. dir .. '/"*.lua 2>/dev/null'
    end

    local ok, handle = pcall(function() return io.popen(lsCmd, "r") end)
    if not ok or not handle then return end
    local output = handle:read("*a")
    handle:close()
    if not output or output == "" then return end

    local underscoreFiles = {}
    local regularFiles = {}
    for filename in output:gmatch("[^\r\n]+") do
        local name = filename:match("[/\\]?([^/\\]+)$") or filename
        if name:match("%.lua$") then
            if name:match("^_") then
                underscoreFiles[#underscoreFiles + 1] = name
            else
                regularFiles[#regularFiles + 1] = name
            end
        end
    end
    table.sort(underscoreFiles)
    table.sort(regularFiles)

    local loadCount = 0
    local allFiles = {}
    for _, f in ipairs(underscoreFiles) do allFiles[#allFiles + 1] = f end
    for _, f in ipairs(regularFiles) do allFiles[#allFiles + 1] = f end

    for _, name in ipairs(allFiles) do
        local filepath = dir .. sep .. name
        local loadOk, err = pcall(dofile, filepath)
        if loadOk then
            loadCount = loadCount + 1
        else
            Echo(RayMA.LOG .. " error loading prism " .. name .. ": " .. tostring(err))
        end
    end
    if loadCount > 0 then
        Echo(string.format("%s loaded %d prism(s)", RayMA.LOG, loadCount))
    end
end

-- ── Auto-load photon files from photons/ directory ─────────
-- Photon files implement parsers (color, dimmer, preset, fan, etc.)
-- Files starting with _ are loaded first (shared utilities), then alphabetical.

local function loadPhotons()
    local base
    pcall(function() base = GetPath(Enums.PathType.CustomPluginLibrary) end)
    if not base or base == "" then return end

    local sep = package.config:sub(1, 1)
    local dir = base .. sep .. "RayMA" .. sep .. "photons"

    local lsCmd
    if sep == "\\" then
        lsCmd = 'dir /B "' .. dir .. '\\*.lua" 2>NUL'
    else
        lsCmd = 'ls -1 "' .. dir .. '/"*.lua 2>/dev/null'
    end

    local ok, handle = pcall(function() return io.popen(lsCmd, "r") end)
    if not ok or not handle then return end
    local output = handle:read("*a")
    handle:close()
    if not output or output == "" then return end

    local underscoreFiles = {}
    local regularFiles = {}
    for filename in output:gmatch("[^\r\n]+") do
        local name = filename:match("[/\\]?([^/\\]+)$") or filename
        if name:match("%.lua$") then
            if name:match("^_") then
                underscoreFiles[#underscoreFiles + 1] = name
            else
                regularFiles[#regularFiles + 1] = name
            end
        end
    end
    table.sort(underscoreFiles)
    table.sort(regularFiles)

    local loadCount = 0
    local allFiles = {}
    for _, f in ipairs(underscoreFiles) do allFiles[#allFiles + 1] = f end
    for _, f in ipairs(regularFiles) do allFiles[#allFiles + 1] = f end

    for _, name in ipairs(allFiles) do
        local filepath = dir .. sep .. name
        local loadOk, err = pcall(dofile, filepath)
        if loadOk then
            loadCount = loadCount + 1
        else
            Echo(RayMA.LOG .. " error loading photon " .. name .. ": " .. tostring(err))
        end
    end
    if loadCount > 0 then
        Echo(string.format("%s loaded %d photon(s)", RayMA.LOG, loadCount))
    end
end

local function loadUserModules()
    local base
    pcall(function() base = GetPath(Enums.PathType.CustomPluginLibrary) end)
    if not base or base == "" then return end

    local sep = package.config:sub(1, 1)
    local dir = base .. sep .. "RayMA" .. sep .. "user_modules"

    -- Scan directory for .lua files
    local lsCmd
    if sep == "\\" then
        lsCmd = 'dir /B "' .. dir .. '\\*.lua" 2>NUL'
    else
        lsCmd = 'ls -1 "' .. dir .. '/"*.lua 2>/dev/null'
    end

    local ok, handle = pcall(function() return io.popen(lsCmd, "r") end)
    if not ok or not handle then return end
    local output = handle:read("*a")
    handle:close()
    if not output or output == "" then return end

    local countBefore = #RayMA.modules
    for filename in output:gmatch("[^\r\n]+") do
        -- Extract just the filename from full path (ls gives full path, dir gives name only)
        local name = filename:match("[/\\]?([^/\\]+)$") or filename
        if name:match("%.lua$") and not name:match("^_") then
            local filepath = dir .. sep .. name
            local loadOk, err = pcall(dofile, filepath)
            if loadOk then
                Echo(RayMA.LOG .. " loaded user module: " .. name)
            else
                Echo(RayMA.LOG .. " error loading " .. name .. ": " .. tostring(err))
            end
        end
    end
    local loaded = #RayMA.modules - countBefore
    if loaded > 0 then
        Echo(string.format("%s loaded %d user module(s)", RayMA.LOG, loaded))
    end
end

local function Main(display_handle, argument)
    Echo(RayMA.LOG .. " v" .. RayMA.VERSION .. " starting")
    RayMA.initState()

    -- Load prism files (symgrid algorithms from prisms/ directory)
    loadPrisms()

    -- Load photon files (parsers: color, dimmer, preset, fan, etc.)
    loadPhotons()

    -- Load user modules (from user_modules/ directory, no XML needed)
    loadUserModules()

    local T = RayMA.T

    -- ── Headless exec: "Ray <command>" runs without UI ──────
    if argument and argument:lower():sub(1, 4) == "ray " then
        local rayCmd = argument:sub(5):match("^%s*(.-)%s*$")
        if rayCmd and rayCmd ~= "" then
            Echo(RayMA.LOG .. " exec: " .. rayCmd)
            local rayMod = RayMA.getModule("ray")
            if rayMod and rayMod.executeRay then
                rayMod.executeRay(rayCmd)
                local rayState = RayMA.getModuleState("ray")
                Echo(string.format("%s exec: %s → %s",
                    RayMA.LOG, rayCmd, rayState.lastResult or "done"))
            else
                Echo(RayMA.LOG .. " Ray module not found")
            end
            return
        end
    end

    -- Keyboard shortcuts are suspended per-window via root.OverrideKeybSC="Yes"
    -- (set in UI.build / Elevated.build) — scoped to our overlay, ShCuts icon turns
    -- red, and it auto-restores on close. No global KeyboardShortcutsActive toggle.

    -- Build UI
    local display = RayMA.H.getTargetDisplay(display_handle)
    RayMA._display = display  -- store for elevated mode transitions
    RayMA.cacheColors()
    RayMA.UI.build(display)
    coroutine.yield({ui = 1})

    -- Build search index in background
    T.STATUS.Text = "Scanning show..."
    coroutine.yield({ui = 1})

    local search = RayMA.getModule("search")
    if search then
        search.searchState.INDEX = search.buildIndex()
        search.searchState.INDEX_SOURCE = "live"
        Echo(string.format("%s index: %d objects", RayMA.LOG, #search.searchState.INDEX))
    end

    -- Check for debug flag in argument
    if argument and argument:lower():find("debug") then
        RayMA.DEBUG = true
        Echo(RayMA.LOG .. " DEBUG mode enabled")
        -- Strip "debug" from argument to allow combining: "debug root"
        argument = argument:gsub("[Dd]ebug", ""):match("^%s*(.-)%s*$")
        if argument == "" then argument = nil end
    end

    -- Elevated shortcut: "#ModuleName" opens directly in elevated mode
    local elevatedStarted = false
    if argument and argument:sub(1, 1) == "#" then
        local elevArg = argument:sub(2):match("^%s*(.-)%s*$")
        if elevArg and elevArg ~= "" then
            local modName = elevArg:lower()
            local targetMod = RayMA.getModule(modName)
            if not targetMod then
                for _, cmd in ipairs(RayMA.commands) do
                    if cmd.command:lower() == modName and cmd._module then
                        targetMod = RayMA.getModule(cmd._module)
                        modName = cmd._module
                        break
                    end
                end
            end
            local label = targetMod and (targetMod.description or modName) or elevArg
            RayMA.elevate(modName, label)
            elevatedStarted = true
        end
    end

    -- Determine startup mode: always start with empty search (home screen)
    -- unless a specific argument is given
    if elevatedStarted then
        -- skip compact mode setup
    elseif argument and argument ~= "" then
        if argument:lower() == "root" then
            RayMA.switchMode("browser")
            local browser = RayMA.getModule("browser")
            if browser then pcall(function() browser.browseObj(Root()) end) end
        elseif argument:lower() == "search" then
            RayMA.switchMode("search")
        else
            -- Route-based argument: "ModuleName" or "ModuleName/action/params..."
            -- First segment is module name, rest is passed as route segments
            local segments = {}
            for seg in argument:gmatch("[^/]+") do
                segments[#segments + 1] = seg:match("^%s*(.-)%s*$")
            end
            local modName = segments[1] and segments[1]:lower() or ""
            local targetMod = RayMA.getModule(modName)
            -- Also check registered commands (e.g. "bpm" → module "bpm")
            if not targetMod then
                for _, cmd in ipairs(RayMA.commands) do
                    if cmd.command:lower() == modName and cmd._module then
                        targetMod = RayMA.getModule(cmd._module)
                        modName = cmd._module
                        break
                    end
                end
            end
            if targetMod then
                -- Build route from remaining segments
                local route = {}
                for i = 2, #segments do route[#route + 1] = segments[i] end
                RayMA.switchMode(modName)
                -- Pass route to module if it supports it
                if #route > 0 and targetMod.onRoute then
                    targetMod.onRoute(route)
                end
            else
                -- Fallback: use as search query
                RayMA.switchMode("search")
                T.QUERY = argument
                T.CARET = #argument
                if search and search.onSearch then search.onSearch() end
            end
        end
    else
        -- Default: fresh home screen with empty search + module list
        RayMA.switchMode("search")
    end

    RayMA.UI.refresh()

    -- The capture field grabs the keyboard natively via Focus="InitialFocus";
    -- OverrideKeybSC keeps MA's shortcuts suspended. No focus grabbing needed.

    Echo(string.format("%s v%s ready — %d modules, %d commands, %d QA actions",
        RayMA.LOG, RayMA.VERSION,
        #RayMA.modules, #RayMA.commands, #RayMA.qaActions))

    -- Main loop
    T.RUNNING = true
    while T.RUNNING do
        -- Deferred property panel build
        if T.SHOW_PROPS_FOR then
            local obj = T.SHOW_PROPS_FOR
            T.SHOW_PROPS_FOR = nil
            local props = RayMA.getModule("properties")
            if props then props.buildPropertyPanel(obj) end
        end

        -- Module tick (for async operations like terminal socket polling)
        local activeMod = RayMA.getActiveModule()
        if activeMod and activeMod.onTick then
            pcall(activeMod.onTick)
        end

        -- Check if our window is still alive on the overlay
        local alive = pcall(function()
            local _ = T.ROOT.Name
            if T.OVERLAY then
                local uiName = (T.UI_MODE == "elevated") and "RayMAE" or "RayMA"
                local found = T.OVERLAY:Find(uiName, "BaseInput")
                if not found then error("gone") end
            end
        end)
        if not alive then T.RUNNING = false; break end
        coroutine.yield(0.2)
    end

    -- Save session before cleanup
    RayMA.saveSession()

    -- Module cleanup (e.g. terminal disconnect)
    for _, m in ipairs(RayMA.modules) do
        if m.onPluginClose then pcall(m.onPluginClose) end
    end

    -- Keyboard shortcuts restore themselves when the OverrideKeybSC window closes
    -- below — nothing to undo here.
    if T.PROP_FRAME then
        pcall(function() T.PROP_FRAME:Parent():Delete(T.PROP_FRAME:Index()) end)
    end
    -- Cleanup: remove UI (compact or elevated)
    if T.OVERLAY then
        pcall(function()
            local existing = T.OVERLAY:Find("RayMA", "BaseInput")
            if existing then existing:Parent():Delete(existing:Index()) end
        end)
        pcall(function()
            local existing = T.OVERLAY:Find("RayMAE", "BaseInput")
            if existing then existing:Parent():Delete(existing:Index()) end
        end)
    end

    -- Execute pending action
    local pending = T.PENDING_ACTION
    Echo(RayMA.LOG .. " closed")
    if pending then
        pcall(function()
            CmdIndirectWait(pending.verb .. " " .. pending.entry.cmd)
        end)
    end
end

return Main