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

package/lib/render/qr.js

@@ -0,0 +1,25 @@
+import qrcode from 'qrcode-generator';
+// The encoder defaults to Latin-1 and would mangle any other character; EPC declares UTF-8.
+qrcode.stringToBytes = (text) => [...new TextEncoder().encode(text)];
+/**
+ * Renders `text` as an inline SVG at build time. Error correction M, as the EPC spec prefers
+ * (L is the minimum it allows). The quiet zone is part of the SVG and always light, so the code
+ * scans on a dark theme too: scanners expect dark modules on a light ground.
+ */
+export function qrSvg(text, label, options = {}) {
+    const margin = options.margin ?? 4;
+    const code = qrcode(0, 'M');
+    code.addData(text, 'Byte');
+    code.make();
+    const count = code.getModuleCount();
+    const size = count + margin * 2;
+    let path = '';
+    for (let row = 0; row < count; row++) {
+        for (let col = 0; col < count; col++) {
+            if (code.isDark(row, col))
+                path += `M${col + margin} ${row + margin}h1v1h-1z`;
+        }
+    }
+    const title = label.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+    return `<svg class="qr" viewBox="0 0 ${size} ${size}" role="img" aria-label="${title}" shape-rendering="crispEdges"><rect width="${size}" height="${size}" fill="#fff"/><path d="${path}" fill="#000"/></svg>`;
+}

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

@@ -0,0 +1,23 @@
+import type { SiteConfig } from './types.js';
+/** The slice of the root package.json the site reads. Everything is optional until validated. */
+export interface RootManifest {
+    version?: string;
+    gjsify?: {
+        site?: unknown;
+        ship?: {
+            icon?: string;
+        };
+        flatpak?: {
+            appId?: string;
+            icon?: string;
+            developer?: {
+                id?: string;
+                name?: string;
+            };
+        };
+    };
+}
+/** Root-relative directory URL: `/x/` with a leading and trailing slash. */
+export declare function normalizeBase(base: string): string;
+/** Validates `gjsify.site` and applies defaults; the error names the offending key. */
+export declare function parseSiteConfig(manifest: RootManifest): SiteConfig;

package/lib/site-data/config.js

@@ -0,0 +1,142 @@
+import { isValidBic, isValidIban, normalizeIban } from './sepa.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireString(raw, key) {
+    const value = raw[key];
+    if (typeof value !== 'string' || value === '')
+        throw new Error(`gjsify.site.${key} is required and must be a non-empty string`);
+    return value;
+}
+function optionalString(raw, key) {
+    const value = raw[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value === '')
+        throw new Error(`gjsify.site.${key} must be a non-empty string`);
+    return value;
+}
+function objectList(raw, key) {
+    const value = raw[key];
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || !value.every(isRecord))
+        throw new Error(`gjsify.site.${key} must be a list of objects`);
+    return value;
+}
+function stringField(entry, key, where) {
+    const value = entry[key];
+    if (typeof value !== 'string' || value === '')
+        throw new Error(`${where}.${key} must be a non-empty string`);
+    return value;
+}
+function parseSupport(entry, where) {
+    const kind = stringField(entry, 'kind', where);
+    if (kind !== 'sepa')
+        return { kind, url: stringField(entry, 'url', where) };
+    const optional = (key) => {
+        if (entry[key] === undefined)
+            return undefined;
+        return stringField(entry, key, where);
+    };
+    const iban = normalizeIban(stringField(entry, 'iban', where));
+    if (!isValidIban(iban))
+        throw new Error(`${where}.iban is not a valid IBAN (format or checksum)`);
+    const bic = optional('bic')?.replace(/\s+/g, '').toUpperCase();
+    if (bic !== undefined && !isValidBic(bic))
+        throw new Error(`${where}.bic is not a valid BIC (8 or 11 characters)`);
+    const name = stringField(entry, 'name', where);
+    if ([...name].length > 70)
+        throw new Error(`${where}.name is longer than the 70 characters an EPC QR code allows`);
+    const reference = optional('reference');
+    if (reference !== undefined && [...reference].length > 140) {
+        throw new Error(`${where}.reference is longer than the 140 characters an EPC QR code allows`);
+    }
+    return { kind: 'sepa', name, iban, bic, reference };
+}
+const PLATFORMS = ['linux', 'darwin', 'win32', 'android', 'web', 'firefox', 'chromium'];
+const FORMATS = [
+    'flathub',
+    'flatpak',
+    'appimage',
+    'deb',
+    'rpm',
+    'msi',
+    'zip',
+    'dmg',
+    'apk',
+    'web',
+    'store',
+    'xpi',
+    'source',
+];
+function parseDownloads(raw) {
+    return objectList(raw, 'downloads').map((entry, index) => {
+        const where = `gjsify.site.downloads[${index}]`;
+        const platform = stringField(entry, 'platform', where);
+        if (!PLATFORMS.includes(platform))
+            throw new Error(`${where}.platform must be one of ${PLATFORMS.join(', ')}`);
+        const format = stringField(entry, 'format', where);
+        if (!FORMATS.includes(format))
+            throw new Error(`${where}.format must be one of ${FORMATS.join(', ')}`);
+        const available = entry.available ?? true;
+        if (typeof available !== 'boolean')
+            throw new Error(`${where}.available must be true or false`);
+        const url = entry.url;
+        if (available && (typeof url !== 'string' || !/^https?:\/\//.test(url))) {
+            throw new Error(`${where}.url must be an http(s) address unless "available" is false`);
+        }
+        if (url !== undefined && (typeof url !== 'string' || !/^https?:\/\//.test(url))) {
+            throw new Error(`${where}.url must be an http(s) address`);
+        }
+        const label = entry.label;
+        if (label !== undefined && (typeof label !== 'string' || label === ''))
+            throw new Error(`${where}.label must be a non-empty string`);
+        return { platform, format, url, label, available };
+    });
+}
+function parseReleaseAssets(raw) {
+    const value = raw.releaseAssets ?? true;
+    if (typeof value !== 'boolean')
+        throw new Error('gjsify.site.releaseAssets must be true or false');
+    return value;
+}
+/** Root-relative directory URL: `/x/` with a leading and trailing slash. */
+export function normalizeBase(base) {
+    return `/${base.replace(/^\/+|\/+$/g, '')}/`.replace(/^\/\/$/, '/');
+}
+/** Validates `gjsify.site` and applies defaults; the error names the offending key. */
+export function parseSiteConfig(manifest) {
+    const raw = manifest.gjsify?.site;
+    if (!isRecord(raw))
+        throw new Error('The root package.json has no "gjsify.site" object');
+    const languages = raw.languages ?? ['en'];
+    if (!Array.isArray(languages) || languages.length === 0 || !languages.every((entry) => typeof entry === 'string')) {
+        throw new Error('gjsify.site.languages must be a non-empty list of language codes');
+    }
+    const defaultLanguage = optionalString(raw, 'defaultLanguage') ?? languages[0];
+    if (!languages.includes(defaultLanguage))
+        throw new Error(`gjsify.site.defaultLanguage "${defaultLanguage}" is not in languages`);
+    const url = requireString(raw, 'url');
+    return {
+        metainfo: requireString(raw, 'metainfo'),
+        base: normalizeBase(requireString(raw, 'base')),
+        url: url.endsWith('/') ? url : `${url}/`,
+        languages: languages,
+        defaultLanguage,
+        sourceLanguage: optionalString(raw, 'sourceLanguage') ?? 'en',
+        repository: requireString(raw, 'repository'),
+        flathub: optionalString(raw, 'flathub'),
+        webApp: optionalString(raw, 'webApp'),
+        translations: optionalString(raw, 'translations'),
+        pageTranslations: optionalString(raw, 'pageTranslations'),
+        icon: optionalString(raw, 'icon'),
+        downloads: parseDownloads(raw),
+        releaseAssets: parseReleaseAssets(raw),
+        support: objectList(raw, 'support').map((entry, index) => parseSupport(entry, `gjsify.site.support[${index}]`)),
+        legal: objectList(raw, 'legal').map((entry, index) => ({
+            label: stringField(entry, 'label', `gjsify.site.legal[${index}]`),
+            url: stringField(entry, 'url', `gjsify.site.legal[${index}]`),
+        })),
+    };
+}

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

@@ -0,0 +1,29 @@
+import type { DownloadTarget, ReleaseAsset, SiteDownloadConfig, TargetArch, TargetFormat, TargetPlatform } from './types.js';
+/** Browser extensions are listed after the OS builds; a page usually has only one kind. */
+export declare const PLATFORM_ORDER: readonly TargetPlatform[];
+/** Platforms that are browsers: their targets are picked by the visitor's browser, not OS. */
+export declare function isBrowserPlatform(platform: TargetPlatform): platform is 'firefox' | 'chromium';
+export declare const DOWNLOAD_LABELS: Record<string, string>;
+/** Fallback for a platform and format pair `DOWNLOAD_LABELS` does not name, e.g. `linux:source`. */
+export declare const FORMAT_LABELS: Record<TargetFormat, string>;
+/** English label of a download target: the platform's own wording, else the format's, never the raw id. */
+export declare function defaultLabel(os: TargetPlatform, format: TargetFormat): string;
+/** Maps a release asset to the OS and format it serves, or `null` for files that are not downloads (checksums, sources). */
+export declare function classifyAsset(asset: ReleaseAsset): {
+    os: TargetPlatform;
+    format: TargetFormat;
+    arch: TargetArch;
+} | null;
+export interface DownloadSources {
+    assets: readonly ReleaseAsset[];
+    /** Flathub application id, when the app is published there. */
+    flathub?: string;
+    /** Bytes the Flathub install transfers, from its summary endpoint. */
+    flathubSize?: number;
+    /** Root-relative URL of the live web build. */
+    webAppUrl?: string;
+    /** `gjsify.site.downloads`: targets no release asset supplies, e.g. a store page. */
+    configured?: readonly SiteDownloadConfig[];
+}
+/** Builds the sorted target list and marks the first available target of every platform as recommended. */
+export declare function buildDownloadTargets(sources: DownloadSources): DownloadTarget[];

package/lib/site-data/downloads.js

@@ -0,0 +1,193 @@
+/** Browser extensions are listed after the OS builds; a page usually has only one kind. */
+export const PLATFORM_ORDER = [
+    'linux',
+    'darwin',
+    'win32',
+    'android',
+    'web',
+    'firefox',
+    'chromium',
+];
+/** Platforms that are browsers: their targets are picked by the visitor's browser, not OS. */
+export function isBrowserPlatform(platform) {
+    return platform === 'firefox' || platform === 'chromium';
+}
+/** Best format first, per OS. The first target in this order is the recommended one. */
+const FORMAT_RANK = {
+    linux: ['flathub', 'appimage', 'flatpak', 'deb', 'rpm'],
+    darwin: ['dmg', 'zip'],
+    win32: ['msi', 'zip'],
+    android: ['apk'],
+    web: ['web', 'zip'],
+    firefox: ['store', 'xpi', 'zip', 'source'],
+    chromium: ['store', 'zip', 'source'],
+};
+/** Apple silicon first on macOS, the common PC architecture first everywhere else. */
+const ARCH_RANK = {
+    linux: ['noarch', 'x86_64', 'arm64'],
+    darwin: ['arm64', 'x86_64', 'noarch'],
+    win32: ['x86_64', 'arm64', 'noarch'],
+    android: ['noarch', 'arm64', 'x86_64'],
+    web: ['noarch', 'x86_64', 'arm64'],
+    firefox: ['noarch'],
+    chromium: ['noarch'],
+};
+export const DOWNLOAD_LABELS = {
+    'linux:flathub': 'Flathub',
+    'linux:flatpak': 'Flatpak bundle',
+    'linux:appimage': 'AppImage',
+    'linux:deb': 'Debian package',
+    'linux:rpm': 'RPM package',
+    'win32:msi': 'Windows installer',
+    'win32:zip': 'Windows portable',
+    'darwin:zip': 'macOS app',
+    'darwin:dmg': 'macOS disk image',
+    'android:apk': 'Android package',
+    'web:web': 'Try in browser',
+    'web:zip': 'Web build',
+    'firefox:store': 'Firefox Add-ons',
+    'firefox:xpi': 'Signed Firefox add-on',
+    'firefox:zip': 'Firefox extension',
+    'firefox:source': 'Build from source',
+    'chromium:store': 'Chrome Web Store',
+    'chromium:zip': 'Chromium extension',
+    'chromium:source': 'Build from source',
+};
+/** Fallback for a platform and format pair `DOWNLOAD_LABELS` does not name, e.g. `linux:source`. */
+export const FORMAT_LABELS = {
+    flathub: 'Flathub',
+    flatpak: 'Flatpak bundle',
+    appimage: 'AppImage',
+    deb: 'Debian package',
+    rpm: 'RPM package',
+    msi: 'Windows installer',
+    zip: 'ZIP archive',
+    dmg: 'macOS disk image',
+    apk: 'Android package',
+    web: 'Try in browser',
+    store: 'Store',
+    xpi: 'Firefox add-on',
+    source: 'Source code',
+};
+/** English label of a download target: the platform's own wording, else the format's, never the raw id. */
+export function defaultLabel(os, format) {
+    return DOWNLOAD_LABELS[`${os}:${format}`] ?? FORMAT_LABELS[format];
+}
+function detectArch(name) {
+    if (/arm64|aarch64/i.test(name))
+        return 'arm64';
+    if (/x86_64|x64|amd64/i.test(name))
+        return 'x86_64';
+    return 'noarch';
+}
+/** Maps a release asset to the OS and format it serves, or `null` for files that are not downloads (checksums, sources). */
+export function classifyAsset(asset) {
+    const name = asset.name.toLowerCase();
+    const arch = detectArch(name);
+    if (name.endsWith('.flatpak'))
+        return { os: 'linux', format: 'flatpak', arch };
+    if (name.endsWith('.appimage'))
+        return { os: 'linux', format: 'appimage', arch };
+    if (name.endsWith('.deb'))
+        return { os: 'linux', format: 'deb', arch };
+    if (name.endsWith('.rpm'))
+        return { os: 'linux', format: 'rpm', arch };
+    if (name.endsWith('.msi'))
+        return { os: 'win32', format: 'msi', arch };
+    if (name.endsWith('.dmg'))
+        return { os: 'darwin', format: 'dmg', arch };
+    if (name.endsWith('.apk'))
+        return { os: 'android', format: 'apk', arch };
+    if (name.endsWith('.xpi'))
+        return { os: 'firefox', format: 'xpi', arch: 'noarch' };
+    if (name.endsWith('.zip')) {
+        if (/windows|win32|win64/.test(name))
+            return { os: 'win32', format: 'zip', arch };
+        if (/macos|darwin/.test(name))
+            return { os: 'darwin', format: 'zip', arch };
+        if (/web/.test(name))
+            return { os: 'web', format: 'zip', arch };
+        if (/firefox/.test(name))
+            return { os: 'firefox', format: 'zip', arch: 'noarch' };
+        if (/chrome|chromium|edge/.test(name))
+            return { os: 'chromium', format: 'zip', arch: 'noarch' };
+    }
+    return null;
+}
+function rank(order, value) {
+    const index = order.indexOf(value);
+    return index === -1 ? order.length : index;
+}
+/**
+ * What the store install costs to download. Flathub's own number is the honest one; the Flatpak
+ * bundle of the same release is close enough to stand in when the API did not answer.
+ */
+function storeSize(sources) {
+    if (sources.flathubSize !== undefined)
+        return sources.flathubSize;
+    const bundle = sources.assets.find((asset) => classifyAsset(asset)?.format === 'flatpak');
+    return bundle?.size;
+}
+/** Builds the sorted target list and marks the first available target of every platform as recommended. */
+export function buildDownloadTargets(sources) {
+    const targets = [];
+    if (sources.flathub) {
+        targets.push({
+            os: 'linux',
+            arch: 'noarch',
+            format: 'flathub',
+            label: defaultLabel('linux', 'flathub'),
+            url: `https://flathub.org/apps/${sources.flathub}`,
+            available: true,
+            size: storeSize(sources),
+            recommended: false,
+        });
+    }
+    for (const asset of sources.assets) {
+        const kind = classifyAsset(asset);
+        if (!kind)
+            continue;
+        targets.push({
+            ...kind,
+            label: defaultLabel(kind.os, kind.format),
+            url: asset.downloadUrl,
+            available: true,
+            size: asset.size,
+            downloadCount: asset.downloadCount,
+            recommended: false,
+        });
+    }
+    if (sources.webAppUrl) {
+        targets.push({
+            os: 'web',
+            arch: 'noarch',
+            format: 'web',
+            label: defaultLabel('web', 'web'),
+            url: sources.webAppUrl,
+            available: true,
+            recommended: false,
+        });
+    }
+    for (const entry of sources.configured ?? []) {
+        targets.push({
+            os: entry.platform,
+            arch: 'noarch',
+            format: entry.format,
+            label: entry.label ?? defaultLabel(entry.platform, entry.format),
+            url: entry.available ? (entry.url ?? '') : '',
+            available: entry.available,
+            recommended: false,
+        });
+    }
+    targets.sort((a, b) => rank(PLATFORM_ORDER, a.os) - rank(PLATFORM_ORDER, b.os) ||
+        rank(FORMAT_RANK[a.os], a.format) - rank(FORMAT_RANK[b.os], b.format) ||
+        rank(ARCH_RANK[a.os], a.arch) - rank(ARCH_RANK[b.os], b.arch));
+    const seen = new Set();
+    for (const target of targets) {
+        if (!target.available || seen.has(target.os))
+            continue;
+        seen.add(target.os);
+        target.recommended = true;
+    }
+    return targets;
+}

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

@@ -0,0 +1,24 @@
+import { type NetworkOptions } from './network.js';
+export interface FlathubStats {
+    installsTotal: number;
+    installsLastMonth?: number;
+}
+/**
+ * Parses `https://flathub.org/api/v2/stats/<appid>`. Verified shape (2026-10): an object with
+ * `installs_total`, `installs_last_month`, `installs_last_7_days`, `installs_per_day` and
+ * `installs_per_country`. Only the totals are used.
+ */
+export declare function parseFlathubStats(payload: unknown): FlathubStats;
+export declare function fetchFlathubStats(appId: string, options: NetworkOptions): Promise<FlathubStats>;
+export interface FlathubSummary {
+    /** Bytes the install transfers, which is what a download size means for a store install. */
+    downloadSize: number;
+    installedSize?: number;
+}
+/**
+ * Parses `https://flathub.org/api/v2/summary/<appid>`. Verified shape (2026-10): `download_size`,
+ * `installed_size`, `branches`, `arches`, `metadata` and `timestamp`, with the sizes in bytes and
+ * repeated per branch. The top-level pair describes the branch Flathub installs by default.
+ */
+export declare function parseFlathubSummary(payload: unknown): FlathubSummary;
+export declare function fetchFlathubSummary(appId: string, options: NetworkOptions): Promise<FlathubSummary>;

package/lib/site-data/flathub.js

@@ -0,0 +1,35 @@
+import { fetchJson } from './network.js';
+/**
+ * Parses `https://flathub.org/api/v2/stats/<appid>`. Verified shape (2026-10): an object with
+ * `installs_total`, `installs_last_month`, `installs_last_7_days`, `installs_per_day` and
+ * `installs_per_country`. Only the totals are used.
+ */
+export function parseFlathubStats(payload) {
+    const stats = payload;
+    if (typeof stats?.installs_total !== 'number')
+        throw new Error('Unexpected Flathub stats payload');
+    return {
+        installsTotal: stats.installs_total,
+        installsLastMonth: typeof stats.installs_last_month === 'number' ? stats.installs_last_month : undefined,
+    };
+}
+export async function fetchFlathubStats(appId, options) {
+    return parseFlathubStats(await fetchJson(`https://flathub.org/api/v2/stats/${encodeURIComponent(appId)}`, { Accept: 'application/json' }, options));
+}
+/**
+ * Parses `https://flathub.org/api/v2/summary/<appid>`. Verified shape (2026-10): `download_size`,
+ * `installed_size`, `branches`, `arches`, `metadata` and `timestamp`, with the sizes in bytes and
+ * repeated per branch. The top-level pair describes the branch Flathub installs by default.
+ */
+export function parseFlathubSummary(payload) {
+    const summary = payload;
+    if (typeof summary?.download_size !== 'number')
+        throw new Error('Unexpected Flathub summary payload');
+    return {
+        downloadSize: summary.download_size,
+        installedSize: typeof summary.installed_size === 'number' ? summary.installed_size : undefined,
+    };
+}
+export async function fetchFlathubSummary(appId, options) {
+    return parseFlathubSummary(await fetchJson(`https://flathub.org/api/v2/summary/${encodeURIComponent(appId)}`, { Accept: 'application/json' }, options));
+}

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

@@ -0,0 +1,9 @@
+import { type NetworkOptions } from './network.js';
+import type { LatestRelease } from './types.js';
+/** Parses the GitHub REST `releases/latest` payload; anything malformed throws so the caller can warn and degrade. */
+export declare function parseLatestRelease(payload: unknown): LatestRelease;
+/**
+ * Fetches the latest published (non-draft, non-prerelease) release; `null` when the repository has
+ * none yet, which is a state and not an error. `token` raises the rate limit.
+ */
+export declare function fetchLatestRelease(repository: string, token: string | undefined, options: NetworkOptions): Promise<LatestRelease | null>;

package/lib/site-data/github.js

@@ -0,0 +1,45 @@
+import { fetchJson, HttpError } from './network.js';
+/** Parses the GitHub REST `releases/latest` payload; anything malformed throws so the caller can warn and degrade. */
+export function parseLatestRelease(payload) {
+    const release = payload;
+    if (typeof release?.tag_name !== 'string' || !Array.isArray(release.assets)) {
+        throw new Error('Unexpected GitHub release payload');
+    }
+    const assets = release.assets.flatMap((asset) => typeof asset.name === 'string' && typeof asset.browser_download_url === 'string'
+        ? [
+            {
+                name: asset.name,
+                size: typeof asset.size === 'number' ? asset.size : 0,
+                downloadUrl: asset.browser_download_url,
+                downloadCount: typeof asset.download_count === 'number' ? asset.download_count : 0,
+            },
+        ]
+        : []);
+    return {
+        tag: release.tag_name,
+        name: typeof release.name === 'string' && release.name ? release.name : release.tag_name,
+        publishedAt: typeof release.published_at === 'string' ? release.published_at : '',
+        url: typeof release.html_url === 'string' ? release.html_url : '',
+        assets,
+    };
+}
+/**
+ * Fetches the latest published (non-draft, non-prerelease) release; `null` when the repository has
+ * none yet, which is a state and not an error. `token` raises the rate limit.
+ */
+export async function fetchLatestRelease(repository, token, options) {
+    const headers = {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': `${repository.replace('/', '-')}-website`,
+    };
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    try {
+        return parseLatestRelease(await fetchJson(`https://api.github.com/repos/${repository}/releases/latest`, headers, options));
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404)
+            return null;
+        throw error;
+    }
+}

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

@@ -0,0 +1,12 @@
+export * from './config.js';
+export * from './downloads.js';
+export * from './flathub.js';
+export * from './github.js';
+export * from './load.js';
+export * from './metainfo.js';
+export * from './network.js';
+export * from './oars.js';
+export * from './po.js';
+export * from './screenshots.js';
+export * from './sepa.js';
+export * from './types.js';

package/lib/site-data/index.js

@@ -0,0 +1,12 @@
+export * from './config.js';
+export * from './downloads.js';
+export * from './flathub.js';
+export * from './github.js';
+export * from './load.js';
+export * from './metainfo.js';
+export * from './network.js';
+export * from './oars.js';
+export * from './po.js';
+export * from './screenshots.js';
+export * from './sepa.js';
+export * from './types.js';

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

@@ -0,0 +1,18 @@
+import type { NetworkOptions } from './network.js';
+import { type Catalog } from './po.js';
+import type { SiteData } from './types.js';
+export interface LoadOptions {
+    /** Repository root: where the root package.json lives and the config's paths start. */
+    root: string;
+    /** Where screenshots hosted outside this repository are kept, so a later offline build finds them again. */
+    screenshotCacheDir?: string;
+    /** Skip every network call (release assets, stats, screenshots hosted elsewhere). */
+    offline?: boolean;
+    githubToken?: string;
+    network?: NetworkOptions;
+    warn?: (message: string) => void;
+}
+/** Reads `<dir>/<lang>.po` for every language, trying `pt-BR` and `pt_BR` spellings; missing files are skipped. */
+export declare function loadCatalogs(dir: string, languages: readonly string[]): Promise<Record<string, Catalog>>;
+/** Collects everything the pages need into one object. Network failures degrade to warnings. */
+export declare function loadSiteData(options: LoadOptions): Promise<SiteData>;