libakgl/TODO.md

# TODO

## Coverage baseline

Generated 2026-07-30 with:

```sh
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`:

```cmake
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.