@gjsify/adwaita-app 0.51.1 → 0.53.0

package/README.md

@@ -64,7 +64,8 @@ promise-job queue under `run()`).
 
 - `runAdwaitaApp(options): Promise<number>` — construct + run, resolve with the
   exit code. `AdwaitaAppOptions`: `applicationId`, `createWindow`, optional
-  `flags`, `css`, `about` (`AboutInfo`), `quitAction` (default on, `<primary>q`),
+  `flags`, `css`, `about` (`AboutInfo`) or `aboutAppdata`
+  (`CreateAboutDialogOptions`, see below), `quitAction` (default on, `<primary>q`),
   `devtools` (`true` | `InstallDevtoolsOptions` | omitted = env-gated),
   `bundledIcons` (default on — see below), `onStartup`.
 - `AdwaitaApp` — the configured `Adw.Application` subclass, if you need the
@@ -128,15 +129,150 @@ has nothing behind it but GTK's own builtins. Register your own with
 > the guarantee is built on the icon THEME rather than on handing widgets an
 > imported SVG: for most of them there is no property to hand it to.
 
+### About dialog from AppStream metainfo
+
+`Adw.AboutDialog.new_from_appdata()` builds the whole dialog out of the metainfo
+file an application already ships — name, developer, licence, urls, version,
+release notes, translated. **It does not exist in the Windows GTK runtime.**
+gvsbuild applies `patches/libadwaita/0001-remove-appstream-dependency.patch`,
+which wraps every `*_from_appdata` entry point in `#ifndef G_OS_WIN32`, because
+libadwaita 1.9.x parses AppStream through the heavyweight `appstream` library
+and gvsbuild defines no project for it. Homebrew's formula `depends_on
+"appstream"`, so **both darwin bundles have it and win32-x64 does not** —
+measured symbol by symbol out of each published bundle's own `Adw-1.typelib`
+([gjsify/gjsify#1662](https://github.com/gjsify/gjsify/issues/1662)). On Windows
+11 the ordinary call site reads `no static method 'new_from_appdata'` and the
+About dialog does not open at all.
+
+`createAboutDialog` is the drop-in that works on all three:
+
+```ts
+import { createAboutDialog } from '@gjsify/adwaita-app';
+
+createAboutDialog({
+    appdataResource: '/org/example/App/metainfo/org.example.App.metainfo.xml',
+    releaseNotesVersion: PACKAGE_VERSION,
+    version: PACKAGE_VERSION,
+}).present(window);
+```
+
+Or let the shell wire the `app.about` action to it:
+
+```ts
+runAdwaitaApp({
+    applicationId: 'org.example.App',
+    createWindow,
+    aboutAppdata: { appdataResource: '/org/example/App/metainfo/org.example.App.metainfo.xml' },
+});
+```
+
+Where the constructor exists it is used, unchanged. Where it does not, the same
+dialog is assembled from the same document by `parseAppdata` — which **ports
+`ministream`'s selection rules rule for rule** (the small parser libadwaita 1.10
+replaced the `appstream` dependency with): BCP-47 segment scoring for
+translations, the `+1024` shift that ranks `<developer><name>` over the legacy
+`<developer_name>`, the `.desktop` id rule, per-language release-note buffers.
+Picking fields by our own taste would show a *different* About dialog on Windows
+than on the two platforms that run the real constructor, which is the whole
+failure this closes.
+
+It sets exactly what upstream's `populate_from_appdata` sets and nothing else —
+application icon (from `<id>`), application name, developer name, version,
+website, support url, issue url, licence **type**, and the release notes of one
+named release. No `comments`, no `copyright`, no `translator-credits`, no
+`developers`: AppStream's `<summary>` is not `Adw.AboutDialog:comments` and
+upstream never treats it as one. Set those on the returned dialog yourself.
+
+Three things it does that upstream does not, each for a measured reason:
+
+| | why |
+|---|---|
+| checks the resource with `Gio.resources_get_info` **before** calling the constructor | libadwaita reports an unreadable resource with `g_error()`, which **aborts the process** — a mistyped resource path would kill the app the moment the user opens About, with no exception for any `catch` to see |
+| accepts `appdataPath`, a plain file | a `gjsify ship` artifact may carry the metainfo beside the bundle rather than inside a GResource; upstream's constructor cannot read that at all, so such an app would have no About dialog on *any* platform |
+| `forceParsedAppdata: true` | the parsed path is what every Windows user sees and what no Linux or macOS run would otherwise execute — this is how you look at it before shipping, and how the suite covers it |
+
+**Two divergences, both named.** Releases are read in document order rather than
+sorted by ministream's dpkg-style version comparison (AppStream requires
+newest-first, and `appstreamcli validate` reports `releases-not-in-order`
+otherwise) — pass `version` to remove the question on every platform at once. And
+an SPDX id GTK does not know becomes `Gtk.License.CUSTOM` with **no** licence
+text, exactly as upstream leaves it; filling the text with the raw id would be
+more helpful and would show a licence line on Windows that Linux does not.
+
+- `createAboutDialog(options?): Adw.AboutDialog` — `appdataResource`,
+  `appdataPath`, `releaseNotesVersion`, `version`, `applicationIcon`,
+  `forceParsedAppdata`.
+- `buildAboutDialogFromAppdata(xml, { releaseNotesVersion?, locale? }): Adw.AboutDialog`
+  — the parsed path on its own, given the document.
+- `applyAppdataFields(dialog, fields, releaseNotesVersion?)` — for an app that
+  already has a dialog.
+- `parseAppdata(xml, { locale?, releaseNotesVersion? }): AppdataFields` and
+  `appdataLocale(GLib.get_language_names(), { LANG })` — the reading half, with
+  **no GI imports**, so it runs (and is tested) under Node as well as GJS.
+- `licenseTypeFor(spdxId): Gtk.License`, `hasAppdataConstructor(namespace?): boolean`.
+
 ### Navigation shell
 
 - `createNavShell(window, options): NavShell` — builds the
   `Adw.NavigationSplitView` (sidebar `Gtk.ListBox` + content `Gtk.Stack`) into
   `window` (which owns the responsive `Adw.Breakpoint`, default `max-width: 720px`).
-  Returns `{ widget, stack, contentHeader, selectById, selectByIndex }`.
+  Returns `{ widget, stack, contentHeader, setItems, selectById, selectByIndex }`.
 - `resolveInitialNavIndex(items, wantedId?)`, `findNavItem(items, id)` — pure
   helpers (e.g. to turn a `${PREFIX}_VIEW` dev hook into a start index).
 
+`NavShellOptions` beyond `items` / `onSelect`: `sidebarTitle`, `sidebarHeaderStart`,
+`sidebarHeaderEnd`, `collapseWidth`, and the three below.
+
+#### A sidebar that fills asynchronously
+
+`setItems(items)` rebuilds the rows in place and replaces the items behind them, so
+`row-selected` → `onSelect(item, index)` and `selectById` / `selectByIndex` always
+resolve against the items you last passed. A hand-rolled `append` does not: inserting a
+row shifts every row below it, and an index read against the array the shell was built
+with hands `onSelect` the wrong item with no error anywhere.
+
+```ts
+const shell = createNavShell(this, {
+    items: [],
+    onSelect: (item) => shell.stack.set_visible_child_name(item.id),
+});
+
+loadInbox().then((threads) => {
+    shell.setItems(threads.map((t) => ({ id: t.id, label: t.subject, icon: 'mail-inbox-symbolic' })));
+    shell.selectById(threads[0].id);
+});
+```
+
+The `Gtk.Stack` stays yours: `setItems` does not touch it, so a page outliving its item
+is your call to keep or drop.
+
+The selected id survives a `setItems` if the new items still carry it, and `onSelect`
+does **not** fire — a rebuild is not a selection, and re-announcing the same item would
+make `onSelect` fire on every list update. An item that is gone leaves nothing selected;
+`selectById` is how you pick the replacement deliberately.
+
+#### Group headers
+
+`headerFunc(row, before)` goes straight into `Gtk.ListBox.set_header_func`. `before` is
+the `NavItem` of the row above `row`, or `null` for the first row — a header is a
+comparison against the previous section, so that is what it hands you. Return `null` to
+draw no header. (The `NavItem` is passed, not the row: the row is right there as `row`.)
+
+```ts
+createNavShell(this, {
+    items: NAV,
+    onSelect: (item) => shell.stack.set_visible_child_name(item.id),
+    headerFunc: (_row, before) =>
+        before && before.id.startsWith('pinned/') ? null : new Gtk.Label({ cssClasses: ['heading'], label: 'Threads' }),
+});
+```
+
+#### Bottom bars
+
+`sidebarBottomBar` and `contentBottomBar` are the respective `Adw.ToolbarView`s'
+`add_bottom_bar` — a control under the sidebar list, and one under the content stack
+rather than inside it.
+
 ### Async view mounting
 
 - `LoadToken` + `loadIntoStack({ stack, token, load, fill, onError? })` — show a
@@ -155,12 +291,65 @@ has nothing behind it but GTK's own builtins. Register your own with
 - `pickFile(parent, { title?, filters? }): Promise<string | null>` /
   `saveFile(parent, { title?, filters?, initialName? }): Promise<string | null>`
 
+### macOS system accent
+
+A GTK window needs nothing here: libadwaita ≥ 1.6 follows the macOS accent itself,
+and `Adw.StyleManager:accent-color` is read-only. This is for what has no libadwaita
+in the process — a web view (WebKit resolves CSS `AccentColor` to blue whatever the
+setting) or a headless companion process — and it is GTK-free, so import it from
+the `@gjsify/adwaita-app/system-accent` subpath there.
+
+- `readMacosAccentColor(): AdwAccentColorName | null` — runs
+  `defaults read -g AppleAccentColor` and maps it with `@gjsify/adwaita-core`'s
+  `adwAccentFromAppleAccentColor` (graphite → `slate`, Multicolor → `blue`).
+  `null` off macOS or for a value macOS does not define.
+- `onMacosAccentColorChanged(listener, { intervalSeconds? }): () => void` — calls
+  `listener` with the new accent when it changes; re-reads every 5 s by default
+  (there is no change signal GI can reach). Hold and call the returned unsubscribe.
+
 ### Dev hooks
 
 - `readAppDevHooks({ prefix, env? }): { view?, file?, debug }` — the
   `${PREFIX}_VIEW` / `${PREFIX}_FILE` / `${PREFIX}_DEBUG` env pattern (e.g.
   `MYAPP_VIEW=reports myapp` to open straight to a view in dev).
 
+## Desktop appearance (`@gjsify/adwaita-app/appearance`)
+
+The desktop's accent colour and colour-scheme preference, for a process that never
+opens a window: a server behind a web UI, a bridge, a CLI. A GTK app does not need
+it, because `Adw.StyleManager` already applies the same values to its widgets. This
+subpath loads only Gio and GLib ([ADR 0078](../../../docs/adr/0078-the-desktop-appearance-reaches-a-web-page-through-a-handoff.md)).
+
+```ts
+import { readDesktopAppearance, renderAppearanceMeta, watchDesktopAppearance } from '@gjsify/adwaita-app/appearance';
+
+const appearance = await readDesktopAppearance();
+// { accent: 'purple', accentRgb: '#9141ac', colorScheme: 'dark' }; absent fields are unknown
+
+const head = renderAppearanceMeta(appearance);
+// <meta name="adw-accent" content="purple">
+// <meta name="adw-color-scheme" content="dark">
+
+const stop = watchDesktopAppearance((next) => broadcast(JSON.stringify(next))); // hold `stop`
+```
+
+A web server must `listen()` before the module's first top-level await. On GJS a server
+started after one exits as soon as the module settles; see `status/open-todos/README.md`.
+[`examples/node/net-adwaita-appearance`](../../../examples/node/net-adwaita-appearance)
+serves a complete page that way.
+
+A reported colour is snapped to one of libadwaita's nine accents with
+`nearestAccent`, as libadwaita does. The reader never throws. Sources per OS:
+
+| OS | Reads | Follows changes by | Measured |
+|---|---|---|---|
+| Linux (GNOME, KDE, Flatpak) | XDG Settings portal `org.freedesktop.appearance`, then GSettings `org.gnome.desktop.interface` for what the portal left unknown, only when `XDG_CURRENT_DESKTOP` names GNOME (elsewhere the schema answers its defaults) | `SettingChanged`, `changed::` | yes, in CI, against a fake portal on a peer D-Bus connection |
+| Windows | `reg.exe query`: `Explorer\Accent AccentPalette` (else `DWM AccentColor`), `Personalize AppsUseLightTheme` | polling every 3 s | mapping only; reg.exe not run on Windows |
+| macOS | `defaults read -g AppleAccentColor / AppleInterfaceStyle / AppleInterfaceStyleSwitchesAutomatically` | a debounced monitor on `~/Library/Preferences` | mapping only; not run end to end on a Mac |
+
+On macOS with Auto appearance and no `AppleInterfaceStyle` key, `colorScheme` stays
+absent: the system switches by time of day, so a missing key does not prove light.
+
 ## See also
 
 - [`@gjsify/devtools`](../devtools) — the DBus control plane wired in on startup.

package/lib/esm/about-dialog.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{appdataLocale as e,parseAppdata as t}from"./appdata.js";import n from"gi://Adw?version=1";import r from"gi://Gio?version=2.0";import i from"gi://GLib?version=2.0";import a from"gi://Gtk?version=4.0";const o={"GPL-2.0-or-later":a.License.GPL_2_0,"GPL-3.0-or-later":a.License.GPL_3_0,"LGPL-2.1-or-later":a.License.LGPL_2_1,"LGPL-3.0-or-later":a.License.LGPL_3_0,"BSD-2-Clause":a.License.BSD,MIT:a.License.MIT_X11,"Artistic-2.0":a.License.ARTISTIC,"GPL-2.0-only":a.License.GPL_2_0_ONLY,"GPL-3.0-only":a.License.GPL_3_0_ONLY,"LGPL-2.1-only":a.License.LGPL_2_1_ONLY,"LGPL-3.0-only":a.License.LGPL_3_0_ONLY,"AGPL-3.0-or-later":a.License.AGPL_3_0,"AGPL-3.0-only":a.License.AGPL_3_0_ONLY,"BSD-3-Clause":a.License.BSD_3,"Apache-2.0":a.License.APACHE_2_0,"MPL-2.0":a.License.MPL_2_0,"0BSD":a.License[`0BSD`],"GPL-2.0":a.License.GPL_2_0_ONLY,"GPL-3.0":a.License.GPL_3_0_ONLY};function licenseTypeFor(e){return o[e]??a.License.CUSTOM}function hasAppdataConstructor(e=n){try{return typeof e?.AboutDialog?.new_from_appdata==`function`}catch{return!1}}function applyAppdataFields(e,t,n){return t.applicationId!==null&&(e.applicationIcon=t.applicationId),t.applicationName!==null&&(e.applicationName=t.applicationName),t.developerName!==null&&(e.developerName=t.developerName),t.website!==null&&(e.website=t.website),t.supportUrl!==null&&(e.supportUrl=t.supportUrl),t.issueUrl!==null&&(e.issueUrl=t.issueUrl),t.license!==null&&(e.licenseType=licenseTypeFor(t.license)),n!==void 0&&n!==``&&(e.releaseNotesVersion=n),t.releaseNotes!==null&&(e.releaseNotes=t.releaseNotes),t.version!==null&&(e.version=t.version),e}function buildAboutDialogFromAppdata(r,a={}){let o=t(r,{locale:a.locale??e(i.get_language_names(),{LANG:i.getenv(`LANG`)??void 0}),releaseNotesVersion:a.releaseNotesVersion});return applyAppdataFields(new n.AboutDialog,o,a.releaseNotesVersion)}function resourceExists(e){try{return r.resources_get_info(e,r.ResourceLookupFlags.NONE),!0}catch{return!1}}function readResource(e){try{let t=r.resources_lookup_data(e,r.ResourceLookupFlags.NONE);return new TextDecoder().decode(t.toArray())}catch{return null}}function readFile(e){try{let[t,n]=i.file_get_contents(e);return t?new TextDecoder().decode(n):null}catch{return null}}let s=!1;function createAboutDialog(e={}){let{appdataResource:t,appdataPath:r,releaseNotesVersion:i}=e,a=t!==void 0&&resourceExists(t),o;if(!e.forceParsedAppdata&&a&&hasAppdataConstructor())o=n.AboutDialog.new_from_appdata(t,i??``);else{let c=(a?readResource(t):null)??(r===void 0?null:readFile(r));c===null?(console.error(`@gjsify/adwaita-app: no AppStream metainfo found for the About dialog; looked at resource ${t??`(none given)`} and file ${r??`(none given)`}`),o=new n.AboutDialog):(!s&&!e.forceParsedAppdata&&a&&(s=!0,console.log(`@gjsify/adwaita-app: Adw.AboutDialog.new_from_appdata is not in this GTK runtime (expected on Windows — gjsify/gjsify#1662); building the About dialog from the AppStream metainfo directly.`)),o=buildAboutDialogFromAppdata(c,{releaseNotesVersion:i}))}return e.applicationIcon!==void 0&&(o.applicationIcon=e.applicationIcon),e.version!==void 0&&(o.version=e.version),o}export{applyAppdataFields,buildAboutDialogFromAppdata,createAboutDialog,hasAppdataConstructor,licenseTypeFor};

package/lib/esm/appdata-xml.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e={amp:`&`,lt:`<`,gt:`>`,quot:`"`,apos:`'`};function decodeXmlEntities(t){return t.includes(`&`)?t.replace(/&(#[Xx][0-9A-Fa-f]+|#[0-9]+|[A-Za-z][A-Za-z0-9]*);/g,(t,n)=>{if(n.charAt(0)!==`#`)return e[n]??t;let r=n.charAt(1)===`x`||n.charAt(1)===`X`,i=Number.parseInt(r?n.slice(2):n.slice(1),r?16:10);return!Number.isFinite(i)||i<1||i>1114111||i>=55296&&i<=57343?t:String.fromCodePoint(i)}):t}function findTagEnd(e,t){let n=``;for(let r=t+1;r<e.length;r++){let t=e.charAt(r);if(n)t===n&&(n=``);else if(t===`"`||t===`'`)n=t;else if(t===`>`)return r}return-1}const t=/([^\s=/<>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;function parseAttributes(e){let n={};t.lastIndex=0;let r=t.exec(e);for(;r!==null;)r[1]in n||(n[r[1]]=decodeXmlEntities(r[2]??r[3]??``)),r=t.exec(e);return n}function scanXml(e){let t=[],pushText=e=>{t.push({kind:`text`,text:decodeXmlEntities(e)})},n=0;for(;n<e.length;){let r=e.indexOf(`<`,n);if(r<0){pushText(e.slice(n));break}if(r>n&&pushText(e.slice(n,r)),e.startsWith(`<!--`,r)){let t=e.indexOf(`-->`,r+4);n=t<0?e.length:t+3;continue}if(e.startsWith(`<![CDATA[`,r)){let i=e.indexOf(`]]>`,r+9);t.push({kind:`text`,text:e.slice(r+9,i<0?e.length:i)}),n=i<0?e.length:i+3;continue}if(e.startsWith(`<?`,r)){let t=e.indexOf(`?>`,r+2);n=t<0?e.length:t+2;continue}if(e.startsWith(`<!`,r)){let t=e.indexOf(`>`,r+2);n=t<0?e.length:t+1;continue}let i=findTagEnd(e,r);if(i<0){pushText(e.slice(r));break}let a=e.slice(r+1,i);if(n=i+1,a.charAt(0)===`/`){let e=a.slice(1).trim();e!==``&&t.push({kind:`close`,name:e});continue}let o=a,s=!1;o.endsWith(`/`)&&(s=!0,o=o.slice(0,-1));let c=/^([^\s/<>]+)/.exec(o);if(c===null)continue;let l=c[1];t.push({kind:`open`,name:l,attributes:parseAttributes(o.slice(l.length)),selfClosing:s})}return t}export{decodeXmlEntities,scanXml};

package/lib/esm/appdata.js

@@ -0,0 +1,2 @@
+import"./_virtual/_rolldown/runtime.js";import{scanXml as e}from"./appdata-xml.js";const t={applicationId:null,applicationName:null,developerName:null,version:null,website:null,supportUrl:null,issueUrl:null,license:null,releaseNotes:null};function localeScore(e,t){let n=0;for(let r=0;;r++){let i=r<e.length?e.charAt(r):`\0`,a=r<t.length?t.charAt(r):`\0`;if((i===`-`||i===`\0`)&&(a===`-`||a===`\0`)&&n++,i===`\0`||a===`\0`)break;if(i!==a)return 0}return n}function appdataLocale(e,t={}){let n,r=e[0];r!==void 0&&!r.includes(`_`)&&t.LANG!==void 0&&t.LANG.includes(`_`)&&(n=t.LANG),n=n??r??`C`,n.endsWith(`.UTF-8`)&&(n=n.slice(0,-6));let i=``,a=n.indexOf(`@`);if(a>=0){let e=n.slice(a);e.startsWith(`@cyrillic`)?i=`-Cyrl`:e.startsWith(`@devanagari`)?i=`-Deva`:e.startsWith(`@latin`)?i=`-Latn`:e.startsWith(`@shaw`)?i=`-Shaw`:e.startsWith(`@euro`)||(i=`-euro`),n=n.slice(0,a)}return n.replace(/_/g,`-`)+i}function childElements(e,t,n){let r=[],i=t;for(;i<n;){let t=e[i];if(t.kind!==`open`){i+=1;continue}let a=t;if(a.selfClosing){r.push({name:a.name,attributes:a.attributes,start:i+1,end:i+1}),i+=1;continue}let o=1,s=i+1;for(;s<n&&o>0;){let t=e[s];t.kind===`open`?t.selfClosing||(o+=1):t.kind===`close`&&--o,s+=1}let c=o===0?s-1:n;r.push({name:a.name,attributes:a.attributes,start:i+1,end:c}),i=o===0?s:n}return r}function elementText(e,t){let n=0,r=``;for(let i=t.start;i<t.end;i++){let t=e[i];t.kind===`open`?t.selfClosing||(n+=1):t.kind===`close`?--n:n===0&&(r+=t.text)}return r.trim()}const lang=e=>e.attributes[`xml:lang`]??`C`;function considerTranslatable(e,t,n,r){(e.value===null&&lang(t)===`C`||r>e.score)&&(e.score=r,e.value=n)}function escapeMarkup(e){return e.replace(/&/g,`&amp;`).replace(/</g,`&lt;`).replace(/>/g,`&gt;`).replace(/'/g,`&#39;`).replace(/"/g,`&quot;`)}function inlineMarkup(e,t){let n=``,r=!0,i=0,a=0;for(let o=t.start;o<t.end;o++){let t=e[o];if(t.kind===`open`){let e=t,r=!e.selfClosing;if(r&&(a+=1),i>0)continue;e.name===`em`||e.name===`code`?n+=`<${e.name}>`:r&&(i=a)}else if(t.kind===`close`)i>0&&a===i?i=0:i===0&&(t.name===`em`||t.name===`code`)&&(n+=`</${t.name}>`),--a;else if(i===0){let e=``;for(let n of t.text){if(n===`
+`||n===`	`||n===` `){if(r)continue;e+=` `,r=!0;continue}e+=n,r=!1}n+=escapeMarkup(e)}}return n}function parseDescription(e,t,n){let r=new Map,bucketFor=(e,t)=>{if(localeScore(n,e)===0&&e!==`C`)return null;let i=r.get(e);return i===void 0&&(i=[],r.set(e,i),t!==void 0&&i.push(`<${t}>\n`)),i};for(let n of childElements(e,t.start,t.end))if(n.name===`p`)bucketFor(lang(n))?.push(`<p>${inlineMarkup(e,n)}</p>\n`);else if(n.name===`ul`||n.name===`ol`){for(let e of r.values())e.push(`<${n.name}>\n`);for(let t of childElements(e,n.start,n.end))t.name===`li`&&bucketFor(lang(t),n.name)?.push(`<li>${inlineMarkup(e,t)}</li>\n`);for(let e of r.values())e.push(`</${n.name}>\n`)}let i=r.get(`C`),a=0;for(let[e,t]of r){let r=localeScore(n,e);r>a&&(a=r,i=t)}return i===void 0?null:i.join(``)}function parseAppdata(n,r={}){let i=r.locale??`C`,a=e(n),o=childElements(a,0,a.length).find(e=>e.name===`component`||e.name===`application`);if(o===void 0)return{...t};let s={...t},c={value:null,score:0},l={value:null,score:0},u=[],d=null;for(let e of childElements(a,o.start,o.end))switch(e.name){case`id`:s.applicationId===null&&(s.applicationId=elementText(a,e));break;case`name`:considerTranslatable(c,e,elementText(a,e),localeScore(i,lang(e)));break;case`developer`:for(let t of childElements(a,e.start,e.end)){if(t.name!==`name`)continue;let e=localeScore(i,lang(t))+1024;e>l.score&&(lang(t)===`C`||e>1024)&&(l.score=e,l.value=elementText(a,t))}break;case`developer_name`:considerTranslatable(l,e,elementText(a,e),localeScore(i,lang(e)));break;case`url`:{let t=elementText(a,e);e.attributes.type===`homepage`?s.website=t:e.attributes.type===`bugtracker`?s.issueUrl=t:e.attributes.type===`help`&&(s.supportUrl=t);break}case`launchable`:e.attributes.type===`desktop-id`&&u.push(elementText(a,e));break;case`project_license`:s.license===null&&(s.license=elementText(a,e));break;case`releases`:d===null&&(d=e);break;default:break}if(s.applicationName=c.value,s.developerName=l.value,d!==null){let e=childElements(a,d.start,d.end).filter(e=>e.name===`release`);s.version=e[0]?.attributes.version??null;let t=r.releaseNotesVersion;if(t!==void 0&&t!==``){let n=e.find(e=>e.attributes.version===t),r=n&&childElements(a,n.start,n.end).find(e=>e.name===`description`);r&&(s.releaseNotes=parseDescription(a,r,i))}}s.applicationId!==null&&s.applicationId.endsWith(`.desktop`)&&(u.includes(`${s.applicationId}.desktop`)||(s.applicationId=s.applicationId.slice(0,-8)));for(let e of Object.keys(s))s[e]===``&&(s[e]=null);return s}export{appdataLocale,localeScore,parseAppdata};

package/lib/esm/appearance/darwin.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import{appearanceFromMacDefaults as e}from"./mapping.js";import{runTool as t}from"./run-tool.js";import n from"gi://Gio?version=2.0";import r from"gi://GLib?version=2.0";const i=`.GlobalPreferences.plist`,a=750;async function readDefault(e){let n=await t([`defaults`,`read`,`-g`,e]);return n===null?null:n.trim()}async function readDarwinAppearance(){let[t,n,r]=await Promise.all([readDefault(`AppleAccentColor`),readDefault(`AppleInterfaceStyle`),readDefault(`AppleInterfaceStyleSwitchesAutomatically`)]);return e({appleAccentColor:t,appleInterfaceStyle:n,appleInterfaceStyleSwitchesAutomatically:r})}function watchDarwinAppearance(e){let t=n.File.new_for_path(r.build_filenamev([r.get_home_dir(),`Library`,`Preferences`])),a;try{a=t.monitor_directory(n.FileMonitorFlags.WATCH_MOVES,null)}catch{return()=>void 0}let o=0,s=a.connect(`changed`,(t,n,a)=>{n.get_basename()!==i&&a?.get_basename()!==i||(o&&r.source_remove(o),o=r.timeout_add(r.PRIORITY_DEFAULT,750,()=>(o=0,e(),r.SOURCE_REMOVE)))});return()=>{o&&r.source_remove(o),a.disconnect(s),a.cancel()}}export{a as DARWIN_DEBOUNCE_MS,readDarwinAppearance,watchDarwinAppearance};

package/lib/esm/appearance/gnome-settings.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import{appearanceFromGnomeSettings as e}from"./mapping.js";import t from"gi://Gio?version=2.0";const n=`org.gnome.desktop.interface`;function gnomeSettingsSource(){let e=t.SettingsSchemaSource.get_default()?.lookup(n,!0);if(!e)return null;let r=[`accent-color`,`color-scheme`].filter(t=>e.has_key(t));return r.length===0?null:{settings:new t.Settings({settings_schema:e}),keys:r}}function readGnomeSettings(t){let read=e=>t.keys.includes(e)?t.settings.get_string(e):null;return e({accentColor:read(`accent-color`),colorScheme:read(`color-scheme`)})}function watchGnomeSettings(e,t){let n=e.keys.map(n=>e.settings.connect(`changed::${n}`,()=>t()));return()=>{for(let t of n)e.settings.disconnect(t)}}export{n as GNOME_INTERFACE_SCHEMA,gnomeSettingsSource,readGnomeSettings,watchGnomeSettings};

package/lib/esm/appearance/index.js

@@ -0,0 +1 @@
+import{MACOS_ACCENT_COLORS as e,appearanceFromGnomeSettings as t,appearanceFromMacDefaults as n,appearanceFromPortal as r,appearanceFromWindowsRegistry as i,isGnomeDesktop as a,mergeAppearance as o,parseRegQuery as s,sameAppearance as c}from"./mapping.js";import{readPortalAppearance as l,watchPortalAppearance as u}from"./portal.js";import{readDesktopAppearance as d,watchDesktopAppearance as f}from"./reader.js";import{parseDesktopAppearance as p,renderAppearanceMeta as m}from"@gjsify/adwaita-core";export{e as MACOS_ACCENT_COLORS,t as appearanceFromGnomeSettings,n as appearanceFromMacDefaults,r as appearanceFromPortal,i as appearanceFromWindowsRegistry,a as isGnomeDesktop,o as mergeAppearance,p as parseDesktopAppearance,s as parseRegQuery,d as readDesktopAppearance,l as readPortalAppearance,m as renderAppearanceMeta,c as sameAppearance,f as watchDesktopAppearance,u as watchPortalAppearance};

package/lib/esm/appearance/mapping.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import{formatAdwRgb as e,isAdwAccentColorName as t,nearestAccent as n,parseAdwRgb as r}from"@gjsify/adwaita-core";function fromRgb(t){return{accent:n(t),accentRgb:e(t)}}function compact(e){let t={};return e.accent&&(t.accent=e.accent),e.accentRgb&&(t.accentRgb=e.accentRgb),e.colorScheme&&(t.colorScheme=e.colorScheme),t}function mergeAppearance(e,t){let n=e.accent!==void 0;return compact({accent:e.accent??t.accent,accentRgb:n?e.accentRgb:t.accentRgb,colorScheme:e.colorScheme??t.colorScheme})}function sameAppearance(e,t){return e.accent===t.accent&&e.accentRgb===t.accentRgb&&e.colorScheme===t.colorScheme}function appearanceFromPortal(e){let t=e[`color-scheme`],n=t===0?`no-preference`:t===1?`dark`:t===2?`light`:void 0,r=e[`accent-color`],i;return Array.isArray(r)&&r.length===3&&r.every(e=>typeof e==`number`&&e>=0&&e<=1)&&(i={red:r[0],green:r[1],blue:r[2]}),compact({...i?fromRgb(i):{},colorScheme:n})}function isGnomeDesktop(e){return(e??``).split(`:`).some(e=>e.trim().toUpperCase()===`GNOME`)}function appearanceFromGnomeSettings(e){return compact({accent:e.accentColor&&t(e.accentColor)?e.accentColor:void 0,colorScheme:e.colorScheme==="default"?`no-preference`:e.colorScheme===`prefer-dark`?`dark`:e.colorScheme===`prefer-light`?`light`:void 0})}function appearanceFromWindowsRegistry(e){let t,n=e.accentPalette;if(n&&n.length>=16)t={red:n[12]/255,green:n[13]/255,blue:n[14]/255};else if(typeof e.dwmAccentColor==`number`){let n=e.dwmAccentColor;t={red:(n&255)/255,green:(n>>>8&255)/255,blue:(n>>>16&255)/255}}let r=e.appsUseLightTheme,i=r===0?`dark`:r===1?`light`:void 0;return compact({...t?fromRgb(t):{},colorScheme:i})}const i={"-1":`#8c8c8c`,0:`#ff5257`,1:`#f7821a`,2:`#ffc602`,3:`#62ba46`,4:`#017bff`,5:`#a550a7`,6:`#f8509e`};function appearanceFromMacDefaults(e){let t=e.appleAccentColor?.trim(),n=t==null||t===``?i[4]:i[t],a=n?r(n):null,o=e.appleInterfaceStyle?.trim(),s=e.appleInterfaceStyleSwitchesAutomatically?.trim()===`1`,c=o===`Dark`?`dark`:o||s?void 0:`light`;return compact({...a?fromRgb(a):{},colorScheme:c})}function parseRegQuery(e,t){for(let n of e.split(/\r?\n/)){let e=/^\s+(.+?)\s{2,}(REG_\w+)\s{2,}(\S*)\s*$/.exec(n);if(!e||e[1]!==t)continue;let[,,r,i]=e;if(r===`REG_DWORD`){let e=Number.parseInt(i,16);return Number.isFinite(e)?e>>>0:null}if(r===`REG_BINARY`){if(i.length%2!=0||!/^[0-9a-f]*$/i.test(i))return null;let e=new Uint8Array(i.length/2);for(let t=0;t<e.length;t++)e[t]=Number.parseInt(i.slice(t*2,t*2+2),16);return e}return null}return null}export{i as MACOS_ACCENT_COLORS,appearanceFromGnomeSettings,appearanceFromMacDefaults,appearanceFromPortal,appearanceFromWindowsRegistry,isGnomeDesktop,mergeAppearance,parseRegQuery,sameAppearance};

package/lib/esm/appearance/portal.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import{appearanceFromPortal as e}from"./mapping.js";import t from"gi://Gio?version=2.0";import n from"gi://GLib?version=2.0";const r=`org.freedesktop.portal.Desktop`,i=`/org/freedesktop/portal/desktop`,a=`org.freedesktop.portal.Settings`,o=`org.freedesktop.appearance`;function readPortalAppearance(r){return new Promise(s=>{r.connection.call(r.busName,i,a,`ReadAll`,new n.Variant(`(as)`,[[o]]),new n.VariantType(`(a{sa{sv}})`),t.DBusCallFlags.NONE,5e3,null,(t,n)=>{try{let[r]=t.call_finish(n).recursiveUnpack();s(e(r[`org.freedesktop.appearance`]??{}))}catch{s(null)}})})}function watchPortalAppearance(e,n){let r=e.connection.signal_subscribe(e.busName,a,`SettingChanged`,i,o,t.DBusSignalFlags.NONE,()=>n());return()=>e.connection.signal_unsubscribe(r)}function sessionPortalEndpoint(){return new Promise(e=>{t.bus_get(t.BusType.SESSION,null,(n,i)=>{try{e({connection:t.bus_get_finish(i),busName:r})}catch{e(null)}})})}export{o as APPEARANCE_NAMESPACE,r as PORTAL_BUS_NAME,i as PORTAL_OBJECT_PATH,a as PORTAL_SETTINGS_INTERFACE,readPortalAppearance,sessionPortalEndpoint,watchPortalAppearance};

package/lib/esm/appearance/reader.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import{isGnomeDesktop as e,mergeAppearance as t,sameAppearance as n}from"./mapping.js";import{readDarwinAppearance as r,watchDarwinAppearance as i}from"./darwin.js";import{gnomeSettingsSource as a,readGnomeSettings as o,watchGnomeSettings as s}from"./gnome-settings.js";import{readPortalAppearance as c,sessionPortalEndpoint as l,watchPortalAppearance as u}from"./portal.js";import{readWin32Appearance as d,watchWin32Appearance as f}from"./win32.js";import p from"gi://GLib?version=2.0";function currentPlatform(e){return e.platform?e.platform:typeof process>`u`?void 0:process.platform}function linuxBackend(n){let r,sources=()=>(r??=(async()=>({portal:n.portal===void 0?await l():n.portal,settings:e(n.currentDesktop===void 0?p.getenv(`XDG_CURRENT_DESKTOP`):n.currentDesktop)?n.gnomeSettings===void 0?a():n.gnomeSettings:null}))(),r);return{async read(){let{portal:e,settings:n}=await sources(),r=e?await c(e):null,i=n?o(n):{};return t(r??{},i)},watch(e){let t=[],n=!1;return sources().then(({portal:r,settings:i})=>{n||(r&&t.push(u(r,e)),i&&t.push(s(i,e)))}),()=>{n=!0;for(let e of t)e();t=[]}}}}function backendFor(e){let t=currentPlatform(e);return t===`win32`?{read:d,watch:f}:t===`darwin`?{read:r,watch:i}:linuxBackend(e)}function readDesktopAppearance(e={}){return backendFor(e).read()}function watchDesktopAppearance(e,t={}){let r=backendFor(t),i,a=!1,o=Promise.resolve(),refresh=()=>{o=o.then(async()=>{let t=await r.read();a||i&&n(i,t)||(i=t,e(t))})},s=r.watch(refresh);return refresh(),()=>{a=!0,s()}}export{readDesktopAppearance,watchDesktopAppearance};

package/lib/esm/appearance/run-tool.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import e from"gi://Gio?version=2.0";function runTool(t){return new Promise(n=>{let r;try{r=e.Subprocess.new([...t],e.SubprocessFlags.STDOUT_PIPE|e.SubprocessFlags.STDERR_SILENCE)}catch{n(null);return}r.communicate_utf8_async(null,null,(e,t)=>{try{let[,r]=e.communicate_utf8_finish(t);n(e.get_successful()?r??``:null)}catch{n(null)}})})}export{runTool};

package/lib/esm/appearance/win32.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import{appearanceFromWindowsRegistry as e,parseRegQuery as t}from"./mapping.js";import{runTool as n}from"./run-tool.js";import r from"gi://GLib?version=2.0";const i=3;async function queryValue(e,r){let i=await n([`reg`,`query`,e,`/v`,r]);return i===null?null:t(i,r)}async function readWin32Appearance(){let[t,n]=await Promise.all([queryValue(`HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Accent`,`AccentPalette`),queryValue(`HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize`,`AppsUseLightTheme`)]),r=t instanceof Uint8Array?t:null,i=r?null:await queryValue(`HKCU\\Software\\Microsoft\\Windows\\DWM`,`AccentColor`);return e({accentPalette:r,dwmAccentColor:typeof i==`number`?i:null,appsUseLightTheme:typeof n==`number`?n:null})}function watchWin32Appearance(e){let t=r.timeout_add_seconds(r.PRIORITY_DEFAULT,3,()=>(e(),r.SOURCE_CONTINUE));return()=>r.source_remove(t)}export{i as WIN32_POLL_INTERVAL_S,readWin32Appearance,watchWin32Appearance};

package/lib/esm/application.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{installBundledIconTheme as e}from"./icon-theme.js";import t from"gi://Adw?version=1";import n from"gi://Gdk?version=4.0";import r from"gi://Gio?version=2.0";import i from"gi://GObject?version=2.0";import a from"gi://Gtk?version=4.0";import o from"system";import{installDevtools as s}from"@gjsify/devtools";var c=class AdwaitaApp extends t.Application{static{i.registerClass({GTypeName:`GjsifyAdwaitaApp`},AdwaitaApp)}constructor(e){super({application_id:e.applicationId,flags:e.flags??r.ApplicationFlags.DEFAULT_FLAGS}),this._window=null,this._options=e,this._initActions(),this.connect(`startup`,()=>this._onStartup()),this.connect(`activate`,()=>this._onActivate())}_initActions(){if(this._options.quitAction!==!1){let e=new r.SimpleAction({name:`quit`});e.connect(`activate`,()=>this.quit()),this.add_action(e),this.set_accels_for_action(`app.quit`,[`<primary>q`])}if(this._options.about){let e=new r.SimpleAction({name:`about`});e.connect(`activate`,()=>this._showAbout()),this.add_action(e)}}_onStartup(){this._installBundledIcons(),this._options.css&&this._loadCss(this._options.css),this._installDevtools(),this._options.onStartup?.(this)}_installBundledIcons(){let t=this._options.bundledIcons;t!==!1&&e(typeof t==`object`?t:{})}_loadCss(e){let t=n.Display.get_default();if(!t){console.error(`@gjsify/adwaita-app: no default display; CSS not applied`);return}let r=new a.CssProvider;r.load_from_string(e),a.StyleContext.add_provider_for_display(t,r,a.STYLE_PROVIDER_PRIORITY_APPLICATION)}_installDevtools(){let e=this._options.devtools;if(e===!1)return;let t=typeof e==`object`?e:{enabled:e||void 0};s(this,t)}_onActivate(){this._window||=this._options.createWindow(this),this._window.present()}_showAbout(){let e=this._options.about;if(!e)return;let n=new t.AboutDialog({application_name:e.applicationName,application_icon:e.applicationIcon??this._options.applicationId});e.version&&(n.version=e.version),e.developerName&&(n.developer_name=e.developerName),e.website&&(n.website=e.website),e.issueUrl&&(n.issue_url=e.issueUrl),e.license&&(n.license=e.license),e.comments&&(n.comments=e.comments),e.copyright&&(n.copyright=e.copyright),e.developers?.length&&n.set_developers(e.developers),n.present(this.get_active_window())}};async function runAdwaitaApp(e){return runApplication(new c(e),[o.programInvocationName,...o.programArgs])}async function runApplication(e,t){let n=!1;try{e.register(null),n=e.get_is_remote()}catch{n=!1}let r=await e.runAsync(t);return n&&console.error(`${e.applicationId??`This application`} is already running — brought the existing instance to the front instead of opening a second window.`),r}i.type_ensure(c.$gtype);export{c as AdwaitaApp,runAdwaitaApp,runApplication};
+import"./_virtual/_rolldown/runtime.js";import{createAboutDialog as e}from"./about-dialog.js";import{installBundledIconTheme as t}from"./icon-theme.js";import n from"gi://Adw?version=1";import r from"gi://Gio?version=2.0";import i from"gi://Gtk?version=4.0";import a from"gi://Gdk?version=4.0";import o from"gi://GObject?version=2.0";import s from"system";import{installDevtools as c}from"@gjsify/devtools";var l=class AdwaitaApp extends n.Application{static{o.registerClass({GTypeName:`GjsifyAdwaitaApp`},AdwaitaApp)}constructor(e){super({application_id:e.applicationId,flags:e.flags??r.ApplicationFlags.DEFAULT_FLAGS}),this._window=null,this._options=e,this._initActions(),this.connect(`startup`,()=>this._onStartup()),this.connect(`activate`,()=>this._onActivate())}_initActions(){if(this._options.quitAction!==!1){let e=new r.SimpleAction({name:`quit`});e.connect(`activate`,()=>this.quit()),this.add_action(e),this.set_accels_for_action(`app.quit`,[`<primary>q`])}if(this._options.about||this._options.aboutAppdata){let e=new r.SimpleAction({name:`about`});e.connect(`activate`,()=>this._showAbout()),this.add_action(e)}}_onStartup(){this._installBundledIcons(),this._options.css&&this._loadCss(this._options.css),this._installDevtools(),this._options.onStartup?.(this)}_installBundledIcons(){let e=this._options.bundledIcons;e!==!1&&t(typeof e==`object`?e:{})}_loadCss(e){let t=a.Display.get_default();if(!t){console.error(`@gjsify/adwaita-app: no default display; CSS not applied`);return}let n=new i.CssProvider;n.load_from_string(e),i.StyleContext.add_provider_for_display(t,n,i.STYLE_PROVIDER_PRIORITY_APPLICATION)}_installDevtools(){let e=this._options.devtools;if(e===!1)return;let t=typeof e==`object`?e:{enabled:e||void 0};c(this,t)}_onActivate(){this._window||=this._options.createWindow(this),this._window.present()}_showAbout(){let t=this._options.aboutAppdata;if(t){e(t).present(this.get_active_window());return}let r=this._options.about;if(!r)return;let i=new n.AboutDialog({application_name:r.applicationName,application_icon:r.applicationIcon??this._options.applicationId});r.version&&(i.version=r.version),r.developerName&&(i.developer_name=r.developerName),r.website&&(i.website=r.website),r.issueUrl&&(i.issue_url=r.issueUrl),r.license&&(i.license=r.license),r.comments&&(i.comments=r.comments),r.copyright&&(i.copyright=r.copyright),r.developers?.length&&i.set_developers(r.developers),i.present(this.get_active_window())}};async function runAdwaitaApp(e){return runApplication(new l(e),[s.programInvocationName,...s.programArgs])}async function runApplication(e,t){let n=!1;try{e.register(null),n=e.get_is_remote()}catch{n=!1}let r=await e.runAsync(t);return n&&console.error(`${e.applicationId??`This application`} is already running — brought the existing instance to the front instead of opening a second window.`),r}o.type_ensure(l.$gtype);export{l as AdwaitaApp,runAdwaitaApp,runApplication};

package/lib/esm/icon-theme.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{BUNDLED_ICON_COUNT as e,BUNDLED_ICON_GRESOURCE_BASE64 as t,BUNDLED_ICON_RESOURCE_PATH as n}from"./icons.generated.js";import r from"gi://Gdk?version=4.0";import i from"gi://Gio?version=2.0";import a from"gi://Gtk?version=4.0";import o from"gi://GLib?version=2.0";const s=`gjsify-adwaita-bundled`;let c=null;function registerBundledIconResource(){if(c)return c;let e=o.base64_decode(t);return c=i.Resource.new_from_data(new o.Bytes(e)),i.resources_register(c),c}function addBundledIconsToTheme(e){registerBundledIconResource(),e.add_resource_path(n)}function installBundledIconTheme(e={}){let t=e.prefer??`fallback`;if(t===`host`)return!1;let n=e.display===void 0?r.Display.get_default():e.display;return n?(addBundledIconsToTheme(a.IconTheme.get_for_display(n)),t===`bundled`&&a.Settings.get_for_display(n).set_property(`gtk-icon-theme-name`,s),!0):!1}export{e as BUNDLED_ICON_COUNT,n as BUNDLED_ICON_RESOURCE_PATH,s as BUNDLED_ICON_THEME_NAME,addBundledIconsToTheme,installBundledIconTheme,registerBundledIconResource};
+import"./_virtual/_rolldown/runtime.js";import{BUNDLED_ICON_COUNT as e,BUNDLED_ICON_GRESOURCE_BASE64 as t,BUNDLED_ICON_RESOURCE_PATH as n}from"./icons.generated.js";import r from"gi://Gio?version=2.0";import i from"gi://GLib?version=2.0";import a from"gi://Gtk?version=4.0";import o from"gi://Gdk?version=4.0";const s=`gjsify-adwaita-bundled`;let c=null;function registerBundledIconResource(){if(c)return c;let e=i.base64_decode(t);return c=r.Resource.new_from_data(new i.Bytes(e)),r.resources_register(c),c}function addBundledIconsToTheme(e){registerBundledIconResource(),e.add_resource_path(n)}function installBundledIconTheme(e={}){let t=e.prefer??`fallback`;if(t===`host`)return!1;let n=e.display===void 0?o.Display.get_default():e.display;return n?(addBundledIconsToTheme(a.IconTheme.get_for_display(n)),t===`bundled`&&a.Settings.get_for_display(n).set_property(`gtk-icon-theme-name`,s),!0):!1}export{e as BUNDLED_ICON_COUNT,n as BUNDLED_ICON_RESOURCE_PATH,s as BUNDLED_ICON_THEME_NAME,addBundledIconsToTheme,installBundledIconTheme,registerBundledIconResource};

package/lib/esm/index.js

@@ -1 +1 @@
-import{BUNDLED_ICON_COUNT as e,BUNDLED_ICON_RESOURCE_PATH as t}from"./icons.generated.js";import{BUNDLED_ICON_THEME_NAME as n,addBundledIconsToTheme as r,installBundledIconTheme as i,registerBundledIconResource as a}from"./icon-theme.js";import{AdwaitaApp as o,runAdwaitaApp as s,runApplication as c}from"./application.js";import{readAppDevHooks as l}from"./dev-hooks.js";import{confirmDialog as u,errorDialog as d}from"./dialogs.js";import{pickFile as f,saveFile as p}from"./file-dialog.js";import{createNavShell as m}from"./nav-shell.js";import{LoadToken as h,loadIntoStack as g}from"./view-loader.js";import{LoadingStack as _}from"./loading-stack.js";import{registerToastOverlay as v,showToast as y}from"./toast.js";import{SYSTEM_LOCALE_DIR as b,resolveLocaleDir as x}from"./locale-dir.js";import{initLocale as S}from"./locale.js";import{findNavItem as C,resolveInitialNavIndex as w}from"./nav-model.js";export{o as AdwaitaApp,e as BUNDLED_ICON_COUNT,t as BUNDLED_ICON_RESOURCE_PATH,n as BUNDLED_ICON_THEME_NAME,h as LoadToken,_ as LoadingStack,b as SYSTEM_LOCALE_DIR,r as addBundledIconsToTheme,u as confirmDialog,m as createNavShell,d as errorDialog,C as findNavItem,S as initLocale,i as installBundledIconTheme,g as loadIntoStack,f as pickFile,l as readAppDevHooks,a as registerBundledIconResource,v as registerToastOverlay,w as resolveInitialNavIndex,x as resolveLocaleDir,s as runAdwaitaApp,c as runApplication,p as saveFile,y as showToast};
+import{appdataLocale as e,parseAppdata as t}from"./appdata.js";import{applyAppdataFields as n,buildAboutDialogFromAppdata as r,createAboutDialog as i,hasAppdataConstructor as a,licenseTypeFor as o}from"./about-dialog.js";import{BUNDLED_ICON_COUNT as s,BUNDLED_ICON_RESOURCE_PATH as c}from"./icons.generated.js";import{BUNDLED_ICON_THEME_NAME as l,addBundledIconsToTheme as u,installBundledIconTheme as d,registerBundledIconResource as f}from"./icon-theme.js";import{AdwaitaApp as p,runAdwaitaApp as m,runApplication as h}from"./application.js";import{readAppDevHooks as g}from"./dev-hooks.js";import{confirmDialog as _,errorDialog as v}from"./dialogs.js";import{pickFile as y,saveFile as b}from"./file-dialog.js";import{createNavShell as x}from"./nav-shell.js";import{LoadToken as S,loadIntoStack as C}from"./view-loader.js";import{LoadingStack as w}from"./loading-stack.js";import{registerToastOverlay as T,showToast as E}from"./toast.js";import{SYSTEM_LOCALE_DIR as D,resolveLocaleDir as O,systemLocaleDir as k}from"./locale-dir.js";import{initLocale as A}from"./locale.js";import{APPLE_ACCENT_COLOR_ARGV as j,MACOS_ACCENT_POLL_SECONDS as M,onMacosAccentColorChanged as N,readMacosAccentColor as P}from"./system-accent.js";import{findNavItem as F,resolveInitialNavIndex as I}from"./nav-model.js";export{j as APPLE_ACCENT_COLOR_ARGV,p as AdwaitaApp,s as BUNDLED_ICON_COUNT,c as BUNDLED_ICON_RESOURCE_PATH,l as BUNDLED_ICON_THEME_NAME,S as LoadToken,w as LoadingStack,M as MACOS_ACCENT_POLL_SECONDS,D as SYSTEM_LOCALE_DIR,u as addBundledIconsToTheme,e as appdataLocale,n as applyAppdataFields,r as buildAboutDialogFromAppdata,_ as confirmDialog,i as createAboutDialog,x as createNavShell,v as errorDialog,F as findNavItem,a as hasAppdataConstructor,A as initLocale,d as installBundledIconTheme,o as licenseTypeFor,C as loadIntoStack,N as onMacosAccentColorChanged,t as parseAppdata,y as pickFile,g as readAppDevHooks,P as readMacosAccentColor,f as registerBundledIconResource,T as registerToastOverlay,I as resolveInitialNavIndex,O as resolveLocaleDir,m as runAdwaitaApp,h as runApplication,b as saveFile,E as showToast,k as systemLocaleDir};

package/lib/esm/loading-stack.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import e from"gi://Adw?version=1";import t from"gi://GObject?version=2.0";import n from"gi://Gtk?version=4.0";var r=class LoadingStack extends n.Stack{static{t.registerClass({GTypeName:`GjsifyLoadingStack`},LoadingStack)}constructor(t={}){super(t);let r=new n.Box({orientation:n.Orientation.VERTICAL,halign:n.Align.CENTER,valign:n.Align.CENTER,hexpand:!0,vexpand:!0});r.append(new e.Spinner),this.add_named(r,`loading`),this._content=new e.Bin({hexpand:!0,vexpand:!0}),this.add_named(this._content,`content`),this._error=new e.StatusPage({iconName:`dialog-error-symbolic`,title:`Something went wrong`}),this.add_named(this._error,`error`),this.set_visible_child_name(`loading`)}setContent(e){this._content.set_child(e)}setError(e,t){this._error.set_title(e),this._error.set_description(t??``)}showLoading(){this.set_visible_child_name(`loading`)}showContent(){this.set_visible_child_name(`content`)}showError(){this.set_visible_child_name(`error`)}};t.type_ensure(r.$gtype);export{r as LoadingStack};
+import"./_virtual/_rolldown/runtime.js";import e from"gi://Adw?version=1";import t from"gi://Gtk?version=4.0";import n from"gi://GObject?version=2.0";var r=class LoadingStack extends t.Stack{static{n.registerClass({GTypeName:`GjsifyLoadingStack`},LoadingStack)}constructor(n={}){super(n);let r=new t.Box({orientation:t.Orientation.VERTICAL,halign:t.Align.CENTER,valign:t.Align.CENTER,hexpand:!0,vexpand:!0});r.append(new e.Spinner),this.add_named(r,`loading`),this._content=new e.Bin({hexpand:!0,vexpand:!0}),this.add_named(this._content,`content`),this._error=new e.StatusPage({iconName:`dialog-error-symbolic`,title:`Something went wrong`}),this.add_named(this._error,`error`),this.set_visible_child_name(`loading`)}setContent(e){this._content.set_child(e)}setError(e,t){this._error.set_title(e),this._error.set_description(t??``)}showLoading(){this.set_visible_child_name(`loading`)}showContent(){this.set_visible_child_name(`content`)}showError(){this.set_visible_child_name(`error`)}};n.type_ensure(r.$gtype);export{r as LoadingStack};

package/lib/esm/locale-dir.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";const e=`/usr/share/locale`;function resolveLocaleDir(e={}){return nonEmpty(e.localeDir)??nonEmpty(e.env?.GJSIFY_LOCALE_DIR)??nonEmpty(e.fallbackDir)??`/usr/share/locale`}function nonEmpty(e){if(e===void 0)return;let t=e.trim();return t===``?void 0:t}export{e as SYSTEM_LOCALE_DIR,resolveLocaleDir};
+import"./_virtual/_rolldown/runtime.js";const e=`/usr/share/locale`,t=[`darwin`,`win32`];function systemLocaleDir(n){return n!==void 0&&t.includes(n)?void 0:e}function resolveLocaleDir(e={}){return nonEmpty(e.localeDir)??nonEmpty(e.env?.GJSIFY_LOCALE_DIR)??nonEmpty(e.fallbackDir)??systemLocaleDir(e.platform)}function nonEmpty(e){if(e===void 0)return;let t=e.trim();return t===``?void 0:t}export{e as SYSTEM_LOCALE_DIR,resolveLocaleDir,systemLocaleDir};

package/lib/esm/locale.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{resolveLocaleDir as e}from"./locale-dir.js";import t from"gi://GLib?version=2.0";import n from"gettext";function initLocale(r,i={}){let a=e({...i,env:{GJSIFY_LOCALE_DIR:t.getenv(`GJSIFY_LOCALE_DIR`)??void 0}});return n.setlocale(n.LocaleCategory.ALL,``),n.bindtextdomain(r,a),n.textdomain(r),Object.assign(e=>n.dgettext(r,e),{plural:(e,t,i)=>n.dngettext(r,e,t,i),context:(e,t)=>n.dpgettext(r,e,t),localeDir:a,domain:r})}export{initLocale};
+import"./_virtual/_rolldown/runtime.js";import{resolveLocaleDir as e}from"./locale-dir.js";import t from"gi://GLib?version=2.0";import n from"gettext";function initLocale(r,i={}){let a=e({...i,env:{GJSIFY_LOCALE_DIR:t.getenv(`GJSIFY_LOCALE_DIR`)??void 0},platform:typeof process>`u`?void 0:process.platform});return n.setlocale(n.LocaleCategory.ALL,``),a!==void 0&&n.bindtextdomain(r,a),n.textdomain(r),Object.assign(e=>n.dgettext(r,e),{plural:(e,t,i)=>n.dngettext(r,e,t,i),context:(e,t)=>n.dpgettext(r,e,t),localeDir:a,domain:r})}export{initLocale};

package/lib/esm/nav-shell.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import e from"gi://Adw?version=1";import t from"gi://Gtk?version=4.0";function buildNavRow(e){let n=new t.ListBoxRow,r=new t.Box({orientation:t.Orientation.HORIZONTAL,spacing:12,marginTop:8,marginBottom:8,marginStart:12,marginEnd:12});e.icon&&r.append(new t.Image({iconName:e.icon}));let i=new t.Box({orientation:t.Orientation.VERTICAL,hexpand:!0});return i.append(new t.Label({label:e.label,xalign:0})),e.subtitle&&i.append(new t.Label({label:e.subtitle,xalign:0,cssClasses:[`dim-label`,`caption`]})),r.append(i),n.set_child(r),n}function createNavShell(n,r){let i=new e.NavigationSplitView,a=new t.Stack({transitionType:t.StackTransitionType.CROSSFADE,hexpand:!0,vexpand:!0}),o=new t.ListBox({cssClasses:[`navigation-sidebar`]}),s=new e.HeaderBar,c=new e.HeaderBar;r.sidebarTitle&&c.set_title_widget(new e.WindowTitle({title:r.sidebarTitle,subtitle:``})),r.sidebarHeaderStart&&c.pack_start(r.sidebarHeaderStart),r.sidebarHeaderEnd&&c.pack_end(r.sidebarHeaderEnd);let l=new e.ToolbarView;l.add_top_bar(c),l.set_content(o),i.set_sidebar(new e.NavigationPage({title:r.sidebarTitle??`Menu`,child:l}));let u=new e.ToolbarView;u.add_top_bar(s),u.set_content(a),i.set_content(new e.NavigationPage({title:r.sidebarTitle??``,child:u}));for(let e of r.items)o.append(buildNavRow(e));o.connect(`row-selected`,(e,t)=>{if(!t)return;let n=t.get_index(),a=r.items[n];a&&(r.onSelect(a,n),i.get_collapsed()&&i.set_show_content(!0))});let d=r.collapseWidth??720,f=e.BreakpointCondition.parse(`max-width: ${d}px`);if(f){let t=new e.Breakpoint({condition:f});t.add_setter(i,`collapsed`,!0),n.add_breakpoint(t)}let selectByIndex=e=>{let t=o.get_row_at_index(e);t&&o.select_row(t)};return{widget:i,stack:a,contentHeader:s,selectByIndex,selectById(e){let t=r.items.findIndex(t=>t.id===e);selectByIndex(t>=0?t:0)}}}export{createNavShell};
+import"./_virtual/_rolldown/runtime.js";import e from"gi://Adw?version=1";import t from"gi://Gtk?version=4.0";function buildNavRow(e){let n=new t.ListBoxRow,r=new t.Box({orientation:t.Orientation.HORIZONTAL,spacing:12,marginTop:8,marginBottom:8,marginStart:12,marginEnd:12});e.icon&&r.append(new t.Image({iconName:e.icon}));let i=new t.Box({orientation:t.Orientation.VERTICAL,hexpand:!0});return i.append(new t.Label({label:e.label,xalign:0})),e.subtitle&&i.append(new t.Label({label:e.subtitle,xalign:0,cssClasses:[`dim-label`,`caption`]})),r.append(i),n.set_child(r),n}function createNavShell(n,r){let i=new e.NavigationSplitView,a=new t.Stack({transitionType:t.StackTransitionType.CROSSFADE,hexpand:!0,vexpand:!0}),o=new t.ListBox({cssClasses:[`navigation-sidebar`]}),s=new e.HeaderBar,c=new WeakMap,l=[],u=[],d=null,f=!1,p=new e.HeaderBar;r.sidebarTitle&&p.set_title_widget(new e.WindowTitle({title:r.sidebarTitle,subtitle:``})),r.sidebarHeaderStart&&p.pack_start(r.sidebarHeaderStart),r.sidebarHeaderEnd&&p.pack_end(r.sidebarHeaderEnd);let m=new e.ToolbarView;m.add_top_bar(p),r.sidebarBottomBar&&m.add_bottom_bar(r.sidebarBottomBar),m.set_content(o),i.set_sidebar(new e.NavigationPage({title:r.sidebarTitle??`Menu`,child:m}));let h=new e.ToolbarView;if(h.add_top_bar(s),r.contentBottomBar&&h.add_bottom_bar(r.contentBottomBar),h.set_content(a),i.set_content(new e.NavigationPage({title:r.sidebarTitle??``,child:h})),o.connect(`row-selected`,(e,t)=>{if(!t){f||(d=null);return}let n=c.get(t);if(!n)return;let a=t.get_index();a<0||(d=n.id,!f&&(r.onSelect(n,a),i.get_collapsed()&&i.set_show_content(!0)))}),r.headerFunc){let e=r.headerFunc;o.set_header_func((t,n)=>e(t,n?c.get(n)??null:null))}let setItems=e=>{let t=d;l=e,f=!0;for(let e of u)o.remove(e);u=l.map(e=>{let t=buildNavRow(e);return c.set(t,e),o.append(t),t});let n=t===null?-1:l.findIndex(e=>e.id===t);n>=0&&o.select_row(u[n]),f=!1};setItems(r.items);let g=r.collapseWidth??720,_=e.BreakpointCondition.parse(`max-width: ${g}px`);if(_){let t=new e.Breakpoint({condition:_});t.add_setter(i,`collapsed`,!0),n.add_breakpoint(t)}let selectByIndex=e=>{let t=o.get_row_at_index(e);t&&o.select_row(t)};return{widget:i,stack:a,contentHeader:s,setItems,selectByIndex,selectById(e){let t=l.findIndex(t=>t.id===e);selectByIndex(t>=0?t:0)}}}export{createNavShell};

package/lib/esm/system-accent.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"gi://Gio?version=2.0";import t from"gi://GLib?version=2.0";import{adwAccentFromAppleAccentColor as n}from"@gjsify/adwaita-core";const r=[`defaults`,`read`,`-g`,`AppleAccentColor`],i=5,a=/Could not find key|does not exist/;function readMacosAccentColor(t={}){let i=[...t.argv??r],o;try{let t=e.Subprocess.new(i,e.SubprocessFlags.STDOUT_PIPE|e.SubprocessFlags.STDERR_PIPE),[,n,r]=t.communicate_utf8(null,null);o={ok:t.get_successful(),stdout:n??``,stderr:r??``}}catch{return null}return o.ok?n(o.stdout):a.test(o.stderr)?n(null):null}function onMacosAccentColorChanged(e,n={}){let r=n.read??(()=>readMacosAccentColor()),i=r(),a=t.timeout_add_seconds(t.PRIORITY_LOW,n.intervalSeconds??5,()=>{let n=r();return n!==i&&(i=n,e(n)),t.SOURCE_CONTINUE});return()=>{a!==null&&(t.source_remove(a),a=null)}}export{r as APPLE_ACCENT_COLOR_ARGV,i as MACOS_ACCENT_POLL_SECONDS,onMacosAccentColorChanged,readMacosAccentColor};

package/lib/types/about-dialog.d.ts

@@ -0,0 +1,127 @@
+import Adw from 'gi://Adw?version=1';
+import Gtk from 'gi://Gtk?version=4.0';
+import { type AppdataFields } from './appdata.js';
+/**
+ * The `Gtk.License` an SPDX id names, or `Gtk.License.CUSTOM` for one GTK does not know.
+ *
+ * CUSTOM is returned WITHOUT also setting a licence text, which is what upstream does. Putting
+ * the raw SPDX id in `Adw.AboutDialog:license` instead would be more informative and would
+ * therefore show a licence line on Windows that Linux does not show — the divergence this
+ * whole module exists to prevent.
+ */
+export declare function licenseTypeFor(spdxId: string): Gtk.License;
+/**
+ * Whether this GTK runtime has `Adw.AboutDialog.new_from_appdata()`.
+ *
+ * Asked as a QUESTION rather than discovered by calling and catching, for two reasons. A
+ * `try` around the call would also swallow a genuine failure — a metainfo file the parser
+ * rejects would silently become "the constructor is missing" and the app would ship a
+ * quietly degraded dialog forever. And it would not work anyway: libadwaita reports an
+ * unreadable or unparseable resource with `g_error()`, which ABORTS the process, and no
+ * catch runs after that.
+ *
+ * The `try` that IS here wraps the LOOKUP, because the absence has two shapes and only one
+ * of them is a plain `undefined`: node-gi reports an entry point missing from the typelib by
+ * throwing `no static method 'new_from_appdata'` at property access, which is exactly how the
+ * Windows 11 measurement in #1662 reads.
+ *
+ * `namespace` defaults to the real `Adw` and is a parameter so both shapes can be held
+ * against the real question on a platform that has neither. It substitutes a namespace and
+ * never means "no namespace": passing `undefined` is the default parameter and therefore asks
+ * about `Adw`.
+ */
+export declare function hasAppdataConstructor(namespace?: unknown): boolean;
+/** Where {@link createAboutDialog} may read the metainfo document from. */
+export interface AppdataSource {
+    /**
+     * GResource path of the metainfo file, e.g.
+     * `/org/example/App/metainfo/org.example.App.metainfo.xml`.
+     *
+     * This is the only form the upstream constructor accepts, so an app that registers its
+     * metainfo as a resource takes the upstream path wherever it exists.
+     */
+    appdataResource?: string;
+    /**
+     * Filesystem path of the metainfo file, consulted when no resource answers.
+     *
+     * Upstream has no equivalent — and that is the point. A `gjsify ship` artifact may carry
+     * the metainfo beside the bundle rather than inside a GResource (a `.app` is dragged
+     * wherever the user likes, a Windows program directory is unzipped to an arbitrary path),
+     * and such an app would otherwise have no About dialog on ANY platform. Where the
+     * directory is remains the caller's question: this module takes a path, exactly as
+     * `locale-dir.ts` takes a directory rather than going looking for one.
+     */
+    appdataPath?: string;
+}
+/** Options for {@link createAboutDialog}. */
+export interface CreateAboutDialogOptions extends AppdataSource {
+    /**
+     * Show the release notes of this exact version, matched by string equality — the second
+     * argument of `Adw.AboutDialog.new_from_appdata()`, with the same semantics.
+     */
+    releaseNotesVersion?: string;
+    /**
+     * Version shown in the dialog, overriding the metainfo's newest release.
+     *
+     * Worth passing. The metainfo answers this question only as well as it is maintained,
+     * and it is the one field where this module's reading and ministream's can disagree —
+     * ministream sorts releases by a dpkg-style version comparison, `appdata.ts` takes the
+     * first one written. An explicit version removes the question on every platform at once.
+     */
+    version?: string;
+    /** Icon name, overriding the one derived from `<id>`. */
+    applicationIcon?: string;
+    /**
+     * Build the dialog from parsed AppStream even where the upstream constructor exists.
+     *
+     * Not a test hook — or not only one. The parsed path is what every Windows user sees and
+     * what NO Linux or macOS run would otherwise execute, so a developer who wants to check
+     * their About dialog before shipping has no other way to look at it. The suite beside
+     * this file uses it for the same reason.
+     */
+    forceParsedAppdata?: boolean;
+}
+/**
+ * Set on `dialog` exactly what `populate_from_appdata` sets, and nothing else.
+ *
+ * The upstream list, read off `adw-about-dialog.c` rather than guessed: application icon
+ * (from `<id>`), application name, developer name, version, website, support url, issue url,
+ * licence TYPE, and the release notes of one named release. It sets no `comments`, no
+ * `copyright`, no `translator-credits` and no `developers` — AppStream's `<summary>` is not
+ * `Adw.AboutDialog:comments` and upstream never treats it as one — so neither does this.
+ * An app that wants those sets them on the returned dialog itself.
+ */
+export declare function applyAppdataFields(dialog: Adw.AboutDialog, fields: AppdataFields, releaseNotesVersion?: string): Adw.AboutDialog;
+/**
+ * Build the dialog from a metainfo document, without consulting libadwaita's constructor.
+ *
+ * This is the Windows path, exported so it is callable on a platform that has the constructor:
+ * a fallback only one OS can reach is a fallback no suite covers, and the class of defect that
+ * hides there is a restructured metainfo file that empties the About dialog on Windows while
+ * every Linux run stays green.
+ */
+export declare function buildAboutDialogFromAppdata(xml: string, options?: {
+    releaseNotesVersion?: string;
+    locale?: string;
+}): Adw.AboutDialog;
+/**
+ * Create an `Adw.AboutDialog` from the application's AppStream metainfo.
+ *
+ * A drop-in for `Adw.AboutDialog.new_from_appdata(resource, version)` that works on Windows:
+ *
+ * ```ts
+ * const dialog = createAboutDialog({
+ *     appdataResource: '/org/example/App/metainfo/org.example.App.metainfo.xml',
+ *     releaseNotesVersion: PACKAGE_VERSION,
+ *     version: PACKAGE_VERSION,
+ * });
+ * dialog.present(window);
+ * ```
+ *
+ * THE RESOURCE IS CHECKED BEFORE THE CONSTRUCTOR IS CALLED, and that is not a tidiness step.
+ * `populate_from_appdata` reports a resource it cannot read with `g_error()`, which aborts the
+ * process — a typo in a resource path would kill the application when the user opens About,
+ * with no exception for anyone to catch. Asking `Gio.resources_get_info` first turns that into
+ * a dialog assembled from whatever source did answer.
+ */
+export declare function createAboutDialog(options?: CreateAboutDialogOptions): Adw.AboutDialog;

package/lib/types/about-dialog.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/appdata-xml.d.ts

@@ -0,0 +1,38 @@
+/** An opening (or self-closing) element. */
+export interface XmlOpenTag {
+    kind: 'open';
+    /** Element name exactly as written, prefix included (`xml:lang` is an attribute, not this). */
+    name: string;
+    /** Attribute values with entities already decoded. */
+    attributes: Record<string, string>;
+    /** `true` for `<foo/>`, which emits no matching {@link XmlCloseTag}. */
+    selfClosing: boolean;
+}
+/** A closing element. */
+export interface XmlCloseTag {
+    kind: 'close';
+    name: string;
+}
+/** Character data between elements, with entities already decoded. */
+export interface XmlText {
+    kind: 'text';
+    text: string;
+}
+export type XmlToken = XmlOpenTag | XmlCloseTag | XmlText;
+/**
+ * Resolve the entity references a metainfo file may contain.
+ *
+ * An UNKNOWN reference is returned verbatim rather than dropped. A metainfo file is
+ * hand-written and `&` is the character most often left unescaped in one; turning
+ * `Tom & Jerry` into `Tom ` would silently truncate a developer name, which is exactly
+ * the kind of Windows-only difference this module exists to prevent.
+ */
+export declare function decodeXmlEntities(text: string): string;
+/**
+ * Tokenise an XML document.
+ *
+ * Returns an array rather than a generator on purpose: a metainfo file is a few kilobytes,
+ * three bundler targets (`gjs`, `node`, library) have to agree on the output, and an array
+ * is the form that needs no iteration-protocol support from any of them.
+ */
+export declare function scanXml(xml: string): XmlToken[];

package/lib/types/appdata-xml.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/appdata.d.ts

@@ -0,0 +1,78 @@
+/** Fields {@link parseAppdata} reads. `null` means the document does not carry the field. */
+export interface AppdataFields {
+    /** `<id>`, with the `.desktop` suffix resolved the way libadwaita resolves it. */
+    applicationId: string | null;
+    /** `<name>`, resolved against the locale. */
+    applicationName: string | null;
+    /** `<name>` inside `<developer>`, or the legacy `<developer_name>`. */
+    developerName: string | null;
+    /** `version` of the first `<release>` — see {@link parseAppdata} on ordering. */
+    version: string | null;
+    /** `<url type="homepage">`. */
+    website: string | null;
+    /** `<url type="help">`. */
+    supportUrl: string | null;
+    /** `<url type="bugtracker">`. */
+    issueUrl: string | null;
+    /** `<project_license>`, an SPDX id. */
+    license: string | null;
+    /**
+     * The `<description>` of the release named by `releaseNotesVersion`, as the Pango-ish
+     * markup `Adw.AboutDialog:release-notes` parses. `null` when no version was asked for,
+     * or when no release matches it.
+     */
+    releaseNotes: string | null;
+}
+/** Options for {@link parseAppdata}. */
+export interface ParseAppdataOptions {
+    /**
+     * BCP-47 locale that translatable elements are resolved against. Default `C`, the
+     * untranslated source string. {@link appdataLocale} derives it from the platform.
+     */
+    locale?: string;
+    /**
+     * Which release's notes to extract, matched by EXACT string equality — the same
+     * `g_strcmp0` libadwaita uses, so no version-comparison semantics are implied and
+     * `1.0` never matches `1.0.0`.
+     */
+    releaseNotesVersion?: string;
+}
+/**
+ * How well `lang` answers for `locale`, as a count of matching BCP-47 segments; `0` is no
+ * match at all.
+ *
+ * Ported from `ms_locale_score`, including the property that is easy to get wrong: a
+ * mismatch INSIDE a segment scores 0 rather than crediting the segments before it, so
+ * `de-DE` against `de-AT` is 0 and against `de` is 1. Anything looser would let a Swiss
+ * German string win over the untranslated one for an Austrian user.
+ */
+export declare function localeScore(locale: string, lang: string): number;
+/**
+ * The BCP-47 locale AppStream matching uses, from `GLib.get_language_names()` and the
+ * environment.
+ *
+ * Ported from `ms_get_current_locale`, quirks included: the most specific name wins, `LANG`
+ * is consulted when that name carries no region (GLib answers `de` for `LANG=de_DE` in some
+ * configurations, and a `de-DE` translation must still win there), `.UTF-8` is dropped
+ * because AppStream assumes it, and an `@variant` becomes a BCP-47 script subtag.
+ */
+export declare function appdataLocale(languageNames: readonly string[], env?: {
+    LANG?: string;
+}): string;
+/**
+ * Read an AppStream metainfo document.
+ *
+ * Mirrors `adw_about_dialog_new_from_appdata()`'s `populate_from_appdata`, whose whole field
+ * list is: application icon (from `<id>`), application name, developer name, version,
+ * website, support url, issue url, licence type, and the release notes of ONE named release.
+ * It sets nothing else — no `comments`, no `copyright`, no `translator-credits`, no
+ * `developers` — so neither does this.
+ *
+ * RELEASE ORDER IS THE ONE DIVERGENCE. ministream sorts `<releases>` by a dpkg-style version
+ * comparison and reports the highest; this takes the first `<release>` in document order and
+ * does not re-implement that comparison. AppStream requires releases to be written
+ * newest-first (`appstreamcli validate` reports `releases-not-in-order` otherwise), so the
+ * two agree on every valid document — and a caller that will not rely on that passes its own
+ * version to `createAboutDialog`, which overrides this on every platform alike.
+ */
+export declare function parseAppdata(xml: string, options?: ParseAppdataOptions): AppdataFields;

package/lib/types/appdata.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/appearance/darwin.d.ts

@@ -0,0 +1,5 @@
+import type { DesktopAppearance } from '@gjsify/adwaita-core';
+/** Quiet time after the last file event before re-reading — cfprefsd writes in bursts. */
+export declare const DARWIN_DEBOUNCE_MS = 750;
+export declare function readDarwinAppearance(): Promise<DesktopAppearance>;
+export declare function watchDarwinAppearance(changed: () => void): () => void;

package/lib/types/appearance/gnome-settings.d.ts

@@ -0,0 +1,23 @@
+import type { DesktopAppearance } from '@gjsify/adwaita-core';
+export declare const GNOME_INTERFACE_SCHEMA = "org.gnome.desktop.interface";
+/** The slice of `Gio.Settings` this reader touches, so a test can hand in a fake. */
+export interface GnomeSettingsLike {
+    get_string(key: string): string;
+    connect(signal: string, callback: () => void): number;
+    disconnect(id: number): void;
+}
+/** A GSettings source and which of the two keys its installed schema actually has. */
+export interface GnomeSettingsSource {
+    readonly settings: GnomeSettingsLike;
+    readonly keys: readonly ('accent-color' | 'color-scheme')[];
+}
+/**
+ * The installed schema, or `null`. Looked up in the schema source FIRST because
+ * `new Gio.Settings` on a missing schema aborts the whole process instead of
+ * throwing, and a missing KEY aborts `get_string` the same way — so each key is
+ * checked too (`accent-color` exists only since GNOME 47).
+ */
+export declare function gnomeSettingsSource(): GnomeSettingsSource | null;
+export declare function readGnomeSettings(source: GnomeSettingsSource): DesktopAppearance;
+/** Call `changed` on a change to either key. Returns the unsubscribe. */
+export declare function watchGnomeSettings(source: GnomeSettingsSource, changed: () => void): () => void;

package/lib/types/appearance/index.d.ts

@@ -0,0 +1,9 @@
+export { readDesktopAppearance, watchDesktopAppearance } from './reader.js';
+export type { DesktopAppearanceOptions } from './reader.js';
+export { appearanceFromGnomeSettings, appearanceFromMacDefaults, appearanceFromPortal, appearanceFromWindowsRegistry, isGnomeDesktop, MACOS_ACCENT_COLORS, mergeAppearance, parseRegQuery, sameAppearance, } from './mapping.js';
+export type { MacDefaultsValues, WindowsRegistryValues } from './mapping.js';
+export { readPortalAppearance, watchPortalAppearance } from './portal.js';
+export type { PortalEndpoint } from './portal.js';
+export type { GnomeSettingsLike, GnomeSettingsSource } from './gnome-settings.js';
+export { parseDesktopAppearance, renderAppearanceMeta } from '@gjsify/adwaita-core';
+export type { AdwSystemColorScheme, DesktopAppearance } from '@gjsify/adwaita-core';

package/lib/types/appearance/mapping.d.ts

@@ -0,0 +1,102 @@
+import { type DesktopAppearance } from '@gjsify/adwaita-core';
+/** Field by field: `primary` wins, `fallback` fills what it left unknown. */
+export declare function mergeAppearance(primary: DesktopAppearance, fallback: DesktopAppearance): DesktopAppearance;
+/** Whether two appearances say the same thing — what a watcher dedupes on. */
+export declare function sameAppearance(a: DesktopAppearance, b: DesktopAppearance): boolean;
+/**
+ * The XDG Settings portal's `org.freedesktop.appearance` namespace, as
+ * `ReadAll` returns it unpacked.
+ *
+ * - `color-scheme` (`u`): 0 no preference, 1 prefer dark, 2 prefer light. Any
+ *   other number is invalid and dropped (libadwaita warns and uses the default).
+ * - `accent-color` (`(ddd)`): sRGB in 0…1. The spec says a value outside that
+ *   range means "not set" — xdg-desktop-portal-gnome sends `(-1,-1,-1)` for a
+ *   desktop with no accent — so it is dropped, not clamped.
+ *
+ * Reference: xdg-desktop-portal `org.freedesktop.impl.portal.Settings` docs
+ * Reference: refs/libadwaita/src/adw-settings-impl-portal.c#get_fdo_accent_color
+ */
+export declare function appearanceFromPortal(namespace: Readonly<Record<string, unknown>>): DesktopAppearance;
+/**
+ * Whether GSettings `org.gnome.desktop.interface` describes THIS desktop, from
+ * `XDG_CURRENT_DESKTOP` (a colon-separated list such as `ubuntu:GNOME`).
+ *
+ * The schema is installed far beyond GNOME: KDE and Xfce ship
+ * gsettings-desktop-schemas, and so does Homebrew on macOS. There nobody writes
+ * the keys, so `get_string` answers the schema DEFAULT, and a reader that took it
+ * would report `blue` for a desktop set to purple (measured on macOS with
+ * `AppleAccentColor = 5`, JumpLink/beifahrer#19). Outside GNOME the answer is
+ * therefore "unknown", never the default.
+ */
+export declare function isGnomeDesktop(currentDesktop: string | null | undefined): boolean;
+/**
+ * GSettings `org.gnome.desktop.interface` — the fallback where no portal
+ * answers. `accent-color` (GNOME 47+) is already one of the nine NAMES, so no
+ * snapping and no colour; `color-scheme` (GNOME 42+) is `default`,
+ * `prefer-dark` or `prefer-light`.
+ */
+export declare function appearanceFromGnomeSettings(values: {
+    readonly accentColor?: string | null;
+    readonly colorScheme?: string | null;
+}): DesktopAppearance;
+/** The raw registry values the Windows reader fetches; `null` where the value does not exist. */
+export interface WindowsRegistryValues {
+    /** `HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Accent` `AccentPalette` (REG_BINARY, 32 bytes). */
+    readonly accentPalette?: Uint8Array | null;
+    /** `HKCU\Software\Microsoft\Windows\DWM` `AccentColor` (REG_DWORD, `0xAABBGGRR`). */
+    readonly dwmAccentColor?: number | null;
+    /** `HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize` `AppsUseLightTheme` (REG_DWORD). */
+    readonly appsUseLightTheme?: number | null;
+}
+/**
+ * Windows. The accent libadwaita reads is WinRT's `UIColorType_Accent`
+ * (`adw-settings-impl-win32.c`), which Explorer persists as entry 3 of the
+ * eight RGBA quads in `AccentPalette` (light 3/2/1, ACCENT, dark 1/2/3,
+ * unused). Where that value is missing, DWM's `AccentColor` — the title-bar
+ * accent, stored `0xAABBGGRR` — is the closest the registry offers.
+ *
+ * `AppsUseLightTheme` is the "choose your app mode" switch: 0 dark, 1 light.
+ * Absent (Windows before 10 1809) leaves the scheme unknown.
+ *
+ * NOT MEASURED ON WINDOWS: the palette layout is Microsoft's undocumented
+ * persistence format, taken from its long-standing public descriptions; the
+ * registry paths match JumpLink/beifahrer#18.
+ */
+export declare function appearanceFromWindowsRegistry(values: WindowsRegistryValues): DesktopAppearance;
+/**
+ * The colour each `AppleAccentColor` index stands for. macOS stores an INDEX,
+ * not a colour, so these are the `NSColor.controlAccentColor` values libadwaita's
+ * own test uses for its macOS cases (`tests/test-accent-color.c`) — the same
+ * colours `adw-settings-impl-macos.c` snaps at runtime. An ABSENT key is
+ * "multicolour", whose accent is blue (Firefox 156 on macOS 27 reports CSS
+ * `AccentColor` as `rgb(0, 122, 255)` there, which snaps to blue as well).
+ */
+export declare const MACOS_ACCENT_COLORS: Readonly<Record<string, string>>;
+/** The raw `defaults read -g <key>` answers; `null` where the key does not exist. */
+export interface MacDefaultsValues {
+    readonly appleAccentColor?: string | null;
+    readonly appleInterfaceStyle?: string | null;
+    readonly appleInterfaceStyleSwitchesAutomatically?: string | null;
+}
+/**
+ * macOS global defaults. Measured on macOS 27 (JumpLink/beifahrer#18): with
+ * default settings all three keys are ABSENT, and absence is itself a value —
+ * multicolour accent, light appearance.
+ *
+ * One exception makes absence ambiguous: with "Auto" appearance
+ * (`AppleInterfaceStyleSwitchesAutomatically = 1`) the system flips between
+ * light and dark by time of day, and a missing `AppleInterfaceStyle` no longer
+ * proves light. The scheme is then left UNKNOWN, so a page falls back to
+ * `prefers-color-scheme`, which the browser tracks live.
+ */
+export declare function appearanceFromMacDefaults(values: MacDefaultsValues): DesktopAppearance;
+/**
+ * Parse one value out of `reg.exe query <key> /v <name>` output:
+ *
+ *     HKEY_CURRENT_USER\Software\Microsoft\Windows\DWM
+ *         AccentColor    REG_DWORD    0xffd47800
+ *
+ * Returns a number for `REG_DWORD`, bytes for `REG_BINARY`, `null` when the
+ * value is not in the output (reg.exe then exits 1 with an error instead).
+ */
+export declare function parseRegQuery(stdout: string, name: string): number | Uint8Array | null;

package/lib/types/appearance/mapping.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/appearance/portal.d.ts

@@ -0,0 +1,25 @@
+import Gio from 'gi://Gio?version=2.0';
+import type { DesktopAppearance } from '@gjsify/adwaita-core';
+export declare const PORTAL_BUS_NAME = "org.freedesktop.portal.Desktop";
+export declare const PORTAL_OBJECT_PATH = "/org/freedesktop/portal/desktop";
+export declare const PORTAL_SETTINGS_INTERFACE = "org.freedesktop.portal.Settings";
+export declare const APPEARANCE_NAMESPACE = "org.freedesktop.appearance";
+/** Where to reach the portal. `busName` is `null` on a peer-to-peer connection (the tests). */
+export interface PortalEndpoint {
+    readonly connection: Gio.DBusConnection;
+    readonly busName: string | null;
+}
+/**
+ * The appearance the portal reports, or `null` when no portal answered — the
+ * caller then falls back. A portal that answers with neither key yields `{}`,
+ * which is an answer ("this desktop says nothing"), not a failure.
+ */
+export declare function readPortalAppearance(endpoint: PortalEndpoint): Promise<DesktopAppearance | null>;
+/**
+ * Call `changed` whenever the portal announces a change in the appearance
+ * namespace. Returns the unsubscribe. The caller re-reads rather than applying
+ * the signal's one value, so a burst of changes collapses into one answer.
+ */
+export declare function watchPortalAppearance(endpoint: PortalEndpoint, changed: () => void): () => void;
+/** The session bus, or `null` where there is none (no `DBUS_SESSION_BUS_ADDRESS`, a CI container). */
+export declare function sessionPortalEndpoint(): Promise<PortalEndpoint | null>;

package/lib/types/appearance/reader.d.ts

@@ -0,0 +1,26 @@
+import type { DesktopAppearance } from '@gjsify/adwaita-core';
+import { type GnomeSettingsSource } from './gnome-settings.js';
+import { type PortalEndpoint } from './portal.js';
+/** Overrides for the sources, mainly so a test can point the reader at a fake. */
+export interface DesktopAppearanceOptions {
+    /** `process.platform` by default. Anything other than `win32`/`darwin` takes the portal route. */
+    readonly platform?: string;
+    /** Linux: the portal to ask. Default: `org.freedesktop.portal.Desktop` on the session bus; `null` skips it. */
+    readonly portal?: PortalEndpoint | null;
+    /** Linux: the GSettings fallback. Default: `org.gnome.desktop.interface` if installed; `null` skips it. */
+    readonly gnomeSettings?: GnomeSettingsSource | null;
+    /**
+     * Linux: `XDG_CURRENT_DESKTOP`, read from the environment by default. GSettings is
+     * consulted only when it names GNOME: elsewhere the schema answers its defaults.
+     */
+    readonly currentDesktop?: string | null;
+}
+/** The desktop's accent and colour-scheme preference, as far as this OS can tell. Never rejects. */
+export declare function readDesktopAppearance(options?: DesktopAppearanceOptions): Promise<DesktopAppearance>;
+/**
+ * Call `callback` with the current appearance, then again whenever it changes
+ * (duplicate reports are dropped). Returns the unsubscribe — HOLD it: the
+ * returned closure is what keeps the bus subscription, the settings object or
+ * the file monitor alive.
+ */
+export declare function watchDesktopAppearance(callback: (appearance: DesktopAppearance) => void, options?: DesktopAppearanceOptions): () => void;

package/lib/types/appearance/reader.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/appearance/run-tool.d.ts

@@ -0,0 +1,6 @@
+/**
+ * stdout of `argv` when it exits 0, `null` otherwise — including when the tool
+ * is missing. Both tools exit non-zero for "no such value", which the readers
+ * treat as absence, so the two cases need no distinction here.
+ */
+export declare function runTool(argv: readonly string[]): Promise<string | null>;

package/lib/types/appearance/win32.d.ts

@@ -0,0 +1,5 @@
+import type { DesktopAppearance } from '@gjsify/adwaita-core';
+/** How often a watcher re-reads. Settings change by hand, so seconds are fast enough. */
+export declare const WIN32_POLL_INTERVAL_S = 3;
+export declare function readWin32Appearance(): Promise<DesktopAppearance>;
+export declare function watchWin32Appearance(changed: () => void): () => void;

package/lib/types/application.d.ts

@@ -2,6 +2,7 @@ import Adw from 'gi://Adw?version=1';
 import Gio from 'gi://Gio?version=2.0';
 import Gtk from 'gi://Gtk?version=4.0';
 import { type InstallDevtoolsOptions } from '@gjsify/devtools';
+import { type CreateAboutDialogOptions } from './about-dialog.js';
 import { type BundledIconThemeOptions } from './icon-theme.js';
 import type { AboutInfo } from './types.js';
 /** Options for {@link AdwaitaApp} / {@link runAdwaitaApp}. */
@@ -31,6 +32,17 @@ export interface AdwaitaAppOptions {
     bundledIcons?: boolean | BundledIconThemeOptions;
     /** When set, wires an `app.about` action opening an `Adw.AboutDialog`. */
     about?: AboutInfo;
+    /**
+     * Build the `app.about` dialog from the application's AppStream metainfo instead of from
+     * literal fields. Wins over {@link AdwaitaAppOptions.about} when both are given.
+     *
+     * Prefer it: the metainfo is already written, already translated and already installed, so
+     * restating its name, developer, licence and urls in `about` is a second copy that drifts
+     * — and the drift is invisible until somebody opens the dialog. See
+     * {@link CreateAboutDialogOptions}; it works where `Adw.AboutDialog.new_from_appdata()`
+     * does not exist.
+     */
+    aboutAppdata?: CreateAboutDialogOptions;
     /** Wire `app.quit` (`<primary>q`). Default `true`. */
     quitAction?: boolean;
     /**

package/lib/types/index.d.ts

@@ -3,10 +3,14 @@ export type { AdwaitaAppOptions } from './application.js';
 export { BUNDLED_ICON_COUNT, BUNDLED_ICON_RESOURCE_PATH, BUNDLED_ICON_THEME_NAME, addBundledIconsToTheme, installBundledIconTheme, registerBundledIconResource, } from './icon-theme.js';
 export type { BundledIconPreference, BundledIconThemeOptions } from './icon-theme.js';
 export { createNavShell } from './nav-shell.js';
-export type { NavShell, NavShellOptions } from './nav-shell.js';
+export type { NavShell, NavShellHeaderFunc, NavShellOptions } from './nav-shell.js';
 export { LoadToken, loadIntoStack } from './view-loader.js';
 export type { LoadIntoStackOptions } from './view-loader.js';
 export { LoadingStack } from './loading-stack.js';
+export { applyAppdataFields, buildAboutDialogFromAppdata, createAboutDialog, hasAppdataConstructor, licenseTypeFor, } from './about-dialog.js';
+export type { AppdataSource, CreateAboutDialogOptions } from './about-dialog.js';
+export { appdataLocale, parseAppdata } from './appdata.js';
+export type { AppdataFields, ParseAppdataOptions } from './appdata.js';
 export { confirmDialog, errorDialog } from './dialogs.js';
 export type { ConfirmOptions } from './dialogs.js';
 export { registerToastOverlay, showToast } from './toast.js';
@@ -14,8 +18,10 @@ export { pickFile, saveFile } from './file-dialog.js';
 export type { FileFilterSpec, PickFileOptions } from './file-dialog.js';
 export { initLocale } from './locale.js';
 export type { InitLocaleOptions, Translator } from './locale.js';
-export { SYSTEM_LOCALE_DIR, resolveLocaleDir } from './locale-dir.js';
+export { SYSTEM_LOCALE_DIR, resolveLocaleDir, systemLocaleDir } from './locale-dir.js';
 export type { ResolveLocaleDirOptions } from './locale-dir.js';
+export { APPLE_ACCENT_COLOR_ARGV, MACOS_ACCENT_POLL_SECONDS, onMacosAccentColorChanged, readMacosAccentColor, } from './system-accent.js';
+export type { OnMacosAccentColorChangedOptions, ReadMacosAccentColorOptions } from './system-accent.js';
 export { readAppDevHooks } from './dev-hooks.js';
 export type { AppDevHooks, ReadAppDevHooksOptions } from './dev-hooks.js';
 export { findNavItem, resolveInitialNavIndex } from './nav-model.js';

package/lib/types/locale-dir.d.ts

@@ -1,5 +1,26 @@
-/** `bindtextdomain`'s directory for a system install, when nothing else names one. */
+/**
+ * `bindtextdomain`'s directory for a system install — **on Linux**, where it exists.
+ *
+ * Deliberately not a cross-platform answer: see {@link systemLocaleDir}.
+ */
 export declare const SYSTEM_LOCALE_DIR = "/usr/share/locale";
+/**
+ * The system catalogue directory for `platform`, or `undefined` where there is none.
+ *
+ * `undefined` for **darwin** and **win32**, and the darwin half is the reason this function
+ * exists rather than a constant. `/usr/share/locale` does not exist on Windows, so naming it
+ * there was merely useless — but it DOES exist on macOS, holding Apple's own locale data and
+ * never an application's catalogues. So the old unconditional fallback bound a real directory
+ * that could not resolve a single msgid: no error, no translation, and `Translator.localeDir`
+ * reporting a plausible path as if the lookup had somewhere to go. A directory that is absent
+ * is the better answer of the two, because it is the true one.
+ *
+ * Any OTHER platform keeps {@link SYSTEM_LOCALE_DIR}. `process.platform` has more values than
+ * the three desktops this project targets — `freebsd`, `openbsd`, `sunos`, … — and it is also
+ * `undefined` in a GJS bundle built with `--globals none`. Answering those with "no directory"
+ * would change behaviour nobody measured; answering them as today changes nothing.
+ */
+export declare function systemLocaleDir(platform?: string): string | undefined;
 export interface ResolveLocaleDirOptions {
     /** Wins over everything — a dev tree (`dist/locale`), or a test fixture. */
     localeDir?: string;
@@ -7,12 +28,19 @@ export interface ResolveLocaleDirOptions {
     env?: Record<string, string | undefined>;
     /** Used when neither the option nor the environment names a directory. */
     fallbackDir?: string;
+    /** `process.platform`, for the last step only. Omitted keeps the Linux answer. */
+    platform?: string;
 }
 /**
- * Resolve the directory to bind a text domain to.
+ * Resolve the directory to bind a text domain to, or `undefined` when there is none to bind.
  *
  * Precedence: explicit option, then `GJSIFY_LOCALE_DIR` (exported by the `gjsify ship` launcher,
  * which is the only party that knows whether the payload became `/usr`, a `--prefix` tree or
- * `/app`), then the caller's fallback, then the system directory.
+ * `/app`), then the caller's fallback, then the platform's system directory — if it has one.
+ *
+ * A shipped app reaches an answer at step two on every OS, so `undefined` means the app carries
+ * no catalogues AND the platform has no system ones. `locale.ts` then skips `bindtextdomain`
+ * rather than binding somewhere arbitrary, and every lookup returns its msgid — which is what an
+ * untranslated application is supposed to do.
  */
-export declare function resolveLocaleDir(options?: ResolveLocaleDirOptions): string;
+export declare function resolveLocaleDir(options?: ResolveLocaleDirOptions): string | undefined;

package/lib/types/locale.d.ts

@@ -7,8 +7,13 @@ export interface Translator {
     plural(singular: string, plural: string, n: number): string;
     /** Disambiguating lookup, for a msgid whose meaning depends on where it appears. */
     context(context: string, msgid: string): string;
-    /** The bound directory and domain — for a diagnostic line, never for a lookup. */
-    readonly localeDir: string;
+    /**
+     * The bound directory and domain — for a diagnostic line, never for a lookup.
+     *
+     * `undefined` when nothing was bound: no catalogues were staged and the platform has no
+     * system directory either (macOS, Windows). Every lookup then returns its msgid.
+     */
+    readonly localeDir: string | undefined;
     readonly domain: string;
 }
 /**

package/lib/types/nav-shell.d.ts

@@ -1,6 +1,14 @@
 import Adw from 'gi://Adw?version=1';
 import Gtk from 'gi://Gtk?version=4.0';
 import type { NavItem } from './types.js';
+/**
+ * Per-row section header, wired straight into `Gtk.ListBox.set_header_func`.
+ *
+ * `before` is the item of the row ABOVE `row`, or `null` for the first row — the
+ * consumer's decision input, since a header is a comparison against the previous
+ * section. Return `null` to draw no header.
+ */
+export type NavShellHeaderFunc = (row: Gtk.ListBoxRow, before: NavItem | null) => Gtk.Widget | null;
 /** Options for {@link createNavShell}. */
 export interface NavShellOptions {
     /** Sidebar rows + stack child ids, in order. */
@@ -15,6 +23,12 @@ export interface NavShellOptions {
     sidebarHeaderEnd?: Gtk.Widget;
     /** Collapse the split view below this width (px). Default `720`. */
     collapseWidth?: number;
+    /** Per-row group header, mapped onto `Gtk.ListBox.set_header_func`. */
+    headerFunc?: NavShellHeaderFunc;
+    /** Widget below the sidebar list (e.g. an account row). */
+    sidebarBottomBar?: Gtk.Widget;
+    /** Widget below the content stack, under the conversation rather than in it. */
+    contentBottomBar?: Gtk.Widget;
 }
 /** The pieces a consumer wires into its window + views. */
 export interface NavShell {
@@ -24,6 +38,18 @@ export interface NavShell {
     stack: Gtk.Stack;
     /** Content header bar — add title widgets / buttons. */
     contentHeader: Adw.HeaderBar;
+    /**
+     * Replace the sidebar rows, in place. The `Gtk.Stack` is left alone: its pages
+     * belong to the consumer (`add_named(view, item.id)`), so a page outliving its
+     * item is theirs to keep or drop.
+     *
+     * The selected id survives if the new items still carry it, and `onSelect` does
+     * NOT fire either way — a rebuild is not a user selection, and re-announcing
+     * the same item would make `onSelect` fire on every list update. An item that
+     * is gone leaves nothing selected; `selectById` is how a consumer picks the
+     * replacement deliberately.
+     */
+    setItems(items: readonly NavItem[]): void;
     /** Select a nav item by its id (falls back to the first item). */
     selectById(id: string): void;
     /** Select a nav item by index. */
@@ -33,6 +59,6 @@ export interface NavShell {
  * Build the nav shell into `window` (which owns the responsive breakpoint).
  * Returns the split view to set as content plus the stack + content header to
  * fill. Row selection drives `onSelect`; a collapsed shell reveals the content
- * pane on selection.
+ * pane on selection. Items may be replaced afterwards — see {@link NavShell.setItems}.
  */
 export declare function createNavShell(window: Adw.ApplicationWindow, options: NavShellOptions): NavShell;

package/lib/types/nav-shell.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/system-accent.d.ts

@@ -0,0 +1,30 @@
+import { type AdwAccentColorName } from '@gjsify/adwaita-core';
+/** The command that prints the accent: `AppleAccentColor` in the global domain. */
+export declare const APPLE_ACCENT_COLOR_ARGV: readonly string[];
+/** How often {@link onMacosAccentColorChanged} re-reads the preference by default. */
+export declare const MACOS_ACCENT_POLL_SECONDS = 5;
+export interface ReadMacosAccentColorOptions {
+    /** The command to run instead of {@link APPLE_ACCENT_COLOR_ARGV}. For tests. */
+    readonly argv?: readonly string[];
+}
+/**
+ * The macOS system accent as one of Adwaita's nine, or `null` where there is
+ * none to follow: not macOS (no `defaults`), or a value macOS does not define.
+ * "Multicolor" gives blue — an Adwaita app's own accent, as libadwaita shows it.
+ *
+ * Synchronous: it waits for one short-lived `defaults` process (~7 ms).
+ */
+export declare function readMacosAccentColor(options?: ReadMacosAccentColorOptions): AdwAccentColorName | null;
+export interface OnMacosAccentColorChangedOptions {
+    /** Seconds between reads. Defaults to {@link MACOS_ACCENT_POLL_SECONDS}. */
+    readonly intervalSeconds?: number;
+    /** The reader. Defaults to {@link readMacosAccentColor}; tests pass their own. */
+    readonly read?: () => AdwAccentColorName | null;
+}
+/**
+ * Call `listener` with the new accent whenever the macOS system accent changes.
+ * Reads once now as the baseline (without calling `listener`), then re-reads
+ * every `intervalSeconds` on the default main context. Returns the unsubscribe,
+ * which the caller must hold and call: the timer lives until then.
+ */
+export declare function onMacosAccentColorChanged(listener: (accent: AdwAccentColorName | null) => void, options?: OnMacosAccentColorChangedOptions): () => void;

package/lib/types/system-accent.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@gjsify/adwaita-app",
-    "version": "0.51.1",
-    "description": "Native Adwaita application shell for GJS/GTK apps — Adw.Application lifecycle (runAsync + devtools + CSS), a data-driven NavigationSplitView nav shell, an async-view mounter, and promise dialog/toast/file helpers",
+    "version": "0.53.0",
+    "description": "Native Adwaita application shell for GJS/GTK apps — Adw.Application lifecycle (runAsync + devtools + CSS), a data-driven NavigationSplitView nav shell, an async-view mounter, promise dialog/toast/file helpers, and a display-less reader of the desktop accent and colour scheme (`./appearance`)",
     "type": "module",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -9,6 +9,14 @@
         ".": {
             "types": "./lib/types/index.d.ts",
             "default": "./lib/esm/index.js"
+        },
+        "./appearance": {
+            "types": "./lib/types/appearance/index.d.ts",
+            "default": "./lib/esm/appearance/index.js"
+        },
+        "./system-accent": {
+            "types": "./lib/types/system-accent.d.ts",
+            "default": "./lib/esm/system-accent.js"
         }
     },
     "files": [
@@ -42,19 +50,20 @@
         "framework"
     ],
     "dependencies": {
-        "@girs/adw-1": "5.0.0",
-        "@girs/gdk-4.0": "5.0.0",
-        "@girs/gio-2.0": "5.0.0",
-        "@girs/gjs": "5.0.0",
-        "@girs/glib-2.0": "5.0.0",
-        "@girs/gobject-2.0": "5.0.0",
-        "@girs/gtk-4.0": "5.0.0",
-        "@gjsify/devtools": "^0.51.1"
+        "@girs/adw-1": "5.4.0",
+        "@girs/gdk-4.0": "5.4.0",
+        "@girs/gio-2.0": "5.4.0",
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@girs/gobject-2.0": "5.4.0",
+        "@girs/gtk-4.0": "5.4.0",
+        "@gjsify/adwaita-core": "^0.53.0",
+        "@gjsify/devtools": "^0.53.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.51.1",
-        "@gjsify/storybook": "^0.51.1",
-        "@gjsify/unit": "^0.51.1",
+        "@gjsify/cli": "^0.53.0",
+        "@gjsify/storybook": "^0.53.0",
+        "@gjsify/unit": "^0.53.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
@@ -66,6 +75,15 @@
             "nativescript": "none"
         },
         "tier": 2,
+        "os": {
+            "linux": "supported",
+            "darwin": "partial",
+            "win32": "partial"
+        },
+        "osNotes": {
+            "darwin": "`locale.ts` reads `process.platform` to decide whether `initLocale` binds a text domain at all, so this package owes an OS claim (ADR 0018). The DECISION is complete and asserted from any host: the platform is an argument to `systemLocaleDir(platform)`, and `locale-dir.spec.ts` drives darwin, win32, linux, an unmeasured platform and an absent `process.platform` through it from Linux. What no runner observes is the SELECTION — `locale.ts` reading the real `process.platform` on a real Mac and skipping `bindtextdomain`. NO LEG OF THIS PACKAGE'S SUITE HAS EVER RUN ON DARWIN: `gtk-os-suites.yml` runs `@gjsify/gtk-host` (gating) and `@gjsify/react-native` (probe) on the darwin legs and nothing else, and `macos-suites.yml` is a Node-pillar workflow that states outright that `gtk4` is not installed. This is exactly the position `@gjsify/path` records for win32 — semantics exercised from every host, selection observable nowhere — and it takes the same word. Promote from the first run of this package's own suite on a darwin leg. The `./appearance` subpath (ADR 0078) branches on `process.platform` too: its macOS reader runs `defaults read -g` and watches `~/Library/Preferences`. Its mapping (`appearanceFromMacDefaults`) is asserted on every host by `appearance/mapping.spec.ts`; spawning `defaults` and the directory monitor have NOT run on a Mac. Verified on real hardware separately, not in CI.",
+            "win32": "As darwin for why a claim is owed and why it is not `supported`: `locale-dir.spec.ts` asserts the win32 answer from Linux, and nothing runs this package's suite on a Windows host — `gtk-os-suites.yml`'s win32 leg carries `@gjsify/gtk-host` and `@gjsify/react-native` as probes and nothing else. One thing is BETTER here than on darwin and is worth recording so the promotion is not blocked on the wrong obstacle: there is no GJS host on Windows at all (ADR 0024 § 4), so the route is Node, where `process.platform` comes from the host itself and is authoritative — the unexercised `uname` probe that keeps `@gjsify/process` at win32 `partial` is not on this path. What is unexercised is this package, not the platform read underneath it. Promote from the first run of this package's own suite on a win32 leg. The `./appearance` subpath (ADR 0078) reads the accent and app mode with `reg.exe query` and polls for changes, because `GWin32RegistryKey` returns values through a `gpointer` out-parameter introspection cannot marshal. The parser and mapping (`parseRegQuery`, `appearanceFromWindowsRegistry`) are asserted on every host; spawning reg.exe on Windows has NOT been measured."
+        },
         "storybook": {
             "applicationId": "org.gjsify.AdwaitaAppStorybook",
             "title": "Adwaita App",