Complete the overworld foundation

Port forced movement (turn delays, bumps, ice, currents, pits), dynamic
return warps, elevators, Surf, Cut, Strength and cycling rules, working
map blocks with changeblock/changemapblocks, and the remaining NPC
movement types and movement commands.

Add tileset animation from the ROM's command tables, grass sprite
priority and special map palettes; room decorations with ownership, the
bedroom PC and save migration; and Key Items access to the Bicycle.

Fourteen original-engine traces compare positions, facing, actors, event
flags and scripted poses. Tile animation matches original VRAM for four
tilesets, and LoadMapPals matches 192 palette cases. skyfall_top now
keeps the $60 sprite offset its step function leaves behind.

Co-Authored-By: Claude Opus 5.5 <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, 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.
+`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, money and room decoration slots. Older saves without decorations migrate to the original bed and Town Map poster. Decoration imports validate slot categories, ownership and unique doll placement. 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.
 
@@ -49,3 +49,24 @@ Asset caches and the ROM reader remain in memory for lazy extraction. Neither RO
 The native viewport follows its available CSS dimensions and draws additional world tiles at a bounded pixel resolution. Beyond a map's edge it draws the connected map with the current tileset, as the original connection strips do, and the border block elsewhere. Resizing also redraws paused sessions. The local minimap caches terrain from the loaded map and updates its marker from the same world position used by the player; the Map tab shares that view. It is a current-area map, not a full region atlas. Leaving Game pauses the session and releases held input; returning requires explicit play. The reference player retains its own fixed-screen styling.
 
 `game/battle` now holds the native battle core and ROM-backed battle tables. Browser tests cover the overworld-to-battle flow using a test-only encounter fixture; Route 29 uses ROM encounter tables. Trainer battles share that core, with ROM trainer decoders, the trainer's send-out and switch AI, and explicit AI support checks. Map trainers (sight and talk) are started by `game/world` and run the ROM's own trainer scripts. Battles receive the script's draft party, bag and Pokédex, so a catch, a thrown ball or a nickname commits only with the script that started the battle. Introduce future modules with working features: `game/audio`, then `features/link` and `features/walking`. Party and bag models live in `game/party`; scripts change them only on their draft state. Rules must not import UI/browser modules. Transports and step providers must not write directly into world state.
+
+
+The overworld extension keeps player travel mode, backup-warp data and Flash
+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
+decorations on the script draft and reloads the room when the menu commits.
+The wall/poster Town Map is a ROM-backed canvas presented by a script effect.
+
+`TilesetAnimator` translates the ROM animation command tables, advancing two
+video frames per overworld tick. It owns mutable graphics separately from the
+asset cache. The renderer records background color indices for grass sprite
+priority and applies special tileset palettes. Animation comparisons cover
+Johto, Ice Path, restless Ilex Forest and Tin Tower. The live forest engine
+flag selects the Celebi animation; the later story remains gated. Palette
+comparisons execute the original LoadMapPals routine across 192 cases.
+Movement traces compare event flags and check destinations across map-entry
+boundaries; controlled scenes also compare scripted pose visibility and lift.

docs/NATIVE_PORT.md

@@ -25,12 +25,12 @@ These paths refer to the pinned [PRET source](https://github.com/pret/pokecrysta
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `game/rom/lz.ts`                 | `home/decompress.asm`                                                                                                          | All LZ command types have unit vectors; six tilesets match original ASM execution byte-for-byte.                                                                                                                                        |
 | `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. Terrain animation and other special palettes pending.                                                  |
-| 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`. Dynamic Pokémon icons and room decorations pending.                                                                     |
-| `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`. Surfing remains absent; turn timing still needs comparison. |
+| 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. |
 | 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` moves the follower into the leader's previous square.                                                              |
-| 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), the empty-room decoration toggles, `HealParty`, `HealMachineAnim` (presentation only), `CheckPokerus` and the `StubbedTrainerRankings_Healings` stub.                                                                              |
+| 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, the decoration PC and Town Map, `HealParty`, `HealMachineAnim` (presentation only), `CheckPokerus` and the `StubbedTrainerRankings_Healings` stub.                                                                              |
 | `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, learnsets, move PP, item pockets, growth-rate exp and front pictures (`FixPicBank`, `PadFrontpic`). Starter pictures match rebuilt bytes.                                                      |
 | `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`. PC boxes, 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.                                                                      |

docs/PLAN.md

@@ -16,7 +16,7 @@ The emulator-backed prototype is now at `/reference.html`. The default applicati
 | 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                                    |
 | Wild and trainer battles, capture and the catching tutorial                  | Done for the areas that are open        |
-| 1. Complete the overworld foundation                                         | In progress                             |
+| 1. Complete the overworld foundation                                         | Done                                    |
 | 2. Opening story and first battle slice                                      | Mostly done                             |
 | 3. Complete Crystal                                                          | Early                                   |
 | 4. Modern mobile presentation and delivery                                   | First increment done                    |
@@ -124,7 +124,7 @@ The numbered sections below keep their full scope. Each one opens with a checkli
 
 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 and type effectiveness. 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, and rollback of unsupported effects. Real Route 29 encounters now use the ROM's encounter tables. Player switching, items other than balls in battle and the PC remain unfinished.
 
-This is still not a complete new game. Party/bag/Pokégear menus, the PC, story progression beyond Route 30 and Mr. Pokémon's house, decorations, animated terrain, surfing and audio remain unfinished. 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. Full party/bag/Pokégear menus, PC storage, story progression beyond Route 30 and Mr. Pokémon's house, and audio remain unfinished. The Key Items menu supports the Bicycle; the bedroom PC supports 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
 
@@ -134,19 +134,50 @@ This is still not a complete new game. Party/bag/Pokégear menus, the PC, story
 - [x] NPC random walks and spins, trainer sight lines
 - [x] Item balls, hidden items and fruit trees with the daily reset
 - [x] Connected transitions for every enabled map (New Bark Town to Route 30)
-- [ ] Dynamic warps, elevators, ice, currents and the remaining forced movement
-- [ ] Surfing, cycling, Cut trees and Strength boulders
-- [ ] Decorations and tile changes (`changeblock`)
-- [ ] Remaining NPC movement types (followers, bouncing) and movement commands
-- [ ] Terrain animation, layering and special palettes
-- [ ] Reference comparison of player turn timing
-- [ ] Acceptance: outdoor, interior, cave and connected-map traces match the reference engine
+- [x] Dynamic warps, elevators, ice, currents and forced movement
+- [x] Native Surf, Cut and Strength interactions, cycling rules and boulder holes
+- [x] Bicycle access from the Key Items menu with keyboard and touch controls
+- [x] Tile changes (`changeblock`, `changemapblocks`) with rollback and minimap refresh
+- [x] Room decorations, ownership, selection, removal, save validation and migration
+- [x] Additional NPC movement types, variable sprites, Pokémon icons and movement-command decoding
+- [x] Expanded original-engine coverage for scripted NPC poses and movement
+- [x] Tileset animation, grass sprite priority and special map palettes
+- [x] Restless forest animation and broader palette/animation reference comparisons
+- [x] Reference comparison of player turn timing
+- [x] Acceptance: outdoor, interior, cave and connected-map traces match the reference engine
 
-Map headers, location names, connection offsets, connected-border drawing, coordinate events, scene scripts, map callbacks and scripted movement are in place (see above). Next: enable connected transitions as their maps are ported; add dynamic warps, elevators, ice, currents, remaining forced movement, surfing, cycling, cut trees and boulders. Player turn timing still needs a reference comparison.
+Movement now covers turn-in-place delays, bumps, ice, currents, forced tiles,
+dynamic return warps, elevator menus, pits, Surf, Cut, Strength and cycling
+rules. Map block changes use a working copy and roll back with a refused script.
+Local-ROM tests exercise elevator travel, Burned Tower pits, Ice Path boulders,
+field moves and cave/water encounters without enabling those later areas.
 
-Port decorations, tile changes (`changeblock`), the remaining NPC movement types (followers, bouncing, Strength boulders) and the remaining movement commands. Complete terrain animation, layering and special palettes. Record deviations from the original until a comparison test closes them.
+Fourteen original-engine traces cover outdoor turns and bumps, connections in
+both directions, ledges, house stairs and doors, the teacher's follow scene,
+Ice Path, and eight controlled movement sequences: spin, teleport out/in,
+skyfall, skyfall departure, tree shake, fishing, flicker and spin-flicker. They compare positions, facing,
+selected actors and event flags. Map-entry ticks compare the destination
+against the original's completed transition; other ticks compare directly.
+Pose checks compare direction, visibility and vertical offset during scripted
+movement, excluding blocking-text boundaries and subsequent random NPC behavior.
 
-Acceptance: representative outdoor/interior/cave/connected-map traces produce matching positions, collisions, transitions and event changes in native and reference engines. Do not enable an area merely because its image can be decoded.
+Tileset animation runs from ROM command tables on a private graphics copy.
+Johto, Ice Path, restless Ilex Forest and Tin Tower animation each match 96
+original VRAM frames. All 36 tilesets run for 2,048 frames without modifying
+cached graphics. An executed original palette routine matches 192 native
+cases. These checks establish sampled engine behavior, not exhaustive
+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
+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.
+
+The foundation milestone is complete within these acceptance boundaries.
+Next: finish the opening-story milestone below. Later maps remain gated until
+their scripts and story progression are supported.
 
 ## 2. Opening story and first battle slice
 

docs/SESSION_HANDOFF.md

@@ -1,5 +1,8 @@
 # Recovered Claude session
 
+Latest continuation: see **Overworld foundation completed: 2026-09-25** at
+the end of this file. Earlier sections are historical snapshots.
+
 Recovered on 2026-09-23 from the local Claude Code transcript
 `~/.claude/projects/-Users-kawa-Crystal/4ac88f30-29e6-4fd5-a4b2-b6a318dd83b3.jsonl`.
 The session stopped at its usage limit at 09:54 UTC, during research, without a final handoff.
@@ -330,3 +333,102 @@ Next: the PC and boxes (catching with a full party, `SendMonIntoBox`, Bill's
 call), then player switching and other items in battle, and party and bag
 menus. The Dude's back picture, ball animation and Pokédex page are not
 presented.
+
+
+## Overworld foundation recovery: 2026-09-25
+
+Resumed Claude Code session `5d15e2b5-2020-4f49-83e7-eddee08c2315`, whose user
+request was “Complete the overworld foundation.” Its last successful check
+compared Johto and Ice Path animation with the original VRAM; the session then
+hit its usage limit. The previous handoff ended at capture and was stale.
+
+Preserved and validated Claude's uncommitted implementation:
+
+- Turn delays, bumps, ice and currents, forced movement, dynamic return warps,
+  elevator menus, pits and arrival timing. Six original-engine traces cover
+  outdoor, connected, ledge, interior, scripted-follow and cave movement.
+- Surf, Cut, Strength, Whirlpool/Waterfall interaction paths and cycling rules;
+  Strength boulders can fall into script-controlled holes. Later maps are
+  enabled only inside tests, not in the production map list.
+- Working map blocks, `changeblock`, `changemapblocks`, rollback and minimap
+  invalidation; cave/water/Kanto encounter tables and `wildoff`.
+- Additional NPC movement, variable sprites and Pokémon icons; all movement
+  command decoding and teleport/fishing/skyfall/shake/flicker presentation.
+- Tileset animations on private graphics, grass sprite priority and special
+  map palettes. Johto and Ice Path match 96 original VRAM frames after matching
+  the reference animation state, including the scrolling scratch buffer.
+
+Recovery changes:
+
+- Removed `zz-grid.test.ts` and `zz-explore.spec.ts`, temporary diagnostics with
+  no assertions. The grid diagnostic also read a private ROM unconditionally.
+- Added grass-priority/transparency and special-palette regressions, and ran
+  all 36 tilesets for 2,048 animation frames each while checking that cached
+  ROM graphics stay unchanged. `NUM_TILESETS` is verified by `check:reference`.
+- Reconciled PLAN, ARCHITECTURE and NATIVE_PORT with the actual implementation
+  and its remaining gaps.
+
+Validation: 271 unit tests passed with the local ROM. With an absent
+`CRYSTAL_ROM_PATH`, 127 passed and 144 skipped. The full Chromium/WebKit run
+passed 64 tests with 8 intentional WebKit skips; two of those passes were the
+subsequently removed exploratory test, leaving 62 substantive browser checks.
+The eight new original-engine comparisons run in Chromium only. Native and
+reference builds, reference addresses/constants, release isolation and vendor
+checks passed. No physical-device or CI run was performed. Changes remain
+uncommitted; no push was made.
+
+The whole foundation milestone is not complete. Continue with:
+
+1. Room decorations: the two decoration specials still implement empty slots;
+   stored choices, ownership and the selection flow are absent.
+2. Player bag-menu access to `GameWorld.useBicycle()`. Its rules are tested,
+   but it is not reachable through the current game controls.
+3. Remaining reference acceptance: movement traces exclude the original's
+   map-entry tick and compare position/facing/selected actor positions, not
+   event flags. Most special poses and palettes lack executed-reference or
+   screenshot comparisons. The Celebi forest animation stays on frame one.
+
+Do not clear those checklist items or enable later maps based on the existing
+movement and rendering tests alone.
+
+
+## Overworld foundation completed: 2026-09-25 (resumed from Codex)
+
+After the recovery above, Codex continued with "Complete the foundation" and
+stopped during its final validation, before updating this file. It had
+already marked the milestone done in PLAN.md. Its work:
+
+- Room decorations (`world/decorations.ts`): the initial bed and Town Map
+  poster, ownership through `DecorationAttributes` event flags, the bedroom
+  PC's selection and put-away flows (including left/right doll placement),
+  room blocks and variable sprites from saved choices, save validation and
+  migration of saves without decorations. The poster opens the native map.
+- Start/Select opens Key Items; the Bicycle follows the native indoor and
+  outdoor rules, with keyboard and touch controls (`foundation-browser.spec.ts`).
+- Movement traces now compare event flags as well as positions. Pose checks
+  compare direction, visibility and vertical offset during scripted
+  movement. An executed `LoadMapPals` matches 192 native palette cases.
+  Restless Ilex Forest and Tin Tower animation match original VRAM.
+- Fixed fishing and flicker pose timing against the original routines.
+
+Claude Code finished the increment. Codex had just added two pose traces.
+Tree shake passed. Skyfall departure (`skyfall_top`) failed:
+`StepFunction_SkyfallTop` leaves `OBJECT_SPRITE_Y_OFFSET` at $60 on the tick
+that ends the command, and the offset persists through later steps. Actors
+now keep a `yOffset`. Skyfall, teleports, the fishing bite and jumps clear it,
+because those routines write the offset again. In the game, only the player
+uses `skyfall_top` (Ruins of Alph chambers, Burned Tower), just before a warp.
+The traces now number fourteen. PLAN and NATIVE_PORT were updated to match.
+
+Checks: 276 unit tests with the local ROM (127 passed, 149 skipped without
+it); 81 Chromium/WebKit browser tests passed and 19 were skipped intentionally
+(the engine parity tests run in Chromium only); native and
+reference builds; reference, vendor and release checks; `git diff --check`.
+Not committed.
+
+Next (PLAN section 2): the PC and boxes (a catch with a full party,
+`SendMonIntoBox`, Bill's call), then the introduction's naming and clock
+screens. Also open there: player switching and non-ball items in battle,
+controlled-seed comparisons beyond damage and type effectiveness, and a
+continuous opening-quest playthrough with save/reload. Later maps stay gated
+until their scripts and story are supported.