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

tools/docs_screenshots.sh

@@ -111,25 +111,31 @@ FONT="${ROOT}/assets/fonts/C64_Pro_Mono-STYLE.ttf"
 # One figure: write the listing to a file, run it, keep the PNG.
 render()
 {
-    local name="$1" body="$2" size="$3" where="$4" setup="$5" text="$6"
-    local w=320 h=200 out="${OUTDIR}/${name}.png" log="" font=""
+    local name="$1" body="$2" size="$3" where="$4" setup="$5" text="$6" ui="$7"
+    local w=320 h=200 out="${OUTDIR}/${name}.png" log="" font="" grid=""
 
     if [ -n "${size}" ]; then
 	w="${size%x*}"
 	h="${size#*x}"
     fi
 
+    # Two separate questions, and they were one until the UI verbs arrived.
     # `text=1` says this program's output is characters rather than drawing, so
-    # the tool has to render the grid -- see the comment at the head of
-    # tools/screenshot.c. Everything else gets no font and no text layer.
-    if [ -n "${text}" ]; then
+    # the tool has to render the grid. `ui=1` says it draws widgets, which need a
+    # font but must not have the grid -- the text layer owns every pixel of the
+    # rows it covers and would black the picture out underneath them. Both need
+    # the font; only `text=1` asks for the layer.
+    if [ -n "${text}" ] || [ -n "${ui}" ]; then
 	if [ ! -r "${FONT}" ]; then
-	    echo "FAIL ${where}: text=1 needs a font at ${FONT}" >&2
+	    echo "FAIL ${where}: text=1 and ui=1 need a font at ${FONT}" >&2
 	    FAILURES=$((FAILURES + 1))
 	    return
 	fi
 	font="${FONT}"
     fi
+    if [ -n "${text}" ]; then
+	grid="1"
+    fi
 
     # The same setup scripts tests/docs_examples.sh uses, run in the same place
     # relative to the program. A listing that loads `ship.png` needs one whether
@@ -153,7 +159,7 @@ render()
     # stderr, so merging the two would make every sprite figure look like a
     # failing program. stderr is shown when the tool itself refuses, which is
     # when it is worth reading.
-    if ! log="$(cd "${WORK}" && "${TOOL}" "${name}.bas" "${out}" "${w}" "${h}" "${font}" \
+    if ! log="$(cd "${WORK}" && "${TOOL}" "${name}.bas" "${out}" "${w}" "${h}" "${font}" "${grid}" \
 			  2>"${WORK}/${name}.err")"; then
 	echo "FAIL ${where}: ${name} did not render" >&2
 	cat "${WORK}/${name}.err" >&2
@@ -214,7 +220,7 @@ for DOC in "${DOCS[@]}"; do
 		if [ -n "${NAME}" ]; then
 		    render "${NAME}" "${BODY}" "$(attr size "${INFO}")" \
 			   "${DOC}:${START}" "$(attr setup "${INFO}")" \
-			   "$(attr text "${INFO}")"
+			   "$(attr text "${INFO}")" "$(attr ui "${INFO}")"
 		fi
 	    fi
 	    ;;

tools/screenshot.c

@@ -75,6 +75,8 @@ static akbasic_GraphicsBackend GRAPHICS;
 static akbasic_AkglGraphics GRAPHICSSTATE;
 static akbasic_SpriteBackend SPRITES;
 static akbasic_AkglSprites SPRITESSTATE;
+static akbasic_UiBackend UI;
+static akbasic_AkglUi UISTATE;
 /*
  * No `window` of our own: akgl/game.h declares one as an unprefixed extern --
  * libakgl's TODO calls that a defect and it is -- so a static here shadows it
@@ -86,13 +88,15 @@ static char SOURCE[65536];
 static void usage(void)
 {
     fprintf(stderr,
-	    "usage: akbasic_screenshot <program.bas> <output.png> [width] [height] [font.ttf]\n"
+	    "usage: akbasic_screenshot <program.bas> <output.png> [width] [height] [font.ttf] [grid]\n"
 	    "\n"
 	    "  Runs the program against an offscreen renderer of the given size\n"
 	    "  (default 320x200) and writes what it drew as a PNG.\n"
 	    "\n"
-	    "  Naming a font draws the text grid as well, for a figure of a\n"
-	    "  program whose output is characters rather than drawing.\n");
+	    "  Naming a font lends the program a UI device, because the widgets\n"
+	    "  draw text and cannot come up without one. Passing 1 for `grid` as\n"
+	    "  well draws the text layer, for a figure of a program whose output\n"
+	    "  is characters rather than drawing.\n");
 }
 
 /** @brief Slurp the program. A figure's listing is small; a partial read is not tolerated. */
@@ -120,7 +124,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *read_program(const char *path)
  * teardown has one place to happen.
  */
 static akerr_ErrorContext AKERR_NOIGNORE *draw_program(const char *outpath, int w, int h,
-						       const char *fontpath)
+						       const char *fontpath, bool grid)
 {
     PREPARE_ERROR(errctx);
     SDL_Surface *shot = NULL;
@@ -160,6 +164,14 @@ static akerr_ErrorContext AKERR_NOIGNORE *draw_program(const char *outpath, int
      * so the characters the program writes are in the picture. The file comment
      * explains why the two are not teed together.
      */
+    /*
+     * The font and the text grid are two separate questions, and they were one
+     * until the UI verbs arrived. A widget draws text, so a UI figure needs a
+     * font -- but it does not want the grid, which owns every pixel of the rows
+     * it covers and would paint the picture black before the widgets landed on
+     * it. So `fontpath` says "there is a font" and `grid` says "draw the text
+     * layer too".
+     */
     if ( fontpath == NULL ) {
 	PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL));
     } else {
@@ -168,12 +180,21 @@ static akerr_ErrorContext AKERR_NOIGNORE *draw_program(const char *outpath, int
 	FONT = TTF_OpenFont(fontpath, (float)AKBASIC_FRONTEND_FONT_SIZE);
 	FAIL_ZERO_RETURN(errctx, (FONT != NULL), AKGL_ERR_SDL,
 			 "Couldn't open the font %s: %s", fontpath, SDL_GetError());
-	PASS(errctx, akbasic_sink_init_akgl(&SINK, &GRIDSTATE, akgl_renderer, FONT, w, h));
+	if ( grid ) {
+	    PASS(errctx, akbasic_sink_init_akgl(&SINK, &GRIDSTATE, akgl_renderer, FONT, w, h));
+	} else {
+	    PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL));
+	}
     }
     PASS(errctx, akbasic_runtime_init(&RUNTIME, &SINK));
     PASS(errctx, akbasic_graphics_init_akgl(&GRAPHICS, &GRAPHICSSTATE, akgl_renderer));
     PASS(errctx, akbasic_sprite_init_akgl(&SPRITES, &SPRITESSTATE, akgl_renderer, &GRAPHICSSTATE));
     PASS(errctx, akbasic_runtime_set_devices(&RUNTIME, &GRAPHICS, NULL, NULL, &SPRITES));
+    if ( fontpath != NULL ) {
+	PASS(errctx, akbasic_ui_init_akgl(&UI, &UISTATE, akgl_renderer, fontpath,
+					  AKBASIC_FRONTEND_FONT_SIZE, w, h));
+	PASS(errctx, akbasic_runtime_set_ui(&RUNTIME, &UI));
+    }
     PASS(errctx, akbasic_runtime_load(&RUNTIME, SOURCE));
     PASS(errctx, akbasic_runtime_start(&RUNTIME, AKBASIC_MODE_RUN));
     PASS(errctx, akbasic_runtime_run(&RUNTIME, 0));
@@ -186,10 +207,14 @@ static akerr_ErrorContext AKERR_NOIGNORE *draw_program(const char *outpath, int
      * and sprites over it, because that ordering is what a program written
      * against the real host will have assumed.
      */
-    if ( fontpath != NULL ) {
+    if ( grid ) {
 	PASS(errctx, akbasic_sink_akgl_render(&SINK));
     }
     PASS(errctx, akbasic_sprite_akgl_render(&SPRITES));
+    /* Last, and over everything, exactly as src/frontend_akgl.c orders it. */
+    if ( fontpath != NULL ) {
+	PASS(errctx, akbasic_ui_akgl_render(&UI));
+    }
 
     shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
     FAIL_ZERO_RETURN(errctx, (shot != NULL), AKGL_ERR_SDL,
@@ -208,6 +233,7 @@ int main(int argc, char **argv)
     int w = 320;
     int h = 200;
     const char *fontpath = NULL;
+    bool grid = false;
 
     if ( argc < 3 ) {
 	usage();
@@ -222,6 +248,9 @@ int main(int argc, char **argv)
     if ( argc > 5 && argv[5][0] != '\0' ) {
 	fontpath = argv[5];
     }
+    if ( argc > 6 && argv[6][0] == '1' ) {
+	grid = true;
+    }
     if ( w <= 0 || h <= 0 ) {
 	usage();
 	return 2;
@@ -238,8 +267,9 @@ int main(int argc, char **argv)
 
     ATTEMPT {
 	CATCH(errctx, read_program(argv[1]));
-	CATCH(errctx, draw_program(argv[2], w, h, fontpath));
+	CATCH(errctx, draw_program(argv[2], w, h, fontpath, grid));
     } CLEANUP {
+	akbasic_ui_akgl_shutdown(&UI);
 	if ( FONT != NULL ) {
 	    TTF_CloseFont(FONT);
 	    FONT = NULL;