# @leumas/value-changer

The Global Value Changer — one layer that reads the text already on the page, matches words Leumas has programmed, and attaches a live component to them (a crypto price, a glossary definition, a...


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

| Import | What |
|---|---|
| `@leumas/value-changer` | `GlobalValueChanger` — the eager host. Mount once, via `AppLayout`. |
| `@leumas/value-changer/engine` | `start()` — the scanner. Dynamically imported; never import it statically. |
| `@leumas/value-changer/packs` | the term-pack catalog: metadata only, React-free. |
| `@leumas/value-changer/settings` | `ValueChangerCard` — the Studio surface. |

## 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.


---
Source: shared/packages/value-changer/README.md
Canonical: https://docs.leumas.tech/p/packages/value-changer