@dotcraft/avatar 0.6.4 → 0.6.5

package/dist/composer/useMascotActiveIdle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMascotActiveIdle.js","sourceRoot":"","sources":["../../src/composer/useMascotActiveIdle.ts"],"names":[],"mappings":"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"}

package/dist/react.d.ts

@@ -3,4 +3,9 @@ export { DecorationSwatch, PrimaryDecoration, SecondaryDecoration } from './Deco
 export { ComposerMascot } from './composer/ComposerMascot.js';
 export type { ComposerMascotProps, ComposerMascotContext, MascotExpression, MascotLight } from './composer/types.js';
 export { ComposerMascotShadow } from './composer/ComposerMascotShadow.js';
+export { useComposerAvatarBehavior } from './composer/useComposerAvatarBehavior.js';
+export { useMascotActiveIdle, type MascotActiveIdleAttributes, type MascotActiveIdleHandle, type MascotActiveIdleOptions } from './composer/useMascotActiveIdle.js';
+export { MascotIdleStage } from './composer/MascotIdleStage.js';
+export { MASCOT_SLEEP_AFTER_MS } from './composer/constants.js';
+export type { MascotActiveIdle, MascotActiveIdleMotion, MascotActiveIdlePhase, MascotActiveIdlePlan, MascotIdleDirection } from './composer/constants.js';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACpG,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACpH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAA"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACpG,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACpH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAA;AACzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAA;AACnF,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,KAAK,sBAAsB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mCAAmC,CAAA;AACnK,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAC/D,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/react.js

@@ -2,4 +2,8 @@ export { Avatar, AppearanceAvatar } from './Avatar.js';
 export { DecorationSwatch, PrimaryDecoration, SecondaryDecoration } from './Decorations.js';
 export { ComposerMascot } from './composer/ComposerMascot.js';
 export { ComposerMascotShadow } from './composer/ComposerMascotShadow.js';
+export { useComposerAvatarBehavior } from './composer/useComposerAvatarBehavior.js';
+export { useMascotActiveIdle } from './composer/useMascotActiveIdle.js';
+export { MascotIdleStage } from './composer/MascotIdleStage.js';
+export { MASCOT_SLEEP_AFTER_MS } from './composer/constants.js';
 //# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAgD,MAAM,aAAa,CAAA;AACpG,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAE7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAA"}
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAgD,MAAM,aAAa,CAAA;AACpG,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAE7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAA;AACzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAA;AACnF,OAAO,EAAE,mBAAmB,EAA8F,MAAM,mCAAmC,CAAA;AACnK,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcraft/avatar",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Name-derived DotCraft avatars and React SVG animation components",
   "type": "module",
   "main": "./dist/index.js",

package/src/composer/ComposerMascot.tsx

@@ -5,7 +5,8 @@ import { useComposerAvatarBehavior } from './useComposerAvatarBehavior.js'
 import { consumeMascotHandoff, recordMascotHandoff } from './mascotHandoff.js'
 import { useComposerProfile } from './useComposerProfile.js'
 import { useComposerMotion } from './useComposerMotion.js'
-import { MASCOT_SIZE, MASCOT_SCALE, MASCOT_HIDDEN_RATIO, MASCOT_RAISE, MASCOT_SLEEP_AFTER_MS, MASCOT_WAVE_DURATION_MS, MASCOT_ACTIVE_IDLE_MIN_MS, MASCOT_ACTIVE_IDLE_JITTER_MS, MASCOT_ACTIVE_IDLE_ACTIVITY_THROTTLE_MS, MASCOT_ACTIVE_IDLE_TRAVEL_MS, MASCOT_ACTIVE_IDLE_HOLD_MS, MASCOT_SPARKLES, pickMascotActiveIdle, type MascotActiveIdleState, type MascotActiveIdleMotion } from './constants.js'
+import { MASCOT_SIZE, MASCOT_SCALE, MASCOT_HIDDEN_RATIO, MASCOT_RAISE, MASCOT_SLEEP_AFTER_MS, MASCOT_WAVE_DURATION_MS, MASCOT_SPARKLES } from './constants.js'
+import { useMascotActiveIdle } from './useMascotActiveIdle.js'
 import type { ComposerMascotProps, ComposerMascotContext, MascotExpression, MascotLight } from './types.js'
 export function ComposerMascot({ name, motion = 'system', theme = 'dark', focused = false, dragOver = false, bounceSignal = 0, interaction, reasoningEffort = 'off', speed = 'standard', contextMax = false, anchorOffset = 0, anchorPushSignal = 0, handoff = false, renderCharacter, renderMenu, onNameRendered }: ComposerMascotProps) {
   const reduced = !useComposerMotion(motion)
@@ -24,11 +25,8 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
   const [nodding, setNodding] = useState(false)
   const [landing, setLanding] = useState(false)
   const [pushLift, setPushLift] = useState(false)
-  const [activeIdle, setActiveIdle] = useState<MascotActiveIdleState | null>(null)
-  const [activityRevision, setActivityRevision] = useState(0)
   const rootRef = useRef<HTMLDivElement | null>(null)
-  const lastActivityRef = useRef(0)
-  const lastActiveIdleRef = useRef<MascotActiveIdleMotion | null>(null)
+  const clearGestureRef = useRef<() => void>(() => {})
 
   const baseExpression: MascotExpression =
     interaction?.expression ?? (dragOver ? 'operator' : focused ? 'happy' : 'neutral')
@@ -58,6 +56,24 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
             : laptopActive
               ? 'working'
               : 'idle'
+  const ambient =
+    !focused &&
+    !dragOver &&
+    !bubble &&
+    !holdSign &&
+    menuPos == null &&
+    baseExpression === 'neutral' &&
+    light === 'default'
+  const idle = useMascotActiveIdle({
+    enabled: ambient && !sleeping && !reduced,
+    onStart: () => clearGestureRef.current(),
+    onActivity: () => {
+      setSleeping((current) => {
+        if (current && !reduced) setStartled(true)
+        return false
+      })
+    }
+  })
   const avatarBehavior = useComposerAvatarBehavior({
     semanticPose: semanticAvatarPose,
     baseExpression,
@@ -65,10 +81,11 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
     dragOver,
     sleeping,
     waving,
-    activeIdle: activeIdle != null,
+    activeIdle: idle.activeIdle != null,
     bounceSignal,
     reducedMotion: reduced
   })
+  clearGestureRef.current = avatarBehavior.clearGesture
   const mascotPalette = mascotPaletteOf(deriveAppearance(avatar ?? ''))
   const activity: ComposerMascotContext["activity"] = light === 'error'
     ? 'error'
@@ -96,87 +113,6 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
     contextMax,
     reducedMotion: reduced
   }
-  const ambient =
-    !focused &&
-    !dragOver &&
-    !bubble &&
-    !holdSign &&
-    menuPos == null &&
-    baseExpression === 'neutral' &&
-    light === 'default'
-
-  const markActivity = useCallback(() => {
-    setActiveIdle(null)
-    setSleeping((current) => {
-      if (current && !reduced) setStartled(true)
-      return false
-    })
-    const now = Date.now()
-    if (now - lastActivityRef.current < MASCOT_ACTIVE_IDLE_ACTIVITY_THROTTLE_MS) return
-    lastActivityRef.current = now
-    setActivityRevision((value) => value + 1)
-  }, [reduced])
-
-  useEffect(() => {
-    const markPointerMoveActivity = (): void => {
-      if (Date.now() - lastActivityRef.current >= MASCOT_ACTIVE_IDLE_ACTIVITY_THROTTLE_MS) {
-        markActivity()
-      }
-    }
-    window.addEventListener('keydown', markActivity)
-    window.addEventListener('pointerdown', markActivity)
-    window.addEventListener('pointermove', markPointerMoveActivity, { passive: true })
-    window.addEventListener('wheel', markActivity, { passive: true })
-    window.addEventListener('focusin', markActivity)
-    return () => {
-      window.removeEventListener('keydown', markActivity)
-      window.removeEventListener('pointerdown', markActivity)
-      window.removeEventListener('pointermove', markPointerMoveActivity)
-      window.removeEventListener('wheel', markActivity)
-      window.removeEventListener('focusin', markActivity)
-    }
-  }, [markActivity])
-
-  useEffect(() => {
-    if (!ambient || sleeping || reduced) {
-      setActiveIdle(null)
-      return undefined
-    }
-
-    let timer = 0
-    const start = (): void => {
-      if (document.hidden) {
-        timer = window.setTimeout(start, 5000)
-        return
-      }
-      const motion = pickMascotActiveIdle(Math.random(), lastActiveIdleRef.current)
-      lastActiveIdleRef.current = motion
-      avatarBehavior.clearGesture()
-      setActiveIdle({ motion, phase: 'outbound' })
-    }
-    timer = window.setTimeout(
-      start,
-      MASCOT_ACTIVE_IDLE_MIN_MS + Math.random() * MASCOT_ACTIVE_IDLE_JITTER_MS
-    )
-    return () => window.clearTimeout(timer)
-  }, [ambient, activityRevision, sleeping, reduced, avatarBehavior.clearGesture])
-
-  useEffect(() => {
-    if (!activeIdle) return undefined
-    const delay = activeIdle.phase === 'away'
-      ? MASCOT_ACTIVE_IDLE_HOLD_MS[activeIdle.motion]
-      : MASCOT_ACTIVE_IDLE_TRAVEL_MS[activeIdle.motion] + 160
-    const timer = window.setTimeout(() => {
-      setActiveIdle((current) => {
-        if (!current) return null
-        if (current.phase === 'outbound') return { ...current, phase: 'away' }
-        if (current.phase === 'away') return { ...current, phase: 'inbound' }
-        return null
-      })
-    }, delay)
-    return () => window.clearTimeout(timer)
-  }, [activeIdle])
-
   useLayoutEffect(() => {
     if (!handoff) return undefined
     const el = rootRef.current
@@ -284,10 +220,10 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
       setSleeping(false)
       return
     }
-    if (sleeping || activeIdle) return
+    if (sleeping || idle.activeIdle) return
     const timer = window.setTimeout(() => setSleeping(true), MASCOT_SLEEP_AFTER_MS)
     return () => window.clearTimeout(timer)
-  }, [ambient, activityRevision, sleeping, activeIdle, reduced])
+  }, [ambient, idle.activityRevision, sleeping, idle.activeIdle, reduced])
 
   const wake = useCallback(() => {
     setSleeping(false)
@@ -311,21 +247,7 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
   }, [focused, reduced])
 
   const onAnimationEnd = (event: AnimationEvent<HTMLDivElement>): void => {
-    if (activeIdle) {
-      const expected = activeIdle.motion === 'hop'
-        ? 'composer-mascot-idle-hop-travel'
-        : activeIdle.motion === 'rocket'
-          ? 'composer-mascot-idle-rocket-flight-x'
-          : activeIdle.phase === 'outbound'
-            ? 'composer-mascot-idle-hover-launch-body'
-            : 'composer-mascot-idle-hover-land-body'
-      if (event.animationName === expected) {
-        setActiveIdle((current) => {
-          if (!current) return null
-          return current.phase === 'outbound' ? { ...current, phase: 'away' } : null
-        })
-      }
-    }
+    idle.onAnimationEnd(event)
     switch (event.animationName) {
       case 'composer-mascot-launch':
         setLaunching(false)
@@ -388,7 +310,7 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
 
   const rootClassName =
     [
-      activeIdle ? 'composer-mascot-active-idle' : null,
+      idle.className,
       sleeping ? 'composer-mascot-sleeping' : null,
     ]
       .filter(Boolean)
@@ -403,6 +325,7 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
 
       aria-hidden={interaction ? undefined : true}
       data-composer-mascot-motion={reduced ? 'off' : 'on'}
+      data-composer-avatar-pose={semanticAvatarPose}
       ref={rootRef}
       className={rootClassName}
       data-mascot-name={avatar ?? ''}
@@ -411,8 +334,7 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
       data-mascot-speed={speed}
       data-mascot-context={contextMax ? 'max' : 'default'}
       data-mascot-profile-transition={profileTransition ? 'active' : 'idle'}
-      data-mascot-active-idle={activeIdle?.motion}
-      data-mascot-idle-phase={activeIdle?.phase}
+      {...idle.attributes}
       data-mascot-anchor-offset={anchorOffset}
       onAnimationEnd={onAnimationEnd}
       style={{
@@ -446,25 +368,27 @@ export function ComposerMascot({ name, motion = 'system', theme = 'dark', focuse
       )}
       <div
         key={profileTransitionRevision}
-        className="composer-mascot-motion"
+        className="composer-mascot-motion composer-mascot-stage"
         style={{
+          '--mascot-idle-stage-scale': MASCOT_SCALE,
           transformOrigin: 'bottom center',
           transform: `scale(${MASCOT_SCALE})`,
 
           filter: `drop-shadow(0 5.3px 7.3px color-mix(in srgb, ${mascotPalette.shadow} 20%, transparent))`
-        }}
+        } as CSSProperties}
       >
         <div
+          className="composer-mascot-travel"
           style={{
             transformOrigin: 'bottom center',
             transition: 'transform 280ms cubic-bezier(0.34, 1.56, 0.64, 1)',
             transform: poseTransform
           }}
         >
-          <div className={shotClass}>
-            <div className={loopClass}>
+          <div className={shotClass ? `composer-mascot-lift ${shotClass}` : 'composer-mascot-lift'}>
+            <div className={`composer-mascot-body ${loopClass}`}>
               <div
-                className="composer-mascot-jelly"
+                className="composer-mascot-jelly composer-mascot-trail"
                 style={{ pointerEvents: 'auto', cursor: hasMenu ? 'context-menu' : undefined }}
                 onMouseEnter={sleeping ? wake : undefined}
                 onClick={() => {

package/src/composer/MascotIdleStage.tsx

@@ -0,0 +1,23 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+
+/**
+ * The layer stack the active-idle styles animate: travel (x), lift (y), body (squash), trail (jets).
+ * ComposerMascot tags its own wrappers with these classes instead of rendering this stage.
+ */
+export function MascotIdleStage({ className, style, children }: {
+  className?: string
+  style?: CSSProperties
+  children: ReactNode
+}): ReactElement {
+  return (
+    <div className={className ? `composer-mascot-stage ${className}` : 'composer-mascot-stage'} style={style}>
+      <div className="composer-mascot-travel">
+        <div className="composer-mascot-lift">
+          <div className="composer-mascot-body">
+            <div className="composer-mascot-trail">{children}</div>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/composer/constants.ts

@@ -10,12 +10,25 @@ export const MASCOT_ACTIVE_IDLE_ACTIVITY_THROTTLE_MS = 500
 
 export type MascotActiveIdleMotion = 'hop' | 'rocket' | 'hover'
 export type MascotActiveIdlePhase = 'outbound' | 'away' | 'inbound'
+export type MascotIdleDirection = 'left' | 'right'
+export const MASCOT_ACTIVE_IDLE_MOTIONS: readonly MascotActiveIdleMotion[] = ['hop', 'rocket', 'hover']
 
 export interface MascotActiveIdleState {
   motion: MascotActiveIdleMotion
   phase: MascotActiveIdlePhase
 }
 
+export interface MascotActiveIdle extends MascotActiveIdleState {
+  /** Where the trip heads; the inbound leg travels the other way. */
+  direction: MascotIdleDirection
+  travel: MascotIdleDirection
+}
+
+export interface MascotActiveIdlePlan {
+  direction?: MascotIdleDirection
+  motions?: readonly MascotActiveIdleMotion[]
+}
+
 export interface MascotProfileTransition {
   fromAccent: string
   toAccent: string
@@ -36,10 +49,18 @@ export const MASCOT_ACTIVE_IDLE_HOLD_MS: Record<MascotActiveIdleMotion, number>
   hover: 2800
 }
 
-export function pickMascotActiveIdle(random: number, previous: MascotActiveIdleMotion | null): MascotActiveIdleMotion {
-  const selected: MascotActiveIdleMotion = random < 0.65 ? 'hop' : random < 0.9 ? 'rocket' : 'hover'
-  if (selected !== previous) return selected
-  return selected === 'hop' ? 'rocket' : selected === 'rocket' ? 'hop' : 'rocket'
+export function pickMascotActiveIdle(
+  random: number,
+  previous: MascotActiveIdleMotion | null,
+  allowed: readonly MascotActiveIdleMotion[] = MASCOT_ACTIVE_IDLE_MOTIONS
+): MascotActiveIdleMotion {
+  const preferred: MascotActiveIdleMotion = random < 0.65 ? 'hop' : random < 0.9 ? 'rocket' : 'hover'
+  const selected = allowed.includes(preferred)
+    ? preferred
+    : MASCOT_ACTIVE_IDLE_MOTIONS.find((motion) => allowed.includes(motion)) ?? preferred
+  if (selected !== previous || allowed.length < 2) return selected
+  const alternate: MascotActiveIdleMotion = selected === 'hop' ? 'rocket' : selected === 'rocket' ? 'hop' : 'rocket'
+  return allowed.includes(alternate) ? alternate : allowed.find((motion) => motion !== selected) ?? selected
 }
 
 export const MASCOT_SPARKLES = Array.from({ length: 7 }, (_, i) => {