Exit a running cart from the pause menu (IN-6)

[aldwinhermanudin]

Tapping MENU in a running cart now offers exit to launcher, returning to the cover-art carousel. No reboot — the frame loop breaks and app_main re-enters the carousel in the same millisecond, panel/SD/audio left up.

The vendored fake-08 is untouched. Zero modified files, gitlink unmoved. Three stock APIs:

• Vm::ExecuteLua registers menuitem(5, "exit to launcher", …) in the cart sandbox — no cart edit
• the callback pokes a magic byte to 0x5fff, inside PICO-8's GPIO area — the documented cart↔host channel
• main.cpp's frame loop reads it via the already-public Vm::getPicoRam()

main.cpp runs its own copy of Vm::GameLoop() because GameLoop owns the frame and never yields, so there's nowhere else to notice the byte. Copying keeps the submodule byte-identical — the same trade GC_MANUAL already makes.

Two easy things to get wrong

• The cart sandbox doesn't exist at LoadCart time — it's created in __z8_run_cart on the first frame, so registering earlier fails with __cart_sandbox is not a table. Registration runs after one Step() and checks its return value; a silent failure would remove the exit route with no symptom beyond the item being absent.
• The exit byte is cleared when a cart starts, so a stale poke can't eject the next cart. Address + magic rather than a bare flag, since GPIO is cart-writable by design.

This replaces two earlier designs

• A hold-MENU gesture in components/input — built and tested, then dropped. Undiscoverable, rebooted the board (~1.8 s, and esp_restart() discards cart save state), and holding MENU re-toggled PICO-8's pause 5–30× so the menu strobed. Supersedes Exit a running cart back to the launcher (IN-6) #35.
• A fake-08 fork change (extcmd("exit_to_host") + a Vm quit flag) — worked, and allowed bottom placement in the menu. Review found extcmd is reachable by any cart, so on stock platforms a downloaded cart could quit the program. Dropped: a vendored dependency changed for cosmetic gain. Supersedes vm: let an embedding host take control back from GameLoop fake-08#6.

Both original premises were false

The worklog records this rather than quietly fixing it: fake-08 already renders a pause menu with an exit (the //todo cited as evidence sits inside a commented-out function), and GameLoop() does return — our own Host::shouldQuit() just returns false.

Verified

pause-menu "exit to launcher" item registered: yes
cart asked to exit — returning to the launcher
pause-menu "exit to launcher" item registered: yes
cart asked to exit — returning to the launcher
clean exits: 2    reboots: 0

Two launch/exit laps in one boot, item re-registering on the second cart, no rst:. The menu screenshot in the worklog is a framebuffer render (FB_DUMP → zlib → PNG), not a camera capture. Both boards build.

Not verified: touch (driven over serial throughout); a cart using all five menuitem slots would displace ours; a cart poking 0x5fff itself would false-trigger.

Worklog: docs/worklog/2026-08-08-exit-cart-to-launcher.md