@mkbabb/glass-ui 3.12.0 → 4.0.0

package/src/styles/glass/ladder.css

@@ -0,0 +1,383 @@
+/* glass/ladder.css
+   The five-tier .glass-{wash,quiet,resting,floating,overlay} surface ladder + the W55 adaptive-legibility @container style(--glass-backdrop: light) bucket (co-located with its rung) + the .glass-opaque escape + the content-aware under-shadow.
+   Carved from the glass.css cascade root; @import-ed by glass.css in cascade
+   order, each in its own @layer components (isomorphic to the monolith).
+   See docs/precepts/design-idioms.md §cohesion-aware partials. */
+@layer components {
+    /* ── Five-tier surface ladder (v0.8.0; visual only, no geometry) ──
+       Tier semantics, alpha-monotonic per R3-spec §A:
+         wash      ~0.30α  + light blur      (was `subtle`)
+         quiet     ~0.50α  + medium blur     (the missing rung)
+         resting   ~0.65α  + canonical blur  (was `default`; the speedtest plate)
+         floating  ~0.80α  + heavier blur    (was `elevated`)
+         overlay   ~0.95α  + heaviest blur   (NEW; modal-over-modal) */
+
+    /* The five-rung surface ladder declares the unprefixed
+       `backdrop-filter` only IN SOURCE. Authoring both forms manually here
+       caused Lightning CSS in Tailwind v4 to dedup-and-keep-prefixed,
+       which modern Chromium then dropped from the CSSOM (the prefixed
+       alias is parser-rejected post-Chrome 113). AY.W-A11Y-PERF O-2a — the
+       build now OWNS the prefix: `vite.style-assets.ts publishStyleAssets()`
+       injects the `-webkit-backdrop-filter:` pair into the SHIPPED
+       `dist/styles/*.css` as a LAST pass (the source stays unprefixed, so
+       the Lightning dedup never sees both forms; the build emits the pair
+       after the cascade is assembled). This GUARANTEES the prefix reaches
+       dist/ regardless of the consumer's autoprefixer/browserslist — a
+       Safari ≤17 engine (webkit-form-only) paints the blur instead of
+       silently dropping the unprefixed rule. Verified by
+       `proof:webkit-backdrop` (count-parity over the shipped dist). */
+    /* AW.W23 — every rung's background composes the adaptive-tint recipe
+       (`color-mix(in oklab, <rung bg>, var(--glass-tint-source) var(--glass-tint-
+       strength))`). With the default `--glass-tint-strength: 0%` the mix is a
+       no-op = byte-identical to the un-tinted rung; a consumer biases the surface
+       toward a sampled backdrop hue by setting `--glass-tint-source` + a
+       strength ≤30%. oklab is the mwg-preferred tint space (NEVER an
+       `oklch(from …)` lightness-shift — browsers don't gamut-map yet). */
+    .glass-wash {
+        position: relative;
+        background: color-mix(in oklab, var(--glass-bg-wash), var(--glass-tint-source) var(--glass-tint-strength));
+        backdrop-filter: var(--glass-blur-wash);
+        border: 1px solid var(--glass-border-wash);
+        box-shadow: var(--glass-material-rim), var(--glass-shadow-wash);
+    }
+
+    /* AL-W10 SLIM under-shadow wiring (tokens.css §AL-W10 SLIM —
+       UNDER-SHADOW recipe rungs). Each tier composes its canonical
+       iOS Liquid Glass under-shadow (a 0.5px dark hairline along the
+       bottom edge reading as glass thickness) as a NON-INSET layer
+       PREPENDED to the existing `--glass-shadow-*` recipe — the under-
+       shadow lays the floor; the existing shadow stack lays the lift.
+         quiet   → `--glass-under-shadow-quiet`   (0 2px 8px -1px α0.04)
+         resting → `--glass-under-shadow-default` (0 4px 16px -2px α0.08)
+         floating→ `--glass-under-shadow-vivid`   (0 8px 32px -4px α0.12)
+       `.glass-wash` is sub-perceptual; `.glass-overlay` is modal-heavy
+       — neither composes an under-shadow rung (Y4/Y6/Y7 SLIM retention).
+       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));
+        backdrop-filter: var(--glass-blur-quiet);
+        border: 1px solid var(--glass-border-quiet);
+        box-shadow:
+            var(--glass-material-rim),
+            var(--glass-under-shadow-quiet),
+            var(--glass-shadow-quiet);
+    }
+
+    .glass-resting {
+        position: relative;
+        background: color-mix(in oklab, var(--glass-bg-resting), var(--glass-tint-source) var(--glass-tint-strength));
+        backdrop-filter: var(--glass-blur-resting);
+        border: 1px solid var(--glass-border-resting);
+        box-shadow:
+            var(--glass-material-rim),
+            var(--glass-under-shadow-default),
+            var(--glass-shadow-resting);
+    }
+
+    /* AV.W15 M3 / AW.W22 — the floating tier carries the full-perimeter rim (the
+       catch-light that "defines the silhouette", WWDC25 sess. 219). The rim now
+       comes from the unified `--glass-material-rim` (= `--glass-edge-light`) so
+       it shares ONE source with the rest of the ladder; it rides INSIDE the
+       box-shadow stack so it composes with the under-shadow floor + the lift. */
+    .glass-floating {
+        /* AY.W-A11Y-PERF O-1 — engage the W55 bright-backdrop bucket BY DEFAULT on
+           the overlay band: a floating surface floats over WHATEVER the consumer
+           painted (frequently a light/near-white app surface — the canonical G2
+           case), so the library opts its own overlay-band glass in at its own root
+           via the SELF-CONTAINER reach below (`.glass-floating { --glass-backdrop }`
+           + `:where(.glass-floating) > * `-less: the rung re-points its OWN tint
+           through the companion self-rule, not only the ancestor @container). `dark`
+           (the :root default at tokens.css) stays the explicit per-surface override a
+           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));
+        backdrop-filter: var(--glass-blur-floating);
+        border: 1px solid var(--glass-border-floating);
+        box-shadow:
+            var(--glass-material-rim),
+            var(--glass-under-shadow-vivid),
+            var(--glass-shadow-floating);
+    }
+
+    .glass-overlay {
+        /* AY.W-A11Y-PERF O-1 — the overlay band engages the W55 bucket by default
+           (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));
+        backdrop-filter: var(--glass-blur-overlay);
+        border: 1px solid var(--glass-border-overlay);
+        box-shadow: var(--glass-material-rim), var(--glass-shadow-overlay);
+    }
+
+    /* ── Adaptive legibility: the bright-backdrop bucket (AX.W55 — the iOS-26/27
+       "locally darken the glass over light content" move; G2) ──────────────────
+       When a consumer sets `--glass-backdrop: light` on any ancestor (a near-white
+       card surface, a pale aurora bleed, a bright data grid), the `@container
+       style()` read engages here and LIFTS the tint toward ink: `--glass-tint-
+       strength` climbs from the `0%` rest default to the bounded AA floor
+       (`--glass-tint-strength-aa`, ≤24% — translucent floor preserved) and `--glass-
+       tint-source` re-points from `var(--card)` to the warm-ink `--glass-tint-ink`.
+       Both are INHERITING custom properties the rungs' `background:` composite
+       already reads, so re-pointing them on the material group re-resolves the
+       EXISTING `color-mix(in oklab, <rung bg>, …)` toward ink — ZERO new compositing
+       seam, the literal darken-over-light recipe. The `.glass-*::before` specular
+       `plus-lighter` gleam (W52) is untouched (it composes ON the darkened plate;
+       the darkening is the orthogonal oklab-tint axis). No `@supports` wrapper:
+       style queries introduce no new `container-type` value (every element is a
+       style container by default), so an engine without style-query support parses
+       the unknown at-rule as invalid, drops the block, and keeps the zero-delta
+       glass (the graceful degradation — the surface is today's-glass, the pre-W55
+       state; see utilities.css §density for the same precedent). */
+    @container style(--glass-backdrop: light) {
+        .glass-material,
+        .glass-wash,
+        .glass-quiet,
+        .glass-resting,
+        .glass-floating,
+        .glass-overlay,
+        .glass-card {
+            --glass-tint-source: var(--glass-tint-ink);
+            --glass-tint-strength: var(--glass-tint-strength-aa);
+            /* BA.W-DARK-MATERIAL scope 7 — the --muted-foreground lift moves HERE, into the
+               declared/sampled BRIGHT condition. The muted L40 tier cannot clear 4.5:1 on a
+               translucent FULL-AA-darkened plate (darkening moves the plate toward muted's
+               own luminance), so it lifts to the full ink ONLY where the plate actually
+               darkens — NOT on the calm-light unconditional floor (where it stays the muted
+               register, the slides caption read). */
+            --muted-foreground: var(--foreground);
+        }
+    }
+
+    /* AY.W-A11Y-PERF O-1 — SELF-ENGAGE the overlay band by default. The
+       `@container style()` rule above queries an ANCESTOR (CSS style queries never
+       self-match — verified on Chrome 148), so the `.glass-floating { --glass-backdrop:
+       light }` default we set on the rung would NOT darken the rung's OWN surface, only
+       its descendants. AND the `:root` library default is `--glass-backdrop: dark`
+       (tokens.css), so a `@container style(--glass-backdrop: dark)` revert would ALWAYS
+       fire (every element has the dark :root as an ancestor) — it cannot distinguish an
+       explicit consumer `dark` from the default. So the overlay band self-engages
+       UNCONDITIONALLY as the library default: a floating/overlay surface floats over
+       WHATEVER the consumer painted (frequently a light/near-white app surface — the
+       canonical G2 case the user reported), so darkening the translucent plate toward
+       the warm-ink is the correct default. This re-points the tint tokens DIRECTLY on
+       the overlay-band surfaces (`.glass-floating` / `.glass-overlay` — the Dialog/
+       Sheet/Popover/DropdownMenu/HoverCard/Command/Tooltip/Toast/Select-content band),
+       engaging the SAME oklab tint axis (zero new compositing seam). Over a DARK page
+       the darken is sub-perceptual (warm-ink over an already-dark plate is a small
+       shift); a dark-substrate consumer who wants the pristine plate sets
+       `--glass-tint-strength: 0%` on the band or uses `.glass-opaque`. The in-srgb
+       `--surface-tint-*` family is never touched (this edits only the in-oklab glass
+       tint axis).
+
+       AZ.W-ADAPTIVE-AUTO Arm 1 — the self-engage now EXTENDS to the plain CONTENT
+       tiers (`.glass-card`/`.glass-resting`/`.glass-quiet`/`.glass-wash`), not just
+       the overlay band. The W54 glass-first MAXIMAL default makes content-on-glass-
+       over-a-bright-backdrop the common case, so every content tier self-darkens over
+       light WITHOUT consumer opt-in — closing the C5-7 asymmetry (the content tiers
+       painted near-invisible over light on every route). The prior W55 overlay-only
+       scoping (which kept the default-path byte-identity canary green by testing
+       `.glass-card`/`.glass-resting` with a bare no-ancestor div) is SUPERSEDED: the
+       three now-self-engaged kinds are no longer byte-identical to the dark bucket
+       (the canary narrows to the legitimately-zero-delta surfaces — the `.glass-opaque`
+       escape + an explicit per-surface `--glass-backdrop: dark` override — and the new
+       in-situ G1 π readback becomes the binding default-path truth). 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), so the low-contrast muted register resolves to
+       the legible dark ink (clears ~10:1) — a token re-point on the same inheriting
+       axis as the tint. */
+    /* The OVERLAY band (.glass-floating/.glass-overlay — Dialog/Sheet/Popover/DropdownMenu/
+       HoverCard/Command/Tooltip/Toast/Select-content) keeps the FULL unconditional AA darken
+       + the muted lift: it floats over WHATEVER the consumer painted (frequently a light/
+       near-white app surface — the canonical G2 case), so darkening toward the warm-ink is
+       the correct DEFAULT over an UNKNOWN surface. Over a DARK page this becomes the
+       luminous-dark LIFT (the dark-arm re-tunes --glass-tint-strength-aa to 12% — the plate
+       lifts off the deep page). A dark-substrate consumer who wants the pristine plate sets
+       `--glass-tint-strength: 0%`. */
+    :where(.glass-floating, .glass-overlay) {
+        --glass-tint-source: var(--glass-tint-ink);
+        --glass-tint-strength: var(--glass-tint-strength-aa);
+        --muted-foreground: var(--foreground);
+    }
+
+    /* BA.W-DARK-MATERIAL scope 7 — the plain CONTENT tiers self-engage the SUB-PERCEPTUAL
+       FLOOR unconditionally, NOT the full AA darken (the R9-1 slides gray-slab fix). Over a
+       calm LIGHT page the floor (--glass-tint-strength-floor: 4%) is a silhouette whisper —
+       the translucent cream card stays warm (L ≈ 0.94), no gray slab. Over a DARK page the
+       floor re-resolves to the luminous-dark lift (12% in the dark arm — the plate lifts off
+       the deep page, the desired register). The FULL AA darken engages on these tiers ONLY
+       under the declared/sampled BRIGHT signal (the @container --glass-backdrop:light bucket
+       above — where the muted lift also lives now). NO unconditional --muted-foreground lift
+       here: on the calm-light floor the caption keeps the muted register (the slides read).
+       A consumer opts a light-page card out via `--glass-tint-strength: 0%` on an ancestor. */
+    :where(.glass-card, .glass-resting, .glass-quiet, .glass-wash) {
+        --glass-tint-source: var(--glass-tint-ink);
+        --glass-tint-strength: var(--glass-tint-strength-floor);
+    }
+
+    /* 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
+       darkens the translucent plate so dark text clears ~11:1 over white at the 18%
+       floor — the live π readback ratifies). On a supporting engine `contrast-color()`
+       REFINES the foreground-ink pick natively, anchored on the LIGHT BACKDROP signal
+       (`--card`, the warm-white surface base the bright bucket implies) — NOT on the
+       ink. `contrast-color(var(--card))` over the light backdrop resolves to the
+       maximally-legible DARK ink (anchoring on the dark ink instead would invert to
+       white, illegible on the still-light translucent plate). The bucket is the floor;
+       this is the native refinement. Scoped to the bright bucket. */
+    @supports (color: contrast-color(white)) {
+        /* The bright-bucket ink flip — the content tiers + overlay band over a DECLARED/
+           sampled bright backdrop. BA.W-DARK-MATERIAL scope 6 — the SYSTEMIC contrast-color()
+           selection-inversion fix (approach A, lockstep-lift). At HEAD this block lifted only
+           --muted-foreground (and the surface `color`) to contrast-color(--card) (white over
+           a light plate, L100), but the ACTIVE control register (a SegmentedTabs active tab,
+           the curve-picker selected label) reads var(--foreground) DIRECTLY (L90, un-lifted) —
+           a control sets its OWN `color: var(--foreground)` which wins over the inherited
+           surface `color`, so the inactive (muted→white) read BRIGHTER than the active
+           (--foreground), inverting selection. The fix lifts --foreground ITSELF in lockstep
+           with --muted-foreground: now an active register reading --foreground resolves the
+           SAME anchored contrast-color ink as the lifted inactive, so selected ≥ unselected
+           everywhere (the inversion gone for ANY --muted-foreground/--foreground selection
+           pairing inside a glass card — the SYSTEMIC library-seam fix, not a curve-picker
+           one-off). Progressive enhancement only — the declarative darken is the AA floor. */
+        @container style(--glass-backdrop: light) {
+            .glass-material,
+            .glass-wash,
+            .glass-quiet,
+            .glass-resting,
+            .glass-floating,
+            .glass-overlay,
+            .glass-card {
+                color: contrast-color(var(--card));
+                --foreground: contrast-color(var(--card));
+                --muted-foreground: contrast-color(var(--card));
+            }
+        }
+        /* The OVERLAY band self-engages the darken UNCONDITIONALLY (it floats over an
+           UNKNOWN consumer surface), so its ink-flip companion mirrors that — UNCONDITIONAL.
+           --foreground lifts in lockstep with --muted-foreground (the scope-6 lockstep). */
+        :where(.glass-floating, .glass-overlay) {
+            color: contrast-color(var(--card));
+            --foreground: contrast-color(var(--card));
+            --muted-foreground: contrast-color(var(--card));
+        }
+        /* BA.W-DARK-MATERIAL scope 7 — the content-tier ink flip is GATED on the bright
+           signal (it moved INTO the @container bucket above), NOT unconditional. Over a calm
+           LIGHT page the content tiers only carry the 4% silhouette floor (still a warm cream
+           plate), so flipping the ink to the contrast-color DARK ink there is correct only
+           where the plate ACTUALLY darkens to the bright-bucket AA — the unconditional flip
+           would force a white-on-cream / dark-on-darkened mismatch on the calm card. The
+           content tiers therefore take NO unconditional contrast-color flip; their flip lives
+           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 */
+    .glass-wash::after,
+    .glass-quiet::after,
+    .glass-resting::after,
+    .glass-floating::after,
+    .glass-overlay::after {
+        content: '';
+        position: absolute;
+        inset: 0;
+        border-radius: inherit;
+        background: var(--paper-clean-texture);
+        background-repeat: repeat;
+        background-size: var(--paper-texture-size);
+        opacity: var(--glass-grain-opacity);
+        pointer-events: none;
+        mix-blend-mode: overlay;
+    }
+
+    /* (b) The unified rim — `--glass-edge-light` full-perimeter inset ring on
+       EVERY material surface (AW.W22). Previously the rim was wired only into
+       the floating/overlay tiers' box-shadow stack; promoting it to the material
+       group makes wash/quiet/resting/card/dock-control all carry the same
+       silhouette catch-light from ONE token. The rim is its OWN `box-shadow`
+       declaration on the material group so it composes uniformly without
+       perturbing each tier's elevation recipe (the floating/overlay tiers drop
+       their now-redundant inline `--glass-edge-light` layer below). The alpha is
+       deliberately low so the rim never eats AA legibility over a busy
+       backdrop. */
+    .glass-material,
+    .glass-wash,
+    .glass-quiet,
+    .glass-resting,
+    .glass-floating,
+    .glass-overlay,
+    .glass-card,
+    .glass-specular-track,
+    .dock-icon-button {
+        --glass-material-rim: var(--glass-edge-light);
+    }
+
+    .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/material.css

@@ -0,0 +1,238 @@
+/* glass/material.css
+   The unified .glass-material atom (AW.W22) + the shared ::before grain/specular wiring across the glass family — ONE source for the three material atoms.
+   Carved from the glass.css cascade root; @import-ed by glass.css in cascade
+   order, each in its own @layer components (isomorphic to the monolith).
+   See docs/precepts/design-idioms.md §cohesion-aware partials. */
+@layer components {
+    /* ── The unified glass material (AW.W22) ──────────────────────────────
+       ONE source for the three material atoms that AV.W15 scattered onto
+       opt-in classes + single tiers:
+         (a) the moving-specular `::before` catch-light (folded here from
+             glass-specular-track.css — that file now keeps only the thin
+             `.glass-specular-track` ALIAS + the brackets that point HERE),
+         (b) the `--glass-edge-light` full-perimeter rim (moved off the
+             floating-only block so EVERY rung carries it),
+         (c) the pointer interaction-light hooks (the `--specular-*`
+             `@property` channel mapped from the consumer's --mouse-x/--mouse-y
+             write).
+       The five ladder rungs + `.glass-card` + the `.dock-icon-button` CONTROL
+       compose `.glass-material`, so a Switch thumb, a glass Button, a Dialog,
+       and a Sheet all read as the SAME material without per-component wiring.
+
+       The `.glass-dock` SHELL is OUT of this group BY DESIGN — it hand-rolls a
+       parallel surface (its own `--glass-*-dock` family + a local rim) the dock arm
+       owns. The COHESION CONSEQUENCE is DELIBERATE: the dock shell carries NO shared
+       edge-gleam / moving-specular `::before` (AZ.W-DOCK-TAXONOMY retired the
+       `instrument-strip` engraved-bezel `::before` — the dock shell now has none).
+       The dock's catch-light lives on
+       its CONTROLS (`.dock-icon-button` et al., listed below + in the opt-in
+       transition block), which ARE in the material group — NOT on the shell plate.
+       Adding a shell gleam would re-introduce glass-on-glass over the controls, so
+       the shell-without-gleam is a NAMED EXEMPTION, gated as `dock-shell-exempt` in
+       proof:glass-cohesion (the only exemption beside the legibility allowlist).
+
+       The selector GROUP is the single source. Adding a surface to the band
+       material is one comma-entry here, not a new opt-in class string. */
+    .glass-material,
+    .glass-wash,
+    .glass-quiet,
+    .glass-resting,
+    .glass-floating,
+    .glass-overlay,
+    .glass-card,
+    .glass-specular-track,
+    .dock-icon-button,
+    .dock-tab-button,
+    .dock-select-trigger,
+    .dock-dropdown-trigger {
+        position: relative;
+    }
+
+    /* (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
+       dedicated `::after` inset ring so it composes alongside (not inside) each
+       tier's own shadow recipe. The `::after` grain overlay already claims the
+       five rungs' `::after`; the rim is folded INTO that same overlay's
+       box-shadow below (the grain `::after` gets the rim inset ring) so no
+       pseudo-element collides. */
+
+    /* (a)+(c) The moving-specular `::before` catch-light — the iOS-26
+       illuminate-from-within behaviour. A masked radial-gradient glow rides the
+       surface at the pointer position (--mouse-x/--mouse-y → the typed
+       --specular-* channel). Folded VERBATIM from glass-specular-track.css so
+       there is exactly ONE specular source. */
+    .glass-material::before,
+    .glass-wash::before,
+    .glass-quiet::before,
+    .glass-resting::before,
+    .glass-floating::before,
+    .glass-overlay::before,
+    .glass-card::before,
+    .glass-specular-track::before,
+    .dock-icon-button::before,
+    .dock-tab-button::before,
+    .dock-select-trigger::before,
+    .dock-dropdown-trigger::before {
+        content: "";
+        position: absolute;
+        inset: 0;
+        border-radius: inherit;
+        pointer-events: none;
+        z-index: 1;
+        /* Map the consumer's pointer write onto the typed properties, ON THE
+           PSEUDO. The `--mouse-x/--mouse-y` write lands on the HOST (inline
+           style) as UNREGISTERED props that inherit down to this `::before`;
+           the registered `--specular-*` props are `inherits: false`, so the
+           mapping is declared HERE where the pseudo owns its typed value. The
+           `var(--mouse-x, 50%)` floor is the centred fallback. */
+        --specular-x: var(--mouse-x, 50%);
+        --specular-y: var(--mouse-y, 50%);
+        /* The catch-light intensity at REST — reads the token cohort
+           (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);
+        /* 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
+           plate) whose falloff reaches `/0` well INSIDE the plate (70%) — a tracked
+           catch-light reading the surface near the lit edge, NEVER a whole-surface
+           wash. The core is genuinely WARM-CREAM (L < 100% so the warm hue survives;
+           the prior `hsl(40 30% 100%)` blew out to white). The `--specular-intensity`
+           multiplier drives the layer `opacity`, NOT a per-stop alpha (a
+           registered-`@property` var() nested in an hsl() alpha computes to 0 in
+           Chromium — the cross-engine-safe path); the per-stop alphas are literals so
+           even the lifted hover/active states read as a lens, not a flash. */
+        background: radial-gradient(
+            circle var(--glass-specular-size, 36%) at var(--specular-x, 50%) var(--specular-y, 50%),
+            hsl(40 35% 92% / 0.5) 0%,
+            hsl(40 35% 92% / 0) 70%,
+            transparent 100%
+        );
+        opacity: var(--specular-intensity, 0);
+        /* Clip the gleam to ITS OWN radius (not the whole plate) so it stays a
+           bounded glint. `mask-image` Baseline 2023-12-07; a non-supporting engine
+           ignores it and the `inset: 0` + radius-inherit + the in-paint falloff
+           already bound the gleam to the surface. */
+        mask-image: radial-gradient(
+            circle var(--glass-specular-size, 36%) at var(--specular-x, 50%) var(--specular-y, 50%),
+            black 0%,
+            black 60%,
+            transparent 100%
+        );
+        /* AX.W52 D19 — `plus-lighter` (additive but HDR-clamped, Safari 16.4+) over
+           the prior `screen` (a non-linear lightener that lifted the whole tile
+           toward white — the muddy-card defect). A non-supporting engine degrades to
+           a plain low-alpha warm overlay (the gleam composes normally — no blend, no
+           blowout), the no-workaround floor; NOT a `screen` fallback. */
+        mix-blend-mode: plus-lighter;
+        /* The moving-specular TRANSITION is NOT declared here. An idle/unwired
+           `::before` is STATIC (no interpolation track), so a bare glass rung / an
+           un-armed Card / a glass Button at rest attaches ZERO animation tracks (the
+           keyframes.js runtime counts 0 idle tracks, not 19). The transition rides
+           ONLY the WIRED + interactive surfaces — the opt-in scoped block below. */
+    }
+
+    /* AY.W-GLASS — the moving-specular transition is OPT-IN (the Card wire-or-omit
+       pattern, generalized). It attaches ONLY to a WIRED surface
+       (`.glass-specular-track` — Card emits it conditionally, the dock controls + the
+       Slider thumb compose it) OR to any glass surface under `:hover`/`:active` (the
+       pointer is present, so the interpolation is legitimately live). An idle/unwired
+       `.glass-floating` / `.glass-wash` / bare-rung `::before` carries NO transition
+       and thus NO keyframes.js track. The §6 register is PRESERVED (still
+       `--ease-standard` on the position-tracked + surface-opacity legs — H-motion §6
+       "position-tracked → --ease-standard"; only the SELECTOR scope changes). The dock
+       controls keep the always-on transition (they are interactive controls; their rest
+       intensity is 0 so they paint nothing at rest, but a control legitimately carries
+       the transition). */
+    .glass-specular-track::before,
+    .glass-material:hover::before,    .glass-material:active::before,
+    .glass-wash:hover::before,        .glass-wash:active::before,
+    .glass-quiet:hover::before,       .glass-quiet:active::before,
+    .glass-resting:hover::before,     .glass-resting:active::before,
+    .glass-floating:hover::before,    .glass-floating:active::before,
+    .glass-overlay:hover::before,     .glass-overlay:active::before,
+    .glass-card:hover::before,        .glass-card:active::before,
+    .dock-icon-button::before,
+    .dock-tab-button::before,
+    .dock-select-trigger::before,
+    .dock-dropdown-trigger::before {
+        /* Smooth the position + intensity between pointer samples (the typed
+           @property regs make the percentage stops interpolable). */
+        transition:
+            --specular-x var(--duration-fast, 150ms) var(--ease-standard, ease-out),
+            --specular-y var(--duration-fast, 150ms) var(--ease-standard, ease-out),
+            opacity var(--duration-normal, 240ms) var(--ease-standard, ease-out);
+    }
+
+    .dark .glass-material::before,
+    .dark .glass-wash::before,
+    .dark .glass-quiet::before,
+    .dark .glass-resting::before,
+    .dark .glass-floating::before,
+    .dark .glass-overlay::before,
+    .dark .glass-card::before,
+    .dark .glass-specular-track::before,
+    .dark .dock-icon-button::before,
+    .dark .dock-tab-button::before,
+    .dark .dock-select-trigger::before,
+    .dark .dock-dropdown-trigger::before {
+        /* Softer over the deep canvas — `plus-lighter` still lifts on dark, so the
+           `.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);
+    }
+
+    /* (c) Interaction-light lockstep — hover/active lift the intensity in the
+       SAME rungs the scale-press squish keys off, so material-light fires in
+       lockstep with the press across every glass surface. Settles back on leave
+       via the opacity transition above. */
+    .glass-material:hover::before,
+    .glass-wash:hover::before,
+    .glass-quiet:hover::before,
+    .glass-resting:hover::before,
+    .glass-floating:hover::before,
+    .glass-overlay:hover::before,
+    .glass-card:hover::before,
+    .glass-specular-track:hover::before,
+    .dock-icon-button:hover::before,
+    .dock-tab-button:hover::before,
+    .dock-select-trigger:hover::before,
+    .dock-dropdown-trigger:hover::before {
+        --specular-intensity: var(--glass-specular-intensity-hover, 0.1);
+    }
+    .glass-material:active::before,
+    .glass-wash:active::before,
+    .glass-quiet:active::before,
+    .glass-resting:active::before,
+    .glass-floating:active::before,
+    .glass-overlay:active::before,
+    .glass-card:active::before,
+    .glass-specular-track:active::before,
+    .dock-icon-button:active::before,
+    .dock-tab-button:active::before,
+    .dock-select-trigger:active::before,
+    .dock-dropdown-trigger:active::before {
+        --specular-intensity: var(--glass-specular-intensity-active, 0.16);
+    }
+
+    /* AX.W45-TUNE C5 — the SELECTED dock control reads as the keyframes-dock glass
+       register: a glass-tier active fill (`--dock-control-active-bg` → the floating
+       plate, tokens.css) WITH the specular gleam waking over it, not a flat ink
+       stamp. The CSS `:active` pseudo above only fires on press-down; a SELECTED tile
+       (`.is-active` / `[aria-pressed]` / `[aria-expanded]` / `[aria-current]`) holds
+       the gleam lit so the selected element reads as a lit glass tier the substrate
+       shows through (the model the user named, `pass-3:13`). Family-scoped addition
+       on the dock-control `::before`, line-disjoint from the shared recipe above. */
+    .dock-icon-button:is(.is-active, .active, [aria-pressed="true"], [aria-expanded="true"], [aria-current="page"])::before,
+    .dock-tab-button:is(.is-active, .active, [aria-pressed="true"], [aria-expanded="true"], [aria-current="page"])::before,
+    .dock-select-trigger:is(.is-active, .active, [aria-pressed="true"], [aria-expanded="true"], [aria-current="page"])::before,
+    .dock-dropdown-trigger:is(.is-active, .active, [aria-pressed="true"], [aria-expanded="true"], [aria-current="page"])::before {
+        --specular-intensity: var(--glass-specular-intensity-active, 0.16);
+    }
+
+}