Merge pull request #1679 from bryanthaboi/dev

findPendingRom answered with the first dump in the save directory whose SHA-1
mapped to any not-yet-ready version.  On a device with no file picker that
scan IS the import, so with four dumps in the folder, choosing Red imported
and decoded Blue (#1274).

It now takes an optional version and narrows to it.  The two Choose paths
pass self.chooseVersion, since a Choose names the cart it is for.  The two
Android USB-drop scans pass nothing and still take the first pending cart of
any version, which is what they are for.

A chosen version with no dump present now imports nothing rather than the
wrong cart, and falls through to the notice that says where to put the file.

.github/workflows/ci.yml

@@ -468,3 +468,24 @@ jobs:
           if [ "$found" = "0" ]; then
             echo "no committed mods to lint"
           fi
+
+  luacheck:
+    name: engine lint (luacheck)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: install luacheck
+        run: |
+          set -e
+          sudo apt-get update
+          sudo apt-get install -y lua5.4 liblua5.4-dev luarocks
+          sudo luarocks install luacheck || sudo apt-get install -y lua-check
+          luacheck --version
+
+      - name: luacheck gate (undefined globals, unreachable code)
+        run: ./scripts/lint.sh --gate
+
+      - name: luacheck full report (advisory)
+        continue-on-error: true
+        run: ./scripts/lint.sh

.luacheckrc

@@ -23,6 +23,10 @@ read_globals = {
   -- LuaJIT 2.1 ships table.unpack even though the bare 5.1 `table` std lacks
   -- it; without this, every `table.unpack` reads as an undefined field.
   table = { fields = { "unpack" } },
+  "POKEPORT_DISPLAY_COMPANION",
+  "POKEPORT_EDITOR_MODE",
+  "rawlen",
+  package = { fields = { "searchers" } },
 }
 
 -- Vendored/native trees and the test suites have their own conventions.
@@ -30,6 +34,7 @@ exclude_files = {
   "mobile/",
   "tests/",
   "tools/save-editor/",
+  "tools/save_convert/vendor/",
 }
 
 ignore = {

CONTRIBUTING-mods.md

@@ -173,7 +173,7 @@ before the key existed changes behavior; list both generations or say `"all"`
 when you mean everywhere.
 
 `docs/mod-api-gen2-compat.md` is the compatibility matrix: what works on Gold
-and Silver today (40 of the 46 registries, 40 event and 43 hook names shared with Gen 1,
+and Silver today (40 of the 46 registries, 40 event and 44 hook names shared with Gen 1,
 and 24 Gen 2-only ones), which registries have no Gen 2 home and drop their
 writes with a report, and which hooks and events are still to come.
 `docs/preparing-your-mod-for-gen2.md` is the step-by-step migration guide for a

data/scripts/safari.lua

@@ -111,7 +111,7 @@ local function joinPrompt(game, ow, done)
   local t = game.data.text
   local back = function(text)
     game.stack:push(TextBox.new(game, text, function()
-      ow:scriptMove(ow.player, "down", 1, done)
+      ow:scriptMove(ow.player, "down", 1, done, { collide = true })
     end))
   end
   game.stack:push(TextBox.new(game,

data/scripts/story.lua

@@ -127,7 +127,7 @@ M.VIRIDIAN_CITY = {
     game.stack:push(TextBox.new(game,
       game.data.text._ViridianCityOldManSleepyPrivatePropertyText
       or "You can't go\nthrough here!\fThis is private\nproperty!",
-      function() ow:scriptMove(ow.player, "down", 1) end))
+      function() ow:scriptMove(ow.player, "down", 1, nil, { collide = true }) end))
     return true
   end,
 }
@@ -356,7 +356,7 @@ M.VERMILION_CITY = {
     if shipLeft then
       game.stack:push(TextBox.new(game,
         t._VermilionCitySailor1ShipSetSailText or "The ship set sail.",
-        function() ow:scriptMove(ow.player, "up", 1) end))
+        function() ow:scriptMove(ow.player, "up", 1, nil, { collide = true }) end))
       return true
     end
     -- Walk-past is never facing-right / inFrontOfOrBehindGuardCoords, so
@@ -377,7 +377,7 @@ M.VERMILION_CITY = {
       ask .. "\f"
       .. (t._VermilionCitySailor1YouNeedATicketText
           or "You need a ticket\nto get aboard."),
-      function() ow:scriptMove(ow.player, "up", 1) end))
+      function() ow:scriptMove(ow.player, "up", 1, nil, { collide = true }) end))
     return true
   end,
   talk = {

data/scripts/story2.lua

@@ -414,7 +414,7 @@ local function saffronGate(guardText, triggers, horizontal)
       game.stack:push(TextBox.new(game,
         t._SaffronGateGuardGeeImThirstyText or "Gee, I'm thirsty\nthough!\nThe road's closed.",
         function()
-          ow:scriptMove(ow.player, back, 1)
+          ow:scriptMove(ow.player, back, 1, nil, { collide = true })
         end))
       return true
     end,
@@ -769,7 +769,7 @@ M.MUSEUM_1F = {
     if y == 4 and (x == 9 or x == 10)
        and not game.save.flags.EVENT_BOUGHT_MUSEUM_TICKET then
       museumClerk(game, ow, nil, function()
-        ow:scriptMove(ow.player, "down", 1)
+        ow:scriptMove(ow.player, "down", 1, nil, { collide = true })
       end)
       return true
     end

data/scripts/story3.lua

@@ -176,7 +176,7 @@ M.POKEMON_TOWER_6F = {
           -- .did_not_defeat: one simulated step right, off the trigger,
           -- so fleeing does not leave you standing on a cell that
           -- immediately re-fires.
-          ow:scriptMove(ow.player, "right", 1)
+          ow:scriptMove(ow.player, "right", 1, nil, { collide = true })
         end
         ow:afterBattle(result, battle)
       end

data/scripts/story4.lua

@@ -734,7 +734,7 @@ local function e4ExitSeal(flag, closedBlock, openBlock, dontRunText, autoFlag)
       local TextBox = require("src.render.TextBox")
       game.stack:push(TextBox.new(game,
         game.data.text[dontRunText] or "Don't run away!", function()
-        ow:scriptMove(ow.player, "up", 1)
+        ow:scriptMove(ow.player, "up", 1, nil, { collide = true })
       end))
       return true
     end,

data/scripts/story5.lua

@@ -240,7 +240,7 @@ local function stepGate(opts)
     push(game, text(game)[opts.text] or opts.fallback, function()
       ow.player.facing = opts.push
       if not ow:checkLedgeHop(opts.push) then
-        ow:scriptMove(ow.player, opts.push, 1)
+        ow:scriptMove(ow.player, opts.push, 1, nil, { collide = true })
       end
     end)
     return true
@@ -820,7 +820,8 @@ M.PEWTER_POKECENTER = {
 -- on the west-side cells and walks you back
 local function bikeGateGuard(coords, stopText, explainText)
   return function(game, ow, x, y)
-    if game.save.inventory.BICYCLE then return false end
+    local bike = game.save.inventory.BICYCLE
+    if bike and bike ~= 0 then return false end
     if not inCoords(coords, x, y) then return false end
     -- walk the player up to the tile beside the counter, no further:
     -- (matchedY - closestY) tiles, 0 when already next to it
@@ -842,10 +843,10 @@ local function bikeGateGuard(coords, stopText, explainText)
         -- (PlayerMovingRightScript). Without it the player was left
         -- parked beside the guard's counter with no way past. #518
         local function shoveRight()
-          ow:scriptMove(ow.player, "right", 1)
+          ow:scriptMove(ow.player, "right", 1, nil, { collide = true })
         end
         if dist > 0 then
-          ow:scriptMove(ow.player, "up", dist, shoveRight)
+          ow:scriptMove(ow.player, "up", dist, shoveRight, { collide = true })
         else
           shoveRight()
         end

docs/mod-api-gen2-compat.md

@@ -24,7 +24,7 @@ The short version, for an author deciding what to write:
   merged.** The write is taken, dropped, and named once per mod in the same
   error feed the mod manager shows -- in both directions, so a Red boot writing
   to `decorations` is told exactly as a Gold boot writing to `map_scripts` is.
-- **40 event names and 43 hook names have a call site in both generations**, so
+- **40 event names and 44 hook names have a call site in both generations**, so
   one subscription serves both games. `tests/engine/gate_gen2_mod_api.lua`
   reads those names back out of the source and fails if a site is renamed or
   deleted on either side, and fails again if a new shared site appears without
@@ -539,7 +539,8 @@ gains a field instead of the name gaining a prefix.
   `battle.damage_dealt`, `battle.fainted`, `battle.status_inflicted`,
   `battle.battler_switched`, `battle.ball_thrown`, `battle.exp_gained`,
   `pokemon.level_up`, `pokemon.move_learned`; hooks `battle.damage`,
-  `battle.crit`, `battle.accuracy`, `battle.turn_order`,
+  `battle.crit`, `battle.accuracy`, `battle.charge_required`,
+  `battle.turn_order`,
   `battle.enemy_action`, `battle.run`, `battle.exp_award`, `exp.gain`,
   `catch.rate`, `trainer.party`, `battle.overlay`, `battle.low_health_alarm`,
   `battle.catch_exp`, `battle.bottom_ui_visible`,
@@ -549,6 +550,17 @@ gains a field instead of the name gaining a prefix.
   screen has no `.data` field, so the Gen 2 site **adds** `ctx.data` beside the
   Gen 1 keys. A mod that calls `nextFn` is unaffected; one that reaches through
   `ctx.battle.data` instead gets nil on Gold.
+  `battle.exp_award`'s `ctx.applyShare(mon, split, announce)` reads its third
+  argument on both generations: truthy prints the mon's GainedText, falsy pays
+  it silently, so one mod source can print a single summary line for a
+  party-wide award instead of a box per recipient. Gold honours it **only when
+  it is passed**, by argument count -- `applyShare(mon, split)` was written
+  against a seam that always announced on Gold and keeps announcing there,
+  while `applyShare(mon, split, nil)` is silent on both. Pass the argument
+  explicitly and the two generations agree; omit it and Gen 1 stays silent
+  where Gold speaks. Only the line is affected: the exp, the stat exp,
+  `battle.exp_gained`, the level-up line, learned moves and the forget prompt
+  happen either way.
 - *The catch and the evolution:* `pokemon.caught`, `pokemon.evolved`; hook
   `evolution.check`. `src/ui/gen2/BattleState.lua:pushCaught` emits
   `pokemon.caught` once the mon is in the party or the box, and

docs/modding.md

@@ -122,21 +122,40 @@ Each object requires a stable `id`, a display `name`, a destination `file`
 digests. `format` is either `"raw"` (the default) or `"n64"`. An optional
 `description` gives players dump or region guidance in the import panel.
 `size` declares the exact canonical byte length; `max_size` declares a smaller
-per-import ceiling when an exact size is not appropriate. Every import also
-has an engine-enforced 128 MiB ceiling and is rejected before hashing when its
-filesystem reports an invalid size.
+per-import ceiling when an exact size is not appropriate. The engine hard limit
+is 2 GiB. Imports above 128 MiB receive an explicit free-space confirmation and
+use the launcher's streaming large-file path rather than being materialized as
+one Lua string.
 
 For `"n64"`, the launcher recognizes `.z64`, `.v64`, and `.n64` byte orders,
 strips a recognized 512-byte copier header, converts the bytes to canonical
 big-endian `.z64` order, and then checks MD5. The canonical bytes are written
 to `mods/<mod-id>/baseroms/<file>`. Each selection is a private grant to that
 mod: the launcher never scans or copies another mod's imported files merely
-because its manifest names the same digest. Mods read the result with their existing scoped `mod:read` API, for
-example `mod:read("baseroms/stadium2.z64")`; no host path or new filesystem
+because its manifest names the same digest. Small sources can still be read
+with the existing scoped `mod:read` API, for example
+`mod:read("baseroms/stadium2.z64")`. For large sources, prefer the bounded
+`mod.imports` facade described below; no host path or new general filesystem
 permission is exposed. Missing `required_imports` block the mod before its
 entry chunk runs; missing `optional_imports` remain visible in the same
 launcher panel but do not block loading.
 
+#### Bounded access to validated imports
+
+A loaded mod can address only ids declared by its own `required_imports` or
+`optional_imports` arrays:
+
+```lua
+local info, err = mod.imports:info("stadium2")
+local header, err = mod.imports:read("stadium2", 0, 4096)
+```
+
+`read` uses zero-based offsets and is capped at 8 MiB per call. The engine
+rechecks the stored import before exposing it, seeks into the engine-owned
+copy, and never gives the mod a host path or file handle. This is intended for
+large source formats whose table/index can be parsed with small reads before
+selectively reading the payloads a transform actually needs.
+
 MD5 here identifies a known dump because ROM databases commonly publish it;
 it is not a security or authenticity guarantee. Do not paste the SHA-1 used by
 Gen1Recomp's own game-ROM importer into an import's `md5` field. Mod archives
@@ -441,6 +460,28 @@ default** (1x front, 2x back).
   ball-to-pic grow multiplies your scale through each stage, so a rescaled
   mon still grows into place from the ball, grounded the whole way.
 
+## Installation-scoped generated cache
+
+Generated data derived from a validated user source often belongs to the mod
+installation rather than to one Pokémon save. `mod.cache` is that namespace:
+
+```lua
+local ok, err = mod.cache:write("extract/v1/arena.bin", encodedArena)
+local bytes, err = mod.cache:read("extract/v1/arena.bin")
+local info = mod.cache:info("extract/v1/arena.bin")
+mod.cache:delete("extract/v1/arena.bin")
+```
+
+The physical root is engine-owned (`mod_cache/<mod-id>/`) and never exposed to
+the mod. Keys are safe relative paths and a single write is capped at 64 MiB.
+The cache does not rewind with checkpoints and is not scoped to game version,
+slot, or playthrough. The mod owns its generated format, fingerprints, rebuild
+policy, and completion marker; the engine treats the bytes as opaque data.
+
+Use `mod.storage` instead when the data belongs to one playthrough. Use
+`mod.cache` when it is a reproducible installation artifact that can be rebuilt
+from a declared user source.
+
 ## Durable tool storage and runtime checkpoints
 
 `mod.save` remains the right place for state that should travel with the next
@@ -633,6 +674,17 @@ the selected indices. Mods remain responsible for selection policy and should
 use only public `mod.ui`, hook, and save APIs. See RFC 0010 for the exact
 contract and compatibility guarantees.
 
+Both battle engines expose the guarded `battle.charge_required` hook when a
+charge-capable move is selected for its initial turn and the active ruleset
+would otherwise charge it. The wrapper receives `(next, ctx)`, where `ctx` is
+`{ battle, user, target, move, charge = true, isCalled }`. Return `false` to
+skip only that initial charge and continue through the ordinary move pipeline;
+call `next(ctx)` to keep it. The hook does not run for the release turn or when
+the active ruleset already skips charging (for example, Gold Solarbeam in
+sun). PP use, accuracy, damage, animation, and secondary effects remain owned
+by the engine. With no subscriber, the vanilla decision runs without building
+the hook context.
+
 ## Developer console
 
 Boot with developer mode on to unlock the in-game console and hot-reload

docs/new-features.md

@@ -14,6 +14,7 @@ Features intentionally added beyond the original Pokémon Red, Blue, and Yellow
 * **Screen position setting** (center, upper, top) shared across all games, for clamp-on controllers that cover the lower screen
 * **Touch skins** in RetroArch overlay format and Delta `.deltaskin` (including PDF-wrapped bezel art), with per-button press states and Super Game Boy borders
 * **Pokédex diploma and printer image exports**
+* **Shareable mod lists** over save sync, optionally carrying the options set for those mods, which the receiving device is asked about before anything is changed
 
 ## Gen 2 Specifics
 

docs/rfcs/0008-streamed-mod-imports-and-install-cache.md

@@ -0,0 +1,141 @@
+# RFC 0008 — Streamed mod imports and installation-scoped generated cache
+
+## Motivation
+
+`required_imports`/`optional_imports` can now describe files up to 2 GiB, but
+the existing launcher and public mod API still assume imported bytes are small:
+
+* the Windows desktop picker stages a selected required import through a fixed
+  `%TEMP%/pokeport_required_import.bin` path before validation;
+* the fallback import path materializes the selected file as one Lua string;
+* after validation a mod can only use `mod:read("baseroms/...")`, which also
+  materializes the whole file;
+* `mod.storage` is intentionally scoped to one Pokémon playthrough, so it is
+  not an appropriate home for a one-time generated asset cache shared by every
+  save using the same installed mod.
+
+This makes optical-disc-sized user sources impractical even though the manifest
+schema already accepts them. A failed temporary staging copy can also turn a
+valid large source into a smaller temporary file and produce a misleading
+"wrong file size" rejection.
+
+A mod should be able to consume its own already-validated source incrementally
+and compile derived runtime data once, without receiving a host path or general
+filesystem access.
+
+## Decision being extended
+
+This extends the same legal/sandbox direction as **D11 asset transforms**
+(`src/mods/AssetTransform.lua`): mods distribute recipes and derive bytes from
+user-owned sources rather than shipping ROM-derived data. It also follows the
+**D14 parity-gate** contract referenced by `tests/harness.lua` and
+`tests/engine/gate_meta_coverage.lua` (the `21-testing-and-ci` plan): additive
+extension points ship public-API coverage, no-mod parity coverage, and docs in
+the same change.
+
+The historical D11 plan document is referenced by source comments but is not
+present in the current repository tree; this RFC is the checked-in design
+record for the new surface.
+
+## Exact API delta
+
+No manifest field changes. Existing `required_imports` and `optional_imports`
+remain the declaration/validation authority.
+
+Two additive facades are added to the `mod` object.
+
+### `mod.imports`
+
+```lua
+local info, err = mod.imports:info("source_id")
+local bytes, err = mod.imports:read("source_id", offset, length)
+```
+
+* `source_id` must name an import declared by the calling mod.
+* the import is rechecked through `RequiredImports.validateStored` before it is
+  exposed, so missing, replaced, or invalid optional imports are not readable;
+* `offset` and `length` are zero-based byte coordinates;
+* one read is capped at 8 MiB;
+* no host path or file handle is returned;
+* production reads seek into the engine-owned stored copy instead of reading
+  the whole source.
+
+`info()` returns declaration metadata plus stored size. It does not expose a
+host path.
+
+### `mod.cache`
+
+```lua
+mod.cache:write("extract/v1/model.bin", bytes)
+local bytes = mod.cache:read("extract/v1/model.bin")
+local info = mod.cache:info("extract/v1/model.bin")
+mod.cache:delete("extract/v1/model.bin")
+```
+
+The cache is rooted at `mod_cache/<mod-id>/`, follows the engine persistence
+backend, and is independent of game version, launcher slot, and playthrough.
+Paths are checked with `SafePath`; `..`, absolute paths, drive paths, and other
+escapes remain unavailable. A single cache write is capped at 64 MiB so large
+generated datasets are naturally split into independently replaceable files.
+
+The engine does not interpret cache bytes. Mods own generated-format versioning,
+fingerprints, transactional completion markers, and rebuild policy.
+
+## Launcher/import transport delta
+
+For large raw required imports:
+
+1. desktop pickers return the original selected path instead of staging it
+   through a fixed temporary file;
+2. the engine opens that source itself;
+3. bytes are copied directly to the existing engine-owned
+   `mods/<id>/baseroms/<file>` destination in 4 MiB chunks;
+4. MD5 is updated incrementally during the copy;
+5. the normal size/MD5 validation receipt is written only after the complete
+   destination passes validation;
+6. partial destinations are removed on short reads, write failure, size
+   mismatch, or digest mismatch.
+
+N64 imports stay on the existing canonicalization path because byte-order and
+copier-header normalization require transformation rather than a raw copy.
+
+If a validation receipt for an already-stored large raw import is missing, the
+engine rebuilds it with streaming MD5 rather than a whole-file read.
+
+## Backward compatibility / migration
+
+**Existing mods do nothing.** This is additive.
+
+* manifest v1/v2 fields are unchanged;
+* `mod:read`, `mod.storage`, registries, events, hooks, and legacy compatibility
+  retain their existing behavior;
+* small required imports retain the existing in-memory validation path;
+* N64 imports retain canonicalization and existing accepted byte orders;
+* a mod that never touches `mod.imports` or `mod.cache` creates no new cache
+  files and observes no new behavior.
+
+The mod API integer is not bumped because no existing member changes meaning or
+shape.
+
+## Security and legal posture
+
+The launcher remains the authority that validates user-supplied bytes. The new
+facade narrows access rather than widening it: a mod can read only ids declared
+in its own manifest, only after validation, and only in bounded ranges. It does
+not receive host paths, `io`, or a raw filesystem handle.
+
+`mod.cache` is writable only beneath the calling mod's generated-cache root.
+Nothing in this RFC permits packaged ROM-derived bytes; `modkit lint/pack`
+continue to enforce the existing legal posture.
+
+## Parity guarantee
+
+The change ships with:
+
+* a no-mod/API-v1 parity test proving an empty load and an existing v1-style
+  `mod:read` load do not create cache data or change the old surface;
+* a public mod-API test that reaches `mod.imports` and `mod.cache` through a
+  real `Loader` load, including bounded reads, undeclared/missing imports,
+  cache isolation, and traversal rejection;
+* incremental MD5 vectors and a large-import streaming regression test;
+* the existing engine suite, required-import suite, and mod lint gates.

docs/rfcs/0011-battle-charge-required.md

@@ -0,0 +1,92 @@
+# RFC 0011: Charge-required battle hook
+
+## Status
+
+Proposed.
+
+## Motivation
+
+A battle-mechanics mod can change damage through `battle.damage` and register
+move effects, but it cannot conditionally skip the first turn of an existing
+charge move. In Gen 1, the engine decides and stores the charge continuation
+before any public effect callback can run. Reaching into `user.charging`,
+`user.chargeReady`, or generation-specific volatile state is private,
+checkpoint-fragile, and would require a mod to duplicate move-pipeline policy.
+
+Weather is the immediate example: a portable sun rule needs Solarbeam to
+resolve on selection while leaving Fly, Dig, PP use, hit resolution, animation,
+and secondary effects to the engine. The capability is generic and useful to
+other ruleset and move-mechanics mods.
+
+## Decision and plan extended
+
+This implements **D-AT-002: charge-stage policy remains mod authority through a
+generic guarded engine decision seam**. The consuming design is tracked in the
+Adaptive Trainers implementation plan,
+[`docs/superpowers/plans/2026-08-14-adaptive-trainers.md`](https://github.com/MaxTomahawk/gen1recomp-adaptive-trainers/blob/main/docs/superpowers/plans/2026-08-14-adaptive-trainers.md),
+Task 8. The delta follows the additive, guarded hook convention documented by
+Route B in `CONTRIBUTING-mods.md`; it contains no weather, move-id, trainer, or
+Adaptive Trainers policy.
+
+## Exact API delta
+
+Both the Gen 1 and Gen 2 battle engines add this guarded hook:
+
+```lua
+mod.hooks:wrap("battle.charge_required", function(next, ctx)
+  -- ctx = {
+  --   battle = live battle controller,
+  --   user = attacking battler,
+  --   target = defending battler,
+  --   move = merged move record,
+  --   charge = true,
+  --   isCalled = false,
+  -- }
+  if should_resolve_now(ctx) then return false end
+  return next(ctx)
+end)
+```
+
+The call site is the initial-use charge decision, after announcement and PP
+handling but before charge state, invulnerability, charge animation, or charge
+text is created. It runs only when the active engine rules would otherwise
+require a charge. It does not run on the release turn. Returning exactly
+`false` skips that initial charge and continues through the engine-owned move
+pipeline. Any other downstream return preserves the charge. `isCalled` is true
+when Metronome or Mirror Move selected the move.
+
+Gold keeps its native sun decision first, so Solarbeam in native sun already
+requires no charge and does not invoke the hook. Gen 1 link battles use the
+shared Gen 1 move pipeline and therefore receive the same seam; normal link
+mod-compatibility rules continue to govern deterministic peers.
+
+The hot path first calls `Runtime.wantsHook("battle.charge_required")`. With no
+subscriber, no hook payload table is allocated and the existing branch runs
+unchanged.
+
+## Migration and compatibility
+
+Existing mods change nothing. The hook name and payload are additive. With no
+wrapper installed, Red, Blue, Yellow, Gold, and Silver retain their previous
+charge state, PP use, text, animation, accuracy, damage, and native weather
+behavior. Existing charge-move data and effect records require no migration.
+
+A mod adopting the seam should call `next(ctx)` unless it deliberately wants to
+skip this charge. It should not mutate private charge fields or re-run the move.
+
+## Verification
+
+- `tests/engine/battle_charge_required.lua` exercises the real Gen 1 and Gen 2
+  engines through a sandboxed public mod, including false-to-skip, next-to-keep,
+  release-turn behavior, called-move PP semantics, shared payload shape, and
+  native Gold sun behavior.
+- The same test proves no-mod charge/release parity and replaces
+  `Runtime.call` with a sentinel behind a false `Runtime.wantsHook` guard.
+- `tests/engine/gate_hooks.lua` discovers the new catalog name and proves empty
+  chains preserve vanilla values and allocation behavior.
+- `tests/engine/gate_gen2_mod_api.lua` requires a guarded site in both
+  generations and keeps the compatibility reference list complete.
+
+## Deprecation etiquette
+
+Nothing is removed, renamed, superseded, or deprecated.

docs/rfcs/0012-gen2-exp-award-announce.md

@@ -0,0 +1,140 @@
+# RFC 0012: `applyShare`'s announce argument on Gen 2
+
+## Status
+
+Proposed.
+
+## Motivation
+
+`battle.exp_award` hands a mod `ctx.applyShare(mon, split, announce)` on both
+generations. On Gen 1 the third argument decides whether the mon's GainedText
+box is printed (`src/battle/BattleState.lua`, `if announce then`), which is how
+a mod that pays the whole party prints **one** summary line instead of a box
+per recipient.
+
+Gold accepts the argument and ignores it, as its own comment above the hook
+call says. So the same mod source, running the same code, prints one line on
+Red and six on Gold — one for the participant plus one for every bench mon it
+paid.
+
+This is not hypothetical. The [Exp Share](https://github.com/ShaneMcGovernIE/exp_share)
+mod declares `"games": ["gen1", "gen2"]` and its description promises "a single
+shared-exp line instead of one message per Pokemon". It passes `true` for the
+fighters and `nil` for the bench, exactly as the Gen 1 seam asks. On Gold every
+one of those `nil` calls announces anyway, so a five-mon party turns every KO
+into six boxes to click through.
+
+There is no mod-side fix. The announcement is emitted inside
+`Battle:giveExperiencePass`, behind no hook, and a mod cannot ask for silence
+because the argument that means "quietly" is discarded. The only workaround is
+to intercept the battle's event queue afterwards and delete the boxes, which is
+what a mod written for this had to do — a mod reaching into engine internals to
+undo something the public seam should never have done.
+
+## Decision and plan extended
+
+This does not add a seam. It finishes one: `battle.exp_award` is documented as
+"the same hook `BattleState:awardExp` calls on Gen 1 and with the same ctx",
+and `docs/mod-api-gen2-compat.md` lists it among the hooks shared with Gen 1.
+The third `applyShare` argument is the one part of that ctx whose meaning did
+not survive the crossing, so the promise the catalog already makes is what this
+change delivers.
+
+The delta follows Route B's additive, guarded convention in
+`CONTRIBUTING-mods.md`: nothing is renamed, nothing is removed, and no mod that
+exists today changes behaviour.
+
+## Exact API delta
+
+`ctx.applyShare(mon, split, announce)` on Gen 2 now reads `announce`:
+
+| Call | Gen 1 | Gen 2 before | Gen 2 after |
+|---|---|---|---|
+| `applyShare(mon, split)` | silent | announces | **announces** (unchanged) |
+| `applyShare(mon, split, nil)` | silent | announces | **silent** |
+| `applyShare(mon, split, false)` | silent | announces | **silent** |
+| `applyShare(mon, split, true)` | announces | announces | announces |
+| `applyShare(mon, split, "expAll")` | announces | announces | announces |
+
+The argument is honoured **only when it is actually passed**, decided by
+argument count rather than by value:
+
+```lua
+local function applyShare(mon, split, ...)
+  local announce = ...
+  local silent = select("#", ...) > 0 and not announce
+  ...
+end
+```
+
+`select("#", ...)` counts an explicit `nil`, so `applyShare(mon, split)` and
+`applyShare(mon, split, nil)` are distinguishable — and they have to be, because
+the first is a Gen 2-era call written against a seam that always announced, and
+the second is a deliberate "pay this one quietly".
+
+Only the `{ kind = "experience" }` event is affected. A silent award is still a
+whole award: the exp, the stat exp, the `battle.exp_gained` event, the
+`grew to level` line, learned moves and the interactive forget-a-move prompt all
+happen exactly as before, in the same order.
+
+Internally `Battle:giveExperiencePass` takes a sixth parameter, `silent`. It
+defaults to announcing, so both of the cart's own passes are untouched.
+
+## Migration and compatibility
+
+**Existing mods change nothing.** A Gen 2 mod calling `applyShare(mon, split)`
+gets the behaviour it was written against. A Gen 1 mod is untouched: no Gen 1
+file is modified. The v1 surface — `content.X:register/override/get`,
+`events:on`, `hooks:wrap`, `mod.log`, `mod:read`, the manifest v1 fields and
+`pokemon.before_give` — is not involved; `mods/example_mew_starter` neither
+calls this seam nor loads differently.
+
+A mod that wants parity passes the argument explicitly, which is what the Gen 1
+seam has always documented. Exp Share already does, and needs no edit to get
+its own README's behaviour on Gold.
+
+One residual difference is deliberate and now documented rather than silent: an
+**omitted** third argument still means "silent" on Gen 1 and "announce" on
+Gold. Closing that would change what an existing Gen 2 mod prints, which Route
+B rejects. Passing the argument makes the two generations agree, so the rule an
+author needs is one sentence: *say what you mean and both games do the same
+thing.*
+
+## Verification
+
+- `tests/gen2_exp_share_test.lua` grows two sections and 14 checks, and the 23
+  checks it already had are unchanged — which is itself the vanilla-parity
+  evidence for this file.
+  - **The no-mod test.** With nothing subscribed to `battle.exp_award`, a solo
+    participant still prints one line and the EXP.SHARE double pass still
+    prints both. The hot path is unchanged: `Runtime.wantsHook` still guards
+    the ctx allocation, and `vanillaAward` never passes `silent`.
+  - **The mod-API test.** The seam is driven through `hooks:wrap` on a real
+    `Runtime.install`ed bus, not by calling internals: the omitted argument
+    announces, an explicit `nil` and an explicit `false` are silent, a truthy
+    value (including Gen 1's `"expAll"`) announces, the exp and stat exp paid
+    are identical either way, and no `experience` event leaks into the queue on
+    a silent pass.
+- `tests/engine/gate_gen2_mod_api.lua` (943 checks),
+  `tests/engine/gate_hooks.lua` (493) and `tests/engine/gate_events.lua` (529)
+  pass unchanged; `battle.exp_award` was already in the shared catalog, so no
+  gate list moves.
+- `tests/gen2_battle_test.lua` (690), `gen2_battle_end_test.lua` (32),
+  `gen2_battle_items_test.lua` (99), `gen2_badge_boosts_test.lua` (34) and
+  `gen2_battle_loss_test.lua` (15) pass unchanged.
+
+## Docs with the change
+
+`docs/mod-api-gen2-compat.md` gains the `applyShare` reading beside the
+existing `battle.low_health_alarm` payload note, in the same section that lists
+`battle.exp_award` as shared — including the argument-count rule and the
+residual difference above.
+
+No registry or schema field changes, so `src/mods/Schemas.lua` is untouched and
+`tools/gen_registry_docs.lua` has nothing new to emit.
+
+## Deprecation etiquette
+
+Nothing is removed, renamed, superseded or deprecated. The two-argument call is
+not deprecated either — it keeps its current Gen 2 meaning permanently, and the
+docs name the explicit form as the one that behaves the same on both games.

docs/skin-studio.md

@@ -1,11 +1,11 @@
 # Touch skins and the Skin Studio
 
 A **skin** replaces the on-screen controls wholesale: a bezel image, a
-control layout, and the rectangle the Game Boy screen is drawn into. Engine:
+control layout, and a screen-placement anchor. Engine:
 `src/core/TouchSkin.lua` (model, parsers, zip export), `src/core/TouchControls.lua`
-(draw and input), `src/render/Renderer.lua` (the screen viewport),
+(draw and input), `src/render/Renderer.lua` (screen placement),
 `src/core/DeltaSkin.lua` (Delta `.deltaskin` import and export),
-`src/ui/SkinStudio.lua` (the desktop editor). Tests:
+`src/ui/SkinStudio.lua` (the responsive skin editor). Tests:
 `tests/engine/touch_skin_test.lua`, `tests/engine/skin_studio_test.lua`,
 `tests/engine/skin_studio_ux.lua`,
 `tests/engine/skin_studio_image_import.lua`,
@@ -13,8 +13,10 @@ control layout, and the rectangle the Game Boy screen is drawn into. Engine:
 `tests/engine/launcher_skins_tab.lua`,
 `tests/engine/launcher_skins_ux.lua`.
 
-Skins are picked in the launcher's **Skins** tab, which also imports them and
-opens the studio. `options.touchControls.skin` holds the folder name.
+The launcher's **Skins** tab imports skins, shows the enabled skin, exports it,
+and is the one place that turns skin use off. **My Skins** holds the visual
+grid, pagination, edit, delete and per-skin export actions.
+`options.touchControls.skin` holds the folder name.
 
 ## Formats
 
@@ -30,7 +32,7 @@ as-is. Supported keys:
 | `overlays` | page count |
 | `overlayN_name` | page name, the target of `next_target` |
 | `overlayN_overlay` | bezel image |
-| `overlayN_full_screen` | stretch the page to the window |
+| `overlayN_full_screen` | cover the window with the page without deforming its artwork |
 | `overlayN_rect` | page placement, default `0,0,1,1` |
 | `overlayN_aspect_ratio` | design aspect; the overlay letterboxes to it even when full screen |
 | `overlayN_range_mod`, `overlayN_alpha_mod` | desc defaults |
@@ -98,8 +100,8 @@ corners fire two directions. `screens[1].outputFrame` (or the legacy
 `gameScreenFrame`) becomes the screen cutout. A portrait page with neither
 keeps `mappingSize` as the overlay aspect, sits at the bottom of the
 window, and puts the Game Boy picture in the leftover space above -- the
-usual GBA4iOS controller-deck layout. Pages that name a screen rect still
-stretch to the window the way Delta does. Host functions map to
+usual GBA4iOS controller-deck layout. Pages that name a screen rect fit the
+game into it. Host functions map to
 engine hotkeys: `menu` to `menu_toggle`, `fastForward` to
 `hold_fast_forward`, `toggleFastForward` to `toggle_fast_forward`;
 `quickSave` and `quickLoad` have nothing to bind to and drop to decoration.
@@ -135,7 +137,7 @@ to decoration and never captures a touch.
 As an extension to the format, `key:<name>` presses any keyboard key, which is
 how a skin button reaches a mod hotkey.
 
-## The screen viewport
+## Screen placement
 
 `overlayN_viewport` is the cutout the picture is fitted into. The Game Boy
 screen keeps its whole-pixel scale and letterboxes inside that rect rather than
@@ -146,6 +148,17 @@ that lets a widescreen bezel take the filling survey-zoom world view instead.
 A viewport also implies the faithful-ratio lock. Without it the world pass
 expands to fill the cutout and you get more map instead of a Game Boy screen.
 
+Zoom still steps around that hole: OUT shows more map inside it, IN enlarges
+the world, and the start menu stays at the hole's fit scale instead of
+shrinking with the map.
+
+An image-backed portrait overlay that has no explicit vertical anchor is treated
+as a controller deck: it is contained without deformation and pinned to the
+bottom on taller screens. The spare space belongs to the game above it.
+
+When a skin is active, **SCREEN POS** reads **SKIN**: placement comes from the
+skin rather than the normal Center / Upper / Top setting.
+
 Border art often ships with a transparent hole and no `viewport` key. **Detect
 screen from bezel** in the studio measures the hole out of the art's alpha
 channel and writes the rect.
@@ -153,10 +166,8 @@ channel and writes the rect.
 ## Bezels versus pads
 
 A skin whose active page binds nothing is a frame rather than a pad: a TV
-surround, a handheld shell, a Super Game Boy border. Those draw on **desktop**
-as well, where the touch overlay itself does not, and a gamepad does not hide
-them. Anything that binds a button still follows the usual mobile /
-`POKEPORT_TOUCH` rule.
+surround, a handheld shell, a Super Game Boy border. Selected skins draw on
+**desktop** as well as mobile; a gamepad does not hide them.
 
 ## Installing
 
@@ -190,9 +201,32 @@ shipping branding.
 
 ## The studio
 
-Launcher, Skins tab, **Open Skin Studio**, or the gear on any skin row to open
-that skin. Desktop only: the launcher does not offer it on Android or iOS,
-because it wants a mouse, typed coordinates and room for an inspector.
+Launcher, Skins tab, **My Skins** opens the Studio library on desktop and
+mobile. **My Skins** is the only visual grid: real bezel previews plus create
+and import actions, with each card owning Edit, Export and (for installed
+skins) Delete. Choosing Edit opens a separate, canvas-first editor; the old
+New/Load workspace controls are deliberately not duplicated inside that editor.
+
+The editor keeps its canvas unobstructed and puts the contextual actions in a
+compact lower tray: add/control binding, button and bezel artwork, pages,
+screen placement, freeform/10:9 screen shape and deletion. **Screen** opens
+cutout, bezel-hole detect, **Detect this screen**, and the canvas presets.
+**Detect this screen** (also on the tray) sets the mock device to the live
+window size so a phone skin is authored at that phone's form factor rather
+than a generic 1080x1920 16:9. **Zoom −** shrinks the mock device inside the
+workspace so the screen hole can be dragged larger than the bezel while the
+handles stay grabable; **Fit** restores contain. The mouse wheel over the
+canvas, and `-` / `=` / `0` on a keyboard, do the same. Touches select, drag and resize the
+same controls that a mouse edits on desktop.
+
+My Skins and the editor chrome sit inside the platform safe area (notch,
+status bar, home indicator), the same inset the launcher uses. The mock
+device still represents the full window, because a skin covers the whole
+screen at play time.
+
+The launcher’s **Turn skins off** button clears the selected skin and disables
+skin use. With no skin enabled, mobile falls back to the built-in pad; that pad
+is not itself a skin card.
 
 **Canvas.** A mock device at a chosen preset, so a phone skin is authored at
 phone proportions on a desktop monitor.
@@ -200,6 +234,7 @@ phone proportions on a desktop monitor.
 | Preset | Size |
 | --- | --- |
 | Phone portrait / landscape | 1080x1920, 1920x1080 |
+| This screen | the live window, so a phone is authored at its own height |
 | Tablet portrait / landscape | 1536x2048, 2048x1536 |
 | Steam Deck | 1280x800 |
 | Desktop 1080p | 1920x1080 |
@@ -216,13 +251,16 @@ and of the page itself when it comes within a few pixels, and the guide it
 snapped to is drawn. X / Y / W / H are in canvas pixels, so a control can be
 typed to the coordinate its art was drawn at. **Back** and **Front** move the
 selection through the draw order. Bind, hitbox shape, hit reach and idle and
-pressed images are per control; the bezel, the pages and the screen cutout are
-per page. The cutout is itself a draggable element with a 10:9 lock.
+pressed images are per control; the bezel, the pages and the screen anchor are
+per page. The SCREEN anchor is itself draggable and resizable; its default
+shape is freeform, with an optional 10:9 lock.
 
 **Bind** opens a grid of every bind the engine understands: the eight Game Boy
-buttons, the diagonal pairs, every hotkey, a few `key:` entries, and
-decoration. The COMBINE chips at the top toggle one part at a time, which is
-how a pipe bind like `left|down` is built without typing it.
+buttons, the diagonal pairs, every hotkey, desktop hotkeys and decoration.
+The desktop section exposes `-` / `=`, `1` through `5`, `F1`, `F2` and `F10`
+as `key:` controls, so a mobile button invokes the exact same game path as
+its desktop shortcut. The COMBINE chips at the top toggle one part at a time,
+which is how a pipe bind like `left|down` is built without typing it.
 
 **Undo** and **Redo** in the top bar cover every edit (ctrl+Z / ctrl+Y, or
 `u` / shift+`u` without a keyboard modifier). The stack holds the last 50
@@ -247,12 +285,13 @@ the **Import** button there and beside each row opens the host file picker (`src
 zenity/kdialog) and copies the chosen PNG or JPG into `img/` under the name in
 the SKIN field, then assigns it to that slot. Dropping a PNG or JPG on the
 window does the same for whichever slot was last touched. A new bezel does not
-move the screen cutout: press **Detect screen from bezel** to measure it out of
+move the screen anchor: press **Detect screen from bezel** to measure it out of
 the art's alpha.
 
-**Testing.** **Test** makes the canvas live: clicking presses real Game Boy
-buttons and the footer reports what is held. **Play** saves the skin, selects
-it, and boots the game with it.
+**Testing.** **Test** renders a game-composition preview behind the live overlay:
+the 160x144 picture letterboxes inside the screen cutout, matching gameplay.
+Clicking presses real Game Boy buttons and the footer reports what is held.
+**Play** saves the skin, selects it, and boots the game with it.
 
 **Saving.** **Save** writes `skins/<name>/skin.lua` and copies every image the
 skin names, so the folder stands alone. **Export** offers three formats, and

docs/updater.md

@@ -126,9 +126,12 @@ bundled game, in that case.
    persistent launcher control. Android downloads the release APK, verifies
    its SHA-256 entry from `sha256sums.txt`, then invokes Android's Package
    Installer. The installer asks the user for consent and enforces package,
-   version-code, and signing-certificate compatibility. iOS links the
-   sideload repository for a re-sideload; Xbox, desktop, and PortMaster builds
-   link their correctly named full package. Switch keeps its native OTA flow.
+   version-code, and signing-certificate compatibility. A legacy APK without
+   the installer bridge links its full package for one manual bootstrap
+   update, including when its downloaded payload already reports the latest
+   engine version. iOS links the sideload repository for a re-sideload; Xbox,
+   desktop, and PortMaster builds link their correctly named full package.
+   Switch keeps its native OTA flow.
 
 ## Known limitations
 

main.lua

@@ -24,10 +24,10 @@ local GameViewport = require("src.render.GameViewport")
 
 -- Lua errors: persist a redacted trace in the save dir and surface a hint.
 do
-  local defaultErrorHandler = love.errorhandler
+  local defaultErrorHandler = love.errorhandler or love.errhand
   function love.errorhandler(msg)
-    local hint = SwitchDiagnostics.logLuaError(msg)
-    if hint and type(msg) == "string" then
+    local ok, hint = pcall(SwitchDiagnostics.logLuaError, msg)
+    if ok and hint and type(msg) == "string" then
       msg = msg .. "\n\n" .. hint
     end
     if defaultErrorHandler then
@@ -302,6 +302,8 @@ local function makeLauncher()
     forceImport = forceImport,
     onEditSave = openEditor,
     onEditTouchControls = openTouchControlsEditor,
+    -- Skin Studio owns a touch-first layout as well as the desktop workspace.
+    -- Keep the compatibility predicate so external hosts using it still work.
     onOpenSkinStudio = require("src.ui.SkinStudio").available_desktop()
       and openSkinStudio or nil,
   })
@@ -877,6 +879,8 @@ love.handlers = love.handlers or {}
 function love.handlers.audiosuspend()
   local ChipAudio = package.loaded["src.core.ChipAudio"]
   if ChipAudio then pcall(ChipAudio.setSuspended, true) end
+  local Sound = package.loaded["src.core.Sound"]
+  if Sound then pcall(Sound.onDeviceReset) end
 end
 
 function love.handlers.audioreset()
@@ -929,7 +933,7 @@ function love.touchpressed(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchpressed(id, x, y)
   end
-  if Studio then return end
+  if Studio then return Studio.touchpressed(id, x, y) end
   if Importer then
     -- Both mobiles: FlexLove scroll needs the real touch stream. Clicks are
     -- polled inside the view; the istouch filter on mousepressed still drops
@@ -946,7 +950,7 @@ function love.touchmoved(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchmoved(id, x, y)
   end
-  if Studio then return end
+  if Studio then return Studio.touchmoved(id, x, y) end
   if Importer then
     return Importer:touchmoved(id, x, y, dx, dy, pressure)
   end
@@ -960,7 +964,7 @@ function love.touchreleased(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchreleased(id, x, y)
   end
-  if Studio then return end
+  if Studio then return Studio.touchreleased(id, x, y) end
   if Importer then
     return Importer:touchreleased(id, x, y, dx, dy, pressure)
   end
@@ -1013,7 +1017,12 @@ function love.mousepressed(x, y, button, istouch)
     if love.system.getOS() == "Android" then return end
     return TouchEditor.mousepressed(x, y, button)
   end
-  if Studio then return Studio.mousepressed(x, y, button) end
+  if Studio then
+    -- Mobile LÖVE sends both a touch event and an `istouch` mouse twin.
+    -- Studio consumes the real finger stream above, so discard the twin.
+    if istouch and (love.system.getOS() == "Android" or love.system.getOS() == "iOS") then return end
+    return Studio.mousepressed(x, y, button)
+  end
   if Importer then
     -- love.touchpressed already forwards the primary touch into FlexLove for
     -- scroll. LÖVE ALSO synthesizes a mouse press for that same touch; if both
@@ -1048,7 +1057,10 @@ function love.mousereleased(x, y, button, istouch)
     if love.system.getOS() == "Android" then return end
     return TouchEditor.mousereleased(x, y, button)
   end
-  if Studio then return Studio.mousereleased(x, y, button) end
+  if Studio then
+    if istouch and (love.system.getOS() == "Android" or love.system.getOS() == "iOS") then return end
+    return Studio.mousereleased(x, y, button)
+  end
   if Importer then return end
   if editorMode and EditorApp.mousereleased then
     return EditorApp.mousereleased(x, y, button)
@@ -1066,7 +1078,10 @@ function love.mousemoved(x, y, dx, dy, istouch)
     if love.system.getOS() == "Android" then return end
     return TouchEditor.mousemoved(x, y)
   end
-  if Studio then return Studio.mousemoved(x, y) end
+  if Studio then
+    if istouch and (love.system.getOS() == "Android" or love.system.getOS() == "iOS") then return end
+    return Studio.mousemoved(x, y)
+  end
   if editorMode or Importer then return end
   if mouseTouch then
     if Game and love.mouse.isDown(1) then Game:touchmoved("mouse", x, y) end

mobile/android/app/src/main/AndroidManifest.xml

@@ -54,7 +54,7 @@
     <activity
         android:name="org.love2d.android.GameActivity"
         android:exported="true"
-        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation"
+        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation|uiMode|density|fontScale|locale|layoutDirection|colorMode"
         android:label="${NAME}"
         android:launchMode="singleTask"
         android:screenOrientation="${ORIENTATION}"
@@ -71,7 +71,7 @@
     </activity>
     <activity
         android:name="org.love2d.android.GameActivity$SecondaryActivity"
-        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation"
+        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation|uiMode|density|fontScale|locale|layoutDirection|colorMode"
         android:excludeFromRecents="true"
         android:exported="false"
         android:launchMode="singleTask"

mobile/ios/app-repo.json

@@ -12,6 +12,41 @@
       "tintColor": "3b5ca8",
       "category": "games",
       "versions": [
+        {
+          "version": "0.2.18",
+          "date": "2026-08-21",
+          "size": 13772120,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.18/gen1recomp++-0.2.18-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.2.17",
+          "date": "2026-08-21",
+          "size": 13771903,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.17/gen1recomp++-0.2.17-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.2.16",
+          "date": "2026-08-21",
+          "size": 13769300,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.16/gen1recomp++-0.2.16-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1367 Android auto scrolling  down bug\n- #1570 Pokemon Gold isn't noticing my controller inputs on...ANY controller I own, despite all of them working in the other games, and in the main launcher\n- #1585 Power-saving mode or dark mode closes the game on Android.\n- #1611 bug: keyboard gets stuck IOS\n- #1612 Fold 7 infinite scrolling mouse.\n- #1636 Game freezes when trainer battle starts\n- #1638 Game screen orientation on smartphone\n- #1641 [Gold] [Android] PKMN Evolutions sequence freezes the Game \n\n## Contributors\n\n- @1Jamie\n- @bryanthaboi\n- @HighDrexler\n- MaxTomahawk"
+        },
+        {
+          "version": "0.2.15",
+          "date": "2026-08-21",
+          "size": 13753007,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.15/gen1recomp++-0.2.15-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #1589 Player sprite still blinking on the Town Map\n- #1595 Pokedex completion certificate is not displaying correctly\n- #1597 Link cable looks broken\n- #1613 Visual differences in Pokemon trades\n- #1619 Save Menu cutting off and Put into another place\n\n## Contributors\n\n- @1Jamie\n- @bryanthaboi"
+        },
+        {
+          "version": "0.2.14",
+          "date": "2026-08-20",
+          "size": 13749372,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.2.14/gen1recomp++-0.2.14-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
         {
           "version": "0.2.13",
           "date": "2026-08-20",

scripts/lint.sh

@@ -7,7 +7,8 @@
 # the nil global), unused values, unreachable code. The .luacheckrc mutes the
 # cosmetic categories the codebase lives with, so what prints is worth a look.
 #
-#   scripts/lint.sh            lint src/
+#   scripts/lint.sh            full advisory report over every shipped tree
+#   scripts/lint.sh --gate     only the codes CI blocks on (0xx, 1xx, 511)
 #   scripts/lint.sh src tools  lint specific paths
 #
 # Install once with:  luarocks install luacheck
@@ -15,9 +16,27 @@
 set -uo pipefail
 cd "$(dirname "$0")/.."
 
+DEFAULT_PATHS=(main.lua conf.lua src data/scripts mods tools)
+
+GATE=0
+if [ "${1:-}" = "--gate" ]; then
+  GATE=1
+  shift
+fi
+
 if ! command -v luacheck >/dev/null 2>&1; then
   echo "luacheck not found on PATH (install: luarocks install luacheck)" >&2
   exit 2
 fi
 
-luacheck "${@:-src}"
+if [ "$#" -gt 0 ]; then
+  PATHS=("$@")
+else
+  PATHS=("${DEFAULT_PATHS[@]}")
+fi
+
+if [ "$GATE" = "1" ]; then
+  exec luacheck "${PATHS[@]}" -q --codes --only 0 1 511
+fi
+
+luacheck "${PATHS[@]}"

scripts/test.sh

@@ -66,6 +66,15 @@ run_tier() {
 
 # ------- ROM-free tiers: these are what CI runs
 
+if command -v luacheck >/dev/null 2>&1; then
+  run_tier "T0 luacheck gate (undefined globals, unreachable code)" \
+    ./scripts/lint.sh --gate
+else
+  echo ""
+  echo "-- T0 luacheck gate: skipped (no luacheck on PATH --"
+  echo "   luarocks install luacheck; CI installs and gates on it regardless)"
+fi
+
 run_tier "T0 ROM builder version routing" python3 tests/build_rom_data_cli_test.py
 run_tier "T0 ROM manifest generator pin/overrides" python3 tests/rom_manifest_generator_test.py
 run_tier "T0 switch CI workflow content gate" "$LUA" tests/switch_ci_workflows_test.lua

src/battle/BattleState.lua

@@ -538,6 +538,7 @@ end
 
 local function makeBattler(data, mon, isPlayer, save)
   local def = data.pokemon[mon.species]
+  require("src.pokemon.Stats").ensure(def, mon)
   local badgeBoosts = data.constants and data.constants.badgeBoosts
   local badges = nil
   if isPlayer and save then
@@ -3980,7 +3981,17 @@ function BattleState:performMove(user, target, moveInst, isCalled)
   -- record (chargeText) and the invulnerability from semiInvulnerable,
   -- falling back to the id tables (Fly AND Dig go semi-invulnerable:
   -- ChargeEffect sets INVULNERABLE for both)
-  if record and record.charge and not releasing then
+  local chargeRequired = record and record.charge ~= nil and not releasing
+  if chargeRequired and Runtime.wantsHook("battle.charge_required") then
+    local required = Runtime.call("battle.charge_required", function(c)
+      return c.charge
+    end, {
+      battle = self, user = user, target = target, move = move,
+      charge = true, isCalled = isCalled or false,
+    })
+    chargeRequired = required ~= false
+  end
+  if chargeRequired then
     self:cancelMoveAnim()
     user.charging = moveInst
     user.chargeReady = true

src/battle/MoveEffects.lua

@@ -645,7 +645,9 @@ MoveEffects.full = {
       user.bideTurns = ctx.rng(2, 3)
       user.bideDamage = 0
       ctx.battle:cancelMoveAnim()
-      ctx.anim(user.isPlayer and "XSTATITEM_ANIM" or "XSTATITEM_DUPLICATE_ANIM")
+      ctx.battle:animBeforeMove(
+        user.isPlayer and "XSTATITEM_ANIM" or "XSTATITEM_DUPLICATE_ANIM",
+        user.isPlayer)
       ctx.say(Strings("%s\nis storing energy!", displayName(user)))
     end,
   },

src/battle/gen2/Battle.lua

@@ -903,8 +903,16 @@ function Battle:movePriority(moveId)
   return (def and Battle.PRIORITY[def.effect]) or 0
 end
 
+-- engine/battle/effect_commands.asm:192-197 (enemy twin :383-390)
+Battle.SLEEP_BYPASS_MOVES = { SNORE = true, SLEEP_TALK = true }
+
 -- Can this mon act?  Returns true, or false plus the message the cart prints.
-function Battle:canAct(mon)
+-- `moveId` is wCurPlayerMove / wCurEnemyMove (effect_commands.asm:193).
+local function clearBide(state)
+  state.bideTurns, state.bideStored, state.bideMove = nil, nil, nil
+end
+
+local function checkTurn(self, mon, moveId)
   local name = self:monName(mon)
   -- SUBSTATUS_RECHARGE, and it is checked BEFORE status: CheckPlayerTurn reads
   -- it first, clears it, prints MustRechargeText and jumps to EndTurn, so a mon
@@ -925,7 +933,11 @@ function Battle:canAct(mon)
   local beforeMove = record and record.beforeMove
   if beforeMove
       and (record.beforeMovePriority or 0) > Battle.VOLATILE_PRIORITY then
-    return beforeMove(self, mon, name) and true or false
+    -- engine/battle/effect_commands.asm:188-200
+    local bypass = mon.status == "sleep" and Battle.SLEEP_BYPASS_MOVES[moveId]
+    local acted = beforeMove(self, mon, name) and true or false
+    if acted or not bypass then return acted end
+    beforeMove = nil
   end
   -- SUBSTATUS_FLINCHED, read and cleared right after the freeze check
   -- (CheckPlayerTurn / CheckEnemyTurn `.not_frozen`).  Set this turn by the
@@ -959,6 +971,14 @@ function Battle:canAct(mon)
   return true
 end
 
+-- CantMove (engine/battle/effect_commands.asm:344-353) clears BIDE on every
+-- arm of CheckPlayerTurn / CheckEnemyTurn that spends the turn.
+function Battle:canAct(mon, moveId)
+  local acted = checkTurn(self, mon, moveId)
+  if not acted then clearBide(self:volatile(mon)) end
+  return acted
+end
+
 -- STRUGGLE, the move a mon with nothing left to spend falls back to
 -- (engine/battle/core.asm `.CheckPlayerHasUsableMoves` for the player and
 -- `.struggle` for the enemy).  It lives in the move table like any other move
@@ -1234,10 +1254,15 @@ function Battle:dealDamage(attacker, defender, damage, opts)
   if opts.critical then
     self:emit({ kind = "message", text = "A critical hit!" })
   end
+  -- SuperEffectiveText / NotVeryEffectiveText (data/text/battle.asm:603,608).
+  -- The cart breaks both across the box's two lines and hyphenates "super-"
+  -- to do it, and the not-very line ends on the single ellipsis glyph Gold's
+  -- charmap carries at $75, not three periods.
   if opts.effectiveness and opts.effectiveness > 10 then
-    self:emit({ kind = "message", text = "It's super effective!" })
+    self:emit({ kind = "message", text = Strings("It's super-\neffective!") })
   elseif opts.effectiveness and opts.effectiveness < 10 then
-    self:emit({ kind = "message", text = "It's not very effective..." })
+    self:emit({ kind = "message",
+      text = Strings("It's not very\neffective…") })
   end
   if endured then
     self:emit({ kind = "message",
@@ -1389,9 +1414,18 @@ function Battle:useMove(attacker, defender, moveId)
   -- free of PP and obedience in exactly the same way.
   local rolling = state.rolloutLock == moveId
 
-  if not (charging or rampaging or rolling) then
+  -- engine/battle/effect_commands.asm:977-979, data/moves/effects.asm:795-800,
+  -- engine/battle/move_effects/bide.asm:62-68
+  local biding = def.effect == "EFFECT_BIDE" and state.bideTurns ~= nil
+
+  -- engine/battle/effect_commands.asm:6222-6234, :949-951
+  local called = (self.copyDepth or 0) > 0
+
+  if not (charging or rampaging or rolling or biding or called) then
     if move and (move.pp or 0) <= 0 then
-      self:emit({ kind = "message", text = "No PP left for this move!" })
+      -- BattleText_TheresNoPPLeftForThisMove (data/text/battle.asm:315).
+      self:emit({ kind = "message",
+        text = Strings("There's no PP left\nfor this move!") })
       return
     end
     if move then move.pp = (move.pp or 1) - 1 end
@@ -1471,9 +1505,38 @@ function Battle:useMove(attacker, defender, moveId)
     return
   end
 
+  -- engine/battle/move_effects/sleep_talk.asm:2, :16-19, :61
+  if def.effect == "EFFECT_SLEEP_TALK" then
+    local picked
+    if attacker.status == "sleep" and (self.copyDepth or 0) == 0 then
+      -- engine/battle/move_effects/sleep_talk.asm:40-44, :117-141
+      local pool = {}
+      for _, own in ipairs(attacker.moves or {}) do
+        local ownDef = self:moveDef(own.id)
+        local effect = ownDef and ownDef.effect
+        if own.id ~= moveId and not self:moveDisabled(attacker, own.id)
+            and not Effects.CHARGE[effect] and effect ~= "EFFECT_BIDE" then
+          pool[#pool + 1] = own.id
+        end
+      end
+      if #pool > 0 then picked = pool[rand(self.random, #pool) + 1] end
+    end
+    if not picked then
+      self:markMissed()
+      self:emit({ kind = "message", text = "But it failed!" })
+      return
+    end
+    state.lastMove = nil
+    self.copyDepth = (self.copyDepth or 0) + 1
+    self:useMove(attacker, defender, picked)
+    self.copyDepth = self.copyDepth - 1
+    return
+  end
+
   -- Everything past here counts as "the user's last move" for Mirror Move,
-  -- Encore and Disable.
-  state.lastMove = moveId
+  -- Encore and Disable.  A called move skips the write
+  -- (engine/battle/used_move_text.asm:30-36).
+  if (self.copyDepth or 0) == 0 then state.lastMove = moveId end
   state.turnsTaken = (state.turnsTaken or 0) + 1
   state.usedMoves = state.usedMoves or {}
   local seen = false
@@ -1494,6 +1557,15 @@ function Battle:useMove(attacker, defender, moveId)
   if def.effect == "EFFECT_SOLARBEAM" and self.weather == "sun" then
     charge = nil
   end
+  if charge and not charging and Runtime.wantsHook("battle.charge_required") then
+    local required = Runtime.call("battle.charge_required", function(c)
+      return c.charge
+    end, {
+      battle = self, user = attacker, target = defender, move = def,
+      charge = true, isCalled = (self.copyDepth or 0) > 0,
+    })
+    if required == false then charge = nil end
+  end
   if charge and not charging then
     state.chargeMove = moveId
     state.vanished = charge.vanish or nil
@@ -1507,6 +1579,13 @@ function Battle:useMove(attacker, defender, moveId)
     return
   end
 
+  -- BattleCommand_Snore (engine/battle/move_effects/snore.asm:1-9)
+  if def.effect == "EFFECT_SNORE" and attacker.status ~= "sleep" then
+    self:markMissed()
+    self:emit({ kind = "message", text = "But it failed!" })
+    return
+  end
+
   -- Counter and Mirror Coat answer what the user took this turn, at double,
   -- and fail outright when nothing of the right kind landed.
   local counterKind = Effects.COUNTER[def.effect]
@@ -1738,8 +1817,12 @@ function Battle:useMove(attacker, defender, moveId)
       landed = landed + 1
     end
     if landed > 1 then
-      self:emit({ kind = "message",
-        text = ("Hit %d time(s)!"):format(landed) })
+      -- PlayerHitTimesText / EnemyHitTimesText (data/text/battle.asm:749,755)
+      -- are "Hit @ times!".  Gen 2 has no singular form of this line, so the
+      -- plural stands even at one hit rather than the "(s)" this printed.
+      -- Gen 1 already says it this way (src/battle/EffectRegistry.lua,
+      -- _HitXTimesText).
+      self:emit({ kind = "message", text = Strings("Hit %d times!", landed) })
     end
 
     -- move_effects/pay_day.asm:13
@@ -1959,8 +2042,11 @@ Battle.MOVE_EFFECTS.EFFECT_PERISH_SONG = function(self)
   if mine.perish and theirs.perish then return fail(self) end
   if not mine.perish then mine.perish = Effects.PERISH_TURNS end
   if not theirs.perish then theirs.perish = Effects.PERISH_TURNS end
+  -- StartPerishText (data/text/battle.asm:986).  What shipped here was a
+  -- sentence no cart prints; the Gen 2 line names both sides and counts in
+  -- digits.
   self:emit({ kind = "message",
-    text = "All POKéMON hearing the song will faint in three turns!" })
+    text = Strings("Both POKéMON will\nfaint in 3 turns!") })
 end
 
 -- BattleCommand_Encore: 3-6 turns locked into the move the target last used.
@@ -2090,6 +2176,11 @@ Battle.MOVE_EFFECTS.EFFECT_SPIKES = function(self, attacker, defender)
   local side = self:sideOf(defender)
   if self.spikes[side] then return fail(self) end
   self.spikes[side] = true
+  -- SpikesText (data/text/battle.asm:974) is three rows, the third scrolled
+  -- (`cont`) and carrying <TARGET>.  The battle message path has no `cont`:
+  -- src/ui/gen2/BattleState.lua sets self.message straight from the event and
+  -- printMessage cuts past two rows, so the cart's line cannot be told here
+  -- yet without the name being dropped on screen.  Left as it stands.
   self:emit({ kind = "message", text = "Spikes were scattered all around!" })
 end
 
@@ -2124,6 +2215,8 @@ Battle.MOVE_EFFECTS.EFFECT_BIDE = function(self, attacker, defender, def, moveId
   if not state.bideTurns then
     state.bideTurns = Effects.bideTurns(self.random)
     state.bideStored = 0
+    -- engine/battle/core.asm:574-576
+    state.bideMove = moveId
     self:emit({ kind = "message",
       text = self:monName(attacker) .. " is storing energy!" })
     return
@@ -2135,7 +2228,7 @@ Battle.MOVE_EFFECTS.EFFECT_BIDE = function(self, attacker, defender, def, moveId
     return
   end
   local damage = Effects.bideDamage(state.bideStored)
-  state.bideTurns, state.bideStored = nil, nil
+  state.bideTurns, state.bideStored, state.bideMove = nil, nil, nil
   self:emit({ kind = "message",
     text = self:monName(attacker) .. " unleashed energy!" })
   if damage <= 0 then return fail(self) end
@@ -2325,7 +2418,9 @@ Battle.MOVE_EFFECTS.EFFECT_BEAT_UP = function(self, attacker, defender, def)
       { move = def, moveId = def and def.id })
     landed = landed + 1
   end
-  self:emit({ kind = "message", text = ("Hit %d time(s)!"):format(landed) })
+  -- BattleCommand_EndLoop prints the same line for Beat Up, and Beat Up can
+  -- land exactly once, which is the case the cart still prints as "times".
+  self:emit({ kind = "message", text = Strings("Hit %d times!", landed) })
 end
 
 -- BattleCommand_Heal (effect_commands.asm:5986): Recover and Rest are both
@@ -2408,6 +2503,8 @@ Battle.MOVE_EFFECTS.EFFECT_BATON_PASS = function(self, attacker)
     self.enemyIndex = target
     self.enemy = party[target]
     self.enemy.volatile = carried
+    -- engine/battle/move_effects/baton_pass.asm:59
+    self:resetParticipants()
   end
   local sent = side == "player" and self.player or self.enemy
   self:emit({ kind = "send", side = side, mon = sent,
@@ -2670,6 +2767,8 @@ Battle.MOVE_EFFECTS.EFFECT_FORCE_SWITCH = function(self, attacker, defender,
     self.enemyIndex = pick
     self.enemy = incoming
     self.stages.enemy = Battle.newStages()
+    -- ForceEnemySwitch (engine/battle/core.asm:2937)
+    self:resetParticipants()
   end
   self:emit({ kind = "send", side = self:sideOf(incoming), mon = incoming,
     hp = incoming.hp or 0, status = incoming.status or false,
@@ -3079,6 +3178,12 @@ end
 
 -- Faint bookkeeping and experience.  Returns true when the battle ended.
 function Battle:resolveFaints()
+  -- engine/battle/core.asm:2551-2556, :7116-7130, :3033-3037
+  if (self.player.hp or 0) <= 0 and self.participantsCleared ~= self.player then
+    self.participantsCleared = self.player
+    if self.playerIndex then self.participants[self.playerIndex] = nil end
+  end
+
   if (self.enemy.hp or 0) <= 0 then
     self:emit({ kind = "faint", side = "enemy",
       text = (self.wild and "Wild " or "") .. self:monName(self.enemy)
@@ -3263,7 +3368,16 @@ end
 -- `count` is the pass's own divisor -- the participant count for the first
 -- pass, the holder count for the EXP.SHARE pass -- and `halved` is whether
 -- any Share holder taxed the whole pool.
-function Battle:giveExperiencePass(loser, def, recipients, count, halved)
+--
+-- `silent` suppresses only the GainedText line.  It exists for the
+-- battle.exp_award seam below, where a mod paying the bench wants one summary
+-- line rather than a box per mon; the cart's own two passes never pass it, so
+-- vanilla prints exactly what it always did.  Everything else about the pass
+-- -- the exp, the stat exp, battle.exp_gained, "grew to level", learned moves
+-- and the forget prompt -- is unaffected, because a silent award is still an
+-- award.
+function Battle:giveExperiencePass(loser, def, recipients, count, halved,
+                                   silent)
   for _, index in ipairs(recipients) do
     local mon = self.party[index]
     if mon and (mon.hp or 0) > 0 and not mon.isEgg then
@@ -3314,10 +3428,12 @@ function Battle:giveExperiencePass(loser, def, recipients, count, halved)
           index = index,
         })
       end
+      if not silent then
         self:emit({ kind = "experience", index = index, amount = amount,
           -- BoostedExpPointsText, keyed on the traded arm alone.
           text = self:monName(mon) .. " gained "
             .. (traded and "a boosted " or "") .. amount .. " EXP. Points!" })
+      end
       if result.levels > 0 then
         -- "level up happiness mod", the cart's own comment, sitting right
         -- after the stat recalc and before the "grew to level" text.  It fires
@@ -3332,7 +3448,9 @@ function Battle:giveExperiencePass(loser, def, recipients, count, halved)
           local moveDef = self:moveDef(moveId)
           local moveName = (moveDef and moveDef.name) or moveId
           if ok then
+            -- data/text/common_3.asm:119
             self:emit({ kind = "message",
+              sfx = "Sfx_DexFanfare5079", waitSfx = true,
               text = self:monName(mon) .. " learned " .. moveName .. "!" })
           elseif reason == "full" then
             -- LearnMove's full-moveset arm calls ForgetMove, which asks with
@@ -3411,22 +3529,38 @@ function Battle:awardExperience(loser)
 
   -- battle.exp_award, the same hook BattleState:awardExp calls on Gen 1 and
   -- with the same ctx: the participant COUNT, the live participants, and an
-  -- applyShare(mon, split) a mod can call to pay one mon its own share.  The
-  -- third applyShare argument is Gen 1's EXP.ALL announcement variant; Gen 2
-  -- has no EXP.ALL (the EXP.SHARE pass below is its replacement), so it is
-  -- accepted and ignored rather than changing what is printed.  `recipients`,
-  -- `holders` and `halved` are the Gen 2 additions.
+  -- applyShare(mon, split, announce) a mod can call to pay one mon its own
+  -- share.  `recipients`, `holders` and `halved` are the Gen 2 additions.
+  --
+  -- `announce` is Gen 1's third argument (src/battle/BattleState.lua
+  -- applyShare) and means the same thing here: truthy prints the mon's
+  -- GainedText, falsy pays it silently.  That is what lets one mod source
+  -- print ONE summary line for a party-wide award on both generations instead
+  -- of a box per mon -- which is what the Exp Share mod documents and could
+  -- not do on Gold, because this argument used to be accepted and ignored.
+  --
+  -- It is honoured only when it is actually PASSED, by argument count rather
+  -- than by value.  A Gen 2-era mod calling applyShare(mon, split) was written
+  -- against a seam that always announced and keeps announcing; a caller that
+  -- passes the argument -- including an explicit nil, which is what a "pay
+  -- this one quietly" call looks like -- gets Gen 1's reading.  So no existing
+  -- mod changes behaviour, and a mod that opts in gets parity.
   if Runtime.wantsHook("battle.exp_award") then
     local alive = {}
     for _, index in ipairs(participants) do
       local mon = self.party[index]
       if mon and (mon.hp or 0) > 0 then alive[#alive + 1] = mon end
     end
-    local function applyShare(mon, split)
+    local function applyShare(mon, split, ...)
+      local announce = ...
+      -- select("#") counts an explicit nil; `announce == nil` alone could not
+      -- tell applyShare(mon, split) from applyShare(mon, split, nil), and
+      -- those two have to mean different things here.
+      local silent = select("#", ...) > 0 and not announce
       for index, candidate in ipairs(self.party) do
         if candidate == mon then
           return self:giveExperiencePass(loser, def, { index },
-            math.max(1, split or 1), halved)
+            math.max(1, split or 1), halved, silent)
         end
       end
     end
@@ -3441,8 +3575,7 @@ function Battle:awardExperience(loser)
 
   -- GiveExperiencePoints .done falls through ResetBattleParticipants into
   -- AddBattleParticipant (engine/battle/core.asm:7116 and :3033).
-  self.participants = {}
-  if self.playerIndex then self.participants[self.playerIndex] = true end
+  self:resetParticipants()
 end
 
 -- The answer to a `choose-forget`: drop the move in `slot` and put the
@@ -3463,7 +3596,9 @@ function Battle:resolveForget(index, slot, entry, moveName)
   end
   self:emit({ kind = "message",
     text = "1, 2 and… " .. self:monName(mon) .. " forgot " .. oldName .. "!" })
+  -- engine/pokemon/learn.asm:115, data/text/common_3.asm:119
   self:emit({ kind = "message",
+    sfx = "Sfx_DexFanfare5079", waitSfx = true,
     text = self:monName(mon) .. " learned "
       .. (moveName or (entry and entry.id) or "?") .. "!" })
   -- The forget path writes the slot itself rather than going through
@@ -3502,6 +3637,13 @@ function Battle:switchLocked()
   return self:volatile(self.enemy).trapsTarget == true
 end
 
+-- ResetBattleParticipants falls through into AddBattleParticipant
+-- (engine/battle/core.asm:3033 and :3037).
+function Battle:resetParticipants()
+  self.participants = {}
+  if self.playerIndex then self.participants[self.playerIndex] = true end
+end
+
 -- EnemySwitch's shift arm zeroes both participant bitfields before PlayerSwitch
 -- (engine/battle/core.asm:2959-2961).
 function Battle:shiftSwitch(index)
@@ -3524,6 +3666,7 @@ function Battle:switch(index)
   -- A mon that comes back (a REVIVE, or a second battle) has to be able to
   -- announce its own faint again; see resolveFaints.
   self.faintAnnounced = nil
+  self.participantsCleared = nil
   -- ForcePlayerMonChoice has been answered, so the next faint may ask again.
   self.pendingSwitch = nil
   self.player = mon
@@ -3761,19 +3904,41 @@ function Battle:lockedInMove(mon)
   return nil
 end
 
+-- ParsePlayerAction's bide arm (engine/battle/core.asm:569-576), enemy twin
+-- at :5650
+function Battle:fightLockedMove(mon)
+  local state = self:volatile(mon)
+  if state.bideTurns then return state.bideMove end
+  return nil
+end
+
+-- engine/battle/core.asm:627-629
+function Battle:cancelBide(mon)
+  clearBide(self:volatile(mon))
+end
+
 -- Encore forces the move; Disable forbids one.  Both are read by the screen
 -- (to grey out the move list) and by the enemy's own choice below.
+-- engine/battle/core.asm:561-566
+local function encoredMove(state, mon)
+  if not state.encore then return nil end
+  for _, move in ipairs(mon.moves or {}) do
+    if move.id == state.encore and (move.pp or 0) > 0 then
+      return state.encore
+    end
+  end
+  state.encore, state.encoreTurns = nil, nil
+  return nil
+end
+
 function Battle:forcedMove(mon)
   local locked = self:lockedInMove(mon)
   if locked then return locked end
-  local state = self:volatile(mon)
-  if not state.encore then return nil end
-  for _, move in ipairs(mon.moves or {}) do
-    if move.id == state.encore and (move.pp or 0) > 0 then return state.encore end
-  end
-  -- Encore ends early when the move runs out of PP.
-  state.encore, state.encoreTurns = nil, nil
-  return nil
+  -- ParsePlayerAction reads SUBSTATUS_ENCORED ahead of the bide arm
+  -- (engine/battle/core.asm:561-566).
+  local encored = encoredMove(self:volatile(mon), mon)
+  if encored then return encored end
+  return self:fightLockedMove(mon)
 end
 
 function Battle:moveDisabled(mon, moveId)
@@ -3787,8 +3952,9 @@ function Battle:usableMoves(mon)
   -- .CheckPlayerHasUsableMoves (core.asm:533-556), so a Rollout or a rampage
   -- that spent its last PP on the opening turn keeps running: no later turn
   -- of the lock spends any.  Encore is not in this exemption -- forcedMove
-  -- ends it the moment the encored move runs dry.
-  local locked = self:lockedInMove(mon)
+  -- ends it the moment the encored move runs dry.  Bide is exempt too:
+  -- .CheckPlayerHasUsableMoves lives inside MoveSelectionScreen (core.asm:5058).
+  local locked = self:lockedInMove(mon) or self:fightLockedMove(mon)
   local out = {}
   for _, move in ipairs(mon.moves or {}) do
     local ok = (move.pp or 0) > 0 and not self:moveDisabled(mon, move.id)
@@ -3990,6 +4156,8 @@ function Battle:enemyTrySwitchOrItem()
         .. self:monName(outgoing) .. "!" })
     self.enemyIndex = target
     self.enemy = self.enemyParty[target]
+    -- AI_Switch (engine/battle/ai/items.asm:697)
+    self:resetParticipants()
     -- ResetEnemyBattleVars (engine/battle/core.asm:3016) zeroes wCurEnemyMove
     -- and wLastEnemyMove and NewEnemyMonStatus wipes the substatus bytes, so
     -- the mon coming IN starts from an empty area -- the same pair of clears
@@ -4080,9 +4248,16 @@ function Battle:vanillaEnemyMove()
   -- move answers "TYPHLOSION's attack missed!", so Hitmonlee cannot be damaged
   -- by anything, at any level.  Fifteen straight attempts at the Elite Four
   -- died there, and no amount of grinding could ever have got past it.
-  local charged = self:volatile(self.enemy).chargeMove
+  local enemyState = self:volatile(self.enemy)
+  local charged = enemyState.chargeMove
   if charged then return charged end
 
+  -- engine/battle/core.asm:5524-5533: the encore arm runs ahead of
+  -- CheckEnemyLockedIn (:5650).
+  local encored = encoredMove(enemyState, self.enemy)
+  if encored then return encored end
+  if enemyState.bideTurns then return enemyState.bideMove end
+
   -- Encore and Disable narrow the pool before the AI ever scores it.
   local moves = self:usableMoves(self.enemy)
   if #moves == 0 then
@@ -4176,6 +4351,7 @@ local function runTurn(self, action)
     -- (engine/battle/core.asm:5035-5038), which reopens the 2x2 menu with the
     -- turn unspent -- so a refused RUN never bought the enemy a free attack.
     if self.runRefused then return self:takeEvents() end
+    self:cancelBide(self.player)
     action = { kind = "skip" }
   end
 
@@ -4191,6 +4367,9 @@ local function runTurn(self, action)
   if action.kind == "item" and Battle.X_ITEMS[action.item] then
     Happiness.change(self.player, "USEDXITEM")
   end
+  -- engine/battle/core.asm:572-573 into :627-629; a switch takes :570-571
+  -- instead and keeps the store.
+  if action.kind == "item" then self:cancelBide(self.player) end
 
   -- AI_SwitchOrTryItem runs BEFORE the move is chosen: a trainer that decides
   -- to rotate or drink a potion spends its whole turn on it.
@@ -4239,7 +4418,6 @@ local function runTurn(self, action)
 
   local function playerAttack()
     if action.kind ~= "move" then return end
-    if not self:canAct(self.player) then return end
     local move = action.move
     -- An encored mon has no choice, whatever the menu said.
     local forced = self:forcedMove(self.player)
@@ -4259,13 +4437,20 @@ local function runTurn(self, action)
     -- player's own mon spends the rest of the battle underground.
     local stored = self:volatile(self.player).chargeMove
     if stored then move = stored end
+    -- engine/battle/core.asm:558-598 settles wCurPlayerMove before
+    -- engine/battle/effect_commands.asm:193 reads it.
+    if not self:canAct(self.player, move) then return end
     -- CheckPlayerLockedIn quits before .CheckPlayerHasUsableMoves and before
     -- checkobedience, so a locked Rollout or Thrash is exempt from the
     -- Struggle substitution and the obedience roll the same way the second
     -- half of a charge move is.
     local charging = self:volatile(self.player).chargeMove == move
       or self:lockedInMove(self.player) == move
-    if not charging and not self:hasUsableMoves(self.player) then
+    -- engine/battle/core.asm:5058, and data/moves/effects.asm:796 keeps
+    -- `checkobedience`.
+    local bideLocked = self:fightLockedMove(self.player) == move
+    if not charging and not bideLocked
+        and not self:hasUsableMoves(self.player) then
       self:emit({ kind = "message",
         text = self:monName(self.player) .. " has no moves left!" })
       move = Battle.STRUGGLE
@@ -4303,7 +4488,7 @@ local function runTurn(self, action)
       -- against a trainer, could not be escaped either.
       enemyMoveId = Battle.STRUGGLE
     end
-    if not self:canAct(self.enemy) then return end
+    if not self:canAct(self.enemy, enemyMoveId) then return end
     -- CheckEnemyTurn's disabled arm (engine/battle/effect_commands.asm:562-574):
     -- the AI chose before the player's Disable landed, so the turn is spent here.
     if self:moveDisabled(self.enemy, enemyMoveId) then

src/core/Game.lua

@@ -919,16 +919,7 @@ function Game:gamepadaxis(joystick, axis, value)
   Input:gamepadaxis(joystick, axis, value)
 end
 
--- conf.lua turns the mobile accelerometer-joystick off (#468), but guard the
--- generic joystick path anyway: any sensor-style device that still reaches us
--- has gravity pinning an axis past the deadzone, which would hide the touch
--- overlay every instant and steer the player by tilt through the axis-1/2
--- mapping (#459).  Real controllers arrive as SDL gamepads or named sticks,
--- never as "* Accelerometer".
-local function isAccelerometer(joystick)
-  local name = joystick and joystick.getName and joystick:getName()
-  return name ~= nil and name:lower():find("accelerometer", 1, true) ~= nil
-end
+local isAccelerometer = GamepadMap.isAccelerometer
 
 -- BindingsMenu's raw-stick capture rides the same top-state routing as the
 -- keyboard and gamepad paths (#632).  Only a stick SDL does not recognize

src/core/Game2.lua

@@ -18,6 +18,7 @@ local Chrome = require("src.ui.gen2.Chrome")
 local Clock = require("src.core.gen2.Clock")
 local FixedStep = require("src.core.FixedStep")
 local Font = require("src.render.Font")
+local GamepadMap = require("src.core.GamepadMap")
 local Input = require("src.core.Input")
 local Music = require("src.core.Music")
 local Save = require("src.core.gen2.Save")
@@ -57,20 +58,6 @@ Game2.__index = Game2
 
 local function noop() end
 
-for _, name in ipairs({
-  "joystickpressed", "joystickreleased", "joystickaxis", "joystickhat",
-  "joystickadded",
-}) do
-  Game2[name] = noop
-end
-
--- Not a noop, because the overlay has to come back on its own: a player who
--- unplugs the only controller would otherwise have to tap a blind screen to
--- get the pad back (src/core/Game.lua:869 does the same).
-function Game2:joystickremoved()
-  TouchControls:joystickremoved()
-end
-
 -- THE FRAME AND INPUT SEAMS.
 --
 -- Gold composites its own frame (Game2:draw / drawScene) and pumps its own pad
@@ -496,8 +483,10 @@ function Game2:learnMoveOn(mon, moveId, onDone)
     if onDone then onDone(learned) end
   end
   if ok then
+    -- data/text/common_3.asm:119
     return self:say(("%s learned\n%s!"):format(name, moveName),
-      function() finish(true) end)
+      function() finish(true) end,
+      TextBox.soundOpts(self, "Sfx_DexFanfare5079"))
   end
   if reason ~= "full" then return finish(false) end
   local askForget, pickMove, askStop
@@ -552,9 +541,11 @@ function Game2:learnMoveOn(mon, moveId, onDone)
         -- The slot is written here rather than through Mon.learnMove, so
         -- pokemon.move_learned is raised here too.
         ModRuntime.emit("pokemon.move_learned", { mon = mon, moveId = moveId })
+        -- engine/pokemon/learn.asm:115, data/text/common_3.asm:119
         self:say(("1, 2 and… Poof!\f%s forgot\n%s.\fAnd…\f%s learned\n%s!")
           :format(name, oldName, name, moveName),
-          function() finish(true) end)
+          function() finish(true) end,
+          TextBox.soundOpts(self, "Sfx_DexFanfare5079"))
       end,
     })
   end
@@ -719,7 +710,9 @@ function Game2:usePartyItem(itemId)
       })
     elseif action == "candy" then
       self:consumeItem(itemId)
-      self:say(result.text, function() self:afterRareCandy(mon, result) end)
+      -- data/text/common_1.asm:86
+      self:say(result.text, function() self:afterRareCandy(mon, result) end,
+        result.sfx and TextBox.soundOpts(self, result.sfx) or nil)
     else
       self:consumeItem(itemId)
       self:say(result.text)
@@ -778,8 +771,10 @@ function Game2:useSelectItem()
     local name = (items[itemId] and items[itemId].name) or itemId
     self:say(Strings("{PLAYER} used the\n%s.", name))
   elseif outcome == "trophy_sent" then
+    -- data/text/common_3.asm:372
     self:say(Strings(
-      "There was a trophy\ninside!\fThe trophy was\nsent home."))
+      "There was a trophy\ninside!\fThe trophy was\nsent home."),
+      nil, TextBox.soundOpts(self, "Sfx_DexFanfare5079"))
   end
   -- Anything else (a fishing bite, the ITEMFINDER's queued script) already
   -- drives its own presentation off World:step -- nothing left to print here.
@@ -791,9 +786,9 @@ end
 -- onDone that popped again ate the state UNDER the box: dismissing a message
 -- over the PACK closed the PACK with it, and over an empty overworld stack it
 -- was a silent extra pop.
-function Game2:say(text, onDone)
+function Game2:say(text, onDone, opts)
   local TextBox = require("src.render.TextBox")
-  self.stack:push(TextBox.new(self, text, onDone))
+  self.stack:push(TextBox.new(self, text, onDone, opts))
 end
 
 -- The landmark the player is standing in, for the Pokegear map's marker.
@@ -1968,7 +1963,11 @@ function Game2:applyOptions()
   local options = self.options or {}
   Music.applyOptions(options)
   require("src.core.Sound").applyOptions(options)
-  require("src.render.Zoom").applyOptions(options)
+  local Zoom = require("src.render.Zoom")
+  Zoom.applyOptions(options)
+  local caps = require("src.core.Performance").applyOptions(options)
+  Zoom.allowSurvey = caps.survey
+  if not caps.survey and Zoom.offset < 0 then Zoom.offset = 0 end
   require("src.render.Tilt").applyOptions(options)
   require("src.render.GbcPalette").applyOptions(options)
   -- engine/gfx/load_font.asm:29 LoadFrame, off options.lua's wTextboxFrame.
@@ -1993,6 +1992,13 @@ function Game2:applyOptions()
   end
 end
 
+function Game2:_cycleSpeed(dir)
+  local GameSpeed = require("src.core.GameSpeed")
+  self.options.speed = GameSpeed.cycle(self.options.speed, dir)
+  if self.save then self.save.options = self.options end
+  self:persistOptions()
+end
+
 -- `back` -- SDL's name for the small left-hand menu button: Xbox VIEW, the PS
 -- CREATE/SHARE beside the touchpad, the Switch MINUS -- is SELECT, and has been
 -- since src/core/GamepadMap.lua's DEFAULT_GAMEPAD_BINDINGS was written
@@ -2003,27 +2009,49 @@ end
 -- the PACK's move-item, the party menu's reorder and half the soft-reset chord
 -- (A+B+SELECT+START) were all unreachable from a pad, and pressing the button
 -- to find out killed the process.  It reaches Input like every other button now.
-function Game2:gamepadpressed(_joystick, button)
+function Game2:gamepadpressed(joystick, button)
   -- a controller is being used: the touch overlay steps aside until the next
   -- screen touch (mobile only; a no-op elsewhere)
   TouchControls:noteGamepad()
-  -- The shoulders cycle GAME SPEED, as they do in the Gen 1 path.
-  if button == "rightshoulder" or button == "leftshoulder" then
-    local GameSpeed = require("src.core.GameSpeed")
-    local dir = button == "rightshoulder" and 1 or -1
-    self.options.speed = GameSpeed.cycle(self.options.speed, dir)
-    if self.save then self.save.options = self.options end
-    self:persistOptions()
+  local selectHeld = Input:isDown("select")
+  if not selectHeld and joystick and joystick.isGamepadDown then
+    local ok, down = pcall(function()
+      return joystick:isGamepadDown("back")
+    end)
+    selectHeld = ok and down == true
+  end
+  -- shoulders and triggers cycle GAME SPEED, as in src/core/Game.lua:881
+  if not selectHeld then
+    if button == "rightshoulder" or button == "righttrigger" then
+      self:_cycleSpeed(1)
       return
+    elseif button == "leftshoulder" or button == "lefttrigger" then
+      self:_cycleSpeed(-1)
+      return
+    end
+  end
+  local top = self.stack and self.stack:top()
+  if top and top.onGamepadPressed then
+    top:onGamepadPressed(button)
+    return
+  end
+  if selectHeld then
+    local digit = GamepadMap.displayChordDigit(button)
+    if digit then
+      self:keypressed(digit)
+      return
+    end
   end
   -- START opens the start menu in the overworld; it used to quit, from before
   -- there was a menu to open.
 
-  Input:gamepadpressed(_joystick, button)
+  Input:gamepadpressed(joystick, button)
 end
 
 function Game2:gamepadreleased(joystick, button)
   Input:gamepadreleased(joystick, button)
+  local top = self.stack and self.stack:top()
+  if top and top.onGamepadReleased then top:onGamepadReleased(button) end
 end
 
 function Game2:gamepadaxis(joystick, axis, value)
@@ -2032,4 +2060,61 @@ function Game2:gamepadaxis(joystick, axis, value)
   Input:gamepadaxis(joystick, axis, value)
 end
 
+-- The raw joystick road, same bodies as src/core/Game.lua:935 (#620, #632, #1570).
+local function isRawStick(joystick)
+  return not (joystick and joystick.isGamepad and joystick:isGamepad())
+end
+
+function Game2:joystickpressed(joystick, button)
+  if GamepadMap.isAccelerometer(joystick) then return end
+  TouchControls:noteGamepad()
+  local top = self.stack and self.stack:top()
+  if isRawStick(joystick) and top and top.onJoystickPressed then
+    top:onJoystickPressed(button)
+    return
+  end
+  Input:joystickpressed(joystick, button)
+end
+
+function Game2:joystickreleased(joystick, button)
+  if GamepadMap.isAccelerometer(joystick) then return end
+  Input:joystickreleased(joystick, button)
+  local top = self.stack and self.stack:top()
+  if isRawStick(joystick) and top and top.onJoystickReleased then
+    top:onJoystickReleased(button)
+  end
+end
+
+function Game2:joystickaxis(joystick, axis, value)
+  if GamepadMap.isAccelerometer(joystick) then return end
+  if math.abs(value) > 0.5 then TouchControls:noteGamepad() end
+  Input:joystickaxis(joystick, axis, value)
+end
+
+function Game2:joystickhat(joystick, hat, direction)
+  if GamepadMap.isAccelerometer(joystick) then return end
+  if direction ~= "c" then TouchControls:noteGamepad() end
+  Input:joystickhat(joystick, hat, direction)
+end
+
+-- src/core/Game.lua:1015 (#799)
+function Game2:recoverInput()
+  Input:reset()
+  Input:reconcile()
+  TouchControls:reset()
+  if self.mods and self.mods.releaseModInput then self.mods:releaseModInput() end
+  self:cancelPointers()
+end
+
+function Game2:joystickadded()
+  self:recoverInput()
+end
+
+-- The overlay comes back on its own when the last pad is unplugged
+-- (src/core/Game.lua:1044).
+function Game2:joystickremoved()
+  self:recoverInput()
+  TouchControls:joystickremoved()
+end
+
 return Game2

src/core/GamepadMap.lua

@@ -106,6 +106,17 @@ function GamepadMap.ignoreRawForJoystick(joystick)
   return ok and isPad == true
 end
 
+-- conf.lua turns the mobile accelerometer-joystick off (#468), but guard the
+-- generic joystick path anyway: any sensor-style device that still reaches us
+-- has gravity pinning an axis past the deadzone, which would hide the touch
+-- overlay every instant and steer the player by tilt through the axis-1/2
+-- mapping (#459).  Real controllers arrive as SDL gamepads or named sticks,
+-- never as "* Accelerometer".
+function GamepadMap.isAccelerometer(joystick)
+  local name = joystick and joystick.getName and joystick:getName()
+  return name ~= nil and name:lower():find("accelerometer", 1, true) ~= nil
+end
+
 function GamepadMap.mapRawButton(index)
   if nxActive() then
     local nx = GamepadMap.NX_RAW_BUTTON_BINDINGS[index]

src/core/Input.lua

@@ -281,6 +281,7 @@ end
 
 function Input:joystickpressed(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   noteCapture(self, "joy", "pressed", button)
   local btn = self.joyBindings[button]
   if btn then press(self, btn, "joy:" .. button) end
@@ -288,6 +289,7 @@ end
 
 function Input:joystickreleased(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   noteCapture(self, "joy", "released", button)
   local btn = self.joyBindings[button]
   if btn then release(self, btn, "joy:" .. button) end
@@ -330,6 +332,7 @@ end
 
 function Input:joystickaxis(joystick, axis, value)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   if axis == 1 then
     self:gamepadaxis(joystick, "leftx", value)
   elseif axis == 2 then
@@ -343,6 +346,7 @@ end
 -- directions on top of a direction rebind.
 function Input:joystickhat(joystick, hat, direction)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   local source = "hat:" .. hat
   for _, btn in ipairs(self.hatDirs[hat] or {}) do
     release(self, btn, source)
@@ -380,7 +384,8 @@ function Input:reconcile()
   local ok, joysticks = pcall(js.getJoysticks)
   if not ok or type(joysticks) ~= "table" then return end
   for _, j in ipairs(joysticks) do
-    if GamepadMap.ignoreRawForJoystick(j) then
+    if GamepadMap.isAccelerometer(j) then
+    elseif GamepadMap.ignoreRawForJoystick(j) then
       -- SDL-recognized pad: buttons + left stick, the gamepad surfaces
       if j.isGamepadDown then
         for button, btn in pairs(self.padBindings) do

src/core/Orientation.lua

@@ -1,4 +1,4 @@
--- Screen orientation lock, Android only (#592, #716).
+-- Screen orientation lock, Android and iOS (#592, #716, #1638).
 --
 -- Persisted as options.orientation: "auto" | "portrait" | "landscape" |
 -- "reverseLandscape".  The lock travels through SDL_HINT_ORIENTATIONS:
@@ -10,16 +10,12 @@
 -- rotation lock"; LANDSCAPE allows both landscapes (SENSOR_LANDSCAPE ->
 -- USER_LANDSCAPE); REVERSE LANDSCAPE is SDL's LandscapeRight alone.
 --
--- SDL only re-reads the hint when the window is created or its resizable
--- flag changes (SDL_androidwindow.c: Android_CreateWindow /
--- Android_SetWindowResizable both call Android_JNI_SetOrientation).  LOVE
--- 11.5 exposes neither hints nor a resizable setter, so apply() goes through
--- the FFI to SDL's C API: set the hint, then pulse the window's resizable
--- flag off and back on -- each edge makes the Android backend recompute the
--- requested orientation, so a change from the launcher or the OPTION menu
--- takes hold immediately, and the flag ends where it started (conf.lua sets
--- resizable on mobile).  Everything is pcall-guarded: desktop, iOS (the
--- Info.plist governs there) and headless stubs make this a no-op.
+-- Android only re-reads the hint at window creation or on a resizable-flag
+-- change (SDL_androidwindow.c), and SDL_SetWindowResizable early-returns on
+-- a fullscreen window (SDL_video.c:2237) -- which LOVE's Android window
+-- always is -- so the hint never reached a running activity (#1638).
+-- apply() sets the hint for a later window, then goes over JNI for the live
+-- one.  iOS needs only the hint.  Desktop and headless stubs no-op.
 
 local Orientation = {}
 
@@ -58,6 +54,11 @@ function Orientation.isAndroid()
   return love.system.getOS() == "Android"
 end
 
+function Orientation.isIOS()
+  if not love or not love.system or not love.system.getOS then return false end
+  return love.system.getOS() == "iOS"
+end
+
 function Orientation.cycle(mode, dir)
   local cur, idx = Orientation.normalize(mode), 1
   for i, m in ipairs(Orientation.MODES) do
@@ -67,6 +68,15 @@ function Orientation.cycle(mode, dir)
   return Orientation.MODES[(idx - 1 + (dir or 1)) % n + 1]
 end
 
+-- ActivityInfo constants, what setOrientationBis lands on per hint after
+-- GameActivity's *_SENSOR -> *_USER remap (#716).
+local REQUESTED = {
+  auto = 13,
+  portrait = 1,
+  landscape = 11,
+  reverseLandscape = 8,
+}
+
 -- The SDL2 C API this module needs.  cdef errors on redefinition, so run it
 -- once and remember whether it took; ffi itself may be absent (plain Lua
 -- test interpreters), hence the pcall'd require.
@@ -77,33 +87,79 @@ local function sdlFfi()
   if cdefOk == nil then
     cdefOk = pcall(ffi.cdef, [[
       typedef struct SDL_Window SDL_Window;
+      typedef union { int32_t i; int64_t pad; } love_jvalue;
       int SDL_SetHint(const char *name, const char *value);
       SDL_Window *SDL_GL_GetCurrentWindow(void);
       void SDL_SetWindowResizable(SDL_Window *window, int resizable);
+      void *SDL_AndroidGetJNIEnv(void);
+      void *SDL_AndroidGetActivity(void);
     ]])
   end
   if not cdefOk then return nil end
   return ffi
 end
 
--- Push the mode into the live activity.  Returns true when the hint reached
--- SDL (the symbols resolved), false on any non-Android / stubbed platform.
+-- Slot numbers in JNINativeInterface (jni.h).
+local JNI_EXCEPTION_CLEAR = 17
+local JNI_DELETE_LOCAL_REF = 23
+local JNI_GET_OBJECT_CLASS = 31
+local JNI_GET_METHOD_ID = 33
+local JNI_CALL_VOID_METHOD_A = 63
+
+-- What Android_JNI_SetOrientation reaches, called directly: the hint path
+-- cannot re-run on a live fullscreen window (SDL_video.c:2237).
+local function setRequestedOrientation(ffi, requested)
+  local env = ffi.C.SDL_AndroidGetJNIEnv()
+  if env == nil then return false end
+  local activity = ffi.C.SDL_AndroidGetActivity()
+  if activity == nil then return false end
+  local fns = ffi.cast("void***", env)[0]
+  local getObjectClass = ffi.cast("void *(*)(void *, void *)", fns[JNI_GET_OBJECT_CLASS])
+  local getMethodID = ffi.cast(
+    "void *(*)(void *, void *, const char *, const char *)", fns[JNI_GET_METHOD_ID])
+  local callVoidMethodA = ffi.cast(
+    "void (*)(void *, void *, void *, love_jvalue *)", fns[JNI_CALL_VOID_METHOD_A])
+  local deleteLocalRef = ffi.cast("void (*)(void *, void *)", fns[JNI_DELETE_LOCAL_REF])
+  local exceptionClear = ffi.cast("void (*)(void *)", fns[JNI_EXCEPTION_CLEAR])
+
+  local ok = false
+  local cls = getObjectClass(env, activity)
+  if cls ~= nil then
+    local mid = getMethodID(env, cls, "setRequestedOrientation", "(I)V")
+    if mid ~= nil then
+      local args = ffi.new("love_jvalue[1]")
+      args[0].pad = 0
+      args[0].i = requested
+      callVoidMethodA(env, activity, mid, args)
+      ok = true
+    end
+    exceptionClear(env)
+    deleteLocalRef(env, cls)
+  end
+  deleteLocalRef(env, activity)
+  return ok
+end
+
+-- Returns true only when the request actually landed, never unconditionally
+-- as it once did (#1638).
 function Orientation.apply(mode)
-  if not Orientation.isAndroid() then return false end
+  local android = Orientation.isAndroid()
+  if not (android or Orientation.isIOS()) then return false end
   local ffi = sdlFfi()
   if not ffi then return false end
   mode = Orientation.normalize(mode)
-  local ok = pcall(function()
-    -- "SDL_IOS_ORIENTATIONS" is SDL_HINT_ORIENTATIONS's name (SDL_hints.h);
-    -- despite the IOS in the string, the Android backend reads it too.
+  local ok, reached = pcall(function()
+    -- SDL_HINT_ORIENTATIONS is "SDL_IOS_ORIENTATIONS" in the SDL2 Android
+    -- ships and "SDL_ORIENTATIONS" in the SDL3 the iOS app links; each
+    -- engine ignores the other's key.
     ffi.C.SDL_SetHint("SDL_IOS_ORIENTATIONS", HINTS[mode])
-    local win = ffi.C.SDL_GL_GetCurrentWindow()
-    if win ~= nil then
-      ffi.C.SDL_SetWindowResizable(win, 0)
-      ffi.C.SDL_SetWindowResizable(win, 1)
-    end
+    ffi.C.SDL_SetHint("SDL_ORIENTATIONS", HINTS[mode])
+    -- On iOS the hint is the lock: UIKit re-asks on every rotation
+    -- (SDL_uikitviewcontroller.m supportedInterfaceOrientations).
+    if not android then return true end
+    return setRequestedOrientation(ffi, REQUESTED[mode])
   end)
-  return ok
+  return ok and reached == true
 end
 
 function Orientation.applyOptions(opts)

src/core/Performance.lua

@@ -86,8 +86,11 @@ function Performance.detect()
   local cores = processorCount()
 
   -- PortMaster-style ARM Linux handhelds (e.g. the RG34XXSP the project
-  -- already ships a build for): the weakest target here.
-  if isArm and os ~= "Android" and os ~= "iOS" then
+  -- already ships a build for): the weakest target here.  Desktop ARM
+  -- (Apple Silicon "OS X", Windows-on-ARM) is not a handheld — those
+  -- used to resolve AUTO → LOW, which stripped survey zoom-out from
+  -- OPTIONS so the ZOOM row only offered IN.
+  if isArm and os == "Linux" then
     return "low"
   end
   -- Phones and tablets: GBC FX is already force-disabled here (issue #136);

src/core/SaveData.lua

@@ -1700,6 +1700,14 @@ local function clamp(n, lo, hi, fallback)
   return n
 end
 
+-- PP and the PP Up count are unsigned bit fields of one byte
+-- (constants/pokemon_data_constants.asm:101-102)
+local function ppInt(v, fallback)
+  local n = tonumber(v)
+  if n == nil or n ~= n or n == math.huge or n == -math.huge then return fallback end
+  return math.max(0, math.floor(n))
+end
+
 local function ensureOrphaned(save)
   if not save.orphaned then
     save.orphaned = { mons = {}, items = {} }
@@ -1763,7 +1771,7 @@ local function scrubKnownMon(mon, data)
   -- (status_screen.asm:66-76, add_mon.asm _MoveMon); deriving once here means
   -- every later reader (menus, battle, items, SGB bar zones, the link
   -- fingerprint) sees a party-shaped mon.  Runs after the level clamp above
-  -- so the derived stats use a sane level.  A save that already has stats is
+  -- so the derived stats use a sane level.  A complete stat block is
   -- untouched.
   Stats.ensure(data.pokemon and data.pokemon[mon.species], mon)
   local moves = mon.moves
@@ -1783,6 +1791,18 @@ local function scrubKnownMon(mon, data)
       moves[1] = { id = fallback, pp = def.pp }
     end
   end
+  -- the replacement PP mirrors AddBonusPP (engine/items/item_effects.asm:2418);
+  -- Mimic rewrites the move id and not the PP (engine/battle/effects.asm:1266)
+  for j = 1, #moves do
+    local slot = moves[j]
+    if type(slot) == "table" then
+      local mdef = data.moves and data.moves[slot.id]
+      local base = ppInt(mdef and mdef.pp, 0)
+      local ppUps = math.min(3, ppInt(slot.ppUps, 0))
+      if slot.ppUps ~= nil then slot.ppUps = ppUps end
+      slot.pp = ppInt(slot.pp, base + ppUps * math.floor(base / 5))
+    end
+  end
 end
 
 local function scrubMonList(list, where, save, data, report)

src/core/ScreenPosition.lua

@@ -12,10 +12,12 @@ function ScreenPosition.normalize(v)
 end
 
 function ScreenPosition.label(v)
+  if ScreenPosition.skinActive() then return "SKIN" end
   return LABELS[ScreenPosition.normalize(v)]
 end
 
 function ScreenPosition.cycle(v, dir)
+  if ScreenPosition.skinActive() then return ScreenPosition.normalize(v) end
   v = ScreenPosition.normalize(v)
   local modes = ScreenPosition.MODES
   local cur = 1
@@ -44,6 +46,9 @@ end
 function ScreenPosition.skinActive(w, h)
   local ok, TouchSkin = pcall(require, "src.core.TouchSkin")
   if not ok or type(TouchSkin.viewport) ~= "function" then return false end
+  if (not w or not h) and love and love.graphics and love.graphics.getDimensions then
+    w, h = love.graphics.getDimensions()
+  end
   local okv, x = pcall(TouchSkin.viewport, w, h)
   return okv and x ~= nil
 end

src/core/Sound.lua

@@ -154,8 +154,14 @@ local function newSfxSource(data, key, def, pitch, tempo, plain)
   return newFileSource(def)
 end
 
+local function deviceSuspended()
+  local ChipAudio = package.loaded["src.core.ChipAudio"]
+  return ChipAudio ~= nil and ChipAudio.isSuspended()
+end
+
 local function playPath(data, key, def, pitch, tempo, plain)
   if not love.audio or not def then return nil end
+  if deviceSuspended() then return nil end
   local src = cache[key]
   if src == false then return nil end -- known bad, already logged
   if not src then
@@ -602,6 +608,7 @@ end
 -- cache carries no clips (Red/Blue) or headless.
 function Sound.playPikaCry(data, n)
   if not love.audio then return nil end
+  if deviceSuspended() then return nil end
   local count = data.audio and data.audio.pikaCries
   if not count then return nil end
   n = math.max(1, math.min(count, n or 1))
@@ -633,6 +640,7 @@ end
 -- like the original's PlayCry -> WaitForSoundToFinish can poll it
 function Sound.playCry(data, species, pikaClip)
   if not love.audio then return nil end
+  if deviceSuspended() then return nil end
   -- Yellow voices every Pikachu cry with the PCM clips (the chip cry is
   -- never used for the species there).  Which clip is a property of the
   -- call site in the original -- every caller of PlayPikachuSoundClip sets

src/core/TouchControls.lua

@@ -293,7 +293,9 @@ function TouchControls:applyOptions(opts)
   -- launcher editor round-trips through config() (#806)
   self.haptics = TouchControls.normalizeHaptics(opts and opts.haptics)
   TouchSkin.setOverlayLive(self.active)
-  self:selectSkin(cfg.skin)
+  -- Off means off everywhere: do not leave a hidden selected skin behind to
+  -- influence renderer placement on desktop or with a controller attached.
+  self:selectSkin(cfg.enabled and cfg.skin or nil)
   self.layouts = cfg.layouts
   self.layoutW, self.layoutH = nil, nil
   self.layoutOx, self.layoutOy = nil, nil
@@ -335,7 +337,10 @@ function TouchControls:visible()
   local art = TouchSkin.active ~= nil or self.img ~= nil
   if self.preview then return art end
   if self.enabled == false or not art then return false end
-  if TouchSkin.active and TouchSkin.decorativeOnly() then return true end
+  -- A selected skin is also a desktop/TV bezel.  Input remains gated in
+  -- touchpressed, but the artwork must not disappear when a controller is
+  -- connected or the platform is not touch-first.
+  if TouchSkin.active then return true end
   return self.active and not self.controllerHidden
 end
 
@@ -778,12 +783,19 @@ local function drawIcon(img, zone, pressed, alphaMul)
                      zone.cy - img:getHeight() * scale / 2, 0, scale, scale)
 end
 
-local function drawStretched(img, x, y, w, h, alpha)
+local function drawCovered(img, x, y, w, h, alpha)
   if not img or alpha <= 0 then return end
   local iw, ih = img:getWidth(), img:getHeight()
   if iw <= 0 or ih <= 0 then return end
+  -- Cover the assigned box with one uniform scale and crop the excess.  The
+  -- old independent X/Y scale made portrait art visibly squash on wide
+  -- displays (and vice versa).
+  local s = math.max(w / iw, h / ih)
+  local dw, dh = iw * s, ih * s
   love.graphics.setColor(1, 1, 1, math.min(1, alpha))
-  love.graphics.draw(img, x, y, 0, w / iw, h / ih)
+  love.graphics.setScissor(x, y, w, h)
+  love.graphics.draw(img, x + (w - dw) * 0.5, y + (h - dh) * 0.5, 0, s, s)
+  love.graphics.setScissor()
 end
 
 function TouchControls:drawSkin(alphaMul)
@@ -795,7 +807,7 @@ function TouchControls:drawSkin(alphaMul)
 
   love.graphics.push("all")
   love.graphics.origin()
-  drawStretched(page.image, bx, by, bw, bh, opacity)
+  drawCovered(page.image, bx, by, bw, bh, opacity)
 
   local pressed = {}
   for _, touch in pairs(self.touches or {}) do
@@ -810,7 +822,7 @@ function TouchControls:drawSkin(alphaMul)
         TouchSkin.controlGeometry(page, ctl, ww, wh, sox, soy)
       local alpha = opacity
       if down and not ctl.pressedImage then alpha = opacity * ctl.alphaMod end
-      drawStretched(img, cx - halfW, cy - halfH, halfW * 2, halfH * 2, alpha)
+      drawCovered(img, cx - halfW, cy - halfH, halfW * 2, halfH * 2, alpha)
     end
   end
 

src/core/TouchSkin.lua

@@ -294,7 +294,6 @@ function TouchSkin.parse(text)
       page.viewport = { x = num(vp[1], 0), y = num(vp[2], 0),
                         w = num(vp[3], 1), h = num(vp[4], 1) }
       page.viewportFill = toBool(kv[p .. "_viewport_fill"])
-      page.viewportExpand = toBool(kv[p .. "_viewport_expand"])
     end
 
     page.pixelCoords = not page.normalized
@@ -447,7 +446,6 @@ function TouchSkin.parseNative(text)
       page.viewport = { x = num(raw.viewport.x, 0), y = num(raw.viewport.y, 0),
                         w = num(raw.viewport.w, 1), h = num(raw.viewport.h, 1) }
       page.viewportFill = raw.viewport.fill == true
-      page.viewportExpand = raw.viewport.expand == true
     end
     for _, c in ipairs(raw.controls or {}) do
       local buttons, hotkeys, keys, decorative = parseBinds(c.bind or "nul")
@@ -526,7 +524,6 @@ function TouchSkin.toNative(skin)
         x = page.viewport.x, y = page.viewport.y,
         w = page.viewport.w, h = page.viewport.h,
         fill = page.viewportFill or nil,
-        expand = page.viewportExpand or nil,
       }
     end
     for _, ctl in ipairs(page.controls or {}) do
@@ -636,6 +633,19 @@ local function applyPixelScale(page)
   return true
 end
 
+-- An overlay image is its own design canvas.  Older RetroArch cfg files often
+-- omit `aspect_ratio`; reading the dimensions here keeps that legacy art and
+-- all of its normalized controls on the same uniform scale.
+function TouchSkin.applyImageAspect(page)
+  if not page or page.aspectFromCfg or not page.image
+     or not page.image.getDimensions then return false end
+  local iw, ih = page.image:getDimensions()
+  if not iw or not ih or iw <= 0 or ih <= 0 then return false end
+  page.aspect = iw / ih
+  page.aspectFromImage = true
+  return true
+end
+
 function TouchSkin.load(root, id)
   local cfgPath, format, prefix = findConfig(root)
   if not cfgPath then return nil, "no skin.lua, .cfg or info.json in " .. root end
@@ -665,6 +675,7 @@ function TouchSkin.load(root, id)
     elseif page.pdfPath then
       rasterizePdfPage(page, root)
     end
+    TouchSkin.applyImageAspect(page)
     if not applyPixelScale(page) then
       return nil, "could not read " .. tostring(page.imagePath)
         .. ", which " .. page.name .. " measures its coordinates against"
@@ -771,6 +782,28 @@ function TouchSkin.find(id)
   return nil
 end
 
+-- Remove only a user-installed skin.  Bundled skins are shipped with the
+-- game and intentionally have no delete affordance.
+function TouchSkin.remove(id)
+  local entry = TouchSkin.find(id)
+  if not entry then return nil, "no skin " .. tostring(id) end
+  if entry.source ~= "user" then return nil, "bundled skins cannot be deleted" end
+  if not (love and love.filesystem and love.filesystem.remove) then
+    return nil, "no writable filesystem"
+  end
+  local function removeTree(path)
+    if isDir(path) and love.filesystem.getDirectoryItems then
+      for _, name in ipairs(love.filesystem.getDirectoryItems(path)) do
+        local ok, err = removeTree(path .. "/" .. name)
+        if not ok then return nil, err end
+      end
+    end
+    local ok, err = love.filesystem.remove(path)
+    return ok and true or nil, err
+  end
+  return removeTree(entry.archive or (TouchSkin.USER_ROOT .. "/" .. entry.id))
+end
+
 function TouchSkin.assetPaths(skin)
   local out, seen = {}, {}
   local function add(rel)
@@ -886,7 +919,6 @@ function TouchSkin.toRetroArchConfig(skin)
     if page.viewport then
       out[#out + 1] = p .. "_viewport = " .. fmtRect(page.viewport)
       if page.viewportFill then out[#out + 1] = p .. "_viewport_fill = true" end
-      if page.viewportExpand then out[#out + 1] = p .. "_viewport_expand = true" end
     end
     local controls = {}
     for _, ctl in ipairs(page.controls or {}) do
@@ -1284,7 +1316,7 @@ function TouchSkin.pageBox(page, w, h, ox, oy)
   -- full_screen means "relative to the window, not the game viewport".
   -- When the cfg also names an aspect_ratio, that window is then fitted
   -- to the overlay's design aspect so buttons do not stretch.  #1503
-  local fit = ((not page.fullScreen) or page.aspectFromCfg)
+  local fit = ((not page.fullScreen) or page.aspectFromCfg or page.aspectFromImage)
     and page.aspect and page.aspect > 0 and h > 0
   if fit then
     local displayAspect = w / h
@@ -1306,6 +1338,11 @@ function TouchSkin.pageBox(page, w, h, ox, oy)
         by = oy + extra
       elseif anchor == "top" then
         by = oy
+      elseif page.aspect < 1 then
+        -- A portrait bezel with controls is a controller deck.  On an
+        -- unusually tall display, pin the deck to the lower edge and leave
+        -- the additional room for the game above it.
+        by = oy + extra
       else
         by = oy + extra * 0.5
       end
@@ -1359,8 +1396,10 @@ function TouchSkin.decorativeOnly()
 end
 
 function TouchSkin.drawable()
-  if not TouchSkin.active then return false end
-  return TouchSkin.overlayLive or TouchSkin.decorativeOnly()
+  -- A selected skin is a presentation choice, not a mobile-only input mode.
+  -- Its artwork and screen placement therefore belong on every platform;
+  -- `overlayLive` still controls whether touch input is available.
+  return TouchSkin.active ~= nil
 end
 
 function TouchSkin.hasViewport()
@@ -1391,6 +1430,16 @@ local function remainderBox(ox, oy, w, h, bx, by, bw, bh)
   return best[1], best[2], best[3], best[4]
 end
 
+-- The deck box pinned to the lower edge (see pageBox) leaves room above it
+-- that belongs to the game, so a screen rect flush with the top of the deck
+-- grows into it instead of showing a black band.
+local function deckHeadroom(y, vh, by, bh, oy, h)
+  if by <= oy + 0.5 then return y, vh end
+  if by + bh < oy + h - 0.5 then return y, vh end
+  if y - by > math.max(2, bh * 0.01) then return y, vh end
+  return oy, vh + (y - oy)
+end
+
 function TouchSkin.pageViewport(page, w, h, ox, oy)
   if not page then return nil end
   ox, oy = ox or 0, oy or 0
@@ -1400,16 +1449,27 @@ function TouchSkin.pageViewport(page, w, h, ox, oy)
     local x, y = bx + v.x * bw, by + v.y * bh
     local vw, vh = v.w * bw, v.h * bh
     if vw <= 0 or vh <= 0 then return nil end
-    return x, y, vw, vh, page.viewportFill == true, page.viewportExpand == true
+    y, vh = deckHeadroom(y, vh, by, bh, oy, h)
+    return x, y, vw, vh, page.viewportFill == true
   end
   if page.screenFit == "remainder" then
     local x, y, vw, vh = remainderBox(ox, oy, w, h, bx, by, bw, bh)
     if not x then return nil end
-    return x, y, vw, vh, false, false
+    return x, y, vw, vh, false
   end
   return nil
 end
 
+-- Centre of the page's screen cutout.  The renderer fits the 160x144
+-- picture into that rect; this helper is for the studio preview.
+function TouchSkin.screenCenter(w, h, ox, oy, page)
+  page = page or TouchSkin.page()
+  if not page then return nil end
+  local x, y, vw, vh = TouchSkin.pageViewport(page, w, h, ox, oy)
+  if not x then return nil end
+  return x + vw * 0.5, y + vh * 0.5
+end
+
 function TouchSkin.viewport(w, h, ox, oy)
   local page = TouchSkin.page()
   if not page or not TouchSkin.drawable() then return nil end

src/core/gen2/ItemEffects.lua

@@ -240,6 +240,8 @@ local function rareCandy(mon, data)
     used = true,
     level = newLevel,
     learned = learned,
+    -- data/text/common_1.asm:86
+    sfx = "Sfx_DexFanfare5079",
     text = ("%s grew to\nlevel %d!"):format(monName(mon), newLevel),
   }
 end

src/import/CacheFs.lua

@@ -287,6 +287,43 @@ function CacheFs.write(rel, data)
   return love.filesystem.write(rel, data)
 end
 
+-- Open a cache-relative file for streaming replacement. The returned handle
+-- has write(bytes) and close() methods and follows the same portable/save-dir
+-- routing as CacheFs.write without forcing the caller to hold the whole file
+-- in one Lua string.
+function CacheFs.openWrite(rel)
+  rel = withPrefix(rel)
+  local root = CacheFs.root()
+  if root then
+    ensureParents(root, rel)
+    local f, err = io.open(realPath(root, rel), "wb")
+    if not f then return nil, err end
+    return {
+      write = function(_, data)
+        local ok, writeErr = f:write(data)
+        if not ok then return nil, writeErr end
+        return true
+      end,
+      close = function() f:close() end,
+    }
+  end
+  if not (love and love.filesystem and love.filesystem.newFile) then
+    return nil, "streaming cache writes are unavailable"
+  end
+  local parent = rel:match("^(.*)/[^/]+$")
+  if parent and not love.filesystem.createDirectory(parent) then
+    local info = love.filesystem.getInfo(parent)
+    local reason = info and ("a " .. info.type .. " already exists there")
+      or "unknown reason"
+    return nil, "could not create " .. parent .. ": " .. reason
+  end
+  local file, makeErr = love.filesystem.newFile(rel)
+  if not file then return nil, makeErr or "could not create cache file" end
+  local ok, openErr = file:open("w")
+  if not ok then return nil, openErr or "could not open cache file" end
+  return file
+end
+
 -- read cache-relative `rel`; returns the bytes or nil
 function CacheFs.read(rel)
   rel = withPrefix(rel)

src/import/ImageWriter.lua

@@ -125,6 +125,26 @@ function ImageWriter.columnsToRows(raw, tilesWide, tilesHigh, bytesPerTile)
   return out
 end
 
+-- Inverse of pret tools/gfx --interleave (pokecrystal tools/gfx.c).
+-- Build-time interleave stores each vertical 8x16 pair as consecutive 8x8
+-- tiles for OBJ mode; this restores row-major sheet order for PNGs.
+function ImageWriter.deinterleave(raw, width, bytesPerTile)
+  bytesPerTile = bytesPerTile or 16
+  local widthTiles = width / 8
+  local numTiles = #raw / bytesPerTile
+  local out = {}
+  for i = 0, numTiles - 1 do
+    local row = math.floor(i / widthTiles)
+    local src = i * 2 - (row % 2 == 1
+      and widthTiles * (row + 1) - 1
+      or widthTiles * row)
+    for offset = 1, bytesPerTile do
+      out[i * bytesPerTile + offset] = raw[src * bytesPerTile + offset]
+    end
+  end
+  return out
+end
+
 function ImageWriter.save(image, path)
   local ok, fileData = pcall(image.encode, image, "png")
   if not ok then error("could not encode " .. path .. ": " .. tostring(fileData)) end

src/import/LauncherSettings.lua

@@ -6,8 +6,8 @@
 -- options.lua table (src/core/SaveData.loadOptions/saveOptions) and lets the
 -- next boot's applyOptions pick the values up.  Every ladder mirrors
 -- OptionsMenu's semantics and stored values; when editing one, keep the two
--- in sync.  ZOOM is deliberately absent: its range depends on the live
--- renderer's fit scale (Renderer:fitScale), which does not exist here.
+-- in sync.  ZOOM uses the live window's integer fit (same 160×144 rule as
+-- Renderer:fitScale) so the row can offer OUT/FIT/IN without a running game.
 --
 -- Rows are the same descriptor idiom OptionRows draws in game:
 --   { label, value = fn() -> string, step = fn(dir) -> changed,
@@ -278,6 +278,16 @@ local function coreRows(opts, hooks)
       end)
   end
 
+  local okZ, Zoom = pcall(require, "src.render.Zoom")
+  if okZ then
+    add(Strings("ZOOM"),
+      function() return Zoom.offsetLabel(opts.zoom or 0) end,
+      function(dir)
+        Zoom.nudgeOptions(opts, dir, Zoom.windowFitScale())
+        return true
+      end)
+  end
+
   local okTile, TileRenderer = pcall(require, "src.render.TileRenderer")
   if okTile and TileRenderer.VOID_FILLS then
     add(Strings("VOID FILL"),
@@ -303,15 +313,12 @@ local function coreRows(opts, hooks)
       end)
   end
 
-  -- ORIENTATION (#592): Android only -- the lock rides SDL's orientation
-  -- hint, which iOS reads only at startup (the Info.plist governs there) and
-  -- desktop ignores.  Unlike the other launcher rows this one live-applies:
-  -- the window exists here too, and rotating under the player's finger is
-  -- the only feedback that reads.
+  -- ORIENTATION (#592, #1638): mobile only.  Unlike the other launcher rows
+  -- this one live-applies: the window exists here too, and rotating under
+  -- the player's finger is the only feedback that reads.
   do
-    local osName = love.system and love.system.getOS and love.system.getOS()
     local okOr, Orientation = pcall(require, "src.core.Orientation")
-    if okOr and osName == "Android" then
+    if okOr and (Orientation.isAndroid() or Orientation.isIOS()) then
       add(Strings("ORIENTATION"),
         function() return Strings(Orientation.modeLabel(opts.orientation)) end,
         function(dir)
@@ -646,6 +653,16 @@ local function gen2Rows(opts, hooks)
       end)
   end
 
+  local okZ, Zoom = pcall(require, "src.render.Zoom")
+  if okZ then
+    add(Strings("ZOOM"),
+      function() return Zoom.offsetLabel(opts.zoom or 0) end,
+      function(dir)
+        Zoom.nudgeOptions(opts, dir, Zoom.windowFitScale())
+        return true
+      end)
+  end
+
   local okFill, BorderFill = pcall(require, "src.world.gen2.BorderFill")
   if okFill and BorderFill.VOID_FILLS then
     add(Strings("VOID FILL"),

src/import/LauncherView.lua

@@ -753,12 +753,15 @@ local function cartridgeButton(imp, x, y, w, h, key, version, gameName, action)
     -- and one below the top-right corner notch, like the DMG cart.
     local grooveW = w * 0.115
     local grooveH = math.max(1, h * 0.009)
+    local grooveScale = { 1.22, 1.10, 1.00, 1.00, 1.10, 1.22 }
+    local grooveInset = w * 0.02
     for i = 0, 5 do
       local ry = mainTop + h * 0.014 + i * h * 0.021
-      cartPolygon(cartQuad(project, -halfW + w * 0.02, ry,
-        grooveW, grooveH, faceZ), side, 0.7)
-      cartPolygon(cartQuad(project, halfW - grooveW - w * 0.02, ry,
-        grooveW, grooveH, faceZ), side, 0.7)
+      local gw = grooveW * grooveScale[i + 1]
+      cartPolygon(cartQuad(project, -halfW + grooveInset, ry,
+        gw, grooveH, faceZ), side, 0.7)
+      cartPolygon(cartQuad(project, halfW - gw - grooveInset, ry,
+        gw, grooveH, faceZ), side, 0.7)
     end
     -- The thin diagonal mold ridge cut into each long side a little below
     -- the grip grooves, mirrored left/right.
@@ -774,12 +777,14 @@ local function cartridgeButton(imp, x, y, w, h, key, version, gameName, action)
         { project(x1 + nx * t, y1 + ny * t, faceZ) },
       }, side, 0.7)
     end
-    local dgY = mainTop + h * 0.20
+    local dgY = mainTop + h * 0.25
     diagonal(-halfW + w * 0.006, dgY, -halfW + w * 0.085, dgY + h * 0.038)
     diagonal(halfW - w * 0.006, dgY, halfW - w * 0.085, dgY + h * 0.038)
-    -- The Nintendo GAME BOY recess: one stadium pill sunk into the shell.
-    local pillX, pillW = -halfW + w * 0.17, w * 0.62
-    local pillY, pillH = mainTop + h * 0.024, h * 0.115
+    -- The pill recess: one stadium pill sunk into the shell.
+    local pillX, pillW = -halfW + w * 0.19, w * 0.62
+    local pillY, pillH = mainTop + h * 0.015, h * 0.115
+    -- log out pillH
+ 
     cartPill(project, pillX, pillY, pillW, pillH, faceZ + 0.5, side, 0.55)
     local inX, inY = w * 0.008, h * 0.008
     cartPill(project, pillX + inX, pillY + inY,
@@ -1062,9 +1067,22 @@ local GAME_TABS = {
 local HEADER_TABS = {
   { id = "mods",   key = "tab-mods" },
   { id = "find",   key = "tab-find" },
-  { id = "skins",  key = "tab-skins", glyph = true },
+  { id = "skins",  key = "tab-skins", glyph = true, beta = true },
   { id = "bug",    key = "tab-bug" },
 }
+
+local BETA_TAG_OPTS = { fill = true, bold = true, ink = PAL.inverse }
+
+local function drawBetaTag(x, y, w, h)
+  Kit.tag(x, y, w, h, "BETA", PAL.yellow, BETA_TAG_OPTS)
+end
+
+local function overlayBeta(tx, ty, w, tabH, m)
+  local bh = math.floor(11 * m.s)
+  local bw = math.min(w, Kit.textWidth("micro", "BETA") + math.floor(10 * m.s))
+  drawBetaTag(tx + (w - bw) / 2, ty + tabH - bh - math.floor(2 * m.s), bw, bh)
+end
+
 for _, t in ipairs(HEADER_TABS) do
   t.opts = { face = "tab", font = "tab", color = t.color, letter = t.letter }
   if t.glyph then
@@ -1268,6 +1286,7 @@ local function buildHeader(imp, m)
     o.image = t.icon
     o.action = chrome.tab[t.id]
     btn(imp, tx, ty, w, tabH, t.key, "", o)
+    if t.beta then overlayBeta(tx, ty, w, tabH, m) end
     tx = tx + w + tabGap
   end
   -- The bug-report chip sits LAST, past the sync chip.
@@ -1285,10 +1304,7 @@ local function buildHeader(imp, m)
     local o = chrome.sync
     o.active = imp._syncModal ~= nil
     btn(imp, tx, ty, w, tabH, "tab-sync", "", o)
-    local bh = math.floor(11 * m.s)
-    local bw = math.min(w, Kit.textWidth("micro", "BETA") + math.floor(10 * m.s))
-    Kit.tag(tx + (w - bw) / 2, ty + tabH - bh - math.floor(2 * m.s), bw, bh,
-      "BETA", o.active and PAL.inverse or PAL.yellow)
+    overlayBeta(tx, ty, w, tabH, m)
     local eng = imp._sync
     if eng and eng.busy and eng:busy() then
       Kit.spinner(tx + w - math.floor(8 * m.s), ty + math.floor(8 * m.s),
@@ -1304,7 +1320,7 @@ local function buildHeader(imp, m)
   return y + math.floor(10 * m.s)
 end
 
--- The state of the self-updater, as a top-right control.
+-- The state of the self-updater, shown in the launcher footer.
 -- Returns status, label, action, glow.
 function LauncherView._updateControl(imp)
   if not imp.Check then return nil end
@@ -2142,16 +2158,20 @@ local function buildModsPanel(imp, x, y, w, availH, m)
     + math.floor(8 * m.s)
   local listTop = cy
 
-  -- One continuous list: every row is laid out, the region scroll moves
-  -- through all of it, and only rows inside the region's viewport draw --
-  -- so the per-frame cost stays bounded by the window, not the list.
+  -- One continuous list: derive the rows that can touch the viewport before
+  -- entering the loop. Drawing was already culled, but scanning every
+  -- installed row to discover that defeats the point on a large mod library.
   local view = imp._tabRegionRect
   local viewTop = view and view.y or listTop
   local viewBot = view and (view.y + view.h) or (listTop + availH)
-  for i = 1, #mods do
+  local stride = rowH + gap
+  local first = math.max(1,
+    math.ceil((viewTop - rowH - listTop) / stride) + 1)
+  local last = math.min(#mods,
+    math.floor((viewBot - listTop) / stride) + 1)
+  for i = first, last do
     local mod = mods[i]
     local ry = listTop + (i - 1) * (rowH + gap)
-    if ry + rowH >= viewTop and ry <= viewBot then
     local rowKey = rowKeyFor(imp, "mod-row-", mod.id)
     local isFullyDisabled = true
     if mod.enabledByVersion then
@@ -2261,7 +2281,6 @@ local function buildModsPanel(imp, x, y, w, availH, m)
         px, ly, PAL.detail)
     end
   end
-  end
 
   local contentH = #mods * rowH + (#mods - 1) * gap
   return (listTop + contentH + gap) - y
@@ -2269,8 +2288,8 @@ end
 
 -- ---------------------------------------------------------- find mods panel
 
--- SKINS tab: pick the on-screen skin, import one, or open the desktop studio.
-local function buildSkinsPanel(imp, x, y, w, availH, m)
+-- SKINS tab: pick the on-screen skin, import one, or open Skin Studio.
+local function buildSkinsPanelLegacy(imp, x, y, w, availH, m)
   local skins = imp:_ensureSkins()
   local active = imp:_activeSkin()
   local gap = m.gap
@@ -2324,7 +2343,7 @@ local function buildSkinsPanel(imp, x, y, w, availH, m)
   end
   cy = cy + urlH + math.floor(8 * m.s)
 
-  -- Studio button.  Desktop only: the host supplies the hook nowhere else.
+  -- The Studio reflows to a touch-first canvas plus inspector on phones.
   if imp.onOpenSkinStudio then
     local label = Strings("Open Skin Studio")
     local bw = math.min(w, Kit.textWidth("small", label) + math.floor(40 * m.s))
@@ -2344,6 +2363,64 @@ local function buildSkinsPanel(imp, x, y, w, availH, m)
   Kit.caption(x, cy, Strings("INSTALLED"))
   cy = cy + Kit.textHeight("small") + math.floor(6 * m.s)
 
+  -- Keep the actionable list below for detailed metadata and exports, but
+  -- lead with a visual picker: skins are much easier to recognize by their
+  -- bezel than by a folder name.  Cards use the same loaded art that the
+  -- runtime draws, so they cannot drift from the selected skin.
+  local previewGap = math.floor(8 * m.s)
+  local previewCols = w >= math.floor(420 * m.s) and 2 or 1
+  local previewW = (w - previewGap * (previewCols - 1)) / previewCols
+  local previewH = math.max(108 * m.s, Kit.tapMin() * 2)
+  local previewCount = #skins
+  for i, entry in ipairs(skins) do
+    local n = i - 1
+    local px = x + (n % previewCols) * (previewW + previewGap)
+    local py = cy + math.floor(n / previewCols) * (previewH + previewGap)
+    local key = "skin-preview-" .. entry.id
+    local selected = active == entry.id
+    local focused = Kit.focusable(key, px, py, previewW, previewH)
+    Kit.card(px, py, previewW, previewH, selected and "selected"
+      or (focused or Kit.hover(px, py, previewW, previewH)))
+    local pad = math.floor(8 * m.s)
+    local artH = math.floor(previewH * 0.60)
+    Theme.fillRounded(px + pad, py + pad, previewW - pad * 2, artH,
+      PAL.bg, 1, Theme.cardRadius() * 0.6)
+    local art = entry.preview
+    if art and art.getDimensions then
+      local iw, ih = art:getDimensions()
+      if iw > 0 and ih > 0 then
+        local scale = math.min((previewW - pad * 4) / iw, (artH - pad * 2) / ih)
+        love.graphics.setColor(1, 1, 1, 1)
+        love.graphics.draw(art, px + (previewW - iw * scale) * 0.5,
+          py + pad + (artH - ih * scale) * 0.5, 0, scale, scale)
+      end
+    else
+      Theme.strokeRounded(px + previewW * 0.23, py + pad + artH * 0.15,
+        previewW * 0.54, artH * 0.42, PAL.line, Theme.A.hairline, 1, 2)
+      Theme.fillRounded(px + previewW * 0.20, py + pad + artH * 0.64,
+        previewW * 0.22, artH * 0.17, PAL.steel, 0.75, 3)
+      Theme.fillRounded(px + previewW * 0.60, py + pad + artH * 0.61,
+        previewW * 0.12, artH * 0.22, PAL.steel, 0.75, artH * 0.11)
+      Theme.fillRounded(px + previewW * 0.75, py + pad + artH * 0.56,
+        previewW * 0.12, artH * 0.22, PAL.steel, 0.75, artH * 0.11)
+    end
+    Kit.text("mono", Kit.ellipsize("mono", entry.id, previewW - pad * 2),
+      px + pad, py + pad + artH + math.floor(5 * m.s),
+      selected and PAL.green or PAL.heading)
+    if selected then
+      Kit.text("micro", Strings("IN USE"), px + pad,
+        py + previewH - pad - Kit.textHeight("micro"), PAL.green)
+    end
+    if Kit.press(px, py, previewW, previewH) or Kit._activateId == key then
+      queueAction(imp, key, function() imp:_useSkin(entry.id) end)
+    end
+  end
+  if previewCount > 0 then
+    cy = cy + math.ceil(previewCount / previewCols) * previewH
+      + math.max(0, math.ceil(previewCount / previewCols) - 1) * previewGap
+      + gap
+  end
+
   local rowH = math.max(Kit.tapMin(), math.floor(44 * m.s))
   imp._skinGear = imp._skinGear
     or love.graphics.newImage("assets/launcher/gear.png")
@@ -2457,6 +2534,69 @@ local function buildSkinsPanel(imp, x, y, w, availH, m)
   return cy + hintH - y
 end
 
+-- The launcher is the short path: bring a skin in, see what is enabled, or
+-- turn skin use off.  Browsing, pagination and per-skin editing/export live
+-- together in My Skins, where they are useful instead of competing here.
+local function buildSkinsPanel(imp, x, y, w, availH, m)
+  local cy, gap, bh = y, m.gap, m.btnH
+  local active = imp:_activeSkin()
+
+  Kit.text("button", Strings("Skins"), x, cy, PAL.heading)
+  local importW = math.min(w * 0.46,
+    Kit.textWidth("small", imp:_skinsImportButtonLabel()) + math.floor(24 * m.s))
+  btn(imp, x + w - importW, cy, importW, bh, "skins-import",
+    imp:_skinsImportButtonLabel(), { kind = "accent", font = "small",
+      action = function() imp:chooseSkin() end })
+  cy = cy + bh + gap
+
+  if imp._skinNotice then
+    cy = cy + Kit.textWrapped("small", imp._skinNotice.text, x, cy, w,
+      imp._skinNotice.ok and PAL.green or PAL.red, 2) + gap
+  end
+
+  local addW = Kit.textWidth("small", Strings("Add")) + math.floor(24 * m.s)
+  if imp._skinFetch then
+    Loader.inline(x, cy, w, bh, Strings("Downloading %s...",
+      tostring(imp._skinFetch.name or "")))
+  else
+    btn(imp, x + w - addW, cy, addW, bh, "skins-url-add", Strings("Add"), {
+      kind = "accent", font = "small", action = function() imp:_addSkinFromUrl() end })
+    textField(imp, x, cy, w - addW - gap, bh, "skins-url", imp.skinUrl or "",
+      Strings("Paste a skin link (.zip, .cfg, .deltaskin)"),
+      imp._skinUrlFocus == true, function() imp:_toggleSkinUrlFocus() end)
+  end
+  cy = cy + bh + gap
+
+  local currentH = active and (bh * 2 + gap * 2) or (bh + gap * 2)
+  Kit.card(x, cy, w, currentH)
+  Kit.caption(x + gap, cy + gap, "CURRENT SKIN")
+  local current = active and tostring(active) or Strings("No skin enabled")
+  Kit.text("mono", Kit.ellipsize("mono", current, w - gap * 2), x + gap,
+    cy + gap + Kit.textHeight("small") + math.floor(4 * m.s),
+    active and PAL.green or PAL.muted)
+  local buttonY = cy + bh + gap
+  local half = (w - gap * 3) * 0.5
+  if active then
+    btn(imp, x + gap, buttonY, half, bh, "skins-export-current",
+      Strings("Export current"), { font = "small",
+        action = function() imp:_exportSkin(active, "native") end })
+    btn(imp, x + gap * 2 + half, buttonY, half, bh, "skins-off",
+      Strings("Turn skins off"), { kind = "danger", font = "small",
+        action = function() imp:_disableSkins() end })
+  end
+  cy = cy + currentH + gap
+
+  if imp.onOpenSkinStudio then
+    btn(imp, x, cy, w, bh, "skins-my-skins", Strings("My Skins"), {
+      kind = "accent", font = "small",
+      action = function() imp.onOpenSkinStudio(imp.modScope or "red", active) end })
+    cy = cy + bh + gap
+  end
+  Kit.textWrapped("small", Strings("Import from a file or link, then manage, edit and export individual skins in My Skins."),
+    x, cy, w, PAL.muted, 3)
+  return cy + Kit.wrapHeight("small", Strings("Import from a file or link, then manage, edit and export individual skins in My Skins."), w, 3) - y
+end
+
 local function buildBugPanel(imp, x, y, w, availH, m)
   local SaveData = require("src.core.SaveData")
   local gap = m.gap
@@ -3017,9 +3157,13 @@ local function buildTextModal(imp, m, key, title, body, closeFn)
   local h = math.floor(math.min(m.H - 2 * m.pad, 460 * m.s))
   local px, py, pw, ph = modalPanel(m, w, h)
   local cy = py + pad
-  Kit.text("button", Kit.ellipsize("button", title, pw - 2 * pad),
+  local xW = math.max(Kit.tapMin(), math.floor(30 * m.s))
+  Kit.text("button", Kit.ellipsize("button", title,
+    pw - 2 * pad - xW - math.floor(8 * m.s)),
     px + pad, cy, PAL.heading)
-  cy = cy + Kit.textHeight("button") + math.floor(10 * m.s)
+  btn(imp, px + pw - pad - xW, cy, xW, xW, key .. "-x", "X",
+    { font = "small", action = closeFn })
+  cy = cy + math.max(Kit.textHeight("button"), xW) + math.floor(10 * m.s)
 
   local pagerH = math.max(Kit.tapMin(), math.floor(30 * m.s))
   local bodyH = (py + ph - pad) - cy - m.btnH - math.floor(10 * m.s)
@@ -4357,26 +4501,75 @@ local function syncTitle(imp, m, px, py, pw, pad)
   Kit.text("button", label, px + pad, py, PAL.heading)
   local bh = math.floor(15 * m.s)
   local bw = Kit.textWidth("micro", "BETA") + math.floor(14 * m.s)
-  Kit.tag(px + pad + Kit.textWidth("button", label) + math.floor(8 * m.s),
-    py + (Kit.textHeight("button") - bh) / 2, bw, bh, "BETA", PAL.yellow)
+  drawBetaTag(px + pad + Kit.textWidth("button", label) + math.floor(8 * m.s),
+    py + (Kit.textHeight("button") - bh) / 2, bw, bh)
   return py + Kit.textHeight("button") + math.floor(12 * m.s)
 end
 
-local function syncStatus(imp, m, x, y, w, eng)
+local function syncWidth(m, want)
+  return math.floor(math.min(want, m.W - 2 * m.pad))
+end
+
+local function syncFit(m, fixed, rows, gaps, texts)
+  local fit = { btnH = m.btnH, gap = math.floor(8 * m.s), lines = {} }
+  local avail = m.H - 2 * m.pad
+  texts = texts or {}
+  for i, blk in ipairs(texts) do fit.lines[i] = blk.max end
+  local function total()
+    local t = fixed + rows * fit.btnH + gaps * fit.gap
+    for i, blk in ipairs(texts) do
+      t = t + Kit.wrapHeight(blk.font, blk.str, blk.w, fit.lines[i])
+    end
+    return t
+  end
+  while total() > avail do
+    local worst, worstH = nil, 0
+    for i, blk in ipairs(texts) do
+      if fit.lines[i] > 1 then
+        local hgt = Kit.wrapHeight(blk.font, blk.str, blk.w, fit.lines[i])
+        if hgt > worstH then worst, worstH = i, hgt end
+      end
+    end
+    if not worst then break end
+    fit.lines[worst] = fit.lines[worst] - 1
+  end
+  if total() > avail and gaps > 0 then
+    fit.gap = math.max(math.max(2, math.floor(3 * m.s)),
+      fit.gap - math.ceil((total() - avail) / gaps))
+  end
+  if total() > avail and rows > 0 then
+    fit.btnH = math.max(Kit.tapMin(),
+      fit.btnH - math.ceil((total() - avail) / rows))
+  end
+  fit.over = total() - avail
+  fit.h = math.min(total(), avail)
+  return fit
+end
+
+local function syncStatus(imp, m, x, y, w, eng, fit)
+  local bh = (fit and fit.btnH) or m.btnH
+  local gap = (fit and fit.gap) or math.floor(8 * m.s)
   if eng:busy() then
-    Loader.inline(x, y, w, m.btnH, eng.status)
-    return m.btnH + math.floor(8 * m.s)
+    Loader.inline(x, y, w, bh, eng.status)
+    return bh + gap
   end
   Kit.text("small", Kit.ellipsize("small", eng.status or "", w), x, y,
     eng.phase == "error" and PAL.red or PAL.muted)
+  return Kit.textHeight("small") + gap + math.floor(2 * m.s)
+end
+
+local function syncReserve(m, eng)
+  if eng:busy() then return m.btnH + math.floor(8 * m.s) end
   return Kit.textHeight("small") + math.floor(10 * m.s)
 end
 
-local function syncRow(imp, m, x, y, w, key, label, opts)
+local function syncRow(imp, m, x, y, w, key, label, opts, fit)
   opts = opts or {}
   opts.font = "small"
-  btn(imp, x, y, w, m.btnH, key, label, opts)
-  return y + m.btnH + math.floor(8 * m.s)
+  local bh = (fit and fit.btnH) or m.btnH
+  local gap = (fit and fit.gap) or math.floor(8 * m.s)
+  btn(imp, x, y, w, bh, key, label, opts)
+  return y + bh + gap
 end
 
 function LauncherView.syncSideText(meta)
@@ -4408,91 +4601,99 @@ end
 local function buildSyncConflict(imp, m, eng)
   local row = eng.conflicts[1]
   local pad = math.floor(18 * m.s)
-  local w = math.floor(520 * m.s)
+  local w = syncWidth(m, math.floor(520 * m.s))
   local innerW = w - 2 * pad
   local lead = row.overlap
     and Strings("These saves were played at the same time.")
     or Strings("This save also changed on another device.")
-  local leadH = Kit.wrapHeight("small", lead, innerW, 2)
-  local sideH = Kit.textHeight("small") + math.floor(2 * m.s)
-    + Kit.wrapHeight("micro", "x", innerW, 2)
-  local h = pad + Kit.textHeight("button") + math.floor(12 * m.s) + leadH
-    + math.floor(10 * m.s) + 2 * (sideH + math.floor(10 * m.s))
-    + 4 * (m.btnH + math.floor(8 * m.s)) + pad
-  local px, py, pw = modalPanel(m, w, h)
+  local mine = LauncherView.syncSideText(row.localMeta)
+  local theirs = LauncherView.syncSideText(row.remoteMeta)
+  local fit = syncFit(m,
+    2 * pad + Kit.textHeight("button") + math.floor(22 * m.s)
+      + 2 * (Kit.textHeight("small") + math.floor(12 * m.s)),
+    4, 4, {
+      { font = "small", str = lead, w = innerW, max = 2 },
+      { font = "micro", str = mine, w = innerW, max = 2 },
+      { font = "micro", str = theirs, w = innerW, max = 2 },
+    })
+  local px, py, pw = modalPanel(m, w, fit.h)
   local cy = syncTitle(imp, m, px, py + pad, pw, pad)
-  cy = cy + Kit.textWrapped("small", lead, px + pad, cy, pw - 2 * pad,
-    PAL.detail, 2) + math.floor(10 * m.s)
+  cy = cy + Kit.textWrapped("small", lead, px + pad, cy, innerW,
+    PAL.detail, fit.lines[1]) + math.floor(10 * m.s)
 
-  local function side(title, meta)
+  local function side(title, text, lines)
     Kit.text("small", title, px + pad, cy, PAL.heading)
     cy = cy + Kit.textHeight("small") + math.floor(2 * m.s)
-    cy = cy + Kit.textWrapped("micro", LauncherView.syncSideText(meta),
-      px + pad, cy, pw - 2 * pad, PAL.muted, 2) + math.floor(10 * m.s)
+    cy = cy + Kit.textWrapped("micro", text, px + pad, cy, innerW,
+      PAL.muted, lines) + math.floor(10 * m.s)
   end
   side(Strings("This device") .. "  \194\183  " .. tostring(row.version or "?"),
-    row.localMeta)
-  side(Strings("Other device"), row.remoteMeta)
+    mine, fit.lines[2])
+  side(Strings("Other device"), theirs, fit.lines[3])
 
   local key = row.key
-  cy = syncRow(imp, m, px + pad, cy, pw - 2 * pad, "sync-keep-this",
+  cy = syncRow(imp, m, px + pad, cy, innerW, "sync-keep-this",
     Strings("Keep this device"), { kind = "primary",
-      action = function() imp:_syncResolve(key, "local") end })
-  cy = syncRow(imp, m, px + pad, cy, pw - 2 * pad, "sync-keep-other",
+      action = function() imp:_syncResolve(key, "local") end }, fit)
+  cy = syncRow(imp, m, px + pad, cy, innerW, "sync-keep-other",
     Strings("Keep the other device"), { kind = "accent",
-      action = function() imp:_syncResolve(key, "remote") end })
-  cy = syncRow(imp, m, px + pad, cy, pw - 2 * pad, "sync-keep-both",
+      action = function() imp:_syncResolve(key, "remote") end }, fit)
+  cy = syncRow(imp, m, px + pad, cy, innerW, "sync-keep-both",
     Strings("Keep both"), {
-      action = function() imp:_syncResolve(key, "both") end })
-  syncRow(imp, m, px + pad, cy, pw - 2 * pad, "sync-conflict-close",
-    Strings("Close"), { action = function() imp:_closeSync() end })
+      action = function() imp:_syncResolve(key, "both") end }, fit)
+  syncRow(imp, m, px + pad, cy, innerW, "sync-conflict-close",
+    Strings("Close"), { action = function() imp:_closeSync() end }, fit)
 end
 
 local function buildSyncLink(imp, m, eng)
   local mo = imp._syncModal
   local pad = math.floor(18 * m.s)
-  local w = math.floor(460 * m.s)
-  local fieldH = math.max(Kit.tapMin(), math.floor(36 * m.s))
+  local w = syncWidth(m, math.floor(460 * m.s))
+  local innerW = w - 2 * pad
   local hint = Strings("Enter the two codes the other device is showing.")
-  local hintH = Kit.wrapHeight("small", hint, w - 2 * pad, 2)
-  local h = pad + Kit.textHeight("button") + math.floor(12 * m.s) + hintH
-    + math.floor(10 * m.s) + 2 * (fieldH + math.floor(8 * m.s))
-    + Kit.textHeight("small") + math.floor(10 * m.s)
-    + 2 * (m.btnH + math.floor(8 * m.s)) + pad
-  local px, py, pw = modalPanel(m, w, h)
+  local fieldH = math.max(Kit.tapMin(), math.floor(36 * m.s))
+  local fit = syncFit(m,
+    2 * pad + Kit.textHeight("button") + math.floor(22 * m.s)
+      + 2 * (fieldH + math.floor(8 * m.s)) + syncReserve(m, eng),
+    2, 2, { { font = "small", str = hint, w = innerW, max = 2 } })
+  local px, py, pw = modalPanel(m, w, fit.h)
   local cy = syncTitle(imp, m, px, py + pad, pw, pad)
-  cy = cy + Kit.textWrapped("small", hint, px + pad, cy, pw - 2 * pad,
-    PAL.detail, 2) + math.floor(10 * m.s)
-  textField(imp, px + pad, cy, pw - 2 * pad, fieldH, "sync-code1",
+  cy = cy + Kit.textWrapped("small", hint, px + pad, cy, innerW,
+    PAL.detail, fit.lines[1]) + math.floor(10 * m.s)
+  textField(imp, px + pad, cy, innerW, fieldH, "sync-code1",
     mo.code1 or "", Strings("First code"), imp._syncFocus == "code1",
     function() imp:_syncFocusField("code1") end)
-  cy = cy + fieldH + math.floor(8 * m.s)
-  textField(imp, px + pad, cy, pw - 2 * pad, fieldH, "sync-code2",
+  cy = cy + fieldH + fit.gap
+  textField(imp, px + pad, cy, innerW, fieldH, "sync-code2",
     mo.code2 or "", Strings("Second code"), imp._syncFocus == "code2",
     function() imp:_syncFocusField("code2") end)
-  cy = cy + fieldH + math.floor(8 * m.s)
-  cy = cy + syncStatus(imp, m, px + pad, cy, pw - 2 * pad, eng)
-  cy = syncRow(imp, m, px + pad, cy, pw - 2 * pad, "sync-link-go",
+  cy = cy + fieldH + fit.gap
+  cy = cy + syncStatus(imp, m, px + pad, cy, innerW, eng, fit)
+  cy = syncRow(imp, m, px + pad, cy, innerW, "sync-link-go",
     Strings("Link this device"), { kind = "primary", enabled = not eng:busy(),
-      action = function() imp:_syncLink() end })
-  syncRow(imp, m, px + pad, cy, pw - 2 * pad, "sync-link-back",
-    Strings("Back"), { action = function() imp:_syncView("home") end })
+      action = function() imp:_syncLink() end }, fit)
+  syncRow(imp, m, px + pad, cy, innerW, "sync-link-back",
+    Strings("Back"), { action = function() imp:_syncView("home") end }, fit)
 end
 
 local function buildSyncMods(imp, m, eng)
   local mo = imp._syncModal
   local pad = math.floor(18 * m.s)
-  local w = math.floor(500 * m.s)
+  local w = syncWidth(m, math.floor(500 * m.s))
+  local innerW = w - 2 * pad
   local fieldH = math.max(Kit.tapMin(), math.floor(36 * m.s))
   local plan = eng.modPlan
   local rows = 4 + (plan and 1 or 0)
-  local h = pad + Kit.textHeight("button") + math.floor(12 * m.s)
-    + 3 * (Kit.textHeight("small") + math.floor(8 * m.s))
-    + fieldH + math.floor(8 * m.s)
-    + rows * (m.btnH + math.floor(8 * m.s)) + pad
-  local px, py, pw = modalPanel(m, w, h)
+  local codeH = eng.shareCode and (Kit.textHeight("small")
+    + Kit.textHeight("stat") + Kit.textHeight("micro")
+    + math.floor(18 * m.s)) or 0
+  local planH = plan and (Kit.textHeight("small") + math.floor(8 * m.s)) or 0
+  local fit = syncFit(m,
+    2 * pad + Kit.textHeight("button") + math.floor(12 * m.s) + codeH + planH
+      + fieldH + math.floor(8 * m.s) + syncReserve(m, eng),
+    rows, rows, {})
+  local px, py, pw = modalPanel(m, w, fit.h)
   local cy = syncTitle(imp, m, px, py + pad, pw, pad)
-  local innerW = pw - 2 * pad
 
   if eng.shareCode then
     Kit.text("small", Strings("Share this code:"), px + pad, cy, PAL.muted)
@@ -4504,17 +4705,23 @@ local function buildSyncMods(imp, m, eng)
       px + pad, cy, PAL.muted)
     cy = cy + Kit.textHeight("micro") + math.floor(10 * m.s)
   end
+  local withOptions = mo.withOptions ~= false
+  cy = syncRow(imp, m, px + pad, cy, innerW, "sync-share-options",
+    Strings("Include my mod options") .. "  \194\183  "
+      .. (withOptions and Strings("ON") or Strings("OFF")),
+    { kind = withOptions and "accent" or nil, enabled = not eng:busy(),
+      action = function() imp:_syncToggleShareOptions() end }, fit)
   cy = syncRow(imp, m, px + pad, cy, innerW, "sync-share-mods",
     Strings("Share mod list"), { kind = "accent", enabled = not eng:busy(),
-      action = function() imp:_syncShareMods() end })
+      action = function() imp:_syncShareMods() end }, fit)
 
   textField(imp, px + pad, cy, innerW, fieldH, "sync-share-code",
     mo.share or "", Strings("Paste a 6-character mod code"),
     imp._syncFocus == "share", function() imp:_syncFocusField("share") end)
-  cy = cy + fieldH + math.floor(8 * m.s)
+  cy = cy + fieldH + fit.gap
   cy = syncRow(imp, m, px + pad, cy, innerW, "sync-get-mods",
     Strings("Get mod list"), { kind = "accent", enabled = not eng:busy(),
-      action = function() imp:_syncGetShare() end })
+      action = function() imp:_syncGetShare() end }, fit)
 
   if plan then
     local line = Strings("%d mods, %d indexes to add",
@@ -4523,24 +4730,29 @@ local function buildSyncMods(imp, m, eng)
       line = line .. "  \194\183  " .. Strings("%d not in your indexes",
         #plan.missing)
     end
+    if #(plan.options or {}) > 0 then
+      line = line .. "  \194\183  " .. (plan.applyOptions
+        and Strings("options for %d mods", #plan.options)
+        or Strings("their options skipped"))
+    end
     Kit.text("small", Kit.ellipsize("small", line, innerW), px + pad, cy,
       PAL.detail)
     cy = cy + Kit.textHeight("small") + math.floor(8 * m.s)
     local prog = mo.progress
     if prog then
-      Loader.inline(px + pad, cy, innerW, m.btnH,
+      Loader.inline(px + pad, cy, innerW, fit.btnH,
         Strings("%d of %d", prog.done or 0, prog.total or 0))
-      cy = cy + m.btnH + math.floor(8 * m.s)
+      cy = cy + fit.btnH + fit.gap
     else
       cy = syncRow(imp, m, px + pad, cy, innerW, "sync-apply-mods",
         Strings("Apply these mods"), { kind = "primary",
           enabled = not eng:busy(),
-          action = function() imp:_syncApplyMods() end })
+          action = function() imp:_syncApplyMods() end }, fit)
     end
   end
-  cy = cy + syncStatus(imp, m, px + pad, cy, innerW, eng)
+  cy = cy + syncStatus(imp, m, px + pad, cy, innerW, eng, fit)
   syncRow(imp, m, px + pad, cy, innerW, "sync-mods-back", Strings("Back"),
-    { action = function() imp:_syncView("home") end })
+    { action = function() imp:_syncView("home") end }, fit)
 end
 
 function LauncherView.syncDeviceRows(eng, limit)
@@ -4562,29 +4774,35 @@ end
 
 local function buildSyncHome(imp, m, eng)
   local pad = math.floor(18 * m.s)
-  local w = math.floor(460 * m.s)
+  local w = syncWidth(m, math.floor(460 * m.s))
   local linked = eng:linked()
   local codes = eng.codes
   local body = linked
     and Strings("This device is linked. Saves sync when the launcher opens, a few seconds after each save, and every few minutes while the app is running.")
     or Strings(SYNC_HINT)
   local innerW = w - 2 * pad
-  local hintH = Kit.wrapHeight("small", body, innerW, 5)
   local codesH = codes
     and (Kit.textHeight("small") + math.floor(6 * m.s)
       + 2 * (Kit.textHeight("title") + math.floor(4 * m.s))
       + math.floor(8 * m.s)) or 0
   local devices = linked and LauncherView.syncDeviceRows(eng) or {}
+  local hidden, fit = 0, nil
+  repeat
     local devicesH = #devices > 0
       and (Kit.textHeight("small") + math.floor(6 * m.s)) or 0
-  local rows = (linked and 5 or 3) + #devices
-  local h = pad + Kit.textHeight("button") + math.floor(12 * m.s) + hintH
-    + math.floor(10 * m.s) + codesH + devicesH + m.btnH + math.floor(10 * m.s)
-    + rows * (m.btnH + math.floor(8 * m.s)) + pad
-  local px, py, pw = modalPanel(m, w, h)
+    fit = syncFit(m,
+      2 * pad + Kit.textHeight("button") + math.floor(22 * m.s) + codesH
+        + devicesH + syncReserve(m, eng),
+      (linked and 4 or 3) + #devices, (linked and 4 or 3) + #devices,
+      { { font = "small", str = body, w = innerW, max = 5 } })
+    if fit.over <= 0 or #devices == 0 then break end
+    table.remove(devices)
+    hidden = hidden + 1
+  until false
+  local px, py, pw = modalPanel(m, w, fit.h)
   local cy = syncTitle(imp, m, px, py + pad, pw, pad)
-  cy = cy + Kit.textWrapped("small", body, px + pad, cy, innerW, PAL.detail, 5)
-    + math.floor(10 * m.s)
+  cy = cy + Kit.textWrapped("small", body, px + pad, cy, innerW, PAL.detail,
+    fit.lines[1]) + math.floor(10 * m.s)
 
   if codes then
     Kit.text("small", Strings("Enter these on your other device:"), px + pad,
@@ -4595,23 +4813,24 @@ local function buildSyncHome(imp, m, eng)
     Kit.text("title", codes.code2, px + pad, cy, PAL.heading)
     cy = cy + Kit.textHeight("title") + math.floor(8 * m.s)
   end
-  cy = cy + syncStatus(imp, m, px + pad, cy, innerW, eng)
+  cy = cy + syncStatus(imp, m, px + pad, cy, innerW, eng, fit)
 
   if #devices > 0 then
-    Kit.text("small", Strings("Devices on this account:"), px + pad, cy,
-      PAL.muted)
+    Kit.text("small", hidden > 0
+      and Strings("Devices on this account (%d more)", hidden)
+      or Strings("Devices on this account:"), px + pad, cy, PAL.muted)
     cy = cy + Kit.textHeight("small") + math.floor(6 * m.s)
     for i, device in ipairs(devices) do
       local id = device.id
       if device.current then
         cy = syncRow(imp, m, px + pad, cy, innerW, "sync-device-" .. i,
           device.label .. "  \194\183  " .. Strings("this device"),
-          { enabled = false })
+          { enabled = false }, fit)
       else
         cy = syncRow(imp, m, px + pad, cy, innerW, "sync-device-" .. i,
           Strings("Unlink %s", device.label), { kind = "danger",
             enabled = not eng:busy(),
-            action = function() imp:_syncUnlinkDevice(id) end })
+            action = function() imp:_syncUnlinkDevice(id) end }, fit)
       end
     end
   end
@@ -4619,38 +4838,69 @@ local function buildSyncHome(imp, m, eng)
   if linked then
     cy = syncRow(imp, m, px + pad, cy, innerW, "sync-now", Strings("Sync now"),
       { kind = "primary", enabled = not eng:busy(),
-        action = function() imp:_syncNow() end })
+        action = function() imp:_syncNow() end }, fit)
     cy = syncRow(imp, m, px + pad, cy, innerW, "sync-mods",
       Strings("Share or get a mod list"), { kind = "accent",
-        action = function() imp:_syncView("mods") end })
+        action = function() imp:_syncView("mods") end }, fit)
     cy = syncRow(imp, m, px + pad, cy, innerW, "sync-unlink",
       Strings("Unlink this device"), { kind = "danger",
-        action = function() imp:_syncUnlink() end })
+        action = function() imp:_syncUnlink() end }, fit)
   else
     cy = syncRow(imp, m, px + pad, cy, innerW, "sync-create",
       Strings("Create sync account"), { kind = "primary",
         enabled = not eng:busy(),
-        action = function() imp:_syncCreate() end })
+        action = function() imp:_syncCreate() end }, fit)
     cy = syncRow(imp, m, px + pad, cy, innerW, "sync-link",
       Strings("Link this device"), { kind = "accent",
-        action = function() imp:_syncView("link") end })
+        action = function() imp:_syncView("link") end }, fit)
   end
   syncRow(imp, m, px + pad, cy, innerW, "sync-close", Strings("Close"),
-    { action = function() imp:_closeSync() end })
+    { action = function() imp:_closeSync() end }, fit)
+end
+
+local function buildSyncModOptions(imp, m, eng)
+  local plan = eng.modPlan
+  local ids = {}
+  for _, row in ipairs(plan.options or {}) do ids[#ids + 1] = row.id end
+  local pad = math.floor(18 * m.s)
+  local w = syncWidth(m, math.floor(480 * m.s))
+  local innerW = w - 2 * pad
+  local lead = Strings(
+    "This mod list also carries the options its owner set for %d mods. Import their options, or keep the ones you have?",
+    #ids)
+  local names = table.concat(ids, ", ")
+  local fit = syncFit(m,
+    2 * pad + Kit.textHeight("button") + math.floor(32 * m.s), 2, 2, {
+      { font = "small", str = lead, w = innerW, max = 4 },
+      { font = "micro", str = names, w = innerW, max = 3 },
+    })
+  local px, py, pw = modalPanel(m, w, fit.h)
+  local cy = syncTitle(imp, m, px, py + pad, pw, pad)
+  cy = cy + Kit.textWrapped("small", lead, px + pad, cy, innerW, PAL.detail,
+    fit.lines[1]) + math.floor(8 * m.s)
+  cy = cy + Kit.textWrapped("micro", names, px + pad, cy, innerW, PAL.muted,
+    fit.lines[2]) + math.floor(12 * m.s)
+  cy = syncRow(imp, m, px + pad, cy, innerW, "sync-options-import",
+    Strings("Import their options"), { kind = "primary",
+      action = function() imp:_syncAnswerModOptions(true) end }, fit)
+  syncRow(imp, m, px + pad, cy, innerW, "sync-options-skip",
+    Strings("Keep my options"), {
+      action = function() imp:_syncAnswerModOptions(false) end }, fit)
 end
 
 local function buildSyncUnavailable(imp, m, msg)
   local pad = math.floor(18 * m.s)
-  local w = math.floor(420 * m.s)
-  local h = pad + Kit.textHeight("button") + math.floor(12 * m.s)
-    + Kit.wrapHeight("small", msg, w - 2 * pad, 4) + math.floor(10 * m.s)
-    + m.btnH + pad
-  local px, py, pw = modalPanel(m, w, h)
+  local w = syncWidth(m, math.floor(420 * m.s))
+  local innerW = w - 2 * pad
+  local fit = syncFit(m,
+    2 * pad + Kit.textHeight("button") + math.floor(22 * m.s), 1, 0,
+    { { font = "small", str = msg, w = innerW, max = 4 } })
+  local px, py, pw = modalPanel(m, w, fit.h)
   local cy = syncTitle(imp, m, px, py + pad, pw, pad)
-  cy = cy + Kit.textWrapped("small", msg, px + pad, cy, pw - 2 * pad,
-    PAL.detail, 4) + math.floor(10 * m.s)
-  syncRow(imp, m, px + pad, cy, pw - 2 * pad, "sync-close",
-    Strings("Close"), { action = function() imp:_closeSync() end })
+  cy = cy + Kit.textWrapped("small", msg, px + pad, cy, innerW,
+    PAL.detail, fit.lines[1]) + math.floor(10 * m.s)
+  syncRow(imp, m, px + pad, cy, innerW, "sync-close",
+    Strings("Close"), { action = function() imp:_closeSync() end }, fit)
 end
 
 local function buildSyncModal(imp, m)
@@ -4669,6 +4919,12 @@ local function buildSyncModal(imp, m)
     buildSyncConflict(imp, m, eng)
     return
   end
+  local plan = eng.modPlan
+  if type(plan) == "table" and #(plan.options or {}) > 0
+      and plan.applyOptions == nil then
+    buildSyncModOptions(imp, m, eng)
+    return
+  end
   local view = imp._syncModal and imp._syncModal.view or "home"
   if view == "link" then
     buildSyncLink(imp, m, eng)
@@ -4959,6 +5215,7 @@ function LauncherView.draw(imp)
   -- whole stage draws shielded (no clicks, no hover, no focus ring) while
   -- one is up; buildModals lowers the shield for the modal's own controls.
   imp._modalUpNow = modalUp(imp)
+  if imp._modalUpNow then imp:_blurPanelFields() end
   Kit.blockClicks = imp._modalUpNow
 
   local step = Kit.scrollStep(m.s)

src/import/RomExtractorGen2.lua

@@ -5151,6 +5151,7 @@ function RomExtractorGen2:extractMenuGfx()
   }
   out.pack = pack
   out.pokedex = self:pokedexGfx()
+  out.billsPc = self:billsPcGfx()
   out.pokegear = self:pokegearGfx()
   out.trainerCard = self:trainerCardGfx()
   out.unownPuzzle = self:unownPuzzleGfx()
@@ -5258,80 +5259,213 @@ function RomExtractorGen2:extractMenuGfx()
   end
 
   -- Goldenrod Game Corner: Slot Machine graphics assets
+  local CacheFs = require("src.import.CacheFs")
+  local function packBytes(bytes)
+    local chars = {}
+    for i = 1, #bytes do chars[i] = string.char(bytes[i]) end
+    return table.concat(chars)
+  end
+  local function writeRaw(relative, bytes)
+    local ok, writeError = CacheFs.write(
+      "assets/generated/" .. relative, packBytes(bytes))
+    if not ok then
+      error("could not write " .. relative .. ": " .. tostring(writeError))
+    end
+  end
+
+  -- Canonical sheet sizes match the cart art the UI indexes (and pret's
+  -- gfx/slots + gfx/card_flip PNGs).  ROM LZ streams are those sheets after
+  -- Makefile gfx transforms; reverse what the decompressed bytes still carry.
+  local SLOTS1_W, SLOTS1_H = 16, 152
+  local SLOTS2_W, SLOTS2_H = 16, 256
+  local SLOTS3_W, SLOTS3_H = 24, 240
+  local CARD1_W, CARD1_H = 128, 32
+  local CARD2_W, CARD2_H = 24, 160
+  local CARD3_W, CARD3_H = 8, 56
+
+  local function pad2bpp(raw, width, height)
+    local need = width * height / 4
+    while #raw < need do raw[#raw + 1] = 0 end
+    while #raw > need do table.remove(raw) end
+    return raw
+  end
+
+  local function writeSheet(raw, width, height, relative, transparent)
+    self:write2bpp(pad2bpp(raw, width, height), width, height, relative,
+      transparent)
+  end
+
+  -- Slots3LZ is unique 8x16 OBJ columns (interleave + remove-duplicates +
+  -- remove-xflip).  Rebuild the 24x240 actor sheet the UI quads expect from
+  -- OAMData_SlotsGolem / Chansey* / Egg (data/sprite_anims/oam.asm), same
+  -- pattern as title-screen Ho-Oh frame composition above.
+  local function composeSlotsActors(raw)
+    local tileCount = math.floor(#raw / 16)
+    local tiles = {}
+    for index = 0, tileCount - 1 do
+      local one = {}
+      for b = 1, 16 do one[b] = raw[index * 16 + b] or 0 end
+      tiles[index] = ImageWriter.decode2bpp(one, 8, 8, true)
+    end
+    local sheet = ImageWriter.blank(SLOTS3_W, SLOTS3_H, 1, 1, 1, 0)
+    local function blit8x16(tileId, dx, dy, flipX)
+      local top, bot = tiles[tileId], tiles[tileId + 1]
+      if not (top and bot) then return end
+      ImageWriter.blit(sheet, top, dx, dy, 0, 0, 8, 8, flipX)
+      ImageWriter.blit(sheet, bot, dx, dy + 8, 0, 0, 8, 8, flipX)
+    end
+    local function blitPose(poseY, base, entries)
+      for _, e in ipairs(entries) do
+        blit8x16(base + e.t, (e.x + 2) * 8, poseY + (e.y + 2) * 8, e.xf)
+      end
+    end
+    local golem = {
+      { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+      { x = 0, y = -2, t = 0x00, xf = true },
+      { x = -2, y = 0, t = 0x04 }, { x = -1, y = 0, t = 0x06 },
+      { x = 0, y = 0, t = 0x04, xf = true },
+    }
+    local chansey = {
+      {
+        { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+        { x = 0, y = -2, t = 0x04 },
+        { x = -2, y = 0, t = 0x06 }, { x = -1, y = 0, t = 0x08 },
+        { x = 0, y = 0, t = 0x0a },
+      },
+      {
+        { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+        { x = 0, y = -2, t = 0x04 },
+        { x = -2, y = 0, t = 0x0c }, { x = -1, y = 0, t = 0x0e },
+        { x = 0, y = 0, t = 0x10 },
+      },
+      {
+        { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+        { x = 0, y = -2, t = 0x04 },
+        { x = -2, y = 0, t = 0x12 }, { x = -1, y = 0, t = 0x14 },
+        { x = 0, y = 0, t = 0x16 },
+      },
+      {
+        { x = -2, y = -2, t = 0x00 }, { x = -1, y = -2, t = 0x02 },
+        { x = 0, y = -2, t = 0x04 },
+        { x = -2, y = 0, t = 0x18 }, { x = -1, y = 0, t = 0x1a },
+        { x = 0, y = 0, t = 0x1c },
+      },
+      {
+        { x = -2, y = -2, t = 0x1e }, { x = -1, y = -2, t = 0x20 },
+        { x = 0, y = -2, t = 0x22 },
+        { x = -2, y = 0, t = 0x24 }, { x = -1, y = 0, t = 0x26 },
+        { x = 0, y = 0, t = 0x28 },
+      },
+    }
+    blitPose(0, 0x00, golem)
+    blitPose(32, 0x08, golem)
+    for index, frame in ipairs(chansey) do
+      blitPose(32 + index * 32, 0x10, frame)
+    end
+    blit8x16(0x3a, 0, 224, false)
+    return sheet
+  end
+
+  -- card_flip_2.2bpp uses --remove-whitespace: blank tiles in column 2 of the
+  -- 3-wide header strip (indices 2,5,...,23) are dropped from the ROM stream.
+  -- Re-insert them so HEADER_TILE_MAP / MON_ANCHORS (pret sheet indices) work.
+  local function expandCardFlip2(compact)
+    local need = CARD2_W * CARD2_H / 4
+    local out = {}
+    for i = 1, need do out[i] = 0 end
+    local whitespace = {
+      [2] = true, [5] = true, [8] = true, [11] = true,
+      [14] = true, [17] = true, [20] = true, [23] = true,
+    }
+    local src = 0
+    for tile = 0, 59 do
+      if not whitespace[tile] then
+        for b = 1, 16 do
+          out[tile * 16 + b] = compact[src * 16 + b] or 0
+        end
+        src = src + 1
+      end
+    end
+    return out
+  end
+
+  local slots = nil
   if self.symbols["Slots1LZ"] then
+    -- --trim-whitespace drops the final empty tile (37 of 38).
     local raw1 = self:decompressLz3Symbol("Slots1LZ")
-    self:write2bpp(raw1, 16, #raw1 / 4, "slots/gold_slots_1.png")
+    writeSheet(raw1, SLOTS1_W, SLOTS1_H, "slots/gold_slots_1.png")
+    slots = slots or {}
+    slots.sheet1 = "assets/generated/slots/gold_slots_1.png"
   end
   if self.symbols["Slots2LZ"] then
-    local raw2 = self:decompressLz3Symbol("Slots2LZ")
-    -- In Pokemon Gold ROM, Seven symbol (first 4 tiles = 64 bytes) has inverted bit polarity
+    local raw2 = ImageWriter.deinterleave(
+      self:decompressLz3Symbol("Slots2LZ"), SLOTS2_W)
+    -- Commercial Gold stores the Seven symbol with inverted bit polarity.
     for i = 1, math.min(64, #raw2) do
       raw2[i] = bit.band(bit.bnot(raw2[i]), 0xFF)
     end
-    self:write2bpp(raw2, 16, #raw2 / 4, "slots/gold_slots_2.png")
+    writeSheet(raw2, SLOTS2_W, SLOTS2_H, "slots/gold_slots_2.png")
+    slots = slots or {}
+    slots.sheet2 = "assets/generated/slots/gold_slots_2.png"
   end
   if self.symbols["Slots3LZ"] then
     local raw3 = self:decompressLz3Symbol("Slots3LZ")
-    self:write2bpp(raw3, 24, #raw3 / 6, "slots/gold_slots_3.png", true)
-    -- Slots3LZ is a 24px-wide (3 tiles), 240px-tall (30 tiles) sprite sheet containing:
-    --   Y=0:   Golem 1 (Standing, 24x32)
-    --   Y=32:  Golem 2 (Ball, 24x32)
-    --   Y=64:  Chansey 1 (Standing / Step 1, 24x32)
-    --   Y=96:  Chansey 2 (Step 2, 24x32)
-    --   Y=128: Chansey 3 (Step 3, 24x32)
-    --   Y=160: Chansey 4 (Arm raised / Step 4, 24x32)
-    --   Y=192: Chansey 5 (Egg Drop pose, 24x32)
-    --   Y=224: Egg (8x16 at X=0)
-    self:write2bpp(raw3, 24, #raw3 / 6, "slots/gold_slots_actors.png", true)
+    local actors = composeSlotsActors(raw3)
+    self:save(actors, "slots/gold_slots_3.png")
+    self:save(actors, "slots/gold_slots_actors.png")
+    slots = slots or {}
+    slots.sheet3 = "assets/generated/slots/gold_slots_3.png"
   end
   if self.symbols["SlotsTilemap"] then
     local symbol = self:symbol("SlotsTilemap")
     local tm = self.rom:bytes(symbol.bank, symbol.address, 20 * 12)
-    self:save(tm, "slots/gold_slots.tilemap")
+    writeRaw("slots/gold_slots.tilemap", tm)
+    slots = slots or {}
+    slots.tilemap = "assets/generated/slots/gold_slots.tilemap"
   end
+  if slots then out.slots = slots end
 
   -- Goldenrod Game Corner: Card Flip graphics assets
+  local cardFlip = nil
   if self.symbols["CardFlipLZ01"] then
+    -- --trim-whitespace: 62 of 64 tiles in the ROM stream.
     local raw1 = self:decompressLz3Symbol("CardFlipLZ01")
-    self:write2bpp(raw1, 128, #raw1 / 32, "card_flip/card_flip_1.png")
+    writeSheet(raw1, CARD1_W, CARD1_H, "card_flip/card_flip_1.png")
+    cardFlip = cardFlip or {}
+    cardFlip.sheet1 = "assets/generated/card_flip/card_flip_1.png"
   end
   if self.symbols["CardFlipLZ02"] then
-    local raw2 = self:decompressLz3Symbol("CardFlipLZ02")
-    self:write2bpp(raw2, 24, #raw2 / 6, "card_flip/card_flip_2.png")
+    local raw2 = expandCardFlip2(self:decompressLz3Symbol("CardFlipLZ02"))
+    writeSheet(raw2, CARD2_W, CARD2_H, "card_flip/card_flip_2.png")
+    cardFlip = cardFlip or {}
+    cardFlip.sheet2 = "assets/generated/card_flip/card_flip_2.png"
   end
   if self.symbols["CardFlipLZ03"] then
     local raw3 = self:decompressLz3Symbol("CardFlipLZ03")
-    self:write2bpp(raw3, 8, #raw3 / 2, "card_flip/card_flip_3.png")
+    writeSheet(raw3, CARD3_W, CARD3_H, "card_flip/card_flip_3.png")
+    cardFlip = cardFlip or {}
+    cardFlip.sheet3 = "assets/generated/card_flip/card_flip_3.png"
   end
   if self.symbols["CardFlipOnButtonGFX"] then
     local symbol = self:symbol("CardFlipOnButtonGFX")
     self:write2bpp(self.rom:bytes(symbol.bank, symbol.address, 16), 8, 8, "card_flip/on.png")
+    cardFlip = cardFlip or {}
+    cardFlip.on = "assets/generated/card_flip/on.png"
   end
   if self.symbols["CardFlipOffButtonGFX"] then
     local symbol = self:symbol("CardFlipOffButtonGFX")
     self:write2bpp(self.rom:bytes(symbol.bank, symbol.address, 16), 8, 8, "card_flip/off.png")
+    cardFlip = cardFlip or {}
+    cardFlip.off = "assets/generated/card_flip/off.png"
   end
   if self.symbols["CardFlipTilemap"] then
     local symbol = self:symbol("CardFlipTilemap")
     local tm = self.rom:bytes(symbol.bank, symbol.address, 11 * 12)
-    self:save(tm, "card_flip/card_flip.tilemap")
+    writeRaw("card_flip/card_flip.tilemap", tm)
+    cardFlip = cardFlip or {}
+    cardFlip.tilemap = "assets/generated/card_flip/card_flip.tilemap"
   end
-
-  out.slots = {
-    sheet1 = "assets/generated/slots/gold_slots_1.png",
-    sheet2 = "assets/generated/slots/gold_slots_2.png",
-    sheet3 = "assets/generated/slots/gold_slots_3.png",
-    tilemap = "assets/generated/slots/gold_slots.tilemap",
-  }
-
-  out.cardFlip = {
-    sheet1 = "assets/generated/card_flip/card_flip_1.png",
-    sheet2 = "assets/generated/card_flip/card_flip_2.png",
-    sheet3 = "assets/generated/card_flip/card_flip_3.png",
-    on = "assets/generated/card_flip/on.png",
-    off = "assets/generated/card_flip/off.png",
-    tilemap = "assets/generated/card_flip/card_flip.tilemap",
-  }
+  if cardFlip then out.cardFlip = cardFlip end
 
   self:write("menu_gfx", out)
   self:tick("Menu graphics", 1, 1)
@@ -5564,6 +5698,25 @@ function RomExtractorGen2:pokedexGfx()
   return dex
 end
 
+-- BillsPC_InitGFX's four tiles at vTiles2 $5c
+-- (engine/pokemon/bills_pc.asm:2170-2173)
+function RomExtractorGen2:billsPcGfx()
+  if not self.symbols["PCMailGFX"] then return nil end
+  local pc = {}
+  local gfx = self:symbol("PCMailGFX")
+  self:write2bpp(self.rom:bytes(gfx.bank, gfx.address, 4 * 16),
+    32, 8, "pc/mail_item.png")
+  pc.icons = "assets/generated/pc/mail_item.png"
+  pc.firstTile = 0x5c
+  pc.palette = self:predefPal(PREDEFPAL_POKEDEX)
+  -- gfx/pc/orange.pal
+  if self.symbols["BillsPCOrangePalette"] then
+    local orange = self:symbol("BillsPCOrangePalette")
+    pc.orangePalette = self:colors(orange.bank, orange.address, 4)
+  end
+  return pc
+end
+
 -- Reads a `tile, count` RLE tilemap (Pokegear_LoadTilemapRLE).  The routine's
 -- own comment says "repeat count, tile ID" and has it backwards: it loads b
 -- from the first byte, c from the second, and writes `b` c times.  $ff ends

src/import/RomImporter.lua

@@ -140,6 +140,14 @@ local VERSION_REQUIRED_FILES_OVERRIDE = {
     -- before the four ball tiles were extracted (#1502).
     "assets/generated/battle/hud/balls.png",
     "assets/generated/audio/programs.bin",
+    -- Goldenrod Game Corner reel + board art (#1581).  menu_gfx.lua used to
+    -- advertise these paths even when Slots*LZ / CardFlip* were absent from
+    -- the manifest, so a cache that never wrote the PNGs still looked
+    -- complete and SlotMachine crashed on its labelled-cell fallback.
+    "assets/generated/slots/gold_slots_1.png",
+    "assets/generated/card_flip/card_flip_1.png",
+    -- PCMailGFX (engine/pokemon/bills_pc.asm:2170-2173)
+    "assets/generated/pc/mail_item.png",
   },
 }
 -- Same Gen 2 extract, so a Silver cache is complete when the same files exist.
@@ -382,6 +390,142 @@ local function externalFileSize(path)
   return size
 end
 
+local function openImportSource(path)
+  -- Desktop picker paths live outside LÖVE's virtual filesystem. Prefer the
+  -- native file handle so a 1.46 GiB disc is never copied to a temp file or
+  -- read into one Lua string before validation.
+  local native = io.open(path, "rb")
+  if native then
+    local size, sizeErr = native:seek("end")
+    if size == nil or size == false then
+      native:close()
+      return nil, sizeErr or "could not determine source file size"
+    end
+    local reset, resetErr = native:seek("set", 0)
+    if reset == nil or reset == false then
+      native:close()
+      return nil, resetErr or "could not rewind source file"
+    end
+    return {
+      size = size,
+      read = function(_, n) return native:read(n) end,
+      close = function() native:close() end,
+    }
+  end
+  if love and love.filesystem and love.filesystem.newFile then
+    local file, makeErr = love.filesystem.newFile(path)
+    if not file then return nil, makeErr or "could not open source file" end
+    local ok, openErr = file:open("r")
+    if not ok then return nil, openErr or "could not open source file" end
+    local size = file.getSize and file:getSize() or nil
+    return {
+      size = size,
+      read = function(_, n) return file:read(n) end,
+      close = function() file:close() end,
+    }
+  end
+  return nil, "streaming source access is unavailable"
+end
+local function streamRequiredImport(manifest, importId, source)
+  local RequiredImports = require("src.mods.RequiredImports")
+  local spec = RequiredImports.spec(manifest, importId)
+  if not spec then return nil, "Import declaration was not found." end
+  if spec.format == "n64" then
+    return nil, "streaming canonicalization is unavailable for N64 imports"
+  end
+  local input, openErr = openImportSource(source)
+  if not input then return nil, openErr end
+  local sizeErr = RequiredImports.sizeError(spec, input.size, false)
+  if sizeErr then input:close(); return nil, sizeErr end
+
+  local CacheFs = require("src.import.CacheFs")
+  local destination = RequiredImports.path(manifest, spec)
+  local savedPrefix = CacheFs.prefix
+  local output
+  local inputClosed, outputClosed = false, false
+
+  local function closeInput()
+    if inputClosed then return end
+    inputClosed = true
+    pcall(function() input:close() end)
+  end
+
+  local function closeOutput()
+    if outputClosed or not output then return end
+    outputClosed = true
+    pcall(function() output:close() end)
+  end
+
+  local resultOk, resultDetail
+  CacheFs.prefix = ""
+  local ran, thrown = xpcall(function()
+    CacheFs.remove(RequiredImports.receiptPath(manifest, spec))
+    CacheFs.remove(destination)
+    local makeErr
+    output, makeErr = CacheFs.openWrite(destination)
+    if not output then
+      resultDetail = makeErr or "could not create imported file"
+      return
+    end
+
+    local MD5 = require("src.mods.StreamMD5")
+    local md5 = MD5.new()
+    local total, chunkBytes = 0, 4 * 1024 * 1024
+    while true do
+      local chunk = input:read(chunkBytes)
+      if not chunk or #chunk == 0 then break end
+      md5:update(chunk)
+      local wrote, writeErr = output:write(chunk)
+      if wrote == false or wrote == nil then
+        resultDetail = "could not copy import: "
+.. tostring(writeErr or "write failed")
+        return
+      end
+      total = total + #chunk
+      if #chunk < chunkBytes then break end
+    end
+
+    closeInput()
+    closeOutput()
+    if input.size and total ~= input.size then
+      resultDetail = ("source read ended early (expected %d bytes, copied %d)")
+        :format(input.size, total)
+      return
+    end
+    local storedSizeErr = RequiredImports.sizeError(spec, total, true)
+    if storedSizeErr then resultDetail = storedSizeErr; return end
+    local digest = md5:final()
+
+    -- acceptStoredDigest uses the normal engine path/receipt rules, so
+    -- restore the caller's prefix before handing control to it.
+    CacheFs.prefix = savedPrefix
+    local accepted, detail = RequiredImports.acceptStoredDigest(
+      manifest, importId, digest, love.filesystem)
+    if not accepted then resultDetail = detail; return end
+    resultOk, resultDetail = true, detail
+  end, function(err)
+    if debug and debug.traceback then
+      return debug.traceback(tostring(err), 2)
+    end
+    return tostring(err)
+  end)
+
+  -- finally: resource handles and the process-global CacheFs prefix must
+  -- be restored even when a read/hash/write helper raises a Lua error.
+  closeInput()
+  closeOutput()
+  CacheFs.prefix = ""
+  if not ran or not resultOk then
+    pcall(function() CacheFs.remove(destination) end)
+  end
+  CacheFs.prefix = savedPrefix
+
+  if not ran then
+    return nil, "could not copy import: " .. tostring(thrown)
+  end
+  if not resultOk then return nil, resultDetail end
+  return true, resultDetail
+end
 local function readDroppedFile(file)
   local ok, openError = file:open("r")
   if not ok then return nil, openError end
@@ -942,13 +1086,19 @@ end
 -- naive "first ROM wins" scan would re-import Red when the player tries to
 -- add Blue (issue #167).  Yellow and Gold carts are typically .gbc (Gold is
 -- 2 MiB).
-local function findPendingRom(ready)
+-- `wanted` narrows the scan to one version.  A Choose names the cart it is
+-- for, so without it several dumps sitting in the save directory answered in
+-- listing order and the selection was dropped: picking Red imported Blue
+-- (#1274).  The callers that are not a Choose, the Android USB-drop scans,
+-- pass nothing and still take the first pending cart of any version.
+local function findPendingRom(ready, wanted)
   for _, name in ipairs(love.filesystem.getDirectoryItems("")) do
     if name:lower():match("%.gbc?$") and love.filesystem.getInfo(name, "file") then
       local data = love.filesystem.read(name)
       if type(data) == "string" and isAcceptedRomSize(#data) then
         local version = GameVersion.forSha1(sha1(data))
-        if version and not ready[version] then
+        if version and not ready[version]
+            and (wanted == nil or version == wanted) then
           return name, data
         end
       end
@@ -1228,11 +1378,13 @@ local function chooseRequiredFile()
       "$d=New-Object System.Windows.Forms.OpenFileDialog;",
       "$d.Title='" .. prompt .. "';",
       "$d.Filter='All files (*.*)|*.*';",
+      -- Required imports can be multi-gigabyte optical-disc images. Do NOT
+      -- stage them through %TEMP%: that doubles free-space requirements and a
+      -- failed Copy-Item can leave a plausible-looking truncated temp file.
+      -- Stream the selected source directly into the mod-owned destination.
       "if($d.ShowDialog() -eq 'OK'){",
-      "$t=Join-Path $env:TEMP 'pokeport_required_import.bin';",
-      "Copy-Item -LiteralPath $d.FileName -Destination $t -Force;",
       "[Console]::OutputEncoding=[Text.Encoding]::UTF8;",
-      "[Console]::Write($t)}",
+      "[Console]::Write($d.FileName)}",
     })
     return commandOutput(
       'powershell -NoProfile -STA -Command "' .. script .. '"')
@@ -2072,8 +2224,13 @@ function RomImporter:_importRequiredSource(modId, importId, source, confirmed)
     return nil
   end
   local RequiredImports = require("src.mods.RequiredImports")
+  -- A desktop picker returns a host path. Ask the host file handle first;
+  -- love.filesystem.getInfo is only authoritative for virtual/save paths.
+  local size = externalFileSize(source)
+  if not size then
     local info = love.filesystem.getInfo(source, "file")
-  local size = info and info.size or externalFileSize(source)
+    size = info and info.size or nil
+  end
   local sizeErr = RequiredImports.sizeError(spec, size, false)
   if sizeErr then
     requiredImportNotice(self, modId, importId, sizeErr)
@@ -2096,6 +2253,20 @@ function RomImporter:_importRequiredSource(modId, importId, source, confirmed)
     }
     return nil
   end
+  if type(size) == "number" and size > RequiredImports.LARGE_WARN_BYTES
+      and spec.format ~= "n64" then
+    local ok, result = streamRequiredImport(manifest, importId, source)
+    if ok then
+      self.requiredImportNotice = nil
+      self.modNotice = { ok = true, text = "Imported " .. tostring(importId)
+        .. " for " .. tostring(manifest.name or manifest.id) .. "." }
+      self:_refreshMods()
+      return true
+    end
+    requiredImportNotice(self, modId, importId, result)
+    self.modNotice = nil
+    return nil
+  end
   local data = love.filesystem.read(source)
   if not data then data = readExternalPath(source) end
   if not data then
@@ -2410,8 +2581,9 @@ function RomImporter:choose(version)
   if self.android then
     -- Prefer a not-yet-imported .gb/.gbc already in the save dir (USB copy, or
     -- a fresh SAF pick).  Never reuse an already-imported cart's file -- that
-    -- was the #167 failure mode (second Choose just re-extracted Red).
-    local name, data = findPendingRom(self.ready)
+    -- was the #167 failure mode (second Choose just re-extracted Red).  This
+    -- is a Choose, so it takes the cart that was asked for and nothing else.
+    local name, data = findPendingRom(self.ready, self.chooseVersion)
     if name then
       self:startData(data, name)
     elseif consumePickedRomError(self) then
@@ -2439,8 +2611,10 @@ function RomImporter:choose(version)
   -- Handheld Linux (Anbernic stock OS / PortMaster) rarely has zenity or
   -- kdialog.  Fall back to the same "drop a .gb/.gbc next to the game" scan
   -- used on Android, which works when the game is launched as an unpacked
-  -- directory (see build-rg34xxsp.sh).
-  local name, data = findPendingRom(self.ready)
+  -- directory (see build-rg34xxsp.sh).  Narrowed to the chosen version: with
+  -- four dumps in the folder the unnarrowed scan answered in listing order,
+  -- so Choose Red imported and decoded Blue (#1274).
+  local name, data = findPendingRom(self.ready, self.chooseVersion)
   if name then
     self:startData(data, name)
     return
@@ -2848,6 +3022,7 @@ function RomImporter:_updatePadCursor(dt)
     local overY = 0
     if ny > oy + h then overY = ny - (oy + h)
     elseif ny < oy then overY = ny - oy end
+    if math.abs(ay) > PAD_DEAD and not self._padStickCentered then overY = 0 end
     if overY ~= 0 and self._flex then
       require("src.import.LauncherView").wheelmoved(self, 0, -overY / 48)
     end
@@ -2907,7 +3082,11 @@ end
 function RomImporter:gamepadaxis(_, axis, value)
   if axis == "leftx" or axis == "lefty" or axis == "righty" then
     self._padAxis[axis] = value
-    if math.abs(value) > PAD_DEAD then self:_activatePadCursor() end
+    if math.abs(value) > PAD_DEAD then
+      self:_activatePadCursor()
+    elseif axis == "lefty" then
+      self._padStickCentered = true
+    end
   end
 end
 
@@ -2916,18 +3095,21 @@ end
 -- fire the virtual cursor's click twice off one A press (#620).
 function RomImporter:joystickpressed(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   local padButton = GamepadMap.mapRawToGamepadButton(button)
   if padButton then self:gamepadpressed(joystick, padButton) end
 end
 
 function RomImporter:joystickreleased(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   local padButton = GamepadMap.mapRawToGamepadButton(button)
   if padButton then self:gamepadreleased(joystick, padButton) end
 end
 
 function RomImporter:joystickaxis(joystick, axis, value)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   if axis == 1 then
     self:gamepadaxis(joystick, "leftx", value)
   elseif axis == 2 then
@@ -2937,6 +3119,7 @@ end
 
 function RomImporter:joystickhat(joystick, hat, direction)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   for _, dir in ipairs(self._rawHatDirs[hat] or {}) do
     self._padDir[dir] = nil
   end
@@ -3182,6 +3365,10 @@ function RomImporter:_ensureSkins(force)
       format = skin and skin.format or nil,
       pages = skin and #skin.pages or 0,
       controls = controls,
+      -- The launcher owns the visual skin picker, so retain the already
+      -- loaded first-page bezel for its preview card instead of decoding it
+      -- again every frame.
+      preview = page and page.image or nil,
       screen = page ~= nil
         and (page.viewport ~= nil or page.screenFit == "remainder"),
       ok = skin ~= nil,
@@ -3194,7 +3381,7 @@ end
 function RomImporter:_activeSkin()
   local opts = require("src.core.SaveData").loadOptions()
   local tc = type(opts.touchControls) == "table" and opts.touchControls or {}
-  return tc.skin
+  return tc.enabled == false and nil or tc.skin
 end
 
 function RomImporter:_useSkin(id)
@@ -3211,6 +3398,16 @@ function RomImporter:_useSkin(id)
   }
 end
 
+function RomImporter:_disableSkins()
+  local SaveData = require("src.core.SaveData")
+  local opts = SaveData.loadOptions()
+  local tc = type(opts.touchControls) == "table" and opts.touchControls or {}
+  tc.enabled, tc.skin = false, nil
+  opts.touchControls = tc
+  SaveData.saveOptions(opts)
+  self._skinNotice = { ok = true, text = "Skins are off. Mobile will use the built-in pad when needed." }
+end
+
 function RomImporter:_installSkinZip(source)
   if self.workState == "working" then return end
   self.tab = "skins"
@@ -3478,7 +3675,7 @@ end
 function RomImporter:_openSync()
   self:_syncEngine()
   self._syncModal = self._syncModal
-    or { view = "home", code1 = "", code2 = "", share = "" }
+    or { view = "home", code1 = "", code2 = "", share = "", withOptions = true }
   self._syncFocus = nil
   self:_disarmTextInput()
 end
@@ -3563,9 +3760,22 @@ function RomImporter:_syncUnlinkDevice(deviceId)
 end
 
 function RomImporter:_syncShareMods()
-  local eng = self:_syncEngine()
+  local eng, mo = self:_syncEngine(), self._syncModal
   if not eng then return false end
-  return eng:shareMods()
+  return eng:shareMods(mo and mo.withOptions ~= false)
+end
+
+function RomImporter:_syncToggleShareOptions()
+  local mo = self._syncModal
+  if not mo then return false end
+  mo.withOptions = not (mo.withOptions ~= false)
+  return mo.withOptions
+end
+
+function RomImporter:_syncAnswerModOptions(importThem)
+  local eng = self:_syncEngine()
+  if not eng or type(eng.answerModOptions) ~= "function" then return false end
+  return eng:answerModOptions(importThem)
 end
 
 function RomImporter:_syncGetShare()
@@ -3984,6 +4194,18 @@ function RomImporter:_disarmTextInput()
   end
 end
 
+function RomImporter:_blurPanelFields()
+  if not (self._findSearchFocus or self._skinUrlFocus) then return end
+  if self._indexPrompt or self._rename or self._settingsText
+      or self._profileSavePrompt or self._profileRenamePrompt
+      or (self._syncModal and self._syncFocus) then
+    return
+  end
+  self._findSearchFocus = false
+  self._skinUrlFocus = false
+  self:_disarmTextInput()
+end
+
 function RomImporter:_beginRename(version, id)
   local label
   for _, slot in ipairs(self.slots[version] or {}) do
@@ -4114,7 +4336,6 @@ function RomImporter:_refreshMods()
     end
     self.mods = kept
   end
-  self:_syncModUpdateInfo(false)
 end
 
 -- Point the MODS panel at one game (or nil for all of them) and relist, so
@@ -4128,15 +4349,12 @@ function RomImporter:_ensureMods()
   if not self.mods then self:_refreshMods() end
 end
 
--- Resolve cached (or freshly fetched) GitHub status for every mod that
--- declares a github field. force=true bypasses the 6h cache on every repo.
--- Results live on self.modUpdateInfo[id] = { status, latest, best, releases }.
--- ASYNC (was synchronous).  This runs on every _refreshMods -- boot, and any
--- toggle or install -- and used to make one blocking curl call per mod with a
--- github field, in a loop, on the render thread.  A handful of mods was a
--- multi-second freeze of the whole launcher.  Now each mod gets a handle and
--- they resolve together across later frames; a mod whose cache is still fresh
--- resolves on the first pump with no network at all.
+-- Resolve GitHub status for every installed mod that declares a github field.
+-- This is deliberately opt-in: only the explicit "Check for updates" action
+-- calls it. Opening, scrolling, toggling, or relisting the MODS tab must not
+-- create a burst of release work behind the list. force=true bypasses the 6h
+-- cache on every repo. Results live on self.modUpdateInfo[id] = {
+-- status, latest, best, releases } and resolve asynchronously across frames.
 function RomImporter:_syncModUpdateInfo(force)
   local ModUpdate = require("src.mods.ModUpdate")
   self.modUpdateInfo = self.modUpdateInfo or {}

src/inventory/Bag.lua

@@ -10,13 +10,14 @@
 local Bag = {}
 
 -- MAX_ITEMS / MAX_BALLS / MAX_KEY_ITEMS, and the TM/HM pocket holds one of
--- every TM plus the seven HMs (NUM_TMS + NUM_HMS).  A `mods` bagSize override
+-- every TM plus the seven HMs (NUM_TMS + NUM_HMS -- ram/wram.asm:2421 is
+-- `wTMsHMs:: ds NUM_TMS + NUM_HMS`, 57 bytes).  A `mods` bagSize override
 -- replaces the ITEM pocket only, the way the Gen 1 single-bag config did.
 local POCKET_CAPACITY = {
   ITEM = 20,
   BALL = 12,
   KEY_ITEM = 25,
-  TM_HM = 64,
+  TM_HM = 57,
 }
 local DEFAULT_CAPACITY = 20
 

src/mods/Gen2Compat.lua

@@ -808,6 +808,33 @@ local function buildOverworld()
   local Movement = rawRequire("src.script.gen2.Movement")
   local HiddenItems = rawRequire("src.world.gen2.HiddenItems")
   local Bike = rawRequire("src.world.gen2.Bike")
+  local FieldMoves = rawRequire("src.world.gen2.FieldMoves")
+
+  -- home/map.asm:1869
+  local function stepAllowed(world, entity, dir, cx, cy)
+    local d = Map2.DELTA[dir]
+    if not (world.map and d and entity) then return true end
+    cx, cy = cx or entity.cellX, cy or entity.cellY
+    if not (cx and cy) then return true end
+    if not Permissions.stepPermitted(
+         function(px, py) return world:cellCollisionAcross(world.map, px, py) end,
+         cx, cy, dir) then
+      return false
+    end
+    local map = world.map
+    if entity == world.player and FieldMoves.isSurfing(world.playerState) then
+      map = world:surfMap(world.map)
+    end
+    local tx, ty = cx + d[1], cy + d[2]
+    if not map:inBounds(tx, ty) or not map:isWalkable(tx, ty) then return false end
+    for _, e in ipairs(world.entities or {}) do
+      if e ~= entity and not e.passable then
+        if e.cellX == tx and e.cellY == ty then return false end
+        if e.moving and e.targetX == tx and e.targetY == ty then return false end
+      end
+    end
+    return true
+  end
 
   local api = nil
   -- one WorldAPI instance, so queueScript reuses the five-verb allow list
@@ -1011,20 +1038,33 @@ local function buildOverworld()
 
   -- Gold has ONE movement slot; a second concurrent call is refused with a
   -- reason rather than dropped (src/world/gen2/WorldAPI.lua:171's recipe).
-  function ow.scriptMove(entity, dir, tiles, onDone)
+  function ow.scriptMove(entity, dir, tiles, onDone, opts)
     local world = w("scriptMove")
     if not world then return nil, "no overworld" end
     if world.moveState then return nil, "a movement is already running" end
     local step = Movement.stepByte(dir)
     if not step then return nil, "unknown direction: " .. tostring(dir) end
-    local bytes = {}
-    for _ = 1, math.max(0, tiles or 1) do bytes[#bytes + 1] = step end
-    bytes[#bytes + 1] = Movement.STEP_END
     local objectId = objectIdOf(world, entity)
     if not objectId then
       return nil, "no Gen 2 objectId for that entity: only the player and a "
         .. "mapped object (def.index) can be moved"
     end
+    local n = math.max(0, tiles or 1)
+    if opts and opts.collide and n > 0 then
+      local d = Map2.DELTA[dir]
+      local cx, cy = entity.cellX, entity.cellY
+      local allowed = 0
+      for _ = 1, n do
+        if not stepAllowed(world, entity, dir, cx, cy) then break end
+        allowed = allowed + 1
+        if d and cx and cy then cx, cy = cx + d[1], cy + d[2] end
+      end
+      if allowed < n then entity.facing = dir end
+      n = allowed
+    end
+    local bytes = {}
+    for _ = 1, n do bytes[#bytes + 1] = step end
+    bytes[#bytes + 1] = Movement.STEP_END
     world:beginMovement(objectId, bytes, onDone)
     return true
   end
@@ -1401,7 +1441,8 @@ COVERAGE[OW] = {
       .. "objectId 1 is wLastTalked, not object zero",
     scriptMove = "the player maps to objectId 0 and a mapped object to "
       .. "def.index + 1; an entity with neither (a mod's own guest) is "
-      .. "REFUSED with a reason rather than moving the last-talked NPC",
+      .. "REFUSED with a reason rather than moving the last-talked NPC; "
+      .. "opts.collide truncates the walk at the first blocked step",
     connectionLanding = "Gen 1's five values (destDef, tilesetDef, x, y, "
       .. "conn); `conn` is Gold's connection record, keyed map/mapId + offset",
     timeOfDay = "recomputed from the clock every call and never cached, so a "

src/mods/ImportAccess.lua

@@ -0,0 +1,174 @@
+-- Scoped access to a mod's launcher-validated required/optional imports and
+-- to installation-wide generated cache data.
+--
+-- This intentionally does not expose host paths or raw filesystem handles.
+-- Import reads are bounded and can only address ids declared by the calling
+-- mod's manifest. Cache paths are confined to mod_cache/<mod-id>/ and are not
+-- tied to a Pokémon playthrough.
+
+local RequiredImports = require("src.mods.RequiredImports")
+local SafePath = require("src.mods.SafePath")
+local SaveData = require("src.core.SaveData")
+
+local ImportAccess = {}
+
+ImportAccess.MAX_READ_BYTES = 8 * 1024 * 1024
+ImportAccess.MAX_CACHE_WRITE_BYTES = 64 * 1024 * 1024
+
+local function specMap(manifest)
+  local out = {}
+  for _, spec in ipairs(RequiredImports.specs(manifest)) do out[spec.id] = spec end
+  return out
+end
+
+local function parentOf(path)
+  return path:match("^(.*)/[^/]+$")
+end
+
+local function copyInfo(info)
+  if not info then return nil end
+  return { type = info.type, size = info.size, modtime = info.modtime }
+end
+
+local function fsReadRange(fs, path, offset, length)
+  if fs and type(fs.readRange) == "function" then
+    return fs.readRange(path, offset, length)
+  end
+  local newFile = fs and fs.newFile
+  if newFile then
+    local file, makeErr = newFile(path)
+    if not file then return nil, makeErr or "could not open import" end
+    local ok, openErr = file:open("r")
+    if not ok then return nil, openErr or "could not open import" end
+    local seekOk, seekErr = file:seek(offset)
+    if seekOk == nil or seekOk == false then
+      file:close()
+      return nil, seekErr or "could not seek import"
+    end
+    local data, readErr = file:read(length)
+    file:close()
+    return data, readErr
+  end
+  -- Injectable headless filesystems may expose only read(). Production
+  -- love.filesystem has newFile(), so large imports are never materialized
+  -- into one Lua string by this fallback.
+  if fs and fs.read then
+    local data = fs.read(path)
+    if type(data) ~= "string" then return nil, "could not read import" end
+    return data:sub(offset + 1, offset + length)
+  end
+  return nil, "random-access import reads are unavailable"
+end
+
+local function validatedInfo(manifest, spec, fs)
+  local ok, detail = RequiredImports.validateStored(manifest, spec, fs)
+  if not ok then return nil, detail or "import is not validated" end
+  local path = RequiredImports.path(manifest, spec)
+  local info = fs.getInfo and fs.getInfo(path, "file") or nil
+  if not info then return nil, "import is missing" end
+  return info, detail
+end
+
+local function makeCache(modId, fs)
+  local root = "mod_cache/" .. modId
+  local function pathFor(rel, what)
+    rel = SafePath.require(rel, what or "mod.cache path")
+    return root .. "/" .. rel
+  end
+  local cache = {}
+
+  function cache:write(rel, bytes)
+    if type(bytes) ~= "string" then
+      return nil, "mod.cache:write expects a byte string"
+    end
+    if #bytes > ImportAccess.MAX_CACHE_WRITE_BYTES then
+      return nil, "mod.cache:write payload exceeds 64 MiB; split generated data into smaller files"
+    end
+    local path = pathFor(rel, "mod.cache:write")
+    local parent = parentOf(path)
+    if parent and fs.createDirectory then
+      local ok = fs.createDirectory(parent)
+      if ok == false then return nil, "could not create cache directory" end
+    end
+    if not fs.write then return nil, "cache writes are unavailable" end
+    return fs.write(path, bytes)
+  end
+
+  function cache:read(rel)
+    local path = pathFor(rel, "mod.cache:read")
+    if not fs.read then return nil, "cache reads are unavailable" end
+    return fs.read(path)
+  end
+
+  function cache:info(rel)
+    local path = pathFor(rel, "mod.cache:info")
+    if not fs.getInfo then return nil end
+    return copyInfo(fs.getInfo(path))
+  end
+
+  function cache:exists(rel)
+    local info = self:info(rel)
+    return info ~= nil and info.type == "file"
+  end
+
+
+  function cache:delete(rel)
+    local path = pathFor(rel, "mod.cache:delete")
+    if not fs.remove then return nil, "cache deletion is unavailable" end
+    return fs.remove(path)
+  end
+
+  return cache
+end
+
+function ImportAccess.new(manifest, fs)
+  local specs = specMap(manifest)
+  local cacheFs = SaveData.persistenceFs(fs) or fs
+  local imports = {}
+
+  function imports:info(id)
+    local spec = specs[id]
+    if not spec then return nil, "undeclared import: " .. tostring(id) end
+    local info, digestOrErr = validatedInfo(manifest, spec, fs)
+    if not info then return nil, digestOrErr end
+    return {
+      id = spec.id,
+      name = spec.name,
+      file = spec.file,
+      size = info.size,
+      md5 = digestOrErr,
+      required = spec.required ~= false,
+    }
+  end
+
+  function imports:read(id, offset, length)
+    local spec = specs[id]
+    if not spec then return nil, "undeclared import: " .. tostring(id) end
+    offset, length = tonumber(offset), tonumber(length)
+    if not offset or offset < 0 or offset % 1 ~= 0 then
+      return nil, "offset must be a non-negative integer"
+    end
+    if not length or length < 0 or length % 1 ~= 0 then
+      return nil, "length must be a non-negative integer"
+    end
+    if length > ImportAccess.MAX_READ_BYTES then
+      return nil, "single import read exceeds 8 MiB"
+    end
+
+    local info, err = validatedInfo(manifest, spec, fs)
+    if not info then return nil, err end
+    local size = tonumber(info.size) or tonumber(spec.size)
+    if size and offset + length > size then return nil, "import read is out of bounds" end
+    if length == 0 then return "" end
+
+    local path = RequiredImports.path(manifest, spec)
+    local data, readErr = fsReadRange(fs, path, offset, length)
+    if not data then return nil, readErr end
+    if #data ~= length then return nil, "short import read" end
+    return data
+  end
+
+  return imports, makeCache(manifest.id, cacheFs)
+end
+
+return ImportAccess

src/mods/LauncherMods.lua

@@ -603,6 +603,33 @@ function LauncherMods.setEnabled(id, enabled, version)
   return true
 end
 
+function LauncherMods.modOptions()
+  local ok, options = pcall(SaveData.loadOptions)
+  if not ok or type(options) ~= "table" then return {} end
+  return options.modOptions or {}
+end
+
+function LauncherMods.setModOptions(id, values)
+  if type(id) ~= "string" or id == "" or type(values) ~= "table" then
+    return false
+  end
+  local options = SaveData.loadOptions()
+  if SaveData.isSafeMode(options) then return false end
+  options.modOptions = options.modOptions or {}
+  local bucket = options.modOptions[id] or {}
+  for key, value in pairs(values) do
+    local t = type(value)
+    if type(key) == "string" and key ~= ""
+        and (t == "string" or t == "number" or t == "boolean") then
+      bucket[key] = value
+    end
+  end
+  options.modOptions[id] = bucket
+  SaveData.saveOptions(options)
+  LauncherMods.syncActiveProfile(options)
+  return true
+end
+
 -- setAllEnabled(ids, enabled [, version]): the launcher's Enable all / Disable
 -- all buttons (#647).  Writes what setEnabled writes, but loads and
 -- saves once for the whole list: saveOptions rewrites the whole options file per

src/mods/Loader.lua

@@ -119,6 +119,17 @@ local GEN1_ONLY_MODULES = {
   ["src.ui.OptionsMenu"] = true,
 }
 
+local function crossGenerationDenial(name, generation)
+  if type(name) ~= "string" or generation ~= 1 then return nil end
+  if not (name:find("^src%.[%w_]+%.gen2%.") or name == "src.core.Game2") then
+    return nil
+  end
+  return ("%s is a Gen 2 engine module and this is a Gen 1 game; the structs "
+    .. "it reads and writes are not this game's, so anything it stores lands "
+    .. "on the save in the wrong shape. Take the game from mod.game and the "
+    .. "world from mod.world, which resolve per generation"):format(name)
+end
+
 -- the src.* modules the mod surface points authors at: another mod's
 -- exports carry a version string that wants range-checking before use, and
 -- ChipAsm is the authoring path for chip music and sfx
@@ -214,6 +225,7 @@ function Loader:_installDevShim()
       if owner or callerIsMod(3) then
         local id = type(owner) == "string" and owner or nil
         local denial = Sandbox.moduleDenial(name, devShim.permissions[id])
+          or (id and crossGenerationDenial(name, devShim.generation))
         if denial then error(("[%s] %s"):format(id or "mod", denial), 0) end
       end
       if devShim.dev or devShim.generation ~= 1 then scanRequire(name) end
@@ -962,6 +974,8 @@ function Loader:_api(mod)
   local Storage = engineRequire("src.mods.Storage")
   local storage = Storage and Storage.new(modId, loader.fs)
   local Checkpoint = engineRequire("src.core.Checkpoint")
+  local ImportAccess = engineRequire("src.mods.ImportAccess")
+  local importApi, installCache = ImportAccess.new(mod.manifest, loader.fs)
   local api = {
     id = modId,
     version = mod.manifest.version,
@@ -1161,6 +1175,12 @@ function Loader:_api(mod)
     -- checkpoint. The
     -- engine binds version/playthrough/mod scope and portable persistence;
     -- callers never receive paths or a raw filesystem handle.
+    -- Read-only bounded access to this mod's manifest-declared, launcher-validated
+    -- imports. No host path is exposed; large sources are read in bounded ranges.
+    imports = importApi,
+    -- Installation-scoped generated data, independent from Pokémon save slots.
+    -- This is where ROM-derived caches belong; mod.storage remains playthrough-scoped.
+    cache = installCache,
     storage = {
       context = function(_, game) return storage:context(game) end,
       selected = function(_, game) return storage:selected(game) end,

src/mods/RequiredImports.lua

@@ -120,6 +120,36 @@ local function accepts(spec, digest)
   return false
 end
 
+local function specById(manifest, importId)
+  for _, candidate in ipairs(allSpecs(manifest)) do
+    if candidate.id == importId then return candidate end
+  end
+  return nil
+end
+
+RequiredImports.spec = specById
+
+local function streamDigest(fs, path, chunkBytes)
+  if not (fs and fs.newFile) then return nil, "streaming file access is unavailable" end
+  local file, makeErr = fs.newFile(path)
+  if not file then return nil, makeErr or "could not open stored import" end
+  local ok, openErr = file:open("r")
+  if not ok then return nil, openErr or "could not open stored import" end
+  local MD5 = require("src.mods.StreamMD5")
+  local ctx = MD5.new()
+  chunkBytes = chunkBytes or (4 * 1024 * 1024)
+  while true do
+    local data, readErr = file:read(chunkBytes)
+    if data and #data > 0 then ctx:update(data) end
+    if not data or #data < chunkBytes then
+      if readErr then file:close(); return nil, readErr end
+      break
+    end
+  end
+  file:close()
+  return ctx:final()
+end
+
 function RequiredImports.path(manifest, spec)
   return manifest.path .. "/baseroms/" .. spec.file
 end
@@ -180,6 +210,47 @@ local function removeReceipt(manifest, spec, fs)
   end
 end
 
+-- Finalize a caller-streamed import after the destination bytes have already
+-- been copied into the engine-owned baseroms path. This keeps large imports
+-- out of a single Lua string while preserving the same size/MD5 receipt rules.
+function RequiredImports.acceptStoredDigest(manifest, importId, digest, fs)
+  fs = fs or (love and love.filesystem)
+  local spec = specById(manifest, importId)
+  if not spec then return nil, "unknown required import: " .. tostring(importId) end
+  digest = tostring(digest or ""):lower()
+  if not accepts(spec, digest) then
+    return nil, ("MD5 mismatch (got %s)"):format(digest ~= "" and digest or "unavailable")
+  end
+  local path = RequiredImports.path(manifest, spec)
+  local info = fs and fs.getInfo and fs.getInfo(path, "file") or nil
+  if not info then return nil, "copied import is missing" end
+  local sizeErr = RequiredImports.sizeError(spec, info.size, true)
+  if sizeErr then return nil, sizeErr end
+  if love and fs == love.filesystem then
+    local savedPrefix = CacheFs.prefix
+    local ok, prefixErr = xpcall(function()
+      CacheFs.prefix = ""
+      CacheFs.remove(removedMarker(manifest, spec))
+      CacheFs.prefix = savedPrefix
+      -- writeReceipt has its own temporary CacheFs prefix switch. Keep it
+      -- inside this guard too so a write error cannot leak global state.
+      writeReceipt(manifest, spec, digest, info, fs)
+    end, function(err)
+      return tostring(err)
+    end)
+    CacheFs.prefix = savedPrefix
+    if not ok then
+      return nil, "could not finalize import receipt: " .. tostring(prefixErr)
+    end
+    return true, digest
+  elseif fs and fs.remove then
+    fs.remove(removedMarker(manifest, spec))
+  end
+  writeReceipt(manifest, spec, digest, info, fs)
+  return true, digest
+end
+
+
 -- Validate bytes against a declaration.  The returned data is canonicalized
 -- (notably for N64 byte order/header variants) and is what must be stored.
 function RequiredImports.validateData(spec, data, hashFn)
@@ -217,6 +288,22 @@ function RequiredImports.validateStored(manifest, spec, fs, hashFn)
   local cached = cachedDigest(manifest, spec, fs, info)
   if cached then return true, cached, true end
   removeReceipt(manifest, spec, fs)
+  -- Large raw imports (GameCube discs, future optical images, etc.) must never
+  -- be materialized into one Lua string merely because their validation
+  -- receipt was lost. Stream the MD5 directly from the installed file. N64
+  -- sources stay on the canonicalization path because byte-order/header
+  -- normalization is part of their validation contract.
+  if info.size and info.size > RequiredImports.LARGE_WARN_BYTES
+      and spec.format ~= "n64" and fs.newFile then
+    local digest, hashErr = streamDigest(fs, path)
+    if not digest then return nil, hashErr end
+    if not accepts(spec, digest) then
+      return nil, ("MD5 mismatch (got %s)"):format(digest)
+    end
+    info = fs.getInfo(path, "file") or info
+    writeReceipt(manifest, spec, digest, info, fs)
+    return true, digest, false
+  end
   if not fs.read then return nil, "file could not be read" end
   local data = fs.read(path)
   local normalized, detail = RequiredImports.validateStoredData(spec, data, hashFn)

src/mods/StreamMD5.lua

@@ -0,0 +1,101 @@
+local bitlib = rawget(_G, "bit") or rawget(_G, "bit32")
+if not bitlib then error("StreamMD5 requires bit or bit32") end
+
+local band, bor, bxor, bnot = bitlib.band, bitlib.bor, bitlib.bxor, bitlib.bnot
+local lshift, rshift = bitlib.lshift, bitlib.rshift
+local rol = bitlib.rol or bitlib.lrotate
+
+local K = {
+  0xd76aa478,0xe8c7b756,0x242070db,0xc1bdceee,0xf57c0faf,0x4787c62a,0xa8304613,0xfd469501,
+  0x698098d8,0x8b44f7af,0xffff5bb1,0x895cd7be,0x6b901122,0xfd987193,0xa679438e,0x49b40821,
+  0xf61e2562,0xc040b340,0x265e5a51,0xe9b6c7aa,0xd62f105d,0x02441453,0xd8a1e681,0xe7d3fbc8,
+  0x21e1cde6,0xc33707d6,0xf4d50d87,0x455a14ed,0xa9e3e905,0xfcefa3f8,0x676f02d9,0x8d2a4c8a,
+  0xfffa3942,0x8771f681,0x6d9d6122,0xfde5380c,0xa4beea44,0x4bdecfa9,0xf6bb4b60,0xbebfbc70,
+  0x289b7ec6,0xeaa127fa,0xd4ef3085,0x04881d05,0xd9d4d039,0xe6db99e5,0x1fa27cf8,0xc4ac5665,
+  0xf4292244,0x432aff97,0xab9423a7,0xfc93a039,0x655b59c3,0x8f0ccc92,0xffeff47d,0x85845dd1,
+  0x6fa87e4f,0xfe2ce6e0,0xa3014314,0x4e0811a1,0xf7537e82,0xbd3af235,0x2ad7d2bb,0xeb86d391,
+}
+local S = {
+  7,12,17,22, 7,12,17,22, 7,12,17,22, 7,12,17,22,
+  5,9,14,20, 5,9,14,20, 5,9,14,20, 5,9,14,20,
+  4,11,16,23, 4,11,16,23, 4,11,16,23, 4,11,16,23,
+  6,10,15,21, 6,10,15,21, 6,10,15,21, 6,10,15,21,
+}
+
+local function add32(a,b,c,d)
+  local n = (a or 0) + (b or 0) + (c or 0) + (d or 0)
+  return band(n, 0xffffffff)
+end
+
+local function le32_from(s, i)
+  local b1,b2,b3,b4 = s:byte(i, i+3)
+  return bor(b1, lshift(b2,8), lshift(b3,16), lshift(b4,24))
+end
+
+local function le32_bytes(x)
+  return string.char(
+    band(x,0xff), band(rshift(x,8),0xff),
+    band(rshift(x,16),0xff), band(rshift(x,24),0xff))
+end
+
+local M = {}
+local StreamMD5 = {}
+StreamMD5.__index = StreamMD5
+
+function StreamMD5.new()
+  return setmetatable({
+    a=0x67452301, b=0xefcdab89, c=0x98badcfe, d=0x10325476,
+    bytes=0, buffer="", done=false,
+  }, StreamMD5)
+end
+
+function StreamMD5:_block(block)
+  for j=1,16 do M[j] = le32_from(block, (j-1)*4+1) end
+  local a,b,c,d = self.a,self.b,self.c,self.d
+  for i=0,63 do
+    local f,g
+    if i < 16 then
+      f = bor(band(b,c), band(bnot(b),d)); g=i
+    elseif i < 32 then
+      f = bor(band(d,b), band(bnot(d),c)); g=(5*i+1)%16
+    elseif i < 48 then
+      f = bxor(b,c,d); g=(3*i+5)%16
+    else
+      f = bxor(c, bor(b,bnot(d))); g=(7*i)%16
+    end
+    local tmp=d
+    d=c
+    c=b
+    b=add32(b, rol(add32(a,f,K[i+1],M[g+1]), S[i+1]))
+    a=tmp
+  end
+  self.a=add32(self.a,a); self.b=add32(self.b,b)
+  self.c=add32(self.c,c); self.d=add32(self.d,d)
+end
+
+function StreamMD5:update(data)
+  assert(not self.done, "StreamMD5 context already finalized")
+  assert(type(data)=="string", "StreamMD5:update expects a string")
+  self.bytes = self.bytes + #data
+  local s = self.buffer .. data
+  local full = #s - (#s % 64)
+  for i=1,full,64 do self:_block(s:sub(i,i+63)) end
+  self.buffer = s:sub(full+1)
+  return self
+end
+
+function StreamMD5:final()
+  assert(not self.done, "StreamMD5 context already finalized")
+  local originalBytes = self.bytes
+  local padLen = (56 - ((originalBytes + 1) % 64)) % 64
+  local bits = originalBytes * 8
+  local lo = bits % 4294967296
+  local hi = math.floor(bits / 4294967296) % 4294967296
+  self:update("\128" .. string.rep("\0", padLen) .. le32_bytes(lo) .. le32_bytes(hi))
+  assert(#self.buffer == 0, "MD5 finalization left a partial block")
+  self.done=true
+  local raw = le32_bytes(self.a)..le32_bytes(self.b)..le32_bytes(self.c)..le32_bytes(self.d)
+  return (raw:gsub(".", function(ch) return string.format("%02x", ch:byte()) end))
+end
+
+return StreamMD5

src/pokemon/Stats.lua

@@ -51,11 +51,20 @@ end
 -- (engine/pokemon/status_screen.asm:66-76, "mon is in a box or daycare" ->
 -- CalcStats) and when one is moved back into the party
 -- (engine/pokemon/add_mon.asm _MoveMon tail).  The stored current HP is
--- kept (box_struct does hold it) but clamped to the recalculated maximum so
--- a tampered save cannot overfill the bar.  A mon that already has stats is
--- returned untouched, so a vanilla save round-trips.  #233, #304
+-- kept (box_struct does hold it) but clamped to the recalculated maximum.
+-- A complete stat block is returned untouched; an incomplete one is rebuilt,
+-- because CalcStats writes all NUM_STATS stats or none
+-- (home/move_mon.asm:33-48).  #233, #304, #1517
+local function statsComplete(stats)
+  for _, key in ipairs(ORDER) do
+    if type(stats[key]) ~= "number" then return false end
+  end
+  return true
+end
+
 function Stats.ensure(speciesDef, mon)
-  if type(mon) ~= "table" or type(mon.stats) == "table" then return mon end
+  if type(mon) ~= "table" then return mon end
+  if type(mon.stats) == "table" and statsComplete(mon.stats) then return mon end
   if type(speciesDef) ~= "table" or type(speciesDef.baseStats) ~= "table" then
     return mon
   end

src/render/PaletteFX.lua

@@ -454,7 +454,7 @@ function PaletteFX.pal(data, name)
     if fromCgb then return fromCgb end
   end
   local p = PaletteFX.pack(data)
-  local c = p and p.palettes[name]
+  local c = p and p.palettes and p.palettes[name]
   if c then return c end
   if GameVersion.isYellow() then
     local y = PaletteFX.yellowPack()

src/render/Playfield.lua

@@ -3,8 +3,6 @@ local TouchSkin = require("src.core.TouchSkin")
 
 local Playfield = {}
 
-Playfield.WIDTH, Playfield.HEIGHT = 160, 144
-
 Playfield.entered = false
 Playfield.box = nil
 
@@ -35,14 +33,9 @@ function Playfield.cutout(sw, sh)
 end
 
 function Playfield.rect(sw, sh)
-  local x, y, w, h, _, expand = Playfield.cutout(sw, sh)
+  local x, y, w, h = Playfield.cutout(sw, sh)
   if not x then return 0, 0, sw or 0, sh or 0, false end
-  if expand then return x, y, w, h, true end
-  local s = math.max(1, math.floor(math.min(w / Playfield.WIDTH,
-    h / Playfield.HEIGHT)))
-  local pw = math.min(w, Playfield.WIDTH * s)
-  local ph = math.min(h, Playfield.HEIGHT * s)
-  return x + math.floor((w - pw) / 2), y + math.floor((h - ph) / 2), pw, ph, true
+  return x, y, w, h, true
 end
 
 function Playfield.enter(x, y, w, h)

src/render/Renderer.lua

@@ -87,12 +87,12 @@ local function displayMetrics()
   if dpiX < 1e-6 then dpiX = 1 end
   if dpiY < 1e-6 then dpiY = 1 end
   local vx, vy = 0, 0
-  local cut, grow = false, false
-  local sx, sy, sw, sh, _, expand = Playfield.cutout(pw, ph)
+  local cut = false
+  local sx, sy, sw, sh = Playfield.cutout(pw, ph)
   if sx then
-    vx, vy, pw, ph, cut, grow = sx, sy, sw, sh, true, expand
+    vx, vy, pw, ph, cut = sx, sy, sw, sh, true
   end
-  return ww, wh, pw, ph, dpiX, dpiY, vx, vy, cut, grow
+  return ww, wh, pw, ph, dpiX, dpiY, vx, vy, cut
 end
 
 local function positionLift(ph, contentPx, dpiY, cut)
@@ -275,7 +275,7 @@ end
 -- corners; flat mode returns exactly today's size (growth factor is 1 when
 -- tilt is inactive).
 function Renderer:worldViewSize()
-  local _, _, pw, ph, _, dpiY, _, _, cut, grow = displayMetrics()
+  local _, _, pw, ph, _, dpiY, _, _, cut = displayMetrics()
   -- FAITHFUL RATIO on mobile.  The world pass deliberately expands to cover the
   -- WHOLE display, so letterbox voids become more map instead of black bars.
   -- That is why the lock appeared to do nothing in the overworld: it shrank
@@ -287,7 +287,6 @@ function Renderer:worldViewSize()
   -- this is the same sum with the viewport standing in for the window, so
   -- both platforms show the same map area at the same zoom.
   local cap = FaithfulRes.scaleCap()
-  if not cap and cut and not grow then cap = self:fitScale() end
   if cap then
     local uiw, uih = self:uiSize()
     pw = cut and math.min(pw, uiw * cap) or uiw * cap

src/render/Transition.lua

@@ -85,7 +85,9 @@ function Transition.new(game, onMidpoint, onDone, warp)
 end
 
 function Transition:finish()
-  self.game.stack:pop()
+  if self.done then return end
+  self.done = true
+  if not self.offStack then self.game.stack:pop() end
   if self.onDone then self.onDone() end
 end
 
@@ -96,10 +98,16 @@ function Transition:update(dt)
     self.t = 0
     if self.phase == "out" then
       self.phase = "in"
-      if self.onMidpoint then self.onMidpoint() end
       -- LoadGBPal restores the palettes in one write, so with no fade in the
       -- map is simply there on the next frame
-      if (self.framesIn or 0) <= 0 then self:finish() end
+      if (self.framesIn or 0) <= 0 then
+        self.offStack = true
+        self.game.stack:pop()
+        if self.onMidpoint then self.onMidpoint() end
+        self:finish()
+      elseif self.onMidpoint then
+        self.onMidpoint()
+      end
     else
       self:finish()
     end

src/render/Zoom.lua

@@ -19,6 +19,8 @@ Zoom.allowSurvey = true
 
 -- legal offset range for a given fit scale (vanilla: survey at 1 px/world
 -- through 2× fit).  zoom.range may widen or shrink the window.
+-- When the window only fits 1×, 1-S is 0 and there would be no OUT
+-- levels; keep three survey steps so OPTIONS always has zoom-out.
 function Zoom.offsetRange(S)
   S = math.max(1, math.floor(tonumber(S) or 1))
   local lo, hi = 1 - S, S
@@ -30,7 +32,11 @@ function Zoom.offsetRange(S)
   end
   -- LOW performance tier: no survey (negative offsets), even if a mod's
   -- zoom.range widened it.  == false so nil/true stays permissive.
-  if Zoom.allowSurvey == false and lo < 0 then lo = 0 end
+  if Zoom.allowSurvey == false then
+    if lo < 0 then lo = 0 end
+  elseif lo > -3 then
+    lo = -3
+  end
   return lo, hi
 end
 
@@ -44,6 +50,8 @@ function Zoom.scale(S)
   local maxScale = math.max(minScale, S + hi)
   if s < minScale then s = minScale end
   if s > maxScale then s = maxScale end
+  -- Integer offset below 1px/world (OPTIONS OUT on a 1× window): 1/2, 1/4, …
+  if s < 1 then s = 0.5 ^ (1 - s) end
   if s < 0.25 then s = 0.25 end
   return s
 end
@@ -79,6 +87,30 @@ function Zoom.applyOptions(opts)
   Zoom.offset = math.floor(tonumber(opts and opts.zoom) or 0)
 end
 
+-- Integer fit used when OPTIONS has no live renderer (launcher, title).
+function Zoom.windowFitScale()
+  if love and love.graphics and love.graphics.getDimensions then
+    local ww, wh = love.graphics.getDimensions()
+    ww, wh = tonumber(ww) or 0, tonumber(wh) or 0
+    if ww >= 160 and wh >= 144 then
+      return math.max(1, math.floor(math.min(ww / 160, wh / 144)))
+    end
+  end
+  return 1
+end
+
+-- One step of the OPTIONS ZOOM row (dir +1 in, -1 out).  Shared by Red
+-- and Gold so both ladders offer OUT / FIT / IN.
+function Zoom.nudgeOptions(options, dir, S)
+  S = math.max(1, math.floor(tonumber(S) or Zoom.windowFitScale()))
+  local lo, hi = Zoom.offsetRange(S)
+  local off = math.floor(tonumber(options and options.zoom) or 0) + (dir or 1)
+  if off > hi then off = lo elseif off < lo then off = hi end
+  if options then options.zoom = off end
+  Zoom.offset = off
+  return off
+end
+
 -- FIT / OUT1 / OUT2 / … / IN1 / IN2 / …
 function Zoom.offsetLabel(offset)
   offset = math.floor(tonumber(offset) or 0)

src/sync/SyncEngine.lua

@@ -596,12 +596,13 @@ function SyncEngine:resolveConflict(key, choice)
   return true
 end
 
-function SyncEngine:uploadMods()
+function SyncEngine:uploadMods(includeOptions)
   if not self:linked() then return false, "this device is not linked" end
   if self:busy() then return false, "sync is busy" end
-  local manifest = SyncMods.build(self.modDeps)
+  local manifest = SyncMods.build(self.modDeps, includeOptions)
   self.phase = "uploading"
-  self.status = "Uploading the mod list..."
+  self.status = includeOptions and "Uploading the mod list and options..."
+    or "Uploading the mod list..."
   local handle, err = self.client:putMods(manifest)
   return self:_request(handle, err, function(eng)
     eng.phase = "idle"
@@ -618,19 +619,17 @@ function SyncEngine:fetchModPlan()
   return self:_request(handle, err, function(eng, res)
     local data = res.data or {}
     local manifest = type(data.manifest) == "table" and data.manifest or data
-    eng.modPlan = SyncMods.plan(manifest, eng.modDeps)
-    eng.phase = "idle"
-    eng.status = SyncMods.planEmpty(eng.modPlan)
-      and "Mods already match" or "Mod changes ready to apply"
+    eng:_takeModPlan(SyncMods.plan(manifest, eng.modDeps))
   end)
 end
 
-function SyncEngine:shareMods()
+function SyncEngine:shareMods(includeOptions)
   if not self:linked() then return false, "this device is not linked" end
   if self:busy() then return false, "sync is busy" end
-  local manifest = SyncMods.build(self.modDeps)
+  local manifest = SyncMods.build(self.modDeps, includeOptions)
   self.phase = "uploading"
-  self.status = "Sharing the mod list..."
+  self.status = includeOptions and "Sharing the mod list and options..."
+    or "Sharing the mod list..."
   local handle, err = self.client:shareMods(manifest)
   return self:_request(handle, err, function(eng, res)
     local data = res.data or {}
@@ -649,16 +648,44 @@ function SyncEngine:fetchShare(code)
   return self:_request(handle, err, function(eng, res)
     local data = res.data or {}
     local manifest = type(data.manifest) == "table" and data.manifest or data
-    eng.modPlan = SyncMods.plan(manifest, eng.modDeps)
-    eng.phase = "idle"
-    eng.status = SyncMods.planEmpty(eng.modPlan)
-      and "Mods already match" or "Mod changes ready to apply"
+    eng:_takeModPlan(SyncMods.plan(manifest, eng.modDeps))
   end)
 end
 
+function SyncEngine:_takeModPlan(plan)
+  self.modPlan = plan
+  self.phase = "idle"
+  if SyncMods.planHasOptions(plan) then
+    self.status = ("This list carries options for %d mods.")
+      :format(#plan.options)
+  elseif SyncMods.planEmpty(plan) then
+    self.status = "Mods already match"
+  else
+    self.status = "Mod changes ready to apply"
+  end
+end
+
+function SyncEngine:modOptionsAsk()
+  local plan = self.modPlan
+  if not SyncMods.planHasOptions(plan) then return nil end
+  if plan.applyOptions ~= nil then return nil end
+  return SyncMods.optionModIds(plan)
+end
+
+function SyncEngine:answerModOptions(importThem)
+  local plan = self.modPlan
+  if not SyncMods.planHasOptions(plan) then return false end
+  SyncMods.answerOptions(plan, importThem)
+  self.status = plan.applyOptions
+    and "Their mod options will be imported too"
+    or "Their mod options will be skipped"
+  return plan.applyOptions
+end
+
 function SyncEngine:applyModPlan(progress)
   if not self.modPlan then return false, "no mod plan" end
   if self.modApply then return false, "the mods are already being applied" end
+  self.modPlan.applyOptions = self.modPlan.applyOptions == true
   local steps = SyncMods.steps(self.modPlan, self.modDeps)
   if #steps == 0 then
     self.modPlan = nil

src/sync/SyncMods.lua

@@ -1,6 +1,8 @@
 local SyncMods = {}
 
-SyncMods.REV = 1
+SyncMods.REV = 2
+SyncMods.MAX_OPTION_KEYS = 64
+SyncMods.MAX_OPTION_TEXT = 256
 
 local function versions()
   local ok, GameVersion = pcall(require, "src.core.GameVersion")
@@ -35,6 +37,12 @@ local function defaultDeps()
     setEnabled = function(id, enabled, version)
       return require("src.mods.LauncherMods").setEnabled(id, enabled, version)
     end,
+    modOptions = function()
+      return require("src.mods.LauncherMods").modOptions()
+    end,
+    setOptions = function(id, values)
+      return require("src.mods.LauncherMods").setModOptions(id, values)
+    end,
   }
 end
 
@@ -46,6 +54,41 @@ local function deps(given)
   return out
 end
 
+local function sanitizeOptions(bucket)
+  if type(bucket) ~= "table" then return nil end
+  local keys = {}
+  for k, v in pairs(bucket) do
+    local t = type(v)
+    if type(k) == "string" and k ~= ""
+        and (t == "string" or t == "number" or t == "boolean") then
+      keys[#keys + 1] = k
+    end
+  end
+  if #keys == 0 then return nil end
+  table.sort(keys)
+  local out, n = {}, 0
+  for _, k in ipairs(keys) do
+    if n >= SyncMods.MAX_OPTION_KEYS then break end
+    local v = bucket[k]
+    if type(v) == "string" then v = v:sub(1, SyncMods.MAX_OPTION_TEXT) end
+    local finite = type(v) ~= "number"
+      or (v == v and v ~= math.huge and v ~= -math.huge)
+    if finite then
+      out[k] = v
+      n = n + 1
+    end
+  end
+  if n == 0 then return nil end
+  return out
+end
+
+local function sameOptions(a, b)
+  for k, v in pairs(a) do
+    if (b or {})[k] ~= v then return false end
+  end
+  return true
+end
+
 local function sourceOf(row)
   local github = row.github
     or (type(row.manifest) == "table" and row.manifest.github)
@@ -55,9 +98,14 @@ local function sourceOf(row)
   return "local"
 end
 
-function SyncMods.build(given)
+function SyncMods.build(given, includeOptions)
   local d = deps(given)
   local manifest = { rev = SyncMods.REV, indexes = {}, mods = {} }
+  local stored = {}
+  if includeOptions then
+    local ok, live = pcall(d.modOptions)
+    if ok and type(live) == "table" then stored = live end
+  end
   for _, row in ipairs(d.indexes() or {}) do
     local url = row.url or row.feed
     if type(url) == "string" and url ~= "" then
@@ -72,11 +120,14 @@ function SyncMods.build(given)
       for _, version in ipairs(versions()) do
         if answers[version] then enabledFor[#enabledFor + 1] = version end
       end
+      local options = includeOptions and sanitizeOptions(stored[row.id]) or nil
+      if options then manifest.hasOptions = true end
       manifest.mods[#manifest.mods + 1] = {
         id = row.id,
         version = row.version,
         source = sourceOf(row),
         enabledFor = enabledFor,
+        options = options,
       }
     end
   end
@@ -86,9 +137,16 @@ end
 
 function SyncMods.plan(manifest, given)
   local d = deps(given)
-  local plan = { indexes = {}, toInstall = {}, toEnable = {}, missing = {} }
+  local plan = { indexes = {}, toInstall = {}, toEnable = {}, missing = {},
+                 options = {}, applyOptions = nil }
   if type(manifest) ~= "table" then return plan end
 
+  local liveOptions = {}
+  do
+    local ok, live = pcall(d.modOptions)
+    if ok and type(live) == "table" then liveOptions = live end
+  end
+
   local haveIndex = {}
   for _, row in ipairs(d.indexes() or {}) do
     if type(row.url) == "string" then haveIndex[row.url] = true end
@@ -130,6 +188,10 @@ function SyncMods.plan(manifest, given)
             plan.toEnable[#plan.toEnable + 1] = { id = mod.id, version = version }
           end
         end
+        local wanted = sanitizeOptions(mod.options)
+        if wanted and not sameOptions(wanted, liveOptions[mod.id]) then
+          plan.options[#plan.options + 1] = { id = mod.id, values = wanted }
+        end
       end
     end
   end
@@ -138,10 +200,33 @@ end
 
 function SyncMods.planEmpty(plan)
   if type(plan) ~= "table" then return true end
+  if plan.applyOptions and #(plan.options or {}) > 0 then return false end
   return #(plan.indexes or {}) == 0 and #(plan.toInstall or {}) == 0
     and #(plan.toEnable or {}) == 0
 end
 
+function SyncMods.planHasOptions(plan)
+  return type(plan) == "table" and #(plan.options or {}) > 0
+end
+
+function SyncMods.optionsAnswered(plan)
+  return not SyncMods.planHasOptions(plan) or plan.applyOptions ~= nil
+end
+
+function SyncMods.answerOptions(plan, importThem)
+  if type(plan) ~= "table" then return false end
+  plan.applyOptions = importThem and true or false
+  return plan.applyOptions
+end
+
+function SyncMods.optionModIds(plan)
+  local out = {}
+  for _, row in ipairs((type(plan) == "table" and plan.options) or {}) do
+    out[#out + 1] = row.id
+  end
+  return out
+end
+
 function SyncMods.steps(plan, given)
   local d = deps(given)
   local out = {}
@@ -175,6 +260,19 @@ function SyncMods.steps(plan, given)
       return true
     end }
   end
+  if plan.applyOptions then
+    for _, want in ipairs(plan.options or {}) do
+      out[#out + 1] = { label = want.id, run = function()
+        if broken[want.id] then return true end
+        local ok, err = d.setOptions(want.id, want.values)
+        if ok == false then
+          return nil, want.id .. ": "
+            .. tostring(err or "could not set the mod options")
+        end
+        return true
+      end }
+    end
+  end
   return out
 end
 

src/ui/Diploma.lua

@@ -1,18 +1,77 @@
 -- The dex-completion diploma (engine/events/diploma.asm DisplayDiploma /
 -- diploma2.asm DisplayDiplomaTop): a bordered certificate page with the
--- player's name, shown by the Celadon Mansion 3F game designer once 150
--- species are owned.  Diploma.render also backs the Yellow-only printed
--- copy (engine/printer/printer.asm PrintDiploma -> src/core/Printer.lua).
+-- player's name and character sprite, shown by the Celadon Mansion 3F game designer
+-- once 150 species are owned. Diploma.render also backs the printed copy
+-- (engine/printer/printer.asm PrintDiploma -> src/core/Printer.lua).
 
+local Assets = require("src.render.Assets")
 local Font = require("src.render.Font")
+local PaletteFX = require("src.render.PaletteFX")
+local Sprites = require("src.pokemon.Sprites")
 local Strings = require("src.core.Strings")
 
 local Diploma = {}
 Diploma.__index = Diploma
 Diploma.isOpaque = true
 
+-- SGB: PalPacket_Generic (MEWMON), whole screen (engine/events/diploma.asm:67)
+function Diploma:sgbPalettes(game)
+  return PaletteFX.wholeNamed(game.data, "MEWMON")
+end
+
+local function tryImage(path)
+  if not path then return nil end
+  local ok, img = pcall(Assets.image, path)
+  if ok and img then return img end
+  local ok2, img2 = pcall(love.graphics.newImage, path)
+  return ok2 and img2 or nil
+end
+
+local function loadFrame()
+  local frame = tryImage("assets/generated/trainer_card/trainer_info.png")
+  if not frame then return nil end
+  local quads = {}
+  for i = 0, 8 do
+    quads[i] = love.graphics.newQuad((i % 3) * 8,
+                                     math.floor(i / 3) * 8,
+                                     8, 8, frame:getDimensions())
+  end
+  return { img = frame, quads = quads }
+end
+
+local function drawFrameBox(frame, tx, ty, tw, th)
+  love.graphics.setColor(1, 1, 1, 1)
+  love.graphics.rectangle("fill", tx * 8, ty * 8, tw * 8, th * 8)
+  if not frame then
+    Font.drawBox(tx, ty, tw, th)
+    return
+  end
+  local img = frame.img
+  local q = frame.quads
+  love.graphics.setColor(1, 1, 1, 1)
+  -- corners
+  love.graphics.draw(img, q[0], tx * 8, ty * 8)
+  love.graphics.draw(img, q[2], (tx + tw - 1) * 8, ty * 8)
+  love.graphics.draw(img, q[6], tx * 8, (ty + th - 1) * 8)
+  love.graphics.draw(img, q[8], (tx + tw - 1) * 8, (ty + th - 1) * 8)
+  -- horizontal edges
+  for x = 1, tw - 2 do
+    love.graphics.draw(img, q[1], (tx + x) * 8, ty * 8)
+    love.graphics.draw(img, q[7], (tx + x) * 8, (ty + th - 1) * 8)
+  end
+  -- vertical edges
+  for y = 1, th - 2 do
+    love.graphics.draw(img, q[3], tx * 8, (ty + y) * 8)
+    love.graphics.draw(img, q[5], (tx + tw - 1) * 8, (ty + y) * 8)
+  end
+end
+
 function Diploma.new(game, onDone)
-  return setmetatable({ game = game, onDone = onDone }, Diploma)
+  local self = setmetatable({
+    game = game,
+    onDone = onDone,
+  }, Diploma)
+  return self
 end
 
 function Diploma:update()
@@ -23,23 +82,55 @@ function Diploma:update()
   end
 end
 
--- the DisplayDiplomaTop layout, hlcoord tiles kept as x*8 / y*8 pixels
+-- the DisplayDiploma / DisplayDiplomaTop layout (hlcoord tiles -> x*8, y*8)
 function Diploma.render(game)
+  local frame = loadFrame()
+  local circle = tryImage("assets/generated/trainer_card/circle_tile.png")
+
+  -- 1. Outer ornate frame border: hlcoord 0, 0 / bc 16, 18 -> (0, 0, 20, 18)
+  drawFrameBox(frame, 0, 0, 20, 18)
+
+  -- 2. Draw Player character sprite: farcall DrawPlayerCharacter
+  -- Shifted +33 px right from title screen base (82 + 33 = 115, y = 80)
+  local picPath, picTrueColor = Sprites.playerPath(
+    game.data, "front", { kind = "diploma" })
+  local pic = tryImage(picPath)
+  if pic then
     love.graphics.setColor(1, 1, 1, 1)
-  love.graphics.rectangle("fill", 0, 0, 160, 144)
-  love.graphics.setColor(0, 0, 0, 1)
-  love.graphics.rectangle("line", 2.5, 2.5, 155, 139)
-  Font.draw(Strings("<Diploma>"), 40, 16)                -- hlcoord 5,2
-  Font.draw(Strings("Player"), 24, 32)                   -- hlcoord 3,4
-  Font.draw(game.save.player.name or "RED", 80, 32)      -- hlcoord 10,4
-  local congrats = {                                     -- hlcoord 2,6
-    "Congrats! This", "diploma certifies", "that you have",
-    "completed your", "POKéDEX.",
-  }
-  for i, line in ipairs(congrats) do
-    Font.draw(Strings(line), 16, 48 + (i - 1) * 10)
+    love.graphics.draw(pic, 115, 80)
+    if picTrueColor then
+      PaletteFX.markTrueColor(115, 80, pic:getDimensions())
     end
-  Font.draw(Strings("GAME FREAK"), 72, 128)              -- hlcoord 9,16
+  end
+
+  -- 3. Header: hlcoord 5, 2 with flanking circle tiles ($70)
+  love.graphics.setColor(1, 1, 1, 1)
+  if circle then
+    love.graphics.draw(circle, 40, 16)   -- hlcoord 5, 2
+    love.graphics.draw(circle, 104, 16)  -- hlcoord 13, 2
+  end
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw(Strings("Diploma"), 48, 16)  -- hlcoord 6, 2
+
+  -- 4. Player info: hlcoord 3, 4 ("PLAYER" / "Player") and hlcoord 10, 4 (name)
+  Font.draw(Strings("Player"), 24, 32)
+  local playerName = (game.save.player and game.save.player.name) or "RED"
+  Font.draw(playerName, 80, 32)
+
+  -- 5. Congratulations text: hlcoord 2, 6 double-spaced lines (rows 6, 8, 10, 12, 14)
+  local congrats = {
+    { text = "Congrats! This",     y = 48 },   -- hlcoord 2, 6
+    { text = "diploma certifies",  y = 64 },   -- hlcoord 2, 8
+    { text = "that you have",      y = 80 },   -- hlcoord 2, 10
+    { text = "completed your",     y = 96 },   -- hlcoord 2, 12
+    { text = "POKéDEX.",           y = 112 },  -- hlcoord 2, 14
+  }
+  for _, line in ipairs(congrats) do
+    Font.draw(Strings(line.text), 16, line.y)
+  end
+
+  -- 6. Developer signature: hlcoord 9, 16
+  Font.draw(Strings("GAME FREAK"), 72, 128)
   love.graphics.setColor(1, 1, 1, 1)
 end
 

src/ui/OptionsMenu.lua

@@ -381,14 +381,7 @@ local function buildRows(game)
         return Zoom.offsetLabel(g.save.options.zoom or 0)
       end,
       step = function(g, dir)
-        local o = g.save.options
-        local S = Renderer:fitScale()
-        local lo, hi = Zoom.offsetRange(S)
-        local off = (o.zoom or 0) + dir
-        if off > hi then off = lo
-        elseif off < lo then off = hi end
-        o.zoom = off
-        Zoom.offset = off
+        Zoom.nudgeOptions(g.save.options, dir, Renderer:fitScale())
         return true
       end },
     { id = "voidFill", label = Strings("VOID FILL"),
@@ -580,8 +573,8 @@ local function buildRows(game)
     end
     rows = filtered
   end
-  -- ORIENTATION only on Android, the one platform Orientation.apply reaches.
-  if not Orientation.isAndroid() then
+  -- ORIENTATION only on the platforms Orientation.apply reaches (#1638).
+  if not (Orientation.isAndroid() or Orientation.isIOS()) then
     local filtered = {}
     for _, row in ipairs(rows) do
       if row.id ~= "orientation" then filtered[#filtered + 1] = row end

src/ui/PadCursor.lua

@@ -151,6 +151,7 @@ end
 
 function PadCursor.joystickpressed(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return nil end
+  if GamepadMap.isAccelerometer(joystick) then return nil end
   local padButton = GamepadMap.mapRawToGamepadButton(button)
   if padButton then return PadCursor.gamepadpressed(joystick, padButton) end
   return nil
@@ -158,12 +159,14 @@ end
 
 function PadCursor.joystickreleased(joystick, button)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   local padButton = GamepadMap.mapRawToGamepadButton(button)
   if padButton then PadCursor.gamepadreleased(joystick, padButton) end
 end
 
 function PadCursor.joystickaxis(joystick, axisIndex, value)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   if axisIndex == 1 then
     PadCursor.gamepadaxis(joystick, "leftx", value)
   elseif axisIndex == 2 then
@@ -173,6 +176,7 @@ end
 
 function PadCursor.joystickhat(joystick, hat, direction)
   if GamepadMap.ignoreRawForJoystick(joystick) then return end
+  if GamepadMap.isAccelerometer(joystick) then return end
   for _, d in ipairs(rawHatDirs[hat] or {}) do
     dir[d] = nil
   end

src/ui/StartMenu.lua

@@ -70,6 +70,9 @@ function StartMenu.new(game)
     -- leaves it up under the prompt -- engine/menus/main_menu.asm:381-405
     local panel
     panel = {
+      -- the panel overlaps the kept-open START menu box (start_sub_menus.asm:
+      -- 641-647), so neither can be docked to a screen edge on its own
+      holdsUIAnchors = true,
       delay = 0,
       update = function()
         -- ld c, 30 / jp DelayFrames: the bare panel holds before the

src/ui/TitleState.lua

@@ -43,6 +43,28 @@ local function withWhiteOf(pal, ref)
   return { ref[1], pal[2], pal[3], pal[4] }
 end
 
+-- Every drawn box, not just the topmost state's: DisplayContinueGameInfo
+-- leaves the menu box up behind the info window (main_menu.asm:36-39), so both
+-- are on screen and both need the overlay below.
+local function titleUiBoxes(game)
+  local stack = game and game.stack
+  local states = stack and stack.states
+  if not states then
+    local top = stack and stack.top and stack:top()
+    local box = top and top.titleUiBox
+    return box and { box } or {}
+  end
+  local boxes = {}
+  for i = (stack.visibleBase and stack:visibleBase() or 1), #states do
+    local state = states[i]
+    local shown = not stack.renderVisible or stack:renderVisible(state)
+    if shown and state and state.titleUiBox then
+      boxes[#boxes + 1] = state.titleUiBox
+    end
+  end
+  return boxes
+end
+
 function TitleState:sgbPalettes(game)
   local P = require("src.render.PaletteFX")
   local z
@@ -65,9 +87,6 @@ function TitleState:sgbPalettes(game)
       P.zone(P.pal(game.data, "MEWMON"), 0, 10, 19, 17),
     }
   end
-  local top = game.stack and game.stack:top()
-  local box = top and top.titleUiBox
-  if box then
   -- A DMG-grays zone, not the trueColor opt-out: through the shade-remap
   -- shader GRAYS is the identity for the box's four shades, so SGB /
   -- ADVANCED / OG modes keep #133's white paper and black ink exactly,
@@ -75,6 +94,7 @@ function TitleState:sgbPalettes(game)
   -- modes -- a trueColor rect skipped the shader entirely, leaving the
   -- main menu and CONTINUE info box a raw white hole over a CLASSIC
   -- pea-green title instead of matching it like the START menu does (#870).
+  for _, box in ipairs(titleUiBoxes(game)) do
     z[#z + 1] = P.zone(P.GRAYS, box[1], box[2], box[3], box[4])
   end
   return z[3] and z or nil
@@ -175,20 +195,21 @@ end
 local function replayObjSprite(game, image, quad, x, y)
   local P = require("src.render.PaletteFX")
   if not P.usesSpriteObp() then return end
-  local top = game.stack and game.stack:top()
-  local box = top and top.titleUiBox
-  if box then
+  local boxes = titleUiBoxes(game)
+  if boxes[1] then
     local w, h
     if quad then
       w, h = select(3, quad:getViewport())
     else
       w, h = image:getDimensions()
     end
+    for _, box in ipairs(boxes) do
       if x < (box[3] + 1) * 8 and x + w > box[1] * 8
          and y < (box[4] + 1) * 8 and y + h > box[2] * 8 then
         return
       end
     end
+  end
   P.markUiSpriteRedraw(image, quad, x, y)
 end
 

src/ui/TownMap.lua

@@ -14,6 +14,7 @@
 -- This is what the party-menu FLY field move opens (#195).
 
 local Font = require("src.render.Font")
+local GameVersion = require("src.core.GameVersion")
 local PaletteFX = require("src.render.PaletteFX")
 local Sound = require("src.core.Sound")
 local SpriteRenderer = require("src.render.SpriteRenderer")
@@ -292,7 +293,8 @@ function TownMap:moveList(step)
 end
 
 function TownMap:update(dt)
-  self.blink = (self.blink + 1) % 32
+  local cycle = GameVersion.generation() == 2 and 32 or 50
+  self.blink = (self.blink + 1) % cycle
   local input = self.game.input
   if input:wasPressed("b") then
     Sound.play(self.game.data, "Press_AB")
@@ -361,7 +363,13 @@ function TownMap:draw()
     end
     if self.nestSpecies then
       -- AREA mode: blinking nests, the species name up top
-      if self.blink % 16 < 10 then
+      local showNest = true
+      if GameVersion.generation() == 1 then
+        showNest = self.blink < 25
+      else
+        showNest = self.blink % 16 < 10
+      end
+      if showNest then
         for _, loc in ipairs(self.nests) do
           local x, y = markerXY(loc)
           if self.nestIcon then
@@ -382,8 +390,8 @@ function TownMap:draw()
       love.graphics.setColor(1, 1, 1, 1)
       return
     end
-    -- engine/items/town_map.asm:347; fallback dot stays red 0 for PaletteFX (#152)
-    if self.playerLoc and self.blink < 20 then
+    -- engine/items/town_map.asm:347; player marker is static in both Gen 1 and 2
+    if self.playerLoc then
       local x, y = markerXY(self.playerLoc)
       if self.playerSheet then
         love.graphics.draw(self.playerSheet, self.playerQuad, x - 4, y - 3)
@@ -399,7 +407,13 @@ function TownMap:draw()
     -- (8,8), so draw it -4,-4 to enclose the cell (engine/menus/town_map.asm
     -- draws the box cursor CENTERED on the selected location).  Drawing it at
     -- the cell top-left put the square in the frame's top-left quadrant (#152).
-    if selected and self.blink % 16 < 10 then
+    local showCursor = true
+    if GameVersion.generation() == 1 then
+      showCursor = self.blink < 25
+    else
+      showCursor = self.blink % 16 < 10
+    end
+    if selected and showCursor then
       local x, y = markerXY(selected)
       if self.bg.cursor then
         love.graphics.draw(self.bg.cursor, x - 4, y - 4)
@@ -424,7 +438,8 @@ function TownMap:draw()
     for _, loc in ipairs(self.locs) do
       drawSquare(loc)
     end
-    if self.playerLoc and self.blink < 20 then
+    -- player marker is static in both Gen 1 and 2
+    if self.playerLoc then
       -- engine/items/town_map.asm:347; fallback dot stays red 0 for PaletteFX (#152)
       if self.playerSheet then
         love.graphics.setColor(1, 1, 1, 1)
@@ -438,7 +453,13 @@ function TownMap:draw()
                                 self.playerLoc.y * 8 + 2, 4, 4)
       end
     end
-    if selected and self.blink % 16 < 10 then
+    local showCursor = true
+    if GameVersion.generation() == 1 then
+      showCursor = self.blink < 25
+    else
+      showCursor = self.blink % 16 < 10
+    end
+    if selected and showCursor then
       love.graphics.setColor(0, 0, 0, 1)
       love.graphics.rectangle("line", selected.x * 8 + 0.5,
                               selected.y * 8 + 0.5, 7, 7)
@@ -452,12 +473,14 @@ function TownMap:draw()
       local loc = self.locs[first + i]
       if loc then
         local y = 40 + i * 16
-        if first + i == self.sel and self.blink % 16 < 10 then
+        -- cursor in list mode (Fly mode) is static in RBY (LoadTownMap_Fly)
+        if first + i == self.sel then
           Font.drawCode(0xED, 8, y)  -- the "▶" cursor glyph
         end
         Font.draw(loc.name, 24, y)
-        if loc == self.playerLoc and self.blink < 20 then
-          -- blinking marker on the player's current town; force the palette-safe
+        -- player marker is static
+        if loc == self.playerLoc then
+          -- marker on the player's current town; force the palette-safe
           -- dark shade explicitly so the red-channel shade-remap keeps it
           -- visible regardless of Font.draw's leftover color (#152)
           love.graphics.setColor(0, 0, 0, 1)

src/ui/TradeAnim.lua

@@ -27,6 +27,7 @@ local DEFAULT_ART = {
   openCable = "assets/generated/trade/open_cable.png",
   cableHoriz = "assets/generated/trade/cable_horiz.png",
   cableConn = "assets/generated/trade/cable_conn.png",
+  cableSeg = "assets/generated/trade/cable_seg.png",
   cableVert = "assets/generated/trade/cable_vert.png",
   cableCorner = "assets/generated/trade/cable_corner.png",
   cableEnd = "assets/generated/trade/cable_end.png",
@@ -112,6 +113,7 @@ function TradeAnim.new(game, opts)
     openCable = tryImage(art.openCable or DEFAULT_ART.openCable),
     cableHoriz = tryImage(art.cableHoriz or DEFAULT_ART.cableHoriz),
     cableConn = tryImage(art.cableConn or DEFAULT_ART.cableConn),
+    cableSeg = tryImage(art.cableSeg or DEFAULT_ART.cableSeg),
     cableVert = tryImage(art.cableVert or DEFAULT_ART.cableVert),
     cableCorner = tryImage(art.cableCorner or DEFAULT_ART.cableCorner),
     cableEnd = tryImage(art.cableEnd or DEFAULT_ART.cableEnd),
@@ -333,11 +335,19 @@ function TradeAnim:update(dt)
 end
 
 local function drawCableHoriz(self, y, x0, x1)
+  local w = math.max(0, x1 - x0)
+  if w <= 0 then return end
   if self.img.cableHoriz then
-    love.graphics.draw(self.img.cableHoriz, x0 - (self.scx % 8), y)
+    local iw, ih = self.img.cableHoriz:getDimensions()
+    local quad = love.graphics.newQuad(0, 0, math.min(w, iw), ih, iw, ih)
+    love.graphics.draw(self.img.cableHoriz, quad, x0, y)
+  elseif self.img.cableSeg then
+    for x = x0, x1 - 8, 8 do
+      love.graphics.draw(self.img.cableSeg, x, y)
+    end
   else
     love.graphics.setColor(0.2, 0.2, 0.2, 1)
-    love.graphics.rectangle("fill", x0, y + 1, math.max(0, x1 - x0), 6)
+    love.graphics.rectangle("fill", x0, y + 1, w, 6)
     love.graphics.setColor(1, 1, 1, 1)
   end
 end
@@ -422,7 +432,7 @@ function TradeAnim:drawRightGB()
   if self.img.cableCorner then love.graphics.draw(self.img.cableCorner, 112, 32) end
   if self.img.cableVert then
     for i = 1, 4 do
-      love.graphics.draw(self.img.cableVert, 120, 40 + (i - 1) * 8)
+      love.graphics.draw(self.img.cableVert, 112, 40 + (i - 1) * 8)
     end
   end
   if self.img.cableEnd then love.graphics.draw(self.img.cableEnd, 112, 72) end

src/ui/gen2/BattleState.lua

@@ -2707,7 +2707,9 @@ function BattleState:pushCaught(enemy, itemId)
   -- so the contest branch is BELOW them (item_effects.asm:528-546), and
   -- CheckReceivedDex gates the pair (:532-533).
   if not knew and self:hasPokedex() then
+    -- data/text/common_3.asm:285
     self:push({ kind = "message",
+      sfx = "Sfx_SlotMachineStart", waitSfx = true,
       text = self:name(enemy) .. "'s data was newly added to the #DEX." })
     self:push({ kind = "dex-entry", species = enemy.species })
   end

src/ui/gen2/BoxMenu.lua

@@ -47,6 +47,7 @@ local Font = require("src.render.Font")
 local GbcPalette = require("src.render.GbcPalette")
 local Mail = require("src.core.gen2.Mail")
 local Palettes = require("src.world.gen2.Palettes")
+local PartyMenu = require("src.ui.gen2.PartyMenu")
 local Screens = require("src.ui.Screens")
 local Sound = require("src.core.Sound")
 local Unown = require("src.core.gen2.Unown")
@@ -65,6 +66,21 @@ local PIC_X, PIC_Y = 1, 4
 -- 7-size blank tiles per column (engine/gfx/load_pics.asm:342-386).
 local PIC_PAD = { [7] = { 0, 0 }, [6] = { 1, 1 }, [5] = { 1, 2 } }
 
+-- gfx/pc/orange.pal
+local BILLS_PC_ORANGE = {
+  { 255, 123, 0 }, { 189, 99, 0 }, { 123, 58, 0 }, { 0, 0, 0 },
+}
+
+-- PCMonInfo prints the held-item icon at hlcoord 7, 12
+-- (engine/pokemon/bills_pc.asm:1093).
+local ICON_X, ICON_Y = 7, 12
+
+-- $5f at hlcoord 8, 1 and $5e at hlcoord 19, 1, off a PCMailGFX sheet that
+-- starts at $5c (engine/pokemon/bills_pc.asm:957-963).
+local ARROW_ROW = 1
+local ARROW_LEFT = { 3, 8 }
+local ARROW_RIGHT = { 2, 19 }
+
 -- wBillsPC_LoadedBox: 0 is the PARTY, 1..NUM_BOXES are the boxes.  Only the
 -- MOVE screen ever loads box 0; the withdraw and deposit lists are one list
 -- each (BillsPC_BoxName reads the same byte for all three).
@@ -272,6 +288,8 @@ function BoxMenu:beginMove()
     -- to the submenu; here the message holds until a button clears it and the
     -- list comes back, which is the same place the player ends up.
     self.phase = nil
+    -- engine/pokemon/bills_pc.asm:1607
+    self:playSfx("Sfx_Wrong")
     self.message = reason
     return
   end
@@ -299,9 +317,13 @@ end
 function BoxMenu:doWithdraw()
   local ok, result = Boxes.withdraw(self.save, self.boxIndex, self.index)
   if not ok then
+    -- engine/pokemon/bills_pc.asm:1845
+    self:playSfx("Sfx_Wrong")
     self.message = result
     return
   end
+  -- engine/pokemon/bills_pc.asm:1817
+  self:playMonCry(result)
   self.message = nil
   self.phase = nil
   self:clampIndex()
@@ -311,9 +333,13 @@ end
 function BoxMenu:doDeposit()
   local ok, result = Boxes.deposit(self.save, self.index, self.boxIndex)
   if not ok then
+    -- engine/pokemon/bills_pc.asm:1790
+    self:playSfx("Sfx_Wrong")
     self.message = result
     return
   end
+  -- engine/pokemon/bills_pc.asm:1762
+  self:playMonCry(result)
   self.message = nil
   self.phase = nil
   self.index, self.scroll = 1, 0
@@ -486,6 +512,8 @@ function BoxMenu:update(_dt)
       if not ok then
         -- .no_space: `dec [hl]` puts the jumptable back on .PrepInsertCursor,
         -- so the refusal leaves the cursor exactly where it was.
+        -- engine/pokemon/bills_pc.asm:1567
+        self:playSfx("Sfx_Wrong")
         self.message = reason
       else
         self:insertMon()
@@ -528,6 +556,14 @@ function BoxMenu:playSfx(name)
   if sfx and sfx[Sound.resolve(data, name)] then Sound.play(data, name) end
 end
 
+-- PlayMonCry: `call GetCryIndex / jr c, .done` (home/pokemon.asm:113-114)
+function BoxMenu:playMonCry(mon)
+  local data = self.game and self.game.data
+  if not (data and mon and mon.species) or mon.isEgg then return end
+  local cries = data.audio and data.audio.cries
+  if cries and cries[mon.species] then Sound.playCry(data, mon.species) end
+end
+
 -- BillsPC's RELEASE, which the model has always supported and nothing on
 -- screen reached.  The cart asks first and starts the prompt on NO, the way
 -- every irreversible choice in the game does.
@@ -541,6 +577,8 @@ function BoxMenu:askRelease()
     local allowed, refusal = self:checkMailPreventBlackout()
     if not allowed then
       self.phase = nil
+      -- engine/pokemon/bills_pc.asm:1607
+      self:playSfx("Sfx_Wrong")
       self.message = refusal
       return
     end
@@ -568,6 +606,8 @@ function BoxMenu:askRelease()
       self.message = err
       return
     end
+    -- engine/pokemon/bills_pc.asm:1866
+    self:playMonCry(mon)
     self.message = name .. " was released."
     self.phase = nil
     self:clampIndex()
@@ -627,14 +667,31 @@ function BoxMenu:picFor(mon)
   return self:image(path)
 end
 
+-- engine/gfx/cgb_layouts.asm:284-300, engine/pokemon/bills_pc.asm:356-369
+function BoxMenu:panelColors(speciesId, shiny)
+  if self.phase == "submenu" or self.phase == "insert" then
+    return self.palettes
+      and Palettes.monColors(self.palettes, speciesId, shiny)
+  end
+  local gfx = (self.menuGfx or {}).billsPc
+  return (gfx and gfx.orangePalette) or BILLS_PC_ORANGE
+end
+
+-- ClearBox runs before `cp -1 / ret z` (engine/pokemon/bills_pc.asm:1009-1021)
+function BoxMenu:fillPicBlock(colors)
+  local G = love.graphics
+  local blank = colors and GbcPalette.color(colors, 1) or { 255, 255, 255 }
+  G.setColor(blank[1] / 255, blank[2] / 255, blank[3] / 255, 1)
+  G.rectangle("fill", PIC_X * 8, PIC_Y * 8, 7 * 8, 7 * 8)
+  G.setColor(1, 1, 1, 1)
+end
+
 -- PCMonInfo lays the padded pic as one 7x7 block at hlcoord 1, 4
 -- (engine/pokemon/bills_pc.asm:1023-1042), the pad tiles at the palette's 0.
 function BoxMenu:drawPicBlock(image, colors)
   if not image then return end
   local G = love.graphics
-  local blank = colors and GbcPalette.color(colors, 1) or { 255, 255, 255 }
-  G.setColor(blank[1] / 255, blank[2] / 255, blank[3] / 255, 1)
-  G.rectangle("fill", PIC_X * 8, PIC_Y * 8, 7 * 8, 7 * 8)
+  self:fillPicBlock(colors)
 
   local pad = PIC_PAD[math.floor(image:getWidth() / 8)] or PIC_PAD[7]
   G.setColor(1, 1, 1, 1)
@@ -650,12 +707,12 @@ function BoxMenu:drawPicBlock(image, colors)
 end
 
 function BoxMenu:drawPic(mon)
-  local image = self:picFor(mon)
-  if not image then return end
   -- _CGB_BillsPC hands wTempMonDVs to GetPlayerOrMonPalettePointer, so the box
   -- pic takes the shiny row (engine/gfx/cgb_layouts.asm:292-293).
-  local colors = self.palettes
-    and Palettes.monColors(self.palettes, mon.species, mon.shiny)
+  local colors = self:panelColors(mon.species, mon.shiny)
+  local image = self:picFor(mon)
+  -- engine/pokemon/bills_pc.asm:1009-1011
+  if not image then return self:fillPicBlock(colors) end
   self:drawPicBlock(image, colors)
 end
 
@@ -664,17 +721,14 @@ end
 -- with the party list's ICON_EGG standing in for a cache built before that.
 function BoxMenu:drawEggPic(mon)
   local G = love.graphics
-  local colors = self.palettes
-    and Palettes.monColors(self.palettes, "EGG", mon and mon.shiny)
+  local colors = self:panelColors("EGG", mon and mon.shiny)
   local gfx = (self.menuGfx or {}).eggHatch
   local image = self:image(gfx and gfx.egg)
   if image then return self:drawPicBlock(image, colors) end
+  self:fillPicBlock(colors)
   local entry = self.icons and self.icons.icons and self.icons.icons.ICON_EGG
   image = self:image(entry and entry.image)
   if not image then return end
-  local blank = colors and GbcPalette.color(colors, 1) or { 255, 255, 255 }
-  G.setColor(blank[1] / 255, blank[2] / 255, blank[3] / 255, 1)
-  G.rectangle("fill", PIC_X * 8, PIC_Y * 8, 7 * 8, 7 * 8)
   -- The ICON_EGG sheet stacks its frames; the first is the egg at rest.
   local w = entry.width or 16
   local h = math.min(entry.height or 16, image:getHeight())
@@ -694,6 +748,58 @@ function BoxMenu:drawEggPic(mon)
   G.setColor(1, 1, 1, 1)
 end
 
+-- ItemIsMail picks $5c over $5d at hlcoord 7, 12
+-- (engine/pokemon/bills_pc.asm:1079-1094)
+function BoxMenu:drawHeldIcon(mon)
+  local row = PartyMenu.heldMarkerRow(mon)
+  if not row then return end
+  local gfx = (self.menuGfx or {}).billsPc
+  local image = self:image(gfx and gfx.icons)
+  if not image then return end
+  local ok, quad = pcall(love.graphics.newQuad, row * 8, 0, 8, 8,
+    image:getDimensions())
+  if not ok then return end
+  local G = love.graphics
+  G.setColor(1, 1, 1, 1)
+  local function body() G.draw(image, quad, ICON_X * 8, ICON_Y * 8) end
+  local colors = gfx and gfx.palette
+  if colors and GbcPalette.available() then
+    GbcPalette.with(colors, body)
+  else
+    body()
+  end
+  G.setColor(1, 1, 1, 1)
+end
+
+-- _MovePKMNWithoutMail only (engine/pokemon/bills_pc.asm:545, :698)
+function BoxMenu:drawBoxArrows()
+  if self.mode ~= "move" then return end
+  local gfx = (self.menuGfx or {}).billsPc
+  local image = self:image(gfx and gfx.icons)
+  if not image then return end
+  local G = love.graphics
+  local quads = {}
+  for _, arrow in ipairs({ ARROW_LEFT, ARROW_RIGHT }) do
+    local ok, quad = pcall(love.graphics.newQuad, arrow[1] * 8, 0, 8, 8,
+      image:getDimensions())
+    if not ok then return end
+    quads[#quads + 1] = { quad, arrow[2] }
+  end
+  G.setColor(1, 1, 1, 1)
+  local function body()
+    for _, entry in ipairs(quads) do
+      G.draw(image, entry[1], entry[2] * 8, ARROW_ROW * 8)
+    end
+  end
+  local colors = gfx and gfx.palette
+  if colors and GbcPalette.available() then
+    GbcPalette.with(colors, body)
+  else
+    body()
+  end
+  G.setColor(1, 1, 1, 1)
+end
+
 -- The PC does not mark the selected row with a ▶: BillsPC_UpdateSelectionCursor
 -- lays 20 OBJs as a frame *around* the row -- ten tiles wide by two tall, top
 -- left at pixel (71, 25), stepping 16 pixels per row.  Those cursor tiles are
@@ -740,6 +846,7 @@ function BoxMenu:drawPanel()
   -- Textbox at (8,0) with a 10x1 interior and the name at (10,1).
   Chrome.box(8, 0, 12, 3)
   Chrome.print(self:title(), 10, 1)
+  self:drawBoxArrows()
   Chrome.box(8, 2, 12, 12)
   -- BillsPC_RefreshTextboxes overwrites its own top corners with '└'/'┘'
   -- (engine/pokemon/bills_pc.asm:1204-1211) so the list reads as hanging
@@ -793,7 +900,10 @@ function BoxMenu:drawPanel()
         Chrome.print("\xe2\x99\x80", 5, 12)
       end
       Chrome.print(mon.name or mon.species or "?", PIC_X, 14)
+      self:drawHeldIcon(mon)
     end
+  else
+    self:fillPicBlock(self:panelColors())
   end
 
   -- BillsPC_PlaceString: Textbox at (0,15) with a one-row interior, string at
@@ -838,8 +948,7 @@ function BoxMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/CardFlip.lua

@@ -49,9 +49,9 @@
 --                           Textbox at (0,12) with an 18x4 interior
 --
 -- The cart's own art (gfx/card_flip/card_flip_1..3.2bpp.lz and
--- gfx/card_flip/card_flip.tilemap) is NOT in the cache: no `cardFlip` entry is
--- written into menu_gfx.lua yet, so the board draws as labelled cells until one
--- appears.
+-- gfx/card_flip/card_flip.tilemap) is extracted into assets/generated/card_flip/
+-- when the Gold/Silver manifest carries CardFlip*.  Until those files exist,
+-- the board draws as labelled cells.
 
 local Chrome = require("src.ui.gen2.Chrome")
 local CoinCase = require("src.core.gen2.CoinCase")
@@ -616,10 +616,8 @@ local TILEMAP = nil
 local function getCardFlipTilemap()
   if TILEMAP == nil then
     local path = "assets/generated/card_flip/card_flip.tilemap"
-    local f = io.open(path, "rb")
-    if f then
-      local data = f:read("*a")
-      f:close()
+    local data = love and love.filesystem and love.filesystem.read(path)
+    if data and #data > 0 then
       TILEMAP = {}
       for i = 1, #data do
         TILEMAP[i] = string.byte(data, i)
@@ -974,8 +972,7 @@ function CardFlip:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/CenterPcMenu.lua

@@ -313,8 +313,7 @@ function CenterPcMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/ContestMenu.lua

@@ -180,8 +180,7 @@ function ContestMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/CopyrightSplash.lua

@@ -108,8 +108,7 @@ function CopyrightSplash:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
-    math.floor((winH - SCREEN_H * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/Credits.lua

@@ -845,8 +845,7 @@ function Credits:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
-    math.floor((winH - SCREEN_H * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/DecorationMenu.lua

@@ -267,8 +267,7 @@ function DecorationMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/EggHatchAnim.lua

@@ -43,8 +43,6 @@ local EggHatchAnim = {}
 EggHatchAnim.__index = EggHatchAnim
 EggHatchAnim.isOpaque = true
 
-local SCREEN_W, SCREEN_H = 160, 144
-
 -- Hatch_UpdateFrontpicBGMapCenter is called twice with different hlcoords:
 -- the egg sits at (7,4) and the hatchling at (6,3).  Both are `lb bc, 7, 7`
 -- PlaceGraphic boxes, and the pic inside that box has already been padded to
@@ -446,8 +444,7 @@ function EggHatchAnim:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
-    math.floor((winH - SCREEN_H * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/EvolutionAnim.lua

@@ -40,8 +40,6 @@ local EvolutionAnim = {}
 EvolutionAnim.__index = EvolutionAnim
 EvolutionAnim.isOpaque = true
 
-local SCREEN_W, SCREEN_H = 160, 144
-
 -- PrepMonFrontpic's box: hlcoord 7, 2, `lb bc, 7, 7`.
 local PIC_TILE_X, PIC_TILE_Y, PIC_TILES = 7, 2, 7
 
@@ -252,6 +250,8 @@ function EvolutionAnim:setPhase(phase)
         full = self.full,
       })
     end
+    local stack = self.game and self.game.stack
+    if stack and stack.top and stack:top() == self then stack:pop() end
     return
   end
 end
@@ -321,8 +321,18 @@ end
 function EvolutionAnim:update(_dt)
   local input = self.game and self.game.input
   local phase = self.phase
-  -- onDone has already fired; the caller pops this state on its own beat.
-  if phase == "done" then return end
+  -- onDone has already fired.
+  if phase == "done" then
+    local stack = self.game and self.game.stack
+    if stack and stack.top and stack:top() == self then stack:pop() end
+    return
+  end
+
+  if phase == "waitingLearn" then
+    local stack = self.game and self.game.stack
+    if stack and stack.top and stack:top() == self then self:nextLearn() end
+    return
+  end
 
   if phase == "flash" then
     return self:updateFlash(input)
@@ -561,8 +571,7 @@ function EvolutionAnim:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
-    math.floor((winH - SCREEN_H * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/GameFreakPresents.lua

@@ -372,8 +372,7 @@ function GameFreakPresents:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
-    math.floor((winH - SCREEN_H * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/GoldSilverIntro.lua

@@ -1033,8 +1033,7 @@ function GoldSilverIntro:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
-    math.floor((winH - SCREEN_H * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/HallOfFame.lua

@@ -657,8 +657,7 @@ function HallOfFame:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
-    math.floor((winH - SCREEN_H * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/ItemPcMenu.lua

@@ -320,12 +320,15 @@ function ItemPcMenu:leaveDeposit()
 end
 
 function ItemPcMenu:offerToDeposit(id, count)
-  -- .TryDepositItem's `.no_toss` arm is a bare ret: a KEY ITEM or HM stays in
-  -- the bag with no message at all.
-  if self:cantToss(id) then return end
   if (count or 0) < 1 then return end
   local def = self:def(id)
   local name = (def and def.name) or id
+  -- .DepositItem (engine/events/pokecenter_pc.asm:504): an item with no
+  -- quantity is always x1 and never reaches .AskQuantity.
+  if self:cantToss(id) then
+    self:deposit(id, name, 1)
+    return
+  end
   self:askQuantity(count,
     { "How many do you", "want to deposit?" },
     function(qty) self:deposit(id, name, qty) end)
@@ -518,9 +521,10 @@ function ItemPcMenu:drawList()
       local entry = self.rows[i]
       if i == self.listIndex then Chrome.cursor(5, ty) end
       Chrome.print(entry.name, 6, ty)
-      -- PlaceMenuItemQuantity (engine/menus/menu_2.asm:24): the xNN is the
-      -- entry's second line, right-aligned in a blank-padded 2-digit field.
+      -- PlaceMenuItemQuantity (engine/menus/menu_2.asm:18, :24)
+      if not self:cantToss(entry.id) then
         Chrome.print(TIMES .. Chrome.number(entry.count, 2), 7, ty + 1)
+      end
     elseif i == self:listTotal() then
       if i == self.listIndex then Chrome.cursor(5, ty) end
       Chrome.print("CANCEL", 6, ty)
@@ -592,8 +596,7 @@ function ItemPcMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/MailCompose.lua

@@ -341,8 +341,7 @@ function MailCompose:drawWidescreen(winW, winH)
   G.setColor(1, 1, 1, 1)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/MailRead.lua

@@ -94,8 +94,7 @@ function MailRead:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/MainMenu.lua

@@ -218,8 +218,7 @@ function MainMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/NamePick.lua

@@ -225,8 +225,7 @@ function NamePick:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/OptionsMenu.lua

@@ -123,13 +123,11 @@ local ROWS = {
   { label = "ZOOM", key = "zoom", port = true,
     cycle = function(options, delta, game)
       local Zoom = require("src.render.Zoom")
-      local scale = (game and game.world and game.world.fitScale
-        and game.world:fitScale()) or 1
-      local lo, hi = Zoom.offsetRange(scale)
-      local offset = (options.zoom or 0) + delta
-      if offset > hi then offset = lo elseif offset < lo then offset = hi end
-      options.zoom = offset
-      Zoom.offset = offset
+      local scale = Zoom.windowFitScale()
+      if game and game.world and game.world.fitScale then
+        scale = game.world:fitScale()
+      end
+      Zoom.nudgeOptions(options, delta, scale)
     end,
     text = function(options)
       return require("src.render.Zoom").offsetLabel(options.zoom or 0)
@@ -466,8 +464,7 @@ function OptionsMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PackMenu.lua

@@ -16,6 +16,9 @@ local PackGfx = require("src.ui.gen2.PackGfx")
 local Screens = require("src.ui.Screens")
 local Strings = require("src.core.Strings")
 
+-- constants/sfx_constants.asm:3, :28
+local SFX_DEX_FANFARE_50_79, SFX_WRONG = 0, 25
+
 local PackMenu = {}
 PackMenu.__index = PackMenu
 PackMenu.isOpaque = true
@@ -192,6 +195,14 @@ function PackMenu:pocketOf(itemId)
   return (def and def.pocket) or "ITEM"
 end
 
+-- engine/items/tmhm.asm:341
+function PackMenu:tmhmKey(itemId)
+  local def = self.items and self.items[itemId]
+  local n = def and tonumber(def.tmNumber)
+  if n then return n end
+  return 1000 + ((def and tonumber(def.index)) or 0)
+end
+
 -- The name on the row.  An inventory key with no ItemAttributes row behind it
 -- (an older cache, a mod's own item, a driver seeding an id that is not in
 -- items.lua) still has to draw something a person can read, so the id stands
@@ -239,6 +250,14 @@ function PackMenu:rebuild()
       }
     end
   end
+  -- engine/items/tmhm.asm:341
+  if pocket == "TM_HM" then
+    table.sort(rows, function(a, b)
+      local ka, kb = self:tmhmKey(a.id), self:tmhmKey(b.id)
+      if ka ~= kb then return ka < kb end
+      return a.id < b.id
+    end)
+  end
   self.rows = rows
   self.index = math.min(self.index, #rows + 1)
   if self.index < 1 then self.index = 1 end
@@ -359,6 +378,9 @@ function PackMenu:useSelected()
       -- with sound_dex_fanfare_50_79 between them; the PACK's box here holds
       -- all four rows at once, the way OAK_THIS_ISNT_THE_TIME's three fit.
       -- World has already set the decoration's flag and taken the box.
+      if world.playSfxNamed then
+        world:playSfxNamed("Sfx_DexFanfare5079", SFX_DEX_FANFARE_50_79)
+      end
       self.message = { "There was a trophy", "inside!",
                        "{PLAYER} sent the", "trophy home." }
       self:rebuild()
@@ -641,6 +663,11 @@ function PackMenu:openTeachParty(row)
         if id == moveId then allowed = true end
       end
       if not allowed then
+        -- engine/items/tmhm.asm:131
+        local world = game.world
+        if world and world.playSfxNamed then
+          world:playSfxNamed("Sfx_Wrong", SFX_WRONG)
+        end
         if game.say then
           game:say(("%s can't learn %s!"):format(
             require("src.battle.gen2.Mon").displayName(mon), moveName))
@@ -740,7 +767,9 @@ function PackMenu:update(_dt)
 end
 
 -- engine/items/pack.asm:1290 Pack_InterpretJoypad .select
+-- engine/items/tmhm.asm:207 -- the TM/HM pocket's joypad filter drops SELECT.
 function PackMenu:armSwitch()
+  if self:pocket().id == "TM_HM" then return end
   if self:isCancel() then return end
   if not self.rows[self.index] then return end
   self.switching = self.index
@@ -1027,8 +1056,7 @@ function PackMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PartyMenu.lua

@@ -849,8 +849,7 @@ function PartyMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PcMenu.lua

@@ -453,8 +453,7 @@ function PcMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PokedexMenu.lua

@@ -1462,8 +1462,7 @@ function PokedexMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/PrizeMenu.lua

@@ -560,8 +560,7 @@ function PrizeMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/SaveMenu.lua

@@ -228,8 +228,7 @@ function SaveMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/SlotMachine.lua

@@ -39,11 +39,9 @@
 --                         tiles at (2,13),(3,13),(2,14),(3,14) and the ▼ at
 --                         (18,17)
 --
--- The cart's own reel art (gfx/slots/slots_1..3.2bpp.lz plus
--- gfx/slots/slots.tilemap) is NOT in the cache: src/import/RomExtractorGen2.lua
--- writes no `slots` entry into menu_gfx.lua yet.  SlotMachine:sheet() reads one
--- the moment it appears and falls back to labelled cells until then, the same
--- way src/ui/gen2/PackGfx.lua degrades.
+-- Reel art (gfx/slots/slots_1..3.2bpp.lz + slots.tilemap) is extracted into
+-- assets/generated/slots/ when the Gold/Silver manifest carries Slots*LZ.
+-- Until those files exist, drawReels falls back to labelled cells.
 
 local Chrome = require("src.ui.gen2.Chrome")
 local CoinCase = require("src.core.gen2.CoinCase")
@@ -1160,10 +1158,8 @@ local TILEMAP = nil
 local function getTilemap()
   if TILEMAP == nil then
     local path = "assets/generated/slots/gold_slots.tilemap"
-    local f = io.open(path, "rb")
-    if f then
-      local data = f:read("*a")
-      f:close()
+    local data = love and love.filesystem and love.filesystem.read(path)
+    if data and #data > 0 then
       TILEMAP = {}
       for i = 1, #data do
         TILEMAP[i] = string.byte(data, i)
@@ -1175,6 +1171,14 @@ local function getTilemap()
   return TILEMAP or nil
 end
 
+-- Placeholder 2x2 symbol cell used when reel sheets are not in the cache yet.
+local function cell(tx, ty, label)
+  local G = love.graphics
+  G.setColor(0, 0, 0, 1)
+  G.rectangle("line", tx * 8, ty * 8, 16, 16)
+  Chrome.print(label, tx, ty + 1)
+end
+
 function SlotMachine:sheets()
   if self.sheet1 == nil then
     self.sheet1 = TileSheet.new({ path = "assets/generated/slots/gold_slots_1.png", wide = 2, firstTile = 0 })
@@ -1253,6 +1257,9 @@ function SlotMachine:drawReels()
     -- Draw 4 consecutive 2x2 symbols from bottom to top, exactly matching SlotMachine.window
     for row = 0, 3 do
       local sym = strip[a + row + 1]
+      if type(sym) ~= "number" then
+        cell(REEL_X[i], REEL_ROW[row + 1], "?")
+      else
         local py = 64 - (row * 16) + dy
         local pal = GBC_PALS.obj[math.floor(sym / 4)] or GBC_PALS.obj[0]
         s2.palette = pal
@@ -1286,6 +1293,7 @@ function SlotMachine:drawReels()
         end
       end
     end
+  end
 end
 
 function SlotMachine:actorsImage()
@@ -1439,6 +1447,9 @@ function SlotMachine:drawMessage()
       and self.phase == "payoutText" then
     local _, s2 = self:sheets()
     local sym = self.matched
+    if type(sym) ~= "number" then
+      cell(PAYOUT_SYMBOL_X, PAYOUT_SYMBOL_Y, "?")
+    else
       local pal = GBC_PALS.obj[math.floor(sym / 4)] or GBC_PALS.obj[0]
       s2.palette = pal
       local t0 = s2:quad(sym + 0)
@@ -1463,7 +1474,8 @@ function SlotMachine:drawMessage()
           drawWin()
         end
       else
-      cell(PAYOUT_SYMBOL_X, PAYOUT_SYMBOL_Y, SlotMachine.LABELS[self.matched] or "?")
+        cell(PAYOUT_SYMBOL_X, PAYOUT_SYMBOL_Y, SlotMachine.LABELS[sym] or "?")
+      end
     end
   end
 end
@@ -1523,8 +1535,7 @@ function SlotMachine:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/SummaryMenu.lua

@@ -1175,8 +1175,7 @@ function SummaryMenu:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/TradeAnim.lua

@@ -58,8 +58,6 @@ local TradeAnimView = {}
 TradeAnimView.__index = TradeAnimView
 TradeAnimView.isOpaque = true
 
-local SCREEN_W, SCREEN_H = 160, 144
-
 -- PlaceGraphic's box and the stats panel's Textbox, in tiles.
 local PIC_TILE_X, PIC_TILE_Y, PIC_TILES = 7, 2, 7
 local PANEL_X, PANEL_Y = 3, 0
@@ -876,8 +874,7 @@ function TradeAnimView:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - SCREEN_W * scale) / 2),
-    math.floor((winH - SCREEN_H * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/TrainerCard.lua

@@ -437,8 +437,7 @@ function TrainerCard:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/gen2/UnownPuzzle.lua

@@ -580,8 +580,7 @@ function UnownPuzzle:drawWidescreen(winW, winH)
   G.rectangle("fill", 0, 0, winW, winH)
   local scale = Chrome.fitScale(winW, winH)
   G.push()
-  G.translate(math.floor((winW - 160 * scale) / 2),
-    math.floor((winH - 144 * scale) / 2))
+  G.translate(Chrome.fitOrigin(winW, winH, scale))
   G.scale(scale, scale)
   self:drawPanel()
   G.pop()

src/ui/kit/Kit.lua

@@ -749,12 +749,23 @@ function Kit.chip(x, y, w, h, label, on, color, id)
 end
 
 -- A status label with no interaction: outlined text, the "INSTALLED"/"UPDATE"
--- markers on mod rows.
-function Kit.tag(x, y, w, h, label, color)
+-- markers on mod rows.  Pass opts.fill for a solid chip (BETA badges); ink
+-- then defaults to PAL.inverse so the label stays readable on the fill.
+function Kit.tag(x, y, w, h, label, color, opts)
   if not G then return end
+  opts = opts or {}
+  if opts.fill then
+    Theme.fillRounded(x, y, w, h, color or PAL.yellow, 1, h / 2)
+  else
     Theme.strokeRounded(x, y, w, h, color or PAL.line, 0.7, 1)
-  Kit.textCenter("micro", label, x, y + (h - Kit.textHeight("micro")) / 2, w,
-    color or PAL.muted)
+  end
+  local ink = opts.ink or (opts.fill and PAL.inverse) or color or PAL.muted
+  local ty = y + (h - Kit.textHeight("micro")) / 2
+  if opts.bold then
+    Kit.textCenterBold("micro", label, x, ty, w, ink)
+  else
+    Kit.textCenter("micro", label, x, ty, w, ink)
+  end
 end
 
 -- Checkbox row.  Returns (newChecked, changed).

src/update/Check.lua

@@ -58,6 +58,13 @@ function Check.fullAssetName(version, osName, arch, port)
   return fullAssetName(version, osName, arch, port)
 end
 
+-- A legacy Android APK can run a newer downloaded payload while still lacking
+-- the native bridge that installs future APK updates. It needs one manual
+-- package update even when that payload already reports the latest engine.
+function Check.androidNeedsInstallerBootstrap(osName, hasInstaller)
+  return osName == "Android" and not hasInstaller
+end
+
 local CMD = "update_check_cmd"
 local STATE = "update_check_state"
 
@@ -266,13 +273,16 @@ function Check.fullUpdateAction()
   local st = Check.state()
   if st.status ~= "needs_full" and st.status ~= "full_ready" then return nil end
   local osName = love and love.system and love.system.getOS and love.system.getOS() or ""
-  if osName == "Android" and type(love.system.installApk) == "function"
-      and type(st.full) == "table" and type(st.full.url) == "string" then
+  if osName == "Android" and type(st.full) == "table"
+      and type(st.full.url) == "string" then
+    if type(love.system.installApk) == "function" then
       if st.status == "full_ready" and type(st.full.path) == "string" then
         return { label = "Install Android update", kind = "install" }
       end
       return { label = "Download Android update", kind = "download" }
     end
+    return { label = "Update app manually", url = st.full.url }
+  end
   if osName == "iOS" then
     return { label = "Re-sideload app", url =
       "https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json" }

src/update/check_worker.lua

@@ -243,6 +243,12 @@ local function doCheck(target)
     return
   end
 
+  if Check.androidNeedsInstallerBootstrap(osName,
+      type(love.system.installApk) == "function") then
+    postFullRequirement(rel, "native_installer_missing")
+    return
+  end
+
   if compareVersions(rel.version, currentEngine) <= 0 then
     -- We are now running a native shell at least as new as GitHub's latest
     -- release, so a former minShell/payloadHost prompt no longer applies.

src/world/OverworldController.lua

@@ -150,6 +150,21 @@ local function pooledNPC(pool, data, mapId, obj)
 end
 OverworldState.pooledNPC = pooledNPC -- exposed for tests
 
+local function nearestWalkableCell(map, x, y)
+  for r = 1, 8 do
+    for dy = -r, r do
+      for dx = -r, r do
+        if math.abs(dx) == r or math.abs(dy) == r then
+          local nx, ny = x + dx, y + dy
+          if map:inBounds(nx, ny) and map:isWalkableCell(nx, ny) then
+            return nx, ny
+          end
+        end
+      end
+    end
+  end
+end
+
 -- connection hops rendered around the current map: two, so
 -- corner-adjacent maps (connections of connections) don't pop in and
 -- out of the survey zoom at the seams (constants.world.neighborHops)
@@ -414,6 +429,15 @@ function OverworldState:setMap(mapId, x, y, facing, opts)
       table.insert(self.npcs, npc)
     end
   end
+  if opts and opts.via == "boot" and self.map:inBounds(x, y)
+     and not self.map:isWalkableCell(x, y) and not self.map:isWaterCell(x, y) then
+    local rx, ry = nearestWalkableCell(self.map, x, y)
+    if rx then
+      Logger.warn("saved position %s (%d,%d) is not walkable; moved to (%d,%d)",
+                  mapId, x, y, rx, ry)
+      x, y = rx, ry
+    end
+  end
   if self.player then
     self.player.cellX, self.player.cellY = x, y
     self.player.px, self.player.py = x * 16, y * 16
@@ -4113,7 +4137,7 @@ function OverworldState:checkBadgeGate()
         Game.stack:push(TextBox.new(Game,
           (t["_" .. g.failText] or Strings("You don't have the\nBOULDERBADGE yet!"))
           .. (t._Route22GateGuardICantLetYouPassText or ""), function()
-            self:scriptMove(p, "down", 1)
+            self:scriptMove(p, "down", 1, nil, { collide = true })
           end))
         return true
       end
@@ -4141,7 +4165,7 @@ function OverworldState:checkBadgeGate()
         local text = (t["_" .. g.failText] or
                       Strings("You don't have the\n{RAM} yet!")):gsub("{RAM:wNameBuffer}", badgeName)
         Game.stack:push(TextBox.new(Game, text, function()
-          self:scriptMove(p, "down", 1)
+          self:scriptMove(p, "down", 1, nil, { collide = true })
         end))
         return true
       end
@@ -4181,7 +4205,7 @@ function OverworldState:checkForcedMovement()
             function()
               local back = ({ up = "down", down = "up",
                               left = "right", right = "left" })[p.facing]
-              self:scriptMove(p, back, 1)
+              self:scriptMove(p, back, 1, nil, { collide = true })
             end))
           return true
         end
@@ -4222,6 +4246,7 @@ function OverworldState:checkSeafoamCurrent()
         -- push so the B3F stair warps underfoot cannot bounce you back.
         self.forcedWarp = false
         require("src.core.Sound").play(Game.data, "Collision")
+        -- home/overworld.asm:1891
         self:scriptMove(p, "up", c.y == 17 and 2 or 1)
         return true
       end
@@ -4780,9 +4805,10 @@ end
 -- scripted movement
 -- -------------------------------------------------------------------------
 
-function OverworldState:scriptMove(entity, dir, tiles, onDone)
+function OverworldState:scriptMove(entity, dir, tiles, onDone, opts)
   table.insert(self.scriptMoves, {
     entity = entity, dir = dir, remaining = tiles, onDone = onDone,
+    collide = opts and opts.collide or nil,
   })
 end
 
@@ -4822,16 +4848,22 @@ function OverworldState:updateScriptMoves()
         e.moving = true
         e.marching = true
         e.progress = 0
+        mv.remaining = mv.remaining - 1
+      elseif mv.collide
+             and not Collision.canMove(self.map, self.entities, e, mv.dir) then
+        -- home/overworld.asm:1224
+        e.facing = mv.dir
+        mv.remaining = 0
       else
         e.facing = mv.dir
         local tx, ty = Collision.target(e.cellX, e.cellY, mv.dir)
         e.targetX, e.targetY = tx, ty
         e.moving = true
         e.progress = 0
-      end
         mv.remaining = mv.remaining - 1
       end
     end
+  end
   -- march_in_place toggles: re-arm the in-place cycle each time it ends.
   -- Not a scriptMove, so an ambient marcher never trips the input lockout.
   for entity in pairs(self.marchers or {}) do