Crystal/docs/SESSION_HANDOFF.md

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.