@mkbabb/glass-ui 3.11.2 → 3.13.0

package/dist/styles/dock/morph-bridge.css

@@ -0,0 +1,123 @@
+/* dock/morph-bridge.css — the AZ.W-MORPH-SHOWCASE metaball-teardrop bridge (H4 arm a).
+ *
+ * The net-new CSS SVG-goo filter that hides the V↔H dock topology jump-cut. The
+ * fleet's Arch B picks "the existing goo-blob mounted behind the docks OR a net-new
+ * CSS SVG-goo filter … the implementation picks per perf/browser." This wave picks the
+ * CSS SVG-goo filter — the M5-DETERMINISTIC choice: the bridge has NO free-running
+ * `uTime` (the goo-blob's three wall-clock channels would RED the M5 scalar-binding
+ * clause), NO WebGL pass at all (so the HG5 frame budget clears trivially — zero shader
+ * frames), and its teardrop aspect is a PURE function of `--dock-morph-t`. The classic
+ * gooey-CSS trick: blur two plates so their alpha bleeds together, then threshold the
+ * blurred alpha back to a sharp edge (feColorMatrix on the A channel) so the merge
+ * reads as one amorphous metaball silhouette.
+ *
+ * The bridge is DECORATIVE only (the contained-creature constraint — it hosts no dock
+ * children; the real DOM docks crossfade UNDER it). It paints BEHIND the two docks and
+ * fully occludes the reflow at the `t≈0.5` midpoint where both plates are at their
+ * dimmest.
+ *
+ * Determinism (HG4/M5): every animated axis below is `f(var(--dock-morph-t))` (the ONE
+ * inheriting scalar the morph spring writes) or `f(var(--stretch))` (the scalar's
+ * DERIVATIVE the liquid-flex squish writes) — NEVER a CSS animation/transition with its
+ * own clock. A frame captured at a given `--dock-morph-t` is byte-reproducible. */
+
+@layer components {
+    /* The bridge host — sits absolutely behind the two docks, isolation-safe so the
+       goo filter does not leak onto siblings. The two plates inside it are merged by
+       the SVG goo filter referenced via `filter: url(#…)`. */
+    .dock-morph-bridge {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+        pointer-events: none;
+        z-index: 0;
+        /* The goo: blur-then-threshold the child plates' alpha. The filter id is
+           authored once in the showcase SFC (a hidden <svg><filter>); the consumer
+           binds it here. `isolation: isolate` keeps the blur/threshold scoped to the
+           plates, not the page behind. */
+        isolation: isolate;
+        /* Under reduced motion the bridge is hidden — the morph snaps (no teardrop). */
+        opacity: var(--dock-bridge-opacity, 1);
+    }
+
+    /* The goo container the filter applies to — only the plates inside it merge.
+       SCOPED to a TIGHT centered box just larger than the max plate footprint (NOT
+       inset:0 over the whole stage) so the per-frame `feGaussianBlur` repaint covers
+       a small region, not the full stage — the morph frame budget (HG5) clears. The
+       box is sized off the morph spans (the consumer passes --dock-bridge-h-w /
+       --dock-bridge-v-h); `contain: paint` clips the filter work to it. */
+    .dock-morph-bridge-goo {
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        translate: -50% -50%;
+        width: calc(var(--dock-bridge-h-w, 18rem) + 2.5rem);
+        height: calc(var(--dock-bridge-v-h, 16rem) + 2.5rem);
+        display: grid;
+        place-items: center;
+        contain: layout paint;
+        filter: var(--dock-bridge-goo-filter, none);
+    }
+
+    /* A bridge plate — a warm-glass capsule. TWO plates: one tracks the vertical dock
+       footprint (tall capsule), one the horizontal (wide capsule); both shrink toward
+       the shared center as the morph crosses the midpoint so the blur fuses them into
+       ONE teardrop. The size + corner radius are `f(--dock-morph-t)`; the
+       volume-preserving squish reads `--stretch` (the scalar derivative). */
+    .dock-morph-bridge-plate {
+        position: absolute;
+        /* The warm-cream gel body — the metaball-teardrop fill (a soft radial so the
+           blur threshold reads a domed droplet, not a flat slab). */
+        background: radial-gradient(
+            120% 120% at 50% 38%,
+            var(--glass-bg-floating, color-mix(in oklab, var(--card), white 8%)) 0%,
+            var(--glass-bg-resting, var(--card)) 62%,
+            color-mix(in oklab, var(--card), var(--foreground) 6%) 100%
+        );
+        border-radius: 999px;
+        /* The volume-preserving teardrop squish — stretch along the travel axis,
+           compress reciprocally. Reads `--stretch` (the liquid-flex derivative). The
+           vertical plate squishes on Y, the horizontal on X (set per-plate below). */
+        will-change: width, height, transform;
+    }
+
+    /* The VERTICAL plate — a tall capsule (the t=0 silhouette). It collapses its height
+       toward the center as t: 0 → 0.5, where it has merged into the teardrop. Width is
+       the dock's inline footprint; height interpolates full → a thin neck. */
+    .dock-morph-bridge-plate--vertical {
+        width: var(--dock-bridge-v-w, 3.25rem);
+        /* full height at t=0, necking to ~the width (a circle) by t=0.5, gone by t=1 */
+        height: calc(
+            var(--dock-bridge-v-h, 16rem) *
+                (1 - clamp(0, var(--dock-morph-t, 0), 1)) +
+                var(--dock-bridge-v-w, 3.25rem) * clamp(0, var(--dock-morph-t, 0), 1)
+        );
+        opacity: calc(1 - clamp(0, calc((var(--dock-morph-t, 0) - 0.5) * 2), 1));
+        /* squish Y on travel (the tall plate stretches along its collapse axis) */
+        scale: calc(1 / var(--stretch, 1)) var(--stretch, 1);
+    }
+
+    /* The HORIZONTAL plate — a wide capsule (the t=1 silhouette). It grows its width
+       from the center as t: 0.5 → 1. Height is the dock's block footprint; width
+       interpolates a thin neck → full. */
+    .dock-morph-bridge-plate--horizontal {
+        height: var(--dock-bridge-h-h, 3.25rem);
+        width: calc(
+            var(--dock-bridge-h-h, 3.25rem) * (1 - clamp(0, var(--dock-morph-t, 0), 1)) +
+                var(--dock-bridge-h-w, 18rem) * clamp(0, var(--dock-morph-t, 0), 1)
+        );
+        opacity: clamp(0, calc(var(--dock-morph-t, 0) * 2), 1);
+        /* squish X on travel (the wide plate stretches along its growth axis) */
+        scale: var(--stretch, 1) calc(1 / var(--stretch, 1));
+    }
+
+    /* PRM — the bridge is removed; the morph snaps to the target dock (the spring's
+       respectReducedMotion jumps the scalar 0→1 in one frame, the docks land at their
+       endpoints, the goo teardrop never paints). */
+    @media (prefers-reduced-motion: reduce) {
+        .dock-morph-bridge {
+            --dock-bridge-opacity: 0;
+        }
+    }
+}

package/dist/styles/dock/morph.css

@@ -54,18 +54,41 @@
 
     /* 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) {
+       to the horizontal dock (`:not(.vertical)`) — the inline-axis aperture morph;
+       a vertical dock collapses its BLOCK axis (the summary/full FLIP from the
+       orchestrator) and reads its own surface plate (shell.css `.glass-dock.vertical`).
+       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.
+       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) {
+        /* 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
+           `--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
+           applied HERE — and the COLLAPSED endpoint `--glass-bg-wash` must carry it too,
+           else a collapsed dock over light paints the un-darkened wash and the plate
+           vanishes — the C5-2 ΔL≈0.01 collapse, re-surfaced on the collapsed endpoint).
+           The srgb transition mix between the two TINTED endpoints is preserved (the
+           in-flight morph frames are sub-perceptual); at the `0%` rest default both
+           inner oklab mixes are no-ops so this is byte-identical to today. */
         background: color-mix(
             in srgb,
-            var(--glass-bg-dock, var(--glass-bg-resting))
+            color-mix(
+                in oklab,
+                var(--glass-bg-dock, var(--glass-bg-resting)),
+                var(--glass-tint-source) var(--glass-tint-strength)
+            )
                 calc(var(--dock-expand-t, 1) * 100%),
-            var(--glass-bg-wash)
+            color-mix(
+                in oklab,
+                var(--glass-bg-wash),
+                var(--glass-tint-source) var(--glass-tint-strength)
+            )
         );
         border-color: color-mix(
             in srgb,
@@ -78,18 +101,40 @@
     /* 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)
+
+       AY.W-DOCK-CHROME §1 — the LAYOUT-ISOLATION fix: the collapse↔expand morph is
+       an INLINE-WIDTH aperture by contract ("horizontal docks animate width"), so
+       the BLOCK axis MUST be invariant across the morph — otherwise the dock's
+       outer height shrinks ~4px on collapse (the collapsed-pad 0.25rem vs the
+       expanded pad-block 0.375rem, ×2) and, because a free-floating / inline dock
+       sits in normal flow (`display:inline-flex`), that height delta REFLOWS its
+       siblings — the page content jumped as the dock animated (the user's 13:27
+       audit item 1). The fix holds `padding-block` PINNED at the expanded value in
+       BOTH states (no `--dock-expand-t` interpolation on the block axis) so the
+       outer block-size is constant; ONLY `padding-inline` morphs to tighten the
+       collapsed pill inline. The collapsed circle is unaffected — its diameter is
+       owned by the summary pane's own symmetric `block-size` + `aspect-ratio:1`
+       (the `.collapsed .dock-layer--summary` rule below), CENTRED on the dock's
+       stable-height plate by the root `align-items:center`, not by the root pad. So
+       the morph reflows NOTHING vertically: 0px container-height delta. */
+    .glass-dock:not(.vertical):not(.dock-overflow-wrap) {
+        /* The collapsed inline-pad endpoint is the EXPANDED block pad (max'd with the
+           consumer `--dock-collapsed-padding` handle) so the height-pinned collapsed
+           pill is SYMMETRIC → a clean circle at the `--radius-dock` 9999px. The block
+           axis is pinned to the expanded pad (below), so matching the inline collapsed
+           endpoint to it keeps the box square (the B4 "symmetric collapsed padding
+           keeps the pill a circle" intent, preserved through the §1 height-pin). The
+           `max()` lets a consumer set `--dock-collapsed-padding` LARGER for a looser
+           pill but never SMALLER than the block pad (which would re-introduce the
+           narrower-than-tall oval the height-pin would otherwise leave). */
+        --dock-pad-collapsed: max(
+            var(--dock-padding-block, 0.375rem),
+            var(--dock-collapsed-padding, 0px)
         );
+        /* block padding is INVARIANT — the expanded value, both states (the
+           layout-isolation contract above): the inline aperture morphs, the block
+           axis is pinned so the outer height never changes → 0px container reflow. */
+        padding-block: var(--dock-padding-block, 0.375rem);
         padding-inline: calc(
             var(--dock-pad-collapsed) +
                 (var(--dock-padding-inline, 0.5rem) - var(--dock-pad-collapsed)) *
@@ -110,14 +155,17 @@
         box-shadow: var(--shadow-dock-override, var(--shadow-dock-collapsed));
     }
 
-    /* AX.W45-TUNE Q1 — the collapsed summary floors on BOTH axes off the SAME
-       `--dock-collapsed-summary-min-size` token (now MINTED in tokens.css §10 as a
-       tight ≈0.7× of the full control height). The prior rule floored ONLY
-       `min-width` and let the token fall to `--dock-layer-height` (the full control
-       height) — so the collapsed pill read as a full-row stub, not a proportioned
-       squircle. Adding the symmetric `min-block-size` makes the collapsed pill a
-       tight square-ish dot the consumer's glyph sits centred in (the proportioned-
-       pill target the user's Q1 named). */
+
+    /* AY.W-DOCK-NAV B4 — the collapsed summary is a PERFECT CIRCLE. The `.dock-layer`
+       base rule (`.glass-dock:not(.vertical) .dock-layer`) locks `height:
+       var(--dock-layer-height)` (40px) on EVERY layer including the summary; against
+       the 0.85× `--dock-collapsed-summary-min-size` min-width that made the pane
+       40h × 30w — an oval (the user's "circle, not oval"). This rule (1) LIFTS the
+       height-lock so the summary block-sizes to the SAME token its width floors at,
+       and (2) floors both axes to that ONE token, so the collapsed pane is a square
+       and the root's symmetric collapsed padding keeps the pill a circle. The glyph
+       sits centred on both axes. The `aspect-ratio: 1` belt-and-braces guarantees
+       1:1 even if a consumer's collapsed-slot content is wider than the floor. */
     .glass-dock.collapsed .dock-layer--summary {
         min-width: var(
             --dock-collapsed-summary-min-size,
@@ -127,6 +175,15 @@
             --dock-collapsed-summary-min-size,
             var(--dock-layer-height, 2.5rem)
         );
+        block-size: var(
+            --dock-collapsed-summary-min-size,
+            var(--dock-layer-height, 2.5rem)
+        );
+        height: var(
+            --dock-collapsed-summary-min-size,
+            var(--dock-layer-height, 2.5rem)
+        );
+        aspect-ratio: 1;
         justify-content: center;
     }
 
@@ -146,17 +203,62 @@
         --dock-expand-t: var(--dock-morph-t);
     }
 
+    /* AY.W-DOCK-NAV B15 — the EMPTY-collapsed-summary trap. A dock with a
+       `#persistent` control but NO `#collapsed` slot (the overview first-section
+       dock) still renders a `.dock-layer--summary` pane that floors to the circle
+       min-width — so collapsed it read as a WIDE pill: the persistent Home glyph on
+       the LEFT + an empty circle of dead space on the RIGHT (the measured 84×50
+       oval). Expanding then grew the content INTO that right-side void, so the
+       morph read "from the right" not center-out (the user's B15). When the summary
+       slot is EMPTY (`:not(:has(*))`), collapse it to zero width + no floor so the
+       persistent control stands alone as the collapsed circle, and the morph grows
+       symmetrically about the persistent. An empty Vue `#collapsed` slot renders
+       ZERO child nodes (no whitespace text node either), so `:empty` matches it
+       exactly — and a flat `:empty` avoids the nested-`:has()` form Lightning CSS
+       drops. An authored `#collapsed` slot (non-empty summary) keeps its circle
+       pill. */
+    .glass-dock.collapsed .dock-layer--summary:empty {
+        min-width: 0;
+        inline-size: 0;
+        padding: 0;
+        margin: 0;
+        border: 0;
+    }
+
+    /* The persistent control IS the collapsed pill in the empty-summary case — drop
+       the inter-region gap so the collapsed circle is exactly the persistent box. */
+    .glass-dock.collapsed:has(.dock-layer--summary:empty) .dock-persistent
+        + .dock-layers {
+        margin-inline-start: 0;
+    }
+
     /* 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
        the expand morph uses — a collapsed→hover→expand gesture is one continuous
        spring, not a `scale`-ease handed off to the width-spring. The hover scale
        and the press squish (`--scale-press-dock`) are now one register on the dock
-       surface. */
+       surface.
+
+       AZ.W-DOCK-FLICKER — the `scale` arm is GATED on `:not([data-morphing])` (the
+       collapse-onset scale-pop fix, C2-2). `.collapsed` flips on SYNCHRONOUSLY when
+       a hovered dock begins collapsing, but the box is still painted at EXPANDED
+       width for the morph's leading frames (the `onSwap` pin + 1-rAF measure-defer
+       in dockMorphContext.ts). The bare `.collapsed:hover { scale: 1.1 }` multiplied
+       that transient ~535px box, painting a ±24-34px right-edge pop (the user's
+       "flashing"). Scoping the SCALE to `:not([data-morphing])` makes the +1.1 lift
+       apply ONLY at rest (the box is the 54px circle then) — during `[data-morphing]`
+       the hover scale is inert, mirroring the shipped `--dock-expand-t`
+       `[data-morphing]` precedent above (morph.css:46-53). The surface arms
+       (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 {
         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]) {
         scale: var(--dock-collapsed-hover-scale);
     }
 
@@ -200,22 +302,44 @@
         border-color: var(--glass-border-floating, var(--glass-border-resting));
     }
 
-    /* ── Adaptive legibility: the dock over a light backdrop (AX.W55 — the literal
-       G2 surface; "Glass dock over VERY LIGHT materials is unreadable") ──────────
-       The dock is the surface the user reported unreadable over light content. Its
-       shell (`--glass-bg-dock`), chassis-strip, and held/open tiers all now read the
-       SAME oklab tint seam the five rungs use, so this ONE bucket block — set when a
-       consumer marks `--glass-backdrop: light` on the dock's ancestor — lifts every
-       dock surface toward ink in lockstep. The tint tokens are INHERITING, so
-       re-pointing them on the `.glass-dock` root re-resolves every nested surface +
-       cascades to the dock CONTROLS (which read `--dock-fg-on-aurora` for their
-       foreground); `--dock-fg-on-aurora` re-points to the warm-ink here so the
-       control glyphs/labels clear AA over the now-darkened plate — ONE reconciled
-       path, the foreground twin folded INTO the probe, not a third fork. The
-       morph-root interp (`.variant-dock:not(.vertical)` above) stays `color-mix(in
-       srgb …)` for the transition; the adaptive darken rides its RESTING endpoint
-       (`--glass-bg-dock`, which carries the tint) — the in-flight morph frames are
-       sub-perceptual (the ratified resting-endpoint-only default). */
+    /* ── 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);
+        --glass-tint-strength: var(--glass-tint-strength-aa);
+        --dock-fg-on-aurora: var(--glass-tint-ink);
+        --muted-foreground: var(--foreground);
+    }
+
+    /* 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);
@@ -235,6 +359,12 @@
        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));

package/dist/styles/dock/overflow.css

@@ -193,9 +193,59 @@
        the floor so the cascade re-resolves at touch scale. */
     @media (pointer: coarse) {
         .glass-dock[data-density] {
-            --dock-local-scale: var(--dock-mobile-scale, 1);
+            /* 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
+               comfort floors at a TIGHTER coarse register than the global --ui-scale
+               (the dock is a dense chrome strip, not a body control): --dock-local-scale
+               falls back to --dock-coarse-scale (≈0.78; × the 1.5 global = ~1.17
+               effective → a ~60px collapsed pill). The consumer knob --dock-mobile-scale
+               WINS the fallback when set on ANY ancestor (inherited in, no specificity
+               war against this block — the dead-knob trap a hard `--dock-mobile-scale:
+               0.78` here would re-create), so a consumer who wants the dock to MATCH
+               the global comfort sets --dock-mobile-scale: 1; one who wants it larger
+               sets >1. The touch floor stays held by the `max(…, --dock-control-floor)`
+               clamp in every scaled control-size (the lift just below). */
+            --dock-local-scale: var(--dock-mobile-scale, var(--dock-coarse-scale, 0.78));
+            /* R5-1 — RE-DECLARE --dock-scale HERE so the consumer knob reaches the
+               geometry cascade. The :root definition (offsets-sizing.css) computes
+               `calc(var(--ui-scale) * var(--dock-local-scale, 1))` AT :root, where
+               --dock-local-scale is the frozen identity 1 — custom-property
+               SUBSTITUTION resolves --dock-scale once at its declaring element, so
+               the descendant --dock-local-scale lift on THIS block never re-flowed
+               into it (the AX.W55 substitution-vs-inheritance trap, 3rd recurrence).
+               Re-declaring --dock-scale on the SAME element that lifts
+               --dock-local-scale makes the var() resolve against the lifted value, so
+               the --dock-mobile-scale / --dock-coarse-scale knobs reach every
+               `calc(<base> * --dock-scale)` geometry leg. Identical to the :root
+               formula by construction. */
+            --dock-scale: calc(var(--ui-scale) * var(--dock-local-scale, 1));
             --dock-control-floor: var(--dock-touch-target, 2.75rem);
             --size-icon-btn: var(--dock-touch-target, 2.75rem);
+            /* R5-1 SWEEP — the OTHER :root tokens that derive from --dock-scale freeze
+               it at the :root value (where --dock-local-scale is the identity 1), so the
+               R5-2 dock-local 0.78 register never reaches them: the SAME
+               substitution-vs-inheritance trap, one level out. With --dock-scale now
+               re-declared ABOVE, RE-RESOLVE each derived token on THIS element so it
+               reads the dock-local --dock-scale (else --dock-icon-glyph /
+               --dock-collapsed-padding / --dock-layer-tab-size paint at the global 1.5×
+               while the density box paints at 1.17× — a desync the R5-2 register would
+               introduce). The formulas are IDENTICAL to their :root definitions; only
+               the resolution element moves so the lifted --dock-scale flows in. */
+            --dock-icon-glyph: calc(1.25rem * var(--dock-scale));
+            --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
+               :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
+               the density-painted --dock-layer-height so the collapsed circle FLOOR
+               tracks the dock scale (the "perfect circle" the user named scales on touch
+               with the box, not a frozen 34px floor). */
+            --dock-collapsed-summary-min-size: calc(
+                var(--dock-layer-height, 2.5rem) * 0.85
+            );
         }
     }
 }