@gjsify/site 0.64.24 → 0.64.26-next.312

package/README.md

@@ -281,6 +281,37 @@ Two things happen to the artwork:
 The `<picture>` carries AVIF, WebP and PNG, each with a `srcset` of 640px, 1280px and 2560px
 renditions up to the source's own width.
 
+#### Language and colour scheme
+
+The metainfo stays the only source; the standard AppStream 1.0 attributes pick the rendition:
+
+```xml
+<screenshot type="default">
+  <image type="source">https://…/list.png</image>
+  <image type="source" xml:lang="de">https://…/list-de.png</image>
+</screenshot>
+<screenshot environment="gnome:dark">
+  <image type="source">https://…/list-dark.png</image>
+  <image type="source" xml:lang="de">https://…/list-dark-de.png</image>
+</screenshot>
+```
+
+- An `<image xml:lang="…">` is the translation of the untagged image. The `/<lang>/` page shows the
+  image of its language and falls back to the untagged one.
+- A `<screenshot>` whose `environment` ends in `:dark` is the dark twin of a light one: the n-th
+  dark screenshot pairs with the n-th non-dark one, in document order. It is never a slide of its
+  own; one without a partner is dropped with a warning. A dark twin without an image for the
+  page's language uses its untagged image, and a light screenshot without a twin has no dark
+  version.
+- The `<picture>` lists the dark AVIF, WebP and PNG `<source>`s with
+  `media="(prefers-color-scheme: dark)"` first, which is the query the site's theme follows too.
+  No JavaScript is involved, and the full-screen view copies the `<picture>`, so it shows the same
+  rendition.
+- Each rendition is cropped, capped and sized on its own, so the translations and the dark twin
+  may differ in size.
+
+The store-listing module is unaffected: it publishes one default image per light screenshot.
+
 ### Colour
 
 Also nothing to configure: the metainfo's `<branding>` colour for the page's scheme paints the

package/lib/render/pages.d.ts

@@ -40,8 +40,13 @@ export declare function supportReference(data: SiteData): string;
  * file are three different promises, so each gets its own wording.
  */
 export declare function ctaLabel(target: DownloadTarget, t: Translate): string;
+/**
+ * The dark renditions come first: a browser takes the first `<source>` that matches, and the
+ * `prefers-color-scheme` media query is what the site's own theme follows too.
+ */
+export declare function picture(ctx: Pick<RenderContext, 'images' | 'lang'>, screenshot: Screenshot, alt: string, eager: boolean): string;
 /** A window shot brings its own shadow; ours would draw a second one around it. */
-export declare function frameAttribute(ctx: Pick<RenderContext, 'images'>, screenshot: Screenshot): 'none' | undefined;
+export declare function frameAttribute(ctx: Pick<RenderContext, 'images' | 'lang'>, screenshot: Screenshot): 'none' | undefined;
 /**
  * The split button plus the dialog holding every target. Both are server-rendered: without
  * JavaScript the dialog stays an open panel below the button (see `site.css`), with it the

package/lib/render/pages.js

@@ -1,4 +1,4 @@
-import { epcPayload, formatIban, isBrowserPlatform, needsOpenAnywayHint, PLATFORM_ORDER, pickByLanguage, relatedText, relatedUrl, } from '../site-data/index.js';
+import { epcPayload, formatIban, isBrowserPlatform, needsOpenAnywayHint, PLATFORM_ORDER, pickByLanguage, relatedText, relatedUrl, screenshotFile, } from '../site-data/index.js';
 import { blogFeedUrl, blogIndexUrl } from './blog.js';
 import { attrs, esc, fmt, plain } from './html.js';
 import { icon } from './icons.js';
@@ -6,6 +6,8 @@ import { absoluteUrl, documentPage, githubUrl, rootPage, simplePage, sitePageUrl
 import { renderMarkdown } from './markdown.js';
 import { qrSvg } from './qr.js';
 import { metaDescription, pageTitle, softwareApplicationJsonLd } from './seo.js';
+/** What `styles/site.css` follows for the theme; the dark `<source>`s answer the same question. */
+const DARK_MEDIA = '(prefers-color-scheme: dark)';
 const FORMAT_TYPES = { avif: 'image/avif', webp: 'image/webp', png: 'image/png' };
 const LINKS = [
     ['homepage', (t) => t('Website'), 'web'],
@@ -165,20 +167,44 @@ function srcset(files) {
 function sizes(image) {
     return `(max-width: 600px) 92vw, min(86vw, ${image.displayWidth}px)`;
 }
+/** The processed image a screenshot has for the language being rendered, in one colour scheme. */
+function shown(ctx, screenshot, scheme = 'light') {
+    return ctx.images.get(screenshotFile(screenshot, ctx.lang, scheme).slug);
+}
 /** What a phone shows for this screenshot: portrait artwork needs a taller track than a landscape window. */
 function portraitOnPhone(ctx, screenshot) {
-    const image = ctx.images.get(screenshot.slug);
+    const image = shown(ctx, screenshot);
     return image !== undefined && image.height > image.width * 1.1;
 }
-function picture(ctx, screenshot, alt, eager) {
-    const image = ctx.images.get(screenshot.slug);
-    const shared = { sizes: sizes(image), width: image.width, height: image.height };
-    const sources = ['avif', 'webp'].map((format) => `<source${attrs({ type: FORMAT_TYPES[format], srcset: srcset(image.formats[format]), ...shared })}>`);
+/**
+ * The dark renditions come first: a browser takes the first `<source>` that matches, and the
+ * `prefers-color-scheme` media query is what the site's own theme follows too.
+ */
+export function picture(ctx, screenshot, alt, eager) {
+    const image = shown(ctx, screenshot);
+    const dark = shown(ctx, screenshot, 'dark');
+    const source = (rendition, format, media) => `<source${attrs({
+        type: FORMAT_TYPES[format],
+        srcset: srcset(rendition.formats[format]),
+        media,
+        sizes: sizes(rendition),
+        width: rendition.width,
+        height: rendition.height,
+    })}>`;
+    const sources = [];
+    if (dark !== image) {
+        for (const format of ['avif', 'webp', 'png'])
+            sources.push(source(dark, format, DARK_MEDIA));
+    }
+    for (const format of ['avif', 'webp'])
+        sources.push(source(image, format));
     const png = image.formats.png;
     const img = `<img${attrs({
         src: png[png.length - 1].url,
         srcset: srcset(png),
-        ...shared,
+        sizes: sizes(image),
+        width: image.width,
+        height: image.height,
         alt,
         loading: eager ? undefined : 'lazy',
         decoding: 'async',
@@ -187,7 +213,7 @@ function picture(ctx, screenshot, alt, eager) {
 }
 /** A window shot brings its own shadow; ours would draw a second one around it. */
 export function frameAttribute(ctx, screenshot) {
-    return ctx.images.get(screenshot.slug)?.frameless === true ? 'none' : undefined;
+    return shown(ctx, screenshot)?.frameless === true ? 'none' : undefined;
 }
 /** The screenshots, at the bottom of the brand-coloured masthead. */
 function screenshotBand(ctx) {

package/lib/site-data/load.js

@@ -59,7 +59,7 @@ export async function loadSiteData(options) {
     const metainfoPath = resolve(options.root, config.metainfo);
     if (!existsSync(metainfoPath))
         throw new Error(`gjsify.site.metainfo points to "${config.metainfo}", which does not exist`);
-    const metainfo = parseMetainfo(await readFile(metainfoPath, 'utf8'));
+    const metainfo = parseMetainfo(await readFile(metainfoPath, 'utf8'), warn);
     const appCatalogs = config.translations
         ? await loadCatalogs(resolve(options.root, config.translations), config.languages)
         : {};

package/lib/site-data/metainfo.d.ts

@@ -6,4 +6,4 @@ import { type XmlElement } from './xml.js';
  */
 export declare function groupLocalized(elements: readonly XmlElement[]): Localized[];
 /** Reads the parts of an AppStream `<component>` the landing page needs. */
-export declare function parseMetainfo(xml: string): Metainfo;
+export declare function parseMetainfo(xml: string, warn?: (message: string) => void): Metainfo;

package/lib/site-data/metainfo.js

@@ -99,8 +99,45 @@ function parseUrls(component) {
     }
     return urls;
 }
+/** The `<image>`s of a `<screenshot>`: the untagged one, and the `xml:lang` ones as translations of it. */
+function parseImages(screenshot) {
+    const pick = (images) => (images.find((image) => image.attrs.type === 'source') ?? images[0])?.text;
+    const images = childrenNamed(screenshot, 'image');
+    const byLanguage = {};
+    for (const language of new Set(images.map((image) => image.attrs[XML_LANG]))) {
+        if (language === undefined)
+            continue;
+        const url = pick(images.filter((image) => image.attrs[XML_LANG] === language));
+        if (url)
+            byLanguage[language] = url;
+    }
+    return { url: pick(images.filter((image) => image.attrs[XML_LANG] === undefined)) ?? '', byLanguage };
+}
+/** AppStream's `environment="gnome:dark"`: the screenshot shows the app in its dark style. */
+function isDark(screenshot) {
+    return (screenshot.attrs.environment ?? '').endsWith(':dark');
+}
+/**
+ * The n-th dark screenshot is the dark twin of the n-th light one, in document order, and never a
+ * slide of its own. A dark screenshot with no light partner is dropped with a warning.
+ */
+function parseScreenshots(screenshots, warn) {
+    const light = screenshots.filter((screenshot) => !isDark(screenshot));
+    const result = light.map((screenshot) => ({
+        ...parseImages(screenshot),
+        caption: singleLocalized(screenshot, 'caption') ?? null,
+    }));
+    for (const [index, dark] of screenshots.filter(isDark).entries()) {
+        const partner = result[index];
+        if (partner)
+            partner.dark = parseImages(dark);
+        else
+            warn(`Dark screenshot ${index + 1} of the metainfo has no light screenshot to pair with; dropping it`);
+    }
+    return result;
+}
 /** Reads the parts of an AppStream `<component>` the landing page needs. */
-export function parseMetainfo(xml) {
+export function parseMetainfo(xml, warn = () => { }) {
     const component = parseXml(xml);
     if (component.name !== 'component')
         throw new Error(`Metainfo root must be <component>, got <${component.name}>`);
@@ -113,11 +150,7 @@ export function parseMetainfo(xml) {
     const summary = singleLocalized(component, 'summary') ?? { source: '', byLanguage: {} };
     const developer = child(component, 'developer');
     const developerName = developer ? child(developer, 'name')?.text : undefined;
-    const screenshots = childrenNamed(child(component, 'screenshots') ?? component, 'screenshot').map((screenshot) => {
-        const images = childrenNamed(screenshot, 'image');
-        const image = images.find((candidate) => candidate.attrs.type === 'source') ?? images[0];
-        return { url: image?.text ?? '', caption: singleLocalized(screenshot, 'caption') ?? null };
-    });
+    const screenshots = parseScreenshots(childrenNamed(child(component, 'screenshots') ?? component, 'screenshot'), warn);
     const contentRating = child(component, 'content_rating');
     const attributes = {};
     for (const attribute of contentRating ? childrenNamed(contentRating, 'content_attribute') : []) {

package/lib/site-data/screenshots.d.ts

@@ -1,5 +1,5 @@
 import { type NetworkOptions } from './network.js';
-import type { Metainfo, Screenshot } from './types.js';
+import type { Metainfo, Screenshot, ScreenshotFile } from './types.js';
 /**
  * The repo-relative path a `raw.githubusercontent.com` URL points at, or `undefined` when the URL
  * belongs to some other repository or host.
@@ -25,9 +25,18 @@ export interface ScreenshotOptions {
 }
 /**
  * The metainfo `<screenshots>` list with every image located on disk — the same artwork Flathub
- * shows, in the same order, so the page doubles as a preview of the store listing.
+ * shows, in the same order, so the page doubles as a preview of the store listing. Each screenshot
+ * also carries its `xml:lang` translations and its dark twin.
  *
- * A screenshot whose file cannot be found or fetched is skipped with a warning: a page missing one
- * image is better than no page at all, and the warning names what to fix.
+ * An image that cannot be found or fetched is skipped with a warning: a page missing one image is
+ * better than no page at all, and the warning names what to fix. When it is the default image the
+ * whole screenshot goes; a missing translation or dark rendition only falls back to the default.
  */
 export declare function resolveScreenshots(metainfo: Metainfo, options: ScreenshotOptions): Promise<Screenshot[]>;
+/**
+ * The image a language sees in a colour scheme: its own translation, else the untagged image; and
+ * for dark, the dark twin's, else the light screenshot's.
+ */
+export declare function screenshotFile(screenshot: Screenshot, language: string, scheme: 'light' | 'dark'): ScreenshotFile;
+/** Every file of a screenshot, each once: what the page has to turn into renditions. */
+export declare function screenshotFiles(screenshot: Screenshot): ScreenshotFile[];

package/lib/site-data/screenshots.js

@@ -3,6 +3,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { extname, join, resolve } from 'node:path';
 import { fetchBinary } from './network.js';
+import { pickByLanguage } from './po.js';
 const RAW_GITHUB = 'https://raw.githubusercontent.com/';
 /**
  * The repo-relative path a `raw.githubusercontent.com` URL points at, or `undefined` when the URL
@@ -42,49 +43,99 @@ export function imageSlug(path) {
 }
 /**
  * The metainfo `<screenshots>` list with every image located on disk — the same artwork Flathub
- * shows, in the same order, so the page doubles as a preview of the store listing.
+ * shows, in the same order, so the page doubles as a preview of the store listing. Each screenshot
+ * also carries its `xml:lang` translations and its dark twin.
  *
- * A screenshot whose file cannot be found or fetched is skipped with a warning: a page missing one
- * image is better than no page at all, and the warning names what to fix.
+ * An image that cannot be found or fetched is skipped with a warning: a page missing one image is
+ * better than no page at all, and the warning names what to fix. When it is the default image the
+ * whole screenshot goes; a missing translation or dark rendition only falls back to the default.
  */
 export async function resolveScreenshots(metainfo, options) {
     const warn = options.warn ?? (() => { });
     const store = options.cacheDir ?? join(tmpdir(), 'gjsify-site-screenshots');
-    const screenshots = [];
-    for (const [index, entry] of metainfo.screenshots.entries()) {
-        const label = `Screenshot ${index + 1}`;
-        if (!entry.url) {
-            warn(`${label} of the metainfo has no <image>; skipping it`);
-            continue;
-        }
-        const repoPath = repositoryPath(entry.url, options.repository);
-        const slug = imageSlug(repoPath ?? urlPath(entry.url));
-        const screenshot = { caption: entry.caption, url: entry.url, slug };
+    const locate = async (url, label) => {
+        const repoPath = repositoryPath(url, options.repository);
+        const slug = imageSlug(repoPath ?? urlPath(url));
         if (repoPath !== undefined) {
             const file = resolve(options.root, repoPath);
-            if (!existsSync(file)) {
-                warn(`${label} points at "${repoPath}" of this repository, which does not exist; skipping it`);
-                continue;
-            }
-            screenshots.push({ ...screenshot, file });
-            continue;
+            if (existsSync(file))
+                return { url, slug, file };
+            warn(`${label} points at "${repoPath}" of this repository, which does not exist; skipping it`);
+            return undefined;
         }
-        const file = join(store, `${slug}${extname(urlPath(entry.url)) || '.png'}`);
+        const file = join(store, `${slug}${extname(urlPath(url)) || '.png'}`);
         if (!existsSync(file)) {
             if (options.offline) {
-                warn(`${label} is hosted at ${entry.url}; skipping it because this build is offline`);
-                continue;
+                warn(`${label} is hosted at ${url}; skipping it because this build is offline`);
+                return undefined;
             }
             try {
                 await mkdir(store, { recursive: true });
-                await writeFile(file, await fetchBinary(entry.url, options.network ?? {}));
+                await writeFile(file, await fetchBinary(url, options.network ?? {}));
             }
             catch (error) {
-                warn(`Could not download ${label} from ${entry.url} (${String(error)}); skipping it`);
-                continue;
+                warn(`Could not download ${label} from ${url} (${String(error)}); skipping it`);
+                return undefined;
             }
         }
-        screenshots.push({ ...screenshot, file });
+        return { url, slug, file };
+    };
+    const locateTranslations = async (byLanguage, label) => {
+        const located = {};
+        for (const [language, url] of Object.entries(byLanguage)) {
+            const file = await locate(url, `${label} (${language})`);
+            if (file)
+                located[language] = file;
+        }
+        return located;
+    };
+    const screenshots = [];
+    for (const [index, entry] of metainfo.screenshots.entries()) {
+        const label = `Screenshot ${index + 1}`;
+        if (!entry.url) {
+            warn(`${label} of the metainfo has no <image>; skipping it`);
+            continue;
+        }
+        const file = await locate(entry.url, label);
+        if (!file)
+            continue;
+        const screenshot = {
+            ...file,
+            caption: entry.caption,
+            byLanguage: await locateTranslations(entry.byLanguage, label),
+        };
+        if (entry.dark) {
+            const darkLabel = `The dark rendition of ${label}`;
+            const dark = entry.dark.url ? await locate(entry.dark.url, darkLabel) : undefined;
+            if (!entry.dark.url)
+                warn(`${darkLabel} has no untagged <image>; ignoring it`);
+            if (dark) {
+                screenshot.dark = {
+                    default: dark,
+                    byLanguage: await locateTranslations(entry.dark.byLanguage, darkLabel),
+                };
+            }
+        }
+        screenshots.push(screenshot);
     }
     return screenshots;
 }
+/**
+ * The image a language sees in a colour scheme: its own translation, else the untagged image; and
+ * for dark, the dark twin's, else the light screenshot's.
+ */
+export function screenshotFile(screenshot, language, scheme) {
+    if (scheme === 'dark' && screenshot.dark) {
+        return pickByLanguage(screenshot.dark.byLanguage, language) ?? screenshot.dark.default;
+    }
+    return pickByLanguage(screenshot.byLanguage, language) ?? screenshot;
+}
+/** Every file of a screenshot, each once: what the page has to turn into renditions. */
+export function screenshotFiles(screenshot) {
+    const files = [
+        screenshot,
+        ...Object.values(screenshot.byLanguage),
+        ...(screenshot.dark ? [screenshot.dark.default, ...Object.values(screenshot.dark.byLanguage)] : []),
+    ];
+    return [...new Map(files.map((file) => [file.slug, file])).values()];
+}

package/lib/site-data/types.d.ts

@@ -230,9 +230,19 @@ export interface SiteConfig extends SiteCommonConfig {
  * One entry of the metainfo `<screenshots>` list, with its artwork located on disk. The same images
  * Flathub shows, so the page is a preview of the store listing.
  */
-export interface Screenshot {
+export interface Screenshot extends ScreenshotFile {
     /** The metainfo caption, translated where the metainfo or a catalogue has a translation. */
     caption: Localized | null;
+    /** The `xml:lang` renditions of the light artwork; the language without one gets the file above. */
+    byLanguage: Record<string, ScreenshotFile>;
+    /** The `environment="…:dark"` twin, when the metainfo has one. It falls back to the light artwork. */
+    dark?: {
+        default: ScreenshotFile;
+        byLanguage: Record<string, ScreenshotFile>;
+    };
+}
+/** One located image of a screenshot. */
+export interface ScreenshotFile {
     /** The `<image>` URL, kept for reference. */
     url: string;
     /** Absolute path of the artwork: the repository's own file, or the downloaded copy. */
@@ -240,6 +250,15 @@ export interface Screenshot {
     /** Stem of the published renditions, derived from the URL path; also the key of the image map. */
     slug: string;
 }
+/** The `<image>` URLs of one screenshot: the untagged one and its `xml:lang` translations. */
+export interface ImageUrls {
+    url: string;
+    byLanguage: Record<string, string>;
+}
+export interface MetainfoScreenshot extends ImageUrls {
+    caption: Localized | null;
+    dark?: ImageUrls;
+}
 export interface Release {
     version: string;
     date: string;
@@ -324,11 +343,11 @@ export interface Metainfo {
         name: string;
     };
     description: DescriptionBlock[];
-    /** Metainfo screenshots in document order; `url` is the remote image, kept for reference. */
-    screenshots: Array<{
-        url: string;
-        caption: Localized | null;
-    }>;
+    /**
+     * Metainfo screenshots in document order, dark twins folded into their light partner; `url` is
+     * the untagged remote image, kept for reference.
+     */
+    screenshots: MetainfoScreenshot[];
     releases: Release[];
     branding: Branding;
     urls: AppUrls;

package/lib/site.js

@@ -15,7 +15,7 @@ import { ogCardSvg } from './render/og-card.js';
 import { absolute, appShell, legalNoticeUrl, localized, pageMeta, pageUrl, privacyUrl, renderLegalNoticePage, renderPage, renderPrivacyPage, renderRoot, renderSupportPage, supportUrl, } from './render/pages.js';
 import { absoluteUrl, rootPage } from './render/layout.js';
 import { neighbourSitemaps, robotsTxt, seoWarnings, sitemapXml } from './render/seo.js';
-import { UI_SOURCE_LANGUAGE, loadCatalogs, loadSiteData, mergeCatalogs, blogAssetFiles, loadBlogPosts, loadDeveloperData, parseAnySiteConfig, translator, APP_MANIFEST_FILE, buildAppManifest, loadLegalNoticeStatements, loadPrivacyStatements, } from './site-data/index.js';
+import { UI_SOURCE_LANGUAGE, loadCatalogs, loadSiteData, mergeCatalogs, blogAssetFiles, loadBlogPosts, loadDeveloperData, parseAnySiteConfig, translator, APP_MANIFEST_FILE, buildAppManifest, loadLegalNoticeStatements, loadPrivacyStatements, screenshotFiles, } from './site-data/index.js';
 /**
  * This package's own directory: `lib/` holds the client bundle, `po/` the page catalogues.
  *
@@ -82,7 +82,8 @@ async function processScreenshots(data, { out }, cacheDir) {
         urlBase: `${data.config.base}img/`,
         pixelated: data.config.theme.imageRendering === 'pixelated',
     };
-    const entries = await Promise.all(data.screenshots.map(async (screenshot) => [screenshot.slug, await processImage(screenshot.file, screenshot.slug, options)]));
+    const files = new Map(data.screenshots.flatMap(screenshotFiles).map((file) => [file.slug, file]));
+    const entries = await Promise.all([...files.values()].map(async (file) => [file.slug, await processImage(file.file, file.slug, options)]));
     return new Map(entries);
 }
 const ICON_TYPES = { '.svg': 'image/svg+xml', '.png': 'image/png' };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/site",
-    "version": "0.64.24",
+    "version": "0.64.26-next.312",
     "description": "Static landing page generator for a GNOME-style app, rendered from its AppStream metainfo — downloads, screenshots, release notes, support links, no JavaScript required.",
     "type": "module",
     "main": "lib/index.js",
@@ -54,25 +54,26 @@
     "license": "MIT",
     "dependencies": {
         "@girs/gdkpixbuf-2.0": "5.4.0",
-        "@gjsify/console": "^0.64.24",
-        "@gjsify/crypto": "^0.64.24",
-        "@gjsify/fs": "^0.64.24",
-        "@gjsify/module": "^0.64.24",
-        "@gjsify/os": "^0.64.24",
-        "@gjsify/path": "^0.64.24",
-        "@gjsify/process": "^0.64.24",
-        "@gjsify/url": "^0.64.24",
+        "@gjsify/console": "0.64.26-next.312",
+        "@gjsify/crypto": "0.64.26-next.312",
+        "@gjsify/fs": "0.64.26-next.312",
+        "@gjsify/module": "0.64.26-next.312",
+        "@gjsify/os": "0.64.26-next.312",
+        "@gjsify/path": "0.64.26-next.312",
+        "@gjsify/process": "0.64.26-next.312",
+        "@gjsify/url": "0.64.26-next.312",
         "fast-xml-parser": "^5.11.2",
         "qrcode-generator": "^2.0.4"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.64.24",
+        "@gjsify/cli": "0.64.26-next.312",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",
-        "@gjsify/unit": "^0.64.24",
+        "@gjsify/unit": "0.64.26-next.312",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "gjsify": {
         "tier": 2
-    }
+    },
+    "gitHead": "75fa6155a8f1fa0f7e5d70c43418ae41ecac8c0e"
 }