acdream/docs/superpowers/specs/2026-06-25-ui-studio-previewer-design.md

# acdream UI Studio — design (live previewer + inspector)

- Date: 2026-06-25
- Status: approved (user pre-approved full v1 scope 2026-06-25)
- Branch: claude/hopeful-maxwell-214a12
- Supersedes/foundation for: the deferred phase-2 drag-drop *designer*

## Goal

A standalone, fast-booting dev tool that renders **any acdream UI panel** through the
**production renderer**, with a click-to-inspect element inspector, sample-data fixtures,
markup hot-reload + write-back editing, and render-config sliders.

It collapses the panel-iteration loop — today `edit → build → login to ACE → wait ~8s →
F12 → eyeball vs retail → close → repeat` (~30–60 s/iteration) — into `edit → glance`
(~1 s). Everything we did on the paperdoll this session (confirming the pose, framing the
camera, catching the mirrored heading) would have been a few clicks here instead of a dozen
relaunches.

**Fidelity is the whole point.** The previewed panel is drawn by the SAME
`UiHost` / `LayoutImporter` / `DatWidgetFactory` / dat-sprite path that ships, so what you
see is what the game renders. This is the decisive reason NOT to build the tool in a
separate stack (Godot/HTML) and NOT to rely on the existing `render-vitals-mockup` (a
separate CPU `SurfaceDecoder` composite that can drift from the GL path).

## Scope — v1 is the maximum capability

IN:
- Load a panel from EITHER a dat `LayoutDesc` id OR a markup file (`MarkupDocument`).
- Render via the production GL `UiHost` (2-D panels) AND the full WB mesh pipeline (the
  3-D paperdoll **doll**).
- **Sample-data fixtures** so data-bound panels look populated: canned inventory items,
  sample vital values, a dressed sample creature for the doll.
- **Inspector (ImGui):** element tree, click-to-inspect, read-only props
  (id / Type / rect / anchors / state-sprites / ZOrder), **editable** markup props
  (write back to the file), and **render-config sliders** (the doll camera eye / FOV /
  heading — values that live in code, not markup).
- **Hot-reload:** file-watch the markup source; reload-on-demand (id picker / reload button)
  for dat layouts.

OUT (phase 2): the drag-drop visual **designer** (compose *new* layouts on a canvas and
emit markup). The previewer is the foundation that phase sits on. Its natural home is the
plugin-UI story, not the retail-panel work.

Not faithfulness-gated: this is a DEV tool. The previewed *panels* are faithful (same
renderer); the tool *chrome* (the ImGui inspector) is dev-only. No
`retail-divergence-register` rows are created by this work.

## Architecture

Seven isolated, single-purpose units. The previewed panel is drawn by the production
renderer; the tool chrome is **ImGui** (already in `AcDream.App` for the `ACDREAM_DEVTOOLS`
overlay — ideal for a tree / sliders / editable fields at near-zero cost).

```
Program.cs ──"ui-studio"──▶ StudioWindow
                              │  owns: Silk window, ImGui ctx, frame loop
                              ▼
                         RenderBootstrap.Create(gl, opts) ──▶ RenderStack
                              │   (GL + DatCollection + TextureCache + UiHost
                              │    + ObjectMeshManager + WbDrawDispatcher + lighting UBO)
                              │   ALSO consumed by GameWindow (shared = de-tangles OnLoad)
        ┌─────────────────────┼───────────────────────────────┐
        ▼                     ▼                                ▼
   LayoutSource         FixtureProvider                  StudioInspector (ImGui)
   dat id | markup      sample item table / vitals /     tree · props(read+edit) ·
   → UiElement tree     dressed creature → controllers   render sliders · canvas(FBO)
        │                                                      │ click → HitTestTopDown
        └────────── HotReloadWatcher (markup) ─────────────────┘
                    MarkupWriteBack (edited props → file)
```

### 1. `RenderBootstrap` — NEW, `src/AcDream.App/Rendering/`
Extracts the **render-stack construction** currently tangled inside `GameWindow.OnLoad`
(the GL api, dat-dir → `DatCollection`, `TextureCache`, the WB mesh pipeline —
`ObjectMeshManager` / `WbDrawDispatcher` / `SceneLightingUboBinding` — and `UiHost`) into a
reusable unit that BOTH `GameWindow` and `StudioWindow` build through.
- Interface: `RenderStack Create(GL gl, RenderBootstrapOptions opts)`; `RenderStack` is a
  record of the constructed pieces (dats, textureCache, meshManager, drawDispatcher,
  lightingUbo, uiHost, shaderDir).
- `GameWindow.OnLoad` is refactored to consume it — **behavior-preserving**, locked by the
  existing App/Core suites + a visual gate that the GAME still renders.
- Highest-risk step → extract the SMALLEST cohesive slice only; do it first, gate it, build
  the studio on it second. Fallback if extraction is too entangled: `StudioWindow` builds a
  studio-local duplicate of the mesh-pipeline setup (more drift, lower regression risk) — to
  be decided at implementation, not assumed away.

### 2. `StudioWindow` — NEW, `src/AcDream.App/Studio/`
A Silk.NET windowed GL app — the studio entry. Owns the window, the `RenderStack`, the ImGui
context, the inspector, the hot-reload watcher, and the per-frame loop. **No** ACE /
world-streaming / physics / movement input. Launched from `Program.cs`:
`AcDream.App ui-studio <datdir> [--layout 0x21000023 | --markup path.xml]`. Config flows
through `RuntimeOptions` (one env/arg read), per the code-structure rules.

### 3. `LayoutSource` — NEW, `src/AcDream.App/Studio/`
Loads a panel into a `UiElement` subtree from a dat id (`LayoutImporter.Import`) or a markup
file (`MarkupDocument.Build`). Owns the current source + `Reload()`.
- Interface: `UiElement Load()`, `void Reload()`, `SourceKind Kind`, `string? MarkupPath`,
  `uint? LayoutId`, plus a `string? LastError` for the inspector to surface parse failures.

### 4. `FixtureProvider` — NEW, `src/AcDream.App/Studio/`
Supplies sample data so data-bound panels render populated. A fake `ClientObjectTable`
seeded with a handful of canned items (icon ids + types); sample vital values; a sample
creature (Setup + ObjDesc) for the doll. Maps a known `layoutId` → its real controller
(`VitalsController` / `InventoryController` / `ToolbarController` / `PaperdollController`)
bound to the fixtures — REUSING the production controllers, not re-implementing them.
- Interface: `void Populate(uint layoutId, UiElement root, RenderStack stack)`. Unknown
  layout id → no fixture (structural preview only), not an error.

### 5. `StudioInspector` — NEW, `src/AcDream.App/Studio/`
The ImGui tool chrome, four docked windows:
- **Canvas** — the panel rendered to an FBO (RTT, the `PaperdollViewportRenderer` technique
  applied to the whole panel) shown via `ImGui.Image`. Click → map canvas-local coords →
  `UiRoot.HitTestTopDown` → select. The FBO route gives a clean dockable IDE layout +
  accurate click mapping, and isolates the panel's GL state from ImGui's.
- **Tree** — the live `UiElement` hierarchy with each node's registered Type; select syncs
  with the canvas highlight.
- **Properties** — the selected element's id / Type / rect / anchors / state-sprites (with
  swatches) / ZOrder. Rect/anchor fields are **editable** (markup source) → applied live +
  queued to `MarkupWriteBack`.
- **Render config** — sliders for the doll's `DollCamera` eye / FOV / heading, mutating the
  live camera so the doll updates next frame; a "copy values" button emits the literals to
  paste into code.

### 6. `MarkupWriteBack` — NEW, `src/AcDream.App/Studio/`
Serializes an edited element's changed props back to the markup XML file (markup source
only; dat layouts are read-only). v1 = **targeted in-place attribute updates** (find the
element by id, rewrite the changed attribute values), NOT a full tree re-serialize — so
hand-authored formatting/comments survive.

### 7. `HotReloadWatcher` — NEW, `src/AcDream.App/Studio/`
`FileSystemWatcher` on the markup file → debounced (≈150 ms) reload event → `LayoutSource.Reload`
→ `FixtureProvider.Populate` → re-select the previously-selected element by id when possible.

## Data flow

- **Boot:** `StudioWindow` → `RenderBootstrap.Create` → `LayoutSource.Load(initial)` →
  `FixtureProvider.Populate` → loop.
- **Frame:** bind panel FBO → `UiHost.Tick` + `Draw` (panel, incl. the doll's own nested
  RTT) → unbind → ImGui frame (Canvas image + Tree + Properties + Render-config) → present.
- **Click canvas:** map coords → `HitTestTopDown` → select → Properties shows props.
- **Edit prop:** apply to the live `UiElement` (instant) + (markup) queue write-back.
- **File change:** watcher → `Reload` → `Populate` → re-select by id.
- **Render slider:** mutate `DollCamera` → next frame the doll re-renders.

## Error handling

- Bad layout id / unparseable markup → `LayoutSource.LastError` shown in the inspector; the
  previous panel stays (or an empty canvas), no crash.
- Missing dats at boot → clear error + exit non-zero.
- Panel build/draw wrapped in try/catch → a thrown panel surfaces its exception text in the
  inspector; the tool stays alive (you're often previewing half-broken markup).
- Write-back failure (file locked) → non-fatal inline notice, edit stays applied in-memory.

## Testing

- `LayoutSource`: load a known dat id + a markup string → assert the `UiElement` tree shape
  (reuse the existing golden-fixture pattern, e.g. `vitals_2100006C.json`).
- `FixtureProvider`: assert the seeded `ClientObjectTable` + vitals shapes.
- `MarkupWriteBack`: round-trip — parse → edit a rect → serialize → re-parse → assert the
  changed attribute + that siblings/formatting are untouched.
- `RenderBootstrap`: the existing suites stay green + a manual game visual gate (the refactor
  is behavior-preserving).
- Window / ImGui / doll render: manual visual gate — the studio is itself the visual tool.
- Tests live in `tests/AcDream.App.Tests/Studio/`.

## Build order (staged; each ≈ one subagent chunk + a gate)

1. **`RenderBootstrap` extraction** — behavior-preserving. GATE: game renders unchanged;
   suites green.
2. **`StudioWindow` skeleton + `LayoutSource`(dat id)** — render a 2-D panel to the window.
   GATE: `ui-studio --layout 0x2100006C` shows vitals.
3. **`StudioInspector`** — ImGui + canvas-FBO + tree + read-only props + click-to-inspect.
   GATE: click an element → see its id/rect/sprites.
4. **`FixtureProvider`** — 2-D panels populated (vitals / toolbar / inventory). GATE:
   inventory shows sample items.
5. **Live doll** — `PaperdollViewportRenderer` in the studio + sample creature. GATE: the
   paperdoll shows a dressed doll.
6. **Markup source + `HotReloadWatcher`** — GATE: edit a markup file → studio reloads.
7. **Editable markup props + `MarkupWriteBack`** — GATE: edit a rect in the inspector → file
   updates → reloads.
8. **Render-config sliders** — GATE: drag the eye/FOV → doll updates live.

Steps 1–4 deliver the high-value 2-D previewer + inspector + fixtures fast; 5–8 add the doll
and the editing power. The end-state is the full maximum-capability tool.

## Open risks

- **`RenderBootstrap` extraction from the tangled `GameWindow.OnLoad`** is the riskiest step.
  Mitigation: smallest cohesive slice, behavior-preserving, gated by the game visual + the
  suites BEFORE the studio depends on it; documented fallback (studio-local duplicate).
- **`MarkupWriteBack` formatting preservation** — keep v1 to in-place attribute edits, never
  a full re-serialize, so hand-authored markup isn't clobbered.
- **ImGui + UiHost GL-state interplay** — the panel renders to its own FBO and ImGui owns the
  default framebuffer, so their GL state can't fight (the same seal the paperdoll RTT uses).