@scenography/overlay-presets 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { Overlay, OverlayComponent, OverlayContext, Text } from "@scenography/overlay";
2
+ import { ControlFlags, ControlMode } from "@scenography/engine";
2
3
  import { Artwork } from "@scenography/plugin-artwork/data";
3
4
 
4
5
  //#region src/util.d.ts
@@ -72,12 +73,87 @@ interface CardboardButtonOptions {
72
73
  */
73
74
  declare function cardboardButton(options?: CardboardButtonOptions): OverlayComponent;
74
75
  //#endregion
76
+ //#region src/components/reset-view/reset-view.d.ts
77
+ interface ResetViewButtonOptions {
78
+ /** Button icon. Defaults to a plain glyph ⌂; pass `lucideIcon("House")`. */
79
+ icon?: IconContent;
80
+ /** Aria-label (relocalized live). Defaults to "Reset view". */
81
+ label?: Text;
82
+ /** Override the daisyUI/utility classes on the button. */
83
+ className?: string;
84
+ }
85
+ /**
86
+ * A "home" button that returns the camera to the scene's start position and
87
+ * orientation (`ctx.camera.reset()`) — for visitors who wander off and want to
88
+ * get back to the entrance. Defaults to a plain glyph; pass `lucideIcon("House")`.
89
+ */
90
+ declare function resetViewButton(options?: ResetViewButtonOptions): OverlayComponent;
91
+ //#endregion
92
+ //#region src/components/view-mode/capabilities.d.ts
93
+ /** The camera-control modes a visitor can pick between (excludes `custom`). */
94
+ type SelectableMode = Exclude<ControlMode, "custom">;
95
+ /** What the current device can do, as far as camera control is concerned. */
96
+ interface ControlCapabilities {
97
+ /** A touch screen (coarse pointer) — needed for the on-screen joysticks. */
98
+ touch: boolean;
99
+ /** A motion sensor for gyroscope head-look (VR / Cardboard). */
100
+ gyro: boolean;
101
+ }
102
+ /**
103
+ * Sniff the device's control capabilities. Deliberately conservative: gyro is
104
+ * gated behind a touch (mobile) device too, since desktops expose the
105
+ * `DeviceOrientationEvent` interface but never fire it — pairing it with a coarse
106
+ * pointer avoids offering VR/Cardboard where they can't work.
107
+ */
108
+ declare function detectControlCapabilities(): ControlCapabilities;
109
+ /**
110
+ * The modes worth offering on this device, in display order. Touch needs a touch
111
+ * screen; VR and Cardboard additionally need the gyro. Desktop (no touch) gets an
112
+ * empty list — it uses keyboard/mouse and shows no mode picker at all.
113
+ */
114
+ declare function availableModes(caps: ControlCapabilities): SelectableMode[];
115
+ //#endregion
116
+ //#region src/components/view-mode/view-mode.d.ts
117
+ /** One selectable mode in the picker. */
118
+ interface ViewModeItem {
119
+ mode: SelectableMode;
120
+ /** Short mode name (e.g. "Touch", "VR", "Cardboard"). */
121
+ label: Text;
122
+ }
123
+ interface ViewModeButtonOptions {
124
+ /** Modal title, also the button's aria-label. */
125
+ title: Text;
126
+ /** Aria-label for the ✕ close button. Defaults to "Close". */
127
+ closeLabel?: Text;
128
+ /**
129
+ * The modes to offer, in order. Usually pre-filtered to what the device
130
+ * supports (see `availableModes`); the caller decides whether to show the
131
+ * button at all (typically only when two or more modes are available).
132
+ */
133
+ modes: ViewModeItem[];
134
+ }
135
+ /**
136
+ * A camera-control mode picker: a `ScanEye` button opening a small modal with one
137
+ * entry per mode (Touch / VR / Cardboard). Picking one calls
138
+ * `ctx.viewControls.setMode` — which, inside this click gesture, flips the
139
+ * gyroscope and stereo split (so iOS grants motion here). The active mode is
140
+ * marked and kept in sync via the `controls:change` event, so the settings panel
141
+ * and this picker never disagree.
142
+ */
143
+ declare function viewModeButton(options: ViewModeButtonOptions): OverlayComponent;
144
+ //#endregion
75
145
  //#region src/components/settings/settings.d.ts
76
146
  /** One option in a single-choice section. */
77
147
  interface SettingsChoice {
78
148
  value: string;
79
149
  label: Text;
80
150
  }
151
+ /** One control-flag toggle in the Controls section (wired to `ctx.viewControls`). */
152
+ interface SettingsControlItem {
153
+ /** Which control flag this toggles (e.g. `gyro`, `invertLookX`). */
154
+ key: keyof ControlFlags;
155
+ label: Text;
156
+ }
81
157
  /** One boolean toggle in the multi-toggle section. */
82
158
  interface SettingsToggleItem {
83
159
  key: string;
@@ -131,6 +207,18 @@ interface SettingsPanelOptions {
131
207
  options: SettingsChoice[];
132
208
  onChange: (value: string) => void;
133
209
  };
210
+ /**
211
+ * The Controls section: toggles for the camera-control flags (gyroscope, split
212
+ * screen, virtual joysticks, invert look X/Y). Unlike the other sections this
213
+ * one is *self-wired* to `ctx.viewControls` — pass which flags to show and their
214
+ * labels; the panel reads/writes the live state and stays in sync with the mode
215
+ * picker. Own tab.
216
+ */
217
+ controls?: {
218
+ tab?: Text;
219
+ label: Text;
220
+ items: SettingsControlItem[];
221
+ };
134
222
  /** A multi-toggle section (e.g. graphics: ssao / bloom / shadows). Own tab. */
135
223
  graphics?: {
136
224
  tab?: Text;
@@ -264,6 +352,55 @@ interface InfoPanelOptions {
264
352
  */
265
353
  declare function infoPanel(options: InfoPanelOptions): OverlayComponent;
266
354
  //#endregion
355
+ //#region src/components/help/diagrams.d.ts
356
+ /**
357
+ * Built-in control-scheme diagrams for the help panel. Standard schemes, so they
358
+ * live in the preset (the app only supplies the localized text). Cardboard is a
359
+ * single diagram; touch, keyboard-mouse and gamepad are split into one figure per
360
+ * control (see `sectionFigures`). Pure pictograms: no words inside the SVG (only
361
+ * universal key legends like WASD), so nothing here needs localizing. Outlines use
362
+ * `currentColor`; the interactive/highlighted parts are wrapped in a `text-primary`
363
+ * group so they pop and stay theme-aware in light and dark.
364
+ */
365
+ /** Which built-in diagram a help tab shows. */
366
+ type HelpTabKind = "touch" | "vr" | "keyboard-mouse" | "gamepad" | "cardboard";
367
+ //#endregion
368
+ //#region src/components/help/help.d.ts
369
+ /** One help tab: a built-in control diagram plus localized instruction lines. */
370
+ interface HelpTab {
371
+ /** Which input mode this tab documents (picks the built-in diagram). */
372
+ kind: HelpTabKind;
373
+ /** Tab title (short). */
374
+ title: Text;
375
+ /** Instruction lines shown under the diagram. */
376
+ lines: Text[];
377
+ /** Render the lines as a numbered list (e.g. Cardboard setup steps). */
378
+ ordered?: boolean;
379
+ }
380
+ interface HelpPanelOptions {
381
+ /** Modal title, also the ⓘ button's aria-label. */
382
+ title: Text;
383
+ /** Aria-label for the ✕ close button. Defaults to "Close". */
384
+ closeLabel?: Text;
385
+ /** The tabs to show, in order. */
386
+ tabs: HelpTab[];
387
+ /**
388
+ * On open, pre-select the tab for the current mode: the active view mode when
389
+ * it's VR or Cardboard (an explicit gyro mode), else the last-used input
390
+ * modality (touch / keyboard-mouse / gamepad). Defaults to `true`. The visitor
391
+ * can still switch tabs freely. When no match is present, the first tab stays
392
+ * selected.
393
+ */
394
+ autoSelect?: boolean;
395
+ }
396
+ /**
397
+ * A visual controls-help panel: an ⓘ button opening a centered daisyUI modal
398
+ * with one tab per input mode, each showing an SVG diagram and a few localized
399
+ * lines. On open it pre-selects the tab for the mode you're using. Diagrams are
400
+ * built in (standard schemes); the text is app-supplied `Text`, relocalized live.
401
+ */
402
+ declare function helpPanel(options: HelpPanelOptions): OverlayComponent;
403
+ //#endregion
267
404
  //#region src/components/artwork-info/artwork-info.d.ts
268
405
  interface ArtworkInfoOptions {
269
406
  /** The artworks' data, looked up by `id` on select. Usually `scene.artworks`. */
@@ -281,14 +418,26 @@ interface ArtworkInfoOptions {
281
418
  };
282
419
  /** Label for the link shown when an artwork has an `href`. Defaults to "View artwork". */
283
420
  linkText?: string;
421
+ /** Label/aria for the "previous piece" button. Defaults to "Previous". */
422
+ prevLabel?: string;
423
+ /** Label/aria for the "next piece" button. Defaults to "Next". */
424
+ nextLabel?: string;
425
+ /**
426
+ * Minimum camera distance from the piece (world units) enforced when the panel
427
+ * closes. If the centered framing would be closer, the camera pulls back to
428
+ * this so a small piece doesn't leave you pinned to the wall. Default `0`.
429
+ */
430
+ minCloseDistance?: number;
284
431
  }
285
432
  /**
286
433
  * The artwork info panel. The engine emits `artwork:select { id }` when you click
287
434
  * a piece's cartela (or the piece itself); this opens a left-hand panel (40%
288
435
  * width, full height, black at 85% alpha) with the full caption and asks the
289
- * camera to frame the piece in the free right 60%. Closing with ✕ re-centers the
290
- * piece full-width; if the user walks/turns away the engine emits
291
- * `artwork:released` and the panel just closes (no camera move).
436
+ * camera to frame the piece in the free right 60%. Prev/next buttons at the
437
+ * bottom cycle through the pieces (wrapping) without leaving the panel. Closing
438
+ * with ✕ re-centers the piece full-width, pulling back to `minCloseDistance` when
439
+ * the framing would otherwise be too close; if the user walks/turns away the
440
+ * engine emits `artwork:released` and the panel just closes (no camera move).
292
441
  *
293
442
  * Content is data (`artworks`), unlocalized for now. The panel is mounted on the
294
443
  * surface (escaping the overlay grid); the slot element is an inert placeholder.
@@ -314,8 +463,28 @@ interface DefaultPresetOptions {
314
463
  settings?: SettingsPanelOptions;
315
464
  /** Environment panel (time of day, sun azimuth); when given, a ☼ button is added top-right. Off by default. */
316
465
  environment?: EnvironmentPanelOptions;
466
+ /** Cardboard (stereoscopic VR) toggle — experimental, so it is opt-in. Pass `true` (or options) to add the 🥽 button top-right. Off by default. */
467
+ cardboard?: CardboardButtonOptions | boolean;
468
+ /**
469
+ * Camera-control mode picker (Touch / VR / Cardboard) as a `ScanEye` button
470
+ * top-right. The button only appears when the device supports two or more of
471
+ * the given modes (e.g. a phone with a gyroscope); on desktop it's hidden. Pass
472
+ * labels for every mode — the preset filters to the available ones.
473
+ */
474
+ viewMode?: ViewModeButtonOptions;
475
+ /**
476
+ * "Home" button (top-right) that returns the camera to the scene's start, for
477
+ * visitors who lose their way. Pass `true` (or options) to add it. Off by default.
478
+ */
479
+ resetView?: ResetViewButtonOptions | boolean;
317
480
  /** Info panel (e.g. control instructions); when given, an ⓘ button is added bottom-right, above credits. */
318
481
  info?: InfoPanelOptions;
482
+ /**
483
+ * Visual controls-help panel (tabbed, with per-mode diagrams). When given, an
484
+ * ⓘ button is added bottom-right, above credits. Prefer this over `info` for
485
+ * control instructions; if both are set, `help` wins (they share the slot).
486
+ */
487
+ help?: HelpPanelOptions;
319
488
  /** Artwork info panel; when given, clicking a piece opens its caption on the left. */
320
489
  artworks?: ArtworkInfoOptions;
321
490
  /** Asset attributions; when given, a credits panel is added bottom-right. */
@@ -333,5 +502,5 @@ interface DefaultPresetOptions {
333
502
  */
334
503
  declare function defaultPreset(overlay: Overlay, options?: DefaultPresetOptions): void;
335
504
  //#endregion
336
- export { type ActionButtonOptions, type ArtworkInfoOptions, type CardboardButtonOptions, type CreditEntry, type CreditItem, type CreditSection, type CreditTab, type CreditsPanelOptions, type DefaultPresetOptions, type EnvironmentPanelOptions, type FullscreenButtonOptions, type IconContent, type InfoPanelOptions, type MuteButtonOptions, type SettingsChoice, type SettingsChoiceGroup, type SettingsPanelOptions, type SettingsSliderItem, type SettingsToggleItem, type WatermarkOptions, actionButton, artworkInfo, cardboardButton, creditsPanel, defaultPreset, environmentPanel, fullscreenButton, infoPanel, lucideIcon, muteButton, settingsPanel, watermark };
505
+ export { type ActionButtonOptions, type ArtworkInfoOptions, type CardboardButtonOptions, type ControlCapabilities, type CreditEntry, type CreditItem, type CreditSection, type CreditTab, type CreditsPanelOptions, type DefaultPresetOptions, type EnvironmentPanelOptions, type FullscreenButtonOptions, type HelpPanelOptions, type HelpTab, type HelpTabKind, type IconContent, type InfoPanelOptions, type MuteButtonOptions, type ResetViewButtonOptions, type SelectableMode, type SettingsChoice, type SettingsChoiceGroup, type SettingsControlItem, type SettingsPanelOptions, type SettingsSliderItem, type SettingsToggleItem, type ViewModeButtonOptions, type ViewModeItem, type WatermarkOptions, actionButton, artworkInfo, availableModes, cardboardButton, creditsPanel, defaultPreset, detectControlCapabilities, environmentPanel, fullscreenButton, helpPanel, infoPanel, lucideIcon, muteButton, resetViewButton, settingsPanel, viewModeButton, watermark };
337
506
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.mts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { Overlay, OverlayComponent, OverlayContext, Text } from "@scenography/overlay";
2
+ import { ControlFlags, ControlMode } from "@scenography/engine";
2
3
  import { Artwork } from "@scenography/plugin-artwork/data";
3
4
 
4
5
  //#region src/util.d.ts
@@ -72,12 +73,87 @@ interface CardboardButtonOptions {
72
73
  */
73
74
  declare function cardboardButton(options?: CardboardButtonOptions): OverlayComponent;
74
75
  //#endregion
76
+ //#region src/components/reset-view/reset-view.d.ts
77
+ interface ResetViewButtonOptions {
78
+ /** Button icon. Defaults to a plain glyph ⌂; pass `lucideIcon("House")`. */
79
+ icon?: IconContent;
80
+ /** Aria-label (relocalized live). Defaults to "Reset view". */
81
+ label?: Text;
82
+ /** Override the daisyUI/utility classes on the button. */
83
+ className?: string;
84
+ }
85
+ /**
86
+ * A "home" button that returns the camera to the scene's start position and
87
+ * orientation (`ctx.camera.reset()`) — for visitors who wander off and want to
88
+ * get back to the entrance. Defaults to a plain glyph; pass `lucideIcon("House")`.
89
+ */
90
+ declare function resetViewButton(options?: ResetViewButtonOptions): OverlayComponent;
91
+ //#endregion
92
+ //#region src/components/view-mode/capabilities.d.ts
93
+ /** The camera-control modes a visitor can pick between (excludes `custom`). */
94
+ type SelectableMode = Exclude<ControlMode, "custom">;
95
+ /** What the current device can do, as far as camera control is concerned. */
96
+ interface ControlCapabilities {
97
+ /** A touch screen (coarse pointer) — needed for the on-screen joysticks. */
98
+ touch: boolean;
99
+ /** A motion sensor for gyroscope head-look (VR / Cardboard). */
100
+ gyro: boolean;
101
+ }
102
+ /**
103
+ * Sniff the device's control capabilities. Deliberately conservative: gyro is
104
+ * gated behind a touch (mobile) device too, since desktops expose the
105
+ * `DeviceOrientationEvent` interface but never fire it — pairing it with a coarse
106
+ * pointer avoids offering VR/Cardboard where they can't work.
107
+ */
108
+ declare function detectControlCapabilities(): ControlCapabilities;
109
+ /**
110
+ * The modes worth offering on this device, in display order. Touch needs a touch
111
+ * screen; VR and Cardboard additionally need the gyro. Desktop (no touch) gets an
112
+ * empty list — it uses keyboard/mouse and shows no mode picker at all.
113
+ */
114
+ declare function availableModes(caps: ControlCapabilities): SelectableMode[];
115
+ //#endregion
116
+ //#region src/components/view-mode/view-mode.d.ts
117
+ /** One selectable mode in the picker. */
118
+ interface ViewModeItem {
119
+ mode: SelectableMode;
120
+ /** Short mode name (e.g. "Touch", "VR", "Cardboard"). */
121
+ label: Text;
122
+ }
123
+ interface ViewModeButtonOptions {
124
+ /** Modal title, also the button's aria-label. */
125
+ title: Text;
126
+ /** Aria-label for the ✕ close button. Defaults to "Close". */
127
+ closeLabel?: Text;
128
+ /**
129
+ * The modes to offer, in order. Usually pre-filtered to what the device
130
+ * supports (see `availableModes`); the caller decides whether to show the
131
+ * button at all (typically only when two or more modes are available).
132
+ */
133
+ modes: ViewModeItem[];
134
+ }
135
+ /**
136
+ * A camera-control mode picker: a `ScanEye` button opening a small modal with one
137
+ * entry per mode (Touch / VR / Cardboard). Picking one calls
138
+ * `ctx.viewControls.setMode` — which, inside this click gesture, flips the
139
+ * gyroscope and stereo split (so iOS grants motion here). The active mode is
140
+ * marked and kept in sync via the `controls:change` event, so the settings panel
141
+ * and this picker never disagree.
142
+ */
143
+ declare function viewModeButton(options: ViewModeButtonOptions): OverlayComponent;
144
+ //#endregion
75
145
  //#region src/components/settings/settings.d.ts
76
146
  /** One option in a single-choice section. */
77
147
  interface SettingsChoice {
78
148
  value: string;
79
149
  label: Text;
80
150
  }
151
+ /** One control-flag toggle in the Controls section (wired to `ctx.viewControls`). */
152
+ interface SettingsControlItem {
153
+ /** Which control flag this toggles (e.g. `gyro`, `invertLookX`). */
154
+ key: keyof ControlFlags;
155
+ label: Text;
156
+ }
81
157
  /** One boolean toggle in the multi-toggle section. */
82
158
  interface SettingsToggleItem {
83
159
  key: string;
@@ -131,6 +207,18 @@ interface SettingsPanelOptions {
131
207
  options: SettingsChoice[];
132
208
  onChange: (value: string) => void;
133
209
  };
210
+ /**
211
+ * The Controls section: toggles for the camera-control flags (gyroscope, split
212
+ * screen, virtual joysticks, invert look X/Y). Unlike the other sections this
213
+ * one is *self-wired* to `ctx.viewControls` — pass which flags to show and their
214
+ * labels; the panel reads/writes the live state and stays in sync with the mode
215
+ * picker. Own tab.
216
+ */
217
+ controls?: {
218
+ tab?: Text;
219
+ label: Text;
220
+ items: SettingsControlItem[];
221
+ };
134
222
  /** A multi-toggle section (e.g. graphics: ssao / bloom / shadows). Own tab. */
135
223
  graphics?: {
136
224
  tab?: Text;
@@ -264,6 +352,55 @@ interface InfoPanelOptions {
264
352
  */
265
353
  declare function infoPanel(options: InfoPanelOptions): OverlayComponent;
266
354
  //#endregion
355
+ //#region src/components/help/diagrams.d.ts
356
+ /**
357
+ * Built-in control-scheme diagrams for the help panel. Standard schemes, so they
358
+ * live in the preset (the app only supplies the localized text). Cardboard is a
359
+ * single diagram; touch, keyboard-mouse and gamepad are split into one figure per
360
+ * control (see `sectionFigures`). Pure pictograms: no words inside the SVG (only
361
+ * universal key legends like WASD), so nothing here needs localizing. Outlines use
362
+ * `currentColor`; the interactive/highlighted parts are wrapped in a `text-primary`
363
+ * group so they pop and stay theme-aware in light and dark.
364
+ */
365
+ /** Which built-in diagram a help tab shows. */
366
+ type HelpTabKind = "touch" | "vr" | "keyboard-mouse" | "gamepad" | "cardboard";
367
+ //#endregion
368
+ //#region src/components/help/help.d.ts
369
+ /** One help tab: a built-in control diagram plus localized instruction lines. */
370
+ interface HelpTab {
371
+ /** Which input mode this tab documents (picks the built-in diagram). */
372
+ kind: HelpTabKind;
373
+ /** Tab title (short). */
374
+ title: Text;
375
+ /** Instruction lines shown under the diagram. */
376
+ lines: Text[];
377
+ /** Render the lines as a numbered list (e.g. Cardboard setup steps). */
378
+ ordered?: boolean;
379
+ }
380
+ interface HelpPanelOptions {
381
+ /** Modal title, also the ⓘ button's aria-label. */
382
+ title: Text;
383
+ /** Aria-label for the ✕ close button. Defaults to "Close". */
384
+ closeLabel?: Text;
385
+ /** The tabs to show, in order. */
386
+ tabs: HelpTab[];
387
+ /**
388
+ * On open, pre-select the tab for the current mode: the active view mode when
389
+ * it's VR or Cardboard (an explicit gyro mode), else the last-used input
390
+ * modality (touch / keyboard-mouse / gamepad). Defaults to `true`. The visitor
391
+ * can still switch tabs freely. When no match is present, the first tab stays
392
+ * selected.
393
+ */
394
+ autoSelect?: boolean;
395
+ }
396
+ /**
397
+ * A visual controls-help panel: an ⓘ button opening a centered daisyUI modal
398
+ * with one tab per input mode, each showing an SVG diagram and a few localized
399
+ * lines. On open it pre-selects the tab for the mode you're using. Diagrams are
400
+ * built in (standard schemes); the text is app-supplied `Text`, relocalized live.
401
+ */
402
+ declare function helpPanel(options: HelpPanelOptions): OverlayComponent;
403
+ //#endregion
267
404
  //#region src/components/artwork-info/artwork-info.d.ts
268
405
  interface ArtworkInfoOptions {
269
406
  /** The artworks' data, looked up by `id` on select. Usually `scene.artworks`. */
@@ -281,14 +418,26 @@ interface ArtworkInfoOptions {
281
418
  };
282
419
  /** Label for the link shown when an artwork has an `href`. Defaults to "View artwork". */
283
420
  linkText?: string;
421
+ /** Label/aria for the "previous piece" button. Defaults to "Previous". */
422
+ prevLabel?: string;
423
+ /** Label/aria for the "next piece" button. Defaults to "Next". */
424
+ nextLabel?: string;
425
+ /**
426
+ * Minimum camera distance from the piece (world units) enforced when the panel
427
+ * closes. If the centered framing would be closer, the camera pulls back to
428
+ * this so a small piece doesn't leave you pinned to the wall. Default `0`.
429
+ */
430
+ minCloseDistance?: number;
284
431
  }
285
432
  /**
286
433
  * The artwork info panel. The engine emits `artwork:select { id }` when you click
287
434
  * a piece's cartela (or the piece itself); this opens a left-hand panel (40%
288
435
  * width, full height, black at 85% alpha) with the full caption and asks the
289
- * camera to frame the piece in the free right 60%. Closing with ✕ re-centers the
290
- * piece full-width; if the user walks/turns away the engine emits
291
- * `artwork:released` and the panel just closes (no camera move).
436
+ * camera to frame the piece in the free right 60%. Prev/next buttons at the
437
+ * bottom cycle through the pieces (wrapping) without leaving the panel. Closing
438
+ * with ✕ re-centers the piece full-width, pulling back to `minCloseDistance` when
439
+ * the framing would otherwise be too close; if the user walks/turns away the
440
+ * engine emits `artwork:released` and the panel just closes (no camera move).
292
441
  *
293
442
  * Content is data (`artworks`), unlocalized for now. The panel is mounted on the
294
443
  * surface (escaping the overlay grid); the slot element is an inert placeholder.
@@ -314,8 +463,28 @@ interface DefaultPresetOptions {
314
463
  settings?: SettingsPanelOptions;
315
464
  /** Environment panel (time of day, sun azimuth); when given, a ☼ button is added top-right. Off by default. */
316
465
  environment?: EnvironmentPanelOptions;
466
+ /** Cardboard (stereoscopic VR) toggle — experimental, so it is opt-in. Pass `true` (or options) to add the 🥽 button top-right. Off by default. */
467
+ cardboard?: CardboardButtonOptions | boolean;
468
+ /**
469
+ * Camera-control mode picker (Touch / VR / Cardboard) as a `ScanEye` button
470
+ * top-right. The button only appears when the device supports two or more of
471
+ * the given modes (e.g. a phone with a gyroscope); on desktop it's hidden. Pass
472
+ * labels for every mode — the preset filters to the available ones.
473
+ */
474
+ viewMode?: ViewModeButtonOptions;
475
+ /**
476
+ * "Home" button (top-right) that returns the camera to the scene's start, for
477
+ * visitors who lose their way. Pass `true` (or options) to add it. Off by default.
478
+ */
479
+ resetView?: ResetViewButtonOptions | boolean;
317
480
  /** Info panel (e.g. control instructions); when given, an ⓘ button is added bottom-right, above credits. */
318
481
  info?: InfoPanelOptions;
482
+ /**
483
+ * Visual controls-help panel (tabbed, with per-mode diagrams). When given, an
484
+ * ⓘ button is added bottom-right, above credits. Prefer this over `info` for
485
+ * control instructions; if both are set, `help` wins (they share the slot).
486
+ */
487
+ help?: HelpPanelOptions;
319
488
  /** Artwork info panel; when given, clicking a piece opens its caption on the left. */
320
489
  artworks?: ArtworkInfoOptions;
321
490
  /** Asset attributions; when given, a credits panel is added bottom-right. */
@@ -333,5 +502,5 @@ interface DefaultPresetOptions {
333
502
  */
334
503
  declare function defaultPreset(overlay: Overlay, options?: DefaultPresetOptions): void;
335
504
  //#endregion
336
- export { type ActionButtonOptions, type ArtworkInfoOptions, type CardboardButtonOptions, type CreditEntry, type CreditItem, type CreditSection, type CreditTab, type CreditsPanelOptions, type DefaultPresetOptions, type EnvironmentPanelOptions, type FullscreenButtonOptions, type IconContent, type InfoPanelOptions, type MuteButtonOptions, type SettingsChoice, type SettingsChoiceGroup, type SettingsPanelOptions, type SettingsSliderItem, type SettingsToggleItem, type WatermarkOptions, actionButton, artworkInfo, cardboardButton, creditsPanel, defaultPreset, environmentPanel, fullscreenButton, infoPanel, lucideIcon, muteButton, settingsPanel, watermark };
505
+ export { type ActionButtonOptions, type ArtworkInfoOptions, type CardboardButtonOptions, type ControlCapabilities, type CreditEntry, type CreditItem, type CreditSection, type CreditTab, type CreditsPanelOptions, type DefaultPresetOptions, type EnvironmentPanelOptions, type FullscreenButtonOptions, type HelpPanelOptions, type HelpTab, type HelpTabKind, type IconContent, type InfoPanelOptions, type MuteButtonOptions, type ResetViewButtonOptions, type SelectableMode, type SettingsChoice, type SettingsChoiceGroup, type SettingsControlItem, type SettingsPanelOptions, type SettingsSliderItem, type SettingsToggleItem, type ViewModeButtonOptions, type ViewModeItem, type WatermarkOptions, actionButton, artworkInfo, availableModes, cardboardButton, creditsPanel, defaultPreset, detectControlCapabilities, environmentPanel, fullscreenButton, helpPanel, infoPanel, lucideIcon, muteButton, resetViewButton, settingsPanel, viewModeButton, watermark };
337
506
  //# sourceMappingURL=index.d.mts.map