@originkit/avatars 0.1.0 → 0.2.0

package/README.md

@@ -30,6 +30,28 @@ In a web page, use an `<img>` with a data URI rather than inline SVG, because in
 <img src={`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`} alt="" width={48} height={48} />
 ```
 
+## Live avatars in React
+
+```jsx
+import { Avatar } from "@originkit/avatars/react";
+
+<Avatar style="glances" name="user-8f3a2c" size={48} />
+```
+
+The same avatars as the studio: they blink, follow the pointer and react to taps. On the server, and until the page runs, `Avatar` shows the still SVG, so nothing jumps. Bots, Blobs, Gummies and Mallows draw in 3D on a WebGL canvas of their own, and show the still where WebGL can't run. Its CSS comes with it, with nothing to import.
+
+| Prop | |
+| --- | --- |
+| `style` | A style id, as `styles` lists them |
+| `name` | What it's generated from |
+| `overrides` | The studio's settings, as its How to use guide prints them |
+| `size` | Width and height, in pixels or any CSS length (96) |
+| `follow` | Whether the eyes follow the pointer (on) |
+| `animate` | Whether it blinks, moves and reacts to taps (on, and off for reduced motion) |
+| `label` | Read out for the image (empty: an avatar beside a name adds nothing) |
+
+React 18 or later. It's an optional peer: the library, the CLI and the MCP server work without it.
+
 ## CLI
 
 Run it with npx, or install it and call `avatars`.

package/dist/controls.d.ts

@@ -86,10 +86,7 @@ export type ControlBuilder = (name: string, overrides: Overrides) => Section[];
  */
 export declare function splitEssentials(sections: Section[], ids: string[]): {
     essentials: Control[];
-    advanced: {
-        title: string;
-        controls: Control[];
-    }[];
+    advanced: Section[];
 };
 export interface Entry {
     label: string;

package/dist/controls.js

@@ -14,13 +14,63 @@ import { colorKey } from "./traits.js";
 export function splitEssentials(sections, ids) {
     const all = sections.flatMap((section) => section.controls);
     const essentials = ids.flatMap((id) => all.filter((control) => control.id === id));
-    const advanced = sections
-        .map((section) => ({
+    const rest = sections.map((section) => ({
         ...section,
         controls: section.controls.filter((control) => !essentials.includes(control)),
-    }))
-        .filter((section) => section.controls.length > 0);
-    return { essentials, advanced };
+    }));
+    return { essentials, advanced: regroup(rest) };
+}
+/**
+ * More options, in the same groups and order for every type. Possibilities leads, with no
+ * heading of its own, as it governs all the rest.
+ */
+const GROUPS = ["", "Shape", "Face", "Details", "Colour", "Container"];
+/** Where a type's own sections land when nothing about a control says otherwise. */
+const FROM_SECTION = {
+    Colour: "Colour",
+    Paint: "Colour",
+    Eyes: "Face",
+    Face: "Face",
+    Words: "Details",
+    Parts: "Details",
+    Accessories: "Details",
+    Hair: "Details",
+    Lines: "Details",
+    Reactions: "Details",
+    Container: "Container",
+};
+/** A control's group, read from what it sets. The type's own sections are only a fallback. */
+function groupOf(control, section) {
+    const id = control.id;
+    if (id === "variance")
+        return "";
+    if (/container/.test(id))
+        return "Container";
+    // A type's Colour section holds only colours, so its word is taken as is.
+    if (FROM_SECTION[section] === "Colour")
+        return "Colour";
+    if (/colou?r|paint|tile|fill|skin|palette|^hue|^tone|ink|fur|^glow|frost|^pool|grain|blend|^mask|speckle/.test(id))
+        return "Colour";
+    if (/hover|effect|hat|glasses|earring|beard|^hair|mark|spots|^top$|^side|straps|studs|topper|holes|wobble|weight|gesture|title|lumps|clothing/.test(id))
+        return "Details";
+    if (/eye|brow|mouth|grin|teeth|^face|mood|feeling|expression|emotion|cheek|nose|blush|iris|formation|gaze|patch/.test(id))
+        return "Face";
+    if (/^pose|mirrored|roundness|angle|^body|^head|width|waist|softness|turn|depth|fluff|stretch/.test(id))
+        return "Shape";
+    return FROM_SECTION[section] ?? (GROUPS.includes(section) ? section : "Shape");
+}
+function regroup(sections) {
+    const groups = new Map();
+    for (const section of sections) {
+        for (const control of section.controls) {
+            const group = groupOf(control, section.title);
+            groups.set(group, [...(groups.get(group) ?? []), control]);
+        }
+    }
+    const rank = (title) => (GROUPS.includes(title) ? GROUPS.indexOf(title) : GROUPS.length);
+    return [...groups]
+        .map(([title, controls]) => ({ title, controls }))
+        .sort((a, b) => rank(a.title) - rank(b.title));
 }
 /** Just below 1, because a position of exactly 1 is past the end of every list. */
 const TOP = 0.999;

package/dist/kinds.js

@@ -44,7 +44,7 @@ export const KINDS = [
         defaultName: "Nova",
         controls: botControls,
         // The container's size and colour join it only while it's on, which may make 8.
-        essentials: ["head", "eye", "paint"],
+        essentials: ["head", "face", "eye", "mouth", "paint"],
         styleKeys: ["head"],
         displayKeys: ["container.size"],
         svg: generateBot,
@@ -72,7 +72,7 @@ export const KINDS = [
         defaultName: "Juju",
         controls: gummyControls,
         // Its colour controls and Possibilities were asked for up front, so it shows 9.
-        essentials: ["body", "face", "glow"],
+        essentials: ["body", "topper", "face", "glow", "gummy.colors"],
         styleKeys: ["body", "face", "topper", "glow"],
         svg: gummySvg,
         parts: gummyParts,
@@ -86,7 +86,7 @@ export const KINDS = [
         controls: mallowControls,
         // Eyes and Pose were asked for up front beside the rest, so it shows 8. As with bots, the
         // container's size and colour join it only while it's on.
-        essentials: ["type", "face", "colour"],
+        essentials: ["type", "face", "eyes", "colour", "mallow.ink"],
         // One bun for every name, as asked, so only its feeling sets variants apart.
         styleKeys: ["face"],
         displayKeys: ["container.size"],
@@ -100,7 +100,7 @@ export const KINDS = [
         hint: "Its eyes follow you. Tap it to see what it does",
         defaultName: "Maya",
         controls: faceControls,
-        essentials: ["eyes", "mouth", "skin"],
+        essentials: ["eyes", "eyebrows", "mouth", "glasses", "skin"],
         styleKeys: ["mouth"],
         svg: faceSvg,
     },
@@ -111,7 +111,7 @@ export const KINDS = [
         hint: "Its eyes follow you. Write anything on it",
         defaultName: "Felix",
         controls: bubbleControls,
-        essentials: ["shape", "mouth", "palette"],
+        essentials: ["shape", "eye.kind", "mouth", "palette", "bubble.colors"],
         styleKeys: ["shape", "palette"],
         svg: bubbleSvg,
     },
@@ -122,7 +122,7 @@ export const KINDS = [
         hint: "Its eyes follow you. Hover over it and it perks up",
         defaultName: "Finn",
         controls: colorControls,
-        essentials: ["hair", "hair.color", "hat.color", "skin"],
+        essentials: ["hair", "hat", "skin", "hair.color", "hat.color"],
         styleKeys: ["hair"],
         svg: (name, overrides) => pixelSvg(name, "color", overrides),
     },
@@ -133,7 +133,7 @@ export const KINDS = [
         hint: "Its eyes follow you. Hover over it and it grows",
         defaultName: "Priya",
         controls: glyphControls,
-        essentials: ["shape", "fill", "tile"],
+        essentials: ["shape", "eyes.kind", "fill", "tile"],
         styleKeys: ["shape"],
         svg: glyphSvg,
     },
@@ -145,7 +145,7 @@ export const KINDS = [
         defaultName: "Milo",
         controls: peekControls,
         // Possibilities was asked for up front beside the rest, so it shows 7.
-        essentials: ["body", "eye.kind", "tile"],
+        essentials: ["body", "pose", "eye.kind", "tile", "peek.colors"],
         styleKeys: ["body", "pose", "tile"],
         svg: peekSvg,
     },
@@ -156,7 +156,7 @@ export const KINDS = [
         hint: "Its eyes follow you. Hover over it and it perks up",
         defaultName: "Kiko",
         controls: doodleControls,
-        essentials: ["mood", "tile", "colourful"],
+        essentials: ["mood", "tile", "colourful", "ink"],
         // Colourful is off until switched on, so Colourway isn't always there to step through.
         styleKeys: ["mood", "tile"],
         svg: doodleSvg,
@@ -168,7 +168,7 @@ export const KINDS = [
         hint: "A cat, a dog, an owl, a bear or a tiger, drawn like the cats. Hover over it and its ears twitch",
         defaultName: "Biscuit",
         controls: animalControls,
-        essentials: ["animal", "mood", "tile"],
+        essentials: ["animal", "mood", "eyes.color", "tile", "fur"],
         styleKeys: ["mood", "ears", "tile"],
         svg: animalSvg,
     },
@@ -181,7 +181,7 @@ export const KINDS = [
         hint: "A tabby or a calico, up to something. Hover over it and its eyes widen",
         defaultName: "Mochi",
         controls: buddyControls,
-        essentials: ["character", "mood", "tile"],
+        essentials: ["character", "mood", "gesture", "tile", "fur"],
         styleKeys: ["gesture", "mood", "tile"],
         svg: buddySvg,
     },
@@ -192,7 +192,7 @@ export const KINDS = [
         hint: "A face put together from bold shapes. Its eyes follow you. Tap it and they hop",
         defaultName: "Lumi",
         controls: shapeControls,
-        essentials: ["eye.left", "eye.right", "mouth", "tile"],
+        essentials: ["eye.left", "eye.right", "mouth", "tile", "colourway"],
         styleKeys: ["eye.left", "eye.right", "mouth", "colourway"],
         svg: shapeSvg,
     },
@@ -203,7 +203,7 @@ export const KINDS = [
         hint: "A monster, a cyclops, a bear, a duck, a chick, an imp or a grump, up close. It watches you and blinks, and pops when tapped",
         defaultName: "Gobo",
         controls: critterControls,
-        essentials: ["kind", "feeling", "body"],
+        essentials: ["kind", "feeling", "eye.style", "body", "iris"],
         // Variants step through the creatures in the generator, as the animals' are different animals.
         styleKeys: ["feeling", "body"],
         svg: critterSvg,
@@ -215,7 +215,7 @@ export const KINDS = [
         hint: "A button of a face, a tile or round, with a big toothy grin. Its googly eyes follow you and blink, and it chomps when tapped",
         defaultName: "Zuzu",
         controls: grinControls,
-        essentials: ["eyes", "mouth", "body"],
+        essentials: ["eyes", "mouth", "teeth", "body"],
         styleKeys: ["eyes", "mouth", "body"],
         svg: grinSvg,
     },
@@ -239,7 +239,7 @@ export const KINDS = [
         hint: "Just two eyes. They follow you, glance about and blink, and pop when tapped",
         defaultName: "Nyx",
         controls: glanceControls,
-        essentials: ["eye.left", "eye.right", "tile"],
+        essentials: ["eye.left", "eye.right", "tile", "ink"],
         styleKeys: ["eye.left", "eye.right", "tile"],
         svg: glanceSvg,
     },
@@ -254,7 +254,7 @@ export const KINDS = [
         controls: auraControls,
         // The type and a sky's horizon were asked for up front beside the rest, as the animals'
         // type is. Formation is only an aura's and Horizon only a sky's, so it shows 7.
-        essentials: ["type", "flow", "palette", "face"],
+        essentials: ["type", "flow", "palette", "aura.colors", "face"],
         // Variants step through the types, formations and palettes themselves, as Mallows do,
         // since each type has palettes of its own. See `stepped` in auras/index.ts.
         styleKeys: [],

package/dist/share.js

@@ -3,7 +3,7 @@
  * query string. Whatever comes back in is untrusted, so anything that doesn't check out is
  * dropped rather than thrown on.
  */
-import { VARIANT_COUNT } from "./variants.js";
+import { MAX_VARIANT } from "./variants.js";
 /** As long as the name box allows. */
 const MAX_NAME = 256;
 const MAX_STRING = 40;
@@ -75,7 +75,7 @@ export function decodeShare(search, sections) {
     return {
         section,
         name: (params.get("n") ?? "").trim().slice(0, MAX_NAME),
-        variant: Number.isInteger(variant) && variant >= 0 && variant < VARIANT_COUNT ? variant : 0,
+        variant: Number.isInteger(variant) && variant >= 0 && variant < MAX_VARIANT ? variant : 0,
         overrides,
     };
 }

package/dist/variants.d.ts

@@ -2,6 +2,8 @@
 import type { AvatarKind } from "./kinds.ts";
 import type { Overrides } from "./traits.ts";
 export declare const VARIANT_COUNT = 8;
+/** The most variants the open tray scrolls to, or a share link may ask for. */
+export declare const MAX_VARIANT = 10000;
 /** The name a variant is generated from. The first is the name itself. */
 export declare const variantName: (name: string, variant: number) => string;
 /**

package/dist/variants.js

@@ -1,6 +1,8 @@
 /** Other takes on the selected avatar, shown in a strip beneath it. */
 import { patched } from "./history.js";
 export const VARIANT_COUNT = 8;
+/** The most variants the open tray scrolls to, or a share link may ask for. */
+export const MAX_VARIANT = 10_000;
 /** Enough for a few names' worth of variants before a typing session starts over. */
 const MAX_REMEMBERED = 256;
 /** The name a variant is generated from. The first is the name itself. */

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@originkit/avatars",
-  "version": "0.1.0",
-  "description": "OriginKit Avatars: turn any name into an avatar. 18 styles, SVG out, with a CLI and an MCP server.",
+  "version": "0.2.0",
+  "description": "OriginKit Avatars: turn any name into an avatar. 18 styles, SVG out, live React avatars, a CLI and an MCP server.",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./react/index.d.ts",
+      "default": "./react/index.js"
     }
   },
   "bin": {
@@ -14,6 +18,7 @@
   },
   "files": [
     "dist",
+    "react",
     "bin",
     "mcp",
     "GUIDE.md",
@@ -21,7 +26,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json && cp ../../LICENSE .",
+    "build": "rm -rf dist && tsc -p tsconfig.json && node scripts/build-react.mjs && cp ../../LICENSE .",
     "test": "node --test \"test/*.test.js\"",
     "prepublishOnly": "npm run build && npm test"
   },
@@ -29,6 +34,15 @@
     "@modelcontextprotocol/sdk": "^1.32.2",
     "zod": "^3.25 || ^4.0"
   },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },

package/react/index.d.ts

@@ -0,0 +1,28 @@
+import type { JSX } from "react";
+
+/** The studio's settings for an avatar, as its How to use guide prints them. */
+export type Overrides = Record<string, number | string>;
+
+export interface AvatarProps {
+  /** A style id, as `styles` from "@originkit/avatars" lists them, such as "bots" or "glances". */
+  style: string;
+  /** What it's generated from. The same name always gives the same avatar. */
+  name: string;
+  /** The studio's settings for it. */
+  overrides?: Overrides;
+  /** Width and height, in pixels or any CSS length. 96 by default. */
+  size?: number | string;
+  /** Whether the eyes follow the pointer. On by default. */
+  follow?: boolean;
+  /** Whether it blinks, moves and reacts to taps. On by default, and off for reduced motion. */
+  animate?: boolean;
+  /** Read out for the image. Empty by default, as an avatar beside a name adds nothing. */
+  label?: string;
+  className?: string;
+}
+
+/**
+ * A live avatar: it blinks, follows the pointer and reacts to taps. On the server, and until
+ * the page is running, it shows the still SVG of the same avatar.
+ */
+export function Avatar(props: AvatarProps): JSX.Element;