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/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.