@gjsify/adwaita-web 0.40.0 → 0.42.0

package/scss/_tab_view.scss

@@ -183,7 +183,7 @@ adw-tab-view {
     background-color: var(--accent-bg-color);
   }
 
-  // --- Close affordance (CSS-drawn "×", no symbolic icon ships) ---
+  // --- Close affordance (CSS-drawn "×"; `window-close` ships, see adw-tab-view.ts) ---
   // Presence is decided in JS by `tabCloseVisible` — `(hovering && fullyVisible)
   // || selected || dragging`, and never on a pinned tab (adw-tab.c:124, :645-650)
   // — which is why the `[hidden]` rule below is load-bearing rather than cosmetic.

package/scss/_theme.scss

@@ -17,6 +17,7 @@
   --headerbar-fg-color: #ffffff;
   --headerbar-shade-color: rgba(0, 0, 6, 0.36);
   --separator-color: rgba(255, 255, 255, 0.08);
+  --shade-color: rgba(0, 0, 6, 0.25);
   --sidebar-bg-color: #2e2e32;
   --sidebar-fg-color: #ffffff;
   --sidebar-backdrop-color: #28282c;

package/scss/_toast.scss

@@ -5,7 +5,7 @@
 // up on show / down on dismiss (mirroring Adw.Toast).
 // Reference: refs/adwaita-web/adwaita-web/scss/_toast.scss
 // Reference: refs/adwaita-web/adwaita-web/scss/_toast_overlay.scss
-// Reference: refs/libadwaita/src/stylesheet/widgets/_toast.scss
+// Reference: refs/libadwaita/src/stylesheet/widgets/_misc.scss (Toasts)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Copyright (c) 2025 csm (adwaita-web). MIT License.
 // Modifications: Adapted for @gjsify/adwaita-web Web Components.
@@ -120,12 +120,14 @@ adw-toast-overlay {
     }
   }
 
-  // Close affordance — a CSS-drawn "×" (mirrors adw-tab-view's .adw-tab-close;
-  // no symbolic close icon ships in the curated adwaita-web icon set).
+  // Close affordance — `window-close-symbolic` in a 24px circle, as upstream builds it
+  // (adw-toast-widget.ui:64). The element supplies the <adw-icon>; this only places it.
   .adw-toast-close-button {
     box-sizing: border-box;
     flex-shrink: 0;
-    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
     width: 24px;
     height: 24px;
     margin: 0;
@@ -149,25 +151,5 @@ adw-toast-overlay {
       outline: 2px solid var(--accent-color);
       outline-offset: 1px;
     }
-
-    &::before,
-    &::after {
-      content: '';
-      position: absolute;
-      top: 50%;
-      left: 50%;
-      width: 11px;
-      height: 1.5px;
-      background-color: currentColor;
-      border-radius: 1px;
-    }
-
-    &::before {
-      transform: translate(-50%, -50%) rotate(45deg);
-    }
-
-    &::after {
-      transform: translate(-50%, -50%) rotate(-45deg);
-    }
   }
 }

package/scss/_toolbar_view.scss

@@ -31,6 +31,35 @@ adw-toolbar-view {
     background-color: var(--window-bg-color);
   }
 
+  // THE CONTENT WIDGET FILLS THE CONTENT RECT. `adw_toolbar_view_size_allocate`
+  // (adw-toolbar-view.c:390-397) hands `self->content` the whole rect between the
+  // bars, and a GTK widget that wants less of it says so through its own
+  // alignment. This port collects the content into a flex COLUMN, where an item
+  // declaring no `flex-grow` is content-sized instead, so the child stopped
+  // wherever its content did and the pane below it stayed empty. Measured on the
+  // docs Navigation Split View preview: a 293px sidebar pane holding a 176px
+  // `adw-sidebar`, i.e. 117px of window-coloured dead strip under the last row,
+  // and beside it a status page top-aligned in a pane it was supposed to centre in.
+  // The web storybook had been papering over it in its own sheet
+  // (`.sb-sidebar-scroll { flex: 1 1 auto }`), deleted now that the widget carries
+  // it: a per-consumer copy is what a missing widget rule looks like from the
+  // outside, and it keeps the widget green while the next consumer hits the same
+  // wall.
+  //
+  // `:only-child` because Adw.ToolbarView HAS one content widget. Several stacked
+  // children are this port's own extension, and GTK defines no distribution for
+  // them, so inventing one here would be a claim rather than a copy.
+  //
+  // NO `min-height: 0` alongside it, deliberately: the automatic minimum size is
+  // already the right answer per child. A scroller (`adw-sidebar`, any
+  // `overflow: auto` box) gets an automatic minimum of 0 and shrinks to scroll
+  // itself, as its GtkScrolledWindow would; a status page keeps its content-based
+  // minimum, so a pane too short to hold it scrolls THIS box instead of crushing a
+  // centred column into overflow its reader cannot scroll back up to.
+  .adw-toolbar-view-content > :only-child {
+    flex: 1 1 auto;
+  }
+
   // top-bar-style / bottom-bar-style: an opaque background plus a persistent
   // shadow, which `.border` swaps for a hairline (adw-toolbar-view.c:1011-1024,
   // _toolbars.scss `> .top-bar.raised`).
@@ -60,30 +89,31 @@ adw-toolbar-view {
     }
   }
 
-  // The scroll fade under a FLAT bar. libadwaita paints it on the scrolled
-  // window; the browser equivalent is a non-interactive gradient stuck to the
-  // scrollport edge, taking no space of its own — a NEGATIVE margin equal to its
-  // height (_toolbars.scss :342-343, _scrolling.scss :150-157).
-  &.undershoot-top .adw-toolbar-view-content::before,
-  &.undershoot-bottom .adw-toolbar-view-content::after {
-    content: '';
-    position: sticky;
-    height: 6px;
-    flex-shrink: 0;
-    pointer-events: none;
-  }
-
-  &.undershoot-top .adw-toolbar-view-content::before {
-    top: 0;
-    margin-bottom: -6px;
-    background: linear-gradient(to bottom, var(--headerbar-shade-color), transparent);
+  // A bar in a toolbar view is INLINE — `%headerbar-inline` → `%headerbar-flat`:
+  // no background of its own, no separator, the content's foreground
+  // (_toolbars.scss :313-317, _header-bar.scss :110-147). That is what makes a
+  // flat-style view read as ONE surface with the bar sitting in it rather than as
+  // a bar bolted on top of a pane, and it is why the shading below is the ONLY
+  // thing that ever draws a line between them.
+  //
+  // Not folded into `%headerbar` itself: a header bar used as a WINDOW titlebar
+  // keeps its own background and shade, which is what `adw-header-bar` outside a
+  // toolbar view still renders.
+  .adw-toolbar-view-top,
+  .adw-toolbar-view-bottom {
+    &:not(.raised) adw-header-bar {
+      background: none;
+      color: inherit;
+      box-shadow: none;
+    }
   }
 
-  &.undershoot-bottom .adw-toolbar-view-content::after {
-    bottom: 0;
-    margin-top: -6px;
-    background: linear-gradient(to top, var(--headerbar-shade-color), transparent);
-  }
+  // The scroll shading under a FLAT bar belongs to the SCROLLER, not to the view:
+  // upstream's selector is `toolbarview.undershoot-top scrolledwindow`, and GTK
+  // draws that node only while the scroller is off the edge. Drawn from the view
+  // instead — which is what this did — the fade is unconditional, so every flat
+  // bar sat behind a permanent hairline that native shows only after scrolling.
+  // `_scrolling.scss` + `src/scroll-shading.ts` now own it, per scroller.
 }
 
 // extend-content-to-*-edge: the content spans the full height and the bar is

package/scss/_variables.scss

@@ -24,6 +24,13 @@
   // draws separators, instead of a harsh near-black line on a dark surface.
   --separator-color: rgba(0, 0, 6, 0.1);
 
+  // The GENERIC shade the whole `*-shade-color` family below specialises
+  // (`_colors.scss:79,141`). Scroll undershoots are drawn from it, and it belongs
+  // to the palette rather than to any one widget: a scroller can sit on a window,
+  // a view, a sidebar or a card, and reading its neighbour's shade would make the
+  // same indicator four different colours.
+  --shade-color: rgba(0, 0, 6, 0.07);
+
   // Sidebar / split panes. libadwaita defines the whole family, not just the
   // background (_colors.scss:47-58), and only the background was here — so
   // `.sidebar-pane` had no foreground to name, and an app overriding
@@ -137,9 +144,29 @@
   // by AdwStyleManager from the desktop's font settings
   // (adw-style-manager.c:169-218), defaulting to `Sans 10` / `Monospace 10`
   // (:50-56). A browser has no style manager, so they are ordinary tokens here
-  // — same names, so re-theming goes through the documented contract. The
-  // monospace stack is the one `_data_grid.scss` used to inline; it has ONE home
-  // now, and Adwaita Mono heads it because `@gjsify/adwaita-fonts` ships it.
+  // — same names, so re-theming goes through the documented contract.
+  //
+  // The monospace stack has ONE home, and did not until recently: `_data_grid.scss`
+  // used to inline it, and `source-view/theme.ts` carried a SECOND, longer copy in
+  // a TS string literal (measured on one page, `.cm-scroller` resolved to
+  // 'Adwaita Mono', 'Cascadia Code', 'JetBrains Mono', … while a `.monospace`
+  // label beside it resolved to this token — two typefaces, same document).
+  // A literal in TS is also outside the `stylesheet-font-families` rule, which
+  // reads `.css`/`.scss`. Both now read this token; its consumers are
+  // `.monospace` (_labels.scss:128), `_action_row.scss:94`, the data-grid mono
+  // cell (via `@extend .monospace`) and `<adw-source-view>`.
+  //
+  // Adwaita Mono heads the stack as a PROGRESSIVE ENHANCEMENT, not because
+  // anything here ships it: `@gjsify/adwaita-fonts` vendors two Sans TTFs and no
+  // mono face at all (the upstream mono faces are 1.4-1.5 MB each). This comment
+  // used to claim the package ships it — a claim the NativeScript theme, which
+  // carries the same stack, already contradicted in prose
+  // (`nativescript-bridge/adwaita/src/theme/adwaita.css:769`). So on a GNOME
+  // desktop the system `adwaita-mono-fonts` resolves it; anywhere else the
+  // generic tail is what renders, which is the correct outcome and the reason the
+  // tail exists. Held honest by the `stylesheet-font-families` conformance rule,
+  // whose ledger carries this reason — never delete one without the other.
+  //
   // `'Cantarell'` is dropped from that stack on the way here: Cantarell is
   // GNOME's PROPORTIONAL UI font, so a monospace fallback chain that reaches it
   // second lands on a font whose figures do not line up — the exact property

package/scss/_view_switcher.scss

@@ -22,12 +22,19 @@ adw-view-switcher {
         min-height: 34px;
     }
 
-    // Each tab is a flat, transparent toggle that lights up with a subtle fill
-    // when hovered and shows the active page with an accent-tinted background.
+    // Each tab is a flat, transparent toggle that lights up with a subtle
+    // neutral fill when hovered and a slightly stronger one while selected.
     .adw-view-switcher-button {
         box-sizing: border-box;
         display: inline-flex;
         flex: 1 1 0; // homogeneous — every tab gets equal width
+        // `min-width: auto` is the flex-item default, and it floors every tab at
+        // its own min-content width, so a long title made ITS tab wider than the
+        // others and homogeneity silently stopped holding at exactly the widths
+        // where it matters. GTK's homogeneous box has no such floor
+        // (adw-view-switcher.c:475) and the labels ellipsize instead
+        // (adw-view-switcher-button.ui:42), which is what the 0 restores.
+        min-width: 0;
         align-items: center;
         justify-content: center;
         margin: 0;
@@ -63,6 +70,10 @@ adw-view-switcher {
         }
 
         .adw-view-switcher-label {
+            // Same min-content floor as the button, one level down: without it the
+            // `overflow: hidden` box never shrinks, so the ellipsis never appears
+            // and the label pushes its tab wide instead.
+            min-width: 0;
             white-space: nowrap;
             overflow: hidden;
             text-overflow: ellipsis;
@@ -99,12 +110,27 @@ adw-view-switcher {
             }
         }
 
+        // AdwViewSwitcherButton is a `.flat` GtkToggleButton
+        // (adw-view-switcher-button.ui:5-7), so its five states are
+        // `%button_basic_flat`'s currentColor alpha ladder, NOT the filled-button
+        // tokens: hover 7% / pressed 16%, and checked 10% / 13% / 19%
+        // (_buttons.scss:250-269 over _colors.scss:268-272). The same ladder the
+        // tab bar and the sidebar rows already spell out.
+        //
+        // It used to spend the FILLED-button tokens here: `--button-active-color`
+        // (.19 light / .22 dark) for the selected tab AND for its hover, and
+        // `--button-hover-color` (.13 / .15) for an unselected hover. Two defects
+        // in one rule. The selected tab sat at the shade upstream keeps for HELD
+        // DOWN, so it read as permanently pressed; and pinning its hover to that
+        // same value left the selected tab answering the pointer with nothing.
+        // Those tokens are also a FIXED rgba, so unlike the ladder they do not
+        // follow the foreground of whatever bar the switcher was dropped into.
         &:hover {
-            background-color: var(--button-hover-color);
+            background-color: color-mix(in srgb, currentColor 7%, transparent);
         }
 
         &:active {
-            background-color: var(--button-active-color);
+            background-color: color-mix(in srgb, currentColor 16%, transparent);
         }
 
         &:focus-visible {
@@ -112,15 +138,17 @@ adw-view-switcher {
             outline-offset: -2px;
         }
 
-        // The selected view — a neutral filled chip (libadwaita darkens the
-        // whole button; the icon/label keep the normal foreground colour
-        // rather than turning accent).
+        // The selected view: a neutral fill over the whole tab. libadwaita leaves
+        // the foreground alone here, so no accent recolouring of icon or label.
         &.active {
-            background-color: var(--button-active-color);
-            color: var(--window-fg-color);
+            background-color: color-mix(in srgb, currentColor 10%, transparent);
 
             &:hover {
-                background-color: var(--button-active-color);
+                background-color: color-mix(in srgb, currentColor 13%, transparent);
+            }
+
+            &:active {
+                background-color: color-mix(in srgb, currentColor 19%, transparent);
             }
         }
     }
@@ -141,8 +169,15 @@ adw-view-switcher {
         .adw-view-switcher-button {
             flex-direction: column;
             gap: 1px;
-            padding-top: 4px;
-            padding-bottom: 2px;
+            // The narrow box carries NO horizontal padding upstream: only
+            // `padding-top: 4px`, and the 3px per side plus the 2px below sit on
+            // the LABEL (_view-switcher.scss:15-24). Aggregated onto the button
+            // here because this port has no separate box node between button and
+            // label, which is the same geometry for every label at least as wide
+            // as the 16px icon. Overriding only the vertical halves left the wide
+            // policy's `2px 12px` standing, so a narrow tab spent 24px on side
+            // padding where libadwaita spends 6px.
+            padding: 4px 3px 2px;
             font-size: 0.75rem;
 
             .adw-view-switcher-label {
@@ -152,22 +187,47 @@ adw-view-switcher {
         }
     }
 
-    // The paired content area showing the active page — a card-like surface
-    // below the switcher (the web stand-in for the Adw.ViewStack body).
+    // The paired content area showing the active page: the Adw.ViewStack half of
+    // this composite, and it draws NOTHING. libadwaita's recommended arrangement
+    // is an AdwToolbarView whose top bar holds the switcher and whose `content`
+    // is the bare AdwViewStack (adw-view-switcher.c:41-73); no rule in
+    // `_view-switcher.scss`, `_toolbars.scss` or `_views.scss` frames that stack,
+    // and the standalone `adw-view-stack` element here says the same in its own
+    // words.
+    //
+    // It used to be a card: a 1px separator outline, a 12px radius, a 9px gap
+    // under the row and 12px of padding inside. On a page that gives the switcher
+    // its full width, that outline runs down the container's own left and right
+    // edges with its corners curling away from them, which reads as a broken
+    // frame rather than as a view. libadwaita has no line between the row and the
+    // content at all: a FLAT top bar (the default, adw-toolbar-view.c:731) has no
+    // background and no shade, and the only shading that ever appears is the
+    // scroller's undershoot, which `_scrolling.scss` owns per scroller for the
+    // reason `_toolbar_view.scss` records.
+    //
+    // `display: flex` is load-bearing, not decoration: this box is the stack, and
+    // `adw-view-stack` is a flex COLUMN for the same reason. Without it the box
+    // stays block-level, its child's `flex: 1 1 auto` below has no flex container
+    // to answer and is silently inert, and the visible page keeps stopping at its
+    // own text in a pane many times its height.
     .adw-view-switcher-content {
+        display: flex;
+        flex-direction: column;
         flex: 1 1 auto;
-        margin-top: var(--spacing-s);
-        padding: var(--spacing-m);
-        background-color: var(--view-bg-color);
-        border: 1px solid var(--separator-color);
-        border-radius: var(--card-radius);
+        min-height: 0;
     }
 
+    // Mirrors `.adw-view-stack-child`: the visible page is handed the whole
+    // content area, which is what lets a status page centre itself in it the way
+    // AdwViewStack allocates to its visible child.
     .adw-view-switcher-page {
         display: none;
 
         &.active-view {
-            display: block;
+            display: flex;
+            flex-direction: column;
+            flex: 1 1 auto;
+            min-height: 0;
         }
     }
 }

package/scss/adwaita-skin.scss

@@ -77,6 +77,7 @@
 @use 'password_entry_row';
 @use 'toast';
 @use 'toolbar_view';
+@use 'scrolling';
 @use 'wrap_box';
 @use 'panes';
 @use 'overlay_split_view';

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

@@ -26,6 +26,9 @@ import {
 
 import { normalizeIconName } from '@gjsify/adwaita-core';
 
+import { isIconAvailable } from './icon-registry.js';
+import { fallbackMask, maskOf } from './icon-registry.spec.js';
+
 import type { AdwActionRow } from './elements/adw-action-row.js';
 import type { AdwSwitchRow } from './elements/adw-switch-row.js';
 import type { AdwWindowTitle } from './elements/adw-window-title.js';
@@ -259,15 +262,24 @@ export const AdwActionRowsTest = async () => {
                 // 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,
-                    );
-                }
-                if (vector.endIconVisible) {
-                    expect(icons[1]!.classList.contains(`adw-icon--${normalizeIconName(vector.endIconName)}`)).toBe(
-                        true,
-                    );
+                //
+                // And the class is only HALF the answer. `external-link-symbolic` in these
+                // vectors is well formed, normalizes cleanly and gets its class — while no
+                // mask class of that name exists (it is in neither the Adwaita icon theme
+                // nor `@gjsify/adwaita-icons`), so it paints the image-missing glyph. This
+                // suite was green on that: the class-string assertion the icon work exists
+                // to end. `isIconAvailable` reads the live cascade, so it decides which of
+                // the two answers is right for THIS name instead of the test guessing.
+                for (const [index, declared, visible] of [
+                    [0, vector.startIconName, vector.startIconVisible],
+                    [1, vector.endIconName, vector.endIconVisible],
+                ] as const) {
+                    if (!visible) continue;
+                    const icon = icons[index]!;
+                    const resolved = normalizeIconName(declared);
+                    expect(icon.classList.contains(`adw-icon--${resolved}`)).toBe(true);
+                    expect(maskOf(icon)).not.toBe('none');
+                    expect(maskOf(icon) === fallbackMask()).toBe(!isIconAvailable(resolved));
                 }
                 host.remove();
             });

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

@@ -20,6 +20,7 @@ import {
     BUTTON_CONTENT_TEXT_VECTORS,
 } from '@gjsify/adwaita-core/conformance';
 import type { AdwButtonContent } from './elements/adw-button-content.js';
+import { fallbackMask, maskOf } from './icon-registry.spec.js';
 
 /** Mount a button content inside a plain Adwaita button, the way the stories do. */
 function mount(attributes: Record<string, string> = {}): {
@@ -123,13 +124,17 @@ export const AdwButtonContentTest = async () => {
                 // asked for `.adw-icon--folder-download-symbolic`, a class that has
                 // never existed, and drew an empty 16px box. `<adw-icon>` applies
                 // `normalizeIconName`, which also makes the `' '` row assertable
-                // instead of skipped: a space is not one CSS token, so it draws
-                // nothing rather than injecting a second class.
+                // instead of skipped: a space is not one CSS token, so it lands on
+                // `image-missing` — the missing icon that row's own rule records GTK
+                // drawing there, by lookup failure rather than by this branch.
                 const maskName = normalizeIconName(resolved);
-                expect(icon.classList.contains(`adw-icon--${maskName}`)).toBe(maskName !== '');
-                expect([...icon.classList].filter((c) => c.startsWith('adw-icon--')).length).toBe(
-                    maskName === '' ? 0 : 1,
-                );
+                const drawn = maskName === '' ? 'image-missing' : maskName;
+                expect(icon.classList.contains(`adw-icon--${drawn}`)).toBe(true);
+                expect([...icon.classList].filter((c) => c.startsWith('adw-icon--')).length).toBe(1);
+                // …and it DRAWS that. The class alone is what the original bug survived:
+                // applied correctly, to a name with no glyph behind it.
+                expect(maskOf(icon)).not.toBe('none');
+                expect(maskOf(icon) === fallbackMask()).toBe(drawn === 'image-missing');
                 // The image node is never hidden — `gtk_widget_set_visible` is
                 // called on the LABEL only.
                 expect(icon.hidden).toBe(false);

package/src/adw-carousel.spec.ts

@@ -9,7 +9,12 @@
 // element sets it as an inline style precisely so it stays overridable.
 import { describe, expect, it } from '@gjsify/unit';
 
-import { CAROUSEL_PAGE_AT_POSITION_VECTORS, CAROUSEL_PAGE_LIST_VECTORS } from '@gjsify/adwaita-core/conformance';
+import type { CarouselPageMeasurement } from '@gjsify/adwaita-core';
+import {
+    CAROUSEL_PAGE_ALLOCATION_VECTORS,
+    CAROUSEL_PAGE_AT_POSITION_VECTORS,
+    CAROUSEL_PAGE_LIST_VECTORS,
+} from '@gjsify/adwaita-core/conformance';
 import type { CarouselPageOp } from '@gjsify/adwaita-core/conformance';
 
 /** The carousel surface this suite drives — the element's own public API. */
@@ -62,6 +67,45 @@ function mount(labels: readonly string[], attributes: Record<string, string> = {
     return { carousel, host, track };
 }
 
+/**
+ * One page that MEASURES what a conformance row says it does. `expand` is spelled
+ * `width: 100%`, the CSS of hexpand; `flex: none` keeps the slot's own flex layout from
+ * shrinking a natural size that is wider than the carousel before it can be measured.
+ */
+function sizedCard(page: CarouselPageMeasurement, index: number): HTMLElement {
+    const element = document.createElement('div');
+    element.dataset.label = `p${index}`;
+    const width = page.expand ? '100%' : `${page.natural}px`;
+    element.style.cssText = `flex:none;height:100%;width:${width};`;
+    return element;
+}
+
+/** Mount a carousel `available` px wide whose pages measure what `pages` says. */
+function mountSized(available: number, pages: readonly CarouselPageMeasurement[]) {
+    const host = document.createElement('div');
+    host.style.cssText = `width:${available}px;height:80px;`;
+    document.body.appendChild(host);
+
+    const carousel = document.createElement('adw-carousel') as CarouselElement;
+    carousel.style.cssText = `display:block;width:${available}px;height:80px;`;
+    pages.forEach((page, index) => carousel.appendChild(sizedCard(page, index)));
+    host.appendChild(carousel);
+
+    const track = carousel.querySelector('.adw-carousel-track') as HTMLElement;
+    // Instant scrolls; snapping stays ON here, because where a page SNAPS is half of
+    // what these tests are about.
+    track.style.setProperty('scroll-behavior', 'auto');
+    return { carousel, host, track };
+}
+
+/** Each page's left edge relative to the carousel, rounded off the subpixel noise. */
+function pageEdges(carousel: HTMLElement): number[] {
+    const origin = carousel.getBoundingClientRect().left;
+    return Array.from(carousel.querySelectorAll('.adw-carousel-page')).map((slot) =>
+        Math.round(slot.getBoundingClientRect().left - origin),
+    );
+}
+
 /** The page labels in DOM order — what the user actually sees, not what the model says. */
 function domOrder(carousel: HTMLElement): string[] {
     return Array.from(carousel.querySelectorAll('.adw-carousel-page')).map(
@@ -159,6 +203,102 @@ export const AdwCarouselTest = async () => {
         }
     });
 
+    await describe('adw-carousel page allocation (libadwaita conformance vectors)', async () => {
+        // The rows the DOM can express. The element measures a RENDERED width, so a page
+        // whose MINIMUM exceeds the carousel has already been resolved by CSS before the
+        // element sees it, and a carousel with no pages has nothing to measure at all.
+        const measurable = CAROUSEL_PAGE_ALLOCATION_VECTORS.filter(
+            (vector) => vector.pages.length > 0 && vector.pages.every((page) => page.minimum === undefined),
+        );
+
+        for (const vector of measurable) {
+            await it(vector.rule, async () => {
+                const { carousel, host, track } = mountSized(vector.available, vector.pages);
+                await flush();
+
+                const widths = Array.from(carousel.querySelectorAll('.adw-carousel-page')).map((slot) =>
+                    Math.round(slot.getBoundingClientRect().width),
+                );
+                expect(widths).toStrictEqual(vector.pages.map(() => vector.pageSize));
+                // The half-gap is the track's own padding, which is what lets the page
+                // strip start inside the carousel instead of flush against its edge.
+                expect(Math.round(Number.parseFloat(getComputedStyle(track).paddingInlineStart))).toBe(
+                    vector.leadingInset,
+                );
+                host.remove();
+            });
+        }
+
+        await it('shows the previous and next page at the edges', async () => {
+            // THE REPORTED DEFECT. With `flex: 0 0 100%` the pages of the Carousel story
+            // (440px cards in a 480px carousel) filled the width and both neighbours sat
+            // entirely off screen, where GTK leaves 20px of each showing.
+            const pages: CarouselPageMeasurement[] = [{ natural: 440 }, { natural: 440 }, { natural: 440 }];
+            const { carousel, host } = mountSized(480, pages);
+            await flush();
+
+            // At rest on page 0: centred, with page 1 starting 20px before the right edge.
+            expect(pageEdges(carousel)).toStrictEqual([20, 460, 900]);
+
+            carousel.scrollToPage(1);
+            await flush();
+            // Page 1 centred, 20px of page 0 showing at the left and 20px of page 2 at the right.
+            expect(pageEdges(carousel)).toStrictEqual([-420, 20, 460]);
+            host.remove();
+        });
+
+        await it('leaves the LAST page room to centre as well', async () => {
+            // The trailing half-gap is track padding too. A scroll container that dropped
+            // its end padding would stop `leadingInset` short of the last snap point, and
+            // the last page would never reach the middle.
+            const pages: CarouselPageMeasurement[] = [{ natural: 440 }, { natural: 440 }, { natural: 440 }];
+            const { carousel, host, track } = mountSized(480, pages);
+            await flush();
+
+            carousel.scrollToPage(2);
+            await flush();
+            expect(Math.round(track.scrollLeft)).toBe(880);
+            expect(carousel.currentPage).toBe(2);
+            expect(pageEdges(carousel)).toStrictEqual([-860, -420, 20]);
+            host.remove();
+        });
+
+        await it('re-aims the scroll in flight instead of rewinding it', async () => {
+            // Mounted inside a HIDDEN ancestor, which is how real markup reaches this:
+            // `connectedCallback` measures 0, so the declared position waits for a
+            // layout, and revealing the host delivers the pending-position observer and
+            // the layout observer in ONE resize pass. The first fires a scroll to page
+            // 2 at the fallback pitch; the second narrows the pages and has to put the
+            // offset back, and `state.position` is still 0 there, because the `scroll`
+            // event that will teach it 2 fires a frame later. Restoring THAT parks the
+            // carousel on page 0 and swallows `position="2"`. GTK re-aims instead: it
+            // pushes the recomputed snap point into the running animation (:786-788).
+            //
+            // A carousel already laid out when it is mounted does NOT reach this: it
+            // allocates during `connectedCallback` and the pending observer never
+            // arms, which is why the mounted-visible spelling of this test passes
+            // either way and is not the one kept.
+            const host = document.createElement('div');
+            host.style.cssText = 'width:480px;height:80px;display:none;';
+            document.body.appendChild(host);
+
+            const carousel = document.createElement('adw-carousel') as CarouselElement;
+            carousel.style.cssText = 'display:block;width:480px;height:80px;';
+            carousel.setAttribute('position', '2');
+            for (let index = 0; index < 3; index++) carousel.appendChild(sizedCard({ natural: 440 }, index));
+            host.appendChild(carousel);
+            await flush();
+
+            host.style.display = 'block';
+            await flush();
+
+            const track = carousel.querySelector('.adw-carousel-track') as HTMLElement;
+            expect(Math.round(track.scrollLeft)).toBe(880);
+            expect(carousel.currentPage).toBe(2);
+            host.remove();
+        });
+    });
+
     await describe('adw-carousel page lookup (libadwaita conformance vectors)', async () => {
         for (const vector of CAROUSEL_PAGE_AT_POSITION_VECTORS) {
             // Only rows whose snap points are a settled page list are reachable through