@gjsify/adwaita-web 0.32.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.32.0",
+    "version": "0.34.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -41,14 +41,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.32.0",
-        "@gjsify/adwaita-fonts": "^0.32.0",
-        "@gjsify/adwaita-icons": "^0.32.0",
+        "@gjsify/adwaita-core": "^0.34.0",
+        "@gjsify/adwaita-fonts": "^0.34.0",
+        "@gjsify/adwaita-icons": "^0.34.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.32.0",
-        "@gjsify/unit": "^0.32.0",
+        "@gjsify/cli": "^0.34.0",
+        "@gjsify/unit": "^0.34.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/scss/_combo_row.scss

@@ -59,6 +59,11 @@ adw-combo-row {
     // fill, making the icon theme-aware (matches libadwaita's dark theme).
     // Using background-image with a data-URI SVG would NOT resolve
     // `currentColor` in most browsers.
+    //
+    // `model_changed` (adw-combo-row.c:187-195) hides the arrow box entirely on
+    // a model of one item or none, so the row stops presenting itself as a
+    // chooser. `[data-presents-chooser='false']` below is that rule; the element
+    // publishes the attribute and disables the overlaid <select> alongside.
     &::after {
       content: "";
       display: inline-block;
@@ -76,3 +81,17 @@ adw-combo-row {
     }
   }
 }
+
+// A model with one item or none: no arrow, and the row is not activatable
+// (`model_changed`, adw-combo-row.c:187-195). Written as its own block rather
+// than a modifier inside `.adw-row-value` so the two selectors that draw the
+// arrow and the one that removes it read at the same specificity depth.
+adw-combo-row[data-presents-chooser='false'] {
+  .adw-row-value::after {
+    display: none;
+  }
+
+  select {
+    cursor: default;
+  }
+}

package/scss/_navigation_split_view.scss

@@ -1,5 +1,16 @@
 // _navigation_split_view.scss — adw-navigation-split-view styling (docked sidebar).
+//
+// Visibility is `data-pane-visible`, written by the element from
+// `update_navigation_stack` (adw-navigation-split-view.c:342-405), not from the
+// two flags. Two of that table's rules are not expressible as
+// `.collapsed.show-content`: a LONE child stays visible whatever `show-content`
+// says (:389-401), and with `sidebar-position: end` the CONTENT is the root page
+// so the sidebar is pushed ON TOP of it rather than replacing it. This file used
+// to key off the flags and got both wrong — a collapsed view with only a sidebar
+// rendered blank.
+//
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/navigationsplitview.md
+// Reference: refs/libadwaita/src/adw-navigation-split-view.c
 // Reference: refs/libadwaita/src/stylesheet/widgets/_sidebars.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Adapted for @gjsify/adwaita-web Web Components.
@@ -11,38 +22,70 @@ adw-navigation-split-view {
   min-width: 0;
   flex: 1 1 auto;
 
+  // NO background here — it comes from the `.sidebar-pane` class the element
+  // applies while DOCKED (see _panes.scss). Collapsed, libadwaita builds no
+  // pane bins at all and the sidebar is an ordinary full-window navigation
+  // page; a background nailed to this private class made it sidebar-coloured
+  // at every width.
   .adw-nsv-sidebar {
     display: flex;
     flex-direction: column;
     min-height: 0;
     flex-shrink: 0;
-    border-right: 1px solid var(--separator-color);
-    background-color: var(--sidebar-bg-color);
   }
 
+  // The container MINIMUM, as CSS spells it: `measure_uncollapsed`
+  // (adw-navigation-split-view.c:264-267) is `sidebar_min + content_min`, which
+  // a flex row reaches by itself once the content may claim its own minimum.
+  // `min-width: 0` — the flex idiom for "let this be crushed" — was here, which
+  // is how the content pane could be squeezed to nothing while the sidebar,
+  // being `flex-shrink: 0`, kept its whole width.
   .adw-nsv-content {
     display: flex;
     flex-direction: column;
-    min-width: 0;
+    min-width: min-content;
     min-height: 0;
     flex: 1 1 auto;
     background-color: var(--window-bg-color);
   }
 
-  // Collapsed (narrow): one pane at a time.
-  &.collapsed.show-content .adw-nsv-sidebar {
-    display: none;
+  // `sidebar-position: end` docks the sidebar past the content. flex `order`
+  // flips the visual order without changing the slotting DOM order.
+  &.sidebar-end {
+    .adw-nsv-content {
+      order: 1;
+    }
+
+    .adw-nsv-sidebar {
+      order: 2;
+    }
   }
 
-  &.collapsed:not(.show-content) {
-    .adw-nsv-content {
+  // THE DIVIDER FOLLOWS THE VISUAL SIDE. `_sidebars.scss:1293-1302` makes it
+  // `:dir()` × `.end`, which is the product `.sidebar-at-visual-start` carries:
+  // under RTL a `start` sidebar is drawn on the right and its divider belongs on
+  // its left edge. A fixed `border-right` drew it on the wrong side for half the
+  // four combinations.
+  &.sidebar-at-visual-start .adw-nsv-sidebar {
+    border-right: 1px solid var(--separator-color);
+  }
+
+  &:not(.sidebar-at-visual-start) .adw-nsv-sidebar {
+    border-left: 1px solid var(--separator-color);
+  }
+
+  // Collapsed: whichever pane the STACK puts on top fills the view, and the
+  // other is not rendered at all.
+  &.collapsed {
+    [data-pane-visible='false'] {
       display: none;
     }
 
-    .adw-nsv-sidebar {
+    .adw-nsv-sidebar[data-pane-visible='true'] {
       flex: 1 1 auto;
       max-width: none;
       border-right: none;
+      border-left: none;
     }
   }
 }

package/scss/_navigation_view.scss

@@ -16,9 +16,13 @@ adw-navigation-view {
   background-color: var(--window-bg-color);
   color: var(--window-fg-color);
 
-  // The page stack — fills the view; positioned so pages can stack.
+  // The page stack — fills the view when it is given a height, and MEASURES the
+  // visible page when it is not. A flex column rather than a positioning
+  // context: the page is an in-flow item, so its content reaches the view.
   .adw-navigation-view-pages {
     flex: 1 1 auto;
+    display: flex;
+    flex-direction: column;
     position: relative;
     box-sizing: border-box;
     min-height: 0;
@@ -26,11 +30,31 @@ adw-navigation-view {
   }
 
   // A single navigation page — the visible one fills the view, the rest are
-  // hidden. Positioned absolutely so a transition can overlap two pages.
+  // `display: none`.
+  //
+  // IN FLOW, not absolute. It was `position: absolute; inset: 0` under a comment
+  // saying it had to be "so a transition can overlap two pages" — but two pages
+  // never overlap here: `adw-navigation-view.ts` marks every page but the
+  // visible one `[hidden]`, which is `display: none` below, and the push
+  // animation runs on `.visible-page` alone. So the absolute positioning bought
+  // an overlap that does not happen, and what it cost was the HEIGHT: an
+  // absolutely-positioned child contributes nothing to its parent, so the page
+  // stack measured 0, the view above it measured 0, and the page — `inset: 0` of
+  // a zero-height parent — measured 0 in turn. A closed circle.
+  //
+  // Inside a window that never showed, because a definite height arrived from
+  // outside. `<adw-about-dialog>` is the case where none does: its sheet is
+  // `position: fixed` with a width and no height, exactly as
+  // `adw-about-dialog.ui` declares it (`content-width` 360, no content-height —
+  // libadwaita takes the height from the content). The whole dialog rendered
+  // invisible, with a header bar inside it genuinely measuring 47px.
+  //
+  // `flex: 1 1 auto` keeps the fill: given a height the page still grows into
+  // it; without one it reports its content.
   .adw-navigation-page {
     box-sizing: border-box;
-    position: absolute;
-    inset: 0;
+    position: relative;
+    flex: 1 1 auto;
     display: flex;
     flex-direction: column;
     overflow: auto;

package/scss/_overlay_split_view.scss

@@ -1,5 +1,21 @@
 // _overlay_split_view.scss — adw-overlay-split-view styling.
+//
+// The GEOMETRY is no longer here. It used to be four `transform: translateX(±100%)`
+// rules keyed on `.collapsed` / `.show-sidebar` / `.sidebar-end`, which can only
+// express the two END STATES of a reveal — so `show-progress` was 0 or 1, the
+// five `OVERLAY_SWIPE_*` conformance tables shipped unexercised, and the docked
+// hide slid the wrong way for an `end` sidebar because the JS wrote `marginRight`
+// whichever edge the pane was on.
+//
+// The element now writes the pane rect per frame from
+// `layoutOverlaySplitView`, which is continuous and knows the edge (including
+// under RTL, where a `start` sidebar is drawn on the RIGHT —
+// `get_start_or_end`, adw-overlay-split-view.c:227-234). What is left here is
+// what CSS genuinely owns: the box model, the stacking, and the transition that
+// smooths a programmatic toggle.
+//
 // Reference: refs/libadwaita/src/adw-overlay-split-view.c
+// Reference: refs/libadwaita/src/stylesheet/widgets/_sidebars.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as Web Component for @gjsify/adwaita-web.
 
@@ -11,38 +27,52 @@ adw-overlay-split-view {
   position: relative;
   overflow: hidden;
 
+  // NO background here. The pane colour comes from the `.sidebar-pane` /
+  // `.overlay-pane` class the element toggles (see _panes.scss), because which
+  // of the two a pane is in is exactly what decides its colour — hard-coding
+  // `--sidebar-bg-color` on this private class painted a collapsed overlay,
+  // which libadwaita puts on the window background, as though it were docked.
   .adw-osv-sidebar {
-    background-color: var(--sidebar-bg-color);
     overflow-y: auto;
     flex-shrink: 0;
-    transition: transform 0.2s ease, opacity 0.2s ease, margin 0.2s ease;
     z-index: 10;
     align-self: stretch;
+    // Only `opacity` transitions. The offset is driven per frame, so animating
+    // it here would fight the swipe: a gesture would lag its own finger.
+    transition: opacity 0.2s ease;
   }
 
+  // THE CONTAINER MINIMUM, as CSS spells it. `measure_uncollapsed`
+  // (adw-overlay-split-view.c:558-563) is `trunc(sidebar_min * progress) +
+  // content_min`, and a flex row reaches exactly that on its own PROVIDED the
+  // content is allowed to claim its own minimum: the sidebar is `flex-shrink: 0`
+  // with a `min-width` of `sidebar_min`, so the sum is the container's floor.
+  //
+  // `min-width: 0` was here instead — the flex idiom for "let this be crushed so
+  // an ellipsis can happen" — which is precisely how the content pane could be
+  // squeezed to nothing while the sidebar kept its whole width. A child that
+  // needs to truncate can still ask for `min-width: 0` itself; the PANE may not.
+  //
+  // Not computed in JS: a measured number would need the content's min-content
+  // size, which the DOM does not expose without a reflow, and the first attempt
+  // used `scrollWidth` — the pane's CURRENT width — which pinned the view at
+  // whatever it happened to be and stopped it responding to its breakpoint.
   .adw-osv-content {
     flex: 1;
-    min-width: 0;
+    min-width: min-content;
     min-height: 0;
     display: flex;
     flex-direction: column;
     align-self: stretch;
   }
 
-  // Docked mode (not collapsed) — sidebar beside content
+  // Docked — the sidebar sits in the flex row and the hidden part is taken off
+  // its own edge by a negative margin the element computes.
   &:not(.collapsed) .adw-osv-sidebar {
     position: relative;
   }
 
-  // Docked hide: slide left and collapse via opacity. Sidebar keeps its
-  // intrinsic width so internal elements don't reflow.
-  &:not(.collapsed):not(.show-sidebar) .adw-osv-sidebar {
-    transform: translateX(-100%);
-    opacity: 0;
-    pointer-events: none;
-  }
-
-  // Docked + sidebar-end — dock the sidebar to the RIGHT of the content
+  // Docked + sidebar-end — dock the sidebar to the far side of the content
   // (the Adw.OverlaySplitView { sidebar-position: end } layout). flex `order`
   // flips the visual order without changing the slotting DOM order.
   &:not(.collapsed).sidebar-end {
@@ -52,49 +82,108 @@ adw-overlay-split-view {
 
     .adw-osv-sidebar {
       order: 2;
-      border-inline-start: 1px solid var(--separator-color);
     }
   }
 
-  // Docked hide when the sidebar is on the end edge: slide RIGHT, not left.
-  &:not(.collapsed):not(.show-sidebar).sidebar-end .adw-osv-sidebar {
-    transform: translateX(100%);
+  // THE DIVIDER FOLLOWS THE VISUAL SIDE, not the logical one. `_sidebars.scss`
+  // makes it `:dir()` × `.end` (:21-39), which is exactly the product
+  // `.sidebar-at-visual-start` already carries: under RTL a `start` sidebar is
+  // drawn on the right and its divider belongs on its left edge.
+  &:not(.collapsed) {
+    .adw-osv-sidebar {
+      border-inline-end: none;
+      border-inline-start: none;
+    }
+
+    &.sidebar-at-visual-start .adw-osv-sidebar {
+      border-right: 1px solid var(--separator-color);
+    }
+
+    &:not(.sidebar-at-visual-start) .adw-osv-sidebar {
+      border-left: 1px solid var(--separator-color);
+    }
   }
 
-  // Overlay mode (collapsed) — sidebar on top of content
+  // Overlay (collapsed) — the sidebar floats above the content at the absolute
+  // offset the element writes into `left`, which is the only property that can
+  // carry a mid-swipe position.
   &.collapsed .adw-osv-sidebar {
     position: absolute;
     top: 0;
     bottom: 0;
-    left: 0;
-    transform: translateX(-100%);
-    opacity: 0;
-    pointer-events: none;
+    box-shadow: 0 0 12px rgb(0 0 0 / 25%);
   }
 
-  &.collapsed.sidebar-end .adw-osv-sidebar {
-    left: auto;
-    right: 0;
-    transform: translateX(100%);
+  // THE TWO RESTING STATES ARE CSS. Everything BETWEEN them is JS.
+  //
+  // Dropping these is what shipped the docs-site regression. The offset is
+  // driven per frame from `layoutOverlaySplitView` — but a view that has never
+  // been measured drives nothing, and an absolutely-positioned pane with no
+  // `left` resolves to `left: 0` at full opacity. So a HIDDEN sidebar was
+  // painted over the content at the wrong edge, on a page whose slideshow
+  // builds each slide inside `display: none` and moves it in, so the first
+  // measurement never arrived and this fallback was the whole rendering.
+  //
+  // Not a second copy of the arithmetic: 0% and 100% ARE the two ends the JS
+  // interpolates between, and neither of them needs a pixel to say. The element
+  // clears its inline placement whenever it has no measurement, which is what
+  // hands control back to these rules instead of stranding a stale offset.
+  &.collapsed {
+    // Revealed: flush against the edge the pane is drawn on.
+    &.sidebar-at-visual-start .adw-osv-sidebar {
+      left: 0;
+      right: auto;
+    }
+
+    &:not(.sidebar-at-visual-start) .adw-osv-sidebar {
+      left: auto;
+      right: 0;
+    }
+
+    // Hidden: entirely off that same edge, and untouchable while it is there.
+    &:not(.show-sidebar) {
+      .adw-osv-sidebar {
+        opacity: 0;
+        pointer-events: none;
+      }
+
+      &.sidebar-at-visual-start .adw-osv-sidebar {
+        left: auto;
+        right: 100%;
+      }
+
+      &:not(.sidebar-at-visual-start) .adw-osv-sidebar {
+        left: 100%;
+        right: auto;
+      }
+    }
   }
 
-  &.collapsed.show-sidebar .adw-osv-sidebar {
-    transform: translateX(0);
-    opacity: 1;
-    pointer-events: auto;
+  // Docked and hidden — the pane takes no room in the row. The JS expresses
+  // this as a negative margin so it can animate; unmeasured, the end state is
+  // simply a pane of no width.
+  &:not(.collapsed):not(.show-sidebar) .adw-osv-sidebar {
+    width: 0;
+    min-width: 0;
+    overflow: hidden;
+    opacity: 0;
+    pointer-events: none;
   }
 
-  // Backdrop — visible only in overlay mode when sidebar is open
+  // Backdrop — the click-outside shield. `hidden` is the element's, off
+  // `shieldVisible`; the OPACITY is the shadow-helper progress, so it fades with
+  // the reveal instead of appearing whole.
   .adw-osv-backdrop {
     display: none;
   }
 
-  &.collapsed.show-sidebar .adw-osv-backdrop {
+  &.collapsed .adw-osv-backdrop:not([hidden]) {
     display: block;
     position: absolute;
     inset: 0;
-    background: rgba(0, 0, 0, 0.3);
+    background: rgb(0 0 0 / 30%);
     z-index: 9;
+    transition: opacity 0.2s ease;
   }
 }
 

package/scss/_panes.scss

@@ -0,0 +1,57 @@
+// _panes.scss — `.sidebar-pane` / `.content-pane` / `.overlay-pane`.
+//
+// These are libadwaita STYLE CLASSES, not private markup of one widget. Both
+// split views document them as their CSS node tree
+// (adw-navigation-split-view.c:157-165, adw-overlay-split-view.c:136-152) and
+// both apply them to their pane bins, which makes them the supported hook an
+// app themes a pane through. They lived nowhere in this stylesheet, so each
+// split view hard-coded `--sidebar-bg-color` onto its own private pane div
+// instead — with two consequences.
+//
+// The first is that an app writing the documented selector styles nothing, and
+// gets no error saying so. Our own docs site is the evidence: every split-view
+// example carried `class="sidebar"` on the sidebar toolbar view, hand-written
+// by someone reaching for exactly this, matching no rule in the build.
+//
+// The second is a rendering defect, because the class is not constant — it is
+// how the widget says which of its states a pane is in. A collapsed overlay
+// sidebar is an `.overlay-pane`, on the WINDOW background, not the sidebar one
+// (adw-overlay-split-view.c:718-741); a collapsed navigation split view has no
+// pane bins at all, its pages being ordinary navigation pages. Painting the
+// sidebar colour at every width, as the private rules did, got both wrong.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_sidebars.scss (.sidebar-pane, .overlay-pane)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+.sidebar-pane {
+  background-color: var(--sidebar-bg-color);
+  color: var(--sidebar-fg-color);
+}
+
+// A pane nested inside another sidebar pane defers to it rather than stacking a
+// second tint (`.sidebar-pane .sidebar-pane`, _sidebars.scss). libadwaita also
+// recolours the MIDDLE pane of a three-pane setup through
+// `--secondary-sidebar-*`; that needs a split view nested in a split view to
+// mean anything, and no such composition is rendered yet, so the tokens are
+// defined (they are public API an app may already reference) and the selector
+// is left for whoever builds the composition that can test it.
+.sidebar-pane .sidebar-pane {
+  background-color: transparent;
+  color: inherit;
+}
+
+// `.content-pane` deliberately has NO rule here. libadwaita gives it no colour
+// of its own — the window shows through — and writing `transparent` would be a
+// claim, not a copy: it would override the `--window-bg-color` the navigation
+// split view sets on its own content pane for the case where the view is not a
+// window's direct child. The class is still applied, because being able to
+// select it is the point.
+
+// Collapsed: the sidebar floats ABOVE the content as a temporary panel, and
+// libadwaita gives it the window colours rather than the sidebar ones — a panel
+// over the content is not the same surface as a pane beside it.
+.overlay-pane {
+  background-color: var(--window-bg-color);
+  color: var(--window-fg-color);
+}

package/scss/_sidebar.scss

@@ -62,12 +62,19 @@ adw-sidebar {
   }
 
   // --- A single item row ---
+  //
+  // NO `width: 100%`. The list is a column flex container, so a row already
+  // stretches to it — and stretching SUBTRACTS the row's own margins, which is
+  // what puts the same 6px of air on both sides. `width: 100%` resolves against
+  // the containing block INSTEAD, which does not know about the margins, so
+  // every row came out 12px too wide: inset 6px on the left, hanging 6px past
+  // the right edge with its rounded corners cut off by the pane. Visible on any
+  // selected or hovered row, because only a filled row shows where it ends.
   .adw-sidebar-item {
     box-sizing: border-box;
     display: flex;
     align-items: center;
     gap: var(--spacing-m);
-    width: 100%;
     min-height: 36px;
     // The native row has a context menu, so padding lives on the inner box and
     // the row itself carries the menu margin + radius.

package/scss/_spinner.scss

@@ -1,32 +1,46 @@
-// _spinner.scss — adw-spinner styling (ring with a spinning arc).
+// _spinner.scss — adw-spinner styling.
+//
+// Almost nothing is left here on purpose. The ring is an SVG the element draws
+// per frame from `@gjsify/adwaita-core`'s `spinnerArc`, because the arc BREATHES
+// (2.7 to 102.8 degrees) and CSS cannot express that: the `border-top-color`
+// chase this file used to carry was a fixed 90-degree quarter-circle at 0.8s
+// against libadwaita's 1.2s, with a hardcoded grey track and square-cut ends.
+//
+// What CSS still owns is the box: the element is `size × size` and the ring is
+// centred inside it, which is how a 200px spinner shows a 64px ring
+// (adw-spinner.c:95-99 hands the widget's real size to the paintable, which caps
+// only the radius).
+//
+// There is deliberately NO `prefers-reduced-motion` rule. The C opts out of the
+// animation setting explicitly (`adw_animation_set_follow_enable_animations_setting
+// (…, FALSE)`, adw-spinner-paintable.c:537) — a frozen busy indicator reads as a
+// hang. This file used to stop the animation there.
+//
+// Reference: refs/libadwaita/src/adw-spinner.c
+// Reference: refs/libadwaita/src/adw-spinner-paintable.c
 // Reference: refs/adwaita-web/adwaita-web/scss/_spinner.scss
-// Reference: refs/libadwaita (Adw.Spinner)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Adapted for @gjsify/adwaita-web Web Components.
 
 adw-spinner {
-  display: inline-block;
+  // The element writes the measured box onto `style` when it upgrades; these are
+  // the values in force until then, which are Adwaita's own minimum
+  // (adw-spinner.c:14, reported as both minimum and natural at :78-81).
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   box-sizing: border-box;
-  // Adw.Spinner measures 16 as BOTH its minimum and its natural size
-  // (adw-spinner.c:78-81), stroked at the documented "2px for 16px". The element
-  // overwrites both from `spinnerGeometry` when it upgrades; these are the values
-  // in force until then — the 24px/3px they replace were not from any source.
   width: 16px;
   height: 16px;
-  // Neutral arc (currentColor, theme-aware) over a faint track — Adw.Spinner
-  // is a neutral indicator, NOT accent-coloured.
-  border: 2px solid rgba(127, 127, 127, 0.25);
-  border-top-color: currentColor;
-  border-radius: 50%;
-  animation: adw-spinner-spin 0.8s linear infinite;
+  // The arc strokes `currentColor` — `gtk_widget_get_color` (:432), the widget's
+  // TEXT colour, never the accent. The track is the same colour at 15%, which
+  // the SVG applies as `stroke-opacity`.
+  color: inherit;
 
-  @media (prefers-reduced-motion: reduce) {
-    animation: none;
-  }
-}
-
-@keyframes adw-spinner-spin {
-  to {
-    transform: rotate(360deg);
+  svg {
+    display: block;
+    // The ring never grows past its own diameter, so an over-large box centres
+    // it rather than stretching it.
+    flex: none;
   }
 }

package/scss/_tab_view.scss

@@ -143,19 +143,18 @@ adw-tab-view {
     }
   }
 
-  // `AdwTabPage:loading` swaps the icon image for a spinner in the same slot
-  // (adw-tab.c:178-183) — the arc geometry and the keyframes are adw-spinner's,
-  // not a second copy of them.
-  .adw-tab-icon.loading {
-    background: none;
-    mask-image: none;
-    border: 2px solid rgba(127, 127, 127, 0.25);
-    border-top-color: currentColor;
-    border-radius: 50%;
-    animation: adw-spinner-spin 0.8s linear infinite;
-
-    @media (prefers-reduced-motion: reduce) {
-      animation: none;
+  // `AdwTabPage:loading` swaps the icon image for an `AdwSpinnerPaintable`
+  // (`update_icons`, adw-tab.c:172-190) — the SAME paintable `Adw.Spinner` uses.
+  // So the tab mounts a real `<adw-spinner>` in the icon's slot and this block
+  // only places it. It used to restate `border: 2px`,
+  // `rgba(127, 127, 127, 0.25)` and `0.8s` under a comment claiming the geometry
+  // and keyframes were adw-spinner's and "not a second copy of them" — which is
+  // how it inherited every spinner defect independently.
+  .adw-tab-spinner {
+    flex: none;
+
+    &[hidden] {
+      display: none;
     }
   }
 

package/scss/_theme.scss

@@ -14,6 +14,15 @@
   --headerbar-shade-color: rgba(0, 0, 6, 0.36);
   --separator-color: rgba(255, 255, 255, 0.08);
   --sidebar-bg-color: #2e2e32;
+  --sidebar-fg-color: #ffffff;
+  --sidebar-backdrop-color: #28282c;
+  --sidebar-shade-color: rgba(0, 0, 6, 0.25);
+  --sidebar-border-color: rgba(0, 0, 6, 0.36);
+  --secondary-sidebar-bg-color: #28282c;
+  --secondary-sidebar-fg-color: #ffffff;
+  --secondary-sidebar-backdrop-color: #252529;
+  --secondary-sidebar-shade-color: rgba(0, 0, 6, 0.25);
+  --secondary-sidebar-border-color: rgba(0, 0, 6, 0.36);
   --card-bg-color: rgba(255, 255, 255, 0.08);
   --card-fg-color: #ffffff;
   --card-shade-color: rgba(0, 0, 6, 0.36);

package/scss/_variables.scss

@@ -24,8 +24,25 @@
   // draws separators, instead of a harsh near-black line on a dark surface.
   --separator-color: rgba(0, 0, 6, 0.1);
 
-  // Sidebar
+  // 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
+  // `--sidebar-fg-color` was overriding nothing.
   --sidebar-bg-color: #ebebed;
+  --sidebar-fg-color: rgba(0, 0, 6, 0.8);
+  --sidebar-backdrop-color: #f2f2f4;
+  --sidebar-shade-color: rgba(0, 0, 6, 0.07);
+  --sidebar-border-color: rgba(0, 0, 6, 0.07);
+
+  // The MIDDLE pane of a three-pane setup. Nothing renders one yet; the tokens
+  // are defined because they are public API an app may already reference, and a
+  // half-present family reads as "this one is unsupported" rather than "this
+  // composition is not built yet".
+  --secondary-sidebar-bg-color: #f3f3f5;
+  --secondary-sidebar-fg-color: rgba(0, 0, 6, 0.8);
+  --secondary-sidebar-backdrop-color: #f6f6fa;
+  --secondary-sidebar-shade-color: rgba(0, 0, 6, 0.07);
+  --secondary-sidebar-border-color: rgba(0, 0, 6, 0.07);
 
   // Cards / boxed lists
   --card-bg-color: #ffffff;