feat: publish versioned data exports

The metadata behind the verifier, the pack builder and the site is now
served as static files: a versioned JSON API, CSV extracts, a SQLite
snapshot, and a catalog carrying a SHA-256 for each artifact.

The gaps dataset covers both layers behind a layer column. It previously
held one row, the single platform-verification anomaly, while the page
offering it as a download led with the emulator-level count.

source_ref renders as a permalink pinned to the revision the profile
cites. When a profile declares two repositories, a path that belongs to
neither by name is left as plain code: a citation without a link still
names the file and the lines, a link to the wrong repository does not.

The table filter, focus outlines and tap targets are progressive
enhancement; the pages work without them.

docs_assets/extra.css

@@ -5,7 +5,8 @@
   --rb-primary: #4a4e8a;
   --rb-primary-light: #6366a0;
   --rb-primary-dark: #363870;
-  --rb-accent: #e8594f;
+  --rb-accent: #b42318;
+  --rb-link: #273c8f;
   --rb-success: #2e7d32;
   --rb-warning: #f57c00;
   --rb-danger: #c62828;
@@ -20,6 +21,8 @@
   --rb-surface: #1e1e2e;
   --rb-border: #313244;
   --rb-text-secondary: #a6adc8;
+  --rb-accent: #ff9a8f;
+  --rb-link: #aebcff;
 }
 
 /* ── Material theme overrides ── */
@@ -509,7 +512,8 @@
 /* Pack button in tables: smaller */
 .md-typeset table .md-button {
   font-size: 0.75rem;
-  padding: 0.3em 0.8em;
+  min-height: 44px;
+  padding: 0.55em 0.8em;
 }
 
 /* ── Hide permalink anchors in hero ── */
@@ -576,3 +580,107 @@
     font-size: 1.3rem;
   }
 }
+
+/* ── Accessibility and dense-data navigation ── */
+.md-typeset a:not(.md-button):not(.headerlink):not(.rb-badge) {
+  color: var(--rb-link);
+  text-decoration: underline;
+  text-decoration-thickness: 0.08em;
+  text-underline-offset: 0.14em;
+}
+
+.md-typeset a:not(.md-button):not(.headerlink):hover {
+  text-decoration-thickness: 0.14em;
+}
+
+:where(a, button, input, select, textarea, [tabindex]):focus-visible {
+  outline: 3px solid var(--rb-accent);
+  outline-offset: 3px;
+}
+
+.md-typeset .md-button,
+.md-typeset button,
+.md-typeset input,
+.md-typeset select {
+  min-height: 44px;
+}
+
+.rb-visually-hidden {
+  position: absolute !important;
+  width: 1px !important;
+  height: 1px !important;
+  padding: 0 !important;
+  margin: -1px !important;
+  overflow: hidden !important;
+  clip: rect(0, 0, 0, 0) !important;
+  white-space: nowrap !important;
+  border: 0 !important;
+}
+
+.rb-table-filter {
+  display: grid;
+  grid-template-columns: minmax(14rem, 28rem) auto;
+  gap: 0.35rem 0.8rem;
+  align-items: end;
+  margin: 1rem 0 0.45rem;
+}
+
+.rb-table-filter label {
+  grid-column: 1 / -1;
+  color: var(--rb-text-secondary);
+  font-size: 0.78rem;
+  font-weight: 700;
+}
+
+.rb-table-filter input {
+  width: 100%;
+  border: 2px solid var(--rb-border);
+  border-radius: 6px;
+  background: var(--md-default-bg-color);
+  color: var(--md-default-fg-color);
+  padding: 0.55rem 0.75rem;
+  font: inherit;
+}
+
+.rb-table-filter-count {
+  align-self: center;
+  color: var(--rb-text-secondary);
+  font-size: 0.8rem;
+  white-space: nowrap;
+}
+
+.md-typeset__scrollwrap[role="region"]:focus-visible {
+  border-radius: 8px;
+  outline: 3px solid var(--rb-accent);
+  outline-offset: 2px;
+}
+
+/* Material's compact footer defaults sit just below WCAG AA on the dark bar. */
+.md-footer-meta .md-copyright {
+  color: #b5b5b5;
+}
+
+.md-footer-meta.md-typeset .md-copyright a {
+  color: #b8c6ff !important;
+}
+
+@media (max-width: 600px) {
+  .rb-table-filter {
+    grid-template-columns: 1fr;
+  }
+
+  .rb-table-filter label {
+    grid-column: auto;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    scroll-behavior: auto !important;
+    transition-duration: 0.01ms !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+  }
+}

docs_assets/site.js

@@ -0,0 +1,110 @@
+/* Progressive enhancement for generated RetroBIOS reference tables. */
+(() => {
+  "use strict";
+
+  const textFromHeading = (element) => {
+    let cursor = element;
+    while (cursor) {
+      cursor = cursor.previousElementSibling;
+      if (!cursor) break;
+      if (/^H[1-6]$/.test(cursor.tagName)) {
+        return cursor.textContent.trim();
+      }
+    }
+    return document.querySelector("h1")?.textContent.trim() || "Data table";
+  };
+
+  const enhanceTables = () => {
+    document.querySelectorAll(".md-typeset table").forEach((table, index) => {
+      if (table.dataset.rbEnhanced === "true") return;
+      table.dataset.rbEnhanced = "true";
+
+      table.querySelectorAll("thead th").forEach((cell) => {
+        if (!cell.hasAttribute("scope")) cell.setAttribute("scope", "col");
+      });
+      table.querySelectorAll("tbody tr").forEach((row) => {
+        const first = row.querySelector(":scope > th");
+        if (first && !first.hasAttribute("scope")) first.setAttribute("scope", "row");
+      });
+
+      const container = table.parentElement;
+      const heading = textFromHeading(container);
+      if (!table.querySelector("caption")) {
+        const caption = document.createElement("caption");
+        caption.className = "rb-visually-hidden";
+        caption.textContent = heading;
+        table.prepend(caption);
+      }
+      if (container && container.scrollWidth > container.clientWidth) {
+        container.tabIndex = 0;
+        container.setAttribute("role", "region");
+        container.setAttribute("aria-label", `${heading}, scrollable table`);
+      }
+
+      const rows = Array.from(table.querySelectorAll("tbody tr"));
+      if (rows.length < 20 || !container || container.dataset.rbFilter === "true") {
+        return;
+      }
+      container.dataset.rbFilter = "true";
+
+      const controls = document.createElement("div");
+      controls.className = "rb-table-filter";
+      const id = `rb-table-filter-${index}-${Math.random().toString(36).slice(2, 8)}`;
+      const label = document.createElement("label");
+      label.htmlFor = id;
+      label.textContent = `Filter ${heading}`;
+      const input = document.createElement("input");
+      input.id = id;
+      input.type = "search";
+      input.autocomplete = "off";
+      input.placeholder = "Name, platform, system, hash...";
+      const count = document.createElement("span");
+      count.className = "rb-table-filter-count";
+      count.setAttribute("aria-live", "polite");
+      count.textContent = `${rows.length} rows`;
+      controls.append(label, input, count);
+      container.before(controls);
+
+      const searchable = rows.map((row) => ({
+        row,
+        text: row.textContent.normalize("NFKD").toLocaleLowerCase(),
+      }));
+      input.addEventListener("input", () => {
+        const query = input.value.trim().normalize("NFKD").toLocaleLowerCase();
+        let visible = 0;
+        searchable.forEach((entry) => {
+          const matches = !query || entry.text.includes(query);
+          entry.row.hidden = !matches;
+          if (matches) visible += 1;
+        });
+        count.textContent = `${visible} of ${rows.length} rows`;
+      });
+    });
+  };
+
+  const nameMaterialWidgets = () => {
+    document.querySelectorAll('[role="dialog"]').forEach((dialog) => {
+      if (dialog.hasAttribute("aria-label") || dialog.hasAttribute("aria-labelledby")) return;
+      const heading = dialog.querySelector("h1, h2, h3");
+      dialog.setAttribute("aria-label", heading?.textContent.trim() || "Site search");
+    });
+    document.querySelectorAll('[role="progressbar"]').forEach((progress) => {
+      if (!progress.hasAttribute("aria-label") && !progress.hasAttribute("aria-labelledby")) {
+        progress.setAttribute("aria-label", "Loading page");
+      }
+    });
+  };
+
+  const enhance = () => {
+    enhanceTables();
+    nameMaterialWidgets();
+  };
+
+  if (window.document$?.subscribe) {
+    window.document$.subscribe(enhance);
+  } else if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", enhance, { once: true });
+  } else {
+    enhance();
+  }
+})();

mkdocs.yml

@@ -8,6 +8,10 @@ repo_name: Abdess/retrobios
 # Almost every page is generated from platforms/, emulators/ and database.json,
 # so a per-page edit link would point at a file that does not exist.
 edit_uri: ''
+# Local implementation plans are preserved in docs/ for development sessions,
+# but are not part of the public reference site.
+exclude_docs: |
+  superpowers/**
 copyright: MIT for the tooling. BIOS and firmware files are third-party system
   software, preserved for personal backup, archival and interoperability.
 theme:
@@ -53,6 +57,8 @@ theme:
   - toc.follow
 extra_css:
 - stylesheets/extra.css
+extra_javascript:
+- javascripts/site.js
 extra:
   social:
   - icon: fontawesome/brands/github
@@ -64,6 +70,7 @@ markdown_extensions:
 - attr_list
 - def_list
 - footnotes
+- meta
 - md_in_html
 - tables
 - toc:
@@ -111,6 +118,7 @@ nav:
   - 3DO Company: systems/3do-company.md
   - APF: systems/apf.md
   - Acorn: systems/acorn.md
+  - Adobe: systems/adobe.md
   - Amstrad: systems/amstrad.md
   - Apple: systems/apple.md
   - Arcade: systems/arcade.md
@@ -510,7 +518,7 @@ nav:
   - Launchers (2):
     - Dolphin Launcher: emulators/dolphin_launcher.md
     - Parallel Launcher: emulators/parallel-launcher.md
-  - Other (37):
+  - Other (36):
     - ares: emulators/ares.md
     - Basilisk II: emulators/basiliskii.md
     - Beetle GBA (Mednafen): emulators/beetle_gba.md
@@ -541,7 +549,6 @@ nav:
     - SUPER ZSNES: emulators/superzsnes.md
     - ti99sim: emulators/ti99sim.md
     - tsugaru: emulators/tsugaru.md
-    - VBA-M: emulators/vba_m.md
     - veesem: emulators/veesem.md
     - VICE: emulators/vice.md
     - Vita3K: emulators/vita3k.md
@@ -551,6 +558,7 @@ nav:
 - Cross-reference: cross-reference.md
 - Gap Analysis: gaps.md
 - Dump provenance: provenance.md
+- Data & API: data.md
 - Wiki:
   - Overview: wiki/index.md
   - Getting started: wiki/getting-started.md

scripts/generate_readme.py

@@ -476,6 +476,7 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
             "- **Per-system pages** showing which emulators and platforms cover each console",
             "- **Gap analysis** identifying missing files and undeclared core requirements",
             f"- **Cross-reference** mapping files across {len(coverages)} platforms and {emulator_count} emulators",
+            "- **Versioned data access** through JSON, CSV and SQLite exports with published SHA-256 checksums",
             "",
             "## How it works",
             "",

tests/test_site_exports.py

@@ -0,0 +1,207 @@
+"""Regression tests for the public website data and citation contracts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+
+from generate_site import (  # noqa: E402
+    _admonition_body,
+    _browser_title,
+    _source_ref_markdown,
+    decorate_markdown_pages,
+    generate_data_exports,
+)
+
+
+class SiteReferenceContracts(unittest.TestCase):
+    def setUp(self) -> None:
+        scratch = ROOT / "tmp" / "tests"
+        scratch.mkdir(parents=True, exist_ok=True)
+        self.temp = tempfile.TemporaryDirectory(dir=scratch)
+        self.docs = Path(self.temp.name) / "docs"
+        self.docs.mkdir()
+
+    def tearDown(self) -> None:
+        self.temp.cleanup()
+
+    @staticmethod
+    def _fixtures() -> tuple[dict, dict, dict, dict]:
+        payload = b"firmware"
+        sha1 = hashlib.sha1(payload).hexdigest()
+        md5 = hashlib.md5(payload).hexdigest()
+        sha256 = hashlib.sha256(payload).hexdigest()
+        db = {
+            "schema_version": 1,
+            "generated_at": "2026-08-09T00:00:00Z",
+            "total_files": 1,
+            "total_size": len(payload),
+            "files": {
+                sha1: {
+                    "path": "bios/Test/fw.bin",
+                    "name": "fw.bin",
+                    "size": len(payload),
+                    "sha1": sha1,
+                    "md5": md5,
+                    "sha256": sha256,
+                    "crc32": "0f00ba11",
+                    "adler32": "0f00ba11",
+                }
+            },
+            "indexes": {
+                "by_md5": {md5: sha1},
+                "by_name": {"fw.bin": [sha1]},
+                "by_crc32": {"0f00ba11": sha1},
+                "by_sha256": {sha256: sha1},
+                "by_path_suffix": {"fw.bin": [sha1]},
+            },
+        }
+        coverages = {
+            "test": {
+                "platform": "Test Platform",
+                "config": {
+                    "platform": "Test Platform",
+                    "cores": ["testemu"],
+                    "systems": {
+                        "test-system": {
+                            "files": [
+                                {
+                                    "name": "fw.bin",
+                                    "destination": "fw.bin",
+                                    "required": True,
+                                    "sha1": sha1,
+                                    "size": len(payload),
+                                }
+                            ]
+                        }
+                    },
+                },
+                "total": 1,
+                "present": 1,
+                "verified": 1,
+                "untested": 0,
+                "missing": 0,
+                "core_present": 1,
+                "core_missing": 0,
+                "core_unsourceable": 0,
+                "details": [],
+            }
+        }
+        profiles = {
+            "testemu": {
+                "emulator": "Test Emulator",
+                "type": "libretro",
+                "source": "https://github.com/example/emulator",
+                "source_commit": "a" * 40,
+                "cores": ["testemu"],
+                "systems": ["test-system"],
+                "files": [
+                    {
+                        "name": "fw.bin",
+                        "system": "test-system",
+                        "required": True,
+                        "source_ref": "src/firmware.cpp:10-12",
+                    }
+                ],
+            }
+        }
+        stats = {
+            "schema_version": 1,
+            "generated_at": "2026-08-09T00:00:00Z",
+            "files": 1,
+            "size_bytes": len(payload),
+            "platforms": 1,
+            "emulators": 1,
+            "systems": 1,
+            "catalog_matched": 0,
+            "source": "https://github.com/Abdess/retrobios",
+            "downloads": "https://github.com/Abdess/retrobios/releases/tag/v2026.08.06",
+            "composition": {
+                "systems": {"files": 1, "size_bytes": len(payload)},
+                "arcade": {"files": 0, "size_bytes": 0},
+                "game_data": {"files": 0, "size_bytes": 0},
+            },
+        }
+        return db, coverages, profiles, stats
+
+    def test_source_references_are_revision_pinned_links(self):
+        _, _, profiles, _ = self._fixtures()
+        rendered = _source_ref_markdown(
+            profiles["testemu"], "src/firmware.cpp:10-12"
+        )
+        self.assertIn("/blob/" + "a" * 40 + "/src/firmware.cpp#L10-L12", rendered)
+
+    def test_ambiguous_two_repository_path_is_never_linked(self):
+        """A path that could live in either declared repository stays plain.
+
+        The libretro port and the original emulator are two different trees.
+        Linking an unattributable path to whichever came first publishes a
+        citation that resolves to nothing.
+        """
+        profile = {
+            "source": "https://github.com/libretro/example-libretro",
+            "source_commit": "a" * 40,
+            "upstream": "https://gitlab.com/vendor/example",
+            "upstream_commit": "b" * 40,
+        }
+        rendered = _source_ref_markdown(profile, "jg.c:213-214")
+        self.assertEqual(rendered, "`jg.c:213-214`")
+        self.assertNotIn("http", rendered)
+
+        # A repository-name prefix removes the ambiguity, so it links again.
+        prefixed = _source_ref_markdown(profile, "example/jg.c:213-214")
+        self.assertIn("gitlab.com/vendor/example/-/blob/" + "b" * 40 + "/jg.c", prefixed)
+
+    def test_preprocessor_tokens_cannot_become_page_headings(self):
+        rendered = _admonition_body("First paragraph.\n\n#if FEATURE\nEnabled")
+        self.assertIn("\\#if FEATURE", rendered)
+        self.assertNotIn("\n    #if FEATURE", rendered)
+
+    def test_browser_titles_distinguish_emulators_from_system_pages(self):
+        self.assertEqual(
+            _browser_title(Path("emulators/qemu.md"), "QEMU"),
+            "QEMU emulator firmware",
+        )
+        self.assertEqual(
+            _browser_title(Path("systems/qemu.md"), "QEMU"),
+            "QEMU systems",
+        )
+
+    def test_exports_have_catalog_hashes_and_queryable_sqlite(self):
+        db, coverages, profiles, stats = self._fixtures()
+        exports = generate_data_exports(
+            self.docs, db, coverages, profiles, stats
+        )
+        catalog = json.loads((self.docs / "api/v1/catalog.json").read_text())
+        self.assertEqual(catalog["count"], len(exports))
+        for item in catalog["items"]:
+            path = self.docs / item["url"]
+            self.assertTrue(path.is_file())
+            self.assertEqual(hashlib.sha256(path.read_bytes()).hexdigest(), item["sha256"])
+
+        with sqlite3.connect(self.docs / "downloads/retrobios.sqlite") as connection:
+            self.assertEqual(connection.execute("SELECT count(*) FROM files").fetchone()[0], 1)
+            self.assertEqual(connection.execute("SELECT count(*) FROM platforms").fetchone()[0], 1)
+            self.assertEqual(connection.execute("SELECT count(*) FROM emulators").fetchone()[0], 1)
+
+    def test_page_metadata_is_specific_and_idempotent(self):
+        page = self.docs / "gaps.md"
+        page.write_text("# Gap Analysis - RetroBIOS\n\nCurrent unresolved entries.\n")
+        decorate_markdown_pages(self.docs)
+        decorate_markdown_pages(self.docs)
+        content = page.read_text()
+        self.assertEqual(content.count('type="application/ld+json"'), 1)
+        self.assertIn("Current RetroBIOS verification gaps", content)
+        self.assertIn('"@type":"TechArticle"', content)
+
+
+if __name__ == "__main__":
+    unittest.main()