Give every exported function a declaration, and check that it stays that way

Closes internal-consistency items 7 through 15. Nineteen non-static functions
were in the ABI with no declaration anywhere, so no consumer could call them
and any consumer could collide with them.

The four gamepad_handle_* functions are the ones that mattered: controller.h
declared akgl_controller_handle_button_down and three siblings that did not
exist, so anything compiled against the header alone failed to link. The
definitions carry the declared names now, which also closes Defects -> Known
and still open item 10, and their documentation moved to the header.

The rest are either declared under a "part of the internal API" block --
akgl_game_save_actors and akgl_game_load_versioncmp, which tests/game.c had to
declare for itself, plus six tilemap loader helpers the untested-loader work
wants to reach -- or static, which is what the four save iterators and
load_objectnamemap should always have been. akgl_path_relative_from is deleted:
declared nowhere, called from nowhere, never wrote its output, and leaked a
pooled string on every call, so it closes Known and still open item 4 and item
40 by ceasing to exist.

scripts/check_api_surface.sh keeps it closed. It reads the built library's
dynamic symbol table and every public header with comments stripped, and fails
on an exported akgl_* symbol that is declared nowhere. Stripping comments is
the whole point -- four of these were mentioned in controller.h prose, which is
how they went unnoticed.

The pool-size ceilings are defined once, in heap.h, so the #ifndef override
hook fires for the first time; actor.h, sprite.h and character.h were defining
the same four unconditionally from headers heap.h includes above its own guard.
tests/header_pool_override.c fails the compile if that regresses.

Also here: (void) rather than () on the twelve no-argument entry points,
AKERR_NOIGNORE only on declarations, static helpers with the akgl_ prefix
dropped, and the six parameter-name mismatches. akgl_get_json_with_default had
its two contexts swapped rather than merely misspelled -- the incoming one was
`err` and its own was `e`, which is the name reserved for an incoming one.

24/24 pass, reindent --check clean.

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

include/akgl/controller.h

@@ -138,49 +138,77 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_list_keyboards(void);
 akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_event(void *appstate, SDL_Event *event);
 
 /**
- * @brief Declared but not defined under this name. Do not call.
+ * @brief Set the movement and facing bits on the "player" actor for a D-pad or arrow press.
  *
- * The implementation exists as `gamepad_handle_button_down` in `src/controller.c`
- * and is `static`-in-spirit -- it is not declared anywhere -- so a caller that
- * uses this declaration compiles and then fails to link. TODO.md, "Known and
- * still open" item 10.
+ * A whole-application shortcut rather than a control-map binding: it looks the
+ * actor up by the literal name `"player"` in #AKGL_REGISTRY_ACTOR instead of
+ * being told which actor to act on, so it only ever drives one. The
+ * akgl_actor_cmhf_* handlers are the general form.
  *
- * @param appstate Application state supplied by SDL.
- * @param event    SDL input event to process.
- * @return Nothing; it cannot be called.
+ * Facing follows movement unless the actor sets `movement_controls_face`, which
+ * is how an actor that aims independently of the direction it walks opts out.
+ *
+ * @param appstate Passed through from SDL. Required as a non-`NULL` token only;
+ *                 never read.
+ * @param event    The button or key event. Required. Both the gamepad and
+ *                 keyboard unions are read on every call, so the arm that does
+ *                 not correspond to the event type is read as garbage -- which
+ *                 works only because no real button and keycode pair collides.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p appstate or @p event is `NULL`, or if there is
+ *         no actor registered under the name "player".
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_button_down(void *appstate, SDL_Event *event);
 /**
- * @brief Declared but not defined under this name. Do not call.
+ * @brief Clear the movement bit on the "player" actor for a D-pad or arrow release, and reset its animation.
  *
- * See akgl_controller_handle_button_down. The implementation is
- * `gamepad_handle_button_up`.
+ * The counterpart to akgl_controller_handle_button_down. It clears only the movement
+ * bit, leaving the facing bits alone so the actor keeps looking the way it was
+ * walking, and rewinds `curSpriteFrameId` to 0 so the next step starts from the
+ * first frame of the walk cycle rather than wherever it stopped.
  *
- * @param appstate Application state supplied by SDL.
- * @param event    SDL input event to process.
- * @return Nothing; it cannot be called.
+ * @param appstate Passed through from SDL. Required as a non-`NULL` token only.
+ * @param event    The button or key release event. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p appstate or @p event is `NULL`, or if there is
+ *         no actor registered under the name "player".
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_button_up(void *appstate, SDL_Event *event);
 /**
- * @brief Declared but not defined under this name. Do not call.
+ * @brief Open a gamepad that has just been plugged in, and log its mapping.
  *
- * See akgl_controller_handle_button_down. The implementation is
- * `gamepad_handle_added`, which opens a newly plugged-in gamepad.
+ * SDL delivers no button events from an unopened gamepad, so a device that
+ * appears mid-session has to be opened here the way akgl_controller_open_gamepads
+ * opens the ones present at startup. A gamepad SDL has already opened is logged
+ * and left alone.
  *
- * @param appstate Application state supplied by SDL.
- * @param event    SDL input event to process.
- * @return Nothing; it cannot be called.
+ * The mapping is logged because a controller with no entry in the database
+ * produces no button events at all, and that is otherwise indistinguishable
+ * from a broken binding.
+ *
+ * @param appstate Passed through from SDL. Required as a non-`NULL` token only.
+ * @param event    The SDL_EVENT_GAMEPAD_ADDED event. Required. The joystick id
+ *                 is read out of the `gbutton` arm rather than `gdevice`, which
+ *                 works because the two share their `which` field.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p appstate or @p event is `NULL`.
+ *
+ * @note A failed `SDL_OpenGamepad` is logged rather than reported: this returns
+ *       success and the device stays silent.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_added(void *appstate, SDL_Event *event);
 /**
- * @brief Declared but not defined under this name. Do not call.
+ * @brief Close a gamepad that has been unplugged.
  *
- * See akgl_controller_handle_button_down. The implementation is
- * `gamepad_handle_removed`, which closes an unplugged gamepad.
+ * An unplugged device SDL still has open is a leaked handle, so this closes it.
+ * A removal for a device that was never opened is logged and otherwise ignored.
+ * Any control map still holding that `jsid` simply stops matching -- the map is
+ * not torn down.
  *
- * @param appstate Application state supplied by SDL.
- * @param event    SDL input event to process.
- * @return Nothing; it cannot be called.
+ * @param appstate Passed through from SDL. Required as a non-`NULL` token only.
+ * @param event    The SDL_EVENT_GAMEPAD_REMOVED event. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER If @p appstate or @p event is `NULL`.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_removed(void *appstate, SDL_Event *event);