@usenavii/core 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# @usenavii/core
|
|
2
|
+
|
|
3
|
+
**Deterministic mascot avatars from a seed.** Pure TypeScript engine. Same seed in → byte-identical SVG out, every time. No state, no uploads, no network.
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="https://navii-api.uxderrick.com/group?seeds=aria,milo,nova,kai,sage,eden,luna,rio,pip,wren,zane,iris&size=72&overlap=0.32&ring=%230a0a0b&tileBg=%23ffffff" alt="Navii cast" />
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
- [Live demo](https://navii.uxderrick.com) — interactive playground + cast
|
|
10
|
+
- [Docs](https://navii.uxderrick.com/docs)
|
|
11
|
+
- [GitHub](https://github.com/uxderrick/navii)
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npm add @usenavii/core
|
|
17
|
+
pnpm add @usenavii/core
|
|
18
|
+
yarn add @usenavii/core
|
|
19
|
+
bun add @usenavii/core
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Quick start
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { createAvatar } from '@usenavii/core';
|
|
26
|
+
|
|
27
|
+
const svg = createAvatar(user.id, { size: 96 });
|
|
28
|
+
document.body.insertAdjacentHTML('beforeend', svg);
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Or use the namespace bundle:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { Navii } from '@usenavii/core';
|
|
35
|
+
|
|
36
|
+
Navii.create(user.id);
|
|
37
|
+
Navii.seed({ id: user.id, email: user.email, name: user.name });
|
|
38
|
+
Navii.build({ body: 'tall', eyes: 'star', palette: 'violet' });
|
|
39
|
+
Navii.group([user1.id, user2.id, user3.id]);
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## The seed: read this once
|
|
43
|
+
|
|
44
|
+
Same seed always produces the same avatar — that's the contract.
|
|
45
|
+
|
|
46
|
+
| Pass | Result |
|
|
47
|
+
| -------------------------- | ------------------------------------------------------- |
|
|
48
|
+
| `user.id` / UUID | ✅ Best. Stable and globally unique. |
|
|
49
|
+
| `user.email` | ✅ Good. Stable, unique per user. |
|
|
50
|
+
| `user.name` alone | ⚠️ Names collide. Two "Alice"s get the same avatar. |
|
|
51
|
+
| `${name}-${createdAt}` | ✅ Fine fallback if no ID exists. Bake at signup. |
|
|
52
|
+
| `Date.now()` at render | ❌ **Don't.** Breaks determinism — changes on reload. |
|
|
53
|
+
|
|
54
|
+
If your shape is uncertain, use the helper:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const s = Navii.seed({ id: user.id, email: user.email, name: user.name, createdAt: user.createdAt });
|
|
58
|
+
const svg = Navii.create(s);
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
It picks the most unique field automatically: `id` → `email` → `name + createdAt` → `name`.
|
|
62
|
+
|
|
63
|
+
## API
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
createAvatar(seed: string, options?: AvatarOptions): string
|
|
67
|
+
selectAvatar(seed: string, options?: AvatarOptions): AvatarSpec
|
|
68
|
+
renderAvatar(spec: AvatarSpec, options?: AvatarOptions): string
|
|
69
|
+
renderGroup(seeds: string[], options?: GroupOptions): string
|
|
70
|
+
|
|
71
|
+
seed(fields: SeedFields): string // pick most-unique field
|
|
72
|
+
build(spec?: BuildSpec, opts?): string // manual mix-and-match (no seed)
|
|
73
|
+
|
|
74
|
+
Navii.{ create, render, select, group, seed, build }
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### `AvatarOptions`
|
|
78
|
+
|
|
79
|
+
| Option | Type | Default |
|
|
80
|
+
| ------------ | ----------------------------------------------------- | ------------ |
|
|
81
|
+
| `size` | `number` (px) | `96` |
|
|
82
|
+
| `paletteId` | known palette id (e.g. `'mint'`) | seed-derived |
|
|
83
|
+
| `background` | `'none' \| 'solid' \| 'ring'` or `{ color }` | seed-derived |
|
|
84
|
+
| `tileBg` | CSS color or `'auto'` (palette accent) | none |
|
|
85
|
+
| `title` | accessible label (sets `<title>` + `aria-label`) | none |
|
|
86
|
+
| `animated` | `boolean` — idle float / blink / sway / pulse / twinkle | `false` |
|
|
87
|
+
|
|
88
|
+
### `build()` — direct construction without a seed
|
|
89
|
+
|
|
90
|
+
Use for brand mascots, logo marks, designer-curated avatars:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
const svg = Navii.build({
|
|
94
|
+
body: 'tall', eyes: 'star', mouth: 'grin',
|
|
95
|
+
palette: 'violet', topper: 'crown',
|
|
96
|
+
}, { size: 192, animated: true });
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Any field omitted falls back to the first variant.
|
|
100
|
+
|
|
101
|
+
## Determinism guarantee
|
|
102
|
+
|
|
103
|
+
`createAvatar(seed)` is a pure function. Same seed + same options → byte-identical SVG.
|
|
104
|
+
|
|
105
|
+
- PRNG: `sfc32` seeded from a `cyrb53` hash of the seed string.
|
|
106
|
+
- Part picks happen in a fixed order. New parts are appended to the end of the stream, so adding variants in future releases never shifts existing seeds.
|
|
107
|
+
- No `Date.now()`, no `Math.random()`, no module-level state, no environment lookups.
|
|
108
|
+
|
|
109
|
+
Render the same avatar in Node, in the browser, on the edge — all byte-identical.
|
|
110
|
+
|
|
111
|
+
## Cast (output space)
|
|
112
|
+
|
|
113
|
+
22 palettes × 8 bodies × 10 eyes × 10 mouths × 5 antennae × 7 accessories × 3 backgrounds × 12 toppers = **22,176,000** discrete combinations. Plus continuous tweaks (hue rotation ±30°, body scale ±8%, eye gap ±2, mouth curvature ±15%, antenna tilt ±8°) → effectively unbounded.
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT. See [LICENSE](https://github.com/uxderrick/navii/blob/main/LICENSE).
|
package/package.json
CHANGED