@mywallpaper/addon-sdk 2.8.1 → 2.10.0

package/dist/index.d.mts

@@ -151,6 +151,15 @@ interface NetworkResponse {
     /** Response data (auto-parsed JSON, text, or base64 for binary) */
     data: unknown;
 }
+/**
+ * Result of a network domain access request.
+ */
+interface NetworkAccessResult {
+    /** Whether access was granted */
+    granted: boolean;
+    /** Error message if denied */
+    error?: string;
+}
 /**
  * Network API for making HTTP requests through the secure host proxy.
  * Access via `window.MyWallpaper.network`
@@ -158,7 +167,9 @@ interface NetworkResponse {
  * **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:
+ * **Two ways to access external domains:**
+ *
+ * 1. **Manifest declaration** (pre-approved):
  * ```json
  * {
  *   "permissions": {
@@ -167,14 +178,25 @@ interface NetworkResponse {
  * }
  * ```
  *
+ * 2. **On-demand permission** (user approval at runtime):
+ * ```typescript
+ * const result = await network.requestAccess('fonts.example.com', 'Load custom fonts')
+ * if (result.granted) {
+ *   const response = await network.fetch('https://fonts.example.com/myfont.woff2')
+ * }
+ * ```
+ *
  * @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)
+ * // On-demand access to a domain (shows permission modal)
+ * const access = await network.requestAccess('api.weather.com', 'Fetch weather data')
+ * if (access.granted) {
+ *   const response = await network.fetch('https://api.weather.com/current')
+ *   if (response.ok) {
+ *     console.log(response.data)
+ *   }
  * }
  *
  * // POST request with JSON body
@@ -186,9 +208,33 @@ interface NetworkResponse {
  * ```
  */
 interface NetworkAPI {
+    /**
+     * Request on-demand access to a domain.
+     * Shows a permission modal to the user: "Widget X requests access to: domain.com"
+     * This permission lasts for the current session only (not persisted).
+     *
+     * @param domain - The domain to request access to (e.g., 'fonts.cdnfonts.com')
+     * @param reason - User-friendly explanation of why access is needed
+     * @returns Promise resolving to NetworkAccessResult
+     *
+     * @example
+     * ```typescript
+     * const result = await api.network.requestAccess(
+     *   'fonts.cdnfonts.com',
+     *   'Load custom font for text display'
+     * )
+     * if (result.granted) {
+     *   // Now we can fetch from this domain
+     *   const css = await api.network.fetch('https://fonts.cdnfonts.com/css/anurati')
+     * }
+     * ```
+     */
+    requestAccess(domain: string, reason: string): Promise<NetworkAccessResult>;
     /**
      * Make an HTTP request through the secure host proxy.
-     * Domain must be whitelisted in manifest.json permissions.
+     * Domain must be either:
+     * - Whitelisted in manifest.json permissions, OR
+     * - Approved via requestAccess() in the current session
      *
      * @param url - Full URL to fetch (must be in allowed domains)
      * @param options - Optional request options
@@ -557,6 +603,21 @@ interface MyWallpaperAPI {
      * ```
      */
     audio: AudioAPI;
+    /**
+     * Settings API for dynamically modifying setting options at runtime.
+     * Allows widgets to populate dropdowns based on external data.
+     *
+     * @example
+     * ```typescript
+     * // After loading font CSS, update the font family dropdown
+     * const fonts = parseFontFaces(cssContent)
+     * api.settings.updateOptions('fontFamily', fonts.map(f => ({
+     *   label: f.family,
+     *   value: f.family
+     * })))
+     * ```
+     */
+    settings: SettingsAPI;
     /**
      * File Access API for requesting access to user-uploaded files.
      * Files are not sent automatically - the addon must request access.
@@ -824,6 +885,86 @@ interface AudioAPI {
      */
     onStateChange(callback: (state: AudioState) => void): () => void;
 }
+/**
+ * A setting option for select/dropdown fields.
+ */
+interface SettingOption {
+    /** Display label shown to user */
+    label: string;
+    /** Value stored when selected */
+    value: string | number | boolean;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * Settings API for dynamically modifying setting options at runtime.
+ * Access via `window.MyWallpaper.settings`
+ *
+ * **Why this exists:**
+ * Some widgets need to populate setting options dynamically based on
+ * external data (e.g., font families from a CSS file, available themes
+ * from an API, etc.). This API allows widgets to modify their own
+ * setting options after loading.
+ *
+ * **Important:**
+ * - Only works for settings declared in manifest.json
+ * - Only 'select' type settings can have their options updated
+ * - Changes are session-only (manifest defines the defaults)
+ *
+ * @example
+ * ```typescript
+ * const api = window.MyWallpaper
+ *
+ * // After fetching a font CSS, parse available fonts and update dropdown
+ * const fonts = parseFontFaces(cssContent)
+ * api.settings.updateOptions('fontFamily', fonts.map(f => ({
+ *   label: f.family,
+ *   value: f.family
+ * })))
+ *
+ * // Update multiple settings at once
+ * api.settings.updateOptions('fontWeight', [
+ *   { label: 'Light', value: '300' },
+ *   { label: 'Regular', value: '400' },
+ *   { label: 'Bold', value: '700' }
+ * ])
+ * ```
+ */
+interface SettingsAPI {
+    /**
+     * Update the options for a select-type setting.
+     * The new options replace existing ones from the manifest.
+     *
+     * @param settingKey - The setting key to update (must be a 'select' type)
+     * @param options - Array of new options
+     * @param defaultValue - Optional new default value
+     *
+     * @example
+     * ```typescript
+     * // Update font family options based on loaded CSS
+     * api.settings.updateOptions('customFontFamily', [
+     *   { label: 'Roboto', value: 'Roboto' },
+     *   { label: 'Open Sans', value: 'Open Sans' },
+     *   { label: 'Lato', value: 'Lato' }
+     * ], 'Roboto')
+     * ```
+     */
+    updateOptions(settingKey: string, options: SettingOption[], defaultValue?: string | number | boolean): void;
+    /**
+     * Get the current options for a setting.
+     * Returns the dynamic options if set, otherwise the manifest defaults.
+     *
+     * @param settingKey - The setting key to get options for
+     * @returns Array of options or undefined if not a select setting
+     */
+    getOptions(settingKey: string): SettingOption[] | undefined;
+    /**
+     * Reset a setting's options back to the manifest defaults.
+     *
+     * @param settingKey - The setting key to reset
+     */
+    resetOptions(settingKey: string): void;
+}
 /**
  * Generic addon values (settings configuration).
  */

package/dist/index.d.ts

@@ -151,6 +151,15 @@ interface NetworkResponse {
     /** Response data (auto-parsed JSON, text, or base64 for binary) */
     data: unknown;
 }
+/**
+ * Result of a network domain access request.
+ */
+interface NetworkAccessResult {
+    /** Whether access was granted */
+    granted: boolean;
+    /** Error message if denied */
+    error?: string;
+}
 /**
  * Network API for making HTTP requests through the secure host proxy.
  * Access via `window.MyWallpaper.network`
@@ -158,7 +167,9 @@ interface NetworkResponse {
  * **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:
+ * **Two ways to access external domains:**
+ *
+ * 1. **Manifest declaration** (pre-approved):
  * ```json
  * {
  *   "permissions": {
@@ -167,14 +178,25 @@ interface NetworkResponse {
  * }
  * ```
  *
+ * 2. **On-demand permission** (user approval at runtime):
+ * ```typescript
+ * const result = await network.requestAccess('fonts.example.com', 'Load custom fonts')
+ * if (result.granted) {
+ *   const response = await network.fetch('https://fonts.example.com/myfont.woff2')
+ * }
+ * ```
+ *
  * @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)
+ * // On-demand access to a domain (shows permission modal)
+ * const access = await network.requestAccess('api.weather.com', 'Fetch weather data')
+ * if (access.granted) {
+ *   const response = await network.fetch('https://api.weather.com/current')
+ *   if (response.ok) {
+ *     console.log(response.data)
+ *   }
  * }
  *
  * // POST request with JSON body
@@ -186,9 +208,33 @@ interface NetworkResponse {
  * ```
  */
 interface NetworkAPI {
+    /**
+     * Request on-demand access to a domain.
+     * Shows a permission modal to the user: "Widget X requests access to: domain.com"
+     * This permission lasts for the current session only (not persisted).
+     *
+     * @param domain - The domain to request access to (e.g., 'fonts.cdnfonts.com')
+     * @param reason - User-friendly explanation of why access is needed
+     * @returns Promise resolving to NetworkAccessResult
+     *
+     * @example
+     * ```typescript
+     * const result = await api.network.requestAccess(
+     *   'fonts.cdnfonts.com',
+     *   'Load custom font for text display'
+     * )
+     * if (result.granted) {
+     *   // Now we can fetch from this domain
+     *   const css = await api.network.fetch('https://fonts.cdnfonts.com/css/anurati')
+     * }
+     * ```
+     */
+    requestAccess(domain: string, reason: string): Promise<NetworkAccessResult>;
     /**
      * Make an HTTP request through the secure host proxy.
-     * Domain must be whitelisted in manifest.json permissions.
+     * Domain must be either:
+     * - Whitelisted in manifest.json permissions, OR
+     * - Approved via requestAccess() in the current session
      *
      * @param url - Full URL to fetch (must be in allowed domains)
      * @param options - Optional request options
@@ -557,6 +603,21 @@ interface MyWallpaperAPI {
      * ```
      */
     audio: AudioAPI;
+    /**
+     * Settings API for dynamically modifying setting options at runtime.
+     * Allows widgets to populate dropdowns based on external data.
+     *
+     * @example
+     * ```typescript
+     * // After loading font CSS, update the font family dropdown
+     * const fonts = parseFontFaces(cssContent)
+     * api.settings.updateOptions('fontFamily', fonts.map(f => ({
+     *   label: f.family,
+     *   value: f.family
+     * })))
+     * ```
+     */
+    settings: SettingsAPI;
     /**
      * File Access API for requesting access to user-uploaded files.
      * Files are not sent automatically - the addon must request access.
@@ -824,6 +885,86 @@ interface AudioAPI {
      */
     onStateChange(callback: (state: AudioState) => void): () => void;
 }
+/**
+ * A setting option for select/dropdown fields.
+ */
+interface SettingOption {
+    /** Display label shown to user */
+    label: string;
+    /** Value stored when selected */
+    value: string | number | boolean;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * Settings API for dynamically modifying setting options at runtime.
+ * Access via `window.MyWallpaper.settings`
+ *
+ * **Why this exists:**
+ * Some widgets need to populate setting options dynamically based on
+ * external data (e.g., font families from a CSS file, available themes
+ * from an API, etc.). This API allows widgets to modify their own
+ * setting options after loading.
+ *
+ * **Important:**
+ * - Only works for settings declared in manifest.json
+ * - Only 'select' type settings can have their options updated
+ * - Changes are session-only (manifest defines the defaults)
+ *
+ * @example
+ * ```typescript
+ * const api = window.MyWallpaper
+ *
+ * // After fetching a font CSS, parse available fonts and update dropdown
+ * const fonts = parseFontFaces(cssContent)
+ * api.settings.updateOptions('fontFamily', fonts.map(f => ({
+ *   label: f.family,
+ *   value: f.family
+ * })))
+ *
+ * // Update multiple settings at once
+ * api.settings.updateOptions('fontWeight', [
+ *   { label: 'Light', value: '300' },
+ *   { label: 'Regular', value: '400' },
+ *   { label: 'Bold', value: '700' }
+ * ])
+ * ```
+ */
+interface SettingsAPI {
+    /**
+     * Update the options for a select-type setting.
+     * The new options replace existing ones from the manifest.
+     *
+     * @param settingKey - The setting key to update (must be a 'select' type)
+     * @param options - Array of new options
+     * @param defaultValue - Optional new default value
+     *
+     * @example
+     * ```typescript
+     * // Update font family options based on loaded CSS
+     * api.settings.updateOptions('customFontFamily', [
+     *   { label: 'Roboto', value: 'Roboto' },
+     *   { label: 'Open Sans', value: 'Open Sans' },
+     *   { label: 'Lato', value: 'Lato' }
+     * ], 'Roboto')
+     * ```
+     */
+    updateOptions(settingKey: string, options: SettingOption[], defaultValue?: string | number | boolean): void;
+    /**
+     * Get the current options for a setting.
+     * Returns the dynamic options if set, otherwise the manifest defaults.
+     *
+     * @param settingKey - The setting key to get options for
+     * @returns Array of options or undefined if not a select setting
+     */
+    getOptions(settingKey: string): SettingOption[] | undefined;
+    /**
+     * Reset a setting's options back to the manifest defaults.
+     *
+     * @param settingKey - The setting key to reset
+     */
+    resetOptions(settingKey: string): void;
+}
 /**
  * Generic addon values (settings configuration).
  */

package/dist/manifest.d.mts

@@ -136,6 +136,15 @@ interface NetworkResponse {
     /** Response data (auto-parsed JSON, text, or base64 for binary) */
     data: unknown;
 }
+/**
+ * Result of a network domain access request.
+ */
+interface NetworkAccessResult {
+    /** Whether access was granted */
+    granted: boolean;
+    /** Error message if denied */
+    error?: string;
+}
 /**
  * Network API for making HTTP requests through the secure host proxy.
  * Access via `window.MyWallpaper.network`
@@ -143,7 +152,9 @@ interface NetworkResponse {
  * **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:
+ * **Two ways to access external domains:**
+ *
+ * 1. **Manifest declaration** (pre-approved):
  * ```json
  * {
  *   "permissions": {
@@ -152,14 +163,25 @@ interface NetworkResponse {
  * }
  * ```
  *
+ * 2. **On-demand permission** (user approval at runtime):
+ * ```typescript
+ * const result = await network.requestAccess('fonts.example.com', 'Load custom fonts')
+ * if (result.granted) {
+ *   const response = await network.fetch('https://fonts.example.com/myfont.woff2')
+ * }
+ * ```
+ *
  * @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)
+ * // On-demand access to a domain (shows permission modal)
+ * const access = await network.requestAccess('api.weather.com', 'Fetch weather data')
+ * if (access.granted) {
+ *   const response = await network.fetch('https://api.weather.com/current')
+ *   if (response.ok) {
+ *     console.log(response.data)
+ *   }
  * }
  *
  * // POST request with JSON body
@@ -171,9 +193,33 @@ interface NetworkResponse {
  * ```
  */
 interface NetworkAPI {
+    /**
+     * Request on-demand access to a domain.
+     * Shows a permission modal to the user: "Widget X requests access to: domain.com"
+     * This permission lasts for the current session only (not persisted).
+     *
+     * @param domain - The domain to request access to (e.g., 'fonts.cdnfonts.com')
+     * @param reason - User-friendly explanation of why access is needed
+     * @returns Promise resolving to NetworkAccessResult
+     *
+     * @example
+     * ```typescript
+     * const result = await api.network.requestAccess(
+     *   'fonts.cdnfonts.com',
+     *   'Load custom font for text display'
+     * )
+     * if (result.granted) {
+     *   // Now we can fetch from this domain
+     *   const css = await api.network.fetch('https://fonts.cdnfonts.com/css/anurati')
+     * }
+     * ```
+     */
+    requestAccess(domain: string, reason: string): Promise<NetworkAccessResult>;
     /**
      * Make an HTTP request through the secure host proxy.
-     * Domain must be whitelisted in manifest.json permissions.
+     * Domain must be either:
+     * - Whitelisted in manifest.json permissions, OR
+     * - Approved via requestAccess() in the current session
      *
      * @param url - Full URL to fetch (must be in allowed domains)
      * @param options - Optional request options
@@ -542,6 +588,21 @@ interface MyWallpaperAPI {
      * ```
      */
     audio: AudioAPI;
+    /**
+     * Settings API for dynamically modifying setting options at runtime.
+     * Allows widgets to populate dropdowns based on external data.
+     *
+     * @example
+     * ```typescript
+     * // After loading font CSS, update the font family dropdown
+     * const fonts = parseFontFaces(cssContent)
+     * api.settings.updateOptions('fontFamily', fonts.map(f => ({
+     *   label: f.family,
+     *   value: f.family
+     * })))
+     * ```
+     */
+    settings: SettingsAPI;
     /**
      * File Access API for requesting access to user-uploaded files.
      * Files are not sent automatically - the addon must request access.
@@ -805,6 +866,86 @@ interface AudioAPI {
      */
     onStateChange(callback: (state: AudioState) => void): () => void;
 }
+/**
+ * A setting option for select/dropdown fields.
+ */
+interface SettingOption {
+    /** Display label shown to user */
+    label: string;
+    /** Value stored when selected */
+    value: string | number | boolean;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * Settings API for dynamically modifying setting options at runtime.
+ * Access via `window.MyWallpaper.settings`
+ *
+ * **Why this exists:**
+ * Some widgets need to populate setting options dynamically based on
+ * external data (e.g., font families from a CSS file, available themes
+ * from an API, etc.). This API allows widgets to modify their own
+ * setting options after loading.
+ *
+ * **Important:**
+ * - Only works for settings declared in manifest.json
+ * - Only 'select' type settings can have their options updated
+ * - Changes are session-only (manifest defines the defaults)
+ *
+ * @example
+ * ```typescript
+ * const api = window.MyWallpaper
+ *
+ * // After fetching a font CSS, parse available fonts and update dropdown
+ * const fonts = parseFontFaces(cssContent)
+ * api.settings.updateOptions('fontFamily', fonts.map(f => ({
+ *   label: f.family,
+ *   value: f.family
+ * })))
+ *
+ * // Update multiple settings at once
+ * api.settings.updateOptions('fontWeight', [
+ *   { label: 'Light', value: '300' },
+ *   { label: 'Regular', value: '400' },
+ *   { label: 'Bold', value: '700' }
+ * ])
+ * ```
+ */
+interface SettingsAPI {
+    /**
+     * Update the options for a select-type setting.
+     * The new options replace existing ones from the manifest.
+     *
+     * @param settingKey - The setting key to update (must be a 'select' type)
+     * @param options - Array of new options
+     * @param defaultValue - Optional new default value
+     *
+     * @example
+     * ```typescript
+     * // Update font family options based on loaded CSS
+     * api.settings.updateOptions('customFontFamily', [
+     *   { label: 'Roboto', value: 'Roboto' },
+     *   { label: 'Open Sans', value: 'Open Sans' },
+     *   { label: 'Lato', value: 'Lato' }
+     * ], 'Roboto')
+     * ```
+     */
+    updateOptions(settingKey: string, options: SettingOption[], defaultValue?: string | number | boolean): void;
+    /**
+     * Get the current options for a setting.
+     * Returns the dynamic options if set, otherwise the manifest defaults.
+     *
+     * @param settingKey - The setting key to get options for
+     * @returns Array of options or undefined if not a select setting
+     */
+    getOptions(settingKey: string): SettingOption[] | undefined;
+    /**
+     * Reset a setting's options back to the manifest defaults.
+     *
+     * @param settingKey - The setting key to reset
+     */
+    resetOptions(settingKey: string): void;
+}
 
 /**
  * @mywallpaper/addon-sdk - Manifest Schema & Validation

package/dist/manifest.d.ts

@@ -136,6 +136,15 @@ interface NetworkResponse {
     /** Response data (auto-parsed JSON, text, or base64 for binary) */
     data: unknown;
 }
+/**
+ * Result of a network domain access request.
+ */
+interface NetworkAccessResult {
+    /** Whether access was granted */
+    granted: boolean;
+    /** Error message if denied */
+    error?: string;
+}
 /**
  * Network API for making HTTP requests through the secure host proxy.
  * Access via `window.MyWallpaper.network`
@@ -143,7 +152,9 @@ interface NetworkResponse {
  * **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:
+ * **Two ways to access external domains:**
+ *
+ * 1. **Manifest declaration** (pre-approved):
  * ```json
  * {
  *   "permissions": {
@@ -152,14 +163,25 @@ interface NetworkResponse {
  * }
  * ```
  *
+ * 2. **On-demand permission** (user approval at runtime):
+ * ```typescript
+ * const result = await network.requestAccess('fonts.example.com', 'Load custom fonts')
+ * if (result.granted) {
+ *   const response = await network.fetch('https://fonts.example.com/myfont.woff2')
+ * }
+ * ```
+ *
  * @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)
+ * // On-demand access to a domain (shows permission modal)
+ * const access = await network.requestAccess('api.weather.com', 'Fetch weather data')
+ * if (access.granted) {
+ *   const response = await network.fetch('https://api.weather.com/current')
+ *   if (response.ok) {
+ *     console.log(response.data)
+ *   }
  * }
  *
  * // POST request with JSON body
@@ -171,9 +193,33 @@ interface NetworkResponse {
  * ```
  */
 interface NetworkAPI {
+    /**
+     * Request on-demand access to a domain.
+     * Shows a permission modal to the user: "Widget X requests access to: domain.com"
+     * This permission lasts for the current session only (not persisted).
+     *
+     * @param domain - The domain to request access to (e.g., 'fonts.cdnfonts.com')
+     * @param reason - User-friendly explanation of why access is needed
+     * @returns Promise resolving to NetworkAccessResult
+     *
+     * @example
+     * ```typescript
+     * const result = await api.network.requestAccess(
+     *   'fonts.cdnfonts.com',
+     *   'Load custom font for text display'
+     * )
+     * if (result.granted) {
+     *   // Now we can fetch from this domain
+     *   const css = await api.network.fetch('https://fonts.cdnfonts.com/css/anurati')
+     * }
+     * ```
+     */
+    requestAccess(domain: string, reason: string): Promise<NetworkAccessResult>;
     /**
      * Make an HTTP request through the secure host proxy.
-     * Domain must be whitelisted in manifest.json permissions.
+     * Domain must be either:
+     * - Whitelisted in manifest.json permissions, OR
+     * - Approved via requestAccess() in the current session
      *
      * @param url - Full URL to fetch (must be in allowed domains)
      * @param options - Optional request options
@@ -542,6 +588,21 @@ interface MyWallpaperAPI {
      * ```
      */
     audio: AudioAPI;
+    /**
+     * Settings API for dynamically modifying setting options at runtime.
+     * Allows widgets to populate dropdowns based on external data.
+     *
+     * @example
+     * ```typescript
+     * // After loading font CSS, update the font family dropdown
+     * const fonts = parseFontFaces(cssContent)
+     * api.settings.updateOptions('fontFamily', fonts.map(f => ({
+     *   label: f.family,
+     *   value: f.family
+     * })))
+     * ```
+     */
+    settings: SettingsAPI;
     /**
      * File Access API for requesting access to user-uploaded files.
      * Files are not sent automatically - the addon must request access.
@@ -805,6 +866,86 @@ interface AudioAPI {
      */
     onStateChange(callback: (state: AudioState) => void): () => void;
 }
+/**
+ * A setting option for select/dropdown fields.
+ */
+interface SettingOption {
+    /** Display label shown to user */
+    label: string;
+    /** Value stored when selected */
+    value: string | number | boolean;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * Settings API for dynamically modifying setting options at runtime.
+ * Access via `window.MyWallpaper.settings`
+ *
+ * **Why this exists:**
+ * Some widgets need to populate setting options dynamically based on
+ * external data (e.g., font families from a CSS file, available themes
+ * from an API, etc.). This API allows widgets to modify their own
+ * setting options after loading.
+ *
+ * **Important:**
+ * - Only works for settings declared in manifest.json
+ * - Only 'select' type settings can have their options updated
+ * - Changes are session-only (manifest defines the defaults)
+ *
+ * @example
+ * ```typescript
+ * const api = window.MyWallpaper
+ *
+ * // After fetching a font CSS, parse available fonts and update dropdown
+ * const fonts = parseFontFaces(cssContent)
+ * api.settings.updateOptions('fontFamily', fonts.map(f => ({
+ *   label: f.family,
+ *   value: f.family
+ * })))
+ *
+ * // Update multiple settings at once
+ * api.settings.updateOptions('fontWeight', [
+ *   { label: 'Light', value: '300' },
+ *   { label: 'Regular', value: '400' },
+ *   { label: 'Bold', value: '700' }
+ * ])
+ * ```
+ */
+interface SettingsAPI {
+    /**
+     * Update the options for a select-type setting.
+     * The new options replace existing ones from the manifest.
+     *
+     * @param settingKey - The setting key to update (must be a 'select' type)
+     * @param options - Array of new options
+     * @param defaultValue - Optional new default value
+     *
+     * @example
+     * ```typescript
+     * // Update font family options based on loaded CSS
+     * api.settings.updateOptions('customFontFamily', [
+     *   { label: 'Roboto', value: 'Roboto' },
+     *   { label: 'Open Sans', value: 'Open Sans' },
+     *   { label: 'Lato', value: 'Lato' }
+     * ], 'Roboto')
+     * ```
+     */
+    updateOptions(settingKey: string, options: SettingOption[], defaultValue?: string | number | boolean): void;
+    /**
+     * Get the current options for a setting.
+     * Returns the dynamic options if set, otherwise the manifest defaults.
+     *
+     * @param settingKey - The setting key to get options for
+     * @returns Array of options or undefined if not a select setting
+     */
+    getOptions(settingKey: string): SettingOption[] | undefined;
+    /**
+     * Reset a setting's options back to the manifest defaults.
+     *
+     * @param settingKey - The setting key to reset
+     */
+    resetOptions(settingKey: string): void;
+}
 
 /**
  * @mywallpaper/addon-sdk - Manifest Schema & Validation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mywallpaper/addon-sdk",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "description": "SDK for building MyWallpaper addons - TypeScript types, manifest validation, and utilities",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/runtime/addon-client.js

@@ -29,7 +29,9 @@
   var pendingOAuth = new Map()
   var pendingOAuthScopes = new Map()
   var pendingFileAccess = new Map()
+  var pendingNetworkAccess = new Map()  // For on-demand domain permission requests
   var grantedBlobUrls = new Map() // settingKey -> blobUrl
+  var dynamicSettingsOptions = new Map() // settingKey -> options[] (dynamic options from widget)
 
   // Audio state (synced from host)
   var audioState = {
@@ -52,6 +54,39 @@
     if (!d || d.source !== 'MyWallpaperHost') return
 
     switch (d.type) {
+      case 'SETTINGS_PREVIEW':
+        // FAST PATH: Lightweight preview for drag operations (color picker, sliders)
+        // Updates CSS variables AND triggers callbacks for immediate visual feedback
+        var previewPayload = d.payload || d
+        var previewSettings = previewPayload.settings || {}
+        var previewKeys = previewPayload.changedKeys || Object.keys(previewSettings)
+
+        // Update CSS variables
+        try {
+          var previewRoot = document.documentElement
+          for (var pi = 0; pi < previewKeys.length; pi++) {
+            var pKey = previewKeys[pi]
+            var pValue = previewSettings[pKey]
+            if (pValue !== undefined && pValue !== null) {
+              var pType = typeof pValue
+              if (pType === 'string' || pType === 'number' || pType === 'boolean') {
+                previewRoot.style.setProperty('--mw-config-' + pKey, String(pValue))
+              }
+            }
+          }
+        } catch (previewErr) {
+          // Silent fail
+        }
+
+        // Also update config and trigger callbacks for addons that use JS
+        for (var pk = 0; pk < previewKeys.length; pk++) {
+          config[previewKeys[pk]] = previewSettings[previewKeys[pk]]
+        }
+        settingsCallbacks.forEach(function (cb) {
+          try { cb(config, previewKeys) } catch (err) { /* silent */ }
+        })
+        break
+
       case 'SETTINGS_UPDATE':
         var p = d.payload || d
         config = p.settings || p
@@ -197,6 +232,15 @@
         }
         break
 
+      case 'NETWORK_ACCESS_RESPONSE':
+        // Handle network domain access response from host
+        var netAccessOp = pendingNetworkAccess.get(d.requestId)
+        if (netAccessOp) {
+          pendingNetworkAccess.delete(d.requestId)
+          netAccessOp.resolve({ granted: d.granted === true, error: d.error })
+        }
+        break
+
       case 'AUDIO_STATE':
         // Sync audio state from host
         audioState = d.payload || d
@@ -225,10 +269,33 @@
     })
   }
 
+  /**
+   * Request on-demand access to a network domain
+   * Shows a permission modal to the user
+   * @param {string} domain - The domain to request access to
+   * @param {string} reason - User-friendly explanation
+   * @returns {Promise<{granted: boolean, error?: string}>}
+   */
+  function networkRequestAccess(domain, reason) {
+    return new Promise(function (resolve) {
+      var id = Date.now() + '-' + Math.random().toString(36).slice(2)
+      pendingNetworkAccess.set(id, { resolve: resolve })
+      // 60s timeout - user needs time to respond to modal
+      setTimeout(function () {
+        if (pendingNetworkAccess.has(id)) {
+          pendingNetworkAccess.delete(id)
+          resolve({ granted: false, error: 'Request timeout' })
+        }
+      }, 60000)
+      send('NETWORK_DOMAIN_REQUEST', { domain: domain, reason: reason, requestId: id })
+    })
+  }
+
   /**
    * Network fetch via secure host proxy
    * This is the ONLY way addons can make network requests
    * Domain must be declared in manifest.json permissions.network.domains
+   * OR approved via networkRequestAccess()
    */
   function networkFetch(url, options) {
     return new Promise(function (resolve, reject) {
@@ -414,11 +481,18 @@
      * All requests go through the host which validates domain whitelist
      *
      * @example
+     * // Option 1: Pre-declare domains in manifest.json
      * // manifest.json: "permissions": { "network": { "domains": ["api.weather.com"] } }
      * const response = await MyWallpaper.network.fetch('https://api.weather.com/current')
-     * if (response.ok) console.log(response.data)
+     *
+     * // Option 2: On-demand permission (shows modal to user)
+     * const access = await MyWallpaper.network.requestAccess('fonts.example.com', 'Load fonts')
+     * if (access.granted) {
+     *   const response = await MyWallpaper.network.fetch('https://fonts.example.com/font.woff2')
+     * }
      */
     network: {
+      requestAccess: networkRequestAccess,
       fetch: networkFetch
     },
 
@@ -641,6 +715,76 @@
         callback(audioState)
         return function () { audioCallbacks.delete(callback) }
       }
+    },
+
+    /**
+     * Settings API - Dynamically modify setting options at runtime
+     * Allows widgets to populate dropdowns based on external data
+     *
+     * @example
+     * // After fetching a font CSS, parse available fonts and update dropdown
+     * const fonts = parseFontFaces(cssContent)
+     * MyWallpaper.settings.updateOptions('fontFamily', fonts.map(f => ({
+     *   label: f.family,
+     *   value: f.family
+     * })))
+     */
+    settings: {
+      /**
+       * Update the options for a select-type setting
+       * @param {string} settingKey - The setting key to update
+       * @param {Array<{label: string, value: string|number|boolean, description?: string}>} options - New options
+       * @param {string|number|boolean} defaultValue - Optional new default value
+       */
+      updateOptions: function (settingKey, options, defaultValue) {
+        if (!settingKey || typeof settingKey !== 'string') {
+          console.error('[MyWallpaper] settings.updateOptions: settingKey is required')
+          return
+        }
+        if (!Array.isArray(options)) {
+          console.error('[MyWallpaper] settings.updateOptions: options must be an array')
+          return
+        }
+
+        // Validate options format
+        var validOptions = options.filter(function (opt) {
+          return opt && typeof opt === 'object' && typeof opt.label === 'string' && opt.value !== undefined
+        })
+
+        if (validOptions.length === 0) {
+          console.warn('[MyWallpaper] settings.updateOptions: no valid options provided')
+          return
+        }
+
+        // Store locally for getOptions()
+        dynamicSettingsOptions.set(settingKey, validOptions)
+
+        // Send to host to update the settings panel
+        send('SETTINGS_OPTIONS_UPDATE', {
+          settingKey: settingKey,
+          options: validOptions,
+          defaultValue: defaultValue
+        })
+      },
+
+      /**
+       * Get the current options for a setting
+       * Returns dynamic options if set, otherwise undefined
+       * @param {string} settingKey - The setting key
+       * @returns {Array|undefined} The options array or undefined
+       */
+      getOptions: function (settingKey) {
+        return dynamicSettingsOptions.get(settingKey)
+      },
+
+      /**
+       * Reset a setting's options back to the manifest defaults
+       * @param {string} settingKey - The setting key to reset
+       */
+      resetOptions: function (settingKey) {
+        dynamicSettingsOptions.delete(settingKey)
+        send('SETTINGS_OPTIONS_RESET', { settingKey: settingKey })
+      }
     }
   }