Native field, UI, palette and battle command adapters

.github/workflows/native-cartridge-views.yml

@@ -0,0 +1,41 @@
+name: Native cartridge observation views
+on:
+  pull_request:
+    paths:
+      - 'src/battle/Gen3SafariText.lua'
+      - 'src/battle/Gen3Battle.lua'
+      - 'src/core/game3/mb.lua'
+      - 'src/core/game3/constants.lua'
+      - 'src/import/gba/field_label_facts.lua'
+      - 'tests/engine/native_constant_queries.lua'
+      - 'src/core/game3/rom_text.lua'
+      - 'src/core/game3/battle/profile.lua'
+      - 'src/core/game3/battle/healthbox.lua'
+      - 'tests/engine/native_safari_text_views.lua'
+      - 'tests/engine/native_rom_text_ir.lua'
+      - 'tests/engine/compatibility_cell_semantics.lua'
+      - '.github/workflows/native-cartridge-views.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: native-cartridge-views-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contracts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Native authority and retired-view boundaries
+        run: |
+          luajit tests/engine/native_safari_text_views.lua
+          luajit tests/engine/native_constant_queries.lua
+          luajit tests/engine/compatibility_cell_semantics.lua
+          luajit tests/engine/native_rom_text_ir.lua
+          luajit tests/engine/native_battle_chrome.lua
+      - name: Existing native Gen2 presentation
+        run: |
+          luajit tests/engine/gen2_battle_window.lua
+          luajit tests/engine/gen2_battle_scene.lua

.github/workflows/native-file-picker.yml

@@ -0,0 +1,31 @@
+name: Native desktop file selection
+on:
+  pull_request:
+    paths:
+      - 'src/core/FilePicker.lua'
+      - 'src/core/HostShell.lua'
+      - 'src/import/RomImporter.lua'
+      - 'tests/engine/native_file_picker.lua'
+      - 'tests/*picker*'
+      - 'tests/rom_importer_android_mod_pick_test.lua'
+      - '.github/workflows/native-file-picker.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: native-file-picker-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contracts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Model desktop commands without opening dialogs
+        run: luajit tests/engine/native_file_picker.lua
+      - name: Preserve native pointer release and mobile fallback
+        run: |
+          luajit tests/parity_picker_pointer_grab.lua
+          luajit tests/rom_importer_no_picker_test.lua
+          luajit tests/rom_importer_android_mod_pick_test.lua

.github/workflows/native-flight.yml

@@ -0,0 +1,41 @@
+name: Native region picker and flight boundary
+on:
+  pull_request:
+    paths:
+      - 'src/compat/gen1/NativeRegionMap.lua'
+      - 'src/world/Gen3FlyTargets.lua'
+      - 'src/world/Gen3FlyArrival.lua'
+      - 'src/core/game3/field_effects.lua'
+      - 'src/render/Transition.lua'
+      - 'tests/engine/native_fly_arrival.lua'
+      - 'src/ui/Gen3RegionMap.lua'
+      - 'src/ui/Gen3RsRegionMap.lua'
+      - 'src/ui/game3/region_map.lua'
+      - 'src/ui/game3/rse/region_map.lua'
+      - 'src/core/game3/field.lua'
+      - 'src/world/OverworldController.lua'
+      - 'tests/engine/native_region_map_observations.lua'
+      - 'tests/engine/native_fly_boundary.lua'
+      - '.github/workflows/native-flight.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: native-flight-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contracts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Native observations and once-only departure
+        run: |
+          luajit tests/engine/native_region_map_observations.lua
+          luajit tests/engine/native_fly_boundary.lua
+          luajit tests/engine/native_fly_arrival.lua
+          luajit tests/engine/native_field_observations.lua
+      - name: Existing native admission and other generations
+        run: |
+          luajit tests/engine/gen2_battle_scene.lua

.github/workflows/native-phase-scopes.yml

@@ -0,0 +1,15 @@
+name: Native coroutine phase ownership
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  contracts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - run: sudo apt-get update && sudo apt-get install -y luajit
+      - run: luajit tests/engine/native_coroutine_phase_scopes.lua
+      - run: luajit tests/engine/native_game_coroutine_scopes.lua

LICENSE-ROXAS2712.md

@@ -0,0 +1,88 @@
+# Roxas2712 — Fork Contributions
+
+Version 1.0 · Effective 25 October 2026
+
+Copyright © 2026 Roxas2712, to the extent of rights held.
+All rights reserved except as expressly granted below or already granted.
+
+## 1. Scope and ownership
+
+This notice applies only to original contributions made by Roxas2712
+(GitHub: Roxas2712) to `Roxas2712/Gen2Recomped`, including original additions
+within modified files, insofar as he owns the relevant rights. Git history,
+pull-request diffs and source provenance identify contributions; a commit
+author or a whole-file change alone does not establish ownership of every
+part of that file.
+
+It does not claim ownership of Cedric's work, Gen1Recomp / BOIS CLUB GAMES
+work, other contributors' work, third-party dependencies, or ROM-derived
+content. Their applicable licences and notices remain in force. It does not
+grant permission to distribute the complete combined fork where another
+rights holder's permission is required.
+
+## 2. General permission and reserved rights
+
+For contributions covered by this notice and not already licensed more
+broadly, you may read and study the published source and make private,
+non-commercial modifications and builds for your own use. This grants no
+general permission to redistribute, sublicense, sell, or offer those
+contributions as a hosted service. Other uses require Roxas2712's
+written permission, except for the specific permission below and rights
+available independently under applicable law.
+
+Keep the relevant copyright, licence and attribution notices. Do not
+represent Roxas2712's contributions as exclusively authored by someone
+else. Public source availability alone does not put them in the public
+domain or grant an open-source licence.
+
+## 3. Specific permission for Cedric / UNDERdecoded
+
+Roxas2712 expressly grants Cedric (Ced; GitHub: UNDERdecoded /
+UNDERdecodedHD) a non-exclusive, worldwide, perpetual, royalty-free
+permission to use, reproduce, integrate, modify and distribute the covered
+contributions that Roxas2712 submits or expressly offers through pull
+requests to `UNDERdecoded/Gen2Recomped`, for Cedric's Gen2Recomped /
+RetroRecompiled project. This includes its renamed continuation maintained
+by Cedric, its official builds, and its commercial operation.
+
+Cedric may license the incorporated contributions to recipients as part of
+that project, subject to preserving this permission's applicable credit and
+notice requirements. This permission is not a copyright assignment, is not
+exclusive, and does not cover unpublished work, separate repositories,
+ModCompass service operation, credentials, or content not offered in those
+pull requests. Roxas2712 retains his own rights to his contributions.
+
+For uses relying on this permission:
+
+- retain the relevant source copyright and licence notices;
+- give visible credit in the project's README or equivalent public project
+  page, and in the application's existing About / Credits view, if present;
+- use at least the following credit, or a substantially equivalent one:
+
+  > Contributions by Roxas2712 —
+  > https://github.com/Roxas2712
+
+A maintained consolidated contributor credit is sufficient; a separate
+credit on every screen or for every change is not required. Adapted
+contributions must not be attributed exclusively to another author. Other
+contributors' credits must also remain intact.
+
+## 4. Earlier licences and permissions remain effective
+
+This notice does not revoke, narrow, or retrospectively add conditions to
+any permission already validly granted, including MIT / GPL grants,
+separate agreements, or permissions arising from previously submitted
+pull requests. Where an earlier grant permits a use independently of this
+notice, its existing terms govern that use. For such earlier uses, the
+visible credit above is requested to the extent it is not already required.
+
+For subsequent contributions, this is the default statement of Roxas2712's own reserved rights and the specific PR permission, subject to any
+applicable existing licence obligations or separately agreed terms. It
+does not change another rights holder's licence or guarantee compatibility
+of a particular combination of code.
+
+## 5. No warranty
+
+To the extent permitted by applicable law, these contributions are provided
+as is, without warranty. No support obligation, endorsement, or rights to
+third-party code, game assets, names, or trademarks are granted.

docs/native-battle-animation-runtime.md

@@ -0,0 +1,72 @@
+# Native battle animation bridge
+
+`src.core.game3.battle.anim` presents the admitted GBA battle through its native
+`BattleState`, `Gen3MoveAnim` and `Gen3BallAnim` owners. It does not load another
+battle engine or rewrite a mod package. FireRed, LeafGreen, Emerald, Ruby and
+Sapphire use the same boundary and their own imported identifiers and records.
+
+## Shared clock and ownership
+
+The native update opens one presentation phase. A source `Anim.update()` can
+advance that phase while a custom ending or pose holds the combat update.
+Repeated source calls and a later native base call consume the same display
+steps. The native dt drives sprite animations. Outside that phase, source
+updates cannot manufacture frames.
+
+Move/ball effects, visual waits, HP drain and EXP fill remain native operations.
+Only the native combat update consumes command rows, input and outcomes.
+Source-launched clips occupy the native animation player and hold the command
+queue until that clip finishes. A presentation serial distinguishes a finished
+source clip from a newer native animation on the same player. Reset/unload
+cancels only a clip still owned by that source admission.
+
+`present(id)` has stable identity for an admitted battler. It observes native
+display HP/maximum/level/status/EXP, visibility, offsets and affine effects.
+Source visual overrides compose around the existing native sprite draw;
+reading a native effect never applies it a second time. `shownBattler` carries
+an owned presentation override without replacing the native combatant.
+Replacing the session, save, data or catalogue retires old poses and callbacks.
+
+`GameVersion.layout(id)` also reports the registered GBA family (`frlg` or
+`rse`) so an unchanged field companion probe can recognize the native host.
+It supports current-version and colon queries without changing cache/save
+selection; an explicit registered layout takes precedence.
+
+## Geometry and screen effects
+
+`anim_coords` exposes authored anchors and ordering for singles and doubles.
+Current imported cartridge coordinates take precedence over the standard
+240x160 anchors. Temporary side bindings restore on success and failure and
+preserve trailing nil arguments/results.
+
+Supported screen effects are inversion, fade to white/black, darkening,
+grayscale and blending to a custom colour. Repeated begin calls reapply within
+one guarded render seam; nested seams restore their caller's shader. The native
+graphics guard restores render targets, transforms, shaders and leaked pushes
+after an error. Synthetic asymmetric sprites test orientation as well as colour.
+
+## Current boundary
+
+This bridge implements native move launch/observation, source pose tweens,
+display ratios, sequence observations, screen effects and coordinate bindings.
+It deliberately does not advertise a complete presentation API version.
+Authored animation commands, mutable VM/sprite/task/palette callbacks,
+particle bands, trainer/intro/switch/catch stage control, source HP/EXP tween
+commands and complete custom UI captures still require integration. A module
+being importable is not evidence of a complete mod boot or playable campaign.
+
+## Validation
+
+- `tests/engine/native_battle_animation.lua`: all five editions; shared clocks,
+  owned clip completion, held command queues, stale poses/callbacks and 180-frame
+  native trajectory comparisons per edition with and without the bridge.
+- `tools/battle-animation-runtime/lifecycle-check.lua`: SDK entry failure,
+  teardown and native peer callback identities.
+- `tools/battle-animation-runtime/coords-check.lua`: optional local contract
+  oracle supplied through `BATTLE_COORDS_ORACLE`; no external engine is bundled.
+- `tools/battle-animation-runtime/host`: actual Metal/OpenGL sprite and screen
+  effect rendering, pixel comparisons and graphics error restoration.
+
+Local qualification runs use the repository's QA storage manager, frozen source
+copies and dedicated LOVE identities. They use synthetic imported data and art;
+they do not open player profiles, save files or ROM originals.

docs/native-battle-chrome.md

@@ -0,0 +1,42 @@
+# Native battle chrome and particle observations
+
+Battle panel wrappers enter the existing native panel pass. Repeated base
+calls paint once, including translucent artwork. Window queries use imported
+cartridge templates and the actual native surface width. Healthbox captures
+validate the current battle and battler, use native geometry, and apply owned
+offsets inside a restored graphics scope. Native shown ailment state stays
+separate from queued logical status changes.
+
+Trainer images and picture offsets resolve from native imported records.
+Additional genuine window templates and the native trainer portrait index
+are retained by new imports. Existing imports retain their available records;
+unavailable windows and artwork are reported rather than invented.
+
+The particle observation module projects actual native event poses at the
+current clip/frame. It cannot advance a clock or create combat particles.
+Reversible position, scale, reflection, visibility and custom drawing changes
+compose around the same native event painter, including OAM-composited draws.
+The ordinary native path avoids these observations until a consumer asks for
+the pool. Retired events and unloaded owners leave no visible source rows.
+This is not a complete external animation VM or managed-sprite API.
+
+ROM-free tests cover all five GBA editions. The real Metal/OpenGL host uses
+asymmetric synthetic sprites and panels, independent pixel remapping, native
+text shaders, multiple logical widths and healthbox offsets. It does not load
+the original package or demonstrate complete gameplay.
+
+The unchanged local package has progressed beyond the previously missing
+battle chrome, healthbox, trainer-picture and picture-coordinate imports.
+Additional battle/UI contracts remain. The complete battle presentation
+protocol is not advertised by this change. No private runtime or cartridge
+assets are included.
+
+## Public-host composition
+
+The API-2 candidate builds on #327 and its declared prerequisites. It passes
+315 chrome/particle, 916 companion, 1,466 terrain, 486 collision and nine
+lifecycle checks, plus 3/3 SDK suites. Engine: 95/106 versus reference 94/105,
+with the identical eleven inherited failed suites. Actual Metal and OpenGL
+runs each pass the same 778 graphics checks, 90 comparisons and 185 readbacks
+on the composed public candidate. No full unchanged-package gameplay
+acceptance is inferred from those fixtures.