Port Repels and the other non-fishing field items

Repel, Super Repel and Max Repel count down 100, 200 or 250 steps where
CountStep does, keep weaker wild Pokémon away from the first party member
that has not fainted, and print "REPEL's effect wore off." on the last
step. The Coin Case and the Blue Card show their balances, Sacred Ash
revives the party once one Pokémon has fainted, and the Normal and
Gorgeous Boxes send their trophy home.

The Itemfinder looks for unfound hidden items on the original's screen
around the player. The Card Key, the Basement Key and the Squirtbottle
run the original's checks for their doors and Sudowoodo, whose maps are
not open yet. Saves gain the Repel's steps, the coins and the Blue Card's
points.

Part of #27

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

docs/NATIVE_PORT.md

@@ -32,7 +32,7 @@ These paths refer to the pinned [PRET source](https://github.com/pret/pokecrysta
 | Movement interpreter             | `macros/scripts/movement.asm`, `engine/overworld/movement.asm`, `engine/overworld/map_objects.asm`                             | Turns, steps, slides, jumps (two tiles with the original arc), sleeps, facing locks, visibility and emotes. `follow` takes one tile toward the leader's previous square. All movement opcodes decode, including teleport, fishing, skyfall, shake and flicker poses; Controlled reference scenes check spin, teleport, skyfall, fishing and flicker direction, visibility and lift.                                                              |
 | Specials                         | `data/events/special_pointers.asm`, `engine/rtc/timeset.asm`, `engine/overworld/decorations.asm`                               | Selected by routine address from the ROM table: `SetDayOfWeek`, initial DST flags, `RestartMapMusic` (no audio yet), room decoration toggles, `PokemonCenterPC` and `PlayersHousePC` (Bill's, the player's and Oak's PCs), the Town Map, `HealParty`, `HealMachineAnim` (presentation only), `CheckPokerus` and the `StubbedTrainerRankings_Healings` stub.                                                                              |
 | `game/scripts/pc.ts`             | `engine/events/pokecenter_pc.asm`, `engine/pokemon/bills_pc_top.asm`, `engine/pokemon/bills_pc.asm`, `engine/events/prof_oaks_pc.asm`, `engine/events/std_collision.asm` | The Pokémon Center and house PCs: Bill's PC (deposit, withdraw, release, change and name boxes, MOVE PKMN W/O MAIL, stats), item storage, the empty mail box and Oak's rating. Menu strings and texts come from the ROM; lists are native. Printing is not ported. |
-| `game/scripts/start-menu.ts`     | `engine/menus/start_menu.asm`, `engine/pokemon/mon_menu.asm`, `mon_submenu.asm`, `party_menu.asm`, `switchpartymons.asm`, `engine/items/pack.asm`, `engine/items/item_effects.asm` | The start menu, the party menu with the Pokémon submenu (STATS, SWITCH, MOVE, ITEM) and the pack (USE, GIVE, TOSS) with the field item effects listed below, including Rare Candy, stones and vitamins. Menu strings, prompts and texts come from the ROM; screens are native. Field moves from the menu (checked by the world), Softboiled and Milk Drink, SEL and the Select button (`SelectMenu`). MAIL and the other field items give a notice. |
+| `game/scripts/start-menu.ts`     | `engine/menus/start_menu.asm`, `engine/pokemon/mon_menu.asm`, `mon_submenu.asm`, `party_menu.asm`, `switchpartymons.asm`, `engine/items/pack.asm`, `engine/items/item_effects.asm` | The start menu, the party menu with the Pokémon submenu (STATS, SWITCH, MOVE, ITEM) and the pack (USE, GIVE, TOSS) with the field item effects listed below, including Rare Candy, stones and vitamins. Menu strings, prompts and texts come from the ROM; screens are native. Field moves from the menu (checked by the world), Softboiled and Milk Drink, SEL and the Select button (`SelectMenu`). MAIL and the rods give a notice. |
 | `game/scripts/pokegear.ts`       | `engine/pokegear/pokegear.asm`, `engine/phone/phone.asm`, `engine/phone/scripts/mom.asm`, `elm.asm`, `engine/rtc/print_hours_mins.asm` | `PokeGear` with each card's joypad handling: the clock (`Pokegear_UpdateClock`, `PrintHoursMins`), the map card's landmark cursor (`TownMap_InitCursorAndPlayerIconPositions`, `TownMap_GetKantoLandmarkLimits`), the phone list (`PokegearPhone_UpdateDisplayList`, `GetCallerClassAndName`, `PokegearPhoneContactSubmenu`, `CheckCanDeletePhoneNumber`) and calls (`MakePhoneCallFromPokegear`, `CheckPhoneContactTimeOfDay`, `GetMapPhoneService`, `HangUp`). Callee scripts run in the event interpreter on the start menu's draft. Screens are native; the radio's stations are not ported. |
 | `game/scripts/trainer-card.ts`   | `engine/menus/trainer_card.asm`, `engine/gfx/player_gfx.asm` (`GetCardPic`), `engine/gfx/cgb_layouts.asm` (`_CGB_TrainerCard`), `home/game_time.asm` | `TrainerCard`'s two reachable pages with their joypad rules, strings from `.Name_Money`, `.Dex_PlayTime` and `.Badges`, the caught count, and the badges from `TrainerCard_JohtoBadgesOAM` with their eight-frame steps. `rendering/trainer-card.ts` draws the card picture, leader faces and badges from the ROM with the card's palettes and attribute map. `world/game-time.ts` is `GameTimer` (capped at 999:59:59). Text is native; the blinking colon's and badges' phase start at the page load. |
 | `game/scripts/options.ts`        | `engine/menus/options_menu.asm`, `data/default_options.asm`, `engine/battle/core.asm` (`CheckWhetherToAskSwitch`), `engine/menus/start_menu.asm` | `_Option` with `OptionsControl` and each option's routine on the four option bytes, `DefaultOptions`, and the two settings consumed so far: `BATTLE_SHIFT` and `MENU_ACCOUNT`. Strings come from the ROM; the screen is native. |
@@ -317,7 +317,15 @@ and then `_DoItemEffect` by the `ItemEffects` routine address, with the
 field side of `RestoreHPEffect`, `StatusHealingEffect`, `FullRestoreEffect`,
 `ReviveEffect`/`RevivalHerbEffect`, `EnergypowderEffect`/`EnergyRootEffect`,
 `HealPowderEffect` and `RestorePPEffect` (Ether, Max Ether, Elixer, Max
-Elixer, MysteryBerry and PP Up with `ApplyPPUp`). Items are used from the
+Elixer, MysteryBerry and PP Up with `ApplyPPUp`), and since the remaining
+field items increment `UseRepel` (`UseItemText`), `CoinCaseEffect`,
+`BlueCardEffect`, `_SacredAsh` (`CheckAnyFaintedMon`, then the queued
+`SacredAshScript`), `OpenBox` (`DecorationIDs`, then the decoration's
+event flag), `ItemFinder` (the world's `CheckForHiddenItems` picks the
+queued script), `_CardKey`, `_BasementKey` (map and facing tile in
+`wPlayerMapX/Y` coordinates) and `_Squirtbottle`, whose
+`.CheckCanUseSquirtbottle` asks the world's `GetFacingObject` and leaves the
+object in `hLastTalked`. Items are used from the
 Items pocket slot they were chosen from (`wCurItemQuantity`).
 `ItemActionTextWaitButton` prints `PrintPartyMenuActionText` with the HP
 change. `ChangeHappiness` outside battle does not touch a battle Pokémon.
@@ -339,6 +347,24 @@ while the menu is open. A Chromium/WebKit test opens the menu with Start,
 switches Pokémon, changes pockets and tosses a Potion. These are not
 emulator comparisons.
 
+`DoRepelStep` runs in the world where `CountStep` calls it, after
+`CheckSpecialPhoneCall`; the poison, happiness, egg, Day-Care and bike
+steps of `CountStep` are not ported yet. `RepelWoreOffScript` starts with
+the step's committed position, like a coordinate event, and its committed
+save keeps the last Repel step; a wild battle's committed save likewise
+keeps the step's count. `TryWildEncounter`'s `CheckRepelEffect` follows
+`ChooseWildEncounter`. `text_ram` of `wPlayerName`, `wRivalName` and
+`wMomsName` reads the text context's names.
+
+Tests: `tests/field-items.test.ts` (local ROM) uses each Repel, walks with
+one through a test-only grass table (weaker Pokémon kept away, a fainted
+lead, an equal level let through, the last step's message and its replay
+after a reload), and covers the Coin Case, the Blue Card, Sacred Ash with
+and without a fainted Pokémon, both boxes, the save migration, the
+Itemfinder at each edge of the screen around Route 30's hidden Potion,
+the keys (a start-menu run with the unopened maps' positions) and the
+Squirtbottle (the interpreter facing a test Sudowoodo on Route 36).
+
 ## Evolution
 
 The battle's experience routine sets a party member's bit in
@@ -430,8 +456,8 @@ animations as timed `fly` effects (65 and 33 ticks). The Escape Rope
 chamber's wall there (`SpecialKabutoChamber`) and using up one rope; a
 failure prints nothing before Oak's warning. `JumpRoamMons` (no roaming
 Pokémon yet) and the fades are not modelled. A destination map that is not
-ported gives a notice. `TreeMonEncounter` and `RockMonEncounter` are not
-ported and give a notice after their checks.
+ported gives a notice. `TreeMonEncounter` and `RockMonEncounter` run since
+the Headbutt and Rock Smash increment.
 `Softboiled_MilkDrinkFunction` runs in the menu with `GetOneFifthMaxHP`,
 `RemoveHP` and `RestoreHealth`, refusing the user itself and Pokémon that
 fainted or are at full HP.

docs/PLAN.md

@@ -169,7 +169,7 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - PACK: the Items, Balls, Key and TM pockets (left and right change pockets; there are no TMs or HMs yet), and each item's submenu chosen by its permissions and field menu (`USE`, `GIVE`, `TOSS`, `SEL`, `QUIT`). TOSS asks how many and confirms. USE follows `UseItem`: Oak's warning without a field use, "You don't have a POKéMON!" for party items without one, and `_DoItemEffect` by the item's `ItemEffects` address: Potions and the other `HealingHPAmounts` items, status healers, Full Restore, Revive and Max Revive, the bitter Energypowder, Energy Root, Heal Powder and Revival Herb, Ethers, Elixers, the MysteryBerry and PP Up. The Bicycle closes the menu and runs `Script_GetOnBike` or `Script_GetOffBike` outdoors; elsewhere Oak objects, because `wFieldMoveSucceeded` shares `wItemEffectSucceeded`'s byte.
 - PP Up keeps a quirk: `wUsePPUp` shares `wTempPP`'s byte, so `ComputeMaxPP` adds one step (a fifth of the base PP, at most 7) to the current PP as well as the maximum. Sketch and moves with three PP Ups are "maxed out".
 - The menu runs on a script draft, like the PC. Changes commit when it closes; a save made while it is open keeps the state from before it. The start menu cursor, the party menu cursor and the last pocket stay in memory between openings and are cleared after a battle, as `CleanUpBattleRAM` does. The party cursor reaches the next battle's `ChangeHappiness`.
-- Not ported: MAIL, moving a Pokémon's moves to another party member with left and right, item reordering with Select and the remaining field items such as Repel (each gives a notice and changes nothing; the Escape Rope runs since the Fly section below). Rare Candy, evolution stones and vitamins run since the evolution section below; field moves, SEL and Select since the section after it.
+- Not ported: MAIL, switching to another party member's moves with left and right, item reordering with Select and the fishing rods (each gives a notice and changes nothing; the Escape Rope runs since the Fly section below, Repels and the other items of the last section since then). Rare Candy, evolution stones and vitamins run since the evolution section below; field moves, SEL and Select since the section after it.
 
 ## Implemented: evolution
 
@@ -240,6 +240,16 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - Talking to a smashable rock runs `SmashRockScript`: "Maybe a POKéMON can break this." without Rock Smash (`HasRockSmash`), otherwise the question; ROCK SMASH from the party menu skips it and acts on the facing rock as `hLastTalked`. The earthquake, the rock's flicker and its disappearance run from the ROM's script, then `RockMonEncounter`: the map's `RockMonMaps` set and a 40% chance of a wild battle.
 - Unreachable in normal play so far: no open map has rocks, and no Pokémon available yet learns Headbutt (the Ilex Forest tutor) or Rock Smash (a TM on Route 36). Route 29 and Route 30 have tree sets.
 
+## Implemented: the remaining field items
+
+- Repel, Super Repel and Max Repel set `wRepelEffect` to 100, 200 or 250 steps ("used the REPEL."), unless "The REPEL used earlier is still in effect.". Each step counts one off where `CountStep` does, after trainer, warp and coordinate events and a special call; the last one prints "REPEL's effect wore off." instead of looking for a wild Pokémon. Under a Repel, wild Pokémon below the level of the first party member that has not fainted are not met (`CheckRepelEffect`); Sweet Scent and Headbutt ignore it, as in the original. A save during the message or a battle replays the step with its Repel step.
+- The Coin Case shows `wCoins` and the Blue Card `wBlueCardBalance`; nothing earns coins or points yet (the Game Corner and the radio's Buena show).
+- Sacred Ash: when a Pokémon that is not an Egg has fainted, the menu closes and `SacredAshScript` heals the whole party; otherwise Oak objects.
+- The Normal Box and the Gorgeous Box hold the silver and the gold trophy doll (`SetSpecificDecorationFlag`), sent home for the bedroom PC.
+- The Itemfinder answers "Yes! ITEMFINDER indicates there's an item nearby." when a hidden item not found yet lies on the original's screen around the player (`CheckForHiddenItems`: four squares left and up, five right, four down), and "Nope!" otherwise. Route 30's hidden Potion is the only one on an open map.
+- The Card Key and the Basement Key run their door scripts only facing the Radio Tower 3F slot or the Goldenrod Underground door (Oak objects elsewhere). The Squirtbottle sprinkles water, and on Route 36 starts the Sudowoodo battle when facing it (`WateredWeirdTreeScript`). None of these maps is open yet.
+- Save format 3 gained `repel`, `coins` and `blueCardBalance`, migrated by absence to 0.
+
 ## 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.