Add the TM/HM pocket, Egg screens and Violet's remaining scripts

The pack's TM/HM pocket lists TMs and HMs with their moves, gives TMs and teaches either through the ABLE/NOT ABLE party menu, the compatibility and "already knows" checks and LearnMove; a TM is used up and makes the Pokémon happier. Eggs show no level or HP in the party menus, get the Egg stats page with its hatching hint, and are skipped by HealParty. Bug Catcher Wade's number registers (VAR_CALLERID and RandomPhoneMon).

The playthrough now runs through Falkner's ZEPHYRBADGE, the Togepi Egg, Kyle's Onix, Flash in Dark Cave, Wade's number and Earl's blackboard. With MAKE_TEST_SAVES it writes a Violet City backup for the manual checks.

Validated with 610 unit tests, 157 browser tests (including all 256 badge bytes against the original BadgeStatBoosts), native/reference builds and reference/vendor/release checks. Egg hatching (#29) and trainer calls (#30) remain on their cards.

Closes #31

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

docs/NATIVE_PORT.md

@@ -114,7 +114,7 @@ A trainer sighting whose script is refused is not restarted until the player mov
 
 ## Next slice
 
-Route 29, Cherrygrove, Route 30 and Mr. Pokémon's house are enabled with item balls, hidden items, fruit trees and the daily reset, the Pokémon Center nurse, the recorded whiteout spawn, map trainers, the first rival battle, Elm's special call, capture and the catching tutorial. NPCs roam. The PC and boxes are ported. Next: party, bag and Pokégear menus over the native models. Other specials stay refused until translated.
+Route 29, Cherrygrove, Route 30, Mr. Pokémon's house, Route 31, Violet City, Sprout Tower and Dark Cave's Violet entrance are enabled with item balls, hidden items, fruit trees and the daily reset, the Pokémon Center nurse, the recorded whiteout spawn, map trainers, the first rival battle, Elm's special call, capture and the catching tutorial. NPCs roam. The PC and boxes are ported. Next: party, bag and Pokégear menus over the native models. Other specials stay refused until translated.
 
 ## Reflect and Light Screen
 

docs/PLAN.md

@@ -15,6 +15,7 @@ The emulator-backed prototype is now at `/reference.html`. The default applicati
 | Exploration foundation, rendering, saves and shell                           | Done                                    |
 | Opening story: New Bark Town to Mr. Pokémon, the rival and the return to Elm | Done                                    |
 | Route 29, Cherrygrove City, Route 30 and their buildings                     | Done                                    |
+| Route 31, Violet City, Sprout Tower and Falkner's gym                        | Done (Dark Cave: Violet entrance only)  |
 | Wild and trainer battles, capture and the catching tutorial                  | Done for the areas that are open        |
 | 1. Complete the overworld foundation                                         | Done                                    |
 | 2. Opening story and first battle slice                                      | Mostly done                             |
@@ -320,11 +321,21 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - Scripts can load the forced-shiny, trap, forced-item, Suicune and contest types with `loadvar VAR_BATTLETYPE`.
 - Still to come with their maps: National Park's contest event (registration, timer, judging; the contest state is not saved), Raikou's, Entei's and Suicune's roaming, and the Ilex Forest Celebi event with `CheckCaughtCelebi`.
 
+## Implemented: Route 31 to Violet City and the first gym
+
+- Route 31 and its Violet gate, Dark Cave's Violet entrance, Violet City with its Mart, gym, Earl's Pokémon Academy, the nickname speech house, the Pokémon Center and Kyle's house, and Sprout Tower's three floors are open, with their scripts, trainers, items, fruit trees and encounters. Route 32, Route 36, Dark Cave's other entrances and the Pokémon Center's second floor stay closed.
+- New script commands: `gettrainername`, `askforphonenumber` (AddPhoneNumber keeps room for Mom and Elm; `addcellnum` now reports failure as the original does), `checkpokemail`, `loadmenu`/`_2dmenu`/`closewindow` (Earl's blackboard, shown as a list), `giveegg`, `trade` (NPCTrade with saved `wTradeFlags`), `loadvar VAR_CALLERID` and the `RandomPhoneMon` special. The trade animation is not presented.
+- Eggs keep their species with an `egg` flag, as `wPartySpecies` holds EGG: the party menu shows no level or HP, the stats screen shows the Egg page with its hatching hint, healing skips them, and `checkpoke` does not count them. Eggs do not hatch yet (board #29).
+- The pack's TM/HM pocket holds counts by number: TMs and HMs are received, listed with their moves, given (TMs) and taught with ABLE/NOT ABLE, the compatibility and "already knows" checks and LearnMove. A TM is used up and makes the Pokémon happier; an HM stays.
+- The Johto badges raise the battle Pokémon's stats (BadgeStatBoosts, with the PlainBadge/MineralBadge swap and the Glacier Badge register bug), compared against the unmodified routine for all 256 badge bytes in `tests/reference-badges.spec.ts`.
+- `tests/playthrough.test.ts` now continues to Route 31 (Mom's call), Sprout Tower (Elder Li's Flash), Falkner (the ZEPHYRBADGE, TM31 and the aide's call), the Togepi Egg, Kyle's Onix, Flash in Dark Cave, Wade's number and Earl's blackboard. `tests/violet.test.ts` covers the other answers.
+- Kenya's MAIL is checked as the original does, but it is given at the Route 35 gate, which is closed; its text (a 15-letter first line) is one the port's MAIL model cannot yet store. Wade's calls, rematches and gifts come with the phone (board #30).
+
 ## 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. 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.
+This is still not a complete new game. The Pokégear's radio, the Pokédex screen, story progression beyond Violet City and Falkner's gym, 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.
 
 ## 1. Complete the overworld foundation
 
@@ -402,7 +413,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. Kurt's balls are thrown too, and the battle engine handles every special battle type (board #28 is complete). Next: Route 31 to Violet City (board #31).
+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, and the battle engine handles every special battle type (board #28 is complete). Route 31, Violet City, Sprout Tower and Falkner's gym are open (board #31). Next: the CI run of the synthetic suite (board #45), then the remaining Johto cities (board #32).
 
 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.
 
@@ -411,7 +422,7 @@ Acceptance: finish the opening quest, including encounters and the rival battle,
 ## 3. Complete Crystal
 
 - [x] Pokémon Center healing, standard Poké Marts and Reflect/Light Screen
-- [ ] Remaining battle commands, move and item effects, AI layers and special battles
+- [x] Remaining battle commands, move and item effects, AI layers and special battles (board #28)
 - [x] Evolution by level, happiness, Tyrogue's stats and stones, with Rare Candy and vitamins (trade evolutions need Link)
 - [ ] Breeding, eggs and the rest of PC storage
 - [ ] Field moves, gyms, Rocket events, the phone and Pokégear, puzzles, minigames, daily events, roaming Pokémon and the postgame

docs/SESSION_HANDOFF.md

@@ -1307,3 +1307,38 @@ Left for the map cards: National Park's contest event (GiveParkBalls,
 timer, out-of-balls/time-up scripts, judging, saving the contest state),
 Burned Tower's roaming release with UpdateRoamMons/JumpRoamMons and
 roaming encounters, and Ilex Forest's CelebiShrineEvent/CheckCaughtCelebi.
+
+## Route 31 to Violet City: 2026-10-03
+
+Card #31 in the same session.
+
+- Maps: 26:2, 26:11, 3:78, 10:5–10:11, 3:1–3:3 in `NATIVE_MAPS`. The
+  closed-connection test now uses Violet City's south edge (Route 32).
+- Script commands added: 0x43 gettrainername, 0x97 askforphonenumber,
+  0x30 checkpokemail, 0x4f/0x58/0x50 loadmenu/_2dmenu/closewindow,
+  0x2e giveegg, 0x96 trade; `loadvar VAR_CALLERID` (0x17, wCurCaller)
+  and the RandomPhoneMon special. `addcellnum` returned success where
+  the original returns TRUE on failure; fixed.
+- Eggs: `PartyMon.egg` with the real species (was species 0xfd). Every
+  former `species === EGG` check uses the flag. HealParty skips Eggs.
+  The stats screen has the Egg page (EggPic, EggPalette). Hatching is
+  not ported (#29).
+- TM/HM: `Bag.tmsHms` (57 counts, migrated as zeros for old saves),
+  item names TM01–HM07, `tmhmMove`, `canLearnTMHM`; the pack's pocket,
+  USE/GIVE/QUIT submenu and AskTeachTMHM/ChooseMonToLearnTMHM/TeachTMHM.
+- `ScriptState.tradeFlags` (saved) for NPCTrade.
+- BadgeStatBoosts at InitBattleMon, the in-battle level-up and
+  CalcPlayerStats; `tests/reference-badges.spec.ts` compares it.
+- Event flag numbers for tests: read them from ROM scripts. Counting
+  `constants/event_flags.asm` by hand drifted by 0x200 for later flags.
+- `MAKE_TEST_SAVES=1 npx vitest run tests/playthrough.test.ts` writes
+  `test-saves/violet-city.crystal-save.json` (Cyndaquil L11 at Violet's
+  east gate) for the manual check cards.
+
+Validation: 610 unit tests passed (3 skipped); without the ROM 143
+passed, 470 skipped. Browser suite: 157 passed, 19 skipped. Both builds,
+reference/release/vendor checks and `git diff --check` passed.
+
+Open boundaries: Egg hatching (#29), trainer calls/rematches (#30), the
+trade animation, Earl's blackboard as a list rather than a 2×3 grid,
+Kenya's MAIL text in the MAIL model, Route 32/36 and Dark Cave's far side.