@usenavii/core 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,125 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.26.1] - 2026-05-31
+
+### Changed (docs)
+
+- Removed Gravatar comparisons from user-facing docs (README, package READMEs, `/docs/recipes`, `/docs/sdk-core`). Functionality unchanged — `seedFromEmail()` still hashes `sha256(email.trim().toLowerCase())`, so cross-product seed parity still holds for any caller using the same scheme.
+
+## [0.26.0] - 2026-05-30
+
+### Added (`@usenavii/core` 0.7.0)
+
+- **`seedFromEmail(email)`** — Gravatar-compatible seed helper. Returns `sha256` hex of the trimmed + lowercased email so the raw address never reaches URLs, server access logs, `Referer` headers, browser history, CDN cache keys, or analytics pixels. Two services hashing the same email produce the same seed → drop-in compatible with Gravatar's lookup scheme.
+- **`normalizeEmail(email)`** — exported canonicalization step (trim + lowercase + NFC) for callers who need to reproduce the form before hashing.
+- **`sha256Hex(input)`** — sync SHA-256 (FIPS 180-4) primitive used by `seedFromEmail`. Pure JS, no deps; available for callers that want to hash other inputs in the same scheme.
+- **`SeedOptions`** type + `hashEmail` option on `Navii.seed()`.
+
+### Changed (`@usenavii/core` 0.7.0) — breaking
+
+- `Navii.seed({ email })` now returns `sha256(normalizeEmail(email))` instead of the raw address. **Migration:** if your existing avatars were keyed on raw emails and you need them to stay stable, pass `{ hashEmail: false }` until you can re-key. New deployments should leave the default.
+- `Navii.seedFromEmail` exposed on the `Navii` namespace.
+
+### Added (`@usenavii/react` 0.8.0)
+
+- Re-exports `seed`, `seedFromEmail`, `normalizeEmail`, `SeedFields`, `SeedOptions` from `@usenavii/core` so `<Navii seed={seedFromEmail(user.email)} />` works without a second import.
+
+### Added (API host)
+
+- `/avatar/:seed` sets `x-navii-warning: plaintext-email-seed; hash with seedFromEmail()` when the seed matches an email pattern. Render still succeeds — the header is a client-side nudge. Also logged at `warn` level for ops visibility.
+
+### Changed (API host)
+
+- `/docs/recipes` gets a new "Using emails as seeds (Gravatar-style)" section.
+- `/docs/sdk-core#seed` documents `seedFromEmail`, `normalizeEmail`, and the `hashEmail` option on `Navii.seed()`.
+- `/docs/http-api#headers` documents the new `x-navii-warning` response header.
+
+## [0.25.2] - 2026-05-28
+
+### Changed (API host)
+- Landing hero CTAs reworked. New triple: `Install Navii →` (primary, scrolls to install snippets), `Get Figma Plugin →` (secondary, opens Figma community), `Try the Builder` (tertiary text link → `/builder`). Old single-purpose pair (`Try it` + `Customize a face`) replaced — plugin is now visible from the hero.
+- `/docs/sdk-core` SDK options table picks up `packs` + `style` rows (matches the engine surface that's been live since v0.23.0).
+
+## [0.25.1] - 2026-05-27
+
+### Added (API host)
+- **`/avatar/:seed?packs=…&style=…`** — `/avatar/:seed` now parses `packs` (comma-separated pack ids) and `style` (`masc | femme | neutral`) query params. Unknown pack ids are silently skipped (engine ignores them). Pack order does not affect cached output — the PNG cache key normalizes by sorting.
+
+### Fixed (API host)
+- PNG cache key extended to include `packs` + `style` so cached renders no longer collide across different pack/style combinations of the same seed.
+
+### Changed (API host)
+- `/docs/http-api` documents the new `packs` and `style` rows in the `/avatar/:seed` query table, plus new example URLs (`?packs=halloween`, `?packs=office,mono&style=neutral`).
+- `/random` inherits the new params (it forwards every `/avatar/:seed` query through unchanged).
+
+### Notes
+- Required by the upcoming Figma plugin update (fixes fill-mode rendering — plugin was sending the right options to the main thread but `buildUrl()` was stripping `packs`/`mood`/`style` before the HTTP request).
+- Backward compatible. Existing `<img src="https://api.navii.dev/avatar/alice">` URLs unchanged.
+
+## [0.25.0] - 2026-05-27
+
+### Added (`@usenavii/react` 0.7.0)
+- **`<NaviiGroup>`** — overlapping avatar stack, thin React wrapper around `@usenavii/core`'s `renderGroup()`. Props: `seeds`, `size`, `overlap`, `max` (overflow → `+N` counter tile), `ring`, `tileBg`, `counterFill`, `counterInk`, plus all per-tile options (`paletteId`, `palette`, `mood`, `background`, `animated`, `styleHint`). `<img>` width is computed from `size + overlap + max` so layout is stable on load.
+- `renderGroup` + `GroupOptions` re-exported from `@usenavii/react`.
+
+### Changed (`@usenavii/core`)
+- No source changes. Stays at `0.6.0` — react `0.7.0` ships independently. Lockstep convention relaxed when only one package has source changes.
+
+### Changed (tooling)
+- `scripts/release-audit.mjs` — core/react version mismatch downgraded from `error` to `warn`. Lockstep stays the default expectation, but the audit no longer forces a no-op publish on the unchanged package.
+
+### Added (API host)
+- `/docs/sdk-react` documents `<NaviiGroup>` props + behavior, plus the new `renderGroup`/`GroupOptions` re-exports.
+
+## [0.24.2] - 2026-05-27
+
+### Added (API host)
+- The Skill Club and ForYu logos in the landing "built with navii" wall.
+
+## [0.24.1] - 2026-05-27
+
+### Added (Figma plugin)
+- **Sign out of Pro** — Pro pill in header now opens upgrade modal even when Pro. Modal footer shows the signed-in email + a Sign-out button that clears the cached license via `license-clear`. Lets users test the free-tier flow on the same device without losing access (the underlying Polar license is unchanged).
+
+### Changed (Figma plugin)
+- Pro pill click now always opens the upgrade modal (was: free-only). Pro view exposes account info + sign-out.
+- Footer (Insert / Fill random) hidden on **Packs** and **Mascots** tabs — those are browsing surfaces with their own inline actions (Enable button in pack-modal, card-click action modal in Mascots). Footer remains on Seed + Build where Insert is the primary CTA.
+
+### Fixed (Figma plugin)
+- Pro user's usage chip stayed stuck at "10 of 10 left today" on plugin open due to a race between `usage-get` (UI request) and `doLicenseRestore` (main thread state). Restore now pushes a fresh usage snapshot via `doUsageGet()` after setting `cachedLicenseOk`, so the chip flips to "Pro · Unlimited" reliably.
+
+## [0.24.0] - 2026-05-27
+
+### Added (API host)
+- **Per-release OG cards** — `GET /og/blog/v<X.Y.Z>.png` composes a 1200×630 card for each minor+ release: dark radial background, hero avatar (deterministic from `navii <version>` seed + `mood: happy`, transparent so the mascot floats on the gradient), version pill, headline parsed from CHANGELOG, date, and `navii.dev/blog` brand mark. Cached per version. `/blog/v<X.Y.Z>` now sets `og:image` + `twitter:image` to this URL so social previews show the release-specific card instead of the generic landing OG image.
+
+## [0.23.6] - 2026-05-27
+
+### Removed (API host)
+- Ghana Duty logo from the landing "built with navii" wall (asset + markup). Wall keeps Elorm UI, Golly Express, Fleetlinq.
+
+## [0.23.5] - 2026-05-27
+
+### Added (API host)
+- Ghana Duty logo (PNG) in the landing "built with navii" wall, alongside Elorm UI.
+
+## [0.23.4] - 2026-05-26
+
+### Fixed (API tests)
+- `license/verify` "route not mounted" test expected `404` but the app's catchall `notFound` handler returns `302 → /`. Test updated to match actual behavior. v0.23.3 release pipeline failed on this stale expectation; v0.23.4 reships the `/blog` timeline with the fix.
+
+## [0.23.3] - 2026-05-26 (yanked — test pipeline failed)
+
+### Added (API host)
+- **`/blog` — release timeline.** New page parses `CHANGELOG.md` at request time, surfaces minor+ releases (`x.y.0`) only, links to GitHub release notes per entry. Per-release permalinks at `/blog/v<x.y.z>`. Hero avatar per release derived from the version string. Sitemap includes every release URL. Linked from landing + docs nav.
+
+## [0.23.2] - 2026-05-26
+
+### Changed (docs)
+- Public READMEs (root, `@usenavii/core`, `@usenavii/react`) and the live API reference at `/docs/http-api` + `/docs/sdk-core` now document `AvatarOptions.mood`, the new `Palette` object override on `build()`, and the `?mood=` query param on `/avatar/:seed`. React README memo-deps line corrected to match source (`mood`, `palette`, `styleHint` in; stale `tileBg` claim out).
+- Chore release — image rebuild deploys the updated landing page and `/docs/*` pages to `api.navii.dev`. No npm package contents changed (publish step no-ops on existing versions).
+
 ## [0.23.1] - 2026-05-26
 
 ### Fixed (release)
@@ -20,10 +139,6 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ### Added (API host)
 - `GET /avatar/:seed?mood=happy|serious|sleepy|wink|neutral` — server-side mood overlay. PNG cache key extended with `m=` so moods don't collide.
-
-
-
-### Added (API host)
 - Elorm UI logo (inline SVG, `currentColor`) in the landing "built with navii" wall, sized via new `.logo svg.lg` rule.
 
 ## [0.22.4] - 2026-05-26
@@ -83,7 +198,7 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 - Mono switched to full-bleed squircle (was contained orb) for editorial tile look.
 
 ### Added (API host)
-- **Polar.sh license verification** — `POST /license/verify` now proxies to Polar's `/v1/customer-portal/license-keys/validate` (replaces Gumroad). Validates `status === 'granted'`, expiry, and optional benefit-id match.
+- **Polar.sh license verification** — `POST /license/verify` now proxies to Polar's `/v1/customer-portal/license-keys/validate` (replaces Polar.sh). Validates `status === 'granted'`, expiry, and optional benefit-id match.
 - **`GET /checkout`** — redirects to Polar checkout w/ configured product preselected. Powered by `@polar-sh/hono`.
 - **`GET /portal`** — Polar customer portal proxy (license re-fetch, refund request).
 - **`POST /polar/webhooks`** — signature-verified webhook receiver, logs events.
@@ -92,12 +207,12 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 - 8 new license unit tests w/ fetch mock covering granted/revoked/expired/wrong-product/upstream-error paths.
 
 ### Changed (API host)
-- Privacy page swapped Gumroad references for Polar.sh.
-- `AppOptions` renamed `gumroadProductPermalink` → `polarOrganizationId` + related Polar fields.
+- Privacy page swapped Polar.sh references for Polar.sh.
+- `AppOptions` renamed `Polar.shProductPermalink` → `polarOrganizationId` + related Polar fields.
 
 ### Added (Figma plugin)
 - **Style hint pill row** in Packs panel — Auto / Masc / Femme / Neutral toggle. Persisted via `navii.style` localStorage. Disabled when no pack active.
-- Plugin checkout URL now points at `${API_BASE}/checkout` (instead of hardcoded Gumroad link), letting us swap payment providers without re-publishing.
+- Plugin checkout URL now points at `${API_BASE}/checkout` (instead of hardcoded Polar.sh link), letting us swap payment providers without re-publishing.
 
 ### Fixed (Figma plugin)
 - Left column in Packs panel was not scrollable when content overflowed (e.g. with new Style hint section). Added `overflow-y: auto` + `min-height: 0` to `.col-left`.

package/README.md

@@ -43,13 +43,14 @@ Navii.group([user1.id, user2.id, user3.id]);
 
 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.   |
+| Pass                       | Result                                                      |
+| -------------------------- | ----------------------------------------------------------- |
+| `user.id` / UUID           | ✅ Best. Stable and globally unique.                        |
+| `seedFromEmail(email)`     | ✅ Good. Hashed email — stable, unique, no PII on the wire. |
+| `user.email` (raw)         | ⚠️ Leaks email into URLs, logs, Referer headers. Hash it.   |
+| `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:
 
@@ -58,7 +59,20 @@ const s = Navii.seed({ id: user.id, email: user.email, name: user.name, createdA
 const svg = Navii.create(s);
 ```
 
-It picks the most unique field automatically: `id` → `email` → `name + createdAt` → `name`.
+It picks the most unique field automatically: `id` → `email` → `name + createdAt` → `name`. When the email branch is used it hashes via `seedFromEmail()` by default — pass `{ hashEmail: false }` only to preserve existing raw-email seeds during a migration.
+
+### Using emails as seeds
+
+Raw emails in URLs leak through server logs, Referer headers, browser history, and CDN cache keys. Hash the email — `sha256` of the trimmed + lowercased address:
+
+```ts
+import { seedFromEmail, createAvatar } from '@usenavii/core';
+
+const s = seedFromEmail(user.email);  // sha256 hex, 64 chars
+createAvatar(s);
+```
+
+Two services that both hash with `seedFromEmail()` get the same seed for the same person, so avatars stay consistent across products.
 
 ## API
 
@@ -81,11 +95,43 @@ Navii.{ create, random, render, select, group, seed, build }
 | ------------ | ----------------------------------------------------- | ------------ |
 | `size`       | `number` (px)                                         | `96`         |
 | `paletteId`  | known palette id (e.g. `'mint'`)                      | seed-derived |
+| `palette`    | `Palette` object — runtime/brand palette, no registration in `PALETTES` needed. Wins over `paletteId`. | none |
 | `background` | `'none' \| 'solid' \| 'ring'` or `{ color }`          | seed-derived |
+| `mood`       | `'neutral' \| 'happy' \| 'serious' \| 'sleepy' \| 'wink'` — overrides seed-derived eyes + mouth with a curated pair. Same seed + same mood = byte-identical. Bypasses pack eye/mouth constraints by design. | `'neutral'` |
 | `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`    |
 
+#### Mood overlay
+
+Same seed, four expressions — body / palette / topper stay identical:
+
+```ts
+import { createAvatar } from '@usenavii/core';
+
+createAvatar('alice');                          // neutral (seed-derived)
+createAvatar('alice', { mood: 'happy' });       // wide eyes + smile
+createAvatar('alice', { mood: 'serious' });     // squint + flat mouth
+createAvatar('alice', { mood: 'sleepy' });      // sleepy + dot
+createAvatar('alice', { mood: 'wink' });        // wink + smirk
+```
+
+#### Runtime palette injection (`build()` only)
+
+Pass a `Palette` object (e.g. pulled from Figma variables or design tokens) without registering it in the global `PALETTES` lookup:
+
+```ts
+import { build } from '@usenavii/core';
+
+const acmePalette = {
+  id: 'acme', name: 'Acme Brand',
+  bodyFrom: '#FF5722', bodyTo: '#FFA726',
+  feature: '#1A1A1A', background: '#FFF8F0',
+};
+
+build({ body: 'tall', eyes: 'wide' }, { palette: acmePalette, size: 128 });
+```
+
 ### `random()` — pick a seed for you
 
 For "spin again" UX, onboarding before the user picks an avatar, dev/demo seeding. Returns the chosen seed so you can persist it:

package/dist/index.cjs

@@ -1668,13 +1668,176 @@ function clamp(n, lo, hi) {
   return Math.max(lo, Math.min(hi, n));
 }
 
+// src/sha256.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function rotr(x, n) {
+  return (x >>> n | x << 32 - n) >>> 0;
+}
+function utf8Encode(str) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(str);
+  const out = [];
+  for (let i = 0; i < str.length; i++) {
+    let c = str.charCodeAt(i);
+    if (c < 128) out.push(c);
+    else if (c < 2048) {
+      out.push(192 | c >> 6, 128 | c & 63);
+    } else if (c < 55296 || c >= 57344) {
+      out.push(224 | c >> 12, 128 | c >> 6 & 63, 128 | c & 63);
+    } else {
+      i++;
+      c = 65536 + ((c & 1023) << 10 | str.charCodeAt(i) & 1023);
+      out.push(
+        240 | c >> 18,
+        128 | c >> 12 & 63,
+        128 | c >> 6 & 63,
+        128 | c & 63
+      );
+    }
+  }
+  return new Uint8Array(out);
+}
+function sha256Hex(input) {
+  const msg = utf8Encode(input);
+  const bitLen = msg.length * 8;
+  const padLen = (msg.length + 9 + 63 & -64) - msg.length;
+  const buf = new Uint8Array(msg.length + padLen);
+  buf.set(msg);
+  buf[msg.length] = 128;
+  const dv = new DataView(buf.buffer);
+  dv.setUint32(buf.length - 4, bitLen >>> 0, false);
+  dv.setUint32(buf.length - 8, Math.floor(bitLen / 4294967296), false);
+  const H = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const W = new Uint32Array(64);
+  for (let chunk = 0; chunk < buf.length; chunk += 64) {
+    for (let i = 0; i < 16; i++) W[i] = dv.getUint32(chunk + i * 4, false);
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(W[i - 15], 7) ^ rotr(W[i - 15], 18) ^ W[i - 15] >>> 3;
+      const s1 = rotr(W[i - 2], 17) ^ rotr(W[i - 2], 19) ^ W[i - 2] >>> 10;
+      W[i] = W[i - 16] + s0 + W[i - 7] + s1 >>> 0;
+    }
+    let a = H[0], b = H[1], c = H[2], d = H[3];
+    let e = H[4], f = H[5], g = H[6], h = H[7];
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = e & f ^ ~e & g;
+      const t1 = h + S1 + ch + K[i] + W[i] >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const mj = a & b ^ a & c ^ b & c;
+      const t2 = S0 + mj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + t1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 >>> 0;
+    }
+    H[0] = H[0] + a >>> 0;
+    H[1] = H[1] + b >>> 0;
+    H[2] = H[2] + c >>> 0;
+    H[3] = H[3] + d >>> 0;
+    H[4] = H[4] + e >>> 0;
+    H[5] = H[5] + f >>> 0;
+    H[6] = H[6] + g >>> 0;
+    H[7] = H[7] + h >>> 0;
+  }
+  let out = "";
+  for (let i = 0; i < 8; i++) out += H[i].toString(16).padStart(8, "0");
+  return out;
+}
+
 // src/seed.ts
-function seed(fields) {
+function normalizeEmail(email) {
+  return email.trim().toLowerCase().normalize("NFC");
+}
+function seedFromEmail(email) {
+  if (typeof email !== "string" || email.length === 0) {
+    throw new Error("navii: seedFromEmail() requires a non-empty string");
+  }
+  return sha256Hex(normalizeEmail(email));
+}
+function seed(fields, options = {}) {
+  const hashEmail = options.hashEmail ?? true;
   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;
+    return hashEmail ? seedFromEmail(fields.email) : fields.email;
   }
   if (fields.name && fields.name.length > 0) {
     if (fields.createdAt !== null && fields.createdAt !== void 0) {
@@ -1733,6 +1896,7 @@ var Navii = {
   select: selectAvatar,
   group: renderGroup,
   seed,
+  seedFromEmail,
   build
 };
 
@@ -1743,12 +1907,15 @@ exports.build = build;
 exports.createAvatar = createAvatar;
 exports.createRng = createRng;
 exports.cyrb53 = cyrb53;
+exports.normalizeEmail = normalizeEmail;
 exports.random = random;
 exports.renderAvatar = renderAvatar;
 exports.renderAvatarInner = renderAvatarInner;
 exports.renderGroup = renderGroup;
 exports.resolvePacks = resolvePacks;
 exports.seed = seed;
+exports.seedFromEmail = seedFromEmail;
 exports.selectAvatar = selectAvatar;
+exports.sha256Hex = sha256Hex;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map