-- ============================================================================
-- HDG_signatures.lua - API Reference
-- HousingDecorGuide Public Function Signatures
-- Auto-generated reference - do not execute, documentation only
-- ============================================================================

-- ============================================================================
-- HDG_Core.lua - Global Namespace
-- ============================================================================
-- HousingDecorGuide = {} -- Global addon table (defined in HDG_Core.lua)

-- ============================================================================
-- HDG_Config.lua - Constants, Settings, Logging
-- ============================================================================
-- privateDB.CONFIG                                 -- Configuration constants table (sizes, colors, textures)
-- privateDB.Log(level, message, ...)               -- Internal logging with LOG_LEVEL filter
-- privateDB.LOG_LEVEL                              -- { DEBUG=1, INFO=2, WARN=3, ERROR=4 }
-- privateDB.ValidateSettings()     -- RETIRED v2.41
-- privateDB.CreateSettingsProxy()  -- RETIRED v2.41
-- privateDB.InitSettingsProxy()    -- RETIRED v2.41

-- ============================================================================
-- HDG_ExpansionData.lua - Zone/Expansion Lookups, BoP Reagents
-- ============================================================================
-- ZONE_DATA (local)                                  -- SSoT: string keys = {mapID, xpac}, int keys = xpac
HDG_ExpansionData.ZONE_MAP_IDS                        -- Built from ZONE_DATA: zoneName -> mapID
HDG_ExpansionData.GetMapIDForZone(zoneName)            -- Lookup mapID for a zone display name
HDG_ExpansionData.GetExpansionForMapID(mapID)           -- Resolve mapID to expansion (walks parent chain)
HDG_ExpansionData.IsBoPReagent(itemID)                 -- Check if itemID is a BoP crafting reagent
HDG_ExpansionData.IsHousingAchievement(achieveID)      -- Check if achieveID is housing (category 15606)
HDG_ExpansionData.GetDecorAchievementProgress()         -- Returns: currentQty, nextThreshold, totalCompleted, totalAchievements
HDG_ExpansionData.GetCouponAchievementProgress()        -- Returns: currentQty, nextThreshold, totalCompleted, totalAchievements
HDG_ExpansionData.GetLumberAchievementSummary()         -- Returns: completedCount, totalCount (12)
HDG_ExpansionData.DECOR_ACHIEVEMENTS                    -- Table of {id, threshold} for 11 decor collection achievements
HDG_ExpansionData.COUPON_ACHIEVEMENTS                   -- Table of {id, threshold} for 7 coupon achievements

-- ============================================================================
-- HDG_Data.lua - Recipe/Collection Data Access
-- ============================================================================
HDG_Data.GetCachedItemName(itemID)                  -- Get item name (cached, async loads if needed)
HDG_Data.GetCachedItemNameLower(itemID)             -- Get pre-lowercased item name (for search filtering)
HDG_Data.GetLocalizedName(itemID, fallbackName)     -- Get localized name, prefer WoW API
HDG_Data.IsItemCollected(itemID)                    -- Check if decor item is collected (by itemID, caches negatives)
HDG_Data.IsDecorCollected(decorID)                  -- Check if decor is collected (by decorID)
HDG_Data.ClearCaches()                              -- Clear item name and collection caches
HDG_Data.GetItemCount(itemID)                       -- Get total item count (bags+bank+warband)
HDG_Data.GetItemCountWithVariants(itemID)           -- Get count including all quality variants (R1+R2+R3)
HDG_Data.GetPersonalItemCount(itemID)               -- Get count excluding Warband Bank
HDG_Data.GetWarbandBankCount(itemID)                -- Get count in Warband Bank only
HDG_Data.SaveCharacterLumberInventory()             -- Save current char's lumber to Store
HDG_Data.GetAccountWideLumberCount(lumberId)        -- Get account-wide lumber total + breakdown
HDG_Data.GetLumberBreakdown(lumberId)               -- Get per-character lumber breakdown
HDG_Data.PlayerKnowsRecipeBySpellID(spellID)        -- Check if player knows recipe (by spellID)
HDG_Data.BuildKnownRecipeCache()                    -- Build cache of known recipe spellIDs
HDG_Data.InvalidateRecipeCache()                    -- Clear known recipe cache
HDG_Data.InvalidateProfessionCache()               -- Clear cached profession skillLine set (invalidated on TRADE_SKILL_LIST_UPDATE)
HDG_Data.PlayerKnowsRecipe(recipeName)              -- Check if player knows recipe (by name, legacy)
HDG_Data.GetRecipeSpellID(recipeName)               -- Get spellID for a recipe name
HDG_Data.PlayerHasProfession(professionName)        -- Check if player has profession
HDG_Data.OpenProfessionAtRecipe(professionName, recipeSpellID) -- Open profession window at recipe
HDG_Data.GetPlayerProfessions()                     -- Get player professions for UI display
HDG_Data.InitializeDatabase()                       -- Transform HDG_DecorDB into addon format
HDG_Data.CalculateLumberNeeds(professions)          -- Calculate lumber needs for all recipes
HDG_Data.CalculateCraftingQueueLumber(queue)        -- Calculate lumber for crafting queue
HDG_Data.GetItemPrice(itemID)                       -- Delegate to HDG_PriceIntegration
HDG_Data.FormatGold(copper, useTextures)            -- Delegate to HDG_PriceIntegration
HDG_Data.HasPriceAddon()                            -- Delegate to HDG_PriceIntegration
HDG_Data.LogCraftFromItemLink(itemLink, quantity)   -- Log craft from item link
HDG_Data.GetCraftingHistory()                       -- Get crafting history
HDG_Data.ClearCraftingHistory()                     -- Clear crafting history
HDG_Data.FormatTimestamp(timestamp)                 -- Format timestamp for display
HDG_Data.CanCraftRecipe(recipe)                     -- Check if player can craft recipe
HDG_Data.GetCraftableRecipes(professionFilter)      -- Get all craftable recipes
HDG_Data.GetCharacterKey()                          -- Get unique character key (Name-Realm)
HDG_Data.CollectCharacterProfessions()              -- Collect/cache current char's professions
HDG_Data.GetAltProfessionData(professionName)       -- Get alt profession data
HDG_Data.GetBestAltRecipeCount(professionName)      -- Get best alt's recipe count
HDG_Data.AnyAltHasProfession(professionName)        -- Check if any alt has profession
HDG_Data.GetCharactersWhoKnowRecipe(spellID, professionName) -- Get chars who know recipe

-- ============================================================================
-- HDG_UI.lua - Main Window Management
-- ============================================================================
HDG_UI.CreateUI()                                   -- Create main addon window
HDG_UI.Toggle()                                     -- Toggle main window visibility
HDG_UI.OpenWithProfession(professionName)           -- Open filtered to specific profession
HDG_UI.RefreshUI()                                  -- Refresh all visible UI elements
HDG_UI.UpdateTabs()                                 -- Update tab states and visibility
HDG_UI.SwitchTab(tabKey)                             -- Switch to a specific tab programmatically
HDG_UI.CountKnownRecipes(profData)                  -- Count known recipes in profession
HDG_UI.CreateTrainersPanel()                        -- Create trainers placeholder frame
HDG_UI.RefreshCharactersPanel()                     -- Refresh characters/alts panel
HDG_UI.UpdateLumberLayout()                         -- Update lumber panel (embedded vs pinned)
HDG_UI.RefreshEmbeddedLumber()                      -- Refresh embedded lumber content
HDG_UI.RefreshLumberTracking()                      -- Refresh all lumber displays
HDG_UI.RefreshProfessionTabs()                      -- Delegate: refresh profession tabs
HDG_UI.AddToCraftingQueue(recipe, skipRefresh)      -- Delegate: add recipe to crafting queue
HDG_UI.RefreshCraftingQueue()                       -- Delegate: refresh crafting queue panel
HDG_UI.RefreshMaterials()                           -- Delegate: refresh materials panel
HDG_UI.AddAllMaterialsToAuctionator()               -- Delegate: add mats to Auctionator search
HDG_UI.UpdateProfessionButtonVisibility()           -- Update profession window button visibility
HDG_UI.RefreshQuote()                               -- Refresh random Orc quote
HDG_UI.RequestHouseInfo()                           -- Request house info (async)
HDG_UI.OnHouseListUpdated(houseInfoList)            -- Handler for PLAYER_HOUSE_LIST_UPDATED
HDG_UI.OnHouseLevelFavorUpdated(houseLevelFavor)    -- Handler for HOUSE_LEVEL_FAVOR_UPDATED
HDG_UI.UpdateHouseLevelDisplay()                    -- Update house level display

-- ============================================================================
-- HDG_UIHelpers.lua - UI Utilities
-- ============================================================================
HDG_UIHelpers.GetScheme()                           -- Get current color scheme from Theme Engine
HDG_UIHelpers.RegisterWidget(widget, widgetType)    -- Register widget with Theme Engine
HDG_UIHelpers.ColorText(text, colorKey)             -- Apply color code to text
HDG_UIHelpers.GetBorderColor(alpha)                 -- Get scheme-aware border color
HDG_UIHelpers.GetActiveColor(alpha)                 -- Get scheme-aware active state color
HDG_UIHelpers.GetInactiveColor(alpha)               -- Get scheme-aware inactive state color
HDG_UIHelpers.GetHoverColor(alpha)                  -- Get scheme-aware hover color
HDG_UIHelpers.GetTextColor(isDim, isHeader)         -- Get scheme-aware text color
HDG_UIHelpers.GetAccentColor(alpha)                 -- Get scheme-aware accent color
HDG_UIHelpers.GetPanelColor(alpha)                  -- Get scheme-aware panel background color
HDG_UIHelpers.GetBgColor(alpha)                     -- Get scheme-aware main background color
HDG_UIHelpers.GetProgressBarColor(percentage)       -- Get teal gradient color for progress bars
HDG_UIHelpers.ApplyBackdrop(frame, backdropType, bgColor, borderColor) -- Apply predefined backdrop
HDG_UIHelpers.SetupTooltip(frame, title, description, anchor) -- Setup standard tooltip
HDG_UIHelpers.SetupItemTooltip(frame, itemID, extraLines, anchor) -- Setup item tooltip
HDG_UIHelpers.SetupHoverEffect(frame, normalColor, hoverColor, textElement, normalTextColor, hoverTextColor) -- Setup hover colors
HDG_UIHelpers.SetupHoverWithTooltip(frame, normalColor, hoverColor, tooltipTitle, tooltipDesc, anchor) -- Combined hover+tooltip
HDG_UIHelpers.CreateSectionHeader(parent, text, yOffset, colorKey) -- Create section header
HDG_UIHelpers.CreateLeftHeader(parent, text, xOffset, yOffset, colorKey) -- Create left-aligned header
HDG_UIHelpers.CreateFilterButton(parent, text, width, isActive, onClick, options) -- Create filter button
HDG_UIHelpers.CreatePanel(parent, config)           -- Create standard panel frame
HDG_UIHelpers.ClearScrollContent(scrollContent)     -- Clear all children from scroll content
HDG_UIHelpers.FormatGold(copper, useTextures)       -- Format copper as gold string
HDG_UIHelpers.PrintMessage(message, messageType)    -- Print addon message with formatting
HDG_UIHelpers.StyleScrollBar(scrollFrame, thumbColor, trackColor) -- Style scrollbar minimalist
HDG_UIHelpers.CreateLumberRow(parent, lumberId, lumberInfo, queueData, allData, yOffset, farmingOptions) -- Create lumber tracking row
HDG_UIHelpers.CreateRowPool(factoryFn)              -- Create reusable row pool with acquire/release
HDG_UIHelpers.Data()                                -- Nil-safe accessor for HDG_Data module
HDG_UIHelpers.CreateExportDialog(opts)              -- Factory: themed export/import dialog {width,height,bottomPad,frameName} -> {frame,editBox,titleFS,selectAllBtn,closeBtn,:Show(text,title),:Hide()}

-- ============================================================================
-- HDG_Data.lua - Craft Logic (extracted from HDG_RecipesTab)
-- Recipe filter state lives on HDG_RecipesTab (search) + HDG.Store (config
-- toggles) + HDG.Store:GetCharacterProfessionFilter() (per-char). Data layer
-- takes filter context as a parameter; no shared mutable filter state here.
-- ============================================================================
HDG_Data.CanCraftRecipe(recipe)                     -- Check if player can craft recipe now
HDG_Data.GetCraftableRecipes(professionFilter)      -- Get all craftable recipes (takes filter)
HDG_Data.RecipeMatchesFilters(recipe, ctx)          -- Check recipe vs caller-supplied filter ctx

-- ============================================================================
-- HDG_PowerCrafting.lua - Material Aggregation (extracted from HDG_RecipesTab)
-- ============================================================================
HDG_PowerCrafting.AggregateMaterials(craftingQueue)  -- Aggregate direct materials from crafting queue
HDG_PowerCrafting.AggregateRawMaterials(craftingQueue) -- Aggregate raw materials (expands crafted)
HDG_PowerCrafting.AggregateMaterialsByRecipe(craftingQueue) -- Materials grouped by recipe
HDG_PowerCrafting.AggregateMaterialsByRecipeRaw(craftingQueue) -- Raw materials grouped by recipe
HDG_PowerCrafting.FilterAndSortMaterials(materials) -- Filter and sort material list
HDG_PowerCrafting.CategorizeMaterials(matArray)     -- Categorize materials by source type
HDG_PowerCrafting.CategorizeMaterialsForRecipe(materials) -- Categorize materials for one recipe
HDG_PowerCrafting.GetSubsidiaryRecipes(item, multiplier) -- Get crafted sub-components
HDG_PowerCrafting.HasSubsidiaryRecipes(item)        -- Check if item has crafted sub-components

-- ============================================================================
-- HDG_CraftDialog.lua - Modal craft confirmation dialog
-- ============================================================================
HDG_CraftDialog.Show(item, queueIndex)              -- Show craft confirmation dialog
HDG_CraftDialog.Execute(item, queueIndex, quantity) -- Execute the craft (window must be ready)

-- ============================================================================
-- HDG_ProfessionSidebar.lua - Left rail of the Recipes tab
-- ============================================================================
HDG_ProfessionSidebar.Init(frame)                   -- Capture mainFrame ref
HDG_ProfessionSidebar.Refresh()                     -- Rebuild expansion + per-profession buttons

-- ============================================================================
-- HDG_QueuePanel.lua - Middle column of the Recipes tab
-- ============================================================================
HDG_QueuePanel.Init(frame)                          -- Capture mainFrame ref
HDG_QueuePanel.Create()                             -- Build queue panel + scrollbox + lumber widget
HDG_QueuePanel.Refresh()                            -- Repaint queue (was RecipesTab:RefreshCraftingQueue)

-- ============================================================================
-- HDG_MaterialsPanel.lua - Right column of the Recipes tab
-- ============================================================================
HDG_MaterialsPanel.Init(frame)                      -- Capture mainFrame ref
HDG_MaterialsPanel.Create()                         -- Build panel: header, sort/raw toggles, scrollbox, cost line, AddAll CTA
HDG_MaterialsPanel.Refresh()                        -- Rebuild materials DataProvider (was RecipesTab:RefreshMaterials)
HDG_MaterialsPanel.AddAllToAuctionator()            -- Send queue mats to Auctionator search list (was RecipesTab:AddAllMaterialsToAuctionator)

-- ============================================================================
-- HDG_RecipesTab.lua - Recipe list panel + tab orchestration
-- ============================================================================
HDG_RecipesTab:Init(frame)                          -- Initialize module + delegate Init to sub-panels
HDG_RecipesTab:CreateRecipePanel()                  -- Create recipe list panel (left column)
HDG_RecipesTab:Create()                             -- Create all three panels (recipe + queue + materials)
HDG_RecipesTab:AddToCraftingQueue(recipe, skipRefresh) -- Add recipe to crafting queue
HDG_RecipesTab:AddAllMaterialsToAuctionator()       -- Add all materials to Auctionator search
HDG_RecipesTab:RefreshRecipes()                     -- Refresh recipe list
HDG_RecipesTab:Refresh()                            -- Refresh all tab content
HDG_RecipesTab:Show()                               -- Show recipes tab panels
HDG_RecipesTab:Hide()                               -- Hide recipes tab panels

-- ============================================================================
-- HDG_PowerCrafting.lua - DAG-Based Recipe Resolution
-- ============================================================================
HDG_PowerCrafting.GetRecipeByItemID(itemID)         -- Get recipe entry by output itemID
HDG_PowerCrafting.GetAllRecipesForItem(itemID)      -- Get ALL recipes that produce itemID
HDG_PowerCrafting.IsCraftedReagent(itemID)          -- Check if item is a crafted reagent
HDG_PowerCrafting.GetCraftedRecipe(itemID)          -- Get recipe for crafted item (basic slots only)
HDG_PowerCrafting.BuildDependencyGraph(decorRecipe) -- Build dependency graph for recipe
HDG_PowerCrafting.TopologicalSort(graph)            -- Kahn's algorithm for crafting order
HDG_PowerCrafting.CalculateRawMaterials(craftingQueue) -- Get total raw materials for queue
HDG_PowerCrafting.GetCraftingOrder(decorRecipe)     -- Get ordered crafting steps
HDG_PowerCrafting.GetItemName(itemID)               -- Get item name with fallbacks
HDG_PowerCrafting.CanPlayerCraft(itemID)            -- Check if player can craft item (stub)
HDG_PowerCrafting.GetMaterialBreakdown(decorRecipe) -- Get detailed material breakdown

-- ============================================================================
-- HDG_VendorResolver.lua - Vendor Name Resolution & Data Access
-- ============================================================================
-- HDG_VendorDB[npcID] = {name, zone, mapID, x, y, faction, exp=, added=, race={}, note="", items={}}
--   race = {"DarkIronDwarf"} or {"Dwarf","Gnome"}         -- Optional: race gate (UnitRace fileNames)
--   note = "directions string"                            -- Optional: built-in vendor directions
-- HDG_VendorByItem = {}                                   -- Reverse index: [itemID] = {npcID1, npcID2, ...} (built at init)
-- HDG_VendorByMapID = {}                                  -- Reverse index: [uiMapID] = {npcID1, npcID2, ...} (built at init)
HDG_VendorResolver.Initialize()                            -- Load cached NPC names, build reverse index
HDG_VendorResolver.SaveCache()                             -- Save name cache to SavedVariables
HDG_VendorResolver.GetVendorName(vendorEntry)              -- Get resolved vendor name for a VendorDB entry
HDG_VendorResolver.GetVendorNameByID(npcID)                -- Get vendor name by npcID (preferred method)
HDG_VendorResolver.TryResolveNPCName(npcID)                -- Attempt NPC name resolution via WoW APIs
HDG_VendorResolver.CacheName(npcID, name)                  -- Cache a resolved NPC name
HDG_VendorResolver.GetVendorsForItem(itemID)               -- Get vendor list: {npcID, name, zone, mapID, x, y, goldCost, factionID, minRep, factionName, currencyCost, race, note}
HDG_VendorResolver.FormatRaceRequirement(vendor)             -- Format race requirement as icon+name string, or nil
HDG_VendorResolver.MeetsRaceRequirement(vendor)              -- Check if player's race meets vendor requirement
HDG_VendorResolver.FormatRepRequirement(vendor)            -- Format rep as "FactionName — Standing" or nil
HDG_VendorResolver.MeetsRepRequirement(vendor)             -- Check if player meets vendor's rep/renown requirement
HDG_VendorResolver.FormatGoldCost(copper)                  -- Format copper as gold/silver/copper display
HDG_VendorResolver.GetStats()                              -- Get cache statistics
HDG_VendorResolver.GetCurrencyCost(itemID)                 -- O(1) lookup: resolves static VendorDB currency data to {{amount, name, icon}, ...} or nil
HDG_VendorResolver.ZonePctToMap(mapID, pctX, pctY)         -- Convert zone-pct coords (0-100) to map coords (0-1)
HDG_VendorResolver.ZoneHasUncollectedVendorItems(uiMapID)  -- Quick check: zone has uncollected vendor items?
HDG_VendorResolver.GetVendorsInZoneWithUncollected(uiMapID)-- Get vendors in zone with uncollected item lists

-- ============================================================================
-- HDG_AllDecorDB.lua - Master Decor Database (all ~1600 items)
-- ============================================================================
-- HDG_AllDecorDB = {}                                    -- Global: [itemID] = {decorID, sourceType, "sourceName", "sourceDetail"}
-- sourceType constants: CONFIG.SOURCE_TYPE = { UNKNOWN=0, ACHIEVEMENT=1, QUEST=2, WORLD_QUEST=3,
--   DROP=4, VENDOR=5, CRAFTED=6, LEARNED=7, GATHERING=8, TREASURE=9, PROMOTION=10, PROFESSION=11, SHOP=12 }
-- CONFIG.ACQUIRABLE_SOURCE_TYPES = {1, 2, 3, 4, 6, 9, 10, 12}  -- Shown in Acquisition tab (6=Crafted)

-- ============================================================================
-- HDG_AcqData.lua - Acquisition Data & Filtering (no UI frames)
-- ============================================================================
-- (filter state lives on HDG_AcquisitionTab as acqFilters/acqSortMode locals;
--  Rebuild* and ItemPassesFilters take filters as a parameter)
-- HDG_AcqData.vendorItems                                 -- [npcID] = {itemID, ...}
-- HDG_AcqData.vendorExpansion                             -- [npcID] = expansion string (computed from mapID)
-- HDG_AcqData.allItems                                    -- Merged deduped acquirable itemIDs
-- HDG_AcqData.craftableByItem                             -- [itemID] = spellID
-- HDG_AcqData.uniqueZones                                 -- Sorted zone names for dropdown
-- HDG_AcqData.uniqueFactions                              -- Sorted faction names for dropdown
-- HDG_AcqData.uniqueExpansions                            -- Sorted expansion names for dropdown
-- HDG_AcqData.filteredItems                               -- ItemIDs passing filters (By Item view)
-- HDG_AcqData.filteredVendors                             -- NpcIDs with matching items (By Vendor view)
-- HDG_AcqData.vendorCounts                                -- [npcID] = {total=N, collected=N}
HDG_AcqData.BuildCaches(CONFIG)                            -- Build all caches from VendorDB/DecorDB/AllDecorDB
HDG_AcqData.RebuildFilteredItems(CONFIG)                   -- Apply filters → filteredItems
HDG_AcqData.RebuildFilteredVendors(CONFIG)                 -- Apply filters per vendor → filteredVendors + counts
HDG_AcqData.ItemPassesFilters(itemID, CONFIG)              -- Unified filter check
HDG_AcqData.GetSourceTypeLabel(srcType, CONFIG)            -- "Achievement"/"Quest"/etc.
HDG_AcqData.GetSourceTypeAtlas(srcType, CONFIG)            -- Atlas name for source type icon
HDG_AcqData.IsAcquirableType(srcType)                      -- Check if source type is acquirable
HDG_AcqData.GetSourceInfo(itemID)                          -- Get AllDecorDB entry: {decorID, type, name, detail} or nil
HDG_AcqData.GetVendorName(npcID)                           -- Get vendor name from VendorDB[npcID][1]
HDG_AcqData.GetVendorZone(npcID)                           -- Get vendor zone from VendorDB[npcID][2]
HDG_AcqData.GetVendorMapID(npcID)                          -- Get vendor mapID from VendorDB[npcID][3]

-- ============================================================================
-- HDG_AcqRows.lua - Row Renderers (ScrollBox initializer/bind)
-- Pool-based factories were retired when the outer scroll migrated to
-- WowScrollBoxList. The ScrollBox owns the frame pool; this module supplies
-- the one-time initializer and per-bind renderers for three element kinds:
-- "item", "vendor" (header), "bundle" (Shop bundle header).
-- ============================================================================
HDG_AcqRows.GetElementExtent(elementData, CONFIG)          -- Variable-height: item=spacing, vendor=VENDOR_ROW_HEIGHT, bundle=18
HDG_AcqRows.InitializeRow(frame, CONFIG)                   -- One-time: create all widgets for all three kinds, install shared scripts
HDG_AcqRows.BindRow(frame, elementData, CONFIG, ctx)       -- Per-bind dispatcher; ctx = {selectedItemID, selectedNpcID, expandedVendors, onSelectItem, onVendorToggle}
HDG_AcqRows.BindItemRow(frame, elementData, CONFIG, ctx)   -- Kind=item: itemID [+ npcID, indent]
HDG_AcqRows.BindVendorRow(frame, elementData, CONFIG, ctx) -- Kind=vendor: npcID
HDG_AcqRows.BindBundleRow(frame, elementData, CONFIG)      -- Kind=bundle: bundle={name,cost,...}, indent
HDG_AcqRows.UpdateRowHighlights(scrollBox, itemID, npcID)  -- Repaint item-row selection via scrollBox:ForEachFrame
HDG_AcqRows.InvalidateSchemeCache()                        -- Drop cached scheme (call on theme change)
HDG_AcqRows.ReleaseAllCells()                              -- Release gallery cells, cancel timers
HDG_AcqRows.CreateGalleryCell(parent, itemID, x, y, cellSize, selectedID, onSelect, CONFIG, npcID)
HDG_AcqRows.UpdateGalleryHighlights(selectedItemID)        -- Update gallery cell selection borders

-- ============================================================================
-- HDG_AcquisitionTab.lua - Acquisition Guide Tab
-- ============================================================================
HDG_AcquisitionTab:Init(configRef, mainFrameRef, dbRef)    -- Initialize module with references
HDG_AcquisitionTab:CreatePanel()                           -- Create the acquisition panel UI
HDG_AcquisitionTab:Show()                                  -- Show the acquisition tab
HDG_AcquisitionTab:Hide()                                  -- Hide the acquisition tab
HDG_AcquisitionTab:IsShown()                               -- Check if tab is visible
HDG_AcquisitionTab:Refresh()                               -- Full refresh of all content
HDG_AcquisitionTab:RefreshList()                           -- Refresh the filtered item list
HDG_AcquisitionTab:SelectItem(itemID)                      -- Select item and update all panels
HDG_AcquisitionTab:UpdateHeaderPanel(itemID)               -- Update header (name + collected badge)
HDG_AcquisitionTab:UpdatePreviewModel(itemID)              -- Load 3D preview model
HDG_AcquisitionTab:UpdateDetailPanel_Vendor(itemID, vendors) -- Vendor info in detail text area
HDG_AcquisitionTab:UpdateDetailPanel_NonVendor(itemID, si) -- Source info in detail text area
HDG_AcquisitionTab:UpdateInfoPanel(itemID, si)             -- Bottom info for non-vendor items
HDG_AcquisitionTab:UpdateNoteDisplay(itemID)               -- Update user note display in header
HDG_AcquisitionTab:UpdateVendorInventory(vendor)           -- Update 3D gallery grid

-- ============================================================================
-- HDG_StyleEngine.lua - Custom Style Support (V2.8)
-- ============================================================================
-- StyleEngine:GetAllStyleDefs()                        -- Get merged built-in + custom style defs
-- StyleEngine:InvalidateCustomStyle(styleId)           -- Rebuild cache for one custom style
-- StyleEngine:RemoveCustomStyle(styleId)               -- Remove style from engine caches
-- StyleEngine:ScoreStyleLive(styleDef, limit)          -- Score items against ad-hoc def for preview

-- ============================================================================
-- HDG_Core.lua - Decor ID Lookups
-- ============================================================================
-- HousingDecorGuide.BuildDecorLookups()               -- Lazy-build _decorToItem / _itemToDecor maps from HDG_AllDecorDB
-- HousingDecorGuide._decorToItem                      -- [decorID] = itemID (populated after BuildDecorLookups)
-- HousingDecorGuide._itemToDecor                      -- [itemID] = decorID (populated after BuildDecorLookups)

-- ============================================================================
-- HDG_StyleSerializer.lua - Import/Export Custom Styles
-- ============================================================================
-- HDG_StyleSerializer:Export(styleDef)                 -- Encode custom style as "HDG:1:<base64>" string
-- HDG_StyleSerializer:ExportSnapshot(def, useDecorID)  -- Encode snapshot as "HDGVL:1:<base64>" (source=snapshot header); useDecorID emits decorIDs + idtype=decor
-- HDG_StyleSerializer:Import(encodedStr)               -- Decode HDG:1: or HDGVL:1: string -> styleDef or nil, err
-- HDG_StyleSerializer:ImportSnapshotFromVL(meta, dataLines) -- (internal) Build snapshot styleDef from parsed VL payload
-- HDG_StyleSerializer:ImportShoppingList(encodedStr)   -- Decode HDGVL:1: -> snapshot styleDef (auto-resolves decorIDs via ResolveDecorIDs)

-- ============================================================================
-- HDG_PriceIntegration.lua - TSM/Auctionator Integration
-- ============================================================================
HDG_PriceIntegration.GetItemPrice(itemID, forceAddon) -- Get market price (TSM or Auctionator)
HDG_PriceIntegration.FormatGold(copper, useTextures) -- Format copper as gold string
HDG_PriceIntegration.FormatGoldOnly(copper)         -- Format as gold-only with commas
HDG_PriceIntegration.HasPriceAddon()                -- Check if any price addon available
HDG_PriceIntegration.IsTSMAvailable()               -- Check if TSM is available
HDG_PriceIntegration.IsAuctionatorAvailable()       -- Check if Auctionator is available
HDG_PriceIntegration.GetAvailableAddons()           -- Get list of available price addons
HDG_PriceIntegration.GetActiveAddon()               -- Get name of active price addon
HDG_PriceIntegration.GetRegionSaleAvg(itemID)       -- Get TSM region sale average
HDG_PriceIntegration.CalculateTotalPrice(materials) -- Calculate total price for material list

-- ============================================================================
-- HDG_VendorShoppingList.lua - Vendor Shopping List + Zone Scanner Widget
-- ============================================================================
-- SerializeVendorList(useDecorID)                      -- (local) Encode active list as HDGVL:1: string; useDecorID emits decorIDs + idtype=decor
-- DeserializeVendorList(encoded)                       -- (local) Decode HDGVL:1: -> entries, err, meta (auto-resolves decorIDs)
-- ============================================================================
-- HDG_LumberTracker.lua - Materials API
-- ============================================================================
-- HDG_LumberTracker.GetNonLumberMaterials()               -- Returns directMats, rawMats tables (keyed by reagentID)

-- ============================================================================
-- HDG_VendorShoppingList.lua - Vendor Shopping List Widget
-- ============================================================================
HDG_VendorShoppingList:Init(configRef)                     -- Store config reference
HDG_VendorShoppingList.Toggle()                            -- Show/hide shopping list
HDG_VendorShoppingList.Show()                              -- Show shopping list
HDG_VendorShoppingList.Hide()                              -- Hide widget
HDG_VendorShoppingList.IsShown()                           -- Visibility check
HDG_VendorShoppingList.GetCount()                          -- Shopping list item count (for badge)
HDG_VendorShoppingList.Refresh()                           -- Rebuild list content
HDG_VendorShoppingList.MapListWaypoints()                  -- Set TomTom waypoints for all list vendors

HDG_ZoneMode.OnZoneChanged(mapID)                          -- Zone scanner trigger (called from event handler)
HDG_ZoneMode.ShowPopup()                                   -- Show standalone zone vendor popup
HDG_ZoneMode.HidePopup()                                   -- Hide zone vendor popup
HDG_ZoneMode.IsPopupShown()                                -- Popup visibility check
HDG_ZoneMode.MapWaypoints()                                -- Set waypoints for current zone vendors
HDG_ZoneMode.GetCurrentMapID()                             -- Current zone map ID
HDG_ZoneMode.CreateGearPopup(anchor)                       -- Zone scanner settings popup


