Add the akgl_ui subsystem: clay-backed menus, HUDs and dialogs (#3)

Merges the clay-ui branch: the akgl_ui subsystem on clay v0.14, the uidemo example, chapter 22, the weaker-model tutorial-test fixes, and the CI repairs that produced this repository's first fully green run.
2026-08-02 16:14:49 -04:00
parent 75da766724 5560edf410
commit bbb7b8f494
35 changed files with 4590 additions and 60 deletions
--- a/.gitea/workflows/ci.yaml
+++ b/.gitea/workflows/ci.yaml
@@ -14,7 +14,7 @@ jobs:
        run: |
          sudo apt-get update -y
          sudo apt-get install -y \
-            cmake doxygen gcc gcovr pkg-config \
+            cmake doxygen gcc gcovr graphviz pkg-config \
            libasound2-dev libfreetype-dev libharfbuzz-dev \
            libpng-dev libtiff-dev libwebp-dev \
            libudev-dev libx11-dev libxcursor-dev libxext-dev \
@@ -56,7 +56,7 @@ jobs:
          fail_on_failure: 'true'
      - name: Upload coverage reports
        if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
        with:
          name: code-coverage
          path: build/coverage/
@@ -123,7 +123,7 @@ jobs:
      # the next baseline if somebody re-records PERFORMANCE.md.
      - name: Upload benchmark tables
        if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
        with:
          name: performance-baseline
          path: perf-baseline.txt
@@ -170,7 +170,7 @@ jobs:
        run: scripts/memcheck.sh
      - name: Upload valgrind logs
        if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
        with:
          name: valgrind-logs
          path: build/Testing/Temporary/MemoryChecker.*.log
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,18 +1,18 @@
 [submodule "deps/semver"]
 	path = deps/semver
-	url = git@github.com:h2non/semver.c.git
+	url = https://github.com/h2non/semver.c.git
 [submodule "deps/SDL"]
 	path = deps/SDL
-	url = git@github.com:libsdl-org/SDL.git
+	url = https://github.com/libsdl-org/SDL.git
 [submodule "deps/SDL_image"]
 	path = deps/SDL_image
-	url = git@github.com:libsdl-org/SDL_image.git
+	url = https://github.com/libsdl-org/SDL_image.git
 [submodule "deps/SDL_mixer"]
 	path = deps/SDL_mixer
-	url = git@github.com:libsdl-org/SDL_mixer.git
+	url = https://github.com/libsdl-org/SDL_mixer.git
 [submodule "deps/SDL_ttf"]
 	path = deps/SDL_ttf
-	url = git@github.com:libsdl-org/SDL_ttf.git
+	url = https://github.com/libsdl-org/SDL_ttf.git
 [submodule "deps/libsdlerror"]
 	path = deps/libakerror
 	url = https://source.starfort.tech/andrew/libakerror.git
@@ -21,10 +21,14 @@
 	url = https://source.starfort.tech/andrew/libakstdlib.git
 [submodule "deps/jansson"]
 	path = deps/jansson
-	url = git@github.com:akheron/jansson.git
+	url = https://github.com/akheron/jansson.git
 [submodule "deps/libccd"]
 	path = deps/libccd
 	url = https://github.com/danfis/libccd.git
 [submodule "deps/tg"]
 	path = deps/tg
 	url = https://github.com/tidwall/tg.git
+[submodule "clay"]
+	path = deps/clay
+	url = https://github.com/nicbarker/clay.git
+	branch = v0.14
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.10)
 # The single source of truth for the library version. It drives the generated
 # include/akgl/version.h, the shared library's VERSION and SOVERSION, and the
 # Version field in akgl.pc. Bump it here and nowhere else.
-project(akgl VERSION 0.8.0 LANGUAGES C)
+project(akgl VERSION 0.9.0 LANGUAGES C)

 # Memory checking reuses the suites that already exist -- `ctest -T memcheck`
 # runs every registered test under valgrind -- rather than adding programs of its
@@ -217,6 +217,7 @@ set(AKGL_PUBLIC_HEADERS
  text
  tilemap
  types
+  ui
  util
 )

@@ -317,6 +318,8 @@ add_library(akgl SHARED
  src/sprite.c
  src/staticstring.c
  src/tilemap.c
+  src/ui.c
+  src/ui_clay.c
  src/util.c
  src/version.c
 )
@@ -368,6 +371,26 @@ set_source_files_properties(${AKGL_CCD_SOURCES} PROPERTIES
  COMPILE_OPTIONS "-w;-fvisibility=hidden;-include;${CMAKE_CURRENT_SOURCE_DIR}/src/ccd_arena_shim.h"
  COMPILE_DEFINITIONS "CCD_STATIC_DEFINE")

+# clay supplies the UI layout engine. Its sources are listed rather than
+# add_subdirectory()'d, on the semver/libccd precedent, because
+# deps/clay/CMakeLists.txt is unusable as a subproject and none of it is ours
+# to fix in a submodule:
+#
+#   - it declares no library target at all -- clay is a single header, and the
+#     add_library(INTERFACE) lines at the bottom are commented out upstream.
+#   - option(CLAY_INCLUDE_ALL_EXAMPLES ... ON) add_subdirectory()s every
+#     example by default, dragging raylib, cairo and sokol into our configure.
+#   - cmake_minimum_required(VERSION 3.27) against this project's 3.10.
+#
+# src/ui_clay.c is the one translation unit that defines CLAY_IMPLEMENTATION;
+# it is 99% vendored code, so it gets -w on the same terms as semver and
+# libccd. Deliberately NOT -fvisibility=hidden, unlike libccd: the CLAY()
+# macros in a consuming game expand to Clay__OpenElement() and friends, which
+# must resolve against libakgl.so, so clay's symbols are part of the ABI on
+# purpose. The matching obligation -- a consumer must not link a second clay --
+# is documented in akgl/ui.h.
+set_source_files_properties(src/ui_clay.c PROPERTIES COMPILE_OPTIONS "-w")
+
 # PRIVATE, so that ccd/*.h never reaches a consumer's include path. The `headers`
 # suite compiles each public header as the first include of a translation unit
 # with only include/ available, so a public header that pulled in <ccd/ccd.h>
@@ -406,6 +429,7 @@ set(AKGL_TEST_SUITES
  staticstring
  text
  tilemap
+  ui
  util
  version
 )
@@ -516,6 +540,11 @@ set_tests_properties(
 target_include_directories(akgl PUBLIC
  include/
  deps/semver/
+  # PUBLIC, unlike libccd's PRIVATE include above, because akgl/ui.h includes
+  # <clay.h> in its public interface -- consumers write CLAY() blocks, so
+  # hiding the header would hide the point. clay.h is installed beside
+  # semver.h for the same reason.
+  deps/clay/
  # akgl/version.h is generated by configure_file, so it lives in the build tree
  # rather than beside the headers it is included from.
  ${CMAKE_CURRENT_BINARY_DIR}/include/
@@ -633,20 +662,26 @@ if(AKGL_VENDORED_DEPENDENCIES)
    "${CMAKE_CURRENT_BINARY_DIR}/deps/libakerror"
    "${CMAKE_CURRENT_BINARY_DIR}/deps/libakstdlib"
  )
+  # set_property rather than set_tests_properties for the list-valued
+  # property: set_tests_properties parses its PROPERTIES arguments as
+  # name/value pairs, so a semicolon-separated value is split and every
+  # element after the first is consumed as a bogus property name -- which
+  # silently reduced this prepend list to its first directory for as long as
+  # it existed. RPATH covered for it locally; a runner found it.
  if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.22")
    set(AKGL_TEST_ENV_MOD "")
    foreach(dir IN LISTS AKGL_TEST_LIBPATH)
      list(APPEND AKGL_TEST_ENV_MOD "LD_LIBRARY_PATH=path_list_prepend:${dir}")
    endforeach()
-    set_tests_properties(
-      ${AKGL_TEST_SUITES} ${AKGL_PERF_SUITES}
-      PROPERTIES ENVIRONMENT_MODIFICATION "${AKGL_TEST_ENV_MOD}"
+    set_property(
+      TEST ${AKGL_TEST_SUITES} ${AKGL_PERF_SUITES}
+      PROPERTY ENVIRONMENT_MODIFICATION ${AKGL_TEST_ENV_MOD}
    )
  else()
    string(REPLACE ";" ":" AKGL_TEST_LIBPATH_JOINED "${AKGL_TEST_LIBPATH}")
-    set_tests_properties(
-      ${AKGL_TEST_SUITES} ${AKGL_PERF_SUITES}
-      PROPERTIES ENVIRONMENT "LD_LIBRARY_PATH=${AKGL_TEST_LIBPATH_JOINED}:$ENV{LD_LIBRARY_PATH}"
+    set_property(
+      TEST ${AKGL_TEST_SUITES} ${AKGL_PERF_SUITES}
+      PROPERTY ENVIRONMENT "LD_LIBRARY_PATH=${AKGL_TEST_LIBPATH_JOINED}:$ENV{LD_LIBRARY_PATH}"
    )
  endif()
 endif()
@@ -754,7 +789,12 @@ add_test(
 set_tests_properties(docs_examples PROPERTIES
  WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
  TIMEOUT 900
-  ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_AUDIODRIVER=dummy;SDL_RENDER_DRIVER=software"
+)
+# set_property for the same pair-splitting reason as the suites above.
+set_property(TEST docs_examples PROPERTY ENVIRONMENT
+  "SDL_VIDEODRIVER=dummy"
+  "SDL_AUDIODRIVER=dummy"
+  "SDL_RENDER_DRIVER=software"
 )

 # Every figure in docs/ re-rendered and byte-compared against the tracked copy.
@@ -779,7 +819,11 @@ add_test(
 set_tests_properties(docs_screenshots PROPERTIES
  WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
  TIMEOUT 900
-  ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_AUDIODRIVER=dummy;SDL_RENDER_DRIVER=software"
+)
+set_property(TEST docs_screenshots PROPERTY ENVIRONMENT
+  "SDL_VIDEODRIVER=dummy"
+  "SDL_AUDIODRIVER=dummy"
+  "SDL_RENDER_DRIVER=software"
 )

 # Regenerating the figures is a deliberate act, never part of a build: the PNGs
@@ -832,7 +876,15 @@ if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/examples/CMakeLists.txt")
            --demo --frames 240
            --screenshot "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/jrpg.png"
            --screenshot-frame 230
-    DEPENDS sidescroller jrpg
+    # Frame 100 of the UI demo's scripted tour is the play screen with the
+    # dialog up and the score mid-count -- all three widgets in one frame.
+    COMMAND ${CMAKE_COMMAND} -E env
+            SDL_VIDEODRIVER=dummy SDL_RENDER_DRIVER=software SDL_AUDIODRIVER=dummy
+            $<TARGET_FILE:uidemo>
+            --demo --frames 240
+            --screenshot "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/uidemo.png"
+            --screenshot-frame 100
+    DEPENDS sidescroller jrpg uidemo
    COMMENT "Regenerating the tutorial figures in docs/images"
    VERBATIM
  )
@@ -882,11 +934,14 @@ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/akgl.pc DESTINATION "lib/pkgconfig/")
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/include/akgl/version.h DESTINATION "include/akgl/")
 install(TARGETS akgl DESTINATION "lib/")
 install(FILES "deps/semver/semver.h" DESTINATION "include/")
-# libccd is compiled into libakgl.so, and its BSD-3 licence requires the notice
-# to travel with the binary form. Nothing else in deps/ is linked in statically
-# -- SDL, jansson, libakerror and libakstdlib are all separate shared objects
-# that ship their own -- so this is the only third-party notice we owe.
+install(FILES "deps/clay/clay.h" DESTINATION "include/")
+# libccd and clay are compiled into libakgl.so, and their licences (BSD-3 and
+# zlib respectively) ask that the notice travel with the binary form. Nothing
+# else in deps/ is linked in statically -- SDL, jansson, libakerror and
+# libakstdlib are all separate shared objects that ship their own -- so these
+# are the only third-party notices we owe.
 install(FILES "deps/libccd/BSD-LICENSE" DESTINATION "share/doc/akgl/" RENAME "BSD-LICENSE.libccd")
+install(FILES "deps/clay/LICENSE.md" DESTINATION "share/doc/akgl/" RENAME "LICENSE.clay")
 foreach(header IN LISTS AKGL_PUBLIC_HEADERS)
  install(FILES "include/akgl/${header}.h" DESTINATION "include/akgl/")
 endforeach()
--- a/TODO.md
+++ b/TODO.md
@@ -1273,6 +1273,15 @@ engines spend the same frame**.
   cached") with the raw-SDL control row the perf rules require. Budget to
   move: `tests/perf_render.c:391`.

+   **The UI subsystem is this cache's second consumer, and the bigger one.**
+   `akgl_ui_execute_commands` (`src/ui.c`) draws every TEXT render command
+   through `akgl_text_rendertextat`, one wrapped line per command per frame —
+   a menu of five rows re-rasterizes five lines at 60 Hz whether or not any
+   of them changed, where the original HUD case was one line changing once a
+   second. Abstract-on-the-second-consumer says this item's time has come;
+   the key already fits, since clay hands the executor stable text bytes
+   between frames.
+
 3. **Non-raising sprite lookup — target 10, a design change.** Give
   `akgl_character_sprite_get` (`src/character.c:84-94`) the companion that
   returns `NULL` without raising, then convert the three sites that raise
@@ -2196,6 +2205,18 @@ a live defect -- but nothing rejects it, and `max_timestep` is caller-settable.
   `renderfunc`. This item is the half that remains: one uniform `scale`, with no way
   to expand a single axis.

+3. **`akgl_ControlMap.mouseid` and `.penid` are still dead fields, deliberately.**
+   The UI subsystem (0.9.0) brought the mouse into the library, and it would have
+   been natural to wire these up on the way -- it did not, on purpose. Control maps
+   translate device events into *actor handler calls*, and the UI wants absolute
+   pointer state per event; those are different consumers, and building
+   gameplay-mouse machinery into `src/controller.c` with no game asking for it is
+   the abstract-before-the-second-consumer mistake. The mouse path lives in
+   `src/ui.c` (`akgl_ui_handle_event`); when a game wants mouse-driven actors,
+   *that* is the consumer these fields were declared for, and the work lands in
+   `controller.c` then. Same for `.axis`, `.axis_range_min` and `.axis_range_max`,
+   which `akgl_controller_handle_event` has never consulted.
+
 ## Found while writing the manual

 Twenty-one chapters and two tutorial games were written against `src/` rather than
--- a/deps/clay
+++ b/deps/clay
--- a/docs/04-errors.md
+++ b/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.
--- a/docs/05-the-heap.md
+++ b/docs/05-the-heap.md
@@ -344,4 +344,4 @@ all visible in `src/heap.c`.

 - [Chapter 4](04-errors.md) — `AKGL_ERR_HEAP` in the status tables.
 - [Chapter 6](06-the-registry.md) — the registries the releases clear entries from.
- [Chapter 22](22-appendix-limits.md) — every `AKGL_MAX_*` in one place.
+- [Chapter 23](23-appendix-limits.md) — every `AKGL_MAX_*` in one place.
--- a/docs/06-the-registry.md
+++ b/docs/06-the-registry.md
@@ -224,5 +224,5 @@ registry's.
 - [Chapter 7](07-the-game-and-the-frame.md) — where in startup the registries are created,
  and where configuration has to be in place by.
 - [Chapter 14](14-physics.md) — choosing a backend, and what the `physics.*` properties do.
- [Chapter 22](22-appendix-limits.md) — the configuration table again, alongside every
+- [Chapter 23](23-appendix-limits.md) — the configuration table again, alongside every
  `AKGL_MAX_*`.
--- a/docs/07-the-game-and-the-frame.md
+++ b/docs/07-the-game-and-the-frame.md
@@ -367,4 +367,4 @@ error-reporting path. See [Chapter 4](04-errors.md).
  what `draw_world` does with the layers.
 - [Chapter 14](14-physics.md) — what `simulate` does with the `dt` this chapter does not
  pace.
- [Chapter 22](22-appendix-limits.md) — `AKGL_GAME_*` and the rest of the constants.
+- [Chapter 23](23-appendix-limits.md) — `AKGL_GAME_*` and the rest of the constants.
--- a/docs/13-tilemaps.md
+++ b/docs/13-tilemaps.md
@@ -37,7 +37,7 @@ why the library's own map, `akgl_default_gamemap`, is a file-scope object in
 The bounds are fixed at compile time, so the size is fixed too. Every field is present
 whether the map uses it or not: a 20x15 map with one tileset and two layers costs the same
 25.2 MiB as a 511x511 one. Raising any of the constants below raises this number and
-changes the ABI — see [Chapter 22](22-appendix-limits.md).
+changes the ABI — see [Chapter 23](23-appendix-limits.md).

 ## Limits

--- a/docs/22-ui.md
+++ b/docs/22-ui.md
@@ -0,0 +1,396 @@
+# 22. User interfaces
+
+![The UI demo's play screen: a LIVES label top-left, a SCORE label top-right, and a dialog panel across the bottom, over a checkerboard standing in for a game world](images/uidemo.png)
+
+Every game eventually wants a dialog box, a score counter, or a menu — and hand-rolling
+them out of rectangles and `akgl_text_rendertextat` is tolerable exactly once.
+[Chapter 21](21-tutorial-jrpg.md) does it once, on purpose, and its 125-line
+`textbox.c` is still the right call for one panel with no ambitions. This chapter is for
+everything past that point: HUDs, menus, options screens, and the layout arithmetic that
+makes them miserable to maintain by hand.
+
+The layout engine is [clay](https://github.com/nicbarker/clay), vendored under
+`deps/clay` and compiled into `libakgl.so`. Per this manual's rule, clay's own API is
+documented by clay — its README is thorough — and this chapter covers what libakgl adds
+or constrains. The split:
+
+| clay owns | libakgl owns |
+|---|---|
+| The layout algorithm and the `CLAY()` declaration DSL | The arena clay allocates from — static storage, no `malloc`, sized by `AKGL_UI_ARENA_BYTES` |
+| Sizing, padding, floating elements, scroll containers | Text measurement, through SDL_ttf and the font registry |
+| The render command list each frame produces | Drawing those commands, through the render backend |
+| Hover and pointer-over queries | Feeding it the mouse, and telling *you* which events the UI consumed |
+
+**There are two ways in, and they compose.** The widget helpers — `akgl_ui_dialog`,
+`akgl_ui_label`, `akgl_ui_menu` — cover the common cases in one call each, and a simple
+game never touches a `CLAY()` macro. When a screen outgrows them, you write clay's
+declarative blocks yourself between the same two frame calls, with the whole DSL
+available. The demo this chapter quotes, [`examples/uidemo`](../examples/uidemo), does
+both: its title menu and HUD are widgets, its options screen is raw `CLAY()`.
+
+**What this chapter assumes.** A program that already brings libakgl up — the
+`akgl_game_init` startup order from [Chapter 7](07-the-game-and-the-frame.md) (or
+[Chapter 3](03-getting-started.md)'s smallest window), plus one loaded font from
+[Chapter 17](17-text-and-fonts.md). None of that is restated here, and the UI adds only
+three calls to it, shown below. When something in *your* bring-up fights you, the demo's
+`startup()` in [`examples/uidemo/uidemo.c`](../examples/uidemo/uidemo.c) is the complete
+working sequence to diff against — including the `main()` shape, which the runnable
+snippets in this manual deliberately hide.
+
+Like collision, the subsystem is optional at runtime rather than at build time: it is
+always compiled in, costs static storage until `akgl_ui_init` runs, and a game that
+never calls that pays nothing else.
+
+**One warning before any code.** libakgl ships clay inside `libakgl.so` and exports its
+symbols, because the `CLAY()` macros in *your* translation units expand to calls into
+them. Do not define `CLAY_IMPLEMENTATION` anywhere and do not link a second copy of clay
+— two definitions of the same symbols, and the loader picks one silently.
+
+## Bring it up, lay something out
+
+`akgl_ui_init(width, height)` takes the layout size as parameters — deliberately not
+read from the camera or the window, so a headless program can bring the UI up with no
+renderer at all. It bounds clay to the `AKGL_UI_*` ceilings, checks the arena fits them,
+and refuses **with both byte counts in the message** when it does not: a raised ceiling
+without a raised arena is a loud startup failure, never a corruption at frame forty
+thousand.
+
+After that, a frame of UI is a bracket with declarations inside:
+
+```c run=akglapp
+PASS(errctx, akgl_ui_init(320, 240));
+
+PASS(errctx, akgl_ui_frame_begin());
+CLAY({
+    .id = CLAY_ID("panel"),
+    .layout = {
+	.sizing = {
+	    .width = CLAY_SIZING_FIXED(120),
+	    .height = CLAY_SIZING_FIXED(40)
+	}
+    },
+    .backgroundColor = { 24, 20, 37, 255 }
+}) {}
+PASS(errctx, akgl_ui_frame_end(akgl_renderer));
+
+PASS(errctx, akgl_ui_shutdown());
+printf("one panel, laid out and drawn\n");
+```
+
+```output
+one panel, laid out and drawn
+```
+
+`frame_begin` starts the clay layout and feeds it the pointer state the event handler
+has been accumulating; `frame_end` computes the layout and draws every render command it
+produces through the backend — fills and rounded fills, borders, clip rectangles, text,
+and sprites. Everything lands in screen coordinates on top of whatever is already on the
+target.
+
+Text needs one more step at startup: fonts. clay names a font by a `uint16_t` fontId;
+libakgl names one by a registry key ([Chapter 17](17-text-and-fonts.md)). The bridge is
+`akgl_ui_font_register`, and the demo's whole font story is three lines:
+
+```c excerpt=examples/uidemo/uidemo.c
+    PASS(errctx, akgl_text_loadfont(UIDEMO_FONT_NAME, UIDEMO_FONT_FILE, UIDEMO_FONT_SIZE));
+    PASS(errctx, akgl_ui_init(UIDEMO_WIDTH, UIDEMO_HEIGHT));
+    PASS(errctx, akgl_ui_font_register(UIDEMO_FONT_NAME, &fontid));
+```
+
+The first font registered gets id 0, which is what the widgets' default style uses — so
+a one-font game never mentions a fontId again. Two things worth knowing before they
+surprise you:
+
+- **`Clay_TextElementConfig.fontSize` is ignored.** A libakgl font bakes its size in at
+  load ([Chapter 17](17-text-and-fonts.md) explains why); the size text renders at is
+  the size the font behind its id was loaded at. One face at two sizes is two loads, two
+  registrations, two ids.
+- The table stores the *name* and resolves it per use, so `akgl_text_unloadfont` on a
+  registered font makes the next frame fail loudly with the name in the message — not
+  dangle.
+
+## The frame contract
+
+Where the bracket goes in a real frame, from the demo — compare the JRPG's `frame()`,
+which calls `akgl_game_update` where this program paints a checkerboard:
+
+```c excerpt=examples/uidemo/uidemo.c
+    PASS(errctx, akgl_renderer->frame_start(akgl_renderer));
+    if ( state == UIDEMO_STATE_PLAY ) {
+	PASS(errctx, akgl_draw_background(akgl_renderer, UIDEMO_WIDTH, UIDEMO_HEIGHT));
+	score += 1;
+    }
+
+    PASS(errctx, akgl_ui_frame_begin());
+    switch ( state ) {
+    case UIDEMO_STATE_TITLE:
+	PASS(errctx, declare_title());
+	break;
+    case UIDEMO_STATE_OPTIONS:
+	PASS(errctx, declare_options());
+	break;
+    case UIDEMO_STATE_PLAY:
+	PASS(errctx, declare_play());
+	break;
+    default:
+	break;
+    }
+    PASS(errctx, akgl_ui_frame_end(akgl_renderer));
+```
+
+The UI draws after the world because it is declared after the world — the overlay slot
+between `akgl_game_update` and the backend's `frame_end` is exactly where the JRPG drew
+its hand-rolled text box, and nothing about that slot changed.
+
+Events go through the UI *first*. `akgl_ui_handle_event` takes every event
+unconditionally — the same pass-everything contract as `akgl_controller_handle_event` —
+and reports back whether the UI claimed it, so a click on a menu never leaks through and
+also fires a game control:
+
+```c excerpt=examples/uidemo/uidemo.c
+    PASS(errctx, akgl_ui_handle_event((void *)&akgl_game.state, event, &consumed));
+    if ( consumed ) {
+	SUCCEED_RETURN(errctx);
+    }
+
+    switch ( state ) {
+    case UIDEMO_STATE_TITLE:
+	PASS(errctx, akgl_ui_menu_handle_event(&title_menu, event, &consumed));
+	break;
+```
+
+Three rules govern what gets consumed, and each is a decision worth stating:
+
+- **Presses, releases and the wheel are consumed when the pointer is over any UI
+  element.** Motion and resizes never are — the game may care where the mouse is, and
+  certainly cares about its window.
+- **The hit test runs against the layout the previous frame declared**, because this
+  frame's does not exist while events are being polled. clay retains the last tree for
+  exactly this purpose; one frame of staleness is the standard model's accepted cost,
+  and before any frame has been laid out, nothing is over anything.
+- **Keyboard events are never consumed by the UI itself.** Which menu hears the arrow
+  keys is something the application declares — the `switch` above *is* the focus model —
+  not something a pointer position implies.
+
+## A dialog in one call — and what it replaces
+
+The play screen's declarations, whole:
+
+```c excerpt=examples/uidemo/uidemo.c
+    PASS(errctx, aksl_snprintf(&count, scoretext, sizeof(scoretext), "SCORE %05d", score));
+    PASS(errctx, aksl_snprintf(&count, livestext, sizeof(livestext), "LIVES %d", lives));
+    PASS(errctx, akgl_ui_label("score", scoretext, AKGL_UI_ANCHOR_TOP_RIGHT, NULL));
+    PASS(errctx, akgl_ui_label("lives", livestext, AKGL_UI_ANCHOR_TOP_LEFT, NULL));
+    if ( dialog_open ) {
+	PASS(errctx, akgl_ui_dialog("dialog",
+				    "This panel is one call. Space dismisses it; "
+				    "compare examples/jrpg/textbox.c.",
+				    NULL));
+    }
+```
+
+Note what is absent: no `visible` flag, no draw call, no geometry. The dialog is open
+because this frame declares it — a declarative frame *is* the flag. The text buffers are
+`static` because clay borrows the pointer until `frame_end` rather than copying; format
+your score into storage that outlives the bracket.
+
+Now the same panel the way [Chapter 21](21-tutorial-jrpg.md) builds it, which is the
+comparison this chapter owes you. The hand-rolled version keeps a flag and a copy of the
+string, and its draw function does the geometry itself:
+
+```c excerpt=examples/jrpg/textbox.c
+    panel.x = TEXTBOX_MARGIN;
+    panel.w = akgl_camera->w - (2.0f * TEXTBOX_MARGIN);
+    panel.h = TEXTBOX_HEIGHT;
+    panel.y = akgl_camera->h - TEXTBOX_MARGIN - panel.h;
+
+    PASS(errctx, akgl_draw_filled_rect(akgl_renderer, &panel, TEXTBOX_FILL));
+    PASS(errctx, akgl_draw_rect(akgl_renderer, &panel, TEXTBOX_EDGE));
+    PASS(errctx,
+	 akgl_text_rendertextat(
+	     font,
+	     textbox_text,
+	     TEXTBOX_INK,
+	     (int)(panel.w - (2.0f * TEXTBOX_PADDING)),
+	     (int)(panel.x + TEXTBOX_PADDING),
+	     (int)(panel.y + TEXTBOX_PADDING)
+	     ));
+```
+
+The widget's default style is **deliberately that panel's palette** — near-black fill,
+parchment edge and ink, 8 pixels of padding — so the two produce the same picture, and
+the trade is visible with nothing hidden in a theme:
+
+- `textbox.c` is 125 lines you own completely. It costs no new concepts, no arena, no
+  frame bracket; its geometry is four assignments you can read. For one panel, that is a
+  perfectly good deal — which is why chapter 21 still teaches it and its game still
+  ships it.
+- `akgl_ui_dialog` is one line that costs you the subsystem: `akgl_ui_init`, a
+  registered font, and the bracket in your frame. The payment buys every *next* piece of
+  interface — the second panel is also one line, the score label is one line, the menu
+  is a struct — and the layout arithmetic, wrapping, and stacking are clay's problem
+  from then on.
+
+Neither is deprecated. The library's own position: build one panel by hand; build an
+interface on the subsystem.
+
+## Menus: one selection, three devices
+
+A menu is caller-owned state — a struct you keep, the way `textbox.c` keeps its statics.
+There is no heap pool behind it because it owns no texture, no font, and no registry
+entry:
+
+```c excerpt=examples/uidemo/uidemo.c
+static akgl_UiMenu title_menu = {
+    .id = "title",
+    .items = { "Start", "Options", "Quit" },
+    .count = 3,
+};
+```
+
+Declaring it each frame is `akgl_ui_menu(&title_menu)`. Input reaches it two ways, and
+they meet in the same struct: `akgl_ui_menu_handle_event` moves `selected` from the
+arrow keys and D-pad (wrapping at both ends) and sets `activated` on Return or gamepad
+South — exactly `SDLK_UP`, `SDLK_DOWN` and `SDLK_RETURN` against `SDL_Event.key.key`,
+and `SDL_GAMEPAD_BUTTON_DPAD_UP`, `_DPAD_DOWN` and `_SOUTH` against
+`SDL_Event.gbutton.button`. Keycodes, not scancodes — which only matters when you
+*synthesize* events, as the demo's `--demo` script does: a hand-built key event must
+fill in `key.key`, or it matches nothing and the menu silently ignores it. The mouse
+selects by *moving onto* a row and activates by clicking one, during the declaration
+itself. A stationary pointer claims nothing — parking the mouse over the
+menu must not pin the selection against the keyboard, which would otherwise fight it
+sixty times a second and lose.
+
+`activated` latches until you clear it, so the check lives wherever reading it is
+convenient — the demo reads it after the frame closes, which catches both input routes:
+
+```c excerpt=examples/uidemo/uidemo.c
+    if ( title_menu.activated ) {
+	title_menu.activated = false;
+	switch ( title_menu.selected ) {
+	case 0:
+	    state = UIDEMO_STATE_PLAY;
+	    score = 0;
+	    dialog_open = false;
+	    break;
+	case 1:
+	    state = UIDEMO_STATE_OPTIONS;
+	    break;
+	case 2:
+	default:
+	    running = false;
+	    break;
+	}
+    }
+```
+
+## Writing layout directly with CLAY()
+
+The options screen uses no widgets, and exists to show that the widgets are a
+convenience rather than a boundary. One row of it carries every idea — hover styling
+computed *inside* the declaration, and a click paired with a press edge the application
+tracks itself:
+
+```c excerpt=examples/uidemo/uidemo.c
+	CLAY({
+		.id = CLAY_ID("options-music"),
+		.layout = { .padding = { 8, 8, 4, 4 } },
+		.backgroundColor = Clay_Hovered()
+		? (Clay_Color){ 64, 58, 88, 255 }
+		: (Clay_Color){ 0, 0, 0, 0 }
+	    }) {
+	    if ( Clay_Hovered() && clicked ) {
+		opt_music = !opt_music;
+	    }
+	    CLAY_TEXT(((Clay_String){ .length = (int32_t)strlen(musicrow), .chars = musicrow }),
+		      CLAY_TEXT_CONFIG({ .textColor = { 240, 236, 214, 255 }, .fontId = 0 }));
+	}
+```
+
+`clicked` is one application-owned `bool`: set when a left press arrives in the event
+loop — *before* `akgl_ui_handle_event` can consume it, because a click on a UI row is
+always consumed — and cleared at the end of the frame. The widgets keep an equivalent
+edge internally; a raw screen keeps its own. Everything else — the sizing model, scroll
+containers, floating attach points, aspect ratios — is clay's DSL, and clay's README
+documents it far better than a restatement here would.
+
+## Images and styles
+
+An image on a UI element is a sprite: set `.image.imageData` in a `CLAY()` declaration
+to an `akgl_Sprite *` ([Chapter 10](10-spritesheets-and-sprites.md)) and its first frame
+is drawn stretched to the element's box. Two current limits, both deliberate scope
+rather than accident: clay's image tint colour and `CUSTOM` render commands are skipped
+by the executor, and per-corner radii collapse to the top-left value — the widgets only
+produce uniform corners. The mouse cursor stays the operating system's; a game that
+wants a themed cursor draws a floating image element at the pointer, which makes a good
+exercise.
+
+A style is one struct shared by all three widgets — colours, padding, corner radius,
+fontId — and `NULL` means the textbox palette described above. There is no per-field
+defaulting: a transparent fill and a zero radius are things a style legitimately says,
+so copy the default and change what you mean to change:
+
+```c wrap=akglbody
+akgl_UiStyle alert = {
+    .fill = { 120, 24, 24, 235 },
+    .edge = { 240, 236, 214, 255 },
+    .ink  = { 240, 236, 214, 255 },
+    .padding = 8.0f,
+    .corner_radius = 6.0f,
+    .fontid = 0
+};
+
+PASS(errctx, akgl_ui_dialog("alert", "The reactor is on fire.", &alert));
+```
+
+## When things go wrong
+
+Everything here reports through the ordinary error protocol
+([Chapter 4](04-errors.md)) under one status, `AKGL_ERR_UI`, and the message says which
+refusal it was. Lifecycle misuse fails at the call that misused it:
+
+```text
+/home/andrew/source/libakgl/src/ui.c:ui_widget_ready:850: 262 (UI Error) : Widgets are declared between akgl_ui_frame_begin and akgl_ui_frame_end
+/home/andrew/source/libakgl/src/ui.c:akgl_ui_dialog:866
+/home/andrew/source/libakgl/main.c:main:13
+/home/andrew/source/libakgl/main.c:main:16: Unhandled Error 262 (UI Error): Widgets are declared between akgl_ui_frame_begin and akgl_ui_frame_end
+```
+
+Errors *inside the layout* cannot fail at the call that caused them, because clay
+reports through a void callback with libakgl nowhere on the stack. So they are logged as
+they happen, stashed, and raised from `akgl_ui_frame_end` — the earliest point the
+protocol can carry them — with the first message and a count of the rest. A frame that
+fails is one bad frame: the next `akgl_ui_frame_begin` is legal, and the executor clears
+any clip rectangle on its way out so a failed UI cannot leave the next frame's *world*
+clipped.
+
+The ceilings — elements, measured words, arena bytes, fonts, text-run length, menu
+entries — are all in [Chapter 23](23-appendix-limits.md), every one of them overridable,
+and every refusal names the number to raise.
+
+## Build it and run it
+
+The demo builds with the library:
+
+```sh norun
+cmake -S . -B build
+cmake --build build -j$(nproc)
+./build/examples/uidemo/uidemo
+```
+
+Arrow keys, Return, the D-pad and the mouse all drive the title menu; Space opens the
+dialog on the play screen; Escape backs out. `ctest -R example_uidemo` runs the same
+program headless through a scripted tour of every screen.
+
+## Where to look next
+
+- [clay's README](https://github.com/nicbarker/clay) — the layout DSL itself: sizing,
+  floating elements, scroll containers, and the debug tools.
+- [Chapter 16](16-input.md) — the control maps that own the keyboard and gamepad once
+  the UI has declined an event.
+- [Chapter 17](17-text-and-fonts.md) — fonts, the registry, and what text costs per
+  frame; a UI panel of text pays the same immediate-mode price.
+- [Chapter 21](21-tutorial-jrpg.md) — the hand-rolled text box this chapter keeps
+  comparing against, in the game that earns it.
+- [Chapter 23](23-appendix-limits.md) — every `AKGL_UI_*` limit and the `ui.h` status
+  cross-reference.
--- a/docs/23-appendix-limits.md
+++ b/docs/23-appendix-limits.md
@@ -1,4 +1,4 @@
-# 22. Appendix: limits, statuses and properties
+# 23. Appendix: limits, statuses and properties

 Three reference tables that no single chapter owns: which function raises which status,
 every compile-time bound, and every configuration property the library reads.
@@ -148,6 +148,9 @@ What the statuses mean is [Chapter 4](04-errors.md).
 | `akgl_draw_circle` | `AKERR_NULLPOINTER`, `AKERR_OUTOFBOUNDS`, `AKGL_ERR_SDL` |
 | `akgl_draw_flood_fill` | `AKERR_NULLPOINTER`, `AKGL_ERR_SDL`, `AKERR_OUTOFBOUNDS` past `AKGL_DRAW_MAX_FLOOD_SPANS` |
 | `akgl_draw_copy_region`, `_paste_region` | `AKERR_NULLPOINTER`, `AKGL_ERR_SDL` |
+| `akgl_draw_filled_rounded_rect` | `AKERR_NULLPOINTER`, `AKGL_ERR_SDL` |
+| `akgl_draw_arc` | `AKERR_NULLPOINTER`, `AKERR_OUTOFBOUNDS`, `AKGL_ERR_SDL` |
+| `akgl_draw_set_clip` | `AKERR_NULLPOINTER`, `AKGL_ERR_SDL` — a `NULL` rectangle is legal here and clears the clip |

 ### `tilemap.h`

@@ -176,6 +179,22 @@ What the statuses mean is [Chapter 4](04-errors.md).
 | `akgl_controller_default` | `AKERR_OUTOFBOUNDS`, **`AKGL_ERR_REGISTRY`** — the library's only site |
 | `akgl_controller_poll_key`, `_poll_keystroke` | `AKERR_NULLPOINTER` |

+### `ui.h`
+
+| Function | Raises |
+|---|---|
+| `akgl_ui_init` | `AKERR_OUTOFBOUNDS`, `AKGL_ERR_UI` — already initialized, or an arena clay's structures do not fit; the message carries both byte counts |
+| `akgl_ui_shutdown` | *nothing — idempotent by design* |
+| `akgl_ui_resize` | `AKGL_ERR_UI`, `AKERR_OUTOFBOUNDS` |
+| `akgl_ui_font_register` | `AKERR_NULLPOINTER`, `AKGL_ERR_UI`, `AKERR_OUTOFBOUNDS` past `AKGL_UI_FONT_NAME_LENGTH` |
+| `akgl_ui_handle_event` | `AKERR_NULLPOINTER`, `AKERR_OUTOFBOUNDS` from a resize event |
+| `akgl_ui_frame_begin` | `AKGL_ERR_UI` — uninitialized, or a frame already open |
+| `akgl_ui_frame_end` | `AKERR_NULLPOINTER`, `AKGL_ERR_UI` — no frame open, clay layout errors, an over-long text run, an unresolvable fontId — plus whatever the draw primitives raise |
+| `akgl_ui_dialog`, `_label`, `_menu` | `AKERR_NULLPOINTER`, `AKGL_ERR_UI` outside the frame bracket; `_label` and `_menu` add `AKERR_OUTOFBOUNDS` |
+| `akgl_ui_menu_handle_event` | `AKERR_NULLPOINTER`, `AKERR_OUTOFBOUNDS` |
+| `akgl_ui_execute_commands` | `AKERR_NULLPOINTER`, `AKGL_ERR_UI`, plus whatever the draw primitives raise |
+| `akgl_ui_measure_text` | *cannot report — clay's callback signature; failures stash and surface from `akgl_ui_frame_end`* |
+
 ### `text.h`, `audio.h`, `assets.h`, `util.h`, `staticstring.h`

 | Function | Raises |
@@ -196,8 +215,9 @@ What the statuses mean is [Chapter 4](04-errors.md).

 ## B. Compile-time limits

-Everything below is fixed when the library is compiled. **Only the `AKGL_MAX_HEAP_*` eight
-and `AKGL_CCD_ARENA_BYTES` are overridable**, and even those have to be overridden for the whole build — see
+Everything below is fixed when the library is compiled. **Only the `AKGL_MAX_HEAP_*` eight,
+`AKGL_CCD_ARENA_BYTES` and the `AKGL_UI_*` family are overridable**, and even those have to
+be overridden for the whole build — see
 [Chapter 5](05-the-heap.md), "The ceilings are a compile-time ABI constraint". The rest are
 plain `#define`s with no `#ifndef` guard: changing one means editing the header and
 rebuilding libakgl and everything linking it.
@@ -347,6 +367,31 @@ keeps instead of recursing per pixel. A region needing more pending runs at once
 `AKERR_OUTOFBOUNDS` rather than overflowing; an ordinary convex or moderately concave shape
 needs a few dozen.

+`AKGL_DRAW_ROUNDED_RECT_SEGMENTS` is 16 — triangles per corner of
+`akgl_draw_filled_rounded_rect`. `AKGL_DRAW_ARC_MAX_POINTS` is 64 — the vertex ceiling one
+`akgl_draw_arc` spends, two per step along the curve; the step count scales with the swept
+angle under it. Both size fixed arrays, so neither is a per-call cost and neither is
+overridable.
+
+### The UI
+
+Every `AKGL_UI_*` limit is guarded by `#ifndef`, so a consumer may override any of them the
+way the pool ceilings are overridden — for the whole build, before `<akgl/ui.h>` is seen.
+`akgl_ui_init` checks that the arena still fits the element and word ceilings and refuses
+with both byte counts in the message when it does not, so a raised ceiling without a raised
+arena is a loud startup failure rather than a corruption.
+
+| Constant | Value | Bounds |
+|---|---|---|
+| `AKGL_UI_MAX_ELEMENTS` | 1024 | Elements one layout may declare |
+| `AKGL_UI_MAX_MEASURE_WORDS` | 4096 | Words clay's text-measurement cache holds |
+| `AKGL_UI_ARENA_BYTES` | 1048576 | Static storage clay lays its structures out in (812544 needed at the defaults) |
+| `AKGL_UI_MAX_FONTS` | 8 | fontId table slots |
+| `AKGL_UI_FONT_NAME_LENGTH` | 64 | Bytes per fontId slot's registry name, terminator included |
+| `AKGL_UI_MAX_TEXT_BYTES` | 1024 | Bytes one text render command's line may occupy |
+| `AKGL_UI_MENU_MAX_ITEMS` | 16 | Entries one `akgl_UiMenu` may carry |
+| `AKGL_UI_DIALOG_HEIGHT` | 56 | Height of the `akgl_ui_dialog` panel, in pixels |
+
 ### Audio

 ```c excerpt=include/akgl/audio.h
@@ -383,8 +428,8 @@ budget and was wrong by a factor of a thousand, blocking for roughly sixteen min
 | Constant | Value |
 |---|---|
 | `AKGL_ERR_BASE` | 256 (`AKERR_FIRST_CONSUMER_STATUS`) |
-| `AKGL_ERR_COUNT` | 5 |
-| `AKGL_ERR_LIMIT` | 261 — **the one-past-the-end sentinel, not a status** |
+| `AKGL_ERR_COUNT` | 7 |
+| `AKGL_ERR_LIMIT` | 263 — **the one-past-the-end sentinel, not a status** |

 ## C. Configuration properties

--- a/docs/README.md
+++ b/docs/README.md
@@ -34,7 +34,8 @@ per-function reference, build the Doxygen output with `doxygen Doxyfile`.
 | **[19. Utilities](19-utilities.md)** | Rectangle overlap, path resolution, the JSON accessors, static strings |
 | **[20. Tutorial: a 2D sidescroller](20-tutorial-sidescroller.md)** | Thirteen steps from an empty directory to a game with gravity, a jump, coins and hazards. **Start here** |
 | **[21. Tutorial: a top-down JRPG](21-tutorial-jrpg.md)** | Thirteen more, for four-way movement, NPCs, a text box, a follower, and freezing the world |
-| **[22. Appendix](22-appendix-limits.md)** | Every limit, every status, every configuration property |
+| **[22. User interfaces](22-ui.md)** | Menus, HUDs and dialogs on the clay layout engine: the widgets, the frame bracket, and writing `CLAY()` yourself |
+| **[23. Appendix](23-appendix-limits.md)** | Every limit, every status, every configuration property |

 **If you are new, read chapter 20 first and read it in order.** It builds a working game from
 an empty directory and teaches the library as it needs each piece; chapter 21 assumes it.
--- a/docs/images/uidemo.png
+++ b/docs/images/uidemo.png
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -1,4 +1,4 @@
-# The two tutorial games.
+# The tutorial games and demos.
 #
 # Each one is a complete, running program that the matching chapter quotes with
 # `c excerpt=examples/...` blocks rather than restating -- so a tutorial cannot
@@ -9,7 +9,7 @@
 # passes and land at different times, and a configure that fails because one of
 # them is not there yet would block the other. There is nothing clever about the
 # guard; it exists so an incomplete tree still builds.
-foreach(_example sidescroller jrpg)
+foreach(_example sidescroller jrpg uidemo)
  if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${_example}/CMakeLists.txt")
    add_subdirectory(${_example})
  endif()
--- a/examples/jrpg/CMakeLists.txt
+++ b/examples/jrpg/CMakeLists.txt
@@ -47,26 +47,31 @@ endif()
 # it to suppress the vendored projects' registrations and lifts the suppression
 # again long before examples/ is added.
 add_test(NAME example_jrpg COMMAND jrpg --frames 320 --demo)
-set_tests_properties(example_jrpg PROPERTIES
-  TIMEOUT 120
-  ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_RENDER_DRIVER=software;SDL_AUDIODRIVER=dummy"
+set_tests_properties(example_jrpg PROPERTIES TIMEOUT 120)
+# set_property, not set_tests_properties: the latter parses its PROPERTIES
+# arguments as name/value *pairs*, so a semicolon-separated value is split and
+# every element after the first is consumed as a bogus property name. The
+# audio and render entries of this list were silently lost that way --
+# invisible on any machine whose real audio device works, and found the first
+# time CI ran on a runner without one.
+set_property(TEST example_jrpg PROPERTY ENVIRONMENT
+  "SDL_VIDEODRIVER=dummy"
+  "SDL_RENDER_DRIVER=software"
+  "SDL_AUDIODRIVER=dummy"
 )

-# ENVIRONMENT above replaces the environment wholesale, so LD_LIBRARY_PATH has
-# to go in the same property rather than a second one. Only needed when the
-# dependencies were vendored; an installed build resolves them normally.
+# LD_LIBRARY_PATH for the vendored satellite libraries. Only needed when they
+# were vendored; an installed build resolves them normally.
 if(AKGL_VENDORED_DEPENDENCIES)
  if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.22")
    set(JRPG_TEST_ENV_MOD "")
    foreach(dir IN LISTS AKGL_TEST_LIBPATH)
      list(APPEND JRPG_TEST_ENV_MOD "LD_LIBRARY_PATH=path_list_prepend:${dir}")
    endforeach()
-    set_tests_properties(example_jrpg
-      PROPERTIES ENVIRONMENT_MODIFICATION "${JRPG_TEST_ENV_MOD}")
+    set_property(TEST example_jrpg PROPERTY ENVIRONMENT_MODIFICATION ${JRPG_TEST_ENV_MOD})
  else()
    string(REPLACE ";" ":" JRPG_TEST_LIBPATH_JOINED "${AKGL_TEST_LIBPATH}")
-    set_tests_properties(example_jrpg PROPERTIES
-      ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_RENDER_DRIVER=software;SDL_AUDIODRIVER=dummy;LD_LIBRARY_PATH=${JRPG_TEST_LIBPATH_JOINED}:$ENV{LD_LIBRARY_PATH}"
-    )
+    set_property(TEST example_jrpg APPEND PROPERTY ENVIRONMENT
+      "LD_LIBRARY_PATH=${JRPG_TEST_LIBPATH_JOINED}:$ENV{LD_LIBRARY_PATH}")
  endif()
 endif()
--- a/examples/sidescroller/CMakeLists.txt
+++ b/examples/sidescroller/CMakeLists.txt
@@ -41,7 +41,15 @@ endif()
 # while this project is top-level, and by the time examples/ is added the
 # suppression has already been lifted. An embedded build gets the builtin.
 add_test(NAME example_sidescroller COMMAND sidescroller --frames 240 --autoplay)
-set_tests_properties(example_sidescroller PROPERTIES
-  TIMEOUT 120
-  ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_RENDER_DRIVER=software;SDL_AUDIODRIVER=dummy"
+set_tests_properties(example_sidescroller PROPERTIES TIMEOUT 120)
+# set_property, not set_tests_properties: the latter parses its PROPERTIES
+# arguments as name/value *pairs*, so a semicolon-separated value is split and
+# every element after the first is consumed as a bogus property name. The
+# audio and render entries of this very list were silently lost that way for
+# as long as the list existed -- invisible on any machine whose real audio
+# device works, and found the first time CI ran on a runner without one.
+set_property(TEST example_sidescroller PROPERTY ENVIRONMENT
+  "SDL_VIDEODRIVER=dummy"
+  "SDL_RENDER_DRIVER=software"
+  "SDL_AUDIODRIVER=dummy"
 )
--- a/examples/uidemo/CMakeLists.txt
+++ b/examples/uidemo/CMakeLists.txt
@@ -0,0 +1,62 @@
+# The UI demo, quoted by the UI chapter's `c excerpt=` blocks.
+#
+# A real target built by `all`, on the same terms as the tutorial games: a
+# chapter whose program does not compile is the failure the documentation
+# harness exists to stop.
+
+add_executable(uidemo
+  uidemo.c
+)
+
+target_link_libraries(uidemo
+  PRIVATE akstdlib::akstdlib akerror::akerror akgl
+          SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image SDL3_mixer::SDL3_mixer
+          jansson::jansson -lm)
+target_include_directories(uidemo PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}")
+target_compile_options(uidemo PRIVATE ${AKGL_WARNING_FLAGS})
+
+# The demo needs no art -- its "world" is akgl_draw_background -- but it does
+# need one font, and it uses the same test-asset face the JRPG does, compiled
+# in as an absolute path for the same run-from-anywhere reason.
+get_filename_component(UIDEMO_REPO_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../.." ABSOLUTE)
+target_compile_definitions(uidemo PRIVATE
+  UIDEMO_FONT_FILE="${UIDEMO_REPO_ROOT}/tests/assets/akgl_test_mono.ttf"
+)
+
+if(AKGL_VENDORED_DEPENDENCIES)
+  set_target_properties(uidemo PROPERTIES BUILD_RPATH "${AKGL_VENDORED_RPATH}")
+endif()
+
+# The headless smoke run. `--demo` tours every screen through the real event
+# chain -- a mouse click on the title menu (the consumed path), keyboard into
+# and out of the raw-CLAY options screen, the play screen's dialog opened and
+# dismissed, and Quit confirmed from the menu -- rather than just proving that
+# main() returns. There is no physics here, so nothing needs a driven clock;
+# `--frames` is a backstop above the script's last step, not the exit path.
+add_test(NAME example_uidemo COMMAND uidemo --frames 240 --demo)
+set_tests_properties(example_uidemo PROPERTIES TIMEOUT 120)
+# set_property, not set_tests_properties: the latter parses its PROPERTIES
+# arguments as name/value *pairs*, so a semicolon-separated value is split and
+# every element after the first is consumed as a bogus property name. See the
+# same note in the other examples' CMakeLists.
+set_property(TEST example_uidemo PROPERTY ENVIRONMENT
+  "SDL_VIDEODRIVER=dummy"
+  "SDL_RENDER_DRIVER=software"
+  "SDL_AUDIODRIVER=dummy"
+)
+
+# LD_LIBRARY_PATH for the vendored satellite libraries. Only needed when they
+# were vendored; an installed build resolves them normally.
+if(AKGL_VENDORED_DEPENDENCIES)
+  if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.22")
+    set(UIDEMO_TEST_ENV_MOD "")
+    foreach(dir IN LISTS AKGL_TEST_LIBPATH)
+      list(APPEND UIDEMO_TEST_ENV_MOD "LD_LIBRARY_PATH=path_list_prepend:${dir}")
+    endforeach()
+    set_property(TEST example_uidemo PROPERTY ENVIRONMENT_MODIFICATION ${UIDEMO_TEST_ENV_MOD})
+  else()
+    string(REPLACE ";" ":" UIDEMO_TEST_LIBPATH_JOINED "${AKGL_TEST_LIBPATH}")
+    set_property(TEST example_uidemo APPEND PROPERTY ENVIRONMENT
+      "LD_LIBRARY_PATH=${UIDEMO_TEST_LIBPATH_JOINED}:$ENV{LD_LIBRARY_PATH}")
+  endif()
+endif()
--- a/examples/uidemo/uidemo.c
+++ b/examples/uidemo/uidemo.c
@@ -0,0 +1,609 @@
+/**
+ * @file uidemo.c
+ * @brief The UI demo: a title menu, an options screen, and a HUD, three ways.
+ *
+ * The chapter on the UI subsystem quotes this program rather than restating
+ * it. Run it with no arguments for a window:
+ *
+ *     ./examples/uidemo/uidemo
+ *
+ * The title menu answers to the arrow keys, Return, the D-pad, and the mouse.
+ * Start opens a stand-in play screen -- a checkerboard where a game would be
+ * -- with a score counter ticking in a HUD label; Space opens and closes a
+ * dialog panel there, and Escape backs out. Options is a screen written in
+ * raw CLAY() declarations, because the widgets are a convenience, not a
+ * boundary. `--frames N` bounds the run and `--demo` drives the whole tour
+ * from a script, which is what makes this runnable as a headless smoke test.
+ *
+ * What is deliberately absent: a tilemap, actors, physics. The world here is
+ * one draw call, so everything left is the subject -- what a UI costs and
+ * where it goes in a frame.
+ */
+
+#include <stdbool.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+#include <SDL3_image/SDL_image.h>
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/draw.h>
+#include <akgl/error.h>
+#include <akgl/game.h>
+#include <akgl/registry.h>
+#include <akgl/renderer.h>
+#include <akgl/text.h>
+#include <akgl/ui.h>
+
+#include "uidemo.h"
+
+/** @brief Milliseconds one 60 Hz frame is allowed to take, for the interactive loop. */
+#define UIDEMO_FRAME_BUDGET_MS 16
+
+/*
+ * The scripted tour `--demo` drives. Every route through the demo, by every
+ * input device it supports: the mouse clicks the title menu open (dead centre
+ * lands on the middle row by symmetry -- the menu is centred and Options is
+ * its middle entry), the keyboard walks back out, into the play screen,
+ * through the dialog, and finally down to Quit.
+ *
+ *  Frame   Event                        Key / position    What it proves
+ */
+static const uidemo_ScriptStep UIDEMO_SCRIPT[] = {
+    {   5,  SDL_EVENT_MOUSE_MOTION,      0,           320.0f, 240.0f },  /* hover the menu     */
+    {  10,  SDL_EVENT_MOUSE_BUTTON_DOWN, 0,           320.0f, 240.0f },  /* consumed click     */
+    {  11,  SDL_EVENT_MOUSE_BUTTON_UP,   0,           320.0f, 240.0f },  /* -> Options screen  */
+    {  40,  SDL_EVENT_KEY_DOWN,          SDLK_ESCAPE, 0.0f,   0.0f   },  /* back to the title  */
+    {  50,  SDL_EVENT_KEY_DOWN,          SDLK_UP,     0.0f,   0.0f   },  /* select Start       */
+    {  60,  SDL_EVENT_KEY_DOWN,          SDLK_RETURN, 0.0f,   0.0f   },  /* -> play screen     */
+    {  80,  SDL_EVENT_KEY_DOWN,          SDLK_SPACE,  0.0f,   0.0f   },  /* open the dialog    */
+    { 120,  SDL_EVENT_KEY_DOWN,          SDLK_SPACE,  0.0f,   0.0f   },  /* close it again     */
+    { 140,  SDL_EVENT_KEY_DOWN,          SDLK_ESCAPE, 0.0f,   0.0f   },  /* back to the title  */
+    { 150,  SDL_EVENT_KEY_DOWN,          SDLK_DOWN,   0.0f,   0.0f   },  /* down to Options    */
+    { 160,  SDL_EVENT_KEY_DOWN,          SDLK_DOWN,   0.0f,   0.0f   },  /* down to Quit       */
+    { 170,  SDL_EVENT_KEY_DOWN,          SDLK_RETURN, 0.0f,   0.0f   }   /* and out            */
+};
+
+#define UIDEMO_SCRIPT_STEPS (sizeof(UIDEMO_SCRIPT) / sizeof(UIDEMO_SCRIPT[0]))
+
+static long frame_limit = 0;
+/** @brief Where `--screenshot` writes, and on which frame. NULL means never. */
+static char *shotpath = NULL;
+static long shotframe = 0;
+static bool demo = false;
+static bool running = true;
+static int exitstatus = 0;
+static bool lowfps_warned = false;
+
+/** @brief Which screen the frame declares. */
+static uidemo_State state = UIDEMO_STATE_TITLE;
+
+/**
+ * @brief The title menu. Caller-owned state, zero machinery: this struct and
+ * the akgl_ui_menu call each frame are the whole main menu.
+ */
+static akgl_UiMenu title_menu = {
+    .id = "title",
+    .items = { "Start", "Options", "Quit" },
+    .count = 3,
+};
+
+/** @brief The options screen's two settings. What the toggles flip. */
+static bool opt_music = true;
+static bool opt_sound = true;
+
+/** @brief The play screen's HUD numbers. The score ticks so the label visibly updates. */
+static int score = 0;
+static int lives = 3;
+/** @brief Whether the play screen's dialog is up. Space flips it. */
+static bool dialog_open = false;
+
+/**
+ * @brief A left click arrived this frame, wherever it landed.
+ *
+ * The raw CLAY() options screen needs a press edge to pair with
+ * Clay_Hovered(), and the application is the right owner of it: it sees
+ * every event before the UI does. Set in route_event, cleared at the end of
+ * each frame. The widget helpers keep their own edge internally -- this one
+ * exists precisely because the options screen does not use them.
+ */
+static bool clicked = false;
+
+/** @brief Replacement `akgl_game.lowfpsfunc`: say it once, not sixty times a second. */
+static void lowfps_quiet(void)
+{
+    if ( lowfps_warned == false ) {
+	lowfps_warned = true;
+	SDL_Log("Frame rate is under 30 and this demo does nothing about it");
+    }
+}
+
+/**
+ * @brief Read `--frames N`, `--demo` and the screenshot flags off the command line.
+ *
+ * @param argc Argument count, from `main`.
+ * @param argv Argument vector, from `main`. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p argv is `NULL`.
+ * @throws AKERR_VALUE If a flag needing an argument is last, or its argument
+ *         is not a number.
+ */
+static akerr_ErrorContext *parse_args(int argc, char *argv[])
+{
+    PREPARE_ERROR(errctx);
+    int i = 0;
+    int number = 0;
+
+    FAIL_ZERO_RETURN(errctx, argv, AKERR_NULLPOINTER, "argv");
+
+    for ( i = 1; i < argc; i++ ) {
+	if ( strcmp(argv[i], "--demo") == 0 ) {
+	    demo = true;
+	} else if ( strcmp(argv[i], "--frames") == 0 ) {
+	    if ( (i + 1) >= argc ) {
+		FAIL_RETURN(errctx, AKERR_VALUE, "--frames needs a frame count");
+	    }
+	    i += 1;
+	    PASS(errctx, aksl_atoi(argv[i], &number));
+	    frame_limit = number;
+	} else if ( strcmp(argv[i], "--screenshot") == 0 ) {
+	    if ( (i + 1) >= argc ) {
+		FAIL_RETURN(errctx, AKERR_VALUE, "--screenshot needs a path");
+	    }
+	    i += 1;
+	    shotpath = argv[i];
+	} else if ( strcmp(argv[i], "--screenshot-frame") == 0 ) {
+	    if ( (i + 1) >= argc ) {
+		FAIL_RETURN(errctx, AKERR_VALUE, "--screenshot-frame needs a number");
+	    }
+	    i += 1;
+	    PASS(errctx, aksl_atoi(argv[i], &number));
+	    shotframe = number;
+	} else {
+	    FAIL_RETURN(errctx, AKERR_VALUE,
+			"usage: uidemo [--frames N] [--demo]"
+			" [--screenshot PATH] [--screenshot-frame N]");
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Bring the library and the UI subsystem up.
+ *
+ * The UI half is three calls: load a font, akgl_ui_init at the screen size,
+ * and register the font for a clay fontId. The id comes back 0 because it is
+ * the first registered, which is what the widgets' default style uses -- so
+ * nothing here ever mentions a fontId again.
+ *
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *startup(void)
+{
+    PREPARE_ERROR(errctx);
+    uint16_t fontid = 0;
+
+    PASS(errctx, aksl_strncpy(akgl_game.name, sizeof(akgl_game.name), "libakgl UI demo", sizeof(akgl_game.name) - 1));
+    PASS(errctx, aksl_strncpy(akgl_game.version, sizeof(akgl_game.version), "1.0.0", sizeof(akgl_game.version) - 1));
+    PASS(errctx, aksl_strncpy(akgl_game.uri, sizeof(akgl_game.uri), "net.aklabs.libakgl.examples.uidemo", sizeof(akgl_game.uri) - 1));
+
+    PASS(errctx, akgl_game_init());
+    akgl_game.lowfpsfunc = &lowfps_quiet;
+
+    PASS(errctx, akgl_set_property("game.screenwidth", UIDEMO_SCREEN_WIDTH));
+    PASS(errctx, akgl_set_property("game.screenheight", UIDEMO_SCREEN_HEIGHT));
+    PASS(errctx, akgl_render_2d_init(akgl_renderer));
+
+    PASS(errctx, akgl_text_loadfont(UIDEMO_FONT_NAME, UIDEMO_FONT_FILE, UIDEMO_FONT_SIZE));
+    PASS(errctx, akgl_ui_init(UIDEMO_WIDTH, UIDEMO_HEIGHT));
+    PASS(errctx, akgl_ui_font_register(UIDEMO_FONT_NAME, &fontid));
+
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Route one event: the UI first, then whatever the current screen wants.
+ *
+ * This is the call-order contract from akgl/ui.h in the flesh. The UI gets
+ * first refusal; a consumed event goes no further, which is what keeps a
+ * click on a menu from also being a click in the game. Only then does the
+ * current screen read the keyboard -- and *that* routing is the whole focus
+ * model: the title menu hears keys because this function sends them there
+ * while the title screen is up, not because anything owns "focus".
+ *
+ * @param event The event to route. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *route_event(SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    bool consumed = false;
+
+    FAIL_ZERO_RETURN(errctx, event, AKERR_NULLPOINTER, "event");
+
+    if ( event->type == SDL_EVENT_QUIT ) {
+	running = false;
+	SUCCEED_RETURN(errctx);
+    }
+    // The options screen's press edge, recorded before the UI can consume
+    // the event -- a click on a toggle row is *always* consumed (the row is
+    // UI), so waiting until afterwards would record nothing.
+    if ( (event->type == SDL_EVENT_MOUSE_BUTTON_DOWN)
+	 && (event->button.button == SDL_BUTTON_LEFT) ) {
+	clicked = true;
+    }
+
+    PASS(errctx, akgl_ui_handle_event((void *)&akgl_game.state, event, &consumed));
+    if ( consumed ) {
+	SUCCEED_RETURN(errctx);
+    }
+
+    switch ( state ) {
+    case UIDEMO_STATE_TITLE:
+	PASS(errctx, akgl_ui_menu_handle_event(&title_menu, event, &consumed));
+	break;
+    case UIDEMO_STATE_OPTIONS:
+	if ( (event->type == SDL_EVENT_KEY_DOWN) && (event->key.key == SDLK_ESCAPE) ) {
+	    state = UIDEMO_STATE_TITLE;
+	}
+	break;
+    case UIDEMO_STATE_PLAY:
+	if ( event->type == SDL_EVENT_KEY_DOWN ) {
+	    if ( event->key.key == SDLK_ESCAPE ) {
+		state = UIDEMO_STATE_TITLE;
+	    } else if ( event->key.key == SDLK_SPACE ) {
+		dialog_open = !dialog_open;
+	    }
+	}
+	break;
+    default:
+	break;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Feed the scripted events due on this frame through the real routing.
+ *
+ * Synthesized SDL_Events, not direct state changes: the demo run proves the
+ * event chain -- consumed and not, menu and screen -- because it travels it.
+ *
+ * @param frameno The frame about to be drawn.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *demo_step(long frameno)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Event event;
+    size_t i = 0;
+
+    for ( i = 0; i < UIDEMO_SCRIPT_STEPS; i++ ) {
+	if ( UIDEMO_SCRIPT[i].frame != frameno ) {
+	    continue;
+	}
+	PASS(errctx, aksl_memset((void *)&event, 0x00, sizeof(event)));
+	event.type = UIDEMO_SCRIPT[i].type;
+	switch ( UIDEMO_SCRIPT[i].type ) {
+	case SDL_EVENT_KEY_DOWN:
+	    event.key.key = UIDEMO_SCRIPT[i].key;
+	    break;
+	case SDL_EVENT_MOUSE_MOTION:
+	    event.motion.x = UIDEMO_SCRIPT[i].x;
+	    event.motion.y = UIDEMO_SCRIPT[i].y;
+	    break;
+	case SDL_EVENT_MOUSE_BUTTON_DOWN:
+	case SDL_EVENT_MOUSE_BUTTON_UP:
+	    event.button.button = SDL_BUTTON_LEFT;
+	    event.button.x = UIDEMO_SCRIPT[i].x;
+	    event.button.y = UIDEMO_SCRIPT[i].y;
+	    break;
+	default:
+	    break;
+	}
+	PASS(errctx, route_event(&event));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Declare the title screen: one widget call.
+ *
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *declare_title(void)
+{
+    PREPARE_ERROR(errctx);
+    PASS(errctx, akgl_ui_label("heading", "libakgl UI demo", AKGL_UI_ANCHOR_TOP_LEFT, NULL));
+    PASS(errctx, akgl_ui_menu(&title_menu));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Declare the options screen in raw CLAY(), no widgets anywhere.
+ *
+ * This screen exists to show the other way in: a centred panel, a column of
+ * rows, hover highlighting via Clay_Hovered() *inside* the declaration, and
+ * clicks paired with the application's own press edge. Everything the widgets
+ * do is done with these same pieces; a screen the widgets cannot express is
+ * written like this rather than waiting for a widget to exist.
+ *
+ * The row labels live in statics because clay borrows the pointer until
+ * frame_end -- a local buffer here would be dangling by the time the text is
+ * drawn.
+ *
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *declare_options(void)
+{
+    PREPARE_ERROR(errctx);
+    static char musicrow[32];
+    static char soundrow[32];
+    int count = 0;
+
+    PASS(errctx, aksl_snprintf(&count, musicrow, sizeof(musicrow), "Music: %s", opt_music ? "ON" : "OFF"));
+    PASS(errctx, aksl_snprintf(&count, soundrow, sizeof(soundrow), "Sound: %s", opt_sound ? "ON" : "OFF"));
+
+    CLAY({
+	    .id = CLAY_ID("options"),
+	    .layout = {
+		.padding = { 16, 16, 16, 16 },
+		.childGap = 8,
+		.layoutDirection = CLAY_TOP_TO_BOTTOM
+	    },
+	    .backgroundColor = { 24, 20, 37, 235 },
+	    .border = { .color = { 240, 236, 214, 255 }, .width = { 1, 1, 1, 1, 0 } },
+	    .floating = {
+		.attachPoints = {
+		    .element = CLAY_ATTACH_POINT_CENTER_CENTER,
+		    .parent = CLAY_ATTACH_POINT_CENTER_CENTER
+		},
+		.attachTo = CLAY_ATTACH_TO_ROOT
+	    }
+	}) {
+	CLAY_TEXT(CLAY_STRING("OPTIONS"), CLAY_TEXT_CONFIG({
+		    .textColor = { 240, 236, 214, 255 },
+		    .fontId = 0
+		}));
+
+	CLAY({
+		.id = CLAY_ID("options-music"),
+		.layout = { .padding = { 8, 8, 4, 4 } },
+		.backgroundColor = Clay_Hovered()
+		? (Clay_Color){ 64, 58, 88, 255 }
+		: (Clay_Color){ 0, 0, 0, 0 }
+	    }) {
+	    if ( Clay_Hovered() && clicked ) {
+		opt_music = !opt_music;
+	    }
+	    CLAY_TEXT(((Clay_String){ .length = (int32_t)strlen(musicrow), .chars = musicrow }),
+		      CLAY_TEXT_CONFIG({ .textColor = { 240, 236, 214, 255 }, .fontId = 0 }));
+	}
+
+	CLAY({
+		.id = CLAY_ID("options-sound"),
+		.layout = { .padding = { 8, 8, 4, 4 } },
+		.backgroundColor = Clay_Hovered()
+		? (Clay_Color){ 64, 58, 88, 255 }
+		: (Clay_Color){ 0, 0, 0, 0 }
+	    }) {
+	    if ( Clay_Hovered() && clicked ) {
+		opt_sound = !opt_sound;
+	    }
+	    CLAY_TEXT(((Clay_String){ .length = (int32_t)strlen(soundrow), .chars = soundrow }),
+		      CLAY_TEXT_CONFIG({ .textColor = { 240, 236, 214, 255 }, .fontId = 0 }));
+	}
+
+	CLAY({
+		.id = CLAY_ID("options-back"),
+		.layout = { .padding = { 8, 8, 4, 4 } },
+		.backgroundColor = Clay_Hovered()
+		? (Clay_Color){ 64, 58, 88, 255 }
+		: (Clay_Color){ 0, 0, 0, 0 }
+	    }) {
+	    if ( Clay_Hovered() && clicked ) {
+		state = UIDEMO_STATE_TITLE;
+	    }
+	    CLAY_TEXT(CLAY_STRING("Back (Esc)"), CLAY_TEXT_CONFIG({
+			.textColor = { 240, 236, 214, 255 },
+			.fontId = 0
+		    }));
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Declare the play screen's HUD: two labels, and the dialog while it is up.
+ *
+ * The score buffer is static for the same borrowed-until-frame_end reason as
+ * the options rows. Note what is *not* here: no visible flag, no draw call,
+ * no geometry. The dialog is open because this frame declares it.
+ *
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *declare_play(void)
+{
+    PREPARE_ERROR(errctx);
+    static char scoretext[32];
+    static char livestext[32];
+    int count = 0;
+
+    PASS(errctx, aksl_snprintf(&count, scoretext, sizeof(scoretext), "SCORE %05d", score));
+    PASS(errctx, aksl_snprintf(&count, livestext, sizeof(livestext), "LIVES %d", lives));
+    PASS(errctx, akgl_ui_label("score", scoretext, AKGL_UI_ANCHOR_TOP_RIGHT, NULL));
+    PASS(errctx, akgl_ui_label("lives", livestext, AKGL_UI_ANCHOR_TOP_LEFT, NULL));
+    if ( dialog_open ) {
+	PASS(errctx, akgl_ui_dialog("dialog",
+				    "This panel is one call. Space dismisses it; "
+				    "compare examples/jrpg/textbox.c.",
+				    NULL));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Read the render target back and write it out as a PNG, for the chapter figure. */
+static akerr_ErrorContext *save_screenshot(char *path)
+{
+    SDL_Surface *shot = NULL;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, path, AKERR_NULLPOINTER, "path");
+
+    shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+    FAIL_ZERO_RETURN(errctx, shot, AKGL_ERR_SDL, "SDL_RenderReadPixels: %s", SDL_GetError());
+
+    ATTEMPT {
+	FAIL_ZERO_BREAK(errctx, IMG_SavePNG(shot, path), AKGL_ERR_SDL,
+			"IMG_SavePNG(%s): %s", path, SDL_GetError());
+    } CLEANUP {
+	SDL_DestroySurface(shot);
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SDL_Log("Wrote %s", path);
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief One frame: events, the world stand-in, the UI bracket, present.
+ *
+ * The shape to compare with the JRPG's frame(): where that program calls
+ * akgl_game_update between frame_start and frame_end, this one paints a
+ * checkerboard -- and the UI bracket sits in the same overlay slot the
+ * hand-rolled textbox draw did.
+ *
+ * @param frameno The frame number, for the demo script.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *frame(long frameno)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Event event;
+
+    while ( SDL_PollEvent(&event) ) {
+	PASS(errctx, route_event(&event));
+    }
+    if ( demo ) {
+	PASS(errctx, demo_step(frameno));
+    }
+
+    PASS(errctx, akgl_renderer->frame_start(akgl_renderer));
+    if ( state == UIDEMO_STATE_PLAY ) {
+	// Where a game would call akgl_game_update. The score ticking is the
+	// stand-in for play, so the HUD label visibly earns its redraw.
+	PASS(errctx, akgl_draw_background(akgl_renderer, UIDEMO_WIDTH, UIDEMO_HEIGHT));
+	score += 1;
+    }
+
+    PASS(errctx, akgl_ui_frame_begin());
+    switch ( state ) {
+    case UIDEMO_STATE_TITLE:
+	PASS(errctx, declare_title());
+	break;
+    case UIDEMO_STATE_OPTIONS:
+	PASS(errctx, declare_options());
+	break;
+    case UIDEMO_STATE_PLAY:
+	PASS(errctx, declare_play());
+	break;
+    default:
+	break;
+    }
+    PASS(errctx, akgl_ui_frame_end(akgl_renderer));
+
+    if ( (shotpath != NULL) && (frameno == shotframe) ) {
+	PASS(errctx, save_screenshot(shotpath));
+    }
+    PASS(errctx, akgl_renderer->frame_end(akgl_renderer));
+
+    // The press edge lives exactly one frame: the declarations above have
+    // seen it, so the next frame starts clean.
+    clicked = false;
+
+    // Menu activation is read after the frame, so it catches both routes in:
+    // Return through akgl_ui_menu_handle_event before the declarations, and a
+    // click through the declaration itself.
+    if ( title_menu.activated ) {
+	title_menu.activated = false;
+	switch ( title_menu.selected ) {
+	case 0:
+	    state = UIDEMO_STATE_PLAY;
+	    score = 0;
+	    dialog_open = false;
+	    break;
+	case 1:
+	    state = UIDEMO_STATE_OPTIONS;
+	    break;
+	case 2:
+	default:
+	    running = false;
+	    break;
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Give back what has to be given back, in the order that works.
+ *
+ * akgl_ui_shutdown first because it is the newest thing up, then the fonts
+ * **before** SDL_Quit -- the registry the fonts live in is an SDL property
+ * set, and SDL_Quit destroys it with them inside. The pools and the clay
+ * arena are static storage; there is nothing to free.
+ */
+static void teardown(void)
+{
+    IGNORE(akgl_ui_shutdown());
+    IGNORE(akgl_text_unloadallfonts());
+    if ( akgl_window != NULL ) {
+	SDL_DestroyWindow(akgl_window);
+	akgl_window = NULL;
+    }
+    SDL_Quit();
+}
+
+int main(int argc, char *argv[])
+{
+    PREPARE_ERROR(errctx);
+    long frameno = 0;
+    uint64_t started = 0;
+    uint64_t spent = 0;
+
+    ATTEMPT {
+	CATCH(errctx, parse_args(argc, argv));
+	CATCH(errctx, startup());
+
+	// The loop is the last thing in this ATTEMPT block on purpose: CATCH
+	// reports failure by `break`ing out of the loop, which falls straight
+	// into CLEANUP. See examples/jrpg/jrpg.c for the long form of this
+	// note.
+	while ( running ) {
+	    started = SDL_GetTicks();
+	    CATCH(errctx, frame(frameno));
+	    frameno += 1;
+	    if ( (frame_limit > 0) && (frameno >= frame_limit) ) {
+		running = false;
+	    }
+	    if ( demo == false ) {
+		spent = SDL_GetTicks() - started;
+		if ( spent < UIDEMO_FRAME_BUDGET_MS ) {
+		    SDL_Delay((uint32_t)(UIDEMO_FRAME_BUDGET_MS - spent));
+		}
+	    }
+	}
+    } CLEANUP {
+	teardown();
+    } PROCESS(errctx) {
+    } HANDLE_DEFAULT(errctx) {
+	LOG_ERROR_WITH_MESSAGE(errctx, "the UI demo could not finish");
+	exitstatus = 1;
+    } FINISH_NORETURN(errctx);
+
+    // Enough for the smoke run to be read rather than merely passed: the
+    // script quits from the title menu, so a run that finished its tour says
+    // so here.
+    printf("uidemo: %ld frames, score %d, music %s, sound %s\n",
+	   frameno, score, opt_music ? "on" : "off", opt_sound ? "on" : "off");
+    return exitstatus;
+}
--- a/examples/uidemo/uidemo.h
+++ b/examples/uidemo/uidemo.h
@@ -0,0 +1,58 @@
+/**
+ * @file uidemo.h
+ * @brief Shared constants and types for the UI demo.
+ *
+ * There is deliberately little here: the demo is one translation unit, and
+ * this header exists so the chapter can quote the constants and the script
+ * type without quoting the code around them.
+ */
+
+#ifndef _UIDEMO_H_
+#define _UIDEMO_H_
+
+#include <SDL3/SDL.h>
+
+/** @brief Window and layout width, in pixels. */
+#define UIDEMO_SCREEN_WIDTH   "640"
+/** @brief Window and layout height, in pixels. */
+#define UIDEMO_SCREEN_HEIGHT  "480"
+/** @brief The same width as a number, for akgl_ui_init. */
+#define UIDEMO_WIDTH          640
+/** @brief The same height as a number. */
+#define UIDEMO_HEIGHT         480
+
+/** @brief Registry name the demo's one font is loaded under. */
+#define UIDEMO_FONT_NAME      "uidemo"
+/** @brief Point size the font is loaded at. The size is baked into the handle. */
+#define UIDEMO_FONT_SIZE      16
+
+/**
+ * @brief Which screen the demo is on.
+ *
+ * Three states, three ways of building an interface: the title screen is the
+ * menu *widget*, the options screen is raw `CLAY()` layout, and the play
+ * screen is the label and dialog widgets over a moving world stand-in.
+ */
+typedef enum {
+    UIDEMO_STATE_TITLE,     /**< The akgl_UiMenu title menu. */
+    UIDEMO_STATE_OPTIONS,   /**< The hand-written CLAY() options panel. */
+    UIDEMO_STATE_PLAY       /**< HUD labels and a dialog over the "game". */
+} uidemo_State;
+
+/**
+ * @brief One scripted input in a `--demo` run.
+ *
+ * Key steps carry a keycode; mouse steps carry a position. Every step is
+ * synthesized as a real SDL_Event and pushed through the same routing the
+ * interactive loop uses, so the demo exercises the event chain rather than
+ * poking state behind its back.
+ */
+typedef struct {
+    long frame;             /**< The frame this step fires on. */
+    uint32_t type;          /**< SDL_EVENT_KEY_DOWN, _MOUSE_MOTION, _MOUSE_BUTTON_DOWN or _MOUSE_BUTTON_UP. */
+    SDL_Keycode key;        /**< For key steps. */
+    float x;                /**< For mouse steps. */
+    float y;                /**< For mouse steps. */
+} uidemo_ScriptStep;
+
+#endif // _UIDEMO_H_
--- a/include/akgl/draw.h
+++ b/include/akgl/draw.h
@@ -36,6 +36,25 @@
 */
 #define AKGL_DRAW_MAX_FLOOD_SPANS 4096

+/**
+ * @brief Triangles each corner of akgl_draw_filled_rounded_rect() is built from.
+ *
+ * A quarter circle approximated by this many segments is visually round at any
+ * radius a UI panel plausibly uses; the vertex arrays are fixed at this size,
+ * so it is a compile-time cost, not a per-call one.
+ */
+#define AKGL_DRAW_ROUNDED_RECT_SEGMENTS 16
+
+/**
+ * @brief Most vertices akgl_draw_arc() will spend on one arc.
+ *
+ * An arc is a triangle strip between its inner and outer edge, two vertices
+ * per step, so half of these are positions along the curve. The step count
+ * scales with the swept angle and is clamped to fit this array -- a full
+ * circle gets all of them, a sliver gets a few -- rather than allocating.
+ */
+#define AKGL_DRAW_ARC_MAX_POINTS 64
+
 /**
 * @brief Paint an 8x8 grey checkerboard over a region, the way an image editor shows transparency.
 *
@@ -242,4 +261,86 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_draw_copy_region(akgl_RenderBackend *sel
 */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_draw_paste_region(akgl_RenderBackend *self, SDL_Surface *src, float32_t x, float32_t y);

+/**
+ * @brief Fill a rectangle whose corners are rounded off with quarter circles.
+ *
+ * The body is three axis-aligned fills and the corners are triangle fans
+ * through `SDL_RenderGeometry` -- #AKGL_DRAW_ROUNDED_RECT_SEGMENTS triangles
+ * each -- so nothing here is anti-aliased, matching every other primitive in
+ * this header.
+ *
+ * @param self   The backend to draw through. Required, along with its
+ *               `sdl_renderer`.
+ * @param rect   The rectangle, in render-target pixels. Required. A zero or
+ *               negative width or height fills nothing and is not reported.
+ * @param radius Corner radius in pixels. Zero or negative falls through to
+ *               akgl_draw_filled_rect() -- a square corner is not an error.
+ *               Larger than half the shorter side is clamped to it, which at
+ *               the limit turns a square into a circle rather than folding the
+ *               corners over each other.
+ * @param color  Colour to fill with, including alpha.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p self, `self->sdl_renderer`, or @p rect is
+ *         `NULL`.
+ * @throws AKGL_ERR_SDL If the draw colour cannot be read or set, or if a band
+ *         or corner cannot be drawn. A failure partway leaves the shape
+ *         partially drawn.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_draw_filled_rounded_rect(akgl_RenderBackend *self, SDL_FRect *rect, float32_t radius, SDL_Color color);
+
+/**
+ * @brief Stroke a circular arc of a given thickness between two angles.
+ *
+ * Angles are in degrees, 0 pointing along +x (three o'clock) and increasing
+ * clockwise on screen -- the same convention as the rotation argument the
+ * render backend's `draw_texture` takes. The stroke runs from the arc's outer
+ * edge at @p radius inward by @p thickness, drawn as one triangle strip, not
+ * anti-aliased.
+ *
+ * @param self      The backend to draw through. Required, along with its
+ *                  `sdl_renderer`.
+ * @param x         Horizontal position of the arc's centre.
+ * @param y         Vertical position of the arc's centre.
+ * @param radius    Outer radius in pixels. Must be positive.
+ * @param start_deg Angle the arc starts at.
+ * @param end_deg   Angle the arc ends at. At or below @p start_deg nothing is
+ *                  drawn and nothing is reported, matching the zero-area
+ *                  rectangle fills above. Neither angle is normalized, so an
+ *                  arc crossing three o'clock is 350 to 370, not 350 to 10; a
+ *                  sweep beyond 360 degrees is clamped to one full turn.
+ * @param thickness Stroke width in pixels, measured inward from @p radius.
+ *                  Must be positive; at or above @p radius the arc becomes a
+ *                  filled wedge to the centre.
+ * @param color     Colour to stroke in, including alpha.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p self or `self->sdl_renderer` is `NULL`.
+ * @throws AKERR_OUTOFBOUNDS If @p radius or @p thickness is not positive. The
+ *         message reports the offending value.
+ * @throws AKGL_ERR_SDL If the strip cannot be drawn.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_draw_arc(akgl_RenderBackend *self, float32_t x, float32_t y, float32_t radius, float32_t start_deg, float32_t end_deg, float32_t thickness, SDL_Color color);
+
+/**
+ * @brief Restrict every subsequent draw to a rectangle of the render target.
+ *
+ * Everything drawn through @p self after this -- primitives here, textures,
+ * text -- is clipped to @p rect until the restriction is cleared. This is the
+ * only entry point in this header where a `NULL` rectangle is legal rather
+ * than an error: it means "clear the restriction", matching what
+ * `SDL_SetRenderClipRect` does with it, and there is no other value that
+ * could.
+ *
+ * The clip is renderer state, not saved and restored around anything: a
+ * caller that sets it owns putting it back, the way a `CLEANUP` block puts
+ * back a draw colour. Leaving it set clips the next frame's world too.
+ *
+ * @param self The backend to clip. Required, along with its `sdl_renderer`.
+ * @param rect Rectangle to clip to, in render-target pixels -- integer, since
+ *             a clip boundary is a pixel boundary. `NULL` clears the clip.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p self or `self->sdl_renderer` is `NULL`.
+ * @throws AKGL_ERR_SDL If the clip cannot be set or cleared.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_draw_set_clip(akgl_RenderBackend *self, SDL_Rect *rect);
+
 #endif //_AKGL_DRAW_H_
--- a/include/akgl/error.h
+++ b/include/akgl/error.h
@@ -76,11 +76,12 @@
 #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 */

 // One past the last libakgl status. The reservation is all-or-nothing -- a
 // subset or superset of an existing one is refused -- so this must stay one
 // past the highest code above.
-#define AKGL_ERR_LIMIT             (AKGL_ERR_BASE + 6)
+#define AKGL_ERR_LIMIT             (AKGL_ERR_BASE + 7)
 #define AKGL_ERR_COUNT             (AKGL_ERR_LIMIT - AKGL_ERR_BASE)

 /**
--- a/include/akgl/ui.h
+++ b/include/akgl/ui.h
@@ -0,0 +1,552 @@
+/**
+ * @file ui.h
+ * @brief Screen-space user interface layouts, built on the clay layout engine.
+ *
+ * This subsystem exists because every game eventually wants a dialog box, a
+ * HUD counter, or a menu, and hand-rolling them out of rectangles and
+ * akgl_text_rendertextat() is tedious the first time and unmaintainable by the
+ * fourth (`examples/jrpg/textbox.c` is the honest record of the first time).
+ * clay computes the layout; libakgl owns everything that has to touch SDL or
+ * the rest of the library -- the arena clay allocates from, the text
+ * measurement it calls back into, the render commands it emits, and the
+ * pointer state it is fed.
+ *
+ * There are two ways in, and they compose:
+ *
+ *   - Write clay's declarative `CLAY({...}) { ... }` blocks yourself between
+ *     akgl_ui_frame_begin() and akgl_ui_frame_end(). The whole of clay's API
+ *     is available -- this header includes `<clay.h>` on purpose, the same way
+ *     SDL types appear undisguised elsewhere in this library.
+ *   - Call the widget helpers, which emit those blocks for you.
+ *
+ * The subsystem is optional the way collision is optional: always compiled in,
+ * inert until akgl_ui_init() runs, and costing nothing but static storage
+ * before that.
+ *
+ * @warning libakgl compiles clay into `libakgl.so` (the `CLAY_IMPLEMENTATION`
+ *          translation unit is `src/ui_clay.c`) and exports its symbols,
+ *          because the `CLAY()` macros in *your* translation units expand to
+ *          calls into them. Do not define `CLAY_IMPLEMENTATION` yourself and
+ *          do not link another copy of clay: two definitions of the same
+ *          symbols and the loader picks one silently, which is the exact
+ *          defect AGENTS.md records against an exported `renderer`.
+ */
+
+#ifndef _AKGL_UI_H_
+#define _AKGL_UI_H_
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include <SDL3/SDL.h>
+
+#include <akerror.h>
+#include <clay.h>
+
+#include <akgl/renderer.h>
+#include <akgl/types.h>
+
+/**
+ * @brief Most elements one layout may declare.
+ *
+ * Passed to `Clay_SetMaxElementCount` before the arena is sized, so it is a
+ * compile-time ceiling in the same sense as the `AKGL_MAX_HEAP_*` family:
+ * define it before including this header to raise it, and see
+ * #AKGL_UI_ARENA_BYTES, which must grow with it.
+ */
+#ifndef AKGL_UI_MAX_ELEMENTS
+#define AKGL_UI_MAX_ELEMENTS            1024
+#endif
+
+/**
+ * @brief Most whitespace-separated words clay's text measurement cache holds.
+ *
+ * Clay measures text one word at a time and caches the result; a cache miss
+ * costs one call back into SDL_ttf. This bounds the cache, not the text -- a
+ * layout with more distinct words than this still renders, it just measures
+ * some of them every frame and clay reports the overflow through the error
+ * handler.
+ */
+#ifndef AKGL_UI_MAX_MEASURE_WORDS
+#define AKGL_UI_MAX_MEASURE_WORDS       4096
+#endif
+
+/**
+ * @brief Bytes of static storage clay lays its internal structures out in.
+ *
+ * The arena is a fixed array in `src/ui.c` -- libakgl does not call `malloc`
+ * at runtime, and clay never allocates behind the arena's back. What clay
+ * needs is a function of #AKGL_UI_MAX_ELEMENTS and #AKGL_UI_MAX_MEASURE_WORDS
+ * and is only computable at runtime, so akgl_ui_init() checks
+ * `Clay_MinMemorySize()` against this and refuses with both numbers in the
+ * message when it does not fit. A too-small arena is a loud failure at
+ * startup, never a corruption at frame forty thousand.
+ */
+#ifndef AKGL_UI_ARENA_BYTES
+#define AKGL_UI_ARENA_BYTES             (1024 * 1024)
+#endif
+
+/**
+ * @brief Most fonts akgl_ui_font_register() will map to clay fontIds.
+ *
+ * clay identifies a font as a `uint16_t`; libakgl identifies one as a name in
+ * #AKGL_REGISTRY_FONT. The table joining them is this many fixed slots. A
+ * size is baked into each registered font handle, so a game using one face at
+ * three sizes is using three slots.
+ */
+#ifndef AKGL_UI_MAX_FONTS
+#define AKGL_UI_MAX_FONTS               8
+#endif
+
+/**
+ * @brief Bytes each fontId table slot holds for its registry name, terminator included.
+ */
+#ifndef AKGL_UI_FONT_NAME_LENGTH
+#define AKGL_UI_FONT_NAME_LENGTH        64
+#endif
+
+/**
+ * @brief Bytes of scratch one text render command may occupy, terminator included.
+ *
+ * clay hands text to a renderer as a length-and-pointer slice, one command
+ * per wrapped line; akgl_text_rendertextat() takes a C string, so each line
+ * is copied through a bounded buffer on the way. A line longer than this
+ * fails the frame loudly rather than drawing a truncation that reads as the
+ * author's text.
+ */
+#ifndef AKGL_UI_MAX_TEXT_BYTES
+#define AKGL_UI_MAX_TEXT_BYTES          1024
+#endif
+
+/**
+ * @brief Most entries one akgl_UiMenu may carry.
+ *
+ * A menu deeper than this wants scrolling and sub-screens, which is `CLAY()`
+ * territory rather than a widget's.
+ */
+#ifndef AKGL_UI_MENU_MAX_ITEMS
+#define AKGL_UI_MENU_MAX_ITEMS          16
+#endif
+
+/**
+ * @brief Height of the akgl_ui_dialog() panel, in pixels.
+ *
+ * Two lines of 12pt monospace plus padding -- the JRPG textbox's height, kept
+ * so the widget's output is comparable with the hand-rolled panel it
+ * replaces.
+ */
+#ifndef AKGL_UI_DIALOG_HEIGHT
+#define AKGL_UI_DIALOG_HEIGHT           56
+#endif
+
+/**
+ * @brief One look, shared by every widget: colours, spacing, corners, font.
+ *
+ * Passing `NULL` wherever a style is taken means the library default, which
+ * is deliberately the JRPG textbox's palette -- near-black fill (24,20,37,235)
+ * with parchment edge and ink (240,236,214,255), 8 pixels of padding, square
+ * corners, fontId 0. A caller wanting one change copies those values and
+ * changes one; there is no per-field "zero means default" magic, because a
+ * transparent fill and a zero radius are things a style legitimately says.
+ */
+typedef struct {
+    SDL_Color fill;             /**< Panel background. */
+    SDL_Color edge;             /**< Border colour. Drawn one pixel wide where a widget has a border. */
+    SDL_Color ink;              /**< Text colour. */
+    float32_t padding;          /**< Pixels between a panel's edge and its content, and between a widget and the screen edge it anchors to. */
+    float32_t corner_radius;    /**< Corner rounding in pixels. 0 is square. */
+    uint16_t fontid;            /**< The clay fontId text renders with, from akgl_ui_font_register(). */
+} akgl_UiStyle;
+
+/**
+ * @brief Where on the screen akgl_ui_label() pins itself.
+ */
+typedef enum {
+    AKGL_UI_ANCHOR_TOP_LEFT,        /**< Inset by the style's padding from the top-left corner. */
+    AKGL_UI_ANCHOR_TOP_RIGHT,       /**< Inset from the top-right corner. */
+    AKGL_UI_ANCHOR_BOTTOM_LEFT,     /**< Inset from the bottom-left corner. */
+    AKGL_UI_ANCHOR_BOTTOM_RIGHT,    /**< Inset from the bottom-right corner. */
+    AKGL_UI_ANCHOR_CENTER           /**< Dead centre, no inset. */
+} akgl_UiAnchor;
+
+/**
+ * @brief One vertical menu: its entries, its selection, and whether it fired.
+ *
+ * Caller-owned, the way the JRPG's textbox state is a static in the game --
+ * there is no heap layer behind this because it owns no texture, no font and
+ * no registry entry; it is a struct of borrowed pointers and two integers.
+ * Declare it static, fill in `id`, `items` and `count`, and leave the rest
+ * zeroed.
+ *
+ * `selected` is yours to read and the menu's to move: keyboard and gamepad
+ * move it through akgl_ui_menu_handle_event(), and the mouse moves it by
+ * hovering while akgl_ui_menu() declares the rows. `activated` latches true
+ * on Return, gamepad South, or a click on a row; the caller acts on it and
+ * sets it back to false -- the menu never clears it, so an unread activation
+ * is not lost between frames.
+ */
+typedef struct {
+    char *id;                               /**< Element id prefix, unique per menu. Required. Borrowed. */
+    char *items[AKGL_UI_MENU_MAX_ITEMS];    /**< The entries, top to bottom. Borrowed; they must outlive the frame. */
+    int32_t count;                          /**< How many of @c items are set. 1 to #AKGL_UI_MENU_MAX_ITEMS. */
+    int32_t selected;                       /**< Index of the highlighted entry. In and out. */
+    bool activated;                         /**< Out: the selected entry was confirmed. Caller clears. */
+    akgl_UiStyle *style;                    /**< Look to draw with, or `NULL` for the library default. */
+} akgl_UiMenu;
+
+/**
+ * @brief Bring the UI subsystem up.
+ *
+ * Bounds clay to the `AKGL_UI_*` ceilings, checks that the arena is big
+ * enough for them, and hands it to `Clay_Initialize` with an error handler
+ * that routes clay's layout-time complaints into the libakgl error protocol
+ * (they surface from akgl_ui_frame_end(), which is the first call after they
+ * can happen).
+ *
+ * The layout dimensions are taken as parameters rather than read from the
+ * camera or the window, so a headless program -- a test, a layout tool -- can
+ * bring the UI up without a renderer existing at all. A windowed game passes
+ * its screen size and lets akgl_ui_handle_event() track resizes from there.
+ *
+ * @param width  Layout width in pixels. Must be positive.
+ * @param height Layout height in pixels. Must be positive.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_OUTOFBOUNDS If @p width or @p height is not positive.
+ * @throws AKGL_ERR_UI If the subsystem is already initialized -- call
+ *         akgl_ui_shutdown() first; if the arena cannot hold clay's
+ *         structures at the current ceilings -- the message carries the bytes
+ *         required and the bytes available, so the operator knows what to
+ *         raise #AKGL_UI_ARENA_BYTES to; or if `Clay_Initialize` refuses,
+ *         which the preceding checks should make unreachable.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_init(int width, int height);
+
+/**
+ * @brief Return the UI subsystem to the inert state.
+ *
+ * clay has no teardown of its own -- everything it built lives in the arena,
+ * and the next akgl_ui_init() lays a new context out over it. This forgets
+ * the context and clears the stashed error state, and is idempotent, because
+ * shutdown paths run after partial startups.
+ *
+ * @warning Anything that captured clay state -- and any `CLAY()` block that
+ *          runs after this -- is left talking to a context this subsystem has
+ *          disowned. Stop declaring layouts before shutting down, the same
+ *          way fonts stop being drawn before akgl_text_unloadallfonts().
+ *
+ * @return `NULL`. Shutting down an uninitialized subsystem is success.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_shutdown(void);
+
+/**
+ * @brief Tell the layout engine the render target changed size.
+ *
+ * akgl_ui_handle_event() calls this for `SDL_EVENT_WINDOW_RESIZED`, so a game
+ * that routes its events through there never calls it directly. It is public
+ * for the host that owns its own event loop.
+ *
+ * @param width  New layout width in pixels. Must be positive.
+ * @param height New layout height in pixels. Must be positive.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKGL_ERR_UI If the subsystem is not initialized.
+ * @throws AKERR_OUTOFBOUNDS If @p width or @p height is not positive.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_resize(int width, int height);
+
+/**
+ * @brief Map a font-registry name to the clay fontId that text elements name it by.
+ *
+ * The table stores the *name* and resolves it through #AKGL_REGISTRY_FONT on
+ * every use, rather than caching the `TTF_Font *` -- fonts are not reference
+ * counted, so a cached handle would dangle the moment akgl_text_unloadfont()
+ * took the font away, while a name honestly reports "no longer registered".
+ * Registering a name that is already in the table returns its existing id
+ * rather than spending a second slot.
+ *
+ * clay's `Clay_TextElementConfig.fontSize` is **ignored** by this subsystem:
+ * a libakgl font bakes its size in at akgl_text_loadfont() time, so the size
+ * a text element renders at is the size the font behind its fontId was loaded
+ * at. One face at two sizes is two loads, two registrations, two ids.
+ *
+ * @param name   Registry key the font was published under. Required, and it
+ *               must already be in the registry -- registering first and
+ *               loading later would leave a window where a fontId resolves to
+ *               nothing.
+ * @param fontid Receives the id to put in `Clay_TextElementConfig.fontId`.
+ *               Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p name or @p fontid is `NULL`.
+ * @throws AKGL_ERR_UI If the subsystem is not initialized; if no font is
+ *         registered under @p name; or if all #AKGL_UI_MAX_FONTS slots are
+ *         taken. Each message says which.
+ * @throws AKERR_OUTOFBOUNDS If @p name does not fit in a table slot --
+ *         #AKGL_UI_FONT_NAME_LENGTH bytes including the terminator.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_font_register(char *name, uint16_t *fontid);
+
+/**
+ * @brief Feed one SDL event to the UI, and learn whether the UI claimed it.
+ *
+ * The mouse half of the input story -- keyboard and gamepad stay with the
+ * control maps and the widget helpers, because keyboard focus is something
+ * the application declares, not something a pointer position implies. This
+ * handles mouse motion, left-button presses and releases, the wheel, and
+ * window resizes; every other event, and every event while the subsystem is
+ * not initialized, reports @p consumed false and succeeds, so a host passes
+ * every event through unconditionally -- the same contract
+ * akgl_controller_handle_event() has.
+ *
+ * Call it *before* akgl_controller_handle_event() in the event loop, and skip
+ * the rest of the chain when it consumed:
+ *
+ *     while ( SDL_PollEvent(&event) ) {
+ *         PASS(errctx, akgl_ui_handle_event(&app, &event, &consumed));
+ *         if ( consumed ) { continue; }
+ *         PASS(errctx, akgl_controller_handle_event(&app, &event));
+ *     }
+ *
+ * A press or release is consumed when the pointer is over any UI element;
+ * motion and resizes never are (the game may care where the mouse is, and
+ * certainly cares about its window). The hit test runs against the layout
+ * the *previous* frame declared, because this frame's does not exist while
+ * events are being polled -- clay retains the last tree for exactly this
+ * purpose, and one frame of staleness is the accepted cost of the standard
+ * model. Before any frame has been laid out, nothing is over anything and
+ * nothing is consumed.
+ *
+ * @param appstate The application state pointer the event loop owns.
+ *                 Required, though this implementation does not read it --
+ *                 the parameter exists so the signature matches
+ *                 akgl_controller_handle_event() and can grow the same way.
+ * @param event    The event SDL handed the loop. Required.
+ * @param consumed Receives whether the UI claimed the event. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p appstate, @p event, or @p consumed is
+ *         `NULL`.
+ * @throws AKERR_OUTOFBOUNDS If a resize event carries a non-positive size,
+ *         from akgl_ui_resize().
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_handle_event(void *appstate, SDL_Event *event, bool *consumed);
+
+/**
+ * @brief Open the UI frame: clear the error stash and begin the clay layout.
+ *
+ * Call once per rendered frame, after akgl_game_update() and before any
+ * `CLAY()` block or widget helper. Everything declared between this and
+ * akgl_ui_frame_end() is this frame's interface; a dialog is "open" because
+ * the frame declares it, not because a mode was toggled somewhere.
+ *
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKGL_ERR_UI If the subsystem is not initialized, or if a frame is
+ *         already open -- a begin/begin sequence means a frame_end went
+ *         missing, and absorbing it would hide the layout of one frame inside
+ *         another.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_frame_begin(void);
+
+/**
+ * @brief Close the UI frame: compute the layout and draw it.
+ *
+ * Runs `Clay_EndLayout` and walks the render commands it produces through
+ * @p self -- fills and rounded fills, borders, clip rectangles, text through
+ * akgl_text_rendertextat(), images through the backend's `draw_texture`.
+ * Draws in screen coordinates on whatever is already on the target, so call
+ * it between akgl_game_update() and the backend's `frame_end`: the UI lands
+ * on top of the world.
+ *
+ * The frame is considered closed even when this fails: the next
+ * akgl_ui_frame_begin() is legal, so one bad frame is one bad frame rather
+ * than a wedged subsystem.
+ *
+ * If clay reported errors during layout -- through its handler, or the
+ * measure callback failing -- this raises the first of them here and does not
+ * draw, because a layout that failed is not a layout, and the raise names how
+ * many more followed it.
+ *
+ * @param self The backend to draw through. Required, along with its
+ *             `sdl_renderer` and `draw_texture`.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p self, its `sdl_renderer`, or its
+ *         `draw_texture` is `NULL`.
+ * @throws AKGL_ERR_UI If the subsystem is not initialized; if no frame is
+ *         open; if clay reported layout errors; if a text command's line
+ *         exceeds #AKGL_UI_MAX_TEXT_BYTES; or if a fontId cannot be resolved.
+ * @throws AKERR_* Whatever the drawing primitives underneath raise.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_frame_end(akgl_RenderBackend *self);
+
+/**
+ * @brief Declare a dialog panel: the JRPG textbox in one call.
+ *
+ * A panel across the bottom of the screen, inset by the style's padding,
+ * #AKGL_UI_DIALOG_HEIGHT pixels tall, with a one-pixel border and the text
+ * wrapped inside it. Legal only between akgl_ui_frame_begin() and
+ * akgl_ui_frame_end(). Showing and hiding is the frame's business: call this
+ * while somebody is talking and don't while nobody is -- there is no
+ * `visible` flag, because a declarative frame *is* the flag.
+ *
+ * @param id    Element id for the panel, unique within the frame. Required.
+ *              Borrowed until frame_end.
+ * @param text  What the dialog says. Required, and borrowed until frame_end
+ *              -- clay keeps the pointer, not a copy. May be empty, which
+ *              draws an empty panel.
+ * @param style Look to draw with, or `NULL` for the textbox palette.
+ *
+ * @note The panel's height is fixed at #AKGL_UI_DIALOG_HEIGHT and the text is
+ *       not clipped to it: a message that wraps to more lines than fit runs
+ *       past the bottom border, visibly. That is the same behaviour as the
+ *       hand-rolled panel this widget mirrors, and it is deliberate --
+ *       overflow you can see beats truncation you cannot. Size the height for
+ *       your longest message, or raise the override.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p id or @p text is `NULL`.
+ * @throws AKGL_ERR_UI If the subsystem is not initialized or no frame is
+ *         open.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_dialog(char *id, char *text, akgl_UiStyle *style);
+
+/**
+ * @brief Declare a HUD label: one line of text on a padded panel, pinned to a corner.
+ *
+ * Fit-sized around its text, anchored per @p anchor and inset by the style's
+ * padding. The score counter and the lives counter are two calls to this with
+ * two ids. Legal only between akgl_ui_frame_begin() and akgl_ui_frame_end().
+ *
+ * The text is borrowed until frame_end, which matters for the obvious use:
+ * format the score into a buffer that outlives the frame bracket, not into a
+ * scope that closes before the draw.
+ *
+ * @param id     Element id for the label, unique within the frame. Required.
+ * @param text   What the label says. Required; empty draws an empty chip.
+ * @param anchor Which corner (or the centre) to pin to.
+ * @param style  Look to draw with, or `NULL` for the library default.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p id or @p text is `NULL`.
+ * @throws AKGL_ERR_UI If the subsystem is not initialized or no frame is
+ *         open.
+ * @throws AKERR_OUTOFBOUNDS If @p anchor is not one of the enum's values.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_label(char *id, char *text, akgl_UiAnchor anchor, akgl_UiStyle *style);
+
+/**
+ * @brief Declare a vertical menu from caller-owned state, centred on screen.
+ *
+ * One row per entry, the selected row drawn inverted (ink on fill swaps to
+ * fill on ink). Moving the mouse onto a row selects it; a left click on a
+ * row selects and sets `activated`. A *stationary* pointer claims nothing --
+ * parking the mouse over the menu must not pin the selection against the
+ * keyboard, which is fighting sixty times a second and losing. Keyboard and
+ * gamepad go through
+ * akgl_ui_menu_handle_event(), which the application calls for whichever
+ * menu currently has its attention -- that routing *is* the focus model.
+ * Legal only between akgl_ui_frame_begin() and akgl_ui_frame_end().
+ *
+ * @param menu The menu state. Required, with a non-`NULL` `id`, a `count` in
+ *             range, every used entry non-`NULL`, and `selected` pointing at
+ *             an entry.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p menu, its `id`, or any of its first
+ *         `count` items is `NULL`. The message names the index.
+ * @throws AKGL_ERR_UI If the subsystem is not initialized or no frame is
+ *         open.
+ * @throws AKERR_OUTOFBOUNDS If `count` or `selected` is out of range.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_menu(akgl_UiMenu *menu);
+
+/**
+ * @brief Drive a menu from a keyboard or gamepad event.
+ *
+ * Up and Down arrows and the D-pad move the selection, wrapping at both
+ * ends; Return and the gamepad South button set `activated`. Anything else
+ * -- and anything while the subsystem is inert -- reports @p consumed false
+ * and succeeds, so it slots into the same pass-everything event chain as
+ * akgl_ui_handle_event(), after it and before the control maps:
+ *
+ *     PASS(errctx, akgl_ui_handle_event(&app, &event, &consumed));
+ *     if ( consumed ) { continue; }
+ *     if ( menu_active ) {
+ *         PASS(errctx, akgl_ui_menu_handle_event(&menu, &event, &consumed));
+ *         if ( consumed ) { continue; }
+ *     }
+ *     PASS(errctx, akgl_controller_handle_event(&app, &event));
+ *
+ * @param menu     The menu the application is routing input to. Required,
+ *                 with `count` in range.
+ * @param event    The event SDL handed the loop. Required.
+ * @param consumed Receives whether the menu claimed the event. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p menu, @p event, or @p consumed is `NULL`.
+ * @throws AKERR_OUTOFBOUNDS If `count` or `selected` is out of range.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_menu_handle_event(akgl_UiMenu *menu, SDL_Event *event, bool *consumed);
+
+/*
+ * The following is part of the internal API. It is exposed so the test suite
+ * can reach it and is not meant to be called by a game.
+ */
+
+/**
+ * @brief The measure callback akgl_ui_init() hands to clay.
+ *
+ * clay's callback signature returns dimensions by value and has no error
+ * channel, so this cannot raise: on any failure -- an unregistered fontId, a
+ * font gone from the registry, SDL_ttf refusing the string -- it reports zero
+ * by zero and stashes the failure where akgl_ui_frame_end() will raise it.
+ * The slice is measured at its stated length through SDL_ttf directly, so it
+ * is never copied and need not be NUL-terminated.
+ *
+ * @param text     The slice of text clay wants measured.
+ * @param config   The text element's configuration; only `fontId` is
+ *                 consulted (see akgl_ui_font_register() on `fontSize`).
+ * @param userData Unused. clay passes back whatever init registered.
+ * @return The slice's size in pixels, or zero by zero on failure.
+ */
+Clay_Dimensions akgl_ui_measure_text(Clay_StringSlice text, Clay_TextElementConfig *config, void *userData);
+
+/**
+ * @brief Draw one frame's render commands through a backend.
+ *
+ * The renderer half of akgl_ui_frame_end(), separated so a test can hand it
+ * a command array and read pixels back without a full frame bracket. Handles
+ * RECTANGLE, BORDER, TEXT, IMAGE and the SCISSOR pair; CUSTOM commands and
+ * image tint colours are skipped in this version, and per-corner radii are
+ * collapsed to the top-left value -- the widget helpers only produce uniform
+ * corners.
+ *
+ * An IMAGE command's `imageData` is an `akgl_Sprite *`; its first frame is
+ * drawn stretched to the command's bounding box.
+ *
+ * Any clip rectangle a command set is cleared before this returns, success or
+ * failure -- the UI must not leave the next frame's world clipped.
+ *
+ * @note TEXT commands draw through akgl_text_rendertextat(), whose contract
+ *       is the *global* `akgl_renderer` -- so a host drawing its UI through
+ *       some other backend must keep the two pointed at the same renderer,
+ *       or its text lands somewhere else.
+ *
+ * @param self     The backend to draw through. Required, along with its
+ *                 `sdl_renderer` and `draw_texture`.
+ * @param commands The commands `Clay_EndLayout` returned. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p self, its `sdl_renderer`, its
+ *         `draw_texture`, or @p commands is `NULL`.
+ * @throws AKGL_ERR_UI If a text line exceeds #AKGL_UI_MAX_TEXT_BYTES, a
+ *         fontId does not resolve, or an IMAGE command carries no sprite.
+ * @throws AKERR_* Whatever the drawing primitives underneath raise.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akgl_ui_execute_commands(akgl_RenderBackend *self, Clay_RenderCommandArray *commands);
+
+/**
+ * @brief Narrow the arena, so a test can drive akgl_ui_init() into refusal.
+ *
+ * The interesting behaviour is the refusal message naming both numbers, and
+ * the only other way to reach it is rebuilding the library with a smaller
+ * #AKGL_UI_ARENA_BYTES, which CI cannot do and a reader cannot repeat. Same
+ * contract as akgl_ccd_arena_set_limit().
+ *
+ * @param limit Usable bytes. 0, or anything above #AKGL_UI_ARENA_BYTES,
+ *              restores the full arena.
+ */
+void akgl_ui_arena_limit(size_t limit);
+
+#endif // _AKGL_UI_H_
--- a/scripts/memcheck.sh
+++ b/scripts/memcheck.sh
@@ -49,8 +49,20 @@ rm -f "$AKGL_MEMCHECK_LOG"/MemoryChecker.*.log
 # The run itself is allowed to fail: a suite that valgrind makes slow enough to
 # trip an assertion still produced a log worth reading, and the log is what
 # decides the exit status below.
+#
+# docs_examples and docs_screenshots are excluded, and the exclusion deserves
+# its reasons stated: those two tests are *shell scripts* that drive gcc and
+# run the compiled snippets as child processes. Valgrind wraps the test
+# command, does not trace children, and so spends the whole test memchecking
+# /bin/bash -- 413 of bash's own by-design leaks on the first CI run that got
+# this far, and not one byte of libakgl. The snippet programs themselves are
+# ordinary akgl consumers whose code paths the suites and example games
+# already cover below, under valgrind, as real binaries. A caller's own -E
+# overrides this one (ctest takes the last), which is fine: a narrowed run
+# chose its scope on purpose.
 set +e
-ctest --test-dir "$AKGL_BUILD_DIR" -T memcheck --output-on-failure "$@"
+ctest --test-dir "$AKGL_BUILD_DIR" -T memcheck --output-on-failure \
+      -E '^(docs_examples|docs_screenshots)$' "$@"
 AKGL_CTEST_STATUS=$?
 set -e

--- a/src/draw.c
+++ b/src/draw.c
@@ -619,3 +619,229 @@ akerr_ErrorContext *akgl_draw_paste_region(akgl_RenderBackend *self, SDL_Surface
    } FINISH(errctx, true);
    SUCCEED_RETURN(errctx);
 }
+
+/**
+ * @brief Fill one quarter-circle corner as a triangle fan.
+ *
+ * `SDL_RenderGeometry` colours from its vertices rather than the renderer's
+ * draw colour, so this neither pushes nor pops it.
+ *
+ * @param self      The backend. Assumed non-`NULL` with a live `sdl_renderer`;
+ *                  the caller has already checked both.
+ * @param cx        Horizontal position of the corner's centre -- the point the
+ *                  fan radiates from, one radius inside the rectangle.
+ * @param cy        Vertical position of the centre.
+ * @param radius    Radius of the quarter circle. Assumed positive.
+ * @param start_deg Angle the quarter starts at; it sweeps 90 degrees clockwise
+ *                  from there.
+ * @param color     Colour to fill with.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKGL_ERR_SDL If the fan cannot be drawn.
+ */
+static akerr_ErrorContext *fill_corner_fan(akgl_RenderBackend *self, float32_t cx, float32_t cy, float32_t radius, float32_t start_deg, SDL_Color color)
+{
+    SDL_Vertex vertices[AKGL_DRAW_ROUNDED_RECT_SEGMENTS + 2];
+    int indices[AKGL_DRAW_ROUNDED_RECT_SEGMENTS * 3];
+    SDL_FColor fcolor;
+    float32_t angle = 0.0f;
+    int i = 0;
+
+    PREPARE_ERROR(errctx);
+    fcolor.r = (float)color.r / 255.0f;
+    fcolor.g = (float)color.g / 255.0f;
+    fcolor.b = (float)color.b / 255.0f;
+    fcolor.a = (float)color.a / 255.0f;
+
+    vertices[0].position.x = cx;
+    vertices[0].position.y = cy;
+    vertices[0].color = fcolor;
+    vertices[0].tex_coord.x = 0.0f;
+    vertices[0].tex_coord.y = 0.0f;
+    for ( i = 0; i <= AKGL_DRAW_ROUNDED_RECT_SEGMENTS; i++ ) {
+	angle = (start_deg + ((90.0f / AKGL_DRAW_ROUNDED_RECT_SEGMENTS) * (float)i)) * (SDL_PI_F / 180.0f);
+	vertices[i + 1].position.x = cx + (radius * SDL_cosf(angle));
+	vertices[i + 1].position.y = cy + (radius * SDL_sinf(angle));
+	vertices[i + 1].color = fcolor;
+	vertices[i + 1].tex_coord.x = 0.0f;
+	vertices[i + 1].tex_coord.y = 0.0f;
+    }
+    for ( i = 0; i < AKGL_DRAW_ROUNDED_RECT_SEGMENTS; i++ ) {
+	indices[(i * 3) + 0] = 0;
+	indices[(i * 3) + 1] = i + 1;
+	indices[(i * 3) + 2] = i + 2;
+    }
+    FAIL_ZERO_RETURN(
+	errctx,
+	SDL_RenderGeometry(
+	    self->sdl_renderer,
+	    NULL,
+	    vertices,
+	    AKGL_DRAW_ROUNDED_RECT_SEGMENTS + 2,
+	    indices,
+	    AKGL_DRAW_ROUNDED_RECT_SEGMENTS * 3),
+	AKGL_ERR_SDL,
+	"%s",
+	SDL_GetError());
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akgl_draw_filled_rounded_rect(akgl_RenderBackend *self, SDL_FRect *rect, float32_t radius, SDL_Color color)
+{
+    SDL_Color previous;
+    SDL_FRect band;
+    float32_t half = 0.0f;
+    bool pushed = false;
+    bool drawfailed = false;
+
+    PREPARE_ERROR(errctx);
+    FAIL_ZERO_RETURN(errctx, self, AKERR_NULLPOINTER, "self");
+    FAIL_ZERO_RETURN(errctx, self->sdl_renderer, AKERR_NULLPOINTER, "No valid SDL rendering backend");
+    FAIL_ZERO_RETURN(errctx, rect, AKERR_NULLPOINTER, "NULL rectangle");
+    if ( (rect->w <= 0.0f) || (rect->h <= 0.0f) ) {
+	SUCCEED_RETURN(errctx);
+    }
+    if ( radius <= 0.0f ) {
+	PASS(errctx, akgl_draw_filled_rect(self, rect, color));
+	SUCCEED_RETURN(errctx);
+    }
+    half = (((rect->w < rect->h) ? rect->w : rect->h) / 2.0f);
+    if ( radius > half ) {
+	radius = half;
+    }
+
+    ATTEMPT {
+	CATCH(errctx, push_draw_color(self, color, &previous));
+	pushed = true;
+
+	// The body is three bands: one the full width between the corner rows,
+	// and one between the corners along each of the top and bottom edges.
+	// A radius of exactly half the shorter side leaves one or more of them
+	// with no area, which SDL fills as nothing -- at the limit the whole
+	// shape is the four fans.
+	band.x = rect->x;
+	band.y = rect->y + radius;
+	band.w = rect->w;
+	band.h = rect->h - (radius * 2.0f);
+	if ( SDL_RenderFillRect(self->sdl_renderer, &band) == false ) {
+	    drawfailed = true;
+	}
+	band.x = rect->x + radius;
+	band.y = rect->y;
+	band.w = rect->w - (radius * 2.0f);
+	band.h = radius;
+	if ( SDL_RenderFillRect(self->sdl_renderer, &band) == false ) {
+	    drawfailed = true;
+	}
+	band.y = rect->y + rect->h - radius;
+	if ( SDL_RenderFillRect(self->sdl_renderer, &band) == false ) {
+	    drawfailed = true;
+	}
+	FAIL_NONZERO_BREAK(errctx, drawfailed, AKGL_ERR_SDL, "%s", SDL_GetError());
+
+	CATCH(errctx, fill_corner_fan(self, rect->x + radius, rect->y + radius, radius, 180.0f, color));
+	CATCH(errctx, fill_corner_fan(self, rect->x + rect->w - radius, rect->y + radius, radius, 270.0f, color));
+	CATCH(errctx, fill_corner_fan(self, rect->x + rect->w - radius, rect->y + rect->h - radius, radius, 0.0f, color));
+	CATCH(errctx, fill_corner_fan(self, rect->x + radius, rect->y + rect->h - radius, radius, 90.0f, color));
+    } CLEANUP {
+	if ( pushed == true ) {
+	    IGNORE(pop_draw_color(self, &previous));
+	}
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akgl_draw_arc(akgl_RenderBackend *self, float32_t x, float32_t y, float32_t radius, float32_t start_deg, float32_t end_deg, float32_t thickness, SDL_Color color)
+{
+    SDL_Vertex vertices[AKGL_DRAW_ARC_MAX_POINTS];
+    int indices[(AKGL_DRAW_ARC_MAX_POINTS - 2) * 3];
+    SDL_FColor fcolor;
+    float32_t span = 0.0f;
+    float32_t inner = 0.0f;
+    float32_t angle = 0.0f;
+    int segments = 0;
+    int base = 0;
+    int i = 0;
+
+    PREPARE_ERROR(errctx);
+    FAIL_ZERO_RETURN(errctx, self, AKERR_NULLPOINTER, "self");
+    FAIL_ZERO_RETURN(errctx, self->sdl_renderer, AKERR_NULLPOINTER, "No valid SDL rendering backend");
+    FAIL_NONZERO_RETURN(errctx, (radius <= 0.0f), AKERR_OUTOFBOUNDS, "Arc radius %f is not positive", (double)radius);
+    FAIL_NONZERO_RETURN(errctx, (thickness <= 0.0f), AKERR_OUTOFBOUNDS, "Arc thickness %f is not positive", (double)thickness);
+    span = end_deg - start_deg;
+    if ( span <= 0.0f ) {
+	SUCCEED_RETURN(errctx);
+    }
+    if ( span > 360.0f ) {
+	span = 360.0f;
+    }
+    inner = radius - thickness;
+    if ( inner < 0.0f ) {
+	inner = 0.0f;
+    }
+
+    // Steps in proportion to the angle swept, so a sliver of arc does not
+    // spend the whole vertex budget and a full circle uses all of it: the
+    // quarter-circle density of AKGL_DRAW_ROUNDED_RECT_SEGMENTS, capped by
+    // what AKGL_DRAW_ARC_MAX_POINTS vertices can carry at two per step.
+    segments = (int)((span / 90.0f) * (float)AKGL_DRAW_ROUNDED_RECT_SEGMENTS) + 1;
+    if ( segments > ((AKGL_DRAW_ARC_MAX_POINTS / 2) - 1) ) {
+	segments = (AKGL_DRAW_ARC_MAX_POINTS / 2) - 1;
+    }
+
+    fcolor.r = (float)color.r / 255.0f;
+    fcolor.g = (float)color.g / 255.0f;
+    fcolor.b = (float)color.b / 255.0f;
+    fcolor.a = (float)color.a / 255.0f;
+    for ( i = 0; i <= segments; i++ ) {
+	angle = (start_deg + ((span / (float)segments) * (float)i)) * (SDL_PI_F / 180.0f);
+	vertices[i * 2].position.x = x + (radius * SDL_cosf(angle));
+	vertices[i * 2].position.y = y + (radius * SDL_sinf(angle));
+	vertices[i * 2].color = fcolor;
+	vertices[i * 2].tex_coord.x = 0.0f;
+	vertices[i * 2].tex_coord.y = 0.0f;
+	vertices[(i * 2) + 1].position.x = x + (inner * SDL_cosf(angle));
+	vertices[(i * 2) + 1].position.y = y + (inner * SDL_sinf(angle));
+	vertices[(i * 2) + 1].color = fcolor;
+	vertices[(i * 2) + 1].tex_coord.x = 0.0f;
+	vertices[(i * 2) + 1].tex_coord.y = 0.0f;
+    }
+    for ( i = 0; i < segments; i++ ) {
+	base = i * 2;
+	indices[(i * 6) + 0] = base;
+	indices[(i * 6) + 1] = base + 2;
+	indices[(i * 6) + 2] = base + 1;
+	indices[(i * 6) + 3] = base + 1;
+	indices[(i * 6) + 4] = base + 2;
+	indices[(i * 6) + 5] = base + 3;
+    }
+    FAIL_ZERO_RETURN(
+	errctx,
+	SDL_RenderGeometry(
+	    self->sdl_renderer,
+	    NULL,
+	    vertices,
+	    (segments + 1) * 2,
+	    indices,
+	    segments * 6),
+	AKGL_ERR_SDL,
+	"%s",
+	SDL_GetError());
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akgl_draw_set_clip(akgl_RenderBackend *self, SDL_Rect *rect)
+{
+    PREPARE_ERROR(errctx);
+    FAIL_ZERO_RETURN(errctx, self, AKERR_NULLPOINTER, "self");
+    FAIL_ZERO_RETURN(errctx, self->sdl_renderer, AKERR_NULLPOINTER, "No valid SDL rendering backend");
+    // NULL rect deliberately passes straight through: it is how the clip is
+    // cleared, and the header says so.
+    FAIL_ZERO_RETURN(
+	errctx,
+	SDL_SetRenderClipRect(self->sdl_renderer, rect),
+	AKGL_ERR_SDL,
+	"%s",
+	SDL_GetError());
+    SUCCEED_RETURN(errctx);
+}
--- a/src/error.c
+++ b/src/error.c
@@ -21,5 +21,6 @@ akerr_ErrorContext *akgl_error_init(void)
    PASS(errctx, akerr_register_status_name(AKGL_ERR_OWNER, AKGL_ERR_BEHAVIOR, "Behavior Error"));
    PASS(errctx, akerr_register_status_name(AKGL_ERR_OWNER, AKGL_ERR_LOGICINTERRUPT, "Logic Interrupt"));
    PASS(errctx, akerr_register_status_name(AKGL_ERR_OWNER, AKGL_ERR_COLLISION, "Collision Error"));
+    PASS(errctx, akerr_register_status_name(AKGL_ERR_OWNER, AKGL_ERR_UI, "UI Error"));
    SUCCEED_RETURN(errctx);
 }
--- a/src/ui.c
+++ b/src/ui.c
--- a/src/ui_clay.c
+++ b/src/ui_clay.c
@@ -0,0 +1,21 @@
+/**
+ * @file ui_clay.c
+ * @brief The one translation unit that compiles clay's implementation.
+ *
+ * clay is a single-header library: every other file that includes <clay.h>
+ * gets declarations only, and exactly one file in the whole program defines
+ * CLAY_IMPLEMENTATION before the include to get the definitions. This is that
+ * file, and it must stay the only one -- a second definition anywhere,
+ * including in a consuming game, is two copies of clay's globals and the
+ * loader picking between them silently. The warning in akgl/ui.h says so to
+ * consumers; this comment says so to us.
+ *
+ * Nothing else belongs here. libakgl's own UI code is src/ui.c, which
+ * includes <clay.h> like any other consumer. CMakeLists.txt compiles this
+ * file with -w on the same terms as deps/semver and deps/libccd: 99% of what
+ * this TU contains is vendored code, and a future clay bump must not be able
+ * to fail the build on a warning we do not own.
+ */
+
+#define CLAY_IMPLEMENTATION
+#include <clay.h>
--- a/tests/character.c
+++ b/tests/character.c
@@ -284,6 +284,10 @@ akerr_ErrorContext *test_character_sprite_rebind_releases_displaced(void)
 int main(void)
 {
    PREPARE_ERROR(errctx);
+
+    SDL_SetHint(SDL_HINT_VIDEO_DRIVER, "dummy");
+    SDL_SetHint(SDL_HINT_AUDIO_DRIVER, "dummy");
+    SDL_SetHint(SDL_HINT_RENDER_DRIVER, "software");
    ATTEMPT {
 	CATCH(errctx, akgl_error_init());
 	akgl_renderer = &akgl_default_renderer;
--- a/tests/docs_preludes/docs_prelude.h
+++ b/tests/docs_preludes/docs_prelude.h
@@ -50,6 +50,7 @@
 #include <akgl/text.h>
 #include <akgl/tilemap.h>
 #include <akgl/types.h>
+#include <akgl/ui.h>
 #include <akgl/util.h>

 /**
--- a/tests/draw.c
+++ b/tests/draw.c
@@ -628,6 +628,183 @@ akerr_ErrorContext *test_draw_background(void)
    SUCCEED_RETURN(errctx);
 }

+akerr_ErrorContext *test_draw_filled_rounded_rect(void)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Surface *shot = NULL;
+    SDL_FRect rect = { 8.0f, 8.0f, 40.0f, 24.0f };
+    SDL_FRect square = { 40.0f, 40.0f, 16.0f, 16.0f };
+
+    ATTEMPT {
+	CATCH(errctx, clear_target());
+	TEST_EXPECT_OK(errctx, akgl_draw_filled_rounded_rect(akgl_renderer, &rect, 8.0f, testred),
+		       "filling a rounded rectangle");
+
+	shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+	FAIL_ZERO_BREAK(errctx, shot, AKGL_ERR_SDL, "%s", SDL_GetError());
+	TEST_ASSERT(errctx, pixel_is(shot, 28, 20, testred),
+		    "the middle of the rounded rectangle is unfilled");
+	TEST_ASSERT(errctx, pixel_is(shot, 28, 8, testred),
+		    "the top edge between the corners is unfilled");
+	TEST_ASSERT(errctx, pixel_is(shot, 8, 20, testred),
+		    "the left edge between the corners is unfilled");
+	// 12,12 is inside the corner's quarter circle (5.7px from its centre
+	// at 16,16); 8,8 and 9,9 are outside it (11.3px and 9.9px). The fan's
+	// triangles are chords of the circle, so they cover nothing beyond it.
+	TEST_ASSERT(errctx, pixel_is(shot, 12, 12, testred),
+		    "the inside of the rounded corner is unfilled");
+	TEST_ASSERT(errctx, pixel_is(shot, 8, 8, testblack),
+		    "the square corner pixel was filled despite the rounding");
+	TEST_ASSERT(errctx, pixel_is(shot, 9, 9, testblack),
+		    "a pixel outside the corner arc was filled");
+	SDL_DestroySurface(shot);
+	shot = NULL;
+
+	// A radius beyond half the shorter side clamps to it, which on a
+	// square is a circle: centre filled, corners untouched.
+	CATCH(errctx, clear_target());
+	TEST_EXPECT_OK(errctx, akgl_draw_filled_rounded_rect(akgl_renderer, &square, 100.0f, testgreen),
+		       "filling a rounded rectangle with an oversized radius");
+	shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+	FAIL_ZERO_BREAK(errctx, shot, AKGL_ERR_SDL, "%s", SDL_GetError());
+	TEST_ASSERT(errctx, pixel_is(shot, 48, 48, testgreen),
+		    "the centre of the clamped-radius square is unfilled");
+	TEST_ASSERT(errctx, pixel_is(shot, 41, 41, testblack),
+		    "clamping the radius still filled the square's corner");
+
+	// Radius zero is the plain fill, corners and all.
+	CATCH(errctx, clear_target());
+	TEST_EXPECT_OK(errctx, akgl_draw_filled_rounded_rect(akgl_renderer, &rect, 0.0f, testred),
+		       "a zero radius falling through to the plain fill");
+	SDL_DestroySurface(shot);
+	shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+	FAIL_ZERO_BREAK(errctx, shot, AKGL_ERR_SDL, "%s", SDL_GetError());
+	TEST_ASSERT(errctx, pixel_is(shot, 8, 8, testred),
+		    "a zero radius did not fill the square corner");
+
+	TEST_EXPECT_STATUS(errctx, AKERR_NULLPOINTER,
+			   akgl_draw_filled_rounded_rect(NULL, &rect, 4.0f, testred),
+			   "rounded fill through a NULL backend");
+	TEST_EXPECT_STATUS(errctx, AKERR_NULLPOINTER,
+			   akgl_draw_filled_rounded_rect(akgl_renderer, NULL, 4.0f, testred),
+			   "rounded fill of a NULL rectangle");
+    } CLEANUP {
+	if ( shot != NULL ) {
+	    SDL_DestroySurface(shot);
+	}
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *test_draw_arc(void)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Surface *shot = NULL;
+
+    ATTEMPT {
+	// A full ring: outer radius 20, stroke 4, so mid-stroke is radius 18.
+	CATCH(errctx, clear_target());
+	TEST_EXPECT_OK(errctx, akgl_draw_arc(akgl_renderer, 32.0f, 32.0f, 20.0f, 0.0f, 360.0f, 4.0f, testred),
+		       "stroking a full circle");
+	shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+	FAIL_ZERO_BREAK(errctx, shot, AKGL_ERR_SDL, "%s", SDL_GetError());
+	TEST_ASSERT(errctx, pixel_is(shot, 50, 32, testred),
+		    "the ring is missing at three o'clock");
+	TEST_ASSERT(errctx, pixel_is(shot, 32, 50, testred),
+		    "the ring is missing at six o'clock");
+	TEST_ASSERT(errctx, pixel_is(shot, 14, 32, testred),
+		    "the ring is missing at nine o'clock");
+	TEST_ASSERT(errctx, pixel_is(shot, 32, 14, testred),
+		    "the ring is missing at twelve o'clock");
+	TEST_ASSERT(errctx, pixel_is(shot, 32, 32, testblack),
+		    "the centre of the ring was filled");
+	TEST_ASSERT(errctx, pixel_is(shot, 42, 32, testblack),
+		    "the stroke bled inside its inner radius");
+	SDL_DestroySurface(shot);
+	shot = NULL;
+
+	// A quarter arc sweeps clockwise from three o'clock to six o'clock;
+	// 44,44 is on its mid-stroke at 45 degrees, twelve o'clock is not in
+	// the sweep at all.
+	CATCH(errctx, clear_target());
+	TEST_EXPECT_OK(errctx, akgl_draw_arc(akgl_renderer, 32.0f, 32.0f, 20.0f, 0.0f, 90.0f, 4.0f, testgreen),
+		       "stroking a quarter arc");
+	shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+	FAIL_ZERO_BREAK(errctx, shot, AKGL_ERR_SDL, "%s", SDL_GetError());
+	TEST_ASSERT(errctx, pixel_is(shot, 44, 44, testgreen),
+		    "the quarter arc is missing at its midpoint");
+	TEST_ASSERT(errctx, pixel_is(shot, 32, 14, testblack),
+		    "the quarter arc drew outside its sweep");
+
+	// An empty sweep draws nothing and reports nothing.
+	TEST_EXPECT_OK(errctx, akgl_draw_arc(akgl_renderer, 32.0f, 32.0f, 20.0f, 90.0f, 90.0f, 4.0f, testred),
+		       "an arc with no sweep");
+
+	TEST_EXPECT_STATUS(errctx, AKERR_OUTOFBOUNDS,
+			   akgl_draw_arc(akgl_renderer, 32.0f, 32.0f, 0.0f, 0.0f, 90.0f, 4.0f, testred),
+			   "an arc with no radius");
+	TEST_EXPECT_STATUS(errctx, AKERR_OUTOFBOUNDS,
+			   akgl_draw_arc(akgl_renderer, 32.0f, 32.0f, 20.0f, 0.0f, 90.0f, -1.0f, testred),
+			   "an arc with a negative thickness");
+	TEST_EXPECT_STATUS(errctx, AKERR_NULLPOINTER,
+			   akgl_draw_arc(NULL, 32.0f, 32.0f, 20.0f, 0.0f, 90.0f, 4.0f, testred),
+			   "an arc through a NULL backend");
+    } CLEANUP {
+	if ( shot != NULL ) {
+	    SDL_DestroySurface(shot);
+	}
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *test_draw_set_clip(void)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Surface *shot = NULL;
+    SDL_Rect clip = { 0, 0, 16, 16 };
+    SDL_FRect everything = { 0.0f, 0.0f, (float)TEST_TARGET_SIZE, (float)TEST_TARGET_SIZE };
+
+    ATTEMPT {
+	CATCH(errctx, clear_target());
+	TEST_EXPECT_OK(errctx, akgl_draw_set_clip(akgl_renderer, &clip),
+		       "setting the clip rectangle");
+	TEST_EXPECT_OK(errctx, akgl_draw_filled_rect(akgl_renderer, &everything, testred),
+		       "filling the whole target under a clip");
+	shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+	FAIL_ZERO_BREAK(errctx, shot, AKGL_ERR_SDL, "%s", SDL_GetError());
+	TEST_ASSERT(errctx, pixel_is(shot, 8, 8, testred),
+		    "the fill did not reach inside the clip rectangle");
+	TEST_ASSERT(errctx, pixel_is(shot, 32, 32, testblack),
+		    "the fill escaped the clip rectangle");
+	SDL_DestroySurface(shot);
+	shot = NULL;
+
+	TEST_EXPECT_OK(errctx, akgl_draw_set_clip(akgl_renderer, NULL),
+		       "clearing the clip rectangle");
+	TEST_EXPECT_OK(errctx, akgl_draw_filled_rect(akgl_renderer, &everything, testgreen),
+		       "filling the whole target after clearing the clip");
+	shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+	FAIL_ZERO_BREAK(errctx, shot, AKGL_ERR_SDL, "%s", SDL_GetError());
+	TEST_ASSERT(errctx, pixel_is(shot, 32, 32, testgreen),
+		    "clearing the clip did not restore the full target");
+
+	TEST_EXPECT_STATUS(errctx, AKERR_NULLPOINTER,
+			   akgl_draw_set_clip(NULL, &clip),
+			   "clipping through a NULL backend");
+    } CLEANUP {
+	// The clip is renderer state; leaving it set would clip every test
+	// after this one.
+	IGNORE(akgl_draw_set_clip(akgl_renderer, NULL));
+	if ( shot != NULL ) {
+	    SDL_DestroySurface(shot);
+	}
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
 int main(void)
 {
    PREPARE_ERROR(errctx);
@@ -668,6 +845,9 @@ int main(void)
 	CATCH(errctx, test_draw_preserves_render_draw_color());
 	CATCH(errctx, test_draw_backend_without_a_renderer());
 	CATCH(errctx, test_draw_background());
+	CATCH(errctx, test_draw_filled_rounded_rect());
+	CATCH(errctx, test_draw_arc());
+	CATCH(errctx, test_draw_set_clip());
    } CLEANUP {
 	SDL_Quit();
    } PROCESS(errctx) {
--- a/tests/error.c
+++ b/tests/error.c
@@ -33,7 +33,8 @@ akerr_ErrorContext *test_error_init_owns_the_status_band(void)
 	{ AKGL_ERR_HEAP,           "Heap Error"      },
 	{ AKGL_ERR_BEHAVIOR,       "Behavior Error"  },
 	{ AKGL_ERR_LOGICINTERRUPT, "Logic Interrupt" },
-	{ AKGL_ERR_COLLISION,      "Collision Error" }
+	{ AKGL_ERR_COLLISION,      "Collision Error" },
+	{ AKGL_ERR_UI,             "UI Error"        }
    };
    bool named = true;
    int i = 0;
--- a/tests/sprite.c
+++ b/tests/sprite.c
@@ -240,6 +240,10 @@ int main(void)
 {
    PREPARE_ERROR(errctx);

+    SDL_SetHint(SDL_HINT_VIDEO_DRIVER, "dummy");
+    SDL_SetHint(SDL_HINT_AUDIO_DRIVER, "dummy");
+    SDL_SetHint(SDL_HINT_RENDER_DRIVER, "software");
+
    ATTEMPT {
 	CATCH(errctx, akgl_error_init());
 	akgl_renderer = &akgl_default_renderer;
--- a/tests/tilemap.c
+++ b/tests/tilemap.c
@@ -740,6 +740,10 @@ int main(void)
 {
    PREPARE_ERROR(errctx);

+    SDL_SetHint(SDL_HINT_VIDEO_DRIVER, "dummy");
+    SDL_SetHint(SDL_HINT_AUDIO_DRIVER, "dummy");
+    SDL_SetHint(SDL_HINT_RENDER_DRIVER, "software");
+
    ATTEMPT {
 	CATCH(errctx, akgl_error_init());
 	akgl_gamemap = &akgl_default_gamemap;
--- a/tests/ui.c
+++ b/tests/ui.c