coding-agent-benchmark/docs/superpowers/specs/2026-07-12-gameoflife-design.md

Conway's Game of Life Application Specification - Canvas Edition

Date: 2026-07-12

🚀 Goal

To create a single-page web application capable of running Conway's Game of Life with specific features, including: start/stop functionality, state editing via mouse interaction, and initialization with the Glider Cannon pattern. The simulation must utilize a fixed 2D array for state management and be rendered efficiently using HTML Canvas to support large board sizes (starting at 100x100).

🖼️ High-Level Architecture

The application is structured as a Single Page Application (SPA) contained entirely within index.html. The three core components interact to manage the simulation loop and output rendering:

• GameController: The central state machine. It manages the internal grid representation (grid[W][H]), handles game logic execution (calculating next generations), maintains the current running status (running/paused/stopped), and provides methods for external state mutation. It is responsible for upholding the rules of Conway's Game of Life (under/overpopulation, death).
• CanvasRenderer: Responsible solely for visual output. It receives the current grid array from GameController periodically and draws the necessary pixels onto the HTML Canvas element. This component also manages aspect ratio and scaling related to the fixed cell size.
• UIHandler: The interface layer (Event Listener). This module listens for user inputs, such as button clicks (Start/Stop) and mouse events (editing state via clicking/dragging the canvas). It translates screen coordinates into array indices while accounting for viewport offset (scrolling), thus interfacing between the human user and the GameController.

🔄 Data Flow and Implementation Details

Initialization

1. The application starts by initializing the internal W \times H grid array (e.g., 100 \times 100).
2. This initial state is populated with a known pattern: the Glider Cannon, placed at specific pre-determined Gosper coordinates within the grid space.

Simulation Loop (The Tick)

The simulation runs asynchronously using requestAnimationFrame for smooth rendering and timing accuracy, rather than a simple fixed interval timer.

1. State Calculation: In each cycle, before modifying the main state, all neighbors are checked for every live cell in the current grid (grid). A temporary 'next_grid' is used during calculation to ensure all neighbor checks rely only on the prior generation's state, preventing race conditions.
2. State Transition: The GameController applies Conway's Rules. Once the next state for every cell is determined and stored in next_grid, the main state array (grid) is atomically swapped with next_grid.
3. Rendering: After the swap, the new state is delivered to CanvasRenderer, which draws the board.

User Editing (Mutation)

When a user interacts with the UI (e.g., clicks on a cell they wish to toggle):

1. The UIHandler captures the screen position and determines the corresponding 2D array index.
2. It commands the GameController to force a change on that specific cell in the current grid, overriding the simulation rules for that moment. This action modifies the state locally but does not necessarily reset or trigger the entire generation sequence unless explicitly requested by a separate 'reset' action.

📏 Constraints and Assumptions

• Initial Dimensions: The initial working dimensions are fixed at 100 \times 100. Future growth beyond this (e.g., to 200\times200) requires only scaling the rendering logic, not a fundamental change in data structure.
• Scrolling Support: A mechanism for handling views larger than the container size is implemented by mapping client-side scroll offsets back into virtual grid coordinates during editing and drawing stages.
• Concurrency Control: The critical requirement of preventing race conditions during next-state calculation is met by using a temporary buffer (next_grid) before committing the state change, ensuring atomicity between generations.

🔎 Spec Self-Review Complete

The design is self-consistent; all components are related appropriately (GameController -> CanvasRenderer via shared grid state). The requirements for fixed array use and Glider Cannon initialization are met in the architecture description. No ambiguous concepts were found requiring further clarification.

Proposed Next Step: Create the implementation plan using writing-plans.