feat(runtime): hand the whole app contract to /.lua/main.lua

The firmware knew four paths and called four globals, so the card could
not change its own layout or put anything around an app. It now loads one
file, and the table that file returns owns the rest: start() mounts the
route, home and data name the tree, and every callback is a field on it
rather than a global the app and its chrome would have to share.
This commit is contained in:
2026-08-04 20:51:25 -04:00
parent e85adfa757
commit e3153f57c5
5 changed files with 192 additions and 108 deletions
+10 -9
View File
@@ -2,21 +2,22 @@
-- Generated from native/src/runtime/runtime.cpp. Do not edit.
-- Runtime layout:
-- /.lua/apps/<AppId>/main.lua application entry point
-- /.lua/apps/<AppId>/<Subapp>/main.lua nested route, omitted from the launcher
-- /.lua/data/<AppId>/ persistent app data, preserved across updates
-- /.lua/lib/<module>.lua shared require() modules
-- require() also searches the running application's directory
-- 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.
--
-- 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.
--
-- 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. Runs once before the first draw; failing here stops the app.
---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 init(arg) end
function start(route, arg) end
---Optional frame loop, called once after init and then at most 30 FPS, best effort.
---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