Event & Transition Animations #772

Problem statement

Event and scene transition animations (coin/reputation pop and simple enter/exit scene transitions) are missing or placeholder in Main Street. Players and QA need consistent, accessible, and testable animations to improve feedback and enable polished thumbnails and play sessions.

Users

• Players: receive clearer feedback when income/reputation changes and when scenes transition; improved perceived responsiveness and polish.
• QA/Producer: get reproducible visual behavior for playtests and thumbnail generation.
• Developers: need small, reusable animation helpers that are easy to test and toggleable (reduced motion, mute).

User stories

• As a player, I want a short "coin" or "reputation" pop animation when my resources change so I can immediately perceive the effect of economic actions.
• As a producer, I want scene enter/exit transitions so recorded replays and thumbnails do not show abrupt visual jumps.
• As a developer, I want small, well-documented animation helpers (pop, fade/slide transitions) that can be reused across scenes.

Success criteria

• A coin/reputation pop animation plays when income or reputation changes and completes within 1500ms without blocking game logic.
• Animations are implemented using SVG placeholder assets (if final art is not yet available) and accept final art formats without API changes.
• Unit or smoke tests verify animation trigger and completion (e.g., animation promise resolves or tween complete callback called) for both pop and transition animations.
• All related documentation is updated to reflect the changes, including code comments, README, and any relevant wiki or docs site entries.
• Full project test suite must pass with the new changes.

Constraints

• Use SVG placeholders for art; final assets will be delivered later and must be swappable without code changes.
• Provide accessibility support: reduced-motion toggle must disable non-essential animations and transitions.
• Keep engine/public APIs unchanged; implement helpers as scene-level utilities or small engine adapters.
• Avoid heavy runtime allocations; animations should be lightweight and not degrade Monte Carlo or headless test runs.

Existing state

• Parent PRD M4 (CG-0MM4RF91E1LR5RSY) calls for event animations and transitions as part of visual polish.
• Some placeholder visuals and scripts for thumbnail generation exist (scripts/generate-thumbnail.ts); no formal animation helpers are present in the codebase for coin/reputation pops or scene transitions.
• Work item CG-0MO4LWX1T003I2LP currently exists with a short description and minimal acceptance criteria.

Desired change

• Implement two small, reusable animation helpers:
  1. popTextOrIcon(target, options): a compact pop + fade animation usable for coin/reputation changes and other small toasts.
  2. sceneTransition(scene, direction|type, options): simple enter/exit transitions (fade, slide) wired into scene lifecycle hooks.
• Wire pop helper into income and reputation change handlers so events trigger the animation without changing game logic flow.
• Add smoke/unit tests that run headlessly to assert that animations are triggered and complete (check callback or promise resolution), ensuring they don't hang headless runs.
• Document usage in docs/main-street/ux-visual-audio.md and add short README examples in the code folder.

Related work

• Parent: Main Street: PRD Milestone 4 -- Visual Polish, Animation, and Audio (CG-0MM4RF91E1LR5RSY) — PRD that lists event animations, transition animations, accessibility requirements, and thumbnail pipeline; M4 is the parent milestone for this work.
• SVG Placeholder Assets (CG-0MO4LWWK90006QB4) — existing work item that added SVG placeholders; relevant as an asset source for placeholders used by these animations.
• Core Card Animations (CG-0MO4LWWWC006HSNZ) — related animation helpers (deal/move/discard) that can provide patterns and reuse opportunities.
• docs/main-street/ux-visual-audio.md — visual and audio direction reference; includes animation timing guidance and accessibility notes.
• scripts/generate-thumbnail.ts — existing thumbnail tooling which benefits from smoother scene transitions for reproducible thumbnails.

Related work (automated report)

• CG-0MM4RF91E1LR5RSY (Main Street: PRD Milestone 4) — Parent PRD: outlines event animations, transitions, reduced-motion accessibility, and thumbnail pipeline requirements. This intake should align with the M4 success criteria and use SVG placeholders where final assets are missing.
• CG-0MO4LWWK90006QB4 (SVG Placeholder Assets) — Provides SVG placeholders used by early visual work; reuse these placeholders for pop and transition visuals to avoid blocking on final art.
• CG-0MO4LWWWC006HSNZ (Core Card Animations) — Existing animation implementations (deal/move/discard) that can be used as a template for implementation patterns and utility functions.
• docs/main-street/ux-visual-audio.md — Design guidance for animation timing, easing, and accessibility (reduced motion). Use timing targets (300–600ms for pops) from this document.
• scripts/generate-thumbnail.ts — Thumbnail generation tooling benefits from predictable transitions; ensure transitions are deterministic and can be disabled for headless thumbnail runs.

Appendix: Clarifying questions & answers

• Q: "Are SVG placeholders acceptable for this work if final art is not available?" — Answer (agent inference + parent PRD): "Yes. Use SVG placeholders and ensure final assets can be swapped in without code changes." Source: parent PRD (CG-0MM4RF91E1LR5RSY). Final: yes.
• Q: "Should animations be disabled by default for headless runs and CI?" — Answer (agent inference): "Animations should either be no-op in headless test mode or expose hooks/promises that allow tests to wait for completion without rendering frames; provide a reduced-motion toggle and a headless-friendly flag." Source: existing project practice and Test constraints. Final: yes.
• No interactive clarifying questions were asked of the user during this intake.