diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..83fe1a1
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,207 @@
+# Lint, test and build on every pull request; on main, also push the built
+# bundle into the portfolio site.
+#
+# The demo on the site is an <iframe> pointed at a path under its own
+# public/ folder, so it is same-origin on purpose. That means the built
+# files have to live in the website repo rather than on a separate host,
+# and publishing is a commit over there rather than a deploy from here.
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  # A new push supersedes the run still going for the same branch, except
+  # on main: cancelling a run mid-publish would leave the website repo
+  # holding half a bundle.
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Lint, test, build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            requirements-dev.txt
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Lint
+        run: |
+          pycodestyle .
+          pyflakes $(git ls-files '*.py')
+
+      - name: Test
+        # SDL needs a display it will never get on a runner. The dummy
+        # driver gives the tests a real surface without a window.
+        env:
+          SDL_VIDEODRIVER: dummy
+          SDL_AUDIODRIVER: dummy
+        run: python -m unittest discover --start-directory tests --top-level-directory . --verbose
+
+      - name: Build the web bundle
+        # --strict turns a trim that no longer matches into a failure. A
+        # pygbag upgrade can change the markup these patterns rewrite, and
+        # the build would otherwise succeed and ship a grey-boxed embed.
+        run: python build_web.py --strict
+
+      - name: Check the bundle is what the page expects
+        run: |
+          test -f build/web/index.html
+          test -f build/web/flappy-bird.tar.gz
+          # The trims that matter most to the embed, asserted on the
+          # output rather than on the patterns that produced it.
+          grep -q 'data-os="gui"' build/web/index.html
+          ! grep -q 'vtx' build/web/index.html
+          ! grep -q 'powderblue' build/web/index.html
+          ! test -e build/web/flappy-bird.apk
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: web-bundle
+          path: build/web
+          if-no-files-found: error
+
+  publish:
+    name: Open a build PR on the website
+    needs: verify
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    # Serialise publishes so two pushes cannot race on the same branch in
+    # the website repo. Never cancelled: see the note on the group above.
+    concurrency:
+      group: publish-website
+      cancel-in-progress: false
+    env:
+      # One machine-owned branch, recreated from the website's default
+      # branch every run, so repeated pushes to main keep updating a
+      # single pull request instead of opening a pile of them.
+      BUILD_BRANCH: flappy-bird-build
+    steps:
+      - name: Check the publish target is configured
+        # actions/checkout treats an empty `repository:` as this repo, so
+        # an unset variable would send the rm -rf and the commit below at
+        # this repository instead of the website. Fail loudly first.
+        env:
+          TARGET_REPO: ${{ vars.WEBSITE_REPO }}
+          TARGET_PATH: ${{ vars.WEBSITE_PATH }}
+          TARGET_TOKEN: ${{ secrets.WEBSITE_REPO_TOKEN }}
+        run: |
+          missing=""
+          [ -n "$TARGET_REPO" ] || missing="$missing vars.WEBSITE_REPO"
+          [ -n "$TARGET_PATH" ] || missing="$missing vars.WEBSITE_PATH"
+          [ -n "$TARGET_TOKEN" ] || missing="$missing secrets.WEBSITE_REPO_TOKEN"
+          if [ -n "$missing" ]; then
+            echo "::error::Not configured to publish. Missing:$missing"
+            exit 1
+          fi
+          case "$TARGET_PATH" in
+            /*|*..*)
+              echo "::error::WEBSITE_PATH must be a relative path inside the repo"
+              exit 1
+              ;;
+          esac
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: web-bundle
+          path: bundle
+
+      - name: Check out the website
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ vars.WEBSITE_REPO }}
+          # GITHUB_TOKEN only reaches this repository, so writing to
+          # another one needs a fine-grained PAT with Contents and Pull
+          # requests both set to read and write on the website repo.
+          token: ${{ secrets.WEBSITE_REPO_TOKEN }}
+          path: website
+          # No `ref:`, so this lands on the website's default branch,
+          # which is what the pull request will target. Full history
+          # because a server will refuse a branch pushed from a shallow
+          # clone.
+          fetch-depth: 0
+
+      - name: Replace the bundle
+        env:
+          TARGET_PATH: ${{ vars.WEBSITE_PATH }}
+        # Wholesale replace rather than copy over the top, so a file that
+        # pygbag stops emitting does not linger in the website repo.
+        run: |
+          rm -rf "website/$TARGET_PATH"
+          mkdir -p "website/$TARGET_PATH"
+          cp -R bundle/. "website/$TARGET_PATH/"
+          ls -l "website/$TARGET_PATH"
+
+      - name: Commit the bundle to a branch
+        id: commit
+        working-directory: website
+        env:
+          TARGET_PATH: ${{ vars.WEBSITE_PATH }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -c "$BUILD_BRANCH"
+          git add -A -- "$TARGET_PATH"
+          # Compares against the default branch we just branched from, so
+          # this is "does the site already serve these bytes". pygbag's
+          # .tar.gz embeds mtimes, so an unchanged game usually still
+          # rebuilds to different bytes and this rarely skips.
+          if git diff --cached --quiet; then
+            echo "The site already has this bundle; no pull request needed."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git commit \
+            -m "Update the Flappy Bird build" \
+            -m "From ${{ github.repository }}@${{ github.sha }}."
+          # Force, because the branch is rebuilt from the default branch
+          # on every run rather than added to. It holds generated output
+          # and nothing else, so there is no hand-written work to lose.
+          git push --force origin "HEAD:refs/heads/$BUILD_BRANCH"
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Open or update the pull request
+        if: steps.commit.outputs.changed == 'true'
+        working-directory: website
+        env:
+          GH_TOKEN: ${{ secrets.WEBSITE_REPO_TOKEN }}
+          TARGET_REPO: ${{ vars.WEBSITE_REPO }}
+          SOURCE_REPO: ${{ github.repository }}
+        run: |
+          # The force-push above already updated any PR that was open on
+          # this branch, so only open one when there is not one already.
+          url=$(gh pr list --repo "$TARGET_REPO" --head "$BUILD_BRANCH" \
+            --state open --json url --jq '.[0].url // empty')
+
+          if [ -n "$url" ]; then
+            echo "Updated the open pull request."
+          else
+            cat > /tmp/pr-body.md <<BODY
+          Rebuilt from [\`${GITHUB_SHA:0:7}\`](https://github.com/$SOURCE_REPO/commit/$GITHUB_SHA) on \`$SOURCE_REPO\`.
+
+          Generated by \`build_web.py\`, so there is nothing here to review line by line. The quickest check is the Vercel preview for this pull request: open the project page and press play.
+
+          This branch is recreated on every push to \`main\` on the game's repo, so this pull request updates in place rather than a new one appearing each time.
+          BODY
+            url=$(gh pr create --repo "$TARGET_REPO" --head "$BUILD_BRANCH" \
+              --title "Update the Flappy Bird build" \
+              --body-file /tmp/pr-body.md)
+            echo "Opened a pull request."
+          fi
+
+          echo "[Review the build PR on the website]($url)" >> "$GITHUB_STEP_SUMMARY"
diff --git a/README.md b/README.md
index 6209d5b..5ee9c35 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,7 @@ A Flappy Bird clone written in Python with pygame.
 
 ![Python](https://img.shields.io/badge/python-3.11-blue)
 ![pygame](https://img.shields.io/badge/pygame-2.6-green)
+[![CI](https://github.com/sschroederdev/python-flappy-bird/actions/workflows/ci.yml/badge.svg)](https://github.com/sschroederdev/python-flappy-bird/actions/workflows/ci.yml)
 
 ## Running it
 
@@ -34,6 +35,65 @@ repo directly. pygbag packs *every* file in the folder it is given, and
 its ignore filter does not catch a local `.venv` — building in place
 sweeps the virtualenv into the download and turns 77KB into 12MB.
 
+## Tests and CI
+
+```bash
+pip install -r requirements-dev.txt
+pycodestyle .
+python -m unittest discover -s tests -t .
+```
+
+The tests drive the state machine a frame at a time instead of running
+`Game.run`, which loops until the window closes, and they run headless
+under SDL's dummy video driver. They lean towards the bugs listed in
+[How it works](#how-it-works) below, since those are the ones a refactor
+is most likely to reintroduce.
+
+[`ci.yml`](.github/workflows/ci.yml) runs the same two commands on every
+pull request, then builds the bundle with `--strict` and checks the
+output. `--strict` turns a trim that no longer matches into a build
+failure: a pygbag upgrade can change the markup those patterns rewrite,
+and without it the build would still succeed and ship an embed with a
+grey box around it.
+
+## Publishing
+
+On a push to `main`, CI puts the freshly built `build/web` on a branch in
+the portfolio site's repo and opens a pull request. Merging it is what
+ships the new build. The demo there is an `<iframe>` served from the
+site's `public/` folder so that it is same-origin, so the built files
+have to live in that repo rather than on a host of their own.
+
+The pull request is worth almost nothing to read — it is a regenerated
+`.tar.gz` and an `index.html` — so review it by opening the Vercel
+preview the site builds for the PR and playing the game on it.
+
+Every run reuses one branch, `flappy-bird-build`, rebuilt from the
+website's default branch and force-pushed. So a second push to `main`
+updates the open pull request rather than opening another one, and the
+branch is never more than one commit ahead. Nothing hand-written lives on
+it; do not commit to it expecting the commit to survive.
+
+Publishing needs three settings on this repository, under
+**Settings > Secrets and variables > Actions**:
+
+| Setting | Kind | Value |
+| ------- | ---- | ----- |
+| `WEBSITE_REPO` | Variable | `sschroederdev/website` |
+| `WEBSITE_PATH` | Variable | `public/flappy` |
+| `WEBSITE_REPO_TOKEN` | Secret | A fine-grained PAT |
+
+The built-in `GITHUB_TOKEN` only reaches the repository it runs in, so
+writing to another one needs a [fine-grained PAT](https://github.com/settings/personal-access-tokens)
+scoped to the website repo alone, with **Contents: Read and write** and
+**Pull requests: Read and write**. It expires on whatever date you give
+it, and publishing fails until it is renewed.
+
+Until all three are set the publish job fails on its first step, by
+design — `actions/checkout` reads an empty `repository:` as *this* repo,
+and the step after it deletes the target directory. Lint, tests and the
+build are a separate job and keep passing either way.
+
 ## Controls
 
 | Input          | Action                    |
diff --git a/build_web.py b/build_web.py
index 372c409..179f12a 100644
--- a/build_web.py
+++ b/build_web.py
@@ -13,10 +13,14 @@
 
     python build_web.py            # build into build/web
     python build_web.py --serve    # build, then serve it on :8000
+    python build_web.py --strict   # fail if a trim no longer matches
 """
 
 import argparse
+import functools
+import http.server
 import shutil
+import socketserver
 import subprocess
 import sys
 import tempfile
@@ -25,11 +29,72 @@
 PROJECT_DIR = Path(__file__).resolve().parent
 OUTPUT_DIR = PROJECT_DIR / "build" / "web"
 
+# pygbag names the bundle after the folder it builds from.
+APP_NAME = "flappy-bird"
+
 # Everything the game opens at runtime, and nothing else.
 RUNTIME_FILES = ["main.py", "flappybirdclone.py"]
 RUNTIME_DIRS = ["images"]
 
 
+def trim(output_dir, app_name, strict=False):
+    """Strip what the embedded build never uses.
+
+    None of this is large next to the ~10MB CPython runtime the page
+    pulls from the pygbag CDN, but it removes a dead file, a request
+    that 404s, and the debug terminal, which does not belong in an
+    embed on a portfolio page.
+    """
+    # The .apk is only read when the page is hosted on itch.io; every
+    # other host takes the .tar.gz. See the loader in index.html.
+    apk = output_dir / f"{app_name}.apk"
+    if apk.exists():
+        apk.unlink()
+
+    # pygbag's own favicon, irrelevant inside an iframe.
+    favicon = output_dir / "favicon.png"
+    if favicon.exists():
+        favicon.unlink()
+
+    index = output_dir / "index.html"
+    html = index.read_text(encoding="utf-8")
+    replacements = [
+        # vtx is the xterm.js debug console (~90KB over the wire) and
+        # snd is the audio shim. This game has neither a console worth
+        # showing nor any sound.
+        ('data-os="vtx,snd,gui"', 'data-os="gui"'),
+        ('<link rel="icon" type="image/png" href="favicon.png" '
+         'sizes="16x16">', ""),
+        # pygbag emits this with a doubled slash and the CDN 404s it.
+        ('<script src="https://pygame-web.github.io/cdn/0.9.3'
+         '//browserfs.min.js"></script>', ""),
+        # pygbag paints the page around the canvas a flat grey, once in
+        # CSS and again from JS after boot. Both have to go transparent
+        # so an iframe picks up whatever the host page is using and the
+        # embed works in light and dark themes alike.
+        ("background-color:powderblue;", "background-color: transparent;"),
+        ('platform.document.body.style.background = "#7f7f7f"',
+         'platform.document.body.style.background = "transparent"'),
+    ]
+    missing = [old for old, _ in replacements if old not in html]
+    for old, new in replacements:
+        html = html.replace(old, new)
+    index.write_text(html, encoding="utf-8")
+
+    if missing:
+        # A pygbag upgrade can change the markup out from under these
+        # patterns. The build still succeeds, so nothing else would
+        # notice until the embed showed up grey on the live page.
+        for old in missing:
+            print(f"  warning: could not trim, pattern not found: "
+                  f"{old[:60]}")
+        if strict:
+            raise SystemExit(
+                f"--strict: {len(missing)} of {len(replacements)} trim "
+                f"patterns did not match; pygbag's output has changed."
+            )
+
+
 def stage(staging_dir):
     """Copy the runtime files into a clean folder for pygbag to pack."""
     for name in RUNTIME_FILES:
@@ -38,12 +103,12 @@ def stage(staging_dir):
         shutil.copytree(PROJECT_DIR / name, staging_dir / name)
 
 
-def build(staging_dir, serve):
+def build(staging_dir):
     """Run pygbag over the staged folder."""
-    command = [sys.executable, "-m", "pygbag", "--title", "Flappy Bird"]
-    if not serve:
-        command.append("--build")
-    command.append(str(staging_dir))
+    command = [
+        sys.executable, "-m", "pygbag", "--build",
+        "--title", "Flappy Bird", str(staging_dir),
+    ]
     subprocess.run(command, check=True)
 
 
@@ -62,6 +127,22 @@ def collect(staging_dir):
     shutil.copytree(built, OUTPUT_DIR, dirs_exist_ok=True)
 
 
+def serve(port):
+    """Serve the trimmed build, the way a real host would.
+
+    pygbag's own test server rewrites the CDN URLs to proxy through
+    itself. Serving the files as they are keeps the page pointed at the
+    real CDN, which is what it will do once it is deployed.
+    """
+    handler = functools.partial(
+        http.server.SimpleHTTPRequestHandler, directory=str(OUTPUT_DIR)
+    )
+    with socketserver.TCPServer(("127.0.0.1", port), handler) as httpd:
+        print(f"\nServing {OUTPUT_DIR} on http://localhost:{port}/")
+        print("Ctrl+C to stop.")
+        httpd.serve_forever()
+
+
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(
@@ -69,28 +150,39 @@ def main():
         action="store_true",
         help="serve the build on http://localhost:8000 when it is done",
     )
+    parser.add_argument(
+        "--port", type=int, default=8000, help="port for --serve"
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="fail if any of the trims to index.html no longer match",
+    )
     args = parser.parse_args()
 
     with tempfile.TemporaryDirectory() as tmp:
         # pygbag names the bundle after this folder.
-        staging_dir = Path(tmp) / "flappy-bird"
+        staging_dir = Path(tmp) / APP_NAME
         staging_dir.mkdir()
         stage(staging_dir)
-        build(staging_dir, args.serve)
-        if not args.serve:
-            collect(staging_dir)
-
-    if not args.serve:
-        total = sum(
-            path.stat().st_size
-            for path in OUTPUT_DIR.rglob("*")
-            if path.is_file()
-        )
-        print(f"\nBuilt {OUTPUT_DIR} ({total / 1024:.0f} KB)")
-        for path in sorted(OUTPUT_DIR.rglob("*")):
-            if path.is_file():
-                size = path.stat().st_size / 1024
-                print(f"  {path.relative_to(OUTPUT_DIR)}  {size:.0f} KB")
+        build(staging_dir)
+        collect(staging_dir)
+
+    trim(OUTPUT_DIR, APP_NAME, strict=args.strict)
+
+    total = sum(
+        path.stat().st_size
+        for path in OUTPUT_DIR.rglob("*")
+        if path.is_file()
+    )
+    print(f"\nBuilt {OUTPUT_DIR} ({total / 1024:.0f} KB)")
+    for path in sorted(OUTPUT_DIR.rglob("*")):
+        if path.is_file():
+            size = path.stat().st_size / 1024
+            print(f"  {path.relative_to(OUTPUT_DIR)}  {size:.0f} KB")
+
+    if args.serve:
+        serve(args.port)
 
 
 if __name__ == "__main__":
diff --git a/requirements-dev.txt b/requirements-dev.txt
new file mode 100644
index 0000000..495d484
--- /dev/null
+++ b/requirements-dev.txt
@@ -0,0 +1,5 @@
+# Everything CI needs on top of requirements.txt. The tests themselves run
+# on stdlib unittest, so there is no test runner to install.
+pycodestyle>=2.14
+pyflakes>=3.4
+pygbag>=0.9.3
diff --git a/setup.cfg b/setup.cfg
new file mode 100644
index 0000000..81c355d
--- /dev/null
+++ b/setup.cfg
@@ -0,0 +1,4 @@
+# Keeps `pycodestyle .` and `python -m unittest discover` behaving the same
+# locally as they do in CI. build/ holds pygbag output and .venv is not ours.
+[pycodestyle]
+exclude = .git,__pycache__,.venv,venv,virtualenv,build
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_game.py b/tests/test_game.py
new file mode 100644
index 0000000..859e09b
--- /dev/null
+++ b/tests/test_game.py
@@ -0,0 +1,282 @@
+"""Headless tests for the game logic.
+
+These drive the state machine a frame at a time rather than running
+``Game.run``, which loops until the window closes. SDL's dummy driver
+gives us a real display surface without a window, so sprites still
+convert and blit exactly as they do on screen.
+
+The cases here are deliberately weighted towards the bugs called out in
+the README: they are the ones a refactor is most likely to reintroduce.
+"""
+
+import os
+import unittest
+from pathlib import Path
+
+# Must be set before pygame initialises its video backend. CI exports the
+# same values; setting them here keeps the suite runnable on a desktop.
+os.environ.setdefault("SDL_VIDEODRIVER", "dummy")
+os.environ.setdefault("SDL_AUDIODRIVER", "dummy")
+
+import pygame  # noqa: E402
+
+import flappybirdclone as game  # noqa: E402
+
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+
+
+class GameTestCase(unittest.TestCase):
+    """Shared display surface and sprites for the whole suite."""
+
+    @classmethod
+    def setUpClass(cls):
+        pygame.init()
+        cls.screen = pygame.display.set_mode(
+            (game.WIN_WIDTH, game.WIN_HEIGHT)
+        )
+        cls.images = game.load_images()
+
+    @classmethod
+    def tearDownClass(cls):
+        pygame.quit()
+
+    def setUp(self):
+        pygame.event.clear()
+        self.game = game.Game(self.screen, self.images)
+
+
+class TestBirdPhysics(GameTestCase):
+
+    def test_position_accumulates_as_a_float(self):
+        """Sub-pixel velocity must not be truncated away.
+
+        pygame.Rect stores integers, so adding a velocity of less than 1
+        straight onto rect.y would round to no movement at all. The first
+        four frames of a fall are +0.5, +1.0, +1.5 and +2.0.
+        """
+        bird = self.game.bird
+        start = bird.y
+        for _ in range(4):
+            bird.update()
+        self.assertAlmostEqual(bird.y, start + 5.0)
+        self.assertEqual(bird.rect.y, round(bird.y))
+
+    def test_fall_speed_is_capped(self):
+        bird = self.game.bird
+        for _ in range(200):
+            bird.update()
+        self.assertEqual(bird.velocity, game.MAX_FALL_SPEED)
+
+    def test_flap_reverses_the_fall(self):
+        bird = self.game.bird
+        for _ in range(10):
+            bird.update()
+        self.assertGreater(bird.velocity, 0)
+        bird.flap()
+        falling_y = bird.y
+        bird.update()
+        self.assertLess(bird.y, falling_y)
+
+    def test_tilting_does_not_grow_the_hitbox(self):
+        """The rotation is applied to a throwaway copy, not to self.rect.
+
+        If the rotated surface were assigned back, the hitbox would swell
+        as the bird tilts and the player would clip pipes they missed.
+        """
+        bird = self.game.bird
+        unrotated = bird.rect.copy()
+        bird.velocity = game.MAX_FALL_SPEED
+        bird.draw(self.screen)
+        self.assertEqual(bird.rect.size, unrotated.size)
+        self.assertEqual(bird.rect.topleft, unrotated.topleft)
+
+
+class TestInput(GameTestCase):
+
+    def test_only_fresh_keydowns_count(self):
+        """Holding a key must not flap once per gravity cycle.
+
+        read_input reports KEYDOWN events, not the held key state, so a
+        held key produces input on exactly one frame.
+        """
+        pygame.event.post(
+            pygame.event.Event(pygame.KEYDOWN, key=pygame.K_SPACE)
+        )
+        _, keys, _ = game.read_input()
+        self.assertIn(pygame.K_SPACE, keys)
+
+        # Next frame the key is still physically down, but with no new
+        # event to report there is nothing in the queue.
+        _, keys, _ = game.read_input()
+        self.assertNotIn(pygame.K_SPACE, keys)
+
+    def test_touch_and_click_both_register_as_a_tap(self):
+        for event_type in (pygame.MOUSEBUTTONDOWN, pygame.FINGERDOWN):
+            with self.subTest(event_type=event_type):
+                pygame.event.clear()
+                pygame.event.post(pygame.event.Event(event_type))
+                _, _, tapped = game.read_input()
+                self.assertTrue(tapped)
+
+    def test_quit_is_reported(self):
+        pygame.event.post(pygame.event.Event(pygame.QUIT))
+        quit_requested, _, _ = game.read_input()
+        self.assertTrue(quit_requested)
+
+
+class TestStateMachine(GameTestCase):
+
+    def start_playing(self):
+        self.game.update_start({pygame.K_SPACE}, False)
+
+    def crash(self):
+        """Let the bird fall until the round ends."""
+        for _ in range(600):
+            self.game.update_play(set(), False)
+            if self.game.state == "end":
+                return
+        self.fail("the bird never crashed")
+
+    def test_space_starts_the_game(self):
+        self.assertEqual(self.game.state, "start")
+        self.start_playing()
+        self.assertEqual(self.game.state, "play")
+        # The keypress that starts the game is also the first flap.
+        self.assertEqual(self.game.bird.velocity, game.FLAP_VELOCITY)
+
+    def test_tap_starts_the_game(self):
+        self.game.update_start(set(), True)
+        self.assertEqual(self.game.state, "play")
+
+    def test_bird_stays_put_before_the_game_starts(self):
+        y = self.game.bird.y
+        for _ in range(30):
+            self.game.update_start(set(), False)
+        self.assertEqual(self.game.bird.y, y)
+
+    def test_falling_ends_the_round(self):
+        self.start_playing()
+        self.crash()
+
+    def test_restart_delay_swallows_the_fatal_input(self):
+        """The tap that killed you must not also restart the round.
+
+        On a touchscreen the crash and the next frame's input are the
+        same gesture, so the end state ignores input for RESTART_DELAY
+        frames.
+        """
+        self.start_playing()
+        self.crash()
+
+        self.game.update_end(set(), True)
+        self.assertEqual(self.game.state, "end")
+
+        for _ in range(game.RESTART_DELAY):
+            self.game.update_end(set(), False)
+        self.game.update_end({pygame.K_r}, False)
+        self.assertEqual(self.game.state, "start")
+
+
+class TestScoring(GameTestCase):
+
+    def add_top_pipe(self, x):
+        pipe = game.Pipe(x, -560, self.images["pipe_top"], "top")
+        self.game.pipes.add(pipe)
+        return pipe
+
+    def cleared_x(self, image):
+        """The x at which a pipe of this image sits just behind the bird."""
+        return self.game.bird.rect.left - image.get_width() - 1
+
+    def test_a_cleared_pipe_scores_once(self):
+        pipe = self.add_top_pipe(self.cleared_x(self.images["pipe_top"]))
+        self.assertLess(pipe.rect.right, self.game.bird.rect.left)
+        self.game.update_score()
+        self.game.update_score()
+        self.assertEqual(self.game.score, 1)
+        self.assertTrue(pipe.scored)
+
+    def test_an_uncleared_pipe_does_not_score(self):
+        self.add_top_pipe(game.PIPE_SPAWN_X)
+        self.game.update_score()
+        self.assertEqual(self.game.score, 0)
+
+    def test_the_bottom_pipe_is_not_counted_separately(self):
+        """A pair is worth one point, so only the top half is scored."""
+        image = self.images["pipe_bottom"]
+        bottom = game.Pipe(self.cleared_x(image), 400, image, "bottom")
+        self.game.pipes.add(bottom)
+        # Cleared on the same terms the top half would have scored on.
+        self.assertLess(bottom.rect.right, self.game.bird.rect.left)
+        self.game.update_score()
+        self.assertEqual(self.game.score, 0)
+
+    def test_high_score_survives_a_restart(self):
+        self.game.update_start({pygame.K_SPACE}, False)
+        self.game.score = 7
+        for _ in range(600):
+            self.game.update_play(set(), False)
+            if self.game.state == "end":
+                break
+        self.assertEqual(self.game.state, "end")
+        self.assertEqual(self.game.high_score, 7)
+
+        for _ in range(game.RESTART_DELAY + 1):
+            self.game.update_end(set(), False)
+        self.game.update_end({pygame.K_r}, False)
+        self.assertEqual(self.game.state, "start")
+        self.assertEqual(self.game.score, 0)
+        self.assertEqual(self.game.high_score, 7)
+
+
+class TestGround(GameTestCase):
+
+    def test_tiles_land_on_the_texture_repeat(self):
+        """ground.png repeats every 24px but the image is 551px wide.
+
+        Spacing tiles by the image width would put a visible break in the
+        diagonal lines at every seam.
+        """
+        self.assertEqual(game.GROUND_SPACING % 24, 0)
+        self.assertLess(game.GROUND_SPACING, game.WIN_WIDTH)
+
+    def test_the_ground_stays_tiled_across_the_screen(self):
+        frames = game.GROUND_SPACING * 2 // game.SCROLL_SPEED
+        for _ in range(frames):
+            self.game.grounds.update()
+            self.game.spawn_ground()
+            covered = max(
+                (ground.rect.right for ground in self.game.grounds),
+                default=0,
+            )
+            self.assertGreaterEqual(covered, game.WIN_WIDTH)
+
+
+class TestWebEntryPoint(unittest.TestCase):
+    """Guards on the two pygbag traps documented in the README."""
+
+    def test_entry_point_imports_pygame(self):
+        """pygbag scans only main.py to decide what to preload.
+
+        Without a bare ``import pygame`` there, pygame is never properly
+        loaded and the browser build dies on "module 'pygame' has no
+        attribute 'sprite'".
+        """
+        source = (PROJECT_DIR / "main.py").read_text(encoding="utf-8")
+        self.assertRegex(source, r"(?m)^import pygame$")
+
+    def test_no_submodule_imports_of_pygame(self):
+        """pygbag reads ``import pygame.x`` as a PyPI package.
+
+        It then goes looking for it and the build fails, so submodules
+        have to be reached by attribute off the top-level import.
+        """
+        for name in ("main.py", "flappybirdclone.py"):
+            with self.subTest(name=name):
+                source = (PROJECT_DIR / name).read_text(encoding="utf-8")
+                self.assertNotRegex(source, r"(?m)^\s*import pygame\.")
+                self.assertNotRegex(source, r"(?m)^\s*from pygame\.")
+
+
+if __name__ == "__main__":
+    unittest.main()