webapp: improve the feature vocabulary and exposed to the user what each feature is

[macabeus]

Closes the two complaints about the Function Explorer's Feature selector: it is 89 options long, and nothing tells a reader what any option means.

The selector was a symptom

The cause is upstream of the UI, and partly my own doing in #16:

distinct tags in the published dataset	89
KNOWN_FEATURES — the "closed" vocabulary from #16	36
…published tags outside it	54
…declared but carried by no row	1 (recursion)

Three separate holes. The closure test reads dataset/real/*.json and nothing else, so the synthetic tier speaks an undeclared 48-tag dialect — s64 beside int64, type-pun beside union, for/while beside loop, each pair silently halving every aggregate over it, which is the exact failure #16 fixed for fixedpoint/fixed-point and left live in the other tier. The six derived codegen tags (hw-div, magic-div, jump-table, …) are published on every row whose asm supports them and were never added to the vocabulary at all. And apps/web cannot import apps/benchmark — it is not a dependency — so every description written in #16 is unreachable from the UI that would render it. The tags were documented in a place the site can't see.

What changed

The vocabulary is data in @asmlift/bench-schema, read by the producer and the consumer alike: 69 ids, each with a label, a summary, an evidence kind and a user-facing group, plus prose and a worked C/asm example where it earns one. Two orthogonal axes on purpose — evidence is how we know a tag is true, group is what kind of thing it is, and only the second is what a reader wants to browse by. src/cases/features.ts keeps every detector but stops declaring the vocabulary: the three lists become filters over FEATURES by evidence, so two lists that must agree became one list with two views.

Authored data now carries judgement tags only. Source-level tags derive per row like the codegen ones already did — SynthSpec carries src, so the same detector works on both tiers. The machine decides what it can decide.

Dataset, all metadata — no outcome, score or gap moves: 10 hard renames (no alias layer); the eight compound divisor ids flattened to div/mod-{const,pow2,reg} with signedness carried by the existing signed/unsigned tags; 9 drops (expr, void, byte, offset, range, select, mutate as unfalsifiable or true of everything, c++ as a duplicate of FunctionResult.language, recursion as unused). The floor also caught six specs tagged cast whose conversion is implicit — their sign-extend/narrow/promotion tags already said it.

The UI: the <select> becomes a searchable multi-select grouped by group, AND-ed. Definitions open in the same right-side drawer the row detail uses — same chrome, same Escape, ?about=<id> beside ?fn=<row> — because "what does table mean?" is asked while reading the table, and answering it on a separate page would throw away the filters that prompted the question.

Five gates, each verified to fail

gate	catches
every published tag has a definition	a new tag nobody documented
every definition is carried by a row	a definition that rotted unused
definitions well-formed, seeAlso resolves	a half-filled entry
derived tags match their evidence, both directions	a tag with no evidence, or evidence with no tag
the same closure check in apps/web, over the committed snapshot	a regenerated results.json whose vocabulary drifted

The last one is the one that matters for the site: without it a snapshot could ship a tag the picker silently omits and a chip opens an empty drawer. I broke each gate deliberately and confirmed it goes red — a gate that has only ever passed is decoration.

Design notes worth reviewing

No AND/OR toggle. At 3.3 tags per row, three AND-ed selections empty the table fast. Instead each option's count is computed over the already-filtered rows and zero-count options go disabled but stay visible, so a selection that would empty the table is visible before it is clicked. That is a better answer than the toggle, not a smaller one.

Three shared primitives, generic by construction. MultiSelect, HoverCard and Pill live in src/shared/, which .dependency-cruiser.cjs forbids from importing src/pages/ — so none of them can reach for a vocabulary, a row count or a route. MultiSelect ships with a second consumer (the decline filter) in the same PR, because one consumer does not prove a component is generic; Pill replaced six hand-rolled copies of one class string. Their logic that can actually be wrong — option filtering, card placement — is extracted into pure modules and unit tested, since apps/web has no DOM-testing setup and adding one for these would be a worse trade.

Hard renames, no aliases, per review. The cost is that ?feature=s64-style permalinks break. Rather than hide that, the Explorer validates URL values against the now-closed vocabulary and reports the unknown one instead of rendering a silently empty table.

Accepted, not fixed

• Chips in the row-detail drawer stack a second drawer over the first. That is deliberate and handled (shared/utils/overlay.ts: ref-counted scroll lock, Escape closes only the topmost) rather than avoided.
• The hover card's lifecycle has no automated test — only its placement maths does. Two of the three bugs I hit during this work were lifecycle bugs found by driving a real browser, so this is a genuine gap, not a shrug.

Verification

bench run + merge → 743 rows, asmlift 354 / m2c 342 — unchanged, regression reports 0 lost / 0 gained / 0 flips, stale-check fresh, provenance clean and an ancestor of this branch. 893 tests across 87 files, typecheck, lint (0 errors), format:check, depcruise, and a production vite build. The picker, the drawer, stacked drawers, Escape ordering, and both "read more" paths were each exercised in a real browser.

🤖 Generated with Claude Code