@scenography/engine 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -1,219 +1,373 @@
-import { AmbientLight, Clock, DoubleSide, Group, HemisphereLight, Mesh, MeshBasicMaterial, MeshStandardMaterial, PerspectiveCamera, PlaneGeometry, Quaternion, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
-//#region src/controls/boundaries.ts
-/**
-* Clamp a step on the XZ plane to a square `[-bound, bound]`. Axes are clamped
-* independently so sliding along a wall still works when one axis is blocked.
-*/
-const clampToBounds = (current, step, bound) => {
-	const next = new Vector3().addVectors(current, step);
-	if (next.x < -bound || next.x > bound) next.x = current.x;
-	if (next.z < -bound || next.z > bound) next.z = current.z;
-	return next;
-};
-//#endregion
-//#region src/controls/headBob.ts
-const createHeadBobState = () => ({
-	active: false,
-	timer: 0
-});
-/**
-* Advance the head-bob timer by `elapsed` seconds, snapping to half-wavelength
-* steps so the bob always settles back to neutral when movement stops.
-*/
-const updateHeadBob = (state, elapsed) => {
-	if (!state.active) return;
-	const wavelength = Math.PI;
-	const nextStepTime = (1 + Math.floor((state.timer + 1e-6) * 10 / wavelength)) * wavelength / 10;
-	state.timer = Math.min(state.timer + elapsed, nextStepTime);
-	if (state.timer === nextStepTime) state.active = false;
-};
-/** Vertical offset to add to the camera, in world units. */
-const headBobOffset = (state) => Math.sin(state.timer * 10) * 1.5;
-//#endregion
-//#region src/controls/keyboard.ts
-const createKeyboardState = () => ({});
-const onKeyDown = (state, event) => {
-	state[event.code] = true;
-};
-const onKeyUp = (state, event) => {
-	state[event.code] = false;
-};
-/**
-* Compute the per-frame translation from WASD input, oriented by the current
-* yaw (`phi`). Holding Shift acts as a speed booster.
-*/
-const movementFromKeyboard = (state, phi, delta) => {
-	const has = (code) => state[code] ? 1 : 0;
-	const forwardVelocity = has("KeyW") - has("KeyS");
-	const strafeVelocity = has("KeyA") - has("KeyD");
-	const factor = state["ShiftLeft"] || state["ShiftRight"] ? 30 : 10;
-	const yaw = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), phi);
-	const forward = new Vector3(0, 0, -10).applyQuaternion(yaw).multiplyScalar(forwardVelocity * delta * factor);
-	const left = new Vector3(-10, 0, 0).applyQuaternion(yaw).multiplyScalar(strafeVelocity * delta * factor);
-	return forward.add(left);
-};
-//#endregion
-//#region src/controls/mouse.ts
-const PHI_SPEED = 8;
-const THETA_SPEED = 5;
-const createMouseState = () => ({
-	dragging: false,
-	pos: new Vector2(),
-	prevPos: new Vector2(),
-	delta: new Vector2()
-});
-const clamp = (x, a, b) => Math.min(Math.max(x, a), b);
-const onMouseDown = (state, event) => {
-	state.dragging = event.button === 0;
-};
-const onMouseUp = (state) => {
-	state.dragging = false;
-};
-const onMouseMove = (state, event) => {
-	state.pos.set(event.pageX - window.innerWidth / 2, event.pageY - window.innerHeight / 2);
-	state.delta.subVectors(state.pos, state.prevPos);
-};
-const commitMouseFrame = (state) => {
-	state.prevPos.copy(state.pos);
-	state.delta.set(0, 0);
+import { BoxGeometry, Clock, EquirectangularReflectionMapping, Group, HalfFloatType, Mesh, MeshBasicMaterial, NoColorSpace, PCFShadowMap, PerspectiveCamera, Quaternion, Raycaster, RepeatWrapping, SRGBColorSpace, Scene, StereoCamera, TextureLoader, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
+//#region src/environment/EnvironmentController.ts
+/** Load an equirectangular HDRI, picking the loader by extension. */
+const loadHDRI = (src, onLoad) => {
+	if (src.toLowerCase().endsWith(".exr")) import("three/examples/jsm/loaders/EXRLoader.js").then(({ EXRLoader }) => {
+		new EXRLoader().load(src, onLoad);
+	});
+	else import("three/examples/jsm/loaders/RGBELoader.js").then(({ RGBELoader }) => {
+		new RGBELoader().load(src, onLoad);
+	});
 };
 /**
-* Integrate the pointer delta into a look quaternion. Mutates `look` and
-* returns the resulting rotation. Yaw is unbounded; pitch is clamped to avoid
-* flipping over.
+* Owns the scene's HDRI sky / image-based lighting and keeps it in sync with the
+* `Environment` definition. Loads the equirectangular map on demand (its loader
+* ships in its own chunk) and assigns it to `scene.background` and/or
+* `scene.environment`. Reconciles by a JSON hash so hot edits only reload when
+* the definition actually changes.
 */
-const updateLookFromMouse = (mouse, look) => {
-	const xh = mouse.delta.x / window.innerWidth;
-	const yh = mouse.delta.y / window.innerHeight;
-	look.phi += -xh * PHI_SPEED;
-	look.theta = clamp(look.theta + -yh * THETA_SPEED, -Math.PI / 3, Math.PI / 3);
-	const qy = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), look.phi);
-	const qx = new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), look.theta);
-	return new Quaternion().multiply(qy).multiply(qx);
+var EnvironmentController = class {
+	scene;
+	hash = null;
+	texture = null;
+	constructor(scene) {
+		this.scene = scene;
+	}
+	reconcile(env) {
+		const hash = env ? JSON.stringify(env) : null;
+		if (hash === this.hash) return;
+		this.hash = hash;
+		this.clear();
+		if (!env) return;
+		loadHDRI(env.src, (tex) => {
+			if (this.hash !== hash) {
+				tex.dispose();
+				return;
+			}
+			tex.mapping = EquirectangularReflectionMapping;
+			this.texture = tex;
+			if (env.background ?? true) {
+				this.scene.background = tex;
+				this.scene.backgroundIntensity = env.intensity ?? 1;
+			}
+			if (env.lighting ?? true) this.scene.environment = tex;
+		});
+	}
+	/** Set the visible sky background brightness (0 = black). Live, for behavior. */
+	setBackgroundIntensity(value) {
+		this.scene.backgroundIntensity = value;
+	}
+	clear() {
+		this.scene.background = null;
+		this.scene.environment = null;
+		this.texture?.dispose();
+		this.texture = null;
+	}
+	dispose() {
+		this.clear();
+		this.hash = null;
+	}
 };
 //#endregion
-//#region src/controls/FreeRoamControls.ts
+//#region src/interaction/InteractionController.ts
+const HIGHLIGHT_COLOR = "#ef4444";
+const HIGHLIGHT_THICKNESS = 1.5;
+const HIGHLIGHT_MARGIN = 1.5;
+const CLICK_SLOP = 4;
 /**
-* First-person, free-roaming camera controls ported from the original Virtual
-* Gallery: drag-to-look with the mouse, WASD to walk, a subtle head-bob while
-* moving, and square boundary clamping. The cardboard / device-orientation path
-* was intentionally dropped.
-*
-* Framework-agnostic: construct it with a camera and the canvas element, call
-* `attach()`, then `update(delta)` once per frame.
+* Pointer picking for artworks: hovering a piece's click target (its label, or
+* the piece itself when it has none) draws a pulsing red frame and shows a
+* pointer cursor; clicking it emits `artwork:select { id }`. Targets are marked
+* in the scene graph (`userData.pickTarget`/`pickInfo`) by the artwork builder,
+* so this just raycasts and walks up to find them. An optional per-id radius
+* gates interaction to when the camera is reasonably close.
 */
-var FreeRoamControls = class {
-	bounds;
+var InteractionController = class {
 	camera;
-	domElement;
-	mouse = createMouseState();
-	keyboard = createKeyboardState();
-	headBob = createHeadBobState();
-	look = {
-		phi: 0,
-		theta: 0
-	};
-	rotation = new Quaternion();
-	translation = new Vector3(0, 170, 0);
+	canvas;
+	scene;
+	emit;
+	canInteract;
+	raycaster = new Raycaster();
+	pointer = new Vector2();
+	over = false;
+	downPos = null;
+	radii = /* @__PURE__ */ new Map();
+	hovered = null;
+	time = 0;
+	highlight = new Group();
+	highlightMat = null;
 	handlers = [];
-	constructor(camera, domElement, options = {}) {
+	constructor(camera, canvas, scene, emit, canInteract) {
 		this.camera = camera;
-		this.domElement = domElement;
-		this.bounds = options.bounds ?? 450;
-		if (options.position) this.translation.copy(options.position);
-		if (options.yaw !== void 0) this.look.phi = options.yaw;
-		this.rotation.setFromAxisAngle(new Vector3(0, 1, 0), this.look.phi);
+		this.canvas = canvas;
+		this.scene = scene;
+		this.emit = emit;
+		this.canInteract = canInteract;
+		this.highlight.visible = false;
+		this.scene.add(this.highlight);
+	}
+	/** Per-artwork max interaction distance (XZ). Absent id = no distance gate. */
+	setRadii(radii) {
+		this.radii = radii;
 	}
 	attach() {
-		const bind = (target, type, listener) => {
-			target.addEventListener(type, listener);
+		const bind = (type, listener) => {
+			this.canvas.addEventListener(type, listener);
 			this.handlers.push([
-				target,
+				this.canvas,
 				type,
 				listener
 			]);
 		};
-		bind(this.domElement, "mousedown", (e) => onMouseDown(this.mouse, e));
-		bind(window, "mousemove", (e) => onMouseMove(this.mouse, e));
-		bind(window, "mouseup", () => onMouseUp(this.mouse));
-		bind(window, "keydown", (e) => onKeyDown(this.keyboard, e));
-		bind(window, "keyup", (e) => onKeyUp(this.keyboard, e));
+		bind("pointermove", (e) => this.onMove(e));
+		bind("pointerdown", (e) => this.onDown(e));
+		bind("pointerup", (e) => this.onUp(e));
+		bind("pointerleave", () => {
+			this.over = false;
+		});
 	}
 	detach() {
 		for (const [target, type, listener] of this.handlers) target.removeEventListener(type, listener);
 		this.handlers.length = 0;
+		this.scene.remove(this.highlight);
+		this.clearHighlight();
 	}
-	/** Advance the camera by `delta` seconds of input. */
-	update(delta) {
-		if (this.mouse.dragging) this.rotation = updateLookFromMouse(this.mouse, this.look);
-		const step = movementFromKeyboard(this.keyboard, this.look.phi, delta);
-		this.translation = clampToBounds(this.translation, step, this.bounds);
-		if (step.x !== 0 || step.z !== 0) this.headBob.active = true;
-		updateHeadBob(this.headBob, delta);
-		this.camera.quaternion.copy(this.rotation);
-		this.camera.position.copy(this.translation);
-		this.camera.position.y += headBobOffset(this.headBob);
-		const target = new Vector3(0, 0, -1).applyQuaternion(this.rotation).multiplyScalar(100).add(this.translation);
-		this.camera.lookAt(target);
-		commitMouseFrame(this.mouse);
+	setPointer(e) {
+		const rect = this.canvas.getBoundingClientRect();
+		this.pointer.set((e.clientX - rect.left) / rect.width * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
+		this.over = true;
+	}
+	onMove(e) {
+		this.setPointer(e);
+	}
+	onDown(e) {
+		this.downPos = {
+			x: e.clientX,
+			y: e.clientY
+		};
+	}
+	onUp(e) {
+		const down = this.downPos;
+		this.downPos = null;
+		if (!down || !this.canInteract()) return;
+		if (Math.hypot(e.clientX - down.x, e.clientY - down.y) > CLICK_SLOP) return;
+		this.setPointer(e);
+		const pick = this.raycast();
+		if (pick) this.emit("artwork:select", { id: pick.id });
+	}
+	/** Resolve the nearest pickable artwork under the pointer, honoring the gate. */
+	raycast() {
+		this.raycaster.setFromCamera(this.pointer, this.camera);
+		const hits = this.raycaster.intersectObjects(this.scene.children, true);
+		for (const hit of hits) {
+			let node = hit.object;
+			while (node && node.userData.pickTarget === void 0) node = node.parent;
+			if (!node) continue;
+			const id = node.userData.pickTarget;
+			const radius = this.radii.get(id);
+			if (radius !== void 0) {
+				const p = node.getWorldPosition(new Vector3());
+				if (Math.hypot(this.camera.position.x - p.x, this.camera.position.z - p.z) > radius) continue;
+			}
+			return {
+				id,
+				holder: node,
+				info: node.userData.pickInfo
+			};
+		}
+		return null;
+	}
+	/** Recompute hover state and animate the highlight. Call once per frame. */
+	update(deltaMs) {
+		this.time += deltaMs;
+		const pick = this.over && this.canInteract() ? this.raycast() : null;
+		if ((pick?.id ?? null) !== this.hovered) {
+			this.hovered = pick?.id ?? null;
+			this.canvas.style.cursor = pick ? "pointer" : "";
+			if (pick) this.buildHighlight(pick);
+			else this.highlight.visible = false;
+		}
+		if (this.highlight.visible && this.highlightMat) this.highlightMat.opacity = .45 + .45 * (.5 + .5 * Math.sin(this.time / 320));
+	}
+	clearHighlight() {
+		for (const child of [...this.highlight.children]) {
+			this.highlight.remove(child);
+			child.geometry?.dispose();
+		}
+		this.highlightMat?.dispose();
+		this.highlightMat = null;
+	}
+	/** Position a fresh pulsing red frame over the picked target's front face. */
+	buildHighlight(pick) {
+		this.clearHighlight();
+		const mat = new MeshBasicMaterial({
+			color: HIGHLIGHT_COLOR,
+			transparent: true,
+			depthTest: false
+		});
+		this.highlightMat = mat;
+		const w = pick.info.width + 2 * HIGHLIGHT_MARGIN;
+		const h = pick.info.height + 2 * HIGHLIGHT_MARGIN;
+		const t = HIGHLIGHT_THICKNESS;
+		const bars = [
+			[
+				w + 2 * t,
+				t,
+				0,
+				h / 2 + t / 2
+			],
+			[
+				w + 2 * t,
+				t,
+				0,
+				-(h / 2 + t / 2)
+			],
+			[
+				t,
+				h,
+				-(w / 2 + t / 2),
+				0
+			],
+			[
+				t,
+				h,
+				w / 2 + t / 2,
+				0
+			]
+		];
+		for (const [bw, bh, x, y] of bars) {
+			const bar = new Mesh(new BoxGeometry(bw, bh, .5), mat);
+			bar.position.set(x, y, 0);
+			bar.renderOrder = 999;
+			this.highlight.add(bar);
+		}
+		const pos = pick.holder.getWorldPosition(new Vector3());
+		const quat = pick.holder.getWorldQuaternion(new Quaternion());
+		const normal = new Vector3(0, 0, 1).applyQuaternion(quat);
+		pos.addScaledVector(normal, pick.info.frontOffset);
+		this.highlight.position.copy(pos);
+		this.highlight.quaternion.copy(quat);
+		this.highlight.visible = true;
 	}
 };
 //#endregion
-//#region src/builders/wall.ts
-/** Build the three.js object that materializes a `Wall` definition. */
-function buildWall(wall) {
-	const [width, height] = wall.size;
-	const mesh = new Mesh(new PlaneGeometry(width, height), new MeshStandardMaterial({
-		color: wall.color ?? "#ffffff",
-		side: DoubleSide
-	}));
-	mesh.position.set(wall.position[0], wall.position[1], wall.position[2]);
-	mesh.rotation.y = wall.rotation ?? 0;
-	mesh.name = `wall:${wall.id}`;
-	mesh.userData.scenographyId = wall.id;
-	return mesh;
-}
+//#region src/input/InputBus.ts
+/**
+* The shared analog-input channel: the current movement and look intent, each
+* axis in `-1..1` and held until a producer changes it. Producers (on-screen
+* joysticks in the overlay, a gamepad…) write to it; whatever camera system is
+* active reads it and interprets it its own way — free-roam walks with it, a
+* fixed camera might only use the look axes to glance around. This is what makes
+* the joysticks reusable across camera types. Pure state — no three.js.
+*/
+var InputBus = class {
+	/** Forward (`+1`) / backward (`-1`). */
+	moveForward = 0;
+	/** Strafe right (`+1`) / left (`-1`). */
+	moveStrafe = 0;
+	/** Look right (`+1`) / left (`-1`). */
+	lookX = 0;
+	/** Look up (`+1`) / down (`-1`). */
+	lookY = 0;
+	/** Set the movement intent (forward, strafe). */
+	setMove(forward, strafe = 0) {
+		this.moveForward = forward;
+		this.moveStrafe = strafe;
+	}
+	/** Set the look intent (turn, pitch). */
+	setLook(x, y = 0) {
+		this.lookX = x;
+		this.lookY = y;
+	}
+};
 //#endregion
-//#region src/builders/artwork.ts
-const loader = new TextureLoader();
-const FRAME_MARGIN = 4;
-const SURFACE_OFFSET = 1;
+//#region src/plugin/CapabilityRegistry.ts
 /**
-* Build the three.js object for an `Artwork`, placing it on its wall. The piece
-* is positioned in the wall's local plane via `offset` and nudged forward along
-* the wall normal so it sits in front of the surface.
+* Shared runtime contracts between plugins, keyed by name. A plugin (or the
+* kernel) *provides* a capability — e.g. the floor provides `terrain` — and
+* other plugins *consume* it if present, without depending on the provider's
+* package. Each name keeps a monotonic version counter so consumers can hash
+* their dependencies cheaply and rebuild when a provider changes.
 */
-function buildArtwork(artwork, wall) {
-	const [width, height] = artwork.size;
-	const [offsetX, offsetY] = artwork.offset ?? [0, 0];
-	const yaw = wall.rotation ?? 0;
-	const group = new Group();
-	const wallQuat = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), yaw);
-	const right = new Vector3(1, 0, 0).applyQuaternion(wallQuat);
-	const normal = new Vector3(0, 0, 1).applyQuaternion(wallQuat);
-	const position = new Vector3(wall.position[0], wall.position[1], wall.position[2]).add(right.clone().multiplyScalar(offsetX)).add(new Vector3(0, offsetY, 0)).add(normal.clone().multiplyScalar(SURFACE_OFFSET));
-	group.position.copy(position);
-	group.rotation.y = yaw;
-	const frame = new Mesh(new PlaneGeometry(width + FRAME_MARGIN, height + FRAME_MARGIN), new MeshStandardMaterial({ color: "#1a1a1a" }));
-	group.add(frame);
-	const texture = loader.load(artwork.src);
-	texture.colorSpace = SRGBColorSpace;
-	const image = new Mesh(new PlaneGeometry(width, height), new MeshBasicMaterial({ map: texture }));
-	image.position.z = .1;
-	group.add(image);
-	group.name = `artwork:${artwork.id}`;
-	group.userData.scenographyId = artwork.id;
-	group.userData.wallId = artwork.wall;
-	return group;
-}
+var CapabilityRegistry = class {
+	values = /* @__PURE__ */ new Map();
+	versions = /* @__PURE__ */ new Map();
+	/** Last change-token seen per name, to suppress redundant version bumps. */
+	tokens = /* @__PURE__ */ new Map();
+	/**
+	* Publish (or replace) the capability under `name`. Pass a `token` (a cheap
+	* hash of the inputs) to dedupe: re-providing with an unchanged token is a
+	* no-op, so consumers that depend on this capability don't rebuild when the
+	* provider recomputes an identical value.
+	*/
+	provide(name, value, token) {
+		if (token !== void 0 && this.values.has(name) && this.tokens.get(name) === token) return;
+		this.values.set(name, value);
+		if (token !== void 0) this.tokens.set(name, token);
+		else this.tokens.delete(name);
+		this.bump(name);
+	}
+	/** Remove the capability; consumers see `undefined` and a version bump. */
+	revoke(name) {
+		if (this.values.delete(name)) {
+			this.tokens.delete(name);
+			this.bump(name);
+		}
+	}
+	get(name) {
+		return this.values.get(name);
+	}
+	/** Monotonic change counter for `name` (`0` if never provided). */
+	version(name) {
+		return this.versions.get(name) ?? 0;
+	}
+	bump(name) {
+		this.versions.set(name, (this.versions.get(name) ?? 0) + 1);
+	}
+};
+//#endregion
+//#region src/plugin/systemPlugin.ts
+/** Narrow a mixed plugin to a system plugin (has `setup`, not `build`). */
+const isSystemPlugin = (plugin) => typeof plugin === "object" && plugin !== null && "setup" in plugin;
+//#endregion
+//#region src/plugin/roamControl.ts
+/** Capability name under which a roaming camera system exposes pose control. */
+const ROAM_CONTROL = "roamControl";
+//#endregion
+//#region src/plugin/terrain.ts
+/** Capability name under which the floor publishes its terrain. */
+const TERRAIN = "terrain";
+//#endregion
+//#region src/plugin/colliders.ts
+/** Capability name under which walkable-space obstacles are published. */
+const COLLIDERS = "colliders";
+//#endregion
+//#region src/plugin/edges.ts
+/** Capability name under which named wall edges are published for hanging. */
+const EDGES = "edges";
+//#endregion
+//#region src/plugin/eyeHeight.ts
+/**
+* Capability name under which the visitor's eye height (world units) is
+* published — the default vertical placement for wall-hung artworks. The kernel
+* provides it from the camera start; a camera plugin will own it later.
+*/
+const EYE_HEIGHT = "eyeHeight";
 //#endregion
 //#region src/SceneManager.ts
 const disposeObject = (object) => {
 	object.traverse((child) => {
+		const video = child.userData?.video;
+		if (video) {
+			video.pause();
+			video.removeAttribute("src");
+			video.load();
+		}
 		const mesh = child;
 		mesh.geometry?.dispose?.();
+		const dispose = (m) => {
+			const material = m;
+			for (const slot of [
+				"map",
+				"normalMap",
+				"roughnessMap",
+				"aoMap",
+				"metalnessMap"
+			]) (material?.[slot])?.dispose?.();
+			material?.dispose?.();
+		};
 		const material = mesh.material;
-		const dispose = (m) => m?.dispose?.();
 		if (Array.isArray(material)) material.forEach(dispose);
 		else dispose(material);
 	});
@@ -227,82 +381,109 @@ const disposeObject = (object) => {
 */
 var SceneManager = class {
 	root;
-	walls = /* @__PURE__ */ new Map();
-	artworks = /* @__PURE__ */ new Map();
-	constructor(root) {
+	plugins;
+	capabilities;
+	/** Mounted plugin elements, per kind, keyed by element id ("" for singletons). */
+	pluginElements = /* @__PURE__ */ new Map();
+	constructor(root, plugins = [], capabilities = new CapabilityRegistry()) {
 		this.root = root;
+		this.plugins = plugins;
+		this.capabilities = capabilities;
 	}
 	reconcile(scene) {
-		const wallById = new Map(scene.walls.map((w) => [w.id, w]));
-		this.reconcileWalls(scene.walls);
-		this.reconcileArtworks(scene.artworks, wallById);
+		const eye = scene.camera.start.position[1];
+		this.capabilities.provide(EYE_HEIGHT, eye, String(eye));
+		this.reconcilePlugins(scene);
 	}
-	reconcileWalls(walls) {
-		const next = new Set(walls.map((w) => w.id));
-		for (const [id, entry] of this.walls) if (!next.has(id)) {
-			this.root.remove(entry.object);
-			disposeObject(entry.object);
-			this.walls.delete(id);
-		}
-		for (const wall of walls) {
-			const hash = JSON.stringify(wall);
-			const existing = this.walls.get(wall.id);
-			if (existing?.hash === hash) continue;
-			if (existing) {
-				this.root.remove(existing.object);
-				disposeObject(existing.object);
+	/**
+	* Reconcile every registered plugin's elements by content: an element
+	* rebuilds when its definition changes or when a capability it depends on
+	* was re-provided (the capability versions are part of the hash).
+	*/
+	reconcilePlugins(scene) {
+		for (const plugin of this.plugins) {
+			const { kind, cardinality } = plugin.data;
+			let mounted = this.pluginElements.get(kind);
+			if (!mounted) {
+				mounted = /* @__PURE__ */ new Map();
+				this.pluginElements.set(kind, mounted);
+			}
+			const raw = scene[kind];
+			const items = cardinality === "many" ? Array.isArray(raw) ? raw.map((item, i) => [String(item.id ?? i), item]) : [] : raw !== void 0 ? [["", raw]] : [];
+			const deps = (plugin.dependsOn ?? []).map((name) => this.capabilities.version(name));
+			const seen = /* @__PURE__ */ new Set();
+			for (const [key, value] of items) {
+				seen.add(key);
+				const hash = JSON.stringify({
+					value,
+					deps
+				});
+				const existing = mounted.get(key);
+				if (existing?.hash === hash) continue;
+				if (existing) this.removePluginElement(mounted, key, existing);
+				const built = plugin.build(value, { capabilities: this.capabilities });
+				if (built.object) this.root.add(built.object);
+				mounted.set(key, {
+					...built,
+					hash
+				});
 			}
-			const object = buildWall(wall);
-			this.root.add(object);
-			this.walls.set(wall.id, {
-				object,
-				hash
-			});
+			for (const [key, entry] of mounted) if (!seen.has(key)) this.removePluginElement(mounted, key, entry);
+			plugin.provide?.(items.map(([, value]) => value), { capabilities: this.capabilities });
 		}
 	}
-	reconcileArtworks(artworks, wallById) {
-		const next = new Set(artworks.map((a) => a.id));
-		for (const [id, entry] of this.artworks) if (!next.has(id)) {
+	removePluginElement(mounted, key, entry) {
+		if (entry.object) {
 			this.root.remove(entry.object);
 			disposeObject(entry.object);
-			this.artworks.delete(id);
-		}
-		for (const artwork of artworks) {
-			const wall = wallById.get(artwork.wall);
-			if (!wall) continue;
-			const hash = JSON.stringify({
-				a: artwork,
-				w: wall
-			});
-			const existing = this.artworks.get(artwork.id);
-			if (existing?.hash === hash) continue;
-			if (existing) {
-				this.root.remove(existing.object);
-				disposeObject(existing.object);
-			}
-			const object = buildArtwork(artwork, wall);
-			this.root.add(object);
-			this.artworks.set(artwork.id, {
-				object,
-				hash
-			});
 		}
+		entry.dispose?.();
+		mounted.delete(key);
+	}
+	/** Advance time-based plugin elements (e.g. water ripple). Call once per frame. */
+	updateElements(deltaMs) {
+		for (const mounted of this.pluginElements.values()) for (const entry of mounted.values()) entry.update?.(deltaMs);
 	}
-	/** Look up the live three.js object for a wall or artwork `id`. */
+	/** Run every element's auxiliary pre-render pass (e.g. water reflection). */
+	beforeRender(renderer, scene, camera) {
+		for (const mounted of this.pluginElements.values()) for (const entry of mounted.values()) entry.beforeRender?.(renderer, scene, camera);
+	}
+	/** Look up the live three.js object for any plugin element `id`. */
 	get(id) {
-		return this.walls.get(id)?.object ?? this.artworks.get(id)?.object;
+		for (const mounted of this.pluginElements.values()) {
+			const object = mounted.get(id)?.object;
+			if (object) return object;
+		}
+	}
+	/** Live objects of one plugin kind, keyed by `id` — for that plugin's controller. */
+	elementsOf(kind) {
+		const out = /* @__PURE__ */ new Map();
+		const mounted = this.pluginElements.get(kind);
+		if (mounted) {
+			for (const [id, entry] of mounted) if (entry.object) out.set(id, entry.object);
+		}
+		return out;
 	}
 	dispose() {
-		for (const entry of [...this.walls.values(), ...this.artworks.values()]) {
-			this.root.remove(entry.object);
-			disposeObject(entry.object);
+		for (const [kind, mounted] of this.pluginElements) {
+			for (const [key, entry] of mounted) this.removePluginElement(mounted, key, entry);
+			this.pluginElements.delete(kind);
 		}
-		this.walls.clear();
-		this.artworks.clear();
 	}
 };
 //#endregion
 //#region src/createGallery.ts
+/** Maps a plugin kind/name onto the `ctx` slot its api fills. */
+const CTX_SLOT = {
+	camera: "focus",
+	lights: "lights",
+	video: "videos",
+	sky: "sky",
+	media: "audio"
+};
+/** The system the cardboard render toggle drives (gyroscope head-look). */
+const CARDBOARD_SYSTEM = "cardboard";
+const DEFAULT_EYE_SEPARATION = 3;
 /**
 * Create and run a gallery from a scene definition. Sets up the three.js
 * renderer, camera, lights and free-roam controls, materializes the scene, and
@@ -314,35 +495,220 @@ function createGallery(scene, options) {
 	const height = canvas.clientHeight || window.innerHeight;
 	const renderer = new WebGLRenderer({
 		canvas,
-		antialias: options.antialias ?? true
+		antialias: false
 	});
 	renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
 	renderer.setSize(width, height, false);
+	renderer.shadowMap.type = PCFShadowMap;
+	const render = {
+		antialias: options.antialias ?? 4,
+		ssao: options.ssao ?? false,
+		bloom: options.bloom ?? 0,
+		shadows: options.shadows ?? true,
+		cardboard: options.cardboard ?? false,
+		eyeSeparation: options.eyeSeparation ?? DEFAULT_EYE_SEPARATION
+	};
+	const stereo = new StereoCamera();
+	stereo.aspect = .5;
+	stereo.eyeSep = render.eyeSeparation;
+	const stereoSize = new Vector2();
 	const threeScene = new Scene();
-	const camera = new PerspectiveCamera(75, width / height, .1, 5e3);
-	const { position, yaw } = scene.camera.start;
+	const camera = new PerspectiveCamera(scene.camera.fov ?? 55, width / height, .1, 5e3);
+	const { position } = scene.camera.start;
 	camera.position.set(position[0], position[1], position[2]);
-	threeScene.add(new AmbientLight(16777215, 1.4));
-	threeScene.add(new HemisphereLight(16777215, 4473924, 1));
-	const manager = new SceneManager(threeScene);
+	const allPlugins = options.plugins ?? [];
+	const systemPlugins = allPlugins.filter(isSystemPlugin);
+	const elementPlugins = allPlugins.filter((p) => !isSystemPlugin(p));
+	const capabilities = new CapabilityRegistry();
+	const manager = new SceneManager(threeScene, elementPlugins, capabilities);
 	manager.reconcile(scene);
-	const controls = new FreeRoamControls(camera, canvas, {
-		bounds: scene.camera.bounds,
-		position: camera.position.clone(),
-		yaw
-	});
-	controls.attach();
+	const input = new InputBus();
+	const environment = new EnvironmentController(threeScene);
+	environment.reconcile(scene.environment);
 	const listeners = /* @__PURE__ */ new Map();
+	const emit = (event, payload) => {
+		listeners.get(event)?.forEach((handler) => handler(payload));
+	};
+	const frameHandlers = /* @__PURE__ */ new Set();
+	const apis = /* @__PURE__ */ new Map();
+	const controllers = [];
+	for (const plugin of elementPlugins) {
+		const controller = plugin.controller?.(() => manager.elementsOf(plugin.data.kind));
+		if (!controller) continue;
+		if (controller.api !== void 0) apis.set(plugin.data.kind, controller.api);
+		controllers.push(controller);
+	}
+	const systems = systemPlugins.map((plugin) => {
+		const instance = plugin.setup({
+			scene,
+			camera,
+			canvas,
+			scene3d: threeScene,
+			renderer,
+			input,
+			capabilities,
+			emit,
+			resolve: (id) => manager.get(id)
+		});
+		if (instance.api !== void 0) apis.set(plugin.name, instance.api);
+		return instance;
+	});
+	const cameraApi = apis.get(CTX_SLOT.camera) ?? {
+		focusArtwork: () => {},
+		centerArtwork: () => {},
+		release: () => {},
+		isAnimating: () => false
+	};
+	const headTracking = apis.get(CARDBOARD_SYSTEM);
+	if (options.cardboard) headTracking?.setEnabled(true);
+	const lightsApi = apis.get(CTX_SLOT.lights) ?? {
+		set: () => {},
+		dimAll: () => {},
+		restore: () => {}
+	};
+	const videoApi = apis.get(CTX_SLOT.video) ?? {
+		play: () => {},
+		pause: () => {},
+		setVisible: () => {}
+	};
+	const skyApi = apis.get(CTX_SLOT.sky) ?? {
+		setTime: () => {},
+		getTime: () => 12,
+		setAzimuth: () => {},
+		getAzimuth: () => 0
+	};
+	const mediaApi = apis.get(CTX_SLOT.media) ?? {
+		play: () => {},
+		pause: () => {},
+		stop: () => {},
+		setVolume: () => {},
+		playing: () => false,
+		setMuted: () => {},
+		muted: () => false
+	};
+	const radiiOf = (s) => {
+		const gated = s.artworks ?? [];
+		return new Map(gated.filter((a) => a.infoRadius !== void 0).map((a) => [a.id, a.infoRadius]));
+	};
+	const interaction = new InteractionController(camera, canvas, threeScene, emit, () => !cameraApi.isAnimating());
+	interaction.setRadii(radiiOf(scene));
+	interaction.attach();
 	const clock = new Clock();
 	let rafId = null;
+	const BLOOM = {
+		radius: .4,
+		threshold: .85
+	};
+	let postClasses = null;
+	let composer = null;
+	let ssaoPass = null;
+	let bloomPass = null;
+	let composerLoading = false;
+	const pixelRatio = Math.min(window.devicePixelRatio, 2);
+	const needsComposer = () => render.antialias > 0 || render.ssao || render.bloom > 0;
+	const buildComposer = () => {
+		if (!postClasses) return;
+		composer?.dispose();
+		const { EffectComposer, RenderPass, SSAOPass, UnrealBloomPass, OutputPass } = postClasses;
+		const c = new EffectComposer(renderer, new WebGLRenderTarget(1, 1, {
+			samples: render.antialias,
+			type: HalfFloatType
+		}));
+		c.setPixelRatio(pixelRatio);
+		c.setSize(width, height);
+		c.addPass(new RenderPass(threeScene, camera));
+		const ssao = new SSAOPass(threeScene, camera, width, height);
+		ssao.kernelRadius = 16;
+		ssao.enabled = render.ssao;
+		c.addPass(ssao);
+		const bloom = new UnrealBloomPass(new Vector2(width, height), render.bloom, BLOOM.radius, BLOOM.threshold);
+		bloom.enabled = render.bloom > 0;
+		c.addPass(bloom);
+		c.addPass(new OutputPass());
+		composer = c;
+		ssaoPass = ssao;
+		bloomPass = bloom;
+	};
+	const ensureComposer = () => {
+		if (!needsComposer()) return;
+		if (postClasses) {
+			if (!composer) buildComposer();
+			return;
+		}
+		if (composerLoading) return;
+		composerLoading = true;
+		Promise.all([
+			import("three/examples/jsm/postprocessing/EffectComposer.js"),
+			import("three/examples/jsm/postprocessing/RenderPass.js"),
+			import("three/examples/jsm/postprocessing/SSAOPass.js"),
+			import("three/examples/jsm/postprocessing/UnrealBloomPass.js"),
+			import("three/examples/jsm/postprocessing/OutputPass.js")
+		]).then(([{ EffectComposer }, { RenderPass }, { SSAOPass }, { UnrealBloomPass }, { OutputPass }]) => {
+			postClasses = {
+				EffectComposer,
+				RenderPass,
+				SSAOPass,
+				UnrealBloomPass,
+				OutputPass
+			};
+			composerLoading = false;
+			buildComposer();
+		});
+	};
+	const refreshShadows = () => {
+		renderer.shadowMap.enabled = render.shadows;
+		threeScene.traverse((obj) => {
+			const mat = obj.material;
+			if (!mat) return;
+			for (const m of Array.isArray(mat) ? mat : [mat]) m.needsUpdate = true;
+		});
+	};
+	refreshShadows();
+	ensureComposer();
+	const renderStereo = () => {
+		camera.updateWorldMatrix(true, false);
+		stereo.update(camera);
+		renderer.getSize(stereoSize);
+		const w = stereoSize.x;
+		const h = stereoSize.y;
+		if (renderer.autoClear) renderer.clear();
+		renderer.setScissorTest(true);
+		renderer.setScissor(0, 0, w / 2, h);
+		renderer.setViewport(0, 0, w / 2, h);
+		renderer.render(threeScene, stereo.cameraL);
+		renderer.setScissor(w / 2, 0, w / 2, h);
+		renderer.setViewport(w / 2, 0, w / 2, h);
+		renderer.render(threeScene, stereo.cameraR);
+		renderer.setScissorTest(false);
+		renderer.setViewport(0, 0, w, h);
+	};
 	const renderFrame = () => {
 		rafId = requestAnimationFrame(renderFrame);
-		controls.update(clock.getDelta());
-		renderer.render(threeScene, camera);
+		const delta = clock.getDelta();
+		const deltaMs = delta * 1e3;
+		for (const system of systems) system.update?.(deltaMs);
+		interaction.update(deltaMs);
+		manager.updateElements(deltaMs);
+		for (const controller of controllers) controller.update?.(deltaMs);
+		for (const handler of frameHandlers) handler(deltaMs);
+		manager.beforeRender(renderer, threeScene, camera);
+		if (render.cardboard) renderStereo();
+		else if (composer && needsComposer()) composer.render(delta);
+		else renderer.render(threeScene, camera);
 	};
 	return {
 		ctx: {
 			entity: (id) => manager.get(id),
+			lights: lightsApi,
+			media: mediaApi,
+			controls: {
+				setMoveInput: (forward, strafe) => input.setMove(forward, strafe),
+				setLookInput: (x, y) => input.setLook(x, y)
+			},
+			environment: { setBackgroundIntensity: (v) => environment.setBackgroundIntensity(v) },
+			sky: skyApi,
+			camera: cameraApi,
+			video: videoApi,
 			three: {
 				scene: threeScene,
 				camera,
@@ -351,7 +717,14 @@ function createGallery(scene, options) {
 		},
 		setScene(next) {
 			manager.reconcile(next);
-			if (next.camera.bounds !== void 0) controls.bounds = next.camera.bounds;
+			interaction.setRadii(radiiOf(next));
+			environment.reconcile(next.environment);
+			for (const system of systems) system.setScene?.(next);
+			const fov = next.camera.fov ?? 55;
+			if (camera.fov !== fov) {
+				camera.fov = fov;
+				camera.updateProjectionMatrix();
+			}
 		},
 		start() {
 			if (rafId === null) {
@@ -367,10 +740,15 @@ function createGallery(scene, options) {
 		},
 		dispose() {
 			this.stop();
-			controls.detach();
+			for (const system of systems) system.dispose?.();
+			for (const controller of controllers) controller.dispose?.();
+			interaction.detach();
+			environment.dispose();
 			manager.dispose();
+			composer?.dispose();
 			renderer.dispose();
 			listeners.clear();
+			frameHandlers.clear();
 		},
 		on(event, handler) {
 			const set = listeners.get(event) ?? /* @__PURE__ */ new Set();
@@ -379,16 +757,92 @@ function createGallery(scene, options) {
 			return () => set.delete(handler);
 		},
 		emit(event, payload) {
-			listeners.get(event)?.forEach((handler) => handler(payload));
+			emit(event, payload);
+		},
+		onFrame(handler) {
+			frameHandlers.add(handler);
+			return () => frameHandlers.delete(handler);
 		},
 		resize(w, h) {
 			camera.aspect = w / h;
 			camera.updateProjectionMatrix();
 			renderer.setSize(w, h, false);
+			composer?.setSize(w, h);
+			ssaoPass?.setSize(w, h);
+			bloomPass?.setSize(w, h);
+		},
+		setRender(next) {
+			if (next.shadows !== void 0 && next.shadows !== render.shadows) {
+				render.shadows = next.shadows;
+				refreshShadows();
+			}
+			if (next.ssao !== void 0) render.ssao = next.ssao;
+			if (next.bloom !== void 0) render.bloom = next.bloom;
+			const aaChanged = next.antialias !== void 0 && next.antialias !== render.antialias;
+			if (next.antialias !== void 0) render.antialias = next.antialias;
+			if (next.cardboard !== void 0 && next.cardboard !== render.cardboard) {
+				render.cardboard = next.cardboard;
+				headTracking?.setEnabled(next.cardboard);
+			}
+			if (next.eyeSeparation !== void 0) {
+				render.eyeSeparation = next.eyeSeparation;
+				stereo.eyeSep = next.eyeSeparation;
+			}
+			if (ssaoPass) ssaoPass.enabled = render.ssao;
+			if (bloomPass) {
+				bloomPass.strength = render.bloom;
+				bloomPass.enabled = render.bloom > 0;
+			}
+			if (aaChanged && composer) buildComposer();
+			ensureComposer();
 		}
 	};
 }
 //#endregion
-export { FreeRoamControls, SceneManager, buildArtwork, buildWall, createGallery };
+//#region src/builders/texture.ts
+const textureLoader = new TextureLoader();
+/** Configure a loaded texture: tiling + color space (sRGB only for color maps). */
+const configure = (tex, repeat, srgb) => {
+	tex.wrapS = RepeatWrapping;
+	tex.wrapT = RepeatWrapping;
+	tex.repeat.set(repeat[0], repeat[1]);
+	tex.colorSpace = srgb ? SRGBColorSpace : NoColorSpace;
+	tex.needsUpdate = true;
+};
+/**
+* Load one map and assign it to `material[slot]` once ready. `.exr` maps go
+* through EXRLoader, imported on demand so it only ships in the bundle when a
+* scene actually uses an EXR map; everything else uses the image loader.
+*/
+const loadMap = (material, slot, src, repeat, srgb) => {
+	const assign = (tex) => {
+		configure(tex, repeat, srgb);
+		material[slot] = tex;
+		material.needsUpdate = true;
+	};
+	if (src.toLowerCase().endsWith(".exr")) import("three/examples/jsm/loaders/EXRLoader.js").then(({ EXRLoader }) => {
+		new EXRLoader().load(src, assign);
+	});
+	else textureLoader.load(src, assign);
+};
+/**
+* Apply a `SurfaceTexture` to a standard material. Returns whether a second UV
+* set (`uv1`) is needed — three samples `aoMap` from it, so the geometry must
+* provide one.
+*/
+const applyTexture = (material, texture) => {
+	const repeat = texture.repeat ?? [1, 1];
+	loadMap(material, "map", texture.src, repeat, true);
+	if (texture.normal) {
+		loadMap(material, "normalMap", texture.normal, repeat, false);
+		const s = texture.normalScale ?? 1;
+		material.normalScale = new Vector2(s, s);
+	}
+	if (texture.roughness) loadMap(material, "roughnessMap", texture.roughness, repeat, false);
+	if (texture.ao) loadMap(material, "aoMap", texture.ao, repeat, false);
+	return texture.ao !== void 0;
+};
+//#endregion
+export { COLLIDERS, CapabilityRegistry, EDGES, EYE_HEIGHT, InputBus, InteractionController, ROAM_CONTROL, SceneManager, TERRAIN, applyTexture, createGallery, isSystemPlugin };
 
 //# sourceMappingURL=index.mjs.map