@simarena/viewport 0.0.1-alpha.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@simarena/viewport",
+  "version": "0.0.1-alpha.0",
+  "description": "SimArena viewport — Three.js rendering, body sync, camera, WebSocket streaming",
+  "license": "MIT",
+  "type": "module",
+  "files": ["src"],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "scripts": {
+    "check": "tsc --noEmit"
+  },
+  "keywords": ["simarena", "viewport", "three.js", "robotics", "simulation", "websocket"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/simarena/viewport"
+  },
+  "dependencies": {
+    "@simarena/format": "0.0.1-alpha.0",
+    "three": "^0.183.2"
+  },
+  "devDependencies": {
+    "@types/three": "^0.183.1",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "three": "^0.170.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  }
+}

package/src/compiler/threejs/index.ts

@@ -0,0 +1,389 @@
+import * as THREE from 'three';
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
+import type { SceneDoc, DocEntity, MaterialDef, MeshDef, TextureDef, LightComponent, CameraComponent } from '@simarena/format';
+import type { Geom } from '@simarena/format';
+import type { Vec3, Vec4 } from '@simarena/format';
+
+const stlLoader = new STLLoader();
+const geoCache = new Map<string, THREE.BufferGeometry>();
+
+async function loadSTL(url: string): Promise<THREE.BufferGeometry> {
+	const hit = geoCache.get(url);
+	if (hit) return hit.clone();
+	const geo = await stlLoader.loadAsync(url);
+	geo.computeVertexNormals();
+	geoCache.set(url, geo);
+	return geo.clone();
+}
+
+const objGroupCache = new Map<string, THREE.Group>();
+const mtlCreatorCache = new Map<string, MTLLoader.MaterialCreator | null>();
+
+async function loadMTL(url: string): Promise<MTLLoader.MaterialCreator | null> {
+	if (mtlCreatorCache.has(url)) return mtlCreatorCache.get(url)!;
+	try {
+		const dir = url.substring(0, url.lastIndexOf('/') + 1);
+		const loader = new MTLLoader();
+		loader.setResourcePath(dir);
+		const creator = await loader.loadAsync(url);
+		creator.preload();
+		mtlCreatorCache.set(url, creator);
+		return creator;
+	} catch {
+		mtlCreatorCache.set(url, null);
+		return null;
+	}
+}
+
+const texLoader = new THREE.TextureLoader();
+const texCache = new Map<string, THREE.Texture>();
+
+async function loadTex(url: string): Promise<THREE.Texture> {
+	const hit = texCache.get(url);
+	if (hit) return hit;
+	const tex = await texLoader.loadAsync(url);
+	tex.colorSpace = THREE.SRGBColorSpace;
+	texCache.set(url, tex);
+	return tex;
+}
+
+async function loadOBJGroup(url: string): Promise<THREE.Group> {
+	const mtlUrl = url.replace(/\.(obj|OBJ)$/, '.mtl');
+	const creator = await loadMTL(mtlUrl);
+	const cacheKey = url + (creator ? ':mtl' : '');
+	const hit = objGroupCache.get(cacheKey);
+	if (hit) return hit.clone() as THREE.Group;
+
+	const loader = new OBJLoader();
+	if (creator) loader.setMaterials(creator);
+	const grp = await loader.loadAsync(url);
+
+	grp.traverse((c) => {
+		if (c instanceof THREE.Mesh) {
+			const old = (Array.isArray(c.material) ? c.material[0] : c.material) as THREE.MeshPhongMaterial;
+			c.material = new THREE.MeshStandardMaterial({
+				map: old?.map ?? null,
+				color: old?.map ? new THREE.Color(1, 1, 1) : (old?.color ?? new THREE.Color(0xaaaaaa)),
+				metalness: 0.0,
+				roughness: 0.8
+			});
+			c.castShadow = true;
+			c.receiveShadow = true;
+		}
+	});
+	objGroupCache.set(cacheKey, grp);
+	return grp.clone() as THREE.Group;
+}
+
+function stdMat(color?: string, opacity?: number): THREE.MeshStandardMaterial {
+	const c = color ? new THREE.Color(color) : new THREE.Color(0x6b7280);
+	const a = opacity ?? 1;
+	return new THREE.MeshStandardMaterial({ color: c, transparent: a < 1, opacity: a, metalness: 0.1, roughness: 0.6 });
+}
+
+function renderGeoms(entity: DocEntity, all: Geom[]): Geom[] {
+	if (!entity.visual) return all;
+	if (!entity.visual.groups?.length) return all;
+	return all.filter(g => entity.visual!.groups!.includes(g.group ?? ''));
+}
+
+function buildGeo(g: Geom): THREE.BufferGeometry | null {
+	switch (g.type) {
+		case 'box': {
+			const [w, h, d] = g.size;
+			return new THREE.BoxGeometry(w, h, d);
+		}
+		case 'sphere': return new THREE.SphereGeometry(g.radius, 32, 32);
+		case 'cylinder': {
+			const geo = new THREE.CylinderGeometry(g.radius, g.radius, g.height, 32);
+			geo.rotateX(Math.PI / 2);
+			return geo;
+		}
+		case 'capsule': {
+			const geo = new THREE.CapsuleGeometry(g.radius, g.height, 16, 32);
+			geo.rotateX(Math.PI / 2);
+			return geo;
+		}
+		case 'plane': {
+			const [w, d] = g.size ?? [10, 10];
+			return new THREE.PlaneGeometry(w * 2, d * 2);
+		}
+		default: return null;
+	}
+}
+
+function applyT(
+	obj: THREE.Object3D,
+	t?: { pos?: Vec3; rot?: Vec3; quat?: Vec4; scale?: number }
+): void {
+	if (!t) return;
+	if (t.pos) obj.position.set(t.pos[0], t.pos[1], t.pos[2]);
+	if (t.quat) {
+		const [w, x, y, z] = t.quat;
+		obj.quaternion.set(x, y, z, w).normalize();
+	} else if (t.rot) {
+		const D = Math.PI / 180;
+		obj.rotation.set(t.rot[0] * D, t.rot[1] * D, t.rot[2] * D);
+	}
+	if (t.scale !== undefined) obj.scale.setScalar(t.scale);
+}
+
+function resolveMat(g: Geom, matMap: Map<string, MaterialDef>): THREE.MeshStandardMaterial {
+	const opacity = g.opacity ?? 1;
+	if (g.material && matMap.has(g.material)) {
+		const def = matMap.get(g.material)!;
+		if (def.rgba) {
+			const alpha = g.opacity ?? def.rgba[3] ?? 1;
+			return new THREE.MeshStandardMaterial({
+				color: new THREE.Color(def.rgba[0], def.rgba[1], def.rgba[2]),
+				transparent: alpha < 1, opacity: alpha,
+				metalness: def.metalness ?? 0.1, roughness: def.roughness ?? 0.6
+			});
+		}
+		if (def.color) return stdMat(def.color, opacity);
+	}
+	if (g.color) return stdMat(g.color, opacity);
+	return new THREE.MeshStandardMaterial({ color: 0x888888, metalness: 0.1, roughness: 0.6 });
+}
+
+export function buildLightComponent(lc: LightComponent): THREE.Light | null {
+	const color = lc.color ? new THREE.Color(lc.color) : new THREE.Color(0xffffff);
+	const intensity = lc.intensity ?? 1;
+	switch (lc.type) {
+		case 'point': {
+			const l = new THREE.PointLight(color, intensity, lc.range ?? 0);
+			l.castShadow = lc.castShadow ?? false;
+			return l;
+		}
+		case 'directional': {
+			const l = new THREE.DirectionalLight(color, intensity);
+			if (lc.dir) l.position.set(-lc.dir[0], -lc.dir[1], -lc.dir[2]).normalize().multiplyScalar(5);
+			l.castShadow = lc.castShadow ?? false;
+			return l;
+		}
+		case 'spot': {
+			const l = new THREE.SpotLight(color, intensity, lc.range ?? 0, lc.angle ? lc.angle * Math.PI / 180 : Math.PI / 6);
+			l.castShadow = lc.castShadow ?? false;
+			return l;
+		}
+		case 'ambient': return new THREE.AmbientLight(color, intensity);
+		case 'hemisphere': {
+			const g = lc.groundColor ? new THREE.Color(lc.groundColor) : new THREE.Color(0x545454);
+			return new THREE.HemisphereLight(color, g, intensity);
+		}
+		default: return null;
+	}
+}
+
+function buildMeshUrlMap(meshes: MeshDef[], basePath: string): Map<string, string> {
+	const map = new Map<string, string>();
+	for (const m of meshes) {
+		const url = m.file.startsWith('/') || m.file.startsWith('http') ? m.file : basePath + m.file;
+		map.set(m.name, url);
+	}
+	return map;
+}
+
+function buildMatMap(materials: MaterialDef[]): Map<string, MaterialDef> {
+	const map = new Map<string, MaterialDef>();
+	for (const m of materials) map.set(m.name, m);
+	return map;
+}
+
+function buildTextureUrlMap(textures: TextureDef[], basePath: string): Map<string, string> {
+	const map = new Map<string, string>();
+	for (const t of textures) {
+		const url = t.file.startsWith('/') || t.file.startsWith('http') ? t.file : basePath + t.file;
+		map.set(t.name, url);
+	}
+	return map;
+}
+
+interface BuildCtx {
+	bodies: Map<string, THREE.Object3D>;
+	entityRoots: Map<string, THREE.Object3D>;
+	meshUrls: Map<string, string>;
+	textureUrls: Map<string, string>;
+	materials: Map<string, MaterialDef>;
+	threeScene: THREE.Scene;
+	deferredParents: Array<{ group: THREE.Group; parentPath: string }>;
+}
+
+async function applyTexture(mat: THREE.MeshStandardMaterial, g: Geom, ctx: BuildCtx): Promise<void> {
+	if (!g.material) return;
+	const def = ctx.materials.get(g.material);
+	if (!def?.map) return;
+	const texUrl = ctx.textureUrls.get(def.map);
+	if (!texUrl) return;
+	try {
+		mat.map = await loadTex(texUrl);
+		mat.color.set(0xffffff);
+		mat.needsUpdate = true;
+	} catch { /* skip */ }
+}
+
+async function buildGeom(g: Geom, parent: THREE.Group, ctx: BuildCtx): Promise<void> {
+	if (g.type === 'mesh') {
+		const url = ctx.meshUrls.get(g.mesh);
+		if (!url) { console.warn(`[threejs] mesh not in catalog: "${g.mesh}"`); return; }
+		try {
+			if (/\.(obj|OBJ)$/.test(url)) {
+				const grp = await loadOBJGroup(url);
+				if (g.material || g.color) {
+					const mat = resolveMat(g, ctx.materials);
+					await applyTexture(mat, g, ctx);
+					grp.traverse((c) => { if (c instanceof THREE.Mesh) { c.material = mat.clone(); c.castShadow = true; c.receiveShadow = true; } });
+				} else {
+					grp.traverse((c) => { if (c instanceof THREE.Mesh) { c.castShadow = true; c.receiveShadow = true; } });
+				}
+				applyT(grp, { pos: g.pos, rot: g.rot, quat: g.quat });
+				parent.add(grp);
+			} else {
+				const mat = resolveMat(g, ctx.materials);
+				await applyTexture(mat, g, ctx);
+				const geo = await loadSTL(url);
+				geo.computeVertexNormals();
+				const mesh = new THREE.Mesh(geo, mat);
+				mesh.castShadow = true; mesh.receiveShadow = true;
+				applyT(mesh, { pos: g.pos, rot: g.rot, quat: g.quat });
+				parent.add(mesh);
+			}
+		} catch (e) { console.error(`[threejs] failed to load mesh "${g.mesh}" from ${url}`, e); }
+	} else {
+		const geo = buildGeo(g);
+		if (!geo) return;
+		const mat = resolveMat(g, ctx.materials);
+		await applyTexture(mat, g, ctx);
+		geo.computeVertexNormals();
+		const mesh = new THREE.Mesh(geo, mat);
+		mesh.castShadow = true; mesh.receiveShadow = true;
+		applyT(mesh, { pos: g.pos, rot: g.rot, quat: g.quat });
+		parent.add(mesh);
+	}
+}
+
+function buildCameraIcon(cc: CameraComponent, parent: THREE.Group): void {
+	const mat = new THREE.MeshStandardMaterial({ color: 0x00bcd4, metalness: 0.3, roughness: 0.5 });
+	const body = new THREE.Mesh(new THREE.BoxGeometry(0.10, 0.065, 0.075), mat);
+	body.castShadow = true;
+
+	const lensMat = new THREE.MeshStandardMaterial({ color: 0x007a9e });
+	const lens = new THREE.Mesh(new THREE.CylinderGeometry(0.03, 0.02, 0.05, 8), lensMat);
+	lens.rotation.x = Math.PI / 2;
+	lens.position.z = 0.06;
+
+	const fov = (cc.fov ?? 50) * Math.PI / 180;
+	const aspect = (cc.resolution?.[0] ?? 256) / (cc.resolution?.[1] ?? 256);
+	const near = cc.near ?? 0.1;
+	const far = Math.min(cc.far ?? 100, 2);
+	const hNear = Math.tan(fov / 2) * near;
+	const wNear = hNear * aspect;
+	const hFar  = Math.tan(fov / 2) * far;
+	const wFar  = hFar * aspect;
+
+	const pts = [
+		new THREE.Vector3(-wNear, -hNear, near), new THREE.Vector3( wNear, -hNear, near),
+		new THREE.Vector3( wNear, -hNear, near), new THREE.Vector3( wNear,  hNear, near),
+		new THREE.Vector3( wNear,  hNear, near), new THREE.Vector3(-wNear,  hNear, near),
+		new THREE.Vector3(-wNear,  hNear, near), new THREE.Vector3(-wNear, -hNear, near),
+		new THREE.Vector3(-wFar, -hFar, far), new THREE.Vector3( wFar, -hFar, far),
+		new THREE.Vector3( wFar, -hFar, far), new THREE.Vector3( wFar,  hFar, far),
+		new THREE.Vector3( wFar,  hFar, far), new THREE.Vector3(-wFar,  hFar, far),
+		new THREE.Vector3(-wFar,  hFar, far), new THREE.Vector3(-wFar, -hFar, far),
+		new THREE.Vector3(0, 0, 0), new THREE.Vector3(-wFar, -hFar, far),
+		new THREE.Vector3(0, 0, 0), new THREE.Vector3( wFar, -hFar, far),
+		new THREE.Vector3(0, 0, 0), new THREE.Vector3( wFar,  hFar, far),
+		new THREE.Vector3(0, 0, 0), new THREE.Vector3(-wFar,  hFar, far),
+	];
+	const geo = new THREE.BufferGeometry().setFromPoints(pts);
+	const lines = new THREE.LineSegments(geo, new THREE.LineBasicMaterial({ color: 0x00bcd4, opacity: 0.6, transparent: true }));
+	lines.userData['isCameraIcon'] = true;
+
+	parent.add(body);
+	parent.add(lens);
+	parent.add(lines);
+}
+
+async function buildEntity(entity: DocEntity, parentObject: THREE.Object3D, ctx: BuildCtx): Promise<void> {
+	const grp = new THREE.Group();
+	grp.name = entity.name;
+	applyT(grp, entity.transform);
+	ctx.bodies.set(entity.name, grp);
+
+	const parentRef = entity.relation?.parent;
+	if (parentRef) {
+		ctx.deferredParents.push({ group: grp, parentPath: parentRef });
+	} else {
+		parentObject.add(grp);
+	}
+
+	for (const g of renderGeoms(entity, entity.geoms ?? [])) await buildGeom(g, grp, ctx);
+
+	if (entity.light) {
+		const l = buildLightComponent(entity.light);
+		if (l) {
+			if (entity.transform?.pos) l.position.set(...entity.transform.pos);
+			grp.add(l);
+		}
+	}
+
+	if (entity.camera) {
+		buildCameraIcon(entity.camera, grp);
+	}
+}
+
+export interface ViewerScene {
+	bodies: Map<string, THREE.Object3D>;
+	entityRoots: Map<string, THREE.Object3D>;
+}
+
+export async function buildScene(doc: SceneDoc, threeScene: THREE.Scene, basePath = ''): Promise<ViewerScene> {
+	const bodies = new Map<string, THREE.Object3D>();
+	const entityRoots = new Map<string, THREE.Object3D>();
+	const deferredParents: Array<{ group: THREE.Group; parentPath: string }> = [];
+
+	const ctx: BuildCtx = {
+		bodies, entityRoots,
+		meshUrls: buildMeshUrlMap(doc.meshes ?? [], basePath),
+		textureUrls: buildTextureUrlMap(doc.textures ?? [], basePath),
+		materials: buildMatMap(doc.materials ?? []),
+		threeScene, deferredParents
+	};
+
+	for (const entity of doc.scene ?? []) {
+		await buildEntity(entity, threeScene, ctx);
+		if (!entity.relation) {
+			const root = bodies.get(entity.name);
+			if (root) entityRoots.set(entity.name, root);
+		}
+	}
+
+	for (const { group, parentPath } of deferredParents) {
+		const target = bodies.get(parentPath);
+		if (target) {
+			group.removeFromParent();
+			target.add(group);
+		} else {
+			console.warn(`[threejs] parent ref unresolved: "${parentPath}" for "${group.name}"`);
+			threeScene.add(group);
+		}
+	}
+
+	return { bodies, entityRoots };
+}
+
+export function createGeomMesh(g: Geom, color?: string): THREE.Mesh | null {
+	const geo = buildGeo(g);
+	if (!geo) return null;
+	geo.computeVertexNormals();
+	const mat = new THREE.MeshStandardMaterial({
+		color: color ?? g.color ?? '#6b7280',
+		roughness: 0.6, metalness: 0.1
+	});
+	const mesh = new THREE.Mesh(geo, mat);
+	mesh.castShadow = true;
+	mesh.receiveShadow = true;
+	return mesh;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { buildScene, createGeomMesh, buildLightComponent } from './compiler/threejs/index.js';
+export type { ViewerScene } from './compiler/threejs/index.js';
+
+export { parseThreeScene } from './parser/threejs/index.js';
+export type { ThreeEntity, ParseOptions, PrimitiveKind } from './parser/threejs/index.js';
+
+export { createViewport } from './viewport.js';
+export type { Viewport, ViewportOpts } from './viewport.js';
+
+export { buildBodyIdx, applyTransforms, flattenBodies, restoreBodies } from './sync.js';
+export type { BodySnapshot } from './sync.js';
+export { loadBodies, connectSim } from './sync.js';
+export type { BodyInfo, LoadBodiesOpts, LoadBodiesResult, SimOpts, SimHandle } from './sync.js';

package/src/parser/threejs/index.ts

@@ -0,0 +1,84 @@
+import * as THREE from 'three';
+import type { SceneDoc, DocEntity, Physics, Joint } from '@simarena/format';
+import type { Vec3, Geom } from '@simarena/format';
+
+export type PrimitiveKind = 'box' | 'sphere' | 'cylinder' | 'capsule' | 'plane';
+
+export interface ThreeEntity {
+	name: string;
+	obj: THREE.Object3D;
+	kind: 'primitive' | 'robot';
+	geom?: PrimitiveKind;
+	size?: Vec3;
+	color?: string;
+	asset?: string;
+	physics?: { dynamic?: boolean; mass?: number; friction?: number };
+	joint?: { type: 'free' | 'hinge' | 'slide' | 'fixed' };
+}
+
+export interface ParseOptions {
+	name?: string;
+	gravity?: Vec3;
+	timestep?: number;
+	substeps?: number;
+}
+
+function buildGeom(kind: PrimitiveKind | undefined, size: Vec3, color?: string): Geom {
+	const [a, b, c] = size;
+	switch (kind) {
+		case 'sphere':   return { type: 'sphere', radius: a, color, group: 'default' };
+		case 'cylinder': return { type: 'cylinder', radius: a, height: b, color, group: 'default' };
+		case 'capsule':  return { type: 'capsule', radius: a, height: b, color, group: 'default' };
+		case 'plane':    return { type: 'plane', size: [a, b], color, group: 'default' };
+		default:         return { type: 'box', size: [a, b, c] as Vec3, color, group: 'default' };
+	}
+}
+
+export function parseThreeScene(entities: ThreeEntity[], opts: ParseOptions = {}): SceneDoc {
+	const scene: DocEntity[] = entities.map(e => {
+		const pos = e.obj.position.toArray() as Vec3;
+		const q = e.obj.quaternion;
+		const hasRot = Math.abs(q.x) + Math.abs(q.y) + Math.abs(q.z) > 1e-6;
+		const quat = hasRot ? [q.w, q.x, q.y, q.z] as [number,number,number,number] : undefined;
+		const transform = { pos, ...(quat ? { quat } : {}) };
+
+		if (e.kind === 'robot' && e.asset) {
+			const scl = (e.obj.scale.x + e.obj.scale.y + e.obj.scale.z) / 3;
+			return {
+				name: e.name,
+				asset: e.asset,
+				transform: { ...transform, ...(Math.abs(scl - 1) > 0.001 ? { scale: scl } : {}) }
+			} satisfies DocEntity;
+		}
+
+		const dyn = e.physics?.dynamic ?? false;
+		const physics: Physics = {
+			dynamic: dyn,
+			...(e.physics?.mass !== undefined ? { mass: e.physics.mass } : {}),
+			...(e.physics?.friction !== undefined ? { friction: e.physics.friction } : {})
+		};
+		const joint: Joint | undefined = e.joint
+			? { type: e.joint.type }
+			: dyn ? { type: 'free' } : undefined;
+
+		return {
+			name: e.name,
+			transform,
+			geoms: [buildGeom(e.geom, e.size ?? [0.1, 0.1, 0.1], e.color)],
+			physics,
+			collider: {},
+			...(joint ? { joint } : {})
+		} satisfies DocEntity;
+	});
+
+	return {
+		_format: 'simarena/scene@1.0',
+		name: opts.name ?? 'Untitled Scene',
+		sim: {
+			timestep: opts.timestep ?? 0.002,
+			gravity: opts.gravity ?? [0, 0, -9.81],
+			substeps: opts.substeps ?? 4
+		},
+		scene
+	};
+}

package/src/sync.ts

@@ -0,0 +1,189 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+// ── Body index ─────────────────────────────────────────────────────────────────
+// Maps entity names → frame indices (matches the order bodies appear in sim state).
+
+export function buildBodyIdx(names: string[]): Map<string, number> {
+	const m = new Map<string, number>();
+	names.forEach((n, i) => m.set(n, i));
+	return m;
+}
+
+// ── Apply world-space transforms ───────────────────────────────────────────────
+// Works for any sim source: WASM worker, WebSocket, cloud.
+// xpos: flat Float32Array of positions [x0,y0,z0, x1,y1,z1, ...]
+// xquat: flat Float32Array of quaternions in wxyz order [w0,x0,y0,z0, ...]
+// Bodies not in the map are skipped automatically.
+
+export function applyTransforms(
+	xpos: Float32Array,
+	xquat: Float32Array,
+	bodyIdx: Map<string, number>,
+	bodies: Map<string, THREE.Object3D>
+): void {
+	for (const [name, idx] of bodyIdx) {
+		const obj = bodies.get(name);
+		if (!obj) continue;
+		const p = idx * 3, q = idx * 4;
+		obj.position.set(xpos[p]!, xpos[p + 1]!, xpos[p + 2]!);
+		// MuJoCo wxyz → Three.js xyzw
+		obj.quaternion.set(xquat[q + 1]!, xquat[q + 2]!, xquat[q + 3]!, xquat[q]!);
+	}
+}
+
+// ── Hierarchy flattening ───────────────────────────────────────────────────────
+// World-space transforms (from any sim) require bodies to be direct children
+// of the scene root. Flatten before sync, restore after.
+
+export interface BodySnapshot {
+	parent: THREE.Object3D;
+	pos: THREE.Vector3;
+	quat: THREE.Quaternion;
+	scale: THREE.Vector3;
+}
+
+export function flattenBodies(
+	bodies: Map<string, THREE.Object3D>,
+	scene: THREE.Scene
+): Map<string, BodySnapshot> {
+	const saved = new Map<string, BodySnapshot>();
+	for (const [name, obj] of bodies) {
+		saved.set(name, {
+			parent: obj.parent ?? scene,
+			pos: obj.position.clone(),
+			quat: obj.quaternion.clone(),
+			scale: obj.scale.clone(),
+		});
+		if (obj.parent !== scene) scene.attach(obj);
+	}
+	return saved;
+}
+
+export function restoreBodies(
+	flatBodies: Map<string, THREE.Object3D>,
+	saved: Map<string, BodySnapshot>
+): void {
+	for (const [name, obj] of flatBodies) {
+		const snap = saved.get(name);
+		if (snap) {
+			snap.parent.add(obj);
+			obj.position.copy(snap.pos);
+			obj.quaternion.copy(snap.quat);
+			obj.scale.copy(snap.scale);
+		}
+		obj.matrixWorldAutoUpdate = true;
+		obj.matrixWorldNeedsUpdate = true;
+	}
+}
+
+// ── HTTP body loading ──────────────────────────────────────────────────────────
+// Fetches GLBs from the Python viewport server (or any compatible server).
+// Returns Map<name, Object3D> keyed by entity name, matching SceneDoc entity names.
+
+export interface BodyInfo {
+	id: number;
+	name: string;
+	fixed?: boolean;
+	size?: number;
+}
+
+export interface LoadBodiesOpts {
+	onProgress?: (loaded: number, total: number) => void;
+}
+
+const loader = new GLTFLoader();
+
+export interface LoadBodiesResult {
+	bodies: Map<string, THREE.Object3D>;
+	manifest: BodyInfo[];
+}
+
+export async function loadBodies(
+	httpBase: string,
+	parent: THREE.Object3D,
+	opts: LoadBodiesOpts = {}
+): Promise<LoadBodiesResult> {
+	const base = httpBase.replace(/\/$/, '');
+	const res = await fetch(`${base}/bodies`);
+	const manifest: BodyInfo[] = await res.json();
+	const bodies = new Map<string, THREE.Object3D>();
+
+	await Promise.all(manifest.map(b =>
+		new Promise<void>(resolve => {
+			loader.load(`${base}/body/${b.id}.glb`, gltf => {
+				const mesh = gltf.scene;
+				mesh.traverse(c => {
+					if ((c as THREE.Mesh).isMesh) {
+						(c as THREE.Mesh).castShadow = true;
+						(c as THREE.Mesh).receiveShadow = true;
+					}
+				});
+				parent.add(mesh);
+				bodies.set(b.name, mesh);
+				opts.onProgress?.(bodies.size, manifest.length);
+				resolve();
+			});
+		})
+	));
+
+	return { bodies, manifest };
+}
+
+// ── WebSocket sim transport ────────────────────────────────────────────────────
+// Connects to any sim server streaming binary frames.
+// Wire protocol: [xpos: nbody*3 floats | xquat: nbody*4 floats]
+// Buffer length must be divisible by 7 (nbody*7 = pos+quat per body).
+
+export interface SimOpts {
+	onFps?: (fps: number) => void;
+	onParticles?: (positions: Float32Array) => void;
+	onConnect?: () => void;
+	onError?: (msg: string) => void;
+	onClose?: () => void;
+}
+
+export interface SimHandle {
+	close(): void;
+}
+
+export function connectSim(
+	wsUrl: string,
+	nbody: number,
+	onFrame: (xpos: Float32Array, xquat: Float32Array) => void,
+	opts: SimOpts = {}
+): SimHandle {
+	const ws = new WebSocket(wsUrl);
+	ws.binaryType = 'arraybuffer';
+
+	let frames = 0;
+	let lastTick = performance.now();
+
+	ws.onopen = () => opts.onConnect?.();
+
+	ws.onmessage = e => {
+		const buf = new Float32Array(e.data as ArrayBuffer);
+		const xpos = buf.subarray(0, nbody * 3);
+		const xquat = buf.subarray(nbody * 3, nbody * 7);
+		onFrame(xpos, xquat);
+
+		// Optional particle data appended after transforms
+		if (buf.length > nbody * 7 && opts.onParticles) {
+			const rest = buf.subarray(nbody * 7);
+			if (rest.length % 3 === 0) opts.onParticles(rest);
+		}
+
+		frames++;
+		const now = performance.now();
+		if (now - lastTick >= 1000) {
+			opts.onFps?.(frames);
+			frames = 0;
+			lastTick = now;
+		}
+	};
+
+	ws.onerror = () => opts.onError?.('WebSocket error');
+	ws.onclose = () => opts.onClose?.();
+
+	return { close: () => ws.close() };
+}

package/src/viewport.ts

@@ -0,0 +1,78 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+export interface ViewportOpts {
+	fov?: number;
+	near?: number;
+	far?: number;
+	pos?: [number, number, number];
+	target?: [number, number, number];
+	grid?: number;
+}
+
+export interface Viewport {
+	scene: THREE.Scene;
+	camera: THREE.PerspectiveCamera;
+	renderer: THREE.WebGLRenderer;
+	orbit: OrbitControls;
+	grid: THREE.GridHelper | null;
+	resize(): void;
+	dispose(): void;
+}
+
+export function createViewport(
+	canvas: HTMLCanvasElement,
+	container: HTMLElement,
+	opts: ViewportOpts = {}
+): Viewport {
+	const { fov = 60, near = 0.1, far = 100, pos = [1.5, -1.5, 1.5], target = [0, 0, 0.3], grid = 2 } = opts;
+
+	THREE.Object3D.DEFAULT_UP.set(0, 0, 1);
+
+	const scene = new THREE.Scene();
+
+	const camera = new THREE.PerspectiveCamera(fov, container.clientWidth / container.clientHeight, near, far);
+	camera.position.set(...pos);
+	camera.lookAt(...target);
+
+	const gl = canvas.getContext('webgl2');
+	const renderer = new THREE.WebGLRenderer({ canvas, context: gl || undefined, antialias: true });
+	renderer.setSize(container.clientWidth, container.clientHeight);
+	renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+	renderer.shadowMap.enabled = true;
+	renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+	renderer.toneMapping = THREE.ACESFilmicToneMapping;
+	renderer.toneMappingExposure = 1.0;
+	renderer.outputColorSpace = THREE.SRGBColorSpace;
+
+	const orbit = new OrbitControls(camera, renderer.domElement);
+	orbit.enableDamping = true;
+	orbit.dampingFactor = 0.05;
+	orbit.target.set(...target);
+	orbit.update();
+
+	let gridHelper: THREE.GridHelper | null = null;
+	if (grid > 0) {
+		gridHelper = new THREE.GridHelper(grid * 10, 20, 0x444444, 0x222222);
+		gridHelper.rotation.x = Math.PI / 2;
+		scene.add(gridHelper);
+	}
+
+	function resize() {
+		const w = container.clientWidth, h = container.clientHeight;
+		camera.aspect = w / h;
+		camera.updateProjectionMatrix();
+		renderer.setSize(w, h);
+	}
+
+	const obs = new ResizeObserver(resize);
+	obs.observe(container);
+
+	function dispose() {
+		obs.disconnect();
+		renderer.dispose();
+		orbit.dispose();
+	}
+
+	return { scene, camera, renderer, orbit, grid: gridHelper, resize, dispose };
+}