@gjsify/site 0.0.0-stage → 0.63.1-next.236

package/lib/site-data/po.js

@@ -0,0 +1,148 @@
+const ESCAPES = { n: '\n', t: '\t', r: '\r', '"': '"', '\\': '\\' };
+function unquote(raw) {
+    const body = raw.trim().slice(1, -1);
+    return body.replace(/\\(.)/g, (_match, char) => ESCAPES[char] ?? char);
+}
+/** Parses a `.po`/`.pot` file; plural forms are not needed for web copy and are skipped. */
+export function parsePo(text) {
+    const entries = [];
+    let current = {};
+    let flags = '';
+    let references = [];
+    const flush = () => {
+        if (current.msgid !== undefined && current.msgstr !== undefined) {
+            entries.push({
+                msgctxt: current.msgctxt,
+                msgid: current.msgid,
+                msgstr: current.msgstr,
+                fuzzy: /\bfuzzy\b/.test(flags),
+                references,
+            });
+        }
+        current = {};
+        flags = '';
+        references = [];
+    };
+    for (const line of text.split(/\r?\n/)) {
+        if (line.startsWith('#,')) {
+            flags += ` ${line.slice(2)}`;
+        }
+        else if (line.startsWith('#:')) {
+            references.push(...line.slice(2).trim().split(/\s+/));
+        }
+        else if (line.startsWith('#') || line.trim() === '') {
+            if (line.trim() === '' && current.msgid !== undefined)
+                flush();
+        }
+        else if (line.startsWith('msgctxt ')) {
+            if (current.msgid !== undefined)
+                flush();
+            current.msgctxt = unquote(line.slice(8));
+            current.field = 'msgctxt';
+        }
+        else if (line.startsWith('msgid_plural ')) {
+            current.field = 'skip';
+        }
+        else if (line.startsWith('msgid ')) {
+            if (current.msgid !== undefined)
+                flush();
+            current.msgid = unquote(line.slice(6));
+            current.field = 'msgid';
+        }
+        else if (/^msgstr(\[0\])? /.test(line)) {
+            current.msgstr = unquote(line.slice(line.indexOf(' ') + 1));
+            current.field = 'msgstr';
+        }
+        else if (/^msgstr\[\d+\] /.test(line)) {
+            current.field = 'skip';
+        }
+        else if (line.startsWith('"') && current.field && current.field !== 'skip') {
+            current[current.field] = (current[current.field] ?? '') + unquote(line);
+        }
+    }
+    flush();
+    return entries;
+}
+/** Builds a lookup from parsed entries, skipping the header, empty, fuzzy and context-bound entries. */
+export function catalogFromEntries(entries) {
+    const catalog = new Map();
+    for (const entry of entries) {
+        if (entry.msgid === '' || entry.msgstr === '' || entry.fuzzy || entry.msgctxt !== undefined)
+            continue;
+        catalog.set(entry.msgid, entry.msgstr);
+    }
+    return catalog;
+}
+export function parseCatalog(text) {
+    return catalogFromEntries(parsePo(text));
+}
+/** Layers catalogues by language; a later one wins per msgid, so an overlay can correct a base. */
+export function mergeCatalogs(...layers) {
+    const merged = {};
+    for (const layer of layers) {
+        for (const [language, catalog] of Object.entries(layer)) {
+            const target = (merged[language] ??= new Map());
+            for (const [msgid, msgstr] of catalog)
+                target.set(msgid, msgstr);
+        }
+    }
+    return merged;
+}
+/** Escapes a string for a `.po` file value. */
+export function quotePo(value) {
+    return `"${value.replace(/[\\"\n\t\r]/g, (char) => (char === '\n' ? '\\n' : char === '\t' ? '\\t' : char === '\r' ? '\\r' : `\\${char}`))}"`;
+}
+/**
+ * Language tags the metainfo (`pt-BR`, BCP 47) and gettext (`pt_BR`) spell differently, from most to
+ * least specific: `pt-BR`, `pt_BR`, `pt`.
+ */
+export function languageCandidates(language) {
+    const dashed = language.replace(/_/g, '-');
+    const candidates = [dashed, dashed.replace(/-/g, '_')];
+    const base = dashed.split('-')[0];
+    if (base && base !== dashed)
+        candidates.push(base);
+    return [...new Set(candidates)];
+}
+/** Finds the entry for a language in a map keyed by either spelling. */
+export function pickByLanguage(byLanguage, language) {
+    for (const candidate of languageCandidates(language)) {
+        if (candidate in byLanguage)
+            return byLanguage[candidate];
+    }
+    return undefined;
+}
+/**
+ * Resolves a text for a language. Precedence: the metainfo's own `xml:lang` translation, then the
+ * app catalogue (msgid = the source text), then the source text itself.
+ */
+export function resolveLocalized(text, language, catalog) {
+    const fromMetainfo = pickByLanguage(text.byLanguage, language);
+    if (fromMetainfo !== undefined)
+        return fromMetainfo;
+    const fromCatalog = catalog?.get(text.source);
+    return fromCatalog ?? text.source;
+}
+/** The page strings are English msgids, so English needs no catalogue. */
+export const UI_SOURCE_LANGUAGE = 'en';
+/** A translator bound to one catalogue; unknown msgids come back unchanged, which is gettext's contract. */
+export function translator(catalog) {
+    return (msgid) => catalog?.get(msgid) ?? msgid;
+}
+/**
+ * Fills in the translations a text lacks for the site's languages, from the app catalogues
+ * (keyed by language). Translations the metainfo already carries win; other metainfo languages are dropped.
+ */
+export function completeLocalized(text, languages, sourceLanguage, catalogs) {
+    const byLanguage = {};
+    for (const language of languages) {
+        if (language === sourceLanguage)
+            continue;
+        const fromMetainfo = pickByLanguage(text.byLanguage, language);
+        const fromCatalog = catalogs[language]?.get(text.source);
+        const resolved = fromMetainfo ?? fromCatalog;
+        if (resolved !== undefined)
+            byLanguage[language] = resolved;
+    }
+    return { source: text.source, byLanguage };
+}

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

@@ -0,0 +1,33 @@
+import { type NetworkOptions } from './network.js';
+import type { Metainfo, Screenshot } 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.
+ *
+ * A metainfo pins its screenshots to a tag, so the URL serves the artwork of the release it was
+ * written for. The checkout being built carries that same file — and, between releases, a newer
+ * one — so reading it locally is both faster and more truthful than downloading the tagged copy.
+ */
+export declare function repositoryPath(url: string, repository: string): string | undefined;
+/** Flattens a path into one filename stem, so `misc/1.png` and `doc/1.png` stay apart. */
+export declare function imageSlug(path: string): string;
+export interface ScreenshotOptions {
+    /** Repository root, which a `raw.githubusercontent.com` URL into this repository is resolved against. */
+    root: string;
+    /** `owner/name` of this repository, from `gjsify.site.repository`. */
+    repository: string;
+    /** Where artwork from other hosts is kept, so a later offline build finds it again. */
+    cacheDir?: string;
+    /** No downloads; a screenshot with no local or cached file is skipped with a warning. */
+    offline?: boolean;
+    network?: NetworkOptions;
+    warn?: (message: string) => void;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function resolveScreenshots(metainfo: Metainfo, options: ScreenshotOptions): Promise<Screenshot[]>;

package/lib/site-data/screenshots.js

@@ -0,0 +1,90 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { extname, join, resolve } from 'node:path';
+import { fetchBinary } from './network.js';
+const RAW_GITHUB = 'https://raw.githubusercontent.com/';
+/**
+ * The repo-relative path a `raw.githubusercontent.com` URL points at, or `undefined` when the URL
+ * belongs to some other repository or host.
+ *
+ * A metainfo pins its screenshots to a tag, so the URL serves the artwork of the release it was
+ * written for. The checkout being built carries that same file — and, between releases, a newer
+ * one — so reading it locally is both faster and more truthful than downloading the tagged copy.
+ */
+export function repositoryPath(url, repository) {
+    if (!url.startsWith(RAW_GITHUB))
+        return undefined;
+    const [owner, name, ...rest] = urlPath(url).split('/').slice(1);
+    if (!owner || !name || rest.length === 0)
+        return undefined;
+    if (`${owner}/${name}`.toLowerCase() !== repository.toLowerCase())
+        return undefined;
+    // The ref is one segment (a branch, a commit) or three (`refs/tags/v1.2.0`, which is what the
+    // GitHub web UI copies and what metainfo files therefore tend to carry).
+    const drop = rest[0] === 'refs' && rest.length > 3 ? 3 : 1;
+    const path = rest.slice(drop).join('/');
+    return path === '' ? undefined : decodeURIComponent(path);
+}
+/** The path of a URL, leading slash included, without query or fragment. */
+function urlPath(url) {
+    const host = url.replace(/^[a-z]+:\/\//i, '');
+    const slash = host.indexOf('/');
+    return slash === -1 ? '/' : host.slice(slash).split(/[?#]/)[0];
+}
+/** Flattens a path into one filename stem, so `misc/1.png` and `doc/1.png` stay apart. */
+export function imageSlug(path) {
+    return path
+        .replace(/\.[^./]+$/, '')
+        .replace(/[^a-zA-Z0-9.]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+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 };
+        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;
+        }
+        const file = join(store, `${slug}${extname(urlPath(entry.url)) || '.png'}`);
+        if (!existsSync(file)) {
+            if (options.offline) {
+                warn(`${label} is hosted at ${entry.url}; skipping it because this build is offline`);
+                continue;
+            }
+            try {
+                await mkdir(store, { recursive: true });
+                await writeFile(file, await fetchBinary(entry.url, options.network ?? {}));
+            }
+            catch (error) {
+                warn(`Could not download ${label} from ${entry.url} (${String(error)}); skipping it`);
+                continue;
+            }
+        }
+        screenshots.push({ ...screenshot, file });
+    }
+    return screenshots;
+}

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

@@ -0,0 +1,20 @@
+/** Upper case, no spaces: the form an IBAN is stored and compared in. */
+export declare function normalizeIban(iban: string): string;
+/** Format check plus the ISO 7064 mod-97 checksum; expects a normalised IBAN. */
+export declare function isValidIban(iban: string): boolean;
+export declare function isValidBic(bic: string): boolean;
+/** Groups of four, as banks print it. */
+export declare function formatIban(iban: string): string;
+export interface EpcRecipient {
+    name: string;
+    iban: string;
+    bic?: string;
+    reference?: string;
+}
+/**
+ * The text of an EPC QR code (EPC069-12 v002): service tag BCD, version 002, charset 1 (UTF-8),
+ * identification SCT, then BIC, name, IBAN, amount, purpose, structured reference and the free
+ * text. The amount stays empty so the donor chooses it in their banking app. Lines are joined by
+ * LF with no trailing newline, which the spec allows for omitted trailing elements.
+ */
+export declare function epcPayload(recipient: EpcRecipient): string;

package/lib/site-data/sepa.js

@@ -0,0 +1,45 @@
+/** Upper case, no spaces: the form an IBAN is stored and compared in. */
+export function normalizeIban(iban) {
+    return iban.replace(/\s+/g, '').toUpperCase();
+}
+/** Format check plus the ISO 7064 mod-97 checksum; expects a normalised IBAN. */
+export function isValidIban(iban) {
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban))
+        return false;
+    const rearranged = iban.slice(4) + iban.slice(0, 4);
+    let remainder = 0;
+    for (const char of rearranged) {
+        const digits = /\d/.test(char) ? char : String(char.charCodeAt(0) - 55);
+        for (const digit of digits)
+            remainder = (remainder * 10 + Number(digit)) % 97;
+    }
+    return remainder === 1;
+}
+export function isValidBic(bic) {
+    return /^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$/.test(bic);
+}
+/** Groups of four, as banks print it. */
+export function formatIban(iban) {
+    return normalizeIban(iban).replace(/(.{4})(?=.)/g, '$1 ');
+}
+/**
+ * The text of an EPC QR code (EPC069-12 v002): service tag BCD, version 002, charset 1 (UTF-8),
+ * identification SCT, then BIC, name, IBAN, amount, purpose, structured reference and the free
+ * text. The amount stays empty so the donor chooses it in their banking app. Lines are joined by
+ * LF with no trailing newline, which the spec allows for omitted trailing elements.
+ */
+export function epcPayload(recipient) {
+    return [
+        'BCD',
+        '002',
+        '1',
+        'SCT',
+        recipient.bic ?? '',
+        recipient.name,
+        normalizeIban(recipient.iban),
+        '',
+        '',
+        '',
+        recipient.reference ?? '',
+    ].join('\n');
+}

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

@@ -0,0 +1,224 @@
+/** Operating systems a download can target. `web` covers the browser build and a self-hosting archive. */
+export type TargetOs = 'linux' | 'darwin' | 'win32' | 'web' | 'android';
+/** Browsers a WebExtension can target; the Chromium family counts as one. */
+export type TargetBrowser = 'firefox' | 'chromium';
+/** What a download group is keyed by: the OS a file runs on, or the browser an extension runs in. */
+export type TargetPlatform = TargetOs | TargetBrowser;
+/** `noarch` means one file serves every architecture (Flatpak, `.deb` "all", the web build). */
+export type TargetArch = 'x86_64' | 'arm64' | 'noarch';
+export type TargetFormat = 'flathub' | 'flatpak' | 'appimage' | 'deb' | 'rpm' | 'msi' | 'zip' | 'dmg' | 'apk' | 'web' | 'store' | 'xpi' | 'source';
+/**
+ * Text with the untranslated source and any translations found in the metainfo. `source` is
+ * written in the site's default language; `byLanguage` is keyed by BCP 47 tag as the metainfo
+ * spells it (`de`, `pt-BR`).
+ */
+export interface Localized {
+    source: string;
+    byLanguage: Record<string, string>;
+}
+export type DescriptionBlock = {
+    type: 'paragraph';
+    text: Localized;
+} | {
+    type: 'list';
+    items: Localized[];
+};
+/** A plain link to a place that takes donations or sponsorship; `kind` is a msgid of the website catalogue. */
+export interface SiteSupportLink {
+    kind: string;
+    url: string;
+}
+/** A SEPA bank transfer, shown as account details and an EPC QR code. The IBAN is stored normalised. */
+export interface SiteSupportSepa {
+    kind: 'sepa';
+    name: string;
+    iban: string;
+    bic?: string;
+    reference?: string;
+}
+export type SiteSupportEntry = SiteSupportLink | SiteSupportSepa;
+export interface SiteLegalLink {
+    label: string;
+    url: string;
+}
+/** One entry of `gjsify.site.downloads`: a target the release assets cannot supply (a store page, the install docs). */
+export interface SiteDownloadConfig {
+    platform: TargetPlatform;
+    format: TargetFormat;
+    /** Required unless `available` is false. */
+    url?: string;
+    /** English label, translated through the website catalogue; a default exists per platform and format. */
+    label?: string;
+    /** False lists the target as "not yet available" without a link. Default true. */
+    available: boolean;
+}
+/** The `gjsify.site` block of the root package.json, with defaults applied. */
+export interface SiteConfig {
+    metainfo: string;
+    base: string;
+    url: string;
+    languages: string[];
+    /** Language `/` falls back to when the visitor's languages match none of `languages`. */
+    defaultLanguage: string;
+    /** Language of the metainfo's untranslated text; the other languages are looked up in the catalogues. */
+    sourceLanguage: string;
+    repository: string;
+    flathub?: string;
+    webApp?: string;
+    /** Directory holding the app's `<lang>.po` catalogues, used when the metainfo lacks a translation. */
+    translations?: string;
+    /**
+     * Directory holding `<lang>.po` catalogues for the strings this configuration itself introduces —
+     * the download labels. They overlay the page catalogues shipped with the renderer, which cannot
+     * know a consumer's own copy.
+     */
+    pageTranslations?: string;
+    /** Repo-relative app icon; defaults to the Flatpak or `ship` icon of the root package.json. */
+    icon?: string;
+    /** Extra download targets, added to the ones derived from the latest release. */
+    downloads: SiteDownloadConfig[];
+    /** False ignores the latest release's assets, so `downloads` is the whole list. Default true. */
+    releaseAssets: boolean;
+    support: SiteSupportEntry[];
+    legal: SiteLegalLink[];
+}
+/**
+ * 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 {
+    /** The metainfo caption, translated where the metainfo or a catalogue has a translation. */
+    caption: Localized | null;
+    /** The `<image>` URL, kept for reference. */
+    url: string;
+    /** Absolute path of the artwork: the repository's own file, or the downloaded copy. */
+    file: string;
+    /** Stem of the published renditions, derived from the URL path; also the key of the image map. */
+    slug: string;
+}
+export interface Release {
+    version: string;
+    date: string;
+    type?: string;
+    description: DescriptionBlock[];
+}
+export interface DownloadTarget {
+    /** The group the target belongs to: an operating system, or a browser for extensions. */
+    os: TargetPlatform;
+    arch: TargetArch;
+    format: TargetFormat;
+    /** English label; the page translates it through the website catalogue. */
+    label: string;
+    /** Empty when the target is not available yet. */
+    url: string;
+    /** False for a target announced but not downloadable; it is listed, never recommended. */
+    available: boolean;
+    size?: number;
+    downloadCount?: number;
+    /** The one target to offer first for its OS. */
+    recommended: boolean;
+}
+export interface ReleaseAsset {
+    name: string;
+    size: number;
+    downloadUrl: string;
+    downloadCount: number;
+}
+export interface LatestRelease {
+    tag: string;
+    name: string;
+    publishedAt: string;
+    url: string;
+    assets: ReleaseAsset[];
+}
+export interface AgeRating {
+    /** Minimum age in years, derived from the OARS attributes the way libappstream does. */
+    minAge: number;
+}
+export interface Branding {
+    light?: string;
+    dark?: string;
+}
+export interface AppUrls {
+    homepage?: string;
+    bugtracker?: string;
+    vcsBrowser?: string;
+    translate?: string;
+    donation?: string;
+    help?: string;
+    faq?: string;
+    contact?: string;
+    contribute?: string;
+}
+/** What the AppStream metainfo says, before any site configuration is mixed in. */
+export interface Metainfo {
+    id: string;
+    name: Localized;
+    summary: Localized;
+    developer: {
+        id?: string;
+        name: string;
+    };
+    description: DescriptionBlock[];
+    /** Metainfo screenshots in document order; `url` is the remote image, kept for reference. */
+    screenshots: Array<{
+        url: string;
+        caption: Localized | null;
+    }>;
+    releases: Release[];
+    branding: Branding;
+    urls: AppUrls;
+    keywords: Localized[];
+    categories: string[];
+    projectLicense?: string;
+    /** Licence of the metainfo text itself, which is what the page reproduces. */
+    metadataLicense?: string;
+    contentRating?: {
+        type: string;
+        attributes: Record<string, string>;
+    };
+}
+export interface Stats {
+    /** Total installs reported by Flathub. */
+    flathubInstalls?: number;
+    flathubInstallsLastMonth?: number;
+    /** Sum of GitHub release asset downloads for the latest release. */
+    githubDownloads?: number;
+}
+export interface SiteData {
+    config: SiteConfig;
+    version: string;
+    app: {
+        id: string;
+        name: Localized;
+        summary: Localized;
+        developer: {
+            id?: string;
+            name: string;
+        };
+        description: DescriptionBlock[];
+        license?: string;
+        /** Licence of the text this page reproduces, as opposed to the app's own. */
+        contentLicense?: string;
+        keywords: Localized[];
+        categories: string[];
+        urls: AppUrls;
+        branding: Branding;
+        ageRating?: AgeRating;
+        /** Repo-relative path to the app icon. */
+        icon?: string;
+    };
+    screenshots: Screenshot[];
+    releases: Release[];
+    latestRelease: LatestRelease | null;
+    downloads: {
+        targets: DownloadTarget[];
+        /** Always present: the fallback when no asset list could be fetched. */
+        releasesUrl: string;
+        /** False when GitHub confirmed there is no release yet; an unreachable API still counts as true. */
+        hasReleases: boolean;
+    };
+    stats: Stats;
+    /** Non-fatal problems met while collecting data, already logged. */
+    warnings: string[];
+}

package/lib/site-data/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,11 @@
+/** A small element tree: `preserveOrder` output is awkward to walk, and order matters for translations. */
+export interface XmlElement {
+    name: string;
+    attrs: Record<string, string>;
+    children: XmlElement[];
+    /** Concatenated text of this element including nested elements (inline markup is flattened). */
+    text: string;
+}
+export declare function parseXml(xml: string): XmlElement;
+export declare function child(element: XmlElement, name: string): XmlElement | undefined;
+export declare function childrenNamed(element: XmlElement, name: string): XmlElement[];

package/lib/site-data/xml.js

@@ -0,0 +1,51 @@
+import { XMLParser } from 'fast-xml-parser';
+const parser = new XMLParser({
+    preserveOrder: true,
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    trimValues: false,
+    processEntities: true,
+    htmlEntities: false,
+});
+function convert(nodes) {
+    const elements = [];
+    for (const node of nodes) {
+        const name = Object.keys(node).find((key) => key !== ':@');
+        if (!name || name === '#text' || name === '#comment' || name.startsWith('?'))
+            continue;
+        const rawAttrs = (node[':@'] ?? {});
+        const attrs = {};
+        for (const [key, value] of Object.entries(rawAttrs))
+            attrs[key.replace(/^@_/, '')] = String(value);
+        const rawChildren = (node[name] ?? []);
+        const children = convert(rawChildren);
+        const element = { name, attrs, children, text: '' };
+        element.text = collectText(rawChildren).replace(/\s+/g, ' ').trim();
+        elements.push(element);
+    }
+    return elements;
+}
+function collectText(nodes) {
+    let text = '';
+    for (const node of nodes) {
+        const name = Object.keys(node).find((key) => key !== ':@');
+        if (name === '#text')
+            text += String(node['#text']);
+        else if (name)
+            text += collectText((node[name] ?? []));
+    }
+    return text;
+}
+export function parseXml(xml) {
+    const root = convert(parser.parse(xml));
+    const element = root[0];
+    if (!element)
+        throw new Error('XML document has no root element');
+    return element;
+}
+export function child(element, name) {
+    return element.children.find((candidate) => candidate.name === name);
+}
+export function childrenNamed(element, name) {
+    return element.children.filter((candidate) => candidate.name === name);
+}

package/lib/site.d.ts

@@ -0,0 +1,49 @@
+import { type I18nResult } from './render/i18n.js';
+/** Where a build reads from and writes to. */
+export interface SiteTarget {
+    /** Repository root: the root package.json, the metainfo, the screenshots and the icon are read from here. */
+    root: string;
+    /** Output directory, emptied first. */
+    out: string;
+}
+export interface SiteBuildOptions extends SiteTarget {
+    /** Skip every network call; the page is rendered from what is in the repository. */
+    offline?: boolean;
+    /**
+     * Where the one-hour HTTP response cache and the image renditions live; `false` disables the
+     * response cache. A published package must not write inside its own install, so the default is
+     * the consumer project's own build cache.
+     */
+    cacheDir?: string | false;
+    /** Raises the GitHub API rate limit. Optional — the public limit is enough for a single build. */
+    githubToken?: string;
+    log?: (message: string) => void;
+    warn?: (message: string) => void;
+    /** This package's install, for a caller whose module URL does not reveal it — a bundle. */
+    packageDir?: string;
+}
+export interface SiteBuildResult {
+    /** The languages that were rendered, in configuration order. */
+    languages: string[];
+    /** Screenshot source paths that were turned into renditions. */
+    screenshots: number;
+}
+export declare function defaultCacheDir(root: string): string;
+/** Renders one static page per configured language, plus the language-picking root page. */
+export declare function buildSite(options: SiteBuildOptions): Promise<SiteBuildResult>;
+export interface SiteI18nOptions {
+    /**
+     * The repository whose `gjsify.site` strings are synced into its `pageTranslations`. Omitted,
+     * this package's own `po/` is synced from the renderer sources instead.
+     */
+    root?: string;
+    /** Report what a regeneration would change instead of writing it. */
+    check?: boolean;
+    /** This package's install, for a caller whose module URL does not reveal it — a bundle. */
+    packageDir?: string;
+}
+/**
+ * Keeps gettext catalogues in sync with the strings that can actually be emitted — this package's
+ * own `po/` when called without a root, otherwise the consumer's `pageTranslations`.
+ */
+export declare function syncSiteI18n(options?: SiteI18nOptions): Promise<I18nResult>;