refactor(api)!: declare callbacks as classes an app composes

The runtime has always called fields on the table main.lua returns, but
@lua-global declared them as loose functions, so the stubs type-checked
something that does not exist and read as "define a global".

Callbacks are now @lua-app blocks that generate a class: App for the core
contract, TouchHandlers and ButtonHandlers beside the namespaces they belong
to. An app composes what it implements:

  ---@class PaintApp : App, TouchHandlers

Names follow the rest of the surface: onTouchDown rather than on_touch_down,
with the field names the runtime looks up renamed to match. @lua-field carries
the plain fields (home, data) that were prose in a preamble before.

lua/api/core/runtime.lua

@@ -4,20 +4,17 @@
 
 -- The firmware loads /.lua/main.lua into every fresh state and calls these on the
 -- table it returns. Where apps live, what surrounds them and which of these an app
--- itself sees are all main.lua's to decide.
+-- itself sees are all main.lua's to decide, which is why an app composes the
+-- classes for the features it handles:
 --
--- Fields the firmware reads: home, the route sys.back() lands on once history is
--- empty, and data, the sys.getAppDataPath() template whose ? is the app id.
+--   ---@class PaintApp : App, TouchHandlers
 --
 -- The firmware does not clear the frame before calling draw(), and commits changed
 -- display content after each callback batch using the panel's own refresh policy.
 -- Timer callbacks are registered directly with timer.after/every.
 
----Required. Mounts the route; failing here leaves no app running.
----@param route string The app path sys.launch, sys.back or the boot recorded.
----@param arg? string The string passed to sys.launch or sys.replace.
-function start(route, arg) end
-
----Optional frame loop, called once after start and then at most 30 FPS, best effort.
----@param deltaMs integer Monotonic milliseconds since the previous draw; zero on the first.
-function draw(deltaMs) end
+---@class App
+---@field home? string The route sys.back() lands on once history is empty.
+---@field data? string The sys.getAppDataPath() template whose ? is the app id.
+---@field start fun(route: string, arg?: string) Required. Mounts the route; failing here leaves no app running.
+---@field draw? fun(deltaMs: integer) Optional frame loop, called once after start and then at most 30 FPS, best effort.

lua/api/features/buttons.lua

@@ -33,14 +33,11 @@ function buttons.wasPressed(button) end
 ---@return boolean
 function buttons.wasReleased(button) end
 
----Fired when a button goes down.
----@param button Button
-function on_button_down(button) end
+-- What an app implements to see buttons, composed into its own class:
+--
+--   ---@class MenuApp : App, ButtonHandlers
 
----Fired when a button comes up.
----@param button Button
-function on_button_up(button) end
-
----Tap alias, fired on release like a click, after on_button_up.
----@param button Button
-function on_button(button) end
+---@class ButtonHandlers
+---@field onButtonDown? fun(button: Button) Fired when a button goes down.
+---@field onButtonUp? fun(button: Button) Fired when a button comes up.
+---@field onButton? fun(button: Button) Tap alias, fired on release like a click, after onButtonUp.

lua/api/features/touch.lua

@@ -28,22 +28,12 @@ function touch.isTouched() end
 ---@return string? error
 function touch.setCalibration(x0, y0, x1, y1) end
 
----Fired when the finger lands.
----@param x integer
----@param y integer
-function on_touch_down(x, y) end
+-- What an app implements to see raw touch, composed into its own class:
+--
+--   ---@class PaintApp : App, TouchHandlers
 
----Fired when the finger moves while down, after the firmware's jitter filter.
----@param x integer
----@param y integer
-function on_touch_move(x, y) end
-
----Fired when the finger lifts.
----@param x integer
----@param y integer
-function on_touch_up(x, y) end
-
----Tap alias, fired on release like a click, after on_touch_up.
----@param x integer
----@param y integer
-function on_touch(x, y) end
+---@class TouchHandlers
+---@field onTouchDown? fun(x: integer, y: integer) Fired when the finger lands.
+---@field onTouchMove? fun(x: integer, y: integer) Fired when the finger moves while down, after the firmware's jitter filter.
+---@field onTouchUp? fun(x: integer, y: integer) Fired when the finger lifts.
+---@field onTouch? fun(x: integer, y: integer) Tap alias, fired on release like a click, after onTouchUp.