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