@illlustrations/avatars 1.0.0

package/AI.md

@@ -0,0 +1,84 @@
+# @illlustrations/avatars — notes for coding agents
+
+Seeded SVG avatars for JavaScript and React. Everything renders locally: no
+API key, network request or account. Croods is the first style.
+
+Install: `npm install @illlustrations/avatars` (Node 20.19+; React 18.3+ or 19
+for the component). Docs: https://illlustrations.co/docs
+
+## Imports
+
+```ts
+import { createAvatar, fromJSON } from '@illlustrations/avatars'; // no React
+import { Avatar } from '@illlustrations/avatars/react';             // React 18.3+ or 19
+import { croods } from '@illlustrations/avatars/croods';            // the style
+```
+
+There is no default export and no `/core`, `/styles/croods` or `/dist/...`
+import path.
+
+## Use
+
+```tsx
+// React. `assets` is required. Same seed = same avatar, on every device.
+<Avatar assets={croods} seed={user.id} size={40} shape="circle" title={user.name} />
+
+// Anywhere else: SVG string, data URI or saved state.
+const avatar = createAvatar(croods, { seed: user.id, size: 128 });
+avatar.toString();   // '<svg ...>'
+avatar.toDataUri();  // for <img src> or CSS; add alt text yourself
+avatar.toJSON();     // store this if the user customizes their avatar
+fromJSON(croods, saved).toString();
+```
+
+## Rules
+
+1. Use only the part IDs below. Unknown IDs throw `Unknown <slot> part: <id>`.
+   `head` and `upperBody` must be real IDs; the others also accept `none`.
+2. Use a stable seed (user ID, not display name or `Math.random()`) so an
+   avatar does not change between renders or on the server and client.
+3. When users pick parts, save `toJSON()` and restore with `fromJSON`. Do not
+   store only the seed: explicit selections are not derivable from it.
+4. Pass `assets={croods}` to `<Avatar>`. `style` is the normal React CSS prop.
+5. Several inline SVG strings on one page need unique IDs:
+   `toString({ idPrefix: 'user-42' })`. The prefix starts with a letter and uses
+   only letters, digits, `_` and `-`: clean user IDs and add the list index, e.g.
+   `` `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.
+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
+   site, somewhere visible (footer, about or credits page). Individual avatars,
+   emails and exported SVGs need no caption.
+
+## Options
+
+| Option | Values |
+| --- | --- |
+| `seed` | Any string. Omit for the default character. |
+| `selections` | Partial `{ head, face, upperBody, facialHair, accessories }` |
+| `colors` | Partial `{ hair, skin, clothing, stroke }` |
+| `theme` | `'ink'` (blue and white) or `'neutral'` (black and white) |
+| `background` | Hex or `'transparent'` (default) |
+| `shape` | `'square'` (default), `'rounded'`, `'circle'` |
+| `size` | Pixels. Core default 600, React default 64 |
+| `seedPool` | `'v1'` (default). Only for pinning seed results across versions |
+
+Resolution order: style defaults → seeded combination → explicit `selections`.
+Explicit `colors` override `theme` colors.
+
+## Parts
+
+<!-- parts:start (generated by scripts/sync-readme.mjs; do not edit) -->
+| Slot | Required | Default | Valid IDs for `croods` |
+| --- | --- | --- | --- |
+| `head` | yes | `default` | `afro-1`, `afro-2`, `bald`, `bangs`, `bowl-cut`, `braid-1`, `braid-2`, `bun-1`, `bun-2`, `bun`, `default`, `dread`, `long-hair`, `long-hair-1`, `long-hair-2`, `messy-afro`, `messy`, `mohawk`, `no-hair`, `normal`, `pixie`, `quiff-1`, `quiff-2`, `shaggy`, `short-hair-1`, `short-hair-2`, `short-hair-3`, `short-hair-4`, `short-hair-5`, `short-hair-6`, `short-hair-7`, `short-hair-8`, `short-hair-9`, `straight-long`, `trimmed`, `wavy-curls` |
+| `face` | no | `normal` | `drool`, `drool-2`, `happy`, `normal`, `open-mouth-1`, `sad`, `none` |
+| `upperBody` | yes | `t-shirt-1` | `blazer`, `hoodie-1`, `shirt-1`, `t-shirt-1`, `t-shirt-bag` |
+| `facialHair` | no | `none` | `beard`, `moustache`, `stubble`, `none` |
+| `accessories` | no | `none` | `glass`, `none` |
+
+Seeded avatars never pick facial hair; pass `selections.facialHair` to opt in.
+<!-- parts:end -->

package/ARTWORK.md

@@ -0,0 +1,34 @@
+# Croods v2 artwork snapshot
+
+On September 16, 2026 the owner requested importing all Croods v2 parts marked
+for the avatar layout. This repository now includes the 51 active variants
+whose `layout_positions.avatar` has a valid positive size:
+
+- 36 heads
+- 6 faces
+- 5 upper bodies
+- 3 facial-hair parts
+- 1 accessory
+
+Seven lower-body parts have no avatar placement and were excluded. Originals
+were downloaded read-only from the configured Supabase storage bucket, using
+the catalog's references to resolve the corresponding private SVG. No database
+or bucket records were changed.
+
+`artwork/croods/catalog.json` records public aliases, display names, source file
+hashes, per-part geometry, effective z-index and import time. It contains no
+credentials, database UUIDs or storage URLs. `source/` holds the exact downloaded
+SVG bytes for reproducible comparison. `manifest.json` contains the package
+snapshot and frozen seed pool; `presets.json` contains 24 resolved portraits.
+
+Normalization preserves source colors by default. Explicit role overrides
+recolor selected source palette entries while retaining accents and coverage.
+The npm file allowlist includes compiled artwork and preset SVGs, not raw
+catalog/source files, import scripts or the unrelated test fixtures.
+
+Croods v2 artwork by [illlustrations / Vijay Verma](https://illlustrations.co)
+is licensed under [CC BY 4.0](LICENSE-ARTWORK). Code uses [MIT](LICENSE-CODE).
+See [README.md](README.md#license) for attribution.
+
+`private: true` and the release guard remain until the npm scope and public
+release are reviewed.

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 1.0.0
+
+First public release of `@illlustrations/avatars`.
+
+- Entry points: `@illlustrations/avatars` (core, no React), `/react` (`<Avatar>`),
+  `/croods` (style), `/croods/presets.json` and `/svg/croods-001.svg`–`croods-024.svg`.
+  Works with `import` and `require` (Node 20.19+).
+- Croods style 1.0.0: 51 parts (36 heads, 6 faces, 5 upper bodies, 3 facial hair,
+  1 accessory) and 24 presets.
+- Seeded avatars from a frozen `v1` pool of 256 combinations. Every seeded avatar
+  has a face; facial hair is opt-in through `selections.facialHair`.
+- Colors per role (`hair`, `skin`, `clothing`, `stroke`), `ink` and `neutral`
+  themes, background, `square`/`rounded`/`circle` shapes.
+- `toString`, `toDataUri`, `toJSON` and `fromJSON` with validated, versioned state.
+- `AI.md` ships rules and every valid part ID for coding agents.
+- Code: MIT. Croods artwork: CC BY 4.0.
+
+Part IDs renamed from the unreleased preview: `t-shit-bag` → `t-shirt-bag`,
+`pixe` → `pixie`, `drool2` → `drool-2`, facial hair `normal` → `stubble`.

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2026 Vijay Verma / illlustrations
+
+Code: MIT — see LICENSE-CODE.
+Artwork: CC BY 4.0 — see LICENSE-ARTWORK.
+
+The artwork license covers artwork/croods/, including SVG parts, manifests
+and presets, plus the Croods artwork embedded in compiled styles, exported
+SVGs and generated avatars. Code wrappers remain under MIT.
+
+Third-party dependencies and other illlustrations collections retain their
+own licenses.

package/LICENSE-ARTWORK

@@ -0,0 +1,9 @@
+Croods v2 artwork
+Copyright (c) 2026 Vijay Verma / illlustrations
+https://illlustrations.co
+
+Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
+https://creativecommons.org/licenses/by/4.0/
+
+Full legal terms: https://creativecommons.org/licenses/by/4.0/legalcode
+See LICENSE for the scope of artwork and code licensing.

package/LICENSE-CODE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay Verma / illlustrations
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @illlustrations/avatars
+
+Composable, seeded SVG avatars for plain JavaScript and React. Croods is the
+first style. Everything renders locally: no API key, account or network request.
+Docs and a live playground: https://illlustrations.co/docs
+
+```sh
+npm install @illlustrations/avatars
+```
+
+React projects also need React 18.3.1 or 19. Node 20.19 or newer. The
+Croods v2 collection includes all 51 active parts with a valid avatar
+configuration in the source database: 36 heads, 6 faces, 5 upper bodies,
+3 facial-hair parts and 1 accessory.
+
+| Import | Contents |
+| --- | --- |
+| `@illlustrations/avatars` | `createAvatar`, `fromJSON` and types. No React. |
+| `@illlustrations/avatars/react` | The `<Avatar>` component. |
+| `@illlustrations/avatars/croods` | The Croods style. Future styles get their own path. |
+| `@illlustrations/avatars/croods/presets.json` | 24 resolved preset states. |
+| `@illlustrations/avatars/svg/croods-001.svg` | Preset SVG files, `001` to `024`. |
+
+Coding agents: see [AI.md](AI.md) for rules and valid part IDs.
+
+## Develop
+
+```sh
+npm install
+npm test
+npm run verify:artwork
+npm run check:package
+npm run preview
+```
+
+The playground includes every part, original/custom colors, shapes, 24 starter
+portraits, SVG/JSON downloads and JSON restoration. The parts gallery displays
+the saved size and offset. Everything renders locally; no account, API key,
+Supabase connection or network request is required by the package at runtime.
+
+To try an unreleased build in another project, run `npm pack` here and
+install the resulting archive there.
+
+## React
+
+```tsx
+import { Avatar } from '@illlustrations/avatars/react';
+import { croods } from '@illlustrations/avatars/croods';
+
+<Avatar assets={croods} seed="user-42" size={64} title="Sam's avatar" />
+<Avatar assets={croods} shape="circle"
+  selections={{ head: 'straight-long', facialHair: 'beard', accessories: 'none' }}
+  colors={{ hair: '#143CFF', stroke: '#111111' }} />
+```
+
+React accepts `title`, `className`, `style`, ARIA and SVG presentation props.
+Without a title or accessible label the avatar is decorative. It uses `useId`
+to isolate SVG definitions. Applications with multiple React roots must use
+matching, unique React `identifierPrefix` settings on server and client.
+
+## Plain JavaScript
+
+```ts
+import { createAvatar, fromJSON } from '@illlustrations/avatars';
+import { croods } from '@illlustrations/avatars/croods';
+
+const avatar = createAvatar(croods, { seed: 'user-42', background: '#EDEDFF' });
+const svg = avatar.toString();
+const imageUrl = avatar.toDataUri();
+const saved = avatar.toJSON();
+const restored = fromJSON(croods, saved);
+```
+
+For HTML, assign `toDataUri()` to an image's `src` and supply `alt`. For multiple
+inline SVG strings, use a unique `toString({ idPrefix: 'profile-42', title: 'Sam' })`
+prefix for each. The root entry and `/croods` do not load React.
+
+Individual SVG exports are available as
+`@illlustrations/avatars/svg/croods-001.svg` through `croods-024.svg`. Use your
+bundler's URL asset handling (for example a Vite `?url` import), or copy these
+files into your public assets directory. An npm specifier is not a browser URL.
+Resolved preset states are in `/croods/presets.json`.
+
+## Parts
+
+Unknown IDs throw `Unknown <slot> part: <id>`. Use only these:
+
+<!-- parts:start (generated by scripts/sync-readme.mjs; do not edit) -->
+| Slot | Required | Default | Valid IDs for `croods` |
+| --- | --- | --- | --- |
+| `head` | yes | `default` | `afro-1`, `afro-2`, `bald`, `bangs`, `bowl-cut`, `braid-1`, `braid-2`, `bun-1`, `bun-2`, `bun`, `default`, `dread`, `long-hair`, `long-hair-1`, `long-hair-2`, `messy-afro`, `messy`, `mohawk`, `no-hair`, `normal`, `pixie`, `quiff-1`, `quiff-2`, `shaggy`, `short-hair-1`, `short-hair-2`, `short-hair-3`, `short-hair-4`, `short-hair-5`, `short-hair-6`, `short-hair-7`, `short-hair-8`, `short-hair-9`, `straight-long`, `trimmed`, `wavy-curls` |
+| `face` | no | `normal` | `drool`, `drool-2`, `happy`, `normal`, `open-mouth-1`, `sad`, `none` |
+| `upperBody` | yes | `t-shirt-1` | `blazer`, `hoodie-1`, `shirt-1`, `t-shirt-1`, `t-shirt-bag` |
+| `facialHair` | no | `none` | `beard`, `moustache`, `stubble`, `none` |
+| `accessories` | no | `none` | `glass`, `none` |
+
+Seeded avatars never pick facial hair; pass `selections.facialHair` to opt in.
+<!-- parts:end -->
+
+## Options
+
+| Option | Behavior |
+| --- | --- |
+| `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. |
+| `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. |
+
+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
+the background independent. Use `<Avatar assets={croods} theme="ink" />` or
+`createAvatar(croods, { theme: 'neutral' })`. Themes are included in saved state.
+`original` preserves each element's source paint, including differently colored
+regions within one role. Background accepts hex or `transparent`. Recoloring
+keeps fixed accent colors, mask coverage and clip paths. The explicit source
+palette mapping is in `scripts/croods-colors.mjs`.
+
+Resolution is defaults → seeded combination → explicit selections. Invalid
+values, unknown parts/roles/slots and declared incompatible combinations throw.
+Inline React rendering uses `--avatar-hair`, `--avatar-skin`,
+`--avatar-clothing`, `--avatar-stroke`. Portable exports resolve paints to
+literals. CSS overrides are presentation-only; use `colors` for a palette that
+also appears in saved state and downloads.
+
+## Stable state and geometry
+
+Every part carries its exact database avatar rectangle and effective layer
+order. The renderer scales the native SVG viewport to that rectangle. This
+preserves each source viewBox, root paint and clipping, including tall hair.
+Geometry and artwork are bundled, versioned snapshots. Database edits do not
+change existing installations; re-import intentionally and update the style
+version when changing rendered output.
+
+The v1 algorithm is unsigned 32-bit FNV-1a over JavaScript UTF-16 code units
+(`Math.imul(hash ^ codeUnit, 16777619)`, starting at `2166136261`), modulo the
+frozen ordered pool length. Croods v1 contains 256 explicit tuples covering
+all imported parts except facial hair, which is always `none` in seeded
+avatars; pass `selections.facialHair` to opt in. Manual selections support
+combinations outside that pool.
+The pool is not a claim that every possible combination has been visually
+reviewed. Never reorder/extend a published pool; add an opt-in pool instead.
+Seeds can collide. Preset states are also committed explicitly.
+
+JSON stores schema version 1, exact style ID/version, resolved selections,
+colors, background, size and shape. `fromJSON` validates this data and rejects
+mismatched versions. Runtime APIs accept compiled styles, never arbitrary SVG.
+
+## Verification and release
+
+`npm run verify:artwork` checks source hashes and database rectangles, then
+compares all 51 parts in starter compositions and 24 presets against untouched
+source SVGs at 32, 64, 128 and 600 px. It generates contact sheets and a report
+in `.preview/`. `npm run check:package` checks actual installed core/style/React
+imports, SVG exports, TypeScript declarations, packed files and ESM/SVG sizes.
+
+See [ARTWORK.md](ARTWORK.md) for provenance and [docs/curation.md](docs/curation.md)
+for re-import instructions. See [CHANGELOG.md](CHANGELOG.md) for releases.
+
+## License
+
+Code is licensed under [MIT](LICENSE-CODE). Croods v2 artwork, including parts,
+presets and generated avatars, is licensed under [CC BY 4.0](LICENSE-ARTWORK).
+
+Credit: Croods v2 by [illlustrations / Vijay Verma](https://illlustrations.co),
+© 2026, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+Retain required notices and indicate changes when sharing modified artwork.

package/dist/core/index.d.ts

@@ -0,0 +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 declare function createAvatar(style: AvatarStyle, options?: AvatarOptions): AvatarResult;
+export declare function fromJSON(style: AvatarStyle, value: unknown): AvatarResult;

package/dist/core/index.js

@@ -0,0 +1,88 @@
+import { renderDocument } from '../internal/render.js';
+import { assertStyle, isColor, isRoleColor, 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) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Invalid ${label}`);
+}
+function keys(value, allowed, label) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            throw new Error(`Unknown ${label}: ${key}`);
+}
+/** FNV-1a over UTF-16 code units, unsigned 32-bit. This algorithm is frozen for v1. */
+function hash(seed) {
+    let value = 2166136261;
+    for (let i = 0; i < seed.length; i++)
+        value = Math.imul(value ^ seed.charCodeAt(i), 16777619);
+    return value >>> 0;
+}
+function validateState(style, state) {
+    record(state, 'avatar state');
+    keys(state, ['schemaVersion', 'style', 'styleVersion', 'selections', 'colors', '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');
+    record(state.selections, 'selections');
+    keys(state.selections, slots, 'slot');
+    validateSelections(style, state.selections);
+    record(state.colors, 'colors');
+    keys(state.colors, colorRoles, 'color role');
+    for (const role of colorRoles)
+        if (!isRoleColor(state.colors[role]))
+            throw new Error(`Invalid ${role} color: use a hex color, transparent or original`);
+    if (!isColor(state.background))
+        throw new Error('Invalid background: use a hex color or transparent');
+    if (!Number.isFinite(state.size) || state.size <= 0 || state.size > 8192)
+        throw new Error('Size must be greater than 0 and at most 8192');
+    if (!['square', 'rounded', 'circle'].includes(state.shape))
+        throw new Error('Unknown avatar shape');
+}
+export function createAvatar(style, options = {}) {
+    assertStyle(style);
+    record(options, 'options');
+    keys(options, ['seed', 'seedPool', 'selections', 'colors', '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');
+    const poolId = options.seedPool ?? style.defaultSeedPool;
+    if (typeof poolId !== 'string' || !own(style.seedPools, poolId))
+        throw new Error(`Unknown seed pool: ${poolId}`);
+    if (options.seed !== undefined) {
+        const pool = style.seedPools[poolId];
+        selections = pool[hash(options.seed) % pool.length];
+    }
+    if (options.selections !== undefined) {
+        record(options.selections, 'selections');
+        keys(options.selections, slots, 'slot');
+    }
+    if (options.colors !== undefined) {
+        record(options.colors, 'colors');
+        keys(options.colors, colorRoles, 'color role');
+    }
+    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 },
+        ...(options.theme === undefined ? {} : { theme: options.theme }),
+        background: options.background ?? 'transparent', size: options.size ?? 600, shape: options.shape ?? 'square',
+    };
+    validateState(style, state);
+    return result(style, state);
+}
+export function fromJSON(style, value) {
+    assertStyle(style);
+    record(value, 'avatar state');
+    const state = JSON.parse(JSON.stringify(value));
+    validateState(style, state);
+    return result(style, state);
+}
+function result(style, state) {
+    return Object.freeze({
+        toJSON: () => JSON.parse(JSON.stringify(state)),
+        toString: (options = {}) => renderDocument(style, state, options),
+        toDataUri: (options = {}) => `data:image/svg+xml,${encodeURIComponent(renderDocument(style, state, options))}`,
+    });
+}

package/dist/core/types.d.ts

@@ -0,0 +1,83 @@
+export declare const slots: readonly ["upperBody", "head", "face", "facialHair", "accessories"];
+export type Slot = (typeof slots)[number];
+export declare const colorRoles: readonly ["hair", "skin", "clothing", "stroke"];
+export type ColorRole = (typeof colorRoles)[number];
+export type Colors = Record<ColorRole, string>;
+export type Selections = Record<Slot, string>;
+export type Theme = 'ink' | 'neutral';
+export type Shape = 'square' | 'rounded' | 'circle';
+export interface AvatarOptions {
+    theme?: Theme;
+    seed?: string;
+    seedPool?: string;
+    selections?: Partial<Selections>;
+    colors?: Partial<Colors>;
+    background?: string;
+    size?: number;
+    shape?: Shape;
+}
+export interface AvatarState {
+    theme?: Theme;
+    schemaVersion: 1;
+    style: string;
+    styleVersion: string;
+    selections: Selections;
+    colors: Colors;
+    background: string;
+    size: number;
+    shape: Shape;
+}
+export interface RenderOptions {
+    /** Unique on the containing page. Standalone image documents need no prefix. */
+    idPrefix?: string;
+    title?: string;
+}
+export interface AvatarResult {
+    toString(options?: RenderOptions): string;
+    toDataUri(options?: Omit<RenderOptions, 'idPrefix'>): string;
+    toJSON(): AvatarState;
+}
+export interface Part {
+    id: string;
+    name?: string;
+    /** Sanitized at build time. Never pass user-supplied SVG here. */
+    svg: string;
+    /** Snapshot of the builder's effective avatar layer order. */
+    zIndex: number;
+    /** Exact per-variant avatar placement from the builder database. */
+    position: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface StyleDefinition {
+    id: string;
+    version: string;
+    parts: Record<Slot, readonly Part[]>;
+    defaults: {
+        selections: Selections;
+        colors: Colors;
+    };
+    /** Ordered, frozen compatible tuples. Adding parts must not alter an existing pool. */
+    seedPools: Record<string, readonly Selections[]>;
+    defaultSeedPool: string;
+    /** Each pair declares a combination that must never be rendered. */
+    incompatible?: readonly {
+        first: {
+            slot: Slot;
+            id: string;
+        };
+        second: {
+            slot: Slot;
+            id: string;
+        };
+    }[];
+}
+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;
+}
+export {};

package/dist/core/types.js

@@ -0,0 +1,2 @@
+export const slots = ['upperBody', 'head', 'face', 'facialHair', 'accessories'];
+export const colorRoles = ['hair', 'skin', 'clothing', 'stroke'];

package/dist/internal/render.d.ts

@@ -0,0 +1,5 @@
+import type { AvatarStyle, AvatarState, RenderOptions } from '../core/types.js';
+export declare const escapeXml: (value: string) => 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

@@ -0,0 +1,74 @@
+import { slots } from '../core/types.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))
+        throw new Error(`Invalid ${label}`);
+}
+function keys(value, allowed, label) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            throw new Error(`Unknown ${label}: ${key}`);
+}
+function prefix(value) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(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}`;
+        });
+    });
+}
+/** 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);
+    const clip = state.shape === 'circle' ? '<circle cx="300" cy="300" r="300"/>'
+        : `<rect width="600" height="600" rx="${state.shape === 'rounded' ? 96 : 0}"/>`;
+    const layers = slots.flatMap(slot => {
+        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 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];
+            return cssVariables ? `var(--avatar-${role}, ${color})` : color;
+        });
+        const p = part.position;
+        // Match the website export: scale the native viewport to the DB rectangle.
+        // Resizing the SVG viewport itself can introduce preserveAspectRatio letterboxing.
+        const root = svg.match(/^<svg\b([^>]*)>/)[1];
+        const width = Number(root.match(/\swidth="([\d.]+)"/)[1]);
+        const height = Number(root.match(/\sheight="([\d.]+)"/)[1]);
+        return `<g transform="translate(${p.x} ${p.y}) scale(${p.width / width} ${p.height / height})">${svg}</g>`;
+    }).join('');
+    return `<defs><clipPath id="${id}-clip">${clip}</clipPath></defs><g clip-path="url(#${id}-clip)"><rect width="600" height="600" fill="${state.background}"/>${layers}</g>`;
+}
+export function renderDocument(style, state, options) {
+    record(options, 'render options');
+    keys(options, ['idPrefix', 'title'], 'render option');
+    if (options.title !== undefined && typeof options.title !== 'string')
+        throw new Error('Title must be a string');
+    const id = prefix(options.idPrefix ?? 'avatar');
+    const title = options.title ? `<title id="${id}-title">${escapeXml(options.title)}</title>` : '';
+    return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 600 600" width="${state.size}" height="${state.size}" ${title ? `role="img" aria-labelledby="${id}-title"` : 'aria-hidden="true"'}>${title}${renderContents(style, state, id)}</svg>`;
+}

package/dist/internal/style.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarStyle, 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;
+/** 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;