@gjsify/adwaita-web 0.54.0 → 0.55.0

package/src/gtk-font-dialog-button.spec.ts

@@ -0,0 +1,166 @@
+// DOM-level tests for <gtk-font-dialog-button>. The label rules are GTK's and each is
+// separate: at `family` it is one word, at `font` it is family plus size, the size box is
+// gone below `font`, and `use-font` draws the family label in the selected font — with the
+// size only when `use-size` says so.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkFontDialogButton } from './elements/gtk-font-dialog-button.js';
+
+function mount(attrs: Record<string, string> = {}): {
+    el: GtkFontDialogButton;
+    host: HTMLElement;
+    label: HTMLElement;
+    sizeBox: HTMLElement;
+    sizeLabel: HTMLElement;
+    button: HTMLButtonElement;
+} {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-font-dialog-button') as GtkFontDialogButton;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return {
+        el,
+        host,
+        label: el.querySelector('.font-button-label') as HTMLElement,
+        sizeBox: el.querySelector('.font-button-size') as HTMLElement,
+        sizeLabel: el.querySelector('.font-button-size-label') as HTMLElement,
+        button: el.querySelector('button') as HTMLButtonElement,
+    };
+}
+
+export const GtkFontDialogButtonTest = async () => {
+    await describe('<gtk-font-dialog-button> defaults', async () => {
+        await it('opens on "Sans 12", the description init builds', () => {
+            const { el, host, label, sizeLabel } = mount();
+            expect(el.fontDesc.family).toBe('Sans');
+            expect(el.fontDesc.size).toBe(12);
+            expect(label.textContent).toBe('Sans');
+            expect(sizeLabel.textContent).toBe('12');
+            host.remove();
+        });
+
+        await it('is at level font, so the size box is showing', () => {
+            const { el, host, sizeBox } = mount();
+            expect(el.level).toBe('font');
+            expect(sizeBox.hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('is insensitive until a dialog is set', () => {
+            const { el, host, button } = mount();
+            expect(button.disabled).toBe(true);
+            el.dialog = {};
+            expect(button.disabled).toBe(false);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-font-dialog-button> font-desc', async () => {
+        await it('parses Pango’s own string form, styles in any order', () => {
+            const { el, host } = mount({ 'font-desc': 'Cantarell Bold Italic 14' });
+            expect(el.fontDesc.family).toBe('Cantarell');
+            expect(el.fontDesc.weight).toBe(700);
+            expect(el.fontDesc.slant).toBe('italic');
+            expect(el.fontDesc.size).toBe(14);
+            host.remove();
+        });
+
+        await it('remembers a size written in pixels, and prints the unit back', () => {
+            const { el, host, sizeLabel } = mount({ 'font-desc': 'Cantarell 18px' });
+            expect(el.fontDesc.absolute).toBe(true);
+            expect(sizeLabel.textContent).toBe('18px');
+            host.remove();
+        });
+
+        await it('a write of the description already held notifies nothing', () => {
+            const { el, host } = mount({ 'font-desc': 'Sans 12' });
+            const notified: unknown[] = [];
+            el.addEventListener('notify::font-desc', (e) => notified.push((e as CustomEvent).detail));
+            el.fontDesc = 'Sans 12';
+            expect(notified.length).toBe(0);
+            el.fontDesc = 'Sans 14';
+            expect(notified.length).toBe(1);
+            host.remove();
+        });
+
+        await it('a family that was never set reads as the C’s "None"', () => {
+            const { el, host, label } = mount();
+            el.fontDesc = '12';
+            expect(el.fontDesc.family).toBe('');
+            expect(label.textContent).toBe('None');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-font-dialog-button> level', async () => {
+        await it('at family the label is the family alone and the size box is gone', () => {
+            const { host, label, sizeBox } = mount({ level: 'family', 'font-desc': 'Cantarell 14' });
+            expect(label.textContent).toBe('Cantarell');
+            expect(sizeBox.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('at face the size box is gone but the style words are in the label', () => {
+            const { el, host, label, sizeBox } = mount();
+            el.fontDesc = 'Cantarell Bold 12';
+            el.level = 'face';
+            expect(sizeBox.hidden).toBe(true);
+            expect(label.textContent).toBe('Cantarell Bold');
+            host.remove();
+        });
+
+        await it('an unknown level is the default, as an unknown orientation is horizontal', () => {
+            const { el, host } = mount();
+            el.setAttribute('level', 'glyph');
+            expect(el.level).toBe('font');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-font-dialog-button> use-font', async () => {
+        await it('draws the label in the selected font, without the size unless asked', () => {
+            const { el, host, label } = mount({ 'font-desc': 'Cantarell Bold 14' });
+            expect(label.style.fontFamily).toBe('');
+            el.useFont = true;
+            expect(label.style.fontWeight).toBe('700');
+            expect(label.style.fontFamily).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;
+            // `pt`, not a bare `14`: Pango's string carries no unit and a CSS length
+            // rejects one that does not, so the projection names the unit Pango means.
+            expect(label.style.fontSize).toBe('14pt');
+            el.useFont = false;
+            expect(label.style.fontFamily).toBe('');
+            host.remove();
+        });
+
+        await it('keeps a size written in pixels in pixels', () => {
+            const { host, label } = mount({ 'font-desc': 'Cantarell 18px', 'use-font': '', 'use-size': '' });
+            expect(label.style.fontSize).toBe('18px');
+            host.remove();
+        });
+
+        await it('carries font-features and language into the label with it', () => {
+            const { el, host, label } = mount({ 'font-desc': 'Cantarell 12', 'use-font': '', 'use-size': '' });
+            el.fontFeatures = 'liga';
+            el.language = 'de-de';
+            // CSS wants each tag quoted, which is the whole translation Pango's list needs.
+            expect(label.style.fontFeatureSettings).toBe('"liga"');
+            expect(label.lang).toBe('de-de');
+            host.remove();
+        });
+
+        await it('keeps the tags a browser knows and drops the ones it does not', () => {
+            const { el, host, label } = mount({ 'font-desc': 'Cantarell 12', 'use-font': '', 'use-size': '' });
+            // A `font-feature-settings` value is dropped WHOLE when any tag in it is unknown
+            // (measured in Firefox: `"liga", "-kern"` stands for nothing, `"liga"` alone
+            // does). So the tags are applied one at a time, and one rejection costs one
+            // feature rather than all of them.
+            el.fontFeatures = 'liga, -kern';
+            expect(label.style.fontFeatureSettings).toBe('"liga"');
+            host.remove();
+        });
+    });
+};

package/src/gtk-frame.spec.ts

@@ -0,0 +1,119 @@
+// DOM-level tests for <gtk-frame>: the label is a `<gtk-label>` the element builds from
+// the `label` STRING (which is what `gtk_frame_set_label()` does), it is the frame's FIRST
+// child (GTK stacks it above the child), and `label-xalign` is the label's `align-self`.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkFrame } from './elements/gtk-frame.js';
+
+function mount(attrs: Record<string, string> = {}, body = ''): { el: GtkFrame; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-frame') as GtkFrame;
+    // Children BEFORE attributes, which is the order the HTML parser sets them in for a
+    // custom element: the attribute fires the build while the label is the only child, and
+    // the author's own child lands after it.
+    if (body !== '') el.innerHTML = body;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** The label widget the frame is currently showing, or null. */
+const labelWidget = (el: GtkFrame) => (el.labelWidget as HTMLElement | null) ?? null;
+
+/** One macrotask, which is after the MutationObserver microtask the element repairs in. */
+const settle = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+export const GtkFrameTest = async () => {
+    await describe('<gtk-frame> label', async () => {
+        await it('builds a gtk-label from the label string and puts it first', () => {
+            const { el, host } = mount({ label: 'Details' }, '<gtk-label label="Body"></gtk-label>');
+            const label = labelWidget(el);
+            expect(label?.tagName.toLowerCase()).toBe('gtk-label');
+            expect(label?.getAttribute('label')).toBe('Details');
+            expect(el.firstElementChild).toBe(label);
+            expect(el.lastElementChild?.getAttribute('label')).toBe('Body');
+            host.remove();
+        });
+
+        await it('removes the label when the string goes, and rebuilds it when it returns', () => {
+            const { el, host } = mount({ label: 'Details' }, '<gtk-label label="Body"></gtk-label>');
+            el.removeAttribute('label');
+            expect(labelWidget(el)).toBe(null);
+            expect(el.children.length).toBe(1);
+            el.setAttribute('label', 'Again');
+            expect(el.firstElementChild?.getAttribute('label')).toBe('Again');
+            host.remove();
+        });
+
+        await it('an authored label-widget wins over the string, and keeps its place', () => {
+            const { el, host } = mount(
+                { label: 'Ignored' },
+                '<gtk-label slot="label-widget" label="Authored"></gtk-label><gtk-label label="Body"></gtk-label>',
+            );
+            const label = labelWidget(el);
+            expect(label?.getAttribute('label')).toBe('Authored');
+            expect(el.firstElementChild).toBe(label);
+            expect(label?.classList.contains('adw-frame-label')).toBe(true);
+            host.remove();
+        });
+
+        await it('the label-xalign is a fraction, and reaches the label as align-self', () => {
+            const { el, host } = mount({ label: 'Details' }, '<gtk-label label="Body"></gtk-label>');
+            expect(el.labelXalign).toBe(0);
+            expect(labelWidget(el)?.style.alignSelf).toBe('flex-start');
+            el.setAttribute('label-xalign', '0.5');
+            expect(el.labelXalign).toBe(0.5);
+            expect(labelWidget(el)?.style.alignSelf).toBe('center');
+            // Out of range lands on the nearer end, which is what the pspec's 0…1 clamp is.
+            el.setAttribute('label-xalign', '4');
+            expect(el.labelXalign).toBe(1);
+            expect(labelWidget(el)?.style.alignSelf).toBe('flex-end');
+            el.setAttribute('label-xalign', 'diagonal');
+            expect(el.labelXalign).toBe(0);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-frame> surface', async () => {
+        await it("is a group, and carries libadwaita's 1px border and card radius", () => {
+            const { el, host } = mount();
+            expect(el.getAttribute('role')).toBe('group');
+            const style = getComputedStyle(el);
+            expect(style.borderTopWidth).toBe('1px');
+            expect(style.borderTopStyle).toBe('solid');
+            expect(style.overflow).toBe('hidden');
+            host.remove();
+        });
+
+        await it('notifies on a real change and on none that did not happen', () => {
+            const { el, host } = mount({ label: 'One' });
+            const notified: unknown[] = [];
+            el.addEventListener('notify::label', (event) => notified.push((event as CustomEvent).detail));
+            el.label = 'Two';
+            el.label = 'Two';
+            expect(notified).toStrictEqual([{ label: 'Two' }]);
+            host.remove();
+        });
+
+        await it('an author who replaces the children gets the label back', async () => {
+            const { el, host } = mount({ label: 'Details' }, '<gtk-label label="Body"></gtk-label>');
+            el.innerHTML = '<gtk-label label="New body"></gtk-label>';
+            await settle();
+            expect(el.firstElementChild?.getAttribute('label')).toBe('Details');
+            expect(el.lastElementChild?.getAttribute('label')).toBe('New body');
+            host.remove();
+        });
+
+        await it('survives a re-parent without doubling the label', () => {
+            const { el, host } = mount({ label: 'Details' }, '<gtk-label label="Body"></gtk-label>');
+            const other = document.createElement('div');
+            document.body.appendChild(other);
+            other.appendChild(el);
+            expect(el.querySelectorAll('gtk-label').length).toBe(2);
+            expect(el.firstElementChild?.getAttribute('label')).toBe('Details');
+            other.remove();
+            host.remove();
+        });
+    });
+};

package/src/gtk-gl-area.spec.ts

@@ -0,0 +1,361 @@
+// DOM-level tests for <gtk-gl-area>. What is worth pinning here is the ORDER the C's
+// snapshot runs in and the two flags it clears — a GL application that gets `::render`
+// before the first `::resize` draws into a viewport nobody told it about, and a flag
+// cleared too early loses the frame `queue_render()` asked for from inside `::render`.
+//
+// Every signal the C emits needs a context (`gtkglarea.c:781-782` returns before
+// `::resize` without one), so these tests bring their own through `::create-context`.
+// Whether the BROWSER can hand out WebGL is a property of the machine — headless
+// Firefox says no — and a test that rests on it reports the machine, not the element.
+// See `stubContext`.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkGLArea } from './elements/gtk-gl-area.js';
+
+/**
+ * A context that remembers what was switched on, because that is the whole surface the
+ * element touches (`attachBuffers` and the snapshot call `enable`/`disable`; `isEnabled`
+ * is how a test reads the result back) plus the two capability names it passes them.
+ *
+ * WHY A STUB AND NOT THE BROWSER'S OWN: `gtk_gl_area_render` returns at
+ * `if (priv->context == NULL)` BEFORE it emits `::resize` (gtkglarea.c:781-782), so
+ * every signal below depends on a context existing. Chromium hands one out from
+ * software GL on a headless runner; Firefox does not, and then every test that waits
+ * for a signal waits forever and reports an empty list. That is a fact about the
+ * machine, not about the element — so a test may not rest on it. `::create-context`
+ * is the documented way in (gtkglarea.c:1086-1109; the element reads `detail.context`
+ * and asks the canvas only when nobody supplied one), which is what this uses.
+ */
+function stubContext(): WebGLRenderingContext {
+    const enabled = new Set<number>();
+    return {
+        DEPTH_TEST: 0x0b71,
+        STENCIL_TEST: 0x0b90,
+        enable: (capability: number) => void enabled.add(capability),
+        disable: (capability: number) => void enabled.delete(capability),
+        isEnabled: (capability: number) => enabled.has(capability),
+    } as unknown as WebGLRenderingContext;
+}
+
+/**
+ * `context: 'stub'` (the default) gives the element a context of its own, so a test
+ * measures the element. `'canvas'` leaves the browser to answer — only the test that is
+ * ABOUT the canvas path uses it, and it asks through a recording stub. `'none'` is for
+ * the tests that bring their own `create-context` handler.
+ */
+function mount(
+    attrs: Record<string, string> = {},
+    context: 'stub' | 'canvas' | 'none' = 'stub',
+): { el: GtkGLArea; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-gl-area') as GtkGLArea;
+    el.style.width = '120px';
+    el.style.height = '90px';
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    // Before the element is in the tree: the handler is read on the first draw, and the
+    // first draw needs an observer record, so it must not be attached after insertion.
+    if (context === 'stub') {
+        el.addEventListener('create-context', (event) => {
+            (event as CustomEvent).detail['context'] = stubContext();
+        });
+    }
+    host.appendChild(el);
+    return { el, host };
+}
+
+/**
+ * Three frames, and the order is the reason: the element draws in an animation frame
+ * that a `ResizeObserver` record schedules, and the platform delivers that record
+ * AFTER the animation-frame callbacks of the frame it belongs to — so the draw lands in
+ * the frame after the one that observed. Two is what Chromium happens to need, and the
+ * count is not a property of the element.
+ */
+function settled(): Promise<void> {
+    return new Promise((resolve) => {
+        let frames = 0;
+        const tick = (): void => {
+            frames += 1;
+            if (frames >= 3) resolve();
+            else requestAnimationFrame(tick);
+        };
+        requestAnimationFrame(tick);
+    });
+}
+
+export const GtkGLAreaTest = async () => {
+    await describe('<gtk-gl-area> defaults', async () => {
+        await it('starts with the GIR defaults and needs_render already set', () => {
+            // gtkglarea.c:1101-1105 — auto_render TRUE, needs_render TRUE, allowed APIs
+            // `GDK_GL_API_GL | GDK_GL_API_GLES`.
+            const { el, host } = mount();
+            expect(el.autoRender).toBe(true);
+            expect(el.hasDepthBuffer).toBe(false);
+            expect(el.hasStencilBuffer).toBe(false);
+            expect(el.allowedApis).toStrictEqual(['gl', 'gles']);
+            expect(el.context).toBe(null);
+            expect(el.error).toBe(null);
+            // `get_api` reads 0 — GDK_GL_API_GL — until a context exists.
+            expect(el.api).toBe('gl');
+            host.remove();
+        });
+
+        await it('reads allowed-apis as a SET of nicks', () => {
+            // g_param_spec_flags ("allowed-apis", …) at :983.
+            const { el, host } = mount({ 'allowed-apis': 'gles' });
+            expect(el.allowedApis).toStrictEqual(['gles']);
+            el.allowedApis = ['gl'];
+            expect(el.allowedApis).toStrictEqual(['gl']);
+            el.allowedApis = ['gl', 'gles'];
+            expect(el.allowedApis).toStrictEqual(['gl', 'gles']);
+            host.remove();
+        });
+
+        await it('notifies only on a real change', () => {
+            const { el, host } = mount();
+            const seen: unknown[] = [];
+            el.addEventListener('notify::auto-render', (event) =>
+                seen.push((event as CustomEvent).detail['auto-render']),
+            );
+            el.autoRender = true;
+            expect(seen).toStrictEqual([]);
+            el.autoRender = false;
+            expect(seen).toStrictEqual([false]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-gl-area> the snapshot order', async () => {
+        await it('emits resize before the first render', async () => {
+            // gtkglarea.c:797-807 — the order is the whole point of `needs_resize`.
+            const { el, host } = mount();
+            const order: string[] = [];
+            el.addEventListener('resize', () => order.push('resize'));
+            el.addEventListener('render', () => order.push('render'));
+            await settled();
+            expect(order).toStrictEqual(['resize', 'render']);
+            host.remove();
+        });
+
+        await it('hands the resize signal the DEVICE-pixel viewport', async () => {
+            // gtkglarea.c:761-763 — `w = gtk_widget_get_width (widget) * scale`.
+            const { el, host } = mount();
+            const seen: { width: number; height: number }[] = [];
+            el.addEventListener('resize', (event) =>
+                seen.push((event as unknown as CustomEvent<{ width: number; height: number }>).detail),
+            );
+            await settled();
+            const scale = el.pixelScale;
+            expect(seen[0].width).toBe(Math.round(120 * scale));
+            expect(seen[0].height).toBe(Math.round(90 * scale));
+            expect(el.viewport).toStrictEqual({ width: Math.round(120 * scale), height: Math.round(90 * scale) });
+            host.remove();
+        });
+
+        await it('emits resize again only when the allocation changed', async () => {
+            const { el, host } = mount();
+            let resizes = 0;
+            el.addEventListener('resize', () => {
+                resizes += 1;
+            });
+            await settled();
+            const first = resizes;
+            el.queueRender();
+            expect(resizes).toBe(first);
+            el.style.width = '160px';
+            await settled();
+            expect(resizes).toBe(first + 1);
+            host.remove();
+        });
+
+        await it('clears needs_render AFTER the signal, so a queue inside it stacks nothing', async () => {
+            // gtkglarea.c:800-811 — `priv->needs_render = FALSE` comes AFTER the emit, so
+            // a `queue_render()` from a handler has its flag overwritten: the frame is
+            // queued, the flag is not. With auto-render off that is ONE render and no
+            // runaway — which is also why a GL animation asks per tick rather than from
+            // inside `::render`.
+            const { el, host } = mount({ 'auto-render': 'false' });
+            let renders = 0;
+            const onRender = () => {
+                renders += 1;
+                el.queueRender();
+            };
+            el.addEventListener('render', onRender);
+            await settled();
+            expect(renders).toBe(1);
+            el.removeEventListener('render', onRender);
+            host.remove();
+        });
+
+        await it('emits no render with auto_render off, until something queues one', async () => {
+            // gtkglarea.c:800 — `if (priv->needs_render || priv->auto_render)`.
+            const { el, host } = mount({ 'auto-render': 'false' });
+            let renders = 0;
+            el.addEventListener('render', () => {
+                renders += 1;
+            });
+            await settled();
+            const first = renders;
+            el.queueRender();
+            await settled();
+            expect(renders).toBe(first + 1);
+            host.remove();
+        });
+
+        await it('draws nothing at an empty allocation', async () => {
+            // gtkglarea.c:767-768 — `if (w == 0 || h == 0) return;`.
+            const { el, host } = mount();
+            let renders = 0;
+            el.addEventListener('render', () => {
+                renders += 1;
+            });
+            await settled();
+            const seen = renders;
+            el.style.width = '0px';
+            el.queueRender();
+            expect(renders).toBe(seen);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-gl-area> the context', async () => {
+        await it('is created from the canvas, newest API first, and never desktop GL', async () => {
+            // The subject is WHERE the context comes from and in what order the element
+            // asks for it. It is not whether this browser implements GL: a real
+            // `getContext('webgl2')` on the headless Firefox runner returns null, which
+            // would say nothing about the element. So the canvas answers through a
+            // recording stub, and the two facts the old assertion could not check — the
+            // order, and that `gl` is never asked for — come out with it.
+            const { el, host } = mount({}, 'canvas');
+            const asked: string[] = [];
+            const canvas = el.querySelector('canvas') as HTMLCanvasElement;
+            // `null` for `webgl2` on purpose: the element stops at the FIRST name the
+            // browser answers, so a stub that answered both would record `webgl2` alone
+            // and the order would be untested. Refusing the newer name is what puts the
+            // fallback — and with it the order — in front of the assertion.
+            canvas.getContext = ((name: string) => {
+                asked.push(name);
+                if (name === 'webgl2') return null;
+                return { enable() {}, disable() {} };
+            }) as unknown as HTMLCanvasElement['getContext'];
+            await settled();
+            expect(asked).toStrictEqual(['webgl2', 'webgl']);
+            expect(el.api).toBe('gles');
+            host.remove();
+        });
+
+        await it('is not created when allowed-apis names neither API', async () => {
+            // The no-context branch of the snapshot (:776-777) — nothing is drawn.
+            const { el, host } = mount({ 'allowed-apis': '' });
+            let renders = 0;
+            el.addEventListener('render', () => {
+                renders += 1;
+            });
+            await settled();
+            expect(el.context).toBe(null);
+            expect(renders).toBe(0);
+            host.remove();
+        });
+
+        await it('takes the context a create-context handler supplied', async () => {
+            // gtkglarea.c:1086-1109 — a handler RETURNS the context; a browser event has
+            // no return channel, so the detail object carries it (see the header).
+            const { el, host } = mount({}, 'none');
+            const spare = {
+                DEPTH_TEST: 1,
+                STENCIL_TEST: 2,
+                enable() {},
+                disable() {},
+            } as unknown as WebGLRenderingContext;
+            let detail: { context: unknown } | null = null;
+            el.addEventListener('create-context', (event) => {
+                detail = (event as CustomEvent).detail as { context: unknown };
+                detail.context = spare;
+            });
+            await settled();
+            expect(detail).not.toBe(null);
+            // A stub is what the handler put there; the element uses it as given, which is
+            // what the C does with a handler's context. It carries the two calls every draw
+            // makes, because an object without them throws out of the next frame.
+            expect(el.context).toBe(spare);
+            host.remove();
+        });
+
+        await it('refuses a changed allowed-apis once the area is realized', async () => {
+            // gtkglarea.c:1242 — `g_return_if_fail (!gtk_widget_get_realized (…))`. The
+            // context is built from the set once, so a later write is undone: the attribute
+            // goes back to the set in force and nothing notifies (the C only warns).
+            const { el, host } = mount();
+            await settled();
+            expect(el.context).not.toBe(null);
+            const notified: string[] = [];
+            el.addEventListener('notify::allowed-apis', () => notified.push('notify'));
+            el.allowedApis = ['gl'];
+            expect(el.allowedApis).toStrictEqual(['gl', 'gles']);
+            expect(el.getAttribute('allowed-apis')).toBe('gl gles');
+            expect(notified).toStrictEqual([]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-gl-area> buffers and errors', async () => {
+        await it('enables the depth test only when the depth buffer is asked for', async () => {
+            // gtkglarea.c:782-785 — `glEnable`/`glDisable (GL_DEPTH_TEST)`, in the SNAPSHOT,
+            // not in `attach_buffers`. Neither buffer setter queues a redraw (:1391-1396), so
+            // the application asks for the frame that applies it — exactly as it would in GTK.
+            const { el, host } = mount();
+            await settled();
+            const context = el.context;
+            expect(context).not.toBe(null);
+            expect(context?.isEnabled((context as WebGLRenderingContext).DEPTH_TEST)).toBe(false);
+            el.hasDepthBuffer = true;
+            el.queueRender();
+            await settled();
+            expect(context?.isEnabled((context as WebGLRenderingContext).DEPTH_TEST)).toBe(true);
+            host.remove();
+        });
+
+        await it('attaches the stencil buffer when asked for, through attach_buffers', async () => {
+            // gtkglarea.c:583-618 — the renderbuffer the two setters drop `have_buffers` for.
+            const { el, host } = mount();
+            await settled();
+            const context = el.context as WebGLRenderingContext;
+            el.hasStencilBuffer = true;
+            el.attachBuffers(context);
+            expect(context.isEnabled(context.STENCIL_TEST)).toBe(true);
+            el.hasStencilBuffer = false;
+            el.attachBuffers(context);
+            expect(context.isEnabled(context.STENCIL_TEST)).toBe(false);
+            host.remove();
+        });
+
+        await it('shows the error message over the widget and draws nothing', async () => {
+            // gtkglarea.c:769-775 and `gtk_gl_area_draw_error_screen` at :701-723.
+            const { el, host } = mount();
+            let renders = 0;
+            el.addEventListener('render', () => {
+                renders += 1;
+            });
+            await settled();
+            const seen = renders;
+            el.setError('could not create GL context');
+            await settled();
+            expect(el.error).toBe('could not create GL context');
+            expect(el.querySelector('.adw-gl-area-error')?.textContent).toBe('could not create GL context');
+            expect(renders).toBe(seen);
+            // The canvas is still there: GTK replaces a frame's contents, not the node.
+            expect(el.querySelector('canvas')).not.toBe(null);
+            host.remove();
+        });
+
+        await it('takes an Error as readily as its message, and clears on null', () => {
+            const { el, host } = mount();
+            el.setError(new Error('GL error'));
+            expect(el.error).toBe('GL error');
+            el.setError(null);
+            expect(el.error).toBe(null);
+            expect(el.querySelector('.adw-gl-area-error')).toBe(null);
+            host.remove();
+        });
+    });
+};