feat: theme flavours for theme varients

docs/CLOUD_SETTINGS_SYNC_SERVER.md

@@ -35,13 +35,16 @@ Upserts the caller’s settings backup.
 ```json
 {
   "schemaVersion": 1,
+  "themeId": "uuid-string-or-empty",
   "data": {
-    "...": "flat key-value map mirroring extension storage (see Payload shape)"
+    "...": "flat key-value map mirroring extension storage (see Payload shape)",
+    "selectedTheme": "uuid-or-empty-string"
   }
 }
 ```
 
 - **`schemaVersion`**: integer. The extension currently sends `1`. The server may reject unknown major versions or store it for future migrations.
+- **`themeId`**: optional but recommended duplicate of **`data.selectedTheme`**. Should be the UUID of the **installed** BetterSEQTA store theme (`selectedTheme`). This may be a normal theme id **or** a **flavour (slave) variant** id from themes with **`flavours[]`** — the extension uses it after restore to prefetch `theme.json` when missing locally (same **`GET …/themes/{id}/download`** as the store UI). Persist and return **`themeId`** in sync with **`data.selectedTheme`**.
 - **`data`**: object whose keys are storage keys (strings) and values are JSON-serializable values (same types as stored in `chrome.storage.local`).
 
 **Success response:** HTTP `200` (or `201` if you prefer create semantics). Example:
@@ -67,15 +70,19 @@ Returns the caller’s latest settings backup.
 ```json
 {
   "schemaVersion": 1,
+  "themeId": "uuid-string-or-empty",
   "data": { },
   "updated_at": "2026-04-07T12:00:00.000Z"
 }
 ```
 
 - **`data`**: required for restore; must be the same shape as accepted in `PUT` (flat map of storage keys).
+- **`themeId`**: optional; if present must match **`data.selectedTheme`** (see `PUT`).
 - **`schemaVersion`**: optional but recommended; should match what was stored.
 - **`updated_at`**: optional; included for UX if the client shows “last backup” time.
 
+The extension resolves **`themeId`** (if non-empty), else **`data.selectedTheme`,** to [`resolveThemeIdForPostSyncDownload`](../src/seqta/utils/cloudSettingsSync.ts) after downloading the envelope — used only to reinstall theme assets from **`betterseqta.org`** when IndexedDB lacks that id (see **BetterSEQTA Cloud** flavour note in **[THEME_STORE_FLAVOURS_API](./THEME_STORE_FLAVOURS_API.md)** section “Cloud settings sync compatibility”).
+
 **No backup yet:** HTTP **`404`**. The extension treats this as “nothing in the cloud” and shows an error to the user.
 
 **Error responses:** `401` if the token is invalid, etc.
@@ -128,6 +135,6 @@ This uses standard **WebExtension** APIs (`browser.alarms`, `runtime` messages,
 
 ## Client reference (extension)
 
-- Upload / dev export: `buildUploadPayload` / `getSnapshotForUpload` in `src/seqta/utils/cloudSettingsSync.ts` (strips OAuth-related keys, sensitive device keys, and **`bsplus_cloud_settings_known_remote_updated_at`**).
+- Upload / dev export: `buildUploadPayload` / `getSnapshotForUpload` in `src/seqta/utils/cloudSettingsSync.ts` (strips OAuth-related keys, sensitive device keys, **`bsplus_pending_theme_ensure_after_cloud`**, and **`bsplus_cloud_settings_known_remote_updated_at`** — includes **`themeId`** aligned with **`selectedTheme`**).
-- Download: `applyDownloadedEnvelope` after `GET`; local auth keys, sensitive device keys, and the client-only watermark key are merged back after `chrome.storage.local.clear()`.
+- Download: resolve id via **`resolveThemeIdForPostSyncDownload`** → **`applyDownloadedEnvelope`** after `GET` → prefetch theme blobs in page context if needed (**`prepareThemeAfterCloudSync`** in **`ThemeManager`**) → reload SEQTA tabs; local auth keys, sensitive device keys, client-only watermark, and **`bsplus_pending_theme_ensure_after_cloud`** semantics preserved as documented above.
 - Auto sync (summary, debounced upload, alarms): `src/background/cloudSettingsAutoSync.ts`; content script triggers a poll on each verified SEQTA Learn/Engage page load (top frame) via `cloudSettingsPoll`.

src/interface/components/store/CoverSwiper.svelte

@@ -1,10 +1,13 @@
 <script lang="ts">
   import { fade } from 'svelte/transition';
-  import type { Theme } from '@/interface/types/Theme';
+  import type { ThemeCoverSlide } from '@/interface/types/Theme';
   import emblaCarouselSvelte from 'embla-carousel-svelte';
   import Autoplay from 'embla-carousel-autoplay';
 
-  let { coverThemes, setDisplayTheme } = $props<{ coverThemes: Theme[], setDisplayTheme: (theme: Theme) => void }>();
+  let { slides, setDisplayTheme } = $props<{
+    slides: ThemeCoverSlide[];
+    setDisplayTheme: (theme: import('@/interface/types/Theme').Theme) => void;
+  }>();
   let emblaApi = $state();
 
   const options = { loop: true };
@@ -12,8 +15,8 @@
     Autoplay({
       delay: 5000,
       stopOnInteraction: false,
-      stopOnMouseEnter: true
+      stopOnMouseEnter: true,
-    })
+    }),
   ];
 
   function onInit(event: CustomEvent) {
@@ -26,7 +29,7 @@
   const slideNext = () => emblaApi?.scrollNext();
 </script>
 
-{#if coverThemes.length > 0}
+{#if slides.length > 0}
   <div class="relative w-full overflow-clip rounded-xl transition-opacity" transition:fade>
     <div
       class="w-full aspect-[5/1] max-h-[500px]"
@@ -34,49 +37,69 @@
       onemblaInit={onInit}
     >
       <div class="flex">
-        {#each coverThemes as theme}
+        {#each slides as slide (slide.imageUrl + slide.title + (slide.subtitle ?? ''))}
           <div
             class="relative flex-[0_0_100%] cursor-pointer rounded-xl overflow-clip"
             role="button"
             tabindex="0"
-            onkeydown={(e) => { if (e.key === 'Enter') setDisplayTheme(theme) }}
+            onkeydown={(e) => {
-            onclick={() => setDisplayTheme(theme)}
+              if (e.key === 'Enter') setDisplayTheme(slide.openTheme);
+            }}
+            onclick={() => setDisplayTheme(slide.openTheme)}
           >
-            <img src={theme.marqueeImage || theme.coverImage} alt="Theme Preview" class="object-cover w-full h-full" />
+            <img src={slide.imageUrl} alt="" class="object-cover w-full h-full" />
-            {#if theme.featured === true}
+            {#if slide.badgeFeatured === true}
               <div class="absolute top-4 left-4 z-[2] pointer-events-none">
                 <span
                   class="inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-xs font-semibold bg-amber-100 text-amber-900 dark:bg-amber-950 dark:text-amber-100 shadow-sm"
                   aria-label="Featured theme"
                 >
                   <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="w-3.5 h-3.5">
-                    <path fill-rule="evenodd" d="M10.788 3.21c.448-1.077 1.976-1.077 2.424 0l2.082 5.006 5.404.434c1.164.093 1.636 1.545.749 2.305l-4.117 3.527 1.257 5.273c.271 1.136-.964 2.033-1.96 1.425L12 18.354 7.373 21.18c-.996.608-2.231-.29-1.96-1.425l1.257-5.273-4.117-3.527c-.887-.76-.415-2.212.749-2.305l5.404-.434 2.082-5.005Z" clip-rule="evenodd" />
+                    <path
+                      fill-rule="evenodd"
+                      d="M10.788 3.21c.448-1.077 1.976-1.077 2.424 0l2.082 5.006 5.404.434c1.164.093 1.636 1.545.749 2.305l-4.117 3.527 1.257 5.273c.271 1.136-.964 2.033-1.96 1.425L12 18.354 7.373 21.18c-.996.608-2.231-.29-1.96-1.425l1.257-5.273-4.117-3.527c-.887-.76-.415-2.212.749-2.305l5.404-.434 2.082-5.005Z"
+                      clip-rule="evenodd"
+                    />
                   </svg>
                   Featured
                 </span>
               </div>
             {/if}
-            <div class='absolute bottom-0 left-0 p-8 z-[1]'>
+            <div class="absolute bottom-0 left-0 p-8 z-[1]">
-              <h2 class='text-4xl font-bold text-white'>{theme.name}</h2>
+              <h2 class="text-4xl font-bold text-white">{slide.title}</h2>
-              {#if theme.author}
+              {#if slide.subtitle}
-                <p class="text-sm text-white/90 mt-1 mb-1 line-clamp-1">By {theme.author}</p>
+                <p class="text-lg font-medium text-white/95 mt-1 line-clamp-2">{slide.subtitle}</p>
+              {/if}
+              {#if slide.openTheme.author && !slide.subtitle}
+                <p class="text-sm text-white/90 mt-1 mb-1 line-clamp-1">By {slide.openTheme.author}</p>
+              {/if}
+              {#if slide.openTheme.description && !slide.subtitle}
+                <p class="text-lg text-white line-clamp-3">{slide.openTheme.description}</p>
               {/if}
-              <p class='text-lg text-white'>{theme.description}</p>
             </div>
-            <div class='absolute bottom-0 left-0 w-full h-1/2 to-transparent bg-linear-to-t from-black/80'></div>
+            <div class="absolute bottom-0 left-0 w-full h-1/2 to-transparent bg-linear-to-t from-black/80"></div>
           </div>
         {/each}
       </div>
     </div>
 
-    <!-- Navigation buttons -->
+    <div class="flex absolute right-2 bottom-2 z-10 gap-2">
-    <div class='flex absolute right-2 bottom-2 z-10 gap-2'>
+      <button
-      <button aria-label="Previous" onclick={slidePrev} class='flex justify-center items-center w-8 h-8 text-white rounded-full bg-black/50 dark:bg-zinc-800'>
+        aria-label="Previous"
+        onclick={slidePrev}
+        type="button"
+        class="flex justify-center items-center w-8 h-8 text-white rounded-full bg-black/50 dark:bg-zinc-800 transition-all duration-200"
+      >
         <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width={1.5} stroke="currentColor" class="w-6 h-6">
           <path stroke-linecap="round" stroke-linejoin="round" d="m15.75 19.5-7.5-7.5 7.5-7.5" />
         </svg>
       </button>
-      <button aria-label="Next" onclick={slideNext} class='flex justify-center items-center w-8 h-8 text-white rounded-full bg-black/50 dark:bg-zinc-800'>
+      <button
+        aria-label="Next"
+        onclick={slideNext}
+        type="button"
+        class="flex justify-center items-center w-8 h-8 text-white rounded-full bg-black/50 dark:bg-zinc-800 transition-all duration-200"
+      >
         <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width={1.5} stroke="currentColor" class="w-6 h-6">
           <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
         </svg>

src/interface/components/store/ThemeCard.svelte

@@ -1,14 +1,54 @@
 <script lang="ts">
   import type { Theme } from '@/interface/types/Theme'
+  import {
+    masterGridDisplayDownloadCount,
+    gridCardPreviewImageUrls,
+  } from '@/interface/utils/themeStoreFlavours'
   import { fade } from 'svelte/transition';
   import { onMount } from 'svelte';
-  let { theme, onClick, toggleFavorite, isLoggedIn, onRequestSignIn } = $props<{
+  import emblaCarouselSvelte from 'embla-carousel-svelte';
+  import Autoplay from 'embla-carousel-autoplay';
+  let { theme, onClick, toggleFavorite, isLoggedIn, onRequestSignIn, allStoreThemeRows } = $props<{
     theme: Theme;
     onClick: () => void;
     toggleFavorite: (theme: Theme) => void;
     isLoggedIn: boolean;
     onRequestSignIn?: () => void;
+    /** Raw API themes (includes hidden slaves) for aggregated master download totals */
+    allStoreThemeRows?: Theme[];
   }>();
+
+  const displayDownloadCount = $derived(
+    allStoreThemeRows != null
+      ? masterGridDisplayDownloadCount(theme, allStoreThemeRows)
+      : (theme.download_count ?? 0),
+  );
+
+  const gridRotatorUrls = $derived(gridCardPreviewImageUrls(theme, allStoreThemeRows));
+
+  /** Mirrors CoverSwiper (featured bar): horizontal slides + autoplay */
+  function prefersReducedMotion(): boolean {
+    return typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  }
+
+  /** Read once synchronously where `window` exists so reduced-motion doesn’t briefly mount carousel */
+  let allowSlideAutoplay = $state(!prefersReducedMotion());
+
+  const gridEmblaKey = $derived(gridRotatorUrls.join('|'));
+
+  const gridEmblaOptions = $derived({ loop: gridRotatorUrls.length > 1 });
+
+  const gridEmblaPlugins = $derived.by(() => {
+    if (!allowSlideAutoplay || gridRotatorUrls.length <= 1) return [];
+    return [
+      Autoplay({
+        delay: 2000,
+        stopOnInteraction: false,
+        stopOnMouseEnter: true,
+      }),
+    ];
+  });
+
   let menuOpen = $state(false);
   let menuRef: HTMLDivElement;
 
@@ -111,7 +151,7 @@
           <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-3.5 h-3.5">
             <path stroke-linecap="round" stroke-linejoin="round" d="M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5M16.5 12L12 16.5m0 0L7.5 12m4.5 4.5V3" />
           </svg>
-          {(theme.download_count ?? 0).toLocaleString()}
+          {displayDownloadCount.toLocaleString()}
         </span>
         <span class="flex items-center gap-1">
           <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill={theme.is_favorited ? 'currentColor' : 'none'} stroke="currentColor" stroke-width="1.5" class="w-3.5 h-3.5">
@@ -122,8 +162,40 @@
       </div>
     </div>
     <div class='absolute bottom-0 z-0 w-full h-3/4 bg-linear-to-t to-transparent from-black/80'></div>
-    <div class='w-full'>
+    {#if gridRotatorUrls.length === 0}
-      <img src={theme.marqueeImage || theme.coverImage} alt="Theme Preview" class="object-cover w-full h-48 rounded-md" />
+      <div class="relative w-full h-48 overflow-hidden rounded-md bg-zinc-200 dark:bg-zinc-700" aria-hidden="true"></div>
+    {:else if !allowSlideAutoplay || gridRotatorUrls.length === 1}
+      <div class="relative w-full h-48 overflow-hidden rounded-md">
+        <img
+          src={gridRotatorUrls[0] ?? theme.marqueeImage ?? theme.coverImage}
+          alt=""
+          class="object-cover w-full h-full"
+          draggable="false"
+        />
+      </div>
+    {:else}
+      {#key gridEmblaKey}
+        <div
+          class="relative w-full h-48 overflow-hidden rounded-md"
+          use:emblaCarouselSvelte={{
+            options: gridEmblaOptions,
+            plugins: gridEmblaPlugins,
+          }}
+        >
+          <div class="flex h-full">
+            {#each gridRotatorUrls as url (url)}
+              <div class="relative flex-[0_0_100%] min-w-0 h-full shrink-0">
+                <img
+                  src={url}
+                  alt=""
+                  class="object-cover w-full h-full select-none"
+                  draggable="false"
+                />
+              </div>
+            {/each}
           </div>
         </div>
+      {/key}
+    {/if}
+  </div>
 </div>

src/interface/components/store/ThemeGrid.svelte

@@ -2,13 +2,23 @@
   import type { Theme } from '@/interface/types/Theme'
   import ThemeCard from './ThemeCard.svelte';
 
-  let { themes, searchTerm, setDisplayTheme, toggleFavorite, isLoggedIn, onRequestSignIn } = $props<{
+  let {
+    themes,
+    searchTerm,
+    setDisplayTheme,
+    toggleFavorite,
+    isLoggedIn,
+    onRequestSignIn,
+    allStoreThemeRows,
+  } = $props<{
     themes: Theme[];
     searchTerm: string;
     setDisplayTheme: (theme: Theme) => void;
     toggleFavorite: (theme: Theme) => void;
     isLoggedIn: boolean;
     onRequestSignIn?: () => void;
+    /** Raw API list (includes `slave` rows) for master download aggregation */
+    allStoreThemeRows?: Theme[];
   }>();
   
   let filteredThemes = $derived(themes.filter((theme: Theme) =>
@@ -25,6 +35,7 @@
         {toggleFavorite}
         {isLoggedIn}
         {onRequestSignIn}
+        {allStoreThemeRows}
       />
     {/each}
   

src/interface/pages/store.svelte

@@ -7,6 +7,7 @@
   import SkeletonLoader from '../components/SkeletonLoader.svelte';
   import { settingsState } from '@/seqta/utils/listeners/SettingsState'
   import type { Theme } from '../types/Theme'
+  import { visibleStoreThemes, buildCoverSlidesForThemes } from '@/interface/utils/themeStoreFlavours'
   import browser from 'webextension-polyfill'
   import ThemeModal from '../components/store/ThemeModal.svelte'
   import Header from '../components/store/Header.svelte'
@@ -26,7 +27,12 @@
   // State variables
   let searchTerm = $state('');
   let themes = $state<Theme[]>([]);
-  let coverThemes = $state<Theme[]>([]);
+
+  /** Grid/search/cover: hides flat-listed slaves when API sends them */
+  let listThemes = $derived(visibleStoreThemes(themes));
+
+  /** Cover marquee slides (master + flavour imagery for top masters) */
+  let coverSlides = $derived(buildCoverSlidesForThemes(listThemes.slice(0, 3)));
   let loading = $state(true);
   let darkMode = $state(false);
   let displayTheme = $state<Theme | null>(null);
@@ -108,7 +114,6 @@
         throw new Error(data?.error || 'Failed to fetch themes');
       }
       themes = [...data.data.themes].sort(compareStoreThemes);
-      coverThemes = themes.slice(0, 3);
 
       loading = false;
     } catch (err) {
@@ -128,13 +133,36 @@
 
   // Filter themes (list is already featured-first, then newest; filter preserves order)
   let filteredThemes = $derived(
-    themes.filter(
+    listThemes.filter(
       (theme) =>
         theme.name.toLowerCase().includes(searchTerm.toLowerCase()) ||
         theme.description.toLowerCase().includes(searchTerm.toLowerCase()),
     ),
   );
 
+  async function installThemeFromStore(themeId: string, meta: Theme) {
+    const fullRow = themes.find((x) => x.id === themeId);
+    if (fullRow) {
+      await themeManager.downloadTheme(fullRow);
+    } else {
+      const flavour = meta.flavours?.find((f) => f.id === themeId);
+      await themeManager.downloadTheme({
+        id: themeId,
+        name: flavour?.name ?? meta.name,
+      } as Theme);
+    }
+    await themeManager.setTheme(themeId);
+    themeUpdates.triggerUpdate();
+    await fetchCurrentThemes();
+    void browser.runtime.sendMessage({ type: 'cloudSettingsRequestDebouncedUpload' }).catch(() => {});
+  }
+
+  async function removeThemeFromStore(themeId: string) {
+    await themeManager.deleteTheme(themeId);
+    themeUpdates.triggerUpdate();
+    await fetchCurrentThemes();
+  }
+
   $effect(() => {
     loadBackground();
     selectedBackground
@@ -172,12 +200,13 @@
         <!-- Themes Tab Content -->
         {#if activeTab === 'themes'}
           {#if searchTerm === ''}
-            <CoverSwiper {coverThemes} {setDisplayTheme} />
+            <CoverSwiper slides={coverSlides} {setDisplayTheme} />
           {/if}
     
           <!-- ThemeGrid to display filtered themes -->
           <ThemeGrid
             themes={filteredThemes}
+            allStoreThemeRows={themes}
             {searchTerm}
             {setDisplayTheme}
             {toggleFavorite}
@@ -188,29 +217,20 @@
           {#if displayTheme}
             <ThemeModal
               currentThemes={currentThemes}
-              allThemes={themes}
+              allThemes={listThemes}
+              allStoreThemeRows={themes}
               theme={displayTheme}
               {displayTheme}
               {setDisplayTheme}
               {toggleFavorite}
               isLoggedIn={cloudLoggedIn}
               onRequestSignIn={() => (showSignInOverlay = true)}
-              onInstall={async () => {
+              onInstall={async (themeId: string) => {
-                if (displayTheme) {
+                if (displayTheme) await installThemeFromStore(themeId, displayTheme);
-                  await themeManager.downloadTheme(displayTheme);
-                  await themeManager.setTheme(displayTheme.id);
-                  themeUpdates.triggerUpdate();
-                  await fetchCurrentThemes();
-                  void browser.runtime.sendMessage({ type: 'cloudSettingsRequestDebouncedUpload' }).catch(() => {});
-                }
               }}
-              onRemove={async () => {
+              onRemove={async (themeId: string) => {
-                if (displayTheme?.id) {
+                console.debug('deleting theme', themeId);
-                  console.debug('deleting theme', displayTheme.id);
+                await removeThemeFromStore(themeId);
-                  await themeManager.deleteTheme(displayTheme.id);
-                  themeUpdates.triggerUpdate();
-                  await fetchCurrentThemes();
-                }
               }}
             />
           {/if}

src/interface/types/Theme.ts

@@ -1,3 +1,17 @@
+export type ThemeRole = "standard" | "master" | "slave";
+
+/** List/detail metadata for variants of a master theme (full theme.json fetched at install by id). */
+export type ThemeFlavour = {
+  id: string;
+  name: string;
+  /** Mirrors theme.json accent (e.g. defaultColour); used for install picker buttons */
+  accent_color: string;
+  cover_image: string;
+  marquee_image?: string;
+  /** Per-variant installs when slaves are not returned as flat `theme_role` rows */
+  download_count?: number;
+};
+
 export type Theme = {
   id: string;
   name: string;
@@ -15,4 +29,22 @@ export type Theme = {
   created_at?: number;
   /** Unix seconds — last server update (GET /api/themes). */
   updated_at?: number;
+  /** Omitted / `standard` — show in grid. `slave` hides from grid. `master` can list `flavours`. */
+  theme_role?: ThemeRole;
+  /** Present when `theme_role === "slave"` and API returns a flat list during migration */
+  master_id?: string;
+  /** Variants nested on master rows; installs use flavour `id` */
+  flavours?: ThemeFlavour[];
+};
+
+/** One marquee slide (cover hero or modal carousel). */
+export type ThemeCoverSlide = {
+  imageUrl: string;
+  /** Main line — usually master name */
+  title: string;
+  /** Subline — flavour name when applicable */
+  subtitle?: string;
+  /** Opening the modal uses this theme (always the grid row / master object) */
+  openTheme: Theme;
+  badgeFeatured?: boolean;
 };

src/interface/utils/themeStoreFlavours.ts

@@ -0,0 +1,165 @@
+import type { Theme, ThemeCoverSlide, ThemeFlavour } from "@/interface/types/Theme";
+
+export function isHiddenStoreTheme(theme: Theme): boolean {
+  return theme.theme_role === "slave";
+}
+
+/** Grid and search: omit slave rows (when API sends a flattened list). */
+export function visibleStoreThemes(themes: Theme[]): Theme[] {
+  return themes.filter((t) => !isHiddenStoreTheme(t));
+}
+
+function marqueeOrCoverUrl(t: { marqueeImage?: string; coverImage: string }): string {
+  return t.marqueeImage || t.coverImage;
+}
+
+/**
+ * Builds slides for CoverSwiper: for each top-N master, first master image then each flavour image.
+ */
+export function buildCoverSlidesForThemes(topThemes: Theme[]): ThemeCoverSlide[] {
+  const slides: ThemeCoverSlide[] = [];
+  for (const theme of topThemes) {
+    const flavours = theme.flavours ?? [];
+    if (flavours.length === 0) {
+      slides.push({
+        imageUrl: marqueeOrCoverUrl(theme),
+        title: theme.name,
+        subtitle: theme.author ? `By ${theme.author}` : undefined,
+        openTheme: theme,
+        badgeFeatured: theme.featured === true,
+      });
+      continue;
+    }
+    slides.push({
+      imageUrl: marqueeOrCoverUrl(theme),
+      title: theme.name,
+      subtitle: theme.author ? `By ${theme.author}` : undefined,
+      openTheme: theme,
+      badgeFeatured: theme.featured === true,
+    });
+    for (const f of flavours) {
+      slides.push({
+        imageUrl: f.marquee_image || f.cover_image,
+        title: theme.name,
+        subtitle: f.name,
+        openTheme: theme,
+        badgeFeatured: theme.featured === true,
+      });
+    }
+  }
+  return slides;
+}
+
+export type ModalHeroSlide = { imageUrl: string; caption: string };
+
+/** Preview image for carousel + flavour picker (matches hero slide order after master slide). */
+export function flavourCarouselImageUrl(f: ThemeFlavour): string {
+  const u = (f.marquee_image || f.cover_image || "").trim();
+  return u;
+}
+
+/** Preview image for master variant tile (modal hero slide 0). */
+export function masterCarouselImageUrl(t: Theme): string {
+  return (marqueeOrCoverUrl(t) || "").trim();
+}
+
+/**
+ * Ordered preview URLs for the store grid card rotator: master first, then each variant.
+ * Uses nested `flavours` when present; otherwise flat `slave` rows (same order as modal when possible).
+ */
+export function gridCardPreviewImageUrls(theme: Theme, allStoreRows?: Theme[]): string[] {
+  const urls: string[] = [];
+  const push = (raw: string) => {
+    const u = raw.trim();
+    if (u && !urls.includes(u)) urls.push(u);
+  };
+
+  push(marqueeOrCoverUrl(theme) || "");
+
+  const flavours = theme.flavours ?? [];
+  if (flavours.length > 0) {
+    for (const f of flavours) {
+      push(flavourCarouselImageUrl(f));
+    }
+    return urls.length > 0 ? urls : [(theme.coverImage || "").trim()].filter(Boolean);
+  }
+
+  if (allStoreRows) {
+    const slaves = allStoreRows
+      .filter((t) => t.theme_role === "slave" && t.master_id === theme.id)
+      .sort((a, b) => a.id.localeCompare(b.id));
+    for (const s of slaves) {
+      push((marqueeOrCoverUrl(s) || "").trim());
+    }
+  }
+
+  if (urls.length > 0) return urls;
+  const fallback = (theme.coverImage || "").trim();
+  return fallback ? [fallback] : [];
+}
+
+/**
+ * Downloads shown on the grid card for a master row: master's count plus each slave
+ * (flat `theme_role === "slave"` with `master_id`) and any flavour-only `download_count`
+ * when there is no matching flat slave id (nested-only API shape).
+ */
+export function masterGridDisplayDownloadCount(master: Theme, allStoreRows: Theme[]): number {
+  let total = master.download_count ?? 0;
+  const slaveRows = allStoreRows.filter(
+    (t) => t.theme_role === "slave" && t.master_id === master.id,
+  );
+  const countedIds = new Set(slaveRows.map((r) => r.id));
+  for (const r of slaveRows) {
+    total += r.download_count ?? 0;
+  }
+  for (const f of master.flavours ?? []) {
+    if (countedIds.has(f.id)) continue;
+    total += f.download_count ?? 0;
+  }
+  return total;
+}
+
+/** Modal hero: master first, then each flavour (plan order). */
+export function buildModalHeroSlides(theme: Theme): ModalHeroSlide[] {
+  const slides: ModalHeroSlide[] = [];
+  slides.push({
+    imageUrl: marqueeOrCoverUrl(theme),
+    caption: theme.name,
+  });
+  const flavours = theme.flavours ?? [];
+  for (const f of flavours) {
+    slides.push({
+      imageUrl: f.marquee_image || f.cover_image,
+      caption: `${theme.name} — ${f.name}`,
+    });
+  }
+  return slides;
+}
+
+/**
+ * Relative luminance 0–1 for rgba/rgb/hex-ish strings; fallback 0.5 → white text
+ */
+export function pickContrastingTextColor(backgroundCss: string): "#ffffff" | "#0a0a0a" {
+  const s = backgroundCss.trim();
+  const rgba = s.match(
+    /rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)/i,
+  );
+  if (rgba) {
+    const r = Number(rgba[1]) / 255;
+    const g = Number(rgba[2]) / 255;
+    const b = Number(rgba[3]) / 255;
+    const a = rgba[4] !== undefined ? Number(rgba[4]) : 1;
+    const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    const effective = lum * a + 0.05 * (1 - a);
+    return effective > 0.45 ? "#0a0a0a" : "#ffffff";
+  }
+  const hex = s.match(/^#?([\da-f]{2})([\da-f]{2})([\da-f]{2})$/i);
+  if (hex) {
+    const r = parseInt(hex[1], 16) / 255;
+    const g = parseInt(hex[2], 16) / 255;
+    const b = parseInt(hex[3], 16) / 255;
+    const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    return lum > 0.45 ? "#0a0a0a" : "#ffffff";
+  }
+  return "#ffffff";
+}

src/plugins/built-in/themes/theme-manager.ts

@@ -170,6 +170,8 @@ export class ThemeManager {
   /**
    * After cloud restore, IndexedDB/theme storage is only reachable from page context (not MV3 SW).
    * Background sets BSPLUS_PENDING_THEME_ENSURE_AFTER_CLOUD_KEY; we fetch the store JSON here before setTheme().
+   * The resolved id matches cloud sync **`themeId` / `selectedTheme`**: it may be a standard theme uuid or a
+   * flavour (slave) variant id — **`downloadAndInstallStoreTheme`** is the same code path as the theme store installer.
    */
   public async prepareThemeAfterCloudSync(): Promise<void> {
     try {

src/seqta/utils/Openers/OpenWhatsNewPopup.ts

@@ -35,9 +35,9 @@ export function OpenWhatsNewPopup(onDismissed?: () => void) {
     <div class="whatsnewTextContainer" style="height: 50%;overflow-y: auto;">
 
 
-      <h1>3.6.4 - Fix for alpine theme & Assement dashlet improvement</h1>
+      <h1>3.6.4 - Theme syncing, falvours, fixes & Upcoming Assement dashlet improvement</h1>
       <li>Added advanced colour adjustments variables for theme customisation.</li>
-      <li>Improved logic for assement dashlet to improve compatibility.</li>
+      <li>Improved logic for upcoming assements dashlet to improve compatibility.</li>
       <li>BS Cloud can now automatically download themes from other devices.</li>
       
       <h1>3.6.3 - Assessment overview fix</h1>

src/seqta/utils/cloudSettingsSync.ts

@@ -143,7 +143,10 @@ export async function getSnapshotForUpload(): Promise<{
   return buildUploadPayload(all as Record<string, unknown>);
 }
 
-/** Theme to ensure is installed locally after a downloaded envelope (explicit field overrides `data.selectedTheme`). */
+/**
+ * Theme to ensure is installed locally after a downloaded envelope (explicit `themeId` overrides `data.selectedTheme`).
+ * Works for any store-backed id, including **flavour (slave) variants** nested under masters in the catalogue.
+ */
 export function resolveThemeIdForPostSyncDownload(envelope: unknown): string | undefined {
   if (envelope && typeof envelope === "object" && "themeId" in envelope) {
     const top = normalizeThemeIdForSync(