Implement native opening scenes, battle foundation and overworld movement

docs/SESSION_HANDOFF.md

@@ -0,0 +1,102 @@
+# Recovered Claude session
+
+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.
+
+## Resumed increment: completed 2026-09-23
+
+The movement increment below is complete. The remaining sections preserve the
+original recovery context.
+
+- Added directional two-tile ledge jumps with the existing arc/shadow animation.
+  Unsupported terrain, invalid destinations and occupied landings remain refused.
+- Corrected directional mats to wait for exit input. Warp arrivals keep their
+  actual coordinates and appropriate facing; doors, stairs and caves animate a
+  downward exit. Removing the old inward teleport also corrected Elm's scripted
+  introduction position.
+- Mid-walk, mid-jump and mid-connection saves retain the source position. Landing
+  scenes rewind to the actual source of a jump, rather than the intervening wall.
+- Restored compatibility with early version-3 saves lacking the money field.
+- Replaced the scratch diagnostic with synthetic movement regressions and
+  optional-ROM tests covering five Route 29 ledge types. Route 29 is enabled only
+  inside that test fixture, not in production.
+- Fixed the battle test suite's eager ROM read so missing-ROM runs really skip
+  private tests. Updated browser stair inputs and added an exit-mat save/reload
+  flow. Updated the roadmap and architecture to distinguish the existing battle
+  code from its unfinished integration.
+
+Final checks: 75 unit tests passed with the local ROM; without it, 55 passed and
+20 private tests skipped. All 24 Chromium/WebKit browser tests passed. Native and
+reference builds, release isolation, pinned-reference checks, vendor checks and
+`git diff --check` passed. No commit or push was made.
+
+Next: validate the overworld-to-battle browser flow and complete Route 29's
+remaining script, capture/tutorial and item interactions before enabling the
+route. Player turn timing also remains a documented comparison gap.
+
+## Scope and current state
+
+The original request was to read ARCHITECTURE.md, PLAN.md and PRESENTATION_PLAN.md
+and continue the native port. The working tree contains substantial uncommitted
+work from multiple increments; preserve it when continuing.
+
+- Opening scenes, scripted movement, starter selection, naming, the aide's Potion
+  and version 3 saves are implemented and documented.
+- Native battle modules, ROM tables, damage/type parity tests, encounter handling,
+  battle UI and whiteout handling have been added. These later changes are not
+  fully reflected in the architecture and roadmap documents.
+- Only the original six maps are enabled in `NATIVE_MAPS`. Route 29 (`24:3`)
+  remains disabled. Passing battle unit tests does not establish a playable
+  Route 29 encounter or the full opening quest.
+
+## Exact stopping point
+
+Claude was preparing to revise player movement in `src/game/world/world.ts`.
+Its last investigation concerned spawn facing after warps. It had not implemented
+the planned ledge/warp revision.
+
+The pinned local PRET checkout contains the relevant routines:
+
+- `engine/overworld/player_movement.asm`: `.TryStep`, `.TryJump`,
+  `.CheckLandPerms`, `.CheckWarp` and the direction tables.
+- `engine/overworld/tile_events.asm`: `CheckWarpCollision` and
+  `CheckDirectionalWarp`.
+- `engine/overworld/player_object.asm`: `SpawnPlayer`.
+- `engine/overworld/map_objects.asm`: movement/turn timing.
+
+Research found that ledge tops have land permission; the jump check uses the
+current tile and facing after an ordinary step fails. Doors use collision `$71`,
+downward warp mats `$70`, and stairs `$7a`. Directional warp mats require their
+designated input rather than an immediate warp simply upon entry. Verify these
+rules against the local routines before changing the existing movement flow.
+
+`tests/zz-scratch.test.ts` is Claude's unfinished diagnostic: it logs local-ROM
+warp and ledge collisions, contains no assertions and unconditionally requires
+the private ROM. Replace it with meaningful optional-ROM or synthetic tests
+before treating the suite as ready for public CI.
+
+## Validation after recovery
+
+Run against the current working tree with the local ROM and reference checkout:
+
+- `npm test`: 45 passed, including the assertion-free scratch diagnostic.
+- `npm run build`: passed.
+- `npm run test:e2e`: 22 passed across Chromium and WebKit, including native
+  damage/type comparisons against original routines in the reference emulator.
+- `npm run check:reference`: ROM, pinned rebuild and profile addresses match.
+- `npm run check:release`: native output excludes emulator and game assets.
+- `npm run check:vendor`: passed.
+
+These checks do not establish complete battle behavior, browser battle UI flows,
+Route 29 progression or physical-device compatibility. No gameplay source was
+changed during session recovery.
+
+## Original next-increment notes (movement now completed)
+
+Finish ledge and directional-warp movement with focused regression tests,
+including interrupted movement/save behavior and preservation of the existing
+opening scenes. Audit Route 29 callbacks, scripts and unsupported destinations
+before enabling it. Then test wild encounters and battle controls through the
+browser, including win, escape, loss and save/reload, and reconcile the roadmap
+with the verified behavior.