diff --git a/README.md b/README.md index 91711d6..f777648 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,66 @@ -# AI Death Clock ๐Ÿ’€ +# ๐Ÿ’€ AI Token Deathclock [![Unit Tests](https://github.com/nitrocode/token-deathclock/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/nitrocode/token-deathclock/actions/workflows/unit-tests.yml) [![E2E Tests](https://github.com/nitrocode/token-deathclock/actions/workflows/e2e-tests.yml/badge.svg)](https://github.com/nitrocode/token-deathclock/actions/workflows/e2e-tests.yml) [![Deploy](https://github.com/nitrocode/token-deathclock/actions/workflows/deploy.yml/badge.svg)](https://github.com/nitrocode/token-deathclock/actions/workflows/deploy.yml) [![codecov](https://codecov.io/gh/nitrocode/token-deathclock/branch/main/graph/badge.svg)](https://codecov.io/gh/nitrocode/token-deathclock) -> **Live site:** `https://nitrocode.github.io/token-deathclock/` +> ๐ŸŒ **Live site:** [nitrocode.github.io/token-deathclock](https://nitrocode.github.io/token-deathclock/) -A GitHub Pages visualisation that shows the environmental cost of global AI token consumption โ€” featuring live counters, milestone tracker, and a token-growth chart with projections. +Every AI prompt has a cost. This site makes it visceral. ๐Ÿ”ฅ + +Watch the global AI token counter tick in real time, track environmental milestones as they fall, and discover what humanity could have done instead with those same resources. Created by **RB**. --- -## Features +## โœจ Features | Feature | Details | |---------|---------| -| **Live counter** | Estimated global AI tokens consumed since Jan 2020, ticking in real-time | -| **Session counter** | Tokens consumed globally since *you* opened the page | -| **Environmental milestones** | 7 thresholds (trees โ†’ bees โ†’ water โ†’ coral โ†’ glaciers โ†’ ocean โ†’ extinction) with triggered status, progress bars, and consequence descriptions | -| **Growth chart** | Historical data + 18-month projection on a log scale (Chart.js) | -| **Predictions table** | Predicted calendar dates for each milestone | -| **Dark / Light mode** | Toggle button; dark mode is the default | +| โฑ๏ธ **Live counter** | Estimated global AI tokens consumed since Jan 2020, ticking in real-time | +| ๐Ÿ“Š **Session counter** | Tokens consumed globally since *you* opened the page | +| ๐ŸŒฟ **Environmental milestones** | 7 thresholds (trees โ†’ bees โ†’ water โ†’ coral โ†’ glaciers โ†’ ocean โ†’ extinction) with progress bars and consequence descriptions | +| ๐Ÿ“ˆ **Growth chart** | Historical data + 18-month projection on a log scale (Chart.js) | +| ๐Ÿ—“๏ธ **Predictions table** | Predicted calendar dates for each upcoming milestone | +| ๐Ÿ† **Doom achievements** | Unlock badges as global consumption hits new levels | +| ๐ŸŽฎ **Accelerate the Doom** | A satirical mini-game โ€” click to burn tokens faster | +| ๐Ÿงฎ **Personal footprint calculator** | Estimate your own AI token footprint | +| ๐ŸŒ™ **Dark / Light mode** | Toggle button; dark mode is the default | --- -## Running Locally +## ๐Ÿš€ Running Locally ```bash -# Clone and open +# Clone the repo git clone https://github.com/nitrocode/token-deathclock.git cd token-deathclock + # Serve with any static server, e.g.: npx serve . # Then open http://localhost:3000 ``` +No build step required โ€” it's a fully static site. ๐ŸŽ‰ + --- -## Running Tests +## ๐Ÿงช Running Tests ```bash npm install -npm test # runs Jest with coverage -npm run test:ci # CI mode (fails on coverage drop) +npm test # runs Jest with coverage (interactive) +npm run test:ci # CI mode โ€” fails if coverage drops +npm run test:e2e # Playwright end-to-end tests ``` -Tests are in `tests/death-clock.test.js` and cover all pure functions in `death-clock-core.js`. +Unit tests live in [`tests/death-clock.test.js`](tests/death-clock.test.js) and cover all pure functions in [`death-clock-core.js`](death-clock-core.js). --- -## Coverage +## ๐Ÿ“Š Coverage Unit-test coverage is tracked by [Codecov](https://codecov.io/gh/nitrocode/token-deathclock). Every pull request receives an automated comment showing per-file coverage deltas; the PR check fails if coverage decreases. @@ -63,42 +72,98 @@ E2E tests run in CI via Playwright (Chromium). Their pass/fail status is shown b --- -## Deployment (GitHub Pages) +## ๐Ÿšข Deployment -The site is automatically deployed on every push to `main` via the `deploy.yml` workflow. -It is live at `https://nitrocode.github.io/token-deathclock/`. +The site deploys automatically on every push to `main` via the [`deploy.yml`](.github/workflows/deploy.yml) workflow, pushing to the `gh-pages` branch. ---- +๐Ÿ”— Live URL: [https://nitrocode.github.io/token-deathclock/](https://nitrocode.github.io/token-deathclock/) -## Architecture +Pull requests each get an isolated preview URL: +`https://nitrocode.github.io/token-deathclock/previews/pr-{number}/` +--- + +## ๐Ÿ—๏ธ Architecture + +### How it fits together + +```mermaid +flowchart TD + subgraph Source["๐Ÿ“ Source Files (edit these)"] + core["death-clock-core.js\nโ˜๏ธ Pure functions\n(no DOM, fully testable)"] + srcjs["src/js/\n00-state โ€ฆ 21-boot\n(feature modules)"] + styleSrc["styles/\nvariables, base,\nfeatures, etc."] + html["index.html\n๐Ÿ  Static HTML shell"] + yaml["milestones.yaml\nproject-stats.yaml\nCHANGELOG.md"] + end + + subgraph Generated["โš™๏ธ Auto-Generated (do not edit)"] + scriptjs["script.js\n(built from src/js/)"] + stylescss["styles.css\n(built from styles/)"] + datajs["*-data.js\n(built from YAML / MD)"] + end + + subgraph Tests["๐Ÿงช Tests"] + unit["tests/death-clock.test.js\nJest unit tests"] + e2e["tests/e2e/\nPlaywright E2E tests"] + end + + subgraph CI["๐Ÿค– GitHub Actions"] + deploy["deploy.yml\nGH Pages deploy"] + unitCI["unit-tests.yml\nJest + Codecov"] + e2eCI["e2e-tests.yml\nPlaywright"] + preview["preview.yml\nPR preview deploy"] + release["release-please.yml\nSemVer + changelog"] + end + + subgraph Live["๐ŸŒ GitHub Pages"] + site["nitrocode.github.io\n/token-deathclock/"] + end + + core -->|imported by| srcjs + srcjs -->|npm run build:js| scriptjs + styleSrc -->|npm run build:css| stylescss + yaml -->|npm run build:*| datajs + + html --> Live + scriptjs --> Live + stylescss --> Live + datajs --> Live + + core --> unit + html --> e2e + scriptjs --> e2e + + unit --> unitCI + e2e --> e2eCI + Live -->|push to main| deploy + deploy --> site ``` -. -โ”œโ”€โ”€ index.html โ† Main GitHub Pages entry point -โ”œโ”€โ”€ styles.css โ† Dark/light theme, animations, layout -โ”œโ”€โ”€ death-clock-core.js โ† Pure functions (no DOM deps; testable) -โ”œโ”€โ”€ script.js โ† DOM manipulation, Chart.js, RAF loop -โ”œโ”€โ”€ package.json โ† Jest config & dev deps -โ”œโ”€โ”€ tests/ -โ”‚ โ””โ”€โ”€ death-clock.test.js -โ””โ”€โ”€ .github/ - โ””โ”€โ”€ workflows/ - โ”œโ”€โ”€ deploy.yml โ† GitHub Pages deployment - โ”œโ”€โ”€ unit-tests.yml โ† Jest unit tests + Codecov upload - โ””โ”€โ”€ e2e-tests.yml โ† Playwright E2E tests -``` + +### Key source files + +| File | Role | +|------|------| +| [`death-clock-core.js`](death-clock-core.js) | ๐Ÿง  Pure calculation functions โ€” no DOM, fully unit-testable | +| [`src/js/`](src/js/) | ๐Ÿ–ฅ๏ธ Feature modules compiled into `script.js` | +| [`styles/`](styles/) | ๐ŸŽจ CSS source files compiled into `styles.css` | +| [`index.html`](index.html) | ๐Ÿ  Static HTML shell loaded by GitHub Pages | +| [`milestones.yaml`](milestones.yaml) | ๐Ÿ Source of truth for environmental milestone data | +| [`project-stats.yaml`](project-stats.yaml) | ๐Ÿ“ฆ Tracks PR count + tokens consumed building this project | + +> โš ๏ธ Never edit `script.js`, `styles.css`, or `*-data.js` directly โ€” they are auto-generated. Edit the source files and run the relevant `npm run build:*` command. --- -## Environmental Data Sources +## ๐ŸŒ Environmental Data Sources | Metric | Source | |--------|--------| | Energy per token (~0.0003 kWh / 1K tokens) | Google/DeepMind inference benchmarks, MLPerf | -| COโ‚‚ per kWh (0.4 kg) | IEA global average grid intensity 2024 | -| Water per token (~0.5 L / 1K tokens) | Microsoft sustainability report 2023 | -| COโ‚‚ per tree (~21 kg/year) | US Forest Service estimates | -| Historical token growth | OpenAI usage blog, Epoch AI, AI Index 2024 | +| COโ‚‚ per kWh (0.4 kg) | [IEA global average grid intensity 2024](https://www.iea.org/data-and-statistics/charts/global-average-co2-intensity-of-electricity-generation-2000-2023) | +| Water per token (~0.5 L / 1K tokens) | [Microsoft sustainability report 2023](https://www.microsoft.com/en-us/corporate-responsibility/sustainability/report) | +| COโ‚‚ per tree (~21 kg/year) | [US Forest Service estimates](https://www.fs.usda.gov/ccrc/topics/urban-forests/canopy-cover-and-carbon-sequestration) | +| Historical token growth | OpenAI usage blog, [Epoch AI](https://epochai.org/), [AI Index 2024](https://aiindex.stanford.edu/report/) | -> All figures are illustrative estimates intended to communicate scale, not precise measurements. +> ๐Ÿ“Œ All figures are illustrative estimates intended to communicate scale, not precise measurements.