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

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-font-dialog-button.spec.ts

@@ -124,7 +124,9 @@ export const GtkFontDialogButtonTest = async () => {
             expect(label.style.fontFamily).toBe('');
             el.useFont = true;
             expect(label.style.fontWeight).toBe('700');
-            expect(label.style.fontFamily).toBe('"Cantarell"');
+            // Engines differ on serializing a quoted single-identifier family: Firefox keeps
+            // the quotes, Chromium drops them. The family name is what matters.
+            expect(label.style.fontFamily.replace(/"/g, '')).toBe('Cantarell');
             // `use-size` is false, so `PANGO_FONT_MASK_SIZE` was cleared and there is no size.
             expect(label.style.fontSize).toBe('');
             el.useSize = true;

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();
@@ -111,6 +185,9 @@ export const GtkScrolledWindowTest = async () => {
             // An unknown nick is the pspec's `automatic`, not a silent never.
             el.setAttribute('vscrollbar-policy', 'sideways');
             expect(el.vscrollbarPolicy).toBe('automatic');
+            // AUTOMATIC decides from the adjustment, and the viewport was just held at its
+            // minimum by NEVER: the re-measure that lifts it is a ResizeObserver delivery.
+            await settle();
             expect(bars(el).vertical.hidden).toBe(false);
             host.remove();
         });

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);
 }

package/src/icon-theme.spec.ts

@@ -0,0 +1,182 @@
+// The colour half of the icon theme, measured through `getComputedStyle` like
+// `icon-registry.spec.ts` measures the symbolic half: a class on the node proves nothing
+// about what it paints.
+//
+// The order under test is GLib's (`g_themed_icon_update_names`, which `GtkImage`'s lookup
+// goes through): `X` tries [X, X-symbolic], `X-symbolic` tries [X-symbolic, X], and a name
+// neither answers draws `image-missing`. The registry is module-level and outlives a test,
+// so every case registers names of its own.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { COLOR_ICON_CLASS, type GtkImage } from './elements/gtk-image.js';
+import { fallbackMask, maskOf } from './icon-registry.spec.js';
+import { isIconAvailable, registerIcon } from './icon-registry.js';
+import { registerColorIcon } from './icon-theme.js';
+
+/** A full-colour app icon: a red square on a blue disc, nothing `currentColor` about it. */
+const COLOR_SVG = `<svg height="128" viewBox="0 0 128 128" width="128" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="64" cy="64" r="60" fill="#3584e4"/>
+    <rect x="40" y="40" width="48" height="48" fill="#e01b24"/>
+</svg>`;
+
+/** A symbolic glyph, distinct from the colour one by its path data. */
+const SYMBOLIC_SVG = `<svg height="16px" viewBox="0 0 16 16" width="16px" xmlns="http://www.w3.org/2000/svg">
+    <path d="m 3 3 h 10 v 10 h -10 z m 0 0" fill="currentColor"/>
+</svg>`;
+
+function mount(iconName: string): { el: GtkImage; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-image') as GtkImage;
+    el.iconName = iconName;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** Every `.adw-icon--…` mask class on the node. */
+function maskClasses(el: HTMLElement): string[] {
+    return [...el.classList].filter((c) => c.startsWith('adw-icon--'));
+}
+
+/** True when `el` paints the registered colour image and nothing masked. */
+function drawsInColor(el: HTMLElement): boolean {
+    const style = getComputedStyle(el);
+    return (
+        el.classList.contains(COLOR_ICON_CLASS) &&
+        maskClasses(el).length === 0 &&
+        style.maskImage === 'none' &&
+        style.backgroundColor === 'rgba(0, 0, 0, 0)' &&
+        // `#e01b24` survives `toDataUri` as `%23e01b24`.
+        style.backgroundImage.includes('%23e01b24')
+    );
+}
+
+export const AdwIconThemeTest = async () => {
+    await describe('registerColorIcon — a full-colour icon draws as-is', async () => {
+        await it('a reverse-DNS application id draws its image, unmasked and unfilled', () => {
+            const APP_ID = 'org.gjsify.ColorProbe';
+            registerColorIcon(APP_ID, COLOR_SVG);
+
+            const { el, host } = mount(APP_ID);
+            expect(drawsInColor(el)).toBe(true);
+            expect(isIconAvailable(APP_ID)).toBe(true);
+            host.remove();
+        });
+
+        await it('an already-mounted element redraws when the registration lands', () => {
+            const APP_ID = 'org.gjsify.LateColorProbe';
+            const { el, host } = mount(APP_ID);
+            // Before: what GTK draws for a name its theme does not have.
+            expect(maskOf(el)).toBe(fallbackMask());
+
+            registerColorIcon(APP_ID, COLOR_SVG);
+            expect(drawsInColor(el)).toBe(true);
+            host.remove();
+        });
+
+        await it("AdwAboutDialog's application-icon draws in colour", () => {
+            const APP_ID = 'org.gjsify.AboutColorProbe';
+            registerColorIcon(APP_ID, COLOR_SVG);
+
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const dialog = document.createElement('adw-about-dialog');
+            dialog.setAttribute('application-icon', APP_ID);
+            host.appendChild(dialog);
+
+            const icon = dialog.querySelector('.adw-about-dialog-icon') as HTMLElement;
+            expect(drawsInColor(icon)).toBe(true);
+            // The 96px box, and NOT a solid square under the image: the about dialog used to
+            // force `background-color: currentColor` on it.
+            expect(getComputedStyle(icon).width).toBe('96px');
+            host.remove();
+        });
+
+        await it('a URL source resolves against the document', () => {
+            const APP_ID = 'org.gjsify.UrlColorProbe';
+            registerColorIcon(APP_ID, 'icons/org.gjsify.UrlColorProbe.svg');
+
+            const { el, host } = mount(APP_ID);
+            const expected = new URL('icons/org.gjsify.UrlColorProbe.svg', document.baseURI).href;
+            expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(true);
+            expect(getComputedStyle(el).backgroundImage).toBe(`url("${expected}")`);
+            host.remove();
+        });
+    });
+
+    await describe('the lookup order is GThemedIcon’s', async () => {
+        await it('a symbolic icon still masks — a compiled one with no colour entry', () => {
+            const { el, host } = mount('go-next-symbolic');
+            expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            expect(maskClasses(el)).toStrictEqual(['adw-icon--go-next']);
+            expect(maskOf(el)).not.toBe(fallbackMask());
+            expect(getComputedStyle(el).backgroundImage).toBe('none');
+            host.remove();
+        });
+
+        await it('X prefers the colour icon, X-symbolic prefers the symbolic one', () => {
+            const NAME = 'gjsify-theme-both-probe';
+            registerColorIcon(NAME, COLOR_SVG);
+            registerIcon(`${NAME}-symbolic`, SYMBOLIC_SVG);
+
+            const plain = mount(NAME);
+            expect(drawsInColor(plain.el)).toBe(true);
+            plain.host.remove();
+
+            const symbolic = mount(`${NAME}-symbolic`);
+            expect(symbolic.el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            expect(maskOf(symbolic.el).includes('m%203%203')).toBe(true);
+            expect(getComputedStyle(symbolic.el).backgroundImage).toBe('none');
+            symbolic.host.remove();
+        });
+
+        await it('X-symbolic falls back to the colour X, and back again once X-symbolic lands', () => {
+            const NAME = 'gjsify-theme-fallback-probe';
+            registerColorIcon(NAME, COLOR_SVG);
+
+            const { el, host } = mount(`${NAME}-symbolic`);
+            expect(drawsInColor(el)).toBe(true);
+            expect(isIconAvailable(`${NAME}-symbolic`)).toBe(true);
+
+            registerIcon(NAME, SYMBOLIC_SVG);
+            expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            expect(maskOf(el).includes('m%203%203')).toBe(true);
+            host.remove();
+        });
+
+        await it('an unknown name draws image-missing', () => {
+            for (const unknown of ['org.gjsify.NeverRegistered', 'gjsify-theme-never-registered']) {
+                const { el, host } = mount(unknown);
+                expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+                expect(maskOf(el)).toBe(fallbackMask());
+                expect(isIconAvailable(unknown)).toBe(false);
+                host.remove();
+            }
+        });
+    });
+
+    await describe('registerColorIcon rejects what it cannot draw faithfully', async () => {
+        await it('throws on a name that is empty, spaced, or symbolic', () => {
+            expect(() => registerColorIcon('', COLOR_SVG)).toThrow();
+            expect(() => registerColorIcon('a b', COLOR_SVG)).toThrow();
+            // The symbolic half has its own door; GTK's theme treats all three suffixes as
+            // symbolic files.
+            expect(() => registerColorIcon('gjsify-probe-symbolic', COLOR_SVG)).toThrow();
+            expect(() => registerColorIcon('gjsify-probe-symbolic-ltr', COLOR_SVG)).toThrow();
+            expect(() => registerColorIcon('gjsify-probe-symbolic-rtl', COLOR_SVG)).toThrow();
+        });
+
+        await it('throws on a source that is not SVG or an image URL, and registers nothing', () => {
+            const REJECTED = 'org.gjsify.RejectedColorProbe';
+            expect(() => registerColorIcon(REJECTED, '')).toThrow();
+            expect(() => registerColorIcon(REJECTED, '<p>not svg</p>')).toThrow();
+            expect(() => registerColorIcon(REJECTED, 'javascript:alert(1)')).toThrow();
+            expect(() => registerColorIcon(REJECTED, 'data:text/html,<svg></svg>')).toThrow();
+            expect(isIconAvailable(REJECTED)).toBe(false);
+
+            const { el, host } = mount(REJECTED);
+            expect(maskOf(el)).toBe(fallbackMask());
+            host.remove();
+        });
+    });
+};

package/src/icon-theme.ts

@@ -0,0 +1,178 @@
+// The one name → glyph lookup every icon in this package goes through, symbolic AND colour.
+//
+// GTK draws two kinds of icon from the same `icon-name`: a symbolic one, recoloured with the
+// foreground colour, and a full-colour one (an application icon, a document thumbnail) that
+// is drawn as it is. Which one a name reaches is not the widget's choice. `GtkImage` builds a
+// `GThemedIcon` for the name (gtkimage.c → `gtk_icon_theme_lookup_by_gicon`) without
+// `use-default-fallbacks`, and `g_themed_icon_update_names` (GLib gio/gthemedicon.c, not in refs/)
+// turns it into an ordered candidate list:
+//
+//   `X`           → [X, X-symbolic]
+//   `X-symbolic`  → [X-symbolic, X]
+//
+// and `gtk_icon_theme_lookup_icon` returns the first candidate the theme has, else
+// `image-missing` — it never returns NULL (refs/gtk/gtk/gtkicontheme.c, `choose_icon`).
+//
+// This package compiles and registers symbolic glyphs only (`icon-registry.ts`, the
+// stylesheet's `.adw-icon--<name>` masks). The colour half lives here: a map from an EXACT
+// name to an image URL, filled by {@link registerColorIcon}. With the map empty every lookup
+// ends where it ended before this module existed, so nothing that only uses symbolic icons
+// changes.
+//
+// The colour map is keyed by the raw name, not by `normalizeIconName`: an application icon
+// is named after its application ID (`org.gnome.Builder`, adw-about-dialog.c:1215), which is
+// not a CSS token and never could be a mask class, but is a perfectly good Map key.
+//
+// Original implementation.
+
+import { normalizeIconName } from '@gjsify/adwaita-core';
+import { toDataUri } from '@gjsify/adwaita-icons/utils';
+
+/** What one icon name resolves to, in the order GTK's theme would try it. */
+export type IconLookup =
+    /** A registered full-colour image, drawn as-is. `url` is ready for `url("…")`. */
+    | { kind: 'color'; name: string; url: string }
+    /** A symbolic glyph, drawn through the `.adw-icon--<name>` mask. `name` is normalized. */
+    | { kind: 'symbolic'; name: string }
+    /** Nothing in the theme answers this name — draw `image-missing`. */
+    | { kind: 'missing' };
+
+/** The suffix `g_themed_icon_update_names` swaps to build the other variant. */
+const SYMBOLIC_SUFFIX = /-symbolic$/;
+
+/**
+ * Every name GTK's theme treats as a symbolic FILE (gtkicontheme.c `icon_name_is_symbolic`):
+ * the directional variants are symbolic too, so none of them is a colour icon.
+ */
+const SYMBOLIC_FILE_NAME = /-symbolic(?:-ltr|-rtl)?$/;
+
+/** Schemes a colour icon may be fetched from. Anything else can run script or is unknown. */
+const ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'blob:', 'file:']);
+
+const colorIcons = new Map<string, string>();
+
+/**
+ * Elements that drew a lookup result and have to redraw when the theme changes. A symbolic
+ * registration is live through CSS and needs no redraw, but a colour one is an inline
+ * `background-image`, and GTK's own images re-run their lookup on the theme's `changed`
+ * signal for the same reason.
+ */
+const listeners = new Set<() => void>();
+
+/** Subscribe to theme changes. Returns the unsubscribe function. */
+export function onIconThemeChanged(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+
+/** Run every subscriber — after any registration that can change a lookup's answer. */
+export function notifyIconThemeChanged(): void {
+    for (const listener of listeners) listener();
+}
+
+/** Whether a symbolic glyph for an already-normalized name is in the cascade. */
+function hasSymbolic(normalized: string): boolean {
+    if (normalized === '') return false;
+    return getComputedStyle(document.documentElement).getPropertyValue(`--icon-${normalized}`).trim() !== '';
+}
+
+/**
+ * Resolve `iconName` as `gtk_icon_theme_lookup_by_gicon` would for a `GtkImage`. `null` when
+ * no name was given — the state where GTK draws nothing, not `image-missing`.
+ *
+ * When no colour icon is registered for the name, a symbolic request is returned WITHOUT
+ * checking the cascade: the mask class falls back to `image-missing` through CSS by itself
+ * and corrects itself when a later `registerIcon` lands, which is how `<gtk-image>` behaved
+ * before this module. The cascade is read only to choose between a colour entry and a
+ * symbolic glyph.
+ */
+export function lookupIcon(iconName: string | null | undefined): IconLookup | null {
+    if (iconName === null || iconName === undefined || iconName === '') return null;
+    const symbolicRequest = SYMBOLIC_SUFFIX.test(iconName);
+    const colorName = symbolicRequest ? iconName.replace(SYMBOLIC_SUFFIX, '') : iconName;
+    const color = colorIcons.get(colorName);
+    const symbolic = normalizeIconName(iconName);
+
+    if (color === undefined) {
+        return symbolic === '' ? { kind: 'missing' } : { kind: 'symbolic', name: symbolic };
+    }
+    if (symbolicRequest && hasSymbolic(symbolic)) return { kind: 'symbolic', name: symbolic };
+    return { kind: 'color', name: colorName, url: color };
+}
+
+/**
+ * Whether `iconName` resolves to something other than `image-missing` — a registered colour
+ * icon, or a symbolic glyph compiled into the stylesheet or registered at runtime.
+ */
+export function iconResolves(iconName: string): boolean {
+    const found = lookupIcon(iconName);
+    if (found === null || found.kind === 'missing') return false;
+    return found.kind === 'color' || hasSymbolic(found.name);
+}
+
+/** `source` as a URL `background-image` can load, or a thrown reason why not. */
+function colorIconUrl(name: string, source: string): string {
+    if (source.trimStart().startsWith('<')) {
+        const root = new DOMParser().parseFromString(source, 'image/svg+xml').documentElement;
+        if (root.tagName !== 'svg') {
+            throw new TypeError(
+                `registerColorIcon(${JSON.stringify(name)}): the source starts with '<' but parsed ` +
+                    `to <${root.tagName}>, not an <svg> root.`,
+            );
+        }
+        return toDataUri(source);
+    }
+
+    let url: URL;
+    try {
+        url = new URL(source, document.baseURI);
+    } catch {
+        throw new TypeError(`registerColorIcon(${JSON.stringify(name)}): the source is neither SVG source nor a URL.`);
+    }
+    const isImageData = url.protocol === 'data:' && /^data:image\//i.test(url.href);
+    if (!isImageData && !ALLOWED_PROTOCOLS.has(url.protocol)) {
+        throw new TypeError(
+            `registerColorIcon(${JSON.stringify(name)}): ${JSON.stringify(url.protocol)} URLs are not ` +
+                'accepted — use http(s):, blob:, file: or a data:image/ URI.',
+        );
+    }
+    return url.href;
+}
+
+/**
+ * Register a FULL-COLOUR icon under `name` — what an application ships in
+ * `hicolor/scalable/apps/<app-id>.svg` and GTK finds through its icon theme. Every
+ * `<gtk-image>` asking for the name draws the image unrecoloured, the way `AdwAboutDialog`'s
+ * `application-icon` does on GNOME.
+ *
+ * `name` is the EXACT icon name, reverse-DNS application IDs included. A name with a
+ * `-symbolic` suffix THROWS: that is the other half of the theme, and {@link registerIcon}
+ * is its door. `source` is SVG source, or a URL (resolved against the document) to any
+ * image the browser can draw.
+ *
+ * Re-registering a name replaces the image, and every mounted `<gtk-image>` redraws.
+ *
+ * CLIENT-SIDE ONLY, like `registerIcon`: it reads `document`.
+ */
+export function registerColorIcon(name: string, source: string): void {
+    if (typeof name !== 'string' || name === '' || /\s/.test(name)) {
+        throw new TypeError(
+            `registerColorIcon: ${JSON.stringify(name)} is not an icon name — it must be non-empty ` +
+                'and contain no whitespace.',
+        );
+    }
+    if (SYMBOLIC_FILE_NAME.test(name)) {
+        throw new TypeError(
+            `registerColorIcon: ${JSON.stringify(name)} names a SYMBOLIC icon, which is recoloured ` +
+                'rather than drawn as-is — register it with registerIcon() instead.',
+        );
+    }
+    if (typeof source !== 'string' || source.trim() === '') {
+        throw new TypeError(`registerColorIcon(${JSON.stringify(name)}): the source is empty.`);
+    }
+
+    colorIcons.set(name, colorIconUrl(name, source));
+    notifyIconThemeChanged();
+}

package/src/index.ts

@@ -89,6 +89,9 @@ export { registerTemplateClass } from './template-classes.js';
 // the way in for an app that needs a glyph this package does not ship — see
 // `icon-registry.ts` for the full recipe.
 export { isIconAvailable, registerIcon } from './icon-registry.js';
+// The full-colour half of the icon theme — an application icon drawn as-is, the web stand-in
+// for an app's `hicolor/…/apps/<app-id>.svg`. See `icon-theme.ts` for the lookup order.
+export { registerColorIcon } from './icon-theme.js';
 
 // THE WIDGET CLASSES ARE REACHABLE ONLY AS `Adw.<Name>` / `Gtk.<Name>` (ADR 0034
 // clause 2 + § Amendment 6). The namespace used to be the LAST line in the file, under a

package/src/namespace/gtk.ts

@@ -96,6 +96,8 @@ export { GtkToggleButton as ToggleButton } from '../elements/gtk-toggle-button.j
 export { GtkTreeExpander as TreeExpander } from '../elements/gtk-tree-expander.js';
 export { GtkVideo as Video } from '../elements/gtk-video.js';
 export { GtkWindow as Window } from '../elements/gtk-window.js';
+// ADR 0098 Amendment 4: the `Gtk.Window` subset both ports and GJS share, for code that runs on all three.
+export type { WindowCommon } from '@gjsify/adwaita-core';
 export { GtkWindowControls as WindowControls } from '../elements/gtk-window-controls.js';
 export { GtkViewport as Viewport } from '../elements/gtk-viewport.js';
 export { GtkWindowHandle as WindowHandle } from '../elements/gtk-window-handle.js';

package/src/navigation-view.spec.ts

@@ -433,8 +433,8 @@ export const AdwNavigationViewTest = async () => {
     await describe('<adw-navigation-view> GJS-spelled API and declared signals', async () => {
         await it('push_by_tag and get_visible_page_tag follow the camelCase members', () => {
             const { adapter, view, host, page } = mountView();
-            adapter.add(page('root'));
-            adapter.add(page('detail'));
+            adapter.add(page('root'), { tag: 'root' });
+            adapter.add(page('detail'), { tag: 'detail' });
             expect(view.push_by_tag('detail')).toBe(true);
             expect(view.get_visible_page_tag()).toBe('detail');
             host.remove();
@@ -442,8 +442,8 @@ export const AdwNavigationViewTest = async () => {
 
         await it('connects `pushed` and `notify::visible-page`', () => {
             const { adapter, view, host, page } = mountView();
-            adapter.add(page('root'));
-            adapter.add(page('detail'));
+            adapter.add(page('root'), { tag: 'root' });
+            adapter.add(page('detail'), { tag: 'detail' });
             const api = view as unknown as { connect(s: string, h: () => void): number };
             let pushed = 0;
             let visible = 0;

package/src/shared-tree-builder.ts

@@ -55,7 +55,7 @@ import {
 
 import { observeAdaptiveSize } from './breakpoints.js';
 import { capabilities } from './capabilities.mjs';
-import { endpointOf, hasElementApi, installElementApi } from './gobject-elements.js';
+import { endpointOf, hasElementApi, installElementApi, installSensitive } from './gobject-elements.js';
 import { dispatchedSignalsOf } from './signals.js';
 import { slottedChildrenOf } from './slotted-children.js';
 import { isTemplateTag, templateTagFor } from './template-classes.js';
@@ -389,6 +389,7 @@ function buildNode(node: SharedTreeNode, record: BuildRecord): HTMLElement {
 /** What a node asks to be wired once every id exists: its binds and its breakpoints. */
 function collectNode(el: HTMLElement, node: SharedTreeNode, record: BuildRecord): void {
     for (const [property, binding] of Object.entries(node.bindings ?? {})) {
+        if (property === 'sensitive') installSensitive(el);
         record.binds.push({
             el,
             property,