Give BASIC menus, dialogs and HUD labels over libakgl's UI helpers

Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought
in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that
wanted a title screen had to draw one out of CHAR and GETKEY, which is
what both breakout tutorials make a reader do.

The interesting part is the impedance mismatch. libakgl's UI is immediate
mode -- widgets are re-declared inside a frame bracket every frame and
clay borrows their text until the bracket closes -- and a BASIC program
says MENU 1, "START" on line 100 and expects it up on line 900, several
hundred frames later. So src/ui_akgl.c is retained on this side and
immediate on that one: the record's entry points are setters that copy
into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set
once a frame from the host's pump. No BASIC string, which lives in the
per-line value pool, is ever what clay is handed.

The shapes are borrowed rather than invented. MENU retires the way SOLID
does -- no entries retires one, no arguments retire them all. GETMENU
holds the step loop the way GETKEY does, so parking is not blocking: the
step still returns, the host keeps its frame rate, and the sprite, audio
and collision services keep running underneath because they run before
the blocking checks. RMENU(n,1) reads and clears the way BUMP() does.
Withdrawing the device or retiring the menu releases a holding GETMENU
with 0 rather than wedging the script, which is akbasic_input_service()'s
rule for a withdrawn keyboard.

One thing a program has to know, and docs/19-user-interface.md says it
twice: a menu that is up owns the cursor keys and Return. It has to, and
retiring it gives them back -- forget the MENU n before an INPUT and the
INPUT never sees the Return that ends it.

akbasic_runtime_set_ui() is its own function rather than a fifth argument
to akbasic_runtime_set_devices(), whose signature has twenty-eight call
sites in tests and documentation that are about something else.

deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead
centre, so HUD offers exactly those five; TODO.md records what a
top-centre and bottom-centre would cost upstream, along with the three
other things this deliberately leaves out. No new error code either --
DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free.

tools/screenshot.c had to learn that "needs a font" and "draws the text
grid" are two questions. They were one, and a UI figure came out black:
the text layer owns every pixel of the rows it covers and painted over
the widgets. The new ui=1 fence attribute asks for the first without the
second; MAINTENANCE.md documents it.

112/112 in both configurations, 112/112 under ASan and UBSan, coverage
94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and
100% of functions, doxygen clean, and the four new figures byte-identical
on a re-render. TODO.md section 8's gate table was stale on several
counts besides these and is refreshed with measured numbers.

Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL

tests/mockdevice.h

@@ -25,6 +25,7 @@
 #include <akbasic/graphics.h>
 #include <akbasic/input.h>
 #include <akbasic/sprite.h>
+#include <akbasic/ui.h>
 
 /** @brief Room for the call log. Longer than any test needs; overflow truncates loudly. */
 #define MOCK_LOG_SIZE		8192
@@ -60,6 +61,15 @@ typedef struct
     akbasic_Contact contact;	/* what the next contact() call describes	*/
     bool hascontact;
     int patternbytes[AKBASIC_MAX_SPRITES];  /* bytes the last define() carried, per sprite */
+
+    /*
+     * UI. The verbs are setters rather than draw calls, so what a test asserts
+     * is both the call sequence *and* what the backend now holds -- a MENU that
+     * logged correctly and stored nothing would still be broken.
+     */
+    int menuselected[AKBASIC_UI_MAX_MENUS];
+    bool menuactivated[AKBASIC_UI_MAX_MENUS];
+    int menucount[AKBASIC_UI_MAX_MENUS];
 } akbasic_MockDevice;
 
 static akbasic_MockDevice MOCK;
@@ -67,6 +77,7 @@ static akbasic_GraphicsBackend MOCK_GRAPHICS;
 static akbasic_AudioBackend MOCK_AUDIO;
 static akbasic_InputBackend MOCK_INPUT;
 static akbasic_SpriteBackend MOCK_SPRITES;
+static akbasic_UiBackend MOCK_UI;
 
 /**
  * @brief Append one formatted call to the log.
@@ -483,6 +494,106 @@ static akerr_ErrorContext *mock_spr_contact(akbasic_SpriteBackend *self, int n,
 
 /* ---------------------------------------------------------------- fixture -- */
 
+/* --------------------------------------------------------------------- ui -- */
+
+static akerr_ErrorContext *mock_ui_dialog(akbasic_UiBackend *self, const char *text)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+    mock_log("dialog %s\n", (text != NULL) ? text : "(none)");
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_ui_label(akbasic_UiBackend *self, int slot, int anchor, const char *text)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+    mock_log("label %d anchor %d %s\n", slot, anchor, (text != NULL) ? text : "(none)");
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_ui_menu(akbasic_UiBackend *self, int slot, const char *const *items, int count)
+{
+    PREPARE_ERROR(errctx);
+    int i = 0;
+    (void)self;
+
+    FAIL_ZERO_RETURN(errctx, (slot >= 0 && slot < AKBASIC_UI_MAX_MENUS), AKERR_OUTOFBOUNDS,
+		     "mock menu slot %d", slot);
+    mock_log("menu %d count %d", slot, count);
+    for ( i = 0; i < count; i++ ) {
+	mock_log(" [%s]", (items != NULL && items[i] != NULL) ? items[i] : "(null)");
+    }
+    mock_log("\n");
+    MOCK.menucount[slot] = count;
+    MOCK.menuselected[slot] = 0;
+    MOCK.menuactivated[slot] = false;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_ui_menu_state(akbasic_UiBackend *self, int slot, int *selected, bool *activated, bool clear)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    FAIL_ZERO_RETURN(errctx, (selected != NULL && activated != NULL), AKERR_NULLPOINTER,
+		     "NULL destination in mock_ui_menu_state");
+    FAIL_ZERO_RETURN(errctx, (slot >= 0 && slot < AKBASIC_UI_MAX_MENUS), AKERR_OUTOFBOUNDS,
+		     "mock menu slot %d", slot);
+    *selected = MOCK.menuselected[slot];
+    *activated = MOCK.menuactivated[slot];
+    if ( clear ) {
+	MOCK.menuactivated[slot] = false;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_ui_style(akbasic_UiBackend *self, akbasic_Color *fill, akbasic_Color *edge, akbasic_Color *ink, double padding, double radius)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    if ( fill == NULL || edge == NULL || ink == NULL ) {
+	mock_log("style default\n");
+	SUCCEED_RETURN(errctx);
+    }
+    mock_log("style #%02x%02x%02x #%02x%02x%02x #%02x%02x%02x pad %.1f radius %.1f\n",
+	     fill->r, fill->g, fill->b, edge->r, edge->g, edge->b,
+	     ink->r, ink->g, ink->b, padding, radius);
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_ui_clear(akbasic_UiBackend *self)
+{
+    PREPARE_ERROR(errctx);
+    int i = 0;
+    (void)self;
+
+    mock_log("uiclear\n");
+    for ( i = 0; i < AKBASIC_UI_MAX_MENUS; i++ ) {
+	MOCK.menucount[i] = 0;
+	MOCK.menuselected[i] = 0;
+	MOCK.menuactivated[i] = false;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Stand in for the player choosing an entry.
+ *
+ * The one thing a mock has to be able to do that no verb can: a real activation
+ * comes from a keystroke libakgl consumed, and there is no keyboard here.
+ */
+__attribute__((unused))
+static void mock_menu_choose(int slot, int selected)
+{
+    if ( slot < 0 || slot >= AKBASIC_UI_MAX_MENUS ) {
+	return;
+    }
+    MOCK.menuselected[slot] = selected;
+    MOCK.menuactivated[slot] = true;
+}
+
 /** @brief Reset the recorder and populate all three vtables. */
 __attribute__((unused))
 static void mock_devices_init(void)
@@ -542,6 +653,14 @@ static void mock_devices_init(void)
     MOCK_SPRITES.shape		= mock_spr_shape;
     MOCK_SPRITES.solid		= mock_spr_solid;
     MOCK_SPRITES.contact	= mock_spr_contact;
+
+    MOCK_UI.self		= &MOCK;
+    MOCK_UI.dialog		= mock_ui_dialog;
+    MOCK_UI.label		= mock_ui_label;
+    MOCK_UI.menu		= mock_ui_menu;
+    MOCK_UI.menu_state		= mock_ui_menu_state;
+    MOCK_UI.style		= mock_ui_style;
+    MOCK_UI.clear		= mock_ui_clear;
 }
 
 /** @brief Set what the next collisions() call will report. Bit n-1 is sprite n. */