From c7dff414882db3b7ef96cd7b4d0451301d52d637 Mon Sep 17 00:00:00 2001
From: gngpp <gngppz@gmail.com>
Date: Sun, 4 Oct 2026 11:25:06 +0800
Subject: [PATCH] fix(docs): isolate benchmark tests and refine dark theme

---
 bench/README.md                               |  9 +-
 bench/report.py                               | 40 ++++----
 bench/test_report.py                          | 31 +++++--
 docs/benchmark_view.py                        | 23 ++---
 docs/build.py                                 |  2 +-
 docs/mkdocs.yml                               | 17 +---
 .../partials/javascripts/palette.html         |  1 +
 docs/source/guide/advanced.md                 |  2 +-
 docs/source/guide/auth.md                     |  2 +-
 docs/source/guide/basic.md                    |  2 +-
 docs/source/guide/blocking.md                 |  2 +-
 docs/source/guide/emulation.md                |  2 +-
 docs/source/guide/proxy.md                    |  2 +-
 docs/source/guide/redirect-errors.md          |  2 +-
 docs/source/guide/websocket.md                |  2 +-
 docs/source/index.md                          |  2 +-
 docs/source/javascripts/benchmarks.js         | 36 +-------
 docs/source/stylesheets/benchmarks.css        | 43 ++-------
 docs/source/stylesheets/home.css              | 17 ++--
 docs/source/stylesheets/theme.css             | 91 +++++++++++++++++++
 docs/templates/benchmark.md                   | 32 ++-----
 pyproject.toml                                |  3 +
 22 files changed, 198 insertions(+), 165 deletions(-)
 create mode 100644 docs/overrides/partials/javascripts/palette.html
 create mode 100644 docs/source/stylesheets/theme.css

diff --git a/bench/README.md b/bench/README.md
index 53c619ad..d5bf678c 100644
--- a/bench/README.md
+++ b/bench/README.md
@@ -85,9 +85,12 @@ uv run --no-sync python bench/run.py \
   --server bench/server/target/release/wreq-benchmark-server \
   --sizes 10240,1048576 --concurrency 2 --requests 4 \
   --rounds 1 --warmup 0 --samples 1 --output bench/data/smoke/RUN.json
-uv run --no-sync python -m pytest bench/test_*.py
+uv run --no-sync python -m pytest bench
 ```
 
+Default `pytest` runs only `tests/`. The explicit command above checks the
+benchmark tools without running a performance measurement.
+
 ## Results and interpretation
 
 The JSON records the source SHA and dirty state, Python and package versions,
@@ -154,8 +157,8 @@ runner doesn't commit, push or enable benchmarks in CI.
 
 `python docs/build.py` reads and validates the checked-in `bench/data/latest.json`.
 It generates responsive light/dark SVG charts and fills
-`docs/templates/benchmark.md` with body-size controls and expandable tables.
-The built site includes a frozen raw JSON download. The build won't fetch
+`docs/templates/benchmark.md` with body-size controls and measurement details.
+The built site includes a frozen raw JSON copy. The build won't fetch
 measurements or start a benchmark, and missing or invalid data stops it.
 Read the Docs uses this same entry point.
 
diff --git a/bench/report.py b/bench/report.py
index 8c464025..81966318 100644
--- a/bench/report.py
+++ b/bench/report.py
@@ -87,7 +87,12 @@ def safe_data_link(link: str) -> str:
     return link
 
 
-def render_markdown(document: dict, data_link: str | None = None) -> str:
+def render_markdown(
+    document: dict,
+    data_link: str | None = None,
+    *,
+    environment_only: bool = False,
+) -> str:
     validate_document(document)
     config = document["configuration"]
     source = document["source"]
@@ -128,13 +133,19 @@ def render_markdown(document: dict, data_link: str | None = None) -> str:
         f"requests/batch: {config['requests']}; warm-up batches/round: {config['warmup']} |",
         "| Stream upload chunk | "
         + (
-            "Varies by payload; see body cases below"
+            (
+                "Varies by payload; recorded in raw JSON"
+                if environment_only
+                else "Varies by payload; see body cases below"
+            )
             if "stream_chunk_bytes_by_payload" in config
             else payload_label(config["stream_chunk_bytes"])
         )
         + " |",
         "",
     ]
+    if environment_only:
+        return "\n".join(lines)
     if "stream_chunk_bytes_by_payload" in config:
         lines += [
             "### Body cases",
@@ -168,27 +179,6 @@ def render_markdown(document: dict, data_link: str | None = None) -> str:
             f"{', '.join('HTTP/1.1' if p == 'h1' else 'HTTP/2' for p in capability['protocols'])} | "
             f"{', '.join(k.title() for k in capability['body_kinds'])} |"
         )
-    if any(
-        "response_read" in document["clients"][client] for client in ordered_clients
-    ):
-        lines += [
-            "",
-            '<details markdown="1">',
-            "<summary>Adapter settings</summary>",
-            "",
-            "| Client | Response consumption | Connection pool |",
-            "| --- | --- | --- |",
-        ]
-        for client in ordered_clients:
-            metadata = document["clients"][client]
-            pool = json.dumps(
-                metadata.get("pool", {"kind": "not recorded"}), sort_keys=True
-            )
-            lines.append(
-                f"| {escape(LABELS.get(client, client))} | "
-                f"{escape(metadata.get('response_read', 'Not recorded'))} | {escape(pool)} |"
-            )
-        lines += ["", "</details>"]
     lines += [
         "",
         "### Throughput comparison",
@@ -196,7 +186,9 @@ def render_markdown(document: dict, data_link: str | None = None) -> str:
         "Each value is total measured requests divided by total measured time "
         "across all rounds, in requests per second (RPS). All timed samples count. "
         "The raw JSON keeps individual timings, per-round results, response-payload "
-        "MB/s and native artifact SHA-256 hashes.",
+        "MB/s and native artifact SHA-256 hashes. Read chunking, buffering and "
+        "connection pools differ between adapters; their configurations are "
+        "recorded in the raw JSON.",
         "",
     ]
     results = {
diff --git a/bench/test_report.py b/bench/test_report.py
index 6db7ad1f..3b6e95f6 100644
--- a/bench/test_report.py
+++ b/bench/test_report.py
@@ -55,9 +55,9 @@ def test_report_aggregation_and_metadata_escaping():
     assert "`x`" not in text and "&#124;" in text
     assert report.escape("CPU's name") == "CPU's name"
     assert "javascript:source-repository" not in text
+    assert "Adapter settings" not in text and "<details" not in text
     assert (
-        '<details markdown="1">' in text
-        and "<summary>Adapter settings</summary>" in text
+        "Read chunking, buffering and connection pools differ between adapters" in text
     )
     assert f"{report.REPOSITORY}/commit/{document['source']['commit']}" in text
     for link in (
@@ -250,11 +250,21 @@ def no_network(*args, **kwargs):
     snapshot = root / "docs/source/assets/benchmark/latest.json"
     page = root / "docs/source/benchmark.md"
     assert json.loads(snapshot.read_text(encoding="utf-8")) == document
-    assert "{{BENCHMARK_RESULTS}}" not in page.read_text(encoding="utf-8")
-    assert "{{BENCHMARK_CHARTS}}" not in page.read_text(encoding="utf-8")
+    content = page.read_text(encoding="utf-8")
+    assert "{{BENCHMARK_RESULTS}}" not in content
+    assert "{{BENCHMARK_CHARTS}}" not in content
+    assert "<details" not in content and "<summary>" not in content
+    assert report.render_markdown(document, environment_only=True) in content
+    assert "### Throughput comparison" not in content
+    assert "| Upload / echo payload | Concurrency" not in content
+    assert "### Measurement environment" in content
+    assert "### Client versions and runtimes" not in content
+    assert "### Body cases" not in content
+    assert "## Runtime and client differences" in content
     charts = root / "docs/source/assets/benchmark/charts"
     assert len(list(charts.glob("*.svg"))) == 16
-    assert "assets/benchmark/latest.json" in page.read_text(encoding="utf-8")
+    assert "Download this build's raw JSON" not in content
+    assert "Raw JSON</a>" not in content and "Download SVG" not in content
     assert build.prepare(data=snapshot, root=root) == document
     override = root / "override.json"
     alternate = make_document(commit="d" * 40)
@@ -318,8 +328,17 @@ def test_chart_explorer_controls_fallback_and_inert_metadata(tmp_path):
     assert 'value="h1" selected' in content and 'value="h2"' not in content
     assert content.count("data-chart-payload=") == 1
     assert content.count("data-chart-controls hidden") == 2
-    assert "<noscript>" in content and "Values for this chart" in content
+    assert "<noscript>" in content and "measurement details remain available" in content
+    assert "Values for this chart" not in content and "data-chart-values" not in content
+    assert "<table" not in content and "<details" not in content
+    assert "data-chart-download" not in content and "Download SVG" not in content
+    assert "Raw JSON</a>" not in content
+    assets = catalog["cases"][0]["assets"]["dark"]
+    assert f'src="assets/benchmark/charts/{assets["desktop"]}"' in content
+    assert f'srcset="assets/benchmark/charts/{assets["mobile"]}"' in content
     assert "zero-based linear scale" in content and "requests/s (RPS)" in content
+    alt = re.search(r'<img data-chart-image[^>]* alt="([^"]*)"', content).group(1)
+    assert f': {catalog["cases"][0]["rows"][0]["rps"]:,.1f}' in alt
     assert '<img src=x onerror="alert(1)">' not in content
     assert "&lt;img src=x" in content
     data = re.search(
diff --git a/docs/benchmark_view.py b/docs/benchmark_view.py
index bdff7f92..6f00024b 100644
--- a/docs/benchmark_view.py
+++ b/docs/benchmark_view.py
@@ -41,16 +41,9 @@ def render_explorer(document, catalog, asset_prefix="assets/benchmark/charts"):
         f'<button type="button" data-chart-payload="{size}" aria-pressed="{str(size == first["payload_bytes"]).lower()}">{payload_label(size)}</button>'
         for size in payloads
     )
-    assets = first["assets"]["light"]
+    assets = first["assets"]["dark"]
     image = safe_data_link(f'{asset_prefix}/{assets["desktop"]}')
     mobile = safe_data_link(f'{asset_prefix}/{assets["mobile"]}')
-    rows = "".join(
-        f'<tr><td>{escape(row["label"])}</td><td>{row["rps"]:,.1f}</td></tr>'
-        for row in first["rows"]
-    ) + "".join(
-        f"<tr><td>{escape(label)}</td><td>N/A</td></tr>"
-        for label in first["unsupported"]
-    )
     # This is inert JSON, not script. Escape HTML delimiters so metadata cannot end the tag.
     data = json.dumps(catalog, ensure_ascii=True, separators=(",", ":"))
     data = data.replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026")
@@ -62,9 +55,14 @@ def render_explorer(document, catalog, asset_prefix="assets/benchmark/charts"):
         if first["unsupported"]
         else "All shown clients support this case."
     )
+    values = "; ".join(
+        [f'{row["label"]}: {row["rps"]:,.1f}' for row in first["rows"]]
+        + [f"{label}: N/A" for label in first["unsupported"]]
+    )
+    alt = f"{first['title']}. Throughput in requests per second. {values}."
     return f"""<section class="wreq-bench" data-bench-explorer aria-label="Benchmark chart explorer">
 <p class="wreq-bench-provenance">Measured <a href="{REPOSITORY}/commit/{source['commit']}">{source['commit'][:12]}</a> · {date:%Y-%m-%d %H:%M UTC}{dirty}</p>
-<div class="wreq-bench-heading"><div><p class="wreq-bench-eyebrow">THROUGHPUT BY WORKLOAD</p><h3>Compare clients</h3></div><a href="assets/benchmark/latest.json">Raw JSON</a></div>
+<div class="wreq-bench-heading"><p class="wreq-bench-eyebrow">THROUGHPUT BY WORKLOAD</p><h3>Compare clients</h3></div>
 <p class="wreq-bench-intro">Pick a body size, then adjust the filters to compare clients. Full and Stream refer to the upload; we read every response to the end.</p>
 <div class="wreq-bench-body-controls" data-chart-controls hidden>
 <button type="button" data-chart-previous aria-label="Previous body size">←</button>
@@ -74,11 +72,10 @@ def render_explorer(document, catalog, asset_prefix="assets/benchmark/charts"):
 <div class="wreq-bench-filters" data-chart-controls hidden>{''.join(controls)}</div>
 <p class="wreq-bench-selection" data-chart-caption aria-live="polite">{escape(first['title'])}</p>
 <figure class="wreq-bench-figure">
-<picture><source media="(max-width: 600px)" data-chart-mobile srcset="{mobile}"><img data-chart-image src="{image}" alt="{escape(first['title'])}. Throughput in requests per second; values in the table below." width="900" decoding="async"></picture>
-<figcaption><span data-chart-unsupported>{escape(unsupported)}</span><a data-chart-download href="{image}" download>Download SVG</a></figcaption>
+<picture><source media="(max-width: 600px)" data-chart-mobile srcset="{mobile}"><img data-chart-image src="{image}" alt="{escape(alt)}" width="900" decoding="async"></picture>
+<figcaption data-chart-unsupported>{escape(unsupported)}</figcaption>
 </figure>
 <p class="wreq-bench-note">Unit: requests/s (RPS). Higher is better. Each chart uses its own zero-based linear scale; compare the numbers, not bar lengths across different charts.</p>
-<details class="wreq-bench-values"><summary>Values for this chart</summary><table><thead><tr><th>Client / runtime</th><th>Requests/s</th></tr></thead><tbody data-chart-values>{rows}</tbody></table></details>
-<noscript><p>Chart switching needs JavaScript. The default chart and complete tables below remain available.</p></noscript>
+<noscript><p>Chart switching needs JavaScript. The default chart and measurement details remain available.</p></noscript>
 <script type="application/json" data-chart-catalog>{data}</script>
 </section>"""
diff --git a/docs/build.py b/docs/build.py
index e765ca8a..0137ed95 100644
--- a/docs/build.py
+++ b/docs/build.py
@@ -68,7 +68,7 @@ def prepare(
         )
     document = decode_document(raw)
     try:
-        content = render_markdown(document, data_link="assets/benchmark/latest.json")
+        content = render_markdown(document, environment_only=True)
         catalog = write_charts(document, root / "docs/source/assets/benchmark/charts")
         charts = render_explorer(document, catalog)
         write_atomic(snapshot, document)
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 5f43ce45..82f1246c 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -9,6 +9,7 @@ repo_url: https://github.com/0x676e67/wreq-python
 docs_dir: source
 
 extra_css:
+  - stylesheets/theme.css
   - stylesheets/home.css
   - stylesheets/benchmarks.css
 
@@ -22,21 +23,13 @@ extra:
 
 theme:
   name: material
+  custom_dir: overrides
   font:
     code: Roboto Mono
   palette:
-    - scheme: slate
-      primary: black
-      accent: indigo
-      toggle:
-        icon: material/toggle-switch-off
-        name: Switch to light mode
-    - scheme: default
-      primary: indigo
-      accent: indigo
-      toggle:
-        icon: material/toggle-switch
-        name: Switch to dark mode
+    scheme: slate
+    primary: black
+    accent: indigo
   features:
     - search.highlight
     - search.share
diff --git a/docs/overrides/partials/javascripts/palette.html b/docs/overrides/partials/javascripts/palette.html
new file mode 100644
index 00000000..b7436c74
--- /dev/null
+++ b/docs/overrides/partials/javascripts/palette.html
@@ -0,0 +1 @@
+{# The site uses a fixed palette, so do not restore a previously saved theme. #}
diff --git a/docs/source/guide/advanced.md b/docs/source/guide/advanced.md
index f8961f93..560fa43b 100644
--- a/docs/source/guide/advanced.md
+++ b/docs/source/guide/advanced.md
@@ -1,4 +1,4 @@
-# :star2: Advanced Features
+# Advanced Features
 
 !!! info "On this page"
     - Header order
diff --git a/docs/source/guide/auth.md b/docs/source/guide/auth.md
index 77a8473f..c0d7957c 100644
--- a/docs/source/guide/auth.md
+++ b/docs/source/guide/auth.md
@@ -1,4 +1,4 @@
-# :lock: Authentication Guide
+# Authentication Guide
 
 !!! tip "Supported authentication methods"
     - Basic Auth
diff --git a/docs/source/guide/basic.md b/docs/source/guide/basic.md
index e6afe24e..f963823c 100644
--- a/docs/source/guide/basic.md
+++ b/docs/source/guide/basic.md
@@ -1,4 +1,4 @@
-# :rocket: Basic Usage
+# Basic Usage
 
 !!! info "On this page"
     - GET/POST requests
diff --git a/docs/source/guide/blocking.md b/docs/source/guide/blocking.md
index 67383a9f..e731f43d 100644
--- a/docs/source/guide/blocking.md
+++ b/docs/source/guide/blocking.md
@@ -1,4 +1,4 @@
-# :hourglass: Blocking/Sync API
+# Blocking/Sync API
 
 !!! info "On this page"
     - Blocking GET
diff --git a/docs/source/guide/emulation.md b/docs/source/guide/emulation.md
index 2a76e5ab..7dcad9fa 100644
--- a/docs/source/guide/emulation.md
+++ b/docs/source/guide/emulation.md
@@ -1,4 +1,4 @@
-# :busts_in_silhouette: Emulation
+# Emulation
 
 !!! info "Emulation topics"
     - Firefox/Chrome/Android
diff --git a/docs/source/guide/proxy.md b/docs/source/guide/proxy.md
index f5982f53..cc4f151e 100644
--- a/docs/source/guide/proxy.md
+++ b/docs/source/guide/proxy.md
@@ -1,4 +1,4 @@
-# :globe_with_meridians: Proxy Usage
+# Proxy Usage
 
 !!! info "On this page"
     - HTTP/HTTPS proxy
diff --git a/docs/source/guide/redirect-errors.md b/docs/source/guide/redirect-errors.md
index 43f27056..f6a0ec0e 100644
--- a/docs/source/guide/redirect-errors.md
+++ b/docs/source/guide/redirect-errors.md
@@ -1,4 +1,4 @@
-# :repeat: Redirects & Error Handling
+# Redirects & Error Handling
 
 !!! info "On this page"
     - Custom redirect policy
diff --git a/docs/source/guide/websocket.md b/docs/source/guide/websocket.md
index 35ac74f9..099add93 100644
--- a/docs/source/guide/websocket.md
+++ b/docs/source/guide/websocket.md
@@ -1,4 +1,4 @@
-# :satellite: WebSocket
+# WebSocket
 
 !!! info "On this page"
     - HTTP/1.1 WebSocket
diff --git a/docs/source/index.md b/docs/source/index.md
index 9ef8642a..4a9a2ddb 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -111,7 +111,7 @@ Choose a body size, protocol and concurrency level to see the results for your w
 
 ## Documentation and community
 
-[Install wreq](getting-started/installation.md) · [Read the guides](guide/basic.md) · [Browse the API](api/wreq.md) · [Join the community](https://discord.gg/rfbvyFkgq3)
+[Install wreq](getting-started/installation.md) · [Read the guides](guide/basic.md) · [Browse the API](api/wreq.md) · [Join the Discord](https://discord.gg/rfbvyFkgq3)
 
 Browser profiles configure network behavior. They do not execute JavaScript or guarantee access to a protected website.
 { .wreq-fine-print }
diff --git a/docs/source/javascripts/benchmarks.js b/docs/source/javascripts/benchmarks.js
index 6b39acb4..9f95b9fe 100644
--- a/docs/source/javascripts/benchmarks.js
+++ b/docs/source/javascripts/benchmarks.js
@@ -1,14 +1,7 @@
 (() => {
   const initialized = new WeakSet();
-  const observers = new Map();
 
   function initialize() {
-    observers.forEach((observer, section) => {
-      if (!section.isConnected) {
-        observer.disconnect();
-        observers.delete(section);
-      }
-    });
     document.querySelectorAll("[data-bench-explorer]").forEach((section) => {
       if (initialized.has(section)) return;
       initialized.add(section);
@@ -28,28 +21,16 @@
           && item.api === values.api && item.protocol === values.protocol
           && item.body_kind === values.body_kind && item.concurrency === Number(values.concurrency));
         if (!current) return;
-        const theme = document.body.getAttribute("data-md-color-scheme") === "slate" ? "dark" : "light";
-        const assets = current.assets[theme];
+        const assets = current.assets.dark;
         image.src = `${prefix}${assets.desktop}`;
-        image.alt = `${current.title}. Throughput in requests per second; values in the table below.`;
+        const description = [...current.rows.map((row) => `${row.label}: ${number.format(row.rps)}`),
+          ...current.unsupported.map((label) => `${label}: N/A`)].join("; ");
+        image.alt = `${current.title}. Throughput in requests per second. ${description}.`;
         mobile.srcset = `${prefix}${assets.mobile}`;
-        const download = section.querySelector("[data-chart-download]");
-        download.href = image.src;
         section.querySelector("[data-chart-caption]").textContent = current.title;
         section.querySelector("[data-chart-unsupported]").textContent = current.unsupported.length
           ? `N/A: ${current.unsupported.join(", ")}` : "All shown clients support this case.";
         payloadButtons.forEach((button) => button.setAttribute("aria-pressed", String(Number(button.dataset.chartPayload) === payload)));
-        const rows = [...current.rows.map((row) => [row.label, number.format(row.rps)]),
-          ...current.unsupported.map((label) => [label, "N/A"])];
-        section.querySelector("[data-chart-values]").replaceChildren(...rows.map((values) => {
-          const row = document.createElement("tr");
-          values.forEach((value) => {
-            const cell = document.createElement("td");
-            cell.textContent = value;
-            row.append(cell);
-          });
-          return row;
-        }));
       }
 
       function move(direction) {
@@ -76,15 +57,6 @@
       section.querySelector("[data-chart-previous]").addEventListener("click", () => move(-1));
       section.querySelector("[data-chart-next]").addEventListener("click", () => move(1));
       selects.forEach((select) => select.addEventListener("change", update));
-      const observer = new MutationObserver(() => {
-        if (!section.isConnected) {
-          observer.disconnect();
-          return;
-        }
-        update();
-      });
-      observer.observe(document.body, { attributes: true, attributeFilter: ["data-md-color-scheme"] });
-      observers.set(section, observer);
       section.querySelectorAll("[data-chart-controls]").forEach((controls) => { controls.hidden = false; });
       update();
     });
diff --git a/docs/source/stylesheets/benchmarks.css b/docs/source/stylesheets/benchmarks.css
index d63df602..201c17dc 100644
--- a/docs/source/stylesheets/benchmarks.css
+++ b/docs/source/stylesheets/benchmarks.css
@@ -1,5 +1,5 @@
 .wreq-bench {
-  --bench-accent: #157f70;
+  --bench-accent: var(--wreq-accent);
   --bench-border: var(--md-default-fg-color--lightest);
   border: 1px solid var(--bench-border);
   border-radius: .6rem;
@@ -7,8 +7,6 @@
   padding: 1.25rem;
 }
 
-[data-md-color-scheme="slate"] .wreq-bench { --bench-accent: #7ed6bc; }
-
 .wreq-bench-provenance,
 .wreq-bench .wreq-bench-note {
   color: var(--md-default-fg-color--light);
@@ -16,14 +14,6 @@
   line-height: 1.65;
 }
 
-.wreq-bench-heading {
-  align-items: center;
-  display: flex;
-  flex-wrap: wrap;
-  gap: .8rem;
-  justify-content: space-between;
-}
-
 .wreq-bench .wreq-bench-eyebrow {
   color: var(--bench-accent);
   font-size: .55rem;
@@ -33,7 +23,6 @@
 }
 
 .wreq-bench .wreq-bench-heading h3 { margin: .3rem 0; }
-.wreq-bench-heading > a { font-size: .65rem; }
 .wreq-bench-intro { font-size: .72rem; }
 
 .wreq-bench-body-controls {
@@ -51,26 +40,18 @@
 }
 
 .wreq-bench button {
-  border: 1px solid var(--bench-border);
+  background: var(--wreq-control-bg);
+  border: 1px solid var(--wreq-control-border);
   border-radius: .3rem;
-  color: var(--md-default-fg-color);
+  color: var(--wreq-control-fg);
   cursor: pointer;
   font-size: .65rem;
   min-height: 2.1rem;
   padding: .35rem .65rem;
 }
 
-.wreq-bench button:hover { border-color: var(--bench-accent); }
 .wreq-bench button[aria-pressed="true"] {
-  background: var(--bench-accent);
-  border-color: var(--bench-accent);
-  color: #fff;
-}
-
-[data-md-color-scheme="slate"] .wreq-bench button[aria-pressed="true"] { color: #162b25; }
-.wreq-bench button:focus-visible, .wreq-bench select:focus-visible {
-  outline: 2px solid var(--bench-accent);
-  outline-offset: 3px;
+  font-weight: 700;
 }
 
 .wreq-bench-filters {
@@ -88,10 +69,10 @@
 }
 
 .wreq-bench-filters select {
-  background: var(--md-default-bg-color);
-  border: 1px solid var(--bench-border);
+  background: var(--wreq-control-bg);
+  border: 1px solid var(--wreq-control-border);
   border-radius: .3rem;
-  color: var(--md-default-fg-color);
+  color: var(--wreq-control-fg);
   font: inherit;
   font-size: .7rem;
   min-height: 2.1rem;
@@ -105,19 +86,11 @@
 .wreq-bench-figure picture, .wreq-bench-figure img { display: block; width: 100%; }
 .wreq-bench-figure figcaption {
   color: var(--md-default-fg-color--light);
-  display: flex;
-  flex-wrap: wrap;
   font-size: .58rem;
   font-style: normal;
-  gap: .6rem;
-  justify-content: space-between;
   margin: .7rem 0;
 }
 
-.md-typeset .wreq-bench-values { margin: 1rem 0 0; }
-.wreq-bench-values table { width: 100%; }
-.wreq-bench-values td:last-child { font-variant-numeric: tabular-nums; text-align: right; }
-
 @media (max-width: 760px) {
   .wreq-bench { padding: .8rem; }
   .wreq-bench-filters { grid-template-columns: repeat(2, minmax(0, 1fr)); }
diff --git a/docs/source/stylesheets/home.css b/docs/source/stylesheets/home.css
index 956c029a..43073dbb 100644
--- a/docs/source/stylesheets/home.css
+++ b/docs/source/stylesheets/home.css
@@ -1,13 +1,8 @@
 .wreq-home {
-  --wreq-accent: #157f70;
   --wreq-border: var(--md-default-fg-color--lightest);
   --wreq-muted: var(--md-default-fg-color--light);
 }
 
-[data-md-color-scheme="slate"] .wreq-home {
-  --wreq-accent: #7ed6bc;
-}
-
 .wreq-home .wreq-eyebrow {
   color: var(--wreq-accent);
   font-size: .62rem;
@@ -196,8 +191,16 @@
   text-decoration: none;
 }
 
-.wreq-feature:hover {
-  border-color: var(--wreq-accent);
+@media (hover: hover) and (pointer: fine) {
+  .wreq-home .wreq-feature:hover {
+    border-color: var(--wreq-accent);
+    box-shadow: var(--wreq-control-shadow);
+  }
+
+  .wreq-home .wreq-sponsor:hover {
+    border-color: var(--wreq-control-border);
+    box-shadow: var(--wreq-control-shadow);
+  }
 }
 
 .wreq-feature-label {
diff --git a/docs/source/stylesheets/theme.css b/docs/source/stylesheets/theme.css
new file mode 100644
index 00000000..afe42b4f
--- /dev/null
+++ b/docs/source/stylesheets/theme.css
@@ -0,0 +1,91 @@
+[data-md-color-scheme] {
+  --wreq-accent: #7ed6bc;
+  --wreq-accent-hover: #a4e5d0;
+  --wreq-accent-active: #67c9ab;
+  --wreq-on-accent: #142c26;
+  --wreq-control-bg: #252c31;
+  --wreq-control-fg: #e2e8e5;
+  --wreq-control-border: #7c8d85;
+  --wreq-control-hover: #303c3b;
+  --wreq-control-active: #3b4a45;
+  --wreq-control-shadow: 0 2px 8px #0006;
+}
+
+/* Override Material's palette and pointer-focus colors before local states. */
+.md-typeset .md-button,
+.md-typeset .md-button:focus,
+.md-typeset .md-button:hover {
+  background: var(--wreq-control-bg);
+  border-color: var(--wreq-accent);
+  color: var(--wreq-accent);
+}
+
+.md-typeset .md-button--primary,
+.md-typeset .md-button--primary:focus,
+.md-typeset .md-button--primary:hover,
+.wreq-bench button[aria-pressed="true"] {
+  background: var(--wreq-accent);
+  border-color: var(--wreq-accent);
+  color: var(--wreq-on-accent);
+}
+
+.md-typeset .md-button,
+.wreq-bench button,
+.wreq-bench select {
+  transition: background-color 120ms ease, border-color 120ms ease,
+              color 120ms ease, box-shadow 120ms ease;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .md-typeset .md-button:not(:disabled):hover,
+  .wreq-bench button:not(:disabled):hover,
+  .wreq-bench select:not(:disabled):hover {
+    background: var(--wreq-control-hover);
+    border-color: var(--wreq-accent);
+    box-shadow: var(--wreq-control-shadow);
+    color: var(--wreq-accent);
+  }
+
+  .md-typeset .md-button--primary:not(:disabled):hover,
+  .wreq-bench button[aria-pressed="true"]:not(:disabled):hover {
+    background: var(--wreq-accent-hover);
+    border-color: var(--wreq-accent-hover);
+    color: var(--wreq-on-accent);
+  }
+}
+
+.md-typeset .md-button:not(:disabled):active,
+.wreq-bench button:not(:disabled):active,
+.wreq-bench select:not(:disabled):active {
+  background: var(--wreq-control-active);
+  border-color: var(--wreq-accent);
+  box-shadow: none;
+  color: var(--wreq-accent-active);
+}
+
+.md-typeset .md-button--primary:not(:disabled):active,
+.wreq-bench button[aria-pressed="true"]:not(:disabled):active {
+  background: var(--wreq-accent-active);
+  border-color: var(--wreq-accent-active);
+  color: var(--wreq-on-accent);
+}
+
+.md-typeset .md-button:focus-visible,
+.wreq-bench button:focus-visible,
+.wreq-bench select:focus-visible {
+  outline: 2px solid var(--wreq-accent);
+  outline-offset: 3px;
+}
+
+.wreq-bench button:disabled,
+.wreq-bench select:disabled {
+  cursor: not-allowed;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .md-typeset .md-button,
+  .wreq-bench button,
+  .wreq-bench select {
+    transition: none;
+  }
+}
diff --git a/docs/templates/benchmark.md b/docs/templates/benchmark.md
index deaa0333..0fa3fbb7 100644
--- a/docs/templates/benchmark.md
+++ b/docs/templates/benchmark.md
@@ -6,7 +6,7 @@ with Full or Stream uploads and every response streamed to EOF.
 
 The results compare the recorded `wreq` revision with pinned versions of `ry`,
 `pyreqwest`, `httpx`, `aiohttp`, `niquests`, `curl_cffi`, `requests`, and `pycurl`.
-Async and blocking clients have separate charts and tables.
+Async and blocking clients have separate charts.
 
 ## Latest measurements
 
@@ -18,17 +18,12 @@ the chart: it identifies the code tested, which may differ from the docs revisio
 !!! note "Reading settings affect throughput"
 
     Larger read chunks and buffering can make a big difference to large-body
-    HTTP/2 throughput. These charts use the configurations recorded below;
+    HTTP/2 throughput. These charts use the configurations saved in the raw JSON;
     they don't show every library's fastest possible configuration. Check the
     [reading settings](#runtime-and-client-differences) when comparing clients.
 
-<details markdown="1">
-<summary>Complete tables, environment and client configurations</summary>
-
 {{BENCHMARK_RESULTS}}
 
-</details>
-
 ## What is measured
 
 | Setting | Behavior |
@@ -42,20 +37,11 @@ the chart: it identifies the code tested, which may differ from the docs revisio
 | Validation | HTTP status, actual HTTP protocol, and echoed body length are checked |
 | Repetition | Case order is shuffled; warm-up batches are excluded from all reported rates |
 
-The default suite tests all seven payloads below with Full and Stream uploads
-at concurrency 10, 50, 100, and 150. Each batch has 300 requests, and each case
-runs for three rounds. Earlier snapshots may cover fewer cases. The tables and
-raw JSON show the cases actually measured.
-
-| Upload / echo payload | Stream upload chunk |
-| --- | --- |
-| 1 KiB | 1 KiB |
-| 10 KiB | 10 KiB |
-| 64 KiB | 16 KiB |
-| 128 KiB | 32 KiB |
-| 1 MiB | 64 KiB |
-| 2 MiB | 128 KiB |
-| 4 MiB | 256 KiB |
+The default suite tests seven body sizes from 1 KiB to 4 MiB, with Full and
+Stream uploads at concurrency 10, 50, 100, and 150. Each batch has 300 requests,
+and each case runs for three rounds. Earlier snapshots may cover fewer cases.
+The charts and raw JSON show the cases actually measured, including the upload
+chunk sizes recorded in the JSON.
 
 The echo server collects the upload before returning the same payload. The
 timer therefore measures the complete HTTPS exchange, including response
@@ -122,7 +108,7 @@ After reviewing a complete run, use `--input RUN.json --publish` to build the
 docs and select it as `latest.json`. This processes the saved data without
 running the measurements again.
 
-Docs builds validate the checked-in dataset and generate the charts, tables
-and a frozen raw JSON download from it. They don't fetch data from another
+Docs builds validate the checked-in dataset and generate the charts, metadata
+and a frozen raw JSON copy from it. They don't fetch data from another
 branch. Missing or invalid data stops the build, so an old generated page can't
 silently take its place.
diff --git a/pyproject.toml b/pyproject.toml
index e6818c05..be45408a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,6 +31,9 @@ keywords = ["http", "client", "websocket", "ja3", "ja4"]
 [tool.maturin]
 python-source = "python"
 
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
 [project.urls]
 Documentation = "https://python.wreq.org"
 Homepage = "https://github.com/0x676e67/wreq-python"