@gjsify/adwaita-web 0.40.0 → 0.42.0

package/src/elements/roving-focus.ts

@@ -0,0 +1,154 @@
+// Arrow-key movement for the composites that hand out a roving tabindex.
+//
+// THE INCIDENT
+//
+// `<adw-view-switcher>`, `<adw-view-switcher-bar>`, `<adw-inline-view-switcher>` and
+// `<adw-sidebar>` each declared `role="tablist"` or `role="listbox"`, then set
+// `tabIndex = -1` on every item except the selected one — the roving tabindex — and
+// registered no keydown listener at all. Measured in Firefox: three items, tabIndex
+// `[0, -1, -1]`, and ArrowRight, ArrowLeft, ArrowDown, Home and End all left
+// `document.activeElement` exactly where it was. The two unselected items were reachable
+// by NO key: the roving tabindex had taken them out of the Tab order and nothing had put
+// them back. That is strictly worse than the plain tab stops they replaced — the widget
+// went from clumsy to unusable by adding an accessibility feature half of it.
+//
+// The rule this module implements is the one `<adw-tab-view>` already states in its own
+// header: "the roving tabindex must keep moving: under `role=tablist` a frozen one leaves
+// every inactive tab keyboard-unreachable". `<adw-tab-view>` keeps its own handler — it
+// also owns Ctrl+Tab, Ctrl+Page-Up/Down and Alt+digit from `Adw.TabView`'s shortcut table,
+// plus a strip-local scroll a shared helper has no business knowing about.
+//
+// WHAT THE KEYS DO, and where each behaviour comes from
+//
+// The SHAPE — Tab enters and leaves at the active item, arrows travel inside — is what
+// the C establishes:
+//   - `refs/libadwaita/src/adw-toggle-group.c:1045` (`adw_toggle_group_focus`) — Tab
+//     forward/backward is PROPAGATED, i.e. focus leaves the group, and every other
+//     direction goes to `adw_widget_focus_child`, i.e. moves within it.
+//     `AdwInlineViewSwitcher` builds exactly this widget with
+//     `accessible-role: GTK_ACCESSIBLE_ROLE_TAB_LIST` (adw-inline-view-switcher.c:702).
+//   - `refs/libadwaita/src/adw-sidebar.c:2168` — `gtk_list_box_set_tab_behavior (…,
+//     GTK_LIST_TAB_ITEM)`: Tab moves BETWEEN rows and their contents, i.e. the list is one
+//     stop from outside, which is the roving tabindex spelled in GTK's own vocabulary.
+//
+// That SELECTION follows focus is grounded for the sidebar and conventional for the two
+// tab lists, and the difference is worth keeping straight:
+//   - `refs/libadwaita/src/adw-sidebar.c:2167` — the sidebar's list is a `GtkListBox` in
+//     `GTK_SELECTION_SINGLE`, where moving the cursor with an unmodified arrow key selects
+//     the row it lands on. The WAI-ARIA listbox practice for a single-select listbox says
+//     the same.
+//   - `refs/libadwaita/src/adw-view-switcher.c:467` and `adw-view-switcher-button.c:337`
+//     declare `TAB_LIST` / `TAB`, but nothing in `AdwToggleGroup` changes `active` on
+//     focus: `set_active_toggle` is reached only from `toggle_active_cb`
+//     (adw-toggle-group.c:818), which fires on a real toggle. So GTK arrows those two
+//     WITHOUT switching the page — manual activation. Selection-follows-focus here is the
+//     WAI-ARIA tabs AUTOMATIC-activation pattern, chosen for consistency with
+//     `<adw-tab-view>`, which already behaves that way. Not a claim about the C.
+//
+// SELECTION IS NOT ACTIVATION. `<adw-sidebar>` emits `activated` — the documented way to
+// reveal a split view's content pane — and an arrow key must not fire it, or every press
+// navigates. `GtkListBox` splits the same two: an arrow key emits `row-selected`, and only
+// Enter/Space/click emit `row-activated`. So the callback below is a SELECT, and Enter and
+// Space stay the browser's own activation of the `<button>` the item already is.
+//
+// No wrap at the ends, following `<adw-tab-view>`, whose arrows use the non-wrapping
+// `selectPreviousPage`/`selectNextPage` (the wrapping pair is Ctrl+Tab's), and GTK, whose
+// `adw_widget_focus_child` stops at the last child.
+
+/** Which axis the items are laid out along — it decides which arrow keys move. */
+export type AdwRovingOrientation = 'horizontal' | 'vertical';
+
+export interface AdwRovingFocusInit {
+    /**
+     * The element the listener sits on — the custom element itself, so items rebuilt at
+     * any time are still covered.
+     */
+    host: HTMLElement;
+    orientation: AdwRovingOrientation;
+    /**
+     * The items a key may land on, in visual order. The widget filters: a `hidden` or
+     * `disabled` item is not navigable, and leaving one in would strand the user on a
+     * `focus()` the browser refuses.
+     */
+    items: () => readonly HTMLElement[];
+    /**
+     * Select `item`. Whether the selection actually MOVED is the widget's own business:
+     * focus travels with the key either way ({@link attachRovingFocus}).
+     */
+    select: (item: HTMLElement) => void;
+}
+
+/** The arrow pair that moves along each axis. */
+const AXIS_KEYS: Record<AdwRovingOrientation, { previous: string; next: string }> = {
+    horizontal: { previous: 'ArrowLeft', next: 'ArrowRight' },
+    vertical: { previous: 'ArrowUp', next: 'ArrowDown' },
+};
+
+/**
+ * Make a roving tabindex navigable: arrows step, Home/End jump, and focus travels with
+ * the selection so the next keypress has somewhere to start from.
+ */
+export function attachRovingFocus(init: AdwRovingFocusInit): void {
+    const { previous, next } = AXIS_KEYS[init.orientation];
+
+    init.host.addEventListener('keydown', (event) => {
+        // A modifier makes it someone else's shortcut: Ctrl+Home is "top of the document",
+        // and `Adw.TabView`'s table is full of Ctrl/Alt combinations.
+        if (event.altKey || event.ctrlKey || event.metaKey) return;
+
+        const items = init.items();
+        // `contains`, not identity: an item is a button holding an icon, a label and a
+        // badge, and a key pressed while one of those is the event target still belongs
+        // to the item.
+        const from = items.findIndex((item) => item === event.target || item.contains(event.target as Node));
+        if (from < 0) return;
+
+        let to: number;
+        switch (event.key) {
+            case previous:
+                to = from - 1;
+                break;
+            case next:
+                to = from + 1;
+                break;
+            case 'Home':
+                to = 0;
+                break;
+            case 'End':
+                to = items.length - 1;
+                break;
+            default:
+                return;
+        }
+
+        // Claimed even when nothing moves: an ArrowDown at the last row that fell through
+        // to the browser would scroll the page out from under a user who is inside the
+        // widget.
+        event.preventDefault();
+        const target = items[to];
+        if (target === undefined || target === items[from]) return;
+
+        // Selection is attempted, and focus moves REGARDLESS of whether it took. Gating
+        // the focus move on the selection having changed put the user back in the state
+        // this module exists to remove: with focus on row 0 and the selection already on
+        // row 1 — reachable by setting `selected` while focus sits elsewhere — the
+        // sidebar's `select` returned false for the row the arrow key targeted, so the
+        // press was swallowed and focus stayed on a row the roving tabindex had taken out
+        // of the Tab order. Measured in Firefox: tabIndex `[-1, 0, -1]`, two ArrowDowns,
+        // `document.activeElement` unmoved both times.
+        init.select(target);
+
+        // Focus travels with the roving tabindex or the next keypress goes nowhere — the
+        // rule `<adw-tab-view>` states. Plain `focus()`, deliberately, and NOT because
+        // these widgets have no scroller of their own: `adw-sidebar` is `overflow-y: auto`
+        // (scss/_sidebar.scss) and does. `focus()` walks every scrollable ancestor up to
+        // the window, and here that is what a GtkListBox cursor move does too — the
+        // enclosing scrolled window scrolls, and an outer one follows. Measured in Firefox
+        // on a 4000 px page: 25 ArrowDowns moved the sidebar's own `scrollTop` 0 → 898 and
+        // left `window.scrollY` at 0. `<adw-tab-view>` needs `preventScroll` for the
+        // opposite reason — C only ever writes the strip's own adjustment
+        // (`scroll_to_tab_full`), so a window scroll there is a divergence, and one
+        // ArrowRight was measured taking the window from y=1800 to y=8367.
+        init.items()[to]?.focus();
+    });
+}

package/src/elements/row-activation.ts

@@ -0,0 +1,92 @@
+// Tab stop and Enter/Space activation for the rows that libadwaita makes activatable.
+//
+// THE INCIDENT
+//
+// Measured in Firefox on an `<adw-preferences-group>` holding an activatable
+// `<adw-action-row>`, an `<adw-button-row>` and an `<adw-expander-row>`: Tab reached NONE
+// of them. Every one reported `tabIndex` `-1` and `role` `null` while all three activated
+// on click, so the whole group was operable by mouse and invisible to a keyboard. The only
+// things Tab did reach inside a group were the NATIVE controls a row happens to contain —
+// `<adw-switch-row>`'s bare checkbox and `<adw-combo-row>`'s `<select>` — i.e. the row was
+// never the thing that took focus, even where upstream says it is.
+//
+// GTK gives this free and the web renderer does not inherit it: every one of these extends
+// `GtkListBoxRow`, which is focusable by construction and activates on Enter and Space.
+//
+// WHICH ROWS, AND WHY EACH
+//
+// Derived from the C, not chosen — a row that is a tab stop it should not be turns every
+// static label into a stop, and one that is not becomes unreachable:
+//
+//   - `<adw-action-row>` only while `activatable`. A plain row is a label.
+//   - `<adw-button-row>` always: `adw-button-row.c:31` says "AdwButtonRow is always
+//     activatable", and the upstream template hardcodes it.
+//   - `<adw-expander-row>` always, on its HEADER — `adw_expander_row_grab_focus`
+//     (adw-expander-row.c:123) forwards focus to `priv->action_row`, so the header row is
+//     the focus target and the disclosure control at once.
+//   - `<adw-switch-row>` on the ROW, and its slider stops being a tab stop:
+//     `adw_switch_row_init` sets `gtk_widget_set_can_focus (self->slider, FALSE)`
+//     (adw-switch-row.c:159) and `gtk_list_box_row_set_activatable (…, TRUE)` (:160).
+//
+// `<adw-combo-row>` is deliberately NOT here. Its control is a native `<select>` stretched
+// over the row: already a tab stop, already a combobox to the accessibility tree, already
+// arrow-navigable, and already `disabled` at one option or fewer — which is exactly
+// `gtk_list_box_row_set_activatable (…, n_items > 1)` (adw-combo-row.c:194) without a line
+// of our own. Making the row the tab stop would take focus off it and put a SECOND
+// combobox in the tree.
+//
+// The key set is `GtkListBoxRow`'s: Enter and Space. Space is prevented because the
+// browser would otherwise scroll the page under the row the user just activated.
+
+/** What a row needs to become the keyboard's idea of one activatable thing. */
+export interface AdwRowActivationInit {
+    /** The element that becomes the tab stop and receives the keys. */
+    row: HTMLElement;
+    /** Re-read on every {@link AdwRowActivation.sync}: is the row activatable right now? */
+    activatable: () => boolean;
+    /**
+     * What Enter and Space do. Defaults to `row.click()` so a row keeps ONE activation
+     * path — the click handler it already has — rather than growing a second one that can
+     * drift from it.
+     */
+    activate?: () => void;
+}
+
+export interface AdwRowActivation {
+    /** Re-derive the tab stop after anything that can change `activatable()`. */
+    sync(): void;
+}
+
+/**
+ * Make `row` a tab stop while it is activatable, and activate it on Enter and Space.
+ *
+ * The listener is the element's OWN and is bound once, without teardown: it survives a
+ * re-parent and is collected with the element, so there is nothing here for
+ * `check-adwaita-connect-rebind.mjs` to hold. Only bindings that reach outside the element
+ * need releasing and re-arming.
+ */
+export function attachRowActivation(init: AdwRowActivationInit): AdwRowActivation {
+    const { row, activatable } = init;
+    const activate = init.activate ?? (() => row.click());
+
+    row.addEventListener('keydown', (event: KeyboardEvent) => {
+        // A child control owns its own keys: a `<select>`, an entry's `<input>` and a
+        // suffix button all use Enter or Space for something else, and swallowing them
+        // here would break the control to activate the row it sits in.
+        if (event.target !== row) return;
+        if (!activatable()) return;
+        if (event.key !== 'Enter' && event.key !== ' ') return;
+        event.preventDefault();
+        activate();
+    });
+
+    const sync = () => {
+        // `removeAttribute`, not `tabIndex = -1`: a row that is not activatable is not
+        // focusable at all upstream, and writing `-1` would make every static label
+        // programmatically focusable instead.
+        if (activatable()) row.tabIndex = 0;
+        else row.removeAttribute('tabindex');
+    };
+    sync();
+    return { sync };
+}

package/src/empty-sections.spec.ts

@@ -0,0 +1,81 @@
+// The `hidden` derivation itself, driven in both directions.
+//
+// `connect-lifecycle.spec.ts` drives the WIDGETS: it appends into every container a
+// consumer can reach and requires the child to be laid out. That half alone does not
+// hold the invariant — replacing the whole derivation with `section.hidden = false`
+// left the full adwaita-web browser suite green, because nothing anywhere asserted that
+// an EMPTY section is hidden or that it goes back to hidden when its last child leaves.
+// An empty bar that re-enters the flow is what that mutant ships.
+//
+// Driven against the helper rather than a widget on purpose: the two elements whose
+// sections are private fields (`<adw-alert-dialog>`, `<adw-status-page>`) have no
+// container getter, so the widget driver cannot see them, and giving them one to satisfy
+// a test would be public API invented for the test.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { bindEmptySections } from './empty-sections.js';
+
+/** A section mounted in the document, since `hidden` is only observable where there is layout. */
+function section(): HTMLElement {
+    const el = document.createElement('div');
+    document.body.appendChild(el);
+    return el;
+}
+
+/** One microtask checkpoint — where a MutationObserver callback lands. */
+const settle = () => Promise.resolve();
+
+export const AdwEmptySectionsTest = async () => {
+    await describe('bindEmptySections', async () => {
+        await it('hides a section that starts empty', async () => {
+            const el = section();
+            bindEmptySections(el);
+            const hidden = el.hidden;
+            el.remove();
+            expect(`empty: hidden=${hidden}`).toBe('empty: hidden=true');
+        });
+
+        await it('shows it when a child lands and hides it again when the last one leaves', async () => {
+            const el = section();
+            bindEmptySections(el);
+
+            const child = document.createElement('span');
+            el.appendChild(child);
+            await settle();
+            const filled = el.hidden;
+
+            child.remove();
+            await settle();
+            const emptied = el.hidden;
+
+            el.remove();
+            expect(`filled: hidden=${filled} | emptied: hidden=${emptied}`).toBe(
+                'filled: hidden=false | emptied: hidden=true',
+            );
+        });
+
+        await it('counts element children, not child nodes', async () => {
+            const el = section();
+            bindEmptySections(el);
+            // The whitespace an indented `<div>\n  </div>` carries is a text node, and a
+            // section full of indentation is still an empty section. This is also why the
+            // CSS `:empty` that this looks like cannot express the rule.
+            el.appendChild(document.createTextNode('\n    '));
+            await settle();
+            const hidden = el.hidden;
+            el.remove();
+            expect(`whitespace only: hidden=${hidden}`).toBe('whitespace only: hidden=true');
+        });
+
+        await it('derives each section it is handed independently', async () => {
+            const empty = section();
+            const filled = section();
+            filled.appendChild(document.createElement('span'));
+            bindEmptySections(empty, filled);
+            const report = `empty=${empty.hidden} filled=${filled.hidden}`;
+            empty.remove();
+            filled.remove();
+            expect(report).toBe('empty=true filled=false');
+        });
+    });
+};

package/src/empty-sections.ts

@@ -0,0 +1,54 @@
+// "Hidden while it has no children" — the ONE derivation, kept live.
+//
+// THE INCIDENT
+//
+// Eight sections across five elements derived `hidden = childElementCount === 0`
+// exactly once — inside the `_initialized` guard, or inside a `_render()` only
+// `attributeChangedCallback` can reach. Neither hears a childList change. Six of them
+// document themselves as imperative append points (`<adw-toolbar-view>.topBar`/
+// `.bottomBar`, `<adw-action-row>` and `<adw-expander-row>`'s `prefixSection`/
+// `.suffixSection`), and the other two are the child slots of `<adw-alert-dialog>` and
+// `<adw-status-page>`. So a header bar appended AFTER connect sat in the DOM with the
+// right classes at offsetHeight 0, while the identical DECLARED bar rendered at 48px:
+// the compiled sheet ends with a global `[hidden] { display: none !important }`, which
+// the widget's own `display: flex` cannot beat. Measured the same in Firefox and
+// Chromium.
+//
+// `<adw-clamp>` had already paid for the same "evaluated once at connect time" shape
+// and fixed it with a MutationObserver on `{ childList: true }`. This is that TECHNIQUE
+// applied to the `hidden` derivation, with one home instead of an eighth site deriving
+// it an eighth time — the clamp keeps its own observer, because what it re-derives is a
+// width, not `hidden`. `<adw-preferences-group>` is the third live one: `hasHeaderSuffix`
+// feeds a core derivation rather than a `hidden` flag, so its existing host observer
+// watches the suffix instead.
+//
+// NOTHING TO TEAR DOWN, deliberately. The observed nodes are children this element
+// BUILT and owns, so the observer is unreachable the moment the element is, and is
+// collected with it — the same reasoning `<adw-overlay-split-view>` writes above the
+// `keydown` listener it binds once and never removes. Only a binding that reaches
+// OUTSIDE (document, window, a media query) has to be released on disconnect and
+// re-established on every connect. Keeping it bound while detached is also the better
+// behaviour: a bar appended to a parked widget is already right when it comes back.
+
+/**
+ * Hide each of `sections` exactly while it holds no element children — now, and one
+ * MICROTASK after every later childList change.
+ *
+ * The deferral is what a MutationObserver is; it matters because the derivation used to
+ * run synchronously inside `_render()`. It lands before paint, so layout is never wrong,
+ * but a caller that appends and measures in the SAME task still reads the old answer —
+ * `<adw-toolbar-view>._syncClasses` does exactly that via `offsetHeight`, and its
+ * undershoot classes are corrected by the ResizeObserver on the next frame.
+ *
+ * Element children, not child NODES: whitespace between two slotted bars is a text node
+ * and an empty bar full of indentation is still an empty bar — which is also why the
+ * CSS `:empty` this looks like cannot express it.
+ */
+export function bindEmptySections(...sections: readonly HTMLElement[]): void {
+    const derive = () => {
+        for (const section of sections) section.hidden = section.childElementCount === 0;
+    };
+    const observer = new MutationObserver(derive);
+    for (const section of sections) observer.observe(section, { childList: true });
+    derive();
+}

package/src/fonts.ts

@@ -0,0 +1,25 @@
+// `@gjsify/adwaita-web/fonts` — the opt-in that actually ships the typeface.
+//
+// A SEPARATE SUBPATH, not part of the root entry, and both halves of that are
+// deliberate:
+//
+//   • Separate, because the payload is base64 TTF. Inlined, the two Adwaita Sans
+//     faces are 2.39 MB / 1.18 MB gzip against a 190 KB / 26 KB stylesheet, and
+//     `gjsify build --app browser` emits ONE file with `inlineDynamicImports`, so
+//     there is no lazy form that costs less. An app on GNOME already has the
+//     typeface installed; an app served to arbitrary browsers does not. That is
+//     the app's call, so it is the app's import.
+//   • A VALUE export rather than a side-effect module, because a side-effect
+//     import is exactly how the fonts stopped shipping in the first place:
+//     `src/index.ts` carried `import '@gjsify/adwaita-fonts';` for its whole
+//     life, and under css-as-string that resolves to `export default "<css>"`,
+//     tree-shakes to nothing, and exits 0. `applyAdwaitaFonts` has to be CALLED,
+//     so there is no way to write the opt-in and still get silence.
+//
+// Usage:
+//
+//     import '@gjsify/adwaita-web';
+//     import { applyAdwaitaFonts } from '@gjsify/adwaita-web/fonts';
+//     applyAdwaitaFonts();
+
+export { ADWAITA_FONTS_CSS, ADWAITA_FONTS_STYLE_ID, applyAdwaitaFonts } from '@gjsify/adwaita-fonts/embedded';

package/src/icon-registry.spec.ts

@@ -0,0 +1,240 @@
+// What an icon actually DRAWS — the assertion `adw-icon.spec.ts` did not make.
+//
+// THE INCIDENT. `_icon.scss` set `background-color: currentColor` plus mask sizing and no
+// `mask-image`, so a name outside the compiled `.adw-icon--<name>` set painted a solid 16px
+// square in the widget's text colour. Every spec in this package agreed with it: they read
+// `classList`, and the class WAS applied — correctly, and to nothing. Measured in Firefox
+// before the fix, `<span class="adw-icon adw-icon--dialog-error">` reported
+// `mask-image: none` with `background-color: rgb(0, 128, 0)` and a 16x16 box, next to a
+// `go-next` control whose mask was an 825-character data URI. That is the whole defect, and
+// the reason it survived is that no assertion anywhere read `maskImage`.
+//
+// So these tests go through `getComputedStyle`. Three states have to stay distinguishable:
+// a compiled name draws its own glyph, an unknown name draws `image-missing`, and a name
+// that was never given draws nothing at all.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { isIconAvailable, registerIcon } from './icon-registry.js';
+import type { AdwIcon } from './elements/adw-icon.js';
+
+/** A name no compiled entry can collide with, for the "not shipped" arm. */
+const ABSENT = 'gjsify-registry-probe';
+
+/** An Adwaita symbolic SVG, small and distinctive — a filled 8px square in the 16px grid. */
+const PROBE_SVG = `<svg height="16px" viewBox="0 0 16 16" width="16px" xmlns="http://www.w3.org/2000/svg">
+    <path d="m 4 4 h 8 v 8 h -8 z m 0 0" fill="currentColor"/>
+</svg>`;
+
+function mount(iconName: string | null): { el: AdwIcon; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('adw-icon') as AdwIcon;
+    if (iconName !== null) el.iconName = iconName;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/**
+ * What an icon box actually draws. Exported because the vector-driven icon specs
+ * (`adw-action-rows`, `adw-button-content`, `split-button`) need the same discriminator:
+ * they used to read `classList` alone, which is green on a correctly-applied class over
+ * a glyph nobody has.
+ */
+export const maskOf = (el: HTMLElement): string => getComputedStyle(el).maskImage;
+
+/**
+ * The `--icon-image-missing` the stylesheet compiles, as the cascade resolves it.
+ *
+ * Compared by EXACT equality against a computed `mask-image` throughout, which is sound
+ * because Firefox serializes both identically — measured, 1336 characters each, byte for
+ * byte. A substring test would not be sound: every icon's data URI opens with the same
+ * `url("data:image/svg+xml,%3Csvg%20height…` prefix, so a leading slice matches ALL of
+ * them, and the first version of this file passed that way while asserting nothing.
+ */
+export function fallbackMask(): string {
+    return getComputedStyle(document.documentElement).getPropertyValue('--icon-image-missing').trim();
+}
+
+export const AdwIconRegistryTest = async () => {
+    await describe('<adw-icon> resolves a name to a real mask', async () => {
+        await it('a compiled name draws its OWN glyph, not the fallback', () => {
+            const { el, host } = mount('go-next');
+            const mask = maskOf(el);
+            expect(mask.startsWith('url(')).toBe(true);
+            // The discriminator. After the fix EVERY icon box has a non-`none` mask, so
+            // "has a mask" no longer separates a drawn glyph from a fallen-back one.
+            expect(mask).not.toBe(fallbackMask());
+            expect(getComputedStyle(el).backgroundColor).not.toBe('rgba(0, 0, 0, 0)');
+            host.remove();
+        });
+
+        await it('an unknown name draws image-missing rather than a solid square', () => {
+            const { el, host } = mount(ABSENT);
+            // The class IS applied — that was never the bug.
+            expect(el.classList.contains(`adw-icon--${ABSENT}`)).toBe(true);
+            expect(maskOf(el)).not.toBe('none');
+            // …and what it draws is libadwaita's own placeholder, the same glyph GTK's icon
+            // theme substitutes for a name it cannot find.
+            expect(maskOf(el)).toBe(fallbackMask());
+            // Still painted: the fill is what makes the mask visible.
+            expect(getComputedStyle(el).backgroundColor).not.toBe('rgba(0, 0, 0, 0)');
+            host.remove();
+        });
+
+        await it('no name at all draws NOTHING — the box is transparent', () => {
+            const { el, host } = mount(null);
+            expect(el.resolvedIconName).toBe('');
+            // `Gtk.Image` with a NULL icon-name renders empty; only a name that was given
+            // and could not be resolved earns the broken glyph.
+            expect(getComputedStyle(el).backgroundColor).toBe('rgba(0, 0, 0, 0)');
+            // The box still occupies its slot, as the GTK image does.
+            expect(getComputedStyle(el).width).toBe('16px');
+            host.remove();
+        });
+
+        await it('a name that is not one CSS token draws image-missing, not nothing', () => {
+            // GTK has no third answer: `gtk_icon_theme_lookup_icon` never returns NULL, so
+            // `org.gnome.Builder` on a machine without Builder paints the broken glyph.
+            // The web used to paint an invisible hole instead — a VISIBLE 16px slot with
+            // nothing in it, since `resolvedIconName === ''` was read as "no icon asked
+            // for". Reachable through a first-class attribute: `application-icon` is the
+            // application ID by convention (adw-about-dialog.c:1215).
+            for (const unusable of ['a b', 'org.gnome.Builder']) {
+                const { el, host } = mount(unusable);
+                expect(el.resolvedIconName).toBe('');
+                expect(maskOf(el)).toBe(fallbackMask());
+                expect(getComputedStyle(el).backgroundColor).not.toBe('rgba(0, 0, 0, 0)');
+                host.remove();
+            }
+        });
+    });
+
+    await describe('a name carried by STATE still resolves', async () => {
+        await it("the password row's peek toggle draws both of its glyphs", () => {
+            // These two reach `<adw-icon>.iconName` as `state.peekIconName`, a property of
+            // the core's `PasswordEntryRowState`, so no literal spells them at the point of
+            // use. `check-adwaita-icon-masks.mjs` reads their DECLARATIONS
+            // (`PASSWORD_REVEAL_ICON_NAME`), which proves the map entry exists — never that
+            // a glyph arrives on the element. That is this test, measured rather than
+            // asserted against the same constant the widget writes, which is how
+            // `entry-rows.spec.ts` reads `dataset.iconName` and agrees with itself.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const row = document.createElement('adw-password-entry-row') as HTMLElement & { revealed: boolean };
+            host.appendChild(row);
+
+            const toggleIcon = row.querySelector('.adw-password-entry-row-toggle .adw-icon') as HTMLElement;
+            const masked = maskOf(toggleIcon);
+            expect(masked).not.toBe(fallbackMask());
+
+            row.revealed = true;
+            const revealed = maskOf(toggleIcon);
+            expect(revealed).not.toBe(fallbackMask());
+            // …and the two are DIFFERENT glyphs, or one of them is drawing the other's.
+            expect(revealed).not.toBe(masked);
+            host.remove();
+        });
+    });
+
+    await describe('registerIcon — the documented way out of the compiled set', async () => {
+        await it('reports an unshipped name as unavailable before registration', () => {
+            expect(isIconAvailable(ABSENT)).toBe(false);
+            // …and a compiled one as available, so the check is not answering `false` to
+            // everything. `image-missing` is the case a fallback-comparison would get wrong.
+            expect(isIconAvailable('go-next')).toBe(true);
+            expect(isIconAvailable('image-missing')).toBe(true);
+            expect(isIconAvailable('')).toBe(false);
+        });
+
+        await it('makes the name resolve, on an element that is ALREADY mounted', () => {
+            const { el, host } = mount(ABSENT);
+            const before = maskOf(el);
+            expect(before).toBe(fallbackMask());
+
+            registerIcon(ABSENT, PROBE_SVG);
+
+            const after = maskOf(el);
+            expect(after).not.toBe(before);
+            expect(after).not.toBe(fallbackMask());
+            // The glyph really is the SVG that was handed over: `toDataUri` percent-encodes
+            // it, so the path data survives as `m%204%204`.
+            expect(after.includes('m%204%204')).toBe(true);
+            expect(isIconAvailable(ABSENT)).toBe(true);
+            host.remove();
+        });
+
+        await it('serves an element mounted AFTER the registration too', () => {
+            const { el, host } = mount(`${ABSENT}-symbolic`);
+            // The `-symbolic` suffix is stripped on both sides, so a consumer may spell the
+            // name either way at either end.
+            expect(el.resolvedIconName).toBe(ABSENT);
+            expect(maskOf(el).includes('m%204%204')).toBe(true);
+            host.remove();
+        });
+
+        await it('re-registering REPLACES the glyph without a second rule', () => {
+            const sheet = (document.getElementById('adwaita-web-icon-registry') as HTMLStyleElement).sheet;
+            const rulesBefore = (sheet as CSSStyleSheet).cssRules.length;
+
+            registerIcon(ABSENT, PROBE_SVG.replace('m 4 4 h 8 v 8 h -8 z', 'm 2 2 h 12 v 12 h -12 z'));
+
+            const { el, host } = mount(ABSENT);
+            expect(maskOf(el).includes('m%202%202')).toBe(true);
+            expect((sheet as CSSStyleSheet).cssRules.length).toBe(rulesBefore);
+            host.remove();
+        });
+
+        await it('throws on a name that could never be one CSS class', () => {
+            // Silently registering nothing is the exact failure this area exists to end, and
+            // unlike a render this is an explicit call with a wrong argument.
+            expect(() => registerIcon('org.gnome.Builder', PROBE_SVG)).toThrow();
+            expect(() => registerIcon('a b', PROBE_SVG)).toThrow();
+            expect(() => registerIcon('', PROBE_SVG)).toThrow();
+        });
+
+        await it('throws on a payload that is not SVG source, and registers nothing', () => {
+            // The NAME was checked from the start; the payload was not, and a wrong payload
+            // is worse than no registration at all: `toDataUri` percent-encodes anything, so
+            // the mask comes out well-formed and masks NOTHING, the registered class beats
+            // `:where(.adw-icon)` and switches this PR's fallback off, and `isIconAvailable`
+            // answers `true`. Measured in Firefox before the guard: `'not an svg at all'`
+            // gave `url("data:image/svg+xml,not%20an%20svg%20at%20all")` on a box painted 0 %,
+            // where the unregistered control painted the 30 % image-missing glyph.
+            const REJECTED = 'gjsify-registry-payload-probe';
+            expect(() => registerIcon(REJECTED, 'not an svg at all')).toThrow();
+            expect(() => registerIcon(REJECTED, '')).toThrow();
+            // The likeliest wrong argument of all: what the custom property HOLDS, handed
+            // over instead of what it was made from.
+            expect(() => registerIcon(REJECTED, 'url("data:image/svg+xml,%3Csvg%3E%3C/svg%3E")')).toThrow();
+            expect(isIconAvailable(REJECTED)).toBe(false);
+
+            const { el, host } = mount(REJECTED);
+            expect(maskOf(el)).toBe(fallbackMask());
+            host.remove();
+        });
+
+        await it('rebuilds its rules after the <style> element is taken away', () => {
+            // What an SPA head swap or an Astro view transition does. The record of inserted
+            // rules is module-level and outlives the element it describes, so the early
+            // return above used to skip the insert forever: the custom property was re-set
+            // and the rule that consumes it never came back.
+            const LOST = 'gjsify-registry-sheet-probe';
+            registerIcon(LOST, PROBE_SVG);
+            document.getElementById('adwaita-web-icon-registry')?.remove();
+
+            registerIcon(LOST, PROBE_SVG);
+
+            expect(document.getElementById('adwaita-web-icon-registry')).not.toBe(null);
+            const { el, host } = mount(LOST);
+            expect(maskOf(el).includes('m%204%204')).toBe(true);
+            host.remove();
+
+            // …and the names registered BEFORE the swap are on the rebuilt sheet too. Their
+            // custom properties survived on the document element, so re-issuing only the
+            // one name being registered would leave every earlier icon on the fallback.
+            const { el: earlier, host: earlierHost } = mount(ABSENT);
+            expect(maskOf(earlier)).not.toBe(fallbackMask());
+            earlierHost.remove();
+        });
+    });
+};