{
  "schema": "leumas.docs.page/1",
  "id": "pkg:@leumas/value-changer",
  "slug": "packages/value-changer",
  "kind": "capabilities",
  "bucket": "package",
  "title": "@leumas/value-changer",
  "name": "@leumas/value-changer",
  "eyebrow": null,
  "chip": null,
  "summary": "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...",
  "keywords": [
    "value-changer",
    "mutation",
    "hit-tested",
    "page-relative",
    "applayout",
    "value changer api",
    "leumas value changer",
    "how to use value changer"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# @leumas/value-changer\n\nThe **Global Value Changer** — one layer, wrapped around every Leumas frontend, that reads the text\nalready on the page, matches words we have programmed, and attaches a live component to them.\n\nHover `BTC` and get a price. Hover `Leviathan` and get its definition and a link to the docs. Hover a\nPokémon name and get its artwork, types and battle cry. A term is programmed in **one file**, and\nevery surface in the ecosystem gains it at once.\n\n## What it absorbs\n\nNothing — this is new ground. A repo-wide search for `TreeWalker`, `CSS.highlights` and any\nterm-highlighting runtime returned zero hits before this package existed. It does, however, reuse\nrather than re-derive: the eager/lazy boot split from `@leumas/ui/oracle`, the catalog shape from\n`@leumas/inputs`, the resolver ladder and per-user preference pattern from `@leumas/entrance`, and\nthe hover timing and viewport clamping from `@leumas/ui`'s tooltip layer.\n\n## The one thing to know\n\n**The root entry is boot-path code.** `GlobalValueChanger` is mounted eagerly by every product, so\n`src/index.js` and `src/GlobalValueChanger.jsx` import nothing from `engine/`, `packs/`, `settings/`\nor the stylesheet. Their whole job is to read two booleans and call `onIdle()`. Everything else\narrives in one lazy chunk after first paint.\n\nThat is not a style preference; it is the feature's entire justification. `pnpm smoke:value-changer`\nasserts the contract and `pnpm check:boot` prices it.\n\n## Zero DOM mutation\n\nMatches are painted with the **CSS Custom Highlight API** and hit-tested against a page-relative rect\nindex. Nothing in the DOM is ever wrapped, added or changed — so React cannot fight the decoration,\nand the `MutationObserver` that repairs stale ranges can never trigger itself. Where\n`CSS.highlights` is unavailable the layer degrades to hover-without-decoration rather than shipping a\nsecond renderer.\n\n## Public API\n\n| Import | What |\n|---|---|\n| `@leumas/value-changer` | `GlobalValueChanger` — the eager host. Mount once, via `AppLayout`. |\n| `@leumas/value-changer/engine` | `start()` — the scanner. Dynamically imported; never import it statically. |\n| `@leumas/value-changer/packs` | the term-pack catalog: metadata only, React-free. |\n| `@leumas/value-changer/settings` | `ValueChangerCard` — the Studio surface. |\n\n## Adding a term pack\n\nCreate `src/packs/<id>/meta.js` (React-free, ~15 lines) and `src/packs/<id>/Card.jsx` (default\nexport, lazily loaded), then add **one line** to `src/packs/index.js`. `pnpm check:value-changer`\nfails on a folder that is not listed, and on an entry with no folder.\n",
  "source": {
    "path": "shared/packages/value-changer/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 2814,
    "hash": "d615c14433818aad206f232d9da66caafca575ee"
  },
  "urls": {
    "html": "/p/packages/value-changer",
    "json": "/docs/packages/value-changer.json",
    "md": "/docs/packages/value-changer.md"
  },
  "links": {
    "composes": [
      "pkg:@leumas/theme",
      "pkg:@leumas/ui"
    ],
    "usedBy": [
      "pkg:@leumas/admin",
      "pkg:@leumas/features",
      "pkg:@leumas/studio"
    ],
    "product": [
      "pkg:@leumas/admin",
      "pkg:@leumas/studio",
      "pkg:@leumas/web"
    ],
    "howTo": [],
    "skills": []
  },
  "exports": {
    "total": 15,
    "component": 7,
    "hook": 0,
    "helper": 8,
    "names": [
      {
        "n": "BindingsEditor",
        "k": "component"
      },
      {
        "n": "CustomTermsEditor",
        "k": "component"
      },
      {
        "n": "ENTRIES",
        "k": "component"
      },
      {
        "n": "GlobalValueChanger",
        "k": "component"
      },
      {
        "n": "TooltipDiagnostics",
        "k": "component"
      },
      {
        "n": "TooltipPreview",
        "k": "component"
      },
      {
        "n": "ValueChangerCard",
        "k": "component"
      },
      {
        "n": "getPack",
        "k": "helper"
      },
      {
        "n": "listPacks",
        "k": "helper"
      },
      {
        "n": "readOverride",
        "k": "helper"
      },
      {
        "n": "resolveValueChanger",
        "k": "helper"
      },
      {
        "n": "safeHref",
        "k": "helper"
      },
      {
        "n": "sampleProse",
        "k": "helper"
      },
      {
        "n": "selectPacks",
        "k": "helper"
      },
      {
        "n": "start",
        "k": "helper"
      }
    ]
  }
}