@gjsify/site 0.0.0-stage → 0.62.0

package/lib/client/site.js

@@ -0,0 +1 @@
+function enhanceDialog(e,t){let n=e.querySelector(`.dialog-close`);n&&(n.hidden=!1,n.addEventListener(`click`,()=>e.close())),t?.addEventListener(`click`,t=>{t.preventDefault(),e.showModal()}),e.addEventListener(`click`,t=>{t.target===e&&e.close()})}const e={linux:`x86_64`,darwin:`arm64`,win32:`x86_64`,android:`arm64`,web:`noarch`};function detectOs(e){let t=`${e.platform??``} ${e.userAgent??``}`;if(/android/i.test(t))return`android`;if(/iphone|ipad|ipod|\bios\b/i.test(t))return`web`;if(/mac|darwin/i.test(t))return`darwin`;if(/win/i.test(t))return`win32`;if(/linux|x11|bsd|cros|chrome ?os/i.test(t))return`linux`}function detectArch(e){if(e.architecture)return e.bitness===`32`?void 0:/arm/i.test(e.architecture)?`arm64`:/x86|amd/i.test(e.architecture)?`x86_64`:void 0;let t=e.userAgent??``;if(/arm64|aarch64/i.test(t))return`arm64`;if(/x86_64|x86-64|amd64|win64|wow64|\bx64\b/i.test(t))return`x86_64`}function detectBrowser(e){let t=e.userAgent??``;if(/firefox|fxios/i.test(t))return`firefox`;if(e.brands?.some(e=>/chromium|chrome|edge|opera|brave/i.test(e))||/chrome|chromium|crios|edg(a|ios)?\/|opr\//i.test(t))return`chromium`}function detectVisitorPlatform(t){let n=detectOs(t),r=detectArch(t);return{os:n,browser:detectBrowser(t),arch:r??(n?e[n]:void 0),archAssumed:r===void 0}}const t=[`firefox`,`chromium`];function isBrowserList(e){return e.length>0&&e.every(e=>t.includes(e.os))}function inGroup(e,n){return t.includes(n)?{...e,browser:n}:{...e,os:n}}function recommendTarget(e,t){let n=isBrowserList(e)?t.browser:t.os;if(!n)return;let r=e.filter(e=>e.os===n&&e.available!==!1),fits=e=>e.arch===`noarch`||e.arch===t.arch;return r.find(e=>e.recommended&&fits(e))??r.find(fits)??r.find(e=>e.recommended)??r[0]}async function readHints(){let e=navigator.userAgentData,t={platform:e?.platform,userAgent:navigator.userAgent,brands:e?.brands?.map(e=>e.brand)};if(e?.getHighEntropyValues)try{let n=await e.getHighEntropyValues([`architecture`,`bitness`]);t.architecture=n.architecture,t.bitness=n.bitness}catch{}return t}function readRows(e){return[...e.querySelectorAll(`li.target`)].flatMap(e=>{let t=e.querySelector(`a`),n=e.dataset.os,r=e.dataset.arch;return!t||!n||!r?[]:[{os:n,arch:r,recommended:e.dataset.recommended!==void 0,url:t.href,cta:e.dataset.cta??t.textContent?.trim()??``,size:e.dataset.size??``}]})}var AppDownload=class extends HTMLElement{connectedCallback(){let e=this.querySelector(`dialog`),t=this.querySelector(`a.download-cta`);if(!e||!t)return;this.dataset.enhanced=`true`,enhanceDialog(e,this.querySelector(`.download-toggle`));let n=readRows(this),r=[...this.querySelectorAll(`.os-group`)],i=[...this.querySelectorAll(`.os-tab`)],a=this.querySelector(`.os-tabs`),o=i.length>1;a&&o&&(a.hidden=!1);let s={os:void 0,arch:void 0,browser:void 0,archAssumed:!0},show=e=>{for(let t of r)t.hidden=o&&t.dataset.os!==e;for(let t of i){let n=t.dataset.os===e;t.setAttribute(`aria-selected`,String(n)),t.tabIndex=n?0:-1}},offer=e=>{t.href=e.url,t.dataset.os=e.os,t.dataset.arch=e.arch;let n=t.querySelector(`.download-label`);n&&(n.textContent=e.cta);let r=document.querySelector(`.badge-size`),i=r?.querySelector(`.badge-value`);if(r&&i){i.textContent=e.size,r.hidden=e.size===``;let t=r.closest(`.badges`);if(t){let e=[...t.children].filter(e=>!e.hidden).length;t.style.setProperty(`--badge-count`,String(e)),t.toggleAttribute(`data-odd`,e%2==1)}}},select=e=>{show(e);let t=recommendTarget(n,inGroup(s,e));t&&offer(t)},c=i.find(e=>e.getAttribute(`aria-selected`)===`true`)?.dataset.os;c&&show(c);for(let e of i)e.addEventListener(`click`,()=>{let t=e.dataset.os;t&&select(t)});a?.addEventListener(`keydown`,e=>{let t=i.indexOf(document.activeElement);if(t===-1)return;let n={ArrowRight:t+1,ArrowLeft:t-1,Home:0,End:i.length-1}[e.key];if(n===void 0)return;e.preventDefault();let r=i[(n+i.length)%i.length];r?.focus(),r?.click()}),readHints().then(e=>{s=detectVisitorPlatform(e);let t=recommendTarget(n,s);t&&(show(t.os),offer(t))})}};customElements.define(`app-download`,AppDownload);function enhanceCopy(e){let t=e.querySelector(`span`),n=t?.textContent??``;navigator.clipboard&&(e.hidden=!1,e.addEventListener(`click`,async()=>{try{await navigator.clipboard.writeText(e.dataset.copy??``)}catch{return}t&&(t.textContent=e.dataset.done??n),setTimeout(()=>{t&&(t.textContent=n)},2e3)}))}var AppSupport=class extends HTMLElement{connectedCallback(){let e=this.querySelector(`dialog`);if(e){this.dataset.enhanced=`true`,enhanceDialog(e,this.querySelector(`.support-cta`));for(let e of this.querySelectorAll(`.sepa-copy`))enhanceCopy(e)}}};customElements.define(`app-support`,AppSupport);var ReleaseNotes=class extends HTMLElement{connectedCallback(){let e=this.querySelector(`.release-body`),t=this.querySelector(`.release-more`);if(!e||!t)return;this.dataset.enhanced=`true`;let n=this.dataset.more??t.textContent??``,r=this.dataset.less??n;if(e.classList.add(`clamped`),e.scrollHeight<=e.clientHeight){e.classList.remove(`clamped`);return}t.hidden=!1,t.textContent=n,t.setAttribute(`aria-expanded`,`false`),t.addEventListener(`click`,()=>{let i=e.classList.toggle(`clamped`);t.textContent=i?n:r,t.setAttribute(`aria-expanded`,String(!i))})}};customElements.define(`release-notes`,ReleaseNotes);var ScreenshotCarousel=class extends HTMLElement{connectedCallback(){let e=this.querySelector(`.carousel-track`),t=[...this.querySelectorAll(`.slide`)];if(!e||t.length===0)return;this.dataset.enhanced=`true`,e.tabIndex=0;let n=matchMedia(`(prefers-reduced-motion: reduce)`),r=[...this.querySelectorAll(`.carousel-dot`)],i=this.querySelector(`.carousel-prev`),a=this.querySelector(`.carousel-next`),o=[this.querySelector(`.carousel-dots`),i,a];if(t.length>1)for(let e of o)e&&(e.hidden=!1);let s=0,clamp=e=>Math.max(0,Math.min(e,t.length-1)),goTo=r=>{let i=t[clamp(r)];if(!i)return;let a=i.offsetLeft-e.offsetLeft-(e.clientWidth-i.clientWidth)/2;e.scrollTo({left:a,behavior:n.matches?`auto`:`smooth`})},mark=e=>{s=e;for(let[t,n]of r.entries())n.setAttribute(`aria-current`,String(t===e));i&&(i.disabled=e===0),a&&(a.disabled=e===t.length-1)};mark(0),i?.addEventListener(`click`,()=>goTo(s-1)),a?.addEventListener(`click`,()=>goTo(s+1));for(let[e,t]of r.entries())t.addEventListener(`click`,()=>goTo(e));let arrowStep=e=>e===`ArrowRight`?1:e===`ArrowLeft`?-1:0;e.addEventListener(`keydown`,e=>{let t=arrowStep(e.key);t!==0&&(e.preventDefault(),goTo(s+t))});let c=new IntersectionObserver(e=>{for(let n of e)n.isIntersecting&&mark(t.indexOf(n.target))},{root:e,threshold:.6});for(let e of t)c.observe(e);let l=this.querySelector(`.lightbox`),u=l?.querySelector(`figure`);if(!l||!u)return;let open=e=>{let n=t[clamp(e)]?.querySelector(`figure`);if(!n)return;s=clamp(e);let r=[...n.children].filter(e=>!e.classList.contains(`slide-expand`));u.replaceChildren(...r.map(e=>e.cloneNode(!0))),l.open||l.showModal()};for(let[e,n]of t.entries()){let t=n.querySelector(`.slide-expand`);t&&(t.hidden=!1,t.addEventListener(`click`,()=>open(e)))}enhanceDialog(l,null),l.addEventListener(`keydown`,e=>{let t=arrowStep(e.key);t!==0&&(e.preventDefault(),open(s+t),goTo(s))})}};customElements.define(`screenshot-carousel`,ScreenshotCarousel);

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+export * from './render/html.js';
+export * from './cli.js';
+export * from './render/i18n.js';
+export * from './render/icons.js';
+export * from './render/images.js';
+export * from './render/pages.js';
+export * from './render/qr.js';
+export * from './site-data/index.js';
+export * from './site.js';

package/lib/index.js

@@ -0,0 +1,9 @@
+export * from './render/html.js';
+export * from './cli.js';
+export * from './render/i18n.js';
+export * from './render/icons.js';
+export * from './render/images.js';
+export * from './render/pages.js';
+export * from './render/qr.js';
+export * from './site-data/index.js';
+export * from './site.js';

package/lib/render/color.d.ts

@@ -0,0 +1,12 @@
+/** `#rgb`, `#rgba`, `#rrggbb` and `#rrggbbaa` as 0–255 channels; alpha is ignored, the band is opaque. */
+export declare function parseHex(hex: string): [number, number, number] | undefined;
+/** WCAG 2 relative luminance, 0 (black) to 1 (white). */
+export declare function relativeLuminance(rgb: readonly [number, number, number]): number;
+/** WCAG 2 contrast ratio, 1 (identical) to 21 (black on white). */
+export declare function contrastRatio(a: number, b: number): number;
+/**
+ * The text colour to put on `background` — whichever of near-black and white the eye can read
+ * better. An unparseable colour answers white, which is what the stylesheet assumed before any of
+ * this was measured.
+ */
+export declare function readableText(background: string): string;

package/lib/render/color.js

@@ -0,0 +1,45 @@
+// The app's `<branding>` colour paints the masthead, so the text on it has to be chosen for that
+// colour rather than hardcoded. CSS cannot measure a colour — `color-contrast()` is not shipped
+// anywhere this page targets — so the generator measures it and writes the answer into a custom
+// property.
+/** `#rgb`, `#rgba`, `#rrggbb` and `#rrggbbaa` as 0–255 channels; alpha is ignored, the band is opaque. */
+export function parseHex(hex) {
+    const digits = hex.replace(/^#/, '');
+    const short = digits.length === 3 || digits.length === 4;
+    if (!short && digits.length !== 6 && digits.length !== 8)
+        return undefined;
+    if (!/^[0-9a-f]+$/i.test(digits))
+        return undefined;
+    const channel = (index) => short ? parseInt(digits[index].repeat(2), 16) : parseInt(digits.slice(index * 2, index * 2 + 2), 16);
+    return [channel(0), channel(1), channel(2)];
+}
+/** WCAG 2 relative luminance, 0 (black) to 1 (white). */
+export function relativeLuminance(rgb) {
+    const [r, g, b] = rgb.map((value) => {
+        const channel = value / 255;
+        return channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** WCAG 2 contrast ratio, 1 (identical) to 21 (black on white). */
+export function contrastRatio(a, b) {
+    const [light, dark] = a >= b ? [a, b] : [b, a];
+    return (light + 0.05) / (dark + 0.05);
+}
+/** Near-black rather than black: a flat #000 on a saturated colour reads as a hole. */
+const INK = '#10233b';
+const PAPER = '#ffffff';
+/**
+ * The text colour to put on `background` — whichever of near-black and white the eye can read
+ * better. An unparseable colour answers white, which is what the stylesheet assumed before any of
+ * this was measured.
+ */
+export function readableText(background) {
+    const rgb = parseHex(background);
+    if (!rgb)
+        return PAPER;
+    const luminance = relativeLuminance(rgb);
+    const onInk = contrastRatio(luminance, relativeLuminance(parseHex(INK)));
+    const onPaper = contrastRatio(luminance, relativeLuminance(parseHex(PAPER)));
+    return onInk >= onPaper ? INK : PAPER;
+}

package/lib/render/html.d.ts

@@ -0,0 +1,8 @@
+/** Escapes text for element content and double-quoted attribute values. */
+export declare function esc(value: string | number): string;
+/** Replaces `{name}` placeholders in a translated string; values are escaped, the template is trusted. */
+export declare function fmt(template: string, values: Record<string, string | number>): string;
+/** Renders attributes, dropping the `undefined`/`false` ones. */
+export declare function attrs(values: Record<string, string | number | boolean | undefined>): string;
+/** Like `fmt`, for values that are escaped later (attribute values, `esc`-wrapped text). */
+export declare function plain(template: string, values: Record<string, string | number>): string;

package/lib/render/html.js

@@ -0,0 +1,20 @@
+const ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+/** Escapes text for element content and double-quoted attribute values. */
+export function esc(value) {
+    return String(value).replace(/[&<>"']/g, (char) => ENTITIES[char] ?? char);
+}
+/** Replaces `{name}` placeholders in a translated string; values are escaped, the template is trusted. */
+export function fmt(template, values) {
+    return esc(template).replace(/\{(\w+)\}/g, (_match, key) => key in values ? esc(values[key]) : `{${key}}`);
+}
+/** Renders attributes, dropping the `undefined`/`false` ones. */
+export function attrs(values) {
+    return Object.entries(values)
+        .filter(([, value]) => value !== undefined && value !== false)
+        .map(([key, value]) => (value === true ? ` ${key}` : ` ${key}="${esc(value)}"`))
+        .join('');
+}
+/** Like `fmt`, for values that are escaped later (attribute values, `esc`-wrapped text). */
+export function plain(template, values) {
+    return template.replace(/\{(\w+)\}/g, (_match, key) => (key in values ? String(values[key]) : `{${key}}`));
+}

package/lib/render/i18n.d.ts

@@ -0,0 +1,38 @@
+import { type Catalog, type SiteConfig } from '../site-data/index.js';
+/**
+ * The msgids the renderer itself can emit: every translator call in its sources, plus the default
+ * download labels. They belong to this package and are translated in its own `po/`.
+ */
+export declare function rendererMsgids(renderDir: string): Promise<string[]>;
+/**
+ * The msgids a configuration introduces: the download labels its author wrote. They belong to the
+ * consumer and are translated in the consumer's `pageTranslations`. Screenshot captions are not
+ * among them — they live in the metainfo and are translated there.
+ */
+export declare function configMsgids(config: SiteConfig): string[];
+/** Every msgid in a `.po`/`.pot` file, translated or not, header excluded. */
+export declare function catalogMsgids(file: string): Promise<Set<string>>;
+/** Writes a catalogue: the translations in `known` are kept, everything else is left empty. */
+export declare function renderPo(msgids: readonly string[], language: string | undefined, known?: Catalog): string;
+export declare function poPath(poDir: string, language: string): string;
+export interface I18nResult {
+    /** Files whose content differs from what the build would write (written unless `check`). */
+    stale: string[];
+    /** Languages with msgids that still lack a translation. */
+    untranslated: string[];
+}
+export interface SyncOptions {
+    /** Directory the `<lang>.po` catalogues live in; created by the caller. */
+    dir: string;
+    /** The languages to keep a catalogue for; `en` is the msgid language and gets none. */
+    languages: readonly string[];
+    msgids: readonly string[];
+    /** Report what would change instead of writing it. */
+    check: boolean;
+    /** Write a `site.pot` template next to the catalogues. An overlay has no template of its own. */
+    pot?: boolean;
+    /** The paths in the result are reported relative to this directory. */
+    base: string;
+}
+/** Regenerates the catalogues of one directory, or with `check` only reports what would change. */
+export declare function syncCatalogs(options: SyncOptions): Promise<I18nResult>;

package/lib/render/i18n.js

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { DOWNLOAD_LABELS, FORMAT_LABELS, UI_SOURCE_LANGUAGE, languageCandidates, parseCatalog, parsePo, quotePo, } from '../site-data/index.js';
+// EITHER quote style, because the formatter picks one and this is not its decision. The renderers
+// were written with double quotes, and the first `gjsify format` that could see them — .gitignore
+// had hidden the directory — rewrote all 66 translator calls to single quotes; a double-quote-only
+// pattern then extracted nothing and the sync offered to delete every translated string in `po/`.
+// Hence also the floor below: an extractor that matches nothing must fail, never quietly empty the
+// catalogues. Note that this pattern reads THIS file too, so no prose here spells out a call.
+const T_CALL = /\bt\(\s*(['"])((?:\\.|(?!\1)[^\\])*)\1\s*\)/g;
+/** Decodes a JS string literal body, whichever quote style it was written in. */
+function unquote(body, quote) {
+    const json = quote === '"' ? body : body.replace(/\\'/g, "'").replace(/"/g, '\\"');
+    return JSON.parse(`"${json}"`);
+}
+/**
+ * The msgids the renderer itself can emit: every translator call in its sources, plus the default
+ * download labels. They belong to this package and are translated in its own `po/`.
+ */
+export async function rendererMsgids(renderDir) {
+    const msgids = new Set();
+    let fromSources = 0;
+    for (const file of (await readdir(renderDir)).sort()) {
+        if (!file.endsWith('.ts') || file.endsWith('.spec.ts'))
+            continue;
+        const source = await readFile(join(renderDir, file), 'utf8');
+        for (const match of source.matchAll(T_CALL)) {
+            msgids.add(unquote(match[2], match[1]));
+            fromSources++;
+        }
+    }
+    if (fromSources === 0) {
+        throw new Error(`${renderDir}: no translator call found in any renderer — the extractor is broken, not the sources`);
+    }
+    for (const label of [...Object.values(DOWNLOAD_LABELS), ...Object.values(FORMAT_LABELS)])
+        msgids.add(label);
+    return [...msgids];
+}
+/**
+ * The msgids a configuration introduces: the download labels its author wrote. They belong to the
+ * consumer and are translated in the consumer's `pageTranslations`. Screenshot captions are not
+ * among them — they live in the metainfo and are translated there.
+ */
+export function configMsgids(config) {
+    const msgids = new Set();
+    for (const download of config.downloads)
+        if (download.label)
+            msgids.add(download.label);
+    return [...msgids];
+}
+/** Every msgid in a `.po`/`.pot` file, translated or not, header excluded. */
+export async function catalogMsgids(file) {
+    if (!existsSync(file))
+        return new Set();
+    const entries = parsePo(await readFile(file, 'utf8'));
+    return new Set(entries.filter((entry) => entry.msgid !== '').map((entry) => entry.msgid));
+}
+const HEADER = (language) => [
+    'msgid ""',
+    'msgstr ""',
+    '"Project-Id-Version: gjsify-site\\n"',
+    ...(language ? [`"Language: ${language}\\n"`] : []),
+    '"MIME-Version: 1.0\\n"',
+    '"Content-Type: text/plain; charset=UTF-8\\n"',
+    '"Content-Transfer-Encoding: 8bit\\n"',
+].join('\n');
+/** Writes a catalogue: the translations in `known` are kept, everything else is left empty. */
+export function renderPo(msgids, language, known = new Map()) {
+    const entries = msgids.map((msgid) => `msgid ${quotePo(msgid)}\nmsgstr ${quotePo(known.get(msgid) ?? '')}`);
+    return `${[HEADER(language), ...entries].join('\n\n')}\n`;
+}
+export function poPath(poDir, language) {
+    const existing = languageCandidates(language)
+        .map((candidate) => join(poDir, `${candidate}.po`))
+        .find((file) => existsSync(file));
+    return existing ?? join(poDir, `${language.replace(/-/g, '_')}.po`);
+}
+/** Regenerates the catalogues of one directory, or with `check` only reports what would change. */
+export async function syncCatalogs(options) {
+    const { dir, languages, msgids, check, base } = options;
+    const stale = [];
+    const untranslated = [];
+    const write = async (file, content) => {
+        const current = existsSync(file) ? await readFile(file, 'utf8') : '';
+        if (current === content)
+            return;
+        stale.push(relative(base, file));
+        if (!check)
+            await writeFile(file, content);
+    };
+    if (options.pot)
+        await write(join(dir, 'site.pot'), renderPo(msgids, undefined));
+    for (const language of languages) {
+        if (language === UI_SOURCE_LANGUAGE)
+            continue;
+        const file = poPath(dir, language);
+        const known = existsSync(file) ? parseCatalog(await readFile(file, 'utf8')) : new Map();
+        await write(file, renderPo(msgids, language, known));
+        const missing = msgids.filter((msgid) => !known.get(msgid));
+        if (missing.length > 0) {
+            untranslated.push(`${relative(base, file)} has ${missing.length} untranslated string(s), e.g. "${missing[0]}"`);
+        }
+    }
+    return { stale, untranslated };
+}

package/lib/render/icons.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The page needs about twenty small glyphs. They are drawn here instead of pulled from an icon
+ * theme: inlining them costs no request and no licence notice, and a symbolic 16×16 grid is
+ * little enough geometry to keep in one file. Every path uses `currentColor` and is sized by CSS.
+ */
+export type IconName = 'linux' | 'macos' | 'windows' | 'android' | 'web' | 'firefox' | 'chromium' | 'package' | 'download' | 'license' | 'chevron-down' | 'chevron-left' | 'chevron-right' | 'close' | 'copy' | 'expand' | 'external' | 'code' | 'bug' | 'heart' | 'help' | 'mail' | 'people' | 'translate';
+export interface IconOptions {
+    /** Added to the `<svg>`, on top of the shared `icon` class. */
+    class?: string;
+    /** Rendered as the accessible name; without it the icon is `aria-hidden`. */
+    title?: string;
+}
+/** Renders one icon as an inline `<svg>`; decorative by default. */
+export declare function icon(name: IconName, options?: IconOptions): string;

package/lib/render/icons.js

@@ -0,0 +1,42 @@
+/**
+ * The page needs about twenty small glyphs. They are drawn here instead of pulled from an icon
+ * theme: inlining them costs no request and no licence notice, and a symbolic 16×16 grid is
+ * little enough geometry to keep in one file. Every path uses `currentColor` and is sized by CSS.
+ */
+/** Shared attributes of the outline icons, so the strokes stay optically equal. */
+const STROKE = 'fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"';
+const PATHS = {
+    // Platform marks are filled silhouettes: at 18px an outline turns to mush.
+    linux: `<path fill-rule="evenodd" d="M8 1.1c-1.7 0-3.1 1.4-3.1 3.1v1.2c0 .5-.2.9-.5 1.3-1.2 1.3-1.8 2.9-1.8 4.7 0 .6-.2 1.1-.6 1.5-.6.7-.3 1.7.5 2 1 .4 2.2.7 3.3.8.2 0 .3 0 .5-.1.5.1 1.1.1 1.7.1s1.2 0 1.7-.1c.2.1.3.1.5.1 1.1-.1 2.3-.4 3.3-.8.8-.3 1.1-1.3.5-2-.4-.4-.6-.9-.6-1.5 0-1.8-.6-3.4-1.8-4.7-.3-.4-.5-.8-.5-1.3V4.2c0-1.7-1.4-3.1-3.1-3.1Zm-1.2 2.2a.7.7 0 1 1 0 1.4.7.7 0 0 1 0-1.4Zm2.4 0a.7.7 0 1 1 0 1.4.7.7 0 0 1 0-1.4ZM8 5.1l1 .9-1 .9-1-.9 1-.9Z"/>`,
+    macos: `<path d="M11.2 8.5c0-1.5 1.2-2.2 1.3-2.3-.7-1-1.8-1.1-2.1-1.1-.9-.1-1.7.5-2.2.5-.4 0-1.1-.5-1.9-.5-1 0-1.9.6-2.4 1.5-1 1.7-.3 4.3.7 5.7.5.7 1.1 1.5 1.8 1.4.7 0 1-.4 1.8-.4.9 0 1.1.4 1.8.4.8 0 1.2-.7 1.7-1.4.6-.8.8-1.5.8-1.6 0 0-1.3-.5-1.3-2.2Z"/><path d="M9.6 3.7c.4-.5.7-1.1.6-1.8-.6 0-1.3.4-1.7.9-.4.4-.7 1.1-.6 1.7.7.1 1.3-.3 1.7-.8Z"/>`,
+    windows: `<path d="M1.6 2.9 7.1 2.1v5.2H1.6V2.9Zm6.5-.9L14.4 1v6.3H8.1V2Zm-6.5 6.7h5.5V14L1.6 13.2V8.7Zm6.5 0h6.3V15L8.1 14.1V8.7Z"/>`,
+    android: `<path ${STROKE} d="m4.9 3 -.8-1.3M11.1 3l.8-1.3"/><path fill-rule="evenodd" d="M3.9 5.8C4.1 3.7 5.8 2 8 2s3.9 1.7 4.1 3.8H3.9Zm2.4-1.9a.6.6 0 1 1 0 1.2.6.6 0 0 1 0-1.2Zm3.4 0a.6.6 0 1 1 0 1.2.6.6 0 0 1 0-1.2Z"/><path d="M3.9 6.8h8.2v5.4c0 .6-.5 1.1-1.1 1.1H5c-.6 0-1.1-.5-1.1-1.1V6.8Zm-2.9.9a.9.9 0 0 1 1.8 0v3.5a.9.9 0 0 1-1.8 0V7.7Zm12.3 0a.9.9 0 0 1 1.8 0v3.5a.9.9 0 0 1-1.8 0V7.7ZM5.1 13.6a.9.9 0 0 1 1.8 0v1.5a.9.9 0 0 1-1.8 0v-1.5Zm4 0a.9.9 0 0 1 1.8 0v1.5a.9.9 0 0 1-1.8 0v-1.5Z"/>`,
+    web: `<g ${STROKE}><circle cx="8" cy="8" r="6.3"/><path d="M1.7 8h12.6"/><path d="M8 1.7c1.7 1.7 2.6 3.9 2.6 6.3S9.7 12.6 8 14.3C6.3 12.6 5.4 10.4 5.4 8s.9-4.6 2.6-6.3Z"/></g>`,
+    firefox: `<g ${STROKE}><circle cx="8" cy="8" r="6.3"/><path d="M4.9 7.4a3.3 3.3 0 1 0 5.7-2.5c.2 1-.1 1.8-.9 2.4"/></g>`,
+    chromium: `<g ${STROKE}><circle cx="8" cy="8" r="6.3"/><circle cx="8" cy="8" r="2.4"/><path d="M8 5.6h5.7M5.9 9.2 3.1 14M10.1 9.2 7.3 14.1"/></g>`,
+    package: `<g ${STROKE}><path d="M8 1.6 14 4.5v7L8 14.4l-6-2.9v-7L8 1.6Z"/><path d="m2 4.5 6 2.9 6-2.9M8 7.4v7"/></g>`,
+    download: `<g ${STROKE}><path d="M8 1.9v7.6M4.8 6.4 8 9.6l3.2-3.2M2.4 13.3h11.2"/></g>`,
+    license: `<g ${STROKE}><path d="M4 1.8h5l3.2 3.2v9.2H4V1.8Z"/><path d="M8.8 1.8V5h3.2M6.2 8.2h3.6M6.2 10.8h3.6"/></g>`,
+    'chevron-down': `<path ${STROKE} d="m4.2 6.2 3.8 3.8 3.8-3.8"/>`,
+    'chevron-left': `<path ${STROKE} d="M9.8 3 4.8 8l5 5"/>`,
+    'chevron-right': `<path ${STROKE} d="m6.2 3 5 5-5 5"/>`,
+    close: `<path ${STROKE} d="m3.8 3.8 8.4 8.4M12.2 3.8 3.8 12.2"/>`,
+    copy: `<g ${STROKE}><rect x="5.4" y="5.4" width="8.2" height="8.2" rx="1.6"/><path d="M10.6 5.4V4c0-.9-.7-1.6-1.6-1.6H4c-.9 0-1.6.7-1.6 1.6v5c0 .9.7 1.6 1.6 1.6h1.4"/></g>`,
+    expand: `<path ${STROKE} d="M6 1.9H1.9V6M10 1.9h4.1V6M10 14.1h4.1V10M6 14.1H1.9V10"/>`,
+    external: `<g ${STROKE}><path d="M9.2 2.2h4.6v4.6M13.4 2.6 7.6 8.4"/><path d="M12 9.6v2.8c0 .8-.6 1.4-1.4 1.4H4c-.8 0-1.4-.6-1.4-1.4V5.8c0-.8.6-1.4 1.4-1.4h2.8"/></g>`,
+    code: `<path ${STROKE} d="M5.6 11.8 2 8l3.6-3.8M10.4 4.2 14 8l-3.6 3.8M9.4 2.6 6.6 13.4"/>`,
+    bug: `<g ${STROKE}><path d="M8 5.2c1.7 0 3 1.4 3 3v1.6c0 1.7-1.3 3-3 3s-3-1.3-3-3V8.2c0-1.6 1.3-3 3-3Z"/><path d="M6.3 4.2 5.5 2.6M9.7 4.2l.8-1.6M5 7.6H2.5M11 7.6h2.5M5 10.8H2.7M11 10.8h2.3M8 5.4v7.4"/></g>`,
+    heart: `<path ${STROKE} d="M8 13.6 3.1 8.5a3.2 3.2 0 1 1 4.5-4.5l.4.4.4-.4a3.2 3.2 0 1 1 4.5 4.5L8 13.6Z"/>`,
+    help: `<g ${STROKE}><circle cx="8" cy="8" r="6.3"/><path d="M6.2 6.2a1.8 1.8 0 1 1 2.7 1.7c-.6.3-.9.8-.9 1.4v.3"/></g><circle cx="8" cy="12" r=".9"/>`,
+    mail: `<g ${STROKE}><rect x="1.8" y="3.4" width="12.4" height="9.2" rx="1.6"/><path d="m2.4 4.6 5.6 4.2 5.6-4.2"/></g>`,
+    people: `<g ${STROKE}><circle cx="6.2" cy="5.2" r="2.6"/><path d="M1.6 13.8c0-2.5 2.1-4.2 4.6-4.2s4.6 1.7 4.6 4.2"/><path d="M10.6 3.1a2.6 2.6 0 0 1 0 5.1M12.1 9.9c1.4.5 2.3 1.7 2.3 3.3"/></g>`,
+    translate: `<g ${STROKE}><path d="M2 4.4c0-.9.7-1.6 1.6-1.6h5.1c.9 0 1.6.7 1.6 1.6v2.3c0 .9-.7 1.6-1.6 1.6H6L3.6 10.4V8.3h-.1c-.8 0-1.5-.7-1.5-1.6V4.4Z"/><path d="M12.3 6h.1c.9 0 1.6.7 1.6 1.6v2.3c0 .9-.7 1.6-1.6 1.6h-.1v2.1L9.9 11.5H8"/></g>`,
+};
+/** Renders one icon as an inline `<svg>`; decorative by default. */
+export function icon(name, options = {}) {
+    const classes = options.class ? `icon ${options.class}` : 'icon';
+    const label = options.title
+        ? ` role="img" aria-label="${options.title.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`)}"`
+        : ' aria-hidden="true"';
+    return `<svg class="${classes}" viewBox="0 0 16 16" width="16" height="16" fill="currentColor"${label}>${PATHS[name]}</svg>`;
+}

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

@@ -0,0 +1,26 @@
+export type ImageFormat = 'avif' | 'webp' | 'png';
+/** A rectangle in pixels, as `opaqueBounds` reports it and `cropped` takes it. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A decoded raster, immutable: `resizedToWidth` and `cropped` answer a new one. */
+export interface RasterImage {
+    readonly width: number;
+    readonly height: number;
+    /** 0–255; an image without an alpha channel answers 255 everywhere. */
+    alphaAt(x: number, y: number): number;
+    /**
+     * The smallest rectangle holding every pixel whose alpha reaches `threshold`, or `null` when no
+     * pixel does. An image without an alpha channel answers its whole area.
+     */
+    opaqueBounds(threshold: number): Rect | null;
+    cropped(rect: Rect): RasterImage;
+    /** Keeps the aspect ratio. Never enlarges: a width at or above this one answers the same image. */
+    resizedToWidth(width: number): RasterImage;
+    encode(format: ImageFormat): Uint8Array;
+}
+export declare function decodeImageFile(path: string): RasterImage;
+export declare function decodeImageBytes(bytes: Uint8Array): RasterImage;

package/lib/render/image-backend.js

@@ -0,0 +1,130 @@
+// The ONE image backend: GdkPixbuf. Decode, alpha probe, downscale, encode —
+// everything `images.ts` needs, behind a plain-object seam so the rest of the
+// build never names a library.
+//
+// Why GdkPixbuf rather than a JS encoder: it is reachable from EVERY runtime
+// gjsify builds for, and it is the only thing in that set that is. Under
+// `--app gjs` the `gi://` import lowers to GJS's own GI loader; under `--app
+// node` the bundler rewrites it to the `@gjsify/node-gi` reverse bridge (ADR
+// 0030), which is also what bun and deno run. So a site build is not a Node
+// site build or a GJS site build — it is the same code on whichever runtime
+// `gjsify` itself runs on. A `sharp` dependency would have inverted that: a
+// native Node-API addon, no GJS story at all.
+//
+// AVIF/WebP writing comes from gdk-pixbuf's loader set (glycin on current
+// GNOME), not from this package, so `assertEncodable` reports a MISSING LOADER
+// by name instead of writing a 0-byte file. One format is deliberately absent
+// 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 GdkPixbuf from 'gi://GdkPixbuf?version=2.0';
+/** Encoder options per format, matching what the renditions were tuned to. */
+const ENCODER = {
+    avif: { keys: ['quality'], values: ['55'] },
+    webp: { keys: ['quality'], values: ['80'] },
+    png: { keys: ['compression'], values: ['9'] },
+};
+let writableFormats;
+/** Throws naming the loader when gdk-pixbuf on this system cannot WRITE the format. */
+function assertEncodable(format) {
+    const writable = (writableFormats ??= new Set(GdkPixbuf.Pixbuf.get_formats()
+        .filter((entry) => entry.is_writable())
+        .map((entry) => entry.get_name())
+        .filter((name) => name !== null)));
+    if (writable.has(format))
+        return;
+    throw new Error(`gdk-pixbuf on this system cannot write ${format.toUpperCase()} — install the gdk-pixbuf loader for it ` +
+        `(GNOME ships AVIF and WebP through glycin). Writable here: ${[...writable].sort().join(', ')}.`);
+}
+function wrap(pixbuf) {
+    const width = pixbuf.get_width();
+    const height = pixbuf.get_height();
+    return {
+        width,
+        height,
+        alphaAt(x, y) {
+            if (!pixbuf.get_has_alpha())
+                return 255;
+            const pixels = pixbuf.get_pixels();
+            return pixels[y * pixbuf.get_rowstride() + x * pixbuf.get_n_channels() + 3] ?? 255;
+        },
+        opaqueBounds(threshold) {
+            if (!pixbuf.get_has_alpha())
+                return { x: 0, y: 0, width, height };
+            // The whole buffer once, not a call per pixel: a 2560px screenshot is seven million
+            // samples, and `get_pixels` copies the buffer out of GI on every call.
+            const pixels = pixbuf.get_pixels();
+            const stride = pixbuf.get_rowstride();
+            const channels = pixbuf.get_n_channels();
+            let top = -1;
+            let bottom = -1;
+            let left = width;
+            let right = -1;
+            for (let y = 0; y < height; y++) {
+                const row = y * stride;
+                let first = -1;
+                let last = -1;
+                for (let x = 0; x < width; x++) {
+                    if ((pixels[row + x * channels + 3] ?? 255) < threshold)
+                        continue;
+                    if (first === -1)
+                        first = x;
+                    last = x;
+                }
+                if (first === -1)
+                    continue;
+                if (top === -1)
+                    top = y;
+                bottom = y;
+                if (first < left)
+                    left = first;
+                if (last > right)
+                    right = last;
+            }
+            if (top === -1)
+                return null;
+            return { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+        },
+        cropped(rect) {
+            const sub = pixbuf.new_subpixbuf(rect.x, rect.y, rect.width, rect.height);
+            if (!sub)
+                throw new Error(`Could not crop an image to ${rect.width}x${rect.height}`);
+            return wrap(sub);
+        },
+        resizedToWidth(target) {
+            if (target >= width)
+                return wrap(pixbuf);
+            const scaled = pixbuf.scale_simple(target, Math.max(1, Math.round((height * target) / width)), 
+            // HYPER over BILINEAR: these are large screenshots scaled far
+            // down, where bilinear drops thin UI lines (1px borders, text
+            // stems) that the page is meant to show.
+            GdkPixbuf.InterpType.HYPER);
+            if (!scaled)
+                throw new Error(`Could not scale an image to ${target}px`);
+            return wrap(scaled);
+        },
+        encode(format) {
+            assertEncodable(format);
+            const { keys, values } = ENCODER[format];
+            const [ok, bytes] = pixbuf.save_to_bufferv(format, keys, values);
+            if (!ok || !bytes?.length)
+                throw new Error(`Encoding ${format.toUpperCase()} produced no data`);
+            return new Uint8Array(bytes);
+        },
+    };
+}
+export function decodeImageFile(path) {
+    const pixbuf = GdkPixbuf.Pixbuf.new_from_file(path);
+    if (!pixbuf)
+        throw new Error(`Could not decode ${path}`);
+    return wrap(pixbuf);
+}
+export function decodeImageBytes(bytes) {
+    const loader = new GdkPixbuf.PixbufLoader();
+    loader.write(bytes);
+    loader.close();
+    const pixbuf = loader.get_pixbuf();
+    if (!pixbuf)
+        throw new Error('Could not decode an image from memory');
+    return wrap(pixbuf);
+}

package/lib/render/images.d.ts

@@ -0,0 +1,51 @@
+import { type ImageFormat, type RasterImage } from './image-backend.js';
+export type { ImageFormat };
+export interface ImageFile {
+    url: string;
+    width: number;
+}
+export interface ProcessedImage {
+    /** Intrinsic size of the largest rendition, for the `width`/`height` attributes. */
+    width: number;
+    height: number;
+    /** CSS pixels the page gives this screenshot at most; the renditions above it serve HiDPI. */
+    displayWidth: number;
+    formats: Record<ImageFormat, ImageFile[]>;
+    /** The artwork already carries its own shadow (a window shot), so the page adds no frame. */
+    frameless: boolean;
+}
+export interface ImageOptions {
+    /** Directory the renditions are published into (served below `urlBase`). */
+    outDir: string;
+    /** Persistent store of encoded renditions; AVIF is slow, so it is reused while the source is unchanged. */
+    cacheDir: string;
+    urlBase: string;
+}
+/**
+ * The widest the page ever shows a screenshot, in CSS pixels. A screenshot is shown at its natural
+ * width capped here and NEVER upscaled, which also settles what a "2×" source is without asking the
+ * metainfo: a 2560px source fills 1280 CSS px at device-pixel-ratio 2, a 1280px one fills the same
+ * box at ratio 1 and is as sharp as its artwork allows. Renditions therefore go up to twice this.
+ */
+export declare const MAX_DISPLAY_WIDTH = 1280;
+/** Never upscales: the largest rendition is the source itself, or twice the display cap if that is smaller. */
+export declare function renditionWidths(natural: number): number[];
+/** CSS pixels this source fills: the display cap, or the source itself when it is narrower. */
+export declare function displayWidth(natural: number): number;
+/**
+ * A window shot cut out of a desktop (GNOME's screenshot tool) keeps a transparent margin with the
+ * window's own shadow, so all four corner pixels are see-through. Opaque screenshots have none.
+ */
+export declare function hasTransparentBorder(input: string | Uint8Array): boolean;
+/**
+ * Drops rows and columns in which not one pixel is painted at all.
+ *
+ * A window shot is saved on a canvas large enough for the window's shadow, and how much empty space
+ * is left around that shadow is up to whoever took the shot. The page cannot see it: the slide sizes
+ * the whole file, so the picture shrinks by the margin and the band above and below it stays blank.
+ * Cropping to the painted area makes every screenshot fill its slide equally — and it keeps the
+ * shadow itself, which is why the threshold is "nothing at all" rather than "barely visible".
+ */
+export declare function trimTransparentMargin(image: RasterImage): RasterImage;
+/** Encodes AVIF, WebP and PNG renditions of one screenshot into `outDir` and describes them. */
+export declare function processImage(source: string, slug: string, options: ImageOptions): Promise<ProcessedImage>;

package/lib/render/images.js

@@ -0,0 +1,97 @@
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { decodeImageBytes, decodeImageFile } from './image-backend.js';
+/**
+ * The widest the page ever shows a screenshot, in CSS pixels. A screenshot is shown at its natural
+ * width capped here and NEVER upscaled, which also settles what a "2×" source is without asking the
+ * metainfo: a 2560px source fills 1280 CSS px at device-pixel-ratio 2, a 1280px one fills the same
+ * box at ratio 1 and is as sharp as its artwork allows. Renditions therefore go up to twice this.
+ */
+export const MAX_DISPLAY_WIDTH = 1280;
+const TARGET_WIDTHS = [640, MAX_DISPLAY_WIDTH, MAX_DISPLAY_WIDTH * 2];
+const FORMATS = ['avif', 'webp', 'png'];
+/** Never upscales: the largest rendition is the source itself, or twice the display cap if that is smaller. */
+export function renditionWidths(natural) {
+    const largest = Math.min(natural, MAX_DISPLAY_WIDTH * 2);
+    const widths = new Set(TARGET_WIDTHS.filter((width) => width < largest));
+    widths.add(largest);
+    return [...widths].sort((a, b) => a - b);
+}
+/** CSS pixels this source fills: the display cap, or the source itself when it is narrower. */
+export function displayWidth(natural) {
+    return Math.min(natural, MAX_DISPLAY_WIDTH);
+}
+/** Alpha below this is nothing at all: a pixel the source left empty, not the faint tail of a shadow. */
+const ALPHA_EMPTY = 1;
+const CORNER_ALPHA_MAX = 16;
+/**
+ * A window shot cut out of a desktop (GNOME's screenshot tool) keeps a transparent margin with the
+ * window's own shadow, so all four corner pixels are see-through. Opaque screenshots have none.
+ */
+export function hasTransparentBorder(input) {
+    return cornersTransparent(typeof input === 'string' ? decodeImageFile(input) : decodeImageBytes(input));
+}
+function cornersTransparent(image) {
+    const right = image.width - 1;
+    const bottom = image.height - 1;
+    return [image.alphaAt(0, 0), image.alphaAt(right, 0), image.alphaAt(0, bottom), image.alphaAt(right, bottom)].every((alpha) => alpha < CORNER_ALPHA_MAX);
+}
+/**
+ * Drops rows and columns in which not one pixel is painted at all.
+ *
+ * A window shot is saved on a canvas large enough for the window's shadow, and how much empty space
+ * is left around that shadow is up to whoever took the shot. The page cannot see it: the slide sizes
+ * the whole file, so the picture shrinks by the margin and the band above and below it stays blank.
+ * Cropping to the painted area makes every screenshot fill its slide equally — and it keeps the
+ * shadow itself, which is why the threshold is "nothing at all" rather than "barely visible".
+ */
+export function trimTransparentMargin(image) {
+    const bounds = image.opaqueBounds(ALPHA_EMPTY);
+    if (!bounds)
+        return image;
+    if (bounds.width === image.width && bounds.height === image.height)
+        return image;
+    return image.cropped(bounds);
+}
+async function isFresh(cached, source) {
+    if (!existsSync(cached))
+        return false;
+    const [a, b] = await Promise.all([stat(cached), stat(source)]);
+    return a.mtimeMs >= b.mtimeMs;
+}
+/** Encodes AVIF, WebP and PNG renditions of one screenshot into `outDir` and describes them. */
+export async function processImage(source, slug, options) {
+    const decoded = decodeImageFile(source);
+    if (!decoded.width || !decoded.height)
+        throw new Error(`Cannot read the size of ${source}`);
+    const image = trimTransparentMargin(decoded);
+    const widths = renditionWidths(image.width);
+    await Promise.all([mkdir(options.outDir, { recursive: true }), mkdir(options.cacheDir, { recursive: true })]);
+    const formats = { avif: [], webp: [], png: [] };
+    for (const width of widths) {
+        // Scaled at most once per width, and only when some format misses the
+        // cache — the resample is the expensive half of a warm rebuild.
+        let scaled;
+        for (const format of FORMATS) {
+            const name = `${slug}-${width}.${format}`;
+            const cached = join(options.cacheDir, name);
+            if (!(await isFresh(cached, source))) {
+                scaled ??= image.resizedToWidth(width);
+                await writeFile(cached, scaled.encode(format));
+            }
+            await copyFile(cached, join(options.outDir, name));
+            formats[format].push({ url: `${options.urlBase}${name}`, width });
+        }
+    }
+    for (const format of FORMATS)
+        formats[format].sort((a, b) => a.width - b.width);
+    const largest = widths[widths.length - 1];
+    return {
+        width: largest,
+        height: Math.round((largest * image.height) / image.width),
+        displayWidth: displayWidth(image.width),
+        formats,
+        frameless: cornersTransparent(image),
+    };
+}