fix: Add throttle guard and documentation to Service Worker version sync (#8695)

Author: tobiu

src/worker/Manager.mjs

@@ -148,6 +148,14 @@ class Manager extends Base {
         !Neo.insideWorker && me.createWorkers();
 
         if (navigator.serviceWorker) {
+            // Bind the message handler globally to ensure even "unmanaged" apps (those not using the SW addon)
+            // can receive critical recovery commands (like 'reloadWindow') from the Service Worker.
+            //
+            // CRITICAL: We must bind this even if Neo.config.useServiceWorker is false.
+            // Scenario: User visits App A (uses SW), then navigates to App B (no SW). The SW from App A
+            // *still controls* App B (if in scope). If App B hits a version mismatch (404), the SW will
+            // send a 'reloadWindow' command. App B must be listening to execute this recovery command,
+            // otherwise it will crash with a blank page.
             navigator.serviceWorker.onmessage = me.onWorkerMessage.bind(me);
             me.checkServiceWorkerVersion()
         }
@@ -183,6 +191,12 @@ class Manager extends Base {
     }
 
     /**
+     * Proactively checks if the controlling Service Worker's version matches the client's version.
+     * This is the primary defense against "Zombie Apps" (stale client code running against a new Service Worker).
+     *
+     * If a mismatch is detected, it forces a hard reload to fetch fresh assets.
+     * Includes a throttle mechanism (via sessionStorage) to prevent infinite reload loops in case of persistent mismatches.
+     *
      * @returns {Promise<void>}
      */
     async checkServiceWorkerVersion() {
@@ -192,6 +206,18 @@ class Manager extends Base {
             });
 
             if (swVersion?.version && swVersion.version !== Neo.config.version) {
+                const
+                    key        = 'neoVersionReload',
+                    lastReload = parseInt(sessionStorage.getItem(key) || '0'),
+                    now        = Date.now();
+
+                if (now - lastReload < 5000) {
+                    console.error('Reload loop detected. Aborting version enforcement.');
+                    return
+                }
+
+                sessionStorage.setItem(key, String(now));
+
                 console.error(`Version Mismatch! Client: ${Neo.config.version}, SW: ${swVersion.version}. Reloading.`);
                 location.reload(true)
             }

src/worker/ServiceBase.mjs

@@ -49,6 +49,8 @@ class ServiceBase extends Base {
          */
         mixins: [RemoteMethodAccess],
         /**
+         * Flag to enable the automatic 404 recovery strategy.
+         * If true, 404 errors on guarded paths will trigger a client reload.
          * @member {Boolean} reloadOn404=true
          */
         reloadOn404: true,
@@ -265,6 +267,12 @@ class ServiceBase extends Base {
     }
 
     /**
+     * Intercepts 404 errors on guarded paths (dist/production, src) to detect version mismatches.
+     * If a mismatch is suspected (old app asking for deleted asset), triggers a forced client reload.
+     *
+     * Use Case: "Reactive Recovery" for when the Boot-Time check passes (or hasn't run) but the
+     * environment changes mid-session (Atomic Deployment deletes assets).
+     *
      * @param {ExtendableMessageEvent} event
      */
     async on404(event) {