feat: add test coverage run with vitest + v8

.github/workflows/coverage.yml

@@ -0,0 +1,90 @@
+# Run vitest+v8 coverage on PRs and main pushes.
+#
+# Uploads the coverage report as an artifact for human download and
+# writes a summary table to the workflow run page. Currently does NOT
+# gate on threshold and does NOT post deltas to PRs — coverage is
+# informational. Closed-loop dark-factory feedback (PR comment + delta
+# gate) is tracked as a follow-up issue.
+#
+# Runs against the chromium browser project only. Firefox/WebKit
+# coverage is not measurable (JSC and SpiderMonkey don't expose V8's
+# coverage protocol). See vitest.config.ts coverage block for details.
+name: Coverage
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# One coverage run per ref; cancel in-progress runs when a new push
+# arrives so we always report on the current tip.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  coverage:
+    name: vitest+v8 coverage
+    runs-on: ubuntu-latest
+    container:
+      image: mcr.microsoft.com/playwright:v1.59.1-noble
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install Bun
+        run: python3 tools/install-bun
+
+      # The Playwright noble image ships without jq; the coverage-summary
+      # step needs it to format the workflow run summary table.
+      - name: Install jq
+        run: apt-get update && apt-get install -y --no-install-recommends jq
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run coverage
+        run: bun run test:coverage
+        env:
+          HOME: /root
+
+      - name: Coverage summary
+        if: always()
+        run: |
+          if [ -f coverage/coverage-summary.json ]; then
+            echo "## Coverage summary" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "| Metric | Pct | Covered/Total |" >> "$GITHUB_STEP_SUMMARY"
+            echo "|---|---|---|" >> "$GITHUB_STEP_SUMMARY"
+            jq -r '
+              .total |
+              "| Lines | \(.lines.pct)% | \(.lines.covered)/\(.lines.total) |\n" +
+              "| Statements | \(.statements.pct)% | \(.statements.covered)/\(.statements.total) |\n" +
+              "| Branches | \(.branches.pct)% | \(.branches.covered)/\(.branches.total) |\n" +
+              "| Functions | \(.functions.pct)% | \(.functions.covered)/\(.functions.total) |"
+            ' coverage/coverage-summary.json >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      # Machine-readable artifacts (~220 KB), retained 30 days. Designed
+      # so a future closed-loop coverage workflow can download a base
+      # commit's data to compute deltas.
+      - name: Upload coverage data
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-data
+          path: |
+            coverage/coverage-summary.json
+            coverage/lcov.info
+          retention-days: 30
+
+      # Human-readable HTML report (~5 MB). Only on main pushes; short
+      # retention since PR runs don't benefit from it.
+      - name: Upload coverage HTML (main only)
+        if: always() && github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-html
+          path: coverage/lcov-report
+          retention-days: 7

.gitignore

@@ -22,6 +22,7 @@ node_modules
 _repo
 coverage
 coverage-temp
+COVERAGE.md
 builds/**/meta
 .nyc_output
 **/dist/*