Refine Princess Lima for v2 presentation

docs/princess-lima-map-authoring.md

@@ -1,58 +1,87 @@
-# Princess Lima map authoring
+# Princess Lima v2 map authoring
 
-## Framework
+## Runtime contract
 
-Use [Tiled](https://www.mapeditor.org/) as the visual authoring tool and Phaser
-as the runtime. Every region is a 720×720 orthogonal map whose locked image
-layer is the corresponding frame from `regional-style-atlas.png`.
+Princess Lima uses committed Tiled JSON maps rendered by Phaser 4.1.0. The
+regional style atlas is reference art only and must never be used as runtime
+terrain or collision geometry. Maps use orthogonal 32-pixel tiles and may vary
+in width and height.
 
-The runtime contract mirrors Tiled object groups in
-`PrincessLimaData.MAP_LAYERS`. Every map has these named layers:
+The current source maps live in `assets/maps/princess-lima/`. Rebuild them with:
 
-1. `Collision`
-2. `Dynamic Collision`
-3. `Exits`
-4. `NPCs`
-5. `Enemies`
-6. `Puzzles`
-7. `Items`
+```sh
+node tools/generate-princess-lima-maps.mjs
+```
 
-Do not paint collision or interaction geometry into the finished artwork.
-Production collision objects are invisible.
+The generator is deterministic so authored content can be reviewed as ordinary
+JSON. It creates the nine production regions and a Tiled tileset reference.
+Hand editing in Tiled is supported as long as the schema below is preserved.
 
-## Collision rules
+Every map has these uniquely named layers:
 
-- Trace only terrain that is visibly solid: buildings, walls, cliff faces,
-  deep water, fences, furniture, and the four outer edges.
+1. Base terrain
+2. Terrain variation
+3. Paths
+4. Water
+5. Cliffs and buildings
+6. Props
+7. Objects behind actors
+8. Actor layer
+9. Objects above actors
+10. Shadows
+11. Lighting
+12. Collision
+13. Interaction zones
+14. Dialogue triggers
+15. Quest triggers
+16. Enemy zones
+17. Camera zones
+18. Scene transitions
+19. Named safe spawns
+20. Audio zones
+21. Optional secrets
+
+Object IDs must be unique. Scene transitions require valid `target` and `spawn`
+properties. Enemy objects require a validated `enemy` ID. Dialogue objects use
+a validated `dialogue` ID. Safe spawns are named points and may not overlap
+collision.
+
+## Collision and navigation
+
+- Trace only visibly solid buildings, walls, cliffs, water, fences, furniture,
+  and map edges.
 - Keep paths, doors, bridges, stairs, and floor tiles walkable.
-- Use rectangles while the game uses Phaser Arcade Physics. A future switch to
-  Matter Physics can use Tiled polygon objects without approximating them.
-- Every dynamic blocker needs an `opensWith` property matching a validated
-  route ID.
-- Never put a puzzle control, item, actor, or safe spawn inside collision.
-- Keep enemies away from puzzle controls and safe spawns.
+- Use rectangles while the runtime uses Arcade Physics.
+- Never place a required objective, transition, actor, or safe spawn inside
+  collision.
+- Keep encounter zones away from chapter-safe spawns.
+- Preserve a collision-free route between each required spawn and objective in
+  every reachable state variant.
+- Route blockers must name the flag or quest consequence that opens them.
 
-## Interaction rules
+EasyStar receives a navigation grid derived from the collision layer at runtime.
+It is pathfinding only; Phaser remains responsible for movement and physics.
 
-- Exits, NPCs, enemies, puzzles, and items belong on their named object layer.
-- Puzzle and item labels appear only within 92 pixels of the player.
-- The interaction radius is 54 pixels; exit portals use 70 pixels.
-- Every mechanism must be reachable before the state change it triggers.
-- Interaction labels must use the object name rather than an unexplained shape.
+## Interactions and state variants
+
+Interaction objects declare a short `action` or `observation`. Reusable actions
+include `puzzle`, `chest`, `free-prisoner`, `disable-defence`,
+`route-choice`, and `boss-mechanic`. Secrets use the Optional secrets layer.
+Resolved variants are driven by `<region>_resolved` story flags and must leave
+all required routes reachable.
 
 ## Verification
 
-On localhost, use:
+The Node map tests validate layers, IDs, transitions, safe spawns, navigation
+reachability, and content references. During manual authoring, also:
 
-```text
-/play/rpg.html?region=mountain&spawn=bridgeControls
-/play/rpg.html?region=mountain&spawn=bridgeControls&collisionDebug=1
-```
+1. Inspect the clean render and collision-debug render.
+2. Walk every boundary and transition in both directions.
+3. Exercise locked and resolved routes.
+4. Check all named spawns after save/reload.
+5. Repeat transitions while watching the browser console and memory.
+6. Confirm production URLs never expose debug geometry.
 
-Before publishing:
-
-1. Compare the clean rendered map with its locked source image.
-2. Enable collision debugging and check every visible boundary.
-3. Walk each route in both its locked and unlocked states.
-4. Confirm all object-layer points pass the collision-safety tests.
-5. Confirm ordinary production URLs show no collision geometry.
+Use `?collisionDebug=1` on localhost for Arcade Physics bounds. The v2 save
+always restores at a named chapter-safe spawn rather than trusting legacy
+coordinates.

docs/princess-lima-v2-implementation.md

@@ -0,0 +1,72 @@
+# Princess Lima v2 implementation
+
+## Architecture
+
+The rebuild keeps the existing four-chapter story, cast, quest consequences,
+keyboard-first accessibility, Org publishing entry point, and v1 save. It
+replaces the static regional backgrounds and single-scene prototype with:
+
+- Boot, preload, title/setup, cinematic intro, region, boss, and ending flows.
+- Versioned data contracts for maps, actors, enemies, items, quests, dialogue,
+  cutscenes, assets, interactions, and saves.
+- Focused map, state, input-lock, combat, AI, dialogue, camera, audio, save, and
+  accessibility controllers.
+- Nine committed Tiled JSON regions with collision, navigation, interaction,
+  transition, spawn, camera, audio, secret, and state layers.
+- EasyStar.js 0.4.4 for obstacle-aware paths; Phaser remains the renderer,
+  input, physics, animation, timeline, camera, and effects engine.
+
+Only `/play/rpg.html` loads the game runtime and its locally hosted assets.
+
+## Art direction
+
+The final field style uses 32px terrain, 48×64 four-direction actors, nearest
+neighbour scaling, dark restrained outlines, warm upper-left lighting, compact
+shadows, parchment and aged-metal DOM UI, serif display faces, and sans-serif
+body copy. Regional palettes distinguish the village, woods, ruins, mountain,
+camp, fortress, throne, and dawn chamber.
+
+`tools/generate-princess-lima-v2-assets.py` normalizes the field atlas, effects,
+palette, transparency, and tile source into deterministic PNG assets. The
+portrait contact sheet began as original ImageGen source art and was inspected,
+cropped through CSS atlas coordinates, and kept free of generated text. It is
+presentation art only and is never used as collision geometry.
+
+## Play and story systems
+
+The complete opening-to-rescue arc includes:
+
+- Broken Village production slice, eight enemy roles, four multi-phase bosses,
+  optional discoveries, puzzles, prisoners, fortress defences, and three
+  approach consequences.
+- Acceleration movement, normalized diagonals, directional animation, two-hit
+  combo, charged strike, block, active-frame hitboxes, one hit per swing,
+  knockback, recovery, particles, and layered local audio.
+- Data-driven conversations with expressions, choices, conditional effects,
+  history, typing controls, camera framing, background focus treatment, and
+  reliable input/focus restoration.
+- A skippable, replayable, pausable, narrated introduction with subtitles,
+  title reveal, muted play, and reduced-motion timing.
+- Resolved-state flags for all nine regions and an ending that reflects rescued
+  allies and preparation choices.
+
+## Saves and accessibility
+
+New progress uses `zxh_princess_lima_rpg_v2`. The v1 key remains untouched.
+Migration validates identity, appearance, chapter, quests, inventory,
+equipment, bosses, intro preference, and settings; rejects unknown IDs;
+reconstructs derived statistics; and restores to a named safe spawn.
+
+Menus and dialogue remain DOM-backed. They provide keyboard focus, an
+`aria-live` spoken-line mirror, history, instant completion, choice navigation,
+subtitles, narration toggle, text speed, high contrast, reduced motion,
+particles, lighting, shake, blur, and effects-quality controls. Canvas and
+blur-disabled modes retain dimming and actor depth separation.
+
+## Validation
+
+Automated coverage lives in `tests/princess-lima-*.test.cjs` and checks schemas,
+map contracts and reachability, dialogue effects, cutscene cleanup, input
+restoration, quests, movement/combat phases, hitbox rules, AI transitions,
+boss phases, v1 migration, invalid-data recovery, and accessibility settings.
+Publishing remains covered by the Emacs and clean Org-build suites.