@gjsify/adwaita-web 0.36.0 → 0.37.0

package/src/tab-view.spec.ts

@@ -2,16 +2,12 @@
 // core suite and the NativeScript renderer assert against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// This family is the one where the two renderers did not merely drift — they had
-// never implemented the model at all. `close-page` meant three different things
-// (libadwaita removes a non-pinned page through a two-phase confirm; this element
-// removed nothing, EVER, so every close was permanently denied; NS removed
-// immediately with no signal and refused on the last tab), out-of-range selection
-// was clamped here and ignored there, and the pinned partition, the parent-aware
-// close successor, the reorder clamps and the keyboard model existed in neither.
-// This suite is what makes the element a thin adapter over `TabViewState` instead
-// of a second implementation: the element is handed STRAIGHT to the shared vector
-// driver, so a method it re-implements fails here.
+// The element is a thin adapter over `TabViewState`, not a second implementation: it is
+// handed STRAIGHT to the shared vector driver, so a method it re-implements fails here.
+// Neither renderer had the model at all — `close-page` meant three different things,
+// out-of-range selection was clamped in one and ignored in the other, and the pinned
+// partition, the parent-aware close successor, the reorder clamps and the keyboard model
+// existed in neither.
 import { describe, expect, it } from '@gjsify/unit';
 
 import {
@@ -38,12 +34,10 @@ interface MountedTabView {
 }
 
 /**
- * Mount an EMPTY view and record its events.
- *
- * Empty rather than markup-seeded: the vectors seed through the same
- * `seedTabViewPages` the other two suites use, which is what makes "the element
- * is the vector target" literal. The declarative path gets its own describe
- * block below.
+ * Mount an EMPTY view and record its events. Empty rather than markup-seeded: the
+ * vectors seed through the same `seedTabViewPages` the other two suites use, which is
+ * what makes "the element is the vector target" literal. The declarative path has its own
+ * describe block below.
  */
 function mountTabView(handler: 'default' | 'defer'): MountedTabView {
     const host = document.createElement('div');
@@ -126,11 +120,9 @@ export const AdwTabViewConformanceTest = async () => {
                 if (vector.closing) expect(tabViewClosing(view)).toStrictEqual([...vector.closing]);
                 if (vector.diagnostics) expect(view.diagnostics).toStrictEqual([...vector.diagnostics]);
 
-                // The DOM must agree with the model: one chip per page in model
-                // order, exactly the selected panel shown, and nothing at all
-                // when the view emptied. The old element built the bar once at
-                // connect and never touched it again, so a closed page kept its
-                // chip forever — this is the assertion that would have caught it.
+                // The DOM must agree with the model: one chip per page in model order,
+                // exactly the selected panel shown, and nothing when the view empties. A
+                // bar built once at connect keeps a closed page's chip forever.
                 expect(tabChips(view).map((tab) => tab.dataset.pageId)).toStrictEqual([...vector.order]);
                 const expectedShown = vector.order.map(() => false);
                 if (vector.selectedIndex >= 0) expectedShown[vector.selectedIndex] = true;
@@ -175,15 +167,15 @@ export const AdwTabViewConformanceTest = async () => {
             expect(view.pages[0]!.title).toBe('Renamed');
             expect(tabChips(view)[0]!.querySelector('.adw-tab-title')!.textContent).toBe('Renamed');
 
-            // `null` coerces to '' (adw-tab-view.c:3021), not to 'null'.
+            // `null` coerces to '', not to 'null'.
             page.removeAttribute('title');
             expect(view.pages[0]!.title).toBe('');
             host.remove();
         });
 
         await it('generates a distinct page id per declared page, and an explicit page-id wins', () => {
-            // An id stands in for the AdwTabPage POINTER, so two pages must never
-            // share one — a declared page without `page-id` still needs its own.
+            // An id stands in for the AdwTabPage POINTER, so two pages must never share
+            // one — a declared page without `page-id` still needs its own.
             const host = document.createElement('div');
             host.innerHTML = `<adw-tab-view>
                 <adw-tab-page title="One"></adw-tab-page>
@@ -221,15 +213,15 @@ export const AdwTabViewConformanceTest = async () => {
         });
 
         await it('IGNORES an out-of-range or unparseable index instead of clamping it', () => {
-            // The old `Number.isNaN(raw) ? 0 : Math.min(Math.max(raw, 0), max)`
-            // silently selected the last page for `99` and the first for `-1`
-            // and `oops`; libadwaita refuses all three (adw-tab-view.c:2145, :4133).
+            // A clamping `Number.isNaN(raw) ? 0 : Math.min(Math.max(raw, 0), max)` selects
+            // the last page for `99` and the first for `-1`/`oops`; libadwaita refuses all
+            // three.
             const { view, host } = mountThree();
             for (const value of ['99', '-1', 'oops']) {
                 view.setAttribute('selected', value);
                 expect(view.selectedIndex).toBe(0);
             }
-            // ...and the attribute is put back in sync rather than left lying.
+            //...and the attribute is put back in sync rather than left lying.
             view.setAttribute('selected', '1');
             expect(view.selectedIndex).toBe(1);
             expect(view.getAttribute('selected')).toBe('1');
@@ -237,8 +229,8 @@ export const AdwTabViewConformanceTest = async () => {
         });
 
         await it('notifies on a PROGRAMMATIC selection, not only on a click', () => {
-            // `view.selected = 2` used to change the visible page and fire
-            // nothing, while a tab click fired; C notifies on every path (:1854).
+            // C notifies on EVERY path: a programmatic `view.selected = 2` must notify as
+            // a tab click does.
             const { view, host } = mountThree();
             const seen: number[] = [];
             view.addEventListener('notify::selected-page', (event) =>
@@ -359,8 +351,8 @@ export const AdwTabViewConformanceTest = async () => {
 
         for (const vector of TAB_CLOSE_VISIBLE_VECTORS) {
             await it(`close visibility: ${vector.rule}`, () => {
-                // The renderer's gate IS the core predicate; asserting the table
-                // here keeps a future "simplify to `selected`" from passing.
+                // The renderer's gate IS the core predicate; the table here keeps a future
+                // "simplify to `selected`" from passing.
                 expect(
                     tabCloseVisible({
                         hovering: vector.hovering,
@@ -416,9 +408,8 @@ export const AdwTabViewConformanceTest = async () => {
         });
 
         await it('moves the roving tabindex with the selection, so inactive tabs stay reachable', () => {
-            // The old element set `tab.tabIndex = isActive ? 0 : -1` under
-            // role=tablist with NO key handler, so every inactive tab was
-            // keyboard-unreachable.
+            // `tab.tabIndex = isActive ? 0 : -1` under role=tablist needs a key handler,
+            // or every inactive tab is keyboard-unreachable.
             const { view, host } = mountFour();
             press(view, { key: 'ArrowRight' });
             expect(view.selectedId).toBe('b');

package/src/test.browser.mts

@@ -40,8 +40,12 @@ import { AdwSwitchTest } from './adw-switch.spec.js';
 import { AdwChecksTest } from './adw-checks.spec.js';
 import { AdwProgressBarTest } from './adw-progress-bar.spec.js';
 import { AdwAboutDialogTest } from './adw-about-dialog.spec.js';
+import { AdwStyleClassesTest } from './style-classes.spec.js';
+import { AdwShortcutLabelTest } from './adw-shortcut-label.spec.js';
 
 run({
+    AdwStyleClassesTest,
+    AdwShortcutLabelTest,
     AdwAboutDialogTest,
     AdwBannerTest,
     AdwButtonContentTest,

package/src/view-stack.spec.ts

@@ -2,16 +2,11 @@
 // the core suite and the NativeScript renderer assert against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers used to carry independent copies of the selection logic —
-// the same four-clause index guard, the same `findIndex` by name, the same
-// `?? ''` fallbacks — and both had drifted away from libadwaita in the same
-// ways: `visibleChildIndex = 1.5` passed the `Number.isFinite` guard and blanked
-// the entire stack, the per-page `visible` flag did not exist so the auto-pick
-// took the first page ADDED instead of the first VISIBLE one, an empty
-// `visible-child-name` was treated as "no name" by the declarative path but as a
-// legal lookup by the property path, and the auto-pick notified nothing so a
-// bound switcher needed a manual `refresh()`. Nothing failed, because nothing
-// compared them. This suite is that comparison.
+// The rules it pins, each of which both renderers had drifted from while carrying
+// independent copies of the selection logic: a non-integer index is REFUSED, not merely
+// finite-checked; the auto-pick takes the first VISIBLE page, not the first added; an
+// empty `visible-child-name` means the same thing to the declarative and the property
+// path; and the auto-pick NOTIFIES, so a bound switcher needs no manual `refresh()`.
 import { describe, expect, it } from '@gjsify/unit';
 
 import type { ViewStackVectorChange, ViewStackVectorOp, ViewStackVectorPage } from '@gjsify/adwaita-core/conformance';
@@ -33,12 +28,10 @@ interface MountedStack {
 /**
  * Mount a stack whose pages are DECLARED as markup, driving the attribute path.
  *
- * Attributes are set through `setAttribute` rather than an HTML string on
- * purpose: several vectors hinge on an exact name — the empty string, the NFD
- * spelling of `Übersicht` — which an attribute value in parsed markup is not a
- * reliable carrier for. The change listener is attached BEFORE the element is
- * connected so the auto-pick notification is observable, which is the whole
- * point of the fix that made it fire at all.
+ * Attributes go through `setAttribute` rather than an HTML string: several vectors hinge
+ * on an exact name — the empty string, the NFD spelling of `Übersicht` — which parsed
+ * markup is not a reliable carrier for. The change listener is attached BEFORE connect,
+ * so the auto-pick notification is observable at all.
  */
 function mountStack(pages: readonly ViewStackVectorPage[], visibleChildName?: string): MountedStack {
     const host = document.createElement('div');
@@ -110,10 +103,9 @@ export const AdwViewStackTest = async () => {
                 expect(stack.pages.length).toBe(vector.count);
                 expect(stack.pages[stack.visibleChildIndex]?.title ?? '').toBe(vector.visibleTitle);
 
-                // The DOM must agree with the model: exactly the selected page is
-                // shown, and nothing at all when the selection is -1. A stack that
-                // stored an unreachable index (the 1.5 bug) showed NOTHING while
-                // still reporting a selection.
+                // The DOM must agree with the model: exactly the selected page is shown,
+                // and nothing at all when the selection is -1. A stack storing an
+                // unreachable index shows NOTHING while still reporting a selection.
                 const expectedShown = vector.pages.map(() => false).slice(0, vector.count);
                 if (vector.visibleIndex >= 0) expectedShown[vector.visibleIndex] = true;
                 expect(shownPages(stack)).toStrictEqual(expectedShown);
@@ -160,11 +152,10 @@ export const AdwViewStackTest = async () => {
 
     await describe('adw-view-stack imperative pages (Adw.ViewStack.add)', async () => {
         await it('keeps pages added BEFORE the stack enters the document', () => {
-            // The regression: connectedCallback used to overwrite the page list
-            // with whatever <adw-view-stack-page> children it found — none, for
-            // imperative use — and then replaceChildren() the subtree away, so
-            // this exact order silently destroyed the caller's element.
-            // libadwaita has no parse-once phase (adw-view-stack.c:2160-2251).
+            // connectedCallback must not overwrite the page list from whatever
+            // <adw-view-stack-page> children it finds — none, for imperative use — and
+            // then replaceChildren() the subtree away, destroying the caller's element.
+            // libadwaita has no parse-once phase.
             const stack = document.createElement('adw-view-stack') as AdwViewStack;
             const content = document.createElement('div');
             content.textContent = 'learn body';
@@ -221,10 +212,9 @@ export const AdwViewStackTest = async () => {
         });
 
         await it('treats an EMPTY declared name as a legal lookup, not as "no name"', () => {
-            // The declarative path used `initialName ? … : -1`, so an explicit
-            // empty name fell through to page 0 while the PROPERTY path matched
-            // the page named '' — one port, two answers for one input.
-            // g_strcmp0("", "") is 0 (adw-view-stack.c:901).
+            // A declarative `initialName ? … : -1` sends an explicit empty name to page 0
+            // while the PROPERTY path matches the page named '' — two answers, one input.
+            // g_strcmp0("", "") is 0.
             const { stack, host } = mountStack([{ name: 'a' }, { name: '' }], '');
             expect(stack.visibleChildIndex).toBe(1);
             expect(shownPages(stack)).toStrictEqual([false, true]);
@@ -235,8 +225,7 @@ export const AdwViewStackTest = async () => {
             const { stack, host } = mountStack([{ name: 'a' }, { name: '' }]);
             expect(stack.getAttribute('visible-child-name')).toBe('a');
             stack.visibleChildIndex = 1;
-            // The old reflection was guarded by `if (current && …)`, so a stack of
-            // nameless pages never reflected its selection at all.
+            // Reflection guarded by `if (current && …)` never fires for nameless pages.
             expect(stack.getAttribute('visible-child-name')).toBe('');
             host.remove();
         });
@@ -259,9 +248,9 @@ export const AdwViewStackTest = async () => {
         });
 
         await it('does not bounce the selection back when a duplicate name is reflected', () => {
-            // Reflection writes the attribute, which re-enters
-            // attributeChangedCallback; with duplicate names a naive re-lookup
-            // would resolve to the FIRST match and undo the selection.
+            // Reflection writes the attribute and re-enters attributeChangedCallback;
+            // with duplicate names a naive re-lookup resolves to the FIRST match and
+            // undoes the selection.
             const { stack, host } = mountStack([{ name: 'dup' }, { name: 'dup' }]);
             stack.visibleChildIndex = 1;
             expect(stack.visibleChildIndex).toBe(1);

package/src/view-switcher.spec.ts

@@ -3,15 +3,9 @@
 // vectors the core suite and the NativeScript suite assert against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// The two renderers used to carry independent copies of everything a switcher
-// derives, and FIVE libadwaita rules lived in neither of them: the
-// button-visibility predicate `visible && (title != NULL || icon-name != NULL)`,
-// the `image-missing` icon fallback, the bar's `reveal && more-than-one-visible-
-// page` gate, the inline switcher's two index spaces, and the badge /
-// needs-attention label with the screen-reader description AdwIndicatorBin
-// derives from them. On top of that the browser switcher CLAMPED an out-of-range
-// index into range where libadwaita refuses. Nothing failed, because nothing
-// compared them. This suite is that comparison.
+// The suite exists to keep the two renderers from drifting: they used to carry
+// independent copies of every switcher derivation, and five libadwaita rules lived in
+// neither because nothing compared them.
 import { describe, expect, it } from '@gjsify/unit';
 
 import {
@@ -44,8 +38,8 @@ import type { AdwViewStack } from './elements/adw-view-stack.js';
 function declarePage(tag: string, page: ViewSwitcherVectorPage): HTMLElement {
     const element = document.createElement(tag);
     element.setAttribute('name', page.name);
-    // `getAttribute` returns null for an absent attribute, which IS C's NULL —
-    // so an absent or explicitly-null title must not become `title=""`.
+    // `getAttribute` returns null for an absent attribute, which IS C's NULL, so an
+    // absent or explicitly-null title must not become `title=""`.
     if (typeof page.title === 'string') element.setAttribute('title', page.title);
     if (typeof page.iconName === 'string') element.setAttribute('icon-name', page.iconName);
     if (page.visible === false) element.setAttribute('hidden', '');
@@ -77,8 +71,7 @@ function mountSwitcher(pages: readonly ViewSwitcherVectorPage[], policy?: string
     for (const page of pages) element.appendChild(declarePage('adw-view-switcher-page', page));
 
     const changes: ViewSwitcherVectorChange[] = [];
-    // The listener is attached BEFORE the element connects so the auto-pick
-    // notification is observable — the switcher used to be silent there.
+    // Attached BEFORE connect, so the auto-pick notification is observable.
     element.addEventListener('notify::visible-child', (event) => {
         const detail = (event as CustomEvent<{ index: number; name: string; title: string; interactive: boolean }>)
             .detail;
@@ -142,16 +135,14 @@ function partText(button: HTMLElement, selector: string): string | null {
 export const AdwViewSwitcherTest = async () => {
     await describe('adw-view-switcher buttons (libadwaita conformance vectors)', async () => {
         for (const vector of VIEW_SWITCHER_BUTTON_VECTORS) {
-            // A `selected: -1` row cannot be staged here: this element bundles its
-            // own stack, whose auto-pick takes the first visible page, and the only
-            // way to reach "nothing selected" is to hide every page — which would
-            // change the very `visible` flags the row is asserting. The core suite
-            // drives that row directly.
+            // `selected: -1` cannot be staged here: this element bundles its own stack,
+            // whose auto-pick takes the first visible page, and reaching "nothing
+            // selected" needs every page hidden — which changes the `visible` flags the
+            // row asserts. The core suite drives that row.
             if (vector.selected < 0) continue;
             await it(vector.rule, () => {
                 const { element, host } = mountSwitcher(vector.pages, vector.policy);
-                // The vectors carry an explicit selection; drive it through the
-                // element rather than assuming the auto-pick landed there.
+                // Drive the vector's selection rather than assume the auto-pick.
                 element.active = vector.selected;
 
                 const buttons = buttonsOf(element, '.adw-view-switcher-button');
@@ -159,11 +150,11 @@ export const AdwViewSwitcherTest = async () => {
 
                 vector.buttons.forEach((model, index) => {
                     const button = buttons[index]!;
-                    // The button-visibility rule, which BOTH ports lacked.
+                    // `visible && (title != NULL || icon-name != NULL)`.
                     expect(button.hidden).toBe(!model.visible);
                     expect(button.getAttribute('aria-selected')).toBe(String(model.selected));
                     expect(partText(button, '.adw-view-switcher-label')).toBe(model.label);
-                    // The icon node always exists and always names an icon —
+                    // The icon node always exists and always names an icon:
                     // `image-missing` when the page has none.
                     const icon = button.querySelector('.adw-icon') as HTMLElement;
                     expect(icon.classList.contains(`adw-icon--${normalizeIconName(model.iconName)}`)).toBe(true);
@@ -171,16 +162,14 @@ export const AdwViewSwitcherTest = async () => {
                     expect(button.getAttribute('aria-description')).toBe(model.description || null);
                 });
 
-                // The policy style class lives on the single `viewswitcher` node.
                 expect(element.classList.contains(vector.policy)).toBe(true);
                 host.remove();
             });
         }
 
         await it('hides a titleless, iconless button in the LAYOUT, not just visually', () => {
-            // The `[hidden]` UA rule loses to the component's own author
-            // `display: inline-flex` unless the stylesheet re-asserts it — the
-            // same cascade trap the switcher BAR was fixed for.
+            // The `[hidden]` UA rule loses to the component's own author `display:
+            // inline-flex` unless the stylesheet re-asserts it.
             const { element, host } = mountSwitcher([{ name: 'a', title: 'A' }, { name: 'b' }]);
             const buttons = buttonsOf(element, '.adw-view-switcher-button');
             expect(getComputedStyle(buttons[1]!).display).toBe('none');
@@ -202,16 +191,16 @@ export const AdwViewSwitcherTest = async () => {
                 expect(element.active).toBe(vector.selected);
                 expect(element.visibleChildName).toBe(vector.selectedName);
 
-                // The DOM must agree with the model: exactly the selected page's
-                // body is shown, and none at all when the selection is -1.
+                // Exactly the selected page's body is shown, none when the selection
+                // is -1.
                 const bodies = buttonsOf(element, '.adw-view-switcher-page');
                 const shown = bodies.map((body) => !(body as HTMLElement).hidden);
                 const expectedShown = vector.pages.map((_page, index) => index === vector.selected);
                 expect(shown).toStrictEqual(expectedShown);
 
-                // The reflected attribute must not claim a selection that was
-                // refused — the old element clamped instead, so `active="99"`
-                // silently became the last page.
+                // The reflected attribute must not claim a REFUSED selection: libadwaita
+                // refuses an out-of-range index, where clamping makes `active="99"` the
+                // last page silently.
                 expect(element.getAttribute('active')).toBe(String(vector.selected));
                 host.remove();
             });
@@ -237,8 +226,8 @@ export const AdwViewSwitcherTest = async () => {
         });
 
         await it('scopes its page query, so a nested switcher keeps its own pages', () => {
-            // Both switchers use the same tag for their pages; an unscoped
-            // querySelectorAll let the outer one adopt the inner one's.
+            // Both switchers use the same tag for their pages, so an unscoped
+            // querySelectorAll lets the outer one adopt the inner one's.
             const host = document.createElement('div');
             document.body.appendChild(host);
 
@@ -286,8 +275,7 @@ export const AdwViewSwitcherTest = async () => {
                 const { element, host } = mountInline(vector.pages, vector.displayMode);
 
                 const toggles = buttonsOf(element, '.adw-inline-view-switcher-toggle');
-                // A hidden page produces NO toggle — the whole reason the two
-                // index spaces exist. The old element made one per declared page.
+                // A hidden page produces NO toggle — why the two index spaces exist.
                 expect(toggles).toHaveLength(vector.toggles.length);
 
                 vector.toggles.forEach((model, index) => {
@@ -307,15 +295,15 @@ export const AdwViewSwitcherTest = async () => {
                     expect(toggle.getAttribute('aria-description')).toBe(model.description || null);
                 });
 
-                // Every panel still exists — only the toggles are compacted.
+                // Every panel still exists; only the toggles are compacted.
                 expect(buttonsOf(element, '.adw-inline-view-switcher-page')).toHaveLength(vector.pages.length);
                 host.remove();
             });
         }
 
         for (const vector of INLINE_TOOLTIP_VECTORS) {
-            // A NULL title has no attribute spelling that differs from an absent
-            // one, and both are covered by the toggle vectors above.
+            // A NULL title has no attribute spelling distinct from an absent one; the
+            // toggle vectors above cover both.
             if (vector.title === null) continue;
             await it(`tooltip in ${vector.displayMode} — ${vector.rule}`, () => {
                 const { element, host } = mountInline(
@@ -329,8 +317,6 @@ export const AdwViewSwitcherTest = async () => {
         }
 
         await it("defaults to 'labels' and REFUSES an unknown display mode", () => {
-            // The old element defaulted to 'both' and replaced the current mode
-            // with 'both' for any unrecognised value.
             const { element, host } = mountInline([
                 { name: 'a', title: 'A', iconName: 'go-home-symbolic' },
                 { name: 'b', title: 'B' },
@@ -360,8 +346,8 @@ export const AdwViewSwitcherTest = async () => {
             changes.length = 0;
 
             const toggles = buttonsOf(element, '.adw-inline-view-switcher-toggle');
-            // Toggle 1 is page 2 — clicking it must select the PAGE, not the
-            // toggle index, which is what the missing child-index mapping did.
+            // Toggle 1 is page 2: a click selects the PAGE, not the toggle index, which is
+            // what a missing child-index mapping would select.
             toggles[1]!.dispatchEvent(new MouseEvent('click', { bubbles: true }));
             expect(element.active).toBe(2);
             expect(element.activeToggle).toBe(1);
@@ -374,9 +360,8 @@ export const AdwViewSwitcherTest = async () => {
                 { name: 'a', title: 'A' },
                 { name: 'b', title: 'B' },
             ]);
-            // Hiding the page a switcher is showing normally moves the selection;
-            // force the "selected page is hidden" state the C sentinel exists for
-            // by hiding every OTHER page first.
+            // Hiding the shown page normally moves the selection, so reach the state the C
+            // sentinel exists for by hiding every OTHER page first.
             element.setPageVisible('a', false);
             expect(element.active).toBe(1);
             element.setPageVisible('b', false);
@@ -410,8 +395,8 @@ export const AdwViewSwitcherTest = async () => {
 
                 bar.reveal = vector.reveal;
                 expect(bar.reveal).toBe(vector.reveal);
-                // The derivation both ports skipped: a one-page stack keeps the
-                // bar collapsed however loudly the layout asks.
+                // `reveal && more-than-one-visible-page`: a one-page stack keeps the bar
+                // collapsed however loudly the layout asks.
                 expect(bar.revealed).toBe(vector.revealed);
                 expect(bar.hidden).toBe(!vector.revealed);
                 expect(getComputedStyle(bar).display).toBe(vector.revealed ? 'block' : 'none');
@@ -420,9 +405,8 @@ export const AdwViewSwitcherTest = async () => {
         }
 
         await it('keeps tracking its stack after being detached and re-inserted', () => {
-            // `disconnectedCallback` dropped the listener and `connectedCallback`
-            // only re-added it when `ref && !this._stack` — which is never true
-            // on a re-attach, so the bar stopped tracking for good.
+            // Re-adding the listener only when `ref && !this._stack` is never true on a
+            // re-attach, and the bar goes deaf.
             const host = document.createElement('div');
             document.body.appendChild(host);
 
@@ -460,9 +444,6 @@ export const AdwViewSwitcherTest = async () => {
                 scheduler: { schedule(cb: () => void, ms: number): unknown; cancel(handle: unknown): void };
             };
             const clock = createViewSwitcherClock();
-            // The seam that did not exist: the elements built their state inline
-            // with the DOM scheduler, so VIEW_SWITCHER_DRAG_VECTORS was driven by
-            // the core suite alone while a header claimed all three drove it.
             switcher.scheduler = clock;
             for (const page of pages) switcher.appendChild(declarePage('adw-view-switcher-page', page));
             switcher.setAttribute('active', String(initial));
@@ -480,9 +461,8 @@ export const AdwViewSwitcherTest = async () => {
                         continue;
                     }
                     const button = buttons[step.index];
-                    // `relatedTarget` OUTSIDE the button, which is what a real
-                    // cross-button move looks like — the internal case is the
-                    // separate test below.
+                    // `relatedTarget` OUTSIDE the button — a real cross-button move; the
+                    // internal case is tested below.
                     button?.dispatchEvent(
                         new DragEvent(step.kind === 'enter' ? 'dragenter' : 'dragleave', {
                             bubbles: true,
@@ -496,11 +476,10 @@ export const AdwViewSwitcherTest = async () => {
         }
 
         await it('a drag sliding from the icon to the LABEL does not restart the dwell', () => {
-            // The bug the vectors could not see: the element bound enter/leave on
-            // a button that CONTAINS an icon and a label, so crossing between them
-            // fired leave + enter, `ViewSwitcherDragSwitch.leave` cleared the timer
-            // and `enter` re-armed a fresh 500 ms. A drag that merely slid across
-            // the button never switched at all.
+            // A button CONTAINS an icon and a label, so crossing between them fires
+            // leave + enter; without the relatedTarget check that cleared the timer and
+            // re-armed a fresh 500 ms, so a drag across the button never switched. The
+            // vectors cannot see this.
             const pages: ViewSwitcherVectorPage[] = [
                 { name: 'one', title: 'One' },
                 { name: 'two', title: 'Two' },
@@ -524,7 +503,7 @@ export const AdwViewSwitcherTest = async () => {
 
         await it('a page attribute changed AFTER connect reaches the button', async () => {
             // `observedAttributes` without an `attributeChangedCallback` is a dead
-            // declaration; C rebinds on every page notify (adw-view-switcher.c:184-193).
+            // declaration, where C rebinds on every page notify.
             const host = document.createElement('div');
             document.body.appendChild(host);
             const switcher = document.createElement('adw-view-switcher') as AdwViewSwitcher;
@@ -537,10 +516,8 @@ export const AdwViewSwitcherTest = async () => {
                 (switcher.querySelector('.adw-view-switcher-label') as HTMLElement | null)?.textContent;
             expect(labelOf()).toBe('One');
             page.setAttribute('title', 'Renamed');
-            // A MutationObserver delivers on a MICROTASK, where GTK's `notify`
-            // is synchronous. One microtask is invisible to a user and is what
-            // the DOM offers for watching a detached node; nothing here depends
-            // on the repaint happening inside the setter.
+            // A MutationObserver delivers on a MICROTASK where GTK's `notify` is sync;
+            // nothing depends on the repaint happening inside the setter.
             await Promise.resolve();
             expect(labelOf()).toBe('Renamed');
             host.remove();
@@ -559,8 +536,8 @@ export const AdwViewSwitcherTest = async () => {
 
                 const indicator = switcher.querySelector('.adw-view-switcher-indicator') as HTMLElement;
                 expect(indicator.textContent).toBe(vector.badgeLabel);
-                // The DESCRIPTION is what a screen reader announces; a badge with
-                // no accessible text is a dot nobody hears.
+                // The DESCRIPTION is what a screen reader announces: a badge with no
+                // accessible text is a dot nobody hears.
                 const button = switcher.querySelector('.adw-view-switcher-button') as HTMLElement;
                 expect(button.getAttribute('aria-description') ?? '').toBe(vector.description);
                 host.remove();
@@ -568,11 +545,10 @@ export const AdwViewSwitcherTest = async () => {
         }
 
         await it('names the three tables that stay the core suite’s', () => {
-            // MNEMONIC and ICON are pure string derivations with no DOM surface
-            // beyond the label this suite already asserts through
-            // VIEW_SWITCHER_BUTTON_VECTORS; BUTTON_VISIBILITY and REBUILD are
-            // asserted through the rendered button set by the same table. Named
-            // so the omission is a decision rather than a gap.
+            // MNEMONIC and ICON are string derivations with no DOM surface beyond the
+            // label VIEW_SWITCHER_BUTTON_VECTORS already asserts; BUTTON_VISIBILITY and
+            // REBUILD are asserted through that table's rendered button set. Named so
+            // the omission is a decision rather than a gap.
             expect(VIEW_SWITCHER_MNEMONIC_VECTORS.length).toBeGreaterThan(0);
             expect(VIEW_SWITCHER_ICON_VECTORS.length).toBeGreaterThan(0);
             expect(VIEW_SWITCHER_BUTTON_VISIBILITY_VECTORS.length).toBeGreaterThan(0);
@@ -582,10 +558,9 @@ export const AdwViewSwitcherTest = async () => {
 
     await describe('<adw-view-switcher-bar> reveal follows the pages model, not just the selection', async () => {
         await it('retracts when a page is REMOVED without moving the selection', () => {
-            // `update_bar_revealed` re-runs on the pages model's `items-changed`
-            // (adw-view-switcher-bar.c:340). Both ports listened only on
-            // `notify::visible-child`, so the bar went stale and a manual
-            // `refresh()` was the documented workaround.
+            // `update_bar_revealed` re-runs on the pages model's `items-changed`.
+            // Listening only on `notify::visible-child` leaves the bar stale, with a
+            // manual `refresh()` as the workaround.
             const host = document.createElement('div');
             document.body.appendChild(host);
             const stack = document.createElement('adw-view-stack') as AdwViewStack;
@@ -627,13 +602,10 @@ export const AdwViewSwitcherTest = async () => {
         });
     });
 
-    // MOVING A SWITCHER MUST NOT MAKE IT DEAF.
-    //
-    // `disconnectedCallback` drops the page observer, and `connectedCallback`
-    // returned early once the element was built — so a switcher that had merely
-    // been moved between parents (a slideshow slide, a client-side route change)
-    // stopped tracking its pages permanently, and silently. Same shape as the
-    // overlay split view's ResizeObserver, and found with it.
+    // `disconnectedCallback` drops the page observer, and `connectedCallback` returned
+    // early once the element was built — so a switcher merely MOVED between parents (a
+    // slideshow slide, a client-side route change) stopped tracking its pages
+    // permanently and silently. Same shape as the overlay split view's ResizeObserver.
     await describe('adw-view-switcher — a moved switcher keeps watching its pages', async () => {
         await it('still notices a page attribute change after being re-parented', async () => {
             const from = document.createElement('div');