agent-robot-avatar 0.2.0

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

@@ -0,0 +1,394 @@
+import AgentRobotAvatar, { registerAvatarExtension } from './agent-robot-avatar-extension-host.js';
+
+if (!AgentRobotAvatar) {
+  throw new Error('Agent Robot Avatar core failed to load.');
+}
+
+const proto = AgentRobotAvatar.prototype;
+const baseUpdateLook = proto._updateLook;
+const baseOnPointerMove = proto._onPointerMove;
+
+const clamp01 = value => Math.max(0, Math.min(1, value));
+const lerp = (a, b, t) => a + (b - a) * t;
+const outQuint = t => 1 - Math.pow(1 - t, 5);
+const smooth = t => {
+  t = clamp01(t);
+  return t * t * (3 - 2 * t);
+};
+
+const WARNING_TIMING = Object.freeze({
+  W1: 480,
+  W2: 400,
+  W4: 600,
+  W5: 200,
+  W5P: 300,
+  W6: 200,
+  W6P: 300,
+  W7: 100,
+  W8: 800,
+  W9: 227,
+});
+
+function buildWarningPhases() {
+  let cursor = 0;
+  const phases = {};
+  for (const key of ['W2', 'W4', 'W5', 'W5P', 'W6', 'W6P', 'W7', 'W8', 'W9']) {
+    phases[`${key.toLowerCase()}Start`] = cursor;
+    cursor += WARNING_TIMING[key];
+    phases[`${key.toLowerCase()}End`] = cursor;
+  }
+  phases.duration = cursor;
+  return Object.freeze(phases);
+}
+
+const WARNING_PHASES = buildWarningPhases();
+
+function segment(t, a, b, from, to) {
+  if (t <= a) return from;
+  if (t >= b) return to;
+  return lerp(from, to, smooth((t - a) / (b - a)));
+}
+
+function errorEyeSweep(t) {
+  if (t < 0.16) return segment(t, 0, 0.16, 0, -1);
+  if (t < 0.40) return segment(t, 0.16, 0.40, -1, 1);
+  if (t < 0.64) return segment(t, 0.40, 0.64, 1, -0.88);
+  if (t < 0.84) return segment(t, 0.64, 0.84, -0.88, 0.58);
+  return segment(t, 0.84, 1, 0.58, 0);
+}
+
+function dispatchActionState(instance, state) {
+  instance.dispatchEvent(new CustomEvent('face-state', { detail: { state } }));
+}
+
+function centerHeadTransform(instance) {
+  if (!instance._headMotion) return;
+  instance._headMotion.style.transformBox = 'view-box';
+  instance._headMotion.style.transformOrigin = '120px 120px';
+}
+
+function cancelCustomMotion(instance) {
+  instance._systemErrorShake = null;
+  instance._warningFx = null;
+  instance._look.x = 0;
+  instance._look.y = 0;
+}
+
+function interruptRunningAction(instance) {
+  ++instance._transitionToken;
+  instance._inputWanted = false;
+  instance._boredRoutine = null;
+  instance._boredLookSpeed = null;
+  instance._eyeNod = null;
+  instance._eyeBob = null;
+  instance._angryEyeDrop = null;
+  instance._surpriseShake = null;
+  cancelCustomMotion(instance);
+  if (instance._headMotion?.getAnimations) {
+    instance._headMotion.getAnimations().forEach(animation => animation.cancel());
+  }
+  if (instance._headMotion) instance._headMotion.style.transform = '';
+}
+
+function playBuiltInAction(action) {
+  if (action === 'idle') return this.reset();
+  if (action === 'input' && (this._inputWanted || this._state === 'input')) return this;
+  if (action === 'wake' && !this._sleeping && this._state !== 'sleep') return this;
+  if (action === 'sleep' && this._sleeping) return this;
+
+  interruptRunningAction(this);
+
+  if (action === 'warning') return this.warning();
+  if (action === 'system-error' || action === 'connection-error') return this.error();
+  if (action === 'blocked' || action === 'policy-blocked') return this.angry();
+  return this[action]();
+}
+
+const BUILT_IN_ACTIONS = [
+  'idle',
+  'bored',
+  'input',
+  'send',
+  'success',
+  'warning',
+  'error',
+  'system-error',
+  'connection-error',
+  'angry',
+  'blocked',
+  'policy-blocked',
+  'surprise',
+  'sleep',
+  'wake',
+];
+
+const actionHandlers = Object.fromEntries(BUILT_IN_ACTIONS.map(action => [
+  action,
+  function() { return playBuiltInAction.call(this, action); },
+]));
+
+proto.setPointerFollow = function(enabled = true) {
+  this._pointerFollowEnabled = enabled !== false;
+  if (!this._pointerFollowEnabled) {
+    this._pointer.active = false;
+    this._pointer.influence = 0;
+    this._pointer.lastMove = 0;
+    this._headCenteringUntil = performance.now() + 320;
+  }
+  return this;
+};
+
+proto._onPointerMove = function(event) {
+  if (this._pointerFollowEnabled === false) return;
+  return baseOnPointerMove.call(this, event);
+};
+
+proto._returnToIdle = async function(duration = 320, ease = outQuint) {
+  const token = this._transitionToken;
+  this.setState('idle', { duration, ease, keepGazeLock: true });
+  this._headCenteringUntil = Math.max(this._headCenteringUntil || 0, performance.now() + duration);
+  await this._wait(duration);
+  if (token === this._transitionToken && this._state === 'idle') this._releaseExpressionLock();
+};
+
+proto.send = async function() {
+  this.noteActivity();
+  this._inputWanted = false;
+  if (!(await this._prepareExpression({ normalizePose: true, duration: 180, pause: 320 }))) return;
+  const token = this._transitionToken;
+  this._eyeNod = { start: performance.now(), duration: 760 };
+  this._animateHead([
+    { transform: 'translateY(0px)' },
+    { transform: 'translateY(5px)', offset: .52 },
+    { transform: 'translateY(0px)' }
+  ], 920);
+  await this._wait(860);
+  if (token !== this._transitionToken) return;
+  this._eyeNod = null;
+  this._releaseExpressionLock();
+};
+
+proto.wake = async function() {
+  if (!this._sleeping && this._state !== 'sleep') return;
+  this._resumeFrames?.();
+  const token = ++this._transitionToken;
+  this._expressionLock = true;
+  this._sleeping = false;
+  this._animateHead([
+    { transform: 'translateY(4px) scale(1)' },
+    { transform: 'translateY(-2px) scale(1.015)', offset: .55 },
+    { transform: 'translateY(0) scale(1)' }
+  ], 500);
+  this.setState('sleepy', { duration: 240, keepGazeLock: true });
+  await this._wait(260);
+  if (token !== this._transitionToken) return;
+  this.setState('surprise', { duration: 120, keepGazeLock: true });
+  await this._wait(190);
+  if (token !== this._transitionToken) return;
+  await this._returnToIdle(300);
+  if (token !== this._transitionToken) return;
+  this._lastActivity = performance.now();
+};
+
+proto.error = async function() {
+  this.noteActivity();
+  this._inputWanted = false;
+  cancelCustomMotion(this);
+  if (!(await this._prepareExpression({ normalizePose: true, duration: 180, pause: 240 }))) return;
+
+  const token = this._transitionToken;
+  const eyeDuration = 980;
+  const headDuration = 1380;
+  this._systemErrorShake = { start: performance.now(), duration: eyeDuration };
+  dispatchActionState(this, 'error');
+
+  centerHeadTransform(this);
+  if (this._headMotion?.animate) {
+    const anim = this._headMotion.animate([
+      { transform: 'translateX(0px)', offset: 0, easing: 'cubic-bezier(.38,0,.28,1)' },
+      { transform: 'translateX(-4px)', offset: 0.34, easing: 'cubic-bezier(.35,0,.22,1)' },
+      { transform: 'translateX(4px)', offset: 0.72, easing: 'cubic-bezier(.35,0,.22,1)' },
+      { transform: 'translateX(0px)', offset: 1 }
+    ], { duration: headDuration, easing: 'linear', fill: 'forwards' });
+    anim.onfinish = () => { this._headMotion.style.transform = 'translateX(0px)'; };
+  }
+
+  await this._wait(headDuration + 40);
+  if (token !== this._transitionToken) return;
+  this._systemErrorShake = null;
+  this._look.x = 0;
+  this._look.y = 0;
+  this._releaseExpressionLock();
+  dispatchActionState(this, 'idle');
+};
+
+proto.warning = async function() {
+  this.noteActivity();
+  this._inputWanted = false;
+  cancelCustomMotion(this);
+  if (!(await this._prepareExpression({ normalizePose: true, duration: 200, pause: WARNING_TIMING.W1 - 200 }))) return;
+
+  const token = this._transitionToken;
+  const duration = WARNING_PHASES.duration;
+  this._warningFx = { start: performance.now(), duration };
+  dispatchActionState(this, 'warning');
+
+  centerHeadTransform(this);
+  if (this._headMotion?.animate) {
+    const anim = this._headMotion.animate([
+      { transform: 'translateY(0px)', offset: 0 },
+      { transform: 'translateY(0px)', offset: WARNING_PHASES.w5Start / duration, easing: 'cubic-bezier(.38,0,.25,1)' },
+      { transform: 'translateY(5px)', offset: WARNING_PHASES.w5End / duration, easing: 'cubic-bezier(.35,0,.22,1)' },
+      { transform: 'translateY(5px)', offset: WARNING_PHASES.w5pEnd / duration, easing: 'cubic-bezier(.35,0,.22,1)' },
+      { transform: 'translateY(-4px)', offset: WARNING_PHASES.w6End / duration },
+      { transform: 'translateY(-4px)', offset: WARNING_PHASES.w6pEnd / duration, easing: 'cubic-bezier(.35,0,.22,1)' },
+      { transform: 'translateY(0px)', offset: WARNING_PHASES.w7End / duration },
+      { transform: 'translateY(0px)', offset: 1 }
+    ], { duration, easing: 'linear', fill: 'forwards' });
+    anim.onfinish = () => { this._headMotion.style.transform = 'translateY(0px)'; };
+  }
+
+  await this._wait(duration + 40);
+  if (token !== this._transitionToken) return;
+  this._warningFx = null;
+  this._look.x = 0;
+  this._look.y = 0;
+  this._releaseExpressionLock();
+  dispatchActionState(this, 'idle');
+};
+
+proto._startBoredRoutine = function(now) {
+  this._boredRoutine = {
+    index: 0,
+    nextAt: now,
+    steps: [
+      { x: -18, y: -16, hold: 1400, lookSpeed: 0.5 },
+      { x: 18, y: -16, hold: 1400, lookSpeed: 0.5 },
+      { x: 0, y: 0, hold: 320, lookSpeed: 0.5 },
+    ]
+  };
+};
+
+proto._updateLook = function(now, dt) {
+  baseUpdateLook.call(this, now, dt);
+
+  if (this._systemErrorShake) {
+    const t = clamp01((now - this._systemErrorShake.start) / this._systemErrorShake.duration);
+    this._look.x = errorEyeSweep(t) * 30;
+    this._look.y = 0;
+    if (t >= 1) this._systemErrorShake = null;
+  }
+};
+
+function drawWarning(now) {
+  const fx = this._warningFx;
+  if (!fx) return;
+
+  const elapsed = Math.max(0, Math.min(fx.duration, now - fx.start));
+
+  let proximity = elapsed < WARNING_PHASES.w2End
+    ? smooth(elapsed / WARNING_TIMING.W2)
+    : 1;
+
+  let lids = elapsed < WARNING_PHASES.w2End
+    ? smooth(elapsed / WARNING_TIMING.W2)
+    : 1;
+
+  const release = elapsed > WARNING_PHASES.w8End
+    ? 1 - smooth((elapsed - WARNING_PHASES.w8End) / WARNING_TIMING.W9)
+    : 1;
+  proximity *= release;
+  lids *= release;
+
+  let lidShift = 0;
+  const lightPress = 4.2;
+  const w4PressEnd = Math.min(WARNING_PHASES.w4Start + 120, WARNING_PHASES.w4End);
+  if (elapsed >= WARNING_PHASES.w4Start && elapsed < WARNING_PHASES.w4End) {
+    lidShift = elapsed < w4PressEnd
+      ? segment(elapsed, WARNING_PHASES.w4Start, w4PressEnd, 0, lightPress)
+      : lightPress;
+  } else if (elapsed >= WARNING_PHASES.w5Start && elapsed < WARNING_PHASES.w5End) {
+    lidShift = segment(elapsed, WARNING_PHASES.w5Start, WARNING_PHASES.w5End, lightPress, 20.5);
+  } else if (elapsed >= WARNING_PHASES.w5pStart && elapsed < WARNING_PHASES.w5pEnd) {
+    lidShift = 20.5;
+  } else if (elapsed >= WARNING_PHASES.w6Start && elapsed < WARNING_PHASES.w6End) {
+    lidShift = segment(elapsed, WARNING_PHASES.w6Start, WARNING_PHASES.w6End, 20.5, -6.5);
+  } else if (elapsed >= WARNING_PHASES.w6pStart && elapsed < WARNING_PHASES.w6pEnd) {
+    lidShift = -6.5;
+  } else if (elapsed >= WARNING_PHASES.w7Start && elapsed < WARNING_PHASES.w7End) {
+    lidShift = segment(elapsed, WARNING_PHASES.w7Start, WARNING_PHASES.w7End, -6.5, lightPress);
+  } else if (elapsed >= WARNING_PHASES.w8Start && elapsed < WARNING_PHASES.w8End) {
+    lidShift = lightPress;
+  }
+
+  let farLowOffset = 0;
+  if (elapsed >= WARNING_PHASES.w5Start && elapsed < WARNING_PHASES.w5End) {
+    farLowOffset = segment(elapsed, WARNING_PHASES.w5Start, WARNING_PHASES.w5End, 0, 2.4);
+  } else if (elapsed >= WARNING_PHASES.w5pStart && elapsed < WARNING_PHASES.w5pEnd) {
+    farLowOffset = 2.4;
+  } else if (elapsed >= WARNING_PHASES.w6Start && elapsed < WARNING_PHASES.w6End) {
+    farLowOffset = segment(elapsed, WARNING_PHASES.w6Start, WARNING_PHASES.w6End, 2.4, 0);
+  }
+
+  let farDeepLidDrop = 0;
+  if (elapsed >= WARNING_PHASES.w5Start && elapsed < WARNING_PHASES.w5End) {
+    farDeepLidDrop = segment(elapsed, WARNING_PHASES.w5Start, WARNING_PHASES.w5End, 0, 3.5);
+  } else if (elapsed >= WARNING_PHASES.w5pStart && elapsed < WARNING_PHASES.w5pEnd) {
+    farDeepLidDrop = 3.5;
+  } else if (elapsed >= WARNING_PHASES.w6Start && elapsed < WARNING_PHASES.w6End) {
+    farDeepLidDrop = segment(elapsed, WARNING_PHASES.w6Start, WARNING_PHASES.w6End, 3.5, 0);
+  }
+
+  const nearSX = lerp(1, 1.48, proximity);
+  const nearSY = lerp(1, 1.40, proximity);
+  const farSX = lerp(1, 0.78, proximity);
+  const farSY = lerp(1, 0.97, proximity);
+
+  const nearX = lerp(86, 102.0, proximity);
+  const farX = lerp(154, 178.5, proximity);
+  const nearY = lerp(126, 125.5, proximity);
+  const farY = lerp(126, 134.0, proximity) + farLowOffset;
+
+  this._leftEye.setAttribute(
+    'transform',
+    `translate(${nearX.toFixed(2)} ${nearY.toFixed(2)}) scale(${nearSX.toFixed(3)} ${nearSY.toFixed(3)})`
+  );
+  this._rightEye.setAttribute(
+    'transform',
+    `translate(${farX.toFixed(2)} ${farY.toFixed(2)}) scale(${farSX.toFixed(3)} ${farSY.toFixed(3)})`
+  );
+
+  const nearTopY = lerp(-36, -10.0, lids) + lidShift;
+  const farTopY = lerp(-36, -18.0, lids) + lidShift * 0.95 + farDeepLidDrop;
+  const nearTopRot = lerp(0, 10.0, lids);
+  const farTopRot = lerp(0, -7.5, lids);
+
+  this._leftTop.setAttribute('y', (nearTopY - 90).toFixed(2));
+  this._leftTop.setAttribute('height', '90');
+  this._leftTop.setAttribute('transform', `rotate(${nearTopRot.toFixed(2)} 0 ${nearTopY.toFixed(2)})`);
+
+  this._rightTop.setAttribute('y', (farTopY - 90).toFixed(2));
+  this._rightTop.setAttribute('height', '90');
+  this._rightTop.setAttribute('transform', `rotate(${farTopRot.toFixed(2)} 0 ${farTopY.toFixed(2)})`);
+
+  const nearBottomY = lerp(36, 35.3, lids);
+  const farBottomY = lerp(36, 35.6, lids);
+  this._leftBottom.setAttribute('y', nearBottomY.toFixed(2));
+  this._leftBottom.setAttribute('height', '90');
+  this._leftBottom.setAttribute('transform', `rotate(0 0 ${nearBottomY.toFixed(2)})`);
+  this._rightBottom.setAttribute('y', farBottomY.toFixed(2));
+  this._rightBottom.setAttribute('height', '90');
+  this._rightBottom.setAttribute('transform', `rotate(0 0 ${farBottomY.toFixed(2)})`);
+}
+
+registerAvatarExtension({
+  name: 'actions',
+  actions: actionHandlers,
+  reset() {
+    interruptRunningAction(this);
+  },
+  draw: drawWarning,
+});
+
+export { AgentRobotAvatar };
+export default AgentRobotAvatar;

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

@@ -0,0 +1,127 @@
+import AgentRobotAvatar, { registerAvatarExtension } from './agent-robot-avatar-extension-host.js';
+
+const proto = AgentRobotAvatar.prototype;
+
+const FLASH_DEFAULTS = Object.freeze({
+  period: 1000,
+  duty: 0.80,
+});
+
+const FLASH_MULTIPLIER = Object.freeze({
+  input: 1.20,
+  send: 1.00,
+  success: 1.10,
+  warning: 1.00,
+  angry: 0.90,
+  error: 0.80,
+  surprise: 0.80,
+});
+
+const runtimeWindow = typeof window !== 'undefined' ? window : null;
+const flashConfig = (runtimeWindow?.AgentRobotAvatarAntennaFlashConfig && typeof runtimeWindow.AgentRobotAvatarAntennaFlashConfig === 'object')
+  ? runtimeWindow.AgentRobotAvatarAntennaFlashConfig
+  : {};
+for (const [key, value] of Object.entries(FLASH_DEFAULTS)) {
+  if (!Number.isFinite(Number(flashConfig[key]))) flashConfig[key] = value;
+}
+if (runtimeWindow) {
+  runtimeWindow.AgentRobotAvatarAntennaFlashConfig = flashConfig;
+  runtimeWindow.AgentRobotAvatarAntennaFlashDefaults = FLASH_DEFAULTS;
+}
+
+function configNumber(key, fallback, min, max) {
+  const value = Number(flashConfig[key]);
+  if (!Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, value));
+}
+
+function flashPeriod(action) {
+  const base = configNumber('period', FLASH_DEFAULTS.period, 200, 4000);
+  return base * (FLASH_MULTIPLIER[action] || 1);
+}
+
+function flashDuty() {
+  return configNumber('duty', FLASH_DEFAULTS.duty, 0.05, 0.95);
+}
+
+function normalizeFlashAction(action) {
+  if (action === 'blocked' || action === 'policy-blocked') return 'angry';
+  if (action === 'system-error' || action === 'connection-error') return 'error';
+  return action;
+}
+
+function beginAntennaFlash(instance, action) {
+  const normalized = normalizeFlashAction(action);
+  if (!FLASH_MULTIPLIER[normalized]) {
+    instance._antennaFlashAction = null;
+    return null;
+  }
+  const token = (instance._antennaFlashToken || 0) + 1;
+  instance._antennaFlashToken = token;
+  instance._antennaFlashAction = normalized;
+  instance._antennaFlashStart = performance.now();
+  return token;
+}
+
+function clearAntennaFlash(instance, token = null) {
+  if (token != null && token !== instance._antennaFlashToken) return;
+  instance._antennaFlashAction = null;
+  const dot = instance._antennaDot;
+  if (dot) dot.style.opacity = '1';
+}
+
+proto.setAntennaFlash = function(enabled = true) {
+  this._antennaFlashEnabled = enabled !== false;
+  if (!this._antennaFlashEnabled) clearAntennaFlash(this);
+  return this;
+};
+
+function drawAntennaFlash(now) {
+  const dot = this._antennaDot;
+  if (!dot) return;
+
+  if (this._antennaFlashAction === 'input' && !this._inputWanted && this._state !== 'input') {
+    clearAntennaFlash(this);
+  }
+
+  const action = this._antennaFlashAction;
+  const enabled = this._antennaFlashEnabled === true;
+  if (!enabled || !action || !FLASH_MULTIPLIER[action]) {
+    dot.style.opacity = '1';
+    return;
+  }
+
+  const period = flashPeriod(action);
+  const phase = ((now - (this._antennaFlashStart || now)) % period) / period;
+  dot.style.opacity = phase < flashDuty() ? '1' : '0';
+}
+
+registerAvatarExtension({
+  name: 'antenna-flash',
+  beforePlay(name, context) {
+    const action = normalizeFlashAction(name);
+    context.antennaFlashAction = action;
+    context.antennaFlashToken = FLASH_MULTIPLIER[action]
+      ? beginAntennaFlash(this, action)
+      : null;
+    if (!context.antennaFlashToken) clearAntennaFlash(this);
+  },
+  afterPlay(_name, result, context) {
+    const action = context.antennaFlashAction;
+    const token = context.antennaFlashToken;
+    if (context.error) {
+      clearAntennaFlash(this, token);
+      return;
+    }
+    if (token && action !== 'input' && result && typeof result.then === 'function') {
+      Promise.resolve(result).finally(() => clearAntennaFlash(this, token));
+    }
+  },
+  reset() {
+    clearAntennaFlash(this);
+  },
+  draw: drawAntennaFlash,
+});
+
+export { AgentRobotAvatar, FLASH_DEFAULTS };
+export default AgentRobotAvatar;

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

@@ -0,0 +1,173 @@
+import AgentRobotAvatar, { registerAvatarExtension } from './agent-robot-avatar-extension-host.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,
+  radius: 15,
+  stiffness: 180,
+  damping: 5.6,
+});
+
+const runtimeWindow = typeof window !== 'undefined' ? window : null;
+const antennaConfig = (runtimeWindow?.AgentRobotAvatarAntennaConfig && typeof runtimeWindow.AgentRobotAvatarAntennaConfig === 'object')
+  ? runtimeWindow.AgentRobotAvatarAntennaConfig
+  : {};
+for (const [key, value] of Object.entries(ANTENNA_DEFAULTS)) {
+  if (!Number.isFinite(Number(antennaConfig[key]))) antennaConfig[key] = value;
+}
+if (runtimeWindow) {
+  runtimeWindow.AgentRobotAvatarAntennaConfig = antennaConfig;
+  runtimeWindow.AgentRobotAvatarAntennaDefaults = ANTENNA_DEFAULTS;
+}
+
+function configNumber(key, fallback, min, max) {
+  const value = Number(antennaConfig[key]);
+  if (!Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, value));
+}
+
+function antennaHome() {
+  return {
+    x: configNumber('x', ANTENNA_DEFAULTS.x, 60, 180),
+    y: configNumber('y', ANTENNA_DEFAULTS.y, -40, 60),
+  };
+}
+
+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 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`;
+
+  instance._baseHeadPoints = flattened;
+  instance._baseHeadPathD = path;
+  instance._headShape.setAttribute('d', path);
+  instance._headFlattenedR32 = true;
+}
+
+function ensureAntenna(instance, now) {
+  flattenHead(instance);
+  if (instance._antennaDot?.isConnected && instance._antennaSpring) return true;
+
+  const svg = instance.shadowRoot?.querySelector('svg');
+  if (!svg || !instance._headMotion) return false;
+
+  const home = antennaHome();
+  let dot = instance.shadowRoot.getElementById('antennaDot');
+  if (!dot) {
+    dot = document.createElementNS(SVG_NS, 'circle');
+    dot.id = 'antennaDot';
+    dot.setAttribute('cx', String(home.x));
+    dot.setAttribute('cy', String(home.y));
+    dot.setAttribute('r', String(configNumber('radius', ANTENNA_DEFAULTS.radius, 2, 40)));
+    dot.setAttribute('fill', instance._head?.getAttribute('fill') || '#08090b');
+    dot.setAttribute('aria-hidden', 'true');
+    dot.style.pointerEvents = 'none';
+    svg.appendChild(dot);
+  }
+
+  instance._antennaDot = dot;
+  instance._antennaSpring = {
+    x: home.x,
+    y: home.y,
+    vx: 0,
+    vy: 0,
+    last: now,
+    initialized: false,
+  };
+  return true;
+}
+
+function antennaTarget(instance) {
+  const svg = instance.shadowRoot?.querySelector('svg');
+  const headMatrix = instance._headMotion?.getScreenCTM?.();
+  const svgMatrix = svg?.getScreenCTM?.();
+  const home = antennaHome();
+  if (!svg || !headMatrix || !svgMatrix || typeof DOMPoint === 'undefined') return home;
+
+  try {
+    const screenPoint = new DOMPoint(home.x, home.y).matrixTransform(headMatrix);
+    const localPoint = screenPoint.matrixTransform(svgMatrix.inverse());
+    return { x: localPoint.x, y: localPoint.y };
+  } catch (_) {
+    return home;
+  }
+}
+
+function updateAntenna(instance, now) {
+  if (!ensureAntenna(instance, now)) return;
+
+  const spring = instance._antennaSpring;
+  const dot = instance._antennaDot;
+  const target = antennaTarget(instance);
+
+  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 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));
+  dot.setAttribute('r', configNumber('radius', ANTENNA_DEFAULTS.radius, 2, 40).toFixed(2));
+  dot.setAttribute('fill', instance._head?.getAttribute('fill') || '#08090b');
+}
+
+function drawAntenna(now) {
+  updateAntenna(this, now);
+}
+
+registerAvatarExtension({
+  name: 'antenna',
+  draw: drawAntenna,
+});
+
+export { AgentRobotAvatar, ANTENNA_DEFAULTS };
+export default AgentRobotAvatar;