@dotcraft/avatar 0.6.3 → 0.6.5

package/src/appearanceModel.ts

@@ -0,0 +1,65 @@
+// Frozen v1 draw order. IDs are serialized; positions are only sampling weights.
+export const primaryIds = ['none', 'baseball-cap', 'bucket-hat', 'beret', 'beanie', 'top-hat', 'wizard-hat', 'chef-hat', 'party-hat', 'crown', 'hard-hat', 'nightcap', 'straw-hat', 'poop', 'banana', 'fried-egg', 'rubber-duck', 'paper-boat', 'traffic-cone', 'sprout', 'donut'] as const
+export const heldIds = ['task-board', 'wrench', 'shield', 'magnifier', 'control-panel'] as const
+export type HeldId = typeof heldIds[number]
+export const secondaryIds = ['none', 'forehead-goggles', ...heldIds] as const
+export type PrimaryId = typeof primaryIds[number]
+export type SecondaryId = typeof secondaryIds[number]
+export type DecorationId = Exclude<PrimaryId | SecondaryId, 'none'>
+export interface Appearance {
+  version: 2
+  palette: number
+  baseFace: number
+  primary: PrimaryId
+  secondary: SecondaryId
+}
+
+// Explicit allow-list, including the undecorated head. No cartesian-product fallback.
+const faceAccessories = ['none', ...heldIds] as const
+export const compatibility: Record<PrimaryId, readonly SecondaryId[]> = {
+  none: [...faceAccessories, 'forehead-goggles'],
+  'baseball-cap': faceAccessories, 'bucket-hat': faceAccessories, beret: faceAccessories,
+  beanie: faceAccessories, 'top-hat': faceAccessories, 'wizard-hat': faceAccessories,
+  'chef-hat': faceAccessories, 'party-hat': faceAccessories, crown: faceAccessories,
+  'hard-hat': faceAccessories, nightcap: faceAccessories, 'straw-hat': faceAccessories,
+  poop: [...faceAccessories, 'forehead-goggles'], banana: [...faceAccessories, 'forehead-goggles'],
+  'fried-egg': [...faceAccessories, 'forehead-goggles'], 'rubber-duck': [...faceAccessories, 'forehead-goggles'],
+  'paper-boat': [...faceAccessories, 'forehead-goggles'], 'traffic-cone': [...faceAccessories, 'forehead-goggles'],
+  sprout: [...faceAccessories, 'forehead-goggles'], donut: [...faceAccessories, 'forehead-goggles'],
+}
+export function isCompatible(primary: PrimaryId, secondary: SecondaryId) {
+  return compatibility[primary].includes(secondary)
+}
+export function withPrimary(appearance: Appearance, primary: PrimaryId): Appearance {
+  return { ...appearance, primary, secondary: isCompatible(primary, appearance.secondary) ? appearance.secondary : 'none' }
+}
+export function hashSeed(seed: string): number {
+  let value = 0x811c9dc5
+  for (let index = 0; index < seed.length; index++) value = Math.imul(value ^ seed.charCodeAt(index), 0x01000193)
+  // Avalanche avoids correlations between adjacent sample IDs and independent dimensions.
+  value ^= value >>> 16; value = Math.imul(value, 0x7feb352d)
+  value ^= value >>> 15; value = Math.imul(value, 0x846ca68b)
+  return (value ^ (value >>> 16)) >>> 0
+}
+export function isHeld(id: SecondaryId): id is HeldId { return (heldIds as readonly string[]).includes(id) }
+export const originalAppearance: Appearance = { version: 2, palette: -1, baseFace: 0, primary: 'none', secondary: 'none' }
+export function normalizeName(name: string): string { return name.trim().normalize('NFC') }
+export function deriveAppearance(name: string): Appearance {
+  const seed = normalizeName(name)
+  if (!seed) return { ...originalAppearance }
+  const draw = (dimension: string) => hashSeed(JSON.stringify(['dotcraft-avatar', 1, seed, dimension])) / 0x100000000
+  const primary = primaryIds[Math.floor(draw('primary') * primaryIds.length)]
+  const choices = compatibility[primary].filter(id => id !== 'none')
+  const secondaryDraw = (dimension: string) => hashSeed(JSON.stringify(['dotcraft-avatar', 2, seed, dimension])) / 0x100000000
+  const secondary = secondaryDraw('secondary-presence') < .5 ? 'none' : choices[Math.floor(secondaryDraw('secondary-item') * choices.length)]
+  return { version: 2, palette: Math.floor(draw('palette') * 12), baseFace: Math.floor(draw('face') * 5), primary, secondary }
+}
+export function sampleSeed(seed: string, round: number, index: number) {
+  return JSON.stringify([seed, round, index])
+}
+export function appearanceWall(seed: string, round = 0) {
+  return Array.from({ length: 100 }, (_, index) => {
+    const id = sampleSeed(seed, round, index)
+    return { id, appearance: deriveAppearance(id) }
+  })
+}

package/src/avatar.css

@@ -0,0 +1,62 @@
+.dca-robot {
+  display: inline-flex;
+  flex: none;
+  vertical-align: middle;
+  isolation: isolate;
+}
+
+.dca-canvas { overflow: visible; }
+.dca-body-motion { transform-origin: 512px 760px; }
+.dca-robot[data-motion='on'] .dca-body-motion {
+  transition: transform 260ms cubic-bezier(.22, .7, .3, 1);
+}
+
+/* The production rig owns arm geometry, paired paint layers and all arm motion. */
+.dca-robot[data-compact='true'] .dca-decoration-detail { display: none; }
+.dca-robot[data-exiting='true'] :is(.dca-part-prop-laptop, .dca-part-prop-sign) {
+  opacity: 0;
+  transition: opacity 140ms ease;
+}
+
+.dca-robot[data-pose='thinking'] .dca-body-motion { transform: rotate(-4deg); }
+.dca-robot[data-pose='working'] .dca-body-motion { transform: translateY(12px) rotate(2deg); }
+.dca-robot[data-pose='blocked'] .dca-body-motion { transform: translateY(22px) scaleY(.96); }
+.dca-robot[data-pose='greeting'] .dca-body-motion { transform: rotate(-3deg); }
+
+.dca-robot[data-motion='on'][data-pose='idle'] .dca-body-motion { animation: dca-breathe 5s ease-in-out infinite; }
+.dca-robot[data-motion='on'][data-pose='idle'] .dca-part-caret { animation: dca-cursor 7s step-end infinite; }
+.dca-robot[data-motion='on'][data-pose='working'] .dca-body-motion { animation: dca-work var(--dca-loop) ease-in-out infinite; }
+.dca-robot[data-motion='on'][data-pose='done'] .dca-body-motion { animation: dca-celebrate 800ms ease-in-out both; }
+.dca-robot[data-motion='on'][data-pose='acknowledge'] .dca-body-motion { animation: dca-nod 350ms ease-in-out both; }
+
+.dca-robot[data-paused='true'] * { animation-play-state: paused !important; }
+.dca-robot[data-exiting='true'] .dca-body-motion { animation: none !important; }
+.dca-robot[data-motion='off'] * { animation: none !important; transition: none !important; }
+
+@keyframes dca-breathe {
+  0%, 100% { transform: translateY(0) scaleY(1); }
+  50% { transform: translateY(-9px) scaleY(1.008); }
+}
+@keyframes dca-cursor { 0%, 93%, 100% { opacity: 1; } 95%, 98% { opacity: .12; } }
+@keyframes dca-work {
+  0%, 100% { transform: translateY(12px) rotate(2deg); }
+  50% { transform: translateY(5px) rotate(0deg); }
+}
+@keyframes dca-celebrate {
+  0%, 100% { transform: translateY(0); }
+  20% { transform: translateY(10px) scaleY(.97); }
+  55% { transform: translateY(-30px) rotate(-3deg); }
+}
+@keyframes dca-nod {
+  0%, 100% { transform: translateY(0); }
+  38% { transform: translateY(17px) scaleY(.97); }
+  68% { transform: translateY(-8px); }
+}
+
+
+.dca-robot[data-pose='sleep'] .dca-body-motion { transform: translateY(18px) rotate(4deg); }
+.dca-robot[data-pose='sleep'] .dca-part-light { opacity: .45; }
+.dca-robot[data-motion='off'][data-pose='greeting'] :is(.dca-part-arm-r-w, .dca-part-arm-r-b) { transform: translate(-48px, 88px) rotate(-110deg) scaleY(.8); }
+@media (prefers-reduced-motion: reduce) {
+ .dca-robot[data-mode='system'] * { animation: none !important; transition: none !important; }
+}

package/src/characters.ts

@@ -0,0 +1,5 @@
+export type AvatarState = 'idle' | 'thinking' | 'working' | 'waiting' | 'blocked' | 'done'
+export type AvatarPose = AvatarState | 'greeting' | 'acknowledge' | 'sleep'
+export type MotionMode = 'system' | 'on' | 'off'
+export type AvatarExpression = 'base' | 'happy' | 'operator' | 'sleep'
+export type AvatarGesture = 'blink' | 'look-left' | 'look-right' | 'antenna-bob'

package/src/composer/ComposerMascot.tsx

@@ -0,0 +1,445 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type AnimationEvent, type CSSProperties } from 'react'
+import { Avatar } from '../Avatar.js'
+import { deriveAppearance, mascotPaletteOf, type AvatarPose } from '../index.js'
+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_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)
+  const { avatar, profileTransition, profileTransitionRevision } = useComposerProfile(name, reduced)
+  useEffect(() => { onNameRendered?.(avatar) }, [avatar, onNameRendered])
+  const [menuPos, setMenuPos] = useState<{ x: number; y: number } | null>(null)
+  const [ambientSleeping, setSleeping] = useState(false)
+  const sleeping = ambientSleeping || interaction?.expression === 'sleep'
+  const [waving, setWaving] = useState(false)
+  const [greetingSequence, setGreetingSequence] = useState(0)
+  const [startled, setStartled] = useState(false)
+  const [launching, setLaunching] = useState(false)
+  const [cheering, setCheering] = useState(false)
+  const [sparkling, setSparkling] = useState(false)
+  const [shaking, setShaking] = useState(false)
+  const [nodding, setNodding] = useState(false)
+  const [landing, setLanding] = useState(false)
+  const [pushLift, setPushLift] = useState(false)
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const clearGestureRef = useRef<() => void>(() => {})
+
+  const baseExpression: MascotExpression =
+    interaction?.expression ?? (dragOver ? 'operator' : focused ? 'happy' : 'neutral')
+  const light: MascotLight = interaction?.light ?? 'default'
+  const hasMenu = renderMenu != null
+  const bubble = interaction?.bubble ?? null
+  const holdSign = interaction?.hold === 'sign'
+
+  const laptopActive =
+    !sleeping &&
+    !dragOver &&
+    !holdSign &&
+    bubble == null &&
+    baseExpression === 'operator' &&
+    light === 'default'
+  const expression: MascotExpression = sleeping ? 'sleep' : waving ? 'happy' : baseExpression
+  const semanticAvatarPose: AvatarPose = light === 'error'
+    ? 'blocked'
+    : light === 'success'
+      ? 'done'
+      : sleeping
+        ? 'sleep'
+        : waving
+          ? 'greeting'
+          : holdSign || bubble != null
+            ? 'waiting'
+            : 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,
+    focused,
+    dragOver,
+    sleeping,
+    waving,
+    activeIdle: idle.activeIdle != null,
+    bounceSignal,
+    reducedMotion: reduced
+  })
+  clearGestureRef.current = avatarBehavior.clearGesture
+  const mascotPalette = mascotPaletteOf(deriveAppearance(avatar ?? ''))
+  const activity: ComposerMascotContext["activity"] = light === 'error'
+    ? 'error'
+    : light === 'success'
+      ? 'success'
+      : sleeping
+        ? 'sleeping'
+        : dragOver
+          ? 'dragging'
+          : holdSign
+            ? 'decision'
+            : baseExpression === 'operator'
+              ? 'working'
+              : focused
+                ? 'focused'
+                : 'idle'
+  const context: ComposerMascotContext = {
+    size: MASCOT_SIZE,
+    activity,
+    expression,
+    light,
+    submitRevision: bounceSignal,
+    reasoningEffort,
+    speed,
+    contextMax,
+    reducedMotion: reduced
+  }
+  useLayoutEffect(() => {
+    if (!handoff) return undefined
+    const el = rootRef.current
+    if (!el) return undefined
+    let timer = 0
+    const dy = reduced ? null : consumeMascotHandoff(el)
+    if (dy != null) {
+      const rising = dy > 0
+      el.style.transition = 'none'
+      el.style.transform = `translateY(${dy}px)`
+      void el.offsetHeight
+      el.style.transition = rising
+        ? 'transform 420ms cubic-bezier(0.34, 1.56, 0.64, 1)'
+        : 'transform 300ms cubic-bezier(0.55, 0, 0.8, 0.9)'
+      el.style.transform = 'translateY(0)'
+      if (rising) setStartled(true)
+      timer = window.setTimeout(() => {
+        el.style.transition = ''
+        el.style.transform = ''
+        if (!rising) setLanding(true)
+      }, rising ? 430 : 310)
+    }
+    return () => {
+      window.clearTimeout(timer)
+      recordMascotHandoff(el)
+    }
+  }, [handoff])
+
+  const previousAnchorOffsetRef = useRef(anchorOffset)
+  useLayoutEffect(() => {
+    const el = rootRef.current
+    const previousOffset = previousAnchorOffsetRef.current
+    previousAnchorOffsetRef.current = anchorOffset
+    if (!el || previousOffset === anchorOffset || reduced) return undefined
+
+    if (anchorOffset > previousOffset) {
+
+      el.style.transition = ''
+      el.style.transform = ''
+      setLanding(false)
+      return undefined
+    }
+
+    const currentVisualTop = el.getBoundingClientRect().top
+    const offsetDelta = anchorOffset - previousOffset
+    el.style.transition = 'none'
+    el.style.transform = ''
+    const targetTop = el.getBoundingClientRect().top
+    const dy = currentVisualTop + offsetDelta - targetTop
+    if (Math.abs(dy) < 1) return undefined
+
+    const rising = dy > 0
+    let timer = 0
+    el.style.transform = `translateY(${dy}px)`
+    void el.offsetHeight
+    el.style.transition = rising
+      ? 'transform 420ms cubic-bezier(0.34, 1.56, 0.64, 1)'
+      : 'transform 300ms cubic-bezier(0.55, 0, 0.8, 0.9)'
+    el.style.transform = 'translateY(0)'
+    if (rising) {
+      setStartled(true)
+    } else {
+
+      setStartled(false)
+      setPushLift(false)
+    }
+    timer = window.setTimeout(() => {
+      el.style.transition = ''
+      el.style.transform = ''
+      if (!rising) setLanding(true)
+    }, rising ? 430 : 310)
+
+    return () => window.clearTimeout(timer)
+  }, [anchorOffset])
+
+  const previousAnchorPushSignalRef = useRef(anchorPushSignal)
+  useEffect(() => {
+    if (anchorPushSignal === previousAnchorPushSignalRef.current) return
+    previousAnchorPushSignalRef.current = anchorPushSignal
+    if (!reduced) setPushLift(true)
+  }, [anchorPushSignal])
+
+  const prevBounceRef = useRef(bounceSignal)
+  useEffect(() => {
+    if (bounceSignal === prevBounceRef.current) return
+    prevBounceRef.current = bounceSignal
+    if (!reduced) setLaunching(true)
+  }, [bounceSignal])
+
+  const prevLightRef = useRef(light)
+  useEffect(() => {
+    const prev = prevLightRef.current
+    prevLightRef.current = light
+    if (light === prev || reduced) return
+    if (light === 'success') {
+      setCheering(true)
+      setSparkling(true)
+    } else if (light === 'error') {
+      setShaking(true)
+    }
+  }, [light])
+
+  useEffect(() => {
+    if (!ambient || reduced) {
+      setSleeping(false)
+      return
+    }
+    if (sleeping || idle.activeIdle) return
+    const timer = window.setTimeout(() => setSleeping(true), MASCOT_SLEEP_AFTER_MS)
+    return () => window.clearTimeout(timer)
+  }, [ambient, idle.activityRevision, sleeping, idle.activeIdle, reduced])
+
+  const wake = useCallback(() => {
+    setSleeping(false)
+    if (!reduced) setStartled(true)
+  }, [reduced])
+
+  useEffect(() => {
+    if (!waving) return
+    const timer = window.setTimeout(() => setWaving(false), MASCOT_WAVE_DURATION_MS)
+    return () => window.clearTimeout(timer)
+  }, [waving])
+
+  useEffect(() => {
+    if (!focused || reduced) return
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.ctrlKey || event.metaKey || event.altKey) return
+      setNodding(true)
+    }
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [focused, reduced])
+
+  const onAnimationEnd = (event: AnimationEvent<HTMLDivElement>): void => {
+    idle.onAnimationEnd(event)
+    switch (event.animationName) {
+      case 'composer-mascot-launch':
+        setLaunching(false)
+        break
+      case 'composer-mascot-cheer':
+        setCheering(false)
+        break
+      case 'composer-mascot-sparkle':
+        setSparkling(false)
+        break
+      case 'composer-mascot-shake':
+        setShaking(false)
+        break
+      case 'composer-mascot-startle':
+        setStartled(false)
+        break
+      case 'composer-mascot-nod':
+        setNodding(false)
+        break
+      case 'composer-mascot-land':
+        setLanding(false)
+        break
+      case 'composer-mascot-push-lift':
+        setPushLift(false)
+        break
+    }
+  }
+
+  const poseTransform = sleeping
+    ? 'translateY(2px) rotate(2.6deg) scale(0.985)'
+    : light === 'error'
+      ? 'translateY(2px) rotate(-3deg) scale(0.98)'
+      : focused
+        ? 'scale(1.1)'
+        : 'scale(1)'
+
+  const shotClass = cheering
+    ? 'composer-mascot-cheer'
+    : shaking
+      ? 'composer-mascot-shake'
+      : pushLift
+        ? 'composer-mascot-push-lift'
+      : startled
+        ? 'composer-mascot-startle'
+        : landing
+          ? 'composer-mascot-land'
+          : launching
+            ? 'composer-mascot-launch'
+            : nodding
+              ? 'composer-mascot-nod'
+              : undefined
+
+  const loopClass = sleeping
+    ? 'composer-mascot-sleep-breathe'
+    : dragOver
+      ? 'composer-mascot-eager'
+      : baseExpression === 'operator' && light === 'default'
+        ? 'composer-mascot-think'
+        : 'composer-mascot-breathe'
+
+  const rootClassName =
+    [
+      idle.className,
+      sleeping ? 'composer-mascot-sleeping' : null,
+    ]
+      .filter(Boolean)
+      .join(' ') || undefined
+
+  const character = <Avatar name={avatar ?? ''} size={MASCOT_SIZE} state={avatarBehavior.pose}
+    expression={avatarBehavior.expression} gesture={avatarBehavior.gesture}
+    gestureSequence={avatarBehavior.gestureSequence} onGestureComplete={avatarBehavior.completeGesture}
+    eventSequence={bounceSignal + greetingSequence} motion={reduced ? 'off' : 'on'} />
+  return (
+    <div
+
+      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 ?? ''}
+      data-mascot-theme={theme}
+      data-mascot-effort={reasoningEffort}
+      data-mascot-speed={speed}
+      data-mascot-context={contextMax ? 'max' : 'default'}
+      data-mascot-profile-transition={profileTransition ? 'active' : 'idle'}
+      {...idle.attributes}
+      data-mascot-anchor-offset={anchorOffset}
+      onAnimationEnd={onAnimationEnd}
+      style={{
+        '--mascot-body-dark': mascotPalette.bodyD,
+        '--mascot-body-mid': mascotPalette.bodyM,
+        '--mascot-body-light': mascotPalette.bodyL,
+        '--mascot-mark-dark': mascotPalette.markD,
+        '--mascot-mark-energy': mascotPalette.markM,
+        '--mascot-energy-accent': mascotPalette.accent,
+        '--mascot-profile-from-accent': profileTransition?.fromAccent ?? mascotPalette.accent,
+        '--mascot-profile-to-accent': profileTransition?.toAccent ?? mascotPalette.accent,
+        position: 'absolute',
+        right: '40px',
+        top: `${-(MASCOT_SIZE * (1 - MASCOT_HIDDEN_RATIO)) - MASCOT_RAISE - anchorOffset}px`,
+        zIndex: 0,
+        pointerEvents: 'none'
+      } as CSSProperties}
+    >
+      {bubble && (
+        <div
+          style={{
+            position: 'absolute',
+            right: 0,
+            bottom: 'calc(100% + 8px)',
+            zIndex: 5,
+            pointerEvents: 'auto'
+          }}
+        >
+          {bubble}
+        </div>
+      )}
+      <div
+        key={profileTransitionRevision}
+        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 ? `composer-mascot-lift ${shotClass}` : 'composer-mascot-lift'}>
+            <div className={`composer-mascot-body ${loopClass}`}>
+              <div
+                className="composer-mascot-jelly composer-mascot-trail"
+                style={{ pointerEvents: 'auto', cursor: hasMenu ? 'context-menu' : undefined }}
+                onMouseEnter={sleeping ? wake : undefined}
+                onClick={() => {
+                  if (sleeping) {
+                    wake()
+                    return
+                  }
+                  if (!reduced) {
+                    setWaving(true)
+                    setGreetingSequence((value) => value + 1)
+                  }
+                }}
+                onContextMenu={
+                  hasMenu
+                    ? (e) => {
+                        e.preventDefault()
+                        setMenuPos({ x: e.clientX, y: e.clientY })
+                      }
+                    : undefined
+                }
+              >
+                <div className="composer-mascot-fast-echo">
+                  <div className="composer-mascot-character-stage">
+                    {renderCharacter ? renderCharacter(character, context) : character}
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {sleeping && (
+          <div aria-hidden className="composer-mascot-zzz">
+            <span>z</span>
+            <span>z</span>
+            <span>z</span>
+          </div>
+        )}
+        {sparkling && (
+          <div aria-hidden className="composer-mascot-sparkles">
+            {MASCOT_SPARKLES.map((s, i) => (
+              <i
+                key={i}
+                style={{ '--dx': s.dx, '--dy': s.dy, animationDelay: s.delay } as CSSProperties}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+
+      {menuPos && renderMenu?.(menuPos, () => setMenuPos(null))}
+    </div>
+  )
+}

package/src/composer/ComposerMascotShadow.tsx

@@ -0,0 +1,5 @@
+import { deriveAppearance, mascotPaletteOf } from '../index.js'
+export function ComposerMascotShadow({ name = '' }: { name?: string }) {
+  const palette = mascotPaletteOf(deriveAppearance(name))
+  return <div aria-hidden className="composer-mascot-contact-shadow" style={{ background: `radial-gradient(50% 100% at 50% 0%, color-mix(in srgb, ${palette.shadow} 10%, transparent) 0%, transparent 72%)` }} />
+}

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>
+  )
+}