acdream/docs/research/2026-08-08-slice5-vendor-browse-research.md

Slice 5 research — vendor browse lifecycle

Date: 2026-08-08 Scope: Slice 5 of docs/plans/2026-07-23-world-interaction-completion.md — "Vendor use opens the authored vendor surface, publishes its inventory, and supports retail selection/browsing." Buy/sell transactions, quantities, and authoritative reconciliation are Slice 6 and explicitly fenced out below (Section D).

Verified starting point: repo HEAD at research time was fa0c053e ("docs(physics): #347 closed WITHOUT a code change..."), which is at/after the required fa0c053e gate. This document makes no code changes; it is a research foundation only.

Reference hierarchy used (per CLAUDE.md): named-retail decomp (docs/research/named-retail/acclient_2013_pseudo_c.txt + symbols.json) is the top oracle for client behavior. ACE (references/ACE/) is authoritative for what the server sends/validates. holtburger (references/holtburger/) is authoritative for what a real client actually sends and how a full client models the state. Chorizite.ACProtocol (references/Chorizite.ACProtocol/) is a clean-room field-order cross-check. Where two sources could plausibly disagree, this document says which one the project's hierarchy prefers — in every case investigated here they agreed byte-for-byte.

---

A. The wire (browse only)

A.1 — What the client sends to open a vendor

There is no vendor-specific open message. Opening a vendor rides the ordinary GameAction 0x36 — UseItem (Use) action — the exact same opcode already used for every other "double-click to use" interaction (containers, doors, levers, Slice 4's equipped-child picking, etc.).

• ACE: GameActionType.Use = 0x0036 — references/ACE/Source/ACE.Server/Network/GameAction/GameActionType.cs:28. Handler: GameActionUseItem.Handle → session.Player.HandleActionUseItem(itemGuid) — references/ACE/Source/ACE.Server/Network/GameAction/Actions/GameActionUseItem.cs:5-16. HandleActionUseItem resolves the guid, optionally walks the player to it, then calls TryUseItem(item) → references/ACE/Source/ACE.Server/WorldObjects/Player_Use.cs:176-241. TryUseItem calls item.OnActivate(this), which (for a Vendor, whose ActivationResponse includes Use) dispatches virtually to Vendor.ActOnUse — references/ACE/Source/ACE.Server/WorldObjects/Vendor.cs:229-266.
• holtburger: AppAction::OpenShop { vendor } → result.commands.push(ClientCommand::Use(vendor)) — references/holtburger/apps/holtburger-cli/src/pages/game/domains/trade_vendor.rs:40-49. Confirms a real client also just sends the ordinary Use command; there is no ClientCommand::OpenVendor.
• acdream already sends this opcode today: InteractRequests.UseOpcode = 0x0036 — src/AcDream.Core.Net/Messages/InteractRequests.cs:29. No new outbound message is needed for Slice 5.
• The retail client's own use-classification policy already special-cases vendors: PublicWeenieFlags.Vendor = 0x00000200 (retail PublicWeenieDesc::BitfieldIndex, acclient.h:6431, verified at binary 0x005884B6/0x00588752) — src/AcDream.Core/Items/ItemInteractionPolicy.cs:21. A vendor NPC's Useability marks it IsUseable, so ItemInteractionPolicy.DecideUse falls into the plain SendUse + IncrementBusy branch (src/AcDream.Core/Items/ItemInteractionPolicy.cs:267-288) — the exact same path already exercised by every other useable NPC/object.

A.2 — What the server sends back: ApproachVendor (GameEvent 0x0062)

GameEventType.ApproachVendor = 0x0062 — references/ACE/Source/ACE.Server/Network/GameEvent/GameEventType.cs:16; already declared in acdream at src/AcDream.Core.Net/Messages/GameEventType.cs:26 (currently unhandled — GameEventDispatcher will count it in UnhandledCounts until Slice 5 wires a handler).

Full field-by-field wire layout, cross-verified across three independent sources (ACE's writer, retail's VendorProfile::UnPack/ItemProfile::UnPack decompiled reader, and Chorizite's generated reader/writer) with zero disagreement:

#	Field	Type	ACE source	Retail source	Chorizite name
1	Vendor's own guid	u32	GameEventApproachVendor.cs:14	Handle_VendorInfo edi = *(u32*)eax (pc:370614)	Vendor_VendorInfo.ObjectId
2	MerchandiseItemTypes (categories the vendor buys)	u32 (ItemType)	:17	VendorProfile::UnPack item_types (pc:484940)	VendorProfile.Categories
3	MerchandiseMinValue	u32	:18	min_value (pc:484943)	VendorProfile.MinValue
4	MerchandiseMaxValue	u32	:19	max_value (pc:484946)	VendorProfile.MaxValue
5	DealMagicalItems	u32 (0/1)	:21 Convert.ToUInt32	magic (pc:484949)	VendorProfile.DealsMagic (bool)
6	BuyPrice (rate applied when the vendor buys from the player — i.e. what the player receives when selling)	float	:23	buy_price (pc:484952)	VendorProfile.BuyPrice
7	SellPrice (rate applied when the vendor sells to the player — i.e. what the player pays when buying)	float	:24	sell_price (pc:484955)	VendorProfile.SellPrice
8	Alternate-currency wcid (AlternateCurrency ?? 0)	u32 (dat id)	:27	trade_id.id (pc:484960)	VendorProfile.CurrencyId
9	Player's current holding of that currency + amount just spent (0 if pyreal vendor)	u32	:37,44	trade_num (pc:484961)	VendorProfile.CurrencyAmount
10	Alt-currency plural name (empty string if pyreal vendor)	String16L	:40,45	trade_name (PStringBase<char>::UnPack, pc:484963)	VendorProfile.CurrencyName
11	Item count	u32 (vendor.DefaultItemsForSale.Count + UniqueItemsForSale.Count)	:50	PackableList<ItemProfile>::UnPack count prefix (pc:370625)	Vendor_VendorInfo.Items (list length prefix)
12..N	Per-item entries (see below)	—	:52-61	—	List<ItemProfile>

Field-name naming trap (worth flagging loudly for the contract): retail's client-side VendorProfile::VendorSellPrice(profile, pwd, stack) computes what you pay to buy an item — it uses the sell_price field (field 7 above), i.e. "the price at which the vendor is selling." ACE's server-side Vendor.GetSellCost (Vendor.cs:577-585) is the same computation and uses SellPrice (same field). Conversely VendorBuyPrice/GetBuyCost (what the vendor pays when you sell to it) uses buy_price/BuyPrice. The names read backwards from an English-first intuition ("BuyPrice" sounds like "price I pay to buy," but it's actually "price the vendor pays when buying from you"). Any pricing helper in acdream should carry an explicit doc comment quoting this inversion.

Per-item encoding — confirmed to be the full CreateObject-style weenie description, not a compact profile. Retail's ItemProfile::UnPack (pc:484668-484742, symbol 0x005D1910):

1. Packed u32: low 24 bits = stack size (sign-extended; 0xFFFFFF ⇒ -1 ⇒ unlimited supply), high 8 bits = pwdType (-1 = new PublicWeenieDesc, 1 = legacy OldPublicWeenieDesc, always -1 in practice). Matches ACE's writer exactly: Writer.Write(stackSize & 0xFFFFFF | -1 << 24) — GameEventApproachVendor.cs:58.
2. u32 item guid (iid) — read before the desc body, i.e. it is a distinct field from whatever the desc-body parser reads.
3. The desc body itself: pwd->vtable->UnPack(arg2, arg3) — this is the same PublicWeenieDesc unpack used by ordinary CreateObject, minus model/physics data. ACE confirms: obj.SerializeGameDataOnly(writer) → SerializeCreateObject(writer, gamedataonly: true, ...) — references/ACE/Source/ACE.Server/WorldObjects/WorldObject_Networking.cs:39-58. SerializeCreateObject writes Guid first (matching step 2 above, since gamedataonly still writes the guid, just skips SerializeModelData + SerializePhysicsData), then the weenieFlags/name/wcid/icon/itemType/ objDescriptionFlags fixed prefix and the same conditional tail fields (PluralName, ItemsCapacity, Value, Useability, StackSize, WielderId, ValidSlots, etc.) that every CreateObject carries. Chorizite's PublicWeenieDesc.generated.cs (Read/Write, lines 226-480) is the exact field-by-field cross-check and matches WorldObject_Networking.cs:56-130 bit-for-bit.
4. Retail's gmVendorUI::OpenVendor (pc:203650, 0x004C4BA0) then materializes each list item as a full CWeenieObject via CFactory::MakeCWeenieObject and registers it in ClientObjMaintSystem/CObjectMaint — the same object table every other spawned entity lives in (pc:203720-203748). Vendor items are not a separate lightweight vendor-item record in retail; they are ordinary client objects with no spatial presence. Recommendation: acdream's ClientObjectTable should host vendor items the same way (see C.2/C.5).

decode_vendor_item_supply in holtburger confirms the sign-extension handling for the packed stack-size field independently: references/holtburger/crates/holtburger-world/src/hydration.rs:33-40 ((packed << 8) as i32 >> 8, negative ⇒ unlimited), with tests at hydration.rs:320-330.

A.3 — How browsing stays current; what closes it server-side

The list is a full snapshot, not incrementally updated. Each ApproachVendor is a complete replace (whole VendorProfile + whole item list); there is no delta/patch opcode for vendor contents in ACE or the retail decomp. A fresh ApproachVendor arrives on: initial open (Vendor.ActOnUse → ApproachVendor(player, VendorType.Open), Vendor.cs:246-266), after a successful buy (FinalizeBuyTransaction → vendor.ApproachVendor(this, VendorType.Buy, ...), Player_Commerce.cs:112), and after a successful sell (ProcessItemsForPurchase → ApproachVendor(player, VendorType.Sell), Vendor.cs:661). All three are Slice 6 triggers (buy/sell); Slice 5 only needs to handle the initial-open case, but the parser/state owner should be built expecting replace semantics (mirroring how ExternalContainerState/ViewContents already model "authoritative full replace," see C.2).

Server-side close is polling, not a push. Vendor.CheckClose runs every closeInterval = 1.5f seconds (references/ACE/Source/ACE.Server/WorldObjects/Vendor.cs:322-367) and, if the last-interacting player has moved beyond UseRadius, calls EmoteManager.DoVendorEmote(VendorType.Close, ...) — this is a cosmetic emote broadcast (goodbye animation/chat text via EmoteManager.DoVendorEmote → references/ACE/Source/ACE.Server/WorldObjects/Managers/EmoteManager.cs:1763-1770), not a distinct wire opcode that tells the client to close its panel. There is no server→client "vendor closed" GameEvent.

Retail's own client independently tracks distance and closes locally: on open, gmVendorUI::OpenVendor registers a range watcher — CPlayerSystem::RegisterObjectRangeHandler(..., eax->id, eax->pwd._useRadius, ...) (pc:203677, 0x004C4C34) — and gmVendorUI::OnObjectRangeExit (pc:199486, 0x004C02F0) calls gmVendorUI::CloseVendor when that handler fires. gmVendorUI::CloseVendor (pc:202080, 0x004C3020) clears the buy/sell/items sub-UI, calls CPlayerSystem::UnregisterObjectRangeHandler, and resets shop state. This confirms the client, not the server, owns the close decision — retail's client independently watches distance client-side (belt-and-suspenders with ACE's server-side emote, which is purely cosmetic).

Also: reopening the same vendor id while already open does not tear down the sub-UIs — gmVendorUI::OpenVendor only calls CloseVendor(true) (same-vendor flag) when shopVendorID was already set and matches, which skips the sub-UI clear (pc:203664-203668). Reopening a different vendor while one is open closes the old one first. This matters for the reset lifecycle contract (C.2): "reset on any new ApproachVendor for a different guid; refresh-in-place on a same-guid ApproachVendor."

A.4 — What the client sends when the panel closes

Nothing. Closing the vendor panel is entirely client-local UI state with no outbound wire message. Confirmed in two independent places:

• holtburger: AppAction::ClearVendor => { state.view.vendor = None; } — references/holtburger/apps/holtburger-cli/src/pages/game/domains/trade_vendor.rs:95-98. No command is pushed to the outbound queue.
• ACE has no HandleAction*CloseVendor* handler anywhere in references/ACE/Source/ACE.Server/WorldObjects/ (only HandleActionBuyItem/HandleActionSellItem exist — Player_Commerce.cs:22, 126).
• Retail's gmVendorUI::CloseVendor (pc:202080) is a pure UI-teardown function; it does not build or send a message.

There is one indirect trigger: holtburger clears the vendor view when a trade (player-to-player) starts (ClientViewEvent::TradeStateUpdated, trade_vendor.rs:134-137), which is a local UX choice (only one modal commerce surface at a time), not a protocol requirement.

---

B. Retail client mechanism (named-retail decomp)

685 lines in acclient_2013_pseudo_c.txt reference "Vendor." The full symbol family (docs/research/named-retail/symbols.json), with addresses:

Symbol	Address	Role
ClientUISystem::Handle_VendorInfo	0x00565D10	Entry point for the inbound ApproachVendor message; unpacks VendorProfile + item list, then fans out via CM_Vendor::SendNotice_OpenVendor
VendorProfile::UnPack / ::VendorProfile	0x005D1D20 / 0x005D1BE0	Wire unpack for the profile header (field table above)
ItemProfile::UnPack / ::Pack	0x005D1910 / 0x005D1890	Wire unpack for each shop item
VendorProfile::VendorSellPrice / ::VendorBuyPrice	0x005D1B00 / 0x005D1B70	Client-local price computation (see B.1)
VendorProfile::InqAcceptability / ::IsAcceptable	0x005D1A90 / 0x005D1B50	Sell-eligibility filter (item type/value/magic) — Slice 6 territory but touches the browse UI (see D)
ShopSystem::BuyPrice / ::SellPrice	0x006B6120 / 0x006B6180	The actual rounding formula (see B.1)
gmVendorUI::Create	0x004C26A0	Panel factory (LayoutDesc-driven UIElement construction)
gmVendorUI::OpenVendor	0x004C4BA0	Panel-level open handler — receives the already-unpacked profile+list
gmVendorUI::CloseVendor	0x004C3020	Panel-level close/reset
gmVendorUI::ResetShopState	0x004C26D0	Full shop-state reset (buy list, sell list, filters)
gmVendorUI::OpenTab	0x004C0390	Switches the Buy/Sell tab
gmVendorUI::OnObjectRangeExit	0x004C02F0	Client-side distance-close trigger (see A.3)
VendorItemsUI::OpenVendor / ::UpdateItemsList / ::UpdateItemsUI / ::AddTypeFilter / ::ListContainsType	0x004C16D0 / 0x004C1EA0 / 0x004C38E0 / 0x004C05C0 / 0x004C0D90	The item-list sub-panel: population, category-tab filtering
VendorBuyUI::OpenVendor / ::UpdateBuyUI / ::UpdateTotalValue / ::UpdateTransactionValue	0x004C49D0 / 0x004C0E10 / 0x004C33D0 / 0x004C3150	Buy-side sub-panel (Slice 6, but shares the item list — see D)
VendorSellUI::OpenVendor / ::AddItemToSell / ::DragItemAcceptable	0x004C2FB0 / ...	Sell-side sub-panel (Slice 6)
CM_Vendor::SendNotice_OpenVendor / ::SendNotice_CloseVendor / ::SendNotice_AddItemToSell	0x0055F...-family	Internal (non-network) client notice-bus fanout from the wire handler to the UI listeners
CM_Vendor::Event_Buy / ::Event_Sell	0x006AA0F0 / 0x006AA000	Outbound buy/sell message builders (Slice 6)

B.1 — Panel open/close, list population, tabs, price display

ClientUISystem::Handle_VendorInfo (pc:370610-370649) is the routing entry point: reads the vendor guid, unpacks VendorProfile, unpacks the PackableList<ItemProfile>, then calls CM_Vendor::SendNotice_OpenVendor(vendorGuid, &profile, &itemList, mode) where mode is 2 (Open/Buy tab) or 3 (Sell tab), chosen by whether this reply correlates to the client's own tracked attemptOpenVendorID (a client-side request-correlation token, analogous to acdream's RuntimeInteractionTransactionState request tracking — see C.1). If a pending sell-item id (attemptSaleObjectID) is also armed, a second internal notice (SendNotice_AddItemToSell) fires. For Slice 5's browse scope, the practical rule is: opening a vendor via ordinary Use always yields mode 2 (Buy/browse tab), since attemptOpenVendorID is only armed by a sell-drag action (Slice 6).

gmVendorUI::OpenVendor(vendorId, profile, itemList, mode) (pc:203650-...) is the panel controller reached via that notice:

1. If a different vendor is currently open, it force-closes the old one first (CloseVendor(false)); reopening the same vendor id refreshes in place (CloseVendor(true), skipping sub-UI teardown).
2. Registers a distance watcher: CPlayerSystem::RegisterObjectRangeHandler keyed to the vendor's own UseRadius (pwd._useRadius) — this is what drives the client-local auto-close (A.3).
3. Copies the profile and item list into panel-owned storage (VendorProfile::operator=, PackableList<ItemProfile>::operator=).
4. Materializes every list item as a full CWeenieObject in ClientObjMaintSystem (already covered in A.2 point 4) — items you have never seen a CreateObject for still get a real client object, since the PublicWeenieDesc in the ItemProfile is sufficient to construct one.
5. Opens a tab by authored control id: UIElement_Panel::OpenTab(panel, 0x100000B9) for mode 2 (Buy/browse) or 0x100000BB for mode 3 (Sell) — pc:203791/203801. These are concrete DAT UI-element ids baked into the executable; they are strong candidates for the browse panel's own tab-control ids once the panel's own LayoutDesc is dat-extracted (see B.3 — the numeric neighborhood matches other already-confirmed vendor- adjacent ids like the examination window's 0x100000B5/B6/71/72).

Category/type filtering happens in VendorItemsUI — AddTypeFilter (0x004C05C0) and ListContainsType (0x004C0D90) drive the tab-per- item-type UI (weapons/armor/misc tabs seen in retail vendor windows), fed by UpdateItemsList/UpdateItemsUI (0x004C1EA0/0x004C38E0). This is squarely "supports retail selection/browsing" (in Slice 5's stated scope) but has not been read in exhaustive detail here — flagged as an open question (see bottom).

Price display is computed client-side, not sent pre-computed. Neither VendorProfile nor ItemProfile/PublicWeenieDesc carries a "displayed price" field — only the item's raw Value and the vendor's buy_price/ sell_price rates. The client computes the number shown in the list itself:

• VendorProfile::VendorSellPrice(profile, pwd, stackCount) (pc:484801-484813, 0x005D1B00) — "price to buy this from the vendor" — calls ShopSystem::SellPrice(perUnitValue, itemType, sell_price, stackCount).
• ShopSystem::SellPrice (pc:702107-702128, 0x006B6180): max(1, ceil(rate * value * stackCount - 0.1)), where rate = 1.15 if itemType == PromissoryNote else sell_price.
• ShopSystem::BuyPrice (pc:702082-702103, 0x006B6120): max(1, floor(rate * value * stackCount + 0.1)), where rate = 1.0 if PromissoryNote else buy_price.

These are byte-identical to ACE's server-side Vendor.GetSellCost/ GetBuyCost (Vendor.cs:573-599: Math.Max(1, (uint)Math.Ceiling((sellRate * value) - 0.1)) and Math.Max(1, (int)Math.Floor((buyRate * value) + 0.1))). Three-way cross-check (retail decomp, ACE server formula, and the fact that ACE's formula is what actually determines the transaction) with zero disagreement. Recommendation: port ShopSystem::BuyPrice/SellPrice as a small pure Core function (e.g. VendorPricing.SellPrice/BuyPrice) so Slice 5's item-list rows can show the retail-correct number, with the naming-inversion warning from A.2 called out in the doc comment.

B.2 — How retail reacts to the approach-vendor event; teardown

Already covered in A.3/B.1: ClientUISystem::Handle_VendorInfo is the sole routing entry (there is no separate "OpenVendor" opcode — everything comes through the one ApproachVendor/0x0062 GameEvent), it fans out via the internal CM_Vendor::SendNotice_OpenVendor notice bus to gmVendorUI::RecvNotice_OpenVendor (a listener registration, symbol present in symbols.json but not read in detail here), and gmVendorUI is the state object that owns shopVendorID, shopVendorProfile, shopItemProfileList, and the sub-UI panels. Teardown is gmVendorUI::CloseVendor (client-local, distance-triggered or different-vendor-triggered — never server-pushed).

B.3 — LayoutDesc/DAT identity

docs/research/retail-ui/UI-DATAIDS.md:229-236 explicitly states the vendor panel (along with Trade/Allegiance/Fellowship/Combat/Tooltip) is "confirmed to exist... but their per-panel sprite IDs live entirely inside their LayoutDesc records... [and] will populate this section after the first dat-extraction pass." The vendor panel's own top-level LayoutDesc id (the 0x210000xx-range analog of the examination window's 0x2100006B) has not yet been dat-extracted or recorded anywhere in the repo. Slice 5 will need to find it via the same import-and-search mechanism Slice 3 used (see C.3), not a pre-existing citation.

What is already a concrete, retail-sourced constant: the two tab control ids opened by gmVendorUI::OpenVendor — 0x100000B9 (Buy/browse tab) and 0x100000BB (Sell tab) — both baked directly into the executable at pc:203791/203801. These sit in the same numeric neighborhood as other already-confirmed vendor-adjacent/list-UI ids: AppraisalUiController's scrollbar/list ids (0x100000B5 horizontal scrollbar, 0x100000B6 item list, 0x10000071/ 0x10000072 decrement/increment buttons — docs/plans/2026-07-23-world-interaction-completion.md:286-289). This is circumstantial but suggestive: Turbine's UI designers assigned these ids in a contiguous block, so the vendor panel's root/child ids likely live nearby and should turn up quickly once LayoutImporter is pointed at a plausible client_local_English.dat LayoutDesc range (the same brute-force/known- neighbor search Slice 3 used to locate 0x2100006B/0x100005F2 — see the git history / research notes for that discovery if a more exact recipe is needed; it was not separately re-derived here since the concrete outcome [AppraisalUiController.LayoutId/RootId] is what matters as the precedent).

Precedent citation for "how Slice 3 found its layout id": AppraisalUiController (src/AcDream.App/UI/Layout/AppraisalUiController.cs:17-44) declares LayoutId = 0x2100006Bu, RootId = 0x100005F2u, and every other authored control as public const uint fields resolved by layout.FindElement(id) after LayoutImporter.Import(dats, LayoutId, RootId, ...) succeeds. The wiring site (src/AcDream.App/UI/RetailUiRuntime.cs:970-1068, MountAppraisal()) is the exact template to replicate for a MountVendor() method (see C.3).

---

C. Existing acdream seams (read-only — nothing here was modified)

C.1 — The use/interaction path a vendor-open rides on

Confirmed: vendor-open is not a new interaction path — it rides the exact same ItemInteractionController → ItemInteractionPolicy.DecideUse → SendUse → _requestUse reservation → J5.2's RuntimeInteractionTransactionState strict-use-gate path already used by Slice 4 (equipped-child picking) and every other useable object:

• src/AcDream.App/UI/ItemInteractionController.cs:877-924 (ExecuteUseActions, case ItemPolicyActionKind.SendUse) routes through _requestUse(action.ObjectId, reservation) when a requestUse delegate is supplied (it always is in production wiring), which is the J5.2 strict-use-gate reservation described in docs/research/2026-07-26-slice-j5-2-interaction-transactions.md.
• The vendor-specific hook already exists but is unwired: ItemInteractionController has a Func<uint> _activeVendorId parameter (ItemInteractionController.cs:48, 85, 120) that defaults to () => 0u and is never given a real value anywhere in the codebase (grep for activeVendorId/ActiveVendorId across src/ turns up only the declaration and the one policy consumer). ItemInteractionPolicy already uses it: if (input.ActiveVendorId != 0 && source.ContainerId == input.ActiveVendorId) return Consumed(); (ItemInteractionPolicy.cs:227-228) — i.e. "using" an item that's inside the currently-open vendor's shop (browsing/clicking a shop-list row) is swallowed as a no-op rather than sent as an ordinary Use, matching retail's UseObject short-circuit for items already inside an open shop window. This is the concrete branch point question C.1 asked about: Slice 5 needs to (a) build the vendor state owner, (b) wire its "currently open vendor guid" into activeVendorId at the ItemInteractionController construction site (currently defaulted everywhere), closing a gap that has existed since before this research.
• PublicWeenieFlags.Vendor = 0x00000200 (ItemInteractionPolicy.cs:21) is already ported and already used for the drag-to-sell branch (SellToVendor action, DecidePlacement, ItemInteractionPolicy.cs:357-363) — that's Slice 6 territory (dragging a player item onto the vendor NPC), but confirms the flag itself is already correctly decoded from PublicWeenieDesc for any vendor NPC's CreateObject.

C.2 — Where vendor session state should live (Runtime ownership)

Recommendation: a new VendorState Core class, owned as a new child of RuntimeInventoryState, following the ExternalContainerState shape.

Reasoning, grounded in the two closeout docs:

• docs/research/2026-07-26-slice-j4-2-inventory-state.md: RuntimeInventoryState (src/AcDream.Runtime/Gameplay/RuntimeInventoryState.cs) is the "single presentation-independent owner for the live external-container state, item-mana state, shortcut assignments, desired spell-component counts, and the retail one-inventory-request-at-a-time transaction gate." It borrows J3's ClientObjectTable (RuntimeInventoryState.cs:54, Objects => _entityObjects.Objects) and exposes each child as a property (ExternalContainers, ItemMana, Shortcuts, Transactions) plus a RuntimeInventoryOwnershipSnapshot used for reset/teardown convergence checks (RuntimeInventoryState.cs:6-31, 62-74) and a Dispose() that resets every child in a fixed order (137-161). A VendorState slots in exactly the same way: a new property, a new line in RuntimeInventoryOwnershipSnapshot, a new Try(...) call in Dispose(), and (per A.3's "reset on portal/reconnect" requirement) a new ResetVendor() method called from wherever ResetExternalContainer()/ ResetTransactions() are called today (session reset, portal-out, disconnect — the generation/lifecycle contract every other J4/J5 child follows).
• Shape to copy: ExternalContainerState (src/AcDream.Core/Items/ExternalContainerState.cs) is the closest existing analog — "an authoritative server-driven full-replace view keyed by a requested/current id, with a Changed event for presentation observers." A vendor session is conceptually identical: request-open (fires on the Use action), apply-open (fires on ApproachVendor matching the requested id), apply-close (client-local distance/switch trigger, A.3), reset (portal/disconnect). The main structural difference from ExternalContainerState is that a vendor session also carries a profile (rates/currency/categories) and an item list, not just a container id — so VendorState is a slightly richer sibling, not a literal subclass.
• Naming precedent: holtburger's own full-client implementation independently arrived at the exact name VendorState (references/holtburger/crates/holtburger-world/src/vendor.rs:98-108, fields: vendor_guid, items: Vec<CoreVendorItem>, buy_multiplier, sell_multiplier, merchandise_item_types, alternate_currency_wcid, alternate_currency_amount, alternate_currency_name) — a strong independent signal that this is the natural shape/name, not an acdream-specific invention.
• J5.2's RuntimeInteractionTransactionState (docs/research/2026-07-26-slice-j5-2-interaction-transactions.md) is the natural home for request correlation if Slice 5 wants to faithfully port retail's attemptOpenVendorID token (B.1) — it already owns "last ordinary or targeted-use source/target identity" and the typed Activate/Use/Pickup FIFO. For Slice 5's browse-only scope this is optional polish (the mode-2-vs-3 tab distinction only matters once sell-drag exists in Slice 6); flagged as an open question below.

C.3 — Authored-panel infrastructure (Slice 3's precedent, to replicate)

Complete, concrete template, read end-to-end:

1. Controller (src/AcDream.App/UI/Layout/AppraisalUiController.cs): implements IRetainedPanelController (src/AcDream.App/UI/IRetainedPanelController.cs — OnShown/OnHidden/ OnDescendantFocusChanged, all default no-ops; "the window manager owns visibility, focus, capture, geometry, and teardown ordering"). Declares every authored control id as a public const uint resolved later via layout.FindElement(id). Exposes a static Bind(...) factory that takes the ImportedLayout plus every Core dependency the controller needs (object table, interaction controller, selection state, etc.) and a show/close action pair, returning null if a required authored control is missing from the imported layout (defensive — the panel simply doesn't mount rather than crash).
2. Wiring site (src/AcDream.App/UI/RetailUiRuntime.cs:970-1068, MountAppraisal()):
   • LayoutImporter.Import(dats, LayoutId, RootId, resolveSprite, defaultFont, resolveFont) → ImportedLayout? (null if the LayoutDesc/root id pair isn't found in the dats — logged and bailed).
   • Any per-panel asset factories (row templates, name resolvers) loaded from the same dat lock.
   • XxxController.Bind(layout, ...dependencies..., show: () => Host.ShowWindow(WindowNames.X), close: () => CloseWindow(WindowNames.X), ...).
   • RetailWindowFrame.Mount(Host.Root, layout.Root, resolveSprite, new RetailWindowFrame.Options { WindowName, Chrome = RetailWindowChrome.Imported, Left/Top/ContentWidth/ContentHeight = root's authored geometry, AuthoredGeometryRevision = 1, Visible = false, ResizeX/Y, MinWidth/MinHeight, ConstrainDragToParent/Resize, ContentClickThrough, Controller = controller }) → RetailWindowHandle. This is what gives Slice 3's window its "independent movable/resizable retail floaty" behavior and its foreground-stacking — all owned by RetailWindowFrame/Host, not by the controller.
   • Window name registered in src/AcDream.App/UI/WindowNames.cs (e.g. public const string Examination = "examination"; at line 24) — Slice 5 needs a new WindowNames.Vendor (or similar) constant.
3. Foreground stacking / show-close semantics: Host.ShowWindow(name) / CloseWindow(name) are the only calls the controller needs; the window manager (Host) handles z-order, focus, and drag/resize bounds uniformly across every retained window. Slice 5 does not need to reinvent any of this — it needs a MountVendor() sibling to MountAppraisal().

C.4 — Inbound-message routing (where a new 0x0062 handler registers)

ACE GameEvents enter through WorldSession's decode path (GameEvents property, GameEventDispatcher, src/AcDream.Core.Net/WorldSession.cs:567) and get routed by GameEventDispatcher.Dispatch(envelope) (src/AcDream.Core.Net/Messages/GameEventDispatcher.cs:95-117) to whatever handler was registered for that GameEventType. The single central registration point for every handler is src/AcDream.Core.Net/GameEventWiring.cs — GameEventWiring.WireAll(...) (a big static method, one registrar.Register(GameEventType.X, e => { parse; apply to state; }) call per opcode, grouped by domain with comment banners // ── Chat ──, // ── Combat ──, // ── Spells ──, // ── Inventory ──, // ── Player ──).

Most recently added handler (the concrete pattern to copy): GameEventType.HouseUpdateRestrictions (0x0248) — GameEventWiring.cs:365-376, added for AP-129 (Campaign P Slice P4, 2026-07-30):

registrar.Register(GameEventType.HouseUpdateRestrictions, e =>
{
    var p = GameEvents.ParseHouseUpdateRestrictions(e.Payload.Span);
    if (p is null) return;
    items.UpdateHouseRestrictions(p.Value.SenderId, p.Value.Restrictions);
});

A new GameEventType.ApproachVendor handler follows the same shape: parse the payload with a new VendorApproach.TryParse (or similar, src/AcDream.Core.Net/Messages/), and apply it to the new VendorState owner (C.2). GameEventWiring.WireAll would need a new optional parameter (VendorState? vendor = null) matching the existing pattern used for itemMana, friends, squelch, externalContainers, etc. (GameEventWiring.cs:77-86).

C.5 — Icon/tooltip/item-row rendering reuse

SpellbookWindowController (Slice 1's spell list, src/AcDream.App/UI/Layout/SpellbookWindowController.cs) is the concrete precedent for a scrollable authored list with icons:

• UiScrollbar (src/AcDream.App/UI/UiScrollbar.cs) is a shared, panel-agnostic primitive bound to an authored control id via layout.FindElement(scrollbarId) is UiScrollbar scrollbar (SpellbookWindowController.cs:237, 246).
• Row icons come from a Func<uint, uint> resolveXxxIcon delegate injected at construction (resolveSpellIcon, resolveComponentIcon — SpellbookWindowController.cs:53-54, 89-90), used as CatalogIconTexture = _resolveSpellIcon(spellId) (SpellbookWindowController.cs:291) against a _rowStyle (SpellbookRowStyle) describing icon geometry (IconLeft/Top/ Width/Height, SpellbookWindowController.cs:299-302).
• Since retail materializes each vendor item as a full weenie object with a real PublicWeenieDesc (icon dat id included — A.2 point 4), a vendor item row can resolve its icon exactly the way the inventory panel resolves any ordinary item's icon (by the item's own IconId field, already parsed by the shared CreateObject/PublicWeenieDesc body parser — see the note in the next paragraph), not by a spell-specific resolver. This is a materially easier reuse case than the spell list, since vendor items are ordinary items once parsed.

One structural gap worth flagging as a contract decision, not just reuse: src/AcDream.Core.Net/Messages/CreateObject.cs (TryParse, line 512 onward) parses the entire WeenieHeader body inline as one large method (opcode → guid → model data → physics data → weenie-header fixed prefix at ~line 781 → weenie-header optional tail at ~line 834 onward, using the same bit flags as Chorizite's PublicWeenieDesc.generated.cs). It is not currently factored into a reusable standalone function callable from a new vendor-item parser. Since A.2 established that each ItemProfile entry uses the exact same PublicWeenieDesc body (just without the preceding model/physics data), the clean move is to extract the weenie-header-body parsing logic (~CreateObject.cs:781 to the end of TryParse) into a shared static helper both CreateObject.TryParse and the new vendor-item parser call, rather than re-deriving/duplicating ~300 lines of conditional-field parsing. This is flagged explicitly as an open question for the contract (below) since it's a nontrivial refactor decision, not a pure research finding.

---

D. Out-of-scope fence — what Slice 6 owns

Per docs/plans/2026-07-23-world-interaction-completion.md:56-57:

| 6 | Vendor transactions | server-authoritative buy/sell command and reconciliation owner |

"Vendor buy/sell transactions, quantities, pending-state ownership, and authoritative inventory reconciliation complete the loop."

Concretely, Slice 6 (not Slice 5) owns:

• Outbound buy/sell wire messages. ACE: HandleActionBuyItem (Player_Commerce.cs:22-52) / HandleActionSellItem (Player_Commerce.cs:126-226), each taking a List<ItemProfile> (quantities + guids). Retail: CM_Vendor::Event_Buy (0x006AA0F0) / ::Event_Sell (0x006AA000).
• Quantity/stack-split selection UI (VendorBuyUI/VendorSellUI sub-panels, stack-slider interaction — gmVendorUI::RecvNotice_StackSliderChanged in the symbol table).
• Drag-to-sell — dragging a player inventory item onto the vendor NPC (ItemInteractionPolicy.ItemPolicyActionKind.SellToVendor, ItemInteractionPolicy.cs:357-363, already ported but its dispatch/UI consumption is Slice 6's to wire).
• VendorProfile::InqAcceptability/IsAcceptable (sell-eligibility filtering by item type/value/magic — pc:484768-484797) — this is a judgment call flagged below, since "does my inventory show which items this vendor will buy" arguably touches Slice 5's "supports retail selection/browsing" language too.
• Currency/pyreal math validation, Vendor.GetSellCost/GetBuyCost as an authoritative transaction input (Slice 5 only needs the display computation — see B.1 — not the transaction-time application).
• Pending-sale correlation (attemptOpenVendorID/attemptSaleObjectID, the mode-2-vs-3 tab-switch nuance from B.1) — Slice 5's browse-only scope can default to always opening the Buy/browse tab and defer full request correlation to Slice 6, since the correlation token only matters once a sell-drag exists.
• ApproachVendor refreshes triggered by FinalizeBuyTransaction (Player_Commerce.cs:112) and ProcessItemsForPurchase (Vendor.cs:661) — Slice 5's parser/state owner should be built to handle repeat ApproachVendor events correctly (A.3, full-replace semantics), but the actual triggers for those repeats are Slice 6 actions.
• Authoritative inventory reconciliation after a purchase/sale lands (new items appearing in the player's pack, coins deducted/added) — this is standard InventoryPutObjInContainer/ViewContents/property-update plumbing already owned by existing Slice 4/J4.2 machinery, but triggered by Slice 6's buy/sell actions.

---

Open questions for the contract

1. Does VendorState live in AcDream.Core.Items (next to ExternalContainerState) or a new AcDream.Core.Commerce/Vendor namespace? Recommendation: AcDream.Core.Items — it's small, it directly parallels ExternalContainerState, and it avoids a near-empty new namespace for one class family. Weak preference; either is defensible.
2. Should the shared PublicWeenieDesc-body parser be extracted from CreateObject.TryParse into a standalone reusable method before Slice 5 writes the vendor-item parser, or should Slice 5 duplicate/adapt a subset first and defer the refactor? Recommendation: extract first — duplicating ~300 lines of conditional-flag parsing for the second time this project has needed it is exactly the kind of drift the project's "grep named → decompile → verify → port" discipline exists to prevent, and a parser bug fixed in one copy but not the other is a classic two-owners bug.
3. Does Slice 5 port ShopSystem::BuyPrice/SellPrice as a pure Core function now (needed to show a display price in the browse list), or is showing raw item value acceptable for a browse-only slice with actual price math deferred to Slice 6? Recommendation: port it now — it's a ~10-line pure function with a byte-verified formula (B.1), and a vendor list that shows the wrong price (or no price) is a visibly broken browse experience even before Buy is wired up.
4. Does Slice 5 wire the attemptOpenVendorID-style request-correlation token (mode 2 vs 3 tab selection), or hardcode "always open on the Buy/browse tab" and let Slice 6 add correlation when sell-drag lands? Recommendation: hardcode Buy/browse tab for Slice 5; the correlation only has externally-visible effect once a sell-initiated open exists.
5. Does "supports retail selection/browsing" (the Slice 5 charter language) include showing which of the player's own inventory items this vendor would accept (via VendorProfile::InqAcceptability), or is that squarely Slice 6 since it's meaningless without the sell action attached? Recommendation: defer to Slice 6 — InqAcceptability has no purpose without a sell UI to gate, and pulling it into Slice 5 would mean touching the sell sub-panel's territory for a browse-only slice.
6. Category/type filter tabs (VendorItemsUI::AddTypeFilter/ ListContainsType) were located but not read in full decompiled detail in this pass (time-boxed). If the Slice 5 contract wants exact retail parity for tab filtering (vs. a single flat browsable list for a first cut), a follow-up grep-and-read pass on pc: lines around 0x004C05C0/0x004C0D90 is needed before implementation.
7. The vendor panel's own top-level LayoutDesc id is not yet dat-extracted anywhere in the repo. The contract should budget time for a LayoutImporter.Import discovery pass (the same process that found 0x2100006B for the examination window) rather than assuming the id is already known. The two concrete tab-control ids (0x100000B9 Buy, 0x100000BB Sell) are known and can serve as a cross-check once a candidate root/LayoutDesc id is found (their FindElement should succeed under the correct root).
8. docs/architecture/retail-divergence-register.md row AP-110 currently lists "vendor/trade/salvage/tinkering" together as absent panels. Per the project's binding divergence-register rule, Slice 5's landing commit must narrow AP-110 to drop "vendor" from the absent list (or add a precise successor row describing what remains absent — e.g. category filter tabs if #6 above is deferred) in the same commit that lands vendor browsing.

---

§B.4 — D0 tab-filter read, 5.4 (2026-08-09)

Mandatory pre-UI read for Slice 5.4 (contract decision 6), grepping VendorItemsUI::AddTypeFilter (0x004C05C0) / ::ListContainsType (0x004C0D90) plus their caller VendorItemsUI::OpenVendor (0x004C16D0) and the whole-panel gmVendorUI::OpenVendor/PostInit/constructor (0x004C4BA0/0x004C09A0/0x004C2470). This also resolves contract decision 7 (layout-id discovery) — the two findings are entangled since the D0 read is what proves the layout structure below.

Layout identity: LayoutDesc 0x21000012, root 0x100000B7

Found via brute-force enumeration of every LayoutDesc in client_local_English.dat (dats.GetAllIdsOfType<LayoutDesc>(), 101 entries) for the one whose descendant tree contains BOTH known tab-control ids 0x100000B9 and 0x100000BB as siblings. Exactly one match. Cross-check per contract decision 7: UIElement::RegisterElementClass(0x10000017, gmVendorUI::Create) (pc:202075) — root 0x100000B7's own resolved Type is 0x10000017, the literal retail class id for gmVendorUI itself. This is not circumstantial; it is the direct proof the root element found IS gmVendorUI's own instantiated root.

Root geometry: 800x110 at design position (0,500) inside an 800x600 canvas — a compact bottom-docked strip, the same shape family as ExternalContainerController's 0x21000008/0x10000063 (not a large grid+icon browse window; AC's vendor UI is a horizontal single-row icon strip, matching general retail recollection).

Method: a throwaway scanner tool (tools/VendorLayoutScan/, not part of the shipped solution) using DatCollection.GetAllIdsOfType<LayoutDesc>() + recursive ElementDesc.Children search, then LayoutImporter.ImportInfos(dats, layoutId, rootId) (the SAME resolved inheritance pipeline production uses) to dump full resolved Type + StateDesc.Properties per element, including DatStringResolver-resolved StringInfo labels (property 0x17). This is what nailed the exact tab→page mapping below with dat-authored-label proof, not inference.

Tree shape (verified via the resolved-property dump, not just raw ElementDesc)

0x100000B7  gmVendorUI root (Type 0x10000017), 800x110 @ design (0,500)
├─ 0x100000D6  close/pushpin button (Type 1, icon-only, no label — plain X)
├─ 0x100000B8  m_vendorPanel (Type 0x8 = UIElement_Panel; PostInit binds
│              this via GetChildRecursive(this, 0x100000b8))
│  ├─ 0x100000B9  tab, label "Items"    (order 1, x=0)
│  ├─ 0x100000BA  tab, label "Buying"   (order 2, x=92)
│  ├─ 0x100000BB  tab, label "Selling"  (order 3, x=184)
│  ├─ 0x100000BC  page for tab B9 ("Items") == VendorItemsUI's content
│  │  ├─ 0x100000BD  m_shopList (Type 0x10000031 UiItemList, 710x32 —
│  │  │              cell 32x32 from base 0x2100003D/0x10000339 ⇒ ~22-slot
│  │  │              single-row horizontal strip, matches
│  │  │              ExternalContainerController's list shape)
│  │  ├─ 0x100000BE  scrollbar (Type 0xB, horizontal, 710x16)
│  │  ├─ 0x100000BF  m_itemTypeMenu (Type 0x6 = UIElement_Menu, resolves
│  │  │              to acdream's UiMenu via DatWidgetFactory's `6 =>
│  │  │              new UiMenu()` — a FULLY IMPLEMENTED dropdown widget
│  │  │              already, Items/Selected/OnSelect/ButtonLabelProvider)
│  │  ├─ 0x100000C0  m_itemNameText
│  │  ├─ 0x100000C1  m_itemCostText
│  │  ├─ 0x100000C2  m_buyButton, label "Buy"
│  │  └─ 0x100000C3  m_addButton, label "Add to List"
│  ├─ 0x100000C4  page for tab BA ("Buying") == VendorBuyUI's content
│  │  ├─ 0x100000C5  m_buyShopList (staged-to-buy list, NOT the shop's
│  │  │              full stock — see below)
│  │  ├─ 0x100000C6  scrollbar
│  │  ├─ 0x100000C7/C8  m_buyListText / m_buyPurseText
│  │  ├─ 0x100000C9  m_buyItemButton, label "Buy Item"
│  │  ├─ 0x100000CA  m_buyAllButton, label "Buy All"
│  │  └─ 0x100000CB/CC  m_buyClearItemButton "Clear Item" /
│  │                    m_buyClearListButton "Clear List"
│  └─ 0x100000CD  page for tab BB ("Selling") == VendorSellUI's content
│     ├─ 0x100000CE  m_sellShopList (staged-to-sell list)
│     ├─ 0x100000CF  scrollbar
│     ├─ 0x100000D0/D1  m_sellListText / m_sellPurseText
│     ├─ 0x100000D2  m_sellItemButton, label "Sell Item"
│     ├─ 0x100000D3  m_sellAllButton, label "Sell All"
│     └─ 0x100000D4/D5  m_sellClearItemButton / m_sellClearListButton,
│                       labels "Clear Item" / "Clear List"
└─ 0x1000008D  title/backdrop (Type 0x8, ZLevel 100 — drawn behind)

Every id above is confirmed two ways: (1) VendorItemsUI::VendorItemsUI (pc:199612)/VendorBuyUI::VendorBuyUI (pc:199717)/ VendorSellUI::VendorSellUI (pc:199753) bind these EXACT child ids via UIElement::GetChildRecursive; (2) the resolved-property dump shows the matching 0x17 StringInfo label on each button, so the id↔label pairing is read directly off the dat, not inferred from ctor ordering alone.

Tab↔page semantics — corrects the contract's 2-tab assumption

The contract (decision 4, written before this read) assumed two tabs: "browse/Buy" (0x100000B9) and "Sell" (0x100000BB). The dat actually authors three tabs, and the dat-resolved labels settle their meaning precisely — this is NOT the Buy/Sell MODE switch the contract assumed, it is Items/Buying/Selling, three independent staging views:

• "Items" (0x100000B9) — VendorItemsUI: the vendor's full stock, filterable by category, each row clickable, with Buy/Add to List buttons. This is Slice 5.4's browse view — the only page with useful content before Slice 6 exists.
• "Buying" (0x100000BA) — VendorBuyUI: review/confirm panel for gmVendorUI.m_buyList, a CLIENT-side staging list of items you've chosen to buy from the Items tab (m_buyItemButton/m_buyAllButton on the Items page add to it; this tab's own buttons commit/clear it). Empty on a fresh open (m_buyList starts empty — confirmed by gmVendorUI::OpenVendor's unconditional CloseVendor on any previous session before rebuilding). Slice 6 territory.
• "Selling" (0x100000BB) — VendorSellUI: the symmetric staging view for items dragged from your own inventory onto the vendor (ItemInteractionPolicy.ItemPolicyActionKind.SellToVendor, already ported, Slice 6 wires its UI consumption). Matches contract decision 4's "Sell tab... stays inert" almost exactly — its authored label is "Selling," not "Sell," but the semantic match is exact.

gmVendorUI::OpenVendor (pc:203650) confirms all three sub-panels (m_itemsUI, m_buyUI, m_sellUI) refresh unconditionally on every ApproachVendor (this->m_itemsUI->vtable->OpenVendor(...); m_sellUI->OpenVendor(...); m_buyUI->OpenVendor(...), pc:203852-203854), regardless of which tab ends up visually open — only the VISIBLE tab is mode-dependent (OpenTab(m_vendorPanel, 0x100000b9) for mode 2, 0x100000bb for mode 3, pc:203791/203801 — mode 2 opens tab 0x100000B9 ("Items"), confirming decision 4's "browse/Buy tab" language was describing this exact tab, just informally — its authored name is "Items," not "Buy"). Slice 5.4 therefore: mounts all three tabs (matching the authored layout and RetailTabBinding's existing tri-state pattern precedent, SpellbookWindowController's Spell/Component tabs), defaults to "Items" selected/visible, and leaves "Buying"/"Selling" as present-but-unpopulated pages (no VendorBuyUI/VendorSellUI port this slice — both are squarely Slice 6, matching the contract's "no buy/sell actions" fence). This symmetric treatment — not just the contract's originally-anticipated single "Sell" tab — gets the "comment the fence" treatment for both non-default tabs.

Category/type filter mechanism (the actual D0 answer)

VendorItemsUI::AddTypeFilter(this, label, typeMask) (pc:199667) does not create a visible tab button — it calls UIElement_Menu::InsertTextItem(m_itemTypeMenu, label, m_numTypeFilters), i.e. it inserts a row into the dropdown menu at 0x100000BF, tagging the new menu item with the type mask via a per-item property (BaseProperty::SetPropertyName(&prop, 0x10000039) then storing typeMask into it). "Category tabs" in the contract's phrasing means this dropdown, not additional tab buttons.

VendorItemsUI::OpenVendor (pc:200779-201025) rebuilds the dropdown from scratch on every open/refresh: flushes m_shopList and m_itemTypeMenu, then walks an ordered, hardcoded 18-entry table, calling ListContainsType(shopItemProfileList, mask) for each and only adding the filter (AddTypeFilter) if the vendor's stock contains a matching item. ListContainsType (pc:200132-200159) is a linear scan: true iff any shop item's InqType() & mask != 0. Table, in authored order, with the acdream ItemType composite that reproduces each literal retail mask bit for bit (verified against src/AcDream.Core/Items/ClientObject.cs:26-75 — every bit accounted for, no gaps):

#	Label	Retail mask	acdream ItemType
1	Armor	0x2	Armor
2	Books, Paper	0x2000	Writable
3	Clothing	0x4	Clothing
4	Containers	0x200	Container
5	Food	0x20	Food
6	Gems	0x800	Gem
7	Jewelry	0x8	Jewelry
8	Keys, Tools	0x20004000	TinkeringTool | Key
9	Miscellaneous	0x490	Useless | Misc | Creature
10	Services	0x100000	Service
11	Spell Components	0x1000	SpellComponents
12	Trade Notes	0x40000	PromissoryNote
13	Weapons	0x101	Weapon (existing composite)
14	Mana Stones	0x80000	ManaStone
15	Magic Items	0x8000	Caster
16	Alchemical Items	0x4800000	CraftAlchemyIntermediate | CraftAlchemyBase
17	Cooking Items	0x400000	CraftCookingBase
18	Fletching Items	0x9000000	CraftFletchingIntermediate | CraftFletchingBase

After rebuilding, retail selects an index (pc:201008-201022): the PREVIOUS selected index if it's still < newCount - 1 inclusive-clamp, otherwise clamps to newCount - 1, then floors at 0. Net effect: first open (GetSelectedIndex returns -1, nothing selected yet) always lands on index 0 — the FIRST present category in table order, not "show everything." Pseudocode:

selected = previousSelectedIndex        // -1 on first open
if (selected >= presentCount - 1) selected = presentCount - 1
if (selected < 0) selected = 0

VendorItemsUI::UpdateItemsList(this, mask, notify) (pc:201029 on) confirms the filter is load-bearing, not cosmetic: it re-walks the FULL shopItemProfileList and inserts into m_shopList only items where (activeMask & itemType) != 0, where activeMask is either the explicit mask argument (arg2 != 0) or, when arg2 == 0, the CURRENTLY selected menu item's stored 0x10000039 property. There is no "all types" state — an empty/no selection filters everything out (0 & anything == 0), which is exactly why retail always force-selects index 0 after rebuilding. Slice 5.4 ports this literally: the item list is always scoped to exactly one category; clicking a different dropdown entry re-filters via the stored mask on that entry, matching UpdateItemsList's arg2 != 0 explicit-mask branch.

Verdict: bounded, in scope, no fallback needed

The full mechanism is an 18-row static table + a linear membership test reused per row + one dropdown-population pass + a selection-index clamp — small and precedented (UiMenu is a complete pre-existing widget; SpellbookWindowController's FilterButtons array is the same "static mask table drives filterable UI" shape, just buttons instead of a dropdown). This does not trigger the "mechanism too large — STOP" clause; the flat-list fallback is not needed. The genuinely new information this read surfaced beyond the contract's decisions — three tabs instead of two, and the dropdown-vs-tab distinction for "category tabs" — is recorded above for the record, not treated as a scope escalation.