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

docs/10-embedding.md

@@ -138,8 +138,12 @@ script's output to a file while you draw.
 
 ```c wrap=hostbody
 PASS(e, akbasic_runtime_set_devices(&RUNTIME, &graphics, &audio, &input, &sprites));
+PASS(e, akbasic_runtime_set_ui(&RUNTIME, &ui));
 ```
 
+The fifth one is set on its own rather than as a fifth argument to the first, because
+that signature predates it and had twenty-eight call sites that do not care about menus.
+
 Any of them may be `NULL`, and that is how you withhold a capability: a script given no
 audio backend gets an error from `SOUND` rather than silence. Each is a record of
 function pointers, so you can supply your own and never link the graphics library at

docs/11-verb-reference.md

@@ -32,6 +32,7 @@ for the reasoning in each case.
 | `DCLOSE` | `DCLOSE [n]` | Close channel `n`, or every channel. |
 | `DEF` | `DEF NAME(args) = expr` | Define a function. Multi-line definitions end in `RETURN`. |
 | `DELETE` | `DELETE [n][-n]` | Delete lines, with the same range forms as `LIST`. |
+| `DIALOG` | `DIALOG ["text"]` | Show a text panel across the bottom of the screen. No argument takes it down. See Chapter 19. |
 | `DIM` | `DIM A#(n [,...])` | Make an array. Subscripts start at zero; `n` is the count. |
 | `DIM` … `AS` | `DIM S@ AS T`, `DIM P@ AS PTR TO T` | Make a structure, or a strict pointer to one. See Chapter 16. |
 | `DIRECTORY` | `DIRECTORY` | **Refused.** Needs a directory-reading wrapper that does not exist yet. |
@@ -49,12 +50,14 @@ for the reasoning in each case.
 | `FOR` | `FOR V = a TO b [STEP c]` | Start a counted loop, ended by `NEXT`. |
 | `GET` | `GET V` | Take a keystroke if one is waiting, without stopping. |
 | `GETKEY` | `GETKEY V` | Wait for a keystroke, holding the program but not the host. |
+| `GETMENU` | `GETMENU n, V%` | Wait for a menu choice, holding the program but not the host. Assigns the entry number. See Chapter 19. |
 | `GOSUB` | `GOSUB line` | Call a subroutine, returning on `RETURN`. |
 | `GOTO` | `GOTO line` | Jump to a line or a label. |
 | `GRAPHIC` | `GRAPHIC mode | CLR` | Choose a screen mode, or clear it. |
 | `GSHAPE` | `GSHAPE A$, x, y` | Stamp a region saved by `SSHAPE`. |
 | `HEADER` | `HEADER "name"` | **Refused.** Formats a disk. |
 | `HELP` | `HELP` | Re-list the line the last error happened on. |
+| `HUD` | `HUD n [,anchor, "text"]` | Pin a line of text to a corner or the centre. No text retires the slot; no arguments retire them all. See Chapter 19. |
 | `IF` | `IF c THEN s [ELSE s]` | Branch. Everything after `THEN` belongs to the condition. |
 | `INPUT` | `INPUT ["prompt"] V` | Read a line from the user. |
 | `INPUT#` | `INPUT #n, V` | Read a line from a channel. |
@@ -65,6 +68,7 @@ for the reasoning in each case.
 | `LOAD` | `LOAD "name"` | The other name for `DLOAD`. |
 | `LOCATE` | `LOCATE x, y` | Move the pixel cursor. |
 | `LOOP` | `LOOP [WHILE c | UNTIL c]` | End a `DO` loop. |
+| `MENU` | `MENU [n [,"item", ...]]` | Show a menu the player picks from. No entries retires it; no arguments retire them all. See Chapter 19. |
 | `MOVSPR` | `MOVSPR n, ...` | Move a sprite. Four forms; see Chapter 8. |
 | `NEW` | `NEW` | Erase the program and every variable. |
 | `NEXT` | `NEXT V` | End a `FOR` loop and advance its counter. |
@@ -106,6 +110,7 @@ for the reasoning in each case.
 | `TROFF` | `TROFF` | Turn line tracing off. |
 | `TRON` | `TRON` | Turn line tracing on; each line prints its number in brackets. |
 | `TYPE` | `TYPE NAME` … `END TYPE` | Declare a record, its fields one per line. See Chapter 16. |
+| `UISTYLE` | `UISTYLE [fill, edge, ink [,pad [,radius]]]` | The one look every widget draws with. No arguments restores the default. See Chapter 19. |
 | `VERIFY` | `VERIFY "name"` | Compare the program in memory against a file. |
 | `VOL` | `VOL n` | Set the overall volume, 0 to 15. |
 | `WAIT` | `WAIT addr, mask [,xor]` | Poll a byte until it matches. Holds the program. |

docs/12-function-reference.md

@@ -28,6 +28,7 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | `RCOLLISION` | 2 | `RCOLLISION(n, f)` | What sprite `n` last collided with and how: what, which, the normal, the depth, the point, and which axis to reverse. See Chapter 8. |
 | `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), the drawing surface's width (1) or height (2) in pixels, or a character cell's width (3) or height (4). |
 | `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
+| `RMENU` | 2 | `RMENU(n, f)` | A menu's state: field 0 the highlighted entry, field 1 whether it has been confirmed. **Reading field 1 clears it.** |
 | `RWINDOW` | 1 | `RWINDOW(f)` | The current text window's rows (0) or columns (1). Field 2 is a C128 screen mode and is refused. |
 | `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
 | `RSPHIT` | 2 | `RSPHIT(n, f)` | One of `SPRHIT`'s settings for sprite `n`, in `SPRHIT`'s own argument order: 0 the kind, 1 to 4 the two corners. |

docs/14-architecture.md

@@ -137,6 +137,7 @@ and the library owns exactly one turn of it.
     +-- mode == QUIT ? ------------------------------------> return
     |
     +-- akbasic_input_service()       GETKEY waiting?  ----->  return  (no line runs)
+    +-- akbasic_ui_service()          GETMENU waiting? ----->  return  (no line runs)
     +-- akbasic_console_update_clock()
     +-- akbasic_console_service()     SLEEP or WAIT holding? -> return
     |
@@ -600,14 +601,15 @@ closed, a host that cannot tolerate that should refuse over-long lines itself.
 
 ## Devices, and how a capability is withheld
 
-The sink and the four device backends are records of function pointers plus whatever
+The sink and the five device backends are records of function pointers plus whatever
 state you hang off `self`. That is the house pattern for anything that varies, and it is
 what keeps SDL out of the core: the whole test suite runs on a machine with no SDL
 installed at all.
 
 ```text
    akbasic_runtime_set_devices(rt, graphics, audio, input, sprites)
-                                  |        |      |      |
+   akbasic_runtime_set_ui(rt, ui)  |        |      |      |
+                              |    |        |      |      |
                           any of them may be NULL, and NULL is not
                           "do nothing" -- it is "refuse by name":
 

docs/19-user-interface.md

@@ -0,0 +1,215 @@
+# 19. Menus and dialogs
+
+Everything in this chapter needs the SDL build and a UI device. Without one each verb
+refuses by name:
+
+```basic requires=noakgl
+10 MENU 1, "START", "QUIT"
+```
+
+```output
+? 10 : RUNTIME ERROR MENU needs a UI device and this runtime has none
+
+```
+
+Every picture in this chapter is generated by running the listing above it; see
+`MAINTENANCE.md` if you are editing one.
+
+## Three widgets, and no fourth
+
+A menu the player picks from, a panel that says something, and a line of text pinned to
+a corner. That is the whole set, and it is the set because it is the set
+[libakgl](../deps/libakgl/docs/22-ui.md) supplies — these verbs are a thin skin over
+`akgl_ui_menu`, `akgl_ui_dialog` and `akgl_ui_label`, and they are deliberately not a
+window toolkit. *What is not here*, at the end, says what to do when you want more.
+
+## MENU
+
+```basic requires=akgl ui=1 screenshot=menu
+10 UISTYLE 1, 8, 2
+20 MENU 1, "START", "OPTIONS", "QUIT"
+```
+
+![](images/menu.png)
+
+`MENU n, item$ [, item$ ...]` puts menu `n` on screen with those entries. `n` runs 1 to
+4, so a pause menu can sit over a title menu, and there are at most 16 entries — that is
+libakgl's own ceiling and not a number invented here.
+
+The player moves the highlight with the cursor keys or a D-pad and confirms with Return
+or a gamepad's south button. The mouse works too: moving onto a row highlights it and
+clicking one confirms it. A pointer sitting still claims nothing, so a mouse parked over
+the list does not fight the keyboard for the highlight.
+
+Defining a menu **resets its highlight to the first entry and forgets any unread
+choice.** The entries have just changed meaning; an index into the old list is not worth
+carrying across, and a stale choice of an entry that no longer exists is worse.
+
+`MENU n` with nothing after it retires that menu. `MENU` on its own retires all four —
+the same convention `SOLID` uses, where no rectangle retires one and no arguments retire
+them all.
+
+## GETMENU
+
+```basic norun
+10 MENU 1, "START", "OPTIONS", "QUIT"
+20 GETMENU 1, C%
+30 ON C% GOTO 500, 600, 900
+```
+
+`GETMENU n, var` parks the program until somebody chooses, then puts the entry's number
+in `var` — 1 for the first — and carries on. The variable has to be a numeric one with a
+sigil, `C%` or `C!`; a bare `C` is a *label* in this dialect and cannot be assigned to at
+all, which is the same rule `GETKEY` keeps.
+
+**Parking is not blocking.** The interpreter never stops returning to its host: while a
+`GETMENU` is unanswered every step comes straight back without advancing the program, so
+the frame rate holds, sprites keep moving, `PLAY` keeps draining its queue, and a game
+that embeds the interpreter stays in control of its own loop. What stops is the program,
+which is the part you asked for.
+
+Two things end the wait without a choice, and both assign 0 rather than leaving the
+program parked forever: retiring the menu, and the host taking the UI device away. A
+script waiting on something that no longer exists is worse than a script told nothing
+happened.
+
+## RMENU
+
+```basic norun
+100 REM the same menu, without parking on it
+110 IF RMENU(1,1) THEN C% = RMENU(1,0) : GOSUB 800
+120 GOSUB 900 : REM move everything else
+130 GOTO 110
+```
+
+`RMENU(n, 0)` is the entry currently highlighted. `RMENU(n, 1)` is -1 once the menu has
+been confirmed and 0 otherwise, **and reading it clears it** — exactly the contract
+`BUMP()` carries, and for the same reason: without it a program that polls in a loop sees
+the same choice forever.
+
+Reading the highlight does not clear anything. Only field 1 consumes.
+
+This is what a game with a loop of its own wants. `GETMENU` is what a title screen wants.
+
+## DIALOG
+
+```basic requires=akgl ui=1 size=480x200 screenshot=dialog
+10 UISTYLE 1, 8, 2
+20 DIALOG "IT IS PITCH BLACK."
+```
+
+![](images/dialog.png)
+
+A panel across the bottom of the screen with wrapped text on it. `DIALOG text$` puts it
+up; `DIALOG` on its own takes it down.
+
+**There is no dismiss key and no return value.** libakgl's dialog has neither — a panel
+is up because the frame declares it — so showing and hiding is the program's business
+and `DIALOG` with no argument *is* the dismissal. The usual shape is a `GETKEY` between
+the two:
+
+```basic norun
+10 DIALOG "YOU FOUND A KEY."
+20 GETKEY K$
+30 DIALOG
+```
+
+The text wraps but does not scroll or page. A message longer than the panel is clipped by
+it, visibly, which is deliberate on libakgl's side: a clipped line is a bug you can see.
+
+## HUD
+
+```basic requires=akgl ui=1 size=480x200 screenshot=hud
+10 UISTYLE 1, 8, 2
+20 HUD 1, 0, "LIVES 3"
+30 HUD 2, 1, "SCORE 00120"
+40 HUD 3, 4, "PAUSED"
+```
+
+![](images/hud.png)
+
+`HUD n, anchor, text$` pins a line of text somewhere on the screen. `n` is a slot, 1 to
+8, and the anchor is one of five places:
+
+| Anchor | Where |
+|---|---|
+| 0 | Top left |
+| 1 | Top right |
+| 2 | Bottom left |
+| 3 | Bottom right |
+| 4 | Centre |
+
+Five, and the numbering is not the reading order, because these are libakgl's five
+`akgl_UiAnchor` values and its numbering. **There is no top-centre or bottom-centre.**
+A title bar is two corners or the middle.
+
+A slot keeps its text until something replaces or retires it, so a score display is one
+`HUD` per change rather than one per frame. `HUD n` retires slot `n` and `HUD` retires
+all eight.
+
+## UISTYLE
+
+```basic requires=akgl ui=1 screenshot=uistyle
+10 UISTYLE 3, 7, 2, 14, 8
+20 MENU 1, "ONE", "TWO"
+30 HUD 1, 0, "STYLED"
+```
+
+![](images/uistyle.png)
+
+`UISTYLE fill, edge, ink [, padding [, radius]]` sets the one look every widget draws
+with. The three colours are ordinary palette indices, 1 to 16, the same ones `COLOR`
+takes. `padding` is the gap in pixels between a panel's edge and its text, and between a
+`HUD` label and the screen edge it hugs; `radius` rounds the corners, and 0 is square.
+Padding defaults to 8 and radius to 0.
+
+`UISTYLE` with no arguments goes back to libakgl's own default, a dark textbox with
+parchment ink. It goes back to the *library's* default rather than to a copy of it, so
+"never styled" and "styled back" stay the same thing.
+
+There is one style, shared. Per-widget looks are not implemented — see below.
+
+## Who owns the keyboard
+
+**A menu that is up owns the cursor keys and Return.** It has to: those are how a menu is
+driven, and something has to have them. While at least one menu has entries, Up, Down and
+Return go to it and never reach `GET`, `GETKEY` or the line editor.
+
+Everything else still gets through — letters, Escape, function keys, the gamepad buttons
+a menu does not use. And retiring the menu gives the keys straight back:
+
+```basic norun
+10 MENU 1, "YES", "NO"
+20 GETMENU 1, C%
+30 MENU 1 : REM now INPUT can have Return again
+40 INPUT "NAME"; N$
+```
+
+Forget line 30 and the `INPUT` on line 40 will never see the Return that ends it. That is
+the one way these verbs can surprise a program, so it is worth the line.
+
+## What is not here
+
+The rest of clay. libakgl builds its widgets on a full immediate-mode layout engine —
+containers, flexible sizing, scrolling regions, images inside panels, custom elements,
+hit-testing any element — and none of that is reachable from BASIC. A verb per clay
+concept would be a second language inside this one.
+
+Specifically absent, and each on purpose:
+
+- **Per-widget styles.** One `UISTYLE`, shared by everything.
+- **Scrolling.** Neither the dialog nor the menu scrolls; 16 entries is the menu's limit
+  and a longer one wants sub-screens.
+- **Top-centre and bottom-centre HUD anchors**, because `akgl_UiAnchor` has neither.
+- **Mouse position, hover state, or clicks on anything but a menu row.** A program cannot
+  ask where the pointer is.
+- **Any way to dismiss a dialog from inside it.**
+
+A game that needs those is writing C against `akgl/ui.h`, which is the route libakgl
+documents for exactly this case, and it can do that in the same window this interpreter
+is drawing into — [Chapter 10](10-embedding.md) is how the two meet.
+
+One cost worth knowing about: libakgl re-rasterizes every line of widget text every
+frame. A `HUD` that changes once a level is free; one rebuilt every frame is the
+expensive case, and a program that has one should say so with `TI#` before blaming the
+interpreter.

docs/README.md

@@ -40,6 +40,7 @@ but the earlier chapters, and 18 assumes it.
 | **[16. Structures](16-structures.md)** | `TYPE`, records, strict pointers, and sharing a C struct with an embedding host |
 | **[17. Tutorial: Breakout](17-tutorial-breakout.md)** | Build a whole game out of the text grid and two `DATA` sprites, in sixteen steps |
 | **[18. Tutorial: Breakout with artwork](18-tutorial-breakout-artwork.md)** | Build it again out of loaded artwork, powerups and a drawn colour HUD, in thirteen |
+| **[19. Menus and dialogs](19-user-interface.md)** | `MENU`, `DIALOG`, `HUD` and `UISTYLE` — the widgets, and who owns the keyboard |
 
 ## The shortest possible start