Finish the language: every remaining verb group, and the defects that blocked them

Closes groups A, C, D, E, F, H and J of TODO.md section 4, plus RESTORE and
RENUMBER, and closes section 6 -- all seventeen reference defects. Seven of
those turned out to have been fixed or never ported and nobody had written it
down; the audit records the evidence for each.

Two of the seventeen were real. math_plus mutated its left operand when the
operand was mutable, so A# + 1 could modify A#; it was gated on FOR/NEXT
coverage because NEXT relied on the mutation, so tests/for_next.c came first
and NEXT now writes the counter back itself. And the binary operators summed
both numeric fields of their right operand, which no BASIC program can reach
-- that one needed a test written against the value API.

Writing the tests turned up eight defects nobody had listed. Seven are fixed:

  IF A = 2 THEN was a parse error; only == worked
  IF ... AND ... was a parse error, because a condition parsed as one relation
  IF A = 1 OR B = 2 THEN was silently always false, and so was IF A THEN
  EXIT before any NEXT restarted the program and exhausted the variable pool
  READ never found a DATA line above it, and swallowed the lines between
  PRINT 2 + 2 at the prompt was filed as program text instead of answering
  a short read discarded its bytes, so COPY produced empty files
  every verb taking an argument list said "peek() returned nil token!" on none

The eighth is not fixed and cannot be quietly: a FOR whose step overshoots
runs its body one extra time, and FOR I = 1 TO 1 runs it zero times. The two
errors cancel for a step of 1, which is why neither was noticed. Correcting
them changes the expected output of a checked-in acceptance file, and
tests/reference/README.md forbids editing one to suit this interpreter. It is
tests/for_semantics.c in AKBASIC_KNOWN_FAILING_TESTS, asserting the correct
contract, and TODO.md items 19 and 20.

Sprites are real libakgl actors with a renderfunc of their own, because
akgl_actor_render draws every sprite square and an actor has no per-axis
scale. Both are filed upstream. SPRSAV takes an image file, an SSHAPE handle
or a 63-element integer array -- a string here cannot hold a zero byte.

Verbs that need hardware that does not exist are refused by name with the
reason rather than faked: SYS, HEADER, COLLECT, BACKUP, BOOT, FILTER, and
DIRECTORY, which is refused for a missing libakstdlib wrapper filed upstream.

94 tests in the default build, 93 with SDL, 94 under ASan and UBSan, doxygen
clean. The Go acceptance corpus stayed green throughout.

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

CLAUDE.md

@@ -42,6 +42,14 @@ In priority order:
    the work queue. A few entries are deliberately out of scope on a modern PC and marked so there
    (`BANK`, `FAST`, `MONITOR`); keep that reasoning rather than reviving them.
 
+   **Group H (sprites) is done.** `src/runtime_sprite.c` and `src/sprite_akgl.c`. libakgl's
+   sprite JSON turned out not to be in the way: `akgl_sprite_load_json()` is a thin wrapper over
+   four initializers plus writes to public struct fields, and every field it fills from a
+   document is something a Commodore sprite does not have. The one thing that *did* survive into
+   the verb syntax is the image path — `SPRSAV "ship.png", 1` goes through `akgl_path_relative()`
+   and `akgl_spritesheet_initialize()`, the same calls the JSON loader makes. `SPRDEF` is out of
+   scope with `BANK`/`FAST`/`MONITOR`: it is an interactive editor, not a programmable verb.
+
    **When `libakgl` cannot supply a capability a verb needs, do not work around it here.** Add a TODO
    item to `deps/libakgl/TODO.md` describing the missing API — what the BASIC verb requires, what the
    `akgl_*` entry point should look like, and what tests would cover it — and follow the numbered,
@@ -88,7 +96,7 @@ that repo is next touched. See the error-code section below for a live collision
 |---|---|---|---|---|
 | `deps/libakerror` | 1.0.0 | `libakerror.so.1` | major only | **none** — no version macro, no `ConfigVersion` file |
 | `deps/libakstdlib` | 0.2.0 | `libakstdlib.so.0.2` | **`MAJOR.MINOR` while major is 0** | `AKSL_VERSION_*`, `aksl_version()`, `AKSL_VERSION_CHECK()` |
-| `deps/libakgl` | 0.3.0 | `libakgl.so.0.3` | **`MAJOR.MINOR` while major is 0** | `AKGL_VERSION*`, `akgl_version()`, `AKGL_VERSION_AT_LEAST()` |
+| `deps/libakgl` | 0.4.0 | `libakgl.so.0.4` | **`MAJOR.MINOR` while major is 0** | `AKGL_VERSION*`, `akgl_version()`, `AKGL_VERSION_AT_LEAST()` |
 
 For both 0.x libraries the soname carries `MAJOR.MINOR` deliberately: 0.1 and 0.2 are *different*
 ABIs, and both become major-only at 1.0. Do not read `0.1 → 0.2` as a compatible bump — and both

CMakeLists.txt

@@ -114,10 +114,13 @@ endfunction()
 # process-terminating call, and buildable with no libakgl present.
 # ---------------------------------------------------------------------------
 set(AKBASIC_SOURCES
+  src/args.c
   src/audio_tables.c
+  src/data.c
   src/environment.c
   src/error.c
   src/grammar.c
+  src/format.c
   src/graphics_tables.c
   src/parser.c
   src/parser_commands.c
@@ -125,13 +128,22 @@ set(AKBASIC_SOURCES
   src/runtime.c
   src/runtime_audio.c
   src/runtime_commands.c
+  src/runtime_console.c
+  src/runtime_disk.c
+  src/runtime_format.c
   src/runtime_functions.c
   src/runtime_graphics.c
   src/runtime_housekeeping.c
+  src/runtime_machine.c
+  src/renumber.c
   src/runtime_input.c
+  src/runtime_sprite.c
+  src/runtime_structure.c
+  src/runtime_trap.c
   src/scanner.c
   src/sink_stdio.c
   src/sink_tee.c
+  src/sprite_tables.c
   src/symtab.c
   src/value.c
   src/variable.c
@@ -165,6 +177,7 @@ if(AKBASIC_WITH_AKGL)
     src/graphics_akgl.c
     src/input_akgl.c
     src/sink_akgl.c
+    src/sprite_akgl.c
   )
   target_compile_options(akbasic_akgl PRIVATE -Wall -Wextra)
   target_link_libraries(akbasic_akgl PUBLIC akbasic akgl)
@@ -233,22 +246,33 @@ endif()
 # ---------------------------------------------------------------------------
 set(AKBASIC_TESTS
   audio_verbs
+  console_verbs
   devices
+  disk_verbs
   environment_scope
   error_codes
+  for_next
+  format_verbs
   grammar_leaves
   graphics_verbs
   hostvars
   housekeeping_verbs
   input_verbs
+  interrupts
+  machine_verbs
   numeric_contract
   parser_commands
   parser_expressions
+  read_data
+  renumber
   runtime_evaluate
   runtime_verbs
   scanner_tokens
   sink_stdio
   sink_tee
+  sprite_verbs
+  structure_verbs
+  trap_verbs
   symtab
   value_arithmetic
   value_bitwise
@@ -266,6 +290,7 @@ set(AKBASIC_WILL_FAIL_TESTS
 # The next defect that has to be reproduced before it can be fixed goes here, and
 # the machinery to do that should not have to be reinvented.
 set(AKBASIC_KNOWN_FAILING_TESTS
+  for_semantics
 )
 
 foreach(_test IN LISTS AKBASIC_TESTS AKBASIC_WILL_FAIL_TESTS AKBASIC_KNOWN_FAILING_TESTS)

README.md

@@ -102,6 +102,14 @@ The Go project is deprecated and will not be updated, so the two are **no longer
 
 That corpus lives at [`tests/reference/`](tests/reference/README.md), copied byte for byte out of the Go project. Its README records where it came from and the rule for changing it: **diverge deliberately, never by accident.** A failure there means this interpreter's behaviour changed — nine times in ten that is a bug you just introduced, and the tenth time it is an improvement that should move the expectation, say why, and add a line to `TODO.md` §5.
 
+## The guide
+
+A full multi-chapter guide lives in [`docs/`](docs/README.md), organised the way the
+C128 Programmer's Reference Guide is: the language, then each hardware area, then a
+reference section for every verb and function. If you already write BASIC 7.0, start
+with [Chapter 13](docs/13-differences.md) — it is the list of everything that behaves
+differently here, and why.
+
 ## Case Sensitivity
 
 The old computers BASIC was originally written on only had CAPITAL LETTER KEYS on their keyboards. Modern keyboards have the indescribable luxury of upper and lower case. In this basic, verbs and function names are case insensitive. Variable names are case sensitive.
@@ -140,6 +148,10 @@ Expressions can be grouped with `()` arbitrarily deeply. Currently the interpret
 The following commands/verbs are implemented:
 
 * `AUTO n` : Turn automatic line numbering on/off at increments of `n`
+* `COLLISION t [, line-or-label]` : Call a subroutine when sprites collide. Type 1 only;
+  omitting the target disarms it. The handler is entered between source lines and must end in
+  `RETURN`, exactly as a `GOSUB` body does. Types 2 (sprite-to-background) and 3 (light pen)
+  are refused by name
 * `REM` : everything after this is a comment
 * `DATA LITERAL[, ...]`: Define a series of literal values that can be read by a preceding `READ` verb
 * `DEF FN(X, ...) = expression` : Define a function with arguments that performs a given expression. See also "Subroutines", below.
@@ -182,6 +194,26 @@ The following commands/verbs are implemented:
 * `RETURN` : return from `GOSUB` to the point where it was called
 * `RUN [n]`: Run the program currently in memory, optionally starting at line `n`
 * `STOP`: Stop program execution at the current point. `CONT` resumes from there
+* `MOVSPR n, ...` : Move a sprite. Four forms, and the separators are what tell them apart:
+  * `MOVSPR n, x, y` — put it at (x, y) in BASIC's 320x200 space
+  * `MOVSPR n, +x, -y` — move it *by* that much; a signed coordinate is an offset
+  * `MOVSPR n, d ; a` — move it `d` pixels along bearing `a`, in degrees clockwise from
+    straight up. Distance first, then angle
+  * `MOVSPR n, a # s` — set it moving along bearing `a` at speed `s` (0-15, 0 stops). Nothing
+    moves on the statement itself: the sprite moves as the program runs, paced off the host's
+    clock
+* `SPRCOLOR [c1] [, c2]` : Set the two colour registers every multicolour sprite shares. Either
+  may be omitted, which leaves that register alone
+* `SPRITE n [,on] [,colour] [,priority] [,xexpand] [,yexpand] [,multicolour]` : Configure a
+  sprite. Only the number is required, and an omitted argument leaves that attribute alone
+* `SPRSAV source, n` : Give sprite `n` an image. Three kinds of source:
+  * `SPRSAV "ship.png", n` — an image file. Tried against the working directory first and then
+    against the directory the running program was loaded from, so a program stored beside its
+    art works from anywhere. The sprite takes the image's own size
+  * `SPRSAV A$, n` — a region `SSHAPE` saved
+  * `SPRSAV A#, n` — 63 elements of a DIMmed integer array, three bytes per row and twenty-one
+    rows, most significant bit leftmost. This is the `DATA`-driven form; it takes an integer
+    array rather than a string because a string here cannot hold a zero byte
 * `SWAP A, B`: Exchange two variables of the same type, arrays and their dimensions included
 * `TRON` / `TROFF`: Turn line tracing on and off. A traced program prints `[10][20]` inline
   ahead of each line, as a C128 does
@@ -195,6 +227,7 @@ The following functions are implemented
 
 * `ABS(x#|x%)`: Return the absolute value of the float or integer argument
 * `ATN(x#|x%)`: Return the arctangent of the float or integer argument. Input and output are in radians.
+* `BUMP(1)`: Return a bitmask of which sprites have collided since the last call — bit 0 is sprite 1. **Reading clears it**, which is what makes "has anything hit me since I last looked" answerable at all. Type 1 (sprite-to-sprite) only
 * `CHR(x#)`: Return the character value of the UTF-8 unicode codepoint in x#. Returns as a string.
 * `COS(x#|x%)`: Return the cosine of the float or integer argument. Input and output are in radians.
 * `HEX(x#)`: Return the string representation of the integer number in x#
@@ -208,6 +241,9 @@ The following functions are implemented
 * `POINTER(X)`: Return the address in memory for the value of the variable identified in X. This is the direct integer, float or string value stored, it is not a reference to the internal variable structure.
 * `POINTERVAR(X)` : Return the address in memory of the variable X. This is the address of the internal `akbasic_Variable` structure, which includes additional metadata about the variable, in addition to the value. For a pointer directly to the value, use `POINTER`.
 * `RAD(X#|X%)`: Convert degrees to radians
+* `RSPCOLOR(F#)`: Return one of `SPRCOLOR`'s two shared registers — 1 or 2
+* `RSPPOS(N#, F#)`: Return sprite `N#`'s x (0), y (1) or speed (2)
+* `RSPRITE(N#, F#)`: Return one of sprite `N#`'s `SPRITE` settings, in `SPRITE`'s own argument order: enabled (0), colour (1), priority (2), x-expand (3), y-expand (4), multicolour (5)
 * `RIGHT(X$, Y#)`: Return the rightmost Y# characters of the string in X$. Y# is clamped to LEN(X$).
 * `SGN(X#)`: Returns the sign of X# (-1 for negative, 1 for positive, 0 if 0).
 * `SHL(X#, Y#)`: Returns the value of X# shifted left Y# bits
@@ -415,7 +451,11 @@ target_link_libraries(YOUR_GAME PRIVATE akbasic::akbasic)
 
 Both are off by default, which is why the interpreter and its whole test suite build on a machine with no SDL.
 
-The graphics, sound and console verbs reach hardware through records of function pointers on the runtime — `akbasic_GraphicsBackend`, `akbasic_AudioBackend` and `akbasic_InputBackend`, attached with `akbasic_runtime_set_devices()`. All three may be `NULL`, which is what a default build of the standalone driver gives them: a verb that needs a device it was not given raises rather than crashing, and a `PRINT`-only program never notices. An SDL build attaches all three. A host that renders some other way supplies its own records and never links `libakgl` at all.
+The graphics, sound, console and sprite verbs reach hardware through records of function pointers on the runtime — `akbasic_GraphicsBackend`, `akbasic_AudioBackend`, `akbasic_InputBackend` and `akbasic_SpriteBackend`, attached with `akbasic_runtime_set_devices()`. All four may be `NULL`, which is what a default build of the standalone driver gives them: a verb that needs a device it was not given raises rather than crashing, and a `PRINT`-only program never notices. An SDL build attaches all four. A host that renders some other way supplies its own records and never links `libakgl` at all.
+
+**Sprites are real `libakgl` actors.** Each of BASIC's eight becomes a `SpriteSheet`, a `Sprite`, a `Character` and an `Actor` registered in `AKGL_REGISTRY_ACTOR`, so a host game sees a script's sprites alongside its own and can do anything to them it can do to an actor. `akbasic_sprite_akgl_render()` draws them; a host that never calls it gets a script whose sprite state is correct and whose sprites are never drawn. None of it goes through libakgl's sprite JSON — a Commodore sprite has no frame list, no animation speed and no state map — except for `SPRSAV "ship.png", n`, which resolves and loads through exactly the calls the JSON loader makes.
+
+If you drive the interpreter without `akbasic_frontend_akgl_init()`, sprites need three things from you that `akgl_game_init()` would otherwise have done: `akgl_heap_init()`, `akgl_registry_init()`, and a `camera` pointing somewhere. `akgl_actor_render()` dereferences that global without checking it. `src/frontend_akgl.c` is the worked example.
 
 Two things about those verbs that differ from a real C128, because both would otherwise surprise you. `PLAY` does not block — it queues its notes and `akbasic_runtime_step()` releases them against whatever time you last passed to `akbasic_runtime_settime()`, so the statement after a `PLAY` runs immediately. And `GETKEY` holds the program without blocking you: the step still returns, it simply does not advance until a key arrives.
 
@@ -455,40 +495,56 @@ Plus six more the original already carried: a leading `0` selects base 8, so `PR
 
 ## Not implemented
 
-* Multiple statements on one line (e.g. `10 PRINT A$ : REM This prints the thing`). The `COLON` token exists and nothing consumes it.
+This list was checked against the dispatch table in `src/verbs.c` when it was last edited. It
-* Using an array reference inside a parameter list (e.g. `READ A$(0), B#`) results in parsing errors
+had drifted badly before that -- it named a third of the language as missing after it had
-* `APPEND`, `BACKUP`, `BEGIN`, `BEND`, `BLOAD`, `BOOT`, `BOX`, `BSAVE`
+landed -- so check it the same way rather than trusting it.
-* `CATALOG`, `CHAR`, `CIRCLE`, `CLOSE`, `CLR`, `CMD`, `COLLECT`, `COLLISION`, `COLOR`, `CONCAT`, `CONT`, `COPY`
+
-* `DCLEAR`, `DCLOSE`, `DIRECTORY`, `DOPEN`, `DRAW`, `DVERIFY`
+* `APPEND`, `BACKUP`, `BLOAD`, `BOOT`, `BSAVE`
-* `DO`, `LOOP`, `WHILE`, `UNTIL`. You can do the same thing with `IF` and `GOTO`.
+* `BEGIN`, `BEND`, `DO`, `LOOP`, `WHILE`, `UNTIL`, `END`, `ON`. You can do the same thing with `IF` and `GOTO`.
-* `END`, `ENVELOPE`, `ER`, `ERR`
+* `CATALOG`, `CHAR`, `CLOSE`, `CMD`, `COLLECT`, `CONCAT`, `COPY`
-* `FETCH`, `FILTER`
+* `DCLEAR`, `DCLOSE`, `DIRECTORY`, `DOPEN`, `DVERIFY`
-* `GET`, `GETKEY`, `GRAPHIC`, `GSHAPE`
+* `ER`, `ERR`, `TRAP`, `RESUME`
-* `HEADER`, `HELP`
+* `FETCH`, `STASH`, `SYS`
-* `KEY`, `LOAD`, `LOCATE`
+* `HEADER`, `KEY`, `LOAD`, `SAVE`, `SCRATCH`, `RENAME`, `VERIFY`
-* `MOVSPR`, `NEW`, `ON`, `PAINT`, `PLAY`, `PUDEF`
+* `PUDEF`, `RENUMBER`, `RESTORE`
-* `RENAME`, `RENUMBER`, `RESTORE`, `RESUME`
+* `SLEEP`, `TI`, `WAIT`, `WIDTH`, `WINDOW`, `USING`
-* `SAVE`, `SCALE`, `SCNCLR`, `SCRATCH`, `SLEEP`, `SOUND`
+* `SPRDEF`
-* `SPRCOLOR`, `SPRDEF`, `SPRITE`, `SPRSAV`, `SSHAPE`, `STASH`, `SWAP`, `SYS`
-* `TEMPO`, `TI`, `TRAP`, `TROFF`, `TRON`
-* `USING`, `VERIFY`, `VOL`, `WAIT`, `WIDTH`, `WINDOW`
 * The I/O-channel variants (`GETIO`, `INPUTIO`, `OPENIO`, `PRINTIO`, `RECORDIO`)
 
-One of those is still blocked on a missing `libakgl` capability, and it is only one. Four were — text measurement, immediate-mode drawing, audio, and a non-blocking keystroke read — and rather than work around them here they were filed in [`deps/libakgl/TODO.md`](deps/libakgl/TODO.md) under "API gaps blocking akbasic". All four have since landed upstream (`akgl_text_measure`, the `akgl_draw_*` family, `akgl_audio_*`, and `akgl_controller_poll_key`), so what is left is akbasic-side work.
+`FILTER` parses and is then refused, which is a third state and deliberate. It sets the SID's
+filter cutoff, band switches and resonance; `akgl_audio_*` synthesises raw waveforms and mixes
+them, there is no filter stage to configure, and SDL3 supplies no primitive to build one from.
+Until an `akgl_audio_filter()` exists it refuses at execution rather than being silently
+ignored -- a program that asks for a low-pass and gets an unfiltered square wave has been lied
+to.
 
-The exception is `FILTER`, which sets the SID's filter cutoff, band switches and resonance. `akgl_audio_*` synthesises raw waveforms and mixes them; there is no filter stage to configure, and SDL3 supplies no primitive to build one from. Until an `akgl_audio_filter()` exists, `FILTER` parses and then refuses at execution rather than being silently ignored — a program that asks for a low-pass and gets an unfiltered square wave has been lied to.
+It is the only verb still blocked on a missing `libakgl` capability. Four others were -- text
+measurement, immediate-mode drawing, audio, and a non-blocking keystroke read -- and rather
+than work around them here they were filed in
+[`deps/libakgl/TODO.md`](deps/libakgl/TODO.md) under "API gaps blocking akbasic". All four have
+since landed upstream (`akgl_text_measure`, the `akgl_draw_*` family, `akgl_audio_*`, and
+`akgl_controller_poll_key`), so what is left is akbasic-side work.
+
+Building the sprite verbs turned up three more, none of which blocks a verb. An actor is drawn
+square regardless of its sprite's height (libakgl's own defect 26) and an actor cannot be scaled
+per axis (filed from here); both are worked around by installing a `renderfunc` of ours on each
+actor. The third — an error context leaked per relative asset path resolved — was found and
+fixed upstream in 0.4.0 while this was being written.
 
 ## Deliberately out of scope
 
 * `BANK` - the modern PC memory layout is incompatible with the idea of bank switching
 * `FAST` - Irrelevant on modern PC CPUs
 * `MONITOR` - there is no machine-language monitor to drop into
+* `SPRDEF` - an interactive full-screen sprite editor driven by single keystrokes, not a
+  programmable verb. A program cannot call it usefully and this interpreter does not own the
+  screen it would take over. `SPRSAV`'s three source forms are what replace it
 
 # Dependencies
 
 * [libakerror](https://source.starfort.tech/andrew/libakerror) 1.0.0 — TRY/CATCH-style error contexts. Every function that can fail returns one.
 * [libakstdlib](https://source.starfort.tech/andrew/libakstdlib) 0.2.0 — libc wrappers that report through `libakerror`.
-* [libakgl](https://source.starfort.tech/andrew/libakgl) 0.3.0 — **optional**, only for `-DAKBASIC_WITH_AKGL=ON`. Pulls in SDL3. 0.3.0 closed every API gap this project had filed against it, so there are no libakgl workarounds left here.
+* [libakgl](https://source.starfort.tech/andrew/libakgl) 0.4.0 — **optional**, only for `-DAKBASIC_WITH_AKGL=ON`. Pulls in SDL3. 0.3.0 closed every API gap this project had filed against it; 0.4.0 is a leak-and-overread release. It changed no public struct, but the soname carries `MAJOR.MINOR` while the major is 0, so rebuild rather than relink.
 * [basicinterpret](https://source.starfort.tech/andrew/basicinterpret) — the Go original. Vendored as the behavioural spec for questions about semantics, and for nothing else: its acceptance corpus and its Commodore font are checked in here now, so **the build and the test suite do not need it**. Not linked, not built, and safe to omit.
 
 Everything is a submodule; `git submodule update --init --recursive` gets all of it. There is nothing to install first.

TODO.md

@@ -623,37 +623,58 @@ Order by what unblocks the most, and by what does not need `libakgl` to grow fir
 
 | Group | Verbs | Blocked on |
 |---|---|---|
-| A. Structure | `DO`, `LOOP`, `WHILE`, `UNTIL`, `ON`, `BEGIN`, `BEND`, `END` | nothing — reuses `waitingForCommand` |
+| ~~A. Structure~~ | ~~`DO`, `LOOP`, `WHILE`, `UNTIL`, `ON`, `BEGIN`, `BEND`, `END`~~ | **done** — `src/runtime_structure.c`, `tests/structure_verbs.c` |
 | ~~B. Housekeeping~~ | ~~`NEW`, `CLR`, `CONT`, `SWAP`, `TRON`, `TROFF`, `HELP`~~ | **done** — `src/runtime_housekeeping.c`, `tests/housekeeping_verbs.c` |
-| B′. Housekeeping, deferred | `RESTORE`, `RENUMBER` | neither is small; see below |
+| ~~B′. Housekeeping, deferred~~ | ~~`RESTORE`, `RENUMBER`~~ | **done** — `src/data.c` and `src/renumber.c`, `tests/read_data.c` and `tests/renumber.c` |
-| C. Errors | `TRAP`, `RESUME`, `ER`, `ERR` | needs a BASIC-visible error object |
+| ~~C. Errors~~ | ~~`TRAP`, `RESUME`, `ER`, `ERR`~~ | **done** — `src/runtime_trap.c`, `tests/trap_verbs.c`. `ER`/`EL` are `ER#`/`EL#`; see §5 |
-| D. Strings/format | `USING`, `PUDEF`, `WIDTH`, `CHAR` | nothing |
+| ~~D. Strings/format~~ | ~~`USING`, `PUDEF`, `WIDTH`, `CHAR`~~ | **done** — `src/format.c`, `src/runtime_format.c`, `tests/format_verbs.c` |
-| E. Console | `WINDOW`, `KEY`, `SLEEP`, `WAIT`, `TI` | the sink, or the clock `akbasic_runtime_settime()` now carries |
+| ~~E. Console~~ | ~~`WINDOW`, `KEY`, `SLEEP`, `WAIT`, `TI`~~ | **done** — `src/runtime_console.c`, `tests/console_verbs.c` |
-| F. Disk | `DOPEN`, `DCLOSE`, `APPEND`, `RECORD`, `HEADER`, `COLLECT`, `BACKUP`, `COPY`, `CONCAT`, `RENAME`, `SCRATCH`, `DIRECTORY`, `CATALOG`, `DCLEAR`, `DVERIFY`, `SAVE`, `LOAD`, `VERIFY`, `BLOAD`, `BSAVE`, `BOOT` | `aksl_f*` only; no new akgl |
+| ~~F. Disk~~ | ~~all 21~~ | **done** — `src/runtime_disk.c`, `tests/disk_verbs.c`. Five refuse for want of a drive and `DIRECTORY` for want of an upstream wrapper; see §5 |
 | ~~G. Graphics~~ | ~~`GRAPHIC`, `DRAW`, `BOX`, `CIRCLE`, `PAINT`, `COLOR`, `SCALE`, `SSHAPE`, `GSHAPE`, `LOCATE`~~ | **done** — `src/runtime_graphics.c`, `tests/graphics_verbs.c` |
-| H. Sprites | `SPRITE`, `MOVSPR`, `SPRCOLOR`, `SPRDEF`, `SPRSAV`, `COLLISION` | `libakgl` sprite/actor API — check before filing |
+| ~~H. Sprites~~ | ~~`SPRITE`, `MOVSPR`, `SPRCOLOR`, `SPRSAV`, `COLLISION`~~ | **done** — `src/runtime_sprite.c`, `src/sprite_akgl.c`, `tests/sprite_verbs.c`. `SPRDEF` is out of scope; see below |
 | ~~I. Audio~~ | ~~`PLAY`, `SOUND`, `ENVELOPE`, `VOL`, `TEMPO`~~ | **done** — `src/runtime_audio.c`, `src/play.c`, `tests/audio_verbs.c` |
 | I′. Audio, still gapped | `FILTER` | `libakgl` has no filter stage and SDL3 supplies no primitive; refused with `AKBASIC_ERR_DEVICE`. `SOUND`'s sweep arguments used to be here and landed with `akgl_audio_sweep` in libakgl 0.3.0 |
 | ~~E′. Console input~~ | ~~`GET`, `GETKEY`, `SCNCLR`~~ | **done** — `src/runtime_input.c`, `tests/input_verbs.c` |
-| J. Machine | `SYS`, `FETCH`, `STASH`, `POKE`/`PEEK` variants | nothing |
+| ~~J. Machine~~ | ~~`SYS`, `FETCH`, `STASH`~~ | **done** — `src/runtime_machine.c`, `tests/machine_verbs.c`. `SYS` is refused by name; see §5 |
 
 **`RESTORE` and `RENUMBER` are deferred, and neither is a small job.**
 
-- **`RESTORE` needs a DATA pointer, and there isn't one.** `READ` does not read: it declares
+- ~~**`RESTORE` needs a DATA pointer, and there isn't one.**~~ **Done.** Every `DATA` statement
-  that the *next* `DATA` line reached in execution order should fill its identifiers, and skips
+  is pre-scanned into one flat list before the program runs -- `src/data.c`, called from
-  forward until one turns up (`akbasic_cmd_read`, ported faithfully). There is no cursor into a
+  `akbasic_runtime_set_mode()` beside the label prescan -- and `READ` walks a cursor along it.
-  list of `DATA` items, so there is nothing for `RESTORE` to reset. Implementing it honestly
+  `RESTORE` resets the cursor; `RESTORE (line)` moves it to the first item on or after that
-  means implementing the pointer, which is worth doing on its own merits, because the current
+  line.
-  arrangement has a defect the corpus does not catch: **a `DATA` line that appears *before* its
+
-  `READ` is never found**, so `10 DATA 1,2` / `20 READ A#` runs off the end of the program in
+  It fixed two defects on the way, both of which were consequences of `READ` not reading.
-  silence, and a second `READ` re-reads the same line rather than continuing. The fix is a
+  **A `DATA` line above its `READ` is now found**, where skipping forward from the `READ` used
-  pre-scan of every `DATA` statement into a flat list plus a read cursor, at which point
+  to run off the end of the program in silence. And **the lines between a `READ` and its `DATA`
-  `RESTORE [line]` is three lines. Its own commit, with the golden cases the change would need.
+  now execute**, where the skip used to swallow them -- a C128 runs them, because `READ` takes
-- **`RENUMBER` has to rewrite references or it is worse than useless.** Moving lines is easy —
+  the next item and execution carries on. The one corpus case has its `DATA` immediately after
-  source is filed under its line number in `source[]`. Rewriting every `GOTO`, `GOSUB`, `THEN`,
+  its `READ`, so neither was observable there. `tests/read_data.c`.
-  `ELSE`, `RUN` and `LIST` target to match is the job, and doing it on source text means
+
-  distinguishing a line number from a digit inside a string literal. Refusing it is better than
+  `DATA` at run time is now a no-op: it is a declaration, and reaching the statement means
-  a `RENUMBER` that silently breaks every branch in the program.
+  walking past it.
+
+- ~~**`RENUMBER` has to rewrite references or it is worse than useless.**~~ **Done.**
+  `src/renumber.c` builds the whole old-to-new map first, then rewrites every line -- including
+  lines *before* the renumbered region, which can branch into it -- and only then moves them.
+
+  The rewrite is textual and understands exactly one thing about the rest of the language:
+  where a string literal starts and stops, so `PRINT "GOTO 10"` survives. `GOTO`, `GOSUB`,
+  `RUN`, `RESTORE` and `TRAP` targets are rewritten, and so is the comma-separated list after
+  `ON X GOTO` -- for free, since the targets follow the `GOTO`. `COLLISION` is special-cased
+  because its handler is its *second* argument.
+
+  Two deliberate non-rewrites. **A target naming a line that does not exist is left alone**:
+  `GOTO 9999` in a program with no line 9999 is already broken, and inventing a destination
+  would hide that. And **`THEN`/`ELSE` do not take bare line numbers in this dialect** -- the
+  corpus writes `THEN GOTO 100` -- so a number after `THEN` is an expression, not a target.
+
+  A renumbering that would land a moved line on a kept one is refused before anything is
+  written, because losing a line to a renumbering is not recoverable.
+
+  **A program written with labels needs none of this.** `GOTO DONE` is unaffected by any
+  renumbering, which is the strongest argument for `LABEL` there is.
 
 `LOCATE` used to appear in both E and G. It belongs to G alone: in BASIC 7.0 `LOCATE` moves the
 *graphics* pixel cursor that `DRAW` starts from, and the text cursor verb is `CHAR`, which is
@@ -661,7 +682,21 @@ already in group D.
 
 **Out of scope, and staying that way** — the reference marks these as incompatible with a
 modern PC and that reasoning stands: `BANK` (no bank switching), `FAST` (irrelevant CPU speed
-control), `MONITOR` (no machine-language monitor).
+control), `MONITOR` (no machine-language monitor). **`SPRDEF` joins them** on the same
+reasoning: it is not a programmable verb but an interactive full-screen sprite editor, driven
+by single keystrokes and its own cursor. A program cannot call it usefully and this interpreter
+does not own the screen it would take over. The three `SPRSAV` source forms are what replace it.
+
+**The `libakgl` JSON layer turned out not to be in the way at all.** Group H was parked on
+"check the sprite/actor API before filing", and the concern was that libakgl's sprites are
+described by JSON documents that would be cumbersome to reach through BASIC.
+`akgl_sprite_load_json()` is a thin wrapper over `akgl_spritesheet_initialize` +
+`akgl_sprite_initialize` + writes to public struct fields, and every field it fills from a
+document — frame list, animation speed, loop flags, state-to-sprite map — is something a
+Commodore sprite does not have. So `src/sprite_akgl.c` builds the same four objects directly.
+The one field that *did* survive into the verb syntax is the spritesheet's filename:
+`SPRSAV "ship.png", 1` goes through `akgl_path_relative()` and `akgl_spritesheet_initialize()`,
+which is the same pair of calls the JSON loader makes.
 
 Also on the queue, from the reference's own defect list:
 
@@ -940,6 +975,278 @@ deviations from the reference's *program*: `main.go` and the SDL half of
     when that arm is the one not taken — with an `ELSE` the last arm is `ELSE`, without one it
     is `THEN`. That is one line of code and it reads as an oddity without the table above it.
 
+### Deviations in the structure and error verbs (groups A and C)
+
+44. **A whole loop on one line does not loop.** `DO : PRINT 1 : LOOP` runs once, exactly as
+    `FOR I=1 TO 3 : PRINT I : NEXT I` does. Block skipping walks *source lines*, which is the
+    reference's `waitingForCommand` model (§1.6), so a `LOOP` on the same line as its `DO` is
+    never reached as a separate step. Fixing it means making the skip operate on statements
+    rather than lines — a deliberate piece of work, already noted in §4 against `FOR`.
+
+45. **`ER` and `EL` are `ER#` and `EL#`.** A C128 exposes them as bare reserved names. This
+    dialect cannot: an identifier carries its type in a suffix, and a name without one is a
+    *label*. They are written into the global scope when a trap fires, so `PRINT ER#` reads the
+    way the rest of the language does and needs no new syntax.
+
+    `ER#` carries the `libakerror` status code, not a Commodore error number — 515 for an
+    out-of-bounds subscript rather than C128 error 9. There is no correspondence to reproduce:
+    the errors this interpreter raises are not the errors a 1985 ROM raised. `ERR(ER#)` gives
+    the name, and that is the part a program should be printing anyway.
+
+46. **`END` does not arm `CONT`.** A C128 lets `CONT` resume after `END` as well as after
+    `STOP`. Here `END` means the program finished, and continuing from a finished program
+    resumes at whatever line happens to follow — so `CONT` refuses instead. `STOP` still arms it.
+
+### Deviations in the format verbs (group D)
+
+47. **`PRINT USING` renders one field per statement.** BASIC 7.0 lets a format string hold
+    several fields and `PRINT USING` take a list of values against them. Here the *first* field
+    is used and any literal text around it is copied through, so `PRINT USING "A: ###"; X` works
+    and `PRINT USING "### ###"; X, Y` does not. Multiple fields need `PRINT` to take a value
+    list, which it does not yet — a separate piece of work from the field rendering itself,
+    which `src/format.c` does properly.
+
+    Exponential fields (`^^^^`) are not implemented either. Nothing in the language produces a
+    value that needs one, since `PRINT` renders a float with `%f`.
+
+48. **`WIDTH` is emulated with parallel passes.** It sets the thickness of drawn lines, and
+    neither the graphics backend record nor `akgl_draw_line` takes a thickness — so a `WIDTH 2`
+    line is drawn twice, offset one pixel along whichever axis the line does *not* mostly run
+    along. Visually right at the only other value the verb accepts; a general thickness would
+    want a real perpendicular offset and an API that takes one.
+
+49. **`CHAR` ignores its colour argument, and needs a sink that has a cursor.** The text sink
+    draws in one colour, chosen by the host when it built the sink, so a per-call colour would
+    have to become part of the sink interface. The argument is accepted and ignored rather than
+    refused, because refusing it would make every published `CHAR` line a syntax error.
+
+    Positioning is a new optional `moveto` on the sink record. A stdio sink leaves it NULL and
+    `CHAR` refuses by name — a terminal's cursor is not this library's to move and a pipe has no
+    cursor at all — so `CHAR` works in an AKGL build and says why it cannot in a stdio one.
+
+### Deviations in the console verbs (group E)
+
+50. **`SLEEP` and `WAIT` hold the step loop; they do not block.** §1.6 forbids blocking, so a
+    waiting program is one that does not *advance* — `akbasic_runtime_step()` still returns, a
+    bounded `akbasic_runtime_run()` still comes back on time, and an embedded game keeps its
+    frame rate while a script sleeps.
+
+    `SLEEP` with no host clock does nothing at all rather than waiting forever. A deadline
+    computed from a clock that never advances is never reached, and the first version of this
+    hung the test suite proving it.
+
+51. **`TI` and `TI$` are `TI#` and `TI$`.** Same reason as `ER#`/`EL#`: no bare variable names.
+    They are ordinary globals refreshed once per step from the host's clock, rather than
+    pseudo-variables, because this dialect has no mechanism for a name that computes itself.
+    A host that never sets a clock gets a stopped clock rather than a wrong one.
+
+52. **`WAIT` polls ordinary process memory.** On a C128 the byte is a hardware register an
+    interrupt is changing. Here nothing changes it but the host, another thread, or a `POKE`
+    from a `TRAP` handler — so a program that waits on a byte nobody writes waits forever, which
+    is exactly what the same program does on a C128 with the wrong address. Read through a
+    `volatile` pointer, because the whole point is that something outside this program writes it.
+
+53. **`KEY` stores its macros and nothing expands them.** The definitions are kept and bare
+    `KEY` lists them, which is the half that is this library's business. Expanding a macro when
+    a function key is pressed belongs to whatever owns the keyboard — the frontend's line editor
+    — and the input backend delivers keycodes rather than editor commands.
+
+### Deviations in the machine verbs (group J)
+
+54. **`FETCH` and `STASH` are the same byte copy.** On a C128 they differ by which side is the
+    RAM Expansion Unit — `STASH` writes out to it, `FETCH` reads back. There is no expansion
+    unit and there are no banks, so both are `memmove` between two addresses and saying so is
+    better than inventing a distinction. `memmove` rather than `memcpy` because a program
+    shifting a buffer along by a few bytes overlaps its own source, which is a normal ask.
+
+    Addresses are real process addresses, which is the decision `POKE`, `PEEK` and `POINTER`
+    already made. There is no bounds check and there cannot be one: a wrong address is a
+    segmentation fault, not an error message.
+
+55. **`SYS` is refused by name.** It calls machine code at an address. There is no 6502 and no
+    ROM to call, so there is nothing to jump to and nothing sensible to emulate — and jumping to
+    a real address in this process would be a way to crash it on purpose. It parses first and
+    refuses second, so a listing containing `SYS` still loads and still lists; only running it
+    fails, and it says why.
+
+    Same reasoning as `BANK`, `FAST` and `MONITOR`, with one difference: those have no table row
+    at all, and `SYS` has a handler because it is common enough in published listings to deserve
+    a specific message rather than "Unknown command".
+
+### Deviations in the disk verbs (group F)
+
+56. **There is no 1541, so the verbs split three ways.** The ones that mean something on a
+    filesystem are implemented against `aksl_f*` — `DOPEN`, `DCLOSE`, `APPEND`, `RECORD`,
+    `SCRATCH`, `RENAME`, `COPY`, `CONCAT`, `BSAVE`, `BLOAD`, `VERIFY`. The ones that are
+    spellings of verbs already here are aliases: `SAVE` is `DSAVE`, `LOAD` is `DLOAD`, `CATALOG`
+    is `DIRECTORY`, `DVERIFY` is `VERIFY`.
+
+    **`HEADER`, `COLLECT`, `BACKUP` and `BOOT` are refused by name**, with the reason. Each
+    operates on a physical disk — formatting one, validating its block allocation map,
+    duplicating it, booting from it — and a filesystem has no equivalent that is not a lie.
+    `HEADER` would have to mean "delete everything in this directory", which is a
+    spectacularly bad thing to do to somebody who typed a C128 verb. `DCLEAR` is the exception:
+    resetting a drive also closes its channels, and closing the channels is real, so that is
+    what it does.
+
+57. **`DIRECTORY` is refused for want of an upstream wrapper.** `libakstdlib` has no
+    `aksl_opendir`, and this project's rule is that a missing capability is filed upstream
+    rather than worked around — so it is filed in `deps/libakstdlib/TODO.md` and the verb says
+    so. Calling `opendir(3)` here would mean reporting through `errno` in a file where
+    everything else reports through an `akerr_ErrorContext *`.
+
+58. **`PRINT #` and `INPUT #` need the space before the `#`.** A C128 writes `PRINT#1,A$`. The
+    scanner reads `#` as a type suffix, so `PRINT#` comes out as an identifier named `PRINT`
+    with an integer suffix — and a verb name carrying a suffix is refused (deviation 30). With
+    a space the `#` is its own token and the parse handler reads it.
+
+59. **`RECORD` counts lines, not fixed-length records.** A C128's relative file has a record
+    length fixed when the file was created; a filesystem file has none. So a record is a line
+    and `RECORD` rewinds and reads forward to it, which is slower than a seek and is the only
+    definition that does not invent a record length the file does not have.
+
+60. **`BLOAD` requires a length.** A C128 reads until the file ends. Here the address is a real
+    process address, so a file longer than the caller expected would write past whatever it was
+    pointed at with no way to notice. Refusing to guess is the only safe answer.
+
+### Deviations in conditions
+
+41. **A lone `=` is equality inside a condition.** `IF A# = 2 THEN` works, which it did not
+    before: the scanner reads `==` as EQUAL and a single `=` as ASSIGNMENT, because at that
+    point it cannot know whether it is looking at a statement or a condition, and the reference
+    never resolved the ambiguity anywhere. A condition is the one context where it has an
+    answer — BASIC has no assignment expression — so `akbasic_Parser::comparing` is set around
+    the condition and the relation parser offers ASSIGNMENT as a comparison operator only while
+    it is. `==` keeps working, and the whole checked-in corpus is written in it.
+
+    Outside a condition `=` has to stay an assignment, which is what the flag is for: the first
+    attempt put ASSIGNMENT in the operator list unconditionally, and `FOR I# = 1 TO 5` promptly
+    stopped initializing its counter.
+
+42. **A condition is a whole expression, so `AND` and `OR` work in one.**
+    `IF A# = 5 AND B# = 3 THEN` used to report "Incomplete IF statement". The reference parses a
+    single *relation* after `IF`, and a relation sits below `AND` and `OR` in the grammar chain,
+    so the `AND` was never consumed and the `THEN` check found the wrong token.
+    `akbasic_parse_if()` calls `akbasic_parser_expression()` now.
+
+43. **Truth is nonzero, not "a boolean holding true".** `akbasic_value_is_truthy()` is what a
+    branch tests. Commodore BASIC has no boolean type: a comparison yields -1 or 0, `AND` and
+    `OR` *are* the bitwise operators, and `IF A THEN` is legal for any numeric A. The reference
+    tests `boolvalue == -1` regardless of the value's type, so `IF A# = 1 OR B# = 2 THEN` — whose
+    `OR` yields an integer — was silently always false, and so was `IF A# THEN`.
+
+    The bitwise operators accept a truth value as an operand for the same reason: -1 is every
+    bit set precisely so that `AND` and `OR` double as the logical pair. A string is still never
+    true; a C128 raises a type mismatch there, which is a stricter answer this could adopt later.
+
+### Deviations in the sprite verbs (group H)
+
+32. **Labels are filed before the program runs, not as each `LABEL` executes.**
+    `akbasic_runtime_scan_labels()` walks the stored source on every entry into
+    `AKBASIC_MODE_RUN` and files every `LABEL <name>` it finds, textually, without parsing the
+    lines around it. The reference resolves a label only once its `LABEL` statement has run, so
+    `GOTO` and `GOSUB` reached backwards and never forwards.
+
+    **This was not a nice-to-have.** An interrupt handler by definition sits on a line normal
+    flow does not fall into, so `COLLISION 1, BUMPED` could not be made to work at all under the
+    old rule — neither resolving at arm time nor at fire time helps when the `LABEL` line is
+    never executed. Forward `GOTO` is the improvement that came with it, covered by
+    `tests/language/statements/label_forward.bas`.
+
+    `LABEL` still executes and still files itself, so a name that appears twice resolves to the
+    last one in the source until one of them runs. The scan is textual on purpose: parsing every
+    line up front would raise on lines the program would never have reached.
+
+33. **Sprite coordinates are BASIC's 320×200, not the VIC-II's 0–511 by 0–255.** `MOVSPR` takes
+    the same coordinate space `DRAW` does. A C128's sprite coordinates are the raster's, offset
+    so that (24, 50) is the top-left of the visible screen; reproducing that would give the
+    language two coordinate systems and make `MOVSPR 1, 0, 0` put a sprite off-screen. Consistent
+    with deviation 18.
+
+34. **`MOVSPR`'s speed unit is ours.** BASIC 7.0 documents speed 0–15 with 15 fastest and says
+    nothing about what a unit is worth. Here one unit is
+    `AKBASIC_SPRITE_SPEED_PIXELS_PER_SECOND` (5) pixels per second, so speed 15 crosses the
+    320-pixel screen in about four seconds. Paced off `akbasic_runtime_settime()` from
+    `akbasic_runtime_step()`, exactly as the `PLAY` queue is, so a host that never sets a clock
+    gets a still picture rather than a hang — same trade as deviation 20.
+
+35. **`SPRSAV` takes an integer array where a C128 takes a string, and takes a file path as
+    well.** Three source forms, one of which is the C128's:
+
+    | Form | Source |
+    |---|---|
+    | `SPRSAV A$, n` | a region `SSHAPE` saved. The C128 documents `SPRSAV`'s string as *the `SSHAPE` data format at a fixed 24×21*, so sharing the shape pool is faithful rather than a shortcut |
+    | `SPRSAV A#, n` | 63 elements of a DIMmed integer array — the DATA-driven path a type-in listing uses |
+    | `SPRSAV "ship.png", n` | an image file |
+
+    **The array form exists because a string here cannot hold a sprite.** A value carries a
+    NUL-terminated `char[256]` (§1.2) and a pattern is 63 raw bytes including zeros, so the
+    C128's own spelling is unrepresentable. `DIM P#(63)` is exactly the right size.
+
+    **The file form is a deliberate addition, not a fallback.** A string source is a path unless
+    it starts with `SHAPE:`, which is the prefix `SSHAPE` mints, so the two never collide. It
+    resolves through `akgl_path_relative()` — the working directory first, then the directory the
+    running program was loaded from — and loads through `akgl_spritesheet_initialize()`, which
+    are the same two calls `akgl_sprite_load_json()` makes for a spritesheet. A sprite loaded
+    this way takes **the image's own size** rather than being forced to 24×21; a modern PC has
+    no reason to throw away art that is not sprite-shaped.
+
+    `akbasic_runtime_set_source_path()` is what tells the interpreter where the program came
+    from. Group F's disk verbs will want the same thing.
+
+    **The reverse direction is refused.** `SPRSAV n, A$` on a C128 copies a sprite *out*; here
+    that would mean writing an image file, which is a disk operation, and group F is
+    unimplemented as a whole. Refused by name rather than half-built.
+
+36. **`COLLISION` implements type 1 only, and types 2 and 3 are refused by name.**
+    Sprite-to-background needs the whole render target read back and compared against each
+    sprite every frame; a light pen has no meaning on a machine with no light pen. Both raise
+    `AKBASIC_ERR_DEVICE` with the reason rather than being accepted and never firing.
+
+    Collision is **bounding-box, not pixel**. A C128's VIC-II collides on set pixels, so two
+    sprites whose boxes overlap but whose art does not are reported as colliding here and would
+    not be there. Pixel-exact collision would mean keeping every sprite's unpacked bitmap and
+    testing the overlap rectangle a pixel at a time; the box test is four comparisons.
+    `akgl_collide_rectangles()` is deliberately not used — it has a documented
+    corner-containment defect that misses a plus-shaped overlap, and nothing in libakgl calls it.
+
+37. **A collision handler is entered between source lines, and must end in `RETURN`.**
+    `akbasic_runtime_service_interrupts()` runs at the top of `akbasic_runtime_step()` and
+    injects what amounts to a `GOSUB` the program did not write. Between lines is the only safe
+    place: a handler entered mid-statement would have to return into the middle of a line and
+    the parser keeps no state that could resume there. That is the same granularity block
+    skipping already works at (§1.6).
+
+    An interrupt does not interrupt an interrupt. A collision that is still true while its own
+    handler runs would otherwise re-enter on the next line until the environment pool was gone.
+    The event is not lost — it is taken as soon as the handler's `RETURN` lands.
+
+38. **Sprite priority is recorded and not honoured.** `SPRITE n,,,1` sets the bit, `RSPRITE`
+    reads it back, and nothing draws differently. A C128 draws a low-priority sprite behind the
+    bitmap plane; here the text layer, the drawing surface and the sprites share one render
+    target and sprites are composited on top of it every frame, so there is nothing to go
+    behind. Honouring it would mean a separate composited surface per plane — which is the same
+    piece of work deviation 19 already needs.
+
+39. **Multicolour mode is recorded and not honoured.** Same shape as priority: `SPRITE`'s
+    seventh argument and `SPRCOLOR`'s two registers are kept, `RSPRITE` and `RSPCOLOR` read them
+    back, and no sprite is drawn in multicolour. Multicolour packs *two* bitmap bits per pixel
+    and selects between the sprite's own colour and the two shared registers; every `SPRSAV`
+    source form here carries one bit per pixel or a full-colour image, so there is no second bit
+    to select with. The argument positions are kept honest for the day a multicolour pattern
+    format exists.
+
+40. **A sprite is a real `libakgl` actor, and it is drawn by a renderfunc of ours.** Each of the
+    eight becomes a `SpriteSheet` + `Sprite` + `Character` + `Actor` registered in
+    `AKGL_REGISTRY_ACTOR`, so an embedding game sees BASIC's sprites alongside its own (goal 3).
+    But `akgl_actor_render()` is not what draws them: it computes its destination *height* from
+    the sprite's **width**, which would draw a 24×21 Commodore sprite as a 24×24 square, and an
+    actor carries a single scalar `scale` that cannot express `SPRITE`'s separate x- and
+    y-expand bits. `src/sprite_akgl.c` installs its own `renderfunc`, which is libakgl's own
+    extension point for exactly this. Both defects are filed upstream.
+
+---
+
 ---
 
 ## 6. Reference defects — **fix them; fidelity is no longer a reason not to**
@@ -958,53 +1265,62 @@ correct contract, and a golden file moved in the same commit if the fix changes
 `AKBASIC_KNOWN_FAILING_TESTS` is empty now and is kept declared for the next defect that has to
 be reproduced before it can be fixed.
 
-1. **`basicvariable.go:176`** — `toString()` tests `len(self.values) == 0` and then indexes
+1. ~~**`basicvariable.go:176`** — `toString()` tests `len(self.values) == 0` and then indexes
-   `self.values[0]`. Inverted condition; on an empty variable it panics, and on a non-empty one
+   `self.values[0]`.~~ **Never ported.** There is no `akbasic_variable_to_string`: rendering a
-   it returns the "not implemented for arrays" string. *Consequence:* `PRINT` of a scalar
+   value is `akbasic_value_to_string()`, which switches on the value type and has no count test
-   through this path is wrong. Fix: `if ( count == 1 )`.
+   to invert. The buggy function had no counterpart to reproduce.
-2. **`basicvariable.go:108`** — `setBoolean` builds a value with `valuetype: TYPE_STRING`.
+2. ~~**`basicvariable.go:108`** — `setBoolean` builds a value with `valuetype: TYPE_STRING`.~~
-   *Consequence:* a boolean stored in a variable reads back as a string with an empty
+   **Fixed in the port.** `akbasic_value_set_bool()` sets `AKBASIC_TYPE_BOOLEAN`, and
-   `stringval`. Fix: `TYPE_BOOLEAN`.
+   `tests/value_compare.c` reads a boolean back through every comparison operator.
-3. **`basicenvironment.go:157`** — `stopWaiting(command)` ignores `command` and clears the
+3. ~~**`basicenvironment.go:157`** — `stopWaiting(command)` ignores `command`.~~ **Fixed in
-   wait unconditionally. *Consequence:* an inner block can clear an outer block's wait. Fix:
+   the port.** `akbasic_environment_stop_waiting()` walks the scope chain and clears the first
-   compare before clearing, and error on a mismatch.
+   environment actually waiting for *that* verb, so an inner block can no longer clear an outer
-4. **`basicvalue.go:181`** — `mathPlus` mutates `self` in place when `self.mutable` is true,
+   block's wait. A miss is tolerated rather than raised, which is the one part of the suggested
-   while every other operator always clones. *Consequence:* `A# + 1` can modify `A#` depending
+   fix not taken: `EXIT` and the end of a `DEF` body both call it speculatively.
-   on where the value came from. This one is high blast radius; it interacts with
+4. ~~**`basicvalue.go:181`** — `mathPlus` mutates `self` in place when `self.mutable` is
-   `eval_clone_identifiers` and with `CommandNEXT`'s increment
+   true.~~ **Fixed.** It clones like every other operator now, so `A# + 1` cannot modify `A#`.
-   (`basicruntime_commands.go:663`), which **relies** on the mutation. Do not fix it before
+
-   `FOR`/`NEXT` has full test coverage.
+   The gate on this item was `FOR`/`NEXT` coverage, because `NEXT`'s increment *relied* on the
-5. **`basicvalue.go:191` and siblings** — every binary operator adds both of the right-hand
+   mutation to advance the counter. `tests/for_next.c` is that coverage -- `STEP`, a negative
-   operand's numeric fields: `rval.intval + int64(rval.floatval)`. Works only because the
+   step, a float counter, a body that assigns to the counter, `EXIT`, and nesting, none of which
-   unused field is always zero. *Consequence:* none today; it is a landmine for any future
+   the golden corpus reaches -- and `akbasic_cmd_next()` now writes the incremented value back
-   value that carries both.
+   with `akbasic_variable_set_subscript()`. Removing that write-back does not fail the suite, it
-6. **`basicvalue.go`, all comparisons** — `dest` is cloned from `self`, so the resulting
+   *hangs* it: the counter stops advancing and the loop never ends.
-   boolean inherits `self.name`. *Consequence:* a comparison result can be written back to the
+5. ~~**`basicvalue.go:191` and siblings** — every binary operator adds both of the right-hand
-   wrong variable through `environment.update()`.
+   operand's numeric fields.~~ **Fixed.** `rval_as_int()` and `rval_as_float()` select on the
-7. **`basicruntime_commands.go:484`** — `CommandIF` walks `expr.right` to the end of the chain
+   operand's type instead of summing `intval + (int64_t)floatval`.
-   looking for a `THEN` command, then dereferences `expr.right` after the loop guaranteed it
+
-   is `nil`. *Consequence:* the "Malformed IF statement" check is unreachable and nested
+   It was filed as a landmine with no consequence today, and that is why it needed a test
-   `IF ... THEN ... ELSE` is unverified.
+   written against the value API rather than against the language: no BASIC program can build a
-8. **`basicruntime_commands.go:669`** — `CommandEXIT` pops the environment without
+   value carrying both fields, and the old code passes every other test in the tree.
-   `stopWaiting`, leaving the parent waiting on a `NEXT` that will never come.
+   `tests/value_arithmetic.c` constructs one directly.
-9. **`basicruntime.go:149`** — `newVariable()` and `BasicRuntime.variables[MAX_VARIABLES]` are
+6. ~~**`basicvalue.go`, all comparisons** — `dest` is cloned from `self`, so the resulting
-   dead; variables live in the environment's map. Do not port them.
+   boolean inherits `self.name`.~~ **Moot.** `BasicValue.name` was dropped as dead during the
+   port along with `BasicEnvironment.update()`, its only reader — deviation 9 above. There is no
+   name for a comparison result to inherit.
+7. ~~**`basicruntime_commands.go:484`** — `CommandIF` dereferences `expr.right` after the loop
+   guaranteed it is `nil`, so the "Malformed IF statement" check is unreachable.~~ **Fixed in
+   the port.** `akbasic_parse_if()` matches the `THEN` token and compares its lexeme directly,
+   so the check runs on every `IF`.
+8. ~~**`basicruntime_commands.go:669`** — `CommandEXIT` pops the environment without
+   `stopWaiting`.~~ **Fixed**, and then fixed again — see item 18, which is what clearing the
+   wait left behind.
+9. ~~**`basicruntime.go:149`** — `newVariable()` and `BasicRuntime.variables[MAX_VARIABLES]`
+   are dead.~~ **Not ported as dead code.** The pair is live here and is the storage model:
+   `akbasic_environment_create()` takes a slot from `akbasic_runtime_new_variable()`, because a
+   pool is what replaced Go's per-environment map (§1.3). The reference's versions were dead;
+   these are not.
 10. ~~**`basicgrammar.go:224`** — `newLiteralInt` selects base 8 whenever the lexeme starts
     with `0`.~~ **Fixed.** Base 10 unless prefixed `0x`; a leading zero in a listing is padding,
     not a radix. `PRINT 010` prints 10 and `PRINT 08` parses. Nothing in the upstream corpus
     had a leading-zero literal, which is why nothing there noticed. Regression tests in
     `tests/grammar_leaves.c` and `tests/language/numeric/octal_literal.bas`, which was rewritten
     from pinning the defect to pinning the fix.
-11. **`basicruntime.go:121` / `basicparser_commands.go:124`** — environments are never freed.
+11. ~~**`basicruntime.go:121` / `basicparser_commands.go:124`** — environments are never
-    Addressed structurally by §1.4; no separate fix needed, but the C pool **will** exhaust
+    freed.~~ **Fixed in the port.** They come from a fixed pool and
-    where Go merely leaked, so `tests/environment_scope.c`'s exhaustion assertion matters.
+    `akbasic_runtime_prev_environment()` releases each one — deviation 3 above. An unreleased
-
+    scope shows up as pool exhaustion rather than as unbounded growth, which is how item 18
-### Found during the port
+    announced itself.
-
-Five more, none of which the reference's own corpus catches. **Four are now fixed**, each with
-a regression test in the suite that pinned it; the fifth is described below and is not a coding
-question.
-
 12. ~~**`basicparser.go:329` — `subtraction()` returns after one operator where `addition()`
     loops.**~~ **Fixed.** `1 - 2 - 3` computed `1 - 2` and abandoned the rest of the line; the
     remaining `- 3` was left in the token stream, picked up by the statement loop as a second
@@ -1108,6 +1424,45 @@ question.
 
 ---
 
+
+### Found while auditing this section against the C port
+
+Writing the `FOR`/`NEXT` coverage that item 4 was gated on turned these up. The first two are
+the reference's semantics reproduced faithfully; the third is the port's own.
+
+18. ~~**`EXIT` on the first pass through a loop restarts the program.**~~ **Fixed.** `EXIT`
+    jumped to `loopExitLine`, which is only ever written by `NEXT` — so an `EXIT` before any
+    `NEXT` had run jumped to line 0. Each restart entered the `FOR` again and took another
+    environment and another variable, so what a reader saw was "Maximum runtime variables
+    reached" reported against the `FOR`, on a four-line program.
+
+    It now skips forward to the `NEXT` using the same `waitingForCommand` machinery a
+    zero-iteration body uses, and the `NEXT` pops on an `exiting` flag. Neither verb has to know
+    where the loop ends. `tests/for_next.c`.
+
+19. **A `FOR` body runs once with the overshot counter.** The loop condition is tested against
+    the counter *before* the increment, so the increment's result reaches the body before
+    anything compares it to the limit. `FOR I = 1 TO 9 STEP 3` runs its body with 1, 4, 7 **and
+    then 10**. Invisible whenever the step lands exactly on the limit, which is every case in
+    the golden corpus and every case in the reference's own tests.
+
+    Related, and the same off-by-one from the other end: `FOR I = 1 TO 1` does not run its body
+    at all, where every BASIC ever written runs it once. The two errors compensate for a step of
+    1, which is why neither was noticed.
+
+    **Not fixed, because the corpus pins it.**
+    `tests/reference/language/flowcontrol/forloopwaitingforcommand.bas` depends on
+    `FOR I# = 1 TO 1` skipping its body, and `tests/reference/README.md` forbids editing an
+    expectation to suit this interpreter. Registered as `tests/for_semantics.c` in
+    `AKBASIC_KNOWN_FAILING_TESTS`, asserting the correct contract. Fixing it means deciding what
+    to do with that golden file, and that is a decision rather than a patch.
+
+20. **A `FOR` counter does not survive its loop.** It is created in the environment the loop
+    pushes, which pops when the loop ends, so reading it afterwards finds a fresh variable
+    holding zero. A C128 leaves it at the value that ended the loop and plenty of published
+    listings read it there. Same known-failing test as item 19; the fix is a scoping decision
+    about where a loop counter is created, not an ordering one.
+
 ## 7. Filing gaps against `libakgl`
 
 When phase 7 or phase 8 needs something `libakgl` does not have, **stop and file it** in
@@ -1207,7 +1562,7 @@ Dependency baseline:
 |---|---|---|
 | `deps/libakerror` | 1.0.0 | Private ownership-enforced status registry. akbasic reserves 512–767 in `akbasic_error_register()`. Does not namespace its `coverage` target when embedded — worked around in our `CMakeLists.txt`. |
 | `deps/libakstdlib` | 0.2.0 | soname `libakstdlib.so.0.2`. `AKSL_VERSION_CHECK()` asserted in `tests/version_check.c`. This release fixed all six confirmed defects the port was working around — see §1.9, where the bans are now lifted. |
-| `deps/libakgl` | 0.3.0 | soname `libakgl.so.0.3`. Owns status codes 256–260. Linked and tested under `-DAKBASIC_WITH_AKGL=ON`, which still defaults OFF so the core library and its whole suite build on a machine with no SDL. **0.3.0 closed every API gap this port had filed** — see §7 — so the four workarounds §3 used to list are gone. |
+| `deps/libakgl` | 0.4.0 | soname `libakgl.so.0.4`. Owns status codes 256–260. Linked and tested under `-DAKBASIC_WITH_AKGL=ON`, which still defaults OFF so the core library and its whole suite build on a machine with no SDL. **0.3.0 closed every API gap this port had filed** — see §7 — so the four workarounds §3 used to list are gone. 0.4.0 is a leak-and-overread release that changed no public struct, but the soname carries `MAJOR.MINOR` while the major is 0, so rebuild rather than relink. |
 
 **The `libakgl` requirement used to be pinned by commit, and no longer is.** 42b60f7 added 22
 public symbols across four headers and left `project(akgl VERSION 0.1.0)` and the

include/akbasic/akgl.h

@@ -29,28 +29,40 @@
 
 #include <akerror.h>
 
+#include <akgl/actor.h>
+#include <akgl/character.h>
 #include <akgl/renderer.h>
+#include <akgl/sprite.h>
 #include <akgl/version.h>
 
 /*
- * Everything in this target now depends on APIs that arrived in libakgl 0.3.0:
+ * The API floor is 0.3.0: akgl_render_bind2d(), akgl_audio_sweep(), and
- * akgl_render_bind2d(), akgl_audio_sweep(), and akgl_Keystroke with
+ * akgl_Keystroke with akgl_controller_poll_keystroke() all arrived there, and
- * akgl_controller_poll_keystroke(). Refused here rather than at link time,
+ * nothing in this target uses anything newer. The floor asserted below is
- * because a missing symbol names a function and this names the release.
+ * 0.4.0 anyway, and the difference is ABI rather than API.
  *
- * The soname carries MAJOR.MINOR while the major is 0, so 0.2 and 0.3 are
+ * The soname carries MAJOR.MINOR while the major is 0, so 0.3 and 0.4 are
- * different ABIs and a mismatch is normally caught at load. This catches the
+ * different ABIs *by declaration* -- libakgl's versioning policy says a 0.x
- * case the soname cannot: a build against 0.2 headers that happens to find a
+ * minor bump may break, and the soname is built to match. 0.4.0 in fact changed
- * 0.3 library, or the reverse.
+ * no public struct: it is leak and overread fixes inside src/. The floor moves
+ * anyway, because the alternative is deciding for ourselves which of libakgl's
+ * minor releases were really compatible, and that is exactly the judgement the
+ * soname exists to take away from us.
+ *
+ * What it catches is the case the soname cannot: a build against 0.3 headers
+ * that happens to find a 0.4 library, or the reverse. Refused here rather than
+ * at link time, because a missing symbol names a function and this names the
+ * release.
  */
-#if !AKGL_VERSION_AT_LEAST(0, 3, 0)
+#if !AKGL_VERSION_AT_LEAST(0, 4, 0)
-#error "akbasic's libakgl adaptors require libakgl 0.3.0 or later"
+#error "akbasic's libakgl adaptors require libakgl 0.4.0 or later"
 #endif
 
 #include <akbasic/audio.h>
 #include <akbasic/graphics.h>
 #include <akbasic/input.h>
 #include <akbasic/sink.h>
+#include <akbasic/sprite.h>
 
 /**
  * @brief One full cursor blink in milliseconds, half on and half off.
@@ -106,6 +118,15 @@ typedef struct
     int y;
     int width;			/* pixel size of the text area				*/
     int height;
+    /*
+     * The whole drawable area, kept so WINDOW can grow back out to it. Without
+     * it a window could only ever shrink, since `x`/`width` have by then been
+     * overwritten with the current window's.
+     */
+    int fullx;
+    int fully;
+    int fullwidth;
+    int fullheight;
     int cellw;			/* one character cell, measured from the font		*/
     int cellh;
     int columns;		/* the character grid the cell size works out to	*/
@@ -156,6 +177,35 @@ typedef struct
     int shapecount;
 } akbasic_AkglGraphics;
 
+/**
+ * @brief State for the libakgl-backed sprite backend.
+ *
+ * One libakgl actor per BASIC sprite, plus the sheet, sprite and character each
+ * actor needs -- built by hand rather than loaded from a sprite document, since
+ * a Commodore sprite has no animation, no frame list and no state map to
+ * describe. Everything is pooled by libakgl; what is held here are the pointers
+ * and the one texture per slot that this backend owns and must destroy.
+ *
+ * `graphics` is the graphics backend's state, borrowed so `SPRSAV A$, n` can
+ * resolve a handle SSHAPE minted. The two devices are separate records on
+ * purpose -- a host may supply one and withhold the other -- so this is a
+ * pointer that may be NULL rather than an assumption that both exist.
+ */
+typedef struct
+{
+    akgl_RenderBackend *renderer;
+    akbasic_AkglGraphics *graphics;
+
+    akgl_SpriteSheet *sheets[AKBASIC_MAX_SPRITES];
+    akgl_Sprite *sprites[AKBASIC_MAX_SPRITES];
+    akgl_Character *characters[AKBASIC_MAX_SPRITES];
+    akgl_Actor *actors[AKBASIC_MAX_SPRITES];
+
+    /** Per-axis expansion, which an actor's single `scale` cannot carry. */
+    bool xexpand[AKBASIC_MAX_SPRITES];
+    bool yexpand[AKBASIC_MAX_SPRITES];
+} akbasic_AkglSprites;
+
 /**
  * @brief Point a text sink at a renderer and a font the host already has.
  *
@@ -235,6 +285,53 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_sink_akgl_set_pump(akbasic_TextSink *
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_graphics_init_akgl(akbasic_GraphicsBackend *obj, akbasic_AkglGraphics *state, akgl_RenderBackend *renderer);
 
+/**
+ * @brief Point a sprite backend at a renderer the host already has.
+ *
+ * Requires akgl_heap_init() and akgl_registry_init() to have run -- every
+ * akgl_*_initialize ends in a registry write -- and requires the global `camera`
+ * to point somewhere, because akgl_actor_render() dereferences it without
+ * checking. akgl_game_init() does all three; a host that skips it, which is
+ * every host embedding this interpreter, does them itself.
+ * src/frontend_akgl.c is the worked example.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param state Storage for the sprite pool; must outlive the backend.
+ * @param renderer The renderer the host already initialized; not created here.
+ * @param graphics The graphics backend's state, so SPRSAV can resolve an SSHAPE handle; may be NULL.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj`, `state` or `renderer` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_sprite_init_akgl(akbasic_SpriteBackend *obj, akbasic_AkglSprites *state, akgl_RenderBackend *renderer, akbasic_AkglGraphics *graphics);
+
+/**
+ * @brief Draw every defined, enabled sprite.
+ *
+ * Separate from the verbs for the same reason akbasic_sink_akgl_render() is: the
+ * interpreter does not own the frame. A host calls this when it is drawing.
+ *
+ * The actors are swept directly rather than through akgl_registry_iterate_actor(),
+ * which ends in FINISH_NORETURN -- an unhandled error inside it terminates the
+ * process, and goal 3 forbids anything in this library doing that. Sweeping our
+ * own eight also leaves a host's own actors alone.
+ *
+ * @param obj The backend to draw.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL or carries no state.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_sprite_akgl_render(akbasic_SpriteBackend *obj);
+
+/**
+ * @brief Release every texture the sprite backend created.
+ *
+ * The actors, sprites, sheets and characters are libakgl's pooled objects and go
+ * back with akgl_heap_init(); the SDL textures behind the sheets are this
+ * backend's own and are not anybody else's to free.
+ *
+ * @param obj The backend to tear down. NULL is not an error.
+ */
+void akbasic_sprite_akgl_shutdown(akbasic_SpriteBackend *obj);
+
 /**
  * @brief Wire an audio backend to libakgl's tone generator.
  *

include/akbasic/args.h

@@ -0,0 +1,46 @@
+/**
+ * @file args.h
+ * @brief Collecting a verb's positional arguments, shared by the verb files.
+ *
+ * Every device verb group -- graphics, audio, and now sprites -- takes a short
+ * positional list with optional trailing members, so every handler wants the
+ * same two things: how many arguments arrived, and their numeric values. This
+ * was written twice before it was written here. src/runtime_audio.c's copy
+ * carried the rule for when to stop copying it:
+ *
+ *     "If a third group wants it, that is the point at which it earns a home of
+ *      its own."
+ *
+ * Group H is the third group.
+ */
+
+#ifndef _AKBASIC_ARGS_H_
+#define _AKBASIC_ARGS_H_
+
+#include <akerror.h>
+
+#include <akbasic/grammar.h>
+
+struct akbasic_Runtime;
+
+/**
+ * @brief Collect a verb's arguments into an array, evaluating each one.
+ *
+ * Strings are refused here rather than in each verb. A verb that does take one
+ * -- SSHAPE, GSHAPE, SPRSAV -- reads its leaf directly instead, because what it
+ * wants from that argument is not a number and never was.
+ *
+ * @param obj Runtime to evaluate against.
+ * @param expr The command leaf.
+ * @param verb Name to use in a diagnostic; a verb that refuses has to say which.
+ * @param values Where to put the evaluated arguments.
+ * @param max Capacity of @p values.
+ * @param count Output destination populated by the function.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When any argument but `verb` is NULL.
+ * @throws AKBASIC_ERR_SYNTAX When more than `max` arguments were given.
+ * @throws AKBASIC_ERR_TYPE When an argument evaluated to a string.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_args_numbers(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb, double *values, int max, int *count);
+
+#endif // _AKBASIC_ARGS_H_

include/akbasic/console.h

@@ -0,0 +1,73 @@
+/**
+ * @file console.h
+ * @brief The group E console state: SLEEP, WAIT, KEY and the TI clock.
+ *
+ * All of it is the program's state rather than the device's, which is why it
+ * lives on the runtime beside the graphics, audio and sprite state. A host that
+ * swaps one output device for another does not expect a sleeping program to wake
+ * up or its function keys to be forgotten.
+ */
+
+#ifndef _AKBASIC_CONSOLE_H_
+#define _AKBASIC_CONSOLE_H_
+
+#include <akerror.h>
+
+#include <akbasic/types.h>
+
+/** @brief Function keys `KEY` can define. A C128 has eight. */
+#define AKBASIC_MAX_FUNCTION_KEYS	8
+
+/** @brief The state SLEEP, WAIT and KEY keep. */
+typedef struct
+{
+    bool sleeping;			/** SLEEP is holding the step loop	*/
+    int64_t sleepuntilms;		/** ...until the host clock reaches this */
+
+    bool waiting;			/** WAIT is holding the step loop	*/
+    uintptr_t waitaddress;		/** the byte it is polling		*/
+    uint8_t waitmask;
+    uint8_t waitxor;
+
+    char keys[AKBASIC_MAX_FUNCTION_KEYS][AKBASIC_MAX_STRING_LENGTH];
+} akbasic_ConsoleState;
+
+struct akbasic_Runtime;
+
+/**
+ * @brief Reset the console state: nothing sleeping, nothing waiting, no macros.
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_console_state_init(akbasic_ConsoleState *obj);
+
+/**
+ * @brief Answer whether a SLEEP or a WAIT is still holding the step loop.
+ *
+ * Called once per akbasic_runtime_step(), beside akbasic_input_service() and for
+ * the same reason: waiting must not mean blocking. The step still returns, it
+ * simply does not advance the program.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param blocked Output destination populated by the function; true while held.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When either argument is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_console_service(struct akbasic_Runtime *obj, bool *blocked);
+
+/**
+ * @brief Refresh `TI#` and `TI$` from the host's clock.
+ *
+ * Called once per step. They are ordinary global variables rather than
+ * pseudo-variables, because this dialect has no bare variable names -- see
+ * TODO.md section 5.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When no variable slot is free.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_console_update_clock(struct akbasic_Runtime *obj);
+
+#endif // _AKBASIC_CONSOLE_H_

include/akbasic/data.h

@@ -0,0 +1,92 @@
+/**
+ * @file data.h
+ * @brief The `DATA` item list and the `READ` cursor `RESTORE` resets.
+ *
+ * The Go reference has neither. Its `READ` does not read: it records the
+ * identifiers it wants filled, sets the scope waiting for a `DATA` verb, and
+ * lets execution skip forward until one turns up. That has two consequences,
+ * both wrong and both fixed here:
+ *
+ *   - **A `DATA` line before its `READ` is never found.** `10 DATA 1,2` /
+ *     `20 READ A#` skipped to the end of the program in silence.
+ *   - **There is no cursor**, so `RESTORE` had nothing to reset and could not be
+ *     implemented at all.
+ *
+ * Every `DATA` statement is pre-scanned into one flat list before the program
+ * runs, the same way labels are (akbasic_runtime_scan_labels), and `READ` walks
+ * a cursor along it. Items are kept as their source text and converted when read,
+ * because what a `DATA` item means depends on the variable it is read into --
+ * `DATA 5` fills `A#` with an integer and `A$` with "5".
+ */
+
+#ifndef _AKBASIC_DATA_H_
+#define _AKBASIC_DATA_H_
+
+#include <akerror.h>
+
+#include <akbasic/types.h>
+
+/** @brief How many `DATA` items a program may hold. */
+#define AKBASIC_MAX_DATA_ITEMS		512
+/** @brief Longest single `DATA` item, terminator included. */
+#define AKBASIC_MAX_DATA_ITEM_LENGTH	128
+
+/** @brief One `DATA` item: its text, where it was written, and whether it was quoted. */
+typedef struct
+{
+    char text[AKBASIC_MAX_DATA_ITEM_LENGTH];
+    int64_t lineno;			/** so RESTORE (line) can find it	*/
+    bool quoted;			/** written with quotes, so it is a string */
+} akbasic_DataItem;
+
+/** @brief Every `DATA` item in the program, and how far `READ` has got. */
+typedef struct
+{
+    akbasic_DataItem items[AKBASIC_MAX_DATA_ITEMS];
+    int count;
+    int cursor;
+} akbasic_DataState;
+
+struct akbasic_Runtime;
+
+/**
+ * @brief Reset the item list and the cursor.
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_data_state_init(akbasic_DataState *obj);
+
+/**
+ * @brief Collect every `DATA` item in the stored program, in source order.
+ *
+ * Called on every entry into AKBASIC_MODE_RUN, beside
+ * akbasic_runtime_scan_labels() and for the same reason: it is the one point
+ * `RUN`, `CONT`, akbasic_runtime_start() and the end of a RUNSTREAM load all
+ * pass through. Re-scanning is what picks up a program edited at the REPL.
+ *
+ * The scan is textual. `DATA` at the start of a statement, outside a string
+ * literal, then comma-separated items up to a `:` or the end of the line -- which
+ * is where a Commodore ends a `DATA` statement too.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When the program holds more than AKBASIC_MAX_DATA_ITEMS items.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_data_scan(struct akbasic_Runtime *obj);
+
+/**
+ * @brief Take the next `DATA` item and convert it for a variable of @p type.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param type The type of the variable being filled.
+ * @param dest Output destination populated by the function.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When any argument is NULL.
+ * @throws AKBASIC_ERR_STATE When there are no items left -- "OUT OF DATA".
+ * @throws AKBASIC_ERR_TYPE When a quoted item is read into a numeric variable.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_data_next(struct akbasic_Runtime *obj, akbasic_Type type, akbasic_Value *dest);
+
+#endif // _AKBASIC_DATA_H_

include/akbasic/disk.h

@@ -0,0 +1,99 @@
+/**
+ * @file disk.h
+ * @brief The group F file channels: DOPEN, DCLOSE, PRINT#, INPUT#, GET#.
+ *
+ * A Commodore's disk verbs address a 1541 over the serial bus. There is no 1541,
+ * so what these mean here is the nearest thing a filesystem offers, and the
+ * verbs that mean nothing without the hardware are refused by name rather than
+ * faked -- see TODO.md section 5.
+ *
+ * Channels are the interpreter's, not the host's: a program that opens a file
+ * and is then stepped by a game's frame loop keeps its channel across frames,
+ * and a `NEW` closes the lot.
+ */
+
+#ifndef _AKBASIC_DISK_H_
+#define _AKBASIC_DISK_H_
+
+#include <stdio.h>
+
+#include <akerror.h>
+
+#include <akbasic/types.h>
+
+/** @brief How many files may be open at once. A C128 allows ten; this allows the same. */
+#define AKBASIC_MAX_CHANNELS	10
+
+/** @brief One open file channel. */
+typedef struct
+{
+    FILE *fp;
+    char name[AKBASIC_MAX_STRING_LENGTH];
+    bool writing;
+} akbasic_Channel;
+
+/** @brief Every open channel. Indexed by the number a program writes after `#`. */
+typedef struct
+{
+    akbasic_Channel channels[AKBASIC_MAX_CHANNELS];
+} akbasic_DiskState;
+
+struct akbasic_Runtime;
+
+/**
+ * @brief Mark every channel closed. Does not close anything; nothing is open yet.
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_disk_state_init(akbasic_DiskState *obj);
+
+/**
+ * @brief Close every open channel.
+ *
+ * Called by `DCLOSE` with no argument and by `NEW`. A program that ends without
+ * closing its files leaves them to this -- and to the host, which owns the
+ * process and outlives the program.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_disk_close_all(akbasic_DiskState *obj);
+
+/**
+ * @brief Write one line to a channel, terminator included.
+ *
+ * What `PRINT #n, ...` reaches. A line rather than raw bytes, because that is
+ * what `INPUT #n` reads back and the pair has to agree.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param number The channel number.
+ * @param text What to write.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` or `text` is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When the channel number is out of range.
+ * @throws AKBASIC_ERR_STATE When the channel is closed, or was opened for reading.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_disk_write(struct akbasic_Runtime *obj, int64_t number, const char *text);
+
+/**
+ * @brief Read one line from a channel, without its terminator.
+ *
+ * What `INPUT #n, VAR` reaches. End of file is reported through @p eof rather
+ * than raised, the same way the sink's `readline` reports it: running out of
+ * input is a state a program handles, not a failure.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param number The channel number.
+ * @param dest Output destination populated by the function.
+ * @param len Capacity of @p dest.
+ * @param eof Output destination populated by the function; true at end of file.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When any pointer argument is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When the channel number is out of range.
+ * @throws AKBASIC_ERR_STATE When the channel is closed, or was opened for writing.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_disk_readline(struct akbasic_Runtime *obj, int64_t number, char *dest, size_t len, bool *eof);
+
+#endif // _AKBASIC_DISK_H_

include/akbasic/environment.h

@@ -23,6 +23,13 @@
 #include <akbasic/value.h>
 #include <akbasic/variable.h>
 
+/** @brief A DO or LOOP with no condition on that end. */
+#define AKBASIC_LOOPCOND_NONE	0
+/** @brief `WHILE c` -- keep looping while the condition is true. */
+#define AKBASIC_LOOPCOND_WHILE	1
+/** @brief `UNTIL c` -- keep looping until the condition becomes true. */
+#define AKBASIC_LOOPCOND_UNTIL	2
+
 struct akbasic_Runtime;
 
 typedef struct akbasic_Environment
@@ -38,9 +45,32 @@ typedef struct akbasic_Environment
     akbasic_Value forToValue;
     akbasic_Variable *forNextVariable;
 
+    /*
+     * DO/LOOP state. The condition may sit on either end -- `DO WHILE c`,
+     * `LOOP UNTIL c`, both, or neither -- so each end keeps its own, and the
+     * leaf lives in this environment's pool because it is re-evaluated on every
+     * iteration long after the line that held it was scanned away.
+     */
+    akbasic_ASTLeaf *doConditionLeaf;
+    /* The condition is re-evaluated every iteration, long after its line was scanned away. */
+    akbasic_ASTLeaf doLeafStorage[AKBASIC_MAX_CONDITION_LEAVES];
+    akbasic_LeafPool doLeafPool;
+    int doConditionKind;		/** AKBASIC_LOOPCOND_* */
+    bool isDoLoop;			/** distinguishes DO/LOOP from FOR/NEXT for EXIT */
+
     /* Loop bounds */
     int64_t loopFirstLine;
     int64_t loopExitLine;
+    /**
+     * Set by `EXIT`, cleared by the `NEXT` that acts on it.
+     *
+     * `EXIT` cannot simply jump past the loop, because where the loop ends is
+     * not known until a `NEXT` has run at least once -- and an `EXIT` on the
+     * first pass is the normal case. So it skips forward to the `NEXT` using the
+     * same waitingForCommand machinery a zero-iteration loop body uses, and this
+     * is what tells that `NEXT` it is ending the loop rather than continuing it.
+     */
+    bool exiting;
 
     int64_t gosubReturnLine;
 

include/akbasic/format.h

@@ -0,0 +1,92 @@
+/**
+ * @file format.h
+ * @brief `PRINT USING` field formatting, and the `PUDEF` characters it fills with.
+ *
+ * Its own translation unit rather than a helper inside the PRINT handler,
+ * because the interesting part is a pure function of a format string and a
+ * value: it can be tested exhaustively without a runtime, a sink or a program,
+ * and field formatting has far more edge cases than a verb usually does.
+ */
+
+#ifndef _AKBASIC_FORMAT_H_
+#define _AKBASIC_FORMAT_H_
+
+#include <akerror.h>
+
+#include <akbasic/types.h>
+#include <akbasic/value.h>
+
+/** @brief How many characters `PUDEF` can redefine. */
+#define AKBASIC_PUDEF_CHARS	4
+
+/** @brief `PUDEF` position 1: what a leading blank in a numeric field is filled with. */
+#define AKBASIC_PUDEF_BLANK	0
+/** @brief `PUDEF` position 2: the thousands separator. */
+#define AKBASIC_PUDEF_COMMA	1
+/** @brief `PUDEF` position 3: the decimal point. */
+#define AKBASIC_PUDEF_POINT	2
+/** @brief `PUDEF` position 4: the currency sign. */
+#define AKBASIC_PUDEF_DOLLAR	3
+
+/**
+ * @brief The four characters `PUDEF` redefines.
+ *
+ * Lives on the runtime beside the other verb-group state: it is the program's,
+ * not the sink's, and a host that swaps one output device for another does not
+ * expect the program's punctuation to change.
+ */
+typedef struct
+{
+    char chars[AKBASIC_PUDEF_CHARS];
+} akbasic_FormatState;
+
+/**
+ * @brief Reset the `PUDEF` characters to their defaults: space, comma, point, dollar.
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_format_state_init(akbasic_FormatState *obj);
+
+/**
+ * @brief Redefine the fill characters, up to four of them.
+ *
+ * Positions past the end of @p chars keep whatever they had, so `PUDEF "*"`
+ * changes only the leading-blank character. That is BASIC 7.0's rule.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param chars Replacement characters, in PUDEF order; at most four are read.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When either argument is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_format_pudef(akbasic_FormatState *obj, const char *chars);
+
+/**
+ * @brief Render one value into one `PRINT USING` field.
+ *
+ * @p format is the whole format string; the *first* field in it is the one used,
+ * and any literal text around that field is copied through. That is how BASIC
+ * 7.0 works -- `PRINT USING "TOTAL: ###.##"; X` prints the label as well.
+ *
+ * Numeric fields are built from `#` digit positions, an optional `.` and
+ * embedded `,` separators, with an optional leading or trailing `$`, `+` or `-`.
+ * String fields are `=` to centre and `>` to right-justify, and a bare run of
+ * `#` left-justifies.
+ *
+ * **A value too wide for its field fills the field with `*`**, which is BASIC
+ * 7.0's answer and is deliberately loud: silently printing more digits than the
+ * field asked for would misalign every column after it.
+ *
+ * @param obj The PUDEF characters to fill with.
+ * @param format The format string.
+ * @param value The value to render.
+ * @param dest Output destination populated by the function.
+ * @param len Capacity of @p dest, terminator included.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When any argument is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When the result does not fit @p dest.
+ * @throws AKBASIC_ERR_SYNTAX When the format string contains no field at all.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_format_using(akbasic_FormatState *obj, const char *format, akbasic_Value *value, char *dest, size_t len);
+
+#endif // _AKBASIC_FORMAT_H_

include/akbasic/frontend.h

@@ -84,6 +84,8 @@ typedef struct akbasic_AkglFrontend
     akbasic_AkglGraphics graphicsstate;
     akbasic_AudioBackend audio;
     akbasic_InputBackend input;
+    akbasic_SpriteBackend sprites;
+    akbasic_AkglSprites spritesstate;
 
     /** False once the window has been closed; the drive loop stops on it. */
     bool running;

include/akbasic/grammar.h

@@ -59,7 +59,14 @@ typedef enum
     AKBASIC_TOK_ARRAY_SUBSCRIPT,	/* 37 */
     AKBASIC_TOK_FUNCTION_ARGUMENT,	/* 38 */
     AKBASIC_TOK_ATSYMBOL,		/* 39 */
-    AKBASIC_TOK_IDENTIFIER_STRUCT	/* 40 */
+    AKBASIC_TOK_IDENTIFIER_STRUCT,	/* 40 */
+    /*
+     * 41, 42 -- MOVSPR's two separators, and nothing else in the language uses
+     * either. Appended rather than filed in with the other punctuation because
+     * the numbering is part of this enum's published shape.
+     */
+    AKBASIC_TOK_SEMICOLON,		/* 41 */
+    AKBASIC_TOK_HASHMARK		/* 42 */
 } akbasic_TokenType;
 
 typedef enum
@@ -189,6 +196,18 @@ akbasic_ASTLeaf *akbasic_leaf_first_subscript(akbasic_ASTLeaf *self);
  */
 bool akbasic_leaf_is_identifier(akbasic_ASTLeaf *self);
 
+/**
+ * @brief The value type an identifier leaf's suffix asks for.
+ *
+ * `A#` is an integer, `A%` a float, `A$` a string. A leaf that is not an
+ * identifier, or one with no suffix -- a label -- reports
+ * #AKBASIC_TYPE_UNDEFINED.
+ *
+ * @param self Leaf to inspect; NULL reports undefined.
+ * @return The type, or #AKBASIC_TYPE_UNDEFINED.
+ */
+akbasic_Type akbasic_leaf_identifier_type(akbasic_ASTLeaf *self);
+
 /**
  * @brief True when a leaf is an integer, float or string literal.
  * @param self Leaf to inspect; NULL is not a literal.

include/akbasic/graphics.h

@@ -67,6 +67,7 @@ typedef struct
     double x;				/* pixel cursor: where LOCATE put it, or where	*/
     double y;				/*   the last DRAW ended			*/
     bool scaling;			/* SCALE on					*/
+    int linewidth;			/* WIDTH: 1 or 2 pixels per drawn line		*/
     double xmax;			/* user-coordinate maxima SCALE maps from	*/
     double ymax;
 } akbasic_GraphicsState;

include/akbasic/parser.h

@@ -31,6 +31,19 @@
 typedef struct akbasic_Parser
 {
     akbasic_Runtime *runtime;
+    /**
+     * True while parsing something that cannot possibly be an assignment, which
+     * makes a lone `=` an equality test rather than one.
+     *
+     * The scanner reads `==` as EQUAL and a lone `=` as ASSIGNMENT, because at
+     * that point it cannot know whether it is looking at a statement or a
+     * condition. A condition is the one place the question has an answer: BASIC
+     * has no assignment expression, so `IF A# = 2 THEN` can only be a
+     * comparison -- and that is how every BASIC manual writes it. Set around the
+     * condition and cleared afterwards, because `FOR I# = 1 TO 5` runs through
+     * the same expression parser and there `=` really is an assignment.
+     */
+    bool comparing;
 } akbasic_Parser;
 
 /**

include/akbasic/runtime.h

@@ -19,11 +19,17 @@
 #include <akerror.h>
 
 #include <akbasic/audio.h>
+#include <akbasic/console.h>
+#include <akbasic/data.h>
+#include <akbasic/disk.h>
 #include <akbasic/environment.h>
+#include <akbasic/format.h>
 #include <akbasic/grammar.h>
 #include <akbasic/graphics.h>
 #include <akbasic/input.h>
 #include <akbasic/sink.h>
+#include <akbasic/sprite.h>
+#include <akbasic/symtab.h>
 #include <akbasic/types.h>
 #include <akbasic/value.h>
 #include <akbasic/variable.h>
@@ -44,6 +50,39 @@ typedef struct
     int64_t lineno;
 } akbasic_SourceLine;
 
+/**
+ * @brief What can interrupt a running program and send it into a handler.
+ *
+ * The numbering is COLLISION's own argument minus one, so `COLLISION 1` arms
+ * slot 0. The two collision types this interpreter refuses still hold slots:
+ * dropping them would make the arithmetic a lookup table for no gain, and a
+ * later release that implements them wants the same numbers.
+ */
+typedef enum
+{
+    AKBASIC_INTERRUPT_SPRITE = 0,	/** COLLISION 1 -- sprite met sprite */
+    AKBASIC_INTERRUPT_BACKGROUND,	/** COLLISION 2 -- sprite met background; refused */
+    AKBASIC_INTERRUPT_LIGHTPEN,		/** COLLISION 3 -- light pen; refused */
+    AKBASIC_INTERRUPT_ERROR,		/** TRAP -- a BASIC error; group C, not yet armed by anything */
+    AKBASIC_MAX_INTERRUPTS
+} akbasic_InterruptSource;
+
+/**
+ * @brief One armed interrupt: where its handler is, and whether it is due.
+ *
+ * The target is held as a line number *or* a label name, and a label is resolved
+ * when the interrupt fires rather than when it is armed. A label may be re-filed
+ * by its own LABEL statement at any point, so resolving late is what lets the
+ * later spelling win.
+ */
+typedef struct
+{
+    bool armed;
+    bool pending;
+    int64_t line;			/* the numeric target; 0 when a label was given	*/
+    char label[AKBASIC_SYMTAB_MAX_KEY];	/* the label target; empty when a number was given */
+} akbasic_Interrupt;
+
 /** @brief A user-defined subroutine or single-expression function. */
 typedef struct
 {
@@ -95,6 +134,7 @@ typedef struct akbasic_Runtime
     akbasic_GraphicsBackend *graphics;
     akbasic_AudioBackend *audio;
     akbasic_InputBackend *input;
+    akbasic_SpriteBackend *sprites;
 
     /*
      * The graphics verbs' own state -- mode, color-source bindings, pixel cursor
@@ -114,6 +154,59 @@ typedef struct akbasic_Runtime
     /* GETKEY's hold on the step loop. Same reasoning again: it is the program's. */
     akbasic_InputState input_state;
 
+    /*
+     * The eight sprites, their positions and their collision bits. Same
+     * reasoning as gfx and audio_state, and one more: RSPPOS and RSPRITE read
+     * this rather than asking the device, so they answer correctly with no
+     * device attached at all.
+     */
+    akbasic_SpriteState sprite_state;
+
+    /* PUDEF's fill characters, which PRINT USING pads and punctuates with. */
+    akbasic_FormatState format_state;
+
+    /* SLEEP's and WAIT's hold on the step loop, and KEY's macros. */
+    akbasic_ConsoleState console_state;
+
+    /* Every DATA item in the program, and how far READ has got along it. */
+    akbasic_DataState data_state;
+
+    /* The open file channels DOPEN hands out. */
+    akbasic_DiskState disk_state;
+
+    /*
+     * Where the running program was loaded from, or empty when it did not come
+     * from a file -- a REPL session, or a host that handed over a string.
+     *
+     * Only one thing needs it today: SPRSAV resolving an image path that does
+     * not exist relative to the working directory, which is what makes a `.bas`
+     * beside its art work from anywhere. Group F's disk verbs will want the
+     * same, which is why it is on the runtime rather than in the sprite state.
+     */
+    char sourcepath[AKBASIC_MAX_LINE_LENGTH];
+
+    /*
+     * The armed interrupts, and the environment the one currently running was
+     * entered through.
+     *
+     * `handlerenv` is doing two jobs at once. It is the "a handler is running"
+     * flag -- an interrupt does not interrupt an interrupt, which is what keeps a
+     * collision that persists across the handler from recursing until the
+     * environment pool is gone. And it is the identity RETURN compares against,
+     * so the flag clears on the RETURN that leaves *this* handler rather than on
+     * the first RETURN of any GOSUB the handler itself makes.
+     */
+    akbasic_Interrupt interrupts[AKBASIC_MAX_INTERRUPTS];
+    akbasic_Environment *handlerenv;
+
+    /*
+     * The status code of the error being reported, for `ER#` to carry into a
+     * TRAP handler. Set by the reporting path, which is the only place that
+     * still has the error context; akbasic_runtime_error() sees a message and a
+     * class, both of which have already lost the number.
+     */
+    int lasterrorstatus;
+
     /*
      * The host's clock, in milliseconds, as of its last akbasic_runtime_settime()
      * call. The interpreter does not read a clock: it owns no loop and must not
@@ -164,6 +257,17 @@ typedef struct akbasic_Runtime
     /* REPL line assembly */
     char userline[AKBASIC_MAX_LINE_LENGTH];
 
+    /*
+     * Set by the scanner when the line it just read began with a line number.
+     *
+     * It is what tells the REPL apart from a program. A line typed *with* a
+     * number is program text and is filed; a line typed *without* one is a
+     * direct-mode statement and runs now. Without this the REPL could only run
+     * the handful of verbs marked immediate, so `PRINT 2 + 2` at the prompt was
+     * silently stored rather than answered -- see TODO.md section 5.
+     */
+    bool hadlinenumber;
+
     /* Scanner state */
     char line[AKBASIC_MAX_LINE_LENGTH];
     int current;
@@ -193,10 +297,33 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_init(akbasic_Runtime *obj, ak
  * @param graphics Where DRAW, BOX, CIRCLE and PAINT land; may be NULL.
  * @param audio Where SOUND, PLAY and VOL land; may be NULL.
  * @param input Where GET and GETKEY read; may be NULL.
+ * @param sprites Where SPRITE, MOVSPR and SPRSAV land; may be NULL.
  * @return `NULL` on success, otherwise an error context owned by the caller.
  * @throws AKERR_NULLPOINTER When `obj` is NULL.
  */
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_set_devices(akbasic_Runtime *obj, akbasic_GraphicsBackend *graphics, akbasic_AudioBackend *audio, akbasic_InputBackend *input);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_set_devices(akbasic_Runtime *obj, akbasic_GraphicsBackend *graphics, akbasic_AudioBackend *audio, akbasic_InputBackend *input, akbasic_SpriteBackend *sprites);
+
+/**
+ * @brief Tell the interpreter where the program it is running came from.
+ *
+ * An asset path a program writes -- `SPRSAV "ship.png", 1` -- is tried against
+ * the process working directory first and against this directory second, so a
+ * program stored beside its art works whether it was launched from its own
+ * directory or from somewhere else. Exactly what libakgl does for a sprite
+ * document naming its spritesheet.
+ *
+ * @p path is the program *file*, not its directory; the directory is taken from
+ * it. Passing NULL, or never calling this, leaves only the working directory,
+ * which is the right answer for a REPL session and for a host that handed the
+ * interpreter a string.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param path Path to the program file, or NULL for none.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When the path is longer than AKBASIC_MAX_LINE_LENGTH.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_set_source_path(akbasic_Runtime *obj, const char *path);
 
 /**
  * @brief Tell the interpreter what time the host thinks it is.
@@ -218,6 +345,153 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_set_devices(akbasic_Runtime *
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_settime(akbasic_Runtime *obj, int64_t timems);
 
+/**
+ * @brief Move every line onto a new number, rewriting every reference to one.
+ *
+ * Moving lines is a permutation of `source[]`. Rewriting `GOTO`, `GOSUB`, `RUN`,
+ * `RESTORE`, `TRAP` and `COLLISION` targets to match is the work, and doing it on
+ * source text means telling a line number apart from digits inside a string
+ * literal -- `PRINT "GOTO 10"` must survive.
+ *
+ * A target naming a line that does not exist is left alone rather than
+ * rewritten: `GOTO 9999` in a program with no line 9999 is already broken, and
+ * inventing a destination for it would hide that. A `GOTO` to a *label* needs no
+ * rewriting at all, which is the strongest argument for writing programs that
+ * way.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param newstart The number the first renumbered line takes.
+ * @param increment How far apart the new numbers are; must be positive.
+ * @param oldstart Renumber from this line on, leaving anything before it alone.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_VALUE When the increment is not positive, or a renumbered line would land on a kept one.
+ * @throws AKBASIC_ERR_BOUNDS When a new number would exceed AKBASIC_MAX_SOURCE_LINES, or a rewritten line would not fit.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_renumber(akbasic_Runtime *obj, int64_t newstart, int64_t increment, int64_t oldstart);
+
+/**
+ * @brief File every `LABEL` in the stored program before any of it runs.
+ *
+ * Without this a label exists only from the moment its `LABEL` statement
+ * executes, so `GOTO` and `GOSUB` reach backwards and never forwards -- and an
+ * interrupt handler, which by definition sits on a line normal flow does not
+ * fall into, could not be named by label at all. That is the case this exists
+ * for; forward `GOTO` is the improvement that comes with it.
+ *
+ * The scan is textual rather than a parse: `LABEL` at the start of a statement,
+ * outside a string literal, followed by an identifier. Parsing every line up
+ * front would raise on lines the program would never have reached, which is a
+ * worse trade than a scanner that understands one keyword.
+ *
+ * `LABEL` still executes normally and still files itself, so a label re-filed at
+ * run time wins. A name that appears twice therefore resolves to the last one in
+ * the source until one of them runs.
+ *
+ * Called by akbasic_runtime_set_mode() on every entry into AKBASIC_MODE_RUN,
+ * which is the one point `RUN`, `CONT`, akbasic_runtime_start() and the end of a
+ * RUNSTREAM load all pass through. A host has no reason to call it directly.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL or the runtime has no environment.
+ * @throws AKBASIC_ERR_BOUNDS When the program holds more labels than AKBASIC_MAX_LABELS.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_scan_labels(akbasic_Runtime *obj);
+
+/**
+ * @brief Point an interrupt source at a handler, replacing whatever it had.
+ *
+ * Exactly one of @p line and @p label carries the target. A label is stored by
+ * name and resolved when the interrupt fires; see #akbasic_Interrupt for why.
+ *
+ * Arming does not clear a pending event. A program that disarms and re-arms
+ * around a critical section still sees the collision that happened inside it,
+ * which is the behaviour that loses no events.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param source Which interrupt to arm.
+ * @param line Line number to enter, or 0 when @p label carries the target.
+ * @param label Label to enter, or NULL when @p line carries the target.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When `source` is out of range or the label is too long.
+ * @throws AKBASIC_ERR_VALUE When neither or both of `line` and `label` name a target.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_arm_interrupt(akbasic_Runtime *obj, akbasic_InterruptSource source, int64_t line, const char *label);
+
+/**
+ * @brief Stop an interrupt source from entering a handler.
+ *
+ * Any event already pending on it is dropped: a program that has said it no
+ * longer cares should not be sent into a handler it has just taken down.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param source Which interrupt to disarm.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When `source` is out of range.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_disarm_interrupt(akbasic_Runtime *obj, akbasic_InterruptSource source);
+
+/**
+ * @brief Record that an interrupt source fired.
+ *
+ * Cheap and safe to call every frame from a device backend, whether or not
+ * anything is armed: an unarmed source records nothing, so a host does not have
+ * to ask what the script has subscribed to. The handler is entered later, by
+ * akbasic_runtime_step(), at a line boundary -- never from inside the code that
+ * raised it.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param source Which interrupt fired.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When `source` is out of range.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_raise_interrupt(akbasic_Runtime *obj, akbasic_InterruptSource source);
+
+/**
+ * @brief Enter the handler of the first pending interrupt, if one is due.
+ *
+ * Called by akbasic_runtime_step() between source lines, which is the only place
+ * it is safe: a handler entered mid-statement would return into the middle of a
+ * line, and the parser holds no state that could resume there. That granularity
+ * is the same one block skipping already works at -- see TODO.md.
+ *
+ * Entering a handler is a GOSUB the program did not write: a scope is pushed,
+ * its return line is the line that was about to run, and the handler's RETURN
+ * pops back to it. So a handler must end in RETURN, exactly as on a C128.
+ *
+ * Sources are tried in enum order, and only one is entered per call. Nothing is
+ * entered while a handler is already running.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param entered Output destination populated by the function; true when a handler was entered. May be NULL.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_UNDEFINED When the handler's label names nothing in the program.
+ * @throws AKBASIC_ERR_ENVIRONMENT When the environment pool is exhausted.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_service_interrupts(akbasic_Runtime *obj, bool *entered);
+
+/**
+ * @brief Publish `ER#` and `EL#` into the global scope for a TRAP handler.
+ *
+ * A C128 spells these `ER` and `EL` as bare reserved names. This dialect has no
+ * bare variable names -- an identifier carries its type in a suffix, and a name
+ * without one is a label -- so they are ordinary global integers. See TODO.md
+ * section 5.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param status The status code of the error.
+ * @param line The line it was reported on.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When no variable slot is free.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_trap_set_error_variables(akbasic_Runtime *obj, int status, int64_t line);
+
 /**
  * @brief Reset the per-line state without disturbing the program or variables.
  * @param obj Object to initialize, inspect, or modify.

include/akbasic/sink.h

@@ -33,6 +33,34 @@ typedef struct akbasic_TextSink
      */
     akerr_ErrorContext AKERR_NOIGNORE *(*readline)(struct akbasic_TextSink *self, char *dest, size_t len, bool *eof);
     akerr_ErrorContext AKERR_NOIGNORE *(*clear)(struct akbasic_TextSink *self);
+    /**
+     * Put the cursor at a character cell, or NULL when the sink has no cursor.
+     *
+     * `CHAR` is the only verb that needs it, and a stdio sink genuinely cannot
+     * do it -- a terminal's cursor is not this library's to move, and a pipe has
+     * no cursor at all. So it is optional, like the audio backend's `sweep`, and
+     * `CHAR` refuses by name against a sink that leaves it NULL rather than
+     * printing in the wrong place.
+     *
+     * @param self The sink.
+     * @param col Zero-based column.
+     * @param row Zero-based row.
+     * @return `NULL` on success, otherwise an error context owned by the caller.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*moveto)(struct akbasic_TextSink *self, int col, int row);
+    /**
+     * Constrain the sink to a rectangle of character cells, or NULL when it has
+     * no grid to constrain. `WINDOW` is the only caller. Coordinates are
+     * inclusive, as BASIC 7.0 writes them.
+     *
+     * @param self The sink.
+     * @param left Leftmost column, zero-based.
+     * @param top Topmost row, zero-based.
+     * @param right Rightmost column, inclusive.
+     * @param bottom Bottommost row, inclusive.
+     * @return `NULL` on success, otherwise an error context owned by the caller.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*window)(struct akbasic_TextSink *self, int left, int top, int right, int bottom);
 } akbasic_TextSink;
 
 /** @brief State for the stdio-backed sink. */

include/akbasic/sprite.h

@@ -0,0 +1,253 @@
+/**
+ * @file sprite.h
+ * @brief Declares the sprite backend: where SPRITE, MOVSPR and SPRSAV land.
+ *
+ * The same shape as akbasic/graphics.h and for the same reason -- the core
+ * library builds with no SDL and no libakgl present, so a sprite verb calls
+ * through a record of function pointers rather than reaching for akgl_actor_*.
+ * akbasic_sprite_init_akgl() lives in the separate akbasic_akgl target.
+ *
+ * **A sprite is a Commodore sprite, not a libakgl sprite.** libakgl's has a
+ * sheet, a frame list, an animation speed and a state-to-sprite map, all of
+ * which arrive from a JSON document; BASIC 7.0 has a word for none of it. What
+ * BASIC has is eight numbered slots, each holding one still image with a
+ * position, a colour, a visibility flag and two expansion bits. So the JSON
+ * layer is bypassed rather than reached through: the adaptor builds the same
+ * structures directly and hands the interpreter this much smaller surface.
+ *
+ * The one place the two overlap is loading an image from a file, which is why
+ * `define_file` is here: a program that has art on disk should be able to say so,
+ * and libakgl already resolves a relative asset path and decodes the image. That
+ * path is not bypassed -- it is exactly akgl_spritesheet_initialize().
+ *
+ * A runtime with no sprite backend is the normal case, so every verb that needs
+ * one refuses with AKBASIC_ERR_DEVICE. The verbs that only touch interpreter
+ * state -- SPRCOLOR, and the RSP* readbacks -- work regardless, which is what
+ * makes them testable without a device.
+ */
+
+#ifndef _AKBASIC_SPRITE_H_
+#define _AKBASIC_SPRITE_H_
+
+#include <akerror.h>
+
+#include <akbasic/graphics.h>
+#include <akbasic/types.h>
+
+/** @brief Sprites a program has. Eight, as on a C128; the verbs number them 1-8. */
+#define AKBASIC_MAX_SPRITES		8
+
+/** @brief Width of a Commodore sprite in pixels. */
+#define AKBASIC_SPRITE_WIDTH		24
+/** @brief Height of a Commodore sprite in pixels. */
+#define AKBASIC_SPRITE_HEIGHT		21
+/**
+ * @brief Bytes in a sprite pattern: three per row, twenty-one rows.
+ *
+ * The C128 documents SPRSAV's string as the SSHAPE data format at a fixed 24x21,
+ * which is 63 bytes of bitmap plus a four-byte header. Only the bitmap is
+ * carried here -- the header records a width and height that are constants for a
+ * sprite -- so a DIMmed integer array of this many elements is a whole pattern.
+ */
+#define AKBASIC_SPRITE_PATTERN_BYTES	63
+
+/**
+ * @brief Fastest MOVSPR speed, and how far one unit of it travels.
+ *
+ * `MOVSPR n, angle # speed` takes 0-15 on a C128 and the reference manual does
+ * not say what a unit is in pixels; it says 15 is fastest and 0 stops. So the
+ * mapping is ours: one unit is #AKBASIC_SPRITE_SPEED_PIXELS_PER_SECOND pixels
+ * per second in BASIC's 320x200 space, which puts speed 15 at four seconds to
+ * cross the screen. Recorded as a deviation in TODO.md section 5 rather than
+ * presented as fidelity.
+ */
+#define AKBASIC_SPRITE_MAX_SPEED	15
+/** @brief Pixels per second one unit of MOVSPR speed is worth. See #AKBASIC_SPRITE_MAX_SPEED. */
+#define AKBASIC_SPRITE_SPEED_PIXELS_PER_SECOND	5.0
+
+/**
+ * @brief One sprite, as BASIC sees it.
+ *
+ * Every field here is something a BASIC verb sets and an RSP* function reads
+ * back, which is why the whole thing lives on the runtime rather than on the
+ * device: a host that swaps one renderer for another does not expect the
+ * program's sprite positions to go with it. The device is told about changes; it
+ * is never asked what they were.
+ */
+typedef struct
+{
+    bool defined;		/* SPRSAV has given this slot an image		*/
+    bool enabled;		/* SPRITE n, 1					*/
+    bool behind;		/* priority: drawn behind the drawing surface	*/
+    bool xexpand;		/* SPRITE's x-expand bit			*/
+    bool yexpand;
+    bool multicolour;
+    int colorindex;		/* 1-16, the sprite's own colour		*/
+    double x;			/* position in BASIC's 320x200 space		*/
+    double y;
+    double angle;		/* MOVSPR's continuous motion: degrees		*/
+    int speed;			/*   clockwise from vertical, and 0-15		*/
+} akbasic_Sprite;
+
+/**
+ * @brief The sprite verbs' own state, which lives on the runtime.
+ *
+ * `bumped` accumulates rather than reporting an instant. A collision that
+ * happens between two BUMP() calls is still news when the second one asks, and a
+ * program polling once a frame would otherwise miss anything that started and
+ * ended inside a frame. BUMP() clears what it reports, which is what a C128 does
+ * and what makes "has this sprite hit anything since I last looked" answerable.
+ */
+typedef struct
+{
+    akbasic_Sprite sprites[AKBASIC_MAX_SPRITES];
+    int sharedcolor1;		/* SPRCOLOR's two multicolour registers, 1-16	*/
+    int sharedcolor2;
+    uint16_t bumped;		/* bit n-1 set when sprite n has collided	*/
+    int64_t lastservicems;	/* when MOVSPR's continuous motion last moved	*/
+} akbasic_SpriteState;
+
+/**
+ * @brief Where the sprite verbs land.
+ *
+ * Sprites are numbered 1 through #AKBASIC_MAX_SPRITES at this boundary, the same
+ * way a BASIC program numbers them. Translating to a zero-based slot is the
+ * backend's business, and doing it here would mean two numbering schemes in one
+ * file for no gain.
+ *
+ * There is deliberately no entry point for the RSP* readbacks. Everything they
+ * report is in #akbasic_SpriteState, which the interpreter owns, so asking the
+ * device would be asking it to repeat what it was told.
+ */
+typedef struct akbasic_SpriteBackend
+{
+    void *self;
+
+    /**
+     * Install a pattern into sprite @p n from packed bitmap bytes.
+     *
+     * Three bytes per row, most significant bit leftmost, twenty-one rows --
+     * the layout a C128 keeps in its sprite block, and what a type-in listing's
+     * DATA statements hold. @p fg is what a set bit draws and @p bg what a clear
+     * one does; a clear bit is normally transparent, which is @p bg with a zero
+     * alpha.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*define)(struct akbasic_SpriteBackend *self, int n, const uint8_t *pattern, int bytes, akbasic_Color fg, akbasic_Color bg);
+    /**
+     * Install a pattern into sprite @p n from a region SSHAPE saved.
+     *
+     * The handle is the graphics backend's, not this one's -- SSHAPE puts it in
+     * a BASIC string and SPRSAV hands it straight back. An adaptor that serves
+     * both devices resolves it; one that does not may refuse with
+     * AKBASIC_ERR_DEVICE.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*define_shape)(struct akbasic_SpriteBackend *self, int n, int handle);
+    /**
+     * Install a pattern into sprite @p n by loading an image file.
+     *
+     * @p path is what the program wrote, resolved by the backend rather than
+     * here: the interpreter has no idea what a path means to the host, and the
+     * akgl adaptor resolves it exactly as libakgl resolves a spritesheet named
+     * by a sprite document. @p root is the directory to fall back to when the
+     * path does not resolve against the working directory, normally the
+     * directory the running program was loaded from; it may be NULL.
+     *
+     * Unlike the other two, this one does not force 24x21: the image's own size
+     * is the sprite's size. A modern PC has no reason to throw away art that
+     * does not happen to be sprite-shaped.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*define_file)(struct akbasic_SpriteBackend *self, int n, const char *path, const char *root);
+    /** Show or hide sprite @p n. */
+    akerr_ErrorContext AKERR_NOIGNORE *(*show)(struct akbasic_SpriteBackend *self, int n, bool visible);
+    /** Put sprite @p n at (@p x, @p y) in BASIC's 320x200 space. */
+    akerr_ErrorContext AKERR_NOIGNORE *(*move)(struct akbasic_SpriteBackend *self, int n, double x, double y);
+    /**
+     * Set sprite @p n's own colour, its expansion bits and its priority.
+     *
+     * One call rather than four because `SPRITE` sets them together and a
+     * backend that has to rebuild a texture to change a colour would otherwise
+     * do it four times for one statement.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*configure)(struct akbasic_SpriteBackend *self, int n, akbasic_Color color, bool xexpand, bool yexpand, bool behind);
+    /** Set the two multicolour registers every multicolour sprite shares. */
+    akerr_ErrorContext AKERR_NOIGNORE *(*shared_colors)(struct akbasic_SpriteBackend *self, akbasic_Color c1, akbasic_Color c2);
+    /**
+     * Report which sprites are currently overlapping another sprite.
+     *
+     * Bit n-1 of @p mask is set when sprite n overlaps at least one other. The
+     * interpreter calls this once per step, ORs the result into
+     * akbasic_SpriteState::bumped, and raises the collision interrupt when
+     * anything is set -- so a backend answers about *now* and does not have to
+     * remember anything.
+     */
+    akerr_ErrorContext AKERR_NOIGNORE *(*collisions)(struct akbasic_SpriteBackend *self, uint16_t *mask);
+} akbasic_SpriteBackend;
+
+/**
+ * @brief Reset the sprite state to its power-on values.
+ *
+ * Eight undefined, hidden sprites at the origin in white, the two shared
+ * multicolour registers at their C128 defaults, and nothing bumped. NEW comes
+ * back through here.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_sprite_state_init(akbasic_SpriteState *obj);
+
+/**
+ * @brief Unpack 63 bytes of sprite bitmap into one pixel per byte.
+ *
+ * Three bytes per row, most significant bit leftmost. @p dest receives
+ * #AKBASIC_SPRITE_WIDTH * #AKBASIC_SPRITE_HEIGHT entries, each 0 or 1. Shared by
+ * every backend that has to turn a pattern into pixels, and separate from them
+ * so the bit order is asserted once rather than trusted eight times.
+ *
+ * @param pattern Packed bitmap; at least @p bytes readable.
+ * @param bytes How many bytes @p pattern holds; must be #AKBASIC_SPRITE_PATTERN_BYTES.
+ * @param dest Output destination populated by the function; 504 entries.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When either pointer is NULL.
+ * @throws AKBASIC_ERR_BOUNDS When `bytes` is not #AKBASIC_SPRITE_PATTERN_BYTES.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_sprite_unpack(const uint8_t *pattern, int bytes, uint8_t *dest);
+
+struct akbasic_Runtime;
+
+/**
+ * @brief Move every sprite MOVSPR set in continuous motion.
+ *
+ * Called once per akbasic_runtime_step(), before the line runs, and paced off
+ * akbasic_runtime_settime() -- exactly the way the PLAY queue is paced, and for
+ * the same reason: this library owns no loop and must not block, so the caller
+ * that owns the frame owns the clock.
+ *
+ * A host that never sets the time leaves it at zero and nothing moves, which is
+ * a still picture rather than a hang.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_sprite_service(struct akbasic_Runtime *obj);
+
+/**
+ * @brief Ask the device what is overlapping, and raise the collision interrupt.
+ *
+ * Also called once per step. What it finds is ORed into
+ * akbasic_SpriteState::bumped for BUMP() to report, and raised as
+ * #AKBASIC_INTERRUPT_SPRITE -- unconditionally, because an unarmed interrupt
+ * records nothing and there is therefore nothing to ask first.
+ *
+ * A runtime with no sprite device, or one whose backend withholds `collisions`,
+ * does nothing here rather than refusing: a step is not a statement and has no
+ * program line to blame.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_collision_service(struct akbasic_Runtime *obj);
+
+#endif // _AKBASIC_SPRITE_H_

include/akbasic/types.h

@@ -31,6 +31,13 @@
 #define AKBASIC_MAX_ENVIRONMENTS	32	/* new: Go allocated these unbounded */
 #define AKBASIC_MAX_FUNCTIONS		64	/* new: Go used an unbounded map */
 #define AKBASIC_MAX_LABELS		64	/* new: Go used an unbounded map */
+/*
+ * Leaves a DO/LOOP condition may use. Its own small pool rather than a second
+ * AKBASIC_MAX_LEAVES one, because a leaf carries two 256-byte strings and this
+ * is per environment: `DO WHILE A# = 1 AND B# = 2` is six leaves, and sixteen
+ * leaves nobody uses on every one of 32 scopes is 250 KB of nothing.
+ */
+#define AKBASIC_MAX_CONDITION_LEAVES	16
 
 /* Commodore convention: true is -1, not 1. */
 #define AKBASIC_TRUE			-1

include/akbasic/value.h

@@ -76,6 +76,19 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_value_set_bool(akbasic_Value *obj, bo
 /** @brief True when the value is a boolean holding AKBASIC_TRUE. */
 bool akbasic_value_is_true(akbasic_Value *self);
 
+/**
+ * @brief True when the value is nonzero, whatever numeric type it carries.
+ *
+ * What a condition tests. Commodore BASIC has no boolean type -- a comparison
+ * yields -1 or 0, `AND` and `OR` are the bitwise operators, and `IF A THEN` is
+ * legal for any numeric A -- so "is this a boolean holding true" is the wrong
+ * question for a branch to ask. Strings are never true.
+ *
+ * @param self Value to test; NULL is not true.
+ * @return `true` when the value is a nonzero number or a true truth value.
+ */
+bool akbasic_value_is_truthy(akbasic_Value *self);
+
 /**
  * @brief Negate a numeric value.
  *

src/args.c

@@ -0,0 +1,43 @@
+/**
+ * @file args.c
+ * @brief Implements the shared positional-argument collector.
+ */
+
+#include <akerror.h>
+
+#include <akbasic/args.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+akerr_ErrorContext *akbasic_args_numbers(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb, double *values, int max, int *count)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Value *value = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && expr != NULL && values != NULL && count != NULL),
+		     AKERR_NULLPOINTER, "NULL argument in args_numbers");
+    *count = 0;
+    arg = akbasic_leaf_first_argument(expr);
+    /*
+     * A loop, so CATCH and the _BREAK macros are banned in here -- they expand to
+     * a C break and would leave the loop with an error still pending. PASS and
+     * the _RETURN forms only.
+     */
+    while ( arg != NULL ) {
+	FAIL_NONZERO_RETURN(errctx, (*count >= max), AKBASIC_ERR_SYNTAX,
+			    "%s takes at most %d arguments", verb, max);
+	PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+	FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING),
+			    AKBASIC_ERR_TYPE,
+			    "%s expected a number in argument %d", verb, *count + 1);
+	if ( value->valuetype == AKBASIC_TYPE_FLOAT ) {
+	    values[*count] = value->floatval;
+	} else {
+	    values[*count] = (double)value->intval;
+	}
+	*count += 1;
+	arg = arg->next;
+    }
+    SUCCEED_RETURN(errctx);
+}

src/data.c

@@ -0,0 +1,211 @@
+/**
+ * @file data.c
+ * @brief Implements the `DATA` item list and the `READ` cursor.
+ */
+
+#include <ctype.h>
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akbasic/data.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+akerr_ErrorContext *akbasic_data_state_init(akbasic_DataState *obj)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL data state in init");
+    obj->count = 0;
+    obj->cursor = 0;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Collect the items of one `DATA` statement.
+ *
+ * @param obj The list to append to.
+ * @param cursor Points just past the `DATA` keyword; advanced past what is read.
+ * @param lineno The line these items were written on.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKBASIC_ERR_BOUNDS When the list is full or an item is too long.
+ */
+static akerr_ErrorContext *collect_items(akbasic_DataState *obj, const char **cursor, int64_t lineno)
+{
+    PREPARE_ERROR(errctx);
+    const char *p = *cursor;
+
+    for ( ;; ) {
+	akbasic_DataItem *item = NULL;
+	size_t used = 0;
+
+	while ( *p == ' ' || *p == '\t' ) {
+	    p += 1;
+	}
+	if ( *p == '\0' || *p == ':' ) {
+	    break;
+	}
+	FAIL_ZERO_RETURN(errctx, (obj->count < AKBASIC_MAX_DATA_ITEMS), AKBASIC_ERR_BOUNDS,
+			 "The program holds more than %d DATA items", AKBASIC_MAX_DATA_ITEMS);
+	item = &obj->items[obj->count];
+	item->lineno = lineno;
+	item->quoted = false;
+
+	if ( *p == '"' ) {
+	    /*
+	     * A quoted item runs to its closing quote and may hold anything --
+	     * commas, colons, spaces. That is the only way to put a comma in a
+	     * DATA item, and it is why the scan has to understand quotes at all.
+	     */
+	    item->quoted = true;
+	    p += 1;
+	    while ( *p != '\0' && *p != '"' && used < sizeof(item->text) - 1 ) {
+		item->text[used] = *p;
+		used += 1;
+		p += 1;
+	    }
+	    if ( *p == '"' ) {
+		p += 1;
+	    }
+	} else {
+	    while ( *p != '\0' && *p != ',' && *p != ':' && used < sizeof(item->text) - 1 ) {
+		item->text[used] = *p;
+		used += 1;
+		p += 1;
+	    }
+	    /* Trailing spaces are not part of an unquoted item. */
+	    while ( used > 0 && (item->text[used - 1] == ' ' || item->text[used - 1] == '\t') ) {
+		used -= 1;
+	    }
+	}
+	item->text[used] = '\0';
+	obj->count += 1;
+
+	while ( *p == ' ' || *p == '\t' ) {
+	    p += 1;
+	}
+	if ( *p != ',' ) {
+	    break;
+	}
+	p += 1;
+    }
+    *cursor = p;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Scan one source line for `DATA` statements.
+ *
+ * Walks statement by statement, the way scan_line_labels() does, because `DATA`
+ * is a verb and a verb starts a statement -- and a string literal is the only
+ * thing that can hide a separator.
+ */
+static akerr_ErrorContext *scan_line(akbasic_DataState *obj, const char *code, int64_t lineno)
+{
+    PREPARE_ERROR(errctx);
+    const char *cursor = code;
+    bool statementstart = true;
+    bool instring = false;
+
+    while ( *cursor != '\0' ) {
+	if ( instring ) {
+	    instring = (*cursor != '"');
+	    cursor += 1;
+	    continue;
+	}
+	if ( *cursor == '"' ) {
+	    instring = true;
+	    statementstart = false;
+	    cursor += 1;
+	    continue;
+	}
+	if ( *cursor == ':' ) {
+	    statementstart = true;
+	    cursor += 1;
+	    continue;
+	}
+	if ( isspace((unsigned char)*cursor) ) {
+	    cursor += 1;
+	    continue;
+	}
+	/* A stored line may still carry its own number; see scan_line_labels(). */
+	if ( statementstart && isdigit((unsigned char)*cursor) ) {
+	    while ( isdigit((unsigned char)*cursor) ) {
+		cursor += 1;
+	    }
+	    continue;
+	}
+	if ( statementstart && strncasecmp(cursor, "DATA", 4) == 0
+	     && !isalnum((unsigned char)cursor[4]) ) {
+	    cursor += 4;
+	    PASS(errctx, collect_items(obj, &cursor, lineno));
+	    statementstart = false;
+	    continue;
+	}
+	statementstart = false;
+	cursor += 1;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_data_scan(akbasic_Runtime *obj)
+{
+    PREPARE_ERROR(errctx);
+    int64_t i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in data_scan");
+    PASS(errctx, akbasic_data_state_init(&obj->data_state));
+    for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
+	if ( obj->source[i].code[0] != '\0' ) {
+	    PASS(errctx, scan_line(&obj->data_state, obj->source[i].code, i));
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_data_next(akbasic_Runtime *obj, akbasic_Type type, akbasic_Value *dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_DataItem *item = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in data_next");
+    FAIL_ZERO_RETURN(errctx, (obj->data_state.cursor < obj->data_state.count),
+		     AKBASIC_ERR_STATE, "OUT OF DATA");
+    item = &obj->data_state.items[obj->data_state.cursor];
+    obj->data_state.cursor += 1;
+
+    PASS(errctx, akbasic_value_zero(dest));
+    if ( type == AKBASIC_TYPE_STRING ) {
+	dest->valuetype = AKBASIC_TYPE_STRING;
+	snprintf(dest->stringval, sizeof(dest->stringval), "%s", item->text);
+	SUCCEED_RETURN(errctx);
+    }
+
+    /*
+     * A quoted item is a string and reading it into a number is a mistake worth
+     * reporting -- `READ A#` against `DATA "TEXT"` would otherwise quietly yield
+     * zero. An *unquoted* item that is not a number is caught the same way, by
+     * the conversion refusing it.
+     */
+    FAIL_NONZERO_RETURN(errctx, item->quoted, AKBASIC_ERR_TYPE,
+			"READ: DATA item \"%s\" on line %" PRId64 " is a string",
+			item->text, item->lineno);
+    if ( type == AKBASIC_TYPE_FLOAT ) {
+	dest->valuetype = AKBASIC_TYPE_FLOAT;
+	PASS(errctx, aksl_atof(item->text, &dest->floatval));
+    } else {
+	long long converted = 0;
+
+	dest->valuetype = AKBASIC_TYPE_INTEGER;
+	PASS(errctx, aksl_atoll(item->text, &converted));
+	dest->intval = (int64_t)converted;
+    }
+    SUCCEED_RETURN(errctx);
+}

src/environment.c

@@ -30,12 +30,19 @@ akerr_ErrorContext *akbasic_environment_init(akbasic_Environment *obj, akbasic_R
     obj->forToLeaf = NULL;
     obj->loopFirstLine = 0;
     obj->loopExitLine = 0;
+    obj->exiting = false;
+    obj->doConditionLeaf = NULL;
+    obj->doConditionKind = AKBASIC_LOOPCOND_NONE;
+    obj->isDoLoop = false;
     obj->gosubReturnLine = 0;
     obj->readReturnLine = 0;
     obj->readIdentifierIdx = 0;
     obj->waitingForCommand[0] = '\0';
     obj->errorToken = NULL;
     memset(obj->readIdentifierLeaves, 0, sizeof(obj->readIdentifierLeaves));
+    obj->doLeafPool.next = 0;
+    obj->doLeafPool.capacity = AKBASIC_MAX_CONDITION_LEAVES;
+    obj->doLeafPool.leaves = obj->doLeafStorage;
     obj->readLeafPool.next = 0;
     obj->readLeafPool.capacity = AKBASIC_MAX_LEAVES;
     obj->readLeafPool.leaves = obj->readLeafStorage;

src/format.c

@@ -0,0 +1,354 @@
+/**
+ * @file format.c
+ * @brief Implements `PRINT USING` field formatting.
+ *
+ * One field per call, with whatever literal text surrounds it copied through.
+ * The work splits three ways: find the field, measure it, then fill it.
+ */
+
+#include <inttypes.h>
+#include <math.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <akerror.h>
+
+#include <akbasic/error.h>
+#include <akbasic/format.h>
+
+/** @brief The PUDEF defaults, in PUDEF's own order. */
+static const char PUDEF_DEFAULTS[AKBASIC_PUDEF_CHARS] = { ' ', ',', '.', '$' };
+
+/** @brief True for a character that can only appear inside a numeric field. */
+static bool is_numeric_field_char(char c)
+{
+    return (c == '#' || c == ',' || c == '.');
+}
+
+/** @brief True for a character that can only appear inside a string field. */
+static bool is_string_field_char(char c)
+{
+    return (c == '=' || c == '>');
+}
+
+akerr_ErrorContext *akbasic_format_state_init(akbasic_FormatState *obj)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL format state in init");
+    memcpy(obj->chars, PUDEF_DEFAULTS, sizeof(obj->chars));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_format_pudef(akbasic_FormatState *obj, const char *chars)
+{
+    PREPARE_ERROR(errctx);
+    int i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && chars != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in pudef");
+    /*
+     * Only as many as were given. `PUDEF "*"` redefines the leading blank and
+     * leaves the comma, the point and the dollar alone, which is BASIC 7.0's
+     * rule and is what makes the one-character form useful.
+     */
+    for ( i = 0; i < AKBASIC_PUDEF_CHARS && chars[i] != '\0'; i++ ) {
+	obj->chars[i] = chars[i];
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Locate the first field in a format string.
+ *
+ * @param format The format string.
+ * @param start Output: index of the field's first character.
+ * @param length Output: how many characters the field spans.
+ * @param numeric Output: true for a numeric field, false for a string field.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKBASIC_ERR_SYNTAX When there is no field.
+ */
+static akerr_ErrorContext *find_field(const char *format, size_t *start, size_t *length, bool *numeric)
+{
+    PREPARE_ERROR(errctx);
+    size_t i = 0;
+
+    for ( i = 0; format[i] != '\0'; i++ ) {
+	if ( format[i] == '#' || format[i] == '.' ) {
+	    *numeric = true;
+	    break;
+	}
+	if ( is_string_field_char(format[i]) ) {
+	    *numeric = false;
+	    break;
+	}
+    }
+    FAIL_ZERO_RETURN(errctx, (format[i] != '\0'), AKBASIC_ERR_SYNTAX,
+		     "PRINT USING format \"%s\" contains no field", format);
+
+    /*
+     * A `$`, `+` or `-` immediately before the field belongs to it. Scanning
+     * backwards is how a leading sign or currency sign is told apart from
+     * literal text: `"COST $###"` has a field of `$###`, and `"A + B ###"` does
+     * not, because the `+` is not adjacent.
+     */
+    *start = i;
+    while ( *start > 0 && (format[*start - 1] == '$' || format[*start - 1] == '+' ||
+			   format[*start - 1] == '-') ) {
+	*start -= 1;
+    }
+
+    for ( ; format[i] != '\0'; i++ ) {
+	if ( *numeric && is_numeric_field_char(format[i]) ) {
+	    continue;
+	}
+	if ( !(*numeric) && is_string_field_char(format[i]) ) {
+	    continue;
+	}
+	break;
+    }
+    /* A trailing sign belongs to the field too. */
+    if ( format[i] == '+' || format[i] == '-' ) {
+	i += 1;
+    }
+    *length = i - *start;
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Measure a numeric field: digits before and after the point, and its decorations. */
+static void measure_numeric(const char *field, size_t length, int *before, int *after,
+			    bool *commas, bool *dollar, bool *leadsign, bool *trailsign)
+{
+    size_t i = 0;
+    bool seenpoint = false;
+
+    *before = 0;
+    *after = 0;
+    *commas = false;
+    *dollar = false;
+    *leadsign = false;
+    *trailsign = false;
+
+    for ( i = 0; i < length; i++ ) {
+	switch ( field[i] ) {
+	case '#':
+	    if ( seenpoint ) {
+		*after += 1;
+	    } else {
+		*before += 1;
+	    }
+	    break;
+	case '.':
+	    seenpoint = true;
+	    break;
+	case ',':
+	    *commas = true;
+	    break;
+	case '$':
+	    *dollar = true;
+	    break;
+	case '+':
+	case '-':
+	    if ( i == 0 ) {
+		*leadsign = true;
+	    } else {
+		*trailsign = true;
+	    }
+	    break;
+	default:
+	    break;
+	}
+    }
+}
+
+/** @brief Fill @p dest with @p width copies of `*`, the overflow marker. */
+static void overflow(char *dest, size_t width)
+{
+    memset(dest, '*', width);
+    dest[width] = '\0';
+}
+
+/**
+ * @brief Render a number into a measured numeric field.
+ *
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *render_numeric(akbasic_FormatState *obj, const char *field, size_t length,
+					  double number, char *dest, size_t len)
+{
+    PREPARE_ERROR(errctx);
+    char digits[AKBASIC_MAX_STRING_LENGTH];
+    char grouped[AKBASIC_MAX_STRING_LENGTH];
+    char *point = NULL;
+    size_t used = 0;
+    size_t i = 0;
+    size_t intlen = 0;
+    int before = 0;
+    int after = 0;
+    int group = 0;
+    bool commas = false;
+    bool dollar = false;
+    bool leadsign = false;
+    bool trailsign = false;
+    bool negative = (number < 0.0);
+
+    measure_numeric(field, length, &before, &after, &commas, &dollar, &leadsign, &trailsign);
+    FAIL_ZERO_RETURN(errctx, (length + 1 <= len), AKBASIC_ERR_BOUNDS,
+		     "PRINT USING field of %zu characters does not fit", length);
+
+    snprintf(digits, sizeof(digits), "%.*f", after, (negative ? -number : number));
+
+    point = strchr(digits, '.');
+    intlen = (point != NULL ? (size_t)(point - digits) : strlen(digits));
+
+    /* Group the integer part, if the field asked for separators. */
+    used = 0;
+    if ( commas ) {
+	for ( i = 0; i < intlen; i++ ) {
+	    if ( i > 0 && ((intlen - i) % 3) == 0 ) {
+		grouped[used] = obj->chars[AKBASIC_PUDEF_COMMA];
+		used += 1;
+	    }
+	    grouped[used] = digits[i];
+	    used += 1;
+	}
+    } else {
+	memcpy(grouped, digits, intlen);
+	used = intlen;
+    }
+    grouped[used] = '\0';
+    group = (int)used;
+
+    /*
+     * Does it fit? The field's `#` positions before the point are the budget,
+     * and a separator or a sign that the field asked for costs nothing extra
+     * because it was written into the field. Overflow fills with `*` rather than
+     * printing wider than asked, which would misalign every later column.
+     */
+    if ( (int)intlen > before ) {
+	overflow(dest, length);
+	SUCCEED_RETURN(errctx);
+    }
+
+    used = 0;
+    if ( leadsign ) {
+	dest[used] = (negative ? '-' : '+');
+	used += 1;
+    }
+    if ( dollar ) {
+	dest[used] = obj->chars[AKBASIC_PUDEF_DOLLAR];
+	used += 1;
+    }
+    /*
+     * Right-justify inside the digit positions, padding with the PUDEF blank.
+     * The width to pad to counts the separators the field will actually use, so
+     * `###,###` holding 1234 pads to the same column every time.
+     */
+    {
+	int width = before + (commas ? (before - 1) / 3 : 0);
+
+	for ( i = (size_t)group; (int)i < width; i++ ) {
+	    dest[used] = obj->chars[AKBASIC_PUDEF_BLANK];
+	    used += 1;
+	}
+    }
+    memcpy(dest + used, grouped, (size_t)group);
+    used += (size_t)group;
+
+    if ( after > 0 ) {
+	dest[used] = obj->chars[AKBASIC_PUDEF_POINT];
+	used += 1;
+	memcpy(dest + used, (point != NULL ? point + 1 : ""), (size_t)after);
+	used += (size_t)after;
+    }
+    if ( trailsign ) {
+	dest[used] = (negative ? '-' : '+');
+	used += 1;
+    }
+    /*
+     * A negative number in a field with no sign position still has to say so.
+     * BASIC 7.0 overflows the field in that case rather than dropping the minus,
+     * because a printed -5 that reads as 5 is worse than a row of stars.
+     */
+    if ( negative && !leadsign && !trailsign ) {
+	overflow(dest, length);
+	SUCCEED_RETURN(errctx);
+    }
+    dest[used] = '\0';
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Render a string into a measured string field: `=` centres, `>` right-justifies. */
+static akerr_ErrorContext *render_string(const char *field, size_t length, const char *text,
+					 char *dest, size_t len)
+{
+    PREPARE_ERROR(errctx);
+    size_t textlen = strlen(text);
+    size_t pad = 0;
+
+    FAIL_ZERO_RETURN(errctx, (length + 1 <= len), AKBASIC_ERR_BOUNDS,
+		     "PRINT USING field of %zu characters does not fit", length);
+    if ( textlen > length ) {
+	/* Truncated, not starred: BASIC 7.0 cuts a string to its field. */
+	memcpy(dest, text, length);
+	dest[length] = '\0';
+	SUCCEED_RETURN(errctx);
+    }
+
+    memset(dest, ' ', length);
+    dest[length] = '\0';
+    if ( field[0] == '=' ) {
+	pad = (length - textlen) / 2;
+    } else {
+	pad = length - textlen;
+    }
+    memcpy(dest + pad, text, textlen);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_format_using(akbasic_FormatState *obj, const char *format, akbasic_Value *value, char *dest, size_t len)
+{
+    PREPARE_ERROR(errctx);
+    char rendered[AKBASIC_MAX_STRING_LENGTH];
+    size_t start = 0;
+    size_t length = 0;
+    size_t used = 0;
+    bool numeric = false;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && format != NULL && value != NULL && dest != NULL),
+		     AKERR_NULLPOINTER, "NULL argument in format_using");
+    FAIL_ZERO_RETURN(errctx, (len > 0), AKBASIC_ERR_BOUNDS, "Zero-length destination");
+
+    PASS(errctx, find_field(format, &start, &length, &numeric));
+
+    if ( numeric ) {
+	double number = 0.0;
+
+	FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			    "PRINT USING: a numeric field cannot print a string");
+	if ( value->valuetype == AKBASIC_TYPE_FLOAT ) {
+	    number = value->floatval;
+	} else if ( value->valuetype == AKBASIC_TYPE_BOOLEAN ) {
+	    number = (double)value->boolvalue;
+	} else {
+	    number = (double)value->intval;
+	}
+	PASS(errctx, render_numeric(obj, format + start, length, number,
+				    rendered, sizeof(rendered)));
+    } else {
+	FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			    "PRINT USING: a string field cannot print a number");
+	PASS(errctx, render_string(format + start, length, value->stringval,
+				   rendered, sizeof(rendered)));
+    }
+
+    /* Literal text before the field, the field, then literal text after it. */
+    used = strlen(rendered) + strlen(format) - length;
+    FAIL_ZERO_RETURN(errctx, (used + 1 <= len), AKBASIC_ERR_BOUNDS,
+		     "PRINT USING result of %zu characters does not fit", used);
+    memcpy(dest, format, start);
+    memcpy(dest + start, rendered, strlen(rendered));
+    snprintf(dest + start + strlen(rendered), len - start - strlen(rendered),
+	     "%s", format + start + length);
+    SUCCEED_RETURN(errctx);
+}

src/frontend_akgl.c

@@ -37,6 +37,8 @@
  * to populate it itself. deps/libakgl/tests/draw.c does the same.
  */
 #include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/registry.h>
 #include <akgl/renderer.h>
 
 #include <akbasic/error.h>
@@ -102,6 +104,41 @@ akerr_ErrorContext *akbasic_frontend_akgl_init(akbasic_AkglFrontend *obj, const
      */
     PASS(errctx, akgl_render_bind2d(obj->renderer));
 
+    /*
+     * The object pools and the name registries. Every akgl_*_initialize ends in
+     * a registry write and fails AKERR_KEY without these, so anything drawn as
+     * an actor -- which is what a BASIC sprite is -- needs them. akgl_game_init()
+     * is where they would normally be done, and it is the function goal 3 keeps
+     * this host out of.
+     *
+     * Unconditional, and it has to be. akgl_registry_init() overwrites the
+     * property-set ids without destroying the old sets, so repeating it would
+     * normally leak -- but this frontend owns SDL_Init and SDL_Quit, and
+     * SDL_Quit destroys every property set while leaving libakgl's ids pointing
+     * at them. So the previous registries are already gone, and skipping the
+     * call on the strength of a non-zero id is what actually breaks: the second
+     * frontend of a process gets ids that name nothing, and the first
+     * akgl_sprite_initialize fails AKERR_KEY.
+     *
+     * A game that embeds the interpreter does not link this file. It has already
+     * called akgl_game_init(), which does both of these itself.
+     */
+    PASS(errctx, akgl_heap_init());
+    PASS(errctx, akgl_registry_init());
+
+    /*
+     * And the camera. akgl_actor_render() dereferences this global to translate
+     * world coordinates into screen ones and does not check it, so an unset
+     * camera is a crash the first time a sprite is drawn rather than an error
+     * anybody could act on. One screen's worth at the origin: BASIC has no verb
+     * that scrolls a view, so the world and the screen are the same thing here.
+     */
+    camera = &_akgl_camera;
+    camera->x = 0.0f;
+    camera->y = 0.0f;
+    camera->w = (float)w;
+    camera->h = (float)h;
+
     obj->font = TTF_OpenFont(fontpath, (float)fontsize);
     FAIL_ZERO_RETURN(errctx, (obj->font != NULL), AKGL_ERR_SDL,
 		     "Couldn't open the font %s: %s", fontpath, SDL_GetError());
@@ -131,6 +168,13 @@ akerr_ErrorContext *akbasic_frontend_akgl_init(akbasic_AkglFrontend *obj, const
     PASS(errctx, akbasic_graphics_init_akgl(&obj->graphics, &obj->graphicsstate,
 					    obj->renderer));
     PASS(errctx, akbasic_input_init_akgl(&obj->input));
+    /*
+     * The graphics state goes with it so SPRSAV can turn an SSHAPE handle into a
+     * sprite. The two devices stay separate records -- a host may lend one and
+     * withhold the other -- and this is the one place they meet.
+     */
+    PASS(errctx, akbasic_sprite_init_akgl(&obj->sprites, &obj->spritesstate,
+					  obj->renderer, &obj->graphicsstate));
 
     /*
      * Audio last, in its own subsystem, and allowed to fail. The reference asks
@@ -170,7 +214,7 @@ akerr_ErrorContext *akbasic_frontend_akgl_attach(akbasic_AkglFrontend *obj, akba
     PASS(errctx, akbasic_runtime_init(rt, &obj->sink));
     PASS(errctx, akbasic_runtime_set_devices(rt, &obj->graphics,
 					     (obj->audioready ? &obj->audio : NULL),
-					     &obj->input));
+					     &obj->input, &obj->sprites));
     SUCCEED_RETURN(errctx);
 }
 
@@ -224,6 +268,13 @@ akerr_ErrorContext *akbasic_frontend_akgl_pump(void *self, bool *running)
      * bitmap plane.
      */
     PASS(errctx, akbasic_sink_akgl_render(&obj->akglsink));
+    /*
+     * Sprites last, so they are over the text as well as over the drawing. That
+     * is what a C128 does with a high-priority sprite, and the low-priority case
+     * -- behind the bitmap plane -- has nowhere to go here: see the note in
+     * spr_configure().
+     */
+    PASS(errctx, akbasic_sprite_akgl_render(&obj->sprites));
     FAIL_ZERO_RETURN(errctx, SDL_RenderPresent(obj->renderer->sdl_renderer),
 		     AKGL_ERR_SDL, "Couldn't present the frame: %s", SDL_GetError());
     SUCCEED_RETURN(errctx);
@@ -266,6 +317,8 @@ void akbasic_frontend_akgl_shutdown(akbasic_AkglFrontend *obj)
     if ( obj == NULL ) {
 	return;
     }
+    /* Before the renderer goes: these are textures it created. */
+    akbasic_sprite_akgl_shutdown(&obj->sprites);
     if ( obj->font != NULL ) {
 	TTF_CloseFont(obj->font);
 	obj->font = NULL;

src/grammar.c

@@ -143,6 +143,24 @@ bool akbasic_leaf_is_identifier(akbasic_ASTLeaf *self)
 	     self->leaftype == AKBASIC_LEAF_IDENTIFIER_STRING));
 }
 
+akbasic_Type akbasic_leaf_identifier_type(akbasic_ASTLeaf *self)
+{
+    if ( self == NULL ) {
+	return AKBASIC_TYPE_UNDEFINED;
+    }
+    switch ( self->leaftype ) {
+    case AKBASIC_LEAF_IDENTIFIER_INT:
+	return AKBASIC_TYPE_INTEGER;
+    case AKBASIC_LEAF_IDENTIFIER_FLOAT:
+	return AKBASIC_TYPE_FLOAT;
+    case AKBASIC_LEAF_IDENTIFIER_STRING:
+	return AKBASIC_TYPE_STRING;
+    default:
+	/* A bare identifier is a label, and a label has no storage to fill. */
+	return AKBASIC_TYPE_UNDEFINED;
+    }
+}
+
 bool akbasic_leaf_is_literal(akbasic_ASTLeaf *self)
 {
     return (self != NULL &&

src/graphics_tables.c

@@ -82,6 +82,7 @@ akerr_ErrorContext *akbasic_graphics_state_init(akbasic_GraphicsState *obj)
     obj->x = 0.0;
     obj->y = 0.0;
     obj->scaling = false;
+    obj->linewidth = 1;
     obj->xmax = (double)AKBASIC_GRAPHICS_WIDTH;
     obj->ymax = (double)AKBASIC_GRAPHICS_HEIGHT;
     for ( source = 0; source < AKBASIC_COLOR_SOURCES; source++ ) {

src/main.c

@@ -100,8 +100,10 @@ static akerr_ErrorContext AKERR_NOIGNORE *drive(akbasic_Runtime *obj)
  * @brief The terminal driver: no window, no SDL, output on stdout.
  *
  * @param program The already-opened program file, or NULL for an interactive REPL.
+ * @param path That file's path, so a relative asset path a program writes can be resolved
+ *             against the program's own directory. NULL for an interactive REPL.
  */
-static akerr_ErrorContext AKERR_NOIGNORE *run_stdio(FILE *program)
+static akerr_ErrorContext AKERR_NOIGNORE *run_stdio(FILE *program, const char *path)
 {
     PREPARE_ERROR(errctx);
 
@@ -112,6 +114,13 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_stdio(FILE *program)
 	 */
 	PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, program));
 	PASS(errctx, akbasic_runtime_init(&RUNTIME, &SINK));
+	/*
+	 * So an asset path a program writes -- `SPRSAV "ship.png", 1` -- can be
+	 * tried against the program's own directory as well as against the
+	 * working one. Without it a `.bas` stored beside its art only works when
+	 * it is launched from its own directory.
+	 */
+	PASS(errctx, akbasic_runtime_set_source_path(&RUNTIME, path));
 	PASS(errctx, akbasic_runtime_start(&RUNTIME, AKBASIC_MODE_RUNSTREAM));
     } else {
 	PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, stdin));
@@ -140,8 +149,9 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_stdio(FILE *program)
  * @brief The SDL driver: an 800x600 window, and stdout still gets everything.
  *
  * @param program The already-opened program file, or NULL to type at the window.
+ * @param path That file's path; see run_stdio(). NULL when there is no program file.
  */
-static akerr_ErrorContext AKERR_NOIGNORE *run_akgl(FILE *program)
+static akerr_ErrorContext AKERR_NOIGNORE *run_akgl(FILE *program, const char *path)
 {
     PREPARE_ERROR(errctx);
     const char *fontpath = getenv("AKBASIC_FONT");
@@ -169,6 +179,8 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_akgl(FILE *program)
 					    fontpath, AKBASIC_FRONTEND_FONT_SIZE,
 					    stdout, input));
     PASS(errctx, akbasic_frontend_akgl_attach(&FRONTEND, &RUNTIME));
+    /* See the note in run_stdio(): this is what makes a relative asset path work. */
+    PASS(errctx, akbasic_runtime_set_source_path(&RUNTIME, path));
     PASS(errctx, akbasic_runtime_start(&RUNTIME, mode));
     PASS(errctx, akbasic_frontend_akgl_drive(&FRONTEND, &RUNTIME));
     SUCCEED_RETURN(errctx);
@@ -186,9 +198,9 @@ int main(int argc, char **argv)
 	    CATCH(errctx, aksl_fopen(argv[1], "r", &program));
 	}
 #ifdef AKBASIC_HAVE_AKGL
-	CATCH(errctx, run_akgl(program));
+	CATCH(errctx, run_akgl(program, (argc > 1 ? argv[1] : NULL)));
 #else
-	CATCH(errctx, run_stdio(program));
+	CATCH(errctx, run_stdio(program, (argc > 1 ? argv[1] : NULL)));
 #endif
     } CLEANUP {
 	if ( program != NULL ) {

src/parser.c

@@ -25,6 +25,7 @@ akerr_ErrorContext *akbasic_parser_init(akbasic_Parser *obj, akbasic_Runtime *ru
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL parser in init");
     FAIL_ZERO_RETURN(errctx, (runtime != NULL), AKERR_NULLPOINTER, "nil runtime argument");
     obj->runtime = runtime;
+    obj->comparing = false;
     SUCCEED_RETURN(errctx);
 }
 
@@ -362,21 +363,40 @@ static akerr_ErrorContext *logicalnot(akbasic_Parser *obj, akbasic_ASTLeaf **des
 akerr_ErrorContext *akbasic_parser_relation(akbasic_Parser *obj, akbasic_ASTLeaf **dest)
 {
     PREPARE_ERROR(errctx);
+    /*
+     * A lone `=` is an equality test here when the caller has said a condition
+     * is what it is parsing. `==` keeps working either way, which is what the Go
+     * reference used and what the whole checked-in corpus is written in. See
+     * akbasic_Parser::comparing and TODO.md section 5.
+     */
     static const akbasic_TokenType OPS[] = {
 	AKBASIC_TOK_LESS_THAN, AKBASIC_TOK_LESS_THAN_EQUAL, AKBASIC_TOK_EQUAL,
-	AKBASIC_TOK_NOT_EQUAL, AKBASIC_TOK_GREATER_THAN, AKBASIC_TOK_GREATER_THAN_EQUAL
+	AKBASIC_TOK_NOT_EQUAL, AKBASIC_TOK_GREATER_THAN, AKBASIC_TOK_GREATER_THAN_EQUAL,
+	AKBASIC_TOK_ASSIGNMENT
     };
     akbasic_ASTLeaf *left = NULL;
     akbasic_ASTLeaf *right = NULL;
     akbasic_ASTLeaf *expr = NULL;
     akbasic_Token *operator_ = NULL;
+    akbasic_TokenType op = AKBASIC_TOK_UNDEFINED;
+    /*
+     * ASSIGNMENT is the last entry, and it is only offered while `comparing` --
+     * see akbasic_Parser. Outside a condition `=` has to stay an assignment, or
+     * `A# = 2` stops storing anything and `FOR I# = 1 TO 5` never initializes
+     * its counter.
+     */
+    int opcount = (obj->comparing ? 7 : 6);
 
     PASS(errctx, subtraction(obj, &left));
-    if ( akbasic_parser_match(obj, OPS, 6) ) {
+    if ( akbasic_parser_match(obj, OPS, opcount) ) {
 	PASS(errctx, akbasic_parser_previous(obj, &operator_));
+	op = operator_->tokentype;
+	if ( op == AKBASIC_TOK_ASSIGNMENT ) {
+	    op = AKBASIC_TOK_EQUAL;
+	}
 	PASS(errctx, subtraction(obj, &right));
 	PASS(errctx, akbasic_parser_new_leaf(obj, &expr));
-	PASS(errctx, akbasic_leaf_new_binary(expr, left, operator_->tokentype, right));
+	PASS(errctx, akbasic_leaf_new_binary(expr, left, op, right));
 	*dest = expr;
 	SUCCEED_RETURN(errctx);
     }

src/parser_commands.c

@@ -38,6 +38,15 @@ akerr_ErrorContext *akbasic_parse_arglist(akbasic_Parser *parser, akbasic_ASTLea
      * column to carry one.
      */
     PASS(errctx, akbasic_parser_previous(parser, &operator_));
+    /*
+     * Checked before parsing rather than after. Handing an empty token stream to
+     * the expression parser fails deep inside it with "peek() returned nil
+     * token!", which tells a program author nothing at all -- and this path is
+     * reached by every verb that takes a list, so the bad message was the one
+     * most people saw.
+     */
+    FAIL_ZERO_RETURN(errctx, (akbasic_parser_peek(parser) != NULL), AKBASIC_ERR_SYNTAX,
+		     "%s expected at least one argument", operator_->lexeme);
     PASS(errctx, akbasic_parser_argument_list(parser, AKBASIC_TOK_FUNCTION_ARGUMENT, false, &arglist));
     FAIL_ZERO_RETURN(errctx, (arglist != NULL), AKBASIC_ERR_SYNTAX,
 		     "%s expected at least one argument", operator_->lexeme);
@@ -100,6 +109,413 @@ akerr_ErrorContext *akbasic_parse_draw(akbasic_Parser *parser, akbasic_ASTLeaf *
     SUCCEED_RETURN(errctx);
 }
 
+akerr_ErrorContext *akbasic_parse_movspr(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arglist = NULL;
+    akbasic_ASTLeaf *form = NULL;
+    akbasic_ASTLeaf *expr = NULL;
+    akbasic_ASTLeaf *tail = NULL;
+    akbasic_Token *operator_ = NULL;
+    akbasic_Token *peeked = NULL;
+    const char *formlexeme = "0";
+
+    /*
+     * MOVSPR is the one verb in the language whose arguments are not simply
+     * comma-separated. It has four forms and the separators are what tell them
+     * apart:
+     *
+     *     MOVSPR n, x, y      absolute
+     *     MOVSPR n, +x, -y    relative -- a signed coordinate, not a negative one
+     *     MOVSPR n, d ; a     polar: distance, then angle
+     *     MOVSPR n, a # s     continuous: angle, then speed
+     *
+     * So the form has to be decided here, where the tokens still exist, and
+     * carried to the exec handler somehow. It is carried as a synthetic integer
+     * literal prepended to the argument list, which flattens the whole statement
+     * to `form, n, a, b` -- the same trick akbasic_parse_draw uses to make a
+     * polyline look like a plain argument chain.
+     */
+    PASS(errctx, akbasic_parser_previous(parser, &operator_));
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &arglist));
+    arglist->leaftype = AKBASIC_LEAF_ARGUMENTLIST;
+    arglist->operator_ = AKBASIC_TOK_FUNCTION_ARGUMENT;
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &form));
+    PASS(errctx, akbasic_parser_expression(parser, &arglist->right));
+    FAIL_ZERO_RETURN(errctx, (arglist->right != NULL), AKBASIC_ERR_SYNTAX,
+		     "MOVSPR expected a sprite number");
+    tail = arglist->right;
+
+    FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMA),
+		     AKBASIC_ERR_SYNTAX, "MOVSPR expected a comma after the sprite number");
+
+    /*
+     * A leading sign makes it relative. `+` has to be consumed here because the
+     * expression parser has no unary plus; `-` is left where it is, because
+     * unary minus is a real operator and re-parsing it would drop the sign.
+     */
+    peeked = akbasic_parser_peek(parser);
+    if ( peeked != NULL &&
+	 (peeked->tokentype == AKBASIC_TOK_PLUS || peeked->tokentype == AKBASIC_TOK_MINUS) ) {
+	formlexeme = "1";
+	if ( peeked->tokentype == AKBASIC_TOK_PLUS ) {
+	    (void)akbasic_parser_match1(parser, AKBASIC_TOK_PLUS);
+	}
+    }
+
+    PASS(errctx, akbasic_parser_expression(parser, &tail->next));
+    FAIL_ZERO_RETURN(errctx, (tail->next != NULL), AKBASIC_ERR_SYNTAX,
+		     "MOVSPR expected a coordinate, a distance or an angle");
+    tail = tail->next;
+
+    if ( akbasic_parser_match1(parser, AKBASIC_TOK_SEMICOLON) ) {
+	formlexeme = "2";
+    } else if ( akbasic_parser_match1(parser, AKBASIC_TOK_HASHMARK) ) {
+	formlexeme = "3";
+    } else {
+	FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMA),
+			 AKBASIC_ERR_SYNTAX,
+			 "MOVSPR expected `, y', `; angle' or `# speed'");
+	if ( formlexeme[0] == '0' ) {
+	    peeked = akbasic_parser_peek(parser);
+	    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_PLUS ) {
+		formlexeme = "1";
+		(void)akbasic_parser_match1(parser, AKBASIC_TOK_PLUS);
+	    } else if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_MINUS ) {
+		formlexeme = "1";
+	    }
+	} else if ( akbasic_parser_peek(parser) != NULL &&
+		    akbasic_parser_peek(parser)->tokentype == AKBASIC_TOK_PLUS ) {
+	    (void)akbasic_parser_match1(parser, AKBASIC_TOK_PLUS);
+	}
+    }
+
+    PASS(errctx, akbasic_parser_expression(parser, &tail->next));
+    FAIL_ZERO_RETURN(errctx, (tail->next != NULL), AKBASIC_ERR_SYNTAX,
+		     "MOVSPR expected a second value");
+
+    PASS(errctx, akbasic_leaf_new_literal_int(form, formlexeme));
+    form->next = arglist->right;
+    arglist->right = form;
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+    PASS(errctx, akbasic_leaf_new_command(expr, operator_->lexeme, arglist));
+    *dest = expr;
+    SUCCEED_RETURN(errctx);
+}
+
+
+/**
+ * @brief Read an optional `WHILE`/`UNTIL` condition off a DO or a LOOP.
+ *
+ * Both ends of a DO/LOOP take the same optional clause, so both parse it the
+ * same way. @p kind comes back as one of the AKBASIC_LOOPCOND_* values and
+ * @p condition is NULL when there was no clause.
+ */
+static akerr_ErrorContext *parse_loop_condition(akbasic_Parser *parser, akbasic_ASTLeaf **condition, int *kind)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Token *peeked = NULL;
+
+    *condition = NULL;
+    *kind = AKBASIC_LOOPCOND_NONE;
+
+    peeked = akbasic_parser_peek(parser);
+    if ( peeked == NULL || peeked->tokentype != AKBASIC_TOK_COMMAND ) {
+	SUCCEED_RETURN(errctx);
+    }
+    if ( strcmp(peeked->lexeme, "WHILE") == 0 ) {
+	*kind = AKBASIC_LOOPCOND_WHILE;
+    } else if ( strcmp(peeked->lexeme, "UNTIL") == 0 ) {
+	*kind = AKBASIC_LOOPCOND_UNTIL;
+    } else {
+	SUCCEED_RETURN(errctx);
+    }
+    (void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
+
+    /* A loop condition is a condition, so a lone `=` in it is an equality test. */
+    parser->comparing = true;
+    PASS(errctx, akbasic_parser_expression(parser, condition));
+    parser->comparing = false;
+    FAIL_ZERO_RETURN(errctx, (*condition != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected a condition after WHILE or UNTIL");
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * DO [WHILE|UNTIL (condition)]
+ *
+ * Pushes the loop's scope at parse time, exactly as FOR does and for the same
+ * reason: the condition leaf has to outlive the line it was written on, and an
+ * environment's leaf pool is what gives it somewhere to live.
+ */
+akerr_ErrorContext *akbasic_parse_do(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Runtime *runtime = parser->runtime;
+    akbasic_Environment *parent = runtime->environment;
+    akbasic_Environment *newenv = NULL;
+    akbasic_ASTLeaf *expr = NULL;
+    akbasic_ASTLeaf *condition = NULL;
+    int kind = AKBASIC_LOOPCOND_NONE;
+    int64_t firstline = parent->lineno + 1;
+
+    PASS(errctx, akbasic_runtime_new_environment(runtime));
+    newenv = runtime->environment;
+    runtime->environment = parent;
+
+    /*
+     * Parsed against the parent's token stream but stored in the new scope --
+     * the body is scanned line by line afterwards, and the new scope must not be
+     * active until parsing is done.
+     */
+    PASS(errctx, parse_loop_condition(parser, &condition, &kind));
+
+    newenv->isDoLoop = true;
+    newenv->loopFirstLine = firstline;
+    newenv->doConditionKind = kind;
+    if ( condition != NULL ) {
+	PASS(errctx, akbasic_leaf_clone(condition, &newenv->doLeafPool, &newenv->doConditionLeaf));
+    }
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+    PASS(errctx, akbasic_leaf_new_command(expr, "DO", NULL));
+
+    runtime->environment = newenv;
+    *dest = expr;
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * LOOP [WHILE|UNTIL (condition)]
+ *
+ * The condition hangs off the command leaf's `.right`, with the WHILE/UNTIL
+ * choice in that leaf's integer literal and the expression on its `.left`. No
+ * cloning: this line is still scanned when the verb runs.
+ */
+akerr_ErrorContext *akbasic_parse_loop(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *expr = NULL;
+    akbasic_ASTLeaf *holder = NULL;
+    akbasic_ASTLeaf *condition = NULL;
+    int kind = AKBASIC_LOOPCOND_NONE;
+
+    PASS(errctx, parse_loop_condition(parser, &condition, &kind));
+    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+    if ( condition != NULL ) {
+	PASS(errctx, akbasic_parser_new_leaf(parser, &holder));
+	PASS(errctx, akbasic_leaf_init(holder, AKBASIC_LEAF_LITERAL_INT));
+	holder->literal_int = kind;
+	holder->left = condition;
+    }
+    PASS(errctx, akbasic_leaf_new_command(expr, "LOOP", holder));
+    *dest = expr;
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * ON (expression) GOTO|GOSUB (target) [, ...]
+ *
+ * Flattened to one argument chain: a marker carrying the GOSUB flag, the
+ * selector expression, then the targets. Same trick akbasic_parse_draw and
+ * akbasic_parse_movspr use, so the exec handler walks a plain list.
+ */
+akerr_ErrorContext *akbasic_parse_on(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arglist = NULL;
+    akbasic_ASTLeaf *marker = NULL;
+    akbasic_ASTLeaf *expr = NULL;
+    akbasic_ASTLeaf *tail = NULL;
+    akbasic_Token *operator_ = NULL;
+    bool gosub = false;
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &arglist));
+    arglist->leaftype = AKBASIC_LEAF_ARGUMENTLIST;
+    arglist->operator_ = AKBASIC_TOK_FUNCTION_ARGUMENT;
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &marker));
+    PASS(errctx, akbasic_leaf_init(marker, AKBASIC_LEAF_LITERAL_INT));
+
+    PASS(errctx, akbasic_parser_expression(parser, &marker->next));
+    FAIL_ZERO_RETURN(errctx, (marker->next != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected ON (expression) GOTO|GOSUB (line) [, ...]");
+    tail = marker->next;
+
+    FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
+		     AKBASIC_ERR_SYNTAX, "Expected GOTO or GOSUB after ON (expression)");
+    PASS(errctx, akbasic_parser_previous(parser, &operator_));
+    if ( strcmp(operator_->lexeme, "GOSUB") == 0 ) {
+	gosub = true;
+    } else {
+	FAIL_NONZERO_RETURN(errctx, strcmp(operator_->lexeme, "GOTO"), AKBASIC_ERR_SYNTAX,
+			    "Expected GOTO or GOSUB after ON (expression)");
+    }
+    marker->literal_int = (gosub ? 1 : 0);
+
+    for ( ;; ) {
+	PASS(errctx, akbasic_parser_expression(parser, &tail->next));
+	FAIL_ZERO_RETURN(errctx, (tail->next != NULL), AKBASIC_ERR_SYNTAX,
+			 "Expected a line number or label after ON ... %s",
+			 (gosub ? "GOSUB" : "GOTO"));
+	tail = tail->next;
+	if ( !akbasic_parser_match1(parser, AKBASIC_TOK_COMMA) ) {
+	    break;
+	}
+    }
+
+    arglist->right = marker;
+    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+    PASS(errctx, akbasic_leaf_new_command(expr, "ON", arglist));
+    *dest = expr;
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * RESUME [NEXT | (line)]
+ *
+ * `NEXT` is a COMMAND token, so the default command path -- which parses the
+ * rval as an expression -- cannot read it: `RESUME NEXT` came back as "Expected
+ * expression or literal". The word is kept as the command leaf's rval so the
+ * exec handler can tell the three forms apart by looking at it.
+ */
+akerr_ErrorContext *akbasic_parse_resume(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *expr = NULL;
+    akbasic_ASTLeaf *target = NULL;
+    akbasic_Token *peeked = NULL;
+
+    peeked = akbasic_parser_peek(parser);
+    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND &&
+	 strcmp(peeked->lexeme, "NEXT") == 0 ) {
+	(void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
+	PASS(errctx, akbasic_parser_new_leaf(parser, &target));
+	PASS(errctx, akbasic_leaf_new_command(target, "NEXT", NULL));
+    } else if ( peeked != NULL && peeked->tokentype != AKBASIC_TOK_COLON ) {
+	PASS(errctx, akbasic_parser_expression(parser, &target));
+    }
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+    PASS(errctx, akbasic_leaf_new_command(expr, "RESUME", target));
+    *dest = expr;
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * PRINT [USING (format);] (expression)
+ *
+ * Only the USING form needs a parse handler; without it PRINT keeps the default
+ * path, which parses one expression. `USING` is a COMMAND token, so the default
+ * path could not read it -- the same reason RESUME needed one for `NEXT`.
+ *
+ * The result is a command leaf whose rval is an argument list of exactly two:
+ * the format and the value. A plain PRINT keeps its single-expression rval, so
+ * the exec handler tells them apart by looking for the list.
+ */
+akerr_ErrorContext *akbasic_parse_print(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *expr = NULL;
+    akbasic_ASTLeaf *arglist = NULL;
+    akbasic_ASTLeaf *right = NULL;
+    akbasic_Token *peeked = NULL;
+
+    peeked = akbasic_parser_peek(parser);
+
+    /*
+     * `PRINT #1, expr` writes to a file channel. A C128 spells it `PRINT#1` with
+     * no space, which this scanner cannot produce: `PRINT#` reads as an
+     * identifier with an integer suffix, and a verb name carrying a suffix is
+     * refused (deviation 30). So the `#` is its own token and the space before
+     * it is required. Recorded in TODO.md section 5.
+     *
+     * The channel form is marked by a leaf named "PRINT#" holding an argument
+     * list of two: the channel and the value.
+     */
+    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_HASHMARK ) {
+	akbasic_ASTLeaf *arglist = NULL;
+
+	(void)akbasic_parser_match1(parser, AKBASIC_TOK_HASHMARK);
+	PASS(errctx, akbasic_parser_new_leaf(parser, &arglist));
+	arglist->leaftype = AKBASIC_LEAF_ARGUMENTLIST;
+	arglist->operator_ = AKBASIC_TOK_FUNCTION_ARGUMENT;
+	PASS(errctx, akbasic_parser_expression(parser, &arglist->right));
+	FAIL_ZERO_RETURN(errctx, (arglist->right != NULL), AKBASIC_ERR_SYNTAX,
+			 "Expected PRINT #(channel), (expression)");
+	FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMA),
+			 AKBASIC_ERR_SYNTAX,
+			 "Expected a comma after PRINT #(channel)");
+	PASS(errctx, akbasic_parser_expression(parser, &arglist->right->next));
+	FAIL_ZERO_RETURN(errctx, (arglist->right->next != NULL), AKBASIC_ERR_SYNTAX,
+			 "Expected PRINT #(channel), (expression)");
+	PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+	PASS(errctx, akbasic_leaf_new_command(expr, "PRINT#", arglist));
+	*dest = expr;
+	SUCCEED_RETURN(errctx);
+    }
+
+    if ( peeked == NULL || peeked->tokentype != AKBASIC_TOK_COMMAND ||
+	 strcmp(peeked->lexeme, "USING") != 0 ) {
+	/* The ordinary PRINT: one expression, or none at all. */
+	if ( peeked != NULL && peeked->tokentype != AKBASIC_TOK_COLON ) {
+	    PASS(errctx, akbasic_parser_expression(parser, &right));
+	}
+	PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+	PASS(errctx, akbasic_leaf_new_command(expr, "PRINT", right));
+	*dest = expr;
+	SUCCEED_RETURN(errctx);
+    }
+    (void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &arglist));
+    arglist->leaftype = AKBASIC_LEAF_ARGUMENTLIST;
+    arglist->operator_ = AKBASIC_TOK_FUNCTION_ARGUMENT;
+
+    PASS(errctx, akbasic_parser_expression(parser, &arglist->right));
+    FAIL_ZERO_RETURN(errctx, (arglist->right != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected PRINT USING (format); (expression)");
+    FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_SEMICOLON),
+		     AKBASIC_ERR_SYNTAX,
+		     "Expected a semicolon between PRINT USING's format and its value");
+    PASS(errctx, akbasic_parser_expression(parser, &arglist->right->next));
+    FAIL_ZERO_RETURN(errctx, (arglist->right->next != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected PRINT USING (format); (expression)");
+
+    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+    PASS(errctx, akbasic_leaf_new_command(expr, "PRINT", arglist));
+    *dest = expr;
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * The argument list, for verbs that may be written with no arguments at all --
+ * bare `KEY` lists the macros, bare `RENUMBER` renumbers with its defaults.
+ * `akbasic_parse_arglist` insists on at least one argument, which is right for
+ * every other verb that uses it.
+ */
+akerr_ErrorContext *akbasic_parse_optional_arglist(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *expr = NULL;
+    akbasic_Token *operator_ = NULL;
+    akbasic_Token *peeked = NULL;
+
+    peeked = akbasic_parser_peek(parser);
+    if ( peeked != NULL && peeked->tokentype != AKBASIC_TOK_COLON ) {
+	PASS(errctx, akbasic_parse_arglist(parser, dest));
+	SUCCEED_RETURN(errctx);
+    }
+    PASS(errctx, akbasic_parser_previous(parser, &operator_));
+    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
+    PASS(errctx, akbasic_leaf_new_command(expr, operator_->lexeme, NULL));
+    *dest = expr;
+    SUCCEED_RETURN(errctx);
+}
+
 akerr_ErrorContext *akbasic_parse_let(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
 {
     PREPARE_ERROR(errctx);
@@ -388,7 +804,21 @@ akerr_ErrorContext *akbasic_parse_if(akbasic_Parser *parser, akbasic_ASTLeaf **d
     akbasic_ASTLeaf *branch = NULL;
     akbasic_Token *operator_ = NULL;
 
-    PASS(errctx, akbasic_parser_relation(parser, &relation));
+    /*
+     * Everything from here to the THEN is a condition, so a lone `=` in it is an
+     * equality test. Cleared immediately afterwards: the statement the THEN arm
+     * holds may well be an assignment.
+     */
+    /*
+     * The whole expression, not just a relation. The reference parses one
+     * relation here, which is below AND and OR in the grammar chain -- so
+     * `IF A# = 5 AND B# = 3 THEN` stopped after the first comparison, left the
+     * AND unconsumed, and reported "Incomplete IF statement" against a line that
+     * is ordinary BASIC. A condition is an expression.
+     */
+    parser->comparing = true;
+    PASS(errctx, akbasic_parser_expression(parser, &relation));
+    parser->comparing = false;
     FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
 		     AKBASIC_ERR_SYNTAX, "Incomplete IF statement");
     PASS(errctx, akbasic_parser_previous(parser, &operator_));
@@ -423,6 +853,34 @@ akerr_ErrorContext *akbasic_parse_input(akbasic_Parser *parser, akbasic_ASTLeaf
     akbasic_ASTLeaf *promptexpr = NULL;
     akbasic_ASTLeaf *identifier = NULL;
     akbasic_ASTLeaf *command = NULL;
+    akbasic_Token *peeked = NULL;
+
+    /*
+     * `INPUT #1, VAR` reads a line from a file channel rather than from the
+     * sink. Same spelling note as PRINT: the `#` is its own token and the space
+     * before it is required.
+     */
+    peeked = akbasic_parser_peek(parser);
+    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_HASHMARK ) {
+	akbasic_ASTLeaf *arglist = NULL;
+
+	(void)akbasic_parser_match1(parser, AKBASIC_TOK_HASHMARK);
+	PASS(errctx, akbasic_parser_new_leaf(parser, &arglist));
+	arglist->leaftype = AKBASIC_LEAF_ARGUMENTLIST;
+	arglist->operator_ = AKBASIC_TOK_FUNCTION_ARGUMENT;
+	PASS(errctx, akbasic_parser_expression(parser, &arglist->right));
+	FAIL_ZERO_RETURN(errctx, (arglist->right != NULL), AKBASIC_ERR_SYNTAX,
+			 "Expected INPUT #(channel), (variable)");
+	FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMA),
+			 AKBASIC_ERR_SYNTAX, "Expected a comma after INPUT #(channel)");
+	PASS(errctx, akbasic_parser_primary(parser, &arglist->right->next));
+	FAIL_ZERO_RETURN(errctx, akbasic_leaf_is_identifier(arglist->right->next),
+			 AKBASIC_ERR_SYNTAX, "Expected INPUT #(channel), (variable)");
+	PASS(errctx, akbasic_parser_new_leaf(parser, &command));
+	PASS(errctx, akbasic_leaf_new_command(command, "INPUT#", arglist));
+	*dest = command;
+	SUCCEED_RETURN(errctx);
+    }
 
     PASS(errctx, akbasic_parser_expression(parser, &promptexpr));
     PASS(errctx, akbasic_parser_primary(parser, &identifier));

src/renumber.c

@@ -0,0 +1,315 @@
+/**
+ * @file renumber.c
+ * @brief RENUMBER: move every line, and rewrite every reference to one.
+ *
+ * Moving the lines is easy -- source is filed under its line number in
+ * `source[]`, so it is a permutation. Rewriting every `GOTO`, `GOSUB`, `RUN`,
+ * `RESTORE`, `TRAP` and `COLLISION` target to match is the job, and it is why
+ * this was deferred rather than written early: a `RENUMBER` that moved lines
+ * without fixing their references would silently break every branch in the
+ * program, which is worse than not having the verb at all.
+ *
+ * The rewrite is textual, and the only thing it has to understand about the rest
+ * of the language is where a string literal starts and stops -- `PRINT "GOTO 10"`
+ * must come through untouched. That is the same statement-walking the label and
+ * DATA prescans do.
+ */
+
+#include <ctype.h>
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+
+#include <akerror.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+/**
+ * @brief Verbs whose numeric arguments name a line.
+ *
+ * `THEN` and `ELSE` are deliberately absent. Commodore BASIC lets `IF X THEN 100`
+ * stand for `THEN GOTO 100`; this dialect does not -- the corpus writes
+ * `THEN GOTO 100` -- so a number after `THEN` here is an expression, not a target.
+ *
+ * `LIST` and `DELETE` are absent too, and for a different reason: their
+ * arguments are ranges typed at a prompt, not references stored in a program.
+ * Renumbering a `DELETE` inside a listing would be rewriting something nobody
+ * meant as a branch.
+ */
+static const char *BRANCH_VERBS[] = { "GOTO", "GOSUB", "RUN", "RESTORE", "TRAP" };
+/** @brief How many entries #BRANCH_VERBS has. */
+#define BRANCH_VERB_COUNT ((int)(sizeof(BRANCH_VERBS) / sizeof(BRANCH_VERBS[0])))
+
+/**
+ * @brief Where a line moved to, or the line itself when it did not move.
+ *
+ * A target naming a line that does not exist is left alone rather than
+ * rewritten: `GOTO 9999` in a program with no line 9999 is already broken, and
+ * inventing a destination for it would hide that.
+ */
+static int64_t mapped(const int64_t *map, int64_t line)
+{
+    if ( line < 0 || line >= AKBASIC_MAX_SOURCE_LINES ) {
+	return line;
+    }
+    return (map[line] >= 0 ? map[line] : line);
+}
+
+/**
+ * @brief Copy a run of comma-separated line numbers, rewriting each.
+ *
+ * `ON X GOTO 100, 200, 300` is why this takes a list rather than one number: the
+ * targets follow the `GOTO`, so handling `GOTO` handles `ON` for free.
+ *
+ * @param map Old line to new line.
+ * @param src Reads from here; advanced past what was consumed.
+ * @param dest Writes to here; advanced past what was written.
+ * @param limit One past the last byte @p dest may write.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKBASIC_ERR_BOUNDS When the rewritten line does not fit.
+ */
+static akerr_ErrorContext *rewrite_targets(const int64_t *map, const char **src, char **dest, const char *limit)
+{
+    PREPARE_ERROR(errctx);
+    const char *p = *src;
+    char *out = *dest;
+
+    for ( ;; ) {
+	int64_t line = 0;
+	int written = 0;
+
+	while ( *p == ' ' || *p == '\t' ) {
+	    FAIL_ZERO_RETURN(errctx, (out < limit), AKBASIC_ERR_BOUNDS,
+			     "RENUMBER: a rewritten line does not fit");
+	    *out = *p;
+	    out += 1;
+	    p += 1;
+	}
+	if ( !isdigit((unsigned char)*p) ) {
+	    /*
+	     * Not a number: a label, an expression, or nothing at all. Labels are
+	     * the reason RENUMBER is survivable in the first place -- a program
+	     * written with `GOTO DONE` needs no rewriting and cannot be broken by
+	     * one.
+	     */
+	    break;
+	}
+	while ( isdigit((unsigned char)*p) ) {
+	    line = (line * 10) + (*p - '0');
+	    p += 1;
+	}
+	written = snprintf(out, (size_t)(limit - out), "%" PRId64, mapped(map, line));
+	FAIL_ZERO_RETURN(errctx, (written > 0 && out + written < limit), AKBASIC_ERR_BOUNDS,
+			 "RENUMBER: a rewritten line does not fit");
+	out += written;
+
+	/*
+	 * A comma continues the list; anything else ends it. The spaces are
+	 * skipped to find out which, and put back if the answer is "ends" --
+	 * without that, `THEN GOTO 9 ELSE ...` came back as `THEN GOTO 30ELSE`.
+	 */
+	{
+	    const char *afterdigits = p;
+
+	    while ( *p == ' ' || *p == '\t' ) {
+		p += 1;
+	    }
+	    if ( *p != ',' ) {
+		p = afterdigits;
+		break;
+	    }
+	}
+	FAIL_ZERO_RETURN(errctx, (out < limit), AKBASIC_ERR_BOUNDS,
+			 "RENUMBER: a rewritten line does not fit");
+	*out = ',';
+	out += 1;
+	p += 1;
+    }
+    *src = p;
+    *dest = out;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Rewrite every branch target in one line of source.
+ *
+ * @param map Old line to new line.
+ * @param code The line to read.
+ * @param dest Where the rewritten line goes.
+ * @param len Capacity of @p dest.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKBASIC_ERR_BOUNDS When the rewritten line does not fit.
+ */
+static akerr_ErrorContext *rewrite_line(const int64_t *map, const char *code, char *dest, size_t len)
+{
+    PREPARE_ERROR(errctx);
+    const char *p = code;
+    char *out = dest;
+    const char *limit = dest + len - 1;
+    bool statementstart = true;
+    bool instring = false;
+    int i = 0;
+
+    while ( *p != '\0' ) {
+	size_t verblen = 0;
+	bool matched = false;
+
+	FAIL_ZERO_RETURN(errctx, (out < limit), AKBASIC_ERR_BOUNDS,
+			 "RENUMBER: a rewritten line does not fit");
+	if ( instring ) {
+	    instring = (*p != '"');
+	    *out = *p;
+	    out += 1;
+	    p += 1;
+	    continue;
+	}
+	if ( *p == '"' ) {
+	    /* A string literal is copied through untouched: `PRINT "GOTO 10"`. */
+	    instring = true;
+	    statementstart = false;
+	    *out = *p;
+	    out += 1;
+	    p += 1;
+	    continue;
+	}
+	if ( *p == ':' ) {
+	    statementstart = true;
+	    *out = *p;
+	    out += 1;
+	    p += 1;
+	    continue;
+	}
+	if ( *p == ' ' || *p == '\t' ) {
+	    *out = *p;
+	    out += 1;
+	    p += 1;
+	    continue;
+	}
+
+	for ( i = 0; i < BRANCH_VERB_COUNT; i++ ) {
+	    verblen = strlen(BRANCH_VERBS[i]);
+	    if ( strncasecmp(p, BRANCH_VERBS[i], verblen) == 0 &&
+		 !isalnum((unsigned char)p[verblen]) ) {
+		matched = true;
+		break;
+	    }
+	}
+	/*
+	 * A branch verb may appear anywhere a statement may, and `GOTO` also
+	 * follows `THEN`, `ELSE` and `ON X` -- none of which is a statement
+	 * start. So the match is not gated on statementstart; what protects
+	 * `A$ = "GOTO"` is the string check above, and what protects a variable
+	 * called `GOTOX#` is the alphanumeric check here.
+	 */
+	if ( matched ) {
+	    FAIL_ZERO_RETURN(errctx, (out + verblen < (size_t)(limit - dest) + dest),
+			     AKBASIC_ERR_BOUNDS, "RENUMBER: a rewritten line does not fit");
+	    memcpy(out, p, verblen);
+	    out += verblen;
+	    p += verblen;
+	    PASS(errctx, rewrite_targets(map, &p, &out, limit));
+	    statementstart = false;
+	    continue;
+	}
+
+	/*
+	 * COLLISION's handler is its *second* argument, so the list rewrite
+	 * cannot be pointed at it directly. Copy the type and the comma, then
+	 * rewrite what follows.
+	 */
+	if ( strncasecmp(p, "COLLISION", 9) == 0 && !isalnum((unsigned char)p[9]) ) {
+	    memcpy(out, p, 9);
+	    out += 9;
+	    p += 9;
+	    while ( *p != '\0' && *p != ',' && *p != ':' ) {
+		FAIL_ZERO_RETURN(errctx, (out < limit), AKBASIC_ERR_BOUNDS,
+				 "RENUMBER: a rewritten line does not fit");
+		*out = *p;
+		out += 1;
+		p += 1;
+	    }
+	    if ( *p == ',' ) {
+		*out = ',';
+		out += 1;
+		p += 1;
+		PASS(errctx, rewrite_targets(map, &p, &out, limit));
+	    }
+	    statementstart = false;
+	    continue;
+	}
+
+	statementstart = false;
+	*out = *p;
+	out += 1;
+	p += 1;
+    }
+    *out = '\0';
+    (void)statementstart;
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_renumber(akbasic_Runtime *obj, int64_t newstart, int64_t increment, int64_t oldstart)
+{
+    PREPARE_ERROR(errctx);
+    static int64_t map[AKBASIC_MAX_SOURCE_LINES];
+    static akbasic_SourceLine rewritten[AKBASIC_MAX_SOURCE_LINES];
+    int64_t next = newstart;
+    int64_t i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in renumber");
+    FAIL_ZERO_RETURN(errctx, (increment > 0), AKBASIC_ERR_VALUE,
+		     "RENUMBER's increment must be positive, not %" PRId64, increment);
+    FAIL_ZERO_RETURN(errctx, (newstart > 0), AKBASIC_ERR_VALUE,
+		     "RENUMBER cannot start at line %" PRId64, newstart);
+
+    for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
+	map[i] = -1;
+    }
+
+    /*
+     * Build the whole map before touching anything. A rewrite needs to know
+     * where *every* line ended up, including ones it has not reached yet --
+     * a backward `GOTO` is as common as a forward one.
+     */
+    for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
+	if ( obj->source[i].code[0] == '\0' || i < oldstart ) {
+	    continue;
+	}
+	FAIL_ZERO_RETURN(errctx, (next < AKBASIC_MAX_SOURCE_LINES), AKBASIC_ERR_BOUNDS,
+			 "RENUMBER: line %" PRId64 " would become %" PRId64 ", past the %d line limit",
+			 i, next, AKBASIC_MAX_SOURCE_LINES - 1);
+	/*
+	 * A renumbered line must not land on a kept one. Refused rather than
+	 * overwritten: losing a line to a renumbering is not recoverable.
+	 */
+	FAIL_ZERO_RETURN(errctx, (next >= oldstart || obj->source[next].code[0] == '\0'),
+			 AKBASIC_ERR_VALUE,
+			 "RENUMBER: line %" PRId64 " would become %" PRId64 ", which already exists",
+			 i, next);
+	map[i] = next;
+	next += increment;
+    }
+
+    memset(rewritten, 0, sizeof(rewritten));
+    for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
+	int64_t target = 0;
+
+	if ( obj->source[i].code[0] == '\0' ) {
+	    continue;
+	}
+	/*
+	 * Every line is rewritten, not just the moved ones: a line before
+	 * `oldstart` can branch into the region that moved.
+	 */
+	target = mapped(map, i);
+	PASS(errctx, rewrite_line(map, obj->source[i].code,
+				  rewritten[target].code, sizeof(rewritten[target].code)));
+	rewritten[target].lineno = target;
+    }
+
+    memcpy(obj->source, rewritten, sizeof(obj->source));
+    SUCCEED_RETURN(errctx);
+}

src/runtime.c

@@ -3,9 +3,11 @@
  * @brief Implements the interpreter core: pools, evaluation and the step loop.
  */
 
+#include <ctype.h>
 #include <inttypes.h>
 #include <stdio.h>
 #include <string.h>
+#include <strings.h>
 
 #include <akerror.h>
 
@@ -164,6 +166,11 @@ akerr_ErrorContext *akbasic_runtime_init(akbasic_Runtime *obj, akbasic_TextSink
     obj->inputEof = false;
 
     PASS(errctx, akbasic_graphics_state_init(&obj->gfx));
+    PASS(errctx, akbasic_sprite_state_init(&obj->sprite_state));
+    PASS(errctx, akbasic_format_state_init(&obj->format_state));
+    PASS(errctx, akbasic_console_state_init(&obj->console_state));
+    PASS(errctx, akbasic_data_state_init(&obj->data_state));
+    PASS(errctx, akbasic_disk_state_init(&obj->disk_state));
     PASS(errctx, akbasic_audio_state_init(&obj->audio_state));
     PASS(errctx, akbasic_valuepool_init(&obj->valuepool));
     PASS(errctx, akbasic_value_zero(&obj->staticTrueValue));
@@ -177,7 +184,7 @@ akerr_ErrorContext *akbasic_runtime_init(akbasic_Runtime *obj, akbasic_TextSink
     SUCCEED_RETURN(errctx);
 }
 
-akerr_ErrorContext *akbasic_runtime_set_devices(akbasic_Runtime *obj, akbasic_GraphicsBackend *graphics, akbasic_AudioBackend *audio, akbasic_InputBackend *input)
+akerr_ErrorContext *akbasic_runtime_set_devices(akbasic_Runtime *obj, akbasic_GraphicsBackend *graphics, akbasic_AudioBackend *audio, akbasic_InputBackend *input, akbasic_SpriteBackend *sprites)
 {
     PREPARE_ERROR(errctx);
 
@@ -193,6 +200,39 @@ akerr_ErrorContext *akbasic_runtime_set_devices(akbasic_Runtime *obj, akbasic_Gr
     obj->graphics = graphics;
     obj->audio = audio;
     obj->input = input;
+    obj->sprites = sprites;
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_runtime_set_source_path(akbasic_Runtime *obj, const char *path)
+{
+    PREPARE_ERROR(errctx);
+    const char *slash = NULL;
+    size_t length = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in set_source_path");
+    obj->sourcepath[0] = '\0';
+    if ( path == NULL || path[0] == '\0' ) {
+	SUCCEED_RETURN(errctx);
+    }
+    /*
+     * The directory, taken here rather than at the point of use. dirname(3)
+     * would do it but it is allowed to modify its argument and two of the three
+     * libcs this has to build on disagree about which one they implement.
+     */
+    slash = strrchr(path, '/');
+    length = (slash == NULL ? 0 : (size_t)(slash - path));
+    if ( length == 0 ) {
+	/* Either no directory at all, or the root. */
+	strncpy(obj->sourcepath, (slash == NULL ? "." : "/"), sizeof(obj->sourcepath) - 1);
+	obj->sourcepath[sizeof(obj->sourcepath) - 1] = '\0';
+	SUCCEED_RETURN(errctx);
+    }
+    FAIL_ZERO_RETURN(errctx, (length < sizeof(obj->sourcepath)), AKBASIC_ERR_BOUNDS,
+		     "Program path of %zu characters exceeds the %d character limit",
+		     length, AKBASIC_MAX_LINE_LENGTH - 1);
+    memcpy(obj->sourcepath, path, length);
+    obj->sourcepath[length] = '\0';
     SUCCEED_RETURN(errctx);
 }
 
@@ -252,6 +292,27 @@ akerr_ErrorContext *akbasic_runtime_error(akbasic_Runtime *obj, akbasic_ErrorCla
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && message != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in runtime error");
+
+    /*
+     * TRAP intercepts here, because this is the one place a BASIC-visible error
+     * is reported and the one place the run is stopped. An armed trap turns both
+     * off: nothing is printed, `errclass` stays clear so the step loop keeps
+     * going, and the handler is entered at the next line boundary by the same
+     * machinery COLLISION uses.
+     *
+     * Not while a handler is already running. An error inside an error handler
+     * is reported and stops the program, which is the only way out of a handler
+     * that is itself broken -- a C128 does the same.
+     */
+    if ( obj->interrupts[AKBASIC_INTERRUPT_ERROR].armed && obj->handlerenv == NULL ) {
+	PASS(errctx, akbasic_trap_set_error_variables(obj, obj->lasterrorstatus,
+						      obj->environment->lineno));
+	PASS(errctx, akbasic_runtime_raise_interrupt(obj, AKBASIC_INTERRUPT_ERROR));
+	/* The rest of the failing line does not run; the handler does. */
+	obj->skiprestofline = true;
+	SUCCEED_RETURN(errctx);
+    }
+
     obj->errclass = errclass;
     /* Where HELP will look. Recorded before the message is built, so a report
      * that itself fails still leaves the line behind. */
@@ -276,6 +337,23 @@ akerr_ErrorContext *akbasic_runtime_set_mode(akbasic_Runtime *obj, int mode)
     if ( obj->mode == AKBASIC_MODE_REPL ) {
 	PASS(errctx, akbasic_runtime_println(obj, "READY"));
     }
+    /*
+     * File the program's labels here rather than in any one of the several
+     * places that start a run. Every one of them -- akbasic_runtime_start(),
+     * RUN, CONT, and the end of a RUNSTREAM load -- arrives through this
+     * function, and the last of those is the one a driver reading a file from
+     * argv takes, where the program does not exist yet when start() is called.
+     */
+    if ( obj->mode == AKBASIC_MODE_RUN && obj->environment != NULL ) {
+	PASS(errctx, akbasic_runtime_scan_labels(obj));
+	/*
+	 * And the DATA items, for the same reason and at the same moment: READ
+	 * walks a cursor along a list built before the program runs, so a DATA
+	 * line *before* its READ is found -- which it was not when READ skipped
+	 * forward looking for one.
+	 */
+	PASS(errctx, akbasic_data_scan(obj));
+    }
     SUCCEED_RETURN(errctx);
 }
 
@@ -293,6 +371,8 @@ static akerr_ErrorContext *report_and_reraise(akbasic_Runtime *obj, akerr_ErrorC
     int status = cause->status;
 
     snprintf(message, sizeof(message), "%s", cause->message);
+    /* What ER# reports, if a TRAP is armed. Recorded before the context goes. */
+    obj->lasterrorstatus = status;
     cause->handled = true;
     IGNORE(akerr_release_error(cause));
     PASS(errctx, akbasic_runtime_error(obj, AKBASIC_ERRCLASS_RUNTIME, message));
@@ -458,9 +538,22 @@ akerr_ErrorContext *akbasic_runtime_evaluate(akbasic_Runtime *obj, akbasic_ASTLe
 	 * is the one *not* taken. With an ELSE present the last arm is ELSE;
 	 * without one it is THEN.
 	 */
-	obj->skiprestofline = ((expr->right != NULL) == (rval->boolvalue == AKBASIC_TRUE));
+	{
+	    bool taken = akbasic_value_is_truthy(rval);
+	    akbasic_ASTLeaf *notaken = (taken ? expr->right : expr->left);
 
-	if ( rval->boolvalue == AKBASIC_TRUE ) {
+	    obj->skiprestofline = ((expr->right != NULL) == taken);
+	    /*
+	     * `IF c THEN BEGIN ... BEND` is a block, and the arm not taken has to
+	     * skip the *lines* between here and its BEND -- skiprestofline only
+	     * reaches the end of this line. Arming the wait is what makes a
+	     * multi-line IF possible at all; BEND clears it.
+	     */
+	    if ( notaken != NULL && notaken->leaftype == AKBASIC_LEAF_COMMAND &&
+		 strcmp(notaken->identifier, "BEGIN") == 0 ) {
+		PASS(errctx, akbasic_environment_wait_for_command(obj->environment, "BEND"));
+	    }
+	    if ( taken ) {
 		PASS(errctx, akbasic_runtime_evaluate(obj, expr->left, dest));
 		SUCCEED_RETURN(errctx);
 	    }
@@ -469,6 +562,7 @@ akerr_ErrorContext *akbasic_runtime_evaluate(akbasic_Runtime *obj, akbasic_ASTLe
 		PASS(errctx, akbasic_runtime_evaluate(obj, expr->right, dest));
 		SUCCEED_RETURN(errctx);
 	    }
+	}
 	SUCCEED_RETURN(errctx);
 
     case AKBASIC_LEAF_IDENTIFIER_INT:
@@ -727,6 +821,7 @@ akerr_ErrorContext *akbasic_runtime_process_line_repl(akbasic_Runtime *obj)
     }
 
     obj->environment->lineno += obj->autoLineNumber;
+    obj->hadlinenumber = false;
     PASS(errctx, akbasic_scanner_scan(obj, obj->userline, scanned, sizeof(scanned)));
     PASS(errctx, akbasic_parser_init(&parser, obj));
     obj->skiprestofline = false;
@@ -750,6 +845,23 @@ akerr_ErrorContext *akbasic_runtime_process_line_repl(akbasic_Runtime *obj)
 	    continue;
 	}
 
+	/*
+	 * A line typed with a number is program text; a line typed without one is
+	 * a statement to run now. That is direct mode, and it is what makes
+	 * `PRINT 2 + 2` at the prompt answer `4` instead of quietly becoming
+	 * line 0 of a program.
+	 *
+	 * The reference only ever ran the verbs it marked immediate -- RUN, LIST,
+	 * NEW and the rest -- and filed everything else, so most of the language
+	 * was unreachable from a prompt.
+	 */
+	if ( !obj->hadlinenumber ) {
+	    PASS(errctx, akbasic_runtime_interpret(obj, leaf, &value));
+	    if ( obj->errclass != AKBASIC_ERRCLASS_NONE ) {
+		SUCCEED_RETURN(errctx);
+	    }
+	    continue;
+	}
 	PASS(errctx, akbasic_runtime_interpret_immediate(obj, leaf, &value));
 	if ( value == NULL ) {
 	    /* Not an immediate command, so it is program text: file it. */
@@ -835,6 +947,233 @@ akerr_ErrorContext *akbasic_runtime_process_line_run(akbasic_Runtime *obj)
     SUCCEED_RETURN(errctx);
 }
 
+/* --------------------------------------------------------- label prescan -- */
+
+/**
+ * @brief File any `LABEL <name>` this one source line declares.
+ *
+ * Walks the line a statement at a time, which is all that is needed: `LABEL` is
+ * a verb, a verb starts a statement, and statements are separated by `:`. The
+ * only thing that can hide a colon is a string literal, so that is the only
+ * thing this has to understand about the rest of the language.
+ *
+ * @param root The root environment, whose label table this writes.
+ * @param code One source line, with or without its line number still on it.
+ * @param lineno The number to file any label under.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKBASIC_ERR_BOUNDS When the label table is full.
+ */
+static akerr_ErrorContext *scan_line_labels(akbasic_Environment *root, const char *code, int64_t lineno)
+{
+    PREPARE_ERROR(errctx);
+    const char *cursor = code;
+    bool statementstart = true;
+    bool instring = false;
+
+    while ( *cursor != '\0' ) {
+	if ( instring ) {
+	    instring = (*cursor != '"');
+	    cursor += 1;
+	    continue;
+	}
+	if ( *cursor == '"' ) {
+	    instring = true;
+	    statementstart = false;
+	    cursor += 1;
+	    continue;
+	}
+	if ( *cursor == ':' ) {
+	    statementstart = true;
+	    cursor += 1;
+	    continue;
+	}
+	if ( isspace((unsigned char)*cursor) ) {
+	    cursor += 1;
+	    continue;
+	}
+	/*
+	 * A stored line may still carry its own line number. RUNSTREAM files the
+	 * raw text and lets the scanner strip the number again on the way to
+	 * execution, where akbasic_runtime_load() files what the scanner already
+	 * stripped -- so "30 LABEL X" and "LABEL X" are both real spellings of
+	 * source[30], depending on how the program arrived. Step over the number
+	 * without ending the statement.
+	 */
+	if ( statementstart && isdigit((unsigned char)*cursor) ) {
+	    while ( isdigit((unsigned char)*cursor) ) {
+		cursor += 1;
+	    }
+	    continue;
+	}
+	if ( statementstart && strncasecmp(cursor, "LABEL", 5) == 0
+	     && !isalnum((unsigned char)cursor[5]) ) {
+	    char name[AKBASIC_SYMTAB_MAX_KEY];
+	    size_t used = 0;
+
+	    cursor += 5;
+	    while ( isspace((unsigned char)*cursor) ) {
+		cursor += 1;
+	    }
+	    /*
+	     * Copied as written. Verbs are case-insensitive in this dialect and
+	     * identifiers are not, so folding the name here would file a label
+	     * under a spelling `LABEL` itself never uses.
+	     */
+	    while ( isalnum((unsigned char)*cursor) && used < sizeof(name) - 1 ) {
+		name[used] = *cursor;
+		used += 1;
+		cursor += 1;
+	    }
+	    name[used] = '\0';
+	    if ( used > 0 ) {
+		PASS(errctx, akbasic_symtab_set(&root->labels, name, NULL, lineno));
+	    }
+	    statementstart = false;
+	    continue;
+	}
+	statementstart = false;
+	cursor += 1;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_runtime_scan_labels(akbasic_Runtime *obj)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Environment *root = NULL;
+    int64_t i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in scan_labels");
+    FAIL_ZERO_RETURN(errctx, (obj->environment != NULL), AKERR_NULLPOINTER,
+		     "Runtime has no environment; call akbasic_runtime_init() first");
+    for ( root = obj->environment; root->parent != NULL; root = root->parent ) {
+    }
+    for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
+	if ( obj->source[i].code[0] != '\0' ) {
+	    PASS(errctx, scan_line_labels(root, obj->source[i].code, i));
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------ interrupts -- */
+
+akerr_ErrorContext *akbasic_runtime_arm_interrupt(akbasic_Runtime *obj, akbasic_InterruptSource source, int64_t line, const char *label)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Interrupt *slot = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in arm_interrupt");
+    FAIL_ZERO_RETURN(errctx, (source >= 0 && source < AKBASIC_MAX_INTERRUPTS),
+		     AKBASIC_ERR_BOUNDS, "Interrupt source %d is outside 0..%d",
+		     (int)source, AKBASIC_MAX_INTERRUPTS - 1);
+    FAIL_ZERO_RETURN(errctx, ((line > 0) != (label != NULL && label[0] != '\0')),
+		     AKBASIC_ERR_VALUE,
+		     "An interrupt handler is named by a line number or by a label, not both and not neither");
+
+    slot = &obj->interrupts[source];
+    slot->armed = true;
+    slot->line = line;
+    slot->label[0] = '\0';
+    if ( label != NULL && label[0] != '\0' ) {
+	FAIL_ZERO_RETURN(errctx, (strlen(label) < sizeof(slot->label)), AKBASIC_ERR_BOUNDS,
+			 "Handler label \"%s\" exceeds the %zu character limit",
+			 label, sizeof(slot->label) - 1);
+	strncpy(slot->label, label, sizeof(slot->label) - 1);
+	slot->label[sizeof(slot->label) - 1] = '\0';
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_runtime_disarm_interrupt(akbasic_Runtime *obj, akbasic_InterruptSource source)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in disarm_interrupt");
+    FAIL_ZERO_RETURN(errctx, (source >= 0 && source < AKBASIC_MAX_INTERRUPTS),
+		     AKBASIC_ERR_BOUNDS, "Interrupt source %d is outside 0..%d",
+		     (int)source, AKBASIC_MAX_INTERRUPTS - 1);
+    memset(&obj->interrupts[source], 0, sizeof(obj->interrupts[source]));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_runtime_raise_interrupt(akbasic_Runtime *obj, akbasic_InterruptSource source)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in raise_interrupt");
+    FAIL_ZERO_RETURN(errctx, (source >= 0 && source < AKBASIC_MAX_INTERRUPTS),
+		     AKBASIC_ERR_BOUNDS, "Interrupt source %d is outside 0..%d",
+		     (int)source, AKBASIC_MAX_INTERRUPTS - 1);
+    /*
+     * An unarmed source records nothing. That is what lets a backend raise
+     * unconditionally every frame without first asking what the script has
+     * subscribed to -- and it means a program that arms a handler later does not
+     * immediately inherit a collision from before it was interested.
+     */
+    if ( obj->interrupts[source].armed ) {
+	obj->interrupts[source].pending = true;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_runtime_service_interrupts(akbasic_Runtime *obj, bool *entered)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Interrupt *slot = NULL;
+    int64_t target = 0;
+    int64_t returnline = 0;
+    int i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in service_interrupts");
+    if ( entered != NULL ) {
+	*entered = false;
+    }
+    /* An interrupt does not interrupt an interrupt. */
+    if ( obj->handlerenv != NULL || obj->environment == NULL ) {
+	SUCCEED_RETURN(errctx);
+    }
+
+    for ( i = 0; i < AKBASIC_MAX_INTERRUPTS; i++ ) {
+	if ( obj->interrupts[i].armed && obj->interrupts[i].pending ) {
+	    break;
+	}
+    }
+    if ( i == AKBASIC_MAX_INTERRUPTS ) {
+	SUCCEED_RETURN(errctx);
+    }
+    slot = &obj->interrupts[i];
+
+    /*
+     * Resolve now rather than at arm time, so a LABEL that re-files itself as the
+     * program runs moves the handler with it.
+     */
+    target = slot->line;
+    if ( slot->label[0] != '\0' ) {
+	PASS(errctx, akbasic_environment_get_label(obj->environment, slot->label, &target));
+    }
+    FAIL_ZERO_RETURN(errctx, (target > 0 && target < AKBASIC_MAX_SOURCE_LINES),
+		     AKBASIC_ERR_BOUNDS,
+		     "Interrupt handler line %" PRId64 " is outside 1..%d",
+		     target, AKBASIC_MAX_SOURCE_LINES - 1);
+
+    /*
+     * A GOSUB the program did not write. The return line is the one that was
+     * about to run -- nextline, not lineno, because the line counter has already
+     * moved on past whatever last executed.
+     */
+    slot->pending = false;
+    returnline = obj->environment->nextline;
+    PASS(errctx, akbasic_runtime_new_environment(obj));
+    obj->environment->gosubReturnLine = returnline;
+    obj->environment->nextline = target;
+    obj->handlerenv = obj->environment;
+    if ( entered != NULL ) {
+	*entered = true;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
 /* ------------------------------------------------------------- step loop -- */
 
 akerr_ErrorContext *akbasic_runtime_start(akbasic_Runtime *obj, int mode)
@@ -905,6 +1244,16 @@ akerr_ErrorContext *akbasic_runtime_step(akbasic_Runtime *obj)
      */
     PASS(errctx, akbasic_play_service(obj));
 
+    /*
+     * Sprite motion is serviced beside the note queue and for the same reason:
+     * MOVSPR's continuous form is a duration, not a statement, and a program
+     * sitting in a GETKEY should still see its sprites move. Collisions are
+     * looked for immediately afterwards, so a collision is reported against
+     * where the sprites have just been moved to rather than where they were.
+     */
+    PASS(errctx, akbasic_sprite_service(obj));
+    PASS(errctx, akbasic_collision_service(obj));
+
     if ( obj->mode == AKBASIC_MODE_QUIT ) {
 	SUCCEED_RETURN(errctx);
     }
@@ -921,6 +1270,17 @@ akerr_ErrorContext *akbasic_runtime_step(akbasic_Runtime *obj)
 	SUCCEED_RETURN(errctx);
     }
 
+    /*
+     * SLEEP and WAIT hold the same way GETKEY does, and the clock is refreshed
+     * before they are asked -- a SLEEP that read a stale clock would wake a step
+     * late every time.
+     */
+    PASS(errctx, akbasic_console_update_clock(obj));
+    PASS(errctx, akbasic_console_service(obj, &blocked));
+    if ( blocked ) {
+	SUCCEED_RETURN(errctx);
+    }
+
     PASS(errctx, akbasic_runtime_zero(obj));
     PASS(errctx, akbasic_scanner_zero(obj));
 
@@ -932,6 +1292,28 @@ akerr_ErrorContext *akbasic_runtime_step(akbasic_Runtime *obj)
 	PASS(errctx, akbasic_runtime_process_line_repl(obj));
 	break;
     case AKBASIC_MODE_RUN:
+	/*
+	 * Between lines is the only safe place to enter a handler: a GOSUB
+	 * injected mid-statement would have to return into the middle of a line,
+	 * and the parser keeps no state that could resume there.
+	 *
+	 * A failure here is the program's -- an undefined handler label, a
+	 * handler line out of range -- so it is reported and it stops the run,
+	 * the same treatment a parse error gets in process_line_run(). Letting it
+	 * out of step() would tear down the host over a script's mistake.
+	 */
+	ATTEMPT {
+	    CATCH(errctx, akbasic_runtime_service_interrupts(obj, NULL));
+	} CLEANUP {
+	} PROCESS(errctx) {
+	} HANDLE_DEFAULT(errctx) {
+	    char message[AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH];
+	    snprintf(message, sizeof(message), "%s", errctx->message);
+	    IGNORE(akbasic_runtime_error(obj, AKBASIC_ERRCLASS_RUNTIME, message));
+	} FINISH(errctx, false);
+	if ( obj->errclass != AKBASIC_ERRCLASS_NONE ) {
+	    break;
+	}
 	PASS(errctx, akbasic_runtime_process_line_run(obj));
 	break;
     default:

src/runtime_audio.c

@@ -17,6 +17,7 @@
 #include <akerror.h>
 
 #include <akbasic/audio.h>
+#include <akbasic/args.h>
 #include <akbasic/error.h>
 #include <akbasic/runtime.h>
 
@@ -40,38 +41,6 @@ static akerr_ErrorContext *require_audio(akbasic_Runtime *obj, const char *verb)
     SUCCEED_RETURN(errctx);
 }
 
-/**
- * @brief Collect a verb's numeric arguments, as the graphics verbs do.
- *
- * Duplicated rather than shared with src/runtime_graphics.c on purpose: sharing
- * it would mean a third file existing only to hold one static helper, and the
- * two copies answer to different verbs. If a third group wants it, that is the
- * point at which it earns a home of its own.
- */
-static akerr_ErrorContext *collect_numbers(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb, double *values, int max, int *count)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_ASTLeaf *arg = NULL;
-    akbasic_Value *value = NULL;
-
-    FAIL_ZERO_RETURN(errctx, (obj != NULL && expr != NULL && values != NULL && count != NULL),
-		     AKERR_NULLPOINTER, "NULL argument in collect_numbers");
-    *count = 0;
-    arg = akbasic_leaf_first_argument(expr);
-    while ( arg != NULL ) {
-	FAIL_NONZERO_RETURN(errctx, (*count >= max), AKBASIC_ERR_SYNTAX,
-			    "%s takes at most %d arguments", verb, max);
-	PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
-	FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING),
-			    AKBASIC_ERR_TYPE,
-			    "%s expected a number in argument %d", verb, *count + 1);
-	values[*count] = (value->valuetype == AKBASIC_TYPE_FLOAT)
-	    ? value->floatval : (double)value->intval;
-	*count += 1;
-	arg = arg->next;
-    }
-    SUCCEED_RETURN(errctx);
-}
 
 /**
  * @brief Issue SOUND's swept note, translating its arguments out of SID space.
@@ -142,7 +111,7 @@ akerr_ErrorContext *akbasic_cmd_sound(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 
     (void)lval; (void)rval;
     PASS(errctx, require_audio(obj, "SOUND"));
-    PASS(errctx, collect_numbers(obj, expr, "SOUND", args, 8, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "SOUND", args, 8, &count));
     FAIL_ZERO_RETURN(errctx, (count >= 3), AKBASIC_ERR_SYNTAX,
 		     "SOUND expected a voice, a frequency and a duration");
 
@@ -219,7 +188,7 @@ akerr_ErrorContext *akbasic_cmd_envelope(akbasic_Runtime *obj, akbasic_ASTLeaf *
      * device and a program can set its instruments up before a host lends it one.
      */
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in ENVELOPE");
-    PASS(errctx, collect_numbers(obj, expr, "ENVELOPE", args, 7, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "ENVELOPE", args, 7, &count));
     FAIL_ZERO_RETURN(errctx, (count >= 1), AKBASIC_ERR_SYNTAX,
 		     "ENVELOPE expected a preset number");
 
@@ -270,7 +239,7 @@ akerr_ErrorContext *akbasic_cmd_vol(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
 
     (void)lval; (void)rval;
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in VOL");
-    PASS(errctx, collect_numbers(obj, expr, "VOL", args, 1, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "VOL", args, 1, &count));
     FAIL_ZERO_RETURN(errctx, (count == 1), AKBASIC_ERR_SYNTAX, "VOL expected a level");
 
     level = (int)args[0];
@@ -302,7 +271,7 @@ akerr_ErrorContext *akbasic_cmd_tempo(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 
     (void)lval; (void)rval;
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in TEMPO");
-    PASS(errctx, collect_numbers(obj, expr, "TEMPO", args, 1, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "TEMPO", args, 1, &count));
     FAIL_ZERO_RETURN(errctx, (count == 1), AKBASIC_ERR_SYNTAX, "TEMPO expected a value");
 
     tempo = (int)args[0];

src/runtime_commands.c

@@ -61,6 +61,32 @@ akerr_ErrorContext *akbasic_cmd_print(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 	SUCCEED_TRUE(obj, dest);
 	SUCCEED_RETURN(errctx);
     }
+
+    /*
+     * PRINT USING: the parse handler leaves an argument list of exactly two --
+     * the format and the value -- where a plain PRINT leaves a single
+     * expression. The list is the only thing that tells them apart.
+     */
+    {
+	akbasic_ASTLeaf *arg = akbasic_leaf_first_argument(expr);
+
+	if ( arg != NULL && arg->next != NULL ) {
+	    akbasic_Value *format = NULL;
+	    akbasic_Value *value = NULL;
+	    char formatted[AKBASIC_MAX_STRING_LENGTH];
+
+	    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &format));
+	    FAIL_NONZERO_RETURN(errctx, (format->valuetype != AKBASIC_TYPE_STRING),
+				AKBASIC_ERR_TYPE, "PRINT USING expected a format string");
+	    PASS(errctx, akbasic_runtime_evaluate(obj, arg->next, &value));
+	    PASS(errctx, akbasic_format_using(&obj->format_state, format->stringval, value,
+					      formatted, sizeof(formatted)));
+	    PASS(errctx, akbasic_runtime_println(obj, formatted));
+	    SUCCEED_TRUE(obj, dest);
+	    SUCCEED_RETURN(errctx);
+	}
+    }
+
     PASS(errctx, akbasic_runtime_evaluate(obj, expr->right, dest));
     PASS(errctx, akbasic_value_to_string(*dest, rendered, sizeof(rendered)));
     PASS(errctx, akbasic_runtime_println(obj, rendered));
@@ -131,6 +157,14 @@ akerr_ErrorContext *akbasic_cmd_return(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 		     "RETURN from an orphaned environment");
     obj->environment->parent->nextline = obj->environment->gosubReturnLine;
     PASS(errctx, akbasic_value_clone(result, &obj->environment->returnValue));
+    /*
+     * Leaving an interrupt handler re-arms interrupts. Compared by identity
+     * rather than by a depth counter so that a GOSUB the handler itself makes
+     * returns without re-arming: it is *this* environment that has to pop.
+     */
+    if ( obj->environment == obj->handlerenv ) {
+	obj->handlerenv = NULL;
+    }
     PASS(errctx, akbasic_runtime_prev_environment(obj));
     *dest = result;
     SUCCEED_RETURN(errctx);
@@ -677,6 +711,23 @@ akerr_ErrorContext *akbasic_cmd_next(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 
     obj->environment->loopExitLine = obj->environment->lineno + 1;
 
+    /*
+     * An EXIT sent us here. The loop is over whatever the counter says, and it
+     * is over for *this* loop -- EXIT leaves the innermost one, and the wait it
+     * armed is on the innermost environment, so the first NEXT reached is the
+     * right one whether or not it names the same variable.
+     */
+    if ( obj->environment->exiting ) {
+	obj->environment->exiting = false;
+	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "NEXT"));
+	FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
+			 "NEXT in an orphaned environment");
+	obj->environment->parent->nextline = obj->environment->loopExitLine;
+	PASS(errctx, akbasic_runtime_prev_environment(obj));
+	*dest = &obj->staticFalseValue;
+	SUCCEED_RETURN(errctx);
+    }
+
     /*
      * A NEXT for someone else's loop variable: this environment is done, hand
      * the line back to the parent and pop. That is how nested loops unwind.
@@ -707,12 +758,15 @@ akerr_ErrorContext *akbasic_cmd_next(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     }
 
     /*
-     * Advance the counter. The stored value is mutable, so math_plus updates it
+     * Advance the counter, then store it. math_plus clones like every other
-     * in place -- see TODO.md section 12 item 4. Changing that without changing
+     * operator, so the sum lands in `scratch` and this is what puts it back in
-     * this breaks every FOR loop.
+     * the variable. The reference relied on math_plus mutating the counter in
+     * place instead, which meant `A# + 1` anywhere in a program could modify
+     * `A#` -- TODO.md section 6 item 4.
      */
     PASS(errctx, akbasic_value_math_plus(counter, &obj->environment->forStepValue,
 					 &scratch, &updated));
+    PASS(errctx, akbasic_variable_set_subscript(nextvar, updated, zerosubscript, 1));
     obj->environment->nextline = obj->environment->loopFirstLine;
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
@@ -723,20 +777,31 @@ akerr_ErrorContext *akbasic_cmd_exit(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     PREPARE_ERROR(errctx);
 
     (void)expr; (void)lval; (void)rval;
+    /*
+     * EXIT leaves whichever kind of loop it is standing in, so which verb it
+     * skips forward to depends on that: NEXT for a FOR, LOOP for a DO.
+     */
     FAIL_NONZERO_RETURN(errctx,
-			(obj->environment->forToValue.valuetype == AKBASIC_TYPE_UNDEFINED),
+			(obj->environment->forToValue.valuetype == AKBASIC_TYPE_UNDEFINED &&
-			AKBASIC_ERR_STATE, "EXIT outside the context of FOR");
+			 !obj->environment->isDoLoop),
+			AKBASIC_ERR_STATE, "EXIT outside the context of FOR or DO");
     FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
 		     "EXIT in an orphaned environment");
-    obj->environment->parent->nextline = obj->environment->loopExitLine;
     /*
-     * The reference pops without clearing the wait, which leaves the parent
+     * Skip forward to the loop's NEXT rather than jumping past it. The reference
-     * waiting for a NEXT that will never arrive (TODO.md section 12 item 8). The
+     * jumps to loopExitLine, which is only ever written by NEXT itself -- so an
-     * wait is cleared here first: leaving it set would hang the interpreter
+     * EXIT on the first pass through the loop, which is the ordinary case, jumps
-     * rather than merely misbehave, and no golden case depends on the hang.
+     * to line 0 and restarts the program. Each restart enters FOR again and
+     * takes another environment and another variable, so what a reader sees is
+     * "Maximum runtime variables reached" reported against the FOR.
+     *
+     * The wait does the work instead: nothing between here and the NEXT
+     * executes, the NEXT sees `exiting` and pops rather than looping, and
+     * neither this verb nor that one has to know where the loop ends.
      */
-    PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "NEXT"));
+    obj->environment->exiting = true;
-    PASS(errctx, akbasic_runtime_prev_environment(obj));
+    PASS(errctx, akbasic_environment_wait_for_command(obj->environment,
+						      (obj->environment->isDoLoop ? "LOOP" : "NEXT")));
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
 }
@@ -744,14 +809,93 @@ akerr_ErrorContext *akbasic_cmd_exit(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 akerr_ErrorContext *akbasic_cmd_read(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    akbasic_Environment *env = obj->environment;
+    akbasic_ASTLeaf *identifier = NULL;
+    akbasic_ASTLeaf assign;
+    akbasic_ASTLeaf literal;
+    akbasic_Value value;
+    akbasic_Value *unused = NULL;
+    int i = 0;
 
     (void)expr; (void)lval; (void)rval;
     /*
-     * READ does not read: it declares that the next DATA line should fill these
+     * READ now reads. The reference records its identifiers, sets the scope
-     * identifiers, and skips forward until one appears.
+     * waiting for a DATA verb and lets execution skip forward until one turns up
+     * -- which never finds a DATA line written *above* the READ, and leaves
+     * nothing for RESTORE to reset. Every DATA item is pre-scanned into one list
+     * before the program runs (see akbasic_data_scan), and this walks a cursor
+     * along it. TODO.md section 6.
      */
-    PASS(errctx, akbasic_environment_wait_for_command(obj->environment, "DATA"));
+    for ( i = 0; i < AKBASIC_MAX_LEAVES; i++ ) {
-    obj->environment->readIdentifierIdx = 0;
+	identifier = env->readIdentifierLeaves[i];
+	if ( identifier == NULL ) {
+	    break;
+	}
+	PASS(errctx, akbasic_data_next(obj, akbasic_leaf_identifier_type(identifier), &value));
+
+	/*
+	 * Build the assignment by hand rather than through the parser: the
+	 * identifier leaf is a stored copy and the value came from the item
+	 * list, so there is no source text to re-parse.
+	 */
+	PASS(errctx, akbasic_leaf_init(&literal, AKBASIC_LEAF_LITERAL_INT));
+	if ( value.valuetype == AKBASIC_TYPE_STRING ) {
+	    literal.leaftype = AKBASIC_LEAF_LITERAL_STRING;
+	    snprintf(literal.literal_string, sizeof(literal.literal_string), "%s", value.stringval);
+	} else if ( value.valuetype == AKBASIC_TYPE_FLOAT ) {
+	    literal.leaftype = AKBASIC_LEAF_LITERAL_FLOAT;
+	    literal.literal_float = value.floatval;
+	} else {
+	    literal.literal_int = value.intval;
+	}
+	PASS(errctx, akbasic_leaf_init(&assign, AKBASIC_LEAF_BINARY));
+	assign.left = identifier;
+	assign.right = &literal;
+	assign.operator_ = AKBASIC_TOK_ASSIGNMENT;
+	PASS(errctx, akbasic_runtime_evaluate(obj, &assign, &unused));
+    }
+    env->readIdentifierIdx = 0;
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_restore(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *target = NULL;
+    int64_t line = 0;
+    int i = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in RESTORE");
+
+    if ( expr == NULL || expr->right == NULL ) {
+	/* Bare RESTORE goes back to the first item, which is what a C128 does. */
+	obj->data_state.cursor = 0;
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+
+    PASS(errctx, akbasic_runtime_evaluate(obj, expr->right, &target));
+    FAIL_NONZERO_RETURN(errctx, (target->valuetype != AKBASIC_TYPE_INTEGER), AKBASIC_ERR_TYPE,
+			"RESTORE expected a line number or a label");
+    line = target->intval;
+
+    /*
+     * The first item at or after that line. "At or after" rather than "on",
+     * because RESTORE 100 in a program whose DATA is on line 110 should find it
+     * -- a program names the line it wants to start reading *from*.
+     */
+    for ( i = 0; i < obj->data_state.count; i++ ) {
+	if ( obj->data_state.items[i].lineno >= line ) {
+	    obj->data_state.cursor = i;
+	    SUCCEED_TRUE(obj, dest);
+	    SUCCEED_RETURN(errctx);
+	}
+    }
+    /* Nothing at or after it: the next READ is out of data, which is honest. */
+    obj->data_state.cursor = obj->data_state.count;
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
 }
@@ -759,48 +903,16 @@ akerr_ErrorContext *akbasic_cmd_read(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 akerr_ErrorContext *akbasic_cmd_data(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
-    akbasic_Environment *env = obj->environment;
-    akbasic_ASTLeaf *literal = NULL;
-    akbasic_ASTLeaf *identifier = NULL;
-    akbasic_ASTLeaf assign;
-    akbasic_Value *unused = NULL;
 
-    (void)lval; (void)rval;
+    (void)expr; (void)lval; (void)rval;
-    FAIL_ZERO_RETURN(errctx, (expr != NULL && expr->right != NULL), AKERR_NULLPOINTER,
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
-		     "NIL expression or argument list");
+		     "NULL argument in DATA");
-
-    for ( literal = expr->right->right; literal != NULL; literal = literal->next ) {
-	if ( env->readIdentifierIdx >= AKBASIC_MAX_LEAVES ) {
-	    break;
-	}
-	identifier = env->readIdentifierLeaves[env->readIdentifierIdx];
-	if ( identifier == NULL ) {
-	    break;
-	}
     /*
-	 * Build the assignment by hand rather than through the parser: the
+     * Nothing to do. DATA is declaration, not execution: every item was
-	 * identifier leaf is a stored copy and the literal belongs to this
+     * collected into the item list before the program started, so reaching the
-	 * line's pool, so there is no source text to re-parse.
+     * statement means walking past it. The reference did the assigning here,
+     * which is why READ had to skip forward to find one.
      */
-	PASS(errctx, akbasic_leaf_init(&assign, AKBASIC_LEAF_BINARY));
-	assign.left = identifier;
-	assign.right = literal;
-	assign.operator_ = AKBASIC_TOK_ASSIGNMENT;
-	PASS(errctx, akbasic_runtime_evaluate(obj, &assign, &unused));
-	env->readIdentifierIdx += 1;
-    }
-
-    if ( literal == NULL &&
-	 env->readIdentifierIdx < AKBASIC_MAX_LEAVES &&
-	 env->readIdentifierLeaves[env->readIdentifierIdx] != NULL ) {
-	/* Out of DATA with READ items outstanding: stay in waiting mode. */
-	SUCCEED_TRUE(obj, dest);
-	SUCCEED_RETURN(errctx);
-    }
-
-    PASS(errctx, akbasic_environment_stop_waiting(env, "DATA"));
-    env->lineno = env->readReturnLine;
-    env->readIdentifierIdx = 0;
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
 }

src/runtime_console.c

@@ -0,0 +1,273 @@
+/**
+ * @file runtime_console.c
+ * @brief The group E verbs: SLEEP, WAIT, KEY, WINDOW, and the TI clock.
+ *
+ * Everything here that waits does so by *holding the step loop*, the way GETKEY
+ * already does (see akbasic_input_service). Section 1.6 forbids the library
+ * blocking: a host calls akbasic_runtime_step() once a frame and it must always
+ * come back, so "wait" means "do not advance this step" rather than "do not
+ * return". A bounded akbasic_runtime_run() still returns on time, and a host
+ * that wants to abandon the wait can change the mode.
+ */
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <akerror.h>
+
+#include <akbasic/args.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "verbs.h"
+
+/* Most verbs answer "did something happen"; this is that answer. */
+#define SUCCEED_TRUE(__obj, __dest)			\
+    do {						\
+	*(__dest) = &(__obj)->staticTrueValue;		\
+    } while ( 0 )
+
+/** @brief Jiffies per second. A Commodore counts time in sixtieths. */
+#define JIFFIES_PER_SECOND	60
+
+/* ------------------------------------------------------------------ SLEEP -- */
+
+akerr_ErrorContext *akbasic_cmd_sleep(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    double args[1];
+    int count = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in SLEEP");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "SLEEP", args, 1, &count));
+    FAIL_ZERO_RETURN(errctx, (count == 1), AKBASIC_ERR_SYNTAX, "Expected SLEEP (seconds)");
+    FAIL_ZERO_RETURN(errctx, (args[0] >= 0.0), AKBASIC_ERR_VALUE,
+		     "SLEEP cannot wait a negative number of seconds");
+
+    /*
+     * Records when to stop and returns. akbasic_console_service() holds the step
+     * loop until then -- so a program that sleeps still lets its host draw
+     * frames, and a sleeping program in an embedded game does not freeze the
+     * game.
+     *
+     * A host that never calls akbasic_runtime_settime() leaves the clock at
+     * zero, and a deadline computed from a clock that never advances is never
+     * reached. So no clock means no sleep: the verb does nothing rather than
+     * hanging the program, which is the same trade the audio durations make
+     * (§5 deviation 20) and the same direction -- fail fast, not silently
+     * forever.
+     */
+    if ( obj->timems <= 0 ) {
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+    obj->console_state.sleepuntilms = obj->timems + (int64_t)(args[0] * 1000.0);
+    obj->console_state.sleeping = true;
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------------- WAIT -- */
+
+akerr_ErrorContext *akbasic_cmd_wait(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    double args[3];
+    int count = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in WAIT");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "WAIT", args, 3, &count));
+    FAIL_ZERO_RETURN(errctx, (count >= 2), AKBASIC_ERR_SYNTAX,
+		     "Expected WAIT (address), (mask) [, (xor)]");
+
+    /*
+     * WAIT polls a byte until `(PEEK(addr) XOR xor) AND mask` is non-zero. On a
+     * C128 that byte is a hardware register an interrupt is changing; here it is
+     * ordinary process memory, and the only thing that can change it is the host
+     * -- or another thread, or a POKE from a TRAP handler.
+     *
+     * So this is honest but rarely useful: a program that waits on memory
+     * nothing writes waits forever, which is exactly what the same program does
+     * on a C128 with the wrong address. It holds the step loop rather than
+     * blocking, so the host keeps its frame rate and can stop the program.
+     */
+    obj->console_state.waitaddress = (uintptr_t)args[0];
+    obj->console_state.waitmask = (uint8_t)args[1];
+    obj->console_state.waitxor = (count >= 3 ? (uint8_t)args[2] : 0);
+    obj->console_state.waiting = true;
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------------------- KEY -- */
+
+akerr_ErrorContext *akbasic_cmd_key(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Value *value = NULL;
+    /* Room for the longest macro plus `KEY n, ""` around it. */
+    char line[AKBASIC_MAX_STRING_LENGTH + 32];
+    int64_t number = 0;
+    int i = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in KEY");
+
+    arg = akbasic_leaf_first_argument(expr);
+    if ( arg == NULL ) {
+	/* Bare KEY lists the definitions, which is what a C128 does. */
+	for ( i = 0; i < AKBASIC_MAX_FUNCTION_KEYS; i++ ) {
+	    snprintf(line, sizeof(line), "KEY %d, \"%s\"",
+		     i + 1, obj->console_state.keys[i]);
+	    PASS(errctx, akbasic_runtime_println(obj, line));
+	}
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"KEY expected a key number");
+    number = value->intval;
+    FAIL_ZERO_RETURN(errctx, (number >= 1 && number <= AKBASIC_MAX_FUNCTION_KEYS),
+		     AKBASIC_ERR_BOUNDS, "KEY %" PRId64 " is outside 1..%d",
+		     number, AKBASIC_MAX_FUNCTION_KEYS);
+
+    arg = arg->next;
+    FAIL_ZERO_RETURN(errctx, (arg != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected KEY (number), (string)");
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"KEY expected a string");
+    snprintf(obj->console_state.keys[number - 1],
+	     sizeof(obj->console_state.keys[0]), "%s", value->stringval);
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ----------------------------------------------------------------- WINDOW -- */
+
+akerr_ErrorContext *akbasic_cmd_window(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    double args[5];
+    int count = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in WINDOW");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "WINDOW", args, 5, &count));
+    FAIL_ZERO_RETURN(errctx, (count >= 4), AKBASIC_ERR_SYNTAX,
+		     "Expected WINDOW (left), (top), (right), (bottom) [, (clear)]");
+    /*
+     * The geometry first, and deliberately: an inside-out rectangle is a mistake
+     * in the program whether or not a device is attached, and reporting "no
+     * device" for it would send the author looking in the wrong place.
+     */
+    FAIL_ZERO_RETURN(errctx, (args[0] <= args[2] && args[1] <= args[3]), AKBASIC_ERR_VALUE,
+		     "WINDOW's bottom right must not be above or left of its top left");
+    FAIL_ZERO_RETURN(errctx, (obj->sink != NULL), AKBASIC_ERR_DEVICE,
+		     "WINDOW needs a text device and this runtime has none");
+    FAIL_ZERO_RETURN(errctx, (obj->sink->window != NULL), AKBASIC_ERR_DEVICE,
+		     "WINDOW needs a text device with a character grid, and this one has none");
+
+    PASS(errctx, obj->sink->window(obj->sink, (int)args[0], (int)args[1],
+				   (int)args[2], (int)args[3]));
+    if ( count >= 5 && args[4] != 0.0 ) {
+	PASS(errctx, obj->sink->clear(obj->sink));
+    }
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- service -- */
+
+akerr_ErrorContext *akbasic_console_state_init(akbasic_ConsoleState *obj)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL console state in init");
+    memset(obj, 0, sizeof(*obj));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_console_service(akbasic_Runtime *obj, bool *blocked)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && blocked != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in console_service");
+    *blocked = false;
+
+    if ( obj->console_state.sleeping ) {
+	if ( obj->timems >= obj->console_state.sleepuntilms ) {
+	    obj->console_state.sleeping = false;
+	} else {
+	    *blocked = true;
+	    SUCCEED_RETURN(errctx);
+	}
+    }
+
+    if ( obj->console_state.waiting ) {
+	const volatile uint8_t *address = (const volatile uint8_t *)obj->console_state.waitaddress;
+	uint8_t byte = 0;
+
+	/*
+	 * `volatile`, because the whole point is that something outside this
+	 * program changes it. Without it the compiler is entitled to read the
+	 * byte once and spin on the register.
+	 */
+	byte = *address;
+	if ( ((byte ^ obj->console_state.waitxor) & obj->console_state.waitmask) != 0 ) {
+	    obj->console_state.waiting = false;
+	} else {
+	    *blocked = true;
+	    SUCCEED_RETURN(errctx);
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_console_update_clock(akbasic_Runtime *obj)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Variable *variable = NULL;
+    int64_t zerosubscript[1] = { 0 };
+    int64_t jiffies = 0;
+    int64_t seconds = 0;
+    char text[16];
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in update_clock");
+    if ( obj->environment == NULL ) {
+	SUCCEED_RETURN(errctx);
+    }
+
+    /*
+     * `TI` and `TI$` are `TI#` and `TI$` here, and they are written rather than
+     * computed on read: this dialect has no bare variable names and no
+     * pseudo-variable mechanism, so they are ordinary globals refreshed once per
+     * step. Same decision as `ER#` and `EL#`, for the same reason.
+     *
+     * Counted in jiffies -- sixtieths of a second -- from the host's clock,
+     * which is what `TI` means on a Commodore. A host that never calls
+     * akbasic_runtime_settime() leaves both at zero, which is a stopped clock
+     * rather than a wrong one.
+     */
+    jiffies = (obj->timems * JIFFIES_PER_SECOND) / 1000;
+    PASS(errctx, akbasic_runtime_global(obj, "TI#", &variable));
+    PASS(errctx, akbasic_variable_set_integer(variable, jiffies, zerosubscript, 1));
+
+    seconds = obj->timems / 1000;
+    snprintf(text, sizeof(text), "%02" PRId64 "%02" PRId64 "%02" PRId64,
+	     (seconds / 3600) % 24, (seconds / 60) % 60, seconds % 60);
+    PASS(errctx, akbasic_runtime_global(obj, "TI$", &variable));
+    PASS(errctx, akbasic_variable_set_string(variable, text, zerosubscript, 1));
+    SUCCEED_RETURN(errctx);
+}

src/runtime_disk.c

@@ -0,0 +1,755 @@
+/**
+ * @file runtime_disk.c
+ * @brief The group F verbs: files, channels, and the ones that need a 1541.
+ *
+ * Split three ways, and the split is the whole design.
+ *
+ *   - **Verbs that mean something on a filesystem** are implemented against
+ *     `aksl_f*`: DOPEN, DCLOSE, APPEND, RECORD, SCRATCH, RENAME, COPY, CONCAT,
+ *     DIRECTORY and the binary pair BSAVE/BLOAD.
+ *   - **Verbs that are spellings of ones already here** are aliases: SAVE and
+ *     LOAD are DSAVE and DLOAD, CATALOG is DIRECTORY, DVERIFY is VERIFY.
+ *   - **Verbs that need the hardware** are refused by name, with the reason:
+ *     HEADER, COLLECT, BACKUP, BOOT and DCLEAR. Formatting a disk, validating
+ *     one, duplicating one and resetting a drive have no filesystem meaning that
+ *     is not a lie.
+ *
+ * Channel numbers are the program's, written after `#`. A leading `#` is
+ * optional everywhere -- `DOPEN #1, "F"` and `DOPEN 1, "F"` are the same
+ * statement -- because the scanner reads `#` as its own token and a verb name
+ * cannot carry one.
+ */
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akbasic/args.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "verbs.h"
+
+/* Most verbs answer "did something happen"; this is that answer. */
+#define SUCCEED_TRUE(__obj, __dest)			\
+    do {						\
+	*(__dest) = &(__obj)->staticTrueValue;		\
+    } while ( 0 )
+
+akerr_ErrorContext *akbasic_disk_state_init(akbasic_DiskState *obj)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL disk state in init");
+    memset(obj, 0, sizeof(*obj));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_disk_close_all(akbasic_DiskState *obj)
+{
+    PREPARE_ERROR(errctx);
+    int i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL disk state in close_all");
+    /*
+     * A loop, so CATCH and the _BREAK macros are banned in here. A close that
+     * fails is reported, but the rest are still closed: leaking the others
+     * because one of them was already gone would be a poor trade.
+     */
+    for ( i = 0; i < AKBASIC_MAX_CHANNELS; i++ ) {
+	if ( obj->channels[i].fp != NULL ) {
+	    IGNORE(aksl_fclose(obj->channels[i].fp));
+	    obj->channels[i].fp = NULL;
+	    obj->channels[i].name[0] = '\0';
+	    obj->channels[i].writing = false;
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Check a channel number and hand back its slot. */
+static akerr_ErrorContext *channel_slot(akbasic_Runtime *obj, int64_t number, akbasic_Channel **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (number >= 0 && number < AKBASIC_MAX_CHANNELS),
+		     AKBASIC_ERR_BOUNDS, "Channel %" PRId64 " is outside 0..%d",
+		     number, AKBASIC_MAX_CHANNELS - 1);
+    *dest = &obj->disk_state.channels[number];
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief The slot for an already-open channel, or an error naming the number. */
+static akerr_ErrorContext *open_channel(akbasic_Runtime *obj, int64_t number, akbasic_Channel **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, channel_slot(obj, number, dest));
+    FAIL_ZERO_RETURN(errctx, ((*dest)->fp != NULL), AKBASIC_ERR_STATE,
+		     "Channel %" PRId64 " is not open", number);
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Evaluate one argument as a string. */
+static akerr_ErrorContext *string_arg(akbasic_Runtime *obj, akbasic_ASTLeaf *arg, const char *verb, char *dest, size_t len)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *value = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (arg != NULL), AKBASIC_ERR_SYNTAX, "%s expected a file name", verb);
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"%s expected a file name", verb);
+    snprintf(dest, len, "%s", value->stringval);
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Evaluate one argument as an integer. */
+static akerr_ErrorContext *int_arg(akbasic_Runtime *obj, akbasic_ASTLeaf *arg, const char *verb, int64_t *dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *value = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (arg != NULL), AKBASIC_ERR_SYNTAX, "%s expected a number", verb);
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"%s expected a number", verb);
+    *dest = (value->valuetype == AKBASIC_TYPE_FLOAT)
+	? (int64_t)value->floatval : value->intval;
+    SUCCEED_RETURN(errctx);
+}
+
+/* --------------------------------------------------------- DOPEN / APPEND -- */
+
+/** @brief Shared by DOPEN and APPEND, which differ only in the mode. */
+static akerr_ErrorContext *open_file(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb, const char *mode)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Channel *channel = NULL;
+    char name[AKBASIC_MAX_STRING_LENGTH];
+    int64_t number = 0;
+    bool writing = (mode[0] != 'r');
+
+    arg = akbasic_leaf_first_argument(expr);
+    PASS(errctx, int_arg(obj, arg, verb, &number));
+    PASS(errctx, channel_slot(obj, number, &channel));
+    FAIL_NONZERO_RETURN(errctx, (channel->fp != NULL), AKBASIC_ERR_STATE,
+			"Channel %" PRId64 " is already open on \"%s\"", number, channel->name);
+    PASS(errctx, string_arg(obj, (arg != NULL ? arg->next : NULL), verb, name, sizeof(name)));
+
+    /*
+     * DOPEN's third argument is the C128's `W` for write. It arrives as a bare
+     * identifier, which is a label to this dialect and so cannot be evaluated --
+     * so what is read is the *leaf*, not its value.
+     */
+    if ( arg != NULL && arg->next != NULL && arg->next->next != NULL ) {
+	akbasic_ASTLeaf *modeleaf = arg->next->next;
+
+	if ( modeleaf->leaftype == AKBASIC_LEAF_IDENTIFIER &&
+	     (modeleaf->identifier[0] == 'W' || modeleaf->identifier[0] == 'w') ) {
+	    mode = "w";
+	    writing = true;
+	}
+    }
+
+    PASS(errctx, aksl_fopen(name, mode, &channel->fp));
+    snprintf(channel->name, sizeof(channel->name), "%s", name);
+    channel->writing = writing;
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_dopen(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in DOPEN");
+    PASS(errctx, open_file(obj, expr, "DOPEN", "r"));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_append(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in APPEND");
+    PASS(errctx, open_file(obj, expr, "APPEND", "a"));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_dclose(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Channel *channel = NULL;
+    int64_t number = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in DCLOSE");
+    arg = akbasic_leaf_first_argument(expr);
+    if ( arg == NULL ) {
+	/* Bare DCLOSE closes everything, which is what a C128 does. */
+	PASS(errctx, akbasic_disk_close_all(&obj->disk_state));
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+    PASS(errctx, int_arg(obj, arg, "DCLOSE", &number));
+    PASS(errctx, open_channel(obj, number, &channel));
+    PASS(errctx, aksl_fclose(channel->fp));
+    channel->fp = NULL;
+    channel->name[0] = '\0';
+    channel->writing = false;
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ----------------------------------------------------------------- RECORD -- */
+
+akerr_ErrorContext *akbasic_cmd_record(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Channel *channel = NULL;
+    int64_t number = 0;
+    int64_t record = 0;
+    int64_t offset = 1;
+    int64_t size = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in RECORD");
+    arg = akbasic_leaf_first_argument(expr);
+    PASS(errctx, int_arg(obj, arg, "RECORD", &number));
+    PASS(errctx, open_channel(obj, number, &channel));
+    PASS(errctx, int_arg(obj, (arg != NULL ? arg->next : NULL), "RECORD", &record));
+    if ( arg != NULL && arg->next != NULL && arg->next->next != NULL ) {
+	PASS(errctx, int_arg(obj, arg->next->next, "RECORD", &offset));
+    }
+
+    /*
+     * A C128's RECORD positions within a *relative* file, whose record length was
+     * fixed when the file was created. There is no such thing on a filesystem, so
+     * a record is taken to be a line: the file is rewound and read forward. That
+     * is slower than a seek and it is the only definition that does not require
+     * inventing a record length the file does not have. TODO.md section 5.
+     */
+    FAIL_ZERO_RETURN(errctx, (record >= 1), AKBASIC_ERR_VALUE,
+		     "RECORD numbers records from 1, not %" PRId64, record);
+    PASS(errctx, aksl_fseek(channel->fp, 0, SEEK_SET));
+    for ( size = 1; size < record; size++ ) {
+	char line[AKBASIC_MAX_STRING_LENGTH];
+	size_t length = 0;
+	akerr_ErrorContext *got = aksl_fgets(line, sizeof(line), channel->fp, &length);
+
+	if ( got != NULL ) {
+	    got->handled = true;
+	    IGNORE(akerr_release_error(got));
+	    break;
+	}
+    }
+    if ( offset > 1 ) {
+	PASS(errctx, aksl_fseek(channel->fp, (long)(offset - 1), SEEK_CUR));
+    }
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------- file management -- */
+
+akerr_ErrorContext *akbasic_cmd_scratch(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    char name[AKBASIC_MAX_STRING_LENGTH];
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in SCRATCH");
+    PASS(errctx, string_arg(obj, akbasic_leaf_first_argument(expr), "SCRATCH", name, sizeof(name)));
+    FAIL_ZERO_RETURN(errctx, (remove(name) == 0), AKERR_IO,
+		     "SCRATCH could not delete \"%s\"", name);
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_rename(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    char from[AKBASIC_MAX_STRING_LENGTH];
+    char to[AKBASIC_MAX_STRING_LENGTH];
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in RENAME");
+    arg = akbasic_leaf_first_argument(expr);
+    PASS(errctx, string_arg(obj, arg, "RENAME", from, sizeof(from)));
+    PASS(errctx, string_arg(obj, (arg != NULL ? arg->next : NULL), "RENAME", to, sizeof(to)));
+    FAIL_ZERO_RETURN(errctx, (rename(from, to) == 0), AKERR_IO,
+		     "RENAME could not rename \"%s\" to \"%s\"", from, to);
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Shared by COPY and CONCAT, which differ only in the destination mode. */
+static akerr_ErrorContext *copy_file(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb, const char *mode)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    FILE *in = NULL;
+    FILE *out = NULL;
+    char from[AKBASIC_MAX_STRING_LENGTH];
+    char to[AKBASIC_MAX_STRING_LENGTH];
+    char buffer[4096];
+
+    arg = akbasic_leaf_first_argument(expr);
+    PASS(errctx, string_arg(obj, arg, verb, from, sizeof(from)));
+    PASS(errctx, string_arg(obj, (arg != NULL ? arg->next : NULL), verb, to, sizeof(to)));
+
+    PASS(errctx, aksl_fopen(from, "rb", &in));
+    ATTEMPT {
+	CATCH(errctx, aksl_fopen(to, mode, &out));
+	for ( ;; ) {
+	    size_t got = 0;
+	    size_t put = 0;
+	    bool done = false;
+	    akerr_ErrorContext *read = aksl_fread(buffer, 1, sizeof(buffer), in, &got);
+
+	    if ( read != NULL ) {
+		/*
+		 * A short read is how a file *ends*: aksl_fread reports fewer
+		 * items than asked for as an error, and `got` still holds what
+		 * it managed. Writing that out before stopping is the whole
+		 * copy for any file smaller than the buffer -- the first
+		 * version broke here and produced an empty destination every
+		 * time.
+		 */
+		read->handled = true;
+		IGNORE(akerr_release_error(read));
+		done = true;
+	    }
+	    if ( got > 0 ) {
+		/*
+		 * PASS rather than CATCH: this is a loop, and CATCH expands to
+		 * a break that would leave the rest of the ATTEMPT running with
+		 * an error pending.
+		 */
+		PASS(errctx, aksl_fwrite(buffer, 1, got, out, &put));
+	    }
+	    if ( done || got == 0 ) {
+		break;
+	    }
+	}
+    } CLEANUP {
+	IGNORE(aksl_fclose(in));
+	if ( out != NULL ) {
+	    IGNORE(aksl_fclose(out));
+	}
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_copy(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in COPY");
+    PASS(errctx, copy_file(obj, expr, "COPY", "wb"));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_concat(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in CONCAT");
+    /* Appends rather than replaces, which is the whole difference from COPY. */
+    PASS(errctx, copy_file(obj, expr, "CONCAT", "ab"));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------------- DIRECTORY -- */
+
+akerr_ErrorContext *akbasic_cmd_directory(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)expr; (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in DIRECTORY");
+    /*
+     * Refused rather than half-built. Listing a directory needs opendir/readdir,
+     * which `libakstdlib` does not wrap -- and this project's rule is that a
+     * missing capability gets filed upstream rather than worked around here
+     * (CLAUDE.md). Filed in deps/libakstdlib/TODO.md.
+     *
+     * The alternative was shelling out to `ls`, which a library has no business
+     * doing, or calling readdir directly and stepping outside the error
+     * convention every other call in this file follows.
+     */
+    FAIL_RETURN(errctx, AKBASIC_ERR_DEVICE,
+		"DIRECTORY is not implemented: libakstdlib has no directory-reading wrapper yet");
+}
+
+/* ------------------------------------------------------------ BSAVE/BLOAD -- */
+
+akerr_ErrorContext *akbasic_cmd_bsave(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    FILE *fp = NULL;
+    char name[AKBASIC_MAX_STRING_LENGTH];
+    int64_t from = 0;
+    int64_t to = 0;
+    size_t put = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in BSAVE");
+    arg = akbasic_leaf_first_argument(expr);
+    PASS(errctx, string_arg(obj, arg, "BSAVE", name, sizeof(name)));
+    PASS(errctx, int_arg(obj, (arg != NULL ? arg->next : NULL), "BSAVE", &from));
+    PASS(errctx, int_arg(obj, (arg != NULL && arg->next != NULL ? arg->next->next : NULL),
+			 "BSAVE", &to));
+    FAIL_ZERO_RETURN(errctx, (from != 0 && to > from), AKBASIC_ERR_VALUE,
+		     "BSAVE needs a start address and a higher end address");
+
+    PASS(errctx, aksl_fopen(name, "wb", &fp));
+    ATTEMPT {
+	CATCH(errctx, aksl_fwrite((const void *)(uintptr_t)from, 1, (size_t)(to - from), fp, &put));
+    } CLEANUP {
+	IGNORE(aksl_fclose(fp));
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_bload(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    FILE *fp = NULL;
+    char name[AKBASIC_MAX_STRING_LENGTH];
+    int64_t at = 0;
+    int64_t limit = 0;
+    size_t got = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in BLOAD");
+    arg = akbasic_leaf_first_argument(expr);
+    PASS(errctx, string_arg(obj, arg, "BLOAD", name, sizeof(name)));
+    PASS(errctx, int_arg(obj, (arg != NULL ? arg->next : NULL), "BLOAD", &at));
+    /*
+     * The length is required, unlike a C128's BLOAD which reads until the file
+     * ends. A file longer than the caller expected would otherwise write past
+     * whatever it was pointed at, and there is no way to notice: a BASIC integer
+     * here is a real address. Refusing to guess is the only safe answer -- and
+     * checked before it is read, so a missing one says *that* rather than
+     * "expected a number".
+     */
+    FAIL_ZERO_RETURN(errctx,
+		     (arg != NULL && arg->next != NULL && arg->next->next != NULL),
+		     AKBASIC_ERR_SYNTAX,
+		     "BLOAD needs an address and a maximum length");
+    PASS(errctx, int_arg(obj, arg->next->next, "BLOAD", &limit));
+    FAIL_ZERO_RETURN(errctx, (at != 0 && limit > 0), AKBASIC_ERR_VALUE,
+		     "BLOAD needs an address and a maximum length");
+
+    PASS(errctx, aksl_fopen(name, "rb", &fp));
+    ATTEMPT {
+	akerr_ErrorContext *read = aksl_fread((void *)(uintptr_t)at, 1, (size_t)limit, fp, &got);
+
+	if ( read != NULL ) {
+	    /* A short read is the ordinary case: the file was smaller than the cap. */
+	    read->handled = true;
+	    IGNORE(akerr_release_error(read));
+	}
+    } CLEANUP {
+	IGNORE(aksl_fclose(fp));
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------ channel I/O -- */
+
+akerr_ErrorContext *akbasic_disk_write(akbasic_Runtime *obj, int64_t number, const char *text)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Channel *channel = NULL;
+    size_t put = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && text != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in disk_write");
+    PASS(errctx, open_channel(obj, number, &channel));
+    FAIL_ZERO_RETURN(errctx, channel->writing, AKBASIC_ERR_STATE,
+		     "Channel %" PRId64 " was opened for reading", number);
+    PASS(errctx, aksl_fwrite(text, 1, strlen(text), channel->fp, &put));
+    PASS(errctx, aksl_fwrite("\n", 1, 1, channel->fp, &put));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_disk_readline(akbasic_Runtime *obj, int64_t number, char *dest, size_t len, bool *eof)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Channel *channel = NULL;
+    akerr_ErrorContext *got = NULL;
+    char *newline = NULL;
+    size_t length = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL && eof != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in disk_readline");
+    PASS(errctx, open_channel(obj, number, &channel));
+    FAIL_NONZERO_RETURN(errctx, channel->writing, AKBASIC_ERR_STATE,
+			"Channel %" PRId64 " was opened for writing", number);
+
+    *eof = false;
+    dest[0] = '\0';
+    got = aksl_fgets(dest, len, channel->fp, &length);
+    if ( got != NULL ) {
+	/*
+	 * End of file is not an error here, the same way it is not one for the
+	 * sink's readline: running out of input is a state a program handles.
+	 */
+	got->handled = true;
+	IGNORE(akerr_release_error(got));
+	*eof = true;
+	SUCCEED_RETURN(errctx);
+    }
+    newline = strchr(dest, '\n');
+    if ( newline != NULL ) {
+	*newline = '\0';
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_print_channel(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Value *value = NULL;
+    char text[AKBASIC_MAX_STRING_LENGTH];
+    int64_t number = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in PRINT#");
+    arg = akbasic_leaf_first_argument(expr);
+    PASS(errctx, int_arg(obj, arg, "PRINT#", &number));
+    FAIL_ZERO_RETURN(errctx, (arg != NULL && arg->next != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected PRINT #(channel), (expression)");
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg->next, &value));
+    PASS(errctx, akbasic_value_to_string(value, text, sizeof(text)));
+    PASS(errctx, akbasic_disk_write(obj, number, text));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_input_channel(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_ASTLeaf *identifier = NULL;
+    akbasic_ASTLeaf literal;
+    akbasic_ASTLeaf assign;
+    akbasic_Value *unused = NULL;
+    char text[AKBASIC_MAX_STRING_LENGTH];
+    int64_t number = 0;
+    bool eof = false;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in INPUT#");
+    arg = akbasic_leaf_first_argument(expr);
+    PASS(errctx, int_arg(obj, arg, "INPUT#", &number));
+    identifier = (arg != NULL ? arg->next : NULL);
+    FAIL_ZERO_RETURN(errctx, akbasic_leaf_is_identifier(identifier), AKBASIC_ERR_SYNTAX,
+		     "Expected INPUT #(channel), (variable)");
+
+    PASS(errctx, akbasic_disk_readline(obj, number, text, sizeof(text), &eof));
+    /*
+     * End of file leaves the variable empty rather than raising. A program reads
+     * until it gets nothing back, which is what it can check -- and a numeric
+     * variable reading an empty line gets zero, the same as a C128.
+     */
+    PASS(errctx, akbasic_leaf_init(&literal, AKBASIC_LEAF_LITERAL_STRING));
+    snprintf(literal.literal_string, sizeof(literal.literal_string), "%s", text);
+    if ( akbasic_leaf_identifier_type(identifier) == AKBASIC_TYPE_INTEGER ) {
+	long long converted = 0;
+
+	literal.leaftype = AKBASIC_LEAF_LITERAL_INT;
+	literal.literal_int = 0;
+	if ( !eof && text[0] != '\0' ) {
+	    PASS(errctx, aksl_atoll(text, &converted));
+	    literal.literal_int = (int64_t)converted;
+	}
+    } else if ( akbasic_leaf_identifier_type(identifier) == AKBASIC_TYPE_FLOAT ) {
+	literal.leaftype = AKBASIC_LEAF_LITERAL_FLOAT;
+	literal.literal_float = 0.0;
+	if ( !eof && text[0] != '\0' ) {
+	    PASS(errctx, aksl_atof(text, &literal.literal_float));
+	}
+    }
+    PASS(errctx, akbasic_leaf_init(&assign, AKBASIC_LEAF_BINARY));
+    assign.left = identifier;
+    assign.right = &literal;
+    assign.operator_ = AKBASIC_TOK_ASSIGNMENT;
+    PASS(errctx, akbasic_runtime_evaluate(obj, &assign, &unused));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- VERIFY -- */
+
+akerr_ErrorContext *akbasic_cmd_dverify(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    FILE *fp = NULL;
+    char name[AKBASIC_MAX_STRING_LENGTH];
+    char line[AKBASIC_MAX_LINE_LENGTH];
+    int64_t lineno = 0;
+    int64_t mismatch = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in VERIFY");
+    PASS(errctx, string_arg(obj, akbasic_leaf_first_argument(expr), "VERIFY", name, sizeof(name)));
+
+    /*
+     * A C128 verifies the program in memory against the one on disk byte for
+     * byte, because a 1541 write could fail silently. Here the comparison is
+     * line by line against the file's text, which is the same question asked of
+     * a filesystem: is what I would save what is already there?
+     */
+    PASS(errctx, aksl_fopen(name, "r", &fp));
+    ATTEMPT {
+	for ( lineno = 0; lineno < AKBASIC_MAX_SOURCE_LINES; lineno++ ) {
+	    size_t length = 0;
+	    akerr_ErrorContext *got = NULL;
+	    char *newline = NULL;
+
+	    if ( obj->source[lineno].code[0] == '\0' ) {
+		continue;
+	    }
+	    got = aksl_fgets(line, sizeof(line), fp, &length);
+	    if ( got != NULL ) {
+		got->handled = true;
+		IGNORE(akerr_release_error(got));
+		mismatch += 1;
+		break;
+	    }
+	    newline = strchr(line, '\n');
+	    if ( newline != NULL ) {
+		*newline = '\0';
+	    }
+	    /*
+	     * The stored line has had its number stripped, so the file's copy is
+	     * compared from past its own number. PASS rather than CATCH: this is
+	     * a loop.
+	     */
+	    {
+		const char *filetext = line;
+
+		while ( *filetext == ' ' ) {
+		    filetext += 1;
+		}
+		while ( *filetext >= '0' && *filetext <= '9' ) {
+		    filetext += 1;
+		}
+		while ( *filetext == ' ' ) {
+		    filetext += 1;
+		}
+		if ( strcmp(filetext, obj->source[lineno].code) != 0 ) {
+		    mismatch += 1;
+		}
+	    }
+	}
+    } CLEANUP {
+	IGNORE(aksl_fclose(fp));
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+
+    FAIL_NONZERO_RETURN(errctx, (mismatch != 0), AKBASIC_ERR_VALUE,
+			"VERIFY: \"%s\" does not match the program in memory (%" PRId64 " lines differ)",
+			name, mismatch);
+    PASS(errctx, akbasic_runtime_println(obj, "OK"));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* --------------------------------------------------- needs a real 1541 --- */
+
+/**
+ * @brief Refuse a verb that has no meaning without the drive, and say why.
+ *
+ * Five of them, and the reasoning is the same each time: formatting a disk,
+ * validating one, duplicating one, resetting a drive and booting from one are
+ * operations on a physical device. A filesystem has no equivalent that is not a
+ * lie -- `HEADER` would have to mean "delete everything in this directory",
+ * which is a spectacularly bad thing to do to somebody who typed a C128 verb.
+ */
+static akerr_ErrorContext *no_drive(const char *verb, const char *what)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_RETURN(errctx, AKBASIC_ERR_DEVICE,
+		"%s %s, and there is no disk drive here -- only a filesystem", verb, what);
+}
+
+akerr_ErrorContext *akbasic_cmd_header(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)expr; (void)lval; (void)rval; (void)dest;
+    PASS(errctx, no_drive("HEADER", "formats a disk"));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_collect(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)expr; (void)lval; (void)rval; (void)dest;
+    PASS(errctx, no_drive("COLLECT", "validates a disk's block allocation map"));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_backup(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)expr; (void)lval; (void)rval; (void)dest;
+    PASS(errctx, no_drive("BACKUP", "duplicates one disk onto another"));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_boot(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)expr; (void)lval; (void)rval; (void)dest;
+    PASS(errctx, no_drive("BOOT", "loads and runs a boot sector"));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_dclear(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)expr; (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in DCLEAR");
+    /*
+     * The one of the five with a defensible meaning. DCLEAR resets the drive and
+     * closes every channel it had open; the second half is exactly
+     * akbasic_disk_close_all(), so that is what it does. The first half has
+     * nothing to reset.
+     */
+    PASS(errctx, akbasic_disk_close_all(&obj->disk_state));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}

src/runtime_format.c

@@ -0,0 +1,121 @@
+/**
+ * @file runtime_format.c
+ * @brief The group D verbs: PRINT USING, PUDEF, WIDTH and CHAR.
+ *
+ * Formatting and text placement. The field rendering itself lives in
+ * src/format.c, which is a pure function of a format string and a value and is
+ * tested as one; what is here is the verbs that reach it.
+ */
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <akerror.h>
+
+#include <akbasic/args.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "verbs.h"
+
+/* Most verbs answer "did something happen"; this is that answer. */
+#define SUCCEED_TRUE(__obj, __dest)			\
+    do {						\
+	*(__dest) = &(__obj)->staticTrueValue;		\
+    } while ( 0 )
+
+/* ------------------------------------------------------------------ PUDEF -- */
+
+akerr_ErrorContext *akbasic_cmd_pudef(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *value = NULL;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in PUDEF");
+    FAIL_ZERO_RETURN(errctx, (expr != NULL && expr->right != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected PUDEF \"characters\"");
+    PASS(errctx, akbasic_runtime_evaluate(obj, expr->right, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"PUDEF expected a string");
+    /*
+     * No device needed. The fill characters are the program's state, the same
+     * way COLOR's source bindings are, and a runtime with no output device is
+     * still entitled to remember what it was told.
+     */
+    PASS(errctx, akbasic_format_pudef(&obj->format_state, value->stringval));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------------ WIDTH -- */
+
+akerr_ErrorContext *akbasic_cmd_width(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    double args[1];
+    int count = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in WIDTH");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "WIDTH", args, 1, &count));
+    FAIL_ZERO_RETURN(errctx, (count == 1), AKBASIC_ERR_SYNTAX, "Expected WIDTH (1 or 2)");
+    /*
+     * BASIC 7.0's WIDTH sets the thickness of the lines the *graphics* verbs
+     * draw, not a text column count -- a common confusion, and the reason this
+     * verb lives with the drawing state rather than with PRINT.
+     */
+    FAIL_ZERO_RETURN(errctx, (args[0] == 1.0 || args[0] == 2.0), AKBASIC_ERR_BOUNDS,
+		     "WIDTH is 1 or 2, not %d", (int)args[0]);
+    obj->gfx.linewidth = (int)args[0];
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------------- CHAR -- */
+
+akerr_ErrorContext *akbasic_cmd_char(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Value *value = NULL;
+    char text[AKBASIC_MAX_STRING_LENGTH];
+    double coords[3];
+    int count = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in CHAR");
+    FAIL_ZERO_RETURN(errctx, (obj->sink != NULL), AKBASIC_ERR_DEVICE,
+		     "CHAR needs a text device and this runtime has none");
+    FAIL_ZERO_RETURN(errctx, (obj->sink->moveto != NULL), AKBASIC_ERR_DEVICE,
+		     "CHAR needs a text device that can position its cursor, and this one cannot");
+
+    /*
+     * CHAR colour, column, row, "text". The colour argument is accepted and
+     * ignored: this interpreter's text sink draws in one colour, chosen by the
+     * host when it built the sink, and a per-call colour would have to become
+     * part of the sink interface. Recorded in TODO.md section 5.
+     */
+    arg = akbasic_leaf_first_argument(expr);
+    for ( count = 0; count < 3 && arg != NULL; count++, arg = arg->next ) {
+	PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+	FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			    "CHAR expected a number in argument %d", count + 1);
+	coords[count] = (value->valuetype == AKBASIC_TYPE_FLOAT)
+	    ? value->floatval : (double)value->intval;
+    }
+    FAIL_ZERO_RETURN(errctx, (count == 3 && arg != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected CHAR (colour), (column), (row), (string)");
+
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    PASS(errctx, akbasic_value_to_string(value, text, sizeof(text)));
+
+    PASS(errctx, obj->sink->moveto(obj->sink, (int)coords[1], (int)coords[2]));
+    PASS(errctx, obj->sink->write(obj->sink, text));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}

src/runtime_graphics.c

@@ -20,6 +20,7 @@
 #include <akerror.h>
 #include <akstdlib.h>
 
+#include <akbasic/args.h>
 #include <akbasic/error.h>
 #include <akbasic/runtime.h>
 
@@ -56,54 +57,6 @@ static akerr_ErrorContext *require_graphics(akbasic_Runtime *obj, const char *ve
     SUCCEED_RETURN(errctx);
 }
 
-/**
- * @brief Collect a verb's arguments into an array, evaluating each one.
- *
- * The graphics verbs all take a short positional list with optional trailing
- * members, so every handler wants the same thing: how many arguments arrived,
- * and their numeric values. Strings are refused here rather than in each verb --
- * SSHAPE and GSHAPE, which do take one, read their leaf directly instead.
- *
- * @param obj Runtime to evaluate against.
- * @param expr The command leaf.
- * @param verb Name to use in a diagnostic.
- * @param values Where to put the evaluated arguments.
- * @param max Capacity of `values`.
- * @param count Output destination populated by the function.
- */
-static akerr_ErrorContext *collect_numbers(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb, double *values, int max, int *count)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_ASTLeaf *arg = NULL;
-    akbasic_Value *value = NULL;
-
-    FAIL_ZERO_RETURN(errctx, (obj != NULL && expr != NULL && values != NULL && count != NULL),
-		     AKERR_NULLPOINTER, "NULL argument in collect_numbers");
-    *count = 0;
-    arg = akbasic_leaf_first_argument(expr);
-    /*
-     * A loop, so CATCH and the _BREAK macros are banned in here -- they expand to
-     * a C break and would leave the loop with an error still pending. PASS and
-     * the _RETURN forms only.
-     */
-    while ( arg != NULL ) {
-	FAIL_NONZERO_RETURN(errctx, (*count >= max), AKBASIC_ERR_SYNTAX,
-			    "%s takes at most %d arguments", verb, max);
-	PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
-	FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING),
-			    AKBASIC_ERR_TYPE,
-			    "%s expected a number in argument %d", verb, *count + 1);
-	if ( value->valuetype == AKBASIC_TYPE_FLOAT ) {
-	    values[*count] = value->floatval;
-	} else {
-	    values[*count] = (double)value->intval;
-	}
-	*count += 1;
-	arg = arg->next;
-    }
-    SUCCEED_RETURN(errctx);
-}
-
 /**
  * @brief Map a user coordinate onto the 320x200 space the backend receives.
  *
@@ -123,6 +76,47 @@ static void scale_point(akbasic_GraphicsState *gfx, double *x, double *y)
     }
 }
 
+/**
+ * @brief Draw a line `WIDTH` pixels thick.
+ *
+ * BASIC 7.0's `WIDTH` sets the thickness of the lines the graphics verbs draw,
+ * and the backend record has no thickness argument -- neither does libakgl's
+ * akgl_draw_line, which is what it would have to reach. So a thick line is drawn
+ * as parallel passes, offset perpendicular to whichever axis the line runs along.
+ * That is what a C128 does in effect and it needs nothing new from the device.
+ *
+ * Approximate for a diagonal, where offsetting along one axis leaves the passes a
+ * fraction under a pixel apart. At WIDTH 2 -- the only other value the verb
+ * accepts -- that is not visible; a general thickness would want a real
+ * perpendicular offset and an API that takes one.
+ */
+static akerr_ErrorContext *draw_line(akbasic_Runtime *obj, double x1, double y1, double x2, double y2, akbasic_Color color)
+{
+    PREPARE_ERROR(errctx);
+    double dx = (x2 > x1 ? x2 - x1 : x1 - x2);
+    double dy = (y2 > y1 ? y2 - y1 : y1 - y2);
+    bool steep = (dy > dx);
+    int pass = 0;
+    int width = (obj->gfx.linewidth > 0 ? obj->gfx.linewidth : 1);
+
+    /*
+     * A loop, so CATCH and the _BREAK macros are banned in here -- they expand
+     * to a C break and would leave the loop with an error still pending.
+     */
+    for ( pass = 0; pass < width; pass++ ) {
+	double offset = (double)pass;
+
+	if ( steep ) {
+	    PASS(errctx, obj->graphics->line(obj->graphics, x1 + offset, y1,
+					     x2 + offset, y2, color));
+	} else {
+	    PASS(errctx, obj->graphics->line(obj->graphics, x1, y1 + offset,
+					     x2, y2 + offset, color));
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
 /* ------------------------------------------------------------- GRAPHIC --- */
 
 akerr_ErrorContext *akbasic_cmd_graphic(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
@@ -135,7 +129,7 @@ akerr_ErrorContext *akbasic_cmd_graphic(akbasic_Runtime *obj, akbasic_ASTLeaf *e
 
     (void)lval; (void)rval;
     PASS(errctx, require_graphics(obj, "GRAPHIC"));
-    PASS(errctx, collect_numbers(obj, expr, "GRAPHIC", args, 2, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "GRAPHIC", args, 2, &count));
     FAIL_ZERO_RETURN(errctx, (count >= 1), AKBASIC_ERR_SYNTAX, "GRAPHIC expected a mode");
 
     mode = (int)args[0];
@@ -186,7 +180,7 @@ akerr_ErrorContext *akbasic_cmd_color(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
      * colors up before the host has lent it a renderer.
      */
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in COLOR");
-    PASS(errctx, collect_numbers(obj, expr, "COLOR", args, 2, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "COLOR", args, 2, &count));
     FAIL_ZERO_RETURN(errctx, (count == 2), AKBASIC_ERR_SYNTAX,
 		     "COLOR expected a source and a color");
 
@@ -212,7 +206,7 @@ akerr_ErrorContext *akbasic_cmd_locate(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 
     (void)lval; (void)rval;
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in LOCATE");
-    PASS(errctx, collect_numbers(obj, expr, "LOCATE", args, 2, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "LOCATE", args, 2, &count));
     FAIL_ZERO_RETURN(errctx, (count == 2), AKBASIC_ERR_SYNTAX, "LOCATE expected X, Y");
 
     /*
@@ -236,7 +230,7 @@ akerr_ErrorContext *akbasic_cmd_scale(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 
     (void)lval; (void)rval;
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in SCALE");
-    PASS(errctx, collect_numbers(obj, expr, "SCALE", args, 3, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "SCALE", args, 3, &count));
     FAIL_ZERO_RETURN(errctx, (count >= 1), AKBASIC_ERR_SYNTAX, "SCALE expected 0 or 1");
 
     /* Pure coordinate arithmetic -- nothing reaches the device. */
@@ -271,7 +265,7 @@ akerr_ErrorContext *akbasic_cmd_draw(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 
     (void)lval; (void)rval;
     PASS(errctx, require_graphics(obj, "DRAW"));
-    PASS(errctx, collect_numbers(obj, expr, "DRAW", args, 32, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "DRAW", args, 32, &count));
     FAIL_ZERO_RETURN(errctx, (count >= 1), AKBASIC_ERR_SYNTAX,
 		     "DRAW expected a color source");
     FAIL_NONZERO_RETURN(errctx, (count > 1 && (count % 2) == 0), AKBASIC_ERR_SYNTAX,
@@ -308,7 +302,7 @@ akerr_ErrorContext *akbasic_cmd_draw(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 	y = args[i + 3];
 	scale_point(&obj->gfx, &px, &py);
 	scale_point(&obj->gfx, &x, &y);
-	PASS(errctx, obj->graphics->line(obj->graphics, px, py, x, y, color));
+	PASS(errctx, draw_line(obj, px, py, x, y, color));
     }
     obj->gfx.x = args[count - 2];
     obj->gfx.y = args[count - 1];
@@ -340,7 +334,7 @@ akerr_ErrorContext *akbasic_cmd_box(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
 
     (void)lval; (void)rval;
     PASS(errctx, require_graphics(obj, "BOX"));
-    PASS(errctx, collect_numbers(obj, expr, "BOX", args, 6, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "BOX", args, 6, &count));
     FAIL_ZERO_RETURN(errctx, (count >= 3), AKBASIC_ERR_SYNTAX,
 		     "BOX expected a color source and at least one corner");
     PASS(errctx, akbasic_graphics_source_color(&obj->gfx, (int)args[0], &color));
@@ -389,10 +383,8 @@ akerr_ErrorContext *akbasic_cmd_box(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
 	ys[corner] = cy + (ox * sin(radians)) + (oy * cos(radians));
     }
     for ( corner = 0; corner < 4; corner++ ) {
-	PASS(errctx, obj->graphics->line(obj->graphics,
+	PASS(errctx, draw_line(obj, xs[corner], ys[corner],
-					 xs[corner], ys[corner],
+			       xs[(corner + 1) % 4], ys[(corner + 1) % 4], color));
-					 xs[(corner + 1) % 4], ys[(corner + 1) % 4],
-					 color));
     }
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
@@ -423,7 +415,7 @@ akerr_ErrorContext *akbasic_cmd_circle(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 
     (void)lval; (void)rval;
     PASS(errctx, require_graphics(obj, "CIRCLE"));
-    PASS(errctx, collect_numbers(obj, expr, "CIRCLE", args, 9, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "CIRCLE", args, 9, &count));
     FAIL_ZERO_RETURN(errctx, (count >= 4), AKBASIC_ERR_SYNTAX,
 		     "CIRCLE expected a color source, a center and a radius");
     PASS(errctx, akbasic_graphics_source_color(&obj->gfx, (int)args[0], &color));
@@ -464,7 +456,7 @@ akerr_ErrorContext *akbasic_cmd_circle(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 	y = cy + (ox * sin(rot)) + (oy * cos(rot));
 	scale_point(&obj->gfx, &x, &y);
 	if ( !first ) {
-	    PASS(errctx, obj->graphics->line(obj->graphics, px, py, x, y, color));
+	    PASS(errctx, draw_line(obj, px, py, x, y, color));
 	}
 	first = false;
 	px = x;
@@ -493,7 +485,7 @@ akerr_ErrorContext *akbasic_cmd_paint(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 
     (void)lval; (void)rval;
     PASS(errctx, require_graphics(obj, "PAINT"));
-    PASS(errctx, collect_numbers(obj, expr, "PAINT", args, 4, &count));
+    PASS(errctx, akbasic_args_numbers(obj, expr, "PAINT", args, 4, &count));
     FAIL_ZERO_RETURN(errctx, (count >= 3), AKBASIC_ERR_SYNTAX,
 		     "PAINT expected a color source and a coordinate");
     PASS(errctx, akbasic_graphics_source_color(&obj->gfx, (int)args[0], &color));
@@ -540,7 +532,7 @@ akerr_ErrorContext *akbasic_cmd_paint(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
  *
  * SSHAPE and GSHAPE are the only two verbs in the group whose first argument is
  * an identifier rather than a number, so they walk the leaf themselves instead
- * of going through collect_numbers().
+ * of going through akbasic_args_numbers().
  */
 static akerr_ErrorContext *shape_variable(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb, akbasic_Variable **dest, akbasic_ASTLeaf **rest)
 {

src/runtime_housekeeping.c

@@ -18,6 +18,7 @@
 
 #include <akerror.h>
 
+#include <akbasic/args.h>
 #include <akbasic/error.h>
 #include <akbasic/runtime.h>
 
@@ -61,6 +62,13 @@ static akerr_ErrorContext AKERR_NOIGNORE *clear_variables(akbasic_Runtime *obj)
     while ( obj->environment != NULL && obj->environment->parent != NULL ) {
 	PASS(errctx, akbasic_runtime_prev_environment(obj));
     }
+    /*
+     * That unwind may have released the environment an interrupt handler was
+     * running in. Leaving the pointer behind would wedge interrupts off for the
+     * rest of the session, since nothing would ever pop the environment it
+     * compares against again.
+     */
+    obj->handlerenv = NULL;
     root = obj->environment;
     FAIL_ZERO_RETURN(errctx, (root != NULL), AKERR_NULLPOINTER, "Runtime has no root environment");
     PASS(errctx, akbasic_symtab_init(&root->variables, AKBASIC_MAX_VARIABLES));
@@ -85,6 +93,31 @@ akerr_ErrorContext *akbasic_cmd_new(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     PASS(errctx, clear_variables(obj));
     PASS(errctx, akbasic_symtab_init(&obj->environment->labels, AKBASIC_MAX_LABELS));
 
+    /* A new program does not inherit the old one's open files. */
+    PASS(errctx, akbasic_disk_close_all(&obj->disk_state));
+
+    /*
+     * Disarm everything. The handlers were lines of the program that has just
+     * been deleted, so an interrupt left armed would send the *next* program
+     * into whatever happens to be at that line number.
+     */
+    for ( i = 0; i < AKBASIC_MAX_INTERRUPTS; i++ ) {
+	PASS(errctx, akbasic_runtime_disarm_interrupt(obj, (akbasic_InterruptSource)i));
+    }
+
+    /*
+     * And the sprites go back to undefined. The patterns belonged to the program
+     * that has just been deleted. The *device* still holds them -- there is no
+     * verb that undefines a sprite and so no entry point to say so -- but every
+     * one of them is hidden, which is the observable half.
+     */
+    PASS(errctx, akbasic_sprite_state_init(&obj->sprite_state));
+    if ( obj->sprites != NULL && obj->sprites->show != NULL ) {
+	for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
+	    PASS(errctx, obj->sprites->show(obj->sprites, (int)i + 1, false));
+	}
+    }
+
     /*
      * The line counter goes home too. Without this a NEW typed at the REPL
      * leaves the next entered line filed under wherever the last program
@@ -120,6 +153,48 @@ akerr_ErrorContext *akbasic_cmd_clr(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     SUCCEED_RETURN(errctx);
 }
 
+/* ------------------------------------------------------------ RENUMBER --- */
+
+akerr_ErrorContext *akbasic_cmd_renumber(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    double args[3];
+    int count = 0;
+    int64_t newstart = 10;
+    int64_t increment = 10;
+    int64_t oldstart = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in RENUMBER");
+    if ( expr != NULL && akbasic_leaf_first_argument(expr) != NULL ) {
+	PASS(errctx, akbasic_args_numbers(obj, expr, "RENUMBER", args, 3, &count));
+    }
+    if ( count >= 1 ) {
+	newstart = (int64_t)args[0];
+    }
+    if ( count >= 2 ) {
+	increment = (int64_t)args[1];
+    }
+    if ( count >= 3 ) {
+	oldstart = (int64_t)args[2];
+    }
+
+    PASS(errctx, akbasic_renumber(obj, newstart, increment, oldstart));
+    /*
+     * The labels and the DATA items were filed against the old numbering, so
+     * both have to be built again. akbasic_runtime_set_mode() does it on the way
+     * into RUN, but a program renumbered and then CONTinued would otherwise
+     * branch on a stale map.
+     */
+    PASS(errctx, akbasic_runtime_scan_labels(obj));
+    PASS(errctx, akbasic_data_scan(obj));
+    obj->stopped = false;
+    obj->stoppedline = 0;
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
 /* ---------------------------------------------------------------- CONT --- */
 
 akerr_ErrorContext *akbasic_cmd_cont(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)

src/runtime_machine.c

@@ -0,0 +1,132 @@
+/**
+ * @file runtime_machine.c
+ * @brief The group J verbs: FETCH, STASH and SYS.
+ *
+ * Machine-level verbs on a machine that is not a Commodore 128. `POKE`, `PEEK`
+ * and `POINTER` already treat a BASIC integer as a real address in this
+ * process's memory -- that decision was made when they were ported -- and these
+ * follow it, because a `FETCH` that meant something different from the `PEEK`
+ * beside it would be worse than either answer on its own.
+ *
+ * `SYS` does not follow it, and the difference is the point: reading and writing
+ * a byte is something this process can do, and jumping to one is not.
+ */
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <akerror.h>
+
+#include <akbasic/args.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "verbs.h"
+
+/* Most verbs answer "did something happen"; this is that answer. */
+#define SUCCEED_TRUE(__obj, __dest)			\
+    do {						\
+	*(__dest) = &(__obj)->staticTrueValue;		\
+    } while ( 0 )
+
+/**
+ * @brief The copy behind both FETCH and STASH.
+ *
+ * On a C128 the two differ by which side is expansion RAM: `STASH` writes out to
+ * the RAM Expansion Unit and `FETCH` reads back from it. There is no expansion
+ * unit here and no banks, so both are the same byte copy and the only honest
+ * thing to do is say so rather than invent a distinction.
+ *
+ * @param obj Runtime to evaluate against.
+ * @param expr The command leaf.
+ * @param verb Name to use in a diagnostic.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+static akerr_ErrorContext *copy_bytes(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *verb)
+{
+    PREPARE_ERROR(errctx);
+    double args[4];
+    int count = 0;
+    int64_t length = 0;
+
+    PASS(errctx, akbasic_args_numbers(obj, expr, verb, args, 4, &count));
+    FAIL_ZERO_RETURN(errctx, (count >= 3), AKBASIC_ERR_SYNTAX,
+		     "Expected %s (count), (source address), (destination address)", verb);
+    length = (int64_t)args[0];
+    FAIL_ZERO_RETURN(errctx, (length >= 0), AKBASIC_ERR_VALUE,
+		     "%s cannot copy a negative number of bytes", verb);
+    FAIL_ZERO_RETURN(errctx, (args[1] != 0.0 && args[2] != 0.0), AKBASIC_ERR_VALUE,
+		     "%s will not touch address zero", verb);
+    if ( length == 0 ) {
+	SUCCEED_RETURN(errctx);
+    }
+    /*
+     * memmove rather than memcpy: a program shifting a buffer along by a few
+     * bytes overlaps its own source, and that is a normal thing to ask for.
+     *
+     * There is no bounds check, and there cannot be one -- the same is true of
+     * POKE and PEEK. A BASIC integer here is a real address, so a wrong one is a
+     * segmentation fault rather than an error message. See TODO.md section 5.
+     */
+    memmove((void *)(uintptr_t)args[2], (const void *)(uintptr_t)args[1], (size_t)length);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_fetch(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in FETCH");
+    PASS(errctx, copy_bytes(obj, expr, "FETCH"));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_stash(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in STASH");
+    PASS(errctx, copy_bytes(obj, expr, "STASH"));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_sys(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    double args[4];
+    int count = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in SYS");
+    /*
+     * Parsed, then refused. Parsing first is deliberate: a program is told that
+     * SYS is not implemented rather than that its arguments are wrong, and a
+     * listing containing SYS still LISTs and still RENUMBERs.
+     */
+    PASS(errctx, akbasic_args_numbers(obj, expr, "SYS", args, 4, &count));
+    FAIL_ZERO_RETURN(errctx, (count >= 1), AKBASIC_ERR_SYNTAX, "Expected SYS (address)");
+
+    /*
+     * There is no 6502. SYS calls machine code at an address, and the machine
+     * code a C128 program would call is ROM that does not exist here -- so there
+     * is nothing to jump to and nothing sensible to emulate. Jumping to a real
+     * address in this process would be a way to crash it on purpose.
+     *
+     * Refused by name rather than ignored, because a program whose SYS silently
+     * did nothing would carry on as though it had worked. This is the same
+     * reasoning BANK, FAST and MONITOR are out of scope on, with one difference:
+     * those are refused at the table and this one has a handler, because SYS is
+     * common enough in published listings to be worth a specific message.
+     */
+    FAIL_RETURN(errctx, AKBASIC_ERR_DEVICE,
+		"SYS %d: there is no 6502 here, and no ROM to call. Machine code cannot be run by this interpreter",
+		(int)args[0]);
+}

src/runtime_sprite.c

@@ -0,0 +1,755 @@
+/**
+ * @file runtime_sprite.c
+ * @brief The group H verb implementations: SPRITE, MOVSPR, SPRCOLOR, SPRSAV,
+ *        COLLISION, and the BUMP / RSPPOS / RSPRITE / RSPCOLOR readbacks.
+ *
+ * Nothing here includes an SDL or a libakgl header. Every device call goes
+ * through the akbasic_SpriteBackend record the host attached, which is what lets
+ * the whole group be tested in a build with no SDL on the machine.
+ *
+ * These verbs are not in the Go reference -- it lists all of them as
+ * unimplemented -- so the semantics come from Commodore BASIC 7.0 rather than
+ * from a port. Where 7.0 does something a modern renderer cannot, or where the
+ * manual leaves a unit undefined, the decision is recorded in TODO.md section 5
+ * rather than presented as fidelity.
+ *
+ * The verbs split three ways, and the split is what makes them testable:
+ *
+ *   - SPRCOLOR and the four readbacks touch only interpreter state and work with
+ *     no device at all.
+ *   - SPRITE and MOVSPR update interpreter state *and* tell the device. With no
+ *     device they still update the state and then refuse, so a program that
+ *     positions a sprite and asks RSPPOS where it is gets the right answer
+ *     either way.
+ *   - SPRSAV and COLLISION need the device outright.
+ */
+
+#include <inttypes.h>
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <akerror.h>
+
+#include <akbasic/args.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "verbs.h"
+
+/* Most verbs answer "did something happen"; this is that answer. */
+#define SUCCEED_TRUE(__obj, __dest)			\
+    do {						\
+	*(__dest) = &(__obj)->staticTrueValue;		\
+    } while ( 0 )
+
+/** @brief What SSHAPE writes into a string variable, ahead of the slot number. */
+#define SHAPE_PREFIX		"SHAPE:"
+
+/** @brief MOVSPR's four forms, as src/parser_commands.c encodes them. */
+#define MOVSPR_ABSOLUTE		0
+#define MOVSPR_RELATIVE		1
+#define MOVSPR_POLAR		2
+#define MOVSPR_CONTINUOUS	3
+
+/**
+ * @brief Refuse politely when the host lent us no sprite device.
+ *
+ * Names the verb, because "no sprite device" on its own tells a program author
+ * nothing about which line to look at. The standalone stdio driver attaches no
+ * backend at all, so this is a common path rather than an edge case.
+ */
+static akerr_ErrorContext *require_sprites(akbasic_Runtime *obj, const char *verb)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && verb != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in require_sprites");
+    FAIL_ZERO_RETURN(errctx, (obj->sprites != NULL), AKBASIC_ERR_DEVICE,
+		     "%s needs a sprite device and this runtime has none", verb);
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Check a sprite number and turn it into a slot index. */
+static akerr_ErrorContext *sprite_index(int n, const char *verb, int *dest)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (n >= 1 && n <= AKBASIC_MAX_SPRITES), AKBASIC_ERR_BOUNDS,
+		     "%s: sprite %d is outside 1..%d", verb, n, AKBASIC_MAX_SPRITES);
+    *dest = n - 1;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Push one sprite's colour, expansion and priority at the device.
+ *
+ * One call rather than four, matching the backend record: SPRITE sets them
+ * together and a backend that has to rebuild a texture to change a colour should
+ * not do it four times for one statement.
+ */
+static akerr_ErrorContext *push_configuration(akbasic_Runtime *obj, int index)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Sprite *sprite = &obj->sprite_state.sprites[index];
+    akbasic_Color color;
+
+    if ( obj->sprites == NULL || obj->sprites->configure == NULL ) {
+	SUCCEED_RETURN(errctx);
+    }
+    PASS(errctx, akbasic_graphics_palette(sprite->colorindex, &color));
+    PASS(errctx, obj->sprites->configure(obj->sprites, index + 1, color,
+					 sprite->xexpand, sprite->yexpand, sprite->behind));
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- SPRITE -- */
+
+akerr_ErrorContext *akbasic_cmd_sprite(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Sprite *sprite = NULL;
+    double args[7];
+    int count = 0;
+    int index = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in SPRITE");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "SPRITE", args, 7, &count));
+    FAIL_ZERO_RETURN(errctx, (count >= 1), AKBASIC_ERR_SYNTAX,
+		     "SPRITE expected a sprite number");
+    PASS(errctx, sprite_index((int)args[0], "SPRITE", &index));
+    sprite = &obj->sprite_state.sprites[index];
+
+    /*
+     * Every argument after the number is optional and an omitted one leaves that
+     * attribute alone -- which is BASIC 7.0's rule and is what makes
+     * `SPRITE 1,1` and `SPRITE 1,,,,1` both useful.
+     */
+    if ( count >= 2 ) {
+	sprite->enabled = (args[1] != 0.0);
+    }
+    if ( count >= 3 ) {
+	FAIL_ZERO_RETURN(errctx, (args[2] >= 1.0 && args[2] <= 16.0), AKBASIC_ERR_BOUNDS,
+			 "SPRITE: colour %d is outside 1..16", (int)args[2]);
+	sprite->colorindex = (int)args[2];
+    }
+    if ( count >= 4 ) {
+	sprite->behind = (args[3] != 0.0);
+    }
+    if ( count >= 5 ) {
+	sprite->xexpand = (args[4] != 0.0);
+    }
+    if ( count >= 6 ) {
+	sprite->yexpand = (args[5] != 0.0);
+    }
+    if ( count >= 7 ) {
+	/*
+	 * The multicolour bit is recorded and RSPRITE reads it back, but no
+	 * pattern format here carries the second bit per pixel that multicolour
+	 * selects with -- see TODO.md section 5. Recording it costs nothing and
+	 * keeps the argument position honest for the day one does.
+	 */
+	sprite->multicolour = (args[6] != 0.0);
+    }
+
+    /*
+     * State first, device second, and the refusal last of all. A program with no
+     * sprite device still gets its state updated, so RSPRITE and RSPPOS answer
+     * correctly -- and it still gets told, by name, that SPRITE could not reach
+     * a device.
+     */
+    PASS(errctx, require_sprites(obj, "SPRITE"));
+    PASS(errctx, push_configuration(obj, index));
+    if ( obj->sprites->show != NULL ) {
+	PASS(errctx, obj->sprites->show(obj->sprites, index + 1, sprite->enabled));
+    }
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- MOVSPR -- */
+
+/**
+ * @brief Put a sprite where the state says it is, if there is a device to tell.
+ *
+ * Shared by MOVSPR and by the continuous-motion service, which are the only two
+ * things that move a sprite.
+ */
+static akerr_ErrorContext *push_position(akbasic_Runtime *obj, int index)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Sprite *sprite = &obj->sprite_state.sprites[index];
+
+    if ( obj->sprites == NULL || obj->sprites->move == NULL ) {
+	SUCCEED_RETURN(errctx);
+    }
+    PASS(errctx, obj->sprites->move(obj->sprites, index + 1, sprite->x, sprite->y));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_movspr(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Sprite *sprite = NULL;
+    double args[4];
+    int count = 0;
+    int index = 0;
+    int form = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in MOVSPR");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "MOVSPR", args, 4, &count));
+    /* form, n, a, b -- the parse handler guarantees all four or it raised. */
+    FAIL_ZERO_RETURN(errctx, (count == 4), AKBASIC_ERR_SYNTAX,
+		     "MOVSPR expected a sprite number and two values");
+    form = (int)args[0];
+    PASS(errctx, sprite_index((int)args[1], "MOVSPR", &index));
+    sprite = &obj->sprite_state.sprites[index];
+
+    switch ( form ) {
+    case MOVSPR_ABSOLUTE:
+	sprite->x = args[2];
+	sprite->y = args[3];
+	break;
+    case MOVSPR_RELATIVE:
+	sprite->x += args[2];
+	sprite->y += args[3];
+	break;
+    case MOVSPR_POLAR:
+	/*
+	 * Distance first, then angle -- that order is BASIC 7.0's and it is the
+	 * opposite of the continuous form's, which is a trap worth naming. The
+	 * angle is degrees clockwise from vertical, so 0 is straight up and 90 is
+	 * to the right; that is a compass bearing, not the mathematical
+	 * convention, and it is why the sine and cosine look swapped.
+	 */
+	sprite->x += args[2] * sin(args[3] * M_PI / 180.0);
+	sprite->y -= args[2] * cos(args[3] * M_PI / 180.0);
+	break;
+    case MOVSPR_CONTINUOUS:
+	FAIL_ZERO_RETURN(errctx,
+			 (args[3] >= 0.0 && args[3] <= (double)AKBASIC_SPRITE_MAX_SPEED),
+			 AKBASIC_ERR_BOUNDS,
+			 "MOVSPR: speed %d is outside 0..%d",
+			 (int)args[3], AKBASIC_SPRITE_MAX_SPEED);
+	sprite->angle = args[2];
+	sprite->speed = (int)args[3];
+	/*
+	 * Nothing moves here. The sprite starts moving on the next step, paced
+	 * off the host's clock by akbasic_sprite_service() -- exactly the way the
+	 * PLAY queue is, and for the same reason: this library owns no loop and
+	 * must not block.
+	 */
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    default:
+	FAIL_RETURN(errctx, AKBASIC_ERR_SYNTAX, "MOVSPR: unknown argument form %d", form);
+    }
+
+    PASS(errctx, require_sprites(obj, "MOVSPR"));
+    PASS(errctx, push_position(obj, index));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_sprite_service(akbasic_Runtime *obj)
+{
+    PREPARE_ERROR(errctx);
+    double elapsed = 0.0;
+    int i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in sprite_service");
+
+    if ( obj->sprite_state.lastservicems == 0 ) {
+	obj->sprite_state.lastservicems = obj->timems;
+	SUCCEED_RETURN(errctx);
+    }
+    elapsed = (double)(obj->timems - obj->sprite_state.lastservicems) / 1000.0;
+    if ( elapsed <= 0.0 ) {
+	/*
+	 * A host that never calls akbasic_runtime_settime() leaves the clock at
+	 * zero, and a host that stepped twice inside one millisecond has not
+	 * moved. Neither is an error and neither should move a sprite by a
+	 * garbage amount; a clock that went backwards lands here too.
+	 */
+	SUCCEED_RETURN(errctx);
+    }
+    obj->sprite_state.lastservicems = obj->timems;
+
+    /*
+     * A loop, so CATCH and the _BREAK macros are banned in here -- they expand to
+     * a C break and would leave the loop with an error still pending.
+     */
+    for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
+	akbasic_Sprite *sprite = &obj->sprite_state.sprites[i];
+	double distance = 0.0;
+
+	if ( sprite->speed <= 0 ) {
+	    continue;
+	}
+	distance = (double)sprite->speed * AKBASIC_SPRITE_SPEED_PIXELS_PER_SECOND * elapsed;
+	sprite->x += distance * sin(sprite->angle * M_PI / 180.0);
+	sprite->y -= distance * cos(sprite->angle * M_PI / 180.0);
+	PASS(errctx, push_position(obj, i));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------------- SPRCOLOR -- */
+
+akerr_ErrorContext *akbasic_cmd_sprcolor(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Color c1;
+    akbasic_Color c2;
+    double args[2];
+    int count = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in SPRCOLOR");
+    PASS(errctx, akbasic_args_numbers(obj, expr, "SPRCOLOR", args, 2, &count));
+    FAIL_ZERO_RETURN(errctx, (count >= 1), AKBASIC_ERR_SYNTAX,
+		     "SPRCOLOR expected at least one colour");
+    FAIL_ZERO_RETURN(errctx, (args[0] >= 1.0 && args[0] <= 16.0), AKBASIC_ERR_BOUNDS,
+		     "SPRCOLOR: colour %d is outside 1..16", (int)args[0]);
+    obj->sprite_state.sharedcolor1 = (int)args[0];
+    if ( count >= 2 ) {
+	FAIL_ZERO_RETURN(errctx, (args[1] >= 1.0 && args[1] <= 16.0), AKBASIC_ERR_BOUNDS,
+			 "SPRCOLOR: colour %d is outside 1..16", (int)args[1]);
+	obj->sprite_state.sharedcolor2 = (int)args[1];
+    }
+
+    /*
+     * No device required. The two registers are the program's state, RSPCOLOR
+     * reads them back, and a runtime with no sprite device is still entitled to
+     * remember what it was told -- the same rule GRAPHIC's mode follows.
+     */
+    if ( obj->sprites != NULL && obj->sprites->shared_colors != NULL ) {
+	PASS(errctx, akbasic_graphics_palette(obj->sprite_state.sharedcolor1, &c1));
+	PASS(errctx, akbasic_graphics_palette(obj->sprite_state.sharedcolor2, &c2));
+	PASS(errctx, obj->sprites->shared_colors(obj->sprites, c1, c2));
+    }
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- SPRSAV -- */
+
+/**
+ * @brief Read a DIMmed integer array out into packed sprite pattern bytes.
+ *
+ * The array form is ours rather than BASIC 7.0's, and it exists because a value
+ * in this interpreter carries a NUL-terminated `char[256]`: a C128 puts the
+ * 63 raw bytes of a pattern in a string, and a string that cannot hold a zero
+ * byte cannot hold a sprite. An integer array can, and `DIM P#(63)` is exactly
+ * the right size -- see TODO.md section 5.
+ */
+static akerr_ErrorContext *pattern_from_array(akbasic_Runtime *obj, akbasic_ASTLeaf *arg, uint8_t *dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Variable *variable = NULL;
+    int64_t subscript[1];
+    int64_t length = 0;
+    int i = 0;
+
+    PASS(errctx, akbasic_environment_get(obj->environment, arg->identifier, &variable));
+    FAIL_ZERO_RETURN(errctx, (variable != NULL), AKBASIC_ERR_UNDEFINED,
+		     "SPRSAV could not reach the array %s", arg->identifier);
+    length = (int64_t)variable->valuecount;
+    FAIL_ZERO_RETURN(errctx, (length >= AKBASIC_SPRITE_PATTERN_BYTES), AKBASIC_ERR_BOUNDS,
+		     "SPRSAV: %s holds %" PRId64 " elements and a sprite pattern is %d",
+		     arg->identifier, length, AKBASIC_SPRITE_PATTERN_BYTES);
+
+    for ( i = 0; i < AKBASIC_SPRITE_PATTERN_BYTES; i++ ) {
+	akbasic_Value *element = NULL;
+
+	subscript[0] = (int64_t)i;
+	PASS(errctx, akbasic_variable_get_subscript(variable, subscript, 1, &element));
+	FAIL_NONZERO_RETURN(errctx, (element->valuetype == AKBASIC_TYPE_STRING),
+			    AKBASIC_ERR_TYPE,
+			    "SPRSAV: %s(%d) is a string, and a pattern is bytes",
+			    arg->identifier, i);
+	/*
+	 * Masked rather than refused. A pattern byte is eight pixels and there
+	 * are only eight to set, so anything outside 0..255 is a program that
+	 * has miscounted -- but a DATA statement full of 256s should draw
+	 * something recognisable rather than stop the program dead.
+	 */
+	dest[i] = (uint8_t)(((element->valuetype == AKBASIC_TYPE_FLOAT)
+			     ? (int64_t)element->floatval : element->intval) & 0xff);
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Install sprite @p index from whatever the first argument turned out to be.
+ *
+ * Three shapes of source, told apart by what the leaf *is* rather than by an
+ * argument position:
+ *
+ *   - an unsubscripted integer-array identifier -- 63 pattern bytes
+ *   - a string beginning "SHAPE:" -- a region SSHAPE saved
+ *   - any other string -- a path to an image file
+ */
+static akerr_ErrorContext *define_from_leaf(akbasic_Runtime *obj, akbasic_ASTLeaf *arg, int index)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *value = NULL;
+    akbasic_Color fg;
+    akbasic_Color bg;
+    uint8_t pattern[AKBASIC_SPRITE_PATTERN_BYTES];
+
+    if ( arg->leaftype == AKBASIC_LEAF_IDENTIFIER_INT &&
+	 akbasic_leaf_first_subscript(arg) == NULL ) {
+	FAIL_ZERO_RETURN(errctx, (obj->sprites->define != NULL), AKBASIC_ERR_DEVICE,
+			 "This sprite device cannot be given a pattern");
+	PASS(errctx, pattern_from_array(obj, arg, pattern));
+	PASS(errctx, akbasic_graphics_palette(obj->sprite_state.sprites[index].colorindex, &fg));
+	/*
+	 * A clear bit is transparent, not black. On a C128 the background shows
+	 * through a sprite's clear pixels; drawing them opaque would put a
+	 * 24x21 black rectangle behind every sprite.
+	 */
+	bg.r = 0;
+	bg.g = 0;
+	bg.b = 0;
+	bg.a = 0;
+	PASS(errctx, obj->sprites->define(obj->sprites, index + 1, pattern,
+					  AKBASIC_SPRITE_PATTERN_BYTES, fg, bg));
+	SUCCEED_RETURN(errctx);
+    }
+
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_ZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+		     "SPRSAV expected a sprite number, an image path, a saved shape or an integer array");
+
+    if ( strncmp(value->stringval, SHAPE_PREFIX, strlen(SHAPE_PREFIX)) == 0 ) {
+	int handle = atoi(value->stringval + strlen(SHAPE_PREFIX));
+
+	FAIL_ZERO_RETURN(errctx, (obj->sprites->define_shape != NULL), AKBASIC_ERR_DEVICE,
+			 "This sprite device cannot take a saved shape");
+	PASS(errctx, obj->sprites->define_shape(obj->sprites, index + 1, handle));
+	SUCCEED_RETURN(errctx);
+    }
+
+    FAIL_ZERO_RETURN(errctx, (obj->sprites->define_file != NULL), AKBASIC_ERR_DEVICE,
+		     "This sprite device cannot load an image file");
+    /*
+     * The running program's directory goes with the path. The backend tries the
+     * working directory first and this second, which is what makes a `.bas`
+     * stored beside its art work from anywhere -- and it is exactly how libakgl
+     * resolves a spritesheet named by a sprite document.
+     */
+    PASS(errctx, obj->sprites->define_file(obj->sprites, index + 1, value->stringval,
+					   (obj->sourcepath[0] != '\0'
+					    ? obj->sourcepath : NULL)));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_sprsav(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *source = NULL;
+    akbasic_ASTLeaf *target = NULL;
+    akbasic_Value *value = NULL;
+    int index = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in SPRSAV");
+    PASS(errctx, require_sprites(obj, "SPRSAV"));
+
+    source = akbasic_leaf_first_argument(expr);
+    target = (source != NULL ? source->next : NULL);
+    FAIL_ZERO_RETURN(errctx, (source != NULL && target != NULL), AKBASIC_ERR_SYNTAX,
+		     "SPRSAV expected a source and a destination");
+    FAIL_NONZERO_RETURN(errctx, (target->next != NULL), AKBASIC_ERR_SYNTAX,
+			"SPRSAV takes exactly two arguments");
+
+    /*
+     * Only one direction. A C128's SPRSAV also copies a sprite *out* into a
+     * string, which here would mean writing an image file -- a disk operation,
+     * and group F is unimplemented as a whole. Refused by name rather than
+     * half-built; see TODO.md section 5.
+     */
+    PASS(errctx, akbasic_runtime_evaluate(obj, target, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_DEVICE,
+			"SPRSAV cannot copy a sprite out to a string or a file; that is a disk operation and this interpreter has none");
+    PASS(errctx, sprite_index((int)value->intval, "SPRSAV", &index));
+
+    PASS(errctx, define_from_leaf(obj, source, index));
+    obj->sprite_state.sprites[index].defined = true;
+    PASS(errctx, push_configuration(obj, index));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------- COLLISION -- */
+
+akerr_ErrorContext *akbasic_cmd_collision(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_ASTLeaf *handler = NULL;
+    akbasic_Value *value = NULL;
+    int type = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in COLLISION");
+    arg = akbasic_leaf_first_argument(expr);
+    FAIL_ZERO_RETURN(errctx, (arg != NULL), AKBASIC_ERR_SYNTAX,
+		     "COLLISION expected a collision type");
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"COLLISION expected a number");
+    type = (int)value->intval;
+
+    FAIL_ZERO_RETURN(errctx, (type >= 1 && type <= 3), AKBASIC_ERR_BOUNDS,
+		     "COLLISION: type %d is outside 1..3", type);
+    /*
+     * Type 1 only. Sprite-to-background would need the whole render target read
+     * back and compared against each sprite every frame, and a light pen has no
+     * meaning on a machine with no light pen; both are refused by name rather
+     * than silently accepted and never fired. TODO.md section 5.
+     */
+    FAIL_ZERO_RETURN(errctx, (type == 1), AKBASIC_ERR_DEVICE,
+		     "COLLISION type %d is not implemented: %s",
+		     type,
+		     (type == 2
+		      ? "sprite-to-background collision needs the screen read back every frame"
+		      : "there is no light pen"));
+
+    handler = arg->next;
+    if ( handler == NULL ) {
+	/* No target disarms it, which is how a C128 turns a handler off. */
+	PASS(errctx, akbasic_runtime_disarm_interrupt(obj, AKBASIC_INTERRUPT_SPRITE));
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+    FAIL_NONZERO_RETURN(errctx, (handler->next != NULL), AKBASIC_ERR_SYNTAX,
+			"COLLISION takes a type and at most one handler");
+
+    /*
+     * A label is taken by *name*, not by evaluating it. Evaluating would resolve
+     * it here and now, and a handler is normally written on a line the program
+     * has not reached yet -- so the name is what is stored and it is resolved
+     * when the interrupt fires. A line number is an ordinary expression and is
+     * evaluated, so `COLLISION 1, L#` works too.
+     */
+    if ( handler->leaftype == AKBASIC_LEAF_IDENTIFIER &&
+	 akbasic_leaf_first_subscript(handler) == NULL ) {
+	PASS(errctx, akbasic_runtime_arm_interrupt(obj, AKBASIC_INTERRUPT_SPRITE,
+						   0, handler->identifier));
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+
+    PASS(errctx, akbasic_runtime_evaluate(obj, handler, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"COLLISION expected a line number or a label");
+    PASS(errctx, akbasic_runtime_arm_interrupt(obj, AKBASIC_INTERRUPT_SPRITE,
+					       value->intval, NULL));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_collision_service(akbasic_Runtime *obj)
+{
+    PREPARE_ERROR(errctx);
+    uint16_t mask = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER,
+		     "NULL runtime in collision_service");
+    if ( obj->sprites == NULL || obj->sprites->collisions == NULL ) {
+	SUCCEED_RETURN(errctx);
+    }
+    PASS(errctx, obj->sprites->collisions(obj->sprites, &mask));
+    if ( mask == 0 ) {
+	SUCCEED_RETURN(errctx);
+    }
+    /*
+     * Accumulated, not replaced. BUMP() answers "has this sprite hit anything
+     * since I last looked", so a collision that starts and ends between two
+     * polls is still news; BUMP clears what it reports.
+     */
+    obj->sprite_state.bumped |= mask;
+    /*
+     * Raised unconditionally. An unarmed source records nothing, so there is
+     * nothing to ask before raising -- see akbasic_runtime_raise_interrupt.
+     */
+    PASS(errctx, akbasic_runtime_raise_interrupt(obj, AKBASIC_INTERRUPT_SPRITE));
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------- readbacks -- */
+
+/**
+ * @brief Evaluate a function's nth argument.
+ *
+ * The dispatch table hands a function handler `lval` and `rval` as NULL and its
+ * whole argument list on the leaf, so every function in the interpreter digs its
+ * arguments out this way. src/runtime_functions.c has the same helper and keeps
+ * it static; a third copy would be the point at which it moved to args.h, and
+ * this is the second.
+ */
+static akerr_ErrorContext *nth_number(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, const char *fname, int n, int64_t *dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Value *value = NULL;
+    int i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (expr != NULL), AKERR_NULLPOINTER, "NIL leaf");
+    arg = akbasic_leaf_first_argument(expr);
+    for ( i = 0; i < n && arg != NULL; i++ ) {
+	arg = arg->next;
+    }
+    FAIL_ZERO_RETURN(errctx, (arg != NULL), AKBASIC_ERR_SYNTAX,
+		     "%s is missing argument %d", fname, n + 1);
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"%s expected a number in argument %d", fname, n + 1);
+    *dest = (value->valuetype == AKBASIC_TYPE_FLOAT)
+	? (int64_t)value->floatval : value->intval;
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Take a scratch integer value from the per-line pool for a function result. */
+static akerr_ErrorContext *integer_result(akbasic_Runtime *obj, int64_t value, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *out = NULL;
+
+    PASS(errctx, akbasic_environment_new_value(obj->environment, &out));
+    PASS(errctx, akbasic_value_zero(out));
+    out->valuetype = AKBASIC_TYPE_INTEGER;
+    out->intval = value;
+    *dest = out;
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_fn_bump(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    uint16_t reported = 0;
+    int64_t type = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in BUMP");
+    PASS(errctx, nth_number(obj, expr, "BUMP", 0, &type));
+    FAIL_ZERO_RETURN(errctx, (type == 1), AKBASIC_ERR_DEVICE,
+		     "BUMP type %" PRId64 " is not implemented; only sprite-to-sprite collision is",
+		     type);
+
+    /*
+     * Reading clears, which is what a C128 does and what makes the question
+     * answerable at all: without it a program that polls in a loop would see the
+     * same collision forever.
+     */
+    reported = obj->sprite_state.bumped;
+    obj->sprite_state.bumped = 0;
+    PASS(errctx, integer_result(obj, (int64_t)reported, dest));
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_fn_rsppos(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    akbasic_Sprite *sprite = NULL;
+    PREPARE_ERROR(errctx);
+    int64_t n = 0;
+    int64_t field = 0;
+    int index = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in RSPPOS");
+    PASS(errctx, nth_number(obj, expr, "RSPPOS", 0, &n));
+    PASS(errctx, nth_number(obj, expr, "RSPPOS", 1, &field));
+    PASS(errctx, sprite_index((int)n, "RSPPOS", &index));
+    sprite = &obj->sprite_state.sprites[index];
+
+    switch ( field ) {
+    case 0:
+	PASS(errctx, integer_result(obj, (int64_t)sprite->x, dest));
+	break;
+    case 1:
+	PASS(errctx, integer_result(obj, (int64_t)sprite->y, dest));
+	break;
+    case 2:
+	PASS(errctx, integer_result(obj, (int64_t)sprite->speed, dest));
+	break;
+    default:
+	FAIL_RETURN(errctx, AKBASIC_ERR_BOUNDS,
+		    "RSPPOS: field %" PRId64 " is outside 0..2 (x, y, speed)", field);
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_fn_rsprite(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    akbasic_Sprite *sprite = NULL;
+    PREPARE_ERROR(errctx);
+    int64_t n = 0;
+    int64_t field = 0;
+    int index = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in RSPRITE");
+    PASS(errctx, nth_number(obj, expr, "RSPRITE", 0, &n));
+    PASS(errctx, nth_number(obj, expr, "RSPRITE", 1, &field));
+    PASS(errctx, sprite_index((int)n, "RSPRITE", &index));
+    sprite = &obj->sprite_state.sprites[index];
+
+    /* The five fields are SPRITE's own arguments, in SPRITE's own order. */
+    switch ( field ) {
+    case 0:
+	PASS(errctx, integer_result(obj, (sprite->enabled ? 1 : 0), dest));
+	break;
+    case 1:
+	PASS(errctx, integer_result(obj, (int64_t)sprite->colorindex, dest));
+	break;
+    case 2:
+	PASS(errctx, integer_result(obj, (sprite->behind ? 1 : 0), dest));
+	break;
+    case 3:
+	PASS(errctx, integer_result(obj, (sprite->xexpand ? 1 : 0), dest));
+	break;
+    case 4:
+	PASS(errctx, integer_result(obj, (sprite->yexpand ? 1 : 0), dest));
+	break;
+    case 5:
+	PASS(errctx, integer_result(obj, (sprite->multicolour ? 1 : 0), dest));
+	break;
+    default:
+	FAIL_RETURN(errctx, AKBASIC_ERR_BOUNDS,
+		    "RSPRITE: field %" PRId64 " is outside 0..5", field);
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_fn_rspcolor(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    int64_t field = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in RSPCOLOR");
+    PASS(errctx, nth_number(obj, expr, "RSPCOLOR", 0, &field));
+    FAIL_ZERO_RETURN(errctx, (field == 1 || field == 2), AKBASIC_ERR_BOUNDS,
+		     "RSPCOLOR: register %" PRId64 " is 1 or 2", field);
+    PASS(errctx, integer_result(obj,
+				(field == 1
+				 ? (int64_t)obj->sprite_state.sharedcolor1
+				 : (int64_t)obj->sprite_state.sharedcolor2),
+				dest));
+    SUCCEED_RETURN(errctx);
+}

src/runtime_structure.c

@@ -0,0 +1,275 @@
+/**
+ * @file runtime_structure.c
+ * @brief The group A verbs: DO, LOOP, BEGIN, BEND, ON and END.
+ *
+ * Block structure, built on the same `waitingForCommand` machinery `FOR`/`NEXT`
+ * uses (section 1.6): a scope records the verb it is skipping forward to, and
+ * nothing executes until that verb turns up. Everything here is a variation on
+ * that one idea.
+ *
+ * **The line-based limitation applies to all of it.** Skipping works a source
+ * line at a time, so a whole loop written on one line -- `DO : PRINT 1 : LOOP` --
+ * does not loop, exactly as `FOR I=1 TO 3 : PRINT I : NEXT I` does not. That is
+ * recorded in TODO.md section 4 and it wants its own piece of work: making the
+ * skip operate on statements rather than lines.
+ *
+ * None of these verbs is in the Go reference, which lists all of them as
+ * unimplemented, so the semantics come from Commodore BASIC 7.0.
+ */
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <akerror.h>
+
+#include <akbasic/args.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "verbs.h"
+
+/* Most verbs answer "did something happen"; this is that answer. */
+#define SUCCEED_TRUE(__obj, __dest)			\
+    do {						\
+	*(__dest) = &(__obj)->staticTrueValue;		\
+    } while ( 0 )
+
+/**
+ * @brief Should a loop carrying this condition keep going?
+ *
+ * `WHILE` continues while the condition holds and `UNTIL` continues until it
+ * does, which is the same test read two ways. A loop with no condition on that
+ * end always continues -- `DO ... LOOP` is an infinite loop, and `EXIT` or a
+ * `GOTO` is how a program leaves it.
+ */
+static akerr_ErrorContext *loop_continues(akbasic_Runtime *obj, akbasic_ASTLeaf *condition, int kind, bool *dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *value = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in loop_continues");
+    if ( kind == AKBASIC_LOOPCOND_NONE || condition == NULL ) {
+	*dest = true;
+	SUCCEED_RETURN(errctx);
+    }
+    PASS(errctx, akbasic_runtime_evaluate(obj, condition, &value));
+    *dest = akbasic_value_is_truthy(value);
+    if ( kind == AKBASIC_LOOPCOND_UNTIL ) {
+	*dest = !(*dest);
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------------- DO / LOOP -- */
+
+akerr_ErrorContext *akbasic_cmd_do(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    bool enter = false;
+
+    (void)expr; (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in DO");
+    /*
+     * The parse handler has already pushed the scope and stored the condition,
+     * the way FOR's does -- so by the time this runs, `obj->environment` is the
+     * loop's own.
+     */
+    FAIL_ZERO_RETURN(errctx, obj->environment->isDoLoop, AKBASIC_ERR_STATE,
+		     "DO did not establish its own scope");
+
+    PASS(errctx, loop_continues(obj, obj->environment->doConditionLeaf,
+				obj->environment->doConditionKind, &enter));
+    if ( !enter ) {
+	/*
+	 * `DO WHILE` with a condition that is already false runs no body at all,
+	 * so skip forward to the LOOP rather than executing the lines between.
+	 * Same mechanism a zero-iteration FOR uses.
+	 */
+	PASS(errctx, akbasic_environment_wait_for_command(obj->environment, "LOOP"));
+    }
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_loop(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value *value = NULL;
+    akbasic_ASTLeaf *arg = NULL;
+    bool again = false;
+    int kind = AKBASIC_LOOPCOND_NONE;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in LOOP");
+    FAIL_ZERO_RETURN(errctx, obj->environment->isDoLoop, AKBASIC_ERR_STATE,
+		     "LOOP outside the context of DO");
+
+    obj->environment->loopExitLine = obj->environment->lineno + 1;
+
+    /* An EXIT sent us here; the loop is over whatever either condition says. */
+    if ( obj->environment->exiting ) {
+	obj->environment->exiting = false;
+	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "LOOP"));
+	again = false;
+    } else {
+	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "LOOP"));
+	/*
+	 * LOOP's own condition, parsed here rather than by a parse handler: the
+	 * leaf is on this line and this line is still scanned, so unlike DO's
+	 * there is nothing to preserve across iterations.
+	 */
+	arg = (expr != NULL ? expr->right : NULL);
+	if ( arg != NULL ) {
+	    kind = (int)arg->literal_int;
+	    PASS(errctx, loop_continues(obj, arg->left, kind, &again));
+	} else {
+	    /*
+	     * A bare LOOP re-tests whatever DO carried. `DO WHILE c ... LOOP`
+	     * has to check `c` again at the bottom or the loop never ends.
+	     */
+	    PASS(errctx, loop_continues(obj, obj->environment->doConditionLeaf,
+					obj->environment->doConditionKind, &again));
+	}
+    }
+    (void)value;
+
+    if ( again ) {
+	obj->environment->nextline = obj->environment->loopFirstLine;
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+
+    FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
+		     "LOOP in an orphaned environment");
+    obj->environment->parent->nextline = obj->environment->loopExitLine;
+    PASS(errctx, akbasic_runtime_prev_environment(obj));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ----------------------------------------------------------- BEGIN / BEND -- */
+
+akerr_ErrorContext *akbasic_cmd_begin(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)expr; (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in BEGIN");
+    /*
+     * Nothing to do when the block is entered. `IF c THEN BEGIN` reaches this
+     * only when `c` was true, and the lines that follow are then ordinary lines
+     * up to the BEND. The *false* case never gets here at all: the branch arms a
+     * skip to BEND instead -- see the BRANCH case in akbasic_runtime_evaluate().
+     */
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_cmd_bend(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)expr; (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in BEND");
+    /*
+     * Either this is the end of a block that ran, in which case there is nothing
+     * to do, or it is the BEND a skipped block was skipping to, in which case
+     * stopping the skip is the whole job.
+     */
+    if ( akbasic_environment_is_waiting_for(obj->environment, "BEND") ) {
+	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "BEND"));
+    }
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* --------------------------------------------------------------------- ON -- */
+
+akerr_ErrorContext *akbasic_cmd_on(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Value *value = NULL;
+    int64_t selector = 0;
+    int64_t target = 0;
+    int64_t returnline = 0;
+    int index = 0;
+    bool gosub = false;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && expr != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in ON");
+
+    arg = akbasic_leaf_first_argument(expr);
+    FAIL_ZERO_RETURN(errctx, (arg != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected ON (expression) GOTO|GOSUB (line) [, ...]");
+    /* The parse handler puts the GOSUB flag in the first argument's literal. */
+    gosub = (arg->literal_int != 0);
+    arg = arg->next;
+    FAIL_ZERO_RETURN(errctx, (arg != NULL), AKBASIC_ERR_SYNTAX,
+		     "Expected ON (expression) GOTO|GOSUB (line) [, ...]");
+
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"ON expected a number");
+    selector = (value->valuetype == AKBASIC_TYPE_FLOAT)
+	? (int64_t)value->floatval : value->intval;
+
+    /*
+     * One-based, and out of range is not an error: BASIC 7.0 falls through to
+     * the next statement when the selector names no target, which is what makes
+     * `ON X GOTO 100, 200` usable without a bounds check in the program.
+     */
+    for ( arg = arg->next, index = 1; arg != NULL; arg = arg->next, index++ ) {
+	if ( (int64_t)index != selector ) {
+	    continue;
+	}
+	PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+	FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_INTEGER),
+			    AKBASIC_ERR_TYPE, "ON expected a line number or a label");
+	target = value->intval;
+
+	if ( gosub ) {
+	    returnline = obj->environment->lineno + 1;
+	    PASS(errctx, akbasic_runtime_new_environment(obj));
+	    obj->environment->gosubReturnLine = returnline;
+	    obj->environment->nextline = target;
+	} else {
+	    obj->environment->nextline = target;
+	}
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------------------- END -- */
+
+akerr_ErrorContext *akbasic_cmd_end(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    (void)expr; (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in END");
+    /*
+     * The program is over, which is not the same as the interpreter being over.
+     * A file run ends; a REPL session goes back to its prompt. That is what
+     * run_finished_mode already means, and it is the difference between END and
+     * QUIT -- QUIT ends the interpreter whatever started it.
+     *
+     * Unlike STOP this does not arm CONT. A C128 allows CONT after END, but END
+     * says the program finished and CONT after a *finished* program resumes into
+     * whatever line happens to follow, which is a worse answer than refusing.
+     */
+    PASS(errctx, akbasic_runtime_set_mode(obj, obj->run_finished_mode));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}

src/runtime_trap.c

@@ -0,0 +1,189 @@
+/**
+ * @file runtime_trap.c
+ * @brief The group C verbs: TRAP, RESUME, and the ERR() message lookup.
+ *
+ * Error trapping, built on the interrupt machinery COLLISION already uses:
+ * #AKBASIC_INTERRUPT_ERROR was declared with it and armed by nothing until now.
+ * A trapped error is a GOSUB the program did not write, entered at a line
+ * boundary, and `RESUME` is its `RETURN`.
+ *
+ * **`ER` and `EL` are ordinary global variables here, spelled `ER#` and `EL#`.**
+ * A C128 exposes them as bare reserved names, which this dialect cannot do: an
+ * identifier carries its type in a suffix and a bare name is a *label*
+ * (`LABEL DONE` / `GOTO DONE`). Writing them into the global scope costs nothing,
+ * needs no new syntax, and `PRINT ER#` reads the way the rest of the language
+ * does. Recorded in TODO.md section 5.
+ */
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <akerror.h>
+
+#include <akbasic/args.h>
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "verbs.h"
+
+/* Most verbs answer "did something happen"; this is that answer. */
+#define SUCCEED_TRUE(__obj, __dest)			\
+    do {						\
+	*(__dest) = &(__obj)->staticTrueValue;		\
+    } while ( 0 )
+
+akerr_ErrorContext *akbasic_trap_set_error_variables(akbasic_Runtime *obj, int status, int64_t line)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Variable *variable = NULL;
+    int64_t zerosubscript[1] = { 0 };
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER,
+		     "NULL runtime in set_error_variables");
+    /*
+     * The *global* scope, not the active one. A trapped error is reported from
+     * wherever it happened -- inside a GOSUB body, inside a loop -- and a
+     * handler that reads ER# has usually been entered through a scope of its
+     * own. akbasic_runtime_global() walks to the root, which is the only place
+     * both can see.
+     */
+    PASS(errctx, akbasic_runtime_global(obj, "ER#", &variable));
+    PASS(errctx, akbasic_variable_set_integer(variable, (int64_t)status, zerosubscript, 1));
+    PASS(errctx, akbasic_runtime_global(obj, "EL#", &variable));
+    PASS(errctx, akbasic_variable_set_integer(variable, line, zerosubscript, 1));
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------------ TRAP -- */
+
+akerr_ErrorContext *akbasic_cmd_trap(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *target = NULL;
+    akbasic_Value *value = NULL;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in TRAP");
+
+    target = (expr != NULL ? expr->right : NULL);
+    if ( target == NULL ) {
+	/* Bare TRAP disarms, which is how a C128 turns trapping back off. */
+	PASS(errctx, akbasic_runtime_disarm_interrupt(obj, AKBASIC_INTERRUPT_ERROR));
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+
+    /*
+     * A label is taken by name and resolved when the trap fires, exactly as
+     * COLLISION's handler is: an error handler sits on a line normal flow does
+     * not fall into.
+     */
+    if ( target->leaftype == AKBASIC_LEAF_IDENTIFIER &&
+	 akbasic_leaf_first_subscript(target) == NULL ) {
+	PASS(errctx, akbasic_runtime_arm_interrupt(obj, AKBASIC_INTERRUPT_ERROR,
+						   0, target->identifier));
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
+
+    PASS(errctx, akbasic_runtime_evaluate(obj, target, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_INTEGER), AKBASIC_ERR_TYPE,
+			"TRAP expected a line number or a label");
+    PASS(errctx, akbasic_runtime_arm_interrupt(obj, AKBASIC_INTERRUPT_ERROR,
+					       value->intval, NULL));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- RESUME -- */
+
+akerr_ErrorContext *akbasic_cmd_resume(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *target = NULL;
+    akbasic_Value *value = NULL;
+    akbasic_Variable *variable = NULL;
+    int64_t zerosubscript[1] = { 0 };
+    int64_t resumeline = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in RESUME");
+    FAIL_ZERO_RETURN(errctx, (obj->handlerenv != NULL), AKBASIC_ERR_STATE,
+		     "RESUME outside the context of a TRAP handler");
+    FAIL_ZERO_RETURN(errctx, (obj->environment == obj->handlerenv), AKBASIC_ERR_STATE,
+		     "RESUME must return from the handler itself, not from a GOSUB inside it");
+    FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
+		     "RESUME from an orphaned environment");
+
+    /* Where the error happened, which EL# is holding. */
+    PASS(errctx, akbasic_runtime_global(obj, "EL#", &variable));
+    PASS(errctx, akbasic_variable_get_subscript(variable, zerosubscript, 1, &value));
+    resumeline = value->intval;
+
+    target = (expr != NULL ? expr->right : NULL);
+    if ( target == NULL ) {
+	/*
+	 * Bare RESUME retries the line that failed. That is a loop unless the
+	 * handler fixed whatever was wrong, which is the program's business and
+	 * is exactly what the verb is for.
+	 */
+	obj->environment->parent->nextline = resumeline;
+    } else if ( target->leaftype == AKBASIC_LEAF_COMMAND &&
+		strcmp(target->identifier, "NEXT") == 0 ) {
+	/* RESUME NEXT carries on at the line after the one that failed. */
+	obj->environment->parent->nextline = resumeline + 1;
+    } else {
+	PASS(errctx, akbasic_runtime_evaluate(obj, target, &value));
+	FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_INTEGER),
+			    AKBASIC_ERR_TYPE, "RESUME expected NEXT, a line number or a label");
+	obj->environment->parent->nextline = value->intval;
+    }
+
+    obj->handlerenv = NULL;
+    PASS(errctx, akbasic_runtime_prev_environment(obj));
+    SUCCEED_TRUE(obj, dest);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------------- ERR -- */
+
+akerr_ErrorContext *akbasic_fn_err(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *arg = NULL;
+    akbasic_Value *value = NULL;
+    akbasic_Value *out = NULL;
+    const char *name = NULL;
+    int64_t status = 0;
+
+    (void)lval; (void)rval;
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && expr != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in ERR");
+    arg = akbasic_leaf_first_argument(expr);
+    FAIL_ZERO_RETURN(errctx, (arg != NULL), AKBASIC_ERR_SYNTAX, "ERR expected an error number");
+    PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
+    FAIL_NONZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
+			"ERR expected a number");
+    status = (value->valuetype == AKBASIC_TYPE_FLOAT)
+	? (int64_t)value->floatval : value->intval;
+
+    PASS(errctx, akbasic_environment_new_value(obj->environment, &out));
+    PASS(errctx, akbasic_value_zero(out));
+    out->valuetype = AKBASIC_TYPE_STRING;
+
+    /*
+     * The name libakerror registered for the code, which is where every status
+     * in this process is named -- akbasic's own band, libakgl's, and the errno
+     * values underneath. It answers for an unregistered code too, with "Unknown
+     * Error", so there is nothing to add here; the NULL guard is for a libakerror
+     * that ever decides otherwise.
+     */
+    name = akerr_name_for_status((int)status, NULL);
+    snprintf(out->stringval, sizeof(out->stringval), "%s",
+	     (name != NULL ? name : "Unknown Error"));
+    *dest = out;
+    SUCCEED_RETURN(errctx);
+}

src/scanner.c

@@ -340,6 +340,14 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
 	case '*': obj->tokentype = AKBASIC_TOK_STAR;			break;
 	case ',': obj->tokentype = AKBASIC_TOK_COMMA;			break;
 	case ':': obj->tokentype = AKBASIC_TOK_COLON;			break;
+	/*
+	 * MOVSPR's two separators. Both were UNKNOWN TOKEN until sprites, so
+	 * scanning them breaks nothing -- and a `#` only reaches this switch
+	 * when it is not an identifier's type suffix, which match_identifier
+	 * consumes before returning.
+	 */
+	case ';': obj->tokentype = AKBASIC_TOK_SEMICOLON;		break;
+	case '#': obj->tokentype = AKBASIC_TOK_HASHMARK;		break;
 	case '[': obj->tokentype = AKBASIC_TOK_LEFT_SQUAREBRACKET;	break;
 	case ']': obj->tokentype = AKBASIC_TOK_RIGHT_SQUAREBRACKET;	break;
 	case '=':
@@ -388,6 +396,7 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
 		/* Everything after REM is a comment. Stop, keeping the line intact. */
 		break;
 	    } else if ( obj->tokentype == AKBASIC_TOK_LINE_NUMBER ) {
+		obj->hadlinenumber = true;
 		/*
 		 * The line number is not kept as a token. Rewrite the line to
 		 * everything after it, minus leading spaces, and restart the

src/sink_akgl.c

@@ -375,6 +375,74 @@ static akerr_ErrorContext *sink_clear(akbasic_TextSink *self)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Put the cursor at a character cell, for CHAR.
+ *
+ * Clamped rather than refused: a program that asks for a column past the edge of
+ * a window it cannot measure has made an ordinary mistake, and a C128 clamps too.
+ */
+static akerr_ErrorContext *sink_moveto(akbasic_TextSink *self, int col, int row)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSink *state = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL sink in moveto");
+    state = (akbasic_AkglSink *)self->self;
+    FAIL_ZERO_RETURN(errctx, (state != NULL), AKERR_NULLPOINTER, "akgl sink has no state");
+
+    if ( col < 0 ) { col = 0; }
+    if ( row < 0 ) { row = 0; }
+    if ( col >= state->columns ) { col = state->columns - 1; }
+    if ( row >= state->rows ) { row = state->rows - 1; }
+    state->cursorcol = col;
+    state->cursorrow = row;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Constrain the text area to a rectangle of cells, for WINDOW.
+ *
+ * The sink already drives everything -- wrap, scroll, cursor -- from `x`, `y`,
+ * `columns` and `rows`, so a window is those four fields and nothing else. The
+ * cell size does not change, which is what keeps a windowed program's text the
+ * same size as an unwindowed one's.
+ *
+ * The full-screen geometry is remembered so a later WINDOW can grow back out;
+ * without it each call could only ever shrink.
+ */
+static akerr_ErrorContext *sink_window(akbasic_TextSink *self, int left, int top, int right, int bottom)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSink *state = NULL;
+    int maxcols = 0;
+    int maxrows = 0;
+
+    FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL sink in window");
+    state = (akbasic_AkglSink *)self->self;
+    FAIL_ZERO_RETURN(errctx, (state != NULL), AKERR_NULLPOINTER, "akgl sink has no state");
+    FAIL_ZERO_RETURN(errctx, (state->cellw > 0 && state->cellh > 0), AKBASIC_ERR_STATE,
+		     "The sink has no character grid to window");
+
+    maxcols = state->fullwidth / state->cellw;
+    maxrows = state->fullheight / state->cellh;
+    if ( left < 0 ) { left = 0; }
+    if ( top < 0 ) { top = 0; }
+    if ( right >= maxcols ) { right = maxcols - 1; }
+    if ( bottom >= maxrows ) { bottom = maxrows - 1; }
+    FAIL_ZERO_RETURN(errctx, (right >= left && bottom >= top), AKBASIC_ERR_VALUE,
+		     "WINDOW asks for no cells at all");
+
+    state->x = state->fullx + (left * state->cellw);
+    state->y = state->fully + (top * state->cellh);
+    state->columns = (right - left) + 1;
+    state->rows = (bottom - top) + 1;
+    state->width = state->columns * state->cellw;
+    state->height = state->rows * state->cellh;
+    state->cursorcol = 0;
+    state->cursorrow = 0;
+    SUCCEED_RETURN(errctx);
+}
+
 akerr_ErrorContext *akbasic_sink_init_akgl(akbasic_TextSink *obj, akbasic_AkglSink *state, akgl_RenderBackend *renderer, TTF_Font *font, int w, int h)
 {
     PREPARE_ERROR(errctx);
@@ -426,6 +494,11 @@ akerr_ErrorContext *akbasic_sink_init_akgl(akbasic_TextSink *obj, akbasic_AkglSi
     state->y = 0;
     state->width = w;
     state->height = h;
+    /* Remembered so WINDOW can grow back out to the whole area. */
+    state->fullx = state->x;
+    state->fully = state->y;
+    state->fullwidth = w;
+    state->fullheight = h;
     state->cellw = cellw;
     state->cellh = cellh;
     state->columns = w / cellw;
@@ -442,6 +515,8 @@ akerr_ErrorContext *akbasic_sink_init_akgl(akbasic_TextSink *obj, akbasic_AkglSi
     obj->writeln = sink_writeln;
     obj->readline = sink_readline;
     obj->clear = sink_clear;
+    obj->moveto = sink_moveto;
+    obj->window = sink_window;
     SUCCEED_RETURN(errctx);
 }
 

src/sink_tee.c

@@ -90,6 +90,31 @@ static akerr_ErrorContext *tee_clear(akbasic_TextSink *self)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Forward a cursor move to whichever half has a cursor.
+ *
+ * Only one of them will: an akgl sink has a character grid and a stdio sink does
+ * not. Forwarding to both would be wrong anyway -- there is one cursor, and it
+ * belongs to the half that draws.
+ */
+static akerr_ErrorContext *tee_moveto(akbasic_TextSink *self, int col, int row)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_TeeSink *state = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL sink in moveto");
+    state = (akbasic_TeeSink *)self->self;
+    FAIL_ZERO_RETURN(errctx, (state != NULL), AKERR_NULLPOINTER, "tee sink has no state");
+
+    if ( state->primary != NULL && state->primary->moveto != NULL ) {
+	PASS(errctx, state->primary->moveto(state->primary, col, row));
+    }
+    if ( state->mirror != NULL && state->mirror->moveto != NULL ) {
+	PASS(errctx, state->mirror->moveto(state->mirror, col, row));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
 akerr_ErrorContext *akbasic_sink_init_tee(akbasic_TextSink *obj, akbasic_TeeSink *state, akbasic_TextSink *primary, akbasic_TextSink *mirror, akbasic_TextSink *reader)
 {
     PREPARE_ERROR(errctx);
@@ -116,5 +141,13 @@ akerr_ErrorContext *akbasic_sink_init_tee(akbasic_TextSink *obj, akbasic_TeeSink
     obj->writeln = tee_writeln;
     obj->readline = tee_readline;
     obj->clear = tee_clear;
+    /*
+     * Offered only when a half can actually do it, so CHAR's refusal against a
+     * stdio-only driver still reads correctly through a tee.
+     */
+    if ( (primary != NULL && primary->moveto != NULL) ||
+	 (mirror != NULL && mirror->moveto != NULL) ) {
+	obj->moveto = tee_moveto;
+    }
     SUCCEED_RETURN(errctx);
 }

src/sprite_akgl.c

@@ -0,0 +1,585 @@
+/**
+ * @file sprite_akgl.c
+ * @brief Wires the sprite backend record to libakgl's actors.
+ *
+ * Each of BASIC's eight sprites becomes a full libakgl object graph -- a
+ * spritesheet holding one texture, a sprite cutting one frame from it, a
+ * character mapping state 0 to that sprite, and an actor instantiating the
+ * character -- so a host game sees BASIC's sprites in libakgl's actor registry
+ * alongside its own and can do anything to them it can do to an actor.
+ *
+ * **None of that comes from JSON.** akgl_sprite_load_json() is a thin wrapper
+ * over the same four initializers plus writes to public struct fields, and every
+ * field it fills from a document -- frame list, animation speed, loop flags,
+ * state-to-sprite map -- is something a Commodore sprite does not have. The one
+ * exception is the image, and that is exactly where this file *does* call
+ * libakgl: `SPRSAV "ship.png", 1` resolves through akgl_path_relative() and
+ * loads through akgl_spritesheet_initialize(), the same two calls
+ * akgl_sprite_load_json_spritesheet() makes.
+ *
+ * Every actor gets a renderfunc of its own rather than akgl_actor_render(). Two
+ * reasons, both defects filed upstream: the default computes its destination
+ * height from the sprite's *width*, which draws a 24x21 Commodore sprite as a
+ * 24x24 square; and an actor carries one scalar `scale`, which cannot express
+ * SPRITE's separate x- and y-expand bits. Installing a function pointer is
+ * libakgl's own extension point for exactly this, so nothing is forked.
+ */
+
+#include <errno.h>
+#include <string.h>
+
+#include <SDL3_image/SDL_image.h>
+
+#include <akerror.h>
+
+#include <akgl/error.h>
+#include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/registry.h>
+#include <akgl/staticstring.h>
+#include <akgl/util.h>
+
+#include <akbasic/akgl.h>
+#include <akbasic/error.h>
+
+/** @brief The colour conversion, same as src/graphics_akgl.c's. */
+static SDL_Color to_sdl(akbasic_Color color)
+{
+    SDL_Color out;
+
+    out.r = color.r;
+    out.g = color.g;
+    out.b = color.b;
+    out.a = color.a;
+    return out;
+}
+
+/** @brief Recover the backend's own state, or say that it has none. */
+static akerr_ErrorContext *state_of(akbasic_SpriteBackend *self, akbasic_AkglSprites **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (self != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in akgl sprite backend");
+    *dest = (akbasic_AkglSprites *)self->self;
+    FAIL_ZERO_RETURN(errctx, (*dest != NULL), AKERR_NULLPOINTER,
+		     "akgl sprite backend has no state");
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Recover the state and turn a BASIC sprite number into a slot index. */
+static akerr_ErrorContext *slot_of(akbasic_SpriteBackend *self, int n, akbasic_AkglSprites **state, int *index)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, state_of(self, state));
+    FAIL_ZERO_RETURN(errctx, (n >= 1 && n <= AKBASIC_MAX_SPRITES), AKBASIC_ERR_BOUNDS,
+		     "Sprite %d is outside 1..%d", n, AKBASIC_MAX_SPRITES);
+    *index = n - 1;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Draw one BASIC sprite, in place of akgl_actor_render().
+ *
+ * Differs from the default in exactly two ways, both noted at the top of this
+ * file: the destination height comes from the sprite's height rather than its
+ * width, and the two expansion bits scale the axes independently.
+ *
+ * Like the default, it skips rather than reports: an actor with no image, one
+ * that is hidden, one whose slot has been reused. A frame is not the place to
+ * fail.
+ */
+static akerr_ErrorContext *spr_render_actor(akgl_Actor *obj)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    akgl_Sprite *sprite = NULL;
+    SDL_FRect src;
+    SDL_FRect dest;
+    int i = 0;
+    int found = -1;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL actor in sprite render");
+    if ( !obj->visible || obj->basechar == NULL ) {
+	SUCCEED_RETURN(errctx);
+    }
+    state = (akbasic_AkglSprites *)obj->actorData;
+    FAIL_ZERO_RETURN(errctx, (state != NULL), AKERR_NULLPOINTER,
+		     "Sprite actor \"%s\" carries no backend state", obj->name);
+    for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
+	if ( state->actors[i] == obj ) {
+	    found = i;
+	    break;
+	}
+    }
+    if ( found < 0 ) {
+	SUCCEED_RETURN(errctx);
+    }
+    sprite = state->sprites[found];
+    if ( sprite == NULL || sprite->sheet == NULL || sprite->sheet->texture == NULL ) {
+	SUCCEED_RETURN(errctx);
+    }
+
+    PASS(errctx, akgl_sprite_sheet_coords_for_frame(sprite, &src, 0));
+    dest.x = obj->x - (camera != NULL ? camera->x : 0.0f);
+    dest.y = obj->y - (camera != NULL ? camera->y : 0.0f);
+    dest.w = (float32_t)sprite->width * (state->xexpand[found] ? 2.0f : 1.0f);
+    dest.h = (float32_t)sprite->height * (state->yexpand[found] ? 2.0f : 1.0f);
+
+    PASS(errctx, state->renderer->draw_texture(state->renderer, sprite->sheet->texture,
+					       &src, &dest, 0, NULL, SDL_FLIP_NONE));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Tear down slot @p i, releasing its texture with it. */
+static akerr_ErrorContext *release_slot(akbasic_AkglSprites *state, int i)
+{
+    PREPARE_ERROR(errctx);
+
+    /*
+     * Actor first, then character, sprite and sheet. Each borrows the one below
+     * it without taking a reference, so releasing in the other order leaves a
+     * live object pointing at a zeroed pool slot.
+     */
+    if ( state->actors[i] != NULL ) {
+	PASS(errctx, akgl_heap_release_actor(state->actors[i]));
+	state->actors[i] = NULL;
+    }
+    if ( state->characters[i] != NULL ) {
+	PASS(errctx, akgl_heap_release_character(state->characters[i]));
+	state->characters[i] = NULL;
+    }
+    if ( state->sprites[i] != NULL ) {
+	PASS(errctx, akgl_heap_release_sprite(state->sprites[i]));
+	state->sprites[i] = NULL;
+    }
+    if ( state->sheets[i] != NULL ) {
+	/* This is what destroys the texture: see akgl_heap_release_spritesheet. */
+	PASS(errctx, akgl_heap_release_spritesheet(state->sheets[i]));
+	state->sheets[i] = NULL;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Build slot @p i's object graph around a sheet that is already loaded.
+ *
+ * The names are fixed 128-byte buffers, not string literals, because
+ * akgl_sprite_initialize() and akgl_actor_initialize() memcpy a whole
+ * AKGL_*_MAX_NAME_LENGTH from whatever they are handed.
+ */
+static akerr_ErrorContext *build_slot(akbasic_AkglSprites *state, int i, int width, int height)
+{
+    PREPARE_ERROR(errctx);
+    char spritename[AKGL_SPRITE_MAX_NAME_LENGTH];
+    char charname[AKGL_SPRITE_MAX_NAME_LENGTH];
+    char actorname[AKGL_ACTOR_MAX_NAME_LENGTH];
+    float32_t oldx = 0.0f;
+    float32_t oldy = 0.0f;
+    bool oldvisible = false;
+
+    if ( state->actors[i] != NULL ) {
+	oldx = state->actors[i]->x;
+	oldy = state->actors[i]->y;
+	oldvisible = state->actors[i]->visible;
+    }
+
+    memset(spritename, 0, sizeof(spritename));
+    memset(charname, 0, sizeof(charname));
+    memset(actorname, 0, sizeof(actorname));
+    SDL_snprintf(spritename, sizeof(spritename), "akbasic:sprite:%d", i + 1);
+    SDL_snprintf(charname, sizeof(charname), "akbasic:character:%d", i + 1);
+    SDL_snprintf(actorname, sizeof(actorname), "akbasic:actor:%d", i + 1);
+
+    PASS(errctx, akgl_heap_next_sprite(&state->sprites[i]));
+    PASS(errctx, akgl_sprite_initialize(state->sprites[i], spritename, state->sheets[i]));
+    state->sprites[i]->frames = 1;
+    state->sprites[i]->frameids[0] = 0;
+    state->sprites[i]->width = (uint32_t)width;
+    state->sprites[i]->height = (uint32_t)height;
+
+    PASS(errctx, akgl_heap_next_character(&state->characters[i]));
+    PASS(errctx, akgl_character_initialize(state->characters[i], charname));
+    PASS(errctx, akgl_character_sprite_add(state->characters[i], state->sprites[i], 0));
+
+    PASS(errctx, akgl_heap_next_actor(&state->actors[i]));
+    PASS(errctx, akgl_actor_initialize(state->actors[i], actorname));
+    PASS(errctx, akgl_actor_set_character(state->actors[i], charname));
+    state->actors[i]->state = 0;
+    state->actors[i]->actorData = state;
+    state->actors[i]->renderfunc = spr_render_actor;
+    /*
+     * Position and visibility survive a redefinition. SPRSAV changes what a
+     * sprite looks like, not where it is or whether it is on -- a program that
+     * animates by swapping patterns in a loop would otherwise have to re-issue
+     * SPRITE and MOVSPR after every frame.
+     */
+    state->actors[i]->x = oldx;
+    state->actors[i]->y = oldy;
+    state->actors[i]->visible = oldvisible;
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Take ownership of @p surface as slot @p i's image, replacing whatever was there. */
+static akerr_ErrorContext *install_surface(akbasic_AkglSprites *state, int i, SDL_Surface *surface)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Texture *texture = NULL;
+    char sheetname[AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH];
+    int width = 0;
+    int height = 0;
+
+    FAIL_ZERO_RETURN(errctx, (surface != NULL), AKERR_NULLPOINTER, "NULL surface for a sprite");
+    width = surface->w;
+    height = surface->h;
+    texture = SDL_CreateTextureFromSurface(state->renderer->sdl_renderer, surface);
+    FAIL_ZERO_RETURN(errctx, (texture != NULL), AKGL_ERR_SDL,
+		     "Could not upload a sprite pattern: %s", SDL_GetError());
+    /*
+     * Nearest-neighbour. A sprite is a 24x21 bitmap and an expanded one is drawn
+     * at twice the size; smoothing it would turn a pixel into a smudge, which is
+     * not what anybody typing SPRSAV into a BASIC has in mind.
+     */
+    SDL_SetTextureScaleMode(texture, SDL_SCALEMODE_NEAREST);
+
+    PASS(errctx, release_slot(state, i));
+
+    /*
+     * The sheet is assembled rather than initialized: akgl_spritesheet_initialize
+     * loads an image from a path, and this pattern came from bytes or from a
+     * saved region. Everything about it still matches what that function
+     * produces, so akgl_heap_release_spritesheet() tears it down the same way --
+     * which is what makes the texture's ownership one rule rather than two.
+     */
+    PASS(errctx, akgl_heap_next_spritesheet(&state->sheets[i]));
+    memset(state->sheets[i], 0, sizeof(*state->sheets[i]));
+    memset(sheetname, 0, sizeof(sheetname));
+    SDL_snprintf(sheetname, sizeof(sheetname), "akbasic:sheet:%d", i + 1);
+    SDL_strlcpy(state->sheets[i]->name, sheetname, sizeof(state->sheets[i]->name));
+    state->sheets[i]->texture = texture;
+    state->sheets[i]->refcount = 1;
+    SDL_SetPointerProperty(AKGL_REGISTRY_SPRITESHEET, state->sheets[i]->name, state->sheets[i]);
+
+    PASS(errctx, build_slot(state, i, width, height));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Write one unpacked pattern into @p surface, a set bit in @p fg and a clear one in @p bg. */
+static akerr_ErrorContext *paint_pattern(SDL_Surface *surface, const uint8_t *pixels, akbasic_Color fg, akbasic_Color bg)
+{
+    PREPARE_ERROR(errctx);
+    int x = 0;
+    int y = 0;
+
+    for ( y = 0; y < AKBASIC_SPRITE_HEIGHT; y++ ) {
+	for ( x = 0; x < AKBASIC_SPRITE_WIDTH; x++ ) {
+	    akbasic_Color c = (pixels[(y * AKBASIC_SPRITE_WIDTH) + x] != 0 ? fg : bg);
+
+	    FAIL_ZERO_RETURN(errctx,
+			     SDL_WriteSurfacePixel(surface, x, y, c.r, c.g, c.b, c.a),
+			     AKGL_ERR_SDL,
+			     "Could not write sprite pixel %d,%d: %s", x, y, SDL_GetError());
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *spr_define(akbasic_SpriteBackend *self, int n, const uint8_t *pattern, int bytes, akbasic_Color fg, akbasic_Color bg)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    SDL_Surface *surface = NULL;
+    uint8_t pixels[AKBASIC_SPRITE_WIDTH * AKBASIC_SPRITE_HEIGHT];
+    int index = 0;
+
+    PASS(errctx, slot_of(self, n, &state, &index));
+    PASS(errctx, akbasic_sprite_unpack(pattern, bytes, pixels));
+
+    surface = SDL_CreateSurface(AKBASIC_SPRITE_WIDTH, AKBASIC_SPRITE_HEIGHT,
+				SDL_PIXELFORMAT_RGBA32);
+    FAIL_ZERO_RETURN(errctx, (surface != NULL), AKGL_ERR_SDL,
+		     "Could not create a sprite surface: %s", SDL_GetError());
+    ATTEMPT {
+	/*
+	 * The pixel loop is its own function so that it can be reached with a
+	 * single CATCH. Written inline it would need a FAIL inside two nested
+	 * loops inside this ATTEMPT, and the _BREAK forms expand to a C break
+	 * that escapes only the inner loop.
+	 */
+	CATCH(errctx, paint_pattern(surface, pixels, fg, bg));
+	CATCH(errctx, install_surface(state, index, surface));
+    } CLEANUP {
+	SDL_DestroySurface(surface);
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *spr_define_shape(akbasic_SpriteBackend *self, int n, int handle)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    int index = 0;
+
+    PASS(errctx, slot_of(self, n, &state, &index));
+    FAIL_ZERO_RETURN(errctx, (state->graphics != NULL), AKBASIC_ERR_DEVICE,
+		     "SPRSAV from a saved shape needs a graphics backend, and this host supplied none");
+    FAIL_ZERO_RETURN(errctx, (handle >= 0 && handle < state->graphics->shapecount),
+		     AKBASIC_ERR_VALUE,
+		     "Shape handle %d names no saved region", handle);
+    FAIL_ZERO_RETURN(errctx, (state->graphics->shapes[handle] != NULL), AKBASIC_ERR_VALUE,
+		     "Shape handle %d has been released", handle);
+    PASS(errctx, install_surface(state, index, state->graphics->shapes[handle]));
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *spr_define_file(akbasic_SpriteBackend *self, int n, const char *path, const char *root)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    akgl_String *resolved = NULL;
+    int index = 0;
+    bool missing = false;
+
+    PASS(errctx, slot_of(self, n, &state, &index));
+    FAIL_ZERO_RETURN(errctx, (path != NULL && path[0] != '\0'), AKBASIC_ERR_VALUE,
+		     "SPRSAV was given an empty file name");
+
+    PASS(errctx, akgl_heap_next_string(&resolved));
+    ATTEMPT {
+	CATCH(errctx, akgl_string_initialize(resolved, NULL));
+	/*
+	 * The same resolution a sprite document gets for the spritesheet it
+	 * names: the working directory first, then the directory the file doing
+	 * the naming lives in -- here, the directory the BASIC program was
+	 * loaded from. A program stored beside its art therefore works whether
+	 * it was launched from its own directory or from anywhere else.
+	 */
+	CATCH(errctx, akgl_path_relative((char *)(root != NULL ? root : "."),
+					 (char *)path, resolved));
+	CATCH(errctx, release_slot(state, index));
+	CATCH(errctx, akgl_heap_next_spritesheet(&state->sheets[index]));
+	/*
+	 * And the same load. The two frame-size arguments are dead upstream --
+	 * akgl_spritesheet_initialize does not write them -- and a Commodore
+	 * sprite has no frame grid anyway, so the image is one whole frame.
+	 */
+	CATCH(errctx, akgl_spritesheet_initialize(state->sheets[index], 0, 0,
+						  (char *)&resolved->data));
+	FAIL_ZERO_BREAK(errctx, (state->sheets[index]->texture != NULL), AKGL_ERR_SDL,
+			"Loaded %s but it produced no texture", path);
+	SDL_SetTextureScaleMode(state->sheets[index]->texture, SDL_SCALEMODE_NEAREST);
+	/*
+	 * The image's own size, not 24x21. A Commodore sprite is 24x21 because
+	 * that is what the hardware could address; there is no reason to throw
+	 * away art that is not sprite-shaped on a machine with no such limit.
+	 */
+	CATCH(errctx, build_slot(state, index,
+				 state->sheets[index]->texture->w,
+				 state->sheets[index]->texture->h));
+    } CLEANUP {
+	IGNORE(akgl_heap_release_string(resolved));
+    } PROCESS(errctx) {
+    } HANDLE(errctx, ENOENT) {
+	/*
+	 * Recorded rather than raised here. Returning from inside a HANDLE block
+	 * leaves FINISH's bookkeeping undone, so the flag is set and the new
+	 * error is raised below where an ordinary return is safe.
+	 */
+	missing = true;
+    } FINISH(errctx, true);
+    FAIL_NONZERO_RETURN(errctx, missing, AKBASIC_ERR_VALUE, "No such sprite image: %s", path);
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *spr_show(akbasic_SpriteBackend *self, int n, bool visible)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    int index = 0;
+
+    PASS(errctx, slot_of(self, n, &state, &index));
+    if ( state->actors[index] != NULL ) {
+	state->actors[index]->visible = visible;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *spr_move(akbasic_SpriteBackend *self, int n, double x, double y)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    int index = 0;
+
+    PASS(errctx, slot_of(self, n, &state, &index));
+    if ( state->actors[index] != NULL ) {
+	state->actors[index]->x = (float32_t)x;
+	state->actors[index]->y = (float32_t)y;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *spr_configure(akbasic_SpriteBackend *self, int n, akbasic_Color color, bool xexpand, bool yexpand, bool behind)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    SDL_Color sdl = to_sdl(color);
+    int index = 0;
+
+    PASS(errctx, slot_of(self, n, &state, &index));
+    state->xexpand[index] = xexpand;
+    state->yexpand[index] = yexpand;
+    /*
+     * Colour is a texture modulation rather than a repaint: a sprite defined
+     * from a pattern was drawn in the colour SPRSAV was given, and SPRITE's
+     * colour argument tints it. For a sprite loaded from an image that means a
+     * white image takes the colour and a coloured one is shaded by it, which is
+     * what texture modulation does everywhere else.
+     */
+    if ( state->sheets[index] != NULL && state->sheets[index]->texture != NULL ) {
+	SDL_SetTextureColorMod(state->sheets[index]->texture, sdl.r, sdl.g, sdl.b);
+    }
+    /*
+     * Priority is not honoured. A C128 draws a low-priority sprite behind the
+     * bitmap screen; here the text layer and the drawing surface are the same
+     * render target and sprites are composited on top of it every frame, so
+     * there is nothing to go behind. Recorded in TODO.md section 5.
+     */
+    (void)behind;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *spr_shared_colors(akbasic_SpriteBackend *self, akbasic_Color c1, akbasic_Color c2)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+
+    PASS(errctx, state_of(self, &state));
+    /*
+     * Nothing to do yet, and saying so is better than pretending. Multicolour
+     * mode packs two bitmap bits per pixel and selects between the sprite's own
+     * colour and these two shared registers; SPRSAV here takes one bit per pixel,
+     * so there is no second bit to select with. The state is kept by the
+     * interpreter, RSPCOLOR reads it back, and the day a multicolour pattern
+     * format exists this is where it lands.
+     */
+    (void)c1;
+    (void)c2;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *spr_collisions(akbasic_SpriteBackend *self, uint16_t *mask)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    int i = 0;
+    int j = 0;
+
+    PASS(errctx, state_of(self, &state));
+    FAIL_ZERO_RETURN(errctx, (mask != NULL), AKERR_NULLPOINTER, "NULL mask in collisions");
+    *mask = 0;
+
+    /*
+     * Axis-aligned bounding boxes, compared here rather than through
+     * akgl_collide_rectangles(): that function has a documented
+     * corner-containment defect -- it misses a plus-shaped overlap where neither
+     * rectangle contains a corner of the other -- and nothing in libakgl calls
+     * it. Four comparisons are both correct and smaller.
+     *
+     * Box against box, not pixel against pixel. A C128 collides on set pixels,
+     * so two sprites whose boxes touch but whose art does not are reported as
+     * colliding here and would not be there. Recorded in TODO.md section 5.
+     */
+    for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
+	for ( j = i + 1; j < AKBASIC_MAX_SPRITES; j++ ) {
+	    float32_t ax = 0.0f, ay = 0.0f, aw = 0.0f, ah = 0.0f;
+	    float32_t bx = 0.0f, by = 0.0f, bw = 0.0f, bh = 0.0f;
+
+	    if ( state->actors[i] == NULL || state->actors[j] == NULL ) {
+		continue;
+	    }
+	    if ( !state->actors[i]->visible || !state->actors[j]->visible ) {
+		continue;
+	    }
+	    if ( state->sprites[i] == NULL || state->sprites[j] == NULL ) {
+		continue;
+	    }
+	    ax = state->actors[i]->x;
+	    ay = state->actors[i]->y;
+	    aw = (float32_t)state->sprites[i]->width * (state->xexpand[i] ? 2.0f : 1.0f);
+	    ah = (float32_t)state->sprites[i]->height * (state->yexpand[i] ? 2.0f : 1.0f);
+	    bx = state->actors[j]->x;
+	    by = state->actors[j]->y;
+	    bw = (float32_t)state->sprites[j]->width * (state->xexpand[j] ? 2.0f : 1.0f);
+	    bh = (float32_t)state->sprites[j]->height * (state->yexpand[j] ? 2.0f : 1.0f);
+
+	    if ( ax < bx + bw && bx < ax + aw && ay < by + bh && by < ay + ah ) {
+		*mask |= (uint16_t)(1u << i);
+		*mask |= (uint16_t)(1u << j);
+	    }
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_sprite_init_akgl(akbasic_SpriteBackend *obj, akbasic_AkglSprites *state, akgl_RenderBackend *renderer, akbasic_AkglGraphics *graphics)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && state != NULL && renderer != NULL),
+		     AKERR_NULLPOINTER, "NULL argument in sprite_init_akgl");
+    /* Before anything else in libakgl, so every AKGL_ERR_* has a name to print. */
+    PASS(errctx, akgl_error_init());
+
+    memset(state, 0, sizeof(*state));
+    state->renderer = renderer;
+    state->graphics = graphics;
+
+    memset(obj, 0, sizeof(*obj));
+    obj->self		= state;
+    obj->define		= spr_define;
+    obj->define_shape	= spr_define_shape;
+    obj->define_file	= spr_define_file;
+    obj->show		= spr_show;
+    obj->move		= spr_move;
+    obj->configure	= spr_configure;
+    obj->shared_colors	= spr_shared_colors;
+    obj->collisions	= spr_collisions;
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_sprite_akgl_render(akbasic_SpriteBackend *obj)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_AkglSprites *state = NULL;
+    int i = 0;
+
+    PASS(errctx, state_of(obj, &state));
+    for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
+	if ( state->actors[i] == NULL ) {
+	    continue;
+	}
+	/*
+	 * PASS rather than CATCH: this is a loop, and CATCH expands to a break.
+	 * Through the actor's own renderfunc rather than calling spr_render_actor
+	 * directly, so a host that has replaced it gets what it asked for.
+	 */
+	PASS(errctx, state->actors[i]->renderfunc(state->actors[i]));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+void akbasic_sprite_akgl_shutdown(akbasic_SpriteBackend *obj)
+{
+    akbasic_AkglSprites *state = NULL;
+    int i = 0;
+
+    if ( obj == NULL || obj->self == NULL ) {
+	return;
+    }
+    state = (akbasic_AkglSprites *)obj->self;
+    for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
+	IGNORE(release_slot(state, i));
+    }
+}

src/sprite_tables.c

@@ -0,0 +1,78 @@
+/**
+ * @file sprite_tables.c
+ * @brief The sprite state's power-on values, and the pattern bit order.
+ *
+ * The counterpart to src/graphics_tables.c: everything about sprites that is
+ * data rather than behaviour, kept away from the verbs so the verb file is
+ * verbs. Both things here are shared by every backend, which is the point --
+ * the bit order in particular is asserted once here rather than trusted in each
+ * adaptor that has to turn a pattern into pixels.
+ */
+
+#include <string.h>
+
+#include <akerror.h>
+
+#include <akbasic/error.h>
+#include <akbasic/sprite.h>
+
+/**
+ * @brief What SPRCOLOR's two registers hold before a program sets them.
+ *
+ * A C128 powers up with multicolour 1 at grey and multicolour 2 at yellow. They
+ * only matter to a multicolour sprite, so a program that never sets them and
+ * never asks for multicolour never sees them.
+ *
+ *     register  palette  colour
+ *     --------  -------  ------
+ *     1         12       medium grey
+ *     2         8        orange
+ */
+#define SHARED_COLOR_1_DEFAULT	12
+#define SHARED_COLOR_2_DEFAULT	8
+
+/** @brief The palette index a sprite has before SPRITE names one. White. */
+#define SPRITE_COLOR_DEFAULT	2
+
+akerr_ErrorContext *akbasic_sprite_state_init(akbasic_SpriteState *obj)
+{
+    PREPARE_ERROR(errctx);
+    int i = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL sprite state in init");
+    memset(obj, 0, sizeof(*obj));
+    for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
+	obj->sprites[i].colorindex = SPRITE_COLOR_DEFAULT;
+    }
+    obj->sharedcolor1 = SHARED_COLOR_1_DEFAULT;
+    obj->sharedcolor2 = SHARED_COLOR_2_DEFAULT;
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *akbasic_sprite_unpack(const uint8_t *pattern, int bytes, uint8_t *dest)
+{
+    PREPARE_ERROR(errctx);
+    int row = 0;
+    int col = 0;
+
+    FAIL_ZERO_RETURN(errctx, (pattern != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in sprite unpack");
+    FAIL_ZERO_RETURN(errctx, (bytes == AKBASIC_SPRITE_PATTERN_BYTES), AKBASIC_ERR_BOUNDS,
+		     "A sprite pattern is %d bytes, not %d",
+		     AKBASIC_SPRITE_PATTERN_BYTES, bytes);
+
+    /*
+     * Three bytes per row, most significant bit leftmost -- which is to say the
+     * first byte of a row is its left eight pixels, and bit 7 of that byte is
+     * the leftmost pixel of all. That is the order a C128 keeps a sprite block
+     * in and the order a type-in listing's DATA statements are written in, so
+     * getting it backwards would mirror every published sprite.
+     */
+    for ( row = 0; row < AKBASIC_SPRITE_HEIGHT; row++ ) {
+	for ( col = 0; col < AKBASIC_SPRITE_WIDTH; col++ ) {
+	    uint8_t byte = pattern[(row * 3) + (col / 8)];
+	    dest[(row * AKBASIC_SPRITE_WIDTH) + col] = (uint8_t)((byte >> (7 - (col % 8))) & 1);
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}

src/value.c

@@ -25,14 +25,34 @@
  * numeric payload the right operand is carrying" -- is legible, and so there is
  * one place to change when TODO.md section 12 item 5 is fixed.
  */
+/*
+ * Selected on the type, not summed. The reference adds both numeric fields --
+ * `rval.intval + int64(rval.floatval)` -- which happens to give the right answer
+ * only because whichever field is unused is always zero (TODO.md section 6
+ * item 5). Nothing enforces that: a value that ever carries both, or one reused
+ * from the pool without being zeroed, silently computes the sum of the two.
+ */
 static int64_t rval_as_int(akbasic_Value *rval)
 {
-    return rval->intval + (int64_t)rval->floatval;
+    if ( rval->valuetype == AKBASIC_TYPE_FLOAT ) {
+	return (int64_t)rval->floatval;
+    }
+    if ( rval->valuetype == AKBASIC_TYPE_BOOLEAN ) {
+	return rval->boolvalue;
+    }
+    return rval->intval;
 }
 
+/** @brief The float counterpart of rval_as_int(); same reasoning. */
 static double rval_as_float(akbasic_Value *rval)
 {
-    return rval->floatval + (double)rval->intval;
+    if ( rval->valuetype == AKBASIC_TYPE_FLOAT ) {
+	return rval->floatval;
+    }
+    if ( rval->valuetype == AKBASIC_TYPE_BOOLEAN ) {
+	return (double)rval->boolvalue;
+    }
+    return (double)rval->intval;
 }
 
 /* Copy a string into a value's inline buffer. Truncation is an error. */
@@ -173,6 +193,35 @@ bool akbasic_value_is_true(akbasic_Value *self)
     return (self->boolvalue == AKBASIC_TRUE);
 }
 
+bool akbasic_value_is_truthy(akbasic_Value *self)
+{
+    if ( self == NULL ) {
+	return false;
+    }
+    /*
+     * Nonzero is true, which is Commodore's rule rather than a convenience.
+     * BASIC 7.0 has no separate boolean type: a comparison yields -1 or 0, `AND`
+     * and `OR` are the bitwise operators, and `IF A THEN` is legal for any
+     * numeric A. Testing only for the boolean type would make `IF A# THEN` and
+     * `IF A = 1 OR B = 2 THEN` -- whose OR yields an integer -- both silently
+     * false.
+     *
+     * A string is never true. A C128 raises a type mismatch instead; that is a
+     * stricter answer this interpreter could adopt later, and false is the
+     * conservative one meanwhile.
+     */
+    switch ( self->valuetype ) {
+    case AKBASIC_TYPE_BOOLEAN:
+	return (self->boolvalue != 0);
+    case AKBASIC_TYPE_INTEGER:
+	return (self->intval != 0);
+    case AKBASIC_TYPE_FLOAT:
+	return (self->floatval != 0.0);
+    default:
+	return false;
+    }
+}
+
 /* Shared prologue for the unary operators: validate, clone into scratch. */
 static akerr_ErrorContext *unary_prologue(akbasic_Value *self, akbasic_Value *scratch, akbasic_Value **dest)
 {
@@ -200,6 +249,31 @@ static akerr_ErrorContext *binary_prologue(akbasic_Value *self, akbasic_Value *r
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief The integer a bitwise operator should use for @p value.
+ *
+ * BOOLEAN counts as an integer here, and that is what makes `AND` and `OR`
+ * double as logical operators. Commodore BASIC has no separate logical pair: it
+ * represents true as -1, every bit set, precisely so that `A = 1 AND B = 2`
+ * works out bit by bit and lands on -1 or 0. Refusing a boolean operand would
+ * make the commonest conditional in the language a type error.
+ */
+static bool bitwise_operand(akbasic_Value *value, int64_t *dest)
+{
+    if ( value == NULL ) {
+	return false;
+    }
+    if ( value->valuetype == AKBASIC_TYPE_INTEGER ) {
+	*dest = value->intval;
+	return true;
+    }
+    if ( value->valuetype == AKBASIC_TYPE_BOOLEAN ) {
+	*dest = value->boolvalue;
+	return true;
+    }
+    return false;
+}
+
 akerr_ErrorContext *akbasic_value_invert(akbasic_Value *self, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
@@ -216,12 +290,21 @@ akerr_ErrorContext *akbasic_value_invert(akbasic_Value *self, akbasic_Value *scr
 akerr_ErrorContext *akbasic_value_bitwise_not(akbasic_Value *self, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int64_t a = 0;
 
     FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL value in bitwise not");
-    FAIL_ZERO_RETURN(errctx, (self->valuetype == AKBASIC_TYPE_INTEGER),
+    FAIL_ZERO_RETURN(errctx, bitwise_operand(self, &a), AKBASIC_ERR_TYPE,
-		     AKBASIC_ERR_TYPE, "Cannot only perform bitwise operations on integers");
+		     "Can only perform bitwise operations on integers and truth values");
     PASS(errctx, unary_prologue(self, scratch, dest));
-    (*dest)->intval = ~(self->intval);
+    /*
+     * A truth value inverts to a truth value. On a C128 true is -1 -- every bit
+     * set -- so `NOT` of it is 0 and `NOT` of 0 is -1 either way you compute it;
+     * carrying the type through is what keeps `IF NOT (A = 9) THEN` reading as a
+     * condition rather than as an integer that happens to be nonzero.
+     */
+    (*dest)->valuetype = self->valuetype;
+    (*dest)->intval = ~a;
+    (*dest)->boolvalue = ~a;
     SUCCEED_RETURN(errctx);
 }
 
@@ -261,40 +344,54 @@ akerr_ErrorContext *akbasic_value_shift_right(akbasic_Value *self, int64_t bits,
 akerr_ErrorContext *akbasic_value_bitwise_and(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int64_t a = 0;
+    int64_t b = 0;
 
     FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL value in bitwise and");
     FAIL_ZERO_RETURN(errctx, (rval != NULL), AKERR_NULLPOINTER, "nil rval");
-    FAIL_ZERO_RETURN(errctx, (self->valuetype == AKBASIC_TYPE_INTEGER),
+    FAIL_ZERO_RETURN(errctx, (bitwise_operand(self, &a) && bitwise_operand(rval, &b)),
-		     AKBASIC_ERR_TYPE, "Cannot perform bitwise operations on string or float");
+		     AKBASIC_ERR_TYPE,
+		     "Can only perform bitwise operations on integers and truth values");
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
-    (*dest)->intval = self->intval & rval->intval;
+    (*dest)->valuetype = AKBASIC_TYPE_INTEGER;
+    (*dest)->intval = a & b;
+    (*dest)->boolvalue = (*dest)->intval;
     SUCCEED_RETURN(errctx);
 }
 
 akerr_ErrorContext *akbasic_value_bitwise_or(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int64_t a = 0;
+    int64_t b = 0;
 
     FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL value in bitwise or");
     FAIL_ZERO_RETURN(errctx, (rval != NULL), AKERR_NULLPOINTER, "nil rval");
-    FAIL_ZERO_RETURN(errctx, (self->valuetype == AKBASIC_TYPE_INTEGER),
+    FAIL_ZERO_RETURN(errctx, (bitwise_operand(self, &a) && bitwise_operand(rval, &b)),
-		     AKBASIC_ERR_TYPE, "Can only perform bitwise operations on integers");
+		     AKBASIC_ERR_TYPE,
+		     "Can only perform bitwise operations on integers and truth values");
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
-    (*dest)->intval = self->intval | rval->intval;
+    (*dest)->valuetype = AKBASIC_TYPE_INTEGER;
+    (*dest)->intval = a | b;
+    (*dest)->boolvalue = (*dest)->intval;
     SUCCEED_RETURN(errctx);
 }
 
 akerr_ErrorContext *akbasic_value_bitwise_xor(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int64_t a = 0;
+    int64_t b = 0;
 
     FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL value in bitwise xor");
     FAIL_ZERO_RETURN(errctx, (rval != NULL), AKERR_NULLPOINTER, "nil rval");
-    FAIL_ZERO_RETURN(errctx,
+    FAIL_ZERO_RETURN(errctx, (bitwise_operand(self, &a) && bitwise_operand(rval, &b)),
-		     (self->valuetype == AKBASIC_TYPE_INTEGER && rval->valuetype == AKBASIC_TYPE_INTEGER),
+		     AKBASIC_ERR_TYPE,
-		     AKBASIC_ERR_TYPE, "Can only perform bitwise operations on integers");
+		     "Can only perform bitwise operations on integers and truth values");
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
-    (*dest)->intval = self->intval ^ rval->intval;
+    (*dest)->valuetype = AKBASIC_TYPE_INTEGER;
+    (*dest)->intval = a ^ b;
+    (*dest)->boolvalue = (*dest)->intval;
     SUCCEED_RETURN(errctx);
 }
 
@@ -310,17 +407,18 @@ akerr_ErrorContext *akbasic_value_math_plus(akbasic_Value *self, akbasic_Value *
     FAIL_ZERO_RETURN(errctx, (dest != NULL), AKERR_NULLPOINTER, "NULL destination in math plus");
 
     /*
-     * The asymmetry with every other operator is deliberate and load-bearing:
+     * Always a clone, like every other operator. The reference mutates `self` in
-     * mathPlus mutates self in place when self is mutable, and CommandNEXT's
+     * place when it happens to be mutable, so `A# + 1` modified `A#` whenever
-     * loop increment relies on that to advance the loop variable. TODO.md
+     * the left operand came from a variable rather than from a literal --
-     * section 12 item 4.
+     * TODO.md section 6 item 4, and the highest-blast-radius entry on that list.
+     *
+     * It was load-bearing: NEXT advanced its counter by calling this and letting
+     * the mutation land in the variable. NEXT now writes the result back itself,
+     * which is what made this safe to change. tests/for_next.c is the coverage
+     * that had to exist first.
      */
-    if ( !self->mutable_ ) {
     PASS(errctx, akbasic_value_clone(self, scratch));
     out = scratch;
-    } else {
-	out = self;
-    }
 
     if ( self->valuetype == AKBASIC_TYPE_INTEGER ) {
 	out->intval = self->intval + rval_as_int(rval);

src/verbs.c

@@ -35,25 +35,48 @@ static const akbasic_Verb VERBS[] = {
     /* name          token type                        arity  parse handler          exec handler          */
     { "ABS",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_abs },
     { "AND",          AKBASIC_TOK_AND,                  -1, NULL,                  NULL },
+    { "APPEND",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_append },
     { "ATN",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_atn },
     { "AUTO",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_auto },
+    { "BACKUP",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_backup },
+    { "BEGIN",        AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_begin },
+    { "BEND",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_bend },
+    { "BLOAD",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_bload },
+    { "BOOT",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_boot },
     { "BOX",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_box },
+    { "BSAVE",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_bsave },
+    { "BUMP",         AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_bump },
+    { "CATALOG",      AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, akbasic_parse_optional_arglist, akbasic_cmd_directory },
+    { "CHAR",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_char },
     { "CHR",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_chr },
     { "CIRCLE",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_circle },
     { "CLR",          AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_clr },
+    { "COLLECT",      AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_collect },
+    { "COLLISION",    AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_collision },
     { "COLOR",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_color },
+    { "CONCAT",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_concat },
     { "CONT",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_cont },
+    { "COPY",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_copy },
     { "COS",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_cos },
     { "DATA",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_data,    akbasic_cmd_data },
+    { "DCLEAR",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_dclear },
+    { "DCLOSE",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_dclose },
     { "DEF",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_def,     akbasic_cmd_def },
     { "DELETE",       AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_delete },
     { "DIM",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_dim,     akbasic_cmd_dim },
+    { "DIRECTORY",    AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, akbasic_parse_optional_arglist, akbasic_cmd_directory },
     { "DLOAD",        AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_dload },
+    { "DO",           AKBASIC_TOK_COMMAND,              -1, akbasic_parse_do,      akbasic_cmd_do },
+    { "DOPEN",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_dopen },
     { "DRAW",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_draw,    akbasic_cmd_draw },
     { "DSAVE",        AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_dsave },
+    { "DVERIFY",      AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, akbasic_parse_arglist, akbasic_cmd_dverify },
     { "ELSE",         AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
+    { "END",          AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_end },
     { "ENVELOPE",     AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_envelope },
+    { "ERR",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_err },
     { "EXIT",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_exit },
+    { "FETCH",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_fetch },
     { "FILTER",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_filter },
     { "FOR",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_for,     akbasic_cmd_for },
     { "GET",          AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_get },
@@ -62,23 +85,37 @@ static const akbasic_Verb VERBS[] = {
     { "GOTO",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_goto },
     { "GRAPHIC",      AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_graphic },
     { "GSHAPE",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_gshape },
+    { "HEADER",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_header },
     { "HELP",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_help },
     { "HEX",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_hex },
     { "IF",           AKBASIC_TOK_COMMAND,              -1, akbasic_parse_if,      akbasic_cmd_if },
     { "INPUT",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_input,   akbasic_cmd_input },
+    /*
+     * `INPUT#` and `PRINT#` are never scanned as verb names -- the scanner reads
+     * a `#` as a type suffix and refuses a verb carrying one -- so these rows are
+     * reached only from akbasic_parse_input() and akbasic_parse_print(), which
+     * build a leaf with the name directly. They still have to be here, and in
+     * order, because dispatch is a bsearch on the leaf's name.
+     */
+    { "INPUT#",       AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_input_channel },
     { "INSTR",        AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_instr },
+    { "KEY",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_key },
     { "LABEL",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_label,   akbasic_cmd_label },
     { "LEFT",         AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_left },
     { "LEN",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_len },
     { "LET",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_let,     akbasic_cmd_let },
     { "LIST",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_list },
+    { "LOAD",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_dload },
     { "LOCATE",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_locate },
     { "LOG",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_log },
+    { "LOOP",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_loop,    akbasic_cmd_loop },
     { "MID",          AKBASIC_TOK_FUNCTION,              3, NULL,                  akbasic_fn_mid },
     { "MOD",          AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_mod },
+    { "MOVSPR",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_movspr,  akbasic_cmd_movspr },
     { "NEW",          AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_new },
     { "NEXT",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_next },
     { "NOT",          AKBASIC_TOK_NOT,                  -1, NULL,                  NULL },
+    { "ON",           AKBASIC_TOK_COMMAND,              -1, akbasic_parse_on,      akbasic_cmd_on },
     { "OR",           AKBASIC_TOK_OR,                   -1, NULL,                  NULL },
     { "PAINT",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_paint },
     { "PEEK",         AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_peek },
@@ -86,35 +123,61 @@ static const akbasic_Verb VERBS[] = {
     { "POINTER",      AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_pointer },
     { "POINTERVAR",   AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_pointervar },
     { "POKE",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_poke,    akbasic_cmd_poke },
-    { "PRINT",        AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_print },
+    { "PRINT",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_print,   akbasic_cmd_print },
+    { "PRINT#",       AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_print_channel },
+    { "PUDEF",        AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_pudef },
     { "QUIT",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_quit },
     { "RAD",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_rad },
     { "READ",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_read,    akbasic_cmd_read },
+    { "RECORD",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_record },
     { "REM",          AKBASIC_TOK_REM,                  -1, NULL,                  NULL },
+    { "RENAME",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_rename },
+    { "RENUMBER",     AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, akbasic_parse_optional_arglist, akbasic_cmd_renumber },
+    { "RESTORE",      AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_restore },
+    { "RESUME",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_resume,  akbasic_cmd_resume },
     { "RETURN",       AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_return },
     { "RIGHT",        AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_right },
+    { "RSPCOLOR",     AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_rspcolor },
+    { "RSPPOS",       AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsppos },
+    { "RSPRITE",      AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsprite },
     { "RUN",          AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_run },
+    { "SAVE",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_dsave },
     { "SCALE",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_scale },
     { "SCNCLR",       AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_scnclr },
+    { "SCRATCH",      AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_scratch },
     { "SGN",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_sgn },
     { "SHL",          AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_shl },
     { "SHR",          AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_shr },
     { "SIN",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_sin },
+    { "SLEEP",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sleep },
     { "SOUND",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sound },
     { "SPC",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_spc },
+    { "SPRCOLOR",     AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sprcolor },
+    { "SPRITE",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sprite },
+    { "SPRSAV",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sprsav },
     { "SSHAPE",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sshape },
+    { "STASH",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_stash },
     { "STEP",         AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
     { "STOP",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_stop },
     { "STR",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_str },
     { "SWAP",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_swap },
+    { "SYS",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_sys },
     { "TAN",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_tan },
     { "TEMPO",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_tempo },
     { "THEN",         AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
     { "TO",           AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
+    { "TRAP",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_trap },
     { "TROFF",        AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_troff },
     { "TRON",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_tron },
+    { "UNTIL",        AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
+    { "USING",        AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
     { "VAL",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_val },
+    { "VERIFY",       AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, akbasic_parse_arglist, akbasic_cmd_dverify },
     { "VOL",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_vol },
+    { "WAIT",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_wait },
+    { "WHILE",        AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
+    { "WIDTH",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_width },
+    { "WINDOW",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_window },
     { "XOR",          AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_xor },
 };
 

src/verbs.h

@@ -23,16 +23,85 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_dim(struct akbasic_Parser *pars
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_for(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_if(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_input(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_optional_arglist(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_label(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_let(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_poke(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_do(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_loop(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_resume(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_on(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_movspr(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_print(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_read(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 
+/* Group F disk verbs -- src/runtime_disk.c */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_append(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_backup(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_bload(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_boot(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_bsave(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_collect(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_concat(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_copy(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_dclear(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_dclose(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_directory(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_dopen(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_input_channel(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_print_channel(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_dverify(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_header(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_record(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_rename(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_scratch(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+
+/* Group J machine verbs -- src/runtime_machine.c */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_fetch(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_stash(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sys(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+
+/* Group E console verbs -- src/runtime_console.c */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_key(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sleep(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_wait(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_window(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+
+/* Group D format verbs -- src/runtime_format.c */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_char(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_pudef(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_width(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+
+/* Group C error verbs -- src/runtime_trap.c */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_resume(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_trap(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_err(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+
+/* Group A structure verbs -- src/runtime_structure.c */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_begin(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_bend(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_do(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_end(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_loop(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_on(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+
+/* Group H sprite verbs and readbacks -- src/runtime_sprite.c */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_collision(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_movspr(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sprcolor(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sprite(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_sprsav(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_bump(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rspcolor(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rsppos(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rsprite(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+
 /* Verb handlers -- src/runtime_housekeeping.c */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_clr(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_cont(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_help(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_new(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_renumber(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_swap(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_troff(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_tron(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
@@ -59,6 +128,7 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_poke(struct akbasic_Runtime *obj,
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_print(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_quit(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_read(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_restore(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_return(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_run(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_stop(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);

tests/akgl_backends.c

@@ -32,11 +32,14 @@
  * deps/libakgl/tests/draw.c does.
  */
 #include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/registry.h>
 #include <akgl/renderer.h>
 #include <akgl/text.h>
 
 #include <akbasic/akgl.h>
 #include <akbasic/error.h>
+#include <akbasic/sprite.h>
 #include <akbasic/runtime.h>
 #include <akbasic/sink.h>
 
@@ -54,6 +57,8 @@ static akbasic_TextSink AKGLSINK;
 static akbasic_GraphicsBackend GRAPHICS;
 static akbasic_AkglGraphics GRAPHICSSTATE;
 static akbasic_InputBackend INPUT;
+static akbasic_SpriteBackend SPRITES;
+static akbasic_AkglSprites SPRITESSTATE;
 static TTF_Font *font = NULL;
 static char OUTPUT[8192];
 static FILE *OUT = NULL;
@@ -100,7 +105,8 @@ static akerr_ErrorContext AKERR_NOIGNORE *start_runtime(const char *source)
     PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, OUT, NULL));
     PASS(errctx, akbasic_runtime_init(&RUNTIME, &SINK));
     PASS(errctx, akbasic_graphics_init_akgl(&GRAPHICS, &GRAPHICSSTATE, renderer));
-    PASS(errctx, akbasic_runtime_set_devices(&RUNTIME, &GRAPHICS, NULL, NULL));
+    PASS(errctx, akbasic_sprite_init_akgl(&SPRITES, &SPRITESSTATE, renderer, &GRAPHICSSTATE));
+    PASS(errctx, akbasic_runtime_set_devices(&RUNTIME, &GRAPHICS, NULL, NULL, &SPRITES));
     PASS(errctx, akbasic_runtime_load(&RUNTIME, source));
     PASS(errctx, akbasic_runtime_start(&RUNTIME, AKBASIC_MODE_RUN));
     PASS(errctx, akbasic_runtime_run(&RUNTIME, 0));
@@ -335,6 +341,130 @@ static akerr_ErrorContext AKERR_NOIGNORE *test_input_backend(void)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief A sprite loaded from an image file lands on the target where MOVSPR put it.
+ *
+ * The one assertion in this repository that exercises the whole file path:
+ * a BASIC string that is not an SSHAPE handle, resolved by akgl_path_relative()
+ * against the working directory, decoded by SDL_image inside
+ * akgl_spritesheet_initialize(), and blitted through the actor's renderfunc.
+ *
+ * The fixture is 8x8 rather than 24x21 on purpose -- a sprite from a file takes
+ * the image's own size, and an assertion at (43, 33) rather than (40, 30) is
+ * what says the size came from the image rather than from a constant.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_sprite_from_file(void)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Surface *shot = NULL;
+
+    PASS(errctx, clear_target());
+    PASS(errctx, start_runtime("10 SPRSAV \"assets/sprite8x8.png\", 1\n"
+			       "20 SPRITE 1, 1\n"
+			       "30 MOVSPR 1, 40, 30\n"));
+    TEST_REQUIRE_STR(OUTPUT, "");
+    PASS(errctx, akbasic_sprite_akgl_render(&SPRITES));
+
+    shot = SDL_RenderReadPixels(renderer->sdl_renderer, NULL);
+    TEST_REQUIRE(shot != NULL, "could not read the render target back");
+    /*
+     * Magenta, not white: SPRITE's colour argument modulates the texture and
+     * this program never gave one, so the image's own colour comes through.
+     */
+    TEST_REQUIRE(pixel_is(shot, 43, 33, 0xff, 0x00, 0xff),
+		 "the loaded sprite should be drawn at MOVSPR's coordinate");
+    TEST_REQUIRE(pixel_is(shot, 47, 37, 0xff, 0x00, 0xff),
+		 "the whole 8x8 image should have been drawn, not one pixel of it");
+    TEST_REQUIRE(!pixel_is(shot, 49, 39, 0xff, 0x00, 0xff),
+		 "an 8x8 sprite should stop after eight pixels");
+    SDL_DestroySurface(shot);
+
+    /* A path that names nothing is the program's mistake, and is reported. */
+    stop_runtime();
+    PASS(errctx, start_runtime("10 SPRSAV \"assets/nosuchfile.png\", 1\n"));
+    TEST_REQUIRE(strstr(OUTPUT, "No such sprite image") != NULL,
+		 "a missing image should be reported by name, got \"%s\"", OUTPUT);
+    stop_runtime();
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief A sprite defined from 63 pattern bytes reaches real pixels, in its colour.
+ *
+ * The DATA-driven path a type-in listing uses, end to end: an integer array, the
+ * bit unpacking, a surface built a pixel at a time, and a texture. The pattern
+ * is one set bit in the top-left corner, so what is asserted is both that the
+ * pixel is lit *and* that its neighbour is not -- which is what catches a bit
+ * order that came through reversed.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_sprite_from_pattern(void)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Surface *shot = NULL;
+
+    PASS(errctx, clear_target());
+    PASS(errctx, start_runtime("10 DIM P#(63)\n"
+			       "20 P#(0) = 128\n"
+			       "30 SPRSAV P#, 1\n"
+			       "40 SPRITE 1, 1, 6\n"
+			       "50 MOVSPR 1, 20, 20\n"));
+    TEST_REQUIRE_STR(OUTPUT, "");
+    PASS(errctx, akbasic_sprite_akgl_render(&SPRITES));
+
+    shot = SDL_RenderReadPixels(renderer->sdl_renderer, NULL);
+    TEST_REQUIRE(shot != NULL, "could not read the render target back");
+    /* Palette index 6 is green: 0x55, 0xa0, 0x49. */
+    TEST_REQUIRE(pixel_is(shot, 20, 20, 0x55, 0xa0, 0x49),
+		 "the pattern's one set bit should be the sprite's top-left pixel");
+    TEST_REQUIRE(!pixel_is(shot, 21, 20, 0x55, 0xa0, 0x49),
+		 "only one bit was set, so only one pixel should be lit");
+    TEST_REQUIRE(!pixel_is(shot, 43, 20, 0x55, 0xa0, 0x49),
+		 "a reversed bit order would have lit the far end of the row");
+    SDL_DestroySurface(shot);
+    stop_runtime();
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief A region SSHAPE saved becomes a sprite, which is the shared-format claim.
+ *
+ * The C128 documents SPRSAV's string as the SSHAPE data format at a fixed 24x21,
+ * so reusing the shape pool here is faithful rather than a shortcut -- and this
+ * is what says the handle actually survives the trip through a BASIC string and
+ * into the sprite device.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_sprite_from_shape(void)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Surface *shot = NULL;
+
+    PASS(errctx, clear_target());
+    PASS(errctx, start_runtime("10 COLOR 1, 3\n"
+			       "20 BOX 1, 0, 0, 10, 10\n"
+			       "30 SSHAPE A$, 0, 0, 10, 10\n"
+			       "40 SPRSAV A$, 1\n"
+			       "50 SPRITE 1, 1\n"
+			       "60 MOVSPR 1, 60, 60\n"));
+    TEST_REQUIRE_STR(OUTPUT, "");
+    PASS(errctx, akbasic_sprite_akgl_render(&SPRITES));
+
+    shot = SDL_RenderReadPixels(renderer->sdl_renderer, NULL);
+    TEST_REQUIRE(shot != NULL, "could not read the render target back");
+    /*
+     * Palette index 3 is red, which is what the BOX was outlined in. The corner
+     * of the box is the (0,0) pixel of the saved region, so it lands exactly
+     * where MOVSPR put the sprite -- and its interior does not, which is what
+     * says a region was copied rather than a rectangle drawn.
+     */
+    TEST_REQUIRE(pixel_is(shot, 60, 60, 0x88, 0x39, 0x32),
+		 "the saved region's corner should have been drawn as a sprite");
+    TEST_REQUIRE(!pixel_is(shot, 65, 65, 0x88, 0x39, 0x32),
+		 "the region was an outline, so its middle should not be red");
+    SDL_DestroySurface(shot);
+    stop_runtime();
+    SUCCEED_RETURN(errctx);
+}
+
 int main(void)
 {
     PREPARE_ERROR(errctx);
@@ -366,6 +496,20 @@ int main(void)
 	 */
 	CATCH(errctx, akgl_render_bind2d(renderer));
 
+	/*
+	 * The three things akgl_game_init() would have done and this file, being
+	 * a host that deliberately never calls it, has to do itself: the object
+	 * pools, the name registries, and a camera for akgl_actor_render() to
+	 * dereference. src/frontend_akgl.c does the same, and says why at length.
+	 */
+	CATCH(errctx, akgl_heap_init());
+	CATCH(errctx, akgl_registry_init());
+	camera = &_akgl_camera;
+	camera->x = 0.0f;
+	camera->y = 0.0f;
+	camera->w = (float)TARGET_SIZE;
+	camera->h = (float)TARGET_SIZE;
+
 	/*
 	 * libakgl's own monospaced fixture, borrowed rather than copied. Being
 	 * monospaced is what makes a character grid meaningful to assert on.
@@ -381,6 +525,9 @@ int main(void)
 	CATCH(errctx, test_sink_grid_and_wrap());
 	CATCH(errctx, test_sink_renders());
 	CATCH(errctx, test_input_backend());
+	CATCH(errctx, test_sprite_from_file());
+	CATCH(errctx, test_sprite_from_pattern());
+	CATCH(errctx, test_sprite_from_shape());
     } CLEANUP {
 	if ( font != NULL ) {
 	    TTF_CloseFont(font);

tests/akgl_frontend.c

@@ -28,9 +28,16 @@
 
 #include <akerror.h>
 
+#include <akgl/actor.h>
+#include <akgl/character.h>
 #include <akgl/controller.h>
 #include <akgl/draw.h>
 #include <akgl/error.h>
+/* game.h for the `camera` global, which akgl_actor_render() reads. */
+#include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/registry.h>
+#include <akgl/sprite.h>
 
 #include <akbasic/error.h>
 #include <akbasic/frontend.h>
@@ -832,6 +839,128 @@ static akerr_ErrorContext AKERR_NOIGNORE *test_repl_session(void)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief The frontend leaves libakgl able to draw an actor, which is what a sprite is.
+ *
+ * Three things the host owes libakgl and that akgl_game_init() would normally
+ * have done -- the object pools, the name registries, and the camera. Nothing in
+ * the interpreter needed any of them until sprites, because text and the drawing
+ * primitives go straight at the renderer; an actor goes through all three.
+ *
+ * Asserted by building one actor by hand and drawing it, rather than by reading
+ * the globals back. Without akgl_registry_init() the actor cannot be named and
+ * akgl_actor_initialize raises AKERR_KEY; without akgl_heap_init() there is no
+ * pool to take it from; without a camera akgl_actor_render() dereferences NULL
+ * and the test does not report a failure so much as stop existing.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_host_can_draw_an_actor(void)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Surface *pattern = NULL;
+    SDL_Surface *shot = NULL;
+    SDL_Texture *texture = NULL;
+    akgl_SpriteSheet *sheet = NULL;
+    akgl_Sprite *sprite = NULL;
+    akgl_Character *basechar = NULL;
+    akgl_Actor *actor = NULL;
+    /*
+     * 128 bytes each, not string literals: akgl_sprite_initialize() and
+     * akgl_actor_initialize() memcpy a fixed AKGL_*_MAX_NAME_LENGTH from what
+     * they are handed, so a shorter buffer is read past its end.
+     */
+    char sheetname[AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH];
+    char spritename[AKGL_SPRITE_MAX_NAME_LENGTH];
+    char charname[AKGL_SPRITE_MAX_NAME_LENGTH];
+    char actorname[AKGL_ACTOR_MAX_NAME_LENGTH];
+
+    PASS(errctx, start_frontend(NULL));
+
+    TEST_REQUIRE(camera != NULL, "the frontend should have pointed the camera somewhere");
+    TEST_REQUIRE_INT((int)camera->w, WINDOW_W);
+    TEST_REQUIRE_INT((int)camera->h, WINDOW_H);
+    TEST_REQUIRE(AKGL_REGISTRY_ACTOR != 0, "the frontend should have created the registries");
+
+    memset(sheetname, 0, sizeof(sheetname));
+    memset(spritename, 0, sizeof(spritename));
+    memset(charname, 0, sizeof(charname));
+    memset(actorname, 0, sizeof(actorname));
+    SDL_strlcpy(sheetname, "akbasic:test:sheet", sizeof(sheetname));
+    SDL_strlcpy(spritename, "akbasic:test:sprite", sizeof(spritename));
+    SDL_strlcpy(charname, "akbasic:test:character", sizeof(charname));
+    SDL_strlcpy(actorname, "akbasic:test:actor", sizeof(actorname));
+
+    /* A solid 8x8 white square, built in memory rather than loaded from a file. */
+    pattern = SDL_CreateSurface(8, 8, SDL_PIXELFORMAT_RGBA32);
+    TEST_REQUIRE(pattern != NULL, "could not create the pattern surface: %s", SDL_GetError());
+    TEST_REQUIRE(SDL_FillSurfaceRect(pattern, NULL,
+				     SDL_MapSurfaceRGBA(pattern, 0xff, 0xff, 0xff, 0xff)),
+		 "could not fill the pattern surface: %s", SDL_GetError());
+    texture = SDL_CreateTextureFromSurface(FRONTEND.renderer->sdl_renderer, pattern);
+    SDL_DestroySurface(pattern);
+    TEST_REQUIRE(texture != NULL, "could not upload the pattern: %s", SDL_GetError());
+
+    /*
+     * The sheet is assembled rather than initialized: akgl_spritesheet_initialize
+     * loads an image from a path, and there is no file here. Everything below it
+     * is the ordinary API.
+     */
+    PASS(errctx, akgl_heap_next_spritesheet(&sheet));
+    memset(sheet, 0, sizeof(*sheet));
+    sheet->texture = texture;
+    SDL_strlcpy(sheet->name, sheetname, sizeof(sheet->name));
+    sheet->refcount = 1;
+
+    PASS(errctx, akgl_heap_next_sprite(&sprite));
+    PASS(errctx, akgl_sprite_initialize(sprite, spritename, sheet));
+    sprite->frames = 1;
+    sprite->frameids[0] = 0;
+    sprite->width = 8;
+    sprite->height = 8;
+
+    PASS(errctx, akgl_heap_next_character(&basechar));
+    PASS(errctx, akgl_character_initialize(basechar, charname));
+    PASS(errctx, akgl_character_sprite_add(basechar, sprite, 0));
+
+    PASS(errctx, akgl_heap_next_actor(&actor));
+    PASS(errctx, akgl_actor_initialize(actor, actorname));
+    PASS(errctx, akgl_actor_set_character(actor, charname));
+    actor->state = 0;
+    actor->visible = true;
+    actor->x = 40.0f;
+    actor->y = 24.0f;
+
+    /* The text layer paints every cell it owns, so draw the actor over it. */
+    PASS(errctx, akbasic_sink_akgl_render(&FRONTEND.akglsink));
+    PASS(errctx, akgl_actor_render(actor));
+
+    shot = SDL_RenderReadPixels(FRONTEND.renderer->sdl_renderer, NULL);
+    TEST_REQUIRE(shot != NULL, "could not read the render target back");
+    TEST_REQUIRE(anything_drawn(shot, 42, 26, 2, 2),
+		 "the actor should have been drawn at its own coordinates");
+    SDL_DestroySurface(shot);
+
+    stop_frontend();
+
+    /*
+     * And the pools start over. akgl_heap_init() is not needed to make the
+     * *first* frontend work -- the pool arrays are file-scope and start zeroed --
+     * so the only thing that shows it ran is a second frontend handing back the
+     * slot the first one was still holding. Without it the actor above survives
+     * SDL_Quit with a live refcount, pointing at a texture that no longer exists,
+     * and the next program's sprites are allocated around the corpse.
+     */
+    {
+	akgl_Actor *reused = NULL;
+
+	PASS(errctx, start_frontend(NULL));
+	PASS(errctx, akgl_heap_next_actor(&reused));
+	TEST_REQUIRE(reused == actor,
+		     "a new frontend should hand back the released pool slot, not the one after it");
+	stop_frontend();
+    }
+    SUCCEED_RETURN(errctx);
+}
+
 /** @brief Every entry point validates its pointers before touching SDL. */
 static akerr_ErrorContext AKERR_NOIGNORE *test_arguments_refused(void)
 {
@@ -880,6 +1009,7 @@ int main(void)
 	CATCH(errctx, test_block_cursor_blinks());
 	CATCH(errctx, test_frame_owns_every_pixel());
 	CATCH(errctx, test_repl_session());
+	CATCH(errctx, test_host_can_draw_an_actor());
     } CLEANUP {
 	stop_frontend();
     } PROCESS(errctx) {

tests/assets/README.md

@@ -0,0 +1,22 @@
+# tests/assets
+
+Fixtures for the tests that need a real file on disk. Only one so far.
+
+## sprite8x8.png
+
+An 8x8 solid magenta square, 76 bytes, generated rather than drawn -- it is a
+PNG header, one IDAT of a single repeated RGBA pixel, and an IEND.
+
+It exists for one assertion in `tests/akgl_backends.c`: that
+`SPRSAV "assets/sprite8x8.png", 1` reaches SDL_image, decodes, and lands on the
+render target as magenta pixels at the coordinate `MOVSPR` put it. Magenta
+because nothing else in that test file draws in it, so a stray pixel cannot be
+mistaken for this one.
+
+Eight by eight rather than a Commodore sprite's 24x21, deliberately: a sprite
+loaded from a file takes the image's own size, and a fixture that happened to be
+24x21 could not tell that apart from a hardcoded constant.
+
+libakgl's own fixtures under `deps/libakgl/tests/assets/` are borrowed where they
+fit -- the monospaced font is used from there rather than copied. There was no
+image small enough to be worth borrowing: the smallest is a 576x384 spritesheet.

tests/audio_verbs.c

@@ -31,7 +31,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
     PASS(errctx, harness_start(NULL));
     mock_devices_init();
     PASS(errctx, akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS,
-					     &MOCK_AUDIO, &MOCK_INPUT));
+					     &MOCK_AUDIO, &MOCK_INPUT, NULL));
     PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
     PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
     PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
@@ -176,7 +176,7 @@ static void test_sound(void)
     mock_devices_init();
     MOCK_AUDIO.sweep = NULL;
     TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS,
-						&MOCK_AUDIO, &MOCK_INPUT));
+						&MOCK_AUDIO, &MOCK_INPUT, NULL));
     TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, "10 SOUND 1, 1000, 60, 1, 500, 10\n"));
     TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
     TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
@@ -268,7 +268,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *parse_notes(const char *notes)
 
     PASS(errctx, harness_start(NULL));
     mock_devices_init();
-    PASS(errctx, akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, &MOCK_AUDIO, NULL));
+    PASS(errctx, akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, &MOCK_AUDIO, NULL, NULL));
     PASS(errctx, akbasic_play_parse(&HARNESS_RUNTIME, notes));
     SUCCEED_RETURN(errctx);
 }
@@ -351,7 +351,7 @@ static void test_play_is_not_blocking(void)
 {
     TEST_REQUIRE_OK(harness_start(NULL));
     mock_devices_init();
-    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, &MOCK_AUDIO, NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, &MOCK_AUDIO, NULL, NULL));
     TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, "10 PLAY \"QCD\"\n20 PRINT \"AFTER\"\n"));
     TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
     TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));

tests/console_verbs.c

@@ -0,0 +1,179 @@
+/**
+ * @file console_verbs.c
+ * @brief Tests the group E verbs: SLEEP, WAIT, KEY, WINDOW and the TI clock.
+ *
+ * The two that wait are the interesting ones, and what they have to prove is
+ * that they *do not block*: a held step still returns, so a bounded
+ * akbasic_runtime_run() comes back on time and a host keeps its frame rate.
+ * Section 1.6 is the rule and this is where it is checked for group E.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Load a program and put the runtime in RUN mode without stepping it. */
+static akerr_ErrorContext AKERR_NOIGNORE *load_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Run a program to completion in RUN mode. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, load_program(source));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief SLEEP holds the step loop until the host's clock passes its deadline. */
+static void test_sleep(void)
+{
+    TEST_REQUIRE_OK(load_program("1 PRINT \"BEFORE\"\n"
+				 "2 SLEEP 5\n"
+				 "3 PRINT \"AFTER\"\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_settime(&HARNESS_RUNTIME, 1000));
+
+    /* Line 0, line 1, line 2 -- the SLEEP arms and the program stops advancing. */
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 3));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "BEFORE\n");
+    TEST_REQUIRE(HARNESS_RUNTIME.console_state.sleeping, "SLEEP should be holding");
+
+    /*
+     * Twenty more steps with the clock standing still change nothing -- and,
+     * crucially, they *return*. A SLEEP that blocked would never get here.
+     */
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 20));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "BEFORE\n");
+
+    /* Past the deadline, it wakes. */
+    TEST_REQUIRE_OK(akbasic_runtime_settime(&HARNESS_RUNTIME, 6500));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "BEFORE\nAFTER\n");
+    TEST_REQUIRE(!HARNESS_RUNTIME.console_state.sleeping, "SLEEP should have finished");
+    harness_stop();
+}
+
+/** @brief A host that never sets a clock does not hang on SLEEP. */
+static void test_sleep_without_a_clock(void)
+{
+    TEST_REQUIRE_OK(run_program("1 SLEEP 10\n2 PRINT \"THROUGH\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "THROUGH\n");
+    harness_stop();
+}
+
+/** @brief SLEEP refuses a negative interval rather than waiting forever. */
+static void test_sleep_refuses_negative(void)
+{
+    TEST_REQUIRE_OK(run_program("10 SLEEP -1\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "negative number of seconds") != NULL,
+		 "SLEEP -1 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief WAIT polls a byte and holds until it matches, without blocking.
+ *
+ * The address is a real one -- this test's own variable -- which is the only
+ * honest way to exercise it: on a C128 the byte is a hardware register, and here
+ * the only thing that can change it is something outside the program.
+ */
+static void test_wait(void)
+{
+    static volatile uint8_t watched = 0;
+    char source[256];
+
+    watched = 0;
+    snprintf(source, sizeof(source),
+	     "1 WAIT %llu, 1\n2 PRINT \"RELEASED\"\n",
+	     (unsigned long long)(uintptr_t)&watched);
+
+    TEST_REQUIRE_OK(load_program(source));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 4));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "");
+    TEST_REQUIRE(HARNESS_RUNTIME.console_state.waiting, "WAIT should be holding");
+
+    /* Still returning, which is the whole point. */
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 20));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "");
+
+    watched = 1;
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "RELEASED\n");
+    harness_stop();
+}
+
+/** @brief KEY stores a macro per key, and bare KEY lists all eight. */
+static void test_key(void)
+{
+    TEST_REQUIRE_OK(run_program("10 KEY 1, \"RUN\"\n"
+				"20 KEY 3, \"LIST\"\n"
+				"30 KEY\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "KEY 1, \"RUN\"") != NULL,
+		 "KEY should list its macros, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "KEY 3, \"LIST\"") != NULL,
+		 "KEY should list its macros, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "KEY 8, \"\"") != NULL,
+		 "KEY should list undefined keys too, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 KEY 9, \"NOPE\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 1..8") != NULL,
+		 "KEY 9 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief WINDOW refuses against a sink with no character grid, which is stdio. */
+static void test_window_needs_a_grid(void)
+{
+    TEST_REQUIRE_OK(run_program("10 WINDOW 1, 1, 20, 10\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "character grid") != NULL,
+		 "WINDOW against a stdio sink should refuse by name, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+
+    /* An inside-out rectangle is refused before the device is even consulted. */
+    TEST_REQUIRE_OK(run_program("10 WINDOW 20, 10, 1, 1\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "bottom right") != NULL,
+		 "an inverted WINDOW should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief TI# counts jiffies and TI$ formats them, both from the host's clock. */
+static void test_ti(void)
+{
+    TEST_REQUIRE_OK(load_program("1 PRINT TI#\n2 PRINT TI$\n"));
+    /* 3661 seconds is 01:01:01, and 3661 * 60 jiffies. */
+    TEST_REQUIRE_OK(akbasic_runtime_settime(&HARNESS_RUNTIME, 3661000));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 3));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "219660\n010101\n");
+    harness_stop();
+
+    /* A host with no clock has a stopped one rather than a wrong one. */
+    TEST_REQUIRE_OK(run_program("1 PRINT TI$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "000000\n");
+    harness_stop();
+}
+
+int main(void)
+{
+    test_sleep();
+    test_sleep_without_a_clock();
+    test_sleep_refuses_negative();
+    test_wait();
+    test_key();
+    test_window_needs_a_grid();
+    test_ti();
+    return akbasic_test_failures;
+}

tests/devices.c

@@ -45,18 +45,18 @@ static void test_set_devices(void)
     mock_devices_init();
 
     TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS,
-						&MOCK_AUDIO, &MOCK_INPUT));
+						&MOCK_AUDIO, &MOCK_INPUT, NULL));
     TEST_REQUIRE(HARNESS_RUNTIME.graphics == &MOCK_GRAPHICS, "graphics backend was not stored");
     TEST_REQUIRE(HARNESS_RUNTIME.audio == &MOCK_AUDIO, "audio backend was not stored");
     TEST_REQUIRE(HARNESS_RUNTIME.input == &MOCK_INPUT, "input backend was not stored");
 
     /* Withholding a capability is spelled NULL, and must actually detach. */
-    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS, NULL, NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS, NULL, NULL, NULL));
     TEST_REQUIRE(HARNESS_RUNTIME.graphics == &MOCK_GRAPHICS, "graphics backend should have stayed");
     TEST_REQUIRE(HARNESS_RUNTIME.audio == NULL, "audio backend should have been detached");
     TEST_REQUIRE(HARNESS_RUNTIME.input == NULL, "input backend should have been detached");
 
-    TEST_REQUIRE_STATUS(akbasic_runtime_set_devices(NULL, NULL, NULL, NULL), AKERR_NULLPOINTER);
+    TEST_REQUIRE_STATUS(akbasic_runtime_set_devices(NULL, NULL, NULL, NULL, NULL), AKERR_NULLPOINTER);
     harness_stop();
 }
 

tests/disk_verbs.c

@@ -0,0 +1,280 @@
+/**
+ * @file disk_verbs.c
+ * @brief Tests the group F verbs: channels, files, and the ones that are refused.
+ *
+ * These touch the filesystem, so they work in a temporary directory of their own
+ * and clean up after themselves. What is asserted is the seam between BASIC and
+ * `aksl_f*` -- that a verb reaches the right call with the right arguments --
+ * plus, for the five that need a real 1541, that they refuse *by name* rather
+ * than doing something plausible and wrong.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Run a program to completion in RUN mode, from a string. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Read a whole file, for checking what a verb wrote. */
+static bool file_contents(const char *name, char *dest, size_t len)
+{
+    FILE *fp = fopen(name, "rb");
+    size_t got = 0;
+
+    if ( fp == NULL ) {
+	return false;
+    }
+    got = fread(dest, 1, len - 1, fp);
+    dest[got] = '\0';
+    fclose(fp);
+    return true;
+}
+
+/** @brief A channel written and then read back gives the same lines. */
+static void test_channel_round_trip(void)
+{
+    char contents[256];
+
+    remove("t_chan.txt");
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_chan.txt\", W\n"
+				"20 PRINT #1, \"FIRST\"\n"
+				"30 PRINT #1, \"SECOND\"\n"
+				"40 DCLOSE 1\n"
+				"50 DOPEN 2, \"t_chan.txt\"\n"
+				"60 INPUT #2, A$\n"
+				"70 INPUT #2, B$\n"
+				"80 DCLOSE 2\n"
+				"90 PRINT A$\n"
+				"100 PRINT B$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "FIRST\nSECOND\n");
+    TEST_REQUIRE(file_contents("t_chan.txt", contents, sizeof(contents)),
+		 "the file should exist");
+    TEST_REQUIRE_STR(contents, "FIRST\nSECOND\n");
+    harness_stop();
+    remove("t_chan.txt");
+}
+
+/** @brief A numeric variable reads a numeric line, and end of file gives zero. */
+static void test_channel_numeric(void)
+{
+    remove("t_num.txt");
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_num.txt\", W\n"
+				"20 PRINT #1, 42\n"
+				"30 DCLOSE 1\n"
+				"40 DOPEN 2, \"t_num.txt\"\n"
+				"50 INPUT #2, A#\n"
+				"60 INPUT #2, B#\n"
+				"70 DCLOSE 2\n"
+				"80 PRINT A#\n"
+				"90 PRINT B#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "42\n0\n");
+    harness_stop();
+    remove("t_num.txt");
+}
+
+/** @brief APPEND adds to a file rather than replacing it. */
+static void test_append(void)
+{
+    char contents[256];
+
+    remove("t_app.txt");
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_app.txt\", W\n"
+				"20 PRINT #1, \"ONE\"\n"
+				"30 DCLOSE 1\n"
+				"40 APPEND 1, \"t_app.txt\"\n"
+				"50 PRINT #1, \"TWO\"\n"
+				"60 DCLOSE 1\n"));
+    TEST_REQUIRE(file_contents("t_app.txt", contents, sizeof(contents)),
+		 "the file should exist");
+    TEST_REQUIRE_STR(contents, "ONE\nTWO\n");
+    harness_stop();
+    remove("t_app.txt");
+}
+
+/** @brief Reading a channel opened for writing is refused, and the reverse too. */
+static void test_channel_direction(void)
+{
+    remove("t_dir.txt");
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_dir.txt\", W\n"
+				"20 INPUT #1, A$\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "opened for writing") != NULL,
+		 "reading a write channel should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_dir.txt\"\n"
+				"20 PRINT #1, \"NO\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "opened for reading") != NULL,
+		 "writing a read channel should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+    remove("t_dir.txt");
+}
+
+/** @brief An unopened or already-open channel is reported rather than silently reused. */
+static void test_channel_state(void)
+{
+    TEST_REQUIRE_OK(run_program("10 PRINT #3, \"NOWHERE\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "is not open") != NULL,
+		 "an unopened channel should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    remove("t_two.txt");
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_two.txt\", W\n"
+				"20 DOPEN 1, \"t_two.txt\", W\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "already open") != NULL,
+		 "re-opening a channel should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+    remove("t_two.txt");
+
+    TEST_REQUIRE_OK(run_program("10 DOPEN 99, \"x\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 0..9") != NULL,
+		 "channel 99 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief COPY duplicates a file and CONCAT appends one to another. */
+static void test_copy_and_concat(void)
+{
+    char contents[256];
+
+    remove("t_a.txt");
+    remove("t_b.txt");
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_a.txt\", W\n"
+				"20 PRINT #1, \"AAA\"\n"
+				"30 DCLOSE 1\n"
+				"40 COPY \"t_a.txt\", \"t_b.txt\"\n"
+				"50 CONCAT \"t_a.txt\", \"t_b.txt\"\n"));
+    TEST_REQUIRE(file_contents("t_b.txt", contents, sizeof(contents)),
+		 "the copy should exist");
+    TEST_REQUIRE_STR(contents, "AAA\nAAA\n");
+    harness_stop();
+    remove("t_a.txt");
+    remove("t_b.txt");
+}
+
+/** @brief RENAME moves a file and SCRATCH deletes one. */
+static void test_rename_and_scratch(void)
+{
+    char contents[256];
+
+    remove("t_from.txt");
+    remove("t_to.txt");
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_from.txt\", W\n"
+				"20 PRINT #1, \"MOVED\"\n"
+				"30 DCLOSE 1\n"
+				"40 RENAME \"t_from.txt\", \"t_to.txt\"\n"));
+    TEST_REQUIRE(!file_contents("t_from.txt", contents, sizeof(contents)),
+		 "the original should be gone");
+    TEST_REQUIRE(file_contents("t_to.txt", contents, sizeof(contents)),
+		 "the new name should exist");
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 SCRATCH \"t_to.txt\"\n"));
+    TEST_REQUIRE(!file_contents("t_to.txt", contents, sizeof(contents)),
+		 "SCRATCH should have deleted it");
+    harness_stop();
+
+    /* Deleting something that is not there is reported rather than ignored. */
+    TEST_REQUIRE_OK(run_program("10 SCRATCH \"t_nosuch.txt\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "could not delete") != NULL,
+		 "deleting a missing file should be reported, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief BSAVE writes a memory range and BLOAD reads one back. */
+static void test_bsave_bload(void)
+{
+    remove("t_bin.dat");
+    TEST_REQUIRE_OK(run_program("10 A$ = \"BINARY\"\n"
+				"20 BSAVE \"t_bin.dat\", POINTER(A$), POINTER(A$) + 7\n"
+				"30 B$ = \".......\"\n"
+				"40 BLOAD \"t_bin.dat\", POINTER(B$), 7\n"
+				"50 PRINT B$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "BINARY\n");
+    harness_stop();
+    remove("t_bin.dat");
+
+    /* BLOAD needs a length, unlike a C128's; see TODO.md section 5. */
+    TEST_REQUIRE_OK(run_program("10 A$ = \"X\"\n20 BLOAD \"t_bin.dat\", POINTER(A$)\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "maximum length") != NULL,
+		 "BLOAD without a length should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief The five verbs that need a real drive refuse by name, with the reason.
+ *
+ * The point is that they do not do something plausible instead. `HEADER` on a
+ * filesystem would have to mean "delete everything here", which is a
+ * spectacularly bad thing to do to somebody who typed a C128 verb.
+ */
+static void test_no_drive_verbs(void)
+{
+    struct { const char *program; const char *expect; } cases[] = {
+	{ "10 HEADER \"DISK\"\n",  "formats a disk" },
+	{ "10 COLLECT\n",          "block allocation map" },
+	{ "10 BACKUP\n",           "duplicates one disk" },
+	{ "10 BOOT\n",             "boot sector" },
+    };
+    size_t i = 0;
+
+    for ( i = 0; i < sizeof(cases) / sizeof(cases[0]); i++ ) {
+	TEST_REQUIRE_OK(run_program(cases[i].program));
+	TEST_REQUIRE(strstr(HARNESS_OUTPUT, cases[i].expect) != NULL,
+		     "expected \"%s\" in the refusal, got \"%s\"",
+		     cases[i].expect, HARNESS_OUTPUT);
+	TEST_REQUIRE(strstr(HARNESS_OUTPUT, "no disk drive") != NULL,
+		     "the refusal should say why, got \"%s\"", HARNESS_OUTPUT);
+	harness_stop();
+    }
+
+    /* DIRECTORY is refused for a different reason, and says which. */
+    TEST_REQUIRE_OK(run_program("10 DIRECTORY\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "libakstdlib") != NULL,
+		 "DIRECTORY should name the missing wrapper, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief DCLEAR closes every channel, which is the half of it that means something. */
+static void test_dclear(void)
+{
+    remove("t_clear.txt");
+    TEST_REQUIRE_OK(run_program("10 DOPEN 1, \"t_clear.txt\", W\n"
+				"20 DCLEAR\n"
+				"30 PRINT #1, \"NO\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "is not open") != NULL,
+		 "DCLEAR should have closed the channel, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+    remove("t_clear.txt");
+}
+
+int main(void)
+{
+    test_channel_round_trip();
+    test_channel_numeric();
+    test_append();
+    test_channel_direction();
+    test_channel_state();
+    test_copy_and_concat();
+    test_rename_and_scratch();
+    test_bsave_bload();
+    test_no_drive_verbs();
+    test_dclear();
+    return akbasic_test_failures;
+}

tests/for_next.c

@@ -0,0 +1,193 @@
+/**
+ * @file for_next.c
+ * @brief Full coverage of FOR/NEXT, which TODO.md section 6 item 4 is gated on.
+ *
+ * That item is `math_plus` mutating its left operand in place when the operand
+ * is mutable, where every other operator clones. It is a real defect -- `A# + 1`
+ * modifying `A#` depending on where the value came from -- and it was left alone
+ * because `NEXT`'s loop increment *relied* on the mutation: fixing one without
+ * the other silently breaks every FOR loop in the language.
+ *
+ * The golden corpus covers a plain loop, a nested pair and the
+ * `waitingForCommand` case. What it does not cover is `STEP`, a negative step, a
+ * float counter, `EXIT`, or a body that assigns to the loop variable -- and
+ * those are the cases where an increment that writes to the wrong storage shows
+ * up. This file is what made the fix safe to make.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Run a program to completion in RUN mode, from a string. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief The counter advances by one and stops *after* the limit, not on it. */
+static void test_plain_loop(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 4\n"
+				"20 PRINT I#\n"
+				"30 NEXT I#\n"));
+    /*
+     * Every value from the start to the limit, once each. That the body sees the
+     * *incremented* value at all is what says the increment reached the variable
+     * rather than a scratch copy of it -- the whole point of this file.
+     *
+     * What the counter reads after the loop is a separate question, and this
+     * interpreter answers it differently from a C128: see tests/for_semantics.c.
+     */
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n2\n3\n4\n");
+    harness_stop();
+}
+
+/** @brief STEP advances by what it says, and the limit is still a limit. */
+static void test_step(void)
+{
+    /*
+     * A step that lands exactly on the limit. The overshooting case is a known
+     * defect and lives in tests/for_semantics.c; what is asserted here is only
+     * that STEP is read and applied.
+     */
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 0 TO 9 STEP 3\n"
+				"20 PRINT I#\n"
+				"30 NEXT I#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "0\n3\n6\n9\n");
+    harness_stop();
+}
+
+/** @brief A negative step counts down, and the comparison flips with it. */
+static void test_negative_step(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 5 TO 1 STEP -2\n"
+				"20 PRINT I#\n"
+				"30 NEXT I#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "5\n3\n1\n");
+    harness_stop();
+}
+
+/** @brief A float counter accumulates in the float field, not the integer one. */
+static void test_float_counter(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I% = 1.0 TO 2.0 STEP 0.5\n"
+				"20 PRINT I%\n"
+				"30 NEXT I%\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1.000000\n1.500000\n2.000000\n");
+    harness_stop();
+}
+
+/**
+ * @brief A body that assigns to the loop variable changes where the loop goes.
+ *
+ * The counter is ordinary storage, so writing to it is legal and the loop reads
+ * the written value. This is the case that tells an increment landing in the
+ * variable apart from one landing in a scratch value that happens to be read
+ * back: with a scratch increment the assignment on line 20 would be overwritten
+ * rather than built on.
+ */
+static void test_body_assigns_to_counter(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 10\n"
+				"20 I# = I# + 3\n"
+				"30 PRINT I#\n"
+				"40 NEXT I#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "4\n8\n12\n");
+    harness_stop();
+}
+
+/** @brief EXIT leaves the loop and lands after its NEXT, with the wait cleared. */
+static void test_exit(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 10\n"
+				"20 PRINT I#\n"
+				"30 IF I# = 2 THEN EXIT\n"
+				"40 NEXT I#\n"
+				"50 PRINT \"OUT\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n2\nOUT\n");
+    harness_stop();
+
+    /* And a second loop afterwards still runs, so the wait really was cleared. */
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 10\n"
+				"20 IF I# = 1 THEN EXIT\n"
+				"30 NEXT I#\n"
+				"40 FOR J# = 1 TO 2\n"
+				"50 PRINT J#\n"
+				"60 NEXT J#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n2\n");
+    harness_stop();
+}
+
+/** @brief Nested loops each advance their own counter and unwind in order. */
+static void test_nested(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 2\n"
+				"20 FOR J# = 1 TO 2\n"
+				"30 PRINT I# * 10 + J#\n"
+				"40 NEXT J#\n"
+				"50 NEXT I#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "11\n12\n21\n22\n");
+    harness_stop();
+}
+
+/**
+ * @brief `A# + 1` does not modify `A#`.
+ *
+ * The defect itself, stated as a program. Addition on a variable read out of the
+ * environment used to update the variable in place, so this printed `2` and then
+ * `2` -- the first PRINT changing what the second one saw.
+ */
+static void test_addition_does_not_mutate(void)
+{
+    TEST_REQUIRE_OK(run_program("10 A# = 1\n"
+				"20 PRINT A# + 1\n"
+				"30 PRINT A#\n"
+				"40 PRINT A# + 1\n"
+				"50 PRINT A#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "2\n1\n2\n1\n");
+    harness_stop();
+
+    /* The same for a float, and for a string, which concatenates. */
+    TEST_REQUIRE_OK(run_program("10 A% = 1.5\n"
+				"20 PRINT A% + 1.0\n"
+				"30 PRINT A%\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "2.500000\n1.500000\n");
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 A$ = \"X\"\n"
+				"20 PRINT A$ + \"Y\"\n"
+				"30 PRINT A$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "XY\nX\n");
+    harness_stop();
+
+    /* And inside an expression used twice on one line. */
+    TEST_REQUIRE_OK(run_program("10 A# = 5\n"
+				"20 PRINT (A# + 1) + (A# + 1)\n"
+				"30 PRINT A#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "12\n5\n");
+    harness_stop();
+}
+
+int main(void)
+{
+    test_plain_loop();
+    test_step();
+    test_negative_step();
+    test_float_counter();
+    test_body_assigns_to_counter();
+    test_exit();
+    test_nested();
+    test_addition_does_not_mutate();
+    return akbasic_test_failures;
+}

tests/for_semantics.c

@@ -0,0 +1,103 @@
+/**
+ * @file for_semantics.c
+ * @brief Known-failing. Asserts what FOR/NEXT *should* do, which is not what it does.
+ *
+ * Registered in `AKBASIC_KNOWN_FAILING_TESTS`, so CTest expects it to fail. When
+ * it starts passing, CTest reports "unexpectedly passed" and that is the cue to
+ * move it into `AKBASIC_TESTS` along with the fix.
+ *
+ * Two defects, both found while writing tests/for_next.c and both recorded in
+ * TODO.md section 6. Neither is the Go reference's fault alone -- the port
+ * reproduced them faithfully -- and neither can be fixed without moving a golden
+ * file, which is why they are written down rather than quietly corrected.
+ *
+ * **1. The body runs once with the overshot value.** The loop condition is
+ * tested against the counter *before* the increment, so the increment's result
+ * reaches the body before anything checks it against the limit.
+ * `FOR I = 1 TO 9 STEP 3` runs its body with 1, 4, 7 and then 10.
+ *
+ * **2. The counter does not survive the loop.** It lives in the environment the
+ * loop pushed, which pops when the loop ends, so reading it afterwards finds a
+ * fresh variable holding zero. A C128 leaves the counter at the value that ended
+ * the loop, and plenty of published listings read it afterwards.
+ *
+ * They are related but not the same fix: the first is an ordering bug in
+ * akbasic_cmd_next(), and the second is a scoping decision about where a loop
+ * counter is created.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Run a program to completion in RUN mode, from a string. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief A step that overshoots the limit must not run the body again. */
+static void test_step_does_not_overshoot(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 9 STEP 3\n"
+				"20 PRINT I#\n"
+				"30 NEXT I#\n"));
+    /* Today: "1\n4\n7\n10\n" -- the body runs with 10, which is past the limit. */
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n4\n7\n");
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 2 STEP 100\n"
+				"20 PRINT I#\n"
+				"30 NEXT I#\n"));
+    /* Today: "1\n101\n". */
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n");
+    harness_stop();
+}
+
+/** @brief The loop counter is readable after the loop, holding where it stopped. */
+static void test_counter_survives_the_loop(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 4\n"
+				"20 NEXT I#\n"
+				"30 PRINT I#\n"));
+    /* Today: "0\n" -- the loop's environment took the variable with it. */
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "5\n");
+    harness_stop();
+}
+
+/**
+ * @brief A loop whose limit equals its start still runs its body once.
+ *
+ * `FOR I = 1 TO 1` executes the body one time on every BASIC there has ever
+ * been. Here the entry test treats "the counter has reached the limit" as
+ * "do not enter", so the body is skipped entirely -- and
+ * tests/reference/language/flowcontrol/forloopwaitingforcommand.bas pins that,
+ * which is why this cannot simply be corrected.
+ */
+static void test_single_iteration_loop(void)
+{
+    TEST_REQUIRE_OK(run_program("10 FOR I# = 1 TO 1\n"
+				"20 PRINT \"ONCE\"\n"
+				"30 NEXT I#\n"));
+    /* Today: "" -- the body never runs. */
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "ONCE\n");
+    harness_stop();
+}
+
+int main(void)
+{
+    test_step_does_not_overshoot();
+    test_counter_survives_the_loop();
+    test_single_iteration_loop();
+    return akbasic_test_failures;
+}

tests/format_verbs.c

@@ -0,0 +1,273 @@
+/**
+ * @file format_verbs.c
+ * @brief Tests the group D verbs: PRINT USING, PUDEF, WIDTH and CHAR.
+ *
+ * Field formatting has more edge cases than a verb usually does, and
+ * akbasic_format_using() is a pure function of a format string and a value, so
+ * most of this exercises it directly rather than through a program. What goes
+ * through a program is the part a program can get wrong: the parse of
+ * `PRINT USING fmt; value`, and the verbs that only set state.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/format.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+static akbasic_FormatState FORMAT;
+
+/** @brief Run a program to completion in RUN mode, from a string. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Format one value, for the direct tests below. */
+static akerr_ErrorContext AKERR_NOIGNORE *fmt_number(const char *format, double number, char *dest, size_t len)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value value;
+
+    PASS(errctx, akbasic_value_zero(&value));
+    value.valuetype = AKBASIC_TYPE_FLOAT;
+    value.floatval = number;
+    PASS(errctx, akbasic_format_using(&FORMAT, format, &value, dest, len));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Format one string, for the direct tests below. */
+static akerr_ErrorContext AKERR_NOIGNORE *fmt_string(const char *format, const char *text, char *dest, size_t len)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value value;
+
+    PASS(errctx, akbasic_value_zero(&value));
+    value.valuetype = AKBASIC_TYPE_STRING;
+    snprintf(value.stringval, sizeof(value.stringval), "%s", text);
+    PASS(errctx, akbasic_format_using(&FORMAT, format, &value, dest, len));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Digit positions right-justify, and the decimal places are fixed. */
+static void test_numeric_fields(void)
+{
+    char out[256];
+
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+
+    TEST_REQUIRE_OK(fmt_number("###.##", 3.14159, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "  3.14");
+
+    /* Rounded to the field, not truncated. */
+    TEST_REQUIRE_OK(fmt_number("###.#", 2.06, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "  2.1");
+
+    /* No decimal point in the field means no fractional part printed. */
+    TEST_REQUIRE_OK(fmt_number("####", 42.9, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "  43");
+
+    /* Zero fills the whole field with blanks but the one digit. */
+    TEST_REQUIRE_OK(fmt_number("####", 0.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "   0");
+}
+
+/** @brief Literal text around the field is copied through. */
+static void test_literal_text(void)
+{
+    char out[256];
+
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+    TEST_REQUIRE_OK(fmt_number("TOTAL: ###.## EACH", 12.5, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "TOTAL:  12.50 EACH");
+}
+
+/** @brief A comma in the field groups the integer part in threes. */
+static void test_grouping(void)
+{
+    char out[256];
+
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+    TEST_REQUIRE_OK(fmt_number("#,###,###", 1234567.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "1,234,567");
+
+    /* Padding counts the separators, so a column stays a column. */
+    TEST_REQUIRE_OK(fmt_number("#,###,###", 12.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "       12");
+}
+
+/** @brief A currency sign and a sign position are part of the field. */
+static void test_decorations(void)
+{
+    char out[256];
+
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+    TEST_REQUIRE_OK(fmt_number("$#,###.##", 1234.5, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "$1,234.50");
+
+    TEST_REQUIRE_OK(fmt_number("+####", 42.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "+  42");
+
+    TEST_REQUIRE_OK(fmt_number("+####", -42.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "-  42");
+
+    /* A trailing sign position puts the sign after the digits. */
+    TEST_REQUIRE_OK(fmt_number("####-", -42.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "  42-");
+}
+
+/**
+ * @brief A value too wide for its field fills the field with stars.
+ *
+ * BASIC 7.0's answer, and deliberately loud: printing more digits than the field
+ * asked for would push every later column out of line, which is exactly what
+ * PRINT USING is for avoiding.
+ */
+static void test_overflow(void)
+{
+    char out[256];
+
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+    TEST_REQUIRE_OK(fmt_number("###", 99999.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "***");
+
+    /*
+     * A negative number in a field with no sign position overflows too. Dropping
+     * the minus would print -5 as 5, which is worse than a row of stars.
+     */
+    TEST_REQUIRE_OK(fmt_number("###", -5.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "***");
+}
+
+/** @brief `=` centres a string in its field and `>` right-justifies it. */
+static void test_string_fields(void)
+{
+    char out[256];
+
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+    TEST_REQUIRE_OK(fmt_string("==========", "MID", out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "   MID    ");
+
+    TEST_REQUIRE_OK(fmt_string(">>>>>>>>>>", "RIGHT", out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "     RIGHT");
+
+    /* A string longer than its field is cut, not starred. */
+    TEST_REQUIRE_OK(fmt_string("===", "TOOLONG", out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "TOO");
+}
+
+/** @brief A field and a value of the wrong kind for each other are refused. */
+static void test_type_mismatch(void)
+{
+    char out[256];
+
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+    TEST_REQUIRE_STATUS(fmt_string("###", "TEXT", out, sizeof(out)), AKBASIC_ERR_TYPE);
+    TEST_REQUIRE_STATUS(fmt_number("===", 1.0, out, sizeof(out)), AKBASIC_ERR_TYPE);
+
+    /* A format with no field at all is a mistake rather than a literal. */
+    TEST_REQUIRE_STATUS(fmt_number("NO FIELD HERE", 1.0, out, sizeof(out)), AKBASIC_ERR_SYNTAX);
+}
+
+/** @brief PUDEF replaces the fill characters, as many as it was given. */
+static void test_pudef(void)
+{
+    char out[256];
+
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+    TEST_REQUIRE_OK(akbasic_format_pudef(&FORMAT, "*"));
+    TEST_REQUIRE_OK(fmt_number("#####", 42.0, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "***42");
+
+    /* The other three are untouched by a one-character PUDEF. */
+    TEST_REQUIRE_OK(fmt_number("#,###.##", 1234.5, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, "1,234.50");
+
+    /* All four at once. */
+    TEST_REQUIRE_OK(akbasic_format_state_init(&FORMAT));
+    TEST_REQUIRE_OK(akbasic_format_pudef(&FORMAT, "_. ,"));
+    TEST_REQUIRE_OK(fmt_number("$#,###.##", 1234.5, out, sizeof(out)));
+    TEST_REQUIRE_STR(out, ",1.234 50");
+}
+
+/** @brief PRINT USING parses and prints through a running program. */
+static void test_print_using(void)
+{
+    TEST_REQUIRE_OK(run_program("10 PRINT USING \"###.##\"; 3.14159\n"
+				"20 PRINT USING \"TOTAL: $#,###.##\"; 1234.5\n"
+				"30 PRINT USING \"###\"; 99999\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "  3.14\nTOTAL: $1,234.50\n***\n");
+    harness_stop();
+
+    /* A plain PRINT still works, which the shared parse handler could break. */
+    TEST_REQUIRE_OK(run_program("10 PRINT \"PLAIN\"\n20 PRINT 1 + 2\n30 PRINT\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "PLAIN\n3\n\n");
+    harness_stop();
+
+    /* And PUDEF reaches PRINT USING through the runtime's own state. */
+    TEST_REQUIRE_OK(run_program("10 PUDEF \"*\"\n"
+				"20 PRINT USING \"#####\"; 42\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "***42\n");
+    harness_stop();
+
+    /* The semicolon is required; without it the format has no value to print. */
+    TEST_REQUIRE_OK(run_program("10 PRINT USING \"###\" 42\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "semicolon") != NULL,
+		 "a missing semicolon should say so, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief WIDTH takes 1 or 2 and refuses anything else. */
+static void test_width(void)
+{
+    TEST_REQUIRE_OK(run_program("10 WIDTH 2\n20 PRINT \"OK\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "OK\n");
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.gfx.linewidth, 2);
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 WIDTH 3\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "WIDTH is 1 or 2") != NULL,
+		 "WIDTH 3 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    /* No device needed: it is drawing state, like COLOR's bindings. */
+    TEST_REQUIRE_OK(run_program("10 WIDTH 2\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "device") == NULL,
+		 "WIDTH should not need a device, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief CHAR refuses against a sink with no cursor, which is the stdio one. */
+static void test_char_needs_a_cursor(void)
+{
+    TEST_REQUIRE_OK(run_program("10 CHAR 1, 5, 3, \"HI\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "position its cursor") != NULL,
+		 "CHAR against a stdio sink should refuse by name, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+}
+
+int main(void)
+{
+    test_numeric_fields();
+    test_literal_text();
+    test_grouping();
+    test_decorations();
+    test_overflow();
+    test_string_fields();
+    test_type_mismatch();
+    test_pudef();
+    test_print_using();
+    test_width();
+    test_char_needs_a_cursor();
+    return akbasic_test_failures;
+}

tests/graphics_verbs.c

@@ -27,7 +27,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
     PASS(errctx, harness_start(NULL));
     mock_devices_init();
     PASS(errctx, akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS,
-					     &MOCK_AUDIO, &MOCK_INPUT));
+					     &MOCK_AUDIO, &MOCK_INPUT, NULL));
     PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
     PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
     PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
@@ -63,7 +63,7 @@ static void test_draw(void)
     /* An odd number of coordinates is a typo, not half a line. */
     TEST_REQUIRE_OK(harness_start(NULL));
     mock_devices_init();
-    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS, NULL, NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS, NULL, NULL, NULL));
     TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, "10 DRAW 1, 5\n"));
     TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
     TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
@@ -163,7 +163,7 @@ static void test_paint(void)
     TEST_REQUIRE_OK(harness_start(NULL));
     mock_devices_init();
     MOCK.paint_exhausts = true;
-    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS, NULL, NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS, NULL, NULL, NULL));
     TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, "10 PAINT 1, 5, 5\n"));
     TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
     TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));

tests/housekeeping_verbs.c

@@ -247,6 +247,40 @@ static akerr_ErrorContext AKERR_NOIGNORE *test_repl_stops_after_an_error(void)
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief A statement typed with no line number runs; one with a number is stored.
+ *
+ * Direct mode. The reference only ran the verbs it marked immediate -- RUN, LIST,
+ * NEW and the rest -- and filed everything else as program text, so `PRINT 2 + 2`
+ * at a prompt silently became line 0 of a program instead of answering. See
+ * TODO.md section 5.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_direct_mode(void)
+{
+    PREPARE_ERROR(errctx);
+
+    TEST_REQUIRE_OK(harness_start("PRINT 2 + 2\n"
+				  "A# = 5\n"
+				  "PRINT A# * 3\n"
+				  "10 PRINT \"STORED\"\n"
+				  "RUN\n"));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_REPL));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 200));
+
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "4\n") != NULL,
+		 "PRINT 2 + 2 should have answered 4, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "15\n") != NULL,
+		 "an assignment then a PRINT should both have run, got \"%s\"",
+		 HARNESS_OUTPUT);
+    /* And the numbered line was stored rather than run when it was typed. */
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "PRINT \"STORED\"");
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "STORED") != NULL,
+		 "RUN should have run the stored line, got \"%s\"", HARNESS_OUTPUT);
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
 int main(void)
 {
     PREPARE_ERROR(errctx);
@@ -260,6 +294,7 @@ int main(void)
 	CATCH(errctx, test_help());
 	CATCH(errctx, test_trace_flag());
 	CATCH(errctx, test_repl_stops_after_an_error());
+	CATCH(errctx, test_direct_mode());
     } CLEANUP {
     } PROCESS(errctx) {
     } HANDLE_DEFAULT(errctx) {

tests/input_verbs.c

@@ -26,7 +26,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
     PASS(errctx, harness_start(NULL));
     mock_devices_init();
     PASS(errctx, akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS,
-					     &MOCK_AUDIO, &MOCK_INPUT));
+					     &MOCK_AUDIO, &MOCK_INPUT, NULL));
     PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
     PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
     SUCCEED_RETURN(errctx);
@@ -146,7 +146,7 @@ static void test_getkey_device_withdrawn(void)
     TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 20));
     TEST_REQUIRE(HARNESS_RUNTIME.input_state.waiting, "GETKEY should be holding");
 
-    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, NULL, NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, NULL, NULL, NULL));
     TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
     TEST_REQUIRE_STR(HARNESS_OUTPUT, "RELEASED\n");
     harness_stop();

tests/interrupts.c

@@ -0,0 +1,366 @@
+/**
+ * @file interrupts.c
+ * @brief Tests the interrupt machinery: arm, raise, enter a handler, RETURN.
+ *
+ * This is the part of COLLISION that has nothing to do with sprites, and it is
+ * tested on its own for two reasons. It is what group C's TRAP will reuse, so it
+ * has to be correct before anything is built on it; and driving it through the
+ * API rather than through a verb is the only way to fire an interrupt at an
+ * exactly known point in a program, which is what most of these assertions turn
+ * on.
+ *
+ * **Every program here is numbered 1, 2, 3, ...** One step of the runtime
+ * advances by one source line *index*, empty ones included -- so consecutive
+ * numbering is what makes a step count mean a statement count. The first step of
+ * any run is line 0, which is always empty, and is accounted for in each count
+ * below.
+ */
+
+#include "harness.h"
+
+/**
+ * @brief A program with a handler at 3 and a main loop that never ends.
+ *
+ * The endless loop is on purpose: every test here steps a fixed number of times
+ * and asserts what came out, so a regression that fails to enter or fails to
+ * return shows up as the wrong output rather than as a run that stops early and
+ * looks plausible.
+ */
+static const char *PROGRAM_BY_LINE =
+    "1 PRINT \"START\"\n"
+    "2 GOTO 5\n"
+    "3 PRINT \"HANDLER\"\n"
+    "4 RETURN\n"
+    "5 PRINT \"MAIN\"\n"
+    "6 GOTO 5\n";
+
+/** @brief Load a program and put the runtime in RUN mode without stepping it. */
+static akerr_ErrorContext AKERR_NOIGNORE *load_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief A handler named by line number runs, and RETURN resumes where it left. */
+static akerr_ErrorContext AKERR_NOIGNORE *test_enter_and_return(void)
+{
+    PREPARE_ERROR(errctx);
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    PASS(errctx, load_program(PROGRAM_BY_LINE));
+    PASS(errctx, akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE, 3, NULL));
+
+    /* Line 0, then 1 and 2, so the program is sitting on 5 with nothing pending. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 3));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "START\n");
+
+    PASS(errctx, akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+    TEST_REQUIRE(HARNESS_RUNTIME.handlerenv == NULL, "raising must not enter anything by itself");
+
+    /* One step: the handler is entered and its first line runs. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "START\nHANDLER\n");
+    TEST_REQUIRE(HARNESS_RUNTIME.handlerenv != NULL, "the runtime should know it is in a handler");
+    TEST_REQUIRE(!HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].pending,
+		 "entering the handler should have consumed the event");
+
+    /* The RETURN, then the line the interrupt took the program away from. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "START\nHANDLER\nMAIN\n");
+    TEST_REQUIRE(HARNESS_RUNTIME.handlerenv == NULL, "RETURN should have left the handler");
+
+    /* Still armed: one collision handled is not a subscription cancelled. */
+    TEST_REQUIRE(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].armed,
+		 "the handler should still be armed after it returns");
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief A handler named by label, on a line the program never falls into.
+ *
+ * This is the shape a handler is actually written in -- jumped over by the main
+ * flow, reachable only through the interrupt -- and it works only because
+ * akbasic_runtime_scan_labels() files LABEL before anything runs. Without the
+ * prescan the label does not exist when the interrupt fires and the run stops
+ * with AKBASIC_ERR_UNDEFINED.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_label_handler(void)
+{
+    PREPARE_ERROR(errctx);
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    PASS(errctx, load_program("1 GOTO 5\n"
+			      "2 LABEL BUMPED\n"
+			      "3 PRINT \"HANDLER\"\n"
+			      "4 RETURN\n"
+			      "5 PRINT \"MAIN\"\n"
+			      "6 GOTO 5\n"));
+    PASS(errctx, akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE,
+					       0, "BUMPED"));
+
+    /* Line 0, the GOTO, then the main loop's PRINT. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 3));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "MAIN\n");
+
+    PASS(errctx, akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+    /* The LABEL line the handler is entered on, then the handler's PRINT. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "MAIN\nHANDLER\n");
+
+    /* RETURN, then back into the main loop where it left off. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 3));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "MAIN\nHANDLER\nMAIN\n");
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief An interrupt does not interrupt an interrupt.
+ *
+ * Without the guard a collision that is still true while its own handler runs
+ * re-enters on the next line, and keeps re-entering until the environment pool
+ * is gone -- the failure would be AKBASIC_ERR_ENVIRONMENT from somewhere with
+ * nothing to do with sprites. The event raised inside the handler is not lost,
+ * though: it is taken as soon as the RETURN lands.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_no_reentry(void)
+{
+    PREPARE_ERROR(errctx);
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    PASS(errctx, load_program("1 GOTO 5\n"
+			      "2 PRINT \"IN\"\n"
+			      "3 PRINT \"OUT\"\n"
+			      "4 RETURN\n"
+			      "5 PRINT \"MAIN\"\n"
+			      "6 GOTO 5\n"));
+    PASS(errctx, akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE, 2, NULL));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 3));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "MAIN\n");
+
+    PASS(errctx, akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "MAIN\nIN\n");
+
+    /* Fires again while the handler is still running. */
+    PASS(errctx, akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "MAIN\nIN\nOUT\n");
+    TEST_REQUIRE(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].pending,
+		 "an event raised inside a handler should be held, not dropped");
+
+    /* The RETURN lands, and the held event is taken on the very next step. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "MAIN\nIN\nOUT\nIN\n");
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief A GOSUB the handler itself makes returns without re-arming interrupts. */
+static akerr_ErrorContext AKERR_NOIGNORE *test_nested_gosub_keeps_the_flag(void)
+{
+    PREPARE_ERROR(errctx);
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    PASS(errctx, load_program("1 GOTO 5\n"
+			      "2 GOSUB 8\n"
+			      "3 RETURN\n"
+			      "5 PRINT \"MAIN\"\n"
+			      "6 GOTO 5\n"
+			      "8 PRINT \"INNER\"\n"
+			      "9 RETURN\n"));
+    PASS(errctx, akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE, 2, NULL));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 3));
+    PASS(errctx, akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+
+    /* Enter the handler, which immediately GOSUBs deeper. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE(HARNESS_RUNTIME.handlerenv != NULL, "the handler should be running");
+
+    /* The inner PRINT and the inner RETURN: still inside the handler. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "MAIN\nINNER\n");
+    TEST_REQUIRE(HARNESS_RUNTIME.handlerenv != NULL,
+		 "the inner RETURN belongs to the inner GOSUB, not to the handler");
+
+    /* The handler's own RETURN is the one that clears it. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE(HARNESS_RUNTIME.handlerenv == NULL, "the handler's RETURN should have cleared it");
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Raising an unarmed source records nothing; disarming drops what is held. */
+static akerr_ErrorContext AKERR_NOIGNORE *test_arm_and_disarm(void)
+{
+    PREPARE_ERROR(errctx);
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    PASS(errctx, load_program(PROGRAM_BY_LINE));
+
+    /* Unarmed. A backend may raise every frame without asking who is listening. */
+    PASS(errctx, akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+    TEST_REQUIRE(!HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].pending,
+		 "an unarmed source should record nothing");
+
+    /* Armed, raised, then taken away again before it could be taken. */
+    PASS(errctx, akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE, 3, NULL));
+    PASS(errctx, akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+    PASS(errctx, akbasic_runtime_disarm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+    TEST_REQUIRE(!HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].pending,
+		 "disarming should drop a pending event rather than deferring it");
+
+    /* And the program runs straight through without ever seeing line 3. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 6));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "START\nMAIN\nMAIN\n");
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief NEW disarms everything: the handler lines belong to a program that is gone. */
+static akerr_ErrorContext AKERR_NOIGNORE *test_new_disarms(void)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_ASTLeaf *leaf = NULL;
+    akbasic_Value *out = NULL;
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    PASS(errctx, load_program(PROGRAM_BY_LINE));
+    PASS(errctx, akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE, 3, NULL));
+
+    PASS(errctx, akbasic_environment_zero(HARNESS_RUNTIME.environment));
+    PASS(errctx, harness_parse("NEW", &leaf));
+    PASS(errctx, akbasic_runtime_evaluate(&HARNESS_RUNTIME, leaf, &out));
+
+    TEST_REQUIRE(!HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].armed,
+		 "NEW should have disarmed the interrupt");
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief A handler label that names nothing is the program's error, not the host's.
+ *
+ * It has to be *reported* and stop the run. Letting it out of
+ * akbasic_runtime_step() would tear down an embedding game over a typo in a
+ * script, which is what goal 3 exists to prevent.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_undefined_label_is_reported(void)
+{
+    PREPARE_ERROR(errctx);
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    PASS(errctx, load_program("1 PRINT \"MAIN\"\n"
+			      "2 GOTO 1\n"));
+    PASS(errctx, akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE,
+					       0, "NOSUCHLABEL"));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    PASS(errctx, akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE));
+
+    /* Returns cleanly -- the error is on the sink, not in the return value. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "NOSUCHLABEL") != NULL,
+		 "the report should name the label that could not be found, got: %s",
+		 HARNESS_OUTPUT);
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.mode, AKBASIC_MODE_QUIT);
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Arming refuses a source out of range, and a target that is both or neither. */
+static akerr_ErrorContext AKERR_NOIGNORE *test_arm_refusals(void)
+{
+    PREPARE_ERROR(errctx);
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+
+    TEST_REQUIRE_STATUS(akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME,
+						      (akbasic_InterruptSource)AKBASIC_MAX_INTERRUPTS,
+						      3, NULL),
+			AKBASIC_ERR_BOUNDS);
+    TEST_REQUIRE_STATUS(akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE,
+						      0, NULL),
+			AKBASIC_ERR_VALUE);
+    TEST_REQUIRE_STATUS(akbasic_runtime_arm_interrupt(&HARNESS_RUNTIME, AKBASIC_INTERRUPT_SPRITE,
+						      3, "BUMPED"),
+			AKBASIC_ERR_VALUE);
+    TEST_REQUIRE_STATUS(akbasic_runtime_raise_interrupt(&HARNESS_RUNTIME,
+							(akbasic_InterruptSource)-1),
+			AKBASIC_ERR_BOUNDS);
+    TEST_REQUIRE_STATUS(akbasic_runtime_disarm_interrupt(&HARNESS_RUNTIME,
+							 (akbasic_InterruptSource)AKBASIC_MAX_INTERRUPTS),
+			AKBASIC_ERR_BOUNDS);
+    TEST_REQUIRE_STATUS(akbasic_runtime_arm_interrupt(NULL, AKBASIC_INTERRUPT_SPRITE, 3, NULL),
+			AKERR_NULLPOINTER);
+    TEST_REQUIRE_STATUS(akbasic_runtime_service_interrupts(NULL, NULL), AKERR_NULLPOINTER);
+    TEST_REQUIRE_STATUS(akbasic_runtime_scan_labels(NULL), AKERR_NULLPOINTER);
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief The label prescan reads LABEL where it is a statement, and nowhere else.
+ *
+ * The forward jump itself is covered by the golden case at
+ * tests/language/statements/label_forward.bas. What is here is the part a
+ * running program cannot show: that a string literal holding the word LABEL
+ * files nothing, and that a second statement on a line is still a statement.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *test_prescan_boundaries(void)
+{
+    PREPARE_ERROR(errctx);
+    int64_t line = 0;
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    PASS(errctx, load_program("1 PRINT \"LABEL DECOY\"\n"
+			      "2 A# = 1 : LABEL SECOND\n"
+			      "3 LABELLED# = 2\n"));
+
+    PASS(errctx, akbasic_environment_get_label(HARNESS_RUNTIME.environment, "SECOND", &line));
+    TEST_REQUIRE_INT(line, 2);
+
+    TEST_REQUIRE_STATUS(akbasic_environment_get_label(HARNESS_RUNTIME.environment, "DECOY", &line),
+			AKBASIC_ERR_UNDEFINED);
+    /* LABELLED# is an identifier that starts with the word, not the verb. */
+    TEST_REQUIRE_STATUS(akbasic_environment_get_label(HARNESS_RUNTIME.environment, "ED", &line),
+			AKBASIC_ERR_UNDEFINED);
+
+    harness_stop();
+    SUCCEED_RETURN(errctx);
+}
+
+int main(void)
+{
+    PREPARE_ERROR(errctx);
+
+    ATTEMPT {
+	CATCH(errctx, test_enter_and_return());
+	CATCH(errctx, test_label_handler());
+	CATCH(errctx, test_no_reentry());
+	CATCH(errctx, test_nested_gosub_keeps_the_flag());
+	CATCH(errctx, test_arm_and_disarm());
+	CATCH(errctx, test_new_disarms());
+	CATCH(errctx, test_undefined_label_is_reported());
+	CATCH(errctx, test_arm_refusals());
+	CATCH(errctx, test_prescan_boundaries());
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE_DEFAULT(errctx) {
+	LOG_ERROR_WITH_MESSAGE(errctx, "interrupt test failed");
+	akbasic_test_failures += 1;
+    } FINISH_NORETURN(errctx);
+
+    return akbasic_test_failures;
+}

tests/language/errors/trap.bas

@@ -0,0 +1,13 @@
+10 REM TRAP catches a BASIC error and sends the program to a handler.
+20 TRAP HANDLER
+30 DIM Q#(2)
+40 PRINT "BEFORE"
+50 PRINT Q#(9)
+60 PRINT "RESUMED"
+70 TRAP
+80 REM Disarmed again, so this one is reported and stops the program.
+90 PRINT Q#(9)
+100 PRINT "NEVER SEEN"
+200 LABEL HANDLER
+210 PRINT "CAUGHT " + ERR(ER#) + " ON LINE " + EL#
+220 RESUME NEXT

tests/language/errors/trap.txt

@@ -0,0 +1,5 @@
+BEFORE
+CAUGHT Out Of Bounds ON LINE 50
+RESUMED
+? 90 : RUNTIME ERROR Variable index access out of bounds at dimension 0: 9 (max 1)
+

tests/language/format/using.bas

@@ -0,0 +1,12 @@
+10 REM PRINT USING lays a number out in a fixed field.
+20 PRINT USING "###.##"; 3.14159
+30 PRINT USING "TOTAL: $#,###.##"; 1234.5
+40 PRINT USING "####-"; -42
+50 REM A value too wide for its field fills the field with stars.
+60 PRINT USING "###"; 99999
+70 REM String fields centre and right-justify.
+80 PRINT USING "=========="; "MID"
+90 PRINT USING ">>>>>>>>>>"; "RIGHT"
+100 REM PUDEF changes what a numeric field pads and punctuates with.
+110 PUDEF "*"
+120 PRINT USING "#####"; 42

tests/language/format/using.txt

@@ -0,0 +1,7 @@
+  3.14
+TOTAL: $1,234.50
+  42-
+***
+   MID    
+     RIGHT
+***42

tests/language/sprites/no_device.bas

@@ -0,0 +1,11 @@
+10 REM The standalone driver lends the script no sprite device.
+20 REM SPRCOLOR and the RSP* readbacks only touch interpreter state.
+30 SPRCOLOR 5, 7
+40 PRINT RSPCOLOR(1)
+50 PRINT RSPCOLOR(2)
+60 REM An untouched sprite reads back at the origin, in the default colour.
+70 PRINT RSPPOS(1, 0)
+80 PRINT RSPRITE(1, 1)
+90 REM SPRSAV needs the device, and has to say which verb wanted it.
+100 SPRSAV "ship.png", 1
+110 PRINT "UNREACHED"

tests/language/sprites/no_device.txt

@@ -0,0 +1,6 @@
+5
+7
+0
+2
+? 100 : RUNTIME ERROR SPRSAV needs a sprite device and this runtime has none
+

tests/language/statements/label_forward.bas

@@ -0,0 +1,12 @@
+10 GOTO SKIPAHEAD
+20 PRINT "SKIPPED"
+30 LABEL SKIPAHEAD
+40 PRINT "ARRIVED"
+50 GOSUB LATER
+60 PRINT "BACK"
+70 GOTO DONE
+80 LABEL LATER
+90 PRINT "IN SUB"
+100 RETURN
+110 LABEL DONE
+120 PRINT "FINISHED"

tests/language/statements/label_forward.txt

@@ -0,0 +1,4 @@
+ARRIVED
+IN SUB
+BACK
+FINISHED

tests/language/structure/loops.bas

@@ -0,0 +1,33 @@
+10 REM DO/LOOP in all four shapes, plus ON and a multi-line IF block.
+20 I# = 0
+30 DO WHILE I# < 3
+40   PRINT "WHILE " + I#
+50   I# = I# + 1
+60 LOOP
+70 I# = 0
+80 DO
+90   PRINT "UNTIL " + I#
+100   I# = I# + 1
+110 LOOP UNTIL I# = 2
+120 REM A condition already false runs no body at all.
+130 DO WHILE 1 == 2
+140   PRINT "NEVER SEEN"
+150 LOOP
+160 REM ON picks the nth target, one-based, and falls through past the end.
+170 X# = 2
+180 ON X# GOSUB 500, 600
+190 X# = 7
+200 ON X# GOTO 500, 600
+210 PRINT "FELL THROUGH"
+220 REM BEGIN/BEND makes an IF span lines.
+230 IF I# = 2 THEN BEGIN
+240   PRINT "IN BLOCK"
+250 BEND
+260 IF I# = 99 THEN BEGIN
+270   PRINT "NEVER SEEN EITHER"
+280 BEND
+290 END
+500 PRINT "SUB ONE"
+510 RETURN
+600 PRINT "SUB TWO"
+610 RETURN

tests/language/structure/loops.txt

@@ -0,0 +1,8 @@
+WHILE 0
+WHILE 1
+WHILE 2
+UNTIL 0
+UNTIL 1
+SUB TWO
+FELL THROUGH
+IN BLOCK

tests/machine_verbs.c

@@ -0,0 +1,115 @@
+/**
+ * @file machine_verbs.c
+ * @brief Tests the group J verbs: FETCH, STASH and SYS.
+ *
+ * These operate on real process memory, exactly as POKE, PEEK and POINTER
+ * already do, so the tests give them real addresses -- their own buffers, taken
+ * with POINTER the way a BASIC program would have to.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Run a program to completion in RUN mode, from a string. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief STASH copies bytes, and FETCH copies them back.
+ *
+ * Addresses come from POINTER, which is the only way a BASIC program can name a
+ * real one. Two string variables give two buffers to copy between.
+ */
+static void test_copy(void)
+{
+    TEST_REQUIRE_OK(run_program("10 A$ = \"SOURCE\"\n"
+				"20 B$ = \"XXXXXX\"\n"
+				"30 STASH 7, POINTER(A$), POINTER(B$)\n"
+				"40 PRINT B$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "SOURCE\n");
+    harness_stop();
+
+    /* FETCH is the same copy; there is no expansion RAM to distinguish them. */
+    TEST_REQUIRE_OK(run_program("10 A$ = \"HELLO!\"\n"
+				"20 B$ = \"......\"\n"
+				"30 FETCH 7, POINTER(A$), POINTER(B$)\n"
+				"40 PRINT B$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "HELLO!\n");
+    harness_stop();
+}
+
+/** @brief A zero-length copy does nothing, and a negative one is refused. */
+static void test_copy_bounds(void)
+{
+    TEST_REQUIRE_OK(run_program("10 A$ = \"ABC\"\n"
+				"20 B$ = \"XYZ\"\n"
+				"30 STASH 0, POINTER(A$), POINTER(B$)\n"
+				"40 PRINT B$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "XYZ\n");
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 A$ = \"ABC\"\n"
+				"20 STASH -1, POINTER(A$), POINTER(A$)\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "negative number of bytes") != NULL,
+		 "a negative count should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    /* Address zero is refused rather than dereferenced. */
+    TEST_REQUIRE_OK(run_program("10 A$ = \"ABC\"\n"
+				"20 STASH 3, 0, POINTER(A$)\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "address zero") != NULL,
+		 "address zero should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    /* Too few arguments is a syntax error naming the form. */
+    TEST_REQUIRE_OK(run_program("10 STASH 3\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "source address") != NULL,
+		 "an incomplete STASH should name the form, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief SYS parses and is then refused by name.
+ *
+ * Parsing first is what keeps a listing containing SYS loadable and listable; it
+ * is only running it that has no meaning.
+ */
+static void test_sys_refused(void)
+{
+    TEST_REQUIRE_OK(run_program("10 SYS 65490\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "no 6502") != NULL,
+		 "SYS should be refused with a reason, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    /*
+     * A SYS with no address is a syntax error, not the device refusal -- and it
+     * names the verb. It used to fail deep in the expression parser with
+     * "peek() returned nil token!", which every verb taking an argument list
+     * shared.
+     */
+    TEST_REQUIRE_OK(run_program("10 SYS\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "SYS expected at least one argument") != NULL,
+		 "a bare SYS should name the verb, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+int main(void)
+{
+    test_copy();
+    test_copy_bounds();
+    test_sys_refused();
+    return akbasic_test_failures;
+}

tests/mockdevice.h

@@ -24,6 +24,7 @@
 #include <akbasic/error.h>
 #include <akbasic/graphics.h>
 #include <akbasic/input.h>
+#include <akbasic/sprite.h>
 
 /** @brief Room for the call log. Longer than any test needs; overflow truncates loudly. */
 #define MOCK_LOG_SIZE		8192
@@ -50,12 +51,17 @@ typedef struct
     int keys[MOCK_MAX_KEYS];
     int keycount;
     int keynext;
+
+    /* Sprites */
+    uint16_t collisions;	/* what the next collisions() call reports	*/
+    int patternbytes[AKBASIC_MAX_SPRITES];  /* bytes the last define() carried, per sprite */
 } akbasic_MockDevice;
 
 static akbasic_MockDevice MOCK;
 static akbasic_GraphicsBackend MOCK_GRAPHICS;
 static akbasic_AudioBackend MOCK_AUDIO;
 static akbasic_InputBackend MOCK_INPUT;
+static akbasic_SpriteBackend MOCK_SPRITES;
 
 /**
  * @brief Append one formatted call to the log.
@@ -288,6 +294,120 @@ static akerr_ErrorContext *mock_flush_keys(akbasic_InputBackend *self)
     SUCCEED_RETURN(errctx);
 }
 
+/* ---------------------------------------------------------------- sprites -- */
+
+/**
+ * @brief Refuse a sprite number the way a real backend has to.
+ *
+ * Sprites are 1-based at this boundary -- see sprite.h -- so an off-by-one in a
+ * verb handler shows up here as AKBASIC_ERR_BOUNDS rather than as a silently
+ * mis-addressed sprite.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *mock_sprite_range(int n)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (n >= 1 && n <= AKBASIC_MAX_SPRITES), AKBASIC_ERR_BOUNDS,
+		     "mock sprite %d out of range", n);
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_spr_define(akbasic_SpriteBackend *self, int n, const uint8_t *pattern, int bytes, akbasic_Color fg, akbasic_Color bg)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    PASS(errctx, mock_sprite_range(n));
+    FAIL_ZERO_RETURN(errctx, (pattern != NULL), AKERR_NULLPOINTER, "NULL pattern in define");
+    MOCK.patternbytes[n - 1] = bytes;
+    /*
+     * The first and last bytes rather than all 63: enough to tell one pattern
+     * from another and to catch a byte order that came through reversed,
+     * without a log line no human can read.
+     */
+    mock_log("sprdef %d %d bytes %02x..%02x fg=%d,%d,%d bg=%d,%d,%d\n",
+	     n, bytes, pattern[0], pattern[bytes - 1],
+	     fg.r, fg.g, fg.b, bg.r, bg.g, bg.b);
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_spr_define_shape(akbasic_SpriteBackend *self, int n, int handle)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    PASS(errctx, mock_sprite_range(n));
+    mock_log("sprshape %d from %d\n", n, handle);
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_spr_define_file(akbasic_SpriteBackend *self, int n, const char *path, const char *root)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    PASS(errctx, mock_sprite_range(n));
+    FAIL_ZERO_RETURN(errctx, (path != NULL), AKERR_NULLPOINTER, "NULL path in define_file");
+    /*
+     * The root is logged as well as the path. Whether the interpreter passed the
+     * running program's directory through is the whole of what this repository
+     * owns about relative asset paths -- resolving one is libakgl's job, and
+     * there is no way to see it happen from a mock.
+     */
+    mock_log("sprfile %d %s root=%s\n", n, path, (root != NULL ? root : "(none)"));
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_spr_show(akbasic_SpriteBackend *self, int n, bool visible)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    PASS(errctx, mock_sprite_range(n));
+    mock_log("sprshow %d %d\n", n, (visible ? 1 : 0));
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_spr_move(akbasic_SpriteBackend *self, int n, double x, double y)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    PASS(errctx, mock_sprite_range(n));
+    mock_log("sprmove %d %.2f,%.2f\n", n, x, y);
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_spr_configure(akbasic_SpriteBackend *self, int n, akbasic_Color color, bool xexpand, bool yexpand, bool behind)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    PASS(errctx, mock_sprite_range(n));
+    mock_log("sprcfg %d %d,%d,%d x%d y%d b%d\n", n, color.r, color.g, color.b,
+	     (xexpand ? 1 : 0), (yexpand ? 1 : 0), (behind ? 1 : 0));
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_spr_shared_colors(akbasic_SpriteBackend *self, akbasic_Color c1, akbasic_Color c2)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    mock_log("sprshared %d,%d,%d %d,%d,%d\n", c1.r, c1.g, c1.b, c2.r, c2.g, c2.b);
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *mock_spr_collisions(akbasic_SpriteBackend *self, uint16_t *mask)
+{
+    PREPARE_ERROR(errctx);
+    (void)self;
+
+    FAIL_ZERO_RETURN(errctx, (mask != NULL), AKERR_NULLPOINTER, "NULL mask in collisions");
+    *mask = MOCK.collisions;
+    SUCCEED_RETURN(errctx);
+}
+
 /* ---------------------------------------------------------------- fixture -- */
 
 /** @brief Reset the recorder and populate all three vtables. */
@@ -325,6 +445,23 @@ static void mock_devices_init(void)
     MOCK_INPUT.self		= &MOCK;
     MOCK_INPUT.poll_key		= mock_poll_key;
     MOCK_INPUT.flush_keys	= mock_flush_keys;
+
+    MOCK_SPRITES.self		= &MOCK;
+    MOCK_SPRITES.define		= mock_spr_define;
+    MOCK_SPRITES.define_shape	= mock_spr_define_shape;
+    MOCK_SPRITES.define_file	= mock_spr_define_file;
+    MOCK_SPRITES.show		= mock_spr_show;
+    MOCK_SPRITES.move		= mock_spr_move;
+    MOCK_SPRITES.configure	= mock_spr_configure;
+    MOCK_SPRITES.shared_colors	= mock_spr_shared_colors;
+    MOCK_SPRITES.collisions	= mock_spr_collisions;
+}
+
+/** @brief Set what the next collisions() call will report. Bit n-1 is sprite n. */
+__attribute__((unused))
+static void mock_set_collisions(uint16_t mask)
+{
+    MOCK.collisions = mask;
 }
 
 /** @brief Prime the input backend with keystrokes GET will drain in order. */

tests/read_data.c

@@ -0,0 +1,201 @@
+/**
+ * @file read_data.c
+ * @brief Tests READ, DATA and RESTORE against the pre-scanned item list.
+ *
+ * The reference's READ does not read: it records its identifiers, sets the scope
+ * waiting for a DATA verb, and lets execution skip forward until one turns up.
+ * Two things follow, and both are asserted here as the defects they were --
+ * TODO.md section 6.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Run a program to completion in RUN mode, from a string. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief The ordinary case: DATA below its READ, filled in order. */
+static void test_read_in_order(void)
+{
+    TEST_REQUIRE_OK(run_program("10 READ A$, B#\n"
+				"20 DATA \"HELLO\", 12345\n"
+				"30 PRINT A$\n"
+				"40 PRINT B#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "HELLO\n12345\n");
+    harness_stop();
+}
+
+/**
+ * @brief A DATA line *above* its READ is found.
+ *
+ * It was not: skipping forward from the READ ran off the end of the program in
+ * silence, and a second READ re-read the same line.
+ */
+static void test_data_before_read(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA 1, 2\n"
+				"20 READ A#, B#\n"
+				"30 PRINT A#\n"
+				"40 PRINT B#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n2\n");
+    harness_stop();
+}
+
+/**
+ * @brief Lines between a READ and its DATA are not skipped.
+ *
+ * They were, because the skip-forward *was* the implementation. A C128 runs
+ * them: READ takes the next item and execution carries on normally.
+ */
+static void test_no_skipping(void)
+{
+    TEST_REQUIRE_OK(run_program("10 READ A#\n"
+				"20 PRINT \"BETWEEN\"\n"
+				"30 DATA 5\n"
+				"40 PRINT A#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "BETWEEN\n5\n");
+    harness_stop();
+}
+
+/** @brief Successive READs walk the cursor along rather than starting over. */
+static void test_cursor_advances(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA 1, 2, 3\n"
+				"20 READ A#\n"
+				"30 READ B#\n"
+				"40 READ C#\n"
+				"50 PRINT A# + B# + C#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "6\n");
+    harness_stop();
+}
+
+/** @brief Bare RESTORE goes back to the first item. */
+static void test_restore(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA 1, 2, 3\n"
+				"20 READ A#\n"
+				"30 RESTORE\n"
+				"40 READ B#\n"
+				"50 PRINT A#\n"
+				"60 PRINT B#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n1\n");
+    harness_stop();
+}
+
+/** @brief RESTORE (line) starts again at the first item on or after that line. */
+static void test_restore_line(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA 1, 2\n"
+				"20 DATA 30, 40\n"
+				"30 RESTORE 20\n"
+				"40 READ A#, B#\n"
+				"50 PRINT A#\n"
+				"60 PRINT B#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "30\n40\n");
+    harness_stop();
+
+    /*
+     * A line with no DATA on it finds the next one that has some -- a program
+     * names the line it wants to read *from*, not one that must hold items.
+     */
+    TEST_REQUIRE_OK(run_program("10 DATA 1, 2\n"
+				"20 REM NOTHING HERE\n"
+				"30 DATA 99\n"
+				"40 RESTORE 20\n"
+				"50 READ A#\n"
+				"60 PRINT A#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "99\n");
+    harness_stop();
+}
+
+/** @brief Reading past the last item is reported rather than yielding zeroes. */
+static void test_out_of_data(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA 1\n"
+				"20 READ A#, B#\n"
+				"30 PRINT \"UNREACHED\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "OUT OF DATA") != NULL,
+		 "reading past the end should say so, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "UNREACHED") == NULL,
+		 "the program should have stopped, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief A quoted item read into a number is a mistake worth reporting. */
+static void test_type_mismatch(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA \"TEXT\"\n"
+				"20 READ A#\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "is a string") != NULL,
+		 "a quoted item read into a number should be refused, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+
+    /* An unquoted number read into a string is fine: it becomes its text. */
+    TEST_REQUIRE_OK(run_program("10 DATA 42\n"
+				"20 READ A$\n"
+				"30 PRINT A$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "42\n");
+    harness_stop();
+}
+
+/** @brief A quoted item may hold commas and colons; that is what quotes are for. */
+static void test_quoted_items(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA \"ONE, TWO\", \"A:B\"\n"
+				"20 READ A$, B$\n"
+				"30 PRINT A$\n"
+				"40 PRINT B$\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "ONE, TWO\nA:B\n");
+    harness_stop();
+}
+
+/** @brief A colon ends a DATA statement, as it does on a Commodore. */
+static void test_colon_ends_data(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA 1, 2 : PRINT \"AFTER DATA\"\n"
+				"20 READ A#, B#\n"
+				"30 PRINT A# + B#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "AFTER DATA\n3\n");
+    harness_stop();
+}
+
+/** @brief A float item fills a float variable with its fractional part intact. */
+static void test_float_items(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DATA 1.5\n"
+				"20 READ A%\n"
+				"30 PRINT A%\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1.500000\n");
+    harness_stop();
+}
+
+int main(void)
+{
+    test_read_in_order();
+    test_data_before_read();
+    test_no_skipping();
+    test_cursor_advances();
+    test_restore();
+    test_restore_line();
+    test_out_of_data();
+    test_type_mismatch();
+    test_quoted_items();
+    test_colon_ends_data();
+    test_float_items();
+    return akbasic_test_failures;
+}

tests/renumber.c

@@ -0,0 +1,243 @@
+/**
+ * @file renumber.c
+ * @brief Tests RENUMBER: the lines move, and every reference to one moves with it.
+ *
+ * The reason this verb was deferred rather than written early is that the easy
+ * half is worthless on its own. Moving lines is a permutation; a RENUMBER that
+ * did only that would silently break every branch in the program. So most of
+ * what is asserted here is the *rewriting*, including the two things a textual
+ * rewrite can get wrong: a number inside a string literal, and a target naming a
+ * line that does not exist.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Load a program without running it. */
+static akerr_ErrorContext AKERR_NOIGNORE *load(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Run whatever is loaded, bounded so a broken branch fails rather than hangs. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_loaded(void)
+{
+    PREPARE_ERROR(errctx);
+
+    HARNESS_RUNTIME.environment->nextline = 0;
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 40000));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief Lines land on the numbers asked for, in source order. */
+static void test_lines_move(void)
+{
+    TEST_REQUIRE_OK(load("5 PRINT \"A\"\n"
+			 "7 PRINT \"B\"\n"
+			 "9 PRINT \"C\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "PRINT \"A\"");
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[20].code, "PRINT \"B\"");
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[30].code, "PRINT \"C\"");
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[5].code, "");
+    harness_stop();
+
+    /* A different start and increment. */
+    TEST_REQUIRE_OK(load("1 PRINT \"A\"\n2 PRINT \"B\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 100, 5, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[100].code, "PRINT \"A\"");
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[105].code, "PRINT \"B\"");
+    harness_stop();
+}
+
+/** @brief GOTO and GOSUB targets follow the lines they name. */
+static void test_branches_rewritten(void)
+{
+    TEST_REQUIRE_OK(load("5 GOTO 9\n"
+			 "7 PRINT \"SKIPPED\"\n"
+			 "9 PRINT \"ARRIVED\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "GOTO 30");
+    TEST_REQUIRE_OK(run_loaded());
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "ARRIVED\n");
+    harness_stop();
+
+    TEST_REQUIRE_OK(load("5 GOSUB 9\n"
+			 "6 END\n"
+			 "9 PRINT \"SUB\"\n"
+			 "11 RETURN\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "GOSUB 30");
+    TEST_REQUIRE_OK(run_loaded());
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "SUB\n");
+    harness_stop();
+}
+
+/** @brief A GOTO after THEN or ELSE is rewritten; it is not at a statement start. */
+static void test_branch_inside_a_condition(void)
+{
+    TEST_REQUIRE_OK(load("5 IF 1 == 1 THEN GOTO 9 ELSE GOTO 7\n"
+			 "7 PRINT \"ELSE\"\n"
+			 "9 PRINT \"THEN\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "IF 1 == 1 THEN GOTO 30 ELSE GOTO 20");
+    harness_stop();
+}
+
+/** @brief ON's whole target list is rewritten, not just the first entry. */
+static void test_on_list_rewritten(void)
+{
+    TEST_REQUIRE_OK(load("5 ON 2 GOTO 7, 9\n"
+			 "7 PRINT \"ONE\"\n"
+			 "9 PRINT \"TWO\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    /* The original spacing survives; only the numbers change. */
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "ON 2 GOTO 20, 30");
+    TEST_REQUIRE_OK(run_loaded());
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "TWO\n");
+    harness_stop();
+}
+
+/** @brief RESTORE, TRAP and COLLISION targets are rewritten too. */
+static void test_other_verbs_rewritten(void)
+{
+    TEST_REQUIRE_OK(load("5 RESTORE 9\n"
+			 "7 TRAP 9\n"
+			 "8 COLLISION 1, 9\n"
+			 "9 DATA 1\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "RESTORE 40");
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[20].code, "TRAP 40");
+    /* COLLISION's handler is its *second* argument, so the type is left alone. */
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[30].code, "COLLISION 1, 40");
+    harness_stop();
+}
+
+/**
+ * @brief A number inside a string literal is not a line reference.
+ *
+ * The one thing a textual rewrite is most likely to get wrong, and the reason
+ * the rewrite has to understand quotes at all.
+ */
+static void test_string_literals_untouched(void)
+{
+    TEST_REQUIRE_OK(load("5 PRINT \"GOTO 9 IS TEXT\"\n"
+			 "9 PRINT \"END\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "PRINT \"GOTO 9 IS TEXT\"");
+    harness_stop();
+}
+
+/**
+ * @brief A target naming no line is left alone rather than invented.
+ *
+ * `GOTO 9999` in a program with no line 9999 is already broken; rewriting it to
+ * point somewhere would hide that rather than fix it.
+ */
+static void test_dangling_target_left_alone(void)
+{
+    TEST_REQUIRE_OK(load("5 GOTO 9999\n"
+			 "9 PRINT \"HERE\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "GOTO 9999");
+    harness_stop();
+}
+
+/** @brief A label target needs no rewriting, which is the case for using labels. */
+static void test_labels_need_no_rewriting(void)
+{
+    TEST_REQUIRE_OK(load("5 GOTO DONE\n"
+			 "7 PRINT \"SKIPPED\"\n"
+			 "9 LABEL DONE\n"
+			 "11 PRINT \"ARRIVED\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 0));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "GOTO DONE");
+    TEST_REQUIRE_OK(run_loaded());
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "ARRIVED\n");
+    harness_stop();
+}
+
+/** @brief RENUMBER from a line leaves everything before it where it was. */
+static void test_partial_renumber(void)
+{
+    TEST_REQUIRE_OK(load("10 PRINT \"KEPT\"\n"
+			 "55 PRINT \"MOVED\"\n"
+			 "57 PRINT \"ALSO MOVED\"\n"));
+    TEST_REQUIRE_OK(akbasic_renumber(&HARNESS_RUNTIME, 100, 10, 50));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "PRINT \"KEPT\"");
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[100].code, "PRINT \"MOVED\"");
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[110].code, "PRINT \"ALSO MOVED\"");
+    harness_stop();
+}
+
+/** @brief A renumbering that would land on a kept line is refused, not applied. */
+static void test_collision_refused(void)
+{
+    TEST_REQUIRE_OK(load("10 PRINT \"KEPT\"\n"
+			 "55 PRINT \"MOVED\"\n"));
+    TEST_REQUIRE_STATUS(akbasic_renumber(&HARNESS_RUNTIME, 10, 10, 50), AKBASIC_ERR_VALUE);
+    /* And nothing moved: the map is built and checked before anything is written. */
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "PRINT \"KEPT\"");
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[55].code, "PRINT \"MOVED\"");
+    harness_stop();
+}
+
+/** @brief A non-positive increment is refused rather than looping forever. */
+static void test_bad_arguments(void)
+{
+    TEST_REQUIRE_OK(load("10 PRINT \"A\"\n"));
+    TEST_REQUIRE_STATUS(akbasic_renumber(&HARNESS_RUNTIME, 10, 0, 0), AKBASIC_ERR_VALUE);
+    TEST_REQUIRE_STATUS(akbasic_renumber(&HARNESS_RUNTIME, 10, -1, 0), AKBASIC_ERR_VALUE);
+    TEST_REQUIRE_STATUS(akbasic_renumber(&HARNESS_RUNTIME, 0, 10, 0), AKBASIC_ERR_VALUE);
+    TEST_REQUIRE_STATUS(akbasic_renumber(NULL, 10, 10, 0), AKERR_NULLPOINTER);
+    harness_stop();
+}
+
+/** @brief The verb reaches all of it, with its defaults. */
+static void test_verb(void)
+{
+    akbasic_ASTLeaf *leaf = NULL;
+    akbasic_Value *out = NULL;
+
+    TEST_REQUIRE_OK(load("5 GOTO 9\n7 PRINT \"SKIPPED\"\n9 PRINT \"ARRIVED\"\n"));
+    TEST_REQUIRE_OK(akbasic_environment_zero(HARNESS_RUNTIME.environment));
+    TEST_REQUIRE_OK(harness_parse("RENUMBER", &leaf));
+    TEST_REQUIRE_OK(akbasic_runtime_evaluate(&HARNESS_RUNTIME, leaf, &out));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[10].code, "GOTO 30");
+    harness_stop();
+
+    /* And with arguments. */
+    TEST_REQUIRE_OK(load("5 GOTO 9\n9 PRINT \"X\"\n"));
+    TEST_REQUIRE_OK(akbasic_environment_zero(HARNESS_RUNTIME.environment));
+    TEST_REQUIRE_OK(harness_parse("RENUMBER 100, 5", &leaf));
+    TEST_REQUIRE_OK(akbasic_runtime_evaluate(&HARNESS_RUNTIME, leaf, &out));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.source[100].code, "GOTO 105");
+    harness_stop();
+}
+
+int main(void)
+{
+    test_lines_move();
+    test_branches_rewritten();
+    test_branch_inside_a_condition();
+    test_on_list_rewritten();
+    test_other_verbs_rewritten();
+    test_string_literals_untouched();
+    test_dangling_target_left_alone();
+    test_labels_need_no_rewriting();
+    test_partial_renumber();
+    test_collision_refused();
+    test_bad_arguments();
+    test_verb();
+    return akbasic_test_failures;
+}

tests/sprite_verbs.c

@@ -0,0 +1,525 @@
+/**
+ * @file sprite_verbs.c
+ * @brief Tests the group H verbs against the recording mock backend.
+ *
+ * Same shape as tests/graphics_verbs.c and for the same reason: these verbs emit
+ * nothing a golden file can compare, so the assertions are on the call log --
+ * what reached the device, in what order, with what geometry. Running a real
+ * BASIC line rather than calling the handler directly is deliberate; it
+ * exercises the dispatch-table row and the parse handler too, which is where an
+ * added verb is most likely to be wrong. MOVSPR in particular has a parse
+ * handler all its own.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+#include <akbasic/sprite.h>
+
+#include "harness.h"
+#include "mockdevice.h"
+#include "testutil.h"
+
+/** @brief Bring up a runtime with the mock devices attached and a program loaded. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    mock_devices_init();
+    PASS(errctx, akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS,
+					     &MOCK_AUDIO, &MOCK_INPUT, &MOCK_SPRITES));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief SPRITE sets what it is given and leaves alone what it is not.
+ *
+ * The "leaves alone" half is the one worth asserting: BASIC 7.0 lets every
+ * argument after the number be omitted, so a handler that treated a missing
+ * argument as zero would silently turn a sprite off on its way to changing the
+ * colour.
+ */
+static void test_sprite(void)
+{
+    TEST_REQUIRE_OK(run_program("10 SPRITE 1, 1, 3, 0, 1, 0\n"));
+    /* Palette index 3 is red: 0x88, 0x39, 0x32 in src/graphics_tables.c. */
+    TEST_REQUIRE_STR(MOCK.log,
+		     "sprcfg 1 136,57,50 x1 y0 b0\n"
+		     "sprshow 1 1\n");
+    TEST_REQUIRE(HARNESS_RUNTIME.sprite_state.sprites[0].enabled, "SPRITE 1,1 should enable it");
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.sprite_state.sprites[0].colorindex, 3);
+    harness_stop();
+
+    /* A second SPRITE naming only the number changes nothing at all. */
+    TEST_REQUIRE_OK(run_program("10 SPRITE 1, 1, 3, 0, 1, 0\n"
+				"20 SPRITE 1\n"));
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.sprite_state.sprites[0].colorindex, 3);
+    TEST_REQUIRE(HARNESS_RUNTIME.sprite_state.sprites[0].xexpand,
+		 "an omitted argument should leave x-expand alone");
+    TEST_REQUIRE(HARNESS_RUNTIME.sprite_state.sprites[0].enabled,
+		 "an omitted argument should leave the enable bit alone");
+    harness_stop();
+
+    /* Sprite 0 and sprite 9 do not exist. */
+    TEST_REQUIRE_OK(run_program("10 SPRITE 9, 1\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 1..8") != NULL,
+		 "sprite 9 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 SPRITE 1, 1, 17\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 1..16") != NULL,
+		 "colour 17 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief All four MOVSPR forms, which is really a test of its parse handler.
+ *
+ * The separators are the whole difference between them and they exist nowhere
+ * else in the language, so this is the only thing that says `;` and `#` are
+ * scanned at all.
+ */
+static void test_movspr(void)
+{
+    /* Absolute. */
+    TEST_REQUIRE_OK(run_program("10 MOVSPR 1, 100, 50\n"));
+    TEST_REQUIRE_STR(MOCK.log, "sprmove 1 100.00,50.00\n");
+    harness_stop();
+
+    /* Relative: a signed coordinate is an offset, not a position. */
+    TEST_REQUIRE_OK(run_program("10 MOVSPR 1, 100, 50\n"
+				"20 MOVSPR 1, +10, -20\n"));
+    TEST_REQUIRE_STR(MOCK.log,
+		     "sprmove 1 100.00,50.00\n"
+		     "sprmove 1 110.00,30.00\n");
+    harness_stop();
+
+    /*
+     * Polar: distance first, then a bearing clockwise from vertical. 90 degrees
+     * is due right, so the whole distance lands on x and none of it on y --
+     * which is the assertion that catches a sine and cosine swapped over.
+     */
+    TEST_REQUIRE_OK(run_program("10 MOVSPR 1, 100, 50\n"
+				"20 MOVSPR 1, 10 ; 90\n"));
+    TEST_REQUIRE_STR(MOCK.log,
+		     "sprmove 1 100.00,50.00\n"
+		     "sprmove 1 110.00,50.00\n");
+    harness_stop();
+
+    /* And 0 degrees is straight up, which is *minus* y on a screen. */
+    TEST_REQUIRE_OK(run_program("10 MOVSPR 1, 100, 50\n"
+				"20 MOVSPR 1, 10 ; 0\n"));
+    TEST_REQUIRE_STR(MOCK.log,
+		     "sprmove 1 100.00,50.00\n"
+		     "sprmove 1 100.00,40.00\n");
+    harness_stop();
+
+    /*
+     * Continuous. Nothing moves on the statement itself -- the sprite starts
+     * moving on the next step, paced off the host's clock -- so what is asserted
+     * here is that the speed was recorded and the device was *not* told to move.
+     */
+    TEST_REQUIRE_OK(run_program("10 MOVSPR 1, 45 # 8\n"));
+    TEST_REQUIRE_STR(MOCK.log, "");
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.sprite_state.sprites[0].speed, 8);
+    TEST_REQUIRE_FEQ(HARNESS_RUNTIME.sprite_state.sprites[0].angle, 45.0);
+    harness_stop();
+
+    /* Speed 16 does not exist. */
+    TEST_REQUIRE_OK(run_program("10 MOVSPR 1, 45 # 16\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 0..15") != NULL,
+		 "speed 16 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief Continuous motion is paced off the host's clock, not off step count.
+ *
+ * The service runs on every step, so a program that does nothing still moves --
+ * and a host that never sets a clock still gets a still picture rather than a
+ * sprite tearing across the screen at step rate.
+ */
+static void test_continuous_motion(void)
+{
+    double stopped = 0.0;
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    mock_devices_init();
+    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, NULL, NULL,
+						&MOCK_SPRITES));
+    TEST_REQUIRE_OK(akbasic_runtime_settime(&HARNESS_RUNTIME, 1000));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME,
+					 "1 MOVSPR 1, 90 # 10\n"
+					 "2 GOTO 2\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+
+    /* Line 0 and line 1, with the clock standing still. */
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE_FEQ(HARNESS_RUNTIME.sprite_state.sprites[0].x, 0.0);
+
+    /*
+     * One second later: speed 10 at AKBASIC_SPRITE_SPEED_PIXELS_PER_SECOND
+     * apiece, due right, so 50 pixels of x and none of y.
+     */
+    TEST_REQUIRE_OK(akbasic_runtime_settime(&HARNESS_RUNTIME, 2000));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE_FEQ(HARNESS_RUNTIME.sprite_state.sprites[0].x,
+		     10.0 * AKBASIC_SPRITE_SPEED_PIXELS_PER_SECOND);
+    TEST_REQUIRE_FEQ(HARNESS_RUNTIME.sprite_state.sprites[0].y, 0.0);
+
+    /*
+     * Speed 0 stops it where it is. The step that runs the MOVSPR services the
+     * motion *before* it runs the line -- the sprite is still moving when that
+     * step begins -- so one more second's worth lands first; where it stopped is
+     * whatever it reads after that, and the point is that six more seconds do
+     * not move it again.
+     */
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, "1 MOVSPR 1, 90 # 0\n"));
+    HARNESS_RUNTIME.environment->nextline = 1;
+    TEST_REQUIRE_OK(akbasic_runtime_settime(&HARNESS_RUNTIME, 3000));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    stopped = HARNESS_RUNTIME.sprite_state.sprites[0].x;
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.sprite_state.sprites[0].speed, 0);
+
+    TEST_REQUIRE_OK(akbasic_runtime_settime(&HARNESS_RUNTIME, 9000));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE_FEQ(HARNESS_RUNTIME.sprite_state.sprites[0].x, stopped);
+    harness_stop();
+}
+
+/** @brief SPRCOLOR sets the two shared registers, and RSPCOLOR reads them back. */
+static void test_sprcolor(void)
+{
+    TEST_REQUIRE_OK(run_program("10 SPRCOLOR 5, 7\n"
+				"20 PRINT RSPCOLOR(1)\n"
+				"30 PRINT RSPCOLOR(2)\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "5\n7\n");
+    harness_stop();
+
+    /* One argument leaves the other register alone. */
+    TEST_REQUIRE_OK(run_program("10 SPRCOLOR 5, 7\n"
+				"20 SPRCOLOR 9\n"
+				"30 PRINT RSPCOLOR(1)\n"
+				"40 PRINT RSPCOLOR(2)\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "9\n7\n");
+    harness_stop();
+}
+
+/**
+ * @brief The pattern bit order, asserted once here rather than trusted per backend.
+ *
+ * Three bytes per row, most significant bit leftmost. Getting it backwards would
+ * mirror every published sprite horizontally, and nothing else in the suite can
+ * see it: a SPRSAV test fills the array with 0xff, where a reversed bit order
+ * produces the identical picture.
+ */
+static void test_pattern_bit_order(void)
+{
+    uint8_t pattern[AKBASIC_SPRITE_PATTERN_BYTES];
+    uint8_t pixels[AKBASIC_SPRITE_WIDTH * AKBASIC_SPRITE_HEIGHT];
+    int i = 0;
+
+    memset(pattern, 0, sizeof(pattern));
+    /* Row 0: the leftmost pixel and nothing else. */
+    pattern[0] = 0x80;
+    /* Row 1: the rightmost pixel of all 24, which is the low bit of the third byte. */
+    pattern[5] = 0x01;
+    /* Row 2: the ninth pixel across, which is the high bit of the second byte. */
+    pattern[7] = 0x80;
+
+    TEST_REQUIRE_OK(akbasic_sprite_unpack(pattern, sizeof(pattern), pixels));
+    TEST_REQUIRE_INT(pixels[0], 1);
+    TEST_REQUIRE_INT(pixels[1], 0);
+    TEST_REQUIRE_INT(pixels[AKBASIC_SPRITE_WIDTH + (AKBASIC_SPRITE_WIDTH - 1)], 1);
+    TEST_REQUIRE_INT(pixels[AKBASIC_SPRITE_WIDTH + (AKBASIC_SPRITE_WIDTH - 2)], 0);
+    TEST_REQUIRE_INT(pixels[(2 * AKBASIC_SPRITE_WIDTH) + 8], 1);
+    TEST_REQUIRE_INT(pixels[(2 * AKBASIC_SPRITE_WIDTH) + 7], 0);
+
+    /* And every other pixel is clear. */
+    for ( i = 3 * AKBASIC_SPRITE_WIDTH; i < AKBASIC_SPRITE_WIDTH * AKBASIC_SPRITE_HEIGHT; i++ ) {
+	TEST_REQUIRE_INT(pixels[i], 0);
+    }
+
+    /* A pattern that is not 63 bytes is not a pattern. */
+    TEST_REQUIRE_STATUS(akbasic_sprite_unpack(pattern, 8, pixels), AKBASIC_ERR_BOUNDS);
+    TEST_REQUIRE_STATUS(akbasic_sprite_unpack(NULL, sizeof(pattern), pixels), AKERR_NULLPOINTER);
+}
+
+/**
+ * @brief SPRSAV takes a pattern from a DIMmed integer array.
+ *
+ * The array form is ours rather than BASIC 7.0's, because a value in this
+ * interpreter carries a NUL-terminated string and a C128 puts 63 raw bytes in
+ * one -- a string that cannot hold a zero byte cannot hold a sprite. See
+ * TODO.md section 5.
+ */
+static void test_sprsav_from_array(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DIM P#(63)\n"
+				"20 FOR I# = 0 TO 62\n"
+				"30 P#(I#) = 255\n"
+				"40 NEXT I#\n"
+				"50 P#(62) = 129\n"
+				"60 SPRSAV P#, 1\n"));
+    TEST_REQUIRE(strstr(MOCK.log, "sprdef 1 63 bytes ff..81") != NULL,
+		 "the whole pattern should have reached the device, got \"%s\"", MOCK.log);
+    TEST_REQUIRE(HARNESS_RUNTIME.sprite_state.sprites[0].defined,
+		 "SPRSAV should have marked the sprite defined");
+    harness_stop();
+
+    /* An array too small to be a pattern is a program that has miscounted. */
+    TEST_REQUIRE_OK(run_program("10 DIM P#(8)\n"
+				"20 SPRSAV P#, 1\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "sprite pattern is 63") != NULL,
+		 "a short array should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief SPRSAV takes a region SSHAPE saved, told apart by its handle prefix. */
+static void test_sprsav_from_shape(void)
+{
+    TEST_REQUIRE_OK(run_program("10 SSHAPE A$, 0, 0, 24, 21\n"
+				"20 SPRSAV A$, 2\n"));
+    TEST_REQUIRE(strstr(MOCK.log, "sprshape 2 from 0") != NULL,
+		 "the saved region should have reached the sprite device, got \"%s\"",
+		 MOCK.log);
+    harness_stop();
+}
+
+/**
+ * @brief SPRSAV takes an image file path, and the program's directory goes with it.
+ *
+ * Any string that is not an SSHAPE handle is a path. What can be asserted from a
+ * mock is the dispatch and the root -- whether a relative path actually resolves
+ * is libakgl's, and is asserted against real pixels in tests/akgl_backends.c.
+ */
+static void test_sprsav_from_file(void)
+{
+    TEST_REQUIRE_OK(harness_start(NULL));
+    mock_devices_init();
+    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, &MOCK_GRAPHICS, NULL, NULL,
+						&MOCK_SPRITES));
+    TEST_REQUIRE_OK(akbasic_runtime_set_source_path(&HARNESS_RUNTIME, "/games/asteroids/main.bas"));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, "10 SPRSAV \"ship.png\", 3\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    TEST_REQUIRE_STR(MOCK.log,
+		     "sprfile 3 ship.png root=/games/asteroids\n"
+		     "sprcfg 3 255,255,255 x0 y0 b0\n");
+    harness_stop();
+
+    /* No source path -- a REPL session, or a host that handed over a string. */
+    TEST_REQUIRE_OK(run_program("10 SPRSAV \"ship.png\", 3\n"));
+    TEST_REQUIRE(strstr(MOCK.log, "root=(none)") != NULL,
+		 "with no program file the backend should be told so, got \"%s\"", MOCK.log);
+    harness_stop();
+}
+
+/** @brief Writing a sprite back out is a disk operation, and is refused by name. */
+static void test_sprsav_refuses_to_write(void)
+{
+    TEST_REQUIRE_OK(run_program("10 SPRSAV 1, \"ship.png\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "disk operation") != NULL,
+		 "SPRSAV out to a file should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief COLLISION arms the interrupt, and refuses the two types nothing implements. */
+static void test_collision_arming(void)
+{
+    TEST_REQUIRE_OK(run_program("10 COLLISION 1, 100\n"));
+    TEST_REQUIRE(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].armed,
+		 "COLLISION 1 should have armed the sprite interrupt");
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].line, 100);
+    harness_stop();
+
+    /* A label is stored by name, not resolved here: the handler may be anywhere. */
+    TEST_REQUIRE_OK(run_program("10 COLLISION 1, BUMPED\n"));
+    TEST_REQUIRE_STR(HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].label, "BUMPED");
+    harness_stop();
+
+    /* Omitting the target disarms. */
+    TEST_REQUIRE_OK(run_program("10 COLLISION 1, 100\n"
+				"20 COLLISION 1\n"));
+    TEST_REQUIRE(!HARNESS_RUNTIME.interrupts[AKBASIC_INTERRUPT_SPRITE].armed,
+		 "COLLISION with no target should disarm");
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 COLLISION 2, 100\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "read back every frame") != NULL,
+		 "COLLISION 2 should be refused with a reason, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 COLLISION 3, 100\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "light pen") != NULL,
+		 "COLLISION 3 should be refused with a reason, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 COLLISION 4, 100\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 1..3") != NULL,
+		 "COLLISION 4 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief A collision the device reports enters the handler and shows up in BUMP.
+ *
+ * The whole path: the mock says two sprites overlap, the service ORs that into
+ * the accumulator and raises the interrupt, the step loop enters the handler,
+ * and BUMP() reports it and clears.
+ */
+static void test_collision_fires(void)
+{
+    TEST_REQUIRE_OK(harness_start(NULL));
+    mock_devices_init();
+    TEST_REQUIRE_OK(akbasic_runtime_set_devices(&HARNESS_RUNTIME, NULL, NULL, NULL,
+						&MOCK_SPRITES));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME,
+					 "1 COLLISION 1, 4\n"
+					 "2 PRINT \"MAIN\"\n"
+					 "3 GOTO 2\n"
+					 "4 PRINT \"HIT\"\n"
+					 "5 PRINT BUMP(1)\n"
+					 "6 RETURN\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+
+    /* Line 0 and the COLLISION, with nothing overlapping yet. */
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "");
+
+    /* Sprites 1 and 3 meet. */
+    mock_set_collisions(0x05);
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 2));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "HIT") != NULL,
+		 "the handler should have been entered, got \"%s\"", HARNESS_OUTPUT);
+
+    /* BUMP reports the mask, and clears it. */
+    mock_set_collisions(0);
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 1));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "5\n") != NULL,
+		 "BUMP should have reported sprites 1 and 3, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.sprite_state.bumped, 0);
+    harness_stop();
+}
+
+/** @brief The readbacks answer from interpreter state, so they need no device. */
+static void test_readbacks(void)
+{
+    TEST_REQUIRE_OK(harness_start(NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME,
+					 "10 MOVSPR 1, 120, 90\n"
+					 "20 PRINT RSPPOS(1, 0)\n"
+					 "30 PRINT RSPPOS(1, 1)\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    /*
+     * MOVSPR refuses for want of a device *after* it has moved the sprite, so
+     * the program stops on line 10 -- but the position took effect, which is
+     * what makes the state readable at all. Read it directly rather than through
+     * PRINT, since the program never got that far.
+     */
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "MOVSPR needs a sprite device") != NULL,
+		 "MOVSPR without a device should name itself, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE_FEQ(HARNESS_RUNTIME.sprite_state.sprites[0].x, 120.0);
+    TEST_REQUIRE_FEQ(HARNESS_RUNTIME.sprite_state.sprites[0].y, 90.0);
+    harness_stop();
+
+    /* With a device attached the same program prints. */
+    TEST_REQUIRE_OK(run_program("10 MOVSPR 1, 120, 90\n"
+				"20 PRINT RSPPOS(1, 0)\n"
+				"30 PRINT RSPPOS(1, 1)\n"
+				"40 PRINT RSPPOS(1, 2)\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "120\n90\n0\n");
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 SPRITE 1, 1, 6, 1, 1, 0\n"
+				"20 PRINT RSPRITE(1, 0)\n"
+				"30 PRINT RSPRITE(1, 1)\n"
+				"40 PRINT RSPRITE(1, 2)\n"
+				"50 PRINT RSPRITE(1, 3)\n"
+				"60 PRINT RSPRITE(1, 4)\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n6\n1\n1\n0\n");
+    harness_stop();
+
+    /* Out-of-range fields are refused rather than answered with a zero. */
+    TEST_REQUIRE_OK(run_program("10 PRINT RSPPOS(1, 9)\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside 0..2") != NULL,
+		 "RSPPOS field 9 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 PRINT RSPCOLOR(3)\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "is 1 or 2") != NULL,
+		 "RSPCOLOR register 3 should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief Every verb that needs a device says so by name when it has none.
+ *
+ * This is the standalone driver's situation, so it is the common path. SPRCOLOR
+ * and the readbacks are excluded on purpose: they only touch interpreter state
+ * and must keep working before a host has lent the script anything.
+ */
+static void test_no_device(void)
+{
+    TEST_REQUIRE_OK(harness_start(NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, "10 SPRSAV \"ship.png\", 1\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "SPRSAV needs a sprite device") != NULL,
+		 "SPRSAV without a device should name itself, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME,
+					 "10 SPRCOLOR 5, 7\n"
+					 "20 PRINT RSPCOLOR(1)\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 0));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "5\n");
+    harness_stop();
+}
+
+/** @brief NEW takes the sprites down with the program that defined them. */
+static void test_new_clears_sprites(void)
+{
+    akbasic_ASTLeaf *leaf = NULL;
+    akbasic_Value *out = NULL;
+
+    TEST_REQUIRE_OK(run_program("10 SPRITE 1, 1, 3\n"));
+    TEST_REQUIRE(HARNESS_RUNTIME.sprite_state.sprites[0].enabled, "SPRITE should have enabled it");
+
+    TEST_REQUIRE_OK(akbasic_environment_zero(HARNESS_RUNTIME.environment));
+    TEST_REQUIRE_OK(harness_parse("NEW", &leaf));
+    TEST_REQUIRE_OK(akbasic_runtime_evaluate(&HARNESS_RUNTIME, leaf, &out));
+
+    TEST_REQUIRE(!HARNESS_RUNTIME.sprite_state.sprites[0].enabled,
+		 "NEW should have taken the sprite state down");
+    TEST_REQUIRE(strstr(MOCK.log, "sprshow 1 0") != NULL,
+		 "NEW should have hidden the sprites on the device, got \"%s\"", MOCK.log);
+    harness_stop();
+}
+
+int main(void)
+{
+    test_sprite();
+    test_movspr();
+    test_continuous_motion();
+    test_sprcolor();
+    test_pattern_bit_order();
+    test_sprsav_from_array();
+    test_sprsav_from_shape();
+    test_sprsav_from_file();
+    test_sprsav_refuses_to_write();
+    test_collision_arming();
+    test_collision_fires();
+    test_readbacks();
+    test_no_device();
+    test_new_clears_sprites();
+    return akbasic_test_failures;
+}

tests/structure_verbs.c

@@ -0,0 +1,291 @@
+/**
+ * @file structure_verbs.c
+ * @brief Tests the group A verbs: DO, LOOP, BEGIN, BEND, ON and END.
+ *
+ * All of them are built on `waitingForCommand` -- a scope records the verb it is
+ * skipping forward to and nothing runs until that verb turns up -- so most of
+ * what is asserted here is *what did not run*. A block that should be skipped
+ * printing nothing is the whole point, and it is invisible unless the test says
+ * so explicitly.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Run a program to completion in RUN mode, from a string. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    /*
+     * Bounded. A defect in any of these verbs is a loop that never ends, and a
+     * suite that hangs tells you far less than one that fails.
+     */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 2000));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief A condition on the top runs the body while it holds, and not at all when it does not. */
+static void test_do_while(void)
+{
+    TEST_REQUIRE_OK(run_program("10 I# = 0\n"
+				"20 DO WHILE I# < 3\n"
+				"30 PRINT I#\n"
+				"40 I# = I# + 1\n"
+				"50 LOOP\n"
+				"60 PRINT \"DONE\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "0\n1\n2\nDONE\n");
+    harness_stop();
+
+    /* Already false: the body must not run once "just to see". */
+    TEST_REQUIRE_OK(run_program("10 I# = 5\n"
+				"20 DO WHILE I# < 3\n"
+				"30 PRINT \"NEVER\"\n"
+				"40 LOOP\n"
+				"50 PRINT \"AFTER\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "AFTER\n");
+    harness_stop();
+}
+
+/** @brief A condition on the bottom runs the body at least once. */
+static void test_loop_until(void)
+{
+    TEST_REQUIRE_OK(run_program("10 I# = 0\n"
+				"20 DO\n"
+				"30 PRINT I#\n"
+				"40 I# = I# + 1\n"
+				"50 LOOP UNTIL I# = 3\n"
+				"60 PRINT \"DONE\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "0\n1\n2\nDONE\n");
+    harness_stop();
+
+    /*
+     * Already true at the bottom, so exactly one pass. This is the difference
+     * between a bottom-tested loop and a top-tested one, and it is why BASIC has
+     * both forms.
+     */
+    TEST_REQUIRE_OK(run_program("10 I# = 99\n"
+				"20 DO\n"
+				"30 PRINT \"ONCE\"\n"
+				"40 LOOP UNTIL I# = 99\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "ONCE\n");
+    harness_stop();
+}
+
+/** @brief DO WHILE re-tests its own condition at the bottom, or it never ends. */
+static void test_do_while_retests(void)
+{
+    TEST_REQUIRE_OK(run_program("10 I# = 0\n"
+				"20 DO WHILE I# < 2\n"
+				"30 I# = I# + 1\n"
+				"40 LOOP\n"
+				"50 PRINT I#\n"));
+    /*
+     * That it printed at all is the assertion: a DO WHILE that failed to re-test
+     * its condition at the bottom never reaches line 50, and the bounded run
+     * above is what turns that into a failure rather than a hang.
+     */
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "2\n");
+    harness_stop();
+}
+
+/** @brief EXIT leaves a DO loop as well as a FOR loop. */
+static void test_exit_from_do(void)
+{
+    TEST_REQUIRE_OK(run_program("10 I# = 0\n"
+				"20 DO\n"
+				"30 I# = I# + 1\n"
+				"40 IF I# = 2 THEN EXIT\n"
+				"50 LOOP\n"
+				"60 PRINT \"EXITED AT \" + I#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "EXITED AT 2\n");
+    harness_stop();
+
+    /* And EXIT outside any loop is refused rather than doing something quiet. */
+    TEST_REQUIRE_OK(run_program("10 EXIT\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside the context of FOR or DO") != NULL,
+		 "a bare EXIT should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief An infinite DO...LOOP is left by GOTO, and the step bound proves it ran. */
+static void test_bare_do_loop(void)
+{
+    TEST_REQUIRE_OK(run_program("10 I# = 0\n"
+				"20 DO\n"
+				"30 I# = I# + 1\n"
+				"40 IF I# = 3 THEN GOTO 60\n"
+				"50 LOOP\n"
+				"60 PRINT I#\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "3\n");
+    harness_stop();
+}
+
+/** @brief ON picks the nth target, one-based, and falls through when there is none. */
+static void test_on_goto(void)
+{
+    TEST_REQUIRE_OK(run_program("10 X# = 2\n"
+				"20 ON X# GOTO 100, 200\n"
+				"30 PRINT \"FELL THROUGH\"\n"
+				"40 END\n"
+				"100 PRINT \"ONE\"\n"
+				"110 END\n"
+				"200 PRINT \"TWO\"\n"
+				"210 END\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "TWO\n");
+    harness_stop();
+
+    /*
+     * Out of range is not an error. BASIC 7.0 falls through to the next
+     * statement, which is what lets `ON X GOTO ...` be written without a bounds
+     * check in front of it. Zero and negative fall through the same way.
+     */
+    TEST_REQUIRE_OK(run_program("10 X# = 9\n"
+				"20 ON X# GOTO 100, 200\n"
+				"30 PRINT \"FELL THROUGH\"\n"
+				"40 END\n"
+				"100 PRINT \"ONE\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "FELL THROUGH\n");
+    harness_stop();
+
+    TEST_REQUIRE_OK(run_program("10 X# = 0\n"
+				"20 ON X# GOTO 100\n"
+				"30 PRINT \"FELL THROUGH\"\n"
+				"40 END\n"
+				"100 PRINT \"ONE\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "FELL THROUGH\n");
+    harness_stop();
+}
+
+/** @brief ON ... GOSUB returns to the line after the ON. */
+static void test_on_gosub(void)
+{
+    TEST_REQUIRE_OK(run_program("10 X# = 1\n"
+				"20 ON X# GOSUB 100, 200\n"
+				"30 PRINT \"BACK\"\n"
+				"40 END\n"
+				"100 PRINT \"SUB ONE\"\n"
+				"110 RETURN\n"
+				"200 PRINT \"SUB TWO\"\n"
+				"210 RETURN\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "SUB ONE\nBACK\n");
+    harness_stop();
+}
+
+/** @brief A label is a legal ON target, since it evaluates to a line number. */
+static void test_on_label(void)
+{
+    TEST_REQUIRE_OK(run_program("10 X# = 1\n"
+				"20 ON X# GOTO TARGET\n"
+				"30 PRINT \"FELL THROUGH\"\n"
+				"40 END\n"
+				"100 LABEL TARGET\n"
+				"110 PRINT \"AT LABEL\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "AT LABEL\n");
+    harness_stop();
+}
+
+/** @brief BEGIN/BEND makes an IF span lines, and the arm not taken skips all of them. */
+static void test_begin_bend(void)
+{
+    TEST_REQUIRE_OK(run_program("10 A# = 1\n"
+				"20 IF A# = 1 THEN BEGIN\n"
+				"30 PRINT \"IN BLOCK\"\n"
+				"40 PRINT \"STILL IN\"\n"
+				"50 BEND\n"
+				"60 PRINT \"AFTER\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "IN BLOCK\nSTILL IN\nAFTER\n");
+    harness_stop();
+
+    /*
+     * The skipped case is the one that needs the wait. `skiprestofline` only
+     * reaches the end of the IF's own line; without arming a skip to BEND the
+     * block's lines would run as ordinary top-level lines.
+     */
+    TEST_REQUIRE_OK(run_program("10 A# = 0\n"
+				"20 IF A# = 1 THEN BEGIN\n"
+				"30 PRINT \"NOT SEEN\"\n"
+				"40 PRINT \"ALSO NOT SEEN\"\n"
+				"50 BEND\n"
+				"60 PRINT \"AFTER\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "AFTER\n");
+    harness_stop();
+}
+
+/** @brief END stops the program without quitting a REPL session. */
+static void test_end(void)
+{
+    TEST_REQUIRE_OK(run_program("10 PRINT \"BEFORE\"\n"
+				"20 END\n"
+				"30 PRINT \"AFTER\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "BEFORE\n");
+    TEST_REQUIRE_INT(HARNESS_RUNTIME.mode, AKBASIC_MODE_QUIT);
+    harness_stop();
+
+    /*
+     * Started from a REPL, END goes back to the prompt rather than ending the
+     * interpreter -- which is the whole difference between END and QUIT.
+     */
+    TEST_REQUIRE_OK(harness_start(NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, "10 PRINT \"HI\"\n20 END\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_REPL));
+    HARNESS_RUNTIME.mode = AKBASIC_MODE_RUN;
+    HARNESS_RUNTIME.environment->nextline = 0;
+    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 40));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "HI") != NULL,
+		 "the program should have run, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "READY") != NULL,
+		 "END from a REPL session should return to the prompt, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief Nested DO loops each keep their own condition and unwind in order. */
+static void test_nested_do(void)
+{
+    TEST_REQUIRE_OK(run_program("10 I# = 0\n"
+				"20 DO WHILE I# < 2\n"
+				"30 J# = 0\n"
+				"40 DO WHILE J# < 2\n"
+				"50 PRINT I# * 10 + J#\n"
+				"60 J# = J# + 1\n"
+				"70 LOOP\n"
+				"80 I# = I# + 1\n"
+				"90 LOOP\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "0\n1\n10\n11\n");
+    harness_stop();
+}
+
+/** @brief LOOP without a DO is refused rather than silently doing nothing. */
+static void test_loop_without_do(void)
+{
+    TEST_REQUIRE_OK(run_program("10 LOOP\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside the context of DO") != NULL,
+		 "a bare LOOP should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+int main(void)
+{
+    test_do_while();
+    test_loop_until();
+    test_do_while_retests();
+    test_exit_from_do();
+    test_bare_do_loop();
+    test_on_goto();
+    test_on_gosub();
+    test_on_label();
+    test_begin_bend();
+    test_end();
+    test_nested_do();
+    test_loop_without_do();
+    return akbasic_test_failures;
+}

tests/trap_verbs.c

@@ -0,0 +1,195 @@
+/**
+ * @file trap_verbs.c
+ * @brief Tests the group C verbs: TRAP, RESUME and ERR().
+ *
+ * The interesting half of error trapping is what *stops* happening: an armed
+ * TRAP suppresses the "? line : CLASS message" report and stops the run from
+ * ending, and neither is visible unless a test says the output is empty of one
+ * and the program kept going.
+ *
+ * `ER` and `EL` are `ER#` and `EL#` here -- ordinary globals, because this
+ * dialect has no bare variable names. See TODO.md section 5.
+ */
+
+#include <string.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+#include "harness.h"
+#include "testutil.h"
+
+/** @brief Run a program to completion in RUN mode, from a string. */
+static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, harness_start(NULL));
+    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    /* Bounded: a bare RESUME that never fixes anything is an infinite retry. */
+    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, 4000));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief An armed TRAP swallows the report and enters the handler instead. */
+static void test_trap_catches(void)
+{
+    TEST_REQUIRE_OK(run_program("10 TRAP 100\n"
+				"20 DIM Q#(2)\n"
+				"30 PRINT Q#(9)\n"
+				"40 PRINT \"AFTER\"\n"
+				"50 END\n"
+				"100 PRINT \"TRAPPED \" + ER# + \" ON LINE \" + EL#\n"
+				"110 RESUME NEXT\n"));
+    /*
+     * AKBASIC_ERR_BOUNDS is 515: base 512 plus SYNTAX, TYPE, UNDEFINED. Spelled
+     * out rather than referenced so that a renumbering of the error band shows up
+     * here as a failure rather than as a silently different program.
+     */
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "TRAPPED 515 ON LINE 30\nAFTER\n");
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "RUNTIME ERROR") == NULL,
+		 "a trapped error must not also be reported, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief With no TRAP the error is reported and the program stops, as before. */
+static void test_untrapped_still_reports(void)
+{
+    TEST_REQUIRE_OK(run_program("10 DIM Q#(2)\n"
+				"20 PRINT Q#(9)\n"
+				"30 PRINT \"UNREACHED\"\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "RUNTIME ERROR") != NULL,
+		 "an untrapped error should be reported, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "UNREACHED") == NULL,
+		 "an untrapped error should stop the program, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief Bare TRAP disarms, and the next error is reported normally again. */
+static void test_trap_disarms(void)
+{
+    TEST_REQUIRE_OK(run_program("10 TRAP 100\n"
+				"20 TRAP\n"
+				"30 DIM Q#(2)\n"
+				"40 PRINT Q#(9)\n"
+				"50 PRINT \"UNREACHED\"\n"
+				"100 PRINT \"NOT SEEN\"\n"
+				"110 RESUME NEXT\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "RUNTIME ERROR") != NULL,
+		 "a disarmed TRAP should let the error through, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "NOT SEEN") == NULL,
+		 "the handler should not have run, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief A handler may be named by label, which is where a handler usually sits. */
+static void test_trap_by_label(void)
+{
+    TEST_REQUIRE_OK(run_program("10 TRAP HANDLER\n"
+				"20 DIM Q#(2)\n"
+				"30 PRINT Q#(9)\n"
+				"40 PRINT \"AFTER\"\n"
+				"50 END\n"
+				"100 LABEL HANDLER\n"
+				"110 PRINT \"CAUGHT\"\n"
+				"120 RESUME NEXT\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "CAUGHT\nAFTER\n");
+    harness_stop();
+}
+
+/** @brief RESUME's three forms land on three different lines. */
+static void test_resume_forms(void)
+{
+    /* RESUME <line> goes where it is told. */
+    TEST_REQUIRE_OK(run_program("10 TRAP 100\n"
+				"20 DIM Q#(2)\n"
+				"30 PRINT Q#(9)\n"
+				"40 PRINT \"NOT HERE\"\n"
+				"50 PRINT \"HERE\"\n"
+				"60 END\n"
+				"100 RESUME 50\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "HERE\n");
+    harness_stop();
+
+    /*
+     * Bare RESUME retries the failing line. The handler fixes the array first,
+     * so the retry succeeds -- which is the only way a bare RESUME terminates,
+     * and the reason the verb exists.
+     */
+    TEST_REQUIRE_OK(run_program("10 TRAP 100\n"
+				"20 DIM Q#(2)\n"
+				"30 PRINT Q#(N#)\n"
+				"40 PRINT \"AFTER\"\n"
+				"50 END\n"
+				"100 N# = 1\n"
+				"110 RESUME\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "0\nAFTER\n");
+    harness_stop();
+}
+
+/** @brief RESUME outside a handler is refused rather than popping something else. */
+static void test_resume_outside_handler(void)
+{
+    TEST_REQUIRE_OK(run_program("10 RESUME NEXT\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "outside the context of a TRAP handler") != NULL,
+		 "a bare RESUME should be refused, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief An error inside a handler is reported rather than re-entering it.
+ *
+ * Otherwise a broken handler traps its own failure forever and the program can
+ * never be stopped. A C128 behaves the same way.
+ */
+static void test_error_inside_handler(void)
+{
+    TEST_REQUIRE_OK(run_program("10 TRAP 100\n"
+				"20 DIM Q#(2)\n"
+				"30 PRINT Q#(9)\n"
+				"40 END\n"
+				"100 PRINT \"IN HANDLER\"\n"
+				"110 PRINT Q#(9)\n"
+				"120 RESUME NEXT\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "IN HANDLER") != NULL,
+		 "the handler should have run once, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "RUNTIME ERROR") != NULL,
+		 "an error inside the handler should be reported, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/** @brief ERR() names a status code, using the registry every code is named in. */
+static void test_err_function(void)
+{
+    TEST_REQUIRE_OK(run_program("10 TRAP 100\n"
+				"20 DIM Q#(2)\n"
+				"30 PRINT Q#(9)\n"
+				"40 END\n"
+				"100 PRINT ERR(ER#)\n"
+				"110 RESUME NEXT\n"));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "Out Of Bounds") != NULL,
+		 "ERR should name the status, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+
+    /*
+     * A code nobody reserved reads back as libakerror's own "Unknown Error",
+     * which is the same string a stack trace would print for it.
+     */
+    TEST_REQUIRE_OK(run_program("10 PRINT ERR(30000)\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "Unknown Error\n");
+    harness_stop();
+}
+
+int main(void)
+{
+    test_trap_catches();
+    test_untrapped_still_reports();
+    test_trap_disarms();
+    test_trap_by_label();
+    test_resume_forms();
+    test_resume_outside_handler();
+    test_error_inside_handler();
+    test_err_function();
+    return akbasic_test_failures;
+}

tests/value_arithmetic.c

@@ -191,17 +191,22 @@ int main(void)
     TEST_REQUIRE_STR(out->stringval, "ababab");
 
     /*
-     * mathPlus mutates self in place when self is mutable, where every other
+     * math_plus clones like every other operator, mutable operand or not.
-     * operator always clones. CommandNEXT's loop increment depends on it --
+     *
-     * TODO.md section 12 item 4. Pinning the asymmetry so a "cleanup" fails here
+     * This used to assert the opposite. The reference mutates `self` in place
-     * rather than silently breaking every FOR loop.
+     * when it is mutable, which made `A# + 1` modify `A#` whenever the left
+     * operand came out of a variable -- TODO.md section 6 item 4. It was left
+     * alone because NEXT's loop increment relied on the mutation to advance the
+     * counter; NEXT writes the result back itself now, so the asymmetry is gone
+     * and this asserts that it stays gone.
      */
     set_int(&A, 10);
     A.mutable_ = true;
     set_int(&B, 5);
     TEST_REQUIRE_OK(akbasic_value_math_plus(&A, &B, &SCRATCH, &out));
-    TEST_REQUIRE(out == &A, "math_plus on a mutable value must return self, not the scratch");
+    TEST_REQUIRE(out == &SCRATCH, "math_plus must use the scratch even for a mutable operand");
-    TEST_REQUIRE_INT(A.intval, 15);
+    TEST_REQUIRE_INT(A.intval, 10);
+    TEST_REQUIRE_INT(SCRATCH.intval, 15);
 
     set_int(&A, 10);
     A.mutable_ = false;
@@ -209,6 +214,34 @@ int main(void)
     TEST_REQUIRE(out == &SCRATCH, "math_plus on an immutable value must use the scratch");
     TEST_REQUIRE_INT(A.intval, 10);
 
+    /*
+     * The unused numeric field is ignored, not added in.
+     *
+     * The reference reads a right-hand operand as `intval + int64(floatval)`,
+     * which gives the right answer only for as long as whichever field is unused
+     * happens to be zero -- TODO.md section 6 item 5, filed as a landmine
+     * because no program can reach it. It is reachable from here: a value is a
+     * plain struct and nothing stops one carrying both. Without this the fix is
+     * untested, and the old code passes every other test in the tree.
+     */
+    set_int(&A, 2);
+    set_int(&B, 5);
+    B.floatval = 3.0;			/* stale, from whatever B held before */
+    TEST_REQUIRE_OK(akbasic_value_math_plus(&A, &B, &SCRATCH, &out));
+    TEST_REQUIRE_INT(out->intval, 7);
+
+    set_float(&A, 2.0);
+    set_float(&B, 5.0);
+    B.intval = 3;			/* stale the other way round */
+    TEST_REQUIRE_OK(akbasic_value_math_plus(&A, &B, &SCRATCH, &out));
+    TEST_REQUIRE_FEQ(out->floatval, 7.0);
+
+    /* And a truth value used as a number is -1, which is what AND/OR rely on. */
+    set_int(&A, 0);
+    TEST_REQUIRE_OK(akbasic_value_set_bool(&B, true));
+    TEST_REQUIRE_OK(akbasic_value_math_plus(&A, &B, &SCRATCH, &out));
+    TEST_REQUIRE_INT(out->intval, -1);
+
     /* Type errors. */
     set_string(&A, "text");
     set_int(&B, 1);

tests/verbs_table.c

@@ -64,9 +64,10 @@ int main(void)
     }
 
     /*
-     * The four rows with no exec handler are consumed by another verb's parse
+     * These rows have no exec handler because another verb's parse path consumes
-     * path and are never evaluated on their own. Any other missing handler is a
+     * them; they are never evaluated on their own. `WHILE` and `UNTIL` belong to
-     * verb that would report "Unknown command" at runtime.
+     * DO and LOOP the way `TO` and `STEP` belong to FOR. Any other missing
+     * handler is a verb that would report "Unknown command" at runtime.
      */
     for ( i = 0; i < count; i++ ) {
 	if ( table[i].exec != NULL ) {
@@ -78,6 +79,9 @@ int main(void)
 		     strcmp(table[i].name, "OR") == 0 ||
 		     strcmp(table[i].name, "REM") == 0 ||
 		     strcmp(table[i].name, "STEP") == 0 ||
+		     strcmp(table[i].name, "UNTIL") == 0 ||
+		     strcmp(table[i].name, "USING") == 0 ||
+		     strcmp(table[i].name, "WHILE") == 0 ||
 		     strcmp(table[i].name, "THEN") == 0 ||
 		     strcmp(table[i].name, "TO") == 0,
 		     "verb \"%s\" has no exec handler and is not a known passive token",