@retoo/scena 0.0.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.
@@ -0,0 +1,1235 @@
1
+ export { default as Scena } from './app/entrypoint/ui/Scena.svelte';
2
+
3
+ /** Event names emitted by the scena widget event bus. */
4
+ declare enum ScenaEvent {
5
+ /** Fired when the scena component is mounted in the DOM. */
6
+ ON_SCENA_MOUNT = "scena:on-mount",
7
+ /** Fired when the scena instance is destroyed. */
8
+ ON_SCENA_DESTROY = "scena:on-destroy",
9
+ /** Fired when the video element is ready for playback. */
10
+ ON_VIDEO_READY = "video:on-ready",
11
+ /** Fired when video playback starts. */
12
+ ON_VIDEO_PLAY = "video:on-play",
13
+ /** Fired when the browser can start playing the video. */
14
+ ON_VIDEO_CAN_PLAY = "video:on-can-play",
15
+ /** Fired when video playback is paused. */
16
+ ON_VIDEO_PAUSE = "video:on-pause",
17
+ /** Fired while the video is seeking to a new position. */
18
+ ON_VIDEO_SEEKING = "video:on-seeking",
19
+ /** Fired when a seek operation completes. */
20
+ ON_VIDEO_SEEKED = "video:on-seeked",
21
+ /** Fired when the user begins a seek interaction. */
22
+ ON_VIDEO_SEEK_START = "video:on-seek-start",
23
+ /** Fired when the user ends a seek interaction. */
24
+ ON_VIDEO_SEEK_END = "video:on-seek-end",
25
+ /** Fired when the video reaches the end. */
26
+ ON_VIDEO_ENDED = "video:on-ended",
27
+ /** Fired when the browser begins loading video data. */
28
+ ON_VIDEO_LOAD_START = "video:on-load-start",
29
+ /** Fired when video metadata has been loaded. */
30
+ ON_VIDEO_LOADED = "video:on-loaded",
31
+ /** Fired periodically as video playback progresses. */
32
+ ON_VIDEO_TIME_UPDATE = "video:on-time-update",
33
+ /** Fired when the volume or muted state changes. */
34
+ ON_VIDEO_VOLUME_CHANGE = "video:on-volume-change",
35
+ /** Fired when the video playback state changes (e.g. playing → paused). */
36
+ ON_VIDEO_STATE_CHANGE = "video:on-state-change",
37
+ /** Fired when the video stalls and starts buffering. */
38
+ ON_VIDEO_WAITING = "video:on-waiting",
39
+ /** Fired when the video download progresses. */
40
+ ON_VIDEO_PROGRESSED = "video:on-progressed",
41
+ /** Fired when a video playback error occurs. */
42
+ ON_VIDEO_ERROR = "video:on-error",
43
+ /** Fired when the video container area is clicked. */
44
+ ON_VIDEO_CONTAINER_CLICK = "video-container:click",
45
+ /** Fired when the CTA button is clicked. */
46
+ ON_CTA_CLICK = "cta:click",
47
+ /** Fired when the close button is clicked. */
48
+ ON_CLOSE_CLICK = "close:click",
49
+ /** Fired when preview mode is activated. */
50
+ ON_PREVIEW_START = "preview:start",
51
+ /** Fired when preview mode is deactivated. */
52
+ ON_PREVIEW_STOP = "preview:stop",
53
+ /** Fired when the widget becomes visible. */
54
+ ON_VISIBILITY_SHOW = "visibility:show",
55
+ /** Fired when the widget becomes hidden. */
56
+ ON_VISIBILITY_HIDE = "visibility:hide"
57
+ }
58
+
59
+ /** Callback invoked when a subscribed event is emitted. */
60
+ type ScenaEventHandler<T = unknown> = (data: T) => void;
61
+ /** Internal storage: event name → set of handlers. */
62
+ type ScenaEventMap<T = unknown> = Map<ScenaEvent, Set<ScenaEventHandler<T>>>;
63
+ /** Pub/sub event bus for communication between scena components. */
64
+ interface ScenaEventEmitter {
65
+ /** Subscribe a handler to an event. */
66
+ on(eventName: ScenaEvent, handler: ScenaEventHandler): void;
67
+ /** Unsubscribe a specific handler from an event. */
68
+ off(eventName: ScenaEvent, handler: ScenaEventHandler): void;
69
+ /** Emit an event, calling all subscribed handlers with optional data. */
70
+ emit<T>(eventName: ScenaEvent, data?: T): void;
71
+ /** Remove all handlers for a specific event. */
72
+ remove(eventName: ScenaEvent): void;
73
+ /** Remove all handlers for all events. */
74
+ clear(): void;
75
+ }
76
+
77
+ /** Creates a pub/sub event emitter instance. */
78
+ declare function useEventEmitter(): ScenaEventEmitter;
79
+
80
+ /** T-shirt size scale used for component sizing. */
81
+ declare enum ComponentSize {
82
+ XS = "xs",
83
+ SM = "sm",
84
+ MD = "md",
85
+ LG = "lg",
86
+ XL = "xl",
87
+ XXL = "xxl"
88
+ }
89
+ /** Placement of a component within its container (3×3 grid). */
90
+ declare enum ComponentPlacement {
91
+ TOP_START = "top-start",
92
+ TOP_CENTER = "top-center",
93
+ TOP_END = "top-end",
94
+ MIDDLE_START = "middle-start",
95
+ MIDDLE_CENTER = "middle-center",
96
+ MIDDLE_END = "middle-end",
97
+ BOTTOM_START = "bottom-start",
98
+ BOTTOM_CENTER = "bottom-center",
99
+ BOTTOM_END = "bottom-end"
100
+ }
101
+ /** CSS `position` values for component layout. */
102
+ declare enum ComponentPosition {
103
+ STATIC = "static",
104
+ RELATIVE = "relative",
105
+ ABSOLUTE = "absolute",
106
+ FIXED = "fixed"
107
+ }
108
+ /** Shape variant for components (affects border-radius and aspect ratio). */
109
+ declare enum ComponentShape {
110
+ CIRCLE = "circle",
111
+ LANDSCAPE = "landscape",
112
+ PORTRAIT = "portrait",
113
+ SQUARE = "square"
114
+ }
115
+ /** Possible values for the `aria-pressed` attribute. */
116
+ declare enum ComponentAriaPressed {
117
+ MIXED = "mixed"
118
+ }
119
+ /** Possible values for the `aria-haspopup` attribute. */
120
+ declare enum ComponentAriaHaspopup {
121
+ MENU = "menu",
122
+ TREE = "tree",
123
+ GRID = "grid",
124
+ DIALOG = "dialog",
125
+ LISTBOX = "listbox"
126
+ }
127
+
128
+ /** Named override layer. */
129
+ declare enum OverrideLayer {
130
+ RESPONSIVE = "responsive",
131
+ PREVIEW = "preview"
132
+ }
133
+
134
+ /** Inline styles — a raw CSS string or a partial `CSSStyleDeclaration` object. */
135
+ type ComponentStyles = string | Partial<CSSStyleDeclaration>;
136
+ /**
137
+ * Class binding value.
138
+ * Accepts a string, falsy values (skipped), an object whose truthy keys
139
+ * are added as classes, or a nested array of the same.
140
+ */
141
+ type ComponentClasses = string | number | false | null | undefined | Record<string, boolean> | ComponentClasses[];
142
+ /** Common ARIA attributes shared across interactive components. */
143
+ interface ComponentAriaProps {
144
+ ariaLabel?: string;
145
+ ariaLabelledby?: string;
146
+ ariaDescribedby?: string;
147
+ ariaDisabled?: boolean;
148
+ ariaExpanded?: boolean;
149
+ ariaControls?: string;
150
+ ariaPressed?: ComponentAriaPressed;
151
+ ariaHaspopup?: ComponentAriaHaspopup;
152
+ }
153
+
154
+ /** Internal return type for component snippets. */
155
+ type ComponentSnippetReturn = any;
156
+ /**
157
+ * Typed Svelte 5 snippet reference.
158
+ * Produces a descriptive compile-time error when used incorrectly
159
+ * (e.g. called as a function instead of `{@render ...}`).
160
+ */
161
+ interface ComponentSnippet<Parameters extends unknown[] = []> {
162
+ (this: void, ...args: number extends Parameters['length'] ? never : Parameters): {
163
+ '{@render ...} must be called with a Snippet': "import type { ComponentSnippet } from '@retoo/scena'";
164
+ } & ComponentSnippetReturn;
165
+ }
166
+
167
+ /** Custom CSS class overrides for the outer container. */
168
+ interface ScenaContainerCustomClasses {
169
+ root: ComponentClasses;
170
+ }
171
+ /** Custom inline style overrides for the outer container. */
172
+ interface ScenaContainerCustomStyles {
173
+ root: ComponentStyles;
174
+ }
175
+ /** Configuration props for the scena outer container. */
176
+ interface ScenaContainerProps {
177
+ id: string;
178
+ /** CSS `position` value for the container. */
179
+ position: ComponentPosition;
180
+ /** Placement within the viewport (e.g. bottom-end). */
181
+ placement: ComponentPlacement;
182
+ customClasses: Partial<ScenaContainerCustomClasses>;
183
+ customStyles: Partial<ScenaContainerCustomStyles>;
184
+ }
185
+ /** Snippet slots for the container widget. */
186
+ interface ScenaContainerSnippets {
187
+ children: ComponentSnippet;
188
+ }
189
+ /** Component ref for the outer container. */
190
+ interface ScenaContainerRef {
191
+ getElements: () => {
192
+ root: HTMLDivElement;
193
+ };
194
+ }
195
+
196
+ /** Possible values for `aria-pressed` on scena buttons. */
197
+ declare enum ScenaButtonAriaPressed {
198
+ MIXED = "mixed"
199
+ }
200
+ /** Possible values for `aria-haspopup` on scena buttons. */
201
+ declare enum ScenaButtonAriaHaspopup {
202
+ MENU = "menu",
203
+ LISTBOX = "listbox",
204
+ TREE = "tree",
205
+ GRID = "grid",
206
+ DIALOG = "dialog"
207
+ }
208
+ /** Shape of the button element. */
209
+ declare enum ScenaButtonShape {
210
+ RECTANGLE = "rectangle",
211
+ CIRCLE = "circle",
212
+ SQUARE = "square"
213
+ }
214
+ /** Visual variant of the button. */
215
+ declare enum ScenaButtonVariant {
216
+ /** Solid background fill. */
217
+ FILLED = "filled",
218
+ /** Transparent background, text only. */
219
+ TEXT = "text"
220
+ }
221
+ /** HTML `type` attribute for the button element. */
222
+ declare enum ScenaButtonType {
223
+ BUTTON = "button",
224
+ SUBMIT = "submit",
225
+ RESET = "reset"
226
+ }
227
+
228
+ /** Custom CSS class overrides for the base button. */
229
+ interface ScenaButtonComponentClasses {
230
+ root: ComponentClasses;
231
+ }
232
+ /** Custom inline style overrides for the base button. */
233
+ interface ScenaButtonComponentStyles {
234
+ root: ComponentStyles;
235
+ }
236
+ /** Configuration props for the base scena button component. */
237
+ interface ScenaButtonProps {
238
+ id: string;
239
+ autosize: boolean;
240
+ size: ComponentSize;
241
+ shape: ScenaButtonShape;
242
+ variant: ScenaButtonVariant;
243
+ type: ScenaButtonType;
244
+ aria: Partial<ComponentAriaProps>;
245
+ customClasses: Partial<ScenaButtonComponentClasses>;
246
+ customStyles: Partial<ScenaButtonComponentStyles>;
247
+ }
248
+ /** Event handlers for the base button. */
249
+ interface ScenaButtonEvents {
250
+ onclick: (event: Event) => void;
251
+ }
252
+ /** Snippet slots for the base button. */
253
+ interface ScenaButtonSnippets {
254
+ children: ComponentSnippet;
255
+ }
256
+ /** DOM element references for the base button. */
257
+ interface ScenaButtonElements {
258
+ root: HTMLButtonElement;
259
+ }
260
+
261
+ interface ScenaIconCustomClasses {
262
+ root: ComponentClasses;
263
+ }
264
+ interface ScenaIconCustomStyles {
265
+ root: ComponentStyles;
266
+ }
267
+ interface ScenaIconProps {
268
+ id: string;
269
+ viewBox: string;
270
+ size: ComponentSize;
271
+ customClasses: Partial<ScenaIconCustomClasses>;
272
+ customStyles: Partial<ScenaIconCustomStyles>;
273
+ }
274
+ interface ScenaIconSnippets {
275
+ children: ComponentSnippet;
276
+ }
277
+ interface ScenaIconElements {
278
+ root: SVGSVGElement;
279
+ }
280
+
281
+ /** Custom CSS class overrides for the close button and its sub-components. */
282
+ interface ScenaCloseButtonComponentClasses {
283
+ root: ComponentClasses;
284
+ button: ComponentClasses;
285
+ cross: ComponentClasses;
286
+ }
287
+ /** Custom inline style overrides for the close button and its sub-components. */
288
+ interface ScenaCloseButtonComponentStyles {
289
+ root: ComponentStyles;
290
+ button: ComponentStyles;
291
+ cross: ComponentStyles;
292
+ }
293
+ /** Configuration props for the close button widget. */
294
+ interface ScenaCloseButtonProps {
295
+ id: string;
296
+ size: ComponentSize;
297
+ shape: ComponentShape;
298
+ aria: Partial<ComponentAriaProps>;
299
+ customClasses: Partial<ScenaCloseButtonComponentClasses>;
300
+ customStyles: Partial<ScenaCloseButtonComponentStyles>;
301
+ onClick: (event: Event) => void;
302
+ }
303
+ /** Component ref for the close button. */
304
+ interface ScenaCloseButtonRef {
305
+ getElements: () => {
306
+ root: HTMLDivElement;
307
+ button: ScenaButtonElements | undefined;
308
+ cross: ScenaIconElements | undefined;
309
+ };
310
+ }
311
+
312
+ declare enum ScenaCtaButtonPlacement {
313
+ INSIDE = "inside",
314
+ OUTSIDE = "outside"
315
+ }
316
+
317
+ /** Custom CSS class overrides for the CTA button. */
318
+ interface ScenaCtaButtonComponentClasses {
319
+ root: ComponentClasses;
320
+ button: ComponentClasses;
321
+ }
322
+ /** Custom inline style overrides for the CTA button. */
323
+ interface ScenaCtaButtonComponentStyles {
324
+ root: ComponentStyles;
325
+ button: ComponentStyles;
326
+ }
327
+ /** Adaptive display settings for the CTA button across screen sizes. */
328
+ interface ScenaCtaButtonAdaptive {
329
+ sizes: ComponentSize[];
330
+ placement: ScenaCtaButtonPlacement;
331
+ }
332
+ /** Configuration props for the CTA (call-to-action) button widget. */
333
+ interface ScenaCtaButtonProps {
334
+ id: string;
335
+ text: string;
336
+ size: ComponentSize;
337
+ placement: ScenaCtaButtonPlacement;
338
+ adaptive: ScenaCtaButtonAdaptive | false;
339
+ aria: Partial<ComponentAriaProps>;
340
+ customClasses: Partial<ScenaCtaButtonComponentClasses>;
341
+ customStyles: Partial<ScenaCtaButtonComponentStyles>;
342
+ onClick: (event: Event) => void;
343
+ }
344
+ /** Component ref for the CTA button. */
345
+ interface ScenaCtaButtonRef {
346
+ getElements: () => {
347
+ root: HTMLDivElement;
348
+ button: ScenaButtonElements | undefined;
349
+ };
350
+ }
351
+
352
+ /** Preload strategy for the `<video>` element. */
353
+ declare enum ScenaVideoPreload {
354
+ NONE = "none",
355
+ AUTO = "auto",
356
+ METADATA = "metadata"
357
+ }
358
+ /** CORS setting for the `<video>` element. */
359
+ declare enum ScenaVideoCrossOrigin {
360
+ ANONYMOUS = "anonymous",
361
+ USE_CREDENTIALS = "use-credentials"
362
+ }
363
+ /** Playback state of the video player. */
364
+ declare enum ScenaVideoState {
365
+ IDLE = "idle",
366
+ LOADING = "loading",
367
+ PLAYING = "playing",
368
+ PAUSED = "paused",
369
+ ENDED = "ended",
370
+ ERROR = "error"
371
+ }
372
+
373
+ /** Reactive state data of the video player. */
374
+ interface ScenaVideoData {
375
+ /** Current playback state. */
376
+ state: ScenaVideoState;
377
+ /** Current playback position in seconds. */
378
+ currentTime: number;
379
+ /** Total video duration in seconds. */
380
+ duration: number;
381
+ /** Playback progress as a fraction (0–1). */
382
+ progress: number;
383
+ /** Active `requestAnimationFrame` ID for progress tracking, if any. */
384
+ progressAnimationFrameId: number | null;
385
+ /** Current volume level (0–1). */
386
+ volume: number;
387
+ /** Buffered amount as a fraction (0–1). */
388
+ buffer: number;
389
+ /** Raw `TimeRanges` from the video element. */
390
+ buffered: TimeRanges | null;
391
+ /** Whether the video is currently buffering. */
392
+ isBuffering: boolean;
393
+ /** Whether a seek operation is in progress. */
394
+ isSeeking: boolean;
395
+ /** Whether the video is muted. */
396
+ isMuted: boolean;
397
+ }
398
+ /** Imperative methods for controlling video playback. */
399
+ interface ScenaVideoMethods {
400
+ /** Start or resume playback. */
401
+ play: () => Promise<void>;
402
+ /** Pause playback. */
403
+ pause: () => void;
404
+ /** Stop playback and reset to the beginning. */
405
+ stop: () => void;
406
+ /** Seek to a specific time in seconds. */
407
+ seek: (value: number) => void;
408
+ /** Set the volume level (0–1). */
409
+ setVolume: (value: number) => void;
410
+ /** Mute the video. */
411
+ mute: () => void;
412
+ /** Unmute the video. */
413
+ unmute: () => void;
414
+ /** Toggle between muted and unmuted. */
415
+ toggleMute: () => void;
416
+ }
417
+ /** Event handler callbacks bound to native `<video>` element events. */
418
+ interface ScenaVideoCallbacks {
419
+ handleLoadedMetadata: (event: Event) => void;
420
+ handlePlay: (event: Event) => void;
421
+ handlePause: (event: Event) => void;
422
+ handleSeeking: (event: Event) => void;
423
+ handleSeeked: (event: Event) => void;
424
+ handleSeekStart: (event: Event, state: ScenaVideoState) => void;
425
+ handleSeekEnd: (event: Event, state: ScenaVideoState) => Promise<void>;
426
+ handleEnded: (event: Event) => void;
427
+ handleLoadStart: (event: Event) => void;
428
+ handleLoaded: (event: Event) => void;
429
+ handleWaiting: (event: Event) => void;
430
+ handleCanPlay: (event: Event) => void;
431
+ handleTimeUpdate: (event: Event) => void;
432
+ handleVolumeChange: (event: Event) => void;
433
+ handleProgress: (event: Event) => void;
434
+ handleError: (event: Event) => void;
435
+ }
436
+ /** Full video context combining reactive data, methods, and callbacks. */
437
+ type ScenaVideoContext = ScenaVideoData & ScenaVideoMethods & ScenaVideoCallbacks;
438
+ /** Event options carrying the original DOM event. */
439
+ interface ScenaVideoEventOptionsWithEvent {
440
+ state: ScenaVideoState;
441
+ event: Event;
442
+ }
443
+ /** Event options carrying an error payload. */
444
+ interface ScenaVideoEventOptionsWithError {
445
+ state: ScenaVideoState;
446
+ error: unknown;
447
+ }
448
+ /** Discriminated union of video event option types. */
449
+ type ScenaVideoEventOptions = ScenaVideoEventOptionsWithEvent | ScenaVideoEventOptionsWithError;
450
+
451
+ declare const getScenaVideoContext: () => ScenaVideoContext;
452
+ declare const setScenaVideoContext: (context: ScenaVideoContext) => ScenaVideoContext;
453
+
454
+ /** Custom CSS class overrides for the video widget. */
455
+ interface ScenaVideoComponentClasses {
456
+ /** Classes for the wrapper `<div>`. */
457
+ root: ComponentClasses;
458
+ /** Classes for the `<video>` element. */
459
+ video: ComponentClasses;
460
+ }
461
+ /** Custom inline style overrides for the video widget. */
462
+ interface ScenaVideoComponentStyles {
463
+ /** Styles for the wrapper `<div>`. */
464
+ root: ComponentStyles;
465
+ /** Styles for the `<video>` element. */
466
+ video: ComponentStyles;
467
+ }
468
+ /** Configuration props for the `<video>` element and its wrapper. */
469
+ interface ScenaVideoProps {
470
+ id: string;
471
+ src: string;
472
+ type: string;
473
+ media: string;
474
+ poster: string;
475
+ preload: ScenaVideoPreload;
476
+ crossorigin: ScenaVideoCrossOrigin;
477
+ autoplay: boolean;
478
+ playsinline: boolean;
479
+ loop: boolean;
480
+ muted: boolean;
481
+ controls: boolean;
482
+ volume: number;
483
+ startTime: number;
484
+ customClasses: Partial<ScenaVideoComponentClasses>;
485
+ customStyles: Partial<ScenaVideoComponentStyles>;
486
+ }
487
+ /** Snippet slots for the video widget. */
488
+ interface ScenaVideoSnippets {
489
+ children: ComponentSnippet;
490
+ }
491
+ /** Options for creating the video controller. */
492
+ interface UseVideoControllerOptions {
493
+ /** Getter that returns the underlying `<video>` DOM element. */
494
+ getVideoElement: () => HTMLVideoElement;
495
+ /** Event emitter to broadcast video lifecycle events. */
496
+ eventEmitter: ScenaEventEmitter;
497
+ }
498
+ /** Return value of `useVideoController` — combines reactive data, methods, and callbacks. */
499
+ type UseVideoControllerReturns = ScenaVideoData & ScenaVideoMethods & ScenaVideoCallbacks;
500
+ /** Component ref for the video widget. */
501
+ interface ScenaVideoRef {
502
+ /** Video playback controller. */
503
+ controller: UseVideoControllerReturns;
504
+ /** Returns references to the root wrapper and video DOM elements. */
505
+ getElements: () => {
506
+ root: HTMLDivElement;
507
+ video: HTMLVideoElement;
508
+ };
509
+ }
510
+
511
+ declare function useVideoController({ getVideoElement, eventEmitter }: UseVideoControllerOptions): UseVideoControllerReturns;
512
+
513
+ /** Custom CSS class overrides for the video container. */
514
+ interface ScenaVideoContainerCustomClasses {
515
+ root: ComponentClasses;
516
+ }
517
+ /** Custom inline style overrides for the video container. */
518
+ interface ScenaVideoContainerCustomStyles {
519
+ root: ComponentStyles;
520
+ }
521
+ /** Configuration props for the video container widget. */
522
+ interface ScenaVideoContainerProps {
523
+ id: string;
524
+ /** Size of the video container. */
525
+ size: ComponentSize;
526
+ /** Shape of the video container (affects aspect ratio and border-radius). */
527
+ shape: ComponentShape;
528
+ /** ARIA attributes for accessibility. */
529
+ aria: Partial<ComponentAriaProps>;
530
+ customClasses: Partial<ScenaVideoContainerCustomClasses>;
531
+ customStyles: Partial<ScenaVideoContainerCustomStyles>;
532
+ }
533
+ /** Snippet slots for the video container. */
534
+ interface ScenaVideoContainerSnippets {
535
+ children: ComponentSnippet;
536
+ }
537
+ /** Component ref for the video container. */
538
+ interface ScenaVideoContainerRef {
539
+ getElements: () => {
540
+ root: HTMLDivElement;
541
+ };
542
+ }
543
+
544
+ /** Custom CSS class overrides for the video play/pause controls. */
545
+ interface ScenaVideoControlsComponentClasses {
546
+ root: ComponentClasses;
547
+ play: ComponentClasses;
548
+ pause: ComponentClasses;
549
+ }
550
+ /** Custom inline style overrides for the video play/pause controls. */
551
+ interface ScenaVideoControlsComponentStyles {
552
+ root: ComponentStyles;
553
+ play: ComponentStyles;
554
+ pause: ComponentStyles;
555
+ }
556
+ /** Per-button ARIA overrides for video controls. */
557
+ interface ScenaVideoControlsComponentAria {
558
+ play: Partial<ComponentAriaProps>;
559
+ pause: Partial<ComponentAriaProps>;
560
+ }
561
+ /** Configuration props for the video play/pause controls widget. */
562
+ interface ScenaVideoControlsProps {
563
+ id: string;
564
+ size: ComponentSize;
565
+ aria: Partial<ScenaVideoControlsComponentAria>;
566
+ customClasses: Partial<ScenaVideoControlsComponentClasses>;
567
+ customStyles: Partial<ScenaVideoControlsComponentStyles>;
568
+ }
569
+ /** Component ref for the video play/pause controls. */
570
+ interface ScenaVideoControlsRef {
571
+ getElements: () => {
572
+ root: HTMLDivElement | null;
573
+ pauseButton: ScenaButtonElements | undefined;
574
+ pauseIcon: ScenaIconElements | undefined;
575
+ playButton: ScenaButtonElements | undefined;
576
+ playIcon: ScenaIconElements | undefined;
577
+ };
578
+ }
579
+
580
+ /** Custom CSS class overrides for the loader spinner. */
581
+ interface ScenaLoaderCustomClasses {
582
+ root: ComponentClasses;
583
+ }
584
+ /** Custom inline style overrides for the loader spinner. */
585
+ interface ScenaLoaderCustomStyles {
586
+ root: ComponentStyles;
587
+ }
588
+ /** Configuration props for the loading spinner component. */
589
+ interface ScenaLoaderProps {
590
+ id: string;
591
+ size: ComponentSize;
592
+ customClasses: Partial<ScenaLoaderCustomClasses>;
593
+ customStyles: Partial<ScenaLoaderCustomStyles>;
594
+ }
595
+ /** DOM element references for the loader spinner. */
596
+ interface ScenaLoaderElements {
597
+ root: SVGSVGElement;
598
+ }
599
+
600
+ /** Custom CSS class overrides for the video loader widget. */
601
+ interface ScenaVideoLoaderComponentClasses {
602
+ root: ComponentClasses;
603
+ loader: ComponentClasses;
604
+ }
605
+ /** Custom inline style overrides for the video loader widget. */
606
+ interface ScenaVideoLoaderComponentStyles {
607
+ root: ComponentStyles;
608
+ loader: ComponentStyles;
609
+ }
610
+ /** Configuration props for the video buffering/loading indicator. */
611
+ interface ScenaVideoLoaderProps {
612
+ id: string;
613
+ size: ComponentSize;
614
+ customClasses: Partial<ScenaVideoLoaderComponentClasses>;
615
+ customStyles: Partial<ScenaVideoLoaderComponentStyles>;
616
+ }
617
+ /** Component ref for the video loader. */
618
+ interface ScenaVideoLoaderRef {
619
+ getElements: () => {
620
+ root: HTMLDivElement;
621
+ loader: ScenaLoaderElements | undefined;
622
+ };
623
+ }
624
+
625
+ declare enum ScenaVideoProgressVariant {
626
+ LINE = "line",
627
+ CIRCLE = "circle"
628
+ }
629
+
630
+ declare const scenaProgressLineThicknessMap: ScenaProgressComponentThickness;
631
+ declare const scenaProgressCircleThicknessMap: ScenaProgressComponentThickness;
632
+
633
+ /** Thickness values for the progress indicator in default and hover states. */
634
+ interface ScenaProgressThickness {
635
+ default: number;
636
+ hover: number;
637
+ }
638
+ /** Maps each component size to its progress thickness settings. */
639
+ type ScenaProgressComponentThickness = Record<ComponentSize, ScenaProgressThickness>;
640
+ /** Custom CSS class overrides for the circular progress indicator. */
641
+ interface ScenaProgressCircleComponentClasses {
642
+ root: ComponentClasses;
643
+ track: ComponentClasses;
644
+ buffer: ComponentClasses;
645
+ progress: ComponentClasses;
646
+ }
647
+ /** Custom inline style overrides for the circular progress indicator. */
648
+ interface ScenaProgressCircleComponentStyles {
649
+ root: ComponentStyles;
650
+ track: ComponentStyles;
651
+ buffer: ComponentStyles;
652
+ progress: ComponentStyles;
653
+ }
654
+ /** Configuration props for the circular progress indicator. */
655
+ interface ScenaProgressCircleProps {
656
+ id: string;
657
+ size: ComponentSize;
658
+ buffer: number;
659
+ progress: number;
660
+ hasBuffer: boolean;
661
+ aria: Partial<ComponentAriaProps>;
662
+ customThickness: Partial<ScenaProgressComponentThickness>;
663
+ customClasses: Partial<ScenaProgressCircleComponentClasses>;
664
+ customStyles: Partial<ScenaProgressCircleComponentStyles>;
665
+ }
666
+ /** Seek event callbacks for the circular progress indicator. */
667
+ interface ScenaProgressCircleEvents {
668
+ onSeek: (progress: number, event: Event) => void;
669
+ onSeekStart?: (event: Event) => void;
670
+ onSeekEnd?: (event: Event) => void;
671
+ }
672
+ /** Custom CSS class overrides for the linear progress bar. */
673
+ interface ScenaProgressLineComponentClasses {
674
+ root: ComponentClasses;
675
+ track: ComponentClasses;
676
+ buffer: ComponentClasses;
677
+ progress: ComponentClasses;
678
+ }
679
+ /** Custom inline style overrides for the linear progress bar. */
680
+ interface ScenaProgressLineComponentStyles {
681
+ root: ComponentStyles;
682
+ track: ComponentStyles;
683
+ buffer: ComponentStyles;
684
+ progress: ComponentStyles;
685
+ }
686
+ /** Configuration props for the linear progress bar. */
687
+ interface ScenaProgressLineProps {
688
+ id: string;
689
+ size: ComponentSize;
690
+ buffer: number;
691
+ progress: number;
692
+ hasBuffer: boolean;
693
+ customThickness: Partial<ScenaProgressComponentThickness>;
694
+ customClasses: Partial<ScenaProgressLineComponentClasses>;
695
+ customStyles: Partial<ScenaProgressLineComponentStyles>;
696
+ aria: Partial<ComponentAriaProps>;
697
+ }
698
+ /** Seek event callbacks for the linear progress bar. */
699
+ interface ScenaProgressLineEvents {
700
+ onSeek: (progress: number, event: Event) => void;
701
+ onSeekStart?: (event: Event) => void;
702
+ onSeekEnd?: (event: Event) => void;
703
+ }
704
+ /** DOM event handlers bound by the line progress hook. */
705
+ interface UseProgressLineReturnEvents {
706
+ onpointerup: (event: PointerEvent) => void;
707
+ onpointermove: (event: PointerEvent) => void;
708
+ onpointerdown: (event: PointerEvent) => void;
709
+ onpointercancel: (event: PointerEvent) => void;
710
+ onmouseenter: () => void;
711
+ onmouseleave: () => void;
712
+ }
713
+ /** Reactive state returned by the line progress hook. */
714
+ interface UseProgressLineReturn {
715
+ isFocused: boolean;
716
+ isDragging: boolean;
717
+ isDisabledTransition: boolean;
718
+ thickness: number;
719
+ transition: string | undefined;
720
+ events: UseProgressLineReturnEvents;
721
+ }
722
+ /** Props accepted by the line progress hook. */
723
+ interface UseProgressLineProps {
724
+ getRootElement: () => HTMLElement;
725
+ getSize: () => ComponentSize;
726
+ getCustomThickness: () => ScenaProgressComponentThickness;
727
+ getProgress: () => number;
728
+ }
729
+ /** Seek event callbacks used internally by the line progress hook. */
730
+ interface UseProgressLineEvents {
731
+ onSeek: (progress: number, event: Event) => void;
732
+ onSeekStart: (event: Event) => void;
733
+ onSeekEnd: (event: Event) => void;
734
+ }
735
+ /** Props accepted by the circle progress hook. */
736
+ interface UseProgressCircleProps {
737
+ getRootElement: () => SVGSVGElement;
738
+ getSize: () => ComponentSize;
739
+ getCustomThickness: () => ScenaProgressComponentThickness;
740
+ getProgress: () => number;
741
+ getBuffer: () => number;
742
+ }
743
+ /** Seek event callbacks used internally by the circle progress hook. */
744
+ interface UseProgressCircleEvents {
745
+ onSeek: (progress: number, event: Event) => void;
746
+ onSeekStart: (event: Event) => void;
747
+ onSeekEnd: (event: Event) => void;
748
+ }
749
+ /** DOM event handlers bound by the circle progress hook. */
750
+ interface UseProgressCircleReturnEvents {
751
+ onclick: (event: MouseEvent) => void;
752
+ onpointerdown: (event: PointerEvent) => void;
753
+ onpointermove: (event: PointerEvent) => void;
754
+ onpointerup: (event: PointerEvent) => void;
755
+ onpointercancel: (event: PointerEvent) => void;
756
+ onmouseenter: () => void;
757
+ onmouseleave: () => void;
758
+ }
759
+ /** DOM element references for the linear progress bar. */
760
+ interface ScenaProgressLineElements {
761
+ root: HTMLDivElement;
762
+ track: HTMLDivElement;
763
+ buffer: HTMLDivElement | null;
764
+ progress: HTMLDivElement;
765
+ }
766
+ /** DOM element references for the circular progress indicator. */
767
+ interface ScenaProgressCircleElements {
768
+ root: SVGSVGElement;
769
+ track: SVGCircleElement | null;
770
+ buffer: SVGCircleElement | null;
771
+ progress: SVGCircleElement | null;
772
+ }
773
+ /** Reactive state returned by the circle progress hook. */
774
+ interface UseProgressCircleReturn {
775
+ isFocused: boolean;
776
+ isDragging: boolean;
777
+ radialSize: number;
778
+ radialRadius: number;
779
+ radialCircumference: number;
780
+ radialProgressOffset: number;
781
+ radialBufferOffset: number;
782
+ thickness: number;
783
+ hitAreaThickness: number;
784
+ transition: string | undefined;
785
+ events: UseProgressCircleReturnEvents;
786
+ }
787
+
788
+ declare function useProgressLine({ getRootElement, getSize, getProgress, getCustomThickness, onSeek, onSeekStart, onSeekEnd }: UseProgressLineProps & Partial<UseProgressLineEvents>): UseProgressLineReturn;
789
+
790
+ declare function useProgressCircle({ getRootElement, getSize, getBuffer, getProgress, getCustomThickness, onSeek, onSeekStart, onSeekEnd }: UseProgressCircleProps & Partial<UseProgressCircleEvents>): UseProgressCircleReturn;
791
+
792
+ /** Custom CSS class overrides for the video progress bar. */
793
+ interface ScenaVideoProgressComponentClasses {
794
+ root: ComponentClasses;
795
+ track: ComponentClasses;
796
+ progress: ComponentClasses;
797
+ buffered: ComponentClasses;
798
+ }
799
+ /** Custom inline style overrides for the video progress bar. */
800
+ interface ScenaVideoProgressComponentStyles {
801
+ root: ComponentStyles;
802
+ track: ComponentStyles;
803
+ progress: ComponentStyles;
804
+ buffered: ComponentStyles;
805
+ }
806
+ /** Thickness values for the progress bar in default and hover states. */
807
+ interface ScenaVideoProgressThickness {
808
+ default: number;
809
+ hover: number;
810
+ }
811
+ /** Maps each component size to its progress thickness values. */
812
+ type ScenaVideoProgressThicknessMap = Record<ComponentSize, ScenaVideoProgressThickness>;
813
+ /** Thickness config per progress variant (line/circle) and size. */
814
+ type ScenaVideoProgressComponentThickness = Record<ScenaVideoProgressVariant, ScenaVideoProgressThicknessMap>;
815
+ /** Configuration props for the video progress widget. */
816
+ interface ScenaVideoProgressProps {
817
+ id: string;
818
+ size: ComponentSize;
819
+ shape: ComponentShape;
820
+ hasBuffer: boolean;
821
+ aria: Partial<ComponentAriaProps>;
822
+ customThickness: Partial<ScenaVideoProgressComponentThickness>;
823
+ customClasses: Partial<ScenaVideoProgressComponentClasses>;
824
+ customStyles: Partial<ScenaVideoProgressComponentStyles>;
825
+ }
826
+ /** Component ref for the video progress bar. */
827
+ interface ScenaVideoProgressRef {
828
+ getElements: () => ScenaProgressLineElements | ScenaProgressCircleElements | null;
829
+ }
830
+
831
+ /** Custom CSS class overrides for the volume mute/unmute controls. */
832
+ interface ScenaVideoVolumeComponentClasses {
833
+ root: ComponentClasses;
834
+ mute: ComponentClasses;
835
+ unmute: ComponentClasses;
836
+ }
837
+ /** Custom inline style overrides for the volume mute/unmute controls. */
838
+ interface ScenaVideoVolumeComponentStyles {
839
+ root: ComponentStyles;
840
+ mute: ComponentStyles;
841
+ unmute: ComponentStyles;
842
+ }
843
+ /** Per-button ARIA overrides for volume controls. */
844
+ interface ScenaVideoVolumeComponentAria {
845
+ mute: Partial<ComponentAriaProps>;
846
+ unmute: Partial<ComponentAriaProps>;
847
+ }
848
+ /** Configuration props for the volume control widget. */
849
+ interface ScenaVideoVolumeProps {
850
+ id: string;
851
+ size: ComponentSize;
852
+ shape: ComponentShape;
853
+ aria: Partial<ScenaVideoVolumeComponentAria>;
854
+ customClasses: Partial<ScenaVideoVolumeComponentClasses>;
855
+ customStyles: Partial<ScenaVideoVolumeComponentStyles>;
856
+ }
857
+ /** Component ref for the volume control widget. */
858
+ interface ScenaVideoVolumeRef {
859
+ getElements: () => {
860
+ root: HTMLDivElement | null;
861
+ unmuteButton: ScenaButtonElements | undefined;
862
+ unmuteIcon: ScenaIconElements | undefined;
863
+ muteButton: ScenaButtonElements | undefined;
864
+ muteIcon: ScenaIconElements | undefined;
865
+ };
866
+ }
867
+
868
+ /** Return value of {@link useScenaOverrides}. */
869
+ interface UseScenaOverridesReturns {
870
+ /** The resolved config with all override layers applied (reactive). */
871
+ resolved: ScenaConfig;
872
+ /** Compute and return the resolved config snapshot. */
873
+ resolve: () => ScenaConfig;
874
+ /** Set an override factory function for a named layer, or `null` to clear that layer. */
875
+ set: (layer: OverrideLayer, value: (() => Partial<ScenaConfig>) | null) => void;
876
+ }
877
+
878
+ /** Public API for controlling preview mode at runtime. */
879
+ interface ScenaPreviewApi {
880
+ /** Whether preview mode is currently active. */
881
+ isPreviewing: boolean;
882
+ /** Whether video position is preserved when expanding from preview. */
883
+ isKeepTimeOnExpand: boolean;
884
+ /** Whether mute state is preserved when expanding from preview. */
885
+ isKeepMuteOnExpand: boolean;
886
+ /** Activate preview mode, applying preview overrides. */
887
+ start: () => void;
888
+ /** Deactivate preview mode, removing preview overrides. */
889
+ stop: () => void;
890
+ }
891
+ /** Return value of {@link useScenaPreview}. */
892
+ interface UseScenaPreviewReturns {
893
+ /** Apply initial preview state from config. */
894
+ apply: () => void;
895
+ /** Reactive public API for controlling preview mode. */
896
+ api: ScenaPreviewApi;
897
+ }
898
+ /** Behavioral options for preview mode. */
899
+ interface ScenaPreviewBehavior {
900
+ /** When true, preserves video playback position when expanding from preview. */
901
+ keepTimeOnExpand: boolean;
902
+ /** When true, preserves mute state when expanding from preview. */
903
+ keepMuteOnExpand: boolean;
904
+ }
905
+ /** Preview config — same shape as {@link ScenaOverrides}. */
906
+ type ScenaPreviewConfig = ScenaOverrides & ScenaPreviewBehavior;
907
+ /** Options for constructing the preview feature. */
908
+ interface UseScenaPreviewOptions {
909
+ config: UseScenaConfigReturns;
910
+ configOverrides: UseScenaOverridesReturns;
911
+ }
912
+
913
+ /** Public API for the responsive feature. */
914
+ interface ScenaResponsiveApi {
915
+ /** The currently active breakpoint (max-width in px), or `null` if none matched. */
916
+ activeBreakpoint: number | null;
917
+ }
918
+ /** Return value of {@link useScenaResponsive}. */
919
+ interface UseScenaResponsiveReturns {
920
+ /** Set up matchMedia listeners and apply the initial breakpoint. */
921
+ apply: () => void;
922
+ /** Remove all listeners and clear responsive overrides. */
923
+ destroy: () => void;
924
+ /** Reactive responsive API. */
925
+ api: ScenaResponsiveApi;
926
+ }
927
+ /** Responsive config — object of breakpoints mapped to partial overrides. */
928
+ type ScenaResponsiveConfig = Record<number, Partial<ScenaOverrides>>;
929
+
930
+ /** Return value of {@link useScenaVisibility}. */
931
+ interface UseScenaVisibilityReturns {
932
+ /** Apply initial visibility state from config defaults. */
933
+ apply: () => void;
934
+ /** Reactive public API for controlling widget visibility. */
935
+ api: ScenaVisibilityApi;
936
+ }
937
+ /** Public API for controlling widget visibility at runtime. */
938
+ interface ScenaVisibilityApi {
939
+ /** Whether the widget is currently hidden. */
940
+ isHidden: boolean;
941
+ /** Whether the widget should auto-show when the video is ready. */
942
+ isShownOnReady: boolean;
943
+ /** Show the widget (set `isHidden` to `false`). */
944
+ show: () => void;
945
+ /** Hide the widget (set `isHidden` to `true`). */
946
+ hide: () => void;
947
+ }
948
+ /** Visibility feature configuration options. */
949
+ interface ScenaVisibilityConfig {
950
+ /** Start the widget in a hidden state. */
951
+ isHidden?: boolean;
952
+ /** Enable CSS animations for show/hide transitions. */
953
+ isAnimated?: boolean;
954
+ /** Automatically show the widget when the video is ready. Defaults to `true`. */
955
+ isShownOnReady?: boolean;
956
+ }
957
+
958
+ /** Per-component property overrides. Pass `false` to disable a component entirely. */
959
+ interface ScenaOverrides {
960
+ size: ComponentSize;
961
+ shape: ComponentShape;
962
+ container: Partial<ScenaContainerProps>;
963
+ video: Partial<ScenaVideoProps> & Pick<ScenaVideoProps, 'src'>;
964
+ videoContainer: Partial<ScenaVideoContainerProps>;
965
+ videoLoader: Partial<ScenaVideoLoaderProps> | false;
966
+ videoProgress: Partial<ScenaVideoProgressProps> | false;
967
+ videoControls: Partial<ScenaVideoControlsProps> | false;
968
+ videoVolume: Partial<ScenaVideoVolumeProps> | false;
969
+ closeButton: Partial<ScenaCloseButtonProps> | false;
970
+ ctaButton: Partial<ScenaCtaButtonProps> | false;
971
+ }
972
+ /** Component override config. All overrides are optional except `video` which requires at least `src`. */
973
+ type ScenaConfigOverrides = Partial<ScenaOverrides> & Pick<ScenaOverrides, 'video'>;
974
+ /** Feature-specific sections of the widget config. */
975
+ interface ScenaFeatures {
976
+ preview: Partial<ScenaPreviewConfig>;
977
+ visibility: Partial<ScenaVisibilityConfig>;
978
+ responsive: ScenaResponsiveConfig;
979
+ }
980
+ /** Optional feature config. All feature sections are optional at the top level. */
981
+ type ScenaConfigFeatures = Partial<ScenaFeatures>;
982
+ /** Root configuration object accepted by `scena.mount()`. */
983
+ type ScenaConfig = ScenaConfigOverrides & ScenaConfigFeatures;
984
+ /** Reactive config store returned by {@link useScenaConfig}. */
985
+ interface UseScenaConfigReturns {
986
+ /** Current resolved config snapshot. */
987
+ current: ScenaConfig;
988
+ /** Returns the current config object. */
989
+ getConfig: () => ScenaConfig;
990
+ /** Replaces the entire config with a new value. */
991
+ setConfig: (value: ScenaConfig) => void;
992
+ /** Deeply merges a partial config into the current one. */
993
+ mergeConfig: (partial: Partial<ScenaConfig>) => void;
994
+ }
995
+
996
+ /** Mount target — a regular DOM element or a Shadow DOM root. */
997
+ type ScenaTarget = HTMLElement | ShadowRoot;
998
+ /** Handle returned after mounting; provides runtime access to the widget. */
999
+ interface ScenaInstance {
1000
+ /** Public widget API (e.g. play, pause, destroy). */
1001
+ api: ScenaApi;
1002
+ /** Reference to the mounted Svelte component. */
1003
+ component: ScenaRef;
1004
+ /** Reactive config store for reading and updating the widget config. */
1005
+ config: UseScenaConfigReturns;
1006
+ /** Preview feature API (start, stop, isPreviewing). */
1007
+ preview: ScenaPreviewApi;
1008
+ /** Responsive feature API (activeBreakpoint). */
1009
+ responsive: ScenaResponsiveApi;
1010
+ /** Visibility feature API (show, hide, isHidden). */
1011
+ visibility: ScenaVisibilityApi;
1012
+ }
1013
+ /** Registry of all component refs within a mounted scena widget. Nullable refs correspond to optional components. */
1014
+ interface ScenaComponents {
1015
+ container: ScenaContainerRef;
1016
+ video: ScenaVideoRef;
1017
+ videoContainer: ScenaVideoContainerRef;
1018
+ videoLoader: ScenaVideoLoaderRef | null;
1019
+ videoProgress: ScenaVideoProgressRef | null;
1020
+ videoControls: ScenaVideoControlsRef | null;
1021
+ videoVolume: ScenaVideoVolumeRef | null;
1022
+ closeButton: ScenaCloseButtonRef | null;
1023
+ ctaButton: ScenaCtaButtonRef | null;
1024
+ }
1025
+ /** Top-level API returned by {@link useScena}. */
1026
+ interface UseScenaReturns {
1027
+ /** Library name. */
1028
+ NAME: string;
1029
+ /** Library version. */
1030
+ VERSION: string;
1031
+ /** Mount the widget into a target element with the given config. */
1032
+ mount: (config: ScenaConfig, target?: ScenaTarget) => Promise<ScenaInstance>;
1033
+ /** Unmount a previously mounted widget instance. */
1034
+ unmount: (instance: ScenaInstance) => Promise<void>;
1035
+ }
1036
+ /** Internal props passed to the root Scena Svelte component. */
1037
+ interface ScenaProps {
1038
+ /** Resolved widget config (with overrides applied). */
1039
+ config: ScenaConfig;
1040
+ /** Shared event bus created by the factory. */
1041
+ eventEmitter: ScenaEventEmitter;
1042
+ /** Callback invoked when the component is mounted. */
1043
+ mount: () => void;
1044
+ /** Callback invoked when the component requests unmount. */
1045
+ unmount: () => void;
1046
+ }
1047
+ /** Top-level API surface exposed by a mounted scena widget. */
1048
+ interface ScenaApi {
1049
+ /** Video playback controller (play, pause, seek, volume, etc.). */
1050
+ controller: UseVideoControllerReturns;
1051
+ /** References to all child component instances. */
1052
+ components: ScenaComponents;
1053
+ /** Pub/sub event bus for widget events. */
1054
+ events: ScenaEventEmitter;
1055
+ }
1056
+ /** Reference to the root Scena Svelte component. */
1057
+ interface ScenaRef {
1058
+ /** Top-level widget API. */
1059
+ api: ScenaApi;
1060
+ }
1061
+
1062
+ /**
1063
+ * Creates a scena widget factory.
1064
+ *
1065
+ * Returns an object with `mount` and `unmount` methods
1066
+ * for managing the widget lifecycle in the DOM.
1067
+ *
1068
+ * @example
1069
+ * ```ts
1070
+ * const scena = useScena();
1071
+ * const instance = await scena.mount({ video: { src: 'video.mp4' } });
1072
+ * // later...
1073
+ * await scena.unmount(instance);
1074
+ * ```
1075
+ */
1076
+ declare function useScena(): UseScenaReturns;
1077
+
1078
+ /**
1079
+ * Creates a reactive config store for the scena widget.
1080
+ *
1081
+ * Provides getter, setter, and deep-merge methods for managing
1082
+ * the widget configuration at runtime.
1083
+ *
1084
+ * @param initial - The initial widget configuration.
1085
+ * @returns A reactive config store with `current`, `getConfig`, `setConfig`, and `mergeConfig`.
1086
+ */
1087
+ declare function useScenaConfig(initial: ScenaConfig): UseScenaConfigReturns;
1088
+
1089
+ /**
1090
+ * Manages runtime config overrides via named layers and a deep-merge strategy.
1091
+ *
1092
+ * Each layer is identified by name and merged in a fixed order
1093
+ * (responsive → preview), so higher-priority layers always win.
1094
+ *
1095
+ * @param config - The reactive config store to overlay overrides on.
1096
+ * @returns A reactive `resolved` config and methods to `set`/`resolve` overrides.
1097
+ */
1098
+ declare function useScenaOverrides(config: UseScenaConfigReturns): UseScenaOverridesReturns;
1099
+
1100
+ /**
1101
+ * Manages the preview mode feature for the scena widget.
1102
+ *
1103
+ * When active, applies preview-specific config overrides (e.g. preview styles)
1104
+ * on top of the base config. Stops preview on video container click.
1105
+ *
1106
+ * @param config - The reactive config store.
1107
+ * @param configOverrides - The config overrides manager.
1108
+ * @param eventEmitter - The shared event bus for emitting preview events.
1109
+ * @returns Methods to apply/start/stop preview and a reactive API.
1110
+ */
1111
+ declare function useScenaPreview(config: UseScenaConfigReturns, configOverrides: UseScenaOverridesReturns, eventEmitter: ScenaEventEmitter): UseScenaPreviewReturns;
1112
+
1113
+ /**
1114
+ * Manages the show/hide visibility feature for the scena widget.
1115
+ *
1116
+ * Reads initial visibility settings from config and provides
1117
+ * `show`/`hide` methods to toggle the widget at runtime.
1118
+ *
1119
+ * @param config - The reactive config store.
1120
+ * @param eventEmitter - The shared event bus for emitting visibility events.
1121
+ * @returns Methods to apply initial state, and a reactive visibility API.
1122
+ */
1123
+ declare function useScenaVisibility(config: UseScenaConfigReturns, eventEmitter: ScenaEventEmitter): UseScenaVisibilityReturns;
1124
+
1125
+ /**
1126
+ * Manages responsive breakpoint overrides for the scena widget.
1127
+ *
1128
+ * Listens to viewport width changes via `matchMedia` and applies
1129
+ * the matching breakpoint's component overrides as a named layer
1130
+ * in the overrides system (below preview priority).
1131
+ *
1132
+ * @param config - The reactive config store.
1133
+ * @param configOverrides - The config overrides manager.
1134
+ * @returns Methods to apply/destroy and a reactive API with activeBreakpoint.
1135
+ */
1136
+ declare function useScenaResponsive(config: UseScenaConfigReturns, configOverrides: UseScenaOverridesReturns): UseScenaResponsiveReturns;
1137
+
1138
+ /**
1139
+ * Returns the custom element constructor if it has already been registered.
1140
+ *
1141
+ * @returns The registered `CustomElementConstructor`, or `undefined` if not yet defined.
1142
+ */
1143
+ declare function getScenaElement(): CustomElementConstructor | undefined;
1144
+ /**
1145
+ * Registers the `<scena-video-widget>` custom element in the browser.
1146
+ *
1147
+ * Safe to call multiple times — skips registration if the element is already defined.
1148
+ */
1149
+ declare function defineScenaElement(): void;
1150
+
1151
+ /** The HTML tag name used for the scena custom element. */
1152
+ type ScenaElementTag = 'scena-video-widget';
1153
+
1154
+ /**
1155
+ * SSR-safe `HTMLElement` constructor.
1156
+ *
1157
+ * On the server `HTMLElement` is undefined, which would throw at module
1158
+ * evaluation time when used as a base class. Falling back to an empty stub
1159
+ * lets the module be imported in SSR environments (Nuxt, Next, etc.) without
1160
+ * forcing consumers to client-only the import itself.
1161
+ */
1162
+ declare const SAFE_HTML_ELEMENT: typeof HTMLElement;
1163
+
1164
+ /**
1165
+ * Custom HTML element that wraps the scena video widget.
1166
+ *
1167
+ * Register via {@link defineScenaElement}, then use as `<scena-video-widget>` in HTML.
1168
+ * Dispatches `scena:mount` and `scena:unmount` custom events on the element.
1169
+ *
1170
+ * @example
1171
+ * ```ts
1172
+ * defineScenaElement();
1173
+ * const el = document.createElement('scena-video-widget');
1174
+ * document.body.appendChild(el);
1175
+ * const instance = await el.mount({ video: { src: 'video.mp4' } });
1176
+ * ```
1177
+ */
1178
+ declare class ScenaElement extends SAFE_HTML_ELEMENT {
1179
+ static readonly tagName: "scena-video-widget";
1180
+ private _instance;
1181
+ private _scena;
1182
+ private _connected;
1183
+ /** Mount promise; concurrent calls share this instead of racing. */
1184
+ private _mountPending;
1185
+ /** Unmount promise; concurrent calls share this instead of racing. */
1186
+ private _unmountPending;
1187
+ /** The scena factory used to create and destroy the widget. */
1188
+ get scena(): UseScenaReturns | null;
1189
+ /** The mounted widget instance, or `null` if not yet mounted. */
1190
+ get instance(): ScenaInstance | null;
1191
+ connectedCallback(): void;
1192
+ disconnectedCallback(): void;
1193
+ /**
1194
+ * Mounts the scena widget inside this custom element.
1195
+ *
1196
+ * If already mounted, updates the config instead.
1197
+ * If a mount or unmount is in flight, waits for it before proceeding —
1198
+ * concurrent calls share the same promise instead of racing.
1199
+ * Dispatches a `scena:mount` CustomEvent with the instance as `detail`.
1200
+ *
1201
+ * @param config - Widget configuration.
1202
+ * @returns A promise resolving with the {@link ScenaInstance}.
1203
+ */
1204
+ mount(config: ScenaConfig): Promise<ScenaInstance>;
1205
+ private _mount;
1206
+ /**
1207
+ * Unmounts the scena widget and dispatches a `scena:unmount` event.
1208
+ * No-op if the widget is not currently mounted.
1209
+ * Concurrent calls share the same in-flight promise.
1210
+ */
1211
+ unmount(): Promise<void>;
1212
+ private _unmount;
1213
+ }
1214
+
1215
+ /** Svelte context shared across all scena child components. */
1216
+ interface ScenaContext {
1217
+ /** Widget-wide event bus. */
1218
+ eventEmitter: ScenaEventEmitter;
1219
+ /** Trigger the component mount lifecycle. */
1220
+ mount: () => void;
1221
+ /** Trigger the component unmount lifecycle. */
1222
+ unmount: () => void;
1223
+ }
1224
+
1225
+ /**
1226
+ * Svelte context pair for sharing {@link ScenaContext} across the component tree.
1227
+ *
1228
+ * - `getScenaContext` — retrieve the context in a child component.
1229
+ * - `setScenaContext` — provide the context in a parent component.
1230
+ */
1231
+ declare const getScenaContext: () => ScenaContext;
1232
+ declare const setScenaContext: (context: ScenaContext) => ScenaContext;
1233
+
1234
+ export { ComponentAriaHaspopup, ComponentAriaPressed, ComponentPlacement, ComponentPosition, ComponentShape, ComponentSize, OverrideLayer, ScenaButtonAriaHaspopup, ScenaButtonAriaPressed, ScenaButtonShape, ScenaButtonType, ScenaButtonVariant, ScenaCtaButtonPlacement, ScenaElement, ScenaEvent, ScenaVideoCrossOrigin, ScenaVideoPreload, ScenaVideoProgressVariant, ScenaVideoState, defineScenaElement, getScenaContext, getScenaElement, getScenaVideoContext, scenaProgressCircleThicknessMap, scenaProgressLineThicknessMap, setScenaContext, setScenaVideoContext, useEventEmitter, useProgressCircle, useProgressLine, useScena, useScenaConfig, useScenaOverrides, useScenaPreview, useScenaResponsive, useScenaVisibility, useVideoController };
1235
+ export type { ComponentAriaProps, ComponentClasses, ComponentSnippet, ComponentSnippetReturn, ComponentStyles, ScenaApi, ScenaButtonComponentClasses, ScenaButtonComponentStyles, ScenaButtonElements, ScenaButtonEvents, ScenaButtonProps, ScenaButtonSnippets, ScenaCloseButtonComponentClasses, ScenaCloseButtonComponentStyles, ScenaCloseButtonProps, ScenaCloseButtonRef, ScenaComponents, ScenaConfig, ScenaConfigFeatures, ScenaConfigOverrides, ScenaContainerCustomClasses, ScenaContainerCustomStyles, ScenaContainerProps, ScenaContainerRef, ScenaContainerSnippets, ScenaContext, ScenaCtaButtonAdaptive, ScenaCtaButtonComponentClasses, ScenaCtaButtonComponentStyles, ScenaCtaButtonProps, ScenaCtaButtonRef, ScenaElementTag, ScenaEventEmitter, ScenaEventHandler, ScenaEventMap, ScenaFeatures, ScenaIconCustomClasses, ScenaIconCustomStyles, ScenaIconElements, ScenaIconProps, ScenaIconSnippets, ScenaInstance, ScenaLoaderCustomClasses, ScenaLoaderCustomStyles, ScenaLoaderElements, ScenaLoaderProps, ScenaOverrides, ScenaPreviewApi, ScenaPreviewConfig, ScenaProgressCircleComponentClasses, ScenaProgressCircleComponentStyles, ScenaProgressCircleElements, ScenaProgressCircleEvents, ScenaProgressCircleProps, ScenaProgressComponentThickness, ScenaProgressLineComponentClasses, ScenaProgressLineComponentStyles, ScenaProgressLineElements, ScenaProgressLineEvents, ScenaProgressLineProps, ScenaProgressThickness, ScenaProps, ScenaRef, ScenaResponsiveApi, ScenaResponsiveConfig, ScenaTarget, ScenaVideoCallbacks, ScenaVideoComponentClasses, ScenaVideoComponentStyles, ScenaVideoContainerCustomClasses, ScenaVideoContainerCustomStyles, ScenaVideoContainerProps, ScenaVideoContainerRef, ScenaVideoContainerSnippets, ScenaVideoContext, ScenaVideoControlsComponentAria, ScenaVideoControlsComponentClasses, ScenaVideoControlsComponentStyles, ScenaVideoControlsProps, ScenaVideoControlsRef, ScenaVideoData, ScenaVideoEventOptions, ScenaVideoEventOptionsWithError, ScenaVideoEventOptionsWithEvent, ScenaVideoLoaderComponentClasses, ScenaVideoLoaderComponentStyles, ScenaVideoLoaderProps, ScenaVideoLoaderRef, ScenaVideoMethods, ScenaVideoProgressComponentClasses, ScenaVideoProgressComponentStyles, ScenaVideoProgressComponentThickness, ScenaVideoProgressProps, ScenaVideoProgressRef, ScenaVideoProgressThickness, ScenaVideoProgressThicknessMap, ScenaVideoProps, ScenaVideoRef, ScenaVideoSnippets, ScenaVideoVolumeComponentAria, ScenaVideoVolumeComponentClasses, ScenaVideoVolumeComponentStyles, ScenaVideoVolumeProps, ScenaVideoVolumeRef, ScenaVisibilityApi, ScenaVisibilityConfig, UseProgressCircleEvents, UseProgressCircleProps, UseProgressCircleReturn, UseProgressCircleReturnEvents, UseProgressLineEvents, UseProgressLineProps, UseProgressLineReturn, UseProgressLineReturnEvents, UseScenaConfigReturns, UseScenaOverridesReturns, UseScenaPreviewOptions, UseScenaPreviewReturns, UseScenaResponsiveReturns, UseScenaReturns, UseScenaVisibilityReturns, UseVideoControllerOptions, UseVideoControllerReturns };