Merge branch 'main' of https://github.com/StroepWafel/BetterSEQTA-Plus

src/seqta/ui/AddBetterSEQTAElements.ts

@@ -3,6 +3,7 @@ import { isSeqtaEngageExperience } from "@/seqta/utils/isSeqtaEngage";
 import { loadEngageHomePage } from "@/seqta/utils/Loaders/LoadEngageHomePage";
 import { loadHomePage } from "@/seqta/utils/Loaders/LoadHomePage";
 import { SendNewsPage } from "@/seqta/utils/SendNewsPage";
+import { attachNotificationsPanelAnimation } from "@/seqta/utils/attachNotificationsPanelAnimation";
 import { setupSettingsButton } from "@/seqta/utils/setupSettingsButton";
 import { waitForElm } from "@/seqta/utils/waitForElm";
 
@@ -89,6 +90,7 @@ export async function AddBetterSEQTAElements() {
   addExtensionSettings();
   await createSettingsButton();
   setupSettingsButton();
+  attachNotificationsPanelAnimation();
 }
 
 function createHomeButton(fragment: DocumentFragment, _: HTMLElement) {
@@ -423,10 +425,12 @@ async function setupEngageSettingsButton() {
     await addDarkLightToggle(parent);
     await createSettingsButton(parent);
     setupSettingsButton();
+    attachNotificationsPanelAnimation();
   } catch {
     await addDarkLightToggle();
     await createSettingsButton();
     setupSettingsButton();
+    attachNotificationsPanelAnimation();
   }
 }
 

src/seqta/utils/CloudAuth.ts

@@ -83,6 +83,25 @@ class CloudAuthService {
     }
   }
 
+  /** Pull cloud settings backup after a fresh sign-in (matches manual “Download from cloud”). */
+  private triggerCloudSettingsDownloadAfterLogin(accessToken: string): void {
+    void browser.runtime
+      .sendMessage({
+        type: "cloudSettingsDownload",
+        token: accessToken,
+      })
+      .then((res: unknown) => {
+        const r = res as { success?: boolean; notFound?: boolean; error?: string } | undefined;
+        if (r?.success || r?.notFound) return;
+        if (r?.error) {
+          console.warn("[BetterSEQTA+] Cloud settings download after login:", r.error);
+        }
+      })
+      .catch((err) => {
+        console.warn("[BetterSEQTA+] Cloud settings download after login failed:", err);
+      });
+  }
+
   public async getStoredToken(): Promise<string | null> {
     const result = await browser.storage.local.get(STORAGE_KEYS.accessToken);
     return (result[STORAGE_KEYS.accessToken] as string) ?? null;
@@ -108,6 +127,26 @@ class CloudAuthService {
     return clientId;
   }
 
+  public async startLogin(): Promise<{ success: boolean; error?: string }> {
+    try {
+      const clientId = await this.getClientId();
+      const result = (await browser.runtime.sendMessage({
+        type: "cloudStartLogin",
+        client_id: clientId,
+        redirect_uri: REDIRECT_URI,
+      })) as { success?: boolean; error?: string };
+      if (result?.success) {
+        return { success: true };
+      }
+      return { success: false, error: result?.error ?? "Failed to open login page" };
+    } catch (err) {
+      return {
+        success: false,
+        error: err instanceof Error ? err.message : "Failed to open login page",
+      };
+    }
+  }
+
   public async login(
     login: string,
     password: string
@@ -135,6 +174,7 @@ class CloudAuthService {
           user: result.user ?? null,
         };
         this.notify();
+        this.triggerCloudSettingsDownloadAfterLogin(result.access_token);
         return { success: true };
       }
       return {

src/seqta/utils/Openers/OpenBsCloudAutoSyncAnnouncement.ts

@@ -0,0 +1,71 @@
+import stringToHTML from "../stringToHTML";
+import { settingsState } from "../listeners/SettingsState";
+import { openPopup } from "./PopupManager";
+import { attachPopupMediaFullscreen } from "./attachPopupMediaFullscreen";
+
+/** Same hosting pattern as the What's New update video (GitHub raw). */
+const BS_CLOUD_DEMO_VIDEO_URL =
+  "https://raw.githubusercontent.com/BetterSEQTA/BetterSEQTA-Plus/main/src/resources/bsclouddemo.webm";
+
+export function shouldShowBsCloudAutoSyncAnnouncement(): boolean {
+  return !settingsState.bsCloudAutoSyncAnnouncementShown;
+}
+
+/**
+ * One-time announcement for BetterSEQTA Cloud automatic settings sync (after other startup popups).
+ * Video layout matches {@link OpenWhatsNewPopup} (`whatsnewImgContainer` / `whatsnewImg`).
+ */
+export function showBsCloudAutoSyncAnnouncement(onDismissed?: () => void) {
+  if (document.getElementById("whatsnewbk")) {
+    onDismissed?.();
+    return;
+  }
+  if (!shouldShowBsCloudAutoSyncAnnouncement()) {
+    onDismissed?.();
+    return;
+  }
+
+  const header = stringToHTML(
+    /* html */
+    `<div class="whatsnewHeader bsCloudAutoSyncAnnouncementHeader">
+      <h1>BetterSEQTA Cloud</h1>
+    </div>`,
+  ).firstChild as HTMLElement;
+
+  const imageContainer = document.createElement("div");
+  imageContainer.classList.add("whatsnewImgContainer");
+
+  const video = document.createElement("video");
+  const source = document.createElement("source");
+  source.setAttribute("src", BS_CLOUD_DEMO_VIDEO_URL);
+  source.setAttribute("type", "video/webm");
+  video.autoplay = true;
+  video.muted = true;
+  video.loop = true;
+  video.appendChild(source);
+  video.classList.add("whatsnewImg");
+  imageContainer.appendChild(video);
+  attachPopupMediaFullscreen(video);
+
+  const text = stringToHTML(/* html */ `
+    <div class="whatsnewTextContainer privacyStatement" style="height: 50%; overflow-y: auto; font-size: 1.2rem; line-height: 1.6;">
+      <p>
+        <strong class="bsCloudAccent">BetterSEQTA Cloud</strong> can keep your BetterSEQTA+ settings backed up and in
+        sync across browsers. Optional <strong>automatic settings sync</strong> runs when you are signed in (passwords
+        and tokens are never included).
+      </p>
+      <p>
+        Close this dialog when you are done. We will not show this announcement again.
+      </p>
+      <p class="bsCloudAutoSyncSignupCallout">Sign up in BetterSEQTA settings</p>
+    </div>
+  `).firstChild as HTMLElement;
+
+  settingsState.bsCloudAutoSyncAnnouncementShown = true;
+
+  openPopup({
+    header,
+    content: [imageContainer, text],
+    afterClose: onDismissed,
+  });
+}

src/seqta/utils/Openers/OpenEngageParentsAnnouncement.ts

@@ -0,0 +1,54 @@
+import { settingsState } from "../listeners/SettingsState";
+import { animate as motionAnimate } from "motion";
+
+export function shouldShowEngageParentsAnnouncement(): boolean {
+  return !settingsState.engageParentsAnnouncementShown;
+}
+
+/**
+ * Non-blocking bottom-right toast announcing SEQTA Engage support. Shown once.
+ */
+export function showEngageParentsToast() {
+  if (!shouldShowEngageParentsAnnouncement()) return;
+
+  settingsState.engageParentsAnnouncementShown = true;
+
+  const toast = document.createElement("div");
+  toast.className = "bsplus-toast";
+  toast.innerHTML = /* html */ `
+    <div class="bsplus-toast-content">
+      <strong>BetterSEQTA+ now supports <span class="seqtaEngageAccent">SEQTA Engage</span></strong>
+      <p>Buy your mum a BetterSEQTA Plus! Parents now get themes, a cleaner home page, and all the Plus polish on SEQTA Engage.</p>
+    </div>
+    <button class="bsplus-toast-close" aria-label="Dismiss">&times;</button>
+  `;
+
+  toast.style.opacity = "0";
+  document.getElementById("container")?.append(toast);
+
+  if (settingsState.animations) {
+    (motionAnimate as any)(
+      toast,
+      { opacity: [0, 1], y: [40, 0] },
+      { duration: 0.35, easing: [0.22, 0.03, 0.26, 1] },
+    );
+  } else {
+    toast.style.opacity = "1";
+  }
+
+  const dismiss = () => {
+    if (settingsState.animations) {
+      (motionAnimate as any)(
+        toast,
+        { opacity: [1, 0], y: [0, 40] },
+        { duration: 0.2, easing: [0.22, 0.03, 0.26, 1] },
+      ).then(() => toast.remove());
+    } else {
+      toast.remove();
+    }
+  };
+
+  toast.querySelector(".bsplus-toast-close")!.addEventListener("click", dismiss);
+
+  setTimeout(dismiss, 10000);
+}

src/seqta/utils/Openers/OpenPrivacyNotification.ts

@@ -1,13 +1,31 @@
 import stringToHTML from "../stringToHTML";
 import { settingsState } from "../listeners/SettingsState";
 import { openPopup } from "./PopupManager";
+import { attachPopupMediaFullscreenIfPresent } from "./attachPopupMediaFullscreen";
 
-export function showPrivacyNotification() {
-  const lastUpdated = "2025-12-19";
+const PRIVACY_STATEMENT_VERSION = "2025-12-19";
 
-  if (document.getElementById("whatsnewbk")) return;
-  if (settingsState.privacyStatementShown) return;
-  if (settingsState.privacyStatementLastUpdated && new Date(settingsState.privacyStatementLastUpdated) > new Date(lastUpdated)) return;
+export function shouldShowPrivacyNotification(): boolean {
+  if (settingsState.privacyStatementShown) return false;
+  if (
+    settingsState.privacyStatementLastUpdated &&
+    new Date(settingsState.privacyStatementLastUpdated) >
+      new Date(PRIVACY_STATEMENT_VERSION)
+  ) {
+    return false;
+  }
+  return true;
+}
+
+export function showPrivacyNotification(onDismissed?: () => void) {
+  if (document.getElementById("whatsnewbk")) {
+    onDismissed?.();
+    return;
+  }
+  if (!shouldShowPrivacyNotification()) {
+    onDismissed?.();
+    return;
+  }
 
   const header = stringToHTML(
     /* html */
@@ -42,11 +60,14 @@ export function showPrivacyNotification() {
     </div>
   `).firstChild as HTMLElement;
 
+  attachPopupMediaFullscreenIfPresent(text, "img.aboutImg");
+
   settingsState.privacyStatementLastUpdated = "2025-12-20";
   settingsState.privacyStatementShown = true;
 
   openPopup({
     header,
     content: [text],
+    afterClose: onDismissed,
   });
 }

src/seqta/utils/Openers/OpenWhatsNewPopup.ts

@@ -2,8 +2,9 @@ import stringToHTML from "../stringToHTML";
 import browser from "webextension-polyfill";
 import kofi from "@/resources/kofi.png?base64";
 import { openPopup } from "./PopupManager";
+import { attachPopupMediaFullscreen } from "./attachPopupMediaFullscreen";
 
-export function OpenWhatsNewPopup() {
+export function OpenWhatsNewPopup(onDismissed?: () => void) {
   const header = stringToHTML(
     /* html */
     `<div class="whatsnewHeader">
@@ -28,11 +29,12 @@ export function OpenWhatsNewPopup() {
   video.appendChild(source);
   video.classList.add("whatsnewImg");
   imageContainer.appendChild(video);
+  attachPopupMediaFullscreen(video);
 
   const text = stringToHTML(/* html */ `
     <div class="whatsnewTextContainer" style="height: 50%;overflow-y: auto;">
 
-      <h1>3.6.0 - Cloud backup, various fixes & SEQTA Engage support</h1>
+      <h1>3.6.2 - Cloud backup, various fixes & SEQTA Engage support</h1>
       <li>BetterSEQTA Cloud: back up and restore extension settings from your account (General settings).</li>
       <li>Optional automatic cloud sync if signed in (on by default).</li>
       <li>Option to use cloud profile photo as the local SEQTA profile picture</li>
@@ -43,7 +45,8 @@ export function OpenWhatsNewPopup() {
       <li>Fixed today's lessons on the homepage misbehaving in developer mode.</li>
       <li>Reduced overlap between BetterSEQTA subject averages and SEQTA's built-in averages UI.</li>
       <li>Updated outdated in-app links and update some under the hood code (Vite 8).</li>
-
+      <li>Added a notifications panel animation to work like settings.</li>
+      <li>Fix timetable edit plugin not working correctly.</li>
       <h1>3.5.3 - Adaptive theme updates</h1>
       <li>Fixed adaptive theming on current-year course and assessment pages.</li>
 
@@ -364,5 +367,7 @@ export function OpenWhatsNewPopup() {
   openPopup({
     header,
     content: [imageContainer, text, footer],
+    afterClose: onDismissed,
+    clearJustUpdated: true,
   });
 }

src/seqta/utils/Openers/PopupManager.ts

@@ -4,6 +4,13 @@ import { animate as motionAnimate, stagger } from "motion";
 type AnimationTarget = string | Element | Element[] | NodeList | null;
 
 let isClosing = false;
+let pendingAfterClose: (() => void) | undefined;
+
+function invokeAfterClose() {
+  const fn = pendingAfterClose;
+  pendingAfterClose = undefined;
+  fn?.();
+}
 
 export async function closePopup() {
   if (isClosing) return;
@@ -16,12 +23,14 @@ export async function closePopup() {
 
   if (!background || !popup) {
     isClosing = false;
+    invokeAfterClose();
     return;
   }
 
   if (!settingsState.animations) {
     background.remove();
     isClosing = false;
+    invokeAfterClose();
     return;
   }
 
@@ -33,19 +42,28 @@ export async function closePopup() {
 
   background.remove();
   isClosing = false;
+  invokeAfterClose();
 }
 
 interface OpenPopupOptions {
   header?: Node | null;
   content?: (Node | null | undefined)[];
   animateSelector?: AnimationTarget;
+  /** Called once after this popup is fully closed (including skip-animation path). */
+  afterClose?: () => void;
+  /** When true, clears the post-update flag when this popup opens (What's New only). */
+  clearJustUpdated?: boolean;
 }
 
 export function openPopup({
   header,
   content = [],
   animateSelector = ".whatsnewTextContainer *",
+  afterClose,
+  clearJustUpdated = false,
 }: OpenPopupOptions = {}) {
+  pendingAfterClose = afterClose;
+
   const background = document.createElement("div");
   background.id = "whatsnewbk";
   background.classList.add("whatsnewBackground");
@@ -88,7 +106,9 @@ export function openPopup({
     }
   }
 
-  delete settingsState.justupdated;
+  if (clearJustUpdated) {
+    delete settingsState.justupdated;
+  }
 
   background.addEventListener("click", (event) => {
     if (event.target === background) void closePopup();

src/seqta/utils/Openers/StartupPopupQueue.ts

@@ -0,0 +1,32 @@
+import { settingsState } from "../listeners/SettingsState";
+import { OpenWhatsNewPopup } from "./OpenWhatsNewPopup";
+import {
+  shouldShowEngageParentsAnnouncement,
+  showEngageParentsToast,
+} from "./OpenEngageParentsAnnouncement";
+
+type QueueStep = (goNext: () => void) => void;
+
+/**
+ * Runs startup modals in order: What's New (if the extension just updated),
+ * then shows the SEQTA Engage toast (once, non-blocking).
+ */
+export function runStartupPopupQueue() {
+  const steps: QueueStep[] = [];
+
+  if (settingsState.justupdated) {
+    steps.push((goNext) => OpenWhatsNewPopup(goNext));
+  }
+
+  function runNext() {
+    const step = steps.shift();
+    if (step) step(runNext);
+    else {
+      if (shouldShowEngageParentsAnnouncement()) {
+        showEngageParentsToast();
+      }
+    }
+  }
+
+  runNext();
+}

src/seqta/utils/Openers/attachPopupMediaFullscreen.ts

@@ -0,0 +1,158 @@
+/**
+ * Makes popup hero images/videos open a padded overlay (not browser fullscreen) on click.
+ * Escape or backdrop click dismisses it. Clicks use stopPropagation so the
+ * parent SEQTA popup does not close.
+ */
+
+import { settingsState } from "../listeners/SettingsState";
+
+const FULLSCREENABLE_CLASS = "popup-media-fullscreenable";
+const OVERLAY_VISIBLE_CLASS = "bsplus-popup-media-overlay-backdrop--visible";
+const OVERLAY_ANIM_MS = 280;
+
+function isImageOrVideo(el: Element): el is HTMLImageElement | HTMLVideoElement {
+  return el instanceof HTMLImageElement || el instanceof HTMLVideoElement;
+}
+
+export function attachPopupMediaFullscreen(el: HTMLImageElement | HTMLVideoElement) {
+  el.classList.add(FULLSCREENABLE_CLASS);
+  el.setAttribute("tabindex", "0");
+  el.setAttribute("role", "button");
+  el.setAttribute("aria-label", "View larger");
+  el.title = "Click to view larger";
+
+  const open = (e: Event) => {
+    e.preventDefault();
+    e.stopPropagation();
+    openMediaOverlayViewer(el);
+  };
+
+  el.addEventListener("click", open);
+  el.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      open(e);
+    }
+  });
+}
+
+function openMediaOverlayViewer(source: HTMLImageElement | HTMLVideoElement) {
+  const backdrop = document.createElement("div");
+  backdrop.id = "bsplus-popup-media-overlay";
+  backdrop.className = "bsplus-popup-media-overlay-backdrop";
+
+  const inner = document.createElement("div");
+  inner.className = "bsplus-popup-media-overlay-inner";
+
+  const slot = document.createElement("div");
+  slot.className = "bsplus-popup-media-overlay-slot";
+
+  let media: HTMLImageElement | HTMLVideoElement;
+  if (source instanceof HTMLVideoElement) {
+    const v = source;
+    const nv = document.createElement("video");
+    nv.classList.add("bsplus-popup-media-overlay-media");
+    nv.controls = true;
+    nv.playsInline = true;
+    nv.loop = v.loop;
+    nv.muted = v.muted;
+    nv.volume = v.volume;
+    for (const s of v.querySelectorAll("source")) {
+      const ns = document.createElement("source");
+      ns.src = (s as HTMLSourceElement).src;
+      const t = (s as HTMLSourceElement).type;
+      if (t) ns.type = t;
+      nv.appendChild(ns);
+    }
+    nv.addEventListener(
+      "loadeddata",
+      () => {
+        try {
+          nv.currentTime = v.currentTime;
+        } catch {
+          /* ignore */
+        }
+        void nv.play().catch(() => {});
+      },
+      { once: true },
+    );
+    v.pause();
+    nv.load();
+    media = nv;
+  } else {
+    const img = document.createElement("img");
+    img.classList.add("bsplus-popup-media-overlay-media");
+    img.src = source.currentSrc || source.src;
+    img.alt = source.alt || "";
+    media = img;
+  }
+
+  media.addEventListener("click", (e) => e.stopPropagation());
+
+  slot.appendChild(media);
+  inner.append(slot);
+  backdrop.appendChild(inner);
+  document.body.append(backdrop);
+
+  if (!settingsState.animations) {
+    backdrop.classList.add("bsplus-popup-media-overlay--instant");
+    backdrop.classList.add(OVERLAY_VISIBLE_CLASS);
+  } else {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        backdrop.classList.add(OVERLAY_VISIBLE_CLASS);
+      });
+    });
+  }
+
+  inner.addEventListener("click", (e) => e.stopPropagation());
+
+  let done = false;
+  const removeOverlay = () => {
+    if (source instanceof HTMLVideoElement && media instanceof HTMLVideoElement) {
+      try {
+        source.currentTime = media.currentTime;
+      } catch {
+        /* ignore */
+      }
+      void source.play().catch(() => {});
+    }
+    backdrop.remove();
+  };
+
+  const close = () => {
+    if (done) return;
+    done = true;
+    document.removeEventListener("keydown", onDocKey, true);
+
+    if (!settingsState.animations) {
+      removeOverlay();
+      return;
+    }
+
+    backdrop.classList.remove(OVERLAY_VISIBLE_CLASS);
+    window.setTimeout(removeOverlay, OVERLAY_ANIM_MS);
+  };
+
+  const onDocKey = (ev: KeyboardEvent) => {
+    if (ev.key === "Escape") {
+      ev.stopPropagation();
+      close();
+    }
+  };
+
+  document.addEventListener("keydown", onDocKey, true);
+
+  backdrop.addEventListener("click", () => {
+    close();
+  });
+}
+
+export function attachPopupMediaFullscreenIfPresent(
+  root: ParentNode,
+  selector: string,
+) {
+  const el = root.querySelector(selector);
+  if (el && isImageOrVideo(el)) {
+    attachPopupMediaFullscreen(el);
+  }
+}

src/seqta/utils/attachNotificationsPanelAnimation.ts

@@ -0,0 +1,128 @@
+import { animate } from "motion";
+import { settingsState } from "@/seqta/utils/listeners/SettingsState";
+import { waitForElm } from "@/seqta/utils/waitForElm";
+
+/**
+ * Finds the SEQTA notifications dropdown panel (the list container next to the bell).
+ */
+function findNotificationPanel(): HTMLElement | null {
+  const wrapper = document.querySelector(".connectedNotificationsWrapper");
+  if (!wrapper) return null;
+
+  const flat = wrapper.querySelector<HTMLElement>(":scope > div > button + div");
+  if (flat) return flat;
+
+  const notifBlock = wrapper.querySelector("[class*='notifications__notifications___']");
+  if (notifBlock?.nextElementSibling instanceof HTMLElement) {
+    return notifBlock.nextElementSibling;
+  }
+
+  const list = wrapper.querySelector<HTMLElement>("[class*='notifications__list___']");
+  if (list) return list;
+
+  return null;
+}
+
+function isPanelVisible(el: HTMLElement): boolean {
+  return (
+    el.getClientRects().length > 0 && getComputedStyle(el).visibility !== "hidden"
+  );
+}
+
+let lastVisible = false;
+/** Invalidates in-flight open animations when the panel closes or reopens. */
+let motionGeneration = 0;
+
+function runOpenAnimation(panel: HTMLElement) {
+  const myGen = ++motionGeneration;
+  panel.classList.add("bsplus-notifications-panel");
+
+  if (!settingsState.animations) {
+    panel.style.opacity = "1";
+    panel.style.transform = "scale(1)";
+    return;
+  }
+
+  panel.style.opacity = "0";
+  panel.style.transform = "scale(0)";
+
+  requestAnimationFrame(() => {
+    if (myGen !== motionGeneration) return;
+    animate(0, 1, {
+      onUpdate: (progress) => {
+        panel.style.opacity = String(progress);
+        panel.style.transform = `scale(${progress})`;
+      },
+      type: "spring",
+      stiffness: 280,
+      damping: 20,
+    });
+  });
+}
+
+function clearPanelMotionStyles(panel: HTMLElement) {
+  motionGeneration++;
+  panel.style.opacity = "";
+  panel.style.transform = "";
+}
+
+/**
+ * Spring open / fade close for the native SEQTA notifications dropdown, matching ExtensionPopup.
+ */
+export function attachNotificationsPanelAnimation() {
+  void setupNotificationsPanelAnimation();
+}
+
+async function setupNotificationsPanelAnimation() {
+  try {
+    await waitForElm(".connectedNotificationsWrapper", true, 100, 60);
+  } catch {
+    return;
+  }
+
+  const wrapper = document.querySelector(".connectedNotificationsWrapper");
+  if (!wrapper) return;
+
+  const sync = () => {
+    const panel = findNotificationPanel();
+    // When SEQTA removes the dropdown from the DOM on close, we must reset
+    // lastVisible — otherwise the next open still looks "already visible" and skips animation.
+    if (!panel) {
+      if (lastVisible) {
+        lastVisible = false;
+        motionGeneration++;
+      }
+      return;
+    }
+
+    const visible = isPanelVisible(panel);
+    if (visible === lastVisible) return;
+
+    if (visible) {
+      runOpenAnimation(panel);
+    } else {
+      clearPanelMotionStyles(panel);
+    }
+    lastVisible = visible;
+  };
+
+  const observer = new MutationObserver(() => {
+    sync();
+  });
+  observer.observe(wrapper, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: ["style", "class"],
+  });
+
+  document.addEventListener(
+    "click",
+    () => {
+      requestAnimationFrame(() => requestAnimationFrame(sync));
+    },
+    true,
+  );
+
+  sync();
+}

src/seqta/utils/cloudSettingsSync.ts

@@ -36,7 +36,10 @@ export const SENSITIVE_DEVICE_STORAGE_KEYS_EXACT = [
 /** e.g. any future `plugin.global-search.storage.*` keys in chrome.storage */
 export const SENSITIVE_DEVICE_STORAGE_KEY_PREFIXES = ["plugin.global-search.storage."] as const;
 
-const CLIENT_ONLY_CLOUD_KEYS_EXACT = [BSPLUS_CLOUD_KNOWN_REMOTE_UPDATED_AT_KEY] as const;
+const CLIENT_ONLY_CLOUD_KEYS_EXACT = [
+  BSPLUS_CLOUD_KNOWN_REMOTE_UPDATED_AT_KEY,
+  "bsplus_lastCloudPoll",
+] as const;
 
 /** After restoring from cloud, keep local session so the user stays signed in. */
 const AUTH_KEYS_TO_PRESERVE = [
@@ -102,11 +105,12 @@ export function buildUploadPayload(all: Record<string, unknown>): {
   schemaVersion: number;
   data: Record<string, unknown>;
 } {
-  const data: Record<string, unknown> = {};
+  const filtered: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(all)) {
     if (shouldOmitKeyFromCloudPayload(k)) continue;
-    data[k] = v;
+    filtered[k] = v;
   }
+  const data = migrateLegacyToPluginSettings(filtered);
   return { schemaVersion: CLOUD_SETTINGS_SYNC_SCHEMA_VERSION, data };
 }
 
@@ -124,8 +128,77 @@ export async function setKnownRemoteUpdatedAt(iso: string | undefined): Promise<
 }
 
 /**
- * Replace local extension storage with the downloaded snapshot, except auth keys
- * and device-only sensitive caches, which are preserved from the current device.
+ * Migrate legacy storage keys to plugin settings format.
+ * Only applies migrations for keys present in the data; does not overwrite
+ * existing plugin settings if the legacy key is absent.
+ */
+function migrateLegacyToPluginSettings(data: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...data };
+
+  function ensurePluginSettings(pluginId: string): Record<string, unknown> {
+    const key = `plugin.${pluginId}.settings`;
+    if (!result[key] || typeof result[key] !== "object") {
+      result[key] = {};
+    }
+    return result[key] as Record<string, unknown>;
+  }
+
+  // animatedbk -> plugin.animated-background.settings.enabled
+  if ("animatedbk" in result) {
+    const settings = ensurePluginSettings("animated-background");
+    if (settings.enabled === undefined) {
+      settings.enabled = !!result.animatedbk;
+    }
+    delete result.animatedbk;
+  }
+
+  // bksliderinput -> plugin.animated-background.settings.speed
+  // Legacy: string "0"-"100", New: float 0.1-2.0
+  if ("bksliderinput" in result) {
+    const settings = ensurePluginSettings("animated-background");
+    if (settings.speed === undefined) {
+      const legacy = parseFloat(String(result.bksliderinput));
+      if (!isNaN(legacy)) {
+        settings.speed = Math.round((0.1 + (legacy / 100) * 1.9) * 100) / 100;
+      }
+    }
+    delete result.bksliderinput;
+  }
+
+  // assessmentsAverage -> plugin.assessments-average.settings.enabled
+  if ("assessmentsAverage" in result) {
+    const settings = ensurePluginSettings("assessments-average");
+    if (settings.enabled === undefined) {
+      settings.enabled = !!result.assessmentsAverage;
+    }
+    delete result.assessmentsAverage;
+  }
+
+  // lettergrade -> plugin.assessments-average.settings.lettergrade
+  if ("lettergrade" in result) {
+    const settings = ensurePluginSettings("assessments-average");
+    if (settings.lettergrade === undefined) {
+      settings.lettergrade = !!result.lettergrade;
+    }
+    delete result.lettergrade;
+  }
+
+  // notificationCollector -> plugin.notificationCollector.settings.enabled
+  if ("notificationCollector" in result && typeof result.notificationCollector === "boolean") {
+    const settings = ensurePluginSettings("notificationCollector");
+    if (settings.enabled === undefined) {
+      settings.enabled = result.notificationCollector;
+    }
+    delete result.notificationCollector;
+  }
+
+  return result;
+}
+
+/**
+ * Apply the downloaded cloud snapshot by setting each key individually,
+ * preserving auth keys and device-only sensitive caches.
+ * Legacy keys are automatically migrated to plugin settings format.
  */
 export async function applyDownloadedEnvelope(envelope: unknown): Promise<void> {
   let remoteFlat: Record<string, unknown>;
@@ -145,10 +218,7 @@ export async function applyDownloadedEnvelope(envelope: unknown): Promise<void>
     throw new Error("Invalid cloud settings payload");
   }
 
-  const local = await browser.storage.local.get();
-  const preserved = collectLocalKeysToPreserve(local);
-  const remoteSanitized = stripExcludedKeysFromRemoteData(remoteFlat);
-
-  await browser.storage.local.clear();
-  await browser.storage.local.set({ ...remoteSanitized, ...preserved });
+  const migrated = migrateLegacyToPluginSettings(remoteFlat);
+  const remoteSanitized = stripExcludedKeysFromRemoteData(migrated);
+  await browser.storage.local.set(remoteSanitized);
 }