wow_bejeweled/docs/api-baseline.md

Retail API baseline

The modernization baseline is the authoritative WoW UI/API source snapshot for live build 12.1.0.69404, Interface 120100, pinned at Gethe/wow-ui-source commit 81d15e42f16f3473131880500e7a8c8eb88fa5e6. These constraints govern the runtime implementation.

Area	Verified constraint	Future use
Backdrops	Frames that call backdrop methods must inherit BackdropTemplate.	UI/Backdrops.lua will create compatible frames before calling SetBackdrop or related methods.
Timers	C_Timer.After and C_Timer.NewTicker are the supported timer primitives.	Replace legacy polling/on-update timing only after behavior-equivalence analysis.
Addon sounds	PlaySoundFile continues to support addon-owned paths. Current Blizzard Mainline code calls PlaySound with identifiers from the current SOUNDKIT table. Obsolete Blizzard-internal paths are not stable.	Core/Audio.lua preserves all addon media paths and replaces the legacy Sound\\Spells\\LevelUp.wav call with SOUNDKIT.UI_SCENARIO_STAGE_END, falling back to SOUNDKIT.UI_AUTO_QUEST_COMPLETE when necessary.
Metadata	Addon metadata access is provided by C_AddOns.	Route future metadata queries through C_AddOns.
Animation	Frames expose CreateAnimationGroup; groups expose CreateAnimation, Play, Pause, IsPaused, Stop, and SetScript; animations expose SetOrder; translation animations expose SetOffset; alpha animations expose SetFromAlpha and SetToAlpha.	UI/Animations.lua reuses per-frame groups for cascades, pauses/resumes active groups with the session, and uses ordered translation pairs for legacy invalid-swap rollback. Completion scripts are removed before cancellation.
Texture rendering	SimpleFrame:CreateTexture returns a texture region. SimpleTextureBase exposes SetTexture, four-coordinate SetTexCoord, SetBlendMode, and SetRotation(radians, optionalPoint) in all environments.	UI/GemPool.lua projects addon-owned textures and proven legacy UV coordinates. UI/Animations.lua uses supported texture rotation instead of the legacy eight-coordinate rotation helper.
UI text	SimpleFrame:CreateFontString returns a non-nil SimpleFontString. Its current all-environment contract exposes SetFont, SetText, SetFormattedText, SetTextColor, and horizontal justification; SetFont reports whether the asset and height were accepted. The first Retail smoke test on 2026-08-24 returned false for the preserved Contb___.ttf.	UI/Fonts.lua attempts the immutable bundled font, then selects STANDARD_TEXT_FONT, GameFontNormal:GetFont(), or the built-in Friz Quadrata path. All runtime text uses this boundary so an obsolete font asset cannot abort startup.
Local chat output	The pinned Mainline ChatFrameUtil writes local system messages with DEFAULT_CHAT_FRAME:AddMessage(message, info.r, info.g, info.b, info.id), using an entry from ChatTypeInfo; the Mainline chat handler continues to classify SKILL as a displayable chat type.	UI/HUD.lua reports deduplicated skill gains to DEFAULT_CHAT_FRAME with ChatTypeInfo["SKILL"], behind the preserved publishSkillGains setting. This does not send a guild or network message.
Timed setup slider	SimpleSlider is available in all environments and exposes SetMinMaxValues, SetValueStep, SetObeyStepOnDrag, SetOrientation, SetThumbTexture, GetThumbTexture, SetValue, and GetValue.	UI/MainWindow.lua builds a BackdropTemplate-safe horizontal selector with the legacy-proven 2–10 range, unit step, and five-minute default.
Main window	SimpleFrame exposes RegisterForDrag, SetMovable, protected StartMoving, and protected StopMovingOrSizing in all environments. UnitName(unit) accepts a non-nil unit token and returns non-nil name/server strings, subject to the documented identity restriction.	UI/MainWindow.lua begins movement only from its direct left-button drag callback when the profile is unlocked. Core/Init.lua supplies UnitName("player") lazily as the existing SavedVariables authentication identity.
Line rendering	SimpleFrame:CreateLine returns SimpleLine; its current all-environment contract exposes ClearAllPoints, SetStartPoint, SetEndPoint, and SetThickness. Line regions inherit texture-region operations used here for addon texture/color, additive blending, alpha, and visibility.	UI/Animations.lua replaces the removed legacy DrawRouteLine call with pooled, board-relative lightning lines and preserves the 15-tick alternating-highlight lifetime.
Addon compartment	TOC metadata names global callbacks. In the pinned Mainline implementation, click invokes the global with (addonName, buttonName); hover enter/leave invoke their globals with (addonName, menuButtonFrame). Current Blizzard code uses GameTooltip:SetOwner, SetText, AddLine, Show, and Hide for frame hover help.	UI/Compartment.lua registers the three distinct callbacks, toggles only on a left click, and anchors concise hover help to the supplied menu button.
Minimap launcher	Current frames expose the positioning, sizing, scale, mouse-script, and clamping operations used by the preserved launcher. Pinned Mainline code continues to normalize GetCursorPosition() by effective UI scale before positioning a frame.	UI/Minimap.lua restores the 33-pixel local launcher, left-click window toggle, tooltip, right-drag attached/detached placement, and the existing hideMinimap, minimapAngle, minimapDetached, minimapX, and minimapY profile fields.
Addon lifecycle	ADDON_LOADED is synchronous and supplies addOnName followed by containsBindings. Frames expose RegisterEvent(eventName) and UnregisterEvent(eventName) in all environments.	Core/Init.lua filters the event by addon name, unregisters its one-shot listener, and performs idempotent initialization after every TOC module is loaded.
Friends	C_FriendList.GetFriendInfoByIndex(index) may return nothing; otherwise it returns one FriendInfo table with name and Boolean connected fields.	Replace all legacy positional GetFriendInfo(index) reads with a nil-checked table read and whisper only when info.connected.
Battlefield queues	Current Blizzard Mainline code still reads local status = GetBattlefieldStatus(index) and compares the first return with queue states.	Keep the queue scan local and preserve the legacy status == "queued" behavior.
Ready checks	C_PartyInfo.ConfirmReadyCheck(isReady) takes one non-nilable Boolean and is restricted; the global ConfirmReadyCheck is a deprecation fallback.	Preserve the isReady Boolean as the semantic input, do not require deprecated globals, and verify the supported observation mechanism before implementation.
Combat log	COMBAT_LOG_EVENT_UNFILTERED remains in the all-environment combat-log system, is marked restricted, and has no documented payload fields. The snapshot exposes all-environment C_CombatLogInternal.GetCurrentEventInfo() and secure-only C_CombatLogSecure.GetCurrentEventInfo() with undocumented variadic returns; the old global accessor exists only behind deprecation fallbacks.	Isolate all combat-log-dependent skills behind one compatibility adapter. Do not copy legacy tuple offsets or claim runtime compatibility until the adapter is verified in build 12.1.0.69404.
Rated PvP	C_PvP.GetTeamInfo(factionIndex) returns a nilable PVPTeamInfo table (name, rating, ratingNew, ratingMMR). Blizzard's current result UI obtains the local player's result from C_PvP.GetScoreInfoByPlayerGuid(GetPlayerGuid()) and reads ratingChange. Persistent GetArenaTeam membership is absent from the snapshot.	Restore the legacy “rating increased” skill from local-player PVPScoreInfo.ratingChange > 0, not obsolete arena-team names.

API existence alone does not prove behavioral equivalence. Each future substitution must cite the legacy call site, arguments, return values, timing assumptions, and the authoritative current API contract before implementation.

Phase-gate evidence

• Addon lifecycle and frame-event contracts: AddOnsDocumentation.lua and SimpleFrameAPIDocumentation.lua
• Supported SoundKit identifiers and current PlaySound(SOUNDKIT.*) usage: SoundKitConstants.lua and LootFrame.lua
• Frame texture construction and rendering methods: SimpleFrameAPIDocumentation.lua and SimpleTextureBaseAPIDocumentation.lua
• HUD font-string creation and text/font operations: SimpleFrameAPIDocumentation.lua and SimpleFontStringAPIDocumentation.lua
• Local chat output and SKILL routing: ChatFrameUtil.lua and ChatFrameOverrides.lua
• Timed setup slider operations: SimpleSliderAPIDocumentation.lua
• Main-window movement and player-name identity: SimpleFrameAPIDocumentation.lua and UnitDocumentation.lua
• Line construction and endpoint/thickness contracts: SimpleFrameAPIDocumentation.lua, SimpleLineAPIDocumentation.lua, and SimpleTextureBaseAPIDocumentation.lua
• Animation-group lifecycle, translation, and alpha contracts: SimpleAnimGroupAPIDocumentation.lua, SimpleAnimTranslationAPIDocumentation.lua, and SimpleAnimAlphaAPIDocumentation.lua
• Animation ordering: SimpleAnimAPIDocumentation.lua
• Addon-compartment metadata dispatch and current callback signatures: AddonCompartment.lua
• Minimap-button frame operations and effective-scale cursor positioning: SimpleFrameAPIDocumentation.lua and LootFrame.lua
• Friend contract: FriendListDocumentation.lua
• Combat-log event/access environments: CombatLogDocumentation.lua, CombatLogInternalDocumentation.lua, and CombatLogSecureDocumentation.lua
• Ready-check contract: PartyInfoDocumentation.lua
• Queue usage: PVPUtil.lua
• Rated-PvP contracts and current local-player result flow: PvpInfoDocumentation.lua and PVPMatchResults.lua