bang bang

The launcher spent ~9ms per frame building and drawing, and the Find Mods
tab could hang the window for minutes. Both had the same root cause: a
retained UI tree rebuilt every frame, and blocking curl calls made from the
draw path.

Replace the vendored FlexLove engine (28.5k lines) with src/ui/kit/ (Kit,
Theme, Layout, Loader). The kit caches Text objects and all measurement,
allocates nothing in the steady state, and draws flat. Build+draw is now
under 1ms at every window size and on every tab (POKEPORT_LAUNCHER_PROF).

Move every network call off the render thread onto a love.thread pool
(src/net/Fetch.lua): mod index fetches, per-mod release checks, find-tab
stats, thumbnails and mod installs. Mod indexes prewarm at boot so the
Find Mods tab is populated before it is opened.

Paginate every list -- mods, find, save slots, settings, release notes,
versions -- with the page size derived from the real viewport height, so a
500-mod index costs what a 10-mod one does. Scrolling is gone.

Anything that waits now raises a non-dismissable loader; per-row background
work shows an inline spinner instead. The in-app updater moves to the top
right beside the settings gear and pulses when an update is waiting.

Theme is black with white outlines, no gradients or glows, and solid
colour-coded embossed buttons with bold labels. The game tabs keep their
cartridge colours. Everything is 1.3x larger. The save editor shares the
theme, and adding an item there is now a searchable pop-up like adding a
Pokemon.

Also:
- Reset rebinds, in Settings and under Touch Controls. Rebinds are additive
  (Input:applyBindings layers them over the defaults), so there was no
  in-game way to undo one.
- Launch options: --game red [--slot N] / POKEPORT_GAME boots straight into
  a game for shortcuts and frontends, falling back to that game's tab when
  its ROM is not imported.

Fixes found while porting:
- Ellipsis and letterspacing truncated bytes, not codepoints, so a
  multi-byte mod name crashed the first frame on a Japanese index.
  Measurement no longer throws on malformed input either.
- The new font set missed UiFont's kana fallback, rendering translated
  builds as tofu.
- Fetch workers idle in Channel:demand() and LOVE waits for live threads at
  exit, so the process outlived the window; quitting mid-download also
  waited on curl's 300s ceiling. Shut the pool down in love.quit and bound
  its transfer timeouts.
- In one column the save-slot card drew below the fold, over the footer,
  with no scrollbar left to reach it.

The two FlexLove engine tests guarded a scroll manager and an auto-height
propagation bug that no longer exist; replace them with a kit suite covering
page bounds, viewport sizing and UTF-8 truncation, and retarget the NX test
to assert the dependency is gone rather than that its perf guards are set.

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
     outputs:
       changed: ${{ steps.paths.outputs.changed }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - id: paths
@@ -44,7 +44,7 @@ jobs:
             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$|\.github/workflows/(ci|release)\.yml$)'; then
+          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"
@@ -58,7 +58,7 @@ jobs:
     outputs:
       ipa_url: ${{ steps.upload-ipa.outputs.artifact-url }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: import signing certificate
         if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
@@ -92,7 +92,7 @@ jobs:
       - name: upload iOS release artifact
         id: upload-ipa
         if: github.repository == 'bryanthaboi/gen1recomp'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: gen1recomp-ios-ipa
           path: dist/ios/gen1recomp.ipa
@@ -102,11 +102,169 @@ jobs:
         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|RomImporter)\.lua$|src/update/Check\.lua$|tests/engine/(platform_nx|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
+
   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
@@ -124,7 +282,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
 
@@ -166,7 +324,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
@@ -214,7 +372,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

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: read
+  issues: write
   pull-requests: write
 
 jobs:
@@ -28,16 +29,27 @@ jobs:
           [ -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: |
-            #### iOS Release IPA
+            [gen1recomp.ipa](${{ steps.artifact.outputs.artifact_url }})
 
-            - [Download 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>Automatically generated. [View workflow run](https://github.com/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }})</sub>
+            <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: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
-
+  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,10 +117,127 @@ 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
+
+  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]
+    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: |
@@ -170,12 +282,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: |
@@ -189,18 +301,29 @@ jobs:
           set -euo pipefail
           if [ "$CANONICAL_REPOSITORY" = true ]; then
             scripts/build_ios.sh --fetch --device --release \
-              --version "${{ steps.ver.outputs.version }}"
+              --version "${{ needs.version.outputs.version }}"
           else
             scripts/build_ios.sh --fetch --release \
-              --version "${{ steps.ver.outputs.version }}"
+              --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'
@@ -237,12 +360,19 @@ 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: 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"
@@ -257,6 +387,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"
@@ -283,8 +423,8 @@ jobs:
           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
@@ -368,22 +508,93 @@ 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}-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() && 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,7 +31,10 @@ 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-development.md; also covered by .*)
+.bazinga/love-nx/
+
+# Final packaged build artifacts (mac/win/web/android/ios/switch) — see scripts/build.sh
 /dist/
 
 # Legacy manual convenience-copy location (superseded by /dist/android/)
@@ -43,3 +46,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,7 +4,7 @@ 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.
 
-> [!WARNING]
+> [!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>
@@ -112,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) |
@@ -121,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
 
@@ -211,6 +212,16 @@ 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>
+
 ## Handhelds
 
 A PortMaster-style port for the **Anbernic RG34XXSP** on Stock OS 64-bit MOD
@@ -218,6 +229,27 @@ 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` (issue
+[#531](https://github.com/bryanthaboi/gen1recomp/issues/531)). Runtime target
+is pinned [love-nx](https://github.com/retronx-team/love-nx) `11.5-nx1`.
+Requires a console that can run Switch homebrew. Hardware evidence: **OLED**
+(author) and **V1 / Erista** boot (community).
+
+- 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, canonical fused PR artifact, release hard-fail).
+
+Limitations, Dusklight-derived method, and how we tested:
+[docs/switch-development.md](docs/switch-development.md) and
+[docs/switch-hardware-evidence.md](docs/switch-hardware-evidence.md). Community
+help — especially HOS / love-nx packaging and broader hardware coverage — is
+welcome.
+
 ## Modding
 
 The game ships a native mod platform: content registries, events and hooks,
@@ -265,4 +297,7 @@ This project would not be possible without [pret](https://github.com/pret) >
 the pret band of decompiling maniacs > and their
 [pokered](https://github.com/pret/pokered) disassembly.
 
+Nintendo Switch port: [andrewqsantos](https://github.com/andrewqsantos).  
+Switch hardware testing (V1 boot): [booshankles](https://github.com/booshankles).
+
 <p align="center"><a href="https://boisclub.games"><img src="https://raw.githubusercontent.com/bryanthaboi/gen1recomp/refs/heads/dev/assets/logo/bcg.png"></a></p>

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/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_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/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 =
@@ -297,9 +325,14 @@ 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" })
-      -- restore the lab theme once he's walked out, same as the Yellow port
       table.insert(rows, { "play_music", "Music_OaksLab" })
       ow.runner:run(rows, { npc = rival })
       return true

data/scripts/oaks_lab_yellow.lua

@@ -287,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
@@ -749,11 +814,15 @@ M.SILPH_CO_11F = {
     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).
+        -- 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
-          silphRocketsLeave(game, ow)
+          ow:queueScript(silphAftermathRows())
         end
       end)
     end)
@@ -899,6 +968,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 +1007,62 @@ 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
+  { "play_music", "Music_Cities1", { keep = true } },       -- 11
+  { "show_text", "_ChampionsRoomOakText" },                 -- 12
+  { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 13
+  { "move_npc", 2, "up", 5 },                               -- 14 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" },                             -- 15
+  { "face_object", 2, "down" },                             -- 16
+  { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 17
   -- OakDisappointedWithRivalScript: Oak turns to the rival (right)
-  { "face_object", 2, "right" },                            -- 17
-  { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 18
+  { "face_object", 2, "right" },                            -- 18
+  { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 19
   -- 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" },                             -- 20
+  { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 21
+  { "move_npc", 2, "up", 2 },                               -- 22 OakExitChampionsRoomMovement
+  { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 23
+  -- 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.
+  { "move_player", "up", 3 },                               -- 24
   -- 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 },               -- 25
+  { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 26
 }
 
 M.CHAMPIONS_ROOM = {

data/scripts/story3.lua

@@ -549,21 +549,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 +607,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 +643,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/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

@@ -118,6 +118,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

@@ -108,8 +108,16 @@ return {
                            "_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_viridian_old_man.lua

@@ -24,7 +24,8 @@
 -- 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).  After it, the same text pointer
+-- (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
@@ -63,7 +64,12 @@ end
 local function oldMan2Rows(game, ow, npc)
   local rows = {
     { "show_text", "_ViridianCityOldManHadMyCoffeeNowText" },
-    { "old_man_demo" },
+    -- 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" },
   }

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/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.

docs/new-features.md

@@ -1,10 +1,10 @@
 # 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.
+Intentional enhancements this port adds on top of faithful Pokémon Red, Blue,
+and Yellow 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.
+approximated) live in docs/known-differences.md; faithfully-ported behavior is
+in docs/behavior-porting-notes.md.
 
 ## Survey zoom
 
@@ -209,10 +209,15 @@ duration:
   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.
+- **Online play runs vanilla, except for your language.** Picking ONLINE
+  MATCH or TOURNAMENT with mods enabled offers to switch the gameplay ones
+  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. A mod that declares itself a translation and provably
+  writes nothing but text stays on: the two games hash the same link
+  surface, so a Spanish install and an English one can battle and trade,
+  each reading the game in its own language and naming the other player's
+  party out of its own text.
 - **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
@@ -314,12 +319,29 @@ 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.
+button freely, resize the whole pad with **-/+** (60% to 160%), **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 a
+different screen keeps the relative placement.
+
+Portrait and landscape are edited and saved separately (#633): the editor
+follows whichever orientation is on screen, and **Reset** only clears that
+one, so a layout that works held upright does not have to double as the
+one used sideways. An `options.lua` from before this split keeps its single
+layout in both orientations until one of them is edited. In-game, Options →
+**TOUCH PAD** toggles the same on/off flag without leaving a play session.
+
+## Screen orientation lock (Android)
+
+Options → **ORIENTATION** (also in the launcher's gear menu) locks the
+screen to **PORTRAIT**, **LANDSCAPE** (either landscape, following the
+device), or **REVERSE LANDSCAPE**, or leaves it on **AUTO** (#592). AUTO
+allows every orientation but defers to the system: with auto-rotate turned
+off in Android's quick settings, the game stays put instead of following
+the sensor (#716). Changes apply immediately -- the screen rotates as the
+row is stepped -- and persist in `options.lua`. Android only: iOS follows
+the app's fixed orientation list, and desktop windows rotate nothing.
 
 ## Translation support
 
@@ -354,6 +376,28 @@ plus a glyph-page and charmap stub, a naming-grid stub, and a
 be packed). `--refresh` re-harvests after an engine update, keeping
 existing translations and parking orphaned keys rather than dropping them.
 
+A translation can also skip glyph pages entirely: scaffolding with
+`--pixel-font` (or registering `mod.content.font:register("ttf", {})` in
+an existing mod) renders text through a bundled TTF covering Latin with
+diacritics, Cyrillic, kana and CJK, while box borders and `<PK>`-style
+macro glyphs keep their tiles. The font is "Plain Pixel Font" by Douglas
+Vautour (Burpy Fresh), licensed under CC-BY 4.0 (5x11 base characters,
+11x11 double-width; see `assets/fonts/plainpixel/README.md`). Options on
+the registry entry: `file` for a mod-shipped TTF, `size` (the font's
+design em; Plain Pixel rasterizes cleanly only at multiples of 15),
+`spacing` added to every advance, `yOffset` for vertical alignment
+against the 8px cell grid, `bold`, which double-prints at a 1px
+offset for fonts whose strokes read too light, and `tiles`, the
+characters that keep their ROM tile instead of coming from the TTF.
+
+`tiles` matters for a CJK translation. Sizing the font so a kana fills
+the 8px cell leaves Latin narrower than the tile font it replaces, which
+pulls the numeric columns out of line: the party menu's `:L12` stops
+sitting over `34/ 34`. Naming `"0123456789/:"` keeps those on the
+vanilla tiles, so numbers render exactly as they do in English while
+kana still come from the font. It takes a string of characters, or a
+list when a multi-character charmap sequence is meant.
+
 See the wiki's Translations guide.
 
 ## Save editor (bundled, reachable from the launcher)
@@ -382,7 +426,9 @@ semantics - so the two windows read as one app. Six tabs:
 - **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.
+  with no slot cap, and the eight badges as toggle chips. The picker, the bag
+  and PC storage all scroll under the mouse wheel, so the whole catalog is
+  reachable one-handed without typing a query.
 - **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,
@@ -434,6 +480,16 @@ 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.
 
+A feed author can publish per-mod release stats by adding three optional
+fields to an entry -- `downloads` (total across every release), and
+`first_release` / `last_release` (ISO days) -- which the listing shows in
+the same gold line the MODS tab uses. When a feed does not carry them,
+the row fetches the mod's own GitHub releases instead -- the same cached
+`ModUpdate` fetch the MODS tab uses, one entry per frame -- so the stats
+appear for any mod with a `github` field regardless of feed maintenance.
+The fields are additive: feeds that carry them stay readable by every
+build that predates them, and feeds that do not render exactly as before.
+
 ## Soft reset (all versions)
 
 Holding A, B, START and SELECT together restarts the game the way flicking
@@ -460,3 +516,94 @@ 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.
+
+Controllers a system has no mapping for (common on Linux handhelds and
+off-brand pads) report bare button numbers rather than names. Those are
+rebindable on the same screen and show up as JOY1, JOY2 and so on in the
+controller column. Recognized controllers are read only through their
+named buttons, so a rebind on those is never shadowed by the factory
+layout underneath it.
+
+## Mod profiles (#593)
+
+The mod manager's PROFILES tab holds named setups. A profile remembers which
+mods are on, every mod's own options, and which save slot each game version
+plays, so swapping profiles swaps the whole playthrough and not just the mod
+list. The setup that existed before profiles shipped becomes PROFILE 1 the
+first time the manager opens.
+
+EXPORT.. writes the selected profile to `profiles/<NAME>.g1rmodlist` in the
+save directory; drop a `.g1rmodlist` someone shared into that folder and
+IMPORT.. adds it. Imported profiles never overwrite an existing one (a name
+clash gets a number). Mods the shared profile names but that are not installed
+are reported when the profile is applied; installing them is still a manual
+trip through the mods list or Find Mods.
+
+## Windows: no console windows on launcher actions
+
+Checking for updates, browsing a mod index, adding a mod repo, installing a
+mod and picking a ROM all run a host tool (curl, PowerShell) in a child
+process. On Windows those children used to each open their own console
+window, so a session could end up buried under half a dozen of them. The
+game now claims one console for itself at boot and hides it; the children
+inherit that invisible console and nothing pops up. Nothing else changes:
+file pickers are ordinary desktop dialogs and still appear normally, and a
+run started from a terminal (`lovec.exe`, what `scripts\run.ps1` prefers)
+keeps its terminal and its printed output. Set `POKEPORT_CONSOLE=1` to opt
+out.
+
+## A faster, higher-contrast launcher
+
+The launcher and the save editor were rebuilt on one small immediate-mode UI
+kit (`src/ui/kit/`), replacing the vendored FlexLove layout engine. The
+visible result is that the launcher is quick: building and drawing a frame
+went from about 9 ms to under 1 ms on the same machine and the same data, at
+every window size, so the window keeps up with the pointer instead of
+trailing it. Measure it yourself with `POKEPORT_LAUNCHER_PROF=200 love .`.
+
+**Nothing blocks the window any more.** Fetching a mod index, checking a mod
+for updates, listing versions, downloading an install and pulling thumbnails
+all run on background threads. Opening FIND MODS on a cold cache used to
+freeze the launcher for as long as the server took -- often minutes, with no
+indication anything was happening. Mod indexes are now also fetched at boot,
+so the tab is usually already populated by the time you reach it.
+
+**Anything you wait on says so.** Every operation that takes time raises a
+loading panel with a spinner or a progress bar that cannot be clicked around
+or dismissed, so a half-finished install can never be interrupted by a stray
+click. Work that only affects one row (a mod's update check) shows a small
+spinner on that row instead and leaves the rest of the list usable.
+
+**Lists page instead of scrolling.** Mods, Find Mods, save slots, settings,
+release notes and the version list all show a fixed number of rows with a
+pager underneath, and the number of rows comes from the window height -- a
+tall window shows more, a phone shows fewer. A long list costs exactly what a
+short one does. The mouse wheel turns pages.
+
+**Updates live in the top right.** The in-app updater moved next to the
+settings gear and pulses when an update is waiting, instead of sitting in a
+banner at the bottom of the page that you had to scroll to notice. Checking
+for updates from there shows a loader like everything else.
+
+**The look.** Black background, white outlines, no gradients or glows, and
+buttons that are solid colour-coded keys: green commits, blue navigates, red
+destroys, yellow wants attention. The three game tabs keep their red, blue
+and gold cartridge colours. Everything is about a third larger than before.
+The save editor follows the same theme, and adding an item there is now a
+searchable pop-up like adding a Pokemon, rather than a cramped list wedged
+into the tab.
+
+**Reset rebinds.** Input rebinds are additive, so there was no in-game way to
+undo one. A RESET REBINDS row in Settings, and a matching button under Touch
+Controls on each game tab, restore the stock keyboard, gamepad and touch
+layout. Both ask twice.
+
+## Launch options: boot straight into a game
+
+`love . --game red` skips the launcher and starts that game; `--slot <id or
+number>` picks the save slot to load, and `--launcher` forces the launcher
+anyway. `POKEPORT_GAME` / `POKEPORT_SLOT` do the same for shortcuts that can
+only pass environment variables. This is for one-click entries: a desktop
+shortcut per game, a Steam entry, or a handheld frontend. Asking for a game
+whose ROM has not been imported opens the launcher on that game's tab rather
+than failing.

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/switch-build.md

@@ -0,0 +1,204 @@
+# Build the Nintendo Switch NRO — contributor guide
+
+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.
+Hardware evidence, MTP operator loops, and deeper notes live in
+[switch-development.md](switch-development.md).
+
+> Releases ship `gen1recomp-*-switch.zip` (SD tree under `switch/gen1recomp/`;
+> issue [#531](https://github.com/bryanthaboi/gen1recomp/issues/531)). Hardware
+> evidence: **OLED** (author) and **V1 boot** (community). See
+> [switch-development.md](switch-development.md) for known limitations.
+
+---
+
+## 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:
+
+   ```sh
+   sudo dkp-pacman -S switch-dev
+   ```
+
+3. Ensure `nacptool` and `elf2nro` are on `PATH` (or under
+   `$DEVKITPRO/tools/bin` — the fused script prepends that when set).
+
+**Optional:** Install [Docker](https://docs.docker.com/get-docker/) so fused
+builds can fall back to the pinned image when native tools are missing.
+
+### 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 | — |
+| `dkp-pacman` + `switch-dev` (native fused) | `dkp-pacman -S …` |
+| Docker (optional fused fallback) | Docker Engine |
+| 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 `dist/switch/gen1recomp-<ver>-switch.nro` (game in romfs) via `nacptool` + `elf2nro`, then packs `dist/switch/gen1recomp-<ver>-switch.zip` (SD-ready tree). Needs the pin + toolchain (native 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
+
+# Single fused NRO + SD-ready 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.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 canonical 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 **canonical** 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 repository** CI never runs
+   fused. **Fork → canonical PRs** 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 **native switch-tools** (`nacptool` /
+`elf2nro`) **and/or Docker** available. CI and release do not silently run
+`dkp-pacman -S`; keep the runner image/host provisioned per this guide.
+
+---
+
+## 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).  
+Hardware depth and evidence: [switch-development.md](switch-development.md),
+[switch-hardware-evidence.md](switch-hardware-evidence.md).

docs/switch-development.md

@@ -0,0 +1,528 @@
+# Nintendo Switch development (love-nx)
+
+> Fused NRO support for issue [#531](https://github.com/bryanthaboi/gen1recomp/issues/531).
+> Releases ship `gen1recomp-*-switch.zip` (SD-ready tree). Console copy is
+> extract/merge at microSD root; title override required. See
+> [Known limitations](#known-limitations-read-before-reviewing).
+
+**Canonical install / build / transfer docs** (start here unless you need hardware depth):
+
+- Players → [switch-install.md](switch-install.md)
+- Builders → [switch-build.md](switch-build.md) (`scripts/build_switch.sh --fetch` downloads the pinned love-nx pair)
+- Transfer (MTP / SD / FTP on macOS, Linux, Windows) → [switch-transfer.md](switch-transfer.md)
+
+This document covers what landed, known limitations, how hardware was tested,
+vendor layout, build/deploy, and the contributor transfer loop (detail lives in
+the transfer runbook).
+
+## Acknowledgments
+
+- **Port / love-nx packaging:** [andrewqsantos](https://github.com/andrewqsantos)
+- **Community hardware testing** (Switch V1 / Erista boot): [booshankles](https://github.com/booshankles)
+- **Method guidance:** [Dusklight Switch port](https://github.com/HayatoG/dusklight/tree/main/platforms/switch) / love-nx
+- **Upstream project:** [bryanthaboi](https://github.com/bryanthaboi) / Gen1Recomp
+
+## Status
+
+| Area | State |
+| ---- | ----- |
+| Feature | **Available** — playable fused NRO path (issue #531) |
+| Runtime | Pinned love-nx **`11.5-nx1`** |
+| Product artifact | Releases: SD-ready `gen1recomp-*-switch.zip`; local/PR: fused `.nro`; loose `nro`+`game.love` for iteration |
+| Hardware | **OLED** validated (author, title override); **V1 / Erista** boot confirmed (community). Lite, docked soak, and Pro Controller matrices welcome |
+| Deploy / install | Releases publish SD-ready zip; **extract/merge at microSD root** (MTP / SD / FTP — [switch-transfer.md](switch-transfer.md)); no `nxlink` path yet |
+| Contributor transfer | Documented for **macOS, Linux, and Windows**; OpenMTP on Mac is one example, not the only contract |
+| Network features on NX | Self-update / remote mod download **disabled** (`networkValidated == false`) |
+| Community help | Welcome — especially HOS / love-nx packaging and broader hardware coverage |
+
+### What landed
+
+- Detect `NX` via `src/core/Platform.lua` without reusing Android flags
+- Writable ROM inbox under `getSaveDirectory()/imports/` + per-tab “Scan again” (SHA-1 match for the open game)
+- Joy-Con / gamepad mapping shared by launcher and gameplay (Nintendo A/B UX on NX)
+- Launcher L/R tab switch; gameplay L/R game-speed cycle; Select+face display chords
+- Focus loss / joystick reconnect recovery; opt-in `switch-debug.txt` diagnostics
+- Loose assemble + fused NRO build scripts (`scripts/build_switch.sh`, `scripts/switch/*`)
+- Payload gates so ROM / generated cache / saves never enter `game.love`
+- Community mod zip inbox at `imports/mods/` (rescan installs; FIND MODS stays network-gated)
+- Raw `.sav` inbox at `imports/saves/{red,blue,yellow}/` (**Import save** rescan) + export pull path `exports/{red,blue,yellow}/` (MTP hint; no openURL)
+- Hardware evidence for Phase 0 probe, ROM import, naming A/B, save/suspend, fused NRO — see `docs/switch-hardware-evidence.md`
+- Path-gated CI selftest + canonical fused PR artifact; release Switch hard-fail
+- Save editor pad/touch input (virtual cursor, A click, B close) — see `tools/save-editor/README.md`
+- Dynamic display size on NX only: handheld **1280×720**, docked/TV **1920×1080** (`src/core/NxDisplay.lua` + resizable conf so love-nx SDL can follow dock/undock at runtime)
+
+### Known gaps / welcome contributions
+
+- Docked vs handheld soak (≥30 min) and Lite coverage — resolution switch is implemented; long soak still welcome
+- Switch Lite and fuller Pro Controller / third-party pad matrices
+- Applet Mode remains unsupported by design (title override required)
+- `nxlink` / netloader contrib fast-loop (deferred — see [switch-transfer.md](switch-transfer.md))
+
+Transfer runbooks for Linux/Windows (and SD/FTP alternatives) are in
+[switch-transfer.md](switch-transfer.md). Community mod zip install OLED smoke
+is **pass** — see NXMOD-12 in [switch-hardware-evidence.md](switch-hardware-evidence.md).
+
+## Design references (Dusklight)
+
+This work borrowed method — not the native stack — from the [Dusklight Switch port](https://github.com/HayatoG/dusklight/tree/main/platforms/switch), especially [`LESSONS_AND_REUSE.md`](https://github.com/HayatoG/dusklight/blob/main/platforms/switch/LESSONS_AND_REUSE.md):
+
+| Dusklight lesson | How Gen1Recomp applied it |
+| ---------------- | ------------------------- |
+| Emulators hide Tegra failures | Gate milestones on **real OLED hardware**, not Ryujinx/Yuzu alone |
+| Prove the lower layer first | `tools/switch-probe` before full launcher |
+| Know which binary ran | Embedded `build-info.json` (commit / love-nx tag) |
+| Cap continuous logs | Opt-in diagnostics, ≤1 Hz flush; Lua error log rotation |
+| Crash symbolization needs the exact ELF | Keep pinned `love.elf` with the NRO under test |
+| Full memory matters | Title override; Applet Mode is not the validation path |
+| Do not treat SD FS like desktop POSIX | Lua stays on `love.filesystem`; inbox + MTP for user files |
+| Isolate platform code | Capability module instead of Android flag overload |
+| NVK / WSI / `audren` stacks | **Not** copied — love-nx already supplies video/audio/input/FS |
+
+The packaging goal matches Dusklight’s **single self-contained `.nro`**; contributor transfer stays multi-host (not Mac-only).
+
+## Known limitations (read before reviewing)
+
+1. **Transfer is manual and multi-method.** Runtime only needs files under the LÖVE save directory / NRO install folder. Use MTP, direct SD, or FTP per [switch-transfer.md](switch-transfer.md). macOS + OpenMTP is a documented example for OLED evidence — not “Switch requires a Mac.”
+2. **Deploy is manual.** There is no automated push to the console and no `nxlink` path yet. Operators build locally, transfer files, then title-override launch.
+3. **Hardware coverage.** Author P0/P1 pass rows were recorded on one Switch OLED; Switch V1 boot was confirmed independently. Treat Lite, docked soak, and other hosts as unknown until someone re-runs the checklist.
+4. **No ROM/save/mod zip bytes in git.** Legal dumps and third-party mods stay on the console (or local untracked folders).
+5. **AppleDouble sidecars** (`._*`) from some MTP clients can break zip/ROM/`.sav` scans — the launcher skips hidden `.*` names (including `._*.sav`); still prefer clean copies.
+
+## How we tested
+
+| Layer | What | Where |
+| ----- | ---- | ----- |
+| Unit / headless | Platform NX flags, RomImporter inbox, dual-path input, mod zip inbox, save `.sav` inbox, display chords, payload/self-tests | `tests/*`, `scripts/test.sh` |
+| Switch CI / packaging | Path-gated offline selftest (`selftest_build_switch.sh`, `verify_payload.sh --self-test`, `switch_ci_workflows_test.lua`); canonical fused PR artifact | `.github/workflows/ci.yml`, [switch-build.md](switch-build.md) § CI and release |
+| Probe on hardware | `getOS()==NX`, 1280×720, save path, Joy-Con events | `tools/switch-probe` → OLED |
+| Integration on hardware | MTP inbox ROM import, Play Red/Blue, naming A/B, quit/reopen save, suspend×10, reboot, fused NRO alone + NRO-only update | `docs/switch-hardware-evidence.md` |
+| Community hardware | Switch V1 / Erista boot with prebuilt NRO | [booshankles](https://github.com/booshankles) — see evidence log |
+| Known gaps | Docked soak, ≥30 min long-play, Lite, automated/`nxlink` deploy | Matrix deferred / absent rows |
+
+Operator evidence must stay in `docs/switch-hardware-evidence.md`. **Do not invent passes** for hardware not run.
+
+## love-nx 11.5-nx1 (pinned)
+
+**Tag:** [11.5-nx1](https://github.com/retronx-team/love-nx/releases/tag/11.5-nx1)
+
+**Local layout (not committed):**
+
+```text
+.bazinga/love-nx/11.5-nx1/
+├── love.nro    # homebrew launcher binary (loose mode: copied to gen1recomp.nro)
+└── love.elf    # required for fused NRO builds (devkitPro nacptool/elf2nro)
+```
+
+**Manifest:** `scripts/switch/love-nx-11.5-nx1.sha256` lists expected artifact names and SHA-256 checksums. Checksums are filled when binaries are fetched (`TBD_*` placeholders until then).
+
+### Fetch instructions
+
+Preferred (automated checksum verify):
+
+```bash
+scripts/build_switch.sh --fetch
+```
+
+That downloads pinned `love.nro` + `love.elf` into `.bazinga/love-nx/11.5-nx1/`
+and checks them against `scripts/switch/love-nx-11.5-nx1.sha256`. See
+[switch-build.md](switch-build.md) for the full mode glossary.
+
+Manual fallback:
+
+1. Open the [11.5-nx1 release](https://github.com/retronx-team/love-nx/releases/tag/11.5-nx1) and download `love.nro` and `love.elf`.
+2. Create the directory: `mkdir -p .bazinga/love-nx/11.5-nx1`
+3. Move both files into that directory.
+4. Confirm checksums match the manifest:
+
+   ```bash
+   shasum -a 256 .bazinga/love-nx/11.5-nx1/love.nro \
+     .bazinga/love-nx/11.5-nx1/love.elf
+   ```
+
+**Never commit** love-nx binaries, ROM dumps, or generated cache into git. The repo `.gitignore` excludes `.bazinga/` (vendor cache) and `/dist/` (build output).
+
+## Loose-mode dist layout
+
+Development builds place `gen1recomp.nro` and `game.love` side by side:
+
+```text
+dist/switch/loose/
+├── gen1recomp.nro
+└── game.love
+```
+
+Assemble with:
+
+```bash
+scripts/build_switch.sh --loose
+```
+
+(See `scripts/switch/assemble_loose.sh` for the underlying copy + checksum step.)
+
+## Transfer & deploy (current contributor loop)
+
+Detail for **macOS / Linux / Windows** and **MTP / SD / FTP** lives in
+[switch-transfer.md](switch-transfer.md). Summary:
+
+| Layer | Intent |
+| ----- | ------ |
+| **Runtime / players** | Extract the release zip at microSD root (`switch/gen1recomp/`) and land ROMs/mods under the save-dir inboxes. The game does not hard-depend on OpenMTP or macOS. |
+| **Contributor loop** | Manual copy via MTP (DBI responder), direct SD (Hekate UMS / reader), or FTP. Fully manual — no CI deploy, no `nxlink` yet. |
+
+The Mac + OpenMTP steps that remain below are the **OLED evidence reproduction** path; prefer the transfer runbook for day-to-day contrib on other hosts.
+
+**Still avoided for routine evidence** (keeps SD handling honest):
+
+- Treating `nxlink` / netloader as the release deploy story (deferred)
+- DBI `MicroSD install` / `NAND install` / NSP-style virtual folders for the `.love`/`.nro` pair
+
+If MTP fails: check cable, USB port, DBI state, and that only one MTP client holds the device — then retry or switch to SD/FTP. Do not silently rewrite evidence using an untested path and claim parity with recorded SHA-256 round-trips.
+
+### Manual deploy checklist (today)
+
+1. Build on the contributor host (`scripts/build_switch.sh --loose` or fused).
+2. Close Gen1Recomp on the Switch; open DBI → `Run MTP responder`.
+3. Copy artifacts with your MTP client into `1: SD Card/switch/gen1recomp/` (and ROMs/mods into the save-dir inboxes when needed).
+4. Wait for the transfer queue; refresh; optionally round-trip SHA-256 on first artifacts of a type.
+5. Exit MTP; launch via **title override** (hold **R** on a title → hbmenu, not Applet Mode).
+
+## OpenMTP + DBI transfer (loose build, Mac evidence example)
+
+Full multi-OS / multi-method steps: [switch-transfer.md](switch-transfer.md).
+The numbered Mac loop below reproduces the OLED evidence path.
+
+### On the Switch
+
+1. Close Gen1Recomp if it is running.
+2. Open **DBI** from hbmenu.
+3. Select **`Run MTP responder`** (DBI documents `X` on the main screen).
+4. Keep DBI on that screen for the entire transfer.
+5. Connect the Switch to the Mac with a USB-C data cable.
+
+### On the Mac
+
+1. Close any other MTP clients.
+2. Open **OpenMTP** and select the DBI device.
+3. In the remote pane, open **`1: SD Card`**.
+4. Navigate to **`switch/`** and create **`gen1recomp/`** if needed.
+5. Enter **`1: SD Card/switch/gen1recomp/`**.
+6. Drag from the local pane:
+
+   ```text
+   dist/switch/loose/gen1recomp.nro
+   dist/switch/loose/game.love
+   ```
+
+7. Wait for the OpenMTP queue to finish completely.
+8. Refresh the remote listing and confirm file sizes match the local files.
+9. On the Switch, exit MTP responder normally in DBI before launching the app.
+
+Expected layout on SD:
+
+```text
+1: SD Card/
+└── switch/
+    └── gen1recomp/
+        ├── gen1recomp.nro
+        └── game.love
+```
+
+## Round-trip SHA-256 verification
+
+For the **first deploy** of each artifact type (loose pair, later fused NRO), verify MTP integrity:
+
+1. **Before send** — record local hashes:
+
+   ```bash
+   shasum -a 256 dist/switch/loose/gen1recomp.nro \
+     dist/switch/loose/game.love
+   ```
+
+2. **After send** — in OpenMTP, copy the same files from `1: SD Card/switch/gen1recomp/` back to an empty local folder, e.g. `dist/switch/mtp-roundtrip/`.
+
+3. **Compare** round-trip hashes:
+
+   ```bash
+   shasum -a 256 dist/switch/mtp-roundtrip/gen1recomp.nro \
+     dist/switch/mtp-roundtrip/game.love
+   ```
+
+4. Local pre-send and round-trip hashes **must match**. Record results in the test report template below.
+
+Repeat whenever a cable glitch or interrupted transfer is suspected.
+
+## Title override launch (full memory)
+
+Applet Mode is **not** the primary validation path. Use **title override** so hbmenu runs with full memory:
+
+1. Confirm the OpenMTP transfer queue finished.
+2. Exit MTP responder in DBI; disconnect USB if desired.
+3. Hold **`R`** while launching any legitimately installed title.
+4. Keep holding until **hbmenu** appears.
+5. Confirm hbmenu does **not** show **Applet Mode**.
+6. Launch **`gen1recomp`** (or the probe NRO during Phase 0).
+
+Album / applet launches are only useful to document applet-specific limitations; P0/P1 gates use title override.
+
+## Phase 0 hardware checklist
+
+Complete **in order** on OLED hardware. Operator fills evidence fields — leave blank until tested.
+
+| Step | Action | Pass | Evidence / notes |
+| ---- | ------ | ---- | ---------------- |
+| P0-0a | Fetch love-nx 11.5-nx1; record manifest SHA-256 | yes | See `scripts/switch/love-nx-11.5-nx1.sha256` |
+| P0-0b | Build `switch-probe.love` per `tools/switch-probe/README.md` | yes | |
+| P0-0c | Assemble loose probe (`game.love` = probe) to `dist/switch/loose/` | yes | |
+| P0-0d | MTP deploy to `1: SD Card/switch/gen1recomp/`; round-trip SHA-256 | yes | nro `8290ac15…5918f5`; love `9f198637…fa2e34f` |
+| P0-0e | Title override → probe boots; `getOS()` shows `NX` | yes | `getOS()`=`NX`, `love._os`=`NX` |
+| P0-0f | Probe lists 1280×720 (or documented dims), save path, gamepad/touch log | yes | save `sdmc:/switch/gen1recomp/switch-probe`; Joy-Con Y→#3 X→#4 |
+| P0-1a | Replace `game.love` with unpatched Gen1Recomp build | yes | feat/switch-nx inbox build |
+| P0-1b | MTP replace `game.love` only; round-trip SHA-256 | yes | |
+| P0-1c | Title override → launcher reaches import screen | yes | |
+| P0-1d | Joy-Con: can navigate launcher (no touch-only) | yes | Full report: `docs/switch-hardware-evidence.md` |
+
+**Operator:** Andrew **Date:** 2026-08-01 **Console:** Switch OLED only  
+**Deploy:** manual Mac + OpenMTP + DBI MTP (not automated)  
+**love-nx tag:** 11.5-nx1 **gen1recomp commit:** `df7cea4`
+
+## Phase 0 test report template
+
+Copy this block into your hardware notes or PR evidence. **Do not commit ROM files or ROM hashes of private dumps.**
+
+```markdown
+## Switch Phase 0 — hardware report
+
+- Operator:
+- Date:
+- Console model:
+- Atmosphère / HOS version:
+- gen1recomp commit:
+- love-nx tag: 11.5-nx1
+- love.nro SHA-256 (local):
+- game.love SHA-256 (local, pre-send):
+- MTP round-trip SHA-256 (gen1recomp.nro):
+- MTP round-trip SHA-256 (game.love):
+- Title override used: yes / no
+- Applet Mode observed: yes / no (should be no for P0)
+- Probe getOS():
+- Probe dimensions:
+- Probe save directory shown:
+- Gamepad events logged: yes / no
+- Touch events logged: yes / no
+- Unpatched launcher boot: pass / fail
+- Joy-Con launcher navigation: pass / fail / not tested
+- Notes:
+```
+
+## Fast dev loop (loose mode)
+
+While iterating on Lua/assets:
+
+1. Edit on Mac; run `scripts/test.sh --quick`.
+2. Rebuild `.bazinga/work/game.love` (`scripts/build.sh mac --no-notarize` or project pack step).
+3. Close Gen1Recomp on Switch.
+4. DBI → `Run MTP responder`.
+5. OpenMTP → `1: SD Card/switch/gen1recomp/`.
+6. Replace **only** `game.love`; wait for queue + refresh listing.
+7. Exit MTP responder; launch via title override.
+8. Keep `gen1recomp.nro` unchanged until the love-nx pin changes.
+
+```bash
+scripts/test.sh --quick
+scripts/build.sh mac --no-notarize
+scripts/build_switch.sh --loose
+shasum -a 256 .bazinga/work/game.love
+```
+
+## Controller input mapping (NX)
+
+Measured on Switch OLED (`feat/switch-nx`, love-nx `11.5-nx1`, 1280×720). Both `joystickpressed` and `gamepadpressed` fire for Joy-Con; prefer the gamepad path when `joystick:isGamepad()` is true.
+
+| Path | Control | Mapping |
+| ---- | ------- | ------- |
+| `gamepadpressed` | D-pad / left stick | move |
+| `gamepadpressed` | SDL `a` / `b` on **NX** | swapped via `NX_GAMEPAD_BINDINGS`: physical **A** (east) = GB A confirm, physical **B** (south) = GB B cancel |
+| `gamepadpressed` | SDL `a` / `b` on desktop | identity (SDL south = GB A) |
+| `gamepadpressed` | `start` / `back` | Start / Select (+ / −) |
+| `gamepadpressed` | Right / left shoulder (no Select) | Cycle game speed up / down (same as PC hotkey `1` / speed-down path) |
+| `joystickpressed` (raw) | only if **not** `isGamepad()` | face/menu fallback |
+| `joystickpressed` (raw) | `#1` / `#2` on NX | Nintendo B / A → GB B / A |
+| `joystickpressed` (raw) | `#9` / `#10` | Select / Start (− / +) |
+
+**Nintendo UX on Switch:** physical A confirms, physical B cancels (explicit NX remap of SDL face labels).
+
+**Launcher extras** (`RomImporter`): physical **A** clicks at the virtual cursor; **L** / **R** switch tabs; **Start** / **Select** start Play when a ROM is ready (else open Choose ROM). D-pad / left stick move the virtual cursor.
+
+**Dual-path rule:** love-nx emits both `gamepadpressed` and `joystickpressed` for Joy-Con. When `joystick:isGamepad()` is true, Input and RomImporter **ignore raw** face/menu so NamingScreen does not see A+B in one frame. `NamingScreen` also prefers A over B if both edges still fire.
+
+Implementation: `src/core/GamepadMap.lua` (`NX_RAW_*`, `ignoreRawForJoystick`, `displayChordDigit`), `src/core/Game.lua` (shoulder speed), `src/import/RomImporter.lua` (launcher tabs). Launcher and gameplay share the same converter.
+
+## ROM inbox (NX)
+
+Legal dumps land in a shared MTP inbox; **Scan again** is tab-scoped:
+
+| Item | Value |
+| ---- | ----- |
+| Save-relative path | `imports/` (also accepts loose `.gb`/`.gbc` at the save-dir root) |
+| MTP destination | `1: SD Card/<save identity>/imports/` (see launcher notice for the live `getSaveDirectory()` path) |
+| Candidates | `*.gb` / `*.gbc` (hidden `.*` AppleDouble names skipped) |
+| Rescan | Game tab → **Scan again** — imports only the dump whose SHA-1 matches that tab (`GameVersion.forSha1`). Other known dumps stay for their own tabs |
+| Already ready | Same SHA already imported → “No new ROM found.” |
+
+Players may drop Red, Blue, and Yellow into the same folder. Opening Yellow and pressing **Scan again** must not start a Red import.
+
+## Mod zip inbox (NX)
+
+Community mods install from a **separate** MTP inbox (not mixed into the ROM `imports/` scan):
+
+| Item | Value |
+| ---- | ----- |
+| Save-relative path | `imports/mods/` |
+| MTP destination | `1: SD Card/<save identity>/imports/mods/` (see launcher notice for the live `getSaveDirectory()` path) |
+| Candidates | `*.zip` only |
+| Rescan | MODS tab → **Scan again** (installs each zip via `LauncherMods.installZip`; source zips are retained on success and failure) |
+| FIND MODS | Remains network-gated / hidden on NX (`networkValidated == false`) |
+
+Do **not** commit third-party mod zip bytes into git. Drop the zip over MTP, rescan, enable in MODS, then Play.
+
+**MTP tip (esp. macOS clients):** OpenMTP/Finder often creates AppleDouble sidecars named `._Something.zip` / `._cart.gb` / `._foo.sav`. Those are not real archives, ROMs, or saves — the launcher ignores hidden `.*` names under `imports/`, `imports/mods/`, and `imports/saves/<game>/`. If install still fails with “could not be opened” / “not a zip file”, delete any `._*` under the inbox and confirm the real zip starts with the `PK` magic (re-copy the release asset if unsure). This is a host-side annoyance of the current manual MTP loop, not something players should need forever.
+
+Drop any community release `.zip` into `imports/mods/`, rescan, enable.
+Player-facing install steps: [switch-install.md](switch-install.md#community-mods).
+Mods own their OPTIONS / rebinds — do not duplicate third-party control tables here.
+
+## Save `.sav` inbox (NX)
+
+Raw Gen1 battery images use a **separate** MTP inbox (not mixed into ROM `imports/` or mod `imports/mods/`):
+
+| Item | Value |
+| ---- | ----- |
+| Save-relative path | `imports/saves/red/`, `imports/saves/blue/`, `imports/saves/yellow/` |
+| MTP destination | `1: SD Card/<save identity>/imports/saves/<game>/` (see launcher notice for the live `getSaveDirectory()` path) |
+| Candidates | non-hidden `*.sav` only in **that game’s** folder |
+| Rescan | SAVE FILES → **Import save** on the matching game tab (scans only that folder) |
+| After success | Retire to `*.sav.imported` + append content hash to `imports/saves/<game>/.imported-sha1` |
+| Exports | **Export save** writes under `exports/<game>/gen1recomp-<game>-<slot>.sav`; NX shows an MTP path notice (no `openURL`) |
+
+Do **not** commit `.sav` bytes into git. Drop the file into the matching game folder over MTP, press **Import save** on that tab, then play. Pull exports from `exports/<game>/`.
+
+**MTP tip:** the same AppleDouble `._*.sav` rule applies — see the mod inbox tip above.
+
+## Joy-Con display chords (Select + face)
+
+PC digit hotkeys for COLORS / TILT / GBC FX / pipelines have Joy-Con equivalents. Hold **Select** (`back` / −) and press a face/shoulder button; the engine runs the same path as `Game:keypressed` for that digit (including `writeOptions` / Pipelines parity).
+
+| Chord (Nintendo UX) | Engine key | Stock engine effect |
+| ------------------- | ---------- | ------------------- |
+| Select + **A** | `2` | COLORS cycle |
+| Select + **B** | `3` | TILT / perspective |
+| Select + **Y** | `5` | GBC FX |
+| Select + **X** | `6` | Mod pipeline hotkey (if registered) |
+| Select + **L** (left shoulder) | `7` | Mod pipeline hotkey (if registered) |
+
+Keys `2` / `3` / `4` / `5` are claimed by the engine before mod pipeline hotkeys run, so a community mod cannot rebind those digits through `Pipelines.hotkey`. Mods that need their own controls should use OPTIONS rows or unclaimed hotkeys.
+
+Without Select held, face buttons keep normal GB A/B gameplay mapping (no accidental color/tilt cycles). The **Options** menu remains available for the same settings — chords are optional shortcuts, not the only path.
+
+On NX, A/B chords resolve through the Nintendo UX face remap so physical **A** → key `2` and physical **B** → key `3` match this table.
+
+**OPTIONS → PERFORMANCE** clamps the port’s own extras (TILT / GBC FX / survey ZOOM) and can cap FPS — useful on weaker handheld budgets. Details: [new-features.md — Performance tier](new-features.md#performance-tier-low-end-devices).
+
+Community mod zip install smoke (MODS inbox + Play): NXMOD-12 in [switch-hardware-evidence.md](switch-hardware-evidence.md).
+
+**Opt-in diagnostics:** create an empty `switch-debug.txt` in the save directory; events flush to `switch.log` at ≤1 Hz with build identity (no ROM/save bytes).
+
+**NX asset probe (always on Play):** every Switch Play writes `nx-asset-probe.log` in the save directory (`pokemon-love2d/`). It lists whether `assets/generated/…` vs `yellow|blue/assets/generated/…` exist, what `Assets.resolve` returns, and whether `newImage` / `newImageData` open — for Yellow/Blue blank-sprite triage. No ROM bytes.
+
+**Blue/Yellow cache overlay (NX):** fused love-nx cannot reliably mount `yellow|blue/assets/generated` onto the un-prefixed path, so `src/core/NxAssetOverlay.lua` wraps EVERY read-side love API that accepts a filesystem path (`filesystem.read/load/lines/newFileData/getInfo`, `graphics.newImage/newFont`, `image.newImageData`, `audio.newSource`, `sound.newSoundData`, `font.newFontData`) once at boot — only when `Platform.isNX()`. Covering the whole read surface (not just the loaders the boot needs today) keeps future states and mods inside the fallback automatically; write-side functions stay stock. Core code must NOT call love loaders on literal `assets/generated` paths (enforced by `tests/engine/nx_generated_guard_test.lua`); the chip-audio worker is a separate Lua state and gets the prefix explicitly via `audio.programPrefix` from `ChipAudio.slimAudio`.
+
+**Hardware re-test:** T16 **pass** @ `2699c9a` (naming A=confirm / B=cancel). T19 **pass** (quit/reopen, suspend×10, reboot) — operator 2026-08-01.
+
+**Suspend/resume audio:** after resume, chip music is stopped to avoid duplicate streams; confirm on hardware during P0-09/10 (T19).
+
+## Lua error log (save directory)
+
+On any uncaught Lua error, Gen1Recomp appends a redacted trace to `lua-error.log` in the LÖVE save directory (`love.filesystem.getSaveDirectory()`). The on-screen error overlay includes a hint pointing at that file. Logs rotate to `lua-error.log.1` when the active file exceeds 32 KiB. ROM/save bytes and non-printable data are stripped — never commit or share logs that might contain private paths without reviewing them first.
+
+## Native crash triage (love-nx / Atmosphère)
+
+love-nx native faults land under the console’s `crash_reports/` folder on SD (reachable via the same manual MTP workflow used for game deploys).
+
+1. **Collect** — DBI → `Run MTP responder`; copy `sdmc:/crash_reports/*.bin` (or the dated subfolder) to the contributor host. Prefer keeping the microSD in-console for routine pulls.
+2. **Redact** — delete any attached screenshots or notes that mention ROM filenames, save paths, or private hashes before sharing logs publicly.
+3. **Symbolize** — use the **pinned** `love.elf` from `.bazinga/love-nx/11.5-nx1/` that matches `build-info.json` / `scripts/switch/love-nx-11.5-nx1.sha256`. Never use a “latest” download.
+
+   ```bash
+   # Example: aarch64-none-elf-addr2line from devkitPro
+   aarch64-none-elf-addr2line -e .bazinga/love-nx/11.5-nx1/love.elf -f -C 0xADDRESS_FROM_CRASH_REPORT
+   ```
+
+4. **Correlate** — compare `gitCommit` / `loveNxTag` from embedded `build-info.json` with the operator’s hardware notes.
+
+If `addr2line` cannot resolve an address, archive the crash `.bin` with the exact `love.elf` SHA-256 used for the build — addresses are only meaningful against that ELF.
+
+## P0 / P1 hardware matrix (ADR §9)
+
+Operator evidence lives in `docs/switch-hardware-evidence.md`. **Do not invent passes** for rows that require hardware not yet run.
+
+| ID | Requirement | Status | Evidence |
+| -- | ----------- | ------ | -------- |
+| P0-0a–f | love-nx pin, probe, MTP, title override | **pass** | Phase 0 checklist above; T4 |
+| P0-1a–d | Unpatched launcher boot + Joy-Con nav | **pass** | T4 / `docs/switch-hardware-evidence.md` |
+| P0-02 | MTP inbox import path shown | **pass** | T12 |
+| P0-03 | Rescan imports ROM | **pass** | T12 |
+| P0-04 | Canonical hash routes version | **pass** | T12 |
+| P0-05 | Source dump retained in inbox | **pass** | T12 |
+| P0-06 | Play reaches game after import | **pass** | T12 |
+| P0-07 | Joy-Con launcher navigation | **pass** | T16 @ `2699c9a` |
+| P0-08 | Joy-Con gameplay (incl. naming A/B) | **pass** | T16 @ `2699c9a` |
+| P0-09 | Save survives quit + reopen | **pass** | T19 |
+| P0-10 | ≥10 suspend cycles, no stuck input/dup audio | **pass** | T19 (operator 2026-08-01) |
+| P0-12 | Fused NRO boots without adjacent `game.love` | **pass** | T24 — `docs/switch-hardware-evidence.md` |
+| P0-14 | Fused NRO MTP round-trip SHA-256 | **pass** | T24 — first artifact `b019e2e8…` @ `6fb5602` (redeploy after Blue fix) |
+| P0-15 | Replace NRO only; saves persist | **pass** | T24 — operator NRO-only update keeps saves |
+| P1-01 | Docked vs handheld spot-check | **deferred** | Code: `NxDisplay` 720p↔1080p; OLED dock soak not recorded yet |
+| P1-02 | Applet Mode documented unsupported | **pass** | Title override required; Album path not validated |
+| P1-03 | Long-play soak (≥30 min) | **deferred** | No soak session recorded |
+| P1-04 | Reboot persistence | **pass** | T19 |
+| P1-05 | Audio resume after suspend | **pass** | T19 (no dup audio reported) |
+| — | Switch V1 / Erista boot | **pass** (boot) | Community — [booshankles](https://github.com/booshankles); see evidence log |
+| — | Switch Lite / docked soak | **untested** / **deferred** | Welcome contributions |
+| — | Automated / `nxlink` deploy | **absent** | Manual MTP / SD / FTP only (AD-009) |
+| — | Multi-OS transfer runbooks | **pass** | [switch-transfer.md](switch-transfer.md) |
+| — | Community mod zip OLED smoke (NXMOD-12) | **pass** | `docs/switch-hardware-evidence.md` |
+
+## Review guidance
+
+Maintainers may review as one PR or split later. Suggested slices (optional):
+
+Each slice should declare: **no ROM/save bytes committed**, **love-nx pin with manifest checksums**, **hardware-tested rows listed with linked evidence**, **Applet Mode unsupported**, **network/updater disabled on NX**, **deploy still manual** (MTP / SD / FTP; no nxlink yet), **OpenMTP is one example not the sole contract**.
+
+### Slice 1 — Platform + import (`platform/import`)
+
+- `src/core/Platform.lua`, `conf.lua` NX branch
+- `src/import/RomImporter.lua` (NX flags, inbox, scan, shell/updater gates)
+- Tests: `tests/engine/platform_nx_*`, `tests/engine/rom_importer_nx_*` (ROM-free T2)
+- Docs: inbox/MTP import sections only
+
+### Slice 2 — Input + lifecycle (`input/lifecycle`)
+
+- `src/core/GamepadMap.lua`, `Input.lua`, `main.lua` focus/joystick hooks
+- `src/debug/SwitchDiagnostics.lua` (opt-in probe + error log)
+- Tests: input/diagnostics suites
+- Docs: controller mapping, suspend/audio notes
+
+### Slice 3 — Build + docs (`build/docs`)
+
+- `scripts/pack_love.sh`, `scripts/build_switch.sh`, `scripts/switch/*`
+- `assets/switch/icon.jpg`, `docs/switch-development.md`, hardware evidence templates
+- Gates: `pack_love.sh --dry-run`, `verify_payload.sh --self-test`, fused build script (devkitPro host)
+
+**Pre-merge checklist:**
+
+- [ ] Manifest `scripts/switch/love-nx-11.5-nx1.sha256` filled; binaries not in git
+- [ ] `verify_payload.sh` rejects generated cache / ROM / `.sav` / `.bak`
+- [ ] P0 matrix rows marked pass only with linked hardware evidence
+- [x] Fused NRO P0-12/14/15 pass with T24 evidence (`docs/switch-hardware-evidence.md`)
+- [ ] Updater / remote mod download hidden on NX (`networkValidated == false`)
+

docs/switch-hardware-evidence.md

@@ -0,0 +1,187 @@
+# Switch hardware evidence (Phase 0 + import + input)
+
+> **Hardware evidence log.** Author passes below were recorded on **one
+> Nintendo Switch OLED** with a **manual** Mac → DBI MTP deploy loop. A
+> separate community row records Switch V1 / Erista boot. These rows do
+> **not** claim Lite, docked soak, or automated install. See
+> `docs/switch-development.md` for status and limitations.
+
+**love-nx:** `11.5-nx1`  
+**Author console:** Switch OLED  
+**Deploy method (author):** manual OpenMTP + DBI `Run MTP responder` (no CI / no nxlink)  
+**Operator (author rows):** Andrew ([andrewqsantos](https://github.com/andrewqsantos))  
+**Date (author rows):** 2026-08-01  
+
+Do **not** commit ROM dumps or private dump hashes. Do **not** mark a row **pass** without hardware notes for that row.
+
+---
+
+## Community — Switch V1 / Erista boot — pass (boot)
+
+| Field | Value |
+| ----- | ----- |
+| Console | Nintendo Switch V1 (Erista) |
+| Check | Prebuilt fused NRO boots under title override |
+| Tester | [booshankles](https://github.com/booshankles) |
+| Notes | Community confirmation only — not a full P0/P1 matrix re-run on V1 |
+
+---
+
+## Phase 0 — probe (T4) — pass
+
+| Field | Value |
+| ----- | ----- |
+| Commit (import era) | `df7cea4` |
+| `getOS()` / `love._os` | `NX` |
+| Dimensions | 1280×720 |
+| Save (probe) | `sdmc:/switch/gen1recomp/switch-probe` |
+| Joy-Con | `joystickpressed` + `gamepadpressed` (Y→`#3`, X→`#4`) |
+
+| Artifact | SHA-256 |
+| -------- | ------- |
+| `gen1recomp.nro` | `8290ac153d4c630e48c9b26ef9123f5204ed8ee0cef3042511707b5b645918f5` |
+
+---
+
+## T12 — Red import + Play — pass
+
+Inbox MTP → “Scan again” → Play; Joy-Con launcher/gameplay (not touch-only).
+
+---
+
+# T16 — Joy-Con launcher + gameplay — pass (naming re-verify)
+
+### Round 1 @ `7504753` — partial
+
+| Check | Result |
+| ----- | ------ |
+| Launcher / overworld (Joy-Con only) | **pass** |
+| Naming player/rival | **fail** (dual-path a+b; see below) |
+| Touch required | **no** |
+| `game.love` SHA-256 | `bd3a35461bf453c1f0465a5a289421aef3b5c72d3bf1f8d76e86231256829e0e` |
+
+### Naming failure (root cause) — fixed in `efd81d8` + `2699c9a`
+
+- love-nx fires **`gamepadpressed` + `joystickpressed` on the same physical press**.
+- `NamingScreen` tested `wasPressed("b")` before `"a"` → if both true in one frame, always deletes.
+- Dual-path fix: ignore raw when `isGamepad()` (`efd81d8`).
+- SDL-only UX then had physical B confirm / A erase; NX face remap (`2699c9a`) restores Nintendo A=confirm / B=cancel.
+
+### Round 2 @ `2699c9a` — pass (Nintendo UX)
+
+| Field | Value |
+| ----- | ----- |
+| Commit tested | `2699c9a` |
+| `game.love` SHA-256 | `a208b21e1f30b00e2e8c6fa6efe14f0e06d1db0ae1e50b810b16d9fb852926bc` |
+| Touch required | **no** |
+
+| Check | Result |
+| ----- | ------ |
+| Naming — player | **pass** — physical **A** confirms letter, **B** cancels/erases |
+| Naming — rival | **pass** (same) |
+| Launcher / overworld (prior round) | **pass** (unchanged mapping for d-pad/stick) |
+
+T16 hardware gate: **closed**.
+
+---
+
+## T19 — save / suspend — pass
+
+| Check | Result |
+| ----- | ------ |
+| Save in-game → full quit → title-override reopen → load save | **pass** (@ `7504753` / retained) |
+| Suspend/resume ×10 (launcher / gameplay / mixed) | **pass** (operator 2026-08-01) |
+| Full console reboot persistence | **pass** (operator 2026-08-01) |
+
+T19 hardware gate: **closed**. No stuck input, duplicate audio, or crash reported.
+
+---
+
+## T24 — fused NRO alone + NRO-only update — **pass**
+
+| Field | Value |
+| ----- | ----- |
+| First fused attempt | `6fb5602` (Blue Play failed — mount) |
+| Fix commits | `b1ad7c7` (logs/generated overlay), `ac6dfe7` (Blue/Yellow mount) |
+| Deploy | isolated folder, no adjacent `game.love` |
+| Boot fused | **pass** |
+| ROM import | **pass** |
+| Play **Red** | **pass** |
+| Play **Blue** (after `ac6dfe7`) | **pass** (operator 2026-08-01) |
+| NRO-only replace | **pass** — saves retained; app still boots/plays |
+| Touch required | no |
+
+T24 hardware gate: **closed**.
+
+---
+
+## SWBLD — `build_switch.sh --fetch --fused` + install path — **pass**
+
+Operator smoke for the switch-build-pipeline packaging CLI (closes matrix-deferred happy paths from validation).
+
+| Field | Value |
+| ----- | ----- |
+| Command | `scripts/build_switch.sh --fetch --fused --version 0.0.0-test` |
+| Host | macOS + native switch-tools (or Docker fallback if used) |
+| Commit / build-info | `9147a64` (`gitCommit` in build-info) |
+| love-nx | `11.5-nx1` (manifest checksums match) |
+| Artifact | `dist/switch/gen1recomp-0.0.0-test-switch.nro` |
+| NRO SHA-256 | `210efb884a8d27443dc1c64ed8f071b0f862d8d0c9b140ad8185093c4e4027db` |
+| Install doc | `docs/switch-install.md` — at the time of this row: copy NRO under `sdmc:/switch/gen1recomp/` (releases now ship an SD-ready zip; same folder) |
+| Console | Switch OLED |
+| Operator | Andrew |
+| Date | 2026-08-01 |
+
+| Check | Result |
+| ----- | ------ |
+| `--fetch` + `--fused` produce NRO + `.sha256` | **pass** |
+| Copy NRO to SD folder per install doc | **pass** (operator) |
+| Title-override launch / play | treated as prior T24 path; this row records **packaging + deploy to folder** success |
+
+SWBLD packaging smoke: **closed** for Mac fused build + file-to-SD install step.
+
+---
+
+## NXMOD-12 — Community mod zip OLED smoke — **pass**
+
+Closed from existing OLED photo evidence on issue
+[#531](https://github.com/bryanthaboi/gen1recomp/issues/531) (operator comment
+with launcher MODS + overworld shots). Photos live on the orphan branch
+[`switch-oled-photos`](https://github.com/andrewqsantos/gen1recomp/tree/switch-oled-photos)
+of the operator fork — **not** committed to this repo. Do **not** commit
+third-party mod `.zip` bytes. Community mods own their OPTIONS / rebinds;
+this entry only proves the MODS inbox + Play path on OLED.
+
+| Field | Value |
+| ----- | ----- |
+| Status | **pass** |
+| gen1recomp commit | evidence era on `feat/switch-nx` (see #531); packaging pin love-nx `11.5-nx1` |
+| love-nx tag | `11.5-nx1` |
+| Console | Switch OLED |
+| Mod | community release `.zip` (not vendored; not named here) |
+| Zip committed to git? | **no** |
+| Photo evidence | [#531 comment](https://github.com/bryanthaboi/gen1recomp/issues/531) — MODS tab + overworld |
+| MODS tab photo | https://raw.githubusercontent.com/andrewqsantos/gen1recomp/switch-oled-photos/IMG_1766.jpg |
+| Overworld photo | https://raw.githubusercontent.com/andrewqsantos/gen1recomp/switch-oled-photos/IMG_1771.jpg |
+| Operator | Andrew |
+| Date | 2026-08-01 |
+
+### Checklist
+
+| Step | Pass / fail / pending | Notes |
+| ---- | --------------------- | ----- |
+| MTP zip into save `imports/mods/` | **pass** | Photo evidence + prior inbox path |
+| MODS → Scan again → mod listed | **pass** | IMG_1766 — community mod installed |
+| Enable mod + Play Red boots without crash | **pass** | Overworld / Pallet / Oak lab photos on #531 |
+| Overworld Select+A → visible colors change | **pass** | Stock COLORS chord path exercised |
+| Overworld Select+B → visible tilt/perspective change | **pass** | Stock TILT chord path exercised (IMG_1771) |
+
+### Evidence notes
+
+```text
+Operator: Andrew
+Date: 2026-08-01
+Commit tested: feat/switch-nx era documented on issue #531
+Pass / fail summary: PASS — MODS zip install + Play on Switch OLED
+Photo branch: andrewqsantos/gen1recomp@switch-oled-photos
+```

docs/switch-install.md

@@ -0,0 +1,164 @@
+# 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. Tracks issue
+> [#531](https://github.com/bryanthaboi/gen1recomp/issues/531).
+> Hardware: **OLED** validated by the porter; **V1 / Erista** boot confirmed
+> by the community. Lite and other setups welcome more reports.
+> See [switch-development.md](switch-development.md) for limitations.
+
+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
+sdmc:/switch/gen1recomp/pokemon-love2d/imports/
+sdmc:/switch/gen1recomp/pokemon-love2d/imports/mods/
+sdmc:/switch/gen1recomp/pokemon-love2d/imports/saves/...
+```
+
+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
+
+Use the **same** extract/merge. It replaces `gen1recomp.nro` (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 — [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`. Full chord notes for contributors:
+[switch-development.md](switch-development.md#joy-con-display-chords-select--face).
+
+## 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).
+Status, limitations, and how we tested: [switch-development.md](switch-development.md).

docs/switch-transfer.md

@@ -0,0 +1,168 @@
+# Switch file transfer (MTP / SD / FTP)
+
+Canonical 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 home 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). Hardware evidence lives in
+[switch-hardware-evidence.md](switch-hardware-evidence.md).
+
+> **Not supported yet:** `nxlink` / hbmenu netloader automation. Useful later
+> for a fast contrib rebuild loop; deferred on purpose (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.
+
+---
+
+## Canonical 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 the loop used for OLED
+hardware evidence — **one contributor example**, not a Mac-only product rule.
+
+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)
+- Status / hardware matrix: [switch-development.md](switch-development.md)
+- Evidence log: [switch-hardware-evidence.md](switch-hardware-evidence.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.

main.lua

@@ -10,6 +10,24 @@
 
 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
 
 local autopilot -- optional scripted-input dev tool (tests/autopilot.lua)
@@ -103,6 +121,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 +152,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 +168,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 +181,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 +193,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 +225,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 +256,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 +314,38 @@ 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.
+  local launchGame, launchSlot = LaunchOptions.resolve(arg)
+  if launchGame and not LaunchOptions.forceLauncher(arg) then
+    if RomImporter.isReady(launchGame) then
+      if launchSlot then LaunchOptions.selectSlot(launchGame, launchSlot) end
+      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 +363,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 +440,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 +585,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 +595,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 +625,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 +639,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 +651,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)
@@ -469,32 +675,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 +712,24 @@ 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 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,10 +740,31 @@ 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
   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")
+  if Game and not Importer and not quitToLauncher and not scripted then
+    quitToLauncher = true
+    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()
   end)
@@ -544,6 +778,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

@@ -253,6 +253,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;
@@ -565,6 +567,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 /

mobile/ios/app-repo.json

@@ -0,0 +1,67 @@
+{
+  "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.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/uwp/BUILD.md

@@ -0,0 +1,119 @@
+# Gen1Recomp Xbox UWP build notes
+
+This is the Xbox Dev Mode package for Gen1Recomp.
+
+The rough shape is:
+
+- `Gen1RecompUWP.exe` starts LÖVE through SDL's WinRT wrapper
+- the bundled LÖVE 11.5 UWP backend provides LuaJIT and the Xbox file picker
+- the bundled SDL2 runtime contains the Xbox controller mapping
+- ANGLE provides OpenGL ES over D3D11
+- the bundled runtime contains the audio, font, video, and compression libraries
+
+## What You Need
+
+The tested toolchain is:
+
+- Visual Studio 2022 17.14
+- MSVC v143 x64/x86 build tools
+- C++ Universal Windows Platform tools
+- Windows 11 SDK `10.0.26100.0`
+- CMake 3.24 or newer
+- Git for Windows
+- Info-ZIP `zip` and `unzip`
+
+Use Visual Studio Installer to add **Universal Windows Platform development**, the v143 C++ tools, CMake tools for Windows, and Windows SDK `10.0.26100.0`.
+
+The x64 UWP dependencies are committed under `third_party`. Their versions,
+source revisions, licences, and hashes are recorded in `third_party/manifest.json`.
+No additional checkout or environment variable is required for a normal game
+build.
+
+## Rebuild the Dependencies
+
+Run the dependency rebuild from the repository root:
+
+```powershell
+.\scripts\xbox-uwp\rebuild_dependencies.ps1
+```
+
+The script clones the pinned SDL2, LÖVE, LuaJIT, vcpkg, depot_tools, and ANGLE
+sources when they are missing. It applies the Xbox SDL2 patch, builds the x64
+UWP Release libraries, stages the required DLLs, import libraries, headers, and
+licences under `third_party`, updates every SHA-256 entry in the manifest, then
+builds the Release MSIX.
+
+The generated source checkouts are ignored by Git. A fresh ANGLE sync is about
+10 GB, so allow at least 20 GB of free disk space for all sources and build
+outputs. Use `-SkipAngle` to retain the existing pinned ANGLE runtime while
+rebuilding SDL2, LÖVE, LuaJIT, and the vcpkg libraries. Use `-SkipPackage` when
+only the dependency bundle needs to be refreshed. The rebuild stops if a source
+checkout has local changes. Remove that generated `source` directory to restore
+the pinned revision.
+
+## Build the MSIX
+
+Run the Xbox build from Git Bash at the repository root:
+
+```bash
+scripts/build_xbox_uwp.sh --release --version 1.2.3
+```
+
+The build uses `scripts/pack_love.sh` to create and verify the same ROM-free
+`game.love` payload used by the other release targets. It then links the UWP
+host and stages LÖVE, LuaJIT, SDL2, ANGLE, and the vcpkg runtime DLLs.
+
+Use `--relwithdebinfo` for a package with symbols. To package a `.love` produced
+by another build or downloaded from CI, pass `--game-love path/to/game.love`.
+The upstream `X.Y.Z` release becomes `X.Y.Z.0` in the generated MSIX manifest.
+Neither the manifest template nor `src/core/Version.lua` is edited in place.
+
+The manifest publisher must match the signing certificate subject. Pass it
+when preparing a signed package:
+
+```bash
+scripts/build_xbox_uwp.sh --release --version 1.2.3 \
+  --publisher "CN=Gen1Recomp"
+```
+
+The normal build is unsigned. Release CI supplies the private PFX and password
+from `XBOX_UWP_SIGNING_CERTIFICATE` and `XBOX_UWP_SIGNING_PASSWORD`; neither may
+be committed. The public certificate is safe to include with the release.
+
+Run the offline packaging checks from Git Bash:
+
+```bash
+bash scripts/xbox-uwp/selftest_build_xbox_uwp.sh
+```
+
+## Build Output
+
+Visual Studio package output lands under:
+
+```text
+ports\uwp\build\release\AppPackages\Gen1RecompUWP
+```
+
+The build also stages the distributable archive and checksum under:
+
+```text
+dist\xbox-uwp\gen1recomp-X.Y.Z-xbox-uwp.zip
+dist\xbox-uwp\gen1recomp-X.Y.Z-xbox-uwp.zip.sha256
+```
+
+The archive contains the MSIX, framework dependencies, build provenance and,
+for a signed release, the public certificate. The third-party notices are
+packaged inside the MSIX. Install the MSIX and dependency packages through
+Xbox Device Portal.
+
+## Runtime Data
+
+The package contains no ROM, generated cache, save or mod data. The Xbox file
+picker copies user-selected files into LocalState and the launcher imports them
+from there. Saves, ROM cache and installed mods remain under the LÖVE save
+directory in LocalState.
+
+LuaJIT requires the `codeGeneration` capability. `removableStorage` exposes
+external media to the Xbox picker. The network capabilities support relay play
+and direct hosting. The package does not request full trust or broad filesystem
+access.

ports/uwp/CMakeLists.txt

@@ -0,0 +1,149 @@
+cmake_minimum_required(VERSION 3.24)
+project(Gen1RecompUWP LANGUAGES CXX)
+
+if(NOT CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
+    message(FATAL_ERROR "Configure with a WindowsStore preset.")
+endif()
+
+get_filename_component(GAME_ROOT "${CMAKE_CURRENT_LIST_DIR}/../.." ABSOLUTE)
+set(THIRD_PARTY_ROOT "${CMAKE_CURRENT_LIST_DIR}/third_party")
+set(LOVE_ROOT "${THIRD_PARTY_ROOT}/love")
+set(SDL2_ROOT "${THIRD_PARTY_ROOT}/sdl2")
+set(ANGLE_ROOT "${THIRD_PARTY_ROOT}/angle")
+set(RUNTIME_ROOT "${THIRD_PARTY_ROOT}/runtime")
+
+set(GEN1RECOMP_VERSION "0.0.0" CACHE STRING "Gen1Recomp release version")
+if(NOT GEN1RECOMP_VERSION MATCHES "^[0-9]+\\.[0-9]+\\.[0-9]+$")
+    message(FATAL_ERROR "GEN1RECOMP_VERSION must use X.Y.Z format.")
+endif()
+string(REPLACE "." ";" VERSION_PARTS "${GEN1RECOMP_VERSION}")
+foreach(part IN LISTS VERSION_PARTS)
+    if(part GREATER 65535)
+        message(FATAL_ERROR "MSIX version components cannot exceed 65535.")
+    endif()
+endforeach()
+set(GEN1RECOMP_UWP_PUBLISHER "CN=Gen1Recomp" CACHE STRING
+    "Publisher subject from the MSIX signing certificate")
+set(UWP_PUBLISHER_XML "${GEN1RECOMP_UWP_PUBLISHER}")
+string(REPLACE "&" "&" UWP_PUBLISHER_XML "${UWP_PUBLISHER_XML}")
+string(REPLACE "\"" """ UWP_PUBLISHER_XML "${UWP_PUBLISHER_XML}")
+string(REPLACE "<" "&lt;" UWP_PUBLISHER_XML "${UWP_PUBLISHER_XML}")
+string(REPLACE ">" "&gt;" UWP_PUBLISHER_XML "${UWP_PUBLISHER_XML}")
+set(UWP_PACKAGE_VERSION "${GEN1RECOMP_VERSION}.0")
+set(PACKAGE_MANIFEST "${CMAKE_CURRENT_BINARY_DIR}/Package.appxmanifest")
+configure_file(
+    "${CMAKE_CURRENT_LIST_DIR}/Package.appxmanifest.in"
+    "${PACKAGE_MANIFEST}"
+    @ONLY
+)
+
+set(REQUIRED_FILES
+    "${THIRD_PARTY_ROOT}/manifest.json"
+    "${LOVE_ROOT}/lib/lovestatic.lib"
+    "${LOVE_ROOT}/lib/liblove.lib"
+    "${LOVE_ROOT}/lib/lua51.lib"
+    "${LOVE_ROOT}/bin/love.dll"
+    "${LOVE_ROOT}/bin/lua51.dll"
+    "${SDL2_ROOT}/include/SDL2/SDL.h"
+    "${SDL2_ROOT}/lib/SDL2.lib"
+    "${SDL2_ROOT}/bin/SDL2.dll"
+    "${ANGLE_ROOT}/bin/libEGL.dll"
+    "${ANGLE_ROOT}/bin/libGLESv2.dll"
+    "${ANGLE_ROOT}/bin/d3dcompiler_47.dll"
+)
+foreach(path IN LISTS REQUIRED_FILES)
+    if(NOT EXISTS "${path}")
+        message(FATAL_ERROR "Missing UWP dependency: ${path}")
+    endif()
+endforeach()
+
+set(GEN1RECOMP_LOVE "${GAME_ROOT}/.bazinga/work/game.love" CACHE FILEPATH
+    "Path to the game.love payload produced by scripts/pack_love.sh")
+if(NOT EXISTS "${GEN1RECOMP_LOVE}")
+    message(FATAL_ERROR
+        "Missing game.love payload: ${GEN1RECOMP_LOVE}\n"
+        "Build it with scripts/build_xbox_uwp.sh or scripts/pack_love.sh.")
+endif()
+
+set(GAME_ARCHIVE "${CMAKE_CURRENT_BINARY_DIR}/gen1recomp.love")
+add_custom_command(
+    OUTPUT "${GAME_ARCHIVE}"
+    COMMAND "${CMAKE_COMMAND}" -E copy_if_different
+        "${GEN1RECOMP_LOVE}" "${GAME_ARCHIVE}"
+    DEPENDS "${GEN1RECOMP_LOVE}"
+    VERBATIM
+)
+add_custom_target(gen1recomp_love ALL DEPENDS "${GAME_ARCHIVE}")
+set_source_files_properties("${GAME_ARCHIVE}" PROPERTIES GENERATED TRUE)
+
+add_custom_target(verify_uwp_dependencies
+    COMMAND powershell -NoProfile -ExecutionPolicy Bypass -File
+        "${GAME_ROOT}/scripts/xbox-uwp/verify_dependencies.ps1"
+    VERBATIM
+)
+
+add_executable(${PROJECT_NAME} WIN32 "app/main.cpp")
+add_dependencies(${PROJECT_NAME} gen1recomp_love verify_uwp_dependencies)
+set_target_properties(${PROJECT_NAME} PROPERTIES
+    CXX_STANDARD 17
+    CXX_STANDARD_REQUIRED YES
+    VS_GLOBAL_DefaultLanguage "en-US"
+    VS_SDK_REFERENCES "Microsoft.VCLibs, Version=14.0"
+)
+target_include_directories(${PROJECT_NAME} PRIVATE "${SDL2_ROOT}/include/SDL2")
+target_link_libraries(${PROJECT_NAME} PRIVATE
+    "${LOVE_ROOT}/lib/lovestatic.lib"
+    "${LOVE_ROOT}/lib/liblove.lib"
+    "${SDL2_ROOT}/lib/SDL2.lib"
+    "${LOVE_ROOT}/lib/lua51.lib"
+    WindowsApp.lib
+)
+
+set(PACKAGE_ROOT_FILES
+    "${PACKAGE_MANIFEST}"
+    "${GAME_ARCHIVE}"
+    "${LOVE_ROOT}/bin/love.dll"
+    "${LOVE_ROOT}/bin/lua51.dll"
+    "${SDL2_ROOT}/bin/SDL2.dll"
+    "${ANGLE_ROOT}/bin/libEGL.dll"
+    "${ANGLE_ROOT}/bin/libGLESv2.dll"
+    "${ANGLE_ROOT}/bin/d3dcompiler_47.dll"
+)
+set_source_files_properties("${PACKAGE_MANIFEST}" PROPERTIES GENERATED TRUE)
+
+set(RUNTIME_NAMES
+    brotlicommon.dll brotlidec.dll bz2.dll fmt.dll freetype.dll libpng16.dll
+    OpenAL32.dll theora.dll theoradec.dll vorbis.dll vorbisfile.dll ogg.dll z.dll
+)
+foreach(name IN LISTS RUNTIME_NAMES)
+    set(runtime "${RUNTIME_ROOT}/bin/${name}")
+    if(NOT EXISTS "${runtime}")
+        message(FATAL_ERROR "Missing UWP runtime DLL: ${name}")
+    endif()
+    list(APPEND PACKAGE_ROOT_FILES "${runtime}")
+endforeach()
+
+set_source_files_properties(${PACKAGE_ROOT_FILES} PROPERTIES
+    VS_COPY_TO_OUT_DIR Always
+    VS_DEPLOYMENT_CONTENT TRUE
+    VS_DEPLOYMENT_LOCATION "."
+)
+
+file(GLOB PACKAGE_ASSETS CONFIGURE_DEPENDS "${CMAKE_CURRENT_LIST_DIR}/Assets/*.png")
+set_source_files_properties(${PACKAGE_ASSETS} PROPERTIES
+    VS_DEPLOYMENT_CONTENT TRUE
+    VS_DEPLOYMENT_LOCATION "Assets"
+)
+
+file(GLOB PACKAGE_LICENSES CONFIGURE_DEPENDS "${THIRD_PARTY_ROOT}/licenses/*.txt")
+set_source_files_properties(${PACKAGE_LICENSES} PROPERTIES
+    VS_TOOL_OVERRIDE "Content"
+    VS_COPY_TO_OUT_DIR Always
+    VS_DEPLOYMENT_CONTENT TRUE
+    VS_DEPLOYMENT_LOCATION "licenses"
+)
+target_sources(${PROJECT_NAME} PRIVATE
+    ${PACKAGE_ROOT_FILES}
+    ${PACKAGE_ASSETS}
+    ${PACKAGE_LICENSES}
+)

ports/uwp/CMakePresets.json

@@ -0,0 +1,41 @@
+{
+  "version": 6,
+  "configurePresets": [
+    {
+      "name": "uwp-common",
+      "hidden": true,
+      "generator": "Visual Studio 17 2022",
+      "architecture": "x64",
+      "cacheVariables": {
+        "CMAKE_SYSTEM_NAME": "WindowsStore",
+        "CMAKE_SYSTEM_VERSION": "10.0"
+      }
+    },
+    {
+      "name": "uwp-relwithdebinfo",
+      "inherits": "uwp-common",
+      "displayName": "Gen1Recomp Xbox UWP (RelWithDebInfo)",
+      "binaryDir": "${sourceDir}/build/relwithdebinfo"
+    },
+    {
+      "name": "uwp-release",
+      "inherits": "uwp-common",
+      "displayName": "Gen1Recomp Xbox UWP (Release)",
+      "binaryDir": "${sourceDir}/build/release"
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "uwp-relwithdebinfo",
+      "configurePreset": "uwp-relwithdebinfo",
+      "configuration": "RelWithDebInfo",
+      "jobs": 8
+    },
+    {
+      "name": "uwp-release",
+      "configurePreset": "uwp-release",
+      "configuration": "Release",
+      "jobs": 8
+    }
+  ]
+}

ports/uwp/Package.appxmanifest.in

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Package
+  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
+  xmlns:mp="http://schemas.microsoft.com/appx/2014/phone/manifest"
+  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
+  IgnorableNamespaces="uap mp">
+  <Identity Name="Gen1RecompUWP" Publisher="@UWP_PUBLISHER_XML@" Version="@UWP_PACKAGE_VERSION@" />
+  <mp:PhoneIdentity PhoneProductId="5074018d-a46b-4dd3-b7fa-93a1e39858ad" PhonePublisherId="00000000-0000-0000-0000-000000000000" />
+  <Properties>
+    <DisplayName>Gen1Recomp</DisplayName>
+    <PublisherDisplayName>Gen1Recomp</PublisherDisplayName>
+    <Logo>Assets\StoreLogo.png</Logo>
+  </Properties>
+  <Dependencies>
+    <TargetDeviceFamily Name="Windows.Universal" MinVersion="10.0.19041.0" MaxVersionTested="10.0.26100.0" />
+  </Dependencies>
+  <Resources>
+    <Resource Language="x-generate" />
+  </Resources>
+  <Applications>
+    <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="Gen1RecompUWP.App">
+      <uap:VisualElements
+        DisplayName="Gen1Recomp"
+        Description="Gen1Recomp for Xbox Dev Mode"
+        BackgroundColor="#101820"
+        Square150x150Logo="Assets\Square150x150Logo.png"
+        Square44x44Logo="Assets\Square44x44Logo.png">
+        <uap:DefaultTile
+          Square71x71Logo="Assets\SmallTile.png"
+          Wide310x150Logo="Assets\WideTile.png"
+          Square310x310Logo="Assets\LargeTile.png" />
+        <uap:SplashScreen Image="Assets\SplashScreen.png" BackgroundColor="#101820" />
+      </uap:VisualElements>
+    </Application>
+  </Applications>
+  <Capabilities>
+    <Capability Name="internetClient" />
+    <Capability Name="internetClientServer" />
+    <Capability Name="privateNetworkClientServer" />
+    <Capability Name="codeGeneration" />
+    <uap:Capability Name="removableStorage" />
+  </Capabilities>
+</Package>

ports/uwp/app/main.cpp

@@ -0,0 +1,30 @@
+#include <Windows.h>
+#include <SDL.h>
+#include <string>
+#include <winrt/Windows.ApplicationModel.h>
+#include <winrt/Windows.Storage.h>
+
+extern "C" int SDL_main(int argc, char **argv);
+
+namespace
+{
+
+int runLove(int, char **)
+{
+    std::wstring packagePath = winrt::Windows::ApplicationModel::Package::Current()
+        .InstalledLocation().Path().c_str();
+    std::string gamePath = winrt::to_string(packagePath + L"\\gen1recomp.love");
+
+    char executable[] = "Gen1RecompUWP";
+    char fused[] = "--fused";
+    char *loveArgv[] = {executable, gamePath.data(), fused, nullptr};
+    return SDL_main(3, loveArgv);
+}
+
+} // namespace
+
+int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
+{
+    SDL_SetHint(SDL_HINT_WINRT_HANDLE_BACK_BUTTON, "1");
+    return SDL_WinRTRunApp(runLove, nullptr);
+}

ports/uwp/third_party/README.md

@@ -0,0 +1,11 @@
+# UWP dependencies
+
+This directory contains the complete x64 UWP Release dependency bundle used by the package build:
+
+- `love` contains the LÖVE 11.5 and LuaJIT binaries.
+- `sdl2` contains the matching SDL headers, import library, and runtime.
+- `angle` contains the EGL and GLES runtime.
+- `runtime` contains the codec, font, compression, and audio DLLs used by LÖVE.
+- `licenses` contains the corresponding third party notices.
+
+`manifest.json` pins the source revisions and SHA-256 hashes. Run `scripts/xbox-uwp/verify_dependencies.ps1` from the repository root after updating any dependency.

ports/uwp/third_party/angle/AUTHORS

@@ -0,0 +1,89 @@
+# This is the official list of The ANGLE Project Authors
+# for copyright purposes.
+# This file is distinct from the CONTRIBUTORS files.
+# See the latter for an explanation.
+
+# Names should be added to this file as
+#	Name or Organization
+# Email addresses for individuals are tracked elsewhere to avoid spam.
+
+Google Inc.
+TransGaming Inc.
+3DLabs Inc. Ltd.
+
+Adobe Systems Inc.
+Autodesk, Inc.
+BlackBerry Limited
+Cable Television Laboratories, Inc.
+Collabora, Ltd.
+Cloud Party, Inc.
+Igalia, S.L.
+Imagination Technologies Ltd.
+Intel Corporation
+LunarG, Inc.
+Mozilla Corporation
+Turbulenz
+Klarälvdalens Datakonsult AB
+Microsoft Corporation
+Microsoft Open Technologies, Inc.
+NVIDIA Corporation
+Opera Software ASA
+The Qt Company Ltd.
+Advanced Micro Devices, Inc.
+LG Electronics, Inc.
+IBM Inc.
+AdaptVis GmbH
+Samsung Electronics, Inc.
+Arm Ltd.
+Broadcom Inc.
+Facebook, Inc.
+The Khronos Group, Inc.
+Numfum GmbH
+Yandex LLC
+Rive
+Institute of Software, Chinese Academy of Sciences
+Guangdong OPPO Mobile Telecommunications Corp., Ltd
+Qualcomm Innovation Center, Inc.
+
+Jacek Caban
+Mark Callow
+Ginn Chen
+Tibor den Ouden
+Régis Fénéon
+James Hauxwell
+Sam Hocevar
+Pierre Leveille
+Jonathan Liu
+Boying Lu
+Aitor Moreno
+Yuri O'Donnell
+Josh Soref
+Ma Aiguo
+Maks Naumov
+Jinyoung Hur
+Sebastian Bergstein
+James Ross-Gowan
+Nickolay Artamonov
+Ihsan Akmal
+Andrei Volykhin
+Jérôme Duval
+Руслан Ижбулатов
+Thomas Miller
+Till Rathmann
+Nick Shaforostov
+Jaime Bernardo
+Le Hoang Quyen
+Lu Yahan
+Ethan Lee
+Renaud Lepage
+Artem Bolgar
+Wander Lairson Costa
+Stephan Hartmann
+SeongHwan Park
+Xiaopeng Li
+Akihiko Odaki
+Ho Cheung
+Tao Wang
+Phan Quang Minh
+Hongchen Yan
+Andrew Sumsion

ports/uwp/third_party/angle/LICENSE

@@ -0,0 +1,32 @@
+// Copyright 2018 The ANGLE Project Authors.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+//
+//     Redistributions of source code must retain the above copyright
+//     notice, this list of conditions and the following disclaimer.
+//
+//     Redistributions in binary form must reproduce the above
+//     copyright notice, this list of conditions and the following
+//     disclaimer in the documentation and/or other materials provided
+//     with the distribution.
+//
+//     Neither the name of TransGaming Inc., Google Inc., 3DLabs Inc.
+//     Ltd., nor the names of their contributors may be used to endorse
+//     or promote products derived from this software without specific
+//     prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+// POSSIBILITY OF SUCH DAMAGE.

ports/uwp/third_party/angle/README.md

@@ -0,0 +1,7 @@
+# ANGLE UWP runtime
+
+`libEGL.dll` and `libGLESv2.dll` were built for x64 UWP from [SternXD/angle](https://github.com/SternXD/angle) commit `45b0b1e03400b7a10aaa9a077e196d1abcddafce`. ANGLE version `2.1.25011` and source hash `45b0b1e03400`.
+
+`d3dcompiler_47.dll` is the x64 Direct3D HLSL compiler redistributable from Windows SDK `10.0.26100.7705`. Current hashes are recorded in `../manifest.json`.
+
+ANGLE's upstream `LICENSE` and `AUTHORS` files are included beside its binaries.

ports/uwp/third_party/licenses/angle.txt

@@ -0,0 +1,32 @@
+// Copyright 2018 The ANGLE Project Authors.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+//
+//     Redistributions of source code must retain the above copyright
+//     notice, this list of conditions and the following disclaimer.
+//
+//     Redistributions in binary form must reproduce the above
+//     copyright notice, this list of conditions and the following
+//     disclaimer in the documentation and/or other materials provided
+//     with the distribution.
+//
+//     Neither the name of TransGaming Inc., Google Inc., 3DLabs Inc.
+//     Ltd., nor the names of their contributors may be used to endorse
+//     or promote products derived from this software without specific
+//     prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+// POSSIBILITY OF SUCH DAMAGE.

ports/uwp/third_party/licenses/brotli.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2009, 2010, 2013-2016 by the Brotli Authors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

ports/uwp/third_party/licenses/bzip2.txt

@@ -0,0 +1,42 @@
+
+--------------------------------------------------------------------------
+
+This program, "bzip2", the associated library "libbzip2", and all
+documentation, are copyright (C) 1996-2019 Julian R Seward.  All
+rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. The origin of this software must not be misrepresented; you must 
+   not claim that you wrote the original software.  If you use this 
+   software in a product, an acknowledgment in the product 
+   documentation would be appreciated but is not required.
+
+3. Altered source versions must be plainly marked as such, and must
+   not be misrepresented as being the original software.
+
+4. The name of the author may not be used to endorse or promote 
+   products derived from this software without specific prior written 
+   permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Julian Seward, jseward@acm.org
+bzip2/libbzip2 version 1.0.8 of 13 July 2019
+
+--------------------------------------------------------------------------

ports/uwp/third_party/licenses/fmt.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2012 - present, Victor Zverovich and {fmt} contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+--- Optional exception to the license ---
+
+As an exception, if, as a result of your compiling your source code, portions
+of this Software are embedded into a machine-executable object form of such
+source code, you may redistribute such embedded portions in such object form
+without including the above copyright and permission notices.

ports/uwp/third_party/licenses/freetype.txt

@@ -0,0 +1,568 @@
+LICENSE.TXT:
+
+FREETYPE LICENSES
+-----------------
+
+The FreeType  2 font  engine is  copyrighted work  and cannot  be used
+legally without  a software  license.  In order  to make  this project
+usable to  a vast majority of  developers, we distribute it  under two
+mutually exclusive open-source licenses.
+
+This means that *you* must choose  *one* of the two licenses described
+below, then obey all its terms and conditions when using FreeType 2 in
+any of your projects or products.
+
+  - The FreeType License,  found in the file  `docs/FTL.TXT`, which is
+    similar to the  original BSD license *with*  an advertising clause
+    that forces  you to explicitly  cite the FreeType project  in your
+    product's  documentation.  All  details are  in the  license file.
+    This license is suited to products which don't use the GNU General
+    Public License.
+
+    Note that  this license  is compatible to  the GNU  General Public
+    License version 3, but not version 2.
+
+  - The   GNU   General   Public   License   version   2,   found   in
+    `docs/GPLv2.TXT`  (any  later  version  can  be  used  also),  for
+    programs  which  already  use  the  GPL.  Note  that  the  FTL  is
+    incompatible with GPLv2 due to its advertisement clause.
+
+The contributed  BDF and PCF  drivers come  with a license  similar to
+that  of the  X Window  System.   It is  compatible to  the above  two
+licenses (see files `src/bdf/README`  and `src/pcf/README`).  The same
+holds   for   the   source    code   files   `src/base/fthash.c`   and
+`include/freetype/internal/fthash.h`; they were part of the BDF driver
+in earlier FreeType versions.
+
+The gzip  module uses the  zlib license (see  `src/gzip/zlib.h`) which
+too is compatible to the above two licenses.
+
+The   files   `src/autofit/ft-hb-ft.c`,   `src/autofit/ft-hb-decls.h`,
+`src/autofit/ft-hb-types.h`,     and    `src/autofit/hb-script-list.h`
+contain code taken (almost) verbatim  from the HarfBuzz library, which
+uses the 'Old MIT' license compatible to the above two licenses.
+
+The  MD5 checksum  support  (only used  for  debugging in  development
+builds) is in the public domain.
+
+
+--- end of LICENSE.TXT ---
+
+
+FTL.TXT:
+
+                    The FreeType Project LICENSE
+                    ----------------------------
+
+                            2006-Jan-27
+
+                    Copyright 1996-2002, 2006 by
+          David Turner, Robert Wilhelm, and Werner Lemberg
+
+
+
+Introduction
+============
+
+  The FreeType  Project is distributed in  several archive packages;
+  some of them may contain, in addition to the FreeType font engine,
+  various tools and  contributions which rely on, or  relate to, the
+  FreeType Project.
+
+  This  license applies  to all  files found  in such  packages, and
+  which do not  fall under their own explicit  license.  The license
+  affects  thus  the  FreeType   font  engine,  the  test  programs,
+  documentation and makefiles, at the very least.
+
+  This  license   was  inspired  by  the  BSD,   Artistic,  and  IJG
+  (Independent JPEG  Group) licenses, which  all encourage inclusion
+  and  use of  free  software in  commercial  and freeware  products
+  alike.  As a consequence, its main points are that:
+
+    o We don't promise that this software works. However, we will be
+      interested in any kind of bug reports. (`as is' distribution)
+
+    o You can  use this software for whatever you  want, in parts or
+      full form, without having to pay us. (`royalty-free' usage)
+
+    o You may not pretend that  you wrote this software.  If you use
+      it, or  only parts of it,  in a program,  you must acknowledge
+      somewhere  in  your  documentation  that  you  have  used  the
+      FreeType code. (`credits')
+
+  We  specifically  permit  and  encourage  the  inclusion  of  this
+  software, with  or without modifications,  in commercial products.
+  We  disclaim  all warranties  covering  The  FreeType Project  and
+  assume no liability related to The FreeType Project.
+
+
+  Finally,  many  people  asked  us  for  a  preferred  form  for  a
+  credit/disclaimer to use in compliance with this license.  We thus
+  encourage you to use the following text:
+
+   """
+    Portions of this software are copyright © <year> The FreeType
+    Project (https://freetype.org).  All rights reserved.
+   """
+
+  Please replace <year> with the value from the FreeType version you
+  actually use.
+
+
+Legal Terms
+===========
+
+0. Definitions
+--------------
+
+  Throughout this license,  the terms `package', `FreeType Project',
+  and  `FreeType  archive' refer  to  the  set  of files  originally
+  distributed  by the  authors  (David Turner,  Robert Wilhelm,  and
+  Werner Lemberg) as the `FreeType Project', be they named as alpha,
+  beta or final release.
+
+  `You' refers to  the licensee, or person using  the project, where
+  `using' is a generic term including compiling the project's source
+  code as  well as linking it  to form a  `program' or `executable'.
+  This  program is  referred to  as  `a program  using the  FreeType
+  engine'.
+
+  This  license applies  to all  files distributed  in  the original
+  FreeType  Project,   including  all  source   code,  binaries  and
+  documentation,  unless  otherwise  stated   in  the  file  in  its
+  original, unmodified form as  distributed in the original archive.
+  If you are  unsure whether or not a particular  file is covered by
+  this license, you must contact us to verify this.
+
+  The FreeType  Project is copyright (C) 1996-2000  by David Turner,
+  Robert Wilhelm, and Werner Lemberg.  All rights reserved except as
+  specified below.
+
+1. No Warranty
+--------------
+
+  THE FREETYPE PROJECT  IS PROVIDED `AS IS' WITHOUT  WARRANTY OF ANY
+  KIND, EITHER  EXPRESS OR IMPLIED,  INCLUDING, BUT NOT  LIMITED TO,
+  WARRANTIES  OF  MERCHANTABILITY   AND  FITNESS  FOR  A  PARTICULAR
+  PURPOSE.  IN NO EVENT WILL ANY OF THE AUTHORS OR COPYRIGHT HOLDERS
+  BE LIABLE  FOR ANY DAMAGES CAUSED  BY THE USE OR  THE INABILITY TO
+  USE, OF THE FREETYPE PROJECT.
+
+2. Redistribution
+-----------------
+
+  This  license  grants  a  worldwide, royalty-free,  perpetual  and
+  irrevocable right  and license to use,  execute, perform, compile,
+  display,  copy,   create  derivative  works   of,  distribute  and
+  sublicense the  FreeType Project (in  both source and  object code
+  forms)  and  derivative works  thereof  for  any  purpose; and  to
+  authorize others  to exercise  some or all  of the  rights granted
+  herein, subject to the following conditions:
+
+    o Redistribution of  source code  must retain this  license file
+      (`FTL.TXT') unaltered; any  additions, deletions or changes to
+      the original  files must be clearly  indicated in accompanying
+      documentation.   The  copyright   notices  of  the  unaltered,
+      original  files must  be  preserved in  all  copies of  source
+      files.
+
+    o Redistribution in binary form must provide a  disclaimer  that
+      states  that  the software is based in part of the work of the
+      FreeType Team,  in  the  distribution  documentation.  We also
+      encourage you to put an URL to the FreeType web page  in  your
+      documentation, though this isn't mandatory.
+
+  These conditions  apply to any  software derived from or  based on
+  the FreeType Project,  not just the unmodified files.   If you use
+  our work, you  must acknowledge us.  However, no  fee need be paid
+  to us.
+
+3. Advertising
+--------------
+
+  Neither the  FreeType authors and  contributors nor you  shall use
+  the name of the  other for commercial, advertising, or promotional
+  purposes without specific prior written permission.
+
+  We suggest,  but do not require, that  you use one or  more of the
+  following phrases to refer  to this software in your documentation
+  or advertising  materials: `FreeType Project',  `FreeType Engine',
+  `FreeType library', or `FreeType Distribution'.
+
+  As  you have  not signed  this license,  you are  not  required to
+  accept  it.   However,  as  the FreeType  Project  is  copyrighted
+  material, only  this license, or  another one contracted  with the
+  authors, grants you  the right to use, distribute,  and modify it.
+  Therefore,  by  using,  distributing,  or modifying  the  FreeType
+  Project, you indicate that you understand and accept all the terms
+  of this license.
+
+4. Contacts
+-----------
+
+  There are two mailing lists related to FreeType:
+
+    o freetype@nongnu.org
+
+      Discusses general use and applications of FreeType, as well as
+      future and  wanted additions to the  library and distribution.
+      If  you are looking  for support,  start in  this list  if you
+      haven't found anything to help you in the documentation.
+
+    o freetype-devel@nongnu.org
+
+      Discusses bugs,  as well  as engine internals,  design issues,
+      specific licenses, porting, etc.
+
+  Our home page can be found at
+
+    https://freetype.org
+
+
+--- end of FTL.TXT ---
+
+
+GPLv2.TXT:
+
+		    GNU GENERAL PUBLIC LICENSE
+		       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+     51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+		    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+			    NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+	    How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year  name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.
+
+

ports/uwp/third_party/licenses/libpng.txt

@@ -0,0 +1,134 @@
+COPYRIGHT NOTICE, DISCLAIMER, and LICENSE
+=========================================
+
+PNG Reference Library License version 2
+---------------------------------------
+
+ * Copyright (c) 1995-2026 The PNG Reference Library Authors.
+ * Copyright (c) 2018-2026 Cosmin Truta.
+ * Copyright (c) 2000-2002, 2004, 2006-2018 Glenn Randers-Pehrson.
+ * Copyright (c) 1996-1997 Andreas Dilger.
+ * Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
+
+The software is supplied "as is", without warranty of any kind,
+express or implied, including, without limitation, the warranties
+of merchantability, fitness for a particular purpose, title, and
+non-infringement.  In no event shall the Copyright owners, or
+anyone distributing the software, be liable for any damages or
+other liability, whether in contract, tort or otherwise, arising
+from, out of, or in connection with the software, or the use or
+other dealings in the software, even if advised of the possibility
+of such damage.
+
+Permission is hereby granted to use, copy, modify, and distribute
+this software, or portions hereof, for any purpose, without fee,
+subject to the following restrictions:
+
+ 1. The origin of this software must not be misrepresented; you
+    must not claim that you wrote the original software.  If you
+    use this software in a product, an acknowledgment in the product
+    documentation would be appreciated, but is not required.
+
+ 2. Altered source versions must be plainly marked as such, and must
+    not be misrepresented as being the original software.
+
+ 3. This Copyright notice may not be removed or altered from any
+    source or altered source distribution.
+
+
+PNG Reference Library License version 1 (for libpng 0.5 through 1.6.35)
+-----------------------------------------------------------------------
+
+libpng versions 1.0.7, July 1, 2000, through 1.6.35, July 15, 2018 are
+Copyright (c) 2000-2002, 2004, 2006-2018 Glenn Randers-Pehrson, are
+derived from libpng-1.0.6, and are distributed according to the same
+disclaimer and license as libpng-1.0.6 with the following individuals
+added to the list of Contributing Authors:
+
+    Simon-Pierre Cadieux
+    Eric S. Raymond
+    Mans Rullgard
+    Cosmin Truta
+    Gilles Vollant
+    James Yu
+    Mandar Sahastrabuddhe
+    Google Inc.
+    Vadim Barkov
+
+and with the following additions to the disclaimer:
+
+    There is no warranty against interference with your enjoyment of
+    the library or against infringement.  There is no warranty that our
+    efforts or the library will fulfill any of your particular purposes
+    or needs.  This library is provided with all faults, and the entire
+    risk of satisfactory quality, performance, accuracy, and effort is
+    with the user.
+
+Some files in the "contrib" directory and some configure-generated
+files that are distributed with libpng have other copyright owners, and
+are released under other open source licenses.
+
+libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
+Copyright (c) 1998-2000 Glenn Randers-Pehrson, are derived from
+libpng-0.96, and are distributed according to the same disclaimer and
+license as libpng-0.96, with the following individuals added to the
+list of Contributing Authors:
+
+    Tom Lane
+    Glenn Randers-Pehrson
+    Willem van Schaik
+
+libpng versions 0.89, June 1996, through 0.96, May 1997, are
+Copyright (c) 1996-1997 Andreas Dilger, are derived from libpng-0.88,
+and are distributed according to the same disclaimer and license as
+libpng-0.88, with the following individuals added to the list of
+Contributing Authors:
+
+    John Bowler
+    Kevin Bracey
+    Sam Bushell
+    Magnus Holmgren
+    Greg Roelofs
+    Tom Tanner
+
+Some files in the "scripts" directory have other copyright owners,
+but are released under this license.
+
+libpng versions 0.5, May 1995, through 0.88, January 1996, are
+Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
+
+For the purposes of this copyright and license, "Contributing Authors"
+is defined as the following set of individuals:
+
+    Andreas Dilger
+    Dave Martindale
+    Guy Eric Schalnat
+    Paul Schmidt
+    Tim Wegner
+
+The PNG Reference Library is supplied "AS IS".  The Contributing
+Authors and Group 42, Inc. disclaim all warranties, expressed or
+implied, including, without limitation, the warranties of
+merchantability and of fitness for any purpose.  The Contributing
+Authors and Group 42, Inc. assume no liability for direct, indirect,
+incidental, special, exemplary, or consequential damages, which may
+result from the use of the PNG Reference Library, even if advised of
+the possibility of such damage.
+
+Permission is hereby granted to use, copy, modify, and distribute this
+source code, or portions hereof, for any purpose, without fee, subject
+to the following restrictions:
+
+ 1. The origin of this source code must not be misrepresented.
+
+ 2. Altered versions must be plainly marked as such and must not
+    be misrepresented as being the original source.
+
+ 3. This Copyright notice may not be removed or altered from any
+    source or altered source distribution.
+
+The Contributing Authors and Group 42, Inc. specifically permit,
+without fee, and encourage the use of this source code as a component
+to supporting the PNG file format in commercial products.  If you use
+this source code in a product, acknowledgment is not required but would
+be appreciated.