Merge pull request #912 from bryanthaboi/dev

launcher update, switch and xbox updates

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -10,8 +10,6 @@ name: ci
 # The T3 content tier asserts Pokemon Red facts; scripts/test.sh detects
 # data/generated/ is absent and skips it rather than failing.
 #
-# Runs alongside release.yml, which is untouched by this file.
-
 on:
   push:
     # Integration branch + release branch. PRs already run via pull_request
@@ -24,12 +22,360 @@ concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
+  ios-changes:
+    name: detect iOS changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(mobile/ios/|scripts/build_ios\.sh$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  ios-build:
+    name: iOS build
+    needs: ios-changes
+    if: needs.ios-changes.outputs.changed == 'true'
+    runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
+    outputs:
+      ipa_url: ${{ steps.upload-ipa.outputs.artifact-url }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: import signing certificate
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        run: |
+          keychain_path="$RUNNER_TEMP/gen1recomp-ci-signing.keychain-db"
+          ci_dir="${POKEMON_CI_DIR:-$HOME/.config/pokemon-ci}"
+          p12="$ci_dir/signing.p12"
+          passfile="$ci_dir/signing.pass"
+          [ -f "$p12" ] && [ -f "$passfile" ] || exit 1
+          p12pw="$(cat "$passfile")"
+          kcpw="$(openssl rand -base64 24)"
+          echo "::add-mask::$kcpw"
+          security delete-keychain "$keychain_path" 2>/dev/null || true
+          security create-keychain -p "$kcpw" "$keychain_path"
+          security set-keychain-settings "$keychain_path"
+          security unlock-keychain -p "$kcpw" "$keychain_path"
+          security import "$p12" -P "$p12pw" -k "$keychain_path" -T /usr/bin/codesign -T /usr/bin/security
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$kcpw" "$keychain_path" >/dev/null
+          existing="$(security list-keychains -d user | sed -e 's/^[[:space:]]*//' -e 's/"//g')"
+          security list-keychains -d user -s "$keychain_path" $existing
+      - name: install xcbeautify
+        run: brew list xcbeautify >/dev/null 2>&1 || brew install xcbeautify
+      - name: build iOS release
+        env:
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
+        run: |
+          if [ "$CANONICAL_REPOSITORY" = true ]; then
+            scripts/build_ios.sh --fetch --device --release
+          else
+            scripts/build_ios.sh --fetch --release
+          fi
+      - name: upload iOS release artifact
+        id: upload-ipa
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-ios-ipa
+          path: dist/ios/gen1recomp.ipa
+          if-no-files-found: error
+          retention-days: 7
+      - name: clean up signing keychain
+        if: ${{ always() && github.repository == 'bryanthaboi/gen1recomp' }}
+        run: security delete-keychain "$RUNNER_TEMP/gen1recomp-ci-signing.keychain-db" 2>/dev/null || true
+
+  switch-changes:
+    name: detect Switch changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(scripts/build_switch\.sh$|scripts/switch/|docs/switch-.*\.md$|tests/switch_ci_workflows_test\.lua$|tests/switch_transfer_docs_test\.lua$|\.github/workflows/(ci|release|switch-artifact-comment)\.yml$|src/core/(NxAssetOverlay|Platform|GameVersion)\.lua$|src/import/CacheFs\.lua$|tests/engine/(assets_version_fallback|nx_generated_guard|nx_yellow_boot|switch_diagnostics)_test\.lua$|tests/engine/platform_nx)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  switch-selftest:
+    name: Switch offline selftest
+    needs: switch-changes
+    if: needs.switch-changes.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: install luajit
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Switch offline selftest
+        run: bash scripts/switch/selftest_build_switch.sh
+      - name: verify_payload self-test
+        run: bash scripts/switch/verify_payload.sh --self-test
+      - name: Switch CI workflow content gate
+        run: luajit tests/switch_ci_workflows_test.lua
+      - name: Switch transfer docs content gate
+        run: luajit tests/switch_transfer_docs_test.lua
+      # NX runtime regressions gate this job via switch-changes; run the NX
+      # engine suites here too so a PR touching them gets feedback on the
+      # fork-safe ubuntu runner before the self-hosted Mac build.
+      - name: NX engine suites (headless)
+        run: |
+          luajit tests/engine/assets_version_fallback_test.lua
+          luajit tests/engine/nx_generated_guard_test.lua
+          luajit tests/engine/nx_yellow_boot_test.lua
+
+  switch-build:
+    name: Switch fused build
+    needs: [switch-changes, switch-selftest]
+    if: |
+      always()
+      && needs.switch-changes.outputs.changed == 'true'
+      && needs.switch-selftest.result == 'success'
+      && github.repository == 'bryanthaboi/gen1recomp'
+      && (github.event_name != 'pull_request'
+          || github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ["self-hosted", "macOS"]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build Switch fused NRO
+        run: |
+          set -euo pipefail
+          VER="$(printf '%s' "$GITHUB_SHA" | cut -c1-7)"
+          scripts/build_switch.sh --fetch --fused --version "$VER"
+          echo "SWITCH_VER=$VER" >> "$GITHUB_ENV"
+      - name: upload Switch NRO artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-switch-nro
+          path: |
+            dist/switch/gen1recomp-${{ env.SWITCH_VER }}-switch.nro
+            dist/switch/gen1recomp-${{ env.SWITCH_VER }}-switch.nro.sha256
+          if-no-files-found: error
+          retention-days: 7
+
+  xbox-uwp-changes:
+    name: detect Xbox UWP changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(ports/uwp/|scripts/build_xbox_uwp\.sh$|scripts/xbox-uwp/|scripts/pack_love\.sh$|\.github/workflows/(ci|release)\.yml$|src/core/Platform\.lua$|src/import/(CacheFs|LauncherView|RomImporter)\.lua$|src/update/Check\.lua$|tests/engine/(platform_nx|uwp_baseroms|uwp_native_picker)_test\.lua$|tests/rom_importer_double_pick_test\.lua$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  xbox-uwp-selftest:
+    name: Xbox UWP offline selftest
+    needs: xbox-uwp-changes
+    if: needs.xbox-uwp-changes.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Xbox UWP offline selftest
+        run: bash scripts/xbox-uwp/selftest_build_xbox_uwp.sh
+      - name: Build shared payload
+        run: |
+          scripts/pack_love.sh \
+            --output .bazinga/work/ci-game.love \
+            --listing .bazinga/work/ci-love-listing.txt \
+            --version 0.0.0
+      - name: Upload shared payload
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp-payload
+          path: .bazinga/work/ci-game.love
+          if-no-files-found: error
+          retention-days: 1
+
+  xbox-uwp-build:
+    name: Xbox UWP build
+    needs: [xbox-uwp-changes, xbox-uwp-selftest]
+    if: |
+      always()
+      && needs.xbox-uwp-changes.outputs.changed == 'true'
+      && needs.xbox-uwp-selftest.result == 'success'
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-xbox-uwp-payload
+          path: .bazinga/work
+      - name: Build Xbox UWP package
+        shell: bash
+        run: |
+          bash scripts/build_xbox_uwp.sh \
+            --release \
+            --version 0.0.0 \
+            --game-love .bazinga/work/ci-game.love
+      - name: Upload Xbox UWP package
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp
+          path: |
+            dist/xbox-uwp/gen1recomp-0.0.0-xbox-uwp.zip
+            dist/xbox-uwp/gen1recomp-0.0.0-xbox-uwp.zip.sha256
+          if-no-files-found: error
+          retention-days: 7
+
+  linux-arm64-changes:
+    name: detect Linux arm64 changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(scripts/build_linux_arm64\.sh$|scripts/linux-arm64/|scripts/pack_love\.sh$|docs/linux-arm64-build\.md$|\.github/workflows/(ci|release)\.yml$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  linux-arm64-selftest:
+    name: Linux arm64 offline selftest
+    needs: linux-arm64-changes
+    if: needs.linux-arm64-changes.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Deliberately on x86_64: everything this gate checks (pins, the
+      # host-arch guard, the dependency exclude list, the AppRun fusion
+      # contract) is answerable without a container or an aarch64 machine,
+      # so the slow native job below only ever starts on a sane tree.
+      - name: Linux arm64 offline selftest
+        run: bash scripts/linux-arm64/selftest_build_linux_arm64.sh
+
+  linux-arm64-build:
+    name: Linux arm64 AppImage build
+    needs: [linux-arm64-changes, linux-arm64-selftest]
+    if: |
+      always()
+      && needs.linux-arm64-changes.outputs.changed == 'true'
+      && needs.linux-arm64-selftest.result == 'success'
+    # No fork restriction, unlike switch-build: this needs no secrets and no
+    # self-hosted hardware, just GitHub's free arm64 runner for public repos,
+    # so contributors get the same coverage on their own PRs.
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build the aarch64 AppImage
+        run: |
+          set -euo pipefail
+          scripts/build_linux_arm64.sh --version 0.0.0
+      - name: Verify the AppImage is self-contained and bullseye-compatible
+        run: |
+          set -euo pipefail
+          image="dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage"
+
+          # --appimage-extract needs no FUSE, so this works on a runner
+          # without /dev/fuse and still exercises the real payload.
+          "$image" --appimage-extract >/dev/null
+          for required in AppRun bin/love game.love lib/liblove-11.5.so; do
+            [ -e "squashfs-root/$required" ] \
+              || { echo "::error::AppImage is missing $required"; exit 1; }
+          done
+
+          # Every bundled object must resolve once AppRun's LD_LIBRARY_PATH is
+          # applied; an unresolved soname here is a user-visible launch crash.
+          #
+          # This runs on a HEADLESS runner on purpose, and that is the point.
+          # The first version of this build bundled Debian's SDL2, which
+          # hard-links libpulse/libasound/libX11/libwayland, so it only ever
+          # started on a full desktop -- a bare runner is what exposed it.
+          missing="$(LD_LIBRARY_PATH="$PWD/squashfs-root/lib" \
+            ldd squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
+            | grep 'not found' || true)"
+          [ -z "$missing" ] || { echo "::error::unresolved deps:"; echo "$missing"; exit 1; }
+
+          # Nothing may hard-link a driver, session or audio-stack library:
+          # those must be reached through dlopen so the AppImage runs on a box
+          # with only ALSA, only Wayland, or only KMSDRM.
+          linked="$(for f in squashfs-root/bin/love squashfs-root/lib/*.so*; do
+            objdump -p "$f" 2>/dev/null | awk '/NEEDED/{print $2}'
+          done | sort -u | grep -E '^lib(pulse|asound|X11|wayland|GL|EGL|drm|gbm|xcb|cairo|sndio|dbus)' || true)"
+          [ -z "$linked" ] \
+            || { echo "::error::these must be dlopened, not linked:"; echo "$linked"; exit 1; }
+
+          # The whole point of compiling on bullseye. If a future change moves
+          # the builder to a newer base, the glibc floor silently rises and
+          # every user on an older distro gets "GLIBC_2.xx not found" -- catch
+          # it here instead of in a release.
+          floor="$(objdump -T squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
+            | grep -o 'GLIBC_[0-9.]*' | sort -V | tail -1)"
+          echo "highest required glibc symbol version: $floor"
+          [ -n "$floor" ] \
+            || { echo "::error::found no versioned glibc symbols -- objdump read nothing"; exit 1; }
+          highest="$(printf '%s\n' "$floor" "GLIBC_2.31" | sort -V | tail -1)"
+          [ "$highest" = "GLIBC_2.31" ] \
+            || { echo "::error::AppImage requires $floor, above the bullseye 2.31 floor"; exit 1; }
+      - name: Upload the AppImage
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-linux-arm64
+          path: |
+            dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage
+            dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage.sha256
+          if-no-files-found: error
+          retention-days: 7
+
   headless:
     name: headless suites (no ROM)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       # LuaJIT, not lua5.4: LOVE 11.x embeds LuaJIT 2.1 and the engine is
       # written to Lua 5.1 semantics, so CI must run the interpreter the
@@ -47,7 +393,7 @@ jobs:
     name: fixture dataset integrity
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - run: sudo apt-get update && sudo apt-get install -y luajit
       - run: python3 -m pip install --upgrade pillow
 
@@ -89,7 +435,7 @@ jobs:
     name: screenshot differ (capture not yet wired)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - run: python3 -m pip install --upgrade pillow
 
       # 21-testing-and-ci §"Testing & acceptance criteria": compare_shots
@@ -137,7 +483,7 @@ jobs:
     name: mod lint (no ROM-derived content)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       # the MK305 dump check key-diffs shipped tables through luajit, and
       # modkit treats a missing interpreter as a fatal MK100 -- without

.github/workflows/ios-artifact-comment.yml

@@ -0,0 +1,55 @@
+name: iOS artifact comment
+
+on:
+  workflow_run:
+    workflows: [ci]
+    types: [completed]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  comment:
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - id: artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name }}
+        run: |
+          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp-ios-ipa") | .id')"
+          [ -n "$artifact_id" ] || exit 0
+          head_owner="${HEAD_REPOSITORY%%/*}"
+          pr_number="$(gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$head_owner:$HEAD_BRANCH" --jq '.[0].number // empty')"
+          [ -n "$pr_number" ] || exit 0
+          echo "artifact_url=https://github.com/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts/$artifact_id" >> "$GITHUB_OUTPUT"
+          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
+      # Upsert via comment-tag only — do not delete-all bot comments (clobbers Switch).
+      - name: Get build info
+        id: build-info
+        env:
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          commit_hash="$(printf '%s' "$HEAD_SHA" | cut -c1-7)"
+          build_time="$(date "+%Y-%m-%d %H:%M:%S")"
+          echo "hash=$commit_hash" >> "$GITHUB_OUTPUT"
+          echo "time=$build_time" >> "$GITHUB_OUTPUT"
+      - name: comment iOS artifact
+        if: steps.artifact.outputs.pr_number != ''
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          message: |
+            [gen1recomp.ipa](${{ steps.artifact.outputs.artifact_url }})
+
+            **Commit**: [#${{ steps.build-info.outputs.hash }}](https://github.com/${{ github.event.workflow_run.head_repository.full_name }}/commit/${{ github.event.workflow_run.head_sha }})
+            **Build Time**: `${{ steps.build-info.outputs.time }}`
+
+            <sub>This comment was automatically generated. [View workflow run](https://github.com/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }})</sub>
+          pr-number: ${{ steps.artifact.outputs.pr_number }}
+          comment-tag: ios-build-result
+          github-token: ${{ github.token }}

.github/workflows/release.yml

@@ -1,8 +1,9 @@
 name: Release
 
 # Builds the macOS, Windows, and Linux desktop apps, an Android APK, an iOS
-# IPA, and the Anbernic RG34XXSP (Stock OS 64-bit MOD / PortMaster) port on
-# the self-hosted Mac runner, and publishes them as a GitHub Release.
+# IPA, a Nintendo Switch SD-ready zip (experimental), Xbox UWP, and the Anbernic
+# RG34XXSP (Stock OS 64-bit MOD / PortMaster) port, then publishes them as a
+# GitHub Release.
 #
 # Versioning:
 #   - First ever release is 0.1.0.
@@ -24,6 +25,7 @@ on:
     paths-ignore:
       - '.github/**'
       - '**.md'
+      - 'mobile/ios/app-repo.json'
   workflow_dispatch:
     inputs:
       version:
@@ -41,22 +43,17 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  release:
-    runs-on: [self-hosted, macOS]
-
+  version:
+    name: determine release version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+      tag: ${{ steps.ver.outputs.tag }}
     steps:
-      # The self-hosted runner lives under the machine owner's home
-      # directory; mask it first so absolute paths in every later step's
-      # output show up as *** in the public workflow logs.
-      - name: Mask runner paths
-        run: echo "::add-mask::$HOME"
-
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           fetch-tags: true
-
       - name: Determine version
         id: ver
         env:
@@ -64,7 +61,6 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
-
           semver_re='^[0-9]+\.[0-9]+\.[0-9]+$'
 
           # 1) Explicit override from a manual run.
@@ -94,7 +90,6 @@ jobs:
               | grep -E "$semver_re" \
               | sort -t. -k1,1n -k2,2n -k3,3n \
               | tail -1 || true)"
-
             if [ -z "$latest" ]; then
               version="0.1.0"
               echo "No existing release tag; starting at $version"
@@ -122,11 +117,159 @@ jobs:
             echo "::error::Release $tag already exists. Pick a different version."
             exit 1
           fi
-
           echo "version=$version" >> "$GITHUB_OUTPUT"
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
 
+  love-payload:
+    name: build release game.love
+    needs: version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build shared payload
+        run: |
+          scripts/pack_love.sh \
+            --output dist/payload/game.love \
+            --listing dist/payload/love-listing.txt \
+            --version "${{ needs.version.outputs.version }}"
+      - name: Upload shared payload
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-release-love
+          path: dist/payload/game.love
+          if-no-files-found: error
+          retention-days: 1
+
+  linux-arm64:
+    name: build Linux arm64 AppImage
+    needs: [version, love-payload]
+    # GitHub's free arm64 runner for public repos. It has to be arm64: the
+    # AppImage compiles LÖVE natively inside a Debian bullseye arm64
+    # container, and the qemu-emulated alternative takes hours.
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-release-love
+          path: .bazinga/work
+      - name: Build Linux arm64 AppImage
+        run: |
+          set -euo pipefail
+          scripts/build_linux_arm64.sh \
+            --version "${{ needs.version.outputs.version }}" \
+            --game-love .bazinga/work/game.love
+      - name: Upload Linux arm64 release
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-linux-arm64-release
+          path: |
+            dist/linux-arm64/gen1recomp-${{ needs.version.outputs.version }}-linux-arm64.AppImage
+            dist/linux-arm64/gen1recomp-${{ needs.version.outputs.version }}-linux-arm64.AppImage.sha256
+          if-no-files-found: error
+          retention-days: 1
+
+  xbox-uwp:
+    name: build Xbox UWP release
+    needs: [version, love-payload]
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-release-love
+          path: .bazinga/work
+      - name: Prepare signing certificate
+        shell: pwsh
+        env:
+          CERTIFICATE_BASE64: ${{ secrets.XBOX_UWP_SIGNING_CERTIFICATE }}
+          CERTIFICATE_PASSWORD: ${{ secrets.XBOX_UWP_SIGNING_PASSWORD }}
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
+        run: |
+          if ($env:CANONICAL_REPOSITORY -eq 'true' -and
+              [string]::IsNullOrWhiteSpace($env:CERTIFICATE_BASE64)) {
+              throw 'XBOX_UWP_SIGNING_CERTIFICATE is not configured.'
+          }
+          if ([string]::IsNullOrWhiteSpace($env:CERTIFICATE_BASE64)) {
+              "UWP_PUBLISHER=CN=Gen1Recomp" | Out-File $env:GITHUB_ENV -Append
+              exit 0
+          }
+          $pfx = Join-Path $env:RUNNER_TEMP 'gen1recomp-uwp.pfx'
+          [IO.File]::WriteAllBytes($pfx, [Convert]::FromBase64String($env:CERTIFICATE_BASE64))
+          $flags = [Security.Cryptography.X509Certificates.X509KeyStorageFlags]::EphemeralKeySet
+          $cert = [Security.Cryptography.X509Certificates.X509Certificate2]::new(
+              $pfx, $env:CERTIFICATE_PASSWORD, $flags)
+          $cer = Join-Path $env:RUNNER_TEMP 'gen1recomp-uwp.cer'
+          [IO.File]::WriteAllBytes(
+              $cer,
+              $cert.Export([Security.Cryptography.X509Certificates.X509ContentType]::Cert))
+          Import-Certificate -FilePath $cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople | Out-Null
+          "UWP_PFX=$pfx" | Out-File $env:GITHUB_ENV -Append
+          "UWP_CERT_THUMBPRINT=$($cert.Thumbprint)" | Out-File $env:GITHUB_ENV -Append
+          "UWP_PUBLISHER=$($cert.Subject)" | Out-File $env:GITHUB_ENV -Append
+      - name: Build Xbox UWP package
+        shell: bash
+        run: |
+          bash scripts/build_xbox_uwp.sh \
+            --release \
+            --version "${{ needs.version.outputs.version }}" \
+            --publisher "$UWP_PUBLISHER" \
+            --game-love .bazinga/work/game.love
+      - name: Sign and stage Xbox UWP release
+        shell: pwsh
+        env:
+          CERTIFICATE_PASSWORD: ${{ secrets.XBOX_UWP_SIGNING_PASSWORD }}
+        run: |
+          if (-not $env:UWP_PFX) {
+              exit 0
+          }
+          scripts/xbox-uwp/stage_release.ps1 `
+            -Version '${{ needs.version.outputs.version }}' `
+            -Configuration Release `
+            -BuildInfo .bazinga/work/xbox-uwp-build-info.json `
+            -CertificatePath $env:UWP_PFX `
+            -CertificatePassword $env:CERTIFICATE_PASSWORD
+      - name: Upload Xbox UWP release
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp-release
+          path: |
+            dist/xbox-uwp/gen1recomp-${{ needs.version.outputs.version }}-xbox-uwp.zip
+            dist/xbox-uwp/gen1recomp-${{ needs.version.outputs.version }}-xbox-uwp.zip.sha256
+          if-no-files-found: error
+          retention-days: 1
+      - name: Remove signing certificate
+        if: always()
+        shell: pwsh
+        run: |
+          if ($env:UWP_CERT_THUMBPRINT) {
+              Remove-Item "Cert:\LocalMachine\TrustedPeople\$env:UWP_CERT_THUMBPRINT" -ErrorAction SilentlyContinue
+          }
+          if ($env:UWP_PFX) {
+              Remove-Item $env:UWP_PFX -Force -ErrorAction SilentlyContinue
+          }
+
+  release:
+    needs: [version, xbox-uwp, linux-arm64]
+    runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
+
+    steps:
+      # The self-hosted runner lives under the machine owner's home
+      # directory; mask it first so absolute paths in every later step's
+      # output show up as *** in the public workflow logs.
+      - name: Mask runner paths
+        run: echo "::add-mask::$HOME"
+
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
       - name: Import signing certificate into a temporary keychain
+        if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
           set -euo pipefail
           KEYCHAIN_PATH="$RUNNER_TEMP/pokemon-signing.keychain-db"
@@ -169,12 +312,12 @@ jobs:
           # notarize separately below so it uses secret credentials, not a
           # login-keychain profile. "all" also builds the Linux AppImage,
           # which needs no signing/notarization.
-          scripts/build.sh all --version "${{ steps.ver.outputs.version }}" --no-notarize
+          scripts/build.sh all --version "${{ needs.version.outputs.version }}" --no-notarize
 
       - name: Build Android
         run: |
           set -euo pipefail
-          scripts/build_android.sh --version "${{ steps.ver.outputs.version }}"
+          scripts/build_android.sh --version "${{ needs.version.outputs.version }}"
 
       - name: Install xcbeautify
         run: |
@@ -182,22 +325,38 @@ jobs:
           brew list xcbeautify >/dev/null 2>&1 || brew install xcbeautify
 
       - name: Build iOS
+        env:
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
         run: |
           set -euo pipefail
-          # Device Release IPA; signs with the Apple Development identity on
-          # the runner (auto team detection). Users on other Apple IDs still
-          # re-sign or build via docs/ios-install.md.
-          scripts/build_ios.sh --fetch --device --release \
-            --version "${{ steps.ver.outputs.version }}"
+          if [ "$CANONICAL_REPOSITORY" = true ]; then
+            scripts/build_ios.sh --fetch --device --release \
+              --version "${{ needs.version.outputs.version }}"
+          else
+            scripts/build_ios.sh --fetch --release \
+              --version "${{ needs.version.outputs.version }}"
+          fi
+
+      - name: Build Switch
+        run: |
+          set -euo pipefail
+          # Hard-fail gate: Switch ships with every release (never soft-fail).
+          # PR CI is path-gated (ubuntu selftest + canonical fused); release
+          # always builds Switch regardless of which files changed.
+          # Needs native switch-tools (nacptool/elf2nro) and/or Docker on the
+          # Mac self-hosted runner; see docs/switch-build.md.
+          scripts/build_switch.sh --fetch --fused \
+            --version "${{ needs.version.outputs.version }}"
 
       - name: Build Anbernic RG34XXSP port
         run: |
           set -euo pipefail
           # Self-contained aarch64 PortMaster-style pack; pulls the LÖVE 11.5
           # runtime from PortMaster-GUI, so it needs no signing/notarization.
-          ./build-rg34xxsp.sh --version "${{ steps.ver.outputs.version }}"
+          ./build-rg34xxsp.sh --version "${{ needs.version.outputs.version }}"
 
       - name: Notarize & staple macOS app
+        if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
           set -euo pipefail
           ci_dir="${POKEMON_CI_DIR:-$HOME/.config/pokemon-ci}"
@@ -231,17 +390,41 @@ jobs:
           ditto -c -k --sequesterRsrc --keepParent "$app" "$zip"
           echo "Notarized + stapled ✓"
 
+      - name: Download Xbox UWP release
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-xbox-uwp-release
+          path: dist/xbox-uwp
+
+      - name: Download Linux arm64 release
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-linux-arm64-release
+          path: dist/linux-arm64
+
       - name: Stage release assets
+        if: github.repository == 'bryanthaboi/gen1recomp'
         id: assets
         run: |
           set -euo pipefail
-          v="${{ steps.ver.outputs.version }}"
+          v="${{ needs.version.outputs.version }}"
           outdir="dist/release"
           rm -rf "$outdir"
           mkdir -p "$outdir"
           cp "dist/mac/gen1recomp-macos.zip" "$outdir/gen1recomp-${v}-macos.zip"
           cp "dist/win/gen1recomp-win64.zip" "$outdir/gen1recomp-${v}-windows.zip"
           cp "dist/linux/gen1recomp-linux.zip" "$outdir/gen1recomp-${v}-linux.zip"
+
+          # arm64 desktop Linux (Raspberry Pi, Armbian, arm64 VMs). Built on
+          # its own runner because LÖVE publishes no aarch64 binary and the
+          # AppImage has to be compiled natively; ships as a runnable
+          # AppImage rather than a zip so `chmod +x && ./it` just works.
+          arm64_appimage="dist/linux-arm64/gen1recomp-${v}-linux-arm64.AppImage"
+          [ -f "$arm64_appimage" ] || { echo "::error::$arm64_appimage not found (expected from the linux-arm64 job)"; exit 1; }
+          cp "$arm64_appimage" "$outdir/gen1recomp-${v}-linux-arm64.AppImage"
+          chmod +x "$outdir/gen1recomp-${v}-linux-arm64.AppImage"
           apk="$(find dist/android/debug -name '*.apk' | head -1)"
           [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
           cp "$apk" "$outdir/gen1recomp-${v}-android.apk"
@@ -250,6 +433,16 @@ jobs:
           [ -f "$ipa" ] || { echo "::error::$ipa not found (expected from scripts/build_ios.sh --device)"; exit 1; }
           cp "$ipa" "$outdir/gen1recomp-${v}-ios.ipa"
 
+          swzip="dist/switch/gen1recomp-${v}-switch.zip"
+          [ -f "$swzip" ] || { echo "::error::$swzip not found (expected from scripts/build_switch.sh --fused → pack_sd_zip.sh)"; exit 1; }
+          cp "$swzip" "$outdir/gen1recomp-${v}-switch.zip"
+          # Local fused .nro stays under dist/switch/ for PR CI / debug; release
+          # publishes the SD-ready zip only.
+
+          uwp="dist/xbox-uwp/gen1recomp-${v}-xbox-uwp.zip"
+          [ -f "$uwp" ] || { echo "::error::$uwp not found (expected from the Xbox UWP job)"; exit 1; }
+          cp "$uwp" "$outdir/gen1recomp-${v}-xbox-uwp.zip"
+
           # Anbernic handheld port (suffix names the CFW it targets, so a
           # future RG35XX/other-CFW pack can ship alongside it).
           rg34="dist/rg34xxsp/gen1recomp-rg34xxsp-stockos64-mod.zip"
@@ -271,12 +464,13 @@ jobs:
           cat "$outdir/sha256sums.txt"
 
       - name: Publish GitHub Release
+        if: github.repository == 'bryanthaboi/gen1recomp'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
-          v="${{ steps.ver.outputs.version }}"
-          tag="${{ steps.ver.outputs.tag }}"
+          v="${{ needs.version.outputs.version }}"
+          tag="${{ needs.version.outputs.tag }}"
 
           # Issues this release closes. Three sources, deduped by number:
           #   1. GitHub's own "closing issues" links on every PR whose
@@ -360,22 +554,94 @@ jobs:
           fi
           printf 'Release notes:\n%s\n' "$notes"
 
+          release_files=(
+            "dist/release/gen1recomp-${v}-macos.zip"
+            "dist/release/gen1recomp-${v}-windows.zip"
+            "dist/release/gen1recomp-${v}-linux.zip"
+            "dist/release/gen1recomp-${v}-linux-arm64.AppImage"
+            "dist/release/gen1recomp-${v}-android.apk"
+            "dist/release/gen1recomp-${v}-ios.ipa"
+            "dist/release/gen1recomp-${v}-switch.zip"
+            "dist/release/gen1recomp-${v}-xbox-uwp.zip"
+            "dist/release/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip"
+            "dist/release/gen1recomp-${v}.love"
+            "dist/release/sha256sums.txt"
+          )
+
           gh release create "$tag" \
             --target "$GITHUB_SHA" \
             --title "$v" \
             --notes "$notes" \
-            "dist/release/gen1recomp-${v}-macos.zip" \
-            "dist/release/gen1recomp-${v}-windows.zip" \
-            "dist/release/gen1recomp-${v}-linux.zip" \
-            "dist/release/gen1recomp-${v}-android.apk" \
-            "dist/release/gen1recomp-${v}-ios.ipa" \
-            "dist/release/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip" \
-            "dist/release/gen1recomp-${v}.love" \
-            "dist/release/sha256sums.txt"
+            "${release_files[@]}"
 
           echo "Published release $tag"
 
+      - name: Update iOS app repository
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        run: |
+          set -euo pipefail
+          v="${{ needs.version.outputs.version }}"
+          ipa="dist/release/gen1recomp-${v}-ios.ipa"
+          app_repo="mobile/ios/app-repo.json"
+          [ -f "$ipa" ] || { echo "::error::$ipa not found"; exit 1; }
+          [ -f "$app_repo" ] || { echo "::error::$app_repo not found"; exit 1; }
+
+          date="$(date -u +"%Y-%m-%d")"
+          size="$(wc -c < "$ipa" | tr -d '[:space:]')"
+          download_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/v${v}/gen1recomp-${v}-ios.ipa"
+          localized_description="Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke"
+          release_notes="$(GH_TOKEN="${{ github.token }}" gh release view "v${v}" --json body --jq '.body // ""' 2>/dev/null || true)"
+          if [ -n "$release_notes" ]; then
+            localized_description="$release_notes"
+          fi
+          entry="$(jq -n \
+            --arg version "$v" \
+            --arg date "$date" \
+            --arg download_url "$download_url" \
+            --arg localized_description "$localized_description" \
+            --argjson size "$size" \
+            '{version: $version, date: $date, size: $size, downloadURL: $download_url, localizedDescription: $localized_description}')"
+
+          if jq -e --arg version "$v" \
+            'any(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions[]?; .version == $version)' \
+            "$app_repo" >/dev/null; then
+            jq --arg version "$v" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= map(if .version == $version then $entry else . end)' \
+              "$app_repo" > "$app_repo.tmp"
+          else
+            jq --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= [$entry] + .' \
+              "$app_repo" > "$app_repo.tmp"
+          fi
+          mv "$app_repo.tmp" "$app_repo"
+
+      # main is PR-only for everyone except deploy keys (the "main protection"
+      # ruleset's bypass actor), so this push must authenticate with the
+      # RELEASE_DEPLOY_KEY deploy key over SSH; the workflow's GITHUB_TOKEN
+      # would be rejected by the branch protection.
+      - name: Commit iOS app repository
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        env:
+          DEPLOY_KEY: ${{ secrets.RELEASE_DEPLOY_KEY }}
+        run: |
+          set -euo pipefail
+          git add mobile/ios/app-repo.json
+          if git diff --cached --quiet; then
+            echo "app-repo.json unchanged; nothing to push"
+            exit 0
+          fi
+          key="$RUNNER_TEMP/release-deploy-key"
+          printf '%s\n' "$DEPLOY_KEY" > "$key"
+          chmod 600 "$key"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "chore(ios): update app-repo.json [skip ci]"
+          git -c core.sshCommand="ssh -i $key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \
+            push "git@github.com:${GITHUB_REPOSITORY}.git" "HEAD:${GITHUB_REF_NAME}"
+          rm -f "$key"
+
       - name: Clean up signing keychain
-        if: always()
+        if: ${{ always() && github.repository == 'bryanthaboi/gen1recomp' }}
         run: |
           security delete-keychain "$RUNNER_TEMP/pokemon-signing.keychain-db" 2>/dev/null || true
+          rm -f "$RUNNER_TEMP/release-deploy-key"

.github/workflows/switch-artifact-comment.yml

@@ -0,0 +1,55 @@
+name: Switch artifact comment
+
+on:
+  workflow_run:
+    workflows: [ci]
+    types: [completed]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  comment:
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - id: artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name }}
+        run: |
+          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp-switch-nro") | .id')"
+          [ -n "$artifact_id" ] || exit 0
+          head_owner="${HEAD_REPOSITORY%%/*}"
+          pr_number="$(gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$head_owner:$HEAD_BRANCH" --jq '.[0].number // empty')"
+          [ -n "$pr_number" ] || exit 0
+          echo "artifact_url=https://github.com/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts/$artifact_id" >> "$GITHUB_OUTPUT"
+          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
+      # Upsert via comment-tag only — do not delete-all bot comments (clobbers iOS).
+      - name: Get build info
+        id: build-info
+        env:
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          commit_hash="$(printf '%s' "$HEAD_SHA" | cut -c1-7)"
+          build_time="$(date "+%Y-%m-%d %H:%M:%S")"
+          echo "hash=$commit_hash" >> "$GITHUB_OUTPUT"
+          echo "time=$build_time" >> "$GITHUB_OUTPUT"
+      - name: comment Switch artifact
+        if: steps.artifact.outputs.pr_number != ''
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          message: |
+            [gen1recomp-switch.nro](${{ steps.artifact.outputs.artifact_url }})
+
+            **Commit**: [#${{ steps.build-info.outputs.hash }}](https://github.com/${{ github.event.workflow_run.head_repository.full_name }}/commit/${{ github.event.workflow_run.head_sha }})
+            **Build Time**: `${{ steps.build-info.outputs.time }}`
+
+            <sub>This comment was automatically generated. [View workflow run](https://github.com/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }})</sub>
+          pr-number: ${{ steps.artifact.outputs.pr_number }}
+          comment-tag: switch-build-result
+          github-token: ${{ github.token }}

.gitignore

@@ -31,9 +31,29 @@ mobile/ios/love-src/
 mobile/ios/cache/
 mobile/ios/build/
 
-# Final packaged build artifacts (mac/win/web/android/ios) — see scripts/build.sh
+# love-nx vendor binaries (fetch per docs/switch-build.md; also covered by .*)
+.bazinga/love-nx/
+
+# Final packaged build artifacts (mac/win/web/android/ios/switch) — see scripts/build.sh
 /dist/
 
+# Switch OTA launcher build outputs
+ports/switch/ota-launcher/build/
+ports/switch/ota-launcher/build-host/
+ports/switch/ota-launcher/*.nro
+ports/switch/ota-launcher/*.nacp
+ports/switch/ota-launcher/*.elf
+ports/switch/ota-launcher/*.map
+ports/switch/ota-launcher/romfs/logo.rgba
+ports/switch/ota-launcher/romfs/logo.png
+ports/switch/ota-launcher/romfs/cacert.pem
+ports/switch/ota-launcher/romfs/ota-bootstrap.nro
+ports/switch/ota-bootstrap/build/
+ports/switch/ota-bootstrap/*.nro
+ports/switch/ota-bootstrap/*.nacp
+ports/switch/ota-bootstrap/*.elf
+ports/switch/ota-bootstrap/*.map
+
 # Legacy manual convenience-copy location (superseded by /dist/android/)
 mobile/dist/
 
@@ -43,3 +63,8 @@ mobile/dist/
 
 # per-machine iOS bundle-id pin (see scripts/build_ios.sh)
 mobile/ios/bundle_id.local
+
+# Xbox UWP build output
+/ports/uwp/build/
+/ports/uwp/third_party/*/source/
+/ports/uwp/third_party/angle/depot_tools/

CONTRIBUTING-mods.md

@@ -118,6 +118,7 @@ not a hard error, so the list can grow without breaking old mods.
 | `QUEST` | New story, NPCs, dialogue, cutscenes | content |
 | `MECHANIC` | New or changed battle/field mechanics via hooks/effects | overhaul |
 | `GRAPHICS` | Sprite / tileset / palette / font changes | content |
+| `LANGUAGE` | A translation: `text`, `strings` and the glyphs it needs | content |
 | `AUDIO` | Music, sfx, cries | content |
 | `UI` | New or modified screens, menus, overlays | content / overhaul |
 | `TOOL` | Dev/QoL utilities, overlays, inter-mod libraries | content |
@@ -128,6 +129,15 @@ not a hard error, so the list can grow without breaking old mods.
 keeps validating with the value it has shipped since before the taxonomy
 existed.
 
+A translation may also set `"language": true` in the manifest. That is the
+one claim online play acts on: an install running nothing but verified
+translations may take an ONLINE MATCH or a TOURNAMENT instead of being
+asked to restart vanilla. The claim is checked, not taken -- the mod
+qualifies only if every record it writes lands in `text`, `strings` or
+`font`, it wraps no hook, subscribes to no event and requests no
+permission. Anything else and it is an ordinary content mod that happens to
+ship text.
+
 ### 4. `mod.card`
 
 The manifest is the *engine's* contract: identity, load order, dependencies,

README.md

@@ -4,6 +4,9 @@ A native LÖVE2D recreation of Poke Red, Blue and Yellow. The engine and map
 behavior are hand-written Lua; game data and graphics are decoded from a ROM
 supplied by the player.
 
+> [!CAUTION]
+> **We are NOT affiliated with the website `gen1recomp[.]com`** That website is not run by this project, was not authorized by us, and we have no idea who operates it. It is impersonating this project; do not download anything from it, and treat anything it hosts or claims as untrustworthy. Even if the site currently links back to this repository, the people behind it can change its content at any time, so nothing on it should ever be trusted. This GitHub repository and the Discord linked below are the only official sources for this project.
+
 <p align="center"><img src="https://raw.githubusercontent.com/bryanthaboi/gen1recomp/refs/heads/dev/assets/logo/logo.png"></p>
 
 **SUPPORT / ANNOUNCEMENTS / MODS:** [Discord](https://bois.icu)
@@ -75,6 +78,19 @@ The packaged app contains neither a ROM nor pre-extracted game data. Music,
 sound effects, and cries are synthesized while the game runs from compact
 audio channel programs copied out of the verified ROM.
 
+### A note on Windows Defender warnings
+
+Windows Defender sometimes flags the Windows build with a generic
+machine-learning detection such as `Trojan:Win32/Wacatac!ml` (#621). This is
+a known false positive: the exe is the official LÖVE runtime with the game
+archive appended (the standard way LÖVE games ship), and Defender's
+heuristics distrust unsigned executables with appended data. Every release
+publishes SHA-256 checksums (`sha256sums.txt`) so you can verify your
+download, and you can confirm a flagged file yourself on
+[VirusTotal](https://www.virustotal.com), where these builds come back clean
+on every engine except Defender's heuristic. False positives are reported to
+Microsoft as they come up.
+
 ## Controls
 
 
@@ -96,6 +112,7 @@ supported out of the box.
 | Key       | What it does                                         |
 | --------- | ---------------------------------------------------- |
 | `-` / `=` | Zoom out / in (overworld; also mouse wheel)          |
+| `1`       | Cycle GAME SPEED up (controller: R2 faster, L2 slower) |
 | `2`       | Cycle COLORS                                         |
 | `3`       | Cycle TILT (free-roam overworld)                     |
 | `4`       | Cycle ZOOM through every level (free-roam overworld) |
@@ -105,8 +122,8 @@ supported out of the box.
 | `F10`     | Open / close the mod manager                         |
 
 
-COLORS, TILT, ZOOM, GBC FX, and VOID FILL are also in the Options menu
-and persist in `options.lua`.
+COLORS, TILT, ZOOM, GBC FX, GAME SPEED, and VOID FILL are also in the
+Options menu and persist in `options.lua`.
 
 ### Low-end devices
 
@@ -188,6 +205,39 @@ even on a different computer, as long as the same folder comes along.
 already written to either location is touched automatically, so copy files
 over yourself if you want to carry existing progress across the switch.
 
+## Launch Options
+
+By default the app opens the launcher so you can pick a game. Launch options
+skip it and start one game directly, which is what you want for a one-click
+entry: a desktop shortcut per game, a Steam entry, or a handheld frontend.
+
+| Option | Effect |
+| --- | --- |
+| `--game=red` | boot Red, skipping the launcher (`blue` and `yellow` too, or just `r` / `b` / `y`) |
+| `--slot=2` | load that save slot; takes a slot number or a slot id |
+| `--launcher` | open the launcher anyway, so you can edit a shortcut you already made |
+
+
+## Linux on arm64 (Raspberry Pi)
+
+Alongside the x86_64 `gen1recomp-*-linux.zip`, every release ships
+`gen1recomp-*-linux-arm64.AppImage` for 64-bit ARM desktop Linux — Raspberry
+Pi 4/5, Armbian and other SBC distros, and arm64 VMs on Apple Silicon:
+
+```sh
+chmod +x gen1recomp-*-linux-arm64.AppImage
+./gen1recomp-*-linux-arm64.AppImage
+```
+
+LÖVE publishes no aarch64 binary of any kind, so this artifact compiles the
+engine — and SDL2, OpenAL and the codecs — from source inside a Debian
+bullseye arm64 container. It needs only glibc 2.29+, libstdc++, freetype and
+zlib on the host; OpenGL, X11, Wayland, KMSDRM, ALSA and PulseAudio are all
+dlopened, so the same image runs on a full desktop, a Wayland-only session or
+a KMSDRM handheld with no X server. Build instructions and the reasoning are
+in [docs/linux-arm64-build.md](docs/linux-arm64-build.md).
+
+
 ## iOS
 
 Every release ships `gen1recomp-*-ios.ipa`. Sideload it with AltStore
@@ -195,6 +245,50 @@ Every release ships `gen1recomp-*-ios.ipa`. Sideload it with AltStore
 build and install from source on a Mac instead, see
 [docs/ios-install.md](docs/ios-install.md).
 
+<div>
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=sidestore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/sidestore-badge.png" alt="Add to SideStore" height="60"></a>
+    &nbsp;
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=feather://source/https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/feather-badge.png" alt="Add to Feather" height="60"></a>
+    &nbsp;
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=altstore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/altstore-badge.png" alt="Add to AltStore" height="60"></a>
+    &nbsp;
+    <a href="https://github.com/bryanthaboi/gen1recomp/releases/latest"><img src="./.github/resources/github-badge.png" alt="Download from GitHub" height="60"></a>
+</div>
+
+## Xbox Dev Mode
+
+Every release ships `gen1recomp-*-xbox-uwp.zip` for Xbox One and Xbox Series
+consoles in Developer Mode. It cannot be installed in retail mode.
+
+Extract the archive, then use Xbox Device Portal to install the `.msix` and
+the x64 package under `Dependencies`.
+
+### External setup
+
+1. Put your legally obtained Red, Blue, or Yellow ROMs on an external drive.
+   Mod ZIPs can go on the same drive.
+2. Connect the drive to the Xbox and open Gen1Recomp.
+3. Select **Import ROM** or **Import Mod**, then choose the file with the Xbox
+   file picker.
+4. Repeat the ROM import for each version you want to use.
+
+### Internal setup
+
+1. Create a folder named `baseroms` on your PC and place your legally obtained
+   Red, Blue, or Yellow ROMs inside it.
+2. ZIP the folder, keeping `baseroms` at the top level of the archive.
+3. Launch Gen1Recomp once, then close it.
+4. Open Xbox Device Portal and upload the ZIP to
+   `Gen1Recomp/LocalState/pokemon-love2d/`.
+5. Choose **Yes** when Device Portal asks whether to extract the archive.
+6. Open Gen1Recomp. The launcher checks baseroms once at startup. When it finds a compatible ROM, that game’s tab shows ROM FOUND and an Import detected ROM button.
+
+ROMs, generated game data, saves, and mods remain in LocalState and are not
+included in the app.
+
+Source builds and package details are covered in
+[the Xbox UWP build notes](ports/uwp/BUILD.md).
+
 ## Handhelds
 
 A PortMaster-style port for the **Anbernic RG34XXSP** on Stock OS 64-bit MOD
@@ -202,6 +296,21 @@ ships with every release as `gen1recomp-*-rg34xxsp-stockos64-mod.zip`.
 Install steps, controls, and troubleshooting live in
 [docs/anbernic-rg34xxsp.md](docs/anbernic-rg34xxsp.md).
 
+## Nintendo Switch
+
+Releases ship an SD-ready `gen1recomp-*-switch.zip`. Runtime target is pinned
+[love-nx](https://github.com/retronx-team/love-nx) `11.5-nx1`. Requires a
+console that can run Switch homebrew.
+
+- Players: [docs/switch-install.md](docs/switch-install.md). Download the
+  zip, extract at the microSD root (install or update), title-override
+  launch, import your own legal ROM, Joy-Con controls and shortcuts.
+- Builders: [docs/switch-build.md](docs/switch-build.md). `--fetch` /
+  `--loose` / `--fused`, toolchain, Docker fallback, and CI vs release
+  (path-gated ubuntu selftest, fused PR artifact on the main repo, release
+  hard-fail).
+- File transfer (MTP / SD / FTP): [docs/switch-transfer.md](docs/switch-transfer.md).
+
 ## Modding
 
 The game ships a native mod platform: content registries, events and hooks,

assets/fonts/plainpixel/README.md

@@ -0,0 +1,13 @@
+# Plain Pixel font
+
+"Plain Pixel Font" by Douglas Vautour (Burpy Fresh) is licensed under
+CC-BY 4.0: https://burpyfresh.itch.io
+
+Version 0.009 (CJK character additions), unmodified. Characters for most
+languages have a 5x11 base but can extend vertically; double-width
+characters such as Hiragana and Katakana are 11x11.
+
+Bundled so a translation mod can opt into TTF text rendering
+(`mod.content.font:register("ttf", {})`; see the Translation support
+section of docs/new-features.md) instead of drawing hundreds of glyph-page
+tiles. The tile font extracted from the player's ROM stays the default.

build-rg34xxsp.sh

@@ -89,7 +89,7 @@ mkdir -p "$GAME_SRC"
 # tools/save-editor is part of that payload: the launcher's Edit button on a
 # save row opens it in-process (main.lua).
 (cd "$ROOT" && zip -q -9 -r "$WORK/game-payload.zip" \
-  main.lua conf.lua src data assets tools/save-editor \
+  main.lua conf.lua src libs data assets tools/save-editor \
   tools/rom_manifest.json tools/rom_manifest_blue.json \
   -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
 if unzip -Z1 "$WORK/game-payload.zip" \

conf.lua

@@ -58,7 +58,17 @@ function love.conf(t)
   -- engine before conf runs (LÖVE 11.x / 11.5).
   local osName = love._os
   local mobile = osName == "Android" or osName == "iOS"
-  if mobile then
+  local nx = osName == "NX"
+  if nx then
+    -- Switch (love-nx): hint handheld 720p. SDL auto-switches portable↔dock
+    -- (720p↔1080p) only when the window is resizable and not exclusive
+    -- fullscreen; NxDisplay.sync also applies the size on boot and dock change.
+    t.window.width = 1280
+    t.window.height = 720
+    t.window.fullscreen = false
+    t.window.resizable = true
+    t.window.highdpi = false
+  elseif mobile then
     -- resizable is what unlocks orientation.  SDL's Android backend, given no
     -- SDL_HINT_ORIENTATIONS (LÖVE sets none), calls setRequestedOrientation
     -- at window creation -- FULL_SENSOR when the window is resizable (rotates
@@ -70,6 +80,10 @@ function love.conf(t)
     -- just work.  FULL_SENSOR ignores the device's rotation lock, so
     -- GameActivity.setOrientationBis remaps it to FULL_USER after SDL has
     -- run: same orientations allowed, but auto-rotate being off now wins.
+    -- A persisted ORIENTATION lock (#592) overrides all of this after boot:
+    -- src/core/Orientation.lua sets SDL_HINT_ORIENTATIONS over the FFI and
+    -- re-triggers the request, from main.lua for the launcher and from
+    -- Game:applyOptions in game.
     -- iOS follows the Info.plist orientations
     -- (see mobile/ios/overlays/love-ios.plist, now portrait + landscape).
     t.window.resizable = true

data/palettes_gbc.lua

@@ -1683,158 +1683,172 @@ return {
       { 0, 0, 0 },
     },
   },
+  -- Species -> palette NAME, taken from pokered-gbc data/pokemon/palettes.asm
+  -- ELSE branch -- the one that is NOT gated on GEN_2_GRAPHICS.
+  --
+  -- That file has two tables.  The IF GEN_2_GRAPHICS branch assigns a
+  -- PER-SPECIES palette (PAL_BULBASAUR, PAL_SQUIRTLE, ...) authored for Gen 2
+  -- sprite art; the ELSE branch keeps Gen 1's own assignments (GREENMON,
+  -- CYANMON, ...).  This port extracts Gen 1 pics from the ROM, so the Gen 1
+  -- branch is the matching one.  The per-species table was imported here by
+  -- mistake, which pointed every mon at colours shaded for different art:
+  -- Bulbasaur wore PAL_BULBASAUR's red-orange over a sprite that has no red
+  -- on it, and Squirtle wore PAL_SQUIRTLE's shell brown on his head.
+  --
+  -- The palette VALUES below are still pokered-gbc's, so ADVANCED keeps its
+  -- richer colours -- only which palette each species points at changed.
   pokemon = {
-    ABRA = "ABRA",
-    AERODACTYL = "AERODACTYL",
-    ALAKAZAM = "ALAKAZAM",
-    ARBOK = "ARBOK",
-    ARCANINE = "ARCANINE",
-    ARTICUNO = "ARTICUNO",
-    BEEDRILL = "BEEDRILL",
-    BELLSPROUT = "BELLSPROUT",
-    BLASTOISE = "BLASTOISE",
-    BULBASAUR = "BULBASAUR",
-    BUTTERFREE = "BUTTERFREE",
-    CATERPIE = "CATERPIE",
-    CHANSEY = "CHANSEY",
-    CHARIZARD = "CHARIZARD",
-    CHARMANDER = "CHARMANDER",
-    CHARMELEON = "CHARMELEON",
-    CLEFABLE = "CLEFABLE",
-    CLEFAIRY = "CLEFAIRY",
-    CLOYSTER = "CLOYSTER",
-    CUBONE = "CUBONE",
-    DEWGONG = "DEWGONG",
-    DIGLETT = "DIGLETT",
-    DITTO = "DITTO",
-    DODRIO = "DODRIO",
-    DODUO = "DODUO",
-    DRAGONAIR = "DRAGONAIR",
-    DRAGONITE = "DRAGONITE",
-    DRATINI = "DRATINI",
-    DROWZEE = "DROWZEE",
-    DUGTRIO = "DUGTRIO",
-    EEVEE = "EEVEE",
-    EKANS = "EKANS",
-    ELECTABUZZ = "ELECTABUZZ",
-    ELECTRODE = "ELECTRODE",
-    EXEGGCUTE = "EXEGGCUTE",
-    EXEGGUTOR = "EXEGGUTOR",
-    FARFETCHD = "FARFETCH_D",
-    FEAROW = "FEAROW",
-    FLAREON = "FLAREON",
-    GASTLY = "GASTLY",
-    GENGAR = "GENGAR",
-    GEODUDE = "GEODUDE",
-    GLOOM = "GLOOM",
-    GOLBAT = "GOLBAT",
-    GOLDEEN = "GOLDEEN",
-    GOLDUCK = "GOLDUCK",
-    GOLEM = "GOLEM",
-    GRAVELER = "GRAVELER",
-    GRIMER = "GRIMER",
-    GROWLITHE = "GROWLITHE",
-    GYARADOS = "GYARADOS",
-    HAUNTER = "HAUNTER",
-    HITMONCHAN = "HITMONCHAN",
-    HITMONLEE = "HITMONLEE",
-    HORSEA = "HORSEA",
-    HYPNO = "HYPNO",
-    IVYSAUR = "IVYSAUR",
-    JIGGLYPUFF = "JIGGLYPUFF",
-    JOLTEON = "JOLTEON",
-    JYNX = "JYNX",
-    KABUTO = "KABUTO",
-    KABUTOPS = "KABUTOPS",
-    KADABRA = "KADABRA",
-    KAKUNA = "KAKUNA",
-    KANGASKHAN = "KANGASKHAN",
-    KINGLER = "KINGLER",
-    KOFFING = "KOFFING",
-    KRABBY = "KRABBY",
-    LAPRAS = "LAPRAS",
-    LICKITUNG = "LICKITUNG",
-    MACHAMP = "MACHAMP",
-    MACHOKE = "MACHOKE",
-    MACHOP = "MACHOP",
-    MAGIKARP = "MAGIKARP",
-    MAGMAR = "MAGMAR",
-    MAGNEMITE = "MAGNEMITE",
-    MAGNETON = "MAGNETON",
-    MANKEY = "MANKEY",
-    MAROWAK = "MAROWAK",
-    MEOWTH = "MEOWTH",
-    METAPOD = "METAPOD",
-    MEW = "MEW",
-    MEWTWO = "MEWTWO",
-    MOLTRES = "MOLTRES",
-    MR_MIME = "MR_MIME",
-    MUK = "MUK",
-    NIDOKING = "NIDOKING",
-    NIDOQUEEN = "NIDOQUEEN",
-    NIDORAN_F = "NIDORAN_F",
-    NIDORAN_M = "NIDORAN_M",
-    NIDORINA = "NIDORINA",
-    NIDORINO = "NIDORINO",
-    NINETALES = "NINETALES",
-    ODDISH = "ODDISH",
-    OMANYTE = "OMANYTE",
-    OMASTAR = "OMASTAR",
-    ONIX = "ONIX",
-    PARAS = "PARAS",
-    PARASECT = "PARASECT",
-    PERSIAN = "PERSIAN",
-    PIDGEOT = "PIDGEOT",
-    PIDGEOTTO = "PIDGEOTTO",
-    PIDGEY = "PIDGEY",
-    PIKACHU = "PIKACHU",
-    PINSIR = "PINSIR",
-    POLIWAG = "POLIWAG",
-    POLIWHIRL = "POLIWHIRL",
-    POLIWRATH = "POLIWRATH",
-    PONYTA = "PONYTA",
-    PORYGON = "PORYGON",
-    PRIMEAPE = "PRIMEAPE",
-    PSYDUCK = "PSYDUCK",
-    RAICHU = "RAICHU",
-    RAPIDASH = "RAPIDASH",
-    RATICATE = "RATICATE",
-    RATTATA = "RATTATA",
-    RHYDON = "RHYDON",
-    RHYHORN = "RHYHORN",
-    SANDSHREW = "SANDSHREW",
-    SANDSLASH = "SANDSLASH",
-    SCYTHER = "SCYTHER",
-    SEADRA = "SEADRA",
-    SEAKING = "SEAKING",
-    SEEL = "SEEL",
-    SHELLDER = "SHELLDER",
-    SLOWBRO = "SLOWBRO",
-    SLOWPOKE = "SLOWPOKE",
-    SNORLAX = "SNORLAX",
-    SPEAROW = "SPEAROW",
-    SQUIRTLE = "SQUIRTLE",
-    STARMIE = "STARMIE",
-    STARYU = "STARYU",
-    TANGELA = "TANGELA",
-    TAUROS = "TAUROS",
-    TENTACOOL = "TENTACOOL",
-    TENTACRUEL = "TENTACRUEL",
-    VAPOREON = "VAPOREON",
-    VENOMOTH = "VENOMOTH",
-    VENONAT = "VENONAT",
-    VENUSAUR = "VENUSAUR",
-    VICTREEBEL = "VICTREEBEL",
-    VILEPLUME = "VILEPLUME",
-    VOLTORB = "VOLTORB",
-    VULPIX = "VULPIX",
-    WARTORTLE = "WARTORTLE",
-    WEEDLE = "WEEDLE",
-    WEEPINBELL = "WEEPINBELL",
-    WEEZING = "WEEZING",
-    WIGGLYTUFF = "WIGGLYTUFF",
-    ZAPDOS = "ZAPDOS",
-    ZUBAT = "ZUBAT",
+    ABRA = "YELLOWMON",
+    AERODACTYL = "GRAYMON",
+    ALAKAZAM = "YELLOWMON",
+    ARBOK = "PURPLEMON",
+    ARCANINE = "REDMON",
+    ARTICUNO = "BLUEMON",
+    BEEDRILL = "YELLOWMON",
+    BELLSPROUT = "GREENMON",
+    BLASTOISE = "CYANMON",
+    BULBASAUR = "GREENMON",
+    BUTTERFREE = "CYANMON",
+    CATERPIE = "GREENMON",
+    CHANSEY = "PINKMON",
+    CHARIZARD = "REDMON",
+    CHARMANDER = "REDMON",
+    CHARMELEON = "REDMON",
+    CLEFABLE = "PINKMON",
+    CLEFAIRY = "PINKMON",
+    CLOYSTER = "GRAYMON",
+    CUBONE = "GRAYMON",
+    DEWGONG = "BLUEMON",
+    DIGLETT = "BROWNMON",
+    DITTO = "GRAYMON",
+    DODRIO = "BROWNMON",
+    DODUO = "BROWNMON",
+    DRAGONAIR = "BLUEMON",
+    DRAGONITE = "BROWNMON",
+    DRATINI = "GRAYMON",
+    DROWZEE = "YELLOWMON",
+    DUGTRIO = "BROWNMON",
+    EEVEE = "GRAYMON",
+    EKANS = "PURPLEMON",
+    ELECTABUZZ = "YELLOWMON",
+    ELECTRODE = "YELLOWMON",
+    EXEGGCUTE = "PINKMON",
+    EXEGGUTOR = "GREENMON",
+    FARFETCHD = "BROWNMON",
+    FEAROW = "BROWNMON",
+    FLAREON = "REDMON",
+    GASTLY = "PURPLEMON",
+    GENGAR = "PURPLEMON",
+    GEODUDE = "GRAYMON",
+    GLOOM = "REDMON",
+    GOLBAT = "BLUEMON",
+    GOLDEEN = "REDMON",
+    GOLDUCK = "CYANMON",
+    GOLEM = "GRAYMON",
+    GRAVELER = "GRAYMON",
+    GRIMER = "PURPLEMON",
+    GROWLITHE = "BROWNMON",
+    GYARADOS = "BLUEMON",
+    HAUNTER = "PURPLEMON",
+    HITMONCHAN = "BROWNMON",
+    HITMONLEE = "BROWNMON",
+    HORSEA = "CYANMON",
+    HYPNO = "YELLOWMON",
+    IVYSAUR = "GREENMON",
+    JIGGLYPUFF = "PINKMON",
+    JOLTEON = "YELLOWMON",
+    JYNX = "MEWMON",
+    KABUTO = "BROWNMON",
+    KABUTOPS = "BROWNMON",
+    KADABRA = "YELLOWMON",
+    KAKUNA = "YELLOWMON",
+    KANGASKHAN = "BROWNMON",
+    KINGLER = "REDMON",
+    KOFFING = "PURPLEMON",
+    KRABBY = "REDMON",
+    LAPRAS = "CYANMON",
+    LICKITUNG = "PINKMON",
+    MACHAMP = "GRAYMON",
+    MACHOKE = "GRAYMON",
+    MACHOP = "GRAYMON",
+    MAGIKARP = "REDMON",
+    MAGMAR = "REDMON",
+    MAGNEMITE = "GRAYMON",
+    MAGNETON = "GRAYMON",
+    MANKEY = "BROWNMON",
+    MAROWAK = "GRAYMON",
+    MEOWTH = "YELLOWMON",
+    METAPOD = "GREENMON",
+    MEW = "MEWMON",
+    MEWTWO = "MEWMON",
+    MOLTRES = "REDMON",
+    MR_MIME = "PINKMON",
+    MUK = "PURPLEMON",
+    NIDOKING = "PURPLEMON",
+    NIDOQUEEN = "BLUEMON",
+    NIDORAN_F = "BLUEMON",
+    NIDORAN_M = "PURPLEMON",
+    NIDORINA = "BLUEMON",
+    NIDORINO = "PURPLEMON",
+    NINETALES = "YELLOWMON",
+    ODDISH = "GREENMON",
+    OMANYTE = "BLUEMON",
+    OMASTAR = "BLUEMON",
+    ONIX = "GRAYMON",
+    PARAS = "REDMON",
+    PARASECT = "REDMON",
+    PERSIAN = "YELLOWMON",
+    PIDGEOT = "BROWNMON",
+    PIDGEOTTO = "BROWNMON",
+    PIDGEY = "BROWNMON",
+    PIKACHU = "YELLOWMON",
+    PINSIR = "BROWNMON",
+    POLIWAG = "BLUEMON",
+    POLIWHIRL = "BLUEMON",
+    POLIWRATH = "BLUEMON",
+    PONYTA = "REDMON",
+    PORYGON = "GRAYMON",
+    PRIMEAPE = "BROWNMON",
+    PSYDUCK = "YELLOWMON",
+    RAICHU = "YELLOWMON",
+    RAPIDASH = "REDMON",
+    RATICATE = "GRAYMON",
+    RATTATA = "GRAYMON",
+    RHYDON = "GRAYMON",
+    RHYHORN = "GRAYMON",
+    SANDSHREW = "BROWNMON",
+    SANDSLASH = "BROWNMON",
+    SCYTHER = "GREENMON",
+    SEADRA = "CYANMON",
+    SEAKING = "REDMON",
+    SEEL = "BLUEMON",
+    SHELLDER = "GRAYMON",
+    SLOWBRO = "PINKMON",
+    SLOWPOKE = "PINKMON",
+    SNORLAX = "PINKMON",
+    SPEAROW = "BROWNMON",
+    SQUIRTLE = "CYANMON",
+    STARMIE = "GRAYMON",
+    STARYU = "REDMON",
+    TANGELA = "BLUEMON",
+    TAUROS = "GRAYMON",
+    TENTACOOL = "CYANMON",
+    TENTACRUEL = "CYANMON",
+    VAPOREON = "CYANMON",
+    VENOMOTH = "PURPLEMON",
+    VENONAT = "PURPLEMON",
+    VENUSAUR = "GREENMON",
+    VICTREEBEL = "GREENMON",
+    VILEPLUME = "REDMON",
+    VOLTORB = "YELLOWMON",
+    VULPIX = "REDMON",
+    WARTORTLE = "CYANMON",
+    WEEDLE = "YELLOWMON",
+    WEEPINBELL = "GREENMON",
+    WEEZING = "PURPLEMON",
+    WIGGLYTUFF = "PINKMON",
+    ZAPDOS = "YELLOWMON",
+    ZUBAT = "BLUEMON",
   },
   source = "pokered-gbc data/super_palettes.asm + data/mon_palettes.asm + color/**",
   world = {

data/scripts/flavor/cerulean_trashed_house.lua

@@ -14,9 +14,9 @@ return {
       --   else               -> .WhatsLostIsLostText (player has TM_DIG)
       TEXT_CERULEANTRASHEDHOUSE_FISHING_GURU = {
         { "check_item", "TM_DIG" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
         { "show_text", "_CeruleanTrashedHouseFishingGuruTheyStoleATMText" },
-        { "jump", 5 },
+        { "jump", "end" },
         { "show_text", "_CeruleanTrashedHouseFishingGuruWhatsLostIsLostText" },
       },
     },

data/scripts/flavor/fuchsia_city.lua

@@ -0,0 +1,80 @@
+-- Fuchsia City (pokered/scripts/FuchsiaCity.asm)
+--
+-- The exhibit signs are text_asm bodies: PrintText of a single text_far,
+-- then DisplayPokedex for the exhibited species.  The preview marks the
+-- species seen but not owned, same as the S.S. Anne passenger's Snorlax.
+--
+-- The fossil sign branches on the Mt. Moon fossil events.  The exhibit
+-- holds the fossil the player did NOT take: taking the Dome Fossil puts
+-- Omanyte on display, taking the Helix Fossil puts Kabuto.  With neither
+-- event set the sign only prints its undetermined line and no dex entry
+-- opens.
+--
+-- The other text pointers (city sign, Safari Game signs, mart/center/gym
+-- and warden signs, the four NPCs, the exhibited-mon FuchsiaCityPokemonText
+-- rows) are plain text_far wrappers that resolve through Data:resolveText,
+-- so they are not ported here.
+return {
+  FUCHSIA_CITY = {
+    talk = {
+      -- FuchsiaCityChanseySignText: PrintText(_FuchsiaCityChanseySignText),
+      -- then DisplayPokedex CHANSEY.
+      TEXT_FUCHSIACITY_CHANSEY_SIGN = {
+        { "show_text", "_FuchsiaCityChanseySignText" },
+        { "mark_seen", "CHANSEY" },
+        { "push_screen", "DexEntryMenu", "CHANSEY" },
+      },
+
+      -- FuchsiaCityVoltorbSignText: PrintText(_FuchsiaCityVoltorbSignText),
+      -- then DisplayPokedex VOLTORB.
+      TEXT_FUCHSIACITY_VOLTORB_SIGN = {
+        { "show_text", "_FuchsiaCityVoltorbSignText" },
+        { "mark_seen", "VOLTORB" },
+        { "push_screen", "DexEntryMenu", "VOLTORB" },
+      },
+
+      -- FuchsiaCityKangaskhanSignText: PrintText(_FuchsiaCityKangaskhanSignText),
+      -- then DisplayPokedex KANGASKHAN.
+      TEXT_FUCHSIACITY_KANGASKHAN_SIGN = {
+        { "show_text", "_FuchsiaCityKangaskhanSignText" },
+        { "mark_seen", "KANGASKHAN" },
+        { "push_screen", "DexEntryMenu", "KANGASKHAN" },
+      },
+
+      -- FuchsiaCitySlowpokeSignText: PrintText(_FuchsiaCitySlowpokeSignText),
+      -- then DisplayPokedex SLOWPOKE.
+      TEXT_FUCHSIACITY_SLOWPOKE_SIGN = {
+        { "show_text", "_FuchsiaCitySlowpokeSignText" },
+        { "mark_seen", "SLOWPOKE" },
+        { "push_screen", "DexEntryMenu", "SLOWPOKE" },
+      },
+
+      -- FuchsiaCityLaprasSignText: PrintText(_FuchsiaCityLaprasSignText),
+      -- then DisplayPokedex LAPRAS.
+      TEXT_FUCHSIACITY_LAPRAS_SIGN = {
+        { "show_text", "_FuchsiaCityLaprasSignText" },
+        { "mark_seen", "LAPRAS" },
+        { "push_screen", "DexEntryMenu", "LAPRAS" },
+      },
+
+      -- FuchsiaCityFossilSignText: CheckEvent EVENT_GOT_DOME_FOSSIL /
+      -- CheckEventReuseA EVENT_GOT_HELIX_FOSSIL pick the text and the
+      -- displayed entry; with neither set only the undetermined line prints.
+      TEXT_FUCHSIACITY_FOSSIL_SIGN = {
+        { "check_flag", "EVENT_GOT_DOME_FOSSIL" },                 -- 1
+        { "jump_if_true", 7 },                                     -- 2
+        { "check_flag", "EVENT_GOT_HELIX_FOSSIL" },                -- 3
+        { "jump_if_true", 11 },                                    -- 4
+        { "show_text", "_FuchsiaCityFossilSignUndeterminedText" }, -- 5
+        { "jump", "end" },                                         -- 6
+        { "show_text", "_FuchsiaCityFossilSignOmanyteText" },      -- 7
+        { "mark_seen", "OMANYTE" },                                -- 8
+        { "push_screen", "DexEntryMenu", "OMANYTE" },              -- 9
+        { "jump", "end" },                                         -- 10
+        { "show_text", "_FuchsiaCityFossilSignKabutoText" },       -- 11
+        { "mark_seen", "KABUTO" },                                 -- 12
+        { "push_screen", "DexEntryMenu", "KABUTO" },               -- 13
+      },
+    },
+  },
+}

data/scripts/flavor/lavender_mart.lua

@@ -8,9 +8,9 @@ return {
       TEXT_LAVENDERMART_COOLTRAINER_M = {
         { "face_player" },
         { "check_flag", "EVENT_RESCUED_MR_FUJI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_LavenderMartCooltrainerMReviveText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_LavenderMartCooltrainerMNuggetText" },
       },
     },

data/scripts/flavor/mr_fujis_house.lua

@@ -13,9 +13,9 @@ M.MR_FUJIS_HOUSE = {
     TEXT_MRFUJISHOUSE_SUPER_NERD = {
       { "face_player" },                                                    -- 1
       { "check_flag", "EVENT_RESCUED_MR_FUJI" },                            -- 2
-      { "jump_if_true", 5 },                                                -- 3
+      { "jump_if_true", 6 },                                                -- 3
       { "show_text", "_MrFujisHouseSuperNerdMrFujiIsntHereText" },          -- 4
-      { "jump", 6 },                                                        -- 5
+      { "jump", "end" },                                                    -- 5
       { "show_text", "_MrFujisHouseSuperNerdMrFujiHadBeenPrayingText" },    -- 6
     },
 
@@ -25,9 +25,9 @@ M.MR_FUJIS_HOUSE = {
     TEXT_MRFUJISHOUSE_LITTLE_GIRL = {
       { "face_player" },                                                    -- 1
       { "check_flag", "EVENT_RESCUED_MR_FUJI" },                            -- 2
-      { "jump_if_true", 5 },                                                -- 3
+      { "jump_if_true", 6 },                                                -- 3
       { "show_text", "_MrFujisHouseLittleGirlThisIsMrFujisHouseText" },     -- 4
-      { "jump", 6 },                                                        -- 5
+      { "jump", "end" },                                                    -- 5
       { "show_text", "_MrFujisHouseLittleGirlPokemonAreNiceToHugText" },    -- 6
     },
 

data/scripts/flavor/pewter_city.lua

@@ -16,9 +16,13 @@ local function push(game, s, done)
   game.stack:push(TextBox.new(game, s, done))
 end
 
+-- PrintText on a text_end string returns with the box still drawn and
+-- YesNoChoice then draws the menu above it (InitYesNoTextBoxParameters,
+-- engine/menus/text_box.asm); no A press clears the question first.  Ride
+-- TextBox's opts.choice, the same as Commands.ask (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end
 
 M.PEWTER_CITY = {

data/scripts/flavor/route_16_gate_1f.lua

@@ -12,9 +12,9 @@ return {
       TEXT_ROUTE16GATE1F_GUARD = {
         { "face_player" },
         { "check_item", "BICYCLE" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_Route16Gate1FGuardNoPedestriansAllowedText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_Route16Gate1FGuardCyclingRoadExplanationText" },
       },
     },

data/scripts/flavor/route_18_gate_1f.lua

@@ -14,9 +14,9 @@ return {
       TEXT_ROUTE18GATE1F_GUARD = {
         { "face_player" },
         { "check_item", "BICYCLE" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_Route18Gate1FGuardYouNeedABicycleText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_Route18Gate1FGuardCyclingRoadUphillText" },
       },
     },

data/scripts/flavor/silph_co_10f.lua

@@ -12,9 +12,9 @@ return {
       TEXT_SILPHCO10F_SILPH_WORKER_F = {
         { "face_player" },
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_SilphCo10FSilphWorkerFImScaredText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_SilphCo10FSilphWorkerFQuietAboutMyCryingText" },
       },
     },

data/scripts/flavor/silph_co_3f.lua

@@ -10,9 +10,9 @@ return {
       --   not set: _SilphCo3FSilphWorkerMWhatShouldIDoText
       TEXT_SILPHCO3F_SILPH_WORKER_M = {
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
         { "show_text", "_SilphCo3FSilphWorkerMWhatShouldIDoText" },
-        { "jump", 5 },
+        { "jump", "end" },
         { "show_text", "_SilphCo3FSilphWorkerMYouSavedUsText" },
       },
     },

data/scripts/flavor/silph_co_4f.lua

@@ -7,9 +7,9 @@ return {
       TEXT_SILPHCO4F_SILPH_WORKER_M = {
         {"face_player"},
         {"check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI"},
-        {"jump_if_true", 5},
+        {"jump_if_true", 6},
         {"show_text", "_SilphCo4FSilphWorkerMImHidingText"},
-        {"jump", 6},
+        {"jump", "end"},
         {"show_text", "_SilphCo4FSilphWorkerMTeamRocketIsGoneText"},
       },
     },

data/scripts/flavor/silph_co_5f.lua

@@ -7,9 +7,9 @@ return {
       TEXT_SILPHCO5F_SILPH_WORKER_M = {
         {"face_player"},
         {"check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI"},
-        {"jump_if_true", 5},
+        {"jump_if_true", 6},
         {"show_text", "_SilphCo5FSilphWorkerMThatsYouRightText"},
-        {"jump", 6},
+        {"jump", "end"},
         {"show_text", "_SilphCo5FSilphWorkerMYoureOurHeroText"},
       },
     },

data/scripts/flavor/silph_co_6f.lua

@@ -11,9 +11,9 @@ return {
       TEXT_SILPHCO6F_SILPH_WORKER_M1 = {
         { "face_player" },
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_SilphCo6FSilphWorkerM1TookOverTheBuildingText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_SilphCo6FSilphWorkerM1BackToWorkText" },
       },
 
@@ -21,9 +21,9 @@ return {
       TEXT_SILPHCO6F_SILPH_WORKER_M2 = {
         { "face_player" },
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_SilphCo6FSilphWorkerMHelpMePleaseText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_SilphCo6FSilphWorkerMWeGotEngagedText" },
       },
 
@@ -31,9 +31,9 @@ return {
       TEXT_SILPHCO6F_SILPH_WORKER_F1 = {
         { "face_player" },
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_SilphCo6FSilphWorkerF1SuchACowardText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_SilphCo6FSilphWorkerF1HaveToMarryHimText" },
       },
 
@@ -41,9 +41,9 @@ return {
       TEXT_SILPHCO6F_SILPH_WORKER_F2 = {
         { "face_player" },
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_SilphCo6FSilphWorkerF2TeamRocketConquerWorldText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_SilphCo6FSilphWorkerF2TeamRocketRanText" },
       },
 
@@ -51,9 +51,9 @@ return {
       TEXT_SILPHCO6F_SILPH_WORKER_M3 = {
         { "face_player" },
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 5 },
+        { "jump_if_true", 6 },
         { "show_text", "_SilphCo6FSilphWorkerM3TargetedSilphText" },
-        { "jump", 6 },
+        { "jump", "end" },
         { "show_text", "_SilphCo6FSilphWorkerM3WorkForSilphText" },
       },
     },

data/scripts/flavor/silph_co_7f.lua

@@ -10,9 +10,9 @@ return {
       --   set: _SilphCo7FSilphWorkerM2CancelledMasterBallText
       TEXT_SILPHCO7F_SILPH_WORKER_M2 = {
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
         { "show_text", "_SilphCo7FSilphWorkerM2AfterTheMasterBallText" },
-        { "jump", 5 },
+        { "jump", "end" },
         { "show_text", "_SilphCo7FSilphWorkerM2CancelledMasterBallText" },
       },
 
@@ -22,9 +22,9 @@ return {
       --   set: _SilphCo7FSilphWorkerM3YouChasedOffTeamRocketText
       TEXT_SILPHCO7F_SILPH_WORKER_M3 = {
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
         { "show_text", "_SilphCo7FSilphWorkerM3ItWouldBeBadText" },
-        { "jump", 5 },
+        { "jump", "end" },
         { "show_text", "_SilphCo7FSilphWorkerM3YouChasedOffTeamRocketText" },
       },
 
@@ -34,9 +34,9 @@ return {
       --   set: _SilphCo7FSilphWorkerM4SafeAtLastText
       TEXT_SILPHCO7F_SILPH_WORKER_M4 = {
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
         { "show_text", "_SilphCo7FSilphWorkerM4ItsReallyDangerousHereText" },
-        { "jump", 5 },
+        { "jump", "end" },
         { "show_text", "_SilphCo7FSilphWorkerM4SafeAtLastText" },
       },
     },

data/scripts/flavor/silph_co_8f.lua

@@ -10,9 +10,9 @@ return {
       --   set: _SilphCo8FSilphWorkerMThanksForSavingUsText
       TEXT_SILPHCO8F_SILPH_WORKER_M = {
         { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
-        { "jump_if_true", 4 },
+        { "jump_if_true", 5 },
         { "show_text", "_SilphCo8FSilphWorkerMSilphIsFinishedText" },
-        { "jump", 5 },
+        { "jump", "end" },
         { "show_text", "_SilphCo8FSilphWorkerMThanksForSavingUsText" },
       },
     },

data/scripts/flavor/viridian_city.lua

@@ -23,9 +23,13 @@ local function push(game, s, done)
   game.stack:push(TextBox.new(game, s, done))
 end
 
+-- PrintText on a text_end string returns with the box still drawn and
+-- YesNoChoice then draws the menu above it (InitYesNoTextBoxParameters,
+-- engine/menus/text_box.asm); no A press clears the question first.  Ride
+-- TextBox's opts.choice, the same as Commands.ask (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end
 
 M.VIRIDIAN_CITY = {

data/scripts/flavor/viridian_school_house.lua

@@ -9,7 +9,8 @@
 -- hidden_text_predef spends the facing byte on the tx_pre id, so neither
 -- tile gates on facing.
 
-local Menu = require("src.ui.Menu")
+local Font = require("src.render.Font")
+local Theme = require("src.ui.Theme")
 local TextBox = require("src.render.TextBox")
 
 -- ViridianSchoolBlackboard (engine/events/hidden_events/school_blackboard.asm):
@@ -25,33 +26,112 @@ local STATUS_LABELS = {
   { " FRZ", "_ViridianBlackboardFrozenText" },
 }
 
+-- The headings list is a two-column menu, which src/ui/Menu.lua does not do
+-- (it stacks one column), so the layout lives here (#591).  .blackboardLoop:
+-- TextBoxBorder at hlcoord 0, 0 with `lb bc, 6, 10` is the 12x8 box,
+-- StatusAilmentText1 (" SLP"/" PSN"/" PAR") is placed at hlcoord 1, 2 and
+-- StatusAilmentText2 (" BRN"/" FRZ"/" QUIT") at hlcoord 6, 2.  LEFT/RIGHT
+-- move wTopMenuItemX between those two columns and swap wMenuItemOffset
+-- between 0 and 3 while leaving wCurrentMenuItem (the row) alone; UP/DOWN
+-- are not in wMenuWatchedKeys, so they only slide the cursor and loop.
+local BOARD_LABELS = {}
+for i, row in ipairs(STATUS_LABELS) do BOARD_LABELS[i] = row[1] end
+BOARD_LABELS[#BOARD_LABELS + 1] = " QUIT"
+local BOARD_COL_X = { 1, 6 }
+local BOARD_ROW_Y = 2
+local BOARD_ROWS = 3
+
+local StatusBoard = {}
+StatusBoard.__index = StatusBoard
+
+function StatusBoard.new(game, onPick, onQuit)
+  return setmetatable({ game = game, col = 1, row = 1, labels = BOARD_LABELS,
+                        onPick = onPick, onQuit = onQuit }, StatusBoard)
+end
+
+-- flat index = pokered's wMenuItemOffset (0 or 3) + wCurrentMenuItem (0..2),
+-- so 1..5 are the statuses in ViridianBlackboardStatusPointers order and 6
+-- is QUIT
+function StatusBoard:selection()
+  return (self.col - 1) * BOARD_ROWS + self.row
+end
+
+function StatusBoard:update()
+  local input = self.game.input
+  if input:wasPressed("up") then
+    -- wMenuWrappingEnabled is never set here, so both ends are hard stops
+    if self.row > 1 then self.row = self.row - 1 end
+  elseif input:wasPressed("down") then
+    if self.row < BOARD_ROWS then self.row = self.row + 1 end
+  elseif input:wasPressed("left") then
+    self.col = 1
+  elseif input:wasPressed("right") then
+    self.col = 2
+  elseif input:wasPressed("a") or input:wasPressed("b") then
+    -- HandleMenuInput_ (home/window.asm) beeps for the PAD_A | PAD_B branch,
+    -- and B and QUIT share .exitBlackboard
+    require("src.core.Sound").play(self.game.data, "Press_AB")
+    local sel = self:selection()
+    if input:wasPressed("b") or sel > #STATUS_LABELS then
+      self.onQuit()
+    else
+      self.onPick(sel)
+    end
+  end
+end
+
+function StatusBoard:draw()
+  Font.drawBox(0, 0, 12, 8)
+  love.graphics.setColor(0, 0, 0, 1)
+  for i, label in ipairs(BOARD_LABELS) do
+    local col = i <= BOARD_ROWS and 1 or 2
+    local row = i - (col - 1) * BOARD_ROWS
+    Font.draw(label, BOARD_COL_X[col] * 8, (BOARD_ROW_Y + row - 1) * 8)
+  end
+  -- wTopMenuItemX equals the column PlaceString started at, so the cursor
+  -- covers the blank each label leads with
+  Font.drawCode(Theme.cursor, BOARD_COL_X[self.col] * 8,
+                (BOARD_ROW_Y + self.row - 1) * 8)
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
 local function blackboard(game)
   local text = game.data.text or {}
-  local items, showMenu, askHeading
-  function showMenu()
-    game.stack:push(Menu.new(game, items,
-      { tx = 0, ty = 0, tw = 12, th = 8, rowStep = 1 }))
+  local openBoard
+  -- wCurrentMenuItem / wMenuItemOffset are zeroed once, above .blackboardLoop,
+  -- and nothing inside the loop clears them again: after a status blurb
+  -- `jp .blackboardLoop` comes back with the cursor still on the row and
+  -- column the player just picked.  One StatusBoard lives for the whole
+  -- reading and is re-pushed each pass, so only entering the blackboard
+  -- resets to the left column / top row (#591).
+  local board
+  -- .blackboardLoop reprints ViridianSchoolBlackboardText2 and only then
+  -- calls HandleMenuInput, so the prompt is on screen for exactly as long as
+  -- the headings list is.  That text ends in `done`, not `prompt`
+  -- (data/text/text_2.asm:646), so PrintText returns with the box still up
+  -- and never waits for a button: TextBox opts.stay holds it open under the
+  -- list and these callbacks pop the pair together (#591).
+  local function closeBoard()
+    game.stack:pop() -- the headings list
+    game.stack:pop() -- the held "Which heading" box under it
   end
-  -- ViridianSchoolBlackboardText2 is reprinted on every .blackboardLoop
-  -- pass, immediately before HandleMenuInput
-  function askHeading()
+  local function pick(i)
+    closeBoard()
+    game.stack:push(TextBox.new(game,
+      text[STATUS_LABELS[i][2]] or STATUS_LABELS[i][1], openBoard))
+  end
+  function openBoard()
     game.stack:push(TextBox.new(game,
       text._ViridianSchoolBlackboardText2 or "Which heading do\nyou want to read?",
-      showMenu))
+      nil, { stay = { onShown = function()
+        board = board or StatusBoard.new(game, pick, closeBoard)
+        game.stack:push(board)
+      end } }))
   end
-  items = {}
-  for i, row in ipairs(STATUS_LABELS) do
-    local label, key = row[1], row[2]
-    items[i] = { label = label, onSelect = function()
-      game.stack:push(TextBox.new(game, text[key] or label, askHeading))
-    end }
-  end
-  -- no onSelect: Menu's own pop closes the box, matching .exitBlackboard
-  items[#items + 1] = { label = " QUIT" }
   game.stack:push(TextBox.new(game,
     text._ViridianSchoolBlackboardText1
       or "The blackboard\ndescribes POKéMON\vSTATUS changes\vduring battles.",
-    askHeading))
+    openBoard))
 end
 
 -- ViridianSchoolNotebook (engine/events/hidden_events/school_notebooks.asm):

data/scripts/flavor_all.lua

@@ -15,6 +15,7 @@ local files = {
   "data.scripts.flavor.cerulean_trashed_house",
   "data.scripts.flavor.copycats_house_1f",
   "data.scripts.flavor.copycats_house_2f",
+  "data.scripts.flavor.fuchsia_city",
   "data.scripts.flavor.game_corner",
   "data.scripts.flavor.lavender_cubone_house",
   "data.scripts.flavor.lavender_mart",

data/scripts/gyms.lua

@@ -18,6 +18,26 @@ local M = {
   VIRIDIAN_GYM  = { city = "VIRIDIAN CITY",  leader = "GIOVANNI", badge = "EARTHBADGE" },
 }
 
+-- The originals' middle branch shared by every leader's text_asm: beaten
+-- but EVENT_GOT_TM* unset means the bag was full when the victory script
+-- ran GiveItem, so talking to the leader re-runs the ReceiveTM script.
+-- Returns true when the retry took over the talk.  A save from before
+-- #797 already holds the TM without the flag; treat the owned TM as
+-- received so those saves fall through to the advice text instead of
+-- collecting a second copy.
+local function retryTmGive(game, ow, victoryKey, done)
+  local reward = require("data.scripts.victories")[victoryKey]
+  if not (reward and reward.gotFlag) then return false end
+  if game.save.flags[reward.gotFlag] then return false end
+  local owned = game.save.inventory and game.save.inventory[reward.item] or 0
+  if owned > 0 then
+    game.save.flags[reward.gotFlag] = true
+    return false
+  end
+  ow:offerGymTm(reward, done)
+  return true
+end
+
 -- scripts/PewterGym.asm PewterGymBrockText (text_asm): CheckEvent
 -- EVENT_BEAT_BROCK branches his dialogue.  Before the badge he prints
 -- _PewterGymBrockPreBattleText and engages the leader battle
@@ -25,12 +45,14 @@ local M = {
 -- badge/TM34 rewards and EVENT_BEAT_BROCK come from
 -- data/scripts/victories.lua OPP_BROCK#1).  After the badge his
 -- .afterBeat branch prints _PewterGymBrockPostBattleAdviceText ("Go to
--- the GYM in CERULEAN...").  The original's middle branch (beat but
--- TM34 not yet handed over, CheckEventReuseA EVENT_GOT_TM34) is
--- unreachable in the port: the TM is granted with the victory.
+-- the GYM in CERULEAN...").  The middle branch (beat but TM34 not yet
+-- handed over, CheckEventReuseA EVENT_GOT_TM34 -> call
+-- PewterGymScriptReceiveTM34) retries the TM give when the bag was full
+-- at the victory (#797).
 M.PEWTER_GYM.talk = {
   TEXT_PEWTERGYM_BROCK = function(game, ow, npc, done)
     if game.save.flags.EVENT_BEAT_BROCK then
+      if retryTmGive(game, ow, "OPP_BROCK#1", done) then return end
       local TextBox = require("src.render.TextBox")
       game.stack:push(TextBox.new(game,
         game.data.text._PewterGymBrockPostBattleAdviceText
@@ -48,16 +70,17 @@ M.PEWTER_GYM.talk = {
 -- (engageTrainer shows that same pre-battle text via resolveText; the
 -- badge/TM rewards and the beat flag come from data/scripts/victories.lua)
 -- -- and once beaten print the post-battle advice text.  As with Brock,
--- the originals' middle branch (beaten but the TM not yet handed over,
--- CheckEventReuseA EVENT_GOT_TM*) is unreachable in the port: the TM is
--- granted with the victory.
+-- the middle branch (beaten but the TM not yet handed over,
+-- CheckEventReuseA EVENT_GOT_TM*) retries the TM give when the bag was
+-- full at the victory.
 -- afterAdvice, when given, takes over `done`: it is handed (game, ow, npc,
 -- done) and must call done() itself once whatever it's doing (e.g. a fade
 -- around a HideObject) finishes, rather than having it invoked
 -- automatically. Only Giovanni's farewell uses this.
-local function leaderTalk(beatFlag, adviceLabel, fallback, afterAdvice)
+local function leaderTalk(beatFlag, adviceLabel, fallback, afterAdvice, victoryKey)
   return function(game, ow, npc, done)
     if game.save.flags[beatFlag] then
+      if victoryKey and retryTmGive(game, ow, victoryKey, done) then return end
       local TextBox = require("src.render.TextBox")
       local finish = done
       if afterAdvice then
@@ -79,42 +102,42 @@ end
 M.CERULEAN_GYM.talk = {
   TEXT_CERULEANGYM_MISTY = leaderTalk("EVENT_BEAT_MISTY",
     "_CeruleanGymMistyTM11ExplanationText",
-    "TM11 teaches\nBUBBLEBEAM!"),
+    "TM11 teaches\nBUBBLEBEAM!", nil, "OPP_MISTY#1"),
 }
 
 -- scripts/VermilionGym.asm VermilionGymLTSurgeText .got_tm24_already
 M.VERMILION_GYM.talk = {
   TEXT_VERMILIONGYM_LT_SURGE = leaderTalk("EVENT_BEAT_LT_SURGE",
     "_VermilionGymLTSurgePostBattleAdviceText",
-    "A little word of\nadvice, kid!"),
+    "A little word of\nadvice, kid!", nil, "OPP_LT_SURGE#1"),
 }
 
 -- scripts/CeladonGym.asm CeladonGymErikaText .afterBeat
 M.CELADON_GYM.talk = {
   TEXT_CELADONGYM_ERIKA = leaderTalk("EVENT_BEAT_ERIKA",
     "_CeladonGymErikaPostBattleAdviceText",
-    "You are cataloging\nPOKéMON? I must\nsay I'm impressed."),
+    "You are cataloging\nPOKéMON? I must\nsay I'm impressed.", nil, "OPP_ERIKA#1"),
 }
 
 -- scripts/FuchsiaGym.asm FuchsiaGymKogaText .afterBeat
 M.FUCHSIA_GYM.talk = {
   TEXT_FUCHSIAGYM_KOGA = leaderTalk("EVENT_BEAT_KOGA",
     "_FuchsiaGymKogaPostBattleAdviceText",
-    "When afflicted by\nTOXIC, POKéMON\nsuffer more and\nmore as battle\nprogresses!"),
+    "When afflicted by\nTOXIC, POKéMON\nsuffer more and\nmore as battle\nprogresses!", nil, "OPP_KOGA#1"),
 }
 
 -- scripts/SaffronGym.asm SaffronGymSabrinaText .afterBeat
 M.SAFFRON_GYM.talk = {
   TEXT_SAFFRONGYM_SABRINA = leaderTalk("EVENT_BEAT_SABRINA",
     "_SaffronGymSabrinaPostBattleAdviceText",
-    "Everyone has\npsychic power!\nPeople just don't\nrealize it!"),
+    "Everyone has\npsychic power!\nPeople just don't\nrealize it!", nil, "OPP_SABRINA#1"),
 }
 
 -- scripts/CinnabarGym.asm CinnabarGymBlaineText .afterBeat
 M.CINNABAR_GYM.talk = {
   TEXT_CINNABARGYM_BLAINE = leaderTalk("EVENT_BEAT_BLAINE",
     "_CinnabarGymBlainePostBattleAdviceText",
-    "FIRE BLAST is the\nultimate fire\ntechnique!"),
+    "FIRE BLAST is the\nultimate fire\ntechnique!", nil, "OPP_BLAINE#1"),
 }
 
 -- scripts/ViridianGym.asm ViridianGymGiovanniText .afterBeat: after the
@@ -142,7 +165,7 @@ M.VIRIDIAN_GYM.talk = {
             "VIRIDIAN_GYM", "VIRIDIANGYM_GIOVANNI")
         end
       end, done))
-    end),
+    end, "OPP_GIOVANNI#3"),
 }
 
 return M

data/scripts/init.lua

@@ -48,7 +48,8 @@ end
 if GameVersion.isYellow() then
   for _, file in ipairs({ "data.scripts.yellow_gifts",
                           "data.scripts.yellow_jessie_james",
-                          "data.scripts.yellow_beach_house" }) do
+                          "data.scripts.yellow_beach_house",
+                          "data.scripts.yellow_viridian_old_man" }) do
     for mapId, mod in pairs(require(file)) do
       MapScripts.attachBase(mapId, mod)
     end

data/scripts/oaks_lab.lua

@@ -22,10 +22,10 @@ local function starterBall(askText, species, choseFlag, ownBall,
                            rivalBallX, rivalBall)
   return {
     { "check_flag", "EVENT_GOT_STARTER" },        -- 1
-    { "jump_if_true", 20 },                       -- 2
+    { "jump_if_true", 22 },                       -- 2
     -- no picking until Oak has walked you in (OaksLabScript gating)
     { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB" }, -- 3
-    { "jump_if_false", 22 },                      -- 4
+    { "jump_if_false", 25 },                      -- 4
     -- the Pokédex "new species" entry shows before the ask (predef
     -- StarterDex ahead of OaksLabYouWant...Text).  StarterDex temporarily
     -- sets the owned bits so ShowPokedexData prints height/weight/text;
@@ -37,33 +37,41 @@ local function starterBall(askText, species, choseFlag, ownBall,
     -- OaksLab.asm prints ReceivedMon then AddPartyMon (AskName lives
     -- inside give_pokemon).  Show the received text first so the
     -- nickname prompt follows "you got X", matching Gen1.
-    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 8
-    { "give_pokemon", species, 5 },               -- 9
-    { "set_flag", "EVENT_GOT_STARTER" },          -- 10
-    { "set_flag", choseFlag },                    -- 11
+    -- The received text carries sound_get_key_item (OaksLab.asm
+    -- OaksLabReceivedMonText); the jingle plays as the box opens
+    -- (same beat as the Yellow port's starter, #668).
+    { "play_sound", "Get_Key_Item" },                              -- 8
+    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 9
+    { "give_pokemon", species, 5 },               -- 10
+    { "set_flag", "EVENT_GOT_STARTER" },          -- 11
+    { "set_flag", choseFlag },                    -- 12
     -- POKé BALLs are not handed out here in the original -- Oak gives
     -- them later, at OaksLabOak1Text's .give_poke_balls beat once the
     -- player has beaten the Route 22 rival (see TEXT_OAKSLAB_OAK1 below)
-    { "hide_object", "OAKS_LAB", ownBall },       -- 12
+    { "hide_object", "OAKS_LAB", ownBall },       -- 13
     -- the rival walks to the countering ball (around the furniture)
-    { "move_npc_to", 1, rivalBallX, 4 },          -- 13
-    { "face_object", 1, "up" },                   -- 14
-    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 15
-    { "hide_object", "OAKS_LAB", rivalBall },     -- 16
+    { "move_npc_to", 1, rivalBallX, 4 },          -- 14
+    { "face_object", 1, "up" },                   -- 15
+    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 16
+    { "hide_object", "OAKS_LAB", rivalBall },     -- 17
+    { "play_sound", "Get_Key_Item" },             -- 18 (sound_get_key_item)
     { "show_text", "_OaksLabRivalReceivedMonText",
       { RAM = rivalBall == "OAKSLAB_CHARMANDER_POKE_BALL" and "CHARMANDER"
               or rivalBall == "OAKSLAB_SQUIRTLE_POKE_BALL" and "SQUIRTLE"
-              or "BULBASAUR" } },                 -- 17
-    { "jump", "end" },                            -- 18
-    { "jump", "end" },                            -- 19 (spacer)
+              or "BULBASAUR" } },                 -- 19
+    { "jump", "end" },                            -- 20
+    { "jump", "end" },                            -- 21 (spacer)
     -- a leftover ball after the player's pick: Oak turns to face the
     -- player and reads the last-mon line instead of re-offering the
     -- starter (scripts/OaksLab.asm OaksLabSelectedPokeBallScript ->
     -- OaksLabLastMonScript; #601).  The ROM's "#MON" ligature is spelled
     -- out as Pokémon here.
-    { "face_object", 5, "down" },                 -- 20
-    { "show_text", "That's PROF.OAK's\nlast Pokémon!" }, -- 21
-    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 22
+    { "face_object", 5, "down" },                 -- 22
+    { "show_text", "That's PROF.OAK's\nlast Pokémon!" }, -- 23
+    -- OaksLabLastMonScript ends at TextScriptEnd; the port used to fall
+    -- through into the pre-pick line below (#601 remnant, reported on #600)
+    { "jump", "end" },                            -- 24
+    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 25
   }
 end
 
@@ -71,10 +79,22 @@ return {
   talk = {
     -- Oak: OaksLabOak1Text.  Parcel delivery kicks SCRIPT_OAKSLAB_RIVAL_
     -- ARRIVES_AT_OAKS_REQUEST + OaksLabOakGivesPokedexScript (rival walk-
-    -- in, full Pokédex speech, rival exit, Route 22 arm).  Dex-rating
-    -- (DisplayDexRating) is still skipped.
+    -- in, full Pokédex speech, rival exit, Route 22 arm).
     TEXT_OAKSLAB_OAK1 = {
       { "face_player" },
+      -- OaksLabOak1Text leads with the dex-rating branch (#600): with
+      -- EVENT_PALLET_AFTER_GETTING_POKEBALLS set (converted saves), or
+      -- 2+ species owned once the Pokédex is in hand, Oak asks how it is
+      -- coming and rates it (predef DisplayDexRating).  Red keeps the
+      -- GOT_POKEDEX gate that Yellow's copy of this text drops
+      -- (data/scripts/oaks_lab_yellow.lua).
+      { "check_flag", "EVENT_PALLET_AFTER_GETTING_POKEBALLS" },
+      { "jump_if_true", "dex_rating" },
+      { "check_dex_owned", 2 },
+      { "jump_if_false", "no_rating" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_true", "dex_rating" },
+      { "label", "no_rating" },
       { "check_item", "POKE_BALL" },
       { "jump_if_true", "come_see" },
       { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },
@@ -160,6 +180,14 @@ return {
 
       { "label", "come_see" },
       { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },
+      { "jump", "end" },
+
+      -- .HowIsYourPokedexComingText ends on `prompt` and OaksLabOak1Text
+      -- sets wDoNotWaitForButtonPressAfterDisplayingText, so the seen/owned
+      -- tally follows with no button wait (engine/events/pokedex_rating.asm)
+      { "label", "dex_rating" },
+      { "show_text", "_OaksLabOak1HowIsYourPokedexComingText" },
+      { "dex_rating" },
     },
 
     TEXT_OAKSLAB_CHARMANDER_POKE_BALL =
@@ -254,7 +282,12 @@ return {
        and y >= 6 then
       local rival = ow:npcByIndex(1)
       if not rival then return false end
+      -- OaksLabRivalChallengesPlayerScript swaps in the rival encounter
+      -- fanfare for the taunt/challenge exchange, same as the Yellow port
+      -- (oaks_lab_yellow.lua); it was silently dropped here (#596).
       local rows = {
+        { "stop_music" },
+        { "play_music", "Music_MeetRival" },
         { "show_text", "_OaksLabRivalIllTakeYouOnText" },         -- 1
       }
       -- the rival routes to a free cell beside the player
@@ -292,8 +325,15 @@ return {
       table.insert(rows, { "jump_if_false", base + 6 })
       table.insert(rows, { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
       table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
+      -- OaksLabRivalStartsExitScript: parting shot, rival exit fanfare, then
+      -- walk out past the player.  The fanfare was dropped here (#683) -- the
+      -- parcel scene above already plays Music_MeetRival on both arrival and
+      -- departure (lines 144-146), and this exit should match (#596).
+      table.insert(rows, { "stop_music" })
+      table.insert(rows, { "play_music", "Music_MeetRival" })
       table.insert(rows, { "move_npc_to", 1, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
+      table.insert(rows, { "play_music", "Music_OaksLab" })
       ow.runner:run(rows, { npc = rival })
       return true
     end

data/scripts/oaks_lab_yellow.lua

@@ -71,8 +71,12 @@ return {
       { "show_text", "_OaksLabRivalLeaveItAllToMeText" },
       { "set_flag", "EVENT_GOT_POKEDEX" },
       { "set_flag", "EVENT_OAK_GOT_PARCEL" },
+      -- OaksLabOakGivesPokedexScript: HideObject TOGGLE_LYING_OLD_MAN /
+      -- ShowObject TOGGLE_OLD_MAN_2 -- Yellow's tutorial old man stands
+      -- on the sleeper's cell (18,9); the Red/Blue walker OLD_MAN at
+      -- (17,5) never appears in Yellow (#617)
       { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" },
-      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN" },
+      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN2" },
       { "stop_music" },
       { "play_music", "Music_MeetRival" },
       { "move_npc_to", RIVAL, 4, 7 },
@@ -283,10 +287,12 @@ return {
       table.insert(rows, { "label", "lost_lab" })
       table.insert(rows, { "set_field", "rivalStarter", 3 })
       table.insert(rows, { "label", "exit" })
-      -- OaksLabRivalStartsExitScript: parting shot, walk out past the
-      -- player, restore the lab theme
+      -- OaksLabRivalStartsExitScript: parting shot, rival exit fanfare, then
+      -- walk out past the player (#683).
       table.insert(rows, { "wait", 20 })
       table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
+      table.insert(rows, { "stop_music" })
+      table.insert(rows, { "play_music", "Music_MeetRival" })
       table.insert(rows, { "move_npc_to", RIVAL, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
       table.insert(rows, { "play_music", "Music_OaksLab" })

data/scripts/safari.lua

@@ -4,9 +4,11 @@
 -- (.PlayerNextToSafariZoneWorker1CoordsArray).  Paying ¥500 hands over
 -- 30 SAFARI BALLs and starts the 502-step game
 -- (SafariZoneGateWouldYouLikeToJoinScript: wSafariSteps = 502,
--- wNumSafariBalls = SAFARI_BALLS_RECEIVED).  Declining walks you back
--- so you can't slip past.  Returning to the gate ends the game and the
--- worker takes the leftover balls back.
+-- wNumSafariBalls = SAFARI_BALLS_RECEIVED), then auto-walks the player
+-- up through the north warp into the zone.  Declining walks you back
+-- so you can't slip past.  Returning to the gate ends the game, the
+-- worker takes the leftover balls back and the auto-walk drops you 3
+-- cells below the warp you came in by (#540).
 --
 -- Step/ball bookkeeping lives in src/world/OverworldController.lua
 -- (safariStep/safariGameOver, from
@@ -19,7 +21,33 @@ local FEE = 500
 local BALLS = 30
 local STEPS = 502
 
-local function startGame(game, t, done, balls, introText)
+-- SafariZoneGateSafariZoneWorker1WouldYouLikeToJoinText .success closes with
+-- `ld a, PAD_UP / ld c, 3 / SafariZoneEntranceAutoWalk`: paying walks the
+-- player up out of the gate and through the north warp, it is never left to
+-- the player.  EVENT_IN_SAFARI_ZONE is already set when that walk runs, so
+-- the two gate steps taken before the warp fires are charged against
+-- wSafariSteps (home/overworld.asm:307-310) -- which is why the counter
+-- reads 500/500 on arrival even though the script wrote 502 (#540).  The
+-- port's counter only runs on the nine interior maps (FieldDefaults
+-- safari.stepMaps, OverworldState:inSafariStepZone), so charge those two
+-- steps here instead.
+local function walkIntoZone(game, ow)
+  local p = ow.player
+  -- only from the two trigger cells in front of the worker, which are the
+  -- columns the north warps sit on; a player who paid after TALKING to him
+  -- from somewhere else walks in on their own, as they do today
+  local w = p.cellY == 2 and ow.map:warpAtCell(p.cellX, 0) or nil
+  if not w then return end
+  ow:scriptMove(p, "up", 2, function()
+    local st = game.save.safari
+    if st then st.steps = st.steps - 2 end
+    -- scripted steps skip onStepComplete (and with it CheckWarpsNoCollision),
+    -- so take that warp explicitly once the walk lands on it
+    ow:takeWarp(w.def)
+  end)
+end
+
+local function startGame(game, ow, t, done, balls, introText)
   game.save.safari = { balls = balls or BALLS, steps = STEPS }
   game.save.safariNags = nil
   local TextBox = require("src.render.TextBox")
@@ -31,7 +59,10 @@ local function startGame(game, t, done, balls, introText)
   local pa = t._SafariZoneGateSafariZoneWorker1CallYouOnThePAText
              or "\fWe'll call you on\nthe PA when you\nrun out of time\nor SAFARI BALLs!"
   local luck = t._SafariZoneGateSafariZoneWorker1GoodLuckText or "Good Luck!"
-  game.stack:push(TextBox.new(game, paid .. pa .. "\f" .. luck, done))
+  game.stack:push(TextBox.new(game, paid .. pa .. "\f" .. luck, function()
+    if done then done() end
+    walkIntoZone(game, ow)
+  end))
 end
 
 -- Yellow's soft-lock fix (scripts/SafariZoneGate_2.asm): a player short of
@@ -52,7 +83,7 @@ local function yellowLowCost(game, ow, t, done, back)
           or "\fOh, all right, pay\nme what you have.")
       .. "\f" .. (t._SafariZoneLowCostText2
                   or "But, I can't give\nyou all 30 BALLs.")
-    startGame(game, t, done, balls, intro)
+    startGame(game, ow, t, done, balls, intro)
     return
   end
   local nag = game.save.safariNags or 0
@@ -62,7 +93,7 @@ local function yellowLowCost(game, ow, t, done, back)
       (t._SafariZoneLowCostText8 or "Read my lips, NO!\nGet it?")
       .. (t._SafariZoneLowCostText3
           or "\fYou're persistent,\naren't you?\fOK, you can go in\nfor free, but\njust this once!")
-    startGame(game, t, done, 1, intro)
+    startGame(game, ow, t, done, 1, intro)
     return
   end
   local nags = {
@@ -100,7 +131,7 @@ local function joinPrompt(game, ow, done)
           end
         else
           game.save.money = game.save.money - FEE
-          startGame(game, t, done)
+          startGame(game, ow, t, done)
         end
       end))
     end))
@@ -135,27 +166,38 @@ M.SAFARI_ZONE_GATE = {
   -- no walks you back into the zone
   onEnter = function(game, ow)
     if not game.save.safari or ow.player.cellY > 1 then return end
-    local TextBox = require("src.render.TextBox")
-    local ChoiceBox = require("src.ui.ChoiceBox")
-    local t = game.data.text
-    game.stack:push(TextBox.new(game,
-      t._SafariZoneGateSafariZoneWorker1LeavingEarlyText or "Leaving early?",
-      function()
-        game.stack:push(ChoiceBox.new(game, function(yes)
-          if not yes then
-            -- back into the zone through the entrance warp
-            local w = game.data.maps.SAFARI_ZONE_CENTER.warps[1]
-            ow:startWarpTo("SAFARI_ZONE_CENTER", w.x, w.y, "up")
-            return
-          end
-          game.save.safari = nil
-          game.stack:push(TextBox.new(game,
-            (t._SafariZoneGateSafariZoneWorker1ReturnSafariBallsText
-             or "Please return any\nSAFARI BALLs you\nhave left.")
-            .. "\f" .. (t._SafariZoneGateSafariZoneWorker1GoodHaulComeAgainText
-                        or "Did you get a\ngood haul?\fCome again!")))
-        end))
-      end))
+    -- QUEUED, never pushed: onEnter runs inside the arriving warp's
+    -- Transition midpoint, and Transition:finish pops whatever is on top
+    -- the same frame (Timing.WARP_FADE_IN is 0) -- so a box pushed here is
+    -- swallowed, and on a build where it survived it drew over a screen
+    -- still faded to black (#540).  Same contract as M.HALL_OF_FAME in
+    -- data/scripts/story.lua.
+    --
+    -- SafariZoneGateLeavingSafariScript .leaving_early: YES prints the
+    -- return-balls text, faces the player down and runs
+    -- SafariZoneEntranceAutoWalk with `PAD_DOWN, c = 3`, landing on the
+    -- counter row 3 cells below the warp you came in by; NO prints
+    -- "Good Luck!" and walks one step back up through that same warp.
+    local rightSide = ow.player.cellX ~= 3
+    local dest = game.data.maps.SAFARI_ZONE_CENTER.warps[rightSide and 2 or 1]
+    ow:queueScript({
+      { "ask", "_SafariZoneGateSafariZoneWorker1LeavingEarlyText" },
+      { "jump_if_false", "stay" },
+      -- the port never reaches SafariZoneGateLeavingSafariScript's own
+      -- GOOD_HAUL_COME_AGAIN branch (safariGameOver warps straight to the
+      -- counter), so the sign-off rides on this path
+      { "show_text", "_SafariZoneGateSafariZoneWorker1ReturnSafariBallsText" },
+      { "show_text", "_SafariZoneGateSafariZoneWorker1GoodHaulComeAgainText" },
+      -- no value: set_field assigns nil, which is how save.safari is cleared
+      { "set_field", "safari" },
+      -- move_player runs through scriptMove, which skips onStepComplete, so
+      -- walking back down past (x,2) cannot re-fire the join trigger
+      { "move_player", "down", 3 },
+      { "jump", "end" },
+      { "label", "stay" },
+      { "show_text", "_SafariZoneGateSafariZoneWorker1GoodLuckText" },
+      { "warp", "SAFARI_ZONE_CENTER", dest.x, dest.y, "up" },
+    })
   end,
 }
 

data/scripts/seafoam.lua

@@ -11,7 +11,7 @@
 -- field.seafoam (SEAFOAM_ISLANDS_1F/B1F/B3F holes+holeDestination and
 -- B3F's pluggedByHolesOn) plus the generic
 -- OverworldState:boulderIntoHole in src/world/OverworldController.lua;
--- no per-map onEnter hook is needed here.
+-- no per-map onEnter hook is needed for the boulders.
 
 local M = {}
 
@@ -23,4 +23,46 @@ M.VERMILION_GYM = {
   end,
 }
 
+-- The PLAYER falling down those same holes (#599).  field.seafoam's holes
+-- carry only the BOULDER's object cell on the floor below (landsAt), not
+-- the player's landing, so the player's landing is spelled out here: it
+-- comes from data/maps/special_warps.asm DungeonWarpList/DungeonWarpData,
+-- which the importer does not extract.  Same shape as MANSION_HOLES in
+-- data/scripts/story6.lua and VICTORY_ROAD_3F.onStep in
+-- data/scripts/story.lua; CAVERN $22 is a walkable tile, so the fall has
+-- to be an onStep, not a collision block.
+--
+-- Sources: scripts/SeafoamIslands1F.asm Seafoam1HolesCoords (17,6)/(24,6),
+-- B1F.asm Seafoam2HolesCoords (18,6)/(23,6), B2F.asm Seafoam3HolesCoords
+-- (19,6)/(22,6), B3F.asm Seafoam4HolesCoords (3,16)/(6,16).  Each floor
+-- sets wDungeonWarpDestinationMap and calls IsPlayerOnDungeonWarp, and
+-- wCoordIndex picks that floor's DungeonWarpData row.  Unconditional in
+-- the original: a plugged hole still drops the player.  The B3F and B4F
+-- landings are water; setMap's CheckForceBikeOrSurf pass
+-- (OverworldState:checkForcedMovement) mounts SURF on arrival.
+local HOLE_FALLS = {
+  SEAFOAM_ISLANDS_1F  = { { 17, 6, "SEAFOAM_ISLANDS_B1F", 18, 7 },
+                          { 24, 6, "SEAFOAM_ISLANDS_B1F", 23, 7 } },
+  SEAFOAM_ISLANDS_B1F = { { 18, 6, "SEAFOAM_ISLANDS_B2F", 19, 7 },
+                          { 23, 6, "SEAFOAM_ISLANDS_B2F", 22, 7 } },
+  SEAFOAM_ISLANDS_B2F = { { 19, 6, "SEAFOAM_ISLANDS_B3F", 18, 7 },
+                          { 22, 6, "SEAFOAM_ISLANDS_B3F", 19, 7 } },
+  SEAFOAM_ISLANDS_B3F = { {  3, 16, "SEAFOAM_ISLANDS_B4F", 4, 14 },
+                          {  6, 16, "SEAFOAM_ISLANDS_B4F", 5, 14 } },
+}
+
+for mapId, holes in pairs(HOLE_FALLS) do
+  M[mapId] = M[mapId] or {}
+  M[mapId].onStep = function(game, ow, x, y)
+    for _, h in ipairs(holes) do
+      if x == h[1] and y == h[2] then
+        require("src.core.Sound").play(game.data, "Faint_Fall")
+        ow:startWarpTo(h[3], h[4], h[5], ow.player.facing)
+        return true
+      end
+    end
+    return false
+  end
+end
+
 return M

data/scripts/story.lua

@@ -188,7 +188,12 @@ M.BILLS_HOUSE = {
           end
           if ow.player.facing == "down" then
             -- the player is standing on his straight path: walk around
-            -- (.PokemonWalkAroundPlayerMovement)
+            -- (.PokemonWalkAroundPlayerMovement).  BillsHouseScript2 runs
+            -- BillsHousePikachuWatchPlayer first on this branch, so a
+            -- Pikachu that is still following steps clear of Bill's detour
+            -- and turns to watch the player (#455).
+            require("src.world.PikachuFollower")
+              .onBillWalksAroundPlayer(game, ow)
             ow:scriptMove(npc, "right", 1, function()
               ow:scriptMove(npc, "up", 2, function()
                 ow:scriptMove(npc, "left", 1, function()
@@ -600,12 +605,34 @@ local function snorlaxWake(mapId, objName, beatFlag, wokeUpText, calmedText)
   }
 end
 
+-- A beaten Snorlax is gone for good: Route12/Route16DefaultScript run
+-- HideObject in the same breath as the battle that sets
+-- EVENT_BEAT_ROUTEnn_SNORLAX, so "event set, object still on the map" is a
+-- state the asm cannot produce.  Here it can (a mod's world:toggleObject, a
+-- save edited or migrated from a build older than the flag), and it is a
+-- dead end: ItemEffects' adjacentSleepingSnorlax refuses to wake a Snorlax
+-- whose beat flag is set (ItemUsePokeFlute's CheckEvent, engine/items/
+-- item_effects.asm), so the sleeper sits in the road forever and Cycling
+-- Road is unreachable (#585).  Reconcile the toggle from the flag on every
+-- entry -- the mirror of SaveData.lua's toggle -> flag backfill, and the
+-- same repair shape the Silph Co. floors use below.
+local function hideBeatenSnorlax(mapId, objName, beatFlag)
+  return function(game, ow)
+    if not game.save.flags[beatFlag] then return end
+    local Commands = require("src.script.Commands")
+    Commands.hide_object({ game = game, save = game.save, overworld = ow },
+                         mapId, objName)
+  end
+end
+
 -- snorlaxWake is looked up by ItemEffects.lua/BagMenu.lua (via
 -- data/scripts/init.lua's M.get) and run when the flute wakes Snorlax;
 -- objName/beatFlag let ItemEffects find the NPC and check whether it's
 -- already been beaten before allowing the wake.
 M.ROUTE_12 = {
   talk = { TEXT_ROUTE12_SNORLAX = { { "show_text", "_Route12SnorlaxText" } } },
+  onEnter = hideBeatenSnorlax("ROUTE_12", "ROUTE12_SNORLAX",
+                              "EVENT_BEAT_ROUTE12_SNORLAX"),
   snorlaxWake = {
     objName = "ROUTE12_SNORLAX", beatFlag = "EVENT_BEAT_ROUTE12_SNORLAX",
     script = snorlaxWake("ROUTE_12", "ROUTE12_SNORLAX", "EVENT_BEAT_ROUTE12_SNORLAX",
@@ -614,6 +641,8 @@ M.ROUTE_12 = {
 }
 M.ROUTE_16 = {
   talk = { TEXT_ROUTE16_SNORLAX = { { "show_text", "_Route16Text7" } } },
+  onEnter = hideBeatenSnorlax("ROUTE_16", "ROUTE16_SNORLAX",
+                              "EVENT_BEAT_ROUTE16_SNORLAX"),
   snorlaxWake = {
     objName = "ROUTE16_SNORLAX", beatFlag = "EVENT_BEAT_ROUTE16_SNORLAX",
     script = snorlaxWake("ROUTE_16", "ROUTE16_SNORLAX", "EVENT_BEAT_ROUTE16_SNORLAX",
@@ -645,16 +674,18 @@ M.SAFARI_ZONE_SECRET_HOUSE = {
 M.WARDENS_HOUSE = {
   talk = {
     TEXT_WARDENSHOUSE_WARDEN = {
+      -- Labelled rather than hand-numbered: the branches here have been
+      -- re-pointed twice now (#535, #645), and every insert used to mean
+      -- renumbering three jumps that had no way of announcing they were stale.
       { "face_player" },                                             -- 1
       { "check_flag", "EVENT_GOT_HM04" },                            -- 2
       -- #535: previously jumped to the same silent-end target as the
-      -- give-then-thank fallthrough (row 13), so the warden said nothing
-      -- on every visit after the trade. pokered's .got_item branch
-      -- (scripts/WardensHouse.asm) instead prints HM04ExplanationText,
-      -- so route here to the new row 17 that does the same.
-      { "jump_if_true", 17 },                                        -- 3
+      -- give-then-thank fallthrough, so the warden said nothing on every
+      -- visit after the trade. pokered's .got_item branch
+      -- (scripts/WardensHouse.asm) instead prints HM04ExplanationText.
+      { "jump_if_true", "got_hm04" },                                -- 3
       { "check_item", "GOLD_TEETH" },                                -- 4
-      { "jump_if_false", 15 },                                       -- 5
+      { "jump_if_false", "no_teeth" },                               -- 5
       { "show_text", "_WardensHouseWardenGaveTheGoldTeethText" },    -- 6
       { "take_item", "GOLD_TEETH", 1 },                              -- 7
       { "set_flag", "EVENT_GAVE_GOLD_TEETH" },                       -- 8
@@ -663,15 +694,27 @@ M.WARDENS_HOUSE = {
       { "give_item", "HM_STRENGTH", 1, false },                      -- 10
       { "show_text", "_WardensHouseWardenReceivedHM04Text" },        -- 11
       { "set_flag", "EVENT_GOT_HM04" },                              -- 12
-      { "jump", 18 },                                                -- 13 (already got it this convo; jp .done)
-      { "jump", 18 },                                                -- 14 (unused)
-      { "show_text", "_WardensHouseWardenGibberish1Text" },          -- 15
-      { "jump", 18 },                                                -- 16 (#535: skip the new explanation row below)
+      { "jump", "end" },                                             -- 13 (jp .done)
+
+      -- #645: WardensHouseWardenText prints Gibberish1, then YesNoChoice,
+      -- and the warden answers the same gibberish either way -- Gibberish2
+      -- on yes, Gibberish3 on no (scripts/WardensHouse.asm).  The port
+      -- printed the question and walked off before the answer.
+      { "label", "no_teeth" },                                       -- 14
+      { "ask", "_WardensHouseWardenGibberish1Text" },                -- 15
+      { "jump_if_true", "gibberish_yes" },                           -- 16
+      { "show_text", "_WardensHouseWardenGibberish3Text" },          -- 17
+      { "jump", "end" },                                             -- 18
+      { "label", "gibberish_yes" },                                  -- 19
+      { "show_text", "_WardensHouseWardenGibberish2Text" },          -- 20
+      { "jump", "end" },                                             -- 21
+
       -- #535: pokered .got_item branch (scripts/WardensHouse.asm) --
       -- printed on every subsequent talk once EVENT_GOT_HM04 is set.
       -- Text is _WardensHouseWardenHM04ExplanationText (text/WardensHouse.asm):
       -- HM04 teaches Strength, and hints at the Safari Zone secret house.
-      { "show_text", "_WardensHouseWardenHM04ExplanationText" },     -- 17
+      { "label", "got_hm04" },                                       -- 22
+      { "show_text", "_WardensHouseWardenHM04ExplanationText" },     -- 23
     },
   },
 }
@@ -723,6 +766,28 @@ local function silphRocketsLeave(game, ow, onlyMap)
   end
 end
 
+-- SilphCo11FGiovanniAfterBattleScript (scripts/SilphCo11F.asm) is the whole
+-- aftermath: DisplayTextID TEXT_SILPHCO11F_GIOVANNI_YOU_RUINED_OUR_PLANS,
+-- GBFadeOutToBlack, SilphCo11FTeamRocketLeavesScript, Delay3,
+-- GBFadeInFromBlack, then SetEvent.  The port had only the hide pass, so the
+-- speech never played and every rocket blinked out in front of the player
+-- (#722).  Same hide list as silphRocketsLeave, spelled as script rows so the
+-- fade can hold over it.
+local function silphAftermathRows()
+  local rows = {
+    { "show_text", "_SilphCo11FGiovanniYouRuinedOurPlansText" },
+    { "fade", "out" },
+  }
+  for _, floor in ipairs(SILPH_ROCKET_OBJECTS) do
+    for _, name in ipairs(floor[2]) do
+      rows[#rows + 1] = { "hide_object", floor[1], name }
+    end
+  end
+  rows[#rows + 1] = { "wait", 3 }   -- Delay3
+  rows[#rows + 1] = { "fade", "in" }
+  return rows
+end
+
 M.SILPH_CO_11F = {
   -- Giovanni's battle is a COORDINATE TRIGGER, not a talk.
   -- SilphCo11FDefaultScript (scripts/SilphCo11F.asm) checks
@@ -735,9 +800,13 @@ M.SILPH_CO_11F = {
   -- line) would touch, and the whole Silph ending -- the flag, the Master
   -- Ball, the Saffron streets clearing -- silently never happened.
   --
-  -- engageTrainer shows TEXT_SILPHCO11F_GIOVANNI as the battle text and,
-  -- via victories.lua OPP_GIOVANNI#2, sets the event on a win; a loss
-  -- sets nothing, so the trigger re-arms exactly as vanilla does.
+  -- SilphCo11FDefaultScript orders it DisplayTextID TEXT_SILPHCO11F_GIOVANNI
+  -- FIRST, then MoveSprite .GiovanniMovement: he speaks from behind the desk
+  -- and only then walks the three tiles down.  Moving him before the box made
+  -- him cross the room in silence and deliver the speech point-blank (#869),
+  -- so the box comes first here and engageTrainer skips its own battle text.
+  -- victories.lua OPP_GIOVANNI#2 sets the event on a win; a loss sets
+  -- nothing, so the trigger re-arms exactly as vanilla does.
   onStep = function(game, ow, x, y)
     if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then return false end
     if not ((x == 6 and y == 13) or (x == 7 and y == 12)) then return false end
@@ -746,17 +815,28 @@ M.SILPH_CO_11F = {
       if npc.def and npc.def.name == "SILPHCO11F_GIOVANNI" then gio = npc break end
     end
     if not gio or ow:trainerDefeated(gio) then return false end
-    ow:scriptMove(gio, "down", 3, function()
-      gio:facePlayer(ow.player)
-      ow:engageTrainer(gio, function()
-        -- SilphCo11FTeamRocketLeavesScript: every Silph rocket leaves
-        -- after the loss (the street rockets are handled by
-        -- M.SAFFRON_CITY.onEnter in story4.lua).
-        if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
-          silphRocketsLeave(game, ow)
-        end
-      end)
-    end)
+    local TextBox = require("src.render.TextBox")
+    game.stack:push(TextBox.new(game,
+      game.data.text._SilphCo11FGiovanniText
+      or "Ah {PLAYER}!\nSo we meet again!",
+      function()
+        ow:scriptMove(gio, "down", 3, function()
+          gio:facePlayer(ow.player)
+          ow:engageTrainer(gio, function()
+            -- SilphCo11FGiovanniAfterBattleScript: the "Blast it all!"
+            -- speech, then SilphCo11FTeamRocketLeavesScript behind a fade so
+            -- every Silph rocket leaves off-screen (the street rockets are
+            -- handled by M.SAFFRON_CITY.onEnter in story4.lua).  Queued, not
+            -- run here: the battle's own callbacks are still unwinding, so
+            -- queueScript starts it on the first idle overworld frame --
+            -- after the end-battle "Arrgh!!" box victories.lua OPP_GIOVANNI#2
+            -- pushes (#722).
+            if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
+              ow:queueScript(silphAftermathRows())
+            end
+          end, nil, true)
+        end)
+      end))
     return true
   end,
   onEnter = function(game, ow)
@@ -899,6 +979,7 @@ M.VICTORY_ROAD_3F = {
   -- fall is onStep, not a collision block.
   onStep = function(game, ow, x, y)
     if x == 23 and y == 15 then
+      require("src.core.Sound").play(game.data, "Faint_Fall")
       ow:startWarpTo("VICTORY_ROAD_2F", 22, 16, ow.player.facing)
       return true
     end
@@ -937,40 +1018,72 @@ M.VICTORY_ROAD_3F = {
 local championsRoomRivalScript = {
   { "face_player" },                                        -- 1
   { "check_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },   -- 2
-  { "jump_if_true", 25 },                                   -- 3  past end
+  -- "end" rather than a row number past the tail: this script grew by a row
+  -- when the follow-Oak walk landed (#704), which silently turned the old
+  -- numeric 26 into a jump ONTO the closing HALL_OF_FAME warp instead of past
+  -- it, so a returning champion warped straight into the induction.
+  { "jump_if_true", "end" },                                -- 3
   { "show_text", "_ChampionsRoomRivalIntroText" },          -- 4
-  { "rival_battle", "OPP_RIVAL3", 1 },                      -- 5
-  { "jump_if_false", 25 },                                  -- 6  past end
-  { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },     -- 7
-  { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL" },              -- 8
+  -- ChampionsRoomRivalReadyToBattleScript plays MUSIC_FINAL_BATTLE after
+  -- the intro text, before the battle itself (#706); pushBattle's wipe-time
+  -- playBattle("final") then no-ops on the same song, so the theme stays
+  -- continuous into the fight
+  { "play_music", "Music_FinalBattle" },                    -- 5
+  { "rival_battle", "OPP_RIVAL3", 1 },                      -- 6
+  -- losing halts here; the numeric target this replaced pointed at the
+  -- closing warp, which inducted a player who had just lost the fight (#704)
+  { "jump_if_false", "end" },                               -- 7
+  { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL_THIS_RUN" },     -- 8
+  { "set_flag", "EVENT_BEAT_CHAMPION_RIVAL" },              -- 9
   -- ChampionsRoomRivalDefeatedScript re-displays TEXT_CHAMPIONSROOM_RIVAL,
   -- whose text_asm takes the EVENT_BEAT_CHAMPION_RIVAL branch =
   -- _ChampionsRoomRivalAfterBattleText (the in-battle _RivalDefeatedText
   -- is the port's generic "<PLAYER> defeated BLUE!" engine line instead).
-  { "show_text", "_ChampionsRoomRivalAfterBattleText" },    -- 9
+  { "show_text", "_ChampionsRoomRivalAfterBattleText" },    -- 10
   -- ChampionsRoomOakArrivesScript: Music_Cities1AlternateTempo
   -- (Cities1, kept into HALL_OF_FAME like BIT_NO_MAP_MUSIC after
-  -- defeating RIVAL3), then Oak's "{PLAYER}!" + reveal + walk in
-  { "play_music", "Music_Cities1", { keep = true } },       -- 10
-  { "show_text", "_ChampionsRoomOakText" },                 -- 11
-  { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 12
-  { "move_npc", 2, "up", 5 },                               -- 13 OakEntranceAfterVictoryMovement
+  -- defeating RIVAL3), then Oak's "{PLAYER}!" + reveal + walk in.
+  -- audio/alternate_tempo.asm Music_Cities1AlternateTempo is not a plain
+  -- PlayMusic: it fades the current song out (wAudioFadeOutControl = 10),
+  -- waits 100 frames for the fade, then restarts Cities1 with channel 1
+  -- pointed at Music_Cities1_Ch1_AlternateTempo -- `tempo 232` where the
+  -- normal Music_Cities1_Ch1 opens `tempo 144`, i.e. the slower, heavier
+  -- reading of the town theme this scene is known for (#847).
+  { "fade_music", 10 },                                     -- 11
+  { "wait", 100 },                                          -- 12
+  { "play_music", "Music_Cities1", { keep = true, tempo = 232 } }, -- 13
+  { "show_text", "_ChampionsRoomOakText" },                 -- 14
+  { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 15
+  { "move_npc", 2, "up", 5 },                               -- 16 OakEntranceAfterVictoryMovement
   -- OakCongratulatesPlayerScript: rival faces left, Oak faces down
-  { "face_object", 1, "left" },                             -- 14
-  { "face_object", 2, "down" },                             -- 15
-  { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 16
+  { "face_object", 1, "left" },                             -- 17
+  { "face_object", 2, "down" },                             -- 18
+  { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 19
   -- OakDisappointedWithRivalScript: Oak turns to the rival (right)
-  { "face_object", 2, "right" },                            -- 17
-  { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 18
+  { "face_object", 2, "right" },                            -- 20
+  { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 21
   -- OakComeWithMeScript: Oak faces down again, then exits up
-  { "face_object", 2, "down" },                             -- 19
-  { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 20
-  { "move_npc", 2, "up", 2 },                               -- 21 OakExitChampionsRoomMovement
-  { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 22
+  { "face_object", 2, "down" },                             -- 22
+  { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 23
+  { "move_npc", 2, "up", 2 },                               -- 24 OakExitChampionsRoomMovement
+  { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 25
+  -- ChampionsRoomPlayerFollowsOakScript / WalkToHallOfFame_RLEMovement
+  -- (PAD_UP 4, PAD_LEFT 1): the player walks out after Oak instead of the
+  -- screen just fading on the spot (#704).  The entrance walk leaves the
+  -- player at (4,3) and both north-wall warps sit on row 0, so the original
+  -- only ever spends three of those simulated steps -- CheckWarpsNoCollision
+  -- takes the HALL_OF_FAME warp the moment the walk lands on (4,0) and the
+  -- trailing UP/LEFT are dropped.  Scripted steps ignore collision here just
+  -- as they do in the original (CollisionCheckOnLand skips its checks while
+  -- wSimulatedJoypadStatesIndex is non-zero), so stepping through the
+  -- rival's cell at (4,2) is the ported behavior, not a clip.  Re-reported
+  -- as a clip in #847 and re-checked against home/overworld.asm
+  -- CollisionCheckOnLand, which is still the authority: do not "fix" it.
+  { "move_player", "up", 3 },                               -- 26
   -- hand the induction off to the HALL_OF_FAME room (consumed by its
   -- onEnter), then warp up into it (destWarp 1 lands at (4,7) facing up)
-  { "set_field", "pendingHallOfFame", true },               -- 23
-  { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 24
+  { "set_field", "pendingHallOfFame", true },               -- 27
+  { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 28
 }
 
 M.CHAMPIONS_ROOM = {

data/scripts/story3.lua

@@ -151,9 +151,27 @@ M.POKEMON_TOWER_6F = {
         -- trick, and the speedrun route this bot follows depends on it.
         if result == "win" or battle.pokeDollEscape then
           game.save.flags.EVENT_BEAT_GHOST_MAROWAK = true
-          game.stack:push(TextBox.new(game,
-            t._PokemonTower6FSoulWasCalmedText
-            or "The mother's soul\nwas calmed.\012It departed to\nthe afterlife!"))
+          -- PokemonTower6FMarowakDepartedText (scripts/PokemonTower6F.asm)
+          -- is two texts, not one: the CUBONE's-mother line first, then
+          -- PlayCry RESTLESS_SOUL (EQU MAROWAK, constants/pokemon_constants
+          -- .asm:209) + WaitForSoundToFinish + DelayFrames 30 before the
+          -- calmed line; the port dropped the first text and the cry
+          -- (#867).  play_cry arms the next show_text, so the cry rides
+          -- the calmed box's open with the button prompt kept, and the
+          -- wait row stands in for the asm's 30-frame gap.
+          local rows = {
+            { "show_text", t._PokemonTower6FGhostWasCubonesMotherText
+              or "The GHOST was the\nrestless soul of\vCUBONE's mother!" },
+            { "play_cry", "MAROWAK", true },
+            { "wait", 30 },
+            { "show_text", t._PokemonTower6FSoulWasCalmedText
+              or "The mother's soul\nwas calmed.\012It departed to\nthe afterlife!" },
+          }
+          if ow.runner then
+            ow.runner:run(rows)
+          elseif ow.queueScript then
+            ow:queueScript(rows)
+          end
         elseif result ~= "lose" then
           -- .did_not_defeat: one simulated step right, off the trigger,
           -- so fleeing does not leave you standing on a cell that
@@ -517,6 +535,14 @@ M.GAME_CORNER = {
         done()
         return
       end
+      -- GameCornerRocketText hands the battle its own loss line through
+      -- SaveEndBattleTextPointers (.BattleEndText ->
+      -- _GameCornerRocketBattleEndText, "Dang!"), and PrintEndBattleText
+      -- prints it ON the battle screen between TrainerDefeatedText and
+      -- MoneyForWinningText (engine/battle/core.asm TrainerBattleVictory).
+      -- He is a text_asm trainer with no def_trainers header, so there is no
+      -- header.won for engageTrainer to find and the line has to be handed
+      -- over here or it never shows at all (#862).
       ow:engageTrainer(npc, function()
         if not ow:trainerDefeated(npc) then
           done()
@@ -527,19 +553,44 @@ M.GAME_CORNER = {
           game.data.text._GameCornerRocketAfterBattleText
           or "Our hideout might\nbe discovered! I\nbetter tell BOSS!",
           function()
-            -- #198: GameCornerRocketExitScript (scripts/GameCorner.asm)
-            -- ApplyMovementData walks the grunt one tile UP into the poster
-            -- (the hideout's secret entrance at 9,4) before HideObject, so
-            -- he leaves the floor rather than popping out of existence on
-            -- (9,5).  scriptMove locks player input (#scriptMoves>0) and
-            -- ignores collision, so we despawn + unfreeze (done) only once
-            -- the step lands.
-            ow:scriptMove(npc, "up", 1, function()
-              hideRocket()
-              done()
-            end)
+            -- #198/#862: GameCornerRocketBattleScript (scripts/GameCorner.asm)
+            -- picks the exit walk from where the player is standing, because
+            -- the grunt on (9,5) has to get past him: wYCoord == 6 (talked to
+            -- from the south) or wXCoord == 8 (from the west) leaves the row
+            -- clear and takes GameCornerMovement_Rocket_WalkDirect, five steps
+            -- RIGHT; otherwise the player is east of him on (10,5) and
+            -- GameCornerMovement_Rocket_WalkAroundPlayer steps DOWN, right, UP
+            -- and right again to go AROUND him.  pokeyellow's copy of the
+            -- around-path takes one extra RIGHT on the lower row before coming
+            -- back up (it also has to clear Pikachu); both versions end on
+            -- (15,5).  He never steps UP: (9,4) is the poster wall, which is
+            -- where the old single UP step sent him.
+            local px = ow.player and ow.player.cellX
+            local py = ow.player and ow.player.cellY
+            local path
+            if py == 6 or px == 8 then
+              path = { { "right", 5 } }
+            elseif require("src.core.GameVersion").isYellow() then
+              path = { { "down", 1 }, { "right", 3 }, { "up", 1 }, { "right", 3 } }
+            else
+              path = { { "down", 1 }, { "right", 2 }, { "up", 1 }, { "right", 4 } }
+            end
+            -- GameCornerRocketExitScript only HideObjects him once
+            -- BIT_SCRIPTED_NPC_MOVEMENT clears, i.e. after the last step.
+            -- scriptMove locks player input (#scriptMoves>0) and ignores
+            -- collision, so the despawn + unfreeze (done) ride the final step.
+            local function step(i)
+              if i > #path then
+                hideRocket()
+                done()
+                return
+              end
+              ow:scriptMove(npc, path[i][1], path[i][2],
+                            function() step(i + 1) end)
+            end
+            step(1)
           end))
-      end)
+      end, game.data.text._GameCornerRocketBattleEndText or "Dang!")
     end,
     -- GameCornerClerk1Text (scripts/GameCorner.asm): the offer, a
     -- YesNoChoice, then ¥1000 for 50 coins.  Yellow drops the "1" from the
@@ -549,21 +600,57 @@ M.GAME_CORNER = {
     -- handler is bound to both text ids just below (#552).
     TEXT_GAMECORNER_CLERK1 = function(game, ow, npc, done)
       local TextBox = require("src.render.TextBox")
-      local ChoiceBox = require("src.ui.ChoiceBox")
+      local Font = require("src.render.Font")
+      local Strings = require("src.core.Strings")
       local t = game.data.text
       local function line(suffix, fallback)
         return t["_GameCornerClerk1" .. suffix]
                or t["_GameCornerClerk" .. suffix]
                or fallback
       end
+      -- GameCornerDrawCoinBox (scripts/GameCorner.asm; pokeyellow's copy is
+      -- identical): TextBoxBorder at hlcoord 11,0 with b=5 c=7, a 9x7-tile
+      -- window in the top right holding MONEY at (12,2) over the amount on
+      -- row 3 and COIN at (12,4) over the count on row 5.  Both
+      -- PrintBCDNumber calls pass LEADING_ZEROES, whose bit 7 SUPPRESSES
+      -- leading zeroes (home/print_bcd.asm), and neither passes LEFT_ALIGN,
+      -- so both numbers read plain and right-aligned against the inner edge
+      -- at column 18.  The asm draws the box before the offer and redraws it
+      -- after the purchase, so it stands for the whole exchange: a draw-only
+      -- state under the dialogue gets that lifetime, since StateStack draws
+      -- every state above the last opaque one and updates only the top
+      -- (src/core/StateStack.lua), and reading save each frame is the
+      -- redraw (#624).
+      local coinBox = { draw = function()
+        Font.drawBox(11, 0, 9, 7)
+        love.graphics.setColor(0, 0, 0, 1)
+        Font.draw(Strings("MONEY"), 96, 16)
+        local money = ("¥%d"):format(game.save.money or 0)
+        Font.draw(money, 152 - Font.width(money), 24)
+        Font.draw(Strings("COIN"), 96, 32)
+        local coins = ("%d"):format(game.save.coins or 0)
+        Font.draw(coins, 152 - Font.width(coins), 40)
+        love.graphics.setColor(1, 1, 1, 1)
+      end }
+      game.stack:push(coinBox)
+      -- Every branch below finishes here.  A TextBox pops itself before its
+      -- onDone runs, so the coin box is top of the stack again by then and
+      -- this pop takes it down, never someone else's state.
+      local function finish()
+        game.stack:pop()
+        done()
+      end
+      -- YesNoChoice is called with the offer still printed, so the prompt
+      -- has to ride the open text box (opts.choice) instead of being pushed
+      -- after it closes, which is what made the question vanish (#624).
       game.stack:push(TextBox.new(game,
         line("DoYouNeedSomeGameCoinsText",
-             "Do you need some\ngame coins?\f¥1000 for 50."), function()
-        game.stack:push(ChoiceBox.new(game, function(yes)
+             "Do you need some\ngame coins?\f¥1000 for 50."),
+        nil, { choice = function(yes)
           if not yes then
             game.stack:push(TextBox.new(game,
               line("PleaseComePlaySometimeText",
-                   "No? Please come\nplay sometime!"), done))
+                   "No? Please come\nplay sometime!"), finish))
             return
           end
           -- scripts/GameCorner.asm GameCornerClerk1Text: coins need
@@ -571,29 +658,30 @@ M.GAME_CORNER = {
           if not game.save.inventory.COIN_CASE then
             game.stack:push(TextBox.new(game,
               line("DontHaveCoinCaseText",
-                   "You don't have a\nCOIN CASE!"), done))
+                   "You don't have a\nCOIN CASE!"), finish))
             return
           end
           if (game.save.coins or 0) >= 9990 then
             game.stack:push(TextBox.new(game,
               line("CoinCaseIsFullText",
-                   "Oops! Your COIN\nCASE is full."), done))
+                   "Oops! Your COIN\nCASE is full."), finish))
             return
           end
           if game.save.money < 1000 then
             game.stack:push(TextBox.new(game,
               line("CantAffordTheCoinsText",
-                   "You can't afford\nthe coins!"), done))
+                   "You can't afford\nthe coins!"), finish))
             return
           end
           game.save.money = game.save.money - 1000
           game.save.coins = math.min(9999, (game.save.coins or 0) + 50)
+          -- the thanks text is the plain _GameCornerClerk1ThanksHereAre50-
+          -- CoinsText; the new count belongs in the coin box the asm
+          -- redraws here, not appended to the line (#624)
           game.stack:push(TextBox.new(game,
             line("ThanksHereAre50CoinsText",
-                 "Thanks! Here are\nyour 50 coins!")
-            .. ("\fCOINS: %d"):format(game.save.coins), done))
-        end))
-      end))
+                 "Thanks! Here are\nyour 50 coins!"), finish))
+        end }))
     end,
   },
 }
@@ -606,99 +694,188 @@ M.GAME_CORNER.talk.TEXT_GAMECORNER_CLERK =
   M.GAME_CORNER.talk.TEXT_GAMECORNER_CLERK1
 
 -- Game Corner prize lists (data/events/prizes.asm, prize_mon_levels.asm).
--- The six mon prizes differ between Red and Blue; the three TM prizes are
--- identical, so they are shared and appended to each version's mon list.
+-- Each counter owns ONE window of three prizes, not the whole catalogue:
+-- GetPrizeMenuId (engine/events/prize_menu.asm) subtracts
+-- TEXT_GAMECORNERPRIZEROOM_PRIZE_VENDOR_1 from hTextID and indexes
+-- PrizeDifferentMenuPtrs with the result, so vendor 1 sells
+-- PrizeMenuMon1Entries, vendor 2 PrizeMenuMon2Entries and vendor 3
+-- PrizeMenuTMsEntries (#623).  The mon windows and their levels differ per
+-- version; the TM window is identical in all three, so it is shared.
 local PRIZE_TMS = {
   { kind = "item", item = "TM_DRAGON_RAGE", cost = 3300 },
   { kind = "item", item = "TM_HYPER_BEAM", cost = 5500 },
   { kind = "item", item = "TM_SUBSTITUTE", cost = 7700 },
 }
-local RED_PRIZES = {
-  { kind = "mon", species = "ABRA", level = 9, cost = 180 },
-  { kind = "mon", species = "CLEFAIRY", level = 8, cost = 500 },
-  { kind = "mon", species = "NIDORINA", level = 17, cost = 1200 },
-  { kind = "mon", species = "DRATINI", level = 18, cost = 2800 },
-  { kind = "mon", species = "SCYTHER", level = 25, cost = 5500 },
-  { kind = "mon", species = "PORYGON", level = 26, cost = 9999 },
-  PRIZE_TMS[1], PRIZE_TMS[2], PRIZE_TMS[3],
+local RED_PRIZE_WINDOWS = {
+  {
+    { kind = "mon", species = "ABRA", level = 9, cost = 180 },
+    { kind = "mon", species = "CLEFAIRY", level = 8, cost = 500 },
+    { kind = "mon", species = "NIDORINA", level = 17, cost = 1200 },
+  },
+  {
+    { kind = "mon", species = "DRATINI", level = 18, cost = 2800 },
+    { kind = "mon", species = "SCYTHER", level = 25, cost = 5500 },
+    { kind = "mon", species = "PORYGON", level = 26, cost = 9999 },
+  },
+  PRIZE_TMS,
 }
-local BLUE_PRIZES = {
-  { kind = "mon", species = "ABRA", level = 6, cost = 120 },
-  { kind = "mon", species = "CLEFAIRY", level = 12, cost = 750 },
-  { kind = "mon", species = "NIDORINO", level = 17, cost = 1200 },
-  { kind = "mon", species = "PINSIR", level = 20, cost = 2500 },
-  { kind = "mon", species = "DRATINI", level = 24, cost = 4600 },
-  { kind = "mon", species = "PORYGON", level = 18, cost = 6500 },
-  PRIZE_TMS[1], PRIZE_TMS[2], PRIZE_TMS[3],
+local BLUE_PRIZE_WINDOWS = {
+  {
+    { kind = "mon", species = "ABRA", level = 6, cost = 120 },
+    { kind = "mon", species = "CLEFAIRY", level = 12, cost = 750 },
+    { kind = "mon", species = "NIDORINO", level = 17, cost = 1200 },
+  },
+  {
+    { kind = "mon", species = "PINSIR", level = 20, cost = 2500 },
+    { kind = "mon", species = "DRATINI", level = 24, cost = 4600 },
+    { kind = "mon", species = "PORYGON", level = 18, cost = 6500 },
+  },
+  PRIZE_TMS,
+}
+-- Yellow keeps the three windows but restocks both mon counters
+-- (pokeyellow/data/events/prizes.asm, prize_mon_levels.asm)
+local YELLOW_PRIZE_WINDOWS = {
+  {
+    { kind = "mon", species = "ABRA", level = 15, cost = 230 },
+    { kind = "mon", species = "VULPIX", level = 18, cost = 1000 },
+    { kind = "mon", species = "WIGGLYTUFF", level = 22, cost = 2680 },
+  },
+  {
+    { kind = "mon", species = "SCYTHER", level = 30, cost = 6500 },
+    { kind = "mon", species = "PINSIR", level = 30, cost = 6500 },
+    { kind = "mon", species = "PORYGON", level = 26, cost = 9999 },
+  },
+  PRIZE_TMS,
 }
 
-local function activePrizes()
-  return require("src.core.GameVersion").isBlue() and BLUE_PRIZES or RED_PRIZES
+local function prizeWindow(n)
+  local GameVersion = require("src.core.GameVersion")
+  local windows = RED_PRIZE_WINDOWS
+  if GameVersion.isBlue() then
+    windows = BLUE_PRIZE_WINDOWS
+  elseif GameVersion.isYellow() then
+    windows = YELLOW_PRIZE_WINDOWS
+  end
+  return windows[n]
 end
 
--- Prize counters (engine/menus/prize_menu.asm CeladonPrizeMenu; the prize
+-- Prize counters (engine/events/prize_menu.asm CeladonPrizeMenu; the prize
 -- list itself is data/events/prizes.asm, prize_mon_levels.asm).  Gen1 gates
 -- the prize window on the COIN CASE: it does IsItemInBag COIN_CASE first, and
 -- with no case prints RequireCoinCaseText and returns without ever opening a
 -- window; only with the case does it print ExchangeCoinsForPrizesText and then
 -- show the prizes.  #194: the port used to open the window unconditionally and
--- skip both text boxes.
-local function prizeCounter(game, ow, npc, done)
-  local ListMenu = require("src.ui.ListMenu")
-  local Commands = require("src.script.Commands")
-  local TextBox = require("src.render.TextBox")
-  local t = game.data.text
-  -- IsItemInBag COIN_CASE: without the case, deny and open no window
-  -- (COIN_CASE is a numeric count in save.inventory, nil when absent).
-  if not game.save.inventory.COIN_CASE then
+-- skip both text boxes.  wMaxMenuItem is 3, i.e. this window's three prizes
+-- plus the NO THANKS row, and HandlePrizeChoice confirms the pick with
+-- SoYouWantPrizeText + YesNoChoice before any coins move; every branch then
+-- rets out of CeladonPrizeMenu, so one transaction ends the conversation and
+-- buying again means talking to the counter again (#623).
+local function prizeCounter(window)
+  return function(game, ow, npc, done)
+    local ListMenu = require("src.ui.ListMenu")
+    local Commands = require("src.script.Commands")
+    local TextBox = require("src.render.TextBox")
+    local t = game.data.text
+    -- IsItemInBag COIN_CASE: without the case, deny and open no window
+    -- (COIN_CASE is a numeric count in save.inventory, nil when absent).
+    if not game.save.inventory.COIN_CASE then
+      game.stack:push(TextBox.new(game,
+        t._RequireCoinCaseText or "A COIN CASE is\nrequired!", done))
+      return
+    end
+    -- ExchangeCoinsForPrizesText plays before the prize window opens.
     game.stack:push(TextBox.new(game,
-      t._RequireCoinCaseText or "A COIN CASE is\nrequired!", done))
-    return
-  end
-  -- ExchangeCoinsForPrizesText plays before the prize window opens.
-  game.stack:push(TextBox.new(game,
-    t._ExchangeCoinsForPrizesText or "We exchange your\ncoins for prizes.",
-    function()
-      local items = {}
-      for _, p in ipairs(activePrizes()) do
-        local label
-        if p.kind == "mon" then
-          label = ("%s L%d"):format(game.data.pokemon[p.species].name, p.level)
-        else
-          label = game.data.items[p.item].name
+      t._ExchangeCoinsForPrizesText or "We exchange your\ncoins for prizes.",
+      function()
+        local items = {}
+        for _, p in ipairs(prizeWindow(window)) do
+          local label
+          if p.kind == "mon" then
+            label = ("%s L%d"):format(game.data.pokemon[p.species].name, p.level)
+          else
+            label = game.data.items[p.item].name
+          end
+          table.insert(items,
+            { label = label, right = tostring(p.cost), value = p })
         end
-        table.insert(items,
-          { label = label, right = tostring(p.cost), value = p })
-      end
-      local list
-      list = ListMenu.new(game, "PRIZES (COINS)", items, {
-        footer = ("COINS %d"):format(game.save.coins or 0),
-        onChoose = function(item)
-          local p = item.value
+        -- NoThanksText (data/events/prizes.asm) sits under the three prizes
+        table.insert(items, { label = "NO THANKS" })
+        local list
+        -- close the window first: every ending in HandlePrizeChoice leaves
+        -- the menu for good, and the closing line belongs over the map
+        local function finish(msg)
+          list:close()
+          game.stack:push(TextBox.new(game, msg, done))
+        end
+        local function buy(p)
           if (game.save.coins or 0) < p.cost then
-            list.footer = "Not enough coins!"
+            finish(t._SorryNeedMoreCoinsText or "Sorry, you need\nmore coins.")
+            return
+          end
+          -- HasEnoughCoins passed, so hand the prize over first and only
+          -- subtract once it landed: the asm rets before .subtractCoins when
+          -- the bag is full, or when both the party and every box are full
+          local roomless = t._OopsYouDontHaveEnoughRoomText
+                           or "Oops! You don't\nhave enough room."
+          if p.kind == "mon" then
+            -- no runner here, so give_pokemon reports through ctx.lastCheck
+            -- and skips the AskName prompt (Commands.give_pokemon)
+            local ctx = { save = game.save, game = game }
+            Commands.give_pokemon(ctx, p.species, p.level)
+            if not ctx.lastCheck then
+              finish(roomless)
+              return
+            end
+          elseif not require("src.inventory.Bag").add(
+              game.save, p.item, 1, game.data) then
+            finish(roomless)
             return
           end
           game.save.coins = game.save.coins - p.cost
-          if p.kind == "mon" then
-            Commands.give_pokemon({ save = game.save, game = game },
-                                  p.species, p.level)
-          else
-            game.save.inventory[p.item] = (game.save.inventory[p.item] or 0) + 1
-          end
-          list.footer = ("Got it! COINS %d"):format(game.save.coins)
-        end,
-        onCancel = done,
-      })
-      game.stack:push(list)
-    end))
+          -- no thank-you line: HereYouGoText is unreferenced in the asm,
+          -- which just redraws the coin box (PrintPrizePrice) and returns
+          list:close()
+          done()
+        end
+        list = ListMenu.new(game, "PRIZES (COINS)", items, {
+          footer = ("COINS %d"):format(game.save.coins or 0),
+          onChoose = function(item)
+            local p = item.value
+            if not p then -- NO THANKS is the B exit (cp 3 -> .noChoice)
+              list:close()
+              done()
+              return
+            end
+            local name = (p.kind == "mon")
+                         and game.data.pokemon[p.species].name
+                         or game.data.items[p.item].name
+            -- SoYouWantPrizeText names the prize out of wNameBuffer, which
+            -- is not one of TextBox's RAM tokens, so fill it in here
+            local ask = (t._SoYouWantPrizeText
+                         or "So, you want\n{RAM:wNameBuffer}?")
+                        :gsub("{RAM:wNameBuffer}", name)
+            game.stack:push(TextBox.new(game, ask, nil, {
+              choice = function(yes)
+                if not yes then
+                  finish(t._OhFineThenText or "Oh, fine then.")
+                  return
+                end
+                buy(p)
+              end,
+            }))
+          end,
+          onCancel = done,
+        })
+        game.stack:push(list)
+      end))
+  end
 end
 
 M.GAME_CORNER_PRIZE_ROOM = {
-  talk = { -- the three prize counters are bg events
-    TEXT_GAMECORNERPRIZEROOM_PRIZE_VENDOR_1 = prizeCounter,
-    TEXT_GAMECORNERPRIZEROOM_PRIZE_VENDOR_2 = prizeCounter,
-    TEXT_GAMECORNERPRIZEROOM_PRIZE_VENDOR_3 = prizeCounter,
+  talk = { -- the three prize counters are bg events, one window each
+    TEXT_GAMECORNERPRIZEROOM_PRIZE_VENDOR_1 = prizeCounter(1),
+    TEXT_GAMECORNERPRIZEROOM_PRIZE_VENDOR_2 = prizeCounter(2),
+    TEXT_GAMECORNERPRIZEROOM_PRIZE_VENDOR_3 = prizeCounter(3),
   },
 }
 

data/scripts/story4.lua

@@ -13,9 +13,18 @@ local function push(game, s, done)
   game.stack:push(TextBox.new(game, s, done))
 end
 
+-- The question stays on screen under the YES/NO menu.  The dojo prize
+-- balls are the clearest case: FightingDojoHitmonleePokeBallText
+-- (scripts/FightingDojo.asm) is `call PrintText` on a text_end string --
+-- no prompt, so no WaitForTextScrollButtonPress -- immediately followed
+-- by `call YesNoChoice`, and InitYesNoTextBoxParameters
+-- (engine/menus/text_box.asm) puts the menu above the dialogue box
+-- rather than replacing it.  Ride TextBox's opts.choice, the same as
+-- Commands.ask, instead of popping the box with an A press and leaving a
+-- bare ChoiceBox over the overworld (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end
 
 -- fill the extracted text placeholders ({NUM:...}, {RAM:...}, {PLAYER})
@@ -155,19 +164,26 @@ local function dojoBall(species, ownBall, otherBall, askKey)
       push(game, "You'll have to\nbeat the master\nfirst!", done)
       return
     end
-    ask(game, t[askKey] or ("You want\n" .. species .. "?"), function(yes)
-      if not yes then done() return end
-      flags["EVENT_GOT_" .. species] = true
-      flags.EVENT_DEFEATED_FIGHTING_DOJO = true
-      local Commands = require("src.script.Commands")
-      local ctx = { save = game.save, game = game, overworld = ow }
-      Commands.give_pokemon(ctx, species, 30)
-      -- Hide ONLY the chosen ball; the other stays (FightingDojo.asm hides
-      -- just the picked object's index) and routes to the greedy line above
-      -- when talked to (#197).
-      Commands.hide_object(ctx, "FIGHTING_DOJO", ownBall)
-      push(game, ("%s got\n%s!"):format(game.save.player.name, species), done)
-    end)
+    -- Examining a ball shows that species' POKéDEX entry first
+    -- (DisplayPokedex in FightingDojo.asm, which also marks it seen),
+    -- then the yes/no take-it prompt (#853).
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.mark_seen(ctx, species)
+    local DexEntryMenu = require("src.ui.DexEntryMenu")
+    game.stack:push(DexEntryMenu.new(game, species, function()
+      ask(game, t[askKey] or ("You want\n" .. species .. "?"), function(yes)
+        if not yes then done() return end
+        flags["EVENT_GOT_" .. species] = true
+        flags.EVENT_DEFEATED_FIGHTING_DOJO = true
+        Commands.give_pokemon(ctx, species, 30)
+        -- Hide ONLY the chosen ball; the other stays (FightingDojo.asm hides
+        -- just the picked object's index) and routes to the greedy line above
+        -- when talked to (#197).
+        Commands.hide_object(ctx, "FIGHTING_DOJO", ownBall)
+        push(game, ("%s got\n%s!"):format(game.save.player.name, species), done)
+      end)
+    end))
   end
 end
 

data/scripts/story5.lua

@@ -49,7 +49,7 @@ local function gift(opts)
         end
       end)
     end
-    if opts.pre then say(opts.pre, "", give) else give() end
+    if opts.pre then say(opts.pre, opts.preFallback or "", give) else give() end
   end
 end
 
@@ -118,11 +118,21 @@ M.CINNABAR_LAB_METRONOME_ROOM = {
   },
 }
 
--- TM42 Dream Eater (scripts/ViridianCity.asm, the fisher; no pre text)
+-- TM42 Dream Eater (scripts/ViridianCity.asm, the fisher).  The fisher's
+-- YouCanHaveThisText prints before GiveItem, so this gift needs a pre
+-- text (#775).  Like the SilphCo2F worker (#393) that label carries no
+-- leading underscore, and on Red it sits outside the extractor's symbol
+-- set, so the literal from text/ViridianCity.asm rides along as the
+-- fallback; Yellow resolves the ROM string instead.
 M.VIRIDIAN_CITY = {
   talk = {
     TEXT_VIRIDIANCITY_FISHER = gift({
       flag = "EVENT_GOT_TM42", item = "TM_DREAM_EATER",
+      pre = "ViridianCityFisherYouCanHaveThisText",
+      preFallback = "Yawn!\nI must have dozed\voff in the sun."
+        .. "\fI had this dream\nabout a DROWZEE\veating my dream."
+        .. "\vWhat's this?\vWhere did this TM\vcome from?"
+        .. "\fThis is spooky!\nHere, you can\vhave this TM.",
       received = "_ViridianCityFisherReceivedTM42Text",
       explain = "_ViridianCityFisherTM42ExplanationText",
       noRoom = "_ViridianCityFisherTM42NoRoomText",
@@ -176,6 +186,20 @@ M.ROUTE_18_GATE_2F = {
       { "face_player" },
       { "trade", 6, "EVENT_TRADED_SLOWBRO_FOR_LICKITUNG" }, -- MARC
     },
+    -- Yellow replaces the youngster with a cook trading SPIKE
+    -- (TANGELA -> PARASECT): pokeyellow/scripts/Route18Gate2F.asm
+    -- Route18Gate2FCookText runs TRADE_FOR_SPIKE, index 6 in the Yellow
+    -- TradeMons table that Data:applyVersionedFieldData swaps in.  Red
+    -- maps have no COOK object here and Yellow maps have no YOUNGSTER,
+    -- so each version only ever fires its own row (#651).  Both rows
+    -- share the Red-flavoured done flag on purpose: a .sav tracks
+    -- "trade slot 6 completed" in one wCompletedInGameTradeFlags bit
+    -- either version reads, and the save codec maps that bit to this
+    -- flag name (src/save_convert/GenSave.lua EXTRA_FLAG_BITS).
+    TEXT_ROUTE18GATE2F_COOK = {
+      { "face_player" },
+      { "trade", 6, "EVENT_TRADED_SLOWBRO_FOR_LICKITUNG" }, -- SPIKE (Yellow)
+    },
   },
 }
 

data/scripts/story6.lua

@@ -12,9 +12,13 @@ local function push(game, s, done)
   game.stack:push(TextBox.new(game, s, done))
 end
 
+-- PrintText on a text_end string returns with the box still drawn and
+-- YesNoChoice then draws the menu above it (InitYesNoTextBoxParameters,
+-- engine/menus/text_box.asm); no A press clears the question first.  Ride
+-- TextBox's opts.choice, the same as Commands.ask (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end
 
 -- -------------------------------------------------------------------
@@ -118,6 +122,7 @@ local MANSION_HOLES = {
 M.POKEMON_MANSION_3F.onStep = function(game, ow, x, y)
   for _, h in ipairs(MANSION_HOLES) do
     if x == h[1] and y == h[2] then
+      require("src.core.Sound").play(game.data, "Faint_Fall")
       ow:startWarpTo(h[3], h[4], h[5], ow.player.facing)
       return true
     end

data/scripts/victories.lua

@@ -18,6 +18,16 @@
 -- script).  Leaders are not def_trainers entries, so engageTrainer has
 -- no header.won -- checkVictoryRewards shows this chain instead of a
 -- synthetic "received badge/TM" stub.
+--
+-- Gym entries split the TM hand-over out of `dialogue`, mirroring the
+-- originals' GiveItem check (`call GiveItem` / `jr nc, .BagFull`):
+-- `tmPre` is the ReceiveTM script's lead-in (badge info / "Wait! Take
+-- this!"), shown at the victory and again when a beaten leader retries
+-- the hand-over; `tmDialogue` shows only when the TM actually goes in
+-- the bag; `noRoom` is the "make room" line shown instead when the bag
+-- is full; `gotFlag` (pokered's EVENT_GOT_TM*) is set only on a
+-- successful give, which is what makes the leader's talk script retry
+-- later (gyms.lua).
 
 local function range(prefix, first, last)
   local t = {}
@@ -33,6 +43,8 @@ return {
   -- escort NPC and the first Route 22 rival stay gone after the badge.
   ["OPP_BROCK#1"] = { badge = "BOULDERBADGE", flag = "EVENT_BEAT_BROCK",
                       item = "TM_BIDE",
+                      gotFlag = "EVENT_GOT_TM34",
+                      noRoom = "_PewterGymTM34NoRoomText",
                       deactivate = { "EVENT_BEAT_PEWTER_GYM_TRAINER_0" },
                       hide = {
                         { "PEWTER_CITY", "PEWTERCITY_YOUNGSTER" },
@@ -41,75 +53,113 @@ return {
                       dialogue = {
                         "_PewterGymBrockReceivedBoulderBadgeText",
                         "_PewterGymBrockBoulderBadgeInfoText",
-                        "_PewterGymBrockWaitTakeThisText",
+                      },
+                      tmPre = { "_PewterGymBrockWaitTakeThisText" },
+                      tmDialogue = {
                         "_PewterGymReceivedTM34Text",
                         "_TM34ExplanationText",
                       } },
   ["OPP_MISTY#1"] = { badge = "CASCADEBADGE", flag = "EVENT_BEAT_MISTY",
                       item = "TM_BUBBLEBEAM",
+                      gotFlag = "EVENT_GOT_TM11",
+                      noRoom = "_CeruleanGymMistyTM11NoRoomText",
                       deactivate = range("EVENT_BEAT_CERULEAN_GYM_TRAINER_", 0, 1),
                       dialogue = {
                         "_CeruleanGymMistyReceivedCascadeBadgeText",
-                        "_CeruleanGymMistyCascadeBadgeInfoText",
+                      },
+                      tmPre = { "_CeruleanGymMistyCascadeBadgeInfoText" },
+                      tmDialogue = {
                         "_CeruleanGymMistyReceivedTM11Text",
                       } },
   ["OPP_LT_SURGE#1"] = { badge = "THUNDERBADGE", flag = "EVENT_BEAT_LT_SURGE",
                          item = "TM_THUNDERBOLT",
+                         gotFlag = "EVENT_GOT_TM24",
+                         noRoom = "_VermilionGymLTSurgeTM24NoRoomText",
                          deactivate = range("EVENT_BEAT_VERMILION_GYM_TRAINER_", 0, 2),
                          dialogue = {
                            "_VermilionGymLTSurgeReceivedThunderBadgeText",
-                           "_VermilionGymLTSurgeThunderBadgeInfoText",
+                         },
+                         tmPre = { "_VermilionGymLTSurgeThunderBadgeInfoText" },
+                         tmDialogue = {
                            "_VermilionGymLTSurgeReceivedTM24Text",
                            "_TM24ExplanationText",
                          } },
   ["OPP_ERIKA#1"] = { badge = "RAINBOWBADGE", flag = "EVENT_BEAT_ERIKA",
                       item = "TM_MEGA_DRAIN",
+                      gotFlag = "EVENT_GOT_TM21",
+                      noRoom = "_CeladonGymTM21NoRoomText",
                       deactivate = range("EVENT_BEAT_CELADON_GYM_TRAINER_", 0, 6),
                       dialogue = {
                         "_CeladonGymErikaReceivedRainbowBadgeText",
-                        "_CeladonGymRainbowBadgeInfoText",
+                      },
+                      tmPre = { "_CeladonGymRainbowBadgeInfoText" },
+                      tmDialogue = {
                         "_CeladonGymReceivedTM21Text",
                         "_TM21ExplanationText",
                       } },
   ["OPP_KOGA#1"] = { badge = "SOULBADGE", flag = "EVENT_BEAT_KOGA",
                      item = "TM_TOXIC",
+                     gotFlag = "EVENT_GOT_TM06",
+                     noRoom = "_FuchsiaGymKogaTM06NoRoomText",
                      deactivate = range("EVENT_BEAT_FUCHSIA_GYM_TRAINER_", 0, 5),
                      dialogue = {
                        "_FuchsiaGymKogaReceivedSoulBadgeText",
-                       "_FuchsiaGymKogaSoulBadgeInfoText",
+                     },
+                     tmPre = { "_FuchsiaGymKogaSoulBadgeInfoText" },
+                     tmDialogue = {
                        "_FuchsiaGymKogaReceivedTM06Text",
                        "_FuchsiaGymKogaTM06ExplanationText",
                      } },
   ["OPP_SABRINA#1"] = { badge = "MARSHBADGE", flag = "EVENT_BEAT_SABRINA",
                         item = "TM_PSYWAVE",
+                        gotFlag = "EVENT_GOT_TM46",
+                        noRoom = "_SaffronGymSabrinaTM46NoRoomText",
                         deactivate = range("EVENT_BEAT_SAFFRON_GYM_TRAINER_", 0, 6),
                         dialogue = {
                           "_SaffronGymSabrinaReceivedMarshBadgeText",
-                          "_SaffronGymSabrinaMarshBadgeInfoText",
+                        },
+                        tmPre = { "_SaffronGymSabrinaMarshBadgeInfoText" },
+                        tmDialogue = {
                           "_SaffronGymSabrinaReceivedTM46Text",
                           "_TM46ExplanationText",
                         } },
   ["OPP_BLAINE#1"] = { badge = "VOLCANOBADGE", flag = "EVENT_BEAT_BLAINE",
                        item = "TM_FIRE_BLAST",
+                       gotFlag = "EVENT_GOT_TM38",
+                       noRoom = "_CinnabarGymBlaineTM38NoRoomText",
                        deactivate = range("EVENT_BEAT_CINNABAR_GYM_TRAINER_", 0, 6),
                        dialogue = {
                          "_CinnabarGymBlaineReceivedVolcanoBadgeText",
-                         "_CinnabarGymBlaineVolcanoBadgeInfoText",
+                       },
+                       tmPre = { "_CinnabarGymBlaineVolcanoBadgeInfoText" },
+                       tmDialogue = {
                          "_CinnabarGymBlaineReceivedTM38Text",
                          "_CinnabarGymBlaineTM38ExplanationText",
                        } },
   ["OPP_GIOVANNI#3"] = { badge = "EARTHBADGE", flag = "EVENT_BEAT_GIOVANNI",
                          item = "TM_FISSURE",
+                         gotFlag = "EVENT_GOT_TM27",
+                         noRoom = "_ViridianGymGiovanniTM27NoRoomText",
                          deactivate = range("EVENT_BEAT_VIRIDIAN_GYM_TRAINER_", 0, 7),
                          dialogue = {
                            "_ViridianGymGiovanniReceivedEarthBadgeText",
-                           "_ViridianGymGiovanniEarthBadgeInfoText",
+                         },
+                         tmPre = { "_ViridianGymGiovanniEarthBadgeInfoText" },
+                         tmDialogue = {
                            "_ViridianGymGiovanniReceivedTM27Text",
                            "_ViridianGymGiovanniTM27ExplanationText",
                          } },
 
-  -- Silph Co. Giovanni: unlocks the president's Master Ball gift
-  ["OPP_GIOVANNI#2"] = { flag = "EVENT_BEAT_SILPH_CO_GIOVANNI" },
+  -- Silph Co. Giovanni: unlocks the president's Master Ball gift.
+  -- SilphCo11FGiovanniStartBattleScript (scripts/SilphCo11F.asm) hands the
+  -- battle SilphCo10FGiovanniILostAgainText through SaveEndBattleTextPointers,
+  -- but he has no def_trainers header on 11F, so engageTrainer finds no
+  -- header.won to give it -- this chain is the port's stand-in for that loss
+  -- line (#722).  The "Blast it all!" speech, the fade and the rockets
+  -- leaving are SilphCo11FGiovanniAfterBattleScript, ported in M.SILPH_CO_11F
+  -- (data/scripts/story.lua).
+  ["OPP_GIOVANNI#2"] = { flag = "EVENT_BEAT_SILPH_CO_GIOVANNI",
+                         dialogue = { "_SilphCo10FGiovanniILostAgainText" } },
 
   -- Fighting Dojo Karate Master (scripts/FightingDojo.asm
   -- FightingDojoKarateMasterPostBattleScript sets EVENT_BEAT_KARATE_MASTER,

data/scripts/yellow_jessie_james.lua

@@ -62,10 +62,15 @@ M.MT_MOON_B2F = {
       { "walk_npc", 6, { "left", "left", "left", "left", "left" } },
       { "face_object", 6, "left" },
       { "show_text", "_MtMoonJessieJamesText2" },
+      -- MtMoonB2FScript12 arms _MtMoonJessieJamesText3 with
+      -- SaveEndBattleTextPointers before it sets wCurOpponent, so
+      -- TrainerBattleVictory prints it on the battle screen as "ROCKET: A
+      -- brat beat us?" between TrainerDefeatedText and MoneyForWinningText.
+      -- Its one-word first line only reads right behind that tag (#866).
+      { "save_end_battle_text", "_MtMoonJessieJamesText3" },
       { "start_battle", "trainer", "OPP_ROCKET", 42 },
       { "check_battle_result", "win" },
       { "jump_if_false", "end" },
-      { "show_text", "_MtMoonJessieJamesText3" },
       { "show_text", "_MtMoonJessieJamesText4" },
       { "stop_music" },
       { "play_music", "Music_MeetJessieJames" },
@@ -85,7 +90,8 @@ M.MT_MOON_B2F = {
 -- motto plays from off-screen FIRST, then the duo pops in at (25,10) /
 -- (24,10) and whichever of them shares the player's column ($18=24 or
 -- $19=25, EVENT_ROCKET_HIDEOUT_4_JESSIE_JAMES_ON_LEFT) walks the three
--- tiles down to loom over the player while the other steps one.  A loss
+-- tiles down to loom over the player while the other walks four and ends
+-- up beside him.  A loss
 -- re-hides them (RocketHideoutB4FResetScripts via EVENT_6A0), so the
 -- trigger re-arms clean.
 -- -------------------------------------------------------------------
@@ -106,7 +112,7 @@ M.ROCKET_HIDEOUT_B4F = {
     if f.EVENT_BEAT_ROCKET_HIDEOUT_4_JESSIE_JAMES then return false end
     -- ON_LEFT: player under James's column (25); movement data pairs
     -- RocketHideoutB4FJessieJamesMovementData_45605/45606 swap so the
-    -- column-mate walks 3, the other 1.
+    -- column-mate walks 3, the other 4.
     local onLeft = (x == 25)
     ow.runner:run({
       { "stop_music" },
@@ -116,16 +122,30 @@ M.ROCKET_HIDEOUT_B4F = {
       { "emote", "player", "shock", 30 },
       { "show_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JAMES" },
       { "show_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JESSIE" },
-      -- James (object 2) then Jessie (object 3), Script4..Script9 order
-      { "walk_npc", 2, onLeft and { "down", "down", "down" } or { "down" } },
+      -- James (object 2) then Jessie (object 3), Script4..Script9 order.
+      -- RocketHideoutB4FJessieJamesMovementData_45605 is a lone $4 that FALLS
+      -- THROUGH into _45606 ($4 $4 $4 $ff), so MoveSprite_ (home/pathfinding.asm)
+      -- reads _45605 as FOUR steps and _45606 as three; $4 is DOWN in Yellow's
+      -- Func_5288 lookup (engine/overworld/movement.asm), which walks with no
+      -- collision test.  From (25,10)/(24,10) against a player on y=14 the
+      -- column-mate stops three down, right above him, and the other walks the
+      -- full four to stand alongside -- which is what the facings below assume.
+      -- Reading _45605 as a single step stranded whoever was off-column three
+      -- tiles away, so James never reached the player (#865).
+      { "walk_npc", 2, onLeft and { "down", "down", "down" }
+                              or { "down", "down", "down", "down" } },
       { "face_object", 2, onLeft and "down" or "left" },
-      { "walk_npc", 3, onLeft and { "down" } or { "down", "down", "down" } },
+      { "walk_npc", 3, onLeft and { "down", "down", "down", "down" }
+                              or { "down", "down", "down" } },
       { "face_object", 3, onLeft and "right" or "down" },
       { "show_text", "_RocketHideoutJessieJamesText2" },
+      -- RocketHideoutB4FScript10 saves _RocketHideoutJessieJamesText3 as the
+      -- end-battle text, so it prints as "ROCKET: Such a dreadful twerp!" on
+      -- the battle screen ahead of MoneyForWinningText (#866).
+      { "save_end_battle_text", "_RocketHideoutJessieJamesText3" },
       { "start_battle", "trainer", "OPP_ROCKET", 43 },
       { "check_battle_result", "win" },
       { "jump_if_false", "lost" },
-      { "show_text", "_RocketHideoutJessieJamesText3" },
       { "show_text", "_RocketHideoutJessieJamesText4" },
       { "stop_music" },
       { "play_music", "Music_MeetJessieJames" },
@@ -175,16 +195,27 @@ M.POKEMON_TOWER_7F = {
       { "show_text", "_PokemonTowerJessieJamesText1" },
       { "face_player_dir", "up" },
       { "emote", "player", "shock", 30 },
-      -- Jessie (object 1) then James (object 2), Script1..Script6 order
-      { "walk_npc", 1, onLeft and { "down" } or { "down", "down", "down" } },
+      -- Jessie (object 1) then James (object 2), Script1..Script6 order.
+      -- Same fall-through blob as the hideout: PokemonTower7FMovementData_60d7a
+      -- is a lone $4 running into _60d7b ($4 $4 $4 $FF), so _60d7a is FOUR
+      -- steps and _60d7b is three.  From (10,8)/(11,8) against a player on
+      -- y=12 the column-mate halts one tile above him and the other closes the
+      -- full four to his side; the single-step reading is why James only
+      -- "moved a bit" here (#865).
+      { "walk_npc", 1, onLeft and { "down", "down", "down", "down" }
+                              or { "down", "down", "down" } },
       { "face_object", 1, onLeft and "right" or "down" },
-      { "walk_npc", 2, onLeft and { "down", "down", "down" } or { "down" } },
+      { "walk_npc", 2, onLeft and { "down", "down", "down" }
+                              or { "down", "down", "down", "down" } },
       { "face_object", 2, onLeft and "down" or "left" },
       { "show_text", "_PokemonTowerJessieJamesText2" },
+      -- PokemonTower7FScript7 saves _PokemonTowerJessieJamesText3 as the
+      -- end-battle text: "ROCKET: You will regret this!" on the battle screen,
+      -- before the prize money (#866).
+      { "save_end_battle_text", "_PokemonTowerJessieJamesText3" },
       { "start_battle", "trainer", "OPP_ROCKET", 44 },
       { "check_battle_result", "win" },
       { "jump_if_false", "end" },
-      { "show_text", "_PokemonTowerJessieJamesText3" },
       { "show_text", "_PokemonTowerJessieJamesText4" },
       { "stop_music" },
       { "play_music", "Music_MeetJessieJames" },
@@ -254,10 +285,12 @@ M.SILPH_CO_11F = {
       { "walk_npc", 6, jessieDirs },
       { "face_object", 6, jessieFace },
       { "show_text", "_SilphCoJessieJamesText2" },
+      -- SilphCo11FScript11 saves _SilphCoJessieJamesText3 (SilphCo11FText_624c2)
+      -- as the end-battle text: "ROCKET: Like always..." before the money (#866).
+      { "save_end_battle_text", "_SilphCoJessieJamesText3" },
       { "start_battle", "trainer", "OPP_ROCKET", 45 },
       { "check_battle_result", "win" },
       { "jump_if_false", "end" },
-      { "show_text", "_SilphCoJessieJamesText3" },
       { "show_text", "_SilphCoJessieJamesText4" },
       { "stop_music" },
       { "play_music", "Music_MeetJessieJames" },

data/scripts/yellow_viridian_old_man.lua

@@ -0,0 +1,151 @@
+-- The Viridian City old-man catch tutorial, Yellow's way
+-- (pokeyellow scripts/ViridianCity.asm, scripts/ViridianCity_2.asm,
+--  scripts/OaksLab.asm).  Registered on top of the shared tables by
+-- data/scripts/init.lua on a Yellow boot.
+--
+-- Yellow has TWO gambler objects where Red/Blue have one:
+--   * VIRIDIANCITY_OLD_MAN    at (17,5) -- a Red/Blue leftover; its
+--     toggle stays OFF forever in Yellow, no script ever shows it.
+--   * VIRIDIANCITY_OLD_MAN2   at (18,9) -- replaces the sleeper the
+--     moment the Pokédex is given (OaksLabOakGivesPokedexScript:
+--     HideObject TOGGLE_LYING_OLD_MAN / ShowObject TOGGLE_OLD_MAN_2).
+--
+-- This is the tutorial old man.  The Red/Blue "Are you in a hurry?"
+-- yes/no script must NOT run against him: Yellow's
+-- _ViridianCityOldManHadMyCoffeeNowText is the apology speech ("I've had
+-- my coffee now ... I'll show you how to catch POKéMON as my apology"),
+-- and the shared story.lua TEXT_VIRIDIANCITY_OLD_MAN rows hang an
+-- invented yes/no over it -- YES printed the TimeIsMoney alias
+-- (_ViridianCityOldManLosingMyTouchText) and NO ran the demo, every
+-- talk, forever (#617).
+--
+-- The real flow (ViridianCityCheckWaitingOldMan + ViridianCityOldMan2Text
+-- + ViridianCityOldManInitialCatchTrainingScript + ...EndInitial... +
+-- ViridianCityPostInitialCatchTraining): stepping into (19,9) -- the gap
+-- east of the sleeper's cell -- faces the old man right and the player
+-- left, prints the apology, and without any choice runs the demo battle
+-- (BATTLE_TYPE_OLD_MAN, RATTATA lvl 5), which he FAILS -- the ball shakes
+-- three times and breaks open.  After it, the same text pointer
+-- now prints _ViridianCityOldManLosingMyTouchText ("That didn't work!
+-- I must be losing my touch."), the old man walks off (down 6 with the
+-- player on (19,9), right 1 otherwise, Pikachu nudged out of the way
+-- first) and TOGGLE_OLD_MAN_2 hides.  A direct talk does the same.
+
+local M = {}
+
+local OLD_MAN2 = "VIRIDIANCITY_OLD_MAN2"
+
+-- Capture the FUNCTION, not the table: attachBase stores the module
+-- table itself, so once this file's onStep is attached the table's slot
+-- points back here -- delegating through the table would self-recurse.
+-- story5's VIRIDIAN_CITY.onStep chains story.lua's sleeping-old-man
+-- gate and its own gym-lock step (same pattern as yellow_jessie_james).
+local baseViridianStep = require("data.scripts.story5").VIRIDIAN_CITY.onStep
+
+-- pokeyellow text/ViridianCity.asm, _ViridianCityOldManHadMyCoffeeNowText
+-- and _ViridianCityOldManLosingMyTouchText, spelled with the extractor's
+-- markers (line -> \n, cont -> \v, para -> \f)
+local function text(game)
+  return {
+    apology = game.data.text._ViridianCityOldManHadMyCoffeeNowText
+      or "Ahh, I've had my\ncoffee now and I\vfeel great!\fSure, you can go\n"
+      .. "through!\fI'm sorry I was\nso rude to you!\fI see you're using\n"
+      .. "a POKéDEX.\fI'll show you how\nto catch POKéMON\vas my apology.",
+    losingMyTouch = game.data.text._ViridianCityOldManLosingMyTouchText
+      or "That didn't work!\nI must be losing\vmy touch.\fI've run out of\n"
+      .. "POKé BALLs too.\fI have to get some\nat POKéMON MART.",
+  }
+end
+
+-- The row list for the initial-tutorial branch, keyed by where the
+-- player stands when the battle ends (ViridianCityPostInitialCatchTraining
+-- reads wXCoord: (19,9) walks the old man down the corridor, anywhere
+-- else walks him right 1 after moving the follower Pikachu aside).
+local function oldMan2Rows(game, ow, npc)
+  local rows = {
+    { "show_text", "_ViridianCityOldManHadMyCoffeeNowText" },
+    -- ViridianCityOldManInitialCatchTrainingScript sets
+    -- EVENT_INITIAL_CATCH_TRAINING before the battle runs, and
+    -- ItemUseBall's .oldManBattle branch turns that event into anim data
+    -- $63: three shakes, then the ball breaks open.  The losing-my-touch
+    -- line below only follows a throw that failed (#636).
+    { "old_man_demo", "fail" },
+    { "set_flag", "EVENT_COMPLETED_CATCH_TRAINING" },
+    { "show_text", "_ViridianCityOldManLosingMyTouchText" },
+  }
+  if ow.player and ow.player.cellX == 19 then
+    rows[#rows + 1] =
+      { "walk_npc", npc.def.index,
+        { "down", "down", "down", "down", "down", "down" } }
+  else
+    -- ViridianCityMovePikachu (scripts/ViridianCity_2.asm): Pikachu
+    -- steps out of the old man's way before he turns right
+    local PikachuFollower = require("src.world.PikachuFollower")
+    local pika = ow and PikachuFollower.current(ow)
+    if pika then
+      rows[#rows + 1] = { "walk_npc", pika.def.index, { "right" } }
+    end
+    rows[#rows + 1] = { "walk_npc", npc.def.index, { "right" } }
+  end
+  rows[#rows + 1] =
+    { "hide_object", "VIRIDIAN_CITY", OLD_MAN2 }
+  return rows
+end
+
+-- The shared talk handler: TEXT_VIRIDIANCITY_OLD_MAN2's text_asm branch
+-- (ViridianCityOldMan2Text) on EVENT_COMPLETED_CATCH_TRAINING.
+local function oldMan2Talk(game, ow, npc, done)
+  if game.save.flags and game.save.flags.EVENT_COMPLETED_CATCH_TRAINING then
+    local TextBox = require("src.render.TextBox")
+    game.stack:push(TextBox.new(game, text(game).losingMyTouch, done))
+    return
+  end
+  ow.runner:run(oldMan2Rows(game, ow, npc), { npc = npc, onDone = done })
+end
+
+M.VIRIDIAN_CITY = {
+  talk = {
+    TEXT_VIRIDIANCITY_OLD_MAN2 = oldMan2Talk,
+  },
+
+  -- Re-apply the Pokédex swap for a save that already holds the flag but
+  -- was never standing here when it fired (converted .sav imports, same
+  -- shape as story.lua's VIRIDIAN_CITY.onEnter).  Yellow shows OLD_MAN2,
+  -- not the Red/Blue OLD_MAN at (17,5), and also puts away a stray
+  -- OLD_MAN a save made by the pre-#617 build left standing.
+  onEnter = function(game, ow)
+    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
+      return
+    end
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.hide_object(ctx, "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY")
+    Commands.hide_object(ctx, "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN")
+    Commands.show_object(ctx, "VIRIDIAN_CITY", OLD_MAN2)
+  end,
+
+  -- ViridianCityCheckWaitingOldMan: with the Pokédex held and the
+  -- tutorial undone, (19,9) -- the gap east of the old man, the same
+  -- cell the sleeper used to gate -- faces him right, turns the player
+  -- left and starts the OLD_MAN2 flow with no choice.
+  onStep = function(game, ow, x, y)
+    if baseViridianStep and baseViridianStep(game, ow, x, y) then
+      return true
+    end
+    local flags = game.save.flags
+    if not flags.EVENT_GOT_POKEDEX then return false end
+    if flags.EVENT_COMPLETED_CATCH_TRAINING then return false end
+    if x ~= 19 or y ~= 9 then return false end
+    local man
+    for _, npc in ipairs(ow.npcs) do
+      if npc.def and npc.def.name == OLD_MAN2 then man = npc break end
+    end
+    if not man then return false end
+    man.facing = "right"
+    ow.player.facing = "left"
+    oldMan2Talk(game, ow, man, nil)
+    return true
+  end,
+}
+
+return M

docs/behavior-porting-notes.md

@@ -234,8 +234,12 @@ What was ported from pokered's engine code and where it came from.
   pre-battle text and engages the leader battle (badge/TM via
   data/scripts/victories.lua); post-badge talk prints the leader's
   post-battle advice text (Misty's is her TM11 explanation). The
-  originals' middle branch (beaten but TM not handed over) is
-  unreachable since the TM is granted with the victory. Giovanni's
+  originals' middle branch (beaten but TM not handed over,
+  CheckEventReuseA EVENT_GOT_TM*) is ported too: the victory's GiveItem
+  goes through the bag's capacity check, a full bag shows the leader's
+  "make room" text instead of the received lines and leaves
+  EVENT_GOT_TM* unset, and talking to the leader re-runs the ReceiveTM
+  script until the TM goes in (#797). Giovanni's
   farewell (`ViridianGymGiovanniText` .afterBeat) hides him inside a
   fade-to-black/fade-in Transition matching ViridianGym.asm's
   GBFadeOutToBlack → HideObject → GBFadeInFromBlack, persisted

docs/launcher.md

@@ -45,6 +45,9 @@ same system picker and install the chosen archive on return.
 draws one chip per game plus a MODS chip and rebuilds `self.tabRects` every
 frame so `mousepressed` can dispatch clicks; switching tabs mid-import is
 allowed (a dropped ROM still routes by SHA-1 regardless of which tab shows).
+On **NX**, **Scan again** is stricter: it only starts an import whose SHA-1
+matches the open game tab, so a shared `imports/` folder with Red+Yellow
+cannot jump Yellow → Red.
 
 - A game tab (`_drawGamePanel`) shows the ROM card, the SAVE FILES card, the
   Play button, and the SAVE SLOT card in a responsive two-column grid (see
@@ -150,6 +153,17 @@ before `Game:load`, so **it never loads a mod's entry chunk**; only
 - `LauncherMods.uninstall(id)` removes `mods/<id>/` and clears
   `options.mods[id]` so a later reinstall starts from the loader's default
   (enabled). The mods panel Delete control calls this and re-derives the list.
+- A mod that declares `github` shows its total GitHub downloads (every
+  release's summed asset `download_count`, from the same cached release
+  fetch the update check uses) as a highlighted body line like "12,345
+  downloads across all releases - Released 2024-05-31 - Updated 2026-07-01"
+  (first and latest `published_at`). Old cache entries written before the
+  counts existed show no line rather than a wrong zero; a manual check
+  refreshes them.
+- The MODS panel sorts its rows by Name, Popularity (downloads),
+  Release date (first release), or Last updated, chosen by chips under the
+  header and persisted in `options.modSort`. Mods without release data
+  (no `github` field, or a stale cache) sink to the bottom of data sorts.
 
 ## Import / Export save
 
@@ -157,9 +171,14 @@ The SAVE FILES card wires a raw Gen1 `.sav` battery image to the save slots
 through `src/import/SaveFileIO.lua`, which sits on top of
 `src/save_convert/SaveConvert.lua` and the slot API in `SaveData`.
 
-- **Import save** is live once the game's ROM is imported (playable). It opens
-  a native `.sav` picker (`chooseSav` on desktop; on Android,
-  `love.system.pickFile("sav")` → `picked_save.sav`, same SAF path as ROMs).
+- **Import save** is live once the game's ROM is imported (playable).
+  On desktop it opens a native `.sav` picker (`chooseSav`); on Android,
+  `love.system.pickFile("sav")` → `picked_save.sav`, same SAF path as ROMs.
+  On **NX (Switch)** there is no picker: copy a `.sav` into
+  `getSaveDirectory()/imports/saves/<red|blue|yellow>/` via MTP / SD / FTP
+  (one folder per game), then press **Import save** on that game’s tab to
+  ensure the inbox and rescan (same pattern as the ROM `imports/` and mod
+  `imports/mods/` inboxes). Hidden `._*.sav` AppleDouble sidecars are skipped.
   `SaveFileIO.importToSlot` reads the bytes (an absolute path, a save-dir
   relative name, a dropped LOVE file, or raw bytes),
   guards the 32768-byte size, runs `SaveConvert.importSav` (which also rejects
@@ -167,19 +186,29 @@ through `src/import/SaveFileIO.lua`, which sits on top of
   writes it (`SaveData.writeSlot`), and makes it active (`SaveData.setActiveSlot`).
   The meta stamp is re-stamped off `gen1_import` to the current numeric format
   so `SaveData.load`'s migration pass accepts the slot. On success the SAVE SLOT
-  panel is refreshed with the new slot selected.
+  panel is refreshed with the new slot selected. On **NX**, a successful inbox
+  import retires the file to `*.sav.imported` and records a content hash in
+  `imports/saves/<game>/.imported-sha1` so a second **Import save** (or the same
+  bytes under a new name) does not clone slots; failures leave the original
+  `.sav`. Only that game’s folder is scanned.
 - **Export save** is live only when the active slot actually holds a save
   (checked against `listSlots`). `SaveFileIO.exportActiveSlot` loads the active
   slot, encodes it back with `SaveConvert.exportSav` (a slot never keeps
   `rawImport`, so this is a zero-filled template export, which is valid), and
-  writes `exports/gen1recomp-<version>-<slotId>.sav` in the save directory
-  (`love.filesystem.createDirectory("exports")`). On desktop it returns the
-  absolute path (`love.filesystem.getSaveDirectory()`), which the notice line
-  shows with an "Open folder" affordance (`love.system.openURL("file://" .. dir)`).
+  writes `exports/<version>/gen1recomp-<version>-<slotId>.sav` under the same
+  root `persistFs` writes slots to: the portable game folder when `portable.txt`
+  marks the install, otherwise the save directory (`exports/` and
+  `exports/<version>/` are created as needed; #752). On desktop it returns the
+  absolute path (`SaveData.portableBaseDir()` when portable, else
+  `love.filesystem.getSaveDirectory()`), which the notice line shows with an
+  "Open folder" affordance (`love.system.openURL("file://" .. dir)`).
   On Android the bytes are also staged as `pending_export.sav` and
   `love.system.createFile(suggestedName)` opens `ACTION_CREATE_DOCUMENT` so the
   player can save to Downloads / Drive / etc.; on return `export_done.flag`
   makes focus show "Save exported."
+  On **NX**, export success sets a notice with the `exports/<game>/` path and an
+  MTP-oriented hint — no `openURL` / Open folder (pull the file via MTP /
+  SD / FTP instead).
 - **Drag-drop.** `filedropped` routes a `.sav` to the import path for the
   currently active game tab; when a non-game tab (mods, or the locked yellow
   placeholder) is showing it defaults to red, the always-present first game

docs/linux-arm64-build.md

@@ -0,0 +1,202 @@
+# Linux arm64 (aarch64) AppImage
+
+Releases ship `gen1recomp-<version>-linux-arm64.AppImage` alongside the
+existing x86_64 `gen1recomp-<version>-linux.zip`. It targets 64-bit ARM
+desktop Linux: Raspberry Pi 4/5 running Raspberry Pi OS, Armbian and other
+SBC distros, arm64 VMs on Apple Silicon, Ampere/Graviton desktops, and the
+aarch64 handhelds that run a full distro.
+
+> The Anbernic RG34XXSP has its own PortMaster-style pack
+> (`gen1recomp-*-rg34xxsp-stockos64-mod.zip`, see
+> [anbernic-rg34xxsp.md](anbernic-rg34xxsp.md)). That one bundles PortMaster's
+> LÖVE runtime and expects the device's own SDL; this AppImage is the generic
+> desktop-Linux artifact and shares nothing with it but the `game.love`.
+
+## For players
+
+```sh
+chmod +x gen1recomp-*-linux-arm64.AppImage
+./gen1recomp-*-linux-arm64.AppImage
+```
+
+Then use **Import ROM** in the launcher to point it at your own legal Red /
+Blue / Yellow cartridge dump, exactly as on every other platform.
+
+If your system has no FUSE (`dlopen(): error loading libfuse.so.2`), either
+install it (`sudo apt install libfuse2`) or run without it:
+
+```sh
+./gen1recomp-*-linux-arm64.AppImage --appimage-extract-and-run
+```
+
+### What the host has to provide
+
+Very little, and this is enforced by an assertion in the build rather than by
+good intentions. The only libraries the AppImage requires at startup are:
+
+```
+glibc 2.29+   libstdc++   libfreetype6   zlib
+```
+
+Everything else — OpenGL/Mesa, X11, Wayland, KMSDRM, ALSA, PulseAudio — is
+**dlopened**, so it is used when present and skipped when absent. That means
+one image runs on a full desktop, on a Wayland-only session, on a
+KMSDRM-only handheld with no X server, and on a box with ALSA but no
+PulseAudio, without a different build for each.
+
+That property does not come for free from Debian's packages, and getting it
+is most of what the build below is doing; see
+[Why five libraries are built from source](#why-five-libraries-are-built-from-source).
+
+## For builders
+
+```sh
+scripts/build_linux_arm64.sh --version 0.1.0
+```
+
+Output:
+
+```
+dist/linux-arm64/gen1recomp-<version>-linux-arm64.AppImage
+dist/linux-arm64/gen1recomp-<version>-linux-arm64.AppImage.sha256
+```
+
+Useful flags: `--game-love PATH` reuses an already-packed payload (CI does
+this so every platform ships identical bytes), `--rebuild-image` forces the
+builder container to rebuild, `--clean-cache` throws away the pinned
+downloads and the compiled LÖVE prefix.
+
+### Requirements
+
+An **aarch64 host** with **docker or podman**. A Raspberry Pi 5 is the
+reference machine (a cold build takes about 10 minutes on one — six libraries
+plus the engine; rebuilds reuse the cached prefix and take seconds). Apple Silicon with Docker
+Desktop and GitHub's `ubuntu-24.04-arm` runner both work too.
+
+The script refuses to run on x86_64 rather than falling back to qemu-user
+emulation: that path takes hours and has produced miscompiled LuaJIT.
+
+### Why this is not just another `scripts/build.sh` target
+
+`scripts/build.sh linux` downloads LÖVE's official `love-11.5-x86_64.AppImage`,
+unpacks its squashfs, drops `game.love` in, and glues it back together. That
+trick is not available here — **LÖVE publishes no aarch64 binary at all.** The
+11.5 release has win32, win64, macOS, Android, iOS and one x86_64 AppImage,
+and that is the entire list.
+
+So this build compiles LÖVE 11.5 from the official `linux-src` tarball and
+assembles the AppImage from scratch. Every pinned input — the LÖVE source, the
+five libraries built alongside it, and the AppImage type-2 runtime — is
+SHA-256 verified on the host before the container ever sees it, and the
+container itself runs with no network access.
+
+### Why the build happens in a Debian bullseye container
+
+glibc is backward compatible but not forward compatible: a binary linked
+against glibc 2.41 will not start on a system with 2.31, and there is no way
+to fix that after the fact. Compiling on the oldest base we support is
+therefore the only thing that makes one artifact work everywhere.
+
+Bullseye (glibc 2.31) is that base. The resulting binaries actually come out
+needing only **glibc 2.29** and **GLIBCXX_3.4.21**, so the AppImage covers
+everything from Ubuntu 20.04 and Raspberry Pi OS bullseye through current
+trixie.
+
+This is a statement about the *compile environment*, not about where the
+artifact runs — building on your own newer distro would silently raise that
+floor and strand every user on an older one, with no symptom until they
+download it. CI enforces the floor: `linux-arm64-build` fails if the highest
+required glibc symbol version climbs above 2.31.
+
+### Why five libraries are built from source
+
+SDL2, OpenAL, libtheora, libogg/libvorbis and libmpg123 are compiled rather
+than installed from bullseye. In every case the reason is *correctness*, not
+a newer version number — Debian builds these for a system where every
+dependency is installed and co-versioned, which is the opposite of an
+AppImage's situation. Each one broke the build in a different way, and all
+three failure modes are now assertions that fail the build instead of
+shipping.
+
+**1. Hard-linked backends (SDL2, OpenAL).** Debian's `libSDL2` lists
+`libpulse`, `libasound`, `libX11` and `libwayland-client` as `DT_NEEDED` —
+resolved by the loader at startup, not dlopened. An AppImage bundling it
+refuses to start unless the host has *all four*. It appeared to work in
+testing only because a desktop Pi has all four; a headless CI runner is what
+exposed it. Debian's OpenAL does the same via `libsndio`, which itself
+hard-links `libasound`. Built from source with `--enable-*-shared` and
+`ALSOFT_DLOPEN`, both dlopen their backends instead.
+
+**2. A stray link (libtheora).** Debian's `libtheoradec.so.1` is linked
+against `libcairo.so.2` — a packaging artifact, since a video decoder has no
+business drawing vector graphics — and cairo drags in X11, xcb, fontconfig
+and freetype. `--disable-examples` produces a `libtheoradec` needing only
+`libogg`.
+
+**3. SONAME collision with the host (ogg, vorbis, mpg123).** The subtle one.
+OpenAL dlopens ALSA, ALSA's config loads its PulseAudio hook plugin, and that
+plugin pulls the *host's* `libsndfile` into our process. `libsndfile` links
+`libogg`, `libvorbis` and `libmpg123` — the same three we bundle. The loader
+resolves a SONAME exactly once per process, so the host's `libsndfile` binds
+to *our* copies:
+
+```
+openal -> libasound -> libasound_module_conf_pulse -> libsndfile (host, new)
+                                                         `-> mpg123_info2 -> libmpg123 (ours, bullseye 1.26)
+```
+
+`mpg123_info2` arrived in mpg123 1.32, so the plugin failed to relocate, ALSA
+config collapsed, and the game ran with **no audio device at all**. Not
+bundling these instead would make `libogg`/`libvorbis`/`libmpg123` mandatory
+host packages; building them current means our copies *satisfy* the host's
+`libsndfile` rather than starving it.
+
+The same collision is why the font stack — freetype, fontconfig, libpng,
+brotli, zlib — is left to the host entirely. Bundling a bullseye freetype
+2.10.4 meant a host `libcairo` could not find `FT_Get_Transform` (added in
+2.11) and the game died at startup. Leaving the whole stack to the host keeps
+it self-consistent, while `liblove` — compiled against 2.10.4 — only ever
+asks for symbols every supported host already has.
+
+The general rule this all reduces to: **never bundle a library the host's own
+stack may also load, unless yours is at least as new as theirs.**
+
+### CI
+
+Three jobs, path-gated on `scripts/build_linux_arm64.sh`,
+`scripts/linux-arm64/`, `scripts/pack_love.sh` and this document:
+
+- **`linux-arm64-selftest`** (`ubuntu-latest`, x86_64) — offline gate. Checks
+  the pins are real digests on a dated tag rather than the moving
+  `continuous` one, that the Dockerfile still builds on bullseye, that the
+  exclude list still classifies known sonames correctly, that AppRun still
+  launches `game.love` with `--fused`, and that the host-arch guard actually
+  fires. Needs no container and no arm64 machine.
+- **`linux-arm64-build`** (`ubuntu-24.04-arm`) — the real build, then extracts
+  the artifact and asserts the layout, that every bundled object resolves
+  under AppRun's `LD_LIBRARY_PATH`, and that the glibc floor is still ≤ 2.31.
+  Uploads the AppImage for 7 days.
+- **release** — `linux-arm64` runs on `ubuntu-24.04-arm`, reuses the shared
+  `game.love` from the `love-payload` job, and the AppImage is staged and
+  published like every other release asset.
+
+Unlike the Switch job, none of this needs secrets or self-hosted hardware, so
+it runs on fork PRs too.
+
+### Updating the pins
+
+Both pins live in `scripts/linux-arm64/common.sh`:
+
+- `LOVE_VERSION` / `LOVE_SRC_SHA256` — bumping any version invalidates the
+  cached prefix automatically (its name is keyed by every source version at
+  once, so a partial rebuild cannot mix vintages). Check that bullseye still
+  has `-dev` packages new enough for the new release; `build_appimage.sh`
+  asserts every optional module actually linked, because LÖVE's `configure`
+  exits 0 and silently drops a module when one is missing.
+- `SDL2_*`, `OPENAL_*`, `THEORA_*`, `OGG_*`, `VORBIS_*`, `MPG123_*` — the
+  source-built libraries. Bumping these is usually safe and occasionally
+  necessary: `libmpg123` in particular must stay at least as new as what a
+  target host's `libsndfile` expects, which is asserted for `mpg123_info2`.
+- `APPIMAGE_RUNTIME_TAG` / `APPIMAGE_RUNTIME_SHA256` — always a dated tag
+  from [AppImage/type2-runtime](https://github.com/AppImage/type2-runtime/releases).
+  The selftest fails the build if this ever points at `continuous`.

docs/modding.md

@@ -174,6 +174,32 @@ It runs immediately before queued button edges are promoted, so input added by
 the wrapper is visible during that same fixed step. The callback receives
 `(next, game, dt)` and must call `next(game, dt)`.
 
+`input.pointer` delivers uncaptured gameplay pointer events -- touches and
+real mouse input alike. The callback receives `(next, game, ev)` where `ev`
+is `{ phase, source, id, x, y, dx, dy, pressure, button }`: `phase` is
+`"pressed"`, `"moved"`, `"released"` or `"cancelled"`; `source` is `"touch"`
+or `"mouse"`; `id` is the LÖVE touch id or `"mouse"`; and the coordinates
+are LOVE window units, the same space `render.hud`'s viewport and the touch
+overlay lay out in. The on-screen touch controls keep first refusal: a
+pointer that begins on a virtual control belongs to the pad for its whole
+lifecycle and never reaches the hook, while one that begins outside stays
+visible even if it later crosses a control. A real mouse reaches the hook
+without `POKEPORT_TOUCH` (synthesized `istouch` mouse twins are dropped, so
+a mobile touch fires once), and focus or visibility loss and input recovery
+deliver a `"cancelled"` for every pointer the hook saw pressed but not yet
+released. Return `true` without calling `next` to consume the event.
+
+`mod.input` presses GB buttons source-safely. `mod.input:tap(game, btn)`
+queues exactly one `wasPressed` edge for the next fixed step and holds
+nothing; `local token = mod.input:press(game, btn)` holds the button until
+`mod.input:release(token)`. Buttons are `up`, `down`, `left`, `right`, `a`,
+`b`, `start` and `select`. Every press is its own input source inside the
+engine's multi-source bookkeeping, so releasing a token never clears a hold
+the keyboard, a controller, the touch overlay or another mod still owns;
+`release` is idempotent and refuses tokens taken by another mod.
+Outstanding tokens are released automatically on entry-chunk rollback, hot
+reload and input recovery.
+
 `ui.title_menu.items` receives `(next, game, items)` and follows the same
 decorate-after-`next` convention as `ui.start_menu.items`. It is the safe place
 for a tool to offer a fresh-session action before gameplay begins.
@@ -200,5 +226,12 @@ for driving a second physical display. This is what lets a mod lay the two
 passes out as two stacked Game Boy screens, or push one onto a second screen,
 without the engine knowing the layout.
 
+`screen.render_visible` receives `(next, state)` while the main screen is being
+composed. Return `false` to omit that state from drawing, opacity selection and
+palette-zone ownership. The state remains on the stack and keeps its normal
+update and input ownership, so a mod can mirror a native menu on another
+display without reimplementing it. The default is `true`. Treat the wrapper as
+a pure predicate: the renderer may ask it more than once per frame.
+
 Developer mode also arms the mod loader's dev tripwire, which flags mods
 that reach outside their permission set.

docs/new-features.md

@@ -1,462 +1,26 @@
-# New features (deliberate additions beyond the original)
-
-Intentional enhancements this port adds on top of faithful Pokémon Red
-behavior. They have no Game Boy equivalent and are kept by design.
-Genuine divergences from the original (things still missing, wrong, or
-approximated) live in docs/known-differences.md; faithfully-ported
-behavior is in docs/behavior-porting-notes.md.
-
-## Survey zoom
-
-The mouse wheel (or `-`/`=`), the Options **ZOOM** row, or hotkey `4`
-zooms the overworld between 1 pixel per world pixel (full survey) and 2×
-the window fit scale (close-up), in crisp integer steps. This has no Game
-Boy equivalent:
-
-- Connected maps render their full bodies, and their NPCs appear as
-  visual-only "ghosts",  they wander but have no sight lines, triggers,
-  dialogue, or collision until the map is actually entered.
-- Menus, text boxes, and battles draw at normal scale on top of the
-  zoomed world. Zoom input is ignored while a script, menu, or battle is
-  active; the zoom offset is persisted as `save.options.zoom` (default
-  `0` = FIT) and survives New Game via `options.lua`.
-- Hotkey `4` ticks through every integer zoom level (survey → FIT →
-  close-up → wrap). The Options row shows `FIT` / `OUTn` / `INn`.
-- Beyond the border ring the void fill repeats indefinitely (see VOID
-  FILL below); interiors keep their own border block. Each visible map
-  area is colorized with its own SGB palette (the original recolored the
-  whole screen per map).
-- Neighbor maps load two connection hops out so corner-adjacent maps
-  don't pop in and out, and ghost NPCs share instances with the real ones
-  so their wander positions persist across seamless connection crossings
-  (a warp or fresh map entry still respawns everything at its script
-  position, like the original's per-entry sprite init).
-
-## VOID FILL
-
-The Options **VOID FILL** row picks what paints the infinite beyond-edge
-space on OVERWORLD-tileset maps during survey zoom:
-
-- **TREES** (default): solid tree wall block `$0F`.
-- **WATER**: animated water tile `$14` (same hshift cycle as on-map water).
-- **BLACK**: solid black.
-
-Other tilesets are unchanged (house/cave borders stay as authored).
-Persisted as `save.options.voidFill`.
-
-## Tilt mode
-
-The `3` key (and the Options menu TILT row) cycles a visual-only perspective
-tilt of the overworld through **OFF → 15° → 35° → 50° → OFF** for an HD-2D /
-diorama look. Like survey zoom this is purely presentational and has no
-Game Boy equivalent:
-
-- The entire map tilts as one rigid ground plane,  paths, grass, water,
-  floors, and every background-tile structure (buildings, trees, fences,
-  signs; in Gen 1 these are baked into the tile layer, not sprites),  so
-  rows above the player recede and rows below come toward the viewer. Only
-  things that actually *stand* on the ground draw as upright billboards,
-  unscaled and pixel-identical to flat mode: the player, NPCs, item balls,
-  and the standing FX attached to them (emote bubbles, the fishing rod,
-  the FLY bird). The Poké Center heal-machine overlay stays on the ground
-  plane with the machine tiles (it is OAM glued to a BG graphic, not a
-  standing sprite). An earlier revision tried
-  billboarding buildings/trees/signs too (cutting them out of the ground
-  per hand-curated per-tileset tables); that chased an endless tail of
-  special cases,  dense tree canopy, fences fused into grass, building
-  facades with their own baked-in fake perspective,  because Gen 1's art
-  was never drawn with a clean seam between ground and standing scenery. It
-  wasn't merged; tilting everything but the characters as one plane is the
-  simpler, shipped tradeoff (buildings recede/foreshorten with the ground
-  like a photo of a diorama, rather than standing fully upright next to
-  a full-height character).
-- Cycling tweens the angle between levels over ~0.25s rather than snapping;
-  with tilt fully off the world pass drops back onto the flat blit path, so
-  flat rendering stays pixel-identical to tilt-off and off costs nothing.
-- Tilt input is gated exactly like survey zoom,  honored only while
-  free-roaming, ignored while a script, menu, or battle is active,  and it
-  composes with survey zoom (the zoom scale feeds the projection). The tilt
-  level is persisted in `save.options.tilt` (default OFF).
-- It applies everywhere the overworld draws, interiors and caves included.
-  Menus, text boxes, and battles render flat on top, unaffected, and the
-  infinite beyond-the-border-ring fill stays flat by design.
-- Collision, movement, sight lines, triggers, encounters, and scripts are
-  untouched; nothing about the tilt reaches gameplay.
-
-## Colors mode
-
-The `2` key (and the Options menu COLORS row) cycles the display mode
-through **OG RED → SGB → ADVANCED → OG → OG INV → SGB INV → CLASSIC → OG RED**
-(on Blue the first slot labels **OG BLUE**; on Yellow, **OG YELLOW**).
-The first three are the real colorizations; the rest are DMG-shade novelties:
-
-- **OG RED** / **OG BLUE**: the Game Boy Color boot-ROM look for that cart --
-  one global BG palette + one OBJ palette, every map, no per-map variation
-  (Red/Blue ship no CGB code, so on a GBC the boot ROM colors them globally).
-  The player/NPCs keep the boot-ROM OBJ color over the terrain via the OBP
-  bake + post-zone redraw (`PaletteFX.GBC_BG` / `GBC_OBJ`, or Blue's blue/pink
-  pair).
-- **OG YELLOW** (Yellow playthrough, same `ogred` save id): Pokemon Yellow's
-  authentic GBC look from `CGBBasePalettes` (`data/palettes_yellow.lua`,
-  sourced from pret/pokeyellow). Per-map / per-species colors, not a single
-  boot-ROM ramp -- Yellow was CGB-enhanced.
-- **SGB** (default): the per-map Super Game Boy region palettes
-  (`data/sgb/sgb_palettes.asm`). Sprites tint with the region palette, as on
-  real SGB. (This is the mode formerly mislabeled "GBC".)
-- **ADVANCED**: pokered-gbc SuperPalettes -- real per-tile GBC coloring plus
-  per-species mon colors (`data/palettes_gbc.lua`). (Formerly labeled
-  "RED++"; it is the richest colorization rather than anything Red-specific.)
-- **OG**: force the four DMG grays (colorization off).
-- **OG INV**: inverted DMG grays.
-- **SGB INV**: each SGB zone palette with shade order reversed.
-- **CLASSIC**: original Game Boy pea-soup greens
-  (`#9BBC0F` / `#8BAC0F` / `#306230` / `#0F380F`).
-
-The shade-remap transform is applied centrally in `PaletteFX.sendColors`, so
-it covers overworld, menus, battles, and tilt upright billboards. OG RED's
-global BG palette is supplied by `OverworldState:overworldBgColors` (per-map
-override in the overworld pass). Persisted as `save.options.colors`; the
-`gbc` / `gbc_inv` / `redpp` save ids are kept for back-compat under the new
-labels.
-
-## GBC FX
-
-The `5` key (and the Options menu GBC FX row) cycles a "played on real
-unlit-GBC hardware" post-process through **OFF → 1 → 2 → 3 → 4**. The
-levels are a cumulative ladder:
-
-- **1**: reflective-screen backing transparency.
-- **2**: + LCD pixel grid.
-- **3**: + pixel drop shadows.
-- **4**: + sunlight glare and rainbow shimmer with a drifting light.
-
-It runs as a final present pass after world + UI composite in
-`Renderer:endFrame`, inspired by the Pixel Transparency RetroArch shader
-([github.com/mattakins/Pixel_Transparency](https://github.com/mattakins/Pixel_Transparency)).
-Default OFF; persisted as `save.options.gbcfx`.
-
-Mobile GPUs often compile the pass but present a black frame, so Android and
-iOS hide the row entirely, pin the level to OFF, and rewrite a level already
-persisted in `options.lua` (issue #136). `POKEPORT_GBCFX` overrides that
-decision either way, same tri-state as `POKEPORT_TOUCH`: `=0` refuses the
-effect, `=1` forces it available. The Anbernic handheld pack exports `0` from
-its launcher because the device reports `"Linux"` while its GPU is in the
-phone class (see [Anbernic RG34XXSP](anbernic-rg34xxsp.md)).
-
-## Performance tier (low-end devices)
-
-The Options **PERFORMANCE** row scales the port's optional presentation
-extras down for weaker hardware. The extras it governs are the three
-heaviest things the port adds on top of the original -- the whole-screen 3D
-**TILT** (transforms the entire map as a ground plane), the **GBC FX**
-post-process shader (a fullscreen pass), and survey **ZOOM** (zooming out
-renders the connected neighbor maps, a lot of extra overdraw) -- plus a hard
-FPS ceiling. None of this touches game logic, which is fixed-step off `dt`
-(`src/core/FixedStep.lua`), so every tier plays identically; they differ
-only in how much eye-candy the renderer is allowed to do.
-
-| Tier         | TILT | GBC FX | Survey ZOOM | Extra FPS ceiling |
-| ------------ | ---- | ------ | ----------- | ----------------- |
-| **HIGH**     | on   | on     | on          | none              |
-| **BALANCED** | off  | off    | on          | none              |
-| **LOW**      | off  | off    | off         | 60                |
-| **AUTO**     | picks a default from the device (below) |||
-
-- **AUTO** (the default) reads the device once at boot: ARM Linux handhelds
-  (e.g. the RG34XXSP) resolve to **LOW**, phones/tablets and very-low-core
-  desktops to **BALANCED**, and everything else -- a normal desktop, and
-  every existing `options.lua` that predates this option -- to **HIGH**,
-  so the common case is unchanged. See `src/core/Performance.detect`.
-- AUTO only chooses the *default*; all four tiers are selectable, so a
-  wrong guess is one row away from being overridden.
-- The clamps are applied **live** against your stored options and never
-  rewrite them (`Game:applyOptions`), so a lower tier hides your TILT / GBC
-  FX / ZOOM without forgetting them -- raising the tier restores exactly
-  what you had. (This is why the TILT / GBC FX / ZOOM rows still show your
-  saved choice on a clamped tier: it's your preference, waiting for a tier
-  that can afford it.)
-- Persisted as `save.options.performance` (`auto` | `high` | `balanced` |
-  `low`); unit-tested in `tests/engine/performance_tiers.lua`.
-
-## Peer-to-peer link play (lua-enet)
-
-Trades and link battles connect two copies of the game directly over
-lua-enet (ENet ships inside LÖVE,  nothing to install, no server to run)
-on a reliable-ordered channel, replacing the original standalone Python
-room-code relay (`tools/relay_server.py`, deleted). HOST A GAME shows the
-host's LAN address (UDP 7777; `POKEPORT_LINK_PORT` overrides); JOIN A
-GAME enters it. Closing performs a graceful ENet disconnect so the final
-confirm/bye always lands; a vanished peer exits with "The link was
-broken." Internet play needs a forwarded UDP port or a VPN (deliberate
-tradeoff vs. the relay). Headless tests drive the protocol over an
-in-memory loopback (`Net.loopbackPair`); under LÖVE the same test file
-also exercises real UDP pairing.
-
-Red, Blue, and Yellow copies link with each other, as the real cable
-does. The compatibility fingerprint hashes only data a link mode can
-actually read, so Yellow's Dragonair/Dragonite catch-rate retunes (the
-only R/B/Y link-surface difference) no longer read as different games
-(issue #511). Moving the fingerprint is a link parity change: builds
-from before this fix will refuse to pair with builds after it.
-
-## Fair play in link and online matches
-
-A link session is decided by the battle and nothing else, so for its
-duration:
-
-- **Game speed is pinned to normal.** The GAME SPEED option and
-  `POKEPORT_SPEED` are ignored from the moment LINK PLAY opens until it
-  closes, and apply again after. Fast-forward otherwise runs one peer's
-  queue faster than the peer it is locked to and drains a tournament shot
-  clock faster than the opponent racing it.
-- **Online play runs vanilla.** Picking ONLINE MATCH or TOURNAMENT with
-  mods enabled offers to switch them all off and relaunch (mods merge at
-  boot, so a restart is the only way). The restart is confirmed, not
-  silent. They stay listed as disabled, ready to switch back on.
-- **Only a meaningful split ends a match.** The per-turn state signature
-  both peers exchange is split three ways: `actives` and `bench` carry
-  species, HP, status, stat stages, PP and the rest of the party, and a
-  divergence there ends the match as a draw. `volatile` carries per-turn
-  flags both sides recompute anyway - a divergence there is logged and
-  reported to mods, and play continues.
-
-The relay logs which component diverged on which turn, so a desync report
-names something specific.
-
-## Custom boot text
-
-The boot sequence replaces the Nintendo / GAME FREAK identifiers with
-"bois club" / "bryanthaboi",  a deliberate branding customization. The
-rest of the boot beats (copyright splash, "presents" shooting-star, the
-Nidorino-vs-Gengar attract scene) mirror the original.
-
-
-## Custom Options
-
-Options persist in a standalone `options.lua` (separate from the game
-progress `save.lua`), so audio/display/battle preferences survive New Game
-and aren't wiped when a save slot is cleared. Changing a row in the Options
-menu or cycling hotkeys `2`/`3`/`4`/`5` writes immediately; an in-game save also
-flushes the live options. Old saves that still embed an `options` table are
-migrated once into `options.lua` on load.
-
-- Music / SFX volume
-- PIKACHU VOL (0-7, Yellow only): trims Pikachu's PCM voice clips under the
-  SFX level, so the follower's constant chatter, the title-screen cry and
-  every in-battle "Pika!" can be pulled down (or muted at 0) without
-  quieting the rest of the sound effects. The row is hidden on Red/Blue,
-  which have no voice clips.
-- Music Filter
-- OG GLITCHES on / off (Gen 1 quirks vs. modern-clean battle rules)
-- BATTLE LAYOUT (OG / WIDE); see "Widescreen battle layout" below
-- COLORS (OG RED / SGB / ADVANCED / OG / OG INV / SGB INV / CLASSIC),  also
-  hotkey `2` (OG RED = GBC boot-ROM look; ADVANCED uses pokered-gbc
-  SuperPalettes + per-species mon colors)
-- TILT (OFF / 15 / 35 / 50),  also hotkey `3` while free-roaming
-- ZOOM (FIT / OUTn / INn),  also hotkey `4` while free-roaming; wheel and
-  `-`/`=` step one level and save
-- VOID FILL (TREES / WATER / BLACK) for OVERWORLD beyond-edge space
-- GBC FX (OFF / 1 / 2 / 3 / 4),  also hotkey `5`
-- MAX FPS (30 / 40 / 50 / 60 / 75 / 90 / 100 / 120 / 144 / 160, default 60),
-  a hard render frame-rate cap (`save.options.fpsCap`).
-
-## Battle transition cascade + white battle letterbox
-
-Into-battle wipes still run the original eight styles inside the classic
-160×144 letterbox. On wide/tall windows (survey zoom), matching black 8×8
-blocks cascade outward from that square into the surrounding world so the
-void outside the OG wipe fills in lockstep. Once the battle state is up,
-letterbox voids around the battle canvas fill **white** instead of black
-so the whole window reads as one continuous battle screen.
-
-## Widescreen battle layout
-
-Options **BATTLE LAYOUT** picks the battle screen's composition: **OG**
-(the default: the original 160×144 arrangement, unchanged) or **WIDE**,
-which gives battles a 304×144 native-pixel surface and a Gen 3-style
-arrangement on it:
-
-- the foe's status box upper left, the foe's picture upper right;
-- the player's picture lower left, the player's status box lower right,
-  with a longer HP bar and the numeric HP under it;
-- a full-width message window;
-- a split "What will X do?" prompt / 2×2 command window;
-- a 2×2 move menu, navigated with all four directions, with a PP and type
-  panel attached to its right.
-
-Only the composition changes. Pictures, palettes, HP-bar colors, font
-pages, window borders, sounds, animations, timing and every battle rule
-stay the engine's, so a COLORS mode or an asset mod still owns the look.
-Each side's picture keeps its original pixels and placement math and is
-composited into its own region of the wider battlefield -- nothing is
-scaled or squeezed -- and animations, which are authored in the original
-160-pixel space, shift as one rigid group onto whichever side they play
-on. The whole screen is drawn at the window's integer fit scale for the
-wider surface, so a 304-pixel screen is drawn a step smaller than a
-160-pixel one in the same window.
-
-The wide surface is live only while the battle itself is the screen on
-top: a party menu, the bag or a nickname prompt is a 160×144 screen and
-brings the classic surface back with it.
-
-## On-screen touch controls (mobile)
-
-On Android/iOS the game draws a translucent d-pad (bottom-left), A/B
-buttons (bottom-right, Game Boy diagonal), and +/- START/SELECT (bottom
-center) over the frame, using Xelu's CC0 controller prompts
-(`assets/touch/`). Real buttons, not gestures: press lands the frame the
-finger does, sliding on the d-pad changes direction without lifting, and
-multi-touch chords (e.g. hold a direction + tap B) work. The overlay only
-appears while no controller is being used: the first gamepad button or
-stick push hides it, the next screen touch brings it back, and unplugging
-the last controller restores it immediately. Layout re-derives from the
-window size on rotation. Desktop testing: `POKEPORT_TOUCH=1 love .` forces
-the overlay on and lets the mouse act as a finger (`=0` forces it off).
-
-The launcher's **Touch Controls** button opens a drag editor: move each
-button freely, **Disable** to hide the overlay permanently (for
-controllers / emulation handhelds -- distinct from the temporary
-gamepad auto-hide), **Reset** for defaults, **Done** to save into
-`options.lua` as normalized window fractions so rotation keeps the
-relative placement. In-game, Options → **TOUCH PAD** toggles the same
-on/off flag without leaving a play session.
-
-## Translation support
-
-Every string the player can read is now reachable from a mod, so a
-translation is an ordinary content mod rather than a fork.
-
-Two things had to change. Text layout stopped counting bytes: the dialogue
-box measures a line in glyphs (charmap sequences), so a 3-byte character
-costs one column, a cut never lands inside a character, and a page with a
-non-default `advance` re-measures instead of overflowing. That also fixed
-25 vanilla English lines that were wrapping early because `é` in POKéMON
-and POKéDEX costs two bytes ("I study POKéMON as" is 19 bytes and 18
-glyphs, and the box was breaking it).
-
-Second, the text the engine writes itself - battle messages, item results,
-menu labels, the link-play screens - moved behind `src/core/Strings.lua`
-and the new `strings` registry. Extracted script text was already
-overridable through `text`; this covers the other half. Entries are keyed
-by the English source, so a translation that has not reached a string yet
-keeps rendering in English and a half-finished translation stays playable.
-
-Authors generate the whole thing:
-
-```sh
-python3 tools/modkit.py translation francais --language "Francais"
-```
-
-That scaffolds a mod with every translatable string as an empty catalog,
-plus a glyph-page and charmap stub, a naming-grid stub, and a
-`francais-worksheet/` directory holding the English to translate from
-(deliberately outside the mod: extracted text is ROM content and must not
-be packed). `--refresh` re-harvests after an engine update, keeping
-existing translations and parking orphaned keys rather than dropping them.
-
-See the wiki's Translations guide.
-
-## Save editor (bundled, reachable from the launcher)
-
-The save editor ships inside every build instead of being a developer-only
-script, and the launcher's SAVE SLOT card grows an **Edit** label next to
-Delete on every slot that actually holds a save. Edit suspends the
-launcher, opens that slot's file in the editor, and **Close** hands the
-process back to the launcher with the slot list re-read (a rename, a badge
-or a dex change shows up on the row immediately). Unsaved edits arm a
-confirm first, so leaving cannot lose work. `love . --editor` still opens
-it standalone, where Close quits instead; `--save <path>` points it at any
-file, and a save can be dragged onto the window.
-
-The editor now wears the launcher's visual language - the same navy radial
-field, 16px translucent cards, tri-colour version rail and green/yellow/red
-semantics - so the two windows read as one app. Six tabs:
-
-- **Party**: the roster with sprites, HP bars and level chips on the left,
-  and the mon inspector permanently docked on the right instead of floating
-  over the list. Species, level, DVs and moves all round-trip through the
-  Gen 1 formulas, so the inspector can never show illegal stats.
-- **Boxes**: the 12 PC boxes as a 5x4 grid with a fill meter per box and a
-  party dock, so deposit and withdraw live in one place. Empty slots are
-  clickable and create a mon there.
-- **Items**: money, a searchable item picker (replacing the arrows that
-  cycled one id at a time through ~250 items), the configurable bag (20 slots
-  by default), PC storage
-  with no slot cap, and the eight badges as toggle chips.
-- **Events**: flags, defeated trainers, taken items and per-map object
-  toggles, with a real filter field and a two-column paged grid.
-- **Map**: any map rendered with the game's own renderer, warps followable,
-  and the player / lastHeal / lastOutdoor spawn points settable by clicking
-  a cell. Setting lastOutdoor on a map the game would not accept as an
-  outdoor source is refused with the reason.
-- **Dex**: seen / owned completion meters and a four-column grid; owning
-  implies seen and un-seeing clears owned, exactly as the game requires.
-
-Two rules run through all of it. Every mutation goes through one funnel
-that sets the dirty flag and writes the status line together, so nothing
-changes silently and no branch can quietly no-op - "Party is full", "Bag is
-full", "click a cell first" all say so. And every destructive verb (Remove,
-Release, Clear all, Wipe dex) arms on the first click and commits on the
-second, relabelling itself to `Confirm?` in between.
-
-A validation pill in the tab rail mirrors what the running game would
-quarantine on load; clicking it jumps to the tab holding the first problem.
-
-## Tiled map editing (mod authoring)
-
-`tools/tiled_export.py` turns the imported ROM cache into a Tiled workspace,
-so maps can be edited in a real map editor and exported back out as a mod.
-It has its own document: docs/tiled-map-editing.md.
-
-## Pokédex diploma (both versions)
-
-The Celadon Mansion 3F game designer shows the dex-completion diploma
-once 150 species are owned. On Yellow, the graphic artist next to him
-then offers to print it, saving the certificate as a PNG under `prints/`
-in the save directory, and Bill's PC gains Yellow's PRINT BOX item which
-exports the current box list the same way.
-
-## Pokédex printing (Yellow)
-
-Yellow's Game Boy Printer PRNT option in the Pokédex side menu is stood in
-for by an image export: choosing PRNT renders the mon's entry page (sprite,
-kind, number, height/weight, dex text) to a PNG at 4x scale under
-`prints/` in the save directory, then reports the filename in a dialog.
-No printer hardware or link cable emulation involved; the file is the
-printout.
-
-## Find Mods (community mod indexes)
-
-A FIND MODS tab sits beside MODS in the launcher and browses a published
-mod index: a metadata-only feed listing mods that live in their authors'
-own repositories. No index ships with the launcher and none is ever added
-automatically, so the tab opens on an "Add an index" prompt until you name
-one; paste an index URL or its `owner/repo` and it is remembered in
-`options.lua`. More than one index can be added, and the listings merge.
-
-## Soft reset (all versions)
-
-Holding A, B, START and SELECT together restarts the game the way flicking
-a Game Boy's power switch did, dropping straight back to the title screen.
-It works from anywhere, including mid-battle, which the QUIT entry on the
-start menu cannot do: the original combo is how stationary and gift
-Pokemon get their stats rerolled without sitting through a full relaunch.
-Unsaved progress is discarded, exactly as on hardware.
-
-As on the original, the four buttons have to stay held for 16 straight
-polls (better than a quarter of a second) and any direction in the mix
-cancels it, so it is hard to hit by accident -- including on the on-screen
-touch controls, where it would take four fingers held on four separate
-controls.
-
-## Controls rebinding (CONTROLS screen)
-
-OPTIONS -> CONTROLS lists every Game Boy button with its current keyboard
-key and controller button side by side (Z/A). Press A on a row, then press
-and release the key or pad button you want; the rebind commits on the
-release. If that input already belongs to another row, the two rows swap,
-so no button is ever stranded without an input and no input ever serves
-two buttons. Holding a second key or pad button while the first is still
-down backs out of the capture without touching a keyboard; Escape still
-cancels too. SELECT clears one row back to its default, and START resets
-every binding after a confirmation.
+# New Features
+
+Features intentionally added beyond the original Pokémon Red, Blue, and Yellow games:
+
+* **Survey zoom** with connected-map rendering and configurable void fill
+* **Perspective tilt mode** for an HD-2D-style overworld
+* **Multiple color modes**, including original, SGB, advanced GBC, monochrome, and classic green
+* **Optional GBC screen effects**, including pixel grids, shadows, glare, and transparency
+* **Performance presets** and configurable FPS limits
+* **Peer-to-peer link play** for trades and battles between Red, Blue, and Yellow
+* **Persistent custom options** stored separately from game saves
+* **Optional widescreen battle layout**
+* **Mobile touch controls** with editable layouts, vibration, and orientation settings
+* **Translation and custom font support**
+* **Built-in save editor** for parties, boxes, items, events, maps, and Pokédex data
+* **Tiled map editing tools** for mod authors
+* **Pokédex diploma and printer image exports**
+* **Community mod browser**
+* **Soft reset button combination**
+* **Keyboard and controller rebinding**
+* **Mod profiles** with separate mod settings and save slots
+* **Improved launcher and save editor UI**, including background downloads and update checks
+* **Direct-launch options** for shortcuts, Steam entries, and handheld frontends
+* **Custom boot branding**
+
+Actual approximations, and missing original behavior are documented separately in `docs/known-differences.md`.

docs/required-to-function.md

@@ -1,12 +1,11 @@
 # What This Port Requires
 
 The packaged desktop app requires one user-supplied input on first boot: a
-canonical 1 MiB US Pokemon Red ROM.
+canonical 1 MiB US Pokemon Red, Blue, or Yellow ROM.
 
-The importer verifies SHA-1
-`ea9bcae617fdf159b045185467ae58b2e4a48b9a`. Other revisions, Virtual
-Console releases, and Pokemon Blue are rejected rather than decoded with
-incorrect addresses.
+The importer verifies the SHA-1 for the game (see `src/core/GameVersion.lua`
+for specific hashes). Other revisions and Virtual Console releases are rejected
+rather than decoded with incorrect addresses.
 
 After verification, the app generates its private cache in the LÖVE save
 directory. It does not keep a copy of the ROM. Later boots use the cache.
@@ -15,9 +14,11 @@ Python and Pillow are not required by the packaged app.
 ## Bundled Metadata
 
 Assembly removes high-level names and some relationships that the Lua port
-needs. `tools/rom_manifest.json` therefore contains:
+needs. The version-specific files `tools/rom_manifest.json`,
+`tools/rom_manifest_blue.json`, and `tools/rom_manifest_yellow.json` therefore
+contain:
 
-- the 3,268 ROM symbol addresses actually read by the extractor
+- the ROM symbol addresses actually read by the extractor
 - symbolic IDs and ordering for maps, species, moves, items, and trainers
 - source-erased dimensions, image names, and map object integration names
 - hand-ported field/script integration tables

docs/rfcs/0001-surfing-pikachu-sprite.md

@@ -0,0 +1,96 @@
+# RFC 0001 — Port Yellow's `IsSurfingPikachuInParty` surf sprite
+
+## Status
+
+Proposed. Engine: `Player.lua`, `FieldDefaults.lua`,
+`OverworldController.lua`, `RomExtractor.lua`, `PaletteFX.lua`. Tools:
+`build_rom_data.py`, `extract/sprites.py`, `make_rom_manifest.py`,
+`make_yellow_manifest.py`. Tests: `parity_surfing_pikachu_sprite.lua`,
+`mod_world_tests.lua`.
+
+**Regeneration required.** The manifest and sprite sheet update by
+re-running `make_yellow_manifest.py` against a `pret/pokeyellow`
+checkout, then re-importing the Yellow ROM.
+
+## Motivation
+
+Yellow's `IsSurfingPikachuInParty` + `LoadSurfingPlayerSpriteGraphics2`
+(`home/map_objects.asm`, `home/overworld.asm`) swap the player's
+overworld sheet to `SurfingPikachuSprite` (`gfx/sprites/
+surfing_pikachu.2bpp`, a 16×96 walk sheet — not the minigame sheets)
+when the party mon that knows SURF is a Pikachu. The recomp misses this
+in two places:
+
+1. **Extraction.** `SurfingPikachuSprite` is not in
+   `SpriteSheetPointerTable` — loaded by its own `ld de,` like
+   `RedBikeSprite`. The extractor never sees it, and the symbol is not
+   in the Yellow manifest.
+2. **Engine rule.** `field.playerSprites.surf` is one static
+   (`SPRITE_SEEL`), cached at boot. No seam for "swap when the SURF-mon
+   is a Pikachu."
+
+## The decision it extends
+
+No prior D-number. Extends the surf-field-move port in
+`docs/behavior-porting-notes.md` (the `IsSurfingAllowed` exact port)
+with the player-sprite swap vanilla runs alongside it.
+
+## The exact API delta
+
+Backward-compatible, additive-only.
+
+### `field.playerSprites.surfPikachu`
+
+New optional key alongside `walk`/`surf`/`bike`/`fly`, defaults to
+`SPRITE_SURFING_PIKACHU`. Guarded in `Player.new` so before extraction
+lands the ride keeps the Seel — no plain on-water Pikachu.
+
+### `Player.surfPikachuSprite`
+
+`Player.new` builds a second `SpriteRenderer` when the field resolves.
+`pose()` picks it when `surfing and surfingPikachu`.
+
+### `Player.surfingPikachu` (runtime)
+
+Runtime-only boolean (not persisted); re-derived so a party change
+between save and load is honored.
+
+### `OverworldState:syncSurfingPikachu()`
+
+Sets `player.surfingPikachu` from `partyKnows("SURF")`. Called at every
+surf-state toggle: trySurf, dismount, flyTo, beginTeleportOut,
+warpToHealPoint, forced-surf tile, setMap boot-restore.
+
+### Importer — `SPRITE_SURFING_PIKACHU`
+
+`make_yellow_manifest.py` adds `SurfingPikachuSprite` to
+`YELLOW_EXTRA_SYMBOLS`. `make_rom_manifest.py`'s `sprite_metadata()`
+gains a `surfPikachu` entry (guarded, so Red/Blue unchanged).
+`RomExtractor.extractSprites` + `build_rom_data.py` + `extract/sprites.py`
+each gain a parallel extract mirroring `RedBikeSprite`.
+
+### `PaletteFX.spriteObp`
+
+`SurfingPikachuSprite` joins `RedBikeSprite` in the no-bracket-index
+special case, wearing the player's OBP palette so it colors in GBC mode.
+
+## Migration note for existing mods
+
+**Nothing.** `surf` still defaults to `SPRITE_SEEL`; `surfPikachu`
+only resolves on a Yellow import after regeneration. No manifest or
+`mod.save` shape changes. An eligibility hook that swaps a rental
+SURF-mon still drives the sprite pick via `partyKnows`.
+
+## Parity tests
+
+- **No-mod** (`mod_world_tests.lua`): `surf == "SPRITE_SEEL"`,
+  `surfPikachu == "SPRITE_SURFING_PIKACHU"` seeded at boot. The 19229-check
+  `world & maps v2` suite stays green.
+- **Mod-API** (`parity_surfing_pikachu_sprite.lua`): `syncSurfingPikachu`
+  + `Player:pose` across four party shapes (12/12). The existing
+  `parity_cinnabar_east_surf.lua` (24/24) stays green.
+
+## Deprecation etiquette
+
+Nothing deprecated. Additive: a new `field.playerSprites` key, a new
+runtime flag, a new engine method, a new sprite id.

docs/rfcs/0002-screen-render-visible.md

@@ -0,0 +1,54 @@
+# RFC 0002 — Let mods hide an active screen state from the main render
+
+## Status
+
+Proposed. Engine: `StateStack.lua`, `Game.lua`. Tests:
+`screen_render_visible.lua`.
+
+## Motivation
+
+A mod can render a native menu on a companion display through
+`render.compose`, but it cannot remove that menu from the main display without
+also popping it. Popping transfers update and input ownership and forces the
+mod to reimplement native menu behavior.
+
+## The decision it extends
+
+No prior D-number. Extends the render-hook plan in `docs/modding.md` and the
+state-stack rendering contract in `docs/architecture.md`.
+
+## The exact API delta
+
+Backward-compatible, additive-only.
+
+### `screen.render_visible`
+
+New hook called with `(state) -> boolean` through the public wrapper signature
+`(next, state)`. Its vanilla result is `true`.
+
+Returning `false` excludes the state from the main draw, from opaque-base
+selection and from palette-zone ownership. It does not remove the state or
+change update, input, push or pop behavior. The call sites are
+`StateStack:visibleBase`, `StateStack:draw` and the equivalent draw and palette
+walks in `Game:draw`.
+
+The hook is guarded by `Runtime.wantsHook`, so the no-subscriber path allocates
+nothing. It is a pure render predicate and may be evaluated more than once per
+frame.
+
+## Migration note for existing mods
+
+**Nothing.** With no subscriber every state remains visible, and the existing
+state-stack, event and hook behavior is unchanged.
+
+## Parity tests
+
+- **No-mod:** the topmost opaque state still owns drawing and palette zones,
+  and `Runtime.wantsHook("screen.render_visible")` stays false.
+- **Mod-API:** a fixture mod registers through `mod.hooks:wrap`, hides one
+  opaque state and proves the state beneath draws and owns the palette while
+  the hidden state remains topmost and continues updating.
+
+## Deprecation etiquette
+
+Nothing deprecated. This is one additive hook with a `true` vanilla default.

docs/switch-build.md

@@ -0,0 +1,244 @@
+# Build Gen1Recomp for Nintendo Switch
+
+Want to play a release build instead? Download the SD-ready zip and extract it
+at your microSD root. See [switch-install.md](switch-install.md).
+
+This guide is for contributors who build Gen1Recomp for Switch from source.
+
+> Releases ship `gen1recomp-*-switch.zip` (SD tree under `switch/gen1recomp/`).
+> Runtime target is pinned [love-nx](https://github.com/retronx-team/love-nx)
+> `11.5-nx1`. Player install and limitations: [switch-install.md](switch-install.md).
+
+---
+
+## Prerequisites by OS
+
+All packaging entrypoints are **bash**. On Windows, use Git Bash, MSYS2, or
+WSL, not cmd.exe or PowerShell (AD-008).
+
+### macOS / Linux
+
+1. Install [devkitPro pacman](https://devkitpro.org/wiki/devkitPro_pacman).
+2. Install Switch tools (**required for `--fused`**):
+
+   ```sh
+   sudo dkp-pacman -S switch-dev
+   ```
+
+3. OTA launcher toolchain, **native or Docker** (either is fine):
+
+   ```sh
+   bash scripts/switch/install_devkitpro_deps.sh   # native
+   # or install Docker (same pin as fused builds)
+   ```
+
+4. Ensure `DEVKITPRO` is exported (typical macOS: `/opt/devkitpro`) and
+   `nacptool` / `elf2nro` are on `PATH` (or under `$DEVKITPRO/tools/bin`).
+
+Fused game builds can also use Docker when native `nacptool`/`elf2nro` are absent.
+
+### Native OTA launcher (included in `--fused`)
+
+In-console OTA uses a **separate DEVKITPRO NRO** (not LÖVE). The LÖVE
+self-updater (`Check.lua`) is disabled on NX. Source:
+`ports/switch/ota-launcher/`. Host protocol tests (no toolchain):
+
+```sh
+make -C ports/switch/ota-launcher host-test
+# or
+scripts/switch/build_ota_launcher.sh   # host-test first; NRO needs DEVKITPRO/Docker
+```
+
+`--fused` always builds the fused game, native OTA launcher, and dual-NRO SD
+zip. The same `*-switch.zip` is the OTA download asset. **DEVKITPRO is
+required.** OTA launcher: native packages **or** Docker. Both are supported.
+
+Release-like build from repo root:
+
+```sh
+scripts/build_switch.sh --fetch --fused --version X.Y.Z
+```
+
+See `ports/switch/ota-launcher/README.md` and
+`scripts/switch/ota_launcher.manifest`.
+
+### Windows (Git Bash / MSYS2 / WSL)
+
+1. Use a bash environment:
+   - **MSYS2** with the [devkitPro](https://devkitpro.org/wiki/devkitPro_pacman)
+     packages (preferred for native `nacptool`/`elf2nro`), or
+   - **WSL** (Ubuntu/etc.) with the Linux pacman flow above, or
+   - **Git Bash** for `--fetch` / `--loose`; for `--fused` prefer MSYS2 or
+     WSL if Docker bind-mounts from Git Bash paths misbehave.
+2. Install `switch-dev` (or rely on Docker fallback; see below).
+3. Do **not** expect `scripts/build_switch.sh` to run under cmd/PowerShell.
+
+### What you must install yourself
+
+| You install | Script does **not** install |
+| ----------- | --------------------------- |
+| bash, git, zip tooling the repo already expects | (none) |
+| `dkp-pacman` + `switch-dev` + OTA packages **or** Docker | `dkp-pacman -S …` |
+| A legal `.gb` ROM (to play) | Any ROM or game data |
+
+---
+
+## Mode glossary
+
+`scripts/build_switch.sh` supports three modes (combinable as noted):
+
+| Mode | What it does |
+| ---- | ------------ |
+| `--fetch` | Downloads pinned **love.nro** + **love.elf** into `.bazinga/love-nx/11.5-nx1/` and verifies SHA-256 against `scripts/switch/love-nx-11.5-nx1.sha256`. |
+| `--loose` | Packs `game.love`, copies pinned `love.nro` → `dist/switch/loose/` as `gen1recomp.nro` + `game.love` side by side. Needs the pin. |
+| `--fused` | Builds fused game NRO, OTA launcher NRO, and dual-NRO SD zip. **Requires DEVKITPRO** + `switch-dev`. OTA launcher: native packages or Docker. GitHub Releases publish the **zip only**. |
+
+Rules:
+
+- `--fetch` alone is fine; combine as `--fetch --loose` or `--fetch --fused`.
+- `--loose` and `--fused` are **XOR**. Pick one packaging path per run.
+- `--version X.Y.Z` sets the NACP / filename version (defaults to short git SHA).
+
+### What `--fetch` downloads
+
+Only the two pinned love-nx release assets (`love.nro`, `love.elf`). It does
+**not** install:
+
+- devkitPro / `dkp-pacman` / `switch-dev`
+- Docker
+- ROMs, saves, or mods
+
+---
+
+## Native tools, then Docker
+
+Fused packaging (`scripts/switch/build_fused.sh`):
+
+1. Prefer native `nacptool` + `elf2nro` on `PATH` (or `$DEVKITPRO/tools/bin`).
+2. Else fall back to Docker using:
+   - `GEN1_DKP_IMAGE` if set, otherwise
+   - the image named in `scripts/switch/dkp-docker.image` (default
+     `devkitpro/devkita64:latest`).
+
+If neither native tools nor Docker work, the script exits non-zero with
+macOS / Linux / Windows / Docker hints and a pointer to this doc.
+
+---
+
+## Example commands
+
+From the repo root:
+
+```sh
+# Download pinned love-nx only
+scripts/build_switch.sh --fetch
+
+# Loose pair for iteration (fetch + assemble)
+scripts/build_switch.sh --fetch --loose
+
+# Fused game + OTA launcher + dual-NRO SD zip for a release-like artifact
+scripts/build_switch.sh --fetch --fused --version 0.2.0
+```
+
+Outputs land under `dist/switch/` (and `dist/switch/loose/` for loose mode).
+The fused path also writes `gen1recomp-<ver>-switch.nro` (game),
+`gen1recomp-<ver>-launcher.nro`, `gen1recomp-<ver>-game.nro`,
+`gen1recomp-<ver>-switch.nro.sha256`, and `gen1recomp-<ver>-switch.zip`
+(+ `.sha256` sidecar for the zip).
+
+Offline packaging smoke (no network, no nacptool required):
+
+```sh
+bash scripts/switch/selftest_build_switch.sh
+bash scripts/switch/verify_payload.sh --self-test
+```
+
+---
+
+## CI and release
+
+Switch packaging has three automated surfaces (same policy as AD-010):
+
+### Path-gated PR / push CI (`.github/workflows/ci.yml`)
+
+When a change touches Switch packaging / Switch docs / NX runtime paths
+(`scripts/build_switch.sh`, `scripts/switch/**`, `docs/switch-*.md`,
+`tests/switch_ci_workflows_test.lua`, `tests/switch_transfer_docs_test.lua`,
+the NX runtime modules `src/core/NxAssetOverlay.lua`, `src/core/Platform.lua`,
+`src/core/GameVersion.lua`, `src/import/CacheFs.lua`, the NX engine suites
+`tests/engine/assets_version_fallback_test.lua`,
+`tests/engine/nx_generated_guard_test.lua`,
+`tests/engine/nx_yellow_boot_test.lua`,
+`tests/engine/switch_diagnostics_test.lua`, `tests/engine/platform_nx_*`,
+or the Switch-related workflow YAML), CI runs:
+
+1. **Offline selftest** on `ubuntu-latest` (forks **and** the main repo):
+   `scripts/switch/selftest_build_switch.sh`,
+   `scripts/switch/verify_payload.sh --self-test`,
+   `luajit tests/switch_ci_workflows_test.lua`,
+   `luajit tests/switch_transfer_docs_test.lua`, and the NX engine suites
+   headlessly (`luajit tests/engine/assets_version_fallback_test.lua`,
+   `luajit tests/engine/nx_generated_guard_test.lua`,
+   `luajit tests/engine/nx_yellow_boot_test.lua`).
+2. **Fused NRO build** only on the **main** repository
+   (`bryanthaboi/gen1recomp`), on the self-hosted Mac runner
+   (`scripts/build_switch.sh --fetch --fused`), and only when the workflow
+   head is that repo (same-repo push/PR). Fork CI never runs fused. Fork PRs into the main repo also skip Switch fused (offline selftest still runs) so untrusted head code is not executed on the self-hosted Mac; iOS device build eligibility is unchanged. Fused also waits for a successful offline selftest before starting on the Mac runner.
+3. On successful PR fused builds, a follow-up workflow posts a PR comment
+   linking the Actions artifact named `gen1recomp-switch-nro`
+   (comment tag `switch-build-result`; see
+   `.github/workflows/switch-artifact-comment.yml`).
+
+Unrelated PRs do not burn the self-hosted Mac on Switch packaging.
+
+### Release hard-fail (`.github/workflows/release.yml`)
+
+GitHub Releases always build Switch on the same self-hosted Mac runner as the
+other platforms. This is a **hard gate** (no `continue-on-error`):
+
+```sh
+scripts/build_switch.sh --fetch --fused --version "<release version>"
+```
+
+A Switch packaging failure fails the entire release job. The release asset is
+`gen1recomp-<ver>-switch.zip` (SD-ready); the versioned `.nro` stays under
+`dist/switch/` for the packer and for PR CI artifacts.
+
+### Runner provisioning
+
+The self-hosted Mac runner **must** have **DEVKITPRO** installed and exported.
+`--fused` preflight fails early with setup steps if it is missing.
+
+**One-time setup on the runner** (if not already present):
+
+```sh
+# devkitPro pacman installer from https://devkitpro.org/wiki/devkitPro_pacman
+sudo dkp-pacman -S switch-dev
+export DEVKITPRO=/opt/devkitpro
+export PATH="$DEVKITPRO/tools/bin:$PATH"
+
+# OTA launcher: pick one
+bash scripts/switch/install_devkitpro_deps.sh   # native
+# or ensure Docker is installed (same pin as fused builds)
+```
+
+CI and release still run `scripts/build_switch.sh --fetch --fused`. Preflight
+requires DEVKITPRO and either native OTA packages or Docker. Without all of
+that, the job fails with the setup steps above. Scripts never auto-run
+`dkp-pacman -S` during CI.
+
+---
+
+## Limitations / non-goals
+
+These scripts and this guide do **not**:
+
+- Push files to the console (no automated MTP / FTP / SD scripting)
+- Bundle or download any Pokémon ROM
+- Install `dkp-pacman` / `switch-dev` for you
+- Provide `nxlink` / netloader deploy (deferred; see [switch-transfer.md](switch-transfer.md))
+- Validate **Applet Mode**. Use title override (hold **R**) for full memory
+
+Player install steps: [switch-install.md](switch-install.md).  
+Manual transfer (MTP / SD / FTP, macOS / Linux / Windows):
+[switch-transfer.md](switch-transfer.md).

docs/switch-install.md

@@ -0,0 +1,204 @@
+# Install Gen1Recomp on Nintendo Switch
+
+Every GitHub Release that includes Switch support ships an SD-ready zip:
+`gen1recomp-*-switch.zip`. Extract it at the root of your microSD (install
+or update, same steps), launch with **title override**, then import your
+own legal `.gb` ROM.
+
+> You need a console that can run Switch homebrew (custom firmware / hbmenu).
+> This project does not help you set that up.
+
+Prefer building from source? See [switch-build.md](switch-build.md).
+
+Port by [andrewqsantos](https://github.com/andrewqsantos). Community testing
+help from [booshankles](https://github.com/booshankles).
+
+## 1. Download the zip
+
+1. Open
+   [Releases](https://github.com/bryanthaboi/gen1recomp/releases).
+2. Download `gen1recomp-*-switch.zip` for the version you want.
+   (Optional: verify against `sha256sums.txt` in the same release.)
+
+## 2. Extract onto the microSD
+
+Extract the zip at the **root** of the microSD so you get:
+
+```text
+sdmc:/switch/gen1recomp/gen1recomp.nro          # native OTA launcher (hbmenu entry)
+sdmc:/switch/gen1recomp/gen1recomp-game.nro     # fused LÖVE game
+sdmc:/switch/gen1recomp/version.txt
+sdmc:/switch/gen1recomp/pokemon-love2d/imports/
+sdmc:/switch/gen1recomp/pokemon-love2d/imports/mods/
+sdmc:/switch/gen1recomp/pokemon-love2d/imports/saves/...
+```
+
+Older single-NRO zips only had `gen1recomp.nro` (the fused game). Current
+releases use the dual-NRO layout above. Open `gen1recomp` in hbmenu (the
+launcher).
+
+Merge folders if your OS asks. Any method works: **MTP** (DBI → Run MTP
+responder + a client), **direct SD** (Hekate UMS or a card reader), or **FTP**.
+Exit MTP / unmount / stop FTP cleanly before launching. Step-by-step for
+macOS, Linux, and Windows: [switch-transfer.md](switch-transfer.md).
+
+### Updating
+
+#### Native OTA launcher (in-console)
+
+Switch OTA runs in a separate **native launcher NRO** (libnx + curl), not the
+LÖVE self-updater (`src/update/Check.lua`). hbmenu opens `gen1recomp.nro`.
+
+When a newer release exists, the launcher downloads the same install zip
+(`gen1recomp-*-switch.zip`), checks SHA-256 against `sha256sums.txt`, replaces
+both `gen1recomp-game.nro` and `gen1recomp.nro` (keeps NACP version in sync
+for hbmenu and Sphaira), then loads the game with `envSetNextLoad`.
+
+If you are up to date or offline, it skips straight to the game with no
+prompt. If an update is available, you get a short prompt styled like the
+in-game launcher: black background, RGB rail, logo, A/B buttons. Saves under
+`pokemon-love2d/` are not touched. See `src/update/SwitchOta.lua` for the
+wire format.
+
+The LÖVE self-updater stays **disabled** on NX (`networkValidated == false`).
+
+**Sphaira forwarder (HOME shortcut):** Sphaira copies name/version/icon into
+the installed forwarder at creation time. After an OTA (or zip) update, the
+`.nro` on the microSD already has the new version, but the HOME shortcut
+keeps the old badge until you **reinstall the forwarder once** in Sphaira
+(Install Forwarder again on `gen1recomp.nro`). Browsing the NRO in Sphaira /
+hbmenu always shows the live file version.
+
+#### Manual zip (fallback)
+
+Use the **same** extract/merge of `gen1recomp-*-switch.zip`. It replaces the
+NROs (and the small help `README.txt` / `INSTALL.txt` files). Saves,
+imported ROMs, mods, and options live under `pokemon-love2d/`. **Do not
+delete that folder** when updating, or you will lose progress.
+
+## 3. Launch with title override
+
+**Applet Mode is not supported** for this game (not enough memory).
+
+1. On the Switch HOME menu, highlight any installed title.
+2. Hold **R** and launch that title. This opens hbmenu with full memory
+   (title override).
+3. From hbmenu, open `gen1recomp`.
+
+Do **not** launch from the Album applet path for normal play.
+
+## 4. Import your ROM
+
+This project ships **no** game data. On first launch:
+
+1. Put your own legally obtained Pokémon Red, Blue (`.gb`), or Yellow
+   (`.gbc`) dump into `switch/gen1recomp/pokemon-love2d/imports/` (the
+   launcher also shows the live save-dir path). All three can sit in the
+   same folder.
+2. Use **Scan again** on that game's tab (Red / Blue / Yellow). Rescan
+   matches by ROM SHA-1 for the open tab only. A Red dump never imports
+   from the Yellow tab (and vice versa).
+
+## 5. Import / Export a raw `.sav`
+
+Continue a cart or PC battery save (or pull a slot off-console) via MTP /
+SD / FTP, same transfer methods as ROMs. Paths are **per game**:
+
+| Game | Import inbox | Export folder |
+| ---- | ------------ | ------------- |
+| Red | `imports/saves/red/` | `exports/red/` |
+| Blue | `imports/saves/blue/` | `exports/blue/` |
+| Yellow | `imports/saves/yellow/` | `exports/yellow/` |
+
+(Under the save dir `pokemon-love2d/`. The zip already creates these folders.)
+
+1. Copy a Gen1 `.sav` (32 KB) into that game's inbox under the save dir
+   ([switch-transfer.md](switch-transfer.md)).
+2. With the game's ROM already imported, open **that game's tab** →
+   **SAVE FILES** → **Import save**. Only that folder is scanned.
+3. A successful import retires the file to `*.sav.imported` and records its
+   content hash so pressing **Import save** again does not clone slots.
+   Failed imports leave the original `.sav` in place.
+4. To pull a slot off the console, use **Export save**, then copy the file
+   from that game's **`exports/<game>/`** folder via MTP / SD / FTP.
+
+Do not put `.sav` files into git. Prefer clean copies. Some MTP clients
+create `._*.sav` AppleDouble sidecars that are not real saves.
+
+## Controls
+
+### Gameplay
+
+| Control | Action |
+| ------- | ------ |
+| D-pad / left stick | Move |
+| **A** | Confirm |
+| **B** | Cancel |
+| **+** (Start) | Start |
+| **−** (Select) | Select |
+| **R** (no Select held) | Cycle game speed up |
+| **L** (no Select held) | Cycle game speed down |
+
+### Launcher
+
+| Control | Action |
+| ------- | ------ |
+| D-pad / left stick | Move virtual cursor |
+| **A** | Click at cursor |
+| **L** / **R** | Previous / next tab |
+| **Start** / **Select** | Play if a ROM is ready; otherwise Choose ROM |
+
+### System
+
+| Control | Action |
+| ------- | ------ |
+| Hold **R** on HOME, then open from hbmenu | Title override (full memory) |
+
+## Community mods
+
+Mods install from a zip inbox (same transfer methods as ROMs):
+
+1. Copy a release `.zip` into the save-dir **`imports/mods/`** path the
+   launcher shows (MTP / SD / FTP. See [switch-transfer.md](switch-transfer.md)).
+2. In the launcher, open **MODS** → **Scan again** → enable the mod →
+   **Play**.
+
+Remote **FIND MODS** / GitHub download stays **off** on Switch. Do not put
+mod zips into git. Community mods ship their own OPTIONS / rebinds. This port
+does not document third-party control tables.
+
+### Joy-Con shortcuts (Select + face)
+
+Hold **Select** (−) and press a face/shoulder button. Without Select, A/B stay
+normal gameplay confirm/cancel. These chords are the stock engine display
+hotkeys (`2`/`3`/`5` are claimed before any mod pipeline hotkey runs).
+
+| Chord | Same as PC key | Stock engine effect |
+| ----- | -------------- | ------------------- |
+| Select + **A** | `2` | COLORS |
+| Select + **B** | `3` | TILT |
+| Select + **Y** | `5` | GBC FX |
+| Select + **X** | `6` | Mod pipeline hotkey (if a mod registers `6`) |
+| Select + **L** | `7` | Mod pipeline hotkey (if a mod registers `7`) |
+
+If the handheld stutters with extras on, try **OPTIONS → PERFORMANCE** →
+`LOW` or `BALANCED`.
+
+## Limitations
+
+- You need homebrew (custom firmware, hbmenu). This project does not set that
+  up.
+- Launch with title override (hold **R** on a title). Applet Mode (Album) is
+  not supported. The game needs full memory.
+- ROMs, mods, and saves are copied manually via MTP, direct SD, or FTP. There
+  is no automated deploy.
+- Updates use the native OTA launcher only. The LÖVE self-updater and remote
+  **FIND MODS** stay off on Switch.
+- Tested on Switch OLED. Switch V1 / Erista boot confirmed by the community.
+  Other models may work but are less tested.
+
+## Prefer building it yourself?
+
+Building the fused NRO (and SD-ready zip) from source is covered in
+[switch-build.md](switch-build.md). Copying artifacts and inbox files
+(MTP / SD / FTP on macOS, Linux, Windows): [switch-transfer.md](switch-transfer.md).

docs/switch-transfer.md

@@ -0,0 +1,165 @@
+# Switch file transfer (MTP / SD / FTP)
+
+Ways to put Gen1Recomp artifacts and inbox files onto a Nintendo Switch.
+**Any method is valid** if the bytes land in the destinations below.
+
+This is the runbook for contributors on **macOS, Linux, and Windows**.
+Player install (what to download, title override) stays in
+[switch-install.md](switch-install.md). Packaging stays in
+[switch-build.md](switch-build.md).
+
+> **Not supported yet:** `nxlink` / hbmenu netloader automation. Useful later
+> for a fast contrib rebuild loop; deferred (AD-009). Do not treat netloader as
+> the release or ROM/mod install path.
+
+---
+
+## Destinations (shared by every method)
+
+| What | Where on the console |
+| ---- | -------------------- |
+| SD-ready release zip | Extract at microSD **root** → `sdmc:/switch/gen1recomp/gen1recomp.nro` plus `pokemon-love2d/` inbox folders. Install and update use the same merge; do **not** delete `pokemon-love2d/` |
+| Loose iteration pair | `sdmc:/switch/gen1recomp/gen1recomp.nro` **and** `game.love` beside it |
+| ROM inbox | LÖVE save dir → `imports/` (launcher shows the live `getSaveDirectory()` path; under MTP often `1: SD Card/<save identity>/imports/`) |
+| Mod zip inbox | Same save dir → `imports/mods/` then MODS → **Scan again** |
+| Save `.sav` inbox | Same save dir → `imports/saves/red\|blue\|yellow/` then that game's SAVE FILES → **Import save** |
+| Save exports | Same save dir → `exports/red\|blue\|yellow/` (pull after **Export save**; MTP / SD / FTP) |
+| Opt-in diagnostics | Empty `switch-debug.txt` in the save dir → `switch.log` |
+| Lua error log | `lua-error.log` in the save dir |
+
+Saves persist across zip re-extract / NRO replacements as long as
+`pokemon-love2d/` is left in place. Never commit ROM dumps, `.sav`
+files, or third-party mod zips to git.
+
+---
+
+## Transfer methods
+
+### 1. MTP (DBI responder + host client)
+
+On the Switch: close Gen1Recomp → open **DBI** → **Run MTP responder** (often
+**X** on the main screen) → keep that screen up → USB-C data cable to the host.
+
+On the host: open **one** MTP client, navigate to **`1: SD Card`**, then the
+paths above. Wait for the transfer queue; refresh; exit MTP on the Switch
+before launching.
+
+#### macOS (example: OpenMTP)
+
+[OpenMTP](https://github.com/ganeshrvel/openmtp) is a documented example for
+macOS, not a Mac-only requirement.
+
+1. Quit other MTP clients.
+2. Open OpenMTP → select the DBI device → **`1: SD Card`**.
+3. Create `switch/gen1recomp/` if needed; extract the release zip at SD root
+   (or copy NRO / `game.love` for loose).
+4. For ROMs/mods/saves, open the save-dir `imports/`, `imports/mods/`,
+   `imports/saves/<red|blue|yellow>/`, or `exports/<red|blue|yellow>/` path the
+   launcher prints.
+5. Wait for the queue; refresh; exit MTP responder; title-override launch.
+
+macOS clients often create AppleDouble sidecars (`._Something.zip`,
+`._cart.gb`, `._foo.sav`). Those are not real archives or saves. The
+launcher skips hidden `.*` names. Delete `._*` junk if a zip/ROM/`.sav`
+fails to open.
+
+#### Linux
+
+1. Install desktop MTP support if needed (e.g. `gvfs-mtp` on GNOME/GTK
+   desktops, or your distro's KDE MTP stack).
+2. With DBI MTP active, open **Files** / **Dolphin** / **Thunar** and select
+   the Switch / DBI device → **`1: SD Card`**.
+3. Extract the release zip at SD root (merge), or copy into `switch/gen1recomp/`
+   and the save-dir inboxes as above.
+4. Use **only one** MTP accessor at a time. If `mtp-tools` / `mtpfs` reports
+   "device is busy", close the file manager's MTP mount (or the CLI mount)
+   and retry with a single client.
+5. Eject/unmount cleanly; exit MTP on the Switch; title-override launch.
+
+If MTP is unavailable or flaky on Linux, use **direct SD** (Hekate UMS or a
+card reader) or **FTP** instead. Same destinations in the table above.
+
+#### Windows
+
+1. With DBI MTP active, open **This PC** / **File Explorer** and look under
+   **Portable Devices** for the Switch / DBI MTP volume → **`1: SD Card`**.
+2. Copy / extract into `switch\gen1recomp\` and the save-dir inboxes.
+3. Optional: [OpenMTP](https://github.com/ganeshrvel/openmtp) on Windows if
+   Explorer is flaky.
+4. If Windows does not show an MTP device: Device Manager → find DBI / Switch
+   → Update driver → **MTP USB Device** (or Standard MTP Device). Prefer a
+   data-capable USB-C cable and a direct port.
+5. Safely disconnect; exit MTP on the Switch; title-override launch.
+
+If MTP is unavailable or flaky on Windows, use **direct SD** (Hekate UMS or a
+card reader) or **FTP** instead. Same destinations in the table above.
+
+### 2. Direct SD (Hekate UMS or card reader)
+
+Same destinations; no MTP client required.
+
+- **Hekate UMS** (preferred when available): expose the microSD to the host
+  while the card stays in the console; mount the volume; copy files; **cleanly
+  unmount** before leaving UMS.
+- **Physical reader**: power off / remove the microSD, copy on the host,
+  **eject safely**, reinsert, boot CFW, title-override launch.
+
+Do not yank the card or unplug UMS mid-write.
+
+### 3. FTP (any SD-exposing Switch FTP)
+
+Any homebrew FTP server that can write the microSD is fine. For example
+**DBI's own FTP**, **sys-ftpd-light**, or **Sphaira**. Names are illustrations
+only; pick what your CFW setup already uses.
+
+1. Start the FTP server on the Switch; note IP/port/credentials from that app.
+2. From the host, connect with any FTP client and upload to the same
+   `switch/gen1recomp/`, `imports/`, `imports/mods/`, `imports/saves/<game>/`,
+   and `exports/<game>/` paths.
+3. Stop the FTP server cleanly before launching Gen1Recomp.
+
+If credentials or chroots differ by app, trust the **destination paths**, not
+a single vendor tutorial.
+
+---
+
+## After every transfer
+
+1. Exit MTP / unmount SD / stop FTP cleanly.
+2. Launch via **title override** (hold **R** on a title → hbmenu). **Applet
+   Mode is not supported** (not enough memory).
+3. For ROMs: open the matching game tab → **Scan again** if the file was
+   added after boot (SHA-1 must match that tab; other dumps in `imports/`
+   stay for their own tabs). For mods: MODS → **Scan again** → enable →
+   Play. For saves: SAVE FILES → **Import save** (rescans
+   `imports/saves/<game>/`). Pull exported `.sav` files from
+   `exports/<game>/`. Joy-Con display chords (stock engine):
+   [switch-install.md](switch-install.md#joy-con-shortcuts-select--face).
+
+### Optional NRO integrity check
+
+For the first deploy of a given artifact (or after a flaky cable):
+
+```bash
+shasum -a 256 path/to/gen1recomp.nro   # or sha256sum
+```
+
+Copy the file back from the SD and compare hashes. Round-trip must match.
+
+---
+
+## Failure modes (quick)
+
+| Symptom | What to try |
+| ------- | ----------- |
+| Device busy / no MTP volume | One client only; different cable/port; Windows MTP USB Device driver; alternate method (SD or FTP) |
+| Zip/ROM/`.sav` "could not be opened" | Delete `._*` sidecars (including `._*.sav`); confirm real zip starts with `PK` |
+| Half-copied NRO / crash on boot | Re-copy; verify SHA-256; exit transfer mode before launch |
+| App opens in Applet Mode | Use title override (hold **R**), not Album |
+
+---
+
+## Related
+
+- Players: [switch-install.md](switch-install.md)
+- Builders: [switch-build.md](switch-build.md)

docs/timing-parity.md

@@ -0,0 +1,382 @@
+# Timing parity with the Game Boy
+
+The port's clock is faithful: `src/core/FixedStep.lua` advances game logic in
+whole 1/60 s steps off wall-clock `dt`, the default speed multiplier is 1x
+(`src/core/GameSpeed.lua:22`), and audio runs on its own real-time accumulator
+so fast-forward cannot pitch it. Almost nothing in `src/` is seconds-based.
+
+What diverges is the **frame budget of composed sequences**. The original
+spends a large fraction of its running time inside `DelayFrames` calls that
+produce no visible change - the pause after a page break, the beat before a
+status move resolves, the drain of an HP bar one point at a time. Those are
+invisible in a screenshot and easy to drop when porting behavior rather than
+timing. Dropping them is why the port reads as faster and snappier than
+hardware even though every individual animation is correct.
+
+This document is the specification: what each sequence costs on hardware, and
+where that number comes from.
+
+## Method
+
+`tools/scan_pokered_delays.ps1` walks the disassembly and reports every
+frame-consuming wait with its enclosing routine label:
+
+| Kind | Meaning | Frames |
+| --- | --- | --- |
+| `DelayFrames` | `ld c, N` + `call DelayFrames` (`home/delay.asm:1`) | N |
+| `DelayFrame` | one vblank wait (`home/vblank.asm:92`) | 1 |
+| `Delay3` | `home/palettes.asm:14`, three frames for a full bg-map update | 3 |
+| `Fade` | the `GBFade*` helpers, expanded to their totals below | 24 or 32 |
+
+Current inventory against `pokered-master`: **450 sites** - 181 `DelayFrames`,
+164 `Delay3`, 65 `DelayFrame`, 31 `GBFade*`, and 9 `DelayFrames` calls whose
+count is computed at runtime.
+
+The four fades all live in `home/fade.asm` and are loops of
+`ld c, 8 / call DelayFrames`:
+
+| Routine | Iterations | Frames | Source |
+| --- | --- | --- | --- |
+| `GBFadeInFromBlack` | 4 | **32** | `home/fade.asm:21` |
+| `GBFadeOutToBlack` | 4 | **32** | `home/fade.asm:43` |
+| `GBFadeOutToWhite` | 3 | **24** | `home/fade.asm:26` |
+| `GBFadeInFromWhite` | 3 | **24** | `home/fade.asm:48` |
+
+## The metric
+
+For each catalog entry, `delta = |port - truth| / truth`; the entry passes at
+`delta <= 0.05`. The headline number is the **exposure-weighted** pass rate,
+weighting each sequence by how often it occurs in ordinary play - a 30-frame
+error on every page of dialogue matters more than a 30-frame error in the Hall
+of Fame. Weights are in the tier column: T1 sequences recur constantly, T2 are
+frequent, T3 are set pieces seen once or twice per playthrough.
+
+## Tier 1 - constant exposure
+
+These recur every few seconds of play and dominate perceived pacing. Both
+sides are verified.
+
+### Overworld and transitions
+
+| Sequence | Hardware | Source | Port | Port source | Delta |
+| --- | --- | --- | --- | --- | --- |
+| Overworld loop iteration | 2 frames (two `DelayFrame`) | `home/overworld.asm:41-44` | 1 step | `src/core/Game.lua:174` | see note |
+| Warp / door: fade out | **32** | `home/overworld.asm:703` -> `GBFadeOutToBlack` | 32 | `src/render/Transition.lua` | **fixed** |
+| Warp / door: fade in | **0** (map is drawn under blacked palettes, no fade) | `home/overworld.asm:690-703` | 0 | `src/render/Transition.lua` | **fixed** |
+| Return to overworld after a battle | **10** hold, then `GBFadeInFromWhite` **24** | `home/overworld.asm:351-352`, `:22`, `:749-753` | 10 + 24 | `Transition.battleReturn` | **fixed** |
+| Special warp entry (fly / teleport / dungeon) | `Delay3` + `GBFadeInFromWhite` = **27** | `engine/overworld/player_animations.asm:5-7` | - | - | unmeasured |
+| Dungeon-warp arrival hold | **50** | `engine/overworld/player_animations.asm:43` | - | - | unmeasured |
+| Player step (walk) | 16 | 8 loop iterations x 2 frames | 16 | `src/world/Player.lua:14` | **ok** |
+| Turn in place | 2 | one extra loop pass | 2 | `src/world/Player.lua:18` | **ok** |
+
+Note on the overworld loop: `OverworldLoop` calls `DelayFrame` and then falls
+through to `OverworldLoopLessDelay`, which calls it again - so a full pass
+costs 2 frames, and input is sampled every other frame. The port steps logic
+and samples input every frame. This does not change walking speed (the 2-frame
+loop moves 2 px, giving the same 16 frames per tile) but it does halve input
+latency versus hardware. Flagged rather than "wrong": matching it exactly would
+make the port feel less responsive than the original does on a modern display,
+and it is the one place where a deliberate divergence is defensible.
+
+### Text
+
+The typewriter cadence itself is already correct - 1/3/5 frames per character
+from `TextSpeedOptionData`, implemented at `src/render/TextBox.lua:267`. The
+gaps around it are missing.
+
+| Sequence | Hardware | Source | Port | Port source | Delta |
+| --- | --- | --- | --- | --- | --- |
+| `<CONT>` line scroll (after the A press) | `ProtectedDelay3` 3 + 2x `ScrollTextUpOneLine` 5 = **13** | `home/text.asm:262-277`, `:283-307` | 13 | `src/render/TextBox.lua` | **fixed** |
+| `<PARA>` paragraph break | `ProtectedDelay3` 3 + clear + **20** = **23** | `home/text.asm:230-243` | 23 | `src/render/TextBox.lua` | **fixed** |
+| Page break (`PageChar`) | 3 + **20** = **23** | `home/text.asm:245-260` | 23 | `src/render/TextBox.lua` | **fixed** |
+| `TextCommand_PAUSE` | **30** | `home/text.asm:500` | - | - | unmeasured |
+| `TextCommand_DOTS` | **10** per dot | `home/text.asm:576` | - | - | unmeasured |
+
+The three ProtectedDelay3 frames are a *pre*-input hold: the arrow is already
+up and the button is ignored, because `ManualTextScroll` only starts watching
+the joypad after the delay returns. Mashing A through a long conversation
+therefore cannot go faster than 3 frames per line on hardware, and now cannot
+here either. `PromptText` (`home/text.asm:209-217`) has the same shape, so a
+finished page holds three frames before it can be dismissed too.
+
+**Battle text is a second, separate engine.** `BattleState` types its own
+messages rather than going through `src/render/TextBox.lua`, so none of the
+fixes above reached it and it had drifted further than the overworld box:
+
+| Sequence | Hardware | Source | Was | Now |
+| --- | --- | --- | --- | --- |
+| Per character | 1 glyph per `wOptions & $f` frames (1/3/5, default **3**) | `home/print_text.asm:4-45` | 2 glyphs **per frame**, option ignored | 3 |
+| Per character, A or B held | **1** frame | `print_text.asm:27-36` | 2 glyphs per frame | 1 |
+| `<CONT>` pre-input hold | **3** | `home/text.asm:263-267` | 0 | 3 |
+| `<CONT>` scroll after the press | **10** | `home/text.asm:280-305` | 0 | 10 |
+| Finished page, pre-input hold | **3** | `home/text.asm:213-217` | 0 | 3 |
+
+At the default text speed the battle typewriter was running **six times**
+hardware speed, which is most of why battle text read as a blur, and it
+ignored the OPTION text-speed setting entirely.
+
+`ScrollTextUpOneLine` is `ld b, 5` of `DelayFrame` (`home/text.asm:301-305`)
+and its own comment notes it is "always called twice in a row", so a CONT
+scroll blocks for 10 frames. The port's `scrollPx` slide at
+`src/render/TextBox.lua:305-307` is a cosmetic 8 px at 2 px/frame running in
+`draw()`, not on the logic step, and it does not gate the typewriter.
+
+### Menus
+
+| Sequence | Hardware | Source | Port | Port source | Delta |
+| --- | --- | --- | --- | --- | --- |
+| Yes/no answer (either option) | **15** | `engine/menus/text_box.asm:322-323`, `:333-334` | 15 | `src/ui/ChoiceBox.lua` | **fixed** |
+| List menu open (bag, PC, party-as-list) | **10** | `home/list_menu.asm:55-56` | 0 | `src/ui/ListMenu.lua` | **-100%, open** |
+| List menu redraw per input | `Delay3` = **3** | `home/list_menu.asm:64` | 0 | - | **-100%, open** |
+| Field move from the party menu | `Delay3` = **3** | `engine/menus/start_sub_menus.asm:4,27,175-203` | 7 (white flash) | `src/render/Transition.lua:8` | see note |
+| Teleport from the party menu | **60** + `Delay3` | `engine/menus/start_sub_menus.asm:224-225` | - | - | unmeasured |
+
+The port's 7-frame `white_flash` models `GBPalWhiteOutWithDelay3` plus the
+screen-tile restore, which is a defensible reading of the same sequence; it is
+listed here to be reconciled against the exact path rather than treated as a
+bug.
+
+### Battle entry
+
+The wipe into a battle and the silhouette slide behind it. Numbers here come
+from **pokered-c** (`C:\Users\Anthony\pokered`), whose `battle_transition.c`
+derives each wipe from `battle_transitions.asm` and then corrects it against a
+live side-by-side with the ROM. Where that project's measured value and a
+naive reading of the asm disagree, the measured value wins - see the inward
+spiral below.
+
+| Sequence | Hardware | Was | Now |
+| --- | --- | --- | --- |
+| DoubleCircle wipe (wild, weak) | 10 x 3 = **30** | 40 | 30 |
+| Circle wipe (wild, strong) | 20 x 3 = **60** | 40 | 60 |
+| Spiral outward (trainer, strong) | 360 fills / 3 per frame = **120** | 40 | 120 |
+| Spiral inward (trainer, weak) | 7 tiles per `Delay3` = **~150** | 40 | 156 |
+| HStripes (dungeon wild, weak) | 20 x 3 = **60** | 24 | 60 |
+| VStripes (dungeon wild, strong) | 18 x 3 = **54** | 24 | 54 |
+| Shrink (dungeon trainer, weak) | 9 x 6 = **54** | 24 | 54 |
+| Split (dungeon trainer, strong) | 9 x 6 = **54** | 24 | 54 |
+| Flash before the circle wipes | 12 x 2 x 3 = **72** | 72 | 72 |
+| Black hold before the battle draws | not stated by pokered; ~30 floor, calibrated **60** | 30 | 60 |
+| Silhouette slide in | 144 px at 2 px/frame = **72** | 40 (160 px at 4 px/frame) | 72 |
+| Trainer intro, before balls + text | `WaitForSoundToFinish` + `DelayFrames 20` | 0 | sfx wait + 20 |
+
+The trainer intro's sound is `SFX_Silph_Scope`, extracted here as
+`Trainer_Appeared` (`tools/rom_manifest.json` `audio.sfxHeaders`, bank 8 /
+`$42bb`). It was being extracted and never played by anything. It now plays
+into a clear window: `PrintBeginningBattleText .trainerBattle` does
+`PlaySound` then `WaitForSoundToFinish`, which **blocks**, and only then
+`DelayFrames 20` before `DrawAllPokeballs` and the text. `BattleState`'s
+message queue grew a `waitSound` row for that, since `WaitForSoundToFinish`
+waits on the sound actually stopping rather than on a fixed frame count.
+
+**Scripted battles were skipping the transition entirely.** `BattleTransition`
+runs from `DoBattleTransitionAndInitBattleVariables`, which both
+`InitBattleCommon` (`core.asm:6680`, trainers) and `InitWildBattle` (`:6699`)
+call unconditionally - every battle on hardware enters through a wipe. In the
+port only `OverworldState:pushBattle` built one, and `Commands.start_battle`
+pushed the `BattleState` straight onto the stack. The trainer-*sight* path
+went through `pushBattle`, but every **script-driven** battle did not: gym
+leaders, the rival, Giovanni, and every scripted wild encounter cut straight
+to the battle screen with no transition at all. The catch tutorial
+(`old_man_demo`) had the same gap; `InitWildBattle` has no
+`BATTLE_TYPE_OLD_MAN` special case, so it gets a wipe too.
+
+**Beyond 160x144.** Both halves of the transition used to stop at the classic
+letterbox. The flash filled the 160x144 UI canvas, and the wipe handed the
+surrounding window a generic centre-out square cascade
+(`Renderer:drawBattleCascade`) regardless of which of the eight styles was
+running - so at any zoom a spiral read as "a spiral in a box, with something
+else happening around it".
+
+- The flash is a palette write (`rBGP`), and a palette register tints every
+  pixel the LCD shows; there is no "outside the screen" for it to miss. It is
+  now published to the renderer as a screen-space veil and painted over the
+  finished composite, so it covers the whole surface at any zoom.
+- The spiral and circle walks are now generated for whatever grid the window
+  works out to (`BattleTransition.gridOrder`), and the area outside the
+  letterbox is filled in that order instead of the square cascade. The
+  authentic 20x18 builders still own the letterbox itself, overrun and all,
+  so nothing changes at 1x. The generic builders are deliberately *not* the
+  ROM's walk - out there the hardware has no behaviour to be faithful to,
+  only a shape to continue.
+- `shrink`, `split` and the two stripe styles are plain geometry rather than
+  a tile order, so they keep the cascade for now. Extending them is
+  rectangles, not a walk, and has not been done.
+
+Note that the **flash is wild-only**: `BattleTransition_FlashScreen` is called
+from `BattleTransition_Circle` (`:585`) and `BattleTransition_DoubleCircle`
+(`:628`) and nowhere else. A trainer battle's transition is the spiral -
+inward against a weaker foe, outward against a stronger one
+(`wBattleTransitionSpiralDirection`, `:119-126`) - with no flash in front of
+it. The port's `flash` mapping was already correct; the transition simply
+never ran for those battles.
+
+Two of these deserve their reasoning recorded:
+
+**The inward spiral** writes one tile per iteration and calls
+`BattleTransition_TransferDelay3` every seventh tile. That helper is not a
+one-frame transfer - it is `ld a,1 / ldh [hAutoBGTransferEnabled] / call
+Delay3 / xor a / ldh [...]` (`battle_transitions.asm:619`), so the cadence is
+7 tiles per **three** frames. Reading it as one frame runs the whole wipe 3x
+too fast, ~46 frames against the ROM's ~150. pokered-c hit that exact bug and
+caught it on a live comparison.
+
+**The black hold** is not a number pokered states anywhere; it is incidental
+load cost that a modern port does not pay. The derivable floor is ~13 frames
+(`LoadHpBarAndStatusTilePatterns` 4, `LoadHudTilePatterns` 2, `ClearScreen`'s
+`Delay3` 3, the `DisableLCD` LY wait 1, `Delay3` after `EnableLCD` 3), but the
+two sprite decompressors (`UncompressSpriteFromDE` for the 7x7 front pic and
+`LoadPlayerBackPic`'s uncompress + `ScaleSpriteByTwo`) are bit-level RLE/delta
+decoders that cannot be cycle-counted from the asm at all. So the derivation
+bottoms out around 25-30 with an unbounded remainder. pokered-c set 60 by ear
+against the real ROM and marked it ~95% right rather than frame-matched. The
+credible range is 30-60; it should not be "corrected" down toward the floor on
+the strength of the derivation, because the omitted decompressors are exactly
+the unbounded part. Pinning it exactly wants a frame-by-frame capture.
+
+### Battle turns
+
+| Sequence | Hardware | Source | Port | Port source | Delta |
+| --- | --- | --- | --- | --- | --- |
+| Player HP bar drain of D HP over P pixels | **D + 2P + 6** | `engine/gfx/hp_bar.asm:81-135`, `:140-159`, `:234` | D + 2P + 6 | `src/battle/BattleState.lua` `stepHPDrain` | **fixed** |
+| Enemy HP bar drain over P pixels | **2P + 5** (no per-HP frame) | same, gated at `:207-209` | 2P + 5 | same | **fixed** |
+| Status move / missed move beat | **30** | `engine/battle/core.asm:3145,3158,3185-3186`; enemy `:5588` | 30 | `EffectRegistry` `missBeat`, `BattleState:performMove` | **fixed** |
+| Applying anim type 1, vertical shake b=8 | **48** | `animations.asm:500-503` | 48 | `BattleState:applyHitFx` | ok |
+| Applying anim type 2, fast horizontal b=8 | **72** | `animations.asm:505-508` | 72 | same | ok |
+| Applying anim type 3, slow horizontal 6,2 | **48** | `animations.asm:510-512,526-549` | 48 | same | ok |
+| Applying anim type 4, `AnimationBlinkMon` | **60** | `animations.asm:514-516`, `:1360-1376` | 60 | same | **fixed** |
+| Applying anim type 5, fast horizontal b=2 | **18** | `animations.asm:518-521` | 18 | same | ok |
+| Applying anim type 6, slow horizontal 3,2 | **24** | `animations.asm:523-525` | 24 | same | ok |
+| Faint slide-down | **14** (`PIC_HEIGHT` x `DelayFrames 2`) | `engine/battle/core.asm:1186-1222` | 14 | `BattleState:onFaint` | **fixed** |
+| Before every move animation | `Delay3` = **3** | `engine/battle/core.asm:6635-6640` | 3 | `BattleState:updateQueue` | **fixed** |
+| Battle start, after enemy send-out | **40** | `engine/battle/core.asm:152-156` | 40 | `BattleState:enter` | **fixed** |
+| Poison / burn / leech-seed tick | **20** | `engine/battle/core.asm:529-530` | 20 | `src/battle/BattleState.lua:1817` | **ok** |
+| Switch player mon | **50** | `engine/battle/core.asm:2421-2422` | 50 | `src/battle/BattleState.lua:1666-1668` | **ok** |
+| Post-hit hold (crit text or not) | **20** | `engine/battle/core.asm:3798-3814` | 20 | `EffectRegistry.runDamaging` | **fixed** |
+| Fainted mon slide-down | **2** per row | `engine/battle/core.asm:1216-1217` | - | - | unmeasured |
+| Trainer pic slide off | **2** per column | `engine/battle/core.asm:1267-1268` | - | - | unmeasured |
+| Trainer battle victory | **40** | `engine/battle/core.asm:940-941` | - | - | unmeasured |
+| Player blackout | **40** | `engine/battle/core.asm:1143-1144` | - | - | unmeasured |
+| No moves left (Struggle) | **60** | `engine/battle/core.asm:2753-2754` | - | - | unmeasured |
+| Send-out animation | `Delay3` + **4** + **5** | `engine/battle/core.asm:6814-6830` | - | - | unmeasured |
+
+The HP bar was the single largest battle divergence. `UpdateHPBar` steps **one
+HP point per loop iteration**; each iteration pays 1 frame in
+`UpdateHPBar_PrintHPNumber` whenever `wHPBarType != 0` - the player's own HUD
+and the party menu, but not the enemy HUD - plus 2 frames for each pixel the
+bar actually moves. The tail (`.animateHPBarDone`, `:132-135`) prints the
+number once more, animates one last pixel and falls into `Delay3`, so it costs
+6 frames player-side and 5 enemy-side.
+
+A 150 HP mon losing everything therefore costs 150 + 96 + 6 = **252 frames
+(4.2 s)** on the player's HUD, against 96 + 5 = 101 on the enemy's. The port
+used a flat `maxHP/96` - the enemy-side rate applied to both sides - and ran
+that same drain in 96 frames (1.6 s).
+
+## Tier 2 - frequent
+
+Status-effect failures (`engine/battle/effects.asm:161,1162,1205`) hold **50**
+frames each. `SwitchAndTeleportEffect` uses 50 and 20
+(`:834-901`). Evolution holds **50** then **40**
+(`engine/pokemon/evos_moves.asm:123,155`). The healing machine
+(`engine/overworld/healing_machine.asm`), item effects
+(`engine/items/item_effects.asm`, 259 frames across 8 sites), and the fishing
+animation (**10** then **100**, `engine/overworld/player_animations.asm:380,399`)
+are all in this tier.
+
+## Tier 3 - set pieces
+
+Highest total budgets in the scan, all seen rarely:
+`engine/movie/hall_of_fame.asm` (529 frames / 7 sites),
+`engine/link/cable_club.asm` (507 / 12), `engine/movie/credits.asm` (502 / 7),
+`engine/movie/trade.asm` (494 / 19), `engine/movie/intro.asm` (317 / 7),
+`engine/menus/main_menu.asm` (271 / 15), `engine/menus/save.asm` (250 / 3),
+`engine/battle/end_of_battle.asm` (200 / 1, the link-battle win/lose string).
+Several of these already have faithful implementations - see
+`src/ui/IntroMovie.lua`, `src/ui/Credits.lua`, `src/ui/HallOfFame.lua`, whose
+constants cite their asm sources directly.
+
+## Status
+
+Closed, and locked by `tests/engine/timing_parity.lua`:
+
+1. **Text page and CONT breaks** - were 0 frames where hardware spends 13-23,
+   on every page of every dialogue in the game. Now exact, including the
+   three-frame pre-input hold that swallows a mashed A.
+2. **Player HP bar drain** - was ~2.5x too fast on a typical mon. Now steps
+   one HP point at a time at the hardware rate, with the enemy HUD correctly
+   cheaper than the player's.
+3. **Warp fade** - was a symmetric 12/12; now 32 out and no fade in, which is
+   both the right duration and the right shape.
+4. **Yes/no answer** - was 0 frames where hardware spends 15, with the cursor
+   snapping to NO on B for the duration as `.choseSecondMenuItem` does.
+
+5. **Battle entry** - every wipe ran at a flat 40/24 against budgets of 30-156,
+   the silhouette slide was 40 frames against 72, the black hold was half
+   what pokered-c calibrated, and the trainer intro's 20-frame gap before the
+   balls and text was missing entirely. This was the single most compressed
+   stretch in the game.
+
+6. **Battle turns** - the type-4 blink ran at 20 frames against 60. That is
+   the applying animation for every plain damaging move the player uses, so
+   it was the single most-repeated timing error in the game. The 30-frame
+   beat that hardware spends on every status move and every miss was missing
+   entirely. The faint slide, unusually, ran *slower* than hardware (30
+   against 14).
+
+Two things worth recording about that last batch, because both contradict a
+plausible reading:
+
+- **`PrintCriticalOHKOText`'s 20-frame hold is not conditional.** The
+  "no critical hit" early-out at `core.asm:3799` jumps to `.done`, and
+  `.done` *is* the `ld c, 20 / jp DelayFrames`. Every landed hit pays it,
+  which is where the beat before "It's super effective!" comes from.
+- **`StartBattle`'s 40-frame hold is not conditional either.** The `call nz`
+  at `core.asm:154` gates only `EnemySendOutFirstMon`; the `DelayFrames 40`
+  under it runs for wild battles too, and it lands *between* the enemy's
+  send-out and `.playerSendOutFirstMon` (`:166`) rather than at the end of
+  the intro.
+
+Trainer victory (24-frame scroll-in + 40-frame hold) and the ball shake
+(`SFX_TINK` + `DelayFrames 40` per rock) were already correct -
+`BattleState.lua`'s `wait = 64` and `AnimPlayer.lua`'s `emit(40)`. Note that
+pokered-c's `BUI_TRAINER_VICTORY_SLIDE` comment calls the scroll-in 14
+frames; `_ScrollTrainerPicAfterBattle` is 6 loop passes of `DelayFrames 4`,
+so 24 is right and this port already had it.
+
+**Leaving a battle was a cut, not a fade.** `EnterMap` checks
+`BIT_BATTLE_OVER_OR_BLACKOUT` and calls `MapEntryAfterBattle`
+(`home/overworld.asm:22`), which is `GBFadeInFromWhite` - so the map fades up
+from white over 24 frames, behind the 10-frame hold at `:351-352`. The port
+popped the battle and the overworld was simply there. `Transition.battleReturn`
+supplies both halves, and steps the veil in three palette stages of 8 frames
+rather than tweening it, because `GBFadeIncCommon` writes a palette and holds
+it with `ld c, 8 / call DelayFrames` (`home/fade.asm:30-41`) three times over.
+
+It is wrapped around `battle.onFinish` in `OverworldState:pushBattle` - the
+one funnel every battle goes through - rather than living in `afterBattle`.
+That placement matters: a script-driven **win** defers `afterBattle` into
+`ctx.afterScript` so an evolution screen cannot be buried under the trainer's
+follow-up text (`Commands.start_battle`), and a fade inside `afterBattle`
+inherited that deferral. On a rival battle it fired after the post-battle
+dialogue *and* the rival's walk-off, rather than when the battle ended.
+
+The rest of `onFinish` runs as the fade's `onDone`, which is also the hardware
+order: `MapEntryAfterBattle` fades the map back in and only then does the map
+script run. The overworld is frozen meanwhile - `StateStack` updates the top
+state only - so nothing moves under the white.
+
+Hardware skips the fade on a dark map (`wMapPalOffset` nonzero takes the
+`LoadGBPal` branch at `:754`). This port has no `wMapPalOffset` equivalent -
+no map needs FLASH to be lit - so that branch is unreachable here;
+`battleReturn` accepts `opts.instant` for it if that ever changes.
+
+Still open, hardware number confirmed but not yet wired:
+
+- List menu open (10) and per-input redraw (`Delay3`).
+- Every battle-table row marked "unmeasured" above - the status/miss beat (30)
+  is the highest-exposure of them, since it is paid on every status move and
+  every miss.
+
+Entries marked "unmeasured" have confirmed hardware numbers but the port side
+has not been traced; they are remaining work, not known-good.

docs/updater.md

@@ -124,3 +124,8 @@ bundled game, in that case.
   `love.filesystem.isFused()` is false, and a working tree's `engine` is the
   `"0.0.0-dev"` placeholder that always reports up to date, so a source
   checkout is always "the game" itself; updating it means pulling the repo.
+- **Nintendo Switch does not use this LÖVE self-updater.** On NX,
+  `Platform.networkValidated()` is `false`, so `Boot.run` / `Check` never
+  download `.love` payloads. In-console OTA uses the **native OTA launcher**
+  (DEVKITPRO), documented in [switch-install.md](switch-install.md). Wire
+  format: `src/update/SwitchOta.lua`. Manual zip install remains the fallback.

main.lua

@@ -10,8 +10,41 @@
 
 local editorMode = os.getenv("POKEPORT_EDITOR") == "1" or POKEPORT_EDITOR_MODE == true
 
+local SwitchDiagnostics = require("src.debug.SwitchDiagnostics")
+local LaunchOptions = require("src.core.LaunchOptions")
+local NxDisplay = require("src.core.NxDisplay")
+
+-- Lua errors: persist a redacted trace in the save dir and surface a hint.
+do
+  local defaultErrorHandler = love.errorhandler
+  function love.errorhandler(msg)
+    local hint = SwitchDiagnostics.logLuaError(msg)
+    if hint and type(msg) == "string" then
+      msg = msg .. "\n\n" .. hint
+    end
+    if defaultErrorHandler then
+      return defaultErrorHandler(msg)
+    end
+  end
+end
+
 local Game, EditorApp, Importer, TouchEditor
 
+-- #887: quit-to-launcher state, shared by love.load and love.quit (both need
+-- it, so it is declared here rather than next to love.quit).
+--   * launchedIntoGame -- a --game / POKEPORT_GAME shortcut booted this
+--     session straight into a game, so there is no launcher behind it and a
+--     window close must exit.  Restarting instead re-read the same shortcut
+--     and came right back into the game, and the next close did it again:
+--     the app could not be closed at all (macOS feels this worst, where the
+--     red X, Cmd+Q and the Dock's Quit are all the same quit event).
+--   * RELAUNCH_MARKER -- written in the save dir just before the #785
+--     restart, so the fresh boot ignores any boot-straight-into-a-game
+--     option exactly once and keeps #785's promise of landing in the
+--     launcher, whatever put the game on screen this time.
+local launchedIntoGame = false
+local RELAUNCH_MARKER = "relaunch_to_launcher.txt"
+
 local autopilot -- optional scripted-input dev tool (tests/autopilot.lua)
 local driverCo  -- optional frame-driver (POKEPORT_DRIVER=file.lua): a
                 -- coroutine that receives `Game` and yields once per
@@ -103,6 +136,11 @@ local function openEditor(version, slotId)
   require("src.import.CacheFs").mountVersion(version)
   editorVersion = version
   editorHost = Importer
+  -- Drop launcher pad/FlexLove so the save editor owns input (NX shim +
+  -- virtual cursor + system hand cursor). Desktop park is a light no-op.
+  if Importer and Importer.prepareOverlayHandoff then
+    Importer:prepareOverlayHandoff()
+  end
   Importer = nil
   editorMode = true
   resizeForEditor()
@@ -129,6 +167,9 @@ function closeEditor()
   restoreWindow()
   Importer = editorHost
   editorHost = nil
+  if Importer and Importer.resumeAfterOverlay then
+    Importer:resumeAfterOverlay()
+  end
   if Importer and version and Importer.savesChanged then
     Importer:savesChanged(version)
   end
@@ -142,6 +183,9 @@ local closeTouchControlsEditor  -- forward declaration
 
 local function openTouchControlsEditor()
   touchEditorHost = Importer
+  if Importer and Importer.prepareOverlayHandoff then
+    Importer:prepareOverlayHandoff()
+  end
   Importer = nil
   TouchEditor = require("src.ui.TouchControlsEditor")
   TouchEditor.load({ onClose = function() closeTouchControlsEditor() end })
@@ -152,6 +196,9 @@ function closeTouchControlsEditor()
   TouchEditor = nil
   Importer = touchEditorHost
   touchEditorHost = nil
+  if Importer and Importer.resumeAfterOverlay then
+    Importer:resumeAfterOverlay()
+  end
 end
 
 local function bootGame(version)
@@ -161,7 +208,16 @@ local function bootGame(version)
   -- data, so data/generated + assets/generated resolve to that version's files.
   local GameVersion = require("src.core.GameVersion")
   GameVersion.set(version or os.getenv("POKEPORT_VERSION") or "red")
-  require("src.import.CacheFs").mountVersion(GameVersion.get())
+  local CacheFs = require("src.import.CacheFs")
+  -- Keep CacheFs.prefix aligned for any CacheFs.read fallback during Data:load
+  -- (Blue/Yellow caches live under blue/ / yellow/).
+  CacheFs.prefix = GameVersion.cachePrefix()
+  CacheFs.mountVersion(GameVersion.get())
+  -- NX: always write nx-asset-probe.log so Yellow/Blue art failures are
+  -- diagnosable from the SD without enabling switch-debug.txt.
+  pcall(function()
+    require("src.debug.SwitchDiagnostics").probeAssets(GameVersion.get())
+  end)
   if love.window and love.window.setTitle then
     local Version = require("src.core.Version")
     love.window.setTitle(Version.title(
@@ -184,6 +240,18 @@ local function bootGame(version)
 end
 
 function love.load(args)
+  -- Before anything can shell out (update check, mod index, ROM picker),
+  -- claim one hidden console on Windows so those children inherit it instead
+  -- of each flashing their own cmd.exe window (#606).  No-op elsewhere.
+  require("src.core.HostShell").hideHostConsole()
+
+  -- NX fused mounts are unreliable for the blue|yellow cache overlay: wrap
+  -- the love loaders once so every generated-asset read falls back to the
+  -- versioned save-dir copy.  Never installed on desktop/Android/iOS.
+  if require("src.core.Platform").isNX() then
+    require("src.core.NxAssetOverlay").install()
+  end
+
   -- Self-updater boot shell: a fused build may mount and chainload a newer
   -- downloaded payload here.  True means it took over, so we must stop.  A
   -- dev / source checkout no-ops (see src/update/Boot.lua).
@@ -203,6 +271,16 @@ function love.load(args)
     end
   end
   love.graphics.setDefaultFilter("nearest", "nearest")
+  -- NX: handheld 720p / docked 1080p. Runs for every boot path (launcher,
+  -- editor, scripted); no-op on desktop/mobile.
+  NxDisplay.sync()
+
+  -- Apply the persisted Android orientation lock (#592) before the launcher
+  -- shows: SDL created the window with no orientation hint, so without this
+  -- the launcher would rotate freely until Game:applyOptions runs at boot.
+  -- No-op on desktop / iOS / when options.lua does not exist yet.
+  require("src.core.Orientation").applyOptions(
+    require("src.core.SaveData").loadOptions())
 
   -- Standalone editor.  A bare `--editor` run has no launcher behind it, so
   -- Close quits; --save points it at a specific file, otherwise it opens the
@@ -251,6 +329,47 @@ function love.load(args)
     return
   end
 
+  -- The launcher draws before any game boots, so the mod loader has not run
+  -- and Strings has no catalog.  Routing the launcher's text through Strings
+  -- (#767) only pays off if something fills that catalog this early, and no
+  -- restart could: the ordering is the same on every launch.  Read the
+  -- enabled mods' string catalogs -- data only, no entry chunk -- so a
+  -- translation reaches the launcher too.  Game:load replaces this with the
+  -- real merged catalog once a version boots.
+  do
+    local preload = require("src.mods.LauncherMods").translationStrings()
+    if preload then require("src.core.Strings").load({ strings = preload }) end
+  end
+
+  -- LAUNCH OPTIONS: skip the launcher and boot a game directly.
+  --   --game red|blue|yellow  (or POKEPORT_GAME / POKEPORT_LAUNCH)
+  --   --slot <id>             optional; picks the save slot to load
+  --   --launcher              force the launcher even if a game is set
+  -- This is what a desktop shortcut, a Steam entry, or a frontend like
+  -- EmulationStation needs: one click into the game the player wants, with no
+  -- menu in between.  A game that is not imported falls through to the
+  -- launcher on its tab rather than booting into nothing.
+  -- A window close that restarted us into the launcher (#785) leaves the
+  -- marker behind: consume it and stay on the launcher, or the shortcut below
+  -- would boot the same game again and that close would restart again,
+  -- forever (#887).  Consumed on read, so the very next launch is normal.
+  local relaunched = love.filesystem.getInfo(RELAUNCH_MARKER) ~= nil
+  if relaunched then pcall(love.filesystem.remove, RELAUNCH_MARKER) end
+
+  local launchGame, launchSlot = LaunchOptions.resolve(arg)
+  if launchGame and not relaunched and not LaunchOptions.forceLauncher(arg) then
+    if RomImporter.isReady(launchGame) then
+      if launchSlot then LaunchOptions.selectSlot(launchGame, launchSlot) end
+      -- No launcher behind this session: love.quit must exit, not restart.
+      launchedIntoGame = true
+      bootGame(launchGame)
+      return
+    end
+    -- Not importable yet: open the launcher already showing that game, so the
+    -- shortcut still lands the player where they meant to go.
+    LaunchOptions.pendingTab = launchGame
+  end
+
   -- Interactive: the launcher always runs.  Red, Blue, and Yellow are each
   -- live: a column shows Play when that game's ROM is already imported, or
   -- Choose ROM / drag-drop when it is not.  Any dropped .gb is routed by its
@@ -268,6 +387,9 @@ function love.load(args)
 end
 
 function love.update(dt)
+  SwitchDiagnostics.maybeFlush(false)
+  -- NX only (no-op elsewhere): follow dock/undock without waiting for SDL.
+  NxDisplay.sync()
   if editorMode then return EditorApp.update(dt) end
   if TouchEditor then return TouchEditor.update(dt) end
   if Importer then return Importer:update(dt) end
@@ -342,48 +464,140 @@ function love.keyreleased(key)
 end
 
 function love.gamepadpressed(joystick, button)
-  if editorMode or TouchEditor then return end
+  SwitchDiagnostics.onJoystickEvent("gamepadpressed", joystick, button)
+  if editorMode then
+    if EditorApp and EditorApp.gamepadpressed then
+      return EditorApp.gamepadpressed(joystick, button)
+    end
+    return
+  end
+  if TouchEditor then
+    if TouchEditor.gamepadpressed then
+      return TouchEditor.gamepadpressed(joystick, button)
+    end
+    return
+  end
   if Importer then return Importer:gamepadpressed(joystick, button) end
   Game:gamepadpressed(joystick, button)
 end
 
 function love.gamepadreleased(joystick, button)
-  if editorMode or TouchEditor then return end
+  SwitchDiagnostics.onJoystickEvent("gamepadreleased", joystick, button)
+  if editorMode then
+    if EditorApp and EditorApp.gamepadreleased then
+      return EditorApp.gamepadreleased(joystick, button)
+    end
+    return
+  end
+  if TouchEditor then
+    if TouchEditor.gamepadreleased then
+      return TouchEditor.gamepadreleased(joystick, button)
+    end
+    return
+  end
   if Importer then return Importer:gamepadreleased(joystick, button) end
   Game:gamepadreleased(joystick, button)
 end
 
 function love.gamepadaxis(joystick, axis, value)
-  if editorMode or TouchEditor then return end
+  SwitchDiagnostics.onJoystickEvent("gamepadaxis", joystick, axis, { value = value })
+  if editorMode then
+    if EditorApp and EditorApp.gamepadaxis then
+      return EditorApp.gamepadaxis(joystick, axis, value)
+    end
+    return
+  end
+  if TouchEditor then
+    if TouchEditor.gamepadaxis then
+      return TouchEditor.gamepadaxis(joystick, axis, value)
+    end
+    return
+  end
   if Importer then return Importer:gamepadaxis(joystick, axis, value) end
   Game:gamepadaxis(joystick, axis, value)
 end
 
 function love.joystickpressed(joystick, button)
-  if editorMode or TouchEditor then return end
+  SwitchDiagnostics.onJoystickEvent("joystickpressed", joystick, button)
+  if editorMode then
+    if EditorApp and EditorApp.joystickpressed then
+      return EditorApp.joystickpressed(joystick, button)
+    end
+    return
+  end
+  if TouchEditor then
+    if TouchEditor.joystickpressed then
+      return TouchEditor.joystickpressed(joystick, button)
+    end
+    return
+  end
   if Importer then return Importer:joystickpressed(joystick, button) end
   Game:joystickpressed(joystick, button)
 end
 
 function love.joystickreleased(joystick, button)
-  if editorMode or TouchEditor then return end
+  SwitchDiagnostics.onJoystickEvent("joystickreleased", joystick, button)
+  if editorMode then
+    if EditorApp and EditorApp.joystickreleased then
+      return EditorApp.joystickreleased(joystick, button)
+    end
+    return
+  end
+  if TouchEditor then
+    if TouchEditor.joystickreleased then
+      return TouchEditor.joystickreleased(joystick, button)
+    end
+    return
+  end
   if Importer then return Importer:joystickreleased(joystick, button) end
   Game:joystickreleased(joystick, button)
 end
 
 function love.joystickaxis(joystick, axis, value)
-  if editorMode or TouchEditor then return end
+  SwitchDiagnostics.onJoystickEvent("joystickaxis", joystick, axis, { value = value })
+  if editorMode then
+    if EditorApp and EditorApp.joystickaxis then
+      return EditorApp.joystickaxis(joystick, axis, value)
+    end
+    return
+  end
+  if TouchEditor then
+    if TouchEditor.joystickaxis then
+      return TouchEditor.joystickaxis(joystick, axis, value)
+    end
+    return
+  end
   if Importer then return Importer:joystickaxis(joystick, axis, value) end
   Game:joystickaxis(joystick, axis, value)
 end
 
 function love.joystickhat(joystick, hat, direction)
-  if editorMode or TouchEditor then return end
+  SwitchDiagnostics.onJoystickEvent("joystickhat", joystick, hat, { direction = direction })
+  if editorMode then
+    if EditorApp and EditorApp.joystickhat then
+      return EditorApp.joystickhat(joystick, hat, direction)
+    end
+    return
+  end
+  if TouchEditor then
+    if TouchEditor.joystickhat then
+      return TouchEditor.joystickhat(joystick, hat, direction)
+    end
+    return
+  end
   if Importer then return Importer:joystickhat(joystick, hat, direction) end
   Game:joystickhat(joystick, hat, direction)
 end
 
+function love.joystickadded(joystick)
+  SwitchDiagnostics.onJoystickEvent("joystickadded", joystick)
+  if editorMode or TouchEditor then return end
+  if Importer then return end
+  Game:joystickadded(joystick)
+end
+
 function love.joystickremoved(joystick)
+  SwitchDiagnostics.onJoystickEvent("joystickremoved", joystick)
   if editorMode or TouchEditor then return end
   if Importer then return end
   Game:joystickremoved(joystick)
@@ -395,6 +609,7 @@ end
 function love.focus(f)
   if editorMode or TouchEditor then return end
   if Importer then
+    require("src.core.Input"):reset()
     if Importer.focus then Importer:focus(f) end
     return
   end
@@ -404,12 +619,29 @@ end
 -- v is true when the window becomes visible again, false on minimize.
 function love.visible(v)
   if editorMode or TouchEditor then return end
-  if Importer then return end
+  if Importer then
+    require("src.core.Input"):reset()
+    return
+  end
   Game:visible(v)
 end
 
+function love.lowmemory()
+  if editorMode or TouchEditor or Importer then return end
+  if Game then Game:onResume() end
+end
+
 function love.touchpressed(id, x, y, dx, dy, pressure)
-  if editorMode then return end
+  if editorMode then
+    -- iOS synthesizes mousepressed for the primary touch; forwarding here
+    -- would double-fire.  Android / NX need the explicit touch → click path
+    -- (love-nx does not synthesize mouse for the editor the way desktop does).
+    if love.system.getOS() == "iOS" then return end
+    if EditorApp and EditorApp.mousepressed then
+      return EditorApp.mousepressed(x, y, 1)
+    end
+    return
+  end
   if TouchEditor then
     -- iOS synthesizes mousepressed for the primary touch (same as the
     -- launcher); Android drives the editor through love.touch directly.
@@ -417,18 +649,12 @@ function love.touchpressed(id, x, y, dx, dy, pressure)
     return TouchEditor.touchpressed(id, x, y)
   end
   if Importer then
-    -- iOS: LÖVE already synthesizes a mousepressed for the primary touch,
-    -- and love.mousepressed below forwards that to the Importer, so
-    -- forwarding here too fires every launcher button twice per tap.  The
-    -- resulting double-present was fatal for the document picker: the
-    -- second sheet stole the first one's weakly-held delegate, so picking
-    -- a file silently did nothing.  Android keeps the forward for upstream
-    -- parity (its SAF picker is a separate activity and tolerates the
-    -- re-launch).
-    if love.system.getOS() == "iOS" then return end
-    return Importer:mousepressed(x, y, 1)
+    -- Both mobiles: FlexLove scroll needs the real touch stream. Clicks are
+    -- polled inside the view; the istouch filter on mousepressed still drops
+    -- Android's synthesized mouse twin so Import cannot double-fire (#553).
+    return Importer:touchpressed(id, x, y, dx, dy, pressure)
   end
-  Game:touchpressed(id, x, y)
+  Game:touchpressed(id, x, y, dx, dy, pressure)
 end
 
 function love.touchmoved(id, x, y, dx, dy, pressure)
@@ -437,8 +663,10 @@ 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 Importer then return end
-  Game:touchmoved(id, x, y)
+  if Importer then
+    return Importer:touchmoved(id, x, y, dx, dy, pressure)
+  end
+  Game:touchmoved(id, x, y, dx, dy, pressure)
 end
 
 function love.touchreleased(id, x, y, dx, dy, pressure)
@@ -447,8 +675,10 @@ 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 Importer then return end
-  Game:touchreleased(id, x, y)
+  if Importer then
+    return Importer:touchreleased(id, x, y, dx, dy, pressure)
+  end
+  Game:touchreleased(id, x, y, dx, dy, pressure)
 end
 
 function love.wheelmoved(x, y)
@@ -461,7 +691,33 @@ function love.wheelmoved(x, y)
   Game:wheelmoved(x, y)
 end
 
+-- #781: Linux X11 multi-monitor with the primary display away from desktop
+-- (0,0): SDL's polled mouse state can come back in desktop-virtual
+-- coordinates while the event stream stays window-relative, which strands
+-- every polled consumer (launcher Kit rising-edge clicks, the pad-cursor
+-- motion yield, PadCursor) on coordinates no hit test can match.  Sanitize
+-- the poll once here: remember the last window-relative event coordinates
+-- and substitute them whenever the polled value falls outside the window.
+-- Linux only -- macOS / Windows / mobile keep the stock function, and the
+-- NX launcher shim still composes because it captures whatever
+-- love.mouse.getPosition is at bridge time (_ensureNxPointerBridge).
+local eventMouseX, eventMouseY
+if love.system and love.system.getOS() == "Linux"
+    and love.mouse and love.mouse.getPosition then
+  local polledGetPosition = love.mouse.getPosition
+  love.mouse.getPosition = function()
+    local x, y = polledGetPosition()
+    local w, h = love.graphics.getDimensions()
+    if x < 0 or y < 0 or x > w or y > h then
+      if eventMouseX then return eventMouseX, eventMouseY end
+      return math.max(0, math.min(x, w)), math.max(0, math.min(y, h))
+    end
+    return x, y
+  end
+end
+
 function love.mousepressed(x, y, button, istouch)
+  if not istouch then eventMouseX, eventMouseY = x, y end
   if TouchEditor then
     -- Android primary touch already arrived via love.touchpressed; a second
     -- mouse path would double-fire Done / begin a second drag.
@@ -469,32 +725,35 @@ function love.mousepressed(x, y, button, istouch)
     return TouchEditor.mousepressed(x, y, button)
   end
   if Importer then
-    -- The same double-fire TouchEditor guards against, which the launcher was
-    -- missing: love.touchpressed above forwards the primary touch to the
-    -- Importer on Android, and LÖVE ALSO synthesizes a mouse press for that
-    -- same touch, so one tap ran every launcher button twice.  On Import that
-    -- meant two choose() calls and two stacked SAF picker activities: the
-    -- player picked their ROM, the top picker closed, and the second was still
-    -- underneath asking for it again, which is the "import the file twice"
-    -- in #553.  Filtering on istouch keeps a real mouse (DeX, a Chromebook, a
-    -- USB mouse) working, which an Android-wide return would have broken.
-    --
-    -- ANDROID ONLY, and the OS test is load bearing: love.touchpressed above
-    -- returns early on iOS and never forwards, so there the synthesized mouse
-    -- press is the ONLY event the launcher gets.  Filtering istouch on both
-    -- killed every tap on iOS outright.
-    if istouch and love.system.getOS() == "Android" then return end
+    -- love.touchpressed already forwards the primary touch into FlexLove for
+    -- scroll. LÖVE ALSO synthesizes a mouse press for that same touch; if both
+    -- reached a press handler, one tap ran every launcher button twice and
+    -- stacked two SAF pickers (#553). Clicks are polled inside FlexLove from
+    -- love.touch / mouse.isDown, so dropping the synthesized istouch press is
+    -- safe. A real mouse (DeX, Chromebook, USB) still reaches mousepressed.
+    if istouch and (love.system.getOS() == "Android"
+        or love.system.getOS() == "iOS") then return end
     return Importer:mousepressed(x, y, button)
   end
   if editorMode and EditorApp.mousepressed then
+    -- Same Android double-fire guard: touchpressed already clicked for the
+    -- save editor; a synthesized mouse press must not fire again.
+    if istouch and love.system.getOS() == "Android" then return end
     return EditorApp.mousepressed(x, y, button)
   end
-  if mouseTouch and Game and button == 1 then
-    Game:touchpressed("mouse", x, y)
+  if mouseTouch then
+    -- the mouse is standing in for a finger: the touch path owns it, and
+    -- feeding the same press back in as a mouse pointer would double it
+    if Game and button == 1 then Game:touchpressed("mouse", x, y) end
+    return
   end
+  -- #807: a real mouse reaches gameplay as a pointer event for mods; Game
+  -- drops synthesized istouch twins so a mobile touch that already arrived
+  -- through love.touchpressed cannot fire twice
+  if Game then Game:mousepressed(x, y, button, istouch) end
 end
 
-function love.mousereleased(x, y, button)
+function love.mousereleased(x, y, button, istouch)
   if TouchEditor then
     if love.system.getOS() == "Android" then return end
     return TouchEditor.mousereleased(x, y, button)
@@ -503,20 +762,25 @@ function love.mousereleased(x, y, button)
   if editorMode and EditorApp.mousereleased then
     return EditorApp.mousereleased(x, y, button)
   end
-  if mouseTouch and Game and button == 1 then
-    Game:touchreleased("mouse", x, y)
+  if mouseTouch then
+    if Game and button == 1 then Game:touchreleased("mouse", x, y) end
+    return
   end
+  if Game then Game:mousereleased(x, y, button, istouch) end
 end
 
-function love.mousemoved(x, y)
+function love.mousemoved(x, y, dx, dy, istouch)
+  if not istouch then eventMouseX, eventMouseY = x, y end
   if TouchEditor then
     if love.system.getOS() == "Android" then return end
     return TouchEditor.mousemoved(x, y)
   end
   if editorMode or Importer then return end
-  if mouseTouch and Game and love.mouse.isDown(1) then
-    Game:touchmoved("mouse", x, y)
+  if mouseTouch then
+    if Game and love.mouse.isDown(1) then Game:touchmoved("mouse", x, y) end
+    return
   end
+  if Game then Game:mousemoved(x, y, dx, dy, istouch) end
 end
 
 function love.textinput(text)
@@ -527,9 +791,43 @@ function love.textinput(text)
   end
 end
 
+-- #785: set once love.quit has routed a window close into HostShell.restart,
+-- so the follow-up quit event the restart itself raises (quit("restart") on
+-- desktop; AppImage and Android relaunch the process instead, #575) falls
+-- through to the normal shutdown below instead of restarting forever.
+local quitToLauncher = false
+
 function love.quit()
   if editorMode and EditorApp.quit then
-    return EditorApp.quit() -- return true to abort quit
+    -- true blocks the quit (unsaved-changes prompt).  A quit that proceeds
+    -- must fall through to the worker shutdowns below instead of returning:
+    -- the bundled editor opens from a live launcher whose update-check and
+    -- fetch-pool workers are still parked in Channel:demand(), and returning
+    -- here skipped their "quit" push, so the process outlived the closed
+    -- window and kept the install folder locked on Windows (#727).
+    if EditorApp.quit() then return true end
+  end
+  -- Closing the window of a running game returns to the launcher instead of
+  -- exiting the app, so testing a mod does not need a relaunch every time
+  -- (#785).  Game is only non-nil once bootGame ran; Importer non-nil means
+  -- the launcher (or its import) owns the window and its close still quits.
+  -- Scripted and headless runs (autopilot, frame driver, import-only, ROM
+  -- path import) keep the plain exit so they terminate as before.  Nothing
+  -- is saved here on purpose: a window close never wrote the save, and the
+  -- restart path must be no worse than that, not quietly better.
+  local scripted = os.getenv("POKEPORT_AUTOPILOT") or os.getenv("POKEPORT_DRIVER")
+    or os.getenv("POKEPORT_IMPORT_ONLY") == "1" or os.getenv("POKEPORT_IMPORT_ROM")
+  -- #887: a shortcut session (--game / POKEPORT_GAME) has no launcher to go
+  -- back to and the restart would re-read the shortcut, so it exits instead.
+  if Game and not Importer and not quitToLauncher and not scripted
+      and not launchedIntoGame then
+    quitToLauncher = true
+    -- Tell the fresh boot to ignore any boot-straight-into-a-game option this
+    -- once, so the restart really does land in the launcher (#887).  A failed
+    -- write only costs that suppression, so it must never block the restart.
+    pcall(love.filesystem.write, RELAUNCH_MARKER, "1")
+    require("src.core.HostShell").restart()
+    return true -- abort this quit; the restart lands back in the launcher
   end
   pcall(function()
     require("src.core.DiscordPresence").shutdown()
@@ -544,6 +842,12 @@ function love.quit()
   if package.loaded["src.update.Check"] then
     pcall(package.loaded["src.update.Check"].shutdown)
   end
+  -- The launcher's fetch pool is the same story: its workers idle in
+  -- Channel:demand(), which never returns on its own, so a launcher that ever
+  -- touched the network would hang the process on exit (#339's shape again).
+  if package.loaded["src.net.Fetch"] then
+    pcall(package.loaded["src.net.Fetch"].shutdown)
+  end
 end
 
 function love.filedropped(file)

mobile/ANDROID.md

@@ -73,6 +73,21 @@ of the build script's permission trim). The first
 read runs immediately (`onRequestPermissionsResult`,
 `STEP_PERMISSION_REQUEST_CODE`).
 
+### Network transport (mod index / mod updates)
+
+`love.system.httpDownload(url, absPath [, userAgent [, accept]])` ->
+`GameActivity.httpDownload` (same JNI route as the picker and the step
+bridge: `common/android.cpp` -> `modules/system/System.cpp` ->
+`wrap_System.cpp`). Android ships no `curl`, which is what the desktop
+builds fetch the mod index, mod release lists and mod zips with, so the
+"Find mods" tab used to fail with "curl is not available on this
+platform" (#597). The Java side is a blocking `HttpsURLConnection` GET
+(https only, redirects followed by hand, body renamed into place only
+once complete) and runs on LOVE's Lua thread, never the UI thread.
+`src/core/HostShell.lua` picks the transport: curl when present,
+otherwise this bridge; an APK older than the bridge simply reports no
+transport, exactly as a missing curl does.
+
 ### SDK / NDK
 
 love-android 11.5a expects:
@@ -93,7 +108,8 @@ The APK lands under `app/build/outputs/apk/embedNoRecord/debug/`.
 ### Payload path
 
 `app/src/embed/assets/game.love` - zip of `main.lua`, `conf.lua`, `src/`,
-`data/`, `assets/`, and the Red, Blue, and Yellow ROM manifests. The Android
+`libs/` (the vendored FlexLove toolkit the launcher UI needs), `data/`,
+`assets/`, and the Red, Blue, and Yellow ROM manifests. The Android
 packer verifies the Yellow manifest before it packages; if a partial source
 export omitted it, it restores the file from this checkout's Git data and then
 falls back to the project's GitHub copy. Generated game data,
@@ -107,7 +123,7 @@ scripts, tests, and mobile build sources are excluded.
 | `app.name` | Pokemon Red |
 | `app.orientation` | `fullUser`. This is only the manifest default: SDL requests FULL_SENSOR at window creation (resizable window, no `SDL_HINT_ORIENTATIONS`), and `GameActivity.setOrientationBis` remaps that to FULL_USER so the device's rotation lock is honoured. |
 | `app.version_name` / `app.version_code` | set from `--version X.Y.Z` (code = major*10000 + minor*100 + patch); left as-is if `--version` is omitted |
-| Permissions | INTERNET / RECORD_AUDIO / WRITE_EXTERNAL_STORAGE stripped; VIBRATE + BLUETOOTH kept |
+| Permissions | RECORD_AUDIO / WRITE_EXTERNAL_STORAGE stripped; VIBRATE + BLUETOOTH + INTERNET (link play, mod index) + ACTIVITY_RECOGNITION (step bridge) kept |
 
 ## Releases
 

mobile/android/love/src/jni/love/src/common/android.cpp

@@ -37,6 +37,13 @@
 
 #include "filesystem/physfs/PhysfsIo.h"
 
+// #604 / #839: the SAF bridges below must hand GameActivity the exact
+// directory physfs mounted as the save dir -- the same contract the iOS
+// GRPickerBridge already gets (mobile/ios/patch_love_src.py,
+// gr_saveDirectory) -- instead of letting Java recompute the root on its
+// own, which can name a different volume on merged / adopted-SD storage.
+#include "filesystem/Filesystem.h"
+
 namespace love
 {
 namespace android
@@ -183,6 +190,19 @@ void vibrate(double seconds)
 	env->DeleteLocalRef(activity);
 }
 
+// The directory physfs actually mounted as the save dir, or "" before the
+// filesystem module is up.  GameActivity must copy SAF picks HERE: its own
+// getExternalFilesDir(null) recomputation can disagree with the mounted
+// root on merged / adopted-SD storage (#604, #839).
+static const char *bridgeSaveDirectory()
+{
+	auto fs = Module::getInstance<love::filesystem::Filesystem>(Module::M_FILESYSTEM);
+	if (fs == nullptr)
+		return "";
+	const char *dir = fs->getSaveDirectory();
+	return dir != nullptr ? dir : "";
+}
+
 bool showFilePicker(const char *destFilename)
 {
 	if (destFilename == nullptr || destFilename[0] == '\0')
@@ -192,9 +212,11 @@ bool showFilePicker(const char *destFilename)
 	jclass activity = env->FindClass("org/love2d/android/GameActivity");
 
 	jmethodID method = env->GetStaticMethodID(activity, "showFilePicker",
-		"(Ljava/lang/String;)Z");
+		"(Ljava/lang/String;Ljava/lang/String;)Z");
 	jstring jname = env->NewStringUTF(destFilename);
-	jboolean result = env->CallStaticBooleanMethod(activity, method, jname);
+	jstring jsavedir = env->NewStringUTF(bridgeSaveDirectory());
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jname, jsavedir);
+	env->DeleteLocalRef(jsavedir);
 	env->DeleteLocalRef(jname);
 
 	env->DeleteLocalRef(activity);
@@ -210,9 +232,11 @@ bool showCreateDocument(const char *suggestedName)
 	jclass activity = env->FindClass("org/love2d/android/GameActivity");
 
 	jmethodID method = env->GetStaticMethodID(activity, "showCreateDocument",
-		"(Ljava/lang/String;)Z");
+		"(Ljava/lang/String;Ljava/lang/String;)Z");
 	jstring jname = env->NewStringUTF(suggestedName);
-	jboolean result = env->CallStaticBooleanMethod(activity, method, jname);
+	jstring jsavedir = env->NewStringUTF(bridgeSaveDirectory());
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jname, jsavedir);
+	env->DeleteLocalRef(jsavedir);
 	env->DeleteLocalRef(jname);
 
 	env->DeleteLocalRef(activity);
@@ -253,6 +277,53 @@ bool restartApp()
 	return result;
 }
 
+bool httpDownload(const char *url, const char *destPath, const char *userAgent, const char *accept)
+{
+	if (url == nullptr || destPath == nullptr)
+		return false;
+
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	// NOT FindClass: this is the one bridge called off the main thread
+	// (love.thread workers in src/net/fetch_worker.lua and
+	// src/update/check_worker.lua).  A worker is a raw pthread whose JNI
+	// class loader is the system one, which cannot see app classes, so
+	// FindClass("org/love2d/android/GameActivity") left a pending
+	// ClassNotFoundException and the next JNI call aborted the process --
+	// opening FIND MODS killed the app on the first stats fetch.  Resolving
+	// through the live activity instance works from any attached thread.
+	jobject activityObj = (jobject) SDL_AndroidGetActivity();
+	if (activityObj == nullptr)
+		return false;
+	jclass activity = env->GetObjectClass(activityObj);
+	env->DeleteLocalRef(activityObj);
+
+	// Old APK / new liblove skew: report "no transport" the same way a
+	// missing curl does, instead of aborting on a missing method (#597).
+	jmethodID method = env->GetStaticMethodID(activity, "httpDownload",
+		"(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Z");
+	if (method == nullptr)
+	{
+		env->ExceptionClear();
+		env->DeleteLocalRef(activity);
+		return false;
+	}
+
+	jstring jurl = env->NewStringUTF(url);
+	jstring jdest = env->NewStringUTF(destPath);
+	jstring jua = env->NewStringUTF(userAgent != nullptr ? userAgent : "gen1recomp");
+	jstring jaccept = accept != nullptr ? env->NewStringUTF(accept) : nullptr;
+
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jurl, jdest, jua, jaccept);
+
+	env->DeleteLocalRef(jurl);
+	env->DeleteLocalRef(jdest);
+	env->DeleteLocalRef(jua);
+	if (jaccept != nullptr)
+		env->DeleteLocalRef(jaccept);
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
 /*
  * Helper functions for the filesystem module
  */

mobile/android/love/src/jni/love/src/common/android.h

@@ -90,6 +90,14 @@ bool syncHealthSteps();
  **/
 bool restartApp();
 
+/**
+ * Blocking HTTPS GET into destPath (GameActivity.httpDownload). Android has
+ * no curl binary, so this is the transport src/core/HostShell.lua uses there
+ * for the mod index and mod updates (#597). userAgent / accept may be null.
+ * Returns whether a complete file was written.
+ **/
+bool httpDownload(const char *url, const char *destPath, const char *userAgent, const char *accept);
+
 /*
  * Helper functions for the filesystem module
  */

mobile/android/love/src/jni/love/src/modules/system/System.cpp

@@ -230,6 +230,20 @@ bool System::restartApp() const
 #endif
 }
 
+bool System::httpDownload(const char *url, const char *destPath,
+	const char *userAgent, const char *accept) const
+{
+#ifdef LOVE_ANDROID
+	return love::android::httpDownload(url, destPath, userAgent, accept);
+#else
+	LOVE_UNUSED(url);
+	LOVE_UNUSED(destPath);
+	LOVE_UNUSED(userAgent);
+	LOVE_UNUSED(accept);
+	return false;
+#endif
+}
+
 bool System::hasBackgroundMusic() const
 {
 #if defined(LOVE_ANDROID)

mobile/android/love/src/jni/love/src/modules/system/System.h

@@ -141,6 +141,14 @@ public:
 	 **/
 	virtual bool restartApp() const;
 
+	/**
+	 * Blocking HTTPS GET into an absolute host path (Android only; false
+	 * elsewhere). Android has no curl, which is what every other platform
+	 * fetches the mod index with (#597).
+	 **/
+	virtual bool httpDownload(const char *url, const char *destPath,
+		const char *userAgent = nullptr, const char *accept = nullptr) const;
+
 	/**
 	 * Gets if the user is playing music on background.
 	 * Throws an exception on unsupported platforms.

mobile/android/love/src/jni/love/src/modules/system/wrap_System.cpp

@@ -123,6 +123,16 @@ int w_restartApp(lua_State *L)
 	return 1;
 }
 
+int w_httpDownload(lua_State *L)
+{
+	const char *url = luaL_checkstring(L, 1);
+	const char *dest = luaL_checkstring(L, 2);
+	const char *ua = luaL_optstring(L, 3, nullptr);
+	const char *accept = luaL_optstring(L, 4, nullptr);
+	luax_pushboolean(L, instance()->httpDownload(url, dest, ua, accept));
+	return 1;
+}
+
 int w_hasBackgroundMusic(lua_State *L)
 {
 	lua_pushboolean(L, instance()->hasBackgroundMusic());
@@ -142,6 +152,7 @@ static const luaL_Reg functions[] =
 	{ "createFile", w_createFile },
 	{ "syncHealthSteps", w_syncHealthSteps },
 	{ "restartApp", w_restartApp },
+	{ "httpDownload", w_httpDownload },
 	{ "hasBackgroundMusic", w_hasBackgroundMusic },
 	{ 0, 0 }
 };

mobile/android/love/src/main/java/org/love2d/android/GameActivity.java

@@ -31,6 +31,8 @@ import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
@@ -114,6 +116,18 @@ public class GameActivity extends SDLActivity {
     // bad ROM instead of installing it (#553).
     private String pendingPickFilename = PICKED_ROM_FILENAME;
     private static final String STATE_PENDING_PICK = "pendingPickFilename";
+    // Absolute save directory physfs actually mounted, as reported by the
+    // native bridge call that opened the picker (love/src/common/android.cpp,
+    // bridgeSaveDirectory).  This activity used to recompute
+    // getExternalFilesDir(null)/save/<identity> on its own at result time; on
+    // merged / adopted-SD storage that can name a different volume than the
+    // one LOVE mounted, so the copied pick (and pick_error.flag) landed where
+    // Lua never scans -- the launcher then "did nothing" after a pick (#604)
+    // and the folders a file manager can browse stayed empty while the game
+    // saved fine elsewhere (#839).  Empty string means "not told yet": fall
+    // back to the historical computation.
+    private String pendingPickSaveDir = "";
+    private static final String STATE_PENDING_PICK_DIR = "pendingPickSaveDir";
     private static final String STATE_PENDING_CREATE = "pendingCreateSuggestedName";
     // Suggested download name for the in-flight SAF create (set by showCreateDocument).
     private String pendingCreateSuggestedName = "export.sav";
@@ -184,6 +198,8 @@ public class GameActivity extends SDLActivity {
             // a recreated activity still lands under the basename it asked for.
             String pick = savedInstanceState.getString(STATE_PENDING_PICK);
             if (pick != null) pendingPickFilename = pick;
+            String pickDir = savedInstanceState.getString(STATE_PENDING_PICK_DIR);
+            if (pickDir != null) pendingPickSaveDir = pickDir;
             String create = savedInstanceState.getString(STATE_PENDING_CREATE);
             if (create != null) pendingCreateSuggestedName = create;
         }
@@ -465,13 +481,23 @@ public class GameActivity extends SDLActivity {
      * @param destFilename basename under the app save identity (e.g.
      *                     picked_rom.gb, picked_mod.zip, picked_save.sav)
      */
+    /** Legacy single-argument entry; resolves the save dir itself. */
     @Keep
     public static boolean showFilePicker(String destFilename) {
+        return showFilePicker(destFilename, null);
+    }
+
+    @Keep
+    public static boolean showFilePicker(String destFilename, String saveDir) {
         GameActivity self = (GameActivity) mSingleton;
         if (self == null) return false;
         if (destFilename == null || destFilename.length() == 0) {
             destFilename = PICKED_ROM_FILENAME;
         }
+        // Remember where LOVE's filesystem is really mounted so
+        // onActivityResult copies the pick there, not into a recomputed
+        // (possibly different-volume) root (#604, #839).
+        self.pendingPickSaveDir = (saveDir != null) ? saveDir : "";
         // Reject path separators so a hostile JNI caller cannot escape the
         // save identity directory.
         if (destFilename.indexOf('/') >= 0 || destFilename.indexOf('\\') >= 0) {
@@ -565,6 +591,73 @@ public class GameActivity extends SDLActivity {
         return true; // unreachable, but keeps the JNI signature honest
     }
 
+    /**
+     * Blocking HTTPS GET into destPath, exposed as love.system.httpDownload
+     * and used by src/core/HostShell.lua. Android ships no curl binary, so
+     * every remote fetch the desktop builds do with curl (mod index feeds,
+     * mod release lists, mod zips, thumbnails) comes through here (#597).
+     * Runs on LOVE's Lua thread, never the UI thread, so the platform's
+     * network-on-main-thread rule is not in play and a blocking call matches
+     * the curl semantics the Lua callers already expect.
+     *
+     * Redirects are followed by hand because HttpURLConnection silently drops
+     * a redirect that changes protocol, and only https is accepted: the feeds
+     * live on GitHub Pages / raw and a downgrade to http must fail, not fetch.
+     * The body lands in a .part file and is renamed only once complete, so a
+     * dropped connection can never leave a half file the caller trusts.
+     */
+    @Keep
+    public static boolean httpDownload(String url, String destPath, String userAgent, String accept) {
+        if (url == null || destPath == null) return false;
+        HttpURLConnection conn = null;
+        File tmp = new File(destPath + ".part");
+        try {
+            String current = url;
+            for (int hop = 0; hop < 5; hop++) {
+                URL parsed = new URL(current);
+                if (!"https".equalsIgnoreCase(parsed.getProtocol())) return false;
+                conn = (HttpURLConnection) parsed.openConnection();
+                conn.setInstanceFollowRedirects(false);
+                conn.setConnectTimeout(15000);
+                conn.setReadTimeout(60000);
+                conn.setRequestProperty("User-Agent",
+                    userAgent == null ? "gen1recomp" : userAgent);
+                if (accept != null) conn.setRequestProperty("Accept", accept);
+                int code = conn.getResponseCode();
+                if (code == 301 || code == 302 || code == 303 || code == 307 || code == 308) {
+                    String next = conn.getHeaderField("Location");
+                    conn.disconnect();
+                    conn = null;
+                    if (next == null) return false;
+                    current = new URL(parsed, next).toString();
+                    continue;
+                }
+                if (code < 200 || code > 299) return false;
+                InputStream in = new BufferedInputStream(conn.getInputStream());
+                OutputStream out = new BufferedOutputStream(new FileOutputStream(tmp));
+                try {
+                    byte[] buf = new byte[16384];
+                    int n;
+                    while ((n = in.read(buf)) > 0) out.write(buf, 0, n);
+                } finally {
+                    try { out.close(); } catch (IOException ignored) {}
+                    try { in.close(); } catch (IOException ignored) {}
+                }
+                File dest = new File(destPath);
+                dest.delete();
+                if (!tmp.renameTo(dest)) return false;
+                return dest.length() > 0;
+            }
+            return false;
+        } catch (Exception e) {
+            Log.d("GameActivity", "httpDownload failed: " + e.getMessage());
+            return false;
+        } finally {
+            if (conn != null) conn.disconnect();
+            if (tmp.exists()) tmp.delete();
+        }
+    }
+
     /**
      * Shows ACTION_CREATE_DOCUMENT so the player can save a staged export
      * (pending_export.sav in the app save identity) to Downloads / Drive /
@@ -575,8 +668,14 @@ public class GameActivity extends SDLActivity {
      * return degrades on the Lua side (RomImporter export) to "Exported
      * inside the app folder", which is the correct pre-KitKat behavior.
      */
+    /** Legacy single-argument entry; resolves the save dir itself. */
     @Keep
     public static boolean showCreateDocument(String suggestedName) {
+        return showCreateDocument(suggestedName, null);
+    }
+
+    @Keep
+    public static boolean showCreateDocument(String suggestedName, String saveDir) {
         if (android.os.Build.VERSION.SDK_INT < 19) return false;
         // (see showFilePicker for why the import side got a pre-19 path)
         GameActivity self = (GameActivity) mSingleton;
@@ -588,9 +687,12 @@ public class GameActivity extends SDLActivity {
             Log.d("GameActivity", "refusing unsafe create name: " + suggestedName);
             return false;
         }
-        File source = new File(
-            new File(self.getExternalFilesDir(null), "save"),
-            ROM_SAVE_IDENTITY + "/" + PENDING_EXPORT_FILENAME);
+        // Route through the mounted save dir (#604, #839): Lua staged
+        // pending_export.sav where physfs writes, which is not necessarily
+        // where a fresh getExternalFilesDir(null) points on merged /
+        // adopted-SD storage.
+        self.pendingPickSaveDir = (saveDir != null) ? saveDir : "";
+        File source = new File(self.saveIdentityDir(), PENDING_EXPORT_FILENAME);
         if (!source.isFile()) {
             Log.d("GameActivity", "no pending export at " + source);
             return false;
@@ -611,7 +713,21 @@ public class GameActivity extends SDLActivity {
     }
 
     private File saveIdentityDir() {
-        return new File(new File(getExternalFilesDir(null), "save"), ROM_SAVE_IDENTITY);
+        // Prefer the mounted save dir the last bridge call reported: the
+        // recomputation below can name a different volume than the one LOVE
+        // mounted on merged / adopted-SD storage (#604, #839).
+        if (pendingPickSaveDir != null && pendingPickSaveDir.length() > 0) {
+            return new File(pendingPickSaveDir);
+        }
+        File ext = getExternalFilesDir(null);
+        if (ext == null) {
+            // Shared storage unavailable (ejected / mid-adoption): without
+            // this guard File(null, "save") silently built the RELATIVE
+            // path save/<identity>, mkdirs() failed against "/", and the
+            // pick was dropped with no message at all (#604).
+            ext = getFilesDir();
+        }
+        return new File(new File(ext, "save"), ROM_SAVE_IDENTITY);
     }
 
     /** Drops a small flag file in the save identity for Lua to consume on focus. */
@@ -806,6 +922,7 @@ public class GameActivity extends SDLActivity {
     protected void onSaveInstanceState(Bundle outState) {
         super.onSaveInstanceState(outState);
         outState.putString(STATE_PENDING_PICK, pendingPickFilename);
+        outState.putString(STATE_PENDING_PICK_DIR, pendingPickSaveDir);
         outState.putString(STATE_PENDING_CREATE, pendingCreateSuggestedName);
     }
 

mobile/ios/app-repo.json

@@ -0,0 +1,137 @@
+{
+  "name": "gen1recomp App Repo",
+  "identifier": "com.theboisclub.gen1recomp.repo",
+  "iconURL": "https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/assets/logo/gen1recomp_cover.png",
+  "apps": [
+    {
+      "name": "gen1recomp",
+      "bundleIdentifier": "com.theboisclub.gen1recomp",
+      "developerName": "bryanthaboi",
+      "iconURL": "https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/assets/logo/gen1recomp_cover.png",
+      "localizedDescription": "Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke",
+      "tintColor": "3b5ca8",
+      "category": "games",
+      "versions": [
+        {
+          "version": "0.1.74",
+          "date": "2026-08-06",
+          "size": 9588946,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.74/gen1recomp-0.1.74-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #883 Evolution Stones consumed if evolution is cancelled\n- #887 MacOS Closing game just keeps reopening\n- #894 Max Repel usable in battle\n\n## Contributors\n\n- @bryanthaboi\n- @MarceloMachadoxD\n- @ratherDashing"
+        },
+        {
+          "version": "0.1.73",
+          "date": "2026-08-06",
+          "size": 9585729,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.73/gen1recomp-0.1.73-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #878 Mod API: allow active screen states to be hidden from the main render\n\n## Contributors\n\n- @AverageConsumer\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.72",
+          "date": "2026-08-05",
+          "size": 9586678,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.72/gen1recomp-0.1.72-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #604 Android, retroid pocket 2+ Rom won't import\n- #666 Pikachu emotions are not working on Android\n- #716 Lock Auto Rotate Mobile\n- #727 [Bug] [Windows] Gen1 Recomp \"still in use\" after closing\n- #763 Some EVENTS are turned off\n- #781 Mouse cursor broken on Linux with multi-monitor X11 setup\n- #784 Leech Seed effect\n- #799 Held direction randomly stops player movement (requires re-input)\n- #801 Cannot update mods from the launcher (MacOS)\n- #810 Launcher menu cuts off in vertical mode iOS\n- #828 Closing the app causes settings in launcher to reset\n- #834 Mod import failing\n- #838 Exporting save file Pokemon Yellow\n- #839 AYN Thor Misplaced Data files\n- #849 Public folder support on iOS\n- #852 Cannot switch between saves states on smaller 4:3 screen or in vertical mode\n- #857 Mt. Moon Fossils Reappeared and Won’t Disappear.\n- #863 [Yellow] When you use stairs, Pikachu shouldn't be next to you in the new area\n- #864 Faithful Ratio\n- #867 Missing Dialogue after defeating Marowak in Pokemon Tower\n- #869 Giovanni moves up to the player too early\n- #870 Start Menu on Classic Color\n- #872 Missing text when finding an item with full inventory\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.71",
+          "date": "2026-08-05",
+          "size": 9569738,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.71/gen1recomp-0.1.71-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #806 Haptic Feedback for On-screen controls (mobile)\n- #809 NPC Stuck in Rock when battle triggered and pushing rock towards it\n- #853 When selecting one of the two pokemon after defeating the Karate Master it should show the Pokedex entry\n- #854 Textbox disappears when the yes/no dialogue appears\n- #860 Disabled moves can still be used in the turn they were disabled\n- #862 Casino Poster Rocket Grunt walks into the poster and doesn't \"Dang!\"\n- #865 [Yellow] James doesn't move in multiple encounters\n- #866 [Yellow] Dialogue in wrong \"order\" after multiple encounters (J+J, Giovanni, probably more)\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.70",
+          "date": "2026-08-05",
+          "size": 9562731,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.70/gen1recomp-0.1.70-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #590 Launcher/Save Editor/Dex\n- #788 Fly to the Pokemon Centers in the Routes is not available in original\n- #795 Fly logic is drastically different from the originals.\n- #796 Using Rare Candy from the menu closes it out.\n- #797 Gym Leaders giving items when your bag is full / Bypassing bag limit.\n- #805 Escape Rope Moltres Tower\n- #826 \"Super effective\" and \"not very effective\" SFX are reversed\n- #833 Cancelling nickname entry results in \"A\" as the nickname\n- #835 Restarting the launcher forgets the last rom used\n- #837 Wrong sound effect for Pikachu when entering battle\n- #844 Blizzard sound effect.\n- #845 Moderate issue: Fuchsia City binoculars.\n- #846 Surfing speed after using the bicycle.\n- #847 Minor issues related to the endgame.\n\n## Contributors\n\n- @bryanthaboi\n- @dburton95\n- @johnjohto\n- @KikiManjaro"
+        },
+        {
+          "version": "0.1.69",
+          "date": "2026-08-04",
+          "size": 9552851,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.69/gen1recomp-0.1.69-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #768 Menu behaviour for Pokemon and HM moves\n- #785 Back to launcher\n- #792 HM moves in the wrong position in the menu.\n- #807 Expose gameplay pointer events and source-safe mod input injection\n- #811 Untranslatables\n- #814 [minor thing] bold arrow on move swap (select)\n\n## Contributors\n\n- @bryanthaboi\n- @johnjohto"
+        },
+        {
+          "version": "0.1.68",
+          "date": "2026-08-04",
+          "size": 9768011,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.68/gen1recomp-0.1.68-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi\n- @caorthann-celt"
+        },
+        {
+          "version": "0.1.67",
+          "date": "2026-08-04",
+          "size": 9767619,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.67/gen1recomp-0.1.67-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #373 Lines at Title Screen\n- #644 Substitute failing causes visual issues\n- #673 iOS: thin vertical seam below the START menu panel (v0.1.56, iPhone 15 Pro Max)\n- #703 Credits playing too fast (song ends after it should)\n- #726 Surfing Pikachu Minigame Broken\n- #737 Battle menu move cursor fails to reset to the first slot after switching Pokémon\n- #750 NPC (possibly player) trades still graphically broken\n- #752 Launcher exports save to AppData while in portable mode\n- #764 Trainer Fanfare doesn't play\n- #765 Text Advance broken in certain aspects\n- #768 Menu behaviour for Pokemon and HM moves\n- #773 Battle screen colours messed up when BG = World, battle in un-flashed Rock Tunnel\n- #774 bug(build): Desktop build can reject a valid game archive under pipefail\n- #775 TM42 Dream Eater dialog.\n- #777 Battle Screen is Very dark\n- #780 Do not delete save\n- #782 Giovanni battle at Silph Co plays wrong song\n\n## Contributors\n\n- @bryanthaboi\n- @luisgonzaleznf\n- @ShaneMcGovernIE"
+        },
+        {
+          "version": "0.1.66",
+          "date": "2026-08-04",
+          "size": 9749980,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.66/gen1recomp-0.1.66-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #691 Save file transfer\n- #743 Cannot Scroll Main Menu/Mod Menu\n- #779 \"Enemy \" untranslateable\n\n## Contributors\n\n- @bryanthaboi\n- @jherediagu\n- @ShaneMcGovernIE\n- @vegerot"
+        },
+        {
+          "version": "0.1.65",
+          "date": "2026-08-03",
+          "size": 9376618,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.65/gen1recomp-0.1.65-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #592 Screen Orientation\n- #702 FLY overworld animation incorrect/incomplete\n- #748 Launcher Menu has overlap\n- #754 Can push boulders with STRENGTH through walls\n- #758 PC to Mac Online Multiplayer Disconnects Shortly After Starting Match\n\n## Contributors\n\n- @andrewqsantos\n- @Bortlesboat\n- @bryanthaboi\n- @castdrian\n- @johnjohto\n- @ShaneMcGovernIE"
+        },
+        {
+          "version": "0.1.64",
+          "date": "2026-08-03",
+          "size": 9317129,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.64/gen1recomp-0.1.64-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi\n- @ShaneMcGovernIE"
+        },
+        {
+          "version": "0.1.63",
+          "date": "2026-08-03",
+          "size": 9316977,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.63/gen1recomp-0.1.63-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #623 Game Corner Prize Exchange various issues\n- #624 Coins purschase menu missing your current money and coins\n- #636 Inaccurate Old Man tutorial in yellow + misc issues relating to him\n- #637 True color broken on Hall of Fame and Party Stats when using the wide battle option\n- #639 Pokédex can't show the correct stats when you catch 100 or more pokémon + overly simplified layout\n- #650 Rocket Hideout Progression Bug - Stuck with door closed after defeating Jessie and James in Yellow\n- #697 Missaligned HUD on Hall of Fame\n- #704 Player doesn't follow Prof. Oak to the Hall of Fame on the first screen\n- #722 Issues with Giovanni in Silph C.O.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.62",
+          "date": "2026-08-03",
+          "size": 9309934,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.62/gen1recomp-0.1.62-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Contributors\n\n- @bryanthaboi"
+        },
+        {
+          "version": "0.1.61",
+          "date": "2026-08-03",
+          "size": 9052744,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.61/gen1recomp-0.1.61-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #325 Launcher crashes importing a mod .zip with non-ASCII characters in the filename (Windows)\n- #646 Fuchsia City Pokemon not being added to Pokedex.\n- #651 Parasect trading NPC mute and deaf\n- #665 fix: file path sanitizing is needed\n- #706 Champion theme playing too late\n- #709 Fainted Pokemon plays its normal cry instead of the pitched-down, slower faint cry\n- #719 Silph C.O workers dialog bug.\n\n## Contributors\n\n- @bryanthaboi\n- @castdrian\n- @jherediagu\n- @johnjohto\n- @ShaneMcGovernIE\n- hernan"
+        },
+        {
+          "version": "0.1.60",
+          "date": "2026-08-02",
+          "size": 8337730,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.60/gen1recomp-0.1.60-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #596 No rival theme\n- #641 PP UP UI\n- #648 The revive item does not return the divided experience to fallen Pokemon that participated in battle.\n- #677 Gamespeed 3x\n- #683 Rival theme not playing in Oak's Lab\n- #689 Corrupted color on table in Celadon City using Advanced Colors preset\n- #694 Missing sound effect when falling from boulder holes\n- #695 Pressing B on the PC should bring you back to the previous screen, not turn it off\n\n## Contributors\n\n- @bryanthaboi\n- @castdrian\n- @ShaneMcGovernIE\n- @spiritsnails\n- Shane McGovern"
+        },
+        {
+          "version": "0.1.59",
+          "date": "2026-08-02",
+          "size": 8334731,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.59/gen1recomp-0.1.59-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #668 No Jingle playing when receiving first Pokemon from Oak\n- #671 faint animation error\n\n## Contributors\n\n- @bryanthaboi\n- @castdrian\n- @jherediagu\n- @spiritsnails\n- Shane McGovern"
+        },
+        {
+          "version": "0.1.58",
+          "date": "2026-08-02",
+          "size": 8331163,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.58/gen1recomp-0.1.58-ios.ipa",
+          "localizedDescription": "Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke"
+        }
+      ]
+    }
+  ]
+}

mobile/ios/native/GRPickerBridge.swift

@@ -30,6 +30,45 @@ public final class GRPickerBridge: NSObject {
     // (<sandbox>/Library/Application Support/<identity>).
     private static let loveIdentity = "pokemon-love2d"
 
+    @objc(httpDownloadWithUrl:destination:userAgent:accept:)
+    public static func httpDownload(url: UnsafePointer<CChar>?,
+                                    destination: UnsafePointer<CChar>?,
+                                    userAgent: UnsafePointer<CChar>?,
+                                    accept: UnsafePointer<CChar>?) -> Bool {
+        guard let url, let destination,
+              let requestURL = URL(string: String(cString: url)) else { return false }
+        var request = URLRequest(url: requestURL)
+        request.timeoutInterval = 300
+        if let userAgent, userAgent.pointee != 0 {
+            request.setValue(String(cString: userAgent), forHTTPHeaderField: "User-Agent")
+        }
+        if let accept, accept.pointee != 0 {
+            request.setValue(String(cString: accept), forHTTPHeaderField: "Accept")
+        }
+        let target = URL(fileURLWithPath: String(cString: destination))
+        let semaphore = DispatchSemaphore(value: 0)
+        var succeeded = false
+        let task = URLSession.shared.downloadTask(with: request) { temporary, response, error in
+            defer { semaphore.signal() }
+            guard error == nil, let temporary,
+                  let http = response as? HTTPURLResponse,
+                  (200..<300).contains(http.statusCode) else { return }
+            try? FileManager.default.removeItem(at: target)
+            do {
+                try FileManager.default.moveItem(at: temporary, to: target)
+                succeeded = true
+            } catch {
+                succeeded = false
+            }
+        }
+        task.resume()
+        guard semaphore.wait(timeout: .now() + 305) == .success else {
+            task.cancel()
+            return false
+        }
+        return succeeded
+    }
+
     // MARK: - Entry points called from liblove (C strings on purpose)
 
     @objc(presentPickerWithKind:saveDir:)
@@ -174,15 +213,27 @@ public final class GRPickerBridge: NSObject {
             // Without this the stacked present makes the picker auto-dismiss
             // with zero documents (observed as didPickDocumentsAt 0 urls)
             // and the user's pick silently does nothing.
+            guard var top = UIApplication.shared.windows
+                .first(where: { $0.isKeyWindow })?.rootViewController
+            else { return false }
+            // Self-heal before consulting the list. If UIKit is presenting
+            // nothing at all, any delegate still in it belongs to a sheet
+            // that is long gone, and treating it as live would lock the
+            // picker out for the rest of the session. Belt and braces with
+            // the dismissal callback above: that one closes the known hole,
+            // this one closes whatever hole iOS invents next.
+            if top.presentedViewController == nil, !liveDelegates.isEmpty {
+                NSLog("GRPickerBridge: clearing %d stale delegate(s)",
+                      liveDelegates.count)
+                liveDelegates.removeAll()
+            }
             guard liveDelegates.isEmpty else {
                 NSLog("GRPickerBridge: picker already active; ignoring re-present")
                 return true
             }
-            guard var top = UIApplication.shared.windows
-                .first(where: { $0.isKeyWindow })?.rootViewController
-            else { return false }
             while let presented = top.presentedViewController { top = presented }
             picker.delegate = delegate
+            picker.presentationController?.delegate = delegate
             liveDelegates.append(delegate)
             delegate.onFinish = { [weak delegate] in
                 liveDelegates.removeAll { $0 === delegate }
@@ -197,7 +248,8 @@ public final class GRPickerBridge: NSObject {
     }
 }
 
-private final class PickerDelegate: NSObject, UIDocumentPickerDelegate {
+private final class PickerDelegate: NSObject, UIDocumentPickerDelegate,
+                                    UIAdaptivePresentationControllerDelegate {
     private let onPick: ([URL]) -> Void
     var onFinish: (() -> Void)?
     init(onPick: @escaping ([URL]) -> Void) { self.onPick = onPick }
@@ -215,4 +267,18 @@ private final class PickerDelegate: NSObject, UIDocumentPickerDelegate {
         NSLog("GRPickerBridge: picker cancelled")
         onFinish?()
     }
+
+    // Swiping the sheet down calls NEITHER of the two above: since iOS 13 an
+    // interactively dismissed picker reports only through the adaptive
+    // presentation delegate. Without this the delegate is never taken out of
+    // liveDelegates, the re-present guard below then swallows every later
+    // picker while still answering true -- so Lua arms its poll and waits for
+    // a file that no sheet is ever going to produce. That is the whole of the
+    // "Import ROM does nothing until you restart the app" report: the restart
+    // is not refreshing anything, it is clearing this array.
+    func presentationControllerDidDismiss(_ presentationController:
+                                          UIPresentationController) {
+        NSLog("GRPickerBridge: picker dismissed interactively")
+        onFinish?()
+    }
 }

mobile/ios/overlays/love-ios.plist

@@ -32,7 +32,7 @@
 	<key>CFBundleInfoDictionaryVersion</key>
 	<string>6.0</string>
 	<key>CFBundleName</key>
-	<string>${PRODUCT_NAME}</string>
+	<string>gen1recomp</string>
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
@@ -44,9 +44,9 @@
 	<key>LSRequiresIPhoneOS</key>
 	<true/>
 	<key>LSSupportsOpeningDocumentsInPlace</key>
-	<false/>
+	<true/>
 	<key>UIFileSharingEnabled</key>
-	<false/>
+	<true/>
 	<key>UILaunchStoryboardName</key>
 	<string>Launch Screen</string>
 	<key>UIStatusBarHidden</key>
@@ -96,13 +96,6 @@
 			</dict>
 		</dict>
 	</array>
-	<!-- gen1recomp iOS: expose the app's Documents folder in the Files app /
-	     Finder so ROMs, mod .zips, and .sav files can be dropped in without
-	     the picker; GRBootstrap sweeps them into the LÖVE save dir. -->
-	<key>UIFileSharingEnabled</key>
-	<true/>
-	<key>LSSupportsOpeningDocumentsInPlace</key>
-	<true/>
 	<!-- gen1recomp iOS: Pokéwalker mod reads step counts (opt-in, in the
 	     in-game mod manager) and converts them to Pokémon EXP. -->
 	<key>NSHealthShareUsageDescription</key>

mobile/ios/patch_love_src.py

@@ -103,6 +103,74 @@ WRAP_REGISTRATION = """#ifdef LOVE_IOS
 	{ "pickFile", w_pickFile },
 	{ "createFile", w_createFile },
 	{ "syncHealthSteps", w_syncHealthSteps },
+	{ "httpDownload", w_httpDownload },
+#endif
+"""
+
+WRAP_SYNC_FUNCS = """
+#ifdef LOVE_IOS
+static const char *gr_saveDirectory()
+{
+	static std::string saveDirectory;
+	auto fs = Module::getInstance<love::filesystem::Filesystem>(Module::M_FILESYSTEM);
+	if (fs == nullptr)
+		return "";
+	saveDirectory = fs->getSaveDirectory();
+	return saveDirectory.c_str();
+}
+
+static int gr_callBridge(lua_State *L, const char *className,
+                         const char *selector, const char *arg)
+{
+	Class cls = objc_getClass(className);
+	if (cls == nullptr)
+	{
+		lua_pushboolean(L, 0);
+		return 1;
+	}
+	typedef signed char (*GRMsg)(Class, SEL, const char *, const char *);
+	signed char ok = ((GRMsg)objc_msgSend)(cls, sel_registerName(selector),
+	                                       arg, gr_saveDirectory());
+	lua_pushboolean(L, ok != 0);
+	return 1;
+}
+
+int w_syncHealthSteps(lua_State *L)
+{
+	return gr_callBridge(L, "GRHealthBridge", "syncStepsWithCommand:saveDir:", "sync");
+}
+#endif
+
+"""
+
+WRAP_SYNC_REGISTRATION = """#ifdef LOVE_IOS
+	{ "syncHealthSteps", w_syncHealthSteps },
+	{ "httpDownload", w_httpDownload },
+#endif
+"""
+
+BRIDGE_EXTRA_FUNCS = """
+#ifdef LOVE_IOS
+int w_httpDownload(lua_State *L)
+{
+	const char *url = luaL_checkstring(L, 1);
+	const char *destination = luaL_checkstring(L, 2);
+	const char *userAgent = luaL_optstring(L, 3, "gen1recomp");
+	const char *accept = luaL_optstring(L, 4, "");
+	Class cls = objc_getClass("GRPickerBridge");
+	if (cls == nullptr)
+	{
+		lua_pushboolean(L, 0);
+		return 1;
+	}
+	typedef signed char (*GRDownload)(Class, SEL, const char *, const char *,
+	                                  const char *, const char *);
+	signed char ok = ((GRDownload)objc_msgSend)(
+		cls, sel_registerName("httpDownloadWithUrl:destination:userAgent:accept:"),
+		url, destination, userAgent, accept);
+	lua_pushboolean(L, ok != 0);
+	return 1;
+}
 #endif
 """
 
@@ -174,14 +242,17 @@ def patch_wrap_system():
     anchor = "static const luaL_Reg functions[] ="
     if anchor not in text:
         fail(f"anchor not found in {WRAP_SYSTEM}")
-    text = text.replace(anchor, WRAP_FUNCS + anchor, 1)
+    has_native_picker = re.search(r"\bint w_pickFile\s*\(", text) is not None
+    bridge_funcs = WRAP_SYNC_FUNCS if has_native_picker else WRAP_FUNCS
+    text = text.replace(anchor, bridge_funcs + BRIDGE_EXTRA_FUNCS + anchor, 1)
     reg_anchor = '\t{ "vibrate", w_vibrate },\n'
     if reg_anchor not in text:
         fail(f"registration anchor not found in {WRAP_SYSTEM}")
-    text = text.replace(reg_anchor, reg_anchor + WRAP_REGISTRATION, 1)
+    registration = WRAP_SYNC_REGISTRATION if has_native_picker else WRAP_REGISTRATION
+    text = text.replace(reg_anchor, reg_anchor + registration, 1)
     WRAP_SYSTEM.write_text(text)
     print("patch_love_src: wrap_System.cpp patched "
-          "(pickFile/createFile/syncHealthSteps)")
+          "(pickFile/createFile/syncHealthSteps/httpDownload)")
 
 
 def patch_pbxproj():

ports/switch/ota-bootstrap/Makefile

@@ -0,0 +1,72 @@
+#---------------------------------------------------------------------------------
+# One-shot OTA bootstrap NRO (copied into the main launcher's romfs).
+#---------------------------------------------------------------------------------
+.SUFFIXES:
+
+ifeq ($(strip $(DEVKITPRO)),)
+
+.PHONY: all
+all:
+	@echo "DEVKITPRO not set — bootstrap builds with the launcher only."
+	@false
+
+else
+
+TOPDIR ?= $(CURDIR)
+include $(DEVKITPRO)/libnx/switch_rules
+
+TARGET		:=	ota-bootstrap
+BUILD		:=	build
+SOURCES		:=	.
+INCLUDES	:=	include
+ROMFS		:=
+
+APP_TITLE	:=	gen1recomp OTA
+APP_AUTHOR	:=	bryanthaboi, port by andrewqsantos
+APP_VERSION	:=	0.0.0
+
+ARCH	:=	-march=armv8-a+crc+crypto -mtune=cortex-a57 -mtp=soft -fPIE
+CFLAGS	:=	-g -Wall -O2 -ffunction-sections $(ARCH) $(DEFINES)
+CFLAGS	+=	$(INCLUDE) -D__SWITCH__
+ASFLAGS	:=	-g $(ARCH)
+LDFLAGS	=	-specs=$(DEVKITPRO)/libnx/switch.specs -g $(ARCH) -Wl,-Map,$(notdir $*.map)
+LIBS	:=	-lnx
+LIBDIRS	:= $(LIBNX)
+
+ifneq ($(BUILD),$(notdir $(CURDIR)))
+export OUTPUT	:=	$(CURDIR)/$(TARGET)
+export TOPDIR	:=	$(CURDIR)
+export VPATH	:=	$(foreach dir,$(SOURCES),$(CURDIR)/$(dir))
+export DEPSDIR	:=	$(CURDIR)/$(BUILD)
+CFILES		:=	$(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.c)))
+export LD	:=	$(CC)
+export OFILES	:=	$(CFILES:.c=.o)
+export INCLUDE	:=	$(foreach dir,$(INCLUDES),-I$(CURDIR)/$(dir)) \
+			$(foreach dir,$(LIBDIRS),-I$(dir)/include) \
+			-I$(CURDIR)/$(BUILD)
+export LIBPATHS	:=	$(foreach dir,$(LIBDIRS),-L$(dir)/lib)
+export APP_ICON := $(LIBNX)/default_icon.jpg
+export NROFLAGS += --icon=$(APP_ICON)
+export NROFLAGS += --nacp=$(CURDIR)/$(TARGET).nacp
+
+.PHONY: $(BUILD) clean all
+
+all: $(BUILD)
+
+$(BUILD):
+	@[ -d $@ ] || mkdir -p $@
+	@$(MAKE) --no-print-directory -C $(BUILD) -f $(CURDIR)/Makefile
+
+clean:
+	@echo clean ...
+	@rm -fr $(BUILD) $(TARGET).nro $(TARGET).nacp $(TARGET).elf
+
+else
+.PHONY: all
+DEPENDS	:=	$(OFILES:.o=.d)
+all: $(OUTPUT).nro
+$(OUTPUT).nro: $(OUTPUT).elf $(OUTPUT).nacp
+$(OUTPUT).elf: $(OFILES)
+-include $(DEPENDS)
+endif
+endif

ports/switch/ota-bootstrap/main.c

@@ -0,0 +1,36 @@
+/*
+ * Tiny one-shot helper: swap a staged launcher NRO into place, then load the game.
+ * The main OTA launcher chainloads here because a running NRO cannot replace itself
+ * on sdmc/FAT.
+ */
+#include <stdio.h>
+#include <string.h>
+#include <unistd.h>
+
+#if defined(__SWITCH__)
+#include <switch.h>
+#endif
+
+#define INSTALL_DIR "sdmc:/switch/gen1recomp"
+#define STAGED INSTALL_DIR "/gen1recomp.nro.staged"
+#define LAUNCHER INSTALL_DIR "/gen1recomp.nro"
+#define GAME INSTALL_DIR "/gen1recomp-game.nro"
+
+int main(int argc, char **argv) {
+  (void)argc;
+  (void)argv;
+
+#if defined(__SWITCH__)
+  remove(LAUNCHER);
+  if (rename(STAGED, LAUNCHER) != 0) {
+    return 1;
+  }
+  Result rc = envSetNextLoad(GAME, GAME);
+  if (R_FAILED(rc)) return 1;
+  return 0;
+#else
+  fprintf(stderr, "ota-bootstrap: host stub (would rename %s -> %s, load %s)\n", STAGED, LAUNCHER,
+          GAME);
+  return 0;
+#endif
+}

ports/switch/ota-launcher/Makefile

@@ -0,0 +1,193 @@
+#---------------------------------------------------------------------------------
+# gen1recomp Switch native OTA launcher
+# Requires: DEVKITPRO + switch-curl, switch-mbedtls, switch-zlib, switch-zziplib
+# Host protocol tests: make host-test (no DEVKITPRO needed)
+#---------------------------------------------------------------------------------
+.SUFFIXES:
+
+#---------------------------------------------------------------------------------
+# Host-only path when DEVKITPRO is unset
+#---------------------------------------------------------------------------------
+ifeq ($(strip $(DEVKITPRO)),)
+
+.PHONY: host-test clean-host
+host-test:
+	@mkdir -p build-host
+	cc -std=c11 -Wall -Wextra -Iinclude -o build-host/test_ota_protocol \
+		src/ota_protocol.c host/test_ota_protocol.c
+	./build-host/test_ota_protocol
+
+clean-host:
+	rm -rf build-host
+
+%:
+	@echo "DEVKITPRO not set — only 'make host-test' is available."
+	@echo "Run: bash scripts/switch/install_devkitpro_deps.sh"
+	@false
+
+else
+
+#---------------------------------------------------------------------------------
+TOPDIR ?= $(CURDIR)
+include $(DEVKITPRO)/libnx/switch_rules
+
+#---------------------------------------------------------------------------------
+TARGET		:=	gen1recomp
+BUILD		:=	build
+SOURCES		:=	src
+DATA		:=	data
+INCLUDES	:=	include
+ROMFS		:=	romfs
+
+APP_TITLE	:=	gen1recomp
+APP_AUTHOR	:=	bryanthaboi, port by andrewqsantos
+# Overridable: scripts/switch/build_ota_launcher.sh passes release X.Y.Z
+APP_VERSION	?=	0.0.0
+
+# Prefer project Switch icon if present
+ICON		:=	$(TOPDIR)/../assets/icon.jpg
+LOGO_RGBA_SRC	:=	$(TOPDIR)/../assets/logo.rgba
+LOGO_ROMFS	:=	$(CURDIR)/$(ROMFS)/logo.rgba
+
+#---------------------------------------------------------------------------------
+ARCH	:=	-march=armv8-a+crc+crypto -mtune=cortex-a57 -mtp=soft -fPIE
+
+CFLAGS	:=	-g -Wall -O2 -ffunction-sections $(ARCH) $(DEFINES)
+CFLAGS	+=	$(INCLUDE) -D__SWITCH__
+
+CXXFLAGS	:= $(CFLAGS) -fno-rtti -fno-exceptions
+
+ASFLAGS	:=	-g $(ARCH)
+LDFLAGS	=	-specs=$(DEVKITPRO)/libnx/switch.specs -g $(ARCH) -Wl,-Map,$(notdir $*.map)
+
+LIBS	:=	-lcurl -lzzip -lmbedtls -lmbedx509 -lmbedcrypto -lz -lnx
+
+LIBDIRS	:= $(PORTLIBS) $(LIBNX)
+
+#---------------------------------------------------------------------------------
+ifneq ($(BUILD),$(notdir $(CURDIR)))
+#---------------------------------------------------------------------------------
+
+export OUTPUT	:=	$(CURDIR)/$(TARGET)
+export TOPDIR	:=	$(CURDIR)
+
+export VPATH	:=	$(foreach dir,$(SOURCES),$(CURDIR)/$(dir)) \
+			$(foreach dir,$(DATA),$(CURDIR)/$(dir))
+
+export DEPSDIR	:=	$(CURDIR)/$(BUILD)
+
+CFILES		:=	$(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.c)))
+CPPFILES	:=	$(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.cpp)))
+SFILES		:=	$(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.s)))
+BINFILES	:=	$(foreach dir,$(DATA),$(notdir $(wildcard $(dir)/*.*)))
+
+#---------------------------------------------------------------------------------
+# use CXX for linking C++ projects, CC for standard C
+#---------------------------------------------------------------------------------
+ifeq ($(strip $(CPPFILES)),)
+	export LD	:=	$(CC)
+else
+	export LD	:=	$(CXX)
+endif
+#---------------------------------------------------------------------------------
+
+export OFILES_BIN	:=	$(addsuffix .o,$(BINFILES))
+export OFILES_SRC	:=	$(CPPFILES:.cpp=.o) $(CFILES:.c=.o) $(SFILES:.s=.o)
+export OFILES 	:=	$(OFILES_BIN) $(OFILES_SRC)
+
+export INCLUDE	:=	$(foreach dir,$(INCLUDES),-I$(CURDIR)/$(dir)) \
+			$(foreach dir,$(LIBDIRS),-I$(dir)/include) \
+			-I$(CURDIR)/$(BUILD)
+
+export LIBPATHS	:=	$(foreach dir,$(LIBDIRS),-L$(dir)/lib)
+
+ifeq ($(strip $(ICON)),)
+	icons := $(wildcard *.jpg)
+	ifneq (,$(findstring $(TARGET).jpg,$(icons)))
+		export APP_ICON := $(TOPDIR)/$(TARGET).jpg
+	else
+		ifneq (,$(findstring icon.jpg,$(icons)))
+			export APP_ICON := $(TOPDIR)/icon.jpg
+		endif
+	endif
+else
+	ifeq ($(wildcard $(ICON)),)
+		# fall back to libnx default if project icon missing
+		export APP_ICON := $(LIBNX)/default_icon.jpg
+	else
+		export APP_ICON := $(ICON)
+	endif
+endif
+
+ifeq ($(strip $(NO_ICON)),)
+	export NROFLAGS += --icon=$(APP_ICON)
+endif
+
+ifeq ($(strip $(NO_NACP)),)
+	export NROFLAGS += --nacp=$(CURDIR)/$(TARGET).nacp
+endif
+
+ifneq ($(ROMFS),)
+	export NROFLAGS += --romfsdir=$(CURDIR)/$(ROMFS)
+endif
+
+BOOTSTRAP_DIR	:=	$(TOPDIR)/../ota-bootstrap
+BOOTSTRAP_ROMFS	:=	$(CURDIR)/$(ROMFS)/ota-bootstrap.nro
+
+.PHONY: $(BUILD) clean all host-test sync-romfs bootstrap-romfs
+
+#---------------------------------------------------------------------------------
+all: sync-romfs $(BUILD)
+
+CACERT_URL	:=	https://curl.se/ca/cacert.pem
+CACERT_ROMFS	:=	$(CURDIR)/$(ROMFS)/cacert.pem
+
+bootstrap-romfs:
+	@$(MAKE) --no-print-directory -C $(BOOTSTRAP_DIR) all
+	@mkdir -p $(CURDIR)/$(ROMFS)
+	@cp -f $(BOOTSTRAP_DIR)/ota-bootstrap.nro $(BOOTSTRAP_ROMFS)
+
+sync-romfs: bootstrap-romfs
+	@mkdir -p $(CURDIR)/$(ROMFS)
+	@[ -f "$(LOGO_RGBA_SRC)" ] || (echo "missing $(LOGO_RGBA_SRC) — run: python3 scripts/switch/bake_ota_logo.py" && exit 1)
+	@cp -f "$(LOGO_RGBA_SRC)" "$(LOGO_ROMFS)"
+	@if ! curl -sfL --time-cond $(CACERT_ROMFS) -o $(CACERT_ROMFS) $(CACERT_URL); then \
+		[ -f $(CACERT_ROMFS) ] || (echo "sync-romfs: failed to fetch cacert.pem" && exit 1); \
+	fi
+
+$(BUILD): sync-romfs
+	@[ -d $@ ] || mkdir -p $@
+	@$(MAKE) --no-print-directory -C $(BUILD) -f $(CURDIR)/Makefile
+
+#---------------------------------------------------------------------------------
+clean:
+	@echo clean ...
+	@$(MAKE) --no-print-directory -C $(BOOTSTRAP_DIR) clean || true
+	@rm -fr $(BUILD) $(TARGET).nro $(TARGET).nacp $(TARGET).elf $(TARGET).lst build-host
+	@rm -f $(CURDIR)/$(ROMFS)/logo.rgba $(CURDIR)/$(ROMFS)/logo.png
+
+host-test:
+	@mkdir -p build-host
+	cc -std=c11 -Wall -Wextra -Iinclude -o build-host/test_ota_protocol \
+		src/ota_protocol.c host/test_ota_protocol.c
+	./build-host/test_ota_protocol
+
+#---------------------------------------------------------------------------------
+else
+.PHONY: all
+
+DEPENDS	:=	$(OFILES:.o=.d)
+
+#---------------------------------------------------------------------------------
+all: $(OUTPUT).nro
+
+$(OUTPUT).nro: $(OUTPUT).elf $(OUTPUT).nacp
+
+$(OUTPUT).elf: $(OFILES)
+
+-include $(DEPENDS)
+
+#---------------------------------------------------------------------------------
+endif
+#---------------------------------------------------------------------------------
+endif

ports/switch/ota-launcher/README.md

@@ -0,0 +1,89 @@
+# Native Switch OTA launcher
+
+In-console updates for Gen1Recomp on Nintendo Switch. This NRO is the **hbmenu
+entry** (`gen1recomp.nro`). It checks GitHub Releases quietly (no UI when you
+are already up to date or offline). Only if a newer release exists does it show
+a **launcher-style screen** (black + RGB rail + project logo + flat A/B
+buttons), download the same `gen1recomp-*-switch.zip` used for install, verify
+SHA-256 from `sha256sums.txt`, replace **both** `gen1recomp-game.nro` and
+`gen1recomp.nro` (matching NACP version for hbmenu/Sphaira), then load the game
+with `envSetNextLoad`.
+
+The LÖVE self-updater (`src/update/Check.lua`) stays **disabled** on NX.
+Wire format (also in Lua): `src/update/SwitchOta.lua`.
+NACP icon: `ports/switch/assets/icon.jpg`.
+
+## Layout on microSD
+
+```text
+sdmc:/switch/gen1recomp/gen1recomp.nro        <- this launcher
+sdmc:/switch/gen1recomp/gen1recomp-game.nro   <- fused LÖVE game
+sdmc:/switch/gen1recomp/version.txt          <- installed X.Y.Z
+sdmc:/switch/gen1recomp/pokemon-love2d/      <- saves (never touched by OTA)
+```
+
+## Host tests (no DEVKITPRO)
+
+```bash
+cd ports/switch/ota-launcher
+make host-test
+```
+
+## Switch build (DEVKITPRO)
+
+Needs `DEVKITPRO` with packages roughly:
+
+```bash
+(dkp-)pacman -S --needed switch-curl switch-mbedtls switch-zlib switch-zziplib
+# or: bash scripts/switch/install_devkitpro_deps.sh
+```
+
+```bash
+export DEVKITPRO=/opt/devkitpro   # typical
+cd ports/switch/ota-launcher
+make
+# -> gen1recomp.nro
+```
+
+Or from repo root (as part of `--fused`):
+
+```bash
+scripts/build_switch.sh --fetch --fused --version X.Y.Z
+```
+
+Standalone launcher build:
+
+```bash
+scripts/switch/build_ota_launcher.sh
+```
+
+Docker fallback uses the same pin as fused builds (`scripts/switch/dkp-docker.image`).
+
+## OTA logo asset
+
+The launcher draws a pre-scaled logo from `romfs:/logo.rgba` (no PNG decoder in
+the NRO). The baked blob lives at `../assets/logo.rgba` and is copied into romfs at
+build time. After changing `assets/logo/logo.png`, regenerate:
+
+```bash
+python3 scripts/switch/bake_ota_logo.py
+```
+
+Requires Pillow, or on macOS uses `sips` when Pillow is not installed.
+
+## Packaging
+
+`scripts/switch/pack_sd_zip.sh GAME_NRO VERSION OUT_ZIP LAUNCHER_NRO` writes both
+NROs into the SD zip. That zip is also what OTA downloads.
+Manifest: `scripts/switch/ota_launcher.manifest`.
+
+## Status / known gaps
+
+- Zip extraction uses `switch-zziplib` (`ota_unzip.c`) on device.
+- OTA replaces game + launcher from the install zip (NACP versions stay aligned).
+  The running launcher cannot overwrite its own NRO on sdmc/FAT; a tiny
+  `ota-bootstrap.nro` (embedded in romfs) chainloads once to swap the staged
+  launcher, then loads the game.
+- HTTPS uses Mozilla CA bundle in romfs (`cacert.pem`, fetched at build time). `ota_net_init()` mounts romfs before the quiet release check.
+- Sphaira HOME forwarders cache metadata until reinstalled (see docs/switch-install.md).
+- Release runner: `switch-dev` + (`install_devkitpro_deps.sh` **or** Docker)

ports/switch/ota-launcher/host/test_ota_protocol.c

@@ -0,0 +1,144 @@
+/* Host-only unit tests for ota_protocol.c — no libnx. */
+#include "ota_protocol.h"
+
+#include <stdio.h>
+#include <string.h>
+
+static int g_fail = 0;
+
+static void expect(int cond, const char *msg) {
+  if (!cond) {
+    fprintf(stderr, "FAIL: %s\n", msg);
+    g_fail++;
+  } else {
+    printf("PASS: %s\n", msg);
+  }
+}
+
+int main(void) {
+  expect(ota_compare_semver("1.2.0", "1.1.0") == 1, "semver newer");
+  expect(ota_compare_semver("1.1.0", "1.1.0") == 0, "semver equal");
+  expect(ota_compare_semver("1.0.0", "1.1.0") == -1, "semver older");
+  expect(ota_is_ota_asset_name("gen1recomp-1.5.0-switch.zip"), "ota asset name");
+  expect(!ota_is_ota_asset_name("gen1recomp-1.5.0-switch-ota.zip"), "reject legacy ota zip name");
+  expect(!ota_is_ota_asset_name("gen1recomp-1.5.0.love"), "reject love payload");
+
+  const char *json =
+      "{"
+      "\"tag_name\":\"v1.5.0\","
+      "\"assets\":["
+      "{\"name\":\"gen1recomp-1.5.0-switch.zip\","
+      "\"browser_download_url\":\"https://example/switch.zip\"},"
+      "{\"name\":\"sha256sums.txt\",\"browser_download_url\":\"https://example/sums\"}"
+      "]"
+      "}";
+  ota_release_t rel;
+  expect(ota_parse_release(json, &rel) == 1, "parse release");
+  expect(strcmp(rel.version, "1.5.0") == 0, "release version");
+  expect(strcmp(rel.asset_name, "gen1recomp-1.5.0-switch.zip") == 0, "release asset");
+
+  ota_decision_t d;
+  ota_decide_update("1.4.0", &rel, &d);
+  expect(strcmp(d.status, "available") == 0, "decide available");
+  ota_decide_update("1.5.0", &rel, &d);
+  expect(strcmp(d.status, "uptodate") == 0, "decide uptodate");
+
+  ota_release_t bad;
+  expect(ota_parse_release("{\"tag_name\":\"v1.5.0\",\"assets\":[]}", &bad) == 0,
+         "missing ota asset");
+  expect(strcmp(bad.reason, "missing_ota_asset") == 0, "missing_ota_asset reason");
+
+  /* GitHub releases/latest shape: release-level name + fat uploader before browser_download_url. */
+  const char *github_json =
+      "{"
+      "\"tag_name\":\"v0.1.70\","
+      "\"name\":\"0.1.70\","
+      "\"assets\":["
+      "{"
+      "\"url\":\"https://api.github.com/repos/bryanthaboi/gen1recomp/releases/assets/502823880\","
+      "\"id\":502823880,"
+      "\"name\":\"gen1recomp-0.1.70-switch.zip\","
+      "\"label\":\"\","
+      "\"uploader\":{"
+      "\"login\":\"github-actions[bot]\","
+      "\"id\":41898282,"
+      "\"node_id\":\"MDM6Qm90NDE4OTgyODI=\","
+      "\"avatar_url\":\"https://avatars.githubusercontent.com/in/15368?v=4\","
+      "\"gravatar_id\":\"\","
+      "\"url\":\"https://api.github.com/users/github-actions%5Bbot%5D\","
+      "\"html_url\":\"https://github.com/apps/github-actions\","
+      "\"followers_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/followers\","
+      "\"following_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/following{/other_user}\","
+      "\"gists_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/gists{/gist_id}\","
+      "\"starred_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/starred{/owner}{/repo}\","
+      "\"subscriptions_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/subscriptions\","
+      "\"organizations_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/orgs\","
+      "\"repos_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/repos\","
+      "\"events_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/events{/privacy}\","
+      "\"received_events_url\":\"https://api.github.com/users/github-actions%5Bbot%5D/received_events\","
+      "\"type\":\"Bot\","
+      "\"user_view_type\":\"public\","
+      "\"site_admin\":false"
+      "},"
+      "\"content_type\":\"application/zip\","
+      "\"state\":\"uploaded\","
+      "\"size\":9000573,"
+      "\"browser_download_url\":\"https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.70/gen1recomp-0.1.70-switch.zip\""
+      "}"
+      "]"
+      "}";
+  ota_release_t gh;
+  expect(ota_parse_release(github_json, &gh) == 1, "parse github-shaped release");
+  expect(strcmp(gh.version, "0.1.70") == 0, "github release version");
+  expect(strcmp(gh.asset_name, "gen1recomp-0.1.70-switch.zip") == 0, "github release asset");
+  expect(strcmp(gh.download_url,
+                 "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.70/gen1recomp-0.1.70-switch.zip") ==
+             0,
+         "github release download url");
+  ota_decide_update("0.1.69", &gh, &d);
+  expect(strcmp(d.status, "available") == 0, "github release decide 0.1.69->0.1.70");
+
+  const char *sums = "abc123  gen1recomp-1.5.0-switch.zip\n";
+  ota_verify_t v;
+  ota_verify_sha256("gen1recomp-1.5.0-switch.zip", "abc123", sums, &v);
+  expect(v.ok == 1, "sha ok");
+  ota_verify_sha256("gen1recomp-1.5.0-switch.zip", "deadbeef", sums, &v);
+  expect(v.ok == 0 && strcmp(v.reason, "hash_mismatch") == 0, "sha mismatch");
+  ota_verify_sha256("gen1recomp-1.5.0-switch.zip", "abc123", "", &v);
+  expect(v.ok == 0 && strcmp(v.reason, "sum_not_found") == 0, "sha missing sum rejected");
+
+  ota_apply_plan_t plan;
+  ota_plan_atomic_apply("switch/gen1recomp", "/tmp/x", &plan);
+  expect(strstr(plan.steps[0], "copy_to_part:") != NULL, "plan copy");
+  expect(strstr(plan.steps[1], "rename:") != NULL, "plan rename");
+  expect(strstr(plan.steps[2], "copy_to_part:launcher") != NULL, "plan launcher copy");
+  expect(strstr(plan.steps[3], "rename:") != NULL, "plan launcher rename");
+  expect(strstr(plan.steps[4], "env_set_next_load:") != NULL, "plan handoff");
+  expect(strstr(plan.preserve, "pokemon-love2d") != NULL, "preserve saves");
+  expect(strstr(plan.forbidden_delete, "delete:") != NULL, "forbid delete saves");
+  expect(strstr(plan.forbidden_direct, "write_direct:") != NULL, "forbid direct write");
+
+  ota_offline_t off;
+  ota_offline_events_t ev = {0};
+  ev.user_skip = 1;
+  ota_offline_policy(1.0, &ev, &off);
+  expect(strcmp(off.action, "play_installed") == 0, "skip plays installed");
+  ev.user_skip = 0;
+  ev.network_ok = 0;
+  ota_offline_policy(1.0, &ev, &off);
+  expect(strcmp(off.action, "play_installed") == 0, "offline plays installed");
+  ev.network_ok = 1;
+  ota_offline_policy(6.0, &ev, &off);
+  expect(strcmp(off.reason, "timeout") == 0, "timeout 6s");
+  ota_offline_policy(2.0, &ev, &off);
+  expect(strcmp(off.action, "keep_checking") == 0, "still checking");
+
+  expect(OTA_CHECK_TIMEOUT_SEC == 6, "timeout constant 6");
+
+  if (g_fail) {
+    fprintf(stderr, "%d failure(s)\n", g_fail);
+    return 1;
+  }
+  printf("all ota_protocol host tests passed\n");
+  return 0;
+}

ports/switch/ota-launcher/include/ota_fs.h

@@ -0,0 +1,38 @@
+#ifndef GEN1_OTA_FS_H
+#define GEN1_OTA_FS_H
+
+#include "ota_protocol.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Read installed game version from sibling version.txt or NRO nacp-less stamp file.
+ * Expects switch/gen1recomp/version.txt containing X.Y.Z. Returns 0 on success. */
+int ota_fs_read_installed_version(const char *install_dir, char *out, size_t out_len);
+
+/* SHA-256 hex (lowercase) of file. Returns 0 on success. */
+int ota_fs_sha256_file(const char *path, char *out_hex, size_t out_len);
+
+/* Apply verified temp payload (extracted game NRO) using atomic plan. Returns 0 on success. */
+int ota_fs_atomic_replace_game(const char *install_dir, const char *verified_game_nro,
+                               char *err, size_t err_len);
+
+/* Atomically replace any named NRO under install_dir (copy→.part→rename). */
+int ota_fs_atomic_replace_nro(const char *install_dir, const char *nro_name,
+                              const char *verified_nro, char *err, size_t err_len);
+
+/* Stage a new launcher + copy romfs bootstrap; chainload bootstrap_out next.
+ * The running launcher cannot replace its own NRO on sdmc/FAT. */
+int ota_fs_stage_launcher_bootstrap(const char *install_dir, const char *verified_launcher,
+                                    char *bootstrap_out, size_t bootstrap_out_len, char *err,
+                                    size_t err_len);
+
+/* Hand off to game NRO via envSetNextLoad (Switch) or no-op stub (host). */
+int ota_fs_handoff_to_game(const char *game_nro_path, char *err, size_t err_len);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

ports/switch/ota-launcher/include/ota_net.h

@@ -0,0 +1,29 @@
+#ifndef GEN1_OTA_NET_H
+#define GEN1_OTA_NET_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* fraction is 0..1 when Content-Length is known, else -1 for indeterminate. */
+typedef void (*ota_net_progress_fn)(void *userdata, double fraction);
+
+/* Mount romfs (CA bundle) and init libcurl. Call before any HTTPS download. */
+int ota_net_init(void);
+void ota_net_shutdown(void);
+
+/* Download URL into memory buffer (caller frees *out). Returns 0 on success. */
+int ota_net_download_buffer(const char *url, long timeout_ms, char **out, size_t *out_len,
+                            char *err, size_t err_len);
+
+/* Download URL to a filesystem path. progress may be NULL. Returns 0 on success. */
+int ota_net_download_file(const char *url, const char *path, long timeout_ms, char *err,
+                          size_t err_len, ota_net_progress_fn progress, void *progress_ud);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

ports/switch/ota-launcher/include/ota_protocol.h

@@ -0,0 +1,95 @@
+#ifndef GEN1_OTA_PROTOCOL_H
+#define GEN1_OTA_PROTOCOL_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define OTA_CHECK_TIMEOUT_SEC 6
+#define OTA_GAME_NRO_NAME "gen1recomp-game.nro"
+#define OTA_LAUNCHER_NRO_NAME "gen1recomp.nro"
+#define OTA_SAVE_DIR_NAME "pokemon-love2d"
+#define OTA_INSTALL_DIR "switch/gen1recomp"
+#define OTA_LAUNCHER_STAGED_SUFFIX ".staged"
+#define OTA_BOOTSTRAP_ROMFS "romfs:/ota-bootstrap.nro"
+#define OTA_BOOTSTRAP_SD_NAME "ota-bootstrap.nro"
+#define OTA_RELEASES_API \
+  "https://api.github.com/repos/bryanthaboi/gen1recomp/releases/latest"
+
+/* Mirrors src/update/SwitchOta.lua — keep semantics in lockstep. */
+
+int ota_compare_semver(const char *a, const char *b);
+int ota_is_ota_asset_name(const char *name);
+int ota_version_from_ota_asset(const char *name, char *out, size_t out_len);
+
+typedef struct {
+  int ok; /* 1 on success */
+  char reason[64];
+  char tag[64];
+  char version[32];
+  char asset_name[128];
+  char download_url[512];
+} ota_release_t;
+
+int ota_parse_release(const char *json_text, ota_release_t *out);
+
+typedef struct {
+  char status[32]; /* uptodate | available | error */
+  char reason[64];
+  char version[32];
+  char asset_name[128];
+  char download_url[512];
+} ota_decision_t;
+
+void ota_decide_update(const char *installed_version, const ota_release_t *release,
+                       ota_decision_t *out);
+
+/* sums: newline-separated sha256sums.txt body */
+int ota_lookup_sum(const char *sums_text, const char *asset_name, char *out_hex,
+                   size_t out_len);
+
+typedef struct {
+  int ok;
+  char reason[64];
+} ota_verify_t;
+
+void ota_verify_sha256(const char *asset_name, const char *actual_hex,
+                       const char *sums_text, ota_verify_t *out);
+
+typedef struct {
+  char steps[5][520]; /* human-readable ops */
+  char preserve[256];
+  char forbidden_delete[256];
+  char forbidden_direct[256];
+  char part_path[256];
+  char game_nro[240];
+  char launcher_nro[240];
+  char launcher_part[256];
+  char next_load[240];
+} ota_apply_plan_t;
+
+void ota_plan_atomic_apply(const char *install_dir, const char *verified_temp,
+                           ota_apply_plan_t *out);
+
+typedef struct {
+  char action[32]; /* play_installed | keep_checking */
+  char reason[64];
+  char message[128];
+} ota_offline_t;
+
+typedef struct {
+  int user_skip;
+  int network_ok; /* 0 = offline/fail, 1 = ok, -1 = unknown */
+  int api_error;
+} ota_offline_events_t;
+
+void ota_offline_policy(double elapsed_sec, const ota_offline_events_t *events,
+                        ota_offline_t *out);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* GEN1_OTA_PROTOCOL_H */

ports/switch/ota-launcher/include/ota_ui.h

@@ -0,0 +1,37 @@
+#ifndef GEN1_OTA_UI_H
+#define GEN1_OTA_UI_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Framebuffer UI matching the in-game launcher look (black + RGB rail +
+ * flat semantic buttons). Silent by default — only call when user-facing. */
+
+/* Returns 1 = update, 0 = skip / play installed. */
+int ota_ui_prompt_update(const char *installed, const char *latest);
+
+/* Status screen (download / install). Redraws each call. */
+void ota_ui_show_status(const char *title, const char *detail);
+
+/* Progress 0..1; detail optional. */
+void ota_ui_show_progress(const char *title, const char *detail, float progress01);
+
+/* Error / info + wait for B. */
+void ota_ui_alert(const char *title, const char *line1, const char *line2);
+
+/* User-friendly error with optional technical detail and installed-version footer. */
+void ota_ui_alert_error(const char *title, const char *friendly, const char *technical,
+                        const char *installed_version);
+
+/* Missing game install screen; wait for +. */
+void ota_ui_missing_game(void);
+
+/* Tear down framebuffer if active. Safe to call when UI never opened. */
+void ota_ui_shutdown(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

ports/switch/ota-launcher/include/ota_unzip.h

@@ -0,0 +1,20 @@
+#ifndef GEN1_OTA_UNZIP_H
+#define GEN1_OTA_UNZIP_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Extract member_name from zip_path into dest_path.
+ * Tries exact member_name, then common prefixes (switch/gen1recomp/).
+ * Returns 0 on success. */
+int ota_unzip_extract_file(const char *zip_path, const char *member_name, const char *dest_path,
+                           char *err, size_t err_len);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

ports/switch/ota-launcher/src/main.c

@@ -0,0 +1,281 @@
+/*
+ * gen1recomp Switch OTA launcher
+ *
+ * Quiet by default: checks GitHub Releases with no UI. Only shows the
+ * branded launcher-style screen when an update is available. Downloads the
+ * same SD zip (gen1recomp-*-switch.zip), verifies SHA-256, replaces game +
+ * launcher NROs, then envSetNextLoad. Never touches pokemon-love2d/.
+ * LÖVE self-updater stays off on NX.
+ */
+
+#include "ota_fs.h"
+#include "ota_net.h"
+#include "ota_protocol.h"
+#include "ota_ui.h"
+#include "ota_unzip.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#if defined(__SWITCH__)
+#include <sys/stat.h>
+#include <switch.h>
+#include <unistd.h>
+#else
+#include <sys/stat.h>
+#include <unistd.h>
+#endif
+
+#define SD_INSTALL_DIR "sdmc:/switch/gen1recomp"
+#define CHECK_TIMEOUT_MS (OTA_CHECK_TIMEOUT_SEC * 1000L)
+#define GAME_MEMBER_IN_ZIP "switch/gen1recomp/" OTA_GAME_NRO_NAME
+#define LAUNCHER_MEMBER_IN_ZIP "switch/gen1recomp/" OTA_LAUNCHER_NRO_NAME
+
+typedef struct {
+  const char *detail;
+  float base;
+  float span;
+} download_progress_ctx_t;
+
+static void on_download_progress(void *userdata, double fraction) {
+  download_progress_ctx_t *ctx = (download_progress_ctx_t *)userdata;
+  if (!ctx) return;
+  float p = ctx->base;
+  if (fraction >= 0.0) p += ctx->span * (float)fraction;
+  else p += ctx->span * 0.1f;
+  if (p > ctx->base + ctx->span) p = ctx->base + ctx->span;
+  ota_ui_show_progress("Step 1/3: Downloading...", ctx->detail, p);
+}
+
+static void show_update_error(const char *title, const char *friendly, const char *technical,
+                              const char *installed) {
+  ota_ui_alert_error(title, friendly, technical, installed);
+}
+
+static int run_update_flow(const char *install_dir) {
+  char installed[64] = "0.0.0";
+  (void)ota_fs_read_installed_version(install_dir, installed, sizeof(installed));
+
+  char *json = NULL;
+  size_t json_len = 0;
+  char err[256];
+  err[0] = '\0';
+
+  if (ota_net_download_buffer(OTA_RELEASES_API, CHECK_TIMEOUT_MS, &json, &json_len, err,
+                              sizeof(err)) != 0) {
+    free(json);
+    return 0; /* offline / timeout — play installed, no UI */
+  }
+
+  ota_release_t rel;
+  if (!ota_parse_release(json, &rel)) {
+    free(json);
+    return 0;
+  }
+  free(json);
+
+  ota_decision_t dec;
+  ota_decide_update(installed, &rel, &dec);
+  if (strcmp(dec.status, "uptodate") == 0 || strcmp(dec.status, "error") == 0) {
+    return 0;
+  }
+
+  if (!ota_ui_prompt_update(installed, dec.version)) {
+    return 0;
+  }
+
+  char updates_dir[192];
+  char zip_path[256];
+  char sums_path[256];
+  snprintf(updates_dir, sizeof(updates_dir), "%s/updates", install_dir);
+  snprintf(zip_path, sizeof(zip_path), "%s/updates/%s", install_dir, dec.asset_name);
+  snprintf(sums_path, sizeof(sums_path), "%s/updates/sha256sums.txt", install_dir);
+
+#if defined(__SWITCH__)
+  mkdir(updates_dir, 0755);
+#endif
+
+  download_progress_ctx_t dl_ctx = {"This may take a minute.", 0.f, 0.5f};
+  ota_ui_show_progress("Step 1/3: Downloading...", dl_ctx.detail, dl_ctx.base);
+  if (ota_net_download_file(dec.download_url, zip_path, 180000L, err, sizeof(err),
+                              on_download_progress, &dl_ctx) != 0) {
+    show_update_error("Download failed",
+                      "Could not download the update. Check Wi-Fi and try again.", err, installed);
+    return 0;
+  }
+
+  ota_ui_show_progress("Step 2/3: Verifying...", "Checking file integrity.", 0.55f);
+  char sums_url[512];
+  snprintf(sums_url, sizeof(sums_url),
+           "https://github.com/bryanthaboi/gen1recomp/releases/download/%s/sha256sums.txt",
+           rel.tag);
+  if (ota_net_download_file(sums_url, sums_path, CHECK_TIMEOUT_MS, err, sizeof(err), NULL,
+                            NULL) != 0) {
+    remove(zip_path);
+    show_update_error("Could not verify", "Downloaded file could not be checked.", err, installed);
+    return 0;
+  }
+
+  FILE *sf = fopen(sums_path, "rb");
+  if (!sf) {
+    remove(zip_path);
+    show_update_error("Could not verify", "Could not read checksum file.", "fopen sums failed",
+                      installed);
+    return 0;
+  }
+  fseek(sf, 0, SEEK_END);
+  long slen = ftell(sf);
+  fseek(sf, 0, SEEK_SET);
+  char *sums = (char *)malloc((size_t)slen + 1);
+  if (!sums) {
+    fclose(sf);
+    remove(zip_path);
+    show_update_error("Could not verify", "Not enough memory to verify update.", "malloc failed",
+                      installed);
+    return 0;
+  }
+  fread(sums, 1, (size_t)slen, sf);
+  sums[slen] = '\0';
+  fclose(sf);
+
+  ota_ui_show_progress("Step 2/3: Verifying...", "Computing checksum...", 0.65f);
+  char hex[96];
+  if (ota_fs_sha256_file(zip_path, hex, sizeof(hex)) != 0) {
+    free(sums);
+    remove(zip_path);
+    show_update_error("Could not verify", "Could not read downloaded update file.",
+                      "sha256 file read failed", installed);
+    return 0;
+  }
+  ota_verify_t ver;
+  ota_verify_sha256(dec.asset_name, hex, sums, &ver);
+  free(sums);
+  if (!ver.ok) {
+    remove(zip_path);
+    show_update_error("Update check failed",
+                      "Downloaded file did not match expected checksum.", ver.reason, installed);
+    return 0;
+  }
+
+  char extracted[256];
+  char extracted_launcher[256];
+  snprintf(extracted, sizeof(extracted), "%s/updates/gen1recomp-game.nro.verified", install_dir);
+  snprintf(extracted_launcher, sizeof(extracted_launcher), "%s/updates/gen1recomp.nro.verified",
+           install_dir);
+
+#if defined(__SWITCH__)
+  ota_ui_show_progress("Step 3/3: Installing...", "Keeping your saves safe.", 0.8f);
+  if (ota_unzip_extract_file(zip_path, GAME_MEMBER_IN_ZIP, extracted, err, sizeof(err)) != 0) {
+    if (ota_unzip_extract_file(zip_path, OTA_GAME_NRO_NAME, extracted, err, sizeof(err)) != 0) {
+      remove(zip_path);
+      show_update_error("Could not extract",
+                        "Update zip is missing game files or is corrupted.", err, installed);
+      return 0;
+    }
+  }
+
+  if (ota_fs_atomic_replace_game(install_dir, extracted, err, sizeof(err)) != 0) {
+    remove(extracted);
+    remove(zip_path);
+    show_update_error("Could not install",
+                      "Could not replace game on microSD. Free up space and try again.", err,
+                      installed);
+    return 0;
+  }
+  remove(extracted);
+
+  int have_launcher = 0;
+  if (ota_unzip_extract_file(zip_path, LAUNCHER_MEMBER_IN_ZIP, extracted_launcher, err,
+                             sizeof(err)) == 0 ||
+      ota_unzip_extract_file(zip_path, OTA_LAUNCHER_NRO_NAME, extracted_launcher, err,
+                             sizeof(err)) == 0) {
+    have_launcher = 1;
+  }
+  if (!have_launcher) {
+    remove(zip_path);
+    show_update_error("Could not extract",
+                      "Update zip is missing launcher files.", err, installed);
+    return 0;
+  }
+
+  char bootstrap_path[256];
+  bootstrap_path[0] = '\0';
+  if (ota_fs_stage_launcher_bootstrap(install_dir, extracted_launcher, bootstrap_path,
+                                      sizeof(bootstrap_path), err, sizeof(err)) != 0) {
+    remove(extracted_launcher);
+    remove(zip_path);
+    show_update_error("Could not install",
+                      "Game updated but launcher could not be staged. Reinstall from the SD zip.",
+                      err, installed);
+    return 0;
+  }
+  remove(extracted_launcher);
+
+  char vpath[192];
+  snprintf(vpath, sizeof(vpath), "%s/version.txt", install_dir);
+  FILE *vf = fopen(vpath, "wb");
+  if (vf) {
+    fprintf(vf, "%s\n", dec.version);
+    fclose(vf);
+  }
+
+  ota_ui_show_progress("Ready", "Finishing update...", 1.0f);
+  svcSleepThread(600000000ULL);
+  remove(zip_path);
+  ota_ui_shutdown();
+
+  if (ota_fs_handoff_to_game(bootstrap_path, err, sizeof(err)) != 0) {
+    show_update_error("Could not install", "Launcher bootstrap failed.", err, installed);
+    return 0;
+  }
+  return 2; /* chainload bootstrap; main must not hand off to game */
+#else
+  (void)extracted;
+  (void)extracted_launcher;
+#endif
+  remove(zip_path);
+  ota_ui_shutdown();
+  return 0;
+}
+
+int main(int argc, char **argv) {
+  (void)argc;
+  (void)argv;
+
+  const char *install = SD_INSTALL_DIR;
+  int update_rc = 0;
+
+#if defined(__SWITCH__)
+  socketInitializeDefault();
+  padConfigureInput(1, HidNpadStyleSet_NpadStandard);
+  if (ota_net_init() == 0) {
+    update_rc = run_update_flow(install);
+    ota_net_shutdown();
+  }
+#else
+  update_rc = run_update_flow(install);
+#endif
+
+  if (update_rc == 2) {
+#if defined(__SWITCH__)
+    socketExit();
+#endif
+    return 0;
+  }
+
+  char game[192];
+  snprintf(game, sizeof(game), "%s/%s", install, OTA_GAME_NRO_NAME);
+  char err[128];
+  err[0] = '\0';
+  if (ota_fs_handoff_to_game(game, err, sizeof(err)) != 0) {
+    ota_ui_missing_game();
+  }
+
+  ota_ui_shutdown();
+
+#if defined(__SWITCH__)
+  socketExit();
+#endif
+  return 0;
+}

ports/switch/ota-launcher/src/ota_fs.c

@@ -0,0 +1,177 @@
+#include "ota_fs.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#if defined(__SWITCH__)
+#include <switch.h>
+#include <mbedtls/sha256.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#else
+#include <unistd.h>
+#endif
+
+int ota_fs_read_installed_version(const char *install_dir, char *out, size_t out_len) {
+  if (!out || out_len == 0) return -1;
+  out[0] = '\0';
+  char path[256];
+  snprintf(path, sizeof(path), "%s/version.txt", install_dir ? install_dir : OTA_INSTALL_DIR);
+  FILE *fp = fopen(path, "rb");
+  if (!fp) return -1;
+  if (!fgets(out, (int)out_len, fp)) {
+    fclose(fp);
+    return -1;
+  }
+  fclose(fp);
+  /* trim */
+  size_t n = strlen(out);
+  while (n > 0 && (out[n - 1] == '\n' || out[n - 1] == '\r' || out[n - 1] == ' ')) {
+    out[--n] = '\0';
+  }
+  return n > 0 ? 0 : -1;
+}
+
+int ota_fs_sha256_file(const char *path, char *out_hex, size_t out_len) {
+  if (!path || !out_hex || out_len < 65) return -1;
+  out_hex[0] = '\0';
+  FILE *fp = fopen(path, "rb");
+  if (!fp) return -1;
+
+#if defined(__SWITCH__)
+  mbedtls_sha256_context ctx;
+  mbedtls_sha256_init(&ctx);
+  mbedtls_sha256_starts(&ctx, 0);
+  unsigned char buf[8192];
+  size_t n;
+  while ((n = fread(buf, 1, sizeof(buf), fp)) > 0) {
+    mbedtls_sha256_update(&ctx, buf, n);
+  }
+  fclose(fp);
+  unsigned char digest[32];
+  mbedtls_sha256_finish(&ctx, digest);
+  mbedtls_sha256_free(&ctx);
+  for (int i = 0; i < 32; i++) snprintf(out_hex + i * 2, out_len - (size_t)(i * 2), "%02x", digest[i]);
+  return 0;
+#else
+  /* Host: shell out to shasum/sha256sum for the host test path if needed.
+   * Protocol host tests do not call this; return not-implemented. */
+  fclose(fp);
+  (void)out_len;
+  return -1;
+#endif
+}
+
+static int copy_file(const char *from, const char *to) {
+  FILE *in = fopen(from, "rb");
+  if (!in) return -1;
+  FILE *out = fopen(to, "wb");
+  if (!out) {
+    fclose(in);
+    return -1;
+  }
+  char buf[8192];
+  size_t n;
+  while ((n = fread(buf, 1, sizeof(buf), in)) > 0) {
+    if (fwrite(buf, 1, n, out) != n) {
+      fclose(in);
+      fclose(out);
+      return -1;
+    }
+  }
+  fclose(in);
+  fclose(out);
+  return 0;
+}
+
+int ota_fs_atomic_replace_game(const char *install_dir, const char *verified_game_nro,
+                               char *err, size_t err_len) {
+  return ota_fs_atomic_replace_nro(install_dir, OTA_GAME_NRO_NAME, verified_game_nro, err,
+                                   err_len);
+}
+
+int ota_fs_atomic_replace_nro(const char *install_dir, const char *nro_name,
+                              const char *verified_nro, char *err, size_t err_len) {
+  if (!nro_name || !*nro_name || !verified_nro || !*verified_nro) {
+    if (err && err_len) snprintf(err, err_len, "missing nro paths");
+    return -1;
+  }
+  char dest[240];
+  char part[256];
+  snprintf(dest, sizeof(dest), "%s/%s", install_dir ? install_dir : OTA_INSTALL_DIR, nro_name);
+  snprintf(part, sizeof(part), "%s.part", dest);
+  if (copy_file(verified_nro, part) != 0) {
+    if (err && err_len) snprintf(err, err_len, "copy to .part failed (%s)", nro_name);
+    return -1;
+  }
+  /* sdmc/FAT (Switch) and Windows do not replace an existing dest on rename. */
+  remove(dest);
+  if (rename(part, dest) != 0) {
+    if (err && err_len) snprintf(err, err_len, "rename .part -> %s failed", nro_name);
+    remove(part);
+    return -1;
+  }
+  return 0;
+}
+
+int ota_fs_stage_launcher_bootstrap(const char *install_dir, const char *verified_launcher,
+                                    char *bootstrap_out, size_t bootstrap_out_len, char *err,
+                                    size_t err_len) {
+  if (!verified_launcher || !*verified_launcher) {
+    if (err && err_len) snprintf(err, err_len, "missing staged launcher path");
+    return -1;
+  }
+  if (!bootstrap_out || bootstrap_out_len == 0) {
+    if (err && err_len) snprintf(err, err_len, "missing bootstrap output buffer");
+    return -1;
+  }
+  bootstrap_out[0] = '\0';
+
+  const char *base = install_dir ? install_dir : OTA_INSTALL_DIR;
+  char staged[256];
+  char bootstrap[256];
+  char updates[192];
+  snprintf(staged, sizeof(staged), "%s/%s%s", base, OTA_LAUNCHER_NRO_NAME,
+           OTA_LAUNCHER_STAGED_SUFFIX);
+  snprintf(updates, sizeof(updates), "%s/updates", base);
+  snprintf(bootstrap, sizeof(bootstrap), "%s/updates/%s", base, OTA_BOOTSTRAP_SD_NAME);
+
+  remove(staged);
+  if (copy_file(verified_launcher, staged) != 0) {
+    if (err && err_len) snprintf(err, err_len, "stage launcher failed");
+    return -1;
+  }
+
+#if defined(__SWITCH__)
+  mkdir(updates, 0755);
+#endif
+  if (copy_file(OTA_BOOTSTRAP_ROMFS, bootstrap) != 0) {
+    remove(staged);
+    if (err && err_len) snprintf(err, err_len, "extract bootstrap failed");
+    return -1;
+  }
+
+  snprintf(bootstrap_out, bootstrap_out_len, "%s", bootstrap);
+  return 0;
+}
+
+int ota_fs_handoff_to_game(const char *game_nro_path, char *err, size_t err_len) {
+  if (!game_nro_path || !*game_nro_path) {
+    if (err && err_len) snprintf(err, err_len, "missing game path");
+    return -1;
+  }
+#if defined(__SWITCH__)
+  /* argv for next load: empty args string is fine */
+  Result rc = envSetNextLoad(game_nro_path, game_nro_path);
+  if (R_FAILED(rc)) {
+    if (err && err_len) snprintf(err, err_len, "envSetNextLoad failed: 0x%x", rc);
+    return -1;
+  }
+  return 0;
+#else
+  if (err && err_len)
+    snprintf(err, err_len, "handoff stub (host): would envSetNextLoad %s", game_nro_path);
+  return 0; /* host stub succeeds for flow tests */
+#endif
+}

ports/switch/ota-launcher/src/ota_net.c

@@ -0,0 +1,185 @@
+#include "ota_net.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#if defined(__SWITCH__)
+#include <curl/curl.h>
+#include <switch.h>
+#endif
+
+#if defined(__SWITCH__)
+#define OTA_CA_BUNDLE "romfs:/cacert.pem"
+
+static int g_net_ready = 0;
+
+static int ota_ca_bundle_ready(void) {
+  FILE *f = fopen(OTA_CA_BUNDLE, "rb");
+  if (!f) return 0;
+  fclose(f);
+  return 1;
+}
+
+int ota_net_init(void) {
+  if (g_net_ready) return 0;
+  if (R_FAILED(romfsInit())) return -1;
+  if (!ota_ca_bundle_ready()) return -1;
+  if (curl_global_init(CURL_GLOBAL_DEFAULT) != CURLE_OK) return -1;
+  g_net_ready = 1;
+  return 0;
+}
+
+void ota_net_shutdown(void) {
+  if (!g_net_ready) return;
+  curl_global_cleanup();
+  romfsExit();
+  g_net_ready = 0;
+}
+
+static void ota_net_configure_tls(CURL *curl) {
+  curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
+  curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L);
+  curl_easy_setopt(curl, CURLOPT_CAINFO, OTA_CA_BUNDLE);
+}
+
+struct mem_buf {
+  char *data;
+  size_t len;
+};
+
+struct file_progress {
+  ota_net_progress_fn fn;
+  void *userdata;
+};
+
+static size_t write_mem(char *ptr, size_t size, size_t nmemb, void *userdata) {
+  struct mem_buf *m = (struct mem_buf *)userdata;
+  size_t n = size * nmemb;
+  char *p = (char *)realloc(m->data, m->len + n + 1);
+  if (!p) return 0;
+  m->data = p;
+  memcpy(m->data + m->len, ptr, n);
+  m->len += n;
+  m->data[m->len] = '\0';
+  return n;
+}
+
+static size_t write_file(char *ptr, size_t size, size_t nmemb, void *userdata) {
+  return fwrite(ptr, size, nmemb, (FILE *)userdata);
+}
+
+static int xfer_progress(void *clientp, curl_off_t dltotal, curl_off_t dlnow, curl_off_t ultotal,
+                         curl_off_t ulnow) {
+  (void)ultotal;
+  (void)ulnow;
+  struct file_progress *fp = (struct file_progress *)clientp;
+  if (!fp || !fp->fn) return 0;
+  if (dltotal > 0) {
+    double frac = (double)dlnow / (double)dltotal;
+    if (frac < 0.0) frac = 0.0;
+    if (frac > 1.0) frac = 1.0;
+    fp->fn(fp->userdata, frac);
+  } else if (dlnow > 0) {
+    fp->fn(fp->userdata, -1.0);
+  }
+  return 0;
+}
+#else
+
+int ota_net_init(void) { return 0; }
+void ota_net_shutdown(void) {}
+
+#endif
+
+int ota_net_download_buffer(const char *url, long timeout_ms, char **out, size_t *out_len,
+                            char *err, size_t err_len) {
+  if (out) *out = NULL;
+  if (out_len) *out_len = 0;
+  if (!url || !out) {
+    if (err && err_len) snprintf(err, err_len, "bad args");
+    return -1;
+  }
+#if defined(__SWITCH__)
+  CURL *curl = curl_easy_init();
+  if (!curl) {
+    if (err && err_len) snprintf(err, err_len, "curl_easy_init failed");
+    return -1;
+  }
+  struct mem_buf mem = {0};
+  curl_easy_setopt(curl, CURLOPT_URL, url);
+  curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
+  curl_easy_setopt(curl, CURLOPT_USERAGENT, "gen1recomp-switch-ota");
+  curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, timeout_ms);
+  curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, timeout_ms);
+  curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_mem);
+  curl_easy_setopt(curl, CURLOPT_WRITEDATA, &mem);
+  ota_net_configure_tls(curl);
+  CURLcode rc = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+  if (rc != CURLE_OK) {
+    free(mem.data);
+    if (err && err_len) snprintf(err, err_len, "%s", curl_easy_strerror(rc));
+    return -1;
+  }
+  *out = mem.data;
+  if (out_len) *out_len = mem.len;
+  return 0;
+#else
+  (void)timeout_ms;
+  if (err && err_len)
+    snprintf(err, err_len, "ota_net_download_buffer only available on __SWITCH__");
+  return -1;
+#endif
+}
+
+int ota_net_download_file(const char *url, const char *path, long timeout_ms, char *err,
+                          size_t err_len, ota_net_progress_fn progress, void *progress_ud) {
+  if (!url || !path) {
+    if (err && err_len) snprintf(err, err_len, "bad args");
+    return -1;
+  }
+#if defined(__SWITCH__)
+  FILE *fp = fopen(path, "wb");
+  if (!fp) {
+    if (err && err_len) snprintf(err, err_len, "fopen failed: %s", path);
+    return -1;
+  }
+  CURL *curl = curl_easy_init();
+  if (!curl) {
+    fclose(fp);
+    if (err && err_len) snprintf(err, err_len, "curl_easy_init failed");
+    return -1;
+  }
+  struct file_progress fp_cb = {progress, progress_ud};
+  curl_easy_setopt(curl, CURLOPT_URL, url);
+  curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
+  curl_easy_setopt(curl, CURLOPT_USERAGENT, "gen1recomp-switch-ota");
+  curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, timeout_ms);
+  curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, timeout_ms);
+  curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_file);
+  curl_easy_setopt(curl, CURLOPT_WRITEDATA, fp);
+  ota_net_configure_tls(curl);
+  if (progress) {
+    curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L);
+    curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, xfer_progress);
+    curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &fp_cb);
+  }
+  CURLcode rc = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+  fclose(fp);
+  if (rc != CURLE_OK) {
+    if (err && err_len) snprintf(err, err_len, "%s", curl_easy_strerror(rc));
+    return -1;
+  }
+  if (progress) progress(progress_ud, 1.0);
+  return 0;
+#else
+  (void)timeout_ms;
+  (void)progress;
+  (void)progress_ud;
+  if (err && err_len)
+    snprintf(err, err_len, "ota_net_download_file only available on __SWITCH__");
+  return -1;
+#endif
+}

ports/switch/ota-launcher/src/ota_protocol.c

@@ -0,0 +1,329 @@
+#include "ota_protocol.h"
+
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+  int major;
+  int minor;
+  int patch;
+  int ok;
+} semver_t;
+
+static void set_reason(char *buf, size_t n, const char *r) {
+  if (!buf || n == 0) return;
+  snprintf(buf, n, "%s", r ? r : "");
+}
+
+static int parse_semver(const char *s, semver_t *out) {
+  memset(out, 0, sizeof(*out));
+  if (!s || !*s) return 0;
+  if (s[0] == 'v' || s[0] == 'V') s++;
+  int maj = 0, min = 0, pat = 0;
+  char trail = 0;
+  if (sscanf(s, "%d.%d.%d%c", &maj, &min, &pat, &trail) != 3) return 0;
+  if (maj < 0 || min < 0 || pat < 0) return 0;
+  out->major = maj;
+  out->minor = min;
+  out->patch = pat;
+  out->ok = 1;
+  return 1;
+}
+
+int ota_compare_semver(const char *a, const char *b) {
+  semver_t pa, pb;
+  int oa = parse_semver(a, &pa);
+  int ob = parse_semver(b, &pb);
+  if (!oa && !ob) return 0;
+  if (!oa) return -1;
+  if (!ob) return 1;
+  if (pa.major != pb.major) return pa.major < pb.major ? -1 : 1;
+  if (pa.minor != pb.minor) return pa.minor < pb.minor ? -1 : 1;
+  if (pa.patch != pb.patch) return pa.patch < pb.patch ? -1 : 1;
+  return 0;
+}
+
+int ota_is_ota_asset_name(const char *name) {
+  int maj = 0, min = 0, pat = 0;
+  if (!name) return 0;
+  /* Unified SD/OTA asset: gen1recomp-X.Y.Z-switch.zip */
+  size_t len = strlen(name);
+  const char *suffix = "-switch.zip";
+  size_t slen = strlen(suffix);
+  if (len <= slen) return 0;
+  if (strcmp(name + len - slen, suffix) != 0) return 0;
+  if (strncmp(name, "gen1recomp-", 11) != 0) return 0;
+  if (sscanf(name + 11, "%d.%d.%d", &maj, &min, &pat) != 3) return 0;
+  char rebuilt[128];
+  snprintf(rebuilt, sizeof(rebuilt), "gen1recomp-%d.%d.%d-switch.zip", maj, min, pat);
+  return strcmp(name, rebuilt) == 0;
+}
+
+int ota_version_from_ota_asset(const char *name, char *out, size_t out_len) {
+  int maj = 0, min = 0, pat = 0;
+  if (!out || out_len == 0) return 0;
+  out[0] = '\0';
+  if (!ota_is_ota_asset_name(name)) return 0;
+  if (sscanf(name + 11, "%d.%d.%d", &maj, &min, &pat) != 3) return 0;
+  snprintf(out, out_len, "%d.%d.%d", maj, min, pat);
+  return 1;
+}
+
+static const char *find_json_string(const char *json, const char *key, char *out, size_t out_len) {
+  char pattern[128];
+  snprintf(pattern, sizeof(pattern), "\"%s\"", key);
+  const char *p = strstr(json, pattern);
+  if (!p) return NULL;
+  p = strchr(p + strlen(pattern), ':');
+  if (!p) return NULL;
+  p++;
+  while (*p && isspace((unsigned char)*p)) p++;
+  if (*p != '"') return NULL;
+  p++;
+  size_t i = 0;
+  while (*p && *p != '"' && i + 1 < out_len) {
+    if (*p == '\\' && p[1]) {
+      p++;
+      out[i++] = *p++;
+      continue;
+    }
+    out[i++] = *p++;
+  }
+  out[i] = '\0';
+  return out;
+}
+
+/* Opening { of the JSON object that contains pos (walk backward). */
+static const char *find_json_object_start(const char *pos, const char *json_start) {
+  if (!pos || !json_start || pos < json_start) return NULL;
+  int depth = 0;
+  const char *p = pos;
+  while (p >= json_start) {
+    if (*p == '}') depth++;
+    else if (*p == '{') {
+      if (depth == 0) return p;
+      depth--;
+    }
+    p--;
+  }
+  return NULL;
+}
+
+/* Pointer just past the closing } of the object that starts at object_start. */
+static const char *find_json_object_end(const char *object_start) {
+  if (!object_start || *object_start != '{') return NULL;
+  int depth = 1;
+  const char *p = object_start + 1;
+  while (*p) {
+    if (*p == '{') depth++;
+    else if (*p == '}') {
+      depth--;
+      if (depth == 0) return p + 1;
+    }
+    p++;
+  }
+  return NULL;
+}
+
+int ota_parse_release(const char *json_text, ota_release_t *out) {
+  memset(out, 0, sizeof(*out));
+  if (!json_text || !*json_text) {
+    set_reason(out->reason, sizeof(out->reason), "empty_json");
+    return 0;
+  }
+  if (!find_json_string(json_text, "tag_name", out->tag, sizeof(out->tag))) {
+    set_reason(out->reason, sizeof(out->reason), "missing_tag");
+    return 0;
+  }
+  semver_t sv;
+  if (!parse_semver(out->tag, &sv)) {
+    set_reason(out->reason, sizeof(out->reason), "bad_tag");
+    return 0;
+  }
+  snprintf(out->version, sizeof(out->version), "%d.%d.%d", sv.major, sv.minor, sv.patch);
+
+  /* Scan for OTA asset name then browser_download_url inside the same asset object. */
+  const char *cursor = json_text;
+  while ((cursor = strstr(cursor, "\"name\"")) != NULL) {
+    char name[128];
+    if (!find_json_string(cursor, "name", name, sizeof(name))) {
+      cursor += 6;
+      continue;
+    }
+    if (!ota_is_ota_asset_name(name)) {
+      cursor += 6;
+      continue;
+    }
+    const char *asset_start = find_json_object_start(cursor, json_text);
+    const char *asset_end =
+        asset_start ? find_json_object_end(asset_start) : NULL;
+    if (!asset_start || !asset_end || asset_end <= cursor) {
+      cursor += 6;
+      continue;
+    }
+    char url[512];
+    const char *u = NULL;
+    const char *scan = cursor;
+    while (scan < asset_end &&
+           (scan = strstr(scan, "\"browser_download_url\"")) != NULL && scan < asset_end) {
+      if (find_json_string(scan, "browser_download_url", url, sizeof(url))) {
+        u = url;
+        break;
+      }
+      scan += 21;
+    }
+    if (!u || !*u) {
+      cursor += 6;
+      continue;
+    }
+    snprintf(out->asset_name, sizeof(out->asset_name), "%s", name);
+    snprintf(out->download_url, sizeof(out->download_url), "%s", u);
+    out->ok = 1;
+    return 1;
+  }
+  set_reason(out->reason, sizeof(out->reason), "missing_ota_asset");
+  return 0;
+}
+
+void ota_decide_update(const char *installed_version, const ota_release_t *release,
+                       ota_decision_t *out) {
+  memset(out, 0, sizeof(*out));
+  semver_t inst;
+  if (!parse_semver(installed_version, &inst)) {
+    snprintf(out->status, sizeof(out->status), "error");
+    set_reason(out->reason, sizeof(out->reason), "bad_installed_version");
+    return;
+  }
+  if (!release || !release->ok) {
+    snprintf(out->status, sizeof(out->status), "error");
+    set_reason(out->reason, sizeof(out->reason), "bad_release");
+    return;
+  }
+  if (ota_compare_semver(release->version, installed_version) <= 0) {
+    snprintf(out->status, sizeof(out->status), "uptodate");
+    snprintf(out->version, sizeof(out->version), "%s", installed_version);
+    return;
+  }
+  snprintf(out->status, sizeof(out->status), "available");
+  snprintf(out->version, sizeof(out->version), "%s", release->version);
+  snprintf(out->asset_name, sizeof(out->asset_name), "%s", release->asset_name);
+  snprintf(out->download_url, sizeof(out->download_url), "%s", release->download_url);
+}
+
+int ota_lookup_sum(const char *sums_text, const char *asset_name, char *out_hex, size_t out_len) {
+  if (out_hex && out_len) out_hex[0] = '\0';
+  if (!sums_text || !asset_name || !out_hex || out_len < 65) return 0;
+  const char *p = sums_text;
+  while (*p) {
+    char hex[96];
+    char name[256];
+    int n = 0;
+    if (sscanf(p, "%95s %255s%n", hex, name, &n) >= 2 && n > 0) {
+      const char *nm = name;
+      if (nm[0] == '*') nm++;
+      if (strncmp(nm, "./", 2) == 0) nm += 2;
+      if (strcmp(nm, asset_name) == 0) {
+        /* normalize hex to lowercase */
+        size_t i;
+        for (i = 0; hex[i] && i + 1 < out_len; i++)
+          out_hex[i] = (char)tolower((unsigned char)hex[i]);
+        out_hex[i] = '\0';
+        return 1;
+      }
+      p += n;
+      while (*p && *p != '\n') p++;
+      if (*p == '\n') p++;
+      continue;
+    }
+    while (*p && *p != '\n') p++;
+    if (*p == '\n') p++;
+  }
+  return 0;
+}
+
+void ota_verify_sha256(const char *asset_name, const char *actual_hex, const char *sums_text,
+                       ota_verify_t *out) {
+  memset(out, 0, sizeof(*out));
+  if (!asset_name || !*asset_name) {
+    set_reason(out->reason, sizeof(out->reason), "bad_asset_name");
+    return;
+  }
+  if (!sums_text) {
+    set_reason(out->reason, sizeof(out->reason), "missing_sums");
+    return;
+  }
+  char expected[96];
+  if (!ota_lookup_sum(sums_text, asset_name, expected, sizeof(expected))) {
+    set_reason(out->reason, sizeof(out->reason), "sum_not_found");
+    return;
+  }
+  if (!actual_hex || !*actual_hex) {
+    set_reason(out->reason, sizeof(out->reason), "missing_actual_hash");
+    return;
+  }
+  char actual[96];
+  size_t i;
+  for (i = 0; actual_hex[i] && i + 1 < sizeof(actual); i++)
+    actual[i] = (char)tolower((unsigned char)actual_hex[i]);
+  actual[i] = '\0';
+  if (strcmp(actual, expected) != 0) {
+    set_reason(out->reason, sizeof(out->reason), "hash_mismatch");
+    return;
+  }
+  out->ok = 1;
+}
+
+void ota_plan_atomic_apply(const char *install_dir, const char *verified_temp,
+                           ota_apply_plan_t *out) {
+  memset(out, 0, sizeof(*out));
+  if (!install_dir || !*install_dir) install_dir = OTA_INSTALL_DIR;
+  if (!verified_temp) verified_temp = "";
+  snprintf(out->game_nro, sizeof(out->game_nro), "%s/%s", install_dir, OTA_GAME_NRO_NAME);
+  snprintf(out->part_path, sizeof(out->part_path), "%s.part", out->game_nro);
+  snprintf(out->launcher_nro, sizeof(out->launcher_nro), "%s/%s", install_dir,
+           OTA_LAUNCHER_NRO_NAME);
+  snprintf(out->launcher_part, sizeof(out->launcher_part), "%s.part", out->launcher_nro);
+  snprintf(out->next_load, sizeof(out->next_load), "%s", out->game_nro);
+  /* verified_temp is the game NRO; launcher replace uses a sibling verified path */
+  snprintf(out->steps[0], sizeof(out->steps[0]), "copy_to_part:%s->%s", verified_temp,
+           out->part_path);
+  snprintf(out->steps[1], sizeof(out->steps[1]), "rename:%s->%s", out->part_path, out->game_nro);
+  snprintf(out->steps[2], sizeof(out->steps[2]), "copy_to_part:launcher->%s", out->launcher_part);
+  snprintf(out->steps[3], sizeof(out->steps[3]), "rename:%s->%s", out->launcher_part,
+           out->launcher_nro);
+  snprintf(out->steps[4], sizeof(out->steps[4]), "env_set_next_load:%s", out->game_nro);
+  snprintf(out->preserve, sizeof(out->preserve), "%s/%s", install_dir, OTA_SAVE_DIR_NAME);
+  snprintf(out->forbidden_delete, sizeof(out->forbidden_delete), "delete:%s/%s", install_dir,
+           OTA_SAVE_DIR_NAME);
+  snprintf(out->forbidden_direct, sizeof(out->forbidden_direct), "write_direct:%s", out->game_nro);
+}
+
+void ota_offline_policy(double elapsed_sec, const ota_offline_events_t *events, ota_offline_t *out) {
+  memset(out, 0, sizeof(*out));
+  ota_offline_events_t ev = {0, -1, 0};
+  if (events) ev = *events;
+  if (ev.user_skip) {
+    snprintf(out->action, sizeof(out->action), "play_installed");
+    set_reason(out->reason, sizeof(out->reason), "user_skip");
+    snprintf(out->message, sizeof(out->message), "update skipped");
+    return;
+  }
+  if (ev.api_error || ev.network_ok == 0) {
+    snprintf(out->action, sizeof(out->action), "play_installed");
+    set_reason(out->reason, sizeof(out->reason), "offline_or_error");
+    snprintf(out->message, sizeof(out->message),
+             "offline or update check failed — play installed version");
+    return;
+  }
+  if (elapsed_sec >= (double)OTA_CHECK_TIMEOUT_SEC) {
+    snprintf(out->action, sizeof(out->action), "play_installed");
+    set_reason(out->reason, sizeof(out->reason), "timeout");
+    snprintf(out->message, sizeof(out->message), "update check timed out after %ds",
+             OTA_CHECK_TIMEOUT_SEC);
+    return;
+  }
+  snprintf(out->action, sizeof(out->action), "keep_checking");
+  set_reason(out->reason, sizeof(out->reason), "in_flight");
+}

ports/switch/ota-launcher/src/ota_ui.c

@@ -0,0 +1,595 @@
+/*
+ * Switch OTA UI — matches in-game launcher language (Theme.lua):
+ * black field, RGB version rail, flat yellow/white buttons, white ink.
+ * Quiet until called. Uses framebuffer + 8x8 font + optional romfs logo.
+ */
+#include "ota_ui.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#if defined(__SWITCH__)
+#include <switch.h>
+
+#include "../third_party/font8x8_basic.h"
+
+#define OTA_LOGO_ROMFS "romfs:/logo.rgba"
+
+#define FB_W 1280
+#define FB_H 720
+
+#define TITLE_Y 200
+#define LINE_TITLE 44
+#define LINE_BODY 36
+#define LINE_SMALL 28
+#define WRAP_MAX_PX 720
+
+/* Theme.PAL (0-255) -> RGBA8 */
+#define COL_BG RGBA8_MAXALPHA(0, 0, 0)
+#define COL_INK RGBA8_MAXALPHA(255, 255, 255)
+#define COL_DETAIL RGBA8_MAXALPHA(200, 200, 200)
+#define COL_MUTED RGBA8_MAXALPHA(150, 150, 150)
+#define COL_INVERSE RGBA8_MAXALPHA(0, 0, 0)
+#define COL_YELLOW RGBA8_MAXALPHA(255, 214, 0)
+#define COL_GREEN RGBA8_MAXALPHA(0, 255, 140)
+#define COL_RAIL_R RGBA8_MAXALPHA(255, 60, 72)
+#define COL_RAIL_B RGBA8_MAXALPHA(70, 150, 255)
+#define COL_RAIL_G RGBA8_MAXALPHA(255, 203, 5)
+#define COL_LINE RGBA8_MAXALPHA(90, 90, 90)
+#define COL_RAISED RGBA8_MAXALPHA(20, 20, 20)
+
+static int g_ready = 0;
+static Framebuffer g_fb;
+static PadState g_pad;
+static u32 *g_logo = NULL;
+static int g_logo_w = 0, g_logo_h = 0;
+
+static void fill_rect(u32 *fb, u32 stride_px, int x, int y, int w, int h, u32 color) {
+  if (w <= 0 || h <= 0) return;
+  if (x < 0) {
+    w += x;
+    x = 0;
+  }
+  if (y < 0) {
+    h += y;
+    y = 0;
+  }
+  if (x + w > FB_W) w = FB_W - x;
+  if (y + h > FB_H) h = FB_H - y;
+  if (w <= 0 || h <= 0) return;
+  for (int row = 0; row < h; row++) {
+    u32 *line = fb + (y + row) * stride_px + x;
+    for (int col = 0; col < w; col++) line[col] = color;
+  }
+}
+
+/* Normalize UTF-8 punctuation to ASCII; drop other non-ASCII bytes. */
+static size_t ota_ui_sanitize_ascii(const char *src, char *dst, size_t dst_len) {
+  if (!dst || dst_len == 0) return 0;
+  dst[0] = '\0';
+  if (!src) return 0;
+  size_t w = 0;
+  for (size_t i = 0; src[i] && w + 1 < dst_len;) {
+    unsigned char c = (unsigned char)src[i];
+    if (c < 0x80) {
+      dst[w++] = (char)c;
+      i++;
+      continue;
+    }
+    if (c == 0xE2 && src[i + 1] && src[i + 2]) {
+      unsigned char b2 = (unsigned char)src[i + 1];
+      unsigned char b3 = (unsigned char)src[i + 2];
+      if (b2 == 0x80 && b3 == 0xA6) {
+        if (w + 3 < dst_len) {
+          dst[w++] = '.';
+          dst[w++] = '.';
+          dst[w++] = '.';
+        }
+        i += 3;
+        continue;
+      }
+      if (b2 == 0x80 && (b3 == 0x94 || b3 == 0x93)) {
+        dst[w++] = '-';
+        i += 3;
+        continue;
+      }
+      if (b2 == 0x80 && (b3 == 0x98 || b3 == 0x99)) {
+        dst[w++] = '\'';
+        i += 3;
+        continue;
+      }
+    }
+    if ((c & 0xE0) == 0xC0) i += 2;
+    else if ((c & 0xF0) == 0xE0) i += 3;
+    else if ((c & 0xF8) == 0xF0) i += 4;
+    else i++;
+  }
+  dst[w] = '\0';
+  return w;
+}
+
+static void draw_glyph(u32 *fb, u32 stride_px, int x, int y, char ch, u32 color, int scale) {
+  unsigned char c = (unsigned char)ch;
+  if (c > 127) return;
+  const char *bits = font8x8_basic[c];
+  for (int row = 0; row < 8; row++) {
+    unsigned char line = (unsigned char)bits[row];
+    for (int col = 0; col < 8; col++) {
+      if (line & (1 << col)) {
+        fill_rect(fb, stride_px, x + col * scale, y + row * scale, scale, scale, color);
+      }
+    }
+  }
+}
+
+static int text_width(const char *s, int scale) {
+  if (!s) return 0;
+  return (int)strlen(s) * 8 * scale;
+}
+
+static void draw_text(u32 *fb, u32 stride_px, int x, int y, const char *s, u32 color, int scale) {
+  if (!s) return;
+  char buf[512];
+  ota_ui_sanitize_ascii(s, buf, sizeof(buf));
+  int cx = x;
+  for (const char *p = buf; *p; p++) {
+    if (*p == '\n') {
+      cx = x;
+      y += 8 * scale + 4;
+      continue;
+    }
+    draw_glyph(fb, stride_px, cx, y, *p, color, scale);
+    cx += 8 * scale;
+  }
+}
+
+static void draw_text_centered(u32 *fb, u32 stride_px, int y, const char *s, u32 color, int scale) {
+  char buf[512];
+  ota_ui_sanitize_ascii(s, buf, sizeof(buf));
+  int w = text_width(buf, scale);
+  draw_text(fb, stride_px, (FB_W - w) / 2, y, buf, color, scale);
+}
+
+static int draw_text_wrapped_centered(u32 *fb, u32 stride_px, int y, const char *s, u32 color,
+                                      int scale, int max_px) {
+  if (!s || !*s) return y;
+  char buf[512];
+  ota_ui_sanitize_ascii(s, buf, sizeof(buf));
+  int char_w = 8 * scale;
+  int max_chars = max_px / char_w;
+  if (max_chars < 8) max_chars = 8;
+
+  char line[128];
+  int line_len = 0;
+  const char *word = buf;
+  int lines = 0;
+
+  while (*word) {
+    while (*word == ' ') word++;
+    if (!*word) break;
+
+    const char *end = word;
+    while (*end && *end != ' ' && *end != '\n') end++;
+    int wlen = (int)(end - word);
+
+    if (line_len > 0 && line_len + 1 + wlen > max_chars) {
+      line[line_len] = '\0';
+      draw_text_centered(fb, stride_px, y, line, color, scale);
+      y += 8 * scale + 4;
+      lines++;
+      line_len = 0;
+    }
+
+    if (wlen > max_chars) {
+      if (line_len > 0) {
+        line[line_len] = '\0';
+        draw_text_centered(fb, stride_px, y, line, color, scale);
+        y += 8 * scale + 4;
+        lines++;
+        line_len = 0;
+      }
+      while (wlen > 0) {
+        int chunk = wlen > max_chars ? max_chars : wlen;
+        memcpy(line, word, (size_t)chunk);
+        line[chunk] = '\0';
+        draw_text_centered(fb, stride_px, y, line, color, scale);
+        y += 8 * scale + 4;
+        lines++;
+        word += chunk;
+        wlen -= chunk;
+      }
+      word = end;
+      continue;
+    }
+
+    if (line_len > 0) line[line_len++] = ' ';
+    memcpy(line + line_len, word, (size_t)wlen);
+    line_len += wlen;
+    line[line_len] = '\0';
+    word = (*end == '\n') ? end + 1 : end;
+    if (*(end - 1) == '\n' || *end == '\n') {
+      draw_text_centered(fb, stride_px, y, line, color, scale);
+      y += 8 * scale + 4;
+      lines++;
+      line_len = 0;
+      if (*end == '\n') word = end + 1;
+    }
+  }
+
+  if (line_len > 0) {
+    draw_text_centered(fb, stride_px, y, line, color, scale);
+    y += 8 * scale + 4;
+    lines++;
+  }
+  if (lines == 0) return y;
+  return y;
+}
+
+static void draw_rail(u32 *fb, u32 stride_px) {
+  int h = 6;
+  int third = FB_W / 3;
+  fill_rect(fb, stride_px, 0, 0, third, h, COL_RAIL_R);
+  fill_rect(fb, stride_px, third, 0, third, h, COL_RAIL_B);
+  fill_rect(fb, stride_px, third * 2, 0, FB_W - third * 2, h, COL_RAIL_G);
+}
+
+static void blit_logo(u32 *fb, u32 stride_px, int dst_x, int dst_y, int max_w) {
+  if (!g_logo || g_logo_w <= 0 || g_logo_h <= 0) return;
+  int dw = g_logo_w;
+  int dh = g_logo_h;
+  if (dw > max_w) {
+    dh = dh * max_w / dw;
+    dw = max_w;
+  }
+  for (int y = 0; y < dh; y++) {
+    int sy = y * g_logo_h / dh;
+    for (int x = 0; x < dw; x++) {
+      int sx = x * g_logo_w / dw;
+      u32 px = g_logo[sy * g_logo_w + sx];
+      u8 a = (px >> 24) & 0xff;
+      if (a < 16) continue;
+      int dx = dst_x + x;
+      int dy = dst_y + y;
+      if (dx < 0 || dy < 0 || dx >= FB_W || dy >= FB_H) continue;
+      fb[dy * stride_px + dx] = px | 0xff000000u;
+    }
+  }
+}
+
+static void load_logo(void) {
+  if (g_logo) return;
+  FILE *fp = fopen(OTA_LOGO_ROMFS, "rb");
+  if (!fp) return;
+
+  unsigned char header[8];
+  if (fread(header, 1, sizeof(header), fp) != sizeof(header)) {
+    fclose(fp);
+    return;
+  }
+
+  int w = (int)(header[0] | (header[1] << 8) | (header[2] << 16) | (header[3] << 24));
+  int h = (int)(header[4] | (header[5] << 8) | (header[6] << 16) | (header[7] << 24));
+  if (w <= 0 || h <= 0 || w > 2048 || h > 2048) {
+    fclose(fp);
+    return;
+  }
+
+  size_t nbytes = (size_t)w * (size_t)h * 4u;
+  unsigned char *data = (unsigned char *)malloc(nbytes);
+  if (!data) {
+    fclose(fp);
+    return;
+  }
+  if (fread(data, 1, nbytes, fp) != nbytes) {
+    free(data);
+    fclose(fp);
+    return;
+  }
+  fclose(fp);
+
+  g_logo = (u32 *)malloc((size_t)w * (size_t)h * sizeof(u32));
+  if (!g_logo) {
+    free(data);
+    return;
+  }
+  for (int i = 0; i < w * h; i++) {
+    unsigned char *p = data + (size_t)i * 4u;
+    g_logo[i] = RGBA8(p[0], p[1], p[2], p[3]);
+  }
+  free(data);
+  g_logo_w = w;
+  g_logo_h = h;
+}
+
+static int ui_ensure(void) {
+  if (g_ready) return 1;
+  NWindow *win = nwindowGetDefault();
+  if (R_FAILED(framebufferCreate(&g_fb, win, FB_W, FB_H, PIXEL_FORMAT_RGBA_8888, 2))) return 0;
+  framebufferMakeLinear(&g_fb);
+  padInitializeDefault(&g_pad);
+  load_logo();
+  g_ready = 1;
+  return 1;
+}
+
+void ota_ui_shutdown(void) {
+  if (!g_ready) return;
+  framebufferClose(&g_fb);
+  free(g_logo);
+  g_logo = NULL;
+  g_logo_w = g_logo_h = 0;
+  g_ready = 0;
+}
+
+static void draw_button(u32 *fb, u32 stride_px, int x, int y, int w, int h, u32 fill, u32 ink,
+                        const char *label, int focused) {
+  fill_rect(fb, stride_px, x, y, w, h, fill);
+  if (focused) {
+    fill_rect(fb, stride_px, x - 3, y - 3, w + 6, 2, COL_INK);
+    fill_rect(fb, stride_px, x - 3, y + h + 1, w + 6, 2, COL_INK);
+    fill_rect(fb, stride_px, x - 3, y - 3, 2, h + 6, COL_INK);
+    fill_rect(fb, stride_px, x + w + 1, y - 3, 2, h + 6, COL_INK);
+  } else {
+    fill_rect(fb, stride_px, x, y, w, 1, COL_LINE);
+    fill_rect(fb, stride_px, x, y + h - 1, w, 1, COL_LINE);
+    fill_rect(fb, stride_px, x, y, 1, h, COL_LINE);
+    fill_rect(fb, stride_px, x + w - 1, y, 1, h, COL_LINE);
+  }
+  int scale = 3;
+  char lbl[128];
+  ota_ui_sanitize_ascii(label, lbl, sizeof(lbl));
+  int max_tw = w - 24;
+  int tw = text_width(lbl, scale);
+  while (scale > 2 && tw > max_tw) {
+    scale--;
+    tw = text_width(lbl, scale);
+  }
+  int tx = x + (w - tw) / 2;
+  int ty = y + (h - 8 * scale) / 2;
+  draw_text(fb, stride_px, tx, ty, lbl, ink, scale);
+}
+
+static void draw_chrome(u32 *fb, u32 stride_px) {
+  fill_rect(fb, stride_px, 0, 0, FB_W, FB_H, COL_BG);
+  draw_rail(fb, stride_px);
+  int logo_max = 320;
+  int logo_h = g_logo ? (g_logo_h * logo_max / g_logo_w) : 40;
+  if (logo_h > 90) logo_h = 90;
+  int logo_y = 48;
+  if (g_logo) {
+    int logo_w = logo_max;
+    if (g_logo_w * logo_h / g_logo_h < logo_max) logo_w = g_logo_w * logo_h / g_logo_h;
+    blit_logo(fb, stride_px, (FB_W - logo_w) / 2, logo_y, logo_max);
+  } else {
+    draw_text_centered(fb, stride_px, logo_y + 16, "gen1recomp", COL_INK, 4);
+  }
+}
+
+static void present(void (*paint)(u32 *fb, u32 stride_px, void *ctx), void *ctx) {
+  if (!ui_ensure()) return;
+  u32 stride = 0;
+  u32 *fb = (u32 *)framebufferBegin(&g_fb, &stride);
+  u32 stride_px = stride / sizeof(u32);
+  paint(fb, stride_px, ctx);
+  framebufferEnd(&g_fb);
+}
+
+typedef struct {
+  const char *installed;
+  const char *latest;
+  int focus; /* 0 = Update, 1 = Play */
+} prompt_ctx_t;
+
+static void paint_prompt(u32 *fb, u32 stride_px, void *ctx) {
+  prompt_ctx_t *p = (prompt_ctx_t *)ctx;
+  draw_chrome(fb, stride_px);
+
+  int y = TITLE_Y - 20;
+  draw_text_centered(fb, stride_px, y, "Update available", COL_INK, 3);
+  y += LINE_TITLE;
+
+  char line[96];
+  snprintf(line, sizeof(line), "v%s to v%s", p->installed ? p->installed : "?",
+           p->latest ? p->latest : "?");
+  draw_text_centered(fb, stride_px, y, line, COL_YELLOW, 3);
+  y += LINE_TITLE + 8;
+
+  draw_text_centered(fb, stride_px, y, "Your saves stay on this console.", COL_MUTED, 2);
+  y += LINE_BODY + 28;
+
+  int bw = 600;
+  int bh = 64;
+  int bx = (FB_W - bw) / 2;
+  draw_button(fb, stride_px, bx, y, bw, bh, COL_YELLOW, COL_INVERSE, "(A) Update", p->focus == 0);
+  y += bh + 24;
+  draw_button(fb, stride_px, bx, y, bw, bh, COL_INK, COL_INVERSE, "(B) Play without update",
+              p->focus == 1);
+}
+
+int ota_ui_prompt_update(const char *installed, const char *latest) {
+  if (!ui_ensure()) return 0;
+  prompt_ctx_t ctx = {installed, latest, 0};
+  while (appletMainLoop()) {
+    present(paint_prompt, &ctx);
+    padUpdate(&g_pad);
+    u64 k = padGetButtonsDown(&g_pad);
+    if (k & HidNpadButton_A) {
+      int do_update = (ctx.focus == 0);
+      if (!do_update) ota_ui_shutdown();
+      return do_update;
+    }
+    if (k & HidNpadButton_B) {
+      ota_ui_shutdown();
+      return 0;
+    }
+    if (k & (HidNpadButton_Up | HidNpadButton_Down | HidNpadButton_Left | HidNpadButton_Right)) {
+      ctx.focus = 1 - ctx.focus;
+    }
+    svcSleepThread(16000000ULL);
+  }
+  ota_ui_shutdown();
+  return 0;
+}
+
+typedef struct {
+  const char *title;
+  const char *detail;
+  float progress;
+  int show_bar;
+} status_ctx_t;
+
+static void paint_progress_bar(u32 *fb, u32 stride_px, int y, float t) {
+  int bw = 520;
+  int bh = 18;
+  int bx = (FB_W - bw) / 2;
+  if (t < 0.f) t = 0.f;
+  if (t > 1.f) t = 1.f;
+  fill_rect(fb, stride_px, bx, y, bw, bh, COL_RAISED);
+  fill_rect(fb, stride_px, bx, y, bw, 1, COL_LINE);
+  fill_rect(fb, stride_px, bx, y + bh - 1, bw, 1, COL_LINE);
+  fill_rect(fb, stride_px, bx, y, 1, bh, COL_LINE);
+  fill_rect(fb, stride_px, bx + bw - 1, y, 1, bh, COL_LINE);
+  int fw = (int)(bw * t);
+  if (fw > 0) fill_rect(fb, stride_px, bx, y, fw, bh, COL_GREEN);
+}
+
+static void paint_status(u32 *fb, u32 stride_px, void *ctx) {
+  status_ctx_t *s = (status_ctx_t *)ctx;
+  draw_chrome(fb, stride_px);
+  int y = TITLE_Y;
+  draw_text_centered(fb, stride_px, y, s->title ? s->title : "", COL_INK, 3);
+  y += LINE_TITLE;
+  if (s->detail && s->detail[0]) {
+    y = draw_text_wrapped_centered(fb, stride_px, y, s->detail, COL_DETAIL, 2, WRAP_MAX_PX);
+    y += LINE_SMALL;
+  }
+  if (s->show_bar) paint_progress_bar(fb, stride_px, y, s->progress);
+}
+
+void ota_ui_show_status(const char *title, const char *detail) {
+  status_ctx_t s = {title, detail, 0.f, 0};
+  present(paint_status, &s);
+}
+
+void ota_ui_show_progress(const char *title, const char *detail, float progress01) {
+  status_ctx_t s = {title, detail, progress01, 1};
+  present(paint_status, &s);
+}
+
+typedef struct {
+  const char *title;
+  const char *line1;
+  const char *line2;
+  const char *line3;
+} alert_ctx_t;
+
+static void paint_alert(u32 *fb, u32 stride_px, void *ctx) {
+  alert_ctx_t *a = (alert_ctx_t *)ctx;
+  draw_chrome(fb, stride_px);
+  int y = TITLE_Y;
+  draw_text_centered(fb, stride_px, y, a->title ? a->title : "", COL_YELLOW, 3);
+  y += LINE_TITLE;
+  if (a->line1 && a->line1[0])
+    y = draw_text_wrapped_centered(fb, stride_px, y, a->line1, COL_DETAIL, 2, WRAP_MAX_PX);
+  y += LINE_SMALL;
+  if (a->line2 && a->line2[0])
+    y = draw_text_wrapped_centered(fb, stride_px, y, a->line2, COL_MUTED, 2, WRAP_MAX_PX);
+  y += LINE_SMALL;
+  if (a->line3 && a->line3[0])
+    y = draw_text_wrapped_centered(fb, stride_px, y, a->line3, COL_MUTED, 2, WRAP_MAX_PX);
+  y += LINE_BODY + 16;
+  int bw = 360;
+  int bh = 56;
+  draw_button(fb, stride_px, (FB_W - bw) / 2, y, bw, bh, COL_INK, COL_INVERSE, "(B) Continue", 1);
+}
+
+void ota_ui_alert(const char *title, const char *line1, const char *line2) {
+  if (!ui_ensure()) return;
+  alert_ctx_t a = {title, line1, line2, NULL};
+  while (appletMainLoop()) {
+    present(paint_alert, &a);
+    padUpdate(&g_pad);
+    if (padGetButtonsDown(&g_pad) & HidNpadButton_B) break;
+    svcSleepThread(16000000ULL);
+  }
+  ota_ui_shutdown();
+}
+
+void ota_ui_alert_error(const char *title, const char *friendly, const char *technical,
+                        const char *installed_version) {
+  if (!ui_ensure()) return;
+  char footer[96];
+  snprintf(footer, sizeof(footer), "Playing installed version (v%s).",
+           installed_version && installed_version[0] ? installed_version : "?");
+  char tech[256];
+  if (technical && technical[0]) {
+    ota_ui_sanitize_ascii(technical, tech, sizeof(tech));
+    if (strlen(tech) > 80) tech[80] = '\0';
+  } else {
+    tech[0] = '\0';
+  }
+  alert_ctx_t a = {title, friendly, tech[0] ? tech : NULL, footer};
+  while (appletMainLoop()) {
+    present(paint_alert, &a);
+    padUpdate(&g_pad);
+    if (padGetButtonsDown(&g_pad) & HidNpadButton_B) break;
+    svcSleepThread(16000000ULL);
+  }
+  ota_ui_shutdown();
+}
+
+static void paint_missing(u32 *fb, u32 stride_px, void *ctx) {
+  (void)ctx;
+  draw_chrome(fb, stride_px);
+  int y = TITLE_Y - 10;
+  draw_text_centered(fb, stride_px, y, "Game files missing", COL_YELLOW, 3);
+  y += LINE_TITLE;
+  y = draw_text_wrapped_centered(fb, stride_px, y,
+                                 "Copy the Switch zip onto your microSD, then open gen1recomp again.",
+                                 COL_DETAIL, 2, WRAP_MAX_PX);
+  y += LINE_BODY + 16;
+  int bw = 320;
+  int bh = 56;
+  draw_button(fb, stride_px, (FB_W - bw) / 2, y, bw, bh, COL_INK, COL_INVERSE, "(+) Exit", 1);
+}
+
+void ota_ui_missing_game(void) {
+  if (!ui_ensure()) return;
+  while (appletMainLoop()) {
+    present(paint_missing, NULL);
+    padUpdate(&g_pad);
+    if (padGetButtonsDown(&g_pad) & HidNpadButton_Plus) break;
+    svcSleepThread(16000000ULL);
+  }
+  ota_ui_shutdown();
+}
+
+#else /* host stub */
+
+int ota_ui_prompt_update(const char *installed, const char *latest) {
+  fprintf(stderr, "[ota_ui] update %s -> %s (host stub: skip)\n", installed ? installed : "?",
+          latest ? latest : "?");
+  return 0;
+}
+void ota_ui_show_status(const char *title, const char *detail) {
+  fprintf(stderr, "[ota_ui] %s %s\n", title ? title : "", detail ? detail : "");
+}
+void ota_ui_show_progress(const char *title, const char *detail, float progress01) {
+  fprintf(stderr, "[ota_ui] %s %s (%.0f%%)\n", title ? title : "", detail ? detail : "",
+          progress01 * 100.f);
+}
+void ota_ui_alert(const char *title, const char *line1, const char *line2) {
+  fprintf(stderr, "[ota_ui] alert: %s / %s / %s\n", title ? title : "", line1 ? line1 : "",
+          line2 ? line2 : "");
+}
+void ota_ui_alert_error(const char *title, const char *friendly, const char *technical,
+                        const char *installed_version) {
+  fprintf(stderr, "[ota_ui] error: %s / %s / %s / v%s\n", title ? title : "",
+          friendly ? friendly : "", technical ? technical : "",
+          installed_version ? installed_version : "?");
+}
+void ota_ui_missing_game(void) { fprintf(stderr, "[ota_ui] missing game\n"); }
+void ota_ui_shutdown(void) {}
+
+#endif