@mywallpaper/addon-sdk 2.0.0

package/dist/index.d.mts

@@ -0,0 +1,1087 @@
+/**
+ * @mywallpaper/addon-sdk - TypeScript Types v2.0
+ *
+ * Complete type definitions for building MyWallpaper addons.
+ * These types describe the runtime API available via window.MyWallpaper
+ *
+ * @example
+ * ```typescript
+ * import type { MyWallpaperAPI, SystemEventType } from '@mywallpaper/addon-sdk'
+ *
+ * // Type-safe event handling
+ * const api = window.MyWallpaper
+ * api.onEvent('viewport:resize', ({ width, height }) => {
+ *   console.log(`Resized to ${width}x${height}`)
+ * })
+ * ```
+ */
+/**
+ * System events that addons can subscribe to.
+ * Subscribe via `window.MyWallpaper.onEvent(eventType, callback)`
+ */
+type SystemEventType = 'viewport:resize' | 'theme:change' | 'visibility:change' | 'layer:focus' | 'layer:blur' | 'app:idle' | 'app:active';
+/**
+ * Event data payloads for each system event type.
+ * TypeScript will infer the correct payload type based on event name.
+ */
+interface SystemEventData {
+    'viewport:resize': {
+        width: number;
+        height: number;
+        aspectRatio: string;
+    };
+    'theme:change': {
+        theme: 'light' | 'dark' | 'system';
+    };
+    'visibility:change': {
+        visible: boolean;
+    };
+    'layer:focus': {
+        layerId: string;
+    };
+    'layer:blur': {
+        layerId: string;
+    };
+    'app:idle': {
+        idleSeconds: number;
+    };
+    'app:active': Record<string, never>;
+}
+/**
+ * Capabilities that an addon can declare.
+ * Declared in `manifest.json` and sent via `ready()` call.
+ */
+type AddonCapability = 'hot-reload' | 'system-events' | 'storage' | 'audio' | 'network';
+/**
+ * OAuth providers supported for addon API access.
+ * Use with `oauth:{provider}` permission format.
+ */
+type OAuthProvider = 'github' | 'google' | 'discord' | 'spotify' | 'twitch';
+/**
+ * OAuth permission types for accessing provider APIs.
+ * Format: `oauth:{provider}`
+ *
+ * @example
+ * ```typescript
+ * const permission: OAuthPermissionType = 'oauth:github'
+ * await api.requestPermission(permission, 'Display your GitHub profile')
+ * ```
+ */
+type OAuthPermissionType = 'oauth:github' | 'oauth:google' | 'oauth:discord' | 'oauth:spotify' | 'oauth:twitch';
+/**
+ * Permission types that addons can request.
+ * Requested via `window.MyWallpaper.requestPermission(type, reason)`
+ */
+type PermissionType = 'storage' | 'cpu-high' | 'network' | 'audio' | 'notifications' | OAuthPermissionType;
+/**
+ * Constraints that may be applied to granted permissions.
+ * Returned when permission is granted with limitations.
+ */
+interface PermissionConstraints {
+    storage?: {
+        quotaKB: number;
+    };
+    network?: {
+        allowedDomains: string[];
+    };
+    cpu?: {
+        maxPercent: number;
+    };
+}
+/**
+ * Storage API for persistent key-value data.
+ * Access via `window.MyWallpaper.storage`
+ *
+ * @example
+ * ```typescript
+ * const { storage } = window.MyWallpaper
+ *
+ * // Save user preferences
+ * await storage.set('preferences', { darkMode: true, fontSize: 14 })
+ *
+ * // Retrieve data
+ * const prefs = await storage.get<{ darkMode: boolean; fontSize: number }>('preferences')
+ *
+ * // Check storage usage
+ * const usedBytes = await storage.size()
+ * console.log(`Using ${usedBytes} bytes of storage`)
+ * ```
+ */
+interface StorageAPI {
+    /**
+     * Get a value by key.
+     * Returns null if key doesn't exist.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set a value for a key.
+     * Throws if quota exceeded (default 1MB per addon).
+     */
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    /**
+     * Delete a key and its value.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all stored data for this addon.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all storage keys.
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Get total storage usage in bytes.
+     */
+    size(): Promise<number>;
+}
+/**
+ * Response from network.fetch() requests.
+ * Similar to native Response but with pre-parsed data.
+ */
+interface NetworkResponse {
+    /** Whether the request was successful (status 200-299) */
+    ok: boolean;
+    /** HTTP status code */
+    status: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response data (auto-parsed JSON, text, or base64 for binary) */
+    data: unknown;
+}
+/**
+ * Network API for making HTTP requests through the secure host proxy.
+ * Access via `window.MyWallpaper.network`
+ *
+ * **IMPORTANT:** Direct `fetch()` and `XMLHttpRequest` are blocked for security.
+ * All network requests MUST go through this API.
+ *
+ * **IMPORTANT:** Domains must be declared in your manifest.json:
+ * ```json
+ * {
+ *   "permissions": {
+ *     "network": { "domains": ["api.example.com"] }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const { network } = window.MyWallpaper
+ *
+ * // Simple GET request
+ * const response = await network.fetch('https://api.weather.com/current')
+ * if (response.ok) {
+ *   console.log(response.data)
+ * }
+ *
+ * // POST request with JSON body
+ * const result = await network.fetch('https://api.example.com/data', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ key: 'value' })
+ * })
+ * ```
+ */
+interface NetworkAPI {
+    /**
+     * Make an HTTP request through the secure host proxy.
+     * Domain must be whitelisted in manifest.json permissions.
+     *
+     * @param url - Full URL to fetch (must be in allowed domains)
+     * @param options - Optional request options
+     * @returns Promise resolving to NetworkResponse
+     * @throws Error if domain not allowed or network permission not granted
+     */
+    fetch(url: string, options?: {
+        /** HTTP method (default: GET) */
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+        /** Request headers */
+        headers?: Record<string, string>;
+        /** Request body (for POST/PUT/PATCH) */
+        body?: string;
+    }): Promise<NetworkResponse>;
+}
+/**
+ * Response from OAuth API proxy requests.
+ */
+interface OAuthResponse {
+    /** Whether the request was successful (status 200-299) */
+    ok: boolean;
+    /** HTTP status code from the provider API */
+    status: number;
+    /** Response headers from the provider API */
+    headers: Record<string, string>;
+    /** Response data (auto-parsed JSON) */
+    data: unknown;
+}
+/**
+ * Error when OAuth scopes are insufficient.
+ * Returned when the addon needs scopes the current token doesn't have.
+ */
+interface OAuthScopesError {
+    /** Error code: 'insufficient_scopes' */
+    error: 'insufficient_scopes';
+    /** Human-readable error message */
+    message: string;
+    /** The OAuth provider that needs re-authorization */
+    provider: OAuthProvider;
+    /** Scopes that are missing from the current token */
+    missingScopes: string[];
+    /** All scopes needed for this request */
+    requiredScopes: string[];
+}
+/**
+ * OAuth API for making authenticated requests to provider APIs.
+ * Access via `window.MyWallpaper.oauth`
+ *
+ * **How it works:**
+ * 1. User connects their OAuth provider in MyWallpaper settings
+ * 2. Your addon requests permission (e.g., `oauth:github`)
+ * 3. API calls are proxied through the host - your addon never sees the token
+ * 4. The host handles token refresh automatically
+ *
+ * **SECURITY:** Your addon NEVER sees OAuth tokens. All requests are proxied
+ * through the backend, which adds authentication headers server-side.
+ *
+ * @example
+ * ```typescript
+ * const api = window.MyWallpaper
+ *
+ * // Request GitHub permission
+ * const granted = await api.requestPermission(
+ *   'oauth:github',
+ *   'Display your GitHub profile and repositories'
+ * )
+ *
+ * if (granted) {
+ *   // Make API calls through the proxy
+ *   const response = await api.oauth.request('github', '/user')
+ *   if (response.ok) {
+ *     console.log('Username:', response.data.login)
+ *   }
+ * }
+ * ```
+ */
+interface OAuthAPI {
+    /**
+     * Make an authenticated request to an OAuth provider's API.
+     *
+     * @param provider - The OAuth provider (github, google, etc.)
+     * @param endpoint - The API endpoint path (e.g., '/user', '/user/repos')
+     * @param options - Optional request options
+     * @returns Promise resolving to OAuthResponse or OAuthScopesError
+     *
+     * @example
+     * ```typescript
+     * // GET request
+     * const profile = await api.oauth.request('github', '/user')
+     *
+     * // POST request
+     * const repo = await api.oauth.request('github', '/user/repos', {
+     *   method: 'POST',
+     *   body: { name: 'new-repo', private: true }
+     * })
+     * ```
+     */
+    request(provider: OAuthProvider, endpoint: string, options?: {
+        /** HTTP method (default: GET) */
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+        /** Request body (for POST/PUT/PATCH) - will be JSON serialized */
+        body?: unknown;
+        /** Additional headers (Authorization is added automatically) */
+        headers?: Record<string, string>;
+        /** Required scopes for this request - triggers re-auth if missing */
+        requiredScopes?: string[];
+    }): Promise<OAuthResponse | OAuthScopesError>;
+    /**
+     * Check if the user has connected a specific OAuth provider.
+     *
+     * @param provider - The OAuth provider to check
+     * @returns Promise resolving to true if connected
+     *
+     * @example
+     * ```typescript
+     * if (await api.oauth.isConnected('github')) {
+     *   console.log('GitHub is connected')
+     * } else {
+     *   console.log('Please connect your GitHub account')
+     * }
+     * ```
+     */
+    isConnected(provider: OAuthProvider): Promise<boolean>;
+    /**
+     * Get the scopes granted for a connected OAuth provider.
+     *
+     * @param provider - The OAuth provider
+     * @returns Promise resolving to array of granted scopes
+     *
+     * @example
+     * ```typescript
+     * const scopes = await api.oauth.getScopes('github')
+     * if (scopes.includes('repo')) {
+     *   // Can access private repos
+     * }
+     * ```
+     */
+    getScopes(provider: OAuthProvider): Promise<string[]>;
+    /**
+     * Request re-authorization with additional scopes.
+     * Opens the OAuth flow with the new scopes, preserving existing ones.
+     *
+     * @param provider - The OAuth provider
+     * @param scopes - Additional scopes to request
+     * @param reason - User-friendly explanation of why scopes are needed
+     * @returns Promise resolving to true if re-auth was successful
+     *
+     * @example
+     * ```typescript
+     * // Request repo scope for private repository access
+     * const granted = await api.oauth.requestScopes(
+     *   'github',
+     *   ['repo'],
+     *   'Access your private repositories to display commit stats'
+     * )
+     *
+     * if (granted) {
+     *   // Now we can access private repos
+     *   const repos = await api.oauth.request('github', '/user/repos')
+     * }
+     * ```
+     */
+    requestScopes(provider: OAuthProvider, scopes: string[], reason: string): Promise<boolean>;
+}
+/**
+ * Callback for settings changes (hot-reload).
+ * @param settings - Complete settings object with new values
+ * @param changedKeys - Array of keys that changed (for optimization)
+ */
+interface SettingsCallback {
+    (settings: Record<string, unknown>, changedKeys: string[]): void;
+}
+/**
+ * Generic callback for system events.
+ * @param data - Event-specific payload
+ */
+interface EventCallback<T = unknown> {
+    (data: T): void;
+}
+/**
+ * Options passed to `ready()` call.
+ */
+interface ReadyOptions {
+    /** Capabilities this addon supports */
+    capabilities?: AddonCapability[];
+    /** System events this addon wants to receive */
+    subscribedEvents?: SystemEventType[];
+}
+/**
+ * The main MyWallpaper API available on `window.MyWallpaper`.
+ *
+ * This API is automatically injected when your addon loads.
+ * No imports needed - just use `window.MyWallpaper` in your code.
+ *
+ * @example
+ * ```typescript
+ * // Type-safe access
+ * declare const window: Window & { MyWallpaper: MyWallpaperAPI }
+ *
+ * const { config, storage } = window.MyWallpaper
+ *
+ * // React to settings changes
+ * window.MyWallpaper.onSettingsChange((settings, changedKeys) => {
+ *   if (changedKeys.includes('primaryColor')) {
+ *     updateTheme(settings.primaryColor as string)
+ *   }
+ * })
+ *
+ * // Signal addon is ready
+ * window.MyWallpaper.ready({
+ *   capabilities: ['hot-reload', 'storage'],
+ *   subscribedEvents: ['viewport:resize', 'theme:change']
+ * })
+ * ```
+ */
+interface MyWallpaperAPI {
+    /**
+     * Current configuration values from user settings.
+     * Updated automatically when settings change.
+     */
+    readonly config: Record<string, unknown>;
+    /**
+     * Unique identifier for this addon layer instance.
+     * Useful for multi-instance scenarios.
+     */
+    readonly layerId: string;
+    /**
+     * SDK version. Always '2.0' for current API.
+     */
+    readonly version: '2.0';
+    /**
+     * Register callback for settings changes (hot-reload).
+     * Called when user modifies addon settings in the UI.
+     *
+     * @param callback - Function called with new settings and changed keys
+     */
+    onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Subscribe to a system event.
+     * @param event - Event type to subscribe to
+     * @param callback - Function called when event fires
+     */
+    onEvent<E extends SystemEventType>(event: E, callback: EventCallback<SystemEventData[E]>): void;
+    /**
+     * Unsubscribe from a system event.
+     * @param event - Event type to unsubscribe from
+     * @param callback - Same callback function passed to onEvent
+     */
+    offEvent<E extends SystemEventType>(event: E, callback: EventCallback<SystemEventData[E]>): void;
+    /**
+     * Called when addon is mounted (first load).
+     */
+    onMount(callback: () => void): void;
+    /**
+     * Called when addon is unmounted (removed from page).
+     * Use for cleanup (event listeners, timers, etc.).
+     */
+    onUnmount(callback: () => void): void;
+    /**
+     * Called when addon is paused (hidden, tab inactive).
+     * Use to pause animations and reduce resource usage.
+     */
+    onPause(callback: () => void): void;
+    /**
+     * Called when addon is resumed (visible again).
+     * Use to restart animations and refresh data.
+     */
+    onResume(callback: () => void): void;
+    /**
+     * Signal that the addon is ready and initialized.
+     * **Must be called** after your addon loads and initializes.
+     *
+     * @param options - Capabilities and event subscriptions
+     *
+     * @example
+     * ```typescript
+     * // After DOM is ready and addon is initialized
+     * window.MyWallpaper.ready({
+     *   capabilities: ['hot-reload'],
+     *   subscribedEvents: ['viewport:resize']
+     * })
+     * ```
+     */
+    ready(options?: ReadyOptions): void;
+    /**
+     * Signal that visual rendering is complete.
+     * Call after images are loaded, canvas drawn, animations ready.
+     * Used by screenshot service to capture addon at right moment.
+     *
+     * @example
+     * ```typescript
+     * async function init() {
+     *   await loadAllImages()
+     *   drawCanvas()
+     *   window.MyWallpaper.renderComplete()
+     * }
+     * ```
+     */
+    renderComplete(): void;
+    /**
+     * Request a permission from the user.
+     * Shows a permission modal explaining why the permission is needed.
+     *
+     * @param permission - Permission type to request
+     * @param reason - User-friendly explanation of why permission is needed
+     * @returns Promise resolving to true if granted, false if denied
+     *
+     * @example
+     * ```typescript
+     * const granted = await window.MyWallpaper.requestPermission(
+     *   'storage',
+     *   'Save your preferences across sessions'
+     * )
+     * if (granted) {
+     *   await window.MyWallpaper.storage.set('initialized', true)
+     * }
+     * ```
+     */
+    requestPermission(permission: PermissionType, reason: string): Promise<boolean>;
+    /**
+     * Persistent key-value storage API.
+     * Requires 'storage' permission to be granted first.
+     * Data syncs across devices for logged-in users.
+     */
+    storage: StorageAPI;
+    /**
+     * Network API for making HTTP requests through the secure host proxy.
+     * Requires 'network' permission and domains declared in manifest.
+     *
+     * **SECURITY:** Direct `fetch()` and `XMLHttpRequest` are blocked.
+     * This is the ONLY way to make network requests from addons.
+     *
+     * @example
+     * ```typescript
+     * // First, request permission
+     * const granted = await MyWallpaper.requestPermission('network', 'Fetch weather data')
+     * if (granted) {
+     *   const response = await MyWallpaper.network.fetch('https://api.weather.com/current')
+     *   if (response.ok) {
+     *     console.log(response.data)
+     *   }
+     * }
+     * ```
+     */
+    network: NetworkAPI;
+    /**
+     * OAuth API for making authenticated requests to provider APIs.
+     * Requires corresponding oauth permission (e.g., 'oauth:github').
+     *
+     * **SECURITY:** Your addon NEVER sees OAuth tokens. All requests are
+     * proxied through the backend which adds authentication server-side.
+     *
+     * **How it works:**
+     * 1. User connects their OAuth provider in MyWallpaper settings
+     * 2. Your addon requests permission (e.g., `oauth:github`)
+     * 3. API calls are proxied through the host
+     * 4. The host handles token refresh automatically
+     *
+     * @example
+     * ```typescript
+     * // First, request GitHub permission
+     * const granted = await MyWallpaper.requestPermission(
+     *   'oauth:github',
+     *   'Display your GitHub profile'
+     * )
+     *
+     * if (granted) {
+     *   // Make authenticated API calls
+     *   const response = await MyWallpaper.oauth.request('github', '/user')
+     *   if (response.ok) {
+     *     console.log('GitHub username:', response.data.login)
+     *   }
+     * }
+     * ```
+     */
+    oauth: OAuthAPI;
+}
+/**
+ * Augments the global Window interface with MyWallpaper API.
+ * Allows `window.MyWallpaper` to be used without type assertions.
+ */
+declare global {
+    interface Window {
+        /** Layer ID injected before addon loads */
+        __MYWALLPAPER_LAYER_ID__?: string;
+        /** Initial config injected before addon loads */
+        __MYWALLPAPER_INITIAL_CONFIG__?: Record<string, unknown>;
+        /** The main MyWallpaper API */
+        MyWallpaper: MyWallpaperAPI;
+    }
+}
+/**
+ * Lifecycle event names.
+ */
+type LifecycleEvent = 'mount' | 'unmount' | 'pause' | 'resume';
+/**
+ * Generic addon values (settings configuration).
+ */
+type AddonValues = Record<string, unknown>;
+
+/**
+ * @mywallpaper/addon-sdk - Manifest Schema & Validation
+ *
+ * Defines the addon manifest format (manifest.json) and provides
+ * Zod-based validation for type safety at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { validateManifest, type AddonManifest } from '@mywallpaper/addon-sdk/manifest'
+ *
+ * const manifest: AddonManifest = {
+ *   name: 'My Addon',
+ *   version: '1.0.0',
+ *   description: 'A cool addon',
+ *   settings: {
+ *     primaryColor: { type: 'color', default: '#ffffff', label: 'Primary Color' }
+ *   }
+ * }
+ *
+ * // Validate at runtime
+ * const result = validateManifest(manifest)
+ * if (!result.success) {
+ *   console.error('Invalid manifest:', result.errors)
+ * }
+ * ```
+ */
+
+/**
+ * Available setting types for addon configuration.
+ */
+type SettingType = 'string' | 'number' | 'boolean' | 'color' | 'select' | 'range' | 'image' | 'section' | 'textarea' | 'radio' | 'gradient' | 'vector2' | 'button' | 'multi-select';
+/**
+ * Definition for a single addon setting.
+ *
+ * @example
+ * ```typescript
+ * const colorSetting: SettingDefinition = {
+ *   type: 'color',
+ *   label: 'Background Color',
+ *   description: 'Choose a background color',
+ *   default: '#000000'
+ * }
+ *
+ * const speedSetting: SettingDefinition = {
+ *   type: 'range',
+ *   label: 'Animation Speed',
+ *   min: 0.1,
+ *   max: 10,
+ *   step: 0.1,
+ *   default: 1
+ * }
+ * ```
+ */
+interface SettingDefinition {
+    /** Setting type determines the UI control */
+    type: SettingType;
+    /** Human-readable label */
+    label?: string;
+    /** Help text shown below the control */
+    description?: string;
+    /** Default value (type depends on setting type) */
+    default?: unknown;
+    /** Options for select, radio, multi-select types */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Minimum value for range type */
+    min?: number;
+    /** Maximum value for range type */
+    max?: number;
+    /** Step increment for range type */
+    step?: number;
+    /** Label text on button */
+    buttonLabel?: string;
+    /** Axis labels for vector types, e.g., ['X', 'Y'] */
+    axisLabels?: [string, string] | [string, string, string];
+    /** Maximum number of selections */
+    maxItems?: number;
+    /** Only show if another setting has a specific value */
+    showIf?: {
+        setting: string;
+        equals: unknown;
+    };
+}
+/**
+ * Default layout configuration for addon positioning.
+ */
+interface AddonDefaultLayout {
+    /** X position as percentage of viewport width (0-100) */
+    xPercent?: number;
+    /** Y position as percentage of viewport height (0-100) */
+    yPercent?: number;
+    /** Width as percentage of viewport width (0-100) */
+    widthPercent?: number;
+    /** Height as percentage of viewport height (0-100) */
+    heightPercent?: number;
+    /** Rotation in degrees */
+    rotation?: number;
+}
+/**
+ * The complete addon manifest schema.
+ * This defines your addon's identity, settings, and capabilities.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "Weather Widget",
+ *   "version": "1.2.0",
+ *   "description": "Displays current weather conditions",
+ *   "author": "Jane Developer",
+ *   "categories": ["utilities", "weather"],
+ *   "capabilities": {
+ *     "hotReload": true,
+ *     "systemEvents": ["viewport:resize", "theme:change"]
+ *   },
+ *   "permissions": {
+ *     "storage": { "quota": 512 },
+ *     "network": { "domains": ["api.openweathermap.org"] }
+ *   },
+ *   "settings": {
+ *     "apiKey": {
+ *       "type": "string",
+ *       "label": "API Key",
+ *       "description": "Get your key at openweathermap.org"
+ *     },
+ *     "unit": {
+ *       "type": "select",
+ *       "label": "Temperature Unit",
+ *       "default": "celsius",
+ *       "options": [
+ *         { "value": "celsius", "label": "Celsius" },
+ *         { "value": "fahrenheit", "label": "Fahrenheit" }
+ *       ]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface AddonManifest {
+    /** Addon name (displayed in UI) */
+    name: string;
+    /** Semantic version (e.g., "1.0.0") */
+    version: string;
+    /** Short description of the addon */
+    description?: string;
+    /** Author name or organization */
+    author?: string;
+    /** Addon type/category for filtering */
+    type?: string;
+    /** Categories for discoverability */
+    categories?: string[];
+    /** License (e.g., "MIT", "Apache-2.0") */
+    license?: string;
+    /** Homepage or documentation URL */
+    homepage?: string;
+    /** Repository URL */
+    repository?: string;
+    /**
+     * User-configurable settings.
+     * Key is the setting ID, value is the definition.
+     */
+    settings?: Record<string, SettingDefinition>;
+    /**
+     * Addon capabilities and event subscriptions.
+     */
+    capabilities?: {
+        /** Supports settings changes without full reload */
+        hotReload?: boolean;
+        /** System events the addon wants to receive */
+        systemEvents?: SystemEventType[];
+    };
+    /**
+     * Permissions the addon will request.
+     * Declaring them here improves UX by showing upfront.
+     */
+    permissions?: {
+        /** Storage permission with quota in KB */
+        storage?: {
+            quota: number;
+        };
+        /** CPU usage limit */
+        cpu?: {
+            limit: 'low' | 'medium' | 'high';
+        };
+        /** Network access with allowed domains */
+        network?: {
+            domains: string[];
+        };
+        /** Audio playback permission */
+        audio?: boolean;
+        /** Notification permission */
+        notifications?: boolean;
+    };
+    /**
+     * Default layout for automatic positioning.
+     * Used when addon is first added to a wallpaper.
+     */
+    defaultLayout?: AddonDefaultLayout;
+    /**
+     * OAuth providers and scopes for authenticated addons.
+     *
+     * Declare the OAuth providers your addon needs and the scopes it requires.
+     * Scopes are requested incrementally - users can connect with basic scopes
+     * first, and your addon can request additional scopes when needed.
+     *
+     * @example
+     * ```json
+     * {
+     *   "permissions": {
+     *     "oauth": {
+     *       "required": [
+     *         { "provider": "github", "scopes": ["read:user"] }
+     *       ],
+     *       "optional": [
+     *         { "provider": "github", "scopes": ["repo"] }
+     *       ]
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    oauth?: {
+        /** OAuth providers required for the addon to function */
+        required?: Array<{
+            provider: OAuthProvider;
+            scopes: string[];
+            /** Reason shown to user when requesting this permission */
+            reason?: string;
+        }>;
+        /** OAuth providers that enhance functionality but aren't required */
+        optional?: Array<{
+            provider: OAuthProvider;
+            scopes: string[];
+            /** Reason shown to user when requesting this permission */
+            reason?: string;
+        }>;
+    };
+}
+/**
+ * Validation result type.
+ */
+interface ValidationResult {
+    success: boolean;
+    errors?: string[];
+    manifest?: AddonManifest;
+}
+/**
+ * Validates an addon manifest object.
+ *
+ * @param input - The manifest object to validate
+ * @returns ValidationResult with success status and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = validateManifest(myManifest)
+ * if (!result.success) {
+ *   result.errors?.forEach(err => console.error(err))
+ * }
+ * ```
+ */
+declare function validateManifest(input: unknown): ValidationResult;
+/**
+ * Type guard to check if an object is a valid AddonManifest.
+ *
+ * @param input - Object to check
+ * @returns True if input is a valid AddonManifest
+ */
+declare function isValidManifest(input: unknown): input is AddonManifest;
+/**
+ * Check if manifest declares hot-reload capability.
+ */
+declare function supportsHotReload(manifest: AddonManifest): boolean;
+/**
+ * Get system events the addon subscribes to.
+ */
+declare function getSubscribedEvents(manifest: AddonManifest): SystemEventType[];
+/**
+ * Get required permissions from manifest.
+ */
+declare function getRequiredPermissions(manifest: AddonManifest): PermissionType[];
+
+/**
+ * @mywallpaper/addon-sdk - Utility Functions
+ *
+ * Helper utilities for addon development.
+ */
+
+/**
+ * Creates a default configuration object from manifest settings.
+ *
+ * @param manifest - Addon manifest with settings definitions
+ * @returns Object with all setting keys and their default values
+ *
+ * @example
+ * ```typescript
+ * const manifest = {
+ *   name: 'My Addon',
+ *   version: '1.0.0',
+ *   settings: {
+ *     color: { type: 'color', default: '#ff0000' },
+ *     speed: { type: 'range', default: 1, min: 0, max: 10 }
+ *   }
+ * }
+ *
+ * const defaults = createDefaultConfig(manifest)
+ * // { color: '#ff0000', speed: 1 }
+ * ```
+ */
+declare function createDefaultConfig(manifest: AddonManifest): Record<string, unknown>;
+/**
+ * Merges user config with defaults, ensuring all keys exist.
+ *
+ * @param defaults - Default configuration
+ * @param userConfig - User-provided configuration (may be partial)
+ * @returns Complete configuration with user values taking precedence
+ *
+ * @example
+ * ```typescript
+ * const defaults = { color: '#ff0000', speed: 1 }
+ * const user = { color: '#00ff00' }
+ *
+ * const config = mergeConfigs(defaults, user)
+ * // { color: '#00ff00', speed: 1 }
+ * ```
+ */
+declare function mergeConfigs(defaults: Record<string, unknown>, userConfig: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Semantic version comparison result.
+ */
+type VersionComparison = -1 | 0 | 1;
+/**
+ * Compare two semantic versions.
+ *
+ * @param a - First version string
+ * @param b - Second version string
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ *
+ * @example
+ * ```typescript
+ * compareVersions('1.0.0', '1.0.1')  // -1
+ * compareVersions('2.0.0', '1.9.9')  // 1
+ * compareVersions('1.0.0', '1.0.0')  // 0
+ * ```
+ */
+declare function compareVersions(a: string, b: string): VersionComparison;
+/**
+ * Check if version satisfies a minimum requirement.
+ *
+ * @param version - Version to check
+ * @param minimum - Minimum required version
+ * @returns True if version >= minimum
+ */
+declare function satisfiesMinVersion(version: string, minimum: string): boolean;
+/**
+ * Calculate the byte size of a value when JSON serialized.
+ * Useful for quota tracking.
+ *
+ * @param value - Value to measure
+ * @returns Size in bytes
+ */
+declare function getStorageSize(value: unknown): number;
+/**
+ * Format bytes as human-readable string.
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 KB", "2.3 MB")
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Check if a value is a plain object.
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Check if a value is a valid color hex string.
+ */
+declare function isValidColor(value: unknown): value is string;
+/**
+ * Debounce a function - only call after delay with no new calls.
+ *
+ * @param fn - Function to debounce
+ * @param delayMs - Delay in milliseconds
+ * @returns Debounced function
+ *
+ * @example
+ * ```typescript
+ * const save = debounce((data) => {
+ *   localStorage.setItem('data', JSON.stringify(data))
+ * }, 1000)
+ *
+ * // Rapid calls only trigger one save after 1s
+ * save({ a: 1 })
+ * save({ a: 2 })
+ * save({ a: 3 }) // Only this one runs (after 1s)
+ * ```
+ */
+declare function debounce<T extends (...args: unknown[]) => void>(fn: T, delayMs: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle a function - call at most once per interval.
+ *
+ * @param fn - Function to throttle
+ * @param intervalMs - Minimum interval between calls
+ * @returns Throttled function
+ */
+declare function throttle<T extends (...args: unknown[]) => void>(fn: T, intervalMs: number): (...args: Parameters<T>) => void;
+/**
+ * Create a one-time event listener that auto-removes after first call.
+ *
+ * @param element - DOM element or window
+ * @param event - Event name
+ * @param handler - Event handler
+ */
+declare function once(element: EventTarget, event: string, handler: EventListener): void;
+
+/**
+ * @mywallpaper/addon-sdk
+ *
+ * Official SDK for building MyWallpaper addons.
+ *
+ * @packageDocumentation
+ *
+ * ## Installation
+ *
+ * ```bash
+ * npm install @mywallpaper/addon-sdk
+ * ```
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * // Your addon's main file
+ * import type { MyWallpaperAPI } from '@mywallpaper/addon-sdk'
+ *
+ * // The API is automatically available on window.MyWallpaper
+ * const api = window.MyWallpaper
+ *
+ * // Access configuration
+ * const { backgroundColor, animationSpeed } = api.config
+ *
+ * // React to setting changes (hot-reload)
+ * api.onSettingsChange((settings, changedKeys) => {
+ *   if (changedKeys.includes('backgroundColor')) {
+ *     document.body.style.background = settings.backgroundColor as string
+ *   }
+ * })
+ *
+ * // Subscribe to system events
+ * api.onEvent('viewport:resize', ({ width, height }) => {
+ *   canvas.width = width
+ *   canvas.height = height
+ * })
+ *
+ * // Signal addon is ready
+ * api.ready({
+ *   capabilities: ['hot-reload'],
+ *   subscribedEvents: ['viewport:resize']
+ * })
+ *
+ * // After visual rendering is complete
+ * await loadImages()
+ * render()
+ * api.renderComplete()
+ * ```
+ *
+ * ## Manifest Validation
+ *
+ * ```typescript
+ * import { validateManifest, type AddonManifest } from '@mywallpaper/addon-sdk/manifest'
+ *
+ * const manifest: AddonManifest = {
+ *   name: 'My Addon',
+ *   version: '1.0.0',
+ *   settings: {
+ *     color: { type: 'color', default: '#ffffff' }
+ *   }
+ * }
+ *
+ * const result = validateManifest(manifest)
+ * if (!result.success) {
+ *   console.error(result.errors)
+ * }
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * Current SDK version.
+ */
+declare const SDK_VERSION = "2.0.0";
+/**
+ * Minimum compatible host version.
+ */
+declare const MIN_HOST_VERSION = "2.0.0";
+
+export { type AddonCapability, type AddonDefaultLayout, type AddonManifest, type AddonValues, type EventCallback, type LifecycleEvent, MIN_HOST_VERSION, type MyWallpaperAPI, type NetworkAPI, type NetworkResponse, type OAuthAPI, type OAuthPermissionType, type OAuthProvider, type OAuthResponse, type OAuthScopesError, type PermissionConstraints, type PermissionType, type ReadyOptions, SDK_VERSION, type SettingDefinition, type SettingType, type SettingsCallback, type StorageAPI, type SystemEventData, type SystemEventType, type ValidationResult, type VersionComparison, compareVersions, createDefaultConfig, debounce, formatBytes, getRequiredPermissions, getStorageSize, getSubscribedEvents, isPlainObject, isValidColor, isValidManifest, mergeConfigs, once, satisfiesMinVersion, supportsHotReload, throttle, validateManifest };