@frybynite/image-cloud 0.5.2 → 0.6.0

package/dist/web-component.d.ts

@@ -1 +1,1654 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web-component/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,MAAM,CAAC,kBAAkB,WAAkC;IAE3D,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,UAAU,CAA+B;IAEjD,iBAAiB,IAAI,IAAI;IAQzB,oBAAoB,IAAI,IAAI;IAQ5B,wBAAwB,CACtB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI;IAQP,WAAW,IAAI,UAAU,GAAG,IAAI;IAIhC,OAAO,CAAC,WAAW;IAmCnB,OAAO,CAAC,KAAK;IAsBb,OAAO,CAAC,QAAQ;CAIjB;AAQD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,kBAAkB,GACnB,MAAM,iBAAiB,CAAC"}
+declare interface AdaptiveSizingResult {
+    height: number;
+}
+
+/**
+ * Animate an element along a path using requestAnimationFrame
+ */
+export declare function animatePath(options: PathAnimationOptions): void;
+
+export declare interface AnimationConfig {
+    duration: number;
+    easing: AnimationEasingConfig;
+    queue: AnimationQueueConfig;
+    performance?: AnimationPerformanceConfig;
+    entry?: EntryAnimationConfig;
+}
+
+declare interface AnimationEasingConfig {
+    default: string;
+    bounce: string;
+    focus: string;
+}
+
+export declare class AnimationEngine {
+    private config;
+    private activeAnimations;
+    private animationIdCounter;
+    constructor(config: AnimationConfig);
+    /**
+     * Build transform string from transform params
+     * Always starts with centering transform to match image positioning system
+     */
+    private buildTransformString;
+    /**
+     * Start a cancellable transform animation using Web Animations API
+     * @param element - The element to animate
+     * @param from - Starting transform state
+     * @param to - Ending transform state
+     * @param duration - Animation duration in ms (optional)
+     * @param easing - CSS easing function (optional)
+     * @returns AnimationHandle that can be used to cancel or query the animation
+     */
+    animateTransformCancellable(element: HTMLElement, from: TransformParams, to: TransformParams, duration?: number | null, easing?: string | null): AnimationHandle;
+    /**
+     * Cancel an active animation
+     * @param handle - The animation handle to cancel
+     * @param commitStyle - If true, keeps current position; if false, no style change
+     * @returns Snapshot of where the animation was when cancelled
+     */
+    cancelAnimation(handle: AnimationHandle, commitStyle?: boolean): AnimationSnapshot;
+    /**
+     * Cancel all animations on an element
+     * Uses Web Animations API to find and cancel ALL animations, not just tracked ones
+     * @param element - The element to cancel animations for
+     */
+    cancelAllAnimations(element: HTMLElement): void;
+    /**
+     * Get current transform state of an element (works mid-animation)
+     * Uses DOMMatrix to parse the computed transform
+     * @param element - The element to query
+     * @returns Current transform snapshot
+     */
+    getCurrentTransform(element: HTMLElement): AnimationSnapshot;
+    /**
+     * Check if an element has an active animation
+     * @param element - The element to check
+     * @returns True if animation is in progress
+     */
+    hasActiveAnimation(element: HTMLElement): boolean;
+    /**
+     * Get animation handle for an element if it exists
+     * @param element - The element to query
+     * @returns AnimationHandle or undefined
+     */
+    getAnimationHandle(element: HTMLElement): AnimationHandle | undefined;
+    /**
+     * Animate element transform with smooth easing (CSS transitions - legacy method)
+     * @param element - The element to animate
+     * @param properties - Transform properties {x, y, rotation, scale}
+     * @param duration - Animation duration in ms (optional)
+     * @param easing - CSS easing function (optional)
+     * @returns Promise that resolves when animation completes
+     */
+    animateTransform(element: HTMLElement, properties: TransformParams, duration?: number | null, easing?: string | null): Promise<void>;
+    /**
+     * Reset element to its original transform
+     * @param element - The element to reset
+     * @param originalState - Original transform state {x, y, rotation, scale}
+     * @returns Promise that resolves when animation completes
+     */
+    resetTransform(element: HTMLElement, originalState: TransformParams | ImageLayout): Promise<void>;
+    /**
+     * Remove transition styles from element
+     * @param element - The element to clear
+     */
+    clearTransition(element: HTMLElement): void;
+    /**
+     * Utility: Wait for a specified duration
+     * @param ms - Milliseconds to wait
+     * @returns Promise that resolves after the specified duration
+     */
+    wait(ms: number): Promise<void>;
+}
+
+/**
+ * Handle for a cancellable animation using Web Animations API
+ */
+declare interface AnimationHandle {
+    id: string;
+    element: HTMLElement;
+    animation: Animation;
+    fromState: TransformParams;
+    toState: TransformParams;
+    startTime: number;
+    duration: number;
+}
+
+declare interface AnimationParams {
+    startTransform: string;
+    duration: number;
+    delay: number;
+    easing: string;
+}
+
+declare interface AnimationPerformanceConfig {
+    useGPU?: boolean;
+    reduceMotion?: boolean;
+}
+
+declare interface AnimationQueueConfig {
+    enabled: boolean;
+    interval: number;
+    maxConcurrent?: number;
+}
+
+/**
+ * Snapshot of an element's current transform state
+ * Used for capturing position mid-animation
+ */
+declare interface AnimationSnapshot {
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+}
+
+declare interface BorderConfig {
+    width?: number;
+    color?: string;
+    radius?: number;
+    style?: BorderStyle;
+}
+
+export declare type BorderStyle = 'solid' | 'dashed' | 'dotted' | 'double' | 'none' | 'groove' | 'ridge' | 'inset' | 'outset' | 'hidden';
+
+/**
+ * Bounce path presets - overshoot and settle animations
+ */
+export declare const BOUNCE_PRESETS: Record<BouncePreset, BouncePathConfig>;
+
+export declare interface BouncePathConfig {
+    overshoot: number;
+    bounces: 1 | 2 | 3;
+    decayRatio: number;
+}
+
+export declare type BouncePreset = 'energetic' | 'playful' | 'subtle';
+
+export declare interface ClusterAlgorithmConfig {
+    clusterCount: number | 'auto';
+    clusterSpread: number;
+    clusterSpacing: number;
+    density: 'uniform' | 'varied';
+    overlap: number;
+    distribution: 'gaussian' | 'uniform';
+}
+
+declare interface ClusterLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class ClusterPlacementLayout implements PlacementLayout {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate cluster layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides (includes fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: ClusterLayoutOptions): ImageLayout[];
+    /**
+     * Calculate optimal number of clusters based on image count and container
+     */
+    private calculateClusterCount;
+    /**
+     * Generate cluster center positions with spacing constraints
+     */
+    private generateClusterCenters;
+    /**
+     * Calculate spread for a cluster (may vary if density='varied')
+     */
+    private calculateClusterSpread;
+    /**
+     * Generate a random number with approximately Gaussian distribution
+     * Using Box-Muller transform
+     */
+    private gaussianRandom;
+    /**
+     * Utility: Generate random number between min and max
+     */
+    private random;
+}
+
+export declare class CompositeLoader implements ImageLoader {
+    private loaders;
+    private debugLogging;
+    private _prepared;
+    private _discoveredUrls;
+    constructor(config: CompositeLoaderConfig);
+    /**
+     * Prepare all loaders in parallel and combine their results
+     * @param filter - Filter to apply to discovered images
+     */
+    prepare(filter: IImageFilter): Promise<void>;
+    /**
+     * Get the combined number of discovered images
+     * @throws Error if called before prepare()
+     */
+    imagesLength(): number;
+    /**
+     * Get the combined ordered list of image URLs
+     * @throws Error if called before prepare()
+     */
+    imageURLs(): string[];
+    /**
+     * Check if the loader has been prepared
+     */
+    isPrepared(): boolean;
+    /**
+     * Debug logging helper
+     * @param args - Arguments to log
+     */
+    private log;
+}
+
+export declare interface CompositeLoaderConfig {
+    loaders: ImageLoader[];
+    debugLogging?: boolean;
+}
+
+export declare interface ConfigSection {
+    loaders?: SharedLoaderConfig;
+    debug?: DebugConfig;
+}
+
+export declare interface ContainerBounds {
+    width: number;
+    height: number;
+}
+
+export declare interface DebugConfig {
+    enabled?: boolean;
+    centers?: boolean;
+    loaders?: boolean;
+}
+
+export declare const DEFAULT_CONFIG: ImageCloudConfig;
+
+/**
+ * Default shared loader configuration
+ */
+export declare const DEFAULT_SHARED_LOADER_CONFIG: SharedLoaderConfig;
+
+declare interface DropShadowConfig {
+    x: number;
+    y: number;
+    blur: number;
+    color: string;
+}
+
+/**
+ * Elastic path presets - spring-like oscillation animations
+ */
+export declare const ELASTIC_PRESETS: Record<ElasticPreset, ElasticPathConfig>;
+
+export declare interface ElasticPathConfig {
+    stiffness: number;
+    damping: number;
+    mass: number;
+    oscillations: number;
+}
+
+export declare type ElasticPreset = 'gentle' | 'bouncy' | 'wobbly' | 'snappy';
+
+declare interface EntryAnimationConfig {
+    start: EntryStartConfig;
+    timing: EntryTimingConfig;
+    easing: string;
+    path?: EntryPathConfig;
+    rotation?: EntryRotationConfig;
+    scale?: EntryScaleConfig;
+}
+
+export declare class EntryAnimationEngine {
+    private config;
+    private layoutAlgorithm;
+    private resolvedStartPosition;
+    private pathConfig;
+    private rotationConfig;
+    private scaleConfig;
+    constructor(config: EntryAnimationConfig, layoutAlgorithm: LayoutAlgorithm);
+    /**
+     * Get the effective start position, considering layout-aware defaults
+     */
+    private resolveStartPosition;
+    /**
+     * Calculate the starting position for an image's entry animation
+     */
+    calculateStartPosition(finalPosition: {
+        x: number;
+        y: number;
+    }, imageSize: {
+        width: number;
+        height: number;
+    }, containerBounds: ContainerBounds, imageIndex: number, totalImages: number): StartPosition;
+    /**
+     * Calculate start position from the nearest edge (current default behavior)
+     */
+    private calculateNearestEdge;
+    /**
+     * Calculate start position from a specific edge
+     */
+    private calculateEdgePosition;
+    /**
+     * Calculate start position from center with scale animation
+     */
+    private calculateCenterPosition;
+    /**
+     * Calculate start position from a random edge
+     */
+    private calculateRandomEdge;
+    /**
+     * Calculate start position on a circle around the container
+     */
+    private calculateCircularPosition;
+    /**
+     * Get animation parameters for an image
+     */
+    getAnimationParams(_imageIndex: number): AnimationParams;
+    /**
+     * Build a CSS transform string for the start position
+     * Uses pixel-based centering offset for reliable cross-browser behavior
+     */
+    buildStartTransform(startPosition: StartPosition, finalPosition: {
+        x: number;
+        y: number;
+    }, finalRotation: number, finalScale: number, imageWidth?: number, imageHeight?: number, startRotation?: number, startScale?: number): string;
+    /**
+     * Build the final CSS transform string
+     * Uses pixel-based centering offset for reliable cross-browser behavior
+     */
+    buildFinalTransform(rotation: number, scale: number, imageWidth?: number, imageHeight?: number): string;
+    /**
+     * Get the transition CSS for entry animation
+     * For JS-animated paths, only animate opacity (transform handled by JS)
+     */
+    getTransitionCSS(): string;
+    /**
+     * Check if the current path type requires JavaScript animation
+     */
+    requiresJSAnimation(): boolean;
+    /**
+     * Get the path configuration
+     */
+    getPathConfig(): EntryPathConfig;
+    /**
+     * Get the path type
+     */
+    getPathType(): EntryPathType;
+    /**
+     * Get animation timing configuration
+     */
+    getTiming(): {
+        duration: number;
+    };
+    /**
+     * Get the rotation configuration
+     */
+    getRotationConfig(): EntryRotationConfig;
+    /**
+     * Get the rotation mode
+     */
+    getRotationMode(): EntryRotationMode;
+    /**
+     * Calculate the starting rotation for an entry animation
+     * @param finalRotation - The final rotation from the layout
+     * @returns The starting rotation in degrees
+     */
+    calculateStartRotation(finalRotation: number): number;
+    /**
+     * Resolve spin direction based on config
+     * @returns 1 for clockwise, -1 for counterclockwise
+     */
+    private resolveSpinDirection;
+    /**
+     * Check if the current rotation mode requires JavaScript animation
+     * (as opposed to CSS transitions)
+     */
+    requiresJSRotation(): boolean;
+    /**
+     * Calculate wobble rotation for a given animation progress
+     * @param progress - Animation progress from 0 to 1
+     * @param finalRotation - The final rotation in degrees
+     * @returns The current rotation in degrees
+     */
+    calculateWobbleRotation(progress: number, finalRotation: number): number;
+    /**
+     * Get the scale configuration
+     */
+    getScaleConfig(): EntryScaleConfig;
+    /**
+     * Get the scale mode
+     */
+    getScaleMode(): EntryScaleMode;
+    /**
+     * Calculate the starting scale for an entry animation
+     * @param finalScale - The final scale from the layout
+     * @returns The starting scale
+     */
+    calculateStartScale(finalScale: number): number;
+    /**
+     * Check if the current scale mode requires JavaScript animation
+     * (as opposed to CSS transitions)
+     */
+    requiresJSScale(): boolean;
+    /**
+     * Calculate pop scale for a given animation progress
+     * @param progress - Animation progress from 0 to 1
+     * @param finalScale - The final scale value
+     * @returns The current scale value with bounce effect
+     */
+    calculatePopScale(progress: number, finalScale: number): number;
+    /**
+     * Generate keyframes for scale bounce animation
+     */
+    private generateScaleBounceKeyframes;
+    /**
+     * Easing function for smooth transitions
+     */
+    private easeOutQuad;
+}
+
+declare interface EntryCircularConfig {
+    radius?: number | string;
+    distribution?: 'even' | 'random';
+}
+
+export declare interface EntryPathConfig {
+    type: EntryPathType;
+    bouncePreset?: BouncePreset;
+    elasticPreset?: ElasticPreset;
+    wavePreset?: WavePathPreset;
+    bounce?: Partial<BouncePathConfig>;
+    elastic?: Partial<ElasticPathConfig>;
+    wave?: Partial<WavePathConfig>;
+}
+
+export declare type EntryPathType = 'linear' | 'arc' | 'bounce' | 'elastic' | 'wave';
+
+declare interface EntryRotationConfig {
+    mode: EntryRotationMode;
+    startRotation?: number | {
+        min: number;
+        max: number;
+    };
+    spinCount?: number;
+    direction?: 'clockwise' | 'counterclockwise' | 'auto' | 'random';
+    wobble?: {
+        amplitude: number;
+        frequency: number;
+        decay: boolean;
+    };
+}
+
+declare type EntryRotationMode = 'none' | 'settle' | 'spin' | 'wobble' | 'random';
+
+declare interface EntryScaleConfig {
+    mode: EntryScaleMode;
+    startScale?: number;
+    range?: {
+        min: number;
+        max: number;
+    };
+    pop?: EntryScalePopConfig;
+}
+
+declare type EntryScaleMode = 'none' | 'grow' | 'shrink' | 'pop' | 'random';
+
+declare interface EntryScalePopConfig {
+    overshoot: number;
+    bounces: number;
+}
+
+declare interface EntryStartConfig {
+    position: EntryStartPosition;
+    offset?: number;
+    circular?: EntryCircularConfig;
+}
+
+declare type EntryStartPosition = 'nearest-edge' | 'top' | 'bottom' | 'left' | 'right' | 'center' | 'random-edge' | 'circular';
+
+declare interface EntryTimingConfig {
+    duration: number;
+}
+
+declare interface FilterConfig {
+    grayscale?: number;
+    blur?: number;
+    brightness?: number;
+    contrast?: number;
+    saturate?: number;
+    opacity?: number;
+    sepia?: number;
+    hueRotate?: number;
+    invert?: number;
+    dropShadow?: DropShadowConfig | string;
+}
+
+/**
+ * Fixed mode height configuration with responsive breakpoints
+ * At least one of mobile, tablet, or screen is required
+ */
+declare interface FixedModeHeight {
+    mobile?: number;
+    tablet?: number;
+    screen?: number;
+}
+
+declare interface FocusInteractionConfig {
+    scalePercent: number;
+    zIndex: number;
+    animationDuration?: number;
+}
+
+/**
+ * Minimal functional CSS required for the library to work.
+ * Injected automatically - no external CSS file needed.
+ */
+export declare const FUNCTIONAL_CSS = "\n.fbn-ic-gallery {\n  position: relative;\n  width: 100%;\n  height: 100%;\n  overflow: hidden;\n  perspective: 1000px;\n}\n\n.fbn-ic-image {\n  position: absolute;\n  cursor: pointer;\n  transition: transform 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    box-shadow 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    filter 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    border 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    outline 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    z-index 0s 0.6s;\n  will-change: transform;\n  user-select: none;\n  backface-visibility: hidden;\n  -webkit-backface-visibility: hidden;\n}\n\n.fbn-ic-image.fbn-ic-focused {\n  z-index: 1000;\n  transition: transform 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    box-shadow 0.6s cubic-bezier(0.4, 0, 0.2, 1),\n    filter 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    border 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    outline 0.3s cubic-bezier(0.4, 0, 0.2, 1),\n    z-index 0s 0s;\n  will-change: auto;\n}\n\n.fbn-ic-counter {\n  position: fixed;\n  bottom: 24px;\n  left: 50%;\n  transform: translateX(-50%);\n  z-index: 10001;\n  pointer-events: none;\n}\n\n.fbn-ic-hidden {\n  display: none !important;\n}\n";
+
+export declare type GalleryConfig = ImageCloudConfig;
+
+declare interface GestureInteractionConfig {
+    pinchToZoom?: boolean;
+    doubleTapToFocus?: boolean;
+}
+
+export declare interface GoogleDriveFilesSource {
+    files: string[];
+}
+
+export declare interface GoogleDriveFolderSource {
+    folders: string[];
+    recursive?: boolean;
+}
+
+export declare class GoogleDriveLoader implements ImageLoader {
+    private apiKey;
+    private apiEndpoint;
+    private debugLogging;
+    private sources;
+    private _prepared;
+    private _discoveredUrls;
+    constructor(config: GoogleDriveLoaderInnerConfig);
+    /**
+     * Prepare the loader by discovering all images from configured sources
+     * @param filter - Filter to apply to discovered images
+     */
+    prepare(filter: IImageFilter): Promise<void>;
+    /**
+     * Get the number of discovered images
+     * @throws Error if called before prepare()
+     */
+    imagesLength(): number;
+    /**
+     * Get the ordered list of image URLs
+     * @throws Error if called before prepare()
+     */
+    imageURLs(): string[];
+    /**
+     * Check if the loader has been prepared
+     */
+    isPrepared(): boolean;
+    /**
+     * Extract folder ID from various Google Drive URL formats
+     * @param folderUrl - Google Drive folder URL
+     * @returns Folder ID or null if invalid
+     */
+    extractFolderId(folderUrl: string): string | null;
+    /**
+     * Load images from a Google Drive folder
+     * @param folderUrl - Google Drive folder URL
+     * @param filter - Filter to apply to discovered images
+     * @param recursive - Whether to include images from subfolders
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadFromFolder;
+    /**
+     * Load images from a single folder (non-recursive)
+     * @param folderId - Google Drive folder ID
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadImagesFromSingleFolder;
+    /**
+     * Load specific files by their URLs or IDs
+     * @param fileUrls - Array of Google Drive file URLs or IDs
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadFiles;
+    /**
+     * Extract file ID from Google Drive file URL
+     * @param fileUrl - Google Drive file URL or file ID
+     * @returns File ID or null if invalid
+     */
+    private extractFileId;
+    /**
+     * Recursively load images from a folder and all its subfolders
+     * @param folderId - Google Drive folder ID
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadImagesRecursively;
+    /**
+     * Direct loading method (no API key required, but less reliable)
+     * Uses embedded folder view to scrape image IDs
+     * @param folderId - Google Drive folder ID
+     * @param filter - Filter to apply (not used in fallback mode)
+     * @returns Promise resolving to array of image URLs
+     */
+    private loadImagesDirectly;
+    /**
+     * Manually add image URLs (for testing or when auto-loading fails)
+     * @param imageIds - Array of Google Drive file IDs
+     * @returns Array of direct image URLs
+     */
+    manualImageUrls(imageIds: string[]): string[];
+    /**
+     * Debug logging helper
+     * @param args - Arguments to log
+     */
+    private log;
+}
+
+export declare interface GoogleDriveLoaderEntry {
+    googleDrive: GoogleDriveLoaderInnerConfig;
+}
+
+export declare interface GoogleDriveLoaderInnerConfig {
+    apiKey: string;
+    sources: GoogleDriveSource[];
+    apiEndpoint?: string;
+    allowedExtensions?: string[];
+    debugLogging?: boolean;
+}
+
+export declare type GoogleDriveSource = GoogleDriveFolderSource | GoogleDriveFilesSource;
+
+export declare interface GridAlgorithmConfig {
+    columns: number | 'auto';
+    rows: number | 'auto';
+    stagger: 'none' | 'row' | 'column';
+    jitter: number;
+    overlap: number;
+    fillDirection: 'row' | 'column';
+    alignment: 'start' | 'center' | 'end';
+    gap: number;
+    overflowOffset: number;
+}
+
+declare interface GridLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class GridPlacementLayout implements PlacementLayout {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate grid layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides (includes fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: GridLayoutOptions): ImageLayout[];
+    /**
+     * Calculate optimal grid dimensions based on image count and container
+     */
+    private calculateGridDimensions;
+    /**
+     * Utility: Generate random number between min and max
+     */
+    private random;
+}
+
+/**
+ * ImageFilter interface for filtering images by extension
+ * Implemented by the ImageFilter class in loaders/ImageFilter.ts
+ */
+export declare interface IImageFilter {
+    isAllowed(filename: string): boolean;
+    getAllowedExtensions(): string[];
+}
+
+declare class ImageCloud {
+    private containerId;
+    private containerRef;
+    private fullConfig;
+    private imagesLoaded;
+    private imageElements;
+    private imageLayouts;
+    private currentImageHeight;
+    private currentFocusIndex;
+    private hoveredImage;
+    private resizeTimeout;
+    private displayQueue;
+    private queueInterval;
+    private loadGeneration;
+    private defaultStyles;
+    private hoverStyles;
+    private defaultClassName;
+    private hoverClassName;
+    private animationEngine;
+    private entryAnimationEngine;
+    private layoutEngine;
+    private zoomEngine;
+    private swipeEngine;
+    private imageLoader;
+    private imageFilter;
+    private containerEl;
+    private loadingEl;
+    private errorEl;
+    private loadingElAutoCreated;
+    private errorElAutoCreated;
+    private counterEl;
+    private counterElAutoCreated;
+    constructor(options?: ImageCloudOptions);
+    /**
+     * Create image filter based on shared loader config
+     */
+    private createImageFilter;
+    /**
+     * Create appropriate image loader based on config
+     * Processes loaders array, merges shared config, wraps in CompositeLoader if needed
+     * Uses dynamic imports to trigger loader registration and enable tree-shaking
+     */
+    private createLoader;
+    /**
+     * Create a single loader from a LoaderEntry, merging shared config
+     * Uses dynamic imports to trigger loader registration and enable tree-shaking
+     */
+    private createLoaderFromEntry;
+    /**
+     * Initialize the gallery
+     */
+    init(): Promise<void>;
+    private setupUI;
+    private resolveElement;
+    private createDefaultLoadingElement;
+    private createDefaultErrorElement;
+    private createDefaultCounterElement;
+    private setupEventListeners;
+    /**
+     * Navigate to the next image (Right arrow)
+     */
+    private navigateToNextImage;
+    /**
+     * Navigate to the previous image (Left arrow)
+     */
+    private navigateToPreviousImage;
+    /**
+     * Navigate to a specific image by index
+     */
+    private handleResize;
+    private getImageHeight;
+    /**
+     * Get container bounds for layout calculations
+     */
+    private getContainerBounds;
+    /**
+     * Load images using the unified loader interface
+     */
+    private loadImages;
+    /**
+     * Helper for debug logging
+     */
+    private logDebug;
+    private createImageCloud;
+    private handleImageClick;
+    /**
+     * Clear the image cloud and reset state
+     */
+    clearImageCloud(): void;
+    private showLoading;
+    private showError;
+    private hideError;
+    private updateCounter;
+    private hideCounter;
+    /**
+     * Destroy the gallery and clean up resources
+     */
+    destroy(): void;
+}
+export { ImageCloud }
+export { ImageCloud as ImageGallery }
+
+export declare interface ImageCloudConfig {
+    loaders: LoaderEntry[];
+    config: ConfigSection;
+    image: ImageConfig;
+    layout: LayoutConfig;
+    animation: AnimationConfig;
+    interaction: InteractionConfig;
+    rendering: RenderingConfig;
+    styling?: ImageStylingConfig;
+}
+
+export declare interface ImageCloudOptions {
+    container?: string | HTMLElement;
+    images?: string[];
+    loaders?: LoaderEntry[];
+    config?: ConfigSection;
+    image?: Partial<ImageConfig>;
+    layout?: Partial<LayoutConfig>;
+    animation?: Partial<AnimationConfig>;
+    interaction?: Partial<InteractionConfig>;
+    rendering?: Partial<RenderingConfig>;
+    styling?: Partial<ImageStylingConfig>;
+}
+
+/**
+ * Combined image configuration
+ */
+declare interface ImageConfig {
+    sizing?: ImageSizingConfig;
+    rotation?: ImageRotationConfig;
+}
+
+/**
+ * ImageFilter.ts
+ * Filters images by extension, designed for future extensibility
+ * (e.g., size filters, date filters, etc.)
+ */
+export declare class ImageFilter {
+    private allowedExtensions;
+    /**
+     * Create a new ImageFilter
+     * @param extensions - Array of allowed file extensions (without dots)
+     *                     Defaults to common image formats if not provided
+     */
+    constructor(extensions?: string[]);
+    /**
+     * Check if a filename has an allowed extension
+     * @param filename - The filename to check (can include path or query string)
+     * @returns True if the file extension is allowed
+     */
+    isAllowed(filename: string): boolean;
+    /**
+     * Get the list of allowed extensions
+     * @returns Array of allowed extensions
+     */
+    getAllowedExtensions(): string[];
+}
+
+export declare type ImageGalleryOptions = ImageCloudOptions;
+
+/**
+ * Type definitions for Image Gallery Library
+ */
+export declare interface ImageLayout {
+    id: number;
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+    baseSize: number;
+    zIndex?: number;
+}
+
+/**
+ * ImageLoader interface with consistent lifecycle pattern:
+ * 1. Constructor - Initialize with required parameters, throw if missing
+ * 2. prepare(filter) - Async discovery of images, accepts filter
+ * 3. imagesLength() - Return count of images (after prepare)
+ * 4. imageURLs() - Return ordered list of URLs (after prepare)
+ */
+export declare interface ImageLoader {
+    /**
+     * Async preparation - discovers images and applies filter
+     * Succeeds even if 0 images found (gallery handles empty state)
+     * @param filter - Filter to apply to discovered images
+     */
+    prepare(filter: IImageFilter): Promise<void>;
+    /**
+     * Get the number of discovered images
+     * @throws Error if called before prepare() completes
+     */
+    imagesLength(): number;
+    /**
+     * Get the ordered list of image URLs
+     * @throws Error if called before prepare() completes
+     */
+    imageURLs(): string[];
+    /**
+     * Check if the loader has been prepared
+     */
+    isPrepared(): boolean;
+}
+
+/**
+ * Image rotation configuration
+ */
+declare interface ImageRotationConfig {
+    mode: ImageRotationMode;
+    range?: ImageRotationRange;
+}
+
+/**
+ * Image rotation mode
+ */
+declare type ImageRotationMode = 'none' | 'random' | 'tangent';
+
+/**
+ * Image rotation range configuration
+ */
+declare interface ImageRotationRange {
+    min: number;
+    max: number;
+}
+
+/**
+ * Image sizing configuration
+ */
+declare interface ImageSizingConfig {
+    mode: SizingMode;
+    height?: number | FixedModeHeight;
+    minSize?: number;
+    maxSize?: number;
+    variance?: ImageVarianceConfig;
+}
+
+declare interface ImageStyleState {
+    className?: string | string[];
+    border?: BorderConfig;
+    borderTop?: Partial<BorderConfig>;
+    borderRight?: Partial<BorderConfig>;
+    borderBottom?: Partial<BorderConfig>;
+    borderLeft?: Partial<BorderConfig>;
+    borderRadiusTopLeft?: number;
+    borderRadiusTopRight?: number;
+    borderRadiusBottomRight?: number;
+    borderRadiusBottomLeft?: number;
+    shadow?: ShadowPreset | string;
+    filter?: FilterConfig;
+    opacity?: number;
+    cursor?: string;
+    outline?: OutlineConfig;
+    objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    aspectRatio?: string;
+}
+
+declare interface ImageStylingConfig {
+    default?: ImageStyleState;
+    hover?: Partial<ImageStyleState>;
+    focused?: Partial<ImageStyleState>;
+}
+
+/**
+ * Image variance configuration
+ * Controls random size variation applied to images
+ */
+declare interface ImageVarianceConfig {
+    min: number;
+    max: number;
+}
+
+/**
+ * Inject functional styles into document head.
+ * Idempotent - safe to call multiple times.
+ */
+export declare function injectFunctionalStyles(): void;
+
+declare interface InteractionConfig {
+    focus: FocusInteractionConfig;
+    navigation?: NavigationInteractionConfig;
+    gestures?: GestureInteractionConfig;
+}
+
+export declare type LayoutAlgorithm = 'random' | 'radial' | 'grid' | 'spiral' | 'cluster' | 'wave';
+
+export declare interface LayoutConfig {
+    algorithm: LayoutAlgorithm;
+    spacing: LayoutSpacingConfig;
+    scaleDecay?: number;
+    responsive?: ResponsiveBreakpoints;
+    targetCoverage?: number;
+    densityFactor?: number;
+    grid?: GridAlgorithmConfig;
+    spiral?: SpiralAlgorithmConfig;
+    cluster?: ClusterAlgorithmConfig;
+    wave?: WaveAlgorithmConfig;
+}
+
+export declare class LayoutEngine {
+    private config;
+    private imageConfig;
+    private layouts;
+    private placementLayout;
+    constructor(config: LayoutEngineConfig);
+    /**
+     * Initialize the appropriate placement layout based on config type
+     * @returns Initialized placement layout
+     */
+    private initLayout;
+    /**
+     * Generate layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides for configuration (e.g. fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generateLayout(imageCount: number, containerBounds: ContainerBounds, options?: Partial<LayoutConfig>): ImageLayout[];
+    /**
+     * Get the original layout state for an image
+     * @param imageId - The image ID (number or string)
+     * @returns Original layout state or undefined if not found
+     */
+    getOriginalState(imageId: number | string): ImageLayout | undefined;
+    /**
+     * Reset all stored layouts
+     */
+    reset(): void;
+    /**
+     * Update config dynamically (useful for responsive changes)
+     * @param newConfig - Updated configuration
+     */
+    updateConfig(newConfig: Partial<LayoutEngineConfig>): void;
+    /**
+     * Get responsive breakpoints from layout config
+     */
+    private getBreakpoints;
+    /**
+     * Resolve breakpoint name based on viewport width
+     */
+    resolveBreakpoint(viewportWidth: number): 'mobile' | 'tablet' | 'screen';
+    /**
+     * Resolve the effective base height based on image config and current viewport
+     * @param viewportWidth - Current viewport width
+     * @returns Resolved base height or undefined if should auto-calculate (adaptive mode)
+     */
+    resolveBaseHeight(viewportWidth: number): number | undefined;
+    /**
+     * Calculate adaptive image size based on container dimensions and image count
+     * @param containerBounds - Container dimensions {width, height}
+     * @param imageCount - Number of images to display
+     * @param maxHeight - Maximum height constraint (upper bound)
+     * @param viewportWidth - Current viewport width for baseHeight resolution
+     * @returns Calculated sizing result with height
+     */
+    calculateAdaptiveSize(containerBounds: ContainerBounds, imageCount: number, maxHeight: number, viewportWidth: number): AdaptiveSizingResult;
+    /**
+     * Utility: Clamp a value between min and max
+     */
+    private clamp;
+}
+
+declare interface LayoutEngineConfig {
+    layout: LayoutConfig;
+    image: ImageConfig;
+}
+
+declare interface LayoutSpacingConfig {
+    padding: number;
+    minGap: number;
+}
+
+export declare type LoaderEntry = StaticLoaderEntry | GoogleDriveLoaderEntry;
+
+declare interface NavigationInteractionConfig {
+    keyboard?: boolean;
+    swipe?: boolean;
+    mouseWheel?: boolean;
+}
+
+declare interface OutlineConfig {
+    width?: number;
+    color?: string;
+    style?: BorderStyle;
+    offset?: number;
+}
+
+declare interface PathAnimationOptions {
+    element: HTMLElement;
+    startPosition: Point;
+    endPosition: Point;
+    pathConfig: EntryPathConfig;
+    duration: number;
+    imageWidth: number;
+    imageHeight: number;
+    rotation: number;
+    scale: number;
+    onComplete?: () => void;
+    rotationConfig?: EntryRotationConfig;
+    startRotation?: number;
+    scaleConfig?: EntryScaleConfig;
+    startScale?: number;
+}
+
+declare interface PerformanceRenderingConfig {
+    lazyLoad?: boolean;
+    preloadCount?: number;
+    imageQuality?: 'auto' | 'high' | 'medium' | 'low';
+}
+
+export declare interface PlacementLayout {
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: Partial<LayoutConfig>): ImageLayout[];
+}
+
+declare interface Point {
+    x: number;
+    y: number;
+}
+
+declare interface RadialLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class RadialPlacementLayout implements PlacementLayout {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate radial layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: RadialLayoutOptions): ImageLayout[];
+    /**
+     * Estimate image width based on height
+     * Assumes landscape aspect ratio (approximately 1.4:1)
+     * @param height - Image height
+     * @returns Estimated width
+     */
+    private estimateWidth;
+    /**
+     * Utility: Generate random number between min and max
+     * @param min - Minimum value
+     * @param max - Maximum value
+     * @returns Random number in range
+     */
+    private random;
+}
+
+declare interface RandomLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class RandomPlacementLayout implements PlacementLayout {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate random layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides (includes fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: RandomLayoutOptions): ImageLayout[];
+    /**
+     * Utility: Generate random number between min and max
+     * @param min - Minimum value
+     * @param max - Maximum value
+     * @returns Random number in range
+     */
+    private random;
+}
+
+declare interface RenderingConfig {
+    responsive: ResponsiveRenderingConfig;
+    ui: UIRenderingConfig;
+    performance?: PerformanceRenderingConfig;
+}
+
+/**
+ * Check if a path type requires JavaScript animation (vs CSS transitions)
+ */
+export declare function requiresJSAnimation(pathType: EntryPathType): boolean;
+
+/**
+ * Responsive breakpoints configuration for layout
+ * Defines viewport width thresholds for mobile and tablet
+ */
+declare interface ResponsiveBreakpoints {
+    mobile: {
+        maxWidth: number;
+    };
+    tablet: {
+        maxWidth: number;
+    };
+}
+
+export declare interface ResponsiveHeight {
+    minWidth: number;
+    height: number;
+}
+
+export declare interface ResponsiveRenderingConfig {
+    breakpoints: {
+        mobile: number;
+        tablet?: number;
+        desktop?: number;
+    };
+    mobileDetection: () => boolean;
+}
+
+declare type ShadowPreset = 'none' | 'sm' | 'md' | 'lg' | 'glow';
+
+export declare interface SharedLoaderConfig {
+    validateUrls?: boolean;
+    validationTimeout?: number;
+    validationMethod?: 'head' | 'simple' | 'none';
+    allowedExtensions?: string[];
+}
+
+/**
+ * Sizing mode:
+ * - 'fixed': single explicit height for all breakpoints
+ * - 'responsive': different heights per breakpoint (mobile/tablet/screen)
+ * - 'adaptive': auto-calculates based on container size and image count
+ */
+declare type SizingMode = 'fixed' | 'responsive' | 'adaptive';
+
+export declare interface SpiralAlgorithmConfig {
+    spiralType: 'golden' | 'archimedean' | 'logarithmic';
+    direction: 'clockwise' | 'counterclockwise';
+    tightness: number;
+    scaleDecay: number;
+    startAngle: number;
+}
+
+declare interface SpiralLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare class SpiralPlacementLayout implements PlacementLayout {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate spiral layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides (includes fixedHeight)
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: SpiralLayoutOptions): ImageLayout[];
+    /**
+     * Calculate tangent angle for spiral curve at given position
+     * This aligns the image along the spiral's direction of travel
+     */
+    private calculateSpiralTangent;
+    /**
+     * Calculate radius for golden spiral (Vogel's model)
+     * Creates even distribution like sunflower seeds
+     */
+    private calculateGoldenRadius;
+    /**
+     * Calculate radius for Archimedean spiral
+     * r = a + b*θ (constant spacing between arms)
+     */
+    private calculateArchimedeanRadius;
+    /**
+     * Calculate radius for logarithmic (equiangular) spiral
+     * r = a * e^(b*θ)
+     */
+    private calculateLogarithmicRadius;
+    /**
+     * Utility: Generate random number between min and max
+     */
+    private random;
+}
+
+declare interface StartPosition {
+    x: number;
+    y: number;
+    useScale?: boolean;
+}
+
+export declare class StaticImageLoader implements ImageLoader {
+    private validateUrls;
+    private validationTimeout;
+    private validationMethod;
+    private sources;
+    private debugLogging;
+    private _prepared;
+    private _discoveredUrls;
+    constructor(config: StaticLoaderInnerConfig);
+    /**
+     * Prepare the loader by discovering all images from configured sources
+     * @param filter - Filter to apply to discovered images
+     */
+    prepare(filter: IImageFilter): Promise<void>;
+    /**
+     * Get the number of discovered images
+     * @throws Error if called before prepare()
+     */
+    imagesLength(): number;
+    /**
+     * Get the ordered list of image URLs
+     * @throws Error if called before prepare()
+     */
+    imageURLs(): string[];
+    /**
+     * Check if the loader has been prepared
+     */
+    isPrepared(): boolean;
+    /**
+     * Process a single source object using shape-based detection
+     * @param source - Source configuration detected by key presence
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of valid URLs from this source
+     */
+    private processSource;
+    /**
+     * Process a list of direct URLs
+     * @param urls - Array of image URLs
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of validated URLs
+     */
+    private processUrls;
+    /**
+     * Process a path-based source
+     * @param basePath - Base path (relative or absolute)
+     * @param files - Array of filenames
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of validated URLs
+     */
+    private processPath;
+    /**
+     * Process a JSON endpoint source
+     * Fetches a JSON endpoint that returns { images: string[] }
+     * @param url - JSON endpoint URL
+     * @param filter - Filter to apply to discovered images
+     * @returns Promise resolving to array of validated URLs
+     */
+    private processJson;
+    /**
+     * Validate a single URL using HEAD request
+     * @param url - URL to validate
+     * @returns Promise resolving to true if valid and accessible
+     */
+    private validateUrl;
+    /**
+     * Construct full URL from basePath and filename
+     * @param basePath - Base path (relative or absolute)
+     * @param filename - Filename to append
+     * @returns Complete URL
+     */
+    private constructUrl;
+    /**
+     * Check if URL is absolute (contains protocol)
+     * @param url - URL to check
+     * @returns True if absolute URL
+     */
+    private isAbsoluteUrl;
+    /**
+     * Debug logging helper
+     * @param args - Arguments to log
+     */
+    private log;
+}
+
+export declare interface StaticJsonSource {
+    json: string;
+}
+
+export declare interface StaticLoaderEntry {
+    static: StaticLoaderInnerConfig;
+}
+
+export declare interface StaticLoaderInnerConfig {
+    sources: StaticSource[];
+    validateUrls?: boolean;
+    validationTimeout?: number;
+    validationMethod?: 'head' | 'simple' | 'none';
+    allowedExtensions?: string[];
+    debugLogging?: boolean;
+}
+
+export declare interface StaticPathSource {
+    path: string;
+    files: string[];
+}
+
+export declare type StaticSource = StaticUrlsSource | StaticPathSource | StaticJsonSource;
+
+export declare interface StaticUrlsSource {
+    urls: string[];
+}
+
+export declare interface TransformParams {
+    x?: number;
+    y?: number;
+    rotation?: number;
+    scale?: number;
+}
+
+export declare interface UIRenderingConfig {
+    showLoadingSpinner: boolean;
+    showImageCounter?: boolean;
+    showThumbnails?: boolean;
+    theme?: 'light' | 'dark' | 'auto';
+    loadingElement?: string | HTMLElement;
+    errorElement?: string | HTMLElement;
+    counterElement?: string | HTMLElement;
+}
+
+/**
+ * Wave path presets - sinusoidal path animations
+ */
+export declare const WAVE_PATH_PRESETS: Record<WavePathPreset, WavePathConfig>;
+
+declare interface WaveAlgorithmConfig {
+    rows: number;
+    amplitude: number;
+    frequency: number;
+    phaseShift: number;
+    synchronization: 'offset' | 'synchronized' | 'alternating';
+}
+
+declare interface WaveLayoutOptions extends Partial<LayoutConfig> {
+    fixedHeight?: number;
+}
+
+export declare interface WavePathConfig {
+    amplitude: number;
+    frequency: number;
+    decay: boolean;
+    decayRate: number;
+    phase: number;
+}
+
+export declare type WavePathPreset = 'gentle' | 'playful' | 'serpentine' | 'flutter';
+
+export declare class WavePlacementLayout implements PlacementLayout {
+    private config;
+    private imageConfig;
+    constructor(config: LayoutConfig, imageConfig?: ImageConfig);
+    /**
+     * Generate wave layout positions for images
+     * @param imageCount - Number of images to layout
+     * @param containerBounds - Container dimensions {width, height}
+     * @param options - Optional overrides
+     * @returns Array of layout objects with position, rotation, scale
+     */
+    generate(imageCount: number, containerBounds: ContainerBounds, options?: WaveLayoutOptions): ImageLayout[];
+    /**
+     * Calculate Y position displacement on wave curve
+     * @param x - Horizontal position
+     * @param containerWidth - Container width
+     * @param amplitude - Wave amplitude
+     * @param frequency - Wave frequency
+     * @param phase - Phase offset
+     * @returns Y displacement from baseline
+     */
+    private calculateWaveY;
+    /**
+     * Calculate rotation based on wave tangent
+     * @param x - Horizontal position
+     * @param containerWidth - Container width
+     * @param amplitude - Wave amplitude
+     * @param frequency - Wave frequency
+     * @param phase - Phase offset
+     * @returns Rotation angle in degrees
+     */
+    private calculateRotation;
+    /**
+     * Estimate image width based on height
+     /**
+     * Utility: Generate random number between min and max
+     * @param min - Minimum value
+     * @param max - Maximum value
+     * @returns Random number in range
+     */
+    private random;
+}
+
+export declare class ZoomEngine {
+    private config;
+    private animationEngine;
+    private state;
+    private currentFocus;
+    private focusData;
+    private outgoing;
+    private incoming;
+    private focusGeneration;
+    private defaultStyles;
+    private focusedStyles;
+    private defaultClassName;
+    private focusedClassName;
+    constructor(config: FocusInteractionConfig, animationEngine: AnimationEngine, styling?: ImageStylingConfig);
+    /**
+     * Get current state machine state
+     */
+    getState(): ZoomState;
+    /**
+     * Check if any animation is in progress
+     */
+    isAnimating(): boolean;
+    /**
+     * Normalize scalePercent value
+     */
+    private normalizeScalePercent;
+    /**
+     * Calculate target dimensions for focused image
+     * Returns actual pixel dimensions instead of scale factor for sharper rendering
+     */
+    private calculateFocusDimensions;
+    /**
+     * Calculate the transform needed to center an image (position only, no scale)
+     * Scale is handled by animating actual dimensions for sharper rendering
+     */
+    private calculateFocusTransform;
+    /**
+     * Build transform string for dimension-based zoom (no scale in transform)
+     */
+    private buildDimensionZoomTransform;
+    /**
+     * Create a Web Animation that animates both transform (position) and dimensions
+     * This provides sharper zoom by re-rendering at target size instead of scaling pixels
+     */
+    private animateWithDimensions;
+    /**
+     * Apply focused styling to an element
+     */
+    private applyFocusedStyling;
+    /**
+     * Remove focused styling from an element
+     */
+    private removeFocusedStyling;
+    /**
+     * Start focus animation for an image using dimension-based zoom
+     * Animates actual width/height for sharper rendering instead of transform scale
+     * @param fromTransform - Optional starting transform (for mid-animation reversals)
+     * @param fromDimensions - Optional starting dimensions (for mid-animation reversals)
+     */
+    private startFocusAnimation;
+    /**
+     * Start unfocus animation for an image using dimension-based zoom
+     * Animates back to original dimensions for consistent behavior
+     * @param fromDimensions - Optional starting dimensions (for mid-animation reversals)
+     */
+    private startUnfocusAnimation;
+    /**
+     * Capture the current visual state of an element mid-animation, BEFORE cancelling.
+     *
+     * The computed matrix.e/f include the -50%/-50% centering offset resolved to pixels.
+     * buildDimensionZoomTransform prepends its own translate(-50%,-50%), so passing raw
+     * matrix.e/f doubles the centering and produces the wrong starting position.
+     *
+     * This method extracts the PURE positional offset (pureX = matrix.e + 0.5*midWidth)
+     * and commits width/height/transform to inline styles before the animation is cancelled,
+     * preventing any visual snap.
+     *
+     * Must be called while the animation is still running (offsetWidth reflects animated size).
+     * Caller is responsible for calling animationEngine.cancelAllAnimations() afterwards.
+     */
+    private captureMidAnimationState;
+    /**
+     * Handle animation completion
+     */
+    private waitForAnimation;
+    /**
+     * Reset an element instantly to its original position and dimensions (no animation)
+     */
+    private resetElementInstantly;
+    /**
+     * Focus (zoom) an image to center of container
+     * Implements cross-animation when swapping focus
+     */
+    focusImage(imageElement: HTMLElement, containerBounds: ContainerBounds, originalState: ImageLayout): Promise<void>;
+    /**
+     * Unfocus current image, returning it to original position
+     */
+    unfocusImage(): Promise<void>;
+    /**
+     * Swap focus from current image to a new one (alias for focusImage with cross-animation)
+     */
+    swapFocus(newImageElement: HTMLElement, containerBounds: ContainerBounds, originalState: ImageLayout): Promise<void>;
+    /**
+     * Get currently focused image element
+     */
+    getCurrentFocus(): HTMLElement | null;
+    /**
+     * Check if an image is currently focused (stable state)
+     */
+    isFocused(imageElement: HTMLElement): boolean;
+    /**
+     * Check if an image is the target of current focus animation
+     */
+    isTargetingFocus(imageElement: HTMLElement): boolean;
+    /**
+     * Check if an image is involved in any focus/animation state
+     * Returns true if the image is focused, animating in, or animating out
+     * Useful for hover state management - don't apply hover to animating images
+     */
+    isInvolved(imageElement: HTMLElement): boolean;
+    /**
+     * Apply a temporary horizontal drag offset to the focused image
+     * Used during swipe gestures for visual feedback
+     */
+    setDragOffset(offset: number): void;
+    /**
+     * Clear the drag offset, optionally animating back to center
+     * @param animate - If true, animate back to center; if false, snap instantly
+     * @param duration - Animation duration in ms (default 150)
+     */
+    clearDragOffset(animate: boolean, duration?: number): void;
+    /**
+     * Reset zoom state (cancels all animations)
+     */
+    reset(): void;
+}
+
+/**
+ * State machine states for zoom/focus animations
+ */
+declare enum ZoomState {
+    IDLE = "idle",// No focus, no animations
+    FOCUSING = "focusing",// Single image animating in
+    FOCUSED = "focused",// Stable focused state
+    UNFOCUSING = "unfocusing",// Single image animating out
+    CROSS_ANIMATING = "cross_animating"
+}
+
+export { }