@usenavii/core 0.2.0 → 0.3.0

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

@@ -559,6 +559,76 @@ function renderTopper(id, anchor, palette) {
   }
 }
 
+// src/parts/outfit.ts
+function renderOutfit(id, anchor, palette) {
+  if (id === "none") return "";
+  const cx = anchor.cx;
+  const cy = anchor.mouthY + (anchor.groundY - anchor.mouthY) * 0.55;
+  const ink = palette.ink;
+  const accent = palette.accent;
+  switch (id) {
+    case "collar":
+      return [
+        `<path d="M${cx - 9} ${cy} L${cx - 2} ${cy - 4} L${cx - 2} ${cy + 5} Z" fill="${accent}" stroke="${ink}" stroke-width="0.7" />`,
+        `<path d="M${cx + 9} ${cy} L${cx + 2} ${cy - 4} L${cx + 2} ${cy + 5} Z" fill="${accent}" stroke="${ink}" stroke-width="0.7" />`,
+        // tiny button at center
+        `<circle cx="${cx}" cy="${cy + 4}" r="0.9" fill="${ink}" />`
+      ].join("");
+    case "scarf":
+      return [
+        // wrap band
+        `<path d="M${cx - 14} ${cy - 2} Q${cx} ${cy + 3} ${cx + 14} ${cy - 2} L${cx + 14} ${cy + 3} Q${cx} ${cy + 8} ${cx - 14} ${cy + 3} Z" fill="${palette.bodyTo}" stroke="${ink}" stroke-width="0.6" />`,
+        // tail 1 (left)
+        `<path d="M${cx - 6} ${cy + 5} L${cx - 9} ${cy + 12} L${cx - 4} ${cy + 12} L${cx - 2} ${cy + 5} Z" fill="${palette.bodyTo}" stroke="${ink}" stroke-width="0.5" />`,
+        // tail 2 (slightly right)
+        `<path d="M${cx + 1} ${cy + 6} L${cx + 4} ${cy + 13} L${cx - 1} ${cy + 13} L${cx - 2} ${cy + 6} Z" fill="${palette.bodyFrom}" stroke="${ink}" stroke-width="0.5" />`
+      ].join("");
+    case "bowtie":
+      return [
+        // left wing
+        `<path d="M${cx - 1} ${cy} L${cx - 9} ${cy - 4} L${cx - 9} ${cy + 4} Z" fill="${palette.bodyTo}" stroke="${ink}" stroke-width="0.7" />`,
+        // right wing
+        `<path d="M${cx + 1} ${cy} L${cx + 9} ${cy - 4} L${cx + 9} ${cy + 4} Z" fill="${palette.bodyTo}" stroke="${ink}" stroke-width="0.7" />`,
+        // center knot
+        `<rect x="${cx - 1.4}" y="${cy - 2.4}" width="2.8" height="4.8" rx="0.8" fill="${palette.bodyFrom}" stroke="${ink}" stroke-width="0.5" />`
+      ].join("");
+    case "sunflower": {
+      const fx = cx - 8;
+      const fy = cy + 2;
+      const petals = [];
+      for (let i = 0; i < 8; i++) {
+        const a = i / 8 * Math.PI * 2;
+        const px = fx + Math.cos(a) * 3.2;
+        const py = fy + Math.sin(a) * 3.2;
+        petals.push(
+          `<ellipse cx="${px.toFixed(2)}" cy="${py.toFixed(2)}" rx="2.4" ry="1.3" fill="#FACC15" stroke="${ink}" stroke-width="0.35" transform="rotate(${(a * 180 / Math.PI).toFixed(1)} ${px.toFixed(2)} ${py.toFixed(2)})" />`
+        );
+      }
+      return [
+        // stem (tucked behind)
+        `<path d="M${fx + 2} ${fy + 2} Q${fx + 4} ${fy + 6} ${fx + 1} ${fy + 10}" stroke="#16A34A" stroke-width="1.1" fill="none" stroke-linecap="round" />`,
+        // leaf
+        `<path d="M${fx + 3} ${fy + 6} Q${fx + 7} ${fy + 4} ${fx + 6} ${fy + 8} Q${fx + 4} ${fy + 8} ${fx + 3} ${fy + 6} Z" fill="#22C55E" stroke="${ink}" stroke-width="0.35" />`,
+        ...petals,
+        // center disc
+        `<circle cx="${fx}" cy="${fy}" r="2" fill="#92400E" stroke="${ink}" stroke-width="0.4" />`,
+        // texture dots on disc
+        `<circle cx="${fx - 0.6}" cy="${fy - 0.5}" r="0.4" fill="#451A03" />`,
+        `<circle cx="${fx + 0.7}" cy="${fy + 0.3}" r="0.4" fill="#451A03" />`,
+        `<circle cx="${fx - 0.4}" cy="${fy + 0.8}" r="0.4" fill="#451A03" />`
+      ].join("");
+    }
+    case "necklace":
+      return [
+        // chain (curve from collarbone left → drop → right)
+        `<path d="M${cx - 10} ${cy} Q${cx} ${cy + 8} ${cx + 10} ${cy}" stroke="${accent}" stroke-width="0.8" fill="none" stroke-linecap="round" />`,
+        // pendant
+        `<circle cx="${cx}" cy="${cy + 7}" r="1.6" fill="${accent}" stroke="${ink}" stroke-width="0.5" />`,
+        `<circle cx="${cx}" cy="${cy + 7}" r="0.7" fill="${palette.blush}" />`
+      ].join("");
+  }
+}
+
 // src/parts/index.ts
 var BODY_IDS = [
   "orb",
@@ -657,6 +727,7 @@ function selectAvatar(seed2, options = {}) {
     accessory,
     background,
     topper,
+    outfit: "none",
     hueShift,
     bodyScale,
     eyeGapShift,
@@ -740,10 +811,13 @@ function renderAvatarInner(spec, options = {}) {
   const antennaWrapped = antennaSvg ? `<g${transformAntenna(spec.antennaTilt ?? 0, anchor)}><g class="antenna">${antennaSvg}</g></g>` : "";
   const tileBg = resolveTileBg(options.tileBg, spec.palette);
   const tileCircle = tileBg ? `<circle cx="50" cy="50" r="50" fill="${tileBg}" />` : "";
+  const outfitSvg = renderOutfit(spec.outfit ?? "none", anchor, spec.palette);
   const parts = [
     tileCircle,
     renderBackground(spec.background, spec.palette, bgOverride),
     bodyWrapped,
+    // outfit sits on the body but below the face, so face features stay readable
+    outfitSvg,
     renderTopper(spec.topper, anchor, spec.palette),
     wrap("eyes", renderEyes(spec.eyes, spec.palette, anchor)),
     renderMouth(spec.mouth, spec.palette, anchor, spec.mouthCurveScale ?? 1),
@@ -859,6 +933,7 @@ function build(spec = {}, options = {}) {
     accessory: spec.accessory ?? "none",
     background: spec.background ?? "none",
     topper: spec.topper ?? "none",
+    outfit: spec.outfit ?? "none",
     hueShift: spec.hueShift ?? 0,
     bodyScale: spec.bodyScale ?? 1,
     eyeGapShift: spec.eyeGapShift ?? 0,