@scenography/engine 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,21 +1,546 @@
-import { Object3D, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from "three";
-import { Artwork, Scene as Scene$1, Wall } from "@scenography/core";
+import { MeshStandardMaterial, Object3D, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from "three";
+import { DataPlugin, Scene as Scene$1, SurfaceTexture, Vec2 } from "@scenography/scene";
 
+//#region src/camera/api.d.ts
+/** Options for framing an artwork on screen. */
+interface FocusOptions {
+  /** Horizontal screen position of the piece's center, `0`=left … `1`=right. Default `0.5`. */
+  centerX?: number;
+  /** Fraction of the viewport width available for the piece (e.g. `0.6`). Default `1`. */
+  widthFraction?: number;
+  /** Tween duration in ms. Default `900`. */
+  duration?: number;
+  /**
+   * Minimum camera distance from the piece, in world units. When the framing that
+   * fits the piece would sit closer, the camera pulls back to this instead (the
+   * piece stays centered, just smaller). Default `0` (no minimum). Useful on close
+   * so a small piece doesn't leave the visitor glued to the wall.
+   */
+  minDistance?: number;
+}
+/**
+ * Public camera-framing API exposed on the gallery context as `ctx.camera`.
+ * Implemented by a framing system plugin (`@scenography/plugin-focus`); when no
+ * such plugin is registered the kernel provides a no-op so callers are safe.
+ */
+interface CameraApi {
+  /** Animate to frame an artwork (by `id`), e.g. offset into the free area beside a panel. */
+  focusArtwork(id: string, options?: FocusOptions): void;
+  /** Animate to center an artwork full-width (used when an info panel closes). */
+  centerArtwork(id: string, options?: FocusOptions): void;
+  /** Drop any active framing watch and hand control fully back to the user. */
+  release(): void;
+  /**
+   * Animate the camera back to the scene's start position and orientation — a
+   * "home" for visitors who lose their way and want to return to the entrance.
+   */
+  reset(): void;
+  /** Whether a framing tween is in progress (e.g. to suppress click-to-select). */
+  isAnimating(): boolean;
+}
+//#endregion
+//#region src/api/index.d.ts
+/**
+ * The public `ctx` API contracts implemented by plugins and surfaced on the
+ * gallery context. The interfaces live in the kernel (they are the supported
+ * surface); the implementations live in the plugins that own each concern.
+ */
+interface LightSetOptions {
+  /** Fade duration in ms. `0`/omitted applies instantly. */
+  duration?: number;
+}
+interface LightSet {
+  intensity?: number;
+  /** CSS-style color. Applied instantly (not tweened). */
+  color?: string;
+}
+/** `ctx.lights` — high-level control over scene lights by id. */
+interface LightsApi {
+  /** Set intensity (tweened) and/or color (instant) on a light by `id`. */
+  set(id: string, props: LightSet, opts?: LightSetOptions): void;
+  /** Dim every light toward `factor` of its current intensity (default `0`). */
+  dimAll(opts?: LightSetOptions & {
+    factor?: number;
+  }): void;
+  /** Fade every light back to the intensity captured before the last dim. */
+  restore(opts?: LightSetOptions): void;
+}
+/** `ctx.video` — high-level control over video screens by id. */
+interface VideoApi {
+  /** Start (or resume) playback of the video with this `id`. */
+  play(id: string): void;
+  /** Pause the video with this `id`. */
+  pause(id: string): void;
+  /** Show or hide the screen with this `id`. */
+  setVisible(id: string, visible: boolean): void;
+}
+/** `ctx.media` — high-level control over background audio by id. */
+interface MediaController {
+  /** Start (or resume) a source by `id`. */
+  play(id: string): void;
+  /** Pause a source, keeping its position. */
+  pause(id: string): void;
+  /** Stop a source and rewind it. */
+  stop(id: string): void;
+  /** Set a source's volume `0`..`1`, optionally fading over `duration` ms. */
+  setVolume(id: string, volume: number, opts?: {
+    duration?: number;
+  }): void;
+  /** Whether a source is currently playing. */
+  playing(id: string): boolean;
+  /** Mute or unmute everything at the master output (per-source volumes are kept). */
+  setMuted(muted: boolean): void;
+  /** Whether the master output is muted. */
+  muted(): boolean;
+}
+/** `ctx.sky` — drive the procedural sky's time of day at runtime. */
+interface SkyApi {
+  /** Set the hour of day (`0`..`24`), updating sun, sky, fill and stars live. */
+  setTime(hour: number): void;
+  /** Current hour of day. */
+  getTime(): number;
+  /** Set the sun's compass offset (degrees). */
+  setAzimuth(degrees: number): void;
+  /** Current sun compass offset (degrees). */
+  getAzimuth(): number;
+}
+//#endregion
+//#region src/input/InputBus.d.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.
+ */
+declare class InputBus {
+  /** Forward (`+1`) / backward (`-1`). */
+  moveForward: number;
+  /** Strafe right (`+1`) / left (`-1`). */
+  moveStrafe: number;
+  /** Look right (`+1`) / left (`-1`). */
+  lookX: number;
+  /** Look up (`+1`) / down (`-1`). */
+  lookY: number;
+  /** Set the movement intent (forward, strafe). */
+  setMove(forward: number, strafe?: number): void;
+  /** Set the look intent (turn, pitch). */
+  setLook(x: number, y?: number): void;
+}
+//#endregion
+//#region src/input/controlSettings.d.ts
+/**
+ * The visitor's camera-control preferences: a set of orthogonal capability flags
+ * plus a derived, friendly "mode". Pure state — no three.js, no DOM. The engine
+ * wires the flags to effects (gyroscope head-look, stereo split); consumers read
+ * them (the analog look-invert axes); the overlay drives it from a mode picker
+ * (the `ScanEye` button) and the settings panel. Persistence and device
+ * feature-detection live in those callers, not here, so this stays trivially
+ * unit-testable.
+ */
+/**
+ * Orthogonal control capabilities. `gyro` / `splitScreen` / `joysticks` are what a
+ * mode fixes; the two `invertLook*` axes are independent look-feel preferences
+ * (some people feel the right stick inverted), kept separate from the mode.
+ */
+interface ControlFlags {
+  /** Orient the camera from the device gyroscope (head-look). */
+  gyro: boolean;
+  /** Split the view into a stereo left/right eye pair (phone-in-a-headset). */
+  splitScreen: boolean;
+  /** Show the on-screen virtual joysticks. */
+  joysticks: boolean;
+  /** Invert the horizontal (turn) axis of analog look. */
+  invertLookX: boolean;
+  /** Invert the vertical (pitch) axis of analog look. */
+  invertLookY: boolean;
+}
+/** A named preset over the mode-defining flags; `custom` when none matches. */
+type ControlMode = "touch" | "vr" | "cardboard" | "custom";
+/** The three flags a mode fixes (the look-invert axes stay a separate preference). */
+type ModeFlags = Pick<ControlFlags, "gyro" | "splitScreen" | "joysticks">;
+/**
+ * Mode presets. Touch = two joysticks, no gyro. VR = the gyro aims and a single
+ * move joystick walks you, no split. Cardboard = gyro aims, stereo split, gaze
+ * select (no joysticks). The move-only single stick in VR is derived downstream
+ * from `gyro && !splitScreen`, so it needs no flag of its own.
+ */
+declare const MODE_PRESETS: Record<Exclude<ControlMode, "custom">, ModeFlags>;
+/** Default flags: plain touch, no look inversion. */
+declare const DEFAULT_CONTROL_FLAGS: ControlFlags;
+/** The mode a flag set represents, or `custom` when no preset matches. */
+declare function modeOf(flags: ControlFlags): ControlMode;
+/** Apply a mode's preset onto `flags`, leaving the look-invert axes untouched. */
+declare function applyMode(flags: ControlFlags, mode: Exclude<ControlMode, "custom">): ControlFlags;
+/**
+ * Live control-preferences state: holds the flags, derives the mode, and notifies
+ * subscribers on every real change. Callers apply the effects — the engine wires
+ * gyro and split, the overlay redraws — so this object is just the shared source
+ * of truth they all read and write.
+ */
+declare class ControlSettings {
+  private flags;
+  private readonly subscribers;
+  constructor(initial?: Partial<ControlFlags>);
+  /** The current flags (a copy — mutate through `setMode` / `setFlag`). */
+  get(): ControlFlags;
+  /** The mode the current flags represent (`custom` when hand-tuned). */
+  getMode(): ControlMode;
+  /** Switch to a mode's preset (keeps the look-invert axes). No-op if unchanged. */
+  setMode(mode: Exclude<ControlMode, "custom">): void;
+  /** Set one flag. Flipping a mode-defining flag can drop you into `custom`. */
+  setFlag<K extends keyof ControlFlags>(key: K, value: ControlFlags[K]): void;
+  /** Subscribe to changes; returns an unsubscribe. Fires on every real change. */
+  subscribe(fn: (flags: ControlFlags) => void): () => void;
+  private replace;
+}
+//#endregion
+//#region src/plugin/CapabilityRegistry.d.ts
+/**
+ * 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.
+ */
+declare class CapabilityRegistry {
+  private readonly values;
+  private readonly versions;
+  /** Last change-token seen per name, to suppress redundant version bumps. */
+  private readonly tokens;
+  /**
+   * 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<T>(name: string, value: T, token?: string): void;
+  /** Remove the capability; consumers see `undefined` and a version bump. */
+  revoke(name: string): void;
+  get<T>(name: string): T | undefined;
+  /** Monotonic change counter for `name` (`0` if never provided). */
+  version(name: string): number;
+  private bump;
+}
+//#endregion
+//#region src/plugin/enginePlugin.d.ts
+/** What a plugin materializes for one element: an object plus lifecycle hooks. */
+interface BuiltElement {
+  /** Mounted into (and removed from) the three.js scene by the kernel. */
+  object?: Object3D;
+  /** Advance time-based behavior; called once per frame with the delta in ms. */
+  update?: (deltaMs: number) => void;
+  /**
+   * Render an auxiliary pass before the main frame — e.g. a planar reflection
+   * or a portal view rendered into a texture the element's material samples.
+   * Called once per frame with the live renderer, scene and camera.
+   */
+  beforeRender?: (renderer: WebGLRenderer, scene: Scene, camera: PerspectiveCamera) => void;
+  /** Extra cleanup beyond the object's geometries/materials (which the kernel disposes). */
+  dispose?: () => void;
+}
+/** What the kernel hands a plugin while building. */
+interface EngineContext {
+  capabilities: CapabilityRegistry;
+}
+/**
+ * An aggregate controller over all of an element plugin's live objects, exposing
+ * a public api (mapped onto `ctx` by the plugin's kind — e.g. the light plugin's
+ * `lights` api becomes `ctx.lights`). It reads the elements fresh each call, so
+ * it keeps working across hot-swaps.
+ */
+interface ElementController<Api = unknown> {
+  /** The api surfaced on `ctx`. */
+  api?: Api;
+  /** Advance time-based control (e.g. light-intensity tweens). */
+  update?(deltaMs: number): void;
+  /** Tear down. */
+  dispose?(): void;
+}
+/**
+ * The runtime half of a plugin: embeds its data half (the scene key, its
+ * validation) and adds how each element materializes into three.js objects.
+ * The kernel reconciles by content: an element rebuilds when its definition
+ * changes, or when any capability named in `dependsOn` is re-provided.
+ */
+interface EnginePlugin<T = unknown> {
+  data: DataPlugin<T>;
+  /** Capability names whose changes force a rebuild of this plugin's elements. */
+  dependsOn?: readonly string[];
+  /** Method syntax on purpose: keeps `EnginePlugin<Water>` assignable to `EnginePlugin[]`. */
+  build(value: T, ctx: EngineContext): BuiltElement;
+  /**
+   * Publish capabilities derived from *all* of this plugin's elements, once
+   * they have reconciled — the aggregate a single `build` can't see (e.g. the
+   * wall plugin indexing every edge into the `edges` capability). Pass a change
+   * token to `ctx.capabilities.provide` so consumers don't rebuild needlessly.
+   */
+  provide?(values: T[], ctx: EngineContext): void;
+  /**
+   * Build an aggregate controller over this plugin's live elements (e.g. the
+   * light plugin's `ctx.lights`). `elements` returns the current objects by id,
+   * queried fresh so it survives hot-swaps.
+   */
+  controller?(elements: () => ReadonlyMap<string, Object3D>): ElementController;
+}
+//#endregion
+//#region src/plugin/systemPlugin.d.ts
+/**
+ * What the kernel hands a system on setup. A *system* plugin — unlike an element
+ * plugin — produces no scene object; it drives shared runtime state (the camera,
+ * input…) each frame. The camera is a kernel primitive (the renderer needs one),
+ * so systems receive it and drive it, publishing/consuming capabilities to
+ * cooperate (e.g. the camera plugin publishes `roamControl`).
+ */
+interface SystemContext {
+  /** The current scene (its data keys, start pose, boundary…); also `setScene` on hot-swap. */
+  scene: Scene$1;
+  /** The render camera the system may drive. */
+  camera: PerspectiveCamera;
+  /** The canvas, for pointer/keyboard listeners. */
+  canvas: HTMLElement;
+  /** The three.js scene graph, for systems that manage their own objects (sky…). */
+  scene3d: Scene;
+  /** The renderer, for systems that need it (e.g. sky IBL generation). */
+  renderer: WebGLRenderer;
+  /** Shared analog input (joysticks feed it); systems interpret it. */
+  input: InputBus;
+  /** The visitor's current control flags (e.g. look-invert axes), read live. */
+  controlFlags: () => ControlFlags;
+  /** Capability registry for cross-plugin contracts (terrain, colliders…). */
+  capabilities: CapabilityRegistry;
+  /** Emit a gallery event. */
+  emit: (event: string, payload?: unknown) => void;
+  /** Resolve a live scene object by id (e.g. for a framing system). */
+  resolve: (id: string) => Object3D | undefined;
+}
+/** A running system: its per-frame update, hot-swap and teardown hooks. */
+interface SystemInstance<Api = unknown> {
+  /** Advance the system by the frame delta (ms). */
+  update?(deltaMs: number): void;
+  /** React to a hot-swapped scene definition. */
+  setScene?(scene: Scene$1): void;
+  /** Tear down (detach listeners, revoke capabilities). */
+  dispose?(): void;
+  /**
+   * Public API the system exposes to userland/overlay. The kernel maps known
+   * system names onto `ctx` (e.g. a `focus` system's api → `ctx.camera`).
+   */
+  api?: Api;
+}
+/**
+ * A system plugin: sets up once against the kernel handles and returns its
+ * running instance. Registered alongside element plugins in `plugins`; the
+ * kernel tells them apart by shape (`setup` vs `build`).
+ */
+interface SystemPlugin<Api = unknown> {
+  name: string;
+  setup(ctx: SystemContext): SystemInstance<Api>;
+}
+/** Narrow a mixed plugin to a system plugin (has `setup`, not `build`). */
+declare const isSystemPlugin: (plugin: unknown) => plugin is SystemPlugin;
+//#endregion
+//#region src/plugin/roamControl.d.ts
+/** Capability name under which a roaming camera system exposes pose control. */
+declare const ROAM_CONTROL = "roamControl";
+/**
+ * Handle a camera plugin publishes so other camera systems can cooperate with
+ * it — chiefly a framing/tour system that suspends free-roam while it animates
+ * the camera, then reads/writes the pose to hand control back cleanly.
+ */
+interface RoamControl {
+  /** Enable/disable free-roam input (disabled while another system owns the camera). */
+  setEnabled(enabled: boolean): void;
+  /** Current pose: world position plus yaw (`phi`) and pitch (`theta`) in radians. */
+  getPose(): {
+    position: Vector3;
+    phi: number;
+    theta: number;
+  };
+  /** Force the pose so free-roam resumes from it. */
+  setPose(position: Vector3, phi: number, theta: number): void;
+  /** Current eye height above the ground (world units). */
+  getEyeHeight(): number;
+}
+//#endregion
+//#region src/plugin/terrain.d.ts
+/** Capability name under which the floor publishes its terrain. */
+declare const TERRAIN = "terrain";
+/**
+ * The geometry a terrain consumer relies on — the fields needed to sample the
+ * same ground a floor was displaced by (e.g. the water shader). A floor
+ * definition satisfies this structurally; the kernel stays floor-agnostic.
+ */
+interface TerrainDefinition {
+  /** Extent on the ground plane, `[width (x), depth (z)]`. */
+  size: Vec2;
+  /** Center on the ground plane `[x, z]`. Defaults to `[0, 0]`. */
+  center?: Vec2;
+  /** Base vertical position (world Y). Defaults to `0`. */
+  y?: number;
+  /** Grayscale heightmap URL that displaces the ground. */
+  heightmap?: string;
+  /** Max displacement (world units) at white in the heightmap. */
+  heightScale?: number;
+}
+/**
+ * The walkable ground, published by the floor: its definition (for shaders that
+ * sample the same heightmap), the live height function (heightmap-aware once the
+ * image loads) and a promise that resolves once that sampling is in effect.
+ */
+interface TerrainCapability {
+  definition: TerrainDefinition;
+  heightAt: (x: number, z: number) => number;
+  /** Resolves once `heightAt` reflects the heightmap (immediately when there is none). */
+  ready: Promise<void>;
+}
+//#endregion
+//#region src/plugin/colliders.d.ts
+/** Capability name under which walkable-space obstacles are published. */
+declare const COLLIDERS = "colliders";
+/**
+ * A collision obstacle as an oriented box on the XZ plane. The camera controls
+ * consume these to keep the visitor out of walls (and any other plugin that
+ * wants to block movement can provide more of them). Purely a movement contract
+ * — no geometry, no three.js.
+ */
+interface Collider {
+  /** Box center `[x, z]`. */
+  cx: number;
+  cz: number;
+  /** Unit direction along the box's length. */
+  dx: number;
+  dz: number;
+  /** Half the box length. */
+  halfLength: number;
+  /** Half the box thickness. */
+  halfThickness: number;
+}
+//#endregion
+//#region src/plugin/edges.d.ts
+/** Capability name under which named wall edges are published for hanging. */
+declare const EDGES = "edges";
+/** A named anchor an artwork can hang on: a wall segment resolved to geometry. */
+interface EdgeAnchor {
+  a: Vec2;
+  b: Vec2;
+  height: number;
+  thickness: number;
+}
+/** The `name -> anchor` index a provider (e.g. the wall plugin) publishes. */
+type EdgeIndex = ReadonlyMap<string, EdgeAnchor>;
+//#endregion
+//#region src/plugin/eyeHeight.d.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.
+ */
+declare const EYE_HEIGHT = "eyeHeight";
+//#endregion
 //#region src/createGallery.d.ts
-interface GalleryOptions {
+/** MSAA sample count for antialiasing. `0` disables it. */
+type Antialias = 0 | 2 | 4 | 8;
+/** Toggleable rendering features. All can be flipped live via `setRender`. */
+interface RenderOptions {
+  /**
+   * Antialiasing as MSAA sample count (`0` off, `2`/`4`/`8`). Applied to the
+   * post-process render target so it survives SSAO/bloom and toggles live,
+   * unlike the canvas's native MSAA. Defaults to `4`.
+   */
+  antialias?: Antialias;
+  /** Screen-space ambient occlusion as a post-process. Defaults to `false`. */
+  ssao?: boolean;
+  /**
+   * Bloom strength: a soft glow bleeding out of the brightest areas. `0` off;
+   * gentle around `0.3`, strong around `1`. Defaults to `0`.
+   */
+  bloom?: number;
+  /** Real-time shadow mapping (PCF). Defaults to `true`. */
+  shadows?: boolean;
+  /**
+   * Cardboard / stereoscopic mode: split the view into a left/right eye pair for
+   * a phone-in-a-headset viewer. Skips post-processing while active. Defaults to
+   * `false`.
+   */
+  cardboard?: boolean;
+  /**
+   * Interocular distance for cardboard mode, in world units. The physical ≈6.4 cm
+   * is too much parallax to fuse comfortably through cardboard lenses, so this
+   * defaults to `3`; tune it live for the viewer. `0` flattens to mono.
+   */
+  eyeSeparation?: number;
+}
+interface GalleryOptions extends RenderOptions {
   /** Canvas the gallery renders into. */
   canvas: HTMLCanvasElement;
   /** Background color. Defaults to a soft gray. */
   background?: string;
-  antialias?: boolean;
+  /**
+   * Runtime plugins: element plugins materialize a scene key; system plugins
+   * (e.g. a camera) drive shared runtime state. Mixed freely — the kernel tells
+   * them apart by shape.
+   */
+  plugins?: (EnginePlugin | SystemPlugin)[];
+}
+/**
+ * Drive the free-roam camera from outside the engine — e.g. on-screen touch
+ * controls in the overlay. Inputs are analog (`-1..1`) and held until changed.
+ */
+interface ControlsApi {
+  /** Walk forward (`+1`) / back (`-1`); optional strafe right (`+1`) / left (`-1`). */
+  setMoveInput(forward: number, strafe?: number): void;
+  /** Turn right (`+1`) / left (`-1`); optional look up (`+1`) / down (`-1`). */
+  setLookInput(x: number, y?: number): void;
+}
+/**
+ * The visitor's camera-control preferences (view mode + capability flags). The
+ * engine applies the effects that touch rendering/input — gyroscope head-look and
+ * the stereo split — as the flags change; the overlay drives it from the mode
+ * picker and settings, and reads it to show the right joysticks. See
+ * `ControlSettings`.
+ */
+interface ViewControlsApi {
+  /** Current capability flags (a copy). */
+  get(): ControlFlags;
+  /** The mode the flags represent (`custom` when hand-tuned in settings). */
+  getMode(): ControlMode;
+  /** Switch to a mode's preset (keeps the look-invert axes). */
+  setMode(mode: Exclude<ControlMode, "custom">): void;
+  /** Set one capability flag (may drop the mode into `custom`). */
+  setFlag<K extends keyof ControlFlags>(key: K, value: ControlFlags[K]): void;
+  /** Subscribe to changes; returns an unsubscribe. */
+  subscribe(fn: (flags: ControlFlags) => void): () => void;
+}
+/** Control the HDRI sky / environment at runtime, for behavior code. */
+interface EnvironmentApi {
+  /** Set the visible sky background brightness (`0` = black). */
+  setBackgroundIntensity(value: number): void;
 }
 /**
  * High-level API handed to behavior code. Deliberately NOT raw three.js: this is
  * the supported surface. Reach into `three` only as a documented escape hatch.
  */
 interface GalleryContext {
-  /** Resolve the live object for a wall/artwork `id`. */
+  /** Resolve the live object for a wall/artwork/light `id`. */
   entity(id: string): Object3D | undefined;
+  /** Control scene lights (dim, set intensity/color) by `id`. */
+  readonly lights: LightsApi;
+  /** Control background audio (play, pause, fade) by `id`. */
+  readonly media: MediaController;
+  /** Drive the camera externally (on-screen touch controls, etc.). */
+  readonly controls: ControlsApi;
+  /** The visitor's camera-control preferences (view mode + capability flags). */
+  readonly viewControls: ViewControlsApi;
+  /** Control the HDRI sky / environment at runtime. */
+  readonly environment: EnvironmentApi;
+  /** Drive the procedural sky's time of day. */
+  readonly sky: SkyApi;
+  /** Animate the camera to frame artworks (e.g. when an info panel opens/closes). */
+  readonly camera: CameraApi;
+  /** Control video screens (play, pause, show/hide) by `id`. */
+  readonly video: VideoApi;
   /** Escape hatch to the underlying three.js objects for advanced use. */
   readonly three: {
     scene: Scene;
@@ -36,8 +561,12 @@ interface Gallery {
   on(event: string, handler: (payload?: unknown) => void): () => void;
   /** Emit a named event to subscribers. */
   emit(event: string, payload?: unknown): void;
+  /** Run a handler every frame with the frame delta in ms; returns unsubscribe. */
+  onFrame(handler: (deltaMs: number) => void): () => void;
   /** Resize the renderer/camera to the given pixel size. */
   resize(width: number, height: number): void;
+  /** Toggle rendering features (antialias, ssao, bloom, shadows) live. */
+  setRender(options: RenderOptions): void;
   readonly ctx: GalleryContext;
 }
 /**
@@ -57,64 +586,80 @@ declare function createGallery(scene: Scene$1, options: GalleryOptions): Gallery
  */
 declare class SceneManager {
   private readonly root;
-  private readonly walls;
-  private readonly artworks;
-  constructor(root: Scene);
+  private readonly plugins;
+  private readonly capabilities;
+  /** Mounted plugin elements, per kind, keyed by element id ("" for singletons). */
+  private readonly pluginElements;
+  constructor(root: Scene, plugins?: EnginePlugin[], capabilities?: CapabilityRegistry);
   reconcile(scene: Scene$1): void;
-  private reconcileWalls;
-  private reconcileArtworks;
-  /** Look up the live three.js object for a wall or artwork `id`. */
+  /**
+   * 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).
+   */
+  private reconcilePlugins;
+  private removePluginElement;
+  /** Advance time-based plugin elements (e.g. water ripple). Call once per frame. */
+  updateElements(deltaMs: number): void;
+  /** Run every element's auxiliary pre-render pass (e.g. water reflection). */
+  beforeRender(renderer: WebGLRenderer, scene: Scene, camera: PerspectiveCamera): void;
+  /** Look up the live three.js object for any plugin element `id`. */
   get(id: string): Object3D | undefined;
+  /** Live objects of one plugin kind, keyed by `id` — for that plugin's controller. */
+  elementsOf(kind: string): ReadonlyMap<string, Object3D>;
   dispose(): void;
 }
 //#endregion
-//#region src/controls/FreeRoamControls.d.ts
-interface FreeRoamOptions {
-  /** Square half-extent that clamps XZ movement. */
-  bounds?: number;
-  /** Starting position. */
-  position?: Vector3;
-  /** Starting yaw in radians. */
-  yaw?: number;
-}
+//#region src/builders/texture.d.ts
+/**
+ * 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.
+ */
+declare const applyTexture: (material: MeshStandardMaterial, texture: SurfaceTexture) => boolean;
+//#endregion
+//#region src/interaction/InteractionController.d.ts
 /**
- * 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.
  */
-declare class FreeRoamControls {
-  bounds: number;
+declare class InteractionController {
   private readonly camera;
-  private readonly domElement;
-  private readonly mouse;
-  private readonly keyboard;
-  private readonly headBob;
-  private readonly look;
-  private rotation;
-  private translation;
+  private readonly canvas;
+  private readonly scene;
+  private readonly emit;
+  private readonly canInteract;
+  private readonly raycaster;
+  private readonly pointer;
+  private over;
+  private downPos;
+  private radii;
+  private hovered;
+  private time;
+  private readonly highlight;
+  private highlightMat;
   private readonly handlers;
-  constructor(camera: PerspectiveCamera, domElement: HTMLElement, options?: FreeRoamOptions);
+  constructor(camera: PerspectiveCamera, canvas: HTMLCanvasElement, scene: Scene, emit: (event: string, payload?: unknown) => void, canInteract: () => boolean);
+  /** Per-artwork max interaction distance (XZ). Absent id = no distance gate. */
+  setRadii(radii: Map<string, number>): void;
   attach(): void;
   detach(): void;
-  /** Advance the camera by `delta` seconds of input. */
-  update(delta: number): void;
+  private setPointer;
+  private onMove;
+  private onDown;
+  private onUp;
+  /** Resolve the nearest pickable artwork under the pointer, honoring the gate. */
+  private raycast;
+  /** Recompute hover state and animate the highlight. Call once per frame. */
+  update(deltaMs: number): void;
+  private clearHighlight;
+  /** Position a fresh pulsing red frame over the picked target's front face. */
+  private buildHighlight;
 }
 //#endregion
-//#region src/builders/wall.d.ts
-/** Build the three.js object that materializes a `Wall` definition. */
-declare function buildWall(wall: Wall): Object3D;
-//#endregion
-//#region src/builders/artwork.d.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.
- */
-declare function buildArtwork(artwork: Artwork, wall: Wall): Object3D;
-//#endregion
-export { FreeRoamControls, type FreeRoamOptions, type Gallery, type GalleryContext, type GalleryOptions, SceneManager, buildArtwork, buildWall, createGallery };
+export { type Antialias, type BuiltElement, COLLIDERS, type CameraApi, CapabilityRegistry, type Collider, type ControlFlags, type ControlMode, ControlSettings, type ControlsApi, DEFAULT_CONTROL_FLAGS, EDGES, EYE_HEIGHT, type EdgeAnchor, type EdgeIndex, type ElementController, type EngineContext, type EnginePlugin, type EnvironmentApi, type FocusOptions, type Gallery, type GalleryContext, type GalleryOptions, InputBus, InteractionController, type LightSet, type LightSetOptions, type LightsApi, MODE_PRESETS, type MediaController, ROAM_CONTROL, type RenderOptions, type RoamControl, SceneManager, type SkyApi, type SystemContext, type SystemInstance, type SystemPlugin, TERRAIN, type TerrainCapability, type TerrainDefinition, type VideoApi, applyMode, applyTexture, createGallery, isSystemPlugin, modeOf };
 //# sourceMappingURL=index.d.cts.map