From 30fa18b68a707cdd11a7beaa76a00c24af326eb9 Mon Sep 17 00:00:00 2001
From: Matthias Klumpp <matthias@tenstral.net>
Date: Fri, 22 Sep 2023 04:46:02 +0200
Subject: [PATCH 1/5] Implement environment property for component screenshots

This adds a new "environment" attribute to the "screenshot" element to
specify the environment in which the screenshot was recorded.
It is comprised of a "<env>:<style>" string, where "style" could be a
specific visual style, like "light" or "dark" or even form factor like
"mobile", and "env" is the desktop environment, like "gnome", "plasma"
or even "windows".

Resolves: #390, #410, #304
---
 compose/asc-utils-screenshots.c |  2 +-
 data/desktop-style-ids.txt      | 16 ++++++
 data/update-data.py             | 31 +++++++++++
 docs/xml/metainfo-component.xml | 34 ++++++++++--
 qt/component.cpp                |  4 +-
 qt/component.h                  |  2 +-
 src/as-component.c              | 96 ++++++++++++++++++++++++++++++---
 src/as-component.h              |  6 ++-
 src/as-screenshot.c             | 44 +++++++++++++++
 src/as-screenshot.h             |  3 ++
 src/as-validator.c              |  4 +-
 tests/test-xmldata.c            | 90 ++++++++++++++++++++++++++++---
 tests/test-yamldata.c           | 44 +++++++++++++--
 tools/ascli-utils.c             | 14 +++--
 14 files changed, 356 insertions(+), 34 deletions(-)
 create mode 100644 data/desktop-style-ids.txt

diff --git a/compose/asc-utils-screenshots.c b/compose/asc-utils-screenshots.c
index a46d8e055..ccee2fc11 100644
--- a/compose/asc-utils-screenshots.c
+++ b/compose/asc-utils-screenshots.c
@@ -777,7 +777,7 @@ asc_process_screenshots (AscResult *cres,
 	if (media_export_root == NULL)
 		store_screenshots = FALSE;
 
-	screenshots = as_component_get_screenshots (cpt);
+	screenshots = as_component_get_screenshots_all (cpt);
 	if (screenshots->len == 0)
 		return;
 
diff --git a/data/desktop-style-ids.txt b/data/desktop-style-ids.txt
new file mode 100644
index 000000000..208667ce9
--- /dev/null
+++ b/data/desktop-style-ids.txt
@@ -0,0 +1,16 @@
+# List of recognized GUI environment IDs
+cinnamon
+dde
+ede
+endless
+gnome
+kde
+lxde
+lxqt
+mate
+pantheon
+plasma
+razor
+rox
+unity
+xfce
diff --git a/data/update-data.py b/data/update-data.py
index 2ea3a1b07..d54acc82e 100755
--- a/data/update-data.py
+++ b/data/update-data.py
@@ -216,6 +216,36 @@ def update_categories_list(spec_url, cat_fname):
         f.write('\n')
 
 
+def update_gui_env_ids():
+    print('Updating GUI environment IDs...')
+
+    desktop_envs = set()
+    with open('desktop-environments.txt', 'r') as f:
+        for line in f.readlines():
+            if line.startswith('#'):
+                continue
+            desktop_envs.add(line.strip().lower())
+
+    # fixup
+    desktop_envs.remove('kde')
+    desktop_envs.add('plasma')
+
+    # extend the existing list
+    gui_env_ids = set()
+    with open('desktop-style-ids.txt', 'r') as f:
+        for line in f.readlines():
+            if line.startswith('#'):
+                continue
+            gui_env_ids.add(line.strip().lower())
+
+    gui_env_ids.update(desktop_envs)
+
+    with open('desktop-style-ids.txt', 'w') as f:
+        f.write('# List of recognized GUI environment IDs\n')
+        f.write('\n'.join(sorted(gui_env_ids)))
+        f.write('\n')
+
+
 def main():
     data_dir = os.path.dirname(os.path.abspath(__file__))
     print('Data directory is: {}'.format(data_dir))
@@ -230,6 +260,7 @@ def main():
     )
     update_categories_list(MENU_SPEC_URL, 'xdg-category-names.txt')
     update_platforms_data()
+    update_gui_env_ids()
 
     print('All done.')
 
diff --git a/docs/xml/metainfo-component.xml b/docs/xml/metainfo-component.xml
index 4371cdcc6..893d396ce 100644
--- a/docs/xml/metainfo-component.xml
+++ b/docs/xml/metainfo-component.xml
@@ -1204,11 +1204,29 @@
 		<para>
 			The <code>&lt;screenshots/&gt;</code> tag contains multiple <code>&lt;screenshot/&gt;</code> children, where at least one of them must have the property
 			<code>type="default"</code> to indicate the primary screenshot of the software. Every <code>&lt;screenshot/&gt;</code> tag must have at least
-			one <code>&lt;image/&gt;</code> or <code>&lt;video/&gt;</code> child, but never an <literal>image</literal> <emphasis>and</emphasis> <literal>video</literal>
-			at the same time.
+			one <code>&lt;image/&gt;</code> <emphasis>or</emphasis> <code>&lt;video/&gt;</code> child, but never an <literal>image</literal> <emphasis>and</emphasis>
+			<literal>video</literal> at the same time.
 		</para>
 		<para>
-			Screenshots containing a video must not be the default screenshot.
+			Screenshots containing videos must not be the default screenshot.
+		</para>
+		<para>
+			Optionally, a <literal>screenshot</literal> may also have an <code>environment</code> property.
+			This string property denotes the GUI environment the screenshot was recorded in, in the form of <code>&lt;env&gt;:&lt;style&gt;</code>,
+			where <literal>env</literal> is a desktop-environment name in lowercase
+			and <literal>style</literal> is a specific style that the desktop environment recognizes, e.g. <code>light</code> and <code>dark</code> for light
+			and dark themes. See <ulink url="https://github.com/ximion/appstream/blob/main/data/desktop-style-ids.txt">desktop-style-ids.txt</ulink> for a list
+			of currently recognized environment and style combinations.
+		</para>
+		<para>
+			Software centers displaying the component will prefer screenshots of the current environment and style first, will then fall back to
+			screenshots of the current environment (without style), and if none of those are available either they will use the environment of the
+			screenshot marked as <code>type="default"</code> (which may be intentionally empty).
+			That way, there will always be a screenshot displayed.
+		</para>
+		<para>
+			In general, screenshots should be displayed in the order the are defined in in their <literal>screenshots</literal> block
+			for the respective component.
 		</para>
 		<para>
 			The value of the <code>&lt;image/&gt;</code> tag is a direct HTTP/HTTPS URL to a screenshot uploaded to a public location on the web.
@@ -1314,6 +1332,16 @@
   <screenshot>
     <video codec="av1" width="1600" height="900">https://example.com/foobar/screencast.mkv</video>
   </screenshot>
+
+  <screenshot environment="plasma-mobile">
+    <caption>The FooBar main window, but on Plasma Mobile</caption>
+    <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-1_plasma-mobile.png</image>
+  </screenshot>
+
+  <screenshot environment="gnome:dark">
+    <caption>The FooBar main window, on GNOME in dark mode</caption>
+    <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-1_gnome_dark.png</image>
+  </screenshot>
  </screenshots>]]></programlisting>
 
 		</listitem>
diff --git a/qt/component.cpp b/qt/component.cpp
index 4ed3e60fe..471cbcb28 100644
--- a/qt/component.cpp
+++ b/qt/component.cpp
@@ -564,11 +564,11 @@ void AppStream::Component::addProvided(const AppStream::Provided &provided)
     as_component_add_provided(d->cpt, provided.asProvided());
 }
 
-QList<Screenshot> Component::screenshots() const
+QList<Screenshot> Component::screenshotsAll() const
 {
     QList<Screenshot> res;
 
-    auto screenshots = as_component_get_screenshots(d->cpt);
+    auto screenshots = as_component_get_screenshots_all(d->cpt);
     res.reserve(screenshots->len);
     for (uint i = 0; i < screenshots->len; i++) {
         auto scr = AS_SCREENSHOT(g_ptr_array_index(screenshots, i));
diff --git a/qt/component.h b/qt/component.h
index 9d4cd4a73..26892c7c5 100644
--- a/qt/component.h
+++ b/qt/component.h
@@ -234,7 +234,7 @@ class APPSTREAMQT_EXPORT Component
     AppStream::Provided provided(Provided::Kind kind) const;
     void addProvided(const AppStream::Provided &provided);
 
-    QList<AppStream::Screenshot> screenshots() const;
+    QList<AppStream::Screenshot> screenshotsAll() const;
     void addScreenshot(const AppStream::Screenshot &screenshot);
 
     Releases releasesPlain() const;
diff --git a/src/as-component.c b/src/as-component.c
index ad0a997f4..8755a5d57 100644
--- a/src/as-component.c
+++ b/src/as-component.c
@@ -621,11 +621,10 @@ as_component_to_string (AsComponent *cpt)
 void
 as_component_add_screenshot (AsComponent *cpt, AsScreenshot *sshot)
 {
-	GPtrArray *sslist;
+	AsComponentPrivate *priv = GET_PRIVATE (cpt);
 	g_return_if_fail (sshot != NULL);
 
-	sslist = as_component_get_screenshots (cpt);
-	g_ptr_array_add (sslist, g_object_ref (sshot));
+	g_ptr_array_add (priv->screenshots, g_object_ref (sshot));
 }
 
 /**
@@ -2001,20 +2000,103 @@ as_component_set_name_variant_suffix (AsComponent *cpt, const gchar *value, cons
 }
 
 /**
- * as_component_get_screenshots:
+ * as_component_get_screenshots_all:
  * @cpt: a #AsComponent instance.
  *
- * Get a list of associated screenshots.
+ * Get a list of all associated screenshots, for all environments.
  *
  * Returns: (element-type AsScreenshot) (transfer none): an array of #AsScreenshot instances
  */
 GPtrArray *
-as_component_get_screenshots (AsComponent *cpt)
+as_component_get_screenshots_all (AsComponent *cpt)
 {
 	AsComponentPrivate *priv = GET_PRIVATE (cpt);
 	return priv->screenshots;
 }
 
+/**
+ * as_component_filter_screenshots:
+ * @cpt: a #AsComponent instance.
+ * @environment: a GUI environment string, e.g. "plasma" or "gnome"
+ * @style: and environment style string, e.g. "light" or "dark"
+ * @allow_default_fallback: if %TRUE, fall back to the component author's default screenshots if no match could be found.
+ *
+ * Filter the associated screenshots for this component by the environment and style, transparently falling back
+ * to the next-best match and ultimately to the screenshots set as default by the metadata authors.
+ *
+ * Returns: (element-type AsScreenshot) (transfer container): an array of #AsScreenshot instances, free with %g_ptr_array_unref
+ */
+GPtrArray *
+as_component_filter_screenshots (AsComponent *cpt,
+				 const gchar *environment,
+				 const gchar *style,
+				 gboolean allow_default_fallback)
+{
+	AsComponentPrivate *priv = GET_PRIVATE (cpt);
+	AsScreenshot *default_scr = NULL;
+	const gchar *default_scr_env = NULL;
+	g_autoptr(GPtrArray) result = NULL;
+	g_autoptr(GPtrArray) fallback_result = NULL;
+	g_autofree gchar *env_id = NULL;
+
+	if (priv->screenshots->len == 0)
+		return g_ptr_array_new ();
+
+	result = g_ptr_array_new ();
+	fallback_result = g_ptr_array_new ();
+
+	env_id = (style == NULL) ? g_strdup (environment)
+				 : g_strconcat (environment, ":", style, NULL);
+	for (guint i = 0; i < priv->screenshots->len; i++) {
+		AsScreenshot *scr = AS_SCREENSHOT (g_ptr_array_index (priv->screenshots, i));
+		const gchar *scr_env_id = as_screenshot_get_environment (scr);
+
+		if (as_screenshot_get_kind (scr) == AS_SCREENSHOT_KIND_DEFAULT)
+			default_scr = scr;
+
+		/* collect exact matches for the requested env/style as result */
+		if (as_str_equal0 (scr_env_id, env_id))
+			g_ptr_array_add (result, scr);
+
+		/* already collect the environment fallback as well */
+		if (as_str_equal0 (scr_env_id, environment))
+			g_ptr_array_add (fallback_result, scr);
+	}
+
+	/* return exact results if we have any! */
+	if (result->len > 0)
+		return g_steal_pointer (&result);
+
+	/* return primary fallbacks if we have any! */
+	if (fallback_result->len > 0)
+		return g_steal_pointer (&fallback_result);
+
+	/* just return if no default fallback is wanted */
+	if (!allow_default_fallback)
+		return g_steal_pointer (&result);
+
+	/* we can only continue if a default screenshot is defined - if we do not
+	 * have one, the metadata was buggy. */
+	if (default_scr == NULL) {
+		g_debug ("Component %s is missing a default screenshot.",
+			 as_component_get_data_id (cpt));
+		return g_steal_pointer (&result);
+	}
+
+	/* if we are here, we need to find the secondary fallback,
+	 * by using the environment of the default screenshot */
+	default_scr_env = as_screenshot_get_environment (default_scr);
+	for (guint i = 0; i < priv->screenshots->len; i++) {
+		AsScreenshot *scr = AS_SCREENSHOT (g_ptr_array_index (priv->screenshots, i));
+		const gchar *scr_env_id = as_screenshot_get_environment (scr);
+
+		if (as_str_equal0 (scr_env_id, default_scr_env))
+			g_ptr_array_add (result, scr);
+	}
+
+	return g_steal_pointer (&result);
+}
+
 /**
  * as_component_get_compulsory_for_desktops:
  * @cpt: a #AsComponent instance.
@@ -6431,7 +6513,7 @@ as_component_get_property (GObject *object, guint property_id, GValue *value, GP
 		g_value_set_string (value, as_component_get_developer_name (cpt));
 		break;
 	case AS_COMPONENT_SCREENSHOTS:
-		g_value_set_boxed (value, as_component_get_screenshots (cpt));
+		g_value_set_boxed (value, as_component_get_screenshots_all (cpt));
 		break;
 	default:
 		G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
diff --git a/src/as-component.h b/src/as-component.h
index 101c54f37..a43a5deca 100644
--- a/src/as-component.h
+++ b/src/as-component.h
@@ -271,7 +271,11 @@ GPtrArray  *as_component_get_categories (AsComponent *cpt);
 void	    as_component_add_category (AsComponent *cpt, const gchar *category);
 gboolean    as_component_has_category (AsComponent *cpt, const gchar *category);
 
-GPtrArray  *as_component_get_screenshots (AsComponent *cpt);
+GPtrArray  *as_component_get_screenshots_all (AsComponent *cpt);
+GPtrArray  *as_component_filter_screenshots (AsComponent *cpt,
+					     const gchar *environment,
+					     const gchar *style,
+					     gboolean	  allow_default_fallback);
 void	    as_component_add_screenshot (AsComponent *cpt, AsScreenshot *sshot);
 
 GPtrArray  *as_component_get_keywords (AsComponent *cpt);
diff --git a/src/as-screenshot.c b/src/as-screenshot.c
index 8cb7bbf1d..cf9d0d3df 100644
--- a/src/as-screenshot.c
+++ b/src/as-screenshot.c
@@ -41,6 +41,7 @@
 typedef struct {
 	AsScreenshotKind kind;
 	AsScreenshotMediaKind media_kind;
+	GRefString *environment;
 	GHashTable *caption;
 
 	GPtrArray *images;
@@ -88,6 +89,7 @@ as_screenshot_finalize (GObject *object)
 	g_ptr_array_unref (priv->videos);
 	g_ptr_array_unref (priv->videos_lang);
 	g_hash_table_unref (priv->caption);
+	as_ref_string_release (priv->environment);
 	if (priv->context != NULL)
 		g_object_unref (priv->context);
 
@@ -186,6 +188,36 @@ as_screenshot_get_media_kind (AsScreenshot *screenshot)
 	return priv->media_kind;
 }
 
+/**
+ * as_screenshot_get_environment:
+ * @screenshot: a #AsScreenshot instance.
+ *
+ * Get the GUI environment ID of this screenshot, if any
+ * is associated with it. E.g. "plasma-mobile" or "gnome:dark".
+ *
+ * Returns: (nullable): The GUI environment ID the screenshot was recorded in, or %NULL if none set.
+ **/
+const gchar *
+as_screenshot_get_environment (AsScreenshot *screenshot)
+{
+	AsScreenshotPrivate *priv = GET_PRIVATE (screenshot);
+	return priv->environment;
+}
+
+/**
+ * as_screenshot_set_environment:
+ * @screenshot: a #AsScreenshot instance.
+ * @env_id: (nullable): the GUI environment ID, e.g. "plasma-mobile" or "gnome:dark"
+ *
+ * Sets the GUI environment ID of this screenshot.
+ **/
+void
+as_screenshot_set_environment (AsScreenshot *screenshot, const gchar *env_id)
+{
+	AsScreenshotPrivate *priv = GET_PRIVATE (screenshot);
+	as_ref_string_assign_safe (&priv->environment, env_id);
+}
+
 /**
  * as_screenshot_get_active_locale:
  *
@@ -548,12 +580,18 @@ as_screenshot_load_from_xml (AsScreenshot *screenshot,
 	g_autofree gchar *prop = NULL;
 	gboolean children_found = FALSE;
 
+	/* screenshot type */
 	prop = as_xml_get_prop_value (node, "type");
 	if (g_strcmp0 (prop, "default") == 0)
 		priv->kind = AS_SCREENSHOT_KIND_DEFAULT;
 	else
 		priv->kind = AS_SCREENSHOT_KIND_EXTRA;
 
+	/* environment */
+	as_ref_string_assign_transfer (&priv->environment,
+				       as_xml_get_prop_value_refstr (node, "environment"));
+
+	/* screenshot media */
 	for (iter = node->children; iter != NULL; iter = iter->next) {
 		const gchar *node_name;
 		/* discard spaces */
@@ -620,6 +658,8 @@ as_screenshot_to_xml_node (AsScreenshot *screenshot, AsContext *ctx, xmlNode *ro
 	subnode = as_xml_add_node (root, "screenshot");
 	if (priv->kind == AS_SCREENSHOT_KIND_DEFAULT)
 		as_xml_add_text_prop (subnode, "type", "default");
+	if (priv->environment != NULL)
+		as_xml_add_text_prop (subnode, "environment", priv->environment);
 
 	as_xml_add_localized_text_node (subnode, "caption", priv->caption);
 
@@ -661,6 +701,8 @@ as_screenshot_load_from_yaml (AsScreenshot *screenshot, AsContext *ctx, GNode *n
 				priv->kind = AS_SCREENSHOT_KIND_DEFAULT;
 			else
 				priv->kind = AS_SCREENSHOT_KIND_EXTRA;
+		} else if (g_strcmp0 (key, "environment") == 0) {
+			as_ref_string_assign_safe (&priv->environment, value);
 		} else if (g_strcmp0 (key, "caption") == 0) {
 			/* the caption is a localized element */
 			as_yaml_set_localized_table (ctx, n, priv->caption);
@@ -715,6 +757,8 @@ as_screenshot_emit_yaml (AsScreenshot *screenshot, AsContext *ctx, yaml_emitter_
 
 	if (priv->kind == AS_SCREENSHOT_KIND_DEFAULT)
 		as_yaml_emit_entry (emitter, "default", "true");
+	if (priv->environment != NULL)
+		as_yaml_emit_entry (emitter, "environment", priv->environment);
 
 	as_yaml_emit_localized_entry (emitter, "caption", priv->caption);
 
diff --git a/src/as-screenshot.h b/src/as-screenshot.h
index 7e46066c5..cfb0bb487 100644
--- a/src/as-screenshot.h
+++ b/src/as-screenshot.h
@@ -89,6 +89,9 @@ AsScreenshot	     *as_screenshot_new (void);
 AsScreenshotKind      as_screenshot_get_kind (AsScreenshot *screenshot);
 void		      as_screenshot_set_kind (AsScreenshot *screenshot, AsScreenshotKind kind);
 
+const gchar	     *as_screenshot_get_environment (AsScreenshot *screenshot);
+void		      as_screenshot_set_environment (AsScreenshot *screenshot, const gchar *env_id);
+
 AsContext	     *as_screenshot_get_context (AsScreenshot *screenshot);
 void		      as_screenshot_set_context (AsScreenshot *screenshot, AsContext *context);
 
diff --git a/src/as-validator.c b/src/as-validator.c
index eaae70468..90a34d0a0 100644
--- a/src/as-validator.c
+++ b/src/as-validator.c
@@ -3299,11 +3299,11 @@ as_validator_validate_component_node (AsValidator *validator, AsContext *ctx, xm
 	}
 
 	/* validate screenshots */
-	if (as_component_get_screenshots (cpt)->len > 0) {
+	if (as_component_get_screenshots_all (cpt)->len > 0) {
 		guint j;
 		GPtrArray *scr_array;
 
-		scr_array = as_component_get_screenshots (cpt);
+		scr_array = as_component_get_screenshots_all (cpt);
 		for (j = 0; j < scr_array->len; j++) {
 			AsScreenshot *scr = AS_SCREENSHOT (g_ptr_array_index (scr_array, j));
 			const gchar *scr_caption = as_screenshot_get_caption (scr);
diff --git a/tests/test-xmldata.c b/tests/test-xmldata.c
index 88e54441c..fce341b78 100644
--- a/tests/test-xmldata.c
+++ b/tests/test-xmldata.c
@@ -144,7 +144,7 @@ test_appstream_parser_legacy (void)
 	g_assert_cmpstr (as_component_get_summary (cpt), ==, "Application manager for GNOME");
 	g_assert_true (as_component_get_kind (cpt) == AS_COMPONENT_KIND_DESKTOP_APP);
 
-	screenshots = as_component_get_screenshots (cpt);
+	screenshots = as_component_get_screenshots_all (cpt);
 	g_assert_cmpint (screenshots->len, ==, 5);
 
 	g_object_unref (metad);
@@ -1238,6 +1238,7 @@ test_appstream_write_metainfo_to_catalog (void)
 	g_free (tmp);
 }
 
+/* clang-format off */
 static const gchar *xmldata_screenshots =
     "<component>\n"
     "  <id>org.example.ScreenshotTest</id>\n"
@@ -1260,11 +1261,19 @@ static const gchar *xmldata_screenshots =
     "    <screenshot>\n"
     "      <video codec=\"av1\" container=\"matroska\" width=\"1916\" "
     "height=\"1056\">https://example.org/screencast.mkv</video>\n"
-    "      <video codec=\"av1\" container=\"matroska\" width=\"1916\" height=\"1056\" "
-    "xml:lang=\"de-DE\">https://example.org/screencast_de.mkv</video>\n"
+    "      <video codec=\"av1\" container=\"matroska\" width=\"1916\" height=\"1056\" xml:lang=\"de-DE\">https://example.org/screencast_de.mkv</video>\n"
+    "    </screenshot>\n"
+    "    <screenshot environment=\"plasma:mobile\">\n"
+    "      <caption>The app, on mobile!</caption>\n"
+    "      <image type=\"source\" width=\"640\" height=\"1136\">https://example.org/alpha_mobile.png</image>\n"
+    "    </screenshot>\n"
+    "    <screenshot environment=\"plasma\">\n"
+    "      <caption>The app, on KDE Plasma desktop!</caption>\n"
+    "      <image type=\"source\" width=\"1916\" height=\"1056\">https://example.org/alpha_desktop.png</image>\n"
     "    </screenshot>\n"
     "  </screenshots>\n"
     "</component>\n";
+/* clang-format on */
 
 /**
  * test_xml_read_screenshots:
@@ -1275,10 +1284,12 @@ static void
 test_xml_read_screenshots (void)
 {
 	g_autoptr(AsComponent) cpt = NULL;
+	g_autoptr(GPtrArray) scr_filtered = NULL;
 	GPtrArray *screenshots;
 	AsScreenshot *scr1;
 	AsScreenshot *scr2;
 	AsScreenshot *scr3;
+	AsScreenshot *scr4;
 	GPtrArray *images;
 	GPtrArray *videos;
 	AsImage *img;
@@ -1295,12 +1306,13 @@ test_xml_read_screenshots (void)
 	cpt = as_xml_test_read_data (xmldata_screenshots, AS_FORMAT_STYLE_METAINFO);
 	g_assert_cmpstr (as_component_get_id (cpt), ==, "org.example.ScreenshotTest");
 
-	screenshots = as_component_get_screenshots (cpt);
-	g_assert_cmpint (screenshots->len, ==, 3);
+	screenshots = as_component_get_screenshots_all (cpt);
+	g_assert_cmpint (screenshots->len, ==, 5);
 
 	scr1 = AS_SCREENSHOT (g_ptr_array_index (screenshots, 0));
 	scr2 = AS_SCREENSHOT (g_ptr_array_index (screenshots, 1));
 	scr3 = AS_SCREENSHOT (g_ptr_array_index (screenshots, 2));
+	scr4 = AS_SCREENSHOT (g_ptr_array_index (screenshots, 3));
 
 	/* screenshot 1 */
 	g_assert_cmpint (as_screenshot_get_kind (scr1), ==, AS_SCREENSHOT_KIND_DEFAULT);
@@ -1395,12 +1407,52 @@ test_xml_read_screenshots (void)
 	g_assert_cmpint (as_video_get_width (vid), ==, 1916);
 	g_assert_cmpint (as_video_get_height (vid), ==, 1056);
 
+	/* screenshot 4 */
+	g_assert_cmpint (as_screenshot_get_kind (scr4), ==, AS_SCREENSHOT_KIND_EXTRA);
+	g_assert_cmpint (as_screenshot_get_media_kind (scr4), ==, AS_SCREENSHOT_MEDIA_KIND_IMAGE);
+	g_assert_cmpstr (as_screenshot_get_caption (scr4), ==, "The app, on mobile!");
+	g_assert_cmpstr (as_screenshot_get_environment (scr4), ==, "plasma:mobile");
+
+	images = as_screenshot_get_images_all (scr4);
+	g_assert_cmpint (images->len, ==, 1);
+
+	img = AS_IMAGE (g_ptr_array_index (images, 0));
+	g_assert_cmpint (as_image_get_kind (img), ==, AS_IMAGE_KIND_SOURCE);
+	g_assert_cmpstr (as_image_get_url (img), ==, "https://example.org/alpha_mobile.png");
+	g_assert_cmpint (as_image_get_width (img), ==, 640);
+	g_assert_cmpint (as_image_get_height (img), ==, 1136);
+
+	/* test some filtered loading */
+	as_component_set_context_locale (cpt, "C");
+	scr_filtered = as_component_filter_screenshots (cpt, "plasma", "mobile", TRUE);
+	g_assert_cmpint (scr_filtered->len, ==, 1);
+	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 0)),
+			 ==,
+			 "The app, on mobile!");
+	g_clear_pointer (&scr_filtered, g_ptr_array_unref);
+
+	scr_filtered = as_component_filter_screenshots (cpt, "plasma", NULL, TRUE);
+	g_assert_cmpint (scr_filtered->len, ==, 1);
+	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 0)),
+			 ==,
+			 "The app, on KDE Plasma desktop!");
+	g_clear_pointer (&scr_filtered, g_ptr_array_unref);
+
+	scr_filtered = as_component_filter_screenshots (cpt, "gnome", NULL, TRUE);
+	g_assert_cmpint (scr_filtered->len, ==, 3);
+	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 0)),
+			 ==,
+			 "The main window displaying a thing");
+	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 1)), ==, NULL);
+	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 2)), ==, NULL);
+	g_clear_pointer (&scr_filtered, g_ptr_array_unref);
+
 	/* test a legacy screenshot entry that we briefly supported in an older AppStream release */
 	g_object_unref (cpt);
 	cpt = as_xml_test_read_data (xmldata_screenshot_legacy, AS_FORMAT_STYLE_METAINFO);
 	g_assert_cmpstr (as_component_get_id (cpt), ==, "org.example.ScreenshotAncient");
 
-	screenshots = as_component_get_screenshots (cpt);
+	screenshots = as_component_get_screenshots_all (cpt);
 	g_assert_cmpint (screenshots->len, ==, 1);
 
 	scr1 = AS_SCREENSHOT (g_ptr_array_index (screenshots, 0));
@@ -1426,6 +1478,8 @@ test_xml_write_screenshots (void)
 	g_autoptr(AsScreenshot) scr1 = NULL;
 	g_autoptr(AsScreenshot) scr2 = NULL;
 	g_autoptr(AsScreenshot) scr3 = NULL;
+	g_autoptr(AsScreenshot) scr4 = NULL;
+	g_autoptr(AsScreenshot) scr5 = NULL;
 	AsImage *img;
 	AsVideo *vid;
 
@@ -1496,9 +1550,33 @@ test_xml_write_screenshots (void)
 	as_screenshot_add_video (scr3, vid);
 	g_object_unref (vid);
 
+	scr4 = as_screenshot_new ();
+	as_screenshot_set_caption (scr4, "The app, on mobile!", "C");
+	as_screenshot_set_environment (scr4, "plasma:mobile");
+	img = as_image_new ();
+	as_image_set_kind (img, AS_IMAGE_KIND_SOURCE);
+	as_image_set_width (img, 640);
+	as_image_set_height (img, 1136);
+	as_image_set_url (img, "https://example.org/alpha_mobile.png");
+	as_screenshot_add_image (scr4, img);
+	g_object_unref (img);
+
+	scr5 = as_screenshot_new ();
+	as_screenshot_set_caption (scr5, "The app, on KDE Plasma desktop!", "C");
+	as_screenshot_set_environment (scr5, "plasma");
+	img = as_image_new ();
+	as_image_set_kind (img, AS_IMAGE_KIND_SOURCE);
+	as_image_set_width (img, 1916);
+	as_image_set_height (img, 1056);
+	as_image_set_url (img, "https://example.org/alpha_desktop.png");
+	as_screenshot_add_image (scr5, img);
+	g_object_unref (img);
+
 	as_component_add_screenshot (cpt, scr1);
 	as_component_add_screenshot (cpt, scr2);
 	as_component_add_screenshot (cpt, scr3);
+	as_component_add_screenshot (cpt, scr4);
+	as_component_add_screenshot (cpt, scr5);
 
 	res = as_xml_test_serialize (cpt, AS_FORMAT_STYLE_METAINFO);
 	g_assert_true (as_xml_test_compare_xml (res, xmldata_screenshots));
diff --git a/tests/test-yamldata.c b/tests/test-yamldata.c
index 293107865..e56e3554a 100644
--- a/tests/test-yamldata.c
+++ b/tests/test-yamldata.c
@@ -1414,7 +1414,15 @@ static const gchar *yamldata_screenshots = "Type: generic\n"
 					   "    url: https://example.org/screencast_de.mkv\n"
 					   "    width: 1916\n"
 					   "    height: 1056\n"
-					   "    lang: de-DE\n";
+					   "    lang: de-DE\n"
+					   "- environment: plasma:mobile\n"
+					   "  caption:\n"
+					   "    C: The app, on mobile!\n"
+					   "  thumbnails: []\n"
+					   "  source-image:\n"
+					   "    url: https://example.org/alpha_mobile.png\n"
+					   "    width: 640\n"
+					   "    height: 1136\n";
 
 /**
  * test_yaml_write_screenshots:
@@ -1428,6 +1436,7 @@ test_yaml_write_screenshots (void)
 	g_autofree gchar *res = NULL;
 	g_autoptr(AsScreenshot) scr1 = NULL;
 	g_autoptr(AsScreenshot) scr2 = NULL;
+	g_autoptr(AsScreenshot) scr3 = NULL;
 	AsImage *img;
 	AsVideo *vid;
 
@@ -1476,8 +1485,20 @@ test_yaml_write_screenshots (void)
 	as_screenshot_add_video (scr2, vid);
 	g_object_unref (vid);
 
+	scr3 = as_screenshot_new ();
+	as_screenshot_set_caption (scr3, "The app, on mobile!", "C");
+	as_screenshot_set_environment (scr3, "plasma:mobile");
+	img = as_image_new ();
+	as_image_set_kind (img, AS_IMAGE_KIND_SOURCE);
+	as_image_set_width (img, 640);
+	as_image_set_height (img, 1136);
+	as_image_set_url (img, "https://example.org/alpha_mobile.png");
+	as_screenshot_add_image (scr3, img);
+	g_object_unref (img);
+
 	as_component_add_screenshot (cpt, scr1);
 	as_component_add_screenshot (cpt, scr2);
+	as_component_add_screenshot (cpt, scr3);
 
 	/* test catalog serialization */
 	res = as_yaml_test_serialize (cpt);
@@ -1496,6 +1517,7 @@ test_yaml_read_screenshots (void)
 	GPtrArray *screenshots;
 	AsScreenshot *scr1;
 	AsScreenshot *scr2;
+	AsScreenshot *scr3;
 	GPtrArray *images;
 	GPtrArray *videos;
 	AsImage *img;
@@ -1504,11 +1526,12 @@ test_yaml_read_screenshots (void)
 	cpt = as_yaml_test_read_data (yamldata_screenshots, NULL);
 	g_assert_cmpstr (as_component_get_id (cpt), ==, "org.example.ScreenshotsTest");
 
-	screenshots = as_component_get_screenshots (cpt);
-	g_assert_cmpint (screenshots->len, ==, 2);
+	screenshots = as_component_get_screenshots_all (cpt);
+	g_assert_cmpint (screenshots->len, ==, 3);
 
 	scr1 = AS_SCREENSHOT (g_ptr_array_index (screenshots, 0));
 	scr2 = AS_SCREENSHOT (g_ptr_array_index (screenshots, 1));
+	scr3 = AS_SCREENSHOT (g_ptr_array_index (screenshots, 2));
 
 	/* screenshot 1 */
 	g_assert_cmpint (as_screenshot_get_kind (scr1), ==, AS_SCREENSHOT_KIND_DEFAULT);
@@ -1569,6 +1592,21 @@ test_yaml_read_screenshots (void)
 	g_assert_cmpstr (as_video_get_url (vid), ==, "https://example.org/screencast_de.mkv");
 	g_assert_cmpint (as_video_get_width (vid), ==, 1916);
 	g_assert_cmpint (as_video_get_height (vid), ==, 1056);
+
+	/* screenshot 3 */
+	g_assert_cmpint (as_screenshot_get_kind (scr3), ==, AS_SCREENSHOT_KIND_EXTRA);
+	g_assert_cmpint (as_screenshot_get_media_kind (scr3), ==, AS_SCREENSHOT_MEDIA_KIND_IMAGE);
+	g_assert_cmpstr (as_screenshot_get_caption (scr3), ==, "The app, on mobile!");
+	g_assert_cmpstr (as_screenshot_get_environment (scr3), ==, "plasma:mobile");
+
+	images = as_screenshot_get_images_all (scr3);
+	g_assert_cmpint (images->len, ==, 1);
+
+	img = AS_IMAGE (g_ptr_array_index (images, 0));
+	g_assert_cmpint (as_image_get_kind (img), ==, AS_IMAGE_KIND_SOURCE);
+	g_assert_cmpstr (as_image_get_url (img), ==, "https://example.org/alpha_mobile.png");
+	g_assert_cmpint (as_image_get_width (img), ==, 640);
+	g_assert_cmpint (as_image_get_height (img), ==, 1136);
 }
 
 static const gchar *yamldata_releases_field =
diff --git a/tools/ascli-utils.c b/tools/ascli-utils.c
index d7e4d4954..a35b5a554 100644
--- a/tools/ascli-utils.c
+++ b/tools/ascli-utils.c
@@ -278,7 +278,6 @@ ascli_print_component (AsComponent *cpt, gboolean show_detailed)
 	gchar *pkgs_str = NULL;
 	gchar *bundles_str = NULL;
 	AsIcon *icon = NULL;
-	guint j;
 
 	short_idline = g_strdup_printf ("%s [%s]",
 					as_component_get_id (cpt),
@@ -290,7 +289,7 @@ ascli_print_component (AsComponent *cpt, gboolean show_detailed)
 	icon = as_component_get_icon_by_size (cpt, 64, 64);
 	if (icon == NULL) {
 		GPtrArray *icons = as_component_get_icons (cpt);
-		for (j = 0; j < icons->len; j++) {
+		for (guint j = 0; j < icons->len; j++) {
 			AsIcon *tmp_icon = AS_ICON (g_ptr_array_index (icons, j));
 			if (as_icon_get_kind (tmp_icon) == AS_ICON_KIND_STOCK) {
 				icon = tmp_icon;
@@ -322,7 +321,6 @@ ascli_print_component (AsComponent *cpt, gboolean show_detailed)
 		GPtrArray *categories;
 		GPtrArray *compulsory_desktops;
 		GPtrArray *provided;
-		guint i;
 		AsScreenshot *sshot;
 		AsImage *img;
 		gchar *str;
@@ -345,11 +343,11 @@ ascli_print_component (AsComponent *cpt, gboolean show_detailed)
 		g_free (str);
 
 		/* some simple screenshot information */
-		sshot_array = as_component_get_screenshots (cpt);
+		sshot_array = as_component_get_screenshots_all (cpt);
 
 		/* find default screenshot, if possible */
 		sshot = NULL;
-		for (j = 0; j < sshot_array->len; j++) {
+		for (guint j = 0; j < sshot_array->len; j++) {
 			sshot = AS_SCREENSHOT (g_ptr_array_index (sshot_array, j));
 			if (as_screenshot_get_kind (sshot) == AS_SCREENSHOT_KIND_DEFAULT)
 				break;
@@ -358,7 +356,7 @@ ascli_print_component (AsComponent *cpt, gboolean show_detailed)
 		if (sshot != NULL) {
 			/* get the first source image and display it's url */
 			imgs = as_screenshot_get_images (sshot);
-			for (j = 0; j < imgs->len; j++) {
+			for (guint j = 0; j < imgs->len; j++) {
 				img = AS_IMAGE (g_ptr_array_index (imgs, j));
 				if (as_image_get_kind (img) == AS_IMAGE_KIND_SOURCE) {
 					ascli_print_key_value (_("Default Screenshot URL"),
@@ -396,7 +394,7 @@ ascli_print_component (AsComponent *cpt, gboolean show_detailed)
 		addons = as_component_get_addons (cpt);
 		if (addons->len > 0) {
 			g_autoptr(GPtrArray) addons_str = g_ptr_array_new_with_free_func (g_free);
-			for (i = 0; i < addons->len; i++) {
+			for (guint i = 0; i < addons->len; i++) {
 				AsComponent *addon = AS_COMPONENT (g_ptr_array_index (addons, i));
 				if (as_component_get_kind (addon) ==
 				    AS_COMPONENT_KIND_LOCALIZATION) {
@@ -424,7 +422,7 @@ ascli_print_component (AsComponent *cpt, gboolean show_detailed)
 			/* TRANSLATORS: Other software or interfaces that this software component provides */
 			ascli_print_key_value (_("Provided Items"), "↓", FALSE);
 		}
-		for (i = 0; i < provided->len; i++) {
+		for (guint i = 0; i < provided->len; i++) {
 			GPtrArray *items = NULL;
 			AsProvided *prov = AS_PROVIDED (g_ptr_array_index (provided, i));
 

From 80df71bd437cc080f5b9416cd57b1ef36401fd0e Mon Sep 17 00:00:00 2001
From: Matthias Klumpp <matthias@tenstral.net>
Date: Wed, 27 Sep 2023 04:10:40 +0200
Subject: [PATCH 2/5] Add ability to reorder screenshots by environment,
 instead of filtering them

---
 src/as-component.c          | 155 +++++++++++++++++++++---------------
 src/as-component.h          |   8 +-
 src/as-screenshot-private.h |   3 +
 src/as-screenshot.c         |  31 ++++++++
 tests/test-xmldata.c        |  74 +++++++++++------
 5 files changed, 180 insertions(+), 91 deletions(-)

diff --git a/src/as-component.c b/src/as-component.c
index 8755a5d57..e160d5411 100644
--- a/src/as-component.c
+++ b/src/as-component.c
@@ -2014,87 +2014,108 @@ as_component_get_screenshots_all (AsComponent *cpt)
 	return priv->screenshots;
 }
 
-/**
- * as_component_filter_screenshots:
- * @cpt: a #AsComponent instance.
- * @environment: a GUI environment string, e.g. "plasma" or "gnome"
- * @style: and environment style string, e.g. "light" or "dark"
- * @allow_default_fallback: if %TRUE, fall back to the component author's default screenshots if no match could be found.
- *
- * Filter the associated screenshots for this component by the environment and style, transparently falling back
- * to the next-best match and ultimately to the screenshots set as default by the metadata authors.
- *
- * Returns: (element-type AsScreenshot) (transfer container): an array of #AsScreenshot instances, free with %g_ptr_array_unref
- */
-GPtrArray *
-as_component_filter_screenshots (AsComponent *cpt,
-				 const gchar *environment,
-				 const gchar *style,
-				 gboolean allow_default_fallback)
+typedef struct {
+	const gchar *env_id;
+	const gchar *style;
+	const gchar *environment;
+	gboolean prioritize_style;
+} AsScreenshotSortHelper;
+
+static gint
+as_screenshot_order_score_helper (AsScreenshot *scr, AsScreenshotSortHelper *helper)
 {
-	AsComponentPrivate *priv = GET_PRIVATE (cpt);
-	AsScreenshot *default_scr = NULL;
-	const gchar *default_scr_env = NULL;
-	g_autoptr(GPtrArray) result = NULL;
-	g_autoptr(GPtrArray) fallback_result = NULL;
-	g_autofree gchar *env_id = NULL;
+	const gchar *scr_env = as_screenshot_get_environment (scr);
 
-	if (priv->screenshots->len == 0)
-		return g_ptr_array_new ();
+	if (as_str_equal0 (scr_env, helper->env_id))
+		return -2 * as_screenshot_get_position (scr);
 
-	result = g_ptr_array_new ();
-	fallback_result = g_ptr_array_new ();
+	if (helper->prioritize_style) {
+		if (scr_env != NULL && g_str_has_suffix (scr_env, helper->style))
+			return -1 * as_screenshot_get_position (scr);
+	}
 
-	env_id = (style == NULL) ? g_strdup (environment)
-				 : g_strconcat (environment, ":", style, NULL);
-	for (guint i = 0; i < priv->screenshots->len; i++) {
-		AsScreenshot *scr = AS_SCREENSHOT (g_ptr_array_index (priv->screenshots, i));
-		const gchar *scr_env_id = as_screenshot_get_environment (scr);
+	if (scr_env != NULL && g_str_has_prefix (scr_env, helper->environment))
+		return -1 * as_screenshot_get_position (scr);
 
-		if (as_screenshot_get_kind (scr) == AS_SCREENSHOT_KIND_DEFAULT)
-			default_scr = scr;
+	return as_screenshot_get_position (scr);
+}
 
-		/* collect exact matches for the requested env/style as result */
-		if (as_str_equal0 (scr_env_id, env_id))
-			g_ptr_array_add (result, scr);
+static gint
+as_screenshots_sort_cb (gconstpointer a, gconstpointer b, gpointer user_data)
+{
+	AsScreenshotSortHelper *helper = user_data;
+	AsScreenshot *scr1 = *((AsScreenshot **) a);
+	AsScreenshot *scr2 = *((AsScreenshot **) b);
 
-		/* already collect the environment fallback as well */
-		if (as_str_equal0 (scr_env_id, environment))
-			g_ptr_array_add (fallback_result, scr);
-	}
+	return as_screenshot_order_score_helper (scr1, helper) -
+	       as_screenshot_order_score_helper (scr2, helper);
+}
 
-	/* return exact results if we have any! */
-	if (result->len > 0)
-		return g_steal_pointer (&result);
+static gint
+as_screenshots_sort_defaults_cb (gconstpointer a, gconstpointer b)
+{
+	AsScreenshot *scr1 = *((AsScreenshot **) a);
+	AsScreenshot *scr2 = *((AsScreenshot **) b);
+	return as_screenshot_get_position (scr1) - as_screenshot_get_position (scr2);
+}
 
-	/* return primary fallbacks if we have any! */
-	if (fallback_result->len > 0)
-		return g_steal_pointer (&fallback_result);
+/**
+ * as_component_sort_screenshots:
+ * @cpt: a #AsComponent instance.
+ * @environment: (nullable): a GUI environment string, e.g. "plasma" or "gnome"
+ * @style: (nullable): and environment style string, e.g. "light" or "dark"
+ * @prioritize_style: if %TRUE, order screenshots of the given style earlier than ones of the given environment.
+ *
+ * Reorder the screenshots to prioritize a certain environment or style, instead of using the default
+ * screenshot order.
+ *
+ * If both "environment" and "style" are %NULL, the previous default order is restored.
+ */
+void
+as_component_sort_screenshots (AsComponent *cpt,
+			       const gchar *environment,
+			       const gchar *style,
+			       gboolean prioritize_style)
+{
+	AsComponentPrivate *priv = GET_PRIVATE (cpt);
+	g_autofree gchar *env_id = NULL;
+	AsScreenshotSortHelper helper;
 
-	/* just return if no default fallback is wanted */
-	if (!allow_default_fallback)
-		return g_steal_pointer (&result);
+	if (priv->screenshots == 0)
+		return;
 
-	/* we can only continue if a default screenshot is defined - if we do not
-	 * have one, the metadata was buggy. */
-	if (default_scr == NULL) {
-		g_debug ("Component %s is missing a default screenshot.",
-			 as_component_get_data_id (cpt));
-		return g_steal_pointer (&result);
+	/* restore defaults if both specifiers are NULL */
+	if (environment == NULL && style == NULL) {
+		/* restore the default order, but only if we changed the order before */
+		if (as_screenshot_get_position (
+			AS_SCREENSHOT (g_ptr_array_index (priv->screenshots, 0))) < 0)
+			return;
+		g_ptr_array_sort (priv->screenshots, as_screenshots_sort_defaults_cb);
+		return;
 	}
 
-	/* if we are here, we need to find the secondary fallback,
-	 * by using the environment of the default screenshot */
-	default_scr_env = as_screenshot_get_environment (default_scr);
+	if (environment == NULL)
+		environment = "";
+
+	/* ensure screenshot ordering positions are set */
 	for (guint i = 0; i < priv->screenshots->len; i++) {
 		AsScreenshot *scr = AS_SCREENSHOT (g_ptr_array_index (priv->screenshots, i));
-		const gchar *scr_env_id = as_screenshot_get_environment (scr);
-
-		if (as_str_equal0 (scr_env_id, default_scr_env))
-			g_ptr_array_add (result, scr);
+		if (as_screenshot_get_position (scr) < 0)
+			as_screenshot_set_position (scr, i);
 	}
 
-	return g_steal_pointer (&result);
+	/* construct the environment ID to sort by */
+	env_id = (style == NULL) ? g_strdup (environment)
+				 : g_strconcat (environment, ":", style, NULL);
+
+	/* set helper */
+	helper.environment = environment;
+	helper.style = style;
+	helper.env_id = env_id;
+	helper.prioritize_style = prioritize_style;
+
+	/* sort screenshots */
+	g_ptr_array_sort_with_data (priv->screenshots, as_screenshots_sort_cb, &helper);
 }
 
 /**
@@ -5079,6 +5100,9 @@ as_component_to_xml_node (AsComponent *cpt, AsContext *ctx, xmlNode *root)
 	if (priv->screenshots->len > 0) {
 		xmlNode *rnode = as_xml_add_node (cnode, "screenshots");
 
+		/* restore default screenshot order */
+		as_component_sort_screenshots (cpt, NULL, NULL, FALSE);
+
 		for (guint i = 0; i < priv->screenshots->len; i++) {
 			AsScreenshot *scr = AS_SCREENSHOT (
 			    g_ptr_array_index (priv->screenshots, i));
@@ -6254,6 +6278,9 @@ as_component_emit_yaml (AsComponent *cpt, AsContext *ctx, yaml_emitter_t *emitte
 
 	/* Screenshots */
 	if (priv->screenshots->len > 0) {
+		/* restore default screenshot order */
+		as_component_sort_screenshots (cpt, NULL, NULL, FALSE);
+
 		as_yaml_emit_scalar (emitter, "Screenshots");
 		as_yaml_sequence_start (emitter);
 
diff --git a/src/as-component.h b/src/as-component.h
index a43a5deca..0e1416410 100644
--- a/src/as-component.h
+++ b/src/as-component.h
@@ -272,10 +272,10 @@ void	    as_component_add_category (AsComponent *cpt, const gchar *category);
 gboolean    as_component_has_category (AsComponent *cpt, const gchar *category);
 
 GPtrArray  *as_component_get_screenshots_all (AsComponent *cpt);
-GPtrArray  *as_component_filter_screenshots (AsComponent *cpt,
-					     const gchar *environment,
-					     const gchar *style,
-					     gboolean	  allow_default_fallback);
+void	    as_component_sort_screenshots (AsComponent *cpt,
+					   const gchar *environment,
+					   const gchar *style,
+					   gboolean	prioritize_style);
 void	    as_component_add_screenshot (AsComponent *cpt, AsScreenshot *sshot);
 
 GPtrArray  *as_component_get_keywords (AsComponent *cpt);
diff --git a/src/as-screenshot-private.h b/src/as-screenshot-private.h
index fb7ba70f9..f15f6b208 100644
--- a/src/as-screenshot-private.h
+++ b/src/as-screenshot-private.h
@@ -43,6 +43,9 @@ gboolean as_screenshot_load_from_yaml (AsScreenshot *screenshot,
 				       GError	   **error);
 void as_screenshot_emit_yaml (AsScreenshot *screenshot, AsContext *ctx, yaml_emitter_t *emitter);
 
+gint as_screenshot_get_position (AsScreenshot *screenshot);
+void as_screenshot_set_position (AsScreenshot *screenshot, gint pos);
+
 AS_END_PRIVATE_DECLS
 
 #endif /* __AS_SCREENSHOT_PRIVATE_H */
diff --git a/src/as-screenshot.c b/src/as-screenshot.c
index cf9d0d3df..733e45174 100644
--- a/src/as-screenshot.c
+++ b/src/as-screenshot.c
@@ -49,6 +49,7 @@ typedef struct {
 	GPtrArray *videos;
 	GPtrArray *videos_lang;
 
+	gint position;
 	AsContext *context;
 } AsScreenshotPrivate;
 
@@ -63,6 +64,7 @@ as_screenshot_init (AsScreenshot *screenshot)
 {
 	AsScreenshotPrivate *priv = GET_PRIVATE (screenshot);
 
+	priv->position = -1;
 	priv->kind = AS_SCREENSHOT_KIND_EXTRA;
 	priv->media_kind = AS_SCREENSHOT_MEDIA_KIND_IMAGE;
 	priv->caption = g_hash_table_new_full (g_str_hash,
@@ -560,6 +562,35 @@ as_screenshot_set_context (AsScreenshot *screenshot, AsContext *context)
 	as_screenshot_rebuild_suitable_media_list (screenshot);
 }
 
+/**
+ * as_screenshot_get_position:
+ * @screenshot: a #AsScreenshot instance.
+ *
+ * Gets the ordering priority of this screenshot.
+ *
+ * Returns: the position of this screenshot in the screenshot list, or -1 if unknown.
+ **/
+gint
+as_screenshot_get_position (AsScreenshot *screenshot)
+{
+	AsScreenshotPrivate *priv = GET_PRIVATE (screenshot);
+	return priv->position;
+}
+
+/**
+ * as_screenshot_set_position:
+ * @screenshot: a #AsScreenshot instance.
+ *
+ * Sets the ordering priority / screenshot list position of
+ * this screenshot.
+ **/
+void
+as_screenshot_set_position (AsScreenshot *screenshot, gint pos)
+{
+	AsScreenshotPrivate *priv = GET_PRIVATE (screenshot);
+	priv->position = pos;
+}
+
 /**
  * as_screenshot_load_from_xml:
  * @screenshot: an #AsScreenshot instance.
diff --git a/tests/test-xmldata.c b/tests/test-xmldata.c
index fce341b78..2a0bd28b2 100644
--- a/tests/test-xmldata.c
+++ b/tests/test-xmldata.c
@@ -1252,6 +1252,7 @@ static const gchar *xmldata_screenshots =
     "height=\"600\">https://example.org/alpha_small.png</image>\n"
     "    </screenshot>\n"
     "    <screenshot>\n"
+    "      <caption>Second screenshot</caption>\n"
     "      <image type=\"source\" width=\"1916\" "
     "height=\"1056\">https://example.org/beta.png</image>\n"
     "      <image type=\"thumbnail\" width=\"800\" "
@@ -1259,6 +1260,7 @@ static const gchar *xmldata_screenshots =
     "      <image type=\"source\" xml:lang=\"de-DE\">https://example.org/localized_de.png</image>\n"
     "    </screenshot>\n"
     "    <screenshot>\n"
+    "      <caption>Screencast</caption>\n"
     "      <video codec=\"av1\" container=\"matroska\" width=\"1916\" "
     "height=\"1056\">https://example.org/screencast.mkv</video>\n"
     "      <video codec=\"av1\" container=\"matroska\" width=\"1916\" height=\"1056\" xml:lang=\"de-DE\">https://example.org/screencast_de.mkv</video>\n"
@@ -1275,6 +1277,17 @@ static const gchar *xmldata_screenshots =
     "</component>\n";
 /* clang-format on */
 
+static void
+_assert_screenshot_captions_order (GPtrArray *screenshots, const gchar **captions)
+{
+	for (guint i = 0; captions[i] != NULL; i++) {
+		g_assert_cmpint (i, <, screenshots->len);
+		g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (screenshots, i)),
+				 ==,
+				 captions[i]);
+	}
+}
+
 /**
  * test_xml_read_screenshots:
  *
@@ -1422,30 +1435,43 @@ test_xml_read_screenshots (void)
 	g_assert_cmpint (as_image_get_width (img), ==, 640);
 	g_assert_cmpint (as_image_get_height (img), ==, 1136);
 
-	/* test some filtered loading */
+	/* test some screenshot sorting */
+	screenshots = as_component_get_screenshots_all (cpt);
 	as_component_set_context_locale (cpt, "C");
-	scr_filtered = as_component_filter_screenshots (cpt, "plasma", "mobile", TRUE);
-	g_assert_cmpint (scr_filtered->len, ==, 1);
-	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 0)),
-			 ==,
-			 "The app, on mobile!");
-	g_clear_pointer (&scr_filtered, g_ptr_array_unref);
-
-	scr_filtered = as_component_filter_screenshots (cpt, "plasma", NULL, TRUE);
-	g_assert_cmpint (scr_filtered->len, ==, 1);
-	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 0)),
-			 ==,
-			 "The app, on KDE Plasma desktop!");
-	g_clear_pointer (&scr_filtered, g_ptr_array_unref);
-
-	scr_filtered = as_component_filter_screenshots (cpt, "gnome", NULL, TRUE);
-	g_assert_cmpint (scr_filtered->len, ==, 3);
-	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 0)),
-			 ==,
-			 "The main window displaying a thing");
-	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 1)), ==, NULL);
-	g_assert_cmpstr (as_screenshot_get_caption (g_ptr_array_index (scr_filtered, 2)), ==, NULL);
-	g_clear_pointer (&scr_filtered, g_ptr_array_unref);
+	_assert_screenshot_captions_order (screenshots,
+					   (const gchar *[]){ "The main window displaying a thing",
+							      "Second screenshot",
+							      "Screencast",
+							      "The app, on mobile!",
+							      "The app, on KDE Plasma desktop!",
+							      NULL });
+
+	as_component_sort_screenshots (cpt, "plasma", "mobile", FALSE);
+	_assert_screenshot_captions_order (screenshots,
+					   (const gchar *[]){ "The app, on mobile!",
+							      "The app, on KDE Plasma desktop!",
+							      "The main window displaying a thing",
+							      "Second screenshot",
+							      "Screencast",
+							      NULL });
+
+	as_component_sort_screenshots (cpt, "plasma", NULL, FALSE);
+	_assert_screenshot_captions_order (screenshots,
+					   (const gchar *[]){ "The app, on KDE Plasma desktop!",
+							      "The app, on mobile!",
+							      "The main window displaying a thing",
+							      "Second screenshot",
+							      "Screencast",
+							      NULL });
+
+	as_component_sort_screenshots (cpt, "gnome", NULL, FALSE);
+	_assert_screenshot_captions_order (screenshots,
+					   (const gchar *[]){ "The main window displaying a thing",
+							      "Second screenshot",
+							      "Screencast",
+							      "The app, on mobile!",
+							      "The app, on KDE Plasma desktop!",
+							      NULL });
 
 	/* test a legacy screenshot entry that we briefly supported in an older AppStream release */
 	g_object_unref (cpt);
@@ -1507,6 +1533,7 @@ test_xml_write_screenshots (void)
 	g_object_unref (img);
 
 	scr2 = as_screenshot_new ();
+	as_screenshot_set_caption (scr2, "Second screenshot", "C");
 	img = as_image_new ();
 	as_image_set_kind (img, AS_IMAGE_KIND_SOURCE);
 	as_image_set_width (img, 1916);
@@ -1531,6 +1558,7 @@ test_xml_write_screenshots (void)
 	g_object_unref (img);
 
 	scr3 = as_screenshot_new ();
+	as_screenshot_set_caption (scr3, "Screencast", "C");
 	vid = as_video_new ();
 	as_video_set_codec_kind (vid, AS_VIDEO_CODEC_KIND_AV1);
 	as_video_set_container_kind (vid, AS_VIDEO_CONTAINER_KIND_MKV);

From 0eb99b907e0962d45437d6265ef891736ce8c0d3 Mon Sep 17 00:00:00 2001
From: Matthias Klumpp <matthias@tenstral.net>
Date: Wed, 27 Sep 2023 05:13:09 +0200
Subject: [PATCH 3/5] Autogenerate translatable DE and gui-environment-style C
 arrays

---
 data/desktop-env-header.tmpl  |  50 +++++++++++++
 data/desktop-environments.txt |  32 ++++----
 data/desktop-style-ids.txt    |  34 +++++----
 data/spdx-license-header.tmpl |   5 +-
 data/update-data.py           | 133 ++++++++++++++++++++++++----------
 src/appstream.gresource.xml   |   1 -
 src/as-category.c             |   2 +-
 src/as-desktop-env-data.h     | 110 ++++++++++++++++++++++++++++
 src/as-profile.c              |   2 +-
 src/as-utils.c                | 107 ++++++++++++++++++++++-----
 src/as-utils.h                |  62 ++++++++--------
 src/as-validator-issue-tag.h  |   4 +-
 src/meson.build               |   1 +
 tests/test-basics.c           |  83 +++++++++++++--------
 14 files changed, 473 insertions(+), 153 deletions(-)
 create mode 100644 data/desktop-env-header.tmpl
 create mode 100644 src/as-desktop-env-data.h

diff --git a/data/desktop-env-header.tmpl b/data/desktop-env-header.tmpl
new file mode 100644
index 000000000..4ae5c60f8
--- /dev/null
+++ b/data/desktop-env-header.tmpl
@@ -0,0 +1,50 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
+ *
+ * This file was automatically generated.
+ */
+
+#pragma once
+
+/* DO NOT EDIT THIS FILE MANUALLY! */
+
+/*
+ * Desktop environment names from: data/desktop-environments.txt
+ * Environment/Style names from:   data/desktop-style-ids.txt
+ */
+
+#include <glib/gi18n-lib.h>
+#include "as-macros-private.h"
+
+AS_BEGIN_PRIVATE_DECLS
+/* clang-format off */
+
+/**
+ * AsDesktopEnvData:
+ *
+ * Registered desktop environments.
+ */
+typedef struct {
+	const gchar	*id;
+	const gchar	*name;
+} AsDesktopEnvData;
+
+/**
+ * AsGUIEnvStyleData:
+ *
+ * Graphical environment/style IDs.
+ */
+typedef struct {
+	const gchar	*id;
+	const gchar	*name;
+} AsGUIEnvStyleData;
+
+AsDesktopEnvData as_desktop_env_data[] = {
+	@DE_DEFS@
+};
+
+AsGUIEnvStyleData as_gui_env_style_data[] = {
+	@GUI_ENV_STYLE_DEFS@
+};
+
+/* clang-format on */
+AS_END_PRIVATE_DECLS
diff --git a/data/desktop-environments.txt b/data/desktop-environments.txt
index 9797d97aa..caac41fcf 100644
--- a/data/desktop-environments.txt
+++ b/data/desktop-environments.txt
@@ -1,16 +1,18 @@
 # List of desktop environments
-GNOME
-KDE
-Plasma
-LXDE
-LXQt
-MATE
-Razor
-ROX
-Unity
-XFCE
-EDE
-Cinnamon
-Pantheon
-DDE
-Endless
+#
+# ID      Human-readable name
+Cinnamon  Cinnamon
+DDE       Deepin
+EDE       EDE
+Endless   Endless
+GNOME     GNOME
+KDE       KDE Plasma
+LXDE      LXDE
+LXQt      LXQt
+MATE      MATE
+Pantheon  Pantheon
+Plasma    KDE Plasma
+Razor     Razor
+ROX       ROX
+Unity     Unity
+XFCE      XFCE
diff --git a/data/desktop-style-ids.txt b/data/desktop-style-ids.txt
index 208667ce9..848b3357b 100644
--- a/data/desktop-style-ids.txt
+++ b/data/desktop-style-ids.txt
@@ -1,16 +1,18 @@
-# List of recognized GUI environment IDs
-cinnamon
-dde
-ede
-endless
-gnome
-kde
-lxde
-lxqt
-mate
-pantheon
-plasma
-razor
-rox
-unity
-xfce
+# List of recognized GUI environments
+# ID            Human-readable name
+#
+cinnamon    Cinnamon
+dde         Deepin
+ede         EDE
+endless     Endless
+gnome       GNOME
+gnome:dark  GNOME (Dark)
+lxde        LXDE
+lxqt        LXQt
+mate        Mate
+pantheon    Pantheon
+plasma      KDE Plasma
+razor       Razor
+rox         Rox
+unity       Unity
+xfce        Xfce
diff --git a/data/spdx-license-header.tmpl b/data/spdx-license-header.tmpl
index 0c6605442..89b06ae76 100644
--- a/data/spdx-license-header.tmpl
+++ b/data/spdx-license-header.tmpl
@@ -1,7 +1,6 @@
 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
  *
  * This file was automatically generated from SPDX metadata.
- *
  */
 
 #pragma once
@@ -13,8 +12,8 @@
  *   Exceptions: @EXCEPTION_LIST_VERSION@
  */
 
-#include <glib.h>
-#include <glib/gi18n.h>
+#include <glib/gi18n-lib.h>
+#include "as-macros-private.h"
 
 AS_BEGIN_PRIVATE_DECLS
 /* clang-format off */
diff --git a/data/update-data.py b/data/update-data.py
index d54acc82e..6cc0a18ba 100755
--- a/data/update-data.py
+++ b/data/update-data.py
@@ -110,9 +110,53 @@ def _read_dfsg_free_license_list():
     return licenses
 
 
+def _write_c_array_header(tmpl_fname, out_fname, l10n_keys=None, l10n_hints=None, **kwargs):
+    """Create a C header with lists based on a template."""
+
+    if not l10n_keys:
+        l10n_keys = set()
+    l10n_keys = set(l10n_keys)
+    if not l10n_hints:
+        l10n_hints = {}
+
+    with open(tmpl_fname, 'r') as f:
+        header = f.read()
+
+    for key, data in kwargs.items():
+        if isinstance(data, list):
+            if not data:
+                continue
+
+            array_def = ''
+            for entry in data:
+                entry_c = ''
+                if key in l10n_hints:
+                    v = list(entry.values())[0]
+                    entry_c += '\t/* TRANSLATORS: {} */\n'.format(l10n_hints[key].format(v))
+                entry_c += '\t{'
+                for k, v in entry.items():
+                    v = v.replace('"', '\\"')
+
+                    if k in l10n_keys:
+                        v_c = f'N_("{v}")'
+                    else:
+                        v_c = f'"{v}"'
+                    entry_c += f' {v_c},'
+                array_def += entry_c[:-1] + ' },\n'
+
+            zero_term = 'NULL, ' * len(data[0])
+            array_def += '\t{ ' + zero_term[:-2] + ' },\n'
+
+            header = header.replace(f'@{key}@', array_def.strip())
+        else:
+            header = header.replace(f'@{key}@', str(data))
+
+    with open(out_fname, 'w') as f:
+        f.write(header)
+
+
 def update_spdx_id_list(
     git_url,
-    header_template_fname,
     licenselist_header_fname,
     licenselist_free_fname,
     with_deprecated=True,
@@ -133,30 +177,15 @@ def update_spdx_id_list(
     exception_list = license_data['exceptions']
     license_list_ver = license_data['license_list_ver']
 
-    with open(header_template_fname, 'r') as f:
-        header_tmpl = f.read()
-
-    with open(licenselist_header_fname, 'w') as f:
-        lic_array_def = ''
-        exc_array_def = ''
-        for license in license_list:
-            lic_id = license['id'].replace('"', '\\"')
-            lic_name = license['name'].replace('"', '\\"')
-            lic_array_def += f'\t{{"{lic_id}", N_("{lic_name}")}},\n'
-        for exception in exception_list:
-            exc_id = exception['id'].replace('"', '\\"')
-            exc_name = exception['name'].replace('"', '\\"')
-            exc_array_def += f'\t{{"{exc_id}", N_("{exc_name}")}},\n'
-
-        lic_array_def += f'\t{{NULL, NULL}}'
-        exc_array_def += f'\t{{NULL, NULL}}'
-
-        header = header_tmpl.replace('@LICENSE_INFO_DEFS@', lic_array_def.strip())
-        header = header.replace('@EXCEPTION_INFO_DEFS@', exc_array_def.strip())
-        header = header.replace('@LICENSE_LIST_VERSION@', license_list_ver)
-        header = header.replace('@EXCEPTION_LIST_VERSION@', license_data['exception_list_ver'])
-
-        f.write(header)
+    _write_c_array_header(
+        'spdx-license-header.tmpl',
+        licenselist_header_fname,
+        ['name'],
+        LICENSE_INFO_DEFS=license_list,
+        EXCEPTION_INFO_DEFS=exception_list,
+        LICENSE_LIST_VERSION=license_list_ver,
+        EXCEPTION_LIST_VERSION=license_data['exception_list_ver'],
+    )
 
     license_free_data = _read_spdx_licenses(tdir.name, last_tag_ver, only_free=True)
     with open(licenselist_free_fname, 'w') as f:
@@ -216,35 +245,66 @@ def update_categories_list(spec_url, cat_fname):
         f.write('\n')
 
 
-def update_gui_env_ids():
+def update_gui_env_ids(data_header_fname):
     print('Updating GUI environment IDs...')
 
-    desktop_envs = set()
+    desktops_list = []
+    desktops_set = set()
     with open('desktop-environments.txt', 'r') as f:
         for line in f.readlines():
             if line.startswith('#'):
                 continue
-            desktop_envs.add(line.strip().lower())
+            de_id, de_name = line.strip().split(' ', 1)
+            de_id = de_id.strip()
+            if not de_id:
+                continue
+            desktops_set.add(de_id.lower())
+            desktops_list.append({'id': de_id, 'name': de_name.strip()})
 
     # fixup
-    desktop_envs.remove('kde')
-    desktop_envs.add('plasma')
+    desktops_set.remove('kde')
+    desktops_set.add('plasma')
 
-    # extend the existing list
+    # extend the existing styles list
     gui_env_ids = set()
+    gui_env_list = []
+    gui_envs_raw = []
     with open('desktop-style-ids.txt', 'r') as f:
         for line in f.readlines():
             if line.startswith('#'):
                 continue
-            gui_env_ids.add(line.strip().lower())
+            line = line.strip()
+            gui_envs_raw.append(line)
+            es_id, es_name = line.split(' ', 1)
+            es_id = es_id.strip().lower()
+            if not de_id:
+                continue
+            gui_env_ids.add(es_id)
+            gui_env_list.append({'id': es_id, 'name': es_name.strip()})
 
-    gui_env_ids.update(desktop_envs)
+    for de_id in desktops_set:
+        if de_id not in gui_env_ids:
+            gui_envs_raw.append(f'{de_id}    {de_id.capitalize()}')
 
     with open('desktop-style-ids.txt', 'w') as f:
-        f.write('# List of recognized GUI environment IDs\n')
-        f.write('\n'.join(sorted(gui_env_ids)))
+        f.write('# List of recognized GUI environments\n')
+        f.write('# ID            Human-readable name\n#\n')
+        f.write('\n'.join(sorted(gui_envs_raw)))
         f.write('\n')
 
+    # write C header with all data
+    _write_c_array_header(
+        'desktop-env-header.tmpl',
+        data_header_fname,
+        ['name'],
+        l10n_hints={
+            'DE_DEFS': 'Name of the "{}" desktop environment.',
+            'GUI_ENV_STYLE_DEFS': 'Name of the "{}" visual environment style.',
+        },
+        DE_DEFS=desktops_list,
+        GUI_ENV_STYLE_DEFS=gui_env_list,
+    )
+
 
 def main():
     data_dir = os.path.dirname(os.path.abspath(__file__))
@@ -254,13 +314,12 @@ def main():
     update_tld_list(IANA_TLD_LIST_URL, 'iana-filtered-tld-list.txt')
     update_spdx_id_list(
         SPDX_REPO_URL,
-        os.path.join(data_dir, 'spdx-license-header.tmpl'),
         '../src/as-spdx-data.h',
         'spdx-free-license-ids.txt',
     )
     update_categories_list(MENU_SPEC_URL, 'xdg-category-names.txt')
     update_platforms_data()
-    update_gui_env_ids()
+    update_gui_env_ids('../src/as-desktop-env-data.h')
 
     print('All done.')
 
diff --git a/src/appstream.gresource.xml b/src/appstream.gresource.xml
index 39a188076..1775c0df7 100644
--- a/src/appstream.gresource.xml
+++ b/src/appstream.gresource.xml
@@ -3,7 +3,6 @@
  <gresource prefix="/org/freedesktop/appstream">
   <file>xdg-category-names.txt</file>
   <file>iana-filtered-tld-list.txt</file>
-  <file>desktop-environments.txt</file>
   <file>spdx-free-license-ids.txt</file>
   <file>platform_arch.txt</file>
   <file>platform_os.txt</file>
diff --git a/src/as-category.c b/src/as-category.c
index 3f9472c27..ea407ac5a 100644
--- a/src/as-category.c
+++ b/src/as-category.c
@@ -23,7 +23,7 @@
 #include "as-category-gi.h"
 
 #include "config.h"
-#include <glib/gi18n.h>
+#include <glib/gi18n-lib.h>
 #include <glib.h>
 
 #include "as-component.h"
diff --git a/src/as-desktop-env-data.h b/src/as-desktop-env-data.h
new file mode 100644
index 000000000..17ea68681
--- /dev/null
+++ b/src/as-desktop-env-data.h
@@ -0,0 +1,110 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
+ *
+ * This file was automatically generated.
+ */
+
+#pragma once
+
+/* DO NOT EDIT THIS FILE MANUALLY! */
+
+/*
+ * Desktop environment names from: data/desktop-environments.txt
+ * Environment/Style names from:   data/desktop-style-ids.txt
+ */
+
+#include <glib/gi18n-lib.h>
+#include "as-macros-private.h"
+
+AS_BEGIN_PRIVATE_DECLS
+/* clang-format off */
+
+/**
+ * AsDesktopEnvData:
+ *
+ * Registered desktop environments.
+ */
+typedef struct {
+	const gchar	*id;
+	const gchar	*name;
+} AsDesktopEnvData;
+
+/**
+ * AsGUIEnvStyleData:
+ *
+ * Graphical environment/style IDs.
+ */
+typedef struct {
+	const gchar	*id;
+	const gchar	*name;
+} AsGUIEnvStyleData;
+
+AsDesktopEnvData as_desktop_env_data[] = {
+	/* TRANSLATORS: Name of the "Cinnamon" desktop environment. */
+	{ "Cinnamon", N_("Cinnamon") },
+	/* TRANSLATORS: Name of the "DDE" desktop environment. */
+	{ "DDE", N_("Deepin") },
+	/* TRANSLATORS: Name of the "EDE" desktop environment. */
+	{ "EDE", N_("EDE") },
+	/* TRANSLATORS: Name of the "Endless" desktop environment. */
+	{ "Endless", N_("Endless") },
+	/* TRANSLATORS: Name of the "GNOME" desktop environment. */
+	{ "GNOME", N_("GNOME") },
+	/* TRANSLATORS: Name of the "KDE" desktop environment. */
+	{ "KDE", N_("KDE Plasma") },
+	/* TRANSLATORS: Name of the "LXDE" desktop environment. */
+	{ "LXDE", N_("LXDE") },
+	/* TRANSLATORS: Name of the "LXQt" desktop environment. */
+	{ "LXQt", N_("LXQt") },
+	/* TRANSLATORS: Name of the "MATE" desktop environment. */
+	{ "MATE", N_("MATE") },
+	/* TRANSLATORS: Name of the "Pantheon" desktop environment. */
+	{ "Pantheon", N_("Pantheon") },
+	/* TRANSLATORS: Name of the "Plasma" desktop environment. */
+	{ "Plasma", N_("KDE Plasma") },
+	/* TRANSLATORS: Name of the "Razor" desktop environment. */
+	{ "Razor", N_("Razor") },
+	/* TRANSLATORS: Name of the "ROX" desktop environment. */
+	{ "ROX", N_("ROX") },
+	/* TRANSLATORS: Name of the "Unity" desktop environment. */
+	{ "Unity", N_("Unity") },
+	/* TRANSLATORS: Name of the "XFCE" desktop environment. */
+	{ "XFCE", N_("XFCE") },
+	{ NULL, NULL },
+};
+
+AsGUIEnvStyleData as_gui_env_style_data[] = {
+	/* TRANSLATORS: Name of the "cinnamon" visual environment style. */
+	{ "cinnamon", N_("Cinnamon") },
+	/* TRANSLATORS: Name of the "dde" visual environment style. */
+	{ "dde", N_("Deepin") },
+	/* TRANSLATORS: Name of the "ede" visual environment style. */
+	{ "ede", N_("EDE") },
+	/* TRANSLATORS: Name of the "endless" visual environment style. */
+	{ "endless", N_("Endless") },
+	/* TRANSLATORS: Name of the "gnome" visual environment style. */
+	{ "gnome", N_("GNOME") },
+	/* TRANSLATORS: Name of the "gnome:dark" visual environment style. */
+	{ "gnome:dark", N_("GNOME (Dark)") },
+	/* TRANSLATORS: Name of the "lxde" visual environment style. */
+	{ "lxde", N_("LXDE") },
+	/* TRANSLATORS: Name of the "lxqt" visual environment style. */
+	{ "lxqt", N_("LXQt") },
+	/* TRANSLATORS: Name of the "mate" visual environment style. */
+	{ "mate", N_("Mate") },
+	/* TRANSLATORS: Name of the "pantheon" visual environment style. */
+	{ "pantheon", N_("Pantheon") },
+	/* TRANSLATORS: Name of the "plasma" visual environment style. */
+	{ "plasma", N_("KDE Plasma") },
+	/* TRANSLATORS: Name of the "razor" visual environment style. */
+	{ "razor", N_("Razor") },
+	/* TRANSLATORS: Name of the "rox" visual environment style. */
+	{ "rox", N_("Rox") },
+	/* TRANSLATORS: Name of the "unity" visual environment style. */
+	{ "unity", N_("Unity") },
+	/* TRANSLATORS: Name of the "xfce" visual environment style. */
+	{ "xfce", N_("Xfce") },
+	{ NULL, NULL },
+};
+
+/* clang-format on */
+AS_END_PRIVATE_DECLS
diff --git a/src/as-profile.c b/src/as-profile.c
index a07eab0ce..bfabeac04 100644
--- a/src/as-profile.c
+++ b/src/as-profile.c
@@ -20,7 +20,7 @@
 
 #include "config.h"
 
-#include <glib/gi18n.h>
+#include <glib/gi18n-lib.h>
 
 #include "as-profile.h"
 
diff --git a/src/as-utils.c b/src/as-utils.c
index d7c57db48..8216af01e 100644
--- a/src/as-utils.c
+++ b/src/as-utils.c
@@ -28,7 +28,6 @@
 #include <stdlib.h>
 #include <gio/gio.h>
 #include <glib/gstdio.h>
-#include <glib/gi18n-lib.h>
 #include <sys/types.h>
 #include <libxml/tree.h>
 #include <libxml/parser.h>
@@ -47,6 +46,7 @@
 #include "as-category.h"
 #include "as-metadata.h"
 #include "as-component-private.h"
+#include "as-desktop-env-data.h"
 
 /**
  * SECTION:as-utils
@@ -1357,32 +1357,105 @@ as_utils_is_tld (const gchar *tld)
 
 /**
  * as_utils_is_desktop_environment:
- * @desktop: a desktop environment id.
+ * @de_id: a desktop environment id.
  *
- * Searches the known list of desktop environments AppStream
- * knows about.
+ * Checks if the submitted desktop environment ID is
+ * known and valid.
  *
  * Returns: %TRUE if the desktop-id is valid
  *
  * Since: 0.10.0
  **/
 gboolean
-as_utils_is_desktop_environment (const gchar *desktop)
+as_utils_is_desktop_environment (const gchar *de_id)
 {
-	g_autoptr(GBytes) data = NULL;
-	g_autofree gchar *key = NULL;
-	GResource *resource = as_get_resource ();
-	g_assert (resource != NULL);
+	/* handle invalid */
+	if (de_id == NULL || de_id[0] == '\0')
+		return FALSE;
 
-	/* load the readonly data section and look for the desktop environment name */
-	data = g_resource_lookup_data (resource,
-				       "/org/freedesktop/appstream/desktop-environments.txt",
-				       G_RESOURCE_LOOKUP_FLAGS_NONE,
-				       NULL);
-	if (data == NULL)
+	for (guint i = 0; as_desktop_env_data[i].id != NULL; i++) {
+		if (as_str_equal0 (as_desktop_env_data[i].id, de_id))
+			return TRUE;
+	}
+
+	return FALSE;
+}
+
+/**
+ * as_utils_get_desktop_environment_name:
+ * @de_id: a desktop environment id.
+ *
+ * Get a human-readable, translated name of the desktop environment
+ * represented by the given ID.
+ *
+ * Returns: A localized name of the DE, or %NULL if none available.
+ *
+ * Since: 1.0.0
+ **/
+const gchar *
+as_utils_get_desktop_environment_name (const gchar *de_id)
+{
+	/* handle invalid */
+	if (de_id == NULL || de_id[0] == '\0')
+		return NULL;
+
+	for (guint i = 0; as_desktop_env_data[i].id != NULL; i++) {
+		if (as_str_equal0 (as_desktop_env_data[i].id, de_id))
+			return as_desktop_env_data[i].name;
+	}
+
+	return NULL;
+}
+
+/**
+ * as_utils_is_gui_environment_style:
+ * @env_style: a GUI environment style ID, e.g. "pantheon:dark"
+ *
+ * Checks if the given identifier is a valid, known GUI environment style.
+ *
+ * Returns: %TRUE if the environment-style ID is is valid
+ *
+ * Since: 1.0.0
+ **/
+gboolean
+as_utils_is_gui_environment_style (const gchar *env_style)
+{
+	/* handle invalid */
+	if (env_style == NULL || env_style[0] == '\0')
 		return FALSE;
-	key = g_strdup_printf ("\n%s\n", desktop);
-	return g_strstr_len (g_bytes_get_data (data, NULL), -1, key) != NULL;
+
+	for (guint i = 0; as_gui_env_style_data[i].id != NULL; i++) {
+		if (as_str_equal0 (as_gui_env_style_data[i].id, env_style))
+			return TRUE;
+	}
+
+	return FALSE;
+}
+
+/**
+ * as_utils_get_gui_environment_style_name:
+ * @env_style: a GUI environment style ID, e.g. "pantheon:dark"
+ *
+ * Get a human-readable, translated name of the combination
+ * of GUI environment and style. E.g. "plasma:dark" becomes "Plasma (Dark)".
+ *
+ * Returns: A localized name of the environment style, or %NULL if none available.
+ *
+ * Since: 1.0.0
+ **/
+const gchar *
+as_utils_get_gui_environment_style_name (const gchar *env_style)
+{
+	/* handle invalid */
+	if (env_style == NULL || env_style[0] == '\0')
+		return NULL;
+
+	for (guint i = 0; as_gui_env_style_data[i].id != NULL; i++) {
+		if (as_str_equal0 (as_gui_env_style_data[i].id, env_style))
+			return as_gui_env_style_data[i].name;
+	}
+
+	return NULL;
 }
 
 /**
diff --git a/src/as-utils.h b/src/as-utils.h
index f6e817f70..c736a65a3 100644
--- a/src/as-utils.h
+++ b/src/as-utils.h
@@ -84,35 +84,39 @@ typedef enum {
 	AS_METADATA_LOCATION_LAST
 } AsMetadataLocation;
 
-GQuark	 as_utils_error_quark (void);
-
-gchar  **as_markup_strsplit_words (const gchar *text, guint line_len);
-gchar	*as_markup_convert_simple (const gchar *markup, GError **error);
-
-gboolean as_utils_locale_is_compatible (const gchar *locale1, const gchar *locale2);
-gchar	*as_utils_posix_locale_to_bcp47 (const gchar *locale);
-
-gboolean as_utils_is_category_name (const gchar *category_name);
-gboolean as_utils_is_tld (const gchar *tld);
-gboolean as_utils_is_desktop_environment (const gchar *desktop);
-
-void	 as_utils_sort_components_into_categories (GPtrArray *cpts,
-						   GPtrArray *categories,
-						   gboolean   check_duplicates);
-
-gchar	*as_utils_build_data_id (AsComponentScope scope,
-				 AsBundleKind	  bundle_kind,
-				 const gchar	 *origin,
-				 const gchar	 *cid,
-				 const gchar	 *branch);
-gboolean as_utils_data_id_valid (const gchar *data_id);
-gchar	*as_utils_data_id_get_cid (const gchar *data_id);
-
-gboolean as_utils_data_id_match (const gchar	   *data_id1,
-				 const gchar	   *data_id2,
-				 AsDataIdMatchFlags match_flags);
-gboolean as_utils_data_id_equal (const gchar *data_id1, const gchar *data_id2);
-guint	 as_utils_data_id_hash (const gchar *data_id);
+GQuark	     as_utils_error_quark (void);
+
+gchar	   **as_markup_strsplit_words (const gchar *text, guint line_len);
+gchar	    *as_markup_convert_simple (const gchar *markup, GError **error);
+
+gboolean     as_utils_locale_is_compatible (const gchar *locale1, const gchar *locale2);
+gchar	    *as_utils_posix_locale_to_bcp47 (const gchar *locale);
+
+gboolean     as_utils_is_category_name (const gchar *category_name);
+gboolean     as_utils_is_tld (const gchar *tld);
+
+gboolean     as_utils_is_desktop_environment (const gchar *de_id);
+const gchar *as_utils_get_desktop_environment_name (const gchar *de_id);
+gboolean     as_utils_is_gui_environment_style (const gchar *env_style);
+const gchar *as_utils_get_gui_environment_style_name (const gchar *env_style);
+
+void	     as_utils_sort_components_into_categories (GPtrArray *cpts,
+						       GPtrArray *categories,
+						       gboolean	  check_duplicates);
+
+gchar	    *as_utils_build_data_id (AsComponentScope scope,
+				     AsBundleKind     bundle_kind,
+				     const gchar     *origin,
+				     const gchar     *cid,
+				     const gchar     *branch);
+gboolean     as_utils_data_id_valid (const gchar *data_id);
+gchar	    *as_utils_data_id_get_cid (const gchar *data_id);
+
+gboolean     as_utils_data_id_match (const gchar       *data_id1,
+				     const gchar       *data_id2,
+				     AsDataIdMatchFlags match_flags);
+gboolean     as_utils_data_id_equal (const gchar *data_id1, const gchar *data_id2);
+guint	     as_utils_data_id_hash (const gchar *data_id);
 
 guint	 as_gstring_replace (GString *string, const gchar *find, const gchar *replace, guint limit);
 
diff --git a/src/as-validator-issue-tag.h b/src/as-validator-issue-tag.h
index 171685902..111918ac9 100644
--- a/src/as-validator-issue-tag.h
+++ b/src/as-validator-issue-tag.h
@@ -21,8 +21,8 @@
 #ifndef __AS_VALIDATOR_ISSUE_TAG_H
 #define __AS_VALIDATOR_ISSUE_TAG_H
 
-#include <glib.h>
-#include <glib/gi18n.h>
+#include "config.h"
+#include <glib/gi18n-lib.h>
 
 #include "as-validator-issue.h"
 
diff --git a/src/meson.build b/src/meson.build
index 4d8919898..67c999c73 100644
--- a/src/meson.build
+++ b/src/meson.build
@@ -106,6 +106,7 @@ aslib_priv_headers = [
     'as-context-private.h',
     'as-curl.h',
     'as-desktop-entry.h',
+    'as-desktop-env-data.h',
     'as-distro-extras.h',
     'as-file-monitor.h',
     'as-icon-private.h',
diff --git a/tests/test-basics.c b/tests/test-basics.c
index c9cadd861..4dab46e8b 100644
--- a/tests/test-basics.c
+++ b/tests/test-basics.c
@@ -605,6 +605,24 @@ test_spdx (void)
 	g_free (tmp);
 }
 
+/**
+ * test_desktop_env:
+ *
+ * Test desktop environment and style validation.
+ */
+static void
+test_desktop_env (void)
+{
+	g_assert_false (as_utils_is_desktop_environment (NULL));
+	g_assert_false (as_utils_is_desktop_environment ("Linux"));
+	g_assert_true (as_utils_is_desktop_environment ("GNOME"));
+
+	g_assert_false (as_utils_is_gui_environment_style (NULL));
+	g_assert_false (as_utils_is_gui_environment_style ("Linux"));
+	g_assert_true (as_utils_is_gui_environment_style ("plasma"));
+	g_assert_true (as_utils_is_gui_environment_style ("gnome:dark"));
+}
+
 /**
  * test_read_desktop_entry_simple:
  *
@@ -1020,43 +1038,45 @@ test_content_rating_mappings (void)
 static void
 as_test_content_rating_from_locale (void)
 {
+	/* clang-format off */
 	const struct {
 		const gchar *locale;
 		AsContentRatingSystem expected_system;
 	} vectors[] = {
-	/* Simple tests to get coverage of each rating system: */
-		{"es_AR",		   AS_CONTENT_RATING_SYSTEM_INCAA },
-		{ "en_AU",		   AS_CONTENT_RATING_SYSTEM_ACB	},
-		{ "pt_BR",		   AS_CONTENT_RATING_SYSTEM_DJCTQ },
-		{ "zh_TW",		   AS_CONTENT_RATING_SYSTEM_GSRR	 },
-		{ "en_GB",		   AS_CONTENT_RATING_SYSTEM_PEGI	 },
-		{ "hy_AM",		   AS_CONTENT_RATING_SYSTEM_PEGI	 },
-		{ "bg_BG",		   AS_CONTENT_RATING_SYSTEM_PEGI	 },
-		{ "fi_FI",		   AS_CONTENT_RATING_SYSTEM_KAVI	 },
-		{ "de_DE",		   AS_CONTENT_RATING_SYSTEM_USK	},
-		{ "az_IR",		   AS_CONTENT_RATING_SYSTEM_ESRA	 },
-		{ "jp_JP",		   AS_CONTENT_RATING_SYSTEM_CERO	 },
-		{ "en_NZ",		   AS_CONTENT_RATING_SYSTEM_OFLCNZ},
-		{ "ru_RU",		   AS_CONTENT_RATING_SYSTEM_RUSSIA},
-		{ "en_SQ",		   AS_CONTENT_RATING_SYSTEM_MDA	},
-		{ "ko_KR",		   AS_CONTENT_RATING_SYSTEM_GRAC	 },
-		{ "en_US",		   AS_CONTENT_RATING_SYSTEM_ESRB	 },
-		{ "en_US",		   AS_CONTENT_RATING_SYSTEM_ESRB	 },
-		{ "en_CA",		   AS_CONTENT_RATING_SYSTEM_ESRB	 },
-		{ "es_MX",		   AS_CONTENT_RATING_SYSTEM_ESRB	 },
- /* Fallback (arbitrarily chosen Venezuela since it seems to use IARC): */
-		{ "es_VE",		   AS_CONTENT_RATING_SYSTEM_IARC	 },
- /* Locale with a codeset: */
-		{ "nl_NL.iso88591",	    AS_CONTENT_RATING_SYSTEM_PEGI  },
- /* Locale with a codeset and modifier: */
+		/* Simple tests to get coverage of each rating system: */
+		{ "es_AR",		  AS_CONTENT_RATING_SYSTEM_INCAA },
+		{ "en_AU",		  AS_CONTENT_RATING_SYSTEM_ACB	},
+		{ "pt_BR",		  AS_CONTENT_RATING_SYSTEM_DJCTQ },
+		{ "zh_TW",		  AS_CONTENT_RATING_SYSTEM_GSRR },
+		{ "en_GB",		  AS_CONTENT_RATING_SYSTEM_PEGI },
+		{ "hy_AM",		  AS_CONTENT_RATING_SYSTEM_PEGI },
+		{ "bg_BG",		  AS_CONTENT_RATING_SYSTEM_PEGI },
+		{ "fi_FI",		  AS_CONTENT_RATING_SYSTEM_KAVI },
+		{ "de_DE",		  AS_CONTENT_RATING_SYSTEM_USK	},
+		{ "az_IR",		  AS_CONTENT_RATING_SYSTEM_ESRA },
+		{ "jp_JP",		  AS_CONTENT_RATING_SYSTEM_CERO },
+		{ "en_NZ",		  AS_CONTENT_RATING_SYSTEM_OFLCNZ },
+		{ "ru_RU",		  AS_CONTENT_RATING_SYSTEM_RUSSIA },
+		{ "en_SQ",		  AS_CONTENT_RATING_SYSTEM_MDA	},
+		{ "ko_KR",		  AS_CONTENT_RATING_SYSTEM_GRAC },
+		{ "en_US",		  AS_CONTENT_RATING_SYSTEM_ESRB },
+		{ "en_US",		  AS_CONTENT_RATING_SYSTEM_ESRB },
+		{ "en_CA",		  AS_CONTENT_RATING_SYSTEM_ESRB },
+		{ "es_MX",		  AS_CONTENT_RATING_SYSTEM_ESRB },
+		/* Fallback (arbitrarily chosen Venezuela since it seems to use IARC): */
+		{ "es_VE",		  AS_CONTENT_RATING_SYSTEM_IARC },
+		/* Locale with a codeset: */
+		{ "nl_NL.iso88591",	  AS_CONTENT_RATING_SYSTEM_PEGI },
+		/* Locale with a codeset and modifier: */
 		{ "nl_NL.iso885915@euro", AS_CONTENT_RATING_SYSTEM_PEGI	},
- /* Locale with a less esoteric codeset: */
-		{ "en_GB.UTF-8",		 AS_CONTENT_RATING_SYSTEM_PEGI  },
- /* Locale with a modifier but no codeset: */
-		{ "fi_FI@euro",		AS_CONTENT_RATING_SYSTEM_KAVI  },
- /* Invalid locale: */
-		{ "_invalid",	      AS_CONTENT_RATING_SYSTEM_IARC  },
+		/* Locale with a less esoteric codeset: */
+		{ "en_GB.UTF-8",	  AS_CONTENT_RATING_SYSTEM_PEGI },
+		/* Locale with a modifier but no codeset: */
+		{ "fi_FI@euro",		  AS_CONTENT_RATING_SYSTEM_KAVI },
+		/* Invalid locale: */
+		{ "_invalid",		  AS_CONTENT_RATING_SYSTEM_IARC },
 	};
+	/* clang-format on */
 
 	for (gsize i = 0; i < G_N_ELEMENTS (vectors); i++) {
 		g_test_message ("Test %" G_GSIZE_FORMAT ": %s", i, vectors[i].locale);
@@ -1210,6 +1230,7 @@ main (int argc, char **argv)
 	g_test_add_func ("/AppStream/Component", test_component);
 	g_test_add_func ("/AppStream/ComponentBox", test_component_box);
 	g_test_add_func ("/AppStream/SPDX", test_spdx);
+	g_test_add_func ("/AppStream/DesktopEnv", test_desktop_env);
 	g_test_add_func ("/AppStream/TranslationFallback", test_translation_fallback);
 	g_test_add_func ("/AppStream/LocaleCompat", test_locale_compat);
 	g_test_add_func ("/AppStream/ReadDesktopEntry", test_read_desktop_entry_simple);

From 4fd4ca50326e27569f733a439f09ce95c0697c90 Mon Sep 17 00:00:00 2001
From: Matthias Klumpp <matthias@tenstral.net>
Date: Wed, 27 Sep 2023 22:09:02 +0200
Subject: [PATCH 4/5] validator: Check screenshot environment property

---
 src/as-validator-issue-tag.h | 6 ++++++
 src/as-validator.c           | 9 +++++++++
 2 files changed, 15 insertions(+)

diff --git a/src/as-validator-issue-tag.h b/src/as-validator-issue-tag.h
index 111918ac9..543dc5005 100644
--- a/src/as-validator-issue-tag.h
+++ b/src/as-validator-issue-tag.h
@@ -205,6 +205,12 @@ AsValidatorIssueTag as_validator_issue_tag_list[] =  {
 	  N_("The update-contact does not appear to be a valid email address (escaping of `@` is only allowed as `_at_` or `_AT_`).")
 	},
 
+	{ "screenshot-invalid-env-style",
+	  AS_ISSUE_SEVERITY_WARNING,
+	  /* TRANSLATORS: Please do not translate AppStream tag/property names (in backticks). */
+	  N_("The `environment` property is set to an unrecognized graphical environment/style combination.")
+	},
+
 	{ "screenshot-invalid-width",
 	  AS_ISSUE_SEVERITY_WARNING,
 	  /* TRANSLATORS: Please do not translate AppStream tag/property names (in backticks). */
diff --git a/src/as-validator.c b/src/as-validator.c
index 90a34d0a0..f764a2ee2 100644
--- a/src/as-validator.c
+++ b/src/as-validator.c
@@ -1448,6 +1448,7 @@ as_validator_check_screenshots (AsValidator *validator, xmlNode *node, AsCompone
 		gboolean caption_found = FALSE;
 		gboolean is_default_screenshot = FALSE;
 		g_autofree gchar *scr_kind_str = NULL;
+		g_autofree gchar *scr_env_style = NULL;
 		gboolean have_source_image = FALSE;
 		g_autoptr(GHashTable) known_source_locale = NULL;
 
@@ -1462,6 +1463,14 @@ as_validator_check_screenshots (AsValidator *validator, xmlNode *node, AsCompone
 			is_default_screenshot = TRUE;
 		}
 
+		scr_env_style = as_xml_get_prop_value (iter, "environment");
+		if (scr_env_style != NULL && !as_utils_is_gui_environment_style (scr_env_style)) {
+			as_validator_add_issue (validator,
+						iter,
+						"screenshot-invalid-env-style",
+						scr_env_style);
+		}
+
 		if (g_strcmp0 ((const gchar *) iter->name, "screenshot") != 0) {
 			as_validator_add_issue (
 			    validator,

From 4d8567d1dbc8d11d55c23105323f6d4194d06131 Mon Sep 17 00:00:00 2001
From: Matthias Klumpp <matthias@tenstral.net>
Date: Wed, 27 Sep 2023 23:41:07 +0200
Subject: [PATCH 5/5] docs: Clarify environment-based screenshot ordering

---
 docs/xml/metainfo-component.xml | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/docs/xml/metainfo-component.xml b/docs/xml/metainfo-component.xml
index 893d396ce..a9c22b672 100644
--- a/docs/xml/metainfo-component.xml
+++ b/docs/xml/metainfo-component.xml
@@ -1203,30 +1203,31 @@
 		</para>
 		<para>
 			The <code>&lt;screenshots/&gt;</code> tag contains multiple <code>&lt;screenshot/&gt;</code> children, where at least one of them must have the property
-			<code>type="default"</code> to indicate the primary screenshot of the software. Every <code>&lt;screenshot/&gt;</code> tag must have at least
-			one <code>&lt;image/&gt;</code> <emphasis>or</emphasis> <code>&lt;video/&gt;</code> child, but never an <literal>image</literal> <emphasis>and</emphasis>
-			<literal>video</literal> at the same time.
-		</para>
-		<para>
-			Screenshots containing videos must not be the default screenshot.
+			<code>type="default"</code> to indicate the primary and most representative screenshot of the software.
 		</para>
 		<para>
 			Optionally, a <literal>screenshot</literal> may also have an <code>environment</code> property.
-			This string property denotes the GUI environment the screenshot was recorded in, in the form of <code>&lt;env&gt;:&lt;style&gt;</code>,
-			where <literal>env</literal> is a desktop-environment name in lowercase
-			and <literal>style</literal> is a specific style that the desktop environment recognizes, e.g. <code>light</code> and <code>dark</code> for light
-			and dark themes. See <ulink url="https://github.com/ximion/appstream/blob/main/data/desktop-style-ids.txt">desktop-style-ids.txt</ulink> for a list
+			This string property denotes the GUI environment the screenshot was recorded in, in the form of <code>{env}:{style}</code>,
+			where <literal>{env}</literal> is a desktop-environment name in lowercase and <literal>{style}</literal> is a specific style
+			that the desktop environment recognizes, e.g. <code>light</code> and <code>dark</code> for light and dark themes.
+			See <ulink url="https://github.com/ximion/appstream/blob/main/data/desktop-style-ids.txt">desktop-style-ids.txt</ulink> for a list
 			of currently recognized environment and style combinations.
 		</para>
 		<para>
-			Software centers displaying the component will prefer screenshots of the current environment and style first, will then fall back to
-			screenshots of the current environment (without style), and if none of those are available either they will use the environment of the
-			screenshot marked as <code>type="default"</code> (which may be intentionally empty).
-			That way, there will always be a screenshot displayed.
+			Software centers displaying the component will usually prefer screenshots of the current environment and style, and display them first,
+			even before the screenshot marked as <literal>default</literal>.
 		</para>
 		<para>
 			In general, screenshots should be displayed in the order the are defined in in their <literal>screenshots</literal> block
-			for the respective component.
+			for the respective component on a per-environment basis (all screenshots of the same environment/style will be displayed in the order
+			they are listed in the XML, but may be moved to the front of the list as a whole depending on the current environment).
+		</para>
+		<para>
+			Every <code>&lt;screenshot/&gt;</code> element must have at least one <code>&lt;image/&gt;</code> <emphasis>or</emphasis> <code>&lt;video/&gt;</code> child,
+			but never an <literal>image</literal> <emphasis>and</emphasis> <literal>video</literal> at the same time.
+		</para>
+		<para>
+			Screenshots containing videos must not be the default screenshot.
 		</para>
 		<para>
 			The value of the <code>&lt;image/&gt;</code> tag is a direct HTTP/HTTPS URL to a screenshot uploaded to a public location on the web.