Rewrite the two game tutorials as instructions rather than commentary

Chapters 17 and 18 read as a code review of a finished listing: they explained
why each decision had been made, walked through the project's own history, and
led with what had once been broken. A reader who wanted to build the game got
the reasoning and had to reconstruct the program.

Both are now step-by-step. Each opens with a picture of the finished game and a
bullet list of the steps, each bullet is a section, and each section states its
goal, shows the code, and says how to check it. Chapter 17 is sixteen steps and
Chapter 18 is thirteen, and the last of each is the assembly: the order of the
file, the full declaration block, and the routines the earlier steps referred to.
Project history is gone -- it belongs in Chapter 14 and in git -- and where a
listing has to do something awkward, the tutorial shows how first and names the
`TODO.md` item that will make it unnecessary second.

**Three defects had no entry anywhere**, which the rewrite found by trying to
state each rule as a rule. §6 item 35: `a - b + c` computes `a - (b + c)`,
because `subtraction()` sits above `addition()` as its own precedence level and
the inner loop eats the `+`. Item 36: only one unparenthesised `AND` or `OR` is
matched, which is item 12's `if`-where-`while` on the one operator pair item 12
did not reach. Item 37: a `GOTO` out of a `FOR` or a `DO` leaks the loop's scope,
so a main loop written that way stops on the thirty-second lost life -- which is
why both games are built out of `LABEL` and `GOTO`, and it is a workaround rather
than a preference. Chapter 3 gains the identifier rule the third trial ran into:
there is no underscore in a name, and the error says `UNKNOWN TOKEN _`.

**`tools/screenshot.c` learned to draw the text layer**, behind a new `text=1`
fence attribute, because Chapter 17's game is characters in the grid and a figure
without that layer is two sprites on black. It opens the bundled font at the size
the standalone frontend uses, so a figure's cell size is the reader's cell size,
and it uses the akgl sink alone rather than a tee so the program's output lands in
the picture instead of on the stdout the caller reads to decide a figure failed.
Both new figures -- `breakout-game.png` and `breakout-game-artwork.png` -- are
generated from listings in the chapters like every other one.

Verified by handing each chapter, alone, to an agent on a much smaller model and
telling it to build the game from the tutorial text with the `examples/` tree off
limits. The first pass scored 3.5 and 3 out of 10 and named what was missing:
routines referred to but never shown, the third level layout, the sprite `DATA`,
the font table, edits to earlier routines that were never marked as edits. Those
are now in. The second pass built a 658-line Chapter 17 game that plays itself
for ninety seconds with the score at 1890 and no error line, and the third built
a 1053-line Chapter 18 game with 61 labels, no invented routines, no gaps found,
and forty seconds clean. 9/10 and 8/10.

One real bug in the new prose, caught in review: Chapter 18's `HITBAR` did not
set the `HIT#` that `BALLPADDLE` reads to decide whether the paddle already
caught the ball. Both suites green in both configurations, `docs_examples` and
`docs_screenshots --check` pass.

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

tools/screenshot.c

@@ -16,10 +16,23 @@
  * completion, read the target back, write it out. deps/libakgl/tests/draw.c and
  * tests/akgl_backends.c set that pattern; this is the third user of it.
  *
- * **The text layer is deliberately not drawn.** A screenshot in the graphics
- * chapter is of the drawing, and a `READY` in the corner is noise in a figure
- * about `CIRCLE`. It also means no font has to be found, which keeps this
- * runnable from a build tree with no assets resolved.
+ * **The text layer is not drawn unless a font is named.** A screenshot in the
+ * graphics chapter is of the drawing, and a `READY` in the corner is noise in a
+ * figure about `CIRCLE`; leaving the layer out also means no font has to be
+ * found, which keeps this runnable from a build tree with no assets resolved.
+ *
+ * A figure of a program whose *output is text* needs the opposite, and
+ * docs/17-tutorial-breakout.md is one: that game's wall, HUD and messages are
+ * characters in the grid, so a picture without the text layer is a picture of
+ * two sprites on a black field. Naming a font as the fifth argument swaps the
+ * stdio sink for the akgl one and renders the grid before the sprites, in the
+ * same order src/frontend_akgl.c uses. The fence attribute that asks for it is
+ * `text=1`; tools/docs_screenshots.sh turns that into this argument.
+ *
+ * The sink is the akgl one *alone* rather than a tee, so a program's output
+ * lands in the picture rather than on stdout -- which is what the caller reads
+ * to decide a figure failed. Nothing is lost: `screenshot=` blocks are also run
+ * by tests/docs_examples.sh, which is where a raised error is caught.
  */
 
 #include <stdio.h>
@@ -28,6 +41,7 @@
 
 #include <SDL3/SDL.h>
 #include <SDL3_image/SDL_image.h>
+#include <SDL3_ttf/SDL_ttf.h>
 
 #include <akerror.h>
 
@@ -46,6 +60,7 @@
 
 #include <akbasic/akgl.h>
 #include <akbasic/error.h>
+#include <akbasic/frontend.h>
 #include <akbasic/runtime.h>
 #include <akbasic/sink.h>
 
@@ -53,6 +68,9 @@
 static akbasic_Runtime RUNTIME;
 static akbasic_TextSink SINK;
 static akbasic_StdioSink SINKSTATE;
+/** @brief The text grid, and the font behind it. Only used when one is named. */
+static akbasic_AkglSink GRIDSTATE;
+static TTF_Font *FONT = NULL;
 static akbasic_GraphicsBackend GRAPHICS;
 static akbasic_AkglGraphics GRAPHICSSTATE;
 static akbasic_SpriteBackend SPRITES;
@@ -68,10 +86,13 @@ static char SOURCE[65536];
 static void usage(void)
 {
     fprintf(stderr,
-	    "usage: akbasic_screenshot <program.bas> <output.png> [width] [height]\n"
+	    "usage: akbasic_screenshot <program.bas> <output.png> [width] [height] [font.ttf]\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");
+	    "  (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");
 }
 
 /** @brief Slurp the program. A figure's listing is small; a partial read is not tolerated. */
@@ -98,7 +119,8 @@ static akerr_ErrorContext AKERR_NOIGNORE *read_program(const char *path)
  * Split out so the ATTEMPT in main() has one thing to CATCH and the SDL
  * teardown has one place to happen.
  */
-static akerr_ErrorContext AKERR_NOIGNORE *draw_program(const char *outpath, int w, int h)
+static akerr_ErrorContext AKERR_NOIGNORE *draw_program(const char *outpath, int w, int h,
+						       const char *fontpath)
 {
     PREPARE_ERROR(errctx);
     SDL_Surface *shot = NULL;
@@ -132,9 +154,22 @@ static akerr_ErrorContext AKERR_NOIGNORE *draw_program(const char *outpath, int
     FAIL_ZERO_RETURN(errctx, SDL_RenderClear(akgl_renderer->sdl_renderer),
 		     AKGL_ERR_SDL, "%s", SDL_GetError());
 
-    /* stdout: a program that errors puts its "? line : CLASS message" there,
-       which is what the caller shows when a figure comes out wrong. */
-    PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL));
+    /*
+     * With no font: stdout, so a program that errors puts its
+     * "? line : CLASS message" where the caller reads it. With one: the grid,
+     * so the characters the program writes are in the picture. The file comment
+     * explains why the two are not teed together.
+     */
+    if ( fontpath == NULL ) {
+	PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL));
+    } else {
+	FAIL_ZERO_RETURN(errctx, TTF_Init(), AKGL_ERR_SDL,
+			 "Couldn't initialize SDL_ttf: %s", SDL_GetError());
+	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));
+    }
     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));
@@ -144,11 +179,16 @@ static akerr_ErrorContext AKERR_NOIGNORE *draw_program(const char *outpath, int
     PASS(errctx, akbasic_runtime_run(&RUNTIME, 0));
 
     /*
-     * The drawing verbs are immediate and are already on the target. Sprites are
-     * not: they are libakgl actors and reach the target through a render pass,
-     * which in the standalone frontend is part of a frame. There is no frame
-     * here, so this is it.
+     * The drawing verbs are immediate and are already on the target. The text
+     * grid and the sprites are not: both are redrawn from state the interpreter
+     * keeps, which in the standalone frontend happens once a frame. There is no
+     * frame here, so this is it -- and the order is the frontend's, grid first
+     * and sprites over it, because that ordering is what a program written
+     * against the real host will have assumed.
      */
+    if ( fontpath != NULL ) {
+	PASS(errctx, akbasic_sink_akgl_render(&SINK));
+    }
     PASS(errctx, akbasic_sprite_akgl_render(&SPRITES));
 
     shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
@@ -167,6 +207,7 @@ int main(int argc, char **argv)
     PREPARE_ERROR(errctx);
     int w = 320;
     int h = 200;
+    const char *fontpath = NULL;
 
     if ( argc < 3 ) {
 	usage();
@@ -178,6 +219,9 @@ int main(int argc, char **argv)
     if ( argc > 4 ) {
 	h = atoi(argv[4]);
     }
+    if ( argc > 5 && argv[5][0] != '\0' ) {
+	fontpath = argv[5];
+    }
     if ( w <= 0 || h <= 0 ) {
 	usage();
 	return 2;
@@ -194,8 +238,13 @@ int main(int argc, char **argv)
 
     ATTEMPT {
 	CATCH(errctx, read_program(argv[1]));
-	CATCH(errctx, draw_program(argv[2], w, h));
+	CATCH(errctx, draw_program(argv[2], w, h, fontpath));
     } CLEANUP {
+	if ( FONT != NULL ) {
+	    TTF_CloseFont(FONT);
+	    FONT = NULL;
+	    TTF_Quit();
+	}
 	if ( akgl_window != NULL ) {
 	    SDL_DestroyWindow(akgl_window);
 	    akgl_window = NULL;