realtime-avatar 0.4.0 → 0.5.0

package/dist/express.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-9leGOgVv.js';
-import './types-C5zypiVY.js';
+import { P as ProxyConfig } from './types-B45GgjrV.js';
+import './types-DLxz6uFE.js';
 
 type Expressish = {
     method: string;

package/dist/express.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -60,7 +60,7 @@ var RealtimeAvatar = class {
     if (!options.apiKey) throw new RealtimeAvatarError("apiKey is required");
     this.#apiKey = options.apiKey;
     this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     this.#timeoutMs = options.timeoutMs ?? 6e4;
     this.#maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.#userAgent = [`realtime-avatar-sdk/${SDK_VERSION}`, runtimeTag(), options.userAgent].filter(Boolean).join(" ");
@@ -197,9 +197,91 @@ var RealtimeAvatar = class {
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
     );
   }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json2 = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json2.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: json2 })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
   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 12 clips: one `idle`, up to two `listen`, the rest `gesture`. 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.
+   */
+  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 })
+      )
+    );
+  }
+  /** 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.
    *
@@ -210,6 +292,10 @@ var RealtimeAvatar = class {
    * **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(
@@ -385,7 +471,11 @@ function toAvatar(raw) {
     displayName: String(a.displayName ?? ""),
     sourceKind: a.sourceKind === "video" ? "video" : "image",
     status: a.status ?? "draft",
-    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null
   };
 }
 function toAsset(raw) {

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-9leGOgVv.js';
-import './types-C5zypiVY.js';
+import { P as ProxyConfig } from './types-B45GgjrV.js';
+import './types-DLxz6uFE.js';
 
 /**
  * Hono (and anything else built on Fetch handlers — Workers, Bun, Deno).

package/dist/hono.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -60,7 +60,7 @@ var RealtimeAvatar = class {
     if (!options.apiKey) throw new RealtimeAvatarError("apiKey is required");
     this.#apiKey = options.apiKey;
     this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     this.#timeoutMs = options.timeoutMs ?? 6e4;
     this.#maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.#userAgent = [`realtime-avatar-sdk/${SDK_VERSION}`, runtimeTag(), options.userAgent].filter(Boolean).join(" ");
@@ -197,9 +197,91 @@ var RealtimeAvatar = class {
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
     );
   }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json2 = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json2.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: json2 })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
   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 12 clips: one `idle`, up to two `listen`, the rest `gesture`. 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.
+   */
+  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 })
+      )
+    );
+  }
+  /** 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.
    *
@@ -210,6 +292,10 @@ var RealtimeAvatar = class {
    * **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(
@@ -385,7 +471,11 @@ function toAvatar(raw) {
     displayName: String(a.displayName ?? ""),
     sourceKind: a.sourceKind === "video" ? "video" : "image",
     status: a.status ?? "draft",
-    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null
   };
 }
 function toAsset(raw) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as ClipSyncResult, d as AssetKind, e as Asset, L as ListSessionsOptions, U as UsageSessionPage, f as UsageSession, g as CreditBalance, T as TranscriptPayload } from './types-C5zypiVY.js';
-export { h as CallConnection, i as CallQueued, j as ContextMessage, k as EndCallReason, V as VideoPolicy, l as VideoState, m as isQueued } from './types-C5zypiVY.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 ClipDeclaration, e as ClipLibraryUpdate, f as ClipLibrary, g as ClipSyncResult, h as AssetKind, i as Asset, L as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as CreditBalance, T as TranscriptPayload } from './types-DLxz6uFE.js';
+export { l as AvatarClip, m as CallConnection, n as CallQueued, o as ClipLibraryPlan, p as ClipSource, q as ContextMessage, r as EndCallReason, V as VideoPolicy, s as VideoState, t as isQueued } from './types-DLxz6uFE.js';
 
 interface RealtimeAvatarOptions {
     /** `tic_live_…` or `tic_test_…`. Server-side only — never ship this to a browser. */
@@ -98,7 +98,62 @@ declare class RealtimeAvatar {
     getAvatar(avatarId: string): Promise<Avatar>;
     /** Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice. */
     updateAvatar(avatarId: string, patch: AvatarUpdate): Promise<Avatar>;
+    /**
+     * Re-shoot the character — swap in new footage as her resting loop.
+     *
+     * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+     * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+     * and cuts over to the new generation in one step once the replacement is prepared.
+     * A call minted a second after this returns is a normal call on the old footage.
+     *
+     * Two consequences worth designing for:
+     *
+     * - **The clip library empties and refills.** Old takes are footage of the old source and
+     *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+     *   cutover and the last re-render she rests on the new loop with less variety — never
+     *   broken, just plainer. Do not gate your UI on the library being full.
+     * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+     *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+     *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+     *
+     * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+     * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+     */
+    swapSource(avatarId: string, input: AvatarSourceSwap): Promise<Avatar>;
+    /**
+     * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+     * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+     *
+     * Re-renders the clip library the same way, with the same degradation window, and is
+     * clamped server-side to the loop's last extractable frame (read the avatar back to see
+     * what was actually cut). Video-sourced avatars only.
+     */
+    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 12 clips: one `idle`, up to two `listen`, the rest `gesture`. 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>;
+    /** 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.
      *
@@ -109,6 +164,10 @@ declare class RealtimeAvatar {
      * **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. */
@@ -189,4 +248,4 @@ declare function verifyTranscript(rawBody: Uint8Array | string, headers: Headers
     toleranceSeconds?: number;
 }): Promise<TranscriptPayload>;
 
-export { Asset, AssetKind, Avatar, AvatarUpdate, CallMode, CallPolicy, ClipSyncResult, CreditBalance, EndCallOptions, ListSessionsOptions, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, type RealtimeAvatarOptions, type StartCallOptions, StartCallResult, TranscriptPayload, UsageSession, UsageSessionPage, verifyTranscript };
+export { Asset, AssetKind, Avatar, AvatarSourceSwap, AvatarUpdate, CallMode, CallPolicy, ClipDeclaration, ClipLibrary, ClipLibraryUpdate, ClipSyncResult, CreditBalance, EndCallOptions, ListSessionsOptions, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, type RealtimeAvatarOptions, type StartCallOptions, StartCallResult, TranscriptPayload, UsageSession, UsageSessionPage, verifyTranscript };

package/dist/index.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -60,7 +60,7 @@ var RealtimeAvatar = class {
     if (!options.apiKey) throw new RealtimeAvatarError("apiKey is required");
     this.#apiKey = options.apiKey;
     this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     this.#timeoutMs = options.timeoutMs ?? 6e4;
     this.#maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.#userAgent = [`realtime-avatar-sdk/${SDK_VERSION}`, runtimeTag(), options.userAgent].filter(Boolean).join(" ");
@@ -197,9 +197,91 @@ var RealtimeAvatar = class {
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
     );
   }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
   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 12 clips: one `idle`, up to two `listen`, the rest `gesture`. 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.
+   */
+  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 })
+      )
+    );
+  }
+  /** 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.
    *
@@ -210,6 +292,10 @@ var RealtimeAvatar = class {
    * **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(
@@ -385,7 +471,11 @@ function toAvatar(raw) {
     displayName: String(a.displayName ?? ""),
     sourceKind: a.sourceKind === "video" ? "video" : "image",
     status: a.status ?? "draft",
-    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null
   };
 }
 function toAsset(raw) {

package/dist/nextjs.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-9leGOgVv.js';
-import './types-C5zypiVY.js';
+import { P as ProxyConfig } from './types-B45GgjrV.js';
+import './types-DLxz6uFE.js';
 
 /**
  * App Router. Mount at `app/api/realtime-avatar/[...path]/route.ts`:

package/dist/nextjs.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -60,7 +60,7 @@ var RealtimeAvatar = class {
     if (!options.apiKey) throw new RealtimeAvatarError("apiKey is required");
     this.#apiKey = options.apiKey;
     this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     this.#timeoutMs = options.timeoutMs ?? 6e4;
     this.#maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.#userAgent = [`realtime-avatar-sdk/${SDK_VERSION}`, runtimeTag(), options.userAgent].filter(Boolean).join(" ");
@@ -197,9 +197,91 @@ var RealtimeAvatar = class {
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
     );
   }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json2 = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json2.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: json2 })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
   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 12 clips: one `idle`, up to two `listen`, the rest `gesture`. 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.
+   */
+  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 })
+      )
+    );
+  }
+  /** 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.
    *
@@ -210,6 +292,10 @@ var RealtimeAvatar = class {
    * **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(
@@ -385,7 +471,11 @@ function toAvatar(raw) {
     displayName: String(a.displayName ?? ""),
     sourceKind: a.sourceKind === "video" ? "video" : "image",
     status: a.status ?? "draft",
-    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null
   };
 }
 function toAsset(raw) {

package/dist/react-native.js

@@ -405,7 +405,8 @@ function useLiveKitAvatarGrant(input) {
   );
   useEffect(() => {
     if (!autoRetryBusy || !active || !tabVisible || state.status !== "busy" || !state.busy) return;
-    const retryMs = Math.max(state.busy.recommended_retry_ms, 250);
+    const hinted = state.busy.recommended_retry_ms;
+    const retryMs = Math.max(Number.isFinite(hinted) ? hinted : 5e3, 250);
     const timer = window.setTimeout(refresh, retryMs);
     return () => window.clearTimeout(timer);
   }, [active, autoRetryBusy, tabVisible, refresh, state.busy, state.status]);

package/dist/react.js

@@ -364,7 +364,8 @@ function useLiveKitAvatarGrant(input) {
   );
   useEffect(() => {
     if (!autoRetryBusy || !active || !tabVisible || state.status !== "busy" || !state.busy) return;
-    const retryMs = Math.max(state.busy.recommended_retry_ms, 250);
+    const hinted = state.busy.recommended_retry_ms;
+    const retryMs = Math.max(Number.isFinite(hinted) ? hinted : 5e3, 250);
     const timer = window.setTimeout(refresh, retryMs);
     return () => window.clearTimeout(timer);
   }, [active, autoRetryBusy, tabVisible, refresh, state.busy, state.status]);

package/dist/server.d.ts

@@ -1,2 +1,2 @@
 export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarOptions, StartCallOptions, verifyTranscript } from './index.js';
-export { e as Asset, d as AssetKind, A as Avatar, b as AvatarUpdate, h as CallConnection, C as CallMode, a as CallPolicy, i as CallQueued, c as ClipSyncResult, j as ContextMessage, g as CreditBalance, E as EndCallOptions, k as EndCallReason, L as ListSessionsOptions, S as StartCallResult, T as TranscriptPayload, f as UsageSession, U as UsageSessionPage, V as VideoPolicy, l as VideoState, m as isQueued } from './types-C5zypiVY.js';
+export { i as Asset, h as AssetKind, A as Avatar, l as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, m as CallConnection, C as CallMode, a as CallPolicy, n as CallQueued, d as ClipDeclaration, f as ClipLibrary, o as ClipLibraryPlan, e as ClipLibraryUpdate, p as ClipSource, g as ClipSyncResult, q as ContextMessage, k as CreditBalance, E as EndCallOptions, r as EndCallReason, L as ListSessionsOptions, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, s as VideoState, t as isQueued } from './types-DLxz6uFE.js';

package/dist/server.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -60,7 +60,7 @@ var RealtimeAvatar = class {
     if (!options.apiKey) throw new RealtimeAvatarError("apiKey is required");
     this.#apiKey = options.apiKey;
     this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     this.#timeoutMs = options.timeoutMs ?? 6e4;
     this.#maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.#userAgent = [`realtime-avatar-sdk/${SDK_VERSION}`, runtimeTag(), options.userAgent].filter(Boolean).join(" ");
@@ -197,9 +197,91 @@ var RealtimeAvatar = class {
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
     );
   }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
   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 12 clips: one `idle`, up to two `listen`, the rest `gesture`. 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.
+   */
+  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 })
+      )
+    );
+  }
+  /** 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.
    *
@@ -210,6 +292,10 @@ var RealtimeAvatar = class {
    * **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(
@@ -385,7 +471,11 @@ function toAvatar(raw) {
     displayName: String(a.displayName ?? ""),
     sourceKind: a.sourceKind === "video" ? "video" : "image",
     status: a.status ?? "draft",
-    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null
   };
 }
 function toAsset(raw) {

package/dist/tanstack-start.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-9leGOgVv.js';
-import './types-C5zypiVY.js';
+import { P as ProxyConfig } from './types-B45GgjrV.js';
+import './types-DLxz6uFE.js';
 
 /**
  * TanStack Start. Mount at `routes/api/realtime-avatar/$.ts` — the trailing `$` is Start's

package/dist/tanstack-start.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -60,7 +60,7 @@ var RealtimeAvatar = class {
     if (!options.apiKey) throw new RealtimeAvatarError("apiKey is required");
     this.#apiKey = options.apiKey;
     this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     this.#timeoutMs = options.timeoutMs ?? 6e4;
     this.#maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.#userAgent = [`realtime-avatar-sdk/${SDK_VERSION}`, runtimeTag(), options.userAgent].filter(Boolean).join(" ");
@@ -197,9 +197,91 @@ var RealtimeAvatar = class {
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
     );
   }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json2 = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json2.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: json2 })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
   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 12 clips: one `idle`, up to two `listen`, the rest `gesture`. 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.
+   */
+  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 })
+      )
+    );
+  }
+  /** 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.
    *
@@ -210,6 +292,10 @@ var RealtimeAvatar = class {
    * **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(
@@ -385,7 +471,11 @@ function toAvatar(raw) {
     displayName: String(a.displayName ?? ""),
     sourceKind: a.sourceKind === "video" ? "video" : "image",
     status: a.status ?? "draft",
-    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null
   };
 }
 function toAsset(raw) {

package/dist/{types-9leGOgVv.d.ts → types-B45GgjrV.d.ts}

@@ -1,4 +1,4 @@
-import { C as CallMode, a as CallPolicy } from './types-C5zypiVY.js';
+import { C as CallMode, a as CallPolicy } from './types-DLxz6uFE.js';
 
 /** The three things a caller can ask the proxy to do. Gate on these, not on URLs. */
 type ProxyOperation = "connect" | "end" | "avatars" | "credits";

package/dist/{types-C5zypiVY.d.ts → types-DLxz6uFE.d.ts}

@@ -132,6 +132,8 @@ interface components {
                     cooldown_seconds?: number;
                     /** @enum {string} */
                     renderer?: "editor" | "generative";
+                    /** @enum {string} */
+                    objects?: "editor" | "generative";
                 };
             };
             transcript_webhook?: {
@@ -142,6 +144,7 @@ interface components {
             client_metadata?: {
                 [key: string]: string;
             };
+            fast_endpointing?: boolean;
         };
         LiveKitSessionGrant: {
             /**
@@ -311,6 +314,42 @@ interface components {
             stylePreset?: "cinematic-founder" | "editorial-companion" | "warm-anime" | "luxury-realism" | "soft-3d" | "noir-avatar";
             /** Format: uri */
             portraitUrl?: string;
+            sourceAssetId?: string;
+            anchorTimeMs?: number;
+        };
+        CreateApiKeyRequest: {
+            name: string;
+            /**
+             * @default test
+             * @enum {string}
+             */
+            environment: "live" | "test";
+            /**
+             * @default [
+             *       "realtime:write",
+             *       "credits:read",
+             *       "avatars:read"
+             *     ]
+             */
+            scopes: ("*" | "api_keys:write" | "credits:read" | "avatars:read" | "avatars:write" | "realtime:write" | "usage:read" | "usage:write")[];
+            spendLimitCreditMicros?: number | null;
+            expiresAt?: string | null;
+        };
+        CreateApiKeyResponse: {
+            id: string;
+            keyId: string;
+            tenantId: string;
+            name: string;
+            /** @enum {string} */
+            environment: "live" | "test";
+            redactedKey: string;
+            scopes: ("*" | "api_keys:write" | "credits:read" | "avatars:read" | "avatars:write" | "realtime:write" | "usage:read" | "usage:write")[];
+            /** @enum {string} */
+            status: "active" | "revoked" | "expired";
+            spendLimitCreditMicros: number | null;
+            createdAt: string;
+            expiresAt: string | null;
+            apiKey: string;
         };
         Asset: {
             id: string;
@@ -326,6 +365,9 @@ interface components {
             createdAt: string;
             updatedAt: string;
         };
+        AssetList: {
+            data: components["schemas"]["Asset"][];
+        };
         CreateRemoteAssetRequest: {
             /** @enum {string} */
             kind: "image" | "video" | "audio";
@@ -377,9 +419,111 @@ interface components {
                 status: "queued" | "generating" | "ready" | "failed";
                 url: string | null;
                 whenHint: string | null;
+                /** @enum {string} */
+                source: "generated" | "uploaded";
+                motionPrompt: string | null;
+                durationSeconds: number | null;
+                anchorVersion: number;
+                poseCheck: {
+                    verdict: {
+                        sameSubject: boolean;
+                        firstFrameMatchesAnchor: boolean;
+                        lastFrameMatchesAnchor: boolean;
+                        framingComparable: boolean;
+                        confidence: number;
+                    };
+                    issues: string[];
+                    firstFrameUrl: string | null;
+                    lastFrameUrl: string | null;
+                    trimStartMs: number | null;
+                    trimEndMs: number | null;
+                } | null;
+                error: {
+                    code: string;
+                    message: string;
+                } | null;
+                createdAt: string;
+                updatedAt: string;
+            }[];
+            avatarId: string;
+            revision: number;
+            anchorVersion: number;
+            anchor: {
+                /** Format: uri */
+                url: string;
+                /** @enum {string} */
+                source: "portrait" | "source_frame";
+                timeMs: number | null;
+            } | null;
+            clipLibraryEligible: boolean;
+        };
+        PutAvatarClipsRequest: {
+            expectedRevision?: number;
+            clips: {
+                clipId: string;
+                /** @enum {string} */
+                role: "idle" | "listen" | "gesture";
+                whenHint?: string;
+                source: {
+                    motionPrompt: string;
+                } | {
+                    assetId: string;
+                };
+                durationSeconds?: number;
+                reroll?: boolean;
+            }[];
+        };
+        PutAvatarClipsResponse: {
+            data: {
+                clipId: string;
+                /** @enum {string} */
+                role: "idle" | "listen" | "gesture";
+                /** @enum {string} */
+                status: "queued" | "generating" | "ready" | "failed";
+                url: string | null;
+                whenHint: string | null;
+                /** @enum {string} */
+                source: "generated" | "uploaded";
+                motionPrompt: string | null;
+                durationSeconds: number | null;
+                anchorVersion: number;
+                poseCheck: {
+                    verdict: {
+                        sameSubject: boolean;
+                        firstFrameMatchesAnchor: boolean;
+                        lastFrameMatchesAnchor: boolean;
+                        framingComparable: boolean;
+                        confidence: number;
+                    };
+                    issues: string[];
+                    firstFrameUrl: string | null;
+                    lastFrameUrl: string | null;
+                    trimStartMs: number | null;
+                    trimEndMs: number | null;
+                } | null;
+                error: {
+                    code: string;
+                    message: string;
+                } | null;
                 createdAt: string;
                 updatedAt: string;
             }[];
+            avatarId: string;
+            revision: number;
+            anchorVersion: number;
+            anchor: {
+                /** Format: uri */
+                url: string;
+                /** @enum {string} */
+                source: "portrait" | "source_frame";
+                timeMs: number | null;
+            } | null;
+            clipLibraryEligible: boolean;
+            plan: {
+                kept: string[];
+                queued: string[];
+                retired: string[];
+            };
         };
         SyncAvatarClipsRequest: {
             clipUrls: string[];
@@ -392,10 +536,6 @@ interface components {
         OkResponse: {
             ok: boolean;
         };
-        HealthResponse: {
-            /** @enum {string} */
-            status: "healthy";
-        };
     };
     responses: never;
     parameters: never;
@@ -703,13 +843,25 @@ type Asset = Pick<Wire["Asset"], "id" | "kind"> & {
      */
     status: Wire["Asset"]["status"] | (string & {});
 };
-type Avatar = Pick<Wire["Avatar"], "id" | "displayName" | "sourceKind" | "status" | "defaultVoiceId">;
+type Avatar = Pick<Wire["Avatar"], "id" | "displayName" | "sourceKind" | "status" | "defaultVoiceId" | "sourceAssetId" | "error">;
 /**
  * The patch `updateAvatar` sends — the two fields an integrator re-points after creation.
  * The contract's `UpdateAvatarRequest` carries more (llm, persona, art direction…); that is
  * dashboard machinery this surface deliberately does not model.
+ *
+ * `sourceAssetId` and `anchorTimeMs` are deliberately NOT here: the platform refuses them
+ * alongside any other field, so folding them in would let this type spell a request that can
+ * only ever 422. They get their own methods — `swapSource` and `retimeAnchor`.
  */
 type AvatarUpdate = Pick<Wire["UpdateAvatarRequest"], "displayName" | "defaultVoiceId">;
+/**
+ * Re-shoot the character: `sourceAssetId` becomes the avatar's new resting loop, and the
+ * whole clip library re-renders against an anchor re-derived from that footage.
+ *
+ * `anchorTimeMs` picks the anchor frame OF THE NEW SOURCE (default 0) — frame 0 of a real
+ * take is sometimes mid-blink. It is the only field that may accompany a source swap.
+ */
+type AvatarSourceSwap = Required<Pick<Wire["UpdateAvatarRequest"], "sourceAssetId">> & Pick<Wire["UpdateAvatarRequest"], "anchorTimeMs">;
 type UsageSessionsResponse = Wire["ListUsageSessionsResponse"];
 /**
  * One billable session — when it ran, how long it was billable for, what it cost.
@@ -746,8 +898,39 @@ interface ListSessionsOptions {
     cursor?: string;
 }
 type CreditBalance = Pick<Wire["CreditBalance"], "balanceCreditMicros" | "reservedCreditMicros">;
-/** Result of reconciling an avatar's clip set to the cache tier. */
+/**
+ * Result of reconciling an avatar's clip set to the cache tier.
+ * @deprecated The externally-hosted clip tier is sunsetting. Declare the library with
+ * `setClipLibrary` instead — the platform renders and hosts the clips for you.
+ */
 type ClipSyncResult = Wire["SyncAvatarClipsResponse"];
+/**
+ * One desired clip in a library declaration: a `clipId` you choose, a role, and exactly ONE
+ * source — a `motionPrompt` the platform renders from the avatar's rest-pose anchor, or the
+ * `assetId` of a video you uploaded. `durationSeconds` (4–8, default 5) applies to generated
+ * clips only; `reroll` is a write-only re-render nudge and is never echoed back by a read.
+ */
+type ClipDeclaration = Wire["PutAvatarClipsRequest"]["clips"][number];
+/** The two ways a declared clip gets its pixels. Exactly one — an object carrying both is rejected. */
+type ClipSource = Wire["PutAvatarClipsRequest"]["clips"][number]["source"];
+/**
+ * One clip row as the platform reports it. `status` is JOB state, not serveability: `url` is
+ * the SERVING asset and may stay non-null while a re-render is `generating` or has `failed` —
+ * the previous take keeps serving. An uploaded clip that fails pose validation carries the
+ * structured verdict in `poseCheck` and the reason in `error`.
+ */
+type AvatarClip = Wire["ListAvatarClipsResponse"]["data"][number];
+/**
+ * The library as `listClips` reports it: every non-retired clip plus the avatar-level facts —
+ * the declaration `revision` (0 = still creation-owned), the anchor generation, and the
+ * rest-pose `anchor` the clips splice against (null only while a video-sourced avatar's
+ * anchor frame has not been derived yet).
+ */
+type ClipLibrary = Wire["ListAvatarClipsResponse"];
+/** How a declaration reconciled against the previous library — by `clipId`. */
+type ClipLibraryPlan = Wire["PutAvatarClipsResponse"]["plan"];
+/** The accepted declaration's answer: the post-apply library plus how it reconciled. */
+type ClipLibraryUpdate = Wire["PutAvatarClipsResponse"];
 /**
  * DERIVATION: hand-written, because the contract does not describe it.
  *
@@ -795,4 +978,4 @@ interface TranscriptPayload {
     client_metadata: Record<string, string>;
 }
 
-export { type Avatar as A, type CallMode as C, type EndCallOptions as E, type ListSessionsOptions as L, type StartCallResult as S, type TranscriptPayload as T, type UsageSessionPage as U, type VideoPolicy as V, type CallPolicy as a, type AvatarUpdate as b, type ClipSyncResult as c, type AssetKind as d, type Asset as e, type UsageSession as f, type CreditBalance as g, type CallConnection as h, type CallQueued as i, type ContextMessage as j, type EndCallReason as k, type VideoState as l, isQueued as m };
+export { type Avatar as A, type CallMode as C, type EndCallOptions as E, type ListSessionsOptions as L, type StartCallResult as S, type TranscriptPayload as T, type UsageSessionPage as U, type VideoPolicy as V, type CallPolicy as a, type AvatarUpdate as b, type AvatarSourceSwap as c, type ClipDeclaration as d, type ClipLibraryUpdate as e, type ClipLibrary as f, type ClipSyncResult as g, type AssetKind as h, type Asset as i, type UsageSession as j, type CreditBalance as k, type AvatarClip as l, type CallConnection as m, type CallQueued as n, type ClipLibraryPlan as o, type ClipSource as p, type ContextMessage as q, type EndCallReason as r, type VideoState as s, isQueued as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Realtime Avatar SDK. `realtime-avatar` and the route adapters hold your API key and are server-only; `realtime-avatar/react`, `/browser` and `/tools` never can — importing a server entry into a browser build throws at bundle time.",
   "license": "MIT",
   "author": "The Influence Company",