Generate the documentation's figures from the listings they illustrate

Chapters 6 and 8 described what a verb draws in prose. Eight figures now show
it, and each one is produced by running the BASIC listing printed immediately
above it -- so a picture cannot drift away from the code beside it, which is the
way a screenshot goes wrong and the way nothing notices.

tools/screenshot.c is a second SDL host, much smaller than the frontend: dummy
video driver, software renderer, run to completion, read the target back, write
a PNG. It draws no text layer on purpose, so a READY in the corner is not noise
in a figure about BOX and no font has to be resolved.

tools/docs_screenshots.sh reads the new screenshot=NAME fence tag straight out
of the markdown. size=WxH is the second tag, and SCALE's figure uses it: the
point being made is a 320x200 listing filling a larger window, which cannot be
made on a 320x200 surface.

Two gates, answering different questions. docs_examples fails a tagged block
with no image, in both configurations, so a figure cannot be added and
forgotten. docs_screenshots -- a CTest, AKGL build only -- re-renders every
figure and compares byte for byte, so a listing edited without regenerating
fails. Only the second catches a stale picture.

The PNGs are checked in because a reader on the forge has no build tree, and
docs/images/README.md says loudly that they are generated. Regenerating is never
part of a build: the target is run deliberately, so a make cannot put eight
binary diffs in front of whoever ran it.

Drawing the BOX figure caught a defect in TODO.md itself. Deviation 16 claimed
in bold that BOX fills on a negative angle while its own paragraph said the fill
was filed rather than implemented. BOX cannot fill, and filled_rect is reached
by no verb as a result.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CMakeLists.txt

@@ -192,6 +192,26 @@ if(AKBASIC_WITH_AKGL)
   target_compile_options(akbasic_frontend PRIVATE -Wall -Wextra)
   target_link_libraries(akbasic_frontend PUBLIC akbasic_akgl)
   akbasic_instrument(akbasic_frontend)
+
+  # The documentation's figure generator: a second, much smaller host that draws
+  # one program onto an offscreen target and writes a PNG. Not instrumented and
+  # not a test -- it produces a build artifact rather than an answer, and folding
+  # it into the coverage figure would credit the interpreter for lines only a
+  # documentation build runs.
+  add_executable(akbasic_screenshot tools/screenshot.c)
+  target_compile_options(akbasic_screenshot PRIVATE -Wall -Wextra)
+  target_link_libraries(akbasic_screenshot PRIVATE akbasic_akgl SDL3_image::SDL3_image)
+
+  # Regenerating every figure in docs/ is a deliberate act, never part of a
+  # build: the PNGs are checked in, and a rebuild that silently rewrote them
+  # would put a binary diff in front of anybody who happened to run `make`.
+  add_custom_target(docs_screenshots
+    COMMAND "${CMAKE_CURRENT_SOURCE_DIR}/tools/docs_screenshots.sh"
+            --root "${CMAKE_CURRENT_SOURCE_DIR}"
+            --tool "$<TARGET_FILE:akbasic_screenshot>"
+    DEPENDS akbasic_screenshot
+    COMMENT "Regenerating the documentation figures in docs/images"
+    VERBATIM)
 endif()
 
 # ---------------------------------------------------------------------------
@@ -370,6 +390,28 @@ if(AKBASIC_WITH_AKGL)
     WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
     TIMEOUT 180
     SKIP_RETURN_CODE 77)
+
+  # Every figure in docs/ re-rendered and byte-compared against the checked-in
+  # copy. docs_examples only asks whether the file *exists*, which catches a
+  # figure that was never generated and not one that stopped being of the code
+  # beside it -- and that second failure is the one this whole arrangement is
+  # against.
+  #
+  # **A byte comparison of a rendered PNG is a deliberate bet**, the same bet
+  # tests/reference/ already makes about golden output: that the dummy video
+  # driver and the software renderer are reproducible. They are, run to run and
+  # build to build. What is untested is an SDL upgrade that shifts one pixel of
+  # a diagonal, and the answer to that is to regenerate the figures in the same
+  # commit as the bump -- not to weaken this to a size check, which would pass
+  # for every wrong picture that happened to be 320x200.
+  _add_test(NAME docs_screenshots
+    COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/tools/docs_screenshots.sh
+            --root "${CMAKE_CURRENT_SOURCE_DIR}"
+            --tool $<TARGET_FILE:akbasic_screenshot>
+            --check)
+  _set_tests_properties(docs_screenshots PROPERTIES
+    TIMEOUT 120
+    ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_AUDIODRIVER=dummy;SDL_RENDER_DRIVER=software")
 endif()
 
 # ---------------------------------------------------------------------------