realtime-avatar 0.9.1 → 0.11.0

package/README.md

@@ -96,12 +96,11 @@ rta.retimeAnchor(avatarId, anchorTimeMs)                    // same loop, differ
 rta.deleteAvatar(avatarId)
 
 // clip library — declared as JSON, never as URLs
-rta.setClipLibrary(avatarId, { clips, expectedRevision? })  // declare the FULL set; CAS via expectedRevision
+rta.setClipLibrary(avatarId, { expectedRevision, clips, idle?, on?, actions? })  // full source record + behavior; revision required
 rta.setLoop(avatarId, { motionPrompt })     // re-direct the RESTING LOOP; clips untouched
 rta.waitForLoop(avatarId)               // block until it settles; THROWS if it failed
 rta.waitForClips(avatarId)              // block until nothing is still rendering
 rta.listClips(avatarId)                 // rows + revision, anchor, eligibility
-rta.syncClips(avatarId, clipUrls)       // DEPRECATED — external-URL tier; use setClipLibrary
 
 // assets
 rta.createRemoteAsset({ kind, remoteUrl })

package/dist/browser.d.ts

@@ -1,5 +1,15 @@
 export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, P as PlayoutDelayTarget, a as applyAvatarPlayoutDelay, b as applyPlayoutDelay } from './playout-delay-DWOc8iCl.js';
 
+type VideoSupport = {
+    supported: true;
+} | {
+    supported: false;
+    reason: "webrtc_unavailable" | "codec_unavailable";
+    message: string;
+};
+/** Check before starting a billed video session; this does not prove negotiated playback. */
+declare function checkVideoSupport(codec?: string): VideoSupport;
+
 /**
  * Turning the microphone on, and saying what went wrong when it does not.
  *
@@ -241,4 +251,4 @@ type BoomerangPlayback = {
  */
 declare function attachBoomerangPlayback(video: HTMLVideoElement, options?: BoomerangPlaybackOptions): BoomerangPlayback;
 
-export { type AttachRemoteAudioOptions, type AttachableTrack, type AudioCapableRoom, type BoomerangPlayback, type BoomerangPlaybackOptions, type EnableMicrophoneOptions, type MicrophoneCapableRoom, type MicrophoneFailureReason, type MicrophoneResult, type PreparableParticipant, type PreparableRoom, type PrepareAvatarRoomOptions, type PreparedAvatarRoom, type RemoteAudioAttachment, attachBoomerangPlayback, attachRemoteAudio, enableMicrophone, prepareAvatarRoom };
+export { type AttachRemoteAudioOptions, type AttachableTrack, type AudioCapableRoom, type BoomerangPlayback, type BoomerangPlaybackOptions, type EnableMicrophoneOptions, type MicrophoneCapableRoom, type MicrophoneFailureReason, type MicrophoneResult, type PreparableParticipant, type PreparableRoom, type PrepareAvatarRoomOptions, type PreparedAvatarRoom, type RemoteAudioAttachment, type VideoSupport, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, enableMicrophone, prepareAvatarRoom };

package/dist/browser.js

@@ -1,3 +1,15 @@
+// ../browser/src/video-support.ts
+function checkVideoSupport(codec = "h264") {
+  if (typeof RTCRtpReceiver === "undefined") {
+    return { supported: false, reason: "webrtc_unavailable", message: "This browser does not support realtime media." };
+  }
+  const codecs = RTCRtpReceiver.getCapabilities("video")?.codecs ?? [];
+  if (!codecs.some((entry) => entry.mimeType.toLowerCase() === `video/${codec.toLowerCase()}`)) {
+    return { supported: false, reason: "codec_unavailable", message: `This browser cannot receive ${codec.toUpperCase()} video. Use a browser with that codec before starting a video call.` };
+  }
+  return { supported: true };
+}
+
 // ../browser/src/microphone.ts
 var HINTS = {
   "insecure-origin": "The browser only exposes microphones on a secure origin. Serve the page over https, or open it on http://localhost \u2014 a LAN address like http://192.168.1.5 will not do.",
@@ -241,4 +253,4 @@ function now() {
   return typeof performance !== "undefined" ? performance.now() : Date.now();
 }
 
-export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, applyAvatarPlayoutDelay, applyPlayoutDelay, attachBoomerangPlayback, attachRemoteAudio, enableMicrophone, prepareAvatarRoom };
+export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, applyAvatarPlayoutDelay, applyPlayoutDelay, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, enableMicrophone, prepareAvatarRoom };

package/dist/{chunk-F7E4HMBW.js → chunk-MBQ2VKLC.js}

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 // ../http-client/src/errors.ts
 var RealtimeAvatarError = class extends Error {
   constructor(message, options) {
@@ -21,6 +23,179 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
     return this.status === 402;
   }
 };
+var motionIdSchema = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/).refine((value) => !["__proto__", "constructor", "prototype"].includes(value), "Reserved identifier");
+function motionRecord(valueSchema) {
+  const record = z.record(motionIdSchema, valueSchema);
+  return z.transform((value, ctx) => {
+    if (value !== null && typeof value === "object" && Object.hasOwn(value, "__proto__")) {
+      ctx.addIssue({ code: "custom", path: ["__proto__"], message: "Reserved identifier" });
+    }
+    return value;
+  }).pipe(record);
+}
+var clipSourceSchema = z.union([
+  z.strictObject({ assetId: z.string().trim().min(1).max(160) }),
+  z.strictObject({
+    motionPrompt: z.string().trim().min(1).max(1200),
+    durationSeconds: z.int().min(4).max(8).optional()
+  })
+]);
+var clipDeclarationSchema = z.strictObject({ source: clipSourceSchema });
+var clipListSchema = z.array(motionIdSchema).min(1).max(32).superRefine((clips, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  clips.forEach((clip, index) => {
+    if (seen.has(clip)) {
+      ctx.addIssue({ code: "custom", path: [index], message: `"${clip}" is already a candidate here` });
+    }
+    seen.add(clip);
+  });
+});
+var idleSchema = z.strictObject({
+  clips: clipListSchema,
+  weight: z.number().min(0).max(100).optional()
+});
+var clipActionSchema = z.strictObject({
+  description: z.string().trim().min(1).max(512),
+  clips: clipListSchema
+});
+var clipBehaviorFields = z.strictObject({
+  idle: idleSchema.optional(),
+  /** AUTOMATIC — one reaction per speech episode, then back to idle. */
+  on: z.strictObject({
+    userSpeechStarted: z.strictObject({ clips: clipListSchema }).optional()
+  }).optional(),
+  /** REQUESTABLE, not automatic: declaring an action does not play it. */
+  actions: motionRecord(clipActionSchema).optional()
+});
+var clipBehaviorSchema = clipBehaviorFields;
+function* clipReferences(behavior) {
+  if (behavior.idle) yield { clips: behavior.idle.clips, path: ["idle", "clips"] };
+  const listening = behavior.on?.userSpeechStarted;
+  if (listening) yield { clips: listening.clips, path: ["on", "userSpeechStarted", "clips"] };
+  for (const [id, action] of Object.entries(behavior.actions ?? {})) {
+    yield { clips: action.clips, path: ["actions", id, "clips"] };
+  }
+}
+var clipLibraryDeclarationSchema = z.strictObject({
+  /** CAS against the served revision: two editors cannot silently overwrite each other. */
+  expectedRevision: z.int().nonnegative(),
+  /** The complete desired media set. Anything omitted is retired. */
+  clips: motionRecord(clipDeclarationSchema).nonoptional(),
+  ...clipBehaviorFields.shape
+}).superRefine((library, ctx) => {
+  if (Object.hasOwn(library.clips, "primary")) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["clips", "primary"],
+      message: "The avatar's stored source is the rest state and is not declared \u2014 pick another id"
+    });
+  }
+  for (const { clips, path } of clipReferences(library)) {
+    clips.forEach((clip, index) => {
+      if (Object.hasOwn(library.clips, clip)) return;
+      ctx.addIssue({ code: "custom", path: [...path, index], message: `Unknown clip "${clip}"` });
+    });
+  }
+});
+z.strictObject({
+  avatar_id: z.string().min(1).max(160),
+  queue_ticket_id: z.string().min(1).max(160).optional(),
+  max_session_seconds: z.int().positive().max(180)
+});
+z.object({
+  avatarId: z.string(),
+  name: z.string(),
+  poster: z.string().url().nullable(),
+  idleUrl: z.string().url(),
+  revision: z.int().nonnegative(),
+  behavior: clipBehaviorSchema,
+  clips: z.array(z.strictObject({ id: motionIdSchema, url: z.url() }))
+}).strict();
+var schema0 = z.string();
+var schema1 = z.enum(["queued", "generating", "ready", "failed"]);
+var schema2 = z.url();
+var schema3 = z.null();
+var schema4 = z.union([schema2, schema3]);
+var schema5 = z.enum(["generated", "uploaded"]);
+var schema6 = z.union([schema0, schema3]);
+var schema7 = z.int().min(-9007199254740991).max(9007199254740991);
+var schema8 = z.union([schema7, schema3]);
+var schema9 = z.boolean();
+var schema10 = z.number().min(0).max(1);
+var schema11 = z.strictObject({
+  "sameSubject": schema9,
+  "firstFrameMatchesAnchor": schema9,
+  "lastFrameMatchesAnchor": schema9,
+  "framingComparable": schema9,
+  "confidence": schema10
+});
+var schema12 = z.array(schema0);
+var schema13 = z.strictObject({
+  "verdict": schema11,
+  "issues": schema12,
+  "firstFrameUrl": schema4,
+  "lastFrameUrl": schema4,
+  "trimStartMs": schema8,
+  "trimEndMs": schema8
+});
+var schema14 = z.union([schema13, schema3]);
+var schema15 = z.strictObject({
+  "code": schema0,
+  "message": schema0
+});
+var schema16 = z.union([schema15, schema3]);
+var schema17 = z.strictObject({
+  "clipId": schema0,
+  "status": schema1,
+  "url": schema4,
+  "source": schema5,
+  "uploadAssetId": schema6,
+  "motionPrompt": schema6,
+  "durationSeconds": schema8,
+  "anchorVersion": schema7,
+  "poseCheck": schema14,
+  "error": schema16,
+  "createdAt": schema0,
+  "updatedAt": schema0
+});
+var schema18 = z.array(schema17);
+var schema19 = z.int().min(0).max(9007199254740991);
+var schema20 = z.int().min(1).max(9007199254740991);
+var schema21 = z.enum(["portrait", "source_frame"]);
+var schema22 = z.strictObject({
+  "url": schema2,
+  "source": schema21,
+  "timeMs": schema8
+});
+var schema23 = z.union([schema22, schema3]);
+var schema24 = z.strictObject({
+  "data": schema18,
+  "avatarId": schema0,
+  "revision": schema19,
+  "anchorVersion": schema20,
+  "anchor": schema23,
+  "clipLibraryEligible": schema9,
+  "defaultSourceAssetId": schema6,
+  "behavior": clipBehaviorSchema
+});
+var schema25 = z.strictObject({
+  "kept": schema12,
+  "queued": schema12,
+  "retired": schema12
+});
+var schema26 = z.strictObject({
+  "data": schema18,
+  "avatarId": schema0,
+  "revision": schema19,
+  "anchorVersion": schema20,
+  "anchor": schema23,
+  "clipLibraryEligible": schema9,
+  "defaultSourceAssetId": schema6,
+  "behavior": clipBehaviorSchema,
+  "plan": schema25
+});
+var clipLibraryResponseSchema = schema24;
+var clipLibraryUpdateSchema = schema26;
 
 // ../http-client/src/retry.ts
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 500, 502, 503, 504]);
@@ -43,7 +218,7 @@ function isTransient(cause) {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.9.1";
+var SDK_VERSION = "0.11.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -280,49 +455,20 @@ var RealtimeAvatar = class {
   async deleteAvatar(avatarId) {
     await this.#json(await this.#request("DELETE", `/avatars/${avatarId}`));
   }
-  // A clip envelope missing `revision` would silently drop `expectedRevision` from the
-  // next declare — CAS degrades to unconditional with zero signal — so it throws instead.
-  #clipEnvelope(out) {
-    if (typeof out.revision !== "number" || !Array.isArray(out.data)) {
-      throw new RealtimeAvatarError("clip library response did not match the contract");
-    }
-    return out;
-  }
-  /**
-   * Declare the avatar's full desired clip library — a declaration, not a delta. The
-   * platform reconciles it against what exists: unchanged clips are `kept` (still
-   * serving), new or changed ones are `queued` to render, and clips you dropped are
-   * `retired`. The 202 is acceptance, not readiness — poll `listClips` until no row is
-   * `queued` or `generating`. A rejected upload settles `failed`, which is terminal, so
-   * waiting for all-`ready` waits forever. While a re-render is in flight the previous
-   * take keeps serving, so a declaration never blanks a live avatar.
-   *
-   * `expectedRevision` is compare-and-set: pass the `revision` you last read and a
-   * concurrent writer surfaces as a 409 instead of a lost update. Omit it to declare
-   * unconditionally.
-   *
-   * At most 20 clips: up to eight `idle`, up to two `listen`, the rest `gesture`. Several
-   * idles are a resting ROTATION she drifts between, not alternatives to one. An uploaded
-   * clip (`source: { assetId }`) must start AND end on the avatar's rest pose — pose
-   * validation rejects it otherwise (`status: "failed"`, the verdict in `poseCheck`),
-   * and the rest of the library is untouched.
-   */
+  /** Reconcile the complete source registry and behavior; 202 accepts work, not media readiness. */
   async setClipLibrary(avatarId, library) {
-    const body = { clips: library.clips };
-    if (library.expectedRevision !== void 0) body.expectedRevision = library.expectedRevision;
-    return this.#clipEnvelope(
-      await this.#json(
-        await this.#request("PUT", `/avatars/${avatarId}/clips`, { json: body })
-      )
-    );
+    const response = clipLibraryUpdateSchema.safeParse(await this.#json(
+      await this.#request("PUT", `/avatars/${avatarId}/clips`, { json: library })
+    ));
+    if (!response.success) throw new RealtimeAvatarError("clip library response did not match the contract");
+    return response.data;
   }
   /**
    * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
    * a new one-sentence description.
    *
-   * Not a clip, and this is the distinction integrations get wrong: a clip with
-   * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
-   * she rests in. This is the only thing that does.
+   * This changes the stored source — the implicit rest state — not the declared idle
+   * variations or ordinary clip assets.
    *
    * `202`, because the render takes minutes. Three properties, all measured against a real
    * render rather than asserted:
@@ -406,32 +552,11 @@ var RealtimeAvatar = class {
   }
   /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
   async listClips(avatarId) {
-    return this.#clipEnvelope(
-      await this.#json(
-        await this.#request("GET", `/avatars/${avatarId}/clips`)
-      )
-    );
-  }
-  /**
-   * Reconcile an avatar's clip set after it changes.
-   *
-   * Required, not optional: clips are prepared once and cached by URL hash, and the serve
-   * path only LOADS that cache. A clip that has never been prepared silently does nothing on
-   * the first call after you add it. Idempotent, so calling it on every write is cheap.
-   *
-   * **At most 32 URLs per call.** This is the whole set for the avatar, not a delta, and the
-   * endpoint rejects an oversize list rather than truncating it — so a library that outgrows
-   * 32 needs the set trimmed, not split across two calls.
-   *
-   * @deprecated The externally-hosted clip tier this serves is sunsetting. Declare the
-   * library with {@link setClipLibrary} instead — the platform renders and hosts the
-   * clips, and pose-validates uploads against the avatar's rest pose.
-   */
-  async syncClips(avatarId, clipUrls) {
-    const out = await this.#json(
-      await this.#request("POST", `/avatars/${avatarId}/clips`, { json: { clipUrls } })
-    );
-    return { queued: out.queued ?? [], ready: out.ready ?? [], retired: out.retired ?? [] };
+    const response = clipLibraryResponseSchema.safeParse(await this.#json(
+      await this.#request("GET", `/avatars/${avatarId}/clips`)
+    ));
+    if (!response.success) throw new RealtimeAvatarError("clip library response did not match the contract");
+    return response.data;
   }
   // ── assets ───────────────────────────────────────────────────────────────
   /** Hand us a URL and we stream it into storage. Prefer this for anything large. */
@@ -582,20 +707,6 @@ function videoToWire(video) {
     }
     out.support_edits = edits;
   }
-  if (video.states) {
-    out.clip_library = Object.entries(video.states).map(([id, state]) => {
-      const clip = {
-        clip_id: id,
-        source_video_url: state.url,
-        trigger: "directive",
-        // `when` is the public name for this cue. The wire also still accepts the older
-        // `hint`; send one name only, and prefer the one the docs and types use.
-        when: state.when
-      };
-      if (state.weight !== void 0) clip.weight = state.weight;
-      return clip;
-    });
-  }
   return out;
 }
 function toAvatar(raw) {
@@ -680,4 +791,4 @@ function isQueued(result) {
   return "queued" in result;
 }
 
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, isQueued, verifyTranscript };
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript };

package/dist/{chunk-FTAD423K.js → chunk-RVBBZCVM.js}

@@ -1,4 +1,4 @@
-import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-F7E4HMBW.js';
+import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-MBQ2VKLC.js';
 
 // ../proxy/src/config.ts
 var json = (body, status = 200) => new Response(JSON.stringify(body), {

package/dist/express.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-QoMHpR1h.js';
-import './types-D_aIKv4P.js';
+import { P as ProxyConfig } from './types-DrgyCwLC.js';
+import './types-FoJMJimV.js';
 
 type Expressish = {
     method: string;

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-FTAD423K.js';
-import './chunk-F7E4HMBW.js';
+import { createProxyHandler } from './chunk-RVBBZCVM.js';
+import './chunk-MBQ2VKLC.js';
 
 // ../proxy/src/express.ts
 function realtimeAvatarExpress(config) {

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-QoMHpR1h.js';
-import './types-D_aIKv4P.js';
+import { P as ProxyConfig } from './types-DrgyCwLC.js';
+import './types-FoJMJimV.js';
 
 /**
  * Hono (and anything else built on Fetch handlers — Workers, Bun, Deno).

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-FTAD423K.js';
-import './chunk-F7E4HMBW.js';
+import { createProxyHandler } from './chunk-RVBBZCVM.js';
+import './chunk-MBQ2VKLC.js';
 
 // ../proxy/src/hono.ts
 function realtimeAvatarHono(config) {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as ClipSyncResult, h as AssetKind, i as Asset, j as ListSessionsOptions, U as UsageSessionPage, k as UsageSession, l as CreditBalance, T as TranscriptPayload } from './types-D_aIKv4P.js';
-export { m as AvatarClip, n as CallConnection, o as CallQueued, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as VideoState, u as isQueued } from './types-D_aIKv4P.js';
+import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as CreditBalance, T as TranscriptPayload } from './types-FoJMJimV.js';
+export { l as AvatarClip, m as CallConnection, n as CallQueued, o as ClipDeclaration, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as isQueued } from './types-FoJMJimV.js';
+import { z } from 'zod';
 
 interface RealtimeAvatarOptions {
     /** `tic_live_…` or `tic_test_…`. Server-side only — never ship this to a browser. */
@@ -169,36 +170,14 @@ declare class RealtimeAvatar {
      */
     retimeAnchor(avatarId: string, anchorTimeMs: number): Promise<Avatar>;
     deleteAvatar(avatarId: string): Promise<void>;
-    /**
-     * Declare the avatar's full desired clip library — a declaration, not a delta. The
-     * platform reconciles it against what exists: unchanged clips are `kept` (still
-     * serving), new or changed ones are `queued` to render, and clips you dropped are
-     * `retired`. The 202 is acceptance, not readiness — poll `listClips` until no row is
-     * `queued` or `generating`. A rejected upload settles `failed`, which is terminal, so
-     * waiting for all-`ready` waits forever. While a re-render is in flight the previous
-     * take keeps serving, so a declaration never blanks a live avatar.
-     *
-     * `expectedRevision` is compare-and-set: pass the `revision` you last read and a
-     * concurrent writer surfaces as a 409 instead of a lost update. Omit it to declare
-     * unconditionally.
-     *
-     * At most 20 clips: up to eight `idle`, up to two `listen`, the rest `gesture`. Several
-     * idles are a resting ROTATION she drifts between, not alternatives to one. An uploaded
-     * clip (`source: { assetId }`) must start AND end on the avatar's rest pose — pose
-     * validation rejects it otherwise (`status: "failed"`, the verdict in `poseCheck`),
-     * and the rest of the library is untouched.
-     */
-    setClipLibrary(avatarId: string, library: {
-        clips: readonly ClipDeclaration[];
-        expectedRevision?: number;
-    }): Promise<ClipLibraryUpdate>;
+    /** Reconcile the complete source registry and behavior; 202 accepts work, not media readiness. */
+    setClipLibrary(avatarId: string, library: ClipLibraryDeclaration): Promise<ClipLibraryUpdate>;
     /**
      * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
      * a new one-sentence description.
      *
-     * Not a clip, and this is the distinction integrations get wrong: a clip with
-     * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
-     * she rests in. This is the only thing that does.
+     * This changes the stored source — the implicit rest state — not the declared idle
+     * variations or ordinary clip assets.
      *
      * `202`, because the render takes minutes. Three properties, all measured against a real
      * render rather than asserted:
@@ -252,22 +231,6 @@ declare class RealtimeAvatar {
     }): Promise<ClipLibrary>;
     /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
     listClips(avatarId: string): Promise<ClipLibrary>;
-    /**
-     * Reconcile an avatar's clip set after it changes.
-     *
-     * Required, not optional: clips are prepared once and cached by URL hash, and the serve
-     * path only LOADS that cache. A clip that has never been prepared silently does nothing on
-     * the first call after you add it. Idempotent, so calling it on every write is cheap.
-     *
-     * **At most 32 URLs per call.** This is the whole set for the avatar, not a delta, and the
-     * endpoint rejects an oversize list rather than truncating it — so a library that outgrows
-     * 32 needs the set trimmed, not split across two calls.
-     *
-     * @deprecated The externally-hosted clip tier this serves is sunsetting. Declare the
-     * library with {@link setClipLibrary} instead — the platform renders and hosts the
-     * clips, and pose-validates uploads against the avatar's rest pose.
-     */
-    syncClips(avatarId: string, clipUrls: readonly string[]): Promise<ClipSyncResult>;
     /** Hand us a URL and we stream it into storage. Prefer this for anything large. */
     createRemoteAsset(input: {
         kind: AssetKind;
@@ -365,4 +328,49 @@ declare function verifyTranscript(rawBody: Uint8Array | string, headers: Headers
     toleranceSeconds?: number;
 }): Promise<TranscriptPayload>;
 
-export { Asset, AssetKind, Avatar, AvatarSourceSwap, AvatarUpdate, CallMode, CallPolicy, ClipDeclaration, ClipLibrary, ClipLibraryUpdate, ClipSyncResult, CreditBalance, EndCallOptions, ListSessionsOptions, LoopRedirect, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, type RealtimeAvatarOptions, type StartCallOptions, StartCallResult, TranscriptPayload, UsageSession, UsageSessionPage, verifyTranscript };
+declare const clipLibraryDeclarationSchema: z.ZodObject<{
+    idle: z.ZodOptional<z.ZodObject<{
+        clips: z.ZodArray<z.ZodString>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    on: z.ZodOptional<z.ZodObject<{
+        userSpeechStarted: z.ZodOptional<z.ZodObject<{
+            clips: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    actions: z.ZodOptional<z.ZodPipe<z.ZodTransform<Record<string, {
+        description: string;
+        clips: string[];
+    }>, Record<string, {
+        description: string;
+        clips: string[];
+    }>>, z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        clips: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>>;
+    expectedRevision: z.ZodInt;
+    clips: z.ZodNonOptional<z.ZodPipe<z.ZodTransform<Record<string, {
+        source: {
+            assetId: string;
+        } | {
+            motionPrompt: string;
+            durationSeconds?: number | undefined;
+        };
+    }>, Record<string, {
+        source: {
+            assetId: string;
+        } | {
+            motionPrompt: string;
+            durationSeconds?: number | undefined;
+        };
+    }>>, z.ZodRecord<z.ZodString, z.ZodObject<{
+        source: z.ZodUnion<readonly [z.ZodObject<{
+            assetId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            motionPrompt: z.ZodString;
+            durationSeconds: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>;
+
+export { Asset, AssetKind, Avatar, AvatarSourceSwap, AvatarUpdate, CallMode, CallPolicy, ClipLibrary, ClipLibraryDeclaration, ClipLibraryUpdate, CreditBalance, EndCallOptions, ListSessionsOptions, LoopRedirect, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, type RealtimeAvatarOptions, type StartCallOptions, StartCallResult, TranscriptPayload, UsageSession, UsageSessionPage, clipLibraryDeclarationSchema, verifyTranscript };

package/dist/index.js

@@ -1 +1 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, isQueued, verifyTranscript } from './chunk-F7E4HMBW.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-MBQ2VKLC.js';

package/dist/nextjs.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-QoMHpR1h.js';
-import './types-D_aIKv4P.js';
+import { P as ProxyConfig } from './types-DrgyCwLC.js';
+import './types-FoJMJimV.js';
 
 /**
  * App Router. Mount at `app/api/realtime-avatar/[...path]/route.ts`:

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-FTAD423K.js';
-import './chunk-F7E4HMBW.js';
+import { createProxyHandler } from './chunk-RVBBZCVM.js';
+import './chunk-MBQ2VKLC.js';
 
 // ../proxy/src/nextjs.ts
 function createRealtimeAvatarRoute(config) {

package/dist/{proxy-client-DlYBC6cp.d.ts → proxy-client-CWvT16wz.d.ts}

@@ -101,11 +101,6 @@ declare const sessionClipSchema: z.ZodObject<{
 type SessionClip = z.infer<typeof sessionClipSchema>;
 declare const sessionBehaviorSchema: z.ZodObject<{
     gestures_enabled: z.ZodOptional<z.ZodBoolean>;
-    gesture_freq: z.ZodOptional<z.ZodEnum<{
-        sparse: "sparse";
-        balanced: "balanced";
-        lively: "lively";
-    }>>;
 }, z.core.$strict>;
 type SessionBehavior = z.infer<typeof sessionBehaviorSchema>;
 /**
@@ -206,11 +201,6 @@ declare const liveKitSessionRequestSchema: z.ZodObject<{
     }, z.core.$strict>>>;
     behavior: z.ZodOptional<z.ZodObject<{
         gestures_enabled: z.ZodOptional<z.ZodBoolean>;
-        gesture_freq: z.ZodOptional<z.ZodEnum<{
-            sparse: "sparse";
-            balanced: "balanced";
-            lively: "lively";
-        }>>;
     }, z.core.$strict>>;
     renderBackend: z.ZodOptional<z.ZodString>;
     supportEdits: z.ZodOptional<z.ZodObject<{
@@ -407,6 +397,8 @@ type AvatarVideoSurfaceProps = {
      * avatars with no idle clip; the poster floor then shows at rest.
      */
     idleVideoUrl: string | null;
+    /** Reports presented-layer changes, not the agent's requested speaking state. */
+    onLiveVisibilityChange?: (visible: boolean) => void;
     /**
      * The avatar's PORTRAIT (its face) — the DEEPEST floor, rendered behind the idle
      * clip and the live video whenever provided. It paints IMMEDIATELY on connect
@@ -1442,7 +1434,7 @@ type UseRealtimeSessionInput<T extends LLMProvider = LLMProvider> = UseSessionLi
     onEnded?: (e: EndedEvent) => void;
     /** The avatar's behavior changed (listening/thinking/idle/special clips). */
     onBehaviorChange?: (b: BehaviorSnapshot) => void;
-    /** A clip request was answered (also resolved on the performClip promise). */
+    /** A clip request was answered (also resolved on the performAction promise). */
     onClipResult?: (r: ClipResult) => void;
 };
 /**
@@ -1495,15 +1487,8 @@ type RealtimeSessionApi = SessionLifecycleApi & {
     end: (reason?: EndReason) => void;
     /** The avatar's live nonverbal behavior, or null pre-choreo (see {@link BehaviorSnapshot}). */
     behavior: BehaviorSnapshot | null;
-    /**
-     * Ask the character to PERFORM a clip by id — a gesture arc plays once (e.g. the
-     * gift moment); a `special`-role clip pins for `holdSeconds` (3-20, default 8).
-     * Scheduled at the next seamless swap point, never a hard cut. Resolves with the
-     * worker's verdict (`accepted:false` + reason on refusal / not connected /
-     * timeout) — never rejects, so the app can always fall back to text-only behavior.
-     */
-    performClip: (clipId: string, opts?: {
-        holdSeconds?: number;
+    /** Request a declared semantic action; acceptance schedules it and does not prove playback. */
+    performAction: (actionId: string, opts?: {
         timeoutMs?: number;
     }) => Promise<ClipResult>;
     /** Inbound `rta.lifecycle` frames (the bridge decodes RoomEvent.DataReceived). */

package/dist/react-native.d.ts

@@ -1,8 +1,8 @@
 import { LiveKitRoomProps } from '@livekit/react-native';
 export { AudioSession, VideoTrack, VideoTrackProps, registerGlobals } from '@livekit/react-native';
 import { ReactNode, ReactElement } from 'react';
-import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-DlYBC6cp.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarSessionClient, B as BehaviorSnapshot, C as CallTranscript, h as CallTranscriptSegment, i as CartesiaTtsModel, j as ClipResult, k as ClosingTurnResult, l as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, m as DEFAULT_CREDITS_LOW_LEAD_SECONDS, n as DEFAULT_GOVERNOR_CONFIG, o as DEFAULT_GRACE_CEILING_SECONDS, p as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, q as DEFAULT_IDLE_SECONDS, r as DEFAULT_IDLE_WARN_LEAD_SECONDS, s as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, t as EndedEvent, u as ExtendResult, F as FishTtsModel, v as FreezeReadingFn, G as Governor, w as GovernorAction, x as GovernorConfig, y as GovernorSignal, z as GovernorState, H as GraceWindowClosedEvent, I as GraceWindowOpenEvent, J as GraceWindowState, K as IdleWarningEvent, M as InboundRtpCursor, N as InboundRtpReading, O as KnownBehaviorState, P as LLMProvider, Q as LLMSelection, R as LiveKitAvatarGrantState, S as LiveKitAvatarGrantStatus, T as LiveKitCapacityState, U as LiveKitConnectionStatus, V as LiveKitSessionRequest, W as LiveKitSessionStartResult, X as MAX_RECONNECT_ATTEMPTS, Y as MAX_SESSION_INSTRUCTIONS_CHARS, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, a0 as RealtimeAvatarRequestOptions, a1 as RealtimeSessionApi, a2 as RealtimeSessionMedia, a3 as RealtimeSessionRoomSinks, a4 as ReconnectPolicy, a5 as ReconnectingEvent, a6 as RecoveryState, a7 as RetryStep, a8 as SessionBehavior, a9 as SessionClip, aa as SessionClocks, ab as SessionEndReason, ac as SessionLifecycleApi, ad as SessionLifecyclePhase, ae as SessionLifecyclePhaseKind, af as SessionLifecycleRoomBridge, ag as SessionLifecycleRoomBridgeProps, ah as SurfaceLayers, ai as TurnState, aj as TurnTimeoutEvent, ak as UseAvatarQualityGovernorInput, al as UseLiveKitAvatarGrantInput, am as UseRealtimeSessionInput, an as UseSessionLifecycleInput, ao as VoiceSpec, ap as VoiceSpecInput, aq as capacityErrorFromBusy, ar as capacityStateFromGrant, as as createProxyClient, at as isNativeLiveTrackSubscribed, au as knownBehaviorStates, av as mapTurnState, aw as readInboundRtp, ax as sessionBehaviorSchema, ay as sessionClipSchema, az as splitCallTranscript, aA as useAvatarAdaptivePlayoutDelay, aB as useAvatarPlayoutDelay, aC as useAvatarQualityGovernor, aD as useCallTranscript, aE as useLiveKitAvatarGrant, aF as useLiveTrackProducing, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-DlYBC6cp.js';
+import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-CWvT16wz.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarSessionClient, B as BehaviorSnapshot, C as CallTranscript, h as CallTranscriptSegment, i as CartesiaTtsModel, j as ClipResult, k as ClosingTurnResult, l as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, m as DEFAULT_CREDITS_LOW_LEAD_SECONDS, n as DEFAULT_GOVERNOR_CONFIG, o as DEFAULT_GRACE_CEILING_SECONDS, p as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, q as DEFAULT_IDLE_SECONDS, r as DEFAULT_IDLE_WARN_LEAD_SECONDS, s as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, t as EndedEvent, u as ExtendResult, F as FishTtsModel, v as FreezeReadingFn, G as Governor, w as GovernorAction, x as GovernorConfig, y as GovernorSignal, z as GovernorState, H as GraceWindowClosedEvent, I as GraceWindowOpenEvent, J as GraceWindowState, K as IdleWarningEvent, M as InboundRtpCursor, N as InboundRtpReading, O as KnownBehaviorState, P as LLMProvider, Q as LLMSelection, R as LiveKitAvatarGrantState, S as LiveKitAvatarGrantStatus, T as LiveKitCapacityState, U as LiveKitConnectionStatus, V as LiveKitSessionRequest, W as LiveKitSessionStartResult, X as MAX_RECONNECT_ATTEMPTS, Y as MAX_SESSION_INSTRUCTIONS_CHARS, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, a0 as RealtimeAvatarRequestOptions, a1 as RealtimeSessionApi, a2 as RealtimeSessionMedia, a3 as RealtimeSessionRoomSinks, a4 as ReconnectPolicy, a5 as ReconnectingEvent, a6 as RecoveryState, a7 as RetryStep, a8 as SessionBehavior, a9 as SessionClip, aa as SessionClocks, ab as SessionEndReason, ac as SessionLifecycleApi, ad as SessionLifecyclePhase, ae as SessionLifecyclePhaseKind, af as SessionLifecycleRoomBridge, ag as SessionLifecycleRoomBridgeProps, ah as SurfaceLayers, ai as TurnState, aj as TurnTimeoutEvent, ak as UseAvatarQualityGovernorInput, al as UseLiveKitAvatarGrantInput, am as UseRealtimeSessionInput, an as UseSessionLifecycleInput, ao as VoiceSpec, ap as VoiceSpecInput, aq as capacityErrorFromBusy, ar as capacityStateFromGrant, as as createProxyClient, at as isNativeLiveTrackSubscribed, au as knownBehaviorStates, av as mapTurnState, aw as readInboundRtp, ax as sessionBehaviorSchema, ay as sessionClipSchema, az as splitCallTranscript, aA as useAvatarAdaptivePlayoutDelay, aB as useAvatarPlayoutDelay, aC as useAvatarQualityGovernor, aD as useCallTranscript, aE as useLiveKitAvatarGrant, aF as useLiveTrackProducing, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-CWvT16wz.js';
 import { StyleProp, ViewStyle } from 'react-native';
 export { useChat, useConnectionState, useLocalParticipant, useRoomContext, useTrackToggle, useTranscriptions, useVoiceAssistant } from '@livekit/components-react';
 export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-DWOc8iCl.js';