feat(runtime)!: sys.startApp replaces routing, history and app identity

The runtime kept a back stack, a launcher fallback, an app id and a title
because a teardown destroys the Lua that would otherwise hold them. Only
the first of those is true: everything about where an app came from can
ride in the arguments, and the arguments are the one value that has to
outlive the VM.

So the runtime now does four things -- close the state, load a path, hand
the next state its arguments, defer the swap to a batch boundary -- and
sys.startApp(path, args) is the whole of navigation. Routing, history,
titles and data directories move to the Lua file a firmware boots, where
they can differ per product without a flag on Runtime.

Arguments cross as JSON, encoded while the sending state still holds the
table, so a function or a cycle raises at the call rather than stranding
a launch. start(args) receives the decoded table, or nil at boot, which
is how the entry file knows to open its own launcher.

Removes launch, replace, back, canGoBack, getAppID, getAppTitle,
setAppTitle and getAppDataPath, along with the home and data fields.
LANDSCAPE.md goes with them: it recorded a divergence from firmwares that
have since migrated.
This commit is contained in:
2026-08-05 17:04:35 -04:00
parent 772618ef89
commit 26f3fdb6e6
10 changed files with 233 additions and 481 deletions
+5 -7
View File
@@ -2,10 +2,10 @@
-- Generated from native/src/runtime/runtime.cpp. Do not edit.
-- 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, which is why an app composes the
-- classes for the features it handles:
-- The firmware loads the path it was booted with 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 that file's to decide, which is why an app
-- composes the classes for the features it handles:
--
-- ---@class PaintApp : App, TouchHandlers
--
@@ -14,7 +14,5 @@
-- Timer callbacks are registered directly with timer.after/every.
---@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 start fun(args?: table) Required. Mounts whatever the arguments describe; 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.