@gjsify/site 0.64.3-next.260 → 0.64.3-next.262

package/README.md

@@ -107,6 +107,7 @@ Lives in the root `package.json`, next to `ship` and `flatpak`.
 | `components` | `[{id, name, summary?, match?}]`: the separately installed parts of the product, in install order, see below. Optional — without it the dialog is one undivided list. |
 | `downloads` | `[{platform, format, url?, label?, available?, component?}]`: targets the release assets do not cover, e.g. browser stores or a source install. `platform` is an OS or `firefox` / `chromium`; `format` adds `store`, `xpi`, `source`. `url` is required unless `available` is `false`, which lists the target as "Not yet available" and never recommends it. `component` is a `components[].id`. |
 | `releaseAssets` | `false` ignores the GitHub release assets, so `downloads` is the whole list. Default `true`. |
+| `relatedApps` | `[url \| {url, name, summary, icon}]`: sites of other apps, listed in order under "More apps by <developer>" on the landing page, see below. Optional — without it there is no section and nothing is fetched. |
 | `support`, `legal` | `support`: `{kind, url}` links, or `{kind: "sepa", name, iban, bic?, reference?}`, a bank transfer shown as IBAN plus an EPC QR code. `legal`: `{label, url}` links. Both empty by default: nothing is invented. |
 
 A `sepa` entry carries no amount, and its IBAN is checked when the config loads — length per
@@ -140,6 +141,28 @@ The recommendation ("Recommended for your system") is made once per part, so eac
 highlights its own best match, and the big button at the top of the dialog offers the first
 declared component: the thing to install first.
 
+### Related apps
+
+Every build also writes `app.json` next to `index.html` — `{schema: 1, id, name, summary, icon, url,
+languages, developer}`, names and summaries per language from the metainfo, `icon` and `url`
+absolute. `relatedApps` reads those of other sites:
+
+```json
+"relatedApps": [
+  "https://example.org/notes/",
+  { "url": "https://example.org/plain/", "name": "Plain", "summary": "No app.json here", "icon": "https://example.org/plain/icon.png" }
+]
+```
+
+A string is a site address: the build fetches `<url>app.json` and renders a card (icon, name,
+summary in the page's language, else English) linking to the app's page in that language. An
+object is an inline entry for an app that publishes no `app.json`; nothing is fetched for it.
+The site's own address and app id are dropped, so all apps can share one list.
+
+The section is plain HTML rendered at build time. A site that cannot be reached, or whose
+`app.json` is invalid, is served from the last good copy in the build cache; with none, that card
+is skipped with a warning. The build never fails because of it.
+
 ### Screenshots
 
 Nothing to configure: the page shows the metainfo `<screenshots>`, in document order, with their

package/lib/client/site.css

@@ -1115,6 +1115,74 @@ app-support {
   margin-block: 1.5rem 0;
 }
 
+/* Related apps: same card list as the links, with the app's own icon */
+
+.related {
+  margin-block: 2rem;
+}
+
+.related h2 {
+  font-size: 1.15rem;
+}
+
+.related-list {
+  border: 1px solid var(--line);
+  border-radius: var(--radius-lg);
+  background: var(--surface);
+  overflow: hidden;
+  list-style: none;
+  padding: 0;
+}
+
+.related-list li + li {
+  border-top: 1px solid var(--line);
+}
+
+.related-list a {
+  display: flex;
+  align-items: center;
+  gap: 0.875rem;
+  padding: 0.75rem 1rem;
+  text-decoration: none;
+  color: inherit;
+}
+
+.related-list a:hover {
+  background: color-mix(in srgb, var(--fg) 6%, transparent);
+}
+
+.related-icon {
+  flex: none;
+  width: 3rem;
+  height: 3rem;
+  border-radius: 10px;
+  object-fit: contain;
+}
+
+.related-icon-blank {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--bg);
+  color: var(--muted);
+}
+
+.related-text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.related-name {
+  font-weight: 600;
+}
+
+.related-summary {
+  color: var(--muted);
+  font-size: 0.85rem;
+  overflow-wrap: anywhere;
+}
+
 /* Footer */
 
 .footer {

package/lib/render/pages.d.ts

@@ -51,6 +51,8 @@ export declare function downloadWidget(ctx: DownloadContext): string;
  */
 export declare function badges(ctx: Pick<RenderContext, 'data' | 't' | 'lang'>): string;
 export declare function linkCard(href: string, title: string, glyph: IconName): string;
+/** Other apps of the same developer, resolved at build time so the page needs no script. */
+export declare function relatedSection(ctx: Pick<RenderContext, 'data' | 'lang' | 't'>): string;
 /** A bank transfer as a card: the details to read or copy, and an EPC QR code that fills them into a banking app. */
 export declare function sepaCard(entry: SiteSupportSepa, t: Translate): string;
 /** The title and description of one page; also what the build checks for weak ones. */

package/lib/render/pages.js

@@ -1,4 +1,4 @@
-import { epcPayload, formatIban, isBrowserPlatform, PLATFORM_ORDER, pickByLanguage, } from '../site-data/index.js';
+import { epcPayload, formatIban, isBrowserPlatform, PLATFORM_ORDER, pickByLanguage, relatedText, relatedUrl, } from '../site-data/index.js';
 import { readableText } from './color.js';
 import { attrs, esc, fmt, plain } from './html.js';
 import { icon } from './icons.js';
@@ -466,6 +466,32 @@ ${items.join('\n')}
 </ul>
 </section>`;
 }
+function relatedCard(app, lang) {
+    const summary = relatedText(app.summary, lang);
+    const mark = app.icon
+        ? `<img class="related-icon" src="${esc(app.icon)}" alt="" width="48" height="48" loading="lazy">`
+        : `<span class="related-icon related-icon-blank">${icon('package')}</span>`;
+    return `<li>
+<a href="${esc(relatedUrl(app, lang))}">
+${mark}
+<span class="related-text"><span class="related-name">${esc(relatedText(app.name, lang))}</span>${summary ? `<span class="related-summary">${esc(summary)}</span>` : ''}</span>
+</a>
+</li>`;
+}
+/** Other apps of the same developer, resolved at build time so the page needs no script. */
+export function relatedSection(ctx) {
+    const { data, lang, t } = ctx;
+    if (data.relatedApps.length === 0)
+        return '';
+    const developer = data.app.developer.name;
+    const heading = developer ? fmt(t('More apps by {developer}'), { developer }) : esc(t('More apps'));
+    return `<section class="related">
+<h2>${heading}</h2>
+<ul class="related-list">
+${data.relatedApps.map((app) => relatedCard(app, lang)).join('\n')}
+</ul>
+</section>`;
+}
 /** A bank transfer as a card: the details to read or copy, and an EPC QR code that fills them into a banking app. */
 export function sepaCard(entry, t) {
     const grouped = formatIban(entry.iban);
@@ -708,6 +734,7 @@ ${blocks(data.app.description, lang)}
 ${releases(ctx)}
 ${support(ctx)}
 ${links(ctx)}
+${relatedSection(ctx)}
 ${tags(ctx)}
 </div>
 </main>

package/lib/site-data/config.js

@@ -54,6 +54,39 @@ function parseSupport(entry, where) {
     }
     return { kind: 'sepa', name, iban, bic, reference };
 }
+function httpUrl(value, where) {
+    if (!/^https?:\/\//.test(value))
+        throw new Error(`${where} must be an http(s) address`);
+    return value;
+}
+/** Strings are site addresses to fetch `app.json` from; objects are inline entries for apps without one. */
+function parseRelatedApps(raw) {
+    const value = raw.relatedApps;
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('gjsify.site.relatedApps must be a list');
+    return value.map((entry, index) => {
+        const where = `gjsify.site.relatedApps[${index}]`;
+        if (typeof entry === 'string')
+            return { url: withSlash(httpUrl(entry, where)) };
+        if (!isRecord(entry))
+            throw new Error(`${where} must be a site address or an object`);
+        const field = (key) => (entry[key] === undefined ? undefined : stringField(entry, key, where));
+        const url = withSlash(httpUrl(stringField(entry, 'url', where), `${where}.url`));
+        const name = field('name');
+        if (name === undefined) {
+            for (const key of ['summary', 'icon']) {
+                if (entry[key] !== undefined)
+                    throw new Error(`${where}.${key} needs "name": inline entries have all three`);
+            }
+            return { url };
+        }
+        const icon = field('icon');
+        return { url, name, summary: field('summary'), icon: icon && httpUrl(icon, `${where}.icon`) };
+    });
+}
+const withSlash = (url) => (url.endsWith('/') ? url : `${url}/`);
 const PLATFORMS = ['linux', 'darwin', 'win32', 'android', 'web', 'firefox', 'chromium'];
 const FORMATS = [
     'flathub',
@@ -149,7 +182,7 @@ export function parseSiteConfig(manifest) {
     return {
         metainfo: requireString(raw, 'metainfo'),
         base: normalizeBase(requireString(raw, 'base')),
-        url: url.endsWith('/') ? url : `${url}/`,
+        url: withSlash(url),
         languages: languages,
         defaultLanguage,
         sourceLanguage: optionalString(raw, 'sourceLanguage') ?? 'en',
@@ -167,6 +200,7 @@ export function parseSiteConfig(manifest) {
             label: stringField(entry, 'label', `gjsify.site.legal[${index}]`),
             url: stringField(entry, 'url', `gjsify.site.legal[${index}]`),
         })),
+        relatedApps: parseRelatedApps(raw),
     };
 }
 /** The `kind` labels the support page knows by name; the page catalogues translate them. */

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

@@ -7,6 +7,7 @@ export * from './metainfo.js';
 export * from './network.js';
 export * from './oars.js';
 export * from './po.js';
+export * from './related.js';
 export * from './screenshots.js';
 export * from './sepa.js';
 export * from './types.js';

package/lib/site-data/index.js

@@ -7,6 +7,7 @@ export * from './metainfo.js';
 export * from './network.js';
 export * from './oars.js';
 export * from './po.js';
+export * from './related.js';
 export * from './screenshots.js';
 export * from './sepa.js';
 export * from './types.js';

package/lib/site-data/load.js

@@ -8,6 +8,7 @@ import { fetchLatestRelease } from './github.js';
 import { parseMetainfo } from './metainfo.js';
 import { minimumAge } from './oars.js';
 import { completeLocalized, languageCandidates, parseCatalog } from './po.js';
+import { loadRelatedApps } from './related.js';
 import { resolveScreenshots } from './screenshots.js';
 /** Reads `<dir>/<lang>.po` for every language, trying `pt-BR` and `pt_BR` spellings; missing files are skipped. */
 export async function loadCatalogs(dir, languages) {
@@ -122,6 +123,11 @@ export async function loadSiteData(options) {
     const developer = metainfo.developer.name
         ? metainfo.developer
         : { id: manifest.gjsify?.flatpak?.developer?.id, name: manifest.gjsify?.flatpak?.developer?.name ?? '' };
+    const relatedApps = await loadRelatedApps(config, metainfo.id, {
+        offline: options.offline,
+        network: options.network,
+        warn,
+    });
     const releases = metainfo.releases.map((release) => ({
         ...release,
         description: completeBlocks(release.description),
@@ -160,6 +166,7 @@ export async function loadSiteData(options) {
             hasReleases,
         },
         stats,
+        relatedApps,
         warnings,
     };
 }

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

@@ -0,0 +1,23 @@
+import { type NetworkOptions } from './network.js';
+import type { AppManifest, RelatedApp, SiteConfig, SiteData } from './types.js';
+/** Where a site publishes its `app.json`. */
+export declare const APP_MANIFEST_FILE = "app.json";
+/** The `app.json` of a site: what another site needs to list this app. Icon URL is absolute. */
+export declare function buildAppManifest(data: SiteData, icon: string | undefined): AppManifest;
+/** Validates what came off the wire; returns why not when it is unusable. */
+export declare function parseAppManifest(raw: unknown): RelatedApp | string;
+export interface RelatedAppsOptions {
+    /** Never touch the network; only a copy from an earlier build can answer. */
+    offline?: boolean;
+    network?: NetworkOptions;
+    warn: (message: string) => void;
+}
+/**
+ * Resolves `gjsify.site.relatedApps` in configured order. The site's own entry is dropped, so every
+ * app can share one list. Never throws: an entry that cannot be had is skipped with a warning.
+ */
+export declare function loadRelatedApps(config: SiteConfig, ownId: string, options: RelatedAppsOptions): Promise<RelatedApp[]>;
+/** A text in the reader's language, else English, else whatever the app has. */
+export declare function relatedText(text: Record<string, string>, lang: string): string;
+/** The page of a related app in the reader's language, or its start page when it has no such one. */
+export declare function relatedUrl(app: RelatedApp, lang: string): string;

package/lib/site-data/related.js

@@ -0,0 +1,102 @@
+import { fetchJson } from './network.js';
+import { pickByLanguage } from './po.js';
+/** Where a site publishes its `app.json`. */
+export const APP_MANIFEST_FILE = 'app.json';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const urlKey = (url) => url.replace(/\/+$/, '').toLowerCase();
+const sameUrl = (a, b) => urlKey(a) === urlKey(b);
+const HTTP_URL = /^https?:\/\//;
+/** The `app.json` of a site: what another site needs to list this app. Icon URL is absolute. */
+export function buildAppManifest(data, icon) {
+    const texts = (text) => ({
+        [data.config.sourceLanguage]: text.source,
+        ...text.byLanguage,
+    });
+    return {
+        schema: 1,
+        id: data.app.id,
+        name: texts(data.app.name),
+        summary: texts(data.app.summary),
+        icon,
+        url: data.config.url,
+        languages: [...data.config.languages],
+        developer: { id: data.app.developer.id, name: data.app.developer.name },
+    };
+}
+function stringRecord(value) {
+    if (!isRecord(value))
+        return undefined;
+    const entries = Object.entries(value);
+    if (!entries.every(([, text]) => typeof text === 'string'))
+        return undefined;
+    return Object.fromEntries(entries);
+}
+/** Validates what came off the wire; returns why not when it is unusable. */
+export function parseAppManifest(raw) {
+    if (!isRecord(raw))
+        return 'not a JSON object';
+    if (raw.schema !== 1)
+        return `unknown schema ${JSON.stringify(raw.schema)}`;
+    const name = stringRecord(raw.name);
+    if (!name || Object.keys(name).length === 0)
+        return 'no "name"';
+    const summary = stringRecord(raw.summary) ?? {};
+    if (typeof raw.url !== 'string' || !HTTP_URL.test(raw.url))
+        return 'no http(s) "url"';
+    const languages = Array.isArray(raw.languages) ? raw.languages.filter((l) => typeof l === 'string') : [];
+    const icon = typeof raw.icon === 'string' && HTTP_URL.test(raw.icon) ? raw.icon : undefined;
+    return {
+        id: typeof raw.id === 'string' ? raw.id : undefined,
+        name,
+        summary,
+        icon,
+        url: raw.url.endsWith('/') ? raw.url : `${raw.url}/`,
+        languages,
+    };
+}
+const offlineFetch = () => Promise.reject(new Error('offline build'));
+async function loadOne(entry, options) {
+    if (entry.name !== undefined) {
+        return {
+            name: { en: entry.name },
+            summary: entry.summary === undefined ? {} : { en: entry.summary },
+            icon: entry.icon,
+            url: entry.url,
+            languages: [],
+        };
+    }
+    const file = `${entry.url}${APP_MANIFEST_FILE}`;
+    try {
+        // A TTL of zero: always ask first, and let the cache answer only when the site does not.
+        const raw = await fetchJson(file, { accept: 'application/json' }, { ...options.network, cacheTtlMs: 0, fetch: options.offline ? offlineFetch : options.network?.fetch });
+        const parsed = parseAppManifest(raw);
+        if (typeof parsed === 'string') {
+            options.warn(`Related app ${file}: ${parsed}; skipping it`);
+            return undefined;
+        }
+        return parsed;
+    }
+    catch (error) {
+        options.warn(`Related app ${file} is unavailable (${String(error)}) and no earlier copy exists; skipping it`);
+        return undefined;
+    }
+}
+/**
+ * Resolves `gjsify.site.relatedApps` in configured order. The site's own entry is dropped, so every
+ * app can share one list. Never throws: an entry that cannot be had is skipped with a warning.
+ */
+export async function loadRelatedApps(config, ownId, options) {
+    const candidates = config.relatedApps.filter((entry) => !sameUrl(entry.url, config.url));
+    const loaded = await Promise.all(candidates.map((entry) => loadOne(entry, options)));
+    return loaded.filter((app) => app !== undefined && app.id !== ownId && !sameUrl(app.url, config.url));
+}
+/** A text in the reader's language, else English, else whatever the app has. */
+export function relatedText(text, lang) {
+    return pickByLanguage(text, lang) ?? text.en ?? Object.values(text)[0] ?? '';
+}
+/** The page of a related app in the reader's language, or its start page when it has no such one. */
+export function relatedUrl(app, lang) {
+    if (app.languages.length === 0)
+        return app.url;
+    return `${app.url}${app.languages.includes(lang) ? lang : app.languages[0]}/`;
+}

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

@@ -73,6 +73,47 @@ export interface SiteDownloadConfig {
     /** Id of the `gjsify.site.components` entry this target installs. */
     component?: string;
 }
+/**
+ * One entry of `gjsify.site.relatedApps`: the site of another app, whose `app.json` is fetched at
+ * build time. With `name` set it is an inline entry instead — for an app that publishes no
+ * `app.json` (not built with gjsify) — and nothing is fetched.
+ */
+export interface SiteRelatedAppConfig {
+    url: string;
+    name?: string;
+    summary?: string;
+    icon?: string;
+}
+/**
+ * `app.json`, published next to every site's `index.html` so other sites can list the app. Bump
+ * `schema` on a breaking change; a reader ignores a schema it does not know.
+ */
+export interface AppManifest {
+    schema: 1;
+    id: string;
+    /** Keyed by language, the metainfo's source text under `sourceLanguage`. */
+    name: Record<string, string>;
+    summary: Record<string, string>;
+    /** Absolute URL of the app icon. */
+    icon?: string;
+    /** The site's own address. */
+    url: string;
+    /** Languages the site has pages for: `<url><lang>/` exists. */
+    languages: string[];
+    developer: {
+        id?: string;
+        name: string;
+    };
+}
+/** A related app as the page shows it: an `app.json` or an inline entry, validated. */
+export interface RelatedApp {
+    id?: string;
+    name: Record<string, string>;
+    summary: Record<string, string>;
+    icon?: string;
+    url: string;
+    languages: string[];
+}
 /** The `gjsify.site` block of the root package.json, with defaults applied. */
 export interface SiteConfig {
     metainfo: string;
@@ -107,6 +148,8 @@ export interface SiteConfig {
     releaseAssets: boolean;
     support: SiteSupportEntry[];
     legal: SiteLegalLink[];
+    /** Sites of other apps to list under "More apps by <developer>", in order. Empty: no section. */
+    relatedApps: SiteRelatedAppConfig[];
 }
 /**
  * One entry of the metainfo `<screenshots>` list, with its artwork located on disk. The same images
@@ -247,6 +290,8 @@ export interface SiteData {
         hasReleases: boolean;
     };
     stats: Stats;
+    /** Resolved `gjsify.site.relatedApps`, in configured order, without this site's own app. */
+    relatedApps: RelatedApp[];
     /** Non-fatal problems met while collecting data, already logged. */
     warnings: string[];
 }

package/lib/site.js

@@ -13,7 +13,7 @@ import { ogCardSvg } from './render/og-card.js';
 import { absolute, localized, pageMeta, pageUrl, renderPage, renderRoot, renderSupportPage, supportUrl, } from './render/pages.js';
 import { renderOverview } from './render/overview.js';
 import { robotsTxt, seoWarnings, sitemapXml } from './render/seo.js';
-import { UI_SOURCE_LANGUAGE, loadCatalogs, loadSiteData, mergeCatalogs, parseMetainfo, parseSiteConfig, pickByLanguage, translator, } from './site-data/index.js';
+import { UI_SOURCE_LANGUAGE, loadCatalogs, loadSiteData, mergeCatalogs, parseMetainfo, parseSiteConfig, pickByLanguage, translator, APP_MANIFEST_FILE, buildAppManifest, } from './site-data/index.js';
 /**
  * This package's own directory: `lib/` holds the client bundle, `po/` the page catalogues.
  *
@@ -150,6 +150,8 @@ export async function buildSite(options) {
             await writeFile(join(target.out, lang, 'support', 'index.html'), renderSupportPage(ctx));
         }
     }
+    const manifest = buildAppManifest(data, iconUrl ? absolute(data, iconUrl) : undefined);
+    await writeFile(join(target.out, APP_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
     await writeFile(join(target.out, 'index.html'), renderRoot(data, assets, iconUrl));
     const address = (build) => Object.fromEntries(data.config.languages.map((lang) => [lang, absolute(data, build(data, lang))]));
     const pages = [address(pageUrl), ...(hasSupport ? [address(supportUrl)] : [])];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/site",
-    "version": "0.64.3-next.260",
+    "version": "0.64.3-next.262",
     "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,26 +54,26 @@
     "license": "MIT",
     "dependencies": {
         "@girs/gdkpixbuf-2.0": "5.4.0",
-        "@gjsify/console": "0.64.3-next.260",
-        "@gjsify/crypto": "0.64.3-next.260",
-        "@gjsify/fs": "0.64.3-next.260",
-        "@gjsify/module": "0.64.3-next.260",
-        "@gjsify/os": "0.64.3-next.260",
-        "@gjsify/path": "0.64.3-next.260",
-        "@gjsify/process": "0.64.3-next.260",
-        "@gjsify/url": "0.64.3-next.260",
+        "@gjsify/console": "0.64.3-next.262",
+        "@gjsify/crypto": "0.64.3-next.262",
+        "@gjsify/fs": "0.64.3-next.262",
+        "@gjsify/module": "0.64.3-next.262",
+        "@gjsify/os": "0.64.3-next.262",
+        "@gjsify/path": "0.64.3-next.262",
+        "@gjsify/process": "0.64.3-next.262",
+        "@gjsify/url": "0.64.3-next.262",
         "fast-xml-parser": "^5.11.2",
         "qrcode-generator": "^2.0.4"
     },
     "devDependencies": {
-        "@gjsify/cli": "0.64.3-next.260",
+        "@gjsify/cli": "0.64.3-next.262",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",
-        "@gjsify/unit": "0.64.3-next.260",
+        "@gjsify/unit": "0.64.3-next.262",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "gjsify": {
         "tier": 2
     },
-    "gitHead": "886de21be840429ce043cdbf8195172530e230d4"
+    "gitHead": "0f5ca82aab25bf9df8d1e790d28483b1f90fe3a9"
 }

package/po/de.po

@@ -168,6 +168,12 @@ msgstr "Ältere Versionen"
 msgid "Links"
 msgstr "Links"
 
+msgid "More apps by {developer}"
+msgstr "Weitere Apps von {developer}"
+
+msgid "More apps"
+msgstr "Weitere Apps"
+
 msgid "Copied"
 msgstr "Kopiert"
 

package/po/site.pot

@@ -167,6 +167,12 @@ msgstr ""
 msgid "Links"
 msgstr ""
 
+msgid "More apps by {developer}"
+msgstr ""
+
+msgid "More apps"
+msgstr ""
+
 msgid "Copied"
 msgstr ""