1# playable-puzzles Specification23## Purpose4Define the initial ordered MIAU teaching campaign and the controls needed to5play, undo, reset, and advance through its levels.6## Requirements7### Requirement: The app SHALL provide three built-in MIAU teaching puzzles8The app SHALL expose valid catalog levels through the INDEX scene rather than a flat level list. The original three MIAU teaching proofs SHALL remain in the built-in catalog, while additional curated or installed packs add proof nodes and sheets. Each proof SHALL retain stable `packId` and `levelId` identity and ordered progress metadata.910#### Scenario: The built-in catalog starts at MIAU teaching proofs11- **WHEN** the app opens without imported content12- **THEN** INDEX selects the first MIAU proof and lays out the rest of the built-in catalog from data1314#### Scenario: A pack adds an INDEX sheet15- **WHEN** a valid pack is installed16- **THEN** its stable proof ids appear on an INDEX sheet without replacing the built-in teaching proofs1718#### Scenario: Completing a proof advances only by explicit input19- **WHEN** the active proof reaches its win state20- **THEN** the win card waits for Enter before returning to INDEX and marking the proof solved2122### Requirement: The app SHALL expose reset, undo, and cardinal controls23The app SHALL provide reset and undo actions and SHALL accept up, down, left, and right intents from keyboard, Standard gamepad, and touch input. Controls SHALL use the shared input adapter and SHALL report blocked, undo, reset, and win outcomes through stage feedback without queuing actions behind animation.2425#### Scenario: Keyboard and touch produce the same move26- **WHEN** the player uses a keyboard arrow or a qualifying touch swipe27- **THEN** the engine receives the same cardinal intent and the resulting state is identical2829#### Scenario: Gamepad confirms a proof30- **WHEN** the player presses Standard gamepad A on an available INDEX node31- **THEN** the stage opens that proof through the same selection path as Enter3233#### Scenario: Reset is available after a deadlock34- **WHEN** the player has made moves that cannot reach the goal35- **THEN** restart restores the initial proof and move count without reloading the page3637#### Scenario: Undo is disabled at the initial state38- **WHEN** the current proof has no successful moves39- **THEN** undo emits no engine action and its stage hint is unavailable4041### Requirement: Level definitions SHALL be validated before play42The app SHALL reject a catalog level whose dimensions, coordinates, entity ids, word text, or object nouns are invalid, and SHALL report the proof identity and validation problem in developer-visible diagnostics.4344#### Scenario: An out-of-bounds entity is rejected45- **WHEN** a level definition places an entity outside its declared width or height46- **THEN** the proof does not start and validation reports its pack/level identity and offending entity4748### Requirement: The app SHALL ship curated additional puzzle packs49The app SHALL ship additional curated packs alongside the existing three-level MIAU teaching campaign. Each added pack SHALL contain valid levels with stable pack and level ids, dimensions, entities, and title or hint metadata; adding these packs SHALL not change the teaching campaign's identities or order.5051#### Scenario: Additional curated content is available52- **WHEN** the player opens the pack and level selector53- **THEN** the selector lists the built-in teaching pack and every other valid bundled pack with stable ids5455#### Scenario: Imported content does not replace built-ins56- **WHEN** a valid local or shared pack is loaded57- **THEN** the three MIAU teaching levels and other valid bundled packs remain selectable58