acdream/docs/superpowers/specs/2026-06-21-d2b-inventory-window-finish-design.md

# D.2b inventory window finish (Stage 1) — design / spec

**Date:** 2026-06-21
**Phase:** D.2b inventory, **Stage 1 of the "full retail inventory" arc** (Stage 2 = paperdoll, separate spec).
**Branch:** `claude/hopeful-maxwell-214a12` (follows B-Wire, tip `7c006d1`).
**Predecessor:** B-Wire (inventory wire layer) — shipped + burden gate passed.
**Status:** approved design → write plan next.

This was triggered by a side-by-side: acdream's inventory vs. a retail client (`+Je`). The gaps the
user flagged — "scroll bar, background all the way, slots for backpacks" — are the 2D window finish.
The 3D paperdoll doll is the heavier, separable Stage 2.

---

## 1. Goal / non-goals

**Goal.** Make the inventory window match retail's 2D presentation:
1. The "Contents of Backpack" grid **clips to its panel and scrolls** (today it renders every row
   unclipped, so a full pack overflows off-window — which is *also* why picked-up items "don't appear"
   and why the backdrop looks torn at the bottom).
2. The dark **backdrop covers the whole window** (no grass showing through).
3. The **side-bag selector** renders as a proper slot column (bags + empty frames), like retail.

**Non-goals (deferred):**
- **Paperdoll** (3D character doll + per-slot equip silhouettes) → **Stage 2** (needs a Core→App
  `UiViewport` render seam + `0x10000032` `UiItemSlot` registration). Research:
  `docs/research/2026-06-16-equipment-paperdoll-deep-dive.md`.
- **Drag-to-drop / drag-from-inventory** → B-Drag.
- The **side-bag column's own scrollbar** (`0x100001CB`): 7 slots fit the 252px column exactly, so
  no scroll is needed there; leave it inert.

---

## 2. Grounding (from the dat layout dumps — authoritative geometry)

Read from `.layout-dumps/inventory-0x21000023.txt`, `items3d-0x21000021.txt`, `backpack-0x21000022.txt`:

- **Outer frame `0x21000023`** (300×362): the **backdrop `0x100001D0`** is **X=0,Y=0, 300×362**
  (full window), Type 3, Alphablend sprite `0x06004D0A`, ZLevel 100. Three sub-windows mount inside:
  paperdoll `0x100001CD` (0,23 224×214), backpack `0x100001CE` (239,23 61×339), 3D-items
  `0x100001CF` (0,237 234×120).
- **3D-items `0x21000021`** (234×120): **contents grid `0x100001C6` = X=15,Y=20, 192×96** (exactly
  6 cols × 3 rows of 32px); **scrollbar `0x100001C7` = X=207,Y=20, 16×96**, Type 0 inheriting base
  layout `0x2100003E` (the scrollbar base → resolves to a Type-11 `UiScrollbar` via the inheritance
  chain), ZLevel 9 (just behind the grid's 10).
- **Backpack `0x21000022`** (61×339): main-pack cell `0x100001C9` (6,32 36×36); **side-bag column
  `0x100001CA` = X=6,Y=73, 36×252** (= 7 slots of 36px), inherits the ItemList base `0x2100003D`;
  side-bag scrollbar gutter `0x100001CB` (41,73 16×252) — unused (7 slots fit). Burden meter
  `0x100001D9` + captions `0x100001D7/D8` (already wired by B-Controller).

**Key deduction:** the backdrop is geometrically full-window, so the "torn" look is the **unclipped
grid overflowing below Y=362** (41 items / 6 cols = 7 rows × 32 = 224px, drawn from abs Y≈257 down to
≈481, far past the frame's 362 bottom). Clipping the grid (component A) removes that overflow and the
torn-bottom backdrop with it.

---

## 3. Components

### A — Contents-grid clip + scroll (the core)

**A1. `UiItemList` gains a clip+scroll capability**, backed by the existing **`UiScrollable`** model
(the same one `UiText`/the chat transcript + `UiScrollbar` use — do not invent a second scroll model).
- The list clips cell drawing to its own rect (`0x100001C6` = 192×96 = 3 visible rows). Content
  height = `ceil(count / Columns) × CellHeight`; view height = the list's `Height`.
- A scroll offset (whole rows, or pixels) shifts the cells up; cells fully outside the view are not
  drawn (scissor-clip via `UiRenderContext`, mirroring the transcript's clip).
- Mouse-wheel over the list scrolls it (reuse the wheel→`UiScrollable` path the transcript uses).
- `UiScrollable` exposes the thumb-size + position ratios the bound `UiScrollbar` reads (already its
  contract).

**A2. `InventoryController` binds the gutter scrollbar.** Resolve `0x100001C7` from the layout; it
is built by `DatWidgetFactory` as a Type-11 `UiScrollbar` (via its `0x2100003E` base). Bind it to
`_contentsGrid`'s `UiScrollable` — exactly as `ChatWindowController` binds its transcript scrollbar
(`ChatWindowController.cs:237-254`). If `0x100001C7` does not resolve to a `UiScrollbar` (inheritance
surprise), the plan's first step pins why before wiring.

**Acceptance:** with > 18 loose items the grid shows 3 rows + a working scrollbar; picked-up items are
reachable by scrolling; the grid no longer draws past the frame; the bottom backdrop is intact.

### B — Backdrop full coverage

The backdrop `0x100001D0` is already full-window (300×362). **Primary fix is A** (clipping the grid
removes the overflow that tears the bottom). After A lands, the implementer verifies at the visual
gate that the dark backing covers the whole window. **If a residual gap remains** (e.g. the Alphablend
backdrop sprite drawn at native size instead of filled to the element's 300×362 bounds, or a sub-window
region uncovered), root-cause it then — the candidate is `UiDatElement`'s Alphablend draw not
stretching/tiling to bounds. This is a **root-cause-then-fix** task gated on the post-A screenshot, not
a pre-committed code change (a render-coverage bug must be confirmed visually before fixing).

**Acceptance:** no world/grass shows through the inventory window anywhere (matches retail's solid
backing).

### C — Side-bag slot column

The side-bag column `0x100001CA` (36×252 = 7 slots) currently renders **only the actual side bags**
(via `InventoryController.Populate`'s `isBag → _containerList` branch), so a character with one bag
shows one lone cell. Retail shows the bag(s) **plus empty slot frames** filling the column.

- `InventoryController.Populate`: after adding the player's side bags to `_containerList`, **pad with
  empty `UiItemSlot`s** up to the slot count. Slot count = the column capacity (252 / cellPitch = 7),
  optionally clamped to the player's `ContainersCapacity` when known (> 0); default to the 7-slot
  column height otherwise. Empty cells draw the empty-slot art already (the toolbar empty-slot path).
- **Cell pitch = 36** for `_containerList` + `_topContainer` (match `0x100001C9`/`0x100001CA`'s 36px
  geometry), not the 32px used for the contents grid. (Today the controller sets `CellPx = 32` for all
  three — split the contents-grid pitch (32) from the backpack-column pitch (36).)

**Acceptance:** the side-bag column shows the character's bag(s) in the top slot(s) + empty frames
below, a clean column like retail's.

---

## 4. Design decisions

- **Reuse `UiScrollable`, don't fork it.** It already models content/view/offset + thumb ratios and is
  battle-tested by the chat transcript. `UiItemList` becomes a second consumer. (DRY; matches the
  widget-generalization ethos.)
- **Scroll by whole rows vs. pixels:** scroll by **pixels** (smooth), clamped so the last row aligns to
  the view bottom — matches the transcript's pixel scroll and avoids a janky row-snap. (Plan may choose
  row-snap if the dat/retail behavior says so; default pixels.)
- **Backdrop fix is gated on the post-A screenshot** (decision §B) — don't pre-change the Alphablend
  draw before confirming A didn't already fix it; avoids touching shared `UiDatElement` render for
  every window without cause.
- **Side-bag slot count from `ContainersCapacity` when known, else 7** — the column is physically 7
  slots; clamping to capacity matches retail (you see only as many slots as you can use) without a wire
  dependency (capacity ships in the weenie header, already parsed).

---

## 5. Testing

- **`UiItemList` clip/scroll (unit, App.Tests):** content-height for N cells; the visible-cell index
  range at scroll offset 0 and at max offset; wheel delta updates the offset (clamped); `UiScrollable`
  thumb/position ratios for a known content/view. (No GL — assert the model + which cells are in-view.)
- **`InventoryController` (unit, App.Tests, `BuildLayout` harness):** the side-bag column renders
  `bags + empties = slotCount` cells (filled first, then empty); the contents grid is bound to the
  scrollbar (the `0x100001C7` widget's scroll model is the grid's). A >18-item grid reports content
  height > view height (scrollable).
- **Backdrop:** visual gate only (no unit test).
- Full `dotnet build` + `dotnet test` green; existing inventory tests (incl. the B-Wire burden tests)
  unbroken.

---

## 6. Divergence register

- If the side-bag slot count uses a fallback (7) when `ContainersCapacity` is absent, add a row noting
  the approximation. If B's residual fix stretches the Alphablend backdrop in a way that differs from
  retail's exact draw, add a row. Otherwise no new deviations (faithful 2D layout). Any row lands in the
  same commit as its deviation (register rule).

---

## 7. Out of scope (explicit)

Paperdoll doll + equip-slot silhouettes (Stage 2); drag-to-drop / drag-from-inventory (B-Drag); the
side-bag column scrollbar `0x100001CB` (inert — 7 slots fit); contents-grid drag-reorder; stack-quantity
overlays.

---

## 8. Acceptance + visual gate

- [ ] Contents grid clips to 3 rows + scrolls (wheel + scrollbar); picked-up items reachable; no
      overflow past the frame.
- [ ] Backdrop covers the whole window (no grass through), confirmed at the gate.
- [ ] Side-bag column shows bag(s) + empty slot frames (36px pitch).
- [ ] `dotnet build` + `dotnet test` green.
- [ ] **Visual gate:** open F12 with a full pack → matches retail screenshot 2 (minus the doll):
      scrollable grid, solid backdrop, bag-slot column.

Then Stage 2 (paperdoll) gets its own brainstorm → spec → plan.