@gjsify/site 0.64.18 → 0.64.19

package/README.md

@@ -49,6 +49,49 @@ gjsify site build --runtime node        # build and run on a specific runtime
 | `--check` | `i18n`: report what is out of date instead of writing it. |
 | `--runtime <r>` | `gjs` \| `node` \| `bun` \| `deno`. Default: the runtime the CLI itself is on. |
 
+## Store listings
+
+`gjsify webext listing` (also `gjsify site listing`) derives the store listing of a browser extension
+from the same sources as the page: the metainfo, the gettext catalogues and the screenshots. It works
+for any extension, not only one built by `gjsify webext build`. See ADR 0135.
+
+```sh
+gjsify webext listing --check                  # validate against the store limits, write nothing
+gjsify webext listing --store amo --out dist/listing
+gjsify webext listing --pot po/listing.pot     # the config strings as a gettext template
+```
+
+It writes `<out>/<store>/<lang>/{name,summary,description}.txt` (plus `description.html` for AMO and
+`permissions.md` for the stores that ask), `<store>/screenshots/*.png`, `<store>/icon*.png` and a
+`listing.json`. Screenshots are scaled down and letterboxed on the `<branding>` light colour to each
+store's exact size; one that would need an enlargement beyond 2× is refused. The metainfo's donation
+URL is never emitted (ADR 0113). Every length is checked and a violation names the field, store,
+language and limit.
+
+Only what the metainfo cannot carry is configured, in `gjsify.webext.listing` of the root
+`package.json` (each key falls back to `gjsify.site`):
+
+```json
+{
+  "gjsify": {
+    "webext": {
+      "listing": {
+        "metainfo": "data/app.metainfo.xml",
+        "singlePurpose": "One sentence: what the extension is for",
+        "permissions": { "tabs": "Why it needs the tab list", "https://*/*": "Why it needs these hosts" },
+        "category": { "cws": "productivity", "edge": "Productivity" },
+        "privacyUrl": "https://example.org/privacy/",
+        "screenshots": "docs/store/screenshots"
+      }
+    }
+  }
+}
+```
+
+`singlePurpose` and the permission justifications are English msgids, translated through the app's
+catalogues like the page strings. The privacy URL comes from `<url type="privacy">`, else
+`privacyUrl`, else `<siteUrl><lang>/privacy/` when `gjsify.site.privacy` is set.
+
 ## Support pages and SEO
 
 With `gjsify.site.support` set, a build also writes `/<base><lang>/support/index.html` (title

package/lib/cli.js

@@ -4,12 +4,15 @@
 // generates a tiny module that calls `runSiteCli`, bundles it for the runtime
 // the CLI itself is on, and runs it — so there is no `gjsify-site` bin bound to
 // one runtime. See `packages/infra/cli/src/commands/site.ts`.
+import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { runListing, STORES } from './listing/index.js';
 import { buildSite, syncSiteI18n } from './site.js';
 const USAGE = `Usage: gjsify site <command> [options]
 
   build [options]    Render the static pages of a repository
   i18n [options]     Update the page catalogues from the strings the build can emit
+  listing [options]  Derive browser-extension store listings (cws, edge, amo) from the metainfo
 
 Options:
   --root <path>      Repository to work on (default: the working directory)
@@ -20,6 +23,10 @@ Options:
   --cache-dir <dir>  Where to keep the response cache and image renditions
                      (default: <root>/node_modules/.cache/gjsify-site)
   --check            i18n: report what is out of date instead of writing it
+  --store <s>        listing: cws | edge | amo | all (default: all)
+  --metainfo <path>  listing: AppStream metainfo, overriding the configured one
+  --config <file>    listing: JSON that overrides \`gjsify.webext.listing\`
+  --pot <file>       listing: write the config strings as a gettext template
   --package          i18n: sync this package's own catalogues instead of a consumer's
   --package-dir <d>  Where @gjsify/site is installed; the client bundle and the
                      shipped catalogues are read from there (default: derived
@@ -71,6 +78,32 @@ async function i18n(flags) {
         console.error(message);
     return untranslated.length > 0 || (check && stale.length > 0) ? 1 : 0;
 }
+async function listing(flags) {
+    const root = resolve(flagValue(flags, '--root') ?? process.cwd());
+    const check = flags.includes('--check');
+    const requested = flagValue(flags, '--store') ?? 'all';
+    if (requested !== 'all' && !STORES.includes(requested))
+        throw new Error(`--store must be one of ${STORES.join(', ')}, all`);
+    const configFile = flagValue(flags, '--config');
+    const pot = flagValue(flags, '--pot');
+    const result = await runListing({
+        root,
+        out: resolve(flagValue(flags, '--out') ?? join(root, 'dist', 'listing')),
+        stores: requested === 'all' ? STORES : [requested],
+        check,
+        config: configFile ? JSON.parse(await readFile(resolve(configFile), 'utf8')) : undefined,
+        metainfo: flagValue(flags, '--metainfo'),
+        pot,
+        offline: flags.includes('--offline'),
+        cacheDir: flagValue(flags, '--cache-dir'),
+        warn: (message) => console.warn(`warning: ${message}`),
+    });
+    for (const issue of result.issues)
+        console.error(`error: ${issue.message}`);
+    if (!check)
+        console.log(`Wrote ${result.files.length} files`);
+    return result.issues.length > 0 ? 1 : 0;
+}
 /**
  * Runs one `gjsify site` invocation and answers the process exit code. Never
  * exits the process itself: under GJS `process.exit` does not halt
@@ -83,6 +116,8 @@ export async function runSiteCli(argv) {
             return await build(flags);
         if (command === 'i18n')
             return await i18n(flags);
+        if (command === 'listing')
+            return await listing(flags);
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : error);

package/lib/index.d.ts

@@ -12,3 +12,4 @@ export * from './render/pages.js';
 export * from './render/qr.js';
 export * from './site-data/index.js';
 export * from './site.js';
+export * from './listing/index.js';

package/lib/index.js

@@ -12,3 +12,4 @@ export * from './render/pages.js';
 export * from './render/qr.js';
 export * from './site-data/index.js';
 export * from './site.js';
+export * from './listing/index.js';

package/lib/listing/build.d.ts

@@ -0,0 +1,42 @@
+import type { Catalog } from '../site-data/po.js';
+import type { Metainfo } from '../site-data/types.js';
+import type { ListingConfig } from './config.js';
+import { type Store } from './limits.js';
+export interface StoreEntry {
+    name: string;
+    summary: string;
+    description: string;
+    descriptionHtml?: string;
+    singlePurpose: string;
+    permissions: Array<{
+        permission: string;
+        justification: string;
+    }>;
+    category?: string;
+    privacyUrl?: string;
+    /** `<url type="homepage">`; the donation URL is never carried (ADR 0113). */
+    homepage?: string;
+    supportUrl?: string;
+}
+export interface Issue {
+    store: Store;
+    language: string;
+    field: string;
+    message: string;
+}
+export interface ListingModel {
+    stores: Partial<Record<Store, Record<string, StoreEntry>>>;
+    issues: Issue[];
+    warnings: string[];
+    /** Every msgid the config blocks asked a catalogue for, for `--pot`. */
+    msgids: string[];
+}
+export interface ListingInput {
+    metainfo: Metainfo;
+    config: ListingConfig;
+    catalogs: Readonly<Record<string, Catalog>>;
+    stores?: readonly Store[];
+}
+/** Error text naming field, store, language and limit. */
+export declare function checkEntry(store: Store, language: string, entry: StoreEntry): Issue[];
+export declare function buildListingModel({ metainfo, config, catalogs, stores }: ListingInput): ListingModel;

package/lib/listing/build.js

@@ -0,0 +1,91 @@
+import { pickByLanguage, resolveLocalized, translator } from '../site-data/po.js';
+import { STORE_SPECS, STORES } from './limits.js';
+import { characters, descriptionHtml, descriptionText } from './text.js';
+/** Error text naming field, store, language and limit. */
+export function checkEntry(store, language, entry) {
+    const spec = STORE_SPECS[store];
+    const issues = [];
+    const add = (field, message) => issues.push({ store, language, field, message: `${spec.label} [${language}] ${field}: ${message}` });
+    for (const field of ['name', 'summary', 'description']) {
+        const limit = spec.text[field];
+        const value = entry[field];
+        if (value === '') {
+            add(field, 'is empty');
+            continue;
+        }
+        if (!limit)
+            continue;
+        const count = characters(value);
+        const note = `${limit.verified ? '' : ' (limit not confirmed by first-party docs) '}${limit.url}`;
+        if (limit.max !== undefined && count > limit.max)
+            add(field, `${count} characters, limit ${limit.max} — ${note}`);
+        if (limit.min !== undefined && count < limit.min)
+            add(field, `${count} characters, minimum ${limit.min} — ${note}`);
+    }
+    if (spec.summaryHasNoUrls && /https?:\/\/|www\./i.test(entry.summary))
+        add('summary', 'must not contain a URL');
+    if (spec.justifiesPermissions) {
+        if (entry.singlePurpose === '')
+            add('singlePurpose', 'is empty (set gjsify.webext.listing.singlePurpose)');
+        for (const { permission, justification } of entry.permissions) {
+            if (justification === '')
+                add(`permissions.${permission}`, 'has no justification');
+        }
+    }
+    if (spec.categoryRequired && !entry.category)
+        add('category', `is not set (gjsify.webext.listing.category.${store})`);
+    return issues;
+}
+export function buildListingModel({ metainfo, config, catalogs, stores = STORES }) {
+    const model = { stores: {}, issues: [], warnings: [], msgids: [] };
+    const used = new Set();
+    for (const language of config.languages) {
+        const catalog = catalogs[language];
+        const isSource = language === config.sourceLanguage;
+        const lookup = translator(catalog);
+        // A config string is a msgid; English needs no catalogue, another language warns once per msgid.
+        const configText = (msgid) => {
+            if (msgid === undefined)
+                return '';
+            used.add(msgid);
+            if (!isSource && !catalog?.has(msgid))
+                model.warnings.push(`"${language}" has no translation of "${msgid}"`);
+            return lookup(msgid);
+        };
+        const app = (text) => {
+            if (!isSource && pickByLanguage(text.byLanguage, language) === undefined && !catalog?.has(text.source)) {
+                model.warnings.push(`"${language}" has no translation of the app text "${text.source.slice(0, 40)}…"`);
+            }
+            return isSource ? text.source : resolveLocalized(text, language, catalog);
+        };
+        const description = metainfo.description;
+        const base = {
+            name: app(metainfo.name),
+            summary: app(metainfo.summary),
+            description: descriptionText(description, app),
+            singlePurpose: configText(config.singlePurpose),
+            permissions: Object.entries(config.permissions).map(([permission, msgid]) => ({
+                permission,
+                justification: configText(msgid),
+            })),
+            privacyUrl: metainfo.urls.privacy ??
+                config.privacyUrl ??
+                (config.siteUrl ? `${config.siteUrl}${language}/privacy/` : undefined),
+            homepage: metainfo.urls.homepage,
+            supportUrl: metainfo.urls.bugtracker,
+        };
+        for (const store of stores) {
+            const spec = STORE_SPECS[store];
+            const entry = {
+                ...base,
+                ...(spec.descriptionHtml ? { descriptionHtml: descriptionHtml(description, app) } : {}),
+                category: config.category[store],
+            };
+            (model.stores[store] ??= {})[language] = entry;
+            model.issues.push(...checkEntry(store, language, entry));
+        }
+    }
+    model.warnings = [...new Set(model.warnings)];
+    model.msgids = [...used];
+    return model;
+}

package/lib/listing/config.d.ts

@@ -0,0 +1,42 @@
+import type { Store } from './limits.js';
+/** The slice of the root package.json the listing reads; `gjsify.site` only supplies fallbacks. */
+export interface ListingManifest {
+    gjsify?: {
+        webext?: {
+            listing?: unknown;
+        };
+        site?: unknown;
+        ship?: {
+            icon?: string;
+        };
+        flatpak?: {
+            icon?: string;
+        };
+    };
+}
+export interface ListingConfig {
+    /** Repo-relative path of the AppStream metainfo. */
+    metainfo: string;
+    languages: string[];
+    sourceLanguage: string;
+    /** Directory of `<lang>.po` catalogues holding the translations of the metainfo and of this block's strings. */
+    translations?: string;
+    repository?: string;
+    /** Repo-relative icon (SVG or PNG). */
+    icon?: string;
+    /** Directory of PNGs used instead of the metainfo screenshots. */
+    screenshots?: string;
+    /** msgid: the single purpose, in one sentence. */
+    singlePurpose?: string;
+    /** permission or host pattern → msgid of its justification. */
+    permissions: Record<string, string>;
+    category: Partial<Record<Store, string>>;
+    privacyUrl?: string;
+    /** Used when the metainfo has no privacy URL and no `privacyUrl` is set: `<siteUrl><lang>/privacy/`. */
+    siteUrl?: string;
+}
+/**
+ * Merges `gjsify.webext.listing` (and `override`, e.g. a `--config` file, which wins) over the
+ * `gjsify.site` values that mean the same thing. Errors name the offending key.
+ */
+export declare function parseListingConfig(manifest: ListingManifest, override?: unknown): ListingConfig;

package/lib/listing/config.js

@@ -0,0 +1,79 @@
+import { isAbsolute } from 'node:path';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function str(raw, key, where) {
+    const value = raw[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value === '')
+        throw new Error(`${where}.${key} must be a non-empty string`);
+    return value;
+}
+/**
+ * Merges `gjsify.webext.listing` (and `override`, e.g. a `--config` file, which wins) over the
+ * `gjsify.site` values that mean the same thing. Errors name the offending key.
+ */
+export function parseListingConfig(manifest, override = undefined) {
+    const own = manifest.gjsify?.webext?.listing;
+    if (own !== undefined && !isRecord(own))
+        throw new Error('gjsify.webext.listing must be an object');
+    if (override !== undefined && !isRecord(override))
+        throw new Error('The listing config must be a JSON object');
+    const raw = { ...own, ...override };
+    const where = 'gjsify.webext.listing';
+    const site = isRecord(manifest.gjsify?.site) ? manifest.gjsify?.site : {};
+    const metainfo = str(raw, 'metainfo', where) ?? (typeof site.metainfo === 'string' ? site.metainfo : undefined);
+    if (!metainfo)
+        throw new Error(`${where}.metainfo is required (or set gjsify.site.metainfo, or pass --metainfo)`);
+    const languages = raw.languages ?? site.languages ?? ['en'];
+    if (!Array.isArray(languages) || languages.length === 0 || !languages.every((entry) => typeof entry === 'string')) {
+        throw new Error(`${where}.languages must be a non-empty list of language codes`);
+    }
+    const permissions = {};
+    if (raw.permissions !== undefined) {
+        if (!isRecord(raw.permissions))
+            throw new Error(`${where}.permissions must map a permission to its justification`);
+        for (const [permission, text] of Object.entries(raw.permissions)) {
+            if (typeof text !== 'string' || text === '')
+                throw new Error(`${where}.permissions["${permission}"] must be a non-empty string`);
+            permissions[permission] = text;
+        }
+    }
+    const category = {};
+    if (raw.category !== undefined) {
+        if (!isRecord(raw.category))
+            throw new Error(`${where}.category must map a store (cws, edge, amo) to a category`);
+        for (const [store, value] of Object.entries(raw.category)) {
+            if (store !== 'cws' && store !== 'edge' && store !== 'amo')
+                throw new Error(`${where}.category.${store}: unknown store (use cws, edge or amo)`);
+            if (typeof value !== 'string' || value === '')
+                throw new Error(`${where}.category.${store} must be a string`);
+            category[store] = value;
+        }
+    }
+    const icon = str(raw, 'icon', where) ??
+        (typeof site.icon === 'string' ? site.icon : (manifest.gjsify?.ship?.icon ?? manifest.gjsify?.flatpak?.icon));
+    const translations = str(raw, 'translations', where) ?? (typeof site.translations === 'string' ? site.translations : undefined);
+    const screenshots = str(raw, 'screenshots', where);
+    for (const [key, value] of [
+        ['screenshots', screenshots],
+        ['translations', translations],
+        ['icon', icon],
+    ]) {
+        if (value !== undefined && isAbsolute(value))
+            throw new Error(`${where}.${key} must be repo-relative`);
+    }
+    return {
+        metainfo,
+        languages: languages,
+        sourceLanguage: str(raw, 'sourceLanguage', where) ?? (typeof site.sourceLanguage === 'string' ? site.sourceLanguage : 'en'),
+        translations,
+        repository: str(raw, 'repository', where) ?? (typeof site.repository === 'string' ? site.repository : undefined),
+        icon,
+        screenshots,
+        singlePurpose: str(raw, 'singlePurpose', where),
+        permissions,
+        category,
+        privacyUrl: str(raw, 'privacyUrl', where),
+        siteUrl: site.privacy !== undefined && typeof site.url === 'string' ? site.url.replace(/\/?$/, '/') : undefined,
+    };
+}

package/lib/listing/fit.d.ts

@@ -0,0 +1,23 @@
+import type { Size } from './limits.js';
+/** Beyond this the pixels are guessed rather than shown; the listing refuses instead of shipping a blur. */
+export declare const MAX_UPSCALE = 2;
+export interface Fit {
+    scale: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The largest placement of `source` inside `box` that keeps the aspect ratio, centred. */
+export declare function fitInto(source: Size, box: Size): Fit;
+/** `#rgb` or `#rrggbb` as `0xRRGGBB`; anything else (alpha forms included) is `undefined`. */
+export declare function parseHexColor(value: string | undefined): number | undefined;
+export type Placement = {
+    ok: true;
+    fit: Fit;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Letterbox placement of `source` on a `box` canvas, or the reason a clean result is impossible. */
+export declare function planPlacement(source: Size, box: Size): Placement;

package/lib/listing/fit.js

@@ -0,0 +1,29 @@
+/** Beyond this the pixels are guessed rather than shown; the listing refuses instead of shipping a blur. */
+export const MAX_UPSCALE = 2;
+/** The largest placement of `source` inside `box` that keeps the aspect ratio, centred. */
+export function fitInto(source, box) {
+    const scale = Math.min(box.width / source.width, box.height / source.height);
+    const width = Math.min(box.width, Math.max(1, Math.round(source.width * scale)));
+    const height = Math.min(box.height, Math.max(1, Math.round(source.height * scale)));
+    return { scale, x: Math.floor((box.width - width) / 2), y: Math.floor((box.height - height) / 2), width, height };
+}
+const HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+/** `#rgb` or `#rrggbb` as `0xRRGGBB`; anything else (alpha forms included) is `undefined`. */
+export function parseHexColor(value) {
+    if (!value || !HEX.test(value))
+        return undefined;
+    const digits = value.slice(1);
+    const full = digits.length === 3 ? [...digits].map((digit) => digit + digit).join('') : digits;
+    return Number.parseInt(full, 16);
+}
+/** Letterbox placement of `source` on a `box` canvas, or the reason a clean result is impossible. */
+export function planPlacement(source, box) {
+    const fit = fitInto(source, box);
+    if (fit.scale > MAX_UPSCALE) {
+        return {
+            ok: false,
+            reason: `${source.width}x${source.height} would be enlarged ${fit.scale.toFixed(1)}x to fit ${box.width}x${box.height} (limit ${MAX_UPSCALE}x)`,
+        };
+    }
+    return { ok: true, fit };
+}

package/lib/listing/images.d.ts

@@ -0,0 +1,27 @@
+import { type ScreenshotOptions } from '../site-data/screenshots.js';
+import type { Metainfo } from '../site-data/types.js';
+import type { Issue } from './build.js';
+import type { ListingConfig } from './config.js';
+import { type Store } from './limits.js';
+export interface SourceShot {
+    file: string;
+    slug: string;
+}
+/** The files to publish: a configured directory of PNGs, else the metainfo's own screenshots. */
+export declare function listingScreenshots(metainfo: Metainfo, config: ListingConfig, root: string, options: Omit<ScreenshotOptions, 'root' | 'repository'>): Promise<SourceShot[]>;
+export interface RenderedImage {
+    name: string;
+    bytes?: Uint8Array;
+}
+/** The background a letterboxed shot sits on: the light brand colour, else white. */
+export declare function letterboxColor(metainfo: Metainfo): number;
+/**
+ * Fits every screenshot onto the store's canvas. A shot that would need a blurry enlargement is an
+ * issue rather than an image. `encode: false` validates geometry without producing bytes.
+ */
+export declare function renderScreenshots(store: Store, shots: readonly SourceShot[], background: number, encode: boolean): {
+    images: RenderedImage[];
+    issues: Issue[];
+};
+/** The icon at the store's edge length, rendered from the SVG (or scaled from a PNG). */
+export declare function renderIcon(store: Store, file: string): RenderedImage;

package/lib/listing/images.js

@@ -0,0 +1,68 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { decodeImageFile, decodeImageFileAtSize } from '../render/image-backend.js';
+import { imageSlug, resolveScreenshots } from '../site-data/screenshots.js';
+import { fitInto, parseHexColor, planPlacement } from './fit.js';
+import { STORE_SPECS } from './limits.js';
+/** The files to publish: a configured directory of PNGs, else the metainfo's own screenshots. */
+export async function listingScreenshots(metainfo, config, root, options) {
+    if (config.screenshots) {
+        const dir = resolve(root, config.screenshots);
+        if (!existsSync(dir))
+            throw new Error(`gjsify.webext.listing.screenshots: "${config.screenshots}" does not exist`);
+        const names = (await readdir(dir)).filter((name) => /\.(png|jpe?g|webp)$/i.test(name)).sort();
+        return names.map((name) => ({ file: join(dir, name), slug: imageSlug(name) }));
+    }
+    if (!config.repository) {
+        throw new Error('Screenshots from the metainfo need gjsify.webext.listing.repository (or gjsify.site.repository)');
+    }
+    const shots = await resolveScreenshots(metainfo, { ...options, root, repository: config.repository });
+    return shots.map(({ file, slug }) => ({ file, slug }));
+}
+/** The background a letterboxed shot sits on: the light brand colour, else white. */
+export function letterboxColor(metainfo) {
+    return parseHexColor(metainfo.branding.light) ?? 0xffffff;
+}
+/**
+ * Fits every screenshot onto the store's canvas. A shot that would need a blurry enlargement is an
+ * issue rather than an image. `encode: false` validates geometry without producing bytes.
+ */
+export function renderScreenshots(store, shots, background, encode) {
+    const spec = STORE_SPECS[store];
+    const images = [];
+    const issues = [];
+    const add = (field, message) => issues.push({ store, language: '*', field, message: `${spec.label} ${field}: ${message}` });
+    if (shots.length < spec.screenshots.min) {
+        add('screenshots', `${shots.length} found, at least ${spec.screenshots.min} required — ${spec.screenshots.url}`);
+    }
+    const kept = shots.slice(0, spec.screenshots.max);
+    if (shots.length > kept.length) {
+        add('screenshots', `${shots.length} found, at most ${spec.screenshots.max} allowed — ${spec.screenshots.url}`);
+    }
+    for (const [index, shot] of kept.entries()) {
+        const source = decodeImageFile(shot.file);
+        const plan = planPlacement(source, spec.screenshots);
+        if (!plan.ok) {
+            add(`screenshots[${index + 1}]`, `${shot.slug}: ${plan.reason}`);
+            continue;
+        }
+        const name = `${String(index + 1).padStart(2, '0')}-${shot.slug}.png`;
+        const bytes = encode ? source.placed(spec.screenshots, plan.fit, background).encode('png') : undefined;
+        images.push({ name, bytes });
+    }
+    return { images, issues };
+}
+/** The icon at the store's edge length, rendered from the SVG (or scaled from a PNG). */
+export function renderIcon(store, file) {
+    const { size } = STORE_SPECS[store].icon;
+    const image = decodeImageFileAtSize(file, size, size);
+    if (image.width !== size || image.height !== size) {
+        const fit = fitInto(image, { width: size, height: size });
+        return {
+            name: `icon-${size}.png`,
+            bytes: image.placed({ width: size, height: size }, fit, 0xffffff).encode('png'),
+        };
+    }
+    return { name: `icon-${size}.png`, bytes: image.encode('png') };
+}

package/lib/listing/index.d.ts

@@ -0,0 +1,7 @@
+export * from './build.js';
+export * from './config.js';
+export * from './fit.js';
+export * from './images.js';
+export * from './limits.js';
+export * from './run.js';
+export * from './text.js';

package/lib/listing/index.js

@@ -0,0 +1,7 @@
+export * from './build.js';
+export * from './config.js';
+export * from './fit.js';
+export * from './images.js';
+export * from './limits.js';
+export * from './run.js';
+export * from './text.js';

package/lib/listing/limits.d.ts

@@ -0,0 +1,36 @@
+export type Store = 'cws' | 'edge' | 'amo';
+export declare const STORES: readonly Store[];
+export type TextField = 'name' | 'summary' | 'description';
+export interface TextLimit {
+    min?: number;
+    max?: number;
+    url: string;
+    verified: boolean;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface StoreSpec {
+    label: string;
+    text: Partial<Record<TextField, TextLimit>>;
+    /** Screenshot canvas, count, and the page that states them. */
+    screenshots: Size & {
+        min: number;
+        max: number;
+        url: string;
+    };
+    /** Square icon edge in pixels. */
+    icon: {
+        size: number;
+        url: string;
+    };
+    /** Summaries may not contain URLs (AMO enforces this server-side). */
+    summaryHasNoUrls?: boolean;
+    /** Emit `description.html` next to the plain text. */
+    descriptionHtml?: boolean;
+    /** Needs one justification per permission and a single-purpose statement. */
+    justifiesPermissions: boolean;
+    categoryRequired: boolean;
+}
+export declare const STORE_SPECS: Record<Store, StoreSpec>;

package/lib/listing/limits.js

@@ -0,0 +1,59 @@
+// What each store accepts, with the page that says so. `verified: false` marks a number that no
+// first-party document states (ADR 0135 lists them); the check still enforces it, because an
+// unverified ceiling that is too low is a message to fix, while one that is too high ships a rejection.
+export const STORES = ['cws', 'edge', 'amo'];
+const CWS_IMAGES = 'https://developer.chrome.com/docs/webstore/images';
+const EDGE_PUBLISH = 'https://learn.microsoft.com/en-us/microsoft-edge/extensions/publish/publish-extension';
+const AMO_LISTING = 'https://extensionworkshop.com/documentation/develop/create-an-appealing-listing/';
+export const STORE_SPECS = {
+    cws: {
+        label: 'Chrome Web Store',
+        text: {
+            name: {
+                max: 75,
+                url: 'https://developer.chrome.com/docs/extensions/reference/manifest/name',
+                verified: true,
+            },
+            summary: {
+                max: 132,
+                url: 'https://developer.chrome.com/docs/extensions/reference/manifest/description',
+                verified: true,
+            },
+            description: {
+                max: 16000,
+                url: 'https://developer.chrome.com/docs/webstore/cws-dashboard-listing',
+                verified: false,
+            },
+        },
+        screenshots: { width: 1280, height: 800, min: 1, max: 5, url: CWS_IMAGES },
+        icon: { size: 128, url: CWS_IMAGES },
+        justifiesPermissions: true,
+        categoryRequired: true,
+    },
+    edge: {
+        label: 'Edge Add-ons',
+        text: {
+            // Name and short description are read from the manifest; the manifest ceilings are Chromium's.
+            name: { max: 75, url: EDGE_PUBLISH, verified: false },
+            summary: { max: 132, url: EDGE_PUBLISH, verified: false },
+            description: { min: 250, max: 10000, url: EDGE_PUBLISH, verified: true },
+        },
+        screenshots: { width: 1280, height: 800, min: 1, max: 6, url: EDGE_PUBLISH },
+        icon: { size: 300, url: EDGE_PUBLISH },
+        justifiesPermissions: true,
+        categoryRequired: true,
+    },
+    amo: {
+        label: 'Firefox Add-ons (AMO)',
+        text: {
+            name: { max: 50, url: AMO_LISTING, verified: true },
+            summary: { max: 250, url: AMO_LISTING, verified: true },
+        },
+        screenshots: { width: 1280, height: 800, min: 1, max: 10, url: AMO_LISTING },
+        icon: { size: 128, url: 'https://mozilla.github.io/addons-server/topics/api/addons.html' },
+        summaryHasNoUrls: true,
+        descriptionHtml: true,
+        justifiesPermissions: false,
+        categoryRequired: false,
+    },
+};

package/lib/listing/run.d.ts

@@ -0,0 +1,25 @@
+import { type Issue, type StoreEntry } from './build.js';
+import { type Store } from './limits.js';
+export interface ListingOptions {
+    root: string;
+    out: string;
+    stores?: readonly Store[];
+    /** Validate only; nothing is written. */
+    check?: boolean;
+    /** Override of the `gjsify.webext.listing` block (a `--config` file). */
+    config?: unknown;
+    /** Overrides `metainfo` of the config. */
+    metainfo?: string;
+    /** Write the config strings as a `.pot` template here. */
+    pot?: string;
+    offline?: boolean;
+    cacheDir?: string;
+    warn?: (message: string) => void;
+}
+export interface ListingResult {
+    issues: Issue[];
+    warnings: string[];
+    files: string[];
+}
+export declare function permissionsMarkdown(entry: StoreEntry): string;
+export declare function runListing(options: ListingOptions): Promise<ListingResult>;

package/lib/listing/run.js

@@ -0,0 +1,109 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { renderPo } from '../render/i18n.js';
+import { parseMetainfo } from '../site-data/metainfo.js';
+import { loadCatalogs } from '../site-data/load.js';
+import { buildListingModel } from './build.js';
+import { parseListingConfig } from './config.js';
+import { letterboxColor, listingScreenshots, renderIcon, renderScreenshots } from './images.js';
+import { STORE_SPECS, STORES } from './limits.js';
+export function permissionsMarkdown(entry) {
+    const rows = entry.permissions.map(({ permission, justification }) => `| \`${permission}\` | ${justification.replace(/\|/g, '\\|')} |`);
+    return [
+        '# Privacy practices',
+        '',
+        '## Single purpose',
+        '',
+        entry.singlePurpose || '_not set_',
+        '',
+        '## Permission justifications',
+        '',
+        ...(rows.length > 0
+            ? ['| Permission | Justification |', '| --- | --- |', ...rows]
+            : ['_No permissions declared._']),
+        '',
+        ...(entry.privacyUrl ? ['## Privacy policy', '', entry.privacyUrl, ''] : []),
+    ].join('\n');
+}
+const ensureNewline = (text) => (text.endsWith('\n') ? text : `${text}\n`);
+export async function runListing(options) {
+    const warn = options.warn ?? (() => { });
+    const root = resolve(options.root);
+    const manifestFile = join(root, 'package.json');
+    if (!existsSync(manifestFile))
+        throw new Error(`No package.json in ${root}`);
+    const manifest = JSON.parse(await readFile(manifestFile, 'utf8'));
+    const config = parseListingConfig(manifest, {
+        ...options.config,
+        ...(options.metainfo ? { metainfo: options.metainfo } : {}),
+    });
+    const metainfo = parseMetainfo(await readFile(resolve(root, config.metainfo), 'utf8'));
+    const catalogs = config.translations
+        ? await loadCatalogs(resolve(root, config.translations), config.languages)
+        : {};
+    const stores = options.stores ?? STORES;
+    const model = buildListingModel({ metainfo, config, catalogs, stores });
+    const issues = [...model.issues];
+    const warnings = [...model.warnings];
+    if (!config.translations && config.languages.some((language) => language !== config.sourceLanguage)) {
+        warnings.push('No translations directory: set gjsify.webext.listing.translations (a directory of .po files)');
+    }
+    const shots = await listingScreenshots(metainfo, config, root, {
+        cacheDir: options.cacheDir,
+        offline: options.offline,
+        warn: (message) => warnings.push(message),
+    });
+    const background = letterboxColor(metainfo);
+    const iconFile = config.icon ? resolve(root, config.icon) : undefined;
+    if (!iconFile || !existsSync(iconFile))
+        warnings.push('No icon: set gjsify.webext.listing.icon (or gjsify.site.icon)');
+    const out = resolve(options.out);
+    const write = !options.check;
+    const files = [];
+    const emit = async (path, data) => {
+        if (!write)
+            return;
+        const target = join(out, path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, data);
+        files.push(path);
+    };
+    if (write)
+        await rm(out, { recursive: true, force: true });
+    const index = {};
+    for (const store of stores) {
+        const entries = model.stores[store] ?? {};
+        const shotResult = renderScreenshots(store, shots, background, write);
+        issues.push(...shotResult.issues);
+        for (const [language, entry] of Object.entries(entries)) {
+            const dir = `${store}/${language}`;
+            await emit(`${dir}/name.txt`, ensureNewline(entry.name));
+            await emit(`${dir}/summary.txt`, ensureNewline(entry.summary));
+            await emit(`${dir}/description.txt`, ensureNewline(entry.description));
+            if (entry.descriptionHtml !== undefined)
+                await emit(`${dir}/description.html`, ensureNewline(entry.descriptionHtml));
+            if (STORE_SPECS[store].justifiesPermissions)
+                await emit(`${dir}/permissions.md`, permissionsMarkdown(entry));
+        }
+        const icon = iconFile && existsSync(iconFile) ? renderIcon(store, iconFile) : undefined;
+        if (icon?.bytes)
+            await emit(`${store}/${icon.name}`, icon.bytes);
+        for (const image of shotResult.images)
+            if (image.bytes)
+                await emit(`${store}/screenshots/${image.name}`, image.bytes);
+        index[store] = {
+            languages: entries,
+            screenshots: shotResult.images.map((image) => `screenshots/${image.name}`),
+            icon: icon?.name,
+        };
+    }
+    await emit('listing.json', `${JSON.stringify({ version: 1, app: metainfo.id, stores: index }, null, 2)}\n`);
+    if (options.pot) {
+        await writeFile(resolve(options.pot), renderPo(model.msgids, undefined));
+        files.push(options.pot);
+    }
+    for (const message of warnings)
+        warn(message);
+    return { issues, warnings, files };
+}

package/lib/listing/text.d.ts

@@ -0,0 +1,9 @@
+import type { DescriptionBlock, Localized } from '../site-data/types.js';
+type Resolve = (text: Localized) => string;
+/** Paragraphs separated by a blank line, list items as `• item` — what every store's textarea shows. */
+export declare function descriptionText(blocks: readonly DescriptionBlock[], resolve: Resolve): string;
+/** The conservative subset (`p`, `ul`, `li`) every HTML sanitiser a store runs keeps. */
+export declare function descriptionHtml(blocks: readonly DescriptionBlock[], resolve: Resolve): string;
+/** Code points, not UTF-16 units: the stores count what a person sees. */
+export declare function characters(value: string): number;
+export {};

package/lib/listing/text.js

@@ -0,0 +1,21 @@
+import { esc } from '../render/html.js';
+/** Paragraphs separated by a blank line, list items as `• item` — what every store's textarea shows. */
+export function descriptionText(blocks, resolve) {
+    return blocks
+        .map((block) => block.type === 'paragraph'
+        ? resolve(block.text)
+        : block.items.map((item) => `• ${resolve(item)}`).join('\n'))
+        .join('\n\n');
+}
+/** The conservative subset (`p`, `ul`, `li`) every HTML sanitiser a store runs keeps. */
+export function descriptionHtml(blocks, resolve) {
+    return blocks
+        .map((block) => block.type === 'paragraph'
+        ? `<p>${esc(resolve(block.text))}</p>`
+        : `<ul>\n${block.items.map((item) => `  <li>${esc(resolve(item))}</li>`).join('\n')}\n</ul>`)
+        .join('\n');
+}
+/** Code points, not UTF-16 units: the stores count what a person sees. */
+export function characters(value) {
+    return [...value].length;
+}

package/lib/render/image-backend.d.ts

@@ -21,9 +21,22 @@ export interface RasterImage {
     /** Keeps the aspect ratio. Never enlarges: a width at or above this one answers the same image. */
     /** `nearest` keeps pixel art's hard edges; the default resamples smoothly. */
     resizedToWidth(width: number, filter?: 'smooth' | 'nearest'): RasterImage;
+    /**
+     * A canvas of `canvas` size filled with the opaque colour `background` (`0xRRGGBB`), with this image
+     * scaled to `at.width` x `at.height` and composited at `at.x`, `at.y`. The answer has no alpha channel.
+     */
+    placed(canvas: {
+        width: number;
+        height: number;
+    }, at: Rect, background: number): RasterImage;
     encode(format: ImageFormat): Uint8Array;
 }
 export declare function decodeImageFile(path: string): RasterImage;
+/**
+ * Decodes at an exact size; for an SVG that is a crisp render, for a raster a plain scale. Goes
+ * through the loader rather than `new_from_file_at_scale`, which does not sniff an SVG here.
+ */
+export declare function decodeImageFileAtSize(path: string, width: number, height: number): RasterImage;
 export declare function decodeImageBytes(bytes: Uint8Array): RasterImage;
 /** Rasterises an SVG document at its own size, through the same loader set as the screenshots. */
 export declare function svgToPng(svg: string): Uint8Array;

package/lib/render/image-backend.js

@@ -17,6 +17,7 @@
 // from `ImageFormat`: JPEG. `save_to_bufferv('jpeg', …)` fails on an RGBA
 // pixbuf ("the encoder or decoder for Jpeg does not support the color type
 // `Rgba8`"), and screenshots of a window are RGBA.
+import { readFileSync } from 'node:fs';
 import GdkPixbuf from 'gi://GdkPixbuf?version=2.0';
 /** Encoder options per format, matching what the renditions were tuned to. */
 const ENCODER = {
@@ -103,6 +104,17 @@ function wrap(pixbuf) {
                 throw new Error(`Could not scale an image to ${target}px`);
             return wrap(scaled);
         },
+        placed(canvas, at, background) {
+            const target = GdkPixbuf.Pixbuf.new(GdkPixbuf.Colorspace.RGB, false, 8, canvas.width, canvas.height);
+            if (!target)
+                throw new Error(`Could not allocate a ${canvas.width}x${canvas.height} canvas`);
+            target.fill((((background & 0xffffff) << 8) | 0xff) >>> 0);
+            const scaled = pixbuf.scale_simple(at.width, at.height, GdkPixbuf.InterpType.HYPER);
+            if (!scaled)
+                throw new Error(`Could not scale an image to ${at.width}x${at.height}`);
+            scaled.composite(target, at.x, at.y, at.width, at.height, at.x, at.y, 1, 1, GdkPixbuf.InterpType.NEAREST, 255);
+            return wrap(target);
+        },
         encode(format) {
             assertEncodable(format);
             const { keys, values } = ENCODER[format];
@@ -119,6 +131,30 @@ export function decodeImageFile(path) {
         throw new Error(`Could not decode ${path}`);
     return wrap(pixbuf);
 }
+/**
+ * glycin decides "is this an SVG" from the first bytes, and a long licence comment ahead of `<svg`
+ * makes it answer `application/xml`; the prologue carries nothing a render needs.
+ */
+function svgWithoutPrologue(bytes) {
+    const text = new TextDecoder().decode(bytes);
+    const root = text.search(/<svg[\s>]/);
+    return root > 0 ? new TextEncoder().encode(text.slice(root)) : bytes;
+}
+/**
+ * Decodes at an exact size; for an SVG that is a crisp render, for a raster a plain scale. Goes
+ * through the loader rather than `new_from_file_at_scale`, which does not sniff an SVG here.
+ */
+export function decodeImageFileAtSize(path, width, height) {
+    const loader = new GdkPixbuf.PixbufLoader();
+    loader.set_size(width, height);
+    const bytes = new Uint8Array(readFileSync(path));
+    loader.write(path.toLowerCase().endsWith('.svg') ? svgWithoutPrologue(bytes) : bytes);
+    loader.close();
+    const pixbuf = loader.get_pixbuf();
+    if (!pixbuf)
+        throw new Error(`Could not decode ${path}`);
+    return wrap(pixbuf);
+}
 export function decodeImageBytes(bytes) {
     const loader = new GdkPixbuf.PixbufLoader();
     loader.write(bytes);

package/lib/site-data/metainfo.js

@@ -86,6 +86,7 @@ const URL_KEYS = {
     faq: 'faq',
     contact: 'contact',
     contribute: 'contribute',
+    privacy: 'privacy',
 };
 /** Links are rendered as `href`, so `javascript:` and friends are dropped. */
 const SAFE_URL = /^(https?:|mailto:)/i;

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

@@ -306,6 +306,7 @@ export interface AppUrls {
     faq?: string;
     contact?: string;
     contribute?: string;
+    privacy?: string;
 }
 /** What the AppStream metainfo says, before any site configuration is mixed in. */
 export interface Metainfo {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/site",
-    "version": "0.64.18",
+    "version": "0.64.19",
     "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,21 +54,21 @@
     "license": "MIT",
     "dependencies": {
         "@girs/gdkpixbuf-2.0": "5.4.0",
-        "@gjsify/console": "^0.64.18",
-        "@gjsify/crypto": "^0.64.18",
-        "@gjsify/fs": "^0.64.18",
-        "@gjsify/module": "^0.64.18",
-        "@gjsify/os": "^0.64.18",
-        "@gjsify/path": "^0.64.18",
-        "@gjsify/process": "^0.64.18",
-        "@gjsify/url": "^0.64.18",
+        "@gjsify/console": "^0.64.19",
+        "@gjsify/crypto": "^0.64.19",
+        "@gjsify/fs": "^0.64.19",
+        "@gjsify/module": "^0.64.19",
+        "@gjsify/os": "^0.64.19",
+        "@gjsify/path": "^0.64.19",
+        "@gjsify/process": "^0.64.19",
+        "@gjsify/url": "^0.64.19",
         "fast-xml-parser": "^5.11.2",
         "qrcode-generator": "^2.0.4"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.64.18",
+        "@gjsify/cli": "^0.64.19",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",
-        "@gjsify/unit": "^0.64.18",
+        "@gjsify/unit": "^0.64.19",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },