@craftedstudios/avatars 0.0.0-stage → 1.0.0

package/src/shader.js

@@ -0,0 +1,298 @@
+// One avatar per draw. The renderer points the viewport at a tile of the shared
+// canvas and this shader fills it: the shape (with a drop drawn out of it when
+// it leans), the effect dragged along into the drop, film grain, and an
+// optional ring.
+
+export const VERT = `attribute vec2 p; void main() { gl_Position = vec4(p, 0.0, 1.0); }`;
+
+export const FRAG = `
+precision highp float;
+uniform vec4 uTile;          // tile origin (GL, y up) and size, device px
+uniform vec2 uC, uE;         // center and the drop's center (tile px, y down)
+uniform float uR;            // radius, device px
+uniform float uDropR;        // the drop's radius, device px
+uniform float uGoo;          // how far apart body and drop still melt together, in r
+uniform float uBulge;        // how much of the pull the body itself follows
+uniform float uShape;        // 0 circle, 1 squircle, 2 square
+uniform float uRing;         // ring width, device px
+uniform vec3 uRingColor;
+uniform float uIn;           // entrance, 0..1
+uniform float uFx;           // which effect; see FX in renderer.js
+uniform vec3 uCol1, uCol2, uCol3, uCol4; // the effect's colors, in its own roles
+uniform float uT;            // seconds, phase included
+uniform float uGrain, uGrainCell;
+uniform float uAngle;        // per-seed angle for effects that have a direction
+uniform vec4 uLayout;        // per-seed pattern offset (xy), turn (z) and zoom (w)
+uniform float uWarp;         // distortion: 1 is each effect's own amount
+uniform float uScale;        // pattern zoom: above 1 makes features larger
+uniform vec2 uMouse;         // the pointer, smoothed (tile px, y down)
+uniform float uMouseAct;     // how much the pointer is acting, 0..1, eased in and out
+uniform float uMode;         // 1 follow, 2 repel, 3 distort, 4 pulse, 5 orbit, 6 turbulence
+
+float hash(vec2 p) { return fract(sin(dot(p, vec2(41.3, 289.1))) * 43758.5); }
+float noise(vec2 p) {
+  vec2 i = floor(p), f = fract(p); f = f * f * (3.0 - 2.0 * f);
+  return mix(mix(hash(i), hash(i + vec2(1, 0)), f.x), mix(hash(i + vec2(0, 1)), hash(i + vec2(1, 1)), f.x), f.y);
+}
+
+// Film grain: a sinless hash (no diagonal banding), re-rolled each frame and
+// strongest in the midtones. The cell grows with the render so large stills
+// keep visible grain instead of per-pixel dust.
+float rfHash12(vec2 p) {
+  vec3 p3 = fract(vec3(p.xyx) * 0.1031);
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.x + p3.y) * p3.z);
+}
+float rfFilmGrain(vec2 px, vec3 col) {
+  float t = floor(fract(uT * 0.731) * 240.0);
+  float n = rfHash12(floor(px / uGrainCell) + vec2(t * 17.0, t * 9.0));
+  float luma = dot(col, vec3(0.2126, 0.7152, 0.0722));
+  float resp = mix(0.35, 1.0, smoothstep(0.0, 0.22, luma)) * (1.0 - 0.8 * smoothstep(0.72, 1.0, luma));
+  return (n - 0.5) * resp * 1.5;
+}
+
+// OKLab, a color space where a straight line between two colors looks even.
+vec3 toLab(vec3 c) {
+  c = pow(max(c, 0.0), vec3(2.2));
+  vec3 lms = pow(vec3(
+    0.4122214708 * c.r + 0.5363325363 * c.g + 0.0514459929 * c.b,
+    0.2119034982 * c.r + 0.6806995451 * c.g + 0.1073969566 * c.b,
+    0.0883024619 * c.r + 0.2817188376 * c.g + 0.6299787005 * c.b), vec3(1.0 / 3.0));
+  return vec3(
+    0.2104542553 * lms.x + 0.7936177850 * lms.y - 0.0040720468 * lms.z,
+    1.9779984951 * lms.x - 2.4285922050 * lms.y + 0.4505937099 * lms.z,
+    0.0259040371 * lms.x + 0.7827717662 * lms.y - 0.8086757660 * lms.z);
+}
+vec3 fromLab(vec3 L) {
+  vec3 lms = vec3(
+    L.x + 0.3963377774 * L.y + 0.2158037573 * L.z,
+    L.x - 0.1055613458 * L.y - 0.0638541728 * L.z,
+    L.x - 0.0894841775 * L.y - 1.2914855480 * L.z);
+  lms = lms * lms * lms;
+  vec3 c = vec3(
+    4.0767416621 * lms.x - 3.3077115913 * lms.y + 0.2309699292 * lms.z,
+    -1.2684380046 * lms.x + 2.6097574011 * lms.y - 0.3413193965 * lms.z,
+    -0.0041960863 * lms.x - 0.7034186147 * lms.y + 1.7076147010 * lms.z);
+  return pow(clamp(c, 0.0, 1.0), vec3(1.0 / 2.2));
+}
+
+// Blends two colors in OKLab, where the halfway point looks halfway: the mix
+// stays as light as its ends rather than dipping dark and dirty the way a
+// straight RGB fade does.
+vec3 blend(vec3 a, vec3 b, float t) {
+  return fromLab(mix(toLab(a), toLab(b), t));
+}
+
+// Four colors along g (0 to 1), the first covering about half and the rest
+// narrower, each held a moment before it turns into the next.
+vec3 steps4(float g, vec3 c1, vec3 c2, vec3 c3, vec3 c4) {
+  if (g < 0.34) return c1;
+  if (g < 0.57) return blend(c1, c2, smoothstep(0.34, 0.57, g));
+  if (g < 0.59) return c2;
+  if (g < 0.76) return blend(c2, c3, smoothstep(0.59, 0.76, g));
+  if (g < 0.78) return c3;
+  if (g < 0.93) return blend(c3, c4, smoothstep(0.78, 0.93, g));
+  return c4;
+}
+
+vec2 rot2(vec2 v, float a) { float c = cos(a), s = sin(a); return vec2(v.x * c - v.y * s, v.x * s + v.y * c); }
+
+// Plasma: interference waves through a light organic distortion, cycled
+// through the four colors.
+vec3 fxPlasma(vec2 uv, float t, vec3 c1, vec3 c2, vec3 c3, vec3 c4) {
+  t *= 0.15;
+  vec2 p = uv * 1.8;
+  for (float i = 1.0; i <= 3.0; i += 1.0) {
+    p.x += 0.16 * uWarp / i * sin(i * 1.7 * p.y + t * 0.9 + i * 0.3);
+    p.y += 0.16 * uWarp / i * cos(i * 2.1 * p.x + t * 1.1 - i * 0.5);
+  }
+  float v = sin(p.x * 3.0 + t) + sin(p.y * 2.7 - t * 0.7) + sin((p.x + p.y) * 2.3 + t * 0.5);
+  vec2 c = p - 0.9;
+  v += sin(length(c) * 4.0 - t * 1.3);
+  v += 0.7 * sin(p.x * 1.8 - p.y * 2.5 + t * 0.8) + 0.5 * sin(rot2(p, 0.7).x * 3.5 + t * 0.4);
+  v = v / 5.2 * 0.5 + 0.5;
+  float g = fract(v * 1.5);
+  // The loop closes back into the first color, which covers about half.
+  if (g > 0.88) return blend(c4, c1, smoothstep(0.88, 1.0, g));
+  return steps4(g / 0.88, c1, c2, c3, c4);
+}
+
+// Linear Gradient: four colors in bands along an angle set by the seed,
+// moved by a light sine warp.
+vec3 fxLinear(vec2 uv, float t, float ang, vec3 c1, vec3 c2, vec3 c3, vec3 c4) {
+  t *= 0.15;
+  vec2 p = uv;
+  for (float i = 1.0; i <= 2.0; i += 1.0) {
+    p.x += 0.12 * uWarp / i * sin(i * 5.1 * p.y + t * 0.9 + i * 0.3);
+    p.y += 0.12 * uWarp / i * cos(i * 6.3 * p.x + t * 1.1 - i * 0.5);
+  }
+  float g = clamp((p.x - 0.5) * cos(ang) + (p.y - 0.5) * sin(ang) + 0.5, 0.0, 1.0);
+  return steps4(g, c1, c2, c3, c4);
+}
+
+// Radial Gradient: concentric bands from the rim in, pushed around by
+// two drifting noise fields and held still at the rim.
+vec3 fxRadial(vec2 uv, float t, vec3 c1, vec3 c2, vec3 c3, vec3 c4) {
+  t *= 0.15;
+  float g = clamp(length(uv - 0.5) * 2.0 / 1.2, 0.0, 1.0);
+  float n = noise(uv * 3.0 + t * 0.4) + noise(uv * 2.5 - t * 0.3 + 50.0) - 1.0;
+  // The first color is the outer band, the largest by area.
+  return steps4(1.0 - clamp(g + n * 0.15 * uWarp * smoothstep(1.0, 0.6, g), 0.0, 1.0), c1, c2, c3, c4);
+}
+
+// Thermal: thick sheets of light folding across the avatar, colored by how
+// bright they are, the way a heat camera colors warmth. Each sheet is a broad
+// band around a slow wave, thicker and thinner along its length, fading softly
+// upward in rays and more quickly below. The first color is the cold ground,
+// and the light climbs through the second and third to the fourth in each
+// sheet's core, held with short blends like the gradients. Upright: it isn't
+// turned per seed.
+vec3 fxThermal(vec2 uv, float t, vec3 c1, vec3 c2, vec3 c3, vec3 c4) {
+  t *= 0.15;
+  float light = 0.0;
+  for (int k = 0; k < 2; k++) {
+    float fk = float(k);
+    float x = uv.x * (1.0 + fk * 0.4) + fk * 5.3;
+    // The main sheet low across the avatar, a fainter one higher up.
+    float mid = mix(0.62, 0.34, fk)
+      + (mix(0.12, 0.08, fk) * sin(x * 2.0 + t * (0.8 + fk * 0.3) + fk * 2.0)
+      + 0.04 * sin(x * 4.7 - t * 1.2 + fk)
+      + 0.07 * (noise(vec2(x * 1.4, t * 0.3 + fk * 4.0)) - 0.5)) * uWarp;
+    float thick = mix(0.13, 0.09, fk) * (0.75 + 0.5 * noise(vec2(x * 1.8 - t * 0.3, fk * 5.0)));
+    float d = mid - uv.y; // above the sheet's middle when positive
+    float ray = 0.75 + 0.5 * noise(vec2(x * 9.0 + t * 0.5, fk * 9.0));
+    float up = thick * 1.6 * ray, down = thick * 0.7;
+    float body = d > 0.0 ? exp(-pow(d / up, 1.6)) : exp(-pow(-d / down, 2.0));
+    float fold = 0.8 + 0.2 * noise(vec2(x * 2.2 - t * 0.4, fk * 6.0));
+    light = 1.0 - (1.0 - light) * (1.0 - clamp(body * fold * mix(1.0, 0.6, fk), 0.0, 1.0));
+  }
+  return steps4(light, c1, c2, c3, c4);
+}
+
+// Topography: contour lines of a warped fBm elevation over a tinted fill.
+float topoFbm(vec2 p) {
+  float v = 0.0, a = 0.5;
+  for (int i = 0; i < 6; i++) { p = rot2(p, 0.6); v += a * noise(p); p *= 2.0; a *= 0.5; }
+  return v;
+}
+vec3 fxTopo(vec2 uv, float t, vec3 line, vec3 fillC, vec3 ground) {
+  t *= 0.15;
+  vec2 p = uv * 1.6;
+  p += vec2(topoFbm(p + t * 0.3), topoFbm(p + vec2(5.2, 1.3) + t * 0.2)) * 0.3 * uWarp;
+  float e = topoFbm(p + t * 0.1), se = e * 6.0;
+  float ld = min(fract(se), 1.0 - fract(se));
+  float l = 1.0 - smoothstep(0.04, 0.14, ld);
+  vec3 fill = mix(ground, fillC, e * 0.6);
+  return mix(fill, line, l);
+}
+
+// Scenery's mouse interactions, as written in its engine, measured across the
+// avatar: they move the pattern around the pointer and leave the shape alone.
+vec2 tsMod289(vec2 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec3 tsMod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec3 tsPermute(vec3 x) { return tsMod289(((x * 34.0) + 1.0) * x); }
+float tsNoise(vec2 v) {
+  const vec4 C = vec4(0.211324865405187, 0.366025403784439, -0.577350269189626, 0.024390243902439);
+  vec2 i = floor(v + dot(v, C.yy));
+  vec2 x0 = v - i + dot(i, C.xx);
+  vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
+  vec4 x12 = x0.xyxy + C.xxzz;
+  x12.xy -= i1;
+  i = tsMod289(i);
+  vec3 p = tsPermute(tsPermute(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));
+  vec3 m = max(0.5 - vec3(dot(x0, x0), dot(x12.xy, x12.xy), dot(x12.zw, x12.zw)), 0.0);
+  m = m * m; m = m * m;
+  vec3 x = 2.0 * fract(p * C.www) - 1.0;
+  vec3 h = abs(x) - 0.5;
+  vec3 ox = floor(x + 0.5);
+  vec3 a0 = x - ox;
+  m *= 1.79284291400159 - 0.85373472095314 * (a0 * a0 + h * h);
+  vec3 g;
+  g.x = a0.x * x0.x + h.x * x0.y;
+  g.yz = a0.yz * x12.xz + h.yz * x12.yw;
+  return 130.0 * dot(m, g);
+}
+float tsFbm(vec2 p) {
+  float v = 0.0, a = 0.5;
+  for (int i = 0; i < 5; i++) { v += tsNoise(p) * a; p *= 2.1; a *= 0.5; }
+  return v;
+}
+
+vec2 mouseInteract(vec2 uv, vec2 mp, float act, float t) {
+  vec2 diff = uv - mp;
+  float dist = length(diff);
+  vec2 dir = normalize(diff + 0.0001);
+  if (uMode < 1.5) {
+    uv -= dir * smoothstep(0.5, 0.0, dist) * 0.08 * act;        // follow
+  } else if (uMode < 2.5) {
+    uv += dir * smoothstep(0.4, 0.0, dist) * 0.06 * act;        // repel
+  } else if (uMode < 3.5) {
+    float inf = smoothstep(0.5, 0.0, dist);                      // distort
+    uv += inf * 0.05 * act * vec2(sin(dist * 10.0 + t * 2.0), cos(dist * 8.0 - t * 1.5));
+  } else if (uMode < 4.5) {
+    float pulse = sin(dist * 15.0 - t * 4.0) * 0.5 + 0.5;        // pulse
+    uv += dir * smoothstep(0.5, 0.0, dist) * pulse * 0.04 * act;
+  } else if (uMode < 5.5) {
+    float inf = smoothstep(0.6, 0.0, dist);                      // orbit
+    uv = mp + rot2(uv - mp, inf * 0.4 * act);
+  } else {
+    float falloff = exp(-pow(dist / 0.26, 2.0));                 // turbulence
+    if (falloff > 0.002) {
+      float ts = t * 0.32;
+      vec2 field = vec2(tsFbm((uv + vec2(0.0, ts * 0.25)) * 5.2), tsFbm((uv + vec2(9.1, -ts * 0.3)) * 5.2));
+      uv += (field - 0.5) * 2.0 * falloff * 0.85 * 0.035 * act;
+    }
+  }
+  return uv;
+}
+
+// Signed distance to the shape, device px. The squircle is a rounded square
+// with corners of 0.6r, which is what border-radius: 30% draws, so the CSS
+// fallback and the live avatar have the same outline.
+float sdShape(vec2 p, float r) {
+  if (uShape < 0.5) return length(p) - r;
+  float k = uShape < 1.5 ? 0.6 * r : 0.0;
+  vec2 q = abs(p) - vec2(r - k);
+  return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - k;
+}
+
+// Polynomial smooth minimum: two shapes closer than k melt into one surface
+// with a neck between them that thins as they part.
+float smin(float a, float b, float k) {
+  float h = clamp(0.5 + 0.5 * (b - a) / k, 0.0, 1.0);
+  return mix(b, a, h) - k * h * (1.0 - h);
+}
+
+void main() {
+  vec2 px = gl_FragCoord.xy - uTile.xy;
+  px.y = uTile.w - px.y;
+  float r = uR * (0.55 + 0.45 * uIn);
+  // The lean is goo: the body bulges a little toward the pointer, and a drop
+  // of the same material, drawn out on a spring, melts back into it.
+  vec2 pull = uE - uC;
+  vec2 body = uC + pull * uBulge;
+  float dBody = sdShape(px - body, r);
+  float dDrop = length(px - uE) - uDropR * (0.55 + 0.45 * uIn);
+  float d = smin(dBody, dDrop, uGoo * r);
+  float cover = clamp(0.5 - d / 1.2, 0.0, 1.0) * uIn;
+  if (cover <= 0.0) { gl_FragColor = vec4(0.0); return; }
+  // The material goes with it: the nearer a point is to the drop, the further
+  // back toward the center it samples, so the pattern draws out like taffy.
+  float w = clamp(0.5 + 0.5 * (dBody - dDrop) / (uGoo * r), 0.0, 1.0);
+  vec2 uv = (px - uC - pull * mix(uBulge, 1.0, w)) / (r * 2.0 * uScale) + 0.5;
+  if (uMouseAct > 0.001) uv = mouseInteract(uv, (uMouse - uC) / (r * 2.0 * uScale) + 0.5, uMouseAct, uT);
+  // Each seed sees its own part of the pattern. Thermal only slides sideways
+  // and zooms, so it stays upright.
+  vec2 ua = (uv - 0.5) / uLayout.w + 0.5 + vec2(uLayout.x, 0.0);
+  uv = rot2(uv - 0.5, uLayout.z) / uLayout.w + 0.5 + uLayout.xy;
+  vec3 c;
+  if (uFx < 0.5) c = fxLinear(uv, uT, uAngle, uCol1, uCol2, uCol3, uCol4);
+  else if (uFx < 1.5) c = fxThermal(ua, uT, uCol1, uCol2, uCol3, uCol4);
+  else if (uFx < 2.5) c = fxTopo(uv, uT, uCol1, uCol2, uCol3);
+  else if (uFx < 3.5) c = fxPlasma(uv, uT, uCol1, uCol2, uCol3, uCol4);
+  else c = fxRadial(uv, uT, uCol1, uCol2, uCol3, uCol4);
+  c += rfFilmGrain(px, c) * uGrain;
+  if (uRing > 0.0) c = mix(c, uRingColor, smoothstep(-uRing - 0.8, -uRing + 0.4, d));
+  c = clamp(c, 0.0, 1.0);
+  gl_FragColor = vec4(c * cover, cover);
+}`;

package/src/still.js

@@ -0,0 +1,60 @@
+import { resolve } from './options.js';
+import { paint2d, shaderColors } from './color.js';
+import { getRenderer, parseColor, angleOf } from './renderer.js';
+import { dropRadius, params as gooParams } from './goo.js';
+
+const MAX = 2048;
+
+// One frame at the seed's phase, for email, OG images and long lists. The image
+// is exactly `size` pixels square and transparent outside the shape.
+//   const png = await toDataURL('dexter@craftedstudios.co', { size: 1024 });
+export async function toDataURL(seed, options = {}) {
+  return (await still(seed, options)).toDataURL('image/png');
+}
+
+export async function toBlob(seed, options = {}) {
+  const canvas = await still(seed, options);
+  return new Promise((ok, fail) => canvas.toBlob((b) => (b ? ok(b) : fail(new Error('Could not encode the avatar'))), 'image/png'));
+}
+
+export async function still(seed, options = {}) {
+  if (typeof document === 'undefined') throw new Error('Still images need a browser');
+  const size = Math.round(Math.min(MAX, Math.max(1, Number(options.size) || 512)));
+  const o = resolve({ ...options, seed, size, interaction: 'none', motion: 'still' });
+  const out = document.createElement('canvas');
+  out.width = out.height = size;
+  const ctx = out.getContext('2d');
+  const r = getRenderer();
+  if (r && !r.lost) {
+    const half = size / 2;
+    const g = gooParams(o.stretch, o.thickness);
+    const target = {
+      dev: size,
+      params: () => ({
+        cx: half, cy: half, ex: half, ey: half, r: half,
+        dropR: dropRadius({ x: 0, y: 0 }, half, g),
+        goo: g.goo, bulge: g.bulge, warp: o.distortion * 2, scale: o.scale,
+        mx: half, my: half, mouseAct: 0, mode: 0,
+        shape: o.shape, ring: o.ring, ringColor: parseColor(o.ringColor),
+        enter: 1, effect: o.traits.effect, colors: shaderColors(o.palette),
+        t: o.traits.phase, grain: o.grain, angle: angleOf(o.traits), layout: o.traits.layout,
+      }),
+      blit: (src, x, y, s) => { ctx.globalCompositeOperation = 'copy'; ctx.drawImage(src, x, y, s, s, 0, 0, size, size); },
+    };
+    r.render([target], 0);
+    return out;
+  }
+  // Without WebGL: the same gradient the CSS fallback shows, cut to the shape.
+  ctx.beginPath();
+  if (o.shape === 'circle') ctx.arc(size / 2, size / 2, size / 2, 0, Math.PI * 2);
+  else if (ctx.roundRect) ctx.roundRect(0, 0, size, size, o.shape === 'squircle' ? size * 0.3 : 0);
+  else ctx.rect(0, 0, size, size);
+  ctx.clip();
+  paint2d(ctx, o.traits.effect, o.palette, size);
+  if (o.ring > 0) {
+    ctx.lineWidth = o.ring * 2;
+    ctx.strokeStyle = o.ringColor;
+    ctx.stroke();
+  }
+  return out;
+}

package/types/index.d.ts

@@ -0,0 +1,114 @@
+export type Effect = 'linear' | 'thermal' | 'topography' | 'plasma' | 'radial';
+export type Shape = 'circle' | 'squircle' | 'square';
+
+export interface AvatarOptions {
+  /** Any string. Used exactly as given; pass a stable ID. */
+  seed: string;
+  /** CSS pixels. Rendered at device pixel ratio, capped at 2. Default 32. */
+  size?: number;
+  /** Default 'auto', which picks from the seed. */
+  effect?: Effect | 'auto';
+  /**
+   * Up to four CSS colors (hex, rgb() or hsl()), used exactly as given in
+   * place of the seed's colors: main color, two neighbors, then the dark
+   * ground. Any left out are built from the main color. Default: colors from
+   * the seed.
+   */
+  colors?: string[];
+  /** 'still' freezes it. Reduced motion always freezes. Default 'auto'. */
+  motion?: 'auto' | 'still';
+  /**
+   * How the avatar reacts to the pointer (mouse only). 'goo' stretches the
+   * outline toward it; the rest move the pattern inside the outline. Reduced
+   * motion turns it off. Default 'goo'.
+   */
+  interaction?: 'goo' | 'follow' | 'repel' | 'distort' | 'pulse' | 'orbit' | 'turbulence' | 'none';
+  /** Film grain strength, 0 to turn it off. Default 0.07. */
+  grain?: number;
+  /** Animation speed multiplier, 0 to 4. Default 1. */
+  speed?: number;
+  /** How much the effect warps, 0 to 1. Default 0.5. */
+  distortion?: number;
+  /** Pattern zoom, 0.25 to 4; above 1 makes features larger. Default 1. */
+  scale?: number;
+  /** Goo only: how far it reaches, 0 (a slight bulge) to 1 (a drip). Default 1. */
+  stretch?: number;
+  /** Goo only: how thick and slow it is, 0 to 1. Default 0.5. */
+  thickness?: number;
+  /** Default 'circle'. */
+  shape?: Shape;
+  /** Width of a ring that separates overlapping avatars, CSS px. Default 0. */
+  ring?: number;
+  /** Ring color, any CSS color. Default '#fff'. */
+  ringColor?: string;
+  /** Sets role="img" and aria-label. Without it the avatar is decorative. */
+  label?: string;
+}
+
+export interface AvatarInstance {
+  element: HTMLElement;
+  update(options: Partial<AvatarOptions>): void;
+  destroy(): void;
+}
+
+/** Appends an avatar to `el`. */
+export function avatar(el: Element, options: AvatarOptions): AvatarInstance;
+
+export type CursorVariant = 'arrow' | 'avatar';
+
+export interface CursorOptions extends Omit<AvatarOptions, 'size' | 'shape' | 'interaction' | 'label'> {
+  /** arrow: a two-color arrow with the avatar beside the name. avatar: the avatar is the pointer. Default arrow. */
+  variant?: CursorVariant;
+  /**
+   * Shown on the tag. Without one the tag shows the seed's anonymous name,
+   * like "Swift Otter" (see nameFor). false leaves the tag off.
+   */
+  name?: string | false;
+  /** Draws the cursor larger, avatars included, for previews or big screens. Default 1. */
+  zoom?: number;
+  /** Where the tip goes, inside the positioned element the cursor was added to. */
+  x?: number;
+  y?: number;
+}
+
+export interface CursorInstance {
+  element: HTMLSpanElement;
+  /** Puts the tip at x, y. Cheap: call it on every pointer update. */
+  move(x: number, y: number): void;
+  update(options: Partial<CursorOptions>): void;
+  destroy(): void;
+}
+
+/** Appends a presence cursor to `el`, which should be positioned. */
+export function cursor(el: Element, options: CursorOptions): CursorInstance;
+
+/** The anonymous name a seed gets, like "Swift Otter": an adjective and an animal. The same seed always gets the same name. */
+export function nameFor(seed: string): string;
+
+/** Registers <crafted-avatar>. Attributes match the options, with ring-color for ringColor. */
+export function defineAvatarElement(name?: string): void;
+
+export interface StillOptions extends Omit<AvatarOptions, 'seed' | 'motion' | 'interaction' | 'stretch' | 'thickness' | 'label'> {
+  /** Pixels, up to 2048. Default 512. */
+  size?: number;
+}
+
+/** One frame at the seed's phase, as a PNG data URL. */
+export function toDataURL(seed: string, options?: StillOptions): Promise<string>;
+/** One frame at the seed's phase, as a PNG blob. */
+export function toBlob(seed: string, options?: StillOptions): Promise<Blob>;
+
+/** What a seed maps to. `colors` are the colors it gives its effect, as hex, in the effect's roles. */
+export function traits(seed: string, overrides?: { effect?: Effect | 'auto' }): {
+  effect: Effect;
+  /** The first color's hue, 0 to 359. */
+  hue: number;
+  /** 32 bits that pick the other colors. */
+  tone: number;
+  phase: number;
+  colors: string[];
+};
+
+/** Every effect. `auto` only picks from AUTO_EFFECTS. */
+export const EFFECTS: readonly Effect[];
+export const AUTO_EFFECTS: readonly Effect[];

package/types/react.d.ts

@@ -0,0 +1,27 @@
+import type { CSSProperties, HTMLAttributes, JSX } from 'react';
+import type { AvatarOptions, CursorOptions } from './index.js';
+
+export type AvatarProps = AvatarOptions & Omit<HTMLAttributes<HTMLSpanElement>, 'children'>;
+
+export function Avatar(props: AvatarProps): JSX.Element;
+
+export type StackSeed = string | (AvatarOptions & { style?: CSSProperties });
+
+export interface AvatarStackProps extends Omit<AvatarOptions, 'seed' | 'label'> {
+  seeds: StackSeed[];
+  /** How many to show before +N. Default 4. */
+  max?: number;
+  /** How much each avatar tucks under the one before, as a fraction of size. Default 0.25. */
+  overlap?: number;
+  /** The group's accessible name. Default "N people". */
+  label?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function AvatarStack(props: AvatarStackProps): JSX.Element;
+
+export type CursorProps = CursorOptions & { className?: string; style?: CSSProperties };
+
+/** A presence cursor with the avatar built in; the tip lands on x, y. */
+export function Cursor(props: CursorProps): JSX.Element;