@mkbabb/glass-ui 4.1.0 → 5.0.0

package/src/styles/dock/morph.css

@@ -53,12 +53,26 @@
         --dock-expand-t: 0;
     }
 
-    .glass-dock.expanded[data-morphing],
-    .glass-dock.always-expanded[data-morphing] {
+    /* BG.W-DOCK-PANE-OVERLAP (F3.R2, box axis) — the `[data-morphing]` derivation arms
+       are gated `:not([data-pane-swap])`. During a NESTED `<DockLayerGroup>` pane swap the
+       orchestrator arms `[data-pane-swap]` (dockMorphContext.ensureSpringRunning), so these
+       arms DO NOT match and `--dock-expand-t` falls back to the static class endpoint above
+       (`.expanded` → 1). The plate box (`--dock-live`, layers.css) + the root chrome
+       (bg/border/padding/blur, below) therefore HOLD at the expanded look while
+       `--dock-morph-t` still glides 0→1 for the overlapped crossfade + the inner stagger
+       (both read `--dock-morph-t` directly, unaffected by this pin). A pane swap on an
+       already-expanded nested dock no longer collapses the plate to the 53.68px pill (the
+       §2.2 box-dips-below-both-endpoints defect). The OUTER collapse↔expand pair carries no
+       `[data-pane-swap]`, so its box morph is byte-identical to HEAD. The inner
+       `.dock-layer-stack`/`.dock-layer--summary` `--dock-expand-t` writes are DESCENDANT
+       overrides (still `[data-morphing]`-gated, unscoped) so the stagger/summary reveal is
+       untouched. */
+    .glass-dock.expanded[data-morphing]:not([data-pane-swap]),
+    .glass-dock.always-expanded[data-morphing]:not([data-pane-swap]) {
         --dock-expand-t: var(--dock-morph-t);
     }
 
-    .glass-dock.collapsed[data-morphing] {
+    .glass-dock.collapsed[data-morphing]:not([data-pane-swap]) {
         --dock-expand-t: calc(1 - var(--dock-morph-t));
     }
 
@@ -76,8 +90,20 @@
         --dock-reveal-blur: 0px; /* resting: CRISP — no own-pixel self-blur */
     }
     .glass-dock[data-morphing] {
-        --dock-reveal-blur: 3px; /* the transient decongest bloom — mid-morph only */
-        filter: blur(calc(var(--dock-reveal-blur) * (1 - var(--dock-expand-t, 1))));
+        /* BD.W-DOCK-CORE (A4) — the blur DIAL-BACK. The peak drops 3px → 1.25px AND the
+           decay is FRONT-LOADED: the `clamp(0, (0.5 - expand-t)/0.5, 1)` ramp drives the
+           blur 1.25px → 0 as expand-t crosses 0 → 0.5, then HOLDS 0 for the back half — a
+           brief decongest FLASH, crisp by the morph's midpoint (the icons never read soft
+           through the slow grow). The resting self-blur stays 0px (above, untouched). The
+           9px BACKDROP blur (the material) is untouched — only the OWN-pixel self-blur is
+           dialed. PRM → 0 (the carve below). */
+        --dock-reveal-blur: 1.25px; /* the transient decongest bloom — mid-morph only */
+        filter: blur(
+            calc(
+                var(--dock-reveal-blur) *
+                    clamp(0, calc((0.5 - var(--dock-expand-t)) / 0.5), 1)
+            )
+        );
     }
 
     /* The morphing root chrome — background / border-color interpolate between the
@@ -91,10 +117,15 @@
        (0 collapsed / 1 expanded) so the resting look is exact.
        AZ.W-DOCK-TAXONOMY — the `variant-dock` class is gone; `.glass-dock:not(.vertical)`
        IS the horizontal dock now (no second-way to express orientation). */
-    .glass-dock:not(.vertical) {
+    /* BI.W-DOCK-SPINE — the collapsed↔expanded SURFACE interp retargeted onto the L0
+       `.dock-plate` (the box is structural; the plate is the glass). The interp still
+       reads the SAME `--dock-expand-t` scalar + the inheriting `--glass-tint-*` tokens;
+       only the paint target moves to the plate so the box carries no competing bg. */
+    .glass-dock:not(.vertical) .dock-plate {
         /* AY.W-A11Y-PERF O-1 / AZ.W-ADAPTIVE-AUTO Arm 1 — BOTH morph endpoints compose
            the W55 oklab adaptive tint so the self-engage darken (the unconditional
-           `:where(.glass-dock)` rule below re-points the element-level
+           `:where(.glass-dock)` rule in the sibling adaptive-legibility.css partial
+           re-points the element-level
            `--glass-tint-source`/`--glass-tint-strength`) reaches the LIVE
            horizontal dock surface in BOTH the expanded AND the COLLAPSED look (this
            0,3,0 morph interp OVERRIDES the 0,1,0 shell.css bg, so the tint must be
@@ -111,7 +142,7 @@
                 var(--glass-bg-dock, var(--glass-bg-resting)),
                 var(--glass-tint-source) var(--glass-tint-strength)
             )
-                calc(var(--dock-expand-t, 1) * 100%),
+                calc(var(--dock-expand-t) * 100%),
             color-mix(
                 in oklab,
                 var(--glass-bg-wash),
@@ -121,7 +152,7 @@
         border-color: color-mix(
             in srgb,
             var(--glass-border-dock, var(--glass-border-resting))
-                calc(var(--dock-expand-t, 1) * 100%),
+                calc(var(--dock-expand-t) * 100%),
             var(--glass-border-floating)
         );
     }
@@ -140,7 +171,10 @@
        the rest endpoints `--dock-expand-t` resolves to the class value (0 collapsed
        / 1 expanded), so the resting look is exact — byte-equivalent to the shell.css
        static plate it supersedes during the morph. */
-    .glass-dock.vertical {
+    /* BI.W-DOCK-SPINE — the VERTICAL surface interp retargeted onto `.dock-plate`
+       (0,3,0 — wins over shell.css's static `.glass-dock.vertical .dock-plate` during the
+       morph). */
+    .glass-dock.vertical .dock-plate {
         background: color-mix(
             in srgb,
             color-mix(
@@ -148,7 +182,7 @@
                 var(--glass-bg-dock, var(--glass-bg-wash)),
                 var(--glass-tint-source) var(--glass-tint-strength)
             )
-                calc(var(--dock-expand-t, 1) * 100%),
+                calc(var(--dock-expand-t) * 100%),
             color-mix(
                 in oklab,
                 var(--glass-bg-wash),
@@ -158,7 +192,7 @@
         border-color: color-mix(
             in srgb,
             var(--glass-border-dock, var(--glass-border-wash))
-                calc(var(--dock-expand-t, 1) * 100%),
+                calc(var(--dock-expand-t) * 100%),
             var(--glass-border-floating)
         );
     }
@@ -203,7 +237,7 @@
         padding-inline: calc(
             var(--dock-pad-collapsed) +
                 (var(--dock-padding-inline, 0.5rem) - var(--dock-pad-collapsed)) *
-                var(--dock-expand-t, 1)
+                var(--dock-expand-t)
         );
     }
 
@@ -232,7 +266,7 @@
         padding-block: calc(
             var(--dock-pad-collapsed) +
                 (var(--dock-padding-block, 0.375rem) - var(--dock-pad-collapsed)) *
-                var(--dock-expand-t, 1)
+                var(--dock-expand-t)
         );
     }
 
@@ -326,6 +360,27 @@
         margin-inline-start: 0;
     }
 
+    /* BD.W-DOCK-CORE (A5) — the collapsed persistent pill centers its single glyph on
+       BOTH axes (the empty-summary case where the #persistent control IS the collapsed
+       circle). The `--dock-control-safe-inset` padding (background-clip: content-box) must
+       not shift the glyph off the pill's geometric center — `place-items: center`
+       belt-and-braces both axes so the shrunken icon reads dead-center (A5 "icons in the
+       SHRUNKEN state are NOT ALIGNED"). */
+    .glass-dock.collapsed:has(.dock-layer--summary:empty) .dock-persistent {
+        display: grid;
+        place-items: center;
+    }
+    .glass-dock.collapsed:has(.dock-layer--summary:empty) .dock-persistent > * {
+        place-self: center;
+    }
+    /* BD.W-DOCK-CORE (A5) — floor the collapsed glyph at the 16px-min the rail glyph
+       carries (never a sliver inside an inline-flex column). */
+    .glass-dock.collapsed .dock-persistent svg,
+    .glass-dock.collapsed .dock-layer--summary svg {
+        min-width: 1rem;
+        min-height: 1rem;
+    }
+
     /* AW.W3 — the collapsed-hover scale rides the unified dock spring vocabulary.
        The `scale var(--dock-motion-resize)` arm was added to the `.glass-dock`
        root transition above, so this hover scale settles on the SAME spring curve
@@ -347,9 +402,13 @@
        (background/border/shadow) stay on the bare `:hover` (they don't multiply
        geometry, so a hovered collapse keeps its hover read without the pop). */
     .glass-dock.collapsed:hover {
+        box-shadow: var(--shadow-dock-override, var(--shadow-dock));
+    }
+    /* BI.W-DOCK-SPINE — the collapsed-hover surface lift retargeted onto the plate
+       (the box keeps the box-shadow elevation above; the plate carries the glass). */
+    .glass-dock.collapsed:hover .dock-plate {
         background: var(--glass-bg-wash);
         border-color: var(--glass-border-floating);
-        box-shadow: var(--shadow-dock-override, var(--shadow-dock));
     }
 
     .glass-dock.collapsed:hover:not([data-morphing]) {
@@ -368,7 +427,8 @@
      * thumb halo) via `useOptionalDockContext().held` for cross-substrate
      * coordination (typed-key canonical shape; O.W2 invariant 25).
      */
-    .glass-dock[data-held] {
+    /* BI.W-DOCK-SPINE — the held-tier surface lift retargeted onto the plate. */
+    .glass-dock[data-held] .dock-plate {
         /* AX.W55 — the held tier threads the oklab tint wrapper (zero-delta at the
            `0%` rest default) so the adaptive darken reaches the held state too. */
         background: color-mix(
@@ -379,121 +439,17 @@
         border-color: var(--glass-border-floating, var(--glass-border-resting));
         transition:
             background var(--duration-fast) var(--ease-standard),
-            border-color var(--duration-fast) var(--ease-standard),
-            box-shadow var(--duration-fast) var(--ease-standard);
+            border-color var(--duration-fast) var(--ease-standard);
     }
 
-    /* AQ.W3 §W3.1b — open-descendant surface response. When a dock-hosted
-       trigger (`[data-state="open"]`) is open, the dock root holds its elevated
-       read natively (no consumer JS). Idempotent with `[data-held]` above (same
-       floating paint, different trigger). Decorative; `:has()` Baseline Widely. */
-    .glass-dock:has([data-state="open"]) {
-        /* AX.W55 — same oklab tint wrapper as `[data-held]` (zero-delta at rest). */
-        background: color-mix(
-            in oklab,
-            var(--glass-bg-floating, var(--glass-bg-resting)),
-            var(--glass-tint-source) var(--glass-tint-strength)
-        );
-        border-color: var(--glass-border-floating, var(--glass-border-resting));
-    }
-
-    /* ── Adaptive legibility: SELF-ENGAGE the dock over a light backdrop by default
-       (AZ.W-ADAPTIVE-AUTO Arm 1 — the literal G2 surface; "Glass dock over VERY
-       LIGHT materials is unreadable, darken DYNAMICALLY like iOS 27") ─────────────
-       The dock floats over WHATEVER the consumer painted — frequently a light/near-
-       white app surface (the canonical G2 case the user reported). AY.W-A11Y-PERF
-       O-1 set `--glass-backdrop: light` on the dock's OWN root (shell.css) intending
-       a self-darken, but CSS style queries NEVER self-match (the `@container
-       style()` block below reads an ANCESTOR — verified on Chrome 148), so the
-       self-declaration was a NO-OP. This `:where(.glass-dock)` rule is the genuine
-       UNCONDITIONAL self-engage — mirroring the overlay band's `ladder.css:169` —
-       re-pointing the INHERITING tint tokens DIRECTLY on the dock root so the
-       shell (`--glass-bg-dock`), chassis-strip, and held/open tiers (which compose
-       the oklab tint AT THE ELEMENT — the substitution-vs-inheritance-safe targets)
-       darken toward warm-ink in lockstep. `--dock-fg-on-aurora` re-points to the
-       warm-ink here too — ONE reconciled path, the foreground twin folded in (it
-       reaches the dock CONTROLS' glyph/label color). Over a DARK page the darken is
-       sub-perceptual; a dark-substrate consumer opts out via `--glass-tint-strength:
-       0%` on the dock root. The morph-root interp (`.glass-dock:not(.vertical)`
-       above) stays `color-mix(in srgb …)` for the transition — the adaptive darken
-       rides its RESTING endpoint (`--glass-bg-dock`), the in-flight morph frames are
-       sub-perceptual (the ratified resting-endpoint-only default). The muted body
-       register lifts to the full warm-ink under the engaged plate (the muted L40
-       tier cannot clear 4.5:1 on a translucent darkened plate — darkening moves the
-       plate TOWARD muted's own luminance; the low-contrast muted register is
-       inappropriate over a busy glass plate, so it resolves to the legible dark
-       ink, which clears ~10:1). */
-    :where(.glass-dock) {
-        --glass-tint-source: var(--glass-tint-ink);
-        /* BC.W-ADAPTIVE-RECONCILE — the dock JOINS the continuous observer driver (the
-           literal G2 surface: "darken DYNAMICALLY like iOS 27"). The dock's own
-           `useGlassBackdropLuminance` observer samples the threaded `:background-canvas`
-           (aurora/blob) and WRITES `--glass-backdrop-luma`; this clamp READS it and lerps
-           the plate from the warm-cream floor toward the ≤24% AA ceiling as the field
-           brightens past the knee — deepening over a bright bleed, lifting translucent over
-           a dark trough (the SAME clamp the content/overlay tiers get — ONE axis/driver/
-           signal; the discrete `@container` bucket RETIRED). Calm (luma ≤ knee) → floor. */
-        --glass-tint-strength: clamp(
-            var(--glass-tint-strength-floor),
-            calc(
-                var(--glass-tint-strength-floor) +
-                (var(--glass-tint-strength-aa) - var(--glass-tint-strength-floor)) *
-                max(0, (var(--glass-backdrop-luma, 0) - var(--glass-backdrop-luma-knee, 0.6)) / (1 - var(--glass-backdrop-luma-knee, 0.6)))
-            ),
-            var(--glass-tint-strength-aa)
-        );
-        --dock-fg-on-aurora: var(--glass-tint-ink);
-        --muted-foreground: var(--foreground);
-    }
+    /* BD.W-DOCK-CORE (A7) — the whole-plate open-descendant recolor is DELETED (clean
+       break, no alias). HEAD repainted the ENTIRE dock plate to the floating tier when ANY
+       descendant overlay opened (a dropdown/select/popover) — 44%α warm-cream → 80.8%α
+       floating, the user's "a dropdown changes the color of the ENTIRE dock" bug. A
+       dropdown opening now leaves the dock plate INVARIANT; the open affordance is
+       TRIGGER-scoped (the trigger's own `[aria-expanded]`/`[data-state=open]` active-fill
+       in dock-controls/triggers.css). The `[data-held]` (slider-drag) lift above is KEPT —
+       a legitimate held-cursor cue, not the bug. */
 
-    /* The ancestor-querying `@container` block KEPT — it reaches the DESCENDANT
-       nested-glass surfaces inside a dock when a consumer marks `--glass-backdrop:
-       light` on the dock's ancestor (the self-engage above re-points only the dock
-       root's own inheriting tokens; a consumer's explicit ancestor bucket still
-       cascades to nested glass through this block). */
-    @container style(--glass-backdrop: light) {
-        .glass-dock {
-            --glass-tint-source: var(--glass-tint-ink);
-            --glass-tint-strength: var(--glass-tint-strength-aa);
-            --dock-fg-on-aurora: var(--glass-tint-ink);
-        }
-    }
-
-    /* AX.W55 — the `contrast-color()` flip for the dock control foreground (Chrome
-       147+/Safari 26+; progressive enhancement, NEVER the load-bearing floor). The
-       declarative bucket above already carries AA on all engines (it darkens the dock
-       plate so the warm-dark `--dock-fg-on-aurora` clears ~17:1 over white at the 18%
-       floor). On a supporting engine `contrast-color()` REFINES the control ink,
-       anchored on the LIGHT BACKDROP signal (`--card`, the warm-white surface base the
-       bright bucket implies) — `contrast-color(var(--card))` resolves to the legible
-       DARK ink. Anchoring on the dark ink instead inverts to white (illegible on the
-       still-light dock plate), so the anchor is the light surface, matching the rung
-       refinement in glass.css. The bucket is the floor; this is the native pick. */
-    @supports (color: contrast-color(white)) {
-        /* The SELF-ENGAGED dock refinement (the unconditional self-engage above);
-           progressive enhancement only — the declarative darken is the AA floor. */
-        :where(.glass-dock) {
-            --dock-fg-on-aurora: contrast-color(var(--card));
-            --muted-foreground: contrast-color(var(--card));
-        }
-        @container style(--glass-backdrop: light) {
-            .glass-dock {
-                --dock-fg-on-aurora: contrast-color(var(--card));
-            }
-        }
-    }
 }
 
-/* BB.W-LIQUID-REVEAL — the dock-expand bloom beat's blur-settle is OFF under
-   `prefers-reduced-motion: reduce` (the vestibular floor): a reduced-motion dock reads
-   crisp at every state, no in-between blur frames.
-   BC.W-DOCK-SHRINK-BLUR — the self-blur is now gated to `[data-morphing]`, so the PRM
-   carve zeroes it on the ARMED scope too (specificity 0,2,0) — a PRM dock that briefly
-   arms `[data-morphing]` carries no 3px bloom; the resting `.glass-dock` is already
-   crisp by the re-gate. */
-@media (prefers-reduced-motion: reduce) {
-    .glass-dock,
-    .glass-dock[data-morphing] {
-        --dock-reveal-blur: 0px;
-    }
-}

package/src/styles/dock/overflow.css

@@ -1,81 +1,121 @@
 /* dock/overflow.css — the OVER-cap overflow strategies (AX.W06 carve).
  *
  * Carved from the dock.css god-module (slice 25). This partial owns the
- * `overflow=` axis: the `overflow="scroll"` inline/block scroll ports
- * (`.dock-scroll-x` / `.dock-scroll-y`, hidden scrollbar, momentum-trapped), the
- * W04 CONTENT-DRIVEN `overflow="wrap"` intrinsic-flex recipe (the
- * `.dock-overflow-wrap` pill↔card radius + floating-tier elevation morph on the
- * ONE `--dock-expand-t` scalar — RELOCATED verbatim, never re-authored), and the
- * W45 D15 single coarse-pointer `--dock-scale` multiplier.
+ * `overflow=` axis: the HORIZONTAL inline scroll port (`.dock-scroll-x`, hidden
+ * scrollbar, momentum-trapped), the W04 CONTENT-DRIVEN `overflow="wrap"`
+ * intrinsic-flex recipe (the `.dock-overflow-wrap` pill↔card radius + floating-
+ * tier elevation morph on the ONE `--dock-expand-t` scalar — RELOCATED verbatim,
+ * never re-authored), and the W45 D15 single coarse-pointer `--dock-scale`
+ * multiplier.
  *
- * @import-ed by dock.css in cascade order, in the SAME `@layer components` — the
- * carve is isomorphic (same layer, same source order → ZERO visual delta). */
+ * BI.W-DOCK-OVERFLOW — the GREENFIELD native scroll track (PASS-1 §2.5). A capped
+ * axis is INTRINSICALLY a scroll axis: `.dock-scroll-x` is emitted on EVERY
+ * horizontal dock (scrollClass in useDockShellProps), and the VERTICAL block-axis
+ * scroll folds into the unconditional cap-derived rule in shell.css. The clip-era
+ * band-aids RETIRE (clean break): the cross-axis `overflow-clip-margin` fudge + the
+ * NO-OP `overflow-y: clip` pin + the `.dock-layers` re-clip are GONE — post-SPINE the
+ * L0 `.dock-plate` `clip-path` owns the silhouette, the L1 controls run is
+ * `overflow: visible`, and the scroll port clips ONLY its own over-cap inline content.
+ * Two EXCLUSIVE modes (PASS-4B ruling 1, never composed): FITS (`:not([data-dock-
+ * overflow])`) is `overflow-x: visible` + `mask-image: none` (the fisheye's branch);
+ * OVERFLOW (`[data-dock-overflow]`, set by `useDockOverflowFit`'s RO) is
+ * `overflow-x: auto` + the `<FadingScroll>` edge mask, fisheye OFF. The cross axis is
+ * honestly `visible` (the ring-room reserved via the `--dock-scroll-safe-inset`
+ * padding/negative-margin no-clip idiom — T-52 b), and `scroll-padding-inline` gutters
+ * the `scrollIntoView` recenter.
+ *
+ * @import-ed by dock.css in cascade order, in the SAME `@layer components`. */
 
 @layer components {
-    /* ── Scroll-on-overflow opt-in (GlassDock `overflow="scroll"`) ───────
-       The default contract grows-to-fit then overflows visibly past the
-       axis cap. `overflow="scroll"` instead makes the dock the scroll port
-       on its layout axis, pairing the existing cap with a hidden-scrollbar
-       scroll region so over-cap content stays reachable. The rounded pill
-       masks the scroll edge; both axes keep their cap. */
+    /* ── The native inline scroll TRACK (BI.W-DOCK-OVERFLOW, PASS-1 §2.5) ──
+       The GREENFIELD overflow facility: a DISTINCT inner scroll track. The
+       clip-era band-aids are GONE (the `overflow-clip-margin` cross-axis fudge +
+       the NO-OP `overflow-y: clip` pin + the `.dock-layers` re-clip that fought
+       the SPINE L1 `overflow: visible` run) — the plate's `clip-path` (dock.css)
+       owns the dock silhouette, the L1 controls run is `overflow: visible`, and
+       the scroll port clips ONLY its own over-cap content on the inline axis.
+       Two EXCLUSIVE modes, NEVER composed (PASS-4B ruling 1):
 
-    /* Inline axis (horizontal docks). The active layer becomes the scroll
-       port: `min-width: 0` releases the flex item's `min-content` floor so
-       it can shrink under the clamped `.dock-layers` track, then `overflow-x:
-       auto` scrolls its over-cap content. `.dock-layers` must KEEP clipping
-       so the pill's rounded edge masks the scroll boundary — hence the
-       grow-mode `overflow-x: visible` (`.dock-layers`, above) is overridden
-       back to `hidden` here. */
-    .glass-dock.dock-scroll-x.expanded:not(.dock-overflow-wrap) > .dock-layers {
-        overflow-x: hidden;
-    }
+         • FITS (default — `:not([data-dock-overflow])`): the row fits the cap, so
+           the port is `overflow-x: visible` (no scroll) and its `mask-image` is
+           `none` (T-52 a — no fade, no 0px-fade transparent-stop shave). The
+           fits-branch fisheye (fisheye.css) is FREE to scale its hump over the
+           `overflow: visible` L1 run.
+         • OVERFLOW (`[data-dock-overflow]`, set by `useDockOverflowFit`'s RO — ZERO
+           scroll listener, G9/O5): the row exceeds the cap, so the port is
+           `overflow-x: auto` (native inline scroll) with the `<FadingScroll>` edge
+           mask; fisheye is OFF (the `:not([data-dock-overflow])` gate). */
 
-    .glass-dock.dock-scroll-x .dock-layer--full {
+    /* min-width:0 releases the flex `min-content` floor so the active full layer
+       can shrink under the `--dock-max-inline-size`-clamped `.dock-layers` track
+       and become the scroll port on the overflow branch. */
+    .glass-dock.dock-scroll-x:not(.dock-overflow-wrap) .dock-layer--full {
         min-width: 0;
+        /* FITS default: no scroll, no mask — the cross axis is honestly `visible`
+           (SPINE: nothing clips the L1 run). T-52(a): `mask-image: none` at rest so
+           the 0px-fade transparent stop can never antialias-shave a flush item's
+           focus-ring arc. */
+        overflow-x: visible;
+        overflow-y: visible;
+        mask-image: none;
+    }
+
+    /* OVERFLOW branch — the native scroll track + the FadingScroll edge mask. */
+    .glass-dock.dock-scroll-x[data-dock-overflow]:not(.dock-overflow-wrap)
+        .dock-layer--full {
         overflow-x: auto;
-        /* BA.W-DOCK-GEOMETRY (DC-1) — PIN the CROSS (block) axis explicitly
-           `visible`. A single-axis `overflow-x: auto` makes the OTHER axis compute
-           from `visible` to `auto` (the MDN single-axis-clip-degrades caveat), so
-           the 40px-tall block axis would clip the 1.1× hover / full active control
-           circle top+bottom — the lozenge. Pinning `overflow-y: visible` keeps the
-           block axis genuinely un-clipped so a control's inset plate paints past the
-           track; the inline scroll port (the real over-cap content axis) is
-           untouched. */
+        /* The cross (block) axis is honestly `visible` in SOURCE. `overflow-x: auto`
+           spec-forces the computed cross axis to a clip, so the RING-ROOM is reserved
+           the canonical no-clip scroll-strip way (T-52 b): a `--dock-scroll-safe-inset`
+           PADDING on all sides (the flush item's focus ring paints INSIDE the padded
+           clip box — all four arcs whole) pulled back by an EQUAL negative MARGIN so
+           the dock's own layout is byte-unchanged. The inline pad ALSO reserves the
+           first/last item's inline ring arc + anchors the mask AA seam in the gutter,
+           so even at a scroll extreme (fade 0) a flush item is never shaved. */
         overflow-y: visible;
+        padding: var(--dock-scroll-safe-inset);
+        margin: calc(-1 * var(--dock-scroll-safe-inset));
+        /* The recenter gutter — `scrollIntoView({inline:'nearest'})` (useSelectionGroup,
+           on every select) lands a selected member with ≥1px port slack (O1). */
+        scroll-padding-inline: var(--dock-scroll-gutter);
         scrollbar-width: none;
-        /* Trap the inline-scroll momentum at the dock's own boundary so a
-           wheel/trackpad gesture that bottoms out the pill does NOT chain into
-           scrolling the page behind it (the dock is a self-contained scroll
-           port, not a window into the route scroller). */
+        /* Trap the inline-scroll momentum at the dock's own boundary so a wheel /
+           trackpad gesture that bottoms out the pill does NOT chain into scrolling the
+           page behind it (the dock is a self-contained scroll port). */
         overscroll-behavior-x: contain;
+        /* The `<FadingScroll>` edge mask, reached BY NAME (the SAME `gl-fade-start-in`/
+           `gl-fade-end-out` keyframes the component drives off `scroll(self inline)` —
+           ZERO new recipe). Painted ONLY on this overflow branch, so at rest (fits) the
+           mask is `none` (T-52 a). On the overflow branch there is ALWAYS trailing OR
+           leading overflow, so at least one fade is active by construction. Not
+           PRM-gated (a legibility cue — it stops interpolating under reduce, the
+           discrete edge-presence stays correct). */
+        mask-image: linear-gradient(
+            to right,
+            transparent 0,
+            black var(--fade-start, 0px),
+            black calc(100% - var(--fade-end, 0px)),
+            transparent 100%
+        );
+        animation:
+            gl-fade-start-in linear both,
+            gl-fade-end-out linear both;
+        animation-timeline: scroll(self inline), scroll(self inline);
+        animation-range:
+            0 var(--fade-scroll-width),
+            calc(100% - var(--fade-scroll-width)) 100%;
     }
 
-    .glass-dock.dock-scroll-x .dock-layer--full::-webkit-scrollbar {
+    .glass-dock.dock-scroll-x[data-dock-overflow]:not(.dock-overflow-wrap)
+        .dock-layer--full::-webkit-scrollbar {
         display: none;
     }
 
-    /* Block axis (vertical rails). The root keeps its `max-block-size` cap
-       and scrolls its over-cap children — cap + scroll is the correct
-       pairing the grow-mode contract split apart. Ties the
-       `.vertical.always-expanded` visible default on specificity and wins on
-       source order. */
-    .glass-dock.vertical.dock-scroll-y {
-        overflow-y: auto;
-        /* BA.W-DOCK-GEOMETRY (DC-1) — PIN the CROSS (inline) axis explicitly
-           `visible` (the vertical-dock twin of the horizontal pin above). A
-           single-axis `overflow-y: auto` would compute the inline axis from
-           `visible` to `auto`, clipping a vertical control's inset plate left+right.
-           The block scroll port (the real over-cap axis) is untouched. */
-        overflow-x: visible;
-        scrollbar-width: none;
-        /* Same momentum-trap as the inline port — a rail that bottoms out must
-           not chain its remaining wheel delta into the page scroller behind it. */
-        overscroll-behavior-y: contain;
-    }
-
-    .glass-dock.vertical.dock-scroll-y::-webkit-scrollbar {
-        display: none;
-    }
+    /* The VERTICAL block-axis scroll port lives in shell.css (the unconditional
+       cap-derived `.glass-dock.vertical…:not([data-morphing])` rule) — the
+       `.dock-scroll-y` opt-in class is RETIRED here (BG.W-DOCK-CAP-SCROLL-FADE,
+       clean break: a capped vertical axis is intrinsically a scroll axis, ONE
+       home, no second opt-in port). */
 
     /* ── `overflow="wrap"` recipe — CONTENT-DRIVEN intrinsic flex reflow ──
        (AX.W04 F0). Parallel to the `.dock-scroll-{x,y}` hooks the
@@ -117,7 +157,7 @@
         border-radius: calc(
             var(--radius-pill) +
                 (var(--dock-card-radius) - var(--radius-pill)) *
-                var(--dock-expand-t, 1)
+                var(--dock-expand-t)
         );
 
         /* F1 — the card-tier elevation morph ("material thickens as glass flexes
@@ -134,13 +174,13 @@
            the full floating stack grounds the multi-row silhouette. The per-layer
            recipe mirrors `--shadow-dock-wrap` (= `--shadow-xl` + `--glass-material-rim`
            + `--glass-under-shadow-vivid`) so the token stays the source-of-record. */
-        --dock-wrap-elev: calc(var(--dock-expand-t, 1) * 100%);
+        --dock-wrap-elev: calc(var(--dock-expand-t) * 100%);
         box-shadow:
             var(--glass-edge-light),
             var(--shadow-dock-override, var(--shadow-dock)),
             0 8px 24px color-mix(in srgb, var(--shadow-color) calc(0.14 * var(--dock-wrap-elev)), transparent),
             0 0 0 0.5px color-mix(in srgb, var(--shadow-color) calc(0.05 * var(--dock-wrap-elev)), transparent),
-            0 8px 32px -4px color-mix(in srgb, oklch(0 0 0 / 0.12) var(--dock-wrap-elev), transparent);
+            calc(8px * var(--glass-key-direction)) 8px 32px -4px color-mix(in srgb, oklch(0 0 0 / 0.12) var(--dock-wrap-elev), transparent);
     }
 
     .glass-dock.dock-overflow-wrap .dock-layer--full {
@@ -202,12 +242,12 @@
            surfaces (a routed gear, no dock ancestor) that read it directly.
        Fine pointer byte-identical (`--ui-scale` stays 1).
 
-       AP.W3 R0G-6 — selector is `.glass-dock[data-density]`, not bare `.glass-dock`:
+       AP.W3 R0G-6 — selector is `.glass-dock[data-size]`, not bare `.glass-dock`:
        the always-present density setter (0,2,0) would shadow a bare (0,1,0) rule. The
        presence-selector (0,2,0) wins by source order, lifting `--dock-local-scale` +
        the floor so the cascade re-resolves at touch scale. */
     @media (pointer: coarse) {
-        .glass-dock[data-density] {
+        .glass-dock[data-size] {
             /* R5-2 — the coarse-register DEFAULT lives in the FALLBACK, NOT a
                hard-pin. The coarse dock painted ~22% too big (the global
                --ui-coarse-scale 1.5 → an ~80px collapsed pill). The dock-layer
@@ -249,7 +289,7 @@
                the resolution element moves so the lifted --dock-scale flows in.
                BB.W-PERF-PRODUCER A′-6 — --dock-icon-glyph is now a RATIO of the
                density-painted --dock-layer-height (offsets-sizing.css + the density.css
-               [data-density] re-resolve). This coarse block @imports AFTER density.css
+               [data-size] re-resolve). This coarse block @imports AFTER density.css
                in the SAME @layer at the SAME specificity, so its --dock-icon-glyph
                source-order-WINS on coarse pointers — it MUST carry the density-aware
                formula too (the flat `1.25rem * --dock-scale` here would re-freeze the
@@ -277,7 +317,7 @@
             --dock-collapsed-padding: calc(0.25rem * var(--dock-scale));
             --dock-layer-tab-size: calc(1.75rem * var(--dock-scale));
             /* --dock-collapsed-summary-min-size derives from --dock-layer-height (the
-               density-resolved control height on .glass-dock[data-density]) — but its
+               density-resolved control height on .glass-dock[data-size]) — but its
                :root definition reads --dock-layer-height at :root, where density.css
                never sets it, so it froze at the inline 2.5rem fallback × 0.85 = 34px
                (the pre-existing freeze, independent of R5-2). Re-resolving it HERE reads