@originkit/avatars 0.0.0-stage → 0.2.0

package/dist/shapes/controls.d.ts

@@ -0,0 +1,2 @@
+import { type ControlBuilder } from "../controls.ts";
+export declare const controls: ControlBuilder;

package/dist/shapes/controls.js

@@ -0,0 +1,41 @@
+import { choice, clearingColor, palette, slider } from "../controls.js";
+import { COLOURWAYS } from "../doodles/index.js";
+import { calmed, narrowed, possibilitiesSlider } from "../possibilities.js";
+import { colorKey, createTraits } from "../traits.js";
+import { CALMING, NOTES } from "./calming.js";
+import { coloursOf, EYES, MOUTHS, PARTS, TILES } from "./index.js";
+const named = (list) => list.map(({ name: label }) => ({ label }));
+export const controls = (name, overrides) => {
+    const t = calmed(createTraits(name, overrides), CALMING);
+    const list = (control) => narrowed(control, t, CALMING);
+    const { parts } = coloursOf(t);
+    return [
+        {
+            title: "Face",
+            controls: [
+                list(choice(t, "eye.left", "Left eye", "list", named(EYES))),
+                list(choice(t, "eye.right", "Right eye", "list", named(EYES))),
+                list(choice(t, "mouth", "Mouth", "list", named(MOUTHS))),
+                possibilitiesSlider(t, NOTES),
+                slider(t, "eye.size", "Eye size", 0, 100, "%"),
+                slider(t, "eye.gap", "Eye gap", 0, 100, "%"),
+                slider(t, "mouth.size", "Mouth size", 0, 100, "%"),
+                slider(t, "mouth.y", "Mouth drop", 0, 100, "%"),
+                slider(t, "weight", "Weight", 0, 100, "%"),
+                slider(t, "tilt", "Tilt", -5, 5, "°"),
+            ],
+        },
+        {
+            title: "Colour",
+            controls: [
+                palette(t, "tile", "Tile", TILES),
+                // A new colourway starts from its own colours, not the ones set by hand for the last.
+                PARTS.reduce(clearingColor, choice(t, "colourway", "Colourway", "swatches", COLOURWAYS.map(({ label, colors }) => ({
+                    label,
+                    color: `conic-gradient(${colors.map((color, i) => `${color} 0 ${(i + 1) * 25}%`).join(", ")})`,
+                })))),
+                { type: "colors", id: "colours", label: "Colours", colors: PARTS.map((part) => ({ id: colorKey(part), color: parts[part] })) },
+            ],
+        },
+    ];
+};

package/dist/shapes/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shapes: a face put together from three bold shapes, as in the reference. Each eye and
+ * the mouth is one fat stroke with round ends along a short skeleton, all at one weight,
+ * so a cloud, a donut and a smile read as one set. Each part comes from its own list in
+ * its own colour, so a few short lists make a great many faces.
+ */
+import { type Overrides, type Traits } from "../traits.ts";
+/** Paper. The first is the reference's. */
+export declare const TILES: string[];
+/** Scales a skeleton drawn in units of its reach. */
+type At = (x: number, y: number) => string;
+interface Part {
+    name: string;
+    /** How far it reaches from its middle, stroke and all: across for an eye, up for a mouth. */
+    span(a: number, w: number): number;
+    /** Markup around the origin, from the skeleton's reach `a` and the stroke's width `w`. */
+    draw(at: At, a: number, w: number): string;
+}
+/** Drawn facing right, towards the nose, for the left eye. The right eye is a mirror image. */
+export declare const EYES: Part[];
+/** In units of the mouth's half width. Neighbours are unlike, as each variant steps to the next. */
+export declare const MOUTHS: Part[];
+/** Each with a colour of its own, which can be picked by hand. */
+export declare const PARTS: string[];
+/** Each name takes three of its colourway's four, in its own order, as the reference does. */
+export declare function coloursOf(t: Traits): {
+    tile: string;
+    parts: Record<string, string>;
+};
+export interface ShapeFace {
+    tile: string;
+    /** Where the face sits and its tilt. */
+    face: string;
+    /** The one stroke weight every shape is drawn in. */
+    weight: number;
+    /** Each part sits in a group that places it, around one that is free to move about its middle. */
+    eyes: string;
+    mouth: string;
+    blinkDelay: number;
+}
+export declare function createShapeFace(name: string, overrides?: Overrides): ShapeFace;
+/** The face at rest, for thumbnails. */
+export declare const shapeSvg: (name: string, overrides?: Overrides) => string;
+export {};

package/dist/shapes/index.js

@@ -0,0 +1,104 @@
+/**
+ * Shapes: a face put together from three bold shapes, as in the reference. Each eye and
+ * the mouth is one fat stroke with round ends along a short skeleton, all at one weight,
+ * so a cloud, a donut and a smile read as one set. Each part comes from its own list in
+ * its own colour, so a few short lists make a great many faces.
+ */
+import { contrast } from "../colors.js";
+import { COLOURWAYS, INK_STYLE } from "../doodles/index.js";
+import { calmed } from "../possibilities.js";
+import { createTraits } from "../traits.js";
+import { CALMING } from "./calming.js";
+/** Paper. The first is the reference's. */
+export const TILES = ["#f9f8f4", "#ffffff", "#fbefe6", "#edf5ef", "#ecf1f8", "#f4eef8", "#fff5d6", "#f1efe9"];
+const round2 = (value) => Math.round(value * 100) / 100;
+const line = (d) => `<path d="${d}" fill="none"/>`;
+/** Filled as well as stroked. Left open, the stroke skips the closing edge, as a heart's notch needs. */
+const solid = (d) => `<path d="${d}"/>`;
+/** A ring always keeps a hole, however heavy the stroke. */
+const ringRadius = (r, w) => Math.max(r, w / 2 + 2.2);
+const ring = (r, w) => `<circle r="${round2(ringRadius(r, w))}" fill="none"/>`;
+const by = (reach) => (a, w) => reach * a + w / 2;
+/** Drawn facing right, towards the nose, for the left eye. The right eye is a mirror image. */
+export const EYES = [
+    { name: "Donut", span: (a, w) => ringRadius(a, w) + w / 2, draw: (_at, a, w) => ring(a, w) },
+    { name: "Chevron", span: by(0.45), draw: (at) => line(`M${at(-0.45, -0.85)}L${at(0.45, 0)}L${at(-0.45, 0.85)}`) },
+    { name: "Disc", span: by(0.85), draw: (_at, a) => `<circle r="${round2(a * 0.85)}"/>` },
+    // The reference's: a flat bar with a bump, sloping down to its end.
+    { name: "Cloud", span: by(1.15), draw: (at) => line(`M${at(-1.15, 0.5)}L${at(1.15, 0.5)}L${at(0.15, -0.5)}`) },
+    { name: "Plus", span: by(0.85), draw: (at) => line(`M${at(-0.85, 0)}L${at(0.85, 0)}M${at(0, -0.85)}L${at(0, 0.85)}`) },
+    { name: "Arch", span: by(1), draw: (at) => line(`M${at(-1, 0.35)}Q${at(0, -1.05)} ${at(1, 0.35)}`) },
+    { name: "Square", span: by(0.6), draw: (at) => solid(`M${at(-0.6, -0.6)}L${at(0.6, -0.6)}L${at(0.6, 0.6)}L${at(-0.6, 0.6)}Z`) },
+    { name: "Pill", span: by(0), draw: (at) => line(`M${at(0, -0.75)}L${at(0, 0.75)}`) },
+    { name: "Heart", span: by(0.7), draw: (at) => solid(`M${at(-0.7, -0.3)}L${at(0, 0.5)}L${at(0.7, -0.3)}`) },
+    { name: "Dash", span: by(0.8), draw: (at) => line(`M${at(-0.8, 0)}L${at(0.8, 0)}`) },
+    { name: "Triangle", span: by(0.8), draw: (at) => solid(`M${at(0, -0.75)}L${at(0.8, 0.55)}L${at(-0.8, 0.55)}Z`) },
+    { name: "Leaf", span: by(0.75), draw: (at) => solid(`M${at(-0.75, 0.75)}Q${at(-0.6, -0.6)} ${at(0.75, -0.75)}Q${at(0.6, 0.6)} ${at(-0.75, 0.75)}Z`) },
+    { name: "Dome", span: by(0.85), draw: (at, a) => solid(`M${at(-0.85, 0.42)}A${round2(a * 0.85)} ${round2(a * 0.85)} 0 0 1 ${at(0.85, 0.42)}Z`) },
+];
+/** In units of the mouth's half width. Neighbours are unlike, as each variant steps to the next. */
+export const MOUTHS = [
+    { name: "Smile", span: by(0.2), draw: (at, a) => line(`M${at(-1, -0.2)}A${round2(a * 1.4)} ${round2(a * 1.4)} 0 0 0 ${at(1, -0.2)}`) },
+    { name: "Oh", span: (a, w) => a * 0.1 + w, draw: (_at, a, w) => ring(a * 0.1 + w / 2, w) },
+    { name: "Flat", span: by(0), draw: (at) => line(`M${at(-0.65, 0)}L${at(0.65, 0)}`) },
+    { name: "Grin", span: by(0.25), draw: (at, a) => solid(`M${at(-0.8, -0.25)}L${at(0.8, -0.25)}A${round2(a * 0.8)} ${round2(a * 0.55)} 0 0 1 ${at(-0.8, -0.25)}Z`) },
+    { name: "Wave", span: by(0.25), draw: (at) => line(`M${at(-1, 0)}Q${at(-0.5, -0.45)} ${at(0, 0)}T${at(1, 0)}`) },
+    { name: "Peep", span: by(0.12), draw: (_at, a) => `<circle r="${round2(a * 0.12)}"/>` },
+    { name: "Frown", span: by(0.15), draw: (at, a) => line(`M${at(-0.7, 0.25)}A${round2(a)} ${round2(a)} 0 0 1 ${at(0.7, 0.25)}`) },
+    { name: "Shout", span: by(0.25), draw: (at) => solid(`M${at(-0.6, -0.25)}L${at(0.6, -0.25)}L${at(0.3, 0.25)}L${at(-0.3, 0.25)}Z`) },
+    { name: "Smirk", span: by(0.25), draw: (at) => line(`M${at(-0.6, 0.05)}Q${at(0.25, 0.3)} ${at(0.7, -0.25)}`) },
+    { name: "Cat", span: by(0.1), draw: (at) => line(`M${at(-0.8, -0.1)}Q${at(-0.4, 0.35)} ${at(0, 0)}Q${at(0.4, 0.35)} ${at(0.8, -0.1)}`) },
+];
+/** Each with a colour of its own, which can be picked by hand. */
+export const PARTS = ["left", "right", "mouth"];
+/** Each name takes three of its colourway's four, in its own order, as the reference does. */
+export function coloursOf(t) {
+    const tile = t.color("tile") ?? t.pick("tile", TILES);
+    // The spare colour stands in for one that would fade into the tile, as yellow does on yellow.
+    const order = t.pick("colourway", COLOURWAYS).colors
+        .map((color, i) => [t(`colourway.${i}`) + (contrast(color, tile) < 1.5 ? 1 : 0), color])
+        .sort(([a], [b]) => a - b);
+    return { tile, parts: Object.fromEntries(PARTS.map((part, i) => [part, t.color(part) ?? order[i][1]])) };
+}
+const scaled = (a) => (x, y) => `${round2(x * a)} ${round2(y * a)}`;
+export function createShapeFace(name, overrides) {
+    const t = calmed(createTraits(name, overrides), CALMING);
+    const { tile, parts } = coloursOf(t);
+    const size = t.num("eye.size", 13, 17);
+    // In proportion to the eyes, so a heavy stroke never fills a small shape in.
+    const w = size * t.num("weight", 0.68, 0.9);
+    const gap = t.num("eye.gap", 1.5, 6);
+    const eyes = [-1, 1].map((side, i) => {
+        const shape = t.pick(i ? "eye.right" : "eye.left", EYES);
+        const r = size * (1 + t.jitter(`eye${i}.size`, 0.14));
+        const a = Math.max(r - w / 2, r * 0.45);
+        return { side, shape, r, a, dy: t.jitter(`eye${i}.y`, 1.8), x: side * (gap + Math.max(shape.span(a, w), r * 0.8)) };
+    });
+    const mouth = t.pick("mouth", MOUTHS);
+    const m = t.num("mouth.size", 19, 28);
+    const rise = mouth.span(m, w);
+    const above = Math.max(...eyes.map(({ r, dy }) => r - dy));
+    const drop = Math.max(...eyes.map(({ r, dy }) => r + dy)) + t.num("mouth.y", 5, 13) + rise;
+    // Taking the mouth to be about as deep as it is tall above its middle. A wide or tall
+    // face is shrunk to fit the tile, stroke and all, so it keeps its proportions.
+    const across = Math.max(...eyes.map(({ x, shape, a }) => Math.abs(x) + shape.span(a, w)), m + w / 2) * 2;
+    const fit = Math.min(1, 80 / across, 76 / (above + drop + rise));
+    const placed = (transform, color, markup) => `<g transform="${transform}" color="${color}"><g>${markup}</g></g>`;
+    const flip = t("mouth.flip") < 0.5 ? -1 : 1;
+    return {
+        tile,
+        face: `translate(50 50) scale(${round2(fit)}) rotate(${round2(t.jitter("tilt", 5))}) translate(0 ${round2((above - drop - rise) / 2)})`,
+        weight: round2(w),
+        eyes: eyes
+            .map(({ side, shape, a, x, dy }, i) => placed(`translate(${round2(x)} ${round2(dy)}) rotate(${round2(t.jitter(`eye${i}.turn`, 10))}) scale(${-side} 1)`, parts[PARTS[i]], shape.draw(scaled(a), a, w)))
+            .join(""),
+        mouth: placed(`translate(0 ${round2(drop)}) scale(${flip} 1)`, parts.mouth, mouth.draw(scaled(m), m, w)),
+        blinkDelay: t.num("blink", 0, 4),
+    };
+}
+/** The face at rest, for thumbnails. */
+export const shapeSvg = (name, overrides) => {
+    const face = createShapeFace(name, overrides);
+    return (`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><rect width="100" height="100" rx="22.22" fill="${face.tile}"/>` +
+        `<g transform="${face.face}" ${INK_STYLE(face.weight)}>${face.eyes}${face.mouth}</g></svg>`);
+};

package/dist/share.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The selected avatar as a link: its section, name, variant and hand-set overrides in the
+ * query string. Whatever comes back in is untrusted, so anything that doesn't check out is
+ * dropped rather than thrown on.
+ */
+import type { Overrides } from "./traits.ts";
+export interface Shared {
+    section: string;
+    /** The typed name, or empty for the section's own. */
+    name: string;
+    variant: number;
+    overrides: Overrides;
+}
+/** The query string, without its `?`. */
+export declare function encodeShare({ section, name, variant, overrides }: Shared): string;
+/** Only the values that are safe to draw with: see the rules above each branch. */
+export declare function cleanOverrides(raw: unknown): Overrides;
+/** What a query string says, for a section in `sections`, or null if it names none. */
+export declare function decodeShare(search: string, sections: readonly string[]): Shared | null;
+/** `<section>-<name>.<ext>`, with anything a file system might refuse swapped for dashes. */
+export declare const fileName: (section: string, name: string, ext: string) => string;

package/dist/share.js

@@ -0,0 +1,83 @@
+/**
+ * The selected avatar as a link: its section, name, variant and hand-set overrides in the
+ * query string. Whatever comes back in is untrusted, so anything that doesn't check out is
+ * dropped rather than thrown on.
+ */
+import { MAX_VARIANT } from "./variants.js";
+/** As long as the name box allows. */
+const MAX_NAME = 256;
+const MAX_STRING = 40;
+const MAX_KEYS = 64;
+/** Well past any real set of overrides, so a giant link isn't decoded at all. */
+const MAX_ENCODED = 4096;
+const KEY = /^[a-z][\w.:-]{0,63}$/i;
+const TOP = 1 - Number.EPSILON;
+const toBase64Url = (text) => btoa(String.fromCharCode(...new TextEncoder().encode(text))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const fromBase64Url = (code) => new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(atob(code.replace(/-/g, "+").replace(/_/g, "/")), (char) => char.charCodeAt(0)));
+/** The query string, without its `?`. */
+export function encodeShare({ section, name, variant, overrides }) {
+    const params = new URLSearchParams({ s: section });
+    if (name)
+        params.set("n", name);
+    if (variant)
+        params.set("v", String(variant));
+    if (Object.keys(overrides).length)
+        params.set("o", toBase64Url(JSON.stringify(overrides)));
+    return params.toString();
+}
+/** Only the values that are safe to draw with: see the rules above each branch. */
+export function cleanOverrides(raw) {
+    const clean = {};
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return clean;
+    for (const [key, value] of Object.entries(raw).slice(0, MAX_KEYS)) {
+        if (!KEY.test(key))
+            continue;
+        if (key.startsWith("color:")) {
+            // A colour picked by hand is 0xRRGGBB.
+            if (Number.isInteger(value) && value >= 0 && value <= 0xffffff)
+                clean[key] = value;
+        }
+        else if (typeof value === "number") {
+            // Every other number is a position in [0, 1).
+            if (Number.isFinite(value))
+                clean[key] = Math.min(TOP, Math.max(0, value));
+        }
+        else if (typeof value === "string") {
+            clean[key] = value.slice(0, MAX_STRING);
+        }
+    }
+    return clean;
+}
+/** What a query string says, for a section in `sections`, or null if it names none. */
+export function decodeShare(search, sections) {
+    let params;
+    try {
+        params = new URLSearchParams(search);
+    }
+    catch {
+        return null;
+    }
+    const section = params.get("s") ?? "";
+    if (!sections.includes(section))
+        return null;
+    const variant = Number(params.get("v") ?? 0);
+    let overrides = {};
+    const code = params.get("o");
+    if (code && code.length <= MAX_ENCODED) {
+        try {
+            overrides = cleanOverrides(JSON.parse(fromBase64Url(code)));
+        }
+        catch {
+            // A broken link still opens the section, just without its tweaks.
+        }
+    }
+    return {
+        section,
+        name: (params.get("n") ?? "").trim().slice(0, MAX_NAME),
+        variant: Number.isInteger(variant) && variant >= 0 && variant < MAX_VARIANT ? variant : 0,
+        overrides,
+    };
+}
+/** `<section>-<name>.<ext>`, with anything a file system might refuse swapped for dashes. */
+export const fileName = (section, name, ext) => `${section}-${name.replace(/[\\/:*?"<>|\s\u0000-\u001f]+/g, "-").slice(0, 64) || "avatar"}.${ext}`;

package/dist/traits.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Turns a name into independent random-looking values.
+ *
+ * The name is hashed once, then each trait key continues from that state, so
+ * every trait is stable and unrelated to the others. Adding a new trait later
+ * cannot change an existing avatar.
+ */
+export interface Traits {
+    /** Uniform float in [0, 1). */
+    (key: string): number;
+    /** Uniform float in [min, max). */
+    num(key: string, min: number, max: number): number;
+    /** Uniform integer in [min, max]. */
+    int(key: string, min: number, max: number): number;
+    /** Symmetric offset in [-amount, amount). */
+    jitter(key: string, amount: number): number;
+    /** Uniform choice. Changing `options` remaps every name, so treat lists as frozen. */
+    pick<T>(key: string, options: readonly T[]): T;
+    /** The value fixed for `key`, if any, for things that are otherwise worked out. */
+    forced(key: string): number | undefined;
+    /** The colour picked by hand for `key`, if any, which wins over whatever the name gives. */
+    color(key: string): string | undefined;
+    /** The words typed in for `key`, if any. */
+    text(key: string): string | undefined;
+}
+/**
+ * Traits fixed by hand, by key. Each value is the position in [0, 1) the name would
+ * otherwise have hashed to, so a generator cannot tell the two apart. The exceptions
+ * are a colour picked by hand, kept beside its trait as `0xrrggbb` under `colorKey`,
+ * and typed words, which are strings.
+ */
+export type Overrides = Record<string, number | string>;
+export declare const colorKey: (key: string) => string;
+export declare function createTraits(name: string, overrides?: Overrides): Traits;

package/dist/traits.js

@@ -0,0 +1,58 @@
+/**
+ * Turns a name into independent random-looking values.
+ *
+ * The name is hashed once, then each trait key continues from that state, so
+ * every trait is stable and unrelated to the others. Adding a new trait later
+ * cannot change an existing avatar.
+ */
+import { intToHex } from "./colors.js";
+const SEPARATOR = 0xff;
+const utf8 = new TextEncoder();
+function feed(hash, bytes) {
+    for (const byte of bytes) {
+        hash = Math.imul(hash ^ byte, 3432918353);
+        hash = (hash << 13) | (hash >>> 19);
+    }
+    return hash;
+}
+/** murmur3 fmix32: makes one changed letter produce an unrelated result. */
+function finalize(hash) {
+    hash = Math.imul(hash ^ (hash >>> 16), 2246822507);
+    hash = Math.imul(hash ^ (hash >>> 13), 3266489909);
+    return (hash ^ (hash >>> 16)) >>> 0;
+}
+/** Names a person would call equal must hash equal. */
+function normalize(name) {
+    return name.normalize("NFC").trim().toLowerCase();
+}
+const COLOR_PREFIX = "color:";
+export const colorKey = (key) => `${COLOR_PREFIX}${key}`;
+export function createTraits(name, overrides = {}) {
+    const seed = normalize(name);
+    const state = feed(1779033703 ^ seed.length, utf8.encode(seed));
+    // Overrides can come from a link or an API call, so anything that isn't the type
+    // a generator expects is treated as unset rather than reaching the markup.
+    const fixed = (key) => {
+        const value = overrides[key];
+        return typeof value === "number" && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : undefined;
+    };
+    const t = ((key) => fixed(key) ?? finalize(feed(feed(state, Uint8Array.of(SEPARATOR)), utf8.encode(key))) / 2 ** 32);
+    // A slider at its far end fixes exactly 1, which must still land on the last option.
+    const index = (key, count) => Math.min(count - 1, Math.floor(t(key) * count));
+    t.num = (key, min, max) => min + t(key) * (max - min);
+    t.int = (key, min, max) => min + index(key, max - min + 1);
+    t.jitter = (key, amount) => (t(key) * 2 - 1) * amount;
+    t.pick = (key, options) => options[index(key, options.length)];
+    t.forced = fixed;
+    t.color = (key) => {
+        const picked = overrides[colorKey(key)];
+        return Number.isInteger(picked) && picked >= 0 && picked <= 0xffffff
+            ? intToHex(picked)
+            : undefined;
+    };
+    t.text = (key) => {
+        const words = overrides[key];
+        return typeof words === "string" ? words : undefined;
+    };
+    return t;
+}

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+export interface Colors {
+    body: string;
+    accent: string;
+    visor: string;
+    light: string;
+}
+/**
+ * A part as numbers, in the 100×100 viewBox, so the 3D shader can draw its outline exactly
+ * rather than from a picture of it. Degrees for `rot`, clockwise. A superellipse with a
+ * `stroke` is only its outline, that thick either side. A curve is a quadratic Bézier
+ * stroke with round ends, through `cx` `cy` as its control point.
+ */
+export type Shape = {
+    kind: "superellipse";
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+    n: number;
+    rot: number;
+    stroke?: number;
+} | {
+    kind: "crescent";
+    cx: number;
+    cy: number;
+    width: number;
+    lift: number;
+    thickness: number;
+} | {
+    kind: "rod";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    r: number;
+} | {
+    kind: "circle";
+    cx: number;
+    cy: number;
+    r: number;
+} | {
+    kind: "curve";
+    x1: number;
+    y1: number;
+    cx: number;
+    cy: number;
+    x2: number;
+    y2: number;
+    r: number;
+};
+/** An avatar as layers of paths, which is everything the 3D renderer needs. */
+export interface AvatarParts {
+    colors: Colors;
+    head: string[];
+    accents: string[];
+    visor: string[];
+    /** The lights that blink, as paths for still pictures and as shapes for 3D. */
+    eyes: string[];
+    eyeShapes: Shape[];
+    /** Any other lights, such as a mouth, which stay put through a blink. */
+    lights: string[];
+    lightShapes: Shape[];
+    /** The dark glass, as shapes for 3D. */
+    visorShapes: Shape[];
+    /** Polished metal, raised slightly from the skin. */
+    chrome: string[];
+    chromeShapes: Shape[];
+    /** Small dark domes. */
+    studs: string[];
+    studShapes: Shape[];
+    /** How thickly the paint is flecked, from 0 to 1. */
+    speckle: number;
+    /** The height of the eyes, which a blink closes towards. */
+    eyeY: number;
+    /** A card behind the avatar, which it stays inside: its side as a share of the slot's. */
+    container?: {
+        size: number;
+        color: string;
+    };
+    /** The lights are eyes painted on the skin, rather than glowing behind a visor. */
+    painted?: boolean;
+    /**
+     * A frosted shell lit from inside, with the accent as a pearly topper, rather than paint:
+     * how milky the shell is, from 0 (the body's colour) to 1 (white), and the glow's size.
+     */
+    jelly?: {
+        frost: number;
+        pool: number;
+    };
+    /** Soft-touch clay: pastel and matte, with no gloss. */
+    matte?: boolean;
+    /** Clay pieces pressed onto the front of the body, such as hands, which stand proud of it. */
+    raised?: string[];
+    /** On clay, white glints that blink and look with the eyes, and marks in the visor's colour. */
+    shineShapes?: Shape[];
+    tintShapes?: Shape[];
+    /** On clay, the whites of the eyes, under the eyes themselves, which blink but don't look about. */
+    whiteShapes?: Shape[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/variants.d.ts

@@ -0,0 +1,13 @@
+/** Other takes on the selected avatar, shown in a strip beneath it. */
+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;
+/**
+ * The overrides to draw a variant with. Anything set by hand wins over its style. The
+ * result is remembered, so the same variant is the same object and memoised work holds.
+ */
+export declare function variantOverrides(kind: AvatarKind, name: string, variant: number, overrides: Overrides): Overrides;

package/dist/variants.js

@@ -0,0 +1,43 @@
+/** 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. */
+export const variantName = (name, variant) => (variant === 0 ? name : `${name}#${variant + 1}`);
+/**
+ * Steps along the type's main styles from the name's own, so no two variants share one.
+ * The controls are read with the visitor's settings, as those can narrow what's on offer.
+ */
+function variantStyle(kind, name, variant, overrides) {
+    const controls = kind.controls(name, overrides).flatMap((section) => section.controls);
+    return kind.styleKeys.reduce((style, key) => {
+        const control = controls.find(({ id }) => id === key);
+        if (control?.type !== "choice")
+            return style;
+        const own = control.options.findIndex((option) => option.id === control.selected);
+        return patched(style, control.options[(own + variant) % control.options.length].set);
+    }, {});
+}
+const remembered = new WeakMap();
+/**
+ * The overrides to draw a variant with. Anything set by hand wins over its style. The
+ * result is remembered, so the same variant is the same object and memoised work holds.
+ */
+export function variantOverrides(kind, name, variant, overrides) {
+    if (variant === 0)
+        return overrides;
+    const seen = remembered.get(overrides) ?? new Map();
+    remembered.set(overrides, seen);
+    if (seen.size >= MAX_REMEMBERED)
+        seen.clear();
+    const key = `${kind.id}|${name}|${variant}`;
+    const known = seen.get(key);
+    if (known)
+        return known;
+    const result = { ...variantStyle(kind, name, variant, overrides), ...overrides };
+    seen.set(key, result);
+    return result;
+}

package/mcp/server.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./tools.js";
+
+const server = createServer(readFileSync(new URL("../GUIDE.md", import.meta.url), "utf8"));
+await server.connect(new StdioServerTransport());

package/mcp/tools.js

@@ -0,0 +1,70 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createAvatar, styles } from "../dist/index.js";
+import { z } from "zod";
+
+const INSTRUCTIONS = `OriginKit Avatars turns a name into an avatar: the same name and style always give the same SVG. There are ${styles.length} styles.
+- list_styles: the style ids and labels.
+- create_avatar: style and name in, SVG out. Use it to see an avatar or to write one file. It is not how an app should draw avatars at runtime.
+- usage_guide (or the resource avatars://guide): how to add avatars to a codebase through the CLI, the npm package or MCP.
+Call usage_guide before adding avatars to a codebase.`;
+
+// The tools, shared by the stdio server and the hosted /mcp endpoint. `markdown` is GUIDE.md: each caller loads it its own way.
+export function createServer(markdown) {
+  // One guide, served as a resource and as a tool. The styles come from the package, so they can't go stale.
+  const guide = () =>
+    `${markdown}\n## Styles\n\n${styles.map((each) => `- \`${each.id}\`: ${each.label}`).join("\n")}\n`;
+
+  const server = new McpServer({ name: "avatars", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+
+  server.registerResource(
+    "guide",
+    "avatars://guide",
+    { description: "How to add OriginKit Avatars to a project", mimeType: "text/markdown" },
+    async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: guide() }] }),
+  );
+
+  server.registerTool(
+    "usage_guide",
+    {
+      description:
+        "How to use OriginKit Avatars in your own project: which surface to pick, recipes, and the styles. Read it before adding avatars to a codebase.",
+    },
+    async () => ({ content: [{ type: "text", text: guide() }] }),
+  );
+
+  server.registerTool(
+    "list_styles",
+    { description: "List the avatar styles, as ids to pass to create_avatar and their labels." },
+    async () => ({ content: [{ type: "text", text: JSON.stringify(styles) }] }),
+  );
+
+  server.registerTool(
+    "create_avatar",
+    {
+      description: "Turn a name into an SVG avatar. The same name and style always give the same avatar.",
+      inputSchema: {
+        style: z.enum(styles.map((each) => each.id)).describe("A style id from list_styles"),
+        name: z.string().min(1).max(100).describe("The name to generate the avatar from"),
+      },
+    },
+    async ({ style, name }) => {
+      try {
+        const svg = createAvatar(style, name);
+        const uri = `avatars://${style}/${encodeURIComponent(name)}.svg`;
+        return {
+          content: [
+            { type: "text", text: svg },
+            { type: "resource", resource: { uri, mimeType: "image/svg+xml", text: svg } },
+          ],
+        };
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+        };
+      }
+    },
+  );
+
+  return server;
+}