From 93f50d20a021150a0b95242be0d5dd5cae9d0185 Mon Sep 17 00:00:00 2001
From: Adam Malczewski <github@tradam.dev>
Date: Sat, 11 Apr 2026 19:06:35 +0900
Subject: plan and research

---
 .rules/plan/phase-10-robustness.md | 48 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 .rules/plan/phase-10-robustness.md

(limited to '.rules/plan/phase-10-robustness.md')

diff --git a/.rules/plan/phase-10-robustness.md b/.rules/plan/phase-10-robustness.md
new file mode 100644
index 0000000..39c719d
--- /dev/null
+++ b/.rules/plan/phase-10-robustness.md
@@ -0,0 +1,48 @@
+# Phase 10 — Robustness & Cleanup
+
+---
+
+## Step 10.1 — Proper error handling
+
+- Set `XSetErrorHandler()` to a handler that logs but doesn't crash on
+  `BadWindow`, `BadPixmap`, `BadDrawable` (windows can vanish between
+  operations).
+- Wrap all X calls that reference a window in the handler's
+  error-checked scope.
+- On fatal errors (`XSetIOErrorHandler`), clean up gracefully.
+
+**Verify:** Rapidly spawn and kill clients (a stress loop script). No
+crashes, no X error floods. Clean log output.
+
+---
+
+## Step 10.2 — Clean shutdown
+
+On `SIGINT`/`SIGTERM` or raylib `WindowShouldClose()`:
+
+1. Unredirect all windows (`XCompositeUnredirectSubwindows`).
+2. Free all pixmaps, textures, damage objects.
+3. Release the overlay (if used later).
+4. `XCloseDisplay()`.
+5. `CloseWindow()` (raylib).
+
+**Verify:** Killing the WM with Ctrl+C cleanly restores windows in
+Xephyr (they become visible via X's normal rendering again). No
+orphaned resources.
+
+---
+
+## Step 10.3 — Stress test script
+
+Create `bin/stress-test.sh` that:
+
+1. Starts Xephyr.
+2. Starts the WM.
+3. Rapidly spawns 20 `xterm` instances.
+4. Randomly moves, resizes, and closes them via `xdotool`.
+5. Checks that `wmctrl -l` count matches expectations.
+6. Screenshots the result.
+7. Tears everything down.
+
+**Verify:** No crashes, no hangs, no leaked windows. Screenshot looks
+sane.
-- 
cgit v1.2.3