Port Kurt's balls and the Park Ball's multiplier (#28)

Add the Heavy, Level, Lure, Fast, Friend, Moon and Love Balls with their documented bugs, the Park Ball's multiplier outside the contest, and Friend Ball happiness in the party and the PC. The Heavy Ball is refused for Kadabra and Sunflora, whose original weight read runs into VRAM.

The reference emulator compares 6,153 more catch states per browser against the unmodified PokeBallEffect. Validated with 582 unit tests, 153 browser tests, native/reference builds and reference/vendor/release checks. The Bug-Catching Contest and other special battle types remain on #28.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/NATIVE_PORT.md

@@ -150,8 +150,8 @@ tests cover the house, the rival battle and the naming field.
 
 ## Capture and the catching tutorial
 
-`PokeBallEffect`, `BallMultiplierFunctionTable` (Poké, Great, Ultra and
-Master Balls), `GetPokeBallWobble` with `WobbleProbabilities`,
+`PokeBallEffect`, `BallMultiplierFunctionTable` (every ball, including
+Kurt's and the Park Ball outside the contest), `GetPokeBallWobble` with `WobbleProbabilities`,
 `UseBallInTrainerBattle` and `BattleMenu_Pack`'s `.UseItem` in
 `engine/items/item_effects.asm`, `engine/battle_anims/pokeball_wobble.asm`
 and `engine/battle/core.asm`. The catch rate is computed with the original
@@ -260,8 +260,11 @@ named by `hBattleTurn` after a switch of turns, which can be the enemy.
 player's turn, `HandleHealingItems` ends a full turn on the enemy's, and
 the trainer AI reports when `AI_Types`, `AI_Status` or `AIDamageCalc`
 set it. A status heal after a full turn therefore penalises a paralysed
-or burned enemy again, as the original does. Remaining gaps: the special
-Kurt and Park balls.
+or burned enemy again, as the original does. Kurt's balls keep their
+documented bugs (Heavy Ball bank, Fast Ball's three bytes, Moon Ball's
+BURN_HEAL compare, Love Ball's same gender). The Heavy Ball is refused for
+Kadabra and Sunflora, whose original weight read runs into VRAM. The
+Bug-Catching Contest's Park Ball count and contest Pokémon remain gaps.
 
 `engine/pokemon/stats_screen.asm`: the stats screen's three pages (HP,
 status, types, experience to the next level; item and moves with PP; ID,

docs/PLAN.md

@@ -116,7 +116,7 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - `GetPokeBallWobble` runs with `WobbleProbabilities` for each shake and picks the break-free message. Every throw uses the ball and, if the Pokémon breaks free, the turn. In trainer battles the ball is blocked, but the ball and turn are still used.
 - A caught Pokémon is reloaded as `LoadEnemyMon` does, which redraws the wild item roll (the item itself is kept). It keeps its current HP, status, item and DVs, and gets back the moves and full PP it appeared with. It joins the party with `SetCaughtData`, is registered as caught (with the new-data message once the Pokédex is owned) and can be nicknamed; a blank name keeps the species name. The Pokédex page itself is not presented yet.
 - Route 29's `Route29Tutorial1/2` and `CatchingTutorialDudeScript` run from the ROM. `catchtutorial` runs the battle as "DUDE": no Pokémon is sent out, the Dude's own Poké Ball always catches, and the Rattata is only seen, not kept. Messages advance on their own, as with `CatchTutorial`'s auto input.
-- A catch with six Pokémon in the party goes to the current box (see the PC section below). Other balls (Kurt's balls, Park and Safari) and non-ball items in battle are not usable yet.
+- A catch with six Pokémon in the party goes to the current box (see the PC section below). Other balls (Kurt's balls, Park and Safari) and non-ball items in battle are not usable yet. (Kurt's balls followed; see below.)
 - A local stress run of 2,160 wild battles (three starters, ten early species, six levels) caught 2,047 Pokémon without refusals.
 - Next: the PC and boxes, player switching and other items in battle, then party and bag menus.
 
@@ -304,11 +304,18 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - Every `AI_Smart_EffectHandlers` entry is translated, so trainers with the Smart layer are no longer refused. The handlers read battle history, stat levels, both parties' reserves, the switch score and the weather.
 - The AI's type checks keep the original `CheckTypeMatchup` bug: the move type and Foresight flag come from whichever side `hBattleTurn` names, so Encore and the switch score can read the player's move struct. Conversion2's write to the player's move type persists, as in the original.
 - `tests/reference-smart-ai.spec.ts` runs the unmodified `AI_Smart` routine in the reference emulator over 6,024 states (all 251 moves, random battle state, either starting turn), comparing scores, Random consumption, `hBattleTurn` and the player's move type. A one-off run over 18,072 more states also matched in both browsers.
-- Card #28 stays in progress for Kurt's balls, the Park and Safari balls and the special battle types.
+
+## Implemented: Kurt's balls
+
+- The Heavy, Level, Lure, Fast, Friend, Moon and Love Balls and the Park Ball (outside the contest) can be thrown. Their documented bugs are kept: the Heavy Ball reads Tauros's weight from the wrong bank, the Fast Ball checks only Magnemite, Grimer and Tangela, the Moon Ball never boosts, and the Love Ball boosts for the same gender. The Level Ball skips the HP, status and held-item terms. A Friend Ball catch gets 200 happiness, in the party or the PC.
+- For Kadabra and Sunflora the original Heavy Ball scan runs off the wrong bank into VRAM, so that throw is refused.
+- `tests/reference-capture.spec.ts` runs the unmodified `PokeBallEffect` over 6,153 more states per browser: every species for the Heavy, Fast, Moon and Love Balls, level pairs for the Level Ball and fishing for the Lure Ball.
+- There is no Safari Ball to port: `SAFARI_BALL` is Moon Stone's item number and never reaches `PokeBallEffect`.
+- Card #28 stays in progress for the Bug-Catching Contest's battle type (Park Ball count, contest Pokémon) and the other special battle types.
 
 ## Native battles: current state
 
-The battle core, ROM tables, encounter hooks, battle UI and whiteout hooks are present. Unit tests cover wins, escape, loss, experience, move learning and capture; reference tests compare damage, type effectiveness, stat calculation and experience curves. Browser tests drive a test-only wild encounter through the real UI: victory with level-up and move learning, escape, whiteout, catching with a nickname, keyboard and on-screen D-pad menu navigation, mid-battle backup restore, rollback of unsupported effects, switching through the party menu and a Potion from the Items pocket. Real Route 29 encounters now use the ROM's encounter tables. Only the special Kurt and Park balls remain unported among battle items.
+The battle core, ROM tables, encounter hooks, battle UI and whiteout hooks are present. Unit tests cover wins, escape, loss, experience, move learning and capture; reference tests compare damage, type effectiveness, stat calculation and experience curves. Browser tests drive a test-only wild encounter through the real UI: victory with level-up and move learning, escape, whiteout, catching with a nickname, keyboard and on-screen D-pad menu navigation, mid-battle backup restore, rollback of unsupported effects, switching through the party menu and a Potion from the Items pocket. Real Route 29 encounters now use the ROM's encounter tables. Every ball can be thrown; only the contest's Park Ball handling remains.
 
 This is still not a complete new game. The Pokégear's radio, the Pokédex screen, story progression beyond Route 30 and Mr. Pokémon's house, and audio remain unfinished. The start menu opens the party menu and the pack, and Select uses the registered item, such as the Bicycle; the PCs store Pokémon, items and decorations. Surfing and terrain animation now have native implementations; later maps remain gated. Save slots, a Johto/Kanto atlas, Pokédex records, online Link, friends and real-world steps come later.
 
@@ -388,7 +395,7 @@ Introduce native player, party, Pokémon, inventory, money and quest models. Rea
 
 Expand script calls, choices, scene state, inventory commands and native special handlers. Translate routines reached through assembly calls into explicit native services; never fall back to emulator execution in the shipping game.
 
-Meeting Mom, Elm's introduction, the starter, the aide's Potion, Route 29, Cherrygrove, Route 30's trainers, Mr. Pokémon's house, the Cherrygrove rival battle, the return to Elm, capture, the catching tutorial, the PC, the introduction's naming and clock screens, and switching and healing items in battle run now. The opening milestone is complete within the recorded acceptance boundaries. The start menu, party menu and pack now run outside battle, and Pokémon evolve. Field moves from the menu, SEL/Select and MOVE PKMN W/O MAIL run too, and the Pokégear's clock, map and phone cards, with calls to Mom and Elm, Mom's bank at home and her purchases, the trainer card with the play time, the options, Fly, Dig, Teleport and the Escape Rope, and Headbutt and Rock Smash with their encounters, every remaining field item, the fishing rods, MAIL, moving items with Select and the MOVE screen's other Pokémon. Next: Kurt's balls, the Park and Safari balls and the special battle types (board #28).
+Meeting Mom, Elm's introduction, the starter, the aide's Potion, Route 29, Cherrygrove, Route 30's trainers, Mr. Pokémon's house, the Cherrygrove rival battle, the return to Elm, capture, the catching tutorial, the PC, the introduction's naming and clock screens, and switching and healing items in battle run now. The opening milestone is complete within the recorded acceptance boundaries. The start menu, party menu and pack now run outside battle, and Pokémon evolve. Field moves from the menu, SEL/Select and MOVE PKMN W/O MAIL run too, and the Pokégear's clock, map and phone cards, with calls to Mom and Elm, Mom's bank at home and her purchases, the trainer card with the play time, the options, Fly, Dig, Teleport and the Escape Rope, and Headbutt and Rock Smash with their encounters, every remaining field item, the fishing rods, MAIL, moving items with Select and the MOVE screen's other Pokémon. Kurt's balls are thrown too. Next: the Bug-Catching Contest and the other special battle types (board #28).
 
 Complete and validate the native battle engine: deterministic randomness, stats, move selection, accuracy/critical checks, damage, status, turn order, switching, fainting, experience, capture and rewards. Compare controlled seeds and states with the original, including integer rounding and overflow behavior.
 

docs/SESSION_HANDOFF.md

@@ -1250,3 +1250,29 @@ physical-device validation.
 
 Next on #28: Kurt's balls, Park and Safari balls, and special battle types.
 Other boundaries listed in the previous section are unchanged.
+
+## Kurt's balls: 2026-10-03
+
+Same session, after the Smart AI commit.
+
+- `Battle.kurtBallRate` translates the Heavy, Level, Lure, Fast, Moon and
+  Love multipliers; `catchRate` adds the Park Ball's 1.5× and the Level
+  Ball's skip of the HP, status and held-item terms. Friend Ball catches
+  get 200 happiness in the party or the PC box.
+- The Heavy Ball's buggy bank makes Kadabra's (64) and Sunflora's (192)
+  scans run past $7fff into VRAM, which the port does not model; those
+  throws raise `UnsupportedBattle`. Tauros (128) reads a wrong in-ROM
+  weight, which is reproduced.
+- `tests/reference-capture.spec.ts` gained a 6,153-state comparison
+  against the unmodified `PokeBallEffect`. Mutating the Love Ball gender
+  test or the Fast Ball's byte count fails it. A Heavy Ball light-mon
+  off-by-one mutation is undetectable: rates 0 and 1 both end at 1.
+
+Validation: 582 unit tests passed (3 skipped); without the ROM 139 passed,
+446 skipped. Browser suite: 153 passed, 19 skipped. Both builds,
+reference/release/vendor checks and `git diff --check` passed.
+
+Next on #28: the Bug-Catching Contest battle type (Park Ball count,
+`BugContest_SetCaughtContestMon`) and the other special battle types.
+Neither is reachable yet: National Park and the legendary encounters
+are not enabled.