@micrio/client/micrio.min.d.ts

Micrio Client image viewer

declare module '@micrio/client' {
	import type { Readable, Writable } from 'svelte/store';
	/**
	 * Defines the current version of the Micrio library.
	 * This constant is used internally and exposed statically via `HTMLMicrioElement.VERSION`.
	 */
	export const VERSION = "5.4.28";
	/**
	 * Loads an image texture asynchronously. Adds the request to the queue
	 * and returns a Promise that resolves with the TextureBitmap or rejects on error.
	 * @param src The URL of the image to load.
	 * @returns A Promise resolving to the loaded TextureBitmap.
	 */
	export const loadTexture: (src: string) => Promise<TextureBitmap>;
	/**
	 * 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;
	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
	}
	export { isLegacyViews };
	/**
	 * 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;
		/** Original source URL */
		originalSrc?: 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;
	/**
	 * Global utility functions used throughout the Micrio application.
	 * Re-exports all utility modules for convenient importing.
	 * @author Marcel Duin <marcel@micr.io>
	 */
	export { MicrioError } from "ts/utils/error";
	export { pyth, mod, limitView } from "ts/utils/math";
	export { clone, deepCopy } from "ts/utils/object";
	export { createGUID, slugify, parseTime } from "ts/utils/string";
	export { Browser } from "ts/utils/browser";
	export { sleep, notypecheck, loadScript } from "ts/utils/dom";
	export { once, after } from "ts/utils/store";
	export { View } from "ts/utils/view";
	export { sanitizeAsset, isLegacyViews, sanitizeImageInfo, sanitizeImageData, sanitizeSpaceData, sanitizeMarker, sanitizeVideoTour } from "ts/utils/sanitize";
	export { jsonCache, fetchJson, isFetching, getLocalData, fetchInfo, fetchAlbumInfo } from "ts/utils/fetch";
	export { loadSerialTour } from "ts/utils/tour";
	export { getIdVal, idIsV5 } from "ts/utils/id";
	export { getSpaceVector } from "ts/utils/space";
	export { hasNativeHLS, parseMediaSource, getIOSAudioElement, YOUTUBE_HOST } from "ts/utils/media";
	export type { ParsedMediaSource } from "ts/utils/media";
	/**
	 * Global utility functions used throughout the Micrio application.
	 * This file re-exports all utilities from the modular utils/ directory.
	 * @author Marcel Duin <marcel@micr.io>
	 */
	export * from "ts/utils/index";
	/**
	 * Defines various enums used throughout the Micrio application,
	 * primarily for standardizing action types and option values.
	 */
	export namespace Enums {
		/** Enums related to the Grid functionality. */
		namespace Grid {
			/**
			 * Defines the types of actions that can be performed on a Grid instance,
			 * often triggered by marker data (`gridAction`) or tour events.
			 */
			enum GridActionType {
				/** Focus on specific images within the grid, hiding others. Data: comma-separated image IDs. */
				focus = 0,
				/** Animate the main grid view to fit the bounding box of specified images. Data: comma-separated image IDs. */
				flyTo = 1,
				/** Focus on images containing markers with a specific tag. Data: tag name. */
				focusWithTagged = 2,
				/** Focus on images containing markers with a specific tag and fly to the marker views. Data: tag name. */
				focusTagged = 3,
				/** Reset the grid to its initial layout and view. */
				reset = 4,
				/** Navigate back one step in the grid layout history. */
				back = 5,
				/** Instantly switch a focused image back to its position within the grid layout (used internally?). */
				switchToGrid = 6,
				/** Filter the grid to show only images that are part of the currently active marker tour. */
				filterTourImages = 7,
				/** Set a one-time crossfade duration for the *next* grid transition. Data: duration in seconds. */
				nextFadeDuration = 8
			}
		}
		/** Enums related to the Camera functionality. */
		namespace Camera {
			/**
			 * Defines the available timing functions for camera animations (flyToView, flyToCoo).
			 * These correspond to standard CSS easing functions.
			 */
			enum TimingFunction {
				'ease' = 0,// Default ease-in-out
				'ease-in' = 1,
				'ease-out' = 2,
				'linear' = 3
			}
		}
	}
	/**
	 * Represents the virtual camera used to view a {@link MicrioImage}.
	 * Provides methods for controlling the viewport (position, zoom, rotation),
	 * converting between screen and image coordinates, and managing animations.
	 *
	 * Instances are typically accessed via `micrioImage.camera`.
	 * @author Marcel Duin <marcel@micr.io>
	*/
	export class Camera {
		/** Current center screen coordinates [x, y] and scale [z]. For 360, also includes [yaw, pitch]. For Omni, also includes [frameIndex]. */
		readonly center: Models.Camera.Coords;
		/** CORRECT view: [x0, y0, width, height] */
		private readonly view;
		/**
		 * Gets the current image view rectangle.
		 * @returns A copy of the current screen viewport array, or undefined if not initialized.
		 */
		getView: () => Models.Camera.View;
		/**
		 * Gets the current image view rectangle [centerX, centerY, width, height] relative to the image (0-1).
		 * @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 opts Options for setting the view.
		 */
		setView(view: Models.Camera.View, opts?: {
			/** If true, allows setting a view outside the normal image boundaries. */
			noLimit?: boolean;
			/** If true (for 360), corrects the view based on the `trueNorth` setting. */
			correctNorth?: boolean;
			/** If true, prevents triggering a Wasm render after setting the view. */
			noRender?: boolean;
			/** If provided, interprets `view` relative to this sub-area instead of the full image. */
			area?: Models.Camera.ViewRect;
		}): void;
		/**
		 * Gets the relative image coordinates [x, y, scale, depth, yaw?, pitch?] corresponding to a screen coordinate.
		 * Rounds the result for cleaner output.
		 * @param x The screen X coordinate in pixels.
		 * @param y The screen Y coordinate in pixels.
		 * @param absolute If true, treats x/y as absolute browser window coordinates.
		 * @param noLimit If true, allows returning coordinates outside the image bounds (0-1).
		 * @returns A Float64Array containing the relative image coordinates [x, y, scale, depth, yaw?, pitch?].
		 */
		getCoo: (x: number, y: number, absolute?: boolean, noLimit?: boolean) => Float64Array;
		/**
		 * Sets the center of the screen to the specified image coordinates and scale instantly.
		 * @param x The target image X coordinate (0-1).
		 * @param y The target image Y coordinate (0-1).
		 * @param scale The target scale (optional, defaults to current scale).
		 */
		setCoo(x: number, y: number, scale?: number): void;
		/**
		 * Gets the screen coordinates [x, y, scale, depth] corresponding to relative image coordinates.
		 * @param x The image X coordinate (0-1).
		 * @param y The image Y coordinate (0-1).
		 * @param abs If true, returns absolute browser window coordinates instead of element-relative.
		 * @param radius Optional offset radius for 360 calculations.
		 * @param rotation Optional offset rotation (radians) for 360 calculations.
		 * @param noTrueNorth If true (for 360), ignores the `trueNorth` correction.
		 * @returns A Float64Array containing the screen coordinates [x, y, scale, depth].
		 */
		getXY: (x: number, y: number, abs?: boolean, radius?: number, rotation?: number, noTrueNorth?: boolean) => Float64Array;
		/** Gets the current camera zoom scale. */
		getScale: () => number;
		/**
		 * Calculates a 4x4 transformation matrix for placing an object at specific coordinates
		 * with scale and rotation in 360 space. Used for CSS `matrix3d`.
		 * @param x The image X coordinate (0-1).
		 * @param y The image Y coordinate (0-1).
		 * @param scale The object scale multiplier.
		 * @param radius The object radius (distance from center, default 10).
		 * @param rotX The object X rotation in radians.
		 * @param rotY The object Y rotation in radians.
		 * @param rotZ The object Z rotation in radians.
		 * @param transY Optional Y translation in 3D space.
		 * @param scaleX Optional non-uniform X scaling.
		 * @param scaleY Optional non-uniform Y scaling.
		 * @returns The resulting 4x4 matrix as a Float32Array.
		 */
		getMatrix(x: number, y: number, scale?: number, radius?: number, rotX?: number, rotY?: number, rotZ?: number, transY?: number, scaleX?: number, scaleY?: number, noCorrectNorth?: boolean): Float32Array;
		/**
		 * Sets the camera zoom scale instantly.
		 * @param s The target scale.
		*/
		setScale: (s: number) => void;
		/** Gets the scale at which the image fully covers the viewport. */
		getCoverScale: () => number;
		/**
		 * Gets the minimum allowed zoom scale for the image.
		 * @returns The minimum scale.
		*/
		getMinScale: () => number;
		/**
		 * Sets the minimum allowed zoom scale.
		 * @param s The minimum scale to set.
		*/
		setMinScale(s: number): void;
		/**
		 * Sets the minimum screen size the image should occupy when zooming out (0-1).
		 * Allows zooming out further than the image boundaries, creating margins.
		 * Note: Does not work with albums.
		 * @param s The minimum screen size fraction (0-1).
		*/
		setMinScreenSize(s: number): void;
		/** Returns true if the camera is currently zoomed in to its maximum limit. */
		isZoomedIn: () => boolean;
		/**
		 * Returns true if the camera is currently zoomed out to its minimum limit.
		 * @param full If true, checks against the absolute minimum scale (ignoring `setMinScreenSize`).
		*/
		isZoomedOut: (full?: boolean) => boolean;
		/**
		 * Sets a rectangular limit for camera navigation within the image.
		 * @param l The viewport limit rectangle [x0, y0, x1, y1].
		*/
		setLimit(v: Models.Camera.ViewRect): void;
		/**
		 * Sets whether the camera view should be limited to always cover the viewport.
		 * @param b If true, limits the view to cover the screen.
		*/
		setCoverLimit(b: boolean): void;
		/** Gets whether the cover limit is currently enabled. */
		getCoverLimit: () => boolean;
		/**
		 * Limits the horizontal and vertical viewing range for 360 images.
		 * @param xPerc The horizontal arc limit as a percentage (0-1, where 1 = 360°). 0 disables horizontal limit.
		 * @param yPerc The vertical arc limit as a percentage (0-1, where 1 = 180°). 0 disables vertical limit.
		*/
		set360RangeLimit(xPerc?: number, yPerc?: number): void;
		/**
		 * 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 opts Optional animation settings.
		 * @returns A Promise that resolves when the animation completes, or rejects if aborted.
		 */
		flyToView: (view: Models.Camera.ViewRect | Models.Camera.View, opts?: Models.Camera.AnimationOptions & {
			/** Set the starting animation progress percentage (0-1). */
			progress?: number;
			/** Base the progress override on this starting view. */
			prevView?: Models.Camera.View;
			/** If true, performs a "jump" animation (zooms out then in). */
			isJump?: boolean;
			/** For Omni objects: the target image frame index to animate to. */
			omniIndex?: number;
			/** If provided, interprets `view` relative to this sub-area. */
			area?: Models.Camera.ViewRect;
			/** If true, respects the image's maximum zoom limit during animation. */
			limitZoom?: boolean;
			/** If provided, adds a margin to the view. */
			margin?: [number, number];
		}) => Promise<void>;
		/**
		 * Animates the camera to a view showing the entire image (minimum zoom).
		 * @param opts Optional animation settings.
		 * @returns A Promise that resolves when the animation completes.
		 */
		flyToFullView: (opts?: Models.Camera.AnimationOptions) => Promise<void>;
		/**
		 * Animates the camera to a view where the image covers the viewport.
		 * @param opts Optional animation settings.
		 * @returns A Promise that resolves when the animation completes.
		 */
		flyToCoverView: (opts?: Models.Camera.AnimationOptions) => Promise<void>;
		/**
		 * Animates the camera to center on specific image coordinates and scale.
		 * @param coords The target coordinates [x, y, scale]. Scale is optional.
		 * @param opts Optional animation settings.
		 * @returns A Promise that resolves when the animation completes.
		 */
		flyToCoo: (coords: Models.Camera.Coords, opts?: Models.Camera.AnimationOptions) => Promise<void>;
		/**
		 * Performs an animated zoom centered on a specific screen point (or the current center).
		 * @param delta The amount to zoom (positive zooms out, negative zooms in).
		 * @param duration Forced duration in ms (0 for instant).
		 * @param x Screen pixel X-coordinate for zoom focus (optional, defaults to center).
		 * @param y Screen pixel Y-coordinate for zoom focus (optional, defaults to center).
		 * @param speed Animation speed multiplier (optional).
		 * @param noLimit If true, allows zooming beyond image boundaries.
		 * @returns A Promise that resolves when the zoom animation completes.
		 */
		zoom: (delta: number, duration?: number, x?: number | undefined, y?: number | undefined, speed?: number, noLimit?: boolean) => Promise<void>;
		/**
		 * Zooms in by a specified factor.
		 * @param factor Zoom factor (e.g., 1 = standard zoom step).
		 * @param duration Animation duration in ms.
		 * @param speed Animation speed multiplier.
		 * @returns A Promise that resolves when the animation completes.
		 */
		zoomIn: (factor?: number, duration?: number, speed?: number) => Promise<void>;
		/**
		 * Zooms out by a specified factor.
		 * @param factor Zoom factor (e.g., 1 = standard zoom step).
		 * @param duration Animation duration in ms.
		 * @param speed Animation speed multiplier.
		 * @returns A Promise that resolves when the animation completes.
		 */
		zoomOut: (factor?: number, duration?: number, speed?: number) => Promise<void>;
		/**
		 * Pans the camera view by a relative pixel amount.
		 * @param x The horizontal pixel distance to pan.
		 * @param y The vertical pixel distance to pan.
		 * @param duration Animation duration in ms (0 for instant).
		 * @param opts Options: render (force render), noLimit (allow panning outside bounds).
		*/
		pan(x: number, y: number, duration?: number, opts?: {
			render?: boolean;
			noLimit?: boolean;
		}): void;
		/** Stops any currently running camera animation immediately. */
		stop(): void;
		/** Pauses the current camera animation. */
		pause(): void;
		/** Resumes a paused camera animation. */
		resume(): void;
		/** Returns true if the camera is currently performing a kinetic pan/zoom (coasting). */
		aniIsKinetic(): boolean;
		/** Gets the current viewing direction (yaw) in 360 mode.
		 * @returns The current yaw in radians.
		 */
		getDirection: () => number;
		/**
		 * Sets the viewing direction (yaw and optionally pitch) instantly in 360 mode.
		 * @param yaw The target yaw in radians.
		 * @param pitch Optional target pitch in radians.
		*/
		setDirection(yaw: number, pitch?: number): void;
		/**
		 * Gets the current viewing pitch in 360 mode.
		 * @returns The current pitch in radians.
		*/
		getPitch: () => number;
		/**
		 * Sets the rendering area for this image within the main canvas.
		 * Used for split-screen and potentially other layout effects. Animates by default.
		 * @param v The target area rectangle [x0, y0, x1, y1] relative to the main canvas (0-1).
		 * @param opts Options for setting the area.
		 */
		setArea(v: Models.Camera.ViewRect, opts?: {
			/** If true, sets the area instantly without animation. */
			direct?: boolean;
			/** If true, prevents dispatching view updates during the animation. */
			noDispatch?: boolean;
			/** If true, prevents triggering a Wasm render after setting the area. */
			noRender?: boolean;
		}): void;
		/** Sets the 3D rotation for an embedded image (used for placing embeds in 360 space). */
		setRotation(rotX?: number, rotY?: number, rotZ?: number): void;
		/** [Omni] Gets the current rotation angle in degrees based on the active frame index. */
		getOmniRotation(): number;
		/** [Omni] Gets the frame index corresponding to a given rotation angle (radians). */
		getOmniFrame(rot?: number): number | undefined;
		/** [Omni] Gets the screen coordinates [x, y, scale, depth] for given 3D object coordinates. */
		getOmniXY(x: number, y: number, z: number): Float64Array;
		/** [Omni] Applies Omni-specific camera settings (distance, FoV, angle) to Wasm. */
		setOmniSettings(): void;
	}
	/**
	 * The main WebAssembly controller class. Handles interaction between JavaScript
	 * and the compiled C++ core of Micrio. Accessed via `micrio.wasm`.
	 */
	export class Wasm {
		micrio: HTMLMicrioElement;
		/** Flag indicating if the Wasm module has been loaded and initialized. */
		ready: boolean;
		/** Shared WebAssembly memory instance. */
		private memory;
		/** Forget in-memory tiles after X seconds not drawn */
		private deleteAfterSeconds;
		/**
		 * Creates the Wasm controller instance.
		 * @param micrio The main HTMLMicrioElement instance.
		*/
		constructor(micrio: HTMLMicrioElement);
		/**
		 * Loads and instantiates the WebAssembly module.
		 * @returns A Promise that resolves when the Wasm module is ready.
		 * @throws Error if WebAssembly binary loading or instantiation fails
		*/
		load(): Promise<void>;
		/** Unbinds event listeners, stops rendering, and cleans up resources. */
		unbind(): void;
		/**
		 * Sets the currently active canvas/image instance in the Wasm module.
		 * Handles adding the canvas to Wasm if it's not already initialized.
		 * @param canvas The MicrioImage instance to set as active.
		*/
		setCanvas(canvas?: MicrioImage): void;
		/** Removes a canvas instance from the Wasm module. */
		removeCanvas(c: MicrioImage): void;
		/** Requests the next animation frame to trigger the `draw` method. */
		render(): void;
		/** Add a child image to the current canvas, either embed or independent canvas */
		private addImage;
		/** Add a child independent canvas to the current canvas, used for grid images
		 * @param image The image
		 * @param parent The parent image
		 * @returns Promise when the image is added
		 */
		addChild: (image: MicrioImage, parent: MicrioImage) => Promise<void>;
	}
	/**
	 * Handles swipe gestures for navigating image sequences, particularly for
	 * swipe galleries and Omni object rotation.
	 * @author Marcel Duin <marcel@micr.io>
	 */
	export class GallerySwiper {
		private micrio;
		private length;
		goto: (i: number) => void;
		private opts;
		/** Getter for the current active image/frame index from the Wasm module. */
		get currentIndex(): number;
		/**
		 * Creates a GallerySwiper instance.
		 * @param micrio The main HTMLMicrioElement instance.
		 * @param length The total number of images/frames in the sequence.
		 * @param goto Callback function to navigate to a specific index.
		 * @param opts Swiper options: sensitivity, continuous looping, coverLimit.
		 */
		constructor(micrio: HTMLMicrioElement, length: number, goto: (i: number) => void, // Callback to change the active index
		opts?: {
			sensitivity?: number;
			continuous?: boolean;
			coverLimit?: boolean;
		});
		/** Cleans up event listeners when the swiper is destroyed. */
		destroy(): void;
		/**
		 * Animates smoothly to a target index using requestAnimationFrame.
		 * @param idx The target index.
		 */
		animateTo(idx: number): void;
	}
	/**
	 * # Micrio State management
	 *
	 * Manages the application state using Svelte stores, allowing reactive updates
	 * throughout the UI and providing methods to get/set the overall state.
	 * Replaces the imperative API of Micrio 3.x.
	 *
	 * Consists of two main state controllers:
	 * 1. {@link State.Main}: Global state for the `<micr-io>` element (active tour, marker, UI state).
	 * 2. {@link State.Image}: State specific to individual {@link MicrioImage} instances (view, active marker within that image).
	 *
	 * @see {@link https://doc.micr.io/client/v4/migrating.html | Migrating from Micrio 3.x}
	 * @author Marcel Duin <marcel@micr.io>
	 */
	export namespace State {
		/** Represents the entire serializable state of a Micrio instance. */
		type MicrioStateJSON = {
			/** The ID of the currently active main image. */
			id: string;
			/** Array containing the state of each individual image canvas. */
			c: ImageState[];
			/** Optional information about the currently active tour [tourId, currentTime?, pausedState?]. */
			t?: [string, number?, string?];
			/** Reference to the currently active HTMLMediaElement (unused?). */
			m?: HTMLMediaElement;
		};
		/** Represents the serializable state of a single MicrioImage instance. */
		type ImageState = [
			/** The image ID. */
			string,
			/** The current viewport x0. */
			number,
			/** The current viewport y0. */
			number,
			/** The current viewport x1. */
			number,
			/** The current viewport y1. */
			number,
			/** The ID of the currently opened marker within this image (optional). */
			string?,
			/** The UUID of the media element associated with the opened marker (optional). */
			string?,
			/** The currentTime of the marker's media element (optional). */
			number?,
			/** The paused state ('p') of the marker's media element (optional). */
			string?
		];
		/**
		* # HTMLMicrioElement state controller (`micrio.state`)
		*
		* Manages the global application state associated with the main `<micr-io>` element.
		* Provides Svelte stores for reactive UI updates and methods for state serialization.
		*/
		class Main {
			private micrio;
			/** Writable Svelte store holding the currently active tour object (VideoTour or MarkerTour), or undefined if no tour is active. */
			readonly tour: Writable<Models.ImageData.VideoTour | Models.ImageData.MarkerTour | undefined>;
			/** Getter for the current value of the {@link tour} store. */
			get $tour(): Models.ImageData.VideoTour | Models.ImageData.MarkerTour | undefined;
			/** Writable Svelte store holding the marker object currently opened in the *main* active image, or undefined if none is open. */
			readonly marker: Writable<Models.ImageData.Marker | undefined>;
			/** Writable Svelte store holding the ID of the marker currently being hovered over. */
			readonly markerHoverId: Writable<string | undefined>;
			/** Getter for the current value of the {@link marker} store. */
			get $marker(): Models.ImageData.Marker | undefined;
			/** Writable Svelte store holding the marker object whose popup is currently displayed. */
			readonly popup: Writable<Models.ImageData.Marker | undefined>;
			/** Writable Svelte store holding the data for the currently displayed popover (custom page or gallery). See {@link Models.State.PopoverType}. */
			readonly popover: Writable<Models.State.PopoverType | undefined>;
			/** UI state stores. */
			ui: {
				/** Writable store controlling the visibility of the main UI controls (bottom right). */
				controls: Writable<boolean>;
				/** Writable store controlling the visibility of zoom buttons. */
				zoom: Writable<boolean>;
				/** Writable store controlling the visibility of all UI elements (e.g., for fullscreen or specific modes). */
				hidden: Writable<boolean>;
			};
			/**
			 * Gets the current state of the Micrio viewer as a serializable JSON object.
			 * This object captures the active image(s), viewports, open markers, active tour,
			 * and media playback states, allowing the exact state to be restored later or elsewhere.
			 *
			 * @example
			 * ```javascript
			 * const currentState = micrio.state.get();
			 * // Store or transmit `currentState`
			 * ```
			 * @returns The current state as a {@link MicrioStateJSON} object, or undefined if no image is loaded.
			 */
			get(): MicrioStateJSON | undefined;
			/**
			 * Sets the Micrio viewer state from a previously saved {@link MicrioStateJSON} object.
			 * This will attempt to restore the active image, viewports, open markers, active tour,
			 * and media playback states.
			 *
			 * @example
			 * ```javascript
			 * const savedState = // ... load state object ...
			 * micrio.state.set(savedState);
			 * ```
			 * @param s The state object to load.
			 */
			set(s: MicrioStateJSON): Promise<void>;
		}
		/**
		* # MicrioImage state controller (`micrioImage.state`)
		*
		* Manages the state specific to a single {@link MicrioImage} instance,
		* primarily its viewport and currently opened marker.
		*/
		class Image {
			private image;
			/** Writable Svelte store holding the current viewport [centerX, centerY, width, height] of this image. */
			readonly view: Writable<Models.Camera.View | undefined>;
			/** Getter for the current value of the {@link view} store. */
			get $view(): Models.Camera.View | undefined;
			/**
			 * Writable Svelte store holding the currently active marker within *this specific image*.
			 * Can be set with a marker ID string or a full marker object. Setting to undefined closes the marker.
			 */
			readonly marker: Writable<Models.ImageData.Marker | string | undefined>;
			/** Getter for the current value of the {@link marker} store. */
			get $marker(): Models.ImageData.Marker | undefined;
			/** Writable Svelte store holding the currently displayed layer index (for Omni objects). */
			readonly layer: Writable<number>;
		}
	}
	/**
	 * Represents and controls a single Micrio image instance within the viewer.
	 * This class manages the image's metadata (info), cultural data (data),
	 * settings, camera, state, and interactions with the WebAssembly module
	 * for rendering and processing. It handles loading image tiles, embeds,
	 * markers, tours, and galleries associated with the image.
	 *
	 * Instances are typically created and managed by the main {@link HTMLMicrioElement}.
	 * @author Marcel Duin <marcel@micr.io>
	*/
	export class MicrioImage {
		wasm: Wasm;
		private attr;
		opts: {
			/** Optional sub area [x0, y0, x1, y1] defining placement within a parent canvas (for embeds/galleries). */
			area?: Models.Camera.ViewRect;
			/** For split screen, the primary image this one is secondary to. */
			secondaryTo?: MicrioImage;
			/** If true, passively follows the view changes of the primary split-screen image. */
			isPassive?: boolean;
			/** If true, this image is embedded within another image (affects rendering/camera). */
			isEmbed?: boolean;
			/** If true, uses the parent image's camera instead of creating its own (for switch/omni galleries). */
			useParentCamera?: boolean;
		};
		/** The unique identifier (Micrio ID) for this image. */
		id: string;
		/** A unique instance identifier (UUID) generated for this specific instance. */
		readonly uuid: string;
		/** Svelte Readable store holding the image's core information (dimensions, format, settings, etc.). See {@link Models.ImageInfo.ImageInfo}. */
		readonly info: Readable<Models.ImageInfo.ImageInfo | undefined>;
		/** Getter for the current value of the {@link info} store.
		 * @readonly
		*/
		get $info(): Models.ImageInfo.ImageInfo | undefined;
		/** Svelte Writable store holding the image's specific settings, often merged from attributes and info data. See {@link Models.ImageInfo.Settings}. */
		readonly settings: Writable<Models.ImageInfo.Settings>;
		/** Getter for the current value of the {@link settings} store. */
		get $settings(): Models.ImageInfo.Settings;
		/** Svelte Writable store holding the image's cultural data (markers, tours, text content for the current language). See {@link Models.ImageData.ImageData}. */
		readonly data: Writable<Models.ImageData.ImageData | undefined>;
		/** Getter for the current value of the {@link data} store. */
		get $data(): Models.ImageData.ImageData | undefined;
		/** State manager specific to this image instance (view, active marker, etc.). See {@link State.Image}. */
		readonly state: State.Image;
		/** The virtual camera instance controlling the view for this image. */
		camera: Camera;
		/** Svelte Writable store holding the HTMLVideoElement if this image represents a video. */
		readonly video: Writable<HTMLVideoElement | undefined>;
		/** Svelte Writable store indicating if this image's canvas is currently visible and being rendered.
		 * @readonly
		*/
		readonly visible: Writable<boolean>;
		/** Album information if this image is part of a V5 album. */
		album?: Models.Album | undefined;
		/** Gallery swiper instance, if this image is part of a swipe gallery. */
		swiper: GallerySwiper | undefined;
		/** Stores the camera view state when a marker is opened, used to return to the previous view. */
		openedView: Models.Camera.View | undefined;
		/** Base path URI for fetching `data.[lang].json` files. */
		dataPath: string;
		/** Stores an error message if loading failed. */
		error: string | undefined;
		/** Svelte Writable store holding the calculated pixel viewport [left, top, width, height] of this image within the main canvas. */
		readonly viewport: Writable<Models.Camera.ViewRect>;
		/** Array of child {@link MicrioImage} instances embedded within this image. */
		readonly embeds: MicrioImage[];
		/** Grid controller instance, if this image is a grid container. */
		grid: Grid | undefined;
		/** Base path for fetching image tiles. */
		tileBase: string | undefined;
		/**
		 * Adds an embedded MicrioImage (representing another Micrio image or video) within this image.
		 * @param info Partial info data for the embed.
		 * @param area The placement area `[x0, y0, x1, y1]` within the parent image.
		 * @param opts Embedding options (opacity, fit, etc.).
		 * @returns The newly created embedded {@link MicrioImage} instance.
		 */
		addEmbed(info: Partial<Models.ImageInfo.ImageInfo>, area: Models.Camera.ViewRect, opts?: Models.Embeds.EmbedOptions): MicrioImage;
		/** Gets the HTMLMediaElement associated with a video embed ID. */
		getEmbedMediaElement(id: string): HTMLMediaElement | undefined;
		/** Fades in the image smoothly or instantly. */
		fadeIn(direct?: boolean): void;
		/** Fades out the image smoothly or instantly. */
		fadeOut(direct?: boolean): void;
	}
	/**
	 * Micrio grid display controller
	 * @author Marcel Duin <marcel@micr.io>
	 */
	/**
	 * Controls the display and interaction logic for grid layouts.
	 * Instantiated on the primary {@link MicrioImage} if grid data is present.
	 * Accessed via `micrioImage.grid`.
	 */
	export class Grid {
		micrio: HTMLMicrioElement;
		image: MicrioImage;
		/** Array of {@link MicrioImage} instances currently part of the grid definition (loaded). */
		readonly images: MicrioImage[];
		/** Array of {@link MicrioImage} instances currently visible in the grid layout. */
		current: MicrioImage[];
		/** If true, the HTML grid overlay remains visible and interactive even when an image is focused. */
		clickable: boolean;
		/** Writable Svelte store holding the currently focused {@link MicrioImage} instance, or undefined if in grid view. */
		readonly focussed: Writable<MicrioImage | undefined>;
		/** Getter for the current value of the {@link focussed} store. */
		get $focussed(): MicrioImage | undefined;
		/** Writable Svelte store holding an array of {@link MicrioImage} instances whose markers should be displayed in the grid view. */
		readonly markersShown: Writable<MicrioImage[]>;
		/** Array storing the history of grid layouts for back navigation. */
		history: Models.Grid.GridHistory[];
		/** Writable Svelte store indicating the current depth in the grid history stack. */
		depth: Writable<number>;
		/** Default animation duration (seconds) when transitioning *into* a new layout or focused view. */
		aniDurationIn: number;
		/** Default animation duration (seconds) when transitioning *out* of a focused view or going back in history. */
		aniDurationOut: number;
		/** Delay (seconds) between individual image transitions for 'delayed' effects. */
		transitionDelay: number;
		/**
		 * The Grid constructor. Initializes the grid based on image settings.
		 * @param micrio The main HTMLMicrioElement instance.
		 * @param image The MicrioImage instance acting as the virtual container for the grid.
		*/
		constructor(micrio: HTMLMicrioElement, image: MicrioImage);
		/**
		 * Sets the grid layout based on an input string or array of image definitions.
		 * This is the main method for changing the grid's content and appearance.
		 *
		 * @param input The grid definition. Can be:
		 *   - A semicolon-separated string following the format defined in `Grid.getString`.
		 *   - An array of {@link MicrioImage} instances.
		 *   - An array of objects `{image: MicrioImage, ...GridImageOptions}`.
		 * @param opts Options controlling the transition and layout.
		 * @returns A Promise that resolves with the array of currently displayed {@link MicrioImage} instances when the transition completes.
		*/
		set(input?: string | MicrioImage[] | ({
			image: MicrioImage;
		} & Models.Grid.GridImageOptions)[], opts?: {
			/** If true, does not add the previous layout to the history stack. */
			noHistory?: boolean;
			/** If true, keeps the HTML grid element in the DOM (used internally). */
			keepGrid?: boolean;
			/** If true, arranges images in a single horizontal row. */
			horizontal?: boolean;
			/** Overrides the default animation duration for the main grid view transition. */
			duration?: number;
			/** If provided, animates the main grid view to this viewport rectangle. */
			view?: Models.Camera.View;
			/** If true, skips the main grid camera animation. */
			noCamAni?: boolean;
			/** If true, forces area animation even for images not currently visible. */
			forceAreaAni?: boolean;
			/** If true, does not unfocus the currently focused image when setting a new layout. */
			noBlur?: boolean;
			/** If true, skips the fade-in animation for new images. */
			noFade?: boolean;
			/** Specifies the transition animation type (e.g., 'crossfade', 'slide-left', 'behind-delayed'). */
			transition?: Models.Grid.GridSetTransition;
			/** If true, forces animation even if duration is 0. */
			forceAni?: boolean;
			/** If true, limits individual image views to cover their grid cell. */
			coverLimit?: boolean;
			/** If true, sets the initial view of images to cover their grid cell (but doesn't enforce limit). */
			cover?: boolean;
			/** Scale factor (0-1) applied to each grid cell (creates margins). */
			scale?: number;
			/** Overrides the automatic calculation of grid columns. */
			columns?: number;
		}): Promise<MicrioImage[]>;
		/**
		 * Parses an individual image grid string into a GridImage object.
		 * @param s The grid string for a single image.
		 * @returns The parsed `Models.Grid.GridImage` object.
		*/
		getImage(s: string): Models.Grid.GridImage;
		/**
		 * Converts an ImageInfo object and options back into the grid string format.
		 * @returns The grid encoded string for this image.
		*/
		getString: (i: Models.ImageInfo.ImageInfo, opts?: Models.Grid.GridImageOptions) => string;
		/** Fade out unused images in the grid
		 * @param images The images to hide
		*/
		private removeImages;
		/** Checks whether current viewed image is (part of) grid */
		insideGrid(): boolean;
		/** Reset the grid to its initial layout
		 * @param duration Duration in seconds
		 * @param noCamAni Don't do any camera animating
		 * @param forceAni Force animation on all grid images
		 * @returns Promise when the transition is complete
		*/
		reset(duration?: number, noCamAni?: boolean, forceAni?: boolean): Promise<MicrioImage[]>;
		/** Fly to the viewports of any markers containing a class name
		 * @param tag The class name to match
		 * @param duration Optional duration in ms
		 * @param noZoom Don't zoom into the markers, just filter the images
		 * @returns Promise when the transition is complete
		*/
		flyToMarkers(tag?: string, duration?: number, noZoom?: boolean): Promise<MicrioImage[]>;
		/** Go back one step in the grid history
		 * @param duration Optional duration for transition
		 * @returns Promise when the transition is complete
		*/
		back(duration?: number): Promise<void>;
		/** Open a grid image full size and set it as the main active image
		 * @param img The image
		 * @param opts Focus options
		 * @returns Promise for when the transition completes
		*/
		focus(img: MicrioImage | undefined, opts?: Models.Grid.FocusOptions): Promise<void>;
		/** Unfocusses any currently focussed image */
		blur(): void;
		/** Do an (external) action
		 * @param action The action type enum or string
		 * @param data Optional action data
		 * @param duration Optional action duration
		*/
		action(action: Enums.Grid.GridActionType | string, data?: string, duration?: number): void;
		/** Enlarge a specific image idx of the currently shown grid
		 * @param idx The image index of the current grid
		 * @param width The image target number of columns
		 * @param height The image target number of rows
		 * @returns Promise when the transition is completed
		*/
		enlarge(idx: number, width: number, height?: number): Promise<MicrioImage[]>;
		/** Get the relative in-grid viewport of the image */
		getRelativeView(image: MicrioImage, view: Models.Camera.ViewRect): Models.Camera.ViewRect;
	}
	/**
	 * Video tour controller. Manages playback and camera animation for video tours
	 * defined by a timeline of view rectangles and durations.
	 * @author Marcel Duin <marcel@micr.io>
	 */
	/**
	 * Controls the playback of a video tour, animating the camera according
	 * to a predefined timeline and synchronizing with associated audio/video media.
	 * Instances are typically created and managed by the `Tour.svelte` component.
	 */
	export class VideoTourInstance {
		private image;
		private data;
		/**
		 * Creates a VideoTourInstance.
		 * @param image The parent {@link MicrioImage} instance.
		 * @param data The {@link Models.ImageData.VideoTour} data object.
		 */
		constructor(image: MicrioImage, data: Models.ImageData.VideoTour);
		/** Cleans up the tour instance, stops animations, and re-hooks events if necessary. */
		destroy(): void;
		/** Parses the raw timeline data from the tour content into the internal `timeline` array. */
		read(): void;
		/** Getter for the total duration of the tour in seconds. */
		get duration(): number;
		/** Setter for the total duration (updates internal content). */
		set duration(v: number);
		/** Getter for the current paused state. */
		get paused(): boolean;
		/** Getter indicating if the tour has ended. */
		get ended(): boolean;
		/** Getter for the current playback time in seconds. */
		get currentTime(): number;
		/** Setter for the current playback time (seeks to the corresponding progress). */
		set currentTime(v: number);
		/** Getter for the current progress percentage (0-1). */
		get progress(): number;
		/** Setter for the current progress percentage (seeks to that point). */
		set progress(v: number);
		/** Starts or resumes tour playback. */
		play(): void;
		/** Pauses the tour playback. */
		pause(): void;
		/**
		 * Seeks the tour to a specific progress percentage.
		 * @param perc The target progress (0-1).
		 */
		private setProgress;
	}
	/**
	 * # Micrio JSON data model
	 *
	 * This page details the data models used by Micrio.
	 *
	 * This data is created in the [Micrio editor](https://dash.micr.io/), and published as static JSON file per image, and optionally any language-specific data such as image markers, tours, audio, etc.
	 *
	 * Each Micrio image uses two data sources, which are retrieved from the Micrio servers:
	 *
	 * 1. **{@link ImageInfo}**: `info.json`: the base image data such as resolution, image type, and basic image settings. This is accessible in JS as {@link MicrioImage.info} as the Readable store, and {@link MicrioImage.$info} for its current value.
	 *
	 * 2. **{@link ImageData}**: `pub.json`: all published image content, which is accessible in JS as {@link MicrioImage.data} as the Writable store, and {@link MicrioImage.$data} for its current value.
	 *
	 */
	export namespace Models {
		type RevisionType = {
			[key: string]: number;
		};
		/**
		 * # Base image data
		 *
		 * The MicrioData.ImageInfo.ImageInfo JSON data object, used to pass to {@link HTMLMicrioElement.open}.
		 *
		 * The static image information, such as original resolution, image type, title, and all non-language specific **settings** ({@link ImageInfo.Settings}), such as initial viewport, camera behavior, and 360&deg; settings.
		 *
		 * The only required field is `id`. If only the `id` field is specified, Micrio attempts to download the additional image data by itself (`info.json`), published by the Micrio servers. This data will also include image title, and any custom viewing settings set in the image editor.
		 *
		 * This is a minimal accepted example:
		 *
		 * ```json
		 * {
		 * 	"id": "dzzLm",
		 * }
		 * ```
		 *
		 * If you have manually entered the image `width` and `height`, _it will not download_ the `info.json` file, assuming you have provided correct and complete data:
		 *
		 * ```json
		 * {
		 * 	"id": "dzzLm",
		 * 	"width": 41472,
		 * 	"height": 30219
		 * }
		 * ```
		 *
		 * Optionally, when using {@link HTMLMicrioElement} `<micr-io>` tag attributes, these will overwrite whatever is loaded from the server. So if in the Micrio editor you have enabled the fullscreen toggle button, you can disable it in your own HTML using `<micr-io data-fullscreen="false">`.
		 *
		 *
		 */
		namespace ImageInfo {
			/** A Micrio image's main static image data object */
			type ImageInfo = {
				/** The image id */
				id: string;
				/** The image base path URI, with a trailing `/`
				 * @default https://b.micr.io/
				*/
				path: string;
				/** The Micrio version this image was created in
				 * @default autoloaded
				*/
				version: string;
				/** Created date */
				created?: number;
				/** Has new viewport model, optimized for 360 images */
				viewsWH?: boolean;
				/** For V5+: published revisions per language */
				revision?: RevisionType;
				/** The original image width
				 * @default autoloaded
				*/
				width: number;
				/** The original image height
				 * @default autoloaded
				*/
				height: number;
				/** The original tile size in px
				 * @default autoloaded
				*/
				tileSize: number;
				/** Use an alternative image ID for the image tiles */
				tilesId?: string;
				/** Use an alternative basePath for image tiles */
				tileBasePath?: string;
				/** Optional custom file extension for tiles */
				tileExtension?: string;
				/** Optional watermark image URI */
				watermark?: string;
				/** Force the `path` attribute to be used to get the info.json data */
				forceInfoPath?: boolean;
				/** The image settings, such as viewport/UI settings, camera and user event behavior
				 * NOTE: to modify this at runtime, use the MicrioImage.settings Writable store.
				*/
				settings?: Partial<ImageInfo.Settings>;
				/** Optional organisation data */
				organisation?: ImageInfo.Organisation;
				/** The image title (default: autoloaded) */
				title?: string;
				/** The initial data language */
				lang?: string;
				/** The image is 360 degrees */
				is360?: boolean;
				/** The image tiles are in WebP format */
				isWebP?: boolean;
				/** The image tiles are in PNG format */
				isPng?: boolean;
				/** The tiled image is in DeepZoom format */
				isDeepZoom?: boolean;
				/** The image has a IIIF source */
				isIIIF?: boolean;
				/** Use a custom, single source uri for the zoomable image / video */
				isSingle?: boolean;
				/** A custom format (`dz` for DeepZoom, `iiif` for IIIF) */
				format?: string;
				/** Optional IIIF source for tiles */
				iiifManifest?: string;
				/** The album (V5+) ID */
				albumId?: string;
				/** Single-canvas sequence -- IIIF Presentation API 3 */
				type?: ('Manifest' | 'Canvas' | 'AnnotationPage' | 'Annotation' | 'Image');
				items?: Partial<ImageInfo.ImageInfo>[];
				body?: Partial<ImageInfo.ImageInfo> & {
					format: string;
					width: number;
					height: number;
					service: {
						id: string;
						type: 'ImageService3';
					}[];
				};
				/** The 360 tour space ID */
				spacesId?: string;
			};
			interface Organisation {
				name: string;
				slug: string;
				baseUrl?: string;
				href?: string;
				logo?: Assets.Image;
				gtmId?: string;
				branding?: boolean;
				fontFamily?: string;
			}
			/** Micrio image settings, which is on load included as {@link ImageInfo}`.settings`. */
			type Settings = {
				/** The starting viewport */
				view?: Camera.View;
				/** Restrict navigation to this viewport (`[x0,y0,x1,y1]`) */
				restrict?: Camera.View;
				/** Load a cover-initing image focussed on this coordinate (`[x, y]`) */
				focus?: [number, number];
				/** When opening the image without a predefined deeplink, open this */
				start?: {
					type: ('marker' | 'markerTour' | 'tour' | 'page');
					id: string;
				};
				/** Use a custom uri for the info json file */
				infoUrl?: string;
				/** Force refresh for published data JSON file */
				forceDataRefresh?: boolean;
				/** Render this image as a static image */
				static?: boolean;
				/** Use a custom thumbnail image uri */
				thumbSrc?: string;
				/** The starting viewport. Possible values `cover` and `contain`. Defaults to `contain` */
				initType?: string;
				/** The user cannot zoom out more than a fully covered view */
				limitToCoverScale?: boolean;
				/** Initialize the image when the container is scrolled into view (default: `false`) */
				lazyload?: number;
				/** Don't load any custom JS or CSS scripts */
				noExternals?: boolean;
				/** Don't load this image's {@link ImageData.ImageData} (markers, tours, etc) */
				skipMeta?: boolean;
				/** Don't auto-load first available non-preferred data language */
				onlyPreferredLang?: boolean;
				/** Do a crossfade when navigating between images (default: true) */
				fadeBetween?: boolean;
				/** Optional image crossfade duration, in seconds */
				crossfadeDuration?: number;
				/** Embedded images/videos fade in/out duration, in seconds */
				embedFadeDuration?: number;
				/** When being re-shown, always restart */
				embedRestartWhenShown?: boolean;
				/** Don't stop drawing frames when idle */
				keepRendering?: boolean;
				/** Don't load GTM module */
				noGTag?: boolean;
				/** With routing enabled, enable marker/tour deeplinks */
				routerMarkerTours?: boolean;
				/** Skip the deepest zoom levels */
				skipBaseLevels?: number;
				/** The camera animation speed (default: 1) */
				camspeed?: number;
				/** Kinetic dragging sensitivity (default: 1) */
				dragElasticity?: number;
				/** The maximum zoom level in % of the original (default: 1) */
				zoomLimit?: number;
				/** Turn off support for high DPI screens */
				noRetina?: boolean;
				/** Adjust the maximum zoom of high DPI screens to that of regular displays */
				zoomLimitDPRFix?: boolean;
				/** Allow the user to pan and zoom out of image bounds */
				freeMove?: boolean;
				/** When navigating back to this image from another image, reset the initial view */
				resetView?: boolean;
				/** Don't smooth out pixels when zooming in > 100% */
				noSmoothing?: boolean;
				/** Hook user events (default: true) */
				hookEvents?: boolean;
				/** Hook keyboard controls (default: false) */
				hookKeys?: boolean;
				/** Don't allow the user to zoom in or out */
				noZoom?: boolean;
				/** Use the mousewheel or trackpad scrolling for zooming (default: true) */
				hookScroll?: boolean;
				/** Allow pinch to zoom on touch devi