@voqalize/avatar 0.2.2 → 0.4.0

package/assets/README.md

@@ -0,0 +1,48 @@
+# The character binaries
+
+Three 2.5-D characters, one compiled file each:
+
+| file | character | what it is |
+|---|---|---|
+| `tara.glb` | tara | the first; shallow geometry under a projected portrait |
+| `tushar.glb` | tushar | the second, her scripts with his landmarks |
+| `tanya.glb` | tanya | the third, built from supplied reference images |
+
+They are loaded for you. `@voqalize/avatar/avatars/tara` resolves the file beside
+itself and hands it to a loader; you never name a path, and the only reason to
+know these are here is the licence below. `three` is an *optional* peer of this
+package, so importing a drawing instead of a character downloads none of this.
+
+Each file carries geometry, one morph target per pose channel, and its texture
+atlases as WebP — which is most of the bytes, because the atlases are
+photographs. **They are build outputs. Do not hand-edit one**; there is nothing
+in this directory to regenerate it from, and the next release overwrites it.
+
+## Licence: CC-BY 4.0
+
+The rest of this package is MIT. These three files are artwork, not code, so they
+carry an artwork licence: **Creative Commons Attribution 4.0 International**, the
+full text in `LICENSE-CC-BY-4.0` at the package root. Use them in a product,
+commercially, modified or retextured, and credit us:
+
+> Character art © 2026 Voqalize, CC-BY 4.0.
+
+That is the whole obligation. There is no non-commercial clause, no
+no-derivatives clause — the renderer's entire job is deforming these meshes, so a
+no-derivatives licence would forbid the only use there is — and no share-alike, so
+retexturing a character does not oblige you to publish the result.
+
+The licence is also written inside each file, in the glTF copyright field. A
+binary gets copied out of a dependency tree and passed around; a string in the
+file is the only way terms travel with it.
+
+## The faces are synthetic
+
+Every character began as an image from a generative model — OpenAI's and
+Google's — and **none of them depicts a real person**. Any resemblance to one is
+coincidence, not a likeness, and there are no personality rights attached to any
+of these three. What we did with that image is ours: the geometry, the measured
+landmarks, the projection, the relighting and the authored morph targets are all
+human work, and they are the substance of what is licensed here.
+
+The tooling that turns a portrait into one of these files is not published.

package/client/Avatar.tsx

@@ -0,0 +1,57 @@
+/**
+ * Avatar — `createAvatar` as a call tile, and the whole of `@voqalize/avatar/react`.
+ *
+ *     <Avatar client={session.client} className="avatar-tile" />
+ *
+ * Three props of its own; everything else is forwarded to the mount `<div>`, so
+ * it sizes and styles like the tile it lives in. There is nothing to configure
+ * because there is nothing the server does not already say: the
+ * `AvatarProcessor` in the pipeline drives the state, the gaze and the mouth.
+ *
+ * `create` is how you use a different avatar — any module exporting
+ * `createAvatar` (docs/design-avatar-interface.md), including a Rive or WebGL
+ * one. The component is generic over that implementation's options, so
+ * `options` is checked against the factory you passed rather than being a bag:
+ *
+ *     <Avatar client={c} create={createMascot} options={{ mood: "sly" }} />
+ *
+ * With no `create` it is the bundled SVG avatar and `options` is
+ * `SvgAvatarOptions` minus `mount`/`client`, which the component supplies.
+ *
+ * The component renders an empty div and a static `role="img"`. It does not
+ * label the avatar with its current state: the implementation owns the DOM
+ * inside the mount and is the only thing that knows what it is portraying —
+ * and a live label would be this package reading back an avatar's internal
+ * state, which is the one thing the interface refuses to promise. Pass your
+ * own `aria-label` to override.
+ */
+
+import type { HTMLAttributes } from "react";
+import type { PipecatClient } from "@pipecat-ai/client-js";
+import { useAvatar } from "./useAvatar.js";
+import type { AvatarFactory, AvatarOptions, SvgAvatarOptions } from "./createAvatar.js";
+
+/** An implementation's own options: everything it takes past the two the
+ * component supplies itself. */
+export type ImplementationOptions<O extends AvatarOptions> = Omit<O, keyof AvatarOptions>;
+
+export type AvatarProps<O extends AvatarOptions = SvgAvatarOptions> =
+  Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The live `PipecatClient`, or `null` before connect. Nothing renders
+     * until it is non-null. */
+    client?: PipecatClient | null;
+    /** An avatar implementation. Omit for the bundled SVG faces. */
+    create?: AvatarFactory<O>;
+    /** Options for that implementation. Read at mount only. */
+    options?: ImplementationOptions<O>;
+  };
+
+export function Avatar<O extends AvatarOptions = SvgAvatarOptions>({
+  client,
+  create,
+  options,
+  ...rest
+}: AvatarProps<O>) {
+  const { containerRef } = useAvatar<O>({ client, create, options });
+  return <div role="img" aria-label="avatar" {...rest} ref={containerRef} />;
+}