@leumas/value-changer

The Global Value Changer — one layer, wrapped around every Leumas frontend, that reads the text already on the page, matches words we have programmed, and attaches a live component to them.

Hover BTC and get a price. Hover Leviathan and get its definition and a link to the docs. Hover a Pokémon name and get its artwork, types and battle cry. A term is programmed in one file, and every surface in the ecosystem gains it at once.

What it absorbs

Nothing — this is new ground. A repo-wide search for TreeWalker, CSS.highlights and any term-highlighting runtime returned zero hits before this package existed. It does, however, reuse rather than re-derive: the eager/lazy boot split from @leumas/ui/oracle, the catalog shape from @leumas/inputs, the resolver ladder and per-user preference pattern from @leumas/entrance, and the hover timing and viewport clamping from @leumas/ui's tooltip layer.

The one thing to know

The root entry is boot-path code. GlobalValueChanger is mounted eagerly by every product, so src/index.js and src/GlobalValueChanger.jsx import nothing from engine/, packs/, settings/ or the stylesheet. Their whole job is to read two booleans and call onIdle(). Everything else arrives in one lazy chunk after first paint.

That is not a style preference; it is the feature's entire justification. pnpm smoke:value-changer asserts the contract and pnpm check:boot prices it.

Zero DOM mutation

Matches are painted with the CSS Custom Highlight API and hit-tested against a page-relative rect index. Nothing in the DOM is ever wrapped, added or changed — so React cannot fight the decoration, and the MutationObserver that repairs stale ranges can never trigger itself. Where CSS.highlights is unavailable the layer degrades to hover-without-decoration rather than shipping a second renderer.

Public API

Adding a term pack

Create src/packs/<id>/meta.js (React-free, ~15 lines) and src/packs/<id>/Card.jsx (default export, lazily loaded), then add one line to src/packs/index.js. pnpm check:value-changer fails on a folder that is not listed, and on an entry with no folder.