@gjsify/site 0.64.1-next.245 → 0.64.1-next.248

package/README.md

@@ -104,7 +104,8 @@ Lives in the root `package.json`, next to `ship` and `flatpak`.
 | `translations` | Directory of the app's `<lang>.po` catalogues, used when the metainfo lacks a translation. Optional. |
 | `pageTranslations` | Directory of `<lang>.po` catalogues for the *page's own* strings, overlaying this package's `po/`. Optional, see below. |
 | `icon` | Icon (SVG or PNG) for the header, hero and favicon; overrides the Flatpak/ship icon. Optional. |
-| `downloads` | `[{platform, format, url?, label?, available?}]`: targets the release assets do not cover, e.g. browser stores or a source install. `platform` is an OS or `firefox` / `chromium`; `format` adds `store`, `xpi`, `source`. `url` is required unless `available` is `false`, which lists the target as "Not yet available" and never recommends it. |
+| `components` | `[{id, name, summary?, match?}]`: the separately installed parts of the product, in install order, see below. Optional — without it the dialog is one undivided list. |
+| `downloads` | `[{platform, format, url?, label?, available?, component?}]`: targets the release assets do not cover, e.g. browser stores or a source install. `platform` is an OS or `firefox` / `chromium`; `format` adds `store`, `xpi`, `source`. `url` is required unless `available` is `false`, which lists the target as "Not yet available" and never recommends it. `component` is a `components[].id`. |
 | `releaseAssets` | `false` ignores the GitHub release assets, so `downloads` is the whole list. Default `true`. |
 | `support`, `legal` | `support`: `{kind, url}` links, or `{kind: "sepa", name, iban, bic?, reference?}`, a bank transfer shown as IBAN plus an EPC QR code. `legal`: `{label, url}` links. Both empty by default: nothing is invented. |
 
@@ -112,6 +113,33 @@ A `sepa` entry carries no amount, and its IBAN is checked when the config loads
 country, alphabet, and the mod-97 checksum — so a typo fails the build instead of printing a QR
 code that moves money nowhere.
 
+### Components
+
+Some products are not one download. A desktop app plus the browser extension that talks to it are
+two things a person installs one after the other, and a single flat list of files does not say
+which goes first. `components` names those parts:
+
+```json
+"components": [
+  { "id": "app", "name": "App", "summary": "Install and start it once.", "match": "^beifahrer[-_]" },
+  { "id": "extension", "name": "Browser extension", "summary": "Then add it to your browser." }
+]
+```
+
+Each part becomes its own block in the download dialog, in declared order, with its own operating
+system tabs — numbered "Step 1", "Step 2", … as soon as there is more than one. The tab strip is
+labelled `Browser` when every target in that block is a browser, otherwise `Operating system`.
+
+`match` is a regular expression on the asset's file name, matched case-insensitively; the first
+component whose `match` hits owns the asset. A component without `match` is the catch-all and
+takes everything left over, which is what a release without a naming scheme for every file needs.
+Entries in `downloads` pick their block by `component` instead, naming a `components[].id` — an
+unknown id fails the build with the known ids listed.
+
+The recommendation ("Recommended for your system") is made once per part, so each block
+highlights its own best match, and the big button at the top of the dialog offers the first
+declared component: the thing to install first.
+
 ### Screenshots
 
 Nothing to configure: the page shows the metainfo `<screenshots>`, in document order, with their

package/lib/client/site.css

@@ -953,6 +953,45 @@ h1 {
   color: var(--fg);
 }
 
+/* One block per part of the product, in the order the parts have to be installed in. */
+.component + .component {
+  margin-top: 1.25rem;
+  border-top: 1px solid var(--line);
+}
+
+.component-head {
+  padding: 1rem 1.25rem 0;
+}
+
+.component-title {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin: 0;
+  font-size: 1rem;
+}
+
+.component-step {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: 999px;
+  background: var(--accent);
+  color: var(--accent-fg);
+  font-size: 0.8rem;
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+}
+
+.component-summary {
+  margin: 0.4rem 0 0;
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
 .os-tabs {
   display: flex;
   gap: 0.35rem;
@@ -989,7 +1028,7 @@ h1 {
   padding: 0 1.25rem;
 }
 
-.os-group h3 {
+.os-title {
   display: flex;
   align-items: center;
   gap: 0.5rem;
@@ -998,7 +1037,7 @@ h1 {
 }
 
 /* With tabs visible the group heading only repeats the selected tab. */
-.os-tabs:not([hidden]) ~ .os-groups h3 {
+.os-tabs:not([hidden]) ~ .os-groups .os-title {
   display: none;
 }
 

package/lib/client/site.js

@@ -1 +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(){this.dataset.enhanced=`true`;let e=this.querySelector(`dialog`);e&&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);
+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??``}]})}function showSize(e){let t=document.querySelector(`.badge-size`),n=t?.querySelector(`.badge-value`);if(!t||!n)return;n.textContent=e,t.hidden=e===``;let r=t.closest(`.badges`);if(!r)return;let i=[...r.children].filter(e=>!e.hidden).length;r.style.setProperty(`--badge-count`,String(i)),r.toggleAttribute(`data-odd`,i%2==1)}var ComponentSection=class{onSelect;rows;groups;tabs;tabBar;grouped;constructor(e,t){this.onSelect=t,this.rows=readRows(e),this.groups=[...e.querySelectorAll(`.os-group`)],this.tabs=[...e.querySelectorAll(`.os-tab`)],this.tabBar=e.querySelector(`.os-tabs`),this.grouped=this.tabs.length>1,this.tabBar&&this.grouped&&(this.tabBar.hidden=!1);let n=this.tabs.find(e=>e.getAttribute(`aria-selected`)===`true`)?.dataset.os;n&&this.show(n);for(let e of this.tabs)e.addEventListener(`click`,()=>{let t=e.dataset.os;t&&this.select(t,this.platform)});this.tabBar?.addEventListener(`keydown`,e=>{let t=this.tabs.indexOf(document.activeElement);if(t===-1)return;let n=this.tabs.length-1,r={ArrowRight:t+1,ArrowLeft:t-1,Home:0,End:n}[e.key];if(r===void 0)return;e.preventDefault();let i=this.tabs[(r+this.tabs.length)%this.tabs.length];i?.focus(),i?.click()})}platform={os:void 0,arch:void 0,browser:void 0,archAssumed:!0};show(e){for(let t of this.groups)t.hidden=this.grouped&&t.dataset.os!==e;for(let t of this.tabs){let n=t.dataset.os===e;t.setAttribute(`aria-selected`,String(n)),t.tabIndex=n?0:-1}}select(e,t){this.show(e);let n=recommendTarget(this.rows,inGroup(t,e));n&&this.onSelect(n)}detected(e){this.platform=e;let t=recommendTarget(this.rows,e);t&&(this.show(t.os),this.onSelect(t))}},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 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),showSize(e.size)},n=[...this.querySelectorAll(`section.component`)],r=(n.length>0?n:[this]).map((e,t)=>new ComponentSection(e,t===0?offer:()=>{}));readHints().then(e=>{let t=detectVisitorPlatform(e);for(let e of r)e.detected(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(){this.dataset.enhanced=`true`;let e=this.querySelector(`dialog`);e&&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/render/i18n.js

@@ -47,6 +47,11 @@ export function configMsgids(config) {
     for (const download of config.downloads)
         if (download.label)
             msgids.add(download.label);
+    for (const component of config.components) {
+        msgids.add(component.name);
+        if (component.summary)
+            msgids.add(component.summary);
+    }
     return [...msgids];
 }
 /** Every msgid in a `.po`/`.pot` file, translated or not, header excluded. */

package/lib/render/pages.d.ts

@@ -20,6 +20,8 @@ export interface RenderContext {
     ogImage?: string;
 }
 type Translate = (msgid: string) => string;
+/** What the download dialog reads: the targets, the catalogue and the locale it formats sizes in. */
+export type DownloadContext = Pick<RenderContext, 'data' | 't' | 'lang'>;
 export declare function localized(text: Localized, lang: string): string;
 export declare function pageUrl(data: SiteData, lang: string): string;
 export declare function absolute(data: SiteData, rootRelative: string): string;
@@ -34,6 +36,15 @@ export declare function languageName(code: string): string;
 export declare function ctaLabel(target: DownloadTarget, t: Translate): string;
 /** A window shot brings its own shadow; ours would draw a second one around it. */
 export declare function frameAttribute(ctx: Pick<RenderContext, 'images'>, screenshot: Screenshot): 'none' | undefined;
+/**
+ * The split button plus the dialog holding every target. Both are server-rendered: without
+ * JavaScript the dialog stays an open panel below the button (see `site.css`), with it the
+ * component turns the same markup into a modal and swaps the button for the detected platform.
+ *
+ * The button offers the part that is installed first; the dialog lists every part in that order,
+ * so a product made of an app and the extension it pairs with reads as the two steps it is.
+ */
+export declare function downloadWidget(ctx: DownloadContext): string;
 /**
  * The facts row under the hero. A badge whose fact is missing is left out, not faked, and the row
  * tells CSS how many it ended up with so the columns divide the width evenly.

package/lib/render/pages.js

@@ -176,6 +176,33 @@ function defaultTarget(targets) {
         available.find((target) => target.recommended) ??
         available[0]);
 }
+/**
+ * The targets of the part a person installs FIRST, which is the one the primary button offers. A
+ * product declaring no components has exactly one part, so the whole list is that part.
+ */
+function primaryTargets(data) {
+    const first = data.config.components[0];
+    if (!first)
+        return data.downloads.targets;
+    const own = data.downloads.targets.filter((target) => target.component === first.id);
+    return own.length > 0 ? own : data.downloads.targets;
+}
+/**
+ * The dialog's blocks, in install order. A component nobody built a file for is left out rather
+ * than shown empty, so a release that is missing an artefact says so by absence.
+ */
+function componentBlocks(data) {
+    const targets = data.downloads.targets;
+    const declared = data.config.components;
+    if (declared.length === 0)
+        return [{ id: '', targets }];
+    const blocks = declared.flatMap((part) => {
+        const own = targets.filter((target) => target.component === part.id);
+        return own.length > 0 ? [{ id: part.id, name: part.name, summary: part.summary, targets: own }] : [];
+    });
+    const rest = targets.filter((target) => !declared.some((part) => part.id === target.component));
+    return rest.length > 0 ? [...blocks, { id: '', targets: rest }] : blocks;
+}
 /**
  * One row of the download dialog. The data attributes carry everything the client needs to put a
  * row on the primary button, so it never has to build a translated string itself.
@@ -205,15 +232,66 @@ ${size ? `<span class="target-size">${esc(size)}</span>` : ''}`;
 ${target.available ? `<a href="${esc(target.url)}">\n${inner}\n</a>` : `<span class="target-link">\n${inner}\n</span>`}
 </li>`;
 }
+/** A component id as an HTML id fragment; a configuration's own ids are not guaranteed to be safe. */
+function blockSlug(block, index) {
+    const slug = block.id
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+    return slug || `part-${index + 1}`;
+}
+/**
+ * One part of the product in the dialog: its heading, then one tab per platform it is built for.
+ * The tabs live inside the block, so the extension's tabs are browsers while the app's are
+ * operating systems — the two parts are picked by different facts about the visitor.
+ *
+ * `step` numbers the part when there is more than one, because the order they are listed in is the
+ * order they have to be installed in.
+ */
+function componentSection(block, slug, step, ctx) {
+    const { t } = ctx;
+    const selected = defaultTarget(block.targets)?.os;
+    const groups = PLATFORM_ORDER.flatMap((os) => {
+        const own = block.targets.filter((target) => target.os === os);
+        return own.length > 0 ? [[os, own]] : [];
+    });
+    // A nested block already has a heading of its own, so its platforms are one level deeper.
+    const level = block.name ? 'h4' : 'h3';
+    const tabs = groups.map(([os]) => `<button class="os-tab" type="button" role="tab" id="os-tab-${esc(slug)}-${esc(os)}" aria-controls="os-group-${esc(slug)}-${esc(os)}" data-os="${esc(os)}" aria-selected="${os === selected}">${icon(PLATFORM_ICONS[os])}<span>${esc(osName(os, t))}</span></button>`);
+    const sections = groups.map(([os, own,]) => `<section class="os-group" id="os-group-${esc(slug)}-${esc(os)}" role="tabpanel" aria-labelledby="os-tab-${esc(slug)}-${esc(os)}" data-os="${esc(os)}">
+<${level} class="os-title">${icon(PLATFORM_ICONS[os])}<span>${esc(osName(os, t))}</span></${level}>
+<ul>
+${own.map((target) => targetItem(target, ctx)).join('\n')}
+</ul>
+${os === 'darwin' ? `<p class="os-note">${esc(t('Apple Silicon is assumed. Pick the Intel build if your Mac has an Intel processor.'))}</p>` : ''}
+</section>`);
+    const head = block.name
+        ? `<div class="component-head">
+<h3 class="component-title">${step === undefined ? '' : `<span class="component-step">${esc(String(step))}</span>`}<span>${esc(t(block.name))}</span></h3>
+${block.summary ? `<p class="component-summary">${esc(t(block.summary))}</p>` : ''}
+</div>`
+        : '';
+    // An extension's tabs are browsers; naming them "Operating system" would mislead a screen reader.
+    const tabsLabel = groups.every(([os]) => isBrowserPlatform(os)) ? t('Browser') : t('Operating system');
+    return `<section class="component"${attrs({ 'data-component': block.id || undefined })}>
+${head}
+<div class="os-tabs" role="tablist" aria-label="${esc(tabsLabel)}" hidden>${tabs.join('')}</div>
+<div class="os-groups">
+${sections.join('\n')}
+</div>
+</section>`;
+}
 /**
  * The split button plus the dialog holding every target. Both are server-rendered: without
  * JavaScript the dialog stays an open panel below the button (see `site.css`), with it the
  * component turns the same markup into a modal and swaps the button for the detected platform.
+ *
+ * The button offers the part that is installed first; the dialog lists every part in that order,
+ * so a product made of an app and the extension it pairs with reads as the two steps it is.
  */
-function downloadWidget(ctx) {
+export function downloadWidget(ctx) {
     const { data, t } = ctx;
-    const targets = data.downloads.targets;
-    const primary = defaultTarget(targets);
+    const primary = defaultTarget(primaryTargets(data));
     if (!primary) {
         // Nothing downloadable yet: point at the releases, or at the source when there are none.
         const [href, label] = data.downloads.hasReleases
@@ -223,18 +301,10 @@ function downloadWidget(ctx) {
 <a class="button download-cta" href="${esc(href)}">${icon('download')}<span class="download-label">${esc(label)}</span></a>
 </div>`;
     }
-    const groups = PLATFORM_ORDER.flatMap((os) => {
-        const own = targets.filter((target) => target.os === os);
-        return own.length > 0 ? [[os, own]] : [];
-    });
-    const tabs = groups.map(([os]) => `<button class="os-tab" type="button" role="tab" id="os-tab-${esc(os)}" aria-controls="os-group-${esc(os)}" data-os="${esc(os)}" aria-selected="${os === primary.os}">${icon(PLATFORM_ICONS[os])}<span>${esc(osName(os, t))}</span></button>`);
-    const sections = groups.map(([os, own,]) => `<section class="os-group" id="os-group-${esc(os)}" role="tabpanel" aria-labelledby="os-tab-${esc(os)}" data-os="${esc(os)}">
-<h3>${icon(PLATFORM_ICONS[os])}<span>${esc(osName(os, t))}</span></h3>
-<ul>
-${own.map((target) => targetItem(target, ctx)).join('\n')}
-</ul>
-${os === 'darwin' ? `<p class="os-note">${esc(t('Apple Silicon is assumed. Pick the Intel build if your Mac has an Intel processor.'))}</p>` : ''}
-</section>`);
+    const blocks = componentBlocks(data);
+    const named = blocks.filter((block) => block.name).length;
+    let step = 0;
+    const sections = blocks.map((block, index) => componentSection(block, blockSlug(block, index), block.name && named > 1 ? ++step : undefined, ctx));
     return `<app-download class="download">
 <div class="download-split">
 <a class="button download-cta" href="${esc(primary.url)}"${attrs({ 'data-os': primary.os, 'data-arch': primary.arch })}>${icon('download')}<span class="download-label">${esc(ctaLabel(primary, t))}</span></a>
@@ -245,8 +315,7 @@ ${os === 'darwin' ? `<p class="os-note">${esc(t('Apple Silicon is assumed. Pick
 <h2 id="all-downloads-title">${esc(t('All download options'))}</h2>
 <button class="dialog-close" type="button" aria-label="${esc(t('Close'))}" hidden>${icon('close')}</button>
 </div>
-<div class="os-tabs" role="tablist" aria-label="${esc(t('Operating system'))}" hidden>${tabs.join('')}</div>
-<div class="os-groups">
+<div class="components">
 ${sections.join('\n')}
 </div>
 ${data.downloads.hasReleases ? `<p class="dialog-foot"><a href="${esc(data.downloads.releasesUrl)}">${esc(t('All releases on GitHub'))}${icon('external', { class: 'link-external' })}</a></p>` : ''}
@@ -276,7 +345,8 @@ export function badges(ctx) {
     const number = new Intl.NumberFormat(lang, { notation: 'compact', maximumFractionDigits: 1 });
     const targets = data.downloads.targets;
     const specs = [];
-    const primary = defaultTarget(targets);
+    // The badge belongs to the primary button, so it reports the part that button offers.
+    const primary = defaultTarget(primaryTargets(data));
     if (primary) {
         // Not every target reports a size; the client swaps this one as the reader picks another.
         const size = sizeLabel(primary.size, lang);

package/lib/site-data/config.js

@@ -70,7 +70,29 @@ const FORMATS = [
     'xpi',
     'source',
 ];
-function parseDownloads(raw) {
+/**
+ * `gjsify.site.components`: the parts of the product a person installs one after another. `match`
+ * arrives as a string because this is JSON, and is compiled case-insensitively — release asset
+ * names differ in case between the formats that build them.
+ */
+function parseComponents(raw) {
+    return objectList(raw, 'components').map((entry, index) => {
+        const where = `gjsify.site.components[${index}]`;
+        const id = stringField(entry, 'id', where);
+        const name = stringField(entry, 'name', where);
+        const summary = entry.summary === undefined ? undefined : stringField(entry, 'summary', where);
+        if (entry.match === undefined)
+            return { id, name, summary };
+        const pattern = stringField(entry, 'match', where);
+        try {
+            return { id, name, summary, match: new RegExp(pattern, 'i') };
+        }
+        catch (cause) {
+            throw new Error(`${where}.match is not a valid regular expression: ${pattern}`, { cause });
+        }
+    });
+}
+function parseDownloads(raw, components) {
     return objectList(raw, 'downloads').map((entry, index) => {
         const where = `gjsify.site.downloads[${index}]`;
         const platform = stringField(entry, 'platform', where);
@@ -92,7 +114,12 @@ function parseDownloads(raw) {
         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 };
+        const component = entry.component === undefined ? undefined : stringField(entry, 'component', where);
+        // A typo here would silently drop the row into the unnamed rest of the dialog.
+        if (component !== undefined && !components.some((part) => part.id === component)) {
+            throw new Error(`${where}.component "${component}" is not one of gjsify.site.components: ${components.map((part) => part.id).join(', ') || '(none declared)'}`);
+        }
+        return { platform, format, url, label, available, component };
     });
 }
 function parseReleaseAssets(raw) {
@@ -118,6 +145,7 @@ export function parseSiteConfig(manifest) {
     if (!languages.includes(defaultLanguage))
         throw new Error(`gjsify.site.defaultLanguage "${defaultLanguage}" is not in languages`);
     const url = requireString(raw, 'url');
+    const components = parseComponents(raw);
     return {
         metainfo: requireString(raw, 'metainfo'),
         base: normalizeBase(requireString(raw, 'base')),
@@ -131,7 +159,8 @@ export function parseSiteConfig(manifest) {
         translations: optionalString(raw, 'translations'),
         pageTranslations: optionalString(raw, 'pageTranslations'),
         icon: optionalString(raw, 'icon'),
-        downloads: parseDownloads(raw),
+        components,
+        downloads: parseDownloads(raw, components),
         releaseAssets: parseReleaseAssets(raw),
         support: objectList(raw, 'support').map((entry, index) => parseSupport(entry, `gjsify.site.support[${index}]`)),
         legal: objectList(raw, 'legal').map((entry, index) => ({

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

@@ -1,4 +1,4 @@
-import type { DownloadTarget, ReleaseAsset, SiteDownloadConfig, TargetArch, TargetFormat, TargetPlatform } from './types.js';
+import type { DownloadTarget, ReleaseAsset, SiteComponent, 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. */
@@ -14,6 +14,13 @@ export declare function classifyAsset(asset: ReleaseAsset): {
     format: TargetFormat;
     arch: TargetArch;
 } | null;
+/**
+ * Which part of the product a release asset installs. The first component whose `match` accepts
+ * the file name wins, so declaration order is the tie-breaker; a component without a `match` is
+ * the catch-all for everything the earlier ones left. Undefined when no component claims the file,
+ * which is also the single-component case where the dialog shows no headings at all.
+ */
+export declare function componentOf(name: string, components: readonly SiteComponent[]): string | undefined;
 export interface DownloadSources {
     assets: readonly ReleaseAsset[];
     /** Flathub application id, when the app is published there. */
@@ -24,6 +31,12 @@ export interface DownloadSources {
     webAppUrl?: string;
     /** `gjsify.site.downloads`: targets no release asset supplies, e.g. a store page. */
     configured?: readonly SiteDownloadConfig[];
+    /** `gjsify.site.components`, in install order; empty when the product is one thing to download. */
+    components?: readonly SiteComponent[];
 }
-/** Builds the sorted target list and marks the first available target of every platform as recommended. */
+/**
+ * Builds the sorted target list and marks the first available target of every platform as
+ * recommended — once per component, because a person installs each part of the product in turn and
+ * every part needs its own first choice.
+ */
 export declare function buildDownloadTargets(sources: DownloadSources): DownloadTarget[];

package/lib/site-data/downloads.js

@@ -118,6 +118,15 @@ function rank(order, value) {
     const index = order.indexOf(value);
     return index === -1 ? order.length : index;
 }
+/**
+ * Which part of the product a release asset installs. The first component whose `match` accepts
+ * the file name wins, so declaration order is the tie-breaker; a component without a `match` is
+ * the catch-all for everything the earlier ones left. Undefined when no component claims the file,
+ * which is also the single-component case where the dialog shows no headings at all.
+ */
+export function componentOf(name, components) {
+    return components.find((part) => part.match === undefined || part.match.test(name))?.id;
+}
 /**
  * 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.
@@ -128,14 +137,24 @@ function storeSize(sources) {
     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. */
+/**
+ * Builds the sorted target list and marks the first available target of every platform as
+ * recommended — once per component, because a person installs each part of the product in turn and
+ * every part needs its own first choice.
+ */
 export function buildDownloadTargets(sources) {
     const targets = [];
+    const components = sources.components ?? [];
+    const order = components.map((part) => part.id);
+    // A store install and the live web build have no file name to match on; they are the product
+    // itself, which is the first component in install order.
+    const primaryComponent = components[0]?.id;
     if (sources.flathub) {
         targets.push({
             os: 'linux',
             arch: 'noarch',
             format: 'flathub',
+            component: primaryComponent,
             label: defaultLabel('linux', 'flathub'),
             url: `https://flathub.org/apps/${sources.flathub}`,
             available: true,
@@ -149,6 +168,7 @@ export function buildDownloadTargets(sources) {
             continue;
         targets.push({
             ...kind,
+            component: componentOf(asset.name, components),
             label: defaultLabel(kind.os, kind.format),
             url: asset.downloadUrl,
             available: true,
@@ -162,6 +182,7 @@ export function buildDownloadTargets(sources) {
             os: 'web',
             arch: 'noarch',
             format: 'web',
+            component: primaryComponent,
             label: defaultLabel('web', 'web'),
             url: sources.webAppUrl,
             available: true,
@@ -173,20 +194,23 @@ export function buildDownloadTargets(sources) {
             os: entry.platform,
             arch: 'noarch',
             format: entry.format,
+            component: entry.component,
             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) ||
+    targets.sort((a, b) => rank(order, a.component ?? '') - rank(order, b.component ?? '') ||
+        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))
+        const key = `${target.component ?? ''}:${target.os}`;
+        if (!target.available || seen.has(key))
             continue;
-        seen.add(target.os);
+        seen.add(key);
         target.recommended = true;
     }
     return targets;

package/lib/site-data/load.js

@@ -151,6 +151,7 @@ export async function loadSiteData(options) {
             targets: buildDownloadTargets({
                 assets: config.releaseAssets ? (latestRelease?.assets ?? []) : [],
                 configured: config.downloads,
+                components: config.components,
                 flathub: config.flathub,
                 flathubSize,
                 webAppUrl: config.webApp ? `${config.base}${config.webApp.replace(/^\//, '')}` : undefined,

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

@@ -41,6 +41,25 @@ export interface SiteLegalLink {
     label: string;
     url: string;
 }
+/**
+ * One part of the product a person installs separately — a desktop app, the browser extension it
+ * pairs with, a command line build. Declared in `gjsify.site.components`, in the order they are
+ * installed, which is the order the download dialog explains them in.
+ */
+export interface SiteComponent {
+    /** Referenced by `gjsify.site.downloads[].component`; also the `data-component` attribute. */
+    id: string;
+    /** English heading, translated through the website catalogue. */
+    name: string;
+    /** One sentence saying what this part is for and why it is needed. */
+    summary?: string;
+    /**
+     * Release assets whose file name matches belong to this component. Anchor it, because the
+     * first matching component in declaration order wins; a component without one takes whatever
+     * is left, so the catch-all goes last.
+     */
+    match?: RegExp;
+}
 /** One entry of `gjsify.site.downloads`: a target the release assets cannot supply (a store page, the install docs). */
 export interface SiteDownloadConfig {
     platform: TargetPlatform;
@@ -51,6 +70,8 @@ export interface SiteDownloadConfig {
     label?: string;
     /** False lists the target as "not yet available" without a link. Default true. */
     available: boolean;
+    /** Id of the `gjsify.site.components` entry this target installs. */
+    component?: string;
 }
 /** The `gjsify.site` block of the root package.json, with defaults applied. */
 export interface SiteConfig {
@@ -75,6 +96,11 @@ export interface SiteConfig {
     pageTranslations?: string;
     /** Repo-relative app icon; defaults to the Flatpak or `ship` icon of the root package.json. */
     icon?: string;
+    /**
+     * The separately installed parts of the product, in install order. Empty for the common case of
+     * one thing to download, which the dialog then lists without any component heading.
+     */
+    components: SiteComponent[];
     /** Extra download targets, added to the ones derived from the latest release. */
     downloads: SiteDownloadConfig[];
     /** False ignores the latest release's assets, so `downloads` is the whole list. Default true. */
@@ -107,6 +133,8 @@ export interface DownloadTarget {
     os: TargetPlatform;
     arch: TargetArch;
     format: TargetFormat;
+    /** Id of the `SiteComponent` this target installs; empty when the product has only one part. */
+    component?: string;
     /** English label; the page translates it through the website catalogue. */
     label: string;
     /** Empty when the target is not available yet. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/site",
-    "version": "0.64.1-next.245",
+    "version": "0.64.1-next.248",
     "description": "Static landing page generator for a GNOME-style app, rendered from its AppStream metainfo — downloads, screenshots, release notes, support links, no JavaScript required.",
     "type": "module",
     "main": "lib/index.js",
@@ -54,26 +54,26 @@
     "license": "MIT",
     "dependencies": {
         "@girs/gdkpixbuf-2.0": "5.4.0",
-        "@gjsify/console": "0.64.1-next.245",
-        "@gjsify/crypto": "0.64.1-next.245",
-        "@gjsify/fs": "0.64.1-next.245",
-        "@gjsify/module": "0.64.1-next.245",
-        "@gjsify/os": "0.64.1-next.245",
-        "@gjsify/path": "0.64.1-next.245",
-        "@gjsify/process": "0.64.1-next.245",
-        "@gjsify/url": "0.64.1-next.245",
+        "@gjsify/console": "0.64.1-next.248",
+        "@gjsify/crypto": "0.64.1-next.248",
+        "@gjsify/fs": "0.64.1-next.248",
+        "@gjsify/module": "0.64.1-next.248",
+        "@gjsify/os": "0.64.1-next.248",
+        "@gjsify/path": "0.64.1-next.248",
+        "@gjsify/process": "0.64.1-next.248",
+        "@gjsify/url": "0.64.1-next.248",
         "fast-xml-parser": "^5.11.2",
         "qrcode-generator": "^2.0.4"
     },
     "devDependencies": {
-        "@gjsify/cli": "0.64.1-next.245",
+        "@gjsify/cli": "0.64.1-next.248",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",
-        "@gjsify/unit": "0.64.1-next.245",
+        "@gjsify/unit": "0.64.1-next.248",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "gjsify": {
         "tier": 2
     },
-    "gitHead": "9a6ca179c1a74477f23791c5b8f6d5a7bffaee61"
+    "gitHead": "4f1f2d4d5330581f496a627fa33133d2769af1a2"
 }

package/po/de.po

@@ -111,18 +111,21 @@ msgstr "Empfohlen"
 msgid "Not yet available"
 msgstr "Noch nicht verfügbar"
 
-msgid "All releases"
-msgstr "Alle Versionen"
-
 msgid "Apple Silicon is assumed. Pick the Intel build if your Mac has an Intel processor."
 msgstr "Apple Silicon wird angenommen. Für Macs mit Intel-Prozessor die Intel-Variante wählen."
 
-msgid "All download options"
-msgstr "Alle Download-Optionen"
+msgid "Browser"
+msgstr "Browser"
 
 msgid "Operating system"
 msgstr "Betriebssystem"
 
+msgid "All releases"
+msgstr "Alle Versionen"
+
+msgid "All download options"
+msgstr "Alle Download-Optionen"
+
 msgid "All releases on GitHub"
 msgstr "Alle Versionen auf GitHub"
 

package/po/site.pot

@@ -110,18 +110,21 @@ msgstr ""
 msgid "Not yet available"
 msgstr ""
 
-msgid "All releases"
-msgstr ""
-
 msgid "Apple Silicon is assumed. Pick the Intel build if your Mac has an Intel processor."
 msgstr ""
 
-msgid "All download options"
+msgid "Browser"
 msgstr ""
 
 msgid "Operating system"
 msgstr ""
 
+msgid "All releases"
+msgstr ""
+
+msgid "All download options"
+msgstr ""
+
 msgid "All releases on GitHub"
 msgstr ""