despia-native 1.0.14 → 1.0.17

package/README.md

@@ -640,9 +640,24 @@ These CSS variables are automatically provided by the Despia native runtime and
 - **watch** (string[], optional): Array of variable names to watch for in the response
 
 Returns a Promise that resolves when all watched variables are available:
-- **Single variable**: 5-second timeout with simple observation
+- **Single variable**: 30-second timeout with observation that ignores empty placeholders and requires a fresh write (Promise always resolves; on timeout it resolves with `undefined`)
 - **Multiple variables**: Uses VariableTracker with 5-minute auto-cleanup
 
+### Timeout behavior
+
+When you call `despia(command, ['someVariable'])`, the SDK waits up to 30 seconds for
+`window.someVariable` to be set by the native runtime. If it appears earlier, the
+Promise resolves with that value. If it is never set, the Promise still resolves
+after 30 seconds with `undefined` and a timeout is logged to the console. This
+prevents hanging Promises for long-running or failing native operations.
+
+### Fresh-data behavior
+
+Before observing, watched variables are cleared to avoid resolving on stale values.
+The observer ignores empty placeholders (`undefined`, `null`, `"n/a"`, `{}`, `[]`)
+and requires the value to change from its baseline before resolving. This ensures
+each call waits for a fresh write from the native side.
+
 ### Direct Property Access
 
 Access any window variable directly through the despia object:

package/index.js

@@ -41,21 +41,53 @@
         processQueue();
       }
     }
+
+    // Generate a safe signature for change detection
+    function safeSig(val) {
+        if (val === undefined) return 'u';
+        if (val === null) return 'n';
+        const t = typeof val;
+        if (t !== 'object') return `${t}:${String(val)}`;
+        try { return `o:${JSON.stringify(val)}`; } catch { return 'o:[unserializable]'; }
+    }
   
-    // Simple variable observer with 5-second timeout
-    function observeDespiaVariable(variableName, callback, timeout = 5000) {
+    // Simple variable observer with longer timeout, change detection, and guaranteed resolve
+    function observeDespiaVariable(variableName, callback, timeout = 30000) {
         const startTime = Date.now();
-        
+        const initialRef = window[variableName];
+        const initialSig = safeSig(initialRef);
+
+        const ready = (val) => {
+            if (val === undefined || val === null || val === "n/a") return false;
+            if (Array.isArray(val) && val.length === 0) return false;
+            if (val && typeof val === 'object' && !Array.isArray(val) && Object.keys(val).length === 0) return false;
+            return true;
+        };
+
+        const changed = (val) => {
+            if (val !== initialRef) return true;
+            return safeSig(val) !== initialSig;
+        };
+
         function checkVariable() {
-            if (window[variableName] !== undefined) {
-                callback(window[variableName]);
-            } else if (Date.now() - startTime < timeout) {
+            const val = window[variableName];
+
+            if (ready(val) && changed(val)) {
+                // Fresh, non-empty value arrived → resolve with it
+                callback(val);
+                return;
+            }
+
+            if (Date.now() - startTime < timeout) {
                 setTimeout(checkVariable, 100);
-            } else {
-                console.error(`Despia timeout: ${variableName} was not set within ${timeout} ms`);
+                return;
             }
+
+            // Timeout: still resolve so promises don't hang
+            console.error(`Despia timeout: ${variableName} was not set within ${timeout} ms`);
+            callback(undefined);
         }
-        
+
         checkVariable();
     }
 
@@ -124,12 +156,17 @@
             return Promise.resolve({});
         }
 
+        // Pre-clear watched vars to avoid stale immediate resolves
+        variables.forEach((name) => {
+            try { delete window[name]; } catch (e) { window[name] = undefined; }
+        });
+
         if (variables.length === 1) {
-            // Simple single variable observation with 5-second timeout
+            // Simple single variable observation with 30-second timeout
             return new Promise((resolve) => {
                 observeDespiaVariable(variables[0], (value) => {
                     resolve({ [variables[0]]: value });
-                }, 5000);
+                }, 30000);
             });
         } else {
             // Multiple variables - use VariableTracker (no timeout, expires after 5 minutes)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "despia-native",
-    "version": "1.0.14",
+    "version": "1.0.17",
     "description": "JavaScript SDK for Despia native integrations with command queuing and variable watching",
     "main": "index.js",
     "module": "index.js",