@voqalize/avatar 0.2.2 → 0.3.0

package/dist/AvatarClient.js

@@ -0,0 +1,450 @@
+/**
+ * AvatarClient — the avatar's server-message dispatcher, turn clock, and cue
+ * splice, framework-free (no React; the hook and component wrap this).
+ *
+ * ## Turn clock anchoring
+ *
+ * Base Pipecat TTS gives each serialized TTS context an opaque `context_id`.
+ * The server uses it only to group and splice cue chunks. `botStartedSpeaking`
+ * has no context payload, so the browser FIFO-claims the next buffered context
+ * at that Pipecat output-lifecycle event and anchors its clock there.
+ * `botStoppedSpeaking` closes the active context. Neither event observes the
+ * browser's audio device, and no avatar-specific speech marker exists.
+ *
+ * `attach()` subscribes to the avatar server-message channel *and* Pipecat's
+ * standard lifecycle events. Server messages carry only what Pipecat cannot:
+ * correlated speech/cue timing and deliberate application instructions. The
+ * lifecycle events project the factual presence states locally. The server
+ * supplies only lower-priority `THINKING` / `WORKING` claims and deliberate,
+ * self-completing actions. This keeps the face tied to Pipecat's output truth
+ * even if a server claim is delayed or stale.
+ *
+ * ## Cue splice
+ *
+ * The widget has two cue-track primitives: `speak({cues, clock})` (a full
+ * replace) and `pushCues(cues)` (a pure union that can only grow the track,
+ * never shrink it). Neither is "discard queued cues at or after `from_ms`,
+ * then append" on its own — `pushCues` has no way to drop a stale tail. So
+ * this client keeps the turn's canonical cue array itself (kept portion +
+ * every appended chunk, spliced on each `cues` message) and picks the cheapest
+ * widget call that stays correct:
+ *
+ *   - if the splice's `from_ms` doesn't reach back into anything already
+ *     queued — the common case past a turn's first sentence, since only the
+ *     first sentence genuinely plays fast-leg cues — nothing needs discarding:
+ *     `pushCues(newCues)` is the cheap, correct append.
+ *   - if it does reach back (a real fast→accurate splice), `pushCues` cannot
+ *     express the discard; we call `speak()` again with the full spliced
+ *     canonical array on the turn's original clock. `speak()` is otherwise
+ *     documented as also killing an in-flight spoken interjection and
+ *     re-entering `SPEAKING` — both harmless mid-splice (an interjection
+ *     should not be running while a server track owns the mouth; re-entering
+ *     an unchanged state is a no-op past the profile/gaze reset the widget
+ *     already does for a same-name `setState`).
+ *
+ * Cues commonly arrive **before** `botStartedSpeaking` — the fast leg starts
+ * the moment a sentence is handed to TTS, well before bot output begins.
+ * Chunks that arrive before the clock is anchored are spliced into the
+ * canonical array but not yet handed to the widget; `botStartedSpeaking` hands over
+ * whatever has accumulated as the turn's first `speak()` call. So "the first
+ * chunk of a turn starts speak()" means the first *widget* call, not
+ * necessarily the first *message*.
+ */
+import { BehaviorController } from "../src/behavior.js";
+import { isAvatarMessage, parseAvatarCommand, } from "./types.js";
+/**
+ * The one `RTVIEvent` member `attach()` subscribes to, spelled as its value.
+ *
+ * Written out rather than imported because that enum was this module's *only*
+ * runtime reference to `@pipecat-ai/client-js`, and one runtime reference makes
+ * the whole `/pipecat` subpath fail to load without the peer installed — even
+ * for a host that drives `dispatch()` from its own transport and never calls
+ * `attach()`. The peer is declared optional; this is what makes that true
+ * rather than aspirational.
+ *
+ * String enums are nominal in TypeScript, so the compiler cannot check these
+ * against the real ones from a type-only import. `packages/avatar/test/AvatarClient.test.ts`
+ * does it instead, against the actual enum — the devDependency is present
+ * exactly where the check belongs and absent from what we ship.
+ */
+export const RTVI_EVENTS = {
+    serverMessage: "serverMessage",
+    connected: "connected",
+    disconnected: "disconnected",
+    botReady: "botReady",
+    error: "error",
+    userStartedSpeaking: "userStartedSpeaking",
+    userStoppedSpeaking: "userStoppedSpeaking",
+    botStartedSpeaking: "botStartedSpeaking",
+    botStoppedSpeaking: "botStoppedSpeaking",
+    // Mute is a Pipecat fact, not a claim: the server's mute strategy emits
+    // `UserMuteStarted/StoppedFrame`, the RTVI observer forwards them, and the
+    // browser client raises these. So "has muted you" costs no wire verb —
+    // reading the events the peer already sends is exactly the authority model.
+    userMuteStarted: "userMuteStarted",
+    userMuteStopped: "userMuteStopped",
+};
+/** Defensive unwrap for the `RTVIEvent.ServerMessage` `{ data }` quirk: some
+ * transports deliver the payload directly and some wrap it once more. */
+function unwrapServerMessage(raw) {
+    const obj = (raw ?? {});
+    const inner = obj["data"];
+    return inner && "type" in inner ? inner : obj;
+}
+export class AvatarClient {
+    avatar;
+    /** Maps factual/wire intent into the broader client behavior catalog. */
+    behavior;
+    opts;
+    now;
+    turn = null;
+    turns = new Map();
+    pendingCtxs = [];
+    closedCtxs = new Set();
+    projected = null;
+    serverClaim = null;
+    userSpeaking = false;
+    botSpeaking = false;
+    muted = false;
+    listening = false;
+    // Idle is earned after a connected, quiet listening interval. A newly
+    // mounted avatar is available, not already "stepped aside".
+    idle = false;
+    failure = null;
+    idleTimer = null;
+    pendingInterruptedAction = false;
+    discardQueuedContextsOnBotStop = false;
+    idleDelayMs;
+    setTimer;
+    clearTimer;
+    constructor(avatar, opts = {}) {
+        this.avatar = avatar;
+        this.behavior = new BehaviorController(avatar);
+        this.opts = opts;
+        this.now = opts.now ?? (() => performance.now());
+        this.idleDelayMs = opts.idleDelayMs ?? 12_000;
+        this.setTimer = opts.setTimeout ?? globalThis.setTimeout.bind(globalThis);
+        this.clearTimer = opts.clearTimeout ?? globalThis.clearTimeout.bind(globalThis);
+    }
+    /** The active turn's ctx, or `null` between turns. For tests and telemetry. */
+    get turnCtx() {
+        return this.turn?.ctx ?? null;
+    }
+    /** The active turn's canonical (already-spliced) cue track. For tests and telemetry. */
+    get turnCues() {
+        return this.turn ? [...this.turn.cues] : [];
+    }
+    /** Current resolved projection. Internal — for tests and Studio's inspector.
+     * Before the first lifecycle fact the renderer is simply at its ready rest
+     * pose, so `LISTENING` is the safe value; it is not a session status. */
+    get presenceState() {
+        return this.projected ?? "LISTENING";
+    }
+    /** Re-apply the currently resolved factual projection after an embedding
+     * tool has temporarily used raw renderer controls. This does not invent a
+     * lifecycle event or cancel a finite action. */
+    restoreProjection() {
+        this.applyProjection(true);
+    }
+    /** Dispatch one server message. Anything that isn't in the avatar envelope
+     * is not ours and is ignored; so is an envelope carrying a `cmd` this build
+     * has never heard of, per the wire protocol's forward-compat rule. */
+    dispatch(raw) {
+        if (!isAvatarMessage(raw))
+            return;
+        const msg = parseAvatarCommand(raw);
+        if (!msg)
+            return;
+        try {
+            switch (msg.cmd) {
+                case "claim":
+                    this.handleClaim(msg.state);
+                    break;
+                case "action":
+                    this.handleAction(msg.id);
+                    break;
+                case "cues":
+                    this.handleCues(msg);
+                    break;
+                // No default: an unknown `cmd` is a newer server talking to an older
+                // widget, and the protocol's forward-compat rule says ignore it. There
+                // is no callback for it — a hook nobody could act on is observability,
+                // not an interface.
+            }
+        }
+        catch (err) {
+            if (this.opts.onError)
+                this.opts.onError(err, msg);
+            else
+                console.warn("[avatar] dispatch failed", msg, err);
+        }
+    }
+    handleClaim(state) {
+        this.serverClaim = state;
+        if (state)
+            this.idle = false;
+        this.applyProjection();
+        this.armIdleIfEligible();
+    }
+    handleAction(id) {
+        // An interruption is a server-confirmed explanation of a transition, not
+        // authority to steal the mouth while bot audio is still playing. Hold it
+        // until Pipecat output has released the speaking state.
+        if (id === "RESPONSE_INTERRUPTED" && this.botSpeaking) {
+            this.pendingInterruptedAction = true;
+            // Any prefetched TTS contexts behind interrupted output belong to
+            // audio Pipecat will now discard. Never let one animate a later reply.
+            this.discardQueuedContextsOnBotStop = true;
+            return;
+        }
+        this.playAction(id);
+    }
+    playAction(id) {
+        this.behavior.wireAction(id);
+    }
+    ensureTurn(ctx) {
+        const existing = this.turns.get(ctx);
+        if (existing)
+            return existing;
+        const turn = { ctx, cues: [], started: false, clock: null };
+        this.turns.set(ctx, turn);
+        this.pendingCtxs.push(ctx);
+        return turn;
+    }
+    handleCues(msg) {
+        if (this.closedCtxs.has(msg.ctx))
+            return;
+        const turn = this.ensureTurn(msg.ctx);
+        const kept = turn.cues.filter((c) => c.t < msg.from_ms);
+        const discarded = turn.cues.length - kept.length;
+        turn.cues = [...kept, ...msg.cues].sort((a, b) => a.t - b.t);
+        if (!turn.started) {
+            // No clock yet — buffer. Pipecat output will claim this FIFO context.
+            if (this.botSpeaking && this.turn === null)
+                this.activateNextTurn();
+            return;
+        }
+        if (discarded === 0) {
+            this.avatar.pushCues(msg.cues);
+        }
+        else {
+            this.avatar.speak({ cues: turn.cues, clock: turn.clock });
+        }
+    }
+    activateNextTurn() {
+        if (this.turn)
+            return;
+        let turn;
+        while (this.pendingCtxs.length && !turn) {
+            turn = this.turns.get(this.pendingCtxs.shift());
+        }
+        if (!turn)
+            return;
+        const t0 = this.now();
+        turn.clock = () => this.now() - t0;
+        turn.started = true;
+        this.turn = turn;
+        this.avatar.speak({ cues: turn.cues, clock: turn.clock });
+    }
+    discardQueuedTurns() {
+        for (const ctx of this.pendingCtxs.splice(0)) {
+            this.closedCtxs.add(ctx);
+            this.turns.delete(ctx);
+        }
+    }
+    lifecycleState() {
+        // The one copy of the ladder is docs/pipecat-lifecycle-protocol.md; this is
+        // its implementation, in the same order.
+        //
+        // Audio truth is the P0 invariant: no lower claim or microphone event may
+        // put the face in a non-speaking pose while bot speech is audible.
+        if (this.botSpeaking)
+            return "SPEAKING";
+        if (this.userSpeaking)
+            return "LISTENING";
+        // A broken session outranks mute, because a mute nobody can hear about is
+        // not the thing worth saying about a dead call.
+        if (this.failure)
+            return this.failure;
+        if (this.muted)
+            return "MUTED";
+        // Every claim resolves to the presence state of the same name, so there is
+        // nothing to rank here — a claim is a single value and only one can be in
+        // flight. STRAINING > THINKING > WORKING is decided where more than one
+        // condition can hold at once, which is the server: `AvatarStateMachine.
+        // _resolve()`. Ranking them again on this side would be a second, silent
+        // copy of that ladder, and the two would drift.
+        if (this.serverClaim)
+            return this.serverClaim;
+        if (this.idle)
+            return "IDLE";
+        return "LISTENING";
+    }
+    applyProjection(force = false) {
+        const state = this.lifecycleState();
+        if (force || this.projected !== state) {
+            this.behavior.setState(state);
+            this.projected = state;
+            this.opts.onPresenceChange?.(state);
+        }
+    }
+    clearIdleTimer() {
+        if (this.idleTimer !== null) {
+            this.clearTimer(this.idleTimer);
+            this.idleTimer = null;
+        }
+    }
+    armIdleIfEligible() {
+        this.clearIdleTimer();
+        // Quiet under a mute is not the quiet that earns IDLE — the silence was
+        // imposed, and letting the timer run behind it would reveal a stepped-aside
+        // face the moment the microphone came back.
+        if (!this.eligibleForIdle())
+            return;
+        this.idleTimer = this.setTimer(() => {
+            this.idleTimer = null;
+            if (this.eligibleForIdle()) {
+                this.idle = true;
+                this.applyProjection();
+            }
+        }, this.idleDelayMs);
+    }
+    eligibleForIdle() {
+        return this.listening && !this.userSpeaking && !this.botSpeaking
+            && !this.muted && !this.serverClaim && !this.failure;
+    }
+    enterListening() {
+        this.listening = true;
+        this.idle = false;
+        this.applyProjection();
+        this.armIdleIfEligible();
+    }
+    clearClaimForTurnBoundary() {
+        // Claims are lower-priority hints. A fresh user turn or bot output means
+        // any prior thinking/work claim is no longer allowed to reappear later.
+        this.serverClaim = null;
+    }
+    maybePlayInterrupted() {
+        if (this.pendingInterruptedAction && !this.botSpeaking) {
+            this.pendingInterruptedAction = false;
+            this.playAction("RESPONSE_INTERRUPTED");
+        }
+    }
+    clearRecoverableFailure() {
+        if (this.failure === "DEGRADED") {
+            this.failure = null;
+            this.applyProjection();
+        }
+    }
+    onUserStartedSpeaking = () => {
+        this.clearRecoverableFailure();
+        this.userSpeaking = true;
+        this.clearClaimForTurnBoundary();
+        this.listening = true;
+        this.idle = false;
+        this.clearIdleTimer();
+        this.avatar.setUserSpeaking(true);
+        this.applyProjection();
+    };
+    onUserStoppedSpeaking = () => {
+        this.userSpeaking = false;
+        this.avatar.setUserSpeaking(false);
+        this.enterListening();
+    };
+    onBotStartedSpeaking = () => {
+        this.clearRecoverableFailure();
+        this.botSpeaking = true;
+        this.clearClaimForTurnBoundary();
+        this.idle = false;
+        this.clearIdleTimer();
+        this.applyProjection();
+        this.activateNextTurn();
+    };
+    onBotStoppedSpeaking = () => {
+        this.botSpeaking = false;
+        // Playout truth releases the only active mouth track. A late cue chunk for
+        // this context is ignored rather than reviving a silent mouth.
+        if (this.turn) {
+            this.avatar.stopSpeaking();
+            this.closedCtxs.add(this.turn.ctx);
+            this.turns.delete(this.turn.ctx);
+            this.turn = null;
+        }
+        if (this.discardQueuedContextsOnBotStop) {
+            this.discardQueuedContextsOnBotStop = false;
+            this.discardQueuedTurns();
+        }
+        this.enterListening();
+        this.maybePlayInterrupted();
+    };
+    onUserMuteStarted = () => {
+        this.muted = true;
+        this.idle = false;
+        this.clearIdleTimer();
+        this.applyProjection();
+    };
+    onUserMuteStopped = () => {
+        this.muted = false;
+        // Whatever the avatar was waiting on before the mute, it is waiting on the
+        // user again now — the same place a turn ends.
+        this.enterListening();
+    };
+    onError = (raw) => {
+        const data = raw?.data;
+        this.failure = data?.fatal === true ? "OFFLINE" : "DEGRADED";
+        this.applyProjection();
+    };
+    onDisconnected = () => {
+        this.failure = "OFFLINE";
+        this.clearIdleTimer();
+        this.applyProjection();
+    };
+    onConnectedOrReady = () => {
+        if (this.failure === "OFFLINE")
+            this.failure = null;
+        // Pipecat has established a session. Until a factual speech event says
+        // otherwise, the avatar is available to listen; it earns IDLE only after
+        // the regular quiet timer expires.
+        this.listening = true;
+        this.idle = false;
+        this.applyProjection();
+        this.armIdleIfEligible();
+    };
+    /**
+     * Subscribe to a live `PipecatClient`. Standard client events own the normal
+     * lifecycle projection; avatar server-messages carry correlated visemes and
+     * explicit application intent. Never throws on malformed or irrelevant
+     * server messages.
+     *
+     * @returns an unsubscribe function; call it on unmount or disconnect.
+     */
+    attach(client) {
+        const onServerMessage = (raw) => this.dispatch(unwrapServerMessage(raw));
+        const subscriptions = [
+            [RTVI_EVENTS.serverMessage, onServerMessage],
+            [RTVI_EVENTS.connected, this.onConnectedOrReady],
+            [RTVI_EVENTS.botReady, this.onConnectedOrReady],
+            [RTVI_EVENTS.disconnected, this.onDisconnected],
+            [RTVI_EVENTS.error, this.onError],
+            [RTVI_EVENTS.userStartedSpeaking, this.onUserStartedSpeaking],
+            [RTVI_EVENTS.userStoppedSpeaking, this.onUserStoppedSpeaking],
+            [RTVI_EVENTS.botStartedSpeaking, this.onBotStartedSpeaking],
+            [RTVI_EVENTS.botStoppedSpeaking, this.onBotStoppedSpeaking],
+            [RTVI_EVENTS.userMuteStarted, this.onUserMuteStarted],
+            [RTVI_EVENTS.userMuteStopped, this.onUserMuteStopped],
+        ];
+        for (const [event, listener] of subscriptions)
+            client.on(event, listener);
+        return () => {
+            this.clearIdleTimer();
+            for (const [event, listener] of subscriptions)
+                client.off(event, listener);
+        };
+    }
+    /** Dispose controller-owned timers when its mounted avatar is destroyed. */
+    destroy() {
+        this.clearIdleTimer();
+        this.behavior.destroy();
+    }
+}
+//# sourceMappingURL=AvatarClient.js.map

package/dist/AvatarClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AvatarClient.js","sourceRoot":"","sources":["../client/AvatarClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,kBAAkB,GAInB,MAAM,YAAY,CAAC;AA6CpB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,aAAa,EAAE,eAAe;IAC9B,SAAS,EAAE,WAAW;IACtB,YAAY,EAAE,cAAc;IAC5B,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,mBAAmB,EAAE,qBAAqB;IAC1C,mBAAmB,EAAE,qBAAqB;IAC1C,kBAAkB,EAAE,oBAAoB;IACxC,kBAAkB,EAAE,oBAAoB;IACxC,wEAAwE;IACxE,2EAA2E;IAC3E,uEAAuE;IACvE,4EAA4E;IAC5E,eAAe,EAAE,iBAAiB;IAClC,eAAe,EAAE,iBAAiB;CACO,CAAC;AAS5C;yEACyE;AACzE,SAAS,mBAAmB,CAAC,GAAY;IACvC,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,EAAE,CAA4B,CAAC;IACnD,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAwC,CAAC;IACjE,OAAO,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;AAChD,CAAC;AAED,MAAM,OAAO,YAAY;IACN,MAAM,CAAY;IACnC,yEAAyE;IACxD,QAAQ,CAAqB;IAC7B,IAAI,CAAsB;IAC1B,GAAG,CAAe;IAC3B,IAAI,GAAgB,IAAI,CAAC;IAChB,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IAChC,WAAW,GAAa,EAAE,CAAC;IAC3B,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,SAAS,GAA0B,IAAI,CAAC;IACxC,WAAW,GAAgB,IAAI,CAAC;IAChC,YAAY,GAAG,KAAK,CAAC;IACrB,WAAW,GAAG,KAAK,CAAC;IACpB,KAAK,GAAG,KAAK,CAAC;IACd,SAAS,GAAG,KAAK,CAAC;IAC1B,sEAAsE;IACtE,4DAA4D;IACpD,IAAI,GAAG,KAAK,CAAC;IACb,OAAO,GAAkC,IAAI,CAAC;IAC9C,SAAS,GAAyC,IAAI,CAAC;IACvD,wBAAwB,GAAG,KAAK,CAAC;IACjC,8BAA8B,GAAG,KAAK,CAAC;IAC9B,WAAW,CAAS;IACpB,QAAQ,CAAoB;IAC5B,UAAU,CAAsB;IAEjD,YAAY,MAAiB,EAAE,OAA4B,EAAE;QAC3D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC;QAC9C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC1E,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,YAAY,IAAI,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClF,CAAC;IAED,+EAA+E;IAC/E,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,CAAC;IAChC,CAAC;IAED,wFAAwF;IACxF,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,CAAC;IAED;;6EAEyE;IACzE,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,SAAS,IAAI,WAAW,CAAC;IACvC,CAAC;IAED;;oDAEgD;IAChD,iBAAiB;QACf,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;0EAEsE;IACtE,QAAQ,CAAC,GAAY;QACnB,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC;YAAE,OAAO;QAClC,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,IAAI,CAAC;YACH,QAAQ,GAAG,CAAC,GAAG,EAAE,CAAC;gBAChB,KAAK,OAAO;oBACV,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;oBAC5B,MAAM;gBACR,KAAK,QAAQ;oBACX,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBAC1B,MAAM;gBACR,KAAK,MAAM;oBACT,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;oBACrB,MAAM;gBACR,qEAAqE;gBACrE,uEAAuE;gBACvE,uEAAuE;gBACvE,oBAAoB;YACtB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;;gBAC9C,OAAO,CAAC,IAAI,CAAC,0BAA0B,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAEO,WAAW,CAAC,KAAkB;QACpC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,IAAI,KAAK;YAAE,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAC7B,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAEO,YAAY,CAAC,EAAkB;QACrC,yEAAyE;QACzE,yEAAyE;QACzE,wDAAwD;QACxD,IAAI,EAAE,KAAK,sBAAsB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACtD,IAAI,CAAC,wBAAwB,GAAG,IAAI,CAAC;YACrC,kEAAkE;YAClE,uEAAuE;YACvE,IAAI,CAAC,8BAA8B,GAAG,IAAI,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IAEO,UAAU,CAAC,EAAkB;QACnC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAEO,UAAU,CAAC,GAAW;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC5D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,UAAU,CAAC,GAAkB;QACnC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QACzC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;QACxD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAE7D,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,sEAAsE;YACtE,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;gBAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACpE,OAAO;QACT,CAAC;QACD,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAM,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAEO,gBAAgB;QACtB,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QACtB,IAAI,IAAsB,CAAC;QAC3B,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YACxC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAG,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5D,CAAC;IAEO,kBAAkB;QACxB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAEO,cAAc;QACpB,4EAA4E;QAC5E,yCAAyC;QACzC,EAAE;QACF,0EAA0E;QAC1E,mEAAmE;QACnE,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,UAAU,CAAC;QACxC,IAAI,IAAI,CAAC,YAAY;YAAE,OAAO,WAAW,CAAC;QAC1C,0EAA0E;QAC1E,gDAAgD;QAChD,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC;QACtC,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,OAAO,CAAC;QAC/B,2EAA2E;QAC3E,0EAA0E;QAC1E,wEAAwE;QACxE,wEAAwE;QACxE,yEAAyE;QACzE,gDAAgD;QAChD,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC;QAC9C,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,MAAM,CAAC;QAC7B,OAAO,WAAW,CAAC;IACrB,CAAC;IAEO,eAAe,CAAC,KAAK,GAAG,KAAK;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACpC,IAAI,KAAK,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;YACtC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC9B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAEO,cAAc;QACpB,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,iBAAiB;QACvB,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,wEAAwE;QACxE,4EAA4E;QAC5E,4CAA4C;QAC5C,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YAAE,OAAO;QACpC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;YAClC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,IAAI,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC;gBAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;gBACjB,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACvB,CAAC;IAEO,eAAe;QACrB,OAAO,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,IAAI,CAAC,WAAW;eAC3D,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IACzD,CAAC;IAEO,cAAc;QACpB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAEO,yBAAyB;QAC/B,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAEO,oBAAoB;QAC1B,IAAI,IAAI,CAAC,wBAAwB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACvD,IAAI,CAAC,wBAAwB,GAAG,KAAK,CAAC;YACtC,IAAI,CAAC,UAAU,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAEO,uBAAuB;QAC7B,IAAI,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YAChC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,eAAe,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;IAEO,qBAAqB,GAAG,GAAS,EAAE;QACzC,IAAI,CAAC,uBAAuB,EAAE,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,yBAAyB,EAAE,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEM,qBAAqB,GAAG,GAAS,EAAE;QACzC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC,CAAC;IAEM,oBAAoB,GAAG,GAAS,EAAE;QACxC,IAAI,CAAC,uBAAuB,EAAE,CAAC;QAC/B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,yBAAyB,EAAE,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC1B,CAAC,CAAC;IAEM,oBAAoB,GAAG,GAAS,EAAE;QACxC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,2EAA2E;QAC3E,+DAA+D;QAC/D,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;YAC3B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;QACD,IAAI,IAAI,CAAC,8BAA8B,EAAE,CAAC;YACxC,IAAI,CAAC,8BAA8B,GAAG,KAAK,CAAC;YAC5C,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAC9B,CAAC,CAAC;IAEM,iBAAiB,GAAG,GAAS,EAAE;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEM,iBAAiB,GAAG,GAAS,EAAE;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,2EAA2E;QAC3E,+CAA+C;QAC/C,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC,CAAC;IAEM,OAAO,GAAG,CAAC,GAAY,EAAQ,EAAE;QACvC,MAAM,IAAI,GAAI,GAA0B,EAAE,IAAuC,CAAC;QAClF,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;QAC7D,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEM,cAAc,GAAG,GAAS,EAAE;QAClC,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEM,kBAAkB,GAAG,GAAS,EAAE;QACtC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpD,uEAAuE;QACvE,yEAAyE;QACzE,mCAAmC;QACnC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC,CAAC;IAEF;;;;;;;OAOG;IACH,MAAM,CAAC,MAAqB;QAC1B,MAAM,eAAe,GAAG,CAAC,GAAY,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;QAClF,MAAM,aAAa,GAA8C;YAC/D,CAAC,WAAW,CAAC,aAAa,EAAE,eAAe,CAAC;YAC5C,CAAC,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,kBAAkB,CAAC;YAChD,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,kBAAkB,CAAC;YAC/C,CAAC,WAAW,CAAC,YAAY,EAAE,IAAI,CAAC,cAAc,CAAC;YAC/C,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;YACjC,CAAC,WAAW,CAAC,mBAAmB,EAAE,IAAI,CAAC,qBAAqB,CAAC;YAC7D,CAAC,WAAW,CAAC,mBAAmB,EAAE,IAAI,CAAC,qBAAqB,CAAC;YAC7D,CAAC,WAAW,CAAC,kBAAkB,EAAE,IAAI,CAAC,oBAAoB,CAAC;YAC3D,CAAC,WAAW,CAAC,kBAAkB,EAAE,IAAI,CAAC,oBAAoB,CAAC;YAC3D,CAAC,WAAW,CAAC,eAAe,EAAE,IAAI,CAAC,iBAAiB,CAAC;YACrD,CAAC,WAAW,CAAC,eAAe,EAAE,IAAI,CAAC,iBAAiB,CAAC;SACtD,CAAC;QACF,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,aAAa;YAAE,MAAM,CAAC,EAAE,CAAC,KAAkB,EAAE,QAAiB,CAAC,CAAC;QAChG,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,aAAa;gBAAE,MAAM,CAAC,GAAG,CAAC,KAAkB,EAAE,QAAiB,CAAC,CAAC;QACnG,CAAC,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,OAAO;QACL,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/dist/arjun.d.ts

@@ -0,0 +1,6 @@
+/** Professional Indian male interviewer, authored to read at call-tile size. */
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+export type { CanvasAvatarOptions };
+export declare function createAvatar(options: CanvasAvatarOptions): AvatarInstance;
+//# sourceMappingURL=arjun.d.ts.map

package/dist/arjun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arjun.d.ts","sourceRoot":"","sources":["../client/arjun.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAGhF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CAOzE"}

package/dist/arjun.js

@@ -0,0 +1,18 @@
+/** Professional Indian male interviewer, authored to read at call-tile size. */
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+const RIG_URL = new URL('../src/canvas/data/interviewer-male.rig.json', import.meta.url);
+const IMAGES = {
+    'round-m3-hair-back.webp': new URL('../src/canvas/data/img/round-m3-hair-back.webp', import.meta.url),
+    'round-m3-top-body.webp': new URL('../src/canvas/data/img/round-m3-top-body.webp', import.meta.url),
+    'round-m3-hair-front.webp': new URL('../src/canvas/data/img/round-m3-hair-front.webp', import.meta.url),
+};
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+export function createAvatar(options) {
+    return createCanvasAvatar(options, {
+        rigUrl: RIG_URL,
+        images: IMAGES,
+        face: FACE,
+        label: 'Arjun — professional male interviewer avatar',
+    });
+}
+//# sourceMappingURL=arjun.js.map

package/dist/arjun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arjun.js","sourceRoot":"","sources":["../client/arjun.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAI7D,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,8CAA8C,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzF,MAAM,MAAM,GAAG;IACb,yBAAyB,EAAE,IAAI,GAAG,CAAC,gDAAgD,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;IACrG,wBAAwB,EAAE,IAAI,GAAG,CAAC,+CAA+C,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;IACnG,0BAA0B,EAAE,IAAI,GAAG,CAAC,iDAAiD,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;CAC/F,CAAC;AACX,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,sCAAsC,CAAC,CAAC;AAIlE,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,OAAO,kBAAkB,CAAC,OAAO,EAAE;QACjC,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,8CAA8C;KACtD,CAAC,CAAC;AACL,CAAC"}

package/dist/createAvatar.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `createAvatar` — the entire public surface of an avatar.
+ *
+ *     const avatar = createAvatar({ mount: el, client: pipecatClient });
+ *     // …
+ *     avatar.destroy();
+ *
+ * An avatar is an embodiment of a `PipecatClient`. You hand it a mount and a
+ * live client; it subscribes and reacts. There is nothing else: no methods to
+ * drive it, no callbacks to observe it, no state to read back. Everything it
+ * needs to know is already on the wire — Pipecat's factual lifecycle events
+ * plus the avatar server-message envelope (docs/contract-wire.md).
+ *
+ * ## This is also the extension point
+ *
+ * There is no registry, no loader and no plug-in system. **You add an avatar by
+ * publishing a module that exports `createAvatar` with this signature**, and
+ * importing yours instead of ours:
+ *
+ *     import { createAvatar } from "@acme/our-mascot";
+ *
+ * That is the whole mechanism, and it is deliberate. A registry would make us
+ * own resolution, versioning and asset paths for code we have never seen; a
+ * renderer interface would make us commit to a second public contract before we
+ * know what the second renderer actually needs. An ES module export we get for
+ * free from the platform.
+ *
+ * Everything past `mount` and `client` belongs to the implementation. Ours takes
+ * `SvgAvatarOptions`; yours takes whatever it likes, and `AvatarFactory<O>` is
+ * generic so the caller still gets your options checked.
+ *
+ * ## What an implementation owes the caller
+ *
+ * Only that `destroy()` leaves the mount as it found it and unsubscribes from
+ * the client. Not returning to rest, not honouring every action, not even
+ * having a mouth — a handless, mouthless avatar that only changes colour is a
+ * conforming avatar. The obligations that *matter* are perceptual, not typed,
+ * and they live in docs/contract-behavior.md.
+ */
+import type { PipecatClient } from "@pipecat-ai/client-js";
+import type { Face, FaceTheme, Gain, HandSide } from "../src/avatar.js";
+export type { Face, FaceTheme, Gain, HandSide };
+/**
+ * What every `createAvatar` takes. Implementations extend it with their own
+ * options; the two named here are the only ones the caller can count on.
+ */
+export interface AvatarOptions {
+    /** The element to render into. The implementation owns its contents. */
+    readonly mount: HTMLElement;
+    /**
+     * A live `PipecatClient`. Required, and not nullable: an avatar with nothing
+     * to embody has no reason to exist yet. React callers get the forgiving
+     * version — `<Avatar>` waits for a non-null client before mounting.
+     */
+    readonly client: PipecatClient;
+}
+/** What every `createAvatar` returns. */
+export interface AvatarInstance {
+    /** Unsubscribe from the client and remove everything from the mount. */
+    destroy(): void;
+}
+/**
+ * The shape a third-party avatar module exports, parameterised by its own
+ * options so a caller passing them gets them checked. `AvatarFactory` bare is
+ * the common denominator — the two options everyone shares.
+ */
+export type AvatarFactory<O extends AvatarOptions = AvatarOptions> = (options: O) => AvatarInstance;
+/**
+ * Options for the bundled SVG avatars — ours alone; nothing outside this
+ * package reads them.
+ *
+ * `face` is a value, not a name: a name needs a table, and a table needs every
+ * face imported to answer any lookup. Import the one you want and the other two
+ * never enter your bundle.
+ *
+ *     import { createAvatar } from "@voqalize/avatar";
+ *     import { wren } from "@voqalize/avatar/faces/wren";
+ *
+ *     createAvatar({ mount, client, face: wren });
+ */
+export interface SvgAvatarOptions extends AvatarOptions {
+    /** Defaults to `peep`, the face this entry point already carries. */
+    readonly face?: Face;
+    /** Palette for that face. Its keys are the face's own; see `THEME` in its
+     * module, and CLAUDE.md on why `peep` has exactly one. */
+    readonly theme?: FaceTheme;
+    /** Viseme amplitude, 0..2. `1` is as authored. */
+    readonly mouthGain?: Gain;
+    /** Gesture-clip amplitude, 0..2. */
+    readonly gestureGain?: Gain;
+    /** Idle/liveness amplitude, 0..2. Low by design — see CLAUDE.md. */
+    readonly motionGain?: Gain;
+    /** Render the frame-edge hand at all. Default true. */
+    readonly hand?: boolean;
+    /** `1` puts it on the viewer's right, `-1` the other side. */
+    readonly handSide?: HandSide;
+}
+export declare function createAvatar(options: SvgAvatarOptions): AvatarInstance;
+//# sourceMappingURL=createAvatar.d.ts.map

package/dist/createAvatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAvatar.d.ts","sourceRoot":"","sources":["../client/createAvatar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAIxE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAC/D,CAAC,OAAO,EAAE,CAAC,KAAK,cAAc,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB;8DAC0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAID,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CA4BtE"}