@dicebear/core 10.0.0-rc.4 → 10.0.0

package/README.md

@@ -27,7 +27,8 @@ Playground, your next avatar is always just a stone's throw away!
 
 ## Sponsors
 
-Advertisement: Many thanks to our sponsors who provide us with free or discounted products.
+Advertisement: Many thanks to our sponsors who provide us with free or
+discounted products.
 
 <a href="https://bunny.net/" target="_blank" rel="noopener noreferrer">
     <picture>

package/lib/Options.d.ts

@@ -1,3 +1,4 @@
+import type { Range } from './StyleDefinition.js';
 import type { StyleOptions, StyleOptionsFlipValue, StyleOptionsColorFillValue } from './StyleOptions.js';
 /**
  * Validates the raw user-supplied options and exposes them through typed
@@ -19,18 +20,17 @@ export declare class Options<D = unknown> {
     flip(): readonly StyleOptionsFlipValue[];
     fontFamily(): readonly string[];
     fontWeight(): readonly number[];
-    scale(): readonly number[];
-    borderRadius(): readonly number[];
-    rotate(): readonly number[];
-    translateX(): readonly number[];
-    translateY(): readonly number[];
+    scale(): Range | undefined;
+    borderRadius(): Range | undefined;
+    rotate(): Range | undefined;
+    translateX(): Range | undefined;
+    translateY(): Range | undefined;
     /**
-     * Returns the user-set variant constraint for `name`:
-     * - `undefined` when the user did not set `${name}Variant`,
-     * - `string[]` when the user gave a string or string list (each weighted 1),
-     * - `Record<string, number>` when the user gave a weighted map.
+     * Returns the user-set variant constraint for `name` as a weighted map, or
+     * `undefined` when `${name}Variant` is unset. A bare string or string list
+     * is normalized to a map with each entry weighted `1`.
      */
-    componentVariant(name: string): readonly string[] | Readonly<Record<string, number>> | undefined;
+    componentVariant(name: string): Readonly<Record<string, number>> | undefined;
     componentProbability(name: string): number | undefined;
     /**
      * Asymmetric on purpose: returns `undefined` (rather than `[]`) when
@@ -39,6 +39,6 @@ export declare class Options<D = unknown> {
      */
     color(name: string): readonly string[] | undefined;
     colorFill(name: string): readonly StyleOptionsColorFillValue[];
-    colorAngle(name: string): readonly number[];
-    colorFillStops(name: string): readonly number[];
+    colorAngle(name: string): Range | undefined;
+    colorFillStops(name: string): Range | undefined;
 }

package/lib/Options.js

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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 _Options_instances, _Options_data, _Options_dynamic, _Options_asArray;
+var _Options_instances, _Options_data, _Options_dynamic, _Options_asArray, _Options_toRange;
 import { OptionsValidator } from './Validator/OptionsValidator.js';
 /**
  * Validates the raw user-supplied options and exposes them through typed
@@ -50,33 +50,35 @@ export class Options {
         return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_data, "f").fontWeight);
     }
     scale() {
-        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_data, "f").scale);
+        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_toRange).call(this, __classPrivateFieldGet(this, _Options_data, "f").scale);
     }
     borderRadius() {
-        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_data, "f").borderRadius);
+        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_toRange).call(this, __classPrivateFieldGet(this, _Options_data, "f").borderRadius);
     }
     rotate() {
-        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_data, "f").rotate);
+        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_toRange).call(this, __classPrivateFieldGet(this, _Options_data, "f").rotate);
     }
     translateX() {
-        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_data, "f").translateX);
+        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_toRange).call(this, __classPrivateFieldGet(this, _Options_data, "f").translateX);
     }
     translateY() {
-        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_data, "f").translateY);
+        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_toRange).call(this, __classPrivateFieldGet(this, _Options_data, "f").translateY);
     }
     /**
-     * Returns the user-set variant constraint for `name`:
-     * - `undefined` when the user did not set `${name}Variant`,
-     * - `string[]` when the user gave a string or string list (each weighted 1),
-     * - `Record<string, number>` when the user gave a weighted map.
+     * Returns the user-set variant constraint for `name` as a weighted map, or
+     * `undefined` when `${name}Variant` is unset. A bare string or string list
+     * is normalized to a map with each entry weighted `1`.
      */
     componentVariant(name) {
         const raw = __classPrivateFieldGet(this, _Options_instances, "m", _Options_dynamic).call(this, `${name}Variant`);
         if (raw === undefined) {
             return undefined;
         }
-        if (typeof raw === 'string' || Array.isArray(raw)) {
-            return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, raw);
+        if (typeof raw === 'string') {
+            return { [raw]: 1 };
+        }
+        if (Array.isArray(raw)) {
+            return Object.fromEntries(raw.map((v) => [v, 1]));
         }
         return raw;
     }
@@ -98,10 +100,10 @@ export class Options {
         return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_instances, "m", _Options_dynamic).call(this, `${name}ColorFill`));
     }
     colorAngle(name) {
-        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_instances, "m", _Options_dynamic).call(this, `${name}ColorAngle`));
+        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_toRange).call(this, __classPrivateFieldGet(this, _Options_instances, "m", _Options_dynamic).call(this, `${name}ColorAngle`));
     }
     colorFillStops(name) {
-        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_asArray).call(this, __classPrivateFieldGet(this, _Options_instances, "m", _Options_dynamic).call(this, `${name}ColorFillStops`));
+        return __classPrivateFieldGet(this, _Options_instances, "m", _Options_toRange).call(this, __classPrivateFieldGet(this, _Options_instances, "m", _Options_dynamic).call(this, `${name}ColorFillStops`));
     }
 }
 _Options_data = new WeakMap(), _Options_instances = new WeakSet(), _Options_dynamic = function _Options_dynamic(key) {
@@ -114,4 +116,12 @@ _Options_data = new WeakMap(), _Options_instances = new WeakSet(), _Options_dyna
         return value;
     }
     return [value];
+}, _Options_toRange = function _Options_toRange(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === 'number') {
+        return { min: value, max: value };
+    }
+    return { min: value[0], max: value[1] };
 };

package/lib/OptionsDescriptor.d.ts

@@ -21,6 +21,7 @@ interface EnumField {
 interface ColorField {
     readonly type: 'color';
     readonly list?: true;
+    readonly contrastTo?: string;
 }
 interface RangeField {
     readonly type: 'range';

package/lib/OptionsDescriptor.js

@@ -63,7 +63,12 @@ _a = OptionsDescriptor, _OptionsDescriptor_descriptor = new WeakMap(), _OptionsD
         result[`${name}Probability`] = { type: 'number', min: 0, max: 100 };
     }
     for (const name of [...__classPrivateFieldGet(this, _OptionsDescriptor_style, "f").colors().keys(), 'background']) {
-        result[`${name}Color`] = { type: 'color', list: true };
+        const contrastTo = __classPrivateFieldGet(this, _OptionsDescriptor_style, "f").colors().get(name)?.contrastTo();
+        result[`${name}Color`] = {
+            type: 'color',
+            list: true,
+            ...(contrastTo ? { contrastTo } : {}),
+        };
         result[`${name}ColorFill`] = {
             type: 'enum',
             values: ['solid', 'linear', 'radial'],

package/lib/Prng/Mulberry32.js

@@ -36,7 +36,7 @@ export class Mulberry32 {
         const z = (__classPrivateFieldSet(this, _Mulberry32_state, (__classPrivateFieldGet(this, _Mulberry32_state, "f") + 0x6d2b79f5) | 0, "f"));
         let t = Math.imul(z ^ (z >>> 15), z | 1);
         t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0);
+        return (t ^ (t >>> 14)) >>> 0;
     }
     /**
      * Advances the state and returns the next value in `[0, 1)`.

package/lib/Prng.d.ts

@@ -1,3 +1,4 @@
+import type { Range } from './StyleDefinition.js';
 /**
  * Key-based pseudorandom number generator.
  *
@@ -10,32 +11,41 @@ export declare class Prng {
     constructor(seed: string);
     /**
      * Picks a single item from `items` deterministically. Returns `undefined`
-     * for an empty list. Items are sorted by their string representation
-     * before picking so that input order does not affect the result.
+     * for an empty list. Duplicate values (by string representation) are
+     * collapsed before picking so that input order and duplication do not
+     * affect the result.
      */
     pick<T>(key: string, items: readonly T[]): T | undefined;
     /**
-     * Picks an item from `entries` proportional to its weight. When all weights
+     * Picks a key from `weights` proportional to its weight. When all weights
      * are zero, falls back to an unweighted {@link pick}. Returns `undefined`
-     * for an empty list.
+     * for an empty map.
      */
-    weightedPick<T>(key: string, entries: readonly (readonly [T, number])[]): T | undefined;
+    weightedPick(key: string, weights: Readonly<Record<string, number>>): string | undefined;
     /**
      * Returns `true` with the given probability (0–100, default 50).
      */
     bool(key: string, likelihood?: number): boolean;
     /**
-     * Returns a deterministic float in the closed range `[min(values), max(values)]`,
-     * rounded to four decimal places. Returns `undefined` for an empty list.
+     * Returns a deterministic float in `range`, rounded to four decimal places.
+     * With `range.step > 0`, the result is drawn uniformly from
+     * `{ min + i*step | 0 ≤ i ≤ floor((max - min) / step) }`, so both endpoints
+     * of an evenly-divisible range are equally likely. Non-positive or absent
+     * step means continuous. `min`/`max` are sorted internally, so a reversed
+     * pair is tolerated.
      */
-    float(key: string, values: readonly number[]): number | undefined;
+    float(key: string, range: Range): number;
     /**
-     * Returns a deterministic integer in the closed range
-     * `[min(values), max(values)]`. Returns `undefined` for an empty list.
+     * Returns a deterministic integer in `range`. `min`/`max` are sorted
+     * internally, so a reversed pair is tolerated. `range.step` is accepted
+     * for symmetry with {@link float} but ignored — integers already step by 1.
      */
-    integer(key: string, values: readonly number[]): number | undefined;
+    integer(key: string, range: Range): number;
     /**
-     * Fisher-Yates shuffle with chained Mulberry32 state.
+     * Fisher-Yates shuffle with chained Mulberry32 state. Duplicate values
+     * (by string representation) are collapsed before shuffling, so a
+     * caller's slice off the front cannot accidentally produce a repeated
+     * value.
      */
     shuffle<T>(key: string, items: readonly T[]): T[];
     /**

package/lib/Prng.js

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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 _Prng_instances, _Prng_seed, _Prng_compareByCodePoint;
+var _Prng_instances, _Prng_seed, _Prng_uniqueByCodePoint, _Prng_compareByCodePoint;
 import { Fnv1a } from './Prng/Fnv1a.js';
 import { Mulberry32 } from './Prng/Mulberry32.js';
 /**
@@ -27,8 +27,9 @@ export class Prng {
     }
     /**
      * Picks a single item from `items` deterministically. Returns `undefined`
-     * for an empty list. Items are sorted by their string representation
-     * before picking so that input order does not affect the result.
+     * for an empty list. Duplicate values (by string representation) are
+     * collapsed before picking so that input order and duplication do not
+     * affect the result.
      */
     pick(key, items) {
         if (items.length === 0) {
@@ -37,33 +38,41 @@ export class Prng {
         if (items.length === 1) {
             return items[0];
         }
-        const sorted = Array.from(items).sort(__classPrivateFieldGet(this, _Prng_instances, "m", _Prng_compareByCodePoint));
+        const unique = __classPrivateFieldGet(this, _Prng_instances, "m", _Prng_uniqueByCodePoint).call(this, items);
+        if (unique.length === 1) {
+            return unique[0];
+        }
+        const sorted = unique.sort(__classPrivateFieldGet(this, _Prng_instances, "m", _Prng_compareByCodePoint));
         const index = Math.floor(this.getValue(key) * sorted.length);
         return sorted[index];
     }
     /**
-     * Picks an item from `entries` proportional to its weight. When all weights
+     * Picks a key from `weights` proportional to its weight. When all weights
      * are zero, falls back to an unweighted {@link pick}. Returns `undefined`
-     * for an empty list.
+     * for an empty map.
      */
-    weightedPick(key, entries) {
-        if (entries.length === 0) {
+    weightedPick(key, weights) {
+        const keys = Object.keys(weights);
+        if (keys.length === 0) {
             return undefined;
         }
-        const sorted = Array.from(entries).sort((a, b) => __classPrivateFieldGet(this, _Prng_instances, "m", _Prng_compareByCodePoint).call(this, a[0], b[0]));
-        const totalWeight = sorted.reduce((sum, e) => sum + e[1], 0);
+        if (keys.length === 1) {
+            return keys[0];
+        }
+        const sorted = keys.sort(__classPrivateFieldGet(this, _Prng_instances, "m", _Prng_compareByCodePoint));
+        const totalWeight = sorted.reduce((sum, k) => sum + weights[k], 0);
         if (totalWeight === 0) {
-            return this.pick(key, sorted.map((e) => e[0]));
+            return this.pick(key, sorted);
         }
         const threshold = this.getValue(key) * totalWeight;
         let cumulative = 0;
-        for (const [item, weight] of sorted) {
-            cumulative += weight;
+        for (const k of sorted) {
+            cumulative += weights[k];
             if (threshold < cumulative) {
-                return item;
+                return k;
             }
         }
-        return sorted[sorted.length - 1][0];
+        return sorted[sorted.length - 1];
     }
     /**
      * Returns `true` with the given probability (0–100, default 50).
@@ -72,34 +81,49 @@ export class Prng {
         return this.getValue(key) * 100 < likelihood;
     }
     /**
-     * Returns a deterministic float in the closed range `[min(values), max(values)]`,
-     * rounded to four decimal places. Returns `undefined` for an empty list.
+     * Returns a deterministic float in `range`, rounded to four decimal places.
+     * With `range.step > 0`, the result is drawn uniformly from
+     * `{ min + i*step | 0 ≤ i ≤ floor((max - min) / step) }`, so both endpoints
+     * of an evenly-divisible range are equally likely. Non-positive or absent
+     * step means continuous. `min`/`max` are sorted internally, so a reversed
+     * pair is tolerated.
      */
-    float(key, values) {
-        if (values.length === 0) {
-            return undefined;
+    float(key, range) {
+        const min = Math.min(range.min, range.max);
+        const max = Math.max(range.min, range.max);
+        const step = range.step ?? 0;
+        let value;
+        if (step > 0) {
+            const buckets = Math.floor((max - min) / step) + 1;
+            const i = Math.floor(this.getValue(key) * buckets);
+            value = min + i * step;
         }
-        const min = Math.min(...values);
-        const max = Math.max(...values);
-        return Math.round((min + this.getValue(key) * (max - min)) * 10000) / 10000;
+        else {
+            value = min + this.getValue(key) * (max - min);
+        }
+        return Math.round(value * 10000) / 10000;
     }
     /**
-     * Returns a deterministic integer in the closed range
-     * `[min(values), max(values)]`. Returns `undefined` for an empty list.
+     * Returns a deterministic integer in `range`. `min`/`max` are sorted
+     * internally, so a reversed pair is tolerated. `range.step` is accepted
+     * for symmetry with {@link float} but ignored — integers already step by 1.
      */
-    integer(key, values) {
-        if (values.length === 0) {
-            return undefined;
-        }
-        const min = Math.min(...values);
-        const max = Math.max(...values);
+    integer(key, range) {
+        const min = Math.min(range.min, range.max);
+        const max = Math.max(range.min, range.max);
         return Math.floor(this.getValue(key) * (max - min + 1)) + min;
     }
     /**
-     * Fisher-Yates shuffle with chained Mulberry32 state.
+     * Fisher-Yates shuffle with chained Mulberry32 state. Duplicate values
+     * (by string representation) are collapsed before shuffling, so a
+     * caller's slice off the front cannot accidentally produce a repeated
+     * value.
      */
     shuffle(key, items) {
-        const result = Array.from(items).sort(__classPrivateFieldGet(this, _Prng_instances, "m", _Prng_compareByCodePoint));
+        if (items.length <= 1) {
+            return [...items];
+        }
+        const result = __classPrivateFieldGet(this, _Prng_instances, "m", _Prng_uniqueByCodePoint).call(this, items).sort(__classPrivateFieldGet(this, _Prng_instances, "m", _Prng_compareByCodePoint));
         const prng = new Mulberry32(Fnv1a.hash(__classPrivateFieldGet(this, _Prng_seed, "f") + ':' + key));
         for (let i = result.length - 1; i > 0; i--) {
             const j = Math.floor(prng.nextFloat() * (i + 1));
@@ -117,7 +141,18 @@ export class Prng {
         return new Mulberry32(Fnv1a.hash(__classPrivateFieldGet(this, _Prng_seed, "f") + ':' + key)).nextFloat();
     }
 }
-_Prng_seed = new WeakMap(), _Prng_instances = new WeakSet(), _Prng_compareByCodePoint = function _Prng_compareByCodePoint(a, b) {
+_Prng_seed = new WeakMap(), _Prng_instances = new WeakSet(), _Prng_uniqueByCodePoint = function _Prng_uniqueByCodePoint(items, keyFn = String) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const repr = keyFn(item);
+        if (!seen.has(repr)) {
+            seen.add(repr);
+            result.push(item);
+        }
+    }
+    return result;
+}, _Prng_compareByCodePoint = function _Prng_compareByCodePoint(a, b) {
     const sa = String(a);
     const sb = String(b);
     if (sa < sb) {

package/lib/Renderer.js

@@ -208,8 +208,17 @@ _Renderer_style = new WeakMap(), _Renderer_resolver = new WeakMap(), _Renderer_d
         __classPrivateFieldGet(this, _Renderer_defs, "f").set(id, `<g id="${id}">${body}</g>`);
     }
     const transforms = __classPrivateFieldGet(this, _Renderer_instances, "m", _Renderer_buildTransforms).call(this, component);
-    const transformAttr = transforms.length > 0 ? ` transform="${transforms.join(' ')}"` : '';
-    return `<use${transformAttr} href="#${id}"/>`;
+    const userAttributes = element.attributes();
+    let mergedAttributes = userAttributes;
+    if (transforms.length > 0) {
+        const userTransform = userAttributes?.transform;
+        const allParts = typeof userTransform === 'string' && userTransform.length > 0
+            ? [userTransform, ...transforms]
+            : transforms;
+        mergedAttributes = { ...userAttributes, transform: allParts.join(' ') };
+    }
+    const attrs = __classPrivateFieldGet(this, _Renderer_instances, "m", _Renderer_renderAttributes).call(this, mergedAttributes);
+    return `<use${attrs} href="#${id}"/>`;
 }, _Renderer_buildTransforms = function _Renderer_buildTransforms(component) {
     const { rotate, translateX, translateY, scale } = __classPrivateFieldGet(this, _Renderer_resolver, "f").componentTransform(component.name());
     if (translateX === 0 && translateY === 0 && rotate === 0 && scale === 1) {

package/lib/Resolver.d.ts

@@ -5,8 +5,10 @@ import type { StyleOptionsFlipValue, StyleOptionsColorFillValue, StyleOptions }
  * Bundles the three inputs needed to derive any deterministic value for an
  * avatar — the {@link Style}, the validated user {@link Options}, and a
  * seeded {@link Prng} — and exposes them as named accessors. Each accessor
- * memoizes its result so that repeated calls cannot drift, and the memo
- * doubles as the snapshot returned by {@link resolved}.
+ * memoizes its result so that repeated calls cannot drift. The memo also
+ * serves as the informational snapshot returned by {@link resolved} — every
+ * value the resolver picks during one resolution lands there, except for
+ * the raw seed.
  */
 export declare class Resolver<D = unknown> {
     #private;
@@ -28,8 +30,9 @@ export declare class Resolver<D = unknown> {
      * as `${name}Variant` in the input data:
      *
      * - `undefined`: PRNG picks from all style variants using their weights.
-     * - `string` or `string[]`: PRNG picks from the given subset (weight 1 each).
-     * - `Record<string, number>`: PRNG picks using the provided weights.
+     * - otherwise: PRNG picks using the user-supplied weighted map (a bare
+     *   string or string list is normalized to weight `1` each in
+     *   {@link Options.componentVariant}).
      *
      * Only variants that exist in the style definition are considered.
      */
@@ -38,9 +41,10 @@ export declare class Resolver<D = unknown> {
     colorFill(name: string): StyleOptionsColorFillValue;
     colorAngle(name: string): number;
     /**
-     * Per-component transform values are render-time decorations derived per
-     * `<use>` reference, not user-input options that should round-trip. They
-     * are intentionally not memoized and so never appear in {@link resolved}.
+     * Picks the rotate/translateX/translateY/scale values for a single
+     * component. Memoized per `name`, so the four values land in
+     * {@link resolved} as `${name}Rotate` / `${name}TranslateX` /
+     * `${name}TranslateY` / `${name}Scale` for downstream introspection.
      */
     componentTransform(name: string): {
         rotate: number;
@@ -49,11 +53,16 @@ export declare class Resolver<D = unknown> {
         scale: number;
     };
     /**
-     * Returns every value that has been touched during this resolution. Only
-     * memoized entries are included; unset options remain `undefined` and
-     * disappear on `JSON.stringify()`. Per-component transform values from
-     * {@link componentTransform} and the user-supplied {@link seed} are
-     * intentionally not memoized and therefore do not appear in the snapshot.
+     * Returns an informational snapshot of every value the resolver picked.
+     * Includes top-level options (scale/rotate/translate/…), per-component
+     * variants/probabilities/colors, and per-component transform picks. The
+     * raw seed is deliberately excluded.
+     *
+     * The snapshot is NOT a round-trip-able options object — extra keys like
+     * `${name}Rotate` are not part of {@link StyleOptions} and feeding the
+     * snapshot back into a new {@link Avatar} is not supported. Callers that
+     * need to reproduce an avatar should pass the original `seed` and
+     * user-supplied options.
      *
      * The returned object aliases the internal cache; callers that need
      * isolation (e.g. {@link Avatar.toJSON}) clone it themselves.