react-ai-avatar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariel A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,310 @@
+# react-ai-avatar
+
+> A presentational React avatar for realtime LLM voice UIs — **you bring the connection, it brings the face.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight, MIT-licensed React library that renders an animated avatar reacting to your AI's conversation state and audio. It is **completely LLM-agnostic**: it doesn't know about Gemini, OpenAI or ElevenLabs. You pass two live things — a `state` and (optionally) a WebAudio `AnalyserNode` — and it does the rest.
+
+```tsx
+import { RealtimeAvatar } from 'react-ai-avatar';
+import 'react-ai-avatar/style.css';
+
+// The whole thing, minimally. Everything but `state` has a sensible default.
+<RealtimeAvatar state="speaking" />
+```
+
+## Philosophy
+
+One thing, done well, embeddable in a few lines, no backend, MIT. The library handles exactly one step of your voice pipeline: turning audio amplitude + state changes into a face that visibly **listens, thinks and speaks**. Your host app keeps the microphone, the WebSocket and the AI provider — none of those dependencies enter your bundle.
+
+## Features
+
+- 👄 **Audio-reactive mouth** — analyzes amplitude and frequency bands in real time. This is deliberately *not* phoneme-perfect "lip-sync": an `AnalyserNode` gives energy, not phonemes, and for flat avatars amplitude is what looks right.
+- 🦺 **Graceful degradation** — `analyser={null}` while `state="speaking"`? The mouth animates with a synthetic speech-like pattern instead of freezing. Perfect for demos and non-WebRTC apps.
+- ⌨️ **Text-streaming LLMs too** — no audio? Drive the mouth from *token cadence* with `createSpeechActivity()`. A text-only assistant (OpenAI-style `/chat/completions` or `/responses` with `stream: true`) gets a face that visibly tracks the stream — busy while tokens arrive, settling on pauses.
+- 🧠 **A visible `thinking` state** — pulsing thought bubble + upward gaze. Your users *see* the LLM thinking, not just a color change.
+- 🎨 **Own-design avatar catalog** — `geometric`, `memoji`, `pixelart`, `doodle`: four MIT, CC0-safe SVG presets. No third-party assets, no attribution headaches.
+- 🎲 **DiceBear avatars (`dicebear`)** — generate deterministic [DiceBear](https://www.dicebear.com) avatars client-side, from a curated **CC0-only** style set (still no attribution). Animated with an audio-reactive bounce.
+- 🔌 **Bring your own SVG (`byos`)** — any SVG implementing the small layer contract gets the full animation runtime for free. Your avatar, your license.
+- ♿ **Production quality** — SSR-safe (Next.js friendly), honors `prefers-reduced-motion`, announces state changes via `aria-live`.
+- 🧊 **Optional 3D (VRM)** — `variant="vrm"` renders VRoid/VRM models with visemes and gaze tracking. The three.js stack is an *optional* peer dependency, lazy-loaded only if you use it.
+
+## Installation
+
+```bash
+npm install react-ai-avatar motion
+```
+
+`react`, `react-dom` and `motion` are peer dependencies. For the optional VRM variant, also install:
+
+```bash
+npm install three @react-three/fiber @react-three/drei @pixiv/three-vrm
+```
+
+## Quick start
+
+The only prop you *have* to pass is `state` — you resolve it in your app, the avatar never infers it. Everything else has a default, so this already works:
+
+```tsx
+import { RealtimeAvatar } from 'react-ai-avatar';
+import 'react-ai-avatar/style.css';
+
+export default function App() {
+  // You resolve this in your app (Gemini, OpenAI Realtime, WebRTC, anything)
+  const aiState = 'speaking'; // 'idle' | 'listening' | 'thinking' | 'speaking'
+
+  return <RealtimeAvatar state={aiState} />;
+}
+```
+
+With no `analyser`, `speaking` falls back to a synthetic speech-like mouth — great for getting something on screen before the audio pipeline exists. Pass an `AnalyserNode` to make the mouth react to real audio (see [Getting an `AnalyserNode`](#getting-an-analysernode)).
+
+### Customizing further
+
+Every default is overridable. Opt into as much as you need:
+
+```tsx
+<RealtimeAvatar
+  state={aiState}
+  analyser={analyser}                 // AnalyserNode | null — real audio-reactive mouth
+  size={300}                          // default 280
+  variant="geometric"                 // 'geometric' | 'memoji' | 'pixelart' | 'doodle' | 'dicebear' | 'vrm' | 'glb' | 'byos'
+  customization={{ skinColor: '#f5c7a9', hairColor: '#2c2c2c', glasses: true, headphones: true }}
+  stateColors={{ idle: '#4b5563', listening: '#3b82f6', thinking: '#8b5cf6', speaking: '#10b981' }}
+/>
+```
+
+## The avatar catalog
+
+| variant | style | notes |
+|---|---|---|
+| `geometric` | minimal flat geometry | the default; canonical layer-contract example |
+| `memoji` | soft volumetric head | radial gradients, glossy eyes, blush |
+| `pixelart` | retro 32×32 grid | mouth and pupils move in whole pixels |
+| `doodle` | hand-drawn ink sketch | wobbly strokes, sketched thought bubble |
+| `dicebear` | [DiceBear](https://www.dicebear.com) styles | optional, lazy-loaded; curated CC0 set; pass `dicebearCollection` / `dicebearSeed` |
+| `vrm` | 3D VRoid/VRM model | optional, lazy-loaded; pass `vrmUrl` |
+| `glb` | 3D glTF + ARKit blendshapes | optional, lazy-loaded; pass `glbUrl`. Works with [Microsoft Rocketbox](https://github.com/microsoft/Microsoft-Rocketbox) (MIT), Ready Player Me, or any `.glb` exposing the 52 ARKit morph targets |
+| `byos` | **your** SVG | pass it as children; see the layer contract |
+
+All built-in presets are original designs licensed MIT — nothing inside this package requires attribution.
+
+## DiceBear avatars (`dicebear`)
+
+Generate [DiceBear](https://www.dicebear.com) avatars client-side — deterministic per `seed`, no network call. The packages are **optional** peer dependencies, lazy-loaded only when this variant renders:
+
+```bash
+npm install @dicebear/core @dicebear/collection
+```
+
+```tsx
+<RealtimeAvatar
+  state={aiState}
+  analyser={analyser}
+  variant="dicebear"
+  dicebearCollection="open-peeps" // curated CC0 style id
+  dicebearSeed="ada-lovelace"     // same seed + style => same face
+/>
+```
+
+**Licensing:** DiceBear ships ~30 styles under mixed licenses. This library's catalog (`DICEBEAR_STYLES`) is curated to **CC0 1.0** styles that have a face — `pixel-art`(+`-neutral`), `lorelei`(+`-neutral`), `notionists`(+`-neutral`), `open-peeps`, `thumbs` — so it keeps the same no-attribution promise as the built-in presets. You *can* pass any other DiceBear style id to `dicebearCollection`, but then its license (e.g. CC BY 4.0 for `adventurer`, or "free for personal and commercial use" for `bottts`) is your responsibility — same deal as `byos`.
+
+**Animation:** DiceBear SVGs have no `#rra-*` hooks, but their *option API* lets us pick which mouth/eyes variant to render. So every curated style actually **talks**: it pre-generates a few frames of the same avatar (same seed ⇒ identical hair/skin/etc.) with closed / mid / open mouths — plus a blink frame where the style allows — and swaps which frame is shown per audio frame, with a subtle bounce on top. Real articulation via the supported API, no fragile path hacks. The per-style variant choices live in the exported `DICEBEAR_RIGS` map. (A non-rigged style id you pass yourself — e.g. a faceless abstract DiceBear style — falls back to a pure audio-reactive bounce.) State color and the thinking bubble still come from the surrounding `<RealtimeAvatar />` chrome.
+
+## 3D GLB + ARKit (`glb`)
+
+Render any `.glb` that exposes the **52 [ARKit blendshapes](https://arkit-face-blendshapes.com/)** (the standard `jawOpen`, `mouthFunnel`, `eyeBlinkLeft`, … morph targets). Same shared mouth engine as the flat presets drives them, so the model talks, blinks and follows the cursor. The three.js stack is optional and lazy-loaded — same deal as `vrm`, minus `@pixiv/three-vrm`:
+
+```bash
+npm install three @react-three/fiber @react-three/drei
+```
+
+```tsx
+<RealtimeAvatar
+  state={aiState}
+  analyser={analyser}
+  variant="glb"
+  glbUrl="/models/rocketbox.glb" // CORS-enabled .glb with ARKit morph targets
+/>
+```
+
+**Recommended example asset — Microsoft Rocketbox (MIT).** [Rocketbox](https://github.com/microsoft/Microsoft-Rocketbox) ships 115 rigged avatars with an ARKit-compatible blendshape variant, under the **MIT license** — the cleanest fit for this library's no-attribution-headaches philosophy. Rocketbox distributes `.fbx`, so convert one avatar to `.glb` once (offline, via [FBX2GLTF](https://github.com/facebookincubator/FBX2glTF) or Blender's glTF 2.0 export, keeping the blendshapes) and drop it in `public/models/`. Keep the MIT notice alongside it. [Ready Player Me](https://docs.readyplayer.me/ready-player-me/api-reference/avatars/morph-targets/apple-arkit) avatars (`?morphTargets=ARKit`) also work out of the box.
+
+## Bring your own SVG (`byos`)
+
+Any SVG exposing these stable hooks is animated by the runtime — same blink, gaze, mouth and thinking behavior as the built-in presets:
+
+| hook | part | the runtime drives |
+|---|---|---|
+| `#rra-ring` | state ring | `stroke` = `stateColors[state]` |
+| `#rra-mouth` | mouth | ellipse: `ry`/`rx` · rect: `height` |
+| `.rra-pupil` (×2) | pupils | circle: `cx`/`cy` · rect: `x`/`y` (mouse tracking, thinking gaze) |
+| `.rra-lid` (×2) | eyelids | `height` (blink; 0 = open) |
+| `#rra-think` | thought bubble | `opacity` + dots pulsing while `thinking` |
+
+Optional data attributes: `data-base-x`/`data-base-y` (pupil rest position), `data-max-height` (closed lid height), `data-quantize` (snap motion to a grid — that's how the pixel-art preset stays chunky).
+
+```tsx
+<RealtimeAvatar state={aiState} analyser={analyser} variant="byos">
+  <MyOwnSvgAvatar /> {/* exposes the #rra-* hooks; its license is your business */}
+</RealtimeAvatar>
+```
+
+## API reference
+
+### `<RealtimeAvatar />`
+
+- `state` (`'idle' | 'listening' | 'thinking' | 'speaking'`) — required. You resolve it; it is never inferred.
+- `analyser` (`AnalyserNode | null`) — optional. Drives the mouth from audio. Omitted or `null`, speaking falls back to the synthetic pattern.
+- `streamingText` (`string`) — optional. Declarative mouth driver: pass the accumulated assistant text (e.g. from `useChat`) and the avatar diffs its growth to drive the mouth. Takes precedence over `analyser`. See [Text-streaming LLMs](#text-streaming-llms-no-audio).
+- `speechActivity` (`SpeechActivitySource`) — optional. Imperative token-rate mouth driver, from `createSpeechActivity()`. Takes precedence over both `streamingText` and `analyser` when set.
+- `size` (`number`) — px, default `280`.
+- `variant` — see catalog above. Default `'geometric'`.
+- `children` — your SVG, for `variant="byos"`.
+- `vrmUrl` (`string`) — CORS-enabled `.vrm` URL, for `variant="vrm"`.
+- `glbUrl` (`string`) — CORS-enabled `.glb` URL with ARKit blendshapes, for `variant="glb"`.
+- `dicebearCollection` (`string`) — DiceBear style id (curated CC0 set), for `variant="dicebear"`.
+- `dicebearSeed` (`string`) — deterministic DiceBear seed, for `variant="dicebear"`.
+- `subtitle` / `thought` (`string`) — optional movie-style captions and a thought bubble.
+- `showGlow` / `showStatePill` / `showThought` / `showSubtitle` (`boolean`) — HUD satellites, each `true` by default. Set any to `false` to hide it individually: the reactive glow, the state pill, the thought bubble, and the subtitle respectively.
+- `maxMouthOpening`, `mouseTrackingIntensity`, `blinkIntervalMin/Max`, `blinkDuration` — animation tuning.
+- `stateColors`, `stateLabels` — theming; labels are announced via `aria-live`.
+- `customization` — preset colors and accessories (skin, hair, clothing, glasses, headphones…).
+
+### Building blocks
+
+Everything the runtime uses is exported, so you can compose your own:
+
+- `ContractAvatar` — wraps any contract-compliant SVG with the runtime.
+- `useAvatarRuntime(containerRef, options)` — the animation runtime itself.
+- `createMouthEngine(source)` / `useAudioMouth(...)` — the source→mouth analysis (amplitude + A/E/O shapes), procedural fallback included. `source` is an `AnalyserNode`, a `SpeechActivitySource`, or `null`.
+- `createSpeechActivity(options?)` — the token-rate mouth driver for text streams (`push` / `end` / `reset` / `sample`).
+- `useStreamingTextActivity(text)` — declarative wrapper: diffs accumulated streaming text into a `SpeechActivitySource` for you (what the `streamingText` prop uses).
+- `useReducedMotion()` — SSR-safe `prefers-reduced-motion` hook.
+- `GeometricAvatar`, `MemojiAvatar`, `PixelArtAvatar`, `DoodleAvatar` — the raw presets.
+- `AudioVisualizer` — Siri-style waveform telemetry strip.
+
+## Getting an `AnalyserNode`
+
+The standard recipe for base64 PCM streams (what Gemini Live / OpenAI Realtime return):
+
+```ts
+const audioCtx = new AudioContext({ sampleRate: 24000 });
+const analyser = audioCtx.createAnalyser();
+analyser.fftSize = 256;
+analyser.connect(audioCtx.destination);
+
+function playAudioChunk(pcmData: Float32Array) {
+  const buffer = audioCtx.createBuffer(1, pcmData.length, 24000);
+  buffer.getChannelData(0).set(pcmData);
+  const source = audioCtx.createBufferSource();
+  source.buffer = buffer;
+  source.connect(analyser); // <- the analyser you pass to <RealtimeAvatar />
+  source.start();
+}
+```
+
+## Text-streaming LLMs (no audio)
+
+Not every assistant speaks. For a text-only LLM that streams tokens — OpenAI-style `/chat/completions` or `/responses` with `stream: true`, or local servers like Ollama / LM Studio / vLLM — there's no `AnalyserNode` to read. Instead, drive the mouth from **token cadence**: the rhythm of arriving text becomes the same 0..1 energy signal the audio path produces. The mouth is busy while the model emits text and settles shut on pauses or when the stream ends. The library still never fetches anything — you own the stream, it owns the face.
+
+There are two ways to feed it, matching the two ways React apps consume streams.
+
+### Declarative — `streamingText` (the easy path)
+
+If you use a streaming chat hook — the [Vercel AI SDK](https://sdk.vercel.ai)'s `useChat` is the de-facto standard — you never see raw chunks: you get the **accumulated** assistant message (it grows each render) plus a `status`. Both map straight onto the avatar. Pass the text, the avatar diffs its growth internally and drives the mouth. No refs, no reader loop:
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { RealtimeAvatar } from 'react-ai-avatar';
+import 'react-ai-avatar/style.css';
+
+function ChatAvatar() {
+  const { messages, status } = useChat();
+  const last = messages.at(-1);
+
+  return (
+    <RealtimeAvatar
+      // status: 'submitted' (awaiting first token) | 'streaming' | 'ready'
+      state={status === 'submitted' ? 'thinking' : status === 'streaming' ? 'speaking' : 'idle'}
+      streamingText={last?.role === 'assistant' ? last.text : ''}
+    />
+  );
+}
+```
+
+That's the whole integration. `streamingText` takes precedence over `analyser`; the ambient glow reacts to it too. Works with every variant — flat presets, DiceBear, VRM and GLB.
+
+### Imperative — `createSpeechActivity()` (you own the reader loop)
+
+Hand-rolling `fetch` or driving the OpenAI SDK's `for await` yourself? Then you *do* have the raw chunks — feed their cadence directly with a `SpeechActivitySource`:
+
+```tsx
+import { RealtimeAvatar, createSpeechActivity } from 'react-ai-avatar';
+import 'react-ai-avatar/style.css';
+import { useRef, useState } from 'react';
+
+function TextAvatar() {
+  const speech = useRef(createSpeechActivity()).current;
+  const [state, setState] = useState<'idle' | 'thinking' | 'speaking'>('idle');
+  const [subtitle, setSubtitle] = useState('');
+
+  async function ask(prompt: string) {
+    setState('thinking');
+    speech.reset();
+    const res = await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages: [{ role: 'user', content: prompt }] }),
+    });
+    const reader = res.body!.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const chunk = decoder.decode(value); // your SSE/delta parsing here
+      text += chunk;
+      speech.push(chunk);   // <- feed token cadence to the mouth
+      setSubtitle(text);
+      setState('speaking');
+    }
+    speech.end();
+    setState('idle');
+  }
+
+  return <RealtimeAvatar state={state} speechActivity={speech} subtitle={subtitle} />;
+}
+```
+
+`createSpeechActivity(options?)` accepts `chargePerChar`, `decayMs` and `maxChargePerPush` to tune how wide / how fast the mouth reacts. The returned source has `push(chunk)`, `end()`, `reset()` (drop energy on an interrupted turn) and `sample()`. When `speechActivity` is provided it takes precedence over both `streamingText` and `analyser`. (`streamingText` is just this, with the diffing done for you — under the hood it's the exported `useStreamingTextActivity` hook.)
+
+> The demo dashboard ships this end-to-end: toggle **TEXT (STREAM)** to talk to an OpenAI-compatible endpoint (set `OPENAI_BASE_URL` / `OPENAI_API_KEY` / `OPENAI_MODEL`, or leave them unset / `MOCK_REALTIME=true` for a no-key mock). See `src/demo/useStreamingLLM.ts` and the `/api/chat` route in `server.ts`.
+
+## Positioning
+
+The closest reference is [TalkingHead](https://github.com/met4citizen/TalkingHead) (3D, realistic lip-sync, Ready Player Me/Mixamo rigs). This library makes the opposite bet:
+
+| | TalkingHead & co. | react-ai-avatar |
+|---|---|---|
+| Star of the show | the realistic human avatar | the LLM's speech + **state** flow |
+| Avatar | 3D full-body rigged | flat SVG, minimal (3D optional, not the focus) |
+| Technical focus | lip-sync fidelity | state + audio reactivity, simplicity |
+| Makes visible | the voice | the *thinking* |
+| Setup | avatar platform + Blender + rig | `npm i` + one component |
+
+## Demo / development
+
+The repo ships a demo dashboard (Gemini Live + a no-API-key mock):
+
+```bash
+npm install
+npm run dev        # starts the demo at :3000 (MOCK_REALTIME=true needs no API key)
+npm test           # vitest: engine, layer contract, SSR, parsers
+npm run build:lib  # builds the publishable package into dist/lib
+```
+
+## License
+
+MIT — for the library, the runtime and all built-in presets. Use it commercially, fork it, reskin it. SVGs you bring via `byos` keep whatever license they had.

package/dist/lib/GlbArkitAvatar-CcPWCsQV.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react/jsx-runtime"),n=require("react"),_=require("@react-three/fiber"),he=require("three/addons/loaders/GLTFLoader.js"),me=require("@react-three/drei"),de=require("three"),ae=require("./useReducedMotion-BRDEmRNI.cjs");function ge(l){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(l){for(const o in l)if(o!=="default"){const L=Object.getOwnPropertyDescriptor(l,o);Object.defineProperty(t,o,L.get?L:{enumerable:!0,get:()=>l[o]})}}return t.default=l,Object.freeze(t)}const Y=ge(de);class pe extends n.Component{constructor(t){super(t),this.state={hasError:!1}}static getDerivedStateFromError(){return{hasError:!0}}componentDidCatch(t){this.props.onError((t==null?void 0:t.message)||String(t))}render(){return this.state.hasError?null:this.props.children}}function xe(l){const t=new Map,o=c=>c.toLowerCase().replace(/[^a-z]/g,"");l.traverse(c=>{const f=c,h=f.morphTargetDictionary;if(!(!h||!f.morphTargetInfluences))for(const i of Object.keys(h)){const g=h[i],r=o(i);t.has(r)||t.set(r,[]),t.get(r).push({mesh:f,index:g})}});const L=c=>{const f=o(c);if(t.has(f))return t.get(f);const h=[];for(const[i,g]of t)i.endsWith(f)&&h.push(...g);return h},S=new Map;return{has(c){return this.entries(c).length>0},entries(c){return S.has(c)||S.set(c,L(c)),S.get(c)},set(c,f){const h=this.entries(c),i=Math.max(0,Math.min(1,f));for(const{mesh:g,index:r}of h)g.morphTargetInfluences[r]=i},names:Array.from(t.keys())}}function be({url:l,state:t,analyser:o,maxMouthOpening:L=30,mouseTrackingIntensity:S=1,blinkIntervalMin:c=2e3,blinkIntervalMax:f=6e3,blinkDuration:h=100,reducedMotion:i=!1,onLoaded:g}){const r=_.useLoader(he.GLTFLoader,l),{camera:a,controls:G}=_.useThree(),p=r.scene,e=n.useMemo(()=>xe(p),[p]);n.useEffect(()=>{var D;g(!0),console.log("[GLB] Model loaded. ARKit blendshapes found:",e.names),p.traverse(B=>{B.frustumCulled=!1});const y=new Y.Box3().setFromObject(p),k=new Y.Vector3,u=new Y.Vector3;y.getSize(k),y.getCenter(u);const w=y.max.y-k.y*.08,Z=Math.max(.45,k.y*.42);a.position.set(u.x,w,y.max.z+Z),a.lookAt(u.x,w,u.z),a.updateProjectionMatrix();const R=G;R!=null&&R.target&&(R.target.set(u.x,w,u.z),(D=R.update)==null||D.call(R))},[p,e,a,G,g]);const v=n.useRef(0),T=n.useRef(0),z=n.useRef(0),E=n.useRef(0),A=n.useRef(0),d=n.useRef(0),m=n.useRef(0),x=n.useRef(0),$=n.useRef(t),V=n.useRef(0),q=n.useRef(0),W=n.useRef(0),X=n.useRef(0),J=n.useRef(Math.random()*3+2),b=n.useRef(0),I=n.useRef(!1),K=n.useRef(null),ee=n.useRef(null);return _.useFrame((y,k)=>{var ue,oe;const u=Y.MathUtils.lerp,w=y.clock.elapsedTime;if(t!==$.current&&(t==="listening"&&!i&&(x.current=1),$.current==="speaking"&&t!=="speaking"&&!i&&(q.current=2),$.current=t),x.current=Math.max(0,x.current-k*2.5),q.current=Math.max(0,q.current-k),!i)if(!I.current)J.current-=k,J.current<=0&&(I.current=!0);else{const j=1e3/(h||100);b.current+=k*j*2,b.current>=1&&(b.current=1,I.current=!1,J.current=Math.random()*((f-c)/1e3)+c/1e3)}if(!I.current&&b.current>0){const j=1e3/(h||100);b.current-=k*j*2,b.current<0&&(b.current=0)}e.set("eyeBlinkLeft",b.current),e.set("eyeBlinkRight",b.current);const Z=((ue=y.pointer)==null?void 0:ue.x)??0,R=((oe=y.pointer)==null?void 0:oe.y)??0,D=i?0:S;let B=Z*D,Q=R*D;t==="thinking"?(B=-.5*(i?0:1),Q=.6*(i?0:1)):i||(B+=Math.sin(w*.23)*.12,Q+=Math.sin(w*.31+1.3)*.08),W.current=u(W.current,B,.1),X.current=u(X.current,Q,.1);const N=W.current,F=X.current;e.set("eyeLookOutRight",Math.max(0,N)),e.set("eyeLookInLeft",Math.max(0,N)),e.set("eyeLookOutLeft",Math.max(0,-N)),e.set("eyeLookInRight",Math.max(0,-N)),e.set("eyeLookUpLeft",Math.max(0,F)),e.set("eyeLookUpRight",Math.max(0,F)),e.set("eyeLookDownLeft",Math.max(0,-F)),e.set("eyeLookDownRight",Math.max(0,-F));let P=0,te=0,ne=0;t==="listening"?(P=.35,te=.25):t==="thinking"?ne=.45:t==="speaking"?P=.12:P=.05,q.current>0&&t!=="speaking"&&(P=Math.max(P,.55));const le=t==="thinking"&&!i?1:0;A.current=u(A.current,P,.1),d.current=u(d.current,te,.1),m.current=u(m.current,ne,.1),V.current=u(V.current,le,.08);const M=A.current,H=V.current;e.set("mouthSmileLeft",M),e.set("mouthSmileRight",M),e.set("browInnerUp",d.current),e.set("browDownLeft",m.current),e.set("browDownRight",m.current),e.set("cheekSquintLeft",M*.6),e.set("cheekSquintRight",M*.6),e.set("mouthDimpleLeft",M*.5),e.set("mouthDimpleRight",M*.5),e.set("eyeSquintLeft",Math.max(M*.35,H*.45)),e.set("eyeSquintRight",Math.max(M*.35,H*.45)),e.set("mouthPressLeft",H*.4),e.set("mouthPressRight",H*.4),e.set("eyeWideLeft",x.current*.7),e.set("eyeWideRight",x.current*.7),e.set("browOuterUpLeft",x.current*.6),e.set("browOuterUpRight",x.current*.6);let U=0,re=0,se=0,ce=0;if(t==="speaking"){(!K.current||ee.current!==o)&&(K.current=ae.createMouthEngine(o),ee.current=o);const j=K.current.read(),fe=L/30,O=j.level*fe;j.shape==="o"?(re=O*.85,se=O*.6,U=O*.35):j.shape==="e"?(ce=O*.7,U=O*.3):j.shape==="a"&&(U=O*.9)}v.current=u(v.current,U,.25),T.current=u(T.current,re,.25),z.current=u(z.current,se,.25),E.current=u(E.current,ce,.25),e.set("jawOpen",v.current),e.set("mouthFunnel",T.current),e.set("mouthPucker",z.current),e.set("mouthStretchLeft",E.current),e.set("mouthStretchRight",E.current);const C=i||t==="speaking"||t==="thinking"?0:1,ie=Math.sin(w*.4)*.06*C;e.set("mouthLeft",Math.max(0,ie)),e.set("mouthRight",Math.max(0,-ie)),e.set("mouthRollLower",(Math.sin(w*.33)*.5+.5)*.07*C),e.set("mouthShrugUpper",(Math.sin(w*.7)*.5+.5)*.06*C)}),s.jsx("primitive",{object:p})}function ke({state:l,analyser:t,size:o=300,className:L="",style:S,maxMouthOpening:c,blinkIntervalMin:f,blinkIntervalMax:h,blinkDuration:i,mouseTrackingIntensity:g,stateColors:r,glbUrl:a}){const[G,p]=n.useState(!1),[e,v]=n.useState(null),[T,z]=n.useState(!1),E=ae.useReducedMotion();n.useEffect(()=>{if(p(!1),v(null),z(!1),!a)return;let d=!1;return fetch(a).then(m=>{const x=m.headers.get("content-type")||"";if(!m.ok)throw new Error(`HTTP ${m.status} for ${a}`);if(x.includes("text/html"))throw new Error(`No .glb found at ${a} (server returned HTML).`);d||z(!0)}).catch(m=>{d||v((m==null?void 0:m.message)||String(m))}),()=>{d=!0}},[a]);const A={idle:(r==null?void 0:r.idle)??"#4b5563",listening:(r==null?void 0:r.listening)??"#3b82f6",thinking:(r==null?void 0:r.thinking)??"#8b5cf6",speaking:(r==null?void 0:r.speaking)??"#10b981",working:(r==null?void 0:r.working)??"#f59e0b"};return s.jsxs("div",{className:`relative flex items-center justify-center rounded-3xl overflow-hidden border border-zinc-800/40 bg-zinc-950/40 ${L}`,style:{width:o,height:o,...S},children:[s.jsxs(_.Canvas,{camera:{position:[0,1.5,1],fov:35},shadows:!0,gl:{antialias:!0,alpha:!0,preserveDrawingBuffer:!0},style:{width:"100%",height:"100%",background:"transparent"},children:[s.jsx("ambientLight",{intensity:1.5}),s.jsx("spotLight",{position:[0,3,2],angle:.6,penumbra:1,intensity:3,color:A[l],castShadow:!0}),s.jsx("directionalLight",{position:[-2,2,-2],intensity:1.8,color:"#ffffff"}),s.jsx("directionalLight",{position:[2,2,2],intensity:2.2,color:"#ffffff"}),s.jsx(pe,{onError:d=>v(d),children:a&&T&&s.jsx(n.Suspense,{fallback:null,children:s.jsx(be,{url:a,state:l,analyser:t,maxMouthOpening:c,mouseTrackingIntensity:g,blinkIntervalMin:f,blinkIntervalMax:h,blinkDuration:i,reducedMotion:E,onLoaded:d=>p(d)})})}),s.jsx(me.OrbitControls,{makeDefault:!0,enableZoom:!1,enablePan:!1,minPolarAngle:Math.PI/2.6,maxPolarAngle:Math.PI/1.7,minAzimuthAngle:-Math.PI/4,maxAzimuthAngle:Math.PI/4})]}),!a&&s.jsxs("div",{className:"absolute inset-0 flex flex-col items-center justify-center bg-zinc-950/90 backdrop-blur-md z-20 p-4 text-center",children:[s.jsx("span",{className:"text-xs font-mono font-bold text-amber-400 uppercase tracking-wider mb-2",children:"Missing glbUrl"}),s.jsx("p",{className:"text-[10px] text-zinc-500 max-w-[200px] leading-relaxed",children:"Pass a CORS-enabled .glb URL (with ARKit blendshapes) via the glbUrl prop."})]}),a&&!G&&!e&&s.jsxs("div",{className:"absolute inset-0 flex flex-col items-center justify-center bg-zinc-950/80 backdrop-blur-md z-20",children:[s.jsx("div",{className:"w-10 h-10 border-4 border-t-emerald-500 border-emerald-500/20 rounded-full animate-spin mb-3"}),s.jsx("span",{className:"text-[10px] font-mono font-bold tracking-widest text-zinc-400 animate-pulse",children:"LOADING GLB MODEL..."})]}),e&&s.jsxs("div",{className:"absolute inset-0 flex flex-col items-center justify-center bg-zinc-950/90 backdrop-blur-md z-20 p-4 text-center",children:[s.jsx("span",{className:"text-xs font-mono font-bold text-red-400 uppercase tracking-wider mb-2",children:"Failed to load GLB"}),s.jsx("p",{className:"text-[10px] text-zinc-500 max-w-[200px] leading-relaxed break-all",children:e})]})]})}exports.GlbArkitAvatar=ke;

package/dist/lib/GlbArkitAvatar-Dm9STiyR.js

@@ -0,0 +1,232 @@
+import { jsxs as I, jsx as o } from "react/jsx-runtime";
+import fe, { useState as ee, useEffect as le, Suspense as pe, useMemo as de, useRef as s } from "react";
+import { Canvas as ge, useLoader as xe, useThree as ke, useFrame as be } from "@react-three/fiber";
+import { GLTFLoader as we } from "three/addons/loaders/GLTFLoader.js";
+import { OrbitControls as Le } from "@react-three/drei";
+import * as H from "three";
+import { u as ye, c as Me } from "./useReducedMotion-BDcEizfP.js";
+class Re extends fe.Component {
+  constructor(t) {
+    super(t), this.state = { hasError: !1 };
+  }
+  static getDerivedStateFromError() {
+    return { hasError: !0 };
+  }
+  componentDidCatch(t) {
+    this.props.onError((t == null ? void 0 : t.message) || String(t));
+  }
+  render() {
+    return this.state.hasError ? null : this.props.children;
+  }
+}
+function ze(R) {
+  const t = /* @__PURE__ */ new Map(), p = (r) => r.toLowerCase().replace(/[^a-z]/g, "");
+  R.traverse((r) => {
+    const u = r, l = u.morphTargetDictionary;
+    if (!(!l || !u.morphTargetInfluences))
+      for (const c of Object.keys(l)) {
+        const f = l[c], n = p(c);
+        t.has(n) || t.set(n, []), t.get(n).push({ mesh: u, index: f });
+      }
+  });
+  const B = (r) => {
+    const u = p(r);
+    if (t.has(u)) return t.get(u);
+    const l = [];
+    for (const [c, f] of t)
+      c.endsWith(u) && l.push(...f);
+    return l;
+  }, z = /* @__PURE__ */ new Map();
+  return {
+    has(r) {
+      return this.entries(r).length > 0;
+    },
+    entries(r) {
+      return z.has(r) || z.set(r, B(r)), z.get(r);
+    },
+    set(r, u) {
+      const l = this.entries(r), c = Math.max(0, Math.min(1, u));
+      for (const { mesh: f, index: n } of l)
+        f.morphTargetInfluences[n] = c;
+    },
+    /** All normalized morph-target names found, for debugging. */
+    names: Array.from(t.keys())
+  };
+}
+function Se({
+  url: R,
+  state: t,
+  analyser: p,
+  maxMouthOpening: B = 30,
+  mouseTrackingIntensity: z = 1,
+  blinkIntervalMin: r = 2e3,
+  blinkIntervalMax: u = 6e3,
+  blinkDuration: l = 100,
+  reducedMotion: c = !1,
+  onLoaded: f
+}) {
+  const n = xe(we, R), { camera: a, controls: O } = ke(), d = n.scene, e = de(() => ze(d), [d]);
+  le(() => {
+    var j;
+    f(!0), console.log("[GLB] Model loaded. ARKit blendshapes found:", e.names), d.traverse((G) => {
+      G.frustumCulled = !1;
+    });
+    const L = new H.Box3().setFromObject(d), k = new H.Vector3(), i = new H.Vector3();
+    L.getSize(k), L.getCenter(i);
+    const b = L.max.y - k.y * 0.08, Q = Math.max(0.45, k.y * 0.42);
+    a.position.set(i.x, b, L.max.z + Q), a.lookAt(i.x, b, i.z), a.updateProjectionMatrix();
+    const w = O;
+    w != null && w.target && (w.target.set(i.x, b, i.z), (j = w.update) == null || j.call(w));
+  }, [d, e, a, O, f]);
+  const S = s(0), D = s(0), v = s(0), E = s(0), T = s(0), m = s(0), h = s(0), g = s(0), V = s(t), W = s(0), N = s(0), X = s(0), J = s(0), K = s(Math.random() * 3 + 2), x = s(0), F = s(!1), Z = s(null), te = s(null);
+  return be((L, k) => {
+    var ae, ue;
+    const i = H.MathUtils.lerp, b = L.clock.elapsedTime;
+    if (t !== V.current && (t === "listening" && !c && (g.current = 1), V.current === "speaking" && t !== "speaking" && !c && (N.current = 2), V.current = t), g.current = Math.max(0, g.current - k * 2.5), N.current = Math.max(0, N.current - k), !c)
+      if (!F.current)
+        K.current -= k, K.current <= 0 && (F.current = !0);
+      else {
+        const M = 1e3 / (l || 100);
+        x.current += k * M * 2, x.current >= 1 && (x.current = 1, F.current = !1, K.current = Math.random() * ((u - r) / 1e3) + r / 1e3);
+      }
+    if (!F.current && x.current > 0) {
+      const M = 1e3 / (l || 100);
+      x.current -= k * M * 2, x.current < 0 && (x.current = 0);
+    }
+    e.set("eyeBlinkLeft", x.current), e.set("eyeBlinkRight", x.current);
+    const Q = ((ae = L.pointer) == null ? void 0 : ae.x) ?? 0, w = ((ue = L.pointer) == null ? void 0 : ue.y) ?? 0, j = c ? 0 : z;
+    let G = Q * j, _ = w * j;
+    t === "thinking" ? (G = -0.5 * (c ? 0 : 1), _ = 0.6 * (c ? 0 : 1)) : c || (G += Math.sin(b * 0.23) * 0.12, _ += Math.sin(b * 0.31 + 1.3) * 0.08), X.current = i(X.current, G, 0.1), J.current = i(J.current, _, 0.1);
+    const q = X.current, U = J.current;
+    e.set("eyeLookOutRight", Math.max(0, q)), e.set("eyeLookInLeft", Math.max(0, q)), e.set("eyeLookOutLeft", Math.max(0, -q)), e.set("eyeLookInRight", Math.max(0, -q)), e.set("eyeLookUpLeft", Math.max(0, U)), e.set("eyeLookUpRight", Math.max(0, U)), e.set("eyeLookDownLeft", Math.max(0, -U)), e.set("eyeLookDownRight", Math.max(0, -U));
+    let P = 0, ne = 0, re = 0;
+    t === "listening" ? (P = 0.35, ne = 0.25) : t === "thinking" ? re = 0.45 : t === "speaking" ? P = 0.12 : P = 0.05, N.current > 0 && t !== "speaking" && (P = Math.max(P, 0.55));
+    const he = t === "thinking" && !c ? 1 : 0;
+    T.current = i(T.current, P, 0.1), m.current = i(m.current, ne, 0.1), h.current = i(h.current, re, 0.1), W.current = i(W.current, he, 0.08);
+    const y = T.current, Y = W.current;
+    e.set("mouthSmileLeft", y), e.set("mouthSmileRight", y), e.set("browInnerUp", m.current), e.set("browDownLeft", h.current), e.set("browDownRight", h.current), e.set("cheekSquintLeft", y * 0.6), e.set("cheekSquintRight", y * 0.6), e.set("mouthDimpleLeft", y * 0.5), e.set("mouthDimpleRight", y * 0.5), e.set("eyeSquintLeft", Math.max(y * 0.35, Y * 0.45)), e.set("eyeSquintRight", Math.max(y * 0.35, Y * 0.45)), e.set("mouthPressLeft", Y * 0.4), e.set("mouthPressRight", Y * 0.4), e.set("eyeWideLeft", g.current * 0.7), e.set("eyeWideRight", g.current * 0.7), e.set("browOuterUpLeft", g.current * 0.6), e.set("browOuterUpRight", g.current * 0.6);
+    let $ = 0, ce = 0, se = 0, ie = 0;
+    if (t === "speaking") {
+      (!Z.current || te.current !== p) && (Z.current = Me(p), te.current = p);
+      const M = Z.current.read(), me = B / 30, A = M.level * me;
+      M.shape === "o" ? (ce = A * 0.85, se = A * 0.6, $ = A * 0.35) : M.shape === "e" ? (ie = A * 0.7, $ = A * 0.3) : M.shape === "a" && ($ = A * 0.9);
+    }
+    S.current = i(S.current, $, 0.25), D.current = i(D.current, ce, 0.25), v.current = i(v.current, se, 0.25), E.current = i(E.current, ie, 0.25), e.set("jawOpen", S.current), e.set("mouthFunnel", D.current), e.set("mouthPucker", v.current), e.set("mouthStretchLeft", E.current), e.set("mouthStretchRight", E.current);
+    const C = c || t === "speaking" || t === "thinking" ? 0 : 1, oe = Math.sin(b * 0.4) * 0.06 * C;
+    e.set("mouthLeft", Math.max(0, oe)), e.set("mouthRight", Math.max(0, -oe)), e.set("mouthRollLower", (Math.sin(b * 0.33) * 0.5 + 0.5) * 0.07 * C), e.set("mouthShrugUpper", (Math.sin(b * 0.7) * 0.5 + 0.5) * 0.06 * C);
+  }), /* @__PURE__ */ o("primitive", { object: d });
+}
+function Te({
+  state: R,
+  analyser: t,
+  size: p = 300,
+  className: B = "",
+  style: z,
+  maxMouthOpening: r,
+  blinkIntervalMin: u,
+  blinkIntervalMax: l,
+  blinkDuration: c,
+  mouseTrackingIntensity: f,
+  stateColors: n,
+  glbUrl: a
+}) {
+  const [O, d] = ee(!1), [e, S] = ee(null), [D, v] = ee(!1), E = ye();
+  le(() => {
+    if (d(!1), S(null), v(!1), !a) return;
+    let m = !1;
+    return fetch(a).then((h) => {
+      const g = h.headers.get("content-type") || "";
+      if (!h.ok) throw new Error(`HTTP ${h.status} for ${a}`);
+      if (g.includes("text/html"))
+        throw new Error(`No .glb found at ${a} (server returned HTML).`);
+      m || v(!0);
+    }).catch((h) => {
+      m || S((h == null ? void 0 : h.message) || String(h));
+    }), () => {
+      m = !0;
+    };
+  }, [a]);
+  const T = {
+    idle: (n == null ? void 0 : n.idle) ?? "#4b5563",
+    listening: (n == null ? void 0 : n.listening) ?? "#3b82f6",
+    thinking: (n == null ? void 0 : n.thinking) ?? "#8b5cf6",
+    speaking: (n == null ? void 0 : n.speaking) ?? "#10b981",
+    working: (n == null ? void 0 : n.working) ?? "#f59e0b"
+  };
+  return /* @__PURE__ */ I(
+    "div",
+    {
+      className: `relative flex items-center justify-center rounded-3xl overflow-hidden border border-zinc-800/40 bg-zinc-950/40 ${B}`,
+      style: { width: p, height: p, ...z },
+      children: [
+        /* @__PURE__ */ I(
+          ge,
+          {
+            camera: { position: [0, 1.5, 1], fov: 35 },
+            shadows: !0,
+            gl: { antialias: !0, alpha: !0, preserveDrawingBuffer: !0 },
+            style: { width: "100%", height: "100%", background: "transparent" },
+            children: [
+              /* @__PURE__ */ o("ambientLight", { intensity: 1.5 }),
+              /* @__PURE__ */ o(
+                "spotLight",
+                {
+                  position: [0, 3, 2],
+                  angle: 0.6,
+                  penumbra: 1,
+                  intensity: 3,
+                  color: T[R],
+                  castShadow: !0
+                }
+              ),
+              /* @__PURE__ */ o("directionalLight", { position: [-2, 2, -2], intensity: 1.8, color: "#ffffff" }),
+              /* @__PURE__ */ o("directionalLight", { position: [2, 2, 2], intensity: 2.2, color: "#ffffff" }),
+              /* @__PURE__ */ o(Re, { onError: (m) => S(m), children: a && D && /* @__PURE__ */ o(pe, { fallback: null, children: /* @__PURE__ */ o(
+                Se,
+                {
+                  url: a,
+                  state: R,
+                  analyser: t,
+                  maxMouthOpening: r,
+                  mouseTrackingIntensity: f,
+                  blinkIntervalMin: u,
+                  blinkIntervalMax: l,
+                  blinkDuration: c,
+                  reducedMotion: E,
+                  onLoaded: (m) => d(m)
+                }
+              ) }) }),
+              /* @__PURE__ */ o(
+                Le,
+                {
+                  makeDefault: !0,
+                  enableZoom: !1,
+                  enablePan: !1,
+                  minPolarAngle: Math.PI / 2.6,
+                  maxPolarAngle: Math.PI / 1.7,
+                  minAzimuthAngle: -Math.PI / 4,
+                  maxAzimuthAngle: Math.PI / 4
+                }
+              )
+            ]
+          }
+        ),
+        !a && /* @__PURE__ */ I("div", { className: "absolute inset-0 flex flex-col items-center justify-center bg-zinc-950/90 backdrop-blur-md z-20 p-4 text-center", children: [
+          /* @__PURE__ */ o("span", { className: "text-xs font-mono font-bold text-amber-400 uppercase tracking-wider mb-2", children: "Missing glbUrl" }),
+          /* @__PURE__ */ o("p", { className: "text-[10px] text-zinc-500 max-w-[200px] leading-relaxed", children: "Pass a CORS-enabled .glb URL (with ARKit blendshapes) via the glbUrl prop." })
+        ] }),
+        a && !O && !e && /* @__PURE__ */ I("div", { className: "absolute inset-0 flex flex-col items-center justify-center bg-zinc-950/80 backdrop-blur-md z-20", children: [
+          /* @__PURE__ */ o("div", { className: "w-10 h-10 border-4 border-t-emerald-500 border-emerald-500/20 rounded-full animate-spin mb-3" }),
+          /* @__PURE__ */ o("span", { className: "text-[10px] font-mono font-bold tracking-widest text-zinc-400 animate-pulse", children: "LOADING GLB MODEL..." })
+        ] }),
+        e && /* @__PURE__ */ I("div", { className: "absolute inset-0 flex flex-col items-center justify-center bg-zinc-950/90 backdrop-blur-md z-20 p-4 text-center", children: [
+          /* @__PURE__ */ o("span", { className: "text-xs font-mono font-bold text-red-400 uppercase tracking-wider mb-2", children: "Failed to load GLB" }),
+          /* @__PURE__ */ o("p", { className: "text-[10px] text-zinc-500 max-w-[200px] leading-relaxed break-all", children: e })
+        ] })
+      ]
+    }
+  );
+}
+export {
+  Te as GlbArkitAvatar
+};