fix(sync): enhance auto-sync on suspend to queue and upload session/progress immediately

    if self.force_push_session_on_suspend then

        self:logInfo("BookloreSync: Force push on suspend enabled")

        -- In automatic suspend-sync mode, queue current progress right now and

        -- flush immediately so session/progress are uploaded on suspend instead

        -- of waiting for deferred wake/close pipelines.

        if self.progress_sync_enabled then

            local queued_progress = self:queueCurrentKoreaderProgress()

            self:logInfo("BookloreSync: Suspend progress queue result:", tostring(queued_progress))

        end

        if self.connect_network_on_suspend then

            -- When ask_wifi_enable is on, prompt before enabling WiFi.

            -- On deny, we still attempt syncPendingSessions (it will be a

            -- no-op if offline, data stays queued).

            self:_requestWifi(_("sync sessions on suspend"), function()

                self:logInfo("BookloreSync: Network ready - force syncing pending sessions on suspend")

            -- Automatic suspend sync should actively try to bring WiFi up.

            -- If ask_wifi_enable is enabled we keep the permission prompt;

            -- otherwise we connect directly.

            if self.ask_wifi_enable then

                self:_requestWifi(_("sync sessions and progress on suspend"), function()

                    self:logInfo("BookloreSync: Network ready - force syncing pending sessions/progress on suspend")

                    self:syncPendingSessions(true)

                end, function()

                self:logInfo("BookloreSync: WiFi request declined on suspend - sessions remain queued")

                    self:logInfo("BookloreSync: WiFi request declined on suspend - data remains queued")

                end)

            else

            self:logInfo("BookloreSync: Force syncing pending sessions on suspend")

                local connected = NetworkMgr:isConnected() or self:connectNetwork()

                if connected then

                    self:logInfo("BookloreSync: Network ready - force syncing pending sessions/progress on suspend")

                    self:syncPendingSessions(true)

                else

                    self:logInfo("BookloreSync: Could not connect WiFi on suspend - data remains queued")

                end

            end

        else

            self:logInfo("BookloreSync: Force syncing pending sessions/progress on suspend")

            self:syncPendingSessions(true)

        end

    else

- Auto-sync on suspend

- Connect WiFi on suspend

- Ask to enable WiFi

With **Automatic** mode (or **Custom** with both suspend toggles enabled), suspend now queues and attempts to upload both the current session and current progress immediately.

| Trigger | Behaviour |

|---------|-----------|

| **Device suspend** | If **Auto-sync on suspend** is enabled, session + current progress are queued and upload is attempted immediately |

| **Session end** | Sync attempted after every valid session (if not in Manual Sync Only mode) |

| **Device resume** | Deferred background sync 15 seconds after device wakes from sleep |

| **Network connected** | Immediate sync when network becomes available (if a wake sync was pending) |

- **Confirm** - WiFi is enabled and the sync proceeds.

- **Cancel** - WiFi is not enabled. The session stays queued and will be uploaded the next time a sync is triggered while WiFi is already on.

This prompt appears before any sync attempt that would require enabling WiFi, including session-end syncs, wake syncs, and manually triggered syncs.

This prompt appears before any sync attempt that would require enabling WiFi, including suspend auto-sync, session-end syncs, wake syncs, and manually triggered syncs.

To configure this, see **Tools → BookLore Sync → Sync Behavior → Ask to enable WiFi**.

|-------|---------|--------|

| `onReaderReady` | Book opens | Start new session |

| `onCloseDocument` | Book closes | End session, validate, queue |

| `onSuspend` | Device sleeps | End session, validate, queue |

| `onSuspend` | Device sleeps | End session, validate, queue, then immediate sync attempt when suspend auto-sync is enabled |

| `onResume` | Device wakes | Start new session, sync pending |

---

### Resume cooldown

To avoid flooding the server when a device suspends and resumes rapidly (e.g., repeated short sleep events), the plugin enforces a **5-minute cooldown** between auto-syncs triggered by resume. If a resume event occurs within 5 minutes of the last auto-sync, the sync is deferred rather than run immediately.

To avoid flooding the server when a device suspends and resumes rapidly (e.g., repeated short sleep events), the plugin enforces a **5-minute cooldown** between auto-syncs triggered by resume.

- If no queued sessions/progress exist, a resume inside the cooldown window skips auto-sync.

- If queued sessions or progress exist, the cooldown is overridden and the pending data is synced.

### Deferred wake sync

When the device wakes, the plugin schedules a sync to run **15 seconds after resume**. This gives the network time to reconnect before the upload is attempted. If the network is not yet available after 15 seconds, the session stays queued and will be picked up when connectivity is detected.

This wake path is a fallback/background path. With **Auto-sync on suspend** enabled, the plugin already attempts to upload session and progress during suspend.

### Network-connected sync

If the plugin is waiting for network and the device reports a new connection (via the `onNetworkConnected` event), any deferred wake sync is triggered immediately without waiting for the full 15-second timer.

A result from the ISBN search is only accepted if the server returns an exact match (`matchScore == 1`). If no exact match is found, or if no ISBN is embedded in the file, the user is shown a brief notification.

If the server is unreachable when you open the book, the session is saved with `book_id = NULL`. When the plugin next attempts to sync (on resume, on the next session end, or via manual sync), it re-queries the server using the cached hash to resolve the ID before uploading.

If the server is unreachable when you open the book, the session is saved with `book_id = NULL`. When the plugin next attempts to sync (on the next automatic sync trigger, on the next session end, or via manual sync), it re-queries the server using the cached hash to resolve the ID before uploading.

See [Features → Book ID Resolution](@/features/book-id-resolution.md) for the full details, including how to embed ISBNs into your book files so the fallback can work.