@craftedstudios/avatars 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crafted Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @craftedstudios/avatars
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Live shader avatars from any name, email or user ID, plus presence cursors with the avatar built in. Every avatar on a page shares one WebGL context. There's a PNG export for places a shader can't run, and a React entry.
+
+See every effect, and try your own seeds, at [avatars.craftedstudios.co](https://avatars.craftedstudios.co).
+
+```sh
+npm i @craftedstudios/avatars
+```
+
+No dependencies. React is optional.
+
+## Quick start
+
+Give each avatar a seed. The seed decides the effect, the colors and the layout, so the same person always gets the same avatar.
+
+React:
+
+```jsx
+import { Avatar } from '@craftedstudios/avatars/react';
+
+<Avatar seed={user.id} size={40} />
+```
+
+Web component:
+
+```js
+import { defineAvatarElement } from '@craftedstudios/avatars';
+defineAvatarElement();
+```
+
+```html
+<crafted-avatar seed="ada@northwind.co" size="40"></crafted-avatar>
+```
+
+Plain JavaScript:
+
+```js
+import { avatar } from '@craftedstudios/avatars';
+
+const a = avatar(el, { seed: 'ada@northwind.co', size: 40 });
+a.update({ effect: 'thermal' });
+a.destroy();
+```
+
+## Options
+
+Every option except `seed` is optional. The same names work as React props, web component attributes (`ring-color` for `ringColor`) and plain JavaScript options.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `seed` | required | Any name, email or user ID. |
+| `size` | `32` | Width and height, in CSS pixels. |
+| `effect` | `auto` | `linear`, `radial`, `thermal`, `topography` or `plasma`. `auto` lets the seed choose. |
+| `colors` | from the seed | Up to four CSS colors for the effect, used in place of the seed's. |
+| `motion` | `auto` | `still` draws one frame and stops. |
+| `interaction` | `goo` | What happens on hover: `goo`, `follow`, `repel`, `distort`, `pulse`, `orbit`, `turbulence` or `none`. |
+| `speed` | `1` | How fast it moves, from 0 to 4. |
+| `shape` | `circle` | `circle`, `squircle` or `square`. |
+| `ring` | `0` | An outline, in pixels. `ringColor` sets its color. |
+| `label` | none | A name for screen readers. Without one, the avatar is hidden from them. |
+
+`grain`, `distortion`, `scale`, `stretch` and `thickness` fine-tune the look. The [Lab](https://avatars.craftedstudios.co/lab/) shows what each one does.
+
+## Seeds
+
+The same seed gives the same avatar everywhere: on the server, in the browser and in a PNG. Nothing is uploaded, fetched or stored.
+
+Use something stable. An email works until someone changes it; a user ID never does.
+
+## Still images
+
+For email, native apps and social images, export a PNG. It takes the same options and comes out up to 2048px square.
+
+```js
+import { toBlob, toDataURL } from '@craftedstudios/avatars';
+
+const png = await toBlob('ada@northwind.co', { size: 1024 });
+const src = await toDataURL('ada@northwind.co', { effect: 'radial' });
+```
+
+## Cursors
+
+For multiplayer, show where people are with their avatar built in. There are two styles: `arrow` puts the avatar beside the name, and `avatar` makes the avatar itself the pointer. Your app already knows where each cursor is, so pass `x` and `y` and the tip lands there, inside the nearest positioned element.
+
+```jsx
+import { Cursor } from '@craftedstudios/avatars/react';
+
+<Cursor seed={user.id} name={user.name} variant="avatar" x={x} y={y} />
+```
+
+The seed decides how the cursor looks. `name` is the text on its tag: pass whatever your app shows for that person. Leave it out and the cursor gets an anonymous name from its seed, like Swift Otter. The same seed always gets the same name, so for visitors who aren't signed in, a session ID gives each one their own. Set `name` to `false` for no tag at all.
+
+`nameFor(seed)` returns the same anonymous name, for showing it elsewhere, like a list of who's here.
+
+Without React, `cursor()` returns a cursor you move as positions arrive. `move()` is cheap enough to call on every update.
+
+```js
+import { cursor } from '@craftedstudios/avatars';
+
+const c = cursor(canvas, { seed: user.id, name: user.name, variant: 'arrow' });
+c.move(x, y);
+```
+
+`zoom` draws a cursor larger, with its avatars still sharp.
+
+## Motion and accessibility
+
+When someone has asked their device for reduced motion, every avatar holds still and stops reacting to the pointer. You don't need to do anything.
+
+To freeze avatars yourself, set `motion` to `still`, and `interaction` to `none` to stop the hover as well. A still avatar draws once and costs nothing after that.
+
+```jsx
+<Avatar seed={user.id} motion="still" interaction="none" />
+```
+
+## Performance
+
+Every avatar on a page shares one WebGL context, however many there are. Only avatars on screen draw, and everything pauses while the tab is hidden. Without WebGL, each avatar shows a gradient in its own colors instead.
+
+## Server rendering
+
+The React component renders its gradient on the server, so the page loads with the avatar already in place and nothing shifts when the shader takes over. It works with Next.js and other frameworks that render on the server.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@craftedstudios/avatars",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Live shader avatars from any name, email or user ID, plus presence cursors. One WebGL context for the whole page, a PNG export and a React entry.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Crafted Studios (https://www.craftedstudios.co)",
+  "homepage": "https://avatars.craftedstudios.co",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./react": {
+      "types": "./types/react.d.ts",
+      "default": "./src/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["src", "types", "LICENSE", "README.md"],
+  "keywords": ["avatar", "avatars", "cursor", "multiplayer", "webgl", "shader", "gradient", "react", "web-component"],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}

package/src/avatar.js

@@ -0,0 +1,55 @@
+import { resolve, hostStyle, hostAttrs } from './options.js';
+import { getRenderer, Item } from './renderer.js';
+
+// Turns `host` into an avatar: sets its size, shape and fallback gradient, and
+// when WebGL is available, adds the live canvas inside it. React and the web
+// component render their own host and call this; `avatar()` makes one.
+export function mount(host, options, { styled = false, enter = false } = {}) {
+  let o = resolve(options);
+  const apply = () => {
+    if (!styled) Object.assign(host.style, hostStyle(o));
+    for (const a of ['role', 'aria-label', 'aria-hidden']) host.removeAttribute(a);
+    for (const [k, v] of Object.entries(hostAttrs(o))) host.setAttribute(k, v);
+  };
+  apply();
+  const r = getRenderer();
+  let item = null;
+  if (r) {
+    item = new Item(host, o, { enter });
+    host.append(item.canvas);
+    r.add(item);
+  }
+  return {
+    element: host,
+    update(next) {
+      o = resolve({ ...o, ...next });
+      apply();
+      if (item) {
+        item.set(o);
+        // The canvas holds the old frame until the next one lands, so the
+        // gradient that apply() just restored stays hidden.
+        if (item.shown) item.hideFallback();
+        r.wake();
+      }
+    },
+    destroy() {
+      if (item) { r.remove(item); item.canvas.remove(); item = null; }
+    },
+  };
+}
+
+// Plain JS: appends an avatar to `el`.
+//   const a = avatar(el, { seed: 'dexter@craftedstudios.co', size: 40 });
+//   a.update({ effect: 'thermal' });
+//   a.destroy();
+export function avatar(el, options) {
+  const host = document.createElement('span');
+  host.className = 'crafted-avatar';
+  el.append(host);
+  const a = mount(host, options);
+  return {
+    element: host,
+    update: a.update,
+    destroy() { a.destroy(); host.remove(); },
+  };
+}

package/src/color.js

@@ -0,0 +1,234 @@
+// A seed's colors come from a color harmony. The seed picks a base hue and
+// one of five classic schemes (analogous, triadic, split complementary,
+// tetradic, complementary), and every color is taken at 90 to 100 percent of
+// the strongest version of its hue a screen can show. Lightness follows the
+// hue: each hue is strongest at its own lightness (yellow light, blue deep),
+// so every color sits near that point instead of one lightness for all, which
+// is what turned yellow to khaki.
+//
+// The first color is the seed's base hue and the one that covers most of the
+// avatar; the rest follow in order around the hue circle, so colors that meet
+// in a gradient sit close. The shaders blend them along the hue circle rather
+// than through grey (see blend() in shader.js).
+
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+const wrap = (h) => ((h % 360) + 360) % 360;
+const arc = (a, b) => ((b - a + 540) % 360) - 180;
+
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const toGamma = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+
+// OKLab to linear sRGB.
+function linear(L, a, b) {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+const fits = (L, C, rad) => linear(L, C * Math.cos(rad), C * Math.sin(rad)).every((v) => v >= -1e-5 && v <= 1 + 1e-5);
+
+// The strongest chroma sRGB can show at lightness L and hue h.
+export function maxChroma(L, h) {
+  const rad = (wrap(h) * Math.PI) / 180;
+  let lo = 0, hi = 0.4;
+  for (let i = 0; i < 16; i++) {
+    const mid = (lo + hi) / 2;
+    if (fits(L, mid, rad)) lo = mid; else hi = mid;
+  }
+  return lo;
+}
+
+// The lightness where a hue is strongest, per whole degree, worked out once.
+const cusps = new Map();
+function cusp(h) {
+  const key = Math.round(wrap(h)) % 360;
+  if (!cusps.has(key)) {
+    let best = 0.6, most = 0;
+    for (let L = 0.3; L <= 0.98; L += 0.01) {
+      const c = maxChroma(L, key);
+      if (c > most) { most = c; best = L; }
+    }
+    cusps.set(key, best);
+  }
+  return cusps.get(key);
+}
+
+// OKLCH to 0..1 sRGB. Chroma above what sRGB can show comes down to the edge,
+// so a color keeps its hue and lightness and loses only strength.
+export function oklch(L, C, h) {
+  const c = Math.min(C, maxChroma(L, h));
+  const rad = (wrap(h) * Math.PI) / 180;
+  return linear(L, c * Math.cos(rad), c * Math.sin(rad)).map((v) => clamp(toGamma(clamp(v, 0, 1)), 0, 1));
+}
+
+// Spreads every input bit across the whole word.
+export function scramble(h) {
+  h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+  h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+  return (h ^ (h >>> 16)) >>> 0;
+}
+
+const bits = (w, at, n) => (w >>> at) & ((1 << n) - 1);
+const apart = (a, b) => Math.abs(arc(a, b));
+const range = (w, at, lo, hi) => lo + (bits(w, at, 4) / 15) * (hi - lo);
+
+// Hue offsets for each scheme, base hue first.
+const SCHEMES = [
+  [0, 30, 60, -30], // analogous
+  [0, 120, 240], // triadic
+  [0, 150, 210], // split complementary
+  [0, 90, 180, 270], // tetradic
+  [0, 180, 20, 200], // complementary
+];
+
+// A color of hue h near full strength: lightness around where the hue is
+// strongest, moved by `shift`, and chroma 90 to 100 percent of the maximum.
+function vivid(h, w, [lo, hi], shift = 0) {
+  const L = clamp(cusp(h) + range(w, 0, lo, hi) + shift, 0.5, 0.95);
+  return oklch(L, maxChroma(L, h) * range(w, 4, 0.9, 1), h);
+}
+
+// A seed's family, from its hue h and its tone k:
+//   colors  four, for the gradient effects; the first covers most of the
+//           avatar, and three-color schemes repeat the base hue lighter
+//   light, mid, deep  three, for the effects with a ground (lines or
+//                     highlight, fill or metal, ground)
+export function family(h, k = 0) {
+  const word = (i) => scramble(k ^ Math.imul(i + 1, 0x9e3779b9));
+  const w0 = word(0);
+  const offsets = SCHEMES[w0 % SCHEMES.length];
+  const rest = offsets.slice(1).map((d) => wrap(h + d)).sort((a, b) => wrap(a - h) - wrap(b - h));
+  if (bits(w0, 8, 1)) rest.reverse();
+  const hues = [h, ...rest];
+  const colors = hues.map((hue, i) => vivid(hue, word(i + 1), [-0.1, 0.04]));
+  if (colors.length < 4) colors.push(vivid(h, word(4), [0.08, 0.16]));
+  // The ground is deep, so it can't be orange to green-yellow: dark, those
+  // are brown, khaki and olive.
+  const grounds = hues.filter((x) => apart(x, 85) > 50);
+  const w = word(9);
+  const deepHue = grounds.length ? grounds[w % grounds.length] : wrap(h + 180);
+  const others = hues.filter((x) => x !== deepHue);
+  const L = range(w, 8, 0.3, 0.42);
+  return {
+    colors,
+    light: (() => { const Ll = range(w, 12, 0.88, 0.95); return oklch(Ll, maxChroma(Ll, others[0]) * 0.95, others[0]); })(),
+    mid: vivid(others[1 % others.length], word(10), [-0.08, 0.02]),
+    deep: oklch(L, maxChroma(L, deepHue) * range(w, 16, 0.85, 1), deepHue),
+  };
+}
+
+function hsl(h, s, l) {
+  s /= 100; l /= 100;
+  const k = (n) => (n + h / 30) % 12, a = s * Math.min(l, 1 - l);
+  return [0, 8, 4].map((n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1)));
+}
+
+// Reads a CSS color without a DOM, so the server render can use it: hex,
+// rgb() and hsl(). Returns 0..1 RGB, or null for anything else.
+export function parseColor(str) {
+  const c = String(str).trim().toLowerCase();
+  let m = /^#([0-9a-f]{3,8})$/.exec(c);
+  if (m) {
+    let h = m[1];
+    if (h.length === 3 || h.length === 4) h = h.replace(/./g, '$&$&');
+    if (h.length !== 6 && h.length !== 8) return null;
+    return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+  }
+  m = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(c);
+  if (!m) return null;
+  const tokens = m[2].split(/[\s,/]+/).filter(Boolean).slice(0, 3);
+  const n = tokens.map(parseFloat);
+  if (n.length < 3 || n.some((v) => !Number.isFinite(v))) return null;
+  if (m[1].startsWith('rgb')) return n.map((v, i) => clamp(tokens[i].endsWith('%') ? v / 100 : v / 255, 0, 1));
+  return hsl(wrap(n[0]), clamp(n[1], 0, 100), clamp(n[2], 0, 100));
+}
+
+// Each effect has its own colors, in Scenery's roles and with Scenery's
+// defaults. `colors` fills them in this order; any left out keep the default.
+export const EFFECT_COLORS = {
+  linear: { roles: ['Start', 'Second', 'Third', 'End'], defaults: ['#FF6B35', '#FF4081', '#7C4DFF', '#1A0A2E'] },
+  thermal: { roles: ['Cold', 'Cool', 'Warm', 'Hot'], defaults: ['#2B1BD9', '#21E3FF', '#FFD23F', '#FF2E63'] },
+  topography: { roles: ['Lines', 'Fill', 'Ground'], defaults: ['#FFFFFF', '#1A1A2E', '#0A0A12'] },
+  radial: { roles: ['Center', 'Second', 'Third', 'Edge'], defaults: ['#FFD700', '#FF6347', '#8B008B', '#0D0D0D'] },
+  plasma: { roles: ['First', 'Second', 'Third', 'Fourth'], defaults: ['#FF006E', '#FFBE0B', '#3A86FF', '#8338EC'] },
+};
+
+const mixRgb = (a, b, t) => a.map((v, i) => v + (b[i] - v) * t);
+
+// How a seed's family fills each effect's roles.
+const RECIPES = {
+  linear: (f) => f.colors,
+  plasma: (f) => f.colors,
+  radial: (f) => f.colors,
+  thermal: (f) => f.colors,
+  topography: (f) => [f.light, f.mid, f.deep],
+};
+
+// An effect's colors, in its roles, as 0..1 RGB: from `colors` when given,
+// otherwise from the seed's hue and tone. Never both.
+export function effectColors(effect, hue, colors, tone = 0) {
+  const spec = EFFECT_COLORS[effect];
+  const picked = (Array.isArray(colors) ? colors : []).map(parseColor);
+  if (!picked.some(Boolean)) return RECIPES[effect](family(hue, tone));
+  return spec.defaults.map((d, i) => picked[i] || parseColor(d));
+}
+
+// The four colors the shader takes. Effects with fewer roles leave the rest
+// unused.
+export const shaderColors = (c) => [0, 1, 2, 3].map((i) => c[i] || [0, 0, 0]);
+
+export const hex = (c) => '#' + c.map((v) => Math.round(v * 255).toString(16).padStart(2, '0')).join('').toUpperCase();
+
+const rgb = ([r, g, b], alpha = 1) =>
+  `rgba(${Math.round(r * 255)},${Math.round(g * 255)},${Math.round(b * 255)},${alpha})`;
+
+// What an avatar looks like without WebGL: a few soft spots of its colors over
+// a base, close to the average look of its effect so the swap to the live
+// version is a shift in detail rather than a change of color. One description
+// feeds both the CSS (server render, no WebGL) and Canvas 2D (still images
+// without WebGL), so the two always agree.
+//   spots: [x, y, color, reach]   x, y and reach as fractions of the size
+export function paint(effect, c) {
+  switch (effect) {
+    case 'thermal':
+      return { base: c[0], spots: [[0.5, 0.62, c[1], 0.45], [0.55, 0.7, c[2], 0.35], [0.45, 0.35, c[3], 0.35]] };
+    case 'topography': {
+      const [lines, fill, ground] = c;
+      return { base: ground, spots: [[0.5, 0.45, mixRgb(ground, fill, 0.6), 0.75], [0.3, 0.75, mixRgb(fill, lines, 0.25), 0.45]] };
+    }
+    case 'radial':
+      return { base: c[3], spots: [[0.5, 0.5, c[0], 0.25], [0.5, 0.5, c[1], 0.45], [0.5, 0.5, c[2], 0.62]] };
+    case 'linear':
+      return { base: c[1], spots: [[0.1, 0.5, c[0], 0.6], [0.6, 0.5, c[2], 0.5], [0.95, 0.5, c[3], 0.55]] };
+    default: // plasma
+      return { base: c[1], spots: [[0.25, 0.3, c[0], 0.6], [0.8, 0.25, c[2], 0.6], [0.6, 0.85, c[3], 0.65]] };
+  }
+}
+
+export function css(effect, c) {
+  const { base, spots } = paint(effect, c);
+  return [
+    ...spots.map(([x, y, c, r]) => `radial-gradient(circle at ${x * 100}% ${y * 100}%, ${rgb(c)}, ${rgb(c, 0)} ${r * 100}%)`),
+    rgb(base),
+  ].join(', ');
+}
+
+// The same picture on a 2D canvas of side `size`. CSS measures a circle
+// gradient's percentage against the box's diagonal over root two, which for a
+// square box is its side, so `reach * size` matches.
+export function paint2d(ctx, effect, c, size) {
+  const { base, spots } = paint(effect, c);
+  ctx.fillStyle = rgb(base);
+  ctx.fillRect(0, 0, size, size);
+  for (const [x, y, c, r] of [...spots].reverse()) {
+    const g = ctx.createRadialGradient(x * size, y * size, 0, x * size, y * size, r * size);
+    g.addColorStop(0, rgb(c));
+    g.addColorStop(1, rgb(c, 0));
+    ctx.fillStyle = g;
+    ctx.fillRect(0, 0, size, size);
+  }
+}

package/src/cursor.js

@@ -0,0 +1,137 @@
+import { mount } from './avatar.js';
+import { traits } from './seed.js';
+import { tagName } from './names.js';
+
+// Presence cursors with the avatar built in, in two styles:
+//   arrow  - a thick arrow in the seed's first two colors, and the live avatar
+//            beside the name on a dark tag.
+//   avatar - the live avatar itself is the pointer, a teardrop whose sharp
+//            corner is the tip, with the name beside it.
+// The tag shows `name`; without one it shows the seed's anonymous name (see
+// names.js), and `name: false` leaves the tag off.
+// Where the cursor is comes from the app (its realtime layer already knows);
+// the tip lands exactly on x, y.
+//   const c = cursor(canvasEl, { seed: user.id, name: 'Ada', variant: 'avatar' });
+//   c.move(x, y);
+
+export const ARROW = 'M4.037 4.688a.495.495 0 0 1 .651-.651l16 6.5a.5.5 0 0 1-.063.947l-6.124 1.58a2 2 0 0 0-1.438 1.435l-1.579 6.126a.5.5 0 0 1-.947.063z';
+const ARROW_PX = 26;
+// Where the tip sits inside each cursor's box.
+export const TIP = { arrow: (4 * ARROW_PX) / 24, avatar: 0 };
+
+// Cursor avatars never react to the pointer; they are the pointer.
+const QUIET = { interaction: 'none' };
+
+export function cursorColors(o) {
+  if (Array.isArray(o.colors) && o.colors.length >= 2) return o.colors;
+  return traits(o.seed, { effect: o.effect }).colors;
+}
+
+export function placeStyle(variant, x, y, zoom = 1) {
+  const t = (TIP[variant] ?? 0) * zoom;
+  return `translate(${x - t}px, ${y - t}px)`;
+}
+
+// Every measure takes a zoom, so a cursor can be drawn larger, for a preview
+// or a big screen, with its avatars rendered sharp at that size.
+export const sizes = (s = 1) => ({ arrow: ARROW_PX * s, drop: 28 * s, dot: Math.round(16 * s) });
+
+export const styles = {
+  root: { position: 'absolute', left: 0, top: 0, display: 'block', pointerEvents: 'none', willChange: 'transform' },
+  arrow: (s = 1) => ({
+    display: 'block', width: ARROW_PX * s, height: ARROW_PX * s, overflow: 'visible',
+    filter: `drop-shadow(0 ${s}px ${3 * s}px rgb(0 0 0 / 0.45))`,
+  }),
+  drop: (s = 1) => ({
+    display: 'block', width: 28 * s, height: 28 * s, overflow: 'hidden', borderRadius: `${s}px 50% 50% 50%`,
+    boxShadow: `0 0 0 ${2 * s}px #fff, 0 ${2 * s}px ${8 * s}px rgb(0 0 0 / 0.45)`,
+  }),
+  tag: (variant, s = 1) => ({
+    position: 'absolute', left: (variant === 'avatar' ? 32 : 20) * s, top: (variant === 'avatar' ? 26 : 24) * s,
+    display: 'flex', alignItems: 'center', gap: 6 * s, width: 'max-content', height: 24 * s,
+    padding: variant === 'avatar' ? `0 ${8 * s}px` : `0 ${8 * s}px 0 ${4 * s}px`,
+    borderRadius: `${4 * s}px ${10 * s}px ${10 * s}px ${10 * s}px`,
+    background: '#1f1f1f', boxShadow: `inset 0 0 0 ${s}px rgb(255 255 255 / 0.08)`,
+    color: 'rgb(255 255 255 / 0.92)', fontSize: 12 * s, fontWeight: 500, lineHeight: `${16 * s}px`, whiteSpace: 'nowrap',
+  }),
+};
+
+let ids = 0;
+const NS = 'http://www.w3.org/2000/svg';
+
+function arrowSvg(colors, zoom) {
+  const id = `crafted-cursor-${++ids}`;
+  const svg = document.createElementNS(NS, 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('width', ARROW_PX * zoom);
+  svg.setAttribute('height', ARROW_PX * zoom);
+  svg.setAttribute('aria-hidden', 'true');
+  Object.assign(svg.style, px(styles.arrow(zoom)));
+  svg.innerHTML = `<defs><linearGradient id="${id}" x1="0.1" y1="0.1" x2="0.9" y2="0.9"><stop offset="0" stop-color="${colors[0]}"/><stop offset="1" stop-color="${colors[1]}"/></linearGradient></defs><path d="${ARROW}" fill="url(#${id})" stroke="#fff" stroke-width="1.6" stroke-linejoin="round"/>`;
+  return svg;
+}
+
+const px = (style) => Object.fromEntries(Object.entries(style).map(([k, v]) => [k, typeof v === 'number' && k !== 'fontWeight' ? `${v}px` : v]));
+
+// Plain JS: appends a cursor to `el`, which should be positioned (relative or
+// absolute), since the cursor is placed inside it.
+export function cursor(el, options = {}) {
+  let o = { variant: 'arrow', ...options };
+  let pos = [o.x ?? 0, o.y ?? 0];
+  const root = document.createElement('span');
+  root.className = 'crafted-cursor';
+  root.setAttribute('aria-hidden', 'true');
+  Object.assign(root.style, px(styles.root));
+  el.append(root);
+  let faces = [];
+
+  const build = () => {
+    faces.forEach((f) => f.destroy());
+    faces = [];
+    root.replaceChildren();
+    const { variant, name, x, y, zoom = 1, ...avatarOptions } = o;
+    const look = { ...avatarOptions, ...QUIET };
+    const size = sizes(zoom);
+    if (variant === 'avatar') {
+      const drop = document.createElement('span');
+      Object.assign(drop.style, px(styles.drop(zoom)));
+      const host = document.createElement('span');
+      drop.append(host);
+      root.append(drop);
+      faces.push(mount(host, { ...look, size: size.drop, shape: 'square' }));
+    } else {
+      root.append(arrowSvg(cursorColors(o), zoom));
+    }
+    const label = tagName(name, o.seed);
+    if (label) {
+      const tag = document.createElement('span');
+      Object.assign(tag.style, px(styles.tag(variant, zoom)));
+      if (variant !== 'avatar') {
+        const host = document.createElement('span');
+        tag.append(host);
+        faces.push(mount(host, { ...look, size: size.dot }));
+      }
+      tag.append(label);
+      root.append(tag);
+    }
+    root.style.transform = placeStyle(o.variant, ...pos, o.zoom);
+  };
+  build();
+
+  return {
+    element: root,
+    move(x, y) {
+      pos = [x, y];
+      root.style.transform = placeStyle(o.variant, x, y, o.zoom);
+    },
+    update(next) {
+      o = { ...o, ...next };
+      if (next.x !== undefined || next.y !== undefined) pos = [o.x ?? pos[0], o.y ?? pos[1]];
+      build();
+    },
+    destroy() {
+      faces.forEach((f) => f.destroy());
+      root.remove();
+    },
+  };
+}

package/src/element.js

@@ -0,0 +1,37 @@
+import { mount } from './avatar.js';
+import { DEFAULTS } from './options.js';
+
+const ATTRS = ['seed', 'size', 'effect', 'colors', 'motion', 'speed', 'distortion', 'scale', 'grain', 'shape', 'interaction', 'stretch', 'thickness', 'ring', 'ring-color', 'label'];
+const prop = (a) => a.replace(/-(\w)/g, (_, c) => c.toUpperCase());
+
+// Registers <crafted-avatar>, for any framework or none.
+//   <crafted-avatar seed="dexter@craftedstudios.co" size="40"></crafted-avatar>
+export function defineAvatarElement(name = 'crafted-avatar') {
+  if (typeof customElements === 'undefined' || customElements.get(name)) return;
+  customElements.define(name, class extends HTMLElement {
+    static observedAttributes = ATTRS;
+
+    options() {
+      // Start from the defaults so a removed attribute goes back to its default.
+      const o = { ...DEFAULTS };
+      for (const a of ATTRS) if (this.hasAttribute(a)) o[prop(a)] = this.getAttribute(a);
+      return o;
+    }
+
+    connectedCallback() {
+      if (!this.avatar) this.avatar = mount(this, this.options());
+    }
+
+    disconnectedCallback() {
+      // Moving the element in the DOM disconnects and reconnects it in the
+      // same task; only tear down if it is really gone.
+      queueMicrotask(() => {
+        if (!this.isConnected && this.avatar) { this.avatar.destroy(); this.avatar = null; }
+      });
+    }
+
+    attributeChangedCallback() {
+      this.avatar?.update(this.options());
+    }
+  });
+}