# 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 `GameEvent`s 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):

```csharp
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.