1 files changed, 58 insertions, 0 deletions

diff --git a/docs/adr/0001-custom-isurface-gui.md b/docs/adr/0001-custom-isurface-gui.md
new file mode 100644
index 0000000..9da3c0c
--- /dev/null
+++ b/docs/adr/0001-custom-isurface-gui.md
@@ -0,0 +1,58 @@
+# 0001 — Custom immediate-mode GUI on ISurface
+
+- Status: Accepted
+- Date: 2026-10-27
+
+## Context
+
+The text-only menu is becoming cumbersome as features accumulate. The cheat
+already has a proven overlay draw path through `ISurface` (`PaintTraverseEx`),
+native text with the bundled Liberation Sans font, text metrics, filled/outlined
+rects, lines and textured polygons. The game runs Source on Linux with a
+32-bit process; the cheat is a single `LD_PRELOAD` shared object.
+
+The main alternatives were:
+
+1. Dear ImGui with its standard OpenGL renderer, hooked into the game's
+   swap/present path.
+2. Dear ImGui rendered through `ISurface`.
+3. A custom immediate-mode GUI on `ISurface`.
+4. Keep the text menu and add categories/pages.
+
+`ISurface::Vertex_t` only carries position and UV, not per-vertex color, so a
+standard ImGui draw-list renderer would lose per-widget text colors unless
+draws were split or text was rendered through a separate path. An OpenGL ImGui
+backend would require locating and hooking the swap path, saving/restoring GL
+state, uploading the font atlas, and integrating SDL input events — an
+unverified risk in this build. The existing ISurface path already draws in-game
+and in menus without a new graphics context.
+
+## Decision
+
+Build a custom immediate-mode GUI directly on the existing `ISurface` draw
+path.
+
+- Fixed dark theme with automatic scale:
+  `clamp(min(screen_w/1920, screen_h/1080), 0.75, 1.5)`.
+- Base window 960x620, body/title fonts 15/20 px at scale 1.
+- Left sidebar categories (Movement, Combat, Visuals, Weapons, System) and a
+  content pane of feature cards with collapsible settings.
+- Native OS cursor by releasing SDL relative-mouse mode while the GUI is open.
+- While open, freeze usercmd input/view and skip combat features; keep the
+  game simulating and keep ESP/FOV circle/speed graph drawing.
+- Replace the text menu with the GUI. No permanent fallback menu; git history
+  retains the old implementation.
+
+## Consequences
+
+- We own the widget set (scrollbar, sliders, toggles, keybind capture, tooltips)
+  and the layout/clipping code. Text clipping and wheel events need explicit
+  handling because ISurface has no clip-rect API and SDL does not expose wheel
+  state by polling.
+- No new runtime dependency or GL context management.
+- The GUI remains inside the engine's VGUI paint path, so it inherits the
+  existing font registration and in-game overlay behavior.
+- The old text menu is removed once the GUI reaches feature parity. During
+  development the GUI is built alongside the text menu and opened with a
+  temporary F2 key; the replacement is complete only when the old tree is
+  deleted.