agent-robot-avatar 0.3.2 → 0.6.0

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

@@ -0,0 +1,226 @@
+import AgentRobotAvatar, { registerAvatarExtension } from './agent-robot-avatar-extension-host.js';
+
+const proto = AgentRobotAvatar.prototype;
+
+const clamp01 = value => Math.max(0, Math.min(1, value));
+const lerp = (a, b, t) => a + (b - a) * t;
+const smooth = t => {
+  t = clamp01(t);
+  return t * t * (3 - 2 * t);
+};
+
+// At full affection the two eyes become upright ovals that lean toward each
+// other and overlap at the bottom, so together they read as one heart with a
+// rounded base. Each oval is rotated about its own bottom point.
+//
+// rx / ry     half width / half height of each oval
+// tilt        degrees each oval leans inward at the bottom (larger = lobes further apart)
+// cross       how far the two bottoms overlap past the centre line
+// centerY     vertical centre of the finished heart (head centre is 120)
+// pulse       heartbeat swell, as a fraction of size
+// swayAngle / swayLift   head lean in degrees / lift in px while the heart is held
+const LOVE_DEFAULTS = Object.freeze({
+  rx: 28,
+  ry: 43,
+  tilt: 42,
+  cross: 13,
+  centerY: 126,
+  pulse: 0.155,
+  prep: 120,
+  morphIn: 240,
+  beat: 760,
+  beats: 3,
+  morphOut: 360,
+  swayAngle: 0,
+  swayLift: 2,
+});
+
+const LOVE_BOUNDS = Object.freeze({
+  rx: [10, 50],
+  ry: [20, 70],
+  tilt: [0, 60],
+  cross: [-10, 20],
+  centerY: [90, 150],
+  pulse: [0, 0.3],
+  prep: [0, 1200],
+  morphIn: [40, 1500],
+  beat: [200, 2000],
+  beats: [1, 60],
+  morphOut: [40, 1500],
+  swayAngle: [0, 8],
+  swayLift: [0, 8],
+});
+
+const runtimeWindow = typeof window !== 'undefined' ? window : null;
+const loveConfig = (runtimeWindow?.AgentRobotAvatarLoveConfig && typeof runtimeWindow.AgentRobotAvatarLoveConfig === 'object')
+  ? runtimeWindow.AgentRobotAvatarLoveConfig
+  : {};
+
+function normalizeConfigValue(key, value) {
+  const fallback = LOVE_DEFAULTS[key];
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  const [min, max] = LOVE_BOUNDS[key];
+  return Math.max(min, Math.min(max, numeric));
+}
+
+if (runtimeWindow) {
+  runtimeWindow.AgentRobotAvatarLoveConfig = loveConfig;
+  runtimeWindow.AgentRobotAvatarLoveDefaults = LOVE_DEFAULTS;
+  runtimeWindow.AgentRobotAvatarLoveBounds = LOVE_BOUNDS;
+}
+
+function currentLoveConfig() {
+  const config = {};
+  for (const key of Object.keys(LOVE_DEFAULTS)) config[key] = normalizeConfigValue(key, loveConfig[key]);
+  config.beats = Math.round(config.beats);
+  return config;
+}
+
+function loveDuration(config) {
+  return config.morphIn + config.beat * config.beats + config.morphOut;
+}
+
+function reducedMotion(instance) {
+  const requested = String(instance.getAttribute('motion') || 'auto').trim().toLowerCase();
+  if (requested === 'reduce') return true;
+  if (requested === 'full') return false;
+  return typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+    && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+function dispatchLoveState(instance, state) {
+  instance.dispatchEvent(new CustomEvent('face-state', { detail: { state } }));
+}
+
+function animateLoveHead(instance, config, duration, elapsed = 0) {
+  if (!instance._headMotion?.animate) return;
+  const token = instance._transitionToken;
+  const { swayAngle, swayLift } = config;
+  instance._headMotion.style.transformBox = 'view-box';
+  instance._headMotion.style.transformOrigin = '120px 120px';
+  const anim = instance._headMotion.animate([
+    { transform: 'translateY(0px) rotate(0deg)', offset: 0, easing: 'cubic-bezier(.38,0,.25,1)' },
+    { transform: `translateY(${-swayLift}px) rotate(${-swayAngle}deg)`, offset: 0.3, easing: 'cubic-bezier(.35,0,.22,1)' },
+    { transform: `translateY(${-swayLift / 2}px) rotate(${swayAngle}deg)`, offset: 0.68, easing: 'cubic-bezier(.35,0,.22,1)' },
+    { transform: 'translateY(0px) rotate(0deg)', offset: 1 },
+  ], { duration, delay: -elapsed, easing: 'linear', fill: 'forwards' });
+  anim.onfinish = () => {
+    if (token === instance._transitionToken) instance._headMotion.style.transform = 'translateY(0px)';
+  };
+}
+
+proto.love = async function() {
+  this.noteActivity();
+  this._inputWanted = false;
+  const config = currentLoveConfig();
+  this.reset();
+  if (!(await this._prepareExpression({ normalizePose: true, duration: 160, pause: config.prep }))) return;
+
+  const token = this._transitionToken;
+  this._expressionLock = true;
+  this._look.x = 0;
+  this._look.y = 0;
+
+  const duration = loveDuration(config);
+  this._loveFx = { start: performance.now(), duration, timing: config, headStarted: false };
+  dispatchLoveState(this, 'love');
+  // Motion preference is read on every frame, so switching it mid-action
+  // takes effect immediately; the head sway starts from the first full-motion frame.
+  if (!reducedMotion(this)) {
+    this._loveFx.headStarted = true;
+    animateLoveHead(this, config, duration);
+  }
+
+  await this._wait(duration + 30);
+  if (token !== this._transitionToken) return;
+
+  this._loveFx = null;
+  this._look.x = 0;
+  this._look.y = 0;
+  this._releaseExpressionLock();
+  dispatchLoveState(this, 'idle');
+};
+
+function drawLove(now) {
+  const fx = this._loveFx;
+  if (!fx) return;
+
+  // Timing is fixed when the action starts; shape and pulse follow the live
+  // config so they can be tuned while the heart is on screen.
+  const timing = fx.timing;
+  const shape = currentLoveConfig();
+  const elapsed = Math.max(0, Math.min(fx.duration, now - fx.start));
+  const holdEnd = timing.morphIn + timing.beat * timing.beats;
+
+  const reduced = reducedMotion(this);
+  if (!reduced && !fx.headStarted) {
+    fx.headStarted = true;
+    animateLoveHead(this, timing, fx.duration, elapsed);
+  }
+
+  // 0 = idle eyes, 1 = full heart. Reduced motion shows the finished heart
+  // straight away and holds it, with no in-between frames or beat.
+  let morph = 1;
+  if (reduced) morph = 1;
+  else if (elapsed < timing.morphIn) morph = smooth(elapsed / timing.morphIn);
+  else if (elapsed > holdEnd) morph = 1 - smooth((elapsed - holdEnd) / timing.morphOut);
+
+  // Heartbeat: two soft swells per beat ("lub-dub"), only while held.
+  let pulse = 0;
+  if (!reduced && elapsed >= timing.morphIn && elapsed <= holdEnd) {
+    const phase = ((elapsed - timing.morphIn) % timing.beat) / timing.beat;
+    const swell = (centre, width) => Math.max(0, 1 - Math.abs(phase - centre) / width);
+    pulse = Math.max(smooth(swell(0.12, 0.12)), 0.6 * smooth(swell(0.36, 0.12)));
+  }
+  const scale = 1 + shape.pulse * pulse;
+
+  const tiltRad = shape.tilt * Math.PI / 180;
+  const baseY = shape.centerY + (shape.ry - 3) * Math.cos(tiltRad);
+  const beat = `translate(120 ${shape.centerY}) scale(${scale.toFixed(3)}) translate(-120 -${shape.centerY})`;
+
+  const eyes = [
+    [this._leftEye, this._leftBase, this._leftTop, this._leftBottom, 86, -1],
+    [this._rightEye, this._rightBase, this._rightTop, this._rightBottom, 154, 1],
+  ];
+  for (const [eye, base, top, bottom, restX, side] of eyes) {
+    const x = lerp(restX, 120 - side * shape.cross, morph);
+    const y = lerp(126, baseY, morph);
+    const tilt = side * shape.tilt * morph;
+    eye.setAttribute('transform', `${beat} translate(${x.toFixed(2)} ${y.toFixed(2)}) rotate(${tilt.toFixed(2)})`);
+
+    base.setAttribute('cx', '0');
+    base.setAttribute('cy', lerp(0, -(shape.ry - 3), morph).toFixed(2));
+    base.setAttribute('rx', lerp(27, shape.rx, morph).toFixed(2));
+    base.setAttribute('ry', lerp(29, shape.ry, morph).toFixed(2));
+    base.setAttribute('opacity', '1');
+
+    // Lids slide out of the way so they never cut the heart.
+    const topY = lerp(-36, -150, morph);
+    const bottomY = lerp(36, 150, morph);
+    top.setAttribute('y', (topY - 90).toFixed(2));
+    top.setAttribute('height', '90');
+    top.setAttribute('transform', `rotate(0 0 ${topY.toFixed(2)})`);
+    bottom.setAttribute('y', bottomY.toFixed(2));
+    bottom.setAttribute('height', '90');
+    bottom.setAttribute('transform', `rotate(0 0 ${bottomY.toFixed(2)})`);
+  }
+}
+
+registerAvatarExtension({
+  name: 'love',
+  actions: {
+    love() { return this.love(); },
+  },
+  beforePlay(action) {
+    if (action === 'love') return;
+    this._loveFx = null;
+  },
+  reset() {
+    this._loveFx = null;
+  },
+  draw: drawLove,
+});
+
+export { AgentRobotAvatar, LOVE_DEFAULTS };
+export default AgentRobotAvatar;

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

@@ -0,0 +1,272 @@
+import AgentRobotAvatar, { registerAvatarExtension } from './agent-robot-avatar-extension-host.js';
+
+const proto = AgentRobotAvatar.prototype;
+const clamp01 = value => Math.max(0, Math.min(1, value));
+const smooth = t => {
+  t = clamp01(t);
+  return t * t * (3 - 2 * t);
+};
+
+// Each eye rolls over a drum that turns about a horizontal axis, like the reels
+// of a slot machine. There is exactly one eye per side, projected the same way
+// the wrap-waiting eyes are: position follows sin(angle) and height follows
+// cos(angle), so the eye flattens to nothing as it rolls over the top or bottom
+// edge instead of being cut off. Because only one eye ever exists on each
+// reel, eyes can never overlap.
+// The left reel slows, overshoots, bounces and settles, then the right reel
+// follows. A settled reel is exactly the ordinary eye, so control returns to
+// the regular eye with no visible jump.
+//
+// radius       drum radius; how far the eye travels above and below its resting place
+// gap          extra travel, out of sight, between leaving the bottom and re-entering at the top
+// squeeze      extra width removed from the eye as it turns edge-on (optical correction)
+// speed        surface speed, units per millisecond
+// ramp         time to reach full speed
+// spin         how long the left reel spins at full speed before it starts to slow
+// stagger      how much later the right reel starts to slow
+// slowDist     distance covered while slowing down (larger = longer, softer stop)
+// overshoot    how far the reel passes its resting place before bouncing back
+// bouncePeriod duration of one bounce oscillation
+// damping      0-1; lower = more bounces
+const RANDOM_DEFAULTS = Object.freeze({
+  radius: 50,
+  gap: 0,
+  squeeze: 12.5,
+  speed: 0.6,
+  ramp: 220,
+  spin: 1000,
+  stagger: 420,
+  slowDist: 40,
+  overshoot: 8,
+  bouncePeriod: 200,
+  damping: 0.3,
+  prep: 120,
+});
+
+const RANDOM_BOUNDS = Object.freeze({
+  radius: [50, 100],
+  gap: [0, 200],
+  squeeze: [0, 30],
+  speed: [0.15, 1.6],
+  ramp: [40, 800],
+  spin: [100, 4000],
+  stagger: [0, 1500],
+  slowDist: [40, 400],
+  overshoot: [0, 40],
+  bouncePeriod: [120, 800],
+  damping: [0.1, 0.9],
+  prep: [0, 1200],
+});
+
+const runtimeWindow = typeof window !== 'undefined' ? window : null;
+const randomConfig = (runtimeWindow?.AgentRobotAvatarRandomConfig && typeof runtimeWindow.AgentRobotAvatarRandomConfig === 'object')
+  ? runtimeWindow.AgentRobotAvatarRandomConfig
+  : {};
+
+function normalizeConfigValue(key, value) {
+  const fallback = RANDOM_DEFAULTS[key];
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  const [min, max] = RANDOM_BOUNDS[key];
+  return Math.max(min, Math.min(max, numeric));
+}
+
+if (runtimeWindow) {
+  runtimeWindow.AgentRobotAvatarRandomConfig = randomConfig;
+  runtimeWindow.AgentRobotAvatarRandomDefaults = RANDOM_DEFAULTS;
+  runtimeWindow.AgentRobotAvatarRandomBounds = RANDOM_BOUNDS;
+}
+
+function currentRandomConfig() {
+  const config = {};
+  for (const key of Object.keys(RANDOM_DEFAULTS)) config[key] = normalizeConfigValue(key, randomConfig[key]);
+  return config;
+}
+
+// Reel position (in units, increasing = moving down) as a function of time.
+// Phase 1: ramp up, then constant speed. Phase 2: Hermite slow-down that starts
+// at the spin speed and ends at rest just past the target. Phase 3: damped
+// bounce back onto the target.
+function planReel(config, slowAt) {
+  const { speed: v, ramp, period: P, slowDist: L, overshoot: O, bouncePeriod, damping: zeta } = config;
+  const spinPos = t => (t < ramp ? v * t * t / (2 * ramp) : v * (t - ramp / 2));
+  const rampEnd = v * ramp / 2;
+
+  let n = Math.max(1, Math.round((spinPos(slowAt) + L - O) / P));
+  while (n * P + O - L < rampEnd) n += 1;
+  const target = n * P;
+  const pStop = target + O - L;
+  const tStop = pStop / v + ramp / 2;
+  const D = 2 * L / v;
+
+  const wd = 2 * Math.PI / bouncePeriod;
+  const w = wd / Math.sqrt(1 - zeta * zeta);
+  const decay = zeta * w;
+  const bounceLength = O > 0.1 ? Math.log(O / 0.1) / decay : 0;
+  const tLand = tStop + D;
+  const tEnd = tLand + bounceLength;
+
+  const position = t => {
+    if (t < tStop) return spinPos(t);
+    if (t < tLand) {
+      const u = (t - tStop) / D;
+      const h10 = u * u * u - 2 * u * u + u;
+      const h01 = -2 * u * u * u + 3 * u * u;
+      return pStop + L * (2 * h10 + h01);
+    }
+    if (t >= tEnd) return target;
+    const tau = t - tLand;
+    return target + O * Math.exp(-decay * tau) * (Math.cos(wd * tau) + (decay / wd) * Math.sin(wd * tau));
+  };
+
+  return { position, tEnd, tStop, tLand, period: P };
+}
+
+function reducedMotion(instance) {
+  const requested = String(instance.getAttribute('motion') || 'auto').trim().toLowerCase();
+  if (requested === 'reduce') return true;
+  if (requested === 'full') return false;
+  return typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+    && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+function dispatchRandomState(instance, state) {
+  instance.dispatchEvent(new CustomEvent('face-state', { detail: { state } }));
+}
+
+function buildRandomFx(config, start, extra = {}) {
+  // Reel position is measured as distance along the drum surface. One pass of
+  // the eye is the visible half of the drum plus the hidden gap.
+  const period = Math.PI * config.radius + config.gap;
+  const reel = { ...config, period };
+  const plans = [planReel(reel, config.spin), planReel(reel, config.spin + config.stagger)];
+  return {
+    start,
+    duration: Math.max(plans[0].tEnd, plans[1].tEnd),
+    plans,
+    period,
+    radius: config.radius,
+    squeeze: config.squeeze,
+    ...extra,
+  };
+}
+
+// Preview hook for the tuner page: renders the expression frozen at `elapsed`
+// milliseconds using the live config and keeps it on screen (no timers, no
+// lifecycle events). Pass null to leave the preview. Returns the duration.
+proto._previewRandom = function(elapsed) {
+  if (elapsed === null) {
+    if (this._randomFx?.preview) {
+      this._randomFx = null;
+      this._releaseExpressionLock();
+      dispatchRandomState(this, 'idle');
+    }
+    return 0;
+  }
+  if (!this._randomFx?.preview) {
+    this.reset();
+    this._expressionLock = true;
+    this._look.x = 0;
+    this._look.y = 0;
+    dispatchRandomState(this, 'random');
+  }
+  this._randomFx = buildRandomFx(currentRandomConfig(), 0, { preview: true, frozenAt: elapsed });
+  this._resumeFrames?.();
+  return this._randomFx.duration;
+};
+
+proto.random = async function() {
+  this.noteActivity();
+  this._inputWanted = false;
+  const config = currentRandomConfig();
+  this.reset();
+  if (!(await this._prepareExpression({ normalizePose: true, duration: 160, pause: config.prep }))) return;
+
+  const token = this._transitionToken;
+  this._expressionLock = true;
+  this._look.x = 0;
+  this._look.y = 0;
+
+  this._randomFx = buildRandomFx(config, performance.now());
+  const duration = this._randomFx.duration;
+  dispatchRandomState(this, 'random');
+
+  await this._wait(duration + 30);
+  if (token !== this._transitionToken) return;
+
+  this._randomFx = null;
+  this._look.x = 0;
+  this._look.y = 0;
+  this._releaseExpressionLock();
+  dispatchRandomState(this, 'idle');
+};
+
+function drawRandom(now) {
+  const fx = this._randomFx;
+  if (!fx) return;
+
+  const elapsed = fx.frozenAt ?? Math.max(0, now - fx.start);
+  // Read live so a motion-preference change takes effect mid-action.
+  const reduced = fx.preview ? false : reducedMotion(this);
+  const { period: P, radius: R, squeeze } = fx;
+  const half = Math.PI * R / 2;
+
+  fx.plans.forEach((plan, index) => {
+    // Settled: leave the ordinary eye exactly as the regular draw left it.
+    if (elapsed >= plan.tEnd) return;
+
+    const base = index === 0 ? this._leftBase : this._rightBase;
+    const top = index === 0 ? this._leftTop : this._rightTop;
+    const bottom = index === 0 ? this._leftBottom : this._rightBottom;
+
+    // Reduced motion holds the eye part-way round instead of spinning.
+    const position = reduced ? P * 0.3 : plan.position(elapsed);
+    let offset = ((position % P) + P) % P;
+    if (offset > P / 2) offset -= P;
+
+    // Distance from the resting place, travelled along the drum surface. Beyond
+    // the visible half the eye is behind the drum and nothing is drawn.
+    const angle = Math.abs(offset) < half ? offset / R : Math.sign(offset) * Math.PI / 2;
+    const front = Math.abs(offset) < half ? Math.cos(angle) : 0;
+
+    // Same optical corrections as the wrap-waiting eyes, turned on their side:
+    // the eye gets slightly narrower and drifts toward the head edge as it
+    // rolls edge-on.
+    const side = 1 - front;
+    const width = 54 - squeeze * smooth(side);
+    const y = R * Math.sin(angle) + Math.sign(angle) * 6 * side ** 3;
+
+    base.setAttribute('cx', '0');
+    base.setAttribute('cy', y.toFixed(2));
+    base.setAttribute('rx', (width / 2).toFixed(2));
+    base.setAttribute('ry', (29 * front).toFixed(2));
+    base.setAttribute('opacity', '1');
+
+    // Eyelid masks stay out of the way while the eye is rolling.
+    top.setAttribute('y', '-240');
+    top.setAttribute('height', '90');
+    top.setAttribute('transform', 'rotate(0 0 -150)');
+    bottom.setAttribute('y', '150');
+    bottom.setAttribute('height', '90');
+    bottom.setAttribute('transform', 'rotate(0 0 150)');
+  });
+}
+
+registerAvatarExtension({
+  name: 'random',
+  actions: {
+    random() { return this.random(); },
+    slot() { return this.random(); },
+  },
+  beforePlay(action) {
+    if (action === 'random' || action === 'slot') return;
+    this._randomFx = null;
+  },
+  reset() {
+    this._randomFx = null;
+  },
+  draw: drawRandom,
+});
+
+export { AgentRobotAvatar, RANDOM_DEFAULTS };
+export default AgentRobotAvatar;