@micrio/client 6.1.2 → 6.1.4

package/micrio.min.d.ts

@@ -12,10 +12,23 @@ declare module '@micrio/client' {
 	 * @returns A Promise resolving to the loaded TextureBitmap.
 	 */
 	export const loadTexture: (src: string) => Promise<TextureBitmap>;
+	/**
+	 * Mathematical utility functions.
+	 * @author Marcel Duin <marcel@micr.io>
+	 */
 	/**
 	 * Calculates the positive modulo (floored division remainder).
 	 */
 	export const mod: (n: number, m?: number) => number;
+	/**
+	 * Converts a Camera.View tuple `[x, y, w, h]` to a center-based JSON object.
+	 */
+	export const toCenterJSON: (v: Models.Camera.View) => {
+		centerX: number;
+		centerY: number;
+		width: number;
+		height: number;
+	};
 	/**
 	 * Defines various enums used throughout the Micrio application,
 	 * primarily for standardizing action types and option values.
@@ -88,14 +101,9 @@ declare module '@micrio/client' {
 		 * @returns A copy of the current screen viewport array, or undefined if not initialized.
 		 */
 		getViewRaw: () => Float64Array;
-		/**
-		 * Gets the current image view rectangle [x0, y0, x1, y1] relative to the image (0-1).
-		 * @returns A copy of the current screen viewport array, or undefined if not initialized.
-		 */
-		getViewLegacy: () => Models.Camera.ViewRect | undefined;
 		/**
 		 * Sets the camera view instantly to the specified viewport.
-		 * @param view The target viewport as either a View [x0, y0, x1, y1] or View {centerX, centerY, width, height}.
+		 * @param view The target viewport as a View [x0, y0, width, height].
 		 * @param opts Options for setting the view.
 		 */
 		setView(view: Models.Camera.View, opts?: {
@@ -184,7 +192,7 @@ declare module '@micrio/client' {
 		aniIsKinetic(): boolean;
 		/**
 		 * Animates the camera smoothly to a target viewport.
-		 * @param view The target viewport as either a View [x0, y0, x1, y1] or View {centerX, centerY, width, height}.
+		 * @param view The target viewport as a View [x0, y0, width, height].
 		 * @param opts Optional animation settings.
 		 * @returns A Promise that resolves when the animation completes, or rejects if aborted.
 		 */
@@ -407,14 +415,6 @@ declare module '@micrio/client' {
 		 */
 		animateTo(idx: number): void;
 	}
-	/**
-	 * Converts seconds into a human-readable time string (hh?:mm:ss).
-	 * @param s Time in seconds. Can be negative for remaining time display.
-	 * @returns Formatted time string (e.g., "1:23", "1:05:09", "-0:15").
-	 */
-	export function parseTime(s: number): string;
-	/** Type for error codes */
-	export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 	/**
 	 * Centralized data loading controller.
 	 * Uses the `bundle.json` endpoint which returns info + data for multiple
@@ -427,6 +427,7 @@ declare module '@micrio/client' {
 	 *
 	 * @author Marcel Duin <marcel@micr.io>
 	 */
+	type BundleImage = Models.ImageBundle.BundleImage;
 	export const DataLoader: {
 		/** Returns the info for an image ID, or undefined if not found in its bundle. */
 		getInfo(id: string): Promise<Models.ImageInfo.ImageInfo | undefined>;
@@ -444,23 +445,10 @@ declare module '@micrio/client' {
 		/** Returns the organisation data from the bundle, or undefined. */
 		getOrganisation(): Models.ImageInfo.Organisation | undefined;
 		/**
-		 * Returns both info + data for a single image ID, or undefined if the image
-		 * is not present in its bundle.
+		 * Returns the full bundle entry (info + data) for a single image ID,
+		 * fetching the bundle once if not cached.
 		 */
-		getBundleImage(id: string): Promise<{
-			data: Models.ImageData.ImageData;
-			info: Models.ImageInfo.ImageInfo;
-		} | undefined>;
-		/**
-		 * Bulk variant of {@link getBundleImage}.
-		 *
-		 * Fetches the bundle for the first non‑IIIF ID, then resolves every requested
-		 * image from the cached bundle results.
-		 */
-		getBundleImages(ids: string[]): Promise<Map<string, {
-			info: Models.ImageInfo.ImageInfo;
-			data: Models.ImageData.ImageData;
-		}>>;
+		getBundleImage(id: string): Promise<BundleImage | undefined>;
 	};
 	/**
 	 * # Micrio State management
@@ -619,36 +607,6 @@ declare module '@micrio/client' {
 		/** Fades out the image smoothly or instantly. */
 		fadeOut(direct?: boolean): void;
 	}
-	/**
-	 * Direction-keyed area rectangles for grid/gallery slide and swipe transitions.
-	 * Areas use [x0, y0, x1, y1] in normalized parent-canvas coordinates and
-	 * extend outside [0,1] to represent off-screen positions.
-	 *
-	 * Direction conventions (degrees of motion of the entering image):
-	 *   0   = enters from top
-	 *   90  = enters from right
-	 *   180 = enters from bottom
-	 *   270 = enters from left
-	 *
-	 * @author Marcel Duin <marcel@micr.io>
-	 */
-	/** Slide transition entry areas (entering image starts half-off-screen). */
-	export const slideAreas: Record<number, Models.Camera.ViewRect>;
-	/** Swipe transition entry areas (entering image starts fully off-screen). */
-	export const swipeAreas: Record<number, Models.Camera.ViewRect>;
-	/** Swipe transition exit areas (leaving image moves fully off-screen). */
-	export const swipeExitAreas: Record<number, Models.Camera.ViewRect>;
-	/** Centered visible slot. */
-	export const centerArea: Models.Camera.ViewRect;
-	/** Off-screen slot to the left, same height. */
-	export const leftSlot: Models.Camera.ViewRect;
-	/** Off-screen slot to the right, same height. */
-	export const rightSlot: Models.Camera.ViewRect;
-	/**
-	 * Returns the horizontal slot area for an integer offset from the active slot.
-	 * offset=0 → centered visible; positive → off to the right; negative → off to the left.
-	 */
-	export const horizontalSlot: (offset: number) => Models.Camera.ViewRect;
 	/**
 	 * Micrio grid display controller
 	 * @author Marcel Duin <marcel@micr.io>
@@ -940,7 +898,7 @@ declare module '@micrio/client' {
 				version: string;
 				/** Created date */
 				created?: number;
-				/** Has new viewport model, optimized for 360 images */
+				/** Has new viewport model, optimized for 360 images. Server-side only, not read client-side. */
 				viewsWH?: boolean;
 				/** For V5+: published revisions per language */
 				revision?: RevisionType;
@@ -1023,7 +981,7 @@ declare module '@micrio/client' {
 			type Settings = {
 				/** The starting viewport */
 				view?: Camera.View;
-				/** Restrict navigation to this viewport (`[x0,y0,x1,y1]`) */
+				/** Restrict navigation to this viewport (`[x0, y0, width, height]`) */
 				restrict?: Camera.View;
 				/** Load a cover-initing image focussed on this coordinate (`[x, y]`) */
 				focus?: [number, number];
@@ -1681,8 +1639,6 @@ declare module '@micrio/client' {
 				keepMarkers?: boolean;
 				/** Don't disable user navigation when running */
 				keepInteraction?: boolean;
-				/** The tour is a direct outside instance using legacy [x0,y0,x1,y1] viewports */
-				isLegacy?: boolean;
 				/** Current running tour instance */
 				instance?: VideoTourInstance;
 			};
@@ -2487,101 +2443,6 @@ declare module '@micrio/client' {
 		/** Has touch support */
 		hasTouch: boolean;
 	}
-	/**
-	 * List of internal Micrio event types that should trigger a debounced 'update' event.
-	 * The 'update' event signals that the overall state relevant for external integrations might have changed.
-	 * @readonly
-	 */
-	export const UpdateEvents: (keyof Models.MicrioEventMap)[];
-	/**
-	 * Update event handler module.
-	 * Manages debounced 'update' event dispatching when internal state changes.
-	 */
-	export class UpdateHandler {
-		private ctx;
-		constructor(ctx: EventContext);
-		/** Hooks listeners for events that should trigger a debounced 'update' event. */
-		hook(): void;
-		/** Unhooks listeners for the debounced 'update' event. */
-		unhook(): void;
-		/**
-		 * Event listener callback that queues the event type and triggers the debounced dispatch.
-		 * @param e The Event object.
-		 */
-		private handleEvent;
-		/**
-		 * Dispatches the 'update' event with the accumulated event types and current state.
-		 * Clears the event stack.
-		 */
-		private dispatch;
-	}
-	export { UpdateEvents } from "ts/events/update";
-	/**
-	 * Handles user input events (mouse, touch, keyboard, wheel, gestures) for the Micrio viewer.
-	 * Translates browser events into camera movements (pan, zoom), dispatches custom Micrio events,
-	 * and manages interaction states like panning, pinching, and enabled/disabled states.
-	 * Accessed via `micrio.events`.
-	 * @author Marcel Duin <marcel@micr.io>
-	 */
-	export class Events implements EventContext {
-		/** Writable Svelte store indicating if event handling is currently enabled. Set to false during tours or animations. */
-		enabled: Writable<boolean>;
-		/** Getter for the current value of the {@link enabled} store. */
-		get $enabled(): boolean;
-		/** Current pinch zoom factor relative to the start of the pinch. Undefined when not pinching. */
-		pinchFactor: number | undefined;
-		private dragHandler;
-		private pinchHandler;
-		private pointerPinchHandler;
-		private gestureHandler;
-		private wheelHandler;
-		private keyboardHandler;
-		private doubleTapHandler;
-		private updateHandler;
-		isEnabled(): boolean;
-		isPanning(): boolean;
-		isPinching(): boolean;
-		setPanning(value: boolean): void;
-		setPinching(value: boolean): void;
-		isWheeling(): boolean;
-		setWheeling(value: boolean): void;
-		isControlZoom(): boolean;
-		isTwoFingerPan(): boolean;
-		getVisible(): MicrioImage[] | undefined;
-		setCapturedPointerId(id: number | undefined): void;
-		setPinchFactor(value: number | undefined): void;
-		setPScale(value: number): void;
-		setHasUsedCtrl(value: boolean): void;
-		/**
-		 * Checks if the user is currently interacting with the map via panning, pinching, or wheeling.
-		 * @returns True if the user is actively navigating.
-		*/
-		get isNavigating(): boolean;
-		/** Hooks all necessary event listeners based on current settings. */
-		hook(): void;
-		/** Unhooks all attached event listeners. */
-		unhook(): void;
-		/** Hooks keyboard event listeners. */
-		hookKeys(): void;
-		/** Unhooks keyboard event listeners. */
-		unhookKeys(): void;
-		/** Hooks zoom-related event listeners (pinch, scroll, double-tap/click). */
-		hookZoom(): void;
-		/** Unhooks zoom-related event listeners. */
-		unhookZoom(): void;
-		/** Hooks mouse wheel/scroll event listeners. */
-		hookScroll(): void;
-		/** Unhooks mouse wheel/scroll event listeners. */
-		unhookScroll(): void;
-		/** Hooks touch pinch and macOS gesture event listeners. */
-		hookPinch(): void;
-		/** Unhooks touch pinch and macOS gesture event listeners. */
-		unhookPinch(): void;
-		/** Hooks pointer down/move/up listeners for drag panning. */
-		hookDrag(): void;
-		/** Unhooks pointer listeners for drag panning. */
-		unhookDrag(): void;
-	}
 	/**
 	 * Drag/pan event handler module.
 	 * Handles pointer down/move/up events for panning the image.
@@ -2771,16 +2632,100 @@ declare module '@micrio/client' {
 		 */
 		private click;
 	}
-	export { Events } from "ts/events/facade";
-	export { DragHandler } from "ts/events/drag";
-	export { PinchHandler } from "ts/events/pinch";
-	export { PointerPinchHandler } from "ts/events/pointer-pinch";
-	export { GestureHandler } from "ts/events/gesture";
-	export { WheelHandler } from "ts/events/wheel";
-	export { KeyboardHandler } from "ts/events/keyboard";
-	export { DoubleTapHandler } from "ts/events/doubletap";
-	export { UpdateHandler } from "ts/events/update";
-	export { type AllEvents, type EventStateVars, type EventContext, eventPassive, eventPassiveCapture, noEventPassive, cancelPrevent, } from "ts/events/shared";
+	/**
+	 * List of internal Micrio event types that should trigger a debounced 'update' event.
+	 * The 'update' event signals that the overall state relevant for external integrations might have changed.
+	 * @readonly
+	 */
+	export const UpdateEvents: (keyof Models.MicrioEventMap)[];
+	/**
+	 * Update event handler module.
+	 * Manages debounced 'update' event dispatching when internal state changes.
+	 */
+	export class UpdateHandler {
+		private ctx;
+		constructor(ctx: EventContext);
+		/** Hooks listeners for events that should trigger a debounced 'update' event. */
+		hook(): void;
+		/** Unhooks listeners for the debounced 'update' event. */
+		unhook(): void;
+		/**
+		 * Event listener callback that queues the event type and triggers the debounced dispatch.
+		 * @param e The Event object.
+		 */
+		private handleEvent;
+		/**
+		 * Dispatches the 'update' event with the accumulated event types and current state.
+		 * Clears the event stack.
+		 */
+		private dispatch;
+	}
+	/**
+	 * Handles user input events (mouse, touch, keyboard, wheel, gestures) for the Micrio viewer.
+	 * Translates browser events into camera movements (pan, zoom), dispatches custom Micrio events,
+	 * and manages interaction states like panning, pinching, and enabled/disabled states.
+	 * Accessed via `micrio.events`.
+	 * @author Marcel Duin <marcel@micr.io>
+	 */
+	export class Events implements EventContext {
+		/** Writable Svelte store indicating if event handling is currently enabled. Set to false during tours or animations. */
+		enabled: Writable<boolean>;
+		/** Getter for the current value of the {@link enabled} store. */
+		get $enabled(): boolean;
+		/** Current pinch zoom factor relative to the start of the pinch. Undefined when not pinching. */
+		pinchFactor: number | undefined;
+		private dragHandler;
+		private pinchHandler;
+		private pointerPinchHandler;
+		private gestureHandler;
+		private wheelHandler;
+		private keyboardHandler;
+		private doubleTapHandler;
+		private updateHandler;
+		isEnabled(): boolean;
+		isPanning(): boolean;
+		isPinching(): boolean;
+		setPanning(value: boolean): void;
+		setPinching(value: boolean): void;
+		isWheeling(): boolean;
+		setWheeling(value: boolean): void;
+		isControlZoom(): boolean;
+		isTwoFingerPan(): boolean;
+		getVisible(): MicrioImage[] | undefined;
+		setCapturedPointerId(id: number | undefined): void;
+		setPinchFactor(value: number | undefined): void;
+		setPScale(value: number): void;
+		setHasUsedCtrl(value: boolean): void;
+		/**
+		 * Checks if the user is currently interacting with the map via panning, pinching, or wheeling.
+		 * @returns True if the user is actively navigating.
+		*/
+		get isNavigating(): boolean;
+		/** Hooks all necessary event listeners based on current settings. */
+		hook(): void;
+		/** Unhooks all attached event listeners. */
+		unhook(): void;
+		/** Hooks keyboard event listeners. */
+		hookKeys(): void;
+		/** Unhooks keyboard event listeners. */
+		unhookKeys(): void;
+		/** Hooks zoom-related event listeners (pinch, scroll, double-tap/click). */
+		hookZoom(): void;
+		/** Unhooks zoom-related event listeners. */
+		unhookZoom(): void;
+		/** Hooks mouse wheel/scroll event listeners. */
+		hookScroll(): void;
+		/** Unhooks mouse wheel/scroll event listeners. */
+		unhookScroll(): void;
+		/** Hooks touch pinch and macOS gesture event listeners. */
+		hookPinch(): void;
+		/** Unhooks touch pinch and macOS gesture event listeners. */
+		unhookPinch(): void;
+		/** Hooks pointer down/move/up listeners for drag panning. */
+		hookDrag(): void;
+		/** Unhooks pointer listeners for drag panning. */
+		unhookDrag(): void;
+	}
 	/**
 	 * Language-related constants and utilities.
 	 */
@@ -2981,8 +2926,6 @@ declare module '@micrio/client' {
 		*/
 		constructor(micrio: HTMLMicrioElement);
 	}
-	export { i18n, langs } from "ts/i18n/strings";
-	export { locale, languageNames, rtlLanguageCodes } from "ts/i18n/locale";
 	/**
 	 * Manages the loading, playback, and WebGL integration of embedded videos
 	 * that are rendered directly onto the Micrio canvas texture (not as HTML elements).
@@ -3119,84 +3062,21 @@ declare module '@micrio/client' {
 		setVolume(volume: number): void;
 		destroy(): void;
 	}
-	export type PREDEFINED = [string, Models.ImageInfo.ImageInfo, Models.ImageData.ImageData | undefined];
-	/** Enum for identifying media type. */
-	export enum MediaType {
-		None = 0,
-		IFrame = 1,
-		Video = 2,
-		Audio = 3,
-		VideoTour = 4,
-		Micrio = 5
-	}
-	/** Enum for identifying iframe player type. */
-	export enum FrameType {
-		YouTube = 1,
-		Vimeo = 2
-	}
 	/**
-	 * Media utilities for source parsing, type detection, and player management.
-	 * @author Marcel Duin <marcel@micr.io>
-	 */
-	/** YouTube no-cookies host */
-	export const YOUTUBE_HOST = "https://www.youtube-nocookie.com";
-	/**
-	 * Parsed media source information.
-	 */
-	export interface ParsedMediaSource {
-		/** The detected media type */
-		type: MediaType;
-		/** The frame type for iframe embeds (YouTube/Vimeo) */
-		frameType?: FrameType;
-		/** The normalized/processed source URL */
-		src?: string;
-		/** YouTube video ID (if applicable) */
-		youtubeId?: string;
-		/** Vimeo video ID (if applicable) */
-		vimeoId?: string;
-		/** Vimeo hash token (if applicable) */
-		vimeoToken?: string;
-		/** Cloudflare video ID (if applicable) */
-		cloudflareId?: string;
-		/** Micrio embed data [id, width?, height?, lang?] */
-		micrioEmbed?: string[];
-		/** Start time extracted from URL (seconds) */
-		startTime?: number;
-		/** Whether the source is a Cloudflare stream */
-		isCloudflare: boolean;
-		/** M3U8 URL for HLS streams */
-		hlsSrc?: string;
-	}
-	/**
-	 * Parses a media source URL and determines its type and configuration.
-	 */
-	export function parseMediaSource(src: string | undefined, tour: Models.ImageData.VideoTour | null, useNativeFrames?: boolean, currentTime?: number): ParsedMediaSource;
-	/**
-	 * Checks if the browser natively supports HLS playback.
-	 */
-	export function hasNativeHLS(el?: HTMLMediaElement): boolean;
-	/**
-	 * Returns a shared Audio element instance for iOS.
-	 * This is a workaround for iOS audio playback restrictions where user
-	 * interaction is required per audio element.
-	 */
-	export function getIOSAudioElement(): HTMLAudioElement;
-	/**
-	 * Adapter for YouTube IFrame Player API.
+	 * Adapter for Vimeo Player API.
 	 */
-	export class YouTubePlayerAdapter implements MediaPlayerAdapter {
+	export class VimeoPlayerAdapter implements MediaPlayerAdapter {
 		private frame;
 		private config;
 		private callbacks;
-		readonly requiresTimeTick = true;
+		readonly requiresTimeTick = false;
 		private player;
 		private destroyed;
 		constructor(frame: HTMLIFrameElement, config: PlayerConfig, callbacks?: PlayerEventCallbacks);
 		/**
-		 * Loads the YouTube API and initializes the player.
+		 * Loads the Vimeo API and initializes the player.
 		 */
 		initialize(): Promise<void>;
-		private handleStateChange;
 		play(): Promise<void>;
 		pause(): void;
 		getCurrentTime(): Promise<number>;
@@ -3204,24 +3084,25 @@ declare module '@micrio/client' {
 		getDuration(): Promise<number>;
 		isPaused(): Promise<boolean>;
 		setMuted(muted: boolean): void;
-		setVolume(_volume: number): void;
+		setVolume(volume: number): void;
 		destroy(): void;
 	}
 	/**
-	 * Adapter for Vimeo Player API.
+	 * Adapter for YouTube IFrame Player API.
 	 */
-	export class VimeoPlayerAdapter implements MediaPlayerAdapter {
+	export class YouTubePlayerAdapter implements MediaPlayerAdapter {
 		private frame;
 		private config;
 		private callbacks;
-		readonly requiresTimeTick = false;
+		readonly requiresTimeTick = true;
 		private player;
 		private destroyed;
 		constructor(frame: HTMLIFrameElement, config: PlayerConfig, callbacks?: PlayerEventCallbacks);
 		/**
-		 * Loads the Vimeo API and initializes the player.
+		 * Loads the YouTube API and initializes the player.
 		 */
 		initialize(): Promise<void>;
+		private handleStateChange;
 		play(): Promise<void>;
 		pause(): void;
 		getCurrentTime(): Promise<number>;
@@ -3229,45 +3110,24 @@ declare module '@micrio/client' {
 		getDuration(): Promise<number>;
 		isPaused(): Promise<boolean>;
 		setMuted(muted: boolean): void;
-		setVolume(volume: number): void;
+		setVolume(_volume: number): void;
 		destroy(): void;
 	}
-	/**
-	 * Media player adapters module.
-	 * Provides unified interfaces for different media player types.
-	 * @author Marcel Duin <marcel@micr.io>
-	 */
-	export type { MediaPlayerAdapter, PlayerEventCallbacks, PlayerConfig } from "ts/media/types";
-	export { HTML5PlayerAdapter } from "ts/media/html5-adapter";
-	export { YouTubePlayerAdapter } from "ts/media/youtube-adapter";
-	export { VimeoPlayerAdapter } from "ts/media/vimeo-adapter";
-	export { HLSPlayerAdapter } from "ts/media/hls-adapter";
-	export { GLEmbedVideo } from "ts/media/embedvideo";
-	export { VideoTourInstance } from "ts/media/videotour";
-	export { Grid } from "ts/nav/grid";
-	export { GallerySwiper } from "ts/nav/swiper";
-	export { Engine } from "ts/render/engine";
-	export { WebGL } from "ts/render/webgl";
-	export { Canvas } from "ts/render/canvas";
-	export { PostProcessor } from "ts/render/postprocess";
-	export { archive } from "ts/render/archive";
-	export { loadTexture, runningThreads, numThreads, abortDownload } from "ts/render/textures";
-	export type { TextureBitmap } from "ts/render/textures";
-	/**
-	 * Marker clustering algorithm for calculating overlapping markers
-	 * and generating cluster marker objects.
-	 * @author Marcel Duin <marcel@micr.io>
-	 */
-	type MarkerData = Models.ImageData.Marker;
-	export type MarkerCoords = [x: number, y: number, w?: number, h?: number];
-	export interface ClusterResult {
-		overlapped: number[];
-		clusterMarkers: MarkerData[];
+	export type PREDEFINED = [string, Models.ImageInfo.ImageInfo, Models.ImageData.ImageData | undefined];
+	/** Enum for identifying media type. */
+	export enum MediaType {
+		None = 0,
+		IFrame = 1,
+		Video = 2,
+		Audio = 3,
+		VideoTour = 4,
+		Micrio = 5
+	}
+	/** Enum for identifying iframe player type. */
+	export enum FrameType {
+		YouTube = 1,
+		Vimeo = 2
 	}
-	/**
-	 * Calculates which markers overlap and generates synthetic cluster markers.
-	 */
-	export function calcClusters(visibleMarkers: MarkerData[] | undefined, coords: Map<string, MarkerCoords>, r: number, isOmni: boolean): ClusterResult;
 }declare module "svelte/store" {
 	/** Callback to inform of a value updates.
 	*/