@dotcraft/avatar 0.6.3 → 0.6.5

package/src/composer/styles/overdrive.css

@@ -0,0 +1,264 @@
+[data-mascot-context='max'] .composer-mascot-motion {
+  --mascot-max-edge: oklch(from var(--mascot-energy-accent)
+    clamp(0.28, calc(l + 0.065), 0.96) clamp(0, calc(c * 0.96), 0.3) calc(h + 4));
+  --mascot-max-shift: oklch(from var(--mascot-energy-accent)
+    clamp(0.28, calc(l + 0.1), 0.96) clamp(0, calc(c * 0.92), 0.3) calc(h + 40));
+  --mascot-max-bright: oklch(from var(--mascot-energy-accent)
+    clamp(0.28, calc(l + 0.18), 0.96) clamp(0, calc(c * 0.68), 0.3) calc(h + 18));
+  --mascot-max-edge-bold: rgb(from var(--mascot-max-edge) r g b / 1);
+  --mascot-max-edge-faint: rgb(from var(--mascot-max-edge) r g b / 0.24);
+  --mascot-max-shift-bold: rgb(from var(--mascot-max-shift) r g b / 1);
+  --mascot-max-shift-medium: rgb(from var(--mascot-max-shift) r g b / 0.88);
+  --mascot-max-shift-soft: rgb(from var(--mascot-max-shift) r g b / 0.44);
+  --mascot-max-bright-medium: rgb(from var(--mascot-max-bright) r g b / 0.88);
+  --mascot-max-blur-hair: 1.4px;
+  --mascot-max-blur-edge: 2.4px;
+  --mascot-max-blur-glow: 6.8px;
+}
+
+.composer-mascot-motion::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  z-index: 3;
+  width: 104px;
+  height: 90px;
+  border-radius: 48%;
+  opacity: 0;
+  pointer-events: none;
+  transform: translate(-50%, -50%);
+  transform-origin: center;
+}
+
+[data-mascot-context='max'] .composer-mascot-motion::after {
+  background:
+    radial-gradient(circle, var(--mascot-max-bright) 0 0.55px, transparent 1.1px) 13% 42% / 3px 3px no-repeat,
+    radial-gradient(circle, var(--mascot-max-edge) 0 0.45px, transparent 1px) 27% 74% / 3px 3px no-repeat,
+    radial-gradient(circle, var(--mascot-max-shift) 0 0.5px, transparent 1.05px) 42% 18% / 3px 3px no-repeat,
+    radial-gradient(circle, var(--mascot-max-bright) 0 0.45px, transparent 1px) 68% 80% / 3px 3px no-repeat,
+    radial-gradient(circle, var(--mascot-max-edge) 0 0.55px, transparent 1.1px) 82% 28% / 3px 3px no-repeat,
+    radial-gradient(circle, var(--mascot-max-shift) 0 0.4px, transparent 0.95px) 91% 62% / 3px 3px no-repeat;
+  filter: drop-shadow(0 0 1.6px color-mix(in srgb, var(--mascot-max-edge) 32%, transparent));
+  opacity: 0.18;
+  animation: composer-mascot-max-micrograin 6.2s ease-in-out infinite;
+}
+
+@keyframes composer-mascot-max-overdrive-edge {
+  0%, 100% {
+    filter:
+      drop-shadow(-0.6px 0 var(--mascot-max-blur-hair) var(--mascot-max-edge-bold))
+      drop-shadow(0.7px 0 var(--mascot-max-blur-edge) var(--mascot-max-shift-medium))
+      drop-shadow(0 0 var(--mascot-max-blur-glow) var(--mascot-max-edge-faint));
+  }
+  46% {
+    filter:
+      drop-shadow(0.2px -0.75px var(--mascot-max-blur-hair) var(--mascot-max-shift-bold))
+      drop-shadow(-0.2px 0.8px var(--mascot-max-blur-edge) var(--mascot-max-bright-medium))
+      drop-shadow(0 0 var(--mascot-max-blur-glow) var(--mascot-max-shift-soft));
+  }
+}
+
+@keyframes composer-mascot-max-coat-dark {
+  0%, 34%, 100% { stop-color: var(--mascot-body-dark); }
+  14% {
+    stop-color: oklch(from var(--mascot-body-dark)
+      clamp(0.28, calc(l + 0.09), 0.96) clamp(0, calc(c * 0.9), 0.3) calc(h + 14));
+  }
+}
+
+@keyframes composer-mascot-max-coat-mid {
+  0%, 24%, 68%, 100% { stop-color: var(--mascot-body-mid); }
+  44% {
+    stop-color: oklch(from var(--mascot-body-mid)
+      clamp(0.28, calc(l + 0.14), 0.96) clamp(0, calc(c * 0.76), 0.3) calc(h + 31));
+  }
+}
+
+@keyframes composer-mascot-max-coat-light {
+  0%, 50%, 94%, 100% { stop-color: var(--mascot-body-light); }
+  72% {
+    stop-color: oklch(from var(--mascot-body-light)
+      clamp(0.28, calc(l + 0.15), 0.96) clamp(0, calc(c * 0.58), 0.3) calc(h + 41));
+  }
+}
+
+@keyframes composer-mascot-max-coat-mark-dark {
+  0%, 44%, 100% { stop-color: var(--mascot-mark-dark); }
+  20% {
+    stop-color: oklch(from var(--mascot-mark-dark)
+      clamp(0.28, calc(l + 0.1), 0.96) clamp(0, calc(c * 0.82), 0.3) calc(h + 18));
+  }
+}
+
+@keyframes composer-mascot-max-coat-mark-light {
+  0%, 40%, 88%, 100% { stop-color: var(--mascot-mark-energy); }
+  64% {
+    stop-color: oklch(from var(--mascot-mark-energy)
+      clamp(0.28, calc(l + 0.15), 0.96) clamp(0, calc(c * 0.6), 0.3) calc(h + 38));
+  }
+}
+
+@keyframes composer-mascot-max-micrograin {
+  0%, 100% { opacity: 0.08; transform: translate(-51%, -49%) scale(0.98); }
+  38% { opacity: 0.28; transform: translate(-49%, -52%) scale(1.02); }
+  68% { opacity: 0.13; transform: translate(-48%, -54%) scale(1.04); }
+}
+
+[data-mascot-profile-transition='active'] .composer-mascot-character-stage {
+  transform-origin: 50% 52%;
+  animation: composer-mascot-profile-character 1.24s linear both;
+}
+
+[data-mascot-profile-transition='active'] .composer-mascot-motion::before {
+  content: '';
+  position: absolute;
+  top: 52%;
+  left: 50%;
+  z-index: 1;
+  width: 64px;
+  height: 64px;
+  box-sizing: border-box;
+  border: 1px solid transparent;
+  border-radius: 50%;
+  background: radial-gradient(
+    circle,
+    #010106 0 34%,
+    #05050c 38%,
+    rgba(232, 236, 255, 0.78) 42%,
+    rgba(135, 145, 180, 0.18) 48%,
+    transparent 66%
+  );
+  opacity: 0;
+  pointer-events: none;
+  transform: translate(-50%, -50%) scale(0.16);
+  transform-origin: center;
+  animation:
+    composer-mascot-profile-hole 1.24s linear both,
+    composer-mascot-profile-rim 1.24s linear both;
+}
+
+[data-mascot-profile-transition='active'] .composer-mascot-motion::after {
+  top: 52%;
+  left: 50%;
+  z-index: 1;
+  width: 86px;
+  height: 86px;
+  border-radius: 50%;
+  color: var(--mascot-profile-from-accent);
+  background:
+    radial-gradient(circle, currentColor 0 0.9px, transparent 1.55px) 50% 2% / 4px 4px no-repeat,
+    radial-gradient(circle, currentColor 0 0.76px, transparent 1.4px) 78% 12% / 4px 4px no-repeat,
+    radial-gradient(circle, rgba(255, 255, 255, 0.88) 0 0.65px, transparent 1.3px) 96% 42% / 4px 4px no-repeat,
+    radial-gradient(circle, currentColor 0 0.82px, transparent 1.48px) 88% 76% / 4px 4px no-repeat,
+    radial-gradient(circle, currentColor 0 0.9px, transparent 1.55px) 55% 98% / 4px 4px no-repeat,
+    radial-gradient(circle, rgba(255, 255, 255, 0.8) 0 0.65px, transparent 1.3px) 19% 86% / 4px 4px no-repeat,
+    radial-gradient(circle, currentColor 0 0.76px, transparent 1.4px) 3% 55% / 4px 4px no-repeat,
+    radial-gradient(circle, currentColor 0 0.82px, transparent 1.48px) 14% 20% / 4px 4px no-repeat;
+  filter: drop-shadow(0 0 3px currentColor);
+  opacity: 0;
+  animation:
+    composer-mascot-profile-particles 1.24s linear both,
+    composer-mascot-profile-particle-color 1.24s linear both;
+}
+
+[data-composer-root]:has([data-mascot-profile-transition='active']) .composer-mascot-contact-shadow {
+  animation: composer-mascot-profile-contact-shadow 1.24s linear both;
+}
+
+@keyframes composer-mascot-profile-character {
+  0%, 100% {
+    opacity: 1;
+    transform: translateY(0) rotate(0) scale(1);
+    filter: none;
+  }
+  18% {
+    opacity: 1;
+    transform: translateY(0) rotate(0) scale(1.015, 0.99);
+    filter: saturate(1.03);
+  }
+  34% {
+    opacity: 0.96;
+    transform: translateY(0) rotate(1.2deg) scale(0.76, 0.8);
+    filter: brightness(0.96) saturate(1.08);
+  }
+  46% {
+    opacity: 0.14;
+    transform: translateY(0) rotate(-4deg) scale(0.13);
+    filter: brightness(0.72) saturate(1.18) blur(0.7px);
+  }
+  48%, 52% {
+    opacity: 0;
+    transform: translateY(0) rotate(-6deg) scale(0.02);
+    filter: brightness(0.58) saturate(1.2) blur(1px);
+  }
+  64% {
+    opacity: 0.95;
+    transform: translateY(0) rotate(1.8deg) scale(1.1, 0.92);
+    filter: brightness(1.12);
+  }
+  76% {
+    opacity: 1;
+    transform: translateY(0) rotate(-0.8deg) scale(0.97, 1.035);
+    filter: none;
+  }
+  89% {
+    opacity: 1;
+    transform: translateY(0) rotate(0.3deg) scale(1.01, 0.995);
+    filter: none;
+  }
+}
+
+@keyframes composer-mascot-profile-hole {
+  0%, 12%, 100% { opacity: 0; transform: translate(-50%, -50%) scale(0.16); }
+  30% { opacity: 0.72; transform: translate(-50%, -50%) scale(0.72); }
+  46%, 54% { opacity: 1; transform: translate(-50%, -50%) scale(1); }
+  72% { opacity: 0.54; transform: translate(-50%, -50%) scale(0.66); }
+  88% { opacity: 0; transform: translate(-50%, -50%) scale(0.2); }
+}
+
+@keyframes composer-mascot-profile-particles {
+  0%, 14%, 100% { opacity: 0; transform: translate(-50%, -50%) rotate(0) scale(1); }
+  20% { opacity: 0.45; transform: translate(-50%, -50%) rotate(8deg) scale(1); }
+  34% { opacity: 0.92; transform: translate(-50%, -50%) rotate(38deg) scale(0.72); }
+  48% { opacity: 0.12; transform: translate(-50%, -50%) rotate(86deg) scale(0.16); }
+  49.5% { opacity: 0; transform: translate(-50%, -50%) rotate(96deg) scale(0.08); }
+  50.5% { opacity: 0; transform: translate(-50%, -50%) rotate(104deg) scale(1); }
+  64% { opacity: 0.82; transform: translate(-50%, -50%) rotate(146deg) scale(0.7); }
+  82% { opacity: 0.08; transform: translate(-50%, -50%) rotate(206deg) scale(0.14); }
+  86% { opacity: 0; transform: translate(-50%, -50%) rotate(218deg) scale(0.08); }
+}
+
+@keyframes composer-mascot-profile-particle-color {
+  0%, 42% { color: var(--mascot-profile-from-accent); }
+  49.5%, 50.5% { color: rgba(240, 244, 255, 0.96); }
+  58%, 100% { color: var(--mascot-profile-to-accent); }
+}
+
+@keyframes composer-mascot-profile-rim {
+  0%, 16% {
+    border-color: color-mix(in srgb, var(--mascot-profile-from-accent) 72%, transparent);
+    box-shadow: 0 0 12px color-mix(in srgb, var(--mascot-profile-from-accent) 42%, transparent);
+  }
+  34% {
+    border-color: color-mix(in srgb, var(--mascot-profile-from-accent) 84%, white);
+    box-shadow: 0 0 15px color-mix(in srgb, var(--mascot-profile-from-accent) 48%, transparent);
+  }
+  50% {
+    border-color: rgba(246, 248, 255, 0.92);
+    box-shadow: 0 0 17px rgba(220, 226, 255, 0.46);
+  }
+  66% {
+    border-color: color-mix(in srgb, var(--mascot-profile-to-accent) 84%, white);
+    box-shadow: 0 0 15px color-mix(in srgb, var(--mascot-profile-to-accent) 48%, transparent);
+  }
+  84%, 100% {
+    border-color: color-mix(in srgb, var(--mascot-profile-to-accent) 72%, transparent);
+    box-shadow: 0 0 12px color-mix(in srgb, var(--mascot-profile-to-accent) 36%, transparent);
+  }
+}
+
+@keyframes composer-mascot-profile-contact-shadow {
+  0%, 100% { opacity: 1; transform: translateX(50%) scaleX(1); }
+  46%, 54% { opacity: 0; transform: translateX(50%) scaleX(0.25); }
+}

package/src/composer/styles/props.css

@@ -0,0 +1,21 @@
+@keyframes composer-mascot-land {
+  0%, 100% { transform: translateY(0) scale(1, 1); }
+  35% { transform: translateY(2px) scale(1.12, 0.86); }
+  70% { transform: translateY(-2px) scale(0.97, 1.03); }
+}
+
+.composer-mascot-land {
+  animation: composer-mascot-land 380ms ease-out;
+  transform-origin: bottom center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .composer-mascot-motion,
+  .composer-mascot-motion * {
+    animation: none !important;
+    transition: none !important;
+  }
+}
+
+[data-composer-mascot-motion='off'],
+[data-composer-mascot-motion='off'] * { animation: none !important; transition: none !important; }

package/src/composer/types.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react'
+export type MascotExpression = 'neutral' | 'happy' | 'operator' | 'sleep'
+export type MascotLight = 'default' | 'error' | 'success'
+export interface ComposerMascotContext {
+  size: number
+  activity: 'error' | 'success' | 'sleeping' | 'dragging' | 'decision' | 'working' | 'focused' | 'idle'
+  expression: MascotExpression
+  light: MascotLight
+  submitRevision: number
+  reasoningEffort: 'off' | 'low' | 'medium' | 'high' | 'extraHigh'
+  speed: 'standard' | 'fast'
+  contextMax: boolean
+  reducedMotion: boolean
+}
+export interface ComposerMascotProps {
+  name?: string
+  motion?: 'system' | 'on' | 'off'
+  theme?: 'light' | 'dark'
+  focused?: boolean
+  dragOver?: boolean
+  bounceSignal?: number
+  interaction?: { expression?: MascotExpression; light?: MascotLight; hold?: 'sign'; bubble?: ReactNode }
+  reasoningEffort?: ComposerMascotContext['reasoningEffort']
+  speed?: ComposerMascotContext['speed']
+  contextMax?: boolean
+  anchorOffset?: number
+  anchorPushSignal?: number
+  handoff?: boolean
+  renderCharacter?: (character: ReactNode, context: ComposerMascotContext) => ReactNode
+  renderMenu?: (position: { x: number; y: number }, close: () => void) => ReactNode
+  onNameRendered?: (name: string | undefined) => void
+}

package/src/composer/useComposerAvatarBehavior.ts

@@ -0,0 +1,98 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { AvatarPose } from '../index.js'
+import type { MascotExpression } from './types.js'
+
+export type ComposerAvatarGesture = 'blink' | 'look-left' | 'look-right' | 'antenna-bob'
+
+interface ComposerAvatarBehaviorOptions {
+  semanticPose: AvatarPose
+  baseExpression: MascotExpression
+  focused: boolean
+  dragOver: boolean
+  sleeping: boolean
+  waving: boolean
+  activeIdle: boolean
+  bounceSignal: number
+  reducedMotion: boolean
+  directionalGestures?: boolean
+}
+
+export function useComposerAvatarBehavior(options: ComposerAvatarBehaviorOptions): {
+  pose: AvatarPose
+  expression: 'base' | 'happy' | 'operator' | 'sleep' | undefined
+  gesture: ComposerAvatarGesture | undefined
+  gestureSequence: number
+  clearGesture: () => void
+  completeGesture: (sequence: number) => void
+} {
+  const [receiptAcknowledging, setReceiptAcknowledging] = useState(false)
+  const [gesture, setGesture] = useState<ComposerAvatarGesture>()
+  const [gestureSequence, setGestureSequence] = useState(0)
+  const previousBounce = useRef(options.bounceSignal)
+
+  useEffect(() => {
+    if (options.reducedMotion || options.semanticPose !== 'idle') {
+      previousBounce.current = options.bounceSignal
+      setReceiptAcknowledging(false)
+      return
+    }
+    if (options.bounceSignal === previousBounce.current) return
+    previousBounce.current = options.bounceSignal
+    setReceiptAcknowledging(true)
+    const timer = window.setTimeout(() => setReceiptAcknowledging(false), 350)
+    return () => window.clearTimeout(timer)
+  }, [options.bounceSignal, options.reducedMotion, options.semanticPose])
+
+  useEffect(() => {
+    if (options.sleeping || options.activeIdle || options.reducedMotion) {
+      setGesture(undefined)
+      return
+    }
+    if (options.baseExpression !== 'neutral' && options.baseExpression !== 'happy') return
+    let timer = 0
+    const schedule = (): void => {
+      timer = window.setTimeout(() => {
+        if (!document.hidden) {
+          const value = Math.random()
+          const next = value < 0.5
+            ? 'blink'
+            : value < 0.72
+              ? (Math.random() < 0.5 ? 'look-left' : 'look-right')
+              : value < 0.86
+                ? 'antenna-bob'
+                : undefined
+          if (next && (options.directionalGestures !== false || (next !== 'look-left' && next !== 'look-right'))) {
+            setGesture(next)
+            setGestureSequence((sequence) => sequence + 1)
+          }
+        }
+        schedule()
+      }, 2600 + Math.random() * 3200)
+    }
+    schedule()
+    return () => { window.clearTimeout(timer) }
+  }, [options.sleeping, options.activeIdle, options.reducedMotion, options.baseExpression, options.directionalGestures])
+
+  const clearGesture = useCallback(() => setGesture(undefined), [])
+  const completeGesture = useCallback((sequence: number) => {
+    setGesture((current) => sequence === gestureSequence ? undefined : current)
+  }, [gestureSequence])
+
+  const expression = options.semanticPose === 'idle'
+    ? options.waving || options.focused
+      ? 'happy'
+      : options.dragOver || options.baseExpression === 'operator'
+        ? 'operator'
+        : options.sleeping
+          ? 'sleep'
+          : 'base'
+    : undefined
+  return {
+    pose: options.semanticPose === 'idle' && receiptAcknowledging ? 'acknowledge' : options.semanticPose,
+    expression,
+    gesture,
+    gestureSequence,
+    clearGesture,
+    completeGesture
+  }
+}

package/src/composer/useComposerMotion.ts

@@ -0,0 +1,15 @@
+import { useEffect, useState } from 'react'
+import { prefersReducedMotion } from './constants.js'
+export function useComposerMotion(mode: 'system' | 'on' | 'off') {
+  const [reduced, setReduced] = useState(prefersReducedMotion)
+  useEffect(() => {
+    const update = () => setReduced(prefersReducedMotion())
+    const media = window.matchMedia?.('(prefers-reduced-motion: reduce)')
+    media?.addEventListener?.('change', update)
+    const observer = new MutationObserver(update)
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-reduce-motion'] })
+    update()
+    return () => { media?.removeEventListener?.('change', update); observer.disconnect() }
+  }, [])
+  return mode === 'on' || (mode === 'system' && !reduced)
+}

package/src/composer/useComposerProfile.ts

@@ -0,0 +1,50 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+import { deriveAppearance, mascotPaletteOf } from '../index.js'
+import { mascotNameKey, MASCOT_PROFILE_TRANSITION_SWAP_MS, MASCOT_PROFILE_TRANSITION_DURATION_MS, type MascotProfileTransition } from './constants.js'
+export function useComposerProfile(mascotName: string | undefined, reduced: boolean) {
+  const [renderedMascotAvatar, setRenderedMascotAvatar] = useState(mascotName)
+  const [transitionState, setTransitionState] = useState<{ revision: number; transition: MascotProfileTransition | null }>({ revision: 0, transition: null })
+  const renderedMascotAvatarRef = useRef(renderedMascotAvatar)
+  const targetMascotAvatarRef = useRef(mascotName)
+  renderedMascotAvatarRef.current = renderedMascotAvatar
+  targetMascotAvatarRef.current = mascotName
+  const targetAvatarKey = mascotNameKey(mascotName)
+  useLayoutEffect(() => {
+    const currentAvatar = renderedMascotAvatarRef.current
+    if (targetAvatarKey === mascotNameKey(currentAvatar)) {
+      setTransitionState(current => ({ ...current, transition: null }))
+      return undefined
+    }
+
+    const nextAvatar = targetMascotAvatarRef.current
+    if (reduced) {
+      renderedMascotAvatarRef.current = nextAvatar
+      setRenderedMascotAvatar(nextAvatar)
+      setTransitionState(current => ({ ...current, transition: null }))
+      return undefined
+    }
+
+    setTransitionState(current => ({
+      revision: current.revision + 1,
+      transition: {
+        fromAccent: mascotPaletteOf(deriveAppearance(currentAvatar ?? '')).accent,
+        toAccent: mascotPaletteOf(deriveAppearance(nextAvatar ?? '')).accent
+      }
+    }))
+
+    const swapTimer = window.setTimeout(() => {
+      renderedMascotAvatarRef.current = nextAvatar
+      setRenderedMascotAvatar(nextAvatar)
+    }, MASCOT_PROFILE_TRANSITION_SWAP_MS)
+    const finishTimer = window.setTimeout(() => {
+      setTransitionState(current => ({ ...current, transition: null }))
+    }, MASCOT_PROFILE_TRANSITION_DURATION_MS)
+
+    return () => {
+      window.clearTimeout(swapTimer)
+      window.clearTimeout(finishTimer)
+    }
+  }, [targetAvatarKey, reduced])
+
+  return { avatar: renderedMascotAvatar, profileTransition: transitionState.transition, profileTransitionRevision: transitionState.revision }
+}

package/src/composer/useMascotActiveIdle.ts

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useRef, useState, type AnimationEvent } from 'react'
+import {
+  MASCOT_ACTIVE_IDLE_ACTIVITY_THROTTLE_MS,
+  MASCOT_ACTIVE_IDLE_HOLD_MS,
+  MASCOT_ACTIVE_IDLE_JITTER_MS,
+  MASCOT_ACTIVE_IDLE_MIN_MS,
+  MASCOT_ACTIVE_IDLE_TRAVEL_MS,
+  pickMascotActiveIdle,
+  type MascotActiveIdle,
+  type MascotActiveIdleMotion,
+  type MascotActiveIdlePhase,
+  type MascotActiveIdlePlan,
+  type MascotIdleDirection
+} from './constants.js'
+
+export interface MascotActiveIdleAttributes {
+  'data-mascot-active-idle'?: MascotActiveIdleMotion
+  'data-mascot-idle-phase'?: MascotActiveIdlePhase
+  'data-mascot-idle-direction'?: MascotIdleDirection
+  'data-mascot-idle-travel'?: MascotIdleDirection
+}
+
+export interface MascotActiveIdleOptions {
+  /** True while the character is free to wander: idle, awake, unfocused, and motion allowed. */
+  enabled: boolean
+  onStart?: () => void
+  /** Runs on user activity, before the schedule-reset throttle. */
+  onActivity?: () => void
+  /** Decides direction and motion pool at launch; `null` skips this round. */
+  plan?: () => MascotActiveIdlePlan | null
+  /** Whether pointer movement aborts a trip in flight; it always defers the next one. */
+  interruptOnPointerMove?: boolean
+}
+
+export interface MascotActiveIdleHandle {
+  activeIdle: MascotActiveIdle | null
+  activityRevision: number
+  className: 'composer-mascot-active-idle' | undefined
+  attributes: MascotActiveIdleAttributes
+  cancel: () => void
+  onAnimationEnd: (event: AnimationEvent<Element>) => void
+}
+
+const RETRY_MS = 5000
+const LEG_SETTLE_MS = 160
+
+function opposite(direction: MascotIdleDirection): MascotIdleDirection {
+  return direction === 'left' ? 'right' : 'left'
+}
+
+function finisherOf(trip: MascotActiveIdle): string {
+  if (trip.motion === 'hop') return 'composer-mascot-idle-hop-travel'
+  if (trip.motion === 'rocket') return 'composer-mascot-idle-rocket-flight-x'
+  return trip.phase === 'outbound' ? 'composer-mascot-idle-hover-launch-body' : 'composer-mascot-idle-hover-land-body'
+}
+
+function advance(trip: MascotActiveIdle | null): MascotActiveIdle | null {
+  if (!trip) return null
+  if (trip.phase === 'outbound') return { ...trip, phase: 'away' }
+  if (trip.phase === 'away') return { ...trip, phase: 'inbound', travel: opposite(trip.direction) }
+  return null
+}
+
+/**
+ * Schedules the traveling idle antics (hop, rocket, hover) after a quiet stretch. Any host that
+ * renders the stage classes (see MascotIdleStage) can spread the returned attributes on its root.
+ */
+export function useMascotActiveIdle(options: MascotActiveIdleOptions): MascotActiveIdleHandle {
+  const { enabled, interruptOnPointerMove = true } = options
+  const [activeIdle, setActiveIdle] = useState<MascotActiveIdle | null>(null)
+  const [activityRevision, setActivityRevision] = useState(0)
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+  const activeRef = useRef(activeIdle)
+  activeRef.current = activeIdle
+  const lastActivityRef = useRef(0)
+  const lastMotionRef = useRef<MascotActiveIdleMotion | null>(null)
+
+  const cancel = useCallback(() => setActiveIdle(null), [])
+
+  const markActivity = useCallback((interrupt: boolean) => {
+    if (interrupt) setActiveIdle(null)
+    optionsRef.current.onActivity?.()
+    const now = Date.now()
+    if (now - lastActivityRef.current < MASCOT_ACTIVE_IDLE_ACTIVITY_THROTTLE_MS) return
+    lastActivityRef.current = now
+    setActivityRevision((value) => value + 1)
+  }, [])
+
+  useEffect(() => {
+    const interrupt = (): void => markActivity(true)
+    const pointerMove = (): void => {
+      if (Date.now() - lastActivityRef.current >= MASCOT_ACTIVE_IDLE_ACTIVITY_THROTTLE_MS) {
+        markActivity(interruptOnPointerMove)
+      }
+    }
+    window.addEventListener('keydown', interrupt)
+    window.addEventListener('pointerdown', interrupt)
+    window.addEventListener('pointermove', pointerMove, { passive: true })
+    window.addEventListener('wheel', interrupt, { passive: true })
+    window.addEventListener('focusin', interrupt)
+    return () => {
+      window.removeEventListener('keydown', interrupt)
+      window.removeEventListener('pointerdown', interrupt)
+      window.removeEventListener('pointermove', pointerMove)
+      window.removeEventListener('wheel', interrupt)
+      window.removeEventListener('focusin', interrupt)
+    }
+  }, [markActivity, interruptOnPointerMove])
+
+  useEffect(() => {
+    if (!enabled) {
+      setActiveIdle(null)
+      return undefined
+    }
+    let timer = 0
+    const wait = (): number => MASCOT_ACTIVE_IDLE_MIN_MS + Math.random() * MASCOT_ACTIVE_IDLE_JITTER_MS
+    const start = (): void => {
+      if (document.hidden || activeRef.current) {
+        timer = window.setTimeout(start, RETRY_MS)
+        return
+      }
+      const plan = optionsRef.current.plan?.()
+      if (plan === null) {
+        timer = window.setTimeout(start, wait())
+        return
+      }
+      const motion = pickMascotActiveIdle(Math.random(), lastMotionRef.current, plan?.motions)
+      lastMotionRef.current = motion
+      optionsRef.current.onStart?.()
+      const direction = plan?.direction ?? 'left'
+      setActiveIdle({ motion, phase: 'outbound', direction, travel: direction })
+    }
+    timer = window.setTimeout(start, wait())
+    return () => window.clearTimeout(timer)
+  }, [enabled, activityRevision])
+
+  useEffect(() => {
+    if (!activeIdle) return undefined
+    const delay = activeIdle.phase === 'away'
+      ? MASCOT_ACTIVE_IDLE_HOLD_MS[activeIdle.motion]
+      : MASCOT_ACTIVE_IDLE_TRAVEL_MS[activeIdle.motion] + LEG_SETTLE_MS
+    const timer = window.setTimeout(() => setActiveIdle(advance), delay)
+    return () => window.clearTimeout(timer)
+  }, [activeIdle])
+
+  const onAnimationEnd = useCallback((event: AnimationEvent<Element>) => {
+    setActiveIdle((current) => {
+      if (!current || event.animationName !== finisherOf(current)) return current
+      return current.phase === 'outbound' ? { ...current, phase: 'away' } : null
+    })
+  }, [])
+
+  const attributes: MascotActiveIdleAttributes = activeIdle
+    ? {
+        'data-mascot-active-idle': activeIdle.motion,
+        'data-mascot-idle-phase': activeIdle.phase,
+        'data-mascot-idle-direction': activeIdle.direction,
+        'data-mascot-idle-travel': activeIdle.travel
+      }
+    : {}
+  return {
+    activeIdle,
+    activityRevision,
+    className: activeIdle ? 'composer-mascot-active-idle' : undefined,
+    attributes,
+    cancel,
+    onAnimationEnd
+  }
+}