@mkbabb/glass-ui 3.6.0 → 3.8.0

package/src/styles/dock.css

@@ -5,6 +5,29 @@
  * layering tokens live here so consumers have one public CSS path.
  */
 
+/* AX.W01 — the SINGLE morph scalar. `useLayerTransition` writes it once per frame
+   to the `.glass-dock` root; EVERY morph axis (box size, padding, radius, scale,
+   background/border color, child stagger) is a pure `calc()` read off it — one
+   driver, one clock, on every engine (the View-Transitions collapse fork is
+   retired). `@property`-registered `<number>` so it interpolates COMPOSITED, not
+   discretely (an UNregistered custom property jumps + animates on the main
+   thread). `initial-value:0` = the collapsed-progress floor.
+
+   `inherits:true` (NOT false) — the SOTA inheritance-bomb guard is specifically
+   "never write the scalar to `:root`" (a whole-document subtree recalc per frame
+   over 1300+ elements). The scalar is written LOCALLY on the small `.glass-dock`
+   subtree, and its CONSUMERS are DESCENDANTS (`.dock-layers`/`.dock-layer-stack`
+   size + the active pane's child stagger) that read it via inheritance, so it MUST
+   inherit. Writing one inheriting var over a ~10–20-element dock subtree is the
+   exact pattern the prior `--dock-morph-progress` used (on `.dock-layers`); the
+   bomb only fires from a `:root` write, which never happens here. The root-chrome
+   reads (padding/bg/border) sit on the same element it is written to. */
+@property --dock-morph-t {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 0;
+}
+
 @layer components {
     :where(
         .glass-dock,
@@ -57,15 +80,26 @@
            scrolls with a mask-fade. Consumers override per-instance by
            setting `--dock-max-block-size` / `--dock-max-inline-size`
            on a `.glass-dock` directly. */
-        --dock-wrap-max-width: calc(100vw - var(--dock-viewport-inline-gutter, 1rem));
         --dock-separator-height: calc(var(--dock-h, var(--size-icon-btn)) * 0.5);
         --dock-collapsed-hover-scale: var(--scale-hover-dock);
         /* AW.W3 — the spring-keyed child stagger knobs. `--dock-stagger-window-size`
            is the fraction of the morph each child reveals over; `--dock-stagger-rise`
            is the px the child rises from as it fades in. Consumers retune the
-           cascade feel per instance. */
+           cascade feel per instance.
+
+           AX.W02 — `--dock-stagger-step` is the per-child onset BEAT: each
+           successive control's reveal starts this fraction-of-morph later than the
+           one before it, so the row fills outer→in. ONE token × the child index
+           replaces the hand-typed 0.08/0.16/0.24/0.32/0.4 onset ladder — the onset
+           is `step × (childIndex − 1)`, capped (the cap below). 0.08 = ~5% of the
+           ~0.32s morph between items — inside Emil Kowalski's 30–60ms stagger band,
+           never the >100ms "slideshow" register. The onset rides the NORMALIZED
+           morph progress (`--dock-expand-t`), NOT a wall-clock timer, so a fast
+           flick and a slow hover-open both choreograph correctly and an interrupted
+           morph orphans no timers. */
         --dock-stagger-window-size: 0.55;
         --dock-stagger-rise: 4px;
+        --dock-stagger-step: 0.08;
         /* AW.W3b — big-dock tokens. `--dock-card-radius` is the finite card-shell
            radius (default --radius-dock-card = --radius-3xl, density-scaled
            below); `--dock-tile-min` is the grid tile minimum (auto-fill track
@@ -160,6 +194,30 @@
         overflow: visible;
     }
 
+    /* AX.W04 F6 — the vertical-dock max-block-size + internal-scroll CONTRACT.
+       A vertical rail caps at `--dock-max-block-size` (the `.vertical` rule), but
+       at rest the `overflow: visible` above let over-cap content SPILL — forcing a
+       consumer (bbnf-buddy ToolsLayer) to hand-anchor a max-height + scroll. Ship
+       the contract here: at rest a vertical column scrolls its OWN block axis when
+       content exceeds the cap (cross axis stays `visible` for focus rings + grown
+       popovers). When content fits under the cap (`height:auto` < cap) nothing
+       scrolls — the scroll port only engages on real over-cap content. The
+       block-axis morph clip stays `data-morphing`-gated above; this is the
+       AT-REST port only. Consumers set `--dock-max-block-size` per-instance to
+       anchor the column to the viewport without re-deriving the scroll plumbing. */
+    .glass-dock.vertical.always-expanded:not([data-morphing]),
+    .glass-dock.vertical.expanded:not([data-morphing]) {
+        overflow-x: visible;
+        overflow-y: auto;
+        scrollbar-width: none;
+        overscroll-behavior-y: contain;
+    }
+
+    .glass-dock.vertical.always-expanded:not([data-morphing])::-webkit-scrollbar,
+    .glass-dock.vertical.expanded:not([data-morphing])::-webkit-scrollbar {
+        display: none;
+    }
+
     .glass-dock[data-density="compact"] {
         --dock-padding-block: var(--dock-density-compact-padding-block, 0.25rem);
         --dock-padding-inline: var(--dock-density-compact-padding-inline, 0.375rem);
@@ -309,41 +367,99 @@
         mix-blend-mode: soft-light;
     }
 
-    /* J.W3.A — horizontal docks transition padding/shadow/transform/background/border
-       only. Width is driven by the inner `.dock-layers` FLIP via
-       `useLayerTransition`; pinning it here would race the FLIP and
-       reintroduce the `width: auto` non-interpolation diagnosed in
-       R1+R6.
-
-       AW.W3 — the collapsed-hover `scale` (the `.collapsed:hover` rule below) +
-       the press squish (`--scale-press-dock` on the dock controls) ride the
-       INDIVIDUAL `scale` property, NOT `transform`. Adding `scale
-       var(--dock-motion-resize)` here unifies the hover scale onto the SAME dock
-       spring vocabulary as the morph, so a collapsed→hover→expand gesture reads as
-       ONE continuous spring rather than a `scale`-ease handed off to the
-       width-spring. Under PRM the global gate strips `scale` from the
-       transition-property → the hover scale snaps (0 morph frames). */
-    .glass-dock:not(.vertical) {
-        transition:
-            padding var(--dock-motion-resize),
-            box-shadow var(--dock-motion-standard),
-            transform var(--dock-motion-resize),
-            scale var(--dock-motion-resize),
-            /* AW.W3b — the pill↔card corner radius morphs on the SAME spring the
-               aperture rides (ONE free interpolation). Without this the
-               shape-card collapsed↔expanded radius snaps discretely. The list is
-               shared by ALL horizontal docks — the radius transition also glides
-               the wrap collapsed↔expanded radius swap (desirable). */
-            border-radius var(--dock-motion-resize),
-            background var(--dock-motion-standard),
-            border-color var(--dock-motion-standard);
-    }
-
-    /* Vertical rails grow-to-fit + clamp, no scroll: descendants wrap to
-       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. */
+    /* AX.W01 — the root chrome morphs off the SINGLE `--dock-morph-t` scalar, NOT a
+       CSS transition (the prior `padding/scale/radius var(--dock-motion-resize)` +
+       `background/border-color var(--dock-motion-standard)` transition list — TWO
+       curves on TWO durations — is DELETED). `--dock-expand-t` is the directional
+       expanded-ness (0 = collapsed look, 1 = expanded look) derived from the
+       per-swap morph scalar + the synchronously-set `.expanded`/`.collapsed` class:
+       the box width AND the root padding/radius/color move on ONE clock. The
+       per-frame writes drive the registered `<number>` scalar; the `calc()` reads
+       below interpolate composited. Under PRM the spring's `respectReducedMotion`
+       settles instantly (the scalar jumps 0→1 in one frame → the chrome snaps). */
+
+    /* `--dock-expand-t` — the directional expanded-ness. `--dock-morph-t` is a
+       REGISTERED `@property` (initial-value 0), so it is NEVER guaranteed-invalid:
+       `var(--dock-morph-t, 1)` reads 0 at REST (the fallback is DEAD), which would
+       resolve every expanded dock to expand-t 0 → the collapsed resting look (the
+       pill-radius + collapsed bg/border/padding regression). So the resting value is
+       stated STATICALLY per class, and ONLY while a morph is in flight
+       (`[data-morphing]` armed on the root by useLayerTransition, cleared on settle)
+       does expand-t track the live spring scalar. The class is ALREADY the END state
+       during the morph, so the read resolves the correct in-flight blend (collapse
+       1→0 via `1 - t`; expand 0→1 via `t`); on settle `[data-morphing]` clears and
+       expand-t snaps to the exact class endpoint. */
+    .glass-dock:not(.vertical).expanded,
+    .glass-dock:not(.vertical).always-expanded {
+        --dock-expand-t: 1;
+    }
+
+    .glass-dock:not(.vertical).collapsed {
+        --dock-expand-t: 0;
+    }
+
+    .glass-dock:not(.vertical).expanded[data-morphing],
+    .glass-dock:not(.vertical).always-expanded[data-morphing] {
+        --dock-expand-t: var(--dock-morph-t);
+    }
+
+    .glass-dock:not(.vertical).collapsed[data-morphing] {
+        --dock-expand-t: calc(1 - var(--dock-morph-t));
+    }
+
+    /* The morphing root chrome — background / border-color interpolate between the
+       collapsed and expanded endpoints on the ONE `--dock-expand-t` scalar. Scoped
+       to the horizontal `variant-dock` (the rail / instrument-strip variants own
+       their own surface vocabulary and do not collapse↔expand). The two color axes
+       blend in srgb (the house mix the token ladder speaks). The `.collapsed`
+       discrete bg/border declarations are RETIRED — this block is the single
+       authority, and at rest `--dock-expand-t` resolves to the class endpoint (0
+       collapsed / 1 expanded) so the resting look is exact. */
+    .glass-dock.variant-dock:not(.vertical) {
+        background: color-mix(
+            in srgb,
+            var(--glass-bg-dock, var(--glass-bg-resting))
+                calc(var(--dock-expand-t, 1) * 100%),
+            var(--glass-bg-wash)
+        );
+        border-color: color-mix(
+            in srgb,
+            var(--glass-border-dock, var(--glass-border-resting))
+                calc(var(--dock-expand-t, 1) * 100%),
+            var(--glass-border-floating)
+        );
+    }
+
+    /* The padding morph is split out + scoped `:not(.dock-overflow-wrap)` so the
+       wrap variant's own padding rules (W04 territory — `.dock-overflow-wrap` +
+       its `@media` snap-back) are NOT clobbered by this higher-specificity longhand.
+       Padding interpolates linearly between the collapsed floor and the expanded
+       block/inline padding on the same `--dock-expand-t` scalar. */
+    .glass-dock.variant-dock:not(.vertical):not(.dock-overflow-wrap) {
+        --dock-pad-collapsed: var(
+            --dock-collapsed-padding,
+            var(--dock-padding-block, 0.375rem)
+        );
+        padding-block: calc(
+            var(--dock-pad-collapsed) +
+                (var(--dock-padding-block, 0.375rem) - var(--dock-pad-collapsed)) *
+                var(--dock-expand-t, 1)
+        );
+        padding-inline: calc(
+            var(--dock-pad-collapsed) +
+                (var(--dock-padding-inline, 0.5rem) - var(--dock-pad-collapsed)) *
+                var(--dock-expand-t, 1)
+        );
+    }
+
+    /* Vertical rails grow-to-fit then clamp at `--dock-max-block-size` (the
+       AX.W04 F6 contract). At rest a capped column scrolls its OWN block axis
+       internally (the `.vertical.always-expanded:not([data-morphing])` port above)
+       so a consumer setting `--dock-max-block-size` gets a viewport-anchored
+       scrollable tool palette without hand-anchoring it. `overflow="wrap"` is
+       horizontal-only (the class is not emitted for a vertical orientation); a
+       vertical column's natural overflow story is this cap + internal scroll. No
+       edge-fade mask — the scroll is scrollbar-hidden, not feathered. */
     .glass-dock.vertical {
         display: inline-flex;
         flex-direction: column;
@@ -358,19 +474,20 @@
            shell above; the cross axis stays visible there. */
         padding: var(--dock-vertical-padding, var(--dock-padding-block, 0.375rem));
         border-radius: var(--radius-dock);
-        /* AW.W2 — axis-parity carve: NON-morph properties only. The block-axis
+        /* AX.W01 — a vertical rail is ALWAYS-EXPANDED (no collapse↔expand morph),
+           so its root padding/background/border-color never morph; the prior
+           `padding/background/border-color var(--dock-motion-*)` transition arms
+           are DELETED (a residual root CSS-transition on the morph-chrome props is
+           the second-clock smell the single-scalar rebuild retires). The block-axis
            (height) morph is owned by the inner `.dock-layer-stack` / DockLayerGroup
-           spring (or the VT path); a `height var(--dock-motion-resize)` here would
-           be a second driver on the same axis (the AV.W9.0 dual-driver race),
-           and `width` is the cross axis the spring never writes. Matches how
-           `:not(.vertical)` already excludes `width`. */
+           via the `--dock-morph-t` scalar (the size `calc()` above), never a CSS
+           transition here. KEPT: the DECORATIVE hover-scale + press-squish (the
+           individual `scale`/`transform`) and the box-shadow fade — these are
+           interaction polish on the static rail, NOT the morph. */
         transition:
-            padding var(--dock-motion-resize),
             box-shadow var(--dock-motion-standard),
             transform var(--dock-motion-resize),
-            scale var(--dock-motion-resize),
-            background var(--dock-motion-standard),
-            border-color var(--dock-motion-standard);
+            scale var(--dock-motion-resize);
     }
 
     .glass-dock.variant-rail {
@@ -399,14 +516,18 @@
 
     /* The big-dock CARD shell — a FINITE concentric radius above 2xl, below pill.
        It does NOT collapse to a stadium. Collapsed it returns to a pill (the morph
-       target); the pill↔card swap glides on the `--dock-motion-resize` spring
-       (`border-radius` is in the `:not(.vertical)` transition list). */
+       target); the pill↔card radius now MORPHS on the SAME `--dock-expand-t` scalar
+       the box + chrome ride (ONE clock, no discrete snap) — `--radius-pill` at
+       expand-t 0 (collapsed), `--dock-card-radius` at expand-t 1 (expanded). The
+       prior two discrete `.shape-card` / `.shape-card.collapsed` rules + their
+       reliance on the deleted `border-radius var(--dock-motion-resize)` transition
+       are RETIRED for this single interpolation. */
     .glass-dock.variant-dock:not(.vertical).shape-card {
-        border-radius: var(--dock-card-radius);
-    }
-
-    .glass-dock.variant-dock:not(.vertical).shape-card.collapsed {
-        border-radius: var(--radius-pill);
+        border-radius: calc(
+            var(--radius-pill) +
+                (var(--dock-card-radius) - var(--radius-pill)) *
+                var(--dock-expand-t, 1)
+        );
     }
 
     /* The squircle reads markedly better at the large card radius — an
@@ -480,15 +601,16 @@
         border-color: var(--surface-tint-6);
     }
 
+    /* AX.W01 — the collapsed padding / background / border-color are RETIRED here
+       (the `--dock-expand-t` morph block above is the single authority for those
+       three axes — they interpolate, never snap). `.collapsed` keeps only its
+       non-morphing concerns: the pointer affordance, the centred summary layout,
+       and the collapsed shadow (box-shadow crossfades discretely — a subtle,
+       acceptable swap that a `color-mix` cannot blend across its multi-layer
+       value). */
     .glass-dock.collapsed {
         cursor: pointer;
-        padding: var(--dock-collapsed-padding, var(--dock-padding-block, 0.375rem));
         justify-content: center;
-        background: var(--glass-bg-wash);
-        border-color: var(--glass-border-floating);
-        /* Idiomatic override path: the consumer-supplied
-           `--shadow-dock-override` variable engages in every dock state
-           (was: base only, leaking through here in collapsed). */
         box-shadow: var(--shadow-dock-override, var(--shadow-dock-collapsed));
     }
 
@@ -578,7 +700,47 @@
     .dock-layers {
         display: grid;
         min-width: 0;
-        transition: width var(--dock-motion-resize);
+    }
+
+    /* AX.W01 — the box size morph reads the SAME `--dock-morph-t` scalar as the
+       root chrome (ONE clock, co-temporal by construction). `useLayerTransition`
+       measures the from→to size ONCE per swap (the allowed one-time FLIP
+       measurement) and writes `--dock-morph-from`/`--dock-morph-to` px on the
+       morphing element; the live scalar interpolates between them. The size lands
+       on the morph AXIS — `inline-size` for a horizontal `.dock-layers` (always
+       inline) + a horizontal inner stack, `block-size` for a vertical inner stack.
+       Gated on the root `[data-morphing]`, so at REST the intrinsic / `width:100%`
+       rules below hold (the morph vars are cleared on settle). Replaces the prior
+       `transition: width var(--dock-motion-resize)` inline-FLIP — there is NO CSS
+       transition on the size axis; the spring writes the scalar, CSS reads it. The
+       active pane is REVEALED through the clip aperture as the box grows (the W2
+       clip-reveal contract). */
+    .glass-dock[data-morphing] .dock-layers,
+    .glass-dock[data-morphing] .dock-layer-stack {
+        --dock-morph-size: calc(
+            var(--dock-morph-from, 0px) +
+                (var(--dock-morph-to, 0px) - var(--dock-morph-from, 0px)) *
+                var(--dock-morph-t, 0)
+        );
+        inline-size: var(--dock-morph-size);
+    }
+
+    /* A vertical inner group morphs the BLOCK axis — the same span lands on
+       block-size, and the inline axis stays intrinsic. */
+    .glass-dock[data-morphing] .dock-layer-group.vertical .dock-layer-stack {
+        inline-size: auto;
+        block-size: var(--dock-morph-size);
+    }
+
+    /* The inner DockLayerGroup stack has no collapsed/expanded class, so its
+       stagger directional scalar is the per-swap progress directly: `--dock-morph-t`
+       reads onto an inheriting `--dock-expand-t` on the morphing stack so the new
+       pane's children cascade in as it reveals. The geometry scalar
+       (`--dock-morph-t`) stays registered + non-inheriting on the root; this is the
+       small-subtree inheriting alias the stagger reads (the inheritance-bomb guard
+       only concerns the `:root`-wide write, which never happens). */
+    .glass-dock[data-morphing] .dock-layer-stack {
+        --dock-expand-t: var(--dock-morph-t, 1);
     }
 
     /* AV.W9.0 — the AU.W8b native container-morph arm (the `@supports` block that
@@ -607,44 +769,39 @@
         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
-       `.dock-layer-item-host` (a DockLayer inside a DockLayerGroup). They
-       differ only in base layout — the active/inactive/leaving paint +
-       hit-test semantics are identical, so the contract is expressed ONCE
-       here over both state vocabularies (`.layer-active` / `.is-active` /
-       `.is-leaving`) rather than copied per rule-set (Q-coh-5 — `beec35e`
-       patched the `visibility` fix into two parallel copies).
-
-       An inactive layer must leave the paint AND hit-test tree: `opacity:0`
-       alone leaves the box answering `elementFromPoint()`, so an inactive
-       layer's button intercepts clicks meant for the active one.
-       `visibility:hidden` removes it from both while KEEPING it in layout
-       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`.
-
-       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. */
+    /* ── Layer crossfade + hit-test contract (ONE vocabulary) ──────────────
+       AX.W02 — the outer `.dock-layer` (GlassDock's built-in collapsed↔expanded
+       pair) and the inner `.dock-layer-item-host` (a DockLayer inside a
+       DockLayerGroup) now share ONE active-state vocabulary: `.is-active` /
+       `.is-leaving`. The prior `.layer-active` / `.is-active` / `.is-leaving`
+       TRIPLE collapsed to the pair — both surfaces drive crossfade + hit-test off
+       the same two state classes, and the morph orchestrator fold (one engine per
+       dock) means the box, both panes, and every child stagger ride one
+       `--dock-morph-t` clock. The greppable-sync tombstone that kept the two
+       never-merged vocabularies in lockstep is DELETED — there is nothing to keep
+       in sync once the vocabulary is one.
+
+       The 3-state active/inactive/leaving visibility contract here is LOAD-BEARING
+       (the a11y-006 anchor): 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). One
+       owner governs each concern — size = the spring scalar, opacity = the CSS
+       crossfade below, visibility = this 3-state fork.
+
+       An inactive layer must leave the paint AND hit-test tree: `opacity:0` alone
+       leaves the box answering `elementFromPoint()`, so an inactive layer's button
+       intercepts clicks meant for the active one. `visibility:hidden` removes it
+       from both while KEEPING it in layout flow, so the FLIP measurement 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`.
+
+       AU.W2 — the opacity-lockstep fold. The layer fade rides `--dock-motion-resize`
+       (the SAME duration the container morph runs at) — NOT the faster
+       `--dock-motion-fast` (0.2s), so 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 crossfade. */
     .dock-layer,
     .dock-layer-item-host {
         transition:
@@ -652,34 +809,34 @@
             visibility 0s linear var(--duration-normal);
     }
 
-    .dock-layer:not(.layer-active),
+    .dock-layer:not(.is-active):not(.is-leaving),
     .dock-layer-item-host:not(.is-active):not(.is-leaving) {
         opacity: 0;
         visibility: hidden;
         pointer-events: none;
     }
 
-    .dock-layer.layer-active,
+    .dock-layer.is-active,
     .dock-layer-item-host.is-active {
         opacity: 1;
         visibility: visible;
         pointer-events: auto;
         /* AW.W2 — the active pane is STATICALLY opacity:1, REVEALED by the clip
-           aperture (the box is the reveal mechanism), never faded. The prior
-           `opacity var(--dock-motion-resize)` arm is DELETED: there is ZERO
-           opacity authority on the active pane now — the aperture uncovers a
-           layout that is laid out ONCE at natural size behind it. Only `visibility
-           0s` survives (the active layer must paint at once, no fade-in delay —
-           the AU.W2 governing rule). The leaving pane keeps the shared-token
-           opacity fade below (the ONLY surviving opacity animation, the thin
-           polish proof:dock-opacity-lockstep names). */
+           aperture (the box is the reveal mechanism), never faded. There is ZERO
+           opacity authority on the active pane — the aperture uncovers a layout
+           that is laid out ONCE at natural size behind it. Only `visibility 0s`
+           survives (the active layer must paint at once, no fade-in delay — the
+           AU.W2 governing rule). The leaving pane keeps the shared-token opacity
+           fade below (the ONLY surviving opacity animation). */
         transition: visibility 0s;
     }
 
-    /* A leaving layer is inactive for hit-testing but still painted
-       through its fade-out. (`.dock-layer` has no separate leaving state —
-       its `:not(.layer-active)` rule above covers the crossfade-out via the
-       delayed `visibility` transition.) */
+    /* A leaving layer is inactive for hit-testing but still painted through its
+       fade-out. The outer collapse↔expand pair has no separate leaving marker in
+       markup — its `:not(.is-active):not(.is-leaving)` rule above covers the
+       crossfade-out via the delayed `visibility` transition; the inner pane swap
+       sets `.is-leaving` explicitly during the crossfade. */
+    .dock-layer.is-leaving,
     .dock-layer-item-host.is-leaving {
         opacity: 0;
         visibility: visible;
@@ -694,10 +851,10 @@
        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. */
+       `visibility 0s linear var(--duration-normal)` hold of the 3-state fork above
+       (the a11y-006 anchor, LOAD-BEARING). One authority per concern: size = the
+       spring scalar, opacity = the CSS crossfade, visibility = the delayed-hold
+       fork. */
 
     /* ── Base layout — distinct per surface ─────────────────────────── */
     .dock-layer {
@@ -719,87 +876,99 @@
         height: var(--dock-layer-height, 2.5rem);
     }
 
-    .dock-layer.layer-active {
+    .dock-layer.is-active {
         position: relative;
     }
 
-    .dock-layer:not(.layer-active) {
+    .dock-layer:not(.is-active) {
         position: absolute;
         inset: 0;
     }
 
-    /* AW.W3 — the spring-keyed child stagger. While the size spring drives the
-       morph, the driver arms the container (`.dock-layers` / `.dock-layer-stack`)
-       with `data-revealing` and writes the morph's normalized progress to
-       `--dock-morph-progress` (0 → 1) every frame. Each direct child of the
-       ACTIVE pane reveals when that progress crosses a per-child onset, so the
-       controls cascade IN ON the physical morph — a fast flick and a slow
-       hover-open both choreograph correctly, and an interrupted morph carries the
-       cascade with it (no orphaned timers). This is a per-CHILD opacity onset; the
-       active PANE itself stays statically opacity:1 (revealed by the aperture —
-       the W2 clip-reveal contract is NOT regressed).
-
-       The reveal is a pure `calc` ramp: `opacity = clamp(0, (progress − onset) /
-       window, 1)`. `--dock-stagger-onset` steps per child (nth-child); the window
-       is `--dock-stagger-window`. The children also rise a few px on a `translate`
-       that resolves on the same ramp. ONLY children inside the `[data-revealing]`
-       active pane are armed — at rest the children carry no opacity authority (the
-       default cascade leaves them at 1).
-
-       PRM: the driver never arms `data-revealing` on the synchronous PRM swap (the
-       FLIP fast-path returns before the spring; the spring's `respectReducedMotion`
-       settles instantly), so the children paint at full opacity at once. The
-       global PRM gate also strips `translate` from the transition-property — the
-       rise snaps. The cascade collapses to 0 stagger frames under PRM. */
-    .dock-layers[data-revealing] .dock-layer--full > *,
-    .dock-layer-stack[data-revealing] .dock-layer-item-host.is-active > * {
+    /* AX.W01 — the spring-keyed child stagger, now off the SINGLE morph scalar.
+       The driver writes `--dock-morph-t` to the `.glass-dock` root and arms
+       `[data-morphing]` while the spring runs; `--dock-expand-t` (the inheriting
+       directional expanded-ness derived above — 0 collapsed, 1 expanded) cascades
+       to the active pane's children. Each direct child reveals when `--dock-expand-t`
+       crosses its per-child onset, so the controls cascade IN ON the physical morph
+       — symmetric in both directions (expand fades them in outer→in, collapse fades
+       them back out) and an interrupted morph carries the cascade with it (no
+       orphaned timers). The active PANE stays statically opacity:1 (revealed by the
+       clip aperture); only its CHILDREN ride this per-child onset (the W2
+       clip-reveal contract is NOT regressed).
+
+       The reveal is a pure `calc` ramp: `opacity = clamp(0, (expand-t − onset) /
+       window, 1)`. Gated on the root `[data-morphing]` so at REST the children
+       carry no opacity authority (default cascade → 1). Under PRM the spring's
+       `respectReducedMotion` jumps `--dock-morph-t` 0→1 in one frame → `--dock-expand-t`
+       lands at the endpoint → the cascade collapses to 0 stagger frames; the
+       global PRM gate strips `translate` so the rise snaps too. The inner
+       DockLayerGroup defines its own `--dock-expand-t` (= the per-swap progress)
+       in DockLayerGroup's scope so a pane swap reveals the new pane's children. */
+    .glass-dock[data-morphing] .dock-layer.is-active > *,
+    .glass-dock[data-morphing] .dock-layer-item-host.is-active > * {
         --dock-stagger-window: var(--dock-stagger-window-size, 0.55);
         --dock-stagger-onset: 0;
         opacity: clamp(
             0,
             calc(
-                (var(--dock-morph-progress, 1) - var(--dock-stagger-onset)) /
+                (var(--dock-expand-t, 1) - var(--dock-stagger-onset)) /
                     var(--dock-stagger-window)
             ),
             1
         );
         translate: 0
             calc(
-                (1 - clamp(0, calc((var(--dock-morph-progress, 1) - var(--dock-stagger-onset)) / var(--dock-stagger-window)), 1)) *
+                (1 - clamp(0, calc((var(--dock-expand-t, 1) - var(--dock-stagger-onset)) / var(--dock-stagger-window)), 1)) *
                     var(--dock-stagger-rise, 4px)
             );
     }
 
-    /* Per-child onsets — each successive control starts a beat later, so the row
-       fills outer→in on expand. The onsets are fractions of the morph progress;
-       capped so even a long row finishes within the morph window. */
-    .dock-layers[data-revealing] .dock-layer--full > *:nth-child(2),
-    .dock-layer-stack[data-revealing] .dock-layer-item-host.is-active > *:nth-child(2) {
-        --dock-stagger-onset: 0.08;
+    /* AX.W02 — per-child onsets off the ONE `--dock-stagger-step` token. Each
+       successive control starts `step` later than the one before it (`onset =
+       step × (childIndex − 1)`), so the row fills outer→in on expand. The
+       hand-typed 0.08/0.16/0.24/0.32/0.4 ladder is RETIRED — the onsets are now
+       derived from the single token, so retuning the cascade beat is a one-token
+       override. The set is capped at the 6th child (`nth-child(n + 6)` holds at
+       `step × 5`) so even a long row finishes within the morph window. ONE rule
+       over the unified `.is-active` vocabulary drives both the outer pane and the
+       inner pane-stack — no duplicated comma-group. (`sibling-index()` would
+       collapse this to a single declaration, but it is not yet Baseline across
+       Safari/Firefox — the token-keyed nth-child set is the cross-engine form, and
+       the magic ladder is gone either way.) */
+    .glass-dock[data-morphing] .dock-layer.is-active > *:nth-child(2),
+    .glass-dock[data-morphing] .dock-layer-item-host.is-active > *:nth-child(2) {
+        --dock-stagger-onset: calc(var(--dock-stagger-step) * 1);
     }
-    .dock-layers[data-revealing] .dock-layer--full > *:nth-child(3),
-    .dock-layer-stack[data-revealing] .dock-layer-item-host.is-active > *:nth-child(3) {
-        --dock-stagger-onset: 0.16;
+    .glass-dock[data-morphing] .dock-layer.is-active > *:nth-child(3),
+    .glass-dock[data-morphing] .dock-layer-item-host.is-active > *:nth-child(3) {
+        --dock-stagger-onset: calc(var(--dock-stagger-step) * 2);
     }
-    .dock-layers[data-revealing] .dock-layer--full > *:nth-child(4),
-    .dock-layer-stack[data-revealing] .dock-layer-item-host.is-active > *:nth-child(4) {
-        --dock-stagger-onset: 0.24;
+    .glass-dock[data-morphing] .dock-layer.is-active > *:nth-child(4),
+    .glass-dock[data-morphing] .dock-layer-item-host.is-active > *:nth-child(4) {
+        --dock-stagger-onset: calc(var(--dock-stagger-step) * 3);
     }
-    .dock-layers[data-revealing] .dock-layer--full > *:nth-child(5),
-    .dock-layer-stack[data-revealing] .dock-layer-item-host.is-active > *:nth-child(5) {
-        --dock-stagger-onset: 0.32;
+    .glass-dock[data-morphing] .dock-layer.is-active > *:nth-child(5),
+    .glass-dock[data-morphing] .dock-layer-item-host.is-active > *:nth-child(5) {
+        --dock-stagger-onset: calc(var(--dock-stagger-step) * 4);
     }
-    .dock-layers[data-revealing] .dock-layer--full > *:nth-child(n + 6),
-    .dock-layer-stack[data-revealing] .dock-layer-item-host.is-active > *:nth-child(n + 6) {
-        --dock-stagger-onset: 0.4;
+    .glass-dock[data-morphing] .dock-layer.is-active > *:nth-child(n + 6),
+    .glass-dock[data-morphing] .dock-layer-item-host.is-active > *:nth-child(n + 6) {
+        --dock-stagger-onset: calc(var(--dock-stagger-step) * 5);
     }
 
     /* AW.W2 — the at-rest clip-lift moved to `.expanded:not([data-morphing])` /
        `.always-expanded:not([data-morphing])` (the clip-shell block at the top).
        A plain `overflow: visible` here would lift the clip DURING the morph (the
        load-bearing sequencing gap), so the `overflow` declarations are dropped
-       from these state rules; they keep only their non-overflow concerns. */
-    .glass-dock.expanded:not(.fit-content) .dock-layers {
+       from these state rules; they keep only their non-overflow concerns.
+
+       AX.W01 — `:not([data-morphing])` gate: at REST expanded the layers fill the
+       box (`width:100%`), but DURING the morph the FLIP from→to px (the
+       `--dock-morph-size` calc above) is the SOLE size authority — a `width:100%`
+       here would win on specificity and snap the box past the spring. The gate
+       hands the size to the scalar for the morph and back to 100% on settle. */
+    .glass-dock.expanded:not(.fit-content):not([data-morphing]) .dock-layers {
         width: 100%;
     }
 
@@ -901,19 +1070,70 @@
         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). */
+    /* ── `overflow="wrap"` recipe — CONTENT-DRIVEN intrinsic flex reflow ──
+       (AX.W04 F0). Parallel to the `.dock-scroll-{x,y}` hooks the
+       `overflow="scroll"` member emits, `overflow="wrap"` emits this class.
+       (HORIZONTAL-ONLY — GlassDock.vue guards the emit on
+       `orientation !== 'vertical'`; a vertical rail grows-to-fit + clamps via
+       `--dock-max-block-size`, its own overflow story.)
+
+       The reflow is INTRINSIC: `flex-wrap: wrap` is ALWAYS-ON (no viewport MQ),
+       and the dock shrink-wraps to content with `max-inline-size` capping it at
+       the canonical `--dock-max-inline-size` token (the SAME cap every
+       overflow strategy reads — `min(80vw, 64rem)` default, consumer-overridable
+       per-instance). So the layer wraps to N rows EXACTLY when its intrinsic row
+       exceeds the cap — at ANY viewport width — and collapses to one row when it
+       fits. The magic-640 `@media` snap-back + the `--dock-overflow-bp` token are
+       DELETED (the inherited mobile-responsive debt, origin 078dd79). */
     .glass-dock.dock-overflow-wrap {
         white-space: normal;
-        border-radius: var(--radius-2xl);
-        max-width: var(--dock-wrap-max-width);
+        /* The content-driven cap. The dock ALREADY shrink-wraps to its content's
+           intrinsic width (the base `.glass-dock` rule), so `max-inline-size` caps
+           that intrinsic width at `--dock-max-inline-size`: under the cap the
+           shrink-wrap wins → one row; over the cap the dock holds at the cap and the
+           inner `flex-wrap: wrap` row reflows to N rows. ONE token, no breakpoint.
+           (The `min(max-content, …)` form is INVALID CSS — the math functions reject
+           the `max-content` intrinsic keyword, computing the property to its initial
+           `none` and silently dropping the cap; intrinsic-shrink + this plain cap IS
+           the valid `min(max-content, cap)`.) */
+        max-inline-size: var(--dock-max-inline-size);
         padding: var(--dock-wrap-padding-block, var(--dock-padding-block, 0.375rem))
             var(--dock-wrap-padding-inline, 0.625rem);
+
+        /* F4 — the pill↔card radius morph. A wrap dock is a FINITE multi-row CARD
+           surface when expanded and a stadium PILL when collapsed — the SAME
+           pill↔card morph the big-dock `shape-card` path rides. The corner glides
+           on the `--dock-expand-t` W01 single-scalar: `--radius-pill` at expand-t 0
+           (collapsed), `--dock-card-radius` at expand-t 1 (expanded — UNIFIED on
+           the SAME finite-radius token the big-dock card uses; the bare 16px
+           `--radius-2xl` literal is DELETED). ONE register, no discrete snap. */
+        border-radius: calc(
+            var(--radius-pill) +
+                (var(--dock-card-radius) - var(--radius-pill)) *
+                var(--dock-expand-t, 1)
+        );
+
+        /* F1 — the card-tier elevation morph ("material thickens as glass flexes
+           larger", WWDC25 §219). The wrap dock lifts from the flat thin-pill
+           `--shadow-dock` glow onto the FLOATING-tier stack (the `--shadow-dock-wrap`
+           token names the canonical composite on `:root`; a consumer retints the
+           whole card shadow by overriding THAT one token per the cartoon-shadow
+           contract). The three floating layers — drop / material-rim / under-cast —
+           fade in driven by the SAME `--dock-expand-t` scalar the radius glides on:
+           `--dock-wrap-elev` is the scalar as a 0→1 percent, so each layer's alpha
+           tracks the corner morph in LOCKSTEP (ONE clock, ONE register). At
+           expand-t 0 (collapsed/pill) the floating layers are 0%-alpha (invisible)
+           → only the base `--shadow-dock` glow shows; at expand-t 1 (expanded/card)
+           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%);
+        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);
     }
 
     .glass-dock.dock-overflow-wrap .dock-layer--full {
@@ -923,15 +1143,12 @@
         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));
-        /* AW.W3b — the graceful wrap-morph. The wrap/unwrap row-reflow flips
-           `flex-wrap` at the `--dock-overflow-bp` `@media` boundary; without a
-           transition the rows JUMP-CUT. Sequencing the layer's `min-height`
-           through the `--dock-motion-resize` spring MORPHS the reflow. The global
-           PRM gate strips `min-height` from the transition-property under reduce →
-           the morph snaps (0 morph frames) while the reflow still completes. The
-           wrap radius swap (`.collapsed` / `@media`) glides too — `border-radius`
-           is in the shared `:not(.vertical)` transition list (AW.W3b scope 2). */
-        transition: min-height var(--dock-motion-resize);
+        /* AX.W04 — NO `transition: min-height` JS-morph (the AW.W3b spring-keyed
+           min-height detector is RETIRED — the false `proof:dock-layering-polish`
+           wrap-reflow claim is STRUCK). The reflow is intrinsic flex: rows
+           appear/vanish on the cap crossing with no second clock. The radius +
+           shadow lift ride the `--dock-expand-t` scalar (the W01 single clock),
+           NOT a CSS transition on the retired `--dock-motion-resize` list. */
     }
 
     .glass-dock.dock-overflow-wrap .dock-layer--summary {
@@ -943,10 +1160,15 @@
         display: none;
     }
 
+    /* Collapsed, a wrap dock is the single-row summary PILL. `white-space: nowrap`
+       keeps the summary on one line; the inline cap stays `max-inline-size:
+       var(--dock-max-inline-size)` (inherited from the `.dock-overflow-wrap` rule
+       above) so the collapsed box still shrink-wraps to the small summary's
+       max-content (NOT the full cap). The
+       radius morph resolves to `--radius-pill` at collapsed (--dock-expand-t 0) and
+       the box-shadow to the flat `--shadow-dock` glow (--dock-wrap-elev 0%). */
     .glass-dock.dock-overflow-wrap.collapsed {
-        border-radius: var(--radius-pill);
         white-space: nowrap;
-        max-width: none;
     }
 
     .dock-separator {
@@ -1151,45 +1373,14 @@
        `popover-animate` motion vocabulary. Click-anchored popovers
        (no dock-keep semantics) compose `<Popover>` directly. */
 
-    /* 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)
-                )
-                var(--dock-wrap-desktop-padding-inline, 0.75rem);
-        }
-
-        .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-overflow-wrap .dock-layer--summary {
-            height: var(--dock-layer-height, 2.5rem);
-        }
-
-        .glass-dock.dock-overflow-wrap .dock-separator {
-            display: block;
-        }
-    }
+    /* AX.W04 F0 — the `@media (min-width: 640px)` desktop snap-back + the
+       `--dock-overflow-bp` token are DELETED. The prior viewport breakpoint forced
+       `flex-wrap: nowrap` + `max-width: none` above 640px, so the dock NEVER
+       wrapped on a wide viewport even when its row overflowed (the 800px → 1861px
+       viewport-bleed defect). The wrap is now CONTENT-driven: the always-on
+       `flex-wrap: wrap` + the `max-inline-size: var(--dock-max-inline-size)` cap
+       above (over the base shrink-wrap) reflow to N rows at ANY width on the
+       over-cap crossing — no viewport coupling, no breakpoint. */
 
     /* O.W6 Lane D — Touch-target floor (speedtest AC.W6 F2.AA-03 / WCAG
        2.5.5). On coarse-pointer devices (touch), every dock-control's