The coverage dashboard #

Explains what README.md's coverage table means, how docs/feature-map.json decides it, and how to keep both in sync after a change.

The five statuses #

Every browser-compat-data leaf key under css, html, api, javascript, svg, webassembly, http and mathml gets exactly one of:

generated — implemented by an admitted model-written candidate under crates/layout/src/generated/. Each generated function's .provenance.json names the spec section it was generated against; docs/feature-map.json's rule for the key points at the function's source file.
hand-written — implemented by substrate code the project wrote by hand: box tree construction, the DOM/cascade boundary onto Stylo, and the reflection/tree-mutation work in crates/dom.
linked — implemented by a real dependency the project integrates rather than writes, using docs/platform-areas.md's own word for it: Stylo for CSS cascade and computed values today, and a JavaScript engine once one is chosen and actually wired in. It covers only the feature surface the dependency itself computes. The project's glue and adapter code around the dependency — the DOM/cascade boundary in crates/dom/src/style.rs, the reads in crates/dom/src/computed.rs — is hand-written, and a key whose behavior beyond the cascaded value (layout, box generation) is done by this project's own code keeps that code's status: display and position are hand-written, width and the top/right/bottom/left offsets are generated, even though Stylo computes their values. The linked rules today are the remaining properties of the style subset compared against getComputedStyle (docs/dump-format.md), which docs/platform-areas.md → "Style, layout and rendering" reports as fully matched. Properties Stylo cascades but that no comparison checks stay unreached until one does, and javascript.* stays unreached while no JavaScript engine exists.
oracle only — not implemented, but a three-engine-comparable probe or conformance suite exists for it (docs/oracle-coverage.md, docs/conformance-oracles.md).
unreached — none of the above: no rule in docs/feature-map.json matches the key. This is the default, and today it accounts for most of the surface — see "Expect small numbers" below.

The rule map #

docs/feature-map.json is the one hand-maintained input: an ordered array of rules, for example:

{ "pattern": "css.properties.width", "status": "generated", "evidence": "crates/layout/src/generated/width.rs" }

pattern is a browser-compat-data key or a prefix of one, dot-separated (css.properties.width matches that key and everything nested under it, such as css.properties.width.calc). A segment can be * (matches any one segment) or end in * (matches a segment starting with that text — api.GPU* matches api.GPUAdapter, api.GPUDevice, and so on).
Rules are checked in file order; the first match wins. A key no rule matches is unreached.
evidence must resolve to something real: a repo-relative file path, path/to/doc.md#Heading Text naming an actual heading in that file, or corpus/<feature>-triage.json#<key> naming a feature triage record in which every page tagged for that key passes (docs/web-features-map.md → "The status rule"). oracle/suites/dashboard.mjs checks every rule's evidence on every run and refuses to compute anything if one doesn't resolve.

Updating the table #

flowchart LR
  map["docs/feature-map.json<br/>(hand-edited rules)"] --> dash["dashboard.mjs --render"]
  bcd["browser-compat-data"] --> dash
  dash --> json["docs/dashboard.json"]
  dash --> hist["docs/dashboard-history.json"]
  hist --> svg["docs/dashboard-history.svg"]
  dash --> svg
  dash --> readme["README.md table<br/>and graph"]
  json --> test["readme_dashboard.rs<br/>and --check"]
  hist --> test
  svg --> test
  readme --> test

Edit docs/feature-map.json — add, remove or repoint a rule, and commit it with the work it describes. This is the only step a spec does by hand.
Landing does the rest. After every merge, bench/after-land.sh runs bench/dashboard-update.sh in the primary checkout. It checks whether docs/dashboard.json, docs/dashboard-history.json, docs/dashboard-history.svg and the tables in README.md still match a fresh computation (node oracle/suites/dashboard.mjs --check; a different date alone does not count), and if not runs node oracle/suites/dashboard.mjs --render and commits the files that changed as dashboard: regenerate at <sha> on the base branch. Numbers that did not move add no commit. The computation is offline and takes seconds. It refuses, and writes nothing, when any of the four files has uncommitted changes; on any failure it puts them back and the landing's output line names it as not done (web-features map or dashboard not updated), and the next landing tries again because it recomputes from scratch.
To refresh by hand (a track that wants the numbers before landing, or after a failed landing step), run npm run dashboard from oracle/ (equivalent to node suites/dashboard.mjs --render from that directory, or node oracle/suites/dashboard.mjs --render from the repo root) and commit the four generated files together, even when the history did not gain an entry, because the SVG and the README block are rewritten from it on every --render.

crates/harness/tests/readme_dashboard.rs fails cargo test --workspace if the README table, the JSON, the history and the graph disagree with each other, and node oracle/suites/dashboard.mjs --check fails if any of them is stale against a fresh computation from browser-compat-data. bench/dashboard-update-test.sh covers the landing step: numbers moved gives one commit, numbers unchanged gives none, and an uncommitted change in one of the four files is refused.

The history graph #

README.md carries a small graph above the table, between  and . It is a committed file, docs/dashboard-history.svg, embedded with <img>: GitHub's README sanitizer strips inline <svg>, <script>, <style> and style=, so a committed image is the only form that renders at a size the page sets while staying reviewable in a diff.

One bar per recorded run, oldest on the left, the newest 60 at most. The x-axis is entry order, not time, so a long gap between runs looks the same as a short one. Each bar stacks generated, hand-written, linked and oracle only from the bottom up, in the table's column order. unreached is the remainder and is not drawn: at around 93% it would flatten the other four into a line at the bottom. It is still named in every bar's tooltip, so nothing is hidden, only unplotted.

The y-axis runs from 0 to the smallest multiple of 5 that covers the tallest stack, never less than 5, and the top edge carries its label (10% today). The label is there to be read: the axis does not go to 100, so the bars look far taller than the shares they stand for.

Behind the bars, a grey line with a faint fill under it plots the number of leaf keys reached (every status but unreached) for each run, one point at each bar's centre. It has its own scale, from 0 to the current leaf-key total, labelled on the right edge (17.3k today) so it is not read against the % on the left; the legend names it. Against the full total the line sits low and nearly flat, which is the point: it shows how much of the platform is covered in absolute terms, where the bars exaggerate. With a single run the line is a short flat segment across that bar. Every bar's tooltip also gives the reached count and the total.

docs/dashboard-history.json is the data. It is a JSON array, oldest first, one compact object per line so a new entry is a one-line diff, and it records only overall — there is no per-area history. Besides the five percentages, an entry records reached and total, the absolute counts behind the line, so a later change in the total does not move old points. A run appends an entry only when one of the five overall percentages, or either count, differs from the last entry's; re-running on unchanged inputs leaves the file byte-identical, on the same day or a later one, even though docs/dashboard.json's date moves. Entries are never rewritten, merged or removed, and several may share a date. The first entry predates the linked status, which did not exist when it was recorded, so its linked is 0. Entries recorded before the counts existed have no reached or total; the graph derives reached as (100 − unreached) × current total / 100, rounded, and the tooltip marks it "about", and the last entry's percentages alone decide whether a run appends while it is one of those.

Expect small numbers #

The generated, hand-written and linked shares are expected to be small single-digit percentages for a long time. linked could be made large overnight by mapping every css.properties key to Stylo, but Stylo's cascade only counts once a comparison shows the value matching, so it grows with the compared style subset, not with Stylo's own property list. The dashboard's job is to be accurate about what's implemented, not to look impressive — an inflated number would mean a bug in docs/feature-map.json, not a feature. oracle only and unreached will dominate every area's row for the foreseeable future; that reflects the plan, not a shortfall the table should hide.

Per-feature progress #

The same rule map also drives docs/web-features-map.json, a per-feature view over the web-features package: each feature's status (complete, partial, none, unknown), its keys, and the evidence behind each, regenerated after every merge. The rule matching is shared code (oracle/suites/feature-map-rules.mjs), so a key's class here and its via there always agree. A dashboard reads that file's totals for per-feature progress; format and status rule: docs/web-features-map.md.

When a candidate is admitted #

Every spec that lands a generated function already says what to commit (the source file, its .provenance.json, the pub mod line, the entry points). Add one more step to that list, to copy into the spec's own "When a candidate is admitted" section: add the function's compat keys to docs/feature-map.json as generated rules pointing at the new file, and commit that alongside the function. The dashboard's numbers, the history and the README table follow from landing ("Updating the table"); the spec does not run npm run dashboard or commit its output.