@dotcraft/avatar 0.6.3 → 0.6.5

package/src/decorationCatalog.ts

@@ -0,0 +1,45 @@
+import { compatibility, primaryIds, type DecorationId, type PrimaryId, type SecondaryId } from './appearanceModel.js'
+
+export interface Decoration {
+  id: DecorationId
+  name: string
+  category: 'Hats' | 'Novelty' | 'Accessories'
+  feature: string
+  colors: readonly string[]
+  mount: string
+}
+export const decorations: Decoration[] = [
+  { id: 'baseball-cap', name: 'Baseball cap', category: 'Hats', feature: 'Rounded crown with a short right-facing brim', colors: ['#e87967', '#b94f50', '#f5a18c'], mount: 'Crown overlaps the top edge; the brim stays inside the body' },
+  { id: 'bucket-hat', name: 'Bucket hat', category: 'Hats', feature: 'Flat top with a continuous downward brim', colors: ['#94bda6', '#5b887a', '#bed8c1'], mount: 'Brim follows the top edge with a slight center overlap' },
+  { id: 'beret', name: 'Beret', category: 'Hats', feature: 'Soft left-leaning crown with a short stem', colors: ['#b17498', '#784c71', '#cf9db5'], mount: 'Narrow band rests on top; the crown leans left' },
+  { id: 'beanie', name: 'Beanie', category: 'Hats', feature: 'Rounded crown and wide folded cuff with minimal texture', colors: ['#e9a653', '#bc753d', '#f7c676'], mount: 'Folded cuff sits on the top edge; crown stays centered' },
+  { id: 'top-hat', name: 'Top hat', category: 'Hats', feature: 'Tall crown, narrow brim, and burgundy band', colors: ['#465069', '#293247', '#c96e85'], mount: 'Narrow brim rests flat on top; crown tapers at its base' },
+  { id: 'wizard-hat', name: 'Wizard hat', category: 'Hats', feature: 'Curved point, wide brim, and gold star', colors: ['#8773c1', '#594b93', '#f4cc75'], mount: 'Wide brim rests on top; point curves into the center safe area' },
+  { id: 'chef-hat', name: 'Chef hat', category: 'Hats', feature: 'Three-lobed puff with an upright band', colors: ['#f5eee3', '#d7caba', '#fffaf1'], mount: 'Band rests at the center of the top edge' },
+  { id: 'party-hat', name: 'Party hat', category: 'Hats', feature: 'Cone with two colored bands and a pom-pom', colors: ['#ea9baf', '#8075b7', '#f5d07b'], mount: 'Shallow curved base follows the top of the body' },
+  { id: 'crown', name: 'Crown', category: 'Hats', feature: 'Three rounded points with a central sapphire', colors: ['#efc65c', '#c99139', '#73b8cc'], mount: 'Curved gold band wraps the top edge; all points face up' },
+  { id: 'hard-hat', name: 'Hard hat', category: 'Hats', feature: 'Rounded shell, center ridge, and short front brim', colors: ['#f5bd48', '#d68d32', '#ffdc79'], mount: 'Short brim overlaps the top edge; ridge stays centered' },
+  { id: 'nightcap', name: 'Nightcap', category: 'Hats', feature: 'Soft drooping point with a pom-pom', colors: ['#789cc9', '#4c709f', '#dce8f4'], mount: 'Soft band follows the top edge; pom-pom stays upper right' },
+  { id: 'straw-hat', name: 'Straw hat', category: 'Hats', feature: 'Low round crown, wide oval brim, and red band', colors: ['#e8c78a', '#c49b5e', '#c57568'], mount: 'Wide brim rests flat without entering the arm areas' },
+  { id: 'poop', name: 'Poop', category: 'Novelty', feature: 'Three rounded layers with a playful curled tip', colors: ['#a97b5f', '#805840', '#c49976'], mount: 'Wide bottom layer rests directly on top; color separates each layer' },
+  { id: 'banana', name: 'Banana', category: 'Novelty', feature: 'Crescent fruit with stems and an inner color plane', colors: ['#f3cf62', '#dbaa40', '#89705a'], mount: 'Outer curve touches the top; both stems point up' },
+  { id: 'fried-egg', name: 'Fried egg', category: 'Novelty', feature: 'Irregular rounded white with a raised golden yolk', colors: ['#fff9e8', '#e6d9bb', '#f3be43'], mount: 'White spreads across the top; raised yolk defines the silhouette' },
+  { id: 'rubber-duck', name: 'Rubber duck', category: 'Novelty', feature: 'Round head, flat orange bill, and short raised tail', colors: ['#f6d05e', '#e4ae3e', '#e58b4b'], mount: 'Belly rests flat on top, with bill left and tail right' },
+  { id: 'paper-boat', name: 'Paper boat', category: 'Novelty', feature: 'Folded hull with a central triangular plane', colors: ['#d6e7eb', '#92b5c1', '#f1f7f5'], mount: 'Folded hull edge rests on top; main fold stays centered' },
+  { id: 'traffic-cone', name: 'Traffic cone', category: 'Novelty', feature: 'Orange cone with a white band and flat base', colors: ['#ed985f', '#c96c43', '#fff0dd'], mount: 'Flat base rests on top; cone tapers upward' },
+  { id: 'sprout', name: 'Sprout', category: 'Novelty', feature: 'Short stem with two leaves pointing in different directions', colors: ['#89b875', '#537f59', '#b5d38f'], mount: 'Stem grows directly from the top edge without a pot or base' },
+  { id: 'donut', name: 'Donut', category: 'Novelty', feature: 'Clear center hole, half-ring of icing, and a few sprinkles', colors: ['#dbab70', '#bf8456', '#e5a0b3'], mount: 'Lower curve touches the top; center remains an open cutout' },
+  { id: 'forehead-goggles', name: 'Forehead goggles', category: 'Accessories', feature: 'Two blue-gray lenses with a center bridge', colors: ['#8b7568', '#a2c5d1', '#dec8ae'], mount: 'Fits within the forehead band; bridge anchors above the screen' },
+  {"id":"task-board","name":"Task board","category":"Accessories","feature":"White planning board with connected role-color markers and a yellow accent","colors":["#ffffff","#3161f7","#f6b500"],"mount":"Screen-left hand; shares the arm pivot, stows for laptop and question sign, then restores"},
+  {"id":"wrench","name":"Wrench","category":"Accessories","feature":"White open-ended wrench with role-color outlines and a yellow handle inset","colors":["#ffffff","#3161f7","#f6b500"],"mount":"Screen-left hand; shares the arm pivot, stows for laptop and question sign, then restores"},
+  {"id":"shield","name":"Shield","category":"Accessories","feature":"White shield with a role-color outline and upright check","colors":["#ffffff","#3161f7","#f6b500"],"mount":"Screen-left hand; shares the arm pivot, stows for laptop and question sign, then restores"},
+  {"id":"magnifier","name":"Magnifier","category":"Accessories","feature":"Upright white lens frame with a role-color outline and a lower grip","colors":["#ffffff","#3161f7","#f6b500"],"mount":"Screen-left hand; shares the arm pivot, stows for laptop and question sign, then restores"},
+  {"id":"control-panel","name":"Control panel","category":"Accessories","feature":"White control panel with dark rails and role-color and yellow knobs","colors":["#ffffff","#3161f7","#f6b500"],"mount":"Screen-left hand; shares the arm pivot, stows for laptop and question sign, then restores"},
+]
+export const decorationOf = (id: DecorationId) => decorations.find(item => item.id === id)!
+export const decorationName = (id: PrimaryId | SecondaryId) => id === 'none' ? 'None' : decorationOf(id).name
+export function compatibleNames(item: Decoration) {
+  return item.category === 'Accessories'
+    ? primaryIds.filter(id => compatibility[id].includes(item.id as SecondaryId)).map(decorationName).join(', ')
+    : compatibility[item.id as PrimaryId].map(decorationName).join(', ')
+}

package/src/decorationMotion.ts

@@ -0,0 +1,68 @@
+import type { PrimaryId } from './appearanceModel.js'
+import type { AvatarPose } from './characters.js'
+
+export type MotionKind = 'lift' | 'fitted' | 'bounce' | 'rock' | 'squish' | 'sprout'
+export interface MotionProfile { kind: MotionKind; x: number; y: number; height: number; angle: number; shadow: number }
+const lift = (x = 512, y = 400): MotionProfile => ({ kind: 'lift', x, y, height: .05, angle: 3, shadow: 95 })
+const fitted = (x = 512): MotionProfile => ({ kind: 'fitted', x, y: 400, height: 0, angle: 3, shadow: 0 })
+const bounce = (x = 512): MotionProfile => ({ kind: 'bounce', x, y: 400, height: .06, angle: 5, shadow: 64 })
+export const decorationMotionProfiles: Record<Exclude<PrimaryId, 'none'>, MotionProfile> = {
+  'baseball-cap': lift(478), 'bucket-hat': lift(), beret: lift(494), beanie: fitted(),
+  'top-hat': lift(), 'wizard-hat': lift(), 'chef-hat': lift(), 'party-hat': lift(), crown: lift(),
+  'hard-hat': fitted(), nightcap: fitted(493), 'straw-hat': lift(),
+  poop: bounce(), 'rubber-duck': bounce(520), donut: { ...bounce(), shadow: 40 },
+  banana: { kind: 'rock', x: 487, y: 402, height: 0, angle: 5, shadow: 0 },
+  'paper-boat': { kind: 'rock', x: 512, y: 399, height: 0, angle: 5, shadow: 0 },
+  'traffic-cone': { kind: 'rock', x: 512, y: 399, height: 0, angle: 2.5, shadow: 0 },
+  'fried-egg': { kind: 'squish', x: 512, y: 400, height: 0, angle: 0, shadow: 0 },
+  sprout: { kind: 'sprout', x: 512, y: 399, height: 0, angle: 6, shadow: 0 },
+}
+export const motionKindLabels: Record<MotionKind, string> = {
+  lift: 'Gentle lift', fitted: 'Fitted sway', bounce: 'Bounce and settle', rock: 'Rocking response', squish: 'Soft wobble', sprout: 'Nod and unfurl',
+}
+export interface DecorationFrame { x: number; y: number; angle: number; sy: number; shadow: number }
+export const restFrame: DecorationFrame = { x: 0, y: 0, angle: 0, sy: 1, shadow: 1 }
+export function eventDuration(pose: AvatarPose) {
+  return pose === 'done' ? 800 : pose === 'greeting' ? 600 : pose === 'acknowledge' ? 350 : pose === 'blocked' ? 250 : 0
+}
+const mix = (a: number, b: number, t: number) => a + (b - a) * t
+export function mixFrame(a: DecorationFrame, b: DecorationFrame, t: number): DecorationFrame {
+  return { x: mix(a.x, b.x, t), y: mix(a.y, b.y, t), angle: mix(a.angle, b.angle, t), sy: mix(a.sy, b.sy, t), shadow: mix(a.shadow, b.shadow, t) }
+}
+export function decorationFrame(profile: MotionProfile, pose: AvatarPose, progress: number): DecorationFrame {
+  const t = Math.max(0, Math.min(1, progress))
+  if (!eventDuration(pose) || t === 0 || t === 1) return { ...restFrame }
+  // Convert a fraction of displayed avatar height into the production rig's 1.3x brand coordinates.
+  if (pose === 'blocked') return { ...restFrame, x: Math.sin(t * Math.PI * 6) * (1 - t) * 1024 / 1.3 * .008 }
+  const strength = pose === 'acknowledge' ? 1 / 3 : pose === 'greeting' ? .65 : 1
+  const sway = Math.sin(t * Math.PI * 2) * Math.sin(t * Math.PI) * strength
+  if (profile.kind === 'squish') return { ...restFrame, sy: 1 - .03 * Math.sin(t * Math.PI * 2) * Math.sin(t * Math.PI) * strength }
+  if (!profile.height) return { ...restFrame, angle: profile.angle * sway }
+  let liftAmount: number
+  if (t < .38) liftAmount = 1 - (1 - t / .38) ** 3
+  else if (t < .46) liftAmount = 1
+  else if (t < .82) liftAmount = 1 - ((t - .46) / .36) ** 2
+  else liftAmount = profile.kind === 'bounce' ? Math.sin((t - .82) / .18 * Math.PI) * .08 : 0
+  return { ...restFrame, y: -liftAmount * profile.height * 1024 / 1.3 * strength,
+    angle: profile.angle * sway, shadow: 1 - liftAmount * .45 * strength }
+}
+export interface DecorationClock { phase: 'return' | 'event' | 'rest'; elapsed: number; pose: AvatarPose; from: DecorationFrame; frame: DecorationFrame }
+export function requestDecorationEvent(current: DecorationClock | null, pose: AvatarPose): DecorationClock {
+  const from = current?.frame ?? restFrame
+  const displaced = Math.abs(from.x) + Math.abs(from.y) + Math.abs(from.angle) + Math.abs(from.sy - 1) > .0001
+  return { phase: displaced ? 'return' : eventDuration(pose) ? 'event' : 'rest', elapsed: 0, pose, from, frame: { ...from } }
+}
+export function advanceDecoration(clock: DecorationClock, profile: MotionProfile, delta: number, paused = false): DecorationClock {
+  if (paused || clock.phase === 'rest') return clock
+  let elapsed = clock.elapsed + Math.max(0, delta)
+  if (clock.phase === 'return') {
+    if (elapsed < 160) return { ...clock, elapsed, frame: mixFrame(clock.from, restFrame, 1 - (1 - elapsed / 160) ** 3) }
+    elapsed -= 160
+  }
+  const duration = eventDuration(clock.pose)
+  if (!duration || elapsed >= duration) return { ...clock, phase: 'rest', elapsed: 0, frame: { ...restFrame } }
+  return { ...clock, phase: 'event', elapsed, frame: decorationFrame(profile, clock.pose, elapsed / duration) }
+}
+export function frameTransform(profile: MotionProfile, frame: DecorationFrame) {
+  return `translate(${frame.x} ${frame.y}) translate(${profile.x} ${profile.y}) rotate(${frame.angle}) scale(1 ${frame.sy}) translate(${-profile.x} ${-profile.y})`
+}

package/src/environment.ts

@@ -0,0 +1,46 @@
+import { useEffect, useState, type RefObject } from 'react'
+import type { MotionMode } from './characters.js'
+
+export function useMotionEnvironment(mode: MotionMode, observe = true) {
+  const [reduced, setReduced] = useState(true)
+  useEffect(() => {
+    if (!observe || mode === 'off' || typeof window.matchMedia !== 'function') return
+    const media = window.matchMedia('(prefers-reduced-motion: reduce)')
+    const update = () => setReduced(media.matches)
+    update()
+    media.addEventListener('change', update)
+    return () => media.removeEventListener('change', update)
+  }, [mode, observe])
+  return observe && (mode === 'on' || (mode === 'system' && !reduced))
+}
+
+export function useOnscreen(ref: RefObject<Element | null>, observe = true) {
+  const [visible, setVisible] = useState(true)
+  useEffect(() => {
+    if (!observe) return
+    let intersects = true
+    const update = () => setVisible(intersects && !document.hidden)
+    const observer = typeof IntersectionObserver === 'undefined' ? undefined
+      : new IntersectionObserver(([entry]) => { intersects = entry.isIntersecting; update() })
+    if (ref.current) observer?.observe(ref.current)
+    document.addEventListener('visibilitychange', update)
+    update()
+    return () => { observer?.disconnect(); document.removeEventListener('visibilitychange', update) }
+  }, [ref, observe])
+  return visible
+}
+
+export function useTransitionPause(ref: RefObject<Element | null>, paused: boolean) {
+  useEffect(() => {
+    if (!paused) return
+    // CSS play-state freezes keyframes; Web Animations also freezes in-flight arm transitions.
+    const transitions = ref.current?.getAnimations?.({ subtree: true })
+      .filter(animation => typeof (animation as CSSTransition).transitionProperty === 'string') ?? []
+    transitions.forEach(animation => animation.pause())
+    return () => {
+      transitions.forEach(animation => {
+        if (ref.current?.isConnected && animation.playState === 'paused') animation.play()
+      })
+    }
+  }, [ref, paused])
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './appearanceModel.js'
+export * from './characters.js'
+export * from './palette.js'
+export * from './decorationCatalog.js'
+export * from './decorationMotion.js'

package/src/palette.ts

@@ -0,0 +1,52 @@
+export interface PaletteEntry {
+  key: string
+  bodyD: string
+  bodyM: string
+  bodyL: string
+  markD: string
+  markL: string
+  shadow: string
+  accent: string
+}
+
+/** Complete paint vocabulary used by the Composer mascot. */
+export interface MascotPaintPalette extends PaletteEntry {
+  /** Middle face-mark stop; profile palettes intentionally reuse `markL`. */
+  markM: string
+}
+
+/** Canonical DotCraft mascot paint when no Agent Profile is selected. */
+export const DEFAULT_MASCOT_PALETTE: MascotPaintPalette = {
+  key: 'default',
+  bodyD: '#2458f7',
+  bodyM: '#5f82f7',
+  bodyL: '#8fa5ff',
+  markD: '#2257f5',
+  markM: '#577df7',
+  markL: '#8ca2ff',
+  shadow: '#0b3d62',
+  accent: '#5f82f7'
+}
+
+/** 12 role palettes. The first five define the built-in Agent Profile roles. */
+export const PALETTE: PaletteEntry[] = [
+  { key: 'blue', bodyD: '#2563eb', bodyM: '#4f7cf6', bodyL: '#8198f5', markD: '#2563eb', markL: '#6f8df5', shadow: '#07307c', accent: '#4f7cf6' },
+  { key: 'indigo', bodyD: '#4f46e5', bodyM: '#6366f1', bodyL: '#8b8ff8', markD: '#3730a3', markL: '#818cf8', shadow: '#1e1b4b', accent: '#6366f1' },
+  { key: 'violet', bodyD: '#6d28d9', bodyM: '#8b5cf6', bodyL: '#a78bfa', markD: '#5b21b6', markL: '#a78bfa', shadow: '#4c1d95', accent: '#8b5cf6' },
+  { key: 'fuchsia', bodyD: '#a21caf', bodyM: '#d946ef', bodyL: '#e9a8f5', markD: '#86198f', markL: '#e879f9', shadow: '#581c87', accent: '#d946ef' },
+  { key: 'pink', bodyD: '#be185d', bodyM: '#ec4899', bodyL: '#f9a8d4', markD: '#9d174d', markL: '#f472b6', shadow: '#831843', accent: '#ec4899' },
+  { key: 'rose', bodyD: '#be123c', bodyM: '#f43f5e', bodyL: '#fda4af', markD: '#9f1239', markL: '#fb7185', shadow: '#881337', accent: '#f43f5e' },
+  { key: 'orange', bodyD: '#c2410c', bodyM: '#f97316', bodyL: '#fdba74', markD: '#9a3412', markL: '#fb923c', shadow: '#7c2d12', accent: '#f97316' },
+  { key: 'amber', bodyD: '#d97706', bodyM: '#eab308', bodyL: '#fbbf24', markD: '#92400e', markL: '#f59e0b', shadow: '#78350f', accent: '#f59e0b' },
+  { key: 'lime', bodyD: '#4d7c0f', bodyM: '#84cc16', bodyL: '#bef264', markD: '#3f6212', markL: '#a3e635', shadow: '#365314', accent: '#84cc16' },
+  { key: 'green', bodyD: '#15803d', bodyM: '#22c55e', bodyL: '#4ade80', markD: '#166534', markL: '#4ade80', shadow: '#14532d', accent: '#22c55e' },
+  { key: 'teal', bodyD: '#0f766e', bodyM: '#14b8a6', bodyL: '#5eead4', markD: '#115e59', markL: '#2dd4bf', shadow: '#134e4a', accent: '#14b8a6' },
+  { key: 'sky', bodyD: '#0284c7', bodyM: '#0ea5e9', bodyL: '#38bdf8', markD: '#0369a1', markL: '#22d3ee', shadow: '#075985', accent: '#0ea5e9' }
+]
+
+
+export function paletteOf(spec: { palette: number }): PaletteEntry { return PALETTE[spec.palette] ?? DEFAULT_MASCOT_PALETTE }
+export function mascotPaletteOf(spec?: { palette: number }): MascotPaintPalette {
+ if (!spec || spec.palette === -1) return DEFAULT_MASCOT_PALETTE
+ const paint = paletteOf(spec); return { ...paint, markM: paint.markL }
+}

package/src/react.ts

@@ -0,0 +1,11 @@
+export { Avatar, AppearanceAvatar, type AvatarProps, type AppearanceAvatarProps } from './Avatar.js'
+export { DecorationSwatch, PrimaryDecoration, SecondaryDecoration } from './Decorations.js'
+
+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'

package/src/rig.css

@@ -0,0 +1,265 @@
+/* The robot's arm/antenna/face pieces carry stable dca-part-* classes (see
+   MascotRig.tsx). Each arm's white and blue pieces are separate elements moving in
+   lockstep, so transform-box: view-box resolves one shared origin for both. */
+.dca-part-eyes,
+.dca-part-glow,
+.dca-part-light,
+.dca-part-face {
+  transform-box: fill-box;
+}
+
+/* The incoming face waits out a ~70ms blank beat so two faces never blend into a
+   double exposure. */
+.dca-part-face {
+  opacity: 0;
+  transition: opacity 110ms ease;
+}
+
+.dca-part-robot[data-expression='neutral'] .dca-part-face-neutral,
+.dca-part-robot[data-expression='happy'] .dca-part-face-happy,
+.dca-part-robot[data-expression='operator'] .dca-part-face-operator,
+.dca-part-robot[data-expression='sleep'] .dca-part-face-sleep {
+  opacity: 1;
+  transition: opacity 150ms ease 70ms;
+}
+
+.dca-part-eyes {
+  transform-origin: center;
+}
+
+.dca-part-glow {
+  opacity: 0;
+  transform-origin: center;
+}
+
+.dca-part-light {
+  transform-origin: center;
+}
+
+/* The default 140ms transition-delay sequences "prop first, arm after" on retract, so
+   a prop is never left floating. Every rule that ENTERS a posed arm state overrides
+   the delay back to 0 so raises stay immediate. */
+.dca-part-arm-l-w,
+.dca-part-arm-l {
+  transform-box: view-box;
+  transform-origin: 233px 514px;
+  transition: transform 320ms cubic-bezier(0.34, 1.56, 0.64, 1) 140ms;
+}
+
+.dca-part-arm-r-w,
+.dca-part-arm-r-b {
+  transform-box: view-box;
+  transform-origin: 791px 514px;
+  transition: transform 320ms cubic-bezier(0.34, 1.56, 0.64, 1) 140ms;
+}
+
+/* Every keyframe keeps the same function list (translate + rotate + scaleY) so the
+   interpolation stays smooth. translate dy=88 lands the hinge at ≈602 viewBox, the
+   height of the resting arm nub, so the hand lifts from where the arm already is. */
+@keyframes dca-action-wave-arm {
+  0% {
+    transform: translate(0, 0) rotate(0) scaleY(1);
+  }
+  16% {
+    transform: translate(-48px, 88px) rotate(-122deg) scaleY(0.8);
+  }
+  32% {
+    transform: translate(-48px, 88px) rotate(-92deg) scaleY(0.8);
+  }
+  48% {
+    transform: translate(-48px, 88px) rotate(-122deg) scaleY(0.8);
+  }
+  64% {
+    transform: translate(-48px, 88px) rotate(-92deg) scaleY(0.8);
+  }
+  80% {
+    transform: translate(-48px, 88px) rotate(-114deg) scaleY(0.8);
+  }
+  100% {
+    transform: translate(0, 0) rotate(0) scaleY(1);
+  }
+}
+
+@keyframes dca-action-wave-lean {
+  0%,
+  100% {
+    transform: rotate(0);
+  }
+  20%,
+  80% {
+    transform: rotate(3deg);
+  }
+}
+
+.dca-action-wave .dca-part-arm-r-w,
+.dca-action-wave .dca-part-arm-r-b {
+  animation: dca-action-wave-arm 1.6s ease-in-out both;
+}
+
+.dca-action-wave .dca-action-jelly {
+  animation: dca-action-wave-lean 1.6s ease-in-out both;
+}
+
+/* Props are always-mounted `dca-part-prop-*` groups inside MascotRobot at opacity 0,
+   revealed by these composer root classes. */
+
+/* Mini terminal: the 1200ms transition delay keeps quick turns from flashing it. The
+   arms only tuck inward by pure translate — a rotation would trigger the solid-colour
+   swap and break the gradient's continuity with the torso. */
+.dca-part-prop-laptop {
+  opacity: 0;
+  transition: opacity 200ms ease;
+}
+
+.dca-action-prop-laptop .dca-part-prop-laptop {
+  opacity: 1;
+  transition: opacity 240ms ease 1200ms;
+}
+
+.dca-action-prop-laptop .dca-part-arm-l-w,
+.dca-action-prop-laptop .dca-part-arm-l {
+  transform: translate(18px, 0);
+  transition: transform 320ms cubic-bezier(0.34, 1.56, 0.64, 1) 1200ms;
+}
+
+.dca-action-prop-laptop .dca-part-arm-r-w,
+.dca-action-prop-laptop .dca-part-arm-r-b {
+  transform: translate(-18px, 0);
+  transition: transform 320ms cubic-bezier(0.34, 1.56, 0.64, 1) 1200ms;
+}
+
+@keyframes dca-action-laptop-scroll {
+  0%,
+  58% {
+    transform: translateY(0);
+  }
+  66%,
+  100% {
+    transform: translateY(-36px);
+  }
+}
+
+.dca-action-prop-laptop .dca-part-laptop-lines {
+  animation: dca-action-laptop-scroll 2200ms ease-in-out 1640ms infinite;
+}
+
+@keyframes dca-action-laptop-caret {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0;
+  }
+}
+
+.dca-action-prop-laptop .dca-part-laptop-caret {
+  animation: dca-action-laptop-caret 800ms steps(1, end) infinite;
+}
+
+/* The sign fades in only after the arm settles (320ms spring plus a beat), and on
+   retract it hides first while the arm waits out its 140ms transition-delay, so the
+   prop is never left floating without a hand. */
+.dca-action-hold-sign .dca-part-arm-r-w,
+.dca-action-hold-sign .dca-part-arm-r-b {
+  transform: translate(-48px, 88px) rotate(-128deg) scaleY(0.8);
+  transition-delay: 0ms;
+}
+
+.dca-action-hold-sign .dca-part-arm-r-b {
+  fill: var(--dca-part-raised-arm-right, #7a96fb);
+}
+
+.dca-part-prop-sign {
+  opacity: 0;
+  transition: opacity 140ms ease;
+}
+
+.dca-action-hold-sign .dca-part-prop-sign {
+  opacity: 1;
+  transition: opacity 180ms ease 340ms;
+}
+
+/* Click greeting while the sign is held: only the angle moves, and it starts and ends
+   exactly at the held pose so the hand-off to .dca-action-hold-sign is seamless.
+   The compound selector outranks the lone .dca-action-wave arm rule. */
+@keyframes dca-action-sign-wave-arm {
+  0% {
+    transform: translate(-48px, 88px) rotate(-128deg) scaleY(0.8);
+  }
+  18% {
+    transform: translate(-48px, 88px) rotate(-143deg) scaleY(0.8);
+  }
+  42% {
+    transform: translate(-48px, 88px) rotate(-113deg) scaleY(0.8);
+  }
+  66% {
+    transform: translate(-48px, 88px) rotate(-143deg) scaleY(0.8);
+  }
+  86% {
+    transform: translate(-48px, 88px) rotate(-120deg) scaleY(0.8);
+  }
+  100% {
+    transform: translate(-48px, 88px) rotate(-128deg) scaleY(0.8);
+  }
+}
+
+/* Pure rotation about the hand's pivot: the shoulder hinge (791,514) shifted by the
+   held translate (-48,88), i.e. C = (743,602), by exactly the arm's angular deviation
+   from -128° at each step. Same centre and delta keeps the board gripped. */
+@keyframes dca-action-sign-wave-prop {
+  0% {
+    transform: rotate(0deg);
+  }
+  18% {
+    transform: rotate(-15deg);
+  }
+  42% {
+    transform: rotate(15deg);
+  }
+  66% {
+    transform: rotate(-15deg);
+  }
+  86% {
+    transform: rotate(8deg);
+  }
+  100% {
+    transform: rotate(0deg);
+  }
+}
+
+.dca-action-hold-sign.dca-action-wave .dca-part-arm-r-w,
+.dca-action-hold-sign.dca-action-wave .dca-part-arm-r-b {
+  animation: dca-action-sign-wave-arm 1.6s ease-in-out;
+}
+
+.dca-action-hold-sign.dca-action-wave .dca-part-prop-sign {
+  transform-box: view-box;
+  transform-origin: 743px 602px;
+  animation: dca-action-sign-wave-prop 1.6s ease-in-out;
+}
+
+/* The cheer reuses the wave's slide-then-rotate hinge grammar, so the outline wraps
+   the band and the colour stays seam-continuous. */
+.dca-action-celebrate .dca-part-arm-l-w,
+.dca-action-celebrate .dca-part-arm-l {
+  transform: translate(48px, 88px) rotate(135deg) scaleY(0.82);
+  transition-delay: 0ms;
+}
+
+.dca-action-celebrate .dca-part-arm-r-w,
+.dca-action-celebrate .dca-part-arm-r-b {
+  transform: translate(-48px, 88px) rotate(-135deg) scaleY(0.82);
+  transition-delay: 0ms;
+}
+
+/* Raised arms swap the body gradient for a solid hinge colour, so a rotated arm has
+   no gradient to diverge from the torso's field. White halo capsules stay white. */
+.dca-action-wave .dca-part-arm-r-b,
+.dca-action-celebrate .dca-part-arm-r-b {
+  fill: var(--dca-part-raised-arm-right, #7a96fb);
+}
+
+.dca-action-celebrate .dca-part-arm-l-b {
+  fill: var(--dca-part-raised-arm-left, #3161f7);
+}

package/src/styles.css

@@ -0,0 +1,13 @@
+@import './rig.css';
+@import './avatar.css';
+@import './accessories.css';
+
+@import "./composer/styles/foundation.css";
+@import "./composer/styles/overdrive.css";
+@import "./composer/styles/idle.css";
+@import "./composer/styles/focus.css";
+@import "./composer/styles/expressions.css";
+@import "./composer/styles/feedback.css";
+@import "./composer/styles/props.css";
+
+@import "./composer/styles/energy.css";

package/src/useEventReplay.ts

@@ -0,0 +1,13 @@
+import { useEffect, useRef, type RefObject } from 'react'
+
+const eventAnimations = new Set(['dca-celebrate', 'dca-nod', 'dca-action-wave-arm', 'dca-action-wave-lean'])
+export function useEventReplay(ref: RefObject<Element | null>, sequence: number, enabled: boolean, paused: boolean) {
+  const previous = useRef(sequence)
+  useEffect(() => {
+    if (!enabled || paused || previous.current === sequence) return
+    previous.current = sequence
+    ref.current?.getAnimations?.({ subtree: true }).forEach(animation => {
+      if (eventAnimations.has((animation as CSSAnimation).animationName)) animation.currentTime = 0
+    })
+  }, [ref, sequence, enabled, paused])
+}

package/src/useGesture.ts

@@ -0,0 +1,51 @@
+import { useEffect, useRef, type RefObject } from 'react'
+import type { AvatarGesture } from './characters.js'
+
+const durations = { blink: 520, 'look-left': 1100, 'look-right': 1100, 'antenna-bob': 720 }
+function curve(points: readonly (readonly [number, number])[], progress: number) {
+  const next = points.findIndex(([at]) => at >= progress)
+  if (next <= 0) return points[Math.max(0, next)][1]
+  const [from, a] = points[next - 1], [to, b] = points[next]
+  const t = (progress - from) / (to - from)
+  return a + (b - a) * t * t * (3 - 2 * t)
+}
+export function useGesture(ref: RefObject<Element | null>, gesture: AvatarGesture | undefined, sequence: number,
+  enabled: boolean, paused: boolean, onComplete?: (sequence: number) => void) {
+  const clock = useRef(0)
+  const complete = useRef(onComplete)
+  const delivered = useRef(false)
+  complete.current = onComplete
+  function paint(elapsed: number) {
+    const root = ref.current
+    if (!root) return
+    const duration = gesture ? durations[gesture] : 1
+    const t = Math.min(1, elapsed / duration)
+    const active = enabled && !!gesture && t < 1
+    const eye = active && gesture === 'blink' && elapsed < 180 ? curve([[0,1],[.35,.08],[.62,.08],[1,1]], elapsed / 180) : 1
+    root.querySelectorAll<SVGElement>('.dca-part-eyes').forEach(e => { e.style.transform = `scaleY(${eye})` })
+    root.querySelectorAll<SVGElement>('.dca-part-caret').forEach(e => { e.style.opacity = active && gesture === 'blink' && Math.floor(elapsed / 130) % 2 ? '0' : '' })
+    const hold = t > .22 && t < .78 ? 1 : t >= .78 ? Math.sin(Math.PI / 2 * (1 - t) / .22) : Math.sin(Math.PI / 2 * t / .22)
+    const x = active && gesture?.startsWith('look-') ? (gesture === 'look-left' ? -34 : 34) * hold : 0
+    root.querySelector('.dca-face-motion')?.setAttribute('transform', `translate(${x} 0)`)
+    const bob = active && gesture === 'antenna-bob' ? curve([[0,0],[.3,-52],[.55,12],[.75,-16],[1,0]],t) : 0
+    root.querySelectorAll<SVGElement>('.dca-part-antenna-w,.dca-part-glow,.dca-part-light').forEach(e => { e.style.transform = `translateY(${bob}px)` })
+  }
+  useEffect(() => { clock.current = 0; delivered.current = false; paint(0) }, [gesture, sequence, enabled])
+  useEffect(() => {
+    if (!gesture || delivered.current) return
+    const finish = () => { delivered.current = true; complete.current?.(sequence) }
+    if (!enabled) { paint(durations[gesture]); finish(); return }
+    if (paused) return
+    let last: number | undefined
+    let frame = 0
+    const tick = (now: number) => {
+      clock.current += last === undefined ? 0 : now - last
+      last = now
+      paint(clock.current)
+      if (clock.current < durations[gesture]) frame = requestAnimationFrame(tick)
+      else finish()
+    }
+    frame = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(frame)
+  }, [gesture, sequence, enabled, paused])
+}