@clockworkdog/cogs-client 3.0.0-alpha.1 → 3.0.0-alpha.10

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export type { default as MediaObjectFit } from './types/MediaObjectFit';
 export * as MediaSchema from './types/MediaSchema';
 export { default as CogsAudioPlayer } from './AudioPlayer';
 export { default as CogsVideoPlayer } from './VideoPlayer';
+export { SurfaceManager } from './state-based/SurfaceManager';
 export * from './types/AudioState';
 export { assetUrl, preloadUrl } from './utils/urls';
 export { getStateAtTime } from './utils/getStateAtTime';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from './CogsConnection';
 export * as MediaSchema from './types/MediaSchema';
 export { default as CogsAudioPlayer } from './AudioPlayer';
 export { default as CogsVideoPlayer } from './VideoPlayer';
+export { SurfaceManager } from './state-based/SurfaceManager';
 export * from './types/AudioState';
 export { assetUrl, preloadUrl } from './utils/urls';
 export { getStateAtTime } from './utils/getStateAtTime';

package/dist/state-based/MediaClipManager.d.ts

@@ -0,0 +1,45 @@
+import { AudialProperties, AudioState, ImageMetadata, ImageState, MediaClipState, TemporalProperties, VideoState, VisualProperties } from '../types/MediaSchema';
+import { MediaPreloader } from './MediaPreloader';
+/**
+ * Each instance of a MediaClipManager is responsible for displaying
+ * an image/audio/video clip in the correct state.
+ */
+export declare abstract class MediaClipManager<T extends MediaClipState> {
+    private surfaceElement;
+    protected clipElement: HTMLElement;
+    protected constructAssetURL: (file: string) => string;
+    protected mediaPreloader: MediaPreloader;
+    constructor(surfaceElement: HTMLElement, clipElement: HTMLElement, state: T, constructAssetURL: (file: string) => string, mediaPreloader: MediaPreloader);
+    protected abstract update(): void;
+    abstract destroy(): void;
+    isConnected(element?: HTMLElement): boolean;
+    protected _state: T;
+    setState(newState: T): void;
+    private timeout;
+    private loop;
+}
+export declare function assertElement(mediaElement: HTMLElement | undefined, parentElement: HTMLElement, clip: MediaClipState, constructAssetURL: (file: string) => string, preloader: MediaPreloader): HTMLElement;
+export declare function assertVisualProperties(mediaElement: HTMLMediaElement | HTMLImageElement, properties: VisualProperties, objectFit: ImageMetadata['fit']): void;
+export declare function assertAudialProperties(mediaElement: HTMLMediaElement, properties: AudialProperties, sinkId: string): void;
+interface TemporalSyncState {
+    state: 'idle' | 'seeking' | 'intercepting';
+}
+export declare function assertTemporalProperties(mediaElement: HTMLMediaElement, properties: TemporalProperties, keyframes: VideoState['keyframes'], syncState: TemporalSyncState): TemporalSyncState;
+export declare class ImageManager extends MediaClipManager<ImageState> {
+    private imageElement;
+    protected update(): void;
+    destroy(): void;
+}
+export declare class AudioManager extends MediaClipManager<AudioState> {
+    private syncState;
+    private audioElement;
+    protected update(): void;
+    destroy(): void;
+}
+export declare class VideoManager extends MediaClipManager<VideoState> {
+    private syncState;
+    private videoElement?;
+    protected update(): void;
+    destroy(): void;
+}
+export {};

package/dist/state-based/MediaClipManager.js

@@ -0,0 +1,261 @@
+import { getStateAtTime } from '../utils/getStateAtTime';
+/**
+ * Each instance of a MediaClipManager is responsible for displaying
+ * an image/audio/video clip in the correct state.
+ */
+export class MediaClipManager {
+    surfaceElement;
+    clipElement;
+    constructAssetURL;
+    mediaPreloader;
+    constructor(surfaceElement, clipElement, state, constructAssetURL, mediaPreloader) {
+        this.surfaceElement = surfaceElement;
+        this.clipElement = clipElement;
+        this.constructAssetURL = constructAssetURL;
+        this.mediaPreloader = mediaPreloader;
+        this._state = state;
+        // Allow the class to be constructed, then call the loop
+        setTimeout(this.loop);
+    }
+    isConnected(element) {
+        if (!this.surfaceElement) {
+            return false;
+        }
+        if (!this.clipElement) {
+            return false;
+        }
+        if (!this.surfaceElement.contains(this.clipElement)) {
+            return false;
+        }
+        if (element) {
+            if (!this.clipElement.contains(element))
+                return false;
+        }
+        return true;
+    }
+    _state;
+    setState(newState) {
+        this._state = newState;
+        clearTimeout(this.timeout);
+        this.loop();
+    }
+    timeout;
+    loop = async () => {
+        if (this.isConnected()) {
+            this.update();
+            this.timeout = setTimeout(this.loop, 0);
+        }
+        else {
+            this.destroy();
+        }
+    };
+}
+export function assertElement(mediaElement, parentElement, clip, constructAssetURL, preloader) {
+    let element;
+    switch (clip.type) {
+        case 'image':
+            {
+                element = mediaElement instanceof HTMLImageElement ? mediaElement : document.createElement('img');
+                const assetURL = constructAssetURL(clip.file);
+                if (!element.src.includes(assetURL)) {
+                    element.src = assetURL;
+                }
+            }
+            break;
+        case 'audio':
+            element = mediaElement instanceof HTMLAudioElement ? mediaElement : preloader.getElement(clip.file, clip.type);
+            break;
+        case 'video':
+            element = mediaElement instanceof HTMLVideoElement ? mediaElement : preloader.getElement(clip.file, clip.type);
+            break;
+    }
+    parentElement.replaceChildren(element);
+    element.style.position = 'absolute';
+    element.style.width = '100%';
+    element.style.height = '100%';
+    return element;
+}
+export function assertVisualProperties(mediaElement, properties, objectFit) {
+    const opacityString = String(properties.opacity);
+    if (mediaElement.style.opacity !== opacityString) {
+        mediaElement.style.opacity = opacityString;
+    }
+    const zIndex = Math.round(properties.zIndex ?? 0);
+    if (parseInt(mediaElement.style.zIndex) !== zIndex) {
+        mediaElement.style.zIndex = String(zIndex);
+    }
+    if (mediaElement.style.objectFit !== objectFit) {
+        mediaElement.style.objectFit = objectFit;
+    }
+}
+export function assertAudialProperties(mediaElement, properties, sinkId) {
+    if (mediaElement.volume !== properties.volume) {
+        mediaElement.volume = properties.volume;
+    }
+    if (mediaElement.sinkId !== sinkId) {
+        mediaElement.setSinkId(sinkId).catch(() => {
+            /* Do nothing, will be tried in next loop */
+        });
+    }
+}
+const OUTER_TARGET_SYNC_THRESHOLD_MS = 50; // When outside of this range we attempt to sync playback
+const INNER_TARGET_SYNC_THRESHOLD_MS = 5; // When attempting to sync playback, we aim for this accuracy
+const MAX_SYNC_THRESHOLD_MS = 1_000; // If we are further than this, we will seek instead
+const SEEK_LOOKAHEAD_MS = 5; // If it takes time to seek, we should seek ahead a little
+const LOOPING_EPSILON_MS = 5;
+const PLAYBACK_ADJUSTMENT_SMOOTHING = 0.3;
+const MAX_PLAYBACK_RATE_ADJUSTMENT = 0.1;
+function playbackSmoothing(deltaTime) {
+    return Math.sign(deltaTime) * Math.pow(Math.abs(deltaTime) / MAX_SYNC_THRESHOLD_MS, PLAYBACK_ADJUSTMENT_SMOOTHING) * MAX_PLAYBACK_RATE_ADJUSTMENT;
+}
+export function assertTemporalProperties(mediaElement, properties, keyframes, syncState) {
+    if (mediaElement.paused && properties.rate > 0) {
+        mediaElement.play().catch(() => {
+            /* Do nothing, will be tried in next loop */
+        });
+    }
+    // At the end of the media, is it set back to the start?
+    // Sounds like looping to me!
+    if (mediaElement.duration) {
+        const nextTemporalKeyframe = keyframes.filter(([t, kf]) => t > properties.t && (kf?.set?.t !== undefined || kf?.set?.rate !== undefined))[0];
+        if (nextTemporalKeyframe?.[1]?.set?.t === 0) {
+            const timeRemaining = (mediaElement.duration - properties.t) / properties.rate;
+            const timeUntilKeyframe = nextTemporalKeyframe[0] - properties.t;
+            const isLooping = Math.abs(timeRemaining - timeUntilKeyframe) <= LOOPING_EPSILON_MS;
+            if (mediaElement.loop !== isLooping) {
+                mediaElement.loop = isLooping;
+            }
+        }
+    }
+    const currentTime = mediaElement.currentTime * 1000;
+    const deltaTime = currentTime - properties.t;
+    const deltaTimeAbs = Math.abs(deltaTime);
+    switch (true) {
+        case syncState.state === 'idle' && properties.rate > 0 && deltaTimeAbs <= OUTER_TARGET_SYNC_THRESHOLD_MS:
+            // We are on course:
+            //   - The video is within accepted latency of the server time
+            //   - The playback rate is aligned with the server rate
+            if (mediaElement.playbackRate !== properties.rate) {
+                mediaElement.playbackRate = properties.rate;
+            }
+            return { state: 'idle' };
+        case syncState.state === 'idle' &&
+            properties.rate > 0 &&
+            deltaTimeAbs > OUTER_TARGET_SYNC_THRESHOLD_MS &&
+            deltaTimeAbs <= MAX_SYNC_THRESHOLD_MS:
+            {
+                // We are close, we can smoothly adjust with playbackRate:
+                //  - The video must be playing
+                //  - We must be close in time to the server time
+                const playbackRateAdjustment = playbackSmoothing(deltaTime);
+                const adjustedPlaybackRate = Math.max(0, properties.rate - playbackRateAdjustment);
+                if (mediaElement.playbackRate !== adjustedPlaybackRate) {
+                    mediaElement.playbackRate = adjustedPlaybackRate;
+                }
+                return { state: 'intercepting' };
+            }
+        case syncState.state === 'intercepting' && properties.rate > 0 && deltaTimeAbs <= INNER_TARGET_SYNC_THRESHOLD_MS: {
+            // We have intercepted, we can now play normally
+            if (mediaElement.playbackRate !== properties.rate) {
+                mediaElement.playbackRate = properties.rate;
+            }
+            return { state: 'idle' };
+        }
+        case syncState.state === 'intercepting' && Math.sign(deltaTime) === Math.sign(mediaElement.playbackRate - properties.rate): {
+            // We have missed our interception.  Go back to idle to try again.
+            console.warn(deltaTime, 'missed intercept');
+            return { state: 'idle' };
+        }
+        case syncState.state === 'intercepting':
+            return { state: 'intercepting' };
+        case syncState.state === 'seeking': {
+            return { state: 'seeking' };
+        }
+        default: {
+            // We cannot smoothly recover:
+            //  - We seek just ahead of server time
+            if (mediaElement.playbackRate !== properties.rate) {
+                mediaElement.playbackRate = properties.rate;
+            }
+            mediaElement.currentTime = (properties.t + properties.rate * SEEK_LOOKAHEAD_MS) / 1000;
+            return { state: 'seeking' };
+        }
+    }
+}
+export class ImageManager extends MediaClipManager {
+    imageElement;
+    update() {
+        const currentState = getStateAtTime(this._state, Date.now());
+        if (currentState) {
+            this.imageElement = assertElement(this.imageElement, this.clipElement, this._state, this.constructAssetURL, this.mediaPreloader);
+        }
+        else if (this.imageElement) {
+            this.destroy();
+        }
+        if (!currentState || !this.imageElement)
+            return;
+        assertVisualProperties(this.imageElement, currentState, this._state.fit);
+    }
+    destroy() {
+        if (this.imageElement) {
+            this.imageElement.remove();
+            this.imageElement.src = '';
+            this.imageElement = undefined;
+        }
+    }
+}
+export class AudioManager extends MediaClipManager {
+    syncState = { state: 'idle' };
+    audioElement;
+    update() {
+        const currentState = getStateAtTime(this._state, Date.now());
+        if (currentState) {
+            this.audioElement = assertElement(this.audioElement, this.clipElement, this._state, this.constructAssetURL, this.mediaPreloader);
+        }
+        else {
+            this.destroy();
+        }
+        if (!currentState || !this.audioElement)
+            return;
+        assertAudialProperties(this.audioElement, currentState, this._state.audioOutput);
+        const nextSyncState = assertTemporalProperties(this.audioElement, currentState, this._state.keyframes, this.syncState);
+        if (this.syncState.state !== 'seeking' && nextSyncState.state === 'seeking') {
+            this.audioElement.addEventListener('seeked', () => {
+                this.syncState = { state: 'idle' };
+            }, { passive: true, once: true });
+        }
+        this.syncState = nextSyncState;
+    }
+    destroy() {
+        this.audioElement?.remove();
+        this.audioElement = undefined;
+    }
+}
+export class VideoManager extends MediaClipManager {
+    syncState = { state: 'idle' };
+    videoElement;
+    update() {
+        const currentState = getStateAtTime(this._state, Date.now());
+        if (currentState) {
+            this.videoElement = assertElement(this.videoElement, this.clipElement, this._state, this.constructAssetURL, this.mediaPreloader);
+        }
+        else {
+            this.destroy();
+        }
+        if (!currentState || !this.videoElement)
+            return;
+        assertVisualProperties(this.videoElement, currentState, this._state.fit);
+        assertAudialProperties(this.videoElement, currentState, this._state.audioOutput);
+        const nextSyncState = assertTemporalProperties(this.videoElement, currentState, this._state.keyframes, this.syncState);
+        if (this.syncState.state !== 'seeking' && nextSyncState.state === 'seeking') {
+            this.videoElement.addEventListener('seeked', () => {
+                this.syncState = { state: 'idle' };
+            }, { passive: true, once: true });
+        }
+        this.syncState = nextSyncState;
+    }
+    destroy() {
+        this.videoElement?.remove();
+        this.videoElement = undefined;
+    }
+}

package/dist/state-based/MediaPreloader.d.ts

@@ -0,0 +1,14 @@
+import { MediaClientConfig } from '../types/CogsClientMessage';
+export declare class MediaPreloader {
+    private _state;
+    private _elements;
+    private _constructAssetURL;
+    constructor(constructAssetURL: (file: string) => string, testState?: MediaClientConfig['files']);
+    get state(): {
+        [x: string]: import("../types/CogsClientMessage").Media;
+    };
+    setState(newState: MediaClientConfig['files']): void;
+    private update;
+    getElement(file: string, type: 'audio' | 'video'): HTMLAudioElement;
+    releaseElement(resource: string | HTMLMediaElement): void;
+}

package/dist/state-based/MediaPreloader.js

@@ -0,0 +1,86 @@
+export class MediaPreloader {
+    _state;
+    _elements = {};
+    _constructAssetURL;
+    constructor(constructAssetURL, testState = {}) {
+        this._constructAssetURL = constructAssetURL;
+        this._state = testState;
+    }
+    get state() {
+        return { ...this._state };
+    }
+    setState(newState) {
+        this._state = newState;
+        this.update();
+    }
+    update() {
+        // Clean up previous elements
+        for (const [filename, media] of Object.entries(this._elements)) {
+            if (!(filename in this._state)) {
+                media.element.src = '';
+                delete this._elements[filename];
+            }
+            media.inUse = media.element.isConnected;
+        }
+        for (const [filename, fileConfig] of Object.entries(this._state)) {
+            if (filename in this._elements) {
+                continue;
+            }
+            // Create new elements
+            let preloadAttr;
+            if (fileConfig.preload === true) {
+                preloadAttr = 'auto';
+            }
+            else if (fileConfig.preload === false) {
+                preloadAttr = 'none';
+            }
+            else {
+                preloadAttr = fileConfig.preload;
+            }
+            switch (fileConfig.type) {
+                case 'audio': {
+                    const element = document.createElement('audio');
+                    element.src = this._constructAssetURL(filename);
+                    element.preload = preloadAttr;
+                    this._elements[filename] = { element, inUse: false, type: 'audio' };
+                    break;
+                }
+                case 'video': {
+                    const element = document.createElement('video');
+                    element.src = this._constructAssetURL(filename);
+                    element.preload = preloadAttr;
+                    this._elements[filename] = { element, inUse: false, type: 'video' };
+                    break;
+                }
+            }
+        }
+    }
+    getElement(file, type) {
+        const media = this._elements[file];
+        if (media && media.inUse === false) {
+            media.inUse = true;
+            return media.element;
+        }
+        else {
+            const element = document.createElement(type);
+            element.src = this._constructAssetURL(file);
+            this._elements[file] = { element, type, inUse: true };
+            return element;
+        }
+    }
+    releaseElement(resource) {
+        if (typeof resource === 'string') {
+            const media = this._elements[resource];
+            if (media) {
+                media.inUse = false;
+            }
+        }
+        else {
+            Object.entries(this._elements).forEach(([file, media]) => {
+                if (media.element === resource) {
+                    delete this._elements[file];
+                }
+            });
+        }
+    }
+}

package/dist/state-based/SurfaceManager.d.ts

@@ -0,0 +1,19 @@
+import { MediaSurfaceState } from '../types/MediaSchema';
+import { MediaPreloader } from './MediaPreloader';
+export declare const DATA_CLIP_ID = "data-clip-id";
+/**
+ * The SurfaceManager will receive state updates and:
+ * - Ensure that each clip has a parent element
+ * - Instantiate a ClipManager attached to each respective element
+ */
+export declare class SurfaceManager {
+    private constructAssetUrl;
+    private mediaPreloader;
+    private _state;
+    setState(newState: MediaSurfaceState): void;
+    private _element;
+    get element(): HTMLDivElement;
+    private resources;
+    constructor(constructAssetUrl: (file: string) => string, testState?: MediaSurfaceState, mediaPreloader?: MediaPreloader);
+    update(): void;
+}

package/dist/state-based/SurfaceManager.js

@@ -0,0 +1,84 @@
+import { AudioManager, ImageManager, VideoManager } from './MediaClipManager';
+import { MediaPreloader } from './MediaPreloader';
+export const DATA_CLIP_ID = 'data-clip-id';
+/**
+ * The SurfaceManager will receive state updates and:
+ * - Ensure that each clip has a parent element
+ * - Instantiate a ClipManager attached to each respective element
+ */
+export class SurfaceManager {
+    constructAssetUrl;
+    mediaPreloader;
+    _state = {};
+    setState(newState) {
+        this._state = newState;
+        this.update();
+    }
+    _element;
+    get element() {
+        return this._element;
+    }
+    resources = {};
+    constructor(constructAssetUrl, testState, mediaPreloader = new MediaPreloader(constructAssetUrl)) {
+        this.constructAssetUrl = constructAssetUrl;
+        this.mediaPreloader = mediaPreloader;
+        this._element = document.createElement('div');
+        this._element.className = 'surface-manager';
+        this._element.style.width = '100%';
+        this._element.style.height = '100%';
+        this._state = testState || {};
+        this.update();
+    }
+    update() {
+        // Destroy stale managers
+        Object.entries(this.resources).forEach(([clipId, { element, manager }]) => {
+            if (!(clipId in this._state)) {
+                delete this.resources[clipId];
+                element.remove();
+                manager?.destroy();
+            }
+        });
+        // Create and attach new wrapper elements
+        const elements = Object.keys(this._state)
+            .toSorted()
+            .map((clipId) => {
+            const resource = this.resources[clipId];
+            if (resource) {
+                return resource.element;
+            }
+            else {
+                const element = document.createElement('div');
+                element.setAttribute(DATA_CLIP_ID, clipId);
+                this.resources[clipId] = { element };
+                return element;
+            }
+        });
+        this._element.replaceChildren(...elements);
+        // Create new managers
+        Object.keys(this._state)
+            .toSorted()
+            .forEach((clipId) => {
+            const clip = this._state[clipId];
+            const resource = this.resources[clipId];
+            if (!resource) {
+                throw new Error('Failed to create resource');
+            }
+            if (!resource.manager) {
+                switch (clip.type) {
+                    case 'image':
+                        resource.manager = new ImageManager(this._element, resource.element, clip, this.constructAssetUrl, this.mediaPreloader);
+                        break;
+                    case 'audio':
+                        resource.manager = new AudioManager(this._element, resource.element, clip, this.constructAssetUrl, this.mediaPreloader);
+                        break;
+                    case 'video':
+                        resource.manager = new VideoManager(this._element, resource.element, clip, this.constructAssetUrl, this.mediaPreloader);
+                        break;
+                }
+            }
+            else {
+                resource.manager.setState(clip);
+            }
+        });
+    }
+}

package/dist/types/MediaSchema.d.ts

@@ -7,6 +7,7 @@ declare const TemporalProperties: z.ZodObject<{
 export type VisualProperties = z.infer<typeof VisualProperties>;
 declare const VisualProperties: z.ZodObject<{
     opacity: z.ZodNumber;
+    zIndex: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type AudialProperties = z.infer<typeof AudialProperties>;
 declare const AudialProperties: z.ZodObject<{
@@ -40,6 +41,7 @@ export type InitialImageKeyframe = z.infer<typeof InitialImageKeyframe>;
 declare const InitialImageKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
     set: z.ZodOptional<z.ZodObject<{
         opacity: z.ZodOptional<z.ZodNumber>;
+        zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     }, z.core.$strip>>;
 }, z.core.$strip>], null>;
 /**
@@ -49,9 +51,11 @@ export type ImageKeyframe = z.infer<typeof ImageKeyframe>;
 declare const ImageKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
     set: z.ZodOptional<z.ZodObject<{
         opacity: z.ZodOptional<z.ZodNumber>;
+        zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     }, z.core.$strip>>;
     lerp: z.ZodOptional<z.ZodObject<{
         opacity: z.ZodOptional<z.ZodNumber>;
+        zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     }, z.core.$strip>>;
 }, z.core.$strip>], null>;
 /**
@@ -86,6 +90,7 @@ export type InitialVideoKeyframe = z.infer<typeof InitialVideoKeyframe>;
 declare const InitialVideoKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
     set: z.ZodOptional<z.ZodObject<{
         opacity: z.ZodOptional<z.ZodNumber>;
+        zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
         volume: z.ZodOptional<z.ZodNumber>;
         t: z.ZodOptional<z.ZodNumber>;
         rate: z.ZodOptional<z.ZodNumber>;
@@ -98,12 +103,14 @@ export type VideoKeyframe = z.infer<typeof VideoKeyframe>;
 declare const VideoKeyframe: z.ZodTuple<[z.ZodNumber, z.ZodObject<{
     set: z.ZodOptional<z.ZodObject<{
         opacity: z.ZodOptional<z.ZodNumber>;
+        zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
         volume: z.ZodOptional<z.ZodNumber>;
         t: z.ZodOptional<z.ZodNumber>;
         rate: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     lerp: z.ZodOptional<z.ZodObject<{
         opacity: z.ZodOptional<z.ZodNumber>;
+        zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
         volume: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>], null>;
@@ -111,13 +118,16 @@ export declare const MediaSurfaceStateSchema: z.ZodRecord<z.ZodString, z.ZodUnio
     keyframes: z.ZodTuple<[z.ZodTuple<[z.ZodNumber, z.ZodObject<{
         set: z.ZodOptional<z.ZodObject<{
             opacity: z.ZodOptional<z.ZodNumber>;
+            zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
         }, z.core.$strip>>;
         lerp: z.ZodOptional<z.ZodObject<{
             opacity: z.ZodOptional<z.ZodNumber>;
+            zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
         }, z.core.$strip>>;
     }, z.core.$strip>], null>], z.ZodUnion<readonly [z.ZodTuple<[z.ZodNumber, z.ZodObject<{
         set: z.ZodOptional<z.ZodObject<{
             opacity: z.ZodOptional<z.ZodNumber>;
+            zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
         }, z.core.$strip>>;
     }, z.core.$strip>], null>, z.ZodTuple<[z.ZodNumber, z.ZodNull], null>]>>;
     type: z.ZodLiteral<"image">;
@@ -147,17 +157,20 @@ export declare const MediaSurfaceStateSchema: z.ZodRecord<z.ZodString, z.ZodUnio
     keyframes: z.ZodTuple<[z.ZodTuple<[z.ZodNumber, z.ZodObject<{
         set: z.ZodOptional<z.ZodObject<{
             opacity: z.ZodOptional<z.ZodNumber>;
+            zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
             volume: z.ZodOptional<z.ZodNumber>;
             t: z.ZodOptional<z.ZodNumber>;
             rate: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         lerp: z.ZodOptional<z.ZodObject<{
             opacity: z.ZodOptional<z.ZodNumber>;
+            zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
             volume: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>], null>], z.ZodUnion<readonly [z.ZodTuple<[z.ZodNumber, z.ZodObject<{
         set: z.ZodOptional<z.ZodObject<{
             opacity: z.ZodOptional<z.ZodNumber>;
+            zIndex: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
             volume: z.ZodOptional<z.ZodNumber>;
             t: z.ZodOptional<z.ZodNumber>;
             rate: z.ZodOptional<z.ZodNumber>;

package/dist/types/MediaSchema.js

@@ -5,6 +5,7 @@ const TemporalProperties = z.object({
 });
 const VisualProperties = z.object({
     opacity: z.number().gte(0).lte(1),
+    zIndex: z.number().default(0),
 });
 const AudialProperties = z.object({
     volume: z.number().gte(0).lte(1),
@@ -139,6 +140,7 @@ true;
 true;
 export const defaultImageOptions = {
     opacity: 1,
+    zIndex: 0,
 };
 export const defaultAudioOptions = {
     t: 0,
@@ -150,4 +152,5 @@ export const defaultVideoOptions = {
     rate: 1,
     volume: 1,
     opacity: 1,
+    zIndex: 0,
 };

package/dist/utils/getStateAtTime.js

@@ -47,11 +47,11 @@ export function getPropertiesAtTime(keyframes, time) {
             // If lerp and set are both present, we assume we lerp up until the timestamp,
             // then set to a new value
             Object.entries(properties.lerp ?? {}).forEach(([property, value]) => {
-                propertyKeyframes[property] ?? (propertyKeyframes[property] = {});
+                propertyKeyframes[property] ??= {};
                 propertyKeyframes[property].before = [timestamp, value];
             });
             Object.entries(properties.set ?? {}).forEach(([property, value]) => {
-                propertyKeyframes[property] ?? (propertyKeyframes[property] = {});
+                propertyKeyframes[property] ??= {};
                 propertyKeyframes[property].before = [timestamp, value];
             });
         }
@@ -59,7 +59,7 @@ export function getPropertiesAtTime(keyframes, time) {
             // We're trying to find the closest timestamp afterwards for lerping
             // So only set if not yet set
             Object.entries(properties.lerp ?? {}).forEach(([property, value]) => {
-                propertyKeyframes[property] ?? (propertyKeyframes[property] = {});
+                propertyKeyframes[property] ??= {};
                 if (propertyKeyframes[property].after === undefined) {
                     propertyKeyframes[property].after = [timestamp, value];
                 }