@illlustrations/avatars 1.0.0 → 1.1.0

package/AI.md

@@ -46,7 +46,10 @@ fromJSON(croods, saved).toString();
    `` `avatar-${i}-${id.replace(/[^A-Za-z0-9_-]/g, '')}` ``. Seed with the raw ID.
    `<Avatar>` and `toDataUri()` handle IDs themselves.
 6. Colors: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `transparent`, or
-   `original` for color roles. Named CSS colors throw. `size` must be above 0 and at most 8192.
+   `original` for color roles. Named CSS colors throw.
+   To recolor something that isn't a role (bag, mouth, drool, accents), use
+   `palette` with a key from `croods.palette` or `avatar.sourceColors()`; never
+   guess artwork hex values. Roles win over the palette. `size` must be above 0 and at most 8192.
 7. `<Avatar>` is a client component (`'use client'`). In a React Server
    Component, render it as-is or use `createAvatar(...).toDataUri()` in an `<img>`.
 8. The artwork is CC BY 4.0: credit "Croods by illlustrations" once per app or
@@ -59,9 +62,10 @@ fromJSON(croods, saved).toString();
 | --- | --- |
 | `seed` | Any string. Omit for the default character. |
 | `selections` | Partial `{ head, face, upperBody, facialHair, accessories }` |
-| `colors` | Partial `{ hair, skin, clothing, stroke }` |
+| `colors` | Partial `{ hair, skin, clothing, stroke }`; each one color or (1.1+) a list the seed picks from |
 | `theme` | `'ink'` (blue and white) or `'neutral'` (black and white) |
-| `background` | Hex or `'transparent'` (default) |
+| `palette` | 1.1+: `{ '#FF4B33': '#254CE9' }` swaps any artwork color; keys from `croods.palette` |
+| `background` | Hex or `'transparent'` (default); 1.1+ also a list the seed picks from |
 | `shape` | `'square'` (default), `'rounded'`, `'circle'` |
 | `size` | Pixels. Core default 600, React default 64 |
 | `seedPool` | `'v1'` (default). Only for pinning seed results across versions |

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.1.0
+
+- `palette` option: swap any artwork color, matching the website builder, e.g.
+  `{ '#FF4B33': '#254CE9' }`. Roles still win; the palette wins over theme
+  accents; mask and clip coverage never change. Works in `createAvatar`,
+  `<Avatar>` and saved state.
+- `style.palette` lists every source color in a style; `avatar.sourceColors()`
+  lists the ones in the chosen parts.
+- Color lists: any role in `colors` and `background` accept a list, e.g.
+  `colors: { clothing: ['#254CE9', '#F76549'] }`; the seed picks one entry per
+  option. Saved state stores the resolved color.
+- Output without a palette or lists is byte-identical to 1.0.0.
+
 ## 1.0.0
 
 First public release of `@illlustrations/avatars`.

package/README.md

@@ -104,11 +104,12 @@ Seeded avatars never pick facial hair; pass `selections.facialHair` to opt in.
 | `seed` | String, including empty string. Omit for the default character. |
 | `seedPool` | Versioned selection pool, initially `v1`. |
 | `selections` | Partial `head`, `face`, `upperBody`, `facialHair`, `accessories` overrides. Face, facial hair and accessories support `none`. |
-| `colors` | Partial `hair`, `skin`, `clothing`, `stroke` overrides. Croods defaults to `original` for each role. |
-| `background` | Transparent by default. |
+| `colors` | Partial `hair`, `skin`, `clothing`, `stroke` overrides: one color or a list the seed picks from (1.1+). Croods defaults to `original` for each role. |
+| `background` | Transparent by default. One color or a list the seed picks from (1.1+). |
 | `size` | Positive number up to 8192; core defaults to 600, React to 64. |
 | `shape` | `square` (default), `rounded`, or `circle`. |
 | `theme` | Omit for original artwork. `ink` uses `#0040FC` and white; `neutral` uses black and white. Explicit `colors` override theme roles. |
+| `palette` | Since 1.1. Swap any artwork color, like the website builder: `{ '#FF4B33': '#254CE9' }`. Keys come from `croods.palette`. |
 
 Colors accept 3/4/6/8-digit hex, `transparent`, or `original` for color roles.
 Themes also recolor fixed accents, while preserving mask coverage and keeping
@@ -126,6 +127,47 @@ Inline React rendering uses `--avatar-hair`, `--avatar-skin`,
 literals. CSS overrides are presentation-only; use `colors` for a palette that
 also appears in saved state and downloads.
 
+## Color lists
+
+Any color role and `background` also take a list. The seed picks one entry, so
+each person keeps the same color and a team gets your brand mix:
+
+```tsx
+<Avatar assets={croods} seed={user.id}
+  colors={{ clothing: ['#254CE9', '#F76549', '#77E87B'], hair: ['original', '#272727'] }}
+  background={['#DDE5FF', '#FFE6D2', '#D4EDE2']} />
+```
+
+Each option picks independently (hash of seed + option name, mixed with
+MurmurHash3 fmix32; frozen from 1.1). Lists never change which parts a seed
+picks. Saved state stores the resolved color. Every entry is validated; lists
+hold 1 to 64 colors.
+
+## Palette (any artwork color)
+
+Roles cover hair, skin, clothing and outlines. `palette` reaches every other
+color too, such as the bag, mouth and drool accents:
+
+```ts
+croods.palette;                 // ['#000000', '#FF0000', '#FFFFFF', …] every source color
+avatar.sourceColors();          // the source colors in this avatar's parts
+
+createAvatar(croods, {
+  selections: { upperBody: 't-shirt-bag' },
+  palette: { '#FF4B33': '#254CE9', '#FF0000': '#1B1B1B' },
+});
+```
+
+- Keys are source colors from `style.palette` (`#RGB` or `#RRGGBB`, any case);
+  unknown colors throw. Values are hex or `transparent`.
+- A palette entry changes every use of that color. `#FFFFFF` is both skin and
+  eye whites, so use `colors.skin` to change skin alone.
+- Explicit `colors` roles win over the palette; the palette wins over theme
+  accents. Mask and clip coverage never change.
+- Saved state includes the palette (canonical `#RRGGBB` keys) only when it is
+  non-empty, so states without one are unchanged from 1.0. Versions before
+  1.1 reject states that contain a palette.
+
 ## Stable state and geometry
 
 Every part carries its exact database avatar rectangle and effective layer

package/dist/core/index.d.ts

@@ -1,4 +1,4 @@
 import type { AvatarOptions, AvatarResult, AvatarStyle } from './types.js';
-export type { AvatarOptions, AvatarResult, AvatarState, AvatarStyle, ColorRole, Colors, RenderOptions, Selections, Shape, Slot, Theme } from './types.js';
+export type { AvatarOptions, AvatarResult, AvatarState, AvatarStyle, ColorChoice, ColorRole, Colors, Palette, RenderOptions, Selections, Shape, Slot, Theme } from './types.js';
 export declare function createAvatar(style: AvatarStyle, options?: AvatarOptions): AvatarResult;
 export declare function fromJSON(style: AvatarStyle, value: unknown): AvatarResult;

package/dist/core/index.js

@@ -1,5 +1,5 @@
-import { renderDocument } from '../internal/render.js';
-import { assertStyle, isColor, isRoleColor, validateSelections } from '../internal/style.js';
+import { renderDocument, usedSourceColors } from '../internal/render.js';
+import { assertStyle, isColor, isRoleColor, normalizePalette, validateSelections } from '../internal/style.js';
 import { colorRoles, slots } from './types.js';
 const own = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
 function record(value, label) {
@@ -20,11 +20,13 @@ function hash(seed) {
 }
 function validateState(style, state) {
     record(state, 'avatar state');
-    keys(state, ['schemaVersion', 'style', 'styleVersion', 'selections', 'colors', 'background', 'size', 'shape', 'theme'], 'state field');
+    keys(state, ['schemaVersion', 'style', 'styleVersion', 'selections', 'colors', 'palette', 'background', 'size', 'shape', 'theme'], 'state field');
     if (state.schemaVersion !== 1 || state.style !== style.id || state.styleVersion !== style.version)
         throw new Error('Avatar state schema or style version does not match');
     if (state.theme !== undefined && !['ink', 'neutral'].includes(state.theme))
         throw new Error('Unknown avatar theme');
+    if (state.palette !== undefined && Object.keys(normalizePalette(style, state.palette, true)).length === 0)
+        throw new Error('Saved palette must not be empty');
     record(state.selections, 'selections');
     keys(state.selections, slots, 'slot');
     validateSelections(style, state.selections);
@@ -40,10 +42,37 @@ function validateState(style, state) {
     if (!['square', 'rounded', 'circle'].includes(state.shape))
         throw new Error('Unknown avatar shape');
 }
+/**
+ * MurmurHash3 fmix32. FNV-1a's low bits depend only on the input's low bits, so
+ * small moduli would tie differently salted picks together. Frozen from 1.1.
+ * The v1 seed pool keeps plain FNV-1a so existing seeds never change.
+ */
+function mix(value) {
+    value ^= value >>> 16;
+    value = Math.imul(value, 0x85ebca6b);
+    value ^= value >>> 13;
+    value = Math.imul(value, 0xc2b2ae35);
+    return (value ^ (value >>> 16)) >>> 0;
+}
+/**
+ * A color option is one color or a list to choose from. The seed picks from a
+ * list (salted per option, so choices are independent); every entry is
+ * validated so a typo fails even when it is not picked.
+ */
+function pickColor(value, seed, salt, valid, label) {
+    if (!Array.isArray(value))
+        return value;
+    if (value.length === 0 || value.length > 64)
+        throw new Error(`${label} list must have 1 to 64 colors`);
+    for (const color of value)
+        if (!valid(color))
+            throw new Error(`Invalid ${label} in list: use a hex color, transparent${label === 'background' ? '' : ' or original'}`);
+    return value[mix(hash(`${seed}\u0000${salt}`)) % value.length];
+}
 export function createAvatar(style, options = {}) {
     assertStyle(style);
     record(options, 'options');
-    keys(options, ['seed', 'seedPool', 'selections', 'colors', 'background', 'size', 'shape', 'theme'], 'option');
+    keys(options, ['seed', 'seedPool', 'selections', 'colors', 'palette', 'background', 'size', 'shape', 'theme'], 'option');
     let selections = style.defaults.selections;
     if (options.seed !== undefined && typeof options.seed !== 'string')
         throw new Error('Seed must be a string');
@@ -62,12 +91,18 @@ export function createAvatar(style, options = {}) {
         record(options.colors, 'colors');
         keys(options.colors, colorRoles, 'color role');
     }
+    const seed = options.seed ?? '';
+    const colors = Object.fromEntries(Object.entries(options.colors ?? {}).map(([role, value]) => [role, pickColor(value, seed, `colors.${role}`, isRoleColor, `${role} color`)]));
+    const background = pickColor(options.background, seed, 'background', isColor, 'background');
+    const palette = options.palette === undefined ? {} : normalizePalette(style, options.palette);
     const state = {
         schemaVersion: 1, style: style.id, styleVersion: style.version,
         selections: { ...selections, ...options.selections },
-        colors: { ...style.defaults.colors, ...(options.theme ? { hair: options.theme === 'ink' ? '#0040FC' : '#000000', stroke: options.theme === 'ink' ? '#0040FC' : '#000000', skin: '#FFFFFF', clothing: '#FFFFFF' } : {}), ...options.colors },
+        colors: { ...style.defaults.colors, ...(options.theme ? { hair: options.theme === 'ink' ? '#0040FC' : '#000000', stroke: options.theme === 'ink' ? '#0040FC' : '#000000', skin: '#FFFFFF', clothing: '#FFFFFF' } : {}), ...colors },
         ...(options.theme === undefined ? {} : { theme: options.theme }),
-        background: options.background ?? 'transparent', size: options.size ?? 600, shape: options.shape ?? 'square',
+        // Omitted when empty, so states without a palette stay identical to 1.0.
+        ...(Object.keys(palette).length ? { palette } : {}),
+        background: background ?? 'transparent', size: options.size ?? 600, shape: options.shape ?? 'square',
     };
     validateState(style, state);
     return result(style, state);
@@ -84,5 +119,6 @@ function result(style, state) {
         toJSON: () => JSON.parse(JSON.stringify(state)),
         toString: (options = {}) => renderDocument(style, state, options),
         toDataUri: (options = {}) => `data:image/svg+xml,${encodeURIComponent(renderDocument(style, state, options))}`,
+        sourceColors: () => usedSourceColors(style, state),
     });
 }

package/dist/core/types.d.ts

@@ -6,18 +6,30 @@ export type Colors = Record<ColorRole, string>;
 export type Selections = Record<Slot, string>;
 export type Theme = 'ink' | 'neutral';
 export type Shape = 'square' | 'rounded' | 'circle';
+/**
+ * Source artwork color → replacement, like the website builder's palette.
+ * Keys are colors from `style.palette` (`#RGB` or `#RRGGBB`, any case); values
+ * are hex or `transparent`. Every use of a source color changes, including
+ * role paints left as `original`. Explicit `colors` roles win over the palette.
+ */
+export type Palette = Record<string, string>;
+/** One color, or a list the seed picks from (the same seed always gets the same entry). */
+export type ColorChoice = string | readonly string[];
 export interface AvatarOptions {
     theme?: Theme;
+    palette?: Palette;
     seed?: string;
     seedPool?: string;
     selections?: Partial<Selections>;
-    colors?: Partial<Colors>;
-    background?: string;
+    colors?: Partial<Record<ColorRole, ColorChoice>>;
+    background?: ColorChoice;
     size?: number;
     shape?: Shape;
 }
 export interface AvatarState {
     theme?: Theme;
+    /** Present only when non-empty. Keys are canonical `#RRGGBB`. */
+    palette?: Palette;
     schemaVersion: 1;
     style: string;
     styleVersion: string;
@@ -36,6 +48,8 @@ export interface AvatarResult {
     toString(options?: RenderOptions): string;
     toDataUri(options?: Omit<RenderOptions, 'idPrefix'>): string;
     toJSON(): AvatarState;
+    /** Source colors in this avatar's parts, as canonical `#RRGGBB`: the keys `palette` can change. */
+    sourceColors(): string[];
 }
 export interface Part {
     id: string;
@@ -79,5 +93,7 @@ declare const compiledStyle: unique symbol;
 /** Only use style objects shipped by the package's curated style entry points. */
 export interface AvatarStyle extends Readonly<StyleDefinition> {
     readonly [compiledStyle]: true;
+    /** Every source color in the style's artwork (canonical `#RRGGBB`), most used first. */
+    readonly palette: readonly string[];
 }
 export {};

package/dist/internal/paint.d.ts

@@ -0,0 +1,9 @@
+/** `#RGB`, `#RRGGBB`, `black` or `white` → uppercase `#RRGGBB`; anything else → undefined. */
+export declare function canonicalHex(value: string | undefined): string | undefined;
+/**
+ * Rewrite literal fill/stroke/stop-color paints outside mask and clip coverage.
+ * Role variables, url() references, none and transparent are never passed on.
+ */
+export declare function mapPaints(svg: string, map: (paint: string) => string): string;
+/** Canonical source colors in one compiled part, with how often each is painted. */
+export declare function sourceColorCounts(svg: string, counts?: Map<string, number>): Map<string, number>;

package/dist/internal/paint.js

@@ -0,0 +1,48 @@
+/** `#RGB`, `#RRGGBB`, `black` or `white` → uppercase `#RRGGBB`; anything else → undefined. */
+export function canonicalHex(value) {
+    if (value === undefined)
+        return undefined;
+    let color = value.trim().toUpperCase();
+    if (color === 'BLACK')
+        return '#000000';
+    if (color === 'WHITE')
+        return '#FFFFFF';
+    if (/^#[0-9A-F]{3}$/.test(color))
+        color = '#' + [...color.slice(1)].map(char => char + char).join('');
+    return /^#[0-9A-F]{6}$/.test(color) ? color : undefined;
+}
+/**
+ * Rewrite literal fill/stroke/stop-color paints outside mask and clip coverage.
+ * Role variables, url() references, none and transparent are never passed on.
+ */
+export function mapPaints(svg, map) {
+    let coverage = 0;
+    return svg.replace(/<[^>]+>/g, tag => {
+        if (/^<\/(?:mask|clipPath)\b/.test(tag)) {
+            coverage--;
+            return tag;
+        }
+        const protectedTag = /^<(?:mask|clipPath)\b/.test(tag);
+        if (protectedTag && !/\/>$/.test(tag))
+            coverage++;
+        if (coverage || protectedTag)
+            return tag;
+        return tag.replace(/(\s(?:fill|stroke|stop-color)=")([^"<>]*)(")/g, (match, start, paint, end) => {
+            if (/^(?:none|transparent|var\(|url\()/i.test(paint))
+                return match;
+            return `${start}${map(paint)}${end}`;
+        });
+    });
+}
+/** Canonical source colors in one compiled part, with how often each is painted. */
+export function sourceColorCounts(svg, counts = new Map()) {
+    const add = (paint) => {
+        const color = canonicalHex(paint);
+        if (color)
+            counts.set(color, (counts.get(color) ?? 0) + 1);
+        return paint;
+    };
+    // Role paints keep their original color as the variable fallback.
+    mapPaints(svg.replace(/(\s(?:fill|stroke|stop-color)=")var\(--avatar-(?:hair|skin|clothing|stroke),\s*([^)]*)\)(")/g, (_, start, original, end) => `${start}${original}${end}`), add);
+    return counts;
+}

package/dist/internal/render.d.ts

@@ -1,5 +1,7 @@
 import type { AvatarStyle, AvatarState, RenderOptions } from '../core/types.js';
 export declare const escapeXml: (value: string) => string;
+/** Canonical source colors used by the avatar's selected parts. */
+export declare function usedSourceColors(style: AvatarStyle, state: AvatarState): string[];
 /** Internal React renderer; the package export map only exposes the supported public API. */
 export declare function renderContents(style: AvatarStyle, state: AvatarState, idPrefix: string, cssVariables?: boolean): string;
 export declare function renderDocument(style: AvatarStyle, state: AvatarState, options: RenderOptions): string;

package/dist/internal/render.js

@@ -1,4 +1,5 @@
 import { slots } from '../core/types.js';
+import { canonicalHex, mapPaints, sourceColorCounts } from './paint.js';
 export const escapeXml = (value) => value.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[char]);
 function record(value, label) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -14,31 +15,38 @@ function prefix(value) {
         throw new Error('idPrefix must start with a letter and contain only letters, digits, underscores or hyphens');
     return value;
 }
-/** Recolor fixed accents while preserving mask/clip coverage and role variables. */
-function themeAccents(svg, ink) {
-    let coverage = 0;
-    return svg.replace(/<[^>]+>/g, tag => {
-        if (/^<\/(?:mask|clipPath)\b/.test(tag)) {
-            coverage--;
-            return tag;
-        }
-        const protectedTag = /^<(?:mask|clipPath)\b/.test(tag);
-        if (protectedTag && !/\/>$/.test(tag))
-            coverage++;
-        if (coverage || protectedTag)
-            return tag;
-        return tag.replace(/(\s(?:fill|stroke|stop-color)=")([^"<>]*)(")/g, (match, start, paint, end) => {
-            if (/^(?:none|transparent|var\(|url\()/i.test(paint))
-                return match;
-            const canonical = paint.toUpperCase();
-            // Dark neutral accents are linework; other fixed accents become paper.
-            const dark = canonical === 'BLACK' || /^#(?:000|000000|424242)$/.test(canonical);
-            if (!/^(?:#[0-9A-F]{3,8}|BLACK|WHITE)$/.test(canonical))
-                return match;
-            return `${start}${dark ? ink : '#FFFFFF'}${end}`;
-        });
+/**
+ * Recolor fixed paints: palette entries first, then theme accents. Mask/clip
+ * coverage and role variables are untouched (see mapPaints).
+ */
+function recolorFixed(svg, theme, palette) {
+    if (!theme && !palette)
+        return svg;
+    const ink = theme === 'ink' ? '#0040FC' : '#000000';
+    return mapPaints(svg, paint => {
+        const swap = palette?.[canonicalHex(paint) ?? ''];
+        if (swap)
+            return swap;
+        if (!theme)
+            return paint;
+        const canonical = paint.toUpperCase();
+        if (!/^(?:#[0-9A-F]{3,8}|BLACK|WHITE)$/.test(canonical))
+            return paint;
+        // Dark neutral accents are linework; other fixed accents become paper.
+        const dark = canonical === 'BLACK' || /^#(?:000|000000|424242)$/.test(canonical);
+        return dark ? ink : '#FFFFFF';
     });
 }
+/** Canonical source colors used by the avatar's selected parts. */
+export function usedSourceColors(style, state) {
+    const counts = new Map();
+    for (const slot of slots) {
+        const part = style.parts[slot].find(item => item.id === state.selections[slot]);
+        if (part)
+            sourceColorCounts(part.svg, counts);
+    }
+    return style.palette.filter(color => counts.has(color));
+}
 /** Internal React renderer; the package export map only exposes the supported public API. */
 export function renderContents(style, state, idPrefix, cssVariables = false) {
     const id = prefix(idPrefix);
@@ -48,9 +56,12 @@ export function renderContents(style, state, idPrefix, cssVariables = false) {
         const part = style.parts[slot].find(item => item.id === state.selections[slot]);
         return part ? [{ slot, part }] : [];
     }).sort((a, b) => a.part.zIndex - b.part.zIndex).map(({ slot, part }) => {
-        const source = state.theme ? themeAccents(part.svg, state.theme === 'ink' ? '#0040FC' : '#000000') : part.svg;
+        const source = recolorFixed(part.svg, state.theme, state.palette);
         const svg = source.replaceAll('__AVATAR_ID__', `${id}-${slot}-`).replace(/var\(--avatar-(hair|skin|clothing|stroke)(?:,\s*([^)]*))?\)/g, (_, role, original) => {
-            const color = state.colors[role] === 'original' ? (original ?? '#000000') : state.colors[role];
+            // Explicit role colors win; a role left as original follows the palette.
+            const color = state.colors[role] === 'original'
+                ? (state.palette?.[canonicalHex(original) ?? ''] ?? original ?? '#000000')
+                : state.colors[role];
             return cssVariables ? `var(--avatar-${role}, ${color})` : color;
         });
         const p = part.position;

package/dist/internal/style.d.ts

@@ -1,7 +1,9 @@
-import type { AvatarStyle, Selections, StyleDefinition } from '../core/types.js';
+import type { AvatarStyle, Palette, Selections, StyleDefinition } from '../core/types.js';
 export declare const isColor: (value: unknown) => value is string;
 export declare const isRoleColor: (value: unknown) => value is string;
 export declare function validateSelections(style: StyleDefinition, selections: Selections): void;
+/** Validate palette input and return it with canonical `#RRGGBB` keys. */
+export declare function normalizePalette(style: AvatarStyle, palette: unknown, strict?: boolean): Palette;
 /** Internal build output loader. Not a public arbitrary-SVG authoring API. */
 export declare function defineStyle(definition: StyleDefinition): AvatarStyle;
 export declare function assertStyle(style: AvatarStyle): void;

package/dist/internal/style.js

@@ -1,4 +1,5 @@
 import { colorRoles, slots } from '../core/types.js';
+import { canonicalHex, sourceColorCounts } from './paint.js';
 const compiled = new WeakSet();
 const identifier = /^[a-z][a-z0-9-]*$/;
 export const isColor = (value) => typeof value === 'string' && /^(#[\da-f]{3}|#[\da-f]{4}|#[\da-f]{6}|#[\da-f]{8}|transparent)$/i.test(value);
@@ -18,6 +19,25 @@ export function validateSelections(style, selections) {
         }
     }
 }
+/** Validate palette input and return it with canonical `#RRGGBB` keys. */
+export function normalizePalette(style, palette, strict = false) {
+    if (!palette || typeof palette !== 'object' || Array.isArray(palette))
+        throw new Error('Invalid palette');
+    const result = {};
+    for (const [key, value] of Object.entries(palette)) {
+        const color = canonicalHex(key);
+        if (!color || (strict && key !== color))
+            throw new Error(`Invalid palette color: ${key}`);
+        if (!style.palette.includes(color))
+            throw new Error(`Unknown palette color: ${key} is not in the ${style.id} artwork`);
+        if (own(result, color))
+            throw new Error(`Duplicate palette color: ${color}`);
+        if (!isColor(value))
+            throw new Error(`Invalid palette value for ${color}: use a hex color or transparent`);
+        result[color] = value;
+    }
+    return result;
+}
 function freeze(value) {
     Object.freeze(value);
     for (const child of Object.values(value))
@@ -61,6 +81,12 @@ export function defineStyle(definition) {
         for (const selections of pool)
             validateSelections(style, selections);
     }
+    // Every source color, most used first: the keys a palette may change.
+    const counts = new Map();
+    for (const slot of slots)
+        for (const part of style.parts[slot])
+            sourceColorCounts(part.svg, counts);
+    style.palette = [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([color]) => color);
     freeze(style);
     compiled.add(style);
     return style;

package/dist/react/index.d.ts

@@ -1,8 +1,8 @@
 import type { SVGProps } from 'react';
 import type { AvatarOptions, AvatarStyle } from '../core/types.js';
-export type { AvatarOptions, AvatarStyle } from '../core/types.js';
+export type { AvatarOptions, AvatarStyle, Palette } from '../core/types.js';
 export type AvatarProps = AvatarOptions & Omit<SVGProps<SVGSVGElement>, keyof AvatarOptions | 'children' | 'dangerouslySetInnerHTML' | 'title' | 'viewBox' | 'width' | 'height'> & {
     assets: AvatarStyle;
     title?: string;
 };
-export declare function Avatar({ assets, theme, seed, seedPool, selections, colors, background, size, shape, title, style, ...props }: AvatarProps): import("react").JSX.Element;
+export declare function Avatar({ assets, theme, seed, seedPool, selections, colors, palette, background, size, shape, title, style, ...props }: AvatarProps): import("react").JSX.Element;

package/dist/react/index.js

@@ -3,11 +3,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from 'react';
 import { createAvatar } from '../core/index.js';
 import { escapeXml, renderContents } from '../internal/render.js';
-export function Avatar({ assets, theme, seed, seedPool, selections, colors, background, size = 64, shape, title, style, ...props }) {
+export function Avatar({ assets, theme, seed, seedPool, selections, colors, palette, background, size = 64, shape, title, style, ...props }) {
     const reactId = useId();
     // Hex encoding is injective and works with both React 18 and 19's useId formats.
     const prefix = `avatar-${Array.from(reactId, char => char.codePointAt(0).toString(16)).join('-')}`;
-    const state = createAvatar(assets, { theme, seed, seedPool, selections, colors, background, size, shape }).toJSON();
+    const state = createAvatar(assets, { theme, seed, seedPool, selections, colors, palette, background, size, shape }).toJSON();
     const labelled = Boolean(props['aria-label'] || props['aria-labelledby'] || title);
     const titleMarkup = title ? `<title id="${prefix}-title">${escapeXml(title)}</title>` : '';
     const variables = Object.fromEntries(Object.entries(state.colors).filter(([, value]) => value !== 'original').map(([role, value]) => [`--avatar-${role}`, value]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illlustrations/avatars",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Composable, seeded SVG avatars for JavaScript and React. Croods is the first style.",
   "homepage": "https://illlustrations.co/docs",
   "repository": {