@usenavii/core 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,117 @@
+# @usenavii/core
+
+**Deterministic mascot avatars from a seed.** Pure TypeScript engine. Same seed in → byte-identical SVG out, every time. No state, no uploads, no network.
+
+<p align="center">
+  <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" />
+</p>
+
+- [Live demo](https://navii.uxderrick.com) — interactive playground + cast
+- [Docs](https://navii.uxderrick.com/docs)
+- [GitHub](https://github.com/uxderrick/navii)
+
+## Install
+
+```sh
+npm  add @usenavii/core
+pnpm add @usenavii/core
+yarn add @usenavii/core
+bun  add @usenavii/core
+```
+
+## Quick start
+
+```ts
+import { createAvatar } from '@usenavii/core';
+
+const svg = createAvatar(user.id, { size: 96 });
+document.body.insertAdjacentHTML('beforeend', svg);
+```
+
+Or use the namespace bundle:
+
+```ts
+import { Navii } from '@usenavii/core';
+
+Navii.create(user.id);
+Navii.seed({ id: user.id, email: user.email, name: user.name });
+Navii.build({ body: 'tall', eyes: 'star', palette: 'violet' });
+Navii.group([user1.id, user2.id, user3.id]);
+```
+
+## The seed: read this once
+
+Same seed always produces the same avatar — that's the contract.
+
+| Pass                       | Result                                                  |
+| -------------------------- | ------------------------------------------------------- |
+| `user.id` / UUID           | ✅ Best. Stable and globally unique.                    |
+| `user.email`               | ✅ Good. Stable, unique per user.                       |
+| `user.name` alone          | ⚠️ Names collide. Two "Alice"s get the same avatar.    |
+| `${name}-${createdAt}`     | ✅ Fine fallback if no ID exists. Bake at signup.       |
+| `Date.now()` at render     | ❌ **Don't.** Breaks determinism — changes on reload.   |
+
+If your shape is uncertain, use the helper:
+
+```ts
+const s = Navii.seed({ id: user.id, email: user.email, name: user.name, createdAt: user.createdAt });
+const svg = Navii.create(s);
+```
+
+It picks the most unique field automatically: `id` → `email` → `name + createdAt` → `name`.
+
+## API
+
+```ts
+createAvatar(seed: string, options?: AvatarOptions): string
+selectAvatar(seed: string, options?: AvatarOptions): AvatarSpec
+renderAvatar(spec:  AvatarSpec, options?: AvatarOptions): string
+renderGroup(seeds:  string[],   options?: GroupOptions):  string
+
+seed(fields:  SeedFields): string         // pick most-unique field
+build(spec?:  BuildSpec, opts?): string   // manual mix-and-match (no seed)
+
+Navii.{ create, render, select, group, seed, build }
+```
+
+### `AvatarOptions`
+
+| Option       | Type                                                  | Default      |
+| ------------ | ----------------------------------------------------- | ------------ |
+| `size`       | `number` (px)                                         | `96`         |
+| `paletteId`  | known palette id (e.g. `'mint'`)                      | seed-derived |
+| `background` | `'none' \| 'solid' \| 'ring'` or `{ color }`          | seed-derived |
+| `tileBg`     | CSS color or `'auto'` (palette accent)                | none         |
+| `title`      | accessible label (sets `<title>` + `aria-label`)      | none         |
+| `animated`   | `boolean` — idle float / blink / sway / pulse / twinkle | `false`    |
+
+### `build()` — direct construction without a seed
+
+Use for brand mascots, logo marks, designer-curated avatars:
+
+```ts
+const svg = Navii.build({
+  body: 'tall', eyes: 'star', mouth: 'grin',
+  palette: 'violet', topper: 'crown',
+}, { size: 192, animated: true });
+```
+
+Any field omitted falls back to the first variant.
+
+## Determinism guarantee
+
+`createAvatar(seed)` is a pure function. Same seed + same options → byte-identical SVG.
+
+- PRNG: `sfc32` seeded from a `cyrb53` hash of the seed string.
+- 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.
+- No `Date.now()`, no `Math.random()`, no module-level state, no environment lookups.
+
+Render the same avatar in Node, in the browser, on the edge — all byte-identical.
+
+## Cast (output space)
+
+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.
+
+## License
+
+MIT. See [LICENSE](https://github.com/uxderrick/navii/blob/main/LICENSE).

package/dist/index.cjs

@@ -15,9 +15,9 @@ function cyrb53(input, salt = 0) {
   h2 ^= Math.imul(h1 ^ h1 >>> 13, 3266489909);
   return [h1 >>> 0, h2 >>> 0];
 }
-function createRng(seed) {
-  const [a, b] = cyrb53(seed, 0);
-  const [c, d] = cyrb53(seed, 1);
+function createRng(seed2) {
+  const [a, b] = cyrb53(seed2, 0);
+  const [c, d] = cyrb53(seed2, 1);
   let s0 = a >>> 0;
   let s1 = b >>> 0;
   let s2 = c >>> 0;
@@ -623,8 +623,8 @@ var TOPPER_IDS = [
 ];
 
 // src/select.ts
-function selectAvatar(seed, options = {}) {
-  const rng = createRng(seed);
+function selectAvatar(seed2, options = {}) {
+  const rng = createRng(seed2);
   const paletteOverride = options.paletteId ? PALETTE_BY_ID[options.paletteId] : void 0;
   const palette = paletteOverride ?? rng.pick(PALETTES);
   const body = rng.pick(BODY_IDS);
@@ -648,7 +648,7 @@ function selectAvatar(seed, options = {}) {
   const mouthCurveScale = Number(rng.range(0.85, 1.15).toFixed(3));
   const antennaTilt = Math.round(rng.range(-8, 8));
   return {
-    seed,
+    seed: seed2,
     palette,
     body,
     eyes,
@@ -777,9 +777,9 @@ function wrap(cls, inner) {
   if (!inner) return inner;
   return `<g class="${cls}">${inner}</g>`;
 }
-function stableId(seed) {
+function stableId(seed2) {
   let h = 5381;
-  for (let i = 0; i < seed.length; i++) h = (h << 5) + h + seed.charCodeAt(i) | 0;
+  for (let i = 0; i < seed2.length; i++) h = (h << 5) + h + seed2.charCodeAt(i) | 0;
   return (h >>> 0).toString(36);
 }
 function escapeXml(s) {
@@ -803,9 +803,9 @@ function renderGroup(seeds, options = {}) {
   const tileCount = visibleSeeds.length + (overflow > 0 ? 1 : 0);
   const step = size * (1 - overlap);
   const totalWidth = tileCount > 0 ? step * (tileCount - 1) + size : 0;
-  const tiles = visibleSeeds.map((seed, i) => {
+  const tiles = visibleSeeds.map((seed2, i) => {
     const x = i * step;
-    const spec = selectAvatar(seed, options);
+    const spec = selectAvatar(seed2, options);
     const bgCircle = tileBg !== "transparent" ? `<circle cx="50" cy="50" r="50" fill="${tileBg}" />` : "";
     return `<svg x="${x}" y="0" width="${size}" height="${size}" viewBox="0 0 100 100" overflow="visible">
       <defs><clipPath id="navii-clip"><circle cx="50" cy="50" r="50" /></clipPath></defs>
@@ -827,20 +827,72 @@ function clamp(n, lo, hi) {
   return Math.max(lo, Math.min(hi, n));
 }
 
+// src/seed.ts
+function seed(fields) {
+  if (fields.id !== null && fields.id !== void 0 && String(fields.id).length > 0) {
+    return String(fields.id);
+  }
+  if (fields.email && fields.email.length > 0) {
+    return fields.email;
+  }
+  if (fields.name && fields.name.length > 0) {
+    if (fields.createdAt !== null && fields.createdAt !== void 0) {
+      const ts = fields.createdAt instanceof Date ? fields.createdAt.getTime() : typeof fields.createdAt === "number" ? fields.createdAt : Date.parse(fields.createdAt);
+      if (Number.isFinite(ts)) return `${fields.name}|${ts}`;
+      return `${fields.name}|${fields.createdAt}`;
+    }
+    return fields.name;
+  }
+  throw new Error("navii: seed() requires at least one of { id, email, name }");
+}
+
+// src/build.ts
+function build(spec = {}, options = {}) {
+  const palette = spec.palette ? PALETTE_BY_ID[spec.palette] ?? PALETTES[0] : PALETTES[0];
+  const resolved = {
+    seed: "__build__",
+    palette,
+    body: spec.body ?? "orb",
+    eyes: spec.eyes ?? "round",
+    mouth: spec.mouth ?? "smile",
+    antenna: spec.antenna ?? "none",
+    accessory: spec.accessory ?? "none",
+    background: spec.background ?? "none",
+    topper: spec.topper ?? "none",
+    hueShift: spec.hueShift ?? 0,
+    bodyScale: spec.bodyScale ?? 1,
+    eyeGapShift: spec.eyeGapShift ?? 0,
+    mouthCurveScale: spec.mouthCurveScale ?? 1,
+    antennaTilt: spec.antennaTilt ?? 0
+  };
+  return renderAvatar(resolved, options);
+}
+
 // src/index.ts
-function createAvatar(seed, options = {}) {
-  if (typeof seed !== "string" || seed.length === 0) {
+function createAvatar(seed2, options = {}) {
+  if (typeof seed2 !== "string" || seed2.length === 0) {
     throw new Error("navii: seed must be a non-empty string");
   }
-  return renderAvatar(selectAvatar(seed, options), options);
+  return renderAvatar(selectAvatar(seed2, options), options);
 }
+var Navii = {
+  create: createAvatar,
+  render: renderAvatar,
+  select: selectAvatar,
+  group: renderGroup,
+  seed,
+  build
+};
 
+exports.Navii = Navii;
+exports.build = build;
 exports.createAvatar = createAvatar;
 exports.createRng = createRng;
 exports.cyrb53 = cyrb53;
 exports.renderAvatar = renderAvatar;
 exports.renderAvatarInner = renderAvatarInner;
 exports.renderGroup = renderGroup;
+exports.seed = seed;
 exports.selectAvatar = selectAvatar;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map