@mkbabb/glass-ui 4.2.0 → 5.0.0

package/src/styles/glass/ladder.css

@@ -38,9 +38,53 @@
        (`tokens/dark-arm.css`), where the tolerant α-mix absorbs the small high-L
        chroma (the gamut-map caveat documented + pinned under the gamut edge there).
        That is the INK derivation, separate from THIS glass-tint mix space. */
+
+    /* BG.W-GLASS-IDIOM-FACTOR — the DRY plate-tint recipe, DECLARED ONCE.
+       The five-rung surface ladder each composed the SAME element-level oklab tint
+       INLINE (5 byte-identical `color-mix(in oklab, var(--glass-bg-<rung>),
+       var(--glass-tint-source) var(--glass-tint-strength))` pastes). The recipe is
+       the W55 adaptive-legibility seam — the rung bg mixed TOWARD the sampled/ink
+       `--glass-tint-source` at the continuous `--glass-tint-strength`; at the `0%`
+       rest default the mix is a no-op (`color-mix(…, X, transparent 0%) ≡ X`),
+       byte-identical to the raw rung bg.
+
+       Factored to ONE declaration: each rung sets only its own `--glass-bg-rung`
+       (the per-rung bg indirection — the EXACT `--glass-border-rung` →
+       `--glass-border-accent` pattern rim.css already runs for the border half) and
+       reads `background: var(--glass-plate-tinted)`. `--glass-plate-tinted` resolves
+       its `var(--glass-bg-rung)` / `--glass-tint-source` / `--glass-tint-strength`
+       at the rung element where it is composed (a custom property substitutes its
+       var() refs against the SAME element's other customs), so the per-rung bg AND
+       the per-element W55 re-points (the `:where()` content-tier + overlay-band tint
+       cascades below) reach it unchanged — net-neutral, dist byte-isomorphic. This
+       single home is the ONE place a later wave (BG.W-GLASS-TINT-UNIFY) adds the
+       bias outer-leg, instead of N pastes.
+
+       BG.W-GLASS-REGISTER-UNIFY — `--glass-plate-tinted` is the LADDER-RUNG spelling
+       of the ONE tint recipe; its applied-at-the-element twin for NON-ladder surfaces
+       is `@utility glass-fill` (glass/surfaces.css, reading `--glass-fill-rung`). Same
+       oklab W55 seam, two delivery seams: the ladder rungs read the token, a Card /
+       button / dock surface APPLIES the utility. A NON-ladder surface never re-spells
+       the `color-mix(in oklab, …)` — it composes `glass-fill`; the `--glass-bg-*-tinted`
+       pre-composed tokens + the `:root --glass-bg-dock` inline tint are the substitution-
+       trap forms the utility supersedes (their DELETE is the sibling-gate-coordinated
+       atomic step). */
+    .glass-wash,
+    .glass-quiet,
+    .glass-resting,
+    .glass-floating,
+    .glass-overlay {
+        --glass-plate-tinted: color-mix(
+            in oklab,
+            var(--glass-bg-rung),
+            var(--glass-tint-source) var(--glass-tint-strength)
+        );
+    }
+
     .glass-wash {
         position: relative;
-        background: color-mix(in oklab, var(--glass-bg-wash), var(--glass-tint-source) var(--glass-tint-strength));
+        --glass-bg-rung: var(--glass-bg-wash);
+        background: var(--glass-plate-tinted);
         backdrop-filter: var(--glass-blur-wash);
         /* BB.W-GLASS-ACCENT — the rung border ink feeds the accent-composed
            `--glass-border-accent` (rim group above); byte-identical at 0%. */
@@ -63,7 +107,8 @@
        Spine tier wires its own rung at instrument-chassis.css. */
     .glass-quiet {
         position: relative;
-        background: color-mix(in oklab, var(--glass-bg-quiet), var(--glass-tint-source) var(--glass-tint-strength));
+        --glass-bg-rung: var(--glass-bg-quiet);
+        background: var(--glass-plate-tinted);
         backdrop-filter: var(--glass-blur-quiet);
         --glass-border-rung: var(--glass-border-quiet);
         border: 1px solid var(--glass-border-accent);
@@ -75,7 +120,8 @@
 
     .glass-resting {
         position: relative;
-        background: color-mix(in oklab, var(--glass-bg-resting), var(--glass-tint-source) var(--glass-tint-strength));
+        --glass-bg-rung: var(--glass-bg-resting);
+        background: var(--glass-plate-tinted);
         backdrop-filter: var(--glass-blur-resting);
         --glass-border-rung: var(--glass-border-resting);
         border: 1px solid var(--glass-border-accent);
@@ -102,7 +148,8 @@
            dark-substrate consumer dials in on an ancestor. */
         --glass-backdrop: light;
         position: relative;
-        background: color-mix(in oklab, var(--glass-bg-floating), var(--glass-tint-source) var(--glass-tint-strength));
+        --glass-bg-rung: var(--glass-bg-floating);
+        background: var(--glass-plate-tinted);
         backdrop-filter: var(--glass-blur-floating);
         --glass-border-rung: var(--glass-border-floating);
         border: 1px solid var(--glass-border-accent);
@@ -117,7 +164,8 @@
            (see .glass-floating). */
         --glass-backdrop: light;
         position: relative;
-        background: color-mix(in oklab, var(--glass-bg-overlay), var(--glass-tint-source) var(--glass-tint-strength));
+        --glass-bg-rung: var(--glass-bg-overlay);
+        background: var(--glass-plate-tinted);
         backdrop-filter: var(--glass-blur-overlay);
         --glass-border-rung: var(--glass-border-overlay);
         border: 1px solid var(--glass-border-accent);
@@ -226,7 +274,7 @@
             calc(
                 var(--glass-tint-strength-floor) +
                 (var(--glass-tint-strength-aa) - var(--glass-tint-strength-floor)) *
-                max(0, (var(--glass-backdrop-luma, 0) - var(--glass-backdrop-luma-knee, 0.6)) / (1 - var(--glass-backdrop-luma-knee, 0.6)))
+                max(0, (var(--glass-backdrop-luma, 0) - var(--glass-backdrop-luma-knee)) / (1 - var(--glass-backdrop-luma-knee)))
             ),
             var(--glass-tint-strength-aa)
         );
@@ -282,16 +330,28 @@
            clamp resolves EXACTLY `--glass-tint-strength-floor` (the GLASS-IDENTITY calm
            identity, byte-equal); rising luma ramps the lift CONTINUOUSLY; the clamp floors
            at the 4% identity and ceilings at the bounded AA — never an unconditional 20%
-           slab (the AZ grey-slab is the OPPOSITE of this earned, measured track). This
-           RETIRES the discrete `@container --glass-backdrop: light` bucket as the strength
-           driver — the continuous calc subsumes it (the bucket survives only as a no-
-           `@property` degrade fallback). */
+           slab (the AZ grey-slab is the OPPOSITE of this earned, measured track).
+
+           BG.W-GLASS-SIGNAL-TRUTH (M7) — THE BAND-DRIVER DECISION (reconciled to ONE):
+           the declarative `@container --glass-backdrop: light` bucket below is THE BAND
+           DRIVER (a consumer/shell writes `--glass-backdrop: light` on an ancestor where
+           it KNOWS the backdrop is bright — the AA darken then reaches every descendant
+           content tier), and this CONTINUOUS `--glass-backdrop-luma` clamp is the DYNAMIC
+           REFINEMENT layer that engages WHERE A LUMA WRITER FIRES — the dock (its own
+           `useGlassBackdropLuminance` observer, wired ON) and any band surface a consumer
+           wires the observer to. On a content-tier Card with no wired observer + no
+           ancestor bucket, `--glass-backdrop-luma` reads the registered initial 0 → the
+           clamp resolves the calm floor (the honest calm identity — a plate over an
+           UNKNOWN backdrop stays warm, never a false darken). The prior claim that this
+           clamp "RETIRES the bucket as THE driver" was the contradictory-canon half the
+           M7 audit named (glass-fx.css declared the bucket the default path); the bucket
+           is the band driver, the clamp is the refinement — no double-ownership. */
         --glass-tint-strength: clamp(
             var(--glass-tint-strength-floor),
             calc(
                 var(--glass-tint-strength-floor) +
                 (var(--glass-tint-strength-aa) - var(--glass-tint-strength-floor)) *
-                max(0, (var(--glass-backdrop-luma, 0) - var(--glass-backdrop-luma-knee, 0.6)) / (1 - var(--glass-backdrop-luma-knee, 0.6)))
+                max(0, (var(--glass-backdrop-luma, 0) - var(--glass-backdrop-luma-knee)) / (1 - var(--glass-backdrop-luma-knee)))
             ),
             var(--glass-tint-strength-aa)
         );
@@ -299,6 +359,31 @@
         --muted-foreground-strong: var(--on-glass-muted-strong);
     }
 
+    /* F2.R1 W-DARK-READABILITY-REPAIR (paint re-open — the full-route dark census Class-3
+       mustFix) — the on-glass MUTED lift EXTENDS to the mid-tone / tone-tinted / selected-
+       glass surfaces the calm content-tier :where() above does NOT reach. The muted register
+       (--muted-foreground = --neutral-5, calibrated "AA vs the OPAQUE page") COLLAPSES on a
+       composited TINTED / mid-tone glass plate exactly as it does on the calm content tier —
+       but these surfaces are NOT content tiers, so the re-point above never reached them
+       (the census measured the raw page-muted at WCAG 3.3-4.27 dark, BELOW AA): the feedback
+       TONE-TINTED plates (`.feedback-tone` — Alert / Notification / Toast, the AlertDescription
+       caption + mono labels), the selected-glass capsule CHIPS + overflow PUCKS (`.glass-capsule`
+       — selectable-chip / toggle-chip / stacked-icons / tags-input, idle `text-muted-foreground`
+       ink), and the `.metric-badge` mono label. These plates composite BRIGHTER than the calm
+       quiet plate (the quiet content plate lands L≈0.28; a tone-tinted / selected chip plate
+       lands L≈0.30-0.35), so a subordinate light ink loses contrast on them — they need the
+       STRONGER on-glass rung (`--on-glass-muted-strong`, one step more present) to clear the
+       floor while STAYING subordinate to the L90 --foreground ink. ONE register (no new token,
+       no fork — it READS the existing on-glass -strong rung the wave already ships), the SAME
+       substitution-over-redeclaration discipline the content-tier re-point uses. The rung
+       auto-flips per mode (the on-glass tokens carry their own light/dark arms); in light these
+       surfaces already read the on-glass register on their light glass, byte-consistent. Machine-
+       locked by `proof:glass` dark-legibility DL5. */
+    :where(.feedback-tone, .glass-capsule, .metric-badge) {
+        --muted-foreground: var(--on-glass-muted-strong);
+        --muted-foreground-strong: var(--on-glass-muted-strong);
+    }
+
     /* AX.W55 — the `contrast-color()` foreground-ink flip (Chrome 147+/Safari 26+).
        A PROGRESSIVE-ENHANCEMENT layer, NEVER the load-bearing floor (Open-Q #5
        ratified): the declarative bucket above already carries AA on ALL engines (it
@@ -364,126 +449,4 @@
            in the @container bucket with the rest of the bright-condition darken. */
     }
 
-    /* ── The opaque escape (AX.W54) ───────────────────
-       The level-0 endpoint of the SAME glass machinery — a solid `--card` plate
-       (the opacity seam → 1) with `blur(0)` (the blur seam → 0), routed through
-       the ONE `--glass-level` knob. NOT a parallel solid `background:` recipe:
-       a `.glass-*` surface that ALSO carries `.glass-opaque` keeps its glass edge,
-       rim, and under-shadow (a solid plate with a glass edge, not a bare div), and
-       the @supports fallback + the a11y brackets compose coherently. This is the
-       explicit opt-out from the MAXIMAL glass default (dense data, forced-colors,
-       a consumer that wants a flat surface). */
-    .glass-opaque {
-        --glass-level: 0;
-        /* BA.W-DARK-MATERIAL scope 7 — the opaque escape suppresses the adaptive TINT axis
-           too (not just the opacity/blur level). A solid opaque plate has no translucent
-           backdrop to darken-over, so the self-engage tint is meaningless on it; zeroing the
-           strength keeps the opaque escape bucket-INVARIANT (the unset floor and the bright
-           bucket resolve the SAME solid plate — the byte-identity canary). Without this, the
-           scope-7 unconditional content-tier floor (4%) tinted even the solid plate, breaking
-           the opt-out's "flat surface" contract. */
-        --glass-tint-strength: 0%;
-    }
-
-    /* ── Content-aware under-shadow modifier (AV.W15 M4) ──────────────
-       Apple raises the under-shadow over text (so the glass reads as
-       lifting OFF the text) and drops it over solid light. The modifier
-       is ATTRIBUTE-DRIVEN, no JS: a consumer adds `.glass-over-text`
-       (or `[data-over-content="text"]`) to a text-bearing glass surface to
-       swap it ONE under-shadow rung heavier, or `[data-over-content="solid"]`
-       to lighten it one rung over a solid-light backdrop. It reuses the
-       existing `--glass-under-shadow-{quiet,default,vivid}` rungs (no new
-       shadow value — `vivid` is sufficient over text), redefining only the
-       leading under-shadow layer per tier; the lift stack is untouched.
-
-       The selectors are per-tier so the swap is rung-correct
-       (quiet→default, resting→vivid). `.glass-floating` already sits at the
-       `vivid` ceiling over text, so the heavier variant is a no-op there
-       (the rung saturates) — documented, not an error. */
-    .glass-quiet.glass-over-text,
-    .glass-quiet[data-over-content="text"] {
-        box-shadow: var(--glass-under-shadow-default), var(--glass-shadow-quiet);
-    }
-    .glass-resting.glass-over-text,
-    .glass-resting[data-over-content="text"] {
-        box-shadow: var(--glass-under-shadow-vivid), var(--glass-shadow-resting);
-    }
-
-    /* The inverse — over a solid-light backdrop the under-shadow lightens
-       one rung (the glass need not lift as hard off a flat bright field). */
-    .glass-resting[data-over-content="solid"] {
-        box-shadow: var(--glass-under-shadow-quiet), var(--glass-shadow-resting);
-    }
-    .glass-floating[data-over-content="solid"] {
-        box-shadow:
-            var(--glass-material-rim),
-            var(--glass-under-shadow-default),
-            var(--glass-shadow-floating);
-    }
-
-    /* Grain noise overlay — reuses paper texture SVG, no extra assets.
-       BB.W-LIQUIDHOVER — the disco-grain pop (T8-F6) killed at the COMPOSITION CLASS:
-       the `background-image` is ALWAYS PRESENT (decoded once at rest, NEVER toggled to
-       `none`), and any STATE-driven grain engagement cross-fades the `opacity` ONLY on
-       the thin `--glass-grain-engage-duration` (~120ms linear) clock. A `background-
-       image: none → var(--paper-clean-texture)` engage decodes-and-appears in one frame
-       (the pop); the opacity cross-fade is a compositor-cheap interpolation with the
-       image constant — the only sanctioned grain engage. The `transition` lives HERE so
-       a hover/active grain lift (wherever a glass surface raises grain on interaction)
-       reads as a smooth fade by construction, not a discrete swap. */
-    .glass-wash::after,
-    .glass-quiet::after,
-    .glass-resting::after,
-    .glass-floating::after,
-    .glass-overlay::after {
-        content: '';
-        position: absolute;
-        inset: 0;
-        border-radius: inherit;
-        /* The grain texture is the `background-image` longhand (NOT the `background`
-           shorthand) so the image stays a STABLE always-present layer the engage
-           never re-declares — the structural anti-pop: opacity is the only animated
-           channel, the image is never `none → image`. */
-        background-image: var(--paper-clean-texture);
-        background-repeat: repeat;
-        background-size: var(--paper-texture-size);
-        opacity: var(--glass-grain-opacity);
-        /* The opacity cross-fade engage — plain ~120ms linear direct-write (no spring,
-           no overshoot — instant-but-smooth per the ask). Under the PRM / reduced-
-           transparency brackets the clock collapses to 0ms (the a11y bracket below). */
-        transition: opacity var(--glass-grain-engage-duration, 120ms) linear;
-        pointer-events: none;
-        mix-blend-mode: overlay;
-    }
-
-    /* BB.W-LIQUIDHOVER — the grain engage collapses to INSTANT under reduced motion (a
-       grain that cross-fades on hover under reduce is still motion; accessibility is
-       absolute). The reduced-transparency / forced-colors brackets already zero
-       `--glass-grain-opacity` (a11y-fallback.css), so the grain is inert there; this
-       bracket covers the reduced-MOTION case where the grain still paints but must not
-       animate. */
-    @media (prefers-reduced-motion: reduce) {
-        .glass-wash::after,
-        .glass-quiet::after,
-        .glass-resting::after,
-        .glass-floating::after,
-        .glass-overlay::after {
-            transition: none;
-        }
-    }
-
-    /* The unified rim (AW.W22) + the BB.W-GLASS-ACCENT per-INSTANCE chromatic-RIM
-       tint group (the rim-ink + --glass-material-rim ring + the per-rung
-       --glass-border-accent border, light + dark arms) lives in glass/rim.css
-       (carved at BB.W-CARVE4 — the next adjacent @layer components block, the SOLE
-       writer of --glass-material-rim/--glass-border-accent). */
-
-    .dark .glass-wash::after,
-    .dark .glass-quiet::after,
-    .dark .glass-resting::after,
-    .dark .glass-floating::after,
-    .dark .glass-overlay::after {
-        mix-blend-mode: soft-light;
-    }
-
 }

package/src/styles/glass/liquid-enter.css

@@ -10,10 +10,13 @@
 
    THREE registers share ONE grammar (NOT three engines):
      • MOUNT  — this file (`.liquid-enter`), plain @keyframes-on-mount, the Safari-15
-                floor, the DEFAULT. Zero JS.
-     • SCROLL — `.scroll-build`/`.scroll-cascade` (scroll-choreography.css), AUGMENTED
-                in place; this file does NOT touch them (Bug B: a 2nd `animation:`
-                shorthand on `.scroll-build > *` clobbers `gl-page-build`).
+                floor, the DEFAULT. Zero JS. The route-enter page entrance rides the
+                sibling `.route-enter` on-mount @keyframes (transitions.css, BG.W-ROUTE-
+                TRANSITION — the bare keyed `<component>` swap), not this recipe.
+     • SCROLL — `.scroll-cascade` (scroll-choreography.css), the section cascade; this
+                file does NOT touch it. (The `.scroll-build` page-build recipe is
+                RETIRED — BG.W-ROUTE-TRANSITION — so its `gl-page-build`-clobber fence
+                is moot.)
      • TRIGGER— `useLiquidReveal`/`useBloomUp` (the JS source-rect bloom).
 
    THE FOUR CHANNELS (the iOS-27 read, design.md §SPATIAL/EFFECTS split):
@@ -197,31 +200,16 @@
     }
 }
 
-/* ── The Safari < 17.2 `linear()` floor (DELTA-ASSAY §3) ──
-   `linear()` spring/punch curves UNPARSE before Safari 17.2 → the `animation`
-   timing falls to the UA default, killing the overshoot. Supply a cubic-bezier
-   floor so the entrance still reads bouncy (not a dead linear ramp) on legacy
-   WebKit. Plain @keyframes + scale/translate/opacity/filter longhands are
-   themselves Safari-15-safe; only the spring CURVE needs the floor. */
-@supports not (animation-timing-function: linear(0, 1)) {
-    @layer components {
-        @media (prefers-reduced-motion: no-preference) {
-            .liquid-enter {
-                animation-timing-function: cubic-bezier(0.34, 1.56, 0.64, 1);
-            }
-            .liquid-enter.is-cel,
-            .liquid-enter.is-cel > .cartoon-cast {
-                animation-timing-function: cubic-bezier(0.5, -0.2, 0.4, 1.4);
-            }
-        }
-    }
-}
+/* The Safari < 17.2 `linear()` cubic-bezier floor was COLLAPSED at BG.NF.2
+   W-LEGACY-LADDER-COLLAPSE — both targets (current Chrome + current Safari)
+   parse `linear()` spring curves, so the `--spring-*` tokens are the sole
+   timing source; the bezier degrade arm served no target engine. */
 
 /* ── REDUCED-MOTION CARVE (the vestibular floor — WCAG 2.3.3 · design.md P6) ──
    Under `prefers-reduced-motion: reduce` the entrance keeps the FADE and drops the
    transform + squish + bounce + blur + stagger + cast in ONE arm (opacity is not a
    vestibular trigger). One calm paint on the short clock, delay → 0. This mirrors the
-   `.glass-reveal` + `.scroll-build` PRM precedent. The shipped `--ease-cartoon-punch`
+   `.glass-reveal` + `.route-enter` PRM precedent. The shipped `--ease-cartoon-punch`
    already re-aliases to `--ease-standard` under reduce (scheme-motion.css) and
    `--motion-weight → 0` zeroes the arc — this carve is the belt-and-suspenders floor
    that also drops the keyframe channels outright. */

package/src/styles/glass/liquid-fill.css

@@ -0,0 +1,65 @@
+/* ════════════════════════════════════════════════════════════════════════
+   .glass-liquid-fill — the ONE shared liquid-fill register (BG.W-LIQUID-FILL).
+
+   The warm glass-cylinder fill — a continuous rounded pill of warm tinted glass
+   over a track — factored ONCE out of the Slider's `.slider-range` composite so
+   EVERY meter/fill consumer COMPOSES it instead of re-forking the
+   backdrop-blur + rim + under-shadow recipe. Fewer-sharper-primitives: ONE
+   liquid-fill recipe, N surfaces.
+
+   ≥2 consumers by construction (the overfitting bar cleared by extraction):
+     · #1  Slider's `.slider-range` RE-READS it (the reference implementation —
+           the glass cylinder you pull; it bridges its own `--slider-range-*`
+           consumer-override tokens onto the register's knobs).
+     · #2  `<Progress variant="liquid">` — the glass meter (the speedtest fill
+           meter consumes it on the 5.0.0 bump).
+
+   PHASE-COLOUR COMPOSABLE, ZERO PER-SITE GLASS KNOWLEDGE. A surface tints the
+   fill by setting the ONE `--liquid-fill-tint` knob (a phase hue, a brand colour,
+   the warm-cream default) — it never touches `backdrop-filter`, the rim, or the
+   under-shadow. The register owns every glass mechanic; the surface owns only the
+   colour. The four knobs (all optional, warm-glass defaults):
+     · --liquid-fill-tint      — the fill hue (default the warm-cream capsule amber).
+     · --liquid-fill-strength  — the tint mix % against the warm 0-alpha leg (88%).
+     · --liquid-fill-blur      — the backdrop blur rung (the quiet ~2px-equiv radius).
+     · --liquid-fill-shadow    — the under-shadow leg (the glass-thickness floor).
+
+   @layer components, @import-ed in glass.css AFTER the glass-capsule register (so
+   the `--glass-bg-*`/`--glass-*-rim`/`--glass-under-shadow-*`/`--glass-capsule-warm`
+   tokens resolve) and BEFORE the consuming slider/progress recipes.
+
+   Compositor-only + Safari-native by construction (the §7 floor): the blur routes
+   `--glass-blur-quiet` (which SCALES by `--glass-level`, so the opaque escape /
+   prefers-reduced-transparency / forced-colors flatten it with the rest of the
+   band); no `backdrop-filter: url()`, no SVG goo, no WebGL. The 0-alpha mix leg is
+   a WARM `oklch(… / 0)`, NEVER bare `transparent` (the WebKit black-premultiply
+   hole, build-trap-(d)).
+   ════════════════════════════════════════════════════════════════════════ */
+
+@layer components {
+    .glass-liquid-fill {
+        border-radius: var(--radius-pill);
+        /* The warm tinted glass fill — the tint mixes against a warm 0-alpha leg so
+           the cylinder is a warm tinted `.glass-atom` over the field, not a flat bar.
+           `--liquid-fill-tint` is the ONE phase-colour knob (default the warm-cream
+           capsule amber — the lib identity; the brand/phase hue is the consumer's). */
+        background: color-mix(
+            in oklab,
+            var(--liquid-fill-tint, var(--glass-capsule-warm))
+                var(--liquid-fill-strength, 88%),
+            oklch(0.9 0.05 75 / 0)
+        );
+        /* The blur routes the `--glass-blur-quiet` rung (the ~2px-equivalent radius
+           that SCALES by `--glass-level`), not a literal blur off the level knob. */
+        backdrop-filter: var(--liquid-fill-blur, var(--glass-blur-quiet));
+        -webkit-backdrop-filter: var(--liquid-fill-blur, var(--glass-blur-quiet));
+        /* The unified edge rim (W52) reads the cylinder's curvature; the under-shadow
+           lays the glass-thickness floor at the leading edge. */
+        box-shadow:
+            var(--glass-material-rim),
+            var(--liquid-fill-shadow, var(--glass-under-shadow-quiet));
+        transition:
+            background var(--duration-fast) var(--ease-standard),
+            box-shadow var(--duration-fast) var(--ease-standard);
+    }
+}

package/src/styles/glass/material.css

@@ -48,6 +48,51 @@
         position: relative;
     }
 
+    /* ── BG.W-GLASS-CLIP-DISCIPLINE — the ONE paint-box clip register ───────────
+       The scattered per-class clip DIALECTS — `.glass-card` → `contain: layout
+       style paint` and `.glass-btn` → `contain: paint` (both surfaces.css) — are
+       RETIRED into this ONE `contain: paint` register on a NARROWED CONTENT +
+       `.glass-card` + glass-atom selector, so every composing content surface
+       inherits ONE discipline instead of two divergent per-class values.
+
+       THE NARROWING (the blast-radius fence — do NOT re-widen):
+       • INCLUDED — the CONTENT tiers (`.glass-wash`/`.glass-quiet`/`.glass-
+         resting`, the tier the real <Card> composes via
+         surfaceClass('glass','resting')) + the `.glass-card` convenience
+         shorthand + the `.glass-btn` glass-atom. `.glass-card`/`.glass-btn` are
+         the AY.W-A11Y-PERF O-4 nested-backdrop-cost surfaces — a glass Button's
+         own backdrop sample must not escape its card box (proof:nested-backdrop-
+         budget reads `contain:paint` on BOTH).
+       • EXCLUDED — the OVERLAY BAND (`.glass-floating`/`.glass-overlay` — reka
+         Dialog/Sheet/Popover/Command/DropdownMenu/HoverCard) carries NO clip: a
+         PopperArrow / submenu / Select-scroll that does NOT portal-to-body paints
+         PAST the rounded corner and a clip would SEVER it (the Popper-arrow-
+         survives cell).
+       • EXCLUDED — the 4 DOCK CONTROLS (`.dock-icon-button`/`.dock-tab-button`/
+         `.dock-select-trigger`/`.dock-dropdown-trigger`) carry NO clip: the
+         BA.W-DOCK-GEOMETRY freed cross-axis + the 1.1× hover plate + the
+         `--dock-control-safe-inset` must stay un-clipped (proof:dock-plate-
+         clearance).
+
+       `contain: paint` clips DESCENDANTS only — the surface's OWN rim / drop-
+       shadow / focus-ring is NOT clipped (device-verified). It is PAINT-only
+       (never `layout`, which would make the box a containing block for
+       abs/fixed descendants — the pre-empt of the overlay-clip class the blast-
+       radius note names). Each clipped surface carries a `border-radius`
+       (`.glass-card` → `--radius-card`, `.glass-btn` → `--radius-pill`, the
+       ladder rungs inherit the host's rounded box; the `::before`/`::after`
+       pseudos carry `border-radius: inherit`) so the clip FOLLOWS the corner (a
+       clip with no radius trims to a SHARP RECT — the bug proof:glass-clip's
+       radius-alongside arm reds). `overflow: hidden` stays FORBIDDEN (it would
+       clip the focus ring). */
+    .glass-wash,
+    .glass-quiet,
+    .glass-resting,
+    .glass-card,
+    .glass-btn {
+        contain: paint;
+    }
+
     /* (b) The rim — UNIFORM across all rungs (ONE `--glass-edge-light` token,
        not a per-rung family). The floating/overlay tiers previously wired it
        into their box-shadow stack; it now rides the material group as a
@@ -107,8 +152,24 @@
            (tokens.css §specular-intensity), default 0 so a static, unwired
            surface is CLEAN and the @property `initial-value: 0` dormancy is no
            longer defeated by a floor. Hover/active lift it through the same
-           cohort (the interaction-light state machine below). */
-        --specular-intensity: var(--glass-specular-intensity-rest, 0);
+           cohort (the interaction-light state machine below).
+
+           BG.W-GLASS-DYNAMICS — the press-COUPLED magnitude (absorbs 13.5, soft-
+           gated by F5.1). The specular reads the ONE `--glass-btn-press-t` spring
+           drive (Button.vue / a dock control writes it off `useSpringPress`), so on
+           RELEASE — after the binary CSS `:active` lets go — the gleam SETTLES with
+           the spring's alive overshoot (the press-swell returns) instead of snapping
+           to rest. Soft-gated: `--glass-btn-press-t` defaults 0 (property-regs.css),
+           so an unwired surface reads `max(rest, 0.16*0) = rest` byte-identical — no
+           hard F5.1 dependency. The `<number> * <number>` calc is engine-safe (NOT a
+           registered var nested in an hsl() alpha — the Chromium-computes-to-0 class
+           the `opacity` path deliberately avoids). The button's OWN active LERP
+           (surfaces.css `.btn-glass:active::before`) still wins while pressed; this
+           carries the general release-settle beneath it. */
+        --specular-intensity: max(
+            var(--glass-specular-intensity-rest, 0),
+            calc(var(--glass-specular-intensity-active, 0.16) * var(--glass-btn-press-t, 0))
+        );
         /* AX.W52 D19 — a thin, BOUNDED, pointer-anchored EDGE gleam (not the prior
            full-plate central disc that washed small tiles muddy). The geometry is an
            EXPLICIT-radius circle bounded by `--glass-specular-size` (36% of the
@@ -146,10 +207,30 @@
            warm-cream floor). Each gradient stop reproduces its original alpha via
            `color-mix(in srgb, <core> N%, transparent)` (=== the prior `<core> / 0.NN`),
            so the geometry + falloff is byte-identical at rest. */
+        /* BG.W-GLASS-DYNAMICS — the iOS-27 backdrop-HUE sample seam (the 2nd of the
+           ≤2 chromatic pairs, beside W-GLASS-ACCENT). BG.W-GLASS-SIGNAL-TRUTH (M9) —
+           ONE hue channel, ONE writer: the seam reads `--glass-ambient-hue` (the REAL
+           observer write — `useGlassBackdropLuminance` writes a sampled `oklch()` modal
+           hue there, tokens/glass.css §BE.W-AMBIENT-TINT), NOT the never-written
+           `--glass-backdrop-hue` the prior comment falsely claimed the observer wrote.
+           So a dock/card catch-light picks up the field hue SUB-PERCEPTUALLY over a live
+           aurora WHERE THE OBSERVER IS WIRED, at the bounded `--glass-ambient-strength`
+           (the companion write-strength knob the observer's target owns). NEUTRAL BY
+           DEFAULT — the `--glass-ambient-hue` registered initial `transparent` +
+           `--glass-ambient-strength` initial `0%` make the OUTER mix
+           `color-mix(in oklab, X, transparent 0%) === X` byte-identical, so an unwired
+           surface reads the warm-cream core exactly (the REFERENCE FENCE: no chromatic
+           pickup until the observer writes the hue). The REST hairline (the `box-shadow`
+           below) reads the RAW neutral `hsl(40 35% 92%)` — NOT this core — so the
+           RESTING hairline is NEVER chromatic (prismatic reserved for WS6). */
         --glass-specular-core: color-mix(
             in oklab,
-            hsl(40 35% 92%),
-            var(--glass-accent) var(--glass-accent-strength)
+            color-mix(
+                in oklab,
+                hsl(40 35% 92%),
+                var(--glass-accent) var(--glass-accent-strength)
+            ),
+            var(--glass-ambient-hue) var(--glass-ambient-strength)
         );
         background:
             conic-gradient(
@@ -165,7 +246,31 @@
                 transparent 70%,
                 transparent 100%
             );
-        opacity: var(--specular-intensity, 0);
+        /* BG.W-GLASS-DYNAMICS — the resting NEUTRAL specular HAIRLINE (the read-carrier
+           at the calmer blur). WS3 demoted the blur ladder (quiet/resting → 8px), so a
+           demoted plate needs a thin bright rim to still read as GLASS at rest. This
+           inset warm-cream ring FOLLOWS the rounded box (`border-radius: inherit`) and
+           composites `plus-lighter` with the disc/conic above (a bright additive edge).
+           It is NEUTRAL — the raw `hsl(40 35% 92%)`, NEVER the `--glass-specular-core`
+           (which carries the accent + backdrop-hue) — so the resting hairline is never
+           chromatic (the REFERENCE FENCE; prismatic reserved for WS6). It is a STATIC
+           paint (no transition, no @keyframes → `proof:no-layout-animation` + the
+           0-idle-track discipline hold; the interaction transition stays scoped to the
+           :hover/:active block below). It is the SUPPLEMENTARY rim beside the primary
+           `--glass-edge-light` box-shadow rim — the two carry the demoted-blur read. */
+        box-shadow: inset 0 0 0 var(--glass-specular-hairline-width, 0.75px)
+            color-mix(in srgb, hsl(40 35% 92%) var(--glass-specular-hairline-ink, 70%), transparent);
+        /* The `::before` opacity gates the disc + conic (via `--specular-intensity`) AND
+           this rest hairline. A rest FLOOR keeps the neutral hairline lit at rest (the
+           read-carrier) while the interaction lift still rides `--specular-intensity`
+           (hover 0.10 / active 0.16 both clear the floor). `--glass-specular-rest-
+           hairline` (0.07) is a low whisper — at this floor the interaction disc/conic
+           stay sub-perceptual (well under the AX.W52 muddy ceiling), so it reads as a
+           rim hairline, not a center wash. */
+        opacity: max(
+            var(--specular-intensity, 0),
+            var(--glass-specular-rest-hairline, 0.07)
+        );
         /* Per-layer masks (the `,`-separated list pairs with the two backgrounds in
            order): the EDGE conic is masked to the RIM BAND ONLY — transparent across
            the interior, opaque in the outer `--glass-edge-glint-band` (default 22%) — so
@@ -247,8 +352,14 @@
            `.dark` cohort runs a lower hover/active rung (tokens.css §specular-
            intensity `.dark` arm); the rest rung is already 0 so the dark arm only
            softens hover/active via the cohort. The rest rung re-reads the (dark)
-           token here so a dark `:root` override resolves. */
-        --specular-intensity: var(--glass-specular-intensity-rest, 0);
+           token here so a dark `:root` override resolves. BG.W-GLASS-DYNAMICS — the
+           dark arm mirrors the base press-couple `max()` so the `--glass-btn-press-t`
+           release-settle is NOT dropped in dark (the base opacity floor + the neutral
+           box-shadow hairline are inherited unchanged). */
+        --specular-intensity: max(
+            var(--glass-specular-intensity-rest, 0),
+            calc(var(--glass-specular-intensity-active, 0.16) * var(--glass-btn-press-t, 0))
+        );
     }
 
     /* (c) Interaction-light lockstep — hover/active lift the intensity in the
@@ -347,10 +458,23 @@
        THROUGH the dim — see-through AND legible, one element, no pseudo collision. */
     [data-surface="clear"],
     .glass-clear {
-        /* The dynamic scrim strength — DERIVED from the sampled backdrop luma
-           (dims MORE over a bright grid). `0.5` is the safe mid-scrim fallback. */
+        /* BG.W-GLASS-SIGNAL-TRUTH (M6) — the MANDATORY scrim is a STATIC FLOOR the
+           sampled luma can only LIFT, never `var(--glass-backdrop-luma, 0.5) * 40%`
+           whose `, 0.5` fallback is DEAD (a registered `@property` initial 0 —
+           property-regs.css — is never guaranteed-invalid, so the fallback CANNOT
+           fire on a target engine, and the unwired resolve was `calc(0 * 40%) = 0%`:
+           the scrim the canon calls FORBIDDEN-to-omit painted NOTHING). Now: an
+           UNWIRED clear plate paints `--glass-clear-scrim-floor` (12% — the mandatory
+           minimum a scrim-less clear surface can never drop below); a wired observer
+           adds the luma-driven ramp on top (`--glass-clear-scrim-ramp` 28% — floor +
+           ramp caps at the prior 40% ceiling over a bright grid, luma→1). Bare
+           `var(--glass-backdrop-luma)` reads the registered initial 0 unwired (floor
+           alone), lifts CONTINUOUSLY as the observer writes. */
+        --glass-clear-scrim-floor: 12%;
+        --glass-clear-scrim-ramp: 28%;
         --glass-clear-scrim-strength: calc(
-            var(--glass-backdrop-luma, 0.5) * 40%
+            var(--glass-clear-scrim-floor) +
+            var(--glass-backdrop-luma) * var(--glass-clear-scrim-ramp)
         );
         background:
             color-mix(