fix(ui): keep deck popups above monster hp

docs/ui-generation-structure.md

@@ -0,0 +1,54 @@
+# UI Generation Structure
+
+## Current Rule
+
+Do not hand-edit `ui/DefaultGroup.ui` for SlayDeck UI changes. It is generated
+by `tools/deck/gen-slaydeck.mjs`.
+
+The `.ui` file is expected to stay large because MapleStory Worlds stores UI as
+one JSON entity list. The maintainable source is the generator, not the output.
+
+## Generated Sections
+
+`tools/deck/gen-slaydeck.mjs` centralizes generated UI roots in
+`GENERATED_UI_SECTIONS`:
+
+- `DeckHud`
+- `DeckInspectHud`
+- `DeckAllHud`
+- `CombatHud`
+- `RewardHud`
+- `MapHud`
+- `ShopHud`
+- `RestHud`
+- `MainMenu`
+- `CharacterSelectHud`
+
+When the generator runs, existing entities under those roots are removed and
+emitted again. Stock mobile controls are handled separately by
+`DISABLED_STOCK_CONTROLS`.
+
+## How To Change UI
+
+1. Edit the relevant section in `tools/deck/gen-slaydeck.mjs`.
+2. Add new top-level HUD roots to `GENERATED_UI_SECTIONS`.
+3. Emit section entities with `emit('SectionName', entities)`.
+4. Run `node tools/deck/gen-slaydeck.mjs`.
+5. Verify JSON parsing for generated files.
+
+`emit()` validates that a section only emits paths under its own root. This
+keeps accidental cross-section UI changes from silently landing in
+`DefaultGroup.ui`.
+
+## Next Refactor Target
+
+The next useful split is to move each large section builder into separate files,
+for example:
+
+- `tools/deck/ui/combat-hud.mjs`
+- `tools/deck/ui/shop-hud.mjs`
+- `tools/deck/ui/map-hud.mjs`
+- `tools/deck/ui/menu-hud.mjs`
+
+Keep shared helpers like `entity`, `transform`, `sprite`, `button`, and `text`
+in one shared UI helper module.