docs(D.5): sub-phase ledger + item-model cold-start prompt

Roadmap: refresh the D.5.2 entry to its final shipped state (per-pixel gradient
surface overload 0x004415b0; AP-43/AP-44 retired by visual verification; range
419c3ac..fb288ad). Add an explicit D.5 sub-phase ledger: D.5.4 client object/item
data model (foundation, NEXT) -> D.5.3 selected-object + spell shortcuts -> window
manager -> D.5.5+ core panels. Handoff doc gains a paste-ready new-session prompt.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/plans/2026-04-11-roadmap.md

@@ -432,9 +432,11 @@ behavior. Estimated 17–26 days focused work, 3–5 weeks calendar.
 - **✓ SHIPPED — D.4 — Dat sprites + 9-slice panel backgrounds.** Shipped 2026-06-14 with D.2b. `TextureCache.GetOrUploadRenderSurface(id, out w, out h)` decodes `RenderSurface` (`0x06xxxxxx`) **directly** (not via the Surface→SurfaceTexture chain — the prove-out finding) → GL `Texture2D`; `DrawSprite` (explicit UV-rect, per-texture batch) added to `TextRenderer` + `UiRenderContext` + a `uUseTexture=2` RGBA frag branch; `UiNineSlicePanel` composes the universal 8-piece bevel (corners `0x060074C3..C6`, edges `0x060074BF/C0/C1/C2`, center `0x06004CC2`). Remaining art polish: the glassy gradient bar fill sprite (D.2b polish).
 - **D.5 — Core panels.** Attributes (`chunk_00470000.c:FUN_0047ba70`), Skills (same), Paperdoll (`chunk_004A0000.c:FUN_004A5200`), Inventory, Spellbook (`chunk_004C0000.c`), Fellowship, Allegiance. Each uses the port sketches in slice 05. **(Targets `AcDream.UI.Abstractions` — ships with D.2a using ImGui-rendered widgets; reskinned by D.2b.)** The *chat* panel originally listed under D.5 shipped early in Phase I (I.4 input + I.7 combat translator superseded the chat-panel design here); this entry now covers Attributes / Skills / Paperdoll / Inventory / Spellbook / Fellowship / Allegiance only.
 - **✓ SHIPPED — D.5.1 — Toolbar (action bar).** Shipped 2026-06-16/17 (`30b28c2`→`0e7a083`, branch claude/hopeful-maxwell-214a12). First data-driven *game* panel: `gmToolbarUI` (`LayoutDesc 0x21000016`) — 18 shortcut slots from the persisted `PlayerDescription` SHORTCUT block, real **composited** item icons (opaque type-default underlay via the `EnumIDMap 0x10000004` resolve), **occupancy-gated slot numbers 1–9** (occupied = dark-box peace/war `0x10000042/43`; empty = background `0x1000005e` from cell composite `0x10000341`), **click-to-use** (`ItemHolder::UseObject` → `0x0036`), **peace/war stance** indicator live-wired to `CombatState`, **movable**, and a **chrome frame** (UiNineSlicePanel drawn over content via the new `UiElement.OnDrawAfterChildren` hook). New shared widgets `UiItemSlot` (`UIElement_UIItem` 0x10000032, procedural leaf) + `UiItemList` (`UIElement_ItemList` 0x10000031, factory branch) + `IconComposer` (CPU layered composite). `CreateObject.TryParse` extended to the full ACE-order weenie-header tail to capture `IconId`/`IconOverlay`/`IconUnderlay` → `ItemRepository.EnrichItem` → re-render. Spec/plan `docs/superpowers/{specs,plans}/2026-06-16-d2b-toolbar-phase1*.md`; research drop `docs/research/2026-06-16-*deep-dive.md` + synthesis. Divergence IA-16/IA-17 added. **User-confirmed** (numbers, icons, frame). Per-task spec+code-review throughout.
-- **✓ SHIPPED — D.5.2 — Stateful item-icon system.** Shipped 2026-06-17 (`419c3ac`..`2f789da`, branch claude/hopeful-maxwell-214a12). Full retail icon composite (`IconData::RenderIcons` @407524, 5 layers + recolor): (1) `UiEffects` bitfield captured from `CreateObject` weenie header (was discarded) → `ItemInstance.Effects`; (2) `IconComposer.GetIcon` rewritten as a 2-stage composite — Stage 1 = drag icon (base + overlay) + effect `ReplaceColor` tint (tile from `EnumIDMap 0x10000005` submap, mean-opaque color → white pixels recolored), Stage 2 = underlay + drag; (3) `PublicUpdatePropertyInt (0x02CE)` parser + `WorldSession.ObjectIntPropertyUpdated` event + `GameWindow` subscription → `ItemRepository.UpdateIntProperty` → icon re-composites live. **Appraise (`0x00C9`) carries NO icon data** (WireMCP confirmed, no overlay/effects in appraise payload) — dropped from scope as a no-op. Retire IA-16 (partial composite); add IA-18 (ReplaceColor anti-regression), AP-43 (effect mean-color), AP-44 (effects==0 recolor skipped), AP-45 (0x02CE sequence not honored). Spec: `docs/superpowers/specs/2026-06-17-d2b-stateful-icon-design.md`; plan: `docs/superpowers/plans/2026-06-17-d2b-stateful-icon.md`; research: `docs/research/2026-06-17-stateful-icon-RESOLVED.md`.
-- **D.5.3 — Toolbar interactivity [NEXT].** The toolbar is the **selected-object display**: wire the B.4 `WorldPicker`/selection state → the two hidden meters (`0x100001A1` health / `0x100001A2` mana) + the stack slider (`0x100001A4`) + the object-name line, so the bar shows what the player has selected in the world. (Click-to-use + the peace/war stance indicator already landed in D.5.1.)
-- **D.5.4+ — remaining core panels.** Inventory (`gmInventoryUI`/`gmBackpackUI`), equipment/paperdoll (`gmPaperDollUI`/`gm3DItemsUI` + the `UiViewport` 3D doll), spellbook, etc. — research drop done (`docs/research/2026-06-16-*`); depends on D.5.2 (the stateful icon) + the item-slot/list spine (shipped in D.5.1) + the window manager. Deferred from D.5.1: drag/reorder, the AddShortcut/RemoveShortcut mutate wire, spell shortcuts, the faithful grip/dragbar window manager.
+- **✓ SHIPPED — D.5.2 — Stateful item-icon system.** Shipped 2026-06-17/18 (`419c3ac`..`fb288ad`, branch claude/hopeful-maxwell-214a12; **visually verified on a live Coldeve server**). Faithful retail icon composite (`IconData::RenderIcons` @0x0058d180): (1) `UiEffects` bitfield captured from the `CreateObject` weenie header (was discarded) → `ItemInstance.Effects`; (2) `IconComposer.GetIcon` rewritten as a 2-stage composite — Stage 1 = drag icon (base + custom overlay) + the effect treatment, Stage 2 = type-default underlay + custom underlay + drag. The effect treatment ports the **surface overload** of `SurfaceWindow::ReplaceColor` (`0x004415b0`): the textured effect tile (`EnumIDMap 0x10000005` by `LowestSetBit(effects)+1`, fallback `0x21` solid-black) is copied **per-pixel** into the icon's pure-white pixels — magical items take the tile's GRADIENT hue, mundane items go black; (3) `PublicUpdatePropertyInt (0x02CE)` parser + `WorldSession.ObjectIntPropertyUpdated` event + `GameWindow` subscription → `ItemRepository.UpdateIntProperty` → icon re-composites live. **Appraise (`0x00C9`) carries NO icon data** (ACE proof: `Icon`/`IconOverlay`/`IconUnderlay`/`UiEffects` all lack `[AssessmentProperty]`) — dropped as a no-op. **Two visual-verification fixes landed after the subagent build:** the `effects==0` recolor MUST run (mundane white edges → black, `40c97a5`) and the tint is a per-pixel GRADIENT not a flat color (the surface overload, `fb288ad`) — both confirmed via clean Ghidra + named decomp. Divergence: IA-16 retired; IA-18 (per-pixel surface-copy anti-regression) + AP-45 (0x02CE sequence) added; **AP-43/AP-44 retired by the visual fixes**. Spec/plan/research: `docs/superpowers/{specs,plans}/2026-06-17-d2b-stateful-icon*.md`, `docs/research/2026-06-17-stateful-icon-RESOLVED.md`.
+- **D.5 remaining — sub-phase ledger.** D.5.1 (toolbar + the `UiItemSlot`/`UiItemList`/`IconComposer` spine) ✅ and D.5.2 (stateful icons) ✅ are shipped. Build order from here: **(a) item/object data model → (b) finish the bar: D.5.3 selected-object + spell shortcuts → (c) window manager → (d) core panels.** The data model is the foundation the panels resolve items from — the live-Coldeve missing-icons (4/6 hotbar slots blank) exposed that it's still a scaffold. Each ☐ below gets its own brainstorm → spec → plan.
+- **☐ D.5.4 — Client object/item data model (foundation) [NEXT].** Port retail `ClientObjMaintSystem`: `CreateObject` is the **canonical** object create/update; `PlayerDescription`/`ViewContents (0x0196)`/shortcuts become references; the UI resolves items by guid. Replaces the current **enrich-existing-only** scaffold (`ItemRepository.EnrichItem` drops `CreateObject`s for items with no pre-seeded stub → the Coldeve blank slots). **Crux to settle first:** unify acdream's two object tracks (the `WorldEntity` 3D system + `ItemRepository`) into one table, or keep them separate with a shared ingestion seam? Blocks D.5.5+ (the panels resolve items from this table). User constraint: *"architecturally solid, no quick fixes."* Handoff + cold-start prompt: `docs/research/2026-06-18-item-object-model-handoff.md`.
+- **☐ D.5.3 — Toolbar selected-object display (issue #140) + spell shortcuts.** Wire the B.4 `WorldPicker`/selection state → the two hidden meters (`0x100001A1` health / `0x100001A2` mana) + the stack slider (`0x100001A4`) + the object-name line, so the bar shows the player's currently-selected world object. Plus **spell shortcuts** — pinned *spells* (vs items) don't render their glyphs yet (`ToolbarController.Populate` skips `ObjectGuid==0`). Together these finish "the bar." (Click-to-use + the peace/war stance indicator landed in D.5.1.)
+- **☐ D.5.5+ — Core panels.** Inventory (`gmInventoryUI`/`gmBackpackUI`), equipment/paperdoll (`gmPaperDollUI`/`gm3DItemsUI` + the `UiViewport` 3D doll), vendor, trade, spellbook. Research drop done (`docs/research/2026-06-16-*`). Depends on **D.5.4** (data model) + the item-slot/list/icon spine (D.5.1/D.5.2) + the **window manager** (Plan 2: open/close/z-order/persist + faithful grip/dragbar drag-resize) + the drag-drop spine wired (`UiRoot` has the chain; the per-cell accept/drop hooks are still stubs in `UiField`). Also deferred from D.5.1: drag/reorder + the `AddShortcut`/`RemoveShortcut` mutate wire.
 - **D.6 — HUD.** Vital orbs (scissor-rect partial fill, dat sprites `0x060013B2`), radar (`0x06001388` / `0x06004CC1`, 1.18× range factor), compass strip (scrolling U), target name plate, damage floaters, selection indicator. See slice 06. **(Targets `AcDream.UI.Abstractions` — ships with D.2a; reskinned by D.2b.)** Phase I.2 retired the StbTrueTypeSharp `DebugOverlay` but kept `TextRenderer` + `BitmapFont` alive specifically for D.6's world-space HUD elements (damage floaters, name plates) — they need raw GL text drawing that ImGui can't reach into the 3D scene.
 - **D.7 — Cursor manager.** OS + dat-sourced custom cursors (`FUN_0043c1c0` GDI HCURSOR builder pattern from slice 03). **(D.2b dependency.)**
 - ~~**D.8 — Sound.**~~ **Superseded — shipped as Phase E.2** (`SoundTable`/`Sound` dat decode, OpenAL 16-voice engine, per-entity 3D positional audio via `AudioHookSink`). Entry kept here for history; see the shipped table.

docs/research/2026-06-18-item-object-model-handoff.md

@@ -89,5 +89,32 @@ NOTE the user's standing constraint for this phase: *"No quick fixes — needs t
 architecturally solid and thought through."* Do not band-aid `EnrichItem` to add new items;
 design the model properly.
 
+## 6. New-session prompt (paste into a fresh session)
+
+> Design and build acdream's **client object/item data model** — the foundation under the D.5
+> core panels (inventory, equipment/paperdoll, vendor, trade). This is roadmap **D.5.4** and it
+> blocks D.5.5+. **Read this handoff first: `docs/research/2026-06-18-item-object-model-handoff.md`**,
+> then `docs/research/2026-06-16-ui-item-slot-icon-dragdrop-spine-deep-dive.md` and
+> `docs/research/2026-06-16-inventory-deep-dive.md`.
+>
+> The problem (confirmed live on Coldeve, character Barris): acdream's item model is
+> **enrich-existing-only** — `ItemRepository.EnrichItem` only fills items pre-seeded as stubs
+> from `PlayerDescription`, and DROPS `CreateObject`s for anything else, so most hotbar/pack
+> items render no icon (4 of 6 hotbar slots were blank). Port retail's `ClientObjMaintSystem`:
+> **`CreateObject` is the canonical object create/update**, `PlayerDescription`/`ViewContents`/
+> shortcuts become references, and the UI resolves items by guid. This is NOT a D.5.2 icon bug
+> (the composite is correct for every item that reaches it).
+>
+> **Do this as a proper design — the user's standing constraint is "architecturally solid, no
+> quick fixes" (do NOT band-aid `EnrichItem` to add new items).** Use the full
+> brainstorm → spec → plan → subagent-driven-development flow. **Open the brainstorm by settling
+> the crux FIRST (§2): unify acdream's two object tracks — the `WorldEntity` 3D system (fed by
+> `GameWindow.OnLiveEntitySpawned`) and `ItemRepository` — into ONE object table like retail, or
+> keep them separate with a shared ingestion seam?** Then the ingestion lifecycle (§3 wire
+> surface) and how the toolbar/inventory/paperdoll bind by guid. Follow the mandatory
+> grep-named→cross-ref→pseudocode→port workflow for any AC-specific wire format; conformance
+> tests throughout. Work continues on branch `claude/hopeful-maxwell-214a12` (kept, unmerged;
+> D.5.2 = `52306d9..fb288ad`).
+
 **MEMORY.md index line:**
 - [Handoff: client object/item data model (2026-06-18)](research/2026-06-18-item-object-model-handoff.md) — next phase after D.5.2. Root cause of the live-Coldeve "4/6 hotbar items missing": acdream's item model is enrich-existing-only (drops CreateObjects without a pre-seeded stub). Fix = port retail's `ClientObjMaintSystem` (CreateObject = canonical ingestion; UI resolves by guid). CRUX to settle first: unify the WorldEntity + ItemRepository tracks into one object table, or keep separate w/ shared ingestion? Grounding research + ingestion surface listed. User constraint: architecturally solid, no quick fixes.