@mywallpaper/addon-sdk 2.12.0 → 2.14.0

package/README.md

@@ -48,7 +48,7 @@ my-addon/
 {
   "name": "My Awesome Addon",
   "version": "1.0.0",
-  "sdkVersion": "2.12.0",
+  "sdkVersion": "2.13.0",
   "description": "A cool widget for your desktop",
   "author": "Your Name",
   "capabilities": {

package/dist/index.d.mts

@@ -955,6 +955,37 @@ interface SettingOption {
  * ```
  */
 interface SettingsAPI {
+    /**
+     * Update a single setting value from the addon.
+     * This syncs the value back to the host UI and persists it.
+     *
+     * @param settingKey - The setting key to update
+     * @param value - The new value
+     *
+     * @example
+     * ```typescript
+     * // Update a color setting after randomization
+     * api.settings.setValue('primaryColor', '#ff0000')
+     * ```
+     */
+    setValue(settingKey: string, value: unknown): void;
+    /**
+     * Update multiple setting values at once.
+     * This syncs all values back to the host UI and persists them.
+     *
+     * @param values - Object with settingKey -> value pairs
+     *
+     * @example
+     * ```typescript
+     * // Update multiple colors after randomization
+     * api.settings.setValues({
+     *   primaryColor: '#ff0000',
+     *   secondaryColor: '#00ff00',
+     *   backgroundColor: '#0000ff'
+     * })
+     * ```
+     */
+    setValues(values: Record<string, unknown>): void;
     /**
      * Update the options for a select-type setting.
      * The new options replace existing ones from the manifest.

package/dist/index.d.ts

@@ -955,6 +955,37 @@ interface SettingOption {
  * ```
  */
 interface SettingsAPI {
+    /**
+     * Update a single setting value from the addon.
+     * This syncs the value back to the host UI and persists it.
+     *
+     * @param settingKey - The setting key to update
+     * @param value - The new value
+     *
+     * @example
+     * ```typescript
+     * // Update a color setting after randomization
+     * api.settings.setValue('primaryColor', '#ff0000')
+     * ```
+     */
+    setValue(settingKey: string, value: unknown): void;
+    /**
+     * Update multiple setting values at once.
+     * This syncs all values back to the host UI and persists them.
+     *
+     * @param values - Object with settingKey -> value pairs
+     *
+     * @example
+     * ```typescript
+     * // Update multiple colors after randomization
+     * api.settings.setValues({
+     *   primaryColor: '#ff0000',
+     *   secondaryColor: '#00ff00',
+     *   backgroundColor: '#0000ff'
+     * })
+     * ```
+     */
+    setValues(values: Record<string, unknown>): void;
     /**
      * Update the options for a select-type setting.
      * The new options replace existing ones from the manifest.

package/dist/manifest.d.mts

@@ -936,6 +936,37 @@ interface SettingOption {
  * ```
  */
 interface SettingsAPI {
+    /**
+     * Update a single setting value from the addon.
+     * This syncs the value back to the host UI and persists it.
+     *
+     * @param settingKey - The setting key to update
+     * @param value - The new value
+     *
+     * @example
+     * ```typescript
+     * // Update a color setting after randomization
+     * api.settings.setValue('primaryColor', '#ff0000')
+     * ```
+     */
+    setValue(settingKey: string, value: unknown): void;
+    /**
+     * Update multiple setting values at once.
+     * This syncs all values back to the host UI and persists them.
+     *
+     * @param values - Object with settingKey -> value pairs
+     *
+     * @example
+     * ```typescript
+     * // Update multiple colors after randomization
+     * api.settings.setValues({
+     *   primaryColor: '#ff0000',
+     *   secondaryColor: '#00ff00',
+     *   backgroundColor: '#0000ff'
+     * })
+     * ```
+     */
+    setValues(values: Record<string, unknown>): void;
     /**
      * Update the options for a select-type setting.
      * The new options replace existing ones from the manifest.

package/dist/manifest.d.ts

@@ -936,6 +936,37 @@ interface SettingOption {
  * ```
  */
 interface SettingsAPI {
+    /**
+     * Update a single setting value from the addon.
+     * This syncs the value back to the host UI and persists it.
+     *
+     * @param settingKey - The setting key to update
+     * @param value - The new value
+     *
+     * @example
+     * ```typescript
+     * // Update a color setting after randomization
+     * api.settings.setValue('primaryColor', '#ff0000')
+     * ```
+     */
+    setValue(settingKey: string, value: unknown): void;
+    /**
+     * Update multiple setting values at once.
+     * This syncs all values back to the host UI and persists them.
+     *
+     * @param values - Object with settingKey -> value pairs
+     *
+     * @example
+     * ```typescript
+     * // Update multiple colors after randomization
+     * api.settings.setValues({
+     *   primaryColor: '#ff0000',
+     *   secondaryColor: '#00ff00',
+     *   backgroundColor: '#0000ff'
+     * })
+     * ```
+     */
+    setValues(values: Record<string, unknown>): void;
     /**
      * Update the options for a select-type setting.
      * The new options replace existing ones from the manifest.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mywallpaper/addon-sdk",
-  "version": "2.12.0",
+  "version": "2.14.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

@@ -30,6 +30,7 @@
   var pendingOAuthScopes = new Map()
   var pendingFileAccess = new Map()
   var pendingNetworkAccess = new Map()  // For on-demand domain permission requests
+  var pendingSystem = new Map()  // requestId -> { resolve, reject } for system API
   var grantedBlobUrls = new Map() // settingKey -> blobUrl
   var dynamicSettingsOptions = new Map() // settingKey -> options[] (dynamic options from widget)
   var buttonCallbacks = new Map() // settingKey -> callback function for button clicks
@@ -244,6 +245,19 @@
         }
         break
 
+      case 'SYSTEM_RESPONSE':
+        // Handle system API response (openPath, etc.)
+        var sysOp = pendingSystem.get(d.payload.requestId)
+        if (sysOp) {
+          pendingSystem.delete(d.payload.requestId)
+          if (d.payload.success) {
+            sysOp.resolve({ success: true })
+          } else {
+            sysOp.reject(new Error(d.payload.error || 'System operation failed'))
+          }
+        }
+        break
+
       case 'AUDIO_STATE':
         // Sync audio state from host
         audioState = d.payload || d
@@ -426,7 +440,7 @@
   window.MyWallpaper = {
     get config() { return config },
     layerId: layerId,
-    version: '2.11.0',
+    version: '2.13.0',
 
     onSettingsChange: function (fn) { if (typeof fn === 'function') settingsCallbacks.push(fn) },
 
@@ -470,7 +484,7 @@
       isReady = true
       opts = opts || {}
       send('ADDON_READY', {
-        version: '2.11.0',
+        version: '2.13.0',
         capabilities: opts.capabilities || [],
         subscribedEvents: opts.subscribedEvents || []
       })
@@ -761,6 +775,42 @@
      * })))
      */
     settings: {
+      /**
+       * Update a setting value from the addon
+       * This syncs the value back to the host UI and persists it
+       * @param {string} settingKey - The setting key to update
+       * @param {*} value - The new value
+       */
+      setValue: function (settingKey, value) {
+        if (!settingKey || typeof settingKey !== 'string') {
+          console.error('[MyWallpaper] settings.setValue: settingKey is required')
+          return
+        }
+        // Update local config immediately
+        config[settingKey] = value
+        // Send to host to update UI and persist
+        send('SETTINGS_VALUE_UPDATE', { settingKey: settingKey, value: value })
+      },
+
+      /**
+       * Update multiple setting values at once
+       * @param {Record<string, *>} values - Object with settingKey -> value pairs
+       */
+      setValues: function (values) {
+        if (!values || typeof values !== 'object') {
+          console.error('[MyWallpaper] settings.setValues: values object is required')
+          return
+        }
+        // Update local config immediately
+        for (var key in values) {
+          if (Object.prototype.hasOwnProperty.call(values, key)) {
+            config[key] = values[key]
+          }
+        }
+        // Send to host to update UI and persist
+        send('SETTINGS_VALUES_UPDATE', { values: values })
+      },
+
       /**
        * Update the options for a select-type setting
        * @param {string} settingKey - The setting key to update
@@ -816,8 +866,67 @@
         dynamicSettingsOptions.delete(settingKey)
         send('SETTINGS_OPTIONS_RESET', { settingKey: settingKey })
       }
+    },
+
+    /**
+     * System API - Interact with the host operating system
+     * Allows opening URLs, files, folders, and applications
+     *
+     * Requires 'system' permission in manifest:
+     * { "permissions": { "system": { "openPath": true } } }
+     *
+     * @example
+     * // Open a URL
+     * await MyWallpaper.system.openPath('https://github.com')
+     *
+     * // Open a folder in file explorer
+     * await MyWallpaper.system.openPath('/home/user/Documents', { type: 'folder' })
+     *
+     * // Open an app via protocol handler
+     * await MyWallpaper.system.openPath('spotify://open')
+     */
+    system: {
+      /**
+       * Open a URL, file, folder, or application
+       *
+       * @param {string} path - The path to open:
+       *   - URL: https://example.com
+       *   - File: /path/to/file.pdf (executes with default app)
+       *   - Folder: /path/to/folder (opens in file explorer)
+       *   - Protocol: spotify://, discord://, vscode:// (opens app)
+       * @param {object} options - Optional configuration
+       * @param {string} options.type - Force type: 'auto'|'url'|'file'|'folder'|'protocol'
+       * @returns {Promise<{success: true}>} Resolves when operation completes
+       * @throws {Error} If operation fails or permission denied
+       */
+      openPath: function (path, options) {
+        return new Promise(function (resolve, reject) {
+          if (!path || typeof path !== 'string') {
+            reject(new Error('path is required and must be a string'))
+            return
+          }
+
+          var id = Date.now() + '-' + Math.random().toString(36).slice(2)
+          pendingSystem.set(id, { resolve: resolve, reject: reject })
+
+          // Timeout after 10 seconds
+          setTimeout(function () {
+            if (pendingSystem.has(id)) {
+              pendingSystem.delete(id)
+              reject(new Error('System operation timeout'))
+            }
+          }, 10000)
+
+          options = options || {}
+          send('SYSTEM_OPEN_PATH', {
+            path: path,
+            type: options.type || 'auto',
+            requestId: id
+          })
+        })
+      }
     }
   }
 
-  console.warn('[MyWallpaper] SDK v2.11.0 ready:', layerId)
+  console.warn('[MyWallpaper] SDK v2.14.0 ready:', layerId)
 })()