cat / miau-is-true
clone

a browser grid puzzle game where you push words around to rewrite the rules of each level

main
miau-is-true / openspec / specs / playable-puzzles / spec.md
spec.md 3.6K source

playable-puzzles Specification

Purpose

Define the initial ordered MIAU teaching campaign and the controls needed to play, undo, reset, and advance through its levels.

Requirements

Requirement: The app SHALL provide three built-in MIAU teaching puzzles

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

Scenario: The built-in catalog starts at MIAU teaching proofs

  • WHEN the app opens without imported content
  • THEN INDEX selects the first MIAU proof and lays out the rest of the built-in catalog from data

Scenario: A pack adds an INDEX sheet

  • WHEN a valid pack is installed
  • THEN its stable proof ids appear on an INDEX sheet without replacing the built-in teaching proofs

Scenario: Completing a proof advances only by explicit input

  • WHEN the active proof reaches its win state
  • THEN the win card waits for Enter before returning to INDEX and marking the proof solved

Requirement: The app SHALL expose reset, undo, and cardinal controls

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

Scenario: Keyboard and touch produce the same move

  • WHEN the player uses a keyboard arrow or a qualifying touch swipe
  • THEN the engine receives the same cardinal intent and the resulting state is identical

Scenario: Gamepad confirms a proof

  • WHEN the player presses Standard gamepad A on an available INDEX node
  • THEN the stage opens that proof through the same selection path as Enter

Scenario: Reset is available after a deadlock

  • WHEN the player has made moves that cannot reach the goal
  • THEN restart restores the initial proof and move count without reloading the page

Scenario: Undo is disabled at the initial state

  • WHEN the current proof has no successful moves
  • THEN undo emits no engine action and its stage hint is unavailable

Requirement: Level definitions SHALL be validated before play

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

Scenario: An out-of-bounds entity is rejected

  • WHEN a level definition places an entity outside its declared width or height
  • THEN the proof does not start and validation reports its pack/level identity and offending entity

Requirement: The app SHALL ship curated additional puzzle packs

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

Scenario: Additional curated content is available

  • WHEN the player opens the pack and level selector
  • THEN the selector lists the built-in teaching pack and every other valid bundled pack with stable ids

Scenario: Imported content does not replace built-ins

  • WHEN a valid local or shared pack is loaded
  • THEN the three MIAU teaching levels and other valid bundled packs remain selectable