agent-robot-avatar 0.5.2 → 0.7.0

package/src/agent-robot-avatar-core.js

@@ -374,8 +374,11 @@ const AgentRobotAvatar = (() => {
       const near = Math.max(r.width, r.height) * 2.55;
       const dist = Math.hypot(dx, dy);
       const influence = clamp(1 - dist / near, 0, 1);
-      this._pointer.x = clamp(dx * .42, -48, 48);
-      this._pointer.y = clamp(dy * .38, -34, 34);
+      // Measure the pointer offset as if the avatar were demo-sized, so a large
+      // avatar does not look further than a small one for the same gesture.
+      const scale = Math.min(1, 120 / Math.max(1, r.width, r.height));
+      this._pointer.x = clamp(dx * .42 * scale, -48, 48);
+      this._pointer.y = clamp(dy * .38 * scale, -34, 34);
       this._pointer.active = influence > 0.001;
       this._pointer.influence = influence;
       this._pointer.lastMove = performance.now();

package/src/agent-robot-avatar-gestures.js

@@ -42,6 +42,15 @@ proto.setPressSqueeze=function(enabled=true){
   if(!enabled && this._gestureFx?.kind==='squeeze')this._cancelGesture();
   return this;
 };
+// Antenna blinking was removed in 0.6. The method stays so existing calls keep working.
+let warnedAntennaFlash=false;
+proto.setAntennaFlash=function(){
+  if(!warnedAntennaFlash){
+    warnedAntennaFlash=true;
+    console.warn('agent-robot-avatar: setAntennaFlash() was removed in 0.6 and does nothing. It will be deleted in 1.0.');
+  }
+  return this;
+};
 proto.setAntennaDrag=function(enabled=true){
   this.setAttribute('antenna-drag',String(Boolean(enabled)));
   if(!enabled && this._gestureFx?.kind==='antenna-drag')this._cancelGesture();

package/src/agent-robot-avatar-runtime.js

@@ -24,28 +24,36 @@ const baseStopWaiting = proto.stopWaiting;
 const baseDraw = proto._draw;
 
 const DEFAULT_SIZE = 112;
+// Canonical action names describe what the avatar does on screen. Older names that
+// described a situation (send, warning, blocked, error, ...) still resolve to the same
+// action, but print a one-time deprecation notice; they are removed in 1.0.
 const ACTION_ALIASES = Object.freeze({
   idle: 'idle',
   bored: 'bored',
   waiting: 'waiting',
+  'waiting-spin': 'waiting',
   wait: 'waiting',
   'waiting-wrap': 'waiting',
+  'waiting-wave': 'waiting',
   input: 'input',
-  send: 'send',
+  affirm: 'affirm',
+  send: 'affirm',
   success: 'success',
   failure: 'failure',
   failed: 'failure',
   fail: 'failure',
-  warning: 'warning',
+  wary: 'wary',
+  warning: 'wary',
   inspect: 'inspect',
   verify: 'inspect',
   review: 'inspect',
   angry: 'angry',
-  blocked: 'blocked',
-  'policy-blocked': 'blocked',
-  error: 'error',
-  'system-error': 'error',
-  'connection-error': 'error',
+  blocked: 'angry',
+  'policy-blocked': 'angry',
+  refuse: 'refuse',
+  error: 'refuse',
+  'system-error': 'refuse',
+  'connection-error': 'refuse',
   surprise: 'surprise',
   love: 'love',
   random: 'random',
@@ -54,10 +62,44 @@ const ACTION_ALIASES = Object.freeze({
   wake: 'wake',
 });
 
+const DEPRECATED_ACTIONS = Object.freeze({
+  wait: 'waiting-spin',
+  send: 'affirm',
+  failed: 'failure',
+  fail: 'failure',
+  warning: 'wary',
+  verify: 'inspect',
+  review: 'inspect',
+  blocked: 'angry',
+  'policy-blocked': 'angry',
+  error: 'refuse',
+  'system-error': 'refuse',
+  'connection-error': 'refuse',
+  slot: 'random',
+});
+
+// The renamed actions still run on the original implementations.
+const ACTION_IMPLEMENTATIONS = Object.freeze({
+  'waiting-spin': 'waiting',
+  affirm: 'send',
+  wary: 'warning',
+  refuse: 'error',
+});
+
+const warnedDeprecations = new Set();
+
+function warnDeprecatedAction(raw) {
+  const replacement = DEPRECATED_ACTIONS[raw];
+  if (!replacement || warnedDeprecations.has(raw)) return;
+  warnedDeprecations.add(raw);
+  console.warn(`agent-robot-avatar: action "${raw}" is deprecated, use "${replacement}". Old names stop working in 1.0.`);
+}
+
 function normalizeAction(name) {
   const raw = String(name || '').trim().toLowerCase();
   const canonical = Object.hasOwn(ACTION_ALIASES, raw) ? ACTION_ALIASES[raw] : null;
-  return { raw, canonical };
+  if (canonical) warnDeprecatedAction(raw);
+  return { raw, canonical, implementation: ACTION_IMPLEMENTATIONS[raw] ?? raw };
 }
 
 function wakePolicy(instance) {
@@ -402,15 +444,18 @@ function ensureRuntime(instance) {
         if (record.attributeName === 'size') applySize(instance);
         if (record.attributeName === 'motion') motionChanged = true;
         if (record.attributeName === 'auto-sleep') autoSleepChanged = true;
+        if (record.attributeName === 'skin') instance._applySkinAttribute?.();
       }
       if (motionChanged) handleMotionChange(instance);
       if (autoSleepChanged) scheduleAutoSleep(instance);
     });
     instance._runtimeAttributeObserver.observe(instance, {
       attributes: true,
-      attributeFilter: ['size', 'motion', 'wake-on', 'auto-sleep'],
+      attributeFilter: ['size', 'motion', 'wake-on', 'auto-sleep', 'skin'],
     });
   }
+  // A skin set with setSkin() survives a reconnect; markup only applies when present.
+  if (instance.hasAttribute('skin')) instance._applySkinAttribute?.();
 
   if (typeof IntersectionObserver !== 'undefined') {
     instance._runtimeIntersectionObserver = new IntersectionObserver(entries => {
@@ -717,17 +762,17 @@ function prepareReplacement(instance, canonical) {
 
 proto.play = function(name) {
   ensureRuntime(this);
-  const { raw, canonical } = normalizeAction(name);
+  const { canonical, implementation } = normalizeAction(name);
   if (!canonical) throw new Error(`Unknown Agent Robot Avatar action: ${name}`);
   if (playNoOp(this, canonical)) return this;
-  if (canonical === 'idle') return basePlay.call(this, raw);
+  if (canonical === 'idle') return basePlay.call(this, implementation);
 
   prepareReplacement(this, canonical);
 
   let result;
   this._runtimeInPlay = true;
   try {
-    result = basePlay.call(this, raw);
+    result = basePlay.call(this, implementation);
   } finally {
     this._runtimeInPlay = false;
   }
@@ -903,3 +948,4 @@ export {
   DEFAULT_SIZE,
 };
 export default AgentRobotAvatar;
+

package/src/agent-robot-avatar-skin-patterns.js

@@ -0,0 +1,234 @@
+// Pattern tiles for skins. Each generator returns the tile size, an optional
+// pattern transform and the SVG markup of one tile, in the head's 240-unit
+// coordinates. Scattered patterns use a seeded random source so every avatar
+// shows the same tile.
+
+const rng = seed => {
+  let state = (seed % 2147483647) || 1;
+  return () => (state = state * 16807 % 2147483647) / 2147483647;
+};
+const n = value => Number(value.toFixed(2));
+const pick = (random, list) => list[Math.floor(random() * list.length) % list.length];
+
+// Repeats an element at the tile edges so scattered shapes wrap seamlessly.
+function wrap(size, x, y, r, draw) {
+  let out = '';
+  for (const dx of [-size, 0, size]) for (const dy of [-size, 0, size]) {
+    if (x + dx + r < 0 || x + dx - r > size || y + dy + r < 0 || y + dy - r > size) continue;
+    out += draw(x + dx, y + dy);
+  }
+  return out;
+}
+
+// Turns a point on the unit sphere, for the patterns drawn on balls.
+function rotate([x, y, z], [yaw, pitch, roll]) {
+  let c = Math.cos(yaw), s = Math.sin(yaw);
+  [x, z] = [x * c + z * s, -x * s + z * c];
+  c = Math.cos(pitch); s = Math.sin(pitch);
+  [y, z] = [y * c - z * s, y * s + z * c];
+  c = Math.cos(roll); s = Math.sin(roll);
+  [x, y] = [x * c - y * s, x * s + y * c];
+  return [x, y, z];
+}
+
+
+
+
+
+const PATTERNS = {
+  tartan({ colors: [a, b, c], size = 56 }) {
+    const bands = [[0, 18, a, .55], [26, 3, b, .8], [38, 2, c, .8], [44, 6, a, .35]];
+    let body = '';
+    for (const [x, w, color, o] of bands) {
+      body += `<rect x="${x}" width="${w}" height="${size}" fill="${color}" opacity="${o}"/><rect y="${x}" width="${size}" height="${w}" fill="${color}" opacity="${o}"/>`;
+    }
+    return { size: [size, size], body };
+  },
+  dots({ colors: [c], r = 5, size = 26, opacity = 1 }) {
+    const q = size / 4;
+    return { size: [size, size], body: `<circle cx="${q}" cy="${q}" r="${r}" fill="${c}" opacity="${opacity}"/><circle cx="${q * 3}" cy="${q * 3}" r="${r}" fill="${c}" opacity="${opacity}"/>` };
+  },
+  terrazzo({ colors, count = 44, size = 120, seed = 5 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let i = 0; i < count; i++) {
+      const x = random() * size, y = random() * size, k = 2.5 + random() * 6, sides = 3 + Math.floor(random() * 3), color = pick(random, colors), turn = random() * Math.PI;
+      let d = '';
+      for (let j = 0; j < sides; j++) {
+        const a = turn + j / sides * Math.PI * 2, rr = k * (.6 + random() * .5);
+        d += `${j ? 'L' : 'M'}${n(Math.cos(a) * rr)} ${n(Math.sin(a) * rr)}`;
+      }
+      body += wrap(size, x, y, k, (px, py) => `<path d="${d}Z" fill="${color}" transform="translate(${n(px)} ${n(py)})"/>`);
+    }
+    return { size: [size, size], body };
+  },
+  marble({ colors: [a, b], seed = 21 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let i = 0; i < 7; i++) {
+      const color = i % 3 === 2 ? b : a;
+      let x = -20, y = random() * 240, d = `M${n(x)} ${n(y)}`;
+      while (x < 260) {
+        const nx = x + 30 + random() * 40, ny = y + (random() - .5) * 70;
+        d += `Q${n(x + 15 + random() * 20)} ${n(y + (random() - .5) * 60)} ${n(nx)} ${n(ny)}`;
+        x = nx; y = ny;
+      }
+      body += `<path d="${d}" fill="none" stroke="${color}" stroke-width="${n(.6 + random() * 1.8)}" opacity="${n(.35 + random() * .35)}"/>`;
+      body += `<path d="${d}" fill="none" stroke="${color}" stroke-width="${n(5 + random() * 6)}" opacity=".07"/>`;
+    }
+    return { size: [240, 240], body };
+  },
+  pixel({ colors, cell = 10, size = 80, seed = 31, opacity = .9 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let y = 0; y < size; y += cell) for (let x = 0; x < size; x += cell) {
+      if (random() < .45) continue;
+      body += `<rect x="${x}" y="${y}" width="${cell}" height="${cell}" fill="${pick(random, colors)}" opacity="${opacity}"/>`;
+    }
+    return { size: [size, size], body };
+  },
+  confetti({ colors, count = 38, size = 120, seed = 37 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let i = 0; i < count; i++) {
+      const x = random() * size, y = random() * size, color = pick(random, colors), turn = random() * 180, strip = random() < .5;
+      body += wrap(size, x, y, 6, (px, py) => strip
+        ? `<rect x="${n(px - 1.6)}" y="${n(py - 4)}" width="3.2" height="8" rx="1" fill="${color}" transform="rotate(${n(turn)} ${n(px)} ${n(py)})"/>`
+        : `<circle cx="${n(px)}" cy="${n(py)}" r="2.2" fill="${color}"/>`);
+    }
+    return { size: [size, size], body };
+  },
+  halftone({ colors: [c], step = 12, opacity = .7 }) {
+    let body = '';
+    for (let y = 6; y < 240; y += step) for (let x = 6 + ((y / step) % 2) * step / 2; x < 240; x += step) {
+      body += `<circle cx="${n(x)}" cy="${n(y)}" r="${n(.6 + 4.4 * (y / 240))}" fill="${c}" opacity="${opacity}"/>`;
+    }
+    return { size: [240, 240], body };
+  },
+  scatter({ colors, shapes, count = 12, size = 120, k = [6, 10], seed = 47 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let i = 0; i < count; i++) {
+      const x = random() * size, y = random() * size, r = k[0] + random() * (k[1] - k[0]), turn = (random() - .5) * 70;
+      const shape = pick(random, shapes), color = colors[i % colors.length], accent = colors[(i + 1) % colors.length];
+      const art = SHAPES[shape](r, color, accent);
+      body += wrap(size, x, y, r * 1.3, (px, py) => `<g transform="translate(${n(px)} ${n(py)}) rotate(${n(turn)})">${art}</g>`);
+    }
+    return { size: [size, size], body };
+  },
+  grooves({ colors: [line, shadow], radius = 138, angles = [.5, -.45, .2] }) {
+    // A modern ball: rings of fine grooves wrapping the surface in three directions.
+    let body = '';
+    for (const axis of [[1, 0, 0], [0, 1, 0], [0, 0, 1]]) {
+      for (const lat of [-.42, 0, .42]) {
+        const pts = [];
+        for (let k = 0; k <= 72; k++) {
+          const a = k / 72 * Math.PI * 2, r = Math.cos(lat), h = Math.sin(lat);
+          const p = axis[0] ? [h, r * Math.cos(a), r * Math.sin(a)] : axis[1] ? [r * Math.cos(a), h, r * Math.sin(a)] : [r * Math.cos(a), r * Math.sin(a), h];
+          pts.push(rotate(p, angles));
+        }
+        let d = '';
+        pts.forEach(([x, y, z], i) => { d += `${i && z > 0 && pts[i - 1][2] > 0 ? 'L' : 'M'}${n(120 + x * radius)} ${n(120 + y * radius)}`; });
+        body += `<path d="${d}" fill="none" stroke="${shadow}" stroke-width="3" opacity=".6" transform="translate(.8 1)"/><path d="${d}" fill="none" stroke="${line}" stroke-width="1.6"/>`;
+      }
+    }
+    return { size: [240, 240], body };
+  },
+  // Balls: each is drawn once across the whole head instead of repeating.
+  basketball({ colors: [seam, grain] }) {
+    return {
+      size: [240, 240],
+      defs: tex => `<pattern id="${tex}" patternUnits="userSpaceOnUse" width="6" height="6"><circle cx="3" cy="3" r=".9" fill="${grain}" opacity=".32"/></pattern>`,
+      body: tex => `<rect width="240" height="240" fill="url(#${tex})"/><path d="M120 0V240M0 120H240M52 18Q100 120 52 222M188 18Q140 120 188 222" fill="none" stroke="#ffd2a6" stroke-width="2.4" stroke-linecap="round" opacity=".55" transform="translate(1.2 1.6)"/><path d="M120 0V240M0 120H240M52 18Q100 120 52 222M188 18Q140 120 188 222" fill="none" stroke="${seam}" stroke-width="3.4" stroke-linecap="round"/>`,
+    };
+  },
+
+
+
+
+
+  tennis({ colors: [seam, fuzz] }) {
+    return {
+      size: [240, 240],
+      defs: tex => `<pattern id="${tex}" patternUnits="userSpaceOnUse" width="7" height="7"><circle cx="1.5" cy="2" r=".7" fill="${fuzz}" opacity=".35"/><circle cx="5" cy="5.5" r=".6" fill="#ffffff" opacity=".3"/></pattern>`,
+      body: tex => `<rect width="240" height="240" fill="url(#${tex})"/><path d="M14 62C92 34 92 206 14 178M226 62C148 34 148 206 226 178" fill="none" stroke="#f7ffd0" stroke-width="6.5" stroke-linecap="round" opacity=".45" transform="translate(1 1.6)"/><path d="M14 62C92 34 92 206 14 178M226 62C148 34 148 206 226 178" fill="none" stroke="#4a6000" stroke-width="6.5" stroke-linecap="round" opacity=".38" transform="translate(-1 -1.6)"/><path d="M14 62C92 34 92 206 14 178M226 62C148 34 148 206 226 178" fill="none" stroke="${seam}" stroke-width="5" stroke-linecap="round"/>`,
+    };
+  },
+  baseball({ colors: [seam, stitch] }) {
+    const arc = (x0, cx) => {
+      let stitches = '';
+      for (let t = .06; t < .96; t += .055) {
+        const x = (1 - t) ** 2 * x0 + 2 * (1 - t) * t * cx + t * t * x0, y = (1 - t) ** 2 * 26 + 2 * (1 - t) * t * 120 + t * t * 214;
+        const dx = 2 * (1 - t) * (cx - x0) + 2 * t * (x0 - cx), dy = 2 * (1 - t) * 94 + 2 * t * 94, len = Math.hypot(dx, dy);
+        const nx = -dy / len * 5, ny = dx / len * 5, tx = dx / len * 2.2, ty = dy / len * 2.2;
+        stitches += `M${n(x - nx - tx)} ${n(y - ny - ty)}L${n(x)} ${n(y)}L${n(x + nx - tx)} ${n(y + ny - ty)}`;
+      }
+      return `<path d="M${x0} 26Q${cx} 120 ${x0} 214" fill="none" stroke="${seam}" stroke-width="1.3"/><path d="${stitches}" fill="none" stroke="${stitch}" stroke-width="2" stroke-linecap="round"/>`;
+    };
+    return { size: [240, 240], body: arc(44, 104) + arc(196, 136) };
+  },
+  cricket({ colors: [seam, stitch] }) {
+    // A raised seam arching over the forehead with three rows of stitches each side.
+    const y = (x, lift) => 84 - Math.sin(x / 240 * Math.PI) * 26 + lift;
+    const curve = lift => {
+      let d = '';
+      for (let x = -4; x <= 244; x += 8) d += `${x < 0 ? 'M' : 'L'}${x} ${n(y(x, lift))}`;
+      return d;
+    };
+    let rows = '';
+    for (const lift of [-11, -7, -3, 3, 7, 11]) {
+      for (let x = 2; x < 240; x += 6) rows += `M${x} ${n(y(x, lift))}l2.6 -1.2`;
+    }
+    return { size: [240, 240], body: `<path d="${curve(0)}" fill="none" stroke="${seam}" stroke-width="15" stroke-linecap="round" opacity=".55"/><path d="${curve(0)}" fill="none" stroke="${seam}" stroke-width="2"/><path d="${rows}" fill="none" stroke="${stitch}" stroke-width="1.5" stroke-linecap="round"/>` };
+  },
+
+
+
+
+
+
+
+
+
+  golf({ colors: [shade, shine], r = 5.6 }) {
+    const w = 15, h = w * Math.sqrt(3);
+    const dimple = (x, y) => `<circle cx="${n(x)}" cy="${n(y)}" r="${r}" fill="${shade}" opacity=".55"/><circle cx="${n(x + .9)}" cy="${n(y + 1)}" r="${n(r * .55)}" fill="${shine}" opacity=".8"/>`;
+    return { size: [w, n(h)], body: dimple(0, 0) + dimple(w, 0) + dimple(w / 2, h / 2) + dimple(0, h) + dimple(w, h) };
+  },
+  football({ colors: [lace, grain, seam] }) {
+    // Lying on its side: laces run along the top, stripes ring both ends.
+    let stitches = '';
+    for (let x = 90; x <= 150; x += 10) stitches += `M${x} 44V60`;
+    return {
+      size: [240, 240],
+      defs: tex => `<pattern id="${tex}" patternUnits="userSpaceOnUse" width="5" height="5"><circle cx="2.5" cy="2.5" r=".8" fill="${grain}" opacity=".35"/></pattern>`,
+      body: tex => `<rect width="240" height="240" fill="url(#${tex})"/>`
+        + `<path d="M-10 40Q120 62 250 40M-10 210Q120 188 250 210" fill="none" stroke="${seam}" stroke-width="1.4" opacity=".7"/>`
+        + `<g transform="translate(1 1.6)" opacity=".35"><path d="M84 52H156" stroke="#1a0800" stroke-width="2"/><path d="${stitches}" stroke="#1a0800" stroke-width="3.6" stroke-linecap="round"/></g>`
+        + `<path d="M84 52H156" stroke="${lace}" stroke-width="2"/><path d="${stitches}" stroke="${lace}" stroke-width="3.4" stroke-linecap="round"/>`
+        + `<path d="M34 20Q46 120 34 220M46 20Q58 120 46 220M206 20Q194 120 206 220M194 20Q182 120 194 220" fill="none" stroke="${lace}" stroke-width="5"/>`,
+    };
+  },
+};
+
+const SHAPES = {
+  leaf: (k, c, accent) => `<path d="M0 ${n(-k)}Q${n(.65 * k)} 0 0 ${n(k)}Q${n(-.65 * k)} 0 0 ${n(-k)}Z" fill="${c}"/><path d="M0 ${n(-.8 * k)}V${n(.9 * k)}" stroke="${accent}" stroke-width="${n(.08 * k)}"/>`,
+  blossom: (k, c, accent) => `${[0, 72, 144, 216, 288].map(a => `<ellipse cy="${n(-.5 * k)}" rx="${n(.3 * k)}" ry="${n(.45 * k)}" fill="${c}" transform="rotate(${a})"/>`).join('')}<circle r="${n(.2 * k)}" fill="${accent}"/>`,
+};
+
+// A generator may also return defs (for example a fine texture tile) that its
+// body refers to; both receive the texture id.
+// Generated tiles are cached per spec; ball layouts take a moment to work out.
+const tiles = new Map();
+function patternMarkup(id, spec) {
+  const make = PATTERNS[spec.kind];
+  if (!make) return '';
+  const key = JSON.stringify(spec);
+  if (!tiles.has(key)) tiles.set(key, make(spec));
+  const { size: [w, h], transform, body, defs } = tiles.get(key);
+  const tex = `${id}-texture`;
+  const inner = typeof body === 'function' ? body(tex) : body;
+  return `${defs ? defs(tex) : ''}<pattern id="${id}" patternUnits="userSpaceOnUse" width="${w}" height="${h}"${transform ? ` patternTransform="${transform}"` : ''}>${inner}</pattern>`;
+}
+
+export { PATTERNS, patternMarkup };

package/src/agent-robot-avatar-skins.js

@@ -0,0 +1,256 @@
+import AgentRobotAvatar, { registerAvatarExtension } from './agent-robot-avatar-extension-host.js';
+import { SKIN_CATALOG, SKIN_SERIES } from './skins/catalog.js';
+
+// The painters are large, so they load the first time a skin needs them. A page
+// that never uses a skin never downloads them.
+const painters = {};
+const loading = {};
+function loadPainter(kind) {
+  loading[kind] ??= Promise.all([
+    import('./skins/paints.js'),
+    kind === 'native' ? import('./skins/native.js') : import('./skins/material-library.js'),
+    import('./skins/eyelids.js'),
+  ]).then(([paints, painter, eyelids]) => {
+    painters.paints = paints.SKIN_PAINTS;
+    painters.maskEyelids = eyelids.maskEyelids;
+    painters[kind] = painter;
+  });
+  return loading[kind];
+}
+
+/** Loads every skin painter now, so later skins show on the same frame they are set. */
+function loadSkins() {
+  return Promise.all([loadPainter('native'), loadPainter('material')]).then(() => undefined);
+}
+
+const proto = AgentRobotAvatar.prototype;
+const baseApplyColor = proto._applyColor;
+
+// Skins are numbered. The number is the permanent public name; the Chinese and
+// English titles are for display and may be reworded later. SKIN_NAMES lists
+// them in display order, series by series.
+const SKIN_NAMES = Object.freeze(SKIN_SERIES.flatMap(series => series.skins));
+const SKINS = Object.freeze(Object.fromEntries(Object.entries(SKIN_CATALOG).map(([id, skin]) => [id,
+  Object.freeze({ series: skin.series, title: skin.zh, titleEn: skin.en, base: Object.freeze([...skin.base]) })])));
+const SERIES = Object.freeze(SKIN_SERIES.map(series => Object.freeze({
+  id: series.id, number: series.number, title: series.zh, titleEn: series.en, skins: Object.freeze([...series.skins]),
+})));
+
+const REST_LIGHT = Object.freeze({ x: -0.5, y: -0.5 });
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+
+function normalizeSkin(value) {
+  const text = String(value ?? '').trim().toLowerCase();
+  if (!text || text === 'none') return null;
+  const name = /^\d+$/.test(text) ? String(Number(text)) : text;
+  return Object.hasOwn(SKIN_CATALOG, name) ? name : undefined;
+}
+
+// Hand adjustments from the skin workshop, applied after a skin is painted.
+// A record names an element by id or selector, optionally a child path, and the
+// attributes to set on it.
+function findPainted(root, record) {
+  let node = record.id ? root.getElementById(record.id) : root.querySelector(record.selector);
+  for (const index of record.path || []) node = node?.children[index];
+  return node;
+}
+
+// Some adjustments touch layers every skin shares, so each change is recorded
+// and undone before the next skin is painted.
+function paintAdjustments(instance, name) {
+  const records = painters.paints[name]?.paint || [];
+  const root = instance.shadowRoot;
+  const undo = instance._skinUndo ??= [];
+  for (const record of records) {
+    const node = findPainted(root, record);
+    if (!node) continue;
+    for (const [attribute, value] of Object.entries(record.attributes)) {
+      undo.push(() => {
+        if (old === null) node.removeAttribute(attribute);
+        else node.setAttribute(attribute, old);
+      });
+      const old = node.getAttribute(attribute);
+      node.setAttribute(attribute, value);
+    }
+  }
+  for (const [property, value] of Object.entries(painters.paints[name]?.properties || {})) {
+    const old = instance.style.getPropertyValue(property);
+    undo.push(() => old ? instance.style.setProperty(property, old) : instance.style.removeProperty(property));
+    instance.style.setProperty(property, value);
+  }
+}
+
+function undoAdjustments(instance) {
+  const undo = instance._skinUndo;
+  while (undo?.length) undo.pop()();
+}
+
+// Adjustments to light-driven attributes were made with the light at rest. They
+// become offsets so they move with the light instead of being overwritten.
+function adjustNative(instance, skin, name) {
+  const { lightNative } = painters.native;
+  const { x, y } = skin.light;
+  lightNative(instance, REST_LIGHT.x, REST_LIGHT.y);
+  const resting = Object.entries(skin.nodes).map(([key, node]) => {
+    const attribute = key.slice(key.lastIndexOf('.') + 1);
+    return { key, node, attribute, value: parseFloat(node.getAttribute(attribute)) };
+  });
+  paintAdjustments(instance, name);
+  for (const { key, node, attribute, value } of resting) {
+    const adjusted = parseFloat(node.getAttribute(attribute));
+    if (Number.isFinite(adjusted) && Number.isFinite(value) && adjusted !== value) skin.offsets[key] = adjusted - value;
+  }
+  skin.shown = {};
+  lightNative(instance, x, y);
+}
+
+function adjustMaterial(instance, material, name) {
+  const records = painters.paints[name]?.paint || [];
+  const root = instance.shadowRoot;
+  const key = SKIN_CATALOG[name].material;
+  const offsets = [];
+  for (const lightKey of material.lightKeys || []) {
+    const [suffix, attribute] = lightKey.split(':');
+    const record = records.find(r => r.id === `material-${key}-${suffix}` && !r.path?.length);
+    const node = record && findPainted(root, record);
+    const value = record?.attributes[attribute];
+    if (node && value != null) offsets.push({ node, attribute, delta: parseFloat(value) - parseFloat(node.getAttribute(attribute)) });
+  }
+  paintAdjustments(instance, name);
+  const light = material.light.bind(material);
+  material.light = (x, y) => {
+    light(x, y);
+    for (const { node, attribute, delta } of offsets) node.setAttribute(attribute, parseFloat(node.getAttribute(attribute)) + delta);
+  };
+}
+
+function render(instance) {
+  const name = instance._skinName ?? null;
+  if (instance._skinShown === name || !instance._head) return;
+  const entry = name ? SKIN_CATALOG[name] : null;
+  const kind = entry ? (entry.native ? 'native' : 'material') : null;
+  if (kind && !painters[kind]) {
+    // Draw it once the painter arrives, unless another skin was chosen meanwhile.
+    if (instance._skinPending !== name) {
+      instance._skinPending = name;
+      loadPainter(kind).then(() => {
+        instance._skinPending = undefined;
+        if ((instance._skinName ?? null) === name) render(instance);
+      });
+    }
+    return;
+  }
+  const { showNative } = painters.native || {};
+  undoAdjustments(instance);
+  instance._material?.dispose();
+  instance._material = null;
+  if (!entry?.native) showNative?.(instance, null);
+  instance._skinShown = name;
+  // Without a skin the head takes the current color attribute again.
+  if (!entry) {
+    baseApplyColor.call(instance, instance.getAttribute('color'));
+    return;
+  }
+  if (entry.native) {
+    // Frames may stop as soon as love ends, so the joined heart is split here.
+    if (!instance._skinLoveEnd) {
+      instance._skinLoveEnd = event => {
+        if (event.detail?.state !== 'love') painters.native?.separateNativeEyes(instance);
+      };
+      instance.addEventListener('face-state', instance._skinLoveEnd);
+    }
+    const skin = showNative(instance, entry.native);
+    if (skin) {
+      const light = instance._skinLight;
+      if (light) { skin.light.x = light.x; skin.light.y = light.y; }
+      adjustNative(instance, skin, name);
+    }
+  } else {
+    // The lids cut the eyes through a mask, so the head paint shows behind them.
+    painters.maskEyelids(instance);
+    const material = painters.material.applyMaterial(instance, entry.material);
+    adjustMaterial(instance, material, name);
+    instance._material = material;
+    instance._materialLight = null;
+  }
+}
+
+// The light follows the pointer the same way the eyes do, and rests at the
+// upper left when the pointer is away, following is off, or motion is reduced.
+function updateLight(instance) {
+  const name = instance._skinShown;
+  if (!name) return;
+  const pointer = instance._pointer;
+  const reduced = instance._isReducedMotion?.();
+  const follows = instance._pointerFollowEnabled !== false && !reduced && pointer?.active && pointer.lastMove > 0;
+  const pull = follows ? Math.pow(clamp(pointer.influence || 0, 0, 1), .7) : 0;
+  // Pages can pin the light with _skinFixedLight = { x, y } in [-1, 1].
+  const fixed = instance._skinFixedLight;
+  const tx = fixed ? fixed.x : REST_LIGHT.x + (clamp(pointer?.x / 48, -1, 1) - REST_LIGHT.x) * pull;
+  const ty = fixed ? fixed.y : REST_LIGHT.y + (clamp(pointer?.y / 34, -1, 1) - REST_LIGHT.y) * pull;
+  const light = instance._skinLight ??= { ...REST_LIGHT };
+  if (reduced) {
+    light.x = tx;
+    light.y = ty;
+  } else {
+    light.x += ((Number.isFinite(tx) ? tx : REST_LIGHT.x) - light.x) * .18;
+    light.y += ((Number.isFinite(ty) ? ty : REST_LIGHT.y) - light.y) * .18;
+  }
+  if (SKIN_CATALOG[name].native) {
+    painters.native.joinNativeEyes(instance);
+    painters.native.lightNative(instance, light.x, light.y);
+  } else if (instance._material) {
+    const last = instance._materialLight;
+    if (last && Math.abs(last.x - light.x) < .0005 && Math.abs(last.y - light.y) < .0005) return;
+    instance._materialLight = { x: light.x, y: light.y };
+    instance._material.light(light.x, light.y);
+  }
+}
+
+// The runtime's attribute observer calls this when the skin attribute changes
+// and once on connect. An unknown name in markup falls back to no skin with a
+// console notice, so an invalid attribute never breaks the page; setSkin()
+// throws instead.
+proto._applySkinAttribute = function() {
+  const value = this.getAttribute('skin');
+  if (normalizeSkin(value) === undefined) {
+    console.warn(`agent-robot-avatar: unknown skin "${value}". Use a skin number such as ${SKIN_NAMES[0]}, or none.`);
+    this.setSkin(null);
+  } else {
+    this.setSkin(value);
+  }
+};
+
+proto.setSkin = function(value = null) {
+  const name = normalizeSkin(value);
+  if (name === undefined) throw new Error(`Unknown Agent Robot Avatar skin: ${value}`);
+  this._skinName = name;
+  render(this);
+  this._resumeFrames?.();
+  return this;
+};
+
+proto.getSkin = function() {
+  return this._skinName ?? null;
+};
+
+// A skin keeps the head paint even when the color attribute changes; removing
+// the skin brings the color back.
+proto._applyColor = function(value) {
+  baseApplyColor.call(this, value);
+  const entry = this._skinShown ? SKIN_CATALOG[this._skinShown] : null;
+  if (!entry || !this._head) return;
+  this._head.setAttribute('fill', entry.native ? 'url(#skin-base)' : `url(#material-${entry.material}-base)`);
+};
+
+registerAvatarExtension({
+  name: 'skins',
+  draw() {
+    // A skin set before the avatar was ready is shown on its first frame.
+    if ((this._skinName ?? null) !== (this._skinShown ?? null)) render(this);
+    updateLight(this);
+  },
+});
+
+export { AgentRobotAvatar, SKINS, SKIN_NAMES, SERIES as SKIN_SERIES, loadSkins };
+export default AgentRobotAvatar;

package/src/agent-robot-avatar-version.js

@@ -1,3 +1,3 @@
-const VERSION = '0.5.2';
+const VERSION = '0.7.0';
 
 export { VERSION };