despia-native 1.0.15 → 1.0.17

package/README.md

@@ -640,7 +640,7 @@ 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**: 30-second timeout with simple observation (Promise always resolves; on timeout it resolves with `undefined`)
+- **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
@@ -651,6 +651,13 @@ 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,16 +41,39 @@
         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 longer timeout and guaranteed resolve
+    // 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() {
             const val = window[variableName];
 
-            // Preserve existing semantics: any non-undefined value is "ready"
-            if (val !== undefined) {
+            if (ready(val) && changed(val)) {
+                // Fresh, non-empty value arrived → resolve with it
                 callback(val);
                 return;
             }
@@ -60,8 +83,8 @@
                 return;
             }
 
+            // Timeout: still resolve so promises don't hang
             console.error(`Despia timeout: ${variableName} was not set within ${timeout} ms`);
-            // Ensure promises watching this variable never hang forever
             callback(undefined);
         }
 
@@ -133,6 +156,11 @@
             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 30-second timeout
             return new Promise((resolve) => {

package/package.json

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