Port the trainer card and the play time

The player's name in the start menu opens TrainerCard: page 1 with the
name, ID, money, Pokédex count and play time, page 2 with the Johto
leaders and the badges owned, turned and closed with the original
buttons. The card picture, leader faces and animated badges come from the
ROM with _CGB_TrainerCard's palettes. GameTimer now counts the play time
from the end of the introduction, capped at 999:59:59, and saves keep it.

Closes #23

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

docs/ARCHITECTURE.md

@@ -86,7 +86,10 @@ is a `pokegear` effect answered with a button, and a phone call runs the
 callee's ROM script in the event interpreter on the same draft. The world
 keeps the card on screen (`world.pokegear`) during the call's texts.
 `scripts/mom.ts` runs `BankOfMom` as a special; its amount box is a
-`mombank` effect answered with buttons in the same way.
+`mombank` effect answered with buttons in the same way, and so are the
+pages of `scripts/trainer-card.ts`. The world refreshes the card's play
+time, colon and badge step every tick; `world/game-time.ts` is the play
+time (`wGameTime`), which the world advances two frames per tick.
 
 `TilesetAnimator` translates the ROM animation command tables, advancing two
 video frames per overworld tick. It owns mutable graphics separately from the

docs/NATIVE_PORT.md

@@ -34,6 +34,7 @@ These paths refer to the pinned [PRET source](https://github.com/pret/pokecrysta
 | `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/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/evolution.ts`      | `engine/pokemon/evolve.asm`, `engine/pokemon/learn.asm`, `engine/movie/evolution_animation.asm`, `engine/pokemon/party_menu.asm` | `EvolveAfterBattle`/`EvolvePokemon` over the raw evolution bytes, the evolution texts and a timed, B-stoppable picture sequence, `UpdateSpeciesNameIfNotNicknamed`, `CalcMonStats` and the HP rise, `LearnLevelMoves`, `LearnMove`/`ForgetMove` outside battle and `PlacePartyMonEvoStoneCompatibility`. |
 | `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.                                         |
@@ -288,8 +289,9 @@ the original.
 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.
+closes and a save meanwhile keeps the previous state. POKéDEX and OPTION
+are not ported and give a notice; POKéGEAR and the trainer card run inside
+the start menu run.
 
 The party menu prints `PartyMenuStrings` for the `PARTYMENUACTION_*` in use.
 `GetMonSubmenuItems` reads `MonMenuOptions`: field moves first, then STATS,

docs/PLAN.md

@@ -164,7 +164,7 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 
 ## 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.
+- 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 and OPTION give a notice (POKéGEAR and the trainer card run since the sections below); 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".
@@ -210,11 +210,18 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 - Save format 3 gained `momItem` and `momItemTriggerBalance` (`wWhichMomItem`, `wMomItemTriggerBalance`), migrated by absence to 0 and ¥2300.
 - The amount box has no key repeat: like the other native menus, a held direction counts once.
 
+## Implemented: the trainer card and the play time
+
+- The player's name in the start menu runs `TrainerCard` and returns to the start menu. Page 1 shows `.Name_Money`'s NAME and MONEY, the ID number with leading zeros, the Pokédex's caught count (`CountSetBits` over the caught species; the line is cleared without the Pokédex), the play time and "BADGES▶". A or right turns to page 2, the eight Johto leaders with the badges owned; there A leaves and left turns back. B leaves from either page. The Kanto page is reachable only through unreferenced code and is not shown.
+- The card picture (`GetCardPic`: Chris or Kris), the leader faces (`TrainerCard_Page2_3_PlaceLeadersFaces`) and the badges come from the ROM, coloured by `_CGB_TrainerCard`'s palettes and attribute map: the frame in the other gender's palette, the picture in the player's, each leader's own and `PREDEFPAL_CGB_BADGE` for the badges. The badges step through `TrainerCard_JohtoBadgesOAM` every eight frames (the Rising Badge mirrors on alternate cycles), and the play time's colon blinks every 32 frames. Both timings start when the page loads; the original's phase also depends on the VBlank counter.
+- `wGameTime` is new: `GameTimer` counts 60 frames to the second, two per overworld tick, from the end of the introduction through scenes, menus and battles, and caps at 999:59:59. A save made during a scene keeps the current play time; everything else in it is still the state before the scene. Save format 3 gained `gameTime`, migrated by absence to zero. The save screen and the Hall of Fame, which pause it in the original, are not ported.
+- The labels drawn as tiles ("ID NO", "STATUS" and "BADGES") are presented as text; the other strings come from the ROM.
+
 ## 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. The Pokégear's radio, the Pokédex and trainer card screens, Mom's bank, 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, the options, 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.
 
 ## 1. Complete the overworld foundation
 
@@ -292,7 +299,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. Next: the trainer card and options.
+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, and the trainer card with the play time. Next: the options.
 
 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.
 
@@ -327,7 +334,8 @@ Acceptance: main-game/postgame playthroughs, representative optional content, ba
 - [x] Bill's PC: MOVE PKMN W/O MAIL between the party and every box
 - [x] Pokégear clock, map and phone cards (the radio card waits for its stations)
 - [x] Mom's bank: the amount box with its digit cursor, on keyboard, D-pad and on-screen buttons
-- [ ] Pokédex, trainer card and options screens
+- [x] Trainer card: both pages, with the ROM's card picture, leader faces and animated badges
+- [ ] Pokédex and options screens
 - [ ] 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

@@ -886,3 +886,46 @@ run. Not committed.
 
 Next: the trainer card and options; later the Fly map and Teleport/Dig
 warps.
+
+## Trainer card and play time: 2026-10-01
+
+Resumed with "continue the plan" after `38b9562` (clean tree), taking the
+recorded next item (the trainer card, board card #23). The Pokégear and
+Mom's bank above were committed as `209778c`.
+
+- `src/game/scripts/trainer-card.ts` (`TrainerCard`): the player's name in
+  the start menu runs the card and returns to the start menu. Each page is
+  a `trainercard` effect answered with a button (a `buttonChoice` like the
+  Pokégear): page 1 A/right → page 2; page 2 A leaves, left → page 1; B
+  leaves from both. The Kanto page (unreferenced code) is not shown. Labels
+  from `.Name_Money`, `.Dex_PlayTime` and `.Badges`; the Pokédex line only
+  with `ENGINE_POKEDEX`; badges from the Johto badge engine flags.
+- `src/game/world/game-time.ts`: `wGameTime` and `GameTimer` (60 frames a
+  second, capped at 999:59:59.00). `GameWorld.gameTime` advances two
+  frames per tick unless the introduction is pending; `beginIntro` resets
+  it. `save()` during a scene returns the committed state with the current
+  play time. Saves gained `gameTime`, migrated by absence to zero.
+- The world refreshes the card's time, blinking colon (every 32 frames on
+  page 1) and badge step (every 8 frames on page 2, only with badges) each
+  tick, counting from the page load.
+- `src/game/rendering/trainer-card.ts`: the Chris/Kris card picture
+  (tile $1c left blank, as the corner covers it) and page 2's leader faces
+  with the owned badges' sprites, coloured by `_CGB_TrainerCard`'s
+  attribute map. UI: `#trainer-card` panel, frame colour from the other
+  gender's palette; checked visually at desktop and 390px widths.
+- New `TRAINER_CARD` profile table, OW constants (`ENGINE_MINERALBADGE`,
+  `NUM_JOHTO_BADGES`, `PREDEFPAL_CGB_BADGE`, the leaders' trainer classes).
+  `check:reference` now understands the `trainerclass` macro.
+- Tests that compare a save before and after a refused or rolled-back
+  action now ignore the play time (`withoutPlayTime` in
+  `tests/world-driver.ts`), which keeps counting.
+
+Checks: 407 unit tests with the local ROM (134 passed, 273 skipped without
+it; new `tests/trainer-card.test.ts`); 117 Chromium/WebKit browser tests
+passed, 19 skipped intentionally (a new trainer card flow in both
+browsers); native and reference builds; reference, vendor and release
+checks; `git diff --check`. No emulator comparison of the card; no CI or
+physical-device run.
+
+Next: the options screen (board #24), then the Fly map and Teleport/Dig
+warps.