@voqalize/avatar 0.2.2 → 0.4.0

package/src/behavior.d.ts

@@ -0,0 +1,42 @@
+import type { AvatarStateName } from "./avatar.js";
+
+/** The two renderer calls behavior resolution actually needs. */
+export interface BehaviorAvatar {
+  setState(name: AvatarStateName): unknown;
+  /**
+   * One motion by name. The vocabulary is open — two core intents plus
+   * whatever this avatar publishes — so a name it does not have must be a
+   * no-op rather than a throw.
+   */
+  action(id: string): unknown;
+}
+
+/**
+ * The whole behaviour vocabulary — the nine. Not an alias list; see behavior.js.
+ *
+ * Every one of these is also an `AvatarStateName`, which is why there is no
+ * mapping table any more.
+ */
+export type BehaviorStateId =
+  | "IDLE" | "LISTENING" | "CANT_HEAR" | "THINKING" | "WORKING"
+  | "MUTED" | "SPEAKING" | "DEGRADED" | "OFFLINE";
+
+export type BehaviorActionId = "ack" | "turn.interrupted";
+
+export const BEHAVIOR_STATE_IDS: readonly BehaviorStateId[];
+export const BEHAVIOR_ACTIONS: Readonly<Record<BehaviorActionId, { renderAction: string }>>;
+export const BEHAVIOR_ACTION_IDS: readonly BehaviorActionId[];
+export const WIRE_ACTION_TO_BEHAVIOR: Readonly<Record<string, BehaviorActionId>>;
+
+export class BehaviorController {
+  constructor(avatar: BehaviorAvatar);
+  state: BehaviorStateId | null;
+  setState(id: BehaviorStateId, options?: { force?: boolean }): this;
+  action(id: BehaviorActionId): this;
+  /**
+   * One id off the wire: a core intent through the catalog, anything else
+   * straight to the renderer. Never throws — the vocabulary is open.
+   */
+  wireAction(id: string): this;
+  destroy(): void;
+}

package/src/behavior.js

@@ -0,0 +1,114 @@
+/**
+ * Behavior catalog and controller.
+ *
+ * This is the layer between factual/wire inputs and the bundled SVG renderer.
+ * It is not a seam any avatar implementation sees: an implementation receives
+ * a PipecatClient and decides for itself what a state means.
+ *
+ * The vocabulary is the nine core states and two core actions. The states used
+ * to be seventeen — the core
+ * set plus every SVG render state (TYPING, SEARCHING_SCREEN, WANTS_IN, …)
+ * passed straight through, so that tooling could drive one of *those* from
+ * here. That made the mixer's private state list look like part of the
+ * behaviour vocabulary. Tooling that wants a render state calls
+ * `avatar.setState` on the mixer, which is whose state it is.
+ */
+
+/**
+ * The durable states this layer resolves. Each one *is* the render state it
+ * asks the bundled SVG mixer for, so there is nothing here to map.
+ *
+ * There used to be a second column — a per-state `renderState`, so a renderer
+ * could draw `WORKING` as anything it liked and the divergence would land here
+ * rather than leak. In nine rows it had exactly one non-identity entry,
+ * `STRAINING -> CANT_HEAR`, and the wire redesign deleted that entry by
+ * renaming the state: a state names the bot's *situation*, never how it looks,
+ * and "straining" was a situation named after one drawing of it. A table whose
+ * every row reads `X: X` documents nothing and invites a renderer to plug into
+ * it, so it is a list now. A renderer that genuinely wants to draw one of these
+ * as something else calls `avatar.setState` with the render state it wants,
+ * which is whose state that is.
+ */
+export const BEHAVIOR_STATE_IDS = Object.freeze([
+  'IDLE', 'LISTENING', 'CANT_HEAR', 'THINKING', 'WORKING',
+  'MUTED', 'SPEAKING', 'DEGRADED', 'OFFLINE',
+]);
+
+const STATE_IDS = new Set(BEHAVIOR_STATE_IDS);
+
+/**
+ * Library action IDs: the two intents every renderer owes a server, in this
+ * layer's readable spelling.
+ *
+ * It used to be seven, with a `sequence` command alongside for a renderer's own
+ * motions. The seven were not the wrong *names* so much as the wrong idea: four
+ * of them were `GESTURE_*` — a greet, a goodbye, a wave — which are things a
+ * particular body does and not intents a server can hold every face to, and two
+ * were the receipt and the nod, which are two *shapes* of acknowledging. So the
+ * server now says only that an acknowledgement is due, the avatar picks which
+ * one it makes, and the gestures live in whichever catalogue can draw them,
+ * reachable by the same open `action` id a sequence used to need its own
+ * command for.
+ */
+export const BEHAVIOR_ACTIONS = Object.freeze({
+  ack: { renderAction: 'ACKNOWLEDGE' },
+  'turn.interrupted': { renderAction: 'RESPONSE_INTERRUPTED' },
+});
+
+export const BEHAVIOR_ACTION_IDS = Object.freeze(Object.keys(BEHAVIOR_ACTIONS));
+
+/** The two core wire names map into the behavior catalog here and nowhere else. */
+export const WIRE_ACTION_TO_BEHAVIOR = Object.freeze({
+  ACKNOWLEDGE: 'ack',
+  RESPONSE_INTERRUPTED: 'turn.interrupted',
+});
+
+/**
+ * Turns behavior intent into the legacy SVG mixer's calls. A future renderer
+ * receives the same intent through its own adapter; it does not need to know
+ * the legacy state/action names used below.
+ */
+export class BehaviorController {
+  constructor(avatar) {
+    if (!avatar || typeof avatar.setState !== 'function' || typeof avatar.action !== 'function') {
+      throw new TypeError('BehaviorController requires an avatar implementation');
+    }
+    this.avatar = avatar;
+    this.state = null;
+  }
+
+  setState(id, { force = false } = {}) {
+    if (!STATE_IDS.has(id)) throw new Error(`unknown behavior state: ${id}`);
+    if (!force && this.state === id) return this;
+    this.state = id;
+    this.avatar.setState(id);
+    return this;
+  }
+
+  destroy() {}
+
+  action(id) {
+    const def = BEHAVIOR_ACTIONS[id];
+    if (!def) throw new Error(`unknown behavior action: ${id}`);
+    this.avatar.action(def.renderAction);
+    return this;
+  }
+
+  /**
+   * One id off the wire. A core one goes through the behavior catalog; any
+   * other goes straight to the renderer, and that asymmetry is the point.
+   * `BEHAVIOR_ACTIONS` exists so a portable intent has a readable name
+   * independent of how any one face renders it. An avatar's own id has no such
+   * independence — it *is* the rendering, named by the renderer that owns it —
+   * so giving it a behavior alias would claim a portability it does not have.
+   *
+   * Neither path throws. The wire's action vocabulary is open and an id this
+   * face cannot draw is the expected case, not somebody's broken build.
+   */
+  wireAction(id) {
+    const behaviorId = WIRE_ACTION_TO_BEHAVIOR[id];
+    if (behaviorId) return this.action(behaviorId);
+    this.avatar.action(id);
+    return this;
+  }
+}

package/src/camera.js

@@ -0,0 +1,29 @@
+/**
+ * The close webcam crop shared by every avatar renderer.
+ *
+ * The head gets most of the tile because lip sync and listening expressions
+ * are the information the avatar is there to carry. The remaining lower band
+ * leaves enough neck and shoulder for posture to read without turning the
+ * call tile into a half-body portrait.
+ */
+export const CALL_CAMERA = Object.freeze({
+  aspect: 4 / 3,
+  headroom: 0.06,
+  head: 0.70,
+  body: 0.24,
+});
+
+/** Derive a camera rectangle from three landmarks in the drawing's own units. */
+export function viewBoxForHead({ centerX, crownY, chinY }) {
+  if (![centerX, crownY, chinY].every(Number.isFinite) || chinY <= crownY) {
+    throw new TypeError('viewBoxForHead: expected a finite centre and crown above chin');
+  }
+  const h = (chinY - crownY) / CALL_CAMERA.head;
+  const w = h * CALL_CAMERA.aspect;
+  return {
+    x: centerX - w / 2,
+    y: crownY - h * CALL_CAMERA.headroom,
+    w,
+    h,
+  };
+}