Port the start menu, the party menu and the pack outside battle

Start opens the original start menu. POKéMON shows the party with the
Pokémon submenu (stats, switching, move order, held items); PACK shows the
four pockets with the field item effects for healing, PP and the Bicycle,
plus giving and tossing. The menu runs on a script draft, and its cursors
persist until a battle clears them. Select keeps the Key Items shortcut.

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

docs/ARCHITECTURE.md

@@ -56,8 +56,13 @@ state in version-3 saves, with defaults for older saves. Forced terrain and
 turn-in-place timing run through the idle movement path. Dynamic warps and
 elevators retain their return destination. Block mutations use a per-map working
 copy and a revision counter, so rollback and the minimap see the same terrain.
-Surf, Cut and Strength use the ROM scripts. Start/Select opens the Key Items
-menu, pausing overworld ticks while choosing the Bicycle. The bedroom PC edits
+Surf, Cut and Strength use the ROM scripts. Select opens the Key Items
+menu, pausing overworld ticks while choosing the Bicycle. Start opens
+`scripts/start-menu.ts`, a native run on a script draft like the introduction:
+the party menu and pack change only the draft, which commits when the menu
+closes, and an item that queues a script (the Bicycle) starts it afterwards.
+The start menu, party menu and pocket cursors live in the world's memory,
+not in saves, and are cleared after each battle. The bedroom PC edits
 decorations on the script draft and reloads the room when the menu commits.
 `scripts/intro.ts` runs a new game's introduction as a native generator on a
 script draft; the session starts it only when nothing is saved, and the name,

docs/NATIVE_PORT.md

@@ -27,11 +27,12 @@ These paths refer to the pinned [PRET source](https://github.com/pret/pokecrysta
 | `game/rom/assets.ts` maps/events | `data/maps/maps.asm`, `data/maps/attributes.asm`, `data/maps/scenes.asm`, `data/maps/landmarks.asm`, `macros/scripts/maps.asm` | Any map header in the ROM's 26 groups decodes; only maps explicitly listed in NATIVE_MAPS can be entered. Location names, scene-variable owners and connection offsets come from the ROM.                                                                 |
 | Tiles/palettes                   | `home/map.asm`, `engine/gfx/color.asm`, `engine/tilesets/mapgroup_roofs.asm`                                                   | Graphics match rebuilt reference bytes. Connected maps draw beyond the edges with the current tileset, like the original strips. Native tileset animation and special palettes; Johto, Ice Path, restless Ilex Forest and Tin Tower each match 96 reference VRAM frames. 192 palette cases match the original routine.                                                  |
 | Sprites/rendering                | `data/sprites/sprites.asm`, `data/sprites/facings.asm`, `data/sprites/emotes.asm`                                              | Chris/Kris, standard NPCs, emote bubbles and jump shadows decoded. Walking frames follow `SetFacingStepAction`. Variable sprites and Pokémon icons decoded; grass priority supported. Owned room decorations support selection, removal, slot placement, descriptions and validated saves.                                                                     |
-| `game/world/world.ts`            | `engine/overworld/events.asm`, `player_movement.asm`, `warp_connection.asm`, `data/collision/collision_permissions.asm`        | 30 Hz overworld ticks, 8-tick walks, 16-tick ledge jumps, directional mats, animated door/stair exits, connection coordinates, events, scenes and callbacks. NPC random walks and spins follow `HandleNPCStep`. Forced movement, Surf, Cut, Strength, cycling rules, pits and elevators implemented. Fourteen reference traces compare turn timing, actors and event flags; map-entry boundaries verify the completed destination. Bicycle access uses the Key Items menu. |
+| `game/world/world.ts`            | `engine/overworld/events.asm`, `player_movement.asm`, `warp_connection.asm`, `data/collision/collision_permissions.asm`        | 30 Hz overworld ticks, 8-tick walks, 16-tick ledge jumps, directional mats, animated door/stair exits, connection coordinates, events, scenes and callbacks. NPC random walks and spins follow `HandleNPCStep`. Forced movement, Surf, Cut, Strength, cycling rules, pits and elevators implemented. Fourteen reference traces compare turn timing, actors and event flags; map-entry boundaries verify the completed destination. Bicycle access uses the Key Items menu (Select) or the pack. |
 | Event interpreter                | `macros/scripts/events.asm`, `engine/overworld/scripting.asm`, `engine/events/std_scripts.asm`                                 | Resumable; yields text, choices, movement, emotes and pauses. Scenes, phone contacts, string buffers and object commands. Unknown commands and specials abort without committing.                                                       |
 | 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), item storage, the empty mail box and Oak's rating. Menu strings and texts come from the ROM; lists are native. Moving Pokémon, the stats screen and printing are 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. Menu strings, prompts and texts come from the ROM; screens are native. Field moves from the menu, MAIL, SEL and the other field items give a notice. |
 | `game/rom/pokemon.ts`            | `data/pokemon/base_stats`, `evos_attacks.asm`, `data/moves/moves.asm`, `data/items/attributes.asm`, `engine/gfx/load_pics.asm` | Species, move and item names, base data, evolution lists, learnsets, move PP, item pockets, growth-rate exp and front pictures (`FixPicBank`, `PadFrontpic`). Starter pictures match rebuilt bytes; all 251 evolution lists match the pinned source. |
 | `game/party`                     | `engine/pokemon/move_mon.asm`, `engine/pokemon/caught_data.asm`, `engine/items/items.asm`                                      | `GeneratePartyMonStats` for script gifts: DVs, `FillMoves`, PP, exp, `CalcMonStatC`, happiness and caught data. `PutItemInPocket`, key items and `TossItem`. `SendMonIntoBox`, `SendGetMonIntoFromBox` (deposit and withdraw), `RestorePPOfDepositedPokemon` and `CalcLevel` for the PC's boxes and item storage. TMs and HMs are refused.                                         |
 | Text interpreter                 | `macros/scripts/text.asm`, `constants/charmap.asm`, `home/text.asm`                                                            | Literal/far text, RAM names and string buffers from native state, numbers of dots, and sound or pause cues (consumed). `text_asm` and other RAM reads are refused.                                                                      |
@@ -278,3 +279,56 @@ through the party menu, use a Potion from the Items pocket and page
 through the stats screen. `WithdrawMonText` still assumes the leftover
 multiplicand high byte is zero; a whole battle has not been compared with
 the original.
+
+## Start menu, party menu and pack
+
+`StartMenu.SetUpMenuItems` builds the list from the Pokédex and Pokégear
+engine flags and the party, and `StartMenu.Items` supplies each item's
+string and description. The start menu runs as `StartMenuRun`, a native
+generator on a copy of the script state, so nothing commits before it
+closes and a save meanwhile keeps the previous state. POKéDEX, POKéGEAR,
+the trainer card and OPTION are not ported and give a notice.
+
+The party menu prints `PartyMenuStrings` for the `PARTYMENUACTION_*` in use.
+`GetMonSubmenuItems` reads `MonMenuOptions`: field moves first, then STATS,
+SWITCH, MOVE, ITEM (MAIL when `MailItems` holds the held item) and CANCEL
+when fewer than `NUM_MONMENU_ITEMS` are listed; the strings come from
+`MonMenuOptionStrings` and move names. `SwitchPartyMons`/`_SwitchPartyMons`
+swap two party entries. `MoveScreenLoop` swaps two moves and their PP; the
+original's flag-dependent write into `wBattleMon` after a swap outside
+battle is not modelled (the next battle reloads that structure), and left
+and right do not move to another Pokémon's moves. `GiveTakePartyMonItem`,
+`TryGiveItemToPartymon` (including the swap and the full-pack refund) and
+`TakePartyItem` use `GiveItemToPokemon`/`ReceiveItemFromPokemon` on the
+chosen pack slot. Giving MAIL needs `ComposeMailMessage` and is refused
+before anything changes.
+
+The pack's submenu follows `.ItemBallsKey_LoadSubmenu`: `CANT_TOSS`,
+`CANT_SELECT` and the field menu (`CheckItemMenu`, the help byte's high
+nibble) pick one of the six `MenuHeader_*` menus. `TossMenu` confirms the
+quantity and tosses from the chosen slot. `UseItem` dispatches by field menu
+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
+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.
+`BicycleEffect` runs `BikeFunction`'s checks; a queued script runs once the
+menu closes, and a refusal gives Oak's warning because
+`wFieldMoveSucceeded` and `wItemEffectSucceeded` share a byte.
+
+`wBattleMenuCursorPosition`, `wPartyMenuCursor` and `wLastPocket` persist
+between openings in memory and are cleared when a battle ends
+(`CleanUpBattleRAM`). The party cursor is passed to the next battle, whose
+`ChangeHappiness` compares it with `wCurPartyMon`.
+
+Tests: `tests/start-menu.test.ts` (local ROM) covers the item list and
+descriptions, the cursor, the submenu with field moves, switching, move
+reordering, giving, swapping and taking items (including a full pack and
+MAIL), every ported field effect, the PP Up step and its maxed-out refusal,
+tossing, the Bicycle outdoors and indoors, unported effects and saving
+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.

docs/PLAN.md

@@ -162,11 +162,20 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - The stats screen shows its three pages from BattleMonMenu and Bill's PC.
 - The reference suite compares the send-out and withdraw texts, `RestoreHealth`, `RestorePP`, `ChangeHappiness` and `CalcPlayerStats` with the original routines.
 
+## Implemented: the start menu, party menu and pack
+
+- Start opens `StartMenu` with the items `SetUpMenuItems` lists for the player's progress (POKéDEX, POKéMON, PACK, POKéGEAR, the player's name, SAVE, OPTION, EXIT) and their ROM descriptions. POKéDEX, POKéGEAR, the trainer card and OPTION give a notice; SAVE points to the automatic session saves.
+- POKéMON: the party menu with the ROM's prompts and `GetMonSubmenuItems`: field moves the Pokémon knows (from `MonMenuOptions`), STATS, SWITCH, MOVE, ITEM or MAIL, and CANCEL when there is room. STATS opens the stats screen; SWITCH asks "Move to where?" and swaps the two Pokémon; MOVE (`MoveScreenLoop`) swaps two moves with their PP; ITEM gives an item from the pack (key items and untossable items "can't be held"), swaps it with the held item or takes it back, with the pack-full checks of `TryGiveItemToPartymon` and `TakePartyItem`.
+- 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`.
+- Select keeps opening the Key Items shortcut, standing in for a registered item. Not ported: field moves from the menu, MAIL, SEL (registering items), moving a Pokémon's moves to another party member with left and right, item reordering with Select, evolution stones, Rare Candy, vitamins and the other field items (each gives a notice and changes nothing).
+
 ## 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.
 
-This is still not a complete new game. Full party/bag/Pokégear menus, story progression beyond Route 30 and Mr. Pokémon's house, and audio remain unfinished. The Key Items menu supports 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, Pokédex and trainer card screens, 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 the Key Items shortcut supports 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
 
@@ -212,8 +221,9 @@ pixel-perfect screenshots or full Celebi story support.
 
 The bedroom PC selects and puts away owned decorations, including left/right
 doll placement. Room blocks, sprites and descriptions reflect saved choices.
-The Town Map poster opens the native ROM-backed map. Start/Select opens Key
-Items; using the Bicycle follows the native outdoor/indoor rules. Browser
+The Town Map poster opens the native ROM-backed map. Select opens Key Items
+(Start now opens the start menu); using the Bicycle follows the native
+outdoor/indoor rules. Browser
 checks cover both controls and decoration flows in Chromium and WebKit.
 Full item/Pokémon PC storage and the other bag pockets belong to later work.
 
@@ -243,7 +253,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. Next: party and bag menus outside battle, MOVE PKMN W/O MAIL and evolution.
+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. Next: evolution, then MOVE PKMN W/O MAIL.
 
 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.
 
@@ -273,7 +283,8 @@ Acceptance: main-game/postgame playthroughs, representative optional content, ba
 - [x] Adaptive canvas, live local minimap, keyboard and on-screen controls
 - [x] Save, backup export and import for the single native save
 - [x] Touch battle commands, move list, PKMN party menu, PACK (Items and Balls pockets) and naming fields
-- [ ] Party, pack, PC and Pokégear menus outside battle
+- [x] Start menu, party menu and pack outside battle (switching, moves, held items, healing and PP items, tossing, the Bicycle)
+- [ ] Pokégear, Pokédex, trainer card and options screens; MOVE PKMN W/O MAIL
 - [ ] Scalable text, configurable controls and fuller accessibility
 - [ ] Save slots with migration, atomic writes and import previews
 - [ ] Installable web app with offline app shell, safe updates and quota handling

docs/SESSION_HANDOFF.md

@@ -1,6 +1,6 @@
 # Recovered Claude session
 
-Latest continuation: see **Controlled capture comparisons: 2026-09-30**
+Latest continuation: see **Start menu, party menu and pack: 2026-09-30**
 at the end of this file. Earlier sections are historical snapshots.
 
 Recovered on 2026-09-23 from the local Claude Code transcript
@@ -688,3 +688,44 @@ verified. This handoff-only follow-up records that delivery.
 
 Next: party and bag menus outside battle, MOVE PKMN W/O MAIL and evolution.
 PLAN section 2 is complete within its recorded acceptance boundaries.
+
+
+## Start menu, party menu and pack: 2026-09-30
+
+Resumed from `60e06ae` (clean tree) with "continue" from the handoff: the
+next plan items were the party and bag menus outside battle, then
+evolution.
+
+- `src/game/scripts/start-menu.ts` (`StartMenuRun`): Start opens the
+  original start menu (items and descriptions from `StartMenu.Items`, list
+  from `SetUpMenuItems`). POKéMON: party menu (`PartyMenuStrings`), the
+  submenu from `MonMenuOptions` (field moves first), STATS, SWITCH,
+  MOVE (swap moves with PP), ITEM (GIVE from the pack with swap and
+  pack-full refund, TAKE). PACK: four pockets with left/right, the item
+  submenus from `MenuHeader_*.MenuData` by permissions and field menu,
+  TOSS with quantity and confirmation, GIVE, and USE through `ItemEffects`
+  addresses: HP items, status healers, Full Restore, revives, bitter
+  herbs, Ethers/Elixers/MysteryBerry and PP Up (one step, because
+  `wUsePPUp` aliases `wTempPP`), and the Bicycle (queued script after the
+  menu closes; Oak's warning where it cannot be used).
+- It runs on a script draft; saves while open keep the prior state. Menu
+  cursors persist in memory and reset after battle (`CleanUpBattleRAM`);
+  the party cursor now reaches the battle's `ChangeHappiness` quirk.
+- Select keeps the Key Items shortcut (browser tests moved from Enter to
+  Shift). New `pack` script effect/choice; `MENU` profile table checked by
+  `check:reference`; menu, pocket and PP constants moved into the verified
+  `C` block; `ENGINE_POKEGEAR` added and verified. The text decoder gained
+  `<POKE>` ($24), needed for "POKéGEAR".
+- Notices without changes: POKéDEX, POKéGEAR, trainer card, OPTION, field
+  moves from the menu, MAIL (giving or reading), SEL, evolution stones,
+  Rare Candy, vitamins and other field items.
+
+Checks: 353 unit tests with the local ROM (16 new in
+`tests/start-menu.test.ts`); 109 Chromium/WebKit browser tests passed, 19
+skipped intentionally (one new start-menu flow in both browsers); native
+and reference builds, reference, vendor and release checks; `git diff
+--check`. No emulator comparison of the menus; no CI or physical-device run.
+
+Next: evolution (`EvolveAfterBattle` after battles and from stones/Rare
+Candy, with the level-up flags the battle must record), then vitamins,
+MOVE PKMN W/O MAIL, SEL/registered items and field moves from the menu.