css-calipers 0.15.0 → 1.1.0-beta.0

package/dist/cjs/factory.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCalipers = void 0;
-const errors_1 = require("./internal/errors");
 const createCoreApi_1 = require("./internal/createCoreApi");
 const createUnitsApi_1 = require("./internal/createUnitsApi");
+const errors_1 = require("./internal/errors");
 const createCalipers = (config = {}) => {
     var _a;
     const errorStore = (0, errors_1.createErrorConfigStore)((_a = config.errorConfig) !== null && _a !== void 0 ? _a : {});

package/dist/cjs/float.js

@@ -0,0 +1,110 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _FloatImpl_instances, _FloatImpl_value, _FloatImpl_min, _FloatImpl_max, _FloatImpl_context, _FloatImpl_options;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFloat = exports.hardenFloat = void 0;
+exports.f = f;
+const toPlainDecimal_1 = require("./internal/toPlainDecimal");
+const scalar_1 = require("./scalar");
+const suffix = (context) => context ? ` [${context}]` : '';
+const coerce = (value) => (0, scalar_1.toNumber)(value);
+class FloatImpl {
+    constructor(value, options = {}) {
+        _FloatImpl_instances.add(this);
+        _FloatImpl_value.set(this, void 0);
+        _FloatImpl_min.set(this, void 0);
+        _FloatImpl_max.set(this, void 0);
+        _FloatImpl_context.set(this, void 0);
+        const { min, max, context } = options;
+        if (min !== undefined && max !== undefined && min > max) {
+            throw new Error(`f: min (${min}) must be <= max (${max})${suffix(context)}`);
+        }
+        if (!Number.isFinite(value)) {
+            throw new Error(`f: expected a finite number (got ${value})${suffix(context)}`);
+        }
+        if (min !== undefined && value < min) {
+            throw new Error(`f: ${value} is below the minimum ${min}${suffix(context)}`);
+        }
+        if (max !== undefined && value > max) {
+            throw new Error(`f: ${value} is above the maximum ${max}${suffix(context)}`);
+        }
+        __classPrivateFieldSet(this, _FloatImpl_value, value, "f");
+        __classPrivateFieldSet(this, _FloatImpl_min, min, "f");
+        __classPrivateFieldSet(this, _FloatImpl_max, max, "f");
+        __classPrivateFieldSet(this, _FloatImpl_context, context, "f");
+    }
+    value() {
+        return __classPrivateFieldGet(this, _FloatImpl_value, "f");
+    }
+    valueOf() {
+        return __classPrivateFieldGet(this, _FloatImpl_value, "f");
+    }
+    constraints() {
+        return { min: __classPrivateFieldGet(this, _FloatImpl_min, "f"), max: __classPrivateFieldGet(this, _FloatImpl_max, "f") };
+    }
+    css() {
+        return (0, toPlainDecimal_1.toPlainDecimal)(__classPrivateFieldGet(this, _FloatImpl_value, "f"));
+    }
+    toString() {
+        return this.css();
+    }
+    withValue(value) {
+        return new FloatImpl(value, __classPrivateFieldGet(this, _FloatImpl_instances, "m", _FloatImpl_options).call(this));
+    }
+    add(delta) {
+        return this.withValue(__classPrivateFieldGet(this, _FloatImpl_value, "f") + coerce(delta));
+    }
+    subtract(delta) {
+        return this.withValue(__classPrivateFieldGet(this, _FloatImpl_value, "f") - coerce(delta));
+    }
+    multiply(factor) {
+        return this.withValue(__classPrivateFieldGet(this, _FloatImpl_value, "f") * coerce(factor));
+    }
+    divide(divisor) {
+        const numeric = coerce(divisor);
+        if (numeric === 0) {
+            throw new Error(`f: cannot divide ${__classPrivateFieldGet(this, _FloatImpl_value, "f")} by zero${suffix(__classPrivateFieldGet(this, _FloatImpl_context, "f"))}`);
+        }
+        const result = __classPrivateFieldGet(this, _FloatImpl_value, "f") / numeric;
+        if (!Number.isFinite(result)) {
+            throw new Error(`f: non-finite result dividing ${__classPrivateFieldGet(this, _FloatImpl_value, "f")} by ${numeric}${suffix(__classPrivateFieldGet(this, _FloatImpl_context, "f"))}`);
+        }
+        return this.withValue(result);
+    }
+    clamp(min, max) {
+        if (min > max) {
+            throw new Error(`f.clamp: min (${min}) must be <= max (${max})`);
+        }
+        return this.withValue(Math.min(max, Math.max(min, __classPrivateFieldGet(this, _FloatImpl_value, "f"))));
+    }
+}
+_FloatImpl_value = new WeakMap(), _FloatImpl_min = new WeakMap(), _FloatImpl_max = new WeakMap(), _FloatImpl_context = new WeakMap(), _FloatImpl_instances = new WeakSet(), _FloatImpl_options = function _FloatImpl_options() {
+    return { min: __classPrivateFieldGet(this, _FloatImpl_min, "f"), max: __classPrivateFieldGet(this, _FloatImpl_max, "f"), context: __classPrivateFieldGet(this, _FloatImpl_context, "f") };
+};
+/**
+ * Create a typed float (a finite, unitless real number) with optional range
+ * constraints. Operations re-validate against the same constraints, so a
+ * hardened float stays hardened (or throws) through arithmetic.
+ */
+function f(value, options = {}) {
+    return new FloatImpl(value, options);
+}
+/**
+ * Bind a set of float constraints once and reuse the bound factory, the scalar
+ * analogue of `makeUnitHelper`. For example, an opacity value is
+ * `hardenFloat({ min: 0, max: 1 })`.
+ */
+const hardenFloat = (constraints = {}) => (value, context) => new FloatImpl(value, { ...constraints, context });
+exports.hardenFloat = hardenFloat;
+const isFloat = (value) => value instanceof FloatImpl;
+exports.isFloat = isFloat;

package/dist/cjs/index.js

@@ -14,17 +14,37 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.storeColor = exports.resolveColor = exports.parseColor = exports.defineColorSpace = exports.defaultFormatPriority = exports.defaultColorConfig = exports.createColor = exports.colorFormats = exports.color = void 0;
 __exportStar(require("./core"), exports);
-__exportStar(require("./units/percent"), exports);
+// The bare default-instance helpers (`m`, refinements, unit-helper builders,
+// error-config accessors) come from the single construction path in `./default`,
+// which assembles them via `createCalipers()` at its defaults.
+__exportStar(require("./default"), exports);
+// The native colour input, alongside `m()` / `r()` / `i()` / `f()`. The full value
+// surface also lives at the `./color` subpath (for bundler/node16 consumers); the root
+// re-exports it too so classic-resolution consumers (e.g. @css-bookends/color) can reach
+// it without a subpath. The lower-level value primitives are color-prefixed (and
+// `resolve` is re-exported as `resolveColor`) to avoid colliding with calipers' own names.
+var color_1 = require("./color");
+Object.defineProperty(exports, "color", { enumerable: true, get: function () { return color_1.color; } });
+Object.defineProperty(exports, "colorFormats", { enumerable: true, get: function () { return color_1.colorFormats; } });
+Object.defineProperty(exports, "createColor", { enumerable: true, get: function () { return color_1.createColor; } });
+Object.defineProperty(exports, "defaultColorConfig", { enumerable: true, get: function () { return color_1.defaultColorConfig; } });
+Object.defineProperty(exports, "defaultFormatPriority", { enumerable: true, get: function () { return color_1.defaultFormatPriority; } });
+Object.defineProperty(exports, "defineColorSpace", { enumerable: true, get: function () { return color_1.defineColorSpace; } });
+Object.defineProperty(exports, "parseColor", { enumerable: true, get: function () { return color_1.parseColor; } });
+Object.defineProperty(exports, "resolveColor", { enumerable: true, get: function () { return color_1.resolve; } });
+Object.defineProperty(exports, "storeColor", { enumerable: true, get: function () { return color_1.storeColor; } });
 __exportStar(require("./units/absolute"), exports);
-__exportStar(require("./units/font-relative"), exports);
-__exportStar(require("./units/viewport"), exports);
-__exportStar(require("./units/viewport-small"), exports);
-__exportStar(require("./units/viewport-large"), exports);
-__exportStar(require("./units/viewport-dynamic"), exports);
-__exportStar(require("./units/container"), exports);
 __exportStar(require("./units/angle"), exports);
-__exportStar(require("./units/time"), exports);
+__exportStar(require("./units/container"), exports);
+__exportStar(require("./units/font-relative"), exports);
 __exportStar(require("./units/frequency"), exports);
-__exportStar(require("./units/resolution"), exports);
 __exportStar(require("./units/grid"), exports);
+__exportStar(require("./units/percent"), exports);
+__exportStar(require("./units/resolution"), exports);
+__exportStar(require("./units/time"), exports);
+__exportStar(require("./units/viewport"), exports);
+__exportStar(require("./units/viewport-dynamic"), exports);
+__exportStar(require("./units/viewport-large"), exports);
+__exportStar(require("./units/viewport-small"), exports);

package/dist/cjs/integer.js

@@ -0,0 +1,114 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _IntegerImpl_instances, _IntegerImpl_value, _IntegerImpl_min, _IntegerImpl_max, _IntegerImpl_context, _IntegerImpl_options;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInteger = exports.hardenInteger = void 0;
+exports.i = i;
+const toPlainDecimal_1 = require("./internal/toPlainDecimal");
+const scalar_1 = require("./scalar");
+const suffix = (context) => context ? ` [${context}]` : '';
+const coerce = (value) => (0, scalar_1.toNumber)(value);
+class IntegerImpl {
+    constructor(value, options = {}) {
+        _IntegerImpl_instances.add(this);
+        _IntegerImpl_value.set(this, void 0);
+        _IntegerImpl_min.set(this, void 0);
+        _IntegerImpl_max.set(this, void 0);
+        _IntegerImpl_context.set(this, void 0);
+        const { min, max, context } = options;
+        if (min !== undefined && max !== undefined && min > max) {
+            throw new Error(`i: min (${min}) must be <= max (${max})${suffix(context)}`);
+        }
+        if (!Number.isFinite(value)) {
+            throw new Error(`i: expected a finite number (got ${value})${suffix(context)}`);
+        }
+        if (!Number.isInteger(value)) {
+            throw new Error(`i: expected an integer (got ${value})${suffix(context)}`);
+        }
+        if (min !== undefined && value < min) {
+            throw new Error(`i: ${value} is below the minimum ${min}${suffix(context)}`);
+        }
+        if (max !== undefined && value > max) {
+            throw new Error(`i: ${value} is above the maximum ${max}${suffix(context)}`);
+        }
+        __classPrivateFieldSet(this, _IntegerImpl_value, value, "f");
+        __classPrivateFieldSet(this, _IntegerImpl_min, min, "f");
+        __classPrivateFieldSet(this, _IntegerImpl_max, max, "f");
+        __classPrivateFieldSet(this, _IntegerImpl_context, context, "f");
+    }
+    value() {
+        return __classPrivateFieldGet(this, _IntegerImpl_value, "f");
+    }
+    valueOf() {
+        return __classPrivateFieldGet(this, _IntegerImpl_value, "f");
+    }
+    constraints() {
+        return { min: __classPrivateFieldGet(this, _IntegerImpl_min, "f"), max: __classPrivateFieldGet(this, _IntegerImpl_max, "f") };
+    }
+    css() {
+        return (0, toPlainDecimal_1.toPlainDecimal)(__classPrivateFieldGet(this, _IntegerImpl_value, "f"));
+    }
+    toString() {
+        return this.css();
+    }
+    withValue(value) {
+        return new IntegerImpl(value, __classPrivateFieldGet(this, _IntegerImpl_instances, "m", _IntegerImpl_options).call(this));
+    }
+    add(delta) {
+        return this.withValue(__classPrivateFieldGet(this, _IntegerImpl_value, "f") + coerce(delta));
+    }
+    subtract(delta) {
+        return this.withValue(__classPrivateFieldGet(this, _IntegerImpl_value, "f") - coerce(delta));
+    }
+    multiply(factor) {
+        return this.withValue(__classPrivateFieldGet(this, _IntegerImpl_value, "f") * coerce(factor));
+    }
+    divide(divisor) {
+        const numeric = coerce(divisor);
+        if (numeric === 0) {
+            throw new Error(`i: cannot divide ${__classPrivateFieldGet(this, _IntegerImpl_value, "f")} by zero${suffix(__classPrivateFieldGet(this, _IntegerImpl_context, "f"))}`);
+        }
+        const result = __classPrivateFieldGet(this, _IntegerImpl_value, "f") / numeric;
+        if (!Number.isFinite(result)) {
+            throw new Error(`i: non-finite result dividing ${__classPrivateFieldGet(this, _IntegerImpl_value, "f")} by ${numeric}${suffix(__classPrivateFieldGet(this, _IntegerImpl_context, "f"))}`);
+        }
+        return this.withValue(result);
+    }
+    clamp(min, max) {
+        if (min > max) {
+            throw new Error(`i.clamp: min (${min}) must be <= max (${max})`);
+        }
+        return this.withValue(Math.min(max, Math.max(min, __classPrivateFieldGet(this, _IntegerImpl_value, "f"))));
+    }
+}
+_IntegerImpl_value = new WeakMap(), _IntegerImpl_min = new WeakMap(), _IntegerImpl_max = new WeakMap(), _IntegerImpl_context = new WeakMap(), _IntegerImpl_instances = new WeakSet(), _IntegerImpl_options = function _IntegerImpl_options() {
+    return { min: __classPrivateFieldGet(this, _IntegerImpl_min, "f"), max: __classPrivateFieldGet(this, _IntegerImpl_max, "f"), context: __classPrivateFieldGet(this, _IntegerImpl_context, "f") };
+};
+/**
+ * Create a typed integer (a finite whole number) with optional range
+ * constraints. Operations re-validate against the same constraints, so a
+ * result that is no longer an integer (or falls out of range) throws. That is
+ * how integer-ness survives arithmetic.
+ */
+function i(value, options = {}) {
+    return new IntegerImpl(value, options);
+}
+/**
+ * Bind a set of integer constraints once and reuse the bound factory, the
+ * scalar analogue of `makeUnitHelper`. For example, a font-weight value is
+ * `hardenInteger({ min: 1, max: 1000 })`.
+ */
+const hardenInteger = (constraints = {}) => (value, context) => new IntegerImpl(value, { ...constraints, context });
+exports.hardenInteger = hardenInteger;
+const isInteger = (value) => value instanceof IntegerImpl;
+exports.isInteger = isInteger;

package/dist/cjs/internal/createCoreApi.js

@@ -12,35 +12,11 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCoreApi = void 0;
+const scalar_1 = require("../scalar");
 const unitDefinitions_1 = require("../unitDefinitions");
 const buildMeasurementCreationError_1 = require("./buildMeasurementCreationError");
 const errors_1 = require("./errors");
-// JS stringifies numbers in exponential form once the magnitude is >= 1e21 or
-// < 1e-6 (e.g. "1e+21", "1e-7"). CSS output must never contain that, so we
-// expand the exponent into a plain decimal by shifting the decimal point on the
-// digit string. This is string manipulation on the same digits, so it does not
-// re-introduce floating-point error.
-const toPlainDecimal = (value) => {
-    const text = `${value}`;
-    if (!text.includes('e') && !text.includes('E')) {
-        return text;
-    }
-    const [mantissa, exponentText] = text.toLowerCase().split('e');
-    const exponent = Number(exponentText);
-    const negative = mantissa.startsWith('-');
-    const unsigned = negative ? mantissa.slice(1) : mantissa;
-    const [intDigits, fracDigits = ''] = unsigned.split('.');
-    const digits = intDigits + fracDigits;
-    const pointFromLeft = intDigits.length + exponent;
-    const sign = negative ? '-' : '';
-    if (pointFromLeft <= 0) {
-        return `${sign}0.${'0'.repeat(-pointFromLeft)}${digits}`;
-    }
-    if (pointFromLeft >= digits.length) {
-        return `${sign}${digits}${'0'.repeat(pointFromLeft - digits.length)}`;
-    }
-    return `${sign}${digits.slice(0, pointFromLeft)}.${digits.slice(pointFromLeft)}`;
-};
+const toPlainDecimal_1 = require("./toPlainDecimal");
 const createCoreApi = (errorStore) => {
     var _Measurement_instances, _a, _Measurement_value, _Measurement_unit, _Measurement_clone;
     const { throwHelperError, throwMeasurementMethodError } = (0, errors_1.createErrorHelpers)(errorStore);
@@ -50,7 +26,10 @@ const createCoreApi = (errorStore) => {
         if (leftUnit !== rightUnit) {
             throwHelperError({
                 operation: 'css-calipers.assertMatchingUnits',
-                params: [left, right],
+                params: [
+                    left,
+                    right,
+                ],
                 message: `measurement unit mismatch: ${leftUnit} vs ${rightUnit}`,
                 context,
                 details: { code: 'CALIPERS_E_UNIT_MISMATCH' },
@@ -80,7 +59,7 @@ const createCoreApi = (errorStore) => {
             __classPrivateFieldSet(this, _Measurement_unit, unit.toLowerCase(), "f");
         }
         css() {
-            return `${toPlainDecimal(__classPrivateFieldGet(this, _Measurement_value, "f"))}${__classPrivateFieldGet(this, _Measurement_unit, "f")}`;
+            return `${(0, toPlainDecimal_1.toPlainDecimal)(__classPrivateFieldGet(this, _Measurement_value, "f"))}${__classPrivateFieldGet(this, _Measurement_unit, "f")}`;
         }
         toString() {
             return this.css();
@@ -156,18 +135,20 @@ const createCoreApi = (errorStore) => {
             return __classPrivateFieldGet(this, _Measurement_instances, "m", _Measurement_clone).call(this, next);
         }
         multiply(factor) {
-            if (factor === 1)
+            const numericFactor = (0, scalar_1.toNumber)(factor);
+            if (numericFactor === 1)
                 return this;
-            if (factor === 0)
+            if (numericFactor === 0)
                 return new _a(0, __classPrivateFieldGet(this, _Measurement_unit, "f"));
-            if (factor === -1)
+            if (numericFactor === -1)
                 return new _a(-__classPrivateFieldGet(this, _Measurement_value, "f"), __classPrivateFieldGet(this, _Measurement_unit, "f"));
-            return __classPrivateFieldGet(this, _Measurement_instances, "m", _Measurement_clone).call(this, __classPrivateFieldGet(this, _Measurement_value, "f") * factor);
+            return __classPrivateFieldGet(this, _Measurement_instances, "m", _Measurement_clone).call(this, __classPrivateFieldGet(this, _Measurement_value, "f") * numericFactor);
         }
         divide(divisor) {
-            if (divisor === 1)
+            const numericDivisor = (0, scalar_1.toNumber)(divisor);
+            if (numericDivisor === 1)
                 return this;
-            if (divisor === 0) {
+            if (numericDivisor === 0) {
                 throwMeasurementMethodError({
                     operation: 'css-calipers.Measurement.divide',
                     caller: this,
@@ -176,7 +157,7 @@ const createCoreApi = (errorStore) => {
                     details: { code: 'CALIPERS_E_DIVIDE_BY_ZERO' },
                 });
             }
-            const result = __classPrivateFieldGet(this, _Measurement_value, "f") / divisor;
+            const result = __classPrivateFieldGet(this, _Measurement_value, "f") / numericDivisor;
             if (!Number.isFinite(result)) {
                 throwMeasurementMethodError({
                     operation: 'css-calipers.Measurement.divide',
@@ -198,6 +179,8 @@ const createCoreApi = (errorStore) => {
             return shouldNegate ? __classPrivateFieldGet(this, _Measurement_instances, "m", _Measurement_clone).call(this, -__classPrivateFieldGet(this, _Measurement_value, "f")) : this;
         }
         absolute() {
+            // Math.abs is always >= 0, so the result is hardened to NonNegativeMeasurement
+            // (the governing rule: a runtime restriction must also harden the type).
             return __classPrivateFieldGet(this, _Measurement_instances, "m", _Measurement_clone).call(this, Math.abs(__classPrivateFieldGet(this, _Measurement_value, "f")));
         }
         round(precision = 0) {
@@ -221,7 +204,10 @@ const createCoreApi = (errorStore) => {
                 throwMeasurementMethodError({
                     operation: 'css-calipers.Measurement.clamp',
                     caller: this,
-                    params: [min, max],
+                    params: [
+                        min,
+                        max,
+                    ],
                     message: 'clamp: expected finite bounds',
                     details: { code: 'CALIPERS_E_CLAMP_NONFINITE_BOUNDS' },
                 });
@@ -230,7 +216,10 @@ const createCoreApi = (errorStore) => {
                 throwMeasurementMethodError({
                     operation: 'css-calipers.Measurement.clamp',
                     caller: this,
-                    params: [min, max],
+                    params: [
+                        min,
+                        max,
+                    ],
                     message: `clamp: min (${min.css()}) must be <= max (${max.css()})`,
                     details: { code: 'CALIPERS_E_CLAMP_INVALID_RANGE' },
                 });
@@ -302,7 +291,11 @@ const createCoreApi = (errorStore) => {
             if (!guard(value)) {
                 throwHelperError({
                     operation: 'css-calipers.makeUnitAssert',
-                    params: isMeasurement(value) ? [value] : [],
+                    params: isMeasurement(value)
+                        ? [
+                            value,
+                        ]
+                        : [],
                     message: `Expected unit "${helper.unit}".`,
                     context,
                     details: { code: 'CALIPERS_E_ASSERT_UNIT' },
@@ -336,6 +329,74 @@ const createCoreApi = (errorStore) => {
             });
         }
     };
+    // Value-constraint refinements. One factory builds the quartet (is / ensure / check /
+    // hardenWith) from a numeric predicate and narrows to a constraint brand. The brand is
+    // additive over `IMeasurement` and is dropped by arithmetic (which can cross a bound),
+    // so a derived result must be re-checked. `nonNegative` / `nonPositive` / `inRange(...)`
+    // are the built-ins.
+    const makeMeasurementRefinement = (spec) => {
+        const is = (measurement) => spec.predicate(measurement.getValue());
+        const ensure = (measurement, context) => {
+            if (!is(measurement)) {
+                throwHelperError({
+                    operation: 'css-calipers.refinement.ensure',
+                    params: [
+                        measurement,
+                    ],
+                    message: spec.message(measurement),
+                    context,
+                    details: { code: 'CALIPERS_E_CONSTRAINT' },
+                });
+            }
+            // A negated generic type-guard does not narrow the fall-through to `M & B`, so the
+            // brand cast is necessary here (the runtime check above guarantees it holds).
+            return measurement;
+        };
+        const check = (measurement) => is(measurement)
+            ? { ok: true, value: measurement }
+            : {
+                ok: false,
+                value: measurement,
+                error: spec.message(measurement),
+            };
+        const hardenWith = (measurement, fallback) => {
+            if (is(measurement))
+                return measurement;
+            if (fallback !== undefined)
+                return fallback;
+            const { defaultFallback } = spec;
+            if (defaultFallback !== undefined) {
+                return createMeasurement(defaultFallback, measurement.getUnit());
+            }
+            return throwHelperError({
+                operation: 'css-calipers.refinement.hardenWith',
+                params: [
+                    measurement,
+                ],
+                message: 'no fallback provided and this refinement has no default fallback',
+                details: { code: 'CALIPERS_E_CONSTRAINT' },
+            });
+        };
+        return { is, ensure, check, hardenWith };
+    };
+    const nonNegative = makeMeasurementRefinement({
+        predicate: (value) => value >= 0,
+        message: (measurement) => `expected a measurement >= 0 (got ${measurement.css()})`,
+        defaultFallback: 0,
+    });
+    const nonPositive = makeMeasurementRefinement({
+        predicate: (value) => value <= 0,
+        message: (measurement) => `expected a measurement <= 0 (got ${measurement.css()})`,
+        defaultFallback: 0,
+    });
+    const inRange = (min, max) => {
+        assertCondition(min <= max, `inRange: min (${min}) must be <= max (${max})`);
+        return makeMeasurementRefinement({
+            predicate: (value) => value >= min && value <= max,
+            message: (measurement) => `expected a measurement in [${min}, ${max}] (got ${measurement.css()})`,
+            defaultFallback: min,
+        });
+    };
     return {
         m,
         isMeasurement,
@@ -350,6 +411,10 @@ const createCoreApi = (errorStore) => {
         hasCssMethod,
         assertUnit,
         assertCondition,
+        makeMeasurementRefinement,
+        nonNegative,
+        nonPositive,
+        inRange,
         getErrorConfig: errorStore.getErrorConfig,
         setErrorConfig: errorStore.setErrorConfig,
     };

package/dist/cjs/internal/errors.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.throwHelperError = exports.throwMeasurementMethodError = exports.createErrorHelpers = exports.getErrorConfig = exports.setErrorConfig = exports.createErrorConfigStore = void 0;
 const DEFAULT_ERROR_CONFIG = {
-    stackHints: "auto",
+    stackHints: 'auto',
 };
 let errorConfig = { ...DEFAULT_ERROR_CONFIG };
 const createErrorConfigStore = (initial = {}) => {
@@ -51,18 +51,17 @@ const createErrorHelpers = (store) => {
 exports.createErrorHelpers = createErrorHelpers;
 const isProductionEnv = () => {
     var _a;
-    if (typeof globalThis === "undefined")
+    if (typeof globalThis === 'undefined')
         return false;
-    const maybeProcess = globalThis
-        .process;
-    return ((_a = maybeProcess === null || maybeProcess === void 0 ? void 0 : maybeProcess.env) === null || _a === void 0 ? void 0 : _a.NODE_ENV) === "production";
+    const maybeProcess = globalThis.process;
+    return ((_a = maybeProcess === null || maybeProcess === void 0 ? void 0 : maybeProcess.env) === null || _a === void 0 ? void 0 : _a.NODE_ENV) === 'production';
 };
 const shouldIncludeStackHint = (override, config = errorConfig) => {
     if (override === false)
         return false;
-    if (config.stackHints === "off")
+    if (config.stackHints === 'off')
         return false;
-    if (config.stackHints === "on")
+    if (config.stackHints === 'on')
         return true;
     if (override === true)
         return !isProductionEnv();
@@ -70,7 +69,7 @@ const shouldIncludeStackHint = (override, config = errorConfig) => {
 };
 const formatDetailBlock = (details) => {
     if (!details)
-        return "";
+        return '';
     const parts = [];
     if (details.code)
         parts.push(`code=${details.code}`);
@@ -80,7 +79,7 @@ const formatDetailBlock = (details) => {
         parts.push(`inputs=${details.inputSummary}`);
     if (details.stackHint)
         parts.push(`stack=${details.stackHint}`);
-    return parts.length > 0 ? ` [${parts.join(" | ")}]` : "";
+    return parts.length > 0 ? ` [${parts.join(' | ')}]` : '';
 };
 const formatErrorMessage = (operation, message, context, details) => {
     const core = `${operation}: ${message}`;
@@ -92,17 +91,17 @@ const extractStackHint = (stack) => {
     if (!stack)
         return undefined;
     const lines = stack
-        .split("\n")
+        .split('\n')
         .map((line) => line.trim())
         .filter(Boolean)
         .slice(1);
     if (lines.length === 0)
         return undefined;
-    const filtered = lines.filter((line) => !line.includes("/src/internal/errors") &&
-        !line.includes("throwHelperError") &&
-        !line.includes("throwMeasurementMethodError"));
+    const filtered = lines.filter((line) => !line.includes('/src/internal/errors') &&
+        !line.includes('throwHelperError') &&
+        !line.includes('throwMeasurementMethodError'));
     const hint = (_a = filtered[0]) !== null && _a !== void 0 ? _a : lines[0];
-    return hint.replace(/^at\s+/, "");
+    return hint.replace(/^at\s+/, '');
 };
 /** Throw an Error for a Measurement instance method using a structured context. */
 const throwMeasurementMethodError = (ctx) => {

package/dist/cjs/internal/toPlainDecimal.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPlainDecimal = void 0;
+// JS stringifies numbers in exponential form once the magnitude is >= 1e21 or
+// < 1e-6 (e.g. "1e+21", "1e-7"). CSS output must never contain that, so we
+// expand the exponent into a plain decimal by shifting the decimal point on the
+// digit string. This is string manipulation on the same digits, so it does not
+// re-introduce floating-point error. Shared by the measurement core and the
+// scalar (float / integer) primitives so every `.css()` renders the same way.
+const toPlainDecimal = (value) => {
+    const text = `${value}`;
+    if (!text.includes('e') && !text.includes('E')) {
+        return text;
+    }
+    const [mantissa, exponentText,] = text.toLowerCase().split('e');
+    const exponent = Number(exponentText);
+    const negative = mantissa.startsWith('-');
+    const unsigned = negative ? mantissa.slice(1) : mantissa;
+    const [intDigits, fracDigits = '',] = unsigned.split('.');
+    const digits = intDigits + fracDigits;
+    const pointFromLeft = intDigits.length + exponent;
+    const sign = negative ? '-' : '';
+    if (pointFromLeft <= 0) {
+        return `${sign}0.${'0'.repeat(-pointFromLeft)}${digits}`;
+    }
+    if (pointFromLeft >= digits.length) {
+        return `${sign}${digits}${'0'.repeat(pointFromLeft - digits.length)}`;
+    }
+    return `${sign}${digits.slice(0, pointFromLeft)}.${digits.slice(pointFromLeft)}`;
+};
+exports.toPlainDecimal = toPlainDecimal;

package/dist/cjs/measurements.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// The COLOUR-FREE measurement surface. This barrel re-exports everything the
+// root entry does EXCEPT the colour value primitive, so a consumer who imports
+// `@css-bookends/css-calipers/measurements` gets `m()` / `r()` / `i()` / `f()`,
+// the refinements, and the unit helpers, with NO transitive dependency on
+// `./color` (and therefore no `culori` in the graph).
+//
+// MUST NOT import `./color` (directly or transitively). The colour surface lives
+// at the `./color` subpath and is opt-in only.
+__exportStar(require("./core"), exports);
+// The bare default-instance helpers (`m`, refinements, unit-helper builders,
+// error-config accessors) assembled via `createCalipers()` at its defaults.
+__exportStar(require("./default"), exports);
+__exportStar(require("./units/absolute"), exports);
+__exportStar(require("./units/angle"), exports);
+__exportStar(require("./units/container"), exports);
+__exportStar(require("./units/font-relative"), exports);
+__exportStar(require("./units/frequency"), exports);
+__exportStar(require("./units/grid"), exports);
+__exportStar(require("./units/percent"), exports);
+__exportStar(require("./units/resolution"), exports);
+__exportStar(require("./units/time"), exports);
+__exportStar(require("./units/viewport"), exports);
+__exportStar(require("./units/viewport-dynamic"), exports);
+__exportStar(require("./units/viewport-large"), exports);
+__exportStar(require("./units/viewport-small"), exports);