@agent-os-lab/agent-game-sdk 0.1.11 → 0.1.13

package/README.md

@@ -82,6 +82,69 @@ export function Office() {
 
 `agent-game-sdk/office` is renderer and framework neutral. `agent-game-sdk/office/react` is the React-only entrypoint.
 
+## Avatar Views
+
+Use `mountAgentAvatar3D` when a tenant application needs the same 3D Agent shape used inside the office game view:
+
+```ts
+import { mountAgentAvatar3D } from "@agent-os-lab/agent-game-sdk/avatar";
+
+const view = mountAgentAvatar3D(container, {
+  agentId: "agent-1",
+  sceneState: "working",
+  framing: "upperBody",
+  viewAngle: "front",
+});
+
+view.update({ sceneState: "thinking", framing: "fullBody", viewAngle: "threeQuarter" });
+view.destroy();
+```
+
+Passing the same `agentId` used in the office game gives the standalone 3D view the same Agent appearance as the game scene. Use `renderIndex` only when you want to override the AgentID-derived appearance.
+
+For Agent lists, prefer static 3D thumbnails instead of mounting one live WebGL view per row. Reuse one thumbnail renderer for the batch, cache the returned data URLs by AgentID and view options, then destroy the renderer when the batch is done:
+
+```ts
+import { createAgentAvatar3DThumbnailRenderer } from "@agent-os-lab/agent-game-sdk/avatar";
+
+const thumbnails = createAgentAvatar3DThumbnailRenderer({
+  width: 96,
+  height: 96,
+});
+
+const rows = agents.map((agent) => ({
+  ...agent,
+  avatarUrl: thumbnails.render({
+    agentId: agent.agentId,
+    framing: "upperBody",
+    viewAngle: "threeQuarter",
+  }).dataUrl,
+}));
+
+thumbnails.destroy();
+```
+
+Use `mountAgentAvatarCanvas` when a tenant application needs the generated 2D pixel sprite:
+
+```ts
+import { createSvgPixelAgentAvatar } from "@agent-os-lab/agent-game-sdk";
+import { mountAgentAvatarCanvas } from "@agent-os-lab/agent-game-sdk/avatar";
+
+const avatar = createSvgPixelAgentAvatar({
+  id: "agent-1",
+  seed: "tenant-a/agent-1",
+});
+
+const view = await mountAgentAvatarCanvas(container, {
+  avatar,
+  animation: "idle.down",
+  scale: 4,
+});
+
+await view.update({ animation: "emote.talk" });
+view.destroy();
+```
+
 ## Runtime Agent List
 
 Use `subscribeAgentPresenceList` when an app needs the live Agent roster and status outside the 3D office view:

package/USAGE.md

@@ -12,6 +12,7 @@ The SDK is intentionally split by responsibility:
 
 - Runtime clients handle token creation and WebSocket subscription.
 - Office view APIs mount a framework-neutral 3D office view into a DOM container.
+- Avatar view APIs mount a framework-neutral canvas for one Agent's visual identity.
 - React APIs wrap the same office view for React applications.
 
 ## Installation
@@ -32,8 +33,10 @@ Runtime requirements:
 import {
   AgentGameRuntimeBrowserClient,
   AgentGameRuntimeServerClient,
+  createSvgPixelAgentAvatar,
   subscribeAgentPresenceList,
 } from "@agent-os-lab/agent-game-sdk";
+import { mountAgentAvatar3D, mountAgentAvatarCanvas } from "@agent-os-lab/agent-game-sdk/avatar";
 import { mountAgentGameOffice } from "@agent-os-lab/agent-game-sdk/office";
 import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
 import type { AgentPresence } from "@agent-os-lab/agent-game-sdk/office";
@@ -42,6 +45,7 @@ import type { AgentPresence } from "@agent-os-lab/agent-game-sdk/office";
 Available entry points:
 
 - `@agent-os-lab/agent-game-sdk`: runtime clients and office exports.
+- `@agent-os-lab/agent-game-sdk/avatar`: framework-neutral avatar view APIs.
 - `@agent-os-lab/agent-game-sdk/office`: framework-neutral office view APIs and office types.
 - `@agent-os-lab/agent-game-sdk/office/react`: React office view component.
 
@@ -175,6 +179,103 @@ await browserClient.subscribe({
 });
 ```
 
+## Avatar Views
+
+Use `mountAgentAvatar3D` when the application needs to display a single Agent's appearance exactly like the office game. It uses the same Three.js Agent mesh as the office view, including the same body render specs, pose system, and activity effect layers.
+
+```ts
+import { mountAgentAvatar3D } from "@agent-os-lab/agent-game-sdk/avatar";
+
+const view = mountAgentAvatar3D(container, {
+  agentId: "agent-1",
+  sceneState: "working",
+  framing: "upperBody",
+  viewAngle: "front",
+});
+
+view.update({
+  sceneState: "thinking",
+  framing: "fullBody",
+  viewAngle: "threeQuarter",
+});
+
+view.destroy();
+```
+
+`framing` supports `fullBody` and `upperBody`. `viewAngle` supports `front` and `threeQuarter`.
+Passing the same `agentId` used in the office game gives the standalone 3D view the same appearance as the office game scene. Use `renderIndex` only when you need to override that AgentID-derived appearance.
+
+### Static 3D Thumbnails
+
+For 50-item Agent lists, use static 3D thumbnails instead of mounting 50 live `mountAgentAvatar3D` views. The thumbnail path renders the same game-style Agent once into a PNG data URL, so list rows can use normal `<img>` elements while still keeping a 3D look.
+
+For one-off UI, mount an image directly:
+
+```ts
+import { mountAgentAvatar3DThumbnail } from "@agent-os-lab/agent-game-sdk/avatar";
+
+const thumbnail = mountAgentAvatar3DThumbnail(container, {
+  agentId: "agent-1",
+  sceneState: "working",
+  framing: "upperBody",
+  viewAngle: "threeQuarter",
+  width: 96,
+  height: 96,
+});
+
+thumbnail.destroy();
+```
+
+For lists, reuse one renderer for the whole batch, cache the result by `agentId`, `sceneState`, `framing`, and `viewAngle`, then call `destroy()` when rendering is complete:
+
+```ts
+import { createAgentAvatar3DThumbnailRenderer } from "@agent-os-lab/agent-game-sdk/avatar";
+
+const renderer = createAgentAvatar3DThumbnailRenderer({
+  width: 96,
+  height: 96,
+});
+
+const rows = agents.map((agent) => ({
+  ...agent,
+  avatarUrl: renderer.render({
+    agentId: agent.agentId,
+    sceneState: agent.sceneState ?? "idle",
+    framing: "upperBody",
+    viewAngle: "threeQuarter",
+  }).dataUrl,
+}));
+
+renderer.destroy();
+```
+
+Use `mountAgentAvatarCanvas` when the application needs the generated 2D pixel sprite outside the 3D office view, such as in a compact table, picker, or profile header.
+
+```ts
+import { createSvgPixelAgentAvatar } from "@agent-os-lab/agent-game-sdk";
+import { mountAgentAvatarCanvas } from "@agent-os-lab/agent-game-sdk/avatar";
+
+const avatar = createSvgPixelAgentAvatar({
+  id: "agent-1",
+  seed: "tenant-a/agent-1",
+  department: "研发部",
+});
+
+const view = await mountAgentAvatarCanvas(container, {
+  avatar,
+  animation: "idle.down",
+  scale: 4,
+});
+
+await view.update({
+  animation: "emote.talk",
+});
+
+view.destroy();
+```
+
+The canvas view consumes an `AgentAvatarDefinition`, so tenant applications can use SDK-generated avatars or an avatar definition returned by their own backend. `mountAgentAvatarCanvas` loads the avatar atlas and sprite sheet, draws one animation frame, and returns a controller with `update` and `destroy`. Use `scale` to render the pixel avatar larger without smoothing.
+
 ## Office View
 
 Use `mountAgentGameOffice` for framework-neutral embedding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-os-lab/agent-game-sdk",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "files": [
     "src",
@@ -9,6 +9,7 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./avatar": "./src/avatar/index.ts",
     "./office": "./src/office/index.ts",
     "./office/react": "./src/office/react/index.ts"
   },

package/src/avatar/canvas-view.ts

@@ -0,0 +1,286 @@
+import { AgentGameError } from "../core/errors";
+
+const REQUIRED_AGENT_AVATAR_ANIMATIONS = [
+  "idle.down",
+  "idle.up",
+  "idle.left",
+  "idle.right",
+  "walk.down",
+  "walk.up",
+  "walk.left",
+  "walk.right",
+  "work.typing",
+  "emote.think",
+  "emote.talk",
+] as const;
+
+export type AgentAvatarAnimationName = (typeof REQUIRED_AGENT_AVATAR_ANIMATIONS)[number];
+export type AgentAvatarAnimationFrames = string | string[];
+export type AgentAvatarDefinition = {
+  id: string;
+  imageUrl: string;
+  atlasUrl: string;
+  animations: Partial<Record<AgentAvatarAnimationName, AgentAvatarAnimationFrames>> & Record<string, AgentAvatarAnimationFrames>;
+};
+
+export type AgentAvatarAtlasFrame = {
+  frame: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  };
+};
+
+export type AgentAvatarAtlasLike = {
+  frames: Record<string, AgentAvatarAtlasFrame>;
+};
+
+export type AgentAvatarCanvasOptions = {
+  avatar: AgentAvatarDefinition;
+  animation?: AgentAvatarAnimationName;
+  frameIndex?: number;
+  scale?: number;
+  canvas?: HTMLCanvasElement;
+  atlas?: AgentAvatarAtlasLike;
+  image?: CanvasImageSource;
+  createImage?: () => HTMLImageElement;
+};
+
+export type AgentAvatarCanvasUpdateOptions = Partial<AgentAvatarCanvasOptions> & {
+  avatar?: AgentAvatarDefinition;
+};
+
+export type AgentAvatarCanvasController = {
+  canvas: HTMLCanvasElement;
+  update(options: AgentAvatarCanvasUpdateOptions): Promise<void>;
+  destroy(): void;
+};
+
+type LoadedAvatarAssets = {
+  avatar: AgentAvatarDefinition;
+  atlas: AgentAvatarAtlasLike;
+  image: CanvasImageSource;
+};
+
+export async function mountAgentAvatarCanvas(
+  container: HTMLElement,
+  options: AgentAvatarCanvasOptions,
+): Promise<AgentAvatarCanvasController> {
+  const canvas = options.canvas ?? createCanvasElement();
+  const context = canvas.getContext("2d");
+  if (!context) {
+    throw new AgentGameError("invalid_renderer", "Agent avatar canvas requires a 2D canvas context");
+  }
+
+  if (!options.canvas) {
+    container.appendChild(canvas);
+  } else if (!canvas.parentElement) {
+    container.appendChild(canvas);
+  }
+
+  let destroyed = false;
+  let version = 0;
+  let currentOptions = normalizeOptions(options);
+  let assets = await loadAssets(currentOptions);
+  drawAvatarFrame(canvas, context, assets, currentOptions);
+
+  return {
+    canvas,
+    async update(nextOptions) {
+      if (destroyed) {
+        throw new AgentGameError("runtime_destroyed", "Agent avatar canvas view has been destroyed");
+      }
+
+      const updateVersion = ++version;
+      const mergedOptions = normalizeOptions({
+        ...currentOptions,
+        ...nextOptions,
+      });
+
+      const needsAssetReload = nextOptions.avatar !== undefined
+        || nextOptions.atlas !== undefined
+        || nextOptions.image !== undefined
+        || nextOptions.createImage !== undefined;
+      const nextAssets = needsAssetReload ? await loadAssets(mergedOptions) : assets;
+      if (destroyed || updateVersion !== version) {
+        return;
+      }
+
+      currentOptions = mergedOptions;
+      assets = nextAssets;
+      drawAvatarFrame(canvas, context, assets, currentOptions);
+    },
+    destroy() {
+      if (!destroyed) {
+        destroyed = true;
+        version++;
+        canvas.remove();
+      }
+    },
+  };
+}
+
+function normalizeOptions(options: AgentAvatarCanvasOptions): Required<Pick<
+  AgentAvatarCanvasOptions,
+  "avatar" | "animation" | "frameIndex" | "scale"
+>> & Omit<AgentAvatarCanvasOptions, "animation" | "frameIndex" | "scale"> {
+  return {
+    ...options,
+    avatar: validateAgentAvatarDefinition(options.avatar),
+    animation: options.animation ?? "idle.down",
+    frameIndex: options.frameIndex ?? 0,
+    scale: options.scale ?? 1,
+  };
+}
+
+async function loadAssets(options: ReturnType<typeof normalizeOptions>): Promise<LoadedAvatarAssets> {
+  return {
+    avatar: options.avatar,
+    atlas: options.atlas ?? await loadAtlas(options.avatar.atlasUrl),
+    image: options.image ?? await loadImage(options.avatar.imageUrl, options.createImage),
+  };
+}
+
+async function loadAtlas(url: string): Promise<AgentAvatarAtlasLike> {
+  if (url.startsWith("data:")) {
+    return JSON.parse(decodeDataUrl(url)) as AgentAvatarAtlasLike;
+  }
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new AgentGameError("invalid_asset_manifest", `Failed to load agent avatar atlas: ${url}`);
+  }
+  return await response.json() as AgentAvatarAtlasLike;
+}
+
+async function loadImage(
+  url: string,
+  createImage: (() => HTMLImageElement) | undefined,
+): Promise<CanvasImageSource> {
+  const image = createImage?.() ?? createDefaultImage();
+  return await new Promise<CanvasImageSource>((resolve, reject) => {
+    image.onload = () => resolve(image);
+    image.onerror = () => reject(new AgentGameError("missing_avatar", `Failed to load agent avatar image: ${url}`));
+    image.src = url;
+  });
+}
+
+function drawAvatarFrame(
+  canvas: HTMLCanvasElement,
+  context: CanvasRenderingContext2D,
+  assets: LoadedAvatarAssets,
+  options: ReturnType<typeof normalizeOptions>,
+): void {
+  const frameName = resolveAnimationFrameName(assets.avatar, options.animation, options.frameIndex);
+  const atlasFrame = assets.atlas.frames[frameName]?.frame;
+  if (!atlasFrame) {
+    throw new AgentGameError("missing_animation", `Agent game avatar ${assets.avatar.id} is missing frame: ${frameName}`);
+  }
+
+  const scale = assertPositiveFiniteInteger(options.scale, "scale");
+  const width = atlasFrame.w * scale;
+  const height = atlasFrame.h * scale;
+  canvas.width = width;
+  canvas.height = height;
+  context.imageSmoothingEnabled = false;
+  context.clearRect(0, 0, width, height);
+  context.drawImage(
+    assets.image,
+    atlasFrame.x,
+    atlasFrame.y,
+    atlasFrame.w,
+    atlasFrame.h,
+    0,
+    0,
+    width,
+    height,
+  );
+}
+
+function resolveAnimationFrameName(
+  avatar: AgentAvatarDefinition,
+  animation: AgentAvatarAnimationName,
+  frameIndex: number,
+): string {
+  const frames = normalizeAgentAvatarAnimationFrames(avatar.animations[animation]);
+  if (frames.length === 0) {
+    throw new AgentGameError("missing_animation", `Agent game avatar ${avatar.id} is missing animation: ${animation}`);
+  }
+
+  const index = assertNonNegativeFiniteInteger(frameIndex, "frameIndex") % frames.length;
+  return frames[index]!;
+}
+
+function validateAgentAvatarDefinition(avatar: AgentAvatarDefinition): AgentAvatarDefinition {
+  assertNonEmpty(avatar.id, "avatar id");
+  assertNonEmpty(avatar.imageUrl, "avatar image url");
+  assertNonEmpty(avatar.atlasUrl, "avatar atlas url");
+
+  for (const animation of REQUIRED_AGENT_AVATAR_ANIMATIONS) {
+    if (!avatar.animations[animation]) {
+      throw new AgentGameError("missing_animation", `Agent game avatar ${avatar.id} is missing animation: ${animation}`);
+    }
+    const frames = normalizeAgentAvatarAnimationFrames(avatar.animations[animation]);
+    if (frames.length === 0) {
+      throw new AgentGameError("missing_animation", `Agent game avatar ${avatar.id} is missing animation: ${animation}`);
+    }
+  }
+
+  return avatar;
+}
+
+function normalizeAgentAvatarAnimationFrames(frames: AgentAvatarAnimationFrames | undefined): string[] {
+  if (frames === undefined) {
+    return [];
+  }
+  return Array.isArray(frames) ? frames : [frames];
+}
+
+function assertNonEmpty(value: string, field: string): void {
+  if (!value || value.trim().length === 0) {
+    throw new AgentGameError("invalid_asset_manifest", `Agent game ${field} must not be empty`);
+  }
+}
+
+function assertPositiveFiniteInteger(value: number, field: string): number {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new AgentGameError("invalid_asset_manifest", `Agent avatar canvas ${field} must be a positive integer`);
+  }
+  return value;
+}
+
+function assertNonNegativeFiniteInteger(value: number, field: string): number {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new AgentGameError("invalid_asset_manifest", `Agent avatar canvas ${field} must be a non-negative integer`);
+  }
+  return value;
+}
+
+function createCanvasElement(): HTMLCanvasElement {
+  if (typeof document === "undefined") {
+    throw new AgentGameError("invalid_renderer", "Agent avatar canvas requires a browser document or a canvas option");
+  }
+  return document.createElement("canvas");
+}
+
+function createDefaultImage(): HTMLImageElement {
+  if (typeof Image === "undefined") {
+    throw new AgentGameError("invalid_renderer", "Agent avatar canvas requires a browser Image or a createImage option");
+  }
+  return new Image();
+}
+
+function decodeDataUrl(url: string): string {
+  const commaIndex = url.indexOf(",");
+  if (commaIndex === -1) {
+    throw new AgentGameError("invalid_asset_manifest", "Agent avatar atlas data URL is malformed");
+  }
+
+  const metadata = url.slice(0, commaIndex);
+  const payload = url.slice(commaIndex + 1);
+  if (metadata.endsWith(";base64")) {
+    return atob(payload);
+  }
+  return decodeURIComponent(payload);
+}

package/src/avatar/index.ts

@@ -0,0 +1,4 @@
+export * from "./canvas-view";
+export * from "./three-thumbnail";
+export * from "./three-view";
+export { resolveAgentAvatarRenderIndex } from "../office/renderers/three/agent-appearance";

package/src/avatar/three-scene.ts

@@ -0,0 +1,150 @@
+import * as THREE from "three";
+
+import type {
+  AgentGameOfficeAgent,
+  AgentGameOfficeSceneState,
+} from "../office/core/types";
+import { applyAgentPose } from "../office/renderers/three/agent-animation";
+import { resolveAgentAvatarRenderIndex } from "../office/renderers/three/agent-appearance";
+import {
+  createAgentBodyInstancedLayer,
+  type AgentBodyInstancedLayer,
+} from "../office/renderers/three/agent-body-instancing";
+import {
+  createAgentEffectInstancedLayer,
+  type AgentEffectInstancedLayer,
+} from "../office/renderers/three/agent-effect-instancing";
+import { createAgentMesh, type AgentMeshParts } from "../office/renderers/three/agent-mesh";
+import type { AgentAvatar3DFraming, AgentAvatar3DViewAngle } from "./three-view";
+
+export type AgentAvatar3DSceneOptions = {
+  agent?: Partial<AgentGameOfficeAgent>;
+  agentId?: string;
+  framing?: AgentAvatar3DFraming;
+  sceneState?: AgentGameOfficeSceneState;
+  renderIndex?: number;
+  viewAngle?: AgentAvatar3DViewAngle;
+  width: number;
+  height: number;
+};
+
+export type ResolvedAgentAvatar3DState = AgentGameOfficeAgent & {
+  framing: AgentAvatar3DFraming;
+  renderIndex: number;
+  viewAngle: AgentAvatar3DViewAngle;
+};
+
+export type AgentAvatar3DScene = {
+  scene: THREE.Scene;
+  camera: THREE.PerspectiveCamera;
+  mesh: AgentMeshParts;
+  bodyLayer: AgentBodyInstancedLayer;
+  effectLayer: AgentEffectInstancedLayer;
+  state: ResolvedAgentAvatar3DState;
+  setState(options: AgentAvatar3DSceneOptions, preservedRenderIndex?: number): ResolvedAgentAvatar3DState;
+  render(renderer: { render(scene: THREE.Scene, camera: THREE.Camera): void }, nowMs: number): void;
+  dispose(): void;
+};
+
+export function createAgentAvatar3DScene(options: AgentAvatar3DSceneOptions): AgentAvatar3DScene {
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0xf8fafc);
+  const camera = new THREE.PerspectiveCamera(38, options.width / options.height, 0.1, 100);
+  scene.add(new THREE.HemisphereLight(0xffffff, 0xd9e2ef, 1.8));
+  const keyLight = new THREE.DirectionalLight(0xffffff, 1.4);
+  keyLight.position.set(3, 5, 4);
+  scene.add(keyLight);
+
+  let state = resolveAgentAvatar3DState(options);
+  const mesh = createAgentMesh(state, state.renderIndex);
+  mesh.group.position.set(0, 0, 0);
+  applyAvatar3DViewAngle(mesh.group, state.viewAngle);
+  applyAvatar3DFraming(camera, state.framing);
+  scene.add(mesh.group);
+  const bodyLayer = createAgentBodyInstancedLayer(scene);
+  const effectLayer = createAgentEffectInstancedLayer(scene);
+
+  return {
+    scene,
+    camera,
+    mesh,
+    bodyLayer,
+    effectLayer,
+    get state() {
+      return state;
+    },
+    setState(nextOptions, preservedRenderIndex) {
+      state = resolveAgentAvatar3DState(nextOptions, preservedRenderIndex);
+      applyAvatar3DViewAngle(mesh.group, state.viewAngle);
+      applyAvatar3DFraming(camera, state.framing);
+      return state;
+    },
+    render(renderer, nowMs) {
+      const elapsedSeconds = nowMs / 1000;
+      applyAgentPose(mesh, state, false, elapsedSeconds);
+      bodyLayer.update([{ mesh, renderIndex: state.renderIndex, visible: state.sceneState !== "offline" }]);
+      effectLayer.update([{ mesh, visible: state.sceneState !== "offline" }]);
+      renderer.render(scene, camera);
+    },
+    dispose() {
+      bodyLayer.dispose();
+      effectLayer.dispose();
+      scene.remove(mesh.group);
+    },
+  };
+}
+
+export function resolveAgentAvatar3DState(
+  options: Omit<AgentAvatar3DSceneOptions, "width" | "height">,
+  preservedRenderIndex?: number,
+): ResolvedAgentAvatar3DState {
+  const agentId = options.agentId ?? options.agent?.id;
+  const agent = {
+    ...createDefaultAgent(),
+    ...options.agent,
+    ...(agentId ? { id: agentId } : {}),
+  };
+  return {
+    ...agent,
+    framing: options.framing ?? "fullBody",
+    sceneState: options.sceneState ?? agent.sceneState,
+    renderIndex: options.renderIndex ?? preservedRenderIndex ?? resolveAgentAvatarRenderIndex(agent.id),
+    viewAngle: options.viewAngle ?? "threeQuarter",
+  };
+}
+
+function applyAvatar3DFraming(camera: THREE.PerspectiveCamera, framing: AgentAvatar3DFraming): void {
+  if (framing === "upperBody") {
+    camera.position.set(0, 2.55, 3.35);
+    camera.lookAt(0, 1.42, 0);
+    return;
+  }
+
+  camera.position.set(0, 2.1, 5.2);
+  camera.lookAt(0, 1.05, 0);
+}
+
+function applyAvatar3DViewAngle(group: THREE.Group, viewAngle: AgentAvatar3DViewAngle): void {
+  group.rotation.y = viewAngle === "front" ? 0 : Math.PI * 0.1;
+}
+
+function createDefaultAgent(): AgentGameOfficeAgent {
+  return {
+    id: "avatar-preview-agent",
+    name: "Agent",
+    role: null,
+    statusLabel: "Idle",
+    activityLabel: undefined,
+    sceneState: "idle",
+    zoneId: "desk",
+    updatedAt: new Date(0).toISOString(),
+    raw: {
+      tenantId: "preview",
+      agentId: "avatar-preview-agent",
+      displayName: "Agent",
+      status: "idle",
+      statusSource: "simulation",
+      updatedAt: new Date(0).toISOString(),
+    },
+  };
+}

package/src/avatar/three-thumbnail.ts

@@ -0,0 +1,125 @@
+import * as THREE from "three";
+
+import {
+  createAgentAvatar3DScene,
+  type AgentAvatar3DSceneOptions,
+} from "./three-scene";
+import type { AgentAvatar3DRendererLike } from "./three-view";
+
+export type AgentAvatar3DThumbnailRendererLike = Omit<AgentAvatar3DRendererLike, "domElement"> & {
+  domElement: HTMLCanvasElement;
+};
+
+export type AgentAvatar3DThumbnailOptions = Omit<
+  AgentAvatar3DSceneOptions,
+  "width" | "height"
+> & {
+  width?: number;
+  height?: number;
+  pixelRatio?: number;
+};
+
+export type AgentAvatar3DThumbnailRendererOptions = {
+  width?: number;
+  height?: number;
+  pixelRatio?: number;
+  createRenderer?: () => AgentAvatar3DThumbnailRendererLike;
+  readDataUrl?: (renderer: AgentAvatar3DThumbnailRendererLike) => string;
+  now?: () => number;
+};
+
+export type AgentAvatar3DThumbnail = {
+  dataUrl: string;
+  width: number;
+  height: number;
+  renderIndex: number;
+};
+
+export type AgentAvatar3DThumbnailRenderer = {
+  render(options: AgentAvatar3DThumbnailOptions): AgentAvatar3DThumbnail;
+  destroy(): void;
+};
+
+export type AgentAvatar3DThumbnailMountOptions = AgentAvatar3DThumbnailOptions & AgentAvatar3DThumbnailRendererOptions & {
+  createImage?: () => HTMLImageElement;
+};
+
+export type AgentAvatar3DThumbnailController = {
+  image: HTMLImageElement;
+  thumbnail: AgentAvatar3DThumbnail;
+  destroy(): void;
+};
+
+export function createAgentAvatar3DThumbnailRenderer(
+  options: AgentAvatar3DThumbnailRendererOptions = {},
+): AgentAvatar3DThumbnailRenderer {
+  const baseWidth = options.width ?? 96;
+  const baseHeight = options.height ?? 96;
+  const renderer = options.createRenderer?.() ?? createDefaultThumbnailRenderer();
+  renderer.setPixelRatio(options.pixelRatio ?? Math.min(globalThis.devicePixelRatio || 1, 2));
+  const readDataUrl = options.readDataUrl ?? ((currentRenderer) => currentRenderer.domElement.toDataURL("image/png"));
+  const now = options.now ?? (() => performance.now());
+  let destroyed = false;
+
+  return {
+    render(renderOptions) {
+      if (destroyed) {
+        throw new Error("Agent avatar 3D thumbnail renderer has been destroyed");
+      }
+      const width = renderOptions.width ?? baseWidth;
+      const height = renderOptions.height ?? baseHeight;
+      renderer.setSize(width, height);
+      const avatarScene = createAgentAvatar3DScene({ ...renderOptions, width, height });
+      avatarScene.render(renderer, now());
+      const dataUrl = readDataUrl(renderer);
+      const renderIndex = avatarScene.state.renderIndex;
+      avatarScene.dispose();
+      return { dataUrl, width, height, renderIndex };
+    },
+    destroy() {
+      if (!destroyed) {
+        destroyed = true;
+        renderer.dispose();
+      }
+    },
+  };
+}
+
+export function renderAgentAvatar3DThumbnail(
+  options: AgentAvatar3DThumbnailOptions & AgentAvatar3DThumbnailRendererOptions,
+): AgentAvatar3DThumbnail {
+  const renderer = createAgentAvatar3DThumbnailRenderer(options);
+  try {
+    return renderer.render(options);
+  } finally {
+    renderer.destroy();
+  }
+}
+
+export function mountAgentAvatar3DThumbnail(
+  container: HTMLElement,
+  options: AgentAvatar3DThumbnailMountOptions,
+): AgentAvatar3DThumbnailController {
+  const thumbnail = renderAgentAvatar3DThumbnail(options);
+  const image = options.createImage?.() ?? new Image();
+  image.src = thumbnail.dataUrl;
+  image.width = thumbnail.width;
+  image.height = thumbnail.height;
+  container.appendChild(image);
+
+  return {
+    image,
+    thumbnail,
+    destroy() {
+      image.remove();
+    },
+  };
+}
+
+function createDefaultThumbnailRenderer(): AgentAvatar3DThumbnailRendererLike {
+  return new THREE.WebGLRenderer({
+    alpha: true,
+    antialias: true,
+    preserveDrawingBuffer: true,
+  });
+}

package/src/avatar/three-view.ts

@@ -0,0 +1,145 @@
+import * as THREE from "three";
+
+import type { AgentGameOfficeAgent, AgentGameOfficeSceneState } from "../office/core/types";
+import { AgentGameError } from "../core/errors";
+import {
+  createAgentAvatar3DScene,
+  type ResolvedAgentAvatar3DState,
+} from "./three-scene";
+
+export type AgentAvatar3DRendererLike = {
+  domElement: Node;
+  setSize(width: number, height: number): void;
+  setPixelRatio(value: number): void;
+  render(scene: THREE.Scene, camera: THREE.Camera): void;
+  dispose(): void;
+};
+
+export type AgentAvatar3DFraming = "fullBody" | "upperBody";
+export type AgentAvatar3DViewAngle = "front" | "threeQuarter";
+
+export type AgentAvatar3DOptions = {
+  agent?: Partial<AgentGameOfficeAgent>;
+  agentId?: string;
+  framing?: AgentAvatar3DFraming;
+  sceneState?: AgentGameOfficeSceneState;
+  renderIndex?: number;
+  viewAngle?: AgentAvatar3DViewAngle;
+  width?: number;
+  height?: number;
+  pixelRatio?: number;
+  createRenderer?: () => AgentAvatar3DRendererLike;
+  requestFrame?: (callback: FrameRequestCallback) => number;
+  cancelFrame?: (id: number) => void;
+  now?: () => number;
+};
+
+export type AgentAvatar3DUpdateOptions = Partial<Pick<
+  AgentAvatar3DOptions,
+  "agent" | "agentId" | "framing" | "sceneState" | "renderIndex" | "viewAngle"
+>>;
+
+export type AgentAvatar3DController = {
+  update(options: AgentAvatar3DUpdateOptions): void;
+  destroy(): void;
+  getAgentGroup(): THREE.Group;
+  getScene(): THREE.Scene;
+  getState(): ResolvedAgentAvatar3DState;
+};
+
+export type { ResolvedAgentAvatar3DState } from "./three-scene";
+
+export function mountAgentAvatar3D(
+  container: HTMLElement,
+  options: AgentAvatar3DOptions = {},
+): AgentAvatar3DController {
+  const width = options.width ?? Math.max(container.clientWidth || 0, 240);
+  const height = options.height ?? Math.max(container.clientHeight || 0, 240);
+  const renderer = options.createRenderer?.() ?? createDefaultRenderer();
+  renderer.setPixelRatio(options.pixelRatio ?? Math.min(globalThis.devicePixelRatio || 1, 2));
+  renderer.setSize(width, height);
+  container.appendChild(renderer.domElement);
+
+  let destroyed = false;
+  let frameId: number | null = null;
+  let hasExplicitRenderIndex = options.renderIndex !== undefined;
+  const avatarScene = createAgentAvatar3DScene({ ...options, width, height });
+  const requestFrame = options.requestFrame ?? requestAnimationFrame;
+  const cancelFrame = options.cancelFrame ?? cancelAnimationFrame;
+  const now = options.now ?? (() => performance.now());
+
+  function renderFrame() {
+    if (destroyed) {
+      return;
+    }
+    avatarScene.render(renderer, now());
+    frameId = requestFrame(renderFrame);
+  }
+
+  renderFrame();
+
+  return {
+    update(nextOptions) {
+      if (destroyed) {
+        throw new AgentGameError("runtime_destroyed", "Agent avatar 3D view has been destroyed");
+      }
+      const agentIdChanged = nextOptions.agentId !== undefined || nextOptions.agent?.id !== undefined;
+      const preserveRenderIndex = hasExplicitRenderIndex && nextOptions.renderIndex === undefined && !agentIdChanged;
+      avatarScene.setState({
+        agent: { ...avatarScene.state, ...nextOptions.agent },
+        agentId: nextOptions.agentId,
+        framing: nextOptions.framing ?? avatarScene.state.framing,
+        sceneState: nextOptions.sceneState ?? avatarScene.state.sceneState,
+        renderIndex: nextOptions.renderIndex,
+        viewAngle: nextOptions.viewAngle ?? avatarScene.state.viewAngle,
+        width,
+        height,
+      }, preserveRenderIndex ? avatarScene.state.renderIndex : undefined);
+      if (nextOptions.renderIndex !== undefined) {
+        hasExplicitRenderIndex = true;
+      } else if (agentIdChanged) {
+        hasExplicitRenderIndex = false;
+      }
+      renderFrameOnce();
+    },
+    destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      if (frameId !== null) {
+        cancelFrame(frameId);
+        frameId = null;
+      }
+      avatarScene.dispose();
+      renderer.dispose();
+      removeNode(renderer.domElement);
+    },
+    getScene() {
+      return avatarScene.scene;
+    },
+    getAgentGroup() {
+      return avatarScene.mesh.group;
+    },
+    getState() {
+      return avatarScene.state;
+    },
+  };
+
+  function renderFrameOnce() {
+    avatarScene.render(renderer, now());
+  }
+}
+
+function createDefaultRenderer(): AgentAvatar3DRendererLike {
+  return new THREE.WebGLRenderer({
+    alpha: true,
+    antialias: true,
+  });
+}
+
+function removeNode(node: Node): void {
+  if (node.parentNode) {
+    node.parentNode.removeChild(node);
+  }
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./runtime-client";
 export * from "./runtime-agent-list";
+export * from "./avatar";
+export { createSvgPixelAgentAvatar } from "./core";
 export * from "./office";
 export * from "./graph";

package/src/office/renderers/three/agent-appearance.ts

@@ -0,0 +1,13 @@
+const AGENT_AVATAR_RENDER_VARIANTS = 3;
+
+export function resolveAgentAvatarRenderIndex(agentId: string): number {
+  return stableHash(agentId) % AGENT_AVATAR_RENDER_VARIANTS;
+}
+
+function stableHash(value: string): number {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+  }
+  return hash;
+}

package/src/office/renderers/three/mount.ts

@@ -12,6 +12,7 @@ import type {
 } from "../../core/types";
 import type { ResolvedOfficeLayout } from "../../layout";
 import { applyAgentPose, updateAgentMotion } from "./agent-animation";
+import { resolveAgentAvatarRenderIndex } from "./agent-appearance";
 import { createAgentBodyInstancedLayer } from "./agent-body-instancing";
 import { createAgentEffectInstancedLayer } from "./agent-effect-instancing";
 import { resolveAgentFacingTarget } from "./agent-layout";
@@ -164,6 +165,10 @@ export function updateOfficeWorkExitDisplayState(
   };
 }
 
+export function resolveOfficeAgentRenderIndex(agent: Pick<AgentGameOfficeAgent, "id">): number {
+  return resolveAgentAvatarRenderIndex(agent.id);
+}
+
 function isActiveWorkSceneState(sceneState: AgentGameOfficeSceneState | undefined): boolean {
   return sceneState === "working" || sceneState === "thinking";
 }
@@ -283,7 +288,7 @@ export function mountThreeAgentGameOffice(
       record.routeState = createAgentRouteState(_options.officeLayout, agent, record.routeState);
       const target = vectorFromLike(resolveRouteTargetPosition(record.routeState));
       record.agent = agent;
-      record.renderIndex = index;
+      record.renderIndex = resolveOfficeAgentRenderIndex(agent);
       record.target.copy(target);
       record.mesh.group.visible = agent.sceneState !== "offline";
       record.mesh.group.userData.officeFloorId = resolveAgentRouteFloorId(_options.officeLayout, record.routeState);
@@ -294,7 +299,8 @@ export function mountThreeAgentGameOffice(
   }
 
   function createAgentRecord(agent: AgentGameOfficeAgent, index: number): AgentMeshRecord {
-    const mesh = createAgentMesh(agent, index);
+    const renderIndex = resolveOfficeAgentRenderIndex(agent);
+    const mesh = createAgentMesh(agent, renderIndex);
     void index;
     const routeState = createAgentRouteState(_options.officeLayout, agent, undefined);
     const position = vectorFromLike(routeState.currentPosition);
@@ -304,7 +310,7 @@ export function mountThreeAgentGameOffice(
     const label = createAgentLabel(overlay);
     label.root.style.opacity = String(resolveFocusedAgentOpacity({ routeState } as AgentMeshRecord));
 
-    return { id: agent.id, agent, renderIndex: index, mesh, label, target: position.clone(), routeState };
+    return { id: agent.id, agent, renderIndex, mesh, label, target: position.clone(), routeState };
   }
 
   function animate() {