@agent-os-lab/agent-game-sdk 0.1.10 → 0.1.12

package/README.md

@@ -33,6 +33,7 @@ const view = await mountAgentGameOffice(container, {
 });
 
 view.focusAgent("agent-1");
+view.resetCamera();
 view.refreshAgents();
 view.destroy();
 ```
@@ -57,6 +58,9 @@ export function Office() {
       <button type="button" onClick={() => view?.refreshAgents()}>
         Refresh agents
       </button>
+      <button type="button" onClick={() => view?.resetCamera()}>
+        Reset view
+      </button>
       <AgentGameOfficeView
         renderer="three"
         office={{
@@ -78,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.
@@ -203,6 +304,7 @@ const view = await mountAgentGameOffice(container, {
 });
 
 view.focusAgent("agent-1");
+view.resetCamera();
 view.refreshAgents();
 view.destroy();
 ```
@@ -221,6 +323,8 @@ The layout packs up to three rooms per row, then starts another row. `capacity`
 
 The SDK keeps runtime statuses simple. `idle` and `resting` agents are locally distributed across ambient anchors for lounge, pantry, gym, and reading areas. `entertaining` stays biased toward the review area. If a configured room does not provide the selected ambient zone, the SDK falls back to another available non-offstage anchor.
 
+`resetCamera` returns the office view to its initial camera position, rotation, target, zoom, and follow state. It is intended for UI controls such as a reset-view button after a user pans, rotates, zooms, or follows an Agent.
+
 `refreshAgents` asks Agent Game Runtime to refresh the tenant roster through the existing bootstrap flow. It is intended for UI controls such as a refresh button after an Agent was created or deleted in another surface.
 
 ## React Office View
@@ -245,6 +349,9 @@ export function Office() {
       <button type="button" onClick={() => view?.refreshAgents()}>
         Refresh agents
       </button>
+      <button type="button" onClick={() => view?.resetCamera()}>
+        Reset view
+      </button>
       <AgentGameOfficeView
         renderer="three"
         office={{
@@ -308,6 +415,8 @@ view.updateAgents([
 
 `updateAgents` only mutates SDK-managed snapshot sources. Runtime and custom sources own their own updates.
 
+`resetCamera` is source-independent and can be called for snapshot, runtime, and custom sources.
+
 ## Custom Source
 
 Use `source.type: "custom"` when another state manager already projects runtime state into office snapshots.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-os-lab/agent-game-sdk",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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,238 @@
+import {
+  AgentGameError,
+  normalizeAgentAvatarAnimationFrames,
+  validateAgentAvatarDefinition,
+  type AgentAvatarAnimationName,
+  type AgentAvatarDefinition,
+} from "../core";
+
+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 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";
+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/core/types.ts

@@ -87,6 +87,7 @@ export type AgentGameOfficeSourceInput =
 
 export type AgentGameOfficeRendererController = {
   update(snapshot: AgentGameOfficeSnapshot): void;
+  resetCamera?(): void;
   focusAgent?(agentId: string | null): void;
   focusFloor?(floorId: string | null): void;
   getFocusedFloor?(): string | null;
@@ -140,6 +141,7 @@ export type AgentGameOfficeResolvedOptions = Omit<AgentGameOfficeMountOptions, "
 
 export type AgentGameOfficeController = {
   updateAgents(agents: AgentPresence[]): void;
+  resetCamera(): void;
   focusAgent(agentId: string | null): void;
   focusFloor(floorId: string | null): void;
   getFocusedFloor(): string | null;

package/src/office/layout/resolver.ts

@@ -705,7 +705,7 @@ function addOfficePreset(layout: MutableResolvedLayout, room: ResolvedOfficeRoom
     addComponent(layout, room.id, "desk", `desk-${index + 1}`, slot.desk.x, slot.desk.z);
     addComponent(layout, room.id, "officeChair", `desk-chair-${index + 1}`, slot.seat.x, slot.seat.z, { rotation: slot.rotation });
     addComponent(layout, room.id, "monitor", `monitor-${index + 1}`, slot.desk.x, slot.desk.z - 0.4);
-    addSeat(layout, room.id, `desk-${index + 1}`, "desk", slot.seat.x, slot.seat.z, { x: scaleOfficeX(-7), z: scaleOfficeZ(-5) });
+    addSeat(layout, room.id, `desk-${index + 1}`, "desk", slot.seat.x, slot.seat.z, { x: slot.desk.x, z: slot.desk.z - 0.4 });
   });
 
   MEETING_ROOMS.forEach((meetingRoom, roomIndex) => {

package/src/office/mount.ts

@@ -72,6 +72,9 @@ export async function mountAgentGameOffice(
         mutableSource.updateAgents(agents);
       }
     },
+    resetCamera() {
+      controller?.resetCamera?.();
+    },
     focusAgent(agentId) {
       controller?.focusAgent?.(agentId);
     },

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/agent-body-instancing.ts

@@ -18,7 +18,7 @@ type AgentBodyBatch = {
   count: number;
 };
 
-const geometryCache = new Map<string, THREE.BoxGeometry>();
+const geometryCache = new Map<string, THREE.BufferGeometry>();
 const materialCache = new Map<string, THREE.MeshLambertMaterial>();
 const matrixHelper = new THREE.Matrix4();
 
@@ -70,7 +70,8 @@ export class AgentBodyInstancedLayer {
     requiredCapacity: number,
     opacity: number,
   ): AgentBodyBatch {
-    const key = `${part.width}:${part.height}:${part.depth}:${part.color}:${opacity}`;
+    const shape = part.shape ?? "box";
+    const key = `${shape}:${part.width}:${part.height}:${part.depth}:${part.color}:${opacity}`;
     const existing = this.batches.get(key);
     if (existing && existing.capacity >= requiredCapacity) {
       return existing;
@@ -80,7 +81,7 @@ export class AgentBodyInstancedLayer {
     }
 
     const mesh = new THREE.InstancedMesh(
-      getGeometry(part.width, part.height, part.depth),
+      getGeometry(part),
       getMaterial(part.color, opacity),
       Math.max(requiredCapacity, 1),
     );
@@ -100,17 +101,33 @@ export function createAgentBodyInstancedLayer(scene: THREE.Scene): AgentBodyInst
   return new AgentBodyInstancedLayer(scene);
 }
 
-function getGeometry(width: number, height: number, depth: number): THREE.BoxGeometry {
-  const key = `${width}:${height}:${depth}`;
+function getGeometry(part: ReturnType<typeof resolveAgentBodyPartRenderSpecs>[number]): THREE.BufferGeometry {
+  const shape = part.shape ?? "box";
+  const key = `${shape}:${part.width}:${part.height}:${part.depth}`;
   const cached = geometryCache.get(key);
   if (cached) {
     return cached;
   }
-  const geometry = new THREE.BoxGeometry(width, height, depth);
+  const geometry = createGeometry(part);
   geometryCache.set(key, geometry);
   return geometry;
 }
 
+function createGeometry(part: ReturnType<typeof resolveAgentBodyPartRenderSpecs>[number]): THREE.BufferGeometry {
+  switch (part.shape) {
+    case "frontPlane":
+      return new THREE.PlaneGeometry(part.width, part.height);
+    case "backPlane": {
+      const geometry = new THREE.PlaneGeometry(part.width, part.height);
+      geometry.rotateY(Math.PI);
+      return geometry;
+    }
+    case "box":
+    case undefined:
+      return new THREE.BoxGeometry(part.width, part.height, part.depth);
+  }
+}
+
 function getMaterial(color: number, opacity: number): THREE.MeshLambertMaterial {
   const key = `${color}:${opacity}`;
   const cached = materialCache.get(key);

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

@@ -2,6 +2,8 @@ import * as THREE from "three";
 
 import type { AgentGameOfficeAgent } from "../../core/types";
 
+export const AGENT_LABEL_WORLD_Y_OFFSET = 3.05;
+
 export type AgentLabelRecord = {
   root: HTMLDivElement;
   title: HTMLDivElement;
@@ -69,7 +71,7 @@ export function updateAgentLabelPosition(
   viewport: HTMLElement,
 ): void {
   const projected = position.clone();
-  projected.y += 2.2;
+  projected.y += AGENT_LABEL_WORLD_Y_OFFSET;
   projected.project(camera);
   const x = (projected.x * 0.5 + 0.5) * viewport.clientWidth;
   const y = (-projected.y * 0.5 + 0.5) * viewport.clientHeight;

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

@@ -13,6 +13,9 @@ export type AgentMeshParts = {
   head: THREE.Object3D;
   leftEye: THREE.Object3D;
   rightEye: THREE.Object3D;
+  mouth: THREE.Object3D;
+  chestFront: THREE.Object3D;
+  backPanel: THREE.Object3D;
   hairTop: THREE.Object3D;
   hairBack: THREE.Object3D;
   leftArm: THREE.Object3D;
@@ -38,6 +41,9 @@ export type AgentBodyPartKey =
   | "head"
   | "leftEye"
   | "rightEye"
+  | "mouth"
+  | "chestFront"
+  | "backPanel"
   | "hairTop"
   | "hairBack"
   | "leftArm"
@@ -45,6 +51,7 @@ export type AgentBodyPartKey =
 
 export type AgentBodyPartRenderSpec = {
   key: AgentBodyPartKey;
+  shape?: "box" | "frontPlane" | "backPlane";
   width: number;
   height: number;
   depth: number;
@@ -66,8 +73,11 @@ export function resolveAgentBodyPartRenderSpecs(index: number): AgentBodyPartRen
     { key: "leftFoot", width: 0.24, height: 0.12, depth: 0.34, color: 0x111827, x: -0.14, y: 0.06, z: 0.08 },
     { key: "rightFoot", width: 0.24, height: 0.12, depth: 0.34, color: 0x111827, x: 0.14, y: 0.06, z: 0.08 },
     { key: "head", width: 0.5, height: 0.48, depth: 0.42, color: skin, x: 0, y: 1.48, z: 0 },
-    { key: "leftEye", width: 0.06, height: 0.07, depth: 0.035, color: 0x111827, x: -0.11, y: 1.5, z: 0.225 },
-    { key: "rightEye", width: 0.06, height: 0.07, depth: 0.035, color: 0x111827, x: 0.11, y: 1.5, z: 0.225 },
+    { key: "leftEye", shape: "frontPlane", width: 0.06, height: 0.07, depth: 0, color: 0x111827, x: -0.11, y: 1.5, z: 0.235 },
+    { key: "rightEye", shape: "frontPlane", width: 0.06, height: 0.07, depth: 0, color: 0x111827, x: 0.11, y: 1.5, z: 0.235 },
+    { key: "mouth", shape: "frontPlane", width: 0.16, height: 0.035, depth: 0, color: 0x7f1d1d, x: 0, y: 1.38, z: 0.245 },
+    { key: "chestFront", shape: "frontPlane", width: 0.28, height: 0.12, depth: 0, color: 0xe0f2fe, x: 0, y: 1.02, z: 0.185 },
+    { key: "backPanel", shape: "backPlane", width: 0.36, height: 0.44, depth: 0, color: 0x0f172a, x: 0, y: 0.92, z: -0.185 },
     { key: "hairTop", width: 0.54, height: 0.14, depth: 0.46, color: hair, x: 0, y: 1.78, z: -0.01 },
     { key: "hairBack", width: 0.52, height: 0.28, depth: 0.09, color: hair, x: 0, y: 1.61, z: -0.23 },
     { key: "leftArm", width: 0.15, height: 0.56, depth: 0.17, color: shirt, x: -0.43, y: 0.88, z: 0 },
@@ -99,6 +109,9 @@ export function createAgentMesh(agent: AgentGameOfficeAgent, index: number): Age
     head: parts.head,
     leftEye: parts.leftEye,
     rightEye: parts.rightEye,
+    mouth: parts.mouth,
+    chestFront: parts.chestFront,
+    backPanel: parts.backPanel,
     hairTop: parts.hairTop,
     hairBack: parts.hairBack,
     leftArm: parts.leftArm,

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";
@@ -58,7 +59,7 @@ const THREE_RENDERER_CAMERA_PADDING = 1.16;
 const OFFICE_CAMERA_MIN_BOUNDS_HEIGHT = 3.2;
 const WORKING_FOLLOW_RESET_DELAY_MS = 30_000;
 const WORK_EXIT_WAIT_MS = 30_000;
-const WORKING_FOLLOW_CAMERA_OFFSET = new THREE.Vector3(9, 12, 12);
+const WORKING_FOLLOW_CAMERA_OFFSET = new THREE.Vector3(14, 18, 20);
 const OFFICE_CAMERA_TRANSITION_DURATION_MS = 600;
 const OFFICE_CAMERA_UP = new THREE.Vector3(0, 1, 0);
 
@@ -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() {
@@ -332,7 +338,7 @@ export function mountThreeAgentGameOffice(
         mesh: record.mesh,
         agent: record.agent,
         target: record.target,
-        facingTarget: record.routeState.activeRoute ? record.target : resolveAgentFacingTarget(record.agent, _options.officeLayout),
+        facingTarget: resolveAgentFacingTarget(record.agent, _options.officeLayout),
         elapsedSeconds,
         deltaSeconds,
       });
@@ -387,6 +393,16 @@ export function mountThreeAgentGameOffice(
 
   return {
     update,
+    resetCamera() {
+      workingFollowState = {
+        ...workingFollowState,
+        selectedAgentId: null,
+        resetAtMs: null,
+      };
+      camera.zoom = 1;
+      camera.updateProjectionMatrix();
+      transitionOfficeCameraTo(createInitialOfficeCameraView(_options.officeLayout, camera.aspect, camera.fov));
+    },
     focusAgent(agentId) {
       if (!agentId) {
         transitionOfficeCameraTo(createInitialOfficeCameraView(_options.officeLayout, camera.aspect, camera.fov));