css-calipers 0.15.0 → 1.1.0-beta.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 slafleche
+Copyright (c) 2025-2026 Stéphane LaFlèche
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,493 +1,129 @@
-# CSS-Calipers
+# css-calipers
 
-[![npm](https://img.shields.io/npm/v/css-calipers.svg)](https://www.npmjs.com/package/css-calipers)
-[![types](https://img.shields.io/npm/types/css-calipers.svg)](https://www.npmjs.com/package/css-calipers)
-[![license](https://img.shields.io/npm/l/css-calipers.svg)](./LICENSE.txt)
+The missing pieces of typed CSS input, build-time-validated: colour, measurements, integers, floats, and ratios.
 
-**CSS is code. Treat it that way.**  
-Compile-time unit safety for numeric, unit-bearing CSS values, with no surprises at runtime.
+## The problem
 
-```ts
-// Before: pull the number AND the unit apart, do the math, glue them back
-const match = base.match(/^(-?\d*\.?\d+)([a-z%]+)$/i);
-if (!match) throw new Error(`Bad measurement: ${base}`);
-const [, numStr, unit] = match;
-const num = parseFloat(numStr);
-const pad = `${num + 4}${unit}`;   // and nobody checked that `unit` matches what the caller expects
-
-// After: typed math, units enforced by the compiler
-const base = m(8);                 // or m(8, "rem"), m(1.5, "em"), etc.
-const pad = base.add(4).css();     // type error if units don't match
-```
-
-A small TypeScript library for **type-safe CSS measurements**. Do arithmetic on real numbers with the unit attached, let the compiler catch `px`-vs-`rem` mistakes, and emit a CSS string only at the edge.
-
-At a glance:
-
-- Create measurements with `m` from a number and a unit; if you omit the unit, it defaults to `px` and is typed as the px measurement type.
-- Do unit-safe math with methods like `add` and `multiply`, then call `.css()`
-  at the edge to get a CSS string (for example "10px").
-
-## Install
-
-```bash
-npm install css-calipers
-```
+CSS input values are untyped. A measurement is a string (`'8px'`), an opacity is a bare number, a colour is whatever string you typed. Nothing catches `opacity: 1.5`, a `px` value added to an `em`, or a `z-index` that is silently a float. The mistake surfaces in the browser, not the compiler.
 
----
+## Highlights
 
-## Quick start
+`.css()` on a colour emits the simplest format that holds it without losing information:
 
 ```ts
-import { m } from "css-calipers";
-
-// Declare vars
-const paddingBase = m(4); // defaults to px (and is typed as a px measurement) when no unit is specified
-const rotation = m(45, "deg"); // equivalent to a dedicated helper: mDeg(45)
-
-// Do safe arithmetic
-const margins = paddingBase.add(4);
-const offset = paddingBase.add(margins).multiply(2).subtract(1);
+import { color } from 'css-calipers';
 
-// Emit only at the end in CSS (at runtime or in a build step)
-const style = {
-  padding: paddingBase.css(),
-  transform: `rotate(${rotation.double().css()})`, // 90deg
-};
+color('#3366cc').css();             // '#3366cc'                  (opaque -> hex)
+color('#3366cc').alpha(0.5).css();  // 'rgba(51, 102, 204, 0.5)'  (translucent -> rgba)
+color('oklch(0.7 0.37 150)').css(); // 'oklch(0.7 0.37 150 / 1)'  (wide gamut -> oklch)
 ```
 
-If you prefer, you can also import unit helpers from dedicated subpaths. For example, `mPercent` is available from the root entrypoint and from `css-calipers/units/percent`, and all unit helpers are aggregated under `css-calipers/units`.
-
----
-
-## Status & support
-
-> API surface and docs may change between `0.x` releases until the first stable version.
-
-- Status: early `0.x` release. Backwards compatibility is not guaranteed until `1.0.0`.
-- Questions or bugs: open an issue on GitHub (see the repository link at the top of this page or in `package.json`).
-- Tooling: tested primarily with TypeScript 5.6+ on Node 18+.
-- Support: this is a solo, early-stage project. If it saves you time, you can [buy me a coffee](https://buymeacoffee.com/slafleche) to support continued work.
-
----
-
-## Media queries
+That ladder is the default and is reconfigurable: set your own output format or priority list, per call or per instance.
 
-Media queries have moved out of CSS-Calipers. From `0.15` on, CSS-Calipers is
-purely the measurement layer.
-
-CSS-Calipers itself is part of
-[CSS-Bookends](https://github.com/slafleche/css-bookends): it is the measurement
-lexicon at the centre of the umbrella. The first CSS-Bookends beta gives you
-exactly what `css-calipers@0.14` does today, the same measurement layer and the
-same media query helper, just split into two installable pieces (`css-calipers`
-plus `@css-bookends/media-queries`). Nothing is lost.
-
-If you use the media query helper:
-
-- **Switch to CSS-Bookends** and add `@css-bookends/media-queries` alongside
-  `css-calipers`. Same helper, now maintained in the umbrella.
-- **Or stay on `css-calipers@0.14`**, which still bundles the media query helper
-  and remains the `latest` release for now.
-
-CSS-Bookends is the long-term home for everything beyond measurement (spacing,
-colours, borders, and more), so moving over is the recommended path.
-
----
-
-## Features
-
-- **Compile-time unit validation.** Prevents mixing incompatible units.
-- **Arithmetic safety.** Operate only within matching units; explicit when
-  converting.
-- **Explicit emission.** `.css()` outputs a typed string literal only when
-  needed.
-- **Light runtime footprint.** Near-zero cost when emitted at build time.
-- **Framework-agnostic.** Works anywhere TypeScript does.
-
-Any numeric, unit-bearing CSS value is supported: `m` accepts any unit string you’d use in CSS
-(`'px'`, `'rem'`, `'%'`, `'vw'`, `'deg'`, `'ms'`, …), and you can model new
-measurements without waiting for a dedicated helper. For convenience and better
-types, every standard CSS unit also has a named helper (for example
-`mPx`, `mPercent`, `mVw`, `mEm`, `mMs`, `mFr`), which are equivalent to calling
-`m(value, 'unit')` directly.
-
-CSS-Calipers focuses exclusively on numeric, unit-bearing CSS values. Keywords
-like `auto`, `fit-content`, or `max-content`, full shorthand strings,
-`var(--token)`, or `calc(...)` expressions should remain explicit strings or
-dedicated keyword types in your app or styling layer. Everything else stays as
-plain CSS (see "Philosophy & Boundaries" below for more detail). For a concrete
-example of this separation in a mixed-input helper, see
-[examples/lineHeight-normalizer.example.ts](examples/lineHeight-normalizer.example.ts),
-which keeps keywords and CSS variables as plain strings while using measurements
-for numeric values.
-
----
-
-## Should I use this?
-
-CSS-Calipers is a good fit if:
-
-- You already use TypeScript (or plan to) and want compile-time guarantees around CSS units.
-- You have a design system or token layer where layout math and unit conversions matter.
-- You care about catching unit mismatches and layout invariants early, in dev or tests.
-  This library is opinionated about types and emitting valid CSS at the edges,
-  but intentionally loose about how you structure or apply styles in between.
-
-It’s probably overkill if:
-
-- Your project has minimal custom layout math or relies mostly on utility classes/framework CSS.
-- You don’t use TypeScript and aren’t looking for stronger typing around CSS values.
-- You’re comfortable relying on manual discipline instead of typed measurements for units.
-
----
-
-### Layout tokens example
+Measurements are branded by unit, so a `px` cannot be added to an `em`, and arithmetic re-validates:
 
 ```ts
-import { m, mPercent, mVw, mVh, assertCondition } from "css-calipers";
-
-// Token-style measurements (px by default)
-const spacing = m(8); // Defaults to px and is typed as a PxMeasurement
-const cardPadding = spacing.multiply(2); // 16px
-const gutter = spacing.multiply(1.5); // 12px
-
-// Responsive bounds expressed in other units
-const minWidthPercent = mPercent(75); // 75%; same as m(75, "%")
-const maxWidthViewport = mVw(100); // 100vw; same as m(100, "vw")
-
-// Derived content width in px
-const contentBase = m(320);
-const minCardWidth = m(260);
-const maxCardWidth = m(360);
-
-// In real code, these bounds typically come from tokens or configuration,
-// so keeping the clamp in measurement space ensures units stay consistent.
-const cardWidth = contentBase.clamp(minCardWidth, maxCardWidth);
-
-// Unitless ratio you can reuse elsewhere
-const ratio = contentBase.getValue() / spacing.getValue(); // returns a number, no unit
-
-// Apply ratio to a different unit family
-const heroHeight = mVh(40).multiply(ratio);
-
-// Invalid arithmetic (different units) fails at compile time
-const exampleError = cardWidth.add(heroHeight); // ❌ Type error (px vs vh) see error handling below
-
-// Use plain numbers where they are just counts
-const columns = 3;
-
-// In development, enforce simple invariants so layout mistakes fail fast.
-// In production, you can either rely on earlier validation or add a separate
-// fallback path if this invariant is ever broken.
-if (process.env.NODE_ENV !== "production") {
-  assertCondition(
-    () => columns > 0,
-    "cardGridStyles: columns must be greater than zero",
-  );
-}
-
-// Compose a simple grid layout
-const cardGridStyles = {
-  display: "grid",
-  gap: gutter.css(),
-  // Keep fraction units as plain CSS alongside measurement-derived values
-  gridTemplateColumns: `repeat(${columns}, 1fr)`,
-  // width driven by card width + gutters
-  width: cardWidth
-    .multiply(columns)
-    .add(gutter.multiply(columns - 1))
-    .css(),
-  // container bounds in percent/viewport units
-  minWidth: minWidthPercent.css(),
-  maxWidth: maxWidthViewport.css(),
-  // derived hero height based on px ratio, expressed in vh and used inside a calc() string
-  // calc() stays plain CSS; CSS-Calipers only provides the numeric pieces
-  minHeight: `calc(${heroHeight.css()} + 10vh)`,
-};
-```
+import { m } from 'css-calipers';
 
----
-
-## Do custom checks your way
-
-CSS-Calipers will happily enforce units anywhere you choose, but it stays
-unopinionated about where those guards live. Drop assertions in a component, in
-a theme override, hardcode a debug routine, or wire a global invariant; the
-structure is up to you:
-
-```ts
-import { assertMatchingUnits } from "css-calipers";
-import { formTokens } from "@/tokens/forms.tokens";
-
-if (process.env.NODE_ENV !== "production") {
-  assertMatchingUnits(
-    formTokens.field.paddingBlock,
-    formTokens.field.paddingInline,
-    "Form control padding mismatch",
-  );
-}
-```
-
-You can apply the same checks globally (e.g., during app bootstrap), only
-inside the components that need them, or in dedicated test helpers. For more
-complete patterns, see the examples folder: the validation unit-tests example
-([examples/validation-unit-tests.example.ts](examples/validation-unit-tests.example.ts)) shows how to
-enforce spacing token invariants in a test suite, and the validation and runtime
-checks example ([examples/validation-and-runtime-checks.example.ts](examples/validation-and-runtime-checks.example.ts))
-shows how to apply dev-only guards around shared tokens in two different
-consumers (an HTML snippet and a style object) using the same line-height
-measurement.
-
----
-
-## Error behavior
-
-- Operations are fail-fast: when you call helpers like `add`, `divide`, `clamp`,
-  `measurementMin` / `measurementMax`, or the assertion helpers with invalid
-  input (for example, mismatched units or non-finite values), CSS-Calipers
-  throws a normal `Error`.
-- Error messages include the operation name (for example,
-  `css-calipers.Measurement.divide` or `css-calipers.assertMatchingUnits`), the
-  relevant values/units, and any context string you pass in.
-- The library does not catch these errors for you. You choose where to place
-  assertions and where (if anywhere) to catch and handle exceptions.
-- In production, a common pattern is to wrap assertions in dev-only guards
-  (such as `if (process.env.NODE_ENV !== 'production')`) or to enforce
-  invariants in tests, so checks stay cheap and predictable at runtime.
-
-For concrete uses of these errors in tests and dev-only guards, see
-`TESTING.md` and the validation examples in
-[examples/validation-unit-tests.example.ts](examples/validation-unit-tests.example.ts) and
-[examples/validation-and-runtime-checks.example.ts](examples/validation-and-runtime-checks.example.ts).
-
----
-
-## Common errors
-
-### Non-finite measurement value
-
-Example
-
-```
-css-calipers.m: Non-finite measurement value: undefined [code=CALIPERS_E_NONFINITE | helper=m | inputs=value=undefined, unit=px | stack=...]
+m(8).add(m(4)).css();          // '12px'  (m() defaults to px)
+m(2, 'rem').multiply(2).css(); // '4rem'
 ```
 
-What it means
-
-- A measurement was constructed with undefined, NaN, or Infinity.
-
-How to fix
+Ratios accept typed integers and floats on either side:
 
-- Provide a real numeric value and a unit (m(12), m(12, "px")).
-- Add a context label so the error points to the calling helper or token (m(12, { context: "tokens.cardWidth" })).
-
-### Unit mismatch
-
-Example
+```ts
+import { r, i, f } from 'css-calipers';
 
+r(i(16), i(9)).css();  // '16/9'
+r(f(1.5), i(2)).css(); // '1.5/2'  (a float and an integer)
 ```
-css-calipers.assertMatchingUnits: measurement unit mismatch: px vs em [code=CALIPERS_E_UNIT_MISMATCH]
-```
-
-What it means
 
-- You mixed units without an explicit conversion.
+Refinements turn a runtime check into a compile-time guarantee: the checked value is branded, so a function that demands a non-negative measurement cannot be handed an unchecked one.
 
-How to fix
-
-- Normalize units at the source (convert em to px or vice versa).
-- Add an assertMatchingUnits call where the values enter your system.
+```ts
+import { m, nonNegative, inRange } from 'css-calipers';
 
-### Divide by zero
+// `ensure` runs the check, then hands the value back with a HARDENED type. The brand
+// proves it passed, so anything typed NonNegativeMeasurement is known to be checked.
+const width = nonNegative.ensure(m(8)); // type: NonNegativeMeasurement<'px'>  (throws if negative)
 
-Example
+// `inRange` bakes its literal bounds into the type, so it is distinct from any other range.
+const pct = inRange(0, 100).ensure(m(50, '%')); // type: InRangeMeasurement<'%', 0, 100>
 
-```
-css-calipers.Measurement.divide: Cannot divide 10px by zero [code=CALIPERS_E_DIVIDE_BY_ZERO]
+// `hardenWith` always returns a valid, hardened value: if the input fails the check it
+// falls back to a known-good one instead of throwing.
+nonNegative.hardenWith(m(-4, 'px')).css(); // '0px'  (-4 fails the check, so it falls back to 0)
 ```
 
-What it means
+Integers (`i`), floats (`f`), and custom colour formats round out the set.
 
-- You attempted to divide by zero in a measurement operation.
+## Why csstype does not cover this
 
-How to fix
+`csstype` is excellent and ships here as a dependency. It types CSS property names and their keywords well. What it leaves loose is open INPUT values: where a property accepts an open number or string, csstype falls back to `(number & {})`, so a bare `1.5`, a `px` added to an `em`, or a float `z-index` all pass. You cannot construct a validated value from that. calipers fills exactly that gap, and `.css()` renders to a string that still satisfies csstype on output. It complements csstype; it never replaces it. csstype types the property and keyword side, calipers types the value side, and the aim is a complete typed surface for CSS input, built from both.
 
-- Guard inputs before dividing or replace zero with a safe fallback.
+calipers is standalone and complete on its own. It is also Layer 1 of the larger CSS-Bookends project (helpers, then an opinionated framework, built on these primitives), and design-token (DTCG) documents convert to these primitives via the Bookends typesetter. Both are there if you want them, never required.
 
-### Clamp bounds
+A note on the names. The book metaphor (calipers, bookends, gilding, compendium) is deliberate, not just whimsy. Each name marks a ROLE, and intentionally hides the library currently filling it, because those internals are meant to be swappable. You import `color()`, not `culori`; the project's browser-compat finisher is `gilding`, not Lightning CSS. Swap the engine underneath and your call sites do not move.
 
-Example
+## Install
 
-```
-css-calipers.Measurement.clamp: clamp: min (20px) must be <= max (12px) [code=CALIPERS_E_CLAMP_INVALID_RANGE]
+```sh
+npm install css-calipers
 ```
 
-What it means
+Dependencies: `csstype` and `culori` (the colour engine). ESM and CommonJS are both published; the colour surface is reachable from the root import.
 
-- The clamp minimum is greater than the clamp maximum.
+## Colour
 
-How to fix
+`color(input, config?)` parses a CSS string, a structured `ColorObject` (one shape per colour space: `{ space: 'rgb', r, g, b, alpha? }`, hsl, hwb, lab, lch, oklab, oklch), a symbolic keyword (`currentColor`, a system colour, a cascade keyword), or an existing resolved colour. It normalizes to OKLCH internally and returns an immutable result.
 
-- Ensure min and max come from the same source or swap them before calling clamp.
+Modifications return a new colour (the original is untouched) and thread the configured output format through: `darken`, `lighten`, `brighten`, `saturate`, `desaturate`, `setLightness`, `setChroma`, `setHue`, `hueShift`, `complement`, `mix`, `mixSolid`, `mixWithAlpha`, `alpha`, `solid`, `clone`, `contrast`. See `examples/color-modify.example.ts`.
 
-### Stack hints and configuration
+**Output.** `.css()` takes no argument and walks the default ladder `[hex, rgba, oklch]` (the order is backed by usage data, see `docs/color-format-popularity.md`). Force a format with a named selector (`.hex()`, `.rgb()`, `.rgba()`, `.hexAlpha()`, `.hsl()`, `.hwb()`, `.lab()`, `.lch()`, `.oklab()`, `.oklch()`, `.displayP3()`) or `.formatAs(...)`. `omitOpaqueAlpha` drops the alpha slot for an opaque colour where it is optional (lossless, off by default).
 
-For m and unit helpers, errors include a trimmed stack hint in non-production by default.
-You can disable or force stack hints globally:
+**Strictness.** When a render cannot faithfully hold the colour (dropping a real alpha, out of sRGB gamut, modifying a symbolic colour), `strictness` decides: `auto` (default, throw in dev, warn in prod), `throw`, `warn`, or `silent`.
 
+```ts
+color('#3366cc80').rgb().css();                           // throws in dev (rgb carries no alpha)
+color('#3366cc80', { strictness: 'silent' }).rgb().css(); // 'rgb(51, 102, 204)'  (alpha dropped)
 ```
-import { setErrorConfig } from "css-calipers";
 
-// Disable stack hints everywhere (for production).
-setErrorConfig({ stackHints: "off" });
+**Transparency.** A fully transparent colour renders as the `transparent` keyword by default; configurable with `{ transparent: 'keyword' | 'white' | 'black' | 'preserve' }` or per render with `.transparentAs(mode)`. See `examples/transparency.example.ts`.
 
-// Force stack hints everywhere (useful in dev or tests).
-setErrorConfig({ stackHints: "on" });
-```
+**Custom formats.** `createColor({ formats })` binds custom format plugins. A plugin bridges the input and output edges (storage stays canonical OKLCH) and gets a typed named selector; author one with `defineColorSpace`, and an optional `fallback` hook rewrites its output into browser-safe CSS. See `examples/custom-format.example.ts` (its "zoo" format is a deliberately silly extensibility demo, not a real format), `examples/plugin-fallback.example.ts`, and `docs/adding-a-color-format.md`.
 
----
+## Measurements
 
-## Factory entrypoint (optional)
+`m(value, unit?)` builds a measurement (unit defaults to `px`, lower-cased). Arithmetic, `round`, and `clamp` return new measurements in the same unit. Per-unit helpers bind the unit (`mPx`, `mEm`, `mRem`, `mPercent`, `mCqw`, ...) across every unit family: absolute, font-relative, viewport, container, angle, time, frequency, resolution, and grid.
 
-If you want instance-scoped configuration and a single re-export surface, use
-the factory entrypoint. The instance includes core helpers and unit helpers.
+## Integers and floats
 
-```
-import { createCalipers } from "css-calipers/factory";
+`i()` (a whole number) and `f()` (a real number) are constrained scalars for the unitless number space CSS leaves untyped. Both validate at construction and re-validate on every operation, so a constrained value stays valid (or throws) through arithmetic. `clamp(min, max)` snaps into range instead of throwing; `hardenInteger({ min, max })` / `hardenFloat({ min, max })` bind a constraint once into a reusable factory. See `examples/integers-floats.example.ts`.
 
-const calipers = createCalipers({
-  errorConfig: { stackHints: "on" },
-});
+## Ratios
 
-export const { m, mPx, units } = calipers;
-```
+`r(numerator, denominator?)` (denominator `1` when omitted) accepts typed integers and floats on either side, with helpers `simplifyRatio`, `reduceRatio`, `normalizeRatio`, and `parseRatio`. See `examples/ratio.example.ts`.
 
-See [examples/factory-wrapper.example.ts](examples/factory-wrapper.example.ts)
-for a wrapper module you can re-export across your project.
+## Hardening and constraints
 
----
+Refinements run a runtime check and return the same value branded with the constraint, so a function can demand "a non-negative measurement" and the compiler rejects anything unchecked (brands are keyed by a private symbol). The built-ins are `nonNegative`, `nonPositive`, and `inRange(min, max)`, each exposing `.is` / `.ensure` / `.check` / `.hardenWith`. `inRange` carries its literal bounds in the type. Build your own with `makeMeasurementRefinement`. The full model is in `docs/hardening.md`, with runnable examples in `examples/refinements.example.ts`.
 
-## Co-existing with other systems
+## Per-property value helpers live in the books layer
 
-You don’t have to convert everything at once, or at all. If it fits your setup,
-you can write small adapters that accept existing CSS strings, CSS-Calipers
-measurements, or plain numbers and turn them into CSS values. CSS-Calipers can
-be dropped into an existing styling system or used from the ground up; it
-focuses narrowly on numeric, unit-bearing values and leaves the rest of your
-styling approach up to you. For a more realistic adapter pattern that
-normalizes mixed inputs (including CSS variables) into a single css-like value,
-see the line-height normalizer example referenced below.
+calipers is the value-type primitives only (colour, measurements, integers, floats, ratios). The per-property value helpers (`opacity`, `zIndex`, `fontWeight`, ...) are NOT a calipers feature: they live one layer up, in the books layer. Each is a book that binds a calipers primitive to one CSS property, applies that property's bound and keyword companions, and types its `.css()` output against the matching csstype `Property.X`. The shared engine behind them is `@css-bookends/css-value-core`. For the full picture, the value-type side is mapped in `lexicons/calipers/surface.md` and the per-property side in `packages/css-value-core/surface.md`.
 
-## Advanced
+## Factories
 
-### String Literal Type Exclusion
+The bare exports (`m`, `color`, the refinements, ...) are each a factory already called at its defaults, so the default instance and a custom instance share one construction path. The factory itself is the real configurable path and the override seam: `createCalipers({ errorConfig? })` returns a measurement instance and `createColor({ formats })` a colour instance with custom format plugins registered, and routing every consumer through a factory means you can rewrite or wrap any step (input, storage, output) with zero call-site changes. `corpus` is the lazy-defaults convenience entry: it default-exports a master factory, `createCalipersBundle({ measurements?, color? })`, that combines `createCalipers` + `createColor` under one keyed config and binds the whole calipers surface in one object (mirroring the compendium's `publishCompendium`), and it named-exports that same primitive set already bound at defaults, so you get everything wired without touching a factory yourself. (`corpus` and the bookends `@css-bookends/compendium/defaults` subpath are the only two lazy-defaults entries in the project.) Binding a factory once in one of your own modules and re-exporting the bound helper from there also keeps the blast radius of a library change small: your code imports that helper from a single seam, so a major restructuring of the library's internal paths lands in that one file, not across the hundreds or thousands of call sites that use it. And because each factory call returns its own independent instance, several configurations coexist side by side with no shared global state to collide: a `createColor` that emits hex and another that emits oklch, or a strict instance next to a clamping one, all live at once, with no cascade or global state to fight (each instance is just a value in scope, not a stylesheet competing in the cascade). See `examples/factory-wrapper.example.ts`.
 
-When helpers must _exclude_ CSS-Calipers–emitted numeric, unit-bearing CSS values from a keyword union,
-use the exported `MeasurementString` type together with your existing CSS
-property typings (for example, the `Property` types from the `csstype`
-package):
+All of that power is opt-in. If you just want sensible defaults and none of the above, you never touch a factory: the bare `m` / `color` / refinement exports are ready as-is, and `corpus` hands you the whole primitive set bound at defaults in one import.
 
-```ts
-import type { MeasurementString } from "css-calipers";
-import type { Property } from "csstype";
+## Documentation
 
-type SpacingKeyword = Exclude<
-  Extract<Property.Margin, string>,
-  MeasurementString
->;
-```
+Deeper dives live in `docs/`:
 
-This lets helpers stay strict: `IMeasurement` for numeric, unit-bearing CSS values; targeted string
-keywords for symbolic CSS values, without reintroducing vague unions like
-`MeasurementLike`.
-
-### Integration Patterns
-
-- **Typed helpers:** Accept either `IMeasurement` or a constrained keyword type,
-  never a generic string.
-- **Pre-emission transforms:** Compose all math in CSS-Calipers, emit once at
-  the style boundary.
-- **Build-time pipelines:** Run measurement math in Node or a build step
-  (scripts, codegen, or bundler plugins) and emit plain CSS or tokens for your
-  existing styling system so runtime only sees static values.
-- **Unit guards in debug:** Use `assertUnit()` in dev-only blocks to confirm
-  consistency between related measurements.
-- **CSS variables:** Pass CSS-Calipers `.css()` output into style layers that
-  interpolate them, but don’t try to store `var(--token)` inside the library.
-
----
-
-## Philosophy & Boundaries
-
-- **Measurement math lives here; string composition lives elsewhere.**  
-  Use CSS-Calipers for unit-aware calculations, then hand results to
-  helpers/adapters that emit CSS literals. Keep `calc()`/`linear-gradient()` logic outside
-  the library so measurement objects remain pure.
-
-- **`.css()` at runtime is an edge, not a habit.**  
-  You can call `.css()` at runtime, but prefer emitting once to avoid hot-path
-  string churn.
-
-- **Numbers are operands, not CSS-Calipers values.**  
-  You cannot create a CSS-Calipers value without a unit. Pass plain numbers as
-  operands (`add`, `subtract`, `multiply`, `divide`) or combine with another
-  `IMeasurement`, but never store bare numbers inside library state. If a value
-  lacks both number and unit, CSS-Calipers won’t track it; you own whatever
-  logic wraps it.
-
-- **Model keywords explicitly (not “escape hatches”).**  
-  If a helper needs symbolic CSS (e.g., `'auto'`, `'fit-content'`), define a
-  precise keyword type and purposely exclude the emitted string type from
-  CSS-Calipers so numeric, unit-bearing CSS values remain the default path.
-
-- **CSS custom properties coexist; they don’t mix.**  
-  Third-party primitives exposing `var(--token)` should keep those values as raw
-  CSS strings. CSS-Calipers is intentionally narrow: it works with numeric
-  measurements and unit-safe conversions, not tokens or CSS variables. You can
-  still use `var(...)` and token strings anywhere in your styling system; they
-  just sit outside the library. If you want those values to flow through
-  CSS-Calipers, first extract the numeric value and unit in your own code and
-  then pass that measurement into the library.
-
-## Using CSS-Calipers in a larger styling system
-
-CSS is inherently flexible: the same property can accept numbers, unit-bearing
-strings, keywords, and CSS variables. CSS-Calipers is one focused piece of that
-ecosystem. It keeps the numeric, unit-bearing parts typed and predictable, and
-lets the rest of your styling system own tokens, variables, and higher-level
-APIs.
-
-For a worked example of this pattern, see
-[examples/lineHeight-normalizer.example.ts](examples/lineHeight-normalizer.example.ts). It shows a helper that accepts a
-`lineHeight` value from a CMS or configuration (numbers, numeric strings with
-units, keywords like `"normal"`, or CSS variables such as
-`"var(--body-line-height)"`) and normalizes them into a value with a `.css()`
-method. CSS-Calipers only participates when there is a concrete measurement
-(numbers and units); keywords and CSS variables remain plain CSS strings owned
-by your styling layer. That’s the intended scope: CSS will always be a mix of
-values, but the library gives you a tight, unit-safe boundary for the numeric
-parts inside a broader styling solution.
-
-### Module guides
-
-Deeper guides live alongside this README:
-
-- Measurements core: [README_MEASUREMENT.md](README_MEASUREMENT.md)
-- Media queries: now in [`@css-bookends/media-queries`](https://github.com/slafleche/css-bookends)
-
-### Further examples in this repo
-
-The `examples/` folder contains a few non-published usage sketches:
-
-- [examples/lineHeight-normalizer.example.ts](examples/lineHeight-normalizer.example.ts) &mdash;
-  mixed input normalization for `lineHeight` (numbers, strings, CSS variables)
-  into a single value with a `.css()` method.
-- [examples/validation-unit-tests.example.ts](examples/validation-unit-tests.example.ts) &mdash;
-  simple unit tests that enforce spacing token invariants (shared units and
-  small &le; large).
-- [examples/validation-and-runtime-checks.example.ts](examples/validation-and-runtime-checks.example.ts) &mdash;
-  dev-only validation around shared tokens in two different consumers (HTML
-  string and style object) using the same line-height measurement.
-- [examples/factory-wrapper.example.ts](examples/factory-wrapper.example.ts) &mdash;
-  instance-scoped factory wrapper that re-exports the helpers.
+- `docs/number-space.md` - which scalar CSS values are worth typing, and why.
+- `docs/hardening.md` - the refinement model, branded types, and custom refinements.
+- `docs/custom-format-registration.md` and `docs/adding-a-color-format.md` - registering custom colour formats end to end.
+- `docs/color-format-popularity.md` - the usage data behind the default output ladder.
+- `docs/integration.md` - using calipers with a styling pipeline.

package/dist/cjs/color/formats/display-p3/display-p3.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.displayP3 = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * display-p3 — wider-than-sRGB device RGB (the P3 gamut), with alpha. This is the
+ * one gamut-DEPENDENT format: a fallback should also gate on
+ * `@media (color-gamut: p3)`, since the wider color only shows on a P3 display. Out
+ * of P3 is clamped (strictness-governed). Not a floor.
+ *
+ * See `display-p3.md`.
+ */
+exports.displayP3 = (0, types_1.defineColorSpace)({
+    format: 'displayP3',
+    hasAlpha: true,
+    gamut: 'p3',
+    supportsProbe: '(color: color(display-p3 0 0 0))',
+    gamutDependent: true,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = (0, internals_1.toP3)((0, internals_1.fitGamut)(color, internals_1.inP3, 'p3', cfg.strictness));
+        return `color(display-p3 ${(0, internals_1.round)(c.r, 5)} ${(0, internals_1.round)(c.g, 5)} ${(0, internals_1.round)(c.b, 5)}${(0, internals_1.alphaSlot)(color, cfg)})`;
+    },
+});

package/dist/cjs/color/formats/escalate.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chooseFormat = void 0;
+const index_1 = require("./index");
+const internals_1 = require("./internals");
+const resolve_1 = require("./resolve");
+const descriptorFor = (format) => (0, resolve_1.asDescriptor)(format, index_1.colorFormats);
+/**
+ * Whether a format can FAITHFULLY hold the color: its gamut contains the color, and
+ * it carries alpha if the color is non-opaque. 8-bit sRGB precision is accepted as
+ * faithful, so gamut + alpha are the only fit criteria.
+ */
+const fits = (color, format) => {
+    const d = descriptorFor(format);
+    const gamutOk = d.gamut === 'unbounded'
+        ? true
+        : d.gamut === 'p3'
+            ? (0, internals_1.inP3)(color)
+            : (0, internals_1.inSrgb)(color);
+    const alphaOk = d.hasAlpha || !(0, internals_1.hasRealAlpha)(color);
+    return gamutOk && alphaOk;
+};
+/**
+ * Resolve an output config to a single format. A single format passes through
+ * unchanged (an explicit choice, no escalation). A priority list escalates to the
+ * first format that faithfully holds the color, or the last entry if none do (which
+ * then clamps via the render step's strictness).
+ */
+const chooseFormat = (color, output) => {
+    if (!Array.isArray(output)) {
+        return output;
+    }
+    const list = output;
+    for (const format of list) {
+        if (fits(color, format)) {
+            return format;
+        }
+    }
+    return list[list.length - 1];
+};
+exports.chooseFormat = chooseFormat;