@gjsify/adwaita-web 0.36.0 → 0.37.0

package/src/adw-action-rows.spec.ts

@@ -3,20 +3,16 @@
 // vectors the NativeScript renderer asserts against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// What this suite exists to catch, in the words of what it found:
-//   - NEITHER renderer hid an empty TITLE. `string_is_not_empty` is bound to the
-//     title label as much as to the subtitle (adw-action-row.ui:49-53 vs :71-75),
-//     and the browser port hand-rolled the subtitle-only half of that block six
-//     times over.
-//   - a programmatic `switchRow.active = true` emitted nothing here, because the
-//     DOM does not fire `change` for a scripted `.checked =` — while the
-//     NativeScript port, whose `checkedChange` does fire, emitted. One C source,
-//     two opposite answers, and nothing comparing them.
-//   - clicking anywhere but the handle of a switch row did nothing, though
-//     `adw_switch_row_init` makes the whole row the switch's activator.
-//   - `<adw-button-row activatable="false">` was honoured, an opt-out libadwaita
-//     does not have — and `<adw-action-row activatable="false">` meant the
-//     OPPOSITE, because that element reads the attribute by presence.
+// The rules it pins, each of which one renderer had wrong:
+//   - `string_is_not_empty` in `adw-action-row.ui` is bound to the TITLE label as much
+//     as to the subtitle, so an empty title hides too;
+//   - the DOM fires no `change` for a scripted `.checked =`, so a programmatic
+//     `switchRow.active = true` must be made to notify anyway — NativeScript's
+//     `checkedChange` does fire, and one C source must not give two answers;
+//   - `adw_switch_row_init` makes the WHOLE row the switch's activator;
+//   - libadwaita has no activatable opt-out for a button row, and
+//     `<adw-action-row activatable="false">` reads by PRESENCE, so it means the
+//     opposite of what it says.
 import { describe, expect, it } from '@gjsify/unit';
 
 import {
@@ -35,9 +31,8 @@ import type { AdwSwitchRow } from './elements/adw-switch-row.js';
 import type { AdwWindowTitle } from './elements/adw-window-title.js';
 
 /**
- * Mount an element imperatively — never through parsed HTML, because several
- * label vectors hinge on exact whitespace (`' '`, `'\t'`) that an attribute
- * value in markup is not a reliable carrier for.
+ * Mount an element imperatively, never through parsed HTML: several label vectors hinge
+ * on exact whitespace (`' '`, `'\t'`) that markup is not a reliable carrier for.
  */
 function mount<T extends HTMLElement>(tag: string): { el: T; host: HTMLElement } {
     const host = document.createElement('div');
@@ -144,13 +139,11 @@ export const AdwActionRowsTest = async () => {
         await it('reads `activatable` by PRESENCE, like every other boolean attribute here', () => {
             const { el: row, host } = mount<AdwActionRow>('adw-action-row');
             row.setAttribute('activatable', 'false');
-            // The HTML boolean-attribute convention (`<input disabled="false">`
-            // is disabled), which is how every other boolean attribute in this
-            // package is read. NOT a libadwaita rule — libadwaita has a typed
-            // gboolean and no attribute parsing at all — so it is pinned here
-            // rather than in the cross-renderer vectors. Pinned so the next
-            // reader does not "fix" it into the string comparison
-            // <adw-button-row> used to carry, which gave one markup two
+            // The HTML boolean-attribute convention (`<input disabled="false">` IS
+            // disabled), how every other boolean attribute in this package is read. NOT a
+            // libadwaita rule — libadwaita has a typed gboolean and no attribute parsing —
+            // so it is pinned here rather than in the cross-renderer vectors, and pinned so
+            // nobody "fixes" it into a string comparison that would give one markup two
             // opposite meanings inside one package.
             expect(row.activatable).toBe(true);
             host.remove();
@@ -183,9 +176,9 @@ export const AdwActionRowsTest = async () => {
 
             widget.click();
 
-            // One click, and no row activation: GtkListBox does not emit
-            // `row-activated` for a click a child widget claimed. Re-clicking the
-            // widget here would also bounce back into the row's own listener.
+            // One click, no row activation: GtkListBox does not emit `row-activated` for a
+            // click a child widget claimed, and re-clicking the widget here would bounce
+            // back into the row's own listener.
             expect(widgetClicks).toBe(1);
             expect(activations.length).toBe(0);
             host.remove();
@@ -257,16 +250,15 @@ export const AdwActionRowsTest = async () => {
                 setAttr(row, 'start-icon-name', vector.startIconName);
                 setAttr(row, 'end-icon-name', vector.endIconName);
 
-                // The two `image.icon.{start,end}` nodes are <adw-icon> now, not
-                // hand-rolled decorative spans.
+                // The two `image.icon.{start,end}` nodes are <adw-icon>, not hand-rolled
+                // decorative spans.
                 const icons = Array.from(row.querySelectorAll('adw-icon')) as HTMLElement[];
                 expect(icons.length).toBe(2);
                 expect(!icons[0]!.hidden).toBe(vector.startIconVisible);
                 expect(!icons[1]!.hidden).toBe(vector.endIconVisible);
-                // The mask class is the NORMALIZED name: the generated classes
-                // never carry `-symbolic`, and this row used to interpolate the
-                // raw one — so `start-icon-name="list-add-symbolic"` asked for a
-                // class that has never existed and drew an empty box.
+                // The mask class is the NORMALIZED name — the generated classes never
+                // carry `-symbolic`, so interpolating the raw one asks for a class that has
+                // never existed and draws an empty box.
                 if (vector.startIconVisible) {
                     expect(icons[0]!.classList.contains(`adw-icon--${normalizeIconName(vector.startIconName)}`)).toBe(
                         true,

package/src/adw-avatar.spec.ts

@@ -1,12 +1,10 @@
 // DOM-level conformance tests for <adw-avatar>, driven by the SAME vectors the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers used to carry independent copies of the initials + colour
-// derivation, and the copies had drifted apart AND away from libadwaita:
-// this element rendered "AD" for `text="Ada"` where GTK and NS render "A", and
-// both hashed UTF-16 code units where GLib hashes UTF-8 bytes, so every accented
-// name was painted the wrong colour. Nothing failed, because nothing compared
-// them. This suite is that comparison.
+// Two rules independent copies of the initials + colour derivation drifted from: GTK
+// takes ONE initial from a single-word `text`, and the colour hash runs over UTF-8 BYTES
+// as GLib's does — hashing UTF-16 code units paints every accented name the wrong
+// colour.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { AVATAR_MODE_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -140,37 +138,70 @@ export const AdwAvatarTest = async () => {
     });
 
     await describe('<adw-avatar> mode (update_visibility, adw-avatar.c:117)', async () => {
-        // The `hasCustomImage` rows are not reachable through this element: it
-        // passes `hasCustomImage: false` unconditionally, because it has no
-        // custom-image support at all — `Adw.Avatar:custom-image` is unported.
-        // Named below rather than silently filtered.
+        // A 1x1 transparent GIF: a real, decodable image, so `custom-image` is
+        // exercised through the same path a photo would take — and no network.
+        const PIXEL = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
+
         for (const { hasCustomImage, showInitials, text, mode, rule } of AVATAR_MODE_VECTORS) {
-            if (hasCustomImage) continue;
-            await it(`initials=${showInitials} "${text}" → ${mode} — ${rule}`, () => {
+            await it(`image=${hasCustomImage} initials=${showInitials} "${text}" → ${mode} — ${rule}`, () => {
                 const host = document.createElement('div');
                 document.body.appendChild(host);
                 const avatar = document.createElement('adw-avatar');
                 if (showInitials) avatar.setAttribute('show-initials', '');
                 if (text) avatar.setAttribute('text', text);
+                if (hasCustomImage) avatar.setAttribute('custom-image', PIXEL);
                 host.appendChild(avatar);
 
-                // Exactly ONE of the two reachable modes is drawn — the point of
-                // the table is the precedence, and "both visible at once" is the
+                // Exactly ONE of the three modes is drawn — the point of the
+                // table is the precedence, and "two visible at once" is the
                 // failure it guards against.
                 const initials = (avatar.querySelector('.adw-avatar-text') as HTMLElement).hidden === false;
                 const icon = (avatar.querySelector('.adw-avatar-icon') as HTMLElement).hidden === false;
+                const image = (avatar.querySelector('.adw-avatar-custom-image') as HTMLElement).hidden === false;
                 expect(initials).toBe(mode === 'initials');
                 expect(icon).toBe(mode === 'icon');
+                expect(image).toBe(mode === 'image');
                 host.remove();
             });
         }
 
-        await it('leaves out only the custom-image rows, which this element cannot reach', () => {
-            const unreachable = AVATAR_MODE_VECTORS.filter((vector) => vector.hasCustomImage);
-            expect(unreachable.length).toBeGreaterThan(0);
-            // Every one of them is an `image` outcome, i.e. the whole mode is
-            // missing rather than a corner of it.
-            for (const vector of unreachable) expect(vector.mode).toBe('image');
+        await it('drops the custom image again when the attribute goes away', () => {
+            // The mode is re-derived on every attribute change, so removing the
+            // image has to fall back to whichever mode the remaining state picks
+            // — this is where a port that only ever ADDS the image node fails.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const avatar = document.createElement('adw-avatar');
+            avatar.setAttribute('show-initials', '');
+            avatar.setAttribute('text', 'Ada Lovelace');
+            avatar.setAttribute('custom-image', PIXEL);
+            host.appendChild(avatar);
+
+            expect((avatar.querySelector('.adw-avatar-custom-image') as HTMLElement).hidden).toBe(false);
+
+            avatar.removeAttribute('custom-image');
+            expect((avatar.querySelector('.adw-avatar-custom-image') as HTMLElement).hidden).toBe(true);
+            expect((avatar.querySelector('.adw-avatar-text') as HTMLElement).hidden).toBe(false);
+
+            host.remove();
+        });
+
+        await it('fills the circle with the image rather than letterboxing it', () => {
+            // `object-fit` is the whole reason the image looks like an avatar and
+            // not like a photo in a round frame — a class-name assertion cannot
+            // see it, and it is one word away from being wrong.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const avatar = document.createElement('adw-avatar');
+            avatar.setAttribute('custom-image', PIXEL);
+            avatar.setAttribute('size', '64');
+            host.appendChild(avatar);
+
+            const image = avatar.querySelector('.adw-avatar-custom-image') as HTMLElement;
+            expect(getComputedStyle(image).objectFit).toBe('cover');
+            expect(Math.round(image.getBoundingClientRect().width)).toBe(64);
+
+            host.remove();
         });
     });
 };

package/src/adw-banner.spec.ts

@@ -1,13 +1,10 @@
 // DOM-level conformance tests for <adw-banner>, driven by the SAME vectors the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers carried independent banner logic and had drifted apart AND
-// away from libadwaita: `revealed` was opt-in here (right) and initialised TRUE
-// on NativeScript with no `visibility` written at all (wrong), `use-markup` was
-// opt-in in both with a comment here asserting that WAS the C default (it is
-// TRUE, adw-banner.c:422-425), `button-style` was in neither, and the mnemonic
-// marker the template pins onto the button (adw-banner.ui:33) was painted as a
-// literal underscore. Nothing failed, because nothing compared them.
+// The defaults independent banner logic drifted from, all of them in
+// `ADW_BANNER_DEFAULTS`: `revealed` is FALSE, `use-markup` is TRUE (opting it in inverts
+// the C), `button-style` exists, and the mnemonic marker the template pins onto the
+// button is a marker, not a literal underscore to paint.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { ADW_BANNER_DEFAULTS } from '@gjsify/adwaita-core';
@@ -64,7 +61,7 @@ export const AdwBannerTest = async () => {
     });
 
     await describe('adw-banner use-markup — a DELIBERATE departure from the C default', async () => {
-        // The C default is unambiguously TRUE (adw-banner.c:422-425) and core
+        // The C default is unambiguously TRUE and core
         // carries it as the spec value. This renderer does NOT adopt it: Pango
         // markup is not HTML, and defaulting a `title` attribute to `innerHTML`
         // would make an injection sink out of a widget that is not one in GTK.

package/src/adw-button-content.spec.ts

@@ -2,15 +2,12 @@
 // vectors the NativeScript renderer asserts against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// THE STYLE CLASS IS WHY THIS SUITE EXISTS. `AdwButtonContent` puts
-// `image-text-button` on the button hosting it (adw-button-content.c:115) and
-// removes it on unroot (:126); the stylesheet gives that class
-// `padding-left/right: 9px` where a plain text button has 17px
-// (_buttons.scss:77-80 against :72-75). `grep -rn "image-text-button"` over both
-// renderer trees returned NOTHING, so every icon+label button in this package
-// was drawn with the wrong horizontal padding for its whole life. `use-underline`
-// was absent, and an empty `icon-name` hid the image where the C sets
-// `image-missing` (:355-356).
+// The STYLE CLASS is why this suite exists: `AdwButtonContent` puts
+// `image-text-button` on the button hosting it and removes it on unroot, and
+// `_buttons.scss` gives that class 9px horizontal padding where a plain text button has
+// 17px — so a renderer that never sets the class draws every icon+label button with the
+// wrong padding. Also pinned: `use-underline`, and that an empty `icon-name` shows
+// `image-missing` rather than hiding the image.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { BUTTON_CONTENT_DEFAULT_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -93,8 +90,8 @@ export const AdwButtonContentTest = async () => {
             host.appendChild(split);
 
             // The class goes on the `splitbutton` node, which is what
-            // `splitbutton.image-text-button > button` (:499-507) selects —
-            // a different declaration block from the plain-button one.
+            // `splitbutton.image-text-button > button` selects — a different declaration
+            // block from the plain-button one.
             expect(split.classList.contains(BUTTON_CONTENT_STYLE_CLASS)).toBe(true);
             expect(action.classList.contains(BUTTON_CONTENT_STYLE_CLASS)).toBe(false);
             // …and the padding lands on the INNER button, which is what that
@@ -134,7 +131,7 @@ export const AdwButtonContentTest = async () => {
                     maskName === '' ? 0 : 1,
                 );
                 // The image node is never hidden — `gtk_widget_set_visible` is
-                // called on the LABEL only (:300, :398).
+                // called on the LABEL only.
                 expect(icon.hidden).toBe(false);
                 host.remove();
             });

package/src/adw-button-row.spec.ts

@@ -36,17 +36,15 @@ export const AdwButtonRowTest = async () => {
 
             expect(errors.length).toBe(0);
             expect(row.textContent).toContain('Add account');
-            // The start icon span carries the adw-icon class derived from the name.
             expect(row.querySelector('.adw-icon--list-add') !== null).toBe(true);
-            // Activatable by default.
             expect(row.classList.contains('activatable')).toBe(true);
             host.remove();
         });
 
         // DELETED: `honours activatable="false"`. It was green, and what it
         // pinned was an INVENTION — `Adw.ButtonRow` is always activatable
-        // (`<property name="activatable">True</property>`, adw-button-row.ui:5;
-        // "AdwButtonRow is always activatable.", adw-button-row.c:31), and the
+        // (`<property name="activatable">True</property>`, adw-button-row.ui;
+        // "AdwButtonRow is always activatable."), and the
         // class exposes no property, no setter and no getter for it. The opt-out
         // also gave one markup two opposite meanings inside one package, because
         // <adw-action-row> reads `activatable` by PRESENCE — so

package/src/adw-carousel.spec.ts

@@ -1,15 +1,9 @@
 // DOM-level conformance tests for <adw-carousel>, driven by the SAME vectors the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers used to carry independent, differently-wrong copies of the
-// carousel's arithmetic, and nothing compared them: this element defaulted
-// `allow-scroll-wheel` to FALSE where libadwaita defaults it TRUE (so a plain
-// <adw-carousel> ignored the wheel while its own header claimed the opposite),
-// resolved a half-way position to the LATER page where every libadwaita lookup
-// takes the earlier one, dropped `<adw-carousel position="2">` on the floor,
-// dropped the horizontal-delta fallback its comment described, and emitted
-// `page-changed` only when the index changed — which made the documented -1
-// unreachable. This suite is that comparison.
+// The suite exists because the two renderers used to carry independent,
+// differently-wrong copies of the carousel's arithmetic with nothing comparing them;
+// each rule that drifted is pinned by a test below.
 //
 // Scrolls are made instant by overriding the track's `scroll-behavior`; the
 // element sets it as an inline style precisely so it stays overridable.
@@ -44,10 +38,9 @@ function card(label: string): HTMLElement {
 }
 
 /**
- * Mount a carousel with the given page labels.
- *
- * The host gets an explicit size because the page pitch is MEASURED — a carousel
- * with no width has no distance, and every scroll would be a no-op.
+ * Mount a carousel with the given page labels. The host gets an explicit size because
+ * the page pitch is MEASURED: a carousel with no width has no distance, so every scroll
+ * would be a no-op.
  */
 function mount(labels: readonly string[], attributes: Record<string, string> = {}) {
     const host = document.createElement('div');
@@ -61,10 +54,9 @@ function mount(labels: readonly string[], attributes: Record<string, string> = {
     host.appendChild(carousel);
 
     const track = carousel.querySelector('.adw-carousel-track') as HTMLElement;
-    // Instant scrolls: the assertions are about WHERE it lands, never about the
-    // animation getting there. Snapping is off for the same reason — `mandatory`
-    // re-snaps a programmatic `scrollLeft` to the nearest page, which is exactly
-    // the fractional position several of these tests are about.
+    // Instant scrolls: the assertions are about WHERE it lands, never the animation.
+    // Snapping is off for the same reason — `mandatory` re-snaps a programmatic
+    // `scrollLeft` to the nearest page, the very fractional position under test.
     track.style.setProperty('scroll-behavior', 'auto');
     track.style.setProperty('scroll-snap-type', 'none');
     return { carousel, host, track };
@@ -131,16 +123,15 @@ function applyPageOp(carousel: CarouselElement, op: CarouselPageOp, pages: Map<s
         case 'scrollTo':
         case 'setPosition':
         case 'settle':
-            // Position ops need a settled scroll, so they are driven separately
-            // by the scroll tests below rather than through this replay.
+            // Position ops need a settled scroll and are driven by the scroll tests
+            // below, not through this replay.
             return true;
     }
 }
 
 export const AdwCarouselTest = async () => {
     await describe('adw-carousel page list (libadwaita conformance vectors)', async () => {
-        // Only the structural rows: the element's page methods are what the DOM
-        // exposes, while position ops need a real scroll and are covered below.
+        // Only the structural rows: the page methods are what the DOM exposes.
         const structural = CAROUSEL_PAGE_LIST_VECTORS.filter((vector) =>
             vector.ops.every((op) => op.kind === 'insert' || op.kind === 'remove' || op.kind === 'reorder'),
         );
@@ -157,11 +148,11 @@ export const AdwCarouselTest = async () => {
 
                 expect(results).toStrictEqual([...vector.opResults]);
                 expect(carousel.nPages).toBe(vector.expected.nPages);
-                // The DOM order IS the model order — a reorder that only moved
-                // the model would leave the pages painted where they were.
+                // The DOM order IS the model order: a reorder that moved only the model
+                // would leave the pages painted where they were.
                 expect(domOrder(carousel)).toStrictEqual([...vector.expected.ids]);
-                // And the position compensation reached the scroll container: a
-                // page revealed before the current one must not push it aside.
+                // The position compensation reaches the scroll container: a page revealed
+                // before the current one must not push it aside.
                 expect(carousel.position).toBe(vector.expected.position);
                 host.remove();
             });
@@ -170,17 +161,15 @@ export const AdwCarouselTest = async () => {
 
     await describe('adw-carousel page lookup (libadwaita conformance vectors)', async () => {
         for (const vector of CAROUSEL_PAGE_AT_POSITION_VECTORS) {
-            // Only the rows whose snap points are a settled page list are
-            // reachable through the DOM; the mid-reveal geometry rows need a
-            // reveal ramp this port does not have.
+            // Only rows whose snap points are a settled page list are reachable through
+            // the DOM; mid-reveal geometry rows need a reveal ramp this port lacks.
             const settled = vector.snapPoints.length > 0 && vector.snapPoints.every((point, i) => point === i);
             if (!settled) continue;
 
             await it(`${vector.position} → page ${vector.page} — ${vector.rule}`, async () => {
-                // Driven through the `position` property rather than a real
-                // scroll: a scroll offset is quantised to device pixels, so the
-                // ±1e-7 rows around the tie are not expressible as a drag. The
-                // tie ITSELF is, and gets its own drag test below.
+                // Driven through the `position` property, not a real scroll: a scroll
+                // offset is quantised to device pixels, so the ±1e-7 rows around the tie
+                // are not expressible as a drag. The tie itself is, below.
                 const { carousel, host } = mount(vector.snapPoints.map((_point, index) => `p${index}`));
                 (carousel as unknown as { position: number }).position = vector.position;
                 await flush();
@@ -192,8 +181,8 @@ export const AdwCarouselTest = async () => {
 
     await describe('adw-carousel scroll wheel (scroll_cb)', async () => {
         await it('pages on a mouse wheel WITHOUT being asked to — the default is TRUE', async () => {
-            // The regression pin: this element used to require an explicit
-            // `allow-scroll-wheel` attribute, inverting adw-carousel.c:1103-1106.
+            // This element used to require an explicit `allow-scroll-wheel` attribute,
+            // inverting the libadwaita default.
             const { carousel, host } = mount(['a', 'b', 'c']);
             expect(carousel.allowScrollWheel).toBe(true);
             expect(wheel(carousel, { deltaY: 120 })).toBe(true);
@@ -212,8 +201,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('pages on a horizontal delta — the fallback the port dropped', async () => {
-            // adw-carousel.c:554-559. The old code returned early whenever
-            // |deltaY| <= |deltaX|, so a dx-only event did nothing at all.
+            // The old code returned early whenever |deltaY| <= |deltaX|, so a dx-only
+            // event did nothing at all.
             const { carousel, host } = mount(['a', 'b', 'c']);
             expect(wheel(carousel, { deltaX: 120 })).toBe(true);
             await flush();
@@ -222,8 +211,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('locks out a second notch for 150 ms', async () => {
-            // adw-carousel.c:22, :526. The old accumulator had no time component
-            // at all, so a fast wheel paged as many times as it had deltas.
+            // The old accumulator had no time component, so a fast wheel paged as many
+            // times as it had deltas.
             const { carousel, host } = mount(['a', 'b', 'c']);
             expect(wheel(carousel, { deltaY: 120 })).toBe(true);
             expect(wheel(carousel, { deltaY: 120 })).toBe(false);
@@ -233,8 +222,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('leaves a touchpad gesture to the native scroll-snap', async () => {
-            // A touchpad is ignored outright (:537-538) because its own kinetic
-            // scroll already drives the strip — here, the track's scroll-snap.
+            // A touchpad is ignored outright: its own kinetic scroll already drives the
+            // strip, here the track's scroll-snap.
             const { carousel, host } = mount(['a', 'b', 'c']);
             expect(wheel(carousel, { deltaX: 12, deltaY: 7 })).toBe(false);
             await flush();
@@ -243,8 +232,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('does not consume a wheel event it did not act on', async () => {
-            // GDK_EVENT_STOP only when it paged (:561-562 vs :576). The old code
-            // called preventDefault BEFORE its threshold test.
+            // GDK_EVENT_STOP only when it paged; the old code called preventDefault()
+            // BEFORE its threshold test.
             const { carousel, host } = mount(['a', 'b', 'c'], { interactive: 'false' });
             expect(wheel(carousel, { deltaY: 120 })).toBe(false);
             host.remove();
@@ -253,8 +242,8 @@ export const AdwCarouselTest = async () => {
 
     await describe('adw-carousel page-changed (scroll_animation_done_cb)', async () => {
         await it('reports every completed scroll, including back onto the same page', async () => {
-            // The old emission was gated on the ROUNDED index changing, so a
-            // settle back onto the page it started from said nothing.
+            // Gating the emission on the ROUNDED index means a settle back onto the page
+            // it started from says nothing.
             const { carousel, host } = mount(['a', 'b', 'c']);
             const seen: number[] = [];
             carousel.addEventListener('page-changed', (event) => {
@@ -271,8 +260,7 @@ export const AdwCarouselTest = async () => {
         await it('reports the LOWER page for a half-way settle', async () => {
             const { carousel, host } = mount(['a', 'b']);
             await dragTo(carousel, 0.5);
-            // Math.round would have said page 1 here; every libadwaita lookup
-            // resolves the tie downwards (adw-carousel.c:198-201).
+            // Math.round would say page 1; every libadwaita lookup resolves the tie down.
             expect(carousel.currentPage).toBe(0);
             host.remove();
         });
@@ -280,8 +268,8 @@ export const AdwCarouselTest = async () => {
 
     await describe('adw-carousel declarative position', async () => {
         await it('honours <adw-carousel position="2"> at upgrade time', async () => {
-            // Attribute changes are delivered BEFORE connectedCallback, and the
-            // old guard dropped them, so a declared position never applied.
+            // Attribute changes are delivered BEFORE connectedCallback, so a guard that
+            // drops them drops a declared position.
             const { carousel, host } = mount(['a', 'b', 'c'], { position: '2' });
             await flush();
             expect(carousel.currentPage).toBe(2);
@@ -360,9 +348,8 @@ export const AdwCarouselTest = async () => {
 
         await it('turns allow-long-swipes into scroll-snap-stop', async () => {
             // The property used to be inert: both branches of its ternary were
-            // `current + step`. FALSE means "each swipe can only move to the
-            // adjacent pages" (adw-carousel.c:1111-1113), which is what
-            // scroll-snap-stop: always enforces.
+            // `current + step`. FALSE means "each swipe moves only to an adjacent
+            // page", which `scroll-snap-stop: always` enforces.
             const { carousel, host } = mount(['a', 'b', 'c']);
             const slot = carousel.querySelector('.adw-carousel-page') as HTMLElement;
             expect(carousel.allowLongSwipes).toBe(false);
@@ -374,8 +361,8 @@ export const AdwCarouselTest = async () => {
         });
 
         await it('spaces the pages by the spacing property', async () => {
-            // `distance = size + spacing` (adw-carousel.c:767); with no gap in the
-            // track the property would have nowhere to show up.
+            // `distance = size + spacing`; with no gap in the track the property would
+            // have nowhere to show up.
             const { carousel, host, track } = mount(['a', 'b', 'c'], { spacing: '16' });
             expect(track.style.columnGap).toBe('16px');
             // The pitch a drag is measured in must include the gap; if it did not,