Cavekit
Cavekit is a small React package for showing Caveman attribution and savings basis without upgrading a number by accident. It makes provenance explicit in props and keeps the display fallback conservative.
@caveman/kit exports two components and a headless core. The attribution mark is locked. The basis badge requires a basis. The core functions normalize untyped data before it reaches UI.
The locked mark
OptimizedByCaveman is the attribution mark. It exposes only variant and className; the wordmark and link are not props. A host can place it and choose a variant, but cannot rename or repoint it through the component API.
import { OptimizedByCaveman } from "@caveman/kit";
<OptimizedByCaveman variant="footer" />The basis badge
BasisBadge renders the provenance of a savings figure. Its basis is a required prop:
import { BasisBadge } from "@caveman/kit";
<BasisBadge basis="inferred" />
<BasisBadge basis="verified" />There is no default. Omitting basis is a compile error, proven by a @ts-expect-error in the type tests. A value outside the known union fails closed to "Inferred" / unverified, never "Verified".
Three rules the kit enforces in the type system
basis is required. Omitting it on BasisBadge is a compile error — you cannot ship a savings badge without saying where the number came from.
The mark is locked. OptimizedByCaveman exposes only variant and className; the wordmark and link cannot be overridden or rebranded.
verified is never manufactured. An unknown basis fails closed to "Inferred" / unverified. The kit renders verified only when it is explicitly given a verified basis — it never upgrades a number on its own.
The headless core
Import @caveman/kit/core when you need the same basis logic without React.
import { normalizeBasis, isVerified, basisLabel } from "@caveman/kit/core";
isVerified("verified"); // true
isVerified("trust-me"); // false — only an exact "verified" passes
normalizeBasis("trust-me"); // "inferred" — unknown fails closed, never "verified"
basisLabel("measured"); // "Measured"normalizeBasis collapses any value that is not an exact known basis — including any near-miss of verified — down to inferred. Untyped data crossing your boundary can therefore never be displayed as verified. isVerified is true only for an exact "verified". basisLabel is the fail-closed display label.
Install names aren't live yet
Cavekit is MIT. The package name @caveman/kit is reserved for launch — it is not live on the registry yet. Today the kit builds from source; document the published name as the path at launch, not as something that resolves today.