Document the UI subsystem: chapter 22, with the appendix moving to 23

docs/22-ui.md covers the clay-backed UI: what clay owns against what libakgl
owns, bring-up and the arena refusal contract, the frame bracket and where it
sits in a real frame, the consumed-event rules (with the one-frame-stale hit
test stated plainly), the three widgets, menus across keyboard, gamepad and
mouse, writing raw CLAY() with an application-owned press edge, images and
styles, and how layout errors surface from frame_end with a captured trace.
Every listing is a checked block: one linked-and-run example with pinned
output, eight excerpts quoting examples/uidemo and examples/jrpg/textbox.c,
and the chapter figure is a frame out of uidemo via docs_game_figures.

The chapter owes and pays the comparison the tutorials earn: the dialog
widget's default style reproduces the JRPG textbox palette, the two listings
sit side by side, and the trade is stated -- 125 lines you own completely
against one call that costs you the subsystem. Neither is deprecated;
chapter 21 keeps teaching the hand-rolled panel on purpose.

The appendix moves to 23 (links in chapters 4, 5, 6, 7, 13 and the TOC
updated) and gains the ui.h status cross-reference, the AKGL_UI_* limits
table, and the new draw primitives' rows. Its status-band figures were stale
at COUNT 5 / LIMIT 261 while the band already held six codes; now correct at
7 / 263. Chapter 4 gains AKGL_ERR_UI (262) in the excerpt, the table and the
name list.

Co-Authored-By: Claude Code (Claude Fable 5, claude-fable-5) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KzBDV2fqgnUAcqCKqKvc71

docs/04-errors.md

@@ -25,7 +25,7 @@ The house rules for *writing* code against the protocol — never a `*_RETURN` i
 
 libakerror reserves statuses 0–255 for the host's `errno` values and its own `AKERR_*`
 codes; consumers allocate upward from `AKERR_FIRST_CONSUMER_STATUS`, which is **256**.
-libakgl claims a band of six starting there, under the owner string `"libakgl"`:
+libakgl claims a band of seven starting there, under the owner string `"libakgl"`:
 
 ```c excerpt=include/akgl/error.h
 #define AKGL_ERR_OWNER             "libakgl"
@@ -37,12 +37,13 @@ libakgl claims a band of six starting there, under the owner string `"libakgl"`:
 #define AKGL_ERR_BEHAVIOR          (AKGL_ERR_BASE + 3)   /**< A component did not behave the way its contract requires */
 #define AKGL_ERR_LOGICINTERRUPT    (AKGL_ERR_BASE + 4)   /**< Actor logic is telling the physics simulator to skip it */
 #define AKGL_ERR_COLLISION         (AKGL_ERR_BASE + 5)   /**< A collision query could not be answered; the message says why */
+#define AKGL_ERR_UI                (AKGL_ERR_BASE + 6)   /**< The UI subsystem refused, or clay reported a layout error; the message says which */
 ```
 
-**`AKGL_ERR_LIMIT` is not a status code.** It is `AKGL_ERR_BASE + 6`, one past the last
+**`AKGL_ERR_LIMIT` is not a status code.** It is `AKGL_ERR_BASE + 7`, one past the last
 one, and exists only so `AKGL_ERR_COUNT` can be computed from it. Nothing in `src/` raises
 it and `akgl_error_init` does not name it. Do not write a `HANDLE(e, AKGL_ERR_LIMIT)`
-arm — it would catch nothing, and if a seventh real code is ever added it would silently
+arm — it would catch nothing, and if an eighth real code is ever added it would silently
 start catching that instead.
 
 | Code | Value | Means | Raised by | What the caller does |
@@ -53,10 +54,12 @@ start catching that instead.
 | `AKGL_ERR_BEHAVIOR` | 259 | A component did not behave the way its contract requires | **Nothing in the library.** Only `tests/` raises it, through `testutil.h` | Available to you for the same purpose: asserting a contract in your own code |
 | `AKGL_ERR_LOGICINTERRUPT` | 260 | **Not a failure — a control signal.** "Skip the rest of this step for this actor" | your own `movementlogicfunc` | Raise it deliberately. See the note below |
 | `AKGL_ERR_COLLISION` | 261 | A collision query could not be answered | **One cause only**: `akgl_collision_test`, when the ccd arena is exhausted. The message carries the high-water mark | Raise `AKGL_CCD_ARENA_BYTES` to the reported figure. See [Chapter 15](15-collision.md) |
+| `AKGL_ERR_UI` | 262 | The UI subsystem refused, or clay reported a layout error | `akgl_ui_*` — lifecycle misuse (init twice, a widget outside the frame bracket), an arena or table at its ceiling, and layout errors surfacing from `akgl_ui_frame_end` | The message says which; the ceilings are in [Chapter 23](23-appendix-limits.md). See [Chapter 22](22-ui.md) |
 
 `akgl_error_init` reserves the band all-or-nothing and registers a name for each of the
-six: `"SDL Error"`, `"Registry Error"`, `"Heap Error"`, `"Behavior Error"`,
-`"Logic Interrupt"`, `"Collision Error"`. Those names are what a stack trace prints.
+seven: `"SDL Error"`, `"Registry Error"`, `"Heap Error"`, `"Behavior Error"`,
+`"Logic Interrupt"`, `"Collision Error"`, `"UI Error"`. Those names are what a stack trace
+prints.
 
 Two rows deserve more than a cell.
 
@@ -99,7 +102,7 @@ Statuses raised by the libraries underneath also reach you unchanged. `aksl_fope
 `akgl_error_init` can raise libakerror's `AKERR_STATUS_RANGE_OVERLAP`,
 `AKERR_STATUS_RANGE_FULL` or `AKERR_STATUS_NAME_FULL`.
 
-[Chapter 22](22-appendix-limits.md) has the per-function cross-reference.
+[Chapter 23](23-appendix-limits.md) has the per-function cross-reference.
 
 ## Table 3 — the exit status trap
 
@@ -266,6 +269,6 @@ Four things in there are libakgl-specific and worth naming:
   release.
 - [Chapter 6](06-the-registry.md) — the name lookups behind `AKERR_KEY` and
   `AKERR_NULLPOINTER`.
-- [Chapter 22](22-appendix-limits.md) — which function raises what.
+- [Chapter 23](23-appendix-limits.md) — which function raises what.
 - `deps/libakerror/README.md` — the protocol itself, and the exit-status discussion.
 - The generated Doxygen reference — every function's own `@throws` list.