gh-space-shooter 0.0.3__tar.gz → 0.0.5__tar.gz

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/.github/workflows/publish.yml

@@ -45,11 +45,12 @@ jobs:
     - name: Publish
       run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}
 
-    - name: GitHub Release v${{ steps.bump.outputs.current-version }}
+    - name: GitHub Release PIP v${{ steps.bump.outputs.current-version }}
       uses: ncipollo/release-action@v1
       with:
-        name: pytest-asyncio-concurrent v${{ steps.bump.outputs.current-version }}
+        name: gh-space-shooter pypi v${{ steps.bump.outputs.current-version }}
         tag: v${{ steps.bump.outputs.current-version }}
-        body: "Automated release of version v${{ steps.bump.outputs.current-version }}"
+        body: "Automated release of pypi version v${{ steps.bump.outputs.current-version }}"
         artifacts: dist/*
-        token: ${{ secrets.GH_TOKEN }}
+        token: ${{ secrets.GH_TOKEN }}
+        generateReleaseNotes: true

gh_space_shooter-0.0.5/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+```bash
+# Install dependencies (uses uv package manager)
+uv sync
+
+# Install with dev dependencies
+uv sync --extra dev
+
+# Run the CLI
+uv run gh-space-shooter <username>
+
+# Run tests
+uv run pytest tests/ -v
+
+# Run a single test file
+uv run pytest tests/test_strategies.py -v
+
+# Run a specific test
+uv run pytest tests/test_strategies.py::test_column_strategy -v
+```
+
+## Environment Setup
+
+Requires a GitHub Personal Access Token with `read:user` scope:
+```bash
+export GH_TOKEN=your_token_here
+# Or create a .env file with GH_TOKEN=your_token
+```
+
+## Project Context
+
+**Current main usage**: GitHub Action that automatically updates a game GIF in user repositories daily (see `.github/workflows/` for the action definition).
+
+**Planned**: Wrap this into a Python webapp for on-demand GIF generation.
+
+## Architecture Overview
+
+This is a CLI tool that transforms GitHub contribution graphs into animated space shooter GIFs using Pillow.
+
+### Core Flow
+
+1. **CLI (`cli.py`)** - Typer-based entry point that orchestrates the pipeline
+2. **GitHubClient (`github_client.py`)** - Fetches contribution data via GitHub GraphQL API, returns typed `ContributionData` dict
+3. **Animator (`game/animator.py`)** - Main game loop that coordinates strategy execution and frame generation
+4. **GameState (`game/game_state.py`)** - Central state container holding ship, enemies, bullets, explosions
+5. **Renderer (`game/renderer.py`)** - Converts GameState to PIL Images each frame
+
+### Strategy Pattern
+
+Strategies (`game/strategies/`) define how the ship clears enemies:
+- `BaseStrategy` - Abstract base defining `generate_actions(game_state) -> Iterator[Action]`
+- `ColumnStrategy` - Clears enemies column by column (left to right)
+- `RowStrategy` - Clears enemies row by row (top to bottom)
+- `RandomStrategy` - Targets enemies in random order
+
+Strategies yield `Action(x, shoot)` objects. The Animator processes these: moving the ship to position `x`, waiting for movement/cooldown to complete, then shooting if `shoot=True`.
+
+### Drawable System
+
+All game objects inherit from `Drawable` (`game/drawables/drawable.py`):
+- `animate(delta_time)` - Update state (position, cooldowns, particles)
+- `draw(draw, context)` - Render to PIL ImageDraw
+
+Drawables: `Ship`, `Enemy`, `Bullet`, `Explosion`, `Starfield`
+
+The `RenderContext` (`game/render_context.py`) holds theming (colors, cell sizes, padding) and coordinate conversion helpers.
+
+### Animation Loop
+
+In `Animator._generate_frames()`:
+1. Strategy yields next action
+2. Ship moves to target x position (animate frames until arrived)
+3. Ship shoots if action.shoot (animate frames for bullet travel + explosions)
+4. Repeat until all enemies destroyed
+
+Frame rate is configurable (default 40 FPS). All speeds use delta_time for frame-rate independence.
+
+### Key Constants (`constants.py`)
+
+- `NUM_WEEKS = 52` - Contribution graph width
+- `NUM_DAYS = 7` - Contribution graph height
+- Speeds are in cells/second, durations in seconds

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gh-space-shooter
-Version: 0.0.3
+Version: 0.0.5
 Summary: A CLI tool that visualizes GitHub contribution graphs as gamified GIFs
 Author-email: zane <czl970721@gmail.com>
 License-File: LICENSE
@@ -60,6 +60,7 @@ Then display it in your README:
 - `username` (optional): Username to generate game for (defaults to repo owner)
 - `output-path` (optional): Where to save the GIF (default: `gh-space-shooter.gif`)
 - `strategy` (optional): Attack pattern - `column`, `row`, or `random` (default: `random`)
+- `fps` (optional): Frames per second for the animation (default: `40`)
 - `commit-message` (optional): Commit message for the update
 
 ### From PyPI
@@ -121,9 +122,15 @@ gh-space-shooter torvalds --output my-epic-game.gif
 gh-space-shooter torvalds -o my-game.gif
 
 # Choose enemy attack strategy
-gh-space-shooter torvalds --strategy column   # Enemies attack in columns
 gh-space-shooter torvalds --strategy row      # Enemies attack in rows
 gh-space-shooter torvalds -s random           # Random chaos (default)
+
+# Adjust animation frame rate
+gh-space-shooter torvalds --fps 25            # Lower Frame rate, Smaller file size
+gh-space-shooter torvalds --fps 40            # Default Frame rate, Larger file size
+
+# Stop the animation earlier
+gh-space-shooter torvalds --max-frame 200     # Stop after 200 frames
 ```
 
 This creates an animated GIF showing:

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/README.md

@@ -44,6 +44,7 @@ Then display it in your README:
 - `username` (optional): Username to generate game for (defaults to repo owner)
 - `output-path` (optional): Where to save the GIF (default: `gh-space-shooter.gif`)
 - `strategy` (optional): Attack pattern - `column`, `row`, or `random` (default: `random`)
+- `fps` (optional): Frames per second for the animation (default: `40`)
 - `commit-message` (optional): Commit message for the update
 
 ### From PyPI
@@ -105,9 +106,15 @@ gh-space-shooter torvalds --output my-epic-game.gif
 gh-space-shooter torvalds -o my-game.gif
 
 # Choose enemy attack strategy
-gh-space-shooter torvalds --strategy column   # Enemies attack in columns
 gh-space-shooter torvalds --strategy row      # Enemies attack in rows
 gh-space-shooter torvalds -s random           # Random chaos (default)
+
+# Adjust animation frame rate
+gh-space-shooter torvalds --fps 25            # Lower Frame rate, Smaller file size
+gh-space-shooter torvalds --fps 40            # Default Frame rate, Larger file size
+
+# Stop the animation earlier
+gh-space-shooter torvalds --max-frame 200     # Stop after 200 frames
 ```
 
 This creates an animated GIF showing:

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/action.yml

@@ -22,6 +22,10 @@ inputs:
     description: 'Enemy attack strategy (column, row, or random)'
     required: false
     default: 'random'
+  fps:
+    description: 'Frames per second for the animation (default: 40)'
+    required: false
+    default: '40'
   commit-message:
     description: 'Commit message for the GIF update'
     required: false
@@ -54,7 +58,8 @@ runs:
       run: |
         gh-space-shooter ${{ inputs.username }} \
           --output ${{ inputs.output-path }} \
-          --strategy ${{ inputs.strategy }}
+          --strategy ${{ inputs.strategy }} \
+          --fps ${{ inputs.fps }}
 
     - name: Commit and push GIF
       shell: bash

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gh-space-shooter"
-version = "0.0.3"
+version = "0.0.5"
 description = "A CLI tool that visualizes GitHub contribution graphs as gamified GIFs"
 readme = "README.md"
 authors = [
@@ -29,7 +29,7 @@ build-backend = "hatchling.build"
 
 
 [tool.bumpversion]
-current_version = "0.0.3"
+current_version = "0.0.5"
 parse = """(?x)
   (?P<major>0|[1-9]\\d*)\\.
   (?P<minor>0|[1-9]\\d*)\\.

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/src/gh_space_shooter/cli.py

@@ -8,8 +8,8 @@ import typer
 from dotenv import load_dotenv
 from rich.console import Console
 
-from gh_space_shooter.game.strategies.base_strategy import BaseStrategy
-
+from .constants import DEFAULT_FPS
+from .game.strategies.base_strategy import BaseStrategy
 from .console_printer import ContributionConsolePrinter
 from .game import Animator, ColumnStrategy, RandomStrategy, RowStrategy
 from .github_client import ContributionData, GitHubAPIError, GitHubClient
@@ -55,6 +55,21 @@ def main(
         "-s",
         help="Strategy for clearing enemies (column, row, random)",
     ),
+    fps: int = typer.Option(
+        DEFAULT_FPS,
+        "--fps",
+        help="Frames per second for the animation",
+    ),
+    maxFrame: int | None = typer.Option(
+        None,
+        "--max-frame",
+        help="Maximum number of frames to generate",
+    ),
+    watermark: bool = typer.Option(
+        False,
+        "--watermark",
+        help="Add watermark to the GIF",
+    ),
 ) -> None:
     """
     Fetch or load GitHub contribution graph data and display it.
@@ -90,7 +105,7 @@ def main(
             _save_data_to_file(data, raw_output)
 
         # Generate GIF if requested
-        _generate_gif(data, out, strategy)
+        _generate_gif(data, out, strategy, fps, watermark, maxFrame)
 
     except CLIError as e:
         err_console.print(f"[bold red]Error:[/bold red] {e}")
@@ -146,8 +161,21 @@ def _save_data_to_file(data: ContributionData, file_path: str) -> None:
         raise CLIError(f"Failed to save file '{file_path}': {e}")
 
 
-def _generate_gif(data: ContributionData, file_path: str, strategy_name: str) -> None:
+def _generate_gif(
+    data: ContributionData, 
+    file_path: str, 
+    strategy_name: str, 
+    fps: int, 
+    watermark: bool, 
+    maxFrame: int | None
+) -> None:
     """Generate animated GIF visualization."""
+    # GIF format limitation: delays below 20ms (>50 FPS) are clamped by most browsers
+    if fps > 50:
+        console.print(
+            f"[yellow]Warning:[/yellow] FPS > 50 may not display correctly in browsers "
+            f"(GIF delay will be {1000 // fps}ms, but browsers clamp delays < 20ms to ~100ms)"
+        )
     console.print("\n[bold blue]Generating GIF animation...[/bold blue]")
 
     if strategy_name == "column":
@@ -163,8 +191,12 @@ def _generate_gif(data: ContributionData, file_path: str, strategy_name: str) ->
 
     # Create animator and generate GIF
     try:
-        animator = Animator(data, strategy)
-        animator.generate_gif(file_path)
+        animator = Animator(data, strategy, fps=fps, watermark=watermark)
+        buffer = animator.generate_gif(maxFrame=maxFrame)
+        console.print("[bold blue]Saving GIF animation...[/bold blue]")
+        with open(file_path, "wb") as f:
+            f.write(buffer.getvalue())
+
         console.print(f"[green]✓[/green] GIF saved to {file_path}")
     except Exception as e:
         raise CLIError(f"Failed to generate GIF: {e}")

gh_space_shooter-0.0.5/src/gh_space_shooter/constants.py

@@ -0,0 +1,30 @@
+"""Global constants for the application."""
+
+# Animation settings
+DEFAULT_FPS = 40  # Default frames per second for animation
+
+# GitHub contribution graph dimensions
+NUM_WEEKS = 52  # Number of weeks in contribution graph
+NUM_DAYS = 7  # Number of days in a week (Sun-Sat)
+SHIP_POSITION_Y = NUM_DAYS + 3  # Ship is positioned just below the grid
+
+# Speeds in cells per second (frame-rate independent)
+SHIP_SPEED = 12.5  # Cells per second the ship moves
+BULLET_SPEED = 7.5  # Cells per second the bullet moves
+BULLET_TRAILING_LENGTH = 3  # Number of trailing segments for bullets
+BULLET_TRAIL_SPACING = 0.15  # Spacing between trail segments in cells
+
+# Durations in seconds (frame-rate independent)
+SHIP_SHOOT_COOLDOWN = 0.2  # Seconds between ship shots
+
+# Explosion settings
+EXPLOSION_PARTICLE_COUNT_LARGE = 8  # Number of particles in a large explosion
+EXPLOSION_PARTICLE_COUNT_SMALL = 4  # Number of particles in a small explosion
+EXPLOSION_MAX_RADIUS_LARGE = 20  # Max radius for large explosions
+EXPLOSION_MAX_RADIUS_SMALL = 10  # Max radius for small explosions
+EXPLOSION_DURATION_LARGE = 0.4  # Seconds for large explosion animation
+EXPLOSION_DURATION_SMALL = 0.12  # Seconds for small explosion animation
+
+# Starfield settings (speeds in cells per second)
+STAR_SPEED_MIN = 1.0  # Minimum star speed (dimmer/farther stars)
+STAR_SPEED_MAX = 2.5  # Maximum star speed (brighter/closer stars)

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/animator.py

@@ -1,11 +1,10 @@
 """Animator for generating GIF animations from game strategies."""
 
+from io import BytesIO
 from typing import Iterator
 
 from PIL import Image
 
-
-from ..constants import FRAME_DURATION_MS
 from ..github_client import ContributionData
 from .game_state import GameState
 from .renderer import Renderer
@@ -20,7 +19,8 @@ class Animator:
         self,
         contribution_data: ContributionData,
         strategy: BaseStrategy,
-        frame_duration: int = FRAME_DURATION_MS,
+        fps: int,
+        watermark: bool = False,
     ):
         """
         Initialize animator.
@@ -28,13 +28,19 @@ class Animator:
         Args:
             contribution_data: The GitHub contribution data
             strategy: The strategy to use for clearing enemies
-            frame_duration: Duration of each frame in milliseconds
+            fps: Frames per second for the animation
+            watermark: Whether to add watermark to the GIF
         """
         self.contribution_data = contribution_data
         self.strategy = strategy
-        self.frame_duration = frame_duration
-
-    def generate_gif(self, output_path: str) -> None:
+        self.fps = fps
+        self.watermark = watermark
+        self.frame_duration = 1000 // fps
+        # Delta time in seconds per frame
+        # Used to scale all speeds (cells/second) to per-frame movement
+        self.delta_time = 1.0 / fps
+
+    def generate_gif(self, maxFrame: int | None) -> BytesIO:
         """
         Generate animated GIF and save to file.
 
@@ -43,20 +49,27 @@ class Animator:
         """
         # Initialize game state
         game_state = GameState(self.contribution_data)
-        renderer = Renderer(game_state, RenderContext.darkmode())
+        renderer = Renderer(game_state, RenderContext.darkmode(), watermark=self.watermark)
 
-        frames = self._generate_frames(game_state, renderer)
+        frames: list[Image.Image] = []
+        for frame in self._generate_frames(game_state, renderer):
+            frames.append(frame)
+            if maxFrame is not None and len(frames) >= maxFrame:
+                break
 
-        # Save as GIF
+        gif_buffer = BytesIO()
         if frames:
-            next(frames).save(
-                output_path,
+            frames[0].save(
+                gif_buffer,
+                format="gif",
                 save_all=True,
-                append_images=list(frames),
+                append_images=frames[1:],
                 duration=self.frame_duration,
                 loop=0,  # Loop forever
                 optimize=False,
             )
+        
+        return gif_buffer
 
     def _generate_frames(
         self, game_state: GameState, renderer: Renderer
@@ -79,18 +92,18 @@ class Animator:
         for action in self.strategy.generate_actions(game_state):
             game_state.ship.move_to(action.x)
             while game_state.can_take_action() is False:
-                game_state.animate()
+                game_state.animate(self.delta_time)
                 yield renderer.render_frame()
 
             if action.shoot:
                 game_state.shoot()
-                game_state.animate()
+                game_state.animate(self.delta_time)
                 yield renderer.render_frame()
 
         force_kill_countdown = 100
         # Add final frames showing completion
         while not game_state.is_complete():
-            game_state.animate()
+            game_state.animate(self.delta_time)
             yield renderer.render_frame()
             
             force_kill_countdown -= 1

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/drawables/bullet.py

@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING
 
 from PIL import ImageDraw
 
-from ...constants import BULLET_SPEED, BULLET_TRAILING_LENGTH, SHIP_POSITION_Y
+from ...constants import BULLET_SPEED, BULLET_TRAILING_LENGTH, BULLET_TRAIL_SPACING, SHIP_POSITION_Y
 from .drawable import Drawable
 from .explosion import Explosion
 
@@ -37,9 +37,13 @@ class Bullet(Drawable):
                 return enemy
         return None
 
-    def animate(self) -> None:
-        """Update bullet position, check for collisions, and remove on hit."""
-        self.y -= BULLET_SPEED
+    def animate(self, delta_time: float) -> None:
+        """Update bullet position, check for collisions, and remove on hit.
+
+        Args:
+            delta_time: Time elapsed since last frame in seconds.
+        """
+        self.y -= BULLET_SPEED * delta_time
         hit_enemy = self._check_collision()
         if hit_enemy:
             explosion = Explosion(self.x, self.y, "small", self.game_state)
@@ -53,7 +57,7 @@ class Bullet(Drawable):
         """Draw the bullet with trailing tail effect."""
 
         for i in range(BULLET_TRAILING_LENGTH):
-            trail_y = self.y + (i + 1) * BULLET_SPEED
+            trail_y = self.y + (i + 1) * BULLET_TRAIL_SPACING
             fade_factor = (i + 1) / BULLET_TRAILING_LENGTH / 2
             self._draw_bullet(draw, context, (self.x, trail_y), fade_factor=fade_factor)
 

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/drawables/drawable.py

@@ -13,8 +13,12 @@ class Drawable(ABC):
     """Interface for objects that can be animated and drawn."""
 
     @abstractmethod
-    def animate(self) -> None:
-        """Update the object's state for the next animation frame."""
+    def animate(self, delta_time: float) -> None:
+        """Update the object's state for the next animation frame.
+
+        Args:
+            delta_time: Time elapsed since last frame in seconds.
+        """
         pass
 
     @abstractmethod

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/drawables/enemy.py

@@ -42,7 +42,7 @@ class Enemy(Drawable):
             self.game_state.explosions.append(explosion)
             self.game_state.enemies.remove(self)
 
-    def animate(self) -> None:
+    def animate(self, delta_time: float) -> None:
         """Update enemy state for next frame (enemies don't animate currently)."""
         pass
 

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/drawables/explosion.py

@@ -7,8 +7,8 @@ from typing import TYPE_CHECKING, Literal
 from PIL import ImageDraw
 
 from ...constants import (
-    EXPLOSION_MAX_FRAMES_LARGE,
-    EXPLOSION_MAX_FRAMES_SMALL,
+    EXPLOSION_DURATION_LARGE,
+    EXPLOSION_DURATION_SMALL,
     EXPLOSION_MAX_RADIUS_LARGE,
     EXPLOSION_MAX_RADIUS_SMALL,
     EXPLOSION_PARTICLE_COUNT_LARGE,
@@ -37,22 +37,26 @@ class Explosion(Drawable):
         self.x = x
         self.y = y
         self.game_state = game_state
-        self.frame = 0
-        self.max_frames = EXPLOSION_MAX_FRAMES_SMALL if size == "small" else EXPLOSION_MAX_FRAMES_LARGE
+        self.elapsed_time = 0.0  # Seconds elapsed since explosion started
+        self.duration = EXPLOSION_DURATION_SMALL if size == "small" else EXPLOSION_DURATION_LARGE
         self.max_radius = EXPLOSION_MAX_RADIUS_SMALL if size == "small" else EXPLOSION_MAX_RADIUS_LARGE
         self.particle_count = EXPLOSION_PARTICLE_COUNT_SMALL if size == "small" else EXPLOSION_PARTICLE_COUNT_LARGE
         self.particle_angles = [random.uniform(0, 2 * math.pi) for _ in range(self.particle_count)]
 
-    def animate(self) -> None:
-        """Progress the explosion animation and remove when complete."""
-        self.frame += 1
-        if self.frame >= self.max_frames:
+    def animate(self, delta_time: float) -> None:
+        """Progress the explosion animation and remove when complete.
+
+        Args:
+            delta_time: Time elapsed since last frame in seconds.
+        """
+        self.elapsed_time += delta_time
+        if self.elapsed_time >= self.duration:
             self.game_state.explosions.remove(self)
 
     def draw(self, draw: ImageDraw.ImageDraw, context: "RenderContext") -> None:
         """Draw expanding particle explosion with fade effect."""
 
-        progress = self.frame / self.max_frames
+        progress = self.elapsed_time / self.duration
         fade = 1 - progress  # Fade out as animation progresses
 
         center_x, center_y = context.get_cell_position(self.x, self.y)

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/drawables/ship.py

@@ -19,7 +19,7 @@ class Ship(Drawable):
         """Initialize the ship at starting position."""
         self.x: float = 25  # Start middle of screen
         self.target_x = self.x
-        self.shoot_cooldown = 0  # Frames until ship can shoot again
+        self.shoot_cooldown = 0.0  # Seconds until ship can shoot again
         self.game_state = game_state
 
     def move_to(self, x: int):
@@ -37,18 +37,23 @@ class Ship(Drawable):
 
     def can_shoot(self) -> bool:
         """Check if ship can shoot (cooldown has finished)."""
-        return self.shoot_cooldown == 0
+        return self.shoot_cooldown <= 0
 
-    def animate(self) -> None:
-        """Update ship position, moving toward target at constant speed."""
+    def animate(self, delta_time: float) -> None:
+        """Update ship position, moving toward target at constant speed.
+
+        Args:
+            delta_time: Time elapsed since last frame in seconds.
+        """
+        delta_x = SHIP_SPEED * delta_time
         if self.x < self.target_x:
-            self.x = min(self.x + SHIP_SPEED, self.target_x)
+            self.x = min(self.x + delta_x, self.target_x)
         elif self.x > self.target_x:
-            self.x = max(self.x - SHIP_SPEED, self.target_x)
+            self.x = max(self.x - delta_x, self.target_x)
 
-        # Decrement shoot cooldown
+        # Decrement shoot cooldown (scaled by delta_time)
         if self.shoot_cooldown > 0:
-            self.shoot_cooldown -= 1
+            self.shoot_cooldown -= delta_time
 
     def draw(self, draw: ImageDraw.ImageDraw, context: "RenderContext") -> None:
         """Draw a simple Galaga-style ship."""

{gh_space_shooter-0.0.3 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/drawables/starfield.py

@@ -1,23 +1,30 @@
 """Animated starfield background."""
 
 import random
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypedDict
 
 from PIL import ImageDraw
 
-from ...constants import NUM_WEEKS, SHIP_POSITION_Y
+from ...constants import NUM_WEEKS, SHIP_POSITION_Y, STAR_SPEED_MIN, STAR_SPEED_MAX
 from .drawable import Drawable
 
 if TYPE_CHECKING:
     from ..render_context import RenderContext
 
+class Star(TypedDict):
+    x: float
+    y: float
+    brightness: float
+    size: int
+    speed: float
+
 
 class Starfield(Drawable):
     """Animated starfield background with slowly moving stars."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         """Initialize the starfield with random stars."""
-        self.stars = []
+        self.stars: list[Star] = []
         # Generate about 100 stars across the play area
         for _ in range(100):
             # Random position across the entire grid area
@@ -27,25 +34,34 @@ class Starfield(Drawable):
             brightness = random.uniform(0.2, 1.0)
             # Size: 1-2 pixels
             size = random.choice([1, 1, 1, 2])  # More 1-pixel stars
-            # Speed: slower for dimmer (farther) stars
-            speed = 0.02 + (brightness * 0.03)  # 0.02-0.05 cells per frame
-            self.stars.append([x, y, brightness, size, speed])
+            # Speed: slower for dimmer (farther) stars (in cells per second)
+            speed = STAR_SPEED_MIN + (brightness * (STAR_SPEED_MAX - STAR_SPEED_MIN))
+            self.stars.append(
+                {"x": x, "y": y, "brightness": brightness, "size": size, "speed": speed}
+            )
+
+    def animate(self, delta_time: float) -> None:
+        """Move stars downward, wrapping around when they go off screen.
 
-    def animate(self) -> None:
-        """Move stars downward, wrapping around when they go off screen."""
+        Args:
+            delta_time: Time elapsed since last frame in seconds.
+        """
         for star in self.stars:
-            # star[1] is the y position, star[4] is the speed
-            star[1] += star[4]
+            star["y"] += star["speed"] * delta_time
 
             # Wrap around: if star goes below the screen, move it back to the top
-            if star[1] > SHIP_POSITION_Y + 4:
-                star[1] = -2
+            if star["y"] > SHIP_POSITION_Y + 4:
+                star["y"] = -2
                 # Randomize x position when wrapping for variety
-                star[0] = random.uniform(-2, NUM_WEEKS + 2)
+                star["x"] = random.uniform(-2, NUM_WEEKS + 2)
 
     def draw(self, draw: ImageDraw.ImageDraw, context: "RenderContext") -> None:
         """Draw all stars at their current positions."""
-        for star_x, star_y, brightness, size, _ in self.stars:
+        for star in self.stars:
+            star_x = star["x"]
+            star_y = star["y"]
+            brightness = star["brightness"]
+            size = star["size"]
             # Convert grid position to pixel position
             x, y = context.get_cell_position(star_x, star_y)