--- paths: - "core/forever.lua" - "core/constants.lua" - "BetterBags_Camelot.toc" - "bags/bank.lua" - "frames/bankslots.lua" - "frames/item.lua" - "data/equipmentsets.lua" - "spec/core/forever_spec.lua" - "spec/core/constants_spec.lua" - "spec/frames/bankslots_spec.lua" - "spec/bags/bank_panel_suppress_spec.lua" - "spec/bags/bank_purchase_button_spec.lua" --- # WoW: Forever (Camelot) Support WoW: Forever (internal codename **Camelot**; launched 2026-11-04 as build `1.60.1.70790`, product `wowf`, installed in `_forever_`; the beta was `wow_classic_beta`; TOC Interface `16001`, which warcraft.wiki.gg's Patch 1.60.1 API changes page gives for 1.60.1; a `_Forever.toc` suffix is accepted as an alias of `_Camelot.toc` since 70291) is a **mainline retail fork**: the engine and UI are retail, so `addon.isRetail == true`, exactly like live retail (see §1 for how the project ID changed in build 70170). Camelot therefore runs BetterBags' **retail** code paths. Its bank is still the numbered-container model (BetterBags renders its own window by scanning container bags via `C_Container`; it never uses Blizzard's paged `BankPanel`), it just exposes **9 character + 9 account bank tabs** instead of retail's **6 + 5**, and the `Enum.BagIndex.AccountBankTab_N` values are shifted up accordingly. ## 1. Detection — `addon.isRetail` and `addon.isForever` Two runtime eras exist, and detection must work on both: - **Before build 1.60.1 (70170):** `WOW_PROJECT_ID == WOW_PROJECT_MAINLINE`. No build, version, or project number distinguishes Camelot from live retail, so the only signal is **which TOC loaded**. - **From 70170 on:** Blizzard added `Blizzard_ProjectConstants/Camelot/ProjectConstants.lua` (`[AllowLoadGameType camelot]` in `Blizzard_ProjectConstants.toc`), which sets `WOW_PROJECT_CAMELOT = 18` and `WOW_PROJECT_ID = WOW_PROJECT_CAMELOT`. `WOW_PROJECT_CAMELOT` is only defined on the camelot game type (Blizzard's own `GlueParent.lua` relies on that: `WOW_PROJECT_CAMELOT or WOW_PROJECT_MAINLINE`). How `core/constants.lua` handles both: - A local `isCamelotProject = WOW_PROJECT_CAMELOT ~= nil and WOW_PROJECT_ID == WOW_PROJECT_CAMELOT`. The `~= nil` guard is load-bearing: when both globals are nil, a bare `WOW_PROJECT_ID == WOW_PROJECT_CAMELOT` is `nil == nil`, i.e. true. That is exactly the spec environment (it defines no `WOW_PROJECT_*` globals), where it would flag every spec that loads `core/constants.lua` as Forever and turn off the warbank. - `addon.isRetail = WOW_PROJECT_ID == WOW_PROJECT_MAINLINE or isCamelotProject`. **Never** compare against `WOW_PROJECT_MAINLINE` alone again. That is what broke 70170: `isRetail` went false, the Classic branch built `const.BANK_BAGS` with `[Enum.BagIndex.Bank]` as a key, and Camelot's retail-shaped `Enum.BagIndex` has no `Bank` member (`Characterbanktab = -2`, `Keyring = -1`), so the addon died at load with `core/constants.lua: table index is nil`. Every other flavor gate in the addon reads `addon.isRetail`, so this one line is the whole fix. - `core/forever.lua` sets `addon.isForever = true`. It is listed **only** in `BetterBags_Camelot.toc`, so it runs solely on the Camelot client. It must load **after** `core/boot.lua` (which creates the addon) and **before** `core/constants.lua`. It is still required: it is the only signal on pre-70170 builds. - `core/constants.lua` normalizes `addon.isForever = addon.isForever == true or isCamelotProject` next to the other `addon.is*` flavor flags, so every consumer sees a plain boolean (`false` on retail/classic, `true` on Camelot) from either signal. - **Never** detect Camelot with `GetBuildInfo`/TOC version checks. The 16001 interface number is not a reliable discriminator. - **Never** add `core/forever.lua` to `BetterBags.toc` (the base TOC) or any non-Camelot TOC — doing so would flag every retail/classic user as Forever. - Vendored libraries carry their own project checks. `libs/LibUIDropDownMenu` (an external, not our code) detects Forever as `projectID == WOW_PROJECT_MAINLINE` with a 1.x interface, so on 70170+ it falls into none of its flavor modes. That needs an upstream fix, not a local patch to `libs/` (which is gitignored and pulled by the packager). Coverage: `spec/core/forever_spec.lua` (flag set; present in Camelot TOC, absent from base TOC; loads before constants.lua) and `spec/core/constants_spec.lua` (boolean normalization, and "client flavor detection (WOW_PROJECT_ID)": the 70170 Camelot project with Camelot's real `Enum.BagIndex` loads and is retail + Forever, the project ID alone sets Forever, pre-70170 mainline + TOC flag still works, live retail and Classic Era are unchanged). ## 2. Bank tab tables are sized off the enum, not hard-coded The retail bank bag-ID tables in `core/constants.lua` — `BANK_TAB`, `BANK_BAGS`, `BANK_ONLY_BAGS`, `BANK_ONLY_BAGS_LIST`, `ACCOUNT_BANK_BAGS` — are built by probing `Enum.BagIndex` with the `enumerateBagIndices(prefix)` helper, which walks contiguous members named `"1"`, `"2"`, … and stops at the first missing index. This yields **6 + 5 on live retail** (byte-for-byte identical to the old static literals) and **9 + 9 on Camelot**, with **no `addon.isForever` branch** — the enum itself is the source of truth, so this is also forward-compatible if Blizzard adds tabs to either client. - **Why this is the load-bearing bank fix:** nearly all of `data/items.lua` (scan, partition, free-slot count, cache-clear) iterates these tables with `pairs()` or tests membership (`const.ACCOUNT_BANK_BAGS[bagid]`) or the symbolic `>= AccountBankTab_1` threshold, and `GetPossibleTabIDs` / `Phase1_DetermineBags` iterate `pairs(const.BANK_BAGS)` / `pairs(const.ACCOUNT_BANK_BAGS)`. Once the constant tables cover all 9+9 tabs, the entire scan/partition/routing pipeline adapts automatically — item storage container IDs are unchanged (`CharacterBankTab_1..9` = bag IDs 6..14, `AccountBankTab_1..9` = 15..23), so "player bags in bank" (`C_Bank.ShouldUsePlayerBagsInBank`) does **not** change what we scan. - **Do not** re-introduce static `CharacterBankTab_1..6` / `AccountBankTab_1..5` literals for these tables. A naive static add of tabs 7–9 would also throw `table index is nil` on live retail, where those enum members do not exist. `ACCOUNT_BANK_BAGS_LIST` is the ordered account-tab counterpart of `BANK_ONLY_BAGS_LIST`, built in the same loop, consumed by the bank tab slots panel (§3). Coverage: `spec/core/constants_spec.lua` ("dynamic bank tab sizing": 6+5 retail shape, 9+9 Camelot expansion across every derived table incl. `ACCOUNT_BANK_BAGS_LIST`, and `BANK_ONLY_BAGS_LIST` ordering by tab index). ## 3. Bank UI is retail code — it carries over; only tab counts needed fixing Camelot runs BetterBags' **retail** bank UI unchanged (`BankPanel`, `C_Bank.FetchPurchasedBankTabData`, `BankPanelPurchaseButtonScriptTemplate` + `overrideBankType`, `BankPanel:SetBankType`, `.TabSettingsMenu` all exist and behave as on retail — audited from the `origin/forever` source). `BankPanel.Header` and `BankPanel.AutoDepositFrame` do **not** exist on Camelot, but `bags/bank.lua` already nil-guards both and uses `SetAlpha(0)` + `Show()` (not `Hide()`), which is correct there too — no change needed. The bank window renders its own container-scan view, so Camelot's paged "player bags in bank" model (`ShouldUsePlayerBagsInBank`) does not affect us. Our tab-slots panel is the analogue of Camelot's physical bank-bag slots in bag mode, and of retail's virtual tabs in non-bag mode — same panel both ways. The only real gap was **tab count**, fixed by deriving from the §2 constant tables (not an `addon.isForever` branch — the enum already encodes the count, so this is forward-compatible and identical on retail): - `frames/bankslots.lua` `CreatePanel` builds `allTabSlots` from `const.BANK_ONLY_BAGS_LIST` (character) + `const.ACCOUNT_BANK_BAGS_LIST` (account), and sets `content.maxCellWidth = #allTabSlots` (was a fixed 11-entry literal + `maxCellWidth = 11`). Renders 11 slots on retail, 18 on Camelot. Coverage: `spec/frames/bankslots_spec.lua` ("Dynamic tab count derived from Constants"). - `integrations/quickfind.lua` classifies a bank tab id via membership in `const.BANK_ONLY_BAGS` / `const.ACCOUNT_BANK_BAGS` instead of the old hard bounds `<= CharacterBankTab_6` / `<= AccountBankTab_5` (which dropped Camelot tabs 7-9 / 6-9 into the visual-only fallback). Coverage: `spec/quickfind_spec.lua`. ## 4. No warbank on Forever — `addon.hasWarbank` Camelot has **no Account bank (Warbank / Warband bank)** at all, even though its `Enum.BagIndex` still declares `AccountBankTab_1..9`. This is a genuine behavioral divergence the enum cannot express, so it is gated on a dedicated predicate rather than the enum: - **`addon.hasWarbank = addon.isRetail and not addon.isForever`** (`core/constants.lua`, set next to the other flavor flags). True on live retail, false on Camelot and on classic. - **Central lever:** the account bag tables are built **only when `addon.hasWarbank`**. On Camelot they are left **present-but-empty** (`const.ACCOUNT_BANK_BAGS = {}`, `ACCOUNT_BANK_BAGS_LIST = {}`) — this must be explicit, because the enum probe would otherwise populate 9 phantom account tabs. Every **table-driven** warbank site then goes inert automatically with no per-site branch: the data sweep/partition/free-slot/cache-clear in `data/items.lua`, the bank tab slots panel (`frames/bankslots.lua` renders character tabs only), `integrations/quickfind.lua`, `data/loader.lua`, `data/refresh.lua` bank-change detection, the virtual-stack `"W"` hash discriminator, and `frames/item.lua` kind classing. - **Explicit `addon.hasWarbank` gates** for the warbank surfaces that reference `Enum.BankType.Account` / warbank UI directly (not through those tables): - `core/database.lua` `Migrate` — does **not** seed the default **Warbank** group (this is what kills the whole data-driven account-tab section / `tabIsAccountBank` routing). - `frames/groupdialog.lua` — the group-creation dialog omits the "Warbank" bank-type option. - `bags/bank.lua` — `money:Create(addon.hasWarbank)` (character-only bank wallet). - `frames/contextmenu.lua` — omits the "Clean Up Warbank" menu entry. - `frames/menubutton.lua` — bag-menu button drops the "Deposit Warbank Items" tooltip line and the shift-right deposit / SortWarbank branch; on Forever right-click always sorts the character bank (see bag-menu-button.md). - `data/refresh.lua` — a backpack sort with the bank open no longer sets `sortWarbank`. - `core/hooks.lua` — does not register the `AccountBanker` interaction. - **Do NOT** gate these on `addon.isRetail` alone (that is still true on Camelot) or on `addon.isForever` inline — use `addon.hasWarbank`, so classic (also warbank-less) stays correct and the intent reads clearly. Coverage: `spec/core/constants_spec.lua` ("warbank availability": empty tables + `hasWarbank` false on Forever, populated + true on retail), `spec/database_migration_spec.lua` ("default Warbank group gating"), `spec/refresh_spec.lua` ("sort the bank but NOT the warbank on a client without one"). ## 5. Slots panels use Blizzard's dark tooltip frame on Camelot `DefaultPanelFlatTemplate` renders **broken** on Camelot: its `Bg` starts 20px below the top (a reserved title strip), and its `ButtonFrameTemplateNoPortrait` NineSlice overhangs the top with tall metal header art that Camelot re-drew even taller (`Blizzard_SharedXML/Camelot/NineSliceLayoutOverrides.lua`) — Blizzard shipped a Camelot-only `NineSliceUtil.UpdateCornerCropping` just to survive it on short frames. On the short bag/bank **slots panels** this showed as an empty dark title-bar band + wrong border. Fix, as theme data (sonata.md §3b): the Default theme's `Clients.Forever` override of its `Slots` window style uses a **`TooltipBorderedFrameTemplate`** (dark, thin-bordered, carries its own background; cross-version-safe, verified on all five TOCs) colored black at 0.9 with a white border (`BackdropColor`, `BackdropBorderColor`), with **even padding of 8** (no reserved header) and the panel nudged 4 pixels right to line up with the bag window (`Layout.Offset`). Both slots panels are Slots windows (window.md §8), so both take it. **The filled template must sit strictly below the slot grid.** The first version created the tooltip template as a sibling child of the panel at the grid's own frame level; the grid is a clipping `WowScrollBox` (`clipChildren="true"`, `ScrollBox.xml`) whose buttons render as a group at the scroll box's level, so the 90%-black filled centre could draw over the grid and every slot button looked sunk under a dark film ("the buttons are a layer under the window"). The next version put the template on the panel frame itself, whose regions are always below its children. Now Sonata places every template **one level below the window frame** (`Level = -1`), the content box is a child of the window, and the grid a child of the content box, so the template is two levels below the grid (patterns-ui.md, "Filled Backdrops Belong on the Panel Frame"; sonata.md §3, "Where things go"). Never give a filled template a level at or above the window's. Coverage: `spec/sonata/themes_spec.lua` ("the slots panels": the tooltip frame, its colors, below the content, even padding, the offset), `spec/frames/bagslots_spec.lua` ("centers its bags with even padding on Classic and on WoW: Forever", "keeps its chrome below its bags") and `spec/frames/bankslots_spec.lua` ("draws Blizzard's dark tooltip frame below its tabs on WoW: Forever, padded evenly"). ## 6. Equipment-set scan routes by API existence, not TOC version `data/equipmentsets.lua` has two harvest implementations: `UpdatePreMidnight` (uses `EquipmentManager_UnpackLocation`) and `UpdateMidnight` (uses `EquipmentManager_GetLocationData`, the API 12.0/Midnight introduced when it removed `UnpackLocation`). The dispatcher in `equipmentSets:Update()` originally chose between them with the version gate `addon.isMidnight` (`addon.isRetail and tocVersion >= 120000`, `core/constants.lua`). Camelot is a mainline fork that already ships the Midnight `EquipmentManager` — only `GetLocationData`, no `UnpackLocation` — yet reports a **sub-12.0 TOC** (Interface `16001`), so `addon.isMidnight` is `false` on Forever. The version gate therefore routed Forever to `UpdatePreMidnight`, which called the non-existent `EquipmentManager_UnpackLocation` and crashed with `attempt to call a nil value` (triggered by `CreateEquipmentSet` → `EQUIPMENT_SETS_CHANGED` → `refresh:RequestUpdate` → `equipmentSets:Update`). This is the same lesson as §1: **no version number distinguishes Forever from other clients** — here it also fails to distinguish which EquipmentManager API is present. Fix: `Update()` selects the implementation by **feature detection**, preferring the old API where it exists — `if EquipmentManager_UnpackLocation ~= nil then UpdatePreMidnight() else UpdateMidnight() end`. This keeps every client that works today byte-for-byte unchanged (War Within retail and the classic-retail variants BCC/Cata/Mists all still have `UnpackLocation`, including the `not addon.isRetail` void-bank slot shift) and routes both Midnight **and** Forever to the `GetLocationData` path. `addon.isMidnight` is no longer the discriminator for equipment sets (it remains defined; it has no other consumer). Coverage: `spec/equipmentsets_spec.lua` ("Update" describe — UnpackLocation-present path, UnpackLocation-absent Midnight path, and the "does not crash on Forever (retail, non-midnight, no UnpackLocation)" regression). ## 7. Camelot bank container model — the bank is the purchased CharacterBankTab_N; -1 is the KEYRING (do not add it) Definitive container map on Camelot (verified live via a per-container `/run` dump plus the `origin/forever` source): - **Character bank storage = the purchased tabs `CharacterBankTab_1..9` = bag ids 6..14.** The first character tab costs nothing, but it is still a purchase, and under BetterBags it is never made for you (§10); the rest are bought for gold. `C_Bank.FetchPurchasedBankTabData(Enum.BankType.Character)` returns the purchased tabs' container ids (6, then 7…). BetterBags already scans these — they are in `const.BANK_BAGS` (§2). A live dump showed `6: slots=48, free=48` for a character with one 48-slot tab, matching the player's hand-counted 48 free. - **`Characterbanktab` (-2) / `Accountbanktab` (-3) hold bank-BAG objects, not items** (addressed `(Characterbanktab, bagSlotID)`); `GetContainerNumSlots(-2)` is 0. Harmless in `BANK_BAGS` (skipped by the `size > 0` guard), same as live retail. - **Bag id -1 is the KEYRING, NOT the bank.** `origin/forever:Blizzard_FrameXMLBase/Constants.lua` sets `KEYRING_CONTAINER = Enum.BagIndex.Keyring` and the enum has `Keyring = -1`; Camelot is Wrath-era and has a working keyring (`Blizzard_MainMenuBarBagButtons/Camelot/MainMenuBarBagButtons.lua` `GetKeyRingSize()` → `GetContainerNumSlots(-1)`). It persistently reports ~32 slots whether or not you are at the bank. **Do NOT add -1 to `const.BANK_BAGS`.** A prior fix misread an empty-bank dump (which, at 0 purchased tabs, showed only `-1: 32` because the free first tab hadn't been granted/loaded yet) and concluded -1 was the "base bank." Adding it made the aggregate free-space counter read `keyring(32) + bank(48) = 80` when the real bank was 48, and would have surfaced 32 keyring slots as bank space. That change (and its `not addon.isForever` keyring-guard edits in `data/items.lua`) was reverted. **The keyring is read with the backpack (issue #1121).** `core/constants.lua` adds `Enum.BagIndex.Keyring` to `BACKPACK_BAGS` and `BACKPACK_ONLY_BAGS` when `addon.isForever` and `C_ActionBar.ShouldShowKeyring()` (Forever-only, "isKeyringEnabled", the check Blizzard's own `ContainerFrame_IsHeldBag` and `ItemUtil.IteratePlayerInventory` make; present since the first Forever build in the UI source mirror, 69913). Not in `BACKPACK_ONLY_BAGS_LIST`: like Classic Era, there is no bag slot button for it. Live retail's enum also has a `Keyring` member but no keyring, so the flag gates it, not the enum. Every backpack table consumer then covers it: the harvest, `BAG_UPDATE` routing (`refresh:OnEnable`), priming, the buttons created at boot (40 per bag; the keyring has about 32 slots), `GetBagFromBagID`, and the bag window as a drop target (keys go to the keyring first, nothing else does). The existing keyring guards apply as on Classic Era: `Phase5_UpdateFreeSlots` leaves its slots out of free space, and Show Bags names it "Keyring", numbered after the last bag (`items:GetBagName`: "#6" on Classic Era, "#7" on Forever, after the reagent bag). Coverage: `spec/core/constants_spec.lua` ("keyring (Forever only)"), `spec/items_spec.lua` ("keyring section name (Show Bags)"), `spec/refresh_pipeline_spec.lua` ("shows the items in the Forever keyring, without counting its slots as free space"). **Nor are its slots shown as free slots.** With "show free slots" (`GetShowAllFreeSpace`), every empty slot of the kind is a button, and `IncludeBagInFreeSpace` (`data/items.lua`) let the keyring's through: a Forever screenshot showed 32 free slots for the keyring, each saying "1 slot free", the first 4 plain and the other 28 under a padlock. The padlock is Blizzard's: `SetFreeSlots` runs `ContainerFrameItemButtonMixin:UpdateExtended` (retail code, so on Forever), which marks a slot past `ContainerFrame_GetContainerNumSlots(bag)` as an "extended" slot, shows `ContainerFrameExtendedItemButtonTemplate` (the `Bags-padlock-authenticator` atlas) and turns the mouse off; for the keyring that count is `GetKeyRingSize()` (`Blizzard_MainMenuBarBagButtons/Camelot/MainMenuBarBagButtons.lua`), the filled slots rounded up to a multiple of 4, which is 4 for an empty keyring. `IncludeBagInFreeSpace` now leaves the keyring out of the backpack's free space, so neither shows. Coverage: `spec/items_spec.lua` ("Free slots shown one by one": "leaves the keyring out"). **Show Bags shows only its open slots, last.** The read takes only the keyring's `GetKeyRingSize()` slots, so Show Bags no longer draws the padlocked ones, and its section comes after every bag's: keyring.md. A Camelot bank that renders blank usually means the character owns no tab yet (the Purchase Bank button, §10, shows then). If it renders blank with tabs that *do* have slots, look at the read after the tab arrived (there is no bank read on `BANK_TABS_CHANGED`), **not** at a missing base-bank container. Do not re-add -1. ## 8. PLAYER_MONEY crash while looting away from the bank (directly UnregisterEvent BankPanel.MoneyDisplay) Symptom: on Camelot, a gold change out in the world (looting coin) throws `Blizzard_UIPanels_Game/Camelot/BankFrame.lua:43: bad argument #1 to 'FetchNumPurchasedBankTabs' (bankType nil)`. It requires having visited the bank at least once in the session, and does not happen with the addon disabled. Root cause (a latent Blizzard bug that BetterBags's frame handling triggers), traced end to end: - `BankPanel.MoneyDisplay` (`BankBagCostMoneyDisplayMixin`, the "cost of the next bank tab" money frame) registers `PLAYER_MONEY` in its `OnShow` / unregisters in `OnHide` (`Camelot/BankFrame.lua`). Its `OnEvent` on `PLAYER_MONEY` calls `Refresh()`, which fires `EventRegistry:TriggerEvent("BankPanelMixin.ShowOrHideBagCost")`. The handler `BankFrameMixin:OnShowOrHideBagCost` calls `C_Bank.FetchNumPurchasedBankTabs(self:GetActiveBankType())` with **no nil check**. - The two `GetActiveBankType`s are asymmetric (`Mainline/BankFrameTemplates.lua`): `BankPanelMixin:GetActiveBankType()` returns `self.bankType` (raw), but `BankFrameBaseMixin:GetActiveBankType()` returns `self.BankPanel:IsShown() and self.BankPanel:GetActiveBankType() or nil` — **gated on `BankPanel:IsShown()`**. `MoneyDisplay:Refresh`'s guard reads the raw (BankPanel) one; the crashing handler reads the IsShown-gated (BankFrame) one. - `IsShown()` is the frame's own flag; `IsVisible()` is effective (self **and** all parents shown) — verified from `warcraft.wiki.gg` (`ScriptRegion:IsVisible`; their example: reparent a shown frame under a hidden one ⇒ `IsShown()==true, IsVisible()==false`). `OnShow`/`OnHide` track **effective visibility**, with one exception: `OnShow` for an XML frame "fires after OnLoad **unless hidden at the time**" (its own hidden state, not the parent chain). And critically, **event registration is independent of shown state** — a registered frame keeps receiving events while hidden, and calling `Hide()` on a frame that is not `IsVisible` produces no visible→hidden transition, so its `OnHide` does **not** fire. - So `MoneyDisplay` registers `PLAYER_MONEY` at **login** (own flag shown, no `hidden` attr), regardless of the parent bank being hidden. BetterBags then reparents `BankFrame` under the permanently-hidden `sneakyFrame` (`core/init.lua` `HideBlizzardBags`, gated on `database:GetEnableBankBag()`). Because `MoneyDisplay` is never *effectively visible*, its `OnHide` never fires, and it stays registered forever. **`Hide()` cannot fix this** — verified live in the broken state: `MoneyDisplay:IsEventRegistered("PLAYER_MONEY")==true` while `IsShown()==false`. (My earlier "close cascade unregisters it" and the two `Hide()`-based attempts — at bank `OnShow` and at close — were all wrong for this reason; the `OnShow` one also fought Blizzard re-`Show()`ing it mid-session.) - After any bank visit, `BankPanel.bankType` is left non-nil (`bags/bank.lua` `SwitchToBankAndWipe` → `SetBankType(Character)`), and `addon.CloseBank` sets `BankPanel:IsShown()` false via `BankPanel:Hide()` (`core/hooks.lua`). Looting then: `PLAYER_MONEY` → `MoneyDisplay:OnEvent` → `Refresh` guard passes (raw bankType non-nil) → handler reads `BankPanel:IsShown()`(false) → nil → crash. (No crash *before* a bank visit — `bankType` is nil, so `Refresh`'s guard bails.) Fix: **`UnregisterEvent("PLAYER_MONEY")` on `MoneyDisplay` directly** — not `Hide()`, which cannot unregister it. Done in two taint-safe places: - `bags/bank.lua` `bank:SuppressBlizzardBankPanel()` — the consolidated BankPanel-suppression helper (previously duplicated inline in the fade + direct `bank.proto:OnShow` paths) that also hides `MoneyFrame`/`AutoDepositFrame`/`Header`. So it's killed the moment BetterBags takes over the bank. - `core/hooks.lua` `addon.CloseBank` — alongside the existing `BankPanel:Hide()`, in the `BANKFRAME_CLOSED` event-handler context (sanctioned by patterns-taint.md). Nothing re-registers it (its `OnShow` can never fire while it is not `IsVisible` under the `sneakyFrame`). Must **not** be done at init — touching `BankPanel`/children during `HideBlizzardBags` taints `BankPanel` and breaks `UseContainerItem()` for all containers (see the `core/init.lua` warning). Nil-guarded, so live retail (no `MoneyDisplay`) is unaffected. Coverage: `spec/core/close_bank_spec.lua` and `spec/bags/bank_panel_suppress_spec.lua`. ## 9. Bank tabs are bag sockets — the "Show Bags" tab button is where the bag goes On Camelot a purchased character bank tab is not a ready container: it is a **bag socket**, and the tab only has slots once a bag is placed in it. Source of truth is Blizzard's own socket button, `BankItemButtonBagMixin` (`Blizzard_UIPanels_Game/Camelot/BankFrame.lua`): - Sockets are addressed as `(Enum.BagIndex.Characterbanktab = -2, socketIndex)`; socket `N` backs tab bag id `CharacterBankTab_1 + N - 1` (`GetExactBankTabSlot`). Blizzard's bag buttons start at socket **2**: tab 1 is the free, fixed-size (48 slots), bagless base bank. - One call does everything: `C_Container.PickupContainerItem(Characterbanktab, N)` picks the bag up, places the cursor bag, or swaps them (bound to click, `OnDragStart`, and `OnReceiveDrag`). - Tooltip: `GameTooltip:SetBagItem(-2, N)` gives the bag's name, size and type. It returns false (and hides the tooltip) for an empty socket (`TooltipDataHandler.lua`). - Refresh events: `PLAYERBANKSLOTS_CHANGED` and `BAG_CONTAINER_UPDATE`. BetterBags Next's bank (next.md §6) shows the same sockets in its Bank Tabs mode, through the module's `BankSlots:GetBagSocketIndex(bankType, bagIndex)` and `BankSlots:PickupBag(bankType, bagIndex)`, which the panel's buttons also call (`GetBagSocketIndex`/`PickupBag` on a button delegate to them): its tab is draggable and takes drops, and its icon is the socketed bag's (or an empty bag slot). Rather than add a second row of bag buttons, BetterBags makes the existing tab button in the bank "Show Bags" strip (`frames/bankslots.lua`) the socket too, because on Camelot each socket is exactly one tab: - `bankSlotButtonProto:GetBagSocketIndex()` — the socket behind a tab, or nil (not Forever, an account tab, or the base tab). `PickupBag()` refuses in combat with the same "Cannot change bags in combat." message the backpack bag buttons use, then calls `PickupContainerItem`. - Clicks: dropping a bag on the tab, or left-clicking while holding an item, places it (swapping out any bag already there); dragging the tab or shift-left-click (`IsModifiedClick("PICKUPITEM")`) picks the bag up; a plain left-click still selects the tab and right-click still opens its settings (name, icon). Drag is only registered on Forever, so live retail tabs are unchanged. - Face: the tab's custom icon stays; a 16px corner badge (`btn.bagBadge`) shows the socketed bag's icon (`C_Item.GetItemIcon` on the socket `ItemLocation`), or the empty-bag-slot art with the tab icon desaturated when the socket is empty. - Tooltip: the bag's own tooltip leads, followed by the tab name, "N of M slots free" and the drag/drop hints. An empty socket reads "No bag in this slot / Drop a bag here to use this tab". The base tab shows its free slots and no bag hints. - The panel redraws on `PLAYERBANKSLOTS_CHANGED` and `BAG_CONTAINER_UPDATE` (Forever only), and `data/refresh.lua` sweeps every bank bag on `PLAYERBANKSLOTS_CHANGED` on Forever (`{ bank = true }`). It must **not** reuse the Classic handler's `bags = { [-1] = true }`: bag -1 is the keyring on Forever (§7). - Gated on `addon.isForever`: the socket model belongs to the Camelot client (Blizzard creates its bag buttons unconditionally there), and no live-retail API expresses it. Coverage: `spec/frames/bankslots_spec.lua` ("Forever bank tabs are bag sockets": socket mapping, live-retail no-op, drop/drag/click/shift-click, base tab, combat refusal, badge, tooltips, redraw events) and `spec/refresh_spec.lua` ("sweep every bank bag on PLAYERBANKSLOTS_CHANGED on Forever", "not listen … on live retail"). ## 10. The free first bank tab: a Purchase Bank button, because it cannot be bought for you On Forever a new character owns no character bank tab. Blizzard's own bank window buys the free first one when it opens: `BankFrameBaseMixin:OnShow` → `SelectDefaultTab` → `SetTab`, which on Camelot calls `BankFrameMixin:PurchaseFirstSlot`, and that calls `C_Bank.PurchaseBankTab(Enum.BankType.Character)` when `FetchNextPurchasableBankTabData` reports `tabCost == 0` (`Blizzard_UIPanels_Game/Camelot/BankFrame.lua`, `Mainline/BankFrameTemplates.lua`). Live retail has no such code. BetterBags breaks that chain on purpose: `HideBlizzardBags` (`core/init.lua`) reparents `BankFrame` under the hidden `BetterBagsSneakyFrame` and clears its `OnShow`, so the open never runs Blizzard's handler and the tab is never bought. The bank opened empty, and the only way in was the "+" on the first tab in the Show Bags panel. **It cannot be bought from BetterBags code.** `C_Bank.PurchaseBankTab` is protected (`HasRestrictions = true` in `BankDocumentation.lua` on Forever and live; addon calls fail with `ADDON_ACTION_FORBIDDEN`, e.g. ArkInventory issue #2003), and calling `BankFrame:PurchaseFirstSlot()` from addon code is the same call. Restoring Blizzard's `OnShow` would make the whole Blizzard bank window run beside ours, with our `BankPanel` calls firing its show/hide handlers from addon code, which is the `BankPanel` taint that breaks `UseContainerItem` (`core/init.lua`). The user has to click. **The button** (`bags/bank.lua`): - `OnCreate` creates `bag.purchaseBankButton`, a `"BankPanelPurchaseButtonScriptTemplate, UIPanelButtonTemplate"` button (the same pair Blizzard's own purchase prompt button inherits) reading "Purchase Bank", with `overrideBankType = Enum.BankType.Character`, centered on the bag's `scrollBox` and 10 levels above it, hidden. The template's own `OnClick` opens Blizzard's `CONFIRM_BUY_BANK_TAB` dialog, whose accept buys the tab: the same secure path as the bank tab slots panel's purchase buttons (`frames/bankslots.lua`). **Never set or hook its `OnClick`.** - `bank.proto:NeedsBankPurchase()` is true when the shown bank type is the character bank (the bag's `bankTab` is not in `const.ACCOUNT_BANK_BAGS`), `C_Bank.FetchNumPurchasedBankTabs(Character)` is 0 and `C_Bank.FetchNextPurchasableBankTabData(Character)` is not nil. It is a `Bank` prototype method, so a profiler trace records each answer. - `bank.proto:UpdatePurchaseBankButton()` shows or hides the button from it. It runs from `SwitchToGroup` (every bank open goes through it), `SwitchToBlizzardTab` (the Show Bags tabs) and `BANK_TABS_CHANGED` (the purchase landing). - Gated on the data, not on `addon.isForever`: a live-retail character with no character tab gets the same button over the character bank, and never over a Warbank group or tab. Not verified by a capture yet: which events read the new tab's slots into the bank after the purchase. The button adds no read; the bank refreshes the way it did after a purchase from the Show Bags panel. Coverage: `spec/bags/bank_purchase_button_spec.lua` (template, attribute, no `OnClick` of ours, placement; shown with no tab, hidden with a tab, with nothing purchasable, after `BANK_TABS_CHANGED`, over the Warbank by group and by Show Bags tab; shown on Forever). Each guard was mutation-tested. ## 11. What the launch build changed in Blizzard's container item buttons (1.60.1.70790) Two changes broke BetterBags at login on launch day, one after the other (§11a, §11b), and a third threw a theme's icon crop away on every draw (§11c); all are fixed for Forever only (asked: "make sure this only runs on forever"). Checked for more: every template BetterBags names exists on 70790 except the one in §11b, and no Blizzard function BetterBags calls was removed between 70532 and 70790. §11d lists what the review found from source and nobody has seen. ### 11a. `Initialize` takes the container The launch build changed Blizzard's item button setup. Forever 70532 (2026-10-22) and live retail 12.1.5 have `ContainerFrameItemButtonMixin:Initialize(bag, slot)`; Forever 70790 has `Initialize(containerFrame, bag, slot)` (`Blizzard_UIPanels_Game/Mainline/ContainerFrame.lua`), which keeps `self.containerFrame`, and Blizzard's own callers became `AcquireNewItemButton():Initialize(self, bagID, slotID)`. With it came `IsCombined()`, which asks `self.containerFrame:IsCombinedBagContainer()`, and Forever's empty slots follow it: `Camelot/ContainerFrame.lua` overrides `ShouldUseBagIconForEmptySlot` to return `IsCombined()`, which `GetItemButtonBackgroundTexture` asks whenever a button's texture is set to none. The old `Initialize`'s combined-bags background is gone. - **Failure mode (fixed, reported on launch day):** `ContainerFrame.lua:1861: bad argument #1 to 'SetID' (Usage: self:SetID(id))`, from `itemFrame:GetButton` in `itemFrame:OnEnable` at login. BetterBags called `Initialize(bagID, slotID)`: the bag went into `containerFrame`, the slot into `bag`, and `SetID` got nil, on the first backpack slot, so no item button was made. - **The fix** (`initializeSlotButton`, `frames/item.lua`): Blizzard's `Initialize` still runs, for the clickable button and the decoration (asked: letting Blizzard's code run, which is sensitive to taint, rather than doing its work ourselves). On Forever (`addon.isForever`) it is handed the slot's holder (`item.frame`), the buttons' parent, as the container: the holder already answers `IsCombinedBagContainer` false and `GetID` with the bag, the two things live retail's `Initialize` asked its parent. Everywhere else it gets `(bag, slot)`, and Classic's buttons, which have no `Initialize`, get `SetID` and `bagID`. - **Forever only, as asked.** PTR 12.1.7 (70740) already has the same `Initialize(containerFrame, bag, slot)`, so live retail will need the same call once 12.1.7 ships; that client is not handled yet. - **The mock** (`spec/helpers/wow_mocks.lua`): `__mockContainerItemButtons("forever")` gives item buttons 70790's `Initialize`, `IsCombined`, Forever's `ShouldUseBagIconForEmptySlot` and `GetItemButtonBackgroundTexture`; `"live"` (the default) puts 12.1.5's back. The whole-addon helper's Forever client uses it (`spec/helpers/whole_addon.lua`). The mock's `SetID` now raises the client's error for a missing id (`SimpleFrameAPIDocumentation`: `id` is a number, not nilable), which it took silently before. Coverage: `spec/frames/item_spec.lua` ("setting up a slot's buttons (Blizzard's Initialize)": every slot's buttons at login on Forever, the holder as both buttons' container and not combined, no container on live retail), and on the whole addon every Forever start (`spec/integration/bag_switch_spec.lua`, `spec/integration/empty_slot_spec.lua`), which failed with the reported error before the fix. Mutation-tested (3 mutations: no container on Forever, the holder on retail, the Forever check dropped; each caught). ### 11b. No `ItemSlotBackgroundCombinedBagsTemplate` 70790 removed the texture template `ItemSlotBackgroundCombinedBagsTemplate` (`Interface\ContainerFrame\UI-Bag-Components` cropped to 0.64453125, 0.7890625, 0.42578125, 0.498046875) from `Mainline/ContainerFrame.xml`, and the template's `emptyBackgroundAtlas` key from `ContainerFrameItemButtonTemplate`. Its own empty container slots now draw the `bags-item-slot64` atlas (`ContainerFrameItemButtonMixin:GetItemButtonBackgroundTexture`; its bank slots too, `BankFrameTemplates.xml`), and nothing in its UI names `UI-Bag-Components` any more. - **Failure mode (fixed, reported on launch day, right after §11a's fix):** `BetterBagsItemButton50Decoration:CreateTexture(): Couldn't find inherited node "ItemSlotBackgroundCombinedBagsTemplate"`, from `itemFrame:CreateDecoration` at login. The Show Bags panel's bag buttons (`BagButtonFrame:_DoCreate`) made the same texture. - **The fix:** on Forever the decoration's and the bag button's `ItemSlotBackground` is a plain texture (BACKGROUND, -6, hidden, as the template made it) drawing `bags-item-slot64`; retail keeps the template. BetterBags Next's guild bank slots (`next/guildbutton.lua`), which draw the old file themselves and so raised nothing, draw the atlas on Forever too, so an empty slot looks the same in the bags and the guild bank (CLAUDE.md, "UI Consistency"). A theme's `EmptySlot` style (sonata.md §3a) restyles the texture and puts the atlas back when it leaves. - **The mock:** `__mockContainerItemButtons("forever")` also makes `CreateTexture` raise the client's error for that template (`missingTextureTemplates`). - **Not seen in game:** how `bags-item-slot64` looks behind BetterBags' empty slots and under a theme's empty slot art. Coverage: `spec/frames/item_spec.lua` (the decoration's background on live and on Forever), `spec/frames/bagbutton_spec.lua` ("its empty slot background"), `spec/next/guildbutton_spec.lua` ("Forever's empty slot atlas on WoW: Forever"), and the whole-addon Forever starts. Mutation-tested (3 mutations, one per file: each caught, the decoration's and the bag button's by the whole-addon starts too). ### 11c. `SetItemButtonTexture` resets the icon's crop Found by the bug review of §11a-b, from source. 70790's `SetItemButtonTexture_Base` (`Blizzard_ItemButton/Mainline/ ItemButtonTemplate.lua`, which `ItemButtonMixin:SetItemButtonTexture` calls) now ends every draw with `icon:SetTexCoord(0, 1, 0, 1)` (or `SetAtlas` with `resetTexCoords`); live 12.1.5 and Forever 70532 leave the coordinates as they were. Sonata sets a theme's icon crop (`Icon.TexCoords`, sonata.md §3a) only when it styles a button, so on Forever the first full draw threw it away: the classic ElvUI theme (no Masque, nothing put it back) and the Next themes that crop their icons, wherever Masque does not skin the buttons; guild bank buttons the same. - **The fix:** `SonataElements:DrawItemIcon(decoration)` puts back the crop the decoration's style gave its icon (nothing for a decoration no style drew). On Forever it runs right after every icon draw: the item buttons' five (`setIcon`, `frames/item.lua`: an item's icon, a free slot's on both clients, a reset's) and the guild bank buttons' item icon (`next/guildbutton.lua`). Masque still re-skins after it (`item/Updated`, `guild/Updated`), so its crop wins where it skins. - **Not on live retail** (asked: Forever only), though PTR 12.1.7 has the same reset. Coverage: `spec/sonata/elements_spec.lua` ("an icon's crop after a draw (DrawItemIcon)"), `spec/frames/item_spec.lua` ("drawing an icon (Blizzard's SetItemButtonTexture)": every draw followed by the crop on Forever, none on live), `spec/next/guildbutton_spec.lua` (the guild icon both ways). Mutation-tested (3 mutations, each caught). ### 11d. Reported by the review, not built for (from source only, not seen in a client) - **Gamepad interface style:** with `InputUtil.IsGamepadUIEnabled()`, 70790's `ContainerFrameItemButtonMixin:OnLoad` gives every container button normal, pushed, disabled and highlight atlases (`ItemSlotFrame_*`). BetterBags clears the normal and pushed art only, so the disabled art may show on a free-space button with no count and the highlight over BetterBags' own. - **An icon mask:** 70790 masks every `ItemButton`'s icon, normal and pushed textures with `common-iconmask` (`Shared/ItemButtonTemplate.xml`, `PostOnLoad`); its shape is not in the source. It may clip an inset or cropped icon's corners, or a Masque skin's. ## 12. Still pending (not yet done) - `C_Bank.ShouldUsePlayerBagsInBank`, `FetchMaxNumBankTabs` and `BankBagTypeAndIDToInvSlot` (Camelot-only) are still unused; the socket feature (§9) works from the `Characterbanktab` container addressing and needs none of them. - Hovering a socket tab does not yet highlight that bag's items in the bank grid (Blizzard's `ToggleButtonGlowForItemsOfBankBag`).