@agent-os-lab/agent-game-sdk 0.1.16 → 0.1.18

package/README.md

@@ -82,6 +82,25 @@ export function Office() {
 
 `agent-game-sdk/office` is renderer and framework neutral. `agent-game-sdk/office/react` is the React-only entrypoint.
 
+Static building canvas:
+
+```tsx
+import type { AgentGameOfficeConfig } from "@agent-os-lab/agent-game-sdk/office";
+import { OfficeBuildingCanvas } from "@agent-os-lab/agent-game-sdk/office/react";
+
+export function BuildingPreview({ office }: { office: AgentGameOfficeConfig }) {
+  return (
+    <OfficeBuildingCanvas
+      office={office}
+      focusedFloorId="floor-2"
+      style={{ height: 360 }}
+    />
+  );
+}
+```
+
+Use `OfficeBuildingCanvas` or `mountOfficeBuildingCanvas` when you only need the static building model. It renders the same office scene without requiring a runtime source and without mounting agents, labels, activity effects, or movement state.
+
 ## Avatar Views
 
 Use `mountAgentAvatar3D` when a tenant application needs the same 3D Agent shape used inside the office game view:

package/USAGE.md

@@ -37,8 +37,8 @@ import {
   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 { mountAgentGameOffice, mountOfficeBuildingCanvas } from "@agent-os-lab/agent-game-sdk/office";
+import { AgentGameOfficeView, OfficeBuildingCanvas } from "@agent-os-lab/agent-game-sdk/office/react";
 import type { AgentPresence } from "@agent-os-lab/agent-game-sdk/office";
 ```
 
@@ -46,8 +46,8 @@ 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.
+- `@agent-os-lab/agent-game-sdk/office`: framework-neutral office view APIs, static building canvas APIs, and office types.
+- `@agent-os-lab/agent-game-sdk/office/react`: React office view and static building canvas components.
 
 Do not import files from `src/` in application code. Use the published entry points above.
 
@@ -383,6 +383,40 @@ export function Office() {
 
 Keep `source` object identity stable across renders when possible. Recreating `source` every render can remount the view because the React wrapper treats it as an effect dependency. Equivalent inline `office` objects do not remount the view, but memoizing office config is still preferable when constructing it dynamically.
 
+## Static Building Canvas
+
+Use `OfficeBuildingCanvas` when a React surface needs the building model without agents or runtime state.
+
+```tsx
+import { useState } from "react";
+import type {
+  AgentGameOfficeBuildingCanvasController,
+  AgentGameOfficeConfig,
+} from "@agent-os-lab/agent-game-sdk/office";
+import { OfficeBuildingCanvas } from "@agent-os-lab/agent-game-sdk/office/react";
+
+export function BuildingPreview({ office }: { office: AgentGameOfficeConfig }) {
+  const [view, setView] = useState<AgentGameOfficeBuildingCanvasController | null>(null);
+
+  return (
+    <>
+      <button type="button" onClick={() => view?.resetCamera()}>
+        Reset building view
+      </button>
+      <OfficeBuildingCanvas
+        office={office}
+        focusedFloorId="floor-2"
+        style={{ height: 360 }}
+        onReady={setView}
+        onDestroy={() => setView(null)}
+      />
+    </>
+  );
+}
+```
+
+Framework-neutral callers can use `mountOfficeBuildingCanvas(container, { office })`. The static canvas reuses the office scene, camera, reset, and floor-focus behavior, but it does not accept a `source` and does not mount agents, labels, activity effects, movement, or runtime subscriptions.
+
 ## Snapshot Source
 
 Use `source.type: "snapshot"` for demos, tests, static previews, or applications that already have agent presence data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-os-lab/agent-game-sdk",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "files": [
     "src",

package/src/office/building-canvas.ts

@@ -0,0 +1,16 @@
+import { resolveOfficeLayout } from "./layout";
+import type {
+  AgentGameOfficeBuildingCanvasController,
+  AgentGameOfficeBuildingCanvasMountOptions,
+} from "./core/types";
+import { mountThreeOfficeBuildingCanvas } from "./renderers/three/building-canvas";
+
+export function mountOfficeBuildingCanvas(
+  container: HTMLElement,
+  options: AgentGameOfficeBuildingCanvasMountOptions = {},
+): AgentGameOfficeBuildingCanvasController {
+  return mountThreeOfficeBuildingCanvas(container, {
+    ...options,
+    officeLayout: resolveOfficeLayout(options.office),
+  });
+}

package/src/office/core/types.ts

@@ -149,3 +149,22 @@ export type AgentGameOfficeController = {
   getNavigationErrors(): AgentNavigationError[];
   destroy(): void;
 };
+
+export type AgentGameOfficeBuildingCanvasMountOptions = {
+  office?: AgentGameOfficeConfig;
+  focusedFloorId?: string | null;
+  className?: string;
+  onCameraChange?: (state: AgentGameOfficeCameraState) => void;
+  onFocusedFloorChange?: (floorId: string | null) => void;
+};
+
+export type AgentGameOfficeBuildingCanvasResolvedOptions = AgentGameOfficeBuildingCanvasMountOptions & {
+  officeLayout: ResolvedOfficeLayout;
+};
+
+export type AgentGameOfficeBuildingCanvasController = {
+  resetCamera(): void;
+  focusFloor(floorId: string | null): void;
+  getFocusedFloor(): string | null;
+  destroy(): void;
+};

package/src/office/index.ts

@@ -3,3 +3,4 @@ export * from "./core/projection";
 export * from "./core/source";
 export * from "./layout";
 export * from "./mount";
+export * from "./building-canvas";

package/src/office/react/OfficeBuildingCanvas.ts

@@ -0,0 +1,87 @@
+import React, { useEffect, useRef } from "react";
+
+import { mountOfficeBuildingCanvas } from "../building-canvas";
+import type {
+  AgentGameOfficeBuildingCanvasController,
+  AgentGameOfficeBuildingCanvasMountOptions,
+} from "../core/types";
+
+export type OfficeBuildingCanvasProps = AgentGameOfficeBuildingCanvasMountOptions & {
+  className?: string;
+  style?: React.CSSProperties;
+  onReady?: (controller: AgentGameOfficeBuildingCanvasController) => void;
+  onDestroy?: () => void;
+};
+
+export function OfficeBuildingCanvas({
+  className,
+  onDestroy,
+  onReady,
+  style,
+  ...options
+}: OfficeBuildingCanvasProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const viewRef = useRef<AgentGameOfficeBuildingCanvasController | null>(null);
+  const onDestroyRef = useRef(onDestroy);
+  const onReadyRef = useRef(onReady);
+  const officeConfigKey = createOfficeConfigKey(options.office);
+
+  useEffect(() => {
+    onReadyRef.current = onReady;
+    onDestroyRef.current = onDestroy;
+  }, [onDestroy, onReady]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+
+    const view = mountOfficeBuildingCanvas(container, options);
+    viewRef.current = view;
+    onReadyRef.current?.(view);
+
+    return () => {
+      viewRef.current?.destroy();
+      viewRef.current = null;
+      onDestroyRef.current?.();
+    };
+  }, [officeConfigKey]);
+
+  useEffect(() => {
+    viewRef.current?.focusFloor(options.focusedFloorId ?? null);
+  }, [options.focusedFloorId]);
+
+  return React.createElement("div", {
+    ref: containerRef,
+    className,
+    style: {
+      width: "100%",
+      height: "100%",
+      minHeight: 240,
+      ...style,
+    },
+  });
+}
+
+function createOfficeConfigKey(office: AgentGameOfficeBuildingCanvasMountOptions["office"]): string {
+  if (!office) {
+    return "default";
+  }
+  return JSON.stringify({
+    floors: office.building.floors.map((floor) => ({
+      id: floor.id,
+      name: floor.name,
+      rooms: floor.rooms.map((room) => ({
+        type: room.type,
+        capacity: room.capacity ?? null,
+      })),
+    })),
+    connectors: office.building.connectors.map((connector) => ({
+      id: connector.id,
+      name: connector.name,
+      type: connector.type,
+      serves: connector.serves,
+    })),
+  });
+}

package/src/office/react/index.ts

@@ -1 +1,2 @@
 export * from "./AgentGameOfficeView";
+export * from "./OfficeBuildingCanvas";

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

@@ -115,6 +115,7 @@ export function applyAgentPose(
 function resetPose(mesh: AgentMeshParts): void {
   mesh.visualRoot.position.y = 0;
   mesh.body.rotation.set(0, 0, 0);
+  mesh.headRoot.rotation.set(0, 0, 0);
   mesh.head.rotation.set(0, 0, 0);
   mesh.leftArm.rotation.set(0, 0, 0);
   mesh.rightArm.rotation.set(0, 0, 0);
@@ -150,7 +151,7 @@ function applyPoseMode(
       applySeatedLowerBody(mesh);
       mesh.visualRoot.position.y = CHAIR_SEATED_VISUAL_Y;
       mesh.body.rotation.x = -0.1;
-      mesh.head.rotation.x = -0.06;
+      mesh.headRoot.rotation.x = -0.06;
       mesh.leftArm.rotation.x = 0.58 + Math.sin(phase) * 0.18;
       mesh.rightArm.rotation.x = 0.58 - Math.sin(phase) * 0.18;
       mesh.leftArm.rotation.z = -0.08;
@@ -158,21 +159,21 @@ function applyPoseMode(
       return;
     }
     case "thinking":
-      mesh.head.rotation.y = Math.sin(elapsedSeconds * 1.2) * 0.35;
-      mesh.head.rotation.x = Math.sin(elapsedSeconds * 0.9) * 0.08;
+      mesh.headRoot.rotation.y = Math.sin(elapsedSeconds * 1.2) * 0.35;
+      mesh.headRoot.rotation.x = Math.sin(elapsedSeconds * 0.9) * 0.08;
       mesh.body.rotation.z = Math.sin(elapsedSeconds * 1.6) * 0.07;
       return;
     case "meeting":
       applySeatedLowerBody(mesh);
       mesh.visualRoot.position.y = CHAIR_SEATED_VISUAL_Y;
-      mesh.head.rotation.x = Math.sin(elapsedSeconds * 2) * 0.08;
+      mesh.headRoot.rotation.x = Math.sin(elapsedSeconds * 2) * 0.08;
       mesh.leftArm.rotation.x = 0.08;
       mesh.rightArm.rotation.x = -0.08;
       return;
     case "waiting":
       applySeatedLowerBody(mesh);
       mesh.visualRoot.position.y = CHAIR_SEATED_VISUAL_Y;
-      mesh.head.rotation.y = Math.sin(elapsedSeconds * 0.9) * 0.12;
+      mesh.headRoot.rotation.y = Math.sin(elapsedSeconds * 0.9) * 0.12;
       return;
     case "resting": {
       const breath = 1 + Math.sin(elapsedSeconds * 1.2) * 0.025;
@@ -180,7 +181,7 @@ function applyPoseMode(
       mesh.visualRoot.position.y = SOFA_SEATED_VISUAL_Y;
       mesh.body.scale.set(1, breath, 1);
       mesh.body.rotation.x = 0.08;
-      mesh.head.rotation.z = Math.sin(elapsedSeconds * 0.8) * 0.05;
+      mesh.headRoot.rotation.z = Math.sin(elapsedSeconds * 0.8) * 0.05;
       return;
     }
     case "idle": {

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

@@ -10,6 +10,7 @@ export type AgentMeshParts = {
   group: THREE.Group;
   visualRoot: THREE.Group;
   body: THREE.Object3D;
+  headRoot: THREE.Object3D;
   head: THREE.Object3D;
   leftEye: THREE.Object3D;
   rightEye: THREE.Object3D;
@@ -61,6 +62,15 @@ export type AgentBodyPartRenderSpec = {
   z: number;
 };
 
+const HEAD_ROOT_PART_KEYS = new Set<AgentBodyPartKey>([
+  "head",
+  "leftEye",
+  "rightEye",
+  "mouth",
+  "hairTop",
+  "hairBack",
+]);
+
 export function resolveAgentBodyPartRenderSpecs(index: number): AgentBodyPartRenderSpec[] {
   const shirt = agentColors[index % agentColors.length] ?? agentColors[0];
   const skin = skinColors[index % skinColors.length] ?? skinColors[0];
@@ -90,11 +100,25 @@ export function createAgentMesh(agent: AgentGameOfficeAgent, index: number): Age
   group.scale.setScalar(AGENT_MESH_SCALE);
   const visualRoot = new THREE.Group();
   group.add(visualRoot);
+  const specs = resolveAgentBodyPartRenderSpecs(index);
+  const headSpec = specs.find((part) => part.key === "head");
+  if (!headSpec) {
+    throw new Error("Agent mesh head part is required");
+  }
+  const headRoot = new THREE.Group();
+  headRoot.position.set(headSpec.x, headSpec.y, headSpec.z);
+  visualRoot.add(headRoot);
   const parts = Object.fromEntries(
-    resolveAgentBodyPartRenderSpecs(index).map((part) => [
-      part.key,
-      addPart(visualRoot, part.x, part.y, part.z),
-    ]),
+    specs.map((part) => {
+      const parent = HEAD_ROOT_PART_KEYS.has(part.key) ? headRoot : visualRoot;
+      const x = HEAD_ROOT_PART_KEYS.has(part.key) ? part.x - headSpec.x : part.x;
+      const y = HEAD_ROOT_PART_KEYS.has(part.key) ? part.y - headSpec.y : part.y;
+      const z = HEAD_ROOT_PART_KEYS.has(part.key) ? part.z - headSpec.z : part.z;
+      return [
+        part.key,
+        addPart(parent, x, y, z),
+      ];
+    }),
   ) as Record<AgentBodyPartKey, THREE.Object3D>;
   const activityGlow = createActivityGlow();
   const activityEffects = createAgentActivityEffects();
@@ -106,6 +130,7 @@ export function createAgentMesh(agent: AgentGameOfficeAgent, index: number): Age
     group,
     visualRoot,
     body: parts.body,
+    headRoot,
     head: parts.head,
     leftEye: parts.leftEye,
     rightEye: parts.rightEye,

package/src/office/renderers/three/building-canvas.ts

@@ -0,0 +1,177 @@
+import * as THREE from "three";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
+
+import type {
+  AgentGameOfficeBuildingCanvasController,
+  AgentGameOfficeBuildingCanvasResolvedOptions,
+} from "../../core/types";
+import type { ResolvedOfficeLayout } from "../../layout";
+import {
+  addLights,
+  applyOfficeFloorFocus,
+  buildOfficeScene,
+  disposeObject,
+} from "./scene";
+import {
+  THREE_RENDERER_MAX_CAMERA_DISTANCE,
+  THREE_RENDERER_MIN_CAMERA_DISTANCE,
+  THREE_RENDERER_PIXEL_RATIO_LIMIT,
+  THREE_RENDERER_TARGET_FPS,
+  createInitialOfficeCameraView,
+  createOfficeCameraState,
+  createOfficeMouseButtons,
+  type OfficeCameraView,
+} from "./mount";
+
+export function mountThreeOfficeBuildingCanvas(
+  container: HTMLElement,
+  options: AgentGameOfficeBuildingCanvasResolvedOptions,
+): AgentGameOfficeBuildingCanvasController {
+  const width = Math.max(container.clientWidth || 960, 320);
+  const height = Math.max(container.clientHeight || 540, 240);
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0xf7f8fb);
+
+  const camera = new THREE.PerspectiveCamera(45, width / height, 0.1, 1000);
+  const initialCameraView = createInitialOfficeCameraView(options.officeLayout, camera.aspect, camera.fov);
+  applyOfficeCameraView(camera, initialCameraView);
+
+  const renderer = new THREE.WebGLRenderer({
+    antialias: true,
+    alpha: false,
+    powerPreference: "high-performance",
+  });
+  renderer.setSize(width, height);
+  renderer.setPixelRatio(Math.min(globalThis.devicePixelRatio || 1, THREE_RENDERER_PIXEL_RATIO_LIMIT));
+  renderer.shadowMap.enabled = false;
+  renderer.domElement.style.width = "100%";
+  renderer.domElement.style.height = "100%";
+  renderer.domElement.style.display = "block";
+  renderer.domElement.style.cursor = "grab";
+
+  function setGrabbingCursor() {
+    renderer.domElement.style.cursor = "grabbing";
+  }
+
+  function setGrabCursor() {
+    renderer.domElement.style.cursor = "grab";
+  }
+
+  renderer.domElement.addEventListener("pointerdown", setGrabbingCursor);
+  renderer.domElement.addEventListener("pointerup", setGrabCursor);
+  renderer.domElement.addEventListener("pointerleave", setGrabCursor);
+
+  const controls = new OrbitControls(camera, renderer.domElement);
+  controls.target.copy(initialCameraView.target);
+  controls.enableDamping = true;
+  controls.dampingFactor = 0.08;
+  controls.enablePan = true;
+  controls.enableRotate = true;
+  controls.enableZoom = true;
+  controls.mouseButtons = createOfficeMouseButtons();
+  controls.minDistance = THREE_RENDERER_MIN_CAMERA_DISTANCE;
+  controls.maxDistance = THREE_RENDERER_MAX_CAMERA_DISTANCE;
+  controls.maxPolarAngle = Math.PI * 0.48;
+  controls.addEventListener("change", emitCameraChange);
+  controls.update();
+
+  const root = document.createElement("div");
+  root.style.position = "relative";
+  root.style.width = "100%";
+  root.style.height = "100%";
+  root.style.overflow = "hidden";
+  root.appendChild(renderer.domElement);
+  container.appendChild(root);
+
+  addLights(scene);
+  buildOfficeScene(scene, options.officeLayout);
+
+  let frameId = 0;
+  let disposed = false;
+  let previousRenderTime = performance.now();
+  let focusedFloorId = normalizeFocusedFloorId(options.officeLayout, options.focusedFloorId ?? null);
+  setFocusedFloor(focusedFloorId, false);
+
+  function animate() {
+    if (disposed) {
+      return;
+    }
+    const now = performance.now();
+    const targetFrameIntervalMs = 1000 / THREE_RENDERER_TARGET_FPS;
+    if (now - previousRenderTime >= targetFrameIntervalMs) {
+      previousRenderTime = now;
+      controls.update();
+      renderer.render(scene, camera);
+    }
+    frameId = requestAnimationFrame(animate);
+  }
+
+  const resizeObserver = new ResizeObserver(() => {
+    const nextWidth = Math.max(container.clientWidth || width, 320);
+    const nextHeight = Math.max(container.clientHeight || height, 240);
+    camera.aspect = nextWidth / nextHeight;
+    camera.updateProjectionMatrix();
+    renderer.setSize(nextWidth, nextHeight);
+    emitCameraChange();
+  });
+  resizeObserver.observe(container);
+
+  emitCameraChange();
+  animate();
+
+  return {
+    resetCamera() {
+      camera.zoom = 1;
+      camera.updateProjectionMatrix();
+      const view = createInitialOfficeCameraView(options.officeLayout, camera.aspect, camera.fov);
+      applyOfficeCameraView(camera, view);
+      controls.target.copy(view.target);
+      controls.update();
+      emitCameraChange();
+    },
+    focusFloor(floorId) {
+      setFocusedFloor(floorId);
+    },
+    getFocusedFloor() {
+      return focusedFloorId;
+    },
+    destroy() {
+      disposed = true;
+      cancelAnimationFrame(frameId);
+      resizeObserver.disconnect();
+      controls.dispose();
+      renderer.domElement.removeEventListener("pointerdown", setGrabbingCursor);
+      renderer.domElement.removeEventListener("pointerup", setGrabCursor);
+      renderer.domElement.removeEventListener("pointerleave", setGrabCursor);
+      disposeObject(scene);
+      renderer.dispose();
+      root.remove();
+    },
+  };
+
+  function emitCameraChange() {
+    options.onCameraChange?.(createOfficeCameraState(camera, controls));
+  }
+
+  function setFocusedFloor(floorId: string | null, emit = true) {
+    const nextFloorId = normalizeFocusedFloorId(options.officeLayout, floorId);
+    focusedFloorId = nextFloorId;
+    applyOfficeFloorFocus(scene, options.officeLayout, focusedFloorId);
+    if (emit) {
+      options.onFocusedFloorChange?.(focusedFloorId);
+    }
+  }
+}
+
+function applyOfficeCameraView(camera: THREE.PerspectiveCamera, view: OfficeCameraView) {
+  camera.up.copy(view.up);
+  camera.position.copy(view.position);
+  camera.rotation.copy(view.rotation);
+}
+
+function normalizeFocusedFloorId(layout: ResolvedOfficeLayout, floorId: string | null): string | null {
+  if (!floorId) {
+    return null;
+  }
+  return layout.building.floors.some((floor) => floor.id === floorId) ? floorId : null;
+}