agent-robot-avatar 0.2.1 → 0.3.1

package/index.d.ts

@@ -38,8 +38,38 @@ export type AgentRobotAvatarState =
   | 'inspect'
   | 'failure';
 
+export type AgentRobotAvatarCanonicalAction =
+  | 'idle'
+  | 'bored'
+  | 'waiting'
+  | 'input'
+  | 'send'
+  | 'success'
+  | 'failure'
+  | 'warning'
+  | 'inspect'
+  | 'angry'
+  | 'blocked'
+  | 'error'
+  | 'surprise'
+  | 'sleep'
+  | 'wake'
+  | 'reaction';
+
+export type AgentRobotAvatarActionPhase = 'start' | 'end' | 'cancel';
+export type AgentRobotAvatarActionSource = 'api' | 'interaction' | 'automatic';
+export type AgentRobotAvatarWakeOn = 'activity' | 'interaction' | 'manual';
+export type AgentRobotAvatarMotion = 'auto' | 'reduce' | 'full';
+
+export interface AgentRobotAvatarActionStateDetail {
+  action: AgentRobotAvatarCanonicalAction;
+  phase: AgentRobotAvatarActionPhase;
+  source: AgentRobotAvatarActionSource;
+}
+
 export interface AgentRobotAvatarEventMap extends HTMLElementEventMap {
   'face-state': CustomEvent<{ state: AgentRobotAvatarState }>;
+  'action-state': CustomEvent<AgentRobotAvatarActionStateDetail>;
   'head-roundness-change': CustomEvent<{ value: number; version: string }>;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-robot-avatar",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "A lightweight expressive robot avatar Web Component for AI agents and interactive applications.",
   "type": "module",
   "main": "./agent-robot-avatar.js",

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

@@ -1,7 +1,7 @@
 import AgentRobotAvatar, { registerAvatarExtension } from './agent-robot-avatar-extension-host.js';
+import { DEFAULT_HEAD_HEIGHT_SCALE, flattenHeadPoints } from './agent-robot-avatar-geometry.js';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
-const HEAD_HEIGHT_SCALE = 0.9;
 const ANTENNA_DEFAULTS = Object.freeze({
   x: 120,
   y: 12,
@@ -35,40 +35,10 @@ function antennaHome() {
   };
 }
 
-function smooth01(t) {
-  t = Math.max(0, Math.min(1, t));
-  return t * t * (3 - 2 * t);
-}
-
 function flattenHead(instance) {
   if (instance._headFlattenedR32 || !instance._headShape || !instance._baseHeadPoints?.length) return;
 
-  const source = instance._baseHeadPoints.map(point => ({ x: point.x, y: point.y }));
-  const minY = Math.min(...source.map(point => point.y));
-  const maxY = Math.max(...source.map(point => point.y));
-  const height = maxY - minY;
-  const centerY = (minY + maxY) / 2;
-  const inset = height * (1 - HEAD_HEIGHT_SCALE) / 2;
-
-  const upperLockY = minY + height * 0.40;
-  const lowerLockY = maxY - height * 0.40;
-
-  const flattened = source.map(point => {
-    let shiftY = 0;
-    if (point.y <= upperLockY) {
-      shiftY = inset;
-    } else if (point.y < centerY) {
-      const t = (centerY - point.y) / Math.max(0.001, centerY - upperLockY);
-      shiftY = inset * smooth01(t);
-    } else if (point.y >= lowerLockY) {
-      shiftY = -inset;
-    } else if (point.y > centerY) {
-      const t = (point.y - centerY) / Math.max(0.001, lowerLockY - centerY);
-      shiftY = -inset * smooth01(t);
-    }
-    return { x: point.x, y: point.y + shiftY };
-  });
-
+  const flattened = flattenHeadPoints(instance._baseHeadPoints, DEFAULT_HEAD_HEIGHT_SCALE);
   const path = typeof instance._pointsToPath === 'function'
     ? instance._pointsToPath(flattened)
     : `M ${flattened.map((point, index) => `${index ? 'L ' : ''}${point.x.toFixed(2)} ${point.y.toFixed(2)}`).join(' ')} Z`;
@@ -135,24 +105,33 @@ function updateAntenna(instance, now) {
   const dot = instance._antennaDot;
   const target = antennaTarget(instance);
 
-  if (!spring.initialized) {
+  if (instance._isReducedMotion?.()) {
     spring.x = target.x;
     spring.y = target.y;
+    spring.vx = 0;
+    spring.vy = 0;
     spring.last = now;
     spring.initialized = true;
-  }
+  } else {
+    if (!spring.initialized) {
+      spring.x = target.x;
+      spring.y = target.y;
+      spring.last = now;
+      spring.initialized = true;
+    }
+
+    const dt = Math.max(0.001, Math.min(0.05, (now - spring.last) / 1000 || 0.033));
+    spring.last = now;
 
-  const dt = Math.max(0.001, Math.min(0.05, (now - spring.last) / 1000 || 0.033));
-  spring.last = now;
-
-  const stiffness = configNumber('stiffness', ANTENNA_DEFAULTS.stiffness, 5, 300);
-  const damping = configNumber('damping', ANTENNA_DEFAULTS.damping, 0.5, 40);
-  const ax = (target.x - spring.x) * stiffness - spring.vx * damping;
-  const ay = (target.y - spring.y) * stiffness - spring.vy * damping;
-  spring.vx += ax * dt;
-  spring.vy += ay * dt;
-  spring.x += spring.vx * dt;
-  spring.y += spring.vy * dt;
+    const stiffness = configNumber('stiffness', ANTENNA_DEFAULTS.stiffness, 5, 300);
+    const damping = configNumber('damping', ANTENNA_DEFAULTS.damping, 0.5, 40);
+    const ax = (target.x - spring.x) * stiffness - spring.vx * damping;
+    const ay = (target.y - spring.y) * stiffness - spring.vy * damping;
+    spring.vx += ax * dt;
+    spring.vy += ay * dt;
+    spring.x += spring.vx * dt;
+    spring.y += spring.vy * dt;
+  }
 
   dot.setAttribute('cx', spring.x.toFixed(2));
   dot.setAttribute('cy', spring.y.toFixed(2));

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

@@ -73,8 +73,14 @@ const AgentRobotAvatar = (() => {
       if (face._dragJelly.active) face._onDragMove(event);
     });
   };
-  const handleGlobalPointerDown = () => forEachConnectedFace(face => face.noteActivity());
-  const handleGlobalKeyDown = () => forEachConnectedFace(face => face.noteActivity());
+  const handleGlobalPointerDown = event => forEachConnectedFace(face => {
+    if (typeof face._noteEnvironmentActivity === 'function') face._noteEnvironmentActivity(event);
+    else face.noteActivity();
+  });
+  const handleGlobalKeyDown = event => forEachConnectedFace(face => {
+    if (typeof face._noteEnvironmentActivity === 'function') face._noteEnvironmentActivity(event);
+    else face.noteActivity();
+  });
   const handleGlobalPointerEnd = event => {
     forEachConnectedFace(face => {
       if (face._dragJelly.active) face._onDragEnd(event);
@@ -175,26 +181,34 @@ const AgentRobotAvatar = (() => {
     }
 
     disconnectedCallback() {
-      unregisterConnectedFace(this);
-      this.removeEventListener('pointerdown', this._boundDragStart);
-      this.removeEventListener('click', this._boundClickCapture, true);
-      // Removal cancels work; reattachment starts idle with appearance settings intact.
-      this._resetToIdle(false);
-      this._blinkAnim = null;
-      this._blink = 1;
-      this._pointer.active = false;
-      this._pointer.influence = 0;
-      const drag = this._dragJelly;
-      if (drag.pointerId != null) {
-        try { this.releasePointerCapture(drag.pointerId); } catch (_) {}
+      // This callback is captured when the custom element is defined, so the
+      // runtime teardown must be entered from the registered core lifecycle.
+      this._runtimeDisconnecting = true;
+      try {
+        unregisterConnectedFace(this);
+        this.removeEventListener('pointerdown', this._boundDragStart);
+        this.removeEventListener('click', this._boundClickCapture, true);
+        // Removal cancels work; reattachment starts idle with appearance settings intact.
+        this._resetToIdle(false);
+        this._blinkAnim = null;
+        this._blink = 1;
+        this._pointer.active = false;
+        this._pointer.influence = 0;
+        const drag = this._dragJelly;
+        if (drag.pointerId != null) {
+          try { this.releasePointerCapture(drag.pointerId); } catch (_) {}
+        }
+        drag.active = false;
+        drag.pointerId = null;
+        this._finishDragReturn(null);
+        this._suppressClick = false;
+        this._running = false;
+        cancelAnimationFrame(this._raf);
+        this._raf = 0;
+      } finally {
+        this._teardownRuntime?.();
+        this._runtimeDisconnecting = false;
       }
-      drag.active = false;
-      drag.pointerId = null;
-      this._finishDragReturn(null);
-      this._suppressClick = false;
-      this._running = false;
-      cancelAnimationFrame(this._raf);
-      this._raf = 0;
     }
 
     static get observedAttributes() { return ['color','size','auto-sleep']; }
@@ -202,7 +216,10 @@ const AgentRobotAvatar = (() => {
       if (oldV === newV) return;
       if (name === 'color') this._applyColor(newV);
       if (name === 'size') this.style.setProperty('--face-size', `${Number(newV)||112}px`);
-      if (name === 'auto-sleep') this._autoSleepMs = Number(newV) || 0;
+      if (name === 'auto-sleep') {
+        this._autoSleepMs = Number(newV) || 0;
+        this._scheduleAutoSleep?.();
+      }
     }
 
     _applyColor(value) {
@@ -1096,7 +1113,6 @@ const AgentRobotAvatar = (() => {
         this._updateLook(ts, dt);
         this._updateHeadFollow(ts, dt);
         this._updateDragJelly(dt);
-        this._autoSleep(ts);
         this._draw(ts);
       }
       if (this._canPauseFrames(ts)) {

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

@@ -0,0 +1,40 @@
+const DEFAULT_HEAD_HEIGHT_SCALE = 0.9;
+
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+const smooth01 = value => {
+  const t = clamp(value, 0, 1);
+  return t * t * (3 - 2 * t);
+};
+
+function flattenHeadPoints(points, heightScale = DEFAULT_HEAD_HEIGHT_SCALE) {
+  if (!points?.length) return [];
+  const source = points.map(point => ({ x: point.x, y: point.y }));
+  const minY = Math.min(...source.map(point => point.y));
+  const maxY = Math.max(...source.map(point => point.y));
+  const height = maxY - minY;
+  if (!(height > 0)) return source;
+
+  const scale = clamp(Number(heightScale), 0.1, 1);
+  const centerY = (minY + maxY) / 2;
+  const inset = height * (1 - scale) / 2;
+  const upperLockY = minY + height * 0.40;
+  const lowerLockY = maxY - height * 0.40;
+
+  return source.map(point => {
+    let shiftY = 0;
+    if (point.y <= upperLockY) {
+      shiftY = inset;
+    } else if (point.y < centerY) {
+      const t = (centerY - point.y) / Math.max(0.001, centerY - upperLockY);
+      shiftY = inset * smooth01(t);
+    } else if (point.y >= lowerLockY) {
+      shiftY = -inset;
+    } else if (point.y > centerY) {
+      const t = (point.y - centerY) / Math.max(0.001, lowerLockY - centerY);
+      shiftY = -inset * smooth01(t);
+    }
+    return { x: point.x, y: point.y + shiftY };
+  });
+}
+
+export { DEFAULT_HEAD_HEIGHT_SCALE, flattenHeadPoints };

package/src/agent-robot-avatar-head-roundness.js

@@ -1,47 +1,14 @@
 import AgentRobotAvatar from './agent-robot-avatar-extension-host.js';
+import { flattenHeadPoints } from './agent-robot-avatar-geometry.js';
 import { VERSION } from './agent-robot-avatar-version.js';
 
 const proto = AgentRobotAvatar.prototype;
-const HEAD_HEIGHT_SCALE = 0.9;
 const DEFAULT_ROUNDNESS = 50;
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
 
-function smooth01(t) {
-  t = clamp(t, 0, 1);
-  return t * t * (3 - 2 * t);
-}
-
-function flattenPoints(points) {
-  if (!points?.length) return [];
-  const source = points.map(point => ({ x: point.x, y: point.y }));
-  const minY = Math.min(...source.map(point => point.y));
-  const maxY = Math.max(...source.map(point => point.y));
-  const height = maxY - minY;
-  const centerY = (minY + maxY) / 2;
-  const inset = height * (1 - HEAD_HEIGHT_SCALE) / 2;
-  const upperLockY = minY + height * 0.40;
-  const lowerLockY = maxY - height * 0.40;
-
-  return source.map(point => {
-    let shiftY = 0;
-    if (point.y <= upperLockY) {
-      shiftY = inset;
-    } else if (point.y < centerY) {
-      const t = (centerY - point.y) / Math.max(0.001, centerY - upperLockY);
-      shiftY = inset * smooth01(t);
-    } else if (point.y >= lowerLockY) {
-      shiftY = -inset;
-    } else if (point.y > centerY) {
-      const t = (point.y - centerY) / Math.max(0.001, lowerLockY - centerY);
-      shiftY = -inset * smooth01(t);
-    }
-    return { x: point.x, y: point.y + shiftY };
-  });
-}
-
 function ensureDefaultGeometry(instance) {
   if (!instance?._headShape || !instance._baseHeadPoints?.length) return false;
   if (instance._headRoundnessDefaultPoints?.length) return true;
@@ -49,7 +16,7 @@ function ensureDefaultGeometry(instance) {
   let points = instance._baseHeadPoints.map(point => ({ x: point.x, y: point.y }));
 
   if (!instance._headFlattenedR32) {
-    points = flattenPoints(points);
+    points = flattenHeadPoints(points);
     instance._headFlattenedR32 = true;
     instance._baseHeadPoints = points.map(point => ({ ...point }));
     instance._baseHeadPathD = instance._pointsToPath(points);

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

@@ -31,46 +31,54 @@ const INSPECT_DEFAULTS = Object.freeze({
   open: 260,
 });
 
+const INSPECT_BOUNDS = Object.freeze({
+  aperture: [6, 40],
+  scanOffset: [0, 24],
+  prepPause: [0, 2400],
+  close: [40, 2400],
+  holdClosed: [0, 2400],
+  down1: [40, 2400],
+  holdDown1: [0, 2400],
+  up1: [40, 2400],
+  holdUp1: [0, 2400],
+  center1: [40, 2400],
+  holdCenter: [0, 2400],
+  down2: [40, 2400],
+  holdDown2: [0, 2400],
+  up2: [40, 2400],
+  holdUp2: [0, 2400],
+  center2: [40, 2400],
+  holdAfter: [0, 2400],
+  open: [40, 2400],
+});
+
 const runtimeWindow = typeof window !== 'undefined' ? window : null;
 const inspectConfig = (runtimeWindow?.AgentRobotAvatarInspectConfig && typeof runtimeWindow.AgentRobotAvatarInspectConfig === 'object')
   ? runtimeWindow.AgentRobotAvatarInspectConfig
   : {};
-for (const [key, value] of Object.entries(INSPECT_DEFAULTS)) {
-  inspectConfig[key] = value;
+
+function normalizeConfigValue(key, value) {
+  const fallback = INSPECT_DEFAULTS[key];
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  const [min, max] = INSPECT_BOUNDS[key];
+  return Math.max(min, Math.min(max, numeric));
+}
+
+for (const key of Object.keys(INSPECT_DEFAULTS)) {
+  inspectConfig[key] = normalizeConfigValue(key, inspectConfig[key]);
 }
 if (runtimeWindow) {
   runtimeWindow.AgentRobotAvatarInspectConfig = inspectConfig;
   runtimeWindow.AgentRobotAvatarInspectDefaults = INSPECT_DEFAULTS;
 }
 
-function configNumber(key, fallback, min, max) {
-  const value = Number(inspectConfig[key]);
-  if (!Number.isFinite(value)) return fallback;
-  return Math.max(min, Math.min(max, value));
-}
-
 function currentInspectConfig() {
-  const duration = key => configNumber(key, INSPECT_DEFAULTS[key], 0, 2400);
-  return {
-    aperture: configNumber('aperture', INSPECT_DEFAULTS.aperture, 6, 40),
-    scanOffset: configNumber('scanOffset', INSPECT_DEFAULTS.scanOffset, 0, 24),
-    prepPause: duration('prepPause'),
-    close: Math.max(40, duration('close')),
-    holdClosed: duration('holdClosed'),
-    down1: Math.max(40, duration('down1')),
-    holdDown1: duration('holdDown1'),
-    up1: Math.max(40, duration('up1')),
-    holdUp1: duration('holdUp1'),
-    center1: Math.max(40, duration('center1')),
-    holdCenter: duration('holdCenter'),
-    down2: Math.max(40, duration('down2')),
-    holdDown2: duration('holdDown2'),
-    up2: Math.max(40, duration('up2')),
-    holdUp2: duration('holdUp2'),
-    center2: Math.max(40, duration('center2')),
-    holdAfter: duration('holdAfter'),
-    open: Math.max(40, duration('open')),
-  };
+  const config = {};
+  for (const key of Object.keys(INSPECT_DEFAULTS)) {
+    config[key] = normalizeConfigValue(key, inspectConfig[key]);
+  }
+  return config;
 }
 
 function dispatchInspectState(instance, state) {