Gfx egui Ecosystem — Third-Party HUD Improvements

Summary

Adopt vetted egui ecosystem crates in crates/gfx to finish §4.7b HUD polish faster: less hand-rolled list/modal/feedback code, better scalability as inventory/shop/quest content grows, and a clearer path to §4.8 dashboard screens later.

Constraint: Gfx runs egui 0.31 via egui-macroquad 0.17. Every crate must be pinned to a version that compiles against 0.31 before adoption. Phase B assumes an egui bump when macroquad integration catches up (0.33+).

Policy: Keyboard-first play (TUI parity) stays primary. New widgets must not block existing keybind flows (m move, n rename, arrow pickers, etc.).

Current stack (baseline)

Touch surfaces: hud/overlays.rs, hud/sidebar.rs, hud/combat.rs, hud/mod.rs, ui/list.rs, theme.rs, lib.rs (GfxRenderer).

Crate shortlist (from wiki review)

Phase A — egui 0.31 compatible (do first)

Verify egui dep in crate Cargo.toml before merging each PR.

Phase B — after egui 0.33+ bump

Explicitly deferred / skip

Phased implementation

Work Phase A → Phase B. Each phase ends with manual smoke on make dev-play-gfx and cargo test -p flatland-gfx-engine.

Phase A1 — Feedback + modals (1–2 PRs)

Goal: Players see immediate feedback; modals behave consistently.

1. Add egui-notify = "0.19" (last release on egui 0.31; newer notify needs egui 0.34+).
2. GfxRenderer holds GfxFeedback / Toasts; draw_egui_hud renders toasts after overlays.
3. Wire events from existing GameState log lines (first pass):
   • Harvest complete / craft complete
   • Asset sync result (pushed to log at gfx startup)
   • Disconnect / reconnect messages
4. Modal chrome via hud/modals.rs (flatland_modal backdrop + centered window); migrate:
   • draw_destroy_confirm, draw_rename_prompt
   • draw_connection_settings (F2)
   • Quest withdraw confirm
   • Revisit egui_modal when it ships for egui 0.31+
5. Exit: Esc closes modals in fixed order; toasts visible without obscuring combat strip.

Files: crates/gfx/Cargo.toml, src/lib.rs, src/hud/mod.rs, src/hud/overlays.rs.

Phase A2 — Virtual lists (1–2 PRs)

Goal: Smooth scrolling for 50+ row panels.

1. Add egui_virtual_list.
2. Replace SelectableList + full ScrollArea iteration in:
   • draw_inventory_overlay
   • draw_craft_overlay
   • Shop buy/sell lists (when shop panel lands)
   • draw_rotation_editor ability picker
   • draw_log_panel (sidebar)
3. Keep keyboard selection index in GameState / local play state — virtual list is render-only; do not move selection into egui focus.
4. Exit: Inventory + craft usable with keyboard only; no regression in ↑↓ / Enter behavior.

Files: src/ui/list.rs, src/hud/overlays.rs, src/hud/sidebar.rs.

Phase A3 — Icons + help (1 PR)

Goal: Scannable HUD; self-serve docs for installed players.

1. Add iconflow; define small mapping in theme.rs or ui/icons.rs (encumbrance, gold, combat, network).
2. Use icons in inventory sidebar column, combat action strip, connection settings.
3. Add egui_commonmark; load static markdown:
   • docs/graphical-client.md excerpts or a new assets/client/help.md
   • Render in draw_help_window instead of plain format_keybindings_plain() only (keep keybind table as primary section).
4. Exit: ? help readable; F2 panel shows host/ports with icon + markdown blurb.

Phase A exit gate

Phase B0 — egui version bump (prerequisite)

Goal: Unlock async + table ecosystem.

1. Track egui-macroquad releases for egui 0.33/0.34 support.
2. Bump workspace: egui, egui-macroquad, fix breaking API in theme.rs, overlays.rs, input.rs.
3. Run gfx smoke + cargo test -p flatland-gfx-engine.
4. Publish client crates patch release after bump.

Exit: crates/gfx builds on egui 0.33+ with macroquad play unchanged.

Phase B1 — Async HUD bindings

1. Add egui-async; register plugin in gfx frame (per crate docs for target egui version).
2. Use for:
   • Connection settings “Test connection” button
   • Asset sync progress in-settings (optional manual sync)
   • Future §4.8 market/bank fetch panels
3. Do not replace tokio net thread — egui-async only for UI-facing short HTTP/tasks.

Phase B2 — Character sheet table + optional dock

1. egui_table for draw_stats_overlay attribute/skill grids (sort by level/name).
2. Spike egui_dock behind FLATLAND_GFX_DOCK=1 env — combat + log + sidebar detachable.
3. Only promote dock to default if play-testers prefer it over fixed layout.

Phase B exit gate

Dependency policy

1. One crate per PR when possible — easier rollback and version debugging.
2. Pin exact versions in crates/gfx/Cargo.toml; document egui compatibility in this plan’s crate table.
3. No new egui deps in flatland-client-lib — keep HUD concerns in flatland-gfx-engine only.
4. Feature flags for experimental UI (FLATLAND_GFX_DOCK, debug egui_logger) — default off.

Testing

Roadmap linkage

Add to specification as §4.7f Gfx egui ecosystem (see checklist there).

Feeds §4.7b exit gate (modal polish, shop/rotation UX) and §4.8 dashboard (Phase B async + tables reuse same crates in gfx or shared crates/gfx helpers).

Suggested PR order

1. feat(gfx): egui-toast for craft/quest/sync feedback
2. feat(gfx): egui_modal for destroy/rename/connection/quest confirm
3. feat(gfx): virtual lists for inventory, craft, log
4. feat(gfx): iconflow + commonmark help
5. chore(gfx): egui 0.33 bump (when macroquad ready)
6. feat(gfx): egui-async connection test + egui_table character sheet

Open questions

Definition of done (track)