Open Mr. Pokémon's house, the first rival battle and the return to Elm

Mr. Pokémon's ROM scene gives the Mystery Egg and Pokédex, heals the
party, sets the Cherrygrove spawn with blackoutmod and queues Elm's
call. Cherrygrove's rival scene runs both triggers and all three
RIVAL1_1 parties as a CANLOSE battle; reloadmap returns to the script.
Smart AI is accepted for effects with no AI_Smart_EffectHandlers entry
(Normal Hit, Attack Down, Defense Down) and still refuses others before
any random draw, including for reserve Pokémon.

Special calls read SpecialPhoneCallList: the entry's condition decides,
and the ROM's CheckSpecialPhoneCall.script and Script_ReceivePhoneCall
run its caller script through memcall, ending with HangUp's timed
"Click!". Ringing and the caller box are not presented yet.

In Elm's lab, NameRival shows the ROM's "RIVAL'S NAME?" title (the
prompt previously had no page and soft-locked) and applies InitName's
default to blank names. Handing over the Egg and the aide's Poké Balls
run from the ROM. Saves gain rivalName and specialPhoneCall.

The quest fixtures use a seeded RNG (a constant byte never ends the
damage-variation loop) and no longer carry the house's moved objects
into Cherrygrove.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/ARCHITECTURE.md

@@ -34,7 +34,7 @@ flowchart LR
 | `src/reference`, `src/emulator` | Original-game reference, excluded from the native build                                         |
 | `reference/public`              | Licensed emulator files for the reference build only                                            |
 
-`GameRuntime` is a lifecycle interface, not an emulator contract. Native state is validated JSON, schema version 3. It holds the map, position, facing, name/avatar, player ID and in-game tile count; event and engine flags and sprite variables; scene values, phone contacts, the weekday offset and DST flag; positions of objects that scripts moved; and the party, bag, Pokédex sets and money. Early version-3 backups without a money field migrate to the starting balance. It contains no graphics, music, dialogue, GB memory or ROM bytes. Versions 1 and 2 migrate with new-game defaults. Party Pokémon are validated by recomputing their stats from the ROM. The backup envelope retains the historical `coreId` field; native backups use it for their runtime/schema ID.
+`GameRuntime` is a lifecycle interface, not an emulator contract. Native state is validated JSON, schema version 3. It holds the map, position, facing, name/avatar, player ID and in-game tile count; event and engine flags and sprite variables; scene values, phone contacts, a queued special call, the rival's name, the weekday offset and DST flag; positions of objects that scripts moved; and the party, bag, Pokédex sets and money. Early version-3 backups without a money field migrate to the starting balance. It contains no graphics, music, dialogue, GB memory or ROM bytes. Versions 1 and 2 migrate with new-game defaults. Party Pokémon are validated by recomputing their stats from the ROM. The backup envelope retains the historical `coreId` field; native backups use it for their runtime/schema ID.
 
 Saves made during an unfinished walk or jump retain its source tile and completed step count, so loading cannot skip a landing event or map transition. Directional mats wait for exit input; doors, stairs and caves force an animated downward step after arrival.
 

docs/NATIVE_PORT.md

@@ -71,7 +71,7 @@ Native saves are version 3. Version 2 added scene values by owning map, phone co
 
 `game/rom/trainers.ts` decodes `TrainerGroups`, `TrainerClassAttributes`, `TrainerClassNames`, `TrainerClassDVs` and map trainer headers. Tests cover all 542 ROM records across 67 classes; CAL2 construction refuses its SRAM-dependent Mystery Gift party.
 
-`game/battle/ai.ts` translates `AIChooseMove`, `AI_Redundant` and the Basic, Setup, Types, Offensive, Opportunist, Aggressive, Cautious, Status and Risky layers. It preserves the original random tie selection, known redundancy quirks, HP thresholds, exclusions and the deterministic pre-variation damage estimate used by Aggressive and Risky. Smart remains refused, including the rival's AI. Synthetic scoring vectors establish the tested branches; original-engine AI execution parity is still pending.
+`game/battle/ai.ts` translates `AIChooseMove`, `AI_Redundant` and the Basic, Setup, Types, Offensive, Opportunist, Aggressive, Cautious, Status and Risky layers. It preserves the original random tie selection, known redundancy quirks, HP thresholds, exclusions and the deterministic pre-variation damage estimate used by Aggressive and Risky. Smart runs only for move effects that have no `AI_Smart_EffectHandlers` entry (Normal Hit, Attack Down, Defense Down; enough for the first rival). Other effects are refused before any random draw. Synthetic scoring vectors establish the tested branches; original-engine AI execution parity is still pending.
 
 `loadtrainer`, `winlosstext` and `startbattle` run scripted trainer battles through the existing battle UI. Tests cover Joey's ROM party/text/reward, RUN refusal, trainer experience, Amulet Coin, CANLOSE behavior, money limits, transactional rollback and midbattle restore. Chromium and WebKit exercise the UI with a test-only script.
 
@@ -87,7 +87,7 @@ A trainer sighting whose script is refused is not restarted until the player mov
 
 ## Next slice
 
-Route 29, Cherrygrove and Route 30 are enabled with item balls, hidden items, fruit trees and the daily reset, the Pokémon Center nurse, the recorded whiteout spawn and map trainers. NPCs roam. Next: Mr. Pokémon's house and the Mystery Egg, capture with the catching tutorial, and party, bag and Pokégear menus over the native models. Other specials stay refused until translated.
+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 and Elm's special call. NPCs roam. Next: capture with the catching tutorial, then party, bag and Pokégear menus over the native models. Other specials stay refused until translated.
 
 ## Reflect and Light Screen
 
@@ -101,3 +101,22 @@ and retains the original critical/stage rule. Safeguard and other screen
 flags remain refused. Seven local-ROM tests cover move execution, counters,
 PP, damage stats and send-out persistence; no screen-routine emulator parity
 or physical-device validation is claimed.
+
+## Mr. Pokémon, the first rival and special calls
+
+`MrPokemonsHouse.asm`, `CherrygroveRivalScene*` and the `ElmsLab.asm` officer
+and Egg scripts run from the ROM. Supporting translations: `blackoutmod`,
+`reloadmap` (returns to the script; native presentation keeps the map),
+`readvar VAR_SPECIALPHONECALL` and `memcall` (only through
+`wCallerContact + PHONE_CONTACT_SCRIPT2_BANK`). Specials: `NameRival` (native
+naming field, ROM title and `InitName` default), `FadeOutMusic`, and the
+presentation-only fades. `CountStep`'s `CheckSpecialPhoneCall` reads the
+queued `SpecialPhoneCallList` entry. It checks `SpecialCallOnlyWhenOutside`
+or `SpecialCallWhereverYouAre`, then runs `CheckSpecialPhoneCall.script` with
+that entry's caller script. `RingTwice_StartCall` and `InitCallReceiveDelay`
+are accepted without effect, because ringing presentation and random calls are
+not ported. `HangUp` shows "Click!" for its 140 frames. Local-ROM tests cover
+the house, both rival triggers with all three parties, a rival loss, the call
+indoors, outdoors and on reload, the officer's naming (including blank names
+and reload at the naming screen), and the Egg and Poké Ball handovers. Browser
+tests cover the house, the rival battle and the naming field.

docs/PLAN.md

@@ -57,15 +57,15 @@ The emulator-backed prototype is now at `/reference.html`. The default applicati
 - The battle engine gained `recoil` (Struggle). A local stress run of 360 Route 29 battles across all starters and times of day finishes without refusals.
 - Save format 3 gains `fruitTrees`, `dailyReset` and `lastSpawnMap`; older backups migrate by absence.
 - NPCs roam as `HandleNPCStep` does: random walks (Y, X, XY) and slow/fast spins from `SpriteMovementData`, `CanObjectMoveInDirection` (side walls, land, objects' current and previous tiles, radius stored plus one, screen edge), random sleeps, freezing during text and `applymovement`, and deletion/respawn at home beyond the object window. Wandering positions are not saved; objects start from home on reload.
-- Still refused: the catching tutorial (`catchtutorial`) and Cherrygrove's rival scene, both reachable only after the Mystery Egg errand.
+- Still refused: the catching tutorial (`catchtutorial`), reachable after the Mystery Egg errand.
 
 ## Implemented: first scripted trainer battle slice
 
 - ROM decoder for 542 trainer records across 67 classes, all four party formats, class names, DVs, rewards and map trainer headers. SRAM-dependent Mystery Gift parties remain refused.
-- Native move scoring for Basic, Setup, Types, Offensive, Opportunist, Aggressive, Cautious, Status and Risky, with deterministic tie selection and the original pre-variation damage estimate. Smart remains refused.
+- Native move scoring for Basic, Setup, Types, Offensive, Opportunist, Aggressive, Cautious, Status and Risky, with deterministic tie selection and the original pre-variation damage estimate. Smart runs only for effects without a Smart handler (see the Mr. Pokémon section).
 - Scripted single-Pokémon trainer battles support the challenge, sending out, RUN refusal, experience, win/loss text and prize money, including Amulet Coin. Script results, party changes and rewards commit together; interrupted saves replay from committed state.
 - Local-ROM tests and Chromium/WebKit tests exercise Youngster Joey through a test-only script. No new maps or trainer encounters are enabled in normal play.
-- Next: Smart AI, trainer items and player switching, then the rival and the rest of the Route 30 story. The rival remains refused because Smart AI is not yet translated.
+- Next: Smart AI handlers, trainer items and player switching.
 
 ## Implemented: Route 30 trainers
 
@@ -73,7 +73,7 @@ The emulator-backed prototype is now at `/reference.html`. The default applicati
 - New script commands: `loadtemptrainer`, `trainertext`, `trainerflagaction`, `scripttalkafter`, `endifjustbattled`, `checkjustbattled`, `writeobjectxy`, `encountermusic` (silent) and `loadmem` for `wRunningTrainerBattleScript`.
 - Trainers with several Pokémon: `HandleEnemyMonFaint` sends out the next one through `EnemySwitch_SetMode`, `FindMonInOTPartyToSwitchIntoBattle` (including its `BattleRandom` fallback) and `NewEnemyMonStatus`. `AI_SwitchOrTryItem` translates `CheckAbleToSwitch` with its original bugs (every matchup uses the enemy's move type; the quarter-HP test rotates bits) and `AI_Switch`. The player's used moves are recorded for it.
 - Hidden items (`BGEVENT_ITEM`) run `HiddenItemScript`.
-- Route 30 and its Berry house are enabled. Mr. Pokémon's house and Route 31 stay closed; Youngster Joey (after the Egg) needs phone registration and stays hidden until then, as in the original.
+- Route 30 and its Berry house are enabled, and Mr. Pokémon's house since the section below. Route 31 stays closed; Youngster Joey (after the Egg) needs phone registration and stays hidden until then, as in the original.
 - A refused trainer script does not restart until the player moves, so a rollback cannot trap the player in a trainer's sight.
 - A local stress run of 1,080 Route 30 battles (three starters, four levels, three times of day, both trainers and wild encounters) found one refusal: Chikorita's Reflect at level 12 (`screen`), now addressed by the screen increment below.
 
@@ -83,6 +83,15 @@ The emulator-backed prototype is now at `/reference.html`. The default applicati
 - Screens persist across enemy send-outs and expire in the original non-Link order, with ROM messages. Physical/special defenses and critical-hit stage rules use the existing damage path.
 - Local-ROM regressions cover both sides, repeated use and PP, concurrent durations, send-out persistence, expiration order and damage stats. These checks are not an emulator comparison of the screen routines.
 
+## Implemented: Mr. Pokémon's house and the return to Elm
+
+- Mr. Pokémon's house is enabled. Its ROM scene gives the Mystery Egg and Pokédex, heals the party (`FadeOutToBlack`, `ReloadSpritesNoPalettes` and `FadeInFromBlack` are presentation-only), sets the Cherrygrove whiteout spawn with `blackoutmod` and queues Elm's call with `specialphonecall`. A refusal late in the scene rolls back the rewards, healing and Oak's exit.
+- Special calls: after trainer, warp and coordinate events, a queued call runs if its `SpecialPhoneCallList` condition allows (Elm's only outdoors). It runs the ROM's `CheckSpecialPhoneCall.script` and `Script_ReceivePhoneCall`, with `memcall` into the entry's caller script and `HangUp`'s timed "Click!". Ringing tones and the caller name box are not presented yet. Queued calls are saved.
+- Cherrygrove's rival scene runs both triggers and all three `RIVAL1_1` parties as a `BATTLETYPE_CANLOSE` battle. `reloadmap` returns to the script, and a loss continues the scene without whiteout or money loss. The name shows as "RIVAL ?", as in the original. Smart AI accepts the rival's Normal Hit, Attack Down and Defense Down moves, because `AI_Smart_EffectHandlers` has no entries for them. Other Smart effects are still refused before any random draw, including for reserve Pokémon.
+- Elm's lab: the officer's `NameRival` opens the naming field with the ROM title "RIVAL'S NAME?". A blank name takes the ROM default, as `InitName` does. The rival name is saved and used by `<RIVAL>` text. Handing over the Egg and the aide's five Poké Balls run from the ROM.
+- Save format 3 gained `rivalName` and `specialPhoneCall` (migrated by absence to "???" and 0).
+- Next: the catching tutorial on Route 29 (`catchtutorial`) with capture; then player switching and items in battle.
+
 ## In progress: native battles
 
 The battle core, ROM tables, encounter hooks, battle UI and whiteout hooks are present. Unit tests cover wins, escape, loss, experience and move learning; reference tests compare damage and type effectiveness. Browser tests drive a test-only wild encounter through the real UI: victory with level-up and move learning, escape, whiteout, keyboard and on-screen D-pad menu navigation, mid-battle backup restore, and rollback of unsupported effects. Real Route 29 encounters now use the ROM's encounter tables. Capture, player switching, items in battle and the rest of the opening quest remain unfinished.
@@ -103,7 +112,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 and Route 30's trainers run now. Next: Mr. Pokémon's house, the Mystery Egg round trip with the catching tutorial and the rival battle; then the introduction's naming and clock screens.
+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 and the return to Elm run now. Next: capture and the catching tutorial; then the introduction's naming and clock screens.
 
 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

@@ -249,3 +249,43 @@ Changes are uncommitted.
 Next: Mr. Pokémon's house and the Mystery Egg; Smart AI before enabling the
 rival; capture and the catching tutorial. Joey's post-Egg phone scripts remain
 unsupported.
+
+## Mr. Pokémon and the return to Elm: 2026-09-24 (resumed from Codex)
+
+Codex had enabled Mr. Pokémon's house and added `NameRival`, `blackoutmod`,
+`reloadmap`, the queued Elm call and the no-handler Smart AI subset. It
+stopped with all four quest browser tests failing and without docs. Claude
+Code finished the increment:
+
+- The rival scene needed `special FadeOutMusic` (audio only, now accepted).
+- The quest fixture's constant `() => 0` RNG hung `BattleCommand_DamageVariation`,
+  which redraws until the byte is at least 217. The fixture now uses a seeded LCG.
+  Relocating to Cherrygrove had also carried the house's moved Mr. Pokémon and
+  Oak onto the Guide Gent and rival (ids 2 and 3), producing an unrestorable
+  save. The fixture now clears objects and starts off the Guide Gent's tile.
+- The browser test expected `specialPhoneCall` 1; `SPECIALCALL_ROBBED` is 2.
+- `NameRival` yielded a naming choice with zero pages, because `promptbutton`
+  had already flushed them. The dialogue never reached its last page, so the
+  officer scene soft-locked. It now shows the ROM's "RIVAL'S NAME?" and reads
+  the "SILVER" default from ROM. As in `InitName`, blank names of any number of
+  spaces take the default. The naming input's accessible label no longer says
+  "Nickname".
+- Elm's call now runs the ROM's `CheckSpecialPhoneCall.script` →
+  `Script_ReceivePhoneCall` wrapper. It reads the condition and caller script
+  from `SpecialPhoneCallList` instead of hard-coding id 2, adds `memcall`, and
+  shows `HangUp`'s timed "Click!". Ringing and the caller name box are still
+  not presented.
+- Added tests: the rival scene for all three starters and both triggers, a
+  `CANLOSE` loss, reload after each scene, the Elm call (indoors, outdoors,
+  mid-call reload), the officer naming (named, blank, all-space, reload at
+  the naming screen), the Egg handover and the aide's Poké Balls, plus a
+  browser naming-field test.
+
+Checks: 191 unit tests with the local ROM (80 passed, 111 skipped without it);
+50 Chromium/WebKit browser tests; native and reference builds; reference,
+release and vendor checks; `git diff --check`. Not committed.
+
+Next: capture and the Route 29 catching tutorial (`catchtutorial`), the
+first remaining refusal in the opening quest. Then the ringing presentation,
+player switching and items in battle. Joey's post-Egg phone scripts remain
+unsupported.