@mywallpaper/addon-sdk 2.9.0 → 2.10.0

package/dist/index.d.mts

@@ -603,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.
@@ -870,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

@@ -603,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.
@@ -870,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

@@ -588,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.
@@ -851,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

@@ -588,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.
@@ -851,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.9.0",
+  "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

@@ -31,6 +31,7 @@
   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 = {
@@ -714,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 })
+      }
     }
   }