Admit native Gen2 faint events with cartridge picture and audio timing

docs/native-gen2-event-queue.md

@@ -0,0 +1,31 @@
+# Native Gen2 typed event admission
+
+This change adapts the real upstream shared controller, on top of the native
+model boundary, rather than substituting a fork battle controller.
+`push`, `pushAll`, `pushFront` and the actual `advanceQueue` boundary share the
+existing queue. Supported kinds are message, item, weather, stage, run, money,
+win-text, move, damage, heal, status and text-pause. Unsupported kinds are
+explicit errors, rather than silently discarded combat events.
+
+Native producers emit observable messages/move announcements. Typing, VM,
+HP/status snapshots and sound completion remain owned by native presentation;
+HP/status snapshots never rewrite combat HP/status or spend PP. A queue
+observer runs at actual admission and sees the settled decision phase when an
+empty Gen2 queue returns. Gen2 resolving/moves spellings and older stored
+messages/moveSelect spellings reach the same update/draw/link owners.
+
+The move entry points run this upstream version's actual Gen2AnimPlayer. Its
+parameter is installed in that VM's vars; its clock remains native. This
+change does not fabricate the newer runner/OAM observation API around that
+older VM, and does not claim the fork's later object renderer/animation parity.
+
+Still outside this incremental change: send/faint/identity/Transform/experience,
+learning/catch/trainer/picker event consumers, the pure model constructor/turn
+protocol, checkpoint integration absent from this upstream base, unchanged
+client acceptance and Windows/macOS GPU/package qualification.
+
+Native queue and HP stepping retain the Gen1Recomp/upstream provenance noted
+in their source files. Original native-owner integration contributions are
+by Roxas2712; see the offered contribution licence:
+https://github.com/Roxas2712/Gen2Recomped/blob/main/LICENSE-ROXAS2712.md
+Existing third-party rights and notices remain effective.

docs/native-gen2-model-boundary.md

@@ -0,0 +1,38 @@
+# Native Gen2 model boundary
+
+`src.battle.gen2.Battle` is a distinct model class attached to the shared
+native battle controller by `Gen2BattleView`. It is not a name alias for
+`BattleState`, a second controller, or a detached copy of the saved party.
+Methods resolve through the class so an SDK-owned decoration also reaches
+already-created models and is restored by loader retirement.
+
+The boundary supplies live `moveDef`, `speciesDef`, `sideOf`, raw `battleStat`
+and `endBattle` operations. Damage, speed, status immunity, weather and shared
+move effects consult the native bound reads. Stages, badge/status/item
+modifiers, RNG and PP stay with their existing native owners. With no
+decoration the read returns the original native table, without a copy.
+Temporary stat/type answers do not replace a species registry row, party
+statistics, wrapper identity or checkpoint data. Explicit native
+Conversion/Transform types keep their priority over a species decoration.
+
+The native finish path invokes the model's end operation, including the
+skipped battle path. It raises one finish notification and permits transient
+cleanup before subscribers observe it. `completeBattle` runs the existing
+screen finish/return path, with repeated completion prevented from popping
+another screen. Existing native consumers retain the screen in the event's
+`battle`; the distinct model is available in `model`.
+
+This is an implemented boundary, not complete source-model parity. The split
+Gen2 model contract was inspected at Gen1Recomp `535a5ec0` and its current
+`e46d1eb2` counterpart. That model additionally has constructors and a pure
+turn/event API, which are not guessed from screen methods here. Its inspected
+class has no `battleStat` method; the raw-stat operation above is an explicit
+native extension, not a claim that all source versions expose it. Source
+event payload normalization and the remaining model operations still require
+separate implementation and acceptance. Existing project and third-party
+credits remain applicable.
+
+ROM-free coverage uses an SDK-loaded generic decorator and actual native
+damage, speed, status, switch, Transform and completion calls. It also checks
+restoration and direct table identity in other generations. It does not prove
+an unchanged client, GPU presentation, a full story run or a release package.

src/battle/BattleQueuePhase.lua

@@ -0,0 +1,15 @@
+-- One native queue, with the public Gen2 resolution phase. Earlier shared
+-- checkpoints retain their stored spelling until the next native update.
+local Version = require("src.core.GameVersion")
+local M = {}
+
+function M.name()
+  return Version.isGen2() and "resolving" or "messages"
+end
+
+function M.active(screen)
+  return screen.phase == "messages"
+    or (screen.phase == "resolving" and Version.isGen2())
+end
+
+return M