@scenography/engine 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -10,6 +10,13 @@ interface FocusOptions {
   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`.
@@ -23,6 +30,11 @@ interface CameraApi {
   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;
 }
@@ -93,6 +105,97 @@ interface SkyApi {
   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
@@ -182,30 +285,6 @@ interface EnginePlugin<T = unknown> {
   controller?(elements: () => ReadonlyMap<string, Object3D>): ElementController;
 }
 //#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/plugin/systemPlugin.d.ts
 /**
  * What the kernel hands a system on setup. A *system* plugin — unlike an element
@@ -227,6 +306,8 @@ interface SystemContext {
   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. */
@@ -413,6 +494,25 @@ interface ControlsApi {
   /** 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). */
@@ -431,6 +531,8 @@ interface GalleryContext {
   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. */
@@ -559,5 +661,5 @@ declare class InteractionController {
   private buildHighlight;
 }
 //#endregion
-export { type Antialias, type BuiltElement, COLLIDERS, type CameraApi, CapabilityRegistry, type Collider, type ControlsApi, 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, type MediaController, ROAM_CONTROL, type RenderOptions, type RoamControl, SceneManager, type SkyApi, type SystemContext, type SystemInstance, type SystemPlugin, TERRAIN, type TerrainCapability, type TerrainDefinition, type VideoApi, applyTexture, createGallery, isSystemPlugin };
+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

package/dist/index.d.mts

@@ -10,6 +10,13 @@ interface FocusOptions {
   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`.
@@ -23,6 +30,11 @@ interface CameraApi {
   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;
 }
@@ -93,6 +105,97 @@ interface SkyApi {
   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
@@ -182,30 +285,6 @@ interface EnginePlugin<T = unknown> {
   controller?(elements: () => ReadonlyMap<string, Object3D>): ElementController;
 }
 //#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/plugin/systemPlugin.d.ts
 /**
  * What the kernel hands a system on setup. A *system* plugin — unlike an element
@@ -227,6 +306,8 @@ interface SystemContext {
   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. */
@@ -413,6 +494,25 @@ interface ControlsApi {
   /** 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). */
@@ -431,6 +531,8 @@ interface GalleryContext {
   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. */
@@ -559,5 +661,5 @@ declare class InteractionController {
   private buildHighlight;
 }
 //#endregion
-export { type Antialias, type BuiltElement, COLLIDERS, type CameraApi, CapabilityRegistry, type Collider, type ControlsApi, 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, type MediaController, ROAM_CONTROL, type RenderOptions, type RoamControl, SceneManager, type SkyApi, type SystemContext, type SystemInstance, type SystemPlugin, TERRAIN, type TerrainCapability, type TerrainDefinition, type VideoApi, applyTexture, createGallery, isSystemPlugin };
+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.mts.map

package/dist/index.mjs

@@ -272,6 +272,139 @@ var InputBus = class {
 	}
 };
 //#endregion
+//#region src/input/controlSettings.ts
+/**
+* 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.
+*/
+const MODE_PRESETS = {
+	touch: {
+		gyro: false,
+		splitScreen: false,
+		joysticks: true
+	},
+	vr: {
+		gyro: true,
+		splitScreen: false,
+		joysticks: true
+	},
+	cardboard: {
+		gyro: true,
+		splitScreen: true,
+		joysticks: false
+	}
+};
+/** Default flags: plain touch, no look inversion. */
+const DEFAULT_CONTROL_FLAGS = {
+	...MODE_PRESETS.touch,
+	invertLookX: false,
+	invertLookY: false
+};
+const FLAG_KEYS$1 = [
+	"gyro",
+	"splitScreen",
+	"joysticks",
+	"invertLookX",
+	"invertLookY"
+];
+const equalFlags = (a, b) => FLAG_KEYS$1.every((key) => a[key] === b[key]);
+/** The mode a flag set represents, or `custom` when no preset matches. */
+function modeOf(flags) {
+	for (const mode of [
+		"touch",
+		"vr",
+		"cardboard"
+	]) {
+		const preset = MODE_PRESETS[mode];
+		if (flags.gyro === preset.gyro && flags.splitScreen === preset.splitScreen && flags.joysticks === preset.joysticks) return mode;
+	}
+	return "custom";
+}
+/** Apply a mode's preset onto `flags`, leaving the look-invert axes untouched. */
+function applyMode(flags, mode) {
+	return {
+		...flags,
+		...MODE_PRESETS[mode]
+	};
+}
+/**
+* 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.
+*/
+var ControlSettings = class {
+	flags;
+	subscribers = /* @__PURE__ */ new Set();
+	constructor(initial = {}) {
+		this.flags = {
+			...DEFAULT_CONTROL_FLAGS,
+			...initial
+		};
+	}
+	/** The current flags (a copy — mutate through `setMode` / `setFlag`). */
+	get() {
+		return { ...this.flags };
+	}
+	/** The mode the current flags represent (`custom` when hand-tuned). */
+	getMode() {
+		return modeOf(this.flags);
+	}
+	/** Switch to a mode's preset (keeps the look-invert axes). No-op if unchanged. */
+	setMode(mode) {
+		this.replace(applyMode(this.flags, mode));
+	}
+	/** Set one flag. Flipping a mode-defining flag can drop you into `custom`. */
+	setFlag(key, value) {
+		this.replace({
+			...this.flags,
+			[key]: value
+		});
+	}
+	/** Subscribe to changes; returns an unsubscribe. Fires on every real change. */
+	subscribe(fn) {
+		this.subscribers.add(fn);
+		return () => this.subscribers.delete(fn);
+	}
+	replace(next) {
+		if (equalFlags(this.flags, next)) return;
+		this.flags = next;
+		const snapshot = this.get();
+		for (const fn of this.subscribers) fn(snapshot);
+	}
+};
+//#endregion
+//#region src/input/controlStorage.ts
+/**
+* localStorage persistence for the control flags, kept out of the pure
+* `ControlSettings` so that stays DOM-free and unit-testable. Both functions are
+* best-effort and guarded: no `localStorage` (SSR, privacy mode) or malformed
+* data just falls back to defaults, never throws.
+*/
+const STORAGE_KEY = "scenography:controls";
+const FLAG_KEYS = Object.keys(DEFAULT_CONTROL_FLAGS);
+/** Read persisted control flags; `null` when absent, unavailable or malformed. */
+function loadControlFlags() {
+	try {
+		const raw = globalThis.localStorage?.getItem(STORAGE_KEY);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		const flags = {};
+		for (const key of FLAG_KEYS) if (typeof parsed[key] === "boolean") flags[key] = parsed[key];
+		return flags;
+	} catch {
+		return null;
+	}
+}
+/** Persist control flags (best-effort; ignores a full/blocked store). */
+function saveControlFlags(flags) {
+	try {
+		globalThis.localStorage?.setItem(STORAGE_KEY, JSON.stringify(flags));
+	} catch {}
+}
+//#endregion
 //#region src/plugin/CapabilityRegistry.ts
 /**
 * Shared runtime contracts between plugins, keyed by name. A plugin (or the
@@ -523,6 +656,7 @@ function createGallery(scene, options) {
 	const manager = new SceneManager(threeScene, elementPlugins, capabilities);
 	manager.reconcile(scene);
 	const input = new InputBus();
+	const controlSettings = new ControlSettings(loadControlFlags() ?? (options.cardboard ? MODE_PRESETS.cardboard : {}));
 	const environment = new EnvironmentController(threeScene);
 	environment.reconcile(scene.environment);
 	const listeners = /* @__PURE__ */ new Map();
@@ -546,6 +680,7 @@ function createGallery(scene, options) {
 			scene3d: threeScene,
 			renderer,
 			input,
+			controlFlags: () => controlSettings.get(),
 			capabilities,
 			emit,
 			resolve: (id) => manager.get(id)
@@ -557,10 +692,24 @@ function createGallery(scene, options) {
 		focusArtwork: () => {},
 		centerArtwork: () => {},
 		release: () => {},
+		reset: () => {},
 		isAnimating: () => false
 	};
 	const headTracking = apis.get(CARDBOARD_SYSTEM);
-	if (options.cardboard) headTracking?.setEnabled(true);
+	const initialFlags = controlSettings.get();
+	render.cardboard = initialFlags.splitScreen;
+	if (initialFlags.gyro) headTracking?.setEnabled(true);
+	let prevFlags = controlSettings.get();
+	controlSettings.subscribe((flags) => {
+		if (flags.gyro !== prevFlags.gyro) headTracking?.setEnabled(flags.gyro);
+		if (flags.splitScreen !== prevFlags.splitScreen) render.cardboard = flags.splitScreen;
+		prevFlags = flags;
+		saveControlFlags(flags);
+		emit("controls:change", {
+			flags,
+			mode: controlSettings.getMode()
+		});
+	});
 	const lightsApi = apis.get(CTX_SLOT.lights) ?? {
 		set: () => {},
 		dimAll: () => {},
@@ -705,6 +854,13 @@ function createGallery(scene, options) {
 				setMoveInput: (forward, strafe) => input.setMove(forward, strafe),
 				setLookInput: (x, y) => input.setLook(x, y)
 			},
+			viewControls: {
+				get: () => controlSettings.get(),
+				getMode: () => controlSettings.getMode(),
+				setMode: (mode) => controlSettings.setMode(mode),
+				setFlag: (key, value) => controlSettings.setFlag(key, value),
+				subscribe: (fn) => controlSettings.subscribe(fn)
+			},
 			environment: { setBackgroundIntensity: (v) => environment.setBackgroundIntensity(v) },
 			sky: skyApi,
 			camera: cameraApi,
@@ -780,10 +936,7 @@ function createGallery(scene, options) {
 			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.cardboard !== void 0 && next.cardboard !== render.cardboard) controlSettings.setMode(next.cardboard ? "cardboard" : "touch");
 			if (next.eyeSeparation !== void 0) {
 				render.eyeSeparation = next.eyeSeparation;
 				stereo.eyeSep = next.eyeSeparation;
@@ -843,6 +996,6 @@ const applyTexture = (material, texture) => {
 	return texture.ao !== void 0;
 };
 //#endregion
-export { COLLIDERS, CapabilityRegistry, EDGES, EYE_HEIGHT, InputBus, InteractionController, ROAM_CONTROL, SceneManager, TERRAIN, applyTexture, createGallery, isSystemPlugin };
+export { COLLIDERS, CapabilityRegistry, ControlSettings, DEFAULT_CONTROL_FLAGS, EDGES, EYE_HEIGHT, InputBus, InteractionController, MODE_PRESETS, ROAM_CONTROL, SceneManager, TERRAIN, applyMode, applyTexture, createGallery, isSystemPlugin, modeOf };
 
 //# sourceMappingURL=index.mjs.map