@gjsify/adwaita-web 0.52.0 → 0.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.52.0",
+    "version": "0.54.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -45,16 +45,16 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.52.0",
-        "@gjsify/adwaita-fonts": "^0.52.0",
-        "@gjsify/adwaita-icons": "^0.52.0",
+        "@gjsify/adwaita-core": "^0.54.0",
+        "@gjsify/adwaita-fonts": "^0.54.0",
+        "@gjsify/adwaita-icons": "^0.54.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/blueprint": "^0.52.0",
-        "@gjsify/cli": "^0.52.0",
-        "@gjsify/unit": "^0.52.0",
-        "@gjsify/vite-plugin-blueprint": "^0.52.0",
+        "@gjsify/blueprint": "^0.54.0",
+        "@gjsify/cli": "^0.54.0",
+        "@gjsify/unit": "^0.54.0",
+        "@gjsify/vite-plugin-blueprint": "^0.54.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/scss/_variables.scss

@@ -118,8 +118,37 @@
   --spacing-l: 18px;
   --spacing-xl: 24px;
 
-  // Typography — GNOME default: Adwaita Sans 11
-  --font-family: 'Adwaita Sans', 'Cantarell', 'Inter', 'Segoe UI', sans-serif;
+  // Typography — GNOME default: Adwaita Sans 11. The stack is a PROGRESSION, and the
+  // tail is what makes it one (#1817). 'Adwaita Sans' is installed on a GNOME desktop
+  // and nowhere else; 'Cantarell' is GNOME's own earlier UI face and the right second
+  // guess there; 'Inter' is the one cross-platform name an app usually has beside it.
+  //
+  // What was MISSING is macOS, and it was missing in the worst place. With no Apple face
+  // named, `sans-serif` resolved to Helvetica — measured on a Mac carrying neither
+  // Adwaita Sans nor Cantarell — which is the one typeface no libadwaita application is
+  // meant to look like, and the stylesheet said nothing about it. `system-ui` and its
+  // `-apple-system` alias are the two spellings every current engine resolves to the
+  // platform's own UI face (SF on macOS, Segoe UI Variable on Windows, Cantarell on
+  // GNOME), so they go after the named faces and BEFORE the generic: a generic asks the
+  // host for its DEFAULT, which is the substitution this is about, while `system-ui` asks
+  // for its UI face, which is what an Adwaita app wants.
+  //
+  // 'Segoe UI' stays ahead of them as the EXPLICIT Windows face: `system-ui` reached it
+  // only from Windows 8 and Segoe UI Variable only from Windows 11, so the name is still
+  // the portable spelling there. Held honest by the `stylesheet-font-families`
+  // conformance rule, whose ledger carries the reason for 'Adwaita Sans' — never delete
+  // one without the other.
+  //
+  // THE PERIOD ending this first sentence, and the absence of a comment block between
+  // these declarations, are both load-bearing rather than stylistic.
+  // `scripts/generate-adwaita-tokens.mjs` titles each token group by the first sentence
+  // of the comment block touching its FIRST declaration, so a caption with no terminator
+  // runs on into the next words — and a block sitting between two declarations starts a
+  // NEW group, which is how a paragraph about this mechanism became a section title in
+  // the website before it was moved in here. Everything past the first sentence is prose
+  // for that one reader; `check-generated-website-data.mjs` holds both derived artifacts
+  // against the run.
+  --font-family: 'Adwaita Sans', 'Cantarell', 'Inter', 'Segoe UI', system-ui, -apple-system, sans-serif;
   --font-size-base: 11pt;
   --font-size-small: 9pt;
   --font-size-heading: 12pt;
@@ -172,9 +201,21 @@
   // GNOME's PROPORTIONAL UI font, so a monospace fallback chain that reaches it
   // second lands on a font whose figures do not line up — the exact property
   // `.monospace` exists for.
+  //
+  // The tail is the same PROGRESSION the sans stack is, for the same reason (#1817), and
+  // it had the gap in the other direction: `ui-monospace` covers macOS and GNOME but
+  // reaches Cascadia Mono only from Windows 10 1903, and no Windows face was named at
+  // all, so a Windows 10 host without it landed on the `monospace` GENERIC — Times New
+  // Roman, whose figures do not line up, which is the one thing this stack exists to
+  // provide. 'Cascadia Code' ships with Windows Terminal and 'Consolas' is on every
+  // Windows since Vista.
+  //
+  // ONE LINE, and not a style choice: the same generator reads this file with a line-based
+  // reader that REFUSES a declaration it cannot read rather than dropping the token
+  // without saying so, so a wrapped value makes it exit 1.
   --document-font-family: var(--font-family);
   --document-font-size: var(--font-size-base);
-  --monospace-font-family: 'Adwaita Mono', ui-monospace, 'SF Mono', 'Menlo', monospace;
+  --monospace-font-family: 'Adwaita Mono', ui-monospace, 'SF Mono', 'Cascadia Code', 'Consolas', 'Menlo', monospace;
   --monospace-font-size: var(--font-size-base);
 }
 

package/src/accent.ts

@@ -58,17 +58,40 @@ export function isAdwaitaDark(element: HTMLElement): boolean {
     return globalThis.matchMedia?.('(prefers-color-scheme: dark)').matches ?? false;
 }
 
-/** Set the accent custom properties for `name`. */
-export function applyAdwaitaAccent(name: AdwAccentColorName, options: ApplyAccentOptions = {}): void {
-    const target = options.target ?? document.documentElement;
-    const dark = options.dark ?? isAdwaitaDark(target);
+/**
+ * Elements whose accent the APP chose. The desktop-appearance follower
+ * (`appearance.ts`) never writes over one: an explicit choice outranks every
+ * source it reads (ADR 0078). A WeakSet, so a removed element is not kept alive.
+ */
+const appChosen = new WeakSet<HTMLElement>();
 
+/** Whether the app has chosen `target`'s accent with {@link applyAdwaitaAccent}. */
+export function hasAppChosenAccent(target: HTMLElement): boolean {
+    return appChosen.has(target);
+}
+
+/** Write the two properties — the one place they are set, for the app's choice and the follower's alike. */
+export function writeAdwaitaAccent(name: AdwAccentColorName, target: HTMLElement, dark: boolean): void {
     target.style.setProperty(ACCENT_BG_PROPERTY, adwaitaAccentBgColor(name));
     target.style.setProperty(ACCENT_PROPERTY, adwaitaAccentColor(name, dark));
 }
 
-/** Drop the properties, so the stylesheet's own values apply again. */
+/**
+ * Set the accent custom properties for `name` — the app's own choice, which
+ * from now on wins over the desktop's appearance on this element.
+ */
+export function applyAdwaitaAccent(name: AdwAccentColorName, options: ApplyAccentOptions = {}): void {
+    const target = options.target ?? document.documentElement;
+    appChosen.add(target);
+    writeAdwaitaAccent(name, target, options.dark ?? isAdwaitaDark(target));
+}
+
+/**
+ * Drop the properties, so the stylesheet's own values apply again, and hand
+ * the element back to the desktop's appearance.
+ */
 export function clearAdwaitaAccent(target: HTMLElement = document.documentElement): void {
+    appChosen.delete(target);
     target.style.removeProperty(ACCENT_BG_PROPERTY);
     target.style.removeProperty(ACCENT_PROPERTY);
 }

package/src/adw-appearance.spec.ts

@@ -0,0 +1,178 @@
+// Following the desktop's appearance in a real browser (ADR 0078): the handoff
+// tags, live JSON, the CSS system colour, and the precedence between them — all
+// read back through the root's COMPUTED style, since the point is what reaches
+// the cascade.
+//
+// Every test restores the root: the follower acts on `document.documentElement`,
+// which every other suite in this bundle renders under.
+
+import { describe, expect, it } from '@gjsify/unit';
+import { ADW_ACCENT_BG_COLORS, renderAppearanceMeta } from '@gjsify/adwaita-core';
+import { APPEARANCE_HANDOFF_VECTORS, NEAREST_ACCENT_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import '@gjsify/adwaita-web';
+import { ACCENT_BG_PROPERTY, applyAdwaitaAccent, clearAdwaitaAccent } from './accent.js';
+import { adwaitaAccentSource, applyDesktopAppearance, applySystemAccent, readSystemAccent } from './appearance.js';
+
+const root = () => document.documentElement;
+const rootAccent = () => getComputedStyle(root()).getPropertyValue(ACCENT_BG_PROPERTY).trim();
+
+/** MutationObserver callbacks are microtasks; one macrotask later they have run. */
+const settle = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+function addMeta(name: string, content: string): HTMLMetaElement {
+    const meta = document.createElement('meta');
+    meta.name = name;
+    meta.content = content;
+    document.head.append(meta);
+    return meta;
+}
+
+async function restore(...metas: HTMLMetaElement[]): Promise<void> {
+    for (const meta of metas) meta.remove();
+    await settle();
+    applySystemAccent(false);
+    applyDesktopAppearance({});
+    clearAdwaitaAccent(root());
+}
+
+export const AdwAppearanceTest = async () => {
+    await describe('desktop appearance: the <meta> handoff', async () => {
+        await it('applies a handed-over accent without any code in the page', async () => {
+            const defaultAccent = rootAccent();
+            const meta = addMeta('adw-accent', 'purple');
+            await settle();
+            expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS.purple);
+            expect(adwaitaAccentSource()).toBe('handoff');
+
+            // Removing the tag hands the root back to the stylesheet.
+            meta.remove();
+            await settle();
+            expect(rootAccent()).toBe(defaultAccent);
+            expect(adwaitaAccentSource()).toBe('default');
+            await restore();
+        });
+
+        await it('follows a changed content attribute', async () => {
+            const meta = addMeta('adw-accent', 'teal');
+            await settle();
+            meta.content = 'orange';
+            await settle();
+            expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS.orange);
+            await restore(meta);
+        });
+
+        await it('hands over the colour scheme as a theme class, and takes it back', async () => {
+            const meta = addMeta('adw-color-scheme', 'dark');
+            await settle();
+            expect(root().classList.contains('theme-dark')).toBe(true);
+            meta.content = 'no-preference';
+            await settle();
+            expect(root().classList.contains('theme-dark')).toBe(false);
+            await restore(meta);
+        });
+
+        await it('does not re-read the tags for an unrelated <head> change', async () => {
+            // A live JSON handoff must survive a framework injecting a <style>.
+            applyDesktopAppearance({ accent: 'green' });
+            document.head.append(document.createElement('style'));
+            await settle();
+            expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS.green);
+            document.head.lastElementChild?.remove();
+            await restore();
+        });
+    });
+
+    await describe('desktop appearance: APPEARANCE_HANDOFF_VECTORS through a real <head>', async () => {
+        for (const vector of APPEARANCE_HANDOFF_VECTORS) {
+            await it(`${JSON.stringify(vector.meta)} paints ${vector.paints ?? 'the default'}`, async () => {
+                const defaultAccent = rootAccent();
+                const holder = document.createElement('template');
+                holder.innerHTML = renderAppearanceMeta(vector.appearance);
+                const metas = [...holder.content.children] as HTMLMetaElement[];
+                document.head.append(...metas);
+                await settle();
+                expect(rootAccent()).toBe(vector.paints ? ADW_ACCENT_BG_COLORS[vector.paints] : defaultAccent);
+                const themeClass = root().classList.contains('theme-dark')
+                    ? 'theme-dark'
+                    : root().classList.contains('theme-light')
+                      ? 'theme-light'
+                      : null;
+                expect(themeClass).toBe(vector.themeClass);
+                await restore(...metas);
+            });
+        }
+    });
+
+    await describe('desktop appearance: a colour-only handoff is snapped (NEAREST_ACCENT_VECTORS)', async () => {
+        // A server that sends only `accentRgb` gets libadwaita's snapping in the page, read
+        // back from the cascade: the table is held by what the page paints, not by the function.
+        for (const vector of NEAREST_ACCENT_VECTORS) {
+            await it(`${vector.source}: ${vector.color} paints ${vector.expected}`, async () => {
+                applyDesktopAppearance({ accentRgb: vector.color });
+                expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS[vector.expected]);
+                await restore();
+            });
+        }
+    });
+
+    await describe('desktop appearance: live JSON and precedence', async () => {
+        await it('applies validated JSON and ignores what is not an accent', async () => {
+            applyDesktopAppearance({ accent: 'red', colorScheme: 'light' });
+            expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS.red);
+            applyDesktopAppearance({ accent: '"><script>' });
+            expect(adwaitaAccentSource()).toBe('default');
+            await restore();
+        });
+
+        await it("never overrides the app's own choice", async () => {
+            applyAdwaitaAccent('yellow');
+            applyDesktopAppearance({ accent: 'pink' });
+            const meta = addMeta('adw-accent', 'slate');
+            await settle();
+            expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS.yellow);
+            expect(adwaitaAccentSource()).toBe('app');
+
+            // Clearing the app's choice hands the root back to the desktop.
+            clearAdwaitaAccent(root());
+            applyDesktopAppearance({ accent: 'pink' });
+            expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS.pink);
+            await restore(meta);
+        });
+
+        await it('ranks the handoff above the CSS system colour', async () => {
+            applySystemAccent();
+            applyDesktopAppearance({ accent: 'teal' });
+            expect(adwaitaAccentSource()).toBe('handoff');
+            expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS.teal);
+            await restore();
+        });
+    });
+
+    await describe('desktop appearance: the CSS system colour (#1821)', async () => {
+        await it('snaps AccentColor to one of the nine where the engine resolves it, else keeps blue', async () => {
+            // Both outcomes are asserted: support for `AccentColor` differs per engine and
+            // per OS, and "unsupported" must leave the stylesheet's blue, not a guess.
+            const defaultAccent = rootAccent();
+            const system = readSystemAccent();
+            const applied = applySystemAccent();
+            expect(applied).toBe(system?.accent ?? null);
+            if (system) {
+                expect(adwaitaAccentSource()).toBe('system');
+                expect(rootAccent()).toBe(ADW_ACCENT_BG_COLORS[system.accent]);
+            } else {
+                expect(adwaitaAccentSource()).toBe('default');
+                expect(rootAccent()).toBe(defaultAccent);
+            }
+            await restore();
+            expect(rootAccent()).toBe(defaultAccent);
+        });
+
+        await it('the meta keyword "system" asks for the same thing', async () => {
+            const meta = addMeta('adw-accent', 'system');
+            await settle();
+            expect(adwaitaAccentSource()).toBe(readSystemAccent() ? 'system' : 'default');
+            await restore(meta);
+        });
+    });
+};

package/src/appearance.ts

@@ -0,0 +1,207 @@
+// Following the desktop's appearance in a plain web page (ADR 0078, #1821).
+//
+// A page learns the desktop's accent from, in order of precedence:
+//
+//   1. the APP's own choice   `applyAdwaitaAccent(name)` — never overwritten here
+//   2. a server HANDOFF       `<meta name="adw-accent" content="purple">`, or
+//                             `applyDesktopAppearance(json)` for live updates
+//   3. the CSS SYSTEM COLOUR  `AccentColor`, once asked for (`applySystemAccent()`
+//                             or `<meta name="adw-accent" content="system">`)
+//   4. Adwaita blue           the stylesheet's own value
+//
+// The handoff outranks `AccentColor` because it is the better-informed source:
+// a gjsify server reads the desktop itself (`@gjsify/adwaita-app/appearance`),
+// while `AccentColor` is supported unevenly across engines and a page cannot
+// tell a real system accent from an engine's fixed default.
+//
+// EVERY SOURCE IS SNAPPED TO ONE OF THE NINE with `nearestAccent`, as libadwaita
+// does with the system colour it reads, so a web page and a native Adwaita
+// window on the same desktop show the same accent. Consequently the standalone
+// `--accent-color` is libadwaita's derivation of a palette colour, never of the
+// raw system colour.
+//
+// Only `document.documentElement` follows; an accent set on any other element
+// is the app's business.
+
+import {
+    ADW_ACCENT_META_SYSTEM,
+    type AdwAccentColorName,
+    type AppearanceMeta,
+    appearanceFromMeta,
+    type DesktopAppearance,
+    formatAdwRgb,
+    nearestAccent,
+    parseAdwRgb,
+    parseDesktopAppearance,
+} from '@gjsify/adwaita-core';
+
+import { clearAdwaitaAccent, hasAppChosenAccent, isAdwaitaDark, writeAdwaitaAccent } from './accent.js';
+
+/** Which source the root's accent currently comes from. */
+export type AdwAccentSource = 'app' | 'handoff' | 'system' | 'default';
+
+/** What the handoff said last: from the `<meta>` tags, or from `applyDesktopAppearance`. */
+let handoff: AppearanceMeta & { accentRgb?: string } = {};
+/** Whether the page asked to follow CSS `AccentColor`. */
+let systemRequested = false;
+/** Whether the follower has written the root's accent, so it knows what it may remove. */
+let wroteAccent = false;
+/** The theme class the follower added for a handed-off colour scheme, if any. */
+let addedSchemeClass: 'theme-dark' | 'theme-light' | null = null;
+let installed = false;
+
+/**
+ * The browser's CSS system colour `AccentColor`, snapped to the nearest of the
+ * nine — or `null` where the engine does not support the keyword or the
+ * resolved colour cannot be read.
+ *
+ * SUPPORT IS UNEVEN AND NOT ASSUMED: Chrome announced shipping `AccentColor`
+ * only in 2026, and what Firefox resolves it to on Linux is not established;
+ * Firefox 156 on macOS resolves it to `rgb(0, 122, 255)`. An engine may also
+ * report a fixed default instead of the real accent (fingerprinting
+ * protection), which a page cannot detect.
+ */
+export function readSystemAccent(): { accent: AdwAccentColorName; accentRgb: string } | null {
+    if (typeof CSS === 'undefined' || !CSS.supports('color', 'AccentColor')) return null;
+    const probe = document.createElement('span');
+    probe.style.color = 'AccentColor';
+    probe.style.display = 'none';
+    document.documentElement.append(probe);
+    const resolved = getComputedStyle(probe).color;
+    probe.remove();
+    const rgb = parseAdwRgb(resolved);
+    if (!rgb) return null;
+    return { accent: nearestAccent(rgb), accentRgb: formatAdwRgb(rgb) };
+}
+
+function resolve(): { accent: AdwAccentColorName; source: AdwAccentSource } | null {
+    if (handoff.accent && handoff.accent !== ADW_ACCENT_META_SYSTEM)
+        return { accent: handoff.accent, source: 'handoff' };
+    // A handoff that carries only a colour (a server that did not snap it) is snapped here.
+    const handedRgb = handoff.accentRgb ? parseAdwRgb(handoff.accentRgb) : null;
+    if (handedRgb) return { accent: nearestAccent(handedRgb), source: 'handoff' };
+    if (systemRequested || handoff.accent === ADW_ACCENT_META_SYSTEM) {
+        const system = readSystemAccent();
+        if (system) return { accent: system.accent, source: 'system' };
+    }
+    return null;
+}
+
+/** The source the root's accent comes from right now. */
+export function adwaitaAccentSource(): AdwAccentSource {
+    if (typeof document === 'undefined') return 'default';
+    if (hasAppChosenAccent(document.documentElement)) return 'app';
+    return resolve()?.source ?? 'default';
+}
+
+function syncScheme(root: HTMLElement): void {
+    const scheme = handoff.colorScheme;
+    const wanted = scheme === 'dark' ? 'theme-dark' : scheme === 'light' ? 'theme-light' : null;
+    if (wanted === addedSchemeClass) return;
+    if (addedSchemeClass) root.classList.remove(addedSchemeClass);
+    addedSchemeClass = null;
+    // A theme class the APP put on the root is its choice; the handoff does not fight it.
+    if (wanted && !root.classList.contains('theme-dark') && !root.classList.contains('theme-light')) {
+        root.classList.add(wanted);
+        addedSchemeClass = wanted;
+    }
+}
+
+/** Re-apply every automatic source to the root, in precedence order. */
+function sync(): void {
+    const root = document.documentElement;
+    syncScheme(root);
+    if (hasAppChosenAccent(root)) return;
+    const resolved = resolve();
+    if (resolved) {
+        writeAdwaitaAccent(resolved.accent, root, isAdwaitaDark(root));
+        wroteAccent = true;
+    } else if (wroteAccent) {
+        clearAdwaitaAccent(root);
+        wroteAccent = false;
+    }
+}
+
+const isHandoffMeta = (node: Node): boolean =>
+    node.nodeName === 'META' && (node as Element).getAttribute('name')?.startsWith('adw-') === true;
+
+/**
+ * Only a change to one of OUR tags re-reads them. Frameworks and this package
+ * itself insert <style> and <script> into <head> all the time, and re-reading on
+ * those would reset a live handoff from `applyDesktopAppearance` to the tags.
+ */
+function touchesHandoffMeta(record: MutationRecord): boolean {
+    // A renamed tag counts by its old name too, so dropping `name="adw-accent"` is seen.
+    if (record.type === 'attributes')
+        return (
+            isHandoffMeta(record.target) ||
+            (record.attributeName === 'name' && record.oldValue?.startsWith('adw-') === true)
+        );
+    return [...record.addedNodes, ...record.removedNodes].some(isHandoffMeta);
+}
+
+function readMetaHandoff(): void {
+    handoff = appearanceFromMeta(
+        (name) => document.head.querySelector(`meta[name="${name}"]`)?.getAttribute('content') ?? null,
+    );
+}
+
+/**
+ * Start following: read the handoff tags, and re-apply when they change, when
+ * the colour scheme flips (the standalone accent differs between light and
+ * dark) and when the page regains focus (`AccentColor` changes with no event).
+ * Idempotent; `@gjsify/adwaita-web` calls it on import in a browser.
+ */
+export function followDesktopAppearance(): void {
+    if (installed || typeof document === 'undefined') return;
+    installed = true;
+    readMetaHandoff();
+    sync();
+    new MutationObserver((records) => {
+        if (records.some(touchesHandoffMeta)) {
+            readMetaHandoff();
+            sync();
+        }
+    }).observe(document.head, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['content', 'name'],
+        attributeOldValue: true,
+    });
+    globalThis.matchMedia?.('(prefers-color-scheme: dark)').addEventListener('change', sync);
+    globalThis.addEventListener('focus', () => {
+        if (systemRequested || handoff.accent === ADW_ACCENT_META_SYSTEM) sync();
+    });
+}
+
+/**
+ * Follow the CSS system colour `AccentColor` (#1821); `false` stops following
+ * it. A server handoff and the app's own choice still win; where the engine
+ * cannot resolve `AccentColor` the page keeps Adwaita blue. Returns the accent
+ * the system colour snapped to, or `null` (always when disabling).
+ */
+export function applySystemAccent(enabled = true): AdwAccentColorName | null {
+    followDesktopAppearance();
+    systemRequested = enabled;
+    sync();
+    return enabled ? (readSystemAccent()?.accent ?? null) : null;
+}
+
+/**
+ * Apply a desktop appearance handed over at runtime — the JSON a gjsify server
+ * sends when the desktop changes (over SSE, a WebSocket, a message port). The
+ * value is validated, so an untrusted payload is safe to pass straight in; it
+ * REPLACES the previous handoff, including one from the `<meta>` tags.
+ */
+export function applyDesktopAppearance(appearance: unknown): void {
+    // Install first: installing reads the <meta> tags, which must not overwrite this newer value.
+    followDesktopAppearance();
+    const { accent, accentRgb, colorScheme }: DesktopAppearance = parseDesktopAppearance(appearance);
+    handoff = {
+        ...(accent ? { accent } : {}),
+        ...(accentRgb ? { accentRgb } : {}),
+        ...(colorScheme ? { colorScheme } : {}),
+    };
+    sync();
+}

package/src/blueprint-tree.spec.ts

@@ -33,7 +33,7 @@
 // `title-widget:` are GtkBuilder's names, this renderer's are the unnamed slot, `top` and
 // `center`, and a table mapping one to the other inside one renderer is the per-surface
 // translator ADR 0051 § Alternatives rejected turned down on a measurement. Tracked in
-// `status/open-todos.md`.
+// `status/open-todos/README.md`.
 
 import { describe, expect, it } from '@gjsify/unit';
 

package/src/elements/swipe-drag.ts

@@ -179,7 +179,7 @@ export function attachSwipeDrag(init: AdwSwipeDragInit): AdwSwipeDrag {
      * at ALL yet: its offset model is `scrollLeft = position * distance`, and an RTL
      * scroll container counts `scrollLeft` DOWN from 0, so even `scrollToPage(1)` moves
      * nothing (measured). A reversed branch would compute a correct progress and write it
-     * to a container that ignores it. `status/open-todos.md` carries the whole gap; the
+     * to a container that ignores it. `status/open-todos/README.md` carries the whole gap; the
      * flag belongs in the change that can test it.
      */
     const progressOffset = (dx: number, dy: number) => -axisOffset(dx, dy);

package/src/font-stack.spec.ts

@@ -0,0 +1,110 @@
+// The fallback TAIL of both font stacks — the part that decides what a widget set
+// looks like on a host that has neither Adwaita face.
+//
+// THE INCIDENT (#1817)
+//
+// `--font-family` was `'Adwaita Sans', 'Cantarell', 'Inter', 'Segoe UI', sans-serif`
+// and `--monospace-font-family` was `'Adwaita Mono', ui-monospace, 'SF Mono',
+// 'Menlo', monospace`. Both are correct on a GNOME desktop and wrong everywhere
+// the Adwaita faces are absent, which is everywhere else: neither package ships
+// them (see `status/stylesheet-font-families.json`), so a consumer that does not
+// call `applyAdwaitaFonts()` reaches the generic. `sans-serif` is Helvetica on
+// macOS — the font whose metrics every other platform has moved away from — and
+// the monospace generic is Courier New on Windows. Nothing errored; the UI just
+// looked borrowed. Found from a consumer's screenshot, which is the only place
+// this is visible at all.
+//
+// READS THE DECLARATION, NOT A COMPUTED FONT
+//
+// This asserts the SHAPE OF A STACK, not that any family is installed — the
+// distinction `adw-fonts.spec.ts` refuses to blur. So it reads the custom
+// property off the `:root` rule of the injected `<style>`, which is the authored
+// text and byte-identical on every host, rather than
+// `getComputedStyle(el).fontFamily`, which resolves against the machine's font
+// map. The second would pass or fail depending on which fonts the runner has,
+// which is an assertion about the CI image wearing a test's clothes.
+//
+// The ORDER is asserted, not just membership. `system-ui` after the generic
+// family is a stack that is textually present and does nothing, and so is
+// `-apple-system` ahead of a `'Segoe UI'` that a Windows host never reaches.
+import { describe, expect, it } from '@gjsify/unit';
+
+import '@gjsify/adwaita-web';
+
+/**
+ * The declared value of a custom property, read off the stylesheet's own rules.
+ *
+ * NOT `getComputedStyle`, and not "the first `:root`": the sheet declares `:root`
+ * more than once — the generated icon block is one, the light-theme token block is
+ * another — and only some of them carry a given token. So every `:root` rule is
+ * asked and the first that DECLARES the property answers. The assertion is about
+ * the authored text, which is the same on every host.
+ */
+const declared = (property: string): string => {
+    const sheet = (document.getElementById('adwaita-web-style') as HTMLStyleElement | null)?.sheet;
+    expect(sheet).not.toBeNull();
+    for (let index = 0; index < (sheet as CSSStyleSheet).cssRules.length; index++) {
+        const rule = (sheet as CSSStyleSheet).cssRules[index];
+        if (!(rule instanceof CSSStyleRule) || rule.selectorText !== ':root') continue;
+        const value = rule.style.getPropertyValue(property).trim();
+        if (value.length > 0) return value;
+    }
+    throw new Error(`no :root rule in #adwaita-web-style declares ${property}`);
+};
+
+/** The stack's family names, in order, unquoted — a family list split on commas. */
+const families = (value: string): string[] =>
+    value
+        .split(',')
+        .map((family) => family.trim().replace(/^['"]|['"]$/g, ''))
+        .filter((family) => family.length > 0);
+
+/** Index of `family` in the declared stack, or `-1`. */
+const at = (stack: string[], family: string): number => stack.indexOf(family);
+
+export const AdwFontStackTest = async () => {
+    await describe('the font fallback tail', async () => {
+        await it('names a native face for macOS and Windows before the generic', async () => {
+            const stack = families(declared('--font-family'));
+
+            // Every OS's own UI face is reachable, and the generic is LAST — the
+            // whole defect was a stack that ended too early for two of the three
+            // desktop platforms.
+            expect(stack).toContain('system-ui');
+            expect(stack).toContain('-apple-system');
+            expect(stack).toContain('Segoe UI');
+            expect(at(stack, 'system-ui')).toBeGreaterThan(-1);
+            expect(at(stack, 'system-ui')).toBeLessThan(stack.length - 1);
+            expect(stack[stack.length - 1]).toBe('sans-serif');
+        });
+
+        await it('keeps the Adwaita family first, so a GNOME host is unaffected', async () => {
+            // The tail was the defect; moving the HEAD would be a different one. On a
+            // host that has the face, `system-ui` resolves to the same place and the
+            // declaration must not have changed which family wins.
+            const stack = families(declared('--font-family'));
+            expect(stack[0]).toBe('Adwaita Sans');
+            expect(at(stack, 'Adwaita Sans')).toBeLessThan(at(stack, 'system-ui'));
+        });
+
+        await it('names Consolas for Windows, where ui-monospace is not supported', async () => {
+            // `ui-monospace` is the right way to ask and is NOT universally supported;
+            // the engines without it fell straight through to the `monospace` generic,
+            // which is Courier New on Windows. Same repair as the sans stack: the
+            // platform's own face, named, before the generic.
+            const stack = families(declared('--monospace-font-family'));
+            expect(stack).toContain('Consolas');
+            expect(at(stack, 'Consolas')).toBeLessThan(stack.length - 1);
+            expect(stack[stack.length - 1]).toBe('monospace');
+            expect(stack[0]).toBe('Adwaita Mono');
+        });
+
+        await it('carries the repaired tail into the document stack too', async () => {
+            // `.document` text reads `--document-font-family`, which is a `var()` over
+            // the base token rather than a stack of its own — so the repair reaches it
+            // for free ONLY while it stays a reference. Written out longhand it would
+            // be a fourth place to forget, which is the failure this pins.
+            expect(declared('--document-font-family')).toBe('var(--font-family)');
+        });
+    });
+};