@usenavii/core

Framework-agnostic engine. Seed in, SVG string out. Pure TypeScript, zero runtime dependencies, ~8 KB gzipped target.

Install

npm i @usenavii/core
# or pnpm / yarn / bun

Functions

createAvatar(seed: string, options?: AvatarOptions): string
selectAvatar(seed: string, options?: AvatarOptions): AvatarSpec
renderAvatar(spec:  AvatarSpec, options?: AvatarOptions): string
renderAvatarInner(spec: AvatarSpec, options?: AvatarOptions): string
renderGroup(seeds:  string[], options?: GroupOptions): string

createAvatar is the convenience composition of selectAvatar + renderAvatar. Use the split pair when you want to inspect or mutate the spec between picking and rendering.

renderAvatarInner emits the SVG body without an outer <svg> wrapper — useful when composing multiple avatars into one SVG document (this is how renderGroup works internally).

AvatarOptions

Option	Type	Default	Description
`size`	number (px)	96	Output canvas size. SVG viewBox is fixed at 100×100; size scales it.
`paletteId`	string	seeded	Force a specific palette. Pass any palette id.
`background`	enum or `{ color: string }`	seeded	Override scene fill. Enum form picks from `'none' \| 'solid' \| 'ring'`; object form supplies an exact color.
`title`	string	—	Adds `role="img"` and `aria-label`.
`animated`	boolean	false	Emits inline `<style>` with idle animations. Honors `prefers-reduced-motion`.
`tileBg`	string	—	Opaque circular fill behind avatar. Any CSS color or `'auto'` to use palette accent.

AvatarSpec

The resolved description of an individual avatar — what selectAvatar returns and what renderAvatar consumes.

interface AvatarSpec {
  seed:       string;
  palette:    Palette;
  body:       BodyShapeId;
  eyes:       EyeStyleId;
  mouth:      MouthStyleId;
  antenna:    AntennaStyleId;
  accessory:  AccessoryId;
  background: BackgroundId;
  topper:     TopperId;

  // Continuous tweaks
  hueShift:        number;  // degrees, signed
  bodyScale:       number;  // 0.92–1.08
  eyeGapShift:     number;  // px (viewBox units), signed
  mouthCurveScale: number;  // 0.85–1.15
  antennaTilt:     number;  // degrees, signed
}

All *Id types are string unions. Palette is an object: { id, bodyFrom, bodyTo, accent, ink, blush }.

Advanced: composition

The split selectAvatar + renderAvatar lets you override any part programmatically — not just the two the HTTP API exposes.

import { selectAvatar, renderAvatar } from '@usenavii/core';

const base = selectAvatar('alice');
const svg = renderAvatar({ ...base, body: 'tall', eyes: 'star' }, { size: 128 });

GroupOptions

Extends AvatarOptions with these additional fields:

Option	Type	Default	Description
`size`	number	64	Per-tile size.
`overlap`	number	0.3	Tile overlap fraction (0–0.7).
`max`	number	all	Cap tiles; remainder collapses into `+N`.
`ring`	string	`#ffffff`	Border ring around each tile.
`tileBg`	string	`#ffffff`	Solid fill behind each avatar.
`counterFill`	string	`#E5E7EB`	Background of the `+N` tile.
`counterInk`	string	`#374151`	Text color of the `+N` tile.

Other exports

createRng(seed) — the PRNG used internally. Returns { next(), range(min, max), pick(arr) }.
cyrb53(string) — fast 53-bit string hash. Used to seed the PRNG.
@usenavii/core/parts subpath — exports the part-id arrays (BODY_IDS, EYE_IDS, etc.) and PALETTES.