@mywallpaper/addon-sdk 2.8.1 → 2.9.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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mywallpaper/addon-sdk",
-  "version": "2.8.1",
+  "version": "2.9.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,6 +29,7 @@
   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
 
   // Audio state (synced from host)
@@ -52,6 +53,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 +231,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 +268,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 +480,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
     },