@gjsify/adwaita-web 0.64.1-next.245 → 0.64.1

package/README.md

@@ -319,22 +319,43 @@ registerColorIcon('org.example.Other', '/icons/other.png'); // …or an image UR
 Every `<gtk-image>` asking for a registered name draws the image unmasked and unrecoloured,
 which covers every widget that draws its icons through it, `<adw-about-dialog>` and
 `<gtk-about-dialog logo-icon-name>` among them. A name is looked up in the order GTK's own
-theme tries it (`g_themed_icon_update_names`):
+theme tries it (`g_themed_icon_update_names`, then gtkicontheme.c's theme order). A colour
+registration is hicolor's, so the current theme's symbolic glyph comes first either way:
 
 | Asked for | Tried, in order | Neither found |
 | --- | --- | --- |
-| `X` | colour `X`, then symbolic `X-symbolic` | `image-missing` |
+| `X` | symbolic `X-symbolic`, then colour `X` | `image-missing` |
 | `X-symbolic` | symbolic `X-symbolic`, then colour `X` | `image-missing` |
 
-So nothing changes for a name with no colour registration. `registerColorIcon` keys on the
+So nothing changes for a name with no colour registration, and a colour `X` shows only where the
+theme has no `X-symbolic` — the same as on GNOME. `registerColorIcon` keys on the
 **exact** name, reverse-DNS IDs included, and *throws* on an empty or spaced name, on a
 `-symbolic` (`-ltr`/`-rtl`) name — that is `registerIcon`'s half — and on a source that is
 neither SVG source nor an `http(s):`, `blob:`, `file:` or `data:image/` URL. A registration
 redraws every mounted `<gtk-image>`, and `isIconAvailable` answers `true` for the name.
 
-`Gtk.IconTheme.add_resource_path` and `add_search_path` stay records only on the web: there
-is no GResource and no file system to search, so a registration is the one way a colour
-icon gets in.
+### Icons from the app's GResource (ADR 0116)
+
+The way GNOME takes: the app's compiled `.gresource`, registered with the GIO calls it already
+makes on GJS. `Gtk.Application` adds `<resource-base-path>/icons/` to the icon theme at startup
+(`resource-base-path` defaults to `/` + the application ID with `.` as `/`), so an app that
+registers before `run()` needs nothing else:
+
+```typescript
+import { Gio } from '@gjsify/adwaita-web';
+
+Gio.resources_register(Gio.Resource.new_from_data(bytes)); // bytes: the embedded .gresource
+```
+
+`Gtk.IconTheme.get_for_display(null).add_resource_path(path)` adds a path by hand. Under a path
+the lookup follows `gtkicontheme.c`: hicolor subdirectories (`16x16/apps/`, `scalable/apps/`,
+`symbolic/apps/`, …, without a `hicolor/` component) by size and scale, then files directly
+under the path. A compiled symbolic glyph still answers a `-symbolic` name first. A `-symbolic`
+file draws as a mask in `currentColor`, any other SVG or PNG as it is; an XPM or a compressed
+entry draws `image-missing` with a warning. After a colour registration, a resource is the next
+answer, so `registerColorIcon` still wins for its name. If the resource holds `gtk/menus.ui`
+or `gtk/help-overlay.ui` under the base path, startup throws: no builder here reads them yet.
+`add_search_path` stays a record, since there is no file system to search.
 
 ### Why this is a web-only concern
 
@@ -345,7 +366,7 @@ knowing which one you are on:
 | --- | --- | --- |
 | GTK (`@gjsify/adwaita-app`) | `GtkIconTheme` looks it up in the **system** icon theme at runtime | draws the theme's `image-missing` |
 | NativeScript (`@gjsify/adwaita-nativescript`) | `GtkImage` is handed the **SVG source**, not a name | cannot happen — a missing icon is a missing import |
-| Web (this package) | a **compile-time** subset, plus `registerIcon` / `registerColorIcon` | draws `image-missing` |
+| Web (this package) | a **compile-time** subset, the `Gtk.IconTheme` resource paths, plus `registerIcon` / `registerColorIcon` | draws `image-missing` |
 
 All three therefore end on ONE glyph for a name they cannot draw. The web reaches it by two
 routes — no mask class for a known-shaped name, or no usable class for a name like

package/lib/types/elements/gtk-image.d.ts

@@ -39,6 +39,13 @@ export declare class GtkImage extends HTMLElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(): void;
+    /**
+     * What `GtkImage` hands `gtk_icon_theme_lookup_by_gicon` besides the name: the size (the
+     * attribute, else the box the stylesheet gave it), the integer scale and the direction.
+     * `size` is a getter: measuring flushes style, which would start the CSS transitions of
+     * every control around an icon, so only a lookup a resource answers pays for it.
+     */
+    private _request;
     private _render;
 }
 /**

package/lib/types/gio-resource.spec.d.ts

@@ -0,0 +1 @@
+export declare const GioResourceTest: () => Promise<void>;

package/lib/types/icon-theme.d.ts

@@ -1,3 +1,4 @@
+import { type IconDirection } from '@gjsify/adwaita-core';
 /** 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("…")`. */
@@ -6,6 +7,17 @@ export type IconLookup =
     name: string;
     url: string;
 }
+/**
+ * A file under a `Gtk.IconTheme` resource path; `symbolic` files are masks in `currentColor`.
+ * `url` is `null` when the browser cannot draw the file (XPM, compressed): draw `image-missing`.
+ */
+ | {
+    kind: 'resource';
+    name: string;
+    path: string;
+    url: string | null;
+    symbolic: boolean;
+}
 /** A symbolic glyph, drawn through the `.adw-icon--<name>` mask. `name` is normalized. */
  | {
     kind: 'symbolic';
@@ -23,16 +35,30 @@ export declare function notifyIconThemeChanged(): void;
  * 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.
+ * When neither a colour registration nor a resource holds a name, the request is returned as a
+ * symbolic one 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
+ * symbolic glyph and a colour entry or file.
+ */
+export declare function lookupIcon(iconName: string | null | undefined, request?: IconRequest): IconLookup | null;
+/** What a `GtkImage` hands its theme besides the name: its size, scale and text direction. */
+export interface IconRequest {
+    /** In CSS pixels; 16 when absent. */
+    readonly size?: number;
+    /** The device scale; 1 when absent. */
+    readonly scale?: number;
+    readonly direction?: IconDirection;
+}
+/**
+ * The lookup over the colour registrations and the theme's resource paths; `null` when neither
+ * answers any name, a `symbolic` entry when the current theme's glyph comes first.
  */
-export declare function lookupIcon(iconName: string | null | undefined): IconLookup | null;
+export declare function resourceIcon(iconName: string, request: IconRequest): IconLookup | null;
 /**
  * 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.
+ * icon, a file under a resource path, or a symbolic glyph compiled into the stylesheet or
+ * registered at runtime.
  */
 export declare function iconResolves(iconName: string): boolean;
 /**

package/lib/types/namespace/gio.d.ts

@@ -2,5 +2,6 @@ import '../file-chooser-host.js';
 export { GioMenu as Menu, GioMenuItem as MenuItem } from '@gjsify/adwaita-core';
 export { GioFile as File, GioListStore as ListStore, GioOutputStream as OutputStream, GioFileOutputStream as FileOutputStream, FileCreateFlags, IOErrorEnum, promisify as _promisify, } from '@gjsify/adwaita-core';
 export { SimpleAction, SimpleActionGroup, ApplicationFlags } from '@gjsify/adwaita-core';
+export { GioResource as Resource, ResourceError, ResourceLookupFlags, resources_enumerate_children, resources_get_info, resources_lookup_data, resources_register, resources_unregister, } from '@gjsify/adwaita-core';
 export { GioApplication as Application } from '../application.js';
 export { Settings } from '@gjsify/app-settings/browser';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.64.1-next.245",
+    "version": "0.64.1",
     "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.245",
-        "@gjsify/adwaita-fonts": "0.64.1-next.245",
-        "@gjsify/adwaita-icons": "0.64.1-next.245",
-        "@gjsify/gtksource-core": "0.64.1-next.245",
+        "@gjsify/adwaita-core": "^0.64.1",
+        "@gjsify/adwaita-fonts": "^0.64.1",
+        "@gjsify/adwaita-icons": "^0.64.1",
+        "@gjsify/gtksource-core": "^0.64.1",
         "@lezer/highlight": "^1.2.3"
     },
     "peerDependencies": {
-        "@gjsify/app-settings": "0.64.1-next.245"
+        "@gjsify/app-settings": "^0.64.1"
     },
     "peerDependenciesMeta": {
         "@gjsify/app-settings": {
@@ -73,11 +73,11 @@
         }
     },
     "devDependencies": {
-        "@gjsify/app-settings": "0.64.1-next.245",
-        "@gjsify/blueprint": "0.64.1-next.245",
-        "@gjsify/cli": "0.64.1-next.245",
-        "@gjsify/unit": "0.64.1-next.245",
-        "@gjsify/vite-plugin-blueprint": "0.64.1-next.245",
+        "@gjsify/app-settings": "^0.64.1",
+        "@gjsify/blueprint": "^0.64.1",
+        "@gjsify/cli": "^0.64.1",
+        "@gjsify/unit": "^0.64.1",
+        "@gjsify/vite-plugin-blueprint": "^0.64.1",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },
@@ -114,6 +114,5 @@
     "bugs": {
         "url": "https://github.com/gjsify/gjsify/issues"
     },
-    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/adwaita-web#readme",
-    "gitHead": "9a6ca179c1a74477f23791c5b8f6d5a7bffaee61"
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/adwaita-web#readme"
 }

package/src/application.spec.ts

@@ -49,6 +49,7 @@ const subject: ApplicationSubject = {
     SimpleAction: Gio.SimpleAction as unknown as ApplicationSubject['SimpleAction'],
     handlesOpen: Gio.ApplicationFlags.HANDLES_OPEN,
     scene,
+    iconTheme: () => Gtk.IconTheme.get_for_display(null),
 };
 
 export const ApplicationTest = async () => {

package/src/application.ts

@@ -19,6 +19,7 @@ import {
     type AdwMenuModel,
     type ApplicationHost,
 } from '@gjsify/adwaita-core';
+import { IconTheme } from './namespace/gtk-platform.js';
 import { webPlatformHost } from './platform-host.js';
 
 export const webHost: ApplicationHost = {
@@ -38,6 +39,7 @@ export const webHost: ApplicationHost = {
         (window as Element).remove();
     },
     exit() {},
+    iconTheme: () => IconTheme.get_for_display(null),
 };
 
 /** An element's parent for action resolution; a popover is rooted at the widget that owns it. */

package/src/elements/gtk-image.ts

@@ -35,7 +35,12 @@
 
 import { normalizeIconName } from '@gjsify/adwaita-core';
 
-import { lookupIcon, onIconThemeChanged } from '../icon-theme.js';
+import { lookupIcon, onIconThemeChanged, type IconRequest } from '../icon-theme.js';
+
+/** `url` as one CSS string token, whatever quotes or backslashes it holds. */
+function cssUrl(url: string): string {
+    return `url("${url.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}")`;
+}
 
 /**
  * The generated mask-class prefix — the one place the `--` spelling appears. `icon-registry`
@@ -114,6 +119,27 @@ export class GtkImage extends HTMLElement {
         this._render();
     }
 
+    /**
+     * What `GtkImage` hands `gtk_icon_theme_lookup_by_gicon` besides the name: the size (the
+     * attribute, else the box the stylesheet gave it), the integer scale and the direction.
+     * `size` is a getter: measuring flushes style, which would start the CSS transitions of
+     * every control around an icon, so only a lookup a resource answers pays for it.
+     */
+    private _request(): IconRequest {
+        const measure = (): number => {
+            if (this.size !== null) return this.size;
+            const measured = this.isConnected ? Number.parseFloat(getComputedStyle(this).width) : Number.NaN;
+            return Number.isFinite(measured) && measured > 0 ? Math.round(measured) : 16;
+        };
+        return {
+            get size() {
+                return measure();
+            },
+            scale: Math.max(1, Math.round(globalThis.devicePixelRatio ?? 1)),
+            direction: this.matches(':dir(rtl)') ? 'rtl' : 'ltr',
+        };
+    }
+
     private _render(): void {
         this.classList.add('adw-icon');
 
@@ -123,16 +149,31 @@ 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 found = lookupIcon(this.getAttribute('icon-name'));
-        this.classList.toggle(COLOR_ICON_CLASS, found?.kind === 'color');
-        if (found?.kind === 'color') {
+        const looked = lookupIcon(this.getAttribute('icon-name'), this._request());
+        // A resource file the browser cannot draw (XPM, compressed) is GTK's `image-missing`.
+        const found = looked?.kind === 'resource' && looked.url === null ? ({ kind: 'missing' } as const) : looked;
+        const asIs = found?.kind === 'color' || (found?.kind === 'resource' && !found.symbolic) ? found.url : null;
+        const mask = found?.kind === 'resource' && found.symbolic ? found.url : null;
+        this.classList.toggle(COLOR_ICON_CLASS, asIs !== null);
+        if (asIs !== null) {
             // 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;
+            // modifier, so only the image paints. `url` is a data-URI, a blob or a resolved href;
             // the quote and backslash escapes keep it one CSS string either way.
-            this.style.backgroundImage = `url("${found.url.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}")`;
+            this.style.backgroundImage = cssUrl(asIs);
         } else {
             this.style.removeProperty('background-image');
         }
+        if (mask !== null) {
+            // A symbolic file from a resource path: the mask is the file, the fill `currentColor`
+            // (inline, because the classless-box rule in `_icon.scss` makes it transparent).
+            this.style.setProperty('mask-image', cssUrl(mask));
+            this.style.setProperty('-webkit-mask-image', cssUrl(mask));
+            this.style.backgroundColor = 'currentColor';
+        } else {
+            this.style.removeProperty('mask-image');
+            this.style.removeProperty('-webkit-mask-image');
+            this.style.removeProperty('background-color');
+        }
         if (found?.kind === 'symbolic') {
             this.classList.add(`${MASK_CLASS_PREFIX}${found.name}`);
         } else if (found?.kind === 'missing') {

package/src/gio-resource.spec.ts

@@ -0,0 +1,137 @@
+// ADR 0116 §§ 3–4 on the web: the `Gio` resource subset through the `Gio` door, the shared
+// icon theme's resource paths through the lookup `<gtk-image>` uses, and what it then paints.
+// Real GJS is the oracle for both vector sets, in adwaita-core's `*.gjs.spec.ts`.
+import {
+    GIO_RESOURCE_VECTORS,
+    ICON_FIXTURE_PATH,
+    ICON_THEME_RESOURCE_VECTORS,
+    driveGioResourceVectors,
+    driveIconThemeResourceVectors,
+    gioResourceFixtures,
+    type IconThemeResourceSubject,
+} from '@gjsify/adwaita-core/conformance';
+import { describe, expect, it } from '@gjsify/unit';
+
+import { COLOR_ICON_CLASS, type GtkImage } from './elements/gtk-image.js';
+import { resourceIcon } from './icon-theme.js';
+import { GLib, Gio, Gtk } from './index.js';
+
+const theme = Gtk.IconTheme.get_for_display(null);
+
+const iconSubject: IconThemeResourceSubject = {
+    name: 'adwaita-web',
+    isOracle: false,
+    register(data) {
+        const resource = Gio.Resource.new_from_data(data);
+        Gio.resources_register(resource);
+        return () => Gio.resources_unregister(resource);
+    },
+    theme() {
+        theme.set_resource_path([]);
+        return theme;
+    },
+    lookup(_theme, name, size, scale, direction) {
+        const found = resourceIcon(name, { size, scale, direction });
+        if (found === null) return null;
+        if (found.kind === 'resource') return { uri: `resource://${found.path}`, symbolic: found.symbolic };
+        return found.kind === 'symbolic' ? 'theme' : null;
+    },
+};
+
+/** Mounts `<gtk-image>` for each name with the fixture's icons on the theme's resource path. */
+async function withIcons(run: (image: (name: string, size?: number) => GtkImage) => Promise<void> | void) {
+    const resource = Gio.Resource.new_from_data(gioResourceFixtures().icons);
+    Gio.resources_register(resource);
+    const before = theme.get_resource_path();
+    theme.add_resource_path(ICON_FIXTURE_PATH);
+    // `changed` is deferred: let it drop the previous scan's URLs (and their warnings) first.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    const host = document.createElement('div');
+    document.body.append(host);
+    try {
+        await run((name, size) => {
+            const el = document.createElement('gtk-image') as GtkImage;
+            if (size !== undefined) el.setAttribute('size', String(size));
+            el.setAttribute('icon-name', name);
+            host.append(el);
+            return el;
+        });
+    } finally {
+        host.remove();
+        theme.set_resource_path(before);
+        Gio.resources_unregister(resource);
+    }
+}
+
+export const GioResourceTest = async () => {
+    await driveGioResourceVectors(
+        {
+            name: 'adwaita-web',
+            isOracle: false,
+            Gio: Gio as never,
+            bytes: (data) => new GLib.Bytes(data),
+        },
+        { describe, it, expect },
+        GIO_RESOURCE_VECTORS,
+    );
+
+    const before = theme.get_resource_path();
+    try {
+        await driveIconThemeResourceVectors(iconSubject, { describe, it, expect }, ICON_THEME_RESOURCE_VECTORS);
+    } finally {
+        theme.set_resource_path(before);
+    }
+
+    await describe('adwaita-web: <gtk-image> draws resource icons (ADR 0116 § 4)', async () => {
+        await it('draws a symbolic file as an inline mask in currentColor', async () => {
+            await withIcons((image) => {
+                const el = image('sym-symbolic', 16);
+                expect(el.style.getPropertyValue('mask-image').startsWith('url("blob:')).toBe(true);
+                expect(el.style.backgroundColor).toBe('currentcolor');
+                expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            });
+        });
+
+        await it('draws a colour file as-is, without a mask', async () => {
+            await withIcons((image) => {
+                const el = image('flat');
+                expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(true);
+                expect(el.style.backgroundImage.startsWith('url("blob:')).toBe(true);
+                expect(el.style.getPropertyValue('mask-image')).toBe('');
+            });
+        });
+
+        await it('draws image-missing for a file a browser cannot draw', async () => {
+            await withIcons((image) => {
+                const warn = console.warn;
+                const warned: unknown[] = [];
+                console.warn = (...args: unknown[]) => warned.push(args);
+                try {
+                    const el = image('old');
+                    expect(el.classList.contains('adw-icon--image-missing')).toBe(true);
+                    expect(el.style.backgroundImage).toBe('');
+                    expect(warned.length > 0).toBe(true);
+                } finally {
+                    console.warn = warn;
+                }
+            });
+        });
+
+        await it("prefers the current theme's glyph over a resource of the same name", async () => {
+            await withIcons((image) => {
+                const el = image('go-next-symbolic', 16);
+                expect(el.classList.contains('adw-icon--go-next')).toBe(true);
+                expect(el.style.getPropertyValue('mask-image')).toBe('');
+            });
+        });
+
+        await it('clears the inline drawing when the name changes to a theme glyph', async () => {
+            await withIcons((image) => {
+                const el = image('sym-symbolic', 16);
+                el.setAttribute('icon-name', 'go-next-symbolic');
+                expect(el.style.getPropertyValue('mask-image')).toBe('');
+                expect(el.style.backgroundColor).toBe('');
+            });
+        });
+    });
+};

package/src/icon-theme.spec.ts

@@ -4,7 +4,9 @@
 //
 // 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,
+// neither answers draws `image-missing`. Over the names the order is gtkicontheme.c's: the
+// current theme (the stylesheet's glyphs) before hicolor, where a colour registration sits.
+// The registry is module-level and outlives a test,
 // so every case registers names of its own.
 import { describe, expect, it } from '@gjsify/unit';
 
@@ -114,13 +116,16 @@ export const AdwIconThemeTest = async () => {
             host.remove();
         });
 
-        await it('X prefers the colour icon, X-symbolic prefers the symbolic one', () => {
+        await it("the theme's X-symbolic answers X and X-symbolic before the colour X, as on GTK", () => {
             const NAME = 'gjsify-theme-both-probe';
             registerColorIcon(NAME, COLOR_SVG);
             registerIcon(`${NAME}-symbolic`, SYMBOLIC_SVG);
 
+            // gtkicontheme.c `real_choose_icon`: theme outer, name inner, and the colour icon is
+            // hicolor's, so the current theme's `X-symbolic` comes first (ADR 0115 Amendment 2).
             const plain = mount(NAME);
-            expect(drawsInColor(plain.el)).toBe(true);
+            expect(plain.el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            expect(maskOf(plain.el).includes('m%203%203')).toBe(true);
             plain.host.remove();
 
             const symbolic = mount(`${NAME}-symbolic`);

package/src/icon-theme.ts

@@ -23,23 +23,43 @@
 // 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.
 //
+// RESOURCE PATHS (ADR 0116 § 4). The names go through the `Gtk.IconTheme` resource paths an
+// application added (`GtkApplication` adds `<resource-base-path>/icons/` at startup);
+// `@gjsify/adwaita-core`'s `lookupResourceIcon` decides which file answers, as gtkicontheme.c
+// does, and asks this module only whether the stylesheet holds a symbolic glyph. A colour
+// registration stands in hicolor there, as the file an app ships in `hicolor/scalable/apps/`
+// would: the stylesheet's `X-symbolic` answers `X` before it, as Adwaita's does on GNOME. A file
+// answers as a blob URL of its bytes: a symbolic one is drawn as a mask in `currentColor`, the
+// rest as-is. A browser draws SVG and PNG; an XPM or a compressed entry draws `image-missing`
+// with a warning.
+//
 // Original implementation.
 
-import { normalizeIconName } from '@gjsify/adwaita-core';
+import {
+    iconLookupNames,
+    lookupResourceIcon,
+    normalizeIconName,
+    resources_lookup_data,
+    type IconDirection,
+} from '@gjsify/adwaita-core';
 import { toDataUri } from '@gjsify/adwaita-icons/utils';
 
+import { IconTheme } from './namespace/gtk-platform.js';
+
 /** 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 file under a `Gtk.IconTheme` resource path; `symbolic` files are masks in `currentColor`.
+     * `url` is `null` when the browser cannot draw the file (XPM, compressed): draw `image-missing`.
+     */
+    | { kind: 'resource'; name: string; path: string; url: string | null; symbolic: boolean }
     /** 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.
@@ -82,33 +102,97 @@ function hasSymbolic(normalized: string): boolean {
  * 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.
+ * When neither a colour registration nor a resource holds a name, the request is returned as a
+ * symbolic one 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
+ * symbolic glyph and a colour entry or file.
  */
-export function lookupIcon(iconName: string | null | undefined): IconLookup | null {
+export function lookupIcon(iconName: string | null | undefined, request: IconRequest = {}): 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 found = resourceIcon(iconName, request);
+    if (found !== null) return found;
     const symbolic = normalizeIconName(iconName);
+    return symbolic === '' ? { kind: 'missing' } : { kind: 'symbolic', name: symbolic };
+}
 
-    if (color === undefined) {
-        return symbolic === '' ? { kind: 'missing' } : { kind: 'symbolic', name: symbolic };
+/** What a `GtkImage` hands its theme besides the name: its size, scale and text direction. */
+export interface IconRequest {
+    /** In CSS pixels; 16 when absent. */
+    readonly size?: number;
+    /** The device scale; 1 when absent. */
+    readonly scale?: number;
+    readonly direction?: IconDirection;
+}
+
+const theme = IconTheme.get_for_display(null);
+
+/** Blob URLs of resource files, by resource path, for the current scan. */
+const resourceUrls = new Map<string, string | null>();
+
+theme.connect('changed', () => {
+    for (const url of resourceUrls.values()) if (url !== null) URL.revokeObjectURL(url);
+    resourceUrls.clear();
+    notifyIconThemeChanged();
+});
+
+const RESOURCE_TYPES: Record<string, string> = { '.svg': 'image/svg+xml', '.png': 'image/png' };
+
+/** The file at `path` as a URL a browser draws, or `null` (warned once) when it cannot. */
+function resourceUrl(path: string): string | null {
+    const cached = resourceUrls.get(path);
+    if (cached !== undefined) return cached;
+    let url: string | null = null;
+    const type = RESOURCE_TYPES[path.slice(path.lastIndexOf('.'))];
+    if (type === undefined) {
+        console.warn(`Gtk.IconTheme: ${path} is not an SVG or a PNG, which is all a browser draws (ADR 0116 § 4).`);
+    } else {
+        try {
+            const data = resources_lookup_data(path, 0).get_data();
+            url = URL.createObjectURL(new Blob([data as Uint8Array<ArrayBuffer>], { type }));
+        } catch (error) {
+            console.warn(`Gtk.IconTheme: ${path} cannot be drawn: ${(error as Error).message}`);
+        }
     }
-    if (symbolicRequest && hasSymbolic(symbolic)) return { kind: 'symbolic', name: symbolic };
-    return { kind: 'color', name: colorName, url: color };
+    resourceUrls.set(path, url);
+    return url;
+}
+
+/**
+ * The lookup over the colour registrations and the theme's resource paths; `null` when neither
+ * answers any name, a `symbolic` entry when the current theme's glyph comes first.
+ */
+export function resourceIcon(iconName: string, request: IconRequest): IconLookup | null {
+    const match = lookupResourceIcon(theme, {
+        names: iconLookupNames(iconName, request.direction ?? null),
+        get size() {
+            return request.size ?? 16;
+        },
+        scale: request.scale ?? 1,
+        themeHas: (name) => hasSymbolic(normalizeIconName(name)),
+        hicolorHas: (name) => colorIcons.has(name),
+    });
+    if (match === null) return null;
+    if (match.kind === 'theme') return { kind: 'symbolic', name: normalizeIconName(match.name) };
+    if (match.kind === 'hicolor') return { kind: 'color', name: match.name, url: colorIcons.get(match.name)! };
+    return {
+        kind: 'resource',
+        name: match.name,
+        path: match.path,
+        url: resourceUrl(match.path),
+        symbolic: match.symbolic,
+    };
 }
 
 /**
  * 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.
+ * icon, a file under a resource path, 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;
+    if (found.kind === 'resource') return found.url !== null;
     return found.kind === 'color' || hasSymbolic(found.name);
 }
 

package/src/namespace/gio.ts

@@ -35,5 +35,15 @@ export {
     promisify as _promisify,
 } from '@gjsify/adwaita-core';
 export { SimpleAction, SimpleActionGroup, ApplicationFlags } from '@gjsify/adwaita-core';
+export {
+    GioResource as Resource,
+    ResourceError,
+    ResourceLookupFlags,
+    resources_enumerate_children,
+    resources_get_info,
+    resources_lookup_data,
+    resources_register,
+    resources_unregister,
+} from '@gjsify/adwaita-core';
 export { GioApplication as Application } from '../application.js';
 export { Settings } from '@gjsify/app-settings/browser';

package/src/test.browser.mts

@@ -67,6 +67,7 @@ import { AdwButtonContentTest } from './adw-button-content.spec.js';
 import { GtkImageTest } from './gtk-image.spec.js';
 import { AdwIconRegistryTest } from './icon-registry.spec.js';
 import { AdwIconThemeTest } from './icon-theme.spec.js';
+import { GioResourceTest } from './gio-resource.spec.js';
 import { GtkSwitchTest } from './gtk-switch.spec.js';
 import { AdwChecksTest } from './checks.spec.js';
 import { GtkProgressBarTest } from './gtk-progress-bar.spec.js';
@@ -202,6 +203,7 @@ run({
     GtkImageTest,
     AdwIconRegistryTest,
     AdwIconThemeTest,
+    GioResourceTest,
     GtkSwitchTest,
     AdwChecksTest,
     GtkProgressBarTest,