@usenavii/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { b as AvatarOptions, c as AvatarSpec } from './types-BlMtdWZf.cjs';
-export { A as AccessoryId, a as AntennaStyleId, B as BackgroundId, d as BodyShapeId, E as EyeStyleId, M as MouthStyleId, P as Palette, T as TopperId } from './types-BlMtdWZf.cjs';
+import { b as AvatarOptions, c as AvatarSpec, d as BodyShapeId, E as EyeStyleId, M as MouthStyleId, a as AntennaStyleId, A as AccessoryId, B as BackgroundId, T as TopperId } from './types-BlMtdWZf.cjs';
+export { P as Palette } from './types-BlMtdWZf.cjs';
 
 /**
  * Seed → stable PRNG stream.
@@ -72,9 +72,136 @@ interface GroupOptions extends AvatarOptions {
 declare function renderGroup(seeds: string[], options?: GroupOptions): string;
 
 /**
- * Convenience: seed → SVG string in one call. Same seed always produces the
- * same output. Pass options to override size, palette, or background.
+ * Seed helper — composes the most stable identifier from a user-shaped
+ * object into a single string for `createAvatar`.
+ *
+ * Priority: `id` → `email` → `name + createdAt` → `name` alone.
+ *
+ * The whole point: stop devs accidentally passing a display name. Names
+ * collide; ids and emails don't. When only a name is available, composing
+ * it with `createdAt` makes the result globally unique while remaining
+ * stable across renders (assuming `createdAt` is set once at signup).
+ */
+interface SeedFields {
+    /** Stable primary key (database id, UUID, OAuth sub). Best choice. */
+    id?: string | number | null | undefined;
+    /** Email. Stable + unique. Good fallback when id isn't available client-side. */
+    email?: string | null | undefined;
+    /** Display name. Collision-prone — only acceptable composed with `createdAt`. */
+    name?: string | null | undefined;
+    /** Account creation time. Combined with `name` to bake uniqueness in at signup. */
+    createdAt?: string | number | Date | null | undefined;
+}
+/**
+ * Compose a stable seed string from the most unique field available.
+ *
+ * @example
+ * ```ts
+ * const s = seed({ id: user.id, email: user.email, name: user.name });
+ * createAvatar(s);
+ * ```
+ *
+ * @example If only a name exists, pass `createdAt` to avoid collisions:
+ * ```ts
+ * seed({ name: 'Alice', createdAt: user.createdAt });
+ * // → "Alice|1700000000000"
+ * ```
+ *
+ * @throws if no usable field is provided.
+ */
+declare function seed(fields: SeedFields): string;
+
+/**
+ * Direct construction of an avatar from explicit part choices — no seed.
+ *
+ * Use when you need a SPECIFIC mascot rather than a deterministic one
+ * derived from a user id. Common uses: brand mascots, logo marks, fixed
+ * tests, designer curation, gallery hero shots.
+ *
+ * Any field left unspecified falls back to its first variant (mostly the
+ * neutral / "none" option). Continuous params default to 0 / 1 (no tweak).
+ */
+interface BuildSpec {
+    palette?: string;
+    body?: BodyShapeId;
+    eyes?: EyeStyleId;
+    mouth?: MouthStyleId;
+    antenna?: AntennaStyleId;
+    accessory?: AccessoryId;
+    background?: BackgroundId;
+    topper?: TopperId;
+    hueShift?: number;
+    bodyScale?: number;
+    eyeGapShift?: number;
+    mouthCurveScale?: number;
+    antennaTilt?: number;
+}
+/**
+ * Build an SVG avatar from explicit part choices.
+ *
+ * @example
+ * ```ts
+ * const svg = build({
+ *   body: 'tall',
+ *   eyes: 'star',
+ *   mouth: 'grin',
+ *   palette: 'violet',
+ *   topper: 'crown',
+ * }, { size: 192 });
+ * ```
+ *
+ * Pass `AvatarOptions` (size, title, animated, tileBg) as the second arg —
+ * same shape as `createAvatar`'s options.
+ */
+declare function build(spec?: BuildSpec, options?: AvatarOptions): string;
+
+/**
+ * Render a deterministic mascot avatar from a seed.
+ *
+ * Same seed in → same SVG out, byte-identical, forever.
+ *
+ * @param seed Stable unique identifier per user. Recommended order: `user.id`
+ *   → UUID → `user.email`. **Avoid display names** — two users called "Alice"
+ *   would get the same avatar. **Never pass `Date.now()`** or any value that
+ *   changes between renders; the avatar would change every refresh.
+ *   See {@link seed} for a helper that picks the right field automatically.
+ *
+ * @param options.size      Output size in px. Default 96. Range 16–1024.
+ * @param options.paletteId Force a color family (e.g. `'mint'`).
+ * @param options.background `'none' | 'solid' | 'ring'` or `{ color }`.
+ * @param options.tileBg    Opaque disc behind the avatar. Color or `'auto'`.
+ * @param options.title     Accessible label (sets `<title>` + `aria-label`).
+ * @param options.animated  Emit idle motion (float, blink, sway, twinkle).
+ *
+ * @returns Self-contained `<svg>` string. Safe to embed via `<img src="data:image/svg+xml;...">`
+ *   or to insert into the DOM directly.
+ *
+ * @example
+ * ```ts
+ * const svg = createAvatar(user.id, { size: 96, animated: true });
+ * ```
  */
 declare function createAvatar(seed: string, options?: AvatarOptions): string;
+/**
+ * Convenience namespace — bundles every public function under one import.
+ *
+ * @example
+ * ```ts
+ * import { Navii } from '@usenavii/core';
+ *
+ * Navii.create(user.id);
+ * Navii.seed({ id: user.id, email: user.email });
+ * Navii.build({ body: 'tall', eyes: 'star', palette: 'violet' });
+ * Navii.group([user1.id, user2.id, user3.id]);
+ * ```
+ */
+declare const Navii: {
+    readonly create: typeof createAvatar;
+    readonly render: typeof renderAvatar;
+    readonly select: typeof selectAvatar;
+    readonly group: typeof renderGroup;
+    readonly seed: typeof seed;
+    readonly build: typeof build;
+};
 
-export { AvatarOptions, AvatarSpec, type GroupOptions, createAvatar, createRng, cyrb53, renderAvatar, renderAvatarInner, renderGroup, selectAvatar };
+export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, type SeedFields, TopperId, build, createAvatar, createRng, cyrb53, renderAvatar, renderAvatarInner, renderGroup, seed, selectAvatar };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { b as AvatarOptions, c as AvatarSpec } from './types-BlMtdWZf.js';
-export { A as AccessoryId, a as AntennaStyleId, B as BackgroundId, d as BodyShapeId, E as EyeStyleId, M as MouthStyleId, P as Palette, T as TopperId } from './types-BlMtdWZf.js';
+import { b as AvatarOptions, c as AvatarSpec, d as BodyShapeId, E as EyeStyleId, M as MouthStyleId, a as AntennaStyleId, A as AccessoryId, B as BackgroundId, T as TopperId } from './types-BlMtdWZf.js';
+export { P as Palette } from './types-BlMtdWZf.js';
 
 /**
  * Seed → stable PRNG stream.
@@ -72,9 +72,136 @@ interface GroupOptions extends AvatarOptions {
 declare function renderGroup(seeds: string[], options?: GroupOptions): string;
 
 /**
- * Convenience: seed → SVG string in one call. Same seed always produces the
- * same output. Pass options to override size, palette, or background.
+ * Seed helper — composes the most stable identifier from a user-shaped
+ * object into a single string for `createAvatar`.
+ *
+ * Priority: `id` → `email` → `name + createdAt` → `name` alone.
+ *
+ * The whole point: stop devs accidentally passing a display name. Names
+ * collide; ids and emails don't. When only a name is available, composing
+ * it with `createdAt` makes the result globally unique while remaining
+ * stable across renders (assuming `createdAt` is set once at signup).
+ */
+interface SeedFields {
+    /** Stable primary key (database id, UUID, OAuth sub). Best choice. */
+    id?: string | number | null | undefined;
+    /** Email. Stable + unique. Good fallback when id isn't available client-side. */
+    email?: string | null | undefined;
+    /** Display name. Collision-prone — only acceptable composed with `createdAt`. */
+    name?: string | null | undefined;
+    /** Account creation time. Combined with `name` to bake uniqueness in at signup. */
+    createdAt?: string | number | Date | null | undefined;
+}
+/**
+ * Compose a stable seed string from the most unique field available.
+ *
+ * @example
+ * ```ts
+ * const s = seed({ id: user.id, email: user.email, name: user.name });
+ * createAvatar(s);
+ * ```
+ *
+ * @example If only a name exists, pass `createdAt` to avoid collisions:
+ * ```ts
+ * seed({ name: 'Alice', createdAt: user.createdAt });
+ * // → "Alice|1700000000000"
+ * ```
+ *
+ * @throws if no usable field is provided.
+ */
+declare function seed(fields: SeedFields): string;
+
+/**
+ * Direct construction of an avatar from explicit part choices — no seed.
+ *
+ * Use when you need a SPECIFIC mascot rather than a deterministic one
+ * derived from a user id. Common uses: brand mascots, logo marks, fixed
+ * tests, designer curation, gallery hero shots.
+ *
+ * Any field left unspecified falls back to its first variant (mostly the
+ * neutral / "none" option). Continuous params default to 0 / 1 (no tweak).
+ */
+interface BuildSpec {
+    palette?: string;
+    body?: BodyShapeId;
+    eyes?: EyeStyleId;
+    mouth?: MouthStyleId;
+    antenna?: AntennaStyleId;
+    accessory?: AccessoryId;
+    background?: BackgroundId;
+    topper?: TopperId;
+    hueShift?: number;
+    bodyScale?: number;
+    eyeGapShift?: number;
+    mouthCurveScale?: number;
+    antennaTilt?: number;
+}
+/**
+ * Build an SVG avatar from explicit part choices.
+ *
+ * @example
+ * ```ts
+ * const svg = build({
+ *   body: 'tall',
+ *   eyes: 'star',
+ *   mouth: 'grin',
+ *   palette: 'violet',
+ *   topper: 'crown',
+ * }, { size: 192 });
+ * ```
+ *
+ * Pass `AvatarOptions` (size, title, animated, tileBg) as the second arg —
+ * same shape as `createAvatar`'s options.
+ */
+declare function build(spec?: BuildSpec, options?: AvatarOptions): string;
+
+/**
+ * Render a deterministic mascot avatar from a seed.
+ *
+ * Same seed in → same SVG out, byte-identical, forever.
+ *
+ * @param seed Stable unique identifier per user. Recommended order: `user.id`
+ *   → UUID → `user.email`. **Avoid display names** — two users called "Alice"
+ *   would get the same avatar. **Never pass `Date.now()`** or any value that
+ *   changes between renders; the avatar would change every refresh.
+ *   See {@link seed} for a helper that picks the right field automatically.
+ *
+ * @param options.size      Output size in px. Default 96. Range 16–1024.
+ * @param options.paletteId Force a color family (e.g. `'mint'`).
+ * @param options.background `'none' | 'solid' | 'ring'` or `{ color }`.
+ * @param options.tileBg    Opaque disc behind the avatar. Color or `'auto'`.
+ * @param options.title     Accessible label (sets `<title>` + `aria-label`).
+ * @param options.animated  Emit idle motion (float, blink, sway, twinkle).
+ *
+ * @returns Self-contained `<svg>` string. Safe to embed via `<img src="data:image/svg+xml;...">`
+ *   or to insert into the DOM directly.
+ *
+ * @example
+ * ```ts
+ * const svg = createAvatar(user.id, { size: 96, animated: true });
+ * ```
  */
 declare function createAvatar(seed: string, options?: AvatarOptions): string;
+/**
+ * Convenience namespace — bundles every public function under one import.
+ *
+ * @example
+ * ```ts
+ * import { Navii } from '@usenavii/core';
+ *
+ * Navii.create(user.id);
+ * Navii.seed({ id: user.id, email: user.email });
+ * Navii.build({ body: 'tall', eyes: 'star', palette: 'violet' });
+ * Navii.group([user1.id, user2.id, user3.id]);
+ * ```
+ */
+declare const Navii: {
+    readonly create: typeof createAvatar;
+    readonly render: typeof renderAvatar;
+    readonly select: typeof selectAvatar;
+    readonly group: typeof renderGroup;
+    readonly seed: typeof seed;
+    readonly build: typeof build;
+};
 
-export { AvatarOptions, AvatarSpec, type GroupOptions, createAvatar, createRng, cyrb53, renderAvatar, renderAvatarInner, renderGroup, selectAvatar };
+export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, type SeedFields, TopperId, build, createAvatar, createRng, cyrb53, renderAvatar, renderAvatarInner, renderGroup, seed, selectAvatar };

package/dist/index.js

@@ -13,9 +13,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;
@@ -621,8 +621,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);
@@ -646,7 +646,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,
@@ -775,9 +775,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) {
@@ -801,9 +801,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>
@@ -825,14 +825,63 @@ 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
+};
 
-export { createAvatar, createRng, cyrb53, renderAvatar, renderAvatarInner, renderGroup, selectAvatar };
+export { Navii, build, createAvatar, createRng, cyrb53, renderAvatar, renderAvatarInner, renderGroup, seed, selectAvatar };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map