1# game-presentation Specification23## Purpose4Define how the browser presents a fixed-coordinate emoji puzzle board, active5word rules, controls, and readable feedback without changing simulation state.6## Requirements7### Requirement: The app SHALL render the simulation as a readable emoji grid8The renderer SHALL draw the simulation on the ink-and-signal full-screen canvas with fixed integer cell geometry, hard-edged board and tiles, stable stack order, and no decorative overlap. Object nouns SHALL use emoji mappings or readable text fallbacks, word entities SHALL remain legible, and physical sentence spans SHALL drive sentence bars.910#### Scenario: Stacked entities remain visible11- **WHEN** multiple objects or words occupy one cell12- **THEN** the renderer preserves their identity with the documented stack offset and does not treat decorative elements as simulation occupancy1314#### Scenario: A modded noun has no emoji fallback15- **WHEN** a noun has no declared emoji mapping16- **THEN** the renderer uses a readable text fallback within its fixed cell1718#### Scenario: A sentence bar follows state spans19- **WHEN** the engine exposes `state.sentences`20- **THEN** the renderer draws maximal horizontal or vertical bars from those physical spans, including exact duplicates2122### Requirement: The app SHALL show active rules and turn feedback23The presentation SHALL render the current proof HUD, ledger, hints, keycap controls, active/inactive words, and no-YOU state on the stage. It SHALL consume settled engine events for blocked movement, undo, reset, transformations, defeat, victory, and rule changes without changing simulation state. New ledger sentences SHALL stamp tile by tile; broken sentences SHALL strike and fall away. Changed step digits SHALL roll up on forward counts and down on Undo. Pushed word tiles SHALL skid toward actual travel, while pushers remain level. Visible keycaps SHALL press when their corresponding keyboard, gamepad, or touch action fires.2425#### Scenario: A pushed word skids independently of its pusher26- **WHEN** a settled accepted turn records a word moved with non-null `pushedBy`27- **THEN** the word tilts toward its travel during its visual tween and rests level at the destination, while the pusher does not tilt2829#### Scenario: Undo rolls the step counter downward30- **WHEN** Undo restores an earlier move count31- **THEN** the clipped digits roll toward the lower number and settle on the restored count3233#### Scenario: New and broken sentences have distinct motion34- **WHEN** a word push forms one sentence and breaks another35- **THEN** the new physical sentence's tiles stamp in sequence and the broken sentence strikes, drops, and leaves without altering the engine's rule list3637### Requirement: Text effects SHALL support variable-length labels without driving grid geometry38The app MAY use Pretext or an equivalent text-effect layer for proof names, hints, ledger labels, pack feedback, and scene copy. Text effects SHALL be laid out in their owning HUD or scene region and SHALL not determine integer simulation coordinates or collision geometry.3940#### Scenario: A long proof title does not move cells41- **WHEN** a proof title or hint is longer than its HUD region42- **THEN** it fits, wraps, or truncates according to the stage copy rules while every grid cell retains its coordinate and size4344### Requirement: The presentation SHALL provide accessible control feedback45The app SHALL expose a polite live region and readable text equivalents for movement, undo, restart, menu, scene, rule, level, pack, and outcome status. Keyboard, gamepad, and touch users SHALL be able to reach every player-facing action, and reduced motion SHALL preserve status without animation.4647#### Scenario: Controls are understandable without animation48- **WHEN** reduced motion is enabled or animation is unavailable49- **THEN** the board, INDEX, active rules, current proof, pack status, and controls remain understandable from static text and tile labels5051### Requirement: Supported character glyphs SHALL use scoped facing state52The presentation SHALL maintain horizontal facing per entity ID as visual state separate from simulation coordinates. The built-in MIAU 🐈 SHALL have native left-facing direction, including when a pack repeats that same glyph as a plain palette string. A mod palette object MAY declare `faces: 'left' | 'right'` for another profile glyph; a different plain string and a front-facing glyph such as FENN 🦊 SHALL remain non-directional by default. Every accepted horizontal displacement SHALL update a directional entity's facing to its travel direction, including being pushed. When a pushed entity also moves itself horizontally in the same turn, its self-movement direction SHALL take precedence. Vertical movement, transformation, idle frames, and blocked intents SHALL preserve prior horizontal facing. Undo SHALL restore per-ID facing history, while loading or resetting a level SHALL use its native declared or neutral facing. A facing change MAY use a glyph-only squash; reduced motion SHALL apply the direction immediately.5354#### Scenario: Built-in cat faces forward in every pack55- **WHEN** a MIAU entity with the built-in 🐈 glyph moves right in a core proof or a pack with `palette.MIAU: '🐈'`56- **THEN** the settled board mirrors the native-left glyph to face right, without mirroring its cell, shadow, or text5758#### Scenario: Leftward travel uses the native pose59- **WHEN** that MIAU entity subsequently moves left60- **THEN** the settled board draws the native-left glyph without a mirror6162#### Scenario: Pushes turn a directional actor63- **WHEN** a directional entity is successfully pushed one cell to the right64- **THEN** its settled horizontal facing is right, while a blocked push leaves its prior facing unchanged6566#### Scenario: Self-movement wins after a push67- **WHEN** one accepted turn pushes an actor right and then moves that actor left under an automaton rule68- **THEN** the actor's settled horizontal facing is left6970#### Scenario: Vertical movement preserves the horizontal pose71- **WHEN** a MIAU entity moves up or down after facing right72- **THEN** its horizontal glyph orientation remains right because the side-profile emoji has no vertical view7374#### Scenario: A transformation preserves per-ID facing75- **WHEN** an entity transforms to another noun during a settled turn76- **THEN** the entity ID retains its prior horizontal facing, unless the resulting noun has no directional glyph and uses its normal fallback7778#### Scenario: A custom mod glyph opts in explicitly79- **WHEN** a mod supplies a different profile glyph with `faces: 'right'`80- **THEN** leftward travel mirrors that glyph, while a different plain-string glyph is not mirrored8182#### Scenario: Undo and reset restore the correct pose83- **WHEN** the player undoes a directional turn or resets/loads a level84- **THEN** Undo restores the prior per-ID facing, and reset/load returns MIAU to the declared native-left pose8586#### Scenario: Reduced motion skips facing animation87- **WHEN** reduced motion is enabled and a horizontal move changes facing88- **THEN** the settled glyph faces its direction immediately without a transitional squash8990### Requirement: Undo SHALL restore the complete visual entity state91After a successful Undo, the presentation SHALL reconcile visible entities from the restored engine snapshot by stable ID, including existence, noun or glyph, grid position, facing, control marker, and active visual effects. Effects created by the undone death turn SHALL not remain visible after reconciliation.9293#### Scenario: Proof 05 death then Undo restores MIAU immediately94- **WHEN** MIAU dies in proof 05 and the player invokes Undo on a mobile viewport95- **THEN** the restored MIAU glyph and its control marker are visible at the prior position on the next presentation frame, and the red death shadow from the undone turn is absent9697#### Scenario: Repeated death and Undo does not accumulate stale effects98- **WHEN** the player repeats a death followed by Undo multiple times99- **THEN** each restored snapshot shows exactly the engine entities for that turn and no prior death shadow or missing glyph persists100101#### Scenario: Reset clears death presentation state102- **WHEN** the player resets after a death or after an Undo103- **THEN** the board shows the native initial entities and facing, with no stale destruction effect or missing controlled glyph104105#### Scenario: Reduced motion restores without a transition gap106- **WHEN** reduced motion is enabled and the player invokes Undo after death107- **THEN** the restored entities and controls appear immediately with no intermediate death animation frame108109#### Scenario: Input paths share the same recovery110- **WHEN** Undo is invoked by keyboard, touch, or Standard gamepad after a death111- **THEN** each input path produces the same restored visual state and unchanged engine move history112