agent-robot-avatar 0.2.1 → 0.3.0

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.0",
   "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-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) {

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

@@ -0,0 +1,178 @@
+import AgentRobotAvatar from './agent-robot-avatar-extension-host.js';
+
+const proto = AgentRobotAvatar.prototype;
+const baseUpdateDragJelly = proto._updateDragJelly;
+const baseResumeFrames = proto._resumeFrames;
+const baseCanPauseFrames = proto._canPauseFrames;
+const baseDraw = proto._draw;
+const baseIsReducedMotion = proto._isReducedMotion;
+
+let currentEnvironmentEvent = null;
+let clearEnvironmentTimer = 0;
+
+function rememberEnvironmentEvent(event) {
+  currentEnvironmentEvent = event;
+  if (clearEnvironmentTimer) clearTimeout(clearEnvironmentTimer);
+  clearEnvironmentTimer = setTimeout(() => {
+    currentEnvironmentEvent = null;
+    clearEnvironmentTimer = 0;
+  }, 0);
+}
+
+if (typeof document !== 'undefined') {
+  document.addEventListener('pointerdown', rememberEnvironmentEvent, true);
+  document.addEventListener('keydown', rememberEnvironmentEvent, true);
+}
+
+function wakePolicy(instance) {
+  const value = String(instance.getAttribute('wake-on') || 'activity').trim().toLowerCase();
+  return value === 'manual' || value === 'interaction' ? value : 'activity';
+}
+
+function eventTargetsAvatar(event, instance) {
+  const path = event?.composedPath?.();
+  if (Array.isArray(path)) return path.includes(instance);
+  return event?.target === instance || instance.contains?.(event?.target);
+}
+
+// Keep the public noteActivity(wake?) contract, but distinguish calls made by
+// the shared environment listeners from explicit API calls. Environment input
+// follows wake-on; an explicit noteActivity() remains an intentional wake.
+proto.noteActivity = function(wake = true) {
+  this._lastActivity = performance.now();
+  this._resumeFrames?.();
+  if (!wake || (!this._sleeping && this._state !== 'sleep')) return;
+
+  const event = currentEnvironmentEvent;
+  if (!event) {
+    this.wake();
+    return;
+  }
+
+  const policy = wakePolicy(this);
+  const shouldWake = policy === 'activity' || (policy === 'interaction' && eventTargetsAvatar(event, this));
+  if (!shouldWake) return;
+
+  const previousSource = this._runtimeActionSource;
+  this._runtimeActionSource = 'automatic';
+  try {
+    this.wake();
+  } finally {
+    this._runtimeActionSource = previousSource;
+  }
+};
+
+function dragAtRest(drag) {
+  if (!drag || drag.active || drag.returning || drag.pendingReaction) return false;
+  return Math.abs(drag.x) < 0.0001 && Math.abs(drag.y) < 0.0001 &&
+    Math.abs(drag.vx) < 0.0001 && Math.abs(drag.vy) < 0.0001 &&
+    Math.abs(drag.stretch) < 0.0001 && Math.abs(drag.shear) < 0.0001 &&
+    Math.abs(drag.pullX) < 0.0001 && Math.abs(drag.pullY) < 0.0001;
+}
+
+// Core's original jelly renderer writes an identity transform every frame even
+// after reset. Clear that identity transform once the interaction is fully at
+// rest so reset/disconnect leave no visual residue or unnecessary style churn.
+proto._updateDragJelly = function(dt) {
+  const result = baseUpdateDragJelly.call(this, dt);
+  if (dragAtRest(this._dragJelly)) {
+    if (this._dragMotion) {
+      this._dragMotion.style.transform = '';
+      this._dragMotion.style.transformOrigin = '';
+    }
+    if (this._headShape && this._baseHeadPathD) {
+      this._headShape.setAttribute('d', this._baseHeadPathD);
+    }
+  }
+  return result;
+};
+
+function cancelContinuousMotion(instance) {
+  const animations = instance._headMotion?.getAnimations?.() || [];
+  for (const animation of animations) animation.cancel();
+  if (instance._headMotion) instance._headMotion.style.transform = '';
+  instance._blinkAnim = null;
+  instance._blink = 1;
+  instance._boredRoutine = null;
+  instance._boredLookSpeed = null;
+  if (instance._wanderTarget) instance._wanderTarget.x = instance._wanderTarget.y = 0;
+  if (instance._look) instance._look.x = instance._look.y = 0;
+}
+
+function requestedMotion(instance) {
+  const value = String(instance.getAttribute('motion') || 'auto').trim().toLowerCase();
+  return value === 'reduce' || value === 'full' ? value : 'auto';
+}
+
+function effectiveReducedMotion(instance) {
+  const requested = requestedMotion(instance);
+  if (requested === 'reduce') return true;
+  if (requested === 'full') return false;
+
+  // A fresh MediaQueryList avoids engine-specific delays where an older
+  // MediaQueryList object's matches value lags behind a runtime preference
+  // update. Fall back to the coordinator's original resolver when unavailable.
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  }
+  return baseIsReducedMotion.call(instance);
+}
+
+function syncMotionPreference(instance) {
+  const reduced = effectiveReducedMotion(instance);
+  if (instance._runtimeLastReducedMotion === reduced) return reduced;
+  instance._runtimeLastReducedMotion = reduced;
+  instance._runtimeVisualDirty = true;
+  if (reduced) cancelContinuousMotion(instance);
+  return reduced;
+}
+
+// Some engines deliver matchMedia change events later than the next animation
+// frame. Also sample the effective preference while frames are active so a
+// runtime switch cannot leave an old Web Animation running until that event.
+proto._isReducedMotion = function() {
+  return syncMotionPreference(this);
+};
+
+// Reduced motion should render each newly reached static state once, then stop
+// scheduling frames. Extension effects historically create some Web Animations
+// directly instead of routing through _animateHead; cancel those in a microtask
+// after an effect becomes active so ordinary-mode animation code stays intact.
+for (const property of ['_waitingFx', '_inspectFx', '_failureFx', '_warningFx', '_systemErrorShake']) {
+  const slot = Symbol(property);
+  Object.defineProperty(proto, property, {
+    configurable: true,
+    get() { return this[slot]; },
+    set(value) {
+      this[slot] = value;
+      this._runtimeVisualDirty = true;
+      if (this.isConnected && this._isReducedMotion?.()) {
+        this._resumeFrames?.();
+        queueMicrotask(() => {
+          if (this.isConnected && this._isReducedMotion?.()) cancelContinuousMotion(this);
+        });
+      }
+    },
+  });
+}
+
+proto._resumeFrames = function() {
+  if (this._isReducedMotion?.()) this._runtimeVisualDirty = true;
+  return baseResumeFrames.call(this);
+};
+
+proto._draw = function(now) {
+  syncMotionPreference(this);
+  const result = baseDraw.call(this, now);
+  this._runtimeVisualDirty = false;
+  return result;
+};
+
+proto._canPauseFrames = function(now) {
+  syncMotionPreference(this);
+  if (this._isReducedMotion?.() && this._runtimeVisualDirty) return false;
+  return baseCanPauseFrames.call(this, now);
+};
+
+export { AgentRobotAvatar };
+export default AgentRobotAvatar;