@beautifi/plugin 0.1.0

package/dist/types/VideoRenderer.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Video Renderer
+ *
+ * Renders video cinemagraphs with seamless transitions from CSS animations.
+ * Handles video playback, loading states, and fallback to CSS on failure.
+ */
+/**
+ * Video playback state
+ */
+export type VideoPlaybackState = 'loading' | 'buffering' | 'playing' | 'paused' | 'error';
+/**
+ * Video renderer configuration
+ */
+export interface VideoRendererConfig {
+    /** Transition duration for CSS to video swap (ms) */
+    transitionDuration?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Auto-play when video is ready */
+    autoPlay?: boolean;
+    /** Loop video playback */
+    loop?: boolean;
+    /** Mute video (required for autoplay) */
+    muted?: boolean;
+}
+/**
+ * VideoRenderer class
+ *
+ * Handles seamless video overlay and playback with CSS transition effects.
+ */
+export declare class VideoRenderer {
+    private config;
+    private activeVideos;
+    constructor(config?: VideoRendererConfig);
+    /**
+     * Prepare a video overlay for an image
+     *
+     * @param imageId - Unique ID for tracking
+     * @param imageElement - The image element to overlay
+     * @param videoUrl - URL of the video to play
+     * @param onFallback - Callback if video fails to load
+     * @returns Promise that resolves when video is ready to play
+     */
+    prepareVideo(imageId: string, imageElement: HTMLImageElement, videoUrl: string, onFallback?: () => void): Promise<boolean>;
+    /**
+     * Play video and transition from CSS animation
+     */
+    play(imageId: string): boolean;
+    /**
+     * Pause video playback
+     */
+    pause(imageId: string): boolean;
+    /**
+     * Resume video playback
+     */
+    resume(imageId: string): boolean;
+    /**
+     * Stop video and remove overlay
+     */
+    stop(imageId: string): void;
+    /**
+     * Check if video is playing for an image
+     */
+    isPlaying(imageId: string): boolean;
+    /**
+     * Check if video is prepared for an image
+     */
+    isPrepared(imageId: string): boolean;
+    /**
+     * Get current playback state
+     */
+    getState(imageId: string): VideoPlaybackState | null;
+    /**
+     * Destroy all videos and cleanup
+     */
+    destroy(): void;
+    /**
+     * Create wrapper element around image
+     */
+    private createWrapper;
+    /**
+     * Create video element with proper attributes
+     */
+    private createVideoElement;
+    /**
+     * Wait for video to be ready to play
+     */
+    private waitForVideoReady;
+    /**
+     * Transition from image to video
+     */
+    private transitionToVideo;
+    /**
+     * Transition from video back to image
+     */
+    private transitionToImage;
+    /**
+     * Cleanup video element and restore image
+     */
+    private cleanup;
+    /**
+     * Debug logging
+     */
+    private log;
+}

package/dist/types/ViewportObserver.d.ts

@@ -0,0 +1,42 @@
+import { TrackedImage, ViewportCallback } from './types';
+
+/**
+ * ViewportObserver class
+ *
+ * Efficiently tracks image visibility using IntersectionObserver.
+ */
+export declare class ViewportObserver {
+    private observer;
+    private visibilityHandler;
+    private callback;
+    private threshold;
+    private rootMargin;
+    private observedElements;
+    private isDocumentVisible;
+    private debug;
+    constructor(callback: ViewportCallback, options?: {
+        threshold?: number;
+        rootMargin?: string;
+        debug?: boolean;
+    });
+    /**
+     * Initialize the observer
+     */
+    init(): void;
+    /**
+     * Start observing an image
+     */
+    observe(image: TrackedImage): void;
+    /**
+     * Stop observing an image
+     */
+    unobserve(image: TrackedImage): void;
+    /**
+     * Check if document is currently visible
+     */
+    isVisible(): boolean;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,55 @@
+import { LivePhotoOptions, TrackedImage } from './types';
+
+export declare const beautifi: {
+    /**
+     * Initialize the plugin
+     */
+    init: (options: LivePhotoOptions) => void;
+    /**
+     * Check if initialized
+     */
+    isInitialized: () => boolean;
+    /**
+     * Get current options
+     */
+    getOptions: () => Required<LivePhotoOptions> | null;
+    /**
+     * Get tracked images
+     */
+    getTrackedImages: () => TrackedImage[];
+    /**
+     * Destroy and clean up
+     */
+    destroy: () => void;
+};
+export declare const LiveMyPhotos: {
+    /**
+     * Initialize the plugin
+     */
+    init: (options: LivePhotoOptions) => void;
+    /**
+     * Check if initialized
+     */
+    isInitialized: () => boolean;
+    /**
+     * Get current options
+     */
+    getOptions: () => Required<LivePhotoOptions> | null;
+    /**
+     * Get tracked images
+     */
+    getTrackedImages: () => TrackedImage[];
+    /**
+     * Destroy and clean up
+     */
+    destroy: () => void;
+};
+export type { LivePhotoOptions, TrackedImage, } from './types';
+export { LivePhotoError, DEFAULT_OPTIONS, DEFAULT_ANIMATION_CONFIG, } from './types';
+export { ImageDetector } from './ImageDetector';
+export { ViewportObserver } from './ViewportObserver';
+export { GeminiApiClient } from './GeminiApiClient';
+export { AnimationRenderer } from './AnimationRenderer';
+export { VeoClient } from './VeoClient';
+export { VideoRenderer } from './VideoRenderer';
+export default beautifi;

package/dist/types/lite.d.ts

@@ -0,0 +1,86 @@
+/**
+ * beautifi Lite - Minimal CSS-only animation bundle
+ *
+ * This is a lightweight (<5KB) version of beautifi that provides
+ * basic CSS-based animations without requiring AI processing.
+ *
+ * Users can upgrade to the full AI-powered version for advanced features.
+ *
+ * @packageDocumentation
+ */
+export interface beautifiLiteOptions {
+    /** Selector for images to animate */
+    selector?: string;
+    /** Animation intensity: 'subtle' | 'moderate' | 'strong' */
+    intensity?: 'subtle' | 'moderate' | 'strong';
+    /** Animation type: 'breathe' | 'sway' | 'parallax' | 'pulse' */
+    type?: 'breathe' | 'sway' | 'parallax' | 'pulse';
+    /** Whether to loop the animation */
+    loop?: boolean;
+    /** Animation duration in milliseconds */
+    duration?: number;
+    /** Enable intersection observer for lazy animation */
+    lazyLoad?: boolean;
+}
+/**
+ * beautifi Lite - CSS-only animation engine
+ *
+ * Provides lightweight, CSS-based animations for images without AI processing.
+ * Use this for basic effects or as a fallback when AI is not available.
+ */
+export declare class beautifiLite {
+    private options;
+    private observer;
+    private styleElement;
+    private animatedElements;
+    constructor(options?: beautifiLiteOptions);
+    /**
+     * Initialize the lite animation engine
+     */
+    private init;
+    /**
+     * Inject global CSS for animations
+     */
+    private injectGlobalStyles;
+    /**
+     * Setup intersection observer for lazy loading
+     */
+    private setupIntersectionObserver;
+    /**
+     * Process all matching elements
+     */
+    private processElements;
+    /**
+     * Animate a single element
+     */
+    animateElement(element: HTMLElement): void;
+    /**
+     * Pause animation on an element
+     */
+    pause(element?: HTMLElement): void;
+    /**
+     * Resume animation on an element
+     */
+    resume(element?: HTMLElement): void;
+    /**
+     * Stop and cleanup animation on an element
+     */
+    stop(element: HTMLElement): void;
+    /**
+     * Destroy the lite engine and cleanup
+     */
+    destroy(): void;
+    /**
+     * Check if an element is currently animated
+     */
+    isAnimated(element: HTMLElement): boolean;
+    /**
+     * Get the number of animated elements
+     */
+    get count(): number;
+}
+/**
+ * Initialize beautifi Lite with options
+ */
+export declare function initLite(options?: beautifiLiteOptions): beautifiLite;
+export default beautifiLite;

package/dist/types/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * beautifi - Core Type Definitions
+ *
+ * This file contains all TypeScript interfaces and types used throughout
+ * the beautifi plugin.
+ */
+/**
+ * Animation intensity levels
+ */
+export type AnimationIntensity = 'subtle' | 'medium' | 'strong';
+/**
+ * Animation type styles
+ */
+export type AnimationType = 'breathing' | 'parallax' | 'sway' | 'auto';
+/**
+ * Animation states
+ */
+export type AnimationState = 'idle' | 'loading' | 'playing' | 'paused' | 'error';
+/**
+ * Error codes for different failure scenarios
+ */
+export type LivePhotoErrorCode = 'API_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT_ERROR' | 'VALIDATION_ERROR' | 'RATE_LIMIT_ERROR' | 'RENDER_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Event types emitted by the plugin
+ */
+export type LivePhotoEventType = 'init' | 'imageDetected' | 'animationStart' | 'animationComplete' | 'animationPause' | 'animationResume' | 'animationError' | 'videoStart' | 'videoReady' | 'videoError' | 'destroy';
+/**
+ * Animation mode - determines how images are animated
+ * - 'auto': CSS animation immediately + AI video in background (default)
+ * - 'css': CSS animation only, no video generation
+ * - 'video': Wait for video, no CSS animation
+ */
+export type AnimationMode = 'auto' | 'css' | 'video';
+/**
+ * Video generation state
+ */
+export type VideoState = 'idle' | 'generating' | 'ready' | 'error';
+/**
+ * Global plugin configuration options
+ */
+export interface LivePhotoOptions {
+    /** API key for Gemini backend (required) */
+    apiKey: string;
+    /** Cloud Functions endpoint URL (optional, uses default if not provided) */
+    endpoint?: string;
+    /** CSS selector for target images (default: 'img') */
+    selector?: string;
+    /** Default animation intensity (default: 'subtle') */
+    intensity?: AnimationIntensity;
+    /** Default animation type (default: 'auto') */
+    type?: AnimationType;
+    /** Whether animations should loop (default: true) */
+    loop?: boolean;
+    /** Respect prefers-reduced-motion (default: true) */
+    respectReducedMotion?: boolean;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Viewport intersection threshold for lazy loading (default: 0.1) */
+    threshold?: number;
+    /** Root margin for eager loading (default: '50px') */
+    rootMargin?: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Animation mode: 'auto' | 'css' | 'video' (default: 'auto') */
+    mode?: AnimationMode;
+    /** Video endpoint URL (if different from main endpoint) */
+    videoEndpoint?: string;
+}
+/**
+ * Per-image animation configuration (from data attributes)
+ */
+export interface AnimationConfig {
+    /** Whether animation is enabled for this image */
+    enabled: boolean;
+    /** Animation intensity level */
+    intensity: AnimationIntensity;
+    /** Animation type/style */
+    type: AnimationType;
+    /** Whether animation loops continuously */
+    loop: boolean;
+    /** Delay before animation starts (ms) */
+    delay: number;
+}
+/**
+ * Animation frame data from Gemini API
+ */
+export interface AnimationFrameData {
+    /** Frame timestamp */
+    timestamp: number;
+    /** Transform data for this frame */
+    transform: {
+        translateX: number;
+        translateY: number;
+        scale: number;
+        rotate: number;
+    };
+    /** Optional opacity value */
+    opacity?: number;
+}
+/**
+ * Gemini API response for animation generation
+ */
+export interface GeminiAnimationResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Unique animation ID */
+    animationId: string;
+    /** Animation duration in milliseconds */
+    duration: number;
+    /** Frame rate (fps) */
+    frameRate: number;
+    /** Animation keyframes */
+    frames: AnimationFrameData[];
+    /** Detected animation type */
+    detectedType: AnimationType;
+    /** Cache status (hit/miss) */
+    cacheStatus?: 'hit' | 'miss';
+    /** Error message if success is false */
+    error?: string;
+}
+/**
+ * API request payload
+ */
+export interface GeminiAnimationRequest {
+    /** Image URL or hash */
+    imageUrl: string;
+    /** Image hash for caching */
+    imageHash?: string;
+    /** Requested animation type */
+    type: AnimationType;
+    /** Requested intensity */
+    intensity: AnimationIntensity;
+    /** Whether to loop */
+    loop: boolean;
+}
+/**
+ * Tracked image element with metadata
+ */
+export interface TrackedImage {
+    /** Original image element */
+    element: HTMLImageElement;
+    /** Unique ID for this tracked image */
+    id: string;
+    /** Current animation state */
+    state: AnimationState;
+    /** Animation configuration for this image */
+    config: AnimationConfig;
+    /** API response data (when loaded) */
+    animationData?: GeminiAnimationResponse;
+    /** Error if animation failed */
+    error?: LivePhotoError;
+}
+/**
+ * Base event payload
+ */
+export interface LivePhotoEventBase {
+    /** Event type */
+    type: LivePhotoEventType;
+    /** Event timestamp */
+    timestamp: number;
+}
+/**
+ * Image-related event payload
+ */
+export interface LivePhotoImageEvent extends LivePhotoEventBase {
+    /** Image element involved */
+    element: HTMLImageElement;
+    /** Image tracking ID */
+    imageId: string;
+}
+/**
+ * Error event payload
+ */
+export interface LivePhotoErrorEvent extends LivePhotoImageEvent {
+    type: 'animationError';
+    /** Error details */
+    error: LivePhotoError;
+}
+/**
+ * Event handler function type
+ */
+export type LivePhotoEventHandler<T extends LivePhotoEventBase = LivePhotoEventBase> = (event: T) => void;
+/**
+ * Viewport observer callback
+ */
+export type ViewportCallback = (image: TrackedImage, isIntersecting: boolean) => void;
+/**
+ * Custom error class for beautifi
+ */
+export declare class LivePhotoError extends Error {
+    readonly code: LivePhotoErrorCode;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, code: LivePhotoErrorCode, originalError?: Error | undefined);
+}
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_OPTIONS: Required<Omit<LivePhotoOptions, 'apiKey'>>;
+/**
+ * Default animation configuration
+ */
+export declare const DEFAULT_ANIMATION_CONFIG: AnimationConfig;

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@beautifi/plugin",
+  "version": "0.1.0",
+  "description": "beautifi JavaScript plugin that transforms static images into lifelike animated photos using AI",
+  "type": "module",
+  "main": "dist/beautifi.cjs.js",
+  "module": "dist/beautifi.esm.js",
+  "browser": "dist/beautifi.umd.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/beautifi.esm.js",
+      "require": "./dist/beautifi.cjs.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./lite": {
+      "import": "./dist/beautifi-lite.esm.js",
+      "require": "./dist/beautifi-lite.cjs.js",
+      "types": "./dist/types/lite.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "jsdelivr": "dist/beautifi.min.js",
+  "unpkg": "dist/beautifi.min.js",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "build:lite": "vite build --config vite.lite.config.ts",
+    "build:all": "npm run build && npm run build:lite && npm run sri",
+    "sri": "npx tsx scripts/generate-sri.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "beautifi",
+    "animation",
+    "images",
+    "ai-photos",
+    "gemini",
+    "ai",
+    "cinemagraph",
+    "image-animation",
+    "living-photos"
+  ],
+  "author": "AgenticCompany",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgenticCompany/beautifi.git"
+  },
+  "homepage": "https://beautif.ai",
+  "bugs": {
+    "url": "https://github.com/AgenticCompany/beautifi/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.55.0",
+    "prettier": "^3.1.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0",
+    "terser": "^5.31.0",
+    "vite-plugin-dts": "^3.6.0",
+    "vitest": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}