@mkbabb/glass-ui 3.1.1 → 3.3.0

package/src/styles/dock.css

@@ -19,7 +19,11 @@
     ) {
         --dock-motion-fast: var(--duration-fast) var(--ease-standard);
         --dock-motion-standard: var(--duration-normal) var(--ease-standard);
-        --dock-motion-resize: var(--duration-normal) var(--spring-snappy);
+        /* AT.W6-dock-c — the FLIP-fallback timing. `--dock-resize-spring` (the
+           `--spring-snappy` linear()) is the single source curve the native
+           View-Transition path ALSO consumes, so the morph is timing-identical
+           across engines. */
+        --dock-motion-resize: var(--duration-normal) var(--dock-resize-spring);
     }
 
     /* Shared four-state contract — the focus-visible ring + disabled paint are
@@ -64,6 +68,15 @@
         position: relative;
         display: inline-flex;
         align-items: center;
+        /* AV.W16 TW3 — the dock establishes an inline-size container named
+           `dock` so its descendants (the label glyph, the density rules)
+           read the dock's OWN box, not the viewport. This makes the dock
+           portable into a 320px sidebar: the label compresses off the
+           dock's box width, not `@media`. A consumer that sets the
+           `containerName` prop overrides the name via inline style (the
+           explicit container-query opt-in); the default `dock` name backs
+           the built-in label/density container reads below. */
+        container: dock / inline-size;
         border-radius: var(--radius-dock);
         white-space: nowrap;
         max-inline-size: var(--dock-max-inline-size);
@@ -71,18 +84,19 @@
         background: var(--glass-bg-dock, var(--glass-bg-resting));
         backdrop-filter: var(--dock-surface-blur);
         border: 1.5px solid var(--glass-border-dock, var(--glass-border-resting));
-        box-shadow: var(--shadow-dock-override, var(--shadow-dock));
-    }
-
-    /* T.W2.T1 — `overflow: hidden` is the default shell, but the
-       container-query host path (`<GlassDock containerName="…">`) must
-       allow descendants to wrap and report intrinsic widths past the
-       padding box. Inline-style on the SFC sets `overflow: visible` for
-       that path; this rule grants the default clip to every dock that
-       is NOT a container-query host. The `data-container-name` attribute
-       is the structural marker (set by the SFC when `containerName` is
-       passed). */
-    .glass-dock:not([data-container-name]) {
+        /* AV.W15 M3 — the full-perimeter `--glass-edge-light` rim rides as the
+           leading inset layer of the dock shadow stack (the navigation-band
+           silhouette catch-light, distinct from the top-only highlight). */
+        box-shadow: var(--glass-edge-light), var(--shadow-dock-override, var(--shadow-dock));
+    }
+
+    /* `overflow: hidden` is the clip shell for every dock. AT.W7-dock-a
+       folded out the prior `containerName` clip-lift (the container-query
+       opt-in is orthogonal — it no longer silently changes the clip), so the
+       clip applies universally and the `.expanded` / `.always-expanded` /
+       `.dock-overflow-wrap` states lift it back to `visible` where they need to
+       grow. A consumer wanting multi-line content opts into `overflow="wrap"`. */
+    .glass-dock {
         overflow: hidden;
     }
 
@@ -92,10 +106,22 @@
         --dock-control-size: var(--dock-density-compact-control-size, 2rem);
         --dock-layer-height: var(--dock-density-compact-layer-height, 2rem);
         --dock-layer-gap: var(--dock-density-compact-gap, 0.25rem);
-        --dock-trigger-padding-block: var(--dock-density-compact-trigger-padding-block, 0.1875rem);
-        --dock-trigger-padding-inline: var(--dock-density-compact-trigger-padding-inline, 0.4375rem);
-        --dock-tab-padding-block: var(--dock-density-compact-tab-padding-block, 0.3125rem);
-        --dock-tab-padding-inline: var(--dock-density-compact-tab-padding-inline, 0.625rem);
+        --dock-trigger-padding-block: var(
+            --dock-density-compact-trigger-padding-block,
+            0.1875rem
+        );
+        --dock-trigger-padding-inline: var(
+            --dock-density-compact-trigger-padding-inline,
+            0.4375rem
+        );
+        --dock-tab-padding-block: var(
+            --dock-density-compact-tab-padding-block,
+            0.3125rem
+        );
+        --dock-tab-padding-inline: var(
+            --dock-density-compact-tab-padding-inline,
+            0.625rem
+        );
         --dock-tab-h: 32px;
     }
 
@@ -107,10 +133,22 @@
         --dock-control-size: var(--dock-density-comfortable-control-size, 2.5rem);
         --dock-layer-height: var(--dock-density-comfortable-layer-height, 2.5rem);
         --dock-layer-gap: var(--dock-density-comfortable-gap, 0.375rem);
-        --dock-trigger-padding-block: var(--dock-density-comfortable-trigger-padding-block, 0.25rem);
-        --dock-trigger-padding-inline: var(--dock-density-comfortable-trigger-padding-inline, 0.5rem);
-        --dock-tab-padding-block: var(--dock-density-comfortable-tab-padding-block, 0.4375rem);
-        --dock-tab-padding-inline: var(--dock-density-comfortable-tab-padding-inline, 0.75rem);
+        --dock-trigger-padding-block: var(
+            --dock-density-comfortable-trigger-padding-block,
+            0.25rem
+        );
+        --dock-trigger-padding-inline: var(
+            --dock-density-comfortable-trigger-padding-inline,
+            0.5rem
+        );
+        --dock-tab-padding-block: var(
+            --dock-density-comfortable-tab-padding-block,
+            0.4375rem
+        );
+        --dock-tab-padding-inline: var(
+            --dock-density-comfortable-tab-padding-inline,
+            0.75rem
+        );
         --dock-tab-h: 38px;
     }
 
@@ -120,10 +158,22 @@
         --dock-control-size: var(--dock-density-spacious-control-size, 2.75rem);
         --dock-layer-height: var(--dock-density-spacious-layer-height, 2.75rem);
         --dock-layer-gap: var(--dock-density-spacious-gap, 0.5rem);
-        --dock-trigger-padding-block: var(--dock-density-spacious-trigger-padding-block, 0.375rem);
-        --dock-trigger-padding-inline: var(--dock-density-spacious-trigger-padding-inline, 0.625rem);
-        --dock-tab-padding-block: var(--dock-density-spacious-tab-padding-block, 0.5rem);
-        --dock-tab-padding-inline: var(--dock-density-spacious-tab-padding-inline, 0.875rem);
+        --dock-trigger-padding-block: var(
+            --dock-density-spacious-trigger-padding-block,
+            0.375rem
+        );
+        --dock-trigger-padding-inline: var(
+            --dock-density-spacious-trigger-padding-inline,
+            0.625rem
+        );
+        --dock-tab-padding-block: var(
+            --dock-density-spacious-tab-padding-block,
+            0.5rem
+        );
+        --dock-tab-padding-inline: var(
+            --dock-density-spacious-tab-padding-inline,
+            0.875rem
+        );
         --dock-tab-h: 44px;
     }
 
@@ -137,25 +187,43 @@
         --dock-control-size: var(--dock-density-audacious-control-size, 4rem);
         --dock-layer-height: var(--dock-density-audacious-layer-height, 4rem);
         --dock-layer-gap: var(--dock-density-audacious-gap, 0.875rem);
-        --dock-trigger-padding-block: var(--dock-density-audacious-trigger-padding-block, 0.625rem);
-        --dock-trigger-padding-inline: var(--dock-density-audacious-trigger-padding-inline, 1rem);
-        --dock-tab-padding-block: var(--dock-density-audacious-tab-padding-block, 0.5rem);
-        --dock-tab-padding-inline: var(--dock-density-audacious-tab-padding-inline, 1.5rem);
+        --dock-trigger-padding-block: var(
+            --dock-density-audacious-trigger-padding-block,
+            0.625rem
+        );
+        --dock-trigger-padding-inline: var(
+            --dock-density-audacious-trigger-padding-inline,
+            1rem
+        );
+        --dock-tab-padding-block: var(
+            --dock-density-audacious-tab-padding-block,
+            0.5rem
+        );
+        --dock-tab-padding-inline: var(
+            --dock-density-audacious-tab-padding-inline,
+            1.5rem
+        );
         --dock-tab-min-height: var(--dock-density-audacious-tab-min-height, 3.5rem);
         --dock-tab-h: var(--dock-density-audacious-tab-min-height, 3.5rem);
     }
 
-    /* Density-audacious mobile carve — at narrow viewports the audacious-dock
-       label glyphs compress so the chrome doesn't overflow its host
-       (≤14px at <480, 15px at 480–719). Consumer dock label spans bind
-       `font-size: var(--dock-label-size)` (typography.css `.dock-label`). */
-    @media (max-width: 479px) {
-        .glass-dock[data-density="audacious"] {
+    /* Density-audacious narrow-box carve (AV.W16 TW3) — when the dock's OWN
+       box is narrow the audacious-dock label glyphs compress so the chrome
+       doesn't overflow its host (≤14px below 30rem, 15px 30–45rem). Keyed off
+       the dock's `dock` inline-size container (established on `.glass-dock`
+       above) rather than the viewport — so a dock dropped into a 320px
+       sidebar compresses its label off ITS box, not the page width. The var
+       is set on the `.dock-label` descendant (which reads it via
+       `font-size: var(--dock-label-size)`, typography.css). Thresholds keep
+       the prior 479/719px viewport cadence as box widths (30rem ≈ 480px,
+       45rem ≈ 720px at the 16px root). */
+    @container dock (max-width: 29.9375rem) {
+        .glass-dock[data-density="audacious"] .dock-label {
             --dock-label-size: 14px;
         }
     }
-    @media (min-width: 480px) and (max-width: 719px) {
-        .glass-dock[data-density="audacious"] {
+    @container dock (min-width: 30rem) and (max-width: 44.9375rem) {
+        .glass-dock[data-density="audacious"] .dock-label {
             --dock-label-size: 15px;
         }
     }
@@ -192,7 +260,7 @@
     }
 
     /* Vertical rails grow-to-fit + clamp, no scroll: descendants wrap to
-       multiple rows (opt-in via `dock-wrap`) or clamp via
+       multiple rows (opt-in via `overflow="wrap"`) or clamp via
        `--dock-max-block-size`; the cap fails visibly rather than masking
        overflow as a scroll affordance. No edge-fade mask — a rail that never
        scrolls has nothing to feather. */
@@ -262,7 +330,10 @@
      * `.variant-instrument-strip` — chassis-strip carries ONE canonical
      * border-radius (`--radius-card`), per the chassis family. */
     .glass-dock.variant-instrument-strip {
-        padding: var(--dock-instrument-strip-padding, var(--dock-padding-inline, 0.75rem));
+        padding: var(
+            --dock-instrument-strip-padding,
+            var(--dock-padding-inline, 0.75rem)
+        );
         background: var(--glass-bg-chassis, var(--glass-bg-wash));
         border: 1px solid var(--glass-border-quiet, var(--glass-border-resting));
         border-radius: var(--radius-card);
@@ -305,7 +376,10 @@
     }
 
     .glass-dock.collapsed .dock-layer--summary {
-        min-width: var(--dock-collapsed-summary-min-size, var(--dock-layer-height, 2.5rem));
+        min-width: var(
+            --dock-collapsed-summary-min-size,
+            var(--dock-layer-height, 2.5rem)
+        );
         justify-content: center;
     }
 
@@ -383,15 +457,43 @@
         transition: width var(--dock-motion-resize);
     }
 
+    /* AV.W9.0 — the AU.W8b native container-morph arm (the `@supports` block that
+       opted the subtree into auto-to-length width interpolation and declared the
+       active layer's destination width as intrinsic) is RETIRED. It was never made
+       mutually exclusive with the `SpringProgress` FLIP driver in
+       `useLayerTransition.ts`: on Chrome 129+ the native arm interpolated
+       `.dock-layers` width on the browser's own clock WHILE the spring wrote inline
+       `width` per frame — a dual-driver race over the SAME property that cancelled
+       the morph and froze the dock at runtime (born-RED under
+       `proof:dock-animation-live`). One authority per concern: the size morph now
+       has exactly ONE driver on every engine — the `SpringProgress` FLIP path above
+       (`:382`), or the orthogonal View-Transitions path inside
+       `startViewTransition` (which owns size + crossfade as a single browser-side
+       mutation and never touches inline width). Neither coexists with a CSS-native
+       intrinsic-width destination, so the race is gone. This re-expresses the
+       `e8380d7` "one driver owns the morph" invariant on the modern
+       FLIP+spring(+VT) architecture. */
+
     /* Horizontal dock content grows visibly when the active layer's natural
        width exceeds the content area (grow-to-fit; consumers needing wrap opt
-       into `dock-wrap`). No edge-fade mask — content never clips or scrolls,
+       into `overflow="wrap"`). No edge-fade mask — content never clips or scrolls,
        so a feather has nothing to feather and only bleeds a stray ramp onto
        the edge controls. */
-    .glass-dock.expanded:not(.dock-wrap) > .dock-layers {
+    .glass-dock.expanded:not(.dock-overflow-wrap) > .dock-layers {
         overflow-x: visible;
     }
 
+    /* AU.W8b-visibility-fork — the 3-state active/inactive/leaving visibility
+       contract below is LOAD-BEARING (the a11y-006 bite-anchor). A later refactor
+       greps for this marker so the semantics are not collapsed: the inactive layer
+       leaves the hit-test tree (`visibility:hidden`), the leaving layer stays
+       painted-but-untouchable through its fade (`visibility:visible` +
+       `pointer-events:none`), and the active layer shows IMMEDIATELY (`visibility
+       0s`, no fade-in delay). The hand-rolled 3-state fork below is now the SOLE
+       visibility authority on every engine — AV.W9.1 retired the native
+       discrete-visibility arm that used to second-drive it, so one owner governs
+       visibility (one owner governs size, one owns opacity). */
+
     /* ── Layer crossfade + hit-test contract (shared) ──────────────────
        Two dock-layer surfaces stack on a 1/1 CSS grid and crossfade:
        `.dock-layer` (GlassDock's built-in collapsed↔expanded pair) and
@@ -409,12 +511,21 @@
        flow, so the FLIP width measurement in `useLayerTransition` still
        reads its geometry (`display:none` would zero it). The delayed
        `visibility` transition holds a leaving layer `visible` for the
-       length of the opacity crossfade, then flips it `hidden`. */
+       length of the opacity crossfade, then flips it `hidden`.
+
+       AU.W2 — the opacity-lockstep fold (slides-F P0, the "not iOS-smooth"
+       report). The layer fade rides `--dock-motion-resize` (the SAME duration +
+       spring the container morph runs at, `:189`/`:216`/`:385`) — NOT the faster
+       `--dock-motion-fast` (0.2s). Before, the host faded in 0.2s while the
+       container morphed in 0.3s: a 100ms-apart settle (the items appeared to lag
+       the pill). Now the fade and the morph settle in lockstep. The matched
+       `visibility` hold extends to `--duration-normal` so the leaving layer stays
+       paintable for the FULL (now longer) crossfade. */
     .dock-layer,
     .dock-layer-item-host {
         transition:
-            opacity var(--dock-motion-fast),
-            visibility 0s linear var(--duration-fast);
+            opacity var(--dock-motion-resize),
+            visibility 0s linear var(--duration-normal);
     }
 
     .dock-layer:not(.layer-active),
@@ -429,9 +540,12 @@
         opacity: 1;
         visibility: visible;
         pointer-events: auto;
-        /* The active layer shows immediately — no deferred `visibility`. */
+        /* The active layer shows immediately — no deferred `visibility`. AU.W2:
+           the opacity rides `--dock-motion-resize` (lockstep with the container
+           morph), but the `visibility 0s` stays immediate (the `:434` rule
+           governs — the active layer must paint at once, no fade-in delay). */
         transition:
-            opacity var(--dock-motion-fast),
+            opacity var(--dock-motion-resize),
             visibility 0s;
     }
 
@@ -445,6 +559,19 @@
         pointer-events: none;
     }
 
+    /* AV.W9.1 — the AU.W8b native discrete-visibility arm (the second `@supports`
+       block that expressed the 3-state contract as one discrete transition over
+       opacity + visibility with a `@starting-style` entry anchor) is RETIRED. It
+       was a THIRD opacity/visibility authority overlapping the hand-rolled 3-state
+       fork above and the spring's settle — three owners for one concern. With the
+       native size arm gone (W9.0), opacity now has ONE owner everywhere: the
+       `opacity var(--dock-motion-resize)` crossfade on `.dock-layer{,-item-host}`
+       (the AU.W2 lockstep token — kept), and visibility has ONE owner: the delayed
+       `visibility 0s linear var(--duration-normal)` hold of the
+       `AU.W8b-visibility-fork` 3-state fallback above (the a11y-006 bite-anchor,
+       LOAD-BEARING). One authority per concern: size = spring/VT, opacity = the
+       CSS crossfade, visibility = the delayed-hold fork. */
+
     /* ── Base layout — distinct per surface ─────────────────────────── */
     .dock-layer {
         display: flex;
@@ -489,33 +616,90 @@
         overflow-y: visible;
     }
 
-    .glass-dock.dock-wrap {
+    /* ── 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. */
+
+    /* 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;
+    }
+
+    .glass-dock.dock-scroll-x .dock-layer--full {
+        min-width: 0;
+        overflow-x: auto;
+        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). */
+        overscroll-behavior-x: contain;
+    }
+
+    .glass-dock.dock-scroll-x .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;
+        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;
+    }
+
+    /* ── `overflow="wrap"` recipe (the `.dock-overflow-wrap` hook) ────────
+       Parallel to the `.dock-scroll-{x,y}` hooks the `overflow="scroll"`
+       member emits: the `overflow="wrap"` enum member emits this class. (The
+       prior `wrap` boolean's hook is retired — clean break, no alias.)
+       Expanded content wraps to multiple rows; the pill narrows to the
+       viewport gutter and snaps back to a single nowrap row past
+       `--dock-overflow-bp` (the `@media` at the tail). */
+    .glass-dock.dock-overflow-wrap {
         white-space: normal;
         border-radius: var(--radius-2xl);
         max-width: var(--dock-wrap-max-width);
-        padding:
-            var(--dock-wrap-padding-block, var(--dock-padding-block, 0.375rem))
+        padding: var(--dock-wrap-padding-block, var(--dock-padding-block, 0.375rem))
             var(--dock-wrap-padding-inline, 0.625rem);
     }
 
-    .glass-dock.dock-wrap .dock-layer--full {
+    .glass-dock.dock-overflow-wrap .dock-layer--full {
         flex-wrap: wrap;
         justify-content: center;
         height: auto;
         min-height: var(--dock-wrap-layer-min-height, var(--dock-layer-height, 2rem));
-        gap: var(--dock-wrap-row-gap, 0.25rem) var(--dock-wrap-column-gap, var(--dock-layer-gap, 0.375rem));
+        gap: var(--dock-wrap-row-gap, 0.25rem)
+            var(--dock-wrap-column-gap, var(--dock-layer-gap, 0.375rem));
     }
 
-    .glass-dock.dock-wrap .dock-layer--summary {
+    .glass-dock.dock-overflow-wrap .dock-layer--summary {
         height: auto;
         min-height: var(--dock-wrap-layer-min-height, var(--dock-layer-height, 2rem));
     }
 
-    .glass-dock.dock-wrap .dock-separator {
+    .glass-dock.dock-overflow-wrap .dock-separator {
         display: none;
     }
 
-    .glass-dock.dock-wrap.collapsed {
+    .glass-dock.dock-overflow-wrap.collapsed {
         border-radius: var(--radius-pill);
         white-space: nowrap;
         max-width: none;
@@ -583,7 +767,16 @@
         border-top: 1px solid color-mix(in srgb, var(--border) 30%, transparent);
     }
 
+    /* AU.W8.4 — the rail is a reka-ui Tabs contract. The travelling
+       `.dock-layer-tab-indicator` (the reka TabsIndicator) now carries the
+       active affordance; the rail is `position: relative` so the indicator's
+       absolute placement is rail-local. */
+    .dock-layer-rail {
+        position: relative;
+    }
+
     .dock-layer-rail .dock-layer-tab {
+        position: relative;
         display: inline-flex;
         align-items: center;
         justify-content: center;
@@ -596,6 +789,8 @@
         cursor: pointer;
         font: inherit;
         font-size: 0.75rem;
+        /* The tab glyph rides above the travelling indicator backplate. */
+        z-index: 1;
         transition:
             background var(--dock-motion-fast),
             color var(--dock-motion-fast);
@@ -606,11 +801,47 @@
         color: var(--foreground);
     }
 
-    .dock-layer-rail .dock-layer-tab.is-active {
-        background: color-mix(in srgb, var(--primary) 15%, transparent);
+    /* AU.W8.4 — KEEP the active glyph tint on the selected tab (reka emits
+       `data-state="active"` + `aria-selected="true"`); the per-button active
+       BACKGROUND is RETIRED — the travelling indicator carries that affordance. */
+    .dock-layer-rail .dock-layer-tab[data-state="active"] {
         color: var(--primary);
     }
 
+    /* AU.W8.4 — the dock control focus-ring contract does not cover
+       `.dock-layer-tab` (the rail tab is not in the `.dock-icon-button` family).
+       The roving tabindex means only the active tab is in the tab order; a
+       focus-visible tab paints the shared dock ring. */
+    .dock-layer-rail [role="tab"]:focus-visible {
+        box-shadow: var(--focus-ring-shadow);
+        outline: none;
+    }
+
+    /* AU.W8.4 — the travelling indicator (reka TabsIndicator). reka computes
+       `--reka-tabs-indicator-position` + `--reka-tabs-indicator-size` from the
+       active tab's geometry; the indicator morphs between tabs riding
+       `--dock-motion-resize` (= `--spring-dock` after AU.W8.2) — NOT a hardcoded
+       `--spring-snappy`. It paints the active-tab backplate the per-button
+       `.is-active` background used to. */
+    .dock-layer-rail .dock-layer-tab-indicator {
+        position: absolute;
+        left: 0;
+        top: 0;
+        height: var(--dock-layer-tab-size, var(--dock-control-size, 1.75rem));
+        width: var(--reka-tabs-indicator-size);
+        transform: translateX(var(--reka-tabs-indicator-position));
+        border-radius: var(--dock-layer-tab-radius, var(--radius-sm));
+        background: color-mix(in srgb, var(--primary) 15%, transparent);
+        transition:
+            width var(--dock-motion-resize),
+            transform var(--dock-motion-resize);
+        pointer-events: none;
+    }
+
+    /* For a vertical rail the indicator travels along the inline axis still
+       (the horizontal-always keyboard decision keeps the indicator inline);
+       reka's position var resolves to the active tab offset regardless. */
+
     .dock-layer-stack {
         position: relative;
         display: grid;
@@ -656,75 +887,14 @@
         height: max-content;
     }
 
-    .dock-icon-button {
-        display: inline-flex;
-        align-items: center;
-        justify-content: center;
-        flex-shrink: 0;
-        /* AQ.W3 §W3.2 identity base */
-        scale: 1;
-        width: var(--dock-control-size, var(--size-icon-btn));
-        height: var(--dock-control-size, var(--size-icon-btn));
-        padding: var(--dock-icon-padding, 0);
-        cursor: pointer;
-        border: none;
-        background: transparent;
-        border-radius: var(--dock-control-radius, var(--radius-pill));
-        color: color-mix(in srgb, var(--foreground) calc(var(--opacity-icon-muted) * 100%), transparent);
-        outline: none;
-        transition:
-            background-color var(--dock-motion-fast),
-            color var(--dock-motion-fast),
-            scale var(--dock-motion-fast),
-            opacity var(--dock-motion-fast);
-    }
-
-    .dock-icon-button--compact {
-        width: var(--dock-compact-control-size, auto);
-        height: var(--dock-compact-control-size, auto);
-        min-width: var(--dock-compact-control-min-width, 0);
-        padding: var(--dock-compact-control-padding, 0.25rem);
-    }
-
-    .dock-icon-button:hover:not(:disabled) {
-        background: var(--muted);
-        color: var(--btn-hover-color, var(--foreground));
-        scale: var(--scale-hover-dock);
-    }
-
-    .dock-icon-button:active:not(:disabled) {
-        scale: var(--scale-press-dock);
-    }
-
-    .dock-icon-button:focus:not(:focus-visible) {
-        box-shadow: none;
-        outline: none;
-    }
-
-    /* focus-visible ring + disabled paint hoisted to the shared `:where()`
-       group at the top; this rule adds only the box-shadow fade transition. */
-    .dock-icon-button:focus-visible {
-        transition:
-            background-color var(--dock-motion-fast),
-            color var(--dock-motion-fast),
-            scale var(--dock-motion-fast),
-            opacity var(--dock-motion-fast),
-            box-shadow var(--dock-motion-fast);
-    }
-
-    /* O.W6 Lane B — token-ladder active paint. Defaults match the prior
-       hardcoded recipe (--muted bg + --foreground color, no transform / border
-       / shadow). Consumers override the active variant via the
-       `--dock-active-{bg,color,scale,border,shadow}` cohort scoped to a parent
-       (e.g. bbnf-buddy `ToolsLayer.vue` audacious active treatment) — no
-       `:deep()` escapes required. See tokens.css §10 (dock geometry block). */
-    .dock-icon-button:is(.is-active, .active, [aria-expanded="true"], [aria-pressed="true"]) {
-        background: var(--dock-active-bg);
-        color: var(--dock-active-color);
-        scale: var(--dock-active-scale);
-        border: var(--dock-active-border);
-        box-shadow: var(--dock-active-shadow);
-    }
+    /* AU.W8b.3 — the five dock CONTROL families (.dock-icon-button,
+       .dark-mode-toggle-button, .dock-tab-button + tiers, the
+       .dock-select-trigger / .dock-dropdown-trigger pair, and the coarse-pointer
+       per-button touch floor) carved out to dock-controls.css (imported directly
+       after this file in index.css, same @layer components). dock.css keeps the
+       shell / density / grain / layer-crossfade contract + the shared
+       cross-control four-state comma-groups (the :focus-visible / :disabled groups
+       + the motion-token :where() group above). */
 
     /* J.W3.B — `.dock-popover` substrate + `pop-up-*` / `pop-down-*`
        Vue Transition keyframes retired. Hover-driven dock popovers
@@ -733,325 +903,42 @@
        `popover-animate` motion vocabulary. Click-anchored popovers
        (no dock-keep semantics) compose `<Popover>` directly. */
 
-    .dark-mode-toggle-button {
-        width: var(--dark-mode-toggle-size, 2.25rem);
-        height: var(--dark-mode-toggle-size, 2.25rem);
-        min-width: var(--dark-mode-toggle-size, 2.25rem);
-        min-height: var(--dark-mode-toggle-size, 2.25rem);
-        max-width: var(--dark-mode-toggle-size, 2.25rem);
-        max-height: var(--dark-mode-toggle-size, 2.25rem);
-        aspect-ratio: 1;
-        padding: var(--dark-mode-toggle-padding, 0.375rem);
-        transition:
-            opacity var(--dock-motion-standard),
-            background-color var(--dock-motion-standard),
-            box-shadow var(--dock-motion-fast);
-    }
-
-    .dark-mode-toggle-button > svg {
-        width: 100%;
-        height: 100%;
-        max-width: 100%;
-        max-height: 100%;
-    }
-
-    .dark-mode-toggle-button:hover,
-    .dark-mode-toggle-button:focus {
-        background: var(--surface-tint-10);
-        opacity: 1;
-        outline: none;
-    }
-
-    .dark-mode-toggle-button:focus-visible {
-        box-shadow: var(--focus-ring-shadow);
-    }
-
-    .dark-mode-toggle-button[data-size="sm"] {
-        --dark-mode-toggle-size: 1.75rem;
-        --dark-mode-toggle-padding: 0.25rem;
-    }
-
-    .dark-mode-toggle-button[data-size="md"] {
-        --dark-mode-toggle-size: 2.25rem;
-        --dark-mode-toggle-padding: 0.375rem;
-    }
-
-    .dark-mode-toggle-button[data-size="lg"] {
-        --dark-mode-toggle-size: 2.75rem;
-        --dark-mode-toggle-padding: 0.5rem;
-    }
-
-    .dark-mode-toggle-button[data-size="control"] {
-        --dark-mode-toggle-size: var(--control-size, 2.25rem);
-        --dark-mode-toggle-padding: var(--control-icon-padding, 0.375rem);
-    }
-
-    .dark-mode-toggle-button[data-size="dock"],
-    .glass-dock .dark-mode-toggle-button:not([data-size="sm"]):not([data-size="lg"]):not([data-size="control"]) {
-        --dark-mode-toggle-size: var(--dock-control-size, var(--size-icon-btn));
-        --dark-mode-toggle-padding: var(--dock-icon-padding, 0);
-    }
-
-    .dock-tab-button {
-        display: inline-flex;
-        align-items: center;
-        flex-shrink: 0;
-        /* P.W4 Lane B inline-absorb: the `--dock-tab-h` density-keyed height
-           knob (parallel to DockIconButton's --dock-control-size) merged
-           here from the prior DockTabButton.vue scoped style block. The
-           density rungs that set `--dock-tab-h` per tier live in this same
-           file (the `.glass-dock[data-density="…"]` blocks above) — Q.W3
-           Lane A consolidated them out of utilities.css, closing the
-           cascade-order split-brain. When a parent <GlassDock density="…">
-           sets `--dock-tab-h`, the tab-button reserves that row even when
-           the glyph + padding sum would ride lower. Falls through to
-           `--dock-tab-min-height` (kept for audacious-tier callers) and
-           finally to `auto`. R3-spec / audit-E P0-3. */
-        min-height: var(--dock-tab-h, var(--dock-tab-min-height, auto));
-        padding-inline: var(--dock-tab-padding-inline, 0.75rem);
-        padding-block: var(--dock-tab-padding-block, 0.375rem);
-        border: none;
-        background: transparent;
-        border-radius: var(--dock-control-radius, var(--radius-pill));
-        /* Default font-size carries through to text-only tab content; consumers
-           wrapping content in an explicit type utility (e.g. `text-hero`,
-           `text-display`) on an inner <span> win because Tailwind v4 ships
-           @utility blocks in @layer utilities, which ranks above @layer
-           components — so this declaration is a fallback, not a ceiling. */
-        font-size: var(--type-small);
-        line-height: 1;
-        color: var(--muted-foreground);
-        text-decoration: none;
-        cursor: pointer;
-        white-space: nowrap;
-        outline: none;
-        /* AQ.W3 §W3.2 identity base */
-        scale: 1;
-        transition:
-            background-color var(--dock-motion-fast),
-            color var(--dock-motion-fast),
-            scale var(--dock-motion-fast);
-    }
-
-    .dock-tab-button:hover:not(:disabled) {
-        background: var(--surface-tint-8);
-        color: var(--foreground);
-    }
-
-    .dock-tab-button:active:not(:disabled) {
-        scale: var(--scale-press-dock);
-    }
-
-    .dock-tab-button:focus:not(:focus-visible) {
-        box-shadow: none;
-    }
-
-    /* focus-visible ring + disabled paint hoisted to the shared `:where()`
-       group at the top. */
-
-    .dock-tab-button:is(.is-active, .active, [aria-current="page"], [aria-pressed="true"]) {
-        background: var(--surface-tint-10);
-        color: var(--foreground);
-    }
-
-    /* Tier — primary ────────────────────────────────────────────
-     *
-     * Per W2.7 §9, §12, §13, §17. The primary tier composes three at-rest
-     * marks (top-highlight, bottom under-shadow, baseline glass) with three
-     * disco accents on hover (specular swap, sparkle sweep, disco-grain).
-     *
-     * Reservation: disco fires on hover only. At rest the button reads as
-     * a Vignelli-restrained composed glass surface. The `--phase-color`
-     * cascade (provided by `<InstrumentChassis>` via `data-phase`) tints
-     * the disco-grain radial only on hover; idle is neutral.
-     *
-     * K.W6 Lane B — the canonical disco-grain + sparkle-sweep + specular
-     * recipe lifted to `@utility btn-audacious` (utilities.css). The Vue
-     * <DockTabButton> attaches `btn-audacious` automatically when the
-     * consumer passes `data-tier="primary"`. The dock-local rules below
-     * are STRICTLY the dock extension: structural shell (padding, base
-     * surface tint, min-height) + phase-tint extensions (hover radial
-     * uses `--phase-color`, plus the `[data-phase]` `::before` halo).
-     */
-    .dock-tab-button[data-tier="primary"] {
-        --dock-tab-min-height: 4rem;
-        padding-inline: 1.5rem;
-        background:
-            color-mix(in srgb, var(--card) 60%, transparent);
-        color: var(--foreground);
-    }
-
-    /* Phase-tint hover override — same disco-grain composition as
-     * `btn-audacious`, but the radial uses `--phase-color` (instrument-
-     * cluster axis) instead of the canonical `--primary`. The `--paper-
-     * clean-texture` overlay and `--glass-specular` shadow stack are
-     * inherited from the underlying `btn-audacious` utility. */
-    .dock-tab-button[data-tier="primary"]:hover:not(:disabled) {
-        --glass-grain-opacity: var(--glass-grain-opacity-disco, 0.08);
-        background-image:
-            var(--paper-clean-texture),
-            radial-gradient(
-                ellipse at 30% 30%,
-                color-mix(in srgb, var(--phase-color, var(--foreground)) 18%, transparent),
-                transparent 70%
-            );
-        background-blend-mode: overlay, normal;
-        background-size: var(--paper-texture-size), auto;
-    }
-
-    /* Q.W3.A.4 — phase-tint backplate halo at the pill wrapper.
-     *
-     * The inner `<GlyphFace>` halo (`.glyph-face-backplate { inset: -25% }`)
-     * gets clipped by the pill's `overflow: hidden`; the halo never escapes
-     * the inner glyph wrapper. This `::before` lifts the phase-tint to the
-     * pill itself so the glow composes with the whole CTA. Scoped to
-     * active phases — at idle / ready the pill stays neutral and inherits
-     * the W2.7 reservation ("disco fires on hover only"). */
-    .dock-tab-button[data-tier="primary"][data-phase]:not([data-phase="ready"]):not([data-phase="idle"])::before {
-        content: "";
-        position: absolute;
-        inset: 0;
-        border-radius: inherit;
-        background: radial-gradient(
-            ellipse at 30% 30%,
-            color-mix(in srgb, var(--phase-color, var(--foreground)) 18%, transparent) 0%,
-            transparent 70%
-        );
-        pointer-events: none;
-        z-index: -1;
-        opacity: 1;
-        transition: opacity var(--duration-fast) var(--ease-standard);
-    }
-
-    /* Tier — secondary ──────────────────────────────────────────
-     *
-     * Companion to `data-tier="primary"`. Carries the same edge-light +
-     * edge-shadow skeu vocabulary at quieter weight: no disco accent, no
-     * sparkle, no curvature radial. Composes for icon-button consumers
-     * (chassis ActionCluster, SettingsCog) where the surface needs a
-     * glass-tier read but not the audacious primary punch. Per P.W1.B
-     * audit-C §3 — closes the four bare `<DockIconButton>` consumer sites
-     * (cog + back + retake + stop) without redefining the family.
-     */
-    .dock-tab-button[data-tier="secondary"],
-    .dock-icon-button[data-tier="secondary"] {
-        background: color-mix(in srgb, var(--card) 50%, transparent);
-        border: 1px solid var(--glass-border-quiet);
-        box-shadow:
-            var(--border-hairline),
-            var(--glass-highlight);
-    }
-
-    .dock-tab-button[data-tier="secondary"]:hover:not(:disabled),
-    .dock-icon-button[data-tier="secondary"]:hover:not(:disabled) {
-        background: color-mix(in srgb, var(--card) 65%, transparent);
-        box-shadow:
-            var(--glass-specular),
-            0 0.5px 0 0 rgb(0 0 0 / 0.06);
-    }
-
-    .dock-select-trigger,
-    .dock-dropdown-trigger {
-        display: inline-flex;
-        align-items: center;
-        justify-content: center;
-        flex-shrink: 0;
-        /* AQ.W3 §W3.2 identity base */
-        scale: 1;
-        gap: var(--dock-trigger-gap, 0.25rem);
-        min-height: var(--dock-trigger-min-height, auto);
-        padding:
-            var(--dock-trigger-padding-block, 0.25rem)
-            var(--dock-trigger-padding-inline, 0.5rem);
-        white-space: nowrap;
-        cursor: pointer;
-        border: none;
-        background: transparent;
-        border-radius: var(--dock-control-radius, var(--radius-pill));
-        color: color-mix(in srgb, var(--foreground) calc(var(--opacity-icon-muted) * 100%), transparent);
-        outline: none;
-        transition:
-            background-color var(--dock-motion-fast),
-            color var(--dock-motion-fast),
-            scale var(--dock-motion-fast),
-            opacity var(--dock-motion-fast);
-    }
-
-    .dock-select-trigger:hover:not(:disabled),
-    .dock-dropdown-trigger:hover:not(:disabled) {
-        background: var(--muted);
-        color: var(--btn-hover-color, var(--foreground));
-    }
-
-    .dock-dropdown-trigger:hover:not(:disabled) {
-        scale: var(--scale-hover-dock);
-    }
-
-    .dock-select-trigger:active:not(:disabled),
-    .dock-dropdown-trigger:active:not(:disabled) {
-        scale: var(--scale-press-dock);
-    }
-
-    .dock-select-trigger:focus:not(:focus-visible),
-    .dock-dropdown-trigger:focus:not(:focus-visible) {
-        box-shadow: none;
-        outline: none;
-    }
-
-    /* focus-visible ring + disabled paint hoisted to the shared `:where()`
-       group at the top; this rule adds only the box-shadow fade transition. */
-    .dock-select-trigger:focus-visible,
-    .dock-dropdown-trigger:focus-visible {
-        transition:
-            background-color var(--dock-motion-fast),
-            color var(--dock-motion-fast),
-            scale var(--dock-motion-fast),
-            opacity var(--dock-motion-fast),
-            box-shadow var(--dock-motion-fast);
-    }
-
-    .dock-select-trigger:is(.is-active, .active, [aria-expanded="true"], [aria-pressed="true"]),
-    .dock-dropdown-trigger:is(.is-active, .active, [aria-expanded="true"], [aria-pressed="true"]) {
-        background: var(--muted);
-        color: var(--foreground);
-    }
-
-    .dock-select-trigger__chevron {
-        width: var(--dock-trigger-icon-size, 0.75rem);
-        height: var(--dock-trigger-icon-size, 0.75rem);
-        flex-shrink: 0;
-        opacity: 0.5;
-        /* Individual-transform identity base (AQ.W3 §W3.2) — `rotate:` longhand
-           for family consistency (not a stacking-context hazard: child glyph). */
-        rotate: 0deg;
-        transition: rotate var(--dock-motion-fast);
-    }
-
-    .dock-select-trigger[data-state="open"] .dock-select-trigger__chevron {
-        rotate: 180deg;
-    }
-
-    @media (min-width: 640px) {
-        .glass-dock.dock-wrap {
+    /* The `overflow="wrap"` desktop snap-back. Past the overflow breakpoint a
+       wrap-mode dock reverts from the narrow multi-row pill to a single nowrap
+       row. The breakpoint is the named token `--dock-overflow-bp` (tokens.css §9
+       Layout) — its single source-of-record. A `var()` cannot drive a
+       media-query feature in Baseline CSS, so this one `@media` realizes the
+       token's value; there is no longer a bare unexplained magic number — the
+       threshold lives under one name and is documented at its mint.
+       AV.W16 TW3 — KEPT as `@media` (not converted to `@container`): the wrap
+       dock is `max-width: calc(100vw - gutter)` — it spans the VIEWPORT by
+       contract, so the snap-back is genuinely viewport-semantic. The dock
+       establishes its own `dock` container and cannot self-query that
+       container for a rule on the dock root; the descendant-readable
+       label/density rules above are the container-query candidates. */
+    @media (min-width: 640px /* = var(--dock-overflow-bp) */) {
+        .glass-dock.dock-overflow-wrap {
             white-space: nowrap;
             border-radius: var(--radius-pill);
             max-width: none;
-            padding:
-                var(--dock-wrap-desktop-padding-block, var(--dock-padding-block, 0.375rem))
+            padding: var(
+                    --dock-wrap-desktop-padding-block,
+                    var(--dock-padding-block, 0.375rem)
+                )
                 var(--dock-wrap-desktop-padding-inline, 0.75rem);
         }
 
-        .glass-dock.dock-wrap .dock-layer--full {
+        .glass-dock.dock-overflow-wrap .dock-layer--full {
             flex-wrap: nowrap;
             height: var(--dock-layer-height, 2.5rem);
             gap: var(--dock-wrap-desktop-gap, var(--dock-layer-gap, 0.25rem));
         }
 
-        .glass-dock.dock-wrap .dock-layer--summary {
+        .glass-dock.dock-overflow-wrap .dock-layer--summary {
             height: var(--dock-layer-height, 2.5rem);
         }
 
-        .glass-dock.dock-wrap .dock-separator {
+        .glass-dock.dock-overflow-wrap .dock-separator {
             display: block;
         }
     }
@@ -1081,5 +968,12 @@
             --dock-control-size: var(--dock-touch-target, 2.75rem);
             --size-icon-btn: var(--dock-touch-target, 2.75rem);
         }
+
+        /* S-2 — the in-dock floor above lifts the control-SIZE token (shell /
+           width-math), which only reaches a DockIconButton that has a
+           `.glass-dock` ancestor. The companion button-level floor (the
+           `.dock-icon-button:not(--compact)` `min-{block,inline}-size` that
+           reaches a STANDALONE DockIconButton with no dock wrapper) moved to
+           dock-controls.css with the rest of the control family (AU.W8b.3). */
     }
 }