Merge pull request #1408 from bryanthaboi/dev

Merge remote-tracking branch 'origin/main' into dev
# Conflicts: # src/world/gen2/World.lua
2026-08-18 11:44:42 +02:00 · 2026-08-16 10:14:26 -04:00 · 2026-08-16 10:11:53 -04:00 · 2026-08-16 10:04:54 -04:00 · 2026-08-16 08:55:40 -04:00 · 2026-08-16 07:28:08 -04:00
1100 changed files with 306298 additions and 41493 deletions
@@ -22,12 +22,14 @@ body:
    id: game
    attributes:
      label: Which game were you playing
-      description: Pick every version you saw the bug in.
+      description: Pick every version you saw the bug in. Use N/A if it isn't game-specific.
      multiple: true
      options:
        - Red
        - Blue
        - Yellow
+        - Gold
+        - N/A
    validations:
      required: true

@@ -35,12 +37,16 @@ body:
    id: os
    attributes:
      label: Which build are you running
+      description: Official release targets. Pick Multiple platforms if you saw it on more than one.
      options:
        - macOS
        - Windows
        - Linux
        - Android
        - iOS
+        - Nintendo Switch
+        - Xbox
+        - Anbernic RG34XXSP
        - Multiple platforms
    validations:
      required: true
@@ -30,13 +30,14 @@ body:
    id: game
    attributes:
      label: Which game is this about
-      description: Pick every version it applies to.
+      description: Pick every version it applies to. Use N/A if it isn't game-specific.
      multiple: true
      options:
        - Red
        - Blue
        - Yellow
-        - Not version-specific
+        - Gold
+        - N/A
    validations:
      required: true

@@ -27,13 +27,14 @@ body:
    id: game
    attributes:
      label: Which game is this for
-      description: Pick every version the mod should cover.
+      description: Pick every version the mod should cover. Use N/A if it isn't game-specific.
      multiple: true
      options:
        - Red
        - Blue
        - Yellow
-        - Not version-specific
+        - Gold
+        - N/A
    validations:
      required: true

@@ -94,8 +94,8 @@ jobs:
        if: github.repository == 'bryanthaboi/gen1recomp'
        uses: actions/upload-artifact@v7
        with:
-          name: gen1recomp-ios-ipa
-          path: dist/ios/gen1recomp.ipa
+          name: gen1recomp++-ios-ipa
+          path: dist/ios/gen1recomp++.ipa
          if-no-files-found: error
          retention-days: 7
      - name: clean up signing keychain
@@ -181,6 +181,196 @@ jobs:
          if-no-files-found: error
          retention-days: 7

+  xbox-uwp-changes:
+    name: detect Xbox UWP changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(ports/uwp/|scripts/build_xbox_uwp\.sh$|scripts/xbox-uwp/|scripts/pack_love\.sh$|\.github/workflows/(ci|release)\.yml$|src/core/Platform\.lua$|src/import/(CacheFs|LauncherView|RomImporter)\.lua$|src/update/Check\.lua$|tests/engine/(platform_nx|uwp_baseroms|uwp_native_picker)_test\.lua$|tests/rom_importer_double_pick_test\.lua$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  xbox-uwp-selftest:
+    name: Xbox UWP offline selftest
+    needs: xbox-uwp-changes
+    if: needs.xbox-uwp-changes.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Xbox UWP offline selftest
+        run: bash scripts/xbox-uwp/selftest_build_xbox_uwp.sh
+      - name: Build shared payload
+        run: |
+          scripts/pack_love.sh \
+            --output .bazinga/work/ci-game.love \
+            --listing .bazinga/work/ci-love-listing.txt \
+            --version 0.0.0
+      - name: Upload shared payload
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp-payload
+          path: .bazinga/work/ci-game.love
+          if-no-files-found: error
+          retention-days: 1
+
+  xbox-uwp-build:
+    name: Xbox UWP build
+    needs: [xbox-uwp-changes, xbox-uwp-selftest]
+    if: |
+      always()
+      && needs.xbox-uwp-changes.outputs.changed == 'true'
+      && needs.xbox-uwp-selftest.result == 'success'
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-xbox-uwp-payload
+          path: .bazinga/work
+      - name: Build Xbox UWP package
+        shell: bash
+        run: |
+          bash scripts/build_xbox_uwp.sh \
+            --release \
+            --version 0.0.0 \
+            --game-love .bazinga/work/ci-game.love
+      - name: Upload Xbox UWP package
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp
+          path: |
+            dist/xbox-uwp/gen1recomp-0.0.0-xbox-uwp.zip
+            dist/xbox-uwp/gen1recomp-0.0.0-xbox-uwp.zip.sha256
+          if-no-files-found: error
+          retention-days: 7
+
+  linux-arm64-changes:
+    name: detect Linux arm64 changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(scripts/build_linux_arm64\.sh$|scripts/linux-arm64/|scripts/pack_love\.sh$|docs/linux-arm64-build\.md$|\.github/workflows/(ci|release)\.yml$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  linux-arm64-selftest:
+    name: Linux arm64 offline selftest
+    needs: linux-arm64-changes
+    if: needs.linux-arm64-changes.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Deliberately on x86_64: everything this gate checks (pins, the
+      # host-arch guard, the dependency exclude list, the AppRun fusion
+      # contract) is answerable without a container or an aarch64 machine,
+      # so the slow native job below only ever starts on a sane tree.
+      - name: Linux arm64 offline selftest
+        run: bash scripts/linux-arm64/selftest_build_linux_arm64.sh
+
+  linux-arm64-build:
+    name: Linux arm64 AppImage build
+    needs: [linux-arm64-changes, linux-arm64-selftest]
+    if: |
+      always()
+      && needs.linux-arm64-changes.outputs.changed == 'true'
+      && needs.linux-arm64-selftest.result == 'success'
+    # No fork restriction, unlike switch-build: this needs no secrets and no
+    # self-hosted hardware, just GitHub's free arm64 runner for public repos,
+    # so contributors get the same coverage on their own PRs.
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build the aarch64 AppImage
+        run: |
+          set -euo pipefail
+          scripts/build_linux_arm64.sh --version 0.0.0
+      - name: Verify the AppImage is self-contained and bullseye-compatible
+        run: |
+          set -euo pipefail
+          image="dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage"
+
+          # --appimage-extract needs no FUSE, so this works on a runner
+          # without /dev/fuse and still exercises the real payload.
+          "$image" --appimage-extract >/dev/null
+          for required in AppRun bin/love game.love lib/liblove-11.5.so; do
+            [ -e "squashfs-root/$required" ] \
+              || { echo "::error::AppImage is missing $required"; exit 1; }
+          done
+
+          # Every bundled object must resolve once AppRun's LD_LIBRARY_PATH is
+          # applied; an unresolved soname here is a user-visible launch crash.
+          #
+          # This runs on a HEADLESS runner on purpose, and that is the point.
+          # The first version of this build bundled Debian's SDL2, which
+          # hard-links libpulse/libasound/libX11/libwayland, so it only ever
+          # started on a full desktop -- a bare runner is what exposed it.
+          missing="$(LD_LIBRARY_PATH="$PWD/squashfs-root/lib" \
+            ldd squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
+            | grep 'not found' || true)"
+          [ -z "$missing" ] || { echo "::error::unresolved deps:"; echo "$missing"; exit 1; }
+
+          # Nothing may hard-link a driver, session or audio-stack library:
+          # those must be reached through dlopen so the AppImage runs on a box
+          # with only ALSA, only Wayland, or only KMSDRM.
+          linked="$(for f in squashfs-root/bin/love squashfs-root/lib/*.so*; do
+            objdump -p "$f" 2>/dev/null | awk '/NEEDED/{print $2}'
+          done | sort -u | grep -E '^lib(pulse|asound|X11|wayland|GL|EGL|drm|gbm|xcb|cairo|sndio|dbus)' || true)"
+          [ -z "$linked" ] \
+            || { echo "::error::these must be dlopened, not linked:"; echo "$linked"; exit 1; }
+
+          # The whole point of compiling on bullseye. If a future change moves
+          # the builder to a newer base, the glibc floor silently rises and
+          # every user on an older distro gets "GLIBC_2.xx not found" -- catch
+          # it here instead of in a release.
+          floor="$(objdump -T squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
+            | grep -o 'GLIBC_[0-9.]*' | sort -V | tail -1)"
+          echo "highest required glibc symbol version: $floor"
+          [ -n "$floor" ] \
+            || { echo "::error::found no versioned glibc symbols -- objdump read nothing"; exit 1; }
+          highest="$(printf '%s\n' "$floor" "GLIBC_2.31" | sort -V | tail -1)"
+          [ "$highest" = "GLIBC_2.31" ] \
+            || { echo "::error::AppImage requires $floor, above the bullseye 2.31 floor"; exit 1; }
+      - name: Upload the AppImage
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-linux-arm64
+          path: |
+            dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage
+            dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage.sha256
+          if-no-files-found: error
+          retention-days: 7
+
  headless:
    name: headless suites (no ROM)
    runs-on: ubuntu-latest
@@ -193,6 +383,9 @@ jobs:
      - name: install luajit
        run: sudo apt-get update && sudo apt-get install -y luajit

+      - name: install Pillow
+        run: python3 -m pip install --upgrade pillow
+
      - name: interpreter version
        run: luajit -v

@@ -22,7 +22,7 @@ jobs:
          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
          HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name }}
        run: |
-          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp-ios-ipa") | .id')"
+          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp++-ios-ipa") | .id')"
          [ -n "$artifact_id" ] || exit 0
          head_owner="${HEAD_REPOSITORY%%/*}"
          pr_number="$(gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$head_owner:$HEAD_BRANCH" --jq '.[0].number // empty')"
@@ -44,7 +44,7 @@ jobs:
        uses: thollander/actions-comment-pull-request@v3
        with:
          message: |
-            [gen1recomp.ipa](${{ steps.artifact.outputs.artifact_url }})
+            [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 }}`
@@ -1,9 +1,10 @@
 name: Release

 # Builds the macOS, Windows, and Linux desktop apps, an Android APK, an iOS
-# IPA, a Nintendo Switch SD-ready zip (experimental), 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, the Anbernic
+# RG34XXSP (Stock OS 64-bit MOD / PortMaster) and Linux ARM SBC PortMaster
+# handheld ports on the self-hosted Mac runner, and publishes them as a
+# GitHub Release.
 #
 # Versioning:
 #   - First ever release is 0.1.0.
@@ -43,22 +44,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@v7
+      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          fetch-tags: true
-
      - name: Determine version
        id: ver
        env:
@@ -66,7 +62,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.
@@ -96,7 +91,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"
@@ -124,10 +118,195 @@ jobs:
            echo "::error::Release $tag already exists. Pick a different version."
            exit 1
          fi
-
          echo "version=$version" >> "$GITHUB_OUTPUT"
          echo "tag=$tag" >> "$GITHUB_OUTPUT"

+  love-payload:
+    name: build release game.love
+    needs: version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build shared payload
+        run: |
+          scripts/pack_love.sh \
+            --output dist/payload/game.love \
+            --listing dist/payload/love-listing.txt \
+            --version "${{ needs.version.outputs.version }}"
+      - name: Upload shared payload
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-release-love
+          path: dist/payload/game.love
+          if-no-files-found: error
+          retention-days: 1
+
+  linux-arm64:
+    name: build Linux arm64 AppImage
+    needs: [version, love-payload]
+    # GitHub's free arm64 runner for public repos. It has to be arm64: the
+    # AppImage compiles LÖVE natively inside a Debian bullseye arm64
+    # container, and the qemu-emulated alternative takes hours.
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-release-love
+          path: .bazinga/work
+      - name: Build Linux arm64 AppImage
+        run: |
+          set -euo pipefail
+          scripts/build_linux_arm64.sh \
+            --version "${{ needs.version.outputs.version }}" \
+            --game-love .bazinga/work/game.love
+      - name: Upload Linux arm64 release
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-linux-arm64-release
+          path: |
+            dist/linux-arm64/gen1recomp-${{ needs.version.outputs.version }}-linux-arm64.AppImage
+            dist/linux-arm64/gen1recomp-${{ needs.version.outputs.version }}-linux-arm64.AppImage.sha256
+          if-no-files-found: error
+          retention-days: 1
+
+  xbox-uwp:
+    name: build Xbox UWP release
+    needs: [version, love-payload]
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-release-love
+          path: .bazinga/work
+      - name: Prepare signing certificate
+        shell: pwsh
+        env:
+          CERTIFICATE_BASE64: ${{ secrets.XBOX_UWP_SIGNING_CERTIFICATE }}
+          CERTIFICATE_PASSWORD: ${{ secrets.XBOX_UWP_SIGNING_PASSWORD }}
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
+        run: |
+          if ($env:CANONICAL_REPOSITORY -eq 'true' -and
+              [string]::IsNullOrWhiteSpace($env:CERTIFICATE_BASE64)) {
+              throw 'XBOX_UWP_SIGNING_CERTIFICATE is not configured.'
+          }
+          if ([string]::IsNullOrWhiteSpace($env:CERTIFICATE_BASE64)) {
+              "UWP_PUBLISHER=CN=Gen1Recomp" | Out-File $env:GITHUB_ENV -Append
+              exit 0
+          }
+          $pfx = Join-Path $env:RUNNER_TEMP 'gen1recomp-uwp.pfx'
+          [IO.File]::WriteAllBytes($pfx, [Convert]::FromBase64String($env:CERTIFICATE_BASE64))
+          $flags = [Security.Cryptography.X509Certificates.X509KeyStorageFlags]::EphemeralKeySet
+          $cert = [Security.Cryptography.X509Certificates.X509Certificate2]::new(
+              $pfx, $env:CERTIFICATE_PASSWORD, $flags)
+          $cer = Join-Path $env:RUNNER_TEMP 'gen1recomp-uwp.cer'
+          [IO.File]::WriteAllBytes(
+              $cer,
+              $cert.Export([Security.Cryptography.X509Certificates.X509ContentType]::Cert))
+          Import-Certificate -FilePath $cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople | Out-Null
+          "UWP_PFX=$pfx" | Out-File $env:GITHUB_ENV -Append
+          "UWP_CERT_THUMBPRINT=$($cert.Thumbprint)" | Out-File $env:GITHUB_ENV -Append
+          "UWP_PUBLISHER=$($cert.Subject)" | Out-File $env:GITHUB_ENV -Append
+      - name: Build Xbox UWP package
+        shell: bash
+        run: |
+          bash scripts/build_xbox_uwp.sh \
+            --release \
+            --version "${{ needs.version.outputs.version }}" \
+            --publisher "$UWP_PUBLISHER" \
+            --game-love .bazinga/work/game.love
+      - name: Sign and stage Xbox UWP release
+        shell: pwsh
+        env:
+          CERTIFICATE_PASSWORD: ${{ secrets.XBOX_UWP_SIGNING_PASSWORD }}
+        run: |
+          if (-not $env:UWP_PFX) {
+              exit 0
+          }
+          scripts/xbox-uwp/stage_release.ps1 `
+            -Version '${{ needs.version.outputs.version }}' `
+            -Configuration Release `
+            -BuildInfo .bazinga/work/xbox-uwp-build-info.json `
+            -CertificatePath $env:UWP_PFX `
+            -CertificatePassword $env:CERTIFICATE_PASSWORD
+      - name: Upload Xbox UWP release
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-xbox-uwp-release
+          path: |
+            dist/xbox-uwp/gen1recomp-${{ needs.version.outputs.version }}-xbox-uwp.zip
+            dist/xbox-uwp/gen1recomp-${{ needs.version.outputs.version }}-xbox-uwp.zip.sha256
+          if-no-files-found: error
+          retention-days: 1
+      - name: Remove signing certificate
+        if: always()
+        shell: pwsh
+        run: |
+          if ($env:UWP_CERT_THUMBPRINT) {
+              Remove-Item "Cert:\LocalMachine\TrustedPeople\$env:UWP_CERT_THUMBPRINT" -ErrorAction SilentlyContinue
+          }
+          if ($env:UWP_PFX) {
+              Remove-Item $env:UWP_PFX -Force -ErrorAction SilentlyContinue
+          }
+
+  # Windows Native AOT TLS dialer. The Mac release runner fuses the win64 zip
+  # from LÖVE's prebuilt binaries and cannot cross-compile this DLL, so build
+  # it here and inject it in the release job before scripts/build.sh win.
+  native-tls-win:
+    name: build Windows gen1tls.dll
+    needs: version
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Setup .NET 8
+        uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: "8.0.x"
+      - name: Publish gen1tls (win-x64 Native AOT)
+        shell: pwsh
+        run: |
+          $out = "dist/native/win-x64"
+          New-Item -ItemType Directory -Force -Path $out | Out-Null
+          dotnet publish native/tls_dial/Gen1Tls.csproj `
+            -c Release -r win-x64 -o $out
+          if (-not (Test-Path "$out/gen1tls.dll")) {
+            throw "gen1tls.dll missing after publish"
+          }
+          Get-Item "$out/gen1tls.dll" | Format-List Name, Length, LastWriteTime
+      - name: Upload gen1tls.dll
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1tls-win-x64
+          path: dist/native/win-x64/gen1tls.dll
+          if-no-files-found: error
+          retention-days: 1
+
+  release:
+    needs: [version, xbox-uwp, linux-arm64, native-tls-win]
+    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: Download Windows gen1tls dialer
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1tls-win-x64
+          path: dist/native/win-x64
+
      - name: Import signing certificate into a temporary keychain
        if: github.repository == 'bryanthaboi/gen1recomp'
        run: |
@@ -166,18 +345,26 @@ jobs:
          security find-identity -v -p codesigning "$KEYCHAIN_PATH"

      - name: Build macOS + Windows + Linux
+        env:
+          GEN1TLS_DLL: ${{ github.workspace }}/dist/native/win-x64/gen1tls.dll
        run: |
          set -euo pipefail
          # Sign in-build (identity auto-detected from the temp keychain);
          # 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
+          if [ ! -f "$GEN1TLS_DLL" ]; then
+            echo "::error::gen1tls.dll missing at $GEN1TLS_DLL (native-tls-win job)"
+            exit 1
+          fi
+          scripts/build.sh all --version "${{ needs.version.outputs.version }}" --no-notarize
+          unzip -l dist/win/gen1recomp-win64.zip | grep -F gen1tls.dll \
+            || { echo "::error::Windows zip is missing gen1tls.dll"; exit 1; }

      - 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: |
@@ -191,10 +378,10 @@ 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
@@ -206,14 +393,28 @@ jobs:
          # 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 "${{ steps.ver.outputs.version }}"
+            --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: Build Linux ARM SBC PortMaster port
+        env:
+          # The release workflow must package the commit being released. The
+          # script defaults to the latest published release for standalone
+          # builds, while this explicit local override keeps CI source-aligned.
+          GEN1RECOMP_SOURCE_DIR: ${{ github.workspace }}
+          GEN1RECOMP_RELEASE_TAG: v${{ needs.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          # Same aarch64 PortMaster-style pack for Linux ARM SBC PortMaster. The build
+          # keeps its own cache because the two scripts use different staging
+          # layouts and runtime package paths.
+          ./build-linux-arm-sbc.sh --version "${{ needs.version.outputs.version }}"

      - name: Notarize & staple macOS app
        if: github.repository == 'bryanthaboi/gen1recomp'
@@ -250,25 +451,48 @@ jobs:
          ditto -c -k --sequesterRsrc --keepParent "$app" "$zip"
          echo "Notarized + stapled ✓"

+      - name: Download Xbox UWP release
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-xbox-uwp-release
+          path: dist/xbox-uwp
+
+      - name: Download Linux arm64 release
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-linux-arm64-release
+          path: dist/linux-arm64
+
      - name: Stage release assets
        if: github.repository == 'bryanthaboi/gen1recomp'
        id: assets
        run: |
          set -euo pipefail
-          v="${{ steps.ver.outputs.version }}"
+          v="${{ needs.version.outputs.version }}"
          outdir="dist/release"
          rm -rf "$outdir"
          mkdir -p "$outdir"
          cp "dist/mac/gen1recomp-macos.zip" "$outdir/gen1recomp-${v}-macos.zip"
          cp "dist/win/gen1recomp-win64.zip" "$outdir/gen1recomp-${v}-windows.zip"
          cp "dist/linux/gen1recomp-linux.zip" "$outdir/gen1recomp-${v}-linux.zip"
+
+          # arm64 desktop Linux (Raspberry Pi, Armbian, arm64 VMs). Built on
+          # its own runner because LÖVE publishes no aarch64 binary and the
+          # AppImage has to be compiled natively; ships as a runnable
+          # AppImage rather than a zip so `chmod +x && ./it` just works.
+          arm64_appimage="dist/linux-arm64/gen1recomp-${v}-linux-arm64.AppImage"
+          [ -f "$arm64_appimage" ] || { echo "::error::$arm64_appimage not found (expected from the linux-arm64 job)"; exit 1; }
+          cp "$arm64_appimage" "$outdir/gen1recomp-${v}-linux-arm64.AppImage"
+          chmod +x "$outdir/gen1recomp-${v}-linux-arm64.AppImage"
          apk="$(find dist/android/debug -name '*.apk' | head -1)"
          [ -n "$apk" ] || { echo "::error::no Android APK found under dist/android/debug"; exit 1; }
          cp "$apk" "$outdir/gen1recomp-${v}-android.apk"

-          ipa="dist/ios/gen1recomp.ipa"
+          ipa="dist/ios/gen1recomp++.ipa"
          [ -f "$ipa" ] || { echo "::error::$ipa not found (expected from scripts/build_ios.sh --device)"; exit 1; }
-          cp "$ipa" "$outdir/gen1recomp-${v}-ios.ipa"
+          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; }
@@ -276,12 +500,21 @@ jobs:
          # 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"
          [ -f "$rg34" ] || { echo "::error::$rg34 not found (expected from ./build-rg34xxsp.sh)"; exit 1; }
          cp "$rg34" "$outdir/gen1recomp-${v}-rg34xxsp-stockos64-mod.zip"

+          # Linux ARM SBC PortMaster handheld port.
+          sbc="dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip"
+          [ -f "$sbc" ] || { echo "::error::$sbc not found (expected from ./build-linux-arm-sbc.sh)"; exit 1; }
+          cp "$sbc" "$outdir/gen1recomp-${v}-sbc-portmaster.zip"
+
          # Platform-independent update payload, built alongside the desktop
          # apps above (same game.love that gets fused into each of them).
          love_file=".bazinga/work/game.love"
@@ -302,8 +535,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
@@ -391,10 +624,13 @@ jobs:
            "dist/release/gen1recomp-${v}-macos.zip"
            "dist/release/gen1recomp-${v}-windows.zip"
            "dist/release/gen1recomp-${v}-linux.zip"
+            "dist/release/gen1recomp-${v}-linux-arm64.AppImage"
            "dist/release/gen1recomp-${v}-android.apk"
-            "dist/release/gen1recomp-${v}-ios.ipa"
+            "dist/release/gen1recomp++-${v}-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}-sbc-portmaster.zip"
            "dist/release/gen1recomp-${v}.love"
            "dist/release/sha256sums.txt"
          )
@@ -411,15 +647,16 @@ jobs:
        if: github.repository == 'bryanthaboi/gen1recomp'
        run: |
          set -euo pipefail
-          v="${{ steps.ver.outputs.version }}"
-          ipa="dist/release/gen1recomp-${v}-ios.ipa"
+          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"
+          download_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/v${v}/gen1recomp++-${v}-ios.ipa"
+          bundle_id="com.theboisclub.gen1recompplusplus"
          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
@@ -433,15 +670,15 @@ jobs:
            --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)' \
+          if jq -e --arg bundle_id "$bundle_id" --arg version "$v" \
+            'any(.apps[] | select(.bundleIdentifier == $bundle_id).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)' \
+            jq --arg bundle_id "$bundle_id" --arg version "$v" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == $bundle_id).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] + .' \
+            jq --arg bundle_id "$bundle_id" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == $bundle_id).versions) |= [$entry] + .' \
              "$app_repo" > "$app_repo.tmp"
          fi
          mv "$app_repo.tmp" "$app_repo"
@@ -3,8 +3,9 @@
 data/generated/
 assets/generated/

-# LÖVE packages
+# LÖVE packages & archives
 *.love
+*.zip

 # Local saves (LÖVE writes to its save dir, but keep the repo clean anyway)
 save/
@@ -31,12 +32,29 @@ mobile/ios/love-src/
 mobile/ios/cache/
 mobile/ios/build/

-# love-nx vendor binaries (fetch per docs/switch-development.md; also covered by .*)
+# love-nx vendor binaries (fetch per docs/switch-build.md; also covered by .*)
 .bazinga/love-nx/

 # Final packaged build artifacts (mac/win/web/android/ios/switch) — see scripts/build.sh
 /dist/

+# Switch OTA launcher build outputs
+ports/switch/ota-launcher/build/
+ports/switch/ota-launcher/build-host/
+ports/switch/ota-launcher/*.nro
+ports/switch/ota-launcher/*.nacp
+ports/switch/ota-launcher/*.elf
+ports/switch/ota-launcher/*.map
+ports/switch/ota-launcher/romfs/logo.rgba
+ports/switch/ota-launcher/romfs/logo.png
+ports/switch/ota-launcher/romfs/cacert.pem
+ports/switch/ota-launcher/romfs/ota-bootstrap.nro
+ports/switch/ota-bootstrap/build/
+ports/switch/ota-bootstrap/*.nro
+ports/switch/ota-bootstrap/*.nacp
+ports/switch/ota-bootstrap/*.elf
+ports/switch/ota-bootstrap/*.map
+
 # Legacy manual convenience-copy location (superseded by /dist/android/)
 mobile/dist/

@@ -46,3 +64,24 @@ 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/
+
+# Native TLS dialer build output (dotnet publish)
+/native/tls_dial/bin/
+/native/tls_dial/obj/
+/dist/native/
+/dist/win/
+/.bazinga/
+
+# Local options / preferences
+/options.lua*
+
+# User-owned ROMs imported for individual mods. Manifests declare the
+# destinations, but source checkouts and packaged mods never ship the files.
+/mods/*/baseroms/
+/imports/baseroms/
+/imports/baseroms-recovery/
@@ -138,10 +138,186 @@ qualifies only if every record it writes lands in `text`, `strings` or
 permission. Anything else and it is an ordinary content mod that happens to
 ship text.

-### 4. `mod.card`
+### 4. `games` (and the legacy `gen2compat`)
+
+Pokemon Gold is Gen 2, and it runs its own battle engine, overworld, script
+VM and save format. The mod API is shared across both generations (same hook
+names, same event names, same registry names) but Gold cannot serve all of it
+yet, so Gen 2 is opt-in. Say which games the mod is for:
+
+```json
+"games": ["gen1", "gen2"]
+```
+
+Each entry is a version id (`"red"`, `"blue"`, `"yellow"`, `"gold"`), a
+generation (`"gen1"`, `"gen2"`) or `"all"`;
+`src/mods/ModTargets.lua` resolves them off `GameVersion.ORDER` so nothing
+restates the game list. `python3 tools/modkit.py scaffold my_mod --games
+gen1,gen2` writes the key for you. The mod still installs to one directory,
+`mods/<id>/`, shared by every game -- targeting is declared, never filed.
+
+Absent means Gen 1 only, which is what every mod written before the key existed
+was tested as. `"gen2compat": true` is the legacy spelling, still accepted and
+purely additive (it *adds* the Gen 2 games), so no manifest can lose a game it
+already ran on. On a Gold boot a mod claiming no Gen 2 game is not loaded at
+all: the manager lists it as `ENABLED (NOT THIS GAME)` and says why, because a
+mod that half-applies reads as a broken mod. Claim Gen 2 once you have actually
+run your mod on Gold.
+
+Every token is enforced, per game: the loader gates on the same
+`ModTargets.supports` answer both mod surfaces draw, so `"games": ["blue"]`
+really does not load on Red and the skip line is the launcher's line, `For
+Blue, not Red`, and `"games": ["gold"]` alone does not load on Red either. A
+manifest with neither key still covers every Gen 1 game, so nothing written
+before the key existed changes behavior; list both generations or say `"all"`
+when you mean everywhere.
+
+`docs/mod-api-gen2-compat.md` is the compatibility matrix: what works on Gold
+today (40 of the 46 registries, 40 event and 43 hook names shared with Gen 1,
+and 24 Gen 2-only ones), which registries have no Gen 2 home and drop their
+writes with a report, and which hooks and events are still to come.
+`docs/preparing-your-mod-for-gen2.md` is the step-by-step migration guide for a
+Gen 1 mod, and it is the one to start from.
+
+Two consequences worth knowing before you claim Gen 2.
+
+**Dependencies are contagious.** A mod whose hard dependency does not run here
+is left out too, with the dependency's own wording (`depends on X, which does
+not run here (For Blue, not Red)`). It is reported as a skip, not as a failure,
+and neither mod lands on the boot error list, but the mod does not run, so
+every hard dependency has to cover the same games.
+
+**The player can override you.** The claim is yours, and a mod written before
+the key existed can never carry one, so the manager's detail pane offers
+`TRY HERE ANYWAY` for any mod that does not claim the game being played. It
+persists per game in `options.modsGen2[id][version]` and takes effect on the
+next boot; forcing a mod onto Red does not force it onto Gold. A forced mod
+loads normally and keeps a note saying its author never verified it here.
+
+**Prefer the API on Gold, but the Gen 1 names still work.** Gen 2 is a
+parallel module tree behind `src/core/Game2.lua`. In new code take the live
+game from `mod.game` (or the `game.ready` payload, or any `ui.*` hook's first
+argument) and the world from `mod.world`; both resolve per generation, and
+neither needs `engine_internals`.
+
+For the mods written before Gold existed, a require made from a mod's own file
+is answered on a Gold boot by an adapter presenting the Gen 1 API over Gen 2
+internals. Fifteen names are served -- `src.core.Game`,
+`src.world.OverworldController`, `src.world.Map`, `src.world.NPC`,
+`src.world.Collision`, `src.world.WorldAPI`, `src.world.PikachuFollower`,
+`src.world.FieldDefaults`, `src.pokemon.Boxes`, `src.script.ScriptRunner`,
+`src.ui.PartyMenu`, `src.ui.StartMenu`, `src.ui.OptionsMenu`, `src.ui.BoxMenu`
+and `src.battle.BattleState`. `src/mods/Gen2Compat.lua` is the full table and
+publishes what it covers through `Gen2Compat.coverage(name)`, whose members are
+`backed`, `warned` or `absent`. A name with no adapter (`src.script.Commands`,
+`src.ui.OptionRows`) is reported against the mod that required it, and a member
+an adapter cannot back is absent or logs once rather than answering wrongly.
+
+Things no adapter can fix, all mod-side: a hardcoded version allow-list
+(`GameVersion.get() == "red" or ...`) excludes you from Gold by construction;
+Gold's builtin screen ids carry a `Gen2` prefix, so a string match on
+`"BoxMenu"` matches nothing there; a write to a field on a live Gen 2 menu
+instance is inert; and `map.warpAt` is a table on Gen 1 and a method on Gold,
+so indexing it raises. Each has a route that works on both generations, in
+`docs/preparing-your-mod-for-gen2.md`.
+
+Check it statically, then load it headless:
+
+```sh
+python3 tools/modkit.py gen2check mods/my_mod
+```
+
+```lua
+local run = T.sdk.loadMod("mods/my_mod", { generation = 2 })
+T.eq(run.mod and run.mod.state, "loaded",
+  "runs on gen 2: " .. tostring(run.mod and run.mod.skipReason))
+T.eq(#run.errors, 0, "and loads with no boot errors")
+```
+
+Assert the state, not only the error count: a gate skip is deliberately not an
+error, so `#run.errors == 0` passes for a mod that never ran a line.
+
+`gen2check` answers `will load`, `will load but degrade` or `will not work`,
+with a `MK4xx` finding per site and an `unresolved:` note, with a file and a
+line, for every reach a static scan could not follow. Neither substitutes for a
+real Gold boot.
+
+### 5. What a mod's code can reach
+
+Your code runs in a sandbox (`src/mods/Sandbox.lua`), not against the
+engine's globals. Every chunk you author gets it: `main.lua`, your
+`options_schema`, and anything you `load()` yourself.
+
+The globals the sandbox took away are still *reachable*, as compat
+stand-ins (`src/mods/LegacyCompat.lua`) that answer with the new API
+underneath. A mod written before the sandbox keeps working; it logs one
+warning per call it should migrate, and the mod manager lists them. What
+each stand-in actually does:
+
+| Pre-sandbox call | What it does now | Migrate to |
+| --- | --- | --- |
+| `io.open`, `io.lines`, `love.filesystem.read`/`lines`/`newFile` | reads your own shipped files, then your overlay, then `mod.storage` | `mod:read`, `mod.storage` |
+| `love.filesystem.write`/`append`, `io.open(…, "w")`, `os.remove`, `os.rename` | writes to a private per-mod overlay under `mod_compat/<your id>/` | `mod.storage` |
+| `love.filesystem.getDirectoryItems`/`getInfo` | your own directory plus your overlay | `mod:list`, `mod:info` |
+| `love.filesystem.getSaveDirectory` and friends | a virtual root; anything joined to it lands in your overlay | `mod.storage` |
+| `os.getenv` | `nil`, except home-like names, which answer with that same virtual root | nothing |
+| `love.filesystem.load`, `dofile`, `loadfile` | compiles the chunk into your sandbox | `require`, `mod:read` plus `load` |
+| `love.system` | `getOS`/`getPowerInfo`/`getProcessorCount` read through; clipboard and `openURL` do nothing | `mod.device:powerInfo()`, `mod.steps` |
+| `love.event` | passes through, except `quit`, which does nothing | `mod.events`, `mod.hooks` |
+| `love.mousemoved = fn` and the other callbacks | installs on the real `love` table, the way it always did | `mod.hooks`, `mod.events` |
+| `package` | an inert stub, so `package.path = …` does not crash | `require` |
+
+What has no stand-in, because there is nothing honest to reroute it to:
+
+| Still refused | Why |
+| --- | --- |
+| `love.thread` | a LÖVE thread is a fresh Lua state with the full standard library, which no environment-based sandbox in this state can reach. Use `mod.fetch` for background HTTP (`network`) or `mod.job` for background compute (`background`) — both run your code inside the sandbox instead of outside it |
+| `require("ffi")` | arbitrary C |
+| `debug`, `getfenv`, `setfenv` | each one undoes the sandbox from inside |
+| `io.popen`, `os.execute` | spawning a process |
+| `love.run`, `love.errorhandler` | the engine's own loop and its crash path |
+| replacing a `love` module table (`love.filesystem = {}`) | the engine reads those tables too |
+
+The rest of `love` passes through unchanged, so graphics, audio, timers and
+input work as they always have.
+
+Three consequences worth knowing before you write against it:
+
+- **Your globals are yours.** `_G` inside a mod is that mod's own table. Two
+  mods no longer share a namespace, and neither can reach the engine's. To
+  publish something to another mod, put it on `mod.exports` and let them
+  `mod.find("your_id").exports` — the channel that was always the intended
+  one. The same goes for the standard library: `string`, `table` and `math`
+  are per-mod copies, so patching one is a local decision.
+- **Paths cannot climb.** `mod:read`, `mod:list`, `mod:info`, `mod.assets:path`
+  and `mod.assets:image` join to your own directory, and `..`, absolute paths
+  and drive letters are refused. So are `entry` and `options_schema` in your
+  manifest. `mod:list("assets")` is the sandboxed `getDirectoryItems` for a
+  folder you shipped; `mod:info` tells file from directory so a walk can
+  recurse.
+- **Ship source, not bytecode.** A precompiled entry file is refused.
+
+`permissions` in the manifest is still a disclosure the manager shows the
+player. `network` gates `require("socket")` and friends plus `mod.fetch`
+(non-blocking HTTP), and `background` gates `mod.job` (compute on a worker
+thread). Those two are the sanctioned ways to work off the main thread now
+that `love.thread` is refused. There is no
+permission that grants raw filesystem access, because no mod needs one:
+everything a mod legitimately writes is already scoped by
+`mod.storage` or the asset-transform derived root.
+
+If your mod used one of the rerouted globals, the fix is almost always
+`mod.storage`. The overlay is a compatibility floor, not a second storage
+system: it is not scoped per playthrough, it does not migrate, and it is
+the first thing that will be dropped once the mods on the index have
+moved off it. Open an issue if you have a case `mod.storage` does not
+cover.
+
+### 6. `mod.card`

 The manifest is the *engine's* contract: identity, load order, dependencies,
-permissions, profile. The card is the *human-facing* one: who made this,
+permissions, profile (see [Manifest specification](docs/modding.md#manifest-specification-manifestjson)).
+The card is the *human-facing* one: who made this,
 what it changes, what it does not do yet. It is never read by the loader's
 merge — only by tooling and the manager's detail pane — so an absent or
 malformed card can never break a load.
@@ -159,7 +335,7 @@ Two fields deserve their own note:
  distributed mod never carries ROM-derived bytes, not even in its preview
  images.

-### 5. Tags
+### 7. Tags

 Lowercase kebab strings, open vocabulary. The showcase generator
 lowercases and de-dupes. A recommended starting set: `beginner`,
@@ -217,12 +393,15 @@ registry or a new schema field lands with its catalog entry in the same PR
 and the generator runs clean:

 ```sh
-luajit tools/gen_registry_docs.lua                 # in-repo default
-luajit tools/gen_registry_docs.lua ../project.wiki # the wiki checkout
+luajit tools/gen_registry_docs.lua                 # docs/modding/reference/registries.md
+luajit tools/gen_registry_docs.lua ../project.wiki # Reference-Registries.md in a wiki checkout
 ```

-The prose reference lives in the GitHub wiki; the generated pages are
-written into a checkout of it, so they cannot drift from the engine.
+With no argument it writes inside the repo, which is the copy `python3
+tools/modkit.py docs` regenerates and `--out` copies from. Pass a directory
+(or set `POKEPORT_DOCS_DIR`) to write the wiki's flat page name into a wiki
+checkout instead. The prose reference lives in the GitHub wiki; both copies
+come off `src/mods/Schemas.lua`, so neither can drift from the engine.

 ### 5. Deprecation etiquette

@@ -53,13 +53,14 @@ supplied by the player.


 This project does not include a ROM, emulate the Game Boy, transpile assembly,
-or download a disassembly. A canonical US Poke Red, Blue, or Yellow ROM is the
-only game content input.
+or download a disassembly. A canonical US Poke Red, Blue, Yellow, or Gold ROM
+is the only game content input.

 The ROM is verified, used during import, and then released from memory. It is
 not copied into the cache. Later launches load the private generated cache and
-do not ask for the ROM again. Red, Blue, and Yellow can all be imported and
-played side by side.
+do not ask for the ROM again. Red, Blue, Yellow, and Gold can all be imported
+side by side. Gold is Gen 2 Phase 1 (import + launcher; see
+`docs/gold-phase1.md`): the Gen 2 engine is still under construction.

 ## Quick Start

@@ -67,12 +68,13 @@ Open the desktop app. On first boot, choose your legally obtained `.gb` /
 `.gbc` file or drop it onto the window. Import takes a few seconds and the
 game starts automatically.

-Only the canonical 1 MiB US Red, Blue, and Yellow ROMs are accepted. The
-importer verifies SHA-1 before creating any game data:
+Only the canonical US Red, Blue, Yellow (1 MiB), and Gold (2 MiB) ROMs are
+accepted. The importer verifies SHA-1 before creating any game data:

 - Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
 - Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
 - Yellow: `cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1`
+- Gold: `d8b8a3600a465308c9953dfa04f0081c05bdcb94`

 The packaged app contains neither a ROM nor pre-extracted game data. Music,
 sound effects, and cries are synthesized while the game runs from compact
@@ -205,9 +207,42 @@ even on a different computer, as long as the same folder comes along.
 already written to either location is touched automatically, so copy files
 over yourself if you want to carry existing progress across the switch.

+## Launch Options
+
+By default the app opens the launcher so you can pick a game. Launch options
+skip it and start one game directly, which is what you want for a one-click
+entry: a desktop shortcut per game, a Steam entry, or a handheld frontend.
+
+| Option | Effect |
+| --- | --- |
+| `--game=red` | boot Red, skipping the launcher (`blue` and `yellow` too, or just `r` / `b` / `y`) |
+| `--slot=2` | load that save slot; takes a slot number or a slot id |
+| `--launcher` | open the launcher anyway, so you can edit a shortcut you already made |
+
+
+## Linux on arm64 (Raspberry Pi)
+
+Alongside the x86_64 `gen1recomp-*-linux.zip`, every release ships
+`gen1recomp-*-linux-arm64.AppImage` for 64-bit ARM desktop Linux — Raspberry
+Pi 4/5, Armbian and other SBC distros, and arm64 VMs on Apple Silicon:
+
+```sh
+chmod +x gen1recomp-*-linux-arm64.AppImage
+./gen1recomp-*-linux-arm64.AppImage
+```
+
+LÖVE publishes no aarch64 binary of any kind, so this artifact compiles the
+engine — and SDL2, OpenAL and the codecs — from source inside a Debian
+bullseye arm64 container. It needs only glibc 2.29+, libstdc++, freetype and
+zlib on the host; OpenGL, X11, Wayland, KMSDRM, ALSA and PulseAudio are all
+dlopened, so the same image runs on a full desktop, a Wayland-only session or
+a KMSDRM handheld with no X server. Build instructions and the reasoning are
+in [docs/linux-arm64-build.md](docs/linux-arm64-build.md).
+
+
 ## iOS

-Every release ships `gen1recomp-*-ios.ipa`. Sideload it with AltStore
+Every release ships `gen1recomp++-*-ios.ipa`. Sideload it with AltStore
 (Windows or Mac) — see [docs/ios-sideload.md](docs/ios-sideload.md). To
 build and install from source on a Mac instead, see
 [docs/ios-install.md](docs/ios-install.md).
@@ -222,6 +257,40 @@ build and install from source on a Mac instead, see
    <a href="https://github.com/bryanthaboi/gen1recomp/releases/latest"><img src="./.github/resources/github-badge.png" alt="Download from GitHub" height="60"></a>
 </div>

+## Xbox Dev Mode
+
+Every release ships `gen1recomp-*-xbox-uwp.zip` for Xbox One and Xbox Series
+consoles in Developer Mode. It cannot be installed in retail mode.
+
+Extract the archive, then use Xbox Device Portal to install the `.msix` and
+the x64 package under `Dependencies`.
+
+### External setup
+
+1. Put your legally obtained Red, Blue, or Yellow ROMs on an external drive.
+   Mod ZIPs can go on the same drive.
+2. Connect the drive to the Xbox and open Gen1Recomp.
+3. Select **Import ROM** or **Import Mod**, then choose the file with the Xbox
+   file picker.
+4. Repeat the ROM import for each version you want to use.
+
+### Internal setup
+
+1. Create a folder named `baseroms` on your PC and place your legally obtained
+   Red, Blue, or Yellow ROMs inside it.
+2. ZIP the folder, keeping `baseroms` at the top level of the archive.
+3. Launch Gen1Recomp once, then close it.
+4. Open Xbox Device Portal and upload the ZIP to
+   `Gen1Recomp/LocalState/pokemon-love2d/`.
+5. Choose **Yes** when Device Portal asks whether to extract the archive.
+6. Open Gen1Recomp. The launcher checks baseroms once at startup. When it finds a compatible ROM, that game’s tab shows ROM FOUND and an Import detected ROM button.
+
+ROMs, generated game data, saves, and mods remain in LocalState and are not
+included in the app.
+
+Source builds and package details are covered in
+[the Xbox UWP build notes](ports/uwp/BUILD.md).
+
 ## Handhelds

 A PortMaster-style port for the **Anbernic RG34XXSP** on Stock OS 64-bit MOD
@@ -231,24 +300,18 @@ Install steps, controls, and troubleshooting live in

 ## 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).
+Releases ship an SD-ready `gen1recomp-*-switch.zip`. Runtime target is pinned
+[love-nx](https://github.com/retronx-team/love-nx) `11.5-nx1`. Requires a
+console that can run Switch homebrew.

- Players: [docs/switch-install.md](docs/switch-install.md) — download the
+- 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.
+- Builders: [docs/switch-build.md](docs/switch-build.md). `--fetch` /
+  `--loose` / `--fused`, toolchain, Docker fallback, and CI vs release
+  (path-gated ubuntu selftest, fused PR artifact on the main repo, release
+  hard-fail).
+- File transfer (MTP / SD / FTP): [docs/switch-transfer.md](docs/switch-transfer.md).

 ## Modding

@@ -297,7 +360,4 @@ 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>
@@ -0,0 +1,366 @@
+#!/usr/bin/env bash
+# Build a PortMaster aarch64 port of gen1recomp for Linux ARM SBC handhelds.
+# The package uses PortMaster control hooks and a self-contained LÖVE runtime,
+# while keeping paths relative to the launcher for broad CFW compatibility.
+#
+# The launcher uses SHDIR-relative paths and bundles the LÖVE 11.5 aarch64
+# runtime so the device does not need a separate runtime download on first launch.
+#
+# Usage:
+#   ./build-linux-arm-sbc.sh [--version X.Y.Z]
+#   GEN1RECOMP_SOURCE_DIR="$PWD" ./build-linux-arm-sbc.sh --version X.Y.Z
+#   ./build-linux-arm-sbc.sh --source /path/to/gen1recomp --version X.Y.Z
+#
+# Output:
+#   dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip
+#
+# Install on device:
+#   1. Install PortMaster for the handheld firmware.
+#   2. Unzip into the device's PortMaster ports folder so you have:
+#        Roms/Ports (PORTS)/gen1recomp-sbc.sh
+#        Roms/Ports (PORTS)/gen1recomp-sbc/...
+#   3. Copy a legal US Red or Blue .gb into Roms/Ports (PORTS)/gen1recomp-sbc/lovegame/
+#   4. Launch "gen1recomp-sbc" from the Ports list; press Choose ROM (scans that
+#      folder when zenity is missing).
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+HERE="$ROOT/.bazinga"
+CACHE="$HERE/cache/linux-arm-sbc"
+WORK="$HERE/work/linux-arm-sbc"
+DIST="$ROOT/dist/linux-arm-sbc"
+
+APP_NAME="gen1recomp-sbc"
+# Artifact suffix identifies this as the generic PortMaster SBC package.
+# Release uploads stage it as gen1recomp-<ver>-sbc-portmaster.zip.
+ARTIFACT_SUFFIX="portmaster"
+PORT_DIR_NAME="gen1recomp-sbc"
+LAUNCHER_NAME="gen1recomp-sbc.sh"
+LOVE_VERSION="11.5"
+# By default the pack is reproducible from the latest published GitHub release,
+# not whatever happens to be in the caller's checkout.  Development builds can
+# point this at a local checkout with GEN1RECOMP_SOURCE_DIR=/path/to/repo.
+SOURCE_DIR_OVERRIDE="${GEN1RECOMP_SOURCE_DIR:-}"
+SOURCE_TAG_OVERRIDE="${GEN1RECOMP_RELEASE_TAG:-}"
+VERSION="${GEN1RECOMP_VERSION:-}"
+
+# Official PortMaster LÖVE 11.5 aarch64 runtime (small love stub + liblove).
+PM_RUNTIME_BASE="https://raw.githubusercontent.com/PortsMaster/PortMaster-GUI/main/PortMaster/runtimes/love_${LOVE_VERSION}"
+RELEASES_LATEST_URL="https://github.com/bryanthaboi/gen1recomp/releases/latest"
+RELEASE_TARBALL_BASE="https://github.com/bryanthaboi/gen1recomp/archive/refs/tags"
+
+say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33mwarn:\033[0m %s\n' "$*" >&2; }
+fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --version) [ $# -ge 2 ] || fail "--version needs X.Y.Z"; VERSION="$2"; shift ;;
+    --source) [ $# -ge 2 ] || fail "--source needs a directory"; SOURCE_DIR_OVERRIDE="$2"; shift ;;
+    --release-tag) [ $# -ge 2 ] || fail "--release-tag needs a tag"; SOURCE_TAG_OVERRIDE="$2"; shift ;;
+    -h|--help)
+      sed -n '2,24p' "$0"
+      exit 0
+      ;;
+    *) fail "unknown argument: $1" ;;
+  esac
+  shift
+done
+
+command -v curl >/dev/null || fail "curl is required"
+command -v zip  >/dev/null || fail "zip is required"
+command -v unzip >/dev/null || fail "unzip is required"
+command -v tar  >/dev/null || fail "tar is required"
+
+mkdir -p "$CACHE" "$WORK" "$DIST"
+
+download() {
+  local url="$1" dest="$2"
+  if [ -f "$dest" ] && [ -s "$dest" ]; then
+    return 0
+  fi
+  say "downloading $(basename "$dest")"
+  curl -fL --progress-bar "$url" -o "$dest.tmp" \
+    || fail "download failed: $url"
+  mv "$dest.tmp" "$dest"
+}
+
+# --------------------------------------------------------------- source + game tree
+# Release builds use the latest published source archive. A local checkout is
+# an explicit override for development and for CI's just-built release source.
+if [ -n "$SOURCE_DIR_OVERRIDE" ]; then
+  SOURCE_DIR_OVERRIDE="$(cd "$SOURCE_DIR_OVERRIDE" 2>/dev/null && pwd)" \
+    || fail "source directory does not exist: $SOURCE_DIR_OVERRIDE"
+  SOURCE_DIR="$SOURCE_DIR_OVERRIDE"
+  SOURCE_TAG="${SOURCE_TAG_OVERRIDE:-local}"
+  if [ "$SOURCE_TAG" != "local" ]; then
+    printf '%s' "$SOURCE_TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+      || fail "release tag must look like vX.Y.Z: $SOURCE_TAG"
+  fi
+  if [ -z "$VERSION" ]; then
+    VERSION="$(git -C "$SOURCE_DIR" rev-parse --short HEAD 2>/dev/null || echo dev)"
+  fi
+else
+  if [ -z "$SOURCE_TAG_OVERRIDE" ]; then
+    latest_location="$(curl -fsSI "$RELEASES_LATEST_URL" \
+      | awk 'tolower($1) == "location:" { print $2 }' | tail -1 | tr -d '\r')" \
+      || fail "could not resolve latest published release"
+    SOURCE_TAG_OVERRIDE="${latest_location##*/}"
+  fi
+  printf '%s' "$SOURCE_TAG_OVERRIDE" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+    || fail "release tag must look like vX.Y.Z: $SOURCE_TAG_OVERRIDE"
+  SOURCE_TAG="$SOURCE_TAG_OVERRIDE"
+  SOURCE_ARCHIVE="$CACHE/gen1recomp-${SOURCE_TAG}.tar.gz"
+  download "$RELEASE_TARBALL_BASE/$SOURCE_TAG.tar.gz" "$SOURCE_ARCHIVE"
+  SOURCE_EXTRACT="$WORK/source-$SOURCE_TAG"
+  rm -rf "$SOURCE_EXTRACT"
+  mkdir -p "$SOURCE_EXTRACT"
+  tar -xzf "$SOURCE_ARCHIVE" -C "$SOURCE_EXTRACT"
+  SOURCE_DIR="$(find "$SOURCE_EXTRACT" -mindepth 1 -maxdepth 1 -type d -print -quit)"
+  [ -n "$SOURCE_DIR" ] || fail "release archive had no source directory"
+  if [ -z "$VERSION" ]; then VERSION="${SOURCE_TAG#v}"; fi
+fi
+
+say "staging lovegame/ from $SOURCE_TAG"
+GAME_SRC="$WORK/lovegame"
+rm -rf "$GAME_SRC"
+mkdir -p "$GAME_SRC"
+
+# Same payload as scripts/build.sh's game.love — never ship ROM-derived cache.
+# tools/save-editor is part of that payload: the launcher's Edit button on a
+# save row opens it in-process (main.lua).
+(cd "$SOURCE_DIR" && zip -q -9 -r "$WORK/game-payload.zip" \
+  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" \
+    | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/'; then
+  fail "payload unexpectedly contains generated ROM data"
+fi
+unzip -q "$WORK/game-payload.zip" -d "$GAME_SRC"
+rm -f "$WORK/game-payload.zip"
+
+# Stamp release version into the staged tree only (never the working tree).
+if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  say "stamping engine version $VERSION"
+  sed -E "s/(engine[[:space:]]*=[[:space:]]*\")[^\"]*(\")/\1$VERSION\2/" \
+    "$SOURCE_DIR/src/core/Version.lua" > "$GAME_SRC/src/core/Version.lua"
+  version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+  grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+    "$GAME_SRC/src/core/Version.lua" \
+    || fail "version stamp failed"
+else
+  say "version '$VERSION' is not X.Y.Z — shipping default engine (no stamp)"
+fi
+
+# Portable marker: saves + ROM cache live next to the game on the SD card.
+: > "$GAME_SRC/portable.txt"
+
+# --------------------------------------------------------------- love runtime
+say "fetching LÖVE $LOVE_VERSION aarch64 runtime"
+LOVE_BIN="$CACHE/love.aarch64"
+LOVE_LIB="$CACHE/liblove-11.5.so"
+LUAJIT_LIB="$CACHE/libluajit-5.1.so.2"
+MODPLUG_LIB="$CACHE/libmodplug.so.1"
+OGG_LIB="$CACHE/libogg.so.0"
+
+download "$PM_RUNTIME_BASE/love.aarch64" "$LOVE_BIN"
+download "$PM_RUNTIME_BASE/libs.aarch64/liblove-11.5.so" "$LOVE_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libluajit-5.1.so.2" "$LUAJIT_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libmodplug.so.1" "$MODPLUG_LIB"
+download "$PM_RUNTIME_BASE/libs.aarch64/libogg.so.0" "$OGG_LIB"
+
+# Sanity: love stub must be an aarch64 ELF.
+file "$LOVE_BIN" | grep -qi 'aarch64\|ARM aarch64' \
+  || fail "love.aarch64 does not look like an aarch64 ELF (got: $(file "$LOVE_BIN"))"
+
+# --------------------------------------------------------------- port tree
+say "assembling port package"
+PORT_ROOT="$WORK/port"
+rm -rf "$PORT_ROOT"
+mkdir -p "$PORT_ROOT/$PORT_DIR_NAME/bin" \
+         "$PORT_ROOT/$PORT_DIR_NAME/libs.aarch64" \
+         "$PORT_ROOT/$PORT_DIR_NAME/licenses" \
+         "$PORT_ROOT/$PORT_DIR_NAME/conf"
+
+cp -R "$GAME_SRC" "$PORT_ROOT/$PORT_DIR_NAME/lovegame"
+cp "$LOVE_BIN" "$PORT_ROOT/$PORT_DIR_NAME/bin/love.aarch64"
+chmod +x "$PORT_ROOT/$PORT_DIR_NAME/bin/love.aarch64"
+cp "$LOVE_LIB" "$LUAJIT_LIB" "$MODPLUG_LIB" "$OGG_LIB" \
+  "$PORT_ROOT/$PORT_DIR_NAME/libs.aarch64/"
+
+# Drop a short license pointer for the bundled LÖVE bits.
+cat > "$PORT_ROOT/$PORT_DIR_NAME/licenses/LICENSE.love2d.txt" <<'EOF'
+This port bundles the LÖVE 11.5 aarch64 runtime from PortMaster
+(https://github.com/PortsMaster/PortMaster-GUI). LÖVE is zlib-licensed;
+see https://love2d.org/ for full terms.
+EOF
+
+# --------------------------------------------------------------- launcher
+# Resolve the game directory from the launcher so this works with both
+# PortMaster-managed ports directories.
+cat > "$PORT_ROOT/$LAUNCHER_NAME" <<'EOF'
+#!/bin/bash
+# gen1recomp-sbc — Linux ARM SBC / PortMaster launcher
+# Uses SHDIR-relative paths so firmware-specific mount points do not matter.
+
+export HOME="${HOME:-/root}"
+XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+SHDIR="$(cd "$(dirname "$0")" && pwd)"
+
+if [ -d "/mnt/SDCARD/Apps/PortMaster/PortMaster/" ]; then
+  controlfolder="/mnt/SDCARD/Apps/PortMaster/PortMaster"
+elif [ -d "/mnt/SDCARD/Roms/ports/PortMaster" ]; then
+  controlfolder="/mnt/SDCARD/Roms/ports/PortMaster"
+elif [ -d "/mnt/SDCARD/Data/PortMaster/" ]; then
+  controlfolder="/mnt/SDCARD/Data/PortMaster"
+elif [ -d "$SHDIR/PortMaster" ]; then
+  controlfolder="$SHDIR/PortMaster"
+elif [ -d "/opt/system/Tools/PortMaster/" ]; then
+  controlfolder="/opt/system/Tools/PortMaster"
+elif [ -d "/opt/tools/PortMaster/" ]; then
+  controlfolder="/opt/tools/PortMaster"
+elif [ -d "$XDG_DATA_HOME/PortMaster/" ]; then
+  controlfolder="$XDG_DATA_HOME/PortMaster"
+elif [ -d "/roms/ports/PortMaster" ]; then
+  controlfolder="/roms/ports/PortMaster"
+else
+  controlfolder="/mnt/SDCARD/Roms/PORTS/PortMaster"
+fi
+
+if [ ! -f "$controlfolder/control.txt" ]; then
+  echo "PortMaster control.txt not found under $controlfolder" >&2
+  exit 1
+fi
+# shellcheck disable=SC1090
+source "$controlfolder/control.txt"
+get_controls
+if [ -n "${CFW_NAME:-}" ] && [ -f "${controlfolder}/mod_${CFW_NAME}.txt" ]; then
+  # shellcheck disable=SC1090
+  source "${controlfolder}/mod_${CFW_NAME}.txt"
+fi
+
+GAMEDIR="$SHDIR/gen1recomp-sbc"
+CONFDIR="$GAMEDIR/conf"
+mkdir -p "$CONFDIR"
+
+cd "$GAMEDIR" || exit 1
+> "$GAMEDIR/log.txt" && exec > >(tee "$GAMEDIR/log.txt") 2>&1
+
+export XDG_DATA_HOME="$CONFDIR"
+export XDG_CONFIG_HOME="$CONFDIR"
+export LD_LIBRARY_PATH="$GAMEDIR/libs.aarch64:${LD_LIBRARY_PATH:-}"
+export SDL_GAMECONTROLLERCONFIG="${sdl_controllerconfig:-}"
+# GLES is the common path on ARM SBC handhelds; firmware may override it.
+export LOVE_GRAPHICS_USE_OPENGLES="${LOVE_GRAPHICS_USE_OPENGLES:-1}"
+
+$ESUDO chmod a+x ./bin/love.aarch64 2>/dev/null || chmod a+x ./bin/love.aarch64
+$ESUDO chmod 666 /dev/uinput 2>/dev/null || true
+
+if [ -n "${GPTOKEYB:-}" ]; then
+  $GPTOKEYB "love.aarch64" &
+fi
+if type pm_platform_helper >/dev/null 2>&1; then
+  pm_platform_helper "$GAMEDIR/bin/love.aarch64"
+fi
+
+./bin/love.aarch64 "$GAMEDIR/lovegame"
+
+if type pm_finish >/dev/null 2>&1; then
+  pm_finish
+else
+  if [ -n "${ESUDO:-}" ]; then
+    $ESUDO kill -9 $(pidof gptokeyb) 2>/dev/null || true
+  else
+    kill -9 $(pidof gptokeyb) 2>/dev/null || true
+  fi
+fi
+EOF
+chmod +x "$PORT_ROOT/$LAUNCHER_NAME"
+
+# --------------------------------------------------------------- metadata
+cat > "$PORT_ROOT/port.json" <<EOF
+{
+  "version": 2,
+  "name": "gen1recomp-sbc.zip",
+  "items": [
+    "$LAUNCHER_NAME",
+    "$PORT_DIR_NAME"
+  ],
+  "items_opt": null,
+  "attr": {
+    "title": "gen1recomp-sbc",
+    "desc": "Native LÖVE2D recreation of Pokemon Red and Blue. Supply your own legal US Red or Blue ROM.",
+    "source": "https://github.com/bryanthaboi/gen1recomp/releases/tag/$SOURCE_TAG",
+    "inst": "Requires a 64-bit Linux ARM handheld with PortMaster. Copy a canonical US Red or Blue .gb into gen1recomp-sbc/lovegame/, then launch and press Choose ROM.",
+    "genres": ["adventure", "rpg"],
+    "porter": ["gen1recomp-sbc"],
+    "image": {},
+    "rtr": true,
+    "runtime": null,
+    "reqs": [],
+    "arch": ["aarch64"]
+  }
+}
+EOF
+
+cat > "$PORT_ROOT/gameinfo.xml" <<EOF
+<?xml version="1.0" encoding="utf-8"?>
+<gameList>
+  <game>
+    <path>./$LAUNCHER_NAME</path>
+    <name>gen1recomp-sbc</name>
+    <desc>Native LÖVE2D recreation of Pokemon Red and Blue. Requires your own legal US Red or Blue ROM.</desc>
+    <releasedate>20250101T000000</releasedate>
+    <developer>the bois club</developer>
+    <publisher>the bois club</publisher>
+    <genre>RPG</genre>
+  </game>
+</gameList>
+EOF
+
+cat > "$PORT_ROOT/README.md" <<'EOF'
+## gen1recomp-sbc (Linux ARM SBC / PortMaster)
+
+Native LÖVE 11.5 aarch64 PortMaster port of gen1recomp for compatible Linux ARM SBC handhelds, including H700-class devices. This pack was built from source release **__SOURCE_TAG__**.
+
+### Install
+
+1. Install PortMaster for your handheld firmware.
+2. Unzip so `gen1recomp-sbc.sh` and the `gen1recomp-sbc/` folder are siblings in the device's PortMaster ports directory.
+3. Copy a legal US Pokémon Red or Blue `.gb` into `gen1recomp-sbc/lovegame/`.
+4. Refresh the launcher and launch **gen1recomp-sbc** from Ports.
+
+### Controls
+
+| Input | Action |
+|--|--|
+| D-pad | Move cursor |
+| A | Click |
+| L1 / R1 | Switch tabs |
+| Start / Select | Play or choose ROM |
+
+Controls use the normal PortMaster / SDL pad map. Device-specific power/suspend behavior is supplied by the firmware and PortMaster runtime.
+
+### First run
+
+Put the `.gb` in `lovegame/`, then press **Choose ROM**. After import, the ROM-derived cache and saves stay beside the game (`portable.txt`).
+
+### Thanks
+
+LÖVE runtime binaries from [PortMaster](https://portmaster.games/). PortMaster device support and runtime integration are maintained by the PortMaster team.
+EOF
+sed -i.bak "s/__SOURCE_TAG__/$SOURCE_TAG/g" "$PORT_ROOT/README.md"
+rm -f "$PORT_ROOT/README.md.bak"
+
+# --------------------------------------------------------------- zip
+ZIP_OUT="$DIST/$APP_NAME-$ARTIFACT_SUFFIX.zip"
+rm -f "$ZIP_OUT"
+say "packing $ZIP_OUT"
+(cd "$PORT_ROOT" && zip -q -9 -r "$ZIP_OUT" \
+  "$LAUNCHER_NAME" "$PORT_DIR_NAME" port.json gameinfo.xml README.md)
+
+say "done."
+say "artifact: $ZIP_OUT ($(du -h "$ZIP_OUT" | cut -f1))"
+say "copy into the device PortMaster ports folder, then drop your .gb into gen1recomp-sbc/lovegame/"
@@ -91,11 +91,14 @@ mkdir -p "$GAME_SRC"
 (cd "$ROOT" && zip -q -9 -r "$WORK/game-payload.zip" \
  main.lua conf.lua src libs data assets tools/save-editor \
  tools/rom_manifest.json tools/rom_manifest_blue.json \
+  tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
  -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
-if unzip -Z1 "$WORK/game-payload.zip" \
-    | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/'; then
-  fail "payload unexpectedly contains generated ROM data"
-fi
+payload_list="$(unzip -Z1 "$WORK/game-payload.zip")"
+printf '%s\n' "$payload_list" \
+  | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/' \
+  && fail "payload unexpectedly contains generated ROM data"
+printf '%s\n' "$payload_list" | grep -qxF "tools/rom_manifest_gold.json" \
+  || fail "payload is missing tools/rom_manifest_gold.json"
 unzip -q "$WORK/game-payload.zip" -d "$GAME_SRC"
 rm -f "$WORK/game-payload.zip"

@@ -92,7 +92,7 @@ return {
      { "set_flag", "EVENT_GOT_EEVEE" },                       -- 7
      { "hide_object", "CELADON_MANSION_ROOF_HOUSE",
        "CELADONMANSION_ROOF_HOUSE_EEVEE_POKEBALL" },          -- 8
-      { "play_sound", "Get_Item1" },                           -- 9 (GotMonText jingle)
+      { "text_sound", "Get_Item1" },                           -- 9 (GotMonText jingle)
      { "show_text", "_GotMonText", { RAM = "EEVEE" } },       -- 10
      { "jump", 13 },                                          -- 11
      { "show_text", "_BoxIsFullText" },                       -- 12
@@ -10,10 +10,10 @@
 local function coinGiver(opts)
  return function(game, ow, npc, done)
    local TextBox = require("src.render.TextBox")
-    local Sound = require("src.core.Sound")
    local t = game.data.text
-    local function push(label, fallback, onDone)
-      game.stack:push(TextBox.new(game, t[label] or fallback, onDone or done))
+    local function push(label, fallback, onDone, popts)
+      game.stack:push(TextBox.new(game, t[label] or fallback, onDone or done,
+                                  popts))
    end
    if game.save.flags[opts.event] then
      push(opts.alreadyGotLabel, opts.alreadyGotFallback)
@@ -30,9 +30,10 @@ local function coinGiver(opts)
      end
      game.save.coins = math.min(9999, (game.save.coins or 0) + opts.amount)
      game.save.flags[opts.event] = true
-      Sound.play(game.data, "Get_Item1")
+      -- the ReceivedNCoinsText strings carry sound_get_item_1
      push(opts.receivedLabel,
-        ("{PLAYER} received\n%d coins!"):format(opts.amount))
+        ("{PLAYER} received\n%d coins!"):format(opts.amount), nil,
+        TextBox.soundOpts(game, "Get_Item1"))
    end)
  end
 end
@@ -22,8 +22,8 @@ return {
        local TextBox = require("src.render.TextBox")
        local Commands = require("src.script.Commands")
        local t = game.data.text
-        local function say(label, cb)
-          game.stack:push(TextBox.new(game, t[label] or label, cb))
+        local function say(label, cb, sopts)
+          game.stack:push(TextBox.new(game, t[label] or label, cb, sopts))
        end

        if game.save.flags.EVENT_GOT_OLD_AMBER then
@@ -39,8 +39,9 @@ return {
          game.save.flags.EVENT_GOT_OLD_AMBER = true
          Commands.hide_object({ save = game.save, overworld = ow, game = game },
                                "MUSEUM_1F", "MUSEUM1F_OLD_AMBER")
-          require("src.core.Sound").play(game.data, "Get_Item1")
-          say("_Museum1FScientist2ReceivedOldAmberText", done)
+          -- .ReceivedOldAmberText carries sound_get_item_1
+          say("_Museum1FScientist2ReceivedOldAmberText", done,
+              TextBox.soundOpts(game, "Get_Item1"))
        end)
      end,

@@ -1,13 +1,39 @@
-- Hand-ported flavor text for OaksLab (registry id OAKS_LAB).
-- Source: pokered/scripts/OaksLab.asm.  These five text_asm bodies are
-- all simple "PrintText; jp TextScriptEnd" -- no flag branches, no
-- YES/NO menu -- so a one-row talk script showing the real extracted
-- text is a faithful port.  (The rest of OaksLab.asm's TEXT_OAKSLAB_*
-- constants -- OAK1, the three starter poke balls, RIVAL -- are already
-- ported with full branching logic in data/scripts/oaks_lab.lua.)
+-- Hand-ported OAKS_LAB flavor: the simple talk texts (scripts/OaksLab.asm;
+-- OAK1, the starter balls and RIVAL live in data/scripts/oaks_lab.lua).
+
+local TextBox = require("src.render.TextBox")

 return {
  OAKS_LAB = {
+    -- data/events/hidden_events.asm:147
+    onInteract = function(game, ow, fx, fy)
+      local t = game.data.text or {}
+      -- engine/events/hidden_events/oaks_lab_posters.asm:1
+      if fy == 0 and fx == 4 then
+        game.stack:push(TextBox.new(game,
+          t._PushStartText or "Push START to\nopen the MENU!"))
+        return true
+      end
+      if fy == 0 and fx == 5 then
+        local owned = 0
+        for _ in pairs(game.save.pokedex.owned or {}) do owned = owned + 1 end
+        game.stack:push(TextBox.new(game,
+          owned >= 2
+            and (t._StrengthsAndWeaknessesText
+                 or "All POKéMON types\nhave strong and\vweak points\vagainst others.")
+            or (t._SaveOptionText
+                or "The SAVE option is\non the MENU\vscreen.")))
+        return true
+      end
+      -- engine/events/hidden_events/oaks_lab_email.asm:1
+      if fy == 1 and (fx == 0 or fx == 1) then
+        if ow.player.facing ~= "up" then return false end
+        game.stack:push(TextBox.new(game,
+          t._OakLabEmailText or "There's an e-mail\nmessage here!"))
+        return true
+      end
+      return false
+    end,
    talk = {
      -- OaksLabGirlText (scripts/OaksLab.asm)
      TEXT_OAKSLAB_GIRL = {
@@ -3,9 +3,8 @@
 -- guide and SUPER_NERD2 garden nerd.
 --
 -- The YOUNGSTER's gym escort (talk + east-exit onStep) lives in
-- story5.lua so the lockstep RLE walk is not overwritten by this
-- flavor merge.  SUPER_NERD1's museum escort is not ported; only the
-- YES/NO-branched flavor text is here.
+-- story5.lua; SUPER_NERD1's museum escort (scripts/PewterCity.asm:47-113)
+-- is below.

 local M = {}

@@ -16,16 +15,147 @@ local function push(game, s, done)
  game.stack:push(TextBox.new(game, s, done))
 end

+-- PrintText on a text_end string returns with the box still drawn and
+-- YesNoChoice then draws the menu above it (InitYesNoTextBoxParameters,
+-- engine/menus/text_box.asm); no A press clears the question first.  Ride
+-- TextBox's opts.choice, the same as Commands.ask (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
+end
+
+-- RLEList_PewterMuseumGuy (engine/overworld/auto_movement.asm:199-204)
+local museumGuySteps = {
+  "up", "up", "up", "up", "up", "up",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left", "left", "left",
+  "up", "up", "up",
+  "left",
+}
+
+-- RLEList_PewterMuseumPlayer (engine/overworld/auto_movement.asm:192-197)
+local museumPlayerRle = {
+  "NO",
+  "up", "up", "up",
+  "left", "left", "left", "left", "left", "left", "left", "left",
+  "left", "left", "left", "left", "left",
+  "up", "up", "up", "up", "up", "up",
+}
+
+-- PewterMuseumGuyCoords (engine/events/pewter_guys.asm:58-75)
+local museumPreambles = {
+  ["27,18"] = { "up", "up" },
+  ["27,16"] = { "right", "left" },
+  ["26,17"] = { "up", "right" },
+  ["28,17"] = { "up", "left" },
+}
+
+-- PewterGuys (engine/events/pewter_guys.asm:1-49), same transform as
+-- pewterEscort.playerPlan in story5.lua
+local function museumPlan(x, y)
+  local pre = museumPreambles[x .. "," .. y]
+  if not pre then return nil end
+  local buf = {}
+  for i, d in ipairs(museumPlayerRle) do buf[i] = d end
+  buf[#buf] = pre[1]
+  for i = 2, #pre do buf[#buf + 1] = pre[i] end
+  local path = {}
+  for i = #buf, 1, -1 do path[#path + 1] = buf[i] end
+  local head = 0
+  while path[head + 1] == "NO" do head = head + 1 end
+  local tail = #path
+  while tail > head and path[tail] == "NO" do tail = tail - 1 end
+  local steps = {}
+  for i = head + 1, tail do steps[#steps + 1] = path[i] end
+  return { steps = steps, guyHeadStart = math.floor(head / 8) }
+end
+
+-- PewterCitySuperNerd1ShowsPlayerMuseumScript (scripts/PewterCity.asm:47-113)
+local function museumEscortWalk(game, ow)
+  if ow.runner:isRunning() or #ow.scriptMoves > 0 then return false end
+  local plan = museumPlan(ow.player.cellX, ow.player.cellY)
+  if not plan then return false end
+  local Music = require("src.core.Music")
+  local t = text(game)
+  local guy = ow:npcByIndex(3) -- PEWTERCITY_SUPER_NERD1
+  local head = plan.guyHeadStart
+
+  -- SetSpritePosition2 + ShowObject back on his spawn (27,17), the same
+  -- snap walkHome does in story5.lua (scripts/PewterCity.asm:102-113)
+  local function walkOut()
+    if not guy then return end
+    local i = 0
+    local function tick()
+      i = i + 1
+      if i > 4 then
+        guy.cellX, guy.cellY = 27, 17
+        guy.px, guy.py = 27 * 16, 17 * 16
+        guy.moving = false
+        guy.targetX, guy.targetY = nil, nil
+        guy.facing = "down"
+        return
+      end
+      ow:scriptMove(guy, "down", 1, tick)
+    end
+    tick()
+  end
+
+  -- SetSpritePosition1 pins him beside the museum door (map (17,12) minus
+  -- the +4 border offset = (13,8)), then MovementData_PewterMuseumGuyExit
+  local function afterWalk()
+    if guy then
+      guy.stepFrames = nil
+      guy.cellX, guy.cellY = 13, 8
+      guy.px, guy.py = 13 * 16, 8 * 16
+      guy.moving = false
+      guy.targetX, guy.targetY = nil, nil
+      guy.facing = "up"
+    end
+    Music.playMap(game.data, "PEWTER_CITY")
+    push(game, t._PewterCitySuperNerd1ItsRightHereText
+      or "It's right here!", walkOut)
+  end
+
+  local function lockstep()
+    local i = 0
+    local function tick()
+      i = i + 1
+      local ps = plan.steps[i]
+      if not ps then
+        afterWalk()
+        return
+      end
+      local gs = museumGuySteps[head + i]
+      if guy and gs then ow:scriptMove(guy, gs, 1) end
+      ow:scriptMove(ow.player, ps, 1, tick)
+    end
+    tick()
+  end
+
+  -- engine/overworld/movement.asm:737 (DoScriptedNPCMovement)
+  if guy then
+    guy.stepFrames = ow.player.stepFramesCur or ow.player.stepFrames
+  end
+  Music.play(game.data, "Music_MuseumGuy")
+  if guy and head > 0 then
+    local h = 0
+    local function headTick()
+      h = h + 1
+      if h > head then lockstep(); return end
+      ow:scriptMove(guy, museumGuySteps[h], 1, headTick)
+    end
+    headTick()
+  else
+    lockstep()
+  end
+  return true
 end

 M.PEWTER_CITY = {
+  museumEscort = { plan = museumPlan, guySteps = museumGuySteps },
  talk = {
-    -- PewterCitySuperNerd1Text (scripts/PewterCity.asm): asks if you
-    -- checked out the museum; YES -> fossils comment, NO -> "you have
-    -- to go" (which in pokered also kicks off the escort script).
+    -- PewterCitySuperNerd1Text (scripts/PewterCity.asm:209-237): YES ->
+    -- fossils comment, NO -> "you have to go" and the museum escort
    TEXT_PEWTERCITY_SUPER_NERD1 = function(game, ow, npc, done)
      local t = text(game)
      ask(game, t._PewterCitySuperNerd1DidYouCheckOutMuseumText
@@ -35,7 +165,10 @@ M.PEWTER_CITY = {
            or "Weren't those\nfossils from MT.\nMOON amazing?", done)
        else
          push(game, t._PewterCitySuperNerd1YouHaveToGoText
-            or "Really?\nYou absolutely\nhave to go!", done)
+            or "Really?\nYou absolutely\nhave to go!", function()
+            museumEscortWalk(game, ow)
+            if done then done() end
+          end)
        end
      end)
    end,
@@ -23,9 +23,13 @@ local function push(game, s, done)
  game.stack:push(TextBox.new(game, s, done))
 end

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

 M.VIRIDIAN_CITY = {
@@ -18,6 +18,26 @@ local M = {
  VIRIDIAN_GYM  = { city = "VIRIDIAN CITY",  leader = "GIOVANNI", badge = "EARTHBADGE" },
 }

+-- The originals' middle branch shared by every leader's text_asm: beaten
+-- but EVENT_GOT_TM* unset means the bag was full when the victory script
+-- ran GiveItem, so talking to the leader re-runs the ReceiveTM script.
+-- Returns true when the retry took over the talk.  A save from before
+-- #797 already holds the TM without the flag; treat the owned TM as
+-- received so those saves fall through to the advice text instead of
+-- collecting a second copy.
+local function retryTmGive(game, ow, victoryKey, done)
+  local reward = require("data.scripts.victories")[victoryKey]
+  if not (reward and reward.gotFlag) then return false end
+  if game.save.flags[reward.gotFlag] then return false end
+  local owned = game.save.inventory and game.save.inventory[reward.item] or 0
+  if owned > 0 then
+    game.save.flags[reward.gotFlag] = true
+    return false
+  end
+  ow:offerGymTm(reward, done)
+  return true
+end
+
 -- scripts/PewterGym.asm PewterGymBrockText (text_asm): CheckEvent
 -- EVENT_BEAT_BROCK branches his dialogue.  Before the badge he prints
 -- _PewterGymBrockPreBattleText and engages the leader battle
@@ -25,12 +45,14 @@ local M = {
 -- badge/TM34 rewards and EVENT_BEAT_BROCK come from
 -- data/scripts/victories.lua OPP_BROCK#1).  After the badge his
 -- .afterBeat branch prints _PewterGymBrockPostBattleAdviceText ("Go to
-- the GYM in CERULEAN...").  The original's middle branch (beat but
-- TM34 not yet handed over, CheckEventReuseA EVENT_GOT_TM34) is
-- unreachable in the port: the TM is granted with the victory.
+-- the GYM in CERULEAN...").  The middle branch (beat but TM34 not yet
+-- handed over, CheckEventReuseA EVENT_GOT_TM34 -> call
+-- PewterGymScriptReceiveTM34) retries the TM give when the bag was full
+-- at the victory (#797).
 M.PEWTER_GYM.talk = {
  TEXT_PEWTERGYM_BROCK = function(game, ow, npc, done)
    if game.save.flags.EVENT_BEAT_BROCK then
+      if retryTmGive(game, ow, "OPP_BROCK#1", done) then return end
      local TextBox = require("src.render.TextBox")
      game.stack:push(TextBox.new(game,
        game.data.text._PewterGymBrockPostBattleAdviceText
@@ -48,16 +70,17 @@ M.PEWTER_GYM.talk = {
 -- (engageTrainer shows that same pre-battle text via resolveText; the
 -- badge/TM rewards and the beat flag come from data/scripts/victories.lua)
 -- -- and once beaten print the post-battle advice text.  As with Brock,
-- the originals' middle branch (beaten but the TM not yet handed over,
-- CheckEventReuseA EVENT_GOT_TM*) is unreachable in the port: the TM is
-- granted with the victory.
+-- the middle branch (beaten but the TM not yet handed over,
+-- CheckEventReuseA EVENT_GOT_TM*) retries the TM give when the bag was
+-- full at the victory.
 -- afterAdvice, when given, takes over `done`: it is handed (game, ow, npc,
 -- done) and must call done() itself once whatever it's doing (e.g. a fade
 -- around a HideObject) finishes, rather than having it invoked
 -- automatically. Only Giovanni's farewell uses this.
-local function leaderTalk(beatFlag, adviceLabel, fallback, afterAdvice)
+local function leaderTalk(beatFlag, adviceLabel, fallback, afterAdvice, victoryKey)
  return function(game, ow, npc, done)
    if game.save.flags[beatFlag] then
+      if victoryKey and retryTmGive(game, ow, victoryKey, done) then return end
      local TextBox = require("src.render.TextBox")
      local finish = done
      if afterAdvice then
@@ -79,42 +102,42 @@ end
 M.CERULEAN_GYM.talk = {
  TEXT_CERULEANGYM_MISTY = leaderTalk("EVENT_BEAT_MISTY",
    "_CeruleanGymMistyTM11ExplanationText",
-    "TM11 teaches\nBUBBLEBEAM!"),
+    "TM11 teaches\nBUBBLEBEAM!", nil, "OPP_MISTY#1"),
 }

 -- scripts/VermilionGym.asm VermilionGymLTSurgeText .got_tm24_already
 M.VERMILION_GYM.talk = {
  TEXT_VERMILIONGYM_LT_SURGE = leaderTalk("EVENT_BEAT_LT_SURGE",
    "_VermilionGymLTSurgePostBattleAdviceText",
-    "A little word of\nadvice, kid!"),
+    "A little word of\nadvice, kid!", nil, "OPP_LT_SURGE#1"),
 }

 -- scripts/CeladonGym.asm CeladonGymErikaText .afterBeat
 M.CELADON_GYM.talk = {
  TEXT_CELADONGYM_ERIKA = leaderTalk("EVENT_BEAT_ERIKA",
    "_CeladonGymErikaPostBattleAdviceText",
-    "You are cataloging\nPOKéMON? I must\nsay I'm impressed."),
+    "You are cataloging\nPOKéMON? I must\nsay I'm impressed.", nil, "OPP_ERIKA#1"),
 }

 -- scripts/FuchsiaGym.asm FuchsiaGymKogaText .afterBeat
 M.FUCHSIA_GYM.talk = {
  TEXT_FUCHSIAGYM_KOGA = leaderTalk("EVENT_BEAT_KOGA",
    "_FuchsiaGymKogaPostBattleAdviceText",
-    "When afflicted by\nTOXIC, POKéMON\nsuffer more and\nmore as battle\nprogresses!"),
+    "When afflicted by\nTOXIC, POKéMON\nsuffer more and\nmore as battle\nprogresses!", nil, "OPP_KOGA#1"),
 }

 -- scripts/SaffronGym.asm SaffronGymSabrinaText .afterBeat
 M.SAFFRON_GYM.talk = {
  TEXT_SAFFRONGYM_SABRINA = leaderTalk("EVENT_BEAT_SABRINA",
    "_SaffronGymSabrinaPostBattleAdviceText",
-    "Everyone has\npsychic power!\nPeople just don't\nrealize it!"),
+    "Everyone has\npsychic power!\nPeople just don't\nrealize it!", nil, "OPP_SABRINA#1"),
 }

 -- scripts/CinnabarGym.asm CinnabarGymBlaineText .afterBeat
 M.CINNABAR_GYM.talk = {
  TEXT_CINNABARGYM_BLAINE = leaderTalk("EVENT_BEAT_BLAINE",
    "_CinnabarGymBlainePostBattleAdviceText",
-    "FIRE BLAST is the\nultimate fire\ntechnique!"),
+    "FIRE BLAST is the\nultimate fire\ntechnique!", nil, "OPP_BLAINE#1"),
 }

 -- scripts/ViridianGym.asm ViridianGymGiovanniText .afterBeat: after the
@@ -142,7 +165,7 @@ M.VIRIDIAN_GYM.talk = {
            "VIRIDIAN_GYM", "VIRIDIANGYM_GIOVANNI")
        end
      end, done))
-    end),
+    end, "OPP_GIOVANNI#3"),
 }

 return M
@@ -22,10 +22,10 @@ local function starterBall(askText, species, choseFlag, ownBall,
                           rivalBallX, rivalBall)
  return {
    { "check_flag", "EVENT_GOT_STARTER" },        -- 1
-    { "jump_if_true", 22 },                       -- 2
+    { "jump_if_true", 23 },                       -- 2
    -- no picking until Oak has walked you in (OaksLabScript gating)
    { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB" }, -- 3
-    { "jump_if_false", 25 },                      -- 4
+    { "jump_if_false", 26 },                      -- 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;
@@ -34,44 +34,38 @@ local function starterBall(askText, species, choseFlag, ownBall,
      { species = species, forceOwned = true } }, -- 5
    { "ask", askText },                           -- 6
    { "jump_if_false", "end" },                   -- 7
-    -- 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.
-    -- 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 },       -- 13
+    -- scripts/OaksLab.asm:919
+    { "show_text", "_OaksLabMonEnergeticText" },  -- 8
+    -- OaksLab.asm: ReceivedMon (sound_get_key_item) then AddPartyMon; the
+    -- jingle fires once the box has typed and holds it (#668)
+    { "text_sound", "Get_Key_Item" },                              -- 9
+    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 10
+    { "give_pokemon", species, 5 },               -- 11
+    { "set_flag", "EVENT_GOT_STARTER" },          -- 12
+    { "set_flag", choseFlag },                    -- 13
+    -- POKé BALLs come later, at OaksLabOak1Text's .give_poke_balls beat
+    -- once the Route 22 rival is beaten (see TEXT_OAKSLAB_OAK1 below)
+    { "hide_object", "OAKS_LAB", ownBall },       -- 14
    -- the rival walks to the countering ball (around the furniture)
-    { "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)
+    { "move_npc_to", 1, rivalBallX, 4 },          -- 15
+    { "face_object", 1, "up" },                   -- 16
+    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 17
+    { "hide_object", "OAKS_LAB", rivalBall },     -- 18
+    { "text_sound", "Get_Key_Item" },             -- 19 (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" } },                 -- 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" },                 -- 22
-    { "show_text", "That's PROF.OAK's\nlast Pokémon!" }, -- 23
+              or "BULBASAUR" } },                 -- 20
+    { "jump", "end" },                            -- 21
+    { "jump", "end" },                            -- 22 (spacer)
+    -- leftover ball: Oak reads the last-mon line (scripts/OaksLab.asm
+    -- OaksLabSelectedPokeBallScript -> OaksLabLastMonScript, #601)
+    { "face_object", 5, "down" },                 -- 23
+    { "show_text", "That's PROF.OAK's\nlast Pokémon!" }, -- 24
    -- 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
+    { "jump", "end" },                            -- 25
+    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 26
  }
 end

@@ -106,8 +100,8 @@ return {
      { "check_item", "OAKS_PARCEL" },
      { "jump_if_false", "raise_young" },
      -- OaksLabOak1Text.got_parcel → RivalArrives + OakGivesPokedex
+      { "text_sound", "Get_Key_Item" },
      { "show_text", "_OaksLabOak1DeliverParcelText" },
-      { "play_sound", "Get_Key_Item" },
      { "show_text", "_OaksLabOak1ParcelThanksText" },
      { "take_item", "OAKS_PARCEL", 1 },
      { "stop_music" },
@@ -128,8 +122,8 @@ return {
      { "face_object", 1, "up" },
      { "face_object", 5, "down" },
      { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "text_sound", "Get_Key_Item" },
      { "show_text", "_OaksLabOakGotPokedexText" },
-      { "play_sound", "Get_Key_Item" },
      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
      { "face_object", 1, "up" },
@@ -246,9 +240,17 @@ return {
  -- the table sprites; re-entering the lab applies the same HideObject
  -- the gift script now does (OaksLab.asm OakGivesPokedex).
  onEnter = function(game, ow)
-    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
-      return
+    local flags = game.save.flags or {}
+    if flags.EVENT_GOT_STARTER and not flags.EVENT_BATTLED_RIVAL_IN_OAKS_LAB then
+      local rival = ow:npcByIndex(1)
+      if rival then
+        rival.cellX = flags.EVENT_CHOSE_CHARMANDER and 7
+          or flags.EVENT_CHOSE_SQUIRTLE and 8 or 6
+        rival.cellY = 4
+        rival.px, rival.py = rival.cellX * 16, rival.cellY * 16
+      end
    end
+    if not flags.EVENT_GOT_POKEDEX then return end
    local Commands = require("src.script.Commands")
    local ctx = { save = game.save, game = game, overworld = ow }
    Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX1")
@@ -286,6 +288,8 @@ return {
      -- fanfare for the taunt/challenge exchange, same as the Yellow port
      -- (oaks_lab_yellow.lua); it was silently dropped here (#596).
      local rows = {
+        { "face_object", 1, "down" },  -- scripts/OaksLab.asm:347-351
+        { "face_player_dir", "up" },
        { "stop_music" },
        { "play_music", "Music_MeetRival" },
        { "show_text", "_OaksLabRivalIllTakeYouOnText" },         -- 1
@@ -309,28 +313,19 @@ return {
      local base = #rows
      local party = flags.EVENT_CHOSE_BULBASAUR and 3
                    or flags.EVENT_CHOSE_SQUIRTLE and 2 or 1
+      table.insert(rows, { "save_end_battle_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
      table.insert(rows, { "start_battle", "trainer", "OPP_RIVAL1", party })
      -- OaksLabRivalEndBattleScript: heal + flag on win or loss; no blackout
      table.insert(rows, { "heal_party" })
      table.insert(rows, { "set_flag", "EVENT_BATTLED_RIVAL_IN_OAKS_LAB" })
-      -- OaksLabRivalEndBattleScript: on WIN, print the "picked the wrong
-      -- POKéMON!" gloat, then BOTH win and loss print the shared exit line
-      -- _OaksLabRivalSmellYouLaterText ("OK! I'll make my POKéMON fight to
-      -- toughen it up!\012<PLAYER>! Gramps! Smell you later!") before Blue
-      -- marches out.  A loss skips only the gloat (that taunt was already
-      -- shown in-battle via Rival1WinText), never the exit line (#231).  The
-      -- jump_if_false convergence point is the exit line: base+6 indexes the
-      -- SmellYouLater row below, so WIN falls IPicked -> SmellYouLater and
-      -- LOSS jumps straight to SmellYouLater (both then walk-out + hide).
      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, { "play_music", "Music_MeetRival", { start = "rival" } })
      table.insert(rows, { "move_npc_to", 1, 4, 11 })
      table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
      table.insert(rows, { "play_music", "Music_OaksLab" })
@@ -38,13 +38,15 @@ return {
      { "jump_if_false", "raise_young" },
      -- .DeliverParcelText: parcel handover, then the Pokédex scene
      -- (OaksLabRivalArrivesAtOaksRequestScript -> OakGivesPokedexScript)
+      { "text_sound", "Get_Key_Item" },
      { "show_text", "_OaksLabOak1DeliverParcelText" },
-      { "play_sound", "Get_Key_Item" },
      { "show_text", "_OaksLabOak1ParcelThanksText" },
      { "take_item", "OAKS_PARCEL", 1 },
      { "stop_music" },
      { "play_music", "Music_MeetRival" },
      { "show_text", "_OaksLabRivalGrampsText" },
+      -- callfar OaksLabPikachuMovementScript, before ShowObject (#1021)
+      { "pikachu_make_way" },
      { "show_object", "OAKS_LAB", "OAKSLAB_RIVAL" },
      { "place_npc", RIVAL, 4, 7, "up" },
      { "move_npc_to", RIVAL, 4, 3 },
@@ -60,8 +62,8 @@ return {
      { "face_object", RIVAL, "up" },
      { "face_object", OAK1, "down" },
      { "show_text", "_OaksLabOakMyInventionPokedexText" },
+      { "text_sound", "Get_Key_Item" },
      { "show_text", "_OaksLabOakGotPokedexText" },
-      { "play_sound", "Get_Key_Item" },
      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX1" },
      { "hide_object", "OAKS_LAB", "OAKSLAB_POKEDEX2" },
      { "face_object", RIVAL, "up" },
@@ -111,8 +113,8 @@ return {
      { "jump_if_true", "come_see" },
      { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
      { "give_item", "POKE_BALL", 5, false },
+      { "text_sound", "Get_Key_Item" },
      { "show_text", "_OaksLabOak1ReceivedPokeballsText" },
-      { "play_sound", "Get_Key_Item" },
      { "show_text", "_OaksLabGivePokeballsExplanationText" },
      { "jump", "end" },

@@ -174,7 +176,7 @@ return {
      -- rival starter baseline (RIVAL_STARTER_JOLTEON) at snatch time
      rows[#rows + 1] = { "set_field", "rivalStarter", 1 }
      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText1" }
-      rows[#rows + 1] = { "play_sound", "Get_Key_Item" }
+      rows[#rows + 1] = { "text_sound", "Get_Key_Item" }
      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText2" }
      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText3" }
      rows[#rows + 1] = { "show_text", "_OaksLabRivalTakesText4" }
@@ -192,15 +194,17 @@ return {
      end
      rows[#rows + 1] = { "face_player_dir", "up" }
      rows[#rows + 1] = { "face_object", OAK1, "down" }
-      -- OaksLabPlayerReceivedMonText: no nickname prompt -- the starter
-      -- Pikachu keeps its species name
+      -- OaksLabPlayerReceivedMonText clears wMonDataLocation, so AskName runs (#1013)
      rows[#rows + 1] = { "show_text", "_OaksLabOakGivesText" }
-      rows[#rows + 1] = { "play_sound", "Get_Key_Item" }
+      rows[#rows + 1] = { "text_sound", "Get_Key_Item" }
      rows[#rows + 1] = { "show_text", "_OaksLabReceivedText", { RAM = "PIKACHU" } }
-      rows[#rows + 1] = { "give_pokemon", "PIKACHU", 5, true }
+      rows[#rows + 1] = { "give_pokemon", "PIKACHU", 5 }
+      -- DisablePikachuOverworldSpriteDrawing keeps it in the ball (#1009)
+      rows[#rows + 1] = { "set_field", "pikachuInBall", true }
      rows[#rows + 1] = { "set_flag", "EVENT_GOT_STARTER" }
      rows[#rows + 1] = { "set_flag", "EVENT_CHOSE_PIKACHU" }
-      ow.runner:run(rows, { npc = npc, onDone = done })
+      ow.runner:run(rows, { npc = npc, onDone = done,
+        checkpointOnDone = "release_npc" })
    end,

    TEXT_OAKSLAB_RIVAL = {
@@ -222,9 +226,15 @@ return {
  },

  onEnter = function(game, ow)
-    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
-      return
+    local flags = game.save.flags or {}
+    if flags.EVENT_GOT_STARTER and not flags.EVENT_BATTLED_RIVAL_IN_OAKS_LAB then
+      local rival = ow:npcByIndex(RIVAL)
+      if rival then
+        rival.cellX, rival.cellY = 7, 4
+        rival.px, rival.py = 7 * 16, 4 * 16
+      end
    end
+    if not flags.EVENT_GOT_POKEDEX then return end
    local Commands = require("src.script.Commands")
    local ctx = { save = game.save, game = game, overworld = ow }
    Commands.hide_object(ctx, "OAKS_LAB", "OAKSLAB_POKEDEX1")
@@ -253,6 +263,7 @@ return {
      local rival = ow:npcByIndex(RIVAL)
      if not rival then return false end
      local rows = {
+        { "face_object", RIVAL, "down" },  -- pokeyellow scripts/OaksLab.asm:311-315
        { "face_player_dir", "up" },
        { "stop_music" },
        { "play_music", "Music_MeetRival" },
@@ -292,13 +303,14 @@ return {
      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, { "play_music", "Music_MeetRival", { start = "rival" } })
      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" })
-      -- OaksLabPikachuEscapesPokeballScript: Pikachu hates its ball.
-      -- The overworld follower itself is still an open port
-      -- (docs/yellow-version.md runtime backlog); the story beat plays.
+      -- OaksLabPikachuEscapesPokeballScript: the follower reaches the map (#1009)
+      table.insert(rows, { "face_player_dir", "up" })
+      table.insert(rows, { "set_field", "pikachuInBall", false })
+      table.insert(rows, { "spawn_pikachu_follower" })
      table.insert(rows, { "play_cry", "PIKACHU" })
      table.insert(rows, { "show_text", "_OaksLabPikachuDislikesPokeballsText1" })
      table.insert(rows, { "show_text", "_OaksLabPikachuDislikesPokeballsText2" })
@@ -140,22 +140,29 @@ M.VIRIDIAN_CITY = {
 -- Daisy hands over the TOWN MAP once Oak's errand is under way
 -- (scripts/BluesHouse.asm BluesHouseDaisySittingText)
 M.BLUES_HOUSE = {
+  -- scripts/BluesHouse.asm:12-16
+  onEnter = function(game, ow)
+    game.save.flags.EVENT_ENTERED_BLUES_HOUSE = true
+  end,
  talk = {
    TEXT_BLUESHOUSE_DAISY_SITTING = {
-      { "face_player" },                                     -- 1
-      { "check_flag", "EVENT_GOT_TOWN_MAP" },                -- 2
-      { "jump_if_true", 10 },                                -- 3
-      { "check_flag", "EVENT_GOT_STARTER" },                 -- 4
-      { "jump_if_false", 12 },                               -- 5
-      { "show_text", "_BluesHouseDaisyOfferMapText" },       -- 6
+      { "face_player" },
+      { "check_flag", "EVENT_GOT_TOWN_MAP" },
+      { "jump_if_true", "got_map" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_false", "too_early" },
+      { "show_text", "_BluesHouseDaisyOfferMapText" },
      -- _GotMapText: "{PLAYER} got a\n{RAM:wStringBuffer}!" -- the
      -- buffer supplies "TOWN MAP" (scripts/BluesHouse.asm GotMapText)
-      { "give_item", "TOWN_MAP", 1, "_GotMapText" },         -- 7
-      { "set_flag", "EVENT_GOT_TOWN_MAP" },                  -- 8
-      { "jump", 13 },                                        -- 9
-      { "show_text", "_BluesHouseDaisyUseMapText" },         -- 10
-      { "jump", 13 },                                        -- 11
-      { "show_text", "_BluesHouseDaisyRivalAtLabText" },     -- 12
+      { "give_item", "TOWN_MAP", 1, "_GotMapText" },
+      { "hide_object", "BLUES_HOUSE", "BLUESHOUSE_TOWN_MAP" },
+      { "set_flag", "EVENT_GOT_TOWN_MAP" },
+      { "jump", "end" },
+      { "label", "got_map" },
+      { "show_text", "_BluesHouseDaisyUseMapText" },
+      { "jump", "end" },
+      { "label", "too_early" },
+      { "show_text", "_BluesHouseDaisyRivalAtLabText" },
    },
  },
 }
@@ -294,6 +301,7 @@ M.BILLS_HOUSE = {

 M.ROUTE_25 = {
  onEnter = function(game, ow)
+    game.save.pikachuMapScriptActive = nil
    local flags = game.save.flags
    if flags.EVENT_LEFT_BILLS_HOUSE_AFTER_HELPING then return end
    local Commands = require("src.script.Commands")
@@ -326,6 +334,7 @@ M.VERMILION_CITY = {
  -- only read while EVENT_1ST_LOCK_OPENED is unset (the gym is only
  -- reachable through this map, so a fresh visit always re-rolls).
  onEnter = function(game, ow)
+    game.save.pikachuMapScriptActive = nil
    local puz = game.save.trashPuzzle or {}
    game.save.trashPuzzle = puz
    puz.first = love.math.random(0, 7) * 2
@@ -800,9 +809,13 @@ M.SILPH_CO_11F = {
  -- line) would touch, and the whole Silph ending -- the flag, the Master
  -- Ball, the Saffron streets clearing -- silently never happened.
  --
-  -- engageTrainer shows TEXT_SILPHCO11F_GIOVANNI as the battle text and,
-  -- via victories.lua OPP_GIOVANNI#2, sets the event on a win; a loss
-  -- sets nothing, so the trigger re-arms exactly as vanilla does.
+  -- SilphCo11FDefaultScript orders it DisplayTextID TEXT_SILPHCO11F_GIOVANNI
+  -- FIRST, then MoveSprite .GiovanniMovement: he speaks from behind the desk
+  -- and only then walks the three tiles down.  Moving him before the box made
+  -- him cross the room in silence and deliver the speech point-blank (#869),
+  -- so the box comes first here and engageTrainer skips its own battle text.
+  -- victories.lua OPP_GIOVANNI#2 sets the event on a win; a loss sets
+  -- nothing, so the trigger re-arms exactly as vanilla does.
  onStep = function(game, ow, x, y)
    if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then return false end
    if not ((x == 6 and y == 13) or (x == 7 and y == 12)) then return false end
@@ -811,21 +824,28 @@ M.SILPH_CO_11F = {
      if npc.def and npc.def.name == "SILPHCO11F_GIOVANNI" then gio = npc break end
    end
    if not gio or ow:trainerDefeated(gio) then return false end
-    ow:scriptMove(gio, "down", 3, function()
-      gio:facePlayer(ow.player)
-      ow:engageTrainer(gio, function()
-        -- SilphCo11FGiovanniAfterBattleScript: the "Blast it all!" speech,
-        -- then SilphCo11FTeamRocketLeavesScript behind a fade so every Silph
-        -- rocket leaves off-screen (the street rockets are handled by
-        -- M.SAFFRON_CITY.onEnter in story4.lua).  Queued, not run here: the
-        -- battle's own callbacks are still unwinding, so queueScript starts
-        -- it on the first idle overworld frame -- after the end-battle
-        -- "Arrgh!!" box victories.lua OPP_GIOVANNI#2 pushes (#722).
-        if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
-          ow:queueScript(silphAftermathRows())
-        end
-      end)
-    end)
+    local TextBox = require("src.render.TextBox")
+    game.stack:push(TextBox.new(game,
+      game.data.text._SilphCo11FGiovanniText
+      or "Ah {PLAYER}!\nSo we meet again!",
+      function()
+        ow:scriptMove(gio, "down", 3, function()
+          gio:facePlayer(ow.player)
+          ow:engageTrainer(gio, function()
+            -- SilphCo11FGiovanniAfterBattleScript: the "Blast it all!"
+            -- speech, then SilphCo11FTeamRocketLeavesScript behind a fade so
+            -- every Silph rocket leaves off-screen (the street rockets are
+            -- handled by M.SAFFRON_CITY.onEnter in story4.lua).  Queued, not
+            -- run here: the battle's own callbacks are still unwinding, so
+            -- queueScript starts it on the first idle overworld frame --
+            -- after the end-battle "Arrgh!!" box victories.lua OPP_GIOVANNI#2
+            -- pushes (#722).
+            if game.save.flags.EVENT_BEAT_SILPH_CO_GIOVANNI then
+              ow:queueScript(silphAftermathRows())
+            end
+          end, nil, true)
+        end)
+      end))
    return true
  end,
  onEnter = function(game, ow)
@@ -1031,38 +1051,39 @@ local championsRoomRivalScript = {
  { "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 } },       -- 11
-  { "show_text", "_ChampionsRoomOakText" },                 -- 12
-  { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 13
-  { "move_npc", 2, "up", 5 },                               -- 14 OakEntranceAfterVictoryMovement
+  -- defeating RIVAL3), then Oak's "{PLAYER}!" + reveal + walk in.
+  -- audio/alternate_tempo.asm Music_Cities1AlternateTempo is not a plain
+  -- PlayMusic: it fades the current song out (wAudioFadeOutControl = 10),
+  -- waits 100 frames for the fade, then restarts Cities1 with channel 1
+  -- pointed at Music_Cities1_Ch1_AlternateTempo -- `tempo 232` where the
+  -- normal Music_Cities1_Ch1 opens `tempo 144`, i.e. the slower, heavier
+  -- reading of the town theme this scene is known for (#847).
+  { "fade_music", 10 },                                     -- 11
+  { "wait", 100 },                                          -- 12
+  { "play_music", "Music_Cities1", { keep = true, tempo = 232 } }, -- 13
+  { "show_text", "_ChampionsRoomOakText" },                 -- 14
+  { "show_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 15
+  { "move_npc", 2, "up", 5 },                               -- 16 OakEntranceAfterVictoryMovement
  -- OakCongratulatesPlayerScript: rival faces left, Oak faces down
-  { "face_object", 1, "left" },                             -- 15
-  { "face_object", 2, "down" },                             -- 16
-  { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 17
+  { "face_object", 1, "left" },                             -- 17
+  { "face_object", 2, "down" },                             -- 18
+  { "load_player_starter_name" },
+  { "show_text", "_ChampionsRoomOakCongratulatesPlayerText" }, -- 19
  -- OakDisappointedWithRivalScript: Oak turns to the rival (right)
-  { "face_object", 2, "right" },                            -- 18
-  { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 19
+  { "face_object", 2, "right" },                            -- 20
+  { "show_text", "_ChampionsRoomOakDisappointedWithRivalText" }, -- 21
  -- OakComeWithMeScript: Oak faces down again, then exits up
-  { "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
+  { "face_object", 2, "down" },                             -- 22
+  { "show_text", "_ChampionsRoomOakComeWithMeText" },       -- 23
+  { "move_npc", 2, "up", 2 },                               -- 24 OakExitChampionsRoomMovement
+  { "hide_object", "CHAMPIONS_ROOM", "CHAMPIONSROOM_OAK" },  -- 25
+  -- scripts/ChampionsRoom.asm WalkToHallOfFame_RLEMovement
+  { "move_player", "left", 1 },
+  { "move_player", "up", 3 },                               -- 27
  -- 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 },               -- 25
-  { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 26
+  { "set_field", "pendingHallOfFame", true },               -- 28
+  { "warp", "HALL_OF_FAME", 4, 7, "up" },                   -- 29
 }

 M.CHAMPIONS_ROOM = {
@@ -1222,6 +1243,7 @@ local function pokemonTower2FRivalScript(playerX)
    { "jump_if_false", "end" },                                   -- 6 loss: stay
    { "set_flag", "EVENT_BEAT_POKEMON_TOWER_RIVAL" },             -- 7
    { "show_text", "_PokemonTower2FRivalDefeatedText" },          -- 8
+    { "play_music", "Music_MeetRival", { start = "rival" } },
    { "walk_npc", 1, exitDirs },                                  -- 9
    { "hide_object", "POKEMON_TOWER_2F", "POKEMONTOWER2F_RIVAL" }, -- 10
    { "jump", "end" },                                            -- 11
@@ -87,6 +87,18 @@ end
 M.PALLET_TOWN = {
  talk = require("data.scripts.pallet_town").talk,
  escort = escort,
+  -- scripts/PalletTown.asm:133-144
+  onEnter = function(game, ow)
+    local f = game.save.flags
+    if f.EVENT_GOT_TOWN_MAP and f.EVENT_ENTERED_BLUES_HOUSE
+       and not f.EVENT_DAISY_WALKING then
+      f.EVENT_DAISY_WALKING = true
+      local Commands = require("src.script.Commands")
+      local ctx = { save = game.save, game = game, overworld = ow }
+      Commands.hide_object(ctx, "BLUES_HOUSE", "BLUESHOUSE_DAISY1")
+      Commands.show_object(ctx, "BLUES_HOUSE", "BLUESHOUSE_DAISY2")
+    end
+  end,
  -- Red: stop at y==1 from (8,5).  Yellow: stop at y==0 from (10,4),
  -- then a wild Pikachu battle before the lab escort (pokeyellow
  -- PalletTownPikachuBattleScript).
@@ -178,7 +190,8 @@ M.PALLET_TOWN = {
      end
    end

-    local function enterLab()
+    local function enterLab(oak)
+      if oak then oak.stepFrames = nil end
      Commands.hide_object(ctx, "PALLET_TOWN", "PALLETTOWN_OAK")
      Commands.show_object(ctx, "OAKS_LAB", "OAKSLAB_OAK2")
      ow.doorWarp = true
@@ -187,12 +200,17 @@ M.PALLET_TOWN = {
    end

    local function walkToLab(oak)
+      -- lockstep half runs Oak on the player's own frames per cell
+      -- engine/overworld/movement.asm:737 (DoScriptedNPCMovement)
      local i = 0
+      if oak then
+        oak.stepFrames = ow.player.stepFramesCur or ow.player.stepFrames
+      end
      local function tick()
        i = i + 1
        local playerStep = escort.playerSteps[i]
        if not playerStep then
-          enterLab()
+          enterLab(oak)
          return
        end
        if oak and escort.oakSteps[i] then
@@ -206,6 +224,13 @@ M.PALLET_TOWN = {
    end

    local function escortToLab(oak)
+      -- PalletMovementScript_OakMoveLeft
+      -- (engine/overworld/auto_movement.asm) starts MUSIC_MUSEUM_GUY
+      -- when the escort begins in Yellow. Until then, Pallet Town plays
+      -- after the battle; Red/Blue leave MUSIC_MEET_PROF_OAK playing.
+      if yellow then
+        Music.play(game.data, "Music_MuseumGuy")
+      end
      local numSteps = x - 10
      if oak and numSteps > 0 then
        ow:scriptMove(oak, "left", numSteps, function()
@@ -249,14 +274,24 @@ M.PALLET_TOWN = {
        function()
          -- Oak turns toward the horizontally adjacent grass (left exit
          -- looks right, right exit looks left -- the
-          -- EVENT_PLAYER_AT_RIGHT_EXIT_TO_PALLET_TOWN branch)
+          -- EVENT_PLAYER_AT_RIGHT_EXIT_TO_PALLET_TOWN branch).
+          -- In pokeyellow, PalletTownOakGreetsPlayerScript turns Oak and
+          -- PalletTownPikachuBattleScript arms the battle on the next
+          -- overworld iteration. OverworldLoopLessDelay
+          -- (home/overworld.asm) burns two DelayFrame calls at the top
+          -- of each iteration and calls RunMapScript before checking
+          -- wCurOpponent, so those two DelayFrame calls are what keep
+          -- Oak's turn on screen before the battle check fires.
          if oak then oak.facing = x == 10 and "right" or "left" end
-          local battle = BattleState.newWild(game, "PIKACHU", 5)
-          battle:makeOldManDemo("PROF.OAK")
-          battle.onFinish = function()
-            afterPikaBattle()
-          end
-          game.stack:push(battle)
+          hold(2, nil, function()
+            local battle = BattleState.newWild(game, "PIKACHU", 5)
+            battle:makeOldManDemo("PROF.OAK")
+            battle.onFinish = function()
+              afterPikaBattle()
+            end
+            -- Use the standard wild-battle entry transition.
+            Commands.pushBattle(ctx, battle)
+          end)
        end))
    end

@@ -396,19 +431,31 @@ M.ROUTE_8_GATE = saffronGate("TEXT_ROUTE8GATE_GUARD", { { 2, 3 }, { 2, 4 } }, tr
 -- -------------------------------------------------------------------

 M.POKEMON_FAN_CLUB = {
+  onEnter = function(game, ow)
+    require("src.world.PikachuFollower").onFanClubEntered(game, ow)
+  end,
  talk = {
    TEXT_POKEMONFANCLUB_CHAIRMAN = {
      { "face_player" },                                          -- 1
      { "check_flag", "EVENT_RECEIVED_BIKE_VOUCHER" },            -- 2
-      { "jump_if_true", 9 },                                      -- 3
-      { "show_text", "_PokemonFanClubChairmanIntroText" },        -- 4
-      { "show_text", "_PokemonFanClubChairmanStoryText" },        -- 5
+      { "jump_if_true", "nothing_left" },                         -- 3
+      -- YesNoChoice (scripts/PokemonFanClub.asm): NO forfeits the voucher (#1050)
+      { "ask", "_PokemonFanClubChairmanIntroText" },              -- 4
+      { "jump_if_false", "no_story" },                            -- 5
+      { "show_text", "_PokemonFanClubChairmanStoryText" },        -- 6
      -- give-then-print like scripts/PokemonFanClub.asm (GiveItem
      -- fills wStringBuffer; the received text reads it)
-      { "give_item", "BIKE_VOUCHER", 1, false },                  -- 6
-      { "show_text", "_PokemonFanClubReceivedBikeVoucherText" },  -- 7
-      { "set_flag", "EVENT_RECEIVED_BIKE_VOUCHER" },              -- 8
-      { "show_text", "_PokemonFanClubExplainBikeVoucherText" },   -- 9
+      { "give_item", "BIKE_VOUCHER", 1, false },                  -- 7
+      { "show_text", "_PokemonFanClubReceivedBikeVoucherText" },  -- 8
+      { "set_flag", "EVENT_RECEIVED_BIKE_VOUCHER" },              -- 9
+      { "show_text", "_PokemonFanClubExplainBikeVoucherText" },   -- 10
+      { "jump", "end" },                                          -- 11
+      { "label", "no_story" },                                    -- 12
+      { "show_text", "_PokemonFanClubNoStoryText" },              -- 13
+      { "jump", "end" },                                          -- 14
+      -- .nothingleft: the gift is done, he only reminisces now
+      { "label", "nothing_left" },                                -- 15
+      { "show_text", "_PokemonFanClubChairFinalText" },           -- 16
    },
  },
 }
@@ -619,8 +666,10 @@ local function mtMoonFossil(itemId, otherName, gotFlag)
      end
      local idef = game.data.items[itemId]
      game.stringBuffer = idef and idef.name or itemId
-      require("src.core.Sound").play(game.data, "Get_Key_Item")
      local dirs = mtMoonNerdWalk(ow.player.cellX, ow.player.cellY, itemId)
+      -- MtMoonB2FReceivedFossilText: text_far, sound_get_key_item,
+      -- text_waitbutton -- the jingle plays after the box has typed and
+      -- the button wait comes after it
      game.stack:push(TextBox.new(game,
        t._MtMoonB2FReceivedFossilText
          or ("{PLAYER} got the\n" .. game.stringBuffer .. "!"),
@@ -633,11 +682,11 @@ local function mtMoonFossil(itemId, otherName, gotFlag)
          ow.runner:run({
            { "walk_npc", 1, dirs },
            { "text_opts", { auto = true } },
+            { "text_sound", "Get_Key_Item" },
            { "show_text", "_MtMoonB2FSuperNerdThenThisIsMineText" },
-            { "play_sound", "Get_Key_Item" },
            { "hide_object", "MT_MOON_B2F", otherName },
          }, { onDone = done })
-        end))
+        end, TextBox.soundOpts(game, "Get_Key_Item")))
    end }))
  end
 end
@@ -660,35 +709,37 @@ M.MT_MOON_B2F = {
  },
 }

-- The ticket clerk (scripts/Museum1F.asm Museum1FScientist1Text):
-- Y50, once.  Declining at the rope shoves the player one tile SOUTH back off
-- the exhibit rope they crossed heading north (#151); the museum floor has no
-- ledges, so a plain scriptMove("down",1) is the correct primitive.
+-- The ticket clerk (scripts/Museum1F.asm Museum1FScientist1Text): Y50, once.
+-- Declining at the rope shoves the player one tile south (#151)
 local function museumClerk(game, ow, done, onDecline)
  local TextBox = require("src.render.TextBox")
-  local ChoiceBox = require("src.ui.ChoiceBox")
+  local t = game.data.text or {}
  if game.save.flags.EVENT_BOUGHT_MUSEUM_TICKET then
    game.stack:push(TextBox.new(game,
      "Take your time,\nand enjoy it all!", done))
    return
  end
+  -- scripts/Museum1F.asm:72
+  local money = function() return game.save.money end
  game.stack:push(TextBox.new(game,
-    "It's ¥50 for a\nchild's ticket.\fWould you like to\ncome in?", function()
-    game.stack:push(ChoiceBox.new(game, function(yes)
+    t._Museum1FScientist1WouldYouLikeToComeInText
+      or "It's ¥50 for a\nchild's ticket.\fWould you like to\ncome in?",
+    nil, { money = money, choice = function(yes)
      if yes and game.save.money >= 50 then
        game.save.money = game.save.money - 50
        game.save.flags.EVENT_BOUGHT_MUSEUM_TICKET = true
+        -- scripts/Museum1F.asm:106
        game.stack:push(TextBox.new(game,
-          "Right, ¥50!\nThank you!", done))
+          t._Museum1FScientist1ThankYouText or "Right, ¥50!\nThank you!", done,
+          { money = money }))
      elseif yes then
        game.stack:push(TextBox.new(game,
-          "You don't have\nenough money.", onDecline or done))
+          "You don't have\nenough money.", onDecline or done, { money = money }))
      else
        game.stack:push(TextBox.new(game,
-          "Come again!", onDecline or done))
+          "Come again!", onDecline or done, { money = money }))
      end
-    end))
-  end))
+    end }))
 end

 M.MUSEUM_1F = {
@@ -151,9 +151,27 @@ M.POKEMON_TOWER_6F = {
        -- trick, and the speedrun route this bot follows depends on it.
        if result == "win" or battle.pokeDollEscape then
          game.save.flags.EVENT_BEAT_GHOST_MAROWAK = true
-          game.stack:push(TextBox.new(game,
-            t._PokemonTower6FSoulWasCalmedText
-            or "The mother's soul\nwas calmed.\012It departed to\nthe afterlife!"))
+          -- PokemonTower6FMarowakDepartedText (scripts/PokemonTower6F.asm)
+          -- is two texts, not one: the CUBONE's-mother line first, then
+          -- PlayCry RESTLESS_SOUL (EQU MAROWAK, constants/pokemon_constants
+          -- .asm:209) + WaitForSoundToFinish + DelayFrames 30 before the
+          -- calmed line; the port dropped the first text and the cry
+          -- (#867).  play_cry arms the next show_text, so the cry rides
+          -- the calmed box's open with the button prompt kept, and the
+          -- wait row stands in for the asm's 30-frame gap.
+          local rows = {
+            { "show_text", t._PokemonTower6FGhostWasCubonesMotherText
+              or "The GHOST was the\nrestless soul of\vCUBONE's mother!" },
+            { "play_cry", "MAROWAK", true },
+            { "wait", 30 },
+            { "show_text", t._PokemonTower6FSoulWasCalmedText
+              or "The mother's soul\nwas calmed.\012It departed to\nthe afterlife!" },
+          }
+          if ow.runner then
+            ow.runner:run(rows)
+          elseif ow.queueScript then
+            ow:queueScript(rows)
+          end
        elseif result ~= "lose" then
          -- .did_not_defeat: one simulated step right, off the trigger,
          -- so fleeing does not leave you standing on a cell that
@@ -517,6 +535,14 @@ M.GAME_CORNER = {
        done()
        return
      end
+      -- GameCornerRocketText hands the battle its own loss line through
+      -- SaveEndBattleTextPointers (.BattleEndText ->
+      -- _GameCornerRocketBattleEndText, "Dang!"), and PrintEndBattleText
+      -- prints it ON the battle screen between TrainerDefeatedText and
+      -- MoneyForWinningText (engine/battle/core.asm TrainerBattleVictory).
+      -- He is a text_asm trainer with no def_trainers header, so there is no
+      -- header.won for engageTrainer to find and the line has to be handed
+      -- over here or it never shows at all (#862).
      ow:engageTrainer(npc, function()
        if not ow:trainerDefeated(npc) then
          done()
@@ -527,19 +553,44 @@ M.GAME_CORNER = {
          game.data.text._GameCornerRocketAfterBattleText
          or "Our hideout might\nbe discovered! I\nbetter tell BOSS!",
          function()
-            -- #198: GameCornerRocketExitScript (scripts/GameCorner.asm)
-            -- ApplyMovementData walks the grunt one tile UP into the poster
-            -- (the hideout's secret entrance at 9,4) before HideObject, so
-            -- he leaves the floor rather than popping out of existence on
-            -- (9,5).  scriptMove locks player input (#scriptMoves>0) and
-            -- ignores collision, so we despawn + unfreeze (done) only once
-            -- the step lands.
-            ow:scriptMove(npc, "up", 1, function()
-              hideRocket()
-              done()
-            end)
+            -- #198/#862: GameCornerRocketBattleScript (scripts/GameCorner.asm)
+            -- picks the exit walk from where the player is standing, because
+            -- the grunt on (9,5) has to get past him: wYCoord == 6 (talked to
+            -- from the south) or wXCoord == 8 (from the west) leaves the row
+            -- clear and takes GameCornerMovement_Rocket_WalkDirect, five steps
+            -- RIGHT; otherwise the player is east of him on (10,5) and
+            -- GameCornerMovement_Rocket_WalkAroundPlayer steps DOWN, right, UP
+            -- and right again to go AROUND him.  pokeyellow's copy of the
+            -- around-path takes one extra RIGHT on the lower row before coming
+            -- back up (it also has to clear Pikachu); both versions end on
+            -- (15,5).  He never steps UP: (9,4) is the poster wall, which is
+            -- where the old single UP step sent him.
+            local px = ow.player and ow.player.cellX
+            local py = ow.player and ow.player.cellY
+            local path
+            if py == 6 or px == 8 then
+              path = { { "right", 5 } }
+            elseif require("src.core.GameVersion").isYellow() then
+              path = { { "down", 1 }, { "right", 3 }, { "up", 1 }, { "right", 3 } }
+            else
+              path = { { "down", 1 }, { "right", 2 }, { "up", 1 }, { "right", 4 } }
+            end
+            -- GameCornerRocketExitScript only HideObjects him once
+            -- BIT_SCRIPTED_NPC_MOVEMENT clears, i.e. after the last step.
+            -- scriptMove locks player input (#scriptMoves>0) and ignores
+            -- collision, so the despawn + unfreeze (done) ride the final step.
+            local function step(i)
+              if i > #path then
+                hideRocket()
+                done()
+                return
+              end
+              ow:scriptMove(npc, path[i][1], path[i][2],
+                            function() step(i + 1) end)
+            end
+            step(1)
          end))
-      end)
+      end, game.data.text._GameCornerRocketBattleEndText or "Dang!")
    end,
    -- GameCornerClerk1Text (scripts/GameCorner.asm): the offer, a
    -- YesNoChoice, then ¥1000 for 50 coins.  Yellow drops the "1" from the
@@ -886,15 +937,10 @@ M.VERMILION_DOCK = {
        ow:startDustAnim(cx, 1, function() puff(n - 1, cx + 2) end)
      end
      puff(3, 15)
-      -- VermilionDock_EraseSSAnne deliberately leaves the blocks under the
-      -- player alone ("south of the player and won't be redrawn"), so skip
-      -- his own block: he must not spend the walk-out standing on water
-      local pbx = math.floor(ow.player.cellX / 2)
-      local pby = math.floor(ow.player.cellY / 2)
+      -- scripts/VermilionDock.asm:182-203
      local rows = {}
      local function setBlock(bx, by, block)
        if bx < 1 or bx > 8 then return end
-        if bx == pbx and by == pby then return end
        rows[#rows + 1] = { "replace_block", bx, by, block }
      end
      rows[#rows + 1] = { "wait", 120 }
@@ -8,21 +8,35 @@ local M = {}

 local function text(game) return game.data.text end

-local function push(game, s, done)
+local function push(game, s, done, opts)
  local TextBox = require("src.render.TextBox")
-  game.stack:push(TextBox.new(game, s, done))
+  game.stack:push(TextBox.new(game, s, done, opts))
 end

+-- The question stays on screen under the YES/NO menu.  The dojo prize
+-- balls are the clearest case: FightingDojoHitmonleePokeBallText
+-- (scripts/FightingDojo.asm) is `call PrintText` on a text_end string --
+-- no prompt, so no WaitForTextScrollButtonPress -- immediately followed
+-- by `call YesNoChoice`, and InitYesNoTextBoxParameters
+-- (engine/menus/text_box.asm) puts the menu above the dialogue box
+-- rather than replacing it.  Ride TextBox's opts.choice, the same as
+-- Commands.ask, instead of popping the box with an A press and leaving a
+-- bare ChoiceBox over the overworld (#854).
 local function ask(game, s, cb)
-  local ChoiceBox = require("src.ui.ChoiceBox")
-  push(game, s, function() game.stack:push(ChoiceBox.new(game, cb)) end)
+  local TextBox = require("src.render.TextBox")
+  game.stack:push(TextBox.new(game, s, nil, { choice = cb }))
 end

-- fill the extracted text placeholders ({NUM:...}, {RAM:...}, {PLAYER})
+-- fill text placeholders; key on the hram/wram symbol first, since one
+-- string can carry two different NUM slots (#1006)
 local function fill(s, subs)
  s = s:gsub("{PLAYER}", subs.player or "")
-  s = s:gsub("{NUM:[^}]*}", function() return tostring(subs.num or "") end)
-  s = s:gsub("{RAM:[^}]*}", function() return subs.ram or "" end)
+  s = s:gsub("{NUM:([%w_]*)[^}]*}", function(name)
+    return tostring(subs[name] or subs.num or "")
+  end)
+  s = s:gsub("{RAM:([%w_]*)[^}]*}", function(name)
+    return subs[name] or subs.ram or ""
+  end)
  return s
 end

@@ -73,9 +87,12 @@ local function oaksAide(threshold, itemId, repeatText)
                { ram = itemName, player = game.save.player.name }), done)
            end)
        else
+          -- .notEnoughOwnedMons prints owned then requirement, two counts
          push(game, fill(t._OaksAideUhOhText or
            "You have only\ncaught {NUM:}!",
-            { num = owned, ram = itemName }), done)
+            { num = owned, ram = itemName,
+              hOaksAideNumMonsOwned = owned,
+              hOaksAideRequirement = threshold }), done)
        end
      end)
  end
@@ -125,7 +142,7 @@ M.MT_MOON_POKECENTER = {
        local Commands = require("src.script.Commands")
        Commands.give_pokemon({ save = game.save, game = game, overworld = ow },
                              "MAGIKARP", 5)
-        push(game, ("%s got a\nMAGIKARP!"):format(game.save.player.name), done)
+        push(game, t._GotMonText or "{PLAYER} got\n{RAM:wNameBuffer}!", done)
      end)
    end,
  },
@@ -155,19 +172,26 @@ local function dojoBall(species, ownBall, otherBall, askKey)
      push(game, "You'll have to\nbeat the master\nfirst!", done)
      return
    end
-    ask(game, t[askKey] or ("You want\n" .. species .. "?"), function(yes)
-      if not yes then done() return end
-      flags["EVENT_GOT_" .. species] = true
-      flags.EVENT_DEFEATED_FIGHTING_DOJO = true
-      local Commands = require("src.script.Commands")
-      local ctx = { save = game.save, game = game, overworld = ow }
-      Commands.give_pokemon(ctx, species, 30)
-      -- Hide ONLY the chosen ball; the other stays (FightingDojo.asm hides
-      -- just the picked object's index) and routes to the greedy line above
-      -- when talked to (#197).
-      Commands.hide_object(ctx, "FIGHTING_DOJO", ownBall)
-      push(game, ("%s got\n%s!"):format(game.save.player.name, species), done)
-    end)
+    -- Examining a ball shows that species' POKéDEX entry first
+    -- (DisplayPokedex in FightingDojo.asm, which also marks it seen),
+    -- then the yes/no take-it prompt (#853).
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.mark_seen(ctx, species)
+    local DexEntryMenu = require("src.ui.DexEntryMenu")
+    game.stack:push(DexEntryMenu.new(game, species, function()
+      ask(game, t[askKey] or ("You want\n" .. species .. "?"), function(yes)
+        if not yes then done() return end
+        flags["EVENT_GOT_" .. species] = true
+        flags.EVENT_DEFEATED_FIGHTING_DOJO = true
+        Commands.give_pokemon(ctx, species, 30)
+        -- Hide ONLY the chosen ball; the other stays (FightingDojo.asm hides
+        -- just the picked object's index) and routes to the greedy line above
+        -- when talked to (#197).
+        Commands.hide_object(ctx, "FIGHTING_DOJO", ownBall)
+        push(game, ("%s got\n%s!"):format(game.save.player.name, species), done)
+      end)
+    end))
  end
 end

@@ -229,27 +253,32 @@ M.FIGHTING_DOJO = {

 M.SILPH_CO_7F = {
  talk = {
-    TEXT_SILPHCO7F_SILPH_WORKER_M1 = function(game, ow, npc, done)
-      local t = text(game)
-      if game.save.flags.EVENT_GOT_LAPRAS then
-        push(game, t._SilphCo7FSilphWorkerM1LaprasDescriptionText
-          or "How is LAPRAS\ndoing?", done)
-        return
-      end
-      push(game, t._SilphCo7FSilphWorkerM1ThankYouText
-        or "Thank you for\nsaving us!\fI want you to\nhave this LAPRAS!",
-        function()
-          game.save.flags.EVENT_GOT_LAPRAS = true
-          local Commands = require("src.script.Commands")
-          Commands.give_pokemon({ save = game.save, game = game, overworld = ow },
-                                "LAPRAS", 15)
-          push(game, ("%s got\nLAPRAS!"):format(game.save.player.name),
-            function()
-              push(game, t._SilphCo7FSilphWorkerM1LaprasDescriptionText
-                or "It's a good\nswimmer!", done)
-            end)
-        end)
-    end,
+    -- command rows, not a Lua handler: give_pokemon needs a runner to AskName (#1049)
+    TEXT_SILPHCO7F_SILPH_WORKER_M1 = {
+      { "face_player" },
+      { "check_flag", "EVENT_GOT_LAPRAS" },
+      { "jump_if_true", "has_lapras" },
+      { "show_text", "_SilphCo7FSilphWorkerM1HaveThisPokemonText" },
+      { "give_pokemon", "LAPRAS", 15 },
+      { "jump_if_false", "box_full" },
+      -- flag ahead of the jingle, like the Celadon EEVEE (#426)
+      { "set_flag", "EVENT_GOT_LAPRAS" },
+      { "text_sound", "Get_Item1" },
+      { "show_text", "_GotMonText", { RAM = "LAPRAS" } },
+      { "show_text", "_SilphCo7FSilphWorkerM1LaprasDescriptionText" },
+      { "jump", "end" },
+      { "label", "box_full" },
+      { "show_text", "_BoxIsFullText" },
+      { "jump", "end" },
+      -- SilphCo7F.asm .saved_silph gates the thanks on Giovanni
+      { "label", "has_lapras" },
+      { "check_flag", "EVENT_BEAT_SILPH_CO_GIOVANNI" },
+      { "jump_if_true", "saved" },
+      { "show_text", "_SilphCo7FSilphWorkerM1IsOurPresidentOkText" },
+      { "jump", "end" },
+      { "label", "saved" },
+      { "show_text", "_SilphCo7FSilphWorkerM1SavedText" },
+    },
  },
 }

@@ -278,12 +307,11 @@ M.COPYCATS_HOUSE_2F = {
            return
          end
          game.stringBuffer = game.data.items.TM_MIMIC.name
-          require("src.core.Sound").play(game.data, "Get_Item1")
          Bag.remove(game.save, "POKE_DOLL", 1)
          game.save.flags.EVENT_GOT_TM31 = true
          push(game, t._CopycatsHouse2FCopycatReceivedTM31Text, function()
            push(game, t._CopycatsHouse2FCopycatTM31Explanation1Text, done)
-          end)
+          end, require("src.render.TextBox").soundOpts(game, "Get_Item1"))
        end)
      end)
    end,
@@ -449,7 +477,6 @@ M.CELADON_MART_ROOF = {
                    return
                  end
                  game.save.flags[g.flag] = true
-                  require("src.core.Sound").play(game.data, "Get_Item1")
                  local subs = { player = game.save.player.name,
                                 ram = game.data.items[g.tm].name }
                  local explain = fill(t[g.explain] or "", subs)
@@ -461,7 +488,7 @@ M.CELADON_MART_ROOF = {
                    else
                      done()
                    end
-                  end)
+                  end, require("src.render.TextBox").soundOpts(game, "Get_Item1"))
                end)
              end,
              onCancel = done,
@@ -483,25 +510,28 @@ M.ROUTE_24 = {
      local flags = game.save.flags
      local function battleOrDone()
        if ow:trainerDefeated(npc) then
-          push(game, "I hate this!\nMy dreams of\nTEAM ROCKET...", done)
+          push(game, text(game)._Route24CooltrainerM1YouCouldBecomeATopLeaderText,
+            done)
        else
          ow:engageTrainer(npc, done)
        end
      end
      if not flags.EVENT_GOT_NUGGET then
-        push(game, "Congratulations!\nYou beat our 5\ncontest trainers!\f"
-          .. "You just earned a\nfabulous prize!", function()
+        local t = text(game)
+        push(game, t._Route24CooltrainerM1YouBeatOurContestText .. "\f"
+          .. t._Route24CooltrainerM1YouJustEarnedAPrizeText, function()
+          if not require("src.inventory.Bag").add(game.save, "NUGGET", 1,
+              game.data) then
+            push(game, t._Route24CooltrainerM1NoRoomText, done)
+            return
+          end
          flags.EVENT_GOT_NUGGET = true
-          require("src.inventory.Bag").add(game.save, "NUGGET", 1)
-          push(game, ("%s received\na NUGGET!"):format(game.save.player.name),
-            function()
-              ask(game, "By the way, would\nyou like to join\nTEAM ROCKET?",
-                function()
-                  push(game, "Arrgh! You are\nnot convinced?\fThen I'll show\n"
-                    .. "you my power!", battleOrDone)
-                end)
-            end)
-        end)
+          game.stringBuffer = game.data.items.NUGGET.name
+          push(game, t._Route24CooltrainerM1ReceivedNuggetText, function()
+            push(game, t._Route24CooltrainerM1JoinTeamRocketText,
+              battleOrDone)
+          end, require("src.render.TextBox").soundOpts(game, "Get_Item1"))
+        end, require("src.render.TextBox").soundOpts(game, "Get_Item1"))
        return
      end
      battleOrDone()
@@ -4,9 +4,9 @@ local M = {}

 local function text(game) return game.data.text end

-local function push(game, s, done)
+local function push(game, s, done, opts)
  local TextBox = require("src.render.TextBox")
-  game.stack:push(TextBox.new(game, s, done))
+  game.stack:push(TextBox.new(game, s, done, opts))
 end

 -- fill the extracted text placeholders ({RAM:...}, {PLAYER})
@@ -25,8 +25,8 @@ local function gift(opts)
    local t = text(game)
    local itemName = game.data.items[opts.item].name
    local subs = { ram = itemName, player = game.save.player.name }
-    local function say(label, fallback, cb)
-      push(game, fill(t[label] or fallback, subs), cb)
+    local function say(label, fallback, cb, sopts)
+      push(game, fill(t[label] or fallback, subs), cb, sopts)
    end
    if game.save.flags[opts.flag] then
      say(opts.already or opts.explain, "It's a useful\nitem, isn't it?", done)
@@ -39,15 +39,16 @@ local function gift(opts)
      end
      game.save.flags[opts.flag] = true
      local idef = game.data.items[opts.item]
-      require("src.core.Sound").play(game.data,
-        (idef and idef.keyItem) and "Get_Key_Item" or "Get_Item1")
+      -- the received texts carry sound_get_item_1 / sound_get_key_item, so
+      -- the jingle only fires once that box has typed out
      say(opts.received, "{PLAYER} received\n{RAM:}!", function()
        if opts.explain then
          say(opts.explain, "", done)
        else
          done()
        end
-      end)
+      end, require("src.render.TextBox").soundOpts(game,
+        (idef and idef.keyItem) and "Get_Key_Item" or "Get_Item1"))
    end
    if opts.pre then say(opts.pre, opts.preFallback or "", give) else give() end
  end
@@ -445,7 +446,7 @@ local function pewterGymEscort(game, ow)
  end

  local function afterWalk()
-    if guy then guy.facing = "left" end
+    if guy then guy.stepFrames, guy.facing = nil, "left" end
    Music.playMap(game.data, "PEWTER_CITY")
    push(game, t._PewterCityYoungsterGoTakeOnBrockText
      or "Go take on BROCK\nat the GYM first!", walkHome)
@@ -468,6 +469,11 @@ local function pewterGymEscort(game, ow)
  end

  local function beginWalk()
+    -- the escort runs the youngster on the player's own frames per cell
+    -- engine/overworld/movement.asm:737 (DoScriptedNPCMovement)
+    if guy then
+      guy.stepFrames = ow.player.stepFramesCur or ow.player.stepFrames
+    end
    Music.play(game.data, "Music_MuseumGuy")
    if guy and head > 0 then
      local h = 0
@@ -508,12 +514,12 @@ M.PEWTER_CITY = {
 -- Rival ambush: show the hidden rival, walk him up to the player, run
 -- the battle rows, march him back and hide him.  On a loss the walk is
 -- skipped (the blackout rebuilds the map mid-script).
-local function runAmbush(game, ow, rows, playerFacing)
+local function runAmbush(game, ow, rows, playerFacing, musicOpts)
  if ow.runner:isRunning() then return false end
  ow.player.facing = playerFacing
  -- the rival encounter sting (MUSIC_MEET_RIVAL); the battle music
  -- takes over and the map theme returns after the victory jingle
-  require("src.core.Music").play(game.data, "Music_MeetRival")
+  require("src.core.Music").play(game.data, "Music_MeetRival", nil, musicOpts)
  ow.runner:run(rows)
  return true
 end
@@ -567,12 +573,15 @@ local function route22Scene(n, objIndex, objName, oppClass, baseParty, beatFlag,
    { "face_object", objIndex, rivalFacing },                  -- 3
    { "show_text", "_Route22RivalBeforeBattleText" .. n },     -- 4
    { "rival_battle", oppClass, baseParty },                   -- 5
-    { "jump_if_false", 11 },                                   -- 6
+    { "jump_if_false", 13 },                                   -- 6
    { "set_flag", beatFlag },                                  -- 7
    { "show_text", "_Route22Rival" .. n .. "DefeatedText" },   -- 8
    { "show_text", "_Route22RivalAfterBattleText" .. n },      -- 9
-    { "walk_npc", objIndex, route22ExitDirs(n, py) },          -- 10
-    { "hide_object", "ROUTE_22", objName },                    -- 11
+    { "play_music", "Music_MeetRival", { start = "rival",
+      tempo = n == 2 and 100 or nil } },                     -- 10
+    { "walk_npc", objIndex, route22ExitDirs(n, py) },          -- 11
+    { "play_default_music" },                    -- scripts/Route22.asm:230
+    { "hide_object", "ROUTE_22", objName },                    -- 13
  }
 end

@@ -594,7 +603,8 @@ M.ROUTE_22 = {
    if f.EVENT_BEAT_GIOVANNI and not f.EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE then
      return runAmbush(game, ow,
        route22Scene(2, 2, "ROUTE22_RIVAL2", "OPP_RIVAL2", 10,
-                     "EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE", y), playerFacing)
+                     "EVENT_BEAT_ROUTE22_RIVAL_2ND_BATTLE", y), playerFacing,
+        { tempo = 100 })
    end
    return false
  end,
@@ -618,12 +628,14 @@ local function ceruleanRivalScene(px, py)
    { "face_object", 1, "down" },                              -- 3
    { "show_text", "_CeruleanCityRivalPreBattleText" },        -- 4
    { "rival_battle", "OPP_RIVAL1", 7 },                       -- 5
-    { "jump_if_false", 11 },                                   -- 6
+    { "jump_if_false", 13 },                                   -- 6
    { "set_flag", "EVENT_BEAT_CERULEAN_RIVAL" },               -- 7
    { "show_text", "_CeruleanCityRivalDefeatedText" },         -- 8
    { "show_text", "_CeruleanCityRivalIWentToBillsText" },     -- 9
-    { "walk_npc", 1, ceruleanRivalExitDirs(px) },              -- 10
-    { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 11
+    { "play_music", "Music_MeetRival", { start = "rival" } }, -- 10
+    { "walk_npc", 1, ceruleanRivalExitDirs(px) },              -- 11
+    { "play_default_music" },                -- scripts/CeruleanCity.asm:230
+    { "hide_object", "CERULEAN_CITY", "CERULEANCITY_RIVAL" },  -- 13
  }
 end

@@ -730,7 +742,7 @@ local JIGGLYPUFF_SILENCE, JIGGLYPUFF_STEP, JIGGLYPUFF_TAIL = 32, 24, 48
 -- Built as a TextBox `auto` table: auto.sound fires the frame the last
 -- page has typed out (PrintText returning), and auto.tick then runs once
 -- per frame while the gate it returns still reads as playing.
-local function jigglypuffDance(game, npc)
+local function jigglypuffDance(game, npc, ow)
  local Music = require("src.core.Music")
  -- .findMatchingFacingDirectionLoop: the rotation picks up at the entry
  -- matching the sprite's current facing (showMapText has just turned it
@@ -776,7 +788,13 @@ local function jigglypuffDance(game, npc)
        if npc then npc.facing = JIGGLYPUFF_SPIN[step] end
        return
      end
-      if frames >= JIGGLYPUFF_TAIL then phase = "done" end
+      if frames >= JIGGLYPUFF_TAIL then
+        phase = "done"
+        if require("src.core.GameVersion").isYellow()
+            and require("src.world.PikachuFollower").starterInParty(game.save) then
+          ow.pikachuPewterSleepScene = true
+        end
+      end
    end,
  }
 end
@@ -789,7 +807,7 @@ M.PEWTER_POKECENTER = {
      local TextBox = require("src.render.TextBox")
      game.stack:push(TextBox.new(game,
        text(game)._PewterPokecenterJigglypuffText or "JIGGLYPUFF: Puu\npupuu!",
-        done, { auto = jigglypuffDance(game, npc) }))
+        done, { auto = jigglypuffDance(game, npc, ow) }))
    end,
  },
 }
@@ -864,12 +882,14 @@ M.SILPH_CO_7F = {
      { "face_object", 9, "up" },                              -- 4
      { "show_text", "_SilphCo7FRivalWaitedHereText" },        -- 5
      { "rival_battle", "OPP_RIVAL2", 7 },                     -- 6
-      { "jump_if_false", 12 },                                 -- 7
+      { "jump_if_false", 14 },                                 -- 7
      { "set_flag", "EVENT_BEAT_SILPH_CO_RIVAL" },             -- 8
      { "show_text", "_SilphCo7FRivalDefeatedText" },          -- 9
      { "show_text", "_SilphCo7FRivalGoodLuckToYouText" },     -- 10
-      { "move_npc_to", 9, 5, y + 1 },                          -- 11
-      { "hide_object", "SILPH_CO_7F", "SILPHCO7F_RIVAL" },     -- 12
+      { "play_music", "Music_MeetRival", { start = "rival" } }, -- 11
+      { "move_npc_to", 9, 5, y + 1 },                          -- 12
+      { "play_default_music" },                -- scripts/SilphCo7F.asm:261
+      { "hide_object", "SILPH_CO_7F", "SILPHCO7F_RIVAL" },     -- 14
    }, "down")
  end,
 }
@@ -899,12 +919,14 @@ M.SS_ANNE_2F = {
      { "face_object", 2, onLeft and "down" or "right" },      -- 3
      { "show_text", "_SSAnne2FRivalText" },                   -- 4
      { "rival_battle", "OPP_RIVAL2", 1 },                     -- 5
-      { "jump_if_false", 11 },                                 -- 6
+      { "jump_if_false", 13 },                                 -- 6
      { "set_flag", "EVENT_BEAT_SS_ANNE_RIVAL" },              -- 7
      { "show_text", "_SSAnne2FRivalDefeatedText" },           -- 8
      { "show_text", "_SSAnne2FRivalCutMasterText" },          -- 9
-      { "walk_npc", 2, ssAnne2FRivalExitDirs(onLeft) },        -- 10
-      { "hide_object", "SS_ANNE_2F", "SSANNE2F_RIVAL" },       -- 11
+      { "play_music", "Music_MeetRival", { start = "rival" } }, -- 10
+      { "walk_npc", 2, ssAnne2FRivalExitDirs(onLeft) },        -- 11
+      { "play_default_music" },                 -- scripts/SSAnne2F.asm:175
+      { "hide_object", "SS_ANNE_2F", "SSANNE2F_RIVAL" },       -- 13
    }, onLeft and "up" or "left")
  end,
 }
@@ -12,9 +12,13 @@ local function push(game, s, done)
  game.stack:push(TextBox.new(game, s, done))
 end

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

 -- -------------------------------------------------------------------
@@ -18,6 +18,24 @@
 -- script).  Leaders are not def_trainers entries, so engageTrainer has
 -- no header.won -- checkVictoryRewards shows this chain instead of a
 -- synthetic "received badge/TM" stub.
+--
+-- Gym entries split the TM hand-over out of `dialogue`, mirroring the
+-- originals' GiveItem check (`call GiveItem` / `jr nc, .BagFull`):
+-- `tmPre` is the ReceiveTM script's lead-in (badge info / "Wait! Take
+-- this!"), shown at the victory and again when a beaten leader retries
+-- the hand-over; `tmDialogue` shows only when the TM actually goes in
+-- the bag; `noRoom` is the "make room" line shown instead when the bag
+-- is full; `gotFlag` (pokered's EVENT_GOT_TM*) is set only on a
+-- successful give, which is what makes the leader's talk script retry
+-- later (gyms.lua).
+--
+-- `badgeSound` / `tmSound` are the text sound command each gym's reward
+-- text carries right after its FIRST label -- home/text.asm TextCommand_SOUND
+-- plays it once that page has typed out and then blocks on
+-- WaitForSoundToFinish, so the jingle sits between the pages rather than
+-- under them.  macros/scripts/text.asm defines sound_level_up as
+-- sound_get_item_1, so Pewter's and Viridian's badge lines are Get_Item1
+-- too.  Vermilion, Celadon and Fuchsia carry no sound on the badge text.

 local function range(prefix, first, last)
  local t = {}
@@ -33,77 +51,122 @@ return {
  -- escort NPC and the first Route 22 rival stay gone after the badge.
  ["OPP_BROCK#1"] = { badge = "BOULDERBADGE", flag = "EVENT_BEAT_BROCK",
                      item = "TM_BIDE",
+                      gotFlag = "EVENT_GOT_TM34",
+                      noRoom = "_PewterGymTM34NoRoomText",
                      deactivate = { "EVENT_BEAT_PEWTER_GYM_TRAINER_0" },
                      hide = {
                        { "PEWTER_CITY", "PEWTERCITY_YOUNGSTER" },
                        { "ROUTE_22", "ROUTE22_RIVAL1" },
                      },
+                      badgeSound = "Get_Item1", -- sound_level_up
+                      tmSound = "Get_Item1",
                      dialogue = {
                        "_PewterGymBrockReceivedBoulderBadgeText",
                        "_PewterGymBrockBoulderBadgeInfoText",
-                        "_PewterGymBrockWaitTakeThisText",
+                      },
+                      tmPre = { "_PewterGymBrockWaitTakeThisText" },
+                      tmDialogue = {
                        "_PewterGymReceivedTM34Text",
                        "_TM34ExplanationText",
                      } },
  ["OPP_MISTY#1"] = { badge = "CASCADEBADGE", flag = "EVENT_BEAT_MISTY",
                      item = "TM_BUBBLEBEAM",
+                      gotFlag = "EVENT_GOT_TM11",
+                      noRoom = "_CeruleanGymMistyTM11NoRoomText",
                      deactivate = range("EVENT_BEAT_CERULEAN_GYM_TRAINER_", 0, 1),
+                      badgeSound = "Get_Key_Item",
+                      tmSound = "Get_Item1",
                      dialogue = {
                        "_CeruleanGymMistyReceivedCascadeBadgeText",
-                        "_CeruleanGymMistyCascadeBadgeInfoText",
+                      },
+                      tmPre = { "_CeruleanGymMistyCascadeBadgeInfoText" },
+                      tmDialogue = {
                        "_CeruleanGymMistyReceivedTM11Text",
                      } },
  ["OPP_LT_SURGE#1"] = { badge = "THUNDERBADGE", flag = "EVENT_BEAT_LT_SURGE",
                         item = "TM_THUNDERBOLT",
+                         gotFlag = "EVENT_GOT_TM24",
+                         noRoom = "_VermilionGymLTSurgeTM24NoRoomText",
                         deactivate = range("EVENT_BEAT_VERMILION_GYM_TRAINER_", 0, 2),
+                         tmSound = "Get_Key_Item",
                         dialogue = {
                           "_VermilionGymLTSurgeReceivedThunderBadgeText",
-                           "_VermilionGymLTSurgeThunderBadgeInfoText",
+                         },
+                         tmPre = { "_VermilionGymLTSurgeThunderBadgeInfoText" },
+                         tmDialogue = {
                           "_VermilionGymLTSurgeReceivedTM24Text",
                           "_TM24ExplanationText",
                         } },
  ["OPP_ERIKA#1"] = { badge = "RAINBOWBADGE", flag = "EVENT_BEAT_ERIKA",
                      item = "TM_MEGA_DRAIN",
+                      gotFlag = "EVENT_GOT_TM21",
+                      noRoom = "_CeladonGymTM21NoRoomText",
                      deactivate = range("EVENT_BEAT_CELADON_GYM_TRAINER_", 0, 6),
+                      tmSound = "Get_Item1",
                      dialogue = {
                        "_CeladonGymErikaReceivedRainbowBadgeText",
-                        "_CeladonGymRainbowBadgeInfoText",
+                      },
+                      tmPre = { "_CeladonGymRainbowBadgeInfoText" },
+                      tmDialogue = {
                        "_CeladonGymReceivedTM21Text",
                        "_TM21ExplanationText",
                      } },
  ["OPP_KOGA#1"] = { badge = "SOULBADGE", flag = "EVENT_BEAT_KOGA",
                     item = "TM_TOXIC",
+                     gotFlag = "EVENT_GOT_TM06",
+                     noRoom = "_FuchsiaGymKogaTM06NoRoomText",
                     deactivate = range("EVENT_BEAT_FUCHSIA_GYM_TRAINER_", 0, 5),
+                     tmSound = "Get_Key_Item",
                     dialogue = {
                       "_FuchsiaGymKogaReceivedSoulBadgeText",
-                       "_FuchsiaGymKogaSoulBadgeInfoText",
+                     },
+                     tmPre = { "_FuchsiaGymKogaSoulBadgeInfoText" },
+                     tmDialogue = {
                       "_FuchsiaGymKogaReceivedTM06Text",
                       "_FuchsiaGymKogaTM06ExplanationText",
                     } },
  ["OPP_SABRINA#1"] = { badge = "MARSHBADGE", flag = "EVENT_BEAT_SABRINA",
                        item = "TM_PSYWAVE",
+                        gotFlag = "EVENT_GOT_TM46",
+                        noRoom = "_SaffronGymSabrinaTM46NoRoomText",
                        deactivate = range("EVENT_BEAT_SAFFRON_GYM_TRAINER_", 0, 6),
+                        badgeSound = "Get_Key_Item",
+                        tmSound = "Get_Item1",
                        dialogue = {
                          "_SaffronGymSabrinaReceivedMarshBadgeText",
-                          "_SaffronGymSabrinaMarshBadgeInfoText",
+                        },
+                        tmPre = { "_SaffronGymSabrinaMarshBadgeInfoText" },
+                        tmDialogue = {
                          "_SaffronGymSabrinaReceivedTM46Text",
                          "_TM46ExplanationText",
                        } },
  ["OPP_BLAINE#1"] = { badge = "VOLCANOBADGE", flag = "EVENT_BEAT_BLAINE",
                       item = "TM_FIRE_BLAST",
+                       gotFlag = "EVENT_GOT_TM38",
+                       noRoom = "_CinnabarGymBlaineTM38NoRoomText",
                       deactivate = range("EVENT_BEAT_CINNABAR_GYM_TRAINER_", 0, 6),
+                       badgeSound = "Get_Key_Item",
+                       tmSound = "Get_Item1",
                       dialogue = {
                         "_CinnabarGymBlaineReceivedVolcanoBadgeText",
-                         "_CinnabarGymBlaineVolcanoBadgeInfoText",
+                       },
+                       tmPre = { "_CinnabarGymBlaineVolcanoBadgeInfoText" },
+                       tmDialogue = {
                         "_CinnabarGymBlaineReceivedTM38Text",
                         "_CinnabarGymBlaineTM38ExplanationText",
                       } },
  ["OPP_GIOVANNI#3"] = { badge = "EARTHBADGE", flag = "EVENT_BEAT_GIOVANNI",
                         item = "TM_FISSURE",
+                         gotFlag = "EVENT_GOT_TM27",
+                         noRoom = "_ViridianGymGiovanniTM27NoRoomText",
                         deactivate = range("EVENT_BEAT_VIRIDIAN_GYM_TRAINER_", 0, 7),
+                         badgeSound = "Get_Item1", -- sound_level_up
+                         tmSound = "Get_Item1",
                         dialogue = {
                           "_ViridianGymGiovanniReceivedEarthBadgeText",
-                           "_ViridianGymGiovanniEarthBadgeInfoText",
+                         },
+                         tmPre = { "_ViridianGymGiovanniEarthBadgeInfoText" },
+                         tmDialogue = {
                           "_ViridianGymGiovanniReceivedTM27Text",
                           "_ViridianGymGiovanniTM27ExplanationText",
                         } },
@@ -36,7 +36,8 @@ M.CERULEAN_MELANIES_HOUSE = {
        rows[#rows + 1] = { "label", "declined" }
        rows[#rows + 1] = { "show_text", "MelanieText5" }
      end
-      ow.runner:run(rows, { npc = npc, onDone = done })
+      ow.runner:run(rows, { npc = npc, onDone = done,
+        checkpointOnDone = "release_npc" })
    end,
    -- pet flavor: the text with the species' cry over it
    TEXT_CERULEANMELANIESHOUSE_BULBASAUR = {
@@ -105,7 +106,8 @@ M.VERMILION_CITY = {
        rows[#rows + 1] = { "label", "declined" }
        rows[#rows + 1] = { "show_text", "_OfficerJennyText4" }
      end
-      ow.runner:run(rows, { npc = npc, onDone = done })
+      ow.runner:run(rows, { npc = npc, onDone = done,
+        checkpointOnDone = "release_npc" })
    end,
  },
 }
@@ -62,10 +62,15 @@ M.MT_MOON_B2F = {
      { "walk_npc", 6, { "left", "left", "left", "left", "left" } },
      { "face_object", 6, "left" },
      { "show_text", "_MtMoonJessieJamesText2" },
+      -- MtMoonB2FScript12 arms _MtMoonJessieJamesText3 with
+      -- SaveEndBattleTextPointers before it sets wCurOpponent, so
+      -- TrainerBattleVictory prints it on the battle screen as "ROCKET: A
+      -- brat beat us?" between TrainerDefeatedText and MoneyForWinningText.
+      -- Its one-word first line only reads right behind that tag (#866).
+      { "save_end_battle_text", "_MtMoonJessieJamesText3" },
      { "start_battle", "trainer", "OPP_ROCKET", 42 },
      { "check_battle_result", "win" },
      { "jump_if_false", "end" },
-      { "show_text", "_MtMoonJessieJamesText3" },
      { "show_text", "_MtMoonJessieJamesText4" },
      { "stop_music" },
      { "play_music", "Music_MeetJessieJames" },
@@ -85,7 +90,8 @@ M.MT_MOON_B2F = {
 -- motto plays from off-screen FIRST, then the duo pops in at (25,10) /
 -- (24,10) and whichever of them shares the player's column ($18=24 or
 -- $19=25, EVENT_ROCKET_HIDEOUT_4_JESSIE_JAMES_ON_LEFT) walks the three
-- tiles down to loom over the player while the other steps one.  A loss
+-- tiles down to loom over the player while the other walks four and ends
+-- up beside him.  A loss
 -- re-hides them (RocketHideoutB4FResetScripts via EVENT_6A0), so the
 -- trigger re-arms clean.
 -- -------------------------------------------------------------------
@@ -106,7 +112,7 @@ M.ROCKET_HIDEOUT_B4F = {
    if f.EVENT_BEAT_ROCKET_HIDEOUT_4_JESSIE_JAMES then return false end
    -- ON_LEFT: player under James's column (25); movement data pairs
    -- RocketHideoutB4FJessieJamesMovementData_45605/45606 swap so the
-    -- column-mate walks 3, the other 1.
+    -- column-mate walks 3, the other 4.
    local onLeft = (x == 25)
    ow.runner:run({
      { "stop_music" },
@@ -116,16 +122,30 @@ M.ROCKET_HIDEOUT_B4F = {
      { "emote", "player", "shock", 30 },
      { "show_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JAMES" },
      { "show_object", "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_JESSIE" },
-      -- James (object 2) then Jessie (object 3), Script4..Script9 order
-      { "walk_npc", 2, onLeft and { "down", "down", "down" } or { "down" } },
+      -- James (object 2) then Jessie (object 3), Script4..Script9 order.
+      -- RocketHideoutB4FJessieJamesMovementData_45605 is a lone $4 that FALLS
+      -- THROUGH into _45606 ($4 $4 $4 $ff), so MoveSprite_ (home/pathfinding.asm)
+      -- reads _45605 as FOUR steps and _45606 as three; $4 is DOWN in Yellow's
+      -- Func_5288 lookup (engine/overworld/movement.asm), which walks with no
+      -- collision test.  From (25,10)/(24,10) against a player on y=14 the
+      -- column-mate stops three down, right above him, and the other walks the
+      -- full four to stand alongside -- which is what the facings below assume.
+      -- Reading _45605 as a single step stranded whoever was off-column three
+      -- tiles away, so James never reached the player (#865).
+      { "walk_npc", 2, onLeft and { "down", "down", "down" }
+                              or { "down", "down", "down", "down" } },
      { "face_object", 2, onLeft and "down" or "left" },
-      { "walk_npc", 3, onLeft and { "down" } or { "down", "down", "down" } },
+      { "walk_npc", 3, onLeft and { "down", "down", "down", "down" }
+                              or { "down", "down", "down" } },
      { "face_object", 3, onLeft and "right" or "down" },
      { "show_text", "_RocketHideoutJessieJamesText2" },
+      -- RocketHideoutB4FScript10 saves _RocketHideoutJessieJamesText3 as the
+      -- end-battle text, so it prints as "ROCKET: Such a dreadful twerp!" on
+      -- the battle screen ahead of MoneyForWinningText (#866).
+      { "save_end_battle_text", "_RocketHideoutJessieJamesText3" },
      { "start_battle", "trainer", "OPP_ROCKET", 43 },
      { "check_battle_result", "win" },
      { "jump_if_false", "lost" },
-      { "show_text", "_RocketHideoutJessieJamesText3" },
      { "show_text", "_RocketHideoutJessieJamesText4" },
      { "stop_music" },
      { "play_music", "Music_MeetJessieJames" },
@@ -175,16 +195,27 @@ M.POKEMON_TOWER_7F = {
      { "show_text", "_PokemonTowerJessieJamesText1" },
      { "face_player_dir", "up" },
      { "emote", "player", "shock", 30 },
-      -- Jessie (object 1) then James (object 2), Script1..Script6 order
-      { "walk_npc", 1, onLeft and { "down" } or { "down", "down", "down" } },
+      -- Jessie (object 1) then James (object 2), Script1..Script6 order.
+      -- Same fall-through blob as the hideout: PokemonTower7FMovementData_60d7a
+      -- is a lone $4 running into _60d7b ($4 $4 $4 $FF), so _60d7a is FOUR
+      -- steps and _60d7b is three.  From (10,8)/(11,8) against a player on
+      -- y=12 the column-mate halts one tile above him and the other closes the
+      -- full four to his side; the single-step reading is why James only
+      -- "moved a bit" here (#865).
+      { "walk_npc", 1, onLeft and { "down", "down", "down", "down" }
+                              or { "down", "down", "down" } },
      { "face_object", 1, onLeft and "right" or "down" },
-      { "walk_npc", 2, onLeft and { "down", "down", "down" } or { "down" } },
+      { "walk_npc", 2, onLeft and { "down", "down", "down" }
+                              or { "down", "down", "down", "down" } },
      { "face_object", 2, onLeft and "down" or "left" },
      { "show_text", "_PokemonTowerJessieJamesText2" },
+      -- PokemonTower7FScript7 saves _PokemonTowerJessieJamesText3 as the
+      -- end-battle text: "ROCKET: You will regret this!" on the battle screen,
+      -- before the prize money (#866).
+      { "save_end_battle_text", "_PokemonTowerJessieJamesText3" },
      { "start_battle", "trainer", "OPP_ROCKET", 44 },
      { "check_battle_result", "win" },
      { "jump_if_false", "end" },
-      { "show_text", "_PokemonTowerJessieJamesText3" },
      { "show_text", "_PokemonTowerJessieJamesText4" },
      { "stop_music" },
      { "play_music", "Music_MeetJessieJames" },
@@ -254,10 +285,12 @@ M.SILPH_CO_11F = {
      { "walk_npc", 6, jessieDirs },
      { "face_object", 6, jessieFace },
      { "show_text", "_SilphCoJessieJamesText2" },
+      -- SilphCo11FScript11 saves _SilphCoJessieJamesText3 (SilphCo11FText_624c2)
+      -- as the end-battle text: "ROCKET: Like always..." before the money (#866).
+      { "save_end_battle_text", "_SilphCoJessieJamesText3" },
      { "start_battle", "trainer", "OPP_ROCKET", 45 },
      { "check_battle_result", "win" },
      { "jump_if_false", "end" },
-      { "show_text", "_SilphCoJessieJamesText3" },
      { "show_text", "_SilphCoJessieJamesText4" },
      { "stop_music" },
      { "play_music", "Music_MeetJessieJames" },
@@ -100,7 +100,8 @@ local function oldMan2Talk(game, ow, npc, done)
    game.stack:push(TextBox.new(game, text(game).losingMyTouch, done))
    return
  end
-  ow.runner:run(oldMan2Rows(game, ow, npc), { npc = npc, onDone = done })
+  ow.runner:run(oldMan2Rows(game, ow, npc), { npc = npc, onDone = done,
+    checkpointOnDone = "release_npc" })
 end

 M.VIRIDIAN_CITY = {
@@ -38,7 +38,7 @@ the same core data and graphics into the source tree for verification.
 | | `src/core/SaveData.lua` | Lua-serialized save in the LÖVE save dir |
 | render | `src/render/Renderer.lua` | 160x144 canvas, integer nearest scaling |
 | | `src/render/TileRenderer.lua` | one SpriteBatch per map (8x8 quads) + border-block ring |
-| | `src/render/SpriteRenderer.lua` | 6-frame walker sheets, flipped right facing |
+| | `src/render/SpriteRenderer.lua` | variable-size anchored sprite sheets, 6-frame walkers and flipped right facing |
 | | `src/render/Font.lua` | glyph rendering via charmap (greedy longest match) |
 | | `src/render/TextBox.lua` | dialogue box: typewriter, `\n` line, `\v` scroll, `\f` page |
 | | `src/render/Camera.lua`, `Transition.lua` | follow camera, warp fades |
@@ -1,515 +0,0 @@
-# Behavior porting notes
-
-What was ported from pokered's engine code and where it came from.
-
-## Overworld
-
- **Collision rule** (`home/overworld.asm` tile-in-front checks): a 16x16
-  cell is passable when its bottom-left 8x8 tile is in the tileset's
-  `coll_tiles` list. Verified against Pallet Town's fences/houses/water
-  and Oak's Lab furniture.
- **Warp activation** (`home/overworld.asm` CheckWarpsNoCollision /
-  ExtraWarpCheck): a warp fires when arriving on a warp whose standing
-  tile is in the tileset's door or warp tile list, or when standing on a
-  warp and walking off the map edge (interior exit mats). Both paths are
-  data-driven from `door_tile_ids.asm` / `warp_tile_ids.asm`.
- **LAST_MAP warps** return to the remembered outdoor map/position, like
-  `wLastMap`.
- **Connections** (`map_header` connection directives): crossing an edge
-  places the player at `destCoord = curCoord - offset*2` cells on the
-  destination's opposite edge.
- **Movement**: tile-by-tile, 1 px/frame at 60 fps (16 frames per step),
-  tap-to-turn without stepping, hold-to-walk, input locked mid-step.
- **Wild encounters** (`engine/battle/wild_encounters.asm`): per grass
-  step, encounter iff `rand(0..255) < rate`; slot picked via the
-  cumulative buckets 51/102/141/166/191/216/229/242/253/256.
- **Initial object visibility** from `toggleable_objects.asm` (e.g. Oak
-  hidden in his lab), with `show_object`/`hide_object` script commands
-  persisting to the save like the missable-object bits.
-
-## Pokémon math (`engine/pokemon/calc_stats.asm`, `experience.asm`)
-
- `stat = floor(((base + DV)*2 + floor(sqrt(statExp)/4)) * L / 100) + 5`
-  (HP: `+ L + 10`); HP DV from the low bits of the other four DVs.
- Growth curves use the exact cubic coefficients (MEDIUM_SLOW =
-  1.2n^3 - 15n^2 + 100n - 140, etc).
- Exp gain = `floor(baseExp * level / 7)` (x1.5 for trainer battles);
-  defeated species' base stats accumulate as stat experience.
-
-## Battle core (`engine/battle/core.asm`)
-
- Damage: `floor(floor(2L(x2 crit)/5 + 2) * power * atk / def / 50)`
-  capped at 997, `+2`, STAB x1.5, per-matchup type multipliers applied
-  sequentially (x10 fixed point), then `rand(217..255)/255` when
-  damage > 1.
- Critical hits: `rand(0..255) < baseSpeed/2` (x4 for Karate Chop, Razor
-  Leaf, Crabhammer, Slash, capped 255); crits double level and ignore
-  stat stages (gen1_faithful ruleset).
- Accuracy: `rand(0..255) < floor(acc*255/100)` after accuracy/evasion
-  stages,  including the 1/256 miss at 100% accuracy (toggleable via the
-  `modern_clean` ruleset).
- Stat stages use the 25/28/33/40/50/66/100/150/.../400 multiplier table
-  (`data/battle/stat_modifiers.asm`).
- Physical/special split by type (special = Water/Grass/Fire/Ice/
-  Electric/Psychic/Dragon).
- Status: paralysis speed/4 and 25% full para, burn halves physical
-  attack, poison/burn residual = maxHP/16, sleep 1-7 turns waking on the
-  lost turn, freeze permanent (as in Gen 1).
- Turn order: effective speed, coin-flip ties; Quick Attack first,
-  Counter last (Gen 1's only priorities).
- Run formula (`TryRunningFromBattle`): always escape if faster,
-  otherwise `floor(pSpd*32 / (eSpd/4)) + 30*attempts` vs `rand(0..255)`.
- Catching (`ItemUseBall`): ball-specific rand ranges (255/200/150),
-  status bonus 25/12, second roll `floor(maxHP*255/ballFactor) /
-  floor(HP/4)` capped 255.
- Prize money: class base money x last defeated mon's level
-  (`pic_pointers_money.asm`).
-
-## Battle move effects (engine/battle/core.asm, move_effects/*)
-
- Mimic via Metronome (effects.asm:1203-1273): MimicEffect's
-  .letPlayerChooseMove branch snapshots wCurrentMenuItem before the
-  copy-picker menu opens and restores it afterward as the write index
-  into wBattleMonMoves. Since SelectMenuItem always writes
-  wCurrentMenuItem/wPlayerMoveListIndex together at the FIGHT-menu
-  confirm and nothing (including MetronomePickMove) touches either
-  variable during mid-move resolution, the reused value is always the
-  calling move's own slot,  BattleState.lua's applyMimic fallback uses
-  self.moveIndex, frozen the same way, so a called Mimic (e.g. from
-  METRONOME in slot 3) overwrites the calling move's own slot, keeping
-  its PP, matching the Gen 1 quirk exactly.
- Multi-hit distribution 2/2/2/3/3/3/4/5 over rand(0..7); all hits reuse
-  the first damage roll (faithful).
- Recoil = damage/4 (Struggle /2); drain/Dream Eater heal = damage/2;
-  Dream Eater requires sleep.
- Fixed damage: SonicBoom 20, Dragon Rage 40, Seismic Toss/Night Shade =
-  level, Psywave rand(1 .. 1.5xlevel-1).
- OHKO deals 65535, fails against faster targets; Swift skips accuracy;
-  Jump Kick crash = 1 damage on miss; Explosion halves defense and
-  faints the user even on a miss; Hyper Beam skips recharge if it KOs.
- Charge moves (incl. Fly's invulnerable turn), trapping moves locking
-  the victim out of its turns, Thrash's 3-4 turn lock ending in
-  confusion, Bide's 2-3 turn store-and-double, Rage's permanent lock
-  with attack-up on being hit, Counter/Quick Attack priority.
- Side-effect chances: 26/256 (10%), 77/256 (30%), stat-down side
-  effects 85/256; Twineedle 20% poison.
- Substitute costs 1/4 max HP, absorbs damage, blocks status/stat/side
-  effects; screens double effective defense (bypassed by crits); Focus
-  Energy keeps the Gen 1 quarter-rate bug under gen1_faithful.
- Status: sleep 1-7 turns (wake turn is lost), freeze permanent, burn
-  halves physical attack, paralysis speed/4 + 25% full para, Toxic's
-  rising counter, Leech Seed transfer, confusion 2-5 turns with 50%
-  40-power typeless self-hit.
- Trainer Pokémon use fixed DVs 9/8/8/8 (TrainerAI.asm convention).
-
-## Items (engine/items/item_effects.asm)
-
- Potion family 20/50/200/full; drinks 50/60/80; status heals per item;
-  Revive half HP; Rare Candy = exact next-level exp with HP delta kept;
-  evolution stones use the extracted evos data; TMs single-use / HMs
-  reusable, gated by the species' real tmhm list; Repel 100/200/250
-  steps blocking wilds below the lead's level; Escape Rope returns to
-  the last heal point.
- Snorlax (Route 12/16) only wakes via `ItemUsePokeFlute` (item-use
-  menu, adjacent to it, not yet beaten),  talking to it with the POKé
-  FLUTE merely in the bag has no effect (`engine/items/item_effects.asm`,
-  `scripts/Route12.asm`/`Route16.asm`).
- Mart inventories come from the script_mart lists per clerk; selling
-  pays half price; TM prices from tm_prices.asm.
-
-## Overworld field systems
-
- Ledges from ledge_tiles.asm (facing + standing tile + ledge tile +
-  input direction -> two-cell hop).
- Counter talk-through uses the tileset's counter tiles
-  (tileset_headers.asm), which is how mart clerks and nurses work.
- Trainer sight (`home/trainers.asm` CheckFightingMapTrainers +
-  `engine/overworld/trainer_sight.asm`): extracted per-trainer range,
-  inclusive tiles along the facing line; detection runs only on
-  tile-aligned frames, before input handling, so on detection the d-pad
-  is dead (wJoyIgnore) and the player freezes on the spotted tile; the
-  "!" holds 60 frames (EmotionBubble), then the trainer walks
-  distance−1 steps to the adjacent tile (none if already adjacent) and
-  uses the real battle/won/after dialogue from the trainer headers.
-  Sight is a pure screen-coordinate comparison with no line-of-sight
-  obstruction check (TrainerEngage / CheckSpriteCanSeePlayer): an
-  aligned in-range trainer engages through interposed NPCs and
-  unwalkable tiles, and the walk-up (TrainerWalkUpToPlayer, a fixed
-  distance−1 MoveSprite_ script) has no collision either, so the
-  trainer simply walks/overlaps through anything on the line,  as OAM
-  sprites overlap on hardware.
- Elevator rides (`engine/overworld/elevator.asm` ShakeElevator →
-  `src/world/ElevatorShake.lua`): choosing a floor stops the music,
-  bounces the BG scroll ±1 px around rest for 100 two-frame cycles with
-  SFX_COLLISION retriggered every cycle, restores the scroll, plays
-  SFX_SAFARI_ZONE_PA to completion, and restarts the map theme before
-  the floor warp. Lead-in delays kept per script: 9 frames of Delay3s
-  inside ShakeElevator (Celadon farjps in), 12 with the Silph/Rocket
-  scripts' extra Delay3. The offset applies to the BG layer only, 
-  sprites are OAM and stay put. After the ride the port no longer
-  jump-cuts: choosing a floor rewrites the car's own exit-warp entries
-  to that floor (`engine/events/elevator.asm` DisplayElevatorFloorMenu
-  .UpdateWarp, per scripts/SilphCoElevator.asm /
-  CeladonMartElevator.asm / RocketHideoutElevator.asm), then the player
-  is walked out through the doorway onto that warp (ow:scriptMove →
-  ow:takeWarp), like the original.
- Field-move gates (engine/overworld/field_move_messages.asm +
-  start_sub_menus.asm): IsSurfingAllowed ported exactly,  SURF refuses
-  with _CyclingIsFunText while the Cycling Road's BIT_ALWAYS_ON_BIKE is
-  armed (save.forcedBike: set on the Route 16/18 forced-bike tiles,
-  cleared by the gates, Fly, dungeon/blackout warps; the forced mount
-  itself is silent, as in CheckForceBikeOrSurf) and with
-  _CurrentTooFastText on Seafoam B4F's stairs square (7,11) until both
-  EVENT_SEAFOAM4 boulders are down. Re-selecting SURF while surfing is
-  ItemUseSurfboard's dismount attempt: steps ashore silently if the
-  facing tile is land-passable and unoccupied, else "There's no place
-  to get off!",  and the menu closes either way (wActionResult stays 1).
-  STRENGTH's first page auto-advances after the cry + Delay3 (no
-  prompt); "can move boulders." prompts. The GBPalWhiteOutWithDelay3
-  white blink plays on every .goBackToMap closer: Strength, surf
-  mount/dismount/no-place, Flash (after its text), and Dig/Teleport
-  (Cut closes without a blink, per the asm).
- Wild slot table + rate per map; water encounter tables used while
-  surfing.
- Cut-tree block swaps from cut_tree_blocks.asm; surfable tilesets from
-  water_tilesets.asm (water tile $14, plus $32 on SHIP_PORT).
-
-## Story events (data/scripts/story.lua and friends)
-
- Every hand-ported script cites its scripts/*.asm source and reuses the
-  real extracted text and event-flag names.
- Custom flag names (audited equivalent): three port-internal flag
-  families have no pokered EVENT constant but mirror the original's
-  state exactly. EVENT_TRADED_* are per-trade names for
-  wCompletedInGameTradeFlags bits (engine/events/in_game_trades.asm:
-  FLAG_TEST before the offer → after-trade text, FLAG_SET on completion;
-  dialogset text families, party-menu pick, the received mon joins the
-  end of the party, ConnectCable→anim→TradedFor→Thanks all ported).
-  EVENT_GOT_EEVEE is bookkeeping alongside the real guard,  the hidden
-  ball object (scripts/CeladonMansionRoofHouse.asm HideObject, ≡
-  save.objectToggles),  and self-heals older saves; a full party+box
-  keeps the ball claimable (_BoxIsFullText). EVENT_BEAT_SS_ANNE_RIVAL
-  stands in for scripts/SSAnne2F.asm's saved wSSAnne2FCurScript NOOP
-  progression, including the lose-and-retrigger path (flag only set on
-  victory). Names are kept for save compatibility. Coverage:
-  tests/parity_trade_gift.lua.
- The Pallet Town intro follows pokered exactly: the trigger is
-  PalletTownDefaultScript's wYCoord==1 check, Oak appears at (8,5) and
-  takes FindPathToPlayer's zigzag to one tile below the player, and the
-  escort is RLEList_ProfOakWalkToLab against the reverse-order playback
-  of RLEList_PlayerWalkToLab (the 17th simulated press is eaten by the
-  door-warp frame), followed by the OaksLab walk-in and choose-mon
-  exchange with map music deferred like BIT_NO_MAP_MUSIC. Oak's speech
-  ends with the real shrink: RedPicFront collapses through the extracted
-  ShrinkPic1/ShrinkPic2 into the overworld walking sprite on
-  OakSpeech.asm's frame timings (SFX_SHRINK, 4/4/20/50-frame beats, fade
-  to white), with the closing text box held on screen. The escort's
-  scripted steps run 16 frames/tile (chained single-tile scriptMoves
-  start back-to-back, no idle frame); Oak marches in place on the door
-  mat for RLEList_ProfOakWalkToLab's trailing NPC_CHANGE_FACING beat
-  (movement.asm ChangeFacingDirection → zero-delta TryWalking); the "!"
-  EmotionBubble overlaps the still-shown "Hey! Wait!" box
-  (PalletTownOakText prints without a button wait, then DelayFrames 10 →
-  EmotionBubble before the box clears); and the shrink beat ramps the
-  music to silence over ~70 frames (wAudioFadeOutControl = 10;
-  home/fade_audio.asm FadeOutAudio steps rAUDVOL 7→0) rather than
-  hard-stopping.
- The 12 disguised static wild battles (Power Plant Voltorb/Electrode +
-  Zapdos, Articuno, Moltres, Mewtwo) follow TalkToTrainer/
-  EndTrainerBattle exactly: cry + battle text, after-battle text without
-  a rematch once EVENT_BEAT_* is set, and the flag/HideObject on any
-  non-blackout result (fleeing loses the legendary, as in Gen 1).
-  Snorlax hides before its battle and only shows the calmed-down/
-  returned line when not caught. Zapdos/Articuno/Moltres/Mewtwo's
-  battle text is a text_far string ending in a bare "...@" terminator
-  (no <DONE>/<PROMPT>) followed by text_asm PlayCry + WaitForSoundToFinish:
-  the box types with no ▼ prompt and auto-closes only once the cry
-  finishes, never on a button press,  ported via `Commands.play_cry`
-  stashing the pending cry for the following `Commands.show_text` to
-  consume as the TextBox's auto-close sound. Voltorb/Electrode's battle
-  text has no PlayCry call in the ROM at all and keeps the ordinary
-  button-wait close.
- Gym leader repeat dialogue (data/scripts/gyms.lua): each leader's
-  text_asm branches on EVENT_BEAT_<LEADER>,  pre-badge talk prints the
-  pre-battle text and engages the leader battle (badge/TM via
-  data/scripts/victories.lua); post-badge talk prints the leader's
-  post-battle advice text (Misty's is her TM11 explanation). The
-  originals' middle branch (beaten but TM not handed over) is
-  unreachable since the TM is granted with the victory. Giovanni's
-  farewell (`ViridianGymGiovanniText` .afterBeat) hides him inside a
-  fade-to-black/fade-in Transition matching ViridianGym.asm's
-  GBFadeOutToBlack → HideObject → GBFadeInFromBlack, persisted
-  permanently via TOGGLE_VIRIDIAN_GYM_GIOVANNI in save.objectToggles.
- Cable Club receptionists (TX_SCRIPT_CABLE_CLUB_RECEPTIONIST →
-  CableClubNPC, all 12 Pokémon Centers): welcome, pre-Pokédex "making
-  preparations" brush-off, and the apply/save YES-NO are ported;
-  accepting saves the game and opens the link menu, declining prints
-  "Please come again!".
- Cinnabar fossil deposit follows GiveFossilToCinnabarLab: a menu of
-  carried fossils (FossilsList order), SeesFossilText with a Yes/No
-  confirm, ComeAgainText on either cancel.
- Hall of Fame induction: each party mon's front sprite scrolls in from
-  the left at 4px/frame, matching HoFShowMonOrPlayer's .ScrollPic
-  front-pic phase (engine/movie/hall_of_fame.asm); the back-pic's
-  enlarged/blurred pre-wipe is a VRAM-scroll-register trick not
-  replicated in this sprite-based renderer. The finale
-  (HoFDisplayPlayerStats) shows trainer name, play time, money, POKéDEX
-  seen/owned, and Prof. Oak's rating text (engine/events/
-  pokedex_rating.asm DexRatingsTable) from real save data.
- End credits + post-game reset (engine/movie/credits.asm,
-  scripts/HallOfFame.asm): screen-by-screen CreditsOrder pages (hlcoord
-  9,6 + signed columns), FadeInCredits' 4x5-frame ramp, 90/110/120/140-
-  frame holds, DisplayCreditsMon's 27-frame 8px/frame silhouette wipe,
-  LoadCopyrightTiles' three-row block, THE END at (4,8). While THE END
-  is up the HoF script autosaves (wLastBlackoutMap := PALLET_TOWN; the
-  player is saved in the HALL_OF_FAME room), waits 600 frames, then A/B
-  triggers `jp Init`,  the boot sequence replays into the title screen.
- Victory Road's boulder switches replicate the original's
-  ReplaceTileBlock data: 1F boulder at (17,13) -> block $1D at (4,6);
-  2F boulders at (1,16)/(9,16) -> $15 at (3,4) and $1D at (11,7); 3F
-  boulder at (3,5) -> $1D at (3,5), and the (23,15) hole drops the
-  boulder to 2F (hide/show toggle). Barriers are re-applied from flags
-  on map entry, exactly like the originals' map-load scripts.
- Item balls, static legendary encounters and trainer rewards
-  (badges + gym TMs, the Silph Giovanni flag) are generic systems driven
-  by the extracted object args and a hand-ported reward table
-  (data/scripts/victories.lua).
- In-game trades use the real data/events/trades.asm table (species in,
-  species out, original nickname).
-
-## Safari game (engine/events/hidden_events/safari_game.asm + engine/battle)
-
- ¥500 buys 30 SAFARI BALLs and 502 steps (scripts/SafariZoneGate.asm
-  sets `wSafariSteps = 502`); steps count down on the four outdoor zone
-  maps and hitting 0 (or throwing the last ball) ends the game at the
-  gate.
- Safari battles offer BALL / BAIT / ROCK / RUN; no player Pokémon
-  acts.  The working catch rate starts at the species rate; BAIT halves
-  it and adds 1-5 to the bait factor (zeroing the escape factor); ROCK
-  doubles it (cap 255) and adds 1-5 to the escape factor (zeroing bait)
-  -- ItemUseBait/ItemUseRock in engine/items/item_effects.asm.
- Each turn one factor decays ("is eating!" / "is angry!"); when the
-  escape factor decays to 0 the catch rate resets to the species rate
-  (PrintSafariZoneBattleText, engine/battle/safari_zone.asm).
- Flee check (engine/battle/core.asm): `b = 2 * (speed % 256)`; the mon
-  always flees when speed > 127; while eating `b /= 4`, while angry
-  `b = min(255, 2b)`; it flees when `rand(0,255) < b`.
- The SAFARI BALL rolls the ULTRA_BALL rand range (0-150) in the Gen 1
-  catch formula, against the BAIT/ROCK-modified rate.
-
-## Slot machines (engine/slots/slot_machine.asm)
-
- The three reels are the extracted 18-symbol wheel sequences
-  (data/events/slot_machine_wheels.asm); bet 1 plays the middle row,
-  bet 2 adds top+bottom, bet 3 adds both diagonals.
- Payouts: 7-7-7 = 300, BAR = 100, CHERRY = 8, MOUSE/FISH/BIRD = 15
-  (SlotRewardPointers).
- Per-wheel stop/slip rules ported exactly: wheel 1 spends up to 4 slip
-  charges, slipping past a centred CHERRY (in seven-and-bar mode it
-  always slips all 4 via pokered's `cp HIGH(SLOTS7)` bug); wheel 2 stops
-  as soon as wheels 1+2 line up any potential match (pairs checked b/b,
-  b/m, m/m, t/m, t/t) or, in seven-and-bar mode, on 7/BAR; wheel 3 rolls
-  past forbidden matches free and burns wSlotMachineRerollCounter
-  charges on winnable no-match spins, animated tile-by-tile. Luck flags
-  (SetFlags): seven-and-bar mode is sticky across spins; r==0 arms 60
-  allow-matches charges; a BAR win clears flags; a 300 win zeroes the
-  counter and clears flags with probability 128/256; 8/15 wins burn one
-  charge. Lines are checked in asm order with the first match taken;
-  A-presses are ignored while a prior wheel's slip counter is nonzero.
-  Machine and COIN CASE texts are byte-identical
-  (_GameCorner*Text; AbleToPlaySlotsCheck's no-coins gate included).
- Flow brackets: PromptUserToPlaySlots "A slot machine! Want to play?"
-  (YesNoChoice) and MainSlotMachineLoop's "One more go?" (TwoOptionMenu);
-  the x3/x2/x1 coin menu (CoinMultiplierSlotMachineText) defaults its
-  cursor to x3, bet = 3 - menu item. Static frame: the real
-  SlotMachineMap (gfx/slots/slots.tilemap, 20x12 tile ids < $25) blitted
-  from red_slots_1.png, extracted as field.slotSymbols.tilemap
-  (tools/extract/gfx.py extract_slots). Win flash:
-  SlotMachine_CheckForMatches.flashScreenLoop flips rBGP (shade 3->2) b
-  times at 5 frames each, b = 20/8/4/2 for the 300/100/15/8 rewards
-  (SlotReward{300,100,8,15}Func). Payout drip:
-  SlotMachine_PayCoinsToPlayer credits one coin every 8 frames (4 for a
-  7/BAR), SFX_SLOTS_REWARD per coin, rOBP0 symbol flicker every 5 coins.
-
-## Spinner arrow tiles (scripts/*.asm arrow movement tables)
-
- Viridian Gym and Rocket Hideout B2F/B3F keep per-coordinate RLE
-  movement lists (map_coord_movement); each list executes backwards
-  from its terminator (DecodeArrowMovementRLE), sliding the player and
-  chaining onto further arrows.
-
-## Cries (data/pokemon/cries.asm, audio/engine_1.asm)
-
- Each species = a base cry (one of 38 SFX_CryXX streams) + a frequency
-  modifier added to every note's frequency register
-  (Audio1_ApplyFrequencyModifier) + a tempo modifier
-  (`sfx tempo = $80 + length`, Audio1_SetSfxTempo).  All 151 cries are
-  rendered offline with those modifiers applied and play on battle
-  entry and Pokédex pages.
-
-## Hidden events & facility puzzles
-
- Card key doors (engine/events/card_key.asm): door tiles $18/$24
-  (SILPH_CO_11F: $5e) replaced with block $0e ($03 on 11F).
- Vermilion trash cans
-  (engine/events/hidden_events/vermilion_gym_trash.asm): the first-lock
-  can re-rolls on every Vermilion City map load (VermilionCity_Script's
-  Random & $e, even cans) and after every failed second-can guess; the
-  second lock uses the GymTrashCans table verbatim, including the
-  underflow bug that can place it in can 0 regardless of adjacency; a
-  wrong pick resets EVENT_1ST_LOCK_OPENED and re-rolls immediately; only
-  SuccessText3 prints on completion; the gym door block at (2,2) is
-  $24 closed / $5 open (scripts/VermilionGym.asm). SuccessText1/
-  SuccessText3/FailText play SFX_SWITCH/GO_INSIDE/DENIED from each
-  text's text_asm tail after the text prints (DisplayTextID's
-  WaitForTextScrollButtonPress then holds the box), so the port fires
-  them from an onDone on the TextBox, landing the beep as the box
-  closes rather than as it opens.
- Menu close-keys follow pokered's per-menu wMenuWatchedKeys mask, not
-  a single global rule: the shared Menu base (src/ui/Menu.lua) closes
-  on B only, and START-close is opt-in via opts.startCloses. Only the
-  start menu sets it, matching engine/menus/draw_start_menu.asm's
-  PAD_DOWN|PAD_UP|PAD_START|PAD_B|PAD_A; OptionsMenu also closes on
-  START via its own loop, matching engine/menus/main_menu.asm
-  DisplayOptionMenu's explicit B_PAD_B/B_PAD_START checks. Every other
-  menu (bag/PC item lists PAD_A|PAD_B|PAD_SELECT, party menu /
-  BUY-SELL-QUIT / USE-TOSS submenu / PC menus / Pokedex side menu
-  PAD_A|PAD_B) leaves PAD_START unwatched, so START does not close
-  them. START never replays SFX_PRESS_AB (HandleMenuInput_ beeps only
-  for the PAD_A|PAD_B branch).
- Old man tutorial hollow cursor: the item list is itself scripted in
-  pokered (DisplayListMenuID's old-man branch, home/list_menu.asm:65-91)
- ,  no input is read; the filled '▶' hovers POKé BALL for 80 frames,
-  auto-presses A, then PlaceUnfilledArrowMenuCursor leaves the hollow
-  '▷' on that row until ItemUseBall tears the list down for the throw.
-  Ported via ListMenu's opts.script hook (src/ui/ListMenu.lua) and
-  BattleState:openOldManBag driving the same beats. The MissingNo./
-  wGrassRate side effects of the OLD MAN name swap are not modeled, 
-  see docs/gameboy-hardware-limitations.md.
- Gym statues (gym_statues.asm): plaque with the city/leader from each
-  gym's script; the player joins WINNING TRAINERS with the badge.
- Route 22 gate / Route 23 guards: real trigger rows, badge order
-  (EARTH down to CASCADE) and EVENT_PASSED_*_CHECK skip flags.
- Game Corner poster (scripts/GameCorner.asm): block (8,2) $2a -> $43
-  on EVENT_FOUND_ROCKET_HIDEOUT.
- Seafoam Islands (scripts/SeafoamIslandsB3F/B4F.asm): reversed-RLE
-  current paths, Seafoam4HolesCoords boulder holes setting the
-  EVENT_SEAFOAM*_BOULDER*_DOWN_HOLE pairs, the forced pool exit rows.
- Rock Tunnel darkness: wMapPalOffset = 6 on entry, cleared by Flash
-  (BOULDERBADGE) or leaving (home/overworld.asm).
-
-## Battle extras
-
- GROWL/ROAR (GetMoveSound/IsCryMove, engine/battle/animations.asm
-  ~2196): the move's own MoveSoundTable tempo byte (Growl $c0, Roar
-  $40, both pitch $00) layers onto the cry via `Sound.playMoveCry`'s
-  `Source:setPitch(256/(128+tempoMod))`. Transform (engine/gfx/
-  palettes.asm DeterminePaletteID, bit TRANSFORMED): the swapped-in pic
-  is tinted PAL_GRAYMON via `PaletteFX.monPal(data, species,
-  transformed)`, not the copied species' own palette, in
-  `BattleState:speciesSprite`. Growl (DoGrowlSpecialEffects,
-  animations.asm ~928): AnimPlayer's GROWL frame-block branch keeps a
-  `growlNoteTrail` snapshot so each block's emitted sprites include the
-  previous block's note copy alongside the current one (GROWL skips
-  AnimationCleanOAM between blocks per the `cp GROWL` check ~line 145);
-  ROAR is unaffected since the asm never applies this quirk to it.
- Master/Ultra ball tosses flicker the OBJ palette: DoBallTossSpecial
-  Effects (engine/battle/animations.asm:685) XORs rOBP0 with %00111100
-  after every frame block while wCurItem <= ULTRA_BALL, so the 11 toss
-  blocks alternate the $F0/$CC shade maps starting normal; PlayAnimation
-  pushes/pops rOBP0 around each subanimation row, so the ambient
-  palette returns when the toss ends. GREAT/POKE/SAFARI balls never
-  flicker, and the toss arc always follows wCurItem via
-  TossBallAnimation, including the ghost-dodge throw.
- Anim-layer OBJ colorization is per 8x8 attribute cell: the SGB's
-  ATTR_BLK regions color the composited DMG picture per cell, not per
-  OAM entry, so an anim sprite overlapping a zone boundary takes each
-  cell's palette on the pixels inside it,  AnimPlayer samples the zone
-  under every cell an 8x8 tile touches and repaints differing cells
-  through a cell-clipped scissor (aligned tiles stay one draw).
- Ball wobbles (ItemUseBall): Z = X*Y/255 + status2 with
-  Y = rate*100/ballFactor2; <10/<30/<70 -> 0/1/2 shakes, else 3, with
-  the matching ItemUseBallText01-04 lines.
- Trainer class AI (data/trainers/ai_pointers.asm +
-  engine/battle/trainer_ai.asm): per-class item/switch routines with
-  wAICount uses per Pokémon, ported to data/scripts/ai_classes.lua.
- Exp (engine/battle/experience.asm): baseExp*level/7 divided by the
-  participant count, x1.5 for trainers, x1.5 for traded mons; stat exp
-  in full to each participant.
- Move sounds: data/moves/sfx.asm (sound + pitch/tempo per move). The
-  pitch/tempo modifiers are applied at synthesis time
-  (Audio2_ApplyFrequencyModifier adds pitch to every frequency write;
-  Audio2_SetSfxTempo scales tone-channel note lengths, noise skips it), 
-  128 variant WAVs keyed "<sfx>@<pitch><tempo>" that Sound.playMove
-  selects, exact rather than a playback-rate approximation. Per-row
-  sounds fire as PlayAnimation does; GROWL/ROAR (IsCryMove) play the
-  attacker's cry. Hit sounds by effectiveness (Damage/Super/NotVery).
- Screen-effect animations (engine/battle/animations.asm +
-  engine/gfx/screen_effects.asm): every SE_* is implemented per-routine, 
-  FlashScreen/FlashScreenLong (the FlashScreenLongSGB 12-entry table),
-  Dark/Light/DarkenMon/Reset palette ops (shade-map permutations of the
-  SGB zone palettes), all SlideMon variants, ShakeBackAndForth,
-  BoundUpAndDown, SquishMonPic, Minimize (real MinimizedMonSprite),
-  spiral/shoot-balls/water-droplets/leaves emitters compiled from the
-  asm trajectories, per-animation-id frame-block flashes (Explosion,
-  Rock Slide's rumbles, Blizzard's cadence...), AnimationWavyScreen with
-  true per-scanline offsets, PredefShakeScreenHorizontally/Vertically
-  and ShakeEnemyHUD. SE rows carry the faithful blocking durations.
- SGB battle colorization (SetPal_Battle, BlkPacket_Battle,
-  SetAnimationPalette): the battle screen is colorized by zone,  player
-  HUD, enemy HUD, player mon + message box, enemy mon; trainer front
-  pics and the player/old-man back pics take PAL_MEWMON (both species
-  IDs are zero at the intro, so MonsterPalettes[0]); the ghost keeps the
-  disguised species' palette; attack animation sprites and thrown balls
-  are colored through the OBJ palettes (wAnimPalette $F0 on SGB, ambient
-  $E4, OBP1 $6C). Headless/no-shader environments fall back to the flat
-  pipeline.
- Mimic resolves mid-move (MimicEffect): accuracy first, then the
-  player's copy menu (enemy/link copy a random slot); the copy
-  overwrites only the slot's move ID,  PP is shared with Mimic's slot, 
-  and reverts on switch/battle end.
- Old man tutorial (DisplayBattleMenu's BATTLE_TYPE_OLD_MAN branch): the
-  real scripted cursor,  ▶ beside FIGHT for 80 frames, beside ITEM for
-  50, ITEM force-selected into the POKé BALL x50 list; the throw always
-  catches at full HP (item_effects.asm jumps straight to .captured, 3
-  shakes, no party/dex add, no ball consumed); backing out of the bag
-  replays the script. The old man never attacks,  the original tutorial
-  is menu navigation + a guaranteed catch, nothing more.
-
-## Link battles (lockstep)
-
- Both sides simulate with a shared Park-Miller RNG stream (host deals
-  the seed), identical pack/unpack-clamped party copies, no badge
-  boosts, and a mirrored speed-tie roll (the guest inverts it); a
-  canonical host-side-first state hash is exchanged per turn and any
-  mismatch ends the match as a draw.
-
-## Music (audio/engine_1.asm)
-
- Note duration: `frames = length * speed * tempo / 0x100` with
-  fractional carry, at 60 fps (Audio1_note_length / CalculateDelay).
- Frequency: `reg = pitches[note] asr (octave - 1)` (CalculateFrequency;
-  the octave byte stores `8 - octave`), `f = 131072/(2048 - reg)` for
-  squares, halved for channel 3.
- note_type volume/fade renders as an NRx2-style envelope (step every
-  `fade/64` s); duty_cycle maps to 12.5/25/50/75% pulse widths;
-  sound_call/sound_loop honor the engine's one-level call stack and
-  loop counters.
-
-## Text & font
-
- The Pokédex height row uses the real ′/″ tiles: gfx/pokedex/pokedex.png
-  tiles 0/1 are patched over font-extra slots $60/$61 exactly as
-  engine/gfx/load_pokedex_tiles.asm loads them over vChars2 (they replace
-  glyphs charmap.asm marks unused); ASCII `"` aliases to the closing-
-  quote glyph $73 so stray hand-written quotes render.
-
-## Validation against the original
-
- `tests/run_tests.lua` pins hand-checked values: L5 Bulbasaur 19 HP /
-  9 Atk at 0 DVs, L100 Mewtwo 415 HP / 406 Spc at max DVs+statExp,
-  MEDIUM_SLOW(5) = 135, type chart spot checks, deterministic damage
-  rolls, Route 1 slot 1 = L3 Pidgey.
- The autopilot run reproduces the original's early flow on real map
-  data: Pallet sign text, lab door warp target (5,11), Oak's Lab exit by
-  walking off the mat, connection into Route 1 at matching x.
@@ -1,50 +0,0 @@
-# ROM Extraction Notes
-
-There are two ROM-only extraction paths:
-
- The packaged app uses `src/import/RomImporter.lua` and
-  `src/import/RomExtractor.lua` on first boot.
- Developers can run `tools/build_data.py --rom <path> [--clean]` to generate
-  data in the source tree for audit and parity work.
-
-Both paths read only the supplied ROM and the checked-in
-`tools/rom_manifest.json`. Neither invokes RGBDS, Git, or a disassembly.
-
-## Validation
-
-Only the canonical US Pokemon Red ROM is supported. SHA-1 is checked before
-any cached output is removed or written.
-
-## Decoded Data
-
-| Area | ROM data |
-| --- | --- |
-| world | map headers, block maps, connections, warps, signs, objects |
-| tiles | tileset graphics, blocksets, collision, door and warp tile lists |
-| text | 2,584 text command streams and RAM/number substitutions |
-| Pokemon | names, stats, evolutions, learnsets, Dex data, compressed pictures |
-| battle | moves, detailed animations, OAM frames/tiles, effects, type chart, palettes, trainer parties/AI/pictures |
-| inventory | item names, prices, key-item flags, TM/HM data |
-| encounters | grass and water wild tables |
-| UI | fonts, icons, title/intro, trainer card, town map, slots, field effects |
-| audio | music, SFX and cry headers, channel programs, wave instruments |
-
-The Python and Lua picture decompressors implement the Gen 1 `pic` format.
-Graphics are converted to RGBA PNGs. OAM artwork uses transparent color 0;
-battle pictures use edge-connected white matting so white interior details
-remain visible.
-
-The in-app importer stores three audio ROM banks as a 48 KiB
-`programs.bin`. `src/core/ChipAudio.lua` interprets the channel bytecode and
-synthesizes music as a queueable stream; SFX and cries are synthesized on
-demand. This avoids shipping or generating a large WAV/OGG tree.
-
-## Metadata Boundary
-
-Names, dimensions, enum ordering, Lua script hooks, and hand-ported field
-behavior do not survive compilation in a form the Lua runtime can infer.
-Those relationships are bundled in `rom_manifest.json`. The manifest stores
-no dialogue strings, images, audio samples, or ROM bytes.
-
-`tools/make_rom_manifest.py` and `tools/verify_rom_data.py` are developer audit
-tools. They are not used by the packaged game.
@@ -1,48 +0,0 @@
-# Sideload the iOS build with AltStore
-
-Every GitHub Release ships an IPA (`gen1recomp-*-ios.ipa`). Install it on
-your iPhone or iPad with [AltStore Classic](https://altstore.io/) — AltStore
-re-signs the app with **your** free Apple ID so you do not need a Mac or
-Xcode.
-
-## 1. Install AltStore
-
-Follow the official guide for your computer:
-
- [How to Install (Windows)](https://faq.altstore.io/altstore-classic/how-to-install-altstore-windows)
- [How to Install (macOS)](https://faq.altstore.io/altstore-classic/how-to-install-altstore-macos)
-
-You will install **AltServer** on the computer, then use it to put AltStore
-on the phone. What AltServer is and why it needs to stay running:
-
- [AltServer](https://faq.altstore.io/altstore-classic/altserver)
-
-Stuck? Start here:
-
- [Troubleshooting Guide](https://faq.altstore.io/altstore-classic/troubleshooting-guide)
-
-## 2. Install the game
-
-1. Download `gen1recomp-*-ios.ipa` from
-   [Releases](https://github.com/bryanthaboi/gen1recomp/releases).
-2. Open **AltStore** on the phone (AltServer must be running on the same
-   Wi‑Fi, or keep the phone plugged into the computer).
-3. Tap **My Apps → +** (or share the IPA into AltStore) and pick the file.
-4. Sign in with your Apple ID when prompted. Wait for the install to finish.
-5. On first launch: Settings → **Privacy & Security → Developer Mode** (iOS
-   16+), and Settings → **General → VPN & Device Management** → Trust your
-   Apple ID if asked.
-
-Then open the app, import your own legal `.gb` ROM on the Red/Blue tab, and
-play.
-
-## Refresh / 7-day limit
-
-With a free Apple ID, sideloaded apps stop launching after **7 days**. Keep
-AltServer running so AltStore can refresh them, or open AltStore and refresh
-manually before they expire. Saves on the phone are kept across refreshes.
-
-## Prefer building it yourself?
-
-Building from source on a Mac (no AltStore) is covered in
-[ios-install.md](ios-install.md).
@@ -1,42 +0,0 @@
-# Known differences from the original game
-
-Only genuine remaining divergences live here: behavior that is still
-**missing, wrong, or approximated for convenience** and would need more
-work for true parity. Faithfully-ported behavior is documented in
-docs/behavior-porting-notes.md; deliberate additions beyond the original
-are in docs/new-features.md.
-
-## Reimplemented unused Prof. Oak and Rocket Chief battles
-
-The original ROM defines trainer data for `PROF_OAK` and `CHIEF`
-(`data/trainers/parties.asm`) but never attaches either to an NPC, so
-both battles are unreachable in the real game. This project makes them
-fightable after the Hall of Fame:
-
- Prof. Oak battles you in Pallet Town once `EVENT_BEAT_CHAMPION_RIVAL`
-  is set, using `ProfOakData`'s three starter-matched teams (the team is
-  picked by the type that counters your starter, mirroring the rival).
- The Celadon Game Corner Chief battles you in his house post-game.
-  `ChiefData` is empty in the ROM, so `OPP_CHIEF` is given a
-  reconstructed party.
-
-This is an intentional divergence: neither battle can be triggered in the
-original game.
-
-## Reimplemented unused Silph Co. card-key doors
-
-`engine/events/card_key.asm` and the unused `CardKeyTable1/2/3` coordinate
-lists (`data/events/card_key_coords.asm`) describe locked doors for Silph
-Co. floors 2F-11F, but no retail `.blk` map layout ever places the closed
-door block at those coordinates, so the card key check is dead code in
-the original game. This project stamps the closed door block (`$54`/`$5f`
-on floors 2F-10F, `$20` on 11F) over each of the 20 door coordinates on
-map load, and swaps it for the open block once that door's
-`EVENT_SILPH_CO_n_UNLOCKED_DOORn` flag is set (using the key from a Team
-Rocket grunt, as in the original's unused design).
-
-This is an intentional divergence: the doors are not visible or
-functional in the original game. The door layout lives in
-`tools/rom_manifest.json` (`field.cardKeyDoors.closedDoors`), hand-ported
-since no retail ROM data encodes it; `src/import/RomExtractor.lua` copies
-it straight through on ROM import.
@@ -1,294 +0,0 @@
-# Launcher
-
-The launcher is `src/import/RomImporter.lua`, the first-run / title screen
-that runs before `Game:load`. Besides ROM import (see the file's own header)
-it hosts a tabbed shell covering per-game save slots and a mod manager. This
-file documents the runtime model; the visual spec lives separately.
-
-## Android multi-ROM / mod / save import
-
-On Android, `love.system.pickFile([kind])` opens the Storage Access Framework
-picker (`GameActivity.showFilePicker`); the chosen file is copied into the app
-save directory as:
-
-| `kind` | Destination |
-| --- | --- |
-| nil / `"rom"` | `picked_rom.gb` (open) |
-| `"mod"` | `picked_mod.zip` (open) |
-| `"sav"` / `"save"` | `picked_save.sav` (open) |
-
-Export uses a separate API: `love.system.createFile(suggestedName)` →
-`GameActivity.showCreateDocument` (`ACTION_CREATE_DOCUMENT`), which copies
-staged `pending_export.sav` to the user-chosen URI and writes `export_done.flag`
-for the launcher to acknowledge on refocus.
-
-`RomImporter` then imports on refocus / Choose:
-
- **ROMs** via `findPendingRom`: only a 1 MiB `.gb` whose SHA-1 maps to a
-  version that is **not** yet ready counts as pending. A leftover
-  `picked_rom.gb` from Red therefore cannot block Blue's Choose (issue #167).
- **Mods** via `findPendingMod`: Prefer `picked_mod.zip`, or (on Choose) any
-  other `.zip` at the save-dir root (USB copy).
- **Saves** via `findPendingSav`: Prefer `picked_save.sav`, or (on Choose) any
-  other `.sav` at the save-dir root.
-
-After a successful import the consumed save-dir file is removed.
-
-**Manual check (device/emulator):** import Red → switch to Blue → Choose →
-system file picker must appear (not a silent Red re-extract) → pick Blue →
-Blue becomes ready beside Red. On the MODS tab, Import mod .zip must open the
-same system picker and install the chosen archive on return.
-
-## Tab structure
-
-`self.tab` is one of `"red"`, `"blue"`, `"yellow"`, `"mods"`. The tab bar
-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
-  Responsiveness). The MODS tab (`_drawModsPanel`) shows the mod list instead.
- The self-updater banner (`self.Check`, see `docs/updater.md`) draws as a
-  centered pill in a reserved band just above the footer, on every tab. That
-  position is unchanged by this redesign, so `docs/updater.md` needed no edits.
-
-## Save slot model
-
-All slot I/O lives in `src/core/SaveData.lua` and goes through the same fs
-abstraction (`persistFs`) every other save/options call uses, so portable
-mode (an `io.*` filesystem used when `portable.txt` marks the install)
-keeps working unchanged.
-
- **Files.** A version's playthroughs live under `saves/<version>/`, one file
-  per slot: `saves/<version>/slot1.lua` plus a rolling `.bak` and staged
-  `.tmp` witness (`slotNames`), mirroring the write/recovery discipline
-  `SaveData.save`/`load` already use for the flat legacy file. Slot ids match
-  `slot%d+`; `createSlot` allocates one past the highest existing number so a
-  reused id can never collide with a lingering file.
- **Registry.** The ordered slot list and which one is active persist in
-  `options.lua` (via the existing `SaveData.loadOptions`/`saveOptions`):
-  `options.saveSlots = { [version] = { list = {"slot1", ...}, active = "slot1" } }`.
-  Custom slot labels (#205) live alongside them in the same registry:
-  `options.saveSlots[version].names = { slot1 = "Nuzlocke" }`, written by
-  `SaveData.renameSlot` (trimmed; an empty label clears it) and surfaced on
-  each `listSlots` row as `label` (the launcher row shows `label`, falling
-  back to the player name). `deleteSlot` drops the label with the slot.
-  Renaming never touches the save file, so an empty slot can be labeled.
-  On desktop, right-clicking a slot row opens the inline rename modal
-  (Enter commits, Esc cancels); touch has no secondary button, so the
-  affordance is desktop-only.
- **Active slot resolution.** `saveNames(version)`, the function every
-  existing caller (`TitleState` hasSave/load/save, recovery order) already
-  goes through, now resolves the *active* slot instead of a fixed flat name.
-  Resolved once per version per process (`ensureVersionSlots`, cached in
-  `activeSlotCache`/`slotsChecked`): a registry entry wins; otherwise a lazy
-  legacy migration may create one; otherwise the flat legacy path is used
-  (`save.lua` / `save_blue.lua`), so a pre-slots install keeps working as before.
- **Legacy migration.** One-time per version, lazy on first
-  `listSlots`/`load`/`saveNames` call (`tryMigrateLegacy`): if a flat legacy
-  file exists and no `saves/<version>/` registry does, its main + `.bak` are
-  copied into `saves/<version>/slot1.lua(.bak)`, verified readable
-  (`decodeSlot`: main, then `.tmp`, then `.bak`), and only then are the
-  originals removed and `slot1` registered as active. A copy that fails to
-  verify leaves the originals in place; migration never loses data.
-
-The launcher-facing API:
- `SaveData.listSlots(version)` -> array of `{id, exists, name, meta}` for
-  every registered slot. `name` is the save's player name, or `nil` for an
-  empty slot; `meta` is `{badges, timeText, dexCount}` (the same fields the
-  title screen's `ContinueInfo` shows) or `nil`. The pure part,
-  `SaveData.slotSummary(save)`, is unit-testable with no filesystem.
- `SaveData.setActiveSlot(version, slotId)` registers the id if new, persists
-  it as active, and updates the process cache so the very next save/load
-  lands there. The launcher calls this the moment a slot row is clicked
-  (`RomImporter:_selectSlot`); pressing Play needs no signature change, since
-  `Game.lua`/`main.lua` still just call `SaveData.load()`/`save()`.
- `SaveData.createSlot(version)` -> new slot id, registered but with **no
-  save file written**. An empty slot means the title screen offers NEW GAME
-  only, which needs no further changes.
- `SaveData.deleteSlot(version, slotId)` removes the slot's
-  main/`.bak`/`.tmp` files, drops it from the registry, and if it was active
-  points active at another remaining slot (or clears active when the list is
-  empty). The launcher's SAVE SLOT panel Delete control calls this.
-
-## Launcher mod manager
-
-`src/mods/LauncherMods.lua` is a launcher-only read of the mod set. It runs
-before `Game:load`, so **it never loads a mod's entry chunk**; only
-`manifest.json` is read and validated (`src/mods/Manifest.validate`), the way
-`Loader:_discover` finds mods without running them. The real loader
-(`src/mods/Loader.lua`) still owns the actual load at boot.
-
- `LauncherMods.list()` scans `mods/` one level deep (first id wins on a
-  duplicate) and returns one row per mod:
-  `{id, name, version, badge, description, enabled, status, statusDetail}`.
-  `badge` is the manifest's `category`, falling back to `profile`, then
-  `"MOD"`, uppercased. `enabled` reads `options.mods[id]` (missing means
-  enabled, matching the loader's own default).
- `status` is `"ok"`, `"warn"`, or `"conflict"`, computed by the pure
-  `LauncherMods.deriveList`/`statusFor` against `ManagerState.resolveToggle`
-  and the validated manifests: `conflict` when enabling this mod collides
-  with another enabled one; `warn` for an out-of-range `game_version` or an
-  absent/disabled/wrong-version hard dependency; `ok` otherwise. Having no
-  `love.*` calls, this half is table-driven by the test suite on its own.
- `LauncherMods.setEnabled(id, bool)` persists `options.mods[id]` as a plain
-  boolean, the exact shape `Loader:_saveState` writes, so the running game
-  and the in-game `ManagerState` see the change on next boot. The mods panel
-  calls this on every toggle and re-derives the list right away
-  (`RomImporter:_refreshMods`) so a status change (e.g. a new conflict)
-  shows without waiting for a reload.
- `LauncherMods.installZip(path)` mounts the archive with
-  `love.filesystem.mount`, locates the mod root via `locateRoot` (manifest at
-  the zip root, or inside one top-level folder), validates its manifest, and
-  copies the tree into the save-dir `mods/<id>/` before unmounting. Rejects a
-  duplicate of an already-installed mod id, and accepts either an external
-  path string or a LOVE `DroppedFile`, staging a dropped file into a save-dir
-  temp first (mount only reaches save-dir-relative paths), the same way
-  `RomImporter` handles a dropped ROM. A failed copy rolls its partial tree
-  back, and every path unmounts and clears the staged temp file.
- `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
-
-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).
-  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
-  a bad main-data checksum), then registers a fresh slot (`SaveData.createSlot`),
-  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. 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/<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
-  (`_savedropTarget`). `.gb` (ROM) and `.zip` (mod) routing is unchanged.
- **Failure UX.** Every error path (wrong size, bad checksum, write failure,
-  nothing to export, ROM not imported yet) surfaces as a red notice line on the
-  card. Nothing raises and nothing silently no-ops.
-
-`SaveFileIO` is love-free enough to unit-test through the same in-memory
-filesystem stub the slot backend uses (`tests/engine/save_file_io_tests.lua`).
-
-## Responsiveness
-
-Every measurement derives from `love.graphics.getDimensions()` each frame
-plus the existing global scale `s = clamp(height / 768, 0.7, 1.6)`; nothing
-assumes a fixed window size. The game panel's two-column grid (ROM/SAVE
-FILES/Play on the left, SAVE SLOT on the right) collapses to one stacked
-column, slot card below Play, when the window is too narrow for both
-`~300 * s`-wide columns. The save-slot list and the mod list both scroll
-(wheel, or drag on touch/desktop) clamped to their own content extent,
-recomputed every draw. The tab bar labels only the active chip so it stays
-narrow-safe, and content caps out at `~1440 * s` wide, centered.
-
-The desktop window has a floor of 480x360 (`conf.lua` `minwidth`/`minheight`),
-under which the cards stop being readable at all. Mobile ignores it: those
-windows are fullscreen.
-
-### Page scroll
-
-Two columns fit any window the launcher is likely to open in; one stacked
-column does not. On a phone-shaped window the ROM card, SAVE FILES, Play and
-SAVE SLOT together run past the bottom, and a footer pinned to the window
-bottom painted over them with the overflow unreachable.
-
-So the whole column under the tab bar -- panel, updater banner, footer --
-scrolls as one page whenever it is taller than the room below the tab bar:
-
- The strip, logo and tab bar stay pinned, so navigation is always on screen.
-  Everything else draws at `contentTop - pageScroll` inside a scissor, and the
-  footer is laid out downward from `footerTop` right after the content instead
-  of upward from the window bottom.
- `RomImporter.pageScrollFor(naturalH, viewportH, scroll)` is the whole
-  decision, pure and pinned by `tests/engine/launcher_page_scroll.lua`. A
-  window that grows back drags the offset down with it, so the page can never
-  stay parked past its own end.
- The panels report their natural height as they draw (`_drawGamePanel` and
-  `_drawModsPanel` return it), so the decision reads the previous frame's
-  measurement -- the same one-frame settle the two lists already rely on.
- **One scroll axis at a time.** While the page scrolls, the panels draw
-  `paged`: the slot and mod lists take their natural height, keep no inner
-  scroll region and report a max of 0, so the wheel, the right stick and a drag
-  all move the page and never fight a list for the same gesture. Two-column
-  layouts do not overflow, `paged` stays false, and every one of these behaves
-  exactly as it did before.
- Hit testing follows the clip: `inside` (clicks) and `_ptIn` (hover) reject a
-  rect that scrolled out of the viewport, so a control that slid under the tab
-  bar cannot be clicked through it. Tab chips carry `pinned = true` and are
-  exempt. `pageScroll` resets on a tab change, each tab being a different
-  length.
- A press on empty background pans the page, resolved in `_updateSlotDrag` like
-  every other drag here.
-
-### Dragging on Android
-
-The launcher is handed no move events on any platform: `main.lua` forwards
-neither `touchmoved` nor `mousemoved` while it is up, which is why every drag
-here is resolved by polling inside `draw` instead. Desktop polls the mouse;
-Android used to poll nothing at all ("no reliable pointer polling" meant its
-mouse emulation), so it had no scroll gesture whatsoever -- fine while every
-scroll region was an inner list with a wheel alternative, useless the moment
-the page itself became the thing that scrolls, since a phone is exactly where
-it overflows.
-
-`love.touch` is pollable, so `_pointerHold` reads the first active touch there
-and hands `_updateSlotDrag` the same (held, y) pair the mouse gives on desktop.
-Consequences:
-
- Slot rows and mod toggles ARM on press and commit on release on Android too,
-  matching desktop, so a swipe that starts on a card scrolls instead of
-  selecting the row it started on.
- `touchPollable` (set once in `new`) gates all of it. Where `love.touch` is
-  missing, every Android path is exactly what it was: act on press, never arm,
-  no drag.
@@ -0,0 +1,54 @@
+# Linux ARM SBC Handhelds (PortMaster)
+
+Download `gen1recomp-*-sbc-portmaster.zip` from the [Gen1Recomp releases](https://github.com/bryanthaboi/gen1recomp/releases). This build targets 64-bit Linux ARM handhelds with PortMaster, including compatible H700 devices.
+
+## Install
+
+1. Unzip the release. It contains `gen1recomp-sbc.sh` and a `gen1recomp-sbc/` folder.
+2. Copy both as siblings into your device's PortMaster ports directory, commonly `Roms/Ports (PORTS)/` or `Roms/PORTS/`.
+3. Install PortMaster for your firmware and refresh the Ports list.
+4. Copy your legally owned canonical US Red or Blue `.gb` file into `gen1recomp-sbc/lovegame/`.
+5. Launch **gen1recomp-sbc** from Ports and choose the ROM.
+
+The pack includes `portable.txt`, so saves and ROM-derived cache remain beside the game on the SD card. The build never ships ROM-derived bytes.
+
+Canonical US cart SHA-1 values:
+
+- Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
+- Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
+
+## Controls
+
+| Input | Action |
+| --- | --- |
+| D-pad | Move cursor |
+| A | Click / confirm |
+| L1 / R1 | Switch tabs |
+| Start / Select | Play or choose ROM |
+
+In-game controls use the normal PortMaster/SDL mapping and can be rebound in **OPTIONS → CONTROLS**.
+
+## Runtime and suspend
+
+The package bundles PortMaster's LÖVE 11.5 aarch64 runtime. The launcher sources `control.txt`, calls `get_controls`, applies an optional CFW override, invokes `pm_platform_helper`, and calls `pm_finish` on exit. Paths are relative to the launcher, allowing different firmware mount points.
+
+Suspend/resume uses the existing LÖVE focus/visibility lifecycle: input is reset on focus loss and the game resumes when the window becomes visible again. Exact power-button behavior remains firmware-dependent; hardware validation has been performed on the TrimUI Brick, not every SBC or H700 device.
+
+## Building
+
+Release workflows build this automatically. Standalone builds resolve the latest published Gen1Recomp release by default:
+
+```sh
+./build-linux-arm-sbc.sh --version 0.1.75
+```
+
+For development, package a local checkout explicitly:
+
+```sh
+GEN1RECOMP_SOURCE_DIR="$PWD" ./build-linux-arm-sbc.sh --version 0.1.0
+# or: ./build-linux-arm-sbc.sh --source "$PWD" --version 0.1.0
+```
+
+The generated `port.json` records the source release tag. `install-linux-arm-sbc.sh` is a macOS helper for copying a built pack to a mounted SD card.
+
+PortMaster device support and runtime integration are maintained in the [PortMaster](https://github.com/PortsMaster/PortMaster-New) ecosystem.
@@ -0,0 +1,202 @@
+# Linux arm64 (aarch64) AppImage
+
+Releases ship `gen1recomp-<version>-linux-arm64.AppImage` alongside the
+existing x86_64 `gen1recomp-<version>-linux.zip`. It targets 64-bit ARM
+desktop Linux: Raspberry Pi 4/5 running Raspberry Pi OS, Armbian and other
+SBC distros, arm64 VMs on Apple Silicon, Ampere/Graviton desktops, and the
+aarch64 handhelds that run a full distro.
+
+> The Anbernic RG34XXSP has its own PortMaster-style pack
+> (`gen1recomp-*-rg34xxsp-stockos64-mod.zip`, see
+> [anbernic-rg34xxsp.md](anbernic-rg34xxsp.md)). That one bundles PortMaster's
+> LÖVE runtime and expects the device's own SDL; this AppImage is the generic
+> desktop-Linux artifact and shares nothing with it but the `game.love`.
+
+## For players
+
+```sh
+chmod +x gen1recomp-*-linux-arm64.AppImage
+./gen1recomp-*-linux-arm64.AppImage
+```
+
+Then use **Import ROM** in the launcher to point it at your own legal Red /
+Blue / Yellow cartridge dump, exactly as on every other platform.
+
+If your system has no FUSE (`dlopen(): error loading libfuse.so.2`), either
+install it (`sudo apt install libfuse2`) or run without it:
+
+```sh
+./gen1recomp-*-linux-arm64.AppImage --appimage-extract-and-run
+```
+
+### What the host has to provide
+
+Very little, and this is enforced by an assertion in the build rather than by
+good intentions. The only libraries the AppImage requires at startup are:
+
+```
+glibc 2.29+   libstdc++   libfreetype6   zlib
+```
+
+Everything else — OpenGL/Mesa, X11, Wayland, KMSDRM, ALSA, PulseAudio — is
+**dlopened**, so it is used when present and skipped when absent. That means
+one image runs on a full desktop, on a Wayland-only session, on a
+KMSDRM-only handheld with no X server, and on a box with ALSA but no
+PulseAudio, without a different build for each.
+
+That property does not come for free from Debian's packages, and getting it
+is most of what the build below is doing; see
+[Why five libraries are built from source](#why-five-libraries-are-built-from-source).
+
+## For builders
+
+```sh
+scripts/build_linux_arm64.sh --version 0.1.0
+```
+
+Output:
+
+```
+dist/linux-arm64/gen1recomp-<version>-linux-arm64.AppImage
+dist/linux-arm64/gen1recomp-<version>-linux-arm64.AppImage.sha256
+```
+
+Useful flags: `--game-love PATH` reuses an already-packed payload (CI does
+this so every platform ships identical bytes), `--rebuild-image` forces the
+builder container to rebuild, `--clean-cache` throws away the pinned
+downloads and the compiled LÖVE prefix.
+
+### Requirements
+
+An **aarch64 host** with **docker or podman**. A Raspberry Pi 5 is the
+reference machine (a cold build takes about 10 minutes on one — six libraries
+plus the engine; rebuilds reuse the cached prefix and take seconds). Apple Silicon with Docker
+Desktop and GitHub's `ubuntu-24.04-arm` runner both work too.
+
+The script refuses to run on x86_64 rather than falling back to qemu-user
+emulation: that path takes hours and has produced miscompiled LuaJIT.
+
+### Why this is not just another `scripts/build.sh` target
+
+`scripts/build.sh linux` downloads LÖVE's official `love-11.5-x86_64.AppImage`,
+unpacks its squashfs, drops `game.love` in, and glues it back together. That
+trick is not available here — **LÖVE publishes no aarch64 binary at all.** The
+11.5 release has win32, win64, macOS, Android, iOS and one x86_64 AppImage,
+and that is the entire list.
+
+So this build compiles LÖVE 11.5 from the official `linux-src` tarball and
+assembles the AppImage from scratch. Every pinned input — the LÖVE source, the
+five libraries built alongside it, and the AppImage type-2 runtime — is
+SHA-256 verified on the host before the container ever sees it, and the
+container itself runs with no network access.
+
+### Why the build happens in a Debian bullseye container
+
+glibc is backward compatible but not forward compatible: a binary linked
+against glibc 2.41 will not start on a system with 2.31, and there is no way
+to fix that after the fact. Compiling on the oldest base we support is
+therefore the only thing that makes one artifact work everywhere.
+
+Bullseye (glibc 2.31) is that base. The resulting binaries actually come out
+needing only **glibc 2.29** and **GLIBCXX_3.4.21**, so the AppImage covers
+everything from Ubuntu 20.04 and Raspberry Pi OS bullseye through current
+trixie.
+
+This is a statement about the *compile environment*, not about where the
+artifact runs — building on your own newer distro would silently raise that
+floor and strand every user on an older one, with no symptom until they
+download it. CI enforces the floor: `linux-arm64-build` fails if the highest
+required glibc symbol version climbs above 2.31.
+
+### Why five libraries are built from source
+
+SDL2, OpenAL, libtheora, libogg/libvorbis and libmpg123 are compiled rather
+than installed from bullseye. In every case the reason is *correctness*, not
+a newer version number — Debian builds these for a system where every
+dependency is installed and co-versioned, which is the opposite of an
+AppImage's situation. Each one broke the build in a different way, and all
+three failure modes are now assertions that fail the build instead of
+shipping.
+
+**1. Hard-linked backends (SDL2, OpenAL).** Debian's `libSDL2` lists
+`libpulse`, `libasound`, `libX11` and `libwayland-client` as `DT_NEEDED` —
+resolved by the loader at startup, not dlopened. An AppImage bundling it
+refuses to start unless the host has *all four*. It appeared to work in
+testing only because a desktop Pi has all four; a headless CI runner is what
+exposed it. Debian's OpenAL does the same via `libsndio`, which itself
+hard-links `libasound`. Built from source with `--enable-*-shared` and
+`ALSOFT_DLOPEN`, both dlopen their backends instead.
+
+**2. A stray link (libtheora).** Debian's `libtheoradec.so.1` is linked
+against `libcairo.so.2` — a packaging artifact, since a video decoder has no
+business drawing vector graphics — and cairo drags in X11, xcb, fontconfig
+and freetype. `--disable-examples` produces a `libtheoradec` needing only
+`libogg`.
+
+**3. SONAME collision with the host (ogg, vorbis, mpg123).** The subtle one.
+OpenAL dlopens ALSA, ALSA's config loads its PulseAudio hook plugin, and that
+plugin pulls the *host's* `libsndfile` into our process. `libsndfile` links
+`libogg`, `libvorbis` and `libmpg123` — the same three we bundle. The loader
+resolves a SONAME exactly once per process, so the host's `libsndfile` binds
+to *our* copies:
+
+```
+openal -> libasound -> libasound_module_conf_pulse -> libsndfile (host, new)
+                                                         `-> mpg123_info2 -> libmpg123 (ours, bullseye 1.26)
+```
+
+`mpg123_info2` arrived in mpg123 1.32, so the plugin failed to relocate, ALSA
+config collapsed, and the game ran with **no audio device at all**. Not
+bundling these instead would make `libogg`/`libvorbis`/`libmpg123` mandatory
+host packages; building them current means our copies *satisfy* the host's
+`libsndfile` rather than starving it.
+
+The same collision is why the font stack — freetype, fontconfig, libpng,
+brotli, zlib — is left to the host entirely. Bundling a bullseye freetype
+2.10.4 meant a host `libcairo` could not find `FT_Get_Transform` (added in
+2.11) and the game died at startup. Leaving the whole stack to the host keeps
+it self-consistent, while `liblove` — compiled against 2.10.4 — only ever
+asks for symbols every supported host already has.
+
+The general rule this all reduces to: **never bundle a library the host's own
+stack may also load, unless yours is at least as new as theirs.**
+
+### CI
+
+Three jobs, path-gated on `scripts/build_linux_arm64.sh`,
+`scripts/linux-arm64/`, `scripts/pack_love.sh` and this document:
+
+- **`linux-arm64-selftest`** (`ubuntu-latest`, x86_64) — offline gate. Checks
+  the pins are real digests on a dated tag rather than the moving
+  `continuous` one, that the Dockerfile still builds on bullseye, that the
+  exclude list still classifies known sonames correctly, that AppRun still
+  launches `game.love` with `--fused`, and that the host-arch guard actually
+  fires. Needs no container and no arm64 machine.
+- **`linux-arm64-build`** (`ubuntu-24.04-arm`) — the real build, then extracts
+  the artifact and asserts the layout, that every bundled object resolves
+  under AppRun's `LD_LIBRARY_PATH`, and that the glibc floor is still ≤ 2.31.
+  Uploads the AppImage for 7 days.
+- **release** — `linux-arm64` runs on `ubuntu-24.04-arm`, reuses the shared
+  `game.love` from the `love-payload` job, and the AppImage is staged and
+  published like every other release asset.
+
+Unlike the Switch job, none of this needs secrets or self-hosted hardware, so
+it runs on fork PRs too.
+
+### Updating the pins
+
+Both pins live in `scripts/linux-arm64/common.sh`:
+
+- `LOVE_VERSION` / `LOVE_SRC_SHA256` — bumping any version invalidates the
+  cached prefix automatically (its name is keyed by every source version at
+  once, so a partial rebuild cannot mix vintages). Check that bullseye still
+  has `-dev` packages new enough for the new release; `build_appimage.sh`
+  asserts every optional module actually linked, because LÖVE's `configure`
+  exits 0 and silently drops a module when one is missing.
+- `SDL2_*`, `OPENAL_*`, `THEORA_*`, `OGG_*`, `VORBIS_*`, `MPG123_*` — the
+  source-built libraries. Bumping these is usually safe and occasionally
+  necessary: `libmpg123` in particular must stay at least as new as what a
+  target host's `libsndfile` expects, which is asserted for `mpg123_info2`.
+- `APPIMAGE_RUNTIME_TAG` / `APPIMAGE_RUNTIME_SHA256` — always a dated tag
+  from [AppImage/type2-runtime](https://github.com/AppImage/type2-runtime/releases).
+  The selftest fails the build if this ever points at `continuous`.
@@ -0,0 +1,862 @@
+# Mods and Gen 2 (Gold)
+
+The mod API is one API across both generations. Hook names, event names,
+registry names and the `mod.*` facade are shared on purpose: a mod that runs on
+Red should be able to run on Gold without learning a second vocabulary.
+
+What differs is how much of it Gold can actually serve, and that is why Gen 2
+support is something a mod **declares** rather than something it inherits.
+
+## What you can rely on today
+
+The short version, for an author deciding what to write:
+
+- **Every registry name, hook name and event name means the same thing in both
+  games.** Nothing is prefixed, renamed or repurposed per generation. Where Gen
+  2 genuinely carries more, the record or the payload gains a *field*.
+- **40 of the 46 registries are available on Gold.** 17 keep their Gen 1 target
+  outright (`commands`, `tokens`, `growth_rates`, `battle_sprite_scales` and
+  `render_pipelines` among them), 16 route to a Gen 2 table under the same
+  name, 6 are Gen 2-only systems Red has no counterpart for, and `migrations`
+  is a code registry with no data target in either game. The other 6 are gated,
+  and are listed below with the consumer change each one still needs.
+- **A registry with no home in a generation is reported, never silently
+  merged.** The write is taken, dropped, and named once per mod in the same
+  error feed the mod manager shows -- in both directions, so a Red boot writing
+  to `decorations` is told exactly as a Gold boot writing to `map_scripts` is.
+- **40 event names and 43 hook names have a call site in both generations**, so
+  one subscription serves both games. `tests/engine/gate_gen2_mod_api.lua`
+  reads those names back out of the source and fails if a site is renamed or
+  deleted on either side, and fails again if a new shared site appears without
+  being listed here.
+- **24 further names are Gen 2-only** (friendship, breeding, the Pokegear, the
+  radio, Pokerus, the roamers, Kurt, the Bug Contest, the Unown puzzle, mail,
+  held items, shininess, gender, and the five cards of the GS boot cinema).
+  They are plain names, not a `gen2.` namespace, so if Red ever grows the
+  system the name is already right.
+- **Every Gen 2 seam is guarded** by `Runtime.wants` / `Runtime.wantsHook`, so
+  a boot with no mod subscribed allocates nothing at any of them.
+- **A mod is loaded on Gold only if it says so.** See `gen2compat` below.
+
+`src/mods/Schemas.lua` is authoritative for routing;
+`tests/engine/gate_gen2_mod_api.lua` holds this document to it.
+
+## Declaring which games a mod is for
+
+```json
+{
+  "id": "my_mod",
+  "name": "My Mod",
+  "version": "1.0.0",
+  "entry": "main.lua",
+  "api": 2,
+  "games": ["gen1", "gen2"]
+}
+```
+
+`games` is an optional array of version ids (`"red"`, `"blue"`, `"yellow"`,
+`"gold"`), generations (`"gen1"`, `"gen2"`, case-insensitive) or `"all"`.
+`src/mods/ModTargets.lua` resolves the tokens off `GameVersion.ORDER` and
+`GameVersion.generation`, so nothing anywhere restates the game list.
+`Manifest.validate` stores the resolved, ORDER-sorted ids on `manifest.games`
+and **derives** `manifest.gen2compat` from them, which is the one field the
+loader's gate reads.
+
+Nothing moves on disk for any of this. A mod is installed once, into
+`mods/<id>/`, and that directory serves every game: there is no `mods/gen1/`
+and no per-generation copy. Targeting is declared, not filed.
+
+`"gen2compat": true` is the legacy spelling and is still accepted. It is purely
+additive -- it *adds* the Gen 2 games to whatever `games` says -- so no shipped
+manifest can lose a game it already ran on. A manifest with neither key is Gen
+1 only, which is exactly what it always meant. An unknown token warns and is
+dropped under `api` 1 and refuses the manifest under `api` 2; a `games` array
+that names no game this engine knows falls back to the default rather than
+orphaning the mod; a non-array `games` is a hard error.
+
+Every token is enforced, per game. `Loader:_gateGeneration` gates on
+`ModTargets.supports(manifest, version, generation)`, the same call both mod
+surfaces make, so `"games": ["blue"]` really does not load on Red and the
+loader's skip line is the launcher's line, `For Blue, not Red`. A manifest with
+no `games` and no `gen2compat` still covers every Gen 1 game, so nothing
+written before the key existed changes behavior.
+
+On a Gold boot, a mod claiming no Gen 2 game is **not loaded at all**: no
+registrations, no subscriptions, no entry chunk. The manager still lists it,
+showing `ENABLED (NOT THIS GAME)` and the reason, and the player's enable flag
+is left alone so it comes straight back on Red.
+
+Both mod surfaces derive what they show from `ModTargets` rather than from
+their own copy of the rule. The launcher's mod panel carries a `Show for:` game
+chip row and a per-mod tag (`GEN 1`, `GEN 1+2`, `RED/GOLD`), greyed with `Not
+for this game` and the detail `For Gen 1, not Gold` when the mod does not run
+on the selected game; the in-game manager shows the same verdict as
+`ENABLED (NOT THIS GAME)` plus an inert `FOR GEN 1+2` row on the detail screen.
+The launcher asks the same question of a mod's dependencies: one whose hard
+dependency does not run on the selected game reads `Needs <id> (not for Gold)`,
+matching the loader's contagious skip.
+
+A separate overlay, `options.modsByVersion[version][id]`, holds each game's
+enable flag. The launcher shows a coloured Red / Blue / Yellow / Gold checkbox
+for every installed mod, and the loader and in-game manager read the same
+game-specific answer on the next boot. On the first launch after this feature,
+the existing shared state is copied to every game, so a mod that was enabled
+remains enabled everywhere; after that, changing one checkbox affects only
+that game. New mods still default to enabled on every game (experimental mods
+retain their explicit opt-in default).
+
+That is deliberate. Gold reimplements the battle engine, the overworld, the
+script VM and the save format, so a Gen 1 mod dropped into a Gold boot would
+find a small fraction of its call sites live. A mod that half-applies reads to
+a player as a broken mod. Not running is the honest state, and naming a Gen 2
+game is the author saying "I have tested this there".
+
+Adding a Gen 2 game does not opt out of anything on Gen 1, because `games` is a
+union: `["gen1", "gen2"]` covers everything it covered before. What does change
+is that the gate now runs on a Gen 1 boot too, so a manifest that names *only*
+Gen 2 games no longer loads on Red, Blue or Yellow. Say `["all"]` or list both
+generations if you want both.
+
+Two riders. **A hard dependency that does not run here takes the dependent down
+with it** (unless scoped to specific games, e.g.
+`dependencies: [{ id = "x", games = ["gen2"] }]`), as a skip rather than a
+failure and carrying the dependency's own wording (`depends on X, which does not
+run here (For Blue, not Red)`), so the whole chain has to cover the same games.
+And **the claim is yours, not the last word**: it is the manager's `TRY HERE ANYWAY` row that lets a player run a mod
+whose author never opted in, which is the only route for a mod written before
+the field existed. The override is per game -- `options.modsGen2[id]` is a
+`{ [version] = true }` table, so forcing a mod onto Red does not force it onto
+Gold, and a legacy `options.modsGen2[id] = true` reads as "the Gen 2 games",
+the only set it could ever have affected. It applies on the next boot; a forced
+mod loads normally and keeps a note saying it was never verified here. Where
+the choice cannot be persisted the manager says `COULD NOT SAVE` instead of
+promising a restart.
+
+If you are writing new code, still prefer the API: take the live game from
+`mod.game` (or the `game.ready` payload, or a `ui.*` hook's first argument) and
+the world from `mod.world`. Those are the names that mean the same thing in
+both games. What follows is for the mods that were written before Gold existed
+and reach past it.
+
+## Gen 1 module facades
+
+A mod with `engine_internals` reaches engine modules by name, and under Gold
+those names used to resolve to Gen 1 modules nothing instantiates -- so the
+patch landed on dead code and the mod was inert with no symptom but silence.
+
+On a Gen 2 boot, **a require made from a mod's own chunk is answered by an
+adapter**: the Gen 1 API, backed by Gen 2 internals. `src/mods/Gen2Compat.lua`
+is the table, `src/mods/Loader.lua`'s require shim is where the swap happens,
+and `tests/engine/gate_gen2_mod_facade.lua` holds both to it. Engine code is
+not affected -- the shim only substitutes when the calling chunk is outside the
+engine tree, so `src/render/PaletteFX.lua` still gets the real Gen 1 module on
+both generations.
+
+Fifteen names are served. **alias** means the adapter *is* the Gen 2 module, so
+a monkey-patch, a `rawset` sentinel and a `getmetatable(x) == M` check all land
+on the table Gold runs; **facade** means a translating wrapper over it.
+
+| the Gen 1 name a mod requires | kind | what it gets on Gold |
+| --- | --- | --- |
+| `src.core.Game` | facade | a live proxy onto the Game2 instance |
+| `src.world.OverworldController` | facade | over `src/world/gen2/World.lua`; `World:step` / `:interact` / `:interactBody` dispatch through it |
+| `src.world.Map` | alias | `src/world/gen2/Map.lua`, grown Gen 1's statics and instance methods |
+| `src.world.NPC` | alias | `src/world/gen2/Npc.lua`; `NPC.new` sniffs the Gen 1 argument order |
+| `src.pokemon.Boxes` | facade | over `src/core/gen2/Boxes.lua`, plus Gen 1's `COUNT` / `CAPACITY` / `ensure` / `active` / `deposit` |
+| `src.battle.BattleState` | facade | over `src/ui/gen2/BattleState.lua`, write-through |
+| `src.ui.PartyMenu` | facade | over `src/ui/gen2/PartyMenu.lua`, write-through |
+| `src.world.WorldAPI` | alias | `src/world/gen2/WorldAPI.lua` |
+| `src.world.PikachuFollower` | alias | `src/world/gen2/Follower.lua` |
+| `src.script.ScriptRunner` | facade | over `src/script/gen2/Vm.lua` |
+| `src.ui.OptionsMenu` | facade | over `src/ui/gen2/OptionsMenu.lua`, write-through |
+| `src.world.FieldDefaults` | facade | the `playerSprites` answer, and a named refusal for the rest |
+| `src.world.Collision` | facade | `DELTA` / `target` / `occupied` / `canMove` |
+| `src.ui.StartMenu` | facade | over `src/ui/gen2/StartMenu.lua`, write-through |
+| `src.ui.BoxMenu` | alias | `src/ui/gen2/PcMenu.lua` |
+
+Two entries in that table are not the pairing they look like.
+`src.ui.BoxMenu` resolves to `PcMenu`, not to `src/ui/gen2/BoxMenu.lua`: Gen 1's
+`BoxMenu` is Bill's PC *top menu*, whose Gold counterpart is `PcMenu`, while
+Gold's `BoxMenu` is the withdraw/deposit *list* Gen 1 builds inline. And
+`src.script.ScriptRunner` is served narrowly rather than fully: `scanLabels`
+and `validate` forward verbatim, with the default verb lookup swapped to
+`game.data.commands` so a script of Gen 1 built-ins cannot validate clean and
+then run as nothing, while the lifecycle half is a thin handle onto the one
+`world.vm` with `resume` and `update` refused rather than double-driving it.
+The `script.started` / `script.ended` / `script.command` seams are the
+supported route and already work on Gold.
+
+`src.script.Commands` and `src.ui.OptionRows` have **no** adapter and are the
+two names a require of which still lands in the boot error feed the manager
+shows, with the module named. Both load fine under Gold and both are traps: the
+first hands back 61 Gen 1 verbs none of which Gold can run, the second paints
+Red's four-box options chrome over Gold's single 18x16 one.
+
+`docs/preparing-your-mod-for-gen2.md` is the migration guide for an author
+working through this, and `python3 tools/modkit.py gen2check <id>` reports a
+mod's own findings against the coverage table below.
+
+Three rules the adapters keep, because a plausible wrong answer is worse than
+the module being missing:
+
+- **Live, never a snapshot.** A mod captures `require("src.core.Game")` at file
+  scope, before a save or a world exists. The facade is a proxy that reads the
+  live instance on every touch, so `Game.save` is nil during the entry chunk
+  and correct forever after. It aliases the two names Gold spells differently
+  (`Game.overworld` is `Game2.world`, `Game.writeOptions` is
+  `Game2:persistOptions`) and the one data table that was renamed
+  (`game.data.sprites` is `data.gen2Sprites`).
+- **A member with no backing says so.** `game.data.field` does not exist on
+  Gold, so it reads nil *and* logs once, naming the mods holding the facade.
+  `BattleState.newWild` is absent rather than invented, because a `newWild`
+  that took a species and a level would be a lie about what Gold's battle
+  screen is.
+- **One stable table for the run.** Where the Gen 2 arm can serve the name
+  outright the adapter *is* that module, so a mod's monkey-patch, its
+  `rawset` sentinel and its `==` idempotency check all land on the table Gold
+  actually runs.
+
+### What the adapter says it covers
+
+The adapter publishes its own coverage, versioned by
+`Gen2Compat.COVERAGE_VERSION` (1), and `modkit gen2check` consumes that table
+rather than a second copy of the same knowledge:
+
+```lua
+Gen2Compat.modules()                            -- the 15 names, sorted
+Gen2Compat.serves(name)                         -- boolean
+Gen2Compat.memberStatus(name, member)           -- "backed" | "warned" | "absent" | nil
+Gen2Compat.coverage(name)                       -- a fresh table per call:
+--   { module, kind = "facade"|"alias", target, members = { [name] = status },
+--     notes = { [name-or-topic] = "one line" } }
+```
+
+The status vocabulary is frozen at three values, and a member listed as both
+resolves to the weaker claim:
+
+| status | means |
+| --- | --- |
+| `backed` | present, and it does the Gen 1 job on Gold |
+| `warned` | present, answers nil or degrades, and names itself once with the mod attributed |
+| `absent` | deliberately not served; a nil read is the honest failure |
+
+Today that is 291 backed, 32 warned and 161 absent across the fifteen modules.
+`notes` keys are documentation topics rather than a member list -- dotted paths
+(`save.money`), field names (`warpAt`), hook names (`hook ui.pc.items`) and
+bare topics (`identity`, `iteration`, `rawset`) all appear there. `members` is
+the authoritative set, and a member it does not record is not a promise either
+way: on an alias it resolves to whatever the Gen 2 module has, on a
+write-through facade it falls to the Gen 2 class, on the `src.core.Game` facade
+it reads nil and says so, and on the `src.world.OverworldController` facade it
+reads nil silently.
+
+**The follower.** Gold's cart has no trailing companion at all, so
+`src/world/gen2/Follower.lua` is new Gen 2 code rather than a facade: the
+entity, the trail loop, and a `shouldSpawn` a mod replaces. `World:step` calls
+`Follower.update(game, world)` once per logic frame after the body, and
+`World:setMap` calls `Follower.onMapEntered` before it emits `map.entered` --
+the same two call sites `src/world/OverworldController.lua` gives the Gen 1
+arm, which is what makes a Gen 1 follower mod's wrappers tick.
+
+Vanilla never spawns one: `shouldSpawn` answers false until something replaces
+it. `Follower.setShouldSpawn(fn)` is the supported way, and it writes the same
+file-local the Gen 1 mods reach through `debug.setupvalue` on the upvalue named
+`shouldSpawn`, so the two cannot disagree.
+
+Two Gen 2 engine changes came with it, both general rather than follower-only:
+an entity with `passable` set never blocks a step (the Gen 1 name and meaning,
+`src/world/Collision.lua`), and `World:rebuildPeople` now preserves **guests** --
+anything in the people list it did not put there. A rebuild runs on every zoom
+and every time-of-day roll, so without that a follower vanished at the top of
+the hour.
+
+**What the facades cannot fix.** A mod that allow-lists version strings
+(`GameVersion.get() == "red" or ...`) excludes itself from Gold by construction,
+and no adapter should special-case it. Neither is a Gen 1 screen id: Gold's
+builtins carry a `Gen2` prefix, so a mod matching `id == "BoxMenu"` matches
+nothing. A write to a field on a live Gen 2 menu instance is inert where Gen 1
+read it back (`menu.onSwitch`, `menu.swapFrom`, `StartMenu`'s box geometry),
+and `map.warpAt` is a name collision rather than a rename -- Gen 1's is a table
+keyed by cell, Gold's is a method, so indexing or iterating it raises. All of
+these are mod-side edits, each with a route that works on both generations;
+`docs/preparing-your-mod-for-gen2.md` walks through them.
+
+## What works on Gold today
+
+**Screens.** The `screens` registry serves both generations. Gold's screens
+are registered under `Gen2`-prefixed ids so a mod that replaces Gold's party
+menu does not also replace Red's; `Screens.GEN2_IDS` in `src/ui/Screens.lua`
+is the full list. Every screen Gold opens goes through an id, including the
+boot cinema and the START menu.
+
+**Asset overrides.** `overrides/` shadowing and asset transforms work
+unchanged: Gold's screens load art through `src/render/Assets.lua`, the same
+choke point Gen 1 uses.
+
+**Content registries at the shared path.** `pokemon`, `moves`, `items`,
+`type_chart`, `strings`, `font`, `screens`, `commands`, `tokens`,
+`growth_rates`, `battle_sprite_scales`, `render_pipelines`, and the audio
+family (`audio`, `music`, `sfx`, `cries`, `map_songs`). These keep their Gen 1
+target path, so one mod source targets both generations.
+
+The last two are the newest and each carries one caveat worth stating before
+you write against it:
+
+- **`battle_sprite_scales`.** `src/ui/gen2/BattleState.lua:imageScale` walks
+  the merged table for a record whose `path` matches the pic being drawn,
+  skipping the registry's own `_owners` row, and `picScale` falls through to
+  the species record's `battleScaleFront` / `battleScaleBack` after it -- the
+  same image-then-species-then-default order Gen 1 resolves in. Because the key
+  is the asset path it also reaches the pics that are nobody's species: the
+  player's trainer back, the DUDE's, an opponent's frontpic. The **default**
+  differs and is not a registry record either side: Red's 32x32 back pics draw
+  at 2x, Gold's 48x48 ones fill their 6x6 box at 1x, so a scale that looks
+  right on Red is twice as large on Gold. At any scale the pic stays centred in
+  its box and standing on the same ground line.
+- **`render_pipelines`.** `src/core/Game2.lua:load` installs
+  `src/render/Pipelines.lua` on Gold's dataset *after* `mods:load`, so the
+  merged table is the one it walks, and `Game2:draw` composites the
+  whole-frame half through `Pipelines.wantsPresent` / `Pipelines.present` with
+  the Gen 1 ctx keys (`width`, `height`, `scale`, `dpi`, `dpiX`, `dpiY`). The
+  **`drawWorld` half is inert on Gold**: its overworld draws straight to the
+  window rather than into a canvas the way `src/world/OverworldController.lua`
+  hands one to `Pipelines.drawWorld`. A drawWorld-only pipeline is not left
+  switched on and drawing nothing -- `Game2:load` retires a restored level for
+  one, leaving `options.pipelines` untouched so the mode comes back the day
+  Gold grows a world canvas. Gold also has no OPTION row for a pipeline
+  (`Pipelines.rows` is read only from `src/ui/OptionsMenu.lua`), so a Gold
+  player reaches one by its `hotkey`.
+
+**Content registries at a Gen 2 path.** `maps`, `tilesets`, `sprites`, `text`,
+`encounters`, `trainers`, `palettes`, `icons`, `battle_anims`, `constants`,
+`statuses`, `move_effects`, `item_effects`, `balls`, `ai_classes` and
+`evolution_methods`. Same registry name, same verbs, a Gen 2 table underneath
+(`data.gen2Maps`, `data.gen2Encounters`, `data.gen2Statuses`, ...).
+`src/core/Game2.lua` loads the extracted ones into `game.data` before it
+calls `mods:load`, and every consumer takes them by reference and never
+copies, so what a mod merges is what the game walks: a registered map is a map
+Gold can warp into, a patched tileset is the one `Map.new` reads, a patched
+encounter table is the one the grass rolls.
+
+The battle-rule six are the newer half and work slightly differently: there is
+no table on disk for them at all. They come into existence *as* the merge, and
+each consumer reads a record through a lookup that falls back to its own module
+records when no loader ran, so a mod-free Gold boot behaves identically:
+
+| registry | who reads it |
+| --- | --- |
+| `statuses` | `Battle.statusRecordFor` / `statusPenaltyFor`, `Catching.statusBonus`, `ItemEffects.healClassOf` |
+| `move_effects` | `Battle.moveEffectRecordFor` (`useMove`'s dispatch) |
+| `balls` | `Catching.recordFor` |
+| `ai_classes` | `Ai.layersFor` (the ten `scoring.asm` passes, plus mod layers) |
+| `evolution_methods` | `Evolution.methodFor` |
+| `item_effects` | `ItemEffects.recordFor` / `partyAction` |
+
+`src/mods/Builtins.lua` seeds those six with **Gold's** records under Gen 2
+rather than Red's. It has to: both games call it `GREAT_BALL`, and Red's record
+carries no `multiplier`, so seeding Red's would leave Gold's x1.5 reading nil.
+
+**Content registries that exist because Gold does.** Six systems Red has no
+counterpart for, so there is no Gen 1 table to share and none of these carries
+a Gen 1 target at all. The routed Gen 2 path is their only home, and
+`Schemas.GEN1` gates them on a Red boot the way `Schemas.GEN2` gates
+`map_scripts` on a Gold one -- reported, not silently merged.
+
+| registry | id space | who reads it |
+| --- | --- | --- |
+| `held_items` | item ids | `ItemEffects.heldItemFor`; the merged rows are written back onto `data.items` for `Battle:itemDef` |
+| `phone_contacts` | `PHONE_*` (`data.gen2Constants.phoneContactOrder`) | `Phone.useRegistry`, folded onto the contact table |
+| `decorations` | `"deco:<n>"` | `Decorations.attributes`, the single read point for an attribute row |
+| `apricorns` | apricorn item ids | `Apricorns.useRegistry`, which rebuilds all three lookups and Kurt's menu order |
+| `landmarks` | `LANDMARK_*` | `Nests.landmarkId` / `Nests.landmark`, which resolve a map header's landmark byte |
+| `radio_channels` | station ids | `MapRadio.channelRecord`, which puts a registered station on the dial |
+
+`Game2:load` calls `Phone.useRegistry`, `Decorations.useRegistry`,
+`Apricorns.useRegistry` and `ItemEffects.applyHeldItems` immediately after
+`mods:load`, so the merge is live before the first frame. `landmarks` and
+`radio_channels` need no such call: their consumers take `data` at call time.
+
+`landmarks` merges onto the cache's own `gen2Landmarks.landmarks` and
+`held_items` onto the view `Game2` builds from `data.items`, so both fold
+against the vanilla row -- a `register` for an existing id collides, a
+`patch` stacks. The other four come into existence as the merge, seeded from
+their module's literals by `src/mods/Builtins.lua`.
+
+Four honest limits on that surface:
+
+- `held_items` reaches the battle by being written back onto `data.items`, so a
+  held row for an id with no `data.items` record lands nowhere. To invent a
+  held item, register the `items` record too. The write-back is a diff against
+  a pre-merge snapshot, which is what lets `items` and `held_items` compose
+  instead of one reverting the other.
+- `decorations` ids are `"deco:<n>"`, not `DECO_*` names: the cart's decoration
+  constants are a bare `const_def` block with no name table behind them, so
+  there is nothing in the ROM to spell them by. `battle_anims` addresses its
+  unnamed rows the same way. `n` is the attribute row's index, which is
+  `wMenuSelection`.
+- `phone_contacts` does not register the four `PHONE_UNUSED` `const_skip` holes
+  (contact bytes 8, 9, 10 and 25). The manifest gives all four the same id, and
+  one id cannot key four rows. They stay copies of the wrong-number filler,
+  which is what the cart does with them.
+- `radio_channels` and `phone_contacts` register *content*, not new UI: a
+  registered station gets a dial position and a name, and a registered contact
+  gets a row the Pokegear indexes, but neither invents a screen.
+
+**Record shapes.** A registry whose Gen 2 records genuinely differ carries a
+Gen 2 schema beside its Gen 1 one (`gen2Fields` / `gen2Keys` / `gen2Write` in
+`src/mods/Schemas.lua`, resolved by `Schemas.shapeFor`). The registry name, the
+verbs and wherever possible the ids stay shared; only the record changes. The
+differences an author meets:
+
+- **`pokemon`.** Gen 2 splits `special` into `specialAttack` /
+  `specialDefense`, names the level-up table `levelMoves` and the pic size
+  `picSize`, has no separate `level1Moves`, and points an evolution at `into`
+  rather than `species`. It also carries the breeding block (`eggGroups`,
+  `eggMoves`, `eggSteps`, `genderRatio`) and the wild held-item pair.
+- **`encounters`.** The id is the encounter *kind*, not the map:
+  `mod.content.encounters:patch("grass", { ROUTE_29 = { rates = { NITE = 40 } } })`.
+  A map's row carries a `rates` set per time of day and one slot list.
+  `fishGroups`, `trees` / `treeSets`, `rocks`, `bugContest` and `roamMaps` are
+  ids of their own.
+- **`trainers`.** The id is the trainer *class*, and the record is
+  `{ name, index, attributes, baseMoney, encounterMusic, trainers, items }`,
+  with one entry per named trainer of the class. The registry writes one level
+  in, into `data.gen2Trainers.classes`, so the call shape is unchanged.
+- **`icons`.** Two id forms in one registry, routed by the `ICON_` prefix a
+  sheet name carries: a species id names an assignment (a string, the sheet's
+  name), an `ICON_*` id names a sheet.
+- **`palettes`, `battle_anims`, `constants`.** The id is a subtable of the
+  target: `pokemon` / `trainers` / `bg` / `objects` / `roofs` for palettes,
+  `scripts` / `moves` / `objects` / `framesets` / `oamsets` / `gfx` for
+  battle_anims, and one of Gold's 42 ordered ROM name lists (plus `mapGroups`,
+  `trainerClassMembers`, `types`) for constants. Those lists are ordered and
+  position *is* the id a script byte resolves through, so they replace rather
+  than append.
+
+Four more id-space notes, because the records at those paths came out of a
+Gen 2 ROM:
+
+- Gold's `text` ids are ROM pointer strings such as `"55:4067"`, not the
+  `TEXT_*` names Red uses. `override` them by pointer; there is no name table.
+- A Gen 2 tileset carries its walkability as `collision` where Gen 1 says
+  `walkable`. Both fields validate; only `collision` is read on Gold.
+- A Gen 2 warp row carries `destGroup` / `destMapNum` beside the `destMap` /
+  `destWarp` pair Gen 1 also has. Both are optional in the shared schema, so a
+  Gen 1 warp row and a Gen 2 one both validate, and patching one of Gold's own
+  maps does not mean restating the ROM's map-group numbers.
+- Gold writes `"burn"` / `"sleep"` into `mon.status` where Red writes `BRN` /
+  `SLP`. The `statuses` registry is the same registry; only the ids differ, and
+  they have to.
+
+**`mod.commands`.** Works on Gold. `src/script/gen2/Vm.lua` runs the cart's own
+bytecode, so there is no opcode byte to hand a mod -- the seam is a row the
+cart cannot write. `Opcodes.MOD_COMMAND` (`"modcommand"`) is an op *name* with
+no byte behind it, and the VM dispatches it through the same merged
+`data.commands` table Gen 1's runner resolves by name. Two row shapes reach it:
+
+```lua
+{ op = "modcommand", verb = "mymod:shake", args = { 4, 2 } }   -- native
+{ "mymod:shake", 4, 2 }                                        -- Gen 1 row
+```
+
+The second is the Gen 1 row shape verbatim, so one row list can serve both
+games as long as every row in it is the mod's own verb. The handler is called
+`fn(ctx, unpack(args))` with `ctx.vm` where Gen 1 has `ctx.runner`; it may
+block on `ctx.vm:showText` / `:waitFrames`, and its return value speaks Gen 1's
+control vocabulary (`"end"`, a row number, or nil). A missing or raising verb
+is warned once per name and the rest of the list still runs. The engine's own
+Gen 1 verbs are **not** seeded on Gold: a row-list verb handed Gold's ctx would
+find no runner on it, so `data.commands` under Gen 2 is the mod verbs alone.
+
+**`mod.save`, `mod.options`, `mod.log`, `mod.assets`, `mod.find`, exports.**
+Generation-agnostic; nothing to adapt.
+
+**`mod.world`.** Same method set, resolved against Gold's world
+(`src/world/gen2/WorldAPI.lua`). Two differences show through and are
+documented on the module: Gold's world is not a stack state, and Gen 2 event
+flags are numeric ids into `wEventFlags` rather than string keys.
+`mapOverview` returns the same read-only terrain, tile-shading, and marker
+shape, using Gold's live object masks and event flags to omit collected items.
+`spawnNpc` / `removeNpc` append onto the map def's own object list, the way the
+Gen 1 arm does, so a spawned actor is pooled, drawn, walked and talked to like
+an extracted one and survives a map reload; it is not serialized, so a mod
+respawns on `map.entered`. `queueScript` takes a small allowlist of verbs Gold
+has its own entry points for (`start_battle "wild" species level`, `warp`,
+`text`, `setflag`, `clearflag`) and refuses a list containing anything else
+**by name, before the first row runs**, so a mod never gets a half-run queue.
+`marchInPlace` still has no Gen 2 equivalent (the Gen 2 movement stream has no
+byte for it) and returns `nil, reason` rather than approximating one.
+`availableFieldActions` and `useFieldAction` expose the same contextual field
+item and move records in both games. Gold extends the shared ids with its own
+`headbutt`, `whirlpool`, `waterfall`, `sweet_scent`, and `squirtbottle`
+actions. Each engine keeps ownership of its inventory, badges, terrain,
+surfing, bike, fishing, and field-move rules.
+
+**Hooks and events that fire on Gold.** Every name below is the Gen 1 name
+carrying the Gen 1 payload keys, because Gold's call sites reuse them rather
+than defining a parallel vocabulary; where Gen 2 carries more, the payload
+gains a field instead of the name gaining a prefix.
+
+- *Engine-wide, from the shared modules:* `game.ready`, `screen.pushed`,
+  `screen.popped`, `screen.render_visible`, `music.started`, `music.stopped`,
+  `music.select`, `music.volume`, `sound.played`, `zoom.range`,
+  `assets.transformed`, `mods.loaded`, `mod.options_changed`.
+- *Overworld (`src/world/gen2/`):* `map.entered`, `map.exited`,
+  `map.reloaded`, `player.warped`, `world.stepped`, `world.interacted`,
+  `world.npc_spawned`, `world.trainer_engaged`, `world.blacked_out`,
+  `world.block_replaced`, `world.boulder_moved`, `world.tod_changed`,
+  `world.object_toggled`, `flag.changed`; hooks `warp.destination`,
+  `movement.collision`, `movement.speed`, `encounter.roll`,
+  `encounter.species`, `encounter.fishing`, `world.tod`, `map.palette`,
+  `fieldmove.eligibility`. `flag.changed` carries the numeric `wEventFlags`
+  id under Gen 1's `name` key, which is the one payload difference the
+  numeric flag space forces.
+- *Menus (`src/ui/gen2/`):* `ui.start_menu.items`, `ui.title_menu.items`,
+  `ui.options.rows`, `ui.party.submenu`, `ui.naming.grid`, `ui.pc.items`,
+  `ui.list_menu`, `transition.style`. `ui.list_menu` covers Gold's script
+  menus (`ScriptMenu.lua`); the `Chrome.List` widget the START and title
+  menus draw with does not raise it yet, so those two are composed through
+  their own hooks only.
+- *The Oak speech (`src/ui/gen2/OakSpeech.lua`):* `intro.oak_speech.started`,
+  `intro.oak_speech.step`, `intro.oak_speech.answered`,
+  `intro.oak_speech.finished`, and the `intro.oak_speech.build` hook. Gold has
+  a real Oak speech, so it is the same extension point rather than a second
+  one: same names, same payload keys, same moments in the sequence. The beats
+  are a data table with the same step vocabulary (`say` / `pic` / `name` /
+  `choice` / `yesno` / `shrink` / `fn`, plus Gold's own `initclock` and
+  `demo`), and the step *ids* match Gen 1's wherever the moment is the same --
+  `oak_welcome`, `demo_mon`, `world_spiel`, `ask_player_name`, `name_player`,
+  `legend`, `shrink` -- so `ModUI.insertStepBefore(steps, "name_player", ...)`
+  lands in the right place in both games. The two ids with no Gen 1
+  counterpart are Gold's own beats, `init_clock` (the `farcall InitClock` the
+  speech opens with) and `oak_study` (the return to Oak for `_OakText5`). Gold
+  has no rival-naming or name-confirmation beats, so it raises no anchors for
+  them: the rival is named by `CopScript` in `maps/ElmsLab.asm`, hours later.
+- *Battle (`src/battle/gen2/`):* `battle.started`, `battle.ended`,
+  `battle.turn_started`, `battle.turn_ended`, `battle.move_used`,
+  `battle.damage_dealt`, `battle.fainted`, `battle.status_inflicted`,
+  `battle.battler_switched`, `battle.ball_thrown`, `battle.exp_gained`,
+  `pokemon.level_up`, `pokemon.move_learned`; hooks `battle.damage`,
+  `battle.crit`, `battle.accuracy`, `battle.turn_order`,
+  `battle.enemy_action`, `battle.run`, `battle.exp_award`, `exp.gain`,
+  `catch.rate`, `trainer.party`, `battle.overlay`, `battle.low_health_alarm`,
+  `battle.catch_exp`, `battle.bottom_ui_visible` and
+  `battle.status_hud_visible`. One payload difference: Gen 1's vanilla
+  `battle.low_health_alarm` link reads `ctx.battle.data`, and Gold's battle
+  screen has no `.data` field, so the Gen 2 site **adds** `ctx.data` beside the
+  Gen 1 keys. A mod that calls `nextFn` is unaffected; one that reaches through
+  `ctx.battle.data` instead gets nil on Gold.
+- *The catch and the evolution:* `pokemon.caught`, `pokemon.evolved`; hook
+  `evolution.check`. `src/ui/gen2/BattleState.lua:pushCaught` emits
+  `pokemon.caught` once the mon is in the party or the box, and
+  `src/core/gen2/Evolution.lua` emits `pokemon.evolved` from `apply` and wraps
+  each row's decision in `evolution.check`. The hook passes `data` where Gen 1
+  passes `game`; positions 2-4 (mon, row, trigger) match.
+- *The frame (`src/core/Game2.lua`):* hooks `input.step`, `input.pointer`,
+  `render.zones`, `render.compose`, `render.output_enabled`, `render.output`,
+  `render.letterbox`, `render.hud`. Each sits
+  at the same moment `src/core/Game.lua` and `src/render/Renderer.lua` raise it
+  -- the logic tick before the pad is read, a pointer the touch overlay gets
+  first refusal on, the palette zone list handed to the present pass, the
+  composed frame before GBCFX, the letterbox, and the finished playfield rect
+  -- and carries the same payload.
+  `render.hud`'s `gameX` / `gameY` really is where Gold's dialogue boxes and
+  menus land, because `Chrome.fitScale` / `fitOrigin` and `World:fitScale`
+  compute the same number. `render.zones` is handed `nil` in GBC mode (Gold
+  computes no zone of its own there) and the engine's own one-rect list in
+  CLASSIC mode; a rect that clamps to nothing is skipped rather than throwing,
+  which is what `src/render/Renderer.lua:scissorClamped` does on the Gen 1 side.
+- *Sprites (`src/pokemon/Sprites.lua`, shared):* `pokemon.sprite`,
+  `pokemon.icon` and `player.sprite`. `pokemon.icon` is reached from
+  `src/ui/gen2/PartyMenu.lua` through the shared module, so it is one call site
+  serving both games. `player.sprite` is raised by `Sprites.playerPic`, which
+  Gold's battle back pic (`src/ui/gen2/BattleState.lua`), Hall of Fame and
+  intro call with an already-resolved path: Gold's trainer art is not in
+  `field.playerPics`, so the path is found first and the hook raised over it,
+  with the Gen 1 `ctx` keys (`side`, `kind`, `demo`, `battle`, `data`)
+  unchanged. The Gen 2 trainer card is the one player-art read still outside
+  it: its portrait is a tile sheet that also carries the frame tiles, not a
+  swappable pic.
+  `pokemon.sprite` has a second site of its own in
+  `src/ui/gen2/BattleState.lua`, which adds `letter` (Unown) and `shiny` to the
+  Gen 1 ctx keys -- both concepts Red does not have.
+- *Save and the script VM:* `save.created`, `save.loaded`, `save.loading`,
+  `save.writing`; hooks `save.write`, `save.new_game`, `script.command`, and
+  the `script.started` / `script.ended` pair off `src/script/gen2/Vm.lua`.
+  `script.command` reports a mod's own row under the name `"modcommand"` with
+  the row's real operands, and may rewrite them, on the same path it wraps a
+  cart row.
+
+## New in Gen 2
+
+These have no Gen 1 analogue -- Red has no friendship byte, no day care egg,
+no Pokegear, no radio, no held items -- so they are the only places a new name
+is justified. They are **live**, guarded by `Runtime.wants` /
+`Runtime.wantsHook`, and each is driven through a real bus by
+`tests/engine/gen2_new_seams.lua`.
+
+### Events
+
+| event | raised from | payload |
+| --- | --- | --- |
+| `happiness.changed` | `Happiness` (`ChangeHappiness`, `StepHappiness`) | `mon`, `event`, `reason` (`"event"` / `"step"`), `delta`, `from`, `to` |
+| `breeding.egg_created` | `Breeding` (`DayCare_InitBreeding`) | `egg`, `mother`, `father`, `compatibility`, `stepsToEgg` |
+| `egg.hatched` | `Breeding` | `mon`, `egg`, `slot`, `species`, `nickname` |
+| `phone.call_received` | `PhoneRing.script` | `call`, `contact`, `name`, `className`, `special`, `scriptKey` |
+| `clock.day_changed` | `Clock` | `day`, `previous`, `reason` |
+| `pokerus.infected` | `Pokerus` | `party`, `slot`, `mon`, `strain`, `days`, `source` |
+| `roamer.moved` | `Roamers` | `index`, `slot`, `species`, `from`, `to`, `reason` |
+| `roamer.encountered` | `Roamers` | `index`, `slot`, `species`, `level`, `mapId` |
+| `apricorn.converted` | `Apricorns` (Kurt) | `apricorn`, `ball`, `event` |
+| `bug_contest.scored` | `BugContest` | `mon`, `score`, `place`, `results` |
+| `unown.unlocked` | `Unown` (`UpdateUnownDex`) | `letter`, `name`, `word`, `count` |
+| `radio.channel` | `MapRadio` | `station`, `channel`, `name`, `source` |
+| `mail.written` | `Mail` | `entry`, `slot`, `mon`, `message`, `author`, `source` |
+| `mail.read` | `Mail` | `entry`, `message`, `author`, `top`, `bottom` |
+| `intro.boot.copyright` | `CopyrightSplash:enter` | `screen`, `game` |
+| `intro.boot.gamefreak` | `GameFreakPresents:enter` | `screen`, `game` |
+| `intro.boot.movie` | `GoldSilverIntro:enter` | `screen`, `game` |
+| `intro.boot.movie_ended` | `GoldSilverIntro:finish` | `screen`, `game`, `skipped`, `frames` |
+| `intro.boot.title` | `TitleState:enter` | `screen`, `game` |
+
+The four `intro.boot.*` cards are the GS boot cinema, and they are the one part
+of Gold's intro with no Gen 1 moment to share a name with: Red boots into
+`IntroMovie` with no copyright card, no GAME FREAK splash and no attract movie.
+The Oak speech immediately after them is the opposite case and reuses
+`intro.oak_speech.*` verbatim (see the shared table above).
+
+Each card raises its name the frame it comes up, because that is the moment a
+mod can act on. Only the movie has an `_ended` name, and only because it
+carries a fact nothing downstream does -- `skipped` is the difference between a
+player who watched all 2335 frames and one who pressed START. The other three
+cards chain straight into the next card, whose own event is their end.
+
+`delta` on `happiness.changed` is `to - from`, not the table's column, because
+the 0 and $ff carry clamps are part of what the cart applied: a mon at 254
+gaining "5" gained 1.
+
+`clock.day_changed` compares against a process-local latch, so the first read
+after a boot has nothing to compare against and raises nothing. That is by
+design; it is a day *change*, not a day report.
+
+`unown.unlocked` is raised from `UpdateUnownDex` -- a form first entering the
+`#DEX` list -- not from the four `ENGINE_UNLOCKED_UNOWNS_*` puzzle flags. Those
+flags are written by the cart's own `setflag`, so there is no Lua transition at
+the puzzle solve to hang a second event on yet.
+
+`mail.read` rides `Mail.lines` with a per-struct latch, because the read page
+redraws every frame. The latch is re-armed by `Mail.get` / `Mail.mailbox`,
+which is how both readers pick the letter they are about to open, so reopening
+the same letter raises a second event.
+
+### Hooks
+
+| hook | wraps | ctx | vanilla answer |
+| --- | --- | --- | --- |
+| `held_item.trigger` | `Battle:heldEffect` | `battle`, `mon`, `item`, `def`, `effect`, `parameter`, `trigger` | `ctx.effect, ctx.parameter` |
+| `breeding.compatibility` | `Breeding.compatibility` | `data`, `mon1`, `mon2`, `dayCare` | the vanilla byte |
+| `phone.contact_list` | `Phone`'s `wPhoneList` read | called `(save, list)`, the shape the other list hooks use | the same list |
+| `shiny.roll` | `Mon` | `dvs`, `species`, `def`, `level` | the DV-derived boolean |
+| `gender.roll` | `Mon` | `def`, `dvs`, `ratio`, `species`, `level` | the DV-derived gender |
+
+`held_item.trigger` is one hook over eight call sites, because on the cart
+those eight *are* one routine (`GetUserItem` / `GetOpponentItem` loading b and
+c, and the caller comparing b against the `HELD_*` it cares about). `trigger`
+says which comparison is about to happen: `"priority"` (Quick Claw),
+`"damage"` (Scope Lens and the type-boost family), `"endure"` (Focus Band),
+`"flinch"` (King's Rock), `"accuracy"` (BrightPowder), `"confuse"`,
+`"residual"` (the end-of-turn Leftovers / Berry / cure arm), and `"check"` for
+any other read. Return nil to make the item do nothing at that trigger, or
+another `HELD_*` name to substitute one -- every call site compares against a
+name, so substitution is the whole mechanism.
+
+`held_item.trigger` wraps the *read*, so a mod can suppress or substitute an
+effect from any item. Defining a **new** held item is the `held_items`
+registry's job, and the two compose: register the row, then steer it from the
+hook.
+
+`phone.contact_list` refuses an answer of the wrong length or with an unknown
+contact id (unknown ids blank to 0 on purpose, so the Pokegear never indexes a
+nil). It reorders and blanks the ten save slots; registering a contact id the
+game does not know is `phone_contacts`' job.
+
+`shiny.roll` does not override a forced-shiny battle (`opts.shiny`), which is
+how the cart's own scripted shiny Gyarados stays shiny.
+
+## Registries with no Gen 2 home
+
+Writing to one of these while Gold is running takes the write, drops it, and
+reports it once per mod into the same error feed the manager shows. It is not
+fatal: a mod that supports both generations registers its Gen 1 content
+unconditionally and still loads the half that applies. The report is worded
+from the boot's own generation, because the gating runs both ways.
+
+`rulesets`, `transitions`, `field`, `text_pointers`, `link_fields`,
+`map_scripts`.
+
+`Schemas.GEN2` in `src/mods/Schemas.lua` is the authoritative table, and
+`tests/engine/gate_gen2_mod_api.lua` holds it to the catalog.
+
+The list used to have three causes behind it and now has one. "No Data path
+exists" closed when the overworld tables stopped loading off disk into World
+fields. "The shape differs" closed when a registry gained the option of
+carrying a Gen 2 record schema beside its Gen 1 one. What is left is one cause:
+
+**Gold reimplements the system without reading a registry.** The Gen 1 target
+is still built and merged into, but nothing in a Gold boot ever looks at it, so
+routing the registry would be a merge into a table with no reader -- exactly
+the silent no-op the gate exists to prevent. Closing one of these is a consumer
+change in the Gen 2 module first and a routing row second:
+
+- `rulesets`: no Gen 2 ruleset dispatch exists.
+- `transitions`: Gold draws its own battle intro
+  (`src/ui/gen2/BattleTransition.lua`), and its `STYLES` is a boolean *set* of
+  the four cart wipes (`spin`, `speckle`, `zoom`, `sine`) rather than the
+  `{ frames, draw, sound, flash }` record this registry carries. There is no
+  styleDef lookup for a registered id to reach, so a mod style would fail the
+  `STYLES` membership test and fall back to vanilla -- routing it would be the
+  silent no-op, not the fix.
+- `field`: the Gen 1 overworld's data grab bag. Gold's equivalents live in
+  `data.gen2Maps` and the VM's own tables.
+- `text_pointers`: Gen 1's `TEXT_*` indirection. Gold's text *is* pointers.
+- `link_fields`: link play is Gen 1 only.
+- `map_scripts`: `data.gen2Scripts` is the cart's bytecode pool keyed by ROM
+  pointer, and a Lua row list merged into it is not something
+  `src/script/gen2/Vm.lua` can run. Routing it needs a Gen 2 side dispatcher in
+  `World`, not just the verb table `mod.commands` already has. The
+  `script.started` / `script.ended` / `script.command` seams do fire, so a mod
+  observes and can veto a script it cannot yet author whole.
+
+Four of this list closed after it was written, and how they closed is the
+pattern for the rest:
+
+- **`growth_rates`** now routes to the SHARED Gen 1 target. Gold's curves are
+  coefficient rows in the extracted `pokemon.lua`, so `src/mods/Builtins.lua`'s
+  Gen 2 registrant wraps each as the `{ expForLevel }` record Gen 1's registry
+  uses, and `src/battle/gen2/Mon.lua:growthFor` is the one accessor all six
+  readers go through (`Mon` twice, `BattleState`, `SummaryMenu`, `Breeding`,
+  `ItemEffects`). One record shape, one id space, one mod source for both
+  games. Because it is routed, the `pokemon` schema's `growthRate` reference is
+  now checked rather than skipped, and it resolves: both sides say
+  `GROWTH_MEDIUM_SLOW`.
+- **`tokens`** was on the list by mistake rather than by cause. `TextBox.new`
+  runs `TextBox.substitute` on every box in both generations and `substitute`
+  reads `game.data.tokens`, so the shared target was live on Gold the whole
+  time. A `{NAME}` a mod registers expands in the world, the menus and the VM's
+  pages alike.
+- **`battle_sprite_scales`** closed consumer-first, the `growth_rates` way:
+  `src/ui/gen2/BattleState.lua` grew `imageScale` / `picScale`, a faithful
+  mirror of Gen 1's `BattleState.imageBattleScale` / `resolveBattleScale` down
+  to skipping `_owners` and the image-then-species-then-default order, so the
+  registry now routes to the SHARED Gen 1 path and one record serves both
+  games. Only the default is generation-specific, and neither side reads that
+  from the registry.
+- **`render_pipelines`** closed because the reader moved, not the registry:
+  `src/core/Game2.lua:load` installs `src/render/Pipelines.lua` on Gold's
+  merged dataset after `mods:load` and `Game2:draw` composites `present`. The
+  `drawWorld` half is still inert, which is why this one is worth reading the
+  caveat above for -- it is routed on the strength of the half that works, and
+  Gold retires a drawWorld-only level rather than pretending.
+
+## Hooks and events Gold does not raise yet
+
+Gold has its own draw path, intro, evolution and sprite lookups, so the call
+sites in those Gen 1 modules are not on Gold's path. The names are not taken
+and not reserved for Gen 1: when a Gen 2 call site lands it uses the existing
+name and the existing payload, plus fields where Gen 2 genuinely carries more
+(the split special stats, held items on a trainer roster).
+
+The list is much shorter than it was. What is outstanding, in descending value:
+
+- `trainer.before_battle`: Gold constructs and pushes its trainer battle in
+  `src/world/gen2/World.lua:startBattle`, which does not yet expose a deferred
+  preparation boundary or a battle-local player-party view. Gen 1 mods can use
+  the hook documented in `docs/modding.md`; do not claim Gold compatibility
+  when that selection is required.
+- `pokemon.before_give` / `pokemon.received`: Gold has no give-mon seam of its
+  own yet.
+- `link.*` and `trade.completed`: a Gold boot offers no link menu at all. The
+  Gen 2 fingerprint and handshake exist (`src/link/Fingerprint.lua` hashes a
+  Gen 2 surface and a cross-generation pairing is refused by name), but nothing
+  in `src/ui/gen2/` opens onto the protocol, so these raise nowhere.
+
+Four groups that used to sit here have since landed and moved to the shared
+table above: the frame seams (`render.compose` / `render.hud` /
+`render.letterbox` / `render.zones`, `input.step` / `input.pointer`), the three
+battle seams (`battle.overlay`, `battle.low_health_alarm`,
+`battle.catch_exp`), the two sprite lookups (`pokemon.sprite`,
+`pokemon.icon`), and the catch/evolution trio (`pokemon.caught`,
+`pokemon.evolved`, `evolution.check` -- `src/ui/gen2/BattleState.lua` emits
+`pokemon.caught` from `pushCaught` once the mon is in the party or the box, and
+`src/core/gen2/Evolution.lua` emits `pokemon.evolved` from `apply` and wraps
+each row's decision in `evolution.check`).
+
+Three partial coverages worth knowing about, because "the hook exists" is not
+the same as "the hook sees everything":
+
+- `encounter.roll` / `encounter.species` are wired into the grass/water step,
+  `randomwildmon`, the Bug Contest and SWEET SCENT, but **not** into
+  `World:tryHeadbutt`, `World:rockMonEncounter` or `Roamers.checkEncounter`.
+  Those three read row shapes that are not `{ species, level }` slot lists, so
+  a mod that reskins encounters misses headbutt trees, rock smash and the
+  roamers.
+- `src/ui/gen2/BattleState.lua` builds a flat `opts` for `Catching.attempt`
+  with no `data` in it, so a mod-registered ball is readable through
+  `Catching.recordFor` but is not yet resolved at the real throw site.
+- Three Gold UI files carry their own copy of the status HUD labels the merged
+  `statuses` records now hold as `hudLabel`, so a mod status shows no label in
+  the battle HUD, the party menu or the summary page until they read
+  `Battle.statusRecordFor(data, status).hudLabel`. The values are identical
+  today, so nothing vanilla is affected.
+
+## Gen 2 tables with no registry
+
+`Game2:load` assigns 24 `data.gen2*` tables and 12 of them are registry-backed,
+so twelve sit in `game.data` on a Gold boot with no registry pointing at them:
+`gen2Marts`, `gen2Roofs`, `gen2StdScripts`, `gen2EventTables` (the phone book,
+in-game trades, elevator labels, decoration descriptions), `gen2InitialEvents`,
+`gen2Pokedex`, `gen2MenuGfx`, `gen2Intro`, `gen2Credits`, `gen2Diploma`,
+`gen2Trade`, and `gen2Scripts` (which the `map_scripts` registry does reach, so
+it is the one of the twelve that is not out of reach). Naming registries for the
+rest is new API surface rather than a routing change, so it is deliberately not
+done yet.
+
+## Testing a Gen 2 mod
+
+Static first. `gen2check` reads the manifest, scans every `.lua` the package
+carries and cross-references what it finds against the coverage table above:
+
+```sh
+python3 tools/modkit.py gen2check my_mod            # or a path
+python3 tools/modkit.py gen2check my_mod --notes    # + the caveat on each backed member
+```
+
+It reports one of `will load`, `will load but degrade` or `will not work`, with
+a `MK4xx` finding per site and an `unresolved:` note, carrying a file and a
+line, for every reach a static scan could not follow. Exit 0 clean, 1 on a
+fatal finding (or any finding under `--strict`), 2 on usage; `--json` emits the
+whole batch as one document, and `--quiet` prints the findings alone, so a
+clean mod prints nothing and the exit code is the answer. The rule ladder is
+`MK400`-`MK410` and is listed in `tools/modkit.py`'s section header.
+
+Then the headless harness, which takes the generation without booting Gold:
+
+```lua
+local run = T.sdk.loadMod("mods/my_mod", { generation = 2 })
+T.eq(run.mod and run.mod.state, "loaded",
+  "runs on gen 2: " .. tostring(run.mod and run.mod.skipReason))
+T.eq(#run.errors, 0, "and loads with no boot errors")
+```
+
+Everything else is the production path: same loader, same validate, same
+topological sort, same merge. Assert the state as well as the error count: a
+gate skip is deliberately not an error, so `#run.errors == 0` passes for a mod
+that never ran a line.
+
+Neither substitutes for a real Gold boot, and the two output channels there are
+not the same. The adapter's own warnings (`Gen2Compat.warnOnce`) go to the log
+only, each attributed to the mod holding the facade. The boot error feed the
+manager shows is `loader.errors`: a failed mod, a duplicate id, a registry with
+no Gen 2 target, a cross-validation problem, and a require for a Gen 1 module
+the adapter does not serve. A skipped mod and a degraded member are on neither
+list, by design.
@@ -0,0 +1,96 @@
+# RFC 0008 — Runtime mod option schema export
+
+## Status
+
+Proposed. Engine: `src/mods/Loader.lua`. Tests:
+`tests/mod_loader_tests.lua`. This RFC defines an optional filesystem
+contract; it does not require a native launcher or any other consumer.
+
+## Motivation
+
+A native launcher may want to present settings for installed mods before it
+starts the game. Running every mod's entry chunk in that launcher just to
+discover its settings would duplicate engine behavior and give the launcher
+an unnecessary code-execution surface. The engine already has the authoritative
+runtime schemas after mod loading, so it can publish a data-only snapshot for
+platform shells that want one.
+
+## The exact contract
+
+After the mod loader has finished running entry chunks, it may write
+`mod_option_schemas.json` beside `options.lua` in the same filesystem. The
+document is a snapshot of the current boot; it is not a second settings store
+and does not change how option values are read or written.
+
+Version 1 has this shape:
+
+```json
+{
+  "schema_version": 1,
+  "mods": {
+    "example": [
+      {"key":"enabled","type":"toggle","label":"Enabled","default":true},
+      {"key":"mode","type":"choice","label":"Mode","default":"safe",
+       "choices":[["Safe","safe"],["Fast","fast"]]},
+      {"key":"rate","type":"number","label":"Rate","default":5,
+       "min":0,"max":10,"step":1},
+      {"key":"name","type":"text","label":"Name","default":"","maxLen":12}
+    ]
+  }
+}
+```
+
+`mods` is keyed by mod id. Its rows come from the runtime
+`mod.options:define` schema, or from the legacy manifest `options_schema` file
+when the runtime schema is absent. The supported row types are `toggle`,
+`choice`, `number`, and `text`. Their optional fields retain the meanings
+established by the existing in-game option UI: choices are `[label, value]`
+pairs, numeric rows may provide `min`, `max`, and `step`, and text rows may
+provide `maxLen`. A row may also use
+`visible_if = {key = "mode", equals = "compact"}` or replace `equals` with
+`not_equals`. This only hides the in-game menu row; the schema and stored value
+remain available, and consumers that do not implement conditions may ignore
+the field.
+
+Only mods that are enabled and successfully loaded in the current boot are
+included. A disabled or failed mod must not contribute rows. If an older
+snapshot exists and the current boot has no schema-bearing mods, the producer
+overwrites it with `{"schema_version":1,"mods":{}}`; this prevents stale
+settings rows from surviving a disable or load failure. A fresh mod-free boot
+does not create the file, and a filesystem without write support is tolerated.
+
+The producer writes the snapshot after entry chunks and the final load set
+have been established. Consumers must treat the file as untrusted input and
+must not execute anything from it.
+
+## Compatibility and versioning
+
+The contract is optional on both sides. A native consumer may be absent, and
+the engine continues normally if the file cannot be written. A native
+consumer is not required to render, validate, or persist every supported row;
+it may ignore an unknown row type or optional field.
+
+For compatibility with files produced by the original unversioned prototype,
+a missing `schema_version` means version 1. Consumers must ignore documents
+with a newer version rather than guessing at their shape. Producers must bump
+the version whenever they change the document envelope or the meaning of an
+existing field. New optional row fields that older consumers can safely ignore
+do not require a bump. Version 1 is therefore the legacy unversioned format as
+well as the explicitly versioned format shown above.
+
+## Migration note
+
+Nothing. Existing mods, option values, and the in-game options UI are
+unchanged. Platforms that do not consume `mod_option_schemas.json` have no
+new integration requirement.
+
+## Parity tests
+
+`tests/mod_loader_tests.lua` verifies the explicit version, runtime and legacy
+row round-tripping, enabled/disabled filtering, failed-mod filtering,
+stale-snapshot clearing, and tolerance of a read-only filesystem.
+
+## Deprecation etiquette
+
+Nothing is deprecated. The unversioned file form remains readable as legacy
+version 1; new producers write the explicit `schema_version` field.
@@ -12,12 +12,175 @@ The modding book lives on the
 - [Registry reference](https://github.com/bryanthaboi/gen1recomp/wiki/Reference-Registries)
  — every registry, generated from `src/mods/Schemas.lua`.

-Regenerate the reference straight into a wiki checkout:
+Regenerate the reference. With no argument it writes in-repo, to
+`docs/modding/reference/registries.md`; name a wiki checkout to write the
+wiki's own page name into it instead:

 ```sh
+luajit tools/gen_registry_docs.lua
 luajit tools/gen_registry_docs.lua ../gen1recomp.wiki
 ```

+## Manifest specification (`manifest.json`)
+
+Every mod contains a root `manifest.json` defining its metadata, supported games, and dependencies for the engine loader.
+
+```json
+{
+  "id": "my_mod",
+  "name": "My Cool Mod",
+  "version": "1.0.0",
+  "api": 2,
+  "entry": "main.lua",
+  "profile": "content",
+  "category": "GAMEPLAY",
+  "games": ["gen1", "gen2"],
+  "game_version": ">=0.0.0-dev <2.0.0",
+  "priority": 100,
+  "dependencies": [
+    "helper_lib@^1.0.0",
+    { "id": "pokegear_cards", "games": ["gen2"], "range": "^1.0.0", "github": "1jamie/pokegear_cards" }
+  ],
+  "optional_dependencies": [
+    "gen1_modern_ui"
+  ],
+  "required_imports": [
+    {
+      "id": "stadium2",
+      "name": "Pokemon Stadium 2 ROM",
+      "description": "Pokemon Stadium 2 (USA), any supported N64 byte order",
+      "file": "stadium2.z64",
+      "format": "n64",
+      "size": 67108864,
+      "md5": ["00000000000000000000000000000000"]
+    }
+  ],
+  "optional_imports": [
+    {
+      "id": "bonus_source",
+      "name": "Optional bonus source",
+      "file": "bonus.bin",
+      "md5": "00000000000000000000000000000000"
+    }
+  ],
+  "conflicts": [],
+  "permissions": ["engine_internals"],
+  "description": "A brief description of the mod.",
+  "github": "author/my_mod"
+}
+```
+
+### Manifest Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique identifier (lowercase alphanumeric, underscores, hyphens). |
+| `name` | `string` | Human-readable title shown in launcher and manager. |
+| `version` | `string` | Semantic version string (e.g. `"1.0.0"`). |
+| `api` | `integer` | Mod API level (`2` for current standard, `1` for legacy). |
+| `entry` | `string` | Entry Lua file path relative to mod root (usually `"main.lua"`). |
+| `profile` | `string` | Mod profile: `"content"`, `"overhaul"`, or `"total_conversion"`. |
+| `category` | `string` | Categorization chip (e.g. `"GAMEPLAY"`, `"CONTENT"`, `"UI"`, `"AUDIO"`). |
+| `games` | `array` | Supported game versions: `["gen1"]`, `["gen2"]`, `["red"]`, `["blue"]`, `["yellow"]`, `["gold"]`, or `["all"]`. |
+| `game_version`| `string` | Semver range of required engine version (e.g. `">=0.0.0-dev <2.0.0"`). |
+| `priority` | `integer` | Load priority order (lower numbers load earlier; dependencies always precede dependents regardless of priority). |
+| `dependencies` | `array` | Hard required dependencies. A mod will not load if a required dependency is missing or disabled for the active game. |
+| `optional_dependencies` | `array` | Soft dependencies. Guarantees that if the target mod is present and active, it loads *before* this mod without blocking load if absent. |
+| `required_imports` | `array` | User-supplied files required by this mod. The launcher validates and copies each file into this mod's `baseroms/` directory; the mod does not load while one is missing. |
+| `optional_imports` | `array` | User-supplied files that unlock optional mod functionality. They use the same validation and private-copy flow but never block the mod from loading. |
+| `conflicts` / `incompatible` | `array` | List of mod IDs that cannot run concurrently with this mod. |
+| `permissions` | `array` | Requested privileges (e.g. `["engine_internals"]`, `["network"]`, `["filesystem"]`). |
+| `log_url` | `string` | Optional https URL for `mod.postLog` log reporting (api 2; requires the `network` permission). |
+| `github` | `string` | GitHub repository (`"owner/repo"`) used for update checks and dependency download links. |
+
+### Declaring Dependencies & Scoping
+
+Dependencies in `dependencies` and `optional_dependencies` can be declared in several formats:
+
+1. **Simple string**: `"mod_id"`
+2. **Version-pinned string**: `"mod_id@^1.2.0"`
+3. **Repository-hinted string**: `"mod_id#owner/repo"` or `"mod_id@^1.2.0#owner/repo"`
+4. **Structured object**:
+   ```json
+   {
+     "id": "mod_id",
+     "range": "^1.2.0",
+     "games": ["gen2"],
+     "github": "owner/repo"
+   }
+   ```
+
+#### Version-Scoped Dependencies
+When a mod supports multiple games (`"games": ["gen1", "gen2"]`), a dependency can specify `"games": ["gen2"]` to indicate it is only required when booting Gen 2. When booting Gen 1, the engine will ignore the dependency, preventing unnecessary boot blocks on games that do not need it.
+
+### Required user-supplied files
+
+`required_imports` and `optional_imports` keep copyrighted or otherwise user-owned source material
+out of mod archives while giving every platform the same installation flow.
+Each object requires a stable `id`, a display `name`, a destination `file`
+(a filename, never a path), and one MD5 digest or an array of accepted MD5
+digests. `format` is either `"raw"` (the default) or `"n64"`. An optional
+`description` gives players dump or region guidance in the import panel.
+`size` declares the exact canonical byte length; `max_size` declares a smaller
+per-import ceiling when an exact size is not appropriate. Every import also
+has an engine-enforced 128 MiB ceiling and is rejected before hashing when its
+filesystem reports an invalid size.
+
+For `"n64"`, the launcher recognizes `.z64`, `.v64`, and `.n64` byte orders,
+strips a recognized 512-byte copier header, converts the bytes to canonical
+big-endian `.z64` order, and then checks MD5. The canonical bytes are written
+to `mods/<mod-id>/baseroms/<file>`. Each selection is a private grant to that
+mod: the launcher never scans or copies another mod's imported files merely
+because its manifest names the same digest. Mods read the result with their existing scoped `mod:read` API, for
+example `mod:read("baseroms/stadium2.z64")`; no host path or new filesystem
+permission is exposed. Missing `required_imports` block the mod before its
+entry chunk runs; missing `optional_imports` remain visible in the same
+launcher panel but do not block loading.
+
+MD5 here identifies a known dump because ROM databases commonly publish it;
+it is not a security or authenticity guarantee. Do not paste the SHA-1 used by
+Gen1Recomp's own game-ROM importer into an import's `md5` field. Mod archives
+must not include anything beneath `baseroms/`. The engine records a validation
+receipt keyed by file size and modification time so launcher refreshes and
+later boots do not repeatedly hash an unchanged imported ROM.
+
+New mobile code should call `love.system.pickFile("required_import")`. The
+older iOS-only `"stadium"` picker kind remains temporarily for compatibility.
+Android now returns `false` for unknown picker kinds instead of treating them
+as game-ROM picks.
+
+### Platform import flow
+
+The same per-mod validation and private `mods/<mod-id>/baseroms/` destination
+applies on every supported platform. Windows, macOS, and Linux use the
+launcher file chooser. Android uses the Storage Access Framework, and iOS uses
+the Files document picker; both stage the choice as `picked_required_import.bin`
+before validation. Xbox/UWP uses its native picker and hands the launcher a
+temporary path. Switch/NX has no host picker, so the player copies a file to
+`imports/baseroms/` over MTP and chooses the import again. No platform grants
+the mod a host filesystem path or bypasses the manifest's size, format, and MD5
+checks.
+
+## Mods and Gold (Gen 2)
+
+The mod API is one API across both generations, but Gold runs its own battle
+engine, overworld, script VM and save format, so a mod says which games it is
+for and Gold serves a declared subset of the surface.
+
+- [`docs/preparing-your-mod-for-gen2.md`](preparing-your-mod-for-gen2.md)
+  the migration guide: what breaks, the `games` manifest key, the module
+  adapter, the patterns no adapter can fix, and a worked before/after.
+- [`docs/mod-api-gen2-compat.md`](mod-api-gen2-compat.md)
+  the reference: every registry, hook and event, whether Gold serves it, and
+  the record-shape differences where it does.
+
+Start with the checker, which reads your manifest and scans your Lua against
+the adapter's own coverage table:
+
+```sh
+python3 tools/modkit.py gen2check mods/my_mod
+```
+
 ## Editing maps in Tiled

 Maps are data, not assets, so they can be authored in a real map editor and
@@ -35,6 +198,91 @@ An edited vanilla map becomes a `mod.content.maps:patch` carrying only the
 fields that moved; a new map becomes a `:register`. See
 `docs/new-features.md` and the extension's own README.

+## Read-only map overviews
+
+`mod.world:mapOverview()` returns collision `rows` at map-cell resolution,
+optional visual `tileRows` at 2x resolution, and optional `tileDetailRows` at
+4x resolution. Visual rows contain Game Boy shades from `"0"` (lightest) to
+`"3"` (darkest); their matching width and height fields describe the grid.
+`markers` contains active `{ kind, x, y }` points in map-cell coordinates for
+`warp`, visible `item`, and untaken `hidden` locations. All fields are
+read-only snapshots; mods choose which layers to render. Red and Gold expose
+the same contract while applying their own object and event visibility rules.
+
+## Party ordering
+
+Companion UIs and alternate party screens can call
+`mod.world:canReorderParty()` before offering a reorder action, then
+`mod.world:reorderParty(fromSlot, toSlot)` with one-based party slots. The
+operation is accepted only during idle overworld play; menus, movement,
+scripts, battles, and transitions leave the party untouched.
+
+## Contextual field actions
+
+`mod.world:availableFieldActions()` returns the field items and moves that can
+start at the player's current position. Both games expose `bicycle`, `fish`,
+`cut`, `surf`, `strength`, `flash`, `dig`, and `teleport`; Gold additionally
+exposes `headbutt`, `whirlpool`, `waterfall`, `sweet_scent`, and the
+contextual `squirtbottle` key item. Fishing rows include the owned rods that
+are valid choices. The list is empty while the world is busy, and omits an
+action whenever its item, move, badge, terrain, or engine state forbids it.
+The optional second return is `"world is busy"` during transient input locks
+or `"no overworld"` before a playable world exists.
+
+Call `mod.world:useFieldAction(id, opts)` to perform a listed action through
+the active game's own field-item path. Fishing accepts `{ rod = "OLD_ROD" }`
+and chooses automatically when only one rod is available. Invalid, stale, and
+busy requests return `nil` plus a reason without changing game state. Mods do
+not need generation-specific badge, terrain, bike, fishing, or field-move
+logic. Action lists are extensible; callers should render the records they
+understand and ignore unknown ids rather than assuming a fixed list length.
+
+## Read-only battle snapshots
+
+`mod.battle:snapshot()` returns `nil` outside a battle and a copied battle
+record while one is active. Gen 1 (Red, Blue, and Yellow) and Gold expose the
+same core fields:
+`revision`, `kind`, `catchable`, `prompt`, `message`, `turn`, `player`,
+`enemy`, `party`, `moves`, and `items`. Pokémon, moves, messages, and items in
+the result are detached records; changing them cannot change the battle.
+`revision` stays stable while the visible battle context is unchanged and
+advances when it changes, so a UI can skip rebuilding an identical view.
+
+Pokémon records contain `species`, `name`, `level`, `hp`, `maxHp`, `status`,
+and `active` (plus `slot` in `party`). Move records contain `slot`, `id`,
+`name`, `pp`, `maxPp`, `type`, `power`, `accuracy`, and `disabled`. Gen 1 also
+reports the actual ruleset-aware `displayPower`, `hitChance` percentage, and
+`effectiveness` multiplier (`10` neutral, `20` super-effective, `5`
+resisted). Item rows contain `id`, `name`, `count`, `ball`, `needsTarget`, and
+an optional stock `catchChance` percentage.
+
+`prompt` describes the currently visible choice (`menu`, `moves`, `party`,
+`advance`, `safari`, or `mimic`) and is `locked` when another screen or battle
+phase owns input. Generation-specific features remain optional: Gen 1 includes
+battle medicine, balls, catch previews, Safari balls, and Mimic choices;
+Gold currently returns an empty `items` list rather than guessing at its
+pocketed PACK flow. Callers should ignore unknown fields and tolerate absent
+optional ones.
+
+## Battle menu intents
+
+`mod.battle:submit(intent)` applies a validated choice to the snapshot the mod
+just read. Every intent needs a mod-owned, strictly increasing positive
+integer `id` and the latest snapshot `revision`. Stale, replayed, covered, or
+invalid choices return `nil` plus a reason without changing the battle.
+
+The shared Red, Blue, Yellow, and Gold intents are:
+
+- `{ kind = "menu", choice = "fight" }` (`party`, `item`, and `run` are the
+  other accepted choices)
+- `{ kind = "move", slot = 1..4 }`
+- `{ kind = "back" }` while the move menu is active
+
+Menu choices and moves use the same engine methods as the native controls;
+`party` and `item` open the native screens rather than exposing or duplicating
+their mutable logic. Tutorial, link, Safari, forced, stale, and covered battle
+states refuse these core intents. Use `mod.input` for ordinary text advance.
+
 ## Rendering pipelines

 Most registries hand the engine *content*. `render_pipelines` hands it
@@ -100,6 +348,44 @@ Three rules worth knowing:
 Returning `nil` from `drawWorld` is a normal answer meaning "not this
 frame"; the engine draws the vanilla world instead.

+## Variable-size overworld sprites
+
+The `sprites` registry keeps the vanilla 16x16 grounded walker as its default,
+but a mod can describe any frame rectangle and anchor for player characters,
+NPCs, followers, mounts, vehicles, bosses, or other field actors:
+
+```lua
+mod.content.sprites:register("SPRITE_COMPANION", {
+  image = "mods/example/companion.png", -- one frame per row
+  frames = 6,
+  walker = true,
+  frameWidth = 32,
+  frameHeight = 32,
+  anchorX = 16, -- frame-relative bottom-center anchor
+  anchorY = 32,
+})
+```
+
+`frameWidth` and `frameHeight` are sheet pixels. `anchorX` and `anchorY` are
+measured from each frame's top-left; when omitted they default to the frame's
+horizontal center and bottom edge, so a larger sprite grows upward while its
+feet stay on the same world cell. Omitting all four fields is exactly the
+vanilla 16x16 placement. The normal player/NPC/follower draw paths consume
+these values automatically, including horizontal flips and the fishing pose.
+
+Custom render pipelines can use the same geometry without reproducing the
+pose rules:
+
+```lua
+local geometry = sprite:getPoseGeometry(facing, walkPhase, stepFlip)
+-- geometry.quad, .x/.y/.width/.height, .anchorX/.anchorY, .mirror
+local originX, originY = sprite:getScreenOrigin(px, py, camX, camY)
+```
+
+`getFrameGeometry(frame)` is the corresponding accessor for a specific
+zero-based sheet frame. Both accessors return fresh tables and share the
+renderer’s frame selection and mirror conventions.
+
 ## Battle sprite scaling

 The enemy's front pic draws at 1x and the player's back pic at 2x, the way
@@ -140,6 +426,198 @@ default** (1x front, 2x back).
  ball-to-pic grow multiplies your scale through each stage, so a rescaled
  mon still grows into place from the ball, grounded the whole way.

+## Durable tool storage and runtime checkpoints
+
+`mod.save` remains the right place for state that should travel with the next
+normal Pokémon SAVE. Tools that need independently written, larger data-only
+records can use `mod.storage`; the engine scopes every logical key by game
+version, opaque playthrough identity, and mod id, and routes it through the same
+standard or portable persistence backend as saves:
+
+```lua
+local context, code, message = mod.storage:context(game)
+local ok, code, message = mod.storage:write(game, "history/quick/q0001", {
+  format = 1, createdAt = os.time(), payload = { money = 3000 },
+})
+local value, code, message = mod.storage:read(game, "history/quick/q0001")
+local keys, code, message = mod.storage:list(game, "history/quick")
+local deleted, code, message = mod.storage:delete(game, "history/quick/q0001")
+```
+
+For independently generated binary data, use the opaque byte methods. They
+accept and return the exact Lua string of bytes, including NUL bytes and bytes
+that are not valid text:
+
+```lua
+local ok, code, message = mod.storage:writeBytes(
+  game, "cache/maps/pallet/terrain", encodedMesh)
+local encodedMesh, code, message = mod.storage:readBytes(
+  game, "cache/maps/pallet/terrain")
+```
+
+Opaque values are limited to 512 MiB per key. The engine stores them without
+decoding, compression, or an engine-defined file format, and never executes
+them. A consuming mod owns validation of its format, fingerprint, checksum,
+and compression metadata. Byte writes are staged and compared byte-for-byte
+before replacement, and reads can recover a valid backup after an interrupted
+write. Existing table values and opaque byte values use one shared logical key
+space; delete a key before changing its value from one type to the other.
+
+`context` returns `{ engineVersion, gameVersion, playthroughId }`. The engine
+version is compatibility metadata; physical launcher-slot and path identity stays
+private. A title-selected context may additionally contain `normalSavedAt`, the
+validated matching ordinary-save chronology only; it never exposes normal-save
+progress or a slot/path handle.
+
+At the title screen only, `mod.storage:selected(game)` returns a bound storage
+facade for the launcher-selected existing playthrough, or `nil, code, message`.
+Resolving this facade is non-allocating: it never allocates an identity, adopts a
+fresh New Game, or exposes a slot id/path. Its `context()`, `read(key)`,
+`write(key, value)`, `readBytes(key)`, `writeBytes(key, bytes)`,
+`list(prefix)`, and `delete(key)` methods have the same scoped and
+transactional contract as `mod.storage`, but remain restricted to the calling
+mod's selected existing namespace. It is intended for title tools that need to
+browse or manage durable history before the first normal SAVE.
+
+Table values must contain serializable data only. Opaque values must be Lua
+strings. Keys are conservative slash-separated segments (letters, digits, `_`,
+`-`); paths and filesystem handles are never exposed. Table writes are staged
+and decode-verified; opaque writes are staged and byte-verified; reads recover
+from a valid staged/backup generation. Methods return structured errors for
+normal data, byte validation, and I/O failures. The playthrough identity is
+allocated lazily on the first storage/checkpoint call, so an unused API changes
+no save bytes.
+
+`mod.checkpoints` captures and reconstructs engine-owned semantic runtime state:
+
+```lua
+local capability = mod.checkpoints:inspect(game)
+if capability.canCapture then
+  local checkpoint, code, message = mod.checkpoints:capture(game)
+  -- Store the detached data-only checkpoint through mod.storage.
+end
+
+local ok, code, message = mod.checkpoints:restore(game, checkpoint)
+
+-- After the tool has durably committed its first checkpoint, make a
+-- never-saved playthrough reachable through ordinary title boot exactly once.
+local anchored, anchorCode, anchorMessage =
+  mod.checkpoints:ensureNormalSave(game, checkpoint)
+```
+
+Checkpoint format 1 supports settled overworld control and proven battle
+player-decision safe points. Ordinary single-player wild/trainer encounters are
+supported. Scripted story battles are also supported when the engine can detach
+their current built-in battle command and data-only row continuation, rebind any
+NPC by stable id, and resume the story through a fresh runner. The suspended Lua
+coroutine is never serialized. Link, Safari, ghost, demo, opaque callback,
+non-data-only script, animation, message, queue, concurrent-script, and
+forced-action phases fail closed. New checkpoints preserve gameplay RNG, while legacy overworld records
+without RNG remain loadable. Capture excludes global options and runtime
+objects. Restore validates format, game/playthrough identity, content,
+coordinates, battle relationships, continuation, and RNG before mutation;
+preserves current options; suppresses normal map-entry/save-load/intro side
+effects; verifies a recapture; and rolls back runtime plus RNG in memory if
+reconstruction fails. Callers that need crash recovery should durably capture
+their own recovery checkpoint before restore.
+
+Checkpoint ownership follows the persistence model rather than mod identity:
+
+- canonical `game.save` progress, including every mod's `save.modData` /
+  `mod.save` bucket and data-only fields added to saved Pokémon, rewinds;
+- global and per-mod options remain at their current values;
+- independently written `mod.storage` records do not rewind; and
+- mod-owned runtime objects, references, and caches are never serialized.
+
+Successful restore emits `checkpoint.restored` only after reconstruction and
+differential recapture have committed. Mods that cache rewound progress or hold
+references to reconstructed runtime objects can re-read their own public state
+and rebuild at that point:
+
+```lua
+mod.events:on("checkpoint.restored", function(ev)
+  -- ev.kind is "overworld" or "battle"; ev.game is fully reconstructed.
+  cachedQuestStage = mod.save:get("quest_stage", 0)
+  rebuildRuntimeFor(ev.game, ev.kind)
+end)
+```
+
+The event is not emitted for validation failure, failed reconstruction, or a
+successful rollback. Its payload contains no checkpoint data or other mod's
+private state. A mod that deliberately stores progress-coupled truth in
+`mod.storage` must version and reconcile that relationship itself; the engine
+cannot distinguish it safely from independent history, configuration, or cache
+data.
+
+`mod.checkpoints:resume(game, checkpoint)` is the title-session counterpart to
+live `restore`. It validates the same data-only checkpoint against the
+engine-selected existing playthrough, reconstructs only after all validation
+passes, preserves current options, and verifies by recapture. A title session
+has no live gameplay rollback state: if reconstruction or verification fails,
+the engine rebuilds a usable title session and returns `false, code, message`.
+It never rewrites a normal Pokémon save. It is unavailable outside title and does
+not broaden capture or arbitrary-frame support.
+
+`mod.checkpoints:ensureNormalSave(game, checkpoint)` is a separate live-runtime
+operation for durable checkpoint tools. It creates ordinary progress only when
+none exists, only after validating that the supplied checkpoint is the exact
+current safe runtime, and through the normal atomic save lifecycle. Once an
+ordinary save exists it returns `true, "already_exists"` without writing, so
+subsequent checkpoints and the player's later SAVE commands remain independent.
+Call it only after the tool's own checkpoint/index commit; treat an anchoring
+failure as a failed first checkpoint rather than claiming restart safety.
+See RFC 0003, RFC 0004, RFC 0005, and RFC 0006 for exact contracts and error
+codes.
+
+At that same settled supported wild/trainer decision boundary, a tool may claim
+START through `battle.menu_auxiliary`. It receives `(next, game, context)`, where
+`context` is the data-only `{ kind = "wild" }` or `{ kind = "trainer" }`; it
+never receives the live battle controller. Return `true` to consume START after
+opening source-owned UI, or call `next(game, context)` to allow lower-priority
+handlers. With no handler, START remains inert. Ordinary encounters and the
+validated built-in scripted battle origins described by RFC 0005 are eligible;
+opaque scripts, link/Safari/ghost/demo battles, action queues,
+animation/messages, forced choices, and every phase that cannot safely be
+checkpointed remain excluded. Exceptions are contained by normal hook isolation
+and fall through without advancing a turn.
+
+Gen 1 trainer encounters also expose `trainer.before_battle` after the
+challenge text and immediately before battle construction. This lets a mod
+defer the encounter while it collects a player choice through a registered
+screen, then resume with a battle-local view of the save party:
+
+```lua
+mod.hooks:wrap("trainer.before_battle", function(next, game, context, continue)
+  -- context = { trainerClass, partyIndex, mapId, npcId }
+  mod.ui.push(game, "party_registration", {
+    onConfirm = function(indices)
+      continue({ playerPartyIndices = indices })
+    end,
+    onCancel = function()
+      continue({ cancel = true })
+    end,
+  })
+  return true
+end)
+```
+
+Return `true` only when retaining `continue` for a later callback. Calling
+`continue({ cancel = true })` ends the encounter without constructing a battle;
+the normal encounter completion callback returns control to the overworld and
+no trainer-defeated state is written. A cancelled sight encounter is suppressed
+at the current player cell so it cannot immediately reopen; moving one cell or
+talking to the trainer permits a new challenge. Calling `continue()` uses the
+full save party; passing
+`{ playerPartyIndices = { 2, 4, 5 } }` uses those ordered, one-based party
+members for initial send, switching and forced replacement, exhaustion,
+experience traversal, and battle party displays. The continuation is one-shot.
+An empty, duplicate, out-of-range, or otherwise malformed list safely falls
+back to the full party. The view references the original Pokemon records and
+never reorders or replaces `game.save.party`; trainer battle checkpoints retain
+the selected indices. Mods remain responsible for selection policy and should
+use only public `mod.ui`, hook, and save APIs. See RFC 0010 for the exact
+contract and compatibility guarantees.
+
 ## Developer console

 Boot with developer mode on to unlock the in-game console and hot-reload
@@ -174,6 +652,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.
@@ -195,10 +699,354 @@ the finished `worldCanvas` and `uiCanvas` with their SGB `zones` / `worldZones`,
 `worldActive`, the frame metrics (`ww`, `wh`, `pw`, `ph`, `ox`, `oy`, `vpw`,
 `vph`, `scale`, `Sx`, `Sy`, `dpiX`, `dpiY`), `renderer:blitCanvas(...)` for a
 palette-correct blit of either canvas into an arbitrary screen rect, and the
-`secondScreen` bridge (`available()` / `push(imageData, w, h)` / `setEnabled`)
-for driving a second physical display. This is what lets a mod lay the two
-passes out as two stacked Game Boy screens, or push one onto a second screen,
-without the engine knowing the layout.
+`secondScreen` bridge (`available()` / `push(imageData, w, h)` / `pollTouch()` /
+`setEnabled`) for driving a second physical display. `pollTouch()` returns the
+oldest queued event as `"action,x,y"` in submitted-frame coordinates, or `nil`.
+This is what lets a mod lay the two passes out as two stacked Game Boy screens,
+or push one onto a second screen, without the engine knowing the layout.
+
+`render.output_enabled` and `render.output` are the later, whole-window seam
+for mods that need the engine's normal composite rather than its separate
+layers. It runs after registered present pipelines and before GBCFX,
+`render.hud`, and touch controls. A mod wraps both hooks: the first returns
+`true` only while output ownership is needed, and the second receives
+`(next, ctx)` with `canvas`, `width`, `height`, `gameX`, `gameY`, `gameWidth`,
+`gameHeight`, `scale`, `dpiX`,
+`dpiY`, and `generation`. Returning `true` from `render.output` takes over the
+window; calling `next(ctx)` keeps the normal presentation. Both hooks default
+to `false`. Enabling the seam requires a full-window canvas for that frame.
+With no `render.output` subscriber, or while `render.output_enabled` is false,
+the existing presentation path is unchanged. `render.compose` takes precedence
+when it owns the frame.
+
+`screen.render_visible` receives `(next, state)` while the main screen is being
+composed. Return `false` to omit that state from drawing, opacity selection and
+palette-zone ownership. The state remains on the stack and keeps its normal
+update and input ownership, so a mod can mirror a native menu on another
+display without reimplementing it. The default is `true`. Treat the wrapper as
+a pure predicate: the renderer may ask it more than once per frame.
+
+Scrollable list states expose `state.kind` for use with this hook. Generic
+lists fall back to their title; PC lists use stable, localization-independent
+identifiers: `pc_box_withdraw`, `pc_box_deposit`, `pc_box_release`,
+`pc_box_change`, `pc_item_withdraw`, `pc_item_deposit`, and `pc_item_toss`.
+
+`battle.bottom_ui_visible` and `battle.status_hud_visible` independently
+control the battle text/menu layer and the HP/status panels. Both receive
+`(next, state)` and default to `true`, so vanilla rendering is unchanged.
+Both hooks apply to Gen 1 and Gen 2 battles.
+Text boxes and YES/NO prompts pushed above a battle inherit a `false` result
+for that battle, so hiding the bottom layer cannot leave their white backing
+behind under another overlay. Text boxes also pass through the hook as their
+own state, preserving selective control outside a battle; a wrapper that only
+owns battle presentation should return `false` only for its active battle or
+text-box state.
+
+`core.logic_speed` receives `(next, game)` once per `Game:logicSpeed()` call
+(once per frame). Vanilla behavior resolves the per-category GAME SPEED
+option (`GameSpeed.CATEGORIES`: overworld/battle/menu) for whichever
+category `Game.speedCategoryInStack` says is active right now. A mod may
+call `next(game)` and return its result to pass that resolution through, or
+return a different number outright to override it for that frame (a bot mod
+forcing 1X for one route segment, say, regardless of the category or saved
+option). The result is clamped to the nearest valid `GameSpeed.LEVELS` entry
+regardless of what a subscriber returns, so a bad value (0, negative, `nil`)
+cannot destabilize the fixed-step accumulator. This hook runs *after* link
+play's 1X lock and the `--speed`/equivalent run-argument override, both of
+which stay unconditional and are never visible to a subscriber.

 Developer mode also arms the mod loader's dev tripwire, which flags mods
 that reach outside their permission set.
+
+## Process-lifecycle hooks
+
+These exist so a platform-specific launcher integration (a native shell
+that embeds this engine and wraps its window in platform UI) can live
+entirely in a mod instead of hand-patching `main.lua`, which every other
+engine change also touches.
+
+`core.update` receives `(next, game, dt)` once per frame from
+`love.update`. Vanilla behavior is `game:update(dt)`, unconditionally. A
+mod may skip calling `next(game, dt)` to pause the simulation for that
+frame (e.g. while a native settings sheet is on top), and may run
+additional per-frame polling before or after that call regardless of
+whether it calls `next` -- useful for one-shot flags that must be observed
+every frame even while paused.
+
+`core.quit_to_launcher` receives `(next)` once from `love.quit()`. `next()`
+returns the engine's own decision for whether closing the window should
+return to the Lua launcher instead of exiting; a mod may return `false`
+outright, without ever calling `next`, to veto that and let the process
+really quit -- for a platform host that owns its own "return to launcher"
+UI and would otherwise get looped straight back into the game it just
+quit.
+
+A manifest may also declare `force_enable_env`, an environment variable
+name that re-enables the mod regardless of a saved disable in
+`options.mods` when that variable is set to `"1"`. This is for a mod that
+cannot function disabled on the one build where its env var is set (a
+platform-bridge mod bundled only with that build's launcher, for example).
+
+Neither hook needs a `Runtime.wantsHook` guard before calling it: `Hooks:call`
+already falls straight through to the vanilla function when no mod has
+wrapped the name, at negligible cost.
+
+## Detached Pokémon icon presentation
+
+`mod.ui.PokemonIcon.draw(game, summary, x, y, opts)` draws the same party icon
+the native Party menu would resolve without exposing a live Pokémon record or
+the private Party menu. `summary` is the detached data-only shape
+`{ species = string, hp = integer, maxHp = integer }`; `opts.selected` and
+`opts.counter` optionally request the native selected-icon animation phase.
+
+The engine retains icon ownership. Content registered through
+`mod.content.icons`, species `icon` definitions, asset overrides, and the
+public `pokemon.icon` hook therefore continue to compose. Invalid summaries
+return `false, code, message` and draw nothing. The helper is presentation
+only: it does not expose moves, status, checkpoint payloads, or mutable party
+state.
+
+## Shared date and time presentation
+
+The global Options menu owns `DATE FORMAT` (`DEVICE`, `DD-MM-YYYY`,
+`MM-DD-YYYY`, `YYYY-MM-DD`) and `TIME FORMAT` (`DEVICE`, `24 HOUR`, `12 HOUR`).
+These preferences live in `options.lua`, so checkpoint restore never rewinds
+them. `DEVICE` uses the process time locale when the platform provides one;
+the portable fallback is `DD-MM-YYYY` plus 24-hour time.
+
+Mods format captured timestamps through the read-only public facade:
+
+```lua
+local date = mod.datetime:date(game, createdAt)
+local time = mod.datetime:time(game, createdAt)
+local both = mod.datetime:dateTime(game, createdAt)
+```
+
+The live `game` supplies only the current option context. Formatting never
+mutates the save, options, or timestamp, and invalid timestamps return
+`"----"`.
+
+## Device power information
+
+Sandboxed mods can read the host's battery state without receiving the rest
+of `love.system`:
+
+```lua
+local state, percent = mod.device:powerInfo()
+```
+
+`state` follows LÖVE's values: `"unknown"`, `"battery"`, `"nobattery"`,
+`"charging"`, or `"charged"`. `percent` is `0` through `100`, or `nil` when
+the platform cannot report it. The facade is read-only and does not expose
+URL launching, clipboard access, or other system operations.
+
+## Real-world steps
+
+On iOS and Android the game counts the player's real-world steps natively
+(HealthKit / the hardware step counter). A mod reaches that bridge through
+the `steps` permission in `manifest.json`, which the player sees in the
+mod manager like every other permission:
+
+```lua
+if mod.steps:available() then
+  mod.steps:sync()                -- async; OS consent sheet on first use
+end
+-- later, at a quiet moment:
+local walk = mod.steps:poll()     -- { steps = n, from = ?, to = ? } or nil
+```
+
+`available()` is `false` on builds without the bridge (desktop) and for
+mods without the permission, so a probe is always safe. `sync()` asks the
+platform to refresh its count and returns whether there was a bridge to
+ask. `poll()` returns the next delivery for this mod — the engine consumes
+the native side's pending file itself, each permissioned mod receives its
+own copy of a delivery, and steps are anchored natively so the same walk
+is never delivered twice. Without the permission, `sync` and `poll` raise
+an error naming it.
+
+## Background HTTP
+
+`mod.fetch` is how a mod does work off the main thread. It is behind the
+`network` permission in `manifest.json`, the same one that gates
+`require("socket")`, and the player sees it in the mod manager.
+
+```lua
+-- somewhere once
+local job = mod.fetch:get("https://example.com/data.json")
+
+-- in a hook or update, every frame -- poll never blocks
+if job then
+  local r = mod.fetch:poll(job)
+  if r.status ~= "pending" then
+    if r.status == "ok" then use(r.body) else warn(r.err) end
+    mod.fetch:release(job)
+    job = nil
+  end
+end
+```
+
+`get(url, opts)` returns an opaque handle, or `nil` plus a reason. `opts`
+takes `accept` (a request Accept header) and `maxSeconds` (clamped to 30).
+`poll(handle)` returns `{ status, body, err, progress }` where `status` is
+`"pending"`, `"ok"`, `"error"` or `"cancelled"`; it is a copy, and it never
+blocks, so calling it every frame is the intended use. `release(handle)`
+frees a finished job — do it, or you will hit the ceiling. `cancel(handle)`
+drops a result you no longer want. `available()` is `false` when the build
+has no transport and for mods without the permission, so a probe is safe.
+
+The rules worth knowing before you design around it:
+
+- **http and https only.** The underlying transport also speaks `file://`,
+  `ftp://` and `scp://`; those are refused, on the initial URL and on any
+  redirect. `mod.fetch` is not a way to read a local file.
+- **Four requests in flight per mod.** The worker pool is shared with the
+  launcher's own downloads, so one mod cannot fill it. Over the ceiling,
+  `get` returns `nil` and a reason until you release something.
+- **Handles are yours alone.** A handle from another mod, a fabricated
+  table, or a guessed number all poll as `"error"`.
+- **Your mod id is in the User-Agent**, so a server operator can see who is
+  calling and a mod cannot pose as the launcher.
+- Jobs are released when your mod unloads.
+
+This is deliberately not `love.thread`. A LÖVE thread is a fresh Lua state
+with a full standard library that the sandbox cannot reach, so handing one
+to a mod would undo every other rule; `mod.fetch`'s workers run engine
+code, so a mod gets asynchrony without gaining any new reach.
+
+## Log reporting
+
+`mod.postLog(body, opts)` is the one-way exception to the rule that a mod
+decides where it talks. It reports a debug/crash log to the https URL the
+manifest declares in `log_url`, and it is the only API that may not be
+pointed at a caller-chosen address:
+
+```json
+{
+  "permissions": ["network"],
+  "log_url": "https://logs.example.com/receive"
+}
+```
+
+The URL is validated at load: it must be `https://`, and declaring it
+without the `network` permission is a load violation for api 2 mods. The
+destination is reviewed when the mod ships, not chosen per call, so a mod
+cannot aim this at arbitrary hosts or read back anything a server replies.
+
+```lua
+-- fire and forget; poll() never blocks, same shape as mod.fetch
+local job = mod:postLog("session crashed at 0x1f3a\n" .. logText)
+```
+
+`postLog(body, opts)` returns the same opaque handle as `mod.fetch:get`,
+polled and released through `mod.fetch:poll` / `mod.fetch:release`. `opts`
+is a closed list with one switch: `format`, either `"text"` (the default)
+or `"json"`. `json` wraps the body in an envelope of `{ ts, mod, format,
+body }` so a server can attribute and sort reports; any other key or value
+is refused before a job is submitted. The body is capped at 64 KB, the
+transfer is bounded by the same worker ceilings as `mod.fetch`, and the
+response body is never returned to the mod.
+
+## Background jobs
+
+`mod.fetch` covers work waiting on a server. `mod.job` covers work waiting on
+the CPU — generating a map, crunching a table, anything that would otherwise
+stall a frame. It is behind the `background` permission in `manifest.json`.
+
+Ship the job as its own file inside your mod:
+
+```lua
+-- mods/your_mod/jobs/crunch.lua
+local arg = ...
+local total = 0
+for i = 1, arg.n do total = total + i end
+return { total = total }
+```
+
+```lua
+-- in your entry file
+local job = mod.job:run("jobs/crunch.lua", { n = 1e6 })
+
+-- later, in a hook -- poll never blocks
+local r = mod.job:poll(job)
+if r.status == "ok" then
+  use(r.result.total)
+  mod.job:release(job)
+end
+```
+
+`run(script, arg, opts)` returns an opaque handle, or `nil` plus a reason.
+`opts.maxSeconds` sets the job's time budget (default 5, clamped to 30).
+`poll(handle)` returns `{ status, result, err }` with `status` one of
+`"pending"`, `"ok"`, `"error"` or `"cancelled"`. `release(handle)` frees it.
+`available()` is `false` on a host without threads and for mods without the
+permission, so a probe is always safe.
+
+**A job is pure compute.** This is the part to design around, not a detail:
+
+- **Plain data in, plain data out.** Numbers, strings, booleans and tables of
+  them. A function, userdata, a cycle or a table key that is not a string or
+  number is refused at your `run` call with a reason. Nothing is shared —
+  your argument is snapshotted, and mutating the original afterwards does not
+  reach the job.
+- **No engine API, no game state, no storage.** `require` is refused inside a
+  job, and there is no `mod` object. A job cannot read the party, write
+  `mod.storage`, or touch a registry. Get what it needs into the argument and
+  act on the result back on the main thread.
+- **Your script is a file in your mod folder.** The path goes through the same
+  rules as `mod:read`; `..`, absolute paths and drive letters are refused.
+- **Two jobs per mod, four on the machine.** Over the limit, `run` returns
+  `nil` and a reason until you release one.
+- **The budget bounds how long YOU wait, not how long the work runs.** Past
+  `maxSeconds`, `poll` reports an error and the result is dropped if it ever
+  arrives — but the thread runs to its own end. There is no way to stop a
+  LÖVE thread from outside, and every attempt to stop one from inside was
+  worse than the disease (a debug hook does not reliably interrupt LuaJIT,
+  and raising from one wedged the whole process). `cancel(handle)` is the
+  same deal: it drops the result, it does not stop the work.
+
+  So **write jobs that terminate.** A job with an infinite loop will keep one
+  core busy until the game closes. It will not freeze the game — the main
+  thread stays responsive and quitting still works — but nothing will reclaim
+  that core in the meantime.
+
+Your job script runs in the same sandbox your entry file does, so `io`, `os`,
+`debug`, `ffi`, `package` and `love.filesystem` are absent there too. That is
+the whole reason this exists rather than `love.thread`: a raw LÖVE thread is a
+fresh Lua state with a full standard library that the sandbox cannot reach, so
+handing one to a mod would undo every other rule. Here the worker builds your
+sandbox first and loads your chunk into it.
+
+## Pre-sandbox globals (compat)
+
+A mod written before the sandbox landed does not have to be updated to
+load. `io`, `package`, `dofile`, `loadfile`, `os.getenv`, `love.filesystem`,
+`love.system` and `love.event` are all present again as compat stand-ins
+(`src/mods/LegacyCompat.lua`), and assigning a LÖVE callback
+(`love.mousemoved = fn`) installs on the real table the way it always did.
+Every stand-in call logs one warning naming its replacement, and
+`loader:legacyReport(modId)` returns the same list with call counts, which
+is what a "needs updating" badge should read.
+
+The stand-ins are not the old globals. Paths are classified rather than
+passed through:
+
+- A path inside your own mod directory reads the file you shipped.
+- Anything else, including an absolute path, resolves into a private
+  per-mod overlay at `mod_compat/<your id>/` under the save directory.
+  Two mods naming the same path never see each other's bytes, and nothing
+  is written outside the game tree.
+- A read misses through the overlay to your shipped file, then to
+  `mod.storage`, so a half-migrated mod sees both.
+- A write over a path you shipped shadows it; the packaged file is never
+  modified, and `mod:read` still returns the packaged bytes.
+- `love.filesystem.getSaveDirectory()` and `os.getenv("HOME")` answer with
+  a virtual root, so a legacy mod that joins its own paths lands back in
+  the same overlay.
+
+`love.thread` stays refused. A LÖVE thread runs in a separate Lua state
+with the full standard library, which the sandbox in this state cannot
+reach, so a stand-in would be a hole rather than a reroute. The same goes
+for `ffi`, `debug`, `setfenv`, `os.execute`, `io.popen`, `love.run` and
+`love.errorhandler`. A mod that needs real background work needs an
+engine-owned facility, not a compat shim -- for HTTP that facility is
+[`mod.fetch`](#modfetch), which runs on the engine's own worker pool.
@@ -1,553 +1,38 @@
-# New features (deliberate additions beyond the original)
-
-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.
-
-## Survey zoom
-
-The mouse wheel (or `-`/`=`), the Options **ZOOM** row, or hotkey `4`
-zooms the overworld between 1 pixel per world pixel (full survey) and 2×
-the window fit scale (close-up), in crisp integer steps. This has no Game
-Boy equivalent:
-
- Connected maps render their full bodies, and their NPCs appear as
-  visual-only "ghosts",  they wander but have no sight lines, triggers,
-  dialogue, or collision until the map is actually entered.
- Menus, text boxes, and battles draw at normal scale on top of the
-  zoomed world. Zoom input is ignored while a script, menu, or battle is
-  active; the zoom offset is persisted as `save.options.zoom` (default
-  `0` = FIT) and survives New Game via `options.lua`.
- Hotkey `4` ticks through every integer zoom level (survey → FIT →
-  close-up → wrap). The Options row shows `FIT` / `OUTn` / `INn`.
- Beyond the border ring the void fill repeats indefinitely (see VOID
-  FILL below); interiors keep their own border block. Each visible map
-  area is colorized with its own SGB palette (the original recolored the
-  whole screen per map).
- Neighbor maps load two connection hops out so corner-adjacent maps
-  don't pop in and out, and ghost NPCs share instances with the real ones
-  so their wander positions persist across seamless connection crossings
-  (a warp or fresh map entry still respawns everything at its script
-  position, like the original's per-entry sprite init).
-
-## VOID FILL
-
-The Options **VOID FILL** row picks what paints the infinite beyond-edge
-space on OVERWORLD-tileset maps during survey zoom:
-
- **TREES** (default): solid tree wall block `$0F`.
- **WATER**: animated water tile `$14` (same hshift cycle as on-map water).
- **BLACK**: solid black.
-
-Other tilesets are unchanged (house/cave borders stay as authored).
-Persisted as `save.options.voidFill`.
-
-## Tilt mode
-
-The `3` key (and the Options menu TILT row) cycles a visual-only perspective
-tilt of the overworld through **OFF → 15° → 35° → 50° → OFF** for an HD-2D /
-diorama look. Like survey zoom this is purely presentational and has no
-Game Boy equivalent:
-
- The entire map tilts as one rigid ground plane,  paths, grass, water,
-  floors, and every background-tile structure (buildings, trees, fences,
-  signs; in Gen 1 these are baked into the tile layer, not sprites),  so
-  rows above the player recede and rows below come toward the viewer. Only
-  things that actually *stand* on the ground draw as upright billboards,
-  unscaled and pixel-identical to flat mode: the player, NPCs, item balls,
-  and the standing FX attached to them (emote bubbles, the fishing rod,
-  the FLY bird). The Poké Center heal-machine overlay stays on the ground
-  plane with the machine tiles (it is OAM glued to a BG graphic, not a
-  standing sprite). An earlier revision tried
-  billboarding buildings/trees/signs too (cutting them out of the ground
-  per hand-curated per-tileset tables); that chased an endless tail of
-  special cases,  dense tree canopy, fences fused into grass, building
-  facades with their own baked-in fake perspective,  because Gen 1's art
-  was never drawn with a clean seam between ground and standing scenery. It
-  wasn't merged; tilting everything but the characters as one plane is the
-  simpler, shipped tradeoff (buildings recede/foreshorten with the ground
-  like a photo of a diorama, rather than standing fully upright next to
-  a full-height character).
- Cycling tweens the angle between levels over ~0.25s rather than snapping;
-  with tilt fully off the world pass drops back onto the flat blit path, so
-  flat rendering stays pixel-identical to tilt-off and off costs nothing.
- Tilt input is gated exactly like survey zoom,  honored only while
-  free-roaming, ignored while a script, menu, or battle is active,  and it
-  composes with survey zoom (the zoom scale feeds the projection). The tilt
-  level is persisted in `save.options.tilt` (default OFF).
- It applies everywhere the overworld draws, interiors and caves included.
-  Menus, text boxes, and battles render flat on top, unaffected, and the
-  infinite beyond-the-border-ring fill stays flat by design.
- Collision, movement, sight lines, triggers, encounters, and scripts are
-  untouched; nothing about the tilt reaches gameplay.
-
-## Colors mode
-
-The `2` key (and the Options menu COLORS row) cycles the display mode
-through **OG RED → SGB → ADVANCED → OG → OG INV → SGB INV → CLASSIC → OG RED**
-(on Blue the first slot labels **OG BLUE**; on Yellow, **OG YELLOW**).
-The first three are the real colorizations; the rest are DMG-shade novelties:
-
- **OG RED** / **OG BLUE**: the Game Boy Color boot-ROM look for that cart --
-  one global BG palette + one OBJ palette, every map, no per-map variation
-  (Red/Blue ship no CGB code, so on a GBC the boot ROM colors them globally).
-  The player/NPCs keep the boot-ROM OBJ color over the terrain via the OBP
-  bake + post-zone redraw (`PaletteFX.GBC_BG` / `GBC_OBJ`, or Blue's blue/pink
-  pair).
- **OG YELLOW** (Yellow playthrough, same `ogred` save id): Pokemon Yellow's
-  authentic GBC look from `CGBBasePalettes` (`data/palettes_yellow.lua`,
-  sourced from pret/pokeyellow). Per-map / per-species colors, not a single
-  boot-ROM ramp -- Yellow was CGB-enhanced.
- **SGB** (default): the per-map Super Game Boy region palettes
-  (`data/sgb/sgb_palettes.asm`). Sprites tint with the region palette, as on
-  real SGB. (This is the mode formerly mislabeled "GBC".)
- **ADVANCED**: pokered-gbc SuperPalettes -- real per-tile GBC coloring plus
-  per-species mon colors (`data/palettes_gbc.lua`). (Formerly labeled
-  "RED++"; it is the richest colorization rather than anything Red-specific.)
- **OG**: force the four DMG grays (colorization off).
- **OG INV**: inverted DMG grays.
- **SGB INV**: each SGB zone palette with shade order reversed.
- **CLASSIC**: original Game Boy pea-soup greens
-  (`#9BBC0F` / `#8BAC0F` / `#306230` / `#0F380F`).
-
-The shade-remap transform is applied centrally in `PaletteFX.sendColors`, so
-it covers overworld, menus, battles, and tilt upright billboards. OG RED's
-global BG palette is supplied by `OverworldState:overworldBgColors` (per-map
-override in the overworld pass). Persisted as `save.options.colors`; the
-`gbc` / `gbc_inv` / `redpp` save ids are kept for back-compat under the new
-labels.
-
-## GBC FX
-
-The `5` key (and the Options menu GBC FX row) cycles a "played on real
-unlit-GBC hardware" post-process through **OFF → 1 → 2 → 3 → 4**. The
-levels are a cumulative ladder:
-
- **1**: reflective-screen backing transparency.
- **2**: + LCD pixel grid.
- **3**: + pixel drop shadows.
- **4**: + sunlight glare and rainbow shimmer with a drifting light.
-
-It runs as a final present pass after world + UI composite in
-`Renderer:endFrame`, inspired by the Pixel Transparency RetroArch shader
-([github.com/mattakins/Pixel_Transparency](https://github.com/mattakins/Pixel_Transparency)).
-Default OFF; persisted as `save.options.gbcfx`.
-
-Mobile GPUs often compile the pass but present a black frame, so Android and
-iOS hide the row entirely, pin the level to OFF, and rewrite a level already
-persisted in `options.lua` (issue #136). `POKEPORT_GBCFX` overrides that
-decision either way, same tri-state as `POKEPORT_TOUCH`: `=0` refuses the
-effect, `=1` forces it available. The Anbernic handheld pack exports `0` from
-its launcher because the device reports `"Linux"` while its GPU is in the
-phone class (see [Anbernic RG34XXSP](anbernic-rg34xxsp.md)).
-
-## Performance tier (low-end devices)
-
-The Options **PERFORMANCE** row scales the port's optional presentation
-extras down for weaker hardware. The extras it governs are the three
-heaviest things the port adds on top of the original -- the whole-screen 3D
-**TILT** (transforms the entire map as a ground plane), the **GBC FX**
-post-process shader (a fullscreen pass), and survey **ZOOM** (zooming out
-renders the connected neighbor maps, a lot of extra overdraw) -- plus a hard
-FPS ceiling. None of this touches game logic, which is fixed-step off `dt`
-(`src/core/FixedStep.lua`), so every tier plays identically; they differ
-only in how much eye-candy the renderer is allowed to do.
-
-| Tier         | TILT | GBC FX | Survey ZOOM | Extra FPS ceiling |
-| ------------ | ---- | ------ | ----------- | ----------------- |
-| **HIGH**     | on   | on     | on          | none              |
-| **BALANCED** | off  | off    | on          | none              |
-| **LOW**      | off  | off    | off         | 60                |
-| **AUTO**     | picks a default from the device (below) |||
-
- **AUTO** (the default) reads the device once at boot: ARM Linux handhelds
-  (e.g. the RG34XXSP) resolve to **LOW**, phones/tablets and very-low-core
-  desktops to **BALANCED**, and everything else -- a normal desktop, and
-  every existing `options.lua` that predates this option -- to **HIGH**,
-  so the common case is unchanged. See `src/core/Performance.detect`.
- AUTO only chooses the *default*; all four tiers are selectable, so a
-  wrong guess is one row away from being overridden.
- The clamps are applied **live** against your stored options and never
-  rewrite them (`Game:applyOptions`), so a lower tier hides your TILT / GBC
-  FX / ZOOM without forgetting them -- raising the tier restores exactly
-  what you had. (This is why the TILT / GBC FX / ZOOM rows still show your
-  saved choice on a clamped tier: it's your preference, waiting for a tier
-  that can afford it.)
- Persisted as `save.options.performance` (`auto` | `high` | `balanced` |
-  `low`); unit-tested in `tests/engine/performance_tiers.lua`.
-
-## Peer-to-peer link play (lua-enet)
-
-Trades and link battles connect two copies of the game directly over
-lua-enet (ENet ships inside LÖVE,  nothing to install, no server to run)
-on a reliable-ordered channel, replacing the original standalone Python
-room-code relay (`tools/relay_server.py`, deleted). HOST A GAME shows the
-host's LAN address (UDP 7777; `POKEPORT_LINK_PORT` overrides); JOIN A
-GAME enters it. Closing performs a graceful ENet disconnect so the final
-confirm/bye always lands; a vanished peer exits with "The link was
-broken." Internet play needs a forwarded UDP port or a VPN (deliberate
-tradeoff vs. the relay). Headless tests drive the protocol over an
-in-memory loopback (`Net.loopbackPair`); under LÖVE the same test file
-also exercises real UDP pairing.
-
-Red, Blue, and Yellow copies link with each other, as the real cable
-does. The compatibility fingerprint hashes only data a link mode can
-actually read, so Yellow's Dragonair/Dragonite catch-rate retunes (the
-only R/B/Y link-surface difference) no longer read as different games
-(issue #511). Moving the fingerprint is a link parity change: builds
-from before this fix will refuse to pair with builds after it.
-
-## Fair play in link and online matches
-
-A link session is decided by the battle and nothing else, so for its
-duration:
-
- **Game speed is pinned to normal.** The GAME SPEED option and
-  `POKEPORT_SPEED` are ignored from the moment LINK PLAY opens until it
-  closes, and apply again after. Fast-forward otherwise runs one peer's
-  queue faster than the peer it is locked to and drains a tournament shot
-  clock faster than the opponent racing it.
- **Online play runs vanilla, 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
-  divergence there ends the match as a draw. `volatile` carries per-turn
-  flags both sides recompute anyway - a divergence there is logged and
-  reported to mods, and play continues.
-
-The relay logs which component diverged on which turn, so a desync report
-names something specific.
-
-## Custom boot text
-
-The boot sequence replaces the Nintendo / GAME FREAK identifiers with
-"bois club" / "bryanthaboi",  a deliberate branding customization. The
-rest of the boot beats (copyright splash, "presents" shooting-star, the
-Nidorino-vs-Gengar attract scene) mirror the original.
-
-
-## Custom Options
-
-Options persist in a standalone `options.lua` (separate from the game
-progress `save.lua`), so audio/display/battle preferences survive New Game
-and aren't wiped when a save slot is cleared. Changing a row in the Options
-menu or cycling hotkeys `2`/`3`/`4`/`5` writes immediately; an in-game save also
-flushes the live options. Old saves that still embed an `options` table are
-migrated once into `options.lua` on load.
-
- Music / SFX volume
- PIKACHU VOL (0-7, Yellow only): trims Pikachu's PCM voice clips under the
-  SFX level, so the follower's constant chatter, the title-screen cry and
-  every in-battle "Pika!" can be pulled down (or muted at 0) without
-  quieting the rest of the sound effects. The row is hidden on Red/Blue,
-  which have no voice clips.
- Music Filter
- OG GLITCHES on / off (Gen 1 quirks vs. modern-clean battle rules)
- BATTLE LAYOUT (OG / WIDE); see "Widescreen battle layout" below
- COLORS (OG RED / SGB / ADVANCED / OG / OG INV / SGB INV / CLASSIC),  also
-  hotkey `2` (OG RED = GBC boot-ROM look; ADVANCED uses pokered-gbc
-  SuperPalettes + per-species mon colors)
- TILT (OFF / 15 / 35 / 50),  also hotkey `3` while free-roaming
- ZOOM (FIT / OUTn / INn),  also hotkey `4` while free-roaming; wheel and
-  `-`/`=` step one level and save
- VOID FILL (TREES / WATER / BLACK) for OVERWORLD beyond-edge space
- GBC FX (OFF / 1 / 2 / 3 / 4),  also hotkey `5`
- MAX FPS (30 / 40 / 50 / 60 / 75 / 90 / 100 / 120 / 144 / 160, default 60),
-  a hard render frame-rate cap (`save.options.fpsCap`).
-
-## Battle transition cascade + white battle letterbox
-
-Into-battle wipes still run the original eight styles inside the classic
-160×144 letterbox. On wide/tall windows (survey zoom), matching black 8×8
-blocks cascade outward from that square into the surrounding world so the
-void outside the OG wipe fills in lockstep. Once the battle state is up,
-letterbox voids around the battle canvas fill **white** instead of black
-so the whole window reads as one continuous battle screen.
-
-## Widescreen battle layout
-
-Options **BATTLE LAYOUT** picks the battle screen's composition: **OG**
-(the default: the original 160×144 arrangement, unchanged) or **WIDE**,
-which gives battles a 304×144 native-pixel surface and a Gen 3-style
-arrangement on it:
-
- the foe's status box upper left, the foe's picture upper right;
- the player's picture lower left, the player's status box lower right,
-  with a longer HP bar and the numeric HP under it;
- a full-width message window;
- a split "What will X do?" prompt / 2×2 command window;
- a 2×2 move menu, navigated with all four directions, with a PP and type
-  panel attached to its right.
-
-Only the composition changes. Pictures, palettes, HP-bar colors, font
-pages, window borders, sounds, animations, timing and every battle rule
-stay the engine's, so a COLORS mode or an asset mod still owns the look.
-Each side's picture keeps its original pixels and placement math and is
-composited into its own region of the wider battlefield -- nothing is
-scaled or squeezed -- and animations, which are authored in the original
-160-pixel space, shift as one rigid group onto whichever side they play
-on. The whole screen is drawn at the window's integer fit scale for the
-wider surface, so a 304-pixel screen is drawn a step smaller than a
-160-pixel one in the same window.
-
-The wide surface is live only while the battle itself is the screen on
-top: a party menu, the bag or a nickname prompt is a 160×144 screen and
-brings the classic surface back with it.
-
-## On-screen touch controls (mobile)
-
-On Android/iOS the game draws a translucent d-pad (bottom-left), A/B
-buttons (bottom-right, Game Boy diagonal), and +/- START/SELECT (bottom
-center) over the frame, using Xelu's CC0 controller prompts
-(`assets/touch/`). Real buttons, not gestures: press lands the frame the
-finger does, sliding on the d-pad changes direction without lifting, and
-multi-touch chords (e.g. hold a direction + tap B) work. The overlay only
-appears while no controller is being used: the first gamepad button or
-stick push hides it, the next screen touch brings it back, and unplugging
-the last controller restores it immediately. Layout re-derives from the
-window size on rotation. Desktop testing: `POKEPORT_TOUCH=1 love .` forces
-the overlay on and lets the mouse act as a finger (`=0` forces it off).
-
-The launcher's **Touch Controls** button opens a drag editor: move each
-button freely, 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
-
-Every string the player can read is now reachable from a mod, so a
-translation is an ordinary content mod rather than a fork.
-
-Two things had to change. Text layout stopped counting bytes: the dialogue
-box measures a line in glyphs (charmap sequences), so a 3-byte character
-costs one column, a cut never lands inside a character, and a page with a
-non-default `advance` re-measures instead of overflowing. That also fixed
-25 vanilla English lines that were wrapping early because `é` in POKéMON
-and POKéDEX costs two bytes ("I study POKéMON as" is 19 bytes and 18
-glyphs, and the box was breaking it).
-
-Second, the text the engine writes itself - battle messages, item results,
-menu labels, the link-play screens - moved behind `src/core/Strings.lua`
-and the new `strings` registry. Extracted script text was already
-overridable through `text`; this covers the other half. Entries are keyed
-by the English source, so a translation that has not reached a string yet
-keeps rendering in English and a half-finished translation stays playable.
-
-Authors generate the whole thing:
-
-```sh
-python3 tools/modkit.py translation francais --language "Francais"
-```
-
-That scaffolds a mod with every translatable string as an empty catalog,
-plus a glyph-page and charmap stub, a naming-grid stub, and a
-`francais-worksheet/` directory holding the English to translate from
-(deliberately outside the mod: extracted text is ROM content and must not
-be packed). `--refresh` re-harvests after an engine update, keeping
-existing translations and parking orphaned keys rather than dropping them.
-
-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)
-
-The save editor ships inside every build instead of being a developer-only
-script, and the launcher's SAVE SLOT card grows an **Edit** label next to
-Delete on every slot that actually holds a save. Edit suspends the
-launcher, opens that slot's file in the editor, and **Close** hands the
-process back to the launcher with the slot list re-read (a rename, a badge
-or a dex change shows up on the row immediately). Unsaved edits arm a
-confirm first, so leaving cannot lose work. `love . --editor` still opens
-it standalone, where Close quits instead; `--save <path>` points it at any
-file, and a save can be dragged onto the window.
-
-The editor now wears the launcher's visual language - the same navy radial
-field, 16px translucent cards, tri-colour version rail and green/yellow/red
-semantics - so the two windows read as one app. Six tabs:
-
- **Party**: the roster with sprites, HP bars and level chips on the left,
-  and the mon inspector permanently docked on the right instead of floating
-  over the list. Species, level, DVs and moves all round-trip through the
-  Gen 1 formulas, so the inspector can never show illegal stats.
- **Boxes**: the 12 PC boxes as a 5x4 grid with a fill meter per box and a
-  party dock, so deposit and withdraw live in one place. Empty slots are
-  clickable and create a mon there.
- **Items**: money, a searchable item picker (replacing the arrows that
-  cycled one id at a time through ~250 items), the configurable bag (20 slots
-  by default), PC storage
-  with no slot cap, and the eight badges as toggle chips. 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,
-  and the player / lastHeal / lastOutdoor spawn points settable by clicking
-  a cell. Setting lastOutdoor on a map the game would not accept as an
-  outdoor source is refused with the reason.
- **Dex**: seen / owned completion meters and a four-column grid; owning
-  implies seen and un-seeing clears owned, exactly as the game requires.
-
-Two rules run through all of it. Every mutation goes through one funnel
-that sets the dirty flag and writes the status line together, so nothing
-changes silently and no branch can quietly no-op - "Party is full", "Bag is
-full", "click a cell first" all say so. And every destructive verb (Remove,
-Release, Clear all, Wipe dex) arms on the first click and commits on the
-second, relabelling itself to `Confirm?` in between.
-
-A validation pill in the tab rail mirrors what the running game would
-quarantine on load; clicking it jumps to the tab holding the first problem.
-
-## Tiled map editing (mod authoring)
-
-`tools/tiled_export.py` turns the imported ROM cache into a Tiled workspace,
-so maps can be edited in a real map editor and exported back out as a mod.
-It has its own document: docs/tiled-map-editing.md.
-
-## Pokédex diploma (both versions)
-
-The Celadon Mansion 3F game designer shows the dex-completion diploma
-once 150 species are owned. On Yellow, the graphic artist next to him
-then offers to print it, saving the certificate as a PNG under `prints/`
-in the save directory, and Bill's PC gains Yellow's PRINT BOX item which
-exports the current box list the same way.
-
-## Pokédex printing (Yellow)
-
-Yellow's Game Boy Printer PRNT option in the Pokédex side menu is stood in
-for by an image export: choosing PRNT renders the mon's entry page (sprite,
-kind, number, height/weight, dex text) to a PNG at 4x scale under
-`prints/` in the save directory, then reports the filename in a dialog.
-No printer hardware or link cable emulation involved; the file is the
-printout.
-
-## Find Mods (community mod indexes)
-
-A FIND MODS tab sits beside MODS in the launcher and browses a published
-mod index: a metadata-only feed listing mods that live in their authors'
-own repositories. No index ships with the launcher and none is ever added
-automatically, so the tab opens on an "Add an index" prompt until you name
-one; paste an index URL or its `owner/repo` and it is remembered in
-`options.lua`. More than one index can be added, and the listings merge.
-
-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
-a Game Boy's power switch did, dropping straight back to the title screen.
-It works from anywhere, including mid-battle, which the QUIT entry on the
-start menu cannot do: the original combo is how stationary and gift
-Pokemon get their stats rerolled without sitting through a full relaunch.
-Unsaved progress is discarded, exactly as on hardware.
-
-As on the original, the four buttons have to stay held for 16 straight
-polls (better than a quarter of a second) and any direction in the mix
-cancels it, so it is hard to hit by accident -- including on the on-screen
-touch controls, where it would take four fingers held on four separate
-controls.
-
-## Controls rebinding (CONTROLS screen)
-
-OPTIONS -> CONTROLS lists every Game Boy button with its current keyboard
-key and controller button side by side (Z/A). Press A on a row, then press
-and release the key or pad button you want; the rebind commits on the
-release. If that input already belongs to another row, the two rows swap,
-so no button is ever stranded without an input and no input ever serves
-two buttons. Holding a second key or pad button while the first is still
-down backs out of the capture without touching a keyboard; Escape still
-cancels too. SELECT clears one row back to its default, and START resets
-every binding after a confirmation.
-
-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.
+# New Features
+
+Features intentionally added beyond the original Pokémon Red, Blue, and Yellow games:
+
+* **Survey zoom** with connected-map rendering and configurable void fill
+* **Perspective tilt mode** for an HD-2D-style overworld
+* **Multiple color modes**, including original, SGB, advanced GBC, monochrome, and classic green
+* **Optional GBC screen effects**, including pixel grids, shadows, glare, and transparency
+* **Performance presets** and configurable FPS limits
+* **Peer-to-peer link play** for trades and battles between Red, Blue, and Yellow
+* **Persistent custom options** stored separately from game saves
+* **Optional widescreen battle layout**
+* **Mobile touch controls** with editable layouts, vibration, and orientation settings
+* **Translation and custom font support**
+* **Built-in save editor** for parties, boxes, items, events, maps, and Pokédex data
+* **Tiled map editing tools** for mod authors
+* **Pokédex diploma and printer image exports**
+* **Community mod browser**
+* **Soft reset button combination**
+* **Keyboard and controller rebinding**
+* **Mod profiles** with separate mod settings and save slots
+* **Sandboxed mods**: an installed mod can read only its own folder and write only its own storage
+* **Improved launcher and save editor UI**, including background downloads and update checks
+* **Direct-launch options** for shortcuts, Steam entries, and handheld frontends
+
+## Pokémon Gold (Gen 2)
+
+* **COLOR, zoom, tilt, GBC FX, and quick save/load** 
+* **UI that stays fixed while the overworld zooms**
+* **Border-block surrounds** for maps smaller than the screen
+* **Gold-specific launcher options**
+* **Optional widescreen battle layout**
+* **Skippable trade animation** with B or START
+* **QUIT and EXIT GAME** from the menus
+* **Mod manager** with Gen 1 mod adapters, per-game targeting, and `modkit gen2check`
+* **Followers** for mods, plus Gen 2-only registries and hooks
+* **On-screen touch pad** and controller SELECT for registered items
+* **Older mods keep loading** after the sandbox change, through per-mod compat stand-ins for the pre-sandbox globals
@@ -0,0 +1,798 @@
+# Preparing your mod for Gen 2 (Gold)
+
+You have a mod that works on Red, Blue or Yellow, and you want it to work on
+Gold. This is the migration guide: what breaks, what the engine papers over
+for you, what it refuses to paper over, and the order to do the work in.
+
+`docs/mod-api-gen2-compat.md` is the reference for *what Gold serves*. This
+document is the procedure for *getting your mod there*. Read that one when you
+need to know whether a registry or a hook exists; read this one first.
+
+## What actually breaks, and why
+
+Gold is not a skin over the Gen 1 engine. It is a second engine living beside
+the first one: `src/core/Game2.lua` owns the boot, `src/world/gen2/World.lua`
+is the overworld, `src/battle/gen2/Battle.lua` is the battle, and
+`src/script/gen2/Vm.lua` runs the cart's own bytecode instead of a Lua row
+list. A Gold boot never loads `src/core/Game.lua`,
+`src/world/OverworldController.lua` or `src/battle/BattleState.lua` at all.
+The mod API on top is deliberately one API -- the same registry names, the
+same hook names, the same event names, the same `mod.*` facade -- so a mod
+that stays on that surface mostly moves across unchanged. What does not move
+is everything underneath it.
+
+The failure that motivated all of this is quiet, which is what makes it worth
+a whole document. A mod with `engine_internals` writes
+`local Game = require("src.core.Game")` and patches a method on it. Under Gold
+that require used to succeed: the file is on disk, `require` finds it, hands
+back a perfectly good module table, and your patch lands on it. Nothing ever
+instantiates that table, so the patch runs zero times and the only symptom is
+that your mod does nothing. No error, no warning, no crash to bisect. Two
+things fixed that. First, a mod is not loaded on a Gold boot unless it says it
+is for Gold, so the default outcome is "not running" rather than "running
+wrong". Second, when it does say so, a require made from your own file is
+answered by an adapter (`src/mods/Gen2Compat.lua`) that presents the Gen 1 API
+over Gold's internals, and a member the adapter cannot honestly back reads nil
+instead of reading plausibly-wrong.
+
+## Step 1: run the checker before you change anything
+
+`modkit gen2check` reads your manifest, statically scans every `.lua` the
+package carries, and cross-references what it finds against the adapter's own
+coverage table. Run it first, because it tells you the size of the job in a
+few seconds.
+
+```sh
+python3 tools/modkit.py gen2check <id-or-path> [<id-or-path>...]
+```
+
+Real output, against a follower mod written for Yellow:
+
+```
+-- PokePCFollowers_VoxelMerge: api 1, profile content, no games declared, permissions engine_internals, 0 dependencies, game_version unset
+MK400 ERROR manifest.json: no Gen 2 game in "games" (and no gen2compat), so a Gen 2 boot skips this mod; the rest of this report is what it would hit once it claims one
+MK404 ERROR main.lua:575: BattleState.newWild has no Gen 2 backing: Gold has no factory that returns an unpushed battle, and World:startBattle constructs and pushes in one call. A mod that wraps newWild to rewrite the species must be pointed at the encounter.species hook, which Gold raises with the same name and shape (World:rollEncounter); this reads nil
+MK404 ERROR main.lua:576: BattleState.newWild has no Gen 2 backing: ... ; nothing on a Gen 2 boot reads this write
+MK409 WARN  main.lua:13: allow-lists a Gen 1 version string, which excludes this mod from a Gen 2 game by construction; test for the capability the code needs instead of the version
+MK409 WARN  main.lua:424: ... (same, a second allow-list)
+MK409 WARN  main.lua:565: ... (and a third)
+modkit: unresolved: 1 site: requires whose result is neither bound to a name nor indexed here, so where the module goes is not followed (main.lua:221)
+modkit: unresolved: 5 debug upvalue calls whose target function this scan could not tie to an engine module, so the local they reach could not be resolved (main.lua:279, main.lua:285, main.lua:288, main.lua:321 and 1 more)
+modkit: src.world.PikachuFollower.onMapEntered closes over 'shouldSpawn' on a Gen 2 boot, so the upvalue surgery at main.lua:325 lands as it does on Gen 1
+FAIL PokePCFollowers_VoxelMerge on gen 2: will not work (3 errors, 3 warnings)
+```
+
+Three kinds of line, and the difference matters:
+
+- **`MK4xx ERROR` / `MK4xx WARN`** are findings with a file and a line. Errors
+  set the exit code; warnings do not unless you pass `--strict`.
+- **`modkit:` notes** are things the tool derived rather than found, or could
+  not decide at all. They never change the exit code. The `shouldSpawn` note
+  above is the tool resolving that member through the adapter on a Gen 2 boot,
+  enumerating the function's real upvalues, and confirming the surgery lands;
+  the `unresolved:` notes are the tool naming, with file and line, every reach
+  it saw and could not follow.
+- **The verdict**: `will load`, `will load but degrade`, or `will not work`.
+
+The rule ladder:
+
+| rule | what it means |
+| --- | --- |
+| `MK400` | the manifest claims no Gen 2 game, so a Gen 2 boot skips the mod |
+| `MK401` | a dependency claims no Gen 2 game, which takes you down with it |
+| `MK402` | you require a Gen 1-only module the adapter does not serve |
+| `MK403` | a Gen 2 boot runs a `gen2/` sibling of the module instead |
+| `MK404` | a member you touch has no Gen 2 backing (the adapter's own reason is quoted) |
+| `MK405` | a member you touch degrades and says so once |
+| `MK406` | the signature moved under an alias |
+| `MK407` | `debug` upvalue surgery the Gen 2 arm cannot take: the member is not a function there, or the function does not close over that local |
+| `MK408` | upvalue surgery the scan could not resolve either way |
+| `MK409` | a version allow-list, or a Gen 1 screen id |
+| `MK410` | the entry chunk reads a member of a game that is not up yet |
+
+Flags: `--strict` promotes warnings to failures, `--notes` prints the adapter's
+note for every *backed* member you touch (worth reading once per mod, because
+several backed members are backed with a caveat), `--json` emits one document
+for the whole batch, `--quiet` drops everything except the findings -- no
+header, no notes, no verdict line, so a clean mod prints nothing at all and the
+exit code is the whole answer. Exit code is 0 clean, 1 on a fatal finding, 2 on
+usage.
+
+Name several mods in one invocation and they are read as one install set, so a
+mod and its dependencies can answer each other's `MK401`.
+
+**What the checker cannot see, and now says so.** It is a static scan, not a
+run. It follows more than it used to -- a require made through your own
+`tryRequire`-style wrapper, `local ok, M = pcall(require, "...")`, an inline
+`require("src.world.Map").waterTiles(...)`, a bracket index `M["member"]`, a
+local hop `local F = M` -- so reaches that used to be invisible now produce
+real findings, and a mod that passed before can fail now.
+
+Two places where it used to answer confidently and wrongly now do not.
+`local A, B = require("src.world.Map")` is read as binding `A`, which is what
+Lua does; it used to take the name nearest the `=` and pin the module on `B`,
+so every reach off `A` went unchecked and every reach off `B` was checked
+against a module that was never there. And a helper of your own is only read as
+upvalue surgery when the scan can see it forward its own `(function, name)`
+pair into the `debug` call; a helper that merely mentions `upvalue`, or that
+finds the slot by walking `debug.getupvalue`, no longer has its call sites
+read as naming an engine local, because they do not.
+
+What it still cannot follow it names instead of ignoring. Every unfollowed
+reach comes back as an `unresolved:` note carrying a file and a line. The scan
+side raises one for:
+
+- a require name built at runtime, whether handed in whole or concatenated
+  (`require("src.world." .. name)` is as unfollowable as `require(name)`);
+- an engine module name handed to a call the scan does not follow;
+- an engine module name spelled in a literal with no require attached;
+- a require whose result is neither bound to a name nor indexed on the spot;
+- a require in a multiple assignment whose value it cannot pair to a name;
+- a name bound to a *member* of a module rather than the module;
+- an engine module indexed with a computed key;
+- `rawget` or `rawset` on a bound module: that goes straight to the table the
+  require shim hands back, so on a Gen 2 boot it reads or writes the
+  Gen2Compat facade and not the module behind it;
+- an engine module read as a value rather than indexed, so where it goes from
+  there (a table field, a call argument, a metatable's `__index`) is not
+  followed;
+- a `debug` upvalue call whose target function could not be tied to a module;
+- a call through one of your own upvalue helpers that the scan could not
+  confirm carries an upvalue name through to the `debug` call.
+
+Four more come from the coverage side rather than the scan: a dependency that
+is not installed beside your mod, a required name that is neither an adapter
+nor a module in this checkout, a module with no coverage row at all, and a Gen
+1 member the coverage table does not classify.
+
+The practical consequence is worth stating plainly: an empty finding list
+*plus* no `unresolved:` notes now means the scan followed everything it saw,
+and an empty finding list on its own does not.
+
+It is still silent on any member the adapter's coverage table does not record:
+the table lists 481 members across the 15 served modules, which is a large
+majority of what real mods touch and is not the whole Gen 1 API. A clean
+`gen2check` means "nothing known-broken was found", not "this works". Boot it.
+
+## Step 2: declare which games the mod is for
+
+Nothing moves on disk. A mod is installed once, into `mods/<id>/`, and that one
+directory serves every game. There is no `mods/gen1/`, no `mods/gen2/`, and no
+per-generation copy: targeting is something the manifest *declares*, not
+something the filesystem encodes.
+
+```json
+{
+  "id": "my_mod",
+  "name": "My Mod",
+  "version": "1.0.0",
+  "entry": "main.lua",
+  "api": 2,
+  "games": ["gen1", "gen2"]
+}
+```
+
+`games` is an optional array. Each entry is one of:
+
+| token | means |
+| --- | --- |
+| `"red"`, `"blue"`, `"yellow"`, `"gold"` | that one game (a version id from `GameVersion.ORDER`) |
+| `"gen1"`, `"gen2"` | every game of that generation (case-insensitive; `"gen 2"` also parses) |
+| `"all"` | every game this engine has |
+
+`src/mods/ModTargets.lua` is the one place those tokens are resolved, and it
+derives the list from `GameVersion.ORDER` rather than restating it, so a game
+added later needs no edit there. The scaffold writes the key for you:
+
+```sh
+python3 tools/modkit.py scaffold my_mod --games gen1,gen2
+```
+
+**Omitting `games` keeps the old meaning exactly.** No `games` key means Gen 1
+only, plus Gen 2 if the legacy `"gen2compat": true` flag is set. Every manifest
+written before the key existed means precisely what it always meant.
+`gen2compat` is still accepted and is purely additive: it *adds* the Gen 2
+games to whatever `games` says, so no manifest can lose a game it already ran
+on. `Manifest.validate` (`src/mods/Manifest.lua:210-224`) resolves the two
+into one ORDER-sorted `manifest.games` array and derives `manifest.gen2compat`
+from it, which is why `"games": ["gen2"]` is honoured by the loader's gate
+today with no other change.
+
+An unknown token warns and is dropped under `api` 1 and refuses the manifest
+under `api` 2 (the normal `violation()` rule). A `games` array that names no
+game this engine knows falls back to the default rather than orphaning the mod.
+A non-array `games` is a hard error.
+
+### What you are claiming
+
+Adding a game to `games` is you saying *I have run this there*. It is not a
+request for best-effort support and the loader does not treat it as one: a mod
+that claims a game is loaded on that boot in full, with its registrations, its
+subscriptions and its entry chunk, exactly like a mod written for it. If it is
+half-working, the player sees a broken mod, not a partially-supported one. That
+is the whole reason the key exists rather than being inferred.
+
+**Every token is enforced, per game.** `Loader:_gateGeneration`
+(`src/mods/Loader.lua:447`) gates on `ModTargets.supports(manifest, version,
+generation)` -- the same call both mod surfaces make -- so `"games": ["blue"]`
+really does not load on Red, and the skip line is the launcher's line, `For
+Blue, not Red`. `"games": ["gold"]` alone no longer loads on Red either: it
+names one game, and that game is Gold. A manifest with no `games` and no
+`gen2compat` still covers every Gen 1 game, so nothing written before the key
+existed changes behavior; what changed is that a version-id token is now a
+statement the boot keeps rather than a label the UIs draw. If you want a mod
+everywhere, say so: `["gen1", "gen2"]` or `["all"]`.
+
+**Dependencies are contagious.** A mod whose hard dependency does not run here
+is left out too, carrying the dependency's own wording (`depends on X, which
+does not run here (For Blue, not Red)`). It is reported as a skip rather than a
+failure and neither mod lands on the boot error list, but the mod does not run.
+Every hard dependency in the chain has to cover the same games; `MK401` is the
+checker's version of this question for the Gen 2 half of it.
+
+**The player can overrule you, in one direction only.** The in-game mod
+manager offers `TRY HERE ANYWAY` on the detail pane for any mod that does not
+claim *this* game (`src/mods/ManagerState.lua:386`), which now includes a Gen 1
+boot: a Blue-only mod is genuinely skipped on Red, so that row is the only way
+to run it there. The choice is **per game**: `options.modsGen2[id]` is a
+`{ [version] = true }` table, so forcing a mod onto Red does not force it onto
+Gold. A stored legacy `options.modsGen2[id] = true` from before the key was
+per-game reads as "the Gen 2 games", which is the only set it could ever have
+affected, and it is expanded in place the next time the player answers. A
+forced mod loads normally and keeps a note saying its author never verified it
+here; the launcher shows it as `Forced onto Gold by you (untested)`. If the
+override cannot be persisted the manager says `COULD NOT SAVE` rather than
+promising a restart that would change nothing.
+
+### What the player sees
+
+All three surfaces read the same derivation -- the two UIs and the loader --
+so they cannot disagree about your mod. The launcher's mod panel carries a
+`Show for:` chip row (All games / Red / Gold / ...) and a per-mod tag from
+`ModTargets.chip` -- `GEN 1`, `GEN 1+2`, `RED/GOLD`, `BLUE` -- greyed out when
+the mod does not run on the selected game, with the line `Not for this game`
+(`src/import/LauncherView.lua:320`) and the detail from `ModTargets.detail`,
+`For Gen 1, not Gold`. The in-game manager shows the same thing as
+`ENABLED (NOT THIS GAME)` with the skipped glyph, plus an inert `FOR GEN 1+2`
+row on the detail screen. The launcher's dependency verdict asks the same
+question of your dependencies: a mod whose hard dependency does not run on the
+selected game reads `Needs <id> (not for Gold)` rather than `Ready`.
+
+### Scoping dependencies per game / generation
+
+For mods targeting multiple generations (`"games": ["gen1", "gen2"]`), a hard
+dependency can be scoped to specific games so that it is only enforced when
+booting those games:
+
+```json
+"dependencies": [
+  { "id": "pokegear_cards", "games": ["gen2"], "range": "^1.0.0", "github": "1jamie/pokegear_cards" }
+]
+```
+
+When booting a Gen 1 game (Red, Blue, Yellow), the engine loader sees that
+`pokegear_cards` is scoped to `"gen2"` and will not skip or block the parent mod
+on Gen 1. When booting Gen 2 (Gold), `pokegear_cards` is strictly required.
+
+For conditional integrations where the dependency is optional across the board,
+`optional_dependencies` remains the standard pattern.
+
+### One limit worth knowing
+
+**Enablement is per game.** The overlay
+`options.modsByVersion[version][id]` is read and written through
+`SaveData.modEnabled` / `SaveData.setModEnabled` by the launcher, in-game
+manager, and loader. Existing shared settings are copied to every game the
+first time this version sees the installed mods; from then on, each coloured
+game checkbox changes only that game's next boot. Nothing about this affects a
+mod author; it affects what a player can express.
+
+Targeting is a different question from enablement and *is* enforced per game,
+as above. The two do not share a switch.
+
+## Step 3: prefer the API over the modules
+
+Before doing any adapter work, check whether you need the modules at all. In
+new code, take the live game from `mod.game` and the world from `mod.world`.
+Both resolve per generation inside the loader (`src/mods/Loader.lua:1021`):
+`mod.game` is `src/core/Game.lua`'s singleton under Gen 1 and the `Game2`
+*instance* Gold injected under Gen 2, read on every touch rather than cached;
+`mod.world` is `src/world/WorldAPI.lua` or `src/world/gen2/WorldAPI.lua` behind
+one method set. Neither needs `engine_internals`. The `game.ready` payload and
+every `ui.*` hook's first argument carry the same live game.
+
+Anything you can express as a registry write, a hook or an event subscription
+is generation-agnostic already and needs nothing from this document. The
+adapter exists for the code that was written before Gold did, and for the small
+number of things the API genuinely does not reach.
+
+## Step 4: the adapter, module by module
+
+On a Gen 2 boot with mods present, `require` is interposed
+(`Loader:_installDevShim`, `src/mods/Loader.lua:184`) and a require *made from
+a mod's own chunk* for one of fifteen Gen 1 names is answered by
+`src/mods/Gen2Compat.lua`. Engine code is unaffected: the shim compares the
+caller's chunk name against the engine tree, so `src/render/PaletteFX.lua`
+requiring `src.core.Game` still gets the real Gen 1 module on both generations.
+This is not a dev-mode feature; it installs on any Gold boot that has mods.
+
+| the name you require | kind | what you get | backed / warned / absent |
+| --- | --- | --- | --- |
+| `src.core.Game` | facade | a live proxy onto the `Game2` instance | 70 / 9 / 12 |
+| `src.world.OverworldController` | facade | over `src/world/gen2/World.lua` | 56 / 5 / 68 |
+| `src.world.Map` | alias | `src/world/gen2/Map.lua` | 28 / 2 / 9 |
+| `src.world.NPC` | alias | `src/world/gen2/Npc.lua` | 27 / 0 / 1 |
+| `src.pokemon.Boxes` | facade | over `src/core/gen2/Boxes.lua` | 22 / 0 / 0 |
+| `src.battle.BattleState` | facade | over `src/ui/gen2/BattleState.lua` | 16 / 2 / 39 |
+| `src.ui.PartyMenu` | facade | over `src/ui/gen2/PartyMenu.lua` | 15 / 2 / 16 |
+| `src.world.WorldAPI` | alias | `src/world/gen2/WorldAPI.lua` | 15 / 2 / 0 |
+| `src.world.PikachuFollower` | alias | `src/world/gen2/Follower.lua` | 10 / 0 / 11 |
+| `src.script.ScriptRunner` | facade | over `src/script/gen2/Vm.lua` | 10 / 7 / 1 |
+| `src.ui.OptionsMenu` | facade | over `src/ui/gen2/OptionsMenu.lua` | 8 / 0 / 1 |
+| `src.world.FieldDefaults` | facade | the `playerSprites` answer and named refusals | 5 / 2 / 3 |
+| `src.world.Collision` | facade | `DELTA` / `target` / `occupied` / `canMove` | 4 / 1 / 0 |
+| `src.ui.StartMenu` | facade | over `src/ui/gen2/StartMenu.lua` | 4 / 0 / 0 |
+| `src.ui.BoxMenu` | alias | `src/ui/gen2/PcMenu.lua` | 1 / 0 / 0 |
+
+**Alias means the adapter *is* the Gen 2 module.** Your monkey-patch, your
+`rawset` sentinel and your `==` idempotency check all land on the table Gold
+actually runs, and `getmetatable(npc) == NPC` is true. Five names are aliases
+because nothing less would work: mods set their own trailer's metatable to
+`src.world.NPC`, a mod is handed `world.map` rather than building one, the
+loader builds every `mod.world` out of `src.world.WorldAPI` so a copy would
+give two, `src.world.PikachuFollower` is reached with `debug.setupvalue` on a
+file-local, and `Screens` caches `src.ui.BoxMenu` for `"Gen2PcMenu"` so a
+`.new` patch has to land there.
+
+Note that `src.ui.BoxMenu` points at `src/ui/gen2/PcMenu.lua`, not at
+`src/ui/gen2/BoxMenu.lua`. Gen 1's `BoxMenu` is Bill's PC *top menu*, whose
+Gold counterpart is `PcMenu`; Gold's `BoxMenu` is the withdraw/deposit *list*
+that Gen 1 builds inline.
+
+**Facade means a translating wrapper.** `.overworld` resolves `Game2.world`,
+`writeOptions` resolves `Game2:persistOptions`, `game.data.sprites` resolves
+`data.gen2Sprites`, `NPC.new(data, mapId, objDef)` is sniffed apart from
+`NPC.new(mapId, objDef, spriteDef)` and the movement vocabulary is translated
+with it. The four UI facades (`PartyMenu`, `StartMenu`, `OptionsMenu`,
+`BattleState`) are write-through: reads fall to the Gen 2 class and **writes go
+to the Gen 2 class**, so `PartyMenu.update = wrapper` still patches the live
+class Gold pushes. Your write also *reads back as your own value* -- after
+`PartyMenu.new = wrapper`, `PartyMenu.new` is `wrapper` and nothing else, so
+`rawequal` holds and an idempotency check works. That is what makes the ordinary
+capture-and-chain idiom safe: a wrapper that calls the value it captured reaches
+Gold's real constructor rather than re-entering the facade's own override.
+Writing `nil` clears the member instead of re-exposing the override underneath.
+
+The `src.world.OverworldController` facade is a facade over the live `World`,
+not over a class, so seven of its fields (`map`, `player`, `npcs`, `entities`,
+`ghosts`, `npcPool`, `camera`) read **and write** through to the running world:
+Gen 1's module *is* the singleton, so a write has to land somewhere real. A
+write made before a world exists is dropped with a warning rather than
+shadowing the world it would have applied to.
+
+### backed, warned, absent
+
+The adapter publishes what it covers, and the checker consumes that same table
+rather than a copy of it. Exactly three statuses, and a member listed as both
+resolves to the weaker one:
+
+- **`backed`** -- present, and it does the Gen 1 job on Gold. Read the note
+  anyway where there is one: several backed members are backed with a caveat
+  (`Boxes.COUNT` is 14 on Gold and not 12; `BattleState.say` ignores
+  `sayAuto`'s delay because Gold's messages always auto-advance;
+  `Collision.DELTA` is Gold's live table, so adding a key mutates Gold's own
+  movement).
+- **`warned`** -- present, answers nil or degrades, and names itself once in
+  the log with your mod attributed. `Game.renderer`, `Game.load`,
+  `Game.step`, `game.data.field`, `game.data.constants`,
+  `ScriptRunner.resume` / `.update` / `.parallel`, `PartyMenu.tmhm` and
+  `OverworldController.neighbors` / `.npcByIndex` are here. `neighbors` is the
+  shape of the whole category: Gold's rows are `{ id, ox, oy, image }` where
+  Gen 1's are `{ map = mapDef, ox, oy }`, so the field warns and answers nil
+  rather than handing back a list whose `nb.map` is nil on every row.
+- **`absent`** -- deliberately not on the table. It reads nil, which is the
+  honest failure. `BattleState.newWild`, `OverworldController.rollEncounter`,
+  `Map.warpPadOrHoleAt`, `PikachuFollower.shouldSpawn` and 157 others are
+  here. (`shouldSpawn` is absent as a *module member* on both generations: it
+  is a file-local, reached through `setShouldSpawn` or the upvalue of that
+  name, and the coverage table says so rather than implying a field exists.)
+
+"Absent" means *not served*, not *wrong*. Every one of them was left off for a
+stated reason, and the reason is in the coverage note. `BattleState.newWild` is
+the clearest case: Gold has no factory that returns an unpushed battle, because
+`World:startBattle` constructs and pushes in one call, so a `newWild` taking a
+species and a level would be a lie about what Gold's battle screen is. The
+route for the thing you were actually doing (rewriting the species of a wild
+encounter) is the `encounter.species` hook, which Gold raises under the same
+name with the same shape.
+
+A member the table does not record is not a guarantee of anything. What it does
+depends on the adapter: an alias hands you the Gen 2 module's own member,
+whatever that is; a write-through facade falls to the Gen 2 class; the
+`src.core.Game` facade names it in the log and reads nil; the
+`src.world.OverworldController` facade reads nil silently. The checker is
+silent about it too.
+
+### Reading the coverage yourself
+
+The table is queryable, and it is the same query the checker makes:
+
+```lua
+local Gen2Compat = require("src.mods.Gen2Compat")
+
+Gen2Compat.modules()                 -- the 15 served names, sorted
+Gen2Compat.serves("src.world.Map")   -- true
+Gen2Compat.memberStatus("src.battle.BattleState", "newWild")  -- "absent"
+
+local c = Gen2Compat.coverage("src.world.Map")
+-- { module, kind = "facade"|"alias", target, members = { [name] = status },
+--   notes = { [name-or-topic] = "one line" } }
+```
+
+`Gen2Compat.COVERAGE_VERSION` is 1 and `Gen2Compat.STATUS` carries the three
+status strings. `notes` keys are documentation topics, not a member list:
+dotted paths (`save.money`), field names (`warpAt`), hook names
+(`hook ui.pc.items`) and bare topics (`identity`, `iteration`, `rawset`) all
+appear there. `members` is the authoritative set.
+
+To dump the lot for one module:
+
+```sh
+luajit -e 'package.path="./?.lua;"..package.path
+local G=require("src.mods.Gen2Compat")
+local c=G.coverage("src.world.OverworldController")
+for m,s in pairs(c.members) do print(s,m) end
+for k,v in pairs(c.notes) do print("note",k,v) end'
+```
+
+## The patterns no adapter can fix
+
+Five shapes come up in nearly every real Gen 1 mod, and none of them can be
+fixed on the engine side without lying to you. Each one has a route that works
+on both generations.
+
+### 1. A hardcoded version allow-list
+
+```lua
+local v = GameVersion.get()
+if v ~= "red" and v ~= "blue" and v ~= "yellow" then return false end
+```
+
+This excludes you from Gold by construction, and it does so *after* everything
+else in your mod has been made to work, which is why it produces the most
+confusing possible outcome: the adapter resolves, your patches land, and the
+feature still never appears. `MK409` catches it.
+
+**Instead**, test for the thing the branch actually depends on. If it is there
+because a member might be missing, test the member:
+
+```lua
+local Follower = require("src.world.PikachuFollower")
+if Follower.setShouldSpawn then ... end   -- present on Gold, absent on Gen 1
+```
+
+If it is there because a piece of per-cart content might be missing, test the
+content -- `mod.find` and the merged data tables answer that in both games.
+Version tests stay legitimate for genuinely per-cart *content*, which is what
+Yellow's starter rename is; they are never right as a gate on a whole feature.
+
+### 2. String-matching a screen id
+
+```lua
+if id == "BoxMenu" then ... end
+```
+
+Gold's builtin screens are registered under `Gen2`-prefixed ids, so this
+matches nothing there. `Screens.GEN2_IDS` in `src/ui/Screens.lua` is the full
+list, 51 ids: `Gen2BoxMenu`, `Gen2PartyMenu`, `Gen2NamingScreen`,
+`Gen2Credits` and 47 more. `MK409` catches this exact line: it keys off the
+string literal itself, not off a screen-shaped word elsewhere on the line, so
+`if id == "BoxMenu" then` is flagged where it used to slip through. The price
+of that is deliberate breadth -- any literal equal to a Gen 1 screen id with a
+`Gen2` twin is warned about, wherever it appears -- so the message states what
+is true of the literal rather than guessing what the surrounding code meant.
+It is a warn, and reading past a false one costs you nothing.
+
+**Instead**, either match both ids, or stop matching ids and take the seam the
+screen offers. Most screens a mod wants to decorate raise a hook whose name is
+shared across both generations -- `ui.start_menu.items`, `ui.options.rows`,
+`ui.party.submenu`, `ui.pc.items`, `ui.naming.grid`, `ui.list_menu` -- and a
+hook subscription needs no id at all. Where you genuinely must key off the id:
+
+```lua
+local BOX_IDS = { BoxMenu = true, Gen2PcMenu = true }
+if BOX_IDS[id] then ... end
+```
+
+Watch the pairing. `ui.pc.items` has the same name on both sides but a
+different menu behind it: Gen 1 raises it over the WHICH-PC list, Gold over
+Bill's PC's own rows. And Gen 1's `BoxMenu` pairs with `Gen2PcMenu`, not with
+`Gen2BoxMenu`.
+
+### 3. `debug.setupvalue` on an engine local
+
+```lua
+local idx = findUpvalue(PikachuFollower.update, "shouldSpawn")
+debug.setupvalue(PikachuFollower.update, idx, myPredicate)
+```
+
+This only ever worked because the Gen 1 file happened to hold that predicate in
+a file-local of that name. Nothing about the engine promises it, and on the Gen
+2 side the local has to exist under the same name and hold the same thing for
+the surgery to land. Today it does: `src/world/gen2/Follower.lua:23` declares
+`local shouldSpawn` for exactly this reason, so follower mods reaching for it
+work unchanged on Gold. That is a deliberate courtesy, not a contract.
+
+`MK407` fires in the two cases where the surgery cannot land: when a Gen 2 boot
+resolves the member to something that is not a function (so `debug.setupvalue`
+raises), and when the function it does resolve to does not close over that
+name, in which case the message quotes the upvalues it *does* close over. The
+check resolves the member through the adapter exactly as the loader does and
+enumerates the resolved function's real upvalues, so a local that merely
+appears somewhere in the Gen 2 file is never mistaken for one -- that used to
+be the check, and it blessed surgery that landed on nothing. `MK408` fires when
+the scan could not resolve the member either way, which is what you get when
+`luajit` is not on `PATH`: the check degrades to an honest warn, never to a
+reassuring note.
+
+**Instead**, use the named seam when there is one, and fall back only when
+there is not:
+
+```lua
+if Follower.setShouldSpawn then
+  Follower.setShouldSpawn(myPredicate)      -- Gen 2, and any future Gen 1 arm
+else
+  patchUpvalue(Follower.update, "shouldSpawn", myPredicate)   -- Gen 1 today
+end
+```
+
+`Follower.setShouldSpawn` writes the same cell `debug.setupvalue` reaches, so
+the two cannot disagree. Note the presence test is doing real work:
+`src/world/PikachuFollower.lua` has no `setShouldSpawn`, so this is not a
+rename you can apply blindly. Note also that the predicate is called
+`(game, world)` on Gold where Gen 1 passes `(game, ow)` -- the same object under
+a different name, so a predicate reading `ow.player` or `ow.map` is unchanged.
+
+### 4. Capturing state off `src.core.Game` at file scope
+
+```lua
+local Game = require("src.core.Game")
+local save = Game.save          -- nil forever
+local party = Game.save.party   -- error at load
+```
+
+The module require itself is fine and is meant to be: the Gen 2 `src.core.Game`
+is a proxy that reads the live `Game2` instance on *every* touch, precisely so
+that a mod capturing it at file scope, before a save or a world exists, keeps
+working once they do. What does not survive is capturing a *field* off it at
+file scope, which snapshots nil. This is true on Gen 1 as well; Gold just makes
+it bite more often because the entry chunk runs earlier relative to the world.
+`MK410` catches the file-scope read of a member the Gen 1 module only ever
+writes as `self.<name>`.
+
+**Instead**, read through the facade at the moment you need the value, or take
+the live game from the `game.ready` payload:
+
+```lua
+local Game = require("src.core.Game")
+mod.events:on("game.ready", function(ev)
+  local game = ev.game            -- the real Game2 instance
+  local party = Game.save.party   -- read now, not at file scope
+end)
+```
+
+Three further properties of the proxy that a Gen 1 mod can trip over, all
+recorded in the coverage notes:
+
+- **Identity.** The proxy can never compare equal to the `Game2` instance the
+  `game.ready` payload carries. Lua 5.1 fires `__eq` only when both operands
+  share a metatable, so `Game == ev.game` is false on Gold. Do not use it as
+  an idempotency check.
+- **Iteration.** `pairs`, `next` and `rawget` see an *empty* table, because the
+  proxy holds nothing of its own. Enumerate the `game.ready` payload instead.
+- **`rawset`.** `rawset(Game, k, v)` lands on the proxy, reads back correctly
+  through the same facade, and is completely invisible to the engine. That
+  read-back is what hides it. Use a plain assignment, which writes through to
+  the live instance.
+
+The save layout moved too, and those fields are absent rather than aliased so
+that a wrong read is loud rather than silent: `save.money` is
+`save.player.money`, `save.player.map` / `.x` / `.y` / `.facing` are
+`save.position.*`, and `save.player.rival` is `save.rival.name`. `save` itself
+is a straight pass-through on purpose.
+
+### 5. Monkey-patching a class, and the two ways it goes wrong
+
+Patching a shared class method is *supported*, and this is worth stating
+plainly because it is the thing most authors expect to have to rewrite. The
+four UI facades write through: `__newindex` forwards to the Gen 2 class, so
+
+```lua
+local PartyMenu = require("src.ui.PartyMenu")
+local origUpdate = PartyMenu.update
+function PartyMenu.update(self, dt) ... return origUpdate(self, dt) end
+```
+
+lands on the class Gold actually pushes. Aliases are the class, so the same
+holds there.
+
+Two variants do not work, and neither can be made to.
+
+**Patching a member the Gen 2 class does not have.** The write succeeds, reads
+back as your own function, and nothing ever calls it. `BattleState.newWild =
+wrapper` is the canonical case: the assignment is taken, and no Gold code path
+reads that name. This is the one place the read-back works against you, which
+is why `MK404` reports the write site separately from the read site.
+
+**Patching a field on a live instance.** `menu.onSwitch = fn` writes a field
+Gen 2 never reads -- Gold takes it as `onChoose` at construction. Same for
+`menu.swapFrom` (renamed `switchFrom`) and for `StartMenu`'s `tx` / `ty` / `tw`
+/ `th` / `anchor` / `maxVisible`, which do not exist on Gold at all because the
+box is fixed at `Chrome.box(10, 0, 10, h)`. A write to any of them is inert.
+Pass what you need to `.new` instead: `PartyMenu.new(game, { onSwitch = f })`
+with no `battle`, `pickOnly` or `forceSwitch` opens the plain list and calls
+`onSwitch(mon, menu)` on A, which is the Gen 1 behavior the facade reproduces.
+
+A close relative worth calling out because it errors rather than no-ops:
+`map.warpAt` is a name collision, not a rename. Gen 1's is a *table* keyed by
+cell; Gold's `Map:warpAt` is a *method* of the same name. `map.warpAt[cell]`
+and `pairs(map.warpAt)` both raise, which is loud but points at your mod.
+Enumerate `map.warps`, which Gold carries as an ordered array.
+
+## A worked migration
+
+Here is one real one, start to finish. The mod is a follower pack written for
+Red/Blue/Yellow. `gen2check` reports `MK400` on the manifest, `MK404` twice on
+`BattleState.newWild` and `MK409` on a version allow-list, plus a note
+confirming its `shouldSpawn` surgery lands.
+
+**Before.** Three separate problems in about twenty lines.
+
+```lua
+local BattleState      = require("src.battle.BattleState")
+local PikachuFollower  = require("src.world.PikachuFollower")
+local GameVersion      = require("src.core.GameVersion")
+
+return function(mod)
+  -- (1) rewrite the starter encounter's species
+  local origNewWild = BattleState.newWild
+  BattleState.newWild = function(game, species, level, ...)
+    if species == "PIKACHU" and level == 5 then species = "CHARMANDER" end
+    return origNewWild(game, species, level, ...)
+  end
+
+  -- (2) decide whether a follower spawns
+  local newShouldSpawn = function(game, ow)
+    local v = GameVersion.get()
+    if v ~= "red" and v ~= "blue" and v ~= "yellow" then return false end
+    return packSize(game) > 0
+  end
+
+  -- (3) install it
+  patchUpvalue(PikachuFollower.update,       "shouldSpawn", newShouldSpawn)
+  patchUpvalue(PikachuFollower.onMapEntered, "shouldSpawn", newShouldSpawn)
+end
+```
+
+On Gold: (1) assigns onto a name nothing reads, so the species rewrite never
+happens. (2) returns false for every Gold boot, so no follower ever spawns.
+(3) actually works, and works on a predicate that has already decided to do
+nothing. Two silent failures and one correct mechanism pointed at them.
+
+**After.** The manifest gains `"games": ["gen1", "gen2"]`, and:
+
+```lua
+local PikachuFollower = require("src.world.PikachuFollower")
+
+return function(mod)
+  -- (1) the species of a wild encounter is a hook on both generations
+  mod.hooks:wrap("encounter.species", function(next, enc, ctx)
+    local rolled = next(enc, ctx)
+    if rolled and rolled.species == "PIKACHU" and rolled.level == 5 then
+      rolled.species = "CHARMANDER"
+    end
+    return rolled
+  end)
+
+  -- (2) no cart check: whether there is a pack to walk is the whole question
+  local newShouldSpawn = function(game, ow)
+    return packSize(game) > 0
+  end
+
+  -- (3) the named seam where there is one, the upvalue where there is not
+  if PikachuFollower.setShouldSpawn then
+    PikachuFollower.setShouldSpawn(newShouldSpawn)
+  else
+    patchUpvalue(PikachuFollower.update,       "shouldSpawn", newShouldSpawn)
+    patchUpvalue(PikachuFollower.onMapEntered, "shouldSpawn", newShouldSpawn)
+  end
+end
+```
+
+`gen2check` now reports clean, and the mod is shorter than it was on Gen 1
+alone. That is the usual shape of this work: two of the three fixes replace
+engine surgery with an API that existed the whole time, and only the third
+needs a generation branch.
+
+The one change that is *not* a simplification is the hook's contract. A wrapper
+takes `(next, ...)` and must call `next` with the arguments it was handed, where
+the monkey-patch could do as it liked with them. `encounter.species` transforms
+a rolled `{ species, level }` and gets a `ctx` beside it: Gen 1 fills in
+`mapId`, `terrain` and `rng`, and Gold adds `daytime`, `environment`, `kind`
+(`"wild"` / `"contest"` / `"script"` / `"sweet_scent"`), `tables` and `data`.
+So the same
+subscription serves both games, and a Gold-only refinement is a field test
+rather than a second hook. That is the trade: a narrower seam that both engines
+raise, in exchange for not owning a function neither engine promised you.
+
+## Testing
+
+**Headless, without a Gold cache.** The SDK harness takes the generation
+directly, and everything after that is the production path -- same loader, same
+validate, same topological sort, same merge:
+
+```lua
+local run = T.sdk.loadMod("mods/my_mod", { generation = 2 })
+T.eq(run.mod and run.mod.state, "loaded",
+  "runs on gen 2: " .. tostring(run.mod and run.mod.skipReason))
+T.eq(#run.errors, 0, "and loads with no boot errors")
+run.release()
+```
+
+**Assert the state, not just the error count.** A gate skip is deliberately not
+an error: `Loader:_skip` sets `mod.state` and `mod.skipReason` and stays off
+`loader.errors`, because neither the mod nor its dependency has a bug. So
+`T.eq(#run.errors, 0)` on its own passes for a mod that never ran a line, which
+is the one result you were testing to rule out. `run.mod.state` is `"loaded"`
+when the entry chunk ran and `"wrong_generation"` when the gate or the
+dependency contagion took it, with `run.mod.skipReason` carrying the sentence
+the manager would show. Keep the error assertion too: it is what catches a
+registry with no Gen 2 home and a require the adapter does not serve, both of
+which *do* land on `loader.errors`.
+
+**On a real Gold boot.** Nothing above substitutes for running it. Import Gold
+in the launcher, enable your mod, and play the part your mod touches. Be
+precise about where the adapter talks to you, because the two channels are not
+the same:
+
+- **The log** carries the adapter's own warnings, each attributed to the mod
+  holding the facade (`[my_mod] Game.renderer has no Gen 2 backing: ...`), so a
+  member that degraded tells you which one and why. `Gen2Compat.warnOnce` goes
+  to `Logger.warn` and nowhere else -- these do **not** appear in the manager.
+- **The manager's error feed** (`loader.errors`) is a shorter list: a mod that
+  failed validation, a duplicate mod id, a registry with no Gen 2 target, a
+  cross-validation problem, and the one adapter-adjacent case, a require for a
+  Gen 1 module the adapter does not serve. A skipped mod is not on it, and
+  neither is a degraded member.
+
+So: read the log for coverage problems, and the manager for load problems.
+
+`POKEPORT_IDENTITY=<name>` sandboxes the save directory if you want a clean
+profile to test in, and `POKEPORT_DEV=1` adds the console and `F5` hot reload.
+
+## What this guide does not promise
+
+- **Coverage is partial and will stay partial.** 15 Gen 1 modules are served
+  out of a much larger engine, and within those 15 the coverage table records
+  291 backed members against 32 warned and 161 absent. The absent ones are not
+  a backlog; most are absent because there is no honest Gen 2 answer, and each
+  one carries its reason. The counts move as the adapter learns something: a
+  member that turns out to answer nil is demoted from backed to warned or
+  absent rather than left flattering the table.
+- **Absent is not broken, it is not-served.** A nil read is the designed
+  outcome. If you would rather have an error, test for the member before you
+  use it.
+- **The checker is a static scan.** It cannot follow a require built at
+  runtime, cannot tie every `debug` call to a module, and says nothing at all
+  about a member the coverage table does not record. What it *can* do is admit
+  each of those individually, with a file and a line, as an `unresolved:` note.
+  Read the notes as part of the report: a clean finding list with notes under
+  it means "nothing known-broken was found in the part I could follow", and
+  only a clean finding list with no notes means the scan followed everything.
+- **A backed member can still surprise you.** `backed` means the adapter took
+  responsibility for the Gen 1 call shape, not that Gold behaves identically.
+  Run `gen2check --notes` once and read the caveats on the members you touch.
+- **The adapter is not a compatibility layer for new code.** It exists so mods
+  written before Gold existed keep working. If you are writing something now,
+  `mod.game`, `mod.world`, the registries and the hooks mean the same thing in
+  both games and need none of this.
@@ -1,96 +0,0 @@
-# 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.
@@ -1,38 +1,66 @@
-# Build the Nintendo Switch NRO — contributor guide
+# Build Gen1Recomp for Nintendo Switch

 Want to play a release build instead? Download the SD-ready zip and extract it
-at your microSD root — see [switch-install.md](switch-install.md).
+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.
+> Releases ship `gen1recomp-*-switch.zip` (SD tree under `switch/gen1recomp/`).
+> Runtime target is pinned [love-nx](https://github.com/retronx-team/love-nx)
+> `11.5-nx1`. Player install and limitations: [switch-install.md](switch-install.md).

 ---

 ## Prerequisites by OS

 All packaging entrypoints are **bash**. On Windows, use Git Bash, MSYS2, or
-WSL — not cmd.exe or PowerShell (AD-008).
+WSL, not cmd.exe or PowerShell (AD-008).

 ### macOS / Linux

 1. Install [devkitPro pacman](https://devkitpro.org/wiki/devkitPro_pacman).
-2. Install Switch tools:
+2. Install Switch tools (**required for `--fused`**):

   ```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).
+3. OTA launcher toolchain, **native or Docker** (either is fine):

-**Optional:** Install [Docker](https://docs.docker.com/get-docker/) so fused
-builds can fall back to the pinned image when native tools are missing.
+   ```sh
+   bash scripts/switch/install_devkitpro_deps.sh   # native
+   # or install Docker (same pin as fused builds)
+   ```
+
+4. Ensure `DEVKITPRO` is exported (typical macOS: `/opt/devkitpro`) and
+   `nacptool` / `elf2nro` are on `PATH` (or under `$DEVKITPRO/tools/bin`).
+
+Fused game builds can also use Docker when native `nacptool`/`elf2nro` are absent.
+
+### Native OTA launcher (included in `--fused`)
+
+In-console OTA uses a **separate DEVKITPRO NRO** (not LÖVE). The LÖVE
+self-updater (`Check.lua`) is disabled on NX. Source:
+`ports/switch/ota-launcher/`. Host protocol tests (no toolchain):
+
+```sh
+make -C ports/switch/ota-launcher host-test
+# or
+scripts/switch/build_ota_launcher.sh   # host-test first; NRO needs DEVKITPRO/Docker
+```
+
+`--fused` always builds the fused game, native OTA launcher, and dual-NRO SD
+zip. The same `*-switch.zip` is the OTA download asset. **DEVKITPRO is
+required.** OTA launcher: native packages **or** Docker. Both are supported.
+
+Release-like build from repo root:
+
+```sh
+scripts/build_switch.sh --fetch --fused --version X.Y.Z
+```
+
+See `ports/switch/ota-launcher/README.md` and
+`scripts/switch/ota_launcher.manifest`.

 ### Windows (Git Bash / MSYS2 / WSL)

@@ -42,16 +70,15 @@ builds can fall back to the pinned image when native tools are missing.
   - **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).
+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 |
+| bash, git, zip tooling the repo already expects | (none) |
+| `dkp-pacman` + `switch-dev` + OTA packages **or** Docker | `dkp-pacman -S …` |
 | A legal `.gb` ROM (to play) | Any ROM or game data |

 ---
@@ -64,12 +91,12 @@ builds can fall back to the pinned image when native tools are missing.
 | ---- | ------------ |
 | `--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**. |
+| `--fused` | Builds fused game NRO, OTA launcher NRO, and dual-NRO SD zip. **Requires DEVKITPRO** + `switch-dev`. OTA launcher: native packages or Docker. GitHub Releases publish the **zip only**. |

 Rules:

 - `--fetch` alone is fine; combine as `--fetch --loose` or `--fetch --fused`.
- `--loose` and `--fused` are **XOR** — pick one packaging path per run.
+- `--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
@@ -109,13 +136,15 @@ 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
+# Fused game + OTA launcher + dual-NRO SD zip for a release-like artifact
 scripts/build_switch.sh --fetch --fused --version 0.2.0
 ```

 Outputs land under `dist/switch/` (and `dist/switch/loose/` for loose mode).
-The fused path also writes `gen1recomp-<ver>-switch.nro.sha256` and
-`gen1recomp-<ver>-switch.zip` (+ `.sha256` sidecar for the zip).
+The fused path also writes `gen1recomp-<ver>-switch.nro` (game),
+`gen1recomp-<ver>-launcher.nro`, `gen1recomp-<ver>-game.nro`,
+`gen1recomp-<ver>-switch.nro.sha256`, and `gen1recomp-<ver>-switch.zip`
+(+ `.sha256` sidecar for the zip).

 Offline packaging smoke (no network, no nacptool required):

@@ -143,7 +172,7 @@ the NX runtime modules `src/core/NxAssetOverlay.lua`, `src/core/Platform.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):
+1. **Offline selftest** on `ubuntu-latest` (forks **and** the main repo):
   `scripts/switch/selftest_build_switch.sh`,
   `scripts/switch/verify_payload.sh --self-test`,
   `luajit tests/switch_ci_workflows_test.lua`,
@@ -151,14 +180,10 @@ or the Switch-related workflow YAML), CI runs:
   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
+2. **Fused NRO build** only on the **main** repository
   (`bryanthaboi/gen1recomp`), on the self-hosted Mac runner
   (`scripts/build_switch.sh --fetch --fused`), and only when the workflow
-   head is that repo (same-repo push/PR). **Fork 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.
+   head is that repo (same-repo push/PR). Fork CI never runs fused. Fork PRs into the main repo also skip Switch fused (offline selftest still runs) so untrusted head code is not executed on the self-hosted Mac; iOS device build eligibility is unchanged. Fused also waits for a successful offline selftest before starting on the Mac runner.
 3. On successful PR fused builds, a follow-up workflow posts a PR comment
   linking the Actions artifact named `gen1recomp-switch-nro`
   (comment tag `switch-build-result`; see
@@ -169,7 +194,7 @@ 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`):
+other platforms. This is a **hard gate** (no `continue-on-error`):

 ```sh
 scripts/build_switch.sh --fetch --fused --version "<release version>"
@@ -181,9 +206,26 @@ A Switch packaging failure fails the entire release job. The release asset is

 ### 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.
+The self-hosted Mac runner **must** have **DEVKITPRO** installed and exported.
+`--fused` preflight fails early with setup steps if it is missing.
+
+**One-time setup on the runner** (if not already present):
+
+```sh
+# devkitPro pacman installer from https://devkitpro.org/wiki/devkitPro_pacman
+sudo dkp-pacman -S switch-dev
+export DEVKITPRO=/opt/devkitpro
+export PATH="$DEVKITPRO/tools/bin:$PATH"
+
+# OTA launcher: pick one
+bash scripts/switch/install_devkitpro_deps.sh   # native
+# or ensure Docker is installed (same pin as fused builds)
+```
+
+CI and release still run `scripts/build_switch.sh --fetch --fused`. Preflight
+requires DEVKITPRO and either native OTA packages or Docker. Without all of
+that, the job fails with the setup steps above. Scripts never auto-run
+`dkp-pacman -S` during CI.

 ---

@@ -194,11 +236,9 @@ 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
+- 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).
+[switch-transfer.md](switch-transfer.md).
@@ -1,528 +0,0 @@
-# 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`)
-
@@ -1,187 +0,0 @@
-# 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
-```
@@ -2,15 +2,11 @@

 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
+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.
+> This project does not help you set that up.

 Prefer building from source? See [switch-build.md](switch-build.md).

@@ -29,12 +25,18 @@ help from [booshankles](https://github.com/booshankles).
 Extract the zip at the **root** of the microSD so you get:

 ```text
-sdmc:/switch/gen1recomp/gen1recomp.nro
+sdmc:/switch/gen1recomp/gen1recomp.nro          # native OTA launcher (hbmenu entry)
+sdmc:/switch/gen1recomp/gen1recomp-game.nro     # fused LÖVE game
+sdmc:/switch/gen1recomp/version.txt
 sdmc:/switch/gen1recomp/pokemon-love2d/imports/
 sdmc:/switch/gen1recomp/pokemon-love2d/imports/mods/
 sdmc:/switch/gen1recomp/pokemon-love2d/imports/saves/...
 ```

+Older single-NRO zips only had `gen1recomp.nro` (the fused game). Current
+releases use the dual-NRO layout above. Open `gen1recomp` in hbmenu (the
+launcher).
+
 Merge folders if your OS asks. Any method works: **MTP** (DBI → Run MTP
 responder + a client), **direct SD** (Hekate UMS or a card reader), or **FTP**.
 Exit MTP / unmount / stop FTP cleanly before launching. Step-by-step for
@@ -42,17 +44,44 @@ 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.
+#### Native OTA launcher (in-console)
+
+Switch OTA runs in a separate **native launcher NRO** (libnx + curl), not the
+LÖVE self-updater (`src/update/Check.lua`). hbmenu opens `gen1recomp.nro`.
+
+When a newer release exists, the launcher downloads the same install zip
+(`gen1recomp-*-switch.zip`), checks SHA-256 against `sha256sums.txt`, replaces
+both `gen1recomp-game.nro` and `gen1recomp.nro` (keeps NACP version in sync
+for hbmenu and Sphaira), then loads the game with `envSetNextLoad`.
+
+If you are up to date or offline, it skips straight to the game with no
+prompt. If an update is available, you get a short prompt styled like the
+in-game launcher: black background, RGB rail, logo, A/B buttons. Saves under
+`pokemon-love2d/` are not touched. See `src/update/SwitchOta.lua` for the
+wire format.
+
+The LÖVE self-updater stays **disabled** on NX (`networkValidated == false`).
+
+**Sphaira forwarder (HOME shortcut):** Sphaira copies name/version/icon into
+the installed forwarder at creation time. After an OTA (or zip) update, the
+`.nro` on the microSD already has the new version, but the HOME shortcut
+keeps the old badge until you **reinstall the forwarder once** in Sphaira
+(Install Forwarder again on `gen1recomp.nro`). Browsing the NRO in Sphaira /
+hbmenu always shows the live file version.
+
+#### Manual zip (fallback)
+
+Use the **same** extract/merge of `gen1recomp-*-switch.zip`. It replaces the
+NROs (and the small help `README.txt` / `INSTALL.txt` files). Saves,
+imported ROMs, mods, and options live under `pokemon-love2d/`. **Do not
+delete that folder** when updating, or you will lose progress.

 ## 3. Launch with title override

 **Applet Mode is not supported** for this game (not enough memory).

 1. On the Switch HOME menu, highlight any installed title.
-2. Hold **R** and launch that title — this opens hbmenu with full memory
+2. Hold **R** and launch that title. This opens hbmenu with full memory
   (title override).
 3. From hbmenu, open `gen1recomp`.

@@ -66,14 +95,14 @@ This project ships **no** game data. On first launch:
   (`.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
+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**:
+SD / FTP, same transfer methods as ROMs. Paths are **per game**:

 | Game | Import inbox | Export folder |
 | ---- | ------------ | ------------- |
@@ -81,19 +110,19 @@ SD / FTP — same transfer methods as ROMs. Paths are **per game**:
 | Blue | `imports/saves/blue/` | `exports/blue/` |
 | Yellow | `imports/saves/yellow/` | `exports/yellow/` |

-(Under the save dir `pokemon-love2d/` — the zip already creates these folders.)
+(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
+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** →
+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.
+   from that game's **`exports/<game>/`** folder via MTP / SD / FTP.

-Do not put `.sav` files into git. Prefer clean copies — some MTP clients
+Do not put `.sav` files into git. Prefer clean copies. Some MTP clients
 create `._*.sav` AppleDouble sidecars that are not real saves.

 ## Controls
@@ -130,12 +159,12 @@ create `._*.sav` AppleDouble sidecars that are not real saves.
 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)).
+   launcher shows (MTP / SD / FTP. See [switch-transfer.md](switch-transfer.md)).
 2. In the launcher, open **MODS** → **Scan again** → enable the mod →
   **Play**.

 Remote **FIND MODS** / GitHub download stays **off** on Switch. Do not put
-mod zips into git. Community mods ship their own OPTIONS / rebinds — this port
+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)
@@ -153,12 +182,23 @@ hotkeys (`2`/`3`/`5` are claimed before any mod pipeline hotkey runs).
 | 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).
+`LOW` or `BALANCED`.
+
+## Limitations
+
+- You need homebrew (custom firmware, hbmenu). This project does not set that
+  up.
+- Launch with title override (hold **R** on a title). Applet Mode (Album) is
+  not supported. The game needs full memory.
+- ROMs, mods, and saves are copied manually via MTP, direct SD, or FTP. There
+  is no automated deploy.
+- Updates use the native OTA launcher only. The LÖVE self-updater and remote
+  **FIND MODS** stay off on Switch.
+- Tested on Switch OLED. Switch V1 / Erista boot confirmed by the community.
+  Other models may work but are less tested.

 ## Prefer building it yourself?

 Building the fused NRO (and SD-ready zip) from source is covered in
 [switch-build.md](switch-build.md). Copying artifacts and inbox files
 (MTP / SD / FTP on macOS, Linux, Windows): [switch-transfer.md](switch-transfer.md).
-Status, limitations, and how we tested: [switch-development.md](switch-development.md).
@@ -1,17 +1,16 @@
 # 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.
+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**.
+This is the runbook for contributors on **macOS, Linux, and Windows**.
 Player install (what to download, title override) stays in
 [switch-install.md](switch-install.md). Packaging stays in
-[switch-build.md](switch-build.md). Hardware evidence lives in
-[switch-hardware-evidence.md](switch-hardware-evidence.md).
+[switch-build.md](switch-build.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.
+> for a fast contrib rebuild loop; deferred (AD-009). Do not treat netloader as
+> the release or ROM/mod install path.

 ---

@@ -23,7 +22,7 @@ Player install (what to download, title override) stays in
 | 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 `.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 |
@@ -34,7 +33,7 @@ files, or third-party mod zips to git.

 ---

-## Canonical methods
+## Transfer methods

 ### 1. MTP (DBI responder + host client)

@@ -47,8 +46,8 @@ 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.
+[OpenMTP](https://github.com/ganeshrvel/openmtp) is a documented example for
+macOS, not a Mac-only requirement.

 1. Quit other MTP clients.
 2. Open OpenMTP → select the DBI device → **`1: SD Card`**.
@@ -60,25 +59,25 @@ hardware evidence — **one contributor example**, not a Mac-only product rule.
 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
+`._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).
+   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)
+   "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.
+card reader) or **FTP** instead. Same destinations in the table above.

 #### Windows

@@ -93,7 +92,7 @@ card reader) or **FTP** instead — same destinations in the table above.
 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.
+card reader) or **FTP** instead. Same destinations in the table above.

 ### 2. Direct SD (Hekate UMS or card reader)

@@ -109,9 +108,9 @@ 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).
+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
@@ -154,7 +153,7 @@ Copy the file back from the SD and compare hashes. Round-trip must match.
 | 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` |
+| 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 |

@@ -164,5 +163,3 @@ Copy the file back from the SD and compare hashes. Round-trip must match.

 - 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)
@@ -1,65 +0,0 @@
-# Tiled map editing (mod authoring)
-
-`tools/tiled_export.py` turns the imported ROM cache into a
-[Tiled](https://www.mapeditor.org) workspace, so maps can be edited in a
-real map editor and exported back out as a mod. The original had no map
-editor at all; the port's own map data is plain Lua, which is what makes
-this a data path rather than an asset path.
-
-Editing is done in our own Tiled build,
-[bryanthaboi/tiled_gen1recomp](https://github.com/bryanthaboi/tiled_gen1recomp/releases),
-which ships the `gen1-mod-export` extension the workspace relies on. Grab it
-from that repo's releases; upstream Tiled opens the workspace but cannot
-export a mod out of it.
-
-```sh
-python3 tools/tiled_export.py          # -> build/tiled/ (gitignored)
-```
-
-Then open `build/tiled/gen1.tiled-project` in that build of Tiled.
-
- **The overworld is one surface.** All 222 maps become `maps/*.tmj`, and
-  `kanto.world` places the 36 connected overworld maps at their real
-  connection offsets. That world is pre-loaded (seeded into the workspace's
-  Tiled session), so opening any one overworld map draws its neighbors around
-  it and you scroll and edit straight across the seams. Everything else is a
-  double-click away in Tiled's project panel.
- **Extending Kanto wires both ends.** A connection lives on both maps, so
-  hooking a new map onto a base map also emits the return connection as a
-  patch on that base map, keeping its other directions intact. The return
-  offset is derived, not guessed: all 78 vanilla reciprocal pairs satisfy
-  `back.offset == -offset`.
- **A Tiled tile is a gen1 block.** Each of the 24 tilesets becomes a Tiled
-  tileset whose tiles are its 32x32 blocks, composited from the 8x8 sheet,
-  so a tile layer *is* the map's `blocks` array. Warps, signs and objects
-  sit on the 16px cell grid in object layers, which is the grid the engine
-  addresses them on.
- **Collision is visible.** View > Show Tile Collision Shapes draws the real
-  walkability: a rectangle covers each cell whose feet tile is not in the
-  tileset's `walkable` list, which is the rule `src/world/Map.lua` applies.
- **Maps are shown in their real colors.** Each map is atlased in the SGB
-  palette it renders with, so Cerulean is blue and Lavender is purple in the
-  editor exactly as in game. Vanilla resolves that through a cascade with
-  interiors inheriting the last outdoor map, so the workspace mirrors the
-  cascade and walks the warp graph to colour interiors. Changing a map's
-  `palette` exports `palette = "..."` on the record, which beats the cascade,
-  and the editor offers the real palette names as a dropdown.
- **New blocks and new tilesets.** `blocksets/*.tmj` show a tileset's blocks
-  as raw 8x8 tiles, four by four, so new blocks can be composed there;
-  per-tile flags on `tilesets/tiles_*.tsj` become `walkable`, `waterTiles`,
-  `doorTiles` and the rest.
- **Export is a diff, not a fork of the data.** The `gen1-mod-export`
-  extension (shipped in `tiled_gen1recomp`) writes either one map file or a whole
-  loadable mod folder. An edited vanilla map diffs against the imported data
-  and emits `mod.content.maps:patch` carrying *only* the fields that moved, so
-  a mod covers the parts it changes and leaves the rest to the base game; a
-  new map gets `:register` at an index of 1000 or above. An unchanged map
-  exports nothing at all. Exports pass `tools/modkit.py validate` and `lint`.
- **Or the whole record, on request.** Ticking `exactExport` on a map switches
-  it to `mod.content.maps:override`, pinning the map to exactly what the
-  editor shows. It is off by default because an override wins outright over
-  any other mod patching that map, where a patch composes.
-
-No ROM-derived art travels into an exported mod: a tileset still drawing on
-the player's own imported sheet references that path rather than shipping the
-pixels, and only a sheet the author supplied is copied in.
@@ -26,7 +26,7 @@ JSON parsing, and sha256 verification run on a background `love.thread`

 ## Version.lua fields

-`src/core/Version.lua` carries three fields the updater reads directly (the
+`src/core/Version.lua` carries four fields the updater reads directly (the
 existing `modApi`, `linkProtocol`, `saveFormat`, and `cache` fields are
 untouched):

@@ -37,6 +37,11 @@ untouched):
  as a valid payload to chainload).
 - `shell` - the native-shell contract this build's fused executable
  implements.
+- `payloadHost` - the native host family an in-place payload targets. Ordinary
+  LÖVE packages use `"love"`. A specialized native package uses a distinct,
+  stable identifier and accepts only payloads carrying that same identifier.
+  A missing field defaults to `"love"`, preserving compatibility with payloads
+  released before this field existed.
 - `minShell` - the lowest shell contract required to *run* this payload.

 Bump `minShell` only when a payload needs something the currently-shipped
@@ -49,6 +54,12 @@ rather than deleting it, in case a future shell upgrade can run it, and
 installer instead. Do not bump `minShell` for an ordinary Lua/data release;
 that is exactly the case the updater exists to avoid a reinstall for.

+Change `payloadHost` only when the packaged Lua depends on a different native
+host family. This is separate from `minShell`: the host name answers *which*
+native integration the payload targets, while the shell number answers *which
+revision* of that integration it requires. A mismatched-host payload is never
+mounted or deleted as stale; the launcher directs the player to a full package.
+
 ## Release assets

 Each tagged release `vX.Y.Z` carries the existing per-platform archives
@@ -115,12 +126,25 @@ bundled game, in that case.
  already driving the frame. A payload that must change `love.run` itself
  needs a `minShell` bump so an older shell refuses to chainload it rather
  than running with half its intended behavior.
- **Android has no in-app download transport yet.** `check_worker.lua`
-  shells out to curl for both the release check and the download; curl is
-  absent on Android, so `Check` degrades to `status = "error"` there (the
-  launcher UI hides on that status) and the player is directed to the
-  releases page via `Check.releaseUrl()` instead.
+- **Android and iOS use the native download bridge, not curl.** Neither
+  platform ships curl, so the old `check_worker.lua` path (shell out to curl)
+  always landed on `error` and the launcher chip's "Check for updates" tap
+  was a no-op. The worker now talks through `HostShell`, the same transport
+  as the mod catalog: curl on desktop, `love.system.httpDownload` on mobile.
+  On Android that is the GameActivity JNI/`HttpsURLConnection` bridge; on
+  iOS it is `GRPickerBridge.httpDownload` (`URLSession`). A fused sideloaded
+  APK or IPA can therefore check GitHub and fetch the `.love` payload
+  in-app. If neither transport exists, the worker reports `needs_full` and
+  the launcher chip opens `Check.releaseUrl()`. Native package-only changes
+  still need a full reinstall (`minShell` / `payloadHost` gate →
+  `needs_full`). Applying a downloaded payload on Android relaunches via
+  `love.system.restartApp`; iOS still uses in-process `quit("restart")`.
 - **Dev/source runs never self-update.** `Boot.run` returns immediately when
  `love.filesystem.isFused()` is false, and a working tree's `engine` is the
  `"0.0.0-dev"` placeholder that always reports up to date, so a source
  checkout is always "the game" itself; updating it means pulling the repo.
+- **Nintendo Switch does not use this LÖVE self-updater.** On NX,
+  `Platform.networkValidated()` is `false`, so `Boot.run` / `Check` never
+  download `.love` payloads. In-console OTA uses the **native OTA launcher**
+  (DEVKITPRO), documented in [switch-install.md](switch-install.md). Wire
+  format: `src/update/SwitchOta.lua`. Manual zip install remains the fallback.
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# After first boot of a compatible Linux ARM handheld (or when PortMaster is installed), reinsert the
+# SD card and run this to install gen1recomp-sbc + Red/Blue ROMs into Roms/PORTS.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+STAGE="$ROOT/.bazinga/work/linux-arm-sbc-install"
+DECPREP="${DECPREP:-$ROOT/../decprep}"
+ZIP="$ROOT/dist/linux-arm-sbc/gen1recomp-sbc-portmaster.zip"
+
+say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
+fail() { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
+
+# Find a mounted handheld userdata volume with a ROMs or Apps directory.
+find_roms_root() {
+  local v candidate
+  for v in /Volumes/*; do
+    [ -d "$v" ] || continue
+    # Prefer a volume that already has Roms/ or Apps/
+    if [ -d "$v/Roms" ] || [ -d "$v/roms" ] || [ -d "$v/PORTS" ] || [ -d "$v/ports" ] || [ -d "$v/Apps" ]; then
+      echo "$v"
+      return 0
+    fi
+  done
+  # Fallback: common removable-volume labels
+  for v in /Volumes/SDCARD /Volumes/sdcard /Volumes/NO\ NAME /Volumes/ROMS; do
+    if [ -d "$v" ]; then
+      echo "$v"
+      return 0
+    fi
+  done
+  return 1
+}
+
+say "looking for handheld SD volume"
+ROMS_ROOT="$(find_roms_root)" || fail "no SD volume mounted. boot the handheld once, power it off, reinsert the SD, then rerun."
+
+say "using: $ROMS_ROOT"
+# Resolve the device PortMaster ports directory
+if [ -d "$ROMS_ROOT/Roms/PORTS" ]; then
+  PORTS="$ROMS_ROOT/Roms/PORTS"
+elif [ -d "$ROMS_ROOT/roms/PORTS" ]; then
+  PORTS="$ROMS_ROOT/roms/PORTS"
+elif [ -d "$ROMS_ROOT/Roms/ports" ]; then
+  PORTS="$ROMS_ROOT/Roms/ports"
+elif [ -d "$ROMS_ROOT/PORTS" ]; then
+  PORTS="$ROMS_ROOT/PORTS"
+else
+  mkdir -p "$ROMS_ROOT/Roms/PORTS"
+  PORTS="$ROMS_ROOT/Roms/PORTS"
+fi
+say "PORTS: $PORTS"
+
+# Refresh staged payload
+mkdir -p "$STAGE/PORTS"
+if [ -f "$ZIP" ]; then
+  rm -rf "$STAGE/PORTS/gen1recomp-sbc.sh" "$STAGE/PORTS/gen1recomp-sbc" "$STAGE/PORTS/port.json" \
+    "$STAGE/PORTS/gameinfo.xml" "$STAGE/PORTS/README.md"
+  unzip -q -o "$ZIP" -d "$STAGE/PORTS"
+else
+  fail "missing $ZIP — run ./build-linux-arm-sbc.sh first"
+fi
+
+# Ensure ROMs are in lovegame (Choose ROM scans this folder on minimal images)
+[ -f "$DECPREP/Pokemon - Red Version.gb" ] || fail "missing Red ROM in $DECPREP"
+[ -f "$DECPREP/Pokemon - Blue Version.gb" ] || fail "missing Blue ROM in $DECPREP"
+cp -f "$DECPREP/Pokemon - Red Version.gb" "$STAGE/PORTS/gen1recomp-sbc/lovegame/"
+cp -f "$DECPREP/Pokemon - Blue Version.gb" "$STAGE/PORTS/gen1recomp-sbc/lovegame/"
+
+say "copying gen1recomp port"
+rm -rf "$PORTS/gen1recomp-sbc" "$PORTS/gen1recomp-sbc.sh"
+cp -R "$STAGE/PORTS/gen1recomp-sbc" "$PORTS/"
+cp -f "$STAGE/PORTS/gen1recomp-sbc.sh" "$PORTS/"
+cp -f "$STAGE/PORTS/port.json" "$PORTS/"
+cp -f "$STAGE/PORTS/README.md" "$PORTS/"
+chmod +x "$PORTS/gen1recomp-sbc.sh" "$PORTS/gen1recomp-sbc/bin/love.aarch64"
+
+# Also drop carts in the stock GB folder for the emulator library
+GB_DIR=""
+for candidate in "$ROMS_ROOT/Roms/GB" "$ROMS_ROOT/roms/GB" "$ROMS_ROOT/Roms/gb"; do
+  if [ -d "$candidate" ]; then GB_DIR="$candidate"; break; fi
+done
+if [ -n "$GB_DIR" ]; then
+  say "copying .gb into $GB_DIR"
+  cp -f "$DECPREP/Pokemon - Red Version.gb" "$GB_DIR/"
+  cp -f "$DECPREP/Pokemon - Blue Version.gb" "$GB_DIR/"
+fi
+
+sync
+say "installed:"
+ls -lh "$PORTS/gen1recomp-sbc.sh"
+ls -lh "$PORTS/gen1recomp-sbc/lovegame/"*.gb
+say "eject the SD, insert it in the handheld, open Ports → gen1recomp-sbc, Choose ROM."
@@ -1,188 +0,0 @@
-- modules/Behavior.lua
--
-- Base module for the pluggable behavior system that drives the Behavior &
-- Mode Unification refactor.
--
-- A *behavior* is a small, stateless table produced by `Behavior.new(spec)`
-- that implements a fixed lifecycle hook set. Concrete behaviors (Clickable,
-- Scrollable, TextEditable, Selectable, ...) each live in their own module and
-- are attached to an Element. The Element's `update`/`draw`/save-restore paths
-- iterate `element.behaviors` and dispatch to the appropriate hooks, replacing
-- the swarm of `if self.scrollable` / immediate-mode-branch checks previously
-- hard-coded in Element.lua.
--
-- Element.new iterates a registry of behavior prototypes and auto-attaches
-- whichever return true from `shouldAttach(props)`. Element therefore never
-- needs to know what an individual behavior does — only that it conforms to
-- this interface.
--
-- Design constraints (locked — tasks 02-13 depend on this API):
--   * Pure Lua — NO `love` import, NO dependency on utils/Color/Units/ErrorHandler.
--     Stays fully stub-testable standalone (see testing/__tests__/behavior_test.lua).
--   * Minimal interface — exactly 6 lifecycle hooks + a `shouldAttach` predicate.
--     Do NOT add hooks "just in case"; new capabilities become new behaviors,
--     not new hooks. Extending HOOK_NAMES is an architectural decision that must
--     be mirrored by every concrete behavior.
--   * Immutable instances — behavior tables are produced once and treated as
--     read-only. Per-element runtime state lives on the element (or a subsystem
--     the behavior attaches), NEVER on the behavior instance itself, so a single
--     behavior instance can be shared across many elements.
--
-- Lifecycle hook contract (each receives the owning element as first argument):
--   onAttach(element)               — called once when the behavior is attached
--                                     (element fully constructed). Allocate
--                                     subsystems / register listeners here.
--   onDetach(element)               — called once when the behavior is detached
--                                     (element destroyed / mode switch). Tear
--                                     down anything onAttach created.
--   onUpdate(element, dt)           — called every frame from Element:update.
--   onDraw(element, ctx)            — called every frame from Element:draw; `ctx`
--                                     is the draw context (viewport transform,
--                                     scissor state, theme renderer, ...).
--   saveState(element) -> state     — called during Element save-state; returns
--                                     a serializable snapshot (or nil) so the
--                                     behavior's runtime state survives the
--                                     immediate-mode recreation cycle.
--   restoreState(element, state)   — called after reconstruction with the
--                                     snapshot previously returned by saveState.
--
-- shouldAttach(props) -> boolean    — class-level predicate (not a hook): given
--                                     an element's props table, return true if
--                                     this behavior should be auto-attached.
--                                     Defaults to false (opt-in).
-
--- A behavior instance: a frozen table of lifecycle hooks + a shouldAttach
--- predicate. All hooks are always present (custom override or no-op default).
---@class Behavior
---@field onAttach fun(element:table)
---@field onDetach fun(element:table)
---@field onUpdate fun(element:table, dt:number)
---@field onDraw fun(element:table, ctx:table)
---@field saveState fun(element:table):any
---@field restoreState fun(element:table, state:any)
---@field shouldAttach fun(props:table):boolean
-
-local Behavior = {}
-
-- The fixed, ordered lifecycle hook set. Order is preserved so downstream tasks
-- (Element behavior iteration) can rely on a deterministic dispatch sequence.
-- HOOK_NAMES is intentionally NOT extended casually — see file header.
-Behavior.HOOK_NAMES = {
-  "onAttach",
-  "onDetach",
-  "onUpdate",
-  "onDraw",
-  "saveState",
-  "restoreState",
-}
-
-- Allowlist of spec keys accepted by Behavior.new. Anything else is rejected so
-- a typo (e.g. `onUpdat`) surfaces immediately instead of silently no-op'ing.
-- Hook keys (HOOK_NAMES + shouldAttach) MUST be functions; metadata keys
-- (drawLayer) may hold any value.
-local ALLOWED_KEYS = {
-  onAttach = true,
-  onDetach = true,
-  onUpdate = true,
-  onDraw = true,
-  saveState = true,
-  restoreState = true,
-  shouldAttach = true,
-  drawLayer = true,
-}
-
-- Spec keys whose values are NOT required to be functions (passive metadata
-- consumed by dispatch sites, e.g. Element:draw's pre/post-children split).
-local NON_FUNCTION_KEYS = {
-  drawLayer = true,
-}
-
-- Default no-op hook. Behaviors override only the hooks they need; every other
-- hook resolves to this so dispatch sites never have to nil-check.
-local function noop() end
-
-- Default shouldAttach predicate: never auto-attach unless the behavior opts in
-- by providing its own predicate. This is the safe default — a behavior with no
-- opinion about which elements it applies to stays inert in the auto-attach
-- pass (it can still be attached explicitly by name in a later task).
-local function defaultShouldAttach()
-  return false
-end
-
-- Module-level default predicate exposed for callers/tests that want to
-- reference the base default directly without constructing an instance.
-Behavior.shouldAttach = defaultShouldAttach
-
--- Factory: create a frozen behavior instance from a spec table.
---
--- `spec` is a table whose keys may be any subset of the 6 lifecycle hook names
--- plus `shouldAttach`; each value (when present) must be a function. The
--- returned table contains every lifecycle hook (custom override OR no-op) and
--- a `shouldAttach` predicate (custom OR always-false default), so dispatch
--- sites can call any hook unconditionally without nil-checking.
---
--- Unknown spec keys and non-function values raise an error immediately so
--- mistakes fail fast at construction rather than as silent no-ops later.
---
---@param spec table|nil spec table overriding select hooks / shouldAttach
---@return Behavior
-function Behavior.new(spec)
-  spec = spec or {}
-
-  -- Validate spec keys up front so typos surface here, not as silent no-ops.
-  for key, value in pairs(spec) do
-    if not ALLOWED_KEYS[key] then
-      error(string.format("Behavior.new: unknown spec key '%s'", tostring(key)), 2)
-    end
-    if not NON_FUNCTION_KEYS[key] and type(value) ~= "function" then
-      error(string.format("Behavior.new: spec key '%s' must be a function, got %s", tostring(key), type(value)), 2)
-    end
-  end
-
-  local instance = {}
-
-  -- Populate every lifecycle hook: custom override when provided, no-op default
-  -- otherwise. Guarantees `instance.hook` is always callable.
-  for _, hook in ipairs(Behavior.HOOK_NAMES) do
-    instance[hook] = spec[hook] or noop
-  end
-
-  -- shouldAttach defaults to always-false; behaviors opt in by supplying one.
-  instance.shouldAttach = spec.shouldAttach or defaultShouldAttach
-
-  -- drawLayer: optional metadata field (default nil = "background"/pre-children).
-  -- Dispatch sites (Element:draw) use it to split rendering into pre-children
-  -- (background layers) and post-children (overlay layers, e.g. scrollbars).
-  instance.drawLayer = spec.drawLayer
-
-  -- Freeze: prevent adding new fields. Behavior instances are shared, stateless
-  -- objects; runtime state belongs on the element, never on the behavior.
-  -- (Reassigning an existing hook is still possible via direct index write —
-  -- Lua metatables cannot intercept that — but the freeze communicates intent
-  -- and catches accidental field additions.)
-  local mt = {
-    __newindex = function(_, key)
-      error(string.format("Behavior: behavior instances are immutable (cannot set '%s')", tostring(key)), 2)
-    end,
-    --- Mark the metatable so consumers can detect a Behavior instance.
-    ---@return string
-    __tostring = function()
-      return "Behavior"
-    end,
-    __metatable = "Behavior",
-  }
-  setmetatable(instance, mt)
-
-  return instance
-end
-
--- Type guard: returns true if `value` is a Behavior instance produced by
--- `Behavior.new`. Used by Element's attach path to validate registry entries
--- without depending on identity.
---@param value any
---@return boolean
-function Behavior.isBehavior(value)
-  return type(value) == "table" and getmetatable(value) == "Behavior"
-end
-
-return Behavior
@@ -1,686 +0,0 @@
-- Lua 5.2+ compatibility for unpack
-local unpack = table.unpack or unpack
-
-- Warning cache to prevent duplicate warnings for the same element
-local warningCache = {}
-
-local Cache = {
-  canvases = {},
-  quads = {},
-  blurInstances = {}, -- Cache blur instances by quality
-  blurredCanvases = {}, -- Cache pre-blurred canvases for immediate mode
-  MAX_CANVAS_SIZE = 20,
-  MAX_QUAD_SIZE = 20,
-  MAX_BLURRED_CANVAS_CACHE = 50, -- Maximum cached blurred canvases
-  RADIUS_THRESHOLD = 0.5, -- Skip blur below this radius
-  LARGE_BLUR_THRESHOLD = 250 * 250, -- Warn if blur area exceeds this (250x250px)
-}
-
--- Round canvas size to nearest bucket for better reuse
---@param size number Size to bucket
---@return number bucketSize Bucketed size
-local function bucketSize(size)
-  if size <= 128 then
-    return math.ceil(size / 32) * 32
-  elseif size <= 512 then
-    return math.ceil(size / 64) * 64
-  elseif size <= 1024 then
-    return math.ceil(size / 128) * 128
-  else
-    return math.ceil(size / 256) * 256
-  end
-end
-
--- Get or create a canvas from cache
---@param width number Canvas width
---@param height number Canvas height
---@return love.Canvas canvas The cached or new canvas
-function Cache.getCanvas(width, height)
-  -- Use bucketed sizes for better cache reuse
-  local bucketedWidth = bucketSize(width)
-  local bucketedHeight = bucketSize(height)
-  local key = string.format("%dx%d", bucketedWidth, bucketedHeight)
-
-  if not Cache.canvases[key] then
-    Cache.canvases[key] = {}
-  end
-
-  local cache = Cache.canvases[key]
-
-  for i, entry in ipairs(cache) do
-    if not entry.inUse then
-      entry.inUse = true
-      return entry.canvas
-    end
-  end
-
-  local canvas = love.graphics.newCanvas(bucketedWidth, bucketedHeight)
-  table.insert(cache, { canvas = canvas, inUse = true })
-
-  if #cache > Cache.MAX_CANVAS_SIZE then
-    local removed = table.remove(cache, 1)
-    if removed and removed.canvas then
-      removed.canvas:release()
-    end
-  end
-
-  return canvas
-end
-
--- Release a canvas back to the cache
---@param canvas love.Canvas Canvas to release
-function Cache.releaseCanvas(canvas)
-  for _, sizeCache in pairs(Cache.canvases) do
-    for _, entry in ipairs(sizeCache) do
-      if entry.canvas == canvas then
-        entry.inUse = false
-        return
-      end
-    end
-  end
-end
-
--- Get or create a quad from cache
---@param x number X position
---@param y number Y position
---@param width number Quad width
---@param height number Quad height
---@param sw number Source width
---@param sh number Source height
---@return love.Quad quad The cached or new quad
-function Cache.getQuad(x, y, width, height, sw, sh)
-  local key = string.format("%d,%d,%d,%d,%d,%d", x, y, width, height, sw, sh)
-
-  if not Cache.quads[key] then
-    Cache.quads[key] = {}
-  end
-
-  local cache = Cache.quads[key]
-
-  for i, entry in ipairs(cache) do
-    if not entry.inUse then
-      entry.inUse = true
-      return entry.quad
-    end
-  end
-
-  local quad = love.graphics.newQuad(x, y, width, height, sw, sh)
-  table.insert(cache, { quad = quad, inUse = true })
-
-  if #cache > Cache.MAX_QUAD_SIZE then
-    table.remove(cache, 1)
-  end
-
-  return quad
-end
-
--- Release a quad back to the cache
---@param quad love.Quad Quad to release
-function Cache.releaseQuad(quad)
-  for _, keyCache in pairs(Cache.quads) do
-    for _, entry in ipairs(keyCache) do
-      if entry.quad == quad then
-        entry.inUse = false
-        return
-      end
-    end
-  end
-end
-
--- Generate cache key for blurred canvas
---@param elementId string Element ID
---@param x number X position
---@param y number Y position
---@param width number Width
---@param height number Height
---@param radius number Blur radius
---@param quality number Blur quality
---@param isBackdrop boolean Whether this is backdrop blur
---@return string key Cache key
-function Cache.generateBlurCacheKey(elementId, x, y, width, height, radius, quality, isBackdrop)
-  return string.format(
-    "%s:%d:%d:%d:%d:%.1f:%d:%s",
-    elementId,
-    x,
-    y,
-    width,
-    height,
-    radius,
-    quality,
-    tostring(isBackdrop)
-  )
-end
-
--- Get cached blurred canvas
---@param key string Cache key
---@return love.Canvas|nil canvas Cached canvas or nil
-function Cache.getBlurredCanvas(key)
-  local entry = Cache.blurredCanvases[key]
-  if entry then
-    entry.lastUsed = os.time()
-    return entry.canvas
-  end
-  return nil
-end
-
--- Store blurred canvas in cache
---@param key string Cache key
---@param canvas love.Canvas Canvas to cache
-function Cache.setBlurredCanvas(key, canvas)
-  -- Limit cache size
-  local count = 0
-  for _ in pairs(Cache.blurredCanvases) do
-    count = count + 1
-  end
-
-  if count >= Cache.MAX_BLURRED_CANVAS_CACHE then
-    -- Remove oldest entry
-    local oldestKey = nil
-    local oldestTime = math.huge
-    for k, v in pairs(Cache.blurredCanvases) do
-      if v.lastUsed < oldestTime then
-        oldestTime = v.lastUsed
-        oldestKey = k
-      end
-    end
-
-    if oldestKey then
-      if Cache.blurredCanvases[oldestKey].canvas then
-        Cache.blurredCanvases[oldestKey].canvas:release()
-      end
-      Cache.blurredCanvases[oldestKey] = nil
-    end
-  end
-
-  Cache.blurredCanvases[key] = {
-    canvas = canvas,
-    lastUsed = os.time(),
-  }
-end
-
--- Clear blurred canvas cache for specific element
---@param elementId string Element ID to clear cache for
-function Cache.clearBlurredCanvasesForElement(elementId)
-  for key, entry in pairs(Cache.blurredCanvases) do
-    if key:match("^" .. elementId .. ":") then
-      if entry.canvas then
-        entry.canvas:release()
-      end
-      Cache.blurredCanvases[key] = nil
-    end
-  end
-end
-
--- Clear all caches
-function Cache.clear()
-  -- Release all blurred canvases
-  for _, entry in pairs(Cache.blurredCanvases) do
-    if entry.canvas then
-      entry.canvas:release()
-    end
-  end
-
-  Cache.canvases = {}
-  Cache.quads = {}
-  Cache.blurInstances = {}
-  Cache.blurredCanvases = {}
-  warningCache = {} -- Clear warning cache on cache clear
-end
-
-- ============================================================================
-- SHADER BUILDER
-- ============================================================================
-
-local ShaderBuilder = {}
-
--- Build Gaussian blur shader with given parameters
---@param taps number Number of samples (must be odd, >= 3)
---@param offset number Offset value
---@param offsetType string "weighted" or "center"
---@param sigma number Sigma value for Gaussian distribution
---@return love.Shader shader The compiled blur shader
-function ShaderBuilder.build(taps, offset, offsetType, sigma)
-  taps = math.floor(taps)
-  sigma = sigma >= 1 and sigma or (taps - 1) * offset / 6
-  sigma = math.max(sigma, 1)
-
-  local steps = (taps + 1) / 2
-
-  local gOffsets = {}
-  local gWeights = {}
-  for i = 1, steps do
-    gOffsets[i] = offset * (i - 1)
-    gWeights[i] = math.exp(-0.5 * (gOffsets[i] - 0) ^ 2 * 1 / sigma ^ 2)
-  end
-
-  local offsets = {}
-  local weights = {}
-  for i = #gWeights, 2, -2 do
-    local oA, oB = gOffsets[i], gOffsets[i - 1]
-    local wA, wB = gWeights[i], gWeights[i - 1]
-    wB = oB == 0 and wB / 2 or wB
-    local weight = wA + wB
-    offsets[#offsets + 1] = offsetType == "center" and (oA + oB) / 2 or (oA * wA + oB * wB) / weight
-    weights[#weights + 1] = weight
-  end
-
-  local code = {
-    [[
-    extern vec2 direction;
-    vec4 effect(vec4 color, Image tex, vec2 tc, vec2 sc) {]],
-  }
-
-  local norm = 0
-  if #gWeights % 2 == 0 then
-    code[#code + 1] = "vec4 c = vec4( 0.0 );"
-  else
-    local weight = gWeights[1]
-    norm = norm + weight
-    code[#code + 1] = string.format("vec4 c = %f * texture2D(tex, tc);", weight)
-  end
-
-  local template = "c += %f * ( texture2D(tex, tc + %f * direction)+ texture2D(tex, tc - %f * direction));\n"
-  for i = 1, #offsets do
-    local offset = offsets[i]
-    local weight = weights[i]
-    norm = norm + weight * 2
-    code[#code + 1] = string.format(template, weight, offset, offset)
-  end
-  code[#code + 1] = string.format("return c * vec4(%f) * color; }", 1 / norm)
-
-  local shaderCode = table.concat(code)
-  return love.graphics.newShader(shaderCode)
-end
-
--- Get or create a blur instance from cache
---@param quality number Quality level (1-10)
---@return table blurData Cached blur data {shader, taps}
-function Cache.getBlurInstance(quality)
-  if not Cache.blurInstances[quality] then
-    local taps = 3 + (quality - 1) * 1.5
-    taps = math.floor(taps)
-    if taps % 2 == 0 then
-      taps = taps + 1
-    end
-
-    local shader = ShaderBuilder.build(taps, 1.0, "weighted", -1)
-    Cache.blurInstances[quality] = {
-      shader = shader,
-      taps = taps,
-    }
-  end
-
-  return Cache.blurInstances[quality]
-end
-
---@class BlurProps
---@field quality number? Quality level (1-10, default: 5)
-
---@class Blur
---@field shader love.Shader The blur shader
---@field quality number Quality level (1-10)
---@field taps number Number of shader taps
---@field _ErrorHandler table? Reference to ErrorHandler module
-local Blur = {}
-Blur.__index = Blur
-
--- Check if we should warn about large blur area in immediate mode
---@param elementId string|nil Element ID for caching warnings
---@param width number Blur area width
---@param height number Blur area height
---@param blurType string "content" or "backdrop"
-local function checkLargeBlurWarning(elementId, width, height, blurType)
-  -- Skip if no ErrorHandler available
-  if not Blur._ErrorHandler then
-    return
-  end
-
-  -- Skip if not in immediate mode
-  if not Blur._blurOptimizations then
-    return
-  end
-
-  -- Calculate blur area
-  local area = width * height
-
-  -- Skip if area is below threshold
-  if area <= Cache.LARGE_BLUR_THRESHOLD then
-    return
-  end
-
-  -- Generate warning key (use elementId if available, otherwise use dimensions)
-  local warningKey = elementId or string.format("%dx%d:%s", width, height, blurType)
-
-  -- Skip if already warned for this element/area
-  if warningCache[warningKey] then
-    return
-  end
-
-  -- Mark as warned
-  warningCache[warningKey] = true
-
-  -- Issue warning
-  local message =
-    string.format("Large %s blur area detected (%dx%d = %d pixels) in immediate mode", blurType, width, height, area)
-
-  local suggestion =
-    "Consider using retained mode for this component to avoid recreating blur effects every frame. Large blur operations are expensive and can cause performance issues in immediate mode."
-
-  Blur._ErrorHandler:warn("Blur", "PERF_003", {
-    area = string.format("%.0fx%.0f", width or 0, height or 0),
-  })
-end
-
--- Create a new blur effect instance
---@param props BlurProps? Blur configuration
---@return Blur blur The new blur instance
-function Blur.new(props)
-  props = props or {}
-
-  local quality = props.quality or 5
-  quality = math.max(1, math.min(10, quality))
-
-  -- Get cached blur instance for this quality level
-  local blurData = Cache.getBlurInstance(quality)
-
-  local self = setmetatable({}, Blur)
-  self.shader = blurData.shader
-  self.quality = quality
-  self.taps = blurData.taps
-
-  return self
-end
-
--- Apply blur to a region of the screen
---@param radius number Blur radius in pixels
---@param x number X position
---@param y number Y position
---@param width number Width of region
---@param height number Height of region
---@param drawFunc function Function to draw content to be blurred
-function Blur:applyToRegion(radius, x, y, width, height, drawFunc)
-  if type(drawFunc) ~= "function" then
-    if Blur._ErrorHandler then
-      Blur._ErrorHandler:warn("Blur", "BLUR_001")
-    end
-    return
-  end
-
-  if radius <= 0 or width <= 0 or height <= 0 then
-    drawFunc()
-    return
-  end
-
-  -- Early exit for very low radius (optimization)
-  if radius < Cache.RADIUS_THRESHOLD then
-    drawFunc()
-    return
-  end
-
-  -- Check for large blur area in immediate mode
-  checkLargeBlurWarning(nil, width, height, "content")
-
-  -- Calculate offset multiplier based on radius and quality
-  -- Higher quality = more samples = smaller steps for same radius
-  local offsetMultiplier = radius / self.quality
-
-  local canvas1 = Cache.getCanvas(width, height)
-  local canvas2 = Cache.getCanvas(width, height)
-
-  local prevCanvas = love.graphics.getCanvas()
-  local prevShader = love.graphics.getShader()
-  local prevColor = { love.graphics.getColor() }
-  local prevBlendMode = love.graphics.getBlendMode()
-
-  love.graphics.setCanvas(canvas1)
-  love.graphics.clear()
-  love.graphics.push()
-  love.graphics.origin()
-  love.graphics.translate(-x, -y)
-  drawFunc()
-  love.graphics.pop()
-
-  love.graphics.setShader(self.shader)
-  love.graphics.setColor(1, 1, 1, 1)
-  love.graphics.setBlendMode("alpha", "premultiplied")
-
-  -- Single pass with radius-controlled offset
-  love.graphics.setCanvas(canvas2)
-  love.graphics.clear()
-  self.shader:send("direction", { offsetMultiplier / width, 0 })
-  love.graphics.draw(canvas1, 0, 0)
-
-  love.graphics.setCanvas(canvas1)
-  love.graphics.clear()
-  self.shader:send("direction", { 0, offsetMultiplier / height })
-  love.graphics.draw(canvas2, 0, 0)
-
-  love.graphics.setCanvas(prevCanvas)
-  love.graphics.setShader()
-  love.graphics.setBlendMode(prevBlendMode)
-  love.graphics.draw(canvas1, x, y)
-
-  love.graphics.setShader(prevShader)
-  love.graphics.setColor(unpack(prevColor))
-
-  Cache.releaseCanvas(canvas1)
-  Cache.releaseCanvas(canvas2)
-end
-
--- Apply backdrop blur effect (blur content behind a region)
---@param radius number Blur radius in pixels
---@param x number X position
---@param y number Y position
---@param width number Width of region
---@param height number Height of region
---@param backdropCanvas love.Canvas Canvas containing the backdrop content
-function Blur:applyBackdrop(radius, x, y, width, height, backdropCanvas)
-  if not backdropCanvas then
-    if Blur._ErrorHandler then
-      Blur._ErrorHandler:warn("Blur", "BLUR_002")
-    end
-    return
-  end
-
-  if radius <= 0 or width <= 0 or height <= 0 then
-    return
-  end
-
-  -- Early exit for very low radius (optimization)
-  if radius < Cache.RADIUS_THRESHOLD then
-    return
-  end
-
-  -- Calculate offset multiplier based on radius and quality
-  local offsetMultiplier = radius / self.quality
-
-  local canvas1 = Cache.getCanvas(width, height)
-  local canvas2 = Cache.getCanvas(width, height)
-
-  local prevCanvas = love.graphics.getCanvas()
-  local prevShader = love.graphics.getShader()
-  local prevColor = { love.graphics.getColor() }
-  local prevBlendMode = love.graphics.getBlendMode()
-
-  love.graphics.setCanvas(canvas1)
-  love.graphics.clear()
-  love.graphics.setColor(1, 1, 1, 1)
-  love.graphics.setBlendMode("alpha", "premultiplied")
-
-  local backdropWidth, backdropHeight = backdropCanvas:getDimensions()
-  local quad = Cache.getQuad(x, y, width, height, backdropWidth, backdropHeight)
-  love.graphics.draw(backdropCanvas, quad, 0, 0)
-
-  love.graphics.setShader(self.shader)
-
-  -- Single pass with radius-controlled offset
-  love.graphics.setCanvas(canvas2)
-  love.graphics.clear()
-  self.shader:send("direction", { offsetMultiplier / width, 0 })
-  love.graphics.draw(canvas1, 0, 0)
-
-  love.graphics.setCanvas(canvas1)
-  love.graphics.clear()
-  self.shader:send("direction", { 0, offsetMultiplier / height })
-  love.graphics.draw(canvas2, 0, 0)
-
-  love.graphics.setCanvas(prevCanvas)
-  love.graphics.setShader()
-  love.graphics.setBlendMode(prevBlendMode)
-  love.graphics.draw(canvas1, x, y)
-
-  love.graphics.setShader(prevShader)
-  love.graphics.setColor(unpack(prevColor))
-
-  Cache.releaseCanvas(canvas1)
-  Cache.releaseCanvas(canvas2)
-  Cache.releaseQuad(quad)
-end
-
--- Get the current quality level
---@return number quality Quality level (1-10)
-function Blur:getQuality()
-  return self.quality
-end
-
--- Get the number of shader taps
---@return number taps Number of shader taps
-function Blur:getTaps()
-  return self.taps
-end
-
--- Clear all caches (call on window resize or memory cleanup)
-function Blur.clearCache()
-  Cache.clear()
-end
-
--- Apply backdrop blur with caching support
---@param radius number Blur radius in pixels
---@param x number X position
---@param y number Y position
---@param width number Width of region
---@param height number Height of region
---@param backdropCanvas love.Canvas Canvas containing the backdrop content
---@param elementId string|nil Element ID for caching (nil disables caching)
-function Blur:applyBackdropCached(radius, x, y, width, height, backdropCanvas, elementId)
-  -- If caching is disabled or no element ID, fall back to regular apply
-  if not Blur._blurOptimizations or not elementId then
-    return self:applyBackdrop(radius, x, y, width, height, backdropCanvas)
-  end
-
-  -- Generate cache key
-  local cacheKey = Cache.generateBlurCacheKey(elementId, x, y, width, height, radius, self.quality, true)
-
-  -- Check cache
-  local cachedCanvas = Cache.getBlurredCanvas(cacheKey)
-  if cachedCanvas then
-    -- Draw cached blur
-    local prevCanvas = love.graphics.getCanvas()
-    local prevShader = love.graphics.getShader()
-    local prevColor = { love.graphics.getColor() }
-    local prevBlendMode = love.graphics.getBlendMode()
-
-    love.graphics.setCanvas(prevCanvas)
-    love.graphics.setShader()
-    love.graphics.setBlendMode(prevBlendMode)
-    love.graphics.draw(cachedCanvas, x, y)
-
-    love.graphics.setShader(prevShader)
-    love.graphics.setColor(unpack(prevColor))
-    return
-  end
-
-  -- Not cached, render and cache
-  if not backdropCanvas then
-    if Blur._ErrorHandler then
-      Blur._ErrorHandler:warn("Blur", "BLUR_002")
-    end
-    return
-  end
-
-  if radius <= 0 or width <= 0 or height <= 0 then
-    return
-  end
-
-  -- Early exit for very low radius (optimization)
-  if radius < Cache.RADIUS_THRESHOLD then
-    return
-  end
-
-  -- Check for large blur area in immediate mode
-  checkLargeBlurWarning(elementId, width, height, "backdrop")
-
-  -- Calculate offset multiplier based on radius and quality
-  local offsetMultiplier = radius / self.quality
-
-  local canvas1 = Cache.getCanvas(width, height)
-  local canvas2 = Cache.getCanvas(width, height)
-
-  local prevCanvas = love.graphics.getCanvas()
-  local prevShader = love.graphics.getShader()
-  local prevColor = { love.graphics.getColor() }
-  local prevBlendMode = love.graphics.getBlendMode()
-
-  love.graphics.setCanvas(canvas1)
-  love.graphics.clear()
-  love.graphics.setColor(1, 1, 1, 1)
-  love.graphics.setBlendMode("alpha", "premultiplied")
-
-  local backdropWidth, backdropHeight = backdropCanvas:getDimensions()
-  local quad = Cache.getQuad(x, y, width, height, backdropWidth, backdropHeight)
-  love.graphics.draw(backdropCanvas, quad, 0, 0)
-
-  love.graphics.setShader(self.shader)
-
-  -- Single pass with radius-controlled offset
-  love.graphics.setCanvas(canvas2)
-  love.graphics.clear()
-  self.shader:send("direction", { offsetMultiplier / width, 0 })
-  love.graphics.draw(canvas1, 0, 0)
-
-  love.graphics.setCanvas(canvas1)
-  love.graphics.clear()
-  self.shader:send("direction", { 0, offsetMultiplier / height })
-  love.graphics.draw(canvas2, 0, 0)
-
-  -- Cache the result
-  local cachedResult = love.graphics.newCanvas(width, height)
-  love.graphics.setCanvas(cachedResult)
-  love.graphics.clear()
-  love.graphics.setShader()
-  love.graphics.setBlendMode("alpha", "premultiplied")
-  love.graphics.draw(canvas1, 0, 0)
-  Cache.setBlurredCanvas(cacheKey, cachedResult)
-
-  love.graphics.setCanvas(prevCanvas)
-  love.graphics.setShader()
-  love.graphics.setBlendMode(prevBlendMode)
-  love.graphics.draw(canvas1, x, y)
-
-  love.graphics.setShader(prevShader)
-  love.graphics.setColor(unpack(prevColor))
-
-  Cache.releaseCanvas(canvas1)
-  Cache.releaseCanvas(canvas2)
-  Cache.releaseQuad(quad)
-end
-
--- Clear blur cache for specific element
---@param elementId string Element ID
-function Blur.clearElementCache(elementId)
-  Cache.clearBlurredCanvasesForElement(elementId)
-end
-
--- Initialize Blur module with dependencies
---@param deps table Dependencies: { ErrorHandler = ErrorHandler?, immediateModeOptimizations = boolean? }
-function Blur.init(deps)
-  if type(deps) == "table" then
-    Blur._ErrorHandler = deps.ErrorHandler
-    Blur._blurOptimizations = deps.immediateModeOptimizations or false
-  end
-end
-
-Blur.Cache = Cache
-Blur.ShaderBuilder = ShaderBuilder
-
-return Blur
@@ -1,385 +0,0 @@
--- Utility module for parsing and evaluating CSS-like calc() expressions
--- Supports arithmetic operations (+, -, *, /) with mixed units (px, %, vw, vh)
---@class Calc
-local Calc = {}
-
--- Initialize Calc module with dependencies
---@param deps CalcDependencies Dependencies: { ErrorHandler = ErrorHandler? }
-function Calc.init(deps)
-  Calc._ErrorHandler = deps.ErrorHandler
-end
-
--- Token types for lexical analysis
-local TokenType = {
-  NUMBER = "NUMBER",
-  UNIT = "UNIT",
-  PLUS = "PLUS",
-  MINUS = "MINUS",
-  MULTIPLY = "MULTIPLY",
-  DIVIDE = "DIVIDE",
-  LPAREN = "LPAREN",
-  RPAREN = "RPAREN",
-  EOF = "EOF",
-}
-
--- Tokenize a calc expression string into tokens
---@param expr string The expression to tokenize (e.g., "50% - 10vw")
---@return CalcToken[]? tokens Array of tokens with type, value, unit
---@return string? error Error message if tokenization fails
-local function tokenize(expr)
-  local tokens = {}
-  local i = 1
-  local len = #expr
-
-  while i <= len do
-    local char = expr:sub(i, i)
-
-    -- Skip whitespace
-    if char:match("%s") then
-      i = i + 1
-    -- Number (including decimals, but NOT negative - handled separately below)
-    elseif char:match("%d") or (char == "." and expr:sub(i + 1, i + 1):match("%d")) then
-      local numStr = ""
-
-      -- Parse integer and decimal parts
-      while i <= len and (expr:sub(i, i):match("%d") or expr:sub(i, i) == ".") do
-        numStr = numStr .. expr:sub(i, i)
-        i = i + 1
-      end
-
-      local num = tonumber(numStr)
-      if not num then
-        return nil, "Invalid number: " .. numStr
-      end
-
-      -- Check for unit following the number
-      local unitStr = ""
-      while i <= len and expr:sub(i, i):match("[%a%%]") do
-        unitStr = unitStr .. expr:sub(i, i)
-        i = i + 1
-      end
-
-      -- Default to px if no unit
-      if unitStr == "" then
-        unitStr = "px"
-      end
-
-      -- Validate unit
-      local validUnits = { px = true, ["%"] = true, vw = true, vh = true }
-      if not validUnits[unitStr] then
-        return nil, "Invalid unit: " .. unitStr
-      end
-
-      table.insert(tokens, {
-        type = TokenType.NUMBER,
-        value = num,
-        unit = unitStr,
-      })
-    -- Operators
-    elseif char == "+" then
-      table.insert(tokens, { type = TokenType.PLUS })
-      i = i + 1
-    elseif char == "-" then
-      -- Check if this is a negative number or subtraction
-      -- It's a negative number if previous token is an operator or opening paren
-      local prevToken = tokens[#tokens]
-      if
-        not prevToken
-        or prevToken.type == TokenType.PLUS
-        or prevToken.type == TokenType.MINUS
-        or prevToken.type == TokenType.MULTIPLY
-        or prevToken.type == TokenType.DIVIDE
-        or prevToken.type == TokenType.LPAREN
-      then
-        -- This is a negative number, continue to number parsing
-        local numStr = "-"
-        i = i + 1
-
-        -- Parse integer and decimal parts
-        while i <= len and (expr:sub(i, i):match("%d") or expr:sub(i, i) == ".") do
-          numStr = numStr .. expr:sub(i, i)
-          i = i + 1
-        end
-
-        local num = tonumber(numStr)
-        if not num then
-          return nil, "Invalid number: " .. numStr
-        end
-
-        -- Check for unit following the number
-        local unitStr = ""
-        while i <= len and expr:sub(i, i):match("[%a%%]") do
-          unitStr = unitStr .. expr:sub(i, i)
-          i = i + 1
-        end
-
-        -- Default to px if no unit
-        if unitStr == "" then
-          unitStr = "px"
-        end
-
-        -- Validate unit
-        local validUnits = { px = true, ["%"] = true, vw = true, vh = true }
-        if not validUnits[unitStr] then
-          return nil, "Invalid unit: " .. unitStr
-        end
-
-        table.insert(tokens, {
-          type = TokenType.NUMBER,
-          value = num,
-          unit = unitStr,
-        })
-      else
-        -- This is subtraction operator
-        table.insert(tokens, { type = TokenType.MINUS })
-        i = i + 1
-      end
-    elseif char == "*" then
-      table.insert(tokens, { type = TokenType.MULTIPLY })
-      i = i + 1
-    elseif char == "/" then
-      table.insert(tokens, { type = TokenType.DIVIDE })
-      i = i + 1
-    elseif char == "(" then
-      table.insert(tokens, { type = TokenType.LPAREN })
-      i = i + 1
-    elseif char == ")" then
-      table.insert(tokens, { type = TokenType.RPAREN })
-      i = i + 1
-    else
-      return nil, "Unexpected character: " .. char
-    end
-  end
-
-  table.insert(tokens, { type = TokenType.EOF })
-  return tokens
-end
-
--- Parser for calc expressions using recursive descent
---@class Parser
---@field tokens CalcToken[] Array of tokens
---@field pos number Current token position
-local Parser = {}
-Parser.__index = Parser
-
--- Create a new parser
---@param tokens CalcToken[] Array of tokens
---@return Parser
-function Parser.new(tokens)
-  local self = setmetatable({}, Parser)
-  self.tokens = tokens
-  self.pos = 1
-  return self
-end
-
--- Get current token
---@return CalcToken token Current token
-function Parser:current()
-  return self.tokens[self.pos]
-end
-
--- Advance to next token
-function Parser:advance()
-  self.pos = self.pos + 1
-end
-
--- Parse expression (handles + and -)
---@return CalcASTNode ast Abstract syntax tree node
-function Parser:parseExpression()
-  local left = self:parseTerm()
-
-  while self:current().type == TokenType.PLUS or self:current().type == TokenType.MINUS do
-    local op = self:current().type
-    self:advance()
-    local right = self:parseTerm()
-    left = {
-      type = op == TokenType.PLUS and "add" or "subtract",
-      left = left,
-      right = right,
-    }
-  end
-
-  return left
-end
-
--- Parse term (handles * and /)
---@return CalcASTNode ast Abstract syntax tree node
-function Parser:parseTerm()
-  local left = self:parseFactor()
-
-  while self:current().type == TokenType.MULTIPLY or self:current().type == TokenType.DIVIDE do
-    local op = self:current().type
-    self:advance()
-    local right = self:parseFactor()
-    left = {
-      type = op == TokenType.MULTIPLY and "multiply" or "divide",
-      left = left,
-      right = right,
-    }
-  end
-
-  return left
-end
-
--- Parse factor (handles numbers and parentheses)
---@return CalcASTNode ast Abstract syntax tree node
-function Parser:parseFactor()
-  local token = self:current()
-
-  if token.type == TokenType.NUMBER then
-    self:advance()
-    return {
-      type = "number",
-      value = token.value,
-      unit = token.unit,
-    }
-  elseif token.type == TokenType.LPAREN then
-    self:advance()
-    local expr = self:parseExpression()
-    if self:current().type ~= TokenType.RPAREN then
-      error("Expected closing parenthesis")
-    end
-    self:advance()
-    return expr
-  else
-    error("Unexpected token: " .. token.type)
-  end
-end
-
--- Parse the tokens into an AST
---@return CalcASTNode ast Abstract syntax tree
-function Parser:parse()
-  local ast = self:parseExpression()
-  if self:current().type ~= TokenType.EOF then
-    error("Unexpected tokens after expression")
-  end
-  return ast
-end
-
--- Create a calc expression object that can be resolved later
--- This is the main API function that users call
---@param expr string The calc expression (e.g., "50% - 10vw")
---@return CalcObject calcObject A calc expression object with AST
-function Calc.new(expr)
-  -- Tokenize
-  local tokens, err = tokenize(expr)
-  if not tokens then
-    if Calc._ErrorHandler then
-      Calc._ErrorHandler:warn("Calc", "VAL_006", {
-        expression = expr,
-        error = err,
-      })
-    end
-    -- Return a fallback calc object that resolves to 0
-    return {
-      _isCalc = true,
-      _expr = expr,
-      _ast = nil,
-      _error = err,
-    }
-  end
-
-  -- Parse
-  local parser = Parser.new(tokens)
-  local success, ast = pcall(function()
-    return parser:parse()
-  end)
-
-  if not success then
-    if Calc._ErrorHandler then
-      Calc._ErrorHandler:warn("Calc", "VAL_006", {
-        expression = expr,
-        error = ast, -- ast contains error message on failure
-      })
-    end
-    -- Return a fallback calc object that resolves to 0
-    return {
-      _isCalc = true,
-      _expr = expr,
-      _ast = nil,
-      _error = ast,
-    }
-  end
-
-  return {
-    _isCalc = true,
-    _expr = expr,
-    _ast = ast,
-  }
-end
-
--- Check if a value is a calc expression
---@param value any The value to check
---@return boolean isCalc True if value is a calc expression
-function Calc.isCalc(value)
-  return type(value) == "table" and value._isCalc == true
-end
-
--- Resolve a calc expression to pixel value
---@param calcObj CalcObject The calc expression object
---@param viewportWidth number Viewport width in pixels
---@param viewportHeight number Viewport height in pixels
---@param parentSize number? Parent dimension for percentage units
---@return number resolvedValue Resolved pixel value
-function Calc.resolve(calcObj, viewportWidth, viewportHeight, parentSize)
-  if not calcObj._ast then
-    -- Error during parsing, return 0
-    return 0
-  end
-
-  --- Evaluate AST node recursively
-  ---@param node table AST node
-  ---@return number value Evaluated value in pixels
-  local function evaluate(node)
-    if node.type == "number" then
-      -- Convert unit to pixels
-      local value = node.value
-      local unit = node.unit
-
-      if unit == "px" then
-        return value
-      elseif unit == "%" then
-        if not parentSize then
-          if Calc._ErrorHandler then
-            Calc._ErrorHandler:warn("Calc", "LAY_003", {
-              unit = "%",
-              issue = "parent dimension not available",
-            })
-          end
-          return 0
-        end
-        return (value / 100) * parentSize
-      elseif unit == "vw" then
-        return (value / 100) * viewportWidth
-      elseif unit == "vh" then
-        return (value / 100) * viewportHeight
-      else
-        return 0
-      end
-    elseif node.type == "add" then
-      return evaluate(node.left) + evaluate(node.right)
-    elseif node.type == "subtract" then
-      return evaluate(node.left) - evaluate(node.right)
-    elseif node.type == "multiply" then
-      return evaluate(node.left) * evaluate(node.right)
-    elseif node.type == "divide" then
-      local divisor = evaluate(node.right)
-      if divisor == 0 then
-        if Calc._ErrorHandler then
-          Calc._ErrorHandler:warn("Calc", "VAL_006", {
-            expression = calcObj._expr,
-            error = "Division by zero",
-          })
-        end
-        return 0
-      end
-      return evaluate(node.left) / divisor
-    else
-      return 0
-    end
-  end
-
-  return evaluate(calcObj._ast)
-end
-
-return Calc
@@ -1,346 +0,0 @@
---@class Color
-local Color = {}
-Color.__index = Color
-
--- Initialize module with shared dependencies
---@param deps table Dependencies {ErrorHandler}
-function Color.init(deps)
-  if type(deps) == "table" then
-    Color._ErrorHandler = deps.ErrorHandler
-  end
-end
-
--- Build type-safe color objects with automatic validation and clamping
--- Use this to avoid invalid color values and ensure consistent LÖVE-compatible colors (0-1 range)
---@param r number? Red component (0-1), defaults to 0
---@param g number? Green component (0-1), defaults to 0
---@param b number? Blue component (0-1), defaults to 0
---@param a number? Alpha component (0-1), defaults to 1
---@return Color color The new color instance
-function Color.new(r, g, b, a)
-  -- Sanitize and clamp color components
-  local _, sanitizedR = Color.validateColorChannel(r or 0, 1)
-  local _, sanitizedG = Color.validateColorChannel(g or 0, 1)
-  local _, sanitizedB = Color.validateColorChannel(b or 0, 1)
-  local _, sanitizedA = Color.validateColorChannel(a or 1, 1)
-
-  -- FFI structs don't support metatables/methods without wrapping
-  -- The wrapping overhead negates the FFI benefits
-  local self = setmetatable({}, Color)
-  self.r = sanitizedR or 0
-  self.g = sanitizedG or 0
-  self.b = sanitizedB or 0
-  self.a = sanitizedA or 1
-  return self
-end
-
--- Extract individual color channels for use with love.graphics.setColor()
--- Use this to pass colors to LÖVE's rendering functions
---@return number r Red component (0-1)
---@return number g Green component (0-1)
---@return number b Blue component (0-1)
---@return number a Alpha component (0-1)
-function Color:toRGBA()
-  return self.r, self.g, self.b, self.a
-end
-
--- Parse CSS-style hex colors into Color objects for designer-friendly workflows
--- Use this to work with colors from design tools that export hex values
---@param hexWithTag string Hex color string (e.g. "#RRGGBB" or "#RRGGBBAA")
---@return Color color The parsed color (returns white on error with warning)
-function Color.fromHex(hexWithTag)
-  -- Validate input type
-  if type(hexWithTag) ~= "string" then
-    Color._ErrorHandler:warn("Color", "VAL_004", {
-      input = tostring(hexWithTag),
-      issue = "not a string",
-      fallback = "white (#FFFFFF)",
-    })
-    return Color.new(1, 1, 1, 1)
-  end
-
-  local hex = hexWithTag:gsub("#", "")
-  if #hex == 6 then
-    local r = tonumber("0x" .. hex:sub(1, 2))
-    local g = tonumber("0x" .. hex:sub(3, 4))
-    local b = tonumber("0x" .. hex:sub(5, 6))
-    if not r or not g or not b then
-      Color._ErrorHandler:warn("Color", "VAL_004", {
-        input = hexWithTag,
-        issue = "invalid hex digits",
-        fallback = "white (#FFFFFF)",
-      })
-      return Color.new(1, 1, 1, 1) -- Return white as fallback
-    end
-    return Color.new(r / 255, g / 255, b / 255, 1)
-  elseif #hex == 8 then
-    local r = tonumber("0x" .. hex:sub(1, 2))
-    local g = tonumber("0x" .. hex:sub(3, 4))
-    local b = tonumber("0x" .. hex:sub(5, 6))
-    local a = tonumber("0x" .. hex:sub(7, 8))
-    if not r or not g or not b or not a then
-      Color._ErrorHandler:warn("Color", "VAL_004", {
-        input = hexWithTag,
-        issue = "invalid hex digits",
-        fallback = "white (#FFFFFFFF)",
-      })
-      return Color.new(1, 1, 1, 1) -- Return white as fallback
-    end
-    return Color.new(r / 255, g / 255, b / 255, a / 255)
-  else
-    Color._ErrorHandler:warn("Color", "VAL_004", {
-      input = hexWithTag,
-      expected = "#RRGGBB or #RRGGBBAA",
-      hexLength = #hex,
-      fallback = "white (#FFFFFF)",
-    })
-    return Color.new(1, 1, 1, 1) -- Return white as fallback
-  end
-end
-
--- Verify and sanitize individual color components to prevent rendering errors
--- Use this to safely process user input or external color data
---@param value any Value to validate
---@param max number? Maximum value (255 for 0-255 range, 1 for 0-1 range), defaults to 1
---@return boolean valid True if valid
---@return number? clamped Clamped value in 0-1 range, nil if invalid
-function Color.validateColorChannel(value, max)
-  max = max or 1
-
-  if type(value) ~= "number" then
-    return false, nil
-  end
-
-  -- Check for NaN
-  if value ~= value then
-    return false, nil
-  end
-
-  -- Check for Infinity
-  if value == math.huge or value == -math.huge then
-    return false, nil
-  end
-
-  -- Normalize to 0-1 range
-  local normalized = value
-  if max == 255 then
-    normalized = value / 255
-  end
-
-  -- Clamp to valid range
-  normalized = math.max(0, math.min(1, normalized))
-
-  return true, normalized
-end
-
--- Validate hex color format
---@param hex string Hex color string (with or without #)
---@return boolean valid True if valid format
---@return string? error Error message if invalid, nil if valid
-function Color.validateHexColor(hex)
-  if type(hex) ~= "string" then
-    return false, "Hex color must be a string"
-  end
-
-  -- Remove # prefix
-  local cleanHex = hex:gsub("^#", "")
-
-  -- Check length (3, 6, or 8 characters)
-  if #cleanHex ~= 3 and #cleanHex ~= 6 and #cleanHex ~= 8 then
-    return false, string.format("Invalid hex length: %d. Expected 3, 6, or 8 characters", #cleanHex)
-  end
-
-  -- Check for valid hex characters
-  if not cleanHex:match("^[0-9A-Fa-f]+$") then
-    return false, "Invalid hex characters. Use only 0-9, A-F"
-  end
-
-  return true, nil
-end
-
--- Validate RGB/RGBA color values
---@param r number Red component
---@param g number Green component
---@param b number Blue component
---@param a number? Alpha component (optional, defaults to max)
---@param max number? Maximum value (255 or 1), defaults to 1
---@return boolean valid True if valid
---@return string? error Error message if invalid, nil if valid
-function Color.validateRGBColor(r, g, b, a, max)
-  max = max or 1
-  a = a or max
-
-  local rValid = Color.validateColorChannel(r, max)
-  local gValid = Color.validateColorChannel(g, max)
-  local bValid = Color.validateColorChannel(b, max)
-  local aValid = Color.validateColorChannel(a, max)
-
-  if not rValid then
-    return false, string.format("Invalid red channel: %s", tostring(r))
-  end
-  if not gValid then
-    return false, string.format("Invalid green channel: %s", tostring(g))
-  end
-  if not bValid then
-    return false, string.format("Invalid blue channel: %s", tostring(b))
-  end
-  if not aValid then
-    return false, string.format("Invalid alpha channel: %s", tostring(a))
-  end
-
-  return true, nil
-end
-
--- Check if a value is a valid color format
---@param value any Value to check
---@return string? format Format type ("hex", "named", "table"), nil if invalid
-function Color.isValidColorFormat(value)
-  local valueType = type(value)
-
-  -- Check for hex string
-  if valueType == "string" then
-    if value:match("^#?[0-9A-Fa-f]+$") then
-      local valid = Color.validateHexColor(value)
-      if valid then
-        return "hex"
-      end
-    end
-
-    return nil
-  end
-
-  -- Check for table format
-  if valueType == "table" then
-    -- Check for Color instance
-    if getmetatable(value) == Color then
-      return "table"
-    end
-
-    -- Check for array format {r, g, b, a}
-    if value[1] and value[2] and value[3] then
-      local valid = Color.validateRGBColor(value[1], value[2], value[3], value[4])
-      if valid then
-        return "table"
-      end
-    end
-
-    -- Check for named format {r=, g=, b=, a=}
-    if value.r and value.g and value.b then
-      local valid = Color.validateRGBColor(value.r, value.g, value.b, value.a)
-      if valid then
-        return "table"
-      end
-    end
-
-    return nil
-  end
-
-  return nil
-end
-
--- Convert any color format to a valid Color object with graceful fallbacks
--- Use this to robustly handle colors from any source without crashes
---@param value any Color value to sanitize (hex, named, table, or Color instance)
---@param default Color? Default color if invalid (defaults to black)
---@return Color color Sanitized color instance (guaranteed non-nil)
-function Color.sanitizeColor(value, default)
-  default = default or Color.new(0, 0, 0, 1)
-
-  local format = Color.isValidColorFormat(value)
-
-  if not format then
-    return default
-  end
-
-  -- Handle hex format
-  if format == "hex" then
-    local cleanHex = value:gsub("^#", "")
-
-    -- Expand 3-digit hex to 6-digit
-    if #cleanHex == 3 then
-      cleanHex = cleanHex:gsub("(.)", "%1%1")
-    end
-
-    -- Try to parse
-    local success, result = pcall(Color.fromHex, "#" .. cleanHex)
-    if success then
-      return result
-    else
-      return default
-    end
-  end
-
-  if format == "table" then
-    -- Color instance
-    if getmetatable(value) == Color then
-      return value
-    end
-
-    -- Array format
-    if value[1] then
-      local _, r = Color.validateColorChannel(value[1], 1)
-      local _, g = Color.validateColorChannel(value[2], 1)
-      local _, b = Color.validateColorChannel(value[3], 1)
-      local _, a = Color.validateColorChannel(value[4] or 1, 1)
-
-      if r and g and b and a then
-        return Color.new(r, g, b, a)
-      end
-    end
-
-    -- Named format
-    if value.r then
-      local _, r = Color.validateColorChannel(value.r, 1)
-      local _, g = Color.validateColorChannel(value.g, 1)
-      local _, b = Color.validateColorChannel(value.b, 1)
-      local _, a = Color.validateColorChannel(value.a or 1, 1)
-
-      if r and g and b and a then
-        return Color.new(r, g, b, a)
-      end
-    end
-  end
-
-  return default
-end
-
--- Universally convert any color format (hex, named, table) into a Color object
--- Use this as your main color input handler to accept flexible color specifications
---@param value any Color value (hex string, named color, table, or Color instance)
---@return Color color Parsed color instance (defaults to black on error)
-function Color.parse(value)
-  return Color.sanitizeColor(value, Color.new(0, 0, 0, 1))
-end
-
--- Smoothly transition between two colors for animations and gradients
--- Use this to create color-based animations without manual channel calculations
---@param colorA Color Starting color
---@param colorB Color Ending color
---@param t number Interpolation factor (0-1)
---@return Color color Interpolated color
-function Color.lerp(colorA, colorB, t)
-  -- Sanitize inputs
-  if type(colorA) ~= "table" or getmetatable(colorA) ~= Color then
-    colorA = Color.new(0, 0, 0, 1)
-  end
-  if type(colorB) ~= "table" or getmetatable(colorB) ~= Color then
-    colorB = Color.new(0, 0, 0, 1)
-  end
-  if type(t) ~= "number" or t ~= t or t == math.huge or t == -math.huge then
-    t = 0
-  end
-
-  -- Clamp t to 0-1 range
-  t = math.max(0, math.min(1, t))
-
-  -- Linear interpolation for each channel
-  local oneMinusT = 1 - t
-  local r = colorA.r * oneMinusT + colorB.r * t
-  local g = colorA.g * oneMinusT + colorB.g * t
-  local b = colorA.b * oneMinusT + colorB.b * t
-  local a = colorA.a * oneMinusT + colorB.a * t
-
-  return Color.new(r, g, b, a)
-end
-
-return Color
@@ -1,596 +0,0 @@
---@class Context
-local modulePath = (...):match("(.-)[^%.]+$")
-local ZIndex = require(modulePath .. "ZIndex")
-local Element = require(modulePath .. "Element")
-local Context = {
-  topElements = {},
-  -- Base scale configuration
-  baseScale = nil, -- {width: number, height: number}
-  -- Current scale factors
-  scaleFactors = { x = 1.0, y = 1.0 },
-  defaultTheme = nil,
-  _focusedElement = nil,
-  _focusedElementId = nil, -- Stable id used to rehydrate focus across immediate-mode frames
-  _activeEventElement = nil,
-  _cachedViewport = { width = 0, height = 0 },
-  -- Immediate mode state
-  _immediateMode = false,
-  _frameNumber = 0,
-  _currentFrameElements = {},
-  _immediateModeState = nil, -- Will be initialized if immediate mode is enabled
-  _frameStarted = false,
-  _autoBeganFrame = false,
-  -- Z-index ordered element tracking for immediate mode
-  _zIndexOrderedElements = {}, -- Array of elements sorted by z-index (lowest to highest)
-  -- Focus management guard
-  _settingFocus = false,
-  -- Hook called whenever focus changes: function(element) or nil
-  _onFocusChanged = nil,
-
-  -- Navigation state
-  _navigationContext = {
-    lastFocusedElement = nil, -- For returning from modals
-    navigationMode = "sequential", -- "sequential" or "directional"
-    containerElement = nil, -- Current navigation container
-  },
-
-  initialized = false,
-
-  -- Expose internal hit-testing helpers for unit testing only.
-  -- These are populated below after their local definitions. They are NOT part
-  -- of the public API and must not be relied on by callers; they exist so the
-  -- shared hit-test core (the single place display:none guarding lives) can be
-  -- exercised directly by the test suite. Subsequent unified-event-routing
-  -- tasks consume these locals through the mode-agnostic query functions.
-  _test = {
-    pointHitsElement = nil,
-    elementHasScrollableOverflow = nil,
-  },
-
-  -- Debug draw overlay
-  _debugDraw = false,
-  _debugDrawKey = nil,
-
-  -- Initialization state tracking
-  ---@type "uninitialized"|"initializing"|"ready"
-  _initState = "uninitialized",
-  ---@type table[] Queue of {props: ElementProps, callback: function(element)|nil}
-  _initQueue = {},
-
-  -- Per-frame cache for findInteractiveAtPosition so Clickable.onUpdate's
-  -- per-element call (unified-event-routing task 05) doesn't re-walk the tree
-  -- + realloc + sort for every interactive element sharing the same cursor.
-  -- Invalidated explicitly by Context.clearInteractiveCache() at the start of
-  -- each flexlove.update (both modes) and in clearFrameElements (immediate
-  -- mid-frame rebuild). It also self-invalidates when the topElements table
-  -- reference changes (tests replace it per-case; immediate-mode beginFrame
-  -- reassigns it each frame), so direct callers that never go through
-  -- flexlove.update still see fresh results across tree swaps.
-  _interactiveLookupCache = {
-    valid = false,
-    x = nil,
-    y = nil,
-    result = nil,
-    topElementsRef = nil,
-    frameNumber = -1,
-  },
-}
-
--- Check if a point hits an element, accounting for scroll offsets and display:none.
--- All mode-agnostic query functions use this as their single hit-test entry point,
--- ensuring fixes like display:none guarding apply everywhere.
---
--- This is the single canonical place where `element.display == false` short-
--- circuits hit testing. Parent-chain clipping/scroll-offset accumulation is
--- the caller's responsibility: callers walk the parent chain (using
--- `elementHasScrollableOverflow` to decide which ancestors clip) and pass the
--- accumulated scroll offset in here. Keeping the parent walk outside this core
--- lets retained-mode (recursive tree descent) and immediate-mode (flat
--- z-index list) callers share the exact same primitive bounds/display logic.
---@param element Element
---@param mx number Screen X coordinate
---@param my number Screen Y coordinate
---@param scrollOffsetX number? Accumulated scroll offset from parent chain
---@param scrollOffsetY number? Accumulated scroll offset from parent chain
---@return boolean hits
-local function pointHitsElement(element, mx, my, scrollOffsetX, scrollOffsetY)
-  scrollOffsetX = scrollOffsetX or 0
-  scrollOffsetY = scrollOffsetY or 0
-
-  -- Skip display:none elements entirely
-  if element.display == false then
-    return false
-  end
-
-  local bx = element.x
-  local by = element.y
-  local bw = element._borderBoxWidth or (element.width + element.padding.left + element.padding.right)
-  local bh = element._borderBoxHeight or (element.height + element.padding.top + element.padding.bottom)
-
-  local adjustedX = mx + scrollOffsetX
-  local adjustedY = my + scrollOffsetY
-
-  return adjustedX >= bx and adjustedX <= bx + bw and adjustedY >= by and adjustedY <= by + bh
-end
-
--- Check if an element has scrollable/clipped overflow (for scroll offset accumulation).
--- Returns true for `scroll`, `auto`, and `hidden` on either axis. These are the
--- overflow values that clip/translate descendant content and therefore require
--- scroll-offset compensation when hit testing descendants.
---@param element Element
---@return boolean
-local function elementHasScrollableOverflow(element)
-  local overflowX = element.overflowX or element.overflow
-  local overflowY = element.overflowY or element.overflow
-  return overflowX == "scroll"
-    or overflowX == "auto"
-    or overflowY == "scroll"
-    or overflowY == "auto"
-    or overflowX == "hidden"
-    or overflowY == "hidden"
-end
-
-- Expose the two core helpers for unit testing only (see Context._test above).
-Context._test.pointHitsElement = pointHitsElement
-Context._test.elementHasScrollableOverflow = elementHasScrollableOverflow
-
-- Public exposure of the canonical hit-test primitive so other modules
-- (e.g. FlexLove's `getElementAtPosition` / `_getTouchElementAtPosition`
-- tree walks) can share the single implementation of bounds + display:none
-- guarding instead of duplicating the `display == false` check inline.
-- This keeps "display == false" in exactly one place for hit-testing.
-Context.pointHitsElement = pointHitsElement
-Context.elementHasScrollableOverflow = elementHasScrollableOverflow
-
--- Find the first scrollable element at a screen position, regardless of mode.
--- This is the mode-agnostic successor to the two duplicated scrollable lookups
--- that previously lived inline in `flexlove.wheelmoved`:
---   * immediate mode — walked `Context._zIndexOrderedElements` in reverse and
---     re-implemented bounds + parent-chain clipping + scroll-offset math; and
---   * retained mode — recursed through `Context.topElements` with a private
---     `findScrollableAtPosition(elements, x, y)` helper.
--- Both paths now collapse into this single function, which routes every
--- hit test through `pointHitsElement` (the single place `display == false`
--- is guarded) and every scroll-offset decision through
--- `elementHasScrollableOverflow`. As a result display:none elements are never
--- returned in either mode, fixing the latent bug where the immediate-mode
--- path's `isPointInElement` did not skip display:none elements.
---
--- The retained-mode branch intentionally mirrors the original
--- `findScrollableAtPosition` helper's tree walk (deepest scrollable wins,
--- children checked before self) but is upgraded to thread accumulated scroll
--- offsets through `pointHitsElement` so nested scrolled containers are tested
--- against their visible position. The original helper is removed once
--- `flexlove.wheelmoved` is rerouted onto this function in task 04.
---@param x number Screen X coordinate
---@param y number Screen Y coordinate
---@return Element|nil The scrollable element, or nil
-function Context.findScrollableAtPosition(x, y)
-  if Context.isImmediateMode() then
-    -- Immediate mode: iterate the z-index ordered list (reverse order =
-    -- topmost first). pointHitsElement supplies the bounds + display guard.
-    for i = #Context._zIndexOrderedElements, 1, -1 do
-      local element = Context._zIndexOrderedElements[i]
-      if pointHitsElement(element, x, y) then
-        local overflowX = element.overflowX or element.overflow
-        local overflowY = element.overflowY or element.overflow
-        if
-          (overflowX == "scroll" or overflowX == "auto" or overflowY == "scroll" or overflowY == "auto")
-          and (element._overflowX or element._overflowY)
-        then
-          return element
-        end
-      end
-    end
-    return nil
-  else
-    -- Retained mode: recursive tree walk from topElements. Children are
-    -- checked before self (deepest scrollable wins); accumulated scroll
-    -- offsets are threaded through pointHitsElement so descendants of
-    -- scrolled containers are hit-tested against their translated position.
-    local function findInTree(elements, scrollOffsetX, scrollOffsetY)
-      scrollOffsetX = scrollOffsetX or 0
-      scrollOffsetY = scrollOffsetY or 0
-      for i = #elements, 1, -1 do
-        local element = elements[i]
-        if pointHitsElement(element, x, y, scrollOffsetX, scrollOffsetY) then
-          if #element.children > 0 then
-            local childScrollOffsetX = scrollOffsetX
-            local childScrollOffsetY = scrollOffsetY
-            if elementHasScrollableOverflow(element) then
-              childScrollOffsetX = childScrollOffsetX + (element._scrollX or 0)
-              childScrollOffsetY = childScrollOffsetY + (element._scrollY or 0)
-            end
-            local childResult = findInTree(element.children, childScrollOffsetX, childScrollOffsetY)
-            if childResult then
-              return childResult
-            end
-          end
-          -- No descendant was scrollable — check self.
-          local overflowX = element.overflowX or element.overflow
-          local overflowY = element.overflowY or element.overflow
-          if
-            (overflowX == "scroll" or overflowX == "auto" or overflowY == "scroll" or overflowY == "auto")
-            and (element._overflowX or element._overflowY)
-          then
-            return element
-          end
-        end
-      end
-      return nil
-    end
-    return findInTree(Context.topElements)
-  end
-end
-
--- Check whether immediate mode is active.
--- This is the single canonical accessor for the mode flag consumed throughout
--- the framework. Mode-aware branches elsewhere call this instead of reading
--- `Context._immediateMode` directly, so the literal mode flag only appears
--- here (its definition) and in StateManager (its mirrored storage) — never
--- scattered across Element / behaviors / managers (behavior-mode-unification
--- task 11).
---@return boolean
-function Context.isImmediateMode()
-  return Context._immediateMode
-end
-
---@return number, number -- scaleX, scaleY
-function Context.getScaleFactors()
-  return Context.scaleFactors.x, Context.scaleFactors.y
-end
-
--- Register an element in the z-index ordered tree (for immediate mode)
---@param element Element The element to register
-function Context.registerElement(element)
-  if not Context.isImmediateMode() then
-    return
-  end
-
-  table.insert(Context._zIndexOrderedElements, element)
-end
-
-function Context.clearFrameElements()
-  Context._zIndexOrderedElements = {}
-  Context.clearInteractiveCache()
-end
-
--- Compute the composite z-index key for an element.
--- rootZ * ROOT_WEIGHT + depth * DEPTH_WEIGHT + ownZ
---
--- ROOT_WEIGHT (10^10) gives the top-level ancestor's z-index 10 digits of significance.
--- DEPTH_WEIGHT (10^3) gives nesting depth 3 digits, ensuring children always sort above
--- their ancestors. The element's own z (capped to ±999 by ZIndex.clamp) fits within the
--- remaining 3 digits without interfering with the depth component.
---
--- These weights assume |z| <= ZIndex.MAX_Z and practical tree depths (< 10^7), which
--- keeps the composite key well within Lua's exact integer range (2^53 ≈ 9 × 10^15).
---
--- This is the SINGLE canonical z-index ordering function, used by both
--- sortElementsByZIndex (the immediate-mode flat list sort) and
--- findInteractiveAtPosition (the mode-agnostic occlusion sort). Keeping them
--- on the same key ensures the interactive topmost element matches the visual
--- draw order — a button in a z=50 MainMenu window must occlude a button in a
--- z=0 BottomBar even when both buttons default to own z=0.
-local function getEffectiveZIndex(elem)
-  local ownZ = elem.z or 0
-  local rootZ = ownZ
-  local depth = 0
-  local current = elem.parent
-  while current do
-    rootZ = current.z or 0
-    depth = depth + 1
-    current = current.parent
-  end
-  return rootZ * ZIndex.ROOT_WEIGHT + depth * ZIndex.DEPTH_WEIGHT + ownZ
-end
-
-- Public exposure so FlexLove.getElementAtPosition shares the single
-- implementation instead of duplicating the parent-chain walk as a closure.
-Context.getEffectiveZIndex = getEffectiveZIndex
-
--- Sort elements by z-index (called after all elements are registered)
-function Context.sortElementsByZIndex()
-  -- Precompute the composite key ONCE per element so the sort comparator is a
-  -- pure table lookup (O(1)) instead of re-walking the parent chain on every
-  -- O(N log N) comparison. This function runs every frame in immediate mode.
-  local elements = Context._zIndexOrderedElements
-  local zIndices = {}
-  for i = 1, #elements do
-    zIndices[elements[i]] = getEffectiveZIndex(elements[i])
-  end
-  table.sort(elements, function(a, b)
-    return zIndices[a] < zIndices[b]
-  end)
-end
-
--- Find the topmost interactive element at a screen position, regardless of mode.
--- Replaces the former immediate-mode-only `Context.getTopElementAt()` (removed
--- in unified-event-routing task 05) and the retained-mode `_activeEventElement`
--- mechanism — both are now funneled through this single entry point.
---
--- In immediate mode this replaces Context.getTopElementAt() (which only worked
--- in immediate mode). In retained mode this provides the same role as the
--- _activeEventElement set by flexlove.getElementAtPosition().
---
--- An element is "interactive" if it has an onEvent handler, themeComponent, or is editable.
---@param x number Screen X coordinate
---@param y number Screen Y coordinate
---@return Element|nil The topmost interactive element, or nil
-function Context.findInteractiveAtPosition(x, y)
-  -- Per-frame cache: Clickable.onUpdate runs this for every interactive
-  -- element under the same cursor, but the result for a given (x,y) is
-  -- identical across all of them within a single update pass. Returning a
-  -- cached element restores the old 1x/frame cost of the _activeEventElement
-  -- mechanism that task 05 replaced. Cache auto-invalidates when the
-  -- topElements table reference changes (so tests and mid-frame rebuilds get
-  -- fresh results) and is cleared explicitly per-frame in flexlove.update.
-  local cache = Context._interactiveLookupCache
-  if
-    cache.valid
-    and cache.x == x
-    and cache.y == y
-    and cache.topElementsRef == Context.topElements
-    and cache.frameNumber == Context._frameNumber
-  then
-    return cache.result
-  end
-
-  local interactiveCandidates = {}
-
-  local function collectInteractive(element, scrollOffsetX, scrollOffsetY)
-    scrollOffsetX = scrollOffsetX or 0
-    scrollOffsetY = scrollOffsetY or 0
-
-    if not pointHitsElement(element, x, y, scrollOffsetX, scrollOffsetY) then
-      return
-    end
-
-    -- Check if this element is interactive
-    if element.onEvent or element.themeComponent or element.editable then
-      table.insert(interactiveCandidates, element)
-    end
-
-    -- Recurse into children with accumulated scroll offset
-    local childScrollOffsetX = scrollOffsetX
-    local childScrollOffsetY = scrollOffsetY
-    if elementHasScrollableOverflow(element) then
-      childScrollOffsetX = childScrollOffsetX + (element._scrollX or 0)
-      childScrollOffsetY = childScrollOffsetY + (element._scrollY or 0)
-    end
-
-    for _, child in ipairs(element.children) do
-      collectInteractive(child, childScrollOffsetX, childScrollOffsetY)
-    end
-  end
-
-  -- Always traverse the tree (works in both modes — topElements exists always)
-  for _, element in ipairs(Context.topElements) do
-    collectInteractive(element)
-  end
-
-  -- Sort by composite z-index descending — topmost wins. The composite key
-  -- (rootZ * ROOT_WEIGHT + depth * DEPTH_WEIGHT + ownZ) matches the ordering
-  -- used by sortElementsByZIndex / _zIndexOrderedElements, so the interactive
-  -- topmost element matches the visual draw order. This is critical for the
-  -- game's multi-window layout: a button inside a z=50 MainMenu window must
-  -- occlude a button inside a z=0 BottomBar even when both buttons default to
-  -- own z=0. Sorting by own-z alone (the original implementation) couldn't
-  -- distinguish them, so the wrong window's button could win, leaving the
-  -- visible button's isActiveElement=false and clicks/hover dead.
-  local zIndices = {}
-  for _, el in ipairs(interactiveCandidates) do
-    zIndices[el] = getEffectiveZIndex(el)
-  end
-  table.sort(interactiveCandidates, function(a, b)
-    return zIndices[a] > zIndices[b]
-  end)
-
-  local result = interactiveCandidates[1]
-
-  cache.x = x
-  cache.y = y
-  cache.result = result
-  cache.topElementsRef = Context.topElements
-  cache.frameNumber = Context._frameNumber
-  cache.valid = true
-
-  return result
-end
-
--- Invalidate the per-frame `findInteractiveAtPosition` cache.
--- Called once at the top of `flexlove.update` (the natural per-frame boundary
--- in both modes) and from `clearFrameElements` (immediate-mode mid-frame
--- rebuild). After invalidation the next lookup recomputes fresh.
-function Context.clearInteractiveCache()
-  local cache = Context._interactiveLookupCache
-  cache.valid = false
-  cache.x = nil
-  cache.y = nil
-  cache.result = nil
-  cache.topElementsRef = nil
-  cache.frameNumber = -1
-end
-
--- Set the focused element (centralizes focus management)
--- Automatically blurs the previously focused element if different
---@param element Element|nil The element to focus (nil to clear focus)
-function Context.setFocused(element)
-  if Context._focusedElement == element then
-    return -- Already focused
-  end
-
-  -- Prevent re-entry during focus change
-  if Context._settingFocus then
-    return
-  end
-  Context._settingFocus = true
-
-  -- Save reference to previously focused element before updating
-  local oldFocusedElement = Context._focusedElement
-
-  -- Blur previously focused element
-  if oldFocusedElement and oldFocusedElement ~= element then
-    if oldFocusedElement._textEditor then
-      oldFocusedElement._textEditor:blur(oldFocusedElement)
-    end
-  end
-
-  -- Set new focused element and persist its id for immediate-mode rehydration
-  Context._focusedElement = element
-  Context._focusedElementId = element and (element.id ~= "" and element.id or nil) or nil
-
-  -- Notify any registered focus change hook (e.g. FocusIndicator)
-  if Context._onFocusChanged then
-    Context._onFocusChanged(element)
-  end
-
-  -- Focus the new element's text editor if it has one
-  if element and element._textEditor then
-    element._textEditor._focused = true
-  end
-
-  Context._settingFocus = false
-end
-
--- Recursively search for an element by id in an element tree
---@param root Element The root element to start searching from
---@param targetId string The id to search for
---@return Element|nil The element with the matching id, or nil if not found
-local function findElementById(root, targetId)
-  if root.id == targetId then
-    return root
-  end
-  for _, child in ipairs(root.children or {}) do
-    local found = findElementById(child, targetId)
-    if found then
-      return found
-    end
-  end
-  return nil
-end
-
--- Rehydrate _focusedElement from _focusedElementId by scanning live elements.
--- Called at the start of getFocused() in immediate mode so stale references
--- are always replaced with the current-frame object before use.
-function Context._rehydrateFocus()
-  if not Context._focusedElementId then
-    Context._focusedElement = nil
-    return
-  end
-
-  -- First, try a fast linear search through all registered elements
-  for _, elem in ipairs(Context._zIndexOrderedElements) do
-    if elem.id == Context._focusedElementId then
-      Context._focusedElement = elem
-      return
-    end
-  end
-
-  -- If not found, recursively search from top-level elements
-  -- This handles cases where elements may not be in _zIndexOrderedElements
-  for _, topLevel in ipairs(Context.topElements or {}) do
-    local found = findElementById(topLevel, Context._focusedElementId)
-    if found then
-      Context._focusedElement = found
-      return
-    end
-  end
-
-  -- Element with that id is not present this frame (e.g. screen changed)
-  Context._focusedElement = nil
-end
-
--- Get the currently focused element
---@return Element|nil The focused element, or nil if none
-function Context.getFocused()
-  if Context.isImmediateMode() then
-    Context._rehydrateFocus()
-  end
-  return Context._focusedElement
-end
-
--- Clear focus from any element
-function Context.clearFocus()
-  Context._focusedElementId = nil
-  Context.setFocused(nil)
-end
-
--- Get all focusable elements in tab order, regardless of mode.
--- In immediate mode this extracts from _zIndexOrderedElements (flat, z-sorted).
--- In retained mode it walks the element tree (DOM order).
--- In both modes, display:none elements are excluded.
---@return table<Element> List of focusable elements in tab order
-function Context.getFocusableElements()
-  local focusable = {}
-
-  local function isFocusable(elem)
-    if elem.display == false then
-      return false
-    end
-    -- Use Element:isFocusable() for consistent behavior
-    return Element.isFocusable(elem)
-  end
-
-  local function collectFromTree(elements)
-    for _, elem in ipairs(elements) do
-      if isFocusable(elem) then
-        table.insert(focusable, elem)
-      end
-      if #elem.children > 0 then
-        collectFromTree(elem.children)
-      end
-    end
-  end
-
-  if Context._immediateMode then
-    -- Immediate mode: _zIndexOrderedElements is already in z-index order (lowest first),
-    -- which approximates tab order for most UIs.
-    for _, elem in ipairs(Context._zIndexOrderedElements) do
-      if isFocusable(elem) then
-        table.insert(focusable, elem)
-      end
-    end
-  else
-    -- Retained mode: walk the top element trees in DOM order
-    collectFromTree(Context.topElements)
-  end
-
-  return focusable
-end
-
-- ====================
-- Navigation Context
-- ====================
-
--- Push current focus onto stack (for modals/dialogs)
---@param element Element?
-function Context.pushFocusStack(element)
-  Context._navigationContext.lastFocusedElement = Context._focusedElement
-  if element then
-    Context.setFocused(element)
-  end
-end
-
--- Pop focus from stack (return from modal)
---@return Element?
-function Context.popFocusStack()
-  local previous = Context._navigationContext.lastFocusedElement
-  Context._navigationContext.lastFocusedElement = nil
-  Context.setFocused(previous)
-  return previous
-end
-
--- Set navigation container (scope for tab navigation)
---@param element Element?
-function Context.setNavigationContainer(element)
-  Context._navigationContext.containerElement = element
-end
-
--- Get navigation container
---@return Element?
-function Context.getNavigationContainer()
-  return Context._navigationContext.containerElement
-end
-
-return Context
@@ -1,171 +0,0 @@
-- Layout, flex, text, image, and ARIA enums used across FlexLove.
-- Extracted from utils so utils stays under its LOC budget; re-exported as
-- `utils.enums` for backward compatibility.
-
-local enums = {
-  ---@enum TextAlign
-  TextAlign = { START = "start", CENTER = "center", END = "end", JUSTIFY = "justify" },
-  ---@enum TextAlignVertical
-  TextAlignVertical = { START = "start", CENTER = "center", END = "end" },
-  ---@enum Positioning
-  Positioning = { ABSOLUTE = "absolute", RELATIVE = "relative", FLEX = "flex", GRID = "grid" },
-  ---@enum FlexDirection
-  FlexDirection = {
-    HORIZONTAL = "horizontal",
-    VERTICAL = "vertical",
-    ROW = "row",
-    COLUMN = "column",
-    HORIZONTAL_REVERSE = "horizontal-reverse",
-    VERTICAL_REVERSE = "vertical-reverse",
-    ROW_REVERSE = "row-reverse",
-    COLUMN_REVERSE = "column-reverse",
-  },
-  ---@enum JustifyContent
-  JustifyContent = {
-    FLEX_START = "flex-start",
-    CENTER = "center",
-    SPACE_AROUND = "space-around",
-    FLEX_END = "flex-end",
-    SPACE_EVENLY = "space-evenly",
-    SPACE_BETWEEN = "space-between",
-  },
-  ---@enum JustifySelf
-  JustifySelf = {
-    AUTO = "auto",
-    FLEX_START = "flex-start",
-    CENTER = "center",
-    FLEX_END = "flex-end",
-    SPACE_AROUND = "space-around",
-    SPACE_EVENLY = "space-evenly",
-    SPACE_BETWEEN = "space-between",
-  },
-  ---@enum AlignItems
-  AlignItems = {
-    STRETCH = "stretch",
-    FLEX_START = "flex-start",
-    FLEX_END = "flex-end",
-    CENTER = "center",
-    BASELINE = "baseline",
-  },
-  ---@enum AlignSelf
-  AlignSelf = {
-    AUTO = "auto",
-    STRETCH = "stretch",
-    FLEX_START = "flex-start",
-    FLEX_END = "flex-end",
-    CENTER = "center",
-    BASELINE = "baseline",
-  },
-  ---@enum AlignContent
-  AlignContent = {
-    STRETCH = "stretch",
-    FLEX_START = "flex-start",
-    FLEX_END = "flex-end",
-    CENTER = "center",
-    SPACE_BETWEEN = "space-between",
-    SPACE_AROUND = "space-around",
-  },
-  ---@enum FlexWrap
-  FlexWrap = { NOWRAP = "nowrap", WRAP = "wrap", WRAP_REVERSE = "wrap-reverse" },
-  ---@enum TextSize
-  TextSize = {
-    XXS = "xxs",
-    XS = "xs",
-    SM = "sm",
-    MD = "md",
-    LG = "lg",
-    XL = "xl",
-    XXL = "xxl",
-    XL3 = "3xl",
-    XL4 = "4xl",
-  },
-  ---@enum ImageRepeat
-  ImageRepeat = {
-    NO_REPEAT = "no-repeat",
-    REPEAT = "repeat",
-    REPEAT_X = "repeat-x",
-    REPEAT_Y = "repeat-y",
-    SPACE = "space",
-    ROUND = "round",
-  },
-
-  ---@enum ARIA Role (accessibility roles for screen readers)
-  ARIA = {
-    -- Widget roles
-    BUTTON = "button",
-    CHECKBOX = "checkbox",
-    LINK = "link",
-    MENUITEM = "menuitem",
-    MENUITEMCHECKBOX = "menuitemcheckbox",
-    MENUITEMRADIO = "menuitemradio",
-    PROGRESSBAR = "progressbar",
-    RADIO = "radio",
-    SCROLLBAR = "scrollbar",
-    SLIDER = "slider",
-    SPINBUTTON = "spinbutton",
-    SWITCH = "switch",
-    TAB = "tab",
-    TABLIST = "tablist",
-    TABPANEL = "tabpanel",
-    TEXTBOX = "textbox",
-    TOOLTIP = "tooltip",
-    TREEITEM = "treeitem",
-    COMBOBOX = "combobox",
-    GRID = "grid",
-    GRIDCELL = "gridcell",
-    LISTBOX = "listbox",
-    LISTITEM = "listitem",
-    MENU = "menu",
-    MENUBAR = "menubar",
-    TREE = "tree",
-    TREEGRID = "treegrid",
-    WINDOW = "window",
-    DIALOG = "dialog",
-    ALERTDIALOG = "alertdialog",
-
-    -- Landmark roles
-    BANNER = "banner",
-    COMPLEMENTARY = "complementary",
-    CONTENTINFO = "contentinfo",
-    FORM = "form",
-    MAIN = "main",
-    NAVIGATION = "navigation",
-    REGION = "region",
-    SEARCH = "search",
-
-    -- Live region roles
-    ALERT = "alert",
-    LOG = "log",
-    MARQUEE = "marquee",
-    STATUS = "status",
-    TIMERTIME = "timer",
-
-    -- Document structure roles
-    ARTICLE = "article",
-    BLOCKQUOTEBLOCKQUOTE = "blockquote",
-    CAPTION = "caption",
-    CODE = "code",
-    DEFINITION = "definition",
-    DELETED = "deletion",
-    DIRECTORY = "directory",
-    DIVISION = "division",
-    EMphasis = "emphasis",
-    HEADING = "heading",
-    INSERTED = "insertion",
-    LIST = "list",
-    MARK = "mark",
-    MATH = "math",
-    NONE = "none",
-    PARAGRAPH = "paragraph",
-    PRESENTATION = "presentation",
-    SEPARATOR = "separator",
-    STRONG = "strong",
-    SUBSCRIPT = "subscript",
-    SUPERSCRIPT = "superscript",
-    TERM = "term",
-    TIME = "time",
-    VARIABLE = "variable",
-  },
-}
-
-return { enums = enums }
@@ -1,843 +0,0 @@
---@class EventHandler
---@field onEvent fun(element:Element, event:InputEvent)?
---@field onEventDeferred boolean?
---@field onTouchEvent fun(element:Element, touchEvent:InputEvent)? -- Touch-specific callback
---@field onTouchEventDeferred boolean? -- Whether onTouchEvent is deferred
---@field onGesture fun(element:Element, gesture:table)? -- Gesture callback
---@field onGestureDeferred boolean? -- Whether onGesture is deferred
---@field touchEnabled boolean -- Whether touch events are processed (default: true)
---@field multiTouchEnabled boolean -- Whether multi-touch is supported (default: false)
---@field _pressed table<number, boolean>
---@field _lastClickTime number?
---@field _lastClickButton number?
---@field _clickCount number
---@field _dragStartX table<number, number>
---@field _dragStartY table<number, number>
---@field _lastMouseX table<number, number>
---@field _lastMouseY table<number, number>
---@field _touches table<string, table> -- Multi-touch state per touch ID
---@field _touchStartPositions table<string, table> -- Touch start positions
---@field _lastTouchPositions table<string, table> -- Last touch positions for delta
---@field _touchHistory table<string, table> -- Touch position history for gestures (last 5)
---@field _hovered boolean
---@field _scrollbarPressHandled boolean
---@field _InputEvent table
---@field _utils table
---@field _Performance Performance? Performance module dependency
---@field _ErrorHandler ErrorHandler
-local EventHandler = {}
-EventHandler.__index = EventHandler
-
--- Initialize module with shared dependencies
---@param deps table Dependencies {Performance, ErrorHandler, InputEvent, Context, utils}
-function EventHandler.init(deps)
-  EventHandler._Performance = deps.Performance
-  EventHandler._ErrorHandler = deps.ErrorHandler
-  EventHandler._InputEvent = deps.InputEvent
-  EventHandler._utils = deps.utils
-  EventHandler._Context = deps.Context
-end
-
---@param config table Configuration options
---@return EventHandler
-function EventHandler.new(config)
-  config = config or {}
-  local self = setmetatable({}, EventHandler)
-
-  self.onEvent = config.onEvent
-  self.onEventDeferred = config.onEventDeferred
-  self.onTouchEvent = config.onTouchEvent
-  self.onTouchEventDeferred = config.onTouchEventDeferred or false
-  self.onGesture = config.onGesture
-  self.onGestureDeferred = config.onGestureDeferred or false
-  self.touchEnabled = config.touchEnabled ~= false -- Default true
-  self.multiTouchEnabled = config.multiTouchEnabled or false -- Default false
-
-  self._pressed = config._pressed or {}
-
-  self._lastClickTime = config._lastClickTime
-  self._lastClickButton = config._lastClickButton
-  self._clickCount = config._clickCount or 0
-
-  -- FocusIndicator reference (set after initialization)
-  self._FocusIndicator = nil
-
-  self._dragStartX = config._dragStartX or {}
-  self._dragStartY = config._dragStartY or {}
-  self._lastMouseX = config._lastMouseX or {}
-  self._lastMouseY = config._lastMouseY or {}
-
-  -- Multi-touch tracking
-  self._touches = config._touches or {}
-  self._touchStartPositions = config._touchStartPositions or {}
-  self._lastTouchPositions = config._lastTouchPositions or {}
-  self._touchHistory = config._touchHistory or {}
-
-  self._hovered = config._hovered or false
-
-  self._scrollbarPressHandled = false
-
-  return self
-end
-
--- Get state for persistence (for immediate mode)
---@return table State data
-function EventHandler:getState()
-  return {
-    _pressed = self._pressed,
-    _lastClickTime = self._lastClickTime,
-    _lastClickButton = self._lastClickButton,
-    _clickCount = self._clickCount,
-    _dragStartX = self._dragStartX,
-    _dragStartY = self._dragStartY,
-    _lastMouseX = self._lastMouseX,
-    _lastMouseY = self._lastMouseY,
-    _touches = self._touches,
-    _touchStartPositions = self._touchStartPositions,
-    _lastTouchPositions = self._lastTouchPositions,
-    _touchHistory = self._touchHistory,
-    _hovered = self._hovered,
-  }
-end
-
--- Restore state from persistence (for immediate mode)
---@param state table State data
-function EventHandler:setState(state)
-  if not state then
-    return
-  end
-
-  self._pressed = state._pressed or {}
-  self._lastClickTime = state._lastClickTime
-  self._lastClickButton = state._lastClickButton
-  self._clickCount = state._clickCount or 0
-  self._dragStartX = state._dragStartX or {}
-  self._dragStartY = state._dragStartY or {}
-  self._lastMouseX = state._lastMouseX or {}
-  self._lastMouseY = state._lastMouseY or {}
-  self._touches = state._touches or {}
-  self._touchStartPositions = state._touchStartPositions or {}
-  self._lastTouchPositions = state._lastTouchPositions or {}
-  self._touchHistory = state._touchHistory or {}
-  self._hovered = state._hovered or false
-end
-
--- Process mouse button events in the update cycle
---@param element Element The parent element
---@param mx number Mouse X position
---@param my number Mouse Y position
---@param isHovering boolean Whether mouse is over element
---@param isActiveElement boolean Whether this is the top element at mouse position
-function EventHandler:processMouseEvents(element, mx, my, isHovering, isActiveElement)
-  -- Start performance timing
-  -- Performance accessed via EventHandler._Performance
-  if EventHandler._Performance and EventHandler._Performance.enabled then
-    EventHandler._Performance:startTimer("event_mouse")
-  end
-
-  -- Check if currently dragging (allows drag continuation even if occluded)
-  local isDragging = false
-  for _, button in ipairs({ 1, 2, 3 }) do
-    if self._pressed[button] and love.mouse.isDown(button) then
-      isDragging = true
-      break
-    end
-  end
-
-  -- Check if any button is currently pressed (tracked state)
-  local hasTrackedPress = false
-  for _, button in ipairs({ 1, 2, 3 }) do
-    if self._pressed[button] then
-      hasTrackedPress = true
-      break
-    end
-  end
-
-  -- Can only process events if we have handler, element is enabled, and is active or dragging or has tracked press
-  -- Read onEvent from element (source of truth), fallback to handler cache for backwards compat
-  local canProcessEvents = (
-    element.onEvent
-    or self.onEvent
-    or element.editable
-    or element._selectState
-    or element.selectOption
-  )
-    and element.visibility ~= "hidden"
-    and not element.disabled
-    and (isActiveElement or isDragging or hasTrackedPress)
-
-  if not canProcessEvents then
-    -- If not hovering and no buttons are physically pressed, reset all pressed states
-    -- This ensures the pressed state is cleared when mouse leaves without button held
-    if not isHovering and not isDragging then
-      for _, button in ipairs({ 1, 2, 3 }) do
-        if self._pressed[button] and not love.mouse.isDown(button) then
-          self._pressed[button] = false
-          self._dragStartX[button] = nil
-          self._dragStartY[button] = nil
-        end
-      end
-    end
-
-    -- Track hover state changes even when events can't be processed
-    -- Fire synthetic unhover when element becomes disabled while hovered
-    if element.disabled and self._hovered then
-      self._hovered = false
-      if element.onEvent or self.onEvent then
-        local modifiers = EventHandler._utils.getModifiers()
-        local unhoverEvent = EventHandler._InputEvent.new({
-          type = "unhover",
-          button = 0,
-          x = mx,
-          y = my,
-          modifiers = modifiers,
-          clickCount = 0,
-        })
-        self:_invokeCallback(element, unhoverEvent)
-      end
-    elseif self._hovered and not isHovering then
-      self._hovered = false
-      if element.onEvent or self.onEvent then
-        local modifiers = EventHandler._utils.getModifiers()
-        local unhoverEvent = EventHandler._InputEvent.new({
-          type = "unhover",
-          button = 0,
-          x = mx,
-          y = my,
-          modifiers = modifiers,
-          clickCount = 0,
-        })
-        self:_invokeCallback(element, unhoverEvent)
-      end
-    end
-
-    if EventHandler._Performance and EventHandler._Performance.enabled then
-      EventHandler._Performance:stopTimer("event_mouse")
-    end
-    return
-  end
-
-  -- Track hover state changes and fire hover/unhover events BEFORE button processing
-  -- This ensures hover fires before press when mouse first enters element
-  local wasHovered = self._hovered
-  local isHoveringAndActive = isHovering and isActiveElement
-
-  if isHoveringAndActive and not wasHovered then
-    -- Just started hovering - fire hover event
-    self._hovered = true
-    local modifiers = EventHandler._utils.getModifiers()
-    local hoverEvent = EventHandler._InputEvent.new({
-      type = "hover",
-      button = 0,
-      x = mx,
-      y = my,
-      modifiers = modifiers,
-      clickCount = 0,
-    })
-    self:_invokeCallback(element, hoverEvent)
-  elseif not isHoveringAndActive and wasHovered then
-    -- Just stopped hovering - fire unhover event
-    self._hovered = false
-    local modifiers = EventHandler._utils.getModifiers()
-    local unhoverEvent = EventHandler._InputEvent.new({
-      type = "unhover",
-      button = 0,
-      x = mx,
-      y = my,
-      modifiers = modifiers,
-      clickCount = 0,
-    })
-    self:_invokeCallback(element, unhoverEvent)
-  end
-
-  -- Process all three mouse buttons
-  local buttons = { 1, 2, 3 } -- left, right, middle
-
-  for _, button in ipairs(buttons) do
-    -- Check if this button was tracked as pressed
-    local wasPressed = self._pressed[button]
-    local isPhysicallyPressed = love.mouse.isDown(button)
-
-    if isHovering or isDragging or wasPressed then
-      if isPhysicallyPressed then
-        -- Button is pressed down
-        if not wasPressed then
-          -- Just pressed - fire press event (only if hovering)
-          if isHovering then
-            self:_handleMousePress(element, mx, my, button)
-          end
-        else
-          -- Button is still pressed - check for drag
-          self:_handleMouseDrag(element, mx, my, button, isHovering)
-        end
-      elseif wasPressed then
-        -- Button was just released
-        -- Only fire click and release events if mouse is still hovering AND element is active
-        -- (not occluded by another element)
-        if isHovering and isActiveElement then
-          self:_handleMouseRelease(element, mx, my, button)
-        else
-          -- Mouse left before release OR element is occluded - just clear the pressed state without firing events
-          self._pressed[button] = false
-          self._dragStartX[button] = nil
-          self._dragStartY[button] = nil
-        end
-      end
-    end
-  end
-
-  -- After processing events, reset pressed states for buttons that are no longer held
-  -- This handles the case where mouse leaves while button is held, then released
-  if not isHovering and not isDragging then
-    for _, button in ipairs({ 1, 2, 3 }) do
-      if self._pressed[button] and not love.mouse.isDown(button) then
-        self._pressed[button] = false
-        self._dragStartX[button] = nil
-        self._dragStartY[button] = nil
-      end
-    end
-  end
-
-  -- Stop performance timing
-  if EventHandler._Performance and EventHandler._Performance.enabled then
-    EventHandler._Performance:stopTimer("event_mouse")
-  end
-end
-
--- Handle mouse button press
---@param element Element The parent element
---@param mx number Mouse X position
---@param my number Mouse Y position
---@param button number Mouse button (1=left, 2=right, 3=middle)
-function EventHandler:_handleMousePress(element, mx, my, button)
-  -- Check if press is on scrollbar first (skip if already handled)
-  if button == 1 and not self._scrollbarPressHandled and element._handleScrollbarPress then
-    if element:_handleScrollbarPress(mx, my, button) then
-      -- Scrollbar consumed the event, mark as pressed to prevent onEvent
-      self._pressed[button] = true
-      self._scrollbarPressHandled = true
-      return
-    end
-  end
-
-  -- Fire press event
-  local modifiers = EventHandler._utils.getModifiers()
-  local pressEvent = EventHandler._InputEvent.new({
-    type = "press",
-    button = button,
-    x = mx,
-    y = my,
-    modifiers = modifiers,
-    clickCount = 1,
-  })
-  self:_invokeCallback(element, pressEvent)
-
-  self._pressed[button] = true
-
-  -- On left click, set keyboard focus to any focusable element (not just editable).
-  -- Clear the focus indicator since mouse navigation doesn't use it.
-  local isFocusable
-  if type(element.isFocusable) == "function" then
-    isFocusable = element:isFocusable()
-  else
-    isFocusable = (element.editable == true)
-      or (type(element.onEvent) == "function")
-      or element._selectState ~= nil
-      or element.selectOption ~= nil
-  end
-
-  if button == 1 and EventHandler._Context and isFocusable then
-    EventHandler._Context.setFocused(element)
-    -- Hide focus indicator - it's only for keyboard navigation
-    if EventHandler._FocusIndicator then
-      EventHandler._FocusIndicator.setFocused(nil)
-    end
-  end
-  -- Set mouse down position for text selection on left click
-  if button == 1 and element._textEditor then
-    element._mouseDownPosition = element._textEditor:mouseToTextPosition(element, mx, my)
-    element._textDragOccurred = false -- Reset drag flag on press
-  end
-
-  -- Record drag start position per button
-  self._dragStartX[button] = mx
-  self._dragStartY[button] = my
-  self._lastMouseX[button] = mx
-  self._lastMouseY[button] = my
-end
-
--- Handle mouse drag (while button is pressed and mouse moves)
---@param element Element The parent element
---@param mx number Mouse X position
---@param my number Mouse Y position
---@param button number Mouse button
---@param isHovering boolean Whether mouse is over element
-function EventHandler:_handleMouseDrag(element, mx, my, button, isHovering)
-  local lastX = self._lastMouseX[button] or mx
-  local lastY = self._lastMouseY[button] or my
-
-  if lastX ~= mx or lastY ~= my then
-    -- Handle scrollbar drag if scrollbar was pressed
-    if button == 1 and self._scrollbarPressHandled and element._handleScrollbarDrag then
-      element:_handleScrollbarDrag(mx, my)
-      self._lastMouseX[button] = mx
-      self._lastMouseY[button] = my
-      return -- Don't process other drag events while dragging scrollbar
-    end
-
-    -- Mouse has moved - fire drag event only if still hovering
-    if isHovering then
-      local modifiers = EventHandler._utils.getModifiers()
-      local dx = mx - self._dragStartX[button]
-      local dy = my - self._dragStartY[button]
-
-      local dragEvent = EventHandler._InputEvent.new({
-        type = "drag",
-        button = button,
-        x = mx,
-        y = my,
-        dx = dx,
-        dy = dy,
-        modifiers = modifiers,
-        clickCount = 1,
-      })
-      self:_invokeCallback(element, dragEvent)
-    end
-
-    -- Handle text selection drag for editable elements
-    if button == 1 and element.editable and element._focused and element._handleTextDrag then
-      element:_handleTextDrag(mx, my)
-    end
-
-    -- Update last known position for this button
-    self._lastMouseX[button] = mx
-    self._lastMouseY[button] = my
-  end
-end
-
--- Handle mouse button release
---@param mx number Mouse X position
---@param my number Mouse Y position
---@param button number Mouse button
-function EventHandler:_handleMouseRelease(element, mx, my, button)
-  local currentTime = love.timer.getTime()
-  local modifiers = EventHandler._utils.getModifiers()
-
-  -- Handle scrollbar release if scrollbar was pressed
-  if button == 1 and self._scrollbarPressHandled and element._handleScrollbarRelease then
-    element:_handleScrollbarRelease(button)
-    self._scrollbarPressHandled = false -- Reset flag
-    self._pressed[button] = false
-    self._dragStartX[button] = nil
-    self._dragStartY[button] = nil
-    return -- Don't process click events for scrollbar release
-  end
-
-  -- Determine click count (double-click detection)
-  local clickCount
-  local doubleClickThreshold = 0.3 -- 300ms for double-click
-
-  if
-    self._lastClickTime
-    and self._lastClickButton == button
-    and (currentTime - self._lastClickTime) < doubleClickThreshold
-  then
-    clickCount = self._clickCount + 1
-  else
-    clickCount = 1
-  end
-
-  self._clickCount = clickCount
-  self._lastClickTime = currentTime
-  self._lastClickButton = button
-
-  -- Determine event type based on button
-  local eventType = "click"
-  if button == 2 then
-    eventType = "rightclick"
-  elseif button == 3 then
-    eventType = "middleclick"
-  end
-
-  -- Fire click event
-  local clickEvent = EventHandler._InputEvent.new({
-    type = eventType,
-    button = button,
-    x = mx,
-    y = my,
-    modifiers = modifiers,
-    clickCount = clickCount,
-  })
-  self:_invokeCallback(element, clickEvent)
-
-  self._pressed[button] = false
-
-  -- Clean up drag tracking
-  self._dragStartX[button] = nil
-  self._dragStartY[button] = nil
-
-  -- Clean up text selection drag tracking
-  if button == 1 then
-    element._mouseDownPosition = nil
-  end
-
-  -- Focus editable elements on left click
-  if button == 1 and element.editable then
-    -- Only focus if not already focused (to avoid moving cursor to end)
-    local wasFocused = element:isFocused()
-    if not wasFocused then
-      element:focus()
-    end
-
-    -- Handle text click for cursor positioning and word selection
-    -- Only process click if no text drag occurred (to preserve drag selection)
-    if element._handleTextClick and not element._textDragOccurred then
-      element:_handleTextClick(mx, my, clickCount)
-    end
-
-    -- Reset drag flag after release
-    element._textDragOccurred = false
-  end
-
-  -- Fire release event
-  local releaseEvent = EventHandler._InputEvent.new({
-    type = "release",
-    button = button,
-    x = mx,
-    y = my,
-    modifiers = modifiers,
-    clickCount = clickCount,
-  })
-  self:_invokeCallback(element, releaseEvent)
-
-  if button == 1 and element._handleSelectRelease then
-    element:_handleSelectRelease()
-  end
-end
-
--- Process touch events in the update cycle
---@param element Element The parent element
-function EventHandler:processTouchEvents(element)
-  -- Start performance timing
-  if EventHandler._Performance and EventHandler._Performance.enabled then
-    EventHandler._Performance:startTimer("event_touch")
-  end
-
-  -- Check if element can process events
-  local canProcessEvents = (
-    element.onEvent
-    or self.onEvent
-    or element.onTouchEvent
-    or self.onTouchEvent
-    or element.editable
-  )
-    and not element.disabled
-    and self.touchEnabled
-
-  if not canProcessEvents then
-    if EventHandler._Performance and EventHandler._Performance.enabled then
-      EventHandler._Performance:stopTimer("event_touch")
-    end
-    return
-  end
-
-  local bx = element.x
-  local by = element.y
-  local bw = element._borderBoxWidth or (element.width + element.padding.left + element.padding.right)
-  local bh = element._borderBoxHeight or (element.height + element.padding.top + element.padding.bottom)
-
-  -- Get current active touches from LÖVE
-  local activeTouches = {}
-  local touches = love.touch.getTouches()
-  for _, id in ipairs(touches) do
-    activeTouches[tostring(id)] = true
-  end
-
-  -- Count active tracked touches for multi-touch filtering
-  local trackedTouchCount = 0
-  for _ in pairs(self._touches) do
-    trackedTouchCount = trackedTouchCount + 1
-  end
-
-  -- Process active touches
-  for _, id in ipairs(touches) do
-    local touchId = tostring(id)
-    local tx, ty = love.touch.getPosition(id)
-    local pressure = 1.0 -- LÖVE doesn't provide pressure by default
-
-    -- Check if touch is within element bounds
-    local isInside = tx >= bx and tx <= bx + bw and ty >= by and ty <= by + bh
-
-    if isInside then
-      if not self._touches[touchId] then
-        -- Multi-touch filtering: reject new touches when multiTouchEnabled=false
-        -- and we already have an active touch
-        if self.multiTouchEnabled or trackedTouchCount == 0 then
-          -- New touch began
-          self:_handleTouchBegan(element, touchId, tx, ty, pressure)
-          trackedTouchCount = trackedTouchCount + 1
-        end
-      else
-        -- Touch moved
-        self:_handleTouchMoved(element, touchId, tx, ty, pressure)
-      end
-    elseif self._touches[touchId] then
-      -- Touch moved outside or ended
-      if activeTouches[touchId] then
-        -- Still active but outside - fire moved event
-        self:_handleTouchMoved(element, touchId, tx, ty, pressure)
-      else
-        -- Touch ended
-        self:_handleTouchEnded(element, touchId, tx, ty, pressure)
-      end
-    end
-  end
-
-  -- Check for ended touches (touches that were tracked but are no longer active)
-  for touchId, _ in pairs(self._touches) do
-    if not activeTouches[touchId] then
-      -- Touch ended or cancelled
-      local lastPos = self._lastTouchPositions[touchId]
-      if lastPos then
-        self:_handleTouchEnded(element, touchId, lastPos.x, lastPos.y, 1.0)
-      else
-        -- Cleanup orphaned touch
-        self:_cleanupTouch(touchId)
-      end
-    end
-  end
-
-  -- Stop performance timing
-  if EventHandler._Performance and EventHandler._Performance.enabled then
-    EventHandler._Performance:stopTimer("event_touch")
-  end
-end
-
--- Handle touch began event
---@param element Element The parent element
---@param touchId string Touch identifier
---@param x number Touch X position
---@param y number Touch Y position
---@param pressure number Touch pressure (0-1)
-function EventHandler:_handleTouchBegan(element, touchId, x, y, pressure)
-  -- Create touch state
-  self._touches[touchId] = {
-    x = x,
-    y = y,
-    pressure = pressure,
-    timestamp = love.timer.getTime(),
-    phase = "began",
-  }
-
-  -- Record start position
-  self._touchStartPositions[touchId] = { x = x, y = y }
-  self._lastTouchPositions[touchId] = { x = x, y = y }
-
-  -- Initialize touch history
-  self._touchHistory[touchId] = { { x = x, y = y, timestamp = love.timer.getTime() } }
-
-  -- Create and fire touch press event
-  local touchEvent = EventHandler._InputEvent.fromTouch(touchId, x, y, "began", pressure)
-  touchEvent.type = "touchpress"
-  touchEvent.dx = 0
-  touchEvent.dy = 0
-  self:_invokeCallback(element, touchEvent)
-  self:_invokeTouchCallback(element, touchEvent)
-end
-
--- Handle touch moved event
---@param element Element The parent element
---@param touchId string Touch identifier
---@param x number Touch X position
---@param y number Touch Y position
---@param pressure number Touch pressure (0-1)
-function EventHandler:_handleTouchMoved(element, touchId, x, y, pressure)
-  local touchState = self._touches[touchId]
-
-  if not touchState then
-    -- Touch not tracked, ignore
-    return
-  end
-
-  local lastPos = self._lastTouchPositions[touchId]
-  if not lastPos or lastPos.x ~= x or lastPos.y ~= y then
-    -- Touch position changed
-    local startPos = self._touchStartPositions[touchId]
-    local dx = x - startPos.x
-    local dy = y - startPos.y
-
-    -- Update touch state
-    touchState.x = x
-    touchState.y = y
-    touchState.pressure = pressure
-    touchState.phase = "moved"
-
-    -- Update last position
-    self._lastTouchPositions[touchId] = { x = x, y = y }
-
-    -- Add to touch history (keep last 5 positions)
-    local history = self._touchHistory[touchId] or {}
-    table.insert(history, { x = x, y = y, timestamp = love.timer.getTime() })
-    if #history > 5 then
-      table.remove(history, 1)
-    end
-    self._touchHistory[touchId] = history
-
-    -- Create and fire touch move event
-    local touchEvent = EventHandler._InputEvent.fromTouch(touchId, x, y, "moved", pressure)
-    touchEvent.type = "touchmove"
-    touchEvent.dx = dx
-    touchEvent.dy = dy
-    self:_invokeCallback(element, touchEvent)
-    self:_invokeTouchCallback(element, touchEvent)
-  end
-end
-
--- Handle touch ended event
---@param element Element The parent element
---@param touchId string Touch identifier
---@param x number Touch X position
---@param y number Touch Y position
---@param pressure number Touch pressure (0-1)
-function EventHandler:_handleTouchEnded(element, touchId, x, y, pressure)
-  local touchState = self._touches[touchId]
-
-  if not touchState then
-    -- Touch not tracked, ignore
-    return
-  end
-
-  local startPos = self._touchStartPositions[touchId]
-  local dx = x - startPos.x
-  local dy = y - startPos.y
-
-  -- Create and fire touch release event
-  local touchEvent = EventHandler._InputEvent.fromTouch(touchId, x, y, "ended", pressure)
-  touchEvent.type = "touchrelease"
-  touchEvent.dx = dx
-  touchEvent.dy = dy
-  self:_invokeCallback(element, touchEvent)
-  self:_invokeTouchCallback(element, touchEvent)
-
-  -- Cleanup touch state
-  self:_cleanupTouch(touchId)
-end
-
--- Cleanup touch state
---@param touchId string Touch ID
-function EventHandler:_cleanupTouch(touchId)
-  self._touches[touchId] = nil
-  self._touchStartPositions[touchId] = nil
-  self._lastTouchPositions[touchId] = nil
-  self._touchHistory[touchId] = nil
-end
-
--- Get active touches on this element
---@return table<string, table> Active touches
-function EventHandler:getActiveTouches()
-  return self._touches
-end
-
--- Reset scrollbar press flag (called each frame)
-function EventHandler:resetScrollbarPressFlag()
-  self._scrollbarPressHandled = false
-end
-
--- Check if any mouse button is pressed
---@return boolean True if any button is pressed
-function EventHandler:isAnyButtonPressed()
-  for _, pressed in pairs(self._pressed) do
-    if pressed then
-      return true
-    end
-  end
-  return false
-end
-
--- Check if a specific button is pressed
---@param button number Mouse button (1=left, 2=right, 3=middle)
---@return boolean True if button is pressed
-function EventHandler:isButtonPressed(button)
-  return self._pressed[button] == true
-end
-
--- Invoke the onEvent callback, optionally deferring it if onEventDeferred is true
---@param element Element The element that triggered the event
---@param event InputEvent The event data
-function EventHandler:_invokeCallback(element, event)
-  -- Read onEvent from element (source of truth), fallback to handler cache for backwards compat
-  local callback = element.onEvent or self.onEvent
-  if not callback then
-    return
-  end
-
-  if self.onEventDeferred then
-    -- Get FlexLove module to defer the callback
-    local FlexLove = package.loaded["FlexLove"] or package.loaded["libs.FlexLove"]
-    if FlexLove and FlexLove.deferCallback then
-      FlexLove.deferCallback(function()
-        callback(element, event)
-      end)
-    else
-      EventHandler._ErrorHandler:error("EventHandler", "SYS_003", {
-        eventType = event.type,
-      })
-    end
-  else
-    callback(element, event)
-  end
-end
-
--- Invoke the onTouchEvent callback, optionally deferring it
---@param element Element The element that triggered the event
---@param event InputEvent The touch event data
-function EventHandler:_invokeTouchCallback(element, event)
-  -- Read onTouchEvent from element (source of truth), fallback to handler cache for backwards compat
-  local callback = element.onTouchEvent or self.onTouchEvent
-  if not callback then
-    return
-  end
-
-  if self.onTouchEventDeferred then
-    local FlexLove = package.loaded["FlexLove"] or package.loaded["libs.FlexLove"]
-    if FlexLove and FlexLove.deferCallback then
-      FlexLove.deferCallback(function()
-        callback(element, event)
-      end)
-    else
-      EventHandler._ErrorHandler:error("EventHandler", "SYS_003", {
-        eventType = event.type,
-      })
-    end
-  else
-    callback(element, event)
-  end
-end
-
--- Invoke the onGesture callback, optionally deferring it
---@param element Element The element that triggered the event
---@param gesture table The gesture data from GestureRecognizer
-function EventHandler:_invokeGestureCallback(element, gesture)
-  -- Read onGesture from element (source of truth), fallback to handler cache for backwards compat
-  local callback = element.onGesture or self.onGesture
-  if not callback then
-    return
-  end
-
-  if self.onGestureDeferred then
-    local FlexLove = package.loaded["FlexLove"] or package.loaded["libs.FlexLove"]
-    if FlexLove and FlexLove.deferCallback then
-      FlexLove.deferCallback(function()
-        callback(element, gesture)
-      end)
-    else
-      EventHandler._ErrorHandler:error("EventHandler", "SYS_003", {
-        gestureType = gesture.type,
-      })
-    end
-  else
-    callback(element, gesture)
-  end
-end
-
-return EventHandler
@@ -1,232 +0,0 @@
-local packageName = ... or "FocusIndicator"
-local modulePath = packageName:match("(.-)[^%.]+$")
-
-local function req(name)
-  return require(modulePath .. name)
-end
-
-local FocusIndicator = {}
-
--- Configuration
---@type KeyboardNavigationFocusIndicatorConfig
-FocusIndicator.config = {
-  enabled = true,
-
-  --- Custom draw function to override default rendering
-  ---@type function|nil
-  --- Called with: element, bounds, style - return true to skip default drawing
-  draw = nil,
-
-  -- Appearance
-  color = { 0.2, 0.6, 1.0, 0.8 }, -- Blue with 80% opacity
-  lineWidth = 2,
-  inset = -3, -- Negative value extends beyond element
-  borderRadius = 4,
-
-  -- Animation
-  animationDuration = 0.15, -- Seconds for focus animation
-  pulseEnabled = false, -- Enable pulsing animation
-  pulseDuration = 1.0, -- Seconds per pulse cycle
-  pulseScaleMin = 0.95, -- Minimum scale during pulse
-  pulseScaleMax = 1.05, -- Maximum scale during pulse
-}
-
--- State
-FocusIndicator._focusedElement = nil
-FocusIndicator._animationProgress = 0
-FocusIndicator._pulsePhase = 0
-FocusIndicator._hidden = true
-FocusIndicator._deps = nil
-
--- Initialize FocusIndicator module
---@param deps table Dependencies table containing Context and Color modules
---@field deps.Context table Context module for getting focused element
---@field deps.Color table Color module for color manipulation
-function FocusIndicator.init(deps)
-  FocusIndicator._deps = deps
-  FocusIndicator._Context = deps.Context
-  FocusIndicator._Color = deps.Color
-end
-
--- Update animation state for entrance and pulse effects
---@param dt number Delta time in seconds since last frame
-function FocusIndicator:update(dt)
-  if not FocusIndicator.config.enabled then
-    return
-  end
-
-  -- Update focus entrance animation
-  if FocusIndicator._animationProgress < 1 then
-    FocusIndicator._animationProgress =
-      math.min(1, FocusIndicator._animationProgress + (dt / FocusIndicator.config.animationDuration))
-  end
-
-  -- Update pulse animation
-  if FocusIndicator.config.pulseEnabled then
-    FocusIndicator._pulsePhase = (FocusIndicator._pulsePhase + dt) % FocusIndicator.config.pulseDuration
-  end
-end
-
--- Set the focused element to render indicator around
---@param element Element? The element to show focus indicator around, or nil to hide
-function FocusIndicator.setFocused(element)
-  FocusIndicator._focusedElement = element
-  FocusIndicator._hidden = element == nil
-  -- Reset animation when focus changes
-  if element then
-    FocusIndicator._animationProgress = 0
-  end
-end
-
--- Get the current scale factor for animations
--- Combines entrance scale (0.8 to 1.0) with optional pulse scale
---@return number Scale factor (typically 0.8-1.05 range)
-function FocusIndicator:getScale()
-  local scale = 1
-
-  -- Apply entrance animation (scale up from 0.8)
-  local entranceScale = 0.8 + (0.2 * FocusIndicator._animationProgress)
-  scale = scale * entranceScale
-
-  -- Apply pulse animation
-  if FocusIndicator.config.pulseEnabled then
-    local pulseProgress = FocusIndicator._pulsePhase / FocusIndicator.config.pulseDuration
-    -- Smooth sine wave pulse
-    local pulseScale = FocusIndicator.config.pulseScaleMin
-      + (FocusIndicator.config.pulseScaleMax - FocusIndicator.config.pulseScaleMin)
-        * (0.5 + 0.5 * math.sin(2 * math.pi * pulseProgress))
-    scale = scale * pulseScale
-  end
-
-  return scale
-end
-
--- Get the current opacity for the indicator
--- Applies entrance animation fade-in to the configured alpha
---@return number Alpha value (0-1 range)
-function FocusIndicator:getOpacity()
-  -- Fade in on focus
-  return FocusIndicator.config.color[4] * FocusIndicator._animationProgress
-end
-
--- Draw the focus indicator around the focused element
--- Renders a rounded rectangle border, or calls custom draw function if configured
--- Should be called from within love.draw() after all elements are drawn
-function FocusIndicator:draw()
-  if not FocusIndicator.config.enabled then
-    return
-  end
-
-  if FocusIndicator._hidden then
-    return
-  end
-
-  -- In immediate mode the stored element reference is stale (recreated every frame).
-  -- Always resolve through Context so we get the live object with up-to-date positions.
-  local element
-  if FocusIndicator._Context then
-    element = FocusIndicator._Context.getFocused()
-  else
-    element = FocusIndicator._focusedElement
-  end
-
-  if not element then
-    return
-  end
-
-  -- Get element dimensions (use border-box size which includes padding)
-  local x = element.x or 0
-  local y = element.y or 0
-  local w = element._borderBoxWidth
-    or (element.width + (element.padding and (element.padding.left + element.padding.right) or 0))
-  local h = element._borderBoxHeight
-    or (element.height + (element.padding and (element.padding.top + element.padding.bottom) or 0))
-
-  if w == 0 or h == 0 then
-    return
-  end
-
-  -- Calculate indicator dimensions with inset and scale
-  local inset = FocusIndicator.config.inset
-  local scale = self:getScale()
-
-  local indicatorX = x + inset
-  local indicatorY = y + inset
-  local indicatorW = w - 2 * inset
-  local indicatorH = h - 2 * inset
-
-  -- Center the scale around the element
-  local offsetX = (indicatorW * (1 - scale)) / 2
-  local offsetY = (indicatorH * (1 - scale)) / 2
-
-  indicatorX = indicatorX + offsetX
-  indicatorY = indicatorY + offsetY
-  indicatorW = indicatorW * scale
-  indicatorH = indicatorH * scale
-
-  -- Get color with animated opacity
-  local r, g, b = FocusIndicator.config.color[1], FocusIndicator.config.color[2], FocusIndicator.config.color[3]
-  local a = self:getOpacity()
-
-  -- Build style table for custom draw callback
-  local bounds = {
-    x = indicatorX,
-    y = indicatorY,
-    width = indicatorW,
-    height = indicatorH,
-  }
-
-  local style = {
-    color = { r = r, g = g, b = b, a = a },
-    lineWidth = FocusIndicator.config.lineWidth,
-    borderRadius = FocusIndicator.config.borderRadius,
-    scale = scale,
-    opacity = a,
-  }
-
-  -- Check for custom draw callback
-  if FocusIndicator.config.draw then
-    local skipDefault = FocusIndicator.config.draw(element, bounds, style)
-    if skipDefault then
-      return
-    end
-  end
-
-  -- Save current love.graphics state
-  local prevBlend, prevAlphaMode = love.graphics.getBlendMode()
-  local prevR, prevG, prevB, prevA = love.graphics.getColor()
-  local prevLineWidth = love.graphics.getLineWidth()
-
-  -- Set blend mode for transparency
-  love.graphics.setBlendMode("alpha")
-
-  -- Draw rounded rectangle border
-  love.graphics.setColor(r, g, b, a)
-  love.graphics.setLineWidth(FocusIndicator.config.lineWidth)
-
-  -- Draw the rounded rectangle border
-  local borderRadius = FocusIndicator.config.borderRadius
-  love.graphics.rectangle("line", indicatorX, indicatorY, indicatorW, indicatorH, borderRadius)
-
-  -- Restore love.graphics state
-  love.graphics.setBlendMode(prevBlend, prevAlphaMode)
-  love.graphics.setColor(prevR, prevG, prevB, prevA)
-  love.graphics.setLineWidth(prevLineWidth)
-end
-
--- Set the indicator color
---@param r number Red component (0-1 range)
---@param g number Green component (0-1 range)
---@param b number Blue component (0-1 range)
---@param a number|nil Alpha component (0-1 range), defaults to current alpha if omitted
-function FocusIndicator.setColor(r, g, b, a)
-  FocusIndicator.config.color = { r, g, b, a or FocusIndicator.config.color[4] }
-end
-
--- Set the stroke width for the indicator border
---@param width number Line width in pixels
-function FocusIndicator.setLineWidth(width)
-  FocusIndicator.config.lineWidth = width
-end
-
-return FocusIndicator
@@ -1,274 +0,0 @@
-local modulePath = (...):match("(.-)[^%.]+$")
-local function req(name)
-  return require(modulePath .. name)
-end
-
-- Font cache with LRU eviction, font resolution, and cache management.
-- `ErrorHandler` and `resolveImagePath` are injected via init() to avoid
-- a cross-import into utils (utils re-exports the cache via aliases).
-
-- Font cache with LRU eviction
-local FONT_CACHE = {}
-local FONT_CACHE_MAX_SIZE = 50
-local FONT_CACHE_STATS = {
-  hits = 0,
-  misses = 0,
-  evictions = 0,
-  size = 0,
-}
-
-local ErrorHandler = nil
-local resolveImagePath = nil
-
--- Initialize dependencies
---@param deps table Dependencies: { ErrorHandler = ErrorHandler, resolveImagePath = function }
-local function init(deps)
-  if type(deps) == "table" then
-    ErrorHandler = deps.ErrorHandler
-    resolveImagePath = deps.resolveImagePath
-  end
-end
-
-- LRU tracking: each entry has {font, lastUsed, accessCount}
-local function updateCacheAccess(cacheKey)
-  local entry = FONT_CACHE[cacheKey]
-  if entry then
-    entry.lastUsed = love.timer.getTime()
-    entry.accessCount = entry.accessCount + 1
-  end
-end
-
-local function evictLRU()
-  local oldestKey = nil
-  local oldestTime = math.huge
-
-  for key, entry in pairs(FONT_CACHE) do
-    -- Skip methods (get, getFont) - only evict cache entries (tables with lastUsed)
-    if type(entry) == "table" and entry.lastUsed then
-      if entry.lastUsed < oldestTime then
-        oldestTime = entry.lastUsed
-        oldestKey = key
-      end
-    end
-  end
-
-  if oldestKey then
-    FONT_CACHE[oldestKey] = nil
-    FONT_CACHE_STATS.evictions = FONT_CACHE_STATS.evictions + 1
-    FONT_CACHE_STATS.size = FONT_CACHE_STATS.size - 1
-  end
-end
-
--- Create or get a font from cache
---@param size number
---@param fontPath string?
---@return love.Font
-function FONT_CACHE.get(size, fontPath)
-  -- Bucket font sizes for better cache reuse (reduces unique cache entries)
-  -- Small sizes (< 20): round to nearest 2
-  -- Medium sizes (20-40): round to nearest 4
-  -- Large sizes (> 40): round to nearest 8
-  if size < 20 then
-    size = math.floor((size + 1) / 2) * 2
-  elseif size < 40 then
-    size = math.floor((size + 2) / 4) * 4
-  else
-    size = math.floor((size + 4) / 8) * 8
-  end
-
-  local cacheKey = fontPath and (fontPath .. ":" .. tostring(size)) or ("default:" .. tostring(size))
-
-  if FONT_CACHE[cacheKey] then
-    -- Cache hit
-    FONT_CACHE_STATS.hits = FONT_CACHE_STATS.hits + 1
-    updateCacheAccess(cacheKey)
-    return FONT_CACHE[cacheKey].font
-  end
-
-  -- Cache miss
-  FONT_CACHE_STATS.misses = FONT_CACHE_STATS.misses + 1
-
-  local font
-  if fontPath then
-    local resolvedPath = resolveImagePath(fontPath)
-    local success, result = pcall(love.graphics.newFont, resolvedPath, size)
-    if success then
-      font = result
-    else
-      if ErrorHandler then
-        ErrorHandler:warn("utils", "RES_004", {
-          resourceType = "font",
-          path = fontPath,
-        })
-      end
-      font = love.graphics.newFont(size)
-    end
-  else
-    font = love.graphics.newFont(size)
-  end
-
-  -- Per-glyph fallback so a non-Latin UI string is not drawn as tofu.
-  -- pcall'd require: FlexLove is vendored and must still load standalone.
-  local okUi, UiFont = pcall(require, "src.render.UiFont")
-  if okUi and UiFont then UiFont.attach(font, size) end
-
-  -- Add to cache with LRU metadata
-  FONT_CACHE[cacheKey] = {
-    font = font,
-    lastUsed = love.timer.getTime(),
-    accessCount = 1,
-  }
-  FONT_CACHE_STATS.size = FONT_CACHE_STATS.size + 1
-
-  -- Evict if cache is full
-  if FONT_CACHE_STATS.size > FONT_CACHE_MAX_SIZE then
-    evictLRU()
-  end
-
-  return font
-end
-
--- Get font for text size (cached)
---@param textSize number?
---@param fontPath string?
---@return love.Font
-function FONT_CACHE.getFont(textSize, fontPath)
-  if textSize then
-    return FONT_CACHE.get(textSize, fontPath)
-  else
-    return love.graphics.getFont()
-  end
-end
-
-- Font resolution utilities
-
--- Resolve font path from fontFamily and theme
---@param fontFamily string? Font family name or direct path
---@param themeComponent string? Theme component name
---@param themeManager table? ThemeManager instance
---@return string? Resolved font path or nil
-local function resolveFontPath(fontFamily, themeComponent, themeManager)
-  if fontFamily then
-    -- Check if fontFamily is a theme font name
-    local themeToUse = themeManager and themeManager:getTheme()
-    if themeToUse and themeToUse.fonts and themeToUse.fonts[fontFamily] then
-      return themeToUse.fonts[fontFamily]
-    else
-      -- Treat as direct path to font file
-      return fontFamily
-    end
-  elseif themeComponent and themeManager then
-    -- If using themeComponent but no fontFamily specified, check for default font in theme
-    return themeManager:getDefaultFontFamily()
-  end
-  return nil
-end
-
--- Get font for element (resolves from theme or fontFamily)
---@param textSize number? Text size in pixels
---@param fontFamily string? Font family name or direct path
---@param themeComponent string? Theme component name
---@param themeManager table? ThemeManager instance
---@return love.Font
-local function getFont(textSize, fontFamily, themeComponent, themeManager)
-  local fontPath = resolveFontPath(fontFamily, themeComponent, themeManager)
-  return FONT_CACHE.getFont(textSize, fontPath)
-end
-
-- Font cache management
-
--- Get font cache statistics
---@return table stats {hits, misses, evictions, size, hitRate}
-local function getFontCacheStats()
-  local total = FONT_CACHE_STATS.hits + FONT_CACHE_STATS.misses
-  local hitRate = total > 0 and (FONT_CACHE_STATS.hits / total) or 0
-  return {
-    hits = FONT_CACHE_STATS.hits,
-    misses = FONT_CACHE_STATS.misses,
-    evictions = FONT_CACHE_STATS.evictions,
-    size = FONT_CACHE_STATS.size,
-    hitRate = hitRate,
-  }
-end
-
--- Set maximum font cache size
---@param maxSize number Maximum number of fonts to cache
-local function setFontCacheSize(maxSize)
-  FONT_CACHE_MAX_SIZE = math.max(1, maxSize)
-
-  -- Evict entries if cache is now over limit
-  while FONT_CACHE_STATS.size > FONT_CACHE_MAX_SIZE do
-    evictLRU()
-  end
-end
-
--- Clear font cache
-local function clearFontCache()
-  -- Clear cache entries but preserve methods (get, getFont)
-  for key, entry in pairs(FONT_CACHE) do
-    if type(entry) == "table" and entry.lastUsed then
-      FONT_CACHE[key] = nil
-    end
-  end
-  FONT_CACHE_STATS.size = 0
-  FONT_CACHE_STATS.evictions = 0
-end
-
--- Preload font at multiple sizes
---@param fontPath string? Path to font file (nil for default font)
---@param sizes table Array of font sizes to preload
-local function preloadFont(fontPath, sizes)
-  for _, size in ipairs(sizes) do
-    -- Round size to reduce cache entries
-    size = math.floor(size + 0.5)
-
-    local cacheKey = fontPath and (fontPath .. ":" .. tostring(size)) or ("default:" .. tostring(size))
-
-    if not FONT_CACHE[cacheKey] then
-      local font
-      if fontPath then
-        local resolvedPath = resolveImagePath(fontPath)
-        local success, result = pcall(love.graphics.newFont, resolvedPath, size)
-        if success then
-          font = result
-        else
-          font = love.graphics.newFont(size)
-        end
-      else
-        font = love.graphics.newFont(size)
-      end
-
-      FONT_CACHE[cacheKey] = {
-        font = font,
-        lastUsed = love.timer.getTime(),
-        accessCount = 1,
-      }
-      FONT_CACHE_STATS.size = FONT_CACHE_STATS.size + 1
-      FONT_CACHE_STATS.misses = FONT_CACHE_STATS.misses + 1
-
-      -- Evict if cache is full
-      if FONT_CACHE_STATS.size > FONT_CACHE_MAX_SIZE then
-        evictLRU()
-      end
-    end
-  end
-end
-
--- Reset font cache statistics
-local function resetFontCacheStats()
-  FONT_CACHE_STATS.hits = 0
-  FONT_CACHE_STATS.misses = 0
-  FONT_CACHE_STATS.evictions = 0
-end
-
-return {
-  FONT_CACHE = FONT_CACHE,
-  init = init,
-  resolveFontPath = resolveFontPath,
-  getFont = getFont,
-  getFontCacheStats = getFontCacheStats,
-  setFontCacheSize = setFontCacheSize,
-  clearFontCache = clearFontCache,
-  preloadFont = preloadFont,
-  resetFontCacheStats = resetFontCacheStats,
-}
@@ -1,583 +0,0 @@
---@class GestureRecognizer
---@field _touches table<string, table> -- Current touch states
---@field _gestureStates table -- Active gesture states
---@field _config table -- Gesture configuration (thresholds, etc.)
---@field _InputEvent table
---@field _utils table
-local GestureRecognizer = {}
-GestureRecognizer.__index = GestureRecognizer
-
-- Gesture types enum
-local GestureType = {
-  TAP = "tap",
-  DOUBLE_TAP = "double_tap",
-  LONG_PRESS = "long_press",
-  SWIPE = "swipe",
-  PAN = "pan",
-  PINCH = "pinch",
-  ROTATE = "rotate",
-}
-
-- Gesture states
-local GestureState = {
-  POSSIBLE = "possible",
-  BEGAN = "began",
-  CHANGED = "changed",
-  ENDED = "ended",
-  CANCELLED = "cancelled",
-  FAILED = "failed",
-}
-
-- Default configuration
-local defaultConfig = {
-  -- Tap gesture
-  tapMaxDuration = 0.3, -- seconds
-  tapMaxMovement = 10, -- pixels
-
-  -- Double-tap gesture
-  doubleTapInterval = 0.3, -- seconds between taps
-
-  -- Long-press gesture
-  longPressMinDuration = 0.5, -- seconds
-  longPressMaxMovement = 10, -- pixels
-
-  -- Swipe gesture
-  swipeMinDistance = 50, -- pixels
-  swipeMaxDuration = 0.2, -- seconds
-  swipeMinVelocity = 200, -- pixels per second
-
-  -- Pan gesture
-  panMinMovement = 5, -- pixels to start pan
-
-  -- Pinch gesture
-  pinchMinScaleChange = 0.1, -- 10% scale change
-
-  -- Rotate gesture
-  rotateMinAngleChange = 5, -- degrees
-}
-
--- Create a new GestureRecognizer instance
---@param config table? Optional configuration options
---@param deps table Dependencies {InputEvent, utils}
---@return GestureRecognizer
-function GestureRecognizer.new(config, deps)
-  config = config or {}
-
-  local self = setmetatable({}, GestureRecognizer)
-
-  self._InputEvent = deps.InputEvent
-  self._utils = deps.utils
-
-  -- Merge configuration with defaults
-  self._config = {}
-  for key, value in pairs(defaultConfig) do
-    self._config[key] = config[key] or value
-  end
-
-  self._touches = {}
-  self._gestureStates = {
-    tap = nil,
-    doubleTap = { lastTapTime = 0, tapCount = 0 },
-    longPress = {},
-    swipe = {},
-    pan = {},
-    pinch = {},
-    rotate = {},
-  }
-
-  return self
-end
-
--- Update gesture recognizer with touch event
---@param event InputEvent Touch event
-function GestureRecognizer:processTouchEvent(event)
-  if not event.touchId then
-    return nil
-  end
-
-  local touchId = event.touchId
-  local gestures = {}
-
-  -- Update touch state
-  if event.type == "touchpress" then
-    self._touches[touchId] = {
-      startX = event.x,
-      startY = event.y,
-      x = event.x,
-      y = event.y,
-      startTime = event.timestamp,
-      lastTime = event.timestamp,
-      phase = "began",
-    }
-
-    -- Initialize gesture detection
-    self:_detectTapBegan(touchId, event)
-    self:_detectLongPressBegan(touchId, event)
-  elseif event.type == "touchmove" then
-    local touch = self._touches[touchId]
-    if touch then
-      touch.x = event.x
-      touch.y = event.y
-      touch.lastTime = event.timestamp
-      touch.phase = "moved"
-
-      -- Update gesture detection
-      local panGesture = self:_detectPan(touchId, event)
-      if panGesture then
-        table.insert(gestures, panGesture)
-      end
-      local swipeGesture = self:_detectSwipe(touchId, event)
-      if swipeGesture then
-        table.insert(gestures, swipeGesture)
-      end
-
-      -- Multi-touch gestures
-      if self:_getTouchCount() >= 2 then
-        local pinchGesture = self:_detectPinch(event)
-        if pinchGesture then
-          table.insert(gestures, pinchGesture)
-        end
-        local rotateGesture = self:_detectRotate(event)
-        if rotateGesture then
-          table.insert(gestures, rotateGesture)
-        end
-      end
-    end
-  elseif event.type == "touchrelease" then
-    local touch = self._touches[touchId]
-    if touch then
-      touch.phase = "ended"
-
-      -- Finalize gesture detection
-      local tapGesture = self:_detectTapEnded(touchId, event)
-      if tapGesture then
-        table.insert(gestures, tapGesture)
-      end
-      local swipeGesture = self:_detectSwipeEnded(touchId, event)
-      if swipeGesture then
-        table.insert(gestures, swipeGesture)
-      end
-      local panGesture = self:_detectPanEnded(touchId, event)
-      if panGesture then
-        table.insert(gestures, panGesture)
-      end
-
-      -- Cleanup touch
-      self._touches[touchId] = nil
-    end
-  elseif event.type == "touchcancel" then
-    -- Cancel all active gestures for this touch
-    self._touches[touchId] = nil
-    self:_cancelAllGestures()
-  end
-
-  return #gestures > 0 and gestures or nil
-end
-
--- Get number of active touches
---@return number
-function GestureRecognizer:_getTouchCount()
-  local count = 0
-  for _ in pairs(self._touches) do
-    count = count + 1
-  end
-  return count
-end
-
--- Detect tap gesture began
---@param touchId string
---@param event InputEvent
-function GestureRecognizer:_detectTapBegan(touchId, event)
-  -- Tap detection happens on touch end
-  -- Just record the touch for now
-end
-
--- Detect tap gesture ended
---@param touchId string
---@param event InputEvent
-function GestureRecognizer:_detectTapEnded(touchId, event)
-  local touch = self._touches[touchId]
-  if not touch then
-    return
-  end
-
-  local duration = event.timestamp - touch.startTime
-  local dx = event.x - touch.startX
-  local dy = event.y - touch.startY
-  local distance = math.sqrt(dx * dx + dy * dy)
-
-  -- Check if it's a valid tap
-  if duration < self._config.tapMaxDuration and distance < self._config.tapMaxMovement then
-    local currentTime = event.timestamp
-    local doubleTapState = self._gestureStates.doubleTap
-
-    -- Check for double-tap
-    if currentTime - doubleTapState.lastTapTime < self._config.doubleTapInterval then
-      doubleTapState.tapCount = doubleTapState.tapCount + 1
-
-      if doubleTapState.tapCount >= 2 then
-        -- Fire double-tap gesture
-        return {
-          type = GestureType.DOUBLE_TAP,
-          state = GestureState.ENDED,
-          x = event.x,
-          y = event.y,
-          timestamp = event.timestamp,
-        }
-      end
-    else
-      doubleTapState.tapCount = 1
-    end
-
-    doubleTapState.lastTapTime = currentTime
-
-    -- Fire tap gesture
-    return {
-      type = GestureType.TAP,
-      state = GestureState.ENDED,
-      x = event.x,
-      y = event.y,
-      timestamp = event.timestamp,
-    }
-  end
-end
-
--- Detect long-press gesture began
---@param touchId string
---@param event InputEvent
-function GestureRecognizer:_detectLongPressBegan(touchId, event)
-  -- Long-press detection happens continuously during touch
-  self._gestureStates.longPress[touchId] = {
-    startX = event.x,
-    startY = event.y,
-    startTime = event.timestamp,
-    triggered = false,
-  }
-end
-
--- Detect pan gesture
---@param touchId string
---@param event InputEvent
---@return table? Gesture event
-function GestureRecognizer:_detectPan(touchId, event)
-  local touch = self._touches[touchId]
-  if not touch then
-    return nil
-  end
-
-  local dx = event.x - touch.startX
-  local dy = event.y - touch.startY
-  local distance = math.sqrt(dx * dx + dy * dy)
-
-  local panState = self._gestureStates.pan[touchId]
-
-  if not panState then
-    -- Check if pan should begin
-    if distance >= self._config.panMinMovement then
-      self._gestureStates.pan[touchId] = {
-        active = true,
-        lastX = touch.startX,
-        lastY = touch.startY,
-      }
-      panState = self._gestureStates.pan[touchId]
-
-      return {
-        type = GestureType.PAN,
-        state = GestureState.BEGAN,
-        x = event.x,
-        y = event.y,
-        dx = dx,
-        dy = dy,
-        timestamp = event.timestamp,
-      }
-    end
-  else
-    -- Pan is active, fire changed event
-    local panDx = event.x - panState.lastX
-    local panDy = event.y - panState.lastY
-
-    panState.lastX = event.x
-    panState.lastY = event.y
-
-    return {
-      type = GestureType.PAN,
-      state = GestureState.CHANGED,
-      x = event.x,
-      y = event.y,
-      dx = panDx,
-      dy = panDy,
-      totalDx = dx,
-      totalDy = dy,
-      timestamp = event.timestamp,
-    }
-  end
-
-  return nil
-end
-
--- Detect pan ended
---@param touchId string
---@param event InputEvent
---@return table? Gesture event
-function GestureRecognizer:_detectPanEnded(touchId, event)
-  local panState = self._gestureStates.pan[touchId]
-  if panState and panState.active then
-    self._gestureStates.pan[touchId] = nil
-
-    local touch = self._touches[touchId]
-    local dx = event.x - touch.startX
-    local dy = event.y - touch.startY
-
-    return {
-      type = GestureType.PAN,
-      state = GestureState.ENDED,
-      x = event.x,
-      y = event.y,
-      dx = dx,
-      dy = dy,
-      timestamp = event.timestamp,
-    }
-  end
-
-  return nil
-end
-
--- Detect swipe gesture
---@param touchId string
---@param event InputEvent
-function GestureRecognizer:_detectSwipe(touchId, event)
-  -- Swipe detection happens on touch end
-end
-
--- Detect swipe ended
---@param touchId string
---@param event InputEvent
---@return table? Gesture event
-function GestureRecognizer:_detectSwipeEnded(touchId, event)
-  local touch = self._touches[touchId]
-  if not touch then
-    return nil
-  end
-
-  local duration = event.timestamp - touch.startTime
-  local dx = event.x - touch.startX
-  local dy = event.y - touch.startY
-  local distance = math.sqrt(dx * dx + dy * dy)
-
-  -- Check if it's a valid swipe
-  if distance >= self._config.swipeMinDistance and duration <= self._config.swipeMaxDuration then
-    local velocity = distance / duration
-
-    if velocity >= self._config.swipeMinVelocity then
-      -- Determine swipe direction
-      local angle = math.atan2(dy, dx)
-      local direction = "right"
-
-      if angle >= -math.pi / 4 and angle < math.pi / 4 then
-        direction = "right"
-      elseif angle >= math.pi / 4 and angle < 3 * math.pi / 4 then
-        direction = "down"
-      elseif angle >= -3 * math.pi / 4 and angle < -math.pi / 4 then
-        direction = "up"
-      else
-        direction = "left"
-      end
-
-      return {
-        type = GestureType.SWIPE,
-        state = GestureState.ENDED,
-        x = event.x,
-        y = event.y,
-        dx = dx,
-        dy = dy,
-        direction = direction,
-        velocity = velocity,
-        timestamp = event.timestamp,
-      }
-    end
-  end
-
-  return nil
-end
-
--- Detect pinch gesture
---@param event InputEvent
---@return table? Gesture event
-function GestureRecognizer:_detectPinch(event)
-  -- Get two touches for pinch
-  local touches = {}
-  for touchId, touch in pairs(self._touches) do
-    table.insert(touches, { id = touchId, touch = touch })
-    if #touches >= 2 then
-      break
-    end
-  end
-
-  if #touches < 2 then
-    return nil
-  end
-
-  local t1 = touches[1].touch
-  local t2 = touches[2].touch
-
-  -- Calculate current distance
-  local currentDx = t2.x - t1.x
-  local currentDy = t2.y - t1.y
-  local currentDistance = math.sqrt(currentDx * currentDx + currentDy * currentDy)
-
-  -- Calculate initial distance
-  local initialDx = t2.startX - t1.startX
-  local initialDy = t2.startY - t1.startY
-  local initialDistance = math.sqrt(initialDx * initialDx + initialDy * initialDy)
-
-  if initialDistance == 0 then
-    return nil
-  end
-
-  -- Calculate scale
-  local scale = currentDistance / initialDistance
-  local pinchState = self._gestureStates.pinch
-
-  if not pinchState.active then
-    -- Check if pinch should begin
-    if math.abs(scale - 1.0) >= self._config.pinchMinScaleChange then
-      pinchState.active = true
-      pinchState.initialScale = scale
-      pinchState.lastScale = scale
-
-      -- Calculate center point
-      local centerX = (t1.x + t2.x) / 2
-      local centerY = (t1.y + t2.y) / 2
-
-      return {
-        type = GestureType.PINCH,
-        state = GestureState.BEGAN,
-        scale = scale,
-        centerX = centerX,
-        centerY = centerY,
-        timestamp = event.timestamp,
-      }
-    end
-  else
-    -- Pinch is active, fire changed event
-    local centerX = (t1.x + t2.x) / 2
-    local centerY = (t1.y + t2.y) / 2
-
-    local scaleChange = scale - pinchState.lastScale
-    pinchState.lastScale = scale
-
-    return {
-      type = GestureType.PINCH,
-      state = GestureState.CHANGED,
-      scale = scale,
-      scaleChange = scaleChange,
-      centerX = centerX,
-      centerY = centerY,
-      timestamp = event.timestamp,
-    }
-  end
-
-  return nil
-end
-
--- Detect rotate gesture
---@param event InputEvent
---@return table? Gesture event
-function GestureRecognizer:_detectRotate(event)
-  -- Get two touches for rotation
-  local touches = {}
-  for touchId, touch in pairs(self._touches) do
-    table.insert(touches, { id = touchId, touch = touch })
-    if #touches >= 2 then
-      break
-    end
-  end
-
-  if #touches < 2 then
-    return nil
-  end
-
-  local t1 = touches[1].touch
-  local t2 = touches[2].touch
-
-  -- Calculate current angle
-  local currentAngle = math.atan2(t2.y - t1.y, t2.x - t1.x)
-
-  -- Calculate initial angle
-  local initialAngle = math.atan2(t2.startY - t1.startY, t2.startX - t1.startX)
-
-  -- Calculate rotation (in degrees)
-  local rotation = (currentAngle - initialAngle) * 180 / math.pi
-
-  local rotateState = self._gestureStates.rotate
-
-  if not rotateState.active then
-    -- Check if rotation should begin
-    if math.abs(rotation) >= self._config.rotateMinAngleChange then
-      rotateState.active = true
-      rotateState.initialRotation = rotation
-      rotateState.lastRotation = rotation
-
-      -- Calculate center point
-      local centerX = (t1.x + t2.x) / 2
-      local centerY = (t1.y + t2.y) / 2
-
-      return {
-        type = GestureType.ROTATE,
-        state = GestureState.BEGAN,
-        rotation = rotation,
-        centerX = centerX,
-        centerY = centerY,
-        timestamp = event.timestamp,
-      }
-    end
-  else
-    -- Rotation is active, fire changed event
-    local centerX = (t1.x + t2.x) / 2
-    local centerY = (t1.y + t2.y) / 2
-
-    local rotationChange = rotation - rotateState.lastRotation
-    rotateState.lastRotation = rotation
-
-    return {
-      type = GestureType.ROTATE,
-      state = GestureState.CHANGED,
-      rotation = rotation,
-      rotationChange = rotationChange,
-      centerX = centerX,
-      centerY = centerY,
-      timestamp = event.timestamp,
-    }
-  end
-
-  return nil
-end
-
--- Cancel all active gestures
-function GestureRecognizer:_cancelAllGestures()
-  for gestureType, state in pairs(self._gestureStates) do
-    if type(state) == "table" and state.active then
-      state.active = false
-    end
-  end
-end
-
--- Reset gesture recognizer state
-function GestureRecognizer:reset()
-  self._touches = {}
-  self._gestureStates = {
-    tap = nil,
-    doubleTap = { lastTapTime = 0, tapCount = 0 },
-    longPress = {},
-    swipe = {},
-    pan = {},
-    pinch = { active = false },
-    rotate = { active = false },
-  }
-end
-
-- Export gesture types and states
-GestureRecognizer.GestureType = GestureType
-GestureRecognizer.GestureState = GestureState
-
-return GestureRecognizer
@@ -1,336 +0,0 @@
-local modulePath = (...):match("(.-)[^%.]+$")
-local utils = require(modulePath .. "utils")
-local enums = utils.enums
-local Units = require(modulePath .. "Units")
-
-local Positioning = enums.Positioning
-local AlignItems = enums.AlignItems
-
--- Grid layout with variable column widths / row heights
--- Supports px, %, fr, auto, vw, vh, and calc track sizes
-local Grid = {}
-
--- Parse a single track spec into {type, value}
--- Uses the Units pipeline for standard CSS units (px, %, vw, vh, calc).
--- Grid-specific types (fr, auto) are handled directly.
---@param spec number|string Track specification: number (px), string ("100px", "50%", "10vw", "1fr", "auto")
---@param availableSize number Container size for % resolution
---@param viewportWidth number Viewport width for vw resolution
---@param viewportHeight number Viewport height for vh resolution
---@return table {type: "px"|"fr"|"auto", value: number}
-function Grid._parseTrack(spec, availableSize, viewportWidth, viewportHeight)
-  -- Handle calc objects (tables with _isCalc flag from FlexLove.calc())
-  if type(spec) == "table" then
-    local resolved = Units.resolve(spec, "calc", viewportWidth, viewportHeight, availableSize)
-    return { type = "px", value = resolved }
-  end
-
-  if type(spec) == "number" then
-    return { type = "px", value = spec }
-  end
-
-  if type(spec) == "string" then
-    if spec == "auto" then
-      return { type = "auto", value = 0 }
-    end
-
-    -- Check for fr unit (grid-specific, not in Units pipeline)
-    local numStr, unit = spec:match("^([%-]?[%d%.]+)(.*)$")
-    if numStr and unit == "fr" then
-      local num = tonumber(numStr)
-      if num then
-        return { type = "fr", value = num }
-      end
-    end
-
-    -- Delegate all other units to the Units pipeline (px, %, vw, vh, calc)
-    local parsedVal, parsedUnit = Units.parse(spec)
-    local resolved = Units.resolve(parsedVal, parsedUnit, viewportWidth, viewportHeight, availableSize)
-    return { type = "px", value = resolved }
-  end
-
-  -- Default: 1fr
-  return { type = "fr", value = 1 }
-end
-
--- Build track list from gridColumns/gridRows or fall back to equal 1fr tracks
---@param spec number|table? Track count (number = equal 1fr tracks) or array of track specs (e.g., {"1fr", "2fr", "100px"})
---@param availableSize number Container size for % resolution
---@param viewportWidth number Viewport width for vw resolution
---@param viewportHeight number Viewport height for vh resolution
---@return table Array of {type, value} track descriptors
-function Grid._buildTracks(spec, availableSize, viewportWidth, viewportHeight)
-  if type(spec) == "table" and #spec > 0 then
-    local tracks = {}
-    for i, s in ipairs(spec) do
-      tracks[i] = Grid._parseTrack(s, availableSize, viewportWidth, viewportHeight)
-    end
-    return tracks
-  end
-  -- Fallback: equal 1fr tracks
-  local count = (type(spec) == "number" and spec > 0) and spec or 1
-  local tracks = {}
-  for i = 1, count do
-    tracks[i] = { type = "fr", value = 1 }
-  end
-  return tracks
-end
-
--- Measure intrinsic content sizes for auto tracks
--- Maps children to their tracks and computes each child's max-content contribution.
--- For children with explicit dimensions (units unit ~= "auto"), uses the original
--- explicit size. For auto-sized children, uses calculated content size.
--- Stores the max per auto track. Matches CSS Grid auto sizing where tracks size
--- to the max-content contribution of their grid items.
---@param tracks table Array of {type, value} track descriptors
---@param children table Array of grid child elements
---@param axis "width"|"height" Dimension axis to measure
-function Grid._measureAutoTracks(tracks, children, axis)
-  local trackSizes = {}
-  local numTracks = #tracks
-
-  for i, child in ipairs(children) do
-    local index = i - 1
-    local trackIdx = (index % numTracks) + 1
-
-    local intrinsicSize
-    if axis == "width" then
-      local unit = child.units and child.units.width and child.units.width.unit
-      if unit and unit ~= "auto" then
-        -- Explicit width: use original value + padding (not stretched border-box)
-        intrinsicSize = (child.units.width.value or 0) + child.padding.left + child.padding.right
-      else
-        -- Auto-sized: use calculated content size
-        intrinsicSize = child:calculateAutoWidth()
-      end
-    else
-      local unit = child.units and child.units.height and child.units.height.unit
-      if unit and unit ~= "auto" then
-        intrinsicSize = (child.units.height.value or 0) + child.padding.top + child.padding.bottom
-      else
-        intrinsicSize = child:calculateAutoHeight()
-      end
-    end
-
-    if intrinsicSize > 0 then
-      trackSizes[trackIdx] = math.max(trackSizes[trackIdx] or 0, intrinsicSize)
-    end
-  end
-
-  -- Apply measured sizes to auto tracks
-  for i, track in ipairs(tracks) do
-    if track.type == "auto" and trackSizes[i] then
-      track.value = trackSizes[i]
-    end
-  end
-end
-
--- Resolve track sizes: auto (content) first, then px (fixed), then fr (remaining)
--- CSS Grid algorithm:
--- 1. auto tracks size to their content (max-content) — measured by _measureAutoTracks
--- 2. px tracks consume their fixed size
--- 3. fr tracks consume remaining free space proportionally
--- 4. If no fr tracks exist, auto tracks share remaining space equally
--- Mutates tracks in-place, converting all to {type="px", value=number}
---@param tracks table Array of {type, value} track descriptors
---@param availableSize number Total space available for tracks
---@param gap number Gap between tracks
-function Grid._resolveTracks(tracks, availableSize, gap)
-  local count = #tracks
-  local totalGaps = (count > 1 and (count - 1) * gap) or 0
-  local remaining = math.max(0, availableSize - totalGaps)
-
-  -- Pass 1: Treat auto tracks as fixed (content-measured) and subtract
-  for _, track in ipairs(tracks) do
-    if track.type == "px" then
-      remaining = remaining - track.value
-    elseif track.type == "auto" then
-      remaining = remaining - math.max(0, track.value)
-    end
-  end
-
-  remaining = math.max(0, remaining)
-
-  -- Pass 2: Count fr shares
-  local totalFr = 0
-  local autoCount = 0
-  for _, track in ipairs(tracks) do
-    if track.type == "fr" then
-      totalFr = totalFr + track.value
-    elseif track.type == "auto" then
-      autoCount = autoCount + 1
-    end
-  end
-
-  -- Pass 3: Distribute remaining space
-  if totalFr > 0 then
-    -- fr tracks consume all remaining free space
-    local frUnit = remaining / totalFr
-    for _, track in ipairs(tracks) do
-      if track.type == "fr" then
-        track.value = frUnit * track.value
-        track.type = "px"
-      end
-    end
-  elseif autoCount > 0 then
-    -- No fr tracks: auto tracks share remaining space equally (grow beyond content)
-    local extraPerAuto = math.max(0, remaining) / autoCount
-    for _, track in ipairs(tracks) do
-      if track.type == "auto" then
-        track.value = track.value + extraPerAuto
-        track.type = "px"
-      end
-    end
-  end
-end
-
--- Layout grid items within a grid container
--- Supports variable column widths and row heights via gridColumns/gridRows (number or track specs)
--- Falls back to equal-sized 1fr tracks when nil
---@param element Element -- Grid container element
-function Grid.layoutGridItems(element)
-  -- Calculate space reserved by absolutely positioned siblings
-  local reservedLeft = 0
-  local reservedRight = 0
-  local reservedTop = 0
-  local reservedBottom = 0
-
-  for _, child in ipairs(element.children) do
-    -- Only consider absolutely positioned children with explicit positioning and display != false
-    if child.positioning == Positioning.ABSOLUTE and child._explicitlyAbsolute and child.display ~= false then
-      -- BORDER-BOX MODEL: Use border-box dimensions for space calculations
-      local childBorderBoxWidth = child:getBorderBoxWidth()
-      local childBorderBoxHeight = child:getBorderBoxHeight()
-
-      if child.left then
-        reservedLeft = math.max(reservedLeft, child.left + childBorderBoxWidth)
-      end
-      if child.right then
-        reservedRight = math.max(reservedRight, child.right + childBorderBoxWidth)
-      end
-      if child.top then
-        reservedTop = math.max(reservedTop, child.top + childBorderBoxHeight)
-      end
-      if child.bottom then
-        reservedBottom = math.max(reservedBottom, child.bottom + childBorderBoxHeight)
-      end
-    end
-  end
-
-  -- Calculate available space (accounting for padding and reserved space)
-  -- BORDER-BOX MODEL: element.width and element.height are already content dimensions
-  local availableWidth = math.max(0, element.width - reservedLeft - reservedRight)
-  local availableHeight = math.max(0, element.height - reservedTop - reservedBottom)
-
-  -- Get gaps
-  local columnGap = element.columnGap or 0
-  local rowGap = element.rowGap or 0
-
-  -- Collect grid children (exclude explicitly absolute and display=false)
-  local gridChildren = {}
-  for _, child in ipairs(element.children) do
-    if not (child.positioning == Positioning.ABSOLUTE and child._explicitlyAbsolute) and child.display ~= false then
-      table.insert(gridChildren, child)
-    end
-  end
-
-  -- Get viewport dimensions for unit resolution (vw, vh, %)
-  local vpw, vph = Units.getViewport()
-
-  -- Build tracks, measure auto tracks by content, then resolve sizes
-  local colTracks = Grid._buildTracks(element.gridColumns, availableWidth, vpw, vph)
-  local rowTracks = Grid._buildTracks(element.gridRows, availableHeight, vpw, vph)
-
-  Grid._measureAutoTracks(colTracks, gridChildren, "width")
-  Grid._measureAutoTracks(rowTracks, gridChildren, "height")
-
-  Grid._resolveTracks(colTracks, availableWidth, columnGap)
-  Grid._resolveTracks(rowTracks, availableHeight, rowGap)
-
-  -- Compute column start positions (for positioning)
-  local colStarts = {}
-  local currentX = element.x + element.padding.left + reservedLeft
-  for col = 1, #colTracks do
-    colStarts[col] = currentX
-    currentX = currentX + colTracks[col].value + columnGap
-  end
-
-  local rowStarts = {}
-  local currentY = element.y + element.padding.top + reservedTop
-  for row = 1, #rowTracks do
-    rowStarts[row] = currentY
-    currentY = currentY + rowTracks[row].value + rowGap
-  end
-
-  local effectiveAlignItems = element.alignItems or AlignItems.STRETCH
-
-  for i, child in ipairs(gridChildren) do
-    -- Calculate row and column (0-indexed for calculation)
-    local index = i - 1
-    local col = index % #colTracks
-    local row = math.floor(index / #colTracks)
-
-    if row >= #rowTracks then
-      break
-    end
-
-    -- Get resolved cell position and size
-    local colIdx = col + 1
-    local rowIdx = row + 1
-    local cellX = colStarts[colIdx]
-    local cellY = rowStarts[rowIdx]
-    local cellWidth = colTracks[colIdx].value
-    local cellHeight = rowTracks[rowIdx].value
-
-    -- Apply alignment within grid cell (default to stretch)
-    -- BORDER-BOX MODEL: Set border-box dimensions, content area adjusts automatically
-    if effectiveAlignItems == AlignItems.STRETCH or effectiveAlignItems == "stretch" then
-      child.x = cellX
-      child.y = cellY
-      child._borderBoxWidth = cellWidth
-      child._borderBoxHeight = cellHeight
-      child.width = math.max(0, cellWidth - child.padding.left - child.padding.right)
-      child.height = math.max(0, cellHeight - child.padding.top - child.padding.bottom)
-      -- Disable auto-sizing when stretched by grid
-      child.autosizing.width = false
-      child.autosizing.height = false
-    elseif effectiveAlignItems == AlignItems.CENTER or effectiveAlignItems == "center" then
-      local childBorderBoxWidth = child:getBorderBoxWidth()
-      local childBorderBoxHeight = child:getBorderBoxHeight()
-      child.x = cellX + (cellWidth - childBorderBoxWidth) / 2
-      child.y = cellY + (cellHeight - childBorderBoxHeight) / 2
-    elseif
-      effectiveAlignItems == AlignItems.FLEX_START
-      or effectiveAlignItems == "flex-start"
-      or effectiveAlignItems == "start"
-    then
-      child.x = cellX
-      child.y = cellY
-    elseif
-      effectiveAlignItems == AlignItems.FLEX_END
-      or effectiveAlignItems == "flex-end"
-      or effectiveAlignItems == "end"
-    then
-      local childBorderBoxWidth = child:getBorderBoxWidth()
-      local childBorderBoxHeight = child:getBorderBoxHeight()
-      child.x = cellX + cellWidth - childBorderBoxWidth
-      child.y = cellY + cellHeight - childBorderBoxHeight
-    else
-      child.x = cellX
-      child.y = cellY
-      child._borderBoxWidth = cellWidth
-      child._borderBoxHeight = cellHeight
-      child.width = math.max(0, cellWidth - child.padding.left - child.padding.right)
-      child.height = math.max(0, cellHeight - child.padding.top - child.padding.bottom)
-      -- Disable auto-sizing when stretched by grid
-      child.autosizing.width = false
-      child.autosizing.height = false
-    end
-
-    if #child.children > 0 then
-      child:layoutChildren()
-    end
-  end
-end
-
-return Grid
@@ -1,160 +0,0 @@
-local modulePath = (...):match("(.-)[^%.]+$")
-local function req(name)
-  return require(modulePath .. name)
-end
-
-local utils = req("utils")
-
-- ErrorHandler will be injected via init
-local ErrorHandler = nil
-
---@class ImageCache
---@field _cache table<string, {image: love.Image, imageData: love.ImageData?}>
-local ImageCache = {}
-ImageCache._cache = {}
-
--- Initialize ImageCache with dependencies
---@param deps table Dependencies table with ErrorHandler
-function ImageCache.init(deps)
-  if deps and deps.ErrorHandler then
-    ErrorHandler = deps.ErrorHandler
-  end
-end
-
--- Load an image from file path with caching
--- Returns cached image if already loaded, otherwise loads and caches it
---@param imagePath string -- Path to image file
---@param loadImageData boolean? -- Optional: also load ImageData for pixel access (default: false)
---@return love.Image|nil -- Image object or nil on error
---@return string|nil -- Error message if loading failed
-function ImageCache.load(imagePath, loadImageData)
-  if not imagePath or type(imagePath) ~= "string" or imagePath == "" then
-    return nil, "Invalid image path: path must be a non-empty string"
-  end
-
-  local normalizedPath = utils.normalizePath(imagePath)
-
-  if ImageCache._cache[normalizedPath] then
-    return ImageCache._cache[normalizedPath].image, nil
-  end
-
-  local success, imageOrError = pcall(love.graphics.newImage, normalizedPath)
-  if not success then
-    if ErrorHandler then
-      ErrorHandler:warn("ImageCache", "RES_004", {
-        resourceType = "image",
-        path = imagePath,
-        error = tostring(imageOrError),
-      })
-    end
-    return nil, string.format("Failed to load image '%s': %s", imagePath, tostring(imageOrError))
-  end
-
-  local image = imageOrError
-  local imgData = nil
-
-  if loadImageData then
-    local dataSuccess, dataOrError = pcall(love.image.newImageData, normalizedPath)
-    if dataSuccess then
-      imgData = dataOrError
-    elseif ErrorHandler then
-      ErrorHandler:warn("ImageCache", "RES_004", {
-        resourceType = "image data",
-        path = imagePath,
-        error = tostring(dataOrError),
-      })
-    end
-  end
-
-  ImageCache._cache[normalizedPath] = {
-    image = image,
-    imageData = imgData,
-  }
-
-  return image, nil
-end
-
--- Get a cached image without loading
---@param imagePath string -- Path to image file
---@return love.Image|nil -- Cached image or nil if not found
-function ImageCache.get(imagePath)
-  if not imagePath or type(imagePath) ~= "string" then
-    return nil
-  end
-
-  local normalizedPath = utils.normalizePath(imagePath)
-  local cached = ImageCache._cache[normalizedPath]
-  return cached and cached.image or nil
-end
-
--- Get cached ImageData for an image
---@param imagePath string -- Path to image file
---@return love.ImageData|nil -- Cached ImageData or nil if not found
-function ImageCache.getImageData(imagePath)
-  if not imagePath or type(imagePath) ~= "string" then
-    return nil
-  end
-
-  local normalizedPath = utils.normalizePath(imagePath)
-  local cached = ImageCache._cache[normalizedPath]
-  return cached and cached.imageData or nil
-end
-
--- Remove a specific image from cache
---@param imagePath string -- Path to image file to remove
---@return boolean -- True if image was removed, false if not found
-function ImageCache.remove(imagePath)
-  if not imagePath or type(imagePath) ~= "string" then
-    return false
-  end
-
-  local normalizedPath = utils.normalizePath(imagePath)
-  if ImageCache._cache[normalizedPath] then
-    local cached = ImageCache._cache[normalizedPath]
-    if cached.image then
-      cached.image:release()
-    end
-    if cached.imageData then
-      cached.imageData:release()
-    end
-    ImageCache._cache[normalizedPath] = nil
-    return true
-  end
-  return false
-end
-
--- Clear all cached images
-function ImageCache.clear()
-  for path, cached in pairs(ImageCache._cache) do
-    if cached.image then
-      cached.image:release()
-    end
-    if cached.imageData then
-      cached.imageData:release()
-    end
-  end
-  ImageCache._cache = {}
-end
-
--- Get cache statistics
---@return {count: number, memoryEstimate: number} -- Cache stats
-function ImageCache.getStats()
-  local count = 0
-  local memoryEstimate = 0
-
-  for path, cached in pairs(ImageCache._cache) do
-    count = count + 1
-    if cached.image then
-      local w, h = cached.image:getDimensions()
-      -- Estimate: 4 bytes per pixel (RGBA)
-      memoryEstimate = memoryEstimate + (w * h * 4)
-    end
-  end
-
-  return {
-    count = count,
-    memoryEstimate = memoryEstimate,
-  }
-end
-
-return ImageCache
@@ -1,380 +0,0 @@
---@class ImageRenderer
-local ImageRenderer = {}
-
-- ErrorHandler and utils will be injected via init
-local ErrorHandler = nil
-local utils = nil
-
--- Initialize ImageRenderer with dependencies
---@param deps table Dependencies table with ErrorHandler and utils
-function ImageRenderer.init(deps)
-  if deps and deps.ErrorHandler then
-    ErrorHandler = deps.ErrorHandler
-  end
-  if deps and deps.utils then
-    utils = deps.utils
-  end
-end
-
--- Calculate rendering parameters for object-fit modes
--- Returns source and destination rectangles for rendering
---@param imageWidth number -- Natural width of the image
---@param imageHeight number -- Natural height of the image
---@param boundsWidth number -- Width of the bounds to fit within
---@param boundsHeight number -- Height of the bounds to fit within
---@param fitMode string? -- One of: "fill", "contain", "cover", "scale-down", "none" (default: "fill")
---@param objectPosition string? -- Position like "center center", "top left", "50% 50%" (default: "center center")
---@return {sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number, scaleX: number, scaleY: number}
-function ImageRenderer.calculateFit(imageWidth, imageHeight, boundsWidth, boundsHeight, fitMode, objectPosition)
-  fitMode = fitMode or "fill"
-  objectPosition = objectPosition or "center center"
-
-  if imageWidth <= 0 or imageHeight <= 0 or boundsWidth <= 0 or boundsHeight <= 0 then
-    ErrorHandler:error("ImageRenderer", "VAL_002", {
-      imageWidth = imageWidth,
-      imageHeight = imageHeight,
-      boundsWidth = boundsWidth,
-      boundsHeight = boundsHeight,
-    })
-  end
-
-  local result = {
-    sx = 0, -- Source X
-    sy = 0, -- Source Y
-    sw = imageWidth, -- Source width
-    sh = imageHeight, -- Source height
-    dx = 0, -- Destination X
-    dy = 0, -- Destination Y
-    dw = boundsWidth, -- Destination width
-    dh = boundsHeight, -- Destination height
-    scaleX = 1, -- Scale factor X
-    scaleY = 1, -- Scale factor Y
-  }
-
-  if fitMode == "fill" then
-    -- Stretch to fill bounds (may distort)
-    result.scaleX = boundsWidth / imageWidth
-    result.scaleY = boundsHeight / imageHeight
-    result.dw = boundsWidth
-    result.dh = boundsHeight
-  elseif fitMode == "contain" then
-    -- Scale to fit within bounds (preserves aspect ratio)
-    local scale = math.min(boundsWidth / imageWidth, boundsHeight / imageHeight)
-    result.scaleX = scale
-    result.scaleY = scale
-    result.dw = imageWidth * scale
-    result.dh = imageHeight * scale
-
-    -- Apply object-position for letterbox alignment
-    local posX, posY = ImageRenderer._parsePosition(objectPosition)
-    result.dx = (boundsWidth - result.dw) * posX
-    result.dy = (boundsHeight - result.dh) * posY
-  elseif fitMode == "cover" then
-    -- Scale to cover bounds (preserves aspect ratio, may crop)
-    local scale = math.max(boundsWidth / imageWidth, boundsHeight / imageHeight)
-    result.scaleX = scale
-    result.scaleY = scale
-
-    local scaledWidth = imageWidth * scale
-    local scaledHeight = imageHeight * scale
-
-    -- Apply object-position for crop alignment
-    local posX, posY = ImageRenderer._parsePosition(objectPosition)
-
-    -- Calculate which part of the scaled image to show
-    local cropX = (scaledWidth - boundsWidth) * posX
-    local cropY = (scaledHeight - boundsHeight) * posY
-
-    -- Convert back to source coordinates
-    result.sx = cropX / scale
-    result.sy = cropY / scale
-    result.sw = boundsWidth / scale
-    result.sh = boundsHeight / scale
-
-    result.dx = 0
-    result.dy = 0
-    result.dw = boundsWidth
-    result.dh = boundsHeight
-  elseif fitMode == "none" then
-    -- Use natural size (no scaling)
-    result.scaleX = 1
-    result.scaleY = 1
-    result.dw = imageWidth
-    result.dh = imageHeight
-
-    -- Apply object-position
-    local posX, posY = ImageRenderer._parsePosition(objectPosition)
-    result.dx = (boundsWidth - imageWidth) * posX
-    result.dy = (boundsHeight - imageHeight) * posY
-  elseif fitMode == "scale-down" then
-    -- Use none or contain, whichever is smaller
-    if imageWidth <= boundsWidth and imageHeight <= boundsHeight then
-      -- Image fits naturally, use "none"
-      return ImageRenderer.calculateFit(imageWidth, imageHeight, boundsWidth, boundsHeight, "none", objectPosition)
-    else
-      -- Image too large, use "contain"
-      return ImageRenderer.calculateFit(imageWidth, imageHeight, boundsWidth, boundsHeight, "contain", objectPosition)
-    end
-  else
-    ErrorHandler:warn("ImageRenderer", "VAL_007", {
-      fitMode = fitMode,
-      fallback = "fill",
-    })
-    -- Use 'fill' as fallback
-    return ImageRenderer.calculateFit(imageWidth, imageHeight, boundsWidth, boundsHeight, "fill", objectPosition)
-  end
-
-  return result
-end
-
--- Parse object-position string into normalized coordinates (0-1)
--- Supports keywords (center, top, bottom, left, right) and percentages
---@param position string -- Position string like "center center", "top left", "50% 50%"
---@return number, number -- Normalized X and Y positions (0-1)
-function ImageRenderer._parsePosition(position)
-  if not position or type(position) ~= "string" then
-    return 0.5, 0.5 -- Default to center
-  end
-
-  -- Split into X and Y components
-  local parts = {}
-  for part in position:gmatch("%S+") do
-    table.insert(parts, part:lower())
-  end
-
-  -- If only one value, use it for both axes (with special handling)
-  if #parts == 1 then
-    local val = parts[1]
-    if val == "left" or val == "right" then
-      parts = { val, "center" }
-    elseif val == "top" or val == "bottom" then
-      parts = { "center", val }
-    else
-      parts = { val, val }
-    end
-  elseif #parts == 0 then
-    return 0.5, 0.5 -- Default to center
-  end
-
-  local function parseValue(val)
-    -- Handle keywords
-    if val == "center" then
-      return 0.5
-    elseif val == "left" or val == "top" then
-      return 0
-    elseif val == "right" or val == "bottom" then
-      return 1
-    end
-
-    -- Handle percentages
-    local percent = val:match("^([%d%.]+)%%$")
-    if percent then
-      return tonumber(percent) / 100
-    end
-
-    -- Handle plain numbers (treat as percentage)
-    local num = tonumber(val)
-    if num then
-      return num / 100
-    end
-
-    -- Invalid value, default to center
-    return 0.5
-  end
-
-  local x = parseValue(parts[1])
-  local y = parseValue(parts[2] or parts[1])
-
-  -- Clamp to 0-1 range
-  x = math.max(0, math.min(1, x))
-  y = math.max(0, math.min(1, y))
-
-  return x, y
-end
-
--- Draw an image with specified object-fit mode
---@param image love.Image -- Image to draw
---@param x number -- X position of bounds
---@param y number -- Y position of bounds
---@param width number -- Width of bounds
---@param height number -- Height of bounds
---@param fitMode string? -- Object-fit mode (default: "fill")
---@param objectPosition string? -- Object-position (default: "center center")
---@param opacity number? -- Opacity 0-1 (default: 1)
---@param tintColor Color? -- Color to tint the image (default: white/no tint)
-function ImageRenderer.draw(image, x, y, width, height, fitMode, objectPosition, opacity, tintColor)
-  if not image then
-    return -- Nothing to draw
-  end
-
-  opacity = opacity or 1
-  fitMode = fitMode or "fill"
-  objectPosition = objectPosition or "center center"
-
-  local imgWidth, imgHeight = image:getDimensions()
-  local params = ImageRenderer.calculateFit(imgWidth, imgHeight, width, height, fitMode, objectPosition)
-
-  -- Save current color
-  local r, g, b, a = love.graphics.getColor()
-
-  -- Apply opacity and tint
-  if tintColor then
-    love.graphics.setColor(tintColor.r, tintColor.g, tintColor.b, tintColor.a * opacity)
-  else
-    love.graphics.setColor(1, 1, 1, opacity)
-  end
-
-  -- Draw image
-  if params.sx ~= 0 or params.sy ~= 0 or params.sw ~= imgWidth or params.sh ~= imgHeight then
-    -- Need to use a quad for cropping
-    local quad = love.graphics.newQuad(params.sx, params.sy, params.sw, params.sh, imgWidth, imgHeight)
-    love.graphics.draw(image, quad, x + params.dx, y + params.dy, 0, params.dw / params.sw, params.dh / params.sh)
-  else
-    -- Simple draw with scaling
-    love.graphics.draw(image, x + params.dx, y + params.dy, 0, params.scaleX, params.scaleY)
-  end
-
-  -- Restore color
-  love.graphics.setColor(r, g, b, a)
-end
-
--- Draw an image with tiling/repeat mode
---@param image love.Image -- Image to draw
---@param x number -- X position of bounds
---@param y number -- Y position of bounds
---@param width number -- Width of bounds
---@param height number -- Height of bounds
---@param repeatMode string? -- Repeat mode: "repeat", "repeat-x", "repeat-y", "no-repeat", "space", "round" (default: "no-repeat")
---@param opacity number? -- Opacity 0-1 (default: 1)
---@param tintColor Color? -- Color to tint the image (default: white/no tint)
-function ImageRenderer.drawTiled(image, x, y, width, height, repeatMode, opacity, tintColor)
-  if not image then
-    return -- Nothing to draw
-  end
-
-  opacity = opacity or 1
-  repeatMode = repeatMode or "no-repeat"
-
-  local imgWidth, imgHeight = image:getDimensions()
-
-  -- Save current color
-  local r, g, b, a = love.graphics.getColor()
-
-  -- Apply opacity and tint
-  if tintColor then
-    love.graphics.setColor(tintColor.r, tintColor.g, tintColor.b, tintColor.a * opacity)
-  else
-    love.graphics.setColor(1, 1, 1, opacity)
-  end
-
-  if repeatMode == "no-repeat" then
-    -- Just draw once, no tiling
-    love.graphics.draw(image, x, y)
-  elseif repeatMode == "repeat" then
-    -- Tile in both directions
-    local tilesX = math.ceil(width / imgWidth)
-    local tilesY = math.ceil(height / imgHeight)
-
-    for tileY = 0, tilesY - 1 do
-      for tileX = 0, tilesX - 1 do
-        local drawX = x + (tileX * imgWidth)
-        local drawY = y + (tileY * imgHeight)
-
-        -- Calculate how much of the tile to draw (for partial tiles at edges)
-        local drawWidth = math.min(imgWidth, width - (tileX * imgWidth))
-        local drawHeight = math.min(imgHeight, height - (tileY * imgHeight))
-
-        if drawWidth < imgWidth or drawHeight < imgHeight then
-          -- Use quad for partial tile
-          local quad = love.graphics.newQuad(0, 0, drawWidth, drawHeight, imgWidth, imgHeight)
-          love.graphics.draw(image, quad, drawX, drawY)
-        else
-          -- Draw full tile
-          love.graphics.draw(image, drawX, drawY)
-        end
-      end
-    end
-  elseif repeatMode == "repeat-x" then
-    -- Tile horizontally only
-    local tilesX = math.ceil(width / imgWidth)
-
-    for tileX = 0, tilesX - 1 do
-      local drawX = x + (tileX * imgWidth)
-      local drawWidth = math.min(imgWidth, width - (tileX * imgWidth))
-
-      if drawWidth < imgWidth then
-        -- Use quad for partial tile
-        local quad = love.graphics.newQuad(0, 0, drawWidth, imgHeight, imgWidth, imgHeight)
-        love.graphics.draw(image, quad, drawX, y)
-      else
-        -- Draw full tile
-        love.graphics.draw(image, drawX, y)
-      end
-    end
-  elseif repeatMode == "repeat-y" then
-    -- Tile vertically only
-    local tilesY = math.ceil(height / imgHeight)
-
-    for tileY = 0, tilesY - 1 do
-      local drawY = y + (tileY * imgHeight)
-      local drawHeight = math.min(imgHeight, height - (tileY * imgHeight))
-
-      if drawHeight < imgHeight then
-        -- Use quad for partial tile
-        local quad = love.graphics.newQuad(0, 0, imgWidth, drawHeight, imgWidth, imgHeight)
-        love.graphics.draw(image, quad, x, drawY)
-      else
-        -- Draw full tile
-        love.graphics.draw(image, x, drawY)
-      end
-    end
-  elseif repeatMode == "space" then
-    -- Distribute tiles with even spacing
-    local tilesX = math.floor(width / imgWidth)
-    local tilesY = math.floor(height / imgHeight)
-
-    if tilesX < 1 then
-      tilesX = 1
-    end
-    if tilesY < 1 then
-      tilesY = 1
-    end
-
-    local spaceX = tilesX > 1 and (width - (tilesX * imgWidth)) / (tilesX - 1) or 0
-    local spaceY = tilesY > 1 and (height - (tilesY * imgHeight)) / (tilesY - 1) or 0
-
-    for tileY = 0, tilesY - 1 do
-      for tileX = 0, tilesX - 1 do
-        local drawX = x + (tileX * (imgWidth + spaceX))
-        local drawY = y + (tileY * (imgHeight + spaceY))
-        love.graphics.draw(image, drawX, drawY)
-      end
-    end
-  elseif repeatMode == "round" then
-    -- Scale tiles to fit bounds exactly
-    local tilesX = math.max(1, utils.round(width / imgWidth))
-    local tilesY = math.max(1, utils.round(height / imgHeight))
-
-    local scaleX = width / (tilesX * imgWidth)
-    local scaleY = height / (tilesY * imgHeight)
-
-    for tileY = 0, tilesY - 1 do
-      for tileX = 0, tilesX - 1 do
-        local drawX = x + (tileX * imgWidth * scaleX)
-        local drawY = y + (tileY * imgHeight * scaleY)
-        love.graphics.draw(image, drawX, drawY, 0, scaleX, scaleY)
-      end
-    end
-  else
-    ErrorHandler:warn("ImageRenderer", "VAL_007", {
-      repeatMode = repeatMode,
-      fallback = "no-repeat",
-    })
-    love.graphics.draw(image, x, y)
-  end
-
-  -- Restore color
-  love.graphics.setColor(r, g, b, a)
-end
-
-return ImageRenderer
@@ -1,174 +0,0 @@
-- ====================
-- ImageScaler
-- ====================
-
-local ImageScaler = {}
-
-- ErrorHandler will be injected via init
-local ErrorHandler = nil
-
--- Initialize ImageScaler with dependencies
---@param deps table Dependencies table with ErrorHandler
-function ImageScaler.init(deps)
-  if deps and deps.ErrorHandler then
-    ErrorHandler = deps.ErrorHandler
-  end
-end
-
--- Scale an ImageData region using nearest-neighbor sampling
--- Produces sharp, pixelated scaling - ideal for pixel art
---@param sourceImageData love.ImageData -- Source image data
---@param srcX number -- Source region X (0-based)
---@param srcY number -- Source region Y (0-based)
---@param srcW number -- Source region width
---@param srcH number -- Source region height
---@param destW number -- Destination width
---@param destH number -- Destination height
---@return love.ImageData -- Scaled image data
-function ImageScaler.scaleNearest(sourceImageData, srcX, srcY, srcW, srcH, destW, destH)
-  if not sourceImageData then
-    ErrorHandler:error("ImageScaler", "VAL_001", {
-      parameter = "sourceImageData",
-    })
-  end
-
-  if srcW <= 0 or srcH <= 0 or destW <= 0 or destH <= 0 then
-    ErrorHandler:warn("ImageScaler", "VAL_002", {
-      srcW = srcW,
-      srcH = srcH,
-      destW = destW,
-      destH = destH,
-      fallback = "1x1 transparent image",
-    })
-    -- Return a minimal 1x1 transparent image as fallback
-    local fallbackImageData = love.image.newImageData(1, 1)
-    fallbackImageData:setPixel(0, 0, 0, 0, 0, 0)
-    return fallbackImageData
-  end
-
-  -- Create destination ImageData
-  local destImageData = love.image.newImageData(destW, destH)
-
-  -- Calculate scale ratios (cached outside loops for performance)
-  local scaleX = srcW / destW
-  local scaleY = srcH / destH
-
-  -- Nearest-neighbor sampling
-  for destY = 0, destH - 1 do
-    for destX = 0, destW - 1 do
-      -- Calculate source pixel coordinates using floor (nearest-neighbor)
-      local srcPixelX = math.floor(destX * scaleX) + srcX
-      local srcPixelY = math.floor(destY * scaleY) + srcY
-
-      -- Clamp to source bounds (safety check)
-      srcPixelX = math.min(srcPixelX, srcX + srcW - 1)
-      srcPixelY = math.min(srcPixelY, srcY + srcH - 1)
-
-      -- Sample source pixel
-      local r, g, b, a = sourceImageData:getPixel(srcPixelX, srcPixelY)
-
-      -- Write to destination
-      destImageData:setPixel(destX, destY, r, g, b, a)
-    end
-  end
-
-  return destImageData
-end
-
--- Linear interpolation helper
--- Blends between two values based on interpolation factor
---@param a number -- Start value
---@param b number -- End value
---@param t number -- Interpolation factor [0, 1]
---@return number -- Interpolated value
-local function lerp(a, b, t)
-  return a + (b - a) * t
-end
-
--- Scale an ImageData region using bilinear interpolation
--- Produces smooth, filtered scaling - ideal for high-quality upscaling
---@param sourceImageData love.ImageData -- Source image data
---@param srcX number -- Source region X (0-based)
---@param srcY number -- Source region Y (0-based)
---@param srcW number -- Source region width
---@param srcH number -- Source region height
---@param destW number -- Destination width
---@param destH number -- Destination height
---@return love.ImageData -- Scaled image data
-function ImageScaler.scaleBilinear(sourceImageData, srcX, srcY, srcW, srcH, destW, destH)
-  if not sourceImageData then
-    ErrorHandler:error("ImageScaler", "VAL_001", {
-      parameter = "sourceImageData",
-    })
-  end
-
-  if srcW <= 0 or srcH <= 0 or destW <= 0 or destH <= 0 then
-    ErrorHandler:warn("ImageScaler", "VAL_002", {
-      srcW = srcW,
-      srcH = srcH,
-      destW = destW,
-      destH = destH,
-      fallback = "1x1 transparent image",
-    })
-    -- Return a minimal 1x1 transparent image as fallback
-    local fallbackImageData = love.image.newImageData(1, 1)
-    fallbackImageData:setPixel(0, 0, 0, 0, 0, 0)
-    return fallbackImageData
-  end
-
-  -- Create destination ImageData
-  local destImageData = love.image.newImageData(destW, destH)
-
-  -- Calculate scale ratios
-  local scaleX = srcW / destW
-  local scaleY = srcH / destH
-
-  -- Bilinear interpolation
-  for destY = 0, destH - 1 do
-    for destX = 0, destW - 1 do
-      -- Calculate fractional source position
-      local srcXf = destX * scaleX
-      local srcYf = destY * scaleY
-
-      -- Get integer coordinates for 2x2 sampling grid
-      local x0 = math.floor(srcXf)
-      local y0 = math.floor(srcYf)
-      local x1 = math.min(x0 + 1, srcW - 1)
-      local y1 = math.min(y0 + 1, srcH - 1)
-
-      -- Get fractional parts for interpolation
-      local fx = srcXf - x0
-      local fy = srcYf - y0
-
-      -- Sample 4 neighboring pixels (with source offset)
-      local r00, g00, b00, a00 = sourceImageData:getPixel(srcX + x0, srcY + y0)
-      local r10, g10, b10, a10 = sourceImageData:getPixel(srcX + x1, srcY + y0)
-      local r01, g01, b01, a01 = sourceImageData:getPixel(srcX + x0, srcY + y1)
-      local r11, g11, b11, a11 = sourceImageData:getPixel(srcX + x1, srcY + y1)
-
-      -- Interpolate horizontally (top and bottom rows)
-      local rTop = lerp(r00, r10, fx)
-      local gTop = lerp(g00, g10, fx)
-      local bTop = lerp(b00, b10, fx)
-      local aTop = lerp(a00, a10, fx)
-
-      local rBottom = lerp(r01, r11, fx)
-      local gBottom = lerp(g01, g11, fx)
-      local bBottom = lerp(b01, b11, fx)
-      local aBottom = lerp(a01, a11, fx)
-
-      -- Interpolate vertically (final result)
-      local r = lerp(rTop, rBottom, fy)
-      local g = lerp(gTop, gBottom, fy)
-      local b = lerp(bTop, bBottom, fy)
-      local a = lerp(aTop, aBottom, fy)
-
-      -- Write to destination
-      destImageData:setPixel(destX, destY, r, g, b, a)
-    end
-  end
-
-  return destImageData
-end
-
-return ImageScaler
@@ -1,88 +0,0 @@
---@class InputEvent
---@field type "click"|"press"|"release"|"rightclick"|"middleclick"|"drag"|"hover"|"unhover"|"touchpress"|"touchmove"|"touchrelease"|"touchcancel"
---@field button number -- Mouse button: 1 (left), 2 (right), 3 (middle)
---@field x number -- Mouse/Touch X position
---@field y number -- Mouse/Touch Y position
---@field dx number? -- Delta X from drag/touch start (only for drag/touch events)
---@field dy number? -- Delta Y from drag/touch start (only for drag/touch events)
---@field modifiers {shift:boolean, ctrl:boolean, alt:boolean, super:boolean}
---@field clickCount number -- Number of clicks (for double/triple click detection)
---@field timestamp number -- Time when event occurred
---@field touchId string? -- Touch identifier (for multi-touch)
---@field pressure number? -- Touch pressure (0-1, defaults to 1.0)
---@field phase string? -- Touch phase: "began", "moved", "ended", "cancelled"
-local InputEvent = {}
-InputEvent.__index = InputEvent
-
---@class InputEventProps
---@field type "click"|"press"|"release"|"rightclick"|"middleclick"|"drag"|"hover"|"unhover"|"touchpress"|"touchmove"|"touchrelease"|"touchcancel"
---@field button number
---@field x number
---@field y number
---@field dx number?
---@field dy number?
---@field modifiers {shift:boolean, ctrl:boolean, alt:boolean, super:boolean}
---@field clickCount number?
---@field timestamp number?
---@field touchId string?
---@field pressure number?
---@field phase string?
-
--- Create a new input event
---@param props InputEventProps
---@return InputEvent
-function InputEvent.new(props)
-  local self = setmetatable({}, InputEvent)
-  self.type = props.type
-  self.button = props.button
-  self.x = props.x
-  self.y = props.y
-  self.dx = props.dx
-  self.dy = props.dy
-  self.modifiers = props.modifiers
-  self.clickCount = props.clickCount or 1
-  self.timestamp = props.timestamp or love.timer.getTime()
-
-  -- Touch-specific properties
-  self.touchId = props.touchId
-  self.pressure = props.pressure or 1.0
-  self.phase = props.phase
-
-  return self
-end
-
--- Create an InputEvent from LÖVE touch data
---@param id userdata Touch ID from LÖVE
---@param x number Touch X position
---@param y number Touch Y position
---@param phase string Touch phase: "began", "moved", "ended", "cancelled"
---@param pressure number? Touch pressure (0-1, defaults to 1.0)
---@return InputEvent
-function InputEvent.fromTouch(id, x, y, phase, pressure)
-  local touchIdStr = tostring(id)
-  local eventType = "touchpress"
-  if phase == "moved" then
-    eventType = "touchmove"
-  elseif phase == "ended" then
-    eventType = "touchrelease"
-  elseif phase == "cancelled" then
-    eventType = "touchcancel"
-  end
-
-  return InputEvent.new({
-    type = eventType,
-    button = 1, -- Treat touch as left button
-    x = x,
-    y = y,
-    dx = 0,
-    dy = 0,
-    modifiers = { shift = false, ctrl = false, alt = false, super = false },
-    clickCount = 1,
-    timestamp = love.timer.getTime(),
-    touchId = touchIdStr,
-    pressure = pressure or 1.0,
-    phase = phase,
-  })
-end
-
-return InputEvent
@@ -1,748 +0,0 @@
-local packageName = ... or "KeyboardNavigation"
-local modulePath = packageName:match("(.-)[^%.]+$")
-
-local function req(name)
-  return require(modulePath .. name)
-end
-
---@class KeyboardNavigation
---@field config KeyboardNavigationConfig
-local KeyboardNavigation = {
-
-  config = {
-    -- Global settings
-    enabled = true,
-    debugMode = false,
-
-    -- Key bindings
-    keys = {
-      next = "tab",
-      previous = "shifttab",
-      up = "up",
-      down = "down",
-      left = "left",
-      right = "right",
-      activate = { "return", "space" },
-      dismiss = "escape",
-      toggleDebug = "f12",
-      inspect = "i",
-    },
-
-    -- Navigation behavior
-    wrapAround = true,
-    directionalNavigation = true,
-    focusVisible = true,
-    autofocusOnCreate = false,
-
-    --- Drop focus after pressing Enter/Space to activate an element
-    --- When false, focus remains on the element after activation
-    dropFocusOnSelection = true,
-
-    -- Developer tools
-    developerTools = {
-      enabled = true,
-      showProperties = true,
-      highlightColor = { 1, 0.8, 0, 0.5 },
-    },
-
-    -- Focus indicator style
-    focusIndicator = {
-      color = { 0.2, 0.6, 1.0, 0.8 },
-      lineWidth = 2,
-      inset = -3,
-      borderRadius = 4,
-      animationDuration = 0.15,
-    },
-  },
-
-  -- State
-  _navigationStack = {},
-  _lastNavigationTime = 0,
-  _inspectMode = false,
-  _deps = nil,
-
-  -- Spatial index for directional navigation (performance optimization)
-  _spatialIndex = {
-    enabled = false,
-    cellSize = 100, -- Grid cell size in pixels
-    grid = {}, -- Grid storing element references
-    elementPositions = {}, -- Cache of element positions {element = {x, y, w, h}}
-    lastUpdateFrame = 0,
-  },
-}
-
--- Initialize KeyboardNavigation module
---@param deps table {Context, Element, ErrorHandler, utils, InputEvent}
-function KeyboardNavigation.init(deps)
-  -- Validate required dependencies
-  local required = { Context = true, Element = true, ErrorHandler = true, utils = true, InputEvent = true }
-  for depName, _ in pairs(required) do
-    if not deps[depName] then
-      error(string.format("KeyboardNavigation.init: Missing required dependency: %s", depName))
-    end
-  end
-
-  KeyboardNavigation._deps = deps
-  KeyboardNavigation._ErrorHandler = deps.ErrorHandler
-  KeyboardNavigation._InputEvent = deps.InputEvent
-  KeyboardNavigation._Context = deps.Context
-  KeyboardNavigation._Element = deps.Element
-  KeyboardNavigation._utils = deps.utils
-end
-
--- Handle keyboard press for navigation
---@param key string
---@param scancode string
---@param isrepeat boolean
---@return boolean handled
-function KeyboardNavigation:handleKeyPress(key, scancode, isrepeat)
-  if not KeyboardNavigation._Context then
-    return false
-  end
-
-  -- Debug logging
-  if KeyboardNavigation.config.debugMode then
-    print(
-      string.format(
-        "[KeyboardNavigation] Key pressed: %s (scancode: %s, repeat: %s)",
-        key,
-        scancode,
-        tostring(isrepeat)
-      )
-    )
-    print(string.format("[KeyboardNavigation] Enabled: %s", tostring(KeyboardNavigation.config.enabled)))
-  end
-
-  local config = KeyboardNavigation.config
-  local keys = config.keys
-
-  -- Check for activation keys
-  for _, activateKey in ipairs(keys.activate) do
-    if key == activateKey then
-      return self:activateElement()
-    end
-  end
-
-  -- Check for dismiss key
-  if key == keys.dismiss then
-    return self:dismissElement()
-  end
-
-  -- Check for next/previous navigation
-  -- Tab with shift held = previous; Tab without shift = next
-  if key == keys.next then
-    if love.keyboard.isDown("lshift") or love.keyboard.isDown("rshift") then
-      return self:previousFocusable()
-    end
-    return self:nextFocusable()
-  end
-
-  if key == keys.previous then
-    return self:previousFocusable()
-  end
-
-  -- Check for directional navigation
-  if config.directionalNavigation then
-    if key == keys.up then
-      return self:navigateDirectional("up")
-    elseif key == keys.down then
-      return self:navigateDirectional("down")
-    elseif key == keys.left then
-      return self:navigateDirectional("left")
-    elseif key == keys.right then
-      return self:navigateDirectional("right")
-    end
-  end
-
-  return false
-end
-
--- Find next focusable element in the focusable list
---@param focusableList table<Element> List of focusable elements in tab order
---@param current Element? Currently focused element
---@return Element?
-function KeyboardNavigation:_findNextInList(focusableList, current)
-  local currentIndex = 0
-  if current then
-    for i, elem in ipairs(focusableList) do
-      if elem.id == current.id then
-        currentIndex = i
-        break
-      end
-    end
-  end
-
-  -- Search forward
-  if currentIndex < #focusableList then
-    return focusableList[currentIndex + 1]
-  end
-
-  -- Wrap around if enabled
-  if KeyboardNavigation.config.wrapAround and #focusableList > 0 then
-    return focusableList[1]
-  end
-
-  return nil
-end
-
--- Get the focusable element list scoped to the navigation container
---@return Element[]
-function KeyboardNavigation:_getScopedFocusableList()
-  local Context = KeyboardNavigation._Context
-  local container = Context.getNavigationContainer()
-  if container then
-    return container:getFocusableChildren()
-  end
-  return Context.getFocusableElements()
-end
-
--- Navigate to next focusable element (Tab)
---@return boolean success
-function KeyboardNavigation:nextFocusable()
-  local Context = KeyboardNavigation._Context
-
-  local current = Context.getFocused()
-  if KeyboardNavigation.config.debugMode then
-    print(
-      string.format("[KeyboardNavigation] Tab pressed - Current focus: %s", tostring(current and current.id or "nil"))
-    )
-  end
-
-  local focusableList = self:_getScopedFocusableList()
-  local nextElem = self:_findNextInList(focusableList, current)
-
-  if nextElem then
-    self:_focusElement(nextElem)
-    return true
-  end
-
-  return false
-end
-
--- Find previous focusable element in the focusable list
---@param focusableList table<Element> List of focusable elements in tab order
---@param current Element? Currently focused element
---@return Element?
-function KeyboardNavigation:_findPreviousInList(focusableList, current)
-  local currentIndex = #focusableList + 1
-  if current then
-    for i, elem in ipairs(focusableList) do
-      if elem.id == current.id then
-        currentIndex = i
-        break
-      end
-    end
-  end
-
-  -- Search backward
-  if currentIndex - 1 >= 1 then
-    return focusableList[currentIndex - 1]
-  end
-
-  -- Wrap around if enabled
-  if KeyboardNavigation.config.wrapAround and #focusableList > 0 then
-    return focusableList[#focusableList]
-  end
-
-  return nil
-end
-
--- Navigate to previous focusable element (Shift+Tab)
---@return boolean success
-function KeyboardNavigation:previousFocusable()
-  local Context = KeyboardNavigation._Context
-
-  local current = Context.getFocused()
-
-  local focusableList = self:_getScopedFocusableList()
-  local prevElem = self:_findPreviousInList(focusableList, current)
-
-  if prevElem then
-    self:_focusElement(prevElem)
-    return true
-  end
-
-  return false
-end
-
--- Navigate using arrow keys
---@param direction "up"|"down"|"left"|"right"
---@return boolean success
-function KeyboardNavigation:navigateDirectional(direction)
-  local Context = KeyboardNavigation._Context
-  local current = Context.getFocused()
-
-  if not current then
-    return false
-  end
-
-  local nextElem = KeyboardNavigation:_findDirectionalNeighbor(current, direction)
-
-  if nextElem then
-    self:_focusElement(nextElem)
-    return true
-  end
-
-  return false
-end
-
--- Find closest focusable element in the given direction
---@param current Element
---@param direction "up"|"down"|"left"|"right"
---@return Element?
-function KeyboardNavigation:_findDirectionalNeighbor(current, direction)
-  -- Try spatial index first if enabled
-  if KeyboardNavigation._spatialIndex.enabled then
-    local spatialResult = self:_findDirectionalNeighborSpatial(current, direction)
-    if spatialResult then
-      return spatialResult
-    end
-  end
-
-  -- Collect all focusable elements visible this frame
-  local Context = KeyboardNavigation._Context
-  local focusable = {}
-
-  local function collectFocusable(elem)
-    if elem:isFocusable() and elem ~= current then
-      table.insert(focusable, elem)
-    end
-    for _, child in ipairs(elem.children) do
-      collectFocusable(child)
-    end
-  end
-
-  -- Mode-agnostic: collect from Context's focusable list
-  local allFocusable = Context.getFocusableElements()
-  for _, elem in ipairs(allFocusable) do
-    if elem ~= current then
-      table.insert(focusable, elem)
-    end
-  end
-
-  if #focusable == 0 then
-    return nil
-  end
-
-  local currentRect = {
-    x = current.x,
-    y = current.y,
-    width = current.width or 0,
-    height = current.height or 0,
-  }
-
-  local closest = nil
-  local closestDistance = math.huge
-
-  for _, elem in ipairs(focusable) do
-    local elemRect = {
-      x = elem.x,
-      y = elem.y,
-      width = elem.width or 0,
-      height = elem.height or 0,
-    }
-
-    local distance, isInDirection = self:_calculateDirectionalDistance(currentRect, elemRect, direction)
-
-    if isInDirection and distance < closestDistance then
-      closest = elem
-      closestDistance = distance
-    end
-  end
-
-  -- If no element found in exact direction, try with looser criteria
-  if not closest then
-    closest = self:_findClosestInDirection(current, focusable, direction)
-  end
-
-  return closest
-end
-
--- Calculate distance and direction between elements
---@param from table {x, y, width, height}
---@param to table {x, y, width, height}
---@param direction string
---@return number distance, boolean isInDirection
-function KeyboardNavigation:_calculateDirectionalDistance(from, to, direction)
-  -- Calculate bounding box edges
-  local fromLeft = from.x
-  local fromRight = from.x + from.width
-  local fromTop = from.y
-  local fromBottom = from.y + from.height
-
-  local toLeft = to.x
-  local toRight = to.x + to.width
-  local toTop = to.y
-  local toBottom = to.y + to.height
-
-  local distance = math.huge
-  local isInDirection = false
-
-  if direction == "up" then
-    if toBottom < fromTop then
-      isInDirection = true
-      distance = fromTop - toBottom
-    end
-  elseif direction == "down" then
-    if toTop > fromBottom then
-      isInDirection = true
-      distance = toTop - fromBottom
-    end
-  elseif direction == "left" then
-    if toRight < fromLeft then
-      isInDirection = true
-      distance = fromLeft - toRight
-    end
-  elseif direction == "right" then
-    if toLeft > fromRight then
-      isInDirection = true
-      distance = toLeft - fromRight
-    end
-  end
-
-  return distance, isInDirection
-end
-
--- Find closest element in direction using center-to-center distance
---@param current Element
---@param focusable Element[]
---@param direction string
---@return Element?
-function KeyboardNavigation:_findClosestInDirection(current, focusable, direction)
-  local currentCenterX = current.x + (current.width or 0) / 2
-  local currentCenterY = current.y + (current.height or 0) / 2
-
-  local closest = nil
-  local closestDistance = math.huge
-
-  for _, elem in ipairs(focusable) do
-    if elem ~= current then
-      local elemCenterX = elem.x + (elem.width or 0) / 2
-      local elemCenterY = elem.y + (elem.height or 0) / 2
-
-      local dx = elemCenterX - currentCenterX
-      local dy = elemCenterY - currentCenterY
-
-      -- Check if element is generally in the right direction
-      local isInDirection = false
-
-      if direction == "up" and dy < 0 then
-        isInDirection = true
-      elseif direction == "down" and dy > 0 then
-        isInDirection = true
-      elseif direction == "left" and dx < 0 then
-        isInDirection = true
-      elseif direction == "right" and dx > 0 then
-        isInDirection = true
-      end
-
-      if isInDirection then
-        local distance = math.sqrt(dx * dx + dy * dy)
-        if distance < closestDistance then
-          closest = elem
-          closestDistance = distance
-        end
-      end
-    end
-  end
-
-  return closest
-end
-
--- Focus an element
---@param element Element
-function KeyboardNavigation:_focusElement(element)
-  local Context = KeyboardNavigation._Context
-
-  if element and element:isFocusable() then
-    if KeyboardNavigation.config.debugMode then
-      print(
-        string.format(
-          "[KeyboardNavigation] Focusing element: %s (id: %s)",
-          element.themeComponent or "unknown",
-          tostring(element.id)
-        )
-      )
-    end
-    Context.setFocused(element)
-
-    -- Update focus indicator
-    if KeyboardNavigation.FocusIndicator then
-      KeyboardNavigation.FocusIndicator.setFocused(element)
-    end
-
-    -- Call onFocus callback if it exists
-    if element.onFocus then
-      local success, err = pcall(function()
-        if element.onFocusDeferred then
-          table.insert(Context._deferredCallbacks or {}, function()
-            element:onFocus(element)
-          end)
-        else
-          element:onFocus(element)
-        end
-      end)
-
-      if not success then
-        KeyboardNavigation._ErrorHandler:warn("KeyboardNavigation", "NAV_001", {
-          elementId = element.id or "unknown",
-          error = tostring(err),
-        })
-      end
-    end
-  end
-end
-
---@param element Element
---@return boolean
-function KeyboardNavigation:_shouldDropFocusOnSelection(element)
-  if element and element.dropFocusOnSelection ~= nil then
-    return element.dropFocusOnSelection == true
-  end
-
-  return KeyboardNavigation.config.dropFocusOnSelection == true
-end
-
--- Activate currently focused element
---@return boolean success
-function KeyboardNavigation:activateElement()
-  local Context = KeyboardNavigation._Context
-  local focused = Context.getFocused()
-
-  if not focused then
-    return false
-  end
-
-  if focused.disabled then
-    return false
-  end
-
-  -- Fire press and release events
-  if focused.onEvent then
-    local modifiers = KeyboardNavigation._utils.getModifiers()
-    local pressEvent = KeyboardNavigation._InputEvent.new({
-      type = "press",
-      button = 1,
-      x = focused.x,
-      y = focused.y,
-      modifiers = modifiers,
-      clickCount = 1,
-    })
-
-    local releaseEvent = KeyboardNavigation._InputEvent.new({
-      type = "release",
-      button = 1,
-      x = focused.x,
-      y = focused.y,
-      modifiers = modifiers,
-      clickCount = 1,
-    })
-
-    local success, err = pcall(function()
-      focused.onEvent(focused, pressEvent)
-      focused.onEvent(focused, releaseEvent)
-    end)
-
-    if not success then
-      KeyboardNavigation._ErrorHandler:warn("KeyboardNavigation", "NAV_002", {
-        elementId = focused.id or "unknown",
-        error = tostring(err),
-      })
-    end
-
-    -- Drop focus after selection based on per-element override or global config.
-    if KeyboardNavigation:_shouldDropFocusOnSelection(focused) then
-      Context.clearFocus()
-      if KeyboardNavigation.FocusIndicator then
-        KeyboardNavigation.FocusIndicator.setFocused(nil)
-      end
-    end
-
-    return true
-  end
-
-  return false
-end
-
--- Dismiss currently focused element
---@return boolean success
-function KeyboardNavigation:dismissElement()
-  local Context = KeyboardNavigation._Context
-  local focused = Context.getFocused()
-
-  if not focused then
-    return false
-  end
-
-  -- Check if element has a dismiss handler
-  if focused.onDismiss then
-    local success, err = pcall(function()
-      if focused.onDismissDeferred then
-        table.insert(Context._deferredCallbacks or {}, function()
-          focused:onDismiss(focused)
-        end)
-      else
-        focused:onDismiss(focused)
-      end
-    end)
-
-    if not success then
-      KeyboardNavigation._ErrorHandler:warn("KeyboardNavigation", "NAV_003", {
-        elementId = focused.id or "unknown",
-        error = tostring(err),
-      })
-    end
-
-    return true -- Handler took care of dismissal
-  end
-
-  -- Default behavior: blur the element (only if no onDismiss handler)
-  Context.clearFocus()
-  return true
-end
-
--- Update keyboard navigation (for animations, etc.)
---@param dt number
-function KeyboardNavigation:update(dt)
-  -- Update focus indicator if it exists
-  if KeyboardNavigation.FocusIndicator then
-    KeyboardNavigation.FocusIndicator:update(dt)
-  end
-end
-
--- Push current focus onto stack (for modals/dialogs)
--- Saves current focus and sets new focus to the given element
---@param element Element? The element to focus (e.g., modal dialog)
-function KeyboardNavigation:pushFocus(element)
-  local Context = KeyboardNavigation._Context
-
-  table.insert(KeyboardNavigation._navigationStack, Context.getFocused())
-  Context.pushFocusStack(element)
-end
-
--- Pop focus from stack (return from modal)
--- Restores previously focused element from the stack
---@return Element? The previously focused element, or nil if stack was empty
-function KeyboardNavigation:popFocus()
-  local Context = KeyboardNavigation._Context
-
-  local previous = Context.popFocusStack()
-  if #KeyboardNavigation._navigationStack > 0 then
-    previous = table.remove(KeyboardNavigation._navigationStack)
-  end
-
-  return previous
-end
-
-- ====================
-- Spatial Index (Performance Optimization)
-- ====================
-
--- Enable spatial index for faster directional navigation
---@param enabled boolean
-function KeyboardNavigation.enableSpatialIndex(enabled)
-  KeyboardNavigation._spatialIndex.enabled = enabled
-  if not enabled then
-    KeyboardNavigation:_clearSpatialIndex()
-  end
-end
-
--- Clear spatial index
-function KeyboardNavigation:_clearSpatialIndex()
-  KeyboardNavigation._spatialIndex.grid = {}
-  KeyboardNavigation._spatialIndex.elementPositions = {}
-end
-
--- Find directional neighbor using spatial index
---@param current Element
---@param direction "up"|"down"|"left"|"right"
---@return Element?
-function KeyboardNavigation:_findDirectionalNeighborSpatial(current, direction)
-  local index = KeyboardNavigation._spatialIndex
-  local cellSize = index.cellSize
-
-  -- Get current element's grid position
-  local currentPos = index.elementPositions[current]
-  if not currentPos then
-    return nil
-  end
-
-  local centerX = currentPos.x + currentPos.w / 2
-  local centerY = currentPos.y + currentPos.h / 2
-  local currentCellX = math.floor(centerX / cellSize)
-  local currentCellY = math.floor(centerY / cellSize)
-
-  -- Search in direction, expanding outward
-  local maxSearchRadius = 20 -- Maximum cells to search
-  local visited = {}
-
-  for radius = 1, maxSearchRadius do
-    local candidates = {}
-
-    -- Get cells in the search ring
-    if direction == "up" then
-      table.insert(candidates, { currentCellX, currentCellY - radius })
-      if radius > 1 then
-        table.insert(candidates, { currentCellX - 1, currentCellY - radius })
-        table.insert(candidates, { currentCellX + 1, currentCellY - radius })
-      end
-    elseif direction == "down" then
-      table.insert(candidates, { currentCellX, currentCellY + radius })
-      if radius > 1 then
-        table.insert(candidates, { currentCellX - 1, currentCellY + radius })
-        table.insert(candidates, { currentCellX + 1, currentCellY + radius })
-      end
-    elseif direction == "left" then
-      table.insert(candidates, { currentCellX - radius, currentCellY })
-      if radius > 1 then
-        table.insert(candidates, { currentCellX - radius, currentCellY - 1 })
-        table.insert(candidates, { currentCellX - radius, currentCellY + 1 })
-      end
-    elseif direction == "right" then
-      table.insert(candidates, { currentCellX + radius, currentCellY })
-      if radius > 1 then
-        table.insert(candidates, { currentCellX + radius, currentCellY - 1 })
-        table.insert(candidates, { currentCellX + radius, currentCellY + 1 })
-      end
-    end
-
-    -- Check each candidate cell
-    for _, cell in ipairs(candidates) do
-      local cellKey = string.format("%d,%d", cell[1], cell[2])
-      local cellElements = index.grid[cellKey]
-
-      if cellElements then
-        for _, elem in ipairs(cellElements) do
-          if elem ~= current and not visited[elem] then
-            visited[elem] = true
-            local elemPos = index.elementPositions[elem]
-            if elemPos then
-              local elemCenterX = elemPos.x + elemPos.w / 2
-              local elemCenterY = elemPos.y + elemPos.h / 2
-
-              -- Check if element is in the correct direction
-              local isInDirection = false
-              if direction == "up" and elemCenterY < centerY then
-                isInDirection = true
-              elseif direction == "down" and elemCenterY > centerY then
-                isInDirection = true
-              elseif direction == "left" and elemCenterX < centerX then
-                isInDirection = true
-              elseif direction == "right" and elemCenterX > centerX then
-                isInDirection = true
-              end
-
-              if isInDirection then
-                return elem
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-
-  return nil
-end
-
-return KeyboardNavigation
@@ -1,697 +0,0 @@
---@class MemoryScanner
---@field _StateManager table
---@field _Context table
---@field _ImageCache table
---@field _ErrorHandler table
-local MemoryScanner = {}
-
---Initialize MemoryScanner with dependencies
---@param deps {StateManager: table, Context: table, ImageCache: table, ErrorHandler: table}
-function MemoryScanner.init(deps)
-  MemoryScanner._StateManager = deps.StateManager
-  MemoryScanner._Context = deps.Context
-  MemoryScanner._ImageCache = deps.ImageCache
-  MemoryScanner._ErrorHandler = deps.ErrorHandler
-end
-
---Count items in a table
---@param tbl table
---@return number
-local function countTable(tbl)
-  local count = 0
-  for _ in pairs(tbl) do
-    count = count + 1
-  end
-  return count
-end
-
---Calculate memory size estimate for a table (recursive)
---@param tbl table
---@param visited table? Tracking table to prevent circular references
---@param depth number? Current recursion depth
---@return number bytes Estimated memory usage in bytes
-local function estimateTableSize(tbl, visited, depth)
-  if type(tbl) ~= "table" then
-    return 0
-  end
-
-  visited = visited or {}
-  depth = depth or 0
-
-  -- Limit recursion depth to prevent stack overflow
-  if depth > 10 then
-    return 0
-  end
-
-  -- Check for circular references
-  if visited[tbl] then
-    return 0
-  end
-  visited[tbl] = true
-
-  local size = 40 -- Base table overhead (approximate)
-
-  for k, v in pairs(tbl) do
-    -- Key size
-    if type(k) == "string" then
-      size = size + #k + 24 -- String overhead
-    elseif type(k) == "number" then
-      size = size + 8
-    else
-      size = size + 8 -- Reference
-    end
-
-    -- Value size
-    if type(v) == "string" then
-      size = size + #v + 24
-    elseif type(v) == "number" then
-      size = size + 8
-    elseif type(v) == "boolean" then
-      size = size + 4
-    elseif type(v) == "table" then
-      size = size + estimateTableSize(v, visited, depth + 1)
-    elseif type(v) == "function" then
-      size = size + 16 -- Function reference
-    else
-      size = size + 8 -- Other references
-    end
-  end
-
-  return size
-end
-
---Scan StateManager for memory issues
---@return table report Detailed report of StateManager memory usage
-function MemoryScanner.scanStateManager()
-  local report = {
-    stateCount = 0,
-    stateStoreSize = 0,
-    metadataSize = 0,
-    callSiteCounterSize = 0,
-    orphanedStates = {},
-    staleStates = {},
-    largeStates = {},
-    issues = {},
-  }
-
-  if not MemoryScanner._StateManager then
-    table.insert(report.issues, {
-      severity = "error",
-      message = "StateManager not initialized",
-    })
-    return report
-  end
-
-  local internal = MemoryScanner._StateManager._getInternalState()
-  local stateStore = internal.stateStore
-  local stateMetadata = internal.stateMetadata
-  local callSiteCounters = internal.callSiteCounters
-  local currentFrame = MemoryScanner._StateManager.getFrameNumber()
-
-  -- Count states
-  report.stateCount = countTable(stateStore)
-
-  -- Estimate sizes
-  report.stateStoreSize = estimateTableSize(stateStore)
-  report.metadataSize = estimateTableSize(stateMetadata)
-  report.callSiteCounterSize = estimateTableSize(callSiteCounters)
-
-  -- Check for orphaned states (metadata without state)
-  for id, _ in pairs(stateMetadata) do
-    if not stateStore[id] then
-      table.insert(report.orphanedStates, id)
-    end
-  end
-
-  -- Check for stale states (not accessed in many frames)
-  local staleThreshold = 120 -- 2 seconds at 60fps
-  for id, meta in pairs(stateMetadata) do
-    local framesSinceAccess = currentFrame - meta.lastFrame
-    if framesSinceAccess > staleThreshold then
-      table.insert(report.staleStates, {
-        id = id,
-        framesSinceAccess = framesSinceAccess,
-        createdFrame = meta.createdFrame,
-        accessCount = meta.accessCount,
-      })
-    end
-  end
-
-  -- Check for large states (may indicate memory bloat)
-  for id, state in pairs(stateStore) do
-    local stateSize = estimateTableSize(state)
-    if stateSize > 1024 then -- More than 1KB
-      table.insert(report.largeStates, {
-        id = id,
-        size = stateSize,
-        keyCount = countTable(state),
-      })
-    end
-  end
-
-  -- Check callSiteCounters (should be near 0 after frame cleanup)
-  local callSiteCount = countTable(callSiteCounters)
-  if callSiteCount > 100 then
-    table.insert(report.issues, {
-      severity = "warning",
-      message = string.format("callSiteCounters has %d entries (expected near 0)", callSiteCount),
-      suggestion = "incrementFrame() may not be called properly, or counters aren't being reset",
-    })
-  end
-
-  -- Check for excessive state count
-  if report.stateCount > 500 then
-    table.insert(report.issues, {
-      severity = "warning",
-      message = string.format("High state count: %d states", report.stateCount),
-      suggestion = "Consider reducing element count or implementing more aggressive cleanup",
-    })
-  end
-
-  -- Check for orphaned states
-  if #report.orphanedStates > 0 then
-    table.insert(report.issues, {
-      severity = "error",
-      message = string.format("Found %d orphaned states (metadata without state)", #report.orphanedStates),
-      suggestion = "This indicates a bug in state management - metadata should be cleaned up with state",
-    })
-  end
-
-  -- Check for stale states
-  if #report.staleStates > 10 then
-    table.insert(report.issues, {
-      severity = "warning",
-      message = string.format("Found %d stale states (not accessed in 2+ seconds)", #report.staleStates),
-      suggestion = "Cleanup may not be aggressive enough - consider reducing stateRetentionFrames",
-    })
-  end
-
-  return report
-end
-
---Scan Context for memory issues
---@return table report Detailed report of Context memory usage
-function MemoryScanner.scanContext()
-  local report = {
-    topElementCount = 0,
-    zIndexElementCount = 0,
-    frameElementCount = 0,
-    issues = {},
-  }
-
-  if not MemoryScanner._Context then
-    table.insert(report.issues, {
-      severity = "error",
-      message = "Context not initialized",
-    })
-    return report
-  end
-
-  -- Count elements
-  report.topElementCount = #MemoryScanner._Context.topElements
-  report.zIndexElementCount = #MemoryScanner._Context._zIndexOrderedElements
-  report.frameElementCount = #MemoryScanner._Context._currentFrameElements
-
-  -- Check for stale z-index elements (should be cleared each frame)
-  if MemoryScanner._Context.isImmediateMode() then
-    -- In immediate mode, _zIndexOrderedElements should be cleared at frame start
-    -- If it has elements outside of frame rendering, that's a leak
-    if not MemoryScanner._Context._frameStarted and report.zIndexElementCount > 0 then
-      table.insert(report.issues, {
-        severity = "warning",
-        message = string.format("Z-index array has %d elements outside of frame", report.zIndexElementCount),
-        suggestion = "clearFrameElements() may not be called properly in beginFrame()",
-      })
-    end
-  end
-
-  -- Check for excessive element count
-  if report.topElementCount > 100 then
-    table.insert(report.issues, {
-      severity = "info",
-      message = string.format("High top-level element count: %d", report.topElementCount),
-      suggestion = "Consider consolidating elements or using fewer top-level containers",
-    })
-  end
-
-  return report
-end
-
---Scan ImageCache for memory issues
---@return table report Detailed report of ImageCache memory usage
-function MemoryScanner.scanImageCache()
-  local report = {
-    imageCount = 0,
-    estimatedMemory = 0,
-    issues = {},
-  }
-
-  if not MemoryScanner._ImageCache then
-    table.insert(report.issues, {
-      severity = "error",
-      message = "ImageCache not initialized",
-    })
-    return report
-  end
-
-  local stats = MemoryScanner._ImageCache.getStats()
-  report.imageCount = stats.count
-  report.estimatedMemory = stats.memoryEstimate
-
-  -- Check for excessive memory usage (>100MB)
-  if report.estimatedMemory > 100 * 1024 * 1024 then
-    table.insert(report.issues, {
-      severity = "warning",
-      message = string.format("ImageCache using ~%.2f MB", report.estimatedMemory / 1024 / 1024),
-      suggestion = "Consider implementing cache eviction or clearing unused images",
-    })
-  end
-
-  -- Check for excessive image count
-  if report.imageCount > 50 then
-    table.insert(report.issues, {
-      severity = "info",
-      message = string.format("ImageCache has %d images", report.imageCount),
-      suggestion = "Review if all cached images are necessary",
-    })
-  end
-
-  return report
-end
-
---Check if a circular reference is intentional (parent-child, module, or metatable)
---@param path string The current path where circular ref was detected
---@param originalPath string The original path where the table was first seen
---@return boolean True if this is an intentional circular reference
-local function isIntentionalCircularReference(path, originalPath)
-  -- Pattern 1: child.parent points back to parent
-  -- Example: "topElements.1.children.1.parent" -> "topElements.1"
-  if path:match("%.parent$") then
-    local parentPath = path:match("^(.+)%.children%.[^.]+%.parent$")
-    if parentPath == originalPath then
-      return true
-    end
-  end
-
-  -- Pattern 2: parent.children[n] points to child, child points back somewhere in parent tree
-  -- Example: "topElements.1" -> "topElements.1.children.1.parent"
-  if originalPath:match("%.parent$") then
-    local childParentPath = originalPath:match("^(.+)%.children%.[^.]+%.parent$")
-    if childParentPath == path then
-      return true
-    end
-  end
-
-  -- Pattern 3: Check for nested parent-child cycles
-  -- child.children[n].parent -> child
-  local segments = {}
-  for segment in path:gmatch("[^.]+") do
-    table.insert(segments, segment)
-  end
-
-  -- Look for .children.N.parent pattern
-  for i = 1, #segments - 2 do
-    if segments[i] == "children" and segments[i + 2] == "parent" then
-      -- Reconstruct path without the .children.N.parent suffix
-      local reconstructedPath = table.concat(segments, ".", 1, i - 1)
-      if reconstructedPath == originalPath then
-        return true
-      end
-    end
-  end
-
-  -- Pattern 4: Metatable __index self-references (modules)
-  -- Example: "element._renderer._Theme.__index" -> "element._renderer._Theme"
-  if path:match("%.__index$") then
-    local basePath = path:match("^(.+)%.__index$")
-    if basePath == originalPath then
-      return true
-    end
-  end
-
-  -- Pattern 5: Shared module references (elements sharing same module instances)
-  -- Example: Multiple elements referencing _utils, _Theme, _Blur, etc.
-  -- These start with _ and are typically modules
-  local pathModuleName = path:match("%.(_[%w]+)%.")
-  local originalModuleName = originalPath:match("%.(_[%w]+)%.")
-
-  if pathModuleName and originalModuleName then
-    -- If both paths reference the same internal module (starting with _), it's intentional
-    if pathModuleName == originalModuleName then
-      return true
-    end
-  end
-
-  -- Pattern 6: Shared Color/Transform objects between elements
-  -- These are value objects that can be safely shared
-  if path:match("Color") and originalPath:match("Color") then
-    return true
-  end
-  if path:match("Transform") and originalPath:match("Transform") then
-    return true
-  end
-
-  -- Pattern 7: LayoutEngine holding reference to its element
-  -- Example: "element._layoutEngine.element" -> "element"
-  if path:match("%._layoutEngine%.element$") then
-    local elementPath = path:match("^(.+)%._layoutEngine%.element$")
-    if elementPath == originalPath then
-      return true
-    end
-  end
-
-  -- Pattern 8: Renderer holding references to element properties
-  -- Example: "element._renderer.cornerRadius" -> "element.cornerRadius"
-  if path:match("%._renderer%.") then
-    local rendererBasePath = path:match("^(.+)%._renderer%.")
-    local originalBasePath = originalPath:match("^(.+)%.")
-    if rendererBasePath == originalBasePath then
-      return true
-    end
-  end
-
-  -- Pattern 9: Context reference from layout engine (shared singleton)
-  -- Example: "element._layoutEngine._Context.topElements" -> "topElements"
-  if path:match("%._layoutEngine%._Context%.") and originalPath == "topElements" then
-    return true
-  end
-
-  return false
-end
-
---Detect circular references in a table
---@param tbl table Table to check
---@param path string? Current path (for reporting)
---@param visited table? Tracking table
---@return table[] circularRefs Array of circular reference paths
---@return table[] intentionalRefs Array of intentional parent-child refs
-local function detectCircularReferences(tbl, path, visited)
-  if type(tbl) ~= "table" then
-    return {}, {}
-  end
-
-  path = path or "root"
-  visited = visited or {}
-  local circularRefs = {}
-  local intentionalRefs = {}
-
-  -- Check if we've seen this table before
-  if visited[tbl] then
-    local ref = {
-      path = path,
-      originalPath = visited[tbl],
-    }
-
-    -- Determine if this is an intentional circular reference
-    if isIntentionalCircularReference(path, visited[tbl]) then
-      table.insert(intentionalRefs, ref)
-    else
-      table.insert(circularRefs, ref)
-    end
-
-    return circularRefs, intentionalRefs
-  end
-
-  -- Mark as visited
-  visited[tbl] = path
-
-  -- Recursively check children
-  for k, v in pairs(tbl) do
-    if type(v) == "table" then
-      local childPath = path .. "." .. tostring(k)
-      local childRefs, childIntentionalRefs = detectCircularReferences(v, childPath, visited)
-      for _, ref in ipairs(childRefs) do
-        table.insert(circularRefs, ref)
-      end
-      for _, ref in ipairs(childIntentionalRefs) do
-        table.insert(intentionalRefs, ref)
-      end
-    end
-  end
-
-  return circularRefs, intentionalRefs
-end
-
---Scan for circular references in immediate mode
---@return table report Detailed report of circular references
-function MemoryScanner.scanCircularReferences()
-  local report = {
-    stateStoreCircularRefs = {},
-    stateStoreIntentionalRefs = {},
-    contextCircularRefs = {},
-    contextIntentionalRefs = {},
-    issues = {},
-  }
-
-  if MemoryScanner._StateManager then
-    local internal = MemoryScanner._StateManager._getInternalState()
-    report.stateStoreCircularRefs, report.stateStoreIntentionalRefs =
-      detectCircularReferences(internal.stateStore, "stateStore")
-  end
-
-  if MemoryScanner._Context then
-    report.contextCircularRefs, report.contextIntentionalRefs =
-      detectCircularReferences(MemoryScanner._Context.topElements, "topElements")
-  end
-
-  -- Report issues only for cross-module circular references
-  if #report.stateStoreCircularRefs > 0 then
-    table.insert(report.issues, {
-      severity = "info",
-      message = string.format(
-        "Found %d cross-module circular references in StateManager",
-        #report.stateStoreCircularRefs
-      ),
-      suggestion = "These are typically architectural dependencies between modules, not memory leaks",
-    })
-  end
-
-  if #report.contextCircularRefs > 0 then
-    table.insert(report.issues, {
-      severity = "info",
-      message = string.format("Found %d cross-module circular references in Context", #report.contextCircularRefs),
-      suggestion = "These are typically architectural dependencies (e.g., layout engine ↔ renderer), not memory leaks",
-    })
-  end
-
-  return report
-end
-
---Run comprehensive memory scan
---@return table report Complete memory analysis report
-function MemoryScanner.scan()
-  local startMemory = collectgarbage("count")
-
-  local report = {
-    timestamp = os.time(),
-    startMemory = startMemory / 1024, -- MB
-    stateManager = MemoryScanner.scanStateManager(),
-    context = MemoryScanner.scanContext(),
-    imageCache = MemoryScanner.scanImageCache(),
-    circularRefs = MemoryScanner.scanCircularReferences(),
-    summary = {
-      totalIssues = 0,
-      criticalIssues = 0,
-      warnings = 0,
-      info = 0,
-    },
-  }
-
-  -- Count issues by severity
-  local function countIssues(subReport)
-    for _, issue in ipairs(subReport.issues or {}) do
-      report.summary.totalIssues = report.summary.totalIssues + 1
-      if issue.severity == "error" then
-        report.summary.criticalIssues = report.summary.criticalIssues + 1
-      elseif issue.severity == "warning" then
-        report.summary.warnings = report.summary.warnings + 1
-      elseif issue.severity == "info" then
-        report.summary.info = report.summary.info + 1
-      end
-    end
-  end
-
-  countIssues(report.stateManager)
-  countIssues(report.context)
-  countIssues(report.imageCache)
-  countIssues(report.circularRefs)
-
-  -- Force GC and measure freed memory
-  local beforeGC = collectgarbage("count")
-  collectgarbage("collect")
-  collectgarbage("collect")
-  local afterGC = collectgarbage("count")
-
-  report.gcAnalysis = {
-    beforeGC = beforeGC / 1024, -- MB
-    afterGC = afterGC / 1024, -- MB
-    freed = (beforeGC - afterGC) / 1024, -- MB
-    freedPercent = ((beforeGC - afterGC) / beforeGC) * 100,
-  }
-
-  -- Analyze GC effectiveness
-  if report.gcAnalysis.freedPercent < 5 then
-    table.insert(report.stateManager.issues, {
-      severity = "info",
-      message = string.format("GC freed only %.1f%% of memory", report.gcAnalysis.freedPercent),
-      suggestion = "Most memory is still referenced - this is normal if UI is active",
-    })
-  elseif report.gcAnalysis.freedPercent > 30 then
-    table.insert(report.stateManager.issues, {
-      severity = "warning",
-      message = string.format("GC freed %.1f%% of memory", report.gcAnalysis.freedPercent),
-      suggestion = "Significant memory was unreferenced - may indicate cleanup issues",
-    })
-  end
-
-  return report
-end
-
---Format report as human-readable string
---@param report table Memory scan report
---@return string formatted Formatted report
-function MemoryScanner.formatReport(report)
-  local lines = {}
-
-  table.insert(lines, "=== FlexLöve Memory Scanner Report ===")
-  table.insert(lines, string.format("Timestamp: %s", os.date("%Y-%m-%d %H:%M:%S", report.timestamp)))
-  table.insert(lines, string.format("Memory: %.2f MB", report.startMemory))
-  table.insert(lines, "")
-
-  -- Summary
-  table.insert(lines, "--- Summary ---")
-  table.insert(lines, string.format("Total Issues: %d", report.summary.totalIssues))
-  table.insert(lines, string.format("  Critical: %d", report.summary.criticalIssues))
-  table.insert(lines, string.format("  Warnings: %d", report.summary.warnings))
-  table.insert(lines, string.format("  Info: %d", report.summary.info))
-  table.insert(lines, "")
-
-  -- StateManager
-  table.insert(lines, "--- StateManager ---")
-  table.insert(lines, string.format("State Count: %d", report.stateManager.stateCount))
-  table.insert(lines, string.format("State Store Size: %.2f KB", report.stateManager.stateStoreSize / 1024))
-  table.insert(lines, string.format("Metadata Size: %.2f KB", report.stateManager.metadataSize / 1024))
-  table.insert(lines, string.format("CallSite Counters: %.2f KB", report.stateManager.callSiteCounterSize / 1024))
-  table.insert(lines, string.format("Orphaned States: %d", #report.stateManager.orphanedStates))
-  table.insert(lines, string.format("Stale States: %d", #report.stateManager.staleStates))
-  table.insert(lines, string.format("Large States: %d", #report.stateManager.largeStates))
-
-  if #report.stateManager.issues > 0 then
-    table.insert(lines, "Issues:")
-    for _, issue in ipairs(report.stateManager.issues) do
-      table.insert(lines, string.format("  [%s] %s", string.upper(issue.severity), issue.message))
-      if issue.suggestion then
-        table.insert(lines, string.format("    → %s", issue.suggestion))
-      end
-    end
-  end
-  table.insert(lines, "")
-
-  -- Context
-  table.insert(lines, "--- Context ---")
-  table.insert(lines, string.format("Top Elements: %d", report.context.topElementCount))
-  table.insert(lines, string.format("Z-Index Elements: %d", report.context.zIndexElementCount))
-  table.insert(lines, string.format("Frame Elements: %d", report.context.frameElementCount))
-
-  if #report.context.issues > 0 then
-    table.insert(lines, "Issues:")
-    for _, issue in ipairs(report.context.issues) do
-      table.insert(lines, string.format("  [%s] %s", string.upper(issue.severity), issue.message))
-      if issue.suggestion then
-        table.insert(lines, string.format("    → %s", issue.suggestion))
-      end
-    end
-  end
-  table.insert(lines, "")
-
-  -- ImageCache
-  table.insert(lines, "--- ImageCache ---")
-  table.insert(lines, string.format("Image Count: %d", report.imageCache.imageCount))
-  table.insert(lines, string.format("Estimated Memory: %.2f MB", report.imageCache.estimatedMemory / 1024 / 1024))
-
-  if #report.imageCache.issues > 0 then
-    table.insert(lines, "Issues:")
-    for _, issue in ipairs(report.imageCache.issues) do
-      table.insert(lines, string.format("  [%s] %s", string.upper(issue.severity), issue.message))
-      if issue.suggestion then
-        table.insert(lines, string.format("    → %s", issue.suggestion))
-      end
-    end
-  end
-  table.insert(lines, "")
-
-  -- Circular References
-  table.insert(lines, "--- Circular References ---")
-  table.insert(lines, string.format("StateStore (Cross-module refs): %d", #report.circularRefs.stateStoreCircularRefs))
-  table.insert(
-    lines,
-    string.format(
-      "StateStore (Intentional - parent-child, modules, metatables): %d",
-      #report.circularRefs.stateStoreIntentionalRefs
-    )
-  )
-  table.insert(lines, string.format("Context (Cross-module refs): %d", #report.circularRefs.contextCircularRefs))
-  table.insert(
-    lines,
-    string.format(
-      "Context (Intentional - parent-child, modules, metatables): %d",
-      #report.circularRefs.contextIntentionalRefs
-    )
-  )
-
-  if #report.circularRefs.issues > 0 then
-    table.insert(lines, "Issues:")
-    for _, issue in ipairs(report.circularRefs.issues) do
-      table.insert(lines, string.format("  [%s] %s", string.upper(issue.severity), issue.message))
-      if issue.suggestion then
-        table.insert(lines, string.format("    → %s", issue.suggestion))
-      end
-    end
-  else
-    table.insert(lines, "  ✓ No unexpected circular references detected")
-  end
-  table.insert(lines, "  Note: Cross-module refs are typically architectural dependencies, not memory leaks")
-  table.insert(lines, "")
-
-  -- GC Analysis
-  table.insert(lines, "--- Garbage Collection Analysis ---")
-  table.insert(lines, string.format("Before GC: %.2f MB", report.gcAnalysis.beforeGC))
-  table.insert(lines, string.format("After GC: %.2f MB", report.gcAnalysis.afterGC))
-  table.insert(lines, string.format("Freed: %.2f MB (%.1f%%)", report.gcAnalysis.freed, report.gcAnalysis.freedPercent))
-  table.insert(lines, "")
-
-  table.insert(lines, "=== End Report ===")
-
-  return table.concat(lines, "\n")
-end
-
---Save report to file
---@param report table Memory scan report
---@param filename string? Output filename (default: memory_report.txt)
-function MemoryScanner.saveReport(report, filename)
-  filename = filename or "memory_report.txt"
-  local formatted = MemoryScanner.formatReport(report)
-
-  local file = io.open(filename, "w")
-  if file then
-    file:write(formatted)
-    file:close()
-    if MemoryScanner._ErrorHandler then
-      MemoryScanner._ErrorHandler:warn("MemoryScanner", "RES_004", {
-        resourceType = "report",
-        path = filename,
-        status = "saved",
-      })
-    end
-  else
-    if MemoryScanner._ErrorHandler then
-      MemoryScanner._ErrorHandler:warn("MemoryScanner", "RES_004", {
-        resourceType = "report",
-        path = filename,
-        status = "failed to save",
-      })
-    end
-  end
-end
-
-return MemoryScanner
@@ -1,202 +0,0 @@
---@class ModuleLoader
-local ModuleLoader = {}
-
-- Module registry to track loaded vs. stub modules
-ModuleLoader._registry = {}
-ModuleLoader._ErrorHandler = nil
-
--- Initialize ModuleLoader with dependencies
---@param deps table
-function ModuleLoader.init(deps)
-  ModuleLoader._ErrorHandler = deps.ErrorHandler
-end
-
--- Create a null-object stub for a missing optional module
--- Provides safe defaults that won't cause runtime errors
---@param moduleName string
---@return table
-local function createNullObject(moduleName)
-  local stub = {
-    _isStub = true,
-    _moduleName = moduleName,
-  }
-
-  -- Common method stubs that return safe defaults
-  local metatable = {
-    __index = function(_, key)
-      -- Common initialization method
-      if key == "init" then
-        return function()
-          return stub
-        end
-      end
-
-      -- Common constructor method
-      if key == "new" then
-        return function()
-          return stub
-        end
-      end
-
-      -- Common draw method
-      if key == "draw" then
-        return function() end
-      end
-
-      -- Common update method
-      if key == "update" then
-        return function() end
-      end
-
-      -- Common render method
-      if key == "render" then
-        return function() end
-      end
-
-      -- Common cleanup method
-      if key == "destroy" then
-        return function() end
-      end
-
-      -- Common cleanup method
-      if key == "cleanup" then
-        return function() end
-      end
-
-      -- Common clear method
-      if key == "clear" then
-        return function() end
-      end
-
-      -- Common reset method
-      if key == "reset" then
-        return function() end
-      end
-
-      -- Common get method
-      if key == "get" then
-        return function()
-          return nil
-        end
-      end
-
-      -- Common set method
-      if key == "set" then
-        return function() end
-      end
-
-      -- Common load method
-      if key == "load" then
-        return function()
-          return stub
-        end
-      end
-
-      -- Common cache-related methods
-      if key == "cache" or key == "getCache" or key == "clearCache" then
-        return function()
-          return {}
-        end
-      end
-
-      -- For any unknown method, return a no-op function that accepts any arguments
-      -- This allows safe method calls on stub objects (e.g., Performance:startFrame())
-      return function()
-        return stub
-      end
-    end,
-
-    -- Make function calls safe (in case the stub itself is called)
-    __call = function()
-      return stub
-    end,
-  }
-
-  setmetatable(stub, metatable)
-  return stub
-end
-
--- Safely require a module with graceful fallback for optional modules
--- Returns the module if it exists, or a null-object stub if it's optional and missing
--- Throws an error if a required module is missing
---@param modulePath string Full path to the module (e.g., "modules.Performance")
---@param isOptional boolean If true, returns null-object on failure; if false, throws error
---@return table module The loaded module or a null-object stub
-function ModuleLoader.safeRequire(modulePath, isOptional)
-  -- Check if already loaded
-  if ModuleLoader._registry[modulePath] then
-    return ModuleLoader._registry[modulePath]
-  end
-
-  -- Attempt to load the module
-  local success, result = pcall(require, modulePath)
-
-  if success then
-    -- Module loaded successfully
-    ModuleLoader._registry[modulePath] = result
-    return result
-  else
-    -- Module failed to load
-    if isOptional then
-      -- Create null-object stub for optional module
-      local stub = createNullObject(modulePath)
-      ModuleLoader._registry[modulePath] = stub
-
-      -- Log warning about missing optional module
-      if ModuleLoader._ErrorHandler then
-        ModuleLoader._ErrorHandler:warn("ModuleLoader", "MOD_001", {
-          modulePath = modulePath,
-        })
-      end
-
-      return stub
-    else
-      -- Required module is missing - throw error
-      error(string.format("Required module '%s' not found: %s", modulePath, tostring(result)))
-    end
-  end
-end
-
--- Check if a module is actually loaded (not a stub)
---@param modulePath string Full path to the module
---@return boolean isLoaded True if module is loaded, false if it's a stub or not loaded
-function ModuleLoader.isModuleLoaded(modulePath)
-  local module = ModuleLoader._registry[modulePath]
-  if not module then
-    return false
-  end
-
-  -- Check if it's a stub
-  return not module._isStub
-end
-
--- Get list of all loaded modules
---@return table modules List of module paths that are actually loaded (not stubs)
-function ModuleLoader.getLoadedModules()
-  local loaded = {}
-  for path, module in pairs(ModuleLoader._registry) do
-    if not module._isStub then
-      table.insert(loaded, path)
-    end
-  end
-  return loaded
-end
-
--- Get list of all stub modules
---@return table stubs List of module paths that are stubs
-function ModuleLoader.getStubModules()
-  local stubs = {}
-  for path, module in pairs(ModuleLoader._registry) do
-    if module._isStub then
-      table.insert(stubs, path)
-    end
-  end
-  return stubs
-end
-
--- Clear the module registry (useful for testing)
-function ModuleLoader._clearRegistry()
-  ModuleLoader._registry = {}
-end
-
-return ModuleLoader
@@ -1,217 +0,0 @@
-local modulePath = (...):match("(.-)[^%.]+$")
-local ImageScaler = require(modulePath .. "ImageScaler")
-
-local NinePatch = {}
-
-- ErrorHandler will be injected via init
-local ErrorHandler = nil
-
--- Initialize NinePatch with dependencies
---@param deps table Dependencies table with ErrorHandler
-function NinePatch.init(deps)
-  if deps and deps.ErrorHandler then
-    ErrorHandler = deps.ErrorHandler
-  end
-  -- Also initialize ImageScaler since it's a dependency
-  if ImageScaler.init then
-    ImageScaler.init(deps)
-  end
-end
-
--- Draw a 9-patch component using Android-style rendering
--- Corners are scaled by scaleCorners multiplier, edges stretch in one dimension only
---@param component ThemeComponent
---@param atlas love.Image
---@param x number -- X position (top-left corner)
---@param y number -- Y position (top-left corner)
---@param width number -- Total width (border-box)
---@param height number -- Total height (border-box)
---@param opacity number?
---@param elementScaleCorners number? -- Element-level override for scaleCorners (scale multiplier)
---@param elementScalingAlgorithm "nearest"|"bilinear"? -- Element-level override for scalingAlgorithm
-function NinePatch.draw(component, atlas, x, y, width, height, opacity, elementScaleCorners, elementScalingAlgorithm)
-  if not component or not atlas then
-    return
-  end
-
-  opacity = opacity or 1
-  love.graphics.setColor(1, 1, 1, opacity)
-
-  local regions = component.regions
-
-  -- Extract border dimensions from regions (in pixels)
-  local left = regions.topLeft.w
-  local right = regions.topRight.w
-  local top = regions.topLeft.h
-  local bottom = regions.bottomLeft.h
-  local centerW = regions.middleCenter.w
-  local centerH = regions.middleCenter.h
-
-  -- Calculate content area (space remaining after borders)
-  local contentWidth = width - left - right
-  local contentHeight = height - top - bottom
-
-  -- Clamp to prevent negative dimensions
-  contentWidth = math.max(0, contentWidth)
-  contentHeight = math.max(0, contentHeight)
-
-  -- Calculate stretch scales for edges and center
-  local scaleX = contentWidth / centerW
-  local scaleY = contentHeight / centerH
-
-  -- Create quads for each region
-  local atlasWidth, atlasHeight = atlas:getDimensions()
-
-  local function makeQuad(region)
-    return love.graphics.newQuad(region.x, region.y, region.w, region.h, atlasWidth, atlasHeight)
-  end
-
-  -- Get corner scale multiplier
-  -- Priority: element-level override > component setting > default (nil = no scaling)
-  local scaleCorners = elementScaleCorners
-  if scaleCorners == nil then
-    scaleCorners = component.scaleCorners
-  end
-
-  -- Priority: element-level override > component setting > default ("bilinear")
-  local scalingAlgorithm = elementScalingAlgorithm
-  if scalingAlgorithm == nil then
-    scalingAlgorithm = component.scalingAlgorithm or "bilinear"
-  end
-
-  if scaleCorners and type(scaleCorners) == "number" and scaleCorners > 0 then
-    -- Initialize cache if needed
-    if not component._scaledRegionCache then
-      component._scaledRegionCache = {}
-    end
-
-    -- Use the numeric scale multiplier directly
-    local scaleFactor = scaleCorners
-
-    -- Helper to get or create scaled region
-    local function getScaledRegion(regionName, region, targetWidth, targetHeight)
-      local cacheKey = string.format("%s_%.2f_%s", regionName, scaleFactor, scalingAlgorithm)
-
-      if component._scaledRegionCache[cacheKey] then
-        return component._scaledRegionCache[cacheKey]
-      end
-
-      -- Get ImageData from component (stored during theme loading)
-      local atlasData = component._loadedAtlasData
-      if not atlasData then
-        ErrorHandler.error(
-          "NinePatch",
-          "REN_007",
-          "No ImageData available for atlas. Image must be loaded with safeLoadImage.",
-          {
-            componentType = component.type,
-          }
-        )
-      end
-
-      local scaledData
-
-      if scalingAlgorithm == "nearest" then
-        scaledData =
-          ImageScaler.scaleNearest(atlasData, region.x, region.y, region.w, region.h, targetWidth, targetHeight)
-      else
-        scaledData =
-          ImageScaler.scaleBilinear(atlasData, region.x, region.y, region.w, region.h, targetWidth, targetHeight)
-      end
-
-      -- Convert to image and cache
-      local scaledImage = love.graphics.newImage(scaledData)
-      component._scaledRegionCache[cacheKey] = scaledImage
-
-      return scaledImage
-    end
-
-    -- Calculate scaled dimensions for corners
-    local scaledLeft = math.floor(left * scaleFactor + 0.5)
-    local scaledRight = math.floor(right * scaleFactor + 0.5)
-    local scaledTop = math.floor(top * scaleFactor + 0.5)
-    local scaledBottom = math.floor(bottom * scaleFactor + 0.5)
-
-    -- CORNERS (scaled using algorithm)
-    local topLeftScaled = getScaledRegion("topLeft", regions.topLeft, scaledLeft, scaledTop)
-    local topRightScaled = getScaledRegion("topRight", regions.topRight, scaledRight, scaledTop)
-    local bottomLeftScaled = getScaledRegion("bottomLeft", regions.bottomLeft, scaledLeft, scaledBottom)
-    local bottomRightScaled = getScaledRegion("bottomRight", regions.bottomRight, scaledRight, scaledBottom)
-
-    love.graphics.draw(topLeftScaled, x, y)
-    love.graphics.draw(topRightScaled, x + width - scaledRight, y)
-    love.graphics.draw(bottomLeftScaled, x, y + height - scaledBottom)
-    love.graphics.draw(bottomRightScaled, x + width - scaledRight, y + height - scaledBottom)
-
-    -- Update content dimensions to account for scaled borders
-    local adjustedContentWidth = width - scaledLeft - scaledRight
-    local adjustedContentHeight = height - scaledTop - scaledBottom
-    adjustedContentWidth = math.max(0, adjustedContentWidth)
-    adjustedContentHeight = math.max(0, adjustedContentHeight)
-
-    -- Recalculate stretch scales
-    local adjustedScaleX = adjustedContentWidth / centerW
-    local adjustedScaleY = adjustedContentHeight / centerH
-
-    -- TOP/BOTTOM EDGES (stretch horizontally, scale vertically)
-    if adjustedContentWidth > 0 then
-      local topCenterScaled = getScaledRegion("topCenter", regions.topCenter, regions.topCenter.w, scaledTop)
-      local bottomCenterScaled =
-        getScaledRegion("bottomCenter", regions.bottomCenter, regions.bottomCenter.w, scaledBottom)
-
-      love.graphics.draw(topCenterScaled, x + scaledLeft, y, 0, adjustedScaleX, 1)
-      love.graphics.draw(bottomCenterScaled, x + scaledLeft, y + height - scaledBottom, 0, adjustedScaleX, 1)
-    end
-
-    -- LEFT/RIGHT EDGES (stretch vertically, scale horizontally)
-    if adjustedContentHeight > 0 then
-      local middleLeftScaled = getScaledRegion("middleLeft", regions.middleLeft, scaledLeft, regions.middleLeft.h)
-      local middleRightScaled = getScaledRegion("middleRight", regions.middleRight, scaledRight, regions.middleRight.h)
-
-      love.graphics.draw(middleLeftScaled, x, y + scaledTop, 0, 1, adjustedScaleY)
-      love.graphics.draw(middleRightScaled, x + width - scaledRight, y + scaledTop, 0, 1, adjustedScaleY)
-    end
-
-    -- CENTER (stretch both dimensions, no scaling)
-    if adjustedContentWidth > 0 and adjustedContentHeight > 0 then
-      love.graphics.draw(
-        atlas,
-        makeQuad(regions.middleCenter),
-        x + scaledLeft,
-        y + scaledTop,
-        0,
-        adjustedScaleX,
-        adjustedScaleY
-      )
-    end
-  else
-    -- Original rendering logic (no scaling)
-    -- CORNERS (no scaling - 1:1 pixel perfect)
-    love.graphics.draw(atlas, makeQuad(regions.topLeft), x, y)
-    love.graphics.draw(atlas, makeQuad(regions.topRight), x + left + contentWidth, y)
-    love.graphics.draw(atlas, makeQuad(regions.bottomLeft), x, y + top + contentHeight)
-    love.graphics.draw(atlas, makeQuad(regions.bottomRight), x + left + contentWidth, y + top + contentHeight)
-
-    -- TOP/BOTTOM EDGES (stretch horizontally only)
-    if contentWidth > 0 then
-      love.graphics.draw(atlas, makeQuad(regions.topCenter), x + left, y, 0, scaleX, 1)
-      love.graphics.draw(atlas, makeQuad(regions.bottomCenter), x + left, y + top + contentHeight, 0, scaleX, 1)
-    end
-
-    -- LEFT/RIGHT EDGES (stretch vertically only)
-    if contentHeight > 0 then
-      love.graphics.draw(atlas, makeQuad(regions.middleLeft), x, y + top, 0, 1, scaleY)
-      love.graphics.draw(atlas, makeQuad(regions.middleRight), x + left + contentWidth, y + top, 0, 1, scaleY)
-    end
-
-    -- CENTER (stretch both dimensions)
-    if contentWidth > 0 and contentHeight > 0 then
-      love.graphics.draw(atlas, makeQuad(regions.middleCenter), x + left, y + top, 0, scaleX, scaleY)
-    end
-  end
-
-  -- Reset color
-  love.graphics.setColor(1, 1, 1, 1)
-end
-
-return NinePatch
@@ -1,351 +0,0 @@
-local modulePath = (...):match("(.-)[^%.]+$")
-local function req(name)
-  return require(modulePath .. name)
-end
-
-- All numeric, range, type, and enum validation lives here.
-- `clamp` is injected via init() to avoid a cross-import into utils.
-- `ErrorHandler` is injected via init() so error reporting routes through
-- the shared handler (matching the pre-split behavior of utils.validate*).
-
-local ErrorHandler = nil
-local clamp = nil
-
--- Initialize dependencies
---@param deps table Dependencies: { ErrorHandler = table, clamp = function }
-local function init(deps)
-  if type(deps) == "table" then
-    ErrorHandler = deps.ErrorHandler or ErrorHandler
-    clamp = deps.clamp or clamp
-  end
-end
-
-- Numeric validation utilities
-
--- Check if a value is NaN (not-a-number)
--- @param value any Value to check
--- @return boolean
-local function isNaN(value)
-  return type(value) == "number" and value ~= value
-end
-
--- Check if a value is Infinity
--- @param value any Value to check
--- @return boolean
-local function isInfinity(value)
-  return type(value) == "number" and (value == math.huge or value == -math.huge)
-end
-
--- Validate a numeric value with comprehensive checks
--- @param value any Value to validate
--- @param options table? Validation options
--- @return boolean, string?, number? Returns valid, errorMessage, sanitizedValue
-local function validateNumber(value, options)
-  options = options or {}
-
-  -- Check if value is a number type
-  if type(value) ~= "number" then
-    if options.default ~= nil then
-      return true, nil, options.default
-    end
-    return false, string.format("Value must be a number, got %s", type(value)), nil
-  end
-
-  -- Check for NaN
-  if isNaN(value) then
-    if not options.allowNaN then
-      if options.default ~= nil then
-        return true, nil, options.default
-      end
-      return false, "Value is NaN (not-a-number)", nil
-    end
-  end
-
-  -- Check for Infinity
-  if isInfinity(value) then
-    if not options.allowInfinity then
-      if options.default ~= nil then
-        return true, nil, options.default
-      end
-      return false, "Value is Infinity", nil
-    end
-  end
-
-  -- Check for integer requirement
-  if options.integer and math.floor(value) ~= value then
-    return false, string.format("Value must be an integer, got %s", value), nil
-  end
-
-  -- Check for positive requirement
-  if options.positive and value <= 0 then
-    return false, string.format("Value must be positive, got %s", value), nil
-  end
-
-  -- Check bounds
-  if options.min and value < options.min then
-    return false, string.format("Value %s is below minimum %s", value, options.min), nil
-  end
-
-  if options.max and value > options.max then
-    return false, string.format("Value %s is above maximum %s", value, options.max), nil
-  end
-
-  return true, nil, value
-end
-
--- Sanitize a numeric value (never errors, always returns valid number)
--- @param value any Value to sanitize
--- @param min number? Minimum value
--- @param max number? Maximum value
--- @param default number? Default value for invalid inputs
--- @return number Sanitized value
-local function sanitizeNumber(value, min, max, default)
-  default = default or 0
-  min = min or -math.huge
-  max = max or math.huge
-
-  -- Convert to number if possible
-  if type(value) == "string" then
-    value = tonumber(value)
-  end
-
-  -- Handle non-numeric
-  if type(value) ~= "number" then
-    return default
-  end
-
-  -- Handle NaN
-  if isNaN(value) then
-    return default
-  end
-
-  -- Handle Infinity
-  if value == math.huge then
-    return max
-  end
-  if value == -math.huge then
-    return min
-  end
-
-  -- Clamp to range
-  return clamp(value, min, max)
-end
-
--- Validate and convert to integer
--- @param value any Value to validate
--- @param min number? Minimum value
--- @param max number? Maximum value
--- @return boolean, string?, number? Returns valid, errorMessage, integerValue
-local function validateInteger(value, min, max)
-  local valid, err, sanitized = validateNumber(value, {
-    min = min,
-    max = max,
-    integer = true,
-  })
-
-  if not valid then
-    return false, err, nil
-  end
-
-  return true, nil, math.floor(sanitized or value)
-end
-
--- Validate and normalize percentage value
--- @param value any Value to validate (can be "50%", 0.5, or 50)
--- @return boolean, string?, number? Returns valid, errorMessage, normalizedValue (0-1)
-local function validatePercentage(value)
-  -- Handle string percentage
-  if type(value) == "string" then
-    local num = value:match("^(%d+%.?%d*)%%$")
-    if num then
-      value = tonumber(num)
-      if value then
-        value = value / 100
-      end
-    else
-      value = tonumber(value)
-    end
-  end
-
-  if type(value) ~= "number" then
-    return false, "Percentage must be a number", nil
-  end
-
-  if isNaN(value) or isInfinity(value) then
-    return false, "Percentage cannot be NaN or Infinity", nil
-  end
-
-  -- If value is > 1, assume it's 0-100 range
-  if value > 1 then
-    value = value / 100
-  end
-
-  -- Clamp to 0-1
-  value = clamp(value, 0, 1)
-
-  return true, nil, value
-end
-
--- Validate opacity value (0-1)
--- @param value any Value to validate
--- @return boolean, string?, number? Returns valid, errorMessage, opacityValue
-local function validateOpacity(value)
-  return validateNumber(value, { min = 0, max = 1, default = 1 })
-end
-
--- Validate degree value (0-360)
--- @param value any Value to validate
--- @return boolean, string?, number? Returns valid, errorMessage, degreeValue
-local function validateDegrees(value)
-  local valid, err, sanitized = validateNumber(value)
-  if not valid then
-    return false, err, nil
-  end
-
-  -- Normalize to 0-360 range
-  local degrees = sanitized or value
-  degrees = degrees % 360
-  if degrees < 0 then
-    degrees = degrees + 360
-  end
-
-  return true, nil, degrees
-end
-
--- Validate coordinate value (pixel position)
--- @param value any Value to validate
--- @return boolean, string?, number? Returns valid, errorMessage, coordinateValue
-local function validateCoordinate(value)
-  return validateNumber(value, {
-    allowNaN = false,
-    allowInfinity = false,
-  })
-end
-
--- Validate dimension value (width/height, must be non-negative)
--- @param value any Value to validate
--- @return boolean, string?, number? Returns valid, errorMessage, dimensionValue
-local function validateDimension(value)
-  return validateNumber(value, {
-    min = 0,
-    allowNaN = false,
-    allowInfinity = false,
-  })
-end
-
--- Validate that a value is in an enum table
---@param value any Value to validate
---@param enumTable table Enum table with valid values
---@param propName string Property name for error messages
---@param moduleName string? Module name for error messages (default: "Element")
---@return boolean True if valid
-local function validateEnum(value, enumTable, propName, moduleName)
-  if value == nil then
-    return true
-  end
-
-  for _, validValue in pairs(enumTable) do
-    if value == validValue then
-      return true
-    end
-  end
-
-  -- Build list of valid options
-  local validOptions = {}
-  for _, v in pairs(enumTable) do
-    table.insert(validOptions, "'" .. v .. "'")
-  end
-  table.sort(validOptions)
-
-  if ErrorHandler then
-    ErrorHandler:error(moduleName or "Element", "VAL_007", {
-      property = propName,
-      expected = table.concat(validOptions, ", "),
-      got = tostring(value),
-    })
-  else
-    error(
-      string.format("%s must be one of: %s. Got: '%s'", propName, table.concat(validOptions, ", "), tostring(value))
-    )
-  end
-end
-
--- Validate that a numeric value is within a range
---@param value any Value to validate
---@param min number Minimum allowed value
---@param max number Maximum allowed value
---@param propName string Property name for error messages
---@param moduleName string? Module name for error messages (default: "Element")
---@return boolean True if valid
-local function validateRange(value, min, max, propName, moduleName)
-  if value == nil then
-    return true
-  end
-  if type(value) ~= "number" then
-    if ErrorHandler then
-      ErrorHandler:error(moduleName or "Element", "VAL_001", {
-        property = propName,
-        expected = "number",
-        got = type(value),
-      })
-    else
-      error(string.format("%s must be a number, got %s", propName, type(value)))
-    end
-  elseif value < min or value > max then
-    if ErrorHandler then
-      ErrorHandler:error(moduleName or "Element", "VAL_002", {
-        property = propName,
-        min = tostring(min),
-        max = tostring(max),
-        value = tostring(value),
-      })
-    else
-      error(
-        string.format("%s must be between %s and %s, got %s", propName, tostring(min), tostring(max), tostring(value))
-      )
-    end
-  end
-  return true
-end
-
--- Validate that a value is of the expected type
---@param value any Value to validate
---@param expectedType string Expected type name
---@param propName string Property name for error messages
---@param moduleName string? Module name for error messages (default: "Element")
---@return boolean True if valid
-local function validateType(value, expectedType, propName, moduleName)
-  if value == nil then
-    return true
-  end
-  local actualType = type(value)
-  if actualType ~= expectedType then
-    if ErrorHandler then
-      ErrorHandler:error(moduleName or "Element", "VAL_001", {
-        property = propName,
-        expected = expectedType,
-        got = actualType,
-      })
-    else
-      error(string.format("%s must be %s, got %s", propName, expectedType, actualType))
-    end
-  end
-  return true
-end
-
-return {
-  init = init,
-  isNaN = isNaN,
-  isInfinity = isInfinity,
-  validateNumber = validateNumber,
-  sanitizeNumber = sanitizeNumber,
-  validateInteger = validateInteger,
-  validatePercentage = validatePercentage,
-  validateOpacity = validateOpacity,
-  validateDegrees = validateDegrees,
-  validateCoordinate = validateCoordinate,
-  validateDimension = validateDimension,
-  validateEnum = validateEnum,
-  validateRange = validateRange,
-  validateType = validateType,
-}
@@ -1,198 +0,0 @@
-local modulePath = (...):match("(.-)[^%.]+$")
-local function req(name)
-  return require(modulePath .. name)
-end
-
-- Path sanitization, validation, and file-extension helpers.
-- Uses love.filesystem when available (optional) for existence checks.
-
--- Normalize a file path for consistent cache keys
---@param path string File path to normalize
---@return string Normalized path
-local function normalizePath(path)
-  path = path:match("^%s*(.-)%s*$")
-  path = path:gsub("\\", "/")
-  path = path:gsub("/+", "/")
-  return path
-end
-
--- Sanitize a file path
--- @param path string Path to sanitize
--- @return string Sanitized path
-local function sanitizePath(path)
-  if path == nil then
-    return ""
-  end
-  path = tostring(path)
-
-  -- Trim whitespace
-  path = path:match("^%s*(.-)%s*$") or ""
-
-  -- Normalize separators to forward slash
-  path = path:gsub("\\", "/")
-
-  -- Remove duplicate slashes
-  path = path:gsub("/+", "/")
-
-  -- Remove trailing slash (except for root)
-  if #path > 1 and path:sub(-1) == "/" then
-    path = path:sub(1, -2)
-  end
-
-  return path
-end
-
--- Check if a path is safe (no traversal attacks)
--- @param path string Path to check
--- @param baseDir string? Base directory to check against (optional)
--- @return boolean, string? Returns true if safe, or false with reason
-local function isPathSafe(path, baseDir)
-  if path == nil or path == "" then
-    return false, "Path is empty"
-  end
-
-  -- Sanitize the path
-  path = sanitizePath(path)
-
-  -- Check for suspicious patterns
-  if path:match("%.%.") then
-    return false, "Path contains '..' (parent directory reference)"
-  end
-
-  -- Check for null bytes
-  if path:match("%z") then
-    return false, "Path contains null bytes"
-  end
-
-  -- Check for encoded traversal attempts (including double-encoding)
-  local lowerPath = path:lower()
-  if
-    lowerPath:match("%%2e")
-    or lowerPath:match("%%2f")
-    or lowerPath:match("%%5c")
-    or lowerPath:match("%%252e")
-    or lowerPath:match("%%252f")
-    or lowerPath:match("%%255c")
-  then
-    return false, "Path contains URL-encoded directory separators"
-  end
-
-  -- If baseDir is provided, ensure path is within it
-  if baseDir then
-    baseDir = sanitizePath(baseDir)
-
-    -- For relative paths, prepend baseDir
-    local fullPath = path
-    if not path:match("^/") and not path:match("^%a:") then
-      fullPath = baseDir .. "/" .. path
-    end
-    fullPath = sanitizePath(fullPath)
-
-    -- Check if fullPath starts with baseDir
-    if not fullPath:match("^" .. baseDir:gsub("[%(%)%.%%%+%-%*%?%[%]%^%$]", "%%%1")) then
-      return false, "Path is outside allowed directory"
-    end
-  end
-
-  return true, nil
-end
-
--- Validate a file path with comprehensive checks
--- @param path string Path to validate
--- @param options table? Validation options
--- @return boolean, string? Returns true if valid, or false with error message
-local function validatePath(path, options)
-  options = options or {}
-
-  -- Check path is not nil/empty
-  if path == nil or path == "" then
-    return false, "Path is empty"
-  end
-
-  path = tostring(path)
-
-  -- Check maximum length
-  local maxLength = options.maxLength or 4096
-  if #path > maxLength then
-    return false, string.format("Path exceeds maximum length of %d characters", maxLength)
-  end
-
-  -- Sanitize path
-  path = sanitizePath(path)
-
-  -- Check for safety (traversal attacks)
-  local safe, reason = isPathSafe(path, options.baseDir)
-  if not safe then
-    return false, reason
-  end
-
-  -- Check allowed extensions
-  if options.allowedExtensions then
-    local ext = path:match("%.([^%.]+)$")
-    if not ext then
-      return false, "Path has no file extension"
-    end
-
-    ext = ext:lower()
-    local allowed = false
-    for _, allowedExt in ipairs(options.allowedExtensions) do
-      if ext == allowedExt:lower() then
-        allowed = true
-        break
-      end
-    end
-
-    if not allowed then
-      return false, string.format("File extension '%s' is not allowed", ext)
-    end
-  end
-
-  -- Check if file must exist
-  if options.mustExist and love and love.filesystem then
-    local info = love.filesystem.getInfo(path)
-    if not info then
-      return false, "File does not exist"
-    end
-  end
-
-  return true, nil
-end
-
--- Get file extension from path
--- @param path string File path
--- @return string? extension File extension (lowercase) or nil
-local function getFileExtension(path)
-  if not path then
-    return nil
-  end
-  local ext = path:match("%.([^%.]+)$")
-  return ext and ext:lower() or nil
-end
-
--- Check if path has allowed extension
--- @param path string File path
--- @param allowedExtensions table Array of allowed extensions
--- @return boolean
-local function hasAllowedExtension(path, allowedExtensions)
-  local ext = getFileExtension(path)
-  if not ext then
-    return false
-  end
-
-  for _, allowedExt in ipairs(allowedExtensions) do
-    if ext == allowedExt:lower() then
-      return true
-    end
-  end
-
-  return false
-end
-
-return {
-  normalizePath = normalizePath,
-  sanitizePath = sanitizePath,
-  isPathSafe = isPathSafe,
-  validatePath = validatePath,
-  getFileExtension = getFileExtension,
-  hasAllowedExtension = hasAllowedExtension,
-}
@@ -1,560 +0,0 @@
---@class Performance
---@field enabled boolean
---@field hudEnabled boolean
---@field hudToggleKey string
---@field hudPosition {x: number, y: number}
---@field warningThresholdMs number
---@field criticalThresholdMs number
---@field logToConsole boolean
---@field logWarnings boolean
---@field warningsEnabled boolean
---@field _ErrorHandler table?
---@field _timers table
---@field _metrics table
---@field _lastMetricsCleanup number
---@field _frameMetrics table
---@field _memoryMetrics table
---@field _warnings table
---@field _lastFrameStart number?
---@field _shownWarnings table
---@field _memoryProfiler table
-local Performance = {}
-Performance.__index = Performance
-
---@type Performance|nil
-local instance = nil
-
-local METRICS_CLEANUP_INTERVAL = 30
-local METRICS_RETENTION_TIME = 10
-local MAX_METRICS_COUNT = 500
-local CORE_METRICS = { frame = true, layout = true, render = true }
-
---@param config {enabled?: boolean, hudEnabled?: boolean, hudToggleKey?: string, hudPosition?: {x: number, y: number}, warningThresholdMs?: number, criticalThresholdMs?: number, logToConsole?: boolean, logWarnings?: boolean, warningsEnabled?: boolean, memoryProfiling?: boolean}?
---@param deps {ErrorHandler: ErrorHandler}
---@return Performance
-function Performance.init(config, deps)
-  if instance == nil then
-    local self = setmetatable({}, Performance)
-
-    -- Configuration
-    self.enabled = config and config.enabled or false
-    self.hudEnabled = config and config.hudEnabled or false
-    self.hudToggleKey = config and config.hudToggleKey or "f3"
-    self.hudPosition = config and config.hudPosition or { x = 10, y = 10 }
-    self.warningThresholdMs = config and config.warningThresholdMs or 13.0
-    self.criticalThresholdMs = config and config.criticalThresholdMs or 16.67
-    self.logToConsole = config and config.logToConsole or false
-    self.logWarnings = config and config.logWarnings or true
-    self.warningsEnabled = config and config.warningsEnabled or true
-
-    self._timers = {}
-    self._metrics = {}
-    self._lastMetricsCleanup = 0
-    self._frameMetrics = {
-      frameCount = 0,
-      totalTime = 0,
-      lastFrameTime = 0,
-      minFrameTime = math.huge,
-      maxFrameTime = 0,
-      fps = 0,
-      lastFpsUpdate = 0,
-      fpsUpdateInterval = 0.5,
-    }
-    self._memoryMetrics = {
-      current = 0,
-      peak = 0,
-      gcCount = 0,
-      lastGcCheck = 0,
-    }
-    self._warnings = {}
-    self._lastFrameStart = nil
-    self._shownWarnings = {}
-    self._memoryProfiler = {
-      enabled = config and config.memoryProfiling or false,
-      sampleInterval = 60,
-      framesSinceLastSample = 0,
-      samples = {},
-      maxSamples = 20,
-      monitoredTables = {},
-    }
-    self._ErrorHandler = deps and deps.ErrorHandler
-    instance = self
-  end
-  return instance
-end
-
--- Toggle HUD visibility
-function Performance:toggleHUD()
-  self.hudEnabled = not self.hudEnabled
-end
-
-function Performance:startTimer(name)
-  if not self.enabled then
-    return
-  end
-  self._timers[name] = love.timer.getTime()
-end
-
-function Performance:stopTimer(name)
-  if not self.enabled then
-    return nil
-  end
-
-  local startTime = self._timers[name]
-  if not startTime then
-    -- Silently return nil if timer wasn't started
-    -- This can happen legitimately when Performance is toggled mid-frame
-    -- or when layout functions have early returns
-    return nil
-  end
-
-  local elapsed = (love.timer.getTime() - startTime) * 1000
-  self._timers[name] = nil
-
-  -- Update metrics
-  if not self._metrics[name] then
-    self._metrics[name] = {
-      total = 0,
-      count = 0,
-      min = math.huge,
-      max = 0,
-      average = 0,
-      lastUsed = love.timer.getTime(),
-    }
-  end
-
-  local m = self._metrics[name]
-  m.total = m.total + elapsed
-  m.count = m.count + 1
-  m.min = math.min(m.min, elapsed)
-  m.max = math.max(m.max, elapsed)
-  m.average = m.total / m.count
-  m.lastUsed = love.timer.getTime()
-
-  -- Check for warnings
-  if elapsed > self.criticalThresholdMs then
-    self:_addWarning(name, elapsed, "critical")
-  elseif elapsed > self.warningThresholdMs then
-    self:_addWarning(name, elapsed, "warning")
-  end
-
-  if self.logToConsole then
-    -- Use ErrorHandler if available, otherwise fall back to print
-    if self._ErrorHandler and self._ErrorHandler.warn then
-      self._ErrorHandler:warn("Performance", "PERF_001", {
-        metric = name,
-        elapsed = string.format("%.3fms", elapsed),
-      })
-    else
-      print(string.format("[Performance] %s: %.3fms", name, elapsed))
-    end
-  end
-
-  return elapsed
-end
-
--- Update with actual delta time from LÖVE (call from love.update)
---@param dt number Delta time in seconds
-function Performance:updateDeltaTime(dt)
-  if not self.enabled then
-    return
-  end
-  local now = love.timer.getTime()
-  if now - self._frameMetrics.lastFpsUpdate >= self._frameMetrics.fpsUpdateInterval then
-    if dt > 0 then
-      self._frameMetrics.fps = math.floor(1 / dt + 0.5)
-    end
-    self._frameMetrics.lastFpsUpdate = now
-  end
-end
-
--- Start frame timing (call at beginning of frame)
-function Performance:startFrame()
-  if not self.enabled then
-    return
-  end
-  self._lastFrameStart = love.timer.getTime()
-  self:_updateMemory()
-end
-
-function Performance:endFrame()
-  if not self.enabled or not self._lastFrameStart then
-    return
-  end
-
-  local now = love.timer.getTime()
-  local frameTime = (now - self._lastFrameStart) * 1000
-
-  self._frameMetrics.lastFrameTime = frameTime
-  self._frameMetrics.totalTime = self._frameMetrics.totalTime + frameTime
-  self._frameMetrics.frameCount = self._frameMetrics.frameCount + 1
-  self._frameMetrics.minFrameTime = math.min(self._frameMetrics.minFrameTime, frameTime)
-  self._frameMetrics.maxFrameTime = math.max(self._frameMetrics.maxFrameTime, frameTime)
-
-  if frameTime > self.criticalThresholdMs then
-    self:_addWarning("frame", frameTime, "critical")
-  end
-
-  self:updateMemoryProfiling()
-
-  -- Periodic metrics cleanup
-  if now - self._lastMetricsCleanup >= METRICS_CLEANUP_INTERVAL then
-    local cleanupTime = now - METRICS_RETENTION_TIME
-    for name, data in pairs(self._metrics) do
-      if not CORE_METRICS[name] and data.lastUsed and data.lastUsed < cleanupTime then
-        self._metrics[name] = nil
-      end
-    end
-    self._lastMetricsCleanup = now
-  end
-
-  -- Enforce max metrics limit
-  local metricsCount = 0
-  for _ in pairs(self._metrics) do
-    metricsCount = metricsCount + 1
-  end
-
-  if metricsCount > MAX_METRICS_COUNT then
-    local sortedMetrics = {}
-    for name, data in pairs(self._metrics) do
-      if not CORE_METRICS[name] then
-        table.insert(sortedMetrics, { name = name, lastUsed = data.lastUsed or 0 })
-      end
-    end
-
-    table.sort(sortedMetrics, function(a, b)
-      return a.lastUsed < b.lastUsed
-    end)
-
-    local toRemove = metricsCount - MAX_METRICS_COUNT
-    for i = 1, math.min(toRemove, #sortedMetrics) do
-      self._metrics[sortedMetrics[i].name] = nil
-    end
-  end
-end
-
--- Update memory metrics
-function Performance:_updateMemory()
-  if not self.enabled then
-    return
-  end
-
-  local memKb = collectgarbage("count")
-  self._memoryMetrics.current = memKb
-  self._memoryMetrics.peak = math.max(self._memoryMetrics.peak, memKb)
-
-  local now = love.timer.getTime()
-  if now - self._memoryMetrics.lastGcCheck >= 1.0 then
-    self._memoryMetrics.gcCount = self._memoryMetrics.gcCount + 1
-    self._memoryMetrics.lastGcCheck = now
-  end
-end
-
--- Add a performance warning (private)
--- @param name string Metric name
--- @param value number Metric value
--- @param level "warning"|"critical" Warning level
-function Performance:_addWarning(name, value, level)
-  if not self.logWarnings then
-    return
-  end
-
-  local warning = {
-    name = name,
-    value = value,
-    level = level,
-    time = love.timer.getTime(),
-  }
-
-  table.insert(self._warnings, warning)
-
-  if #self._warnings > 100 then
-    table.remove(self._warnings, 1)
-  end
-
-  if self.logToConsole or self.warningsEnabled then
-    local warningKey = name .. "_" .. level
-    local lastWarningTime = self._shownWarnings[warningKey] or 0
-    local now = love.timer.getTime()
-
-    if now - lastWarningTime >= 60 then
-      if self._ErrorHandler and self._ErrorHandler.warn then
-        local code = level == "critical" and "PERF_002" or "PERF_001"
-
-        self._ErrorHandler:warn("Performance", code, {
-          metric = name,
-          value = string.format("%.2fms", value),
-          threshold = level == "critical" and self.criticalThresholdMs or self.warningThresholdMs,
-        })
-      end
-
-      self._shownWarnings[warningKey] = now
-    end
-  end
-end
-
--- Render performance HUD
--- @param x number? X position (default: 10)
--- @param y number? Y position (default: 10)
-function Performance:renderHUD(x, y)
-  if not self.hudEnabled then
-    return
-  end
-
-  x = x or self.hudPosition.x
-  y = y or self.hudPosition.y
-
-  self:_updateMemory()
-
-  local fm = self._frameMetrics
-  local mm = self._memoryMetrics
-
-  love.graphics.setColor(0, 0, 0, 0.8)
-  love.graphics.rectangle("fill", x, y, 300, 220)
-
-  love.graphics.setColor(1, 1, 1, 1)
-  local lineHeight = 18
-  local currentY = y + 10
-
-  -- FPS
-  local fpsColor = { 1, 1, 1 }
-  if fm.lastFrameTime > self.criticalThresholdMs then
-    fpsColor = { 1, 0, 0 }
-  elseif fm.lastFrameTime > self.warningThresholdMs then
-    fpsColor = { 1, 1, 0 }
-  end
-  love.graphics.setColor(fpsColor)
-  love.graphics.print(string.format("FPS: %d (%.2fms)", fm.fps, fm.lastFrameTime), x + 10, currentY)
-  currentY = currentY + lineHeight
-
-  love.graphics.setColor(1, 1, 1, 1)
-  local avgFrame = fm.frameCount > 0 and fm.totalTime / fm.frameCount or 0
-  love.graphics.print(string.format("Avg Frame: %.2fms", avgFrame), x + 10, currentY)
-  currentY = currentY + lineHeight
-  love.graphics.print(string.format("Min/Max: %.2f/%.2fms", fm.minFrameTime, fm.maxFrameTime), x + 10, currentY)
-  currentY = currentY + lineHeight
-
-  local currentMb = mm.current / 1024
-  local peakMb = mm.peak / 1024
-  love.graphics.print(string.format("Memory: %.2f MB (peak: %.2f MB)", currentMb, peakMb), x + 10, currentY)
-  currentY = currentY + lineHeight
-
-  local metricsCount = 0
-  for _ in pairs(self._metrics) do
-    metricsCount = metricsCount + 1
-  end
-  local metricsColor = metricsCount > MAX_METRICS_COUNT * 0.8 and { 1, 0.5, 0 } or { 1, 1, 1 }
-  love.graphics.setColor(metricsColor)
-  love.graphics.print(string.format("Metrics: %d/%d", metricsCount, MAX_METRICS_COUNT), x + 10, currentY)
-  currentY = currentY + lineHeight + 5
-
-  -- Top timings
-  love.graphics.setColor(1, 1, 1, 1)
-  local sortedMetrics = {}
-  for name, data in pairs(self._metrics) do
-    table.insert(sortedMetrics, { name = name, average = data.average })
-  end
-  table.sort(sortedMetrics, function(a, b)
-    return a.average > b.average
-  end)
-
-  love.graphics.print("Top Timings:", x + 10, currentY)
-  currentY = currentY + lineHeight
-
-  for i = 1, math.min(5, #sortedMetrics) do
-    local m = sortedMetrics[i]
-    love.graphics.print(string.format("  %s: %.3fms", m.name, m.average), x + 10, currentY)
-    currentY = currentY + lineHeight
-  end
-
-  if #self._warnings > 0 then
-    love.graphics.setColor(1, 0.5, 0, 1)
-    love.graphics.print(string.format("Warnings: %d", #self._warnings), x + 10, currentY)
-  end
-end
-
--- Handle keyboard input for HUD toggle
--- @param key string Key pressed
-function Performance:keypressed(key)
-  if key == self.hudToggleKey then
-    self:toggleHUD()
-  end
-end
-
--- Log a performance warning (only once per warning key)
--- @param warningKey string Unique key for this warning type
--- @param module string Module name (e.g., "LayoutEngine", "Element")
--- @param message string Warning message
--- @param details table? Additional details
--- @param suggestion string? Optimization suggestion
-function Performance:logWarning(warningKey, module, message, details, suggestion)
-  if not self.warningsEnabled then
-    return
-  end
-
-  if self._shownWarnings[warningKey] then
-    return
-  end
-
-  self._shownWarnings[warningKey] = true
-
-  local count = 0
-  for _ in pairs(self._shownWarnings) do
-    count = count + 1
-  end
-  if count > 1000 then
-    self._shownWarnings = { [warningKey] = true }
-  end
-
-  if self._ErrorHandler and self._ErrorHandler.warn then
-    self._ErrorHandler:warn(module, "PERF_001", details or {})
-  end
-end
-
--- Track a counter metric (increments per frame)
--- @param name string Counter name
--- @param value number? Value to add (default: 1)
-function Performance:incrementCounter(name, value)
-  if not self.enabled then
-    return
-  end
-
-  value = value or 1
-
-  if not self._metrics[name] then
-    self._metrics[name] = {
-      total = 0,
-      count = 0,
-      min = math.huge,
-      max = 0,
-      average = 0,
-      frameValue = 0,
-      lastUsed = love.timer.getTime(),
-    }
-  end
-
-  local m = self._metrics[name]
-  m.frameValue = (m.frameValue or 0) + value
-  m.lastUsed = love.timer.getTime()
-end
-
--- Reset frame counters (call at end of frame)
-function Performance:resetFrameCounters()
-  if not self.enabled then
-    return
-  end
-
-  local now = love.timer.getTime()
-  local toRemove = {}
-
-  for name, data in pairs(self._metrics) do
-    if data.frameValue then
-      if data.frameValue > 0 then
-        data.total = data.total + data.frameValue
-        data.count = data.count + 1
-        data.min = math.min(data.min, data.frameValue)
-        data.max = math.max(data.max, data.frameValue)
-        data.average = data.total / data.count
-        data.lastUsed = now
-      end
-
-      data.frameValue = 0
-
-      if data.count == 0 and not CORE_METRICS[name] then
-        table.insert(toRemove, name)
-      end
-    end
-  end
-
-  for _, name in ipairs(toRemove) do
-    self._metrics[name] = nil
-  end
-end
-
--- Register a table for memory leak monitoring
--- @param name string Friendly name for the table
--- @param tableRef table Reference to the table to monitor
-function Performance:registerTableForMonitoring(name, tableRef)
-  self._memoryProfiler.monitoredTables[name] = tableRef
-end
-
-function Performance:_sampleMemory()
-  local sample = {
-    time = love.timer.getTime(),
-    memory = collectgarbage("count") / 1024, -- MB
-    tableSizes = {},
-  }
-  local function getTableSize(tbl)
-    local count = 0
-    for _ in pairs(tbl) do
-      count = count + 1
-    end
-    return count
-  end
-
-  for name, tableRef in pairs(self._memoryProfiler.monitoredTables) do
-    sample.tableSizes[name] = getTableSize(tableRef)
-  end
-
-  table.insert(self._memoryProfiler.samples, sample)
-
-  -- Keep only maxSamples
-  if #self._memoryProfiler.samples > self._memoryProfiler.maxSamples then
-    table.remove(self._memoryProfiler.samples, 1)
-  end
-
-  -- Check for memory leaks (consistent growth)
-  if #self._memoryProfiler.samples >= 5 then
-    for name, _ in pairs(self._memoryProfiler.monitoredTables) do
-      local sizes = {}
-      for i = math.max(1, #self._memoryProfiler.samples - 4), #self._memoryProfiler.samples do
-        table.insert(sizes, self._memoryProfiler.samples[i].tableSizes[name])
-      end
-
-      -- Check if table is consistently growing
-      local growing = true
-      for i = 2, #sizes do
-        if sizes[i] <= sizes[i - 1] then
-          growing = false
-          break
-        end
-      end
-
-      if growing and sizes[#sizes] > sizes[1] * 1.5 then
-        self:_addWarning("memory_leak", sizes[#sizes], "warning")
-
-        if not self._shownWarnings[name] then
-          local message = string.format("Table '%s' growing consistently", name)
-          if self._ErrorHandler and self._ErrorHandler.warn then
-            self._ErrorHandler:warn("Performance", "MEM_001", {
-              table = name,
-              initialSize = sizes[1],
-              currentSize = sizes[#sizes],
-              growthPercent = math.floor(((sizes[#sizes] / sizes[1]) - 1) * 100),
-            })
-          end
-
-          self._shownWarnings[name] = true
-        end
-      elseif not growing then
-        self._shownWarnings[name] = nil
-      end
-    end
-  end
-end
-
--- Update memory profiling (call from endFrame)
-function Performance:updateMemoryProfiling()
-  if not self._memoryProfiler.enabled then
-    return
-  end
-
-  self._memoryProfiler.framesSinceLastSample = self._memoryProfiler.framesSinceLastSample + 1
-
-  if self._memoryProfiler.framesSinceLastSample >= self._memoryProfiler.sampleInterval then
-    self:_sampleMemory()
-    self._memoryProfiler.framesSinceLastSample = 0
-  end
-end
-
-return Performance
@@ -1,505 +0,0 @@
-- modules/PropertySchema.lua
--
-- Declarative source of truth for every Element prop.
--
-- Each entry describes one prop that Element.new / Element:setProperty currently
-- handles inline. Downstream tasks (03 data-driven prop binding, 05 registry-driven
-- setProperty dispatch) read this metadata instead of hardcoding property names.
--
-- Design constraints (locked — tasks 03/05 depend on this API):
--   * Pure Lua — NO `love` import, NO dependency on utils/Color/Units/ErrorHandler.
--     Normalizers/validators are small, dependency-free closures so the module is
--     unit-testable standalone. Color/^/unit/enum *defaults* that require those
--     modules are left as `nil` here and applied by construction-time special
--     handlers in Task 03; only defaults expressible as literals are stored.
--   * O(1) lookup — `get(name)` is a single table index into a pre-built registry;
--     no per-call construction.
--   * Additive — `define(specs)` merges entries by name so build profiles can
--     extend/override without rebuilding the whole table.
--
-- Metadata shape per prop (all fields present, false/nil when not applicable):
--   type         string   — type tag for tooling ("number"|"string"|"boolean"|
--                                    "table"|"function"|"color"|"any")
--   default      any|nil   — literal default value applied when prop is absent
--   normalizer   fn|nil    — pure fn(value) -> value; transforms input before
--                            storage (e.g. single-value padding -> 4-side table)
--   validator    fn|nil    — pure fn(value) -> bool; returns false for invalid
--                            input (Task 03 warns + falls back on false)
--   isDimension  boolean   — true for width/height: setProperty routes these
--                            through _resolveDimensionProperty (unit-string
--                            resolution + border-box sync). Other unit-accepting
--                            props (x/y/gap/padding/etc.) are resolved at
--                            construction via special handlers, NOT via this flag.
--   affectsLayout boolean  — true for props in the legacy setProperty
--                            `layoutProperties` table; setting one invalidates
--                            layout (matches baseline behavior exactly).
--   syncsTheme   boolean   — true for props whose setProperty path must reach
--                            ThemeManager/Renderer (disabled/active/themeComponent)
--   hasDeferred  boolean   — true for callbacks that have an `on<Name>Deferred`
--                            boolean companion prop (auto-wired by Task 03)
--   storageKey   string|nil— when set, the prop is stored on the element under
--                            this key instead of its own name (prop aliases, e.g.
--                            isDisabled -> stored as `disabled`)
-
-local PropertySchema = {}
-
---@type table<string, table>
-local registry = {}
-
-- ---------------------------------------------------------------------------
-- Pure normalizers (small + dependency-free; hot-pathed during construction)
-- ---------------------------------------------------------------------------
-
--- Expand a single value to a 4-side table. Leaves tables unchanged. nil passthrough.
--- Used by padding/margin: `padding = 5` -> `{top=5,right=5,bottom=5,left=5}`.
-local function expandSides(value)
-  if value == nil then
-    return nil
-  end
-  if type(value) == "table" then
-    return value
-  end
-  return { top = value, right = value, bottom = value, left = value }
-end
-
--- Normalize flex direction aliases to internal enum names.
--- "row" -> "horizontal", "column" -> "vertical",
--- "row-reverse" -> "horizontal-reverse", "column-reverse" -> "vertical-reverse";
--- everything else passes through.
-local function normalizeFlexDirection(value)
-  if value == "row" then
-    return "horizontal"
-  elseif value == "column" then
-    return "vertical"
-  elseif value == "row-reverse" then
-    return "horizontal-reverse"
-  elseif value == "column-reverse" then
-    return "vertical-reverse"
-  end
-  return value
-end
-
--- Replicate Element.new's border-shape normalization (pure).
--- * table with sides: true -> 1, number -> value, false/nil -> false; nil if no
---   truthy side remains.
--- * number / other truthy scalar: kept as-is.
--- * nil / false: nil.
-local function normalizeBorder(value)
-  if value == nil or value == false then
-    return nil
-  end
-  if type(value) == "table" then
-    local function side(v)
-      if v == true then
-        return 1
-      elseif type(v) == "number" then
-        return v
-      else
-        return false
-      end
-    end
-    local t = side(value.top)
-    local r = side(value.right)
-    local b = side(value.bottom)
-    local l = side(value.left)
-    if not (t or r or b or l) then
-      return nil
-    end
-    return { top = t, right = r, bottom = b, left = l }
-  end
-  return value
-end
-
--- Replicate Element.new's cornerRadius-shape normalization (pure).
--- * number: 0 -> nil, else the number.
--- * table: nil if all four sides are zero/absent, else fill zeros for absent sides.
--- * nil -> nil.
-local function normalizeCornerRadius(value)
-  if value == nil then
-    return nil
-  end
-  if type(value) == "number" then
-    if value == 0 then
-      return nil
-    end
-    return value
-  end
-  if type(value) == "table" then
-    -- Mirrors Element.new: `or` truthiness (0 is truthy in Lua). Only an all-
-    -- nil/false table collapses to nil; any present side — including 0 — yields
-    -- the 4-side table with zero-filled absent sides.
-    local hasAny = value.topLeft or value.topRight or value.bottomLeft or value.bottomRight
-    if not hasAny then
-      return nil
-    end
-    return {
-      topLeft = value.topLeft or 0,
-      topRight = value.topRight or 0,
-      bottomLeft = value.bottomLeft or 0,
-      bottomRight = value.bottomRight or 0,
-    }
-  end
-  return value
-end
-
-- ---------------------------------------------------------------------------
-- Pure validators (dependency-free; return boolean)
-- ---------------------------------------------------------------------------
-
--- Range validator factory: returns fn(v) -> bool. nil is treated as valid
--- (absence handling is the default mechanism's job).
-local function rangeValidator(min, max)
-  return function(v)
-    if v == nil then
-      return true
-    end
-    return type(v) == "number" and v >= min and v <= max
-  end
-end
-
--- Enum validator factory: returns fn(v) -> bool for membership in `set` (set may
--- be an array or a map of value->truthy).
-local function enumValidator(set)
-  local lookup = {}
-  if type(set) == "table" then
-    for k, v in pairs(set) do
-      if type(k) == "number" then
-        lookup[v] = true
-      else
-        lookup[k] = true
-      end
-    end
-  end
-  return function(v)
-    if v == nil then
-      return true
-    end
-    return lookup[v] == true
-  end
-end
-
--- Boolean validator: nil is valid (absence); otherwise must be a boolean.
-local function booleanValidator(v)
-  return v == nil or type(v) == "boolean"
-end
-
-- ---------------------------------------------------------------------------
-- Registry construction
-- ---------------------------------------------------------------------------
-
--- Build a fully-populated metadata entry, filling omitted fields with defaults.
-local function entry(spec)
-  return {
-    type = spec.type or "any",
-    default = spec.default,
-    normalizer = spec.normalizer,
-    validator = spec.validator,
-    isDimension = spec.isDimension == true,
-    affectsLayout = spec.affectsLayout == true,
-    syncsTheme = spec.syncsTheme == true,
-    hasDeferred = spec.hasDeferred == true,
-    storageKey = spec.storageKey,
-  }
-end
-
--- Merge prop specs into the registry (additive; later entries override earlier).
---@param specs table<string, table> map of prop-name -> spec
---@return table registry the live registry table (for chaining/inspection)
-function PropertySchema.define(specs)
-  for name, spec in pairs(specs) do
-    registry[name] = entry(spec)
-  end
-  return registry
-end
-
--- O(1) metadata lookup.
---@param name string prop name
---@return table|nil metadata nil for unknown props (no error)
-function PropertySchema.get(name)
-  return registry[name]
-end
-
--- Return the live registry (for inspection / coverage assertions only — not for
--- per-call construction).
---@return table
-function PropertySchema.all()
-  return registry
-end
-
--- True if a prop is registered.
---@param name string
---@return boolean
-function PropertySchema.has(name)
-  return registry[name] ~= nil
-end
-
--- True if setting this prop invalidates layout (legacy `layoutProperties` set).
--- O(1) registry lookup — no per-call table construction. Unknown props return false,
--- matching the legacy `layoutProperties[name]` nil-lookup behavior exactly.
---@param name string prop name
---@return boolean
-function PropertySchema.affectsLayout(name)
-  local meta = registry[name]
-  return meta ~= nil and meta.affectsLayout == true
-end
-
--- True for dimension props (width/height) that `setProperty` routes through
--- `_resolveDimensionProperty` (unit-string resolution + border-box sync).
--- O(1) registry lookup — no per-call table construction. Unknown props return false,
--- matching the legacy `dimensionProperties[name]` nil-lookup behavior exactly.
---@param name string prop name
---@return boolean
-function PropertySchema.isDimension(name)
-  local meta = registry[name]
-  return meta ~= nil and meta.isDimension == true
-end
-
--- True for props whose setProperty path must reach ThemeManager/Renderer
--- (disabled/active/themeComponent). O(1) registry lookup — no per-call table
--- construction. Unknown props return false, matching a legacy nil-lookup exactly.
---@param name string prop name
---@return boolean
-function PropertySchema.syncsTheme(name)
-  local meta = registry[name]
-  return meta ~= nil and meta.syncsTheme == true
-end
-
-- ---------------------------------------------------------------------------
-- Default schema (covers every prop handled in Element.new lines 259-1909 and
-- Element:setProperty lines 4291-4417 of the Task-01 baseline).
-- ---------------------------------------------------------------------------
-local function defineDefaults()
-  PropertySchema.define({
-    -- ------------------------------------------------------------------ identity
-    id = { type = "string" },
-    userdata = { type = "any" },
-    parent = { type = "table", affectsLayout = true },
-    children = { type = "table" },
-
-    -- ------------------------------------------------------------------ callbacks
-    onEvent = { type = "function", hasDeferred = true },
-    onFocus = { type = "function", hasDeferred = true },
-    onBlur = { type = "function", hasDeferred = true },
-    onTextInput = { type = "function", hasDeferred = true },
-    onTextChange = { type = "function", hasDeferred = true },
-    onEnter = { type = "function", hasDeferred = true },
-    onCreate = { type = "function", hasDeferred = true },
-    onTouchEvent = { type = "function", hasDeferred = true },
-    onGesture = { type = "function", hasDeferred = true },
-    onImageLoad = { type = "function", hasDeferred = true },
-    onImageError = { type = "function", hasDeferred = true },
-
-    -- Deferred companion flags (stored directly; no further Deferred companion)
-    onEventDeferred = { type = "boolean", default = false },
-    onFocusDeferred = { type = "boolean", default = false },
-    onBlurDeferred = { type = "boolean", default = false },
-    onTextInputDeferred = { type = "boolean", default = false },
-    onTextChangeDeferred = { type = "boolean", default = false },
-    onEnterDeferred = { type = "boolean", default = false },
-    onCreateDeferred = { type = "boolean", default = false },
-    onTouchEventDeferred = { type = "boolean", default = false },
-    onGestureDeferred = { type = "boolean", default = false },
-    onImageLoadDeferred = { type = "boolean", default = false },
-    onImageErrorDeferred = { type = "boolean", default = false },
-
-    -- focus / touch behavior
-    dropFocusOnSelection = { type = "boolean" },
-    customDraw = { type = "function" },
-    touchEnabled = { type = "boolean", default = true },
-    multiTouchEnabled = { type = "boolean", default = false },
-
-    -- ------------------------------------------------------------------ theme
-    theme = { type = "table" },
-    themeComponent = { type = "string", syncsTheme = true },
-    disabled = { type = "boolean", default = false, syncsTheme = true },
-    isDisabled = {
-      type = "boolean",
-      default = false,
-      syncsTheme = true,
-      storageKey = "disabled",
-    },
-    active = { type = "boolean", default = false, syncsTheme = true },
-    disableHighlight = { type = "boolean" },
-    themeStateLock = { type = "boolean" },
-    themeComponentDisabledStates = { type = "table" },
-    scaleCorners = { type = "boolean" },
-    scalingAlgorithm = { type = "string" },
-    contentAutoSizingMultiplier = { type = "table" },
-    contentBlur = { type = "table" },
-    backdropBlur = { type = "table" },
-
-    -- ------------------------------------------------------------------ text editing
-    editable = { type = "boolean", default = false },
-    multiline = { type = "boolean", default = false },
-    passwordMode = { type = "boolean", default = false },
-    textWrap = { type = "string" }, -- default computed from multiline
-    maxLines = { type = "number" },
-    maxLength = { type = "number" },
-    placeholder = { type = "string" },
-    inputType = { type = "string", default = "text" },
-    textOverflow = { type = "string", default = "clip" },
-    scrollable = { type = "boolean" }, -- default = multiline
-    autoGrow = { type = "boolean" }, -- default = multiline
-    selectOnFocus = { type = "boolean", default = false },
-    cursorColor = { type = "color" },
-    selectionColor = { type = "color" },
-    cursorBlinkRate = { type = "number", default = 0.5 },
-    text = { type = "string" },
-    textAlign = {
-      type = "string",
-      default = "start",
-      validator = enumValidator({ "start", "center", "end", "justify" }),
-    },
-    -- textAlignVertical is a derived storage field split out from textAlign
-    -- (bindVisualState resolves table/compound-string input into H + V). Its
-    -- validator is exposed for bindVisualState to validate the V component; the
-    -- prop itself stays in SPECIAL_PROPS because compound parsing needs
-    -- ErrorHandler warnings (schema is pure-Lua, cannot warn).
-    textAlignVertical = {
-      type = "string",
-      default = "start",
-      validator = enumValidator({ "start", "center", "end" }),
-    },
-    textColor = { type = "color" },
-    fontFamily = { type = "string" },
-    textSize = { type = "any" }, -- number | preset string; resolved by special handler
-    minTextSize = { type = "number" },
-    maxTextSize = { type = "number" },
-    autoScaleText = { type = "boolean", default = true },
-
-    -- ------------------------------------------------------------------ dimensions / box model
-    width = { type = "any", isDimension = true, affectsLayout = true },
-    height = { type = "any", isDimension = true, affectsLayout = true },
-    x = { type = "any", affectsLayout = false },
-    y = { type = "any", affectsLayout = false },
-    minWidth = { type = "any" },
-    maxWidth = { type = "any" },
-    minHeight = { type = "any" },
-    maxHeight = { type = "any" },
-    gap = { type = "any", affectsLayout = true },
-    padding = {
-      type = "any",
-      affectsLayout = true,
-      normalizer = expandSides,
-    },
-    margin = {
-      type = "any",
-      affectsLayout = true,
-      normalizer = expandSides,
-    },
-    flexDirection = {
-      type = "string",
-      default = "horizontal",
-      affectsLayout = true,
-      normalizer = normalizeFlexDirection,
-    },
-    flexWrap = { type = "string", default = "nowrap", affectsLayout = true },
-    justifyContent = { type = "string", default = "flex-start", affectsLayout = true },
-    alignItems = { type = "string", default = "stretch", affectsLayout = true },
-    alignContent = { type = "string", default = "stretch", affectsLayout = true },
-    positioning = { type = "string", default = "relative", affectsLayout = true },
-    gridRows = { type = "number", affectsLayout = true },
-    gridColumns = { type = "number", affectsLayout = true },
-    top = { type = "any", affectsLayout = true },
-    right = { type = "any", affectsLayout = true },
-    bottom = { type = "any", affectsLayout = true },
-    left = { type = "any", affectsLayout = true },
-    columnGap = { type = "any" },
-    rowGap = { type = "any" },
-    flex = { type = "any" }, -- shorthand: expands to flexGrow/flexShrink/flexBasis
-    flexGrow = { type = "number", default = 0, validator = rangeValidator(0, math.huge) },
-    flexShrink = { type = "number", default = 1, validator = rangeValidator(0, math.huge) },
-    flexBasis = { type = "any", default = "auto" },
-    alignSelf = { type = "string", default = "auto" },
-    justifySelf = { type = "string" },
-    z = { type = "number", default = 0 },
-    tabIndex = { type = "number" },
-
-    -- ------------------------------------------------------------------ border / background / visual
-    border = { type = "any", normalizer = normalizeBorder },
-    borderColor = { type = "color" }, -- default Color.new(0,0,0,1) via special handler
-    backgroundColor = { type = "color" }, -- default transparent via special handler
-    opacity = {
-      type = "number",
-      default = 1,
-      validator = rangeValidator(0, 1),
-    },
-    visibility = { type = "string", default = "visible" },
-    display = {
-      type = "boolean",
-      default = true,
-      validator = booleanValidator,
-    },
-    transform = { type = "table" },
-    cornerRadius = { type = "any", normalizer = normalizeCornerRadius },
-
-    -- ------------------------------------------------------------------ image
-    imagePath = { type = "string" },
-    image = { type = "table" },
-    objectFit = {
-      type = "string",
-      default = "fill",
-      validator = enumValidator({ "fill", "contain", "cover", "scale-down", "none" }),
-    },
-    objectPosition = { type = "string", default = "center center" },
-    imageOpacity = {
-      type = "number",
-      default = 1,
-      validator = rangeValidator(0, 1),
-    },
-    imageRepeat = {
-      type = "string",
-      default = "no-repeat",
-      validator = enumValidator({
-        "no-repeat",
-        "repeat",
-        "repeat-x",
-        "repeat-y",
-        "space",
-        "round",
-      }),
-    },
-    imageTint = { type = "color" },
-
-    -- ------------------------------------------------------------------ scroll / scrollbar
-    overflow = { type = "string" },
-    overflowX = { type = "string" },
-    overflowY = { type = "string" },
-    scrollbarWidth = { type = "number" },
-    scrollbarColor = { type = "color" },
-    scrollbarTrackColor = { type = "color" },
-    scrollbarRadius = { type = "number" },
-    scrollbarPadding = { type = "number" },
-    scrollSpeed = { type = "number" },
-    invertScroll = { type = "boolean" },
-    smoothScrollEnabled = { type = "boolean" },
-    scrollBarStyle = { type = "string" },
-    scrollbarKnobOffset = { type = "number" },
-    hideScrollbars = { type = "boolean" },
-    scrollbarPlacement = { type = "string" },
-    scrollbarBalance = { type = "number" },
-    _scrollX = { type = "number", storageKey = "_scrollX" },
-    _scrollY = { type = "number", storageKey = "_scrollY" },
-
-    -- ------------------------------------------------------------------ select
-    selectParent = { type = "table" },
-    selectOption = { type = "table" },
-
-    -- ------------------------------------------------------------------ transition
-    transition = { type = "table", default = {} },
-  })
-end
-
--- (Re)populate the default schema. Idempotent: safe to call from Element.init
--- for build profiles that re-require the module. Returns the live registry.
---@return table registry
-function PropertySchema.populate()
-  defineDefaults()
-  return registry
-end
-
-- Auto-populate on require so the registry is ready without an explicit init call
-- (pure module, no external deps — safe at load time).
-PropertySchema.populate()
-
-return PropertySchema
@@ -1,124 +0,0 @@
-local RoundedRect = {}
-
--- Generate points for a rounded rectangle
---@param x number
---@param y number
---@param width number
---@param height number
---@param cornerRadius {topLeft:number, topRight:number, bottomLeft:number, bottomRight:number}|number
---@param segments number? -- Number of segments per corner arc (default: 10)
---@return table -- Array of vertices for love.graphics.polygon
-function RoundedRect.getPoints(x, y, width, height, cornerRadius, segments)
-  segments = segments or 10
-  local points = {}
-
-  -- Helper to add arc points
-  local function addArc(cx, cy, radius, startAngle, endAngle)
-    if radius <= 0 then
-      table.insert(points, cx)
-      table.insert(points, cy)
-      return
-    end
-
-    for i = 0, segments do
-      local angle = startAngle + (endAngle - startAngle) * (i / segments)
-      table.insert(points, cx + math.cos(angle) * radius)
-      table.insert(points, cy + math.sin(angle) * radius)
-    end
-  end
-
-  -- Handle uniform corner radius (number)
-  if type(cornerRadius) == "number" then
-    cornerRadius = {
-      topLeft = cornerRadius,
-      topRight = cornerRadius,
-      bottomLeft = cornerRadius,
-      bottomRight = cornerRadius,
-    }
-  end
-
-  local r1 = math.min(cornerRadius.topLeft, width / 2, height / 2)
-  local r2 = math.min(cornerRadius.topRight, width / 2, height / 2)
-  local r3 = math.min(cornerRadius.bottomRight, width / 2, height / 2)
-  local r4 = math.min(cornerRadius.bottomLeft, width / 2, height / 2)
-
-  -- Top-right corner
-  addArc(x + width - r2, y + r2, r2, -math.pi / 2, 0)
-
-  -- Bottom-right corner
-  addArc(x + width - r3, y + height - r3, r3, 0, math.pi / 2)
-
-  -- Bottom-left corner
-  addArc(x + r4, y + height - r4, r4, math.pi / 2, math.pi)
-
-  -- Top-left corner
-  addArc(x + r1, y + r1, r1, math.pi, math.pi * 1.5)
-
-  return points
-end
-
--- Draw a filled rounded rectangle
---@param mode string -- "fill" or "line"
---@param x number
---@param y number
---@param width number
---@param height number
---@param cornerRadius {topLeft:number, topRight:number, bottomLeft:number, bottomRight:number}|number|nil
-function RoundedRect.draw(mode, x, y, width, height, cornerRadius)
-  -- OPTIMIZATION: Handle nil cornerRadius (no rounding)
-  if not cornerRadius then
-    love.graphics.rectangle(mode, x, y, width, height)
-    return
-  end
-
-  -- Handle uniform corner radius (number)
-  if type(cornerRadius) == "number" then
-    if cornerRadius <= 0 then
-      love.graphics.rectangle(mode, x, y, width, height)
-      return
-    end
-    -- Convert to table format for processing
-    cornerRadius = {
-      topLeft = cornerRadius,
-      topRight = cornerRadius,
-      bottomLeft = cornerRadius,
-      bottomRight = cornerRadius,
-    }
-  end
-
-  -- Check if any corners are rounded
-  local hasRoundedCorners = cornerRadius.topLeft > 0
-    or cornerRadius.topRight > 0
-    or cornerRadius.bottomLeft > 0
-    or cornerRadius.bottomRight > 0
-
-  if not hasRoundedCorners then
-    -- No rounded corners, use regular rectangle
-    love.graphics.rectangle(mode, x, y, width, height)
-    return
-  end
-
-  local points = RoundedRect.getPoints(x, y, width, height, cornerRadius)
-
-  if mode == "fill" then
-    love.graphics.polygon("fill", points)
-  else
-    -- For line mode, draw the outline
-    love.graphics.polygon("line", points)
-  end
-end
-
--- Create a stencil function for rounded rectangle clipping
---@param x number
---@param y number
---@param width number
---@param height number
---@param cornerRadius {topLeft:number, topRight:number, bottomLeft:number, bottomRight:number}|number|nil
---@return function
-function RoundedRect.stencilFunction(x, y, width, height, cornerRadius)
-  return function()
-    RoundedRect.draw("fill", x, y, width, height, cornerRadius)
-  end
-end
-
-return RoundedRect
@@ -1,719 +0,0 @@
---@class Select
-local Select = {}
-
---Initialize Select module with required dependencies
---@param deps table
-function Select.init(deps)
-  Select._ErrorHandler = deps.ErrorHandler
-  Select._Context = deps.Context
-  Select._StateManager = deps.StateManager
-  Select._utils = deps.utils
-  Select._Element = deps.Element
-end
-
---Initialize selectParent state on an element
---@param element Element
---@param selectParentConfig table
-function Select.initSelectParent(element, selectParentConfig)
-  element._selectState = {
-    value = selectParentConfig.value,
-    open = selectParentConfig.open or false,
-    placeholder = selectParentConfig.placeholder,
-    selectFrame = nil,
-    selectAnchor = nil,
-    onChange = selectParentConfig.onChange,
-    options = {},
-    optionLookup = {},
-    expectedFrameParent = nil,
-    frameAdopted = false,
-  }
-
-  -- Restore select state from StateManager. Mode-aware via
-  -- Context.isImmediateMode (behavior-mode-unification task 11).
-  if Select._Context.isImmediateMode() and element._stateId and element._stateId ~= "" then
-    local state = Select._StateManager.getState(element._stateId)
-    if state and state._selectOpen ~= nil then
-      element._selectState.open = state._selectOpen
-    end
-    if state and state._selectValue ~= nil then
-      element._selectState.value = state._selectValue
-      if element.selectParent then
-        element.selectParent.value = state._selectValue
-      end
-    end
-    if state and state._selectSelectedLabel ~= nil then
-      element._selectState.selectedLabel = state._selectSelectedLabel
-    end
-  end
-end
-
---Initialize selectOption on an element
---@param element Element
---@param selectOptionConfig table
-function Select.initSelectOption(element, selectOptionConfig)
-  element.selectOption = {
-    value = selectOptionConfig.value,
-    label = selectOptionConfig.label or element.text,
-    disabled = selectOptionConfig.disabled or false,
-  }
-end
-
---@param selectParent Element
-function Select.rebuildOptionLookup(selectParent)
-  if not selectParent or not selectParent._selectState then
-    return
-  end
-
-  selectParent._selectState.optionLookup = {}
-  for _, optionElement in ipairs(selectParent._selectState.options) do
-    if optionElement and optionElement.selectOption then
-      selectParent._selectState.optionLookup[optionElement.selectOption.value] = optionElement
-    end
-  end
-end
-
---@param selectParent Element
-function Select.syncOptionStates(selectParent)
-  if not selectParent or not selectParent._selectState then
-    return
-  end
-
-  local selectedOption = nil
-  local selectedLabel = selectParent._selectState.selectedLabel
-
-  for _, optionElement in ipairs(selectParent._selectState.options) do
-    local isSelected = optionElement.selectOption
-      and optionElement.selectOption.value == selectParent._selectState.value
-    optionElement._selectSelected = isSelected
-    optionElement.ariaChecked = isSelected
-
-    if isSelected then
-      selectedOption = optionElement
-      selectedLabel = optionElement.selectOption.label or optionElement.text
-    end
-  end
-
-  selectParent._selectState.selectedOption = selectedOption
-  selectParent._selectState.selectedLabel = selectedLabel
-end
-
---@param element Element
-function Select.resetOptions(element)
-  if not element._selectState then
-    return
-  end
-
-  element._selectState.options = {}
-  element._selectState.optionLookup = {}
-  element._selectState.selectedOption = nil
-end
-
---@param frame any
---@return boolean
-function Select.isValidSelectFrame(frame)
-  local Element = Select._Element
-  return type(frame) == "table" and getmetatable(frame) == Element
-end
-
---@param element Element
---@param code string
---@param details table?
-function Select.warnSelectFrame(element, code, details)
-  Select._ErrorHandler:warn("Element", code, details or { element = element.id })
-end
-
---@param element Element
---@param frame Element
-function Select.trackManagedFrame(element, frame)
-  element._selectState.selectFrame = frame
-  local expectedParent = element._selectState.selectAnchor or element
-  element._selectState.expectedFrameParent = expectedParent
-  element._selectState.frameAdopted = frame.parent == expectedParent
-  if frame._managedSelectBaseOpacity == nil then
-    frame._managedSelectBaseOpacity = frame.opacity
-  end
-  if frame._managedSelectBaseVisibility == nil then
-    frame._managedSelectBaseVisibility = frame.visibility or "visible"
-  end
-  if frame._managedSelectBaseDisabled == nil then
-    frame._managedSelectBaseDisabled = frame.disabled or false
-  end
-  frame._managedSelectOwner = element
-  frame._managedSelectFrame = true
-end
-
---@param element Element
---@return Element
-function Select.getOrCreateManagedAnchor(element)
-  if element._selectState.selectAnchor then
-    return element._selectState.selectAnchor
-  end
-
-  local Element = Select._Element
-  local anchor = Element.new({
-    id = string.format("%s__select_anchor", element.id or "select"),
-    parent = element,
-    positioning = Select._utils.enums.Positioning.ABSOLUTE,
-    left = 0,
-    top = element:getBorderBoxHeight(),
-    width = element:getBorderBoxWidth(),
-    opacity = 1,
-    visibility = "hidden",
-    disabled = true,
-  })
-
-  anchor._managedSelectAnchor = true
-  anchor._managedSelectOwner = element
-  element._selectState.selectAnchor = anchor
-  return anchor
-end
-
---@param element Element
---@param frame Element
-function Select.applyManagedFrameLayout(element, frame)
-  local anchor = Select.getOrCreateManagedAnchor(element)
-  local triggerBorderBoxWidth = element:getBorderBoxWidth()
-  anchor.left = 0
-  anchor.top = element:getBorderBoxHeight()
-  anchor.width = triggerBorderBoxWidth
-  anchor.units.left = { value = 0, unit = "px" }
-  anchor.units.top = { value = element:getBorderBoxHeight(), unit = "px" }
-  anchor.units.width = { value = triggerBorderBoxWidth, unit = "px" }
-  frame._managedSelectMinimumBorderBoxWidth = triggerBorderBoxWidth
-
-  frame.positioning = frame.positioning or Select._utils.enums.Positioning.RELATIVE
-  frame._explicitlyAbsolute = false
-  frame.left = nil
-  frame.top = nil
-  frame.right = nil
-  frame.bottom = nil
-
-  if frame.parent ~= anchor then
-    frame:setParent(anchor)
-  end
-
-  if frame.autosizing and frame.autosizing.width then
-    local contentWidth = frame:calculateAutoWidth()
-    frame._borderBoxWidth = contentWidth + frame.padding.left + frame.padding.right
-    frame.width = contentWidth
-  end
-
-  if frame.parent == anchor then
-    anchor.width = math.max(triggerBorderBoxWidth, frame:getBorderBoxWidth())
-    anchor.units.width = { value = anchor.width, unit = "px" }
-  end
-
-  element._selectState.expectedFrameParent = anchor
-  element._selectState.frameAdopted = frame.parent == anchor
-end
-
---@param element Element
---@param frame Element
-function Select.adoptSelectFrame(element, frame)
-  if not element._selectState then
-    return
-  end
-
-  if not Select.isValidSelectFrame(frame) then
-    Select.warnSelectFrame(element, "ELEM_007", {
-      element = element.id,
-      property = "selectParent.selectFrame",
-      got = type(frame),
-    })
-    return
-  end
-
-  if frame == element then
-    Select.warnSelectFrame(element, "ELEM_007", {
-      element = element.id,
-      property = "selectParent.selectFrame",
-      reason = "select cannot use itself as its managed frame",
-    })
-    return
-  end
-
-  local anchor = Select.getOrCreateManagedAnchor(element)
-
-  if frame.parent and frame.parent ~= element and frame.parent ~= anchor then
-    Select.warnSelectFrame(element, "ELEM_008", {
-      element = element.id,
-      frame = frame.id,
-      parent = frame.parent.id,
-    })
-  end
-
-  Select.trackManagedFrame(element, frame)
-  Select.applyManagedFrameLayout(element, frame)
-  Select.syncManagedFrameVisibility(element)
-
-  -- Layout is deferred to endFrame in immediate mode. shouldLayout()
-  -- encapsulates the mode check (behavior-mode-unification task 11).
-  if Select._StateManager.shouldLayout() then
-    anchor:layoutChildren()
-    element:layoutChildren()
-  end
-
-  local pendingOptions = {}
-  for _, child in ipairs(element.children) do
-    if child ~= frame and child.selectOption then
-      table.insert(pendingOptions, child)
-    end
-  end
-
-  for _, option in ipairs(pendingOptions) do
-    Select.attachOptionToManagedFrame(option)
-  end
-end
-
---@param element Element
-function Select.ensureFrameState(element)
-  if not element._selectState or not element._selectState.selectFrame then
-    return
-  end
-
-  local frame = element._selectState.selectFrame
-  local anchor = element._selectState.selectAnchor
-  if anchor then
-    local triggerBorderBoxWidth = element:getBorderBoxWidth()
-    anchor.left = 0
-    anchor.top = element:getBorderBoxHeight()
-    anchor.width = triggerBorderBoxWidth
-    anchor.units.left = { value = 0, unit = "px" }
-    anchor.units.top = { value = element:getBorderBoxHeight(), unit = "px" }
-    anchor.units.width = { value = triggerBorderBoxWidth, unit = "px" }
-    frame._managedSelectMinimumBorderBoxWidth = triggerBorderBoxWidth
-    if frame.autosizing and frame.autosizing.width then
-      local contentWidth = frame:calculateAutoWidth()
-      frame._borderBoxWidth = contentWidth + frame.padding.left + frame.padding.right
-      frame.width = contentWidth
-    end
-    if frame.parent == anchor then
-      anchor.width = math.max(triggerBorderBoxWidth, frame:getBorderBoxWidth())
-      anchor.units.width = { value = anchor.width, unit = "px" }
-    end
-    if frame.parent == anchor then
-      anchor:layoutChildren()
-    end
-  elseif frame.parent == element then
-    Select.applyManagedFrameLayout(element, frame)
-  end
-
-  local expectedParent = anchor or element._selectState.expectedFrameParent
-  if frame.parent ~= expectedParent then
-    Select.warnSelectFrame(element, "ELEM_009", {
-      element = element.id,
-      frame = frame.id,
-      expectedParent = expectedParent and expectedParent.id or nil,
-      actualParent = frame.parent and frame.parent.id or nil,
-    })
-    element._selectState.expectedFrameParent = frame.parent
-    element._selectState.frameAdopted = frame.parent == expectedParent
-  end
-end
-
---@param element Element
-function Select.syncManagedFrameVisibility(element)
-  if not element._selectState or not element._selectState.selectFrame then
-    return
-  end
-
-  local frame = element._selectState.selectFrame
-  local anchor = element._selectState.selectAnchor
-  local isOpen = element._selectState.open == true
-  frame.visibility = isOpen and (frame._managedSelectBaseVisibility or "visible") or "hidden"
-  frame.opacity = frame._managedSelectBaseOpacity or 1
-  if isOpen then
-    frame.disabled = frame._managedSelectBaseDisabled == true
-  else
-    frame.disabled = true
-  end
-  if anchor then
-    anchor.visibility = isOpen and "visible" or "hidden"
-    anchor.opacity = 1
-    anchor.disabled = not isOpen
-  end
-end
-
---@param element Element
---@return Element?
-function Select.findOwningSelectParent(element)
-  if element._selectParentHint and element._selectParentHint._selectState then
-    return element._selectParentHint
-  end
-
-  local current = element.parent
-  while current do
-    if current._selectState then
-      return current
-    end
-    current = current.parent
-  end
-
-  return nil
-end
-
---@param element Element
-function Select.registerWithSelectParent(element)
-  if not element.selectOption then
-    return
-  end
-
-  local selectParent = Select.findOwningSelectParent(element)
-  if not selectParent then
-    return
-  end
-
-  element._selectParentElement = selectParent
-
-  for _, optionElement in ipairs(selectParent._selectState.options) do
-    if optionElement == element then
-      return
-    end
-  end
-
-  table.insert(selectParent._selectState.options, element)
-  Select.rebuildOptionLookup(selectParent)
-  Select.syncOptionStates(selectParent)
-end
-
---@param element Element
-function Select.attachOptionToManagedFrame(element)
-  if not element.selectOption then
-    return
-  end
-
-  local selectParent = Select.findOwningSelectParent(element)
-  if not selectParent or not selectParent._selectState or not selectParent._selectState.selectFrame then
-    return
-  end
-
-  local selectFrame = selectParent._selectState.selectFrame
-  if element.parent ~= selectFrame then
-    element._selectParentHint = selectParent
-
-    if
-      element._originalPositioning == Select._utils.enums.Positioning.ABSOLUTE
-      and element._managedSelectOptionUsesFrameLayout == nil
-    then
-      element._managedSelectOptionUsesFrameLayout = true
-      element.positioning = Select._utils.enums.Positioning.RELATIVE
-      element._originalPositioning = nil
-      element._explicitlyAbsolute = false
-      element.left = nil
-      element.top = nil
-      element.right = nil
-      element.bottom = nil
-    end
-
-    element:setParent(selectFrame)
-    -- Ensure frame geometry eagerly only in retained mode; deferred to the
-    -- per-frame update in immediate mode (behavior-mode-unification task 11).
-    if Select._StateManager.shouldLayout() then
-      Select.ensureFrameState(selectParent)
-    end
-  end
-end
-
---@param element Element
-function Select.unregisterFromSelectParent(element)
-  if not element.selectOption or not element._selectParentElement or not element._selectParentElement._selectState then
-    element._selectParentElement = nil
-    return
-  end
-
-  local selectParent = element._selectParentElement
-  for index, optionElement in ipairs(selectParent._selectState.options) do
-    if optionElement == element then
-      table.remove(selectParent._selectState.options, index)
-      break
-    end
-  end
-
-  Select.rebuildOptionLookup(selectParent)
-  Select.syncOptionStates(selectParent)
-  element._selectParentElement = nil
-end
-
---@param element Element
-function Select.saveStateToStateManager(element)
-  if not element._selectState then
-    return
-  end
-  if element._stateId and Select._Context.isImmediateMode() and element._stateId ~= "" then
-    Select._StateManager.updateState(element._stateId, {
-      _selectOpen = element._selectState.open,
-      _selectValue = element._selectState.value,
-      _selectSelectedLabel = element._selectState.selectedLabel,
-    })
-  end
-end
-
---@param element Element
-function Select.openSelect(element)
-  if not element._selectState then
-    return
-  end
-
-  Select.ensureFrameState(element)
-  element._selectState.open = true
-  element.ariaExpanded = true
-  if element.selectParent then
-    element.selectParent.open = true
-  end
-  Select.syncManagedFrameVisibility(element)
-  Select.saveStateToStateManager(element)
-end
-
---@param element Element
-function Select.closeSelect(element)
-  if not element._selectState then
-    return
-  end
-
-  Select.ensureFrameState(element)
-  element._selectState.open = false
-  element.ariaExpanded = false
-  if element.selectParent then
-    element.selectParent.open = false
-  end
-  Select.syncManagedFrameVisibility(element)
-  Select.saveStateToStateManager(element)
-end
-
---@param element Element
-function Select.toggleSelect(element)
-  if not element._selectState then
-    return
-  end
-
-  if element.disabled then
-    return
-  end
-
-  if element._selectState.open then
-    Select.closeSelect(element)
-  else
-    Select.openSelect(element)
-  end
-
-  if element.onEvent then
-    element.onEvent(element, { type = "selecttoggle", open = element._selectState.open })
-  end
-end
-
---@param element Element
---@return boolean
-function Select.isSelectOpen(element)
-  return element._selectState ~= nil and element._selectState.open == true
-end
-
---@param element Element
---@return any
-function Select.getSelectValue(element)
-  if not element._selectState then
-    return nil
-  end
-  return element._selectState.value
-end
-
---@param element Element
---@return string?
-function Select.getSelectLabel(element)
-  if not element._selectState then
-    return nil
-  end
-
-  local selectedOption = element._selectState.selectedOption
-    or element._selectState.optionLookup[element._selectState.value]
-  if selectedOption and selectedOption.selectOption then
-    return selectedOption.selectOption.label or selectedOption.text
-  end
-
-  return element._selectState.selectedLabel or element._selectState.placeholder
-end
-
---@param element Element
---@return boolean
-function Select.isSelectedOption(element)
-  if not element.selectOption or not element._selectParentElement or not element._selectParentElement._selectState then
-    return false
-  end
-  return element._selectParentElement._selectState.value == element.selectOption.value
-end
-
---@param element Element
---@param value any
---@param optionElement Element?
-function Select.setSelectValue(element, value, optionElement)
-  if not element._selectState then
-    return
-  end
-
-  if element.disabled then
-    return
-  end
-
-  local didChange = element._selectState.value ~= value
-  element._selectState.value = value
-  if element.selectParent then
-    element.selectParent.value = value
-  end
-
-  if optionElement and optionElement.selectOption then
-    element._selectState.selectedLabel = optionElement.selectOption.label or optionElement.text
-  end
-
-  Select.syncOptionStates(element)
-  Select.closeSelect(element)
-  Select.saveStateToStateManager(element)
-
-  if element.onEvent then
-    element.onEvent(element, { type = "selectchange", value = value, option = optionElement })
-  end
-
-  if didChange and element._selectState.onChange then
-    element._selectState.onChange(element, value, optionElement and optionElement.selectOption or nil)
-  end
-end
-
---@param element Element
-function Select.handleRelease(element)
-  if element.disabled then
-    return
-  end
-
-  if element.selectOption then
-    local selectParent = element._selectParentElement or Select.findOwningSelectParent(element)
-    if not selectParent then
-      return
-    end
-
-    if element.selectOption.disabled then
-      Select.closeSelect(selectParent)
-      return
-    end
-
-    Select.setSelectValue(selectParent, element.selectOption.value, element)
-    return
-  end
-
-  if element._selectState then
-    Select.toggleSelect(element)
-  end
-end
-
---Save select state for state persistence (called from Element:saveState)
---@param element Element
---@return table?
-function Select.saveState(element)
-  if not element._selectState then
-    return nil
-  end
-  return {
-    value = element._selectState.value,
-    open = element._selectState.open,
-    selectedLabel = element._selectState.selectedLabel,
-  }
-end
-
---Restore select state (called from Element:restoreState)
---@param element Element
---@param state table
-function Select.restoreState(element, state)
-  if not element._selectState or not state then
-    return
-  end
-  element._selectState.value = state.value
-  element._selectState.open = state.open or false
-  element._selectState.selectedLabel = state.selectedLabel
-  if element.selectParent then
-    element.selectParent.value = state.value
-    element.selectParent.open = state.open or false
-  end
-  element.ariaExpanded = element._selectState.open
-  Select.syncOptionStates(element)
-end
-
---Clean up select-related resources (called from Element:destroy)
---@param element Element
-function Select.cleanupDestroy(element)
-  if element._selectState then
-    local frame = element._selectState.selectFrame
-    local anchor = element._selectState.selectAnchor
-    if frame then
-      frame._managedSelectOwner = nil
-      frame._managedSelectFrame = nil
-      frame._managedSelectBaseOpacity = nil
-      frame._managedSelectBaseVisibility = nil
-      frame._managedSelectBaseDisabled = nil
-    end
-    if anchor then
-      anchor._managedSelectOwner = nil
-      anchor._managedSelectAnchor = nil
-    end
-    element._selectState = nil
-  end
-  if element._managedSelectFrame and element._managedSelectOwner then
-    if element._managedSelectOwner._selectState then
-      element._managedSelectOwner._selectState.selectFrame = nil
-      element._managedSelectOwner._selectState.expectedFrameParent = nil
-      element._managedSelectOwner._selectState.frameAdopted = false
-    end
-    element._managedSelectOwner = nil
-    element._managedSelectFrame = nil
-    element._managedSelectBaseOpacity = nil
-    element._managedSelectBaseVisibility = nil
-    element._managedSelectBaseDisabled = nil
-  end
-  if element._managedSelectAnchor and element._managedSelectOwner then
-    if element._managedSelectOwner._selectState then
-      element._managedSelectOwner._selectState.selectAnchor = nil
-    end
-    element._managedSelectOwner = nil
-    element._managedSelectAnchor = nil
-  end
-  if element.selectParent then
-    element.selectParent.onChange = nil
-  end
-end
-
--- Called when a select parent removes a child: clears frame/anchor refs if the removed child was the
--- select-managed frame or anchor. Keeps select state-mutation logic owned by the Select module.
---@param element Element The select parent whose child was removed.
---@param child Element The removed child.
-function Select.handleChildRemoved(element, child)
-  if not element._selectState then
-    return
-  end
-  if element._selectState.selectFrame == child then
-    element._selectState.selectFrame = nil
-    element._selectState.expectedFrameParent = nil
-    element._selectState.frameAdopted = false
-  end
-  if element._selectState.selectAnchor == child then
-    element._selectState.selectAnchor = nil
-  end
-end
-
--- Layout-path hook: adjust an auto-width child's border-box width for a managed-select frame.
--- Invoked from LayoutEngine (via the Element delegate) during vertical-flex auto-width calculation.
---@param element Element The managed-select frame (the dropdown container).
---@param child Element The flex child being measured.
---@param childBorderBoxWidth number Current computed border-box width of `child`.
---@return number Possibly-adjusted border-box width.
-function Select.adjustAutoWidthChild(element, child, childBorderBoxWidth)
-  if
-    element._managedSelectFrame
-    and element.autosizing
-    and element.autosizing.width
-    and child.units
-    and child.units.width
-    and child.units.width.unit == "%"
-  then
-    local intrinsicBorderBoxWidth = child:calculateAutoWidth() + child.padding.left + child.padding.right
-    return math.max(childBorderBoxWidth, intrinsicBorderBoxWidth)
-  end
-  return childBorderBoxWidth
-end
-
-return Select
@@ -1,790 +0,0 @@
---@class StateManager
-local StateManager = {}
-
-- ErrorHandler will be injected via init
-local ErrorHandler
-
-- State storage: ID -> state table
-local stateStore = {}
-
-- Frame tracking metadata: ID -> {lastFrame, createdFrame, accessCount}
-local stateMetadata = {}
-
-- Frame counter
-local frameNumber = 0
-
-- Counter to track multiple elements created at the same source location (e.g., in loops)
-local callSiteCounters = {}
-
-- Stateful element mapping: stateId -> element instance
-- Used in retained mode for cache-through: StateManager resolves id -> element -> field
-local statefulElements = {}
-
-- Dirty state tracking for flushFrame: set of {id, key} pairs modified this frame
-local dirtyState = {}
-
-- Immediate mode flag
-local _immediateMode = false
-
-- Configuration
-local config = {
-  stateRetentionFrames = 2, -- Keep unused state for 2 frames
-  maxStateEntries = 1000, -- Maximum state entries before forced GC
-}
-
-- Default state values (sparse storage - don't store these)
-local stateDefaults = {
-  -- Interaction states
-  hover = false,
-  pressed = false,
-  focused = false,
-  disabled = false,
-  active = false,
-
-  -- Scrollbar states
-  scrollbarHoveredVertical = false,
-  scrollbarHoveredHorizontal = false,
-  scrollbarDragging = false,
-  hoveredScrollbar = nil,
-  scrollbarDragOffset = 0,
-  dragStartMouseX = 0,
-  dragStartMouseY = 0,
-  dragStartScrollX = 0,
-  dragStartScrollY = 0,
-
-  -- Scroll position
-  scrollX = 0,
-  scrollY = 0,
-  _scrollX = 0,
-  _scrollY = 0,
-
-  -- Click tracking
-  _clickCount = 0,
-  _lastClickTime = nil,
-  _lastClickButton = nil,
-
-  -- Internal states
-  _hovered = nil,
-  _focused = nil,
-  _cursorPosition = nil,
-  _selectionStart = nil,
-  _selectionEnd = nil,
-  _textBuffer = "",
-  _cursorBlinkTimer = 0,
-  _cursorVisible = true,
-  _cursorBlinkPaused = false,
-  _cursorBlinkPauseTimer = 0,
-}
-
--- Check if a value equals the default for a key
---@param key string State key
---@param value any Value to check
---@return boolean isDefault True if value equals default
-local function isDefaultValue(key, value)
-  local defaultVal = stateDefaults[key]
-
-  -- If no default defined, check for common defaults
-  if defaultVal == nil then
-    -- Empty tables are default
-    if type(value) == "table" and next(value) == nil then
-      return true
-    end
-    -- nil values are default
-    if value == nil then
-      return true
-    end
-    -- Otherwise, not a default value
-    return false
-  end
-
-  -- Compare values
-  if type(value) == "table" then
-    -- Empty tables are considered default
-    if next(value) == nil then
-      return true
-    end
-    -- For other tables, compare contents (shallow)
-    if type(defaultVal) ~= "table" then
-      return false
-    end
-    for k, v in pairs(value) do
-      if defaultVal[k] ~= v then
-        return false
-      end
-    end
-    return true
-  else
-    return value == defaultVal
-  end
-end
-
-- ====================
-- ID Generation
-- ====================
-
--- Generate a hash from a table of properties
---@param props table
---@param visited table|nil Tracking table to prevent circular references
---@param depth number|nil Current recursion depth
---@return string
-local function hashProps(props, visited, depth)
-  if not props then
-    return ""
-  end
-
-  -- Initialize visited table on first call
-  visited = visited or {}
-  depth = depth or 0
-
-  -- Limit recursion depth to prevent deep nesting issues
-  if depth > 3 then
-    return "[deep]"
-  end
-
-  -- Check if we've already visited this table (circular reference)
-  if visited[props] then
-    return "[circular]"
-  end
-
-  -- Mark this table as visited
-  visited[props] = true
-
-  local parts = {}
-  local keys = {}
-
-  -- Properties to skip (they cause issues or aren't relevant for ID generation)
-  local skipKeys = {
-    onEvent = true,
-    parent = true,
-    children = true,
-    onFocus = true,
-    onBlur = true,
-    onTextInput = true,
-    onTextChange = true,
-    onEnter = true,
-    userdata = true,
-    -- Dynamic input/state properties that should not affect ID stability
-    text = true, -- Text content changes as user types
-    placeholder = true, -- Placeholder text is presentational
-    editable = true, -- Editable state can be toggled dynamically
-    selectOnFocus = true, -- Input behavior flag
-    autoGrow = true, -- Auto-grow behavior flag
-    passwordMode = true, -- Password mode can be toggled
-  }
-
-  -- Collect and sort keys for consistent ordering
-  for k in pairs(props) do
-    if not skipKeys[k] then
-      table.insert(keys, k)
-    end
-  end
-  table.sort(keys)
-
-  -- Build hash string from sorted key-value pairs
-  for _, k in ipairs(keys) do
-    local v = props[k]
-    local vtype = type(v)
-
-    if vtype == "string" or vtype == "number" or vtype == "boolean" then
-      table.insert(parts, k .. "=" .. tostring(v))
-    elseif vtype == "table" then
-      table.insert(parts, k .. "={" .. hashProps(v, visited, depth + 1) .. "}")
-    end
-  end
-
-  return table.concat(parts, ";")
-end
-
--- Generate a unique ID from call site and properties
---@param props table|nil Optional properties to include in ID generation
---@param parent table|nil Optional parent element for tree-based ID generation
---@return string
-function StateManager.generateID(props, parent)
-  -- Get call stack information
-  local info = debug.getinfo(3, "Sl") -- Level 3: caller of Element.new -> caller of generateID
-
-  if not info then
-    -- Fallback to random ID if debug info unavailable
-    return "auto_" .. tostring(math.random(1000000, 9999999))
-  end
-
-  local source = info.source or "unknown"
-  local line = info.currentline or 0
-
-  -- Create base location key from source file and line number
-  local filename = source:match("([^/\\]+)$") or source -- Get filename
-  filename = filename:gsub("%.lua$", "") -- Remove .lua extension
-  local locationKey = filename .. "_L" .. line
-
-  -- If we have a parent, use tree-based ID generation for stability
-  if parent and parent.id and parent.id ~= "" then
-    -- For child elements, use call-site (file + line) like top-level elements
-    -- This ensures the same call site always generates the same ID, even when
-    -- retained children persist in parent.children array
-    local baseID = parent.id .. "_" .. locationKey
-
-    -- Count how many children have been created at THIS call site
-    local callSiteKey = parent.id .. "_" .. locationKey
-    callSiteCounters[callSiteKey] = (callSiteCounters[callSiteKey] or 0) + 1
-    local instanceNum = callSiteCounters[callSiteKey]
-
-    if instanceNum > 1 then
-      baseID = baseID .. "_" .. instanceNum
-    end
-
-    -- Add property hash if provided (for additional differentiation)
-    if props then
-      local propHash = hashProps(props)
-      if propHash ~= "" then
-        -- Use first 8 chars of a simple hash
-        local hash = 0
-        for i = 1, #propHash do
-          hash = (hash * 31 + string.byte(propHash, i)) % 1000000
-        end
-        baseID = baseID .. "_" .. hash
-      end
-    end
-
-    return baseID
-  end
-
-  -- No parent (top-level element): use call-site counter approach
-  -- Track how many elements have been created at this location
-  callSiteCounters[locationKey] = (callSiteCounters[locationKey] or 0) + 1
-  local instanceNum = callSiteCounters[locationKey]
-
-  local baseID = locationKey
-
-  -- Add instance number if multiple elements created at same location (e.g., in loops)
-  if instanceNum > 1 then
-    baseID = baseID .. "_" .. instanceNum
-  end
-
-  -- Add property hash if provided (for additional differentiation)
-  if props then
-    local propHash = hashProps(props)
-    if propHash ~= "" then
-      -- Use first 8 chars of a simple hash
-      local hash = 0
-      for i = 1, #propHash do
-        hash = (hash * 31 + string.byte(propHash, i)) % 1000000
-      end
-      baseID = baseID .. "_" .. hash
-    end
-  end
-
-  return baseID
-end
-
-- ====================
-- State Management
-- ====================
-
--- Initialize StateManager with dependencies
---@param deps table Dependencies: { ErrorHandler = ErrorHandler }
-function StateManager.init(deps)
-  if type(deps) == "table" then
-    ErrorHandler = deps.ErrorHandler
-  end
-end
-
--- Get state for an element ID, creating if it doesn't exist
---@param id string Element ID
---@param defaultState table|nil Default state if creating new
---@return table state State table for the element
-function StateManager.getState(id, defaultState)
-  if not id then
-    ErrorHandler:error("StateManager", "SYS_001", {
-      parameter = "id",
-      value = "nil",
-    })
-  end
-
-  -- Create state if it doesn't exist
-  if not stateStore[id] then
-    -- Start with empty state (sparse storage)
-    stateStore[id] = defaultState or {}
-
-    -- Create metadata
-    stateMetadata[id] = {
-      lastFrame = frameNumber,
-      createdFrame = frameNumber,
-      accessCount = 0,
-    }
-  else
-    -- Update metadata
-    local meta = stateMetadata[id]
-    meta.lastFrame = frameNumber
-    meta.accessCount = meta.accessCount + 1
-  end
-
-  return stateStore[id]
-end
-
--- Set state for an element ID (replaces entire state)
---@param id string Element ID
---@param state table State to store
-function StateManager.setState(id, state)
-  if not id then
-    ErrorHandler:error("StateManager", "SYS_001", {
-      parameter = "id",
-      value = "nil",
-    })
-  end
-
-  -- Create sparse state (remove default values)
-  local sparseState = {}
-  for key, value in pairs(state) do
-    if not isDefaultValue(key, value) then
-      sparseState[key] = value
-    end
-  end
-
-  stateStore[id] = sparseState
-
-  -- Update or create metadata
-  if not stateMetadata[id] then
-    stateMetadata[id] = {
-      lastFrame = frameNumber,
-      createdFrame = frameNumber,
-      accessCount = 1,
-    }
-  else
-    stateMetadata[id].lastFrame = frameNumber
-  end
-end
-
--- Update state for an element ID (merges with existing state)
---@param id string Element ID
---@param newState table New state values to merge
-function StateManager.updateState(id, newState)
-  local state = StateManager.getState(id)
-
-  -- Merge new state into existing state (with diffing optimization)
-  local changed = false
-  for key, value in pairs(newState) do
-    if state[key] ~= value then
-      state[key] = value
-      changed = true
-    end
-  end
-
-  -- Only update metadata if something actually changed
-  if changed then
-    stateMetadata[id].lastFrame = frameNumber
-  end
-end
-
--- Update state only if values have changed (optimized for immediate mode)
---@param id string Element ID
---@param newState table New state values to merge
---@return boolean changed True if any values changed
-function StateManager.updateStateIfChanged(id, newState)
-  local state = StateManager.getState(id)
-  local changed = false
-
-  for key, value in pairs(newState) do
-    -- Skip if value hasn't changed (optimization)
-    if state[key] ~= value then
-      state[key] = value
-      changed = true
-    end
-  end
-
-  if changed then
-    stateMetadata[id].lastFrame = frameNumber
-  end
-
-  return changed
-end
-
--- Clear state for a specific element ID
---@param id string Element ID
-function StateManager.clearState(id)
-  stateStore[id] = nil
-  stateMetadata[id] = nil
-end
-
--- Mark state as used this frame (updates last accessed frame)
---@param id string Element ID
-function StateManager.markStateUsed(id)
-  if stateMetadata[id] then
-    stateMetadata[id].lastFrame = frameNumber
-  end
-end
-
-- ====================
-- Frame Management
-- ====================
-
--- Increment frame counter (called at frame start)
-function StateManager.incrementFrame()
-  frameNumber = frameNumber + 1
-  -- Reset call site counters for new frame
-  callSiteCounters = {}
-end
-
--- Get current frame number
---@return number
-function StateManager.getFrameNumber()
-  return frameNumber
-end
-
-- ====================
-- Granular State Access (Unified API for both modes)
-- ====================
-
--- Get a single state value by key for a given element ID.
--- Works identically in both modes — the caller does not need to know the mode.
---
--- Immediate mode: reads from persistent state store.
--- Retained mode: resolves through registered element field (cache-through).
---
---@param id string Element state ID
---@param key string State key
---@return any value The stored value, or nil if not found
-function StateManager.getStateValue(id, key)
-  if not id or not key then
-    ErrorHandler:error("StateManager", "SYS_001", {
-      parameter = "id and key",
-      value = "missing",
-    })
-  end
-
-  -- Update metadata for access tracking
-  if stateMetadata[id] then
-    stateMetadata[id].lastFrame = frameNumber
-    stateMetadata[id].accessCount = stateMetadata[id].accessCount + 1
-  end
-
-  if _immediateMode then
-    -- Immediate mode: read from persistent state store
-    local state = stateStore[id]
-    if state then
-      return state[key]
-    end
-    return nil
-  else
-    -- Retained mode: resolve through element field
-    local element = statefulElements[id]
-    if element then
-      return element[key]
-    end
-    return nil
-  end
-end
-
--- Set a single state value by key for a given element ID.
--- Works identically in both modes — the caller does not need to know the mode.
---
--- Immediate mode: marks dirty for flushFrame() persistence.
--- Retained mode: writes directly to element field (cache-through).
---
---@param id string Element state ID
---@param key string State key
---@param value any Value to store
-function StateManager.setStateValue(id, key, value)
-  if not id or not key then
-    ErrorHandler:error("StateManager", "SYS_001", {
-      parameter = "id and key",
-      value = "missing",
-    })
-  end
-
-  -- Update metadata
-  if not stateMetadata[id] then
-    stateMetadata[id] = {
-      lastFrame = frameNumber,
-      createdFrame = frameNumber,
-      accessCount = 1,
-    }
-  else
-    stateMetadata[id].lastFrame = frameNumber
-  end
-
-  if _immediateMode then
-    -- Immediate mode: mark dirty for flushFrame persistence
-    local state = StateManager.getState(id)
-    state[key] = value
-    dirtyState[id] = dirtyState[id] or {}
-    dirtyState[id][key] = true
-  else
-    -- Retained mode: write directly to element field
-    local element = statefulElements[id]
-    if element then
-      element[key] = value
-    end
-  end
-end
-
-- ====================
-- Stateful Element Registration (Retained Mode Cache-Through)
-- ====================
-
--- Register an element instance for retained-mode cache-through.
--- After registration, getStateValue/setStateValue will resolve through the element's fields.
---
--- Called by Element in _construct phase.
---
---@param id string State ID (typically element.id)
---@param element table Element instance to link
-function StateManager.registerStateful(id, element)
-  if not id or not element then
-    return
-  end
-  statefulElements[id] = element
-end
-
--- Unregister an element instance.
--- After unregistration, retained-mode access will fall back to nil.
---
--- Called by Element in _cleanup phase.
---
---@param id string State ID to unregister
-function StateManager.unregisterStateful(id)
-  if id then
-    statefulElements[id] = nil
-  end
-end
-
-- ====================
-- Frame Flush (Immediate Mode Dirty State Persistence)
-- ====================
-
--- Flush dirty state to persistent store at end of frame.
--- Called automatically at frame end in immediate mode.
--- Behaviors call setStateValue during update without knowing the mode.
---
--- In retained mode, this is a no-op (state is written directly to elements).
-function StateManager.flushFrame()
-  if not _immediateMode then
-    return
-  end
-
-  -- All dirty writes were already applied to stateStore during setStateValue
-  -- This method exists for future extensions (e.g., batching, analytics)
-  -- Reset dirty tracking for next frame
-  dirtyState = {}
-end
-
-- ====================
-- Mode Configuration
-- ====================
-
--- Configure immediate mode state.
--- Called by Context when immediate mode is enabled/disabled.
---
---@param enabled boolean Whether immediate mode is active
-function StateManager.setImmediateMode(enabled)
-  _immediateMode = enabled
-end
-
--- Check if immediate mode is active.
---@return boolean
-function StateManager.isImmediateMode()
-  return _immediateMode
-end
-
--- Whether at-construction layout / eager initialization should run now.
--- Returns true in retained mode (layout eagerly), false in immediate mode
--- (layout is deferred to `FlexLove.endFrame` / FlexLove so it runs once all
--- elements for the frame have been created). This replaces the scattered
--- `if not _immediateMode then layoutChildren()` mode checks with a single
--- mode-aware query (behavior-mode-unification task 11).
---@return boolean
-function StateManager.shouldLayout()
-  return not _immediateMode
-end
-
-- ====================
-- Cleanup & Maintenance
-- ====================
-
--- Clean up stale states (not accessed recently)
---@return number count Number of states cleaned up
-function StateManager.cleanup()
-  local cleanedCount = 0
-  local retentionFrames = config.stateRetentionFrames
-
-  for id, meta in pairs(stateMetadata) do
-    local framesSinceAccess = frameNumber - meta.lastFrame
-
-    if framesSinceAccess > retentionFrames then
-      stateStore[id] = nil
-      stateMetadata[id] = nil
-      cleanedCount = cleanedCount + 1
-    end
-  end
-
-  -- Clean up empty states (sparse storage optimization)
-  for id, state in pairs(stateStore) do
-    if next(state) == nil then
-      stateStore[id] = nil
-      stateMetadata[id] = nil
-      cleanedCount = cleanedCount + 1
-    end
-  end
-
-  return cleanedCount
-end
-
--- Force cleanup if state count exceeds maximum
---@return number count Number of states cleaned up
-function StateManager.forceCleanupIfNeeded()
-  local stateCount = StateManager.getStateCount()
-
-  if stateCount > config.maxStateEntries then
-    -- Clean up states not accessed in last 10 frames (aggressive)
-    local cleanedCount = 0
-
-    for id, meta in pairs(stateMetadata) do
-      local framesSinceAccess = frameNumber - meta.lastFrame
-
-      if framesSinceAccess > 10 then
-        stateStore[id] = nil
-        stateMetadata[id] = nil
-        cleanedCount = cleanedCount + 1
-      end
-    end
-
-    return cleanedCount
-  end
-
-  return 0
-end
-
--- Get total number of stored states
---@return number
-function StateManager.getStateCount()
-  local count = 0
-  for _ in pairs(stateStore) do
-    count = count + 1
-  end
-  return count
-end
-
--- Clear all states
-function StateManager.clearAllStates()
-  stateStore = {}
-  stateMetadata = {}
-end
-
--- Configure state management
---@param newConfig {stateRetentionFrames?: number, maxStateEntries?: number}
-function StateManager.configure(newConfig)
-  if newConfig.stateRetentionFrames then
-    config.stateRetentionFrames = newConfig.stateRetentionFrames
-  end
-  if newConfig.maxStateEntries then
-    config.maxStateEntries = newConfig.maxStateEntries
-  end
-end
-
--- Get state statistics for debugging
---@return table stats State usage statistics
-function StateManager.getStats()
-  local stateCount = StateManager.getStateCount()
-  local oldest = nil
-  local newest = nil
-
-  for _, meta in pairs(stateMetadata) do
-    if not oldest or meta.createdFrame < oldest then
-      oldest = meta.createdFrame
-    end
-    if not newest or meta.createdFrame > newest then
-      newest = meta.createdFrame
-    end
-  end
-
-  -- Count callSiteCounters
-  local callSiteCount = 0
-  for _ in pairs(callSiteCounters) do
-    callSiteCount = callSiteCount + 1
-  end
-
-  -- Warn if callSiteCounters is unexpectedly large
-  if callSiteCount > 1000 then
-    if ErrorHandler then
-      ErrorHandler.warn("StateManager", "STATE_001", {
-        count = callSiteCount,
-        expected = "near 0",
-        frameNumber = frameNumber,
-      })
-    end
-  end
-
-  return {
-    stateCount = stateCount,
-    frameNumber = frameNumber,
-    oldestState = oldest,
-    newestState = newest,
-    callSiteCounterCount = callSiteCount,
-  }
-end
-
--- Get internal state (for debugging/profiling only)
---@return table internal {stateStore, stateMetadata, callSiteCounters}
-function StateManager._getInternalState()
-  return {
-    stateStore = stateStore,
-    stateMetadata = stateMetadata,
-    callSiteCounters = callSiteCounters,
-  }
-end
-
--- Reset the entire state system (for testing)
-function StateManager.reset()
-  stateStore = {}
-  stateMetadata = {}
-  frameNumber = 0
-  callSiteCounters = {}
-  statefulElements = {}
-  dirtyState = {}
-  _immediateMode = false
-end
-
-- ====================
-- Convenience Functions (for backward compatibility)
-- ====================
-
--- Check if an element is currently hovered
---@param id string Element ID
---@return boolean
-function StateManager.isHovered(id)
-  local state = StateManager.getState(id)
-  return state.hover or false
-end
-
--- Check if an element is currently pressed
---@param id string Element ID
---@return boolean
-function StateManager.isPressed(id)
-  local state = StateManager.getState(id)
-  return state.pressed or false
-end
-
--- Check if an element is currently focused
---@param id string Element ID
---@return boolean
-function StateManager.isFocused(id)
-  local state = StateManager.getState(id)
-  return state.focused or false
-end
-
--- Check if an element is disabled
---@param id string Element ID
---@return boolean
-function StateManager.isDisabled(id)
-  local state = StateManager.getState(id)
-  return state.disabled or false
-end
-
--- Check if an element is active (e.g., input focused)
---@param id string Element ID
---@return boolean
-function StateManager.isActive(id)
-  local state = StateManager.getState(id)
-  return state.active or false
-end
-
-return StateManager
@@ -1,183 +0,0 @@
-local modulePath = (...):match("(.-)[^%.]+$")
-local function req(name)
-  return require(modulePath .. name)
-end
-
-- Text sanitization, escaping, and input validation utilities.
-
-- ErrorHandler is injected via init() for truncation warnings.
-local ErrorHandler = nil
-
--- Initialize dependencies
---@param deps table Dependencies: { ErrorHandler = ErrorHandler }
-local function init(deps)
-  if type(deps) == "table" then
-    ErrorHandler = deps.ErrorHandler
-  end
-end
-
--- Sanitize text to prevent security vulnerabilities
--- @param text string? Text to sanitize
--- @param options table? Sanitization options
--- @return string Sanitized text
-local function sanitizeText(text, options)
-  local utf8 = require("utf8")
-  -- Handle nil or non-string inputs
-  if text == nil then
-    return ""
-  end
-  if type(text) ~= "string" then
-    text = tostring(text)
-  end
-
-  -- Default options
-  options = options or {}
-  local maxLength = options.maxLength or 10000
-  local allowNewlines = options.allowNewlines ~= false -- default true
-  local allowTabs = options.allowTabs ~= false -- default true
-  local stripControls = options.stripControls ~= false -- default true
-  local trimWhitespace = options.trimWhitespace ~= false -- default true
-
-  -- Remove null bytes (critical security risk)
-  text = text:gsub("%z", "")
-
-  -- Strip control characters except allowed ones
-  if stripControls then
-    local pattern = "[\1-\31\127]" -- All control characters
-    if allowNewlines and allowTabs then
-      pattern = "[\1-\8\11\12\14-\31\127]" -- Exclude \t (9), \n (10), \r (13)
-    elseif allowNewlines then
-      pattern = "[\1-\9\11\12\14-\31\127]" -- Exclude \n (10), \r (13)
-    elseif allowTabs then
-      pattern = "[\1-\8\10\12-\31\127]" -- Exclude \t (9)
-    end
-    text = text:gsub(pattern, "")
-  end
-
-  -- Trim leading/trailing whitespace
-  if trimWhitespace then
-    text = text:match("^%s*(.-)%s*$") or ""
-  end
-
-  -- Limit string length (use UTF-8 character count, not byte count)
-  local charCount = utf8.len(text)
-  if charCount and charCount > maxLength then
-    if ErrorHandler then
-      ErrorHandler:warn("utils", "UTIL_001", {
-        original = charCount,
-        truncated = maxLength,
-      })
-    end
-    -- Truncate to maxLength UTF-8 characters
-    local bytePos = utf8.offset(text, maxLength + 1)
-    if bytePos then
-      text = text:sub(1, bytePos - 1)
-    end
-    if ErrorHandler then
-      ErrorHandler:warn("utils", string.format("Text truncated from %d to %d characters", charCount, maxLength))
-    end
-  end
-
-  return text
-end
-
--- Validate text input against rules
--- @param text string Text to validate
--- @param rules table Validation rules
--- @return boolean, string? Returns true if valid, or false with error message
-local function validateTextInput(text, rules)
-  rules = rules or {}
-
-  -- Check minimum length
-  if rules.minLength and #text < rules.minLength then
-    return false, string.format("Text must be at least %d characters", rules.minLength)
-  end
-
-  -- Check maximum length
-  if rules.maxLength and #text > rules.maxLength then
-    return false, string.format("Text must be at most %d characters", rules.maxLength)
-  end
-
-  -- Check pattern match
-  if rules.pattern and not text:match(rules.pattern) then
-    return false, rules.patternError or "Text does not match required pattern"
-  end
-
-  -- Check character whitelist
-  if rules.allowedChars then
-    local pattern = "[^" .. rules.allowedChars .. "]"
-    if text:match(pattern) then
-      return false, "Text contains invalid characters"
-    end
-  end
-
-  -- Check character blacklist
-  if rules.forbiddenChars then
-    local pattern = "[" .. rules.forbiddenChars .. "]"
-    if text:match(pattern) then
-      return false, "Text contains forbidden characters"
-    end
-  end
-
-  return true, nil
-end
-
--- Validate text against range/length rules (alias of validateTextInput)
--- @param text string Text to validate
--- @param rules table Validation rules (minLength, maxLength, pattern, etc.)
--- @return boolean, string? Returns true if valid, or false with error message
-local function validateTextRange(text, rules)
-  return validateTextInput(text, rules)
-end
-
--- Escape HTML special characters
--- @param text string Text to escape
--- @return string Escaped text
-local function escapeHtml(text)
-  if text == nil then
-    return ""
-  end
-  text = tostring(text)
-  text = text:gsub("&", "&amp;")
-  text = text:gsub("<", "&lt;")
-  text = text:gsub(">", "&gt;")
-  text = text:gsub('"', "&quot;")
-  text = text:gsub("'", "&#39;")
-  return text
-end
-
--- Escape Lua pattern special characters
--- @param text string Text to escape
--- @return string Escaped text
-local function escapeLuaPattern(text)
-  if text == nil then
-    return ""
-  end
-  text = tostring(text)
-  -- Escape all Lua pattern special characters
-  text = text:gsub("([%^%$%(%)%%%.%[%]%*%+%-%?])", "%%%1")
-  return text
-end
-
--- Strip all non-printable characters from text
--- @param text string Text to clean
--- @return string Cleaned text
-local function stripNonPrintable(text)
-  if text == nil then
-    return ""
-  end
-  text = tostring(text)
-  -- Keep printable ASCII (32-126), newline (10), tab (9), and carriage return (13)
-  text = text:gsub("[^\9\10\13\32-\126]", "")
-  return text
-end
-
-return {
-  init = init,
-  sanitizeText = sanitizeText,
-  validateTextInput = validateTextInput,
-  validateTextRange = validateTextRange,
-  escapeHtml = escapeHtml,
-  escapeLuaPattern = escapeLuaPattern,
-  stripNonPrintable = stripNonPrintable,
-}
@@ -1,44 +0,0 @@
---@class UTF8
---Compatibility layer for UTF-8 support across Lua versions
---Handles utf8 (Lua 5.3+), lua-utf8 (LuaRocks), and basic fallbacks
-
-local UTF8 = {}
-
-- Try to load UTF-8 library in order of preference:
-- 1. Built-in utf8 (Lua 5.3+, LÖVE2D)
-- 2. lua-utf8 from LuaRocks (Lua 5.1, 5.2)
-- 3. Error if neither available
-local function loadUTF8()
-  -- Try built-in utf8 first (Lua 5.3+ and LÖVE2D)
-  if utf8 and type(utf8) == "table" and utf8.len then
-    return utf8
-  end
-
-  -- Try lua-utf8 from LuaRocks
-  local ok, luautf8 = pcall(require, "lua-utf8")
-  if ok then
-    return luautf8
-  end
-
-  -- Try standard utf8 module name as fallback
-  ok, luautf8 = pcall(require, "utf8")
-  if ok then
-    return luautf8
-  end
-
-  -- No UTF-8 library available
-  error("No UTF-8 library available. Please install 'luautf8' via LuaRocks: luarocks install luautf8")
-end
-
-- Load the UTF-8 implementation
-local utf8lib = loadUTF8()
-
-- Export all utf8 functions
-UTF8.char = utf8lib.char
-UTF8.charpattern = utf8lib.charpattern
-UTF8.codes = utf8lib.codes
-UTF8.codepoint = utf8lib.codepoint
-UTF8.len = utf8lib.len
-UTF8.offset = utf8lib.offset
-
-return UTF8
@@ -1,335 +0,0 @@
--- Utility module for parsing and resolving CSS-like units (px, %, vw, vh)
--- Provides unit parsing, validation, and conversion to pixel values
---@class Units
---@field _Context table? Context module dependency
---@field _ErrorHandler table? ErrorHandler module dependency
---@field _Calc table? Calc module dependency
-local Units = {}
-
--- Initialize Units module with dependencies
---@param deps table Dependencies: { Context = table?, ErrorHandler = table?, Calc = table? }
-function Units.init(deps)
-  Units._Context = deps.Context
-  Units._ErrorHandler = deps.ErrorHandler
-  Units._Calc = deps.Calc
-end
-
--- Parse a unit value into numeric value and unit type
--- Supports: px (pixels), % (percentage), vw/vh (viewport), and calc() expressions
---@param value string|number|table The value to parse (e.g., "50px", "10%", "2vw", 100, or calc object)
---@return number|table numericValue The numeric portion of the value or calc object
---@return string unitType The unit type ("px", "%", "vw", "vh", "calc")
-function Units.parse(value)
-  -- Check if value is a calc expression
-  if Units._Calc and Units._Calc.isCalc(value) then
-    return value, "calc"
-  end
-
-  if type(value) == "number" then
-    return value, "px"
-  end
-
-  if type(value) ~= "string" and type(value) ~= "table" then
-    Units._ErrorHandler:warn("Units", "VAL_001", {
-      property = "unit value",
-      expected = "string, number, or calc object",
-      got = type(value),
-    })
-    return 0, "px"
-  end
-
-  -- Check for unit-only input (e.g., "px", "%", "vw" without a number)
-  local validUnits = { px = true, ["%"] = true, vw = true, vh = true }
-  if validUnits[value] then
-    Units._ErrorHandler:warn("Units", "VAL_005", {
-      input = value,
-      expected = "number + unit (e.g., '50" .. value .. "')",
-    })
-    return 0, "px"
-  end
-
-  -- Check for invalid format (space between number and unit)
-  if value:match("%d%s+%a") then
-    Units._ErrorHandler:warn("Units", "VAL_005", {
-      input = value,
-      issue = "contains space between number and unit",
-    })
-    return 0, "px"
-  end
-
-  -- Match number followed by optional unit
-  local numStr, unit = value:match("^([%-]?[%d%.]+)(.*)$")
-  if not numStr then
-    Units._ErrorHandler:warn("Units", "VAL_005", {
-      input = value,
-    })
-    return 0, "px"
-  end
-
-  local num = tonumber(numStr)
-  if not num then
-    Units._ErrorHandler:warn("Units", "VAL_005", {
-      input = value,
-      issue = "numeric value cannot be parsed",
-    })
-    return 0, "px"
-  end
-
-  -- Default to pixels if no unit specified
-  if unit == "" then
-    unit = "px"
-  end
-
-  -- validUnits is already defined at the top of the function
-  if not validUnits[unit] then
-    Units._ErrorHandler:warn("Units", "VAL_005", {
-      input = value,
-      unit = unit,
-      validUnits = "px, %, vw, vh",
-    })
-    return num, "px"
-  end
-
-  return num, unit
-end
-
--- Convert relative units to absolute pixel values
--- Resolves %, vw, vh units based on viewport and parent dimensions, and evaluates calc() expressions
---@param value number|table Numeric value to convert or calc object
---@param unit string Unit type ("px", "%", "vw", "vh", "calc")
---@param viewportWidth number Current viewport width in pixels
---@param viewportHeight number Current viewport height in pixels
---@param parentSize number? Required for percentage units (parent dimension in pixels)
---@return number resolvedValue Resolved pixel value
-function Units.resolve(value, unit, viewportWidth, viewportHeight, parentSize)
-  if unit == "calc" then
-    -- Resolve calc expression
-    if Units._Calc then
-      return Units._Calc.resolve(value, viewportWidth, viewportHeight, parentSize)
-    else
-      Units._ErrorHandler:warn("Units", "VAL_006", {
-        unit = "calc",
-        issue = "Calc module not available",
-      })
-      return 0
-    end
-  elseif unit == "px" then
-    return value
-  elseif unit == "%" then
-    if not parentSize then
-      Units._ErrorHandler:warn("Units", "LAY_003", {
-        unit = "%",
-        issue = "parent dimension not available",
-      })
-      return 0
-    end
-    return (value / 100) * parentSize
-  elseif unit == "vw" then
-    return (value / 100) * viewportWidth
-  elseif unit == "vh" then
-    return (value / 100) * viewportHeight
-  else
-    Units._ErrorHandler:warn("Units", "VAL_005", {
-      unit = unit,
-      validUnits = "px, %, vw, vh, calc",
-    })
-    return 0
-  end
-end
-
--- Get current viewport dimensions
--- Uses cached viewport during resize operations, otherwise queries LÖVE graphics
---@return number width Viewport width in pixels
---@return number height Viewport height in pixels
-function Units.getViewport()
-  -- Return cached viewport if available (only during resize operations)
-  if Units._Context._cachedViewport and Units._Context._cachedViewport.width > 0 then
-    return Units._Context._cachedViewport.width, Units._Context._cachedViewport.height
-  end
-
-  if love.graphics and love.graphics.getDimensions then
-    return love.graphics.getDimensions()
-  else
-    local w, h = love.window.getMode()
-    return w, h
-  end
-end
-
--- Apply base scale factor to a value based on axis
--- Used for responsive scaling of UI elements
---@param value number The value to scale
---@param axis "x"|"y" The axis to scale on
---@param scaleFactors {x:number, y:number} Scale factors for each axis
---@return number scaledValue The scaled value
-function Units.applyBaseScale(value, axis, scaleFactors)
-  if axis == "x" then
-    return value * scaleFactors.x
-  else
-    return value * scaleFactors.y
-  end
-end
-
--- Resolve spacing properties (margin, padding) to pixel values
--- Supports individual sides (top, right, bottom, left) and shortcuts (vertical, horizontal)
---@param spacingProps table? Spacing properties with top/right/bottom/left/vertical/horizontal
---@param parentWidth number Parent element width in pixels
---@param parentHeight number Parent element height in pixels
---@return table resolvedSpacing Table with top, right, bottom, left in pixels
-function Units.resolveSpacing(spacingProps, parentWidth, parentHeight)
-  if not spacingProps then
-    return { top = 0, right = 0, bottom = 0, left = 0 }
-  end
-
-  local viewportWidth, viewportHeight = Units.getViewport()
-  local result = {}
-
-  local vertical = spacingProps.vertical
-  local horizontal = spacingProps.horizontal
-
-  if vertical then
-    if type(vertical) == "string" or (Units._Calc and Units._Calc.isCalc(vertical)) then
-      local value, unit = Units.parse(vertical)
-      vertical = Units.resolve(value, unit, viewportWidth, viewportHeight, parentHeight)
-    end
-  end
-
-  if horizontal then
-    if type(horizontal) == "string" or (Units._Calc and Units._Calc.isCalc(horizontal)) then
-      local value, unit = Units.parse(horizontal)
-      horizontal = Units.resolve(value, unit, viewportWidth, viewportHeight, parentWidth)
-    end
-  end
-
-  for _, side in ipairs({ "top", "right", "bottom", "left" }) do
-    local value = spacingProps[side]
-    if value then
-      if type(value) == "string" or (Units._Calc and Units._Calc.isCalc(value)) then
-        local numValue, unit = Units.parse(value)
-        local parentSize = (side == "top" or side == "bottom") and parentHeight or parentWidth
-        result[side] = Units.resolve(numValue, unit, viewportWidth, viewportHeight, parentSize)
-      else
-        result[side] = value
-      end
-    else
-      if side == "top" or side == "bottom" then
-        result[side] = vertical or 0
-      else
-        result[side] = horizontal or 0
-      end
-    end
-  end
-
-  return result
-end
-
--- Validate a unit string format
--- Checks if the string can be successfully parsed as a valid unit or calc expression
---@param unitStr string|table The unit string to validate (e.g., "50px", "10%") or calc object
---@return boolean isValid True if the unit string is valid, false otherwise
-function Units.isValid(unitStr)
-  -- Check if it's a calc expression
-  if Units._Calc and Units._Calc.isCalc(unitStr) then
-    return true
-  end
-
-  if type(unitStr) ~= "string" then
-    return false
-  end
-
-  -- Check for invalid format (space between number and unit)
-  if unitStr:match("%d%s+%a") then
-    return false
-  end
-
-  -- Match number followed by optional unit
-  local numStr, unit = unitStr:match("^([%-]?[%d%.]+)(.*)$")
-  if not numStr then
-    return false
-  end
-
-  -- Check if numeric part is valid
-  local num = tonumber(numStr)
-  if not num then
-    return false
-  end
-
-  -- Default to pixels if no unit specified
-  if unit == "" then
-    unit = "px"
-  end
-
-  -- Check if unit is valid
-  local validUnits = { px = true, ["%"] = true, vw = true, vh = true }
-  return validUnits[unit] == true
-end
-
--- Parse CSS flex shorthand into flexGrow, flexShrink, flexBasis
--- Supports: number, "auto", "none", "grow shrink basis"
---@param flexValue number|string The flex shorthand value
---@return number flexGrow
---@return number flexShrink
---@return string|number flexBasis
-function Units.parseFlexShorthand(flexValue)
-  -- Single number: flex-grow
-  if type(flexValue) == "number" then
-    return flexValue, 1, 0
-  end
-
-  -- String values
-  if type(flexValue) == "string" then
-    -- "auto" = 1 1 auto
-    if flexValue == "auto" then
-      return 1, 1, "auto"
-    end
-
-    -- "none" = 0 0 auto
-    if flexValue == "none" then
-      return 0, 0, "auto"
-    end
-
-    -- Parse "grow shrink basis" format
-    local parts = {}
-    for part in flexValue:gmatch("%S+") do
-      table.insert(parts, part)
-    end
-
-    local grow = 0
-    local shrink = 1
-    local basis = "auto"
-
-    if #parts == 1 then
-      -- Single value: could be grow (number) or basis (with unit)
-      local num = tonumber(parts[1])
-      if num then
-        grow = num
-        basis = 0
-      else
-        basis = parts[1]
-      end
-    elseif #parts == 2 then
-      -- Two values: grow shrink (both numbers) or grow basis
-      local num1 = tonumber(parts[1])
-      local num2 = tonumber(parts[2])
-      if num1 and num2 then
-        grow = num1
-        shrink = num2
-        basis = 0
-      elseif num1 then
-        grow = num1
-        basis = parts[2]
-      end
-    elseif #parts >= 3 then
-      -- Three values: grow shrink basis
-      grow = tonumber(parts[1]) or 0
-      shrink = tonumber(parts[2]) or 1
-      basis = parts[3]
-    end
-
-    return grow, shrink, basis
-  end
-
-  -- Default fallback
-  return 0, 1, "auto"
-end
-
-return Units
@@ -1,35 +0,0 @@
---@class ZIndex
-local ZIndex = {}
-
-- The effective z-index formula used for sorting is:
--   rootZ * ROOT_WEIGHT + depth * DEPTH_WEIGHT + ownZ
-- where rootZ is the z-index of the top-level ancestor, depth is the
-- nesting level, and ownZ is the element's own z property.
--
-- Constraints enforced by these weights:
--   |ownZ| <= MAX_Z   (must fit within DEPTH_WEIGHT digits)
--   DEPTH_WEIGHT has enough room for depths well beyond any practical tree
--   ROOT_WEIGHT has enough room for the rootZ without exceeding double-precision
---
---@type integer
-ZIndex.MIN_Z = -999
---@type integer
-ZIndex.MAX_Z = 999
---@type integer
-ZIndex.ROOT_WEIGHT = 10000000000
---@type integer
-ZIndex.DEPTH_WEIGHT = 1000
-
--- Clamp a z-index value to the valid range
---@param value number
---@return integer
-function ZIndex.clamp(value)
-  if value < ZIndex.MIN_Z then
-    return ZIndex.MIN_Z
-  elseif value > ZIndex.MAX_Z then
-    return ZIndex.MAX_Z
-  end
-  return value
-end
-
-return ZIndex
@@ -1,245 +0,0 @@
-- modules/behaviors/Animated.lua
--
-- Concrete behavior: animation update, interpolation application, chaining
-- resolution, and transition wiring.
--
-- Task 06 of the behavior-mode-unification refactor. Moves the entire
-- animation-update block out of Element:update (lines ~2761-2800) into
-- `Animated.onUpdate(element, dt)`, and the `_ColorModule`/`_TransformModule`
-- init-time wiring into `Animated.onAttach(element)`.
--
-- This behavior is UNIQUE among the behavior set because it can attach
-- AFTER element creation. Animation is opt-in: a plain Element created without
-- `transitions` and without an `animation` field never attaches Animated.
-- The moment something creates an animation on the element — either directly
-- (`element.animation = Animation.new(...)`, `element:fadeIn(...)`) or via a
-- transition firing in `setProperty` — `Animated.ensureAttached(element)`
-- attaches this behavior on demand so subsequent `Element:update` frames
-- dispatch to `Animated.onUpdate`.
--
-- Attachment rule (shouldAttach): true when `props.transitions` is set OR an
-- `element.animation` already exists at runtime. The runtime arm covers the
-- late-attach case (animateTo / fadeIn / direct animation assignment).
--
-- State ownership (per the locked Behavior contract):
--   * Per-element runtime state lives ON THE ELEMENT (`element.animation`).
--   * The behavior instance itself is stateless and shared across elements.
--   * Element-class-level dependencies (Element._Animation, Element._Color,
--     Element._Transform) are resolved from the owning element's metatable,
--     exactly like Clickable does — keeping the behavior stateless without
--     expanding the 6-hook signature.
--
-- saveState/restoreState are no-ops: animations are ephemeral (an in-flight
-- animation is not part of immediate-mode persisted state — the next frame
-- re-evaluates transitions / re-applies animations fresh). Persisted scalar
-- props (`opacity`, `x`, ...) survive via Element.saveState's `_props` block,
-- not via the animation.
-
-local _pkg = (...):match("^(.-)behaviors%.") or "modules."
-local Behavior = require(_pkg .. "Behavior")
-
-- Resolve the Element class from an element instance.
-- Element instances are created via `setmetatable({}, Element)` in _construct,
-- so their metatable IS the Element class — giving us Element._Animation,
-- Element._Color, Element._Transform, etc. without threading deps through the
-- behavior hook signature.
-local function ElementClass(element)
-  return getmetatable(element)
-end
-
-- ----------------------------------------------------------------------------
-- ensureAnimationModuleWiring — set Element._Animation._ColorModule /
-- _TransformModule. Idempotent; called from both onAttach and onUpdate so it
-- works even when an animation was assigned by a caller that bypassed
-- onAttach (direct `element.animation = Animation.new(...)`).
-- ----------------------------------------------------------------------------
-
-local function ensureAnimationModuleWiring(element)
-  local Element = ElementClass(element)
-  local Animation = Element._Animation
-  if not Animation then
-    return
-  end
-  -- Ensure animation has Color module reference for color interpolation
-  if not Animation._ColorModule and Element._Color then
-    Animation._ColorModule = Element._Color
-  end
-  -- Ensure animation has Transform module reference for transform interpolation
-  if not Animation._TransformModule and Element._Transform then
-    Animation._TransformModule = Element._Transform
-  end
-end
-
-- ----------------------------------------------------------------------------
-- shouldAttach (class-level predicate, no element required)
-- ----------------------------------------------------------------------------
-
-- True when the element declares transitions up front OR already has an
-- animation attached. The `animation` arm is consulted by ensureAttached at
-- runtime (after creation); the `transitions` arm lets Animated auto-attach
-- during Element.new for elements that pre-declare transitions.
-local function shouldAttach(props)
-  if not props then
-    return false
-  end
-  if props.transitions ~= nil then
-    return true
-  end
-  -- Late-attach case: an animation was assigned after creation. When ensure
-  -- Attached passes the element instance as `props`, this arm catches it.
-  if type(props) == "table" and props.animation ~= nil then
-    return true
-  end
-  return false
-end
-
-- ----------------------------------------------------------------------------
-- ensureAttached — dynamic late-attach entry point
-- ----------------------------------------------------------------------------
-
-- Idempotently attach the Animated behavior to an element that just gained an
-- animation (via animateTo / fadeIn / direct assignment / a firing transition
-- in setProperty). Called from Element.setProperty when a transition fires and
-- from the transition helper methods on Element. Safe to call when already
-- attached (no-op / returns false).
--
-- `animatedBehavior` is the shared behavior instance resolved lazily by
-- Element (see Element._resolveAnimatedBehavior). The behavior is looked up
-- from the registry once and cached on the class.
--
-- Returns true if the behavior was attached this call, false otherwise.
-local function ensureAttached(element, animatedBehavior)
-  if not element or not animatedBehavior then
-    return false
-  end
-  -- Already attached? Avoid duplicate entries within one element lifetime
-  -- (a behavior may legitimately be re-added across immediate-mode frames
-  -- since Element is recreated each frame, but within one lifetime at most
-  -- once).
-  local behaviors = element.behaviors
-  if behaviors then
-    for i = 1, #behaviors do
-      if behaviors[i] == animatedBehavior then
-        return false
-      end
-    end
-  end
-  table.insert(element.behaviors, animatedBehavior)
-  animatedBehavior.onAttach(element)
-  return true
-end
-
-- ----------------------------------------------------------------------------
-- onAttach — initialize Animation module references (formerly the
-- Element._Animation._ColorModule / _TransformModule wiring in Element:update
-- lines ~2772-2778).
-- ----------------------------------------------------------------------------
-
-local function onAttach(element)
-  ensureAnimationModuleWiring(element)
-end
-
-- ----------------------------------------------------------------------------
-- onUpdate — the animation update + interpolation + chain-resolution block
-- (formerly Element:update lines ~2761-2800).
-- ----------------------------------------------------------------------------
-
-local function onUpdate(element, dt)
-  local animation = element.animation
-  if not animation then
-    return
-  end
-
-  -- (Re)ensure module wiring is present in case the Animation instance was
-  -- created by a caller that bypassed onAttach (e.g. direct
-  -- `element.animation = Animation.new(...)`). Cheap idempotent writes.
-  ensureAnimationModuleWiring(element)
-
-  local finished = animation:update(dt, element)
-  if finished then
-    -- Animation:update() already called onComplete callback.
-    -- Check for chained animation.
-    if animation._next then
-      element.animation = animation._next
-    elseif animation._nextFactory and type(animation._nextFactory) == "function" then
-      local success, nextAnim = pcall(animation._nextFactory, element)
-      if success and nextAnim then
-        element.animation = nextAnim
-      else
-        element.animation = nil
-      end
-    else
-      element.animation = nil
-    end
-  else
-    -- Apply animation interpolation during update.
-    animation:applyInterpolation(element)
-  end
-end
-
-- ----------------------------------------------------------------------------
-- saveState / restoreState — no-ops (animations are ephemeral).
-- ----------------------------------------------------------------------------
-
-- Animations are not persisted across immediate-mode frames — they are
-- re-derived each frame from transitions / direct calls. The element's scalar
-- props (opacity, x, ...) are persisted by Element.saveState's _props block,
-- so a completed animation's final visual state still survives recreation.
-- While an animation is mid-flight in immediate mode, the element is recreated
-- and the animation is NOT carried over (intentional — animating in immediate
-- mode requires setting up the animation each frame).
-local function saveState()
-  return nil
-end
-
-local function restoreState()
-  return nil
-end
-
-- ----------------------------------------------------------------------------
-- Build the (stateless, shared) behavior instance.
-- ----------------------------------------------------------------------------
-
-- onDetach/onDraw omitted: they default to no-ops (the behavior allocates no
-- behavior-local state and animations have no draw pass). Animation state lives
-- on the element (`element.animation`); nothing to tear down on detach.
--
-- We build the immutable behavior via Behavior.new (for validation + freeze +
-- isBehavior parity with Clickable), then expose the late-attach helper on a
-- thin module table since the frozen instance cannot accept new keys. The
-- module table passes the behavior to the registry while making
-- `Animated.ensureAttached` callable from Element.setProperty / the transition
-- helpers — exactly as the task spec requires.
-local behavior = Behavior.new({
-  onAttach = onAttach,
-  onUpdate = onUpdate,
-  saveState = saveState,
-  restoreState = restoreState,
-  shouldAttach = shouldAttach,
-})
-
-- Thin module table: exposes the behavior instance (for the registry) plus the
-- late-attach helper (for Element.setProperty). All hooks delegate to the
-- frozen behavior instance so dispatch sites get the validated, frozen
-- implementation. shouldAttach is also exposed at module level (mirrors
-- Clickable.shouldAttach) for tests/callers without an element.
-local Animated = {
-  behavior = behavior,
-  ensureAttached = ensureAttached,
-  shouldAttach = shouldAttach,
-  onAttach = onAttach,
-  onUpdate = onUpdate,
-}
-
-- Metatable so the module table itself satisfies the duck-typed registry
-- contract (iterating `Element._behaviorRegistry` calls `behavior.shouldAttach`
-- and `behavior.onAttach` / `behavior.onUpdate` directly). Falls through to the
-- frozen behavior instance for every hook.
-setmetatable(Animated, {
-  __index = behavior,
-  __tostring = function()
-    return "Animated"
-  end,
-})
-
-return Animated
--- a/Show More
+++ b/Show More