@gjsify/adwaita-web 0.54.0 → 0.55.0

package/src/gtk-video.spec.ts

@@ -0,0 +1,240 @@
+// DOM-level tests for <gtk-video>. What matters is the OVERLAY ICON, because it is the only
+// part of this widget with logic in it: `gtk_video_update_overlay_icon` is a four-way choice
+// whose ORDER carries meaning (no stream before error, error before ended), and
+// `gtk_video_update_playing` hides the icon by VISIBILITY rather than swapping it for a pause
+// glyph. Both are asserted here against the arm they come from.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkVideo } from './elements/gtk-video.js';
+
+/** A `<video>` with no `src`: no stream to report, so every media event is synthetic here. */
+function mount(withMedia: boolean, attrs: Record<string, string> = {}): { el: GtkVideo; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-video') as GtkVideo;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    if (withMedia) el.appendChild(document.createElement('video'));
+    host.appendChild(el);
+    return { el, host };
+}
+
+function overlayIcon(el: GtkVideo): string | null {
+    return el.querySelector('.adw-video-overlay-icon gtk-image')?.getAttribute('icon-name') ?? null;
+}
+
+export const GtkVideoTest = async () => {
+    await describe('<gtk-video> the four-way overlay icon', async () => {
+        await it('draws the EJECT glyph with no media stream at all', () => {
+            // gtkvideo.c:629 — the no-stream arm is FIRST, not the fallback, so an element
+            // that has not been given a `<video>` shows "there is nothing here to play"
+            // rather than a play glyph over nothing.
+            const { el, host } = mount(false);
+            expect(el.media).toBe(null);
+            expect(overlayIcon(el)).toBe('media-eject-symbolic');
+            host.remove();
+        });
+
+        await it('draws the PLAY glyph once a stream is present and healthy', () => {
+            // gtkvideo.c:645 — the last arm, reached only with a stream, no error, not ended.
+            const { el, host } = mount(true);
+            expect(overlayIcon(el)).toBe('media-playback-start-symbolic');
+            host.remove();
+        });
+
+        await it('draws the ERROR glyph and takes the message as its tooltip', () => {
+            // gtkvideo.c:633-643 — the error arm also sets the tooltip to `error->message`,
+            // which is the only place this widget carries text that is not an accessible name.
+            const { el, host } = mount(true);
+            const media = el.media!;
+            Object.defineProperty(media, 'error', { value: { message: 'no such stream' }, configurable: true });
+            media.dispatchEvent(new Event('error'));
+            expect(overlayIcon(el)).toBe('dialog-error-symbolic');
+            const button = el.querySelector('.adw-video-overlay-icon') as HTMLButtonElement;
+            expect(button.title).toBe('no such stream');
+            host.remove();
+        });
+
+        await it('draws the REPEAT glyph once the stream has ended', () => {
+            // gtkvideo.c:638-639 — the ended arm.
+            const { el, host } = mount(true);
+            el.media!.dispatchEvent(new Event('ended'));
+            expect(overlayIcon(el)).toBe('media-playlist-repeat-symbolic');
+            host.remove();
+        });
+
+        await it('prefers ERROR over ENDED, which is what the arm order says', () => {
+            // gtkvideo.c:632-638 — the error test comes first, so a stream that both failed and
+            // ended shows the error. Asserting the reverse would pass on a port that swapped
+            // the two arms.
+            const { el, host } = mount(true);
+            const media = el.media!;
+            media.dispatchEvent(new Event('ended'));
+            Object.defineProperty(media, 'error', { value: { message: 'boom' }, configurable: true });
+            media.dispatchEvent(new Event('error'));
+            expect(overlayIcon(el)).toBe('dialog-error-symbolic');
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-video> the overlay is hidden while playing', async () => {
+        await it('a play HIDES the icon and a pause shows it, both by visibility', () => {
+            // gtkvideo.c:665 — `gtk_widget_set_visible (self->overlay_icon, !playing)`. There
+            // is no pause glyph in the overlay: the controls bar carries the pause button, and
+            // a playing video shows the frames and nothing on top of them.
+            const { el, host } = mount(true);
+            const button = el.querySelector('.adw-video-overlay-icon') as HTMLButtonElement;
+            expect(button.hidden).toBe(false);
+            el.media!.dispatchEvent(new Event('play'));
+            expect(button.hidden).toBe(true);
+            expect(el.classList.contains('playing')).toBe(true);
+            el.media!.dispatchEvent(new Event('pause'));
+            expect(button.hidden).toBe(false);
+            expect(el.classList.contains('playing')).toBe(false);
+            host.remove();
+        });
+
+        await it("keeps the icon's GLYPH across the hide — it is not swapped for a pause", () => {
+            const { el, host } = mount(true);
+            el.media!.dispatchEvent(new Event('play'));
+            expect(overlayIcon(el)).toBe('media-playback-start-symbolic');
+            host.remove();
+        });
+
+        await it('announces playing as its own notify, which the C does not', () => {
+            const { el, host } = mount(true);
+            const events: unknown[] = [];
+            el.addEventListener('notify::playing', (e) => events.push((e as CustomEvent).detail));
+            el.media!.dispatchEvent(new Event('play'));
+            el.media!.dispatchEvent(new Event('pause'));
+            expect(events).toStrictEqual([{ playing: true }, { playing: false }]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-video> the properties', async () => {
+        await it('autoplay and loop default to FALSE and apply to the media element', () => {
+            // ui/gtkvideo.ui's `<property name="enabled">disabled</property>` on the
+            // graphics offload is the same shape: the template starts the widget off.
+            const { el, host } = mount(true);
+            expect(el.autoplay).toBe(false);
+            expect(el.loop).toBe(false);
+            expect(el.media!.loop).toBe(false);
+            el.loop = true;
+            expect(el.media!.loop).toBe(true);
+            host.remove();
+        });
+
+        await it('NEVER gives the media element an autoplay attribute of its own', () => {
+            // The C's `autoplay` is not the element's autoplay attribute: it plays when the
+            // stream reports `prepared` AND the widget is mapped (gtkvideo.c:684-690), and
+            // the readiness gate is bound separately. Handing `<video>` an autoplay attribute
+            // would bypass the second condition entirely.
+            const { el, host } = mount(true, { autoplay: '' });
+            expect(el.autoplay).toBe(true);
+            expect(el.media!.autoplay).toBe(false);
+            host.remove();
+        });
+
+        await it('plays on readiness, not on the property write', () => {
+            const { el, host } = mount(true, { autoplay: '' });
+            const media = el.media!;
+            let played = false;
+            media.play = () => {
+                played = true;
+                return Promise.resolve();
+            };
+            expect(played).toBe(false);
+            media.dispatchEvent(new Event('loadeddata'));
+            expect(played).toBe(true);
+            host.remove();
+        });
+
+        await it('graphics-offload is stored and class-flagged, and buys no rendering', () => {
+            // `GtkGraphicsOffload` moves a subtree into a shared GL texture; CSS has no such
+            // mechanism. The property is observed faithfully — that is what the
+            // element-properties ratchet measures — and the class is deliberately unstyled.
+            const { el, host } = mount(true);
+            expect(el.graphicsOffload).toBe(false);
+            el.graphicsOffload = true;
+            expect(el.hasAttribute('graphics-offload')).toBe(true);
+            expect(el.classList.contains('graphics-offload')).toBe(true);
+            host.remove();
+        });
+
+        await it('notifies once per real change', () => {
+            const { el, host } = mount(true);
+            const events: unknown[] = [];
+            el.addEventListener('notify::loop', (e) => events.push((e as CustomEvent).detail));
+            el.loop = true;
+            el.loop = true;
+            el.loop = false;
+            expect(events).toStrictEqual([{ loop: true }, { loop: false }]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-video> the controls reveal', async () => {
+        await it('is hidden until revealControls() and stays out of the way while so', async () => {
+            // ui/gtkvideo.ui's `controls_revealer` has `measure` 1, so the bar is allocated
+            // even while hidden — which is why this is an opacity transition and not
+            // `display: none`, and why the revealer keeps its box.
+            const { el, host } = mount(true);
+            const revealer = el.querySelector('.adw-video-controls-revealer') as HTMLElement;
+            expect(el.controlsRevealed).toBe(false);
+            expect(getComputedStyle(revealer).display).not.toBe('none');
+            el.revealControls();
+            expect(el.controlsRevealed).toBe(true);
+            expect(getComputedStyle(revealer).pointerEvents).toBe('auto');
+            host.remove();
+        });
+
+        await it('withdraws itself after three seconds of stillness, and re-arms on movement', async () => {
+            // gtkvideo.c:130 — `g_timeout_add (3 * 1000, …)`. Re-arming on every reveal is
+            // what makes it "three seconds after the LAST movement" rather than after the
+            // first, so the test moves the pointer before the first timeout could fire.
+            const { el, host } = mount(true);
+            el.revealControls();
+            el.revealControls();
+            expect(el.controlsRevealed).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe("<gtk-video> the template's three nodes", async () => {
+        await it("keeps the author's <video> as the main child and adds the two overlays", () => {
+            // ui/gtkvideo.ui puts the picture (here the media) UNDER an overlay icon and a
+            // controls revealer. Wrapping in place rather than re-creating is what lets the
+            // light DOM stay the API.
+            const { el, host } = mount(true);
+            const surface = el.querySelector('.adw-video-surface') as HTMLElement;
+            expect(surface.querySelector('video')).toBe(el.media);
+            expect(surface.querySelector('.adw-video-overlay-icon')).not.toBe(null);
+            expect(surface.querySelector('.adw-video-controls-revealer')).not.toBe(null);
+            host.remove();
+        });
+
+        await it('the overlay icon wears .osd and .circular and is a real BUTTON', async () => {
+            // ui/gtkvideo.ui — `<class name="osd"/>`, `<class name="circular"/>`, and an
+            // `accessible-role` of button. A `<button>` IS that role natively, which is the
+            // honest way to build it rather than a div with a click handler.
+            const { el, host } = mount(true);
+            const button = el.querySelector('.adw-video-overlay-icon') as HTMLButtonElement;
+            expect(button.tagName).toBe('BUTTON');
+            expect(button.classList.contains('osd')).toBe(true);
+            expect(button.classList.contains('circular')).toBe(true);
+            host.remove();
+        });
+
+        await it("the icon is 64px with a 32px radius — libadwaita's three lines", () => {
+            // refs/libadwaita/src/stylesheet/widgets/_misc.scss:76-80 — `video image.osd`.
+            // The radius is half the width, the same shape `.circular` gives at 34px.
+            const { el, host } = mount(true);
+            const button = el.querySelector('.adw-video-overlay-icon') as HTMLButtonElement;
+            const style = getComputedStyle(button);
+            expect(style.minWidth).toBe('64px');
+            expect(style.minHeight).toBe('64px');
+            expect(style.borderTopLeftRadius).toBe('32px');
+            host.remove();
+        });
+    });
+};

package/src/gtk-viewport.spec.ts

@@ -0,0 +1,140 @@
+// DOM-level tests for <gtk-viewport>: the adjustments are GTK's own configure — a step of a
+// tenth of the window and a page of nine tenths — read off the scrollport rather than
+// recomputed, and `scroll-to-focus` moves the position the way GTK's focus handler does.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwAdjustment } from '@gjsify/adwaita-core';
+
+import type { GtkViewport } from './elements/gtk-viewport.js';
+
+/**
+ * A host of a known size, so a viewport inside it has a measurable page.
+ *
+ * The VIEWPORT carries the size rather than the host: GTK hands a viewport an allocation from
+ * its parent, and in a browser the allocation is a height on the scrollport itself — without
+ * one it grows with its content and has nothing to scroll.
+ */
+function mount(width = 200, height = 100): { el: GtkViewport; host: HTMLElement } {
+    const host = document.createElement('div');
+    host.style.width = `${width}px`;
+    host.style.height = `${height}px`;
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-viewport') as GtkViewport;
+    el.style.width = `${width}px`;
+    el.style.height = `${height}px`;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** A child of a fixed size, so the viewport's page and content sizes are exact. */
+function content(el: GtkViewport, height: number, width = 200): HTMLElement {
+    const box = document.createElement('div');
+    box.style.width = `${width}px`;
+    box.style.height = `${height}px`;
+    el.appendChild(box);
+    return box;
+}
+
+/** The `detail` of every `event` dispatched on (or bubbling to) `el`. */
+function record(el: HTMLElement, event: string): unknown[] {
+    const details: unknown[] = [];
+    el.addEventListener(event, (e) => details.push((e as CustomEvent).detail));
+    return details;
+}
+
+/** The `detail` of a `value-changed`, which carries one adjustment per axis. */
+const detail = (value: unknown): { hadjustment: AdwAdjustment; vadjustment: AdwAdjustment } =>
+    value as { hadjustment: AdwAdjustment; vadjustment: AdwAdjustment };
+
+export const GtkViewportTest = async () => {
+    await describe('<gtk-viewport> the adjustments', async () => {
+        await it('is a generic role, and an empty one has nothing to scroll', async () => {
+            const { el, host } = mount();
+            expect(el.getAttribute('role')).toBe('generic');
+            // No content: the range is exactly the window, which is `upper == page_size` and
+            // the reason an automatic scrollbar stays hidden.
+            expect(el.vadjustment.upper).toBe(el.vadjustment.pageSize);
+            expect(el.vadjustment.value).toBe(0);
+            host.remove();
+        });
+
+        await it("configures each axis as GTK's viewport does", async () => {
+            const { el, host } = mount(200, 100);
+            content(el, 400);
+            const vertical = el.vadjustment;
+            // `viewport_set_adjustment_values`: lower 0, upper the child size, page the
+            // viewport size, and the two increments as fractions OF it.
+            expect(vertical.lower).toBe(0);
+            expect(vertical.upper).toBe(400);
+            expect(vertical.pageSize).toBe(100);
+            expect(vertical.stepIncrement).toBe(10);
+            expect(vertical.pageIncrement).toBe(90);
+            expect(el.hadjustment.upper).toBe(200);
+            host.remove();
+        });
+
+        await it('announces a move as a value-changed, once, with both axes', async () => {
+            const { el, host } = mount(200, 100);
+            content(el, 400);
+            const seen = record(el, 'value-changed');
+            el.scrollAxis('vertical', 40);
+            expect(seen.length).toBe(1);
+            const both = detail(seen[0]);
+            expect(both.vadjustment.value).toBe(40);
+            expect(both.hadjustment.value).toBe(0);
+            host.remove();
+        });
+
+        await it("clamps a move into the range, which is set_value's contract", async () => {
+            const { el, host } = mount(200, 100);
+            content(el, 400);
+            el.scrollAxis('vertical', 1000);
+            // upper - pageSize = 300.
+            expect(el.vadjustment.value).toBe(300);
+            el.scrollAxis('vertical', -50);
+            expect(el.vadjustment.value).toBe(0);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-viewport> scroll-to-focus', async () => {
+        await it('is on by default, and only the literal false turns it off', async () => {
+            const { el, host } = mount();
+            expect(el.scrollToFocus).toBe(true);
+            el.setAttribute('scroll-to-focus', 'false');
+            expect(el.scrollToFocus).toBe(false);
+            // An unknown value is the pspec's TRUE again, as an unset construct bag is.
+            el.setAttribute('scroll-to-focus', 'maybe');
+            expect(el.scrollToFocus).toBe(true);
+            host.remove();
+        });
+
+        await it('notifies the way a GObject property does', async () => {
+            const { el, host } = mount();
+            const seen = record(el, 'notify::scroll-to-focus');
+            el.scrollToFocus = false;
+            expect(seen.length).toBe(1);
+            // `toEqual` compares with `==` in this runner, so a detail object is read field by
+            // field rather than compared as one value.
+            expect((seen[0] as Record<string, unknown>)['scroll-to-focus']).toBe(false);
+            host.remove();
+        });
+
+        await it('brings a focused widget into view, and ignores a change written to itself', async () => {
+            const { el, host } = mount(200, 100);
+            const last = content(el, 400);
+            const button = document.createElement('button');
+            button.style.width = '80px';
+            button.style.height = '20px';
+            el.appendChild(button);
+            button.style.marginTop = '360px';
+            expect(el.vadjustment.value).toBe(0);
+            button.focus();
+            // The C checks `FOCUS_WITHIN` and skips a target that is the viewport itself;
+            // a real focus change inside it is what moves the adjustment.
+            expect(el.vadjustment.value > 0).toBe(true);
+            el.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+            host.remove();
+        });
+    });
+};

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

@@ -0,0 +1,232 @@
+// DOM-level tests for <gtk-window-controls>. The widget is a small decision table and every
+// branch of it is a line in `update_window_buttons` (gtkwindowcontrols.c:247-426): which half
+// of the decoration layout `side` selects, which tokens build a button, and the four window
+// properties that each token reads.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkWindowControls } from './elements/gtk-window-controls.js';
+import type { GtkWindow } from './elements/gtk-window.js';
+
+function mount(
+    attrs: Record<string, string> = {},
+    windowAttrs: Record<string, string> | null = null,
+): {
+    el: GtkWindowControls;
+    host: HTMLElement;
+} {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    let parent: HTMLElement = host;
+    if (windowAttrs !== null) {
+        const win = document.createElement('gtk-window') as GtkWindow;
+        for (const [name, value] of Object.entries(windowAttrs)) win.setAttribute(name, value);
+        host.appendChild(win);
+        parent = win;
+    }
+    const el = document.createElement('gtk-window-controls') as GtkWindowControls;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    parent.appendChild(el);
+    return { el, host };
+}
+
+/**
+ * What each child under the controls IS, in DOM order: the window icon, or the button's own
+ * role class (`minimize` / `maximize` / `close`, gtkwindowcontrols.c:322, :359, :387).
+ */
+function children(el: GtkWindowControls): string[] {
+    return [...el.children].map(
+        (node) =>
+            [...node.classList].find((name) => name !== 'adw-window-controls-button' && name !== 'adw-icon') ?? 'icon',
+    );
+}
+
+export const GtkWindowControlsTest = async () => {
+    await describe('<gtk-window-controls> defaults', async () => {
+        await it('is empty outside a window, exactly as GTK returns early there', () => {
+            // gtkwindowcontrols.c:257-264 — no GtkWindow root, `set_empty (self, TRUE)`.
+            const { el, host } = mount();
+            expect(el.empty).toBe(true);
+            expect(el.classList.contains('empty')).toBe(true);
+            expect(el.getAttribute('role')).toBe('group');
+            expect(el.children.length).toBe(0);
+            host.remove();
+        });
+
+        await it('defaults `side` to start, and `empty` to TRUE', () => {
+            // :68 — PROP_SIDE's default is GTK_PACK_START; :618 — `empty` defaults TRUE.
+            const { el, host } = mount();
+            expect(el.side).toBe('start');
+            expect(el.empty).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-window-controls> the decoration layout', async () => {
+        await it('builds the three GNOME buttons inside a window, on the end half', async () => {
+            // GNOME's layout is `menu:minimize,maximize,close`, and `menu` is the application
+            // menu: the START half names a token GTK's loop does not build a button for
+            // (gtkwindowcontrols.c:299-393), so a start-side bar is empty by construction.
+            const { el, host } = mount({ side: 'end' }, {});
+            expect(el.empty).toBe(false);
+            expect(el.classList.contains('empty')).toBe(false);
+            expect(children(el)).toStrictEqual(['minimize', 'maximize', 'close']);
+            host.remove();
+        });
+
+        await it('a layout with no colon is the SAME half on both sides', async () => {
+            // gtkwindowcontrols.c:150-158 — one token list, both sides, verbatim.
+            const start = mount({ 'decoration-layout': 'close' }, {});
+            expect(children(start.el)).toStrictEqual(['close']);
+            start.host.remove();
+            const end = mount({ 'decoration-layout': 'close', side: 'end' }, {});
+            expect(children(end.el)).toStrictEqual(['close']);
+            end.host.remove();
+        });
+
+        await it("GNOME's own layout leaves a START-side bar empty", async () => {
+            // `menu:minimize,maximize,close` — the application menu is the start half, and
+            // GTK's loop builds no button for a token it does not name
+            // (gtkwindowcontrols.c:299-393, :416-419).
+            const { el, host } = mount({}, {});
+            expect(children(el)).toStrictEqual([]);
+            expect(el.empty).toBe(true);
+            host.remove();
+        });
+
+        await it('`side` picks the half after the first colon', async () => {
+            // gtkwindowcontrols.c:141-166 — the START half is what is BEFORE the first
+            // colon, so the buttons are written there and the menu section after.
+            const layout = { 'decoration-layout': 'minimize,close:menu' };
+            const start = mount(layout, {});
+            expect(children(start.el)).toStrictEqual(['minimize', 'close']);
+            start.host.remove();
+            const end = mount({ ...layout, side: 'end' }, {});
+            expect(children(end.el)).toStrictEqual([]);
+            end.host.remove();
+        });
+
+        await it('an empty layout is the no-layout case, which is empty', async () => {
+            // gtkwindowcontrols.c:140-144 — an empty string is NULL, and NULL is empty.
+            const { el, host } = mount({ 'decoration-layout': '' }, {});
+            expect(el.empty).toBe(true);
+            host.remove();
+        });
+
+        await it('a token nothing knows builds nothing', async () => {
+            // The tail of the loop (:416-419) leaves `button` NULL for an unknown token.
+            const { el, host } = mount({ 'decoration-layout': 'menu,close' }, {});
+            expect(children(el)).toStrictEqual(['close']);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-window-controls> the window it reads', async () => {
+        await it('drops minimize and the icon on a modal window', async () => {
+            // gtkwindowcontrols.c:272-273, :299 and :318 — `is_sovereign_window` gates both.
+            const { el, host } = mount({ 'decoration-layout': 'icon,minimize,close' }, { modal: 'true' });
+            expect(children(el)).toStrictEqual(['close']);
+            host.remove();
+        });
+
+        await it('drops minimize and the icon on a transient window', async () => {
+            const { el, host } = mount(
+                { 'decoration-layout': 'icon,minimize,close' },
+                {
+                    'transient-for': 'main',
+                },
+            );
+            expect(children(el)).toStrictEqual(['close']);
+            host.remove();
+        });
+
+        await it('drops the icon when the window has none to show', async () => {
+            // update_window_icon (:187-210) leaves the icon out when there is no paintable.
+            const bare = mount({ 'decoration-layout': 'icon,close' }, {});
+            expect(children(bare.el)).toStrictEqual(['close']);
+            bare.host.remove();
+            const named = mount({ 'decoration-layout': 'icon,close' }, { 'icon-name': 'utilities-terminal' });
+            expect(children(named.el)).toStrictEqual(['icon', 'close']);
+            named.host.remove();
+        });
+
+        await it('drops the maximize button while the window is not resizable', async () => {
+            // gtkwindowcontrols.c:342-346 — `resizable` is the only test on this token.
+            const { el, host } = mount({ side: 'end' }, { resizable: 'false' });
+            expect(children(el)).toStrictEqual(['minimize', 'close']);
+            host.remove();
+        });
+
+        await it('swaps maximize for restore while the window is maximized', async () => {
+            // gtkwindowcontrols.c:347-350 — the glyph AND the label follow the state.
+            const { el, host } = mount({ side: 'end' }, { maximized: 'true' });
+            const button = el.querySelector('.maximize') as HTMLButtonElement;
+            expect(button.getAttribute('aria-label')).toBe('Restore');
+            expect(button.querySelector('gtk-image')?.getAttribute('icon-name')).toBe('window-restore-symbolic');
+            host.remove();
+        });
+
+        await it('drops the close button while the window is not deletable', async () => {
+            const { el, host } = mount({ side: 'end' }, { deletable: 'false' });
+            expect(children(el)).toStrictEqual(['minimize', 'maximize']);
+            host.remove();
+        });
+
+        await it('rebuilds when one of the six watched window properties moves', async () => {
+            // window_notify_cb (gtkwindowcontrols.c:428-441) names exactly these six.
+            const { el, host } = mount({ side: 'end' }, { deletable: 'false' });
+            const win = el.closest('gtk-window') as GtkWindow;
+            win.deletable = true;
+            await Promise.resolve();
+            await Promise.resolve();
+            expect(children(el)).toStrictEqual(['minimize', 'maximize', 'close']);
+            host.remove();
+        });
+
+        await it('takes the layout off the frame when it has none of its own', async () => {
+            // `get_layout`'s second stop, the port's stand-in for Gtk.Settings (:129-140).
+            const { el, host } = mount({ side: 'end' }, { 'decoration-layout': ':close' });
+            expect(children(el)).toStrictEqual(['close']);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-window-controls> events', async () => {
+        await it('a press asks for the action its GtkActionable name names', async () => {
+            const { el, host } = mount({ 'decoration-layout': 'minimize,close', side: 'end' }, {});
+            const actions: unknown[] = [];
+            el.addEventListener('window-action', (e) => actions.push((e as CustomEvent).detail));
+            (el.querySelector('.minimize') as HTMLButtonElement).click();
+            (el.querySelector('.close') as HTMLButtonElement).click();
+            expect(actions).toStrictEqual([{ action: 'minimize' }, { action: 'close' }]);
+            host.remove();
+        });
+
+        await it('`empty` notifies only when it moves', async () => {
+            // set_empty (gtkwindowcontrols.c:216-230) returns early on an unchanged value.
+            const { el, host } = mount({ side: 'end' }, {});
+            const events: unknown[] = [];
+            el.addEventListener('notify::empty', (e) => events.push((e as CustomEvent).detail));
+            const win = el.closest('gtk-window') as GtkWindow;
+            win.setAttribute('decoration-layout', '');
+            win.setAttribute('decoration-layout', '');
+            await Promise.resolve();
+            await Promise.resolve();
+            win.setAttribute('decoration-layout', ':close');
+            await Promise.resolve();
+            await Promise.resolve();
+            expect(events).toStrictEqual([{ empty: true }, { empty: false }]);
+            host.remove();
+        });
+
+        await it('a `side` write notifies with the property, not the attribute', async () => {
+            const { el, host } = mount({ side: 'start' }, {});
+            const events: unknown[] = [];
+            el.addEventListener('notify::side', (e) => events.push((e as CustomEvent).detail));
+            el.side = 'start';
+            el.side = 'end';
+            el.side = 'end';
+            expect(events).toStrictEqual([{ side: 'end' }]);
+            host.remove();
+        });
+    });
+};