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.

AGENTS.md

@@ -13,6 +13,7 @@ Lua-language sources stay under `lua/`; C/C++ and the vendored interpreter stay
 Apps are fully trusted; keep permissions and sandboxing out of scope.
 Firmware commits dirty display content and owns panel refresh policy. Binding annotations under
 `native/src/bindings/` generate matching `lua/api/` files; regenerate instead of editing files
-marked generated. Each `@lua-module`/`@lua-augment` directive sits immediately above the
+marked generated. Callbacks are fields on the table an app returns, so a `@lua-app` block generates
+a class an app composes (`---@class PaintApp : App, TouchHandlers`) rather than global functions. Each `@lua-module`/`@lua-augment` directive sits immediately above the
 `luaL_Reg` table it describes, which is how one source declares several namespaces. This repository owns portable `lua/lib/` modules; shared UI owns theme application and persistence. Use `ble` for BLE/GATT
 and reserve `bt` for a future Classic Bluetooth contract.