@gjsify/adwaita-web 0.41.0 → 0.43.0

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

package/src/icon-registry.ts

@@ -0,0 +1,157 @@
+// The runtime half of icon resolution — how a name OUTSIDE the compiled set gets drawn.
+//
+// `scripts/build-scss.mjs` inlines a chosen subset of `@gjsify/adwaita-icons` into the
+// stylesheet as `--icon-<name>` custom properties plus matching `.adw-icon--<name>` mask
+// classes. The subset exists because the whole set does not fit — inlining every icon that
+// package exports costs a measured ~1.07 MB of data-URI, some five times the stylesheet it
+// would sit in — so a consumer whose app needs a glyph this package does not ship needs a
+// way in that is not "wait for a release".
+//
+// That is this module. `registerIcon` writes the SAME pair the generator writes — the
+// custom property on the document element, the mask class into a stylesheet this module
+// owns — so a registered icon is indistinguishable from a compiled one at every later
+// point: `<adw-icon icon-name="…">`, a hand-written `class="adw-icon adw-icon--…"`, a
+// widget attribute, `var(--icon-…)` in the consumer's own CSS.
+//
+//   import { registerIcon } from '@gjsify/adwaita-web';
+//   import { dialogErrorSymbolic } from '@gjsify/adwaita-icons/status';
+//
+//   registerIcon('dialog-error-symbolic', dialogErrorSymbolic);
+//   // …then anywhere: <adw-icon icon-name="dialog-error-symbolic"></adw-icon>
+//
+// Register BEFORE the icon is mounted where you can. An `<adw-icon>` already in the
+// document draws the `image-missing` fallback (see `_icon.scss`) until the registration
+// lands; the CSS is live, so it corrects itself on the next style recalculation with no
+// re-render, but there is a visible frame in between.
+//
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+ — the icon SVGs.
+// Original implementation.
+
+import { normalizeIconName } from '@gjsify/adwaita-core';
+import { toDataUri } from '@gjsify/adwaita-icons/utils';
+
+import { MASK_CLASS_PREFIX } from './elements/adw-icon.js';
+
+/** Marks the one `<style>` element this module owns, so a reload reuses it. */
+const REGISTRY_STYLE_ID = 'adwaita-web-icon-registry';
+
+/**
+ * Names already given a mask rule. Re-registering a name has to update the GLYPH without
+ * appending a second rule: the custom property carries the glyph and the rule only points
+ * at it, so the property assignment is the whole update and a duplicate rule would be
+ * dead weight that grows without bound under a live theme switcher.
+ */
+const ruled = new Set<string>();
+
+/** The one rule a registration adds: the class, pointing at the custom property. */
+function insertMaskRule(sheet: CSSStyleSheet, name: string): void {
+    sheet.insertRule(
+        `.${MASK_CLASS_PREFIX}${name} { mask-image: var(--icon-${name}); ` +
+            `-webkit-mask-image: var(--icon-${name}); }`,
+        sheet.cssRules.length,
+    );
+}
+
+/** This module's stylesheet, created on first use and appended last so nothing hides it. */
+function registrySheet(): CSSStyleSheet {
+    const existing = document.getElementById(REGISTRY_STYLE_ID) as HTMLStyleElement | null;
+    if (existing?.sheet) return existing.sheet;
+
+    const style = document.createElement('style');
+    style.id = REGISTRY_STYLE_ID;
+    document.head.appendChild(style);
+    // `sheet` is non-null the moment a <style> is in a document — the property is only
+    // null while the element is disconnected, which the append above rules out.
+    const sheet = style.sheet as CSSStyleSheet;
+
+    // Reaching here a SECOND time means the previous element was taken away — an SPA head
+    // swap, an Astro view transition — and every rule it held went with it. The custom
+    // properties did NOT: they sit on the document element. So re-issue the rules, or every
+    // name registered before the swap keeps its glyph in a property nothing consumes and
+    // draws the fallback forever. Nothing observes the head, so the recovery happens on the
+    // next `registerIcon` call rather than at the moment of the swap.
+    for (const name of ruled) insertMaskRule(sheet, name);
+    return sheet;
+}
+
+/**
+ * The second argument has to be SVG SOURCE, and nothing else can tell us so: `toDataUri`
+ * percent-encodes whatever it is handed, so `registerIcon('x', 'not an svg')` produces a
+ * perfectly well-formed `mask-image` that masks NOTHING — an icon strictly worse than an
+ * unregistered one, because the registered class beats `:where(.adw-icon)` and switches the
+ * `image-missing` fallback OFF, while `isIconAvailable` reports `true`. Measured in Firefox:
+ * `url("data:image/svg+xml,not%20an%20svg")`, 0 % of the box painted, no throw, no warning.
+ *
+ * A real parser rather than a `^<svg` test: an icon read from a file carries an XML prolog
+ * or a DOCTYPE before its root element, and both are legitimate here.
+ */
+function svgRootOf(source: string): Element {
+    return new DOMParser().parseFromString(source, 'image/svg+xml').documentElement;
+}
+
+/**
+ * Make `name` drawable by every `.adw-icon` in the document, from an Adwaita symbolic SVG
+ * source string (what `@gjsify/adwaita-icons` exports).
+ *
+ * BOTH arguments are checked and a wrong one THROWS rather than registering nothing: unlike
+ * a render, this is an explicit call with a wrong argument, and silently doing nothing is
+ * the failure mode this whole area exists to end. The name is normalized exactly as
+ * `<adw-icon icon-name>` normalizes it — a single `-symbolic` suffix comes off, and the rest
+ * must be one CSS token; the SVG has to parse to an `<svg>` root. `<adw-icon>` draws
+ * `image-missing` for the same unusable name instead — there it came from markup, and
+ * taking the page down over a typo is not proportionate.
+ *
+ * Registering a name the stylesheet already compiles is allowed and REPLACES the glyph:
+ * the property is set on the document element, so it wins over the `:root` rule.
+ *
+ * CLIENT-SIDE ONLY: this touches `document.documentElement` and `document.head`, so at
+ * module top level in an SSR/SSG build it throws before a page is rendered.
+ */
+export function registerIcon(name: string, svg: string): void {
+    const resolved = normalizeIconName(name);
+    if (resolved === '') {
+        throw new TypeError(
+            `registerIcon: ${JSON.stringify(name)} is not usable as an icon name — it has to be a single ` +
+                'CSS token ([A-Za-z0-9_-]+) once an optional `-symbolic` suffix is removed.',
+        );
+    }
+
+    const root = svgRootOf(svg);
+    if (root.tagName !== 'svg') {
+        throw new TypeError(
+            `registerIcon(${JSON.stringify(resolved)}): the second argument has to be SVG SOURCE — the ` +
+                'kind of string `@gjsify/adwaita-icons` exports, not a URL, a data-URI or a DOM node. ' +
+                `Parsing it produced <${root.tagName}>, so it would have masked nothing at all.`,
+        );
+    }
+
+    document.documentElement.style.setProperty(`--icon-${resolved}`, toDataUri(svg));
+
+    // 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);
+}
+
+/**
+ * Whether `name` has a glyph — compiled into the stylesheet, or registered at runtime.
+ *
+ * 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
+ * deliberately the CUSTOM PROPERTY that is read and not the rendered `mask-image` of a
+ * probe element: since `_icon.scss` gives every icon box the `image-missing` fallback,
+ * a rendered mask is never `none`, and comparing against the fallback would answer
+ * `false` for `image-missing` itself — the one name where being drawn and having fallen
+ * back look identical.
+ *
+ * Narrowing worth knowing: a consumer who writes `.adw-icon--x { mask-image: url(…) }`
+ * with no matching `--icon-x` gets `false` here and a drawn icon anyway. The generator and
+ * {@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() !== '';
+}

package/src/index.ts

@@ -5,9 +5,26 @@
 // SCSS partials at `@gjsify/adwaita-web/scss/...` for custom theming.
 // Reference: refs/libadwaita (colors/sizing), refs/adwaita-web (component patterns).
 
-import '@gjsify/adwaita-fonts'; // Registers @font-face (fontsource pattern)
 import { ADWAITA_WEB_CSS } from './styles.generated.js';
 
+// NO font import here, and the absence is the decision. This line used to be
+// `import '@gjsify/adwaita-fonts';` with the comment "Registers @font-face
+// (fontsource pattern)". It registered nothing: that package's `.` export is
+// `index.css`, css-as-string turns it into `export default "<css>"`, and a
+// SIDE-EFFECT import of a module with no side effect is tree-shaken — measured
+// on 0.41.0 as a 0-byte bundle with zero `@font-face`, exit 0. It was invisible
+// because the primary target platform installs the typeface system-wide, so
+// every local screenshot looked right.
+//
+// The faces now travel through `@gjsify/adwaita-web/fonts` → the generated
+// `@gjsify/adwaita-fonts/embedded`, as `data:` URIs behind a VALUE import, which
+// is the shape a bundler cannot discard. It stays OUT of this entry because it
+// is 2.39 MB / 1.18 MB gzip of base64 against a 190 KB / 26 KB stylesheet, and
+// `--app browser` has no code splitting (`output.inlineDynamicImports`), so a
+// lazy face would cost the same bytes as an eager one. The stacks that head with
+// `'Adwaita Sans'` / `'Adwaita Mono'` are a progressive enhancement over a
+// system-installed face, declared as such in `status/stylesheet-font-families.json`.
+
 // Self-applied so `import '@gjsify/adwaita-web'` styles the components under ANY bundler:
 // a separate `import '@gjsify/adwaita-web/style.css'` is a no-op under a gjsify
 // `--app browser` build, where css-as-string yields a string a side-effect import
@@ -40,6 +57,12 @@ export type { ApplyAccentOptions } from './accent.js';
 export { AdwScrollShading } from './scroll-shading.js';
 export type { AdwUndershootEdges } from './scroll-shading.js';
 
+// The stylesheet compiles a chosen SUBSET of `@gjsify/adwaita-icons` (the whole set is
+// ~1.07 MB of data-URI), so a name outside it draws the `image-missing` fallback. This is
+// 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';
+
 export { AdwAvatar } from './elements/adw-avatar.js';
 export { AdwBanner } from './elements/adw-banner.js';
 export { AdwCard } from './elements/adw-card.js';