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
+4 -32
View File
@@ -20,38 +20,10 @@ function sys.hasFeature(feature) end
---@return integer
function sys.getMillis() end
---Returns the immutable first path component of the running app.
---@return string
function sys.getAppID() end
---Returns the running app title, initially the app ID.
---@return string
function sys.getAppTitle() end
---Returns the current app's guaranteed-existing persistent data directory.
---@return string Absolute path under /.lua/data, preserved across app updates.
function sys.getAppDataPath() end
---Changes the running app's display title.
---@param title string
function sys.setAppTitle(title) end
---Launches a route, which main.lua resolves, and pushes the current one.
---@param path string App-relative route; traversal is rejected.
---@param arg? string Passed to main.start(route, arg).
function sys.launch(path, arg) end
---Launches a route without retaining the current one.
---@param path string App-relative route; traversal is rejected.
---@param arg? string Passed to main.start(route, arg).
function sys.replace(path, arg) end
---Returns to the previous app, or the launcher when history is empty.
function sys.back() end
---Whether sys.back() would return somewhere rather than land on the launcher, which is what chrome needs to decide whether to offer a back control.
---@return boolean
function sys.canGoBack() end
---Tears the runtime down and starts over from a Lua file, which is the only navigation there is: history, titles and where apps live are whatever that file makes of the arguments.
---@param path string Absolute path to the Lua file to load; traversal is rejected.
---@param args? table Plain data, carried across the teardown as JSON and handed to start(args). Raises on anything JSON cannot represent.
function sys.startApp(path, args) end
---Returns heap statistics.
---@return integer freeBytes