@gjsify/adwaita-web 0.64.1-next.241 → 0.64.1-next.243

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.64.1-next.241",
+    "version": "0.64.1-next.243",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -58,14 +58,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "0.64.1-next.241",
-        "@gjsify/adwaita-fonts": "0.64.1-next.241",
-        "@gjsify/adwaita-icons": "0.64.1-next.241",
-        "@gjsify/gtksource-core": "0.64.1-next.241",
+        "@gjsify/adwaita-core": "0.64.1-next.243",
+        "@gjsify/adwaita-fonts": "0.64.1-next.243",
+        "@gjsify/adwaita-icons": "0.64.1-next.243",
+        "@gjsify/gtksource-core": "0.64.1-next.243",
         "@lezer/highlight": "^1.2.3"
     },
     "peerDependencies": {
-        "@gjsify/app-settings": "0.64.1-next.241"
+        "@gjsify/app-settings": "0.64.1-next.243"
     },
     "peerDependenciesMeta": {
         "@gjsify/app-settings": {
@@ -73,11 +73,11 @@
         }
     },
     "devDependencies": {
-        "@gjsify/app-settings": "0.64.1-next.241",
-        "@gjsify/blueprint": "0.64.1-next.241",
-        "@gjsify/cli": "0.64.1-next.241",
-        "@gjsify/unit": "0.64.1-next.241",
-        "@gjsify/vite-plugin-blueprint": "0.64.1-next.241",
+        "@gjsify/app-settings": "0.64.1-next.243",
+        "@gjsify/blueprint": "0.64.1-next.243",
+        "@gjsify/cli": "0.64.1-next.243",
+        "@gjsify/unit": "0.64.1-next.243",
+        "@gjsify/vite-plugin-blueprint": "0.64.1-next.243",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },
@@ -115,5 +115,5 @@
         "url": "https://github.com/gjsify/gjsify/issues"
     },
     "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/adwaita-web#readme",
-    "gitHead": "9937e8d27d18d159e35471b6669bdca6dff0cd05"
+    "gitHead": "f88c7b1074d454e211094963a9f4dc7d0982bf32"
 }

package/scss/_about_dialog.scss

@@ -149,10 +149,10 @@ adw-about-dialog {
     height: 96px;
     margin-top: var(--spacing-s);
     margin-bottom: var(--spacing-m);
-    // Mask-driven .adw-icon skin scaled up to the about-dialog app-icon size.
+    // A symbolic glyph scales with the box; the fill stays `.adw-icon`'s `currentColor`,
+    // which `.adw-icon-color` turns off for a registered colour application icon.
     -webkit-mask-size: contain;
     mask-size: contain;
-    background-color: currentColor;
   }
 
   // --- App name (title-1) ---

package/scss/_icon.scss

@@ -96,3 +96,21 @@
 .adw-icon:not([class*='adw-icon--']) {
   background-color: transparent;
 }
+
+// A FULL-COLOUR icon — what `registerColorIcon()` registers and `<gtk-image>` resolves a
+// name to before (or, for `-symbolic` names, after) the symbolic glyph, in the order GTK's
+// theme tries them. It is drawn as-is, the way GTK draws `hicolor/…/apps/<app-id>.svg`: no
+// mask and no `currentColor` fill, only the image the element puts in `background-image`.
+//
+// The modifier is NOT `adw-icon--…`, so the rule above never sees it as a mask class.
+// Two classes beat both `:where(.adw-icon)` and the one-class sizing rules a context sets
+// (`.adw-about-dialog-icon`'s mask-size), so an icon box drawn in colour never picks up a
+// leftover mask from them.
+.adw-icon.adw-icon-color {
+  mask-image: none;
+  -webkit-mask-image: none;
+  background-color: transparent;
+  background-position: center;
+  background-repeat: no-repeat;
+  background-size: contain;
+}

package/src/canvas2d/canvas2d-bridge.ts

@@ -63,7 +63,55 @@ export class Canvas2DBridgeElement extends HostElement {
     private _drawFrame: number | null = null;
 
     static get observedAttributes() {
-        return ['content-width', 'content-height'];
+        return ['content-width', 'content-height', 'focusable', 'can-focus'];
+    }
+
+    /**
+     * `Gtk.Widget:focusable`, whether the widget can hold the keyboard focus. `Gtk.DrawingArea`
+     * leaves it FALSE, so it is read by PRESENCE; a blueprint's `focusable: true` writes it.
+     */
+    get focusable(): boolean {
+        return this.hasAttribute('focusable');
+    }
+
+    set focusable(v: boolean) {
+        this.toggleAttribute('focusable', !!v);
+    }
+
+    /** `Gtk.Widget:can-focus`, TRUE by default, so it is read by VALUE. */
+    get canFocus(): boolean {
+        return this.getAttribute('can-focus') !== 'false';
+    }
+
+    set canFocus(v: boolean) {
+        this.setAttribute('can-focus', v ? 'true' : 'false');
+    }
+
+    get can_focus(): boolean {
+        return this.canFocus;
+    }
+
+    set can_focus(v: boolean) {
+        this.canFocus = v;
+    }
+
+    /**
+     * `gtk_widget_grab_focus`: moves the keyboard focus here and says whether it landed.
+     * FALSE when the widget is not focusable or cannot focus, as in GTK.
+     */
+    grab_focus(): boolean {
+        if (!this.focusable || !this.canFocus) return false;
+        this.focus();
+        return this.ownerDocument.activeElement === this;
+    }
+
+    grabFocus(): boolean {
+        return this.grab_focus();
+    }
+
+    private _syncFocus(): void {
+        if (this.focusable && this.canFocus) this.tabIndex = 0;
+        else this.removeAttribute('tabindex');
     }
 
     /** `Gtk.DrawingArea:content-width`, the minimum and natural width. Defaults to 0. */
@@ -161,6 +209,7 @@ export class Canvas2DBridgeElement extends HostElement {
         this.style.overflow = 'hidden';
         this.style.position = 'relative';
         this._publishSize();
+        this._syncFocus();
         this._observe();
     }
 
@@ -171,6 +220,7 @@ export class Canvas2DBridgeElement extends HostElement {
 
     attributeChangedCallback(name: string) {
         if (name === 'content-width' || name === 'content-height') this._publishSize();
+        else this._syncFocus();
     }
 
     private _publishSize(): void {

package/src/canvas2d-bridge.spec.ts

@@ -0,0 +1,47 @@
+// DOM-level tests for <gjsify-canvas2d-bridge>: the keyboard focus a game console needs for its keys.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { Canvas2DBridgeElement } from './canvas2d/canvas2d-bridge.js';
+
+function mount(attrs: Record<string, string> = {}): { el: Canvas2DBridgeElement; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gjsify-canvas2d-bridge') as Canvas2DBridgeElement;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+export const Canvas2DBridgeTest = async () => {
+    await describe('<gjsify-canvas2d-bridge> focus', async () => {
+        await it('is not focusable by default, so grab_focus returns false', () => {
+            const { el, host } = mount();
+            expect(el.focusable).toBe(false);
+            expect(el.grab_focus()).toBe(false);
+            expect(document.activeElement === el).toBe(false);
+            host.remove();
+        });
+
+        await it('grab_focus takes the keyboard focus when focusable', () => {
+            const { el, host } = mount({ focusable: '' });
+            expect(el.grab_focus()).toBe(true);
+            expect(document.activeElement === el).toBe(true);
+            host.remove();
+        });
+
+        await it('a focusable set after connect makes the element focusable', () => {
+            const { el, host } = mount();
+            el.focusable = true;
+            expect(el.grab_focus()).toBe(true);
+            host.remove();
+        });
+
+        await it('can-focus false refuses the focus', () => {
+            const { el, host } = mount({ focusable: '' });
+            el.canFocus = false;
+            expect(el.can_focus).toBe(false);
+            expect(el.grab_focus()).toBe(false);
+            host.remove();
+        });
+    });
+};

package/src/elements/adw-about-dialog.ts

@@ -19,8 +19,10 @@
 // Properties / attributes (all reflected, mirroring the AdwAboutDialog GObject
 // properties of the same name, hyphenated):
 //   application-name   the application's display name (shown as a title-1)
-//   application-icon   a symbolic icon name (with or without -symbolic); absent
-//                        one, no icon is drawn
+//   application-icon   an icon name, by convention the application ID; drawn in
+//                        colour once `registerColorIcon(id, …)` registered it, else
+//                        as a symbolic glyph or `image-missing` (`<gtk-image>`'s
+//                        lookup); absent one, no icon is drawn
 //   developer-name     the developer / vendor line below the name
 //   version            the version, shown as a clickable pill
 //   comments           a longer description (Details page)

package/src/elements/gtk-image.ts

@@ -1,14 +1,17 @@
-// <gtk-image> — the symbolic icon node as an element. Every icon in this package is a
-// CSS-masked box whose glyph comes from a generated `.adw-icon--<name>` class and
-// whose colour is `currentColor`, so it themes with whatever contains it. The name
-// derivation and its guard live once in `@gjsify/adwaita-core`'s
-// {@link normalizeIconName}, the markup once here.
+// <gtk-image> — the icon node as an element. A symbolic icon is a CSS-masked box whose
+// glyph comes from a generated `.adw-icon--<name>` class and whose colour is
+// `currentColor`, so it themes with whatever contains it. A full-colour icon registered
+// through `registerColorIcon` is the same box with the image as its background and no
+// mask. Which of the two a name reaches is decided once, in `../icon-theme.ts`, in the
+// order GTK's own theme tries them; the symbolic name derivation and its guard live once
+// in `@gjsify/adwaita-core`'s {@link normalizeIconName}, the markup once here.
 //
 // Attributes:
-//   icon-name — symbolic name, with or without the `-symbolic` suffix. A name that is
-//               not a single CSS token (a space, a quote, a reverse-DNS application
-//               id) never reaches a class — it draws {@link MISSING_ICON_NAME}, which
-//               is what GTK draws for it, rather than injecting markup.
+//   icon-name — icon name, `-symbolic` suffix optional. A name that is neither a
+//               registered colour icon nor a single CSS token (a space, a quote, an
+//               unregistered reverse-DNS application id) never reaches a class — it
+//               draws {@link MISSING_ICON_NAME}, which is what GTK draws for it, rather
+//               than injecting markup.
 //   size      — rendered edge length in px. Absent leaves the stylesheet's 16px in
 //               charge; a context that sizes its own icons through CSS
 //               (`.adw-about-dialog-icon`, the split button's 14px arrows) keeps doing
@@ -30,7 +33,9 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 //   name derivation composed from @gjsify/adwaita-core.
 
-import { normalizeIconName, stringIsNotEmpty } from '@gjsify/adwaita-core';
+import { normalizeIconName } from '@gjsify/adwaita-core';
+
+import { lookupIcon, onIconThemeChanged } from '../icon-theme.js';
 
 /**
  * The generated mask-class prefix — the one place the `--` spelling appears. `icon-registry`
@@ -46,6 +51,13 @@ export const MASK_CLASS_PREFIX = 'adw-icon--';
  */
 export const MISSING_ICON_NAME = 'image-missing';
 
+/**
+ * The modifier a colour icon carries. Deliberately NOT under {@link MASK_CLASS_PREFIX}: the
+ * stale-class sweep below and `.adw-icon:not([class*='adw-icon--'])` both read that prefix
+ * as "a mask is applied", and a colour icon has none.
+ */
+export const COLOR_ICON_CLASS = 'adw-icon-color';
+
 export class GtkImage extends HTMLElement {
     static get observedAttributes() {
         return ['icon-name', 'size'];
@@ -62,9 +74,10 @@ export class GtkImage extends HTMLElement {
     }
 
     /**
-     * The name that actually reached the mask class — `''` when the icon-name is
-     * absent, empty, or not usable as one CSS token. Consumers that need to know
-     * whether the DECLARED name is drawable ask this, not the raw attribute.
+     * The name the SYMBOLIC lookup works with — `''` when the icon-name is absent, empty,
+     * or not usable as one CSS token. A registered colour icon can still draw for a name
+     * that answers `''` here (`org.gnome.Builder`); whether a name draws anything but
+     * `image-missing` is `isIconAvailable`'s question.
      *
      * `''` does NOT mean the box draws nothing: an unusable name that was given still
      * draws {@link MISSING_ICON_NAME}. Whether an icon was ASKED FOR is the raw
@@ -85,10 +98,18 @@ export class GtkImage extends HTMLElement {
         else this.setAttribute('size', String(value));
     }
 
+    private _unsubscribe: (() => void) | null = null;
+
     connectedCallback() {
+        this._unsubscribe ??= onIconThemeChanged(() => this._render());
         this._render();
     }
 
+    disconnectedCallback() {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+    }
+
     attributeChangedCallback() {
         this._render();
     }
@@ -102,20 +123,30 @@ export class GtkImage extends HTMLElement {
         // would skip the entry after each hit.
         const stale = [...this.classList].filter((existing) => existing.startsWith(MASK_CLASS_PREFIX));
         this.classList.remove(...stale);
-        const name = this.resolvedIconName;
-        if (name !== '') {
-            this.classList.add(`${MASK_CLASS_PREFIX}${name}`);
-        } else if (stringIsNotEmpty(this.getAttribute('icon-name'))) {
-            // A name was GIVEN and cannot be one CSS token (a space, a quote, a reverse-DNS
-            // application id). GTK has no such state: `gtk_icon_theme_lookup_icon` never
-            // returns NULL, it returns the always-available `image-missing`
-            // (refs/gtk/gtk/gtkicontheme.c — `gtk_icon_paintable_get_icon_name`'s own docs
-            // say so). So the same glyph is drawn here rather than an invisible 16px hole,
-            // which is what `<adw-button-row start-icon-name="a b">` reserved and showed.
+        const found = lookupIcon(this.getAttribute('icon-name'));
+        this.classList.toggle(COLOR_ICON_CLASS, found?.kind === 'color');
+        if (found?.kind === 'color') {
+            // Drawn as-is: `_icon.scss` drops the mask and the `currentColor` fill for this
+            // modifier, so only the image paints. `url` is a data-URI or a resolved href;
+            // the quote and backslash escapes keep it one CSS string either way.
+            this.style.backgroundImage = `url("${found.url.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}")`;
+        } else {
+            this.style.removeProperty('background-image');
+        }
+        if (found?.kind === 'symbolic') {
+            this.classList.add(`${MASK_CLASS_PREFIX}${found.name}`);
+        } else if (found?.kind === 'missing') {
+            // A name was GIVEN and nothing answers it — not a colour icon, and not one CSS
+            // token (a space, a quote, an unregistered reverse-DNS application id). GTK has
+            // no such state: `gtk_icon_theme_lookup_icon` never returns NULL, it returns the
+            // always-available `image-missing` (refs/gtk/gtk/gtkicontheme.c —
+            // `gtk_icon_paintable_get_icon_name`'s own docs say so). So the same glyph is
+            // drawn here rather than an invisible 16px hole, which is what
+            // `<adw-button-row start-icon-name="a b">` reserved and showed.
             this.classList.add(`${MASK_CLASS_PREFIX}${MISSING_ICON_NAME}`);
         }
 
-        // A masked box has no text, so assistive tech has nothing to announce — the
+        // An icon box has no text, so assistive tech has nothing to announce — the
         // accessible name belongs to the control that HOSTS the icon.
         this.setAttribute('aria-hidden', 'true');
 

package/src/elements/gtk-scrolled-window.ts

@@ -394,6 +394,36 @@ export class GtkScrolledWindow extends HTMLElement {
         return this._bars?.vertical ?? null;
     }
 
+    /** `Gtk.ScrolledWindow:child` — the widget inside the viewport, or the one waiting to be adopted. */
+    get child(): Element | null {
+        return this._built ? this._viewport.firstElementChild : this.firstElementChild;
+    }
+
+    set child(value: Element | null) {
+        this.set_child(value);
+    }
+
+    get_child(): Element | null {
+        return this.child;
+    }
+
+    /**
+     * `gtk_scrolled_window_set_child`: replace the child, which sits in the viewport. Before the
+     * first connect there is no viewport yet, so the child waits in the light DOM where
+     * `connectedCallback` adopts it the way it adopts a declared one.
+     */
+    set_child(child: Element | null): void {
+        const current = this.child;
+        if (child === current) return;
+        if (this._built) {
+            this._viewport.replaceChildren(...(child === null ? [] : [child]));
+        } else {
+            current?.remove();
+            if (child !== null) this.appendChild(child);
+        }
+        this.dispatchEvent(new CustomEvent('notify::child', { bubbles: true, detail: { child } }));
+    }
+
     /** The `<gtk-viewport>` the child sits in — the one GTK's `set_child` builds for itself. */
     get viewport(): GtkViewport {
         return this._viewport;
@@ -408,7 +438,13 @@ export class GtkScrolledWindow extends HTMLElement {
             horizontal.setAttribute('orientation', 'horizontal');
             vertical.setAttribute('orientation', 'vertical');
             this._bars = { horizontal, vertical };
-            bindSlottedChildren(this, [{ into: this._viewport }]).install(this._viewport, vertical, horizontal);
+            // `Gtk.ScrolledWindow:child` is a widget PROPERTY, so an authored `child: …` names the
+            // slot by that name; the bare child is the default. Both land in the viewport.
+            bindSlottedChildren(this, [{ name: 'child', into: this._viewport }, { into: this._viewport }]).install(
+                this._viewport,
+                vertical,
+                horizontal,
+            );
             this.setAttribute('role', 'generic');
             // A bar is a VIEW of the viewport's adjustment, so the viewport's
             // `value-changed` is what moves the content and a bar's is what moves the

package/src/gobject-door.spec.ts

@@ -62,6 +62,34 @@ GObject.registerClass(
     GoWebHexdump as never,
 );
 
+const SensitiveTemplate = tree(`template $GoWebSensitive : Adw.Bin {
+    child: Gtk.Box {
+        Gtk.Button btn { sensitive: bind template.enabled; }
+        Gtk.Switch sw { sensitive: bind template.enabled inverted; }
+        Gtk.Label lbl { sensitive: bind template.enabled; }
+    };
+}`);
+
+class GoWebSensitive extends Adw.Bin {
+    declare _btn: HTMLButtonElement;
+    declare _sw: HTMLElement & { disabled: boolean };
+    declare _lbl: HTMLElement;
+    declare enabled: boolean;
+    constructor(params?: Record<string, unknown>) {
+        // @ts-expect-error the element's own constructor takes none; the registered class's takes the params
+        super(params);
+    }
+}
+GObject.registerClass(
+    {
+        GTypeName: 'GoWebSensitive',
+        Template: SensitiveTemplate,
+        InternalChildren: ['btn', 'sw', 'lbl'],
+        Properties: { enabled: GObject.ParamSpec.boolean('enabled', '', '', GObject.ParamFlags.READWRITE, true) },
+    },
+    GoWebSensitive as never,
+);
+
 export const GObjectDoorTest = async () => {
     await driveGObjectVectors(subject, { describe, it, expect }, GOBJECT_VECTORS);
     await describe('adwaita-web: GObject.registerClass end to end (ADR 0096)', async () => {
@@ -116,4 +144,20 @@ export const GObjectDoorTest = async () => {
             });
         }
     });
+    await describe('adwaita-web: Gtk.Widget:sensitive in a template bind', async () => {
+        await it('binds sensitive to a template property, following it both ways of the flag', () => {
+            const el = new GoWebSensitive();
+            expect(el._btn.hasAttribute('disabled')).toBe(false);
+            expect(el._lbl.getAttribute('aria-disabled')).toBe(null);
+            el.enabled = false;
+            expect(el._btn.hasAttribute('disabled')).toBe(true);
+            expect((el._btn as unknown as { sensitive: boolean }).sensitive).toBe(false);
+            expect(el._lbl.getAttribute('aria-disabled')).toBe('true');
+            expect(el._sw.hasAttribute('disabled')).toBe(false);
+            el.enabled = true;
+            expect(el._btn.hasAttribute('disabled')).toBe(false);
+            expect(el._lbl.getAttribute('aria-disabled')).toBe(null);
+            expect(el._sw.hasAttribute('disabled')).toBe(true);
+        });
+    });
 };

package/src/gobject-elements.ts

@@ -132,6 +132,28 @@ export function dispatchElement(el: HTMLElement, signal: string, args: readonly
     el.dispatchEvent(domEvent);
 }
 
+/**
+ * `Gtk.Widget:sensitive` for an element that has no member of that name. The DOM spells it
+ * `disabled` on a form control and `aria-disabled` on anything else (`adw-action-row.ts` reads
+ * both), so the accessor writes the spelling the element understands. An element that already
+ * declares `sensitive` (`<adw-toggle-group>`) keeps its own.
+ */
+export function installSensitive(el: HTMLElement): void {
+    if ('sensitive' in el) return;
+    const observed = (el.constructor as { observedAttributes?: string[] }).observedAttributes ?? [];
+    const form = 'disabled' in el || observed.includes('disabled');
+    Object.defineProperty(el, 'sensitive', {
+        configurable: true,
+        enumerable: false,
+        get: () => (form ? !el.hasAttribute('disabled') : el.getAttribute('aria-disabled') !== 'true'),
+        set: (value: boolean) => {
+            if (form) el.toggleAttribute('disabled', !value);
+            else if (value) el.removeAttribute('aria-disabled');
+            else el.setAttribute('aria-disabled', 'true');
+        },
+    });
+}
+
 /** Gives `el` the instance API of a registered class, over the events it declares. */
 export function installElementApi(el: HTMLElement): void {
     // A registered class already has the core's four methods on its prototype.

package/src/gtk-scrolled-window.spec.ts

@@ -91,6 +91,80 @@ export const GtkScrolledWindowTest = async () => {
         });
     });
 
+    await describe('<gtk-scrolled-window> its child, before and after connect', async () => {
+        const detached = (): { el: GtkScrolledWindow; host: HTMLElement } => {
+            const host = document.createElement('div');
+            host.style.height = '100px';
+            const el = document.createElement('gtk-scrolled-window') as GtkScrolledWindow;
+            host.appendChild(el);
+            return { el, host };
+        };
+        const label = (slot?: string): HTMLElement => {
+            const child = document.createElement('gtk-label');
+            if (slot !== undefined) child.setAttribute('slot', slot);
+            return child;
+        };
+
+        await it('adopts a slot="child" child appended BEFORE the element connects', async () => {
+            const host = document.createElement('div');
+            const el = document.createElement('gtk-scrolled-window') as GtkScrolledWindow;
+            const child = label('child');
+            el.appendChild(child);
+            host.appendChild(el);
+            document.body.appendChild(host);
+            await settle();
+            expect(el.viewport.contains(child)).toBe(true);
+            host.remove();
+        });
+
+        await it('adopts a slot="child" child appended AFTER the element connects', async () => {
+            const { el, host } = mount();
+            const child = label('child');
+            el.appendChild(child);
+            await settle();
+            expect(el.viewport.contains(child)).toBe(true);
+            host.remove();
+        });
+
+        await it('adopts a default-slot child appended before connect', async () => {
+            const host = document.createElement('div');
+            const el = document.createElement('gtk-scrolled-window') as GtkScrolledWindow;
+            const child = label();
+            el.appendChild(child);
+            host.appendChild(el);
+            document.body.appendChild(host);
+            await settle();
+            expect(el.viewport.contains(child)).toBe(true);
+            host.remove();
+        });
+
+        await it('set_child before connect is adopted on connect', async () => {
+            const { el, host } = detached();
+            const child = label();
+            el.set_child(child);
+            expect(el.get_child()).toBe(child);
+            document.body.appendChild(host);
+            await settle();
+            expect(el.viewport.contains(child)).toBe(true);
+            expect(el.child).toBe(child);
+            host.remove();
+        });
+
+        await it('set_child after connect replaces the child inside the viewport', async () => {
+            const { el, host } = mount();
+            const first = label();
+            const second = label();
+            el.set_child(first);
+            expect(el.viewport.contains(first)).toBe(true);
+            el.set_child(second);
+            expect(el.viewport.contains(first)).toBe(false);
+            expect(el.viewport.contains(second)).toBe(true);
+            el.set_child(null);
+            expect(el.child).toBe(null);
+            host.remove();
+        });
+    });
+
     await describe('<gtk-scrolled-window> the policies', async () => {
         await it('shows an automatic bar only while the content is longer than the window', async () => {
             const { el, host } = mount();

package/src/icon-registry.ts

@@ -31,6 +31,7 @@ import { normalizeIconName } from '@gjsify/adwaita-core';
 import { toDataUri } from '@gjsify/adwaita-icons/utils';
 
 import { MASK_CLASS_PREFIX } from './elements/gtk-image.js';
+import { iconResolves, notifyIconThemeChanged } from './icon-theme.js';
 
 /** Marks the one `<style>` element this module owns, so a reload reuses it. */
 const REGISTRY_STYLE_ID = 'adwaita-web-icon-registry';
@@ -130,13 +131,20 @@ export function registerIcon(name: string, svg: string): void {
     // BEFORE the `ruled` early return: taking the sheet is what detects a lost <style>,
     // and a name already in `ruled` is exactly the one the early return would skip.
     const sheet = registrySheet();
-    if (ruled.has(resolved)) return;
-    insertMaskRule(sheet, resolved);
-    ruled.add(resolved);
+    if (!ruled.has(resolved)) {
+        insertMaskRule(sheet, resolved);
+        ruled.add(resolved);
+    }
+    // The CSS above is live for every mask class, but a `name-symbolic` request that fell
+    // back to a registered COLOUR icon has no mask class to update — the symbolic glyph
+    // now wins that lookup, so the element has to run it again.
+    notifyIconThemeChanged();
 }
 
 /**
- * Whether `name` has a glyph — compiled into the stylesheet, or registered at runtime.
+ * Whether `name` draws something other than `image-missing` — a symbolic glyph compiled into
+ * the stylesheet or registered at runtime, or a colour icon from `registerColorIcon`. The
+ * name is looked up exactly as `<gtk-image icon-name>` looks it up (`icon-theme.ts`).
  *
  * Reads the live cascade rather than a generated list, so it answers for a glyph that
  * arrived by any route, including a consumer's own `--icon-<name>` declaration. It is
@@ -151,7 +159,5 @@ export function registerIcon(name: string, svg: string): void {
  * {@link registerIcon} are the two things that create the pair, and both create both.
  */
 export function isIconAvailable(name: string): boolean {
-    const resolved = normalizeIconName(name);
-    if (resolved === '') return false;
-    return getComputedStyle(document.documentElement).getPropertyValue(`--icon-${resolved}`).trim() !== '';
+    return iconResolves(name);
 }