libakgl/TODO.md

TODO

Coverage baseline

Generated 2026-07-30 with:

cmake -S . -B build-coverage -DAKGL_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build-coverage --parallel
ctest --test-dir build-coverage --output-on-failure

Reports land in build-coverage/coverage/ (index.html, coverage.xml).

Note: the vendored SDL/akerror/akstdlib/jansson shared objects are not on the default loader path in a fresh out-of-tree build, so every test that links them dies with error while loading shared libraries before main() runs. Export LD_LIBRARY_PATH over build-coverage/deps/{SDL,SDL_image,SDL_ttf,SDL_mixer,libakerror,libakstdlib} first, or the report will read 0% for reasons that have nothing to do with the tests. Fixing this properly (see "Test infrastructure" below) is a prerequisite for trustworthy CI coverage numbers.

Baseline with that fixed — character is the known intentionally-failing test, everything else passes:

File	Lines	Branches	Functions
src/assets.c	0/21 (0%)	0/88	0/1
src/controller.c	0/243 (0%)	0/660	0/9
src/draw.c	0/13 (0%)	0/4	0/1
src/game.c	0/224 (0%)	0/1702	0/15
src/physics.c	0/138 (0%)	0/765	0/10
src/text.c	0/28 (0%)	0/146	0/2
src/renderer.c	7/70 (10%)	5/430	1/7
src/actor.c	61/256 (24%)	76/1020	4/18
src/tilemap.c	201/426 (47%)	209/3150	10/20
src/registry.c	54/102 (53%)	63/582	8/12
src/json_helpers.c	86/111 (78%)	73/710	9/11
src/character.c	93/118 (79%)	74/806	5/7
src/sprite.c	88/101 (87%)	112/810	4/5
src/util.c	121/131 (92%)	185/1057	7/8
src/staticstring.c	16/17 (94%)	9/64	2/2
src/heap.c	111/116 (96%)	87/266	12/12
TOTAL	838/2115 (39.6%)	893/12260 (7.3%)	44.3%

The 7.3% branch figure is misleading and should not be used as a target. The akerror control-flow macros (ATTEMPT/CATCH/PROCESS/FINISH, FAIL_*_RETURN) expand into large branch trees per call site, most of which are unreachable in normal operation — src/game.c reports 1702 branches across only 224 lines. Track line and function coverage; treat branch coverage as a relative signal within a single file, not an absolute goal.

Goal for the work below: line coverage 39.6% → ~70%, function coverage 44.3% → ~80%, without adding any test that needs a real display.

---

Suspected defects found while reading the uncovered code

Write the tests below to assert correct behavior, so these fail loudly rather than getting baked in. Each is listed against the suite that will surface it.

1. akgl_render_and_compare() compares a texture against itself. src/util.c:228 and src/util.c:245 both draw t1; t2 is never rendered. The function therefore always passes, which silently neuters the image assertions in tests/sprite.c. → Suite U2.
2. akgl_tilemap_release() double-frees tileset textures. src/tilemap.c:849 destroys dest->tilesets[i].texture inside the layers loop; it should be dest->layers[i].texture. It also never NULLs the pointers or memsets the map, so a second release is a use-after-free. → Suite T3.
3. akgl_physics_simulate() dereferences self before the NULL check. src/physics.c:132 reads self->gravity_time at declaration time; FAIL_ZERO_RETURN(e, self, ...) is not until line 135. Passing NULL segfaults instead of returning AKERR_NULLPOINTER. → Suite P4.
4. akgl_path_relative_from() is a stub that leaks. src/util.c:105 acquires dirnamestr from the string heap, never writes *dst, and never releases the string. Calling it AKGL_MAX_HEAP_STRING (256) times exhausts the heap. → Suite U1.
5. akgl_registry_init() never initializes the properties registry. akgl_registry_init_properties() is not called from akgl_registry_init() (src/registry.c:27), so AKGL_REGISTRY_PROPERTIES stays 0. Every akgl_set_property() is then a silent no-op against property set 0 and akgl_get_property() always returns the caller's default — which means akgl_physics_init_arcade() and akgl_render_init2d() silently ignore configuration. → Suite R1.
6. akgl_compare_sdl_surfaces() memcmps without checking geometry. src/util.c:208 compares s1->pitch * s1->h bytes of s2 without verifying the two surfaces share dimensions, pitch, or format. → Suite U2.
7. Heap acquire functions are asymmetric. akgl_heap_next_string() increments refcount; next_actor, next_sprite, next_spritesheet, and next_character do not (src/heap.c:57-121). Callers that acquire-then-release a non-string object drive the refcount negative-ish or free a live object. → Suite H1; decide whether to fix or document.
8. tests/util.c defines test_akgl_collide_point_rectangle_logic() but main() never calls it (tests/util.c:134 vs. tests/util.c:312-317). One-line fix; do it as part of Suite U3.
9. akgl_actor_logic_movement() null-checks the wrong pointer. src/actor.c:130 checks actor twice; the message says actor->basechar but basechar is never validated before it is dereferenced on the next line. → Suite A2.
10. akgl_Actor_cmhf_up_on() / _down_on() dereference basechar unguarded. src/actor.c:385 and :413 read obj->basechar->ay with no FAIL_ZERO_RETURN on basechar, unlike their left/right counterparts (:326, :355). → Suite A1.

---

Tier 1 — new suites, no renderer required

These are pure logic or property-map code. They need akgl_heap_init() and the relevant akgl_registry_init_*() calls, nothing else. Highest coverage per unit of effort.

Suite P — tests/physics.c → target test_physics, CTest name physics

Covers src/physics.c (0% → target ~85%). 10 uncovered functions.

• P1 test_physics_null_backend — akgl_physics_init_null() installs akgl_physics_null_{gravity,collide,move} and akgl_physics_simulate; assert each field is the expected function pointer. Assert AKERR_NULLPOINTER for init_null(NULL) and for each null-backend function called with self == NULL. Assert the null gravity/move functions leave a populated actor's x/y/z, ex/ey/ez, and vx/vy/vz bit-identical.
• P2 test_physics_arcade_gravity — table-driven over gravity_{x,y,z} ∈ {0, positive, negative} × dt ∈ {0, 0.5, 1.0}. Assert the sign conventions in src/physics.c:56-67: ex -= gx*dt, ey += gy*dt, ez -= gz*dt, and that a zero component leaves its axis untouched. Assert AKERR_NULLPOINTER for null self and null actor.
• P3 test_physics_arcade_move — assert x += vx*dt on all three axes for positive, negative, and zero dt; assert dt == 0 is a no-op. Assert akgl_physics_arcade_collide() returns AKERR_API ("Not implemented") so the stub is pinned until it is written.
• P4 test_physics_simulate_iteration — the big one. Build a small heap by hand (akgl_heap_init(), then akgl_heap_next_actor() + akgl_actor_initialize()), attach a stub movementlogicfunc, and drive akgl_physics_simulate() with a null backend to isolate the loop. Assert:
  • actors with refcount == 0 are skipped;
  • actors with basechar == NULL are skipped;
  • a child actor (parent != NULL) gets x = parent->x + vx and does not go through gravity/move;
  • AKGL_ITERATOR_OP_LAYERMASK skips actors whose layer != opflags->layerid, and opflags == NULL selects the documented defaults;
  • thrust clamps: set tx beyond sx in both directions and assert tx == ±sx exactly (src/physics.c:174-194), including the sz axis which has a clamp but no accumulate;
  • MOVING_LEFT/MOVING_RIGHT accumulate tx += ax*dt, MOVING_UP/_DOWN accumulate ty += ay*dt, and neither fires for an idle actor;
  • drag: ex -= ex*drag_x*dt for nonzero drag, untouched for zero drag;
  • vx == ex + tx after the pass;
  • a movementlogicfunc that raises AKGL_ERR_LOGICINTERRUPT is swallowed and the loop continues to the next actor.
  • Defect 3: akgl_physics_simulate(NULL, NULL) must return AKERR_NULLPOINTER, not crash.
• P5 test_physics_factory — "null" and "arcade" dispatch to the right initializer; an unknown name returns AKERR_KEY; null self and null type return AKERR_NULLPOINTER. Add cases for the strncmp prefix matching in src/physics.c:232-239: "nullx" and "arcade_extra" currently match — pin whichever behavior is intended.
• P6 test_physics_arcade_properties — with AKGL_REGISTRY_PROPERTIES initialized and physics.gravity.y / physics.drag.x set via akgl_set_property(), assert akgl_physics_init_arcade() reads them into the backend. Assert the documented defaults (0.0) when unset. Depends on Suite R1 resolving defect 5.

Suite R — extend tests/registry.c

Covers akgl_registry_init_properties, akgl_set_property, akgl_get_property, akgl_registry_load_properties (src/registry.c 53% → target ~90%).

• R1 test_registry_properties_roundtrip — akgl_registry_init_properties() then set/get a value; assert the default is returned for a missing key and the stored value wins for a present key. Defect 5: assert that a plain akgl_registry_init() leaves properties usable — this is expected to fail until akgl_registry_init_properties() is added to akgl_registry_init().
• R2 test_registry_property_nullpointers — akgl_set_property(NULL, x), (x, NULL), akgl_get_property(NULL, ...), (x, NULL, ...) all AKERR_NULLPOINTER. Assert akgl_get_property with *dest == NULL allocates from the string heap (src/registry.c:178) and with a preallocated *dest reuses it.
• R3 test_registry_load_properties — new fixture tests/assets/snippets/test_properties.json with a properties object of several string values. Assert every key lands in the registry. Error cases: NULL filename → AKERR_NULLPOINTER; nonexistent file → error not crash; a file with no properties key → AKERR_KEY; a properties value that is a number rather than a string → AKERR_TYPE. Also assert the loop at src/registry.c:148-158 does not leak the string heap: record free slots before and after and require them equal.
• R4 test_registry_init_actor_state_strings — assert all AKGL_ACTOR_MAX_STATES (32) names from AKGL_ACTOR_STATE_STRING_NAMES map to 1 << i, and that a name not in the table reads back as 0.
• R5 test_registry_init_idempotent — akgl_registry_init_actor() destroys and recreates on re-init (src/registry.c:47) while the other seven initializers leak their previous SDL_PropertiesID. Pin the intended behavior; if the leak is unintended, this is the test that catches the fix.

Suite J — extend tests/ for src/json_helpers.c

New file tests/json_helpers.c → target test_json_helpers, CTest name json_helpers (78% → target ~95%). Currently json_helpers has no dedicated suite; it is covered only incidentally through sprite/character/tilemap loading.

• J1 test_json_double_value — akgl_get_json_double_value() is entirely uncovered. Assert value retrieval, AKERR_KEY for a missing key, AKERR_TYPE for a string value, AKERR_NULLPOINTER for a null object. Assert it accepts both a JSON integer and a JSON real (it uses json_is_number).
• J2 test_json_with_default — akgl_get_json_with_default() is entirely uncovered and is the odd one out: it takes a prior error context. Assert that a NULL error is a no-op success; that an AKERR_KEY error copies defsize bytes from defval into dest; that an AKERR_INDEX-group error does the same; and that an unrelated error (e.g. AKERR_TYPE) is not swallowed. Assert null defval/dest with a non-null error → AKERR_NULLPOINTER.
• J3 test_json_string_heap_allocation — for both akgl_get_json_string_value() and akgl_get_json_array_index_string(), assert the *dest == NULL path acquires and initializes a heap string (src/json_helpers.c:83, :137) and the non-null path overwrites in place. Assert a JSON string longer than AKGL_MAX_STRING_LENGTH is truncated rather than overflowing (strncpy at :91 does not NUL-terminate on truncation — assert the intended behavior explicitly).
• J4 test_json_array_index_bounds — negative index, index == length, and index > length all return AKERR_OUTOFBOUNDS for the object/integer/string variants. Wrong element type returns AKERR_TYPE.
• J5 test_json_helpers_nullpointers — sweep all 11 entry points with null obj, null key, and null dest. Several currently omit the key/dest checks that akgl_get_json_string_value() has; pin what each should do.

Fixture: one tests/assets/snippets/test_json_helpers.json holding an object with a string, integer, real, boolean, nested object, and a mixed-type array.

Suite H — extend tests/ for src/heap.c

New file tests/heap.c → target test_heap, CTest name heap (96% lines but the five uncovered lines are every exhaustion path).

• H1 test_heap_exhaustion — for each pool, claim every slot and assert the next acquire returns AKGL_ERR_HEAP: actors (AKGL_MAX_HEAP_ACTOR = 64), sprites (1024), spritesheets (1024), characters (256), strings (256). Because only akgl_heap_next_string() increments the refcount (defect 7), the non-string loops must bump refcount by hand — write the test to make that asymmetry explicit and add an assertion recording which behavior is intended.
• H2 test_heap_release_refcounting — release below zero is clamped (refcount > 0 guard); release at 1 zeroes the object and clears its registry entry; release of a still-referenced object leaves data intact.
• H3 test_heap_release_actor_children — an actor with children releases them recursively (src/heap.c:132-136); assert a child shared by two parents is not double-released, and that a full AKGL_ACTOR_MAX_CHILDREN (8) set is walked.
• H4 test_heap_release_nullpointers — all five release functions return AKERR_NULLPOINTER for NULL.
• H5 test_heap_init_clears — dirty every pool, call akgl_heap_init(), assert all slots are zeroed and akgl_heap_init_actor() alone clears only actors.

Suite S — extend tests/staticstring.c

• S1 test_string_copy_count — the only uncovered line in the file is the strncpy failure branch (src/staticstring.c:32), which is unreachable; instead pin the count == 0 → AKGL_MAX_STRING_LENGTH default (:28) versus an explicit short count, and assert a short count does not NUL-terminate (current strncpy semantics) so callers know.
• S2 test_string_initialize_truncation — initialize with a string longer than AKGL_MAX_STRING_LENGTH (PATH_MAX) and assert the documented truncation. Assert the init == NULL branch zeroes data and still sets refcount = 1 — note src/staticstring.c:17 memsets sizeof(akgl_String) starting at &obj->data, which writes past data if data is not the last member; assert the struct's trailing fields survive.

Suite A — extend tests/actor.c

Covers the 14 uncovered actor functions (24% → target ~75%). Everything except akgl_actor_render and actor_visible is renderer-free.

• A1 test_actor_control_map_handlers — the eight akgl_Actor_cmhf_* functions. For each _on: assert FACE_ALL | MOVING_ALL is cleared, the correct MOVING_* and FACE_* bits are set, and ax/ay picks up ±basechar->ax/ay. For each _off: assert ax/ex/tx/vx (or the y set) are zeroed and only the matching MOVING_* bit is cleared — note _off does not clear the FACE_* bit, which is deliberate; pin it. Assert AKERR_NULLPOINTER for null actor and null event on all eight. Defect 10: up_on/down_on with basechar == NULL must return AKERR_NULLPOINTER rather than segfault.
• A2 test_actor_logic_movement — assert sx/sy/sz are copied from basechar, and the four MOVING_* states select the right ax/ay sign. Assert the "neither left nor right" case leaves ax at its prior value (current behavior — there is no else branch). Defect 9: null basechar must return AKERR_NULLPOINTER.
• A3 test_actor_logic_changeframe — pure state machine, table-driven over (loop, loopReverse, curSpriteReversing, curSpriteFrameId, frames): forward advance mid-animation; wrap to 0 at the end when not reversing; enter reverse at the end when loop && loopReverse; leave reverse at frame 0; single-frame sprite (frames == 1); frames == 0 (currently underflows curSpriteFrameId — assert the intended guard). Assert null actor → AKERR_NULLPOINTER; note curSprite is dereferenced unchecked at src/actor.c:96, so add a null-curSprite case too.
• A4 test_actor_automatic_face — movement_controls_face == false leaves state untouched; true clears FACE_ALL and applies the documented left > right > up > down precedence; simultaneous left+up resolves to left; no movement bits leaves no face bits.
• A5 test_actor_update — with a character/sprite pair wired up, assert changeframefunc fires only when curtime - curSpriteFrameTimer >= speed, that curSpriteFrameTimer is then updated, and that a state with no bound sprite (AKERR_KEY from akgl_character_sprite_get) is swallowed as success (src/actor.c:167). Null actor and null basechar → AKERR_NULLPOINTER.
• A6 test_actor_add_child_limits — extend the existing coverage: filling all 8 slots then adding a 9th returns AKERR_OUTOFBOUNDS; adding a child that already has a parent returns AKERR_RELATIONSHIP; the child's refcount is incremented exactly once.
• A7 test_registry_iterate_actor_flags — drive akgl_registry_iterate_actor() with each AKGL_ITERATOR_OP_* combination via stub updatefunc/renderfunc that record calls. Assert LAYERMASK filters, UPDATE and RENDER fire independently, and the else branch resets scale to 1.0 when TILEMAPSCALE is absent. Note the break at src/actor.c:303 exits the ATTEMPT block — assert it skips the actor rather than aborting the enumeration.

Suite C — extend tests/character.c

Covers akgl_character_sprite_get and akgl_character_state_sprites_iterate (79% → target ~95%). The existing character test is the intentionally-failing one; add these as separate functions so they can be enabled independently.

• C1 test_character_sprite_get — add a sprite for a composite state and read it back; assert an unbound state returns AKERR_KEY; assert null basechar and null dest return AKERR_NULLPOINTER; assert state 0 and a negative state are handled (SDL_itoa renders both).
• C2 test_character_state_sprites_iterate — with AKGL_ITERATOR_OP_RELEASE set, assert each bound sprite's refcount drops by one; without the flag, assert nothing changes; assert a null userdata and a null name are logged and skipped rather than crashing.
• C3 test_character_load_json_errors — new snippet fixtures for: a sprite_mappings entry naming a sprite absent from the registry (AKERR_NULLPOINTER, src/character.c:163); a state array containing an unknown state name (AKERR_KEY, :115); a missing speedtime key. Assert that on failure the character heap slot is released and the registry entry is not left dangling. Note src/character.c:223 logs obj->name after the cleanup block has potentially zeroed it — assert the failure path does not read freed data.

Suite G — tests/game.c → target test_game, CTest name game

Covers the renderer-free half of src/game.c (0% → target ~45%). Skip akgl_game_init, akgl_game_update, akgl_game_lowfps, and akgl_game_updateFPS for now; they need a window and a running loop.

• G1 test_game_load_versioncmp — pure function, entirely testable. Equal versions succeed; differing major/minor/patch return AKERR_API; a malformed current version and a malformed save version each return AKERR_VALUE with the right message; all three null arguments return AKERR_NULLPOINTER. Assert semver_free() runs on both paths (no leak across 1000 iterations).
• G2 test_game_save_load_roundtrip — write to a temp path with akgl_game_save(), read back with akgl_game_load(), assert game is restored bit-identical. Then assert the rejection paths: a save whose name differs, whose uri differs, and whose libversion differs each return AKERR_API. Null path → AKERR_NULLPOINTER; unwritable path → IO error.
• G3 test_game_save_actors_tables — with a couple of actors, sprites, spritesheets, and characters registered, save and then parse the resulting file by hand: assert each of the four name→pointer tables is present, in order, and terminated by the NUL name + NUL pointer sentinel that akgl_game_load_objectnamemap() looks for.
• G4 test_game_load_objectnamemap_truncation — feed a deliberately truncated table (EOF before the sentinel). The while (1) loop at src/game.c:340 relies on aksl_fread raising; assert it returns an error rather than looping forever. Give this test an aggressive CTest TIMEOUT.
• G5 test_game_state_lock — assert akgl_game_state_lock() / _unlock() pair correctly and that a double-lock and an unlock-without-lock behave as documented.

Suite U — extend tests/util.c

• U1 test_path_relative_from — akgl_path_relative_from() is entirely uncovered. Assert it writes *dst, that the result is the dirname of the resolved from, and that null path/from return AKERR_NULLPOINTER. Defect 4: this is expected to fail — the function never assigns *dst and leaks its heap string. Add a loop of 300 calls asserting the string heap does not run dry.
• U2 test_render_and_compare_detects_difference — build two textures with deliberately different pixels and assert akgl_render_and_compare() reports AKERR_VALUE. Defect 1: expected to fail today. Add test_compare_sdl_surfaces_geometry: surfaces with mismatched w/h/pitch must be rejected before the memcmp (defect 6). This suite needs a renderer — see Tier 2 harness.
• U3 test_path_relative_errors — akgl_path_relative() with a path that resolves in the CWD, a path that only resolves under root, and a path that resolves under neither (assert ENOENT propagates). Assert akgl_path_relative_root() returns AKERR_OUTOFBOUNDS when strlen(root) + strlen(path) >= AKGL_MAX_STRING_LENGTH, and that both functions release their heap strings on the failure path. Defect 8: wire the existing test_akgl_collide_point_rectangle_logic() into main().

---

Tier 2 — suites that need the offscreen renderer harness

Test infrastructure (do this first)

1. Fix the loader path. Set BUILD_RPATH/INSTALL_RPATH on the test targets to the vendored dependency directories, or add ENVIRONMENT_MODIFICATION "LD_LIBRARY_PATH=path_list_prepend:..." to the set_tests_properties() block in CMakeLists.txt:141. Without this, CI coverage numbers are meaningless (see the note at the top).
2. Add tests/harness.c / tests/harness.h with akgl_test_init_headless() and akgl_test_shutdown_headless(): set SDL_VIDEODRIVER=dummy and SDL_AUDIODRIVER=dummy, SDL_Init(), akgl_heap_init(), akgl_registry_init(), create a software SDL_CreateWindowAndRenderer and point the global renderer at it. Four existing tests hand-roll this today (tests/sprite.c:194, tests/character.c:200, tests/tilemap.c:421, tests/charviewer.c:42) — collapse them onto the shared harness in the same change.
3. Add a tests/assets/snippets/ fixture per new JSON case rather than embedding JSON in C string literals, matching the existing test_tilemap_get_json_tilemap_property.json convention.

Suite T — extend tests/tilemap.c

Covers the 10 uncovered tilemap functions (47% → target ~75%).

• T1 test_tilemap_properties_numeric — akgl_get_json_properties_number, _float, and _double are all uncovered. Assert each reads the right type discriminator; note akgl_get_json_properties_double() asks for type "float" (src/tilemap.c:138) — pin whether that is intended. Assert a type mismatch returns AKERR_TYPE and a missing property returns AKERR_KEY.
• T2 test_tilemap_scale_actor — pure math, no renderer. Three branches at src/tilemap.c:824-830: y <= p_vanishing_y → p_vanishing_scale; y >= p_foreground_y → p_foreground_scale; between → the linear interpolation. Assert both exact boundaries and a midpoint. Null map and null actor → AKERR_NULLPOINTER.
• T3 test_tilemap_release — defect 2. Load tests/assets/testmap.tmj, release, and assert every tileset and layer texture pointer is NULLed and the map is safe to release a second time. Under the current implementation the layers loop frees tileset textures again; this test should fail until fixed. Run it under ASan if available.
• T4 test_tilemap_load_physics — akgl_tilemap_load_physics() is uncovered. Fixture snippets for a map with a full physics property block, one with the block absent (assert documented defaults), and one with a malformed value.
• T5 test_tilemap_load_layer_image — uncovered. Fixture with an image layer; assert the texture loads, the layer is recorded, and a missing image file yields AKGL_ERR_SDL rather than a null-texture crash later.
• T6 test_tilemap_load_bounds — assert a map declaring more than AKGL_TILEMAP_MAX_TILESETS (16) tilesets or AKGL_TILEMAP_MAX_LAYERS (16) layers returns AKERR_OUTOFBOUNDS rather than writing past the arrays.
• T7 test_tilemap_draw — with the dummy renderer, assert akgl_tilemap_draw() and akgl_tilemap_draw_tileset() complete for each layer index, that an out-of-range layeridx is rejected, and that a viewport entirely outside the map draws nothing without erroring.

Suite N — tests/renderer.c → target test_renderer, CTest name renderer

Covers src/renderer.c (10% → target ~70%).

• N1 test_render_init2d — with game.screenwidth/screenheight properties set, assert akgl_render_init2d() populates all six function pointers and sets camera to {0, 0, w, h}. Assert null self → AKERR_NULLPOINTER and that the two heap strings it acquires are released (src/renderer.c:31-32) even on the failure path — they currently are not, because PASS returns early on SDL_CreateWindowAndRenderer failure.
• N2 test_render_frame_start_end — assert AKERR_NULLPOINTER when self->sdl_renderer is NULL; assert success against the dummy renderer.
• N3 test_render_2d_draw_texture — the rotated path (angle != 0) is uncovered: assert angle != 0 with center == NULL returns AKERR_NULLPOINTER, and that a valid rotation succeeds. Assert null self and null texture are rejected.
• N4 test_render_2d_draw_mesh — pin the AKERR_API "Not implemented" stub.
• N5 test_render_2d_draw_world — assert layer ordering (tilemap layer i drawn before the actors on layer i), that refcount == 0 actors are skipped, and that opflags == NULL zero-initializes the default iterator. Note defflags at src/renderer.c:113 is uninitialized until the if body runs — assert the non-null-opflags path does not read it.

Suite X — tests/text.c, tests/draw.c, tests/assets.c

Small files, 0% each, cheap wins once the harness exists.

• X1 test_text_loadfont — load a TTF from a new tests/assets/ fixture; assert it lands in AKGL_REGISTRY_FONT, that a missing file errors, and that a null name/path is rejected.
• X2 test_text_rendertextat — render into the dummy renderer; assert a null font and null text are rejected and that wraplength 0 vs. positive both work.
• X3 test_draw_background — akgl_draw_background() returns void and cannot report failure; assert it does not crash for zero, negative, and oversized dimensions.
• X4 test_load_start_bgm — with the dummy audio driver, assert a valid file loads into AKGL_REGISTRY_MUSIC, a missing file errors, and a null filename is rejected.

---

Tier 3 — deferred

Suite K — tests/controller.c → target test_controller

src/controller.c is 0% across 9 functions and 243 lines, but every entry point is driven by real SDL gamepad/keyboard events. Worth doing, but only after Tier 1 and 2 land.

• Synthesize SDL_Event structs directly and call akgl_controller_handle_event() — no physical device needed for SDL_EVENT_KEY_DOWN/_UP, and SDL_EVENT_GAMEPAD_ADDED/_REMOVED can be pushed onto the SDL event queue.
• akgl_controller_pushmap() and akgl_controller_default() are the most testable: assert a control map is registered and retrievable, that an out-of-range controlmapid is rejected, and that akgl_controller_default() binds the eight akgl_Actor_cmhf_* handlers to the expected keys.
• akgl_controller_list_keyboards() and _open_gamepads() should at minimum be asserted not to crash with zero devices attached.

Deferred src/game.c entry points

akgl_game_init, akgl_game_update, akgl_game_updateFPS, and akgl_game_lowfps need a window and a live frame loop. Revisit once Suite N proves the dummy renderer is stable enough to run a bounded number of frames.

---

Registration checklist

Each new suite needs, in CMakeLists.txt:

add_executable(test_<feature> tests/<feature>.c)
add_test(NAME <feature> COMMAND test_<feature>)
target_link_libraries(test_<feature> PRIVATE akstdlib::akstdlib akerror::akerror akgl
  SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image SDL3_mixer::SDL3_mixer jansson::jansson -lm)

and its name added to the set_tests_properties(...) list at CMakeLists.txt:141 and to the FIXTURES_REQUIRED akgl_coverage list at CMakeLists.txt:167 — a suite missing from the second list runs outside the coverage fixture and its counters are discarded by coverage_reset.

New suites in dependency order: physics, json_helpers, heap, game, renderer, text, draw, assets, controller.

---

Carried over

1. Make character-to-sprite state bindings release their references symmetrically. akgl_character_sprite_add() increments the sprite refcount for every state-map binding, but no corresponding removal API exists. Replacing a state binding also leaves the previous sprite's refcount incremented. When akgl_heap_release_character() drops the character refcount to zero, it clears the character registry entry and zeroes the structure without enumerating state_sprites, decrementing the bound sprites, or destroying the SDL property map. Implement binding removal/replacement so each removed binding releases exactly one sprite reference. On final character release, enumerate every remaining binding (the existing akgl_character_state_sprites_iterate() release path may be reusable), release each reference, destroy state_sprites, and then clear the character. Add tests for removal, replacement, duplicate sprite bindings across multiple states, and final character release.

   Suites C2 and H2 above are the coverage side of this item; the API work is still outstanding.