@mkbabb/glass-ui 4.0.0 → 4.1.0

package/src/styles/glass/control-surfaces.css

@@ -0,0 +1,167 @@
+/* glass/control-surfaces.css
+   The form-control REST register carved from glass/surfaces.css — the
+   `.input-pill` family (Input/Textarea/NumberField), the shared `.control-surface`
+   class (Select default + TagsInput), the validity vocabulary, and the Select
+   trigger resting-border lift. A cohesive sub-concern of surfaces.css (the
+   no-god-module re-drain), @import-ed by glass.css in cascade order IMMEDIATELY
+   AFTER surfaces.css and BEFORE surface-axis.css — same `@layer components`, same
+   source order, so the carve is byte-isomorphic.
+   See docs/precepts/design-idioms.md §cohesion-aware partials. */
+@layer components {
+    /* ── Pill input ───────────────────────────────── */
+    .input-pill {
+        @apply flex w-full;
+
+        /* AX.W51 D18 — the input pill rides the ONE `--ui-scale` comfort axis: the
+           height reads the `--control-h-md` cohort (`max(calc(2.5rem * --ui-scale),
+           --control-floor)`, the h-10 register with the WCAG-44px coarse clamp), the
+           font reads `--control-text`, the inline padding scales — so ONE override
+           grows the field's height + padding + font in lockstep. Desktop default is
+           the identity. */
+        /* BC.W-CONTROL-CUSTOM — the height reads the `--control-pill-h` element-
+           override seam, DEFAULTING to the cohort `--control-h-md` so a bare
+           control is byte-identical to HEAD. The shared `controlSizeClass(size)`
+           (_shared/useControlSize.ts) re-points the seam per rung
+           (sm→`--control-h-sm`, lg→`--control-h-lg`), so the `size` prop retunes
+           the field height WITHOUT a recipe fork — ONE substitution rung, the
+           cohort is still the source. */
+        height: var(--control-pill-h, var(--control-h-md));
+        border-radius: var(--radius-pill);
+        /* AW.W13 — the resting field edge reads as an enclosed control at rest
+           (~15%α — ~2× the prior 8% glass-wash floor that vanished on cream). The
+           `:focus-visible` accent ring + the `:user-invalid`/`[aria-invalid]`
+           destructive ring below still win by order + specificity.
+           AX.W54 — moved off the srgb `--surface-tint-15` fork onto the glass
+           border seam so the pill is ONE glass model with the rest of the ladder.
+           BA.W-SURFACE-AXIS scope 7 — re-pointed onto the SHARED `--control-surface-*`
+           REST register so Input/Textarea/NumberField/Select/Combobox/TagsInput are
+           ONE material at rest (the input rung was the warmer of the two; Select rode
+           the `glass-wash` gray — the no-gray control-family seam). The register reads
+           the same `--glass-*` ladder, so `--glass-level`/the W55 bright bucket retune
+           the whole form family in lockstep (--control-surface-border defaults to the
+           `--glass-border-floating` 15%α rung, --control-surface-bg to `--glass-bg-quiet`,
+           --control-surface-blur to `--glass-blur-quiet`). */
+        border: 1.5px solid var(--control-surface-border);
+        background: var(--control-surface-bg);
+        /* The control's REAL glass blur — the shared register's quiet-tier radius
+           (the same `--control-surface-blur` pairs with `--control-surface-bg`); the
+           `--glass-level` knob clarifies it in lockstep with every surface. */
+        backdrop-filter: var(--control-surface-blur);
+        padding: 0 calc(1rem * var(--ui-scale));
+        /* BC.W-CONTROL-CUSTOM — the font reads the `--control-pill-text` seam,
+           DEFAULTING to `--control-text` (byte-identical at unset). The `sm` rung
+           re-points it to `--control-text-sm` (the quieter register); `default`/`lg`
+           keep `--control-text`. This is the C1 close — the input register reads
+           `--control-text` via the recipe, NOT a bare `text-sm` literal. */
+        font-size: var(--control-pill-text, var(--control-text));
+        color: var(--foreground);
+        transition:
+            background-color var(--duration-fast) var(--ease-standard),
+            border-color var(--duration-fast) var(--ease-standard),
+            box-shadow var(--duration-fast) var(--ease-standard),
+            color var(--duration-fast) var(--ease-standard),
+            opacity var(--duration-fast) var(--ease-standard);
+    }
+
+    .input-pill::placeholder {
+        color: var(--surface-tint-35);
+    }
+
+    /* BA.W-SURFACE-AXIS scope 7 — the shared control REST surface class. The
+       NON-pill control families (the Select trigger, the TagsInput root) that do
+       NOT compose `.input-pill` but want the SAME resting material read this — so
+       the whole form band is ONE register at rest (the Select default rode the
+       lighter `glass-wash` gray before; this is the no-gray control-family seam).
+       It carries the bg/border/blur ONLY (each control owns its own height/radius/
+       padding/font), so a non-pill control composes `.control-surface` + its own
+       geometry. The hover lift brightens the fill one step toward the resting rung. */
+    .control-surface {
+        background: var(--control-surface-bg);
+        border: 1px solid var(--control-surface-border);
+        backdrop-filter: var(--control-surface-blur);
+        -webkit-backdrop-filter: var(--control-surface-blur);
+    }
+    .control-surface:hover:not(:disabled, [data-disabled]) {
+        background: var(--control-surface-bg-hover);
+    }
+
+    /* AQ.W4 §W4.6 — keyboard-focus ring only. Was bare `:focus` (showed the
+       accent ring on a mouse click); `:focus-visible` matches the
+       `.focus-ring` / `.glass-btn` / dock-control discipline. Ordered BEFORE
+       the `:user-invalid` rungs so an invalid focused field shows destructive,
+       not accent (the `:user-invalid:focus-visible` rule below wins by order +
+       specificity). `:focus-visible` Baseline Widely — no fallback. */
+    .input-pill:focus-visible {
+        outline: none;
+        border-color: var(--color-accent-opaque, var(--ring));
+        box-shadow: 0 0 0 2px var(--color-accent, color-mix(in srgb, var(--ring) 30%, transparent));
+    }
+
+    /* AQ.W4 §W4.1 — validity vocabulary on `.input-pill` (Input + Textarea).
+       The forgiving `:where(:user-invalid, .user-invalid-fallback,
+       [aria-invalid="true"])` group is ONE rule covering THREE trigger surfaces:
+       native constraint-validation (`:user-invalid`), the `useUserInvalidAria`
+       fallback class for engines without `:user-invalid` (css §3.2; NOT a
+       live+dead alias — the class is the SOLE fallback), AND (AW.W18) the
+       imperative `[aria-invalid="true"]` attribute. The `[aria-invalid]` arm
+       serves APP-DRIVEN validity — a custom key match, an async server check —
+       where there is no native constraint to trip `:user-invalid`, so the app
+       sets the ARIA attribute and the library's own ring paints with no
+       `:deep()` re-paint at the consumer. The destructive/success tints reuse
+       the semantic tokens via `color-mix` per the house pattern (W2). Non-color
+       reinforcement is the error TEXT (W4.5 `error` slot) + the `required`
+       asterisk — the border/bg shift is the supplementary cue, never the sole
+       one. `:user-valid` is intentionally subtle (border only, no bg fill) so
+       a long valid form is not a wall of green. */
+    .input-pill:where(:user-invalid, .user-invalid-fallback, [aria-invalid="true"]) {
+        border-color: var(--destructive);
+        background: color-mix(in srgb, var(--destructive) 8%, var(--glass-bg-quiet));
+    }
+    .input-pill:where(:user-valid, .user-valid-fallback) {
+        border-color: var(--success);
+    }
+    /* Invalid + keyboard-focused → destructive ring (overrides the accent
+       `:focus-visible` ring above by order + the extra invalid compound). The
+       `[aria-invalid]` arm rides the same widened group so an app-driven
+       invalid field shows the destructive ring on focus too. */
+    .input-pill:where(:user-invalid, .user-invalid-fallback, [aria-invalid="true"]):focus-visible {
+        border-color: var(--destructive);
+        /* BB.W-INVALID-RING — the shared destructive ring register (the
+           --focus-ring-shadow sibling). The byte-identical recipe is now ONE
+           token; the `8%` at-rest bg arm above stays `.input-pill`-local (a
+           glass-tint substrate the bare-ring surfaces do not carry). */
+        box-shadow: var(--invalid-ring);
+    }
+
+    /* AQ.W4 §W4.3 — `field-sizing: content` autosize (opt-in via the Textarea
+       `autosize` prop → `[data-autosize]`). The textarea grows vertically with
+       content between a 3-line floor and a token-driven ceiling, then scrolls.
+       `field-sizing` Baseline Newly (Chromium 2024) — on a non-supporting
+       engine the declaration is ignored and the element keeps the
+       `min/max-block-size` bounds + standard scroll (no JS, no `@supports`,
+       no grid-mirror polyfill). The fixed-size path (default, `min-h-20`) is
+       the unchanged no-op fallback. */
+    .input-pill[data-autosize] {
+        field-sizing: content;
+        width: 100%;
+        min-block-size: 3lh;
+        max-block-size: var(--textarea-autosize-max, 12lh);
+        resize: vertical;
+    }
+
+    .input-pill:disabled {
+        opacity: 0.5;
+        cursor: not-allowed;
+    }
+
+    /* AW.W13 — the Select trigger mirrors the input pill's resting border lift.
+       The reka-ui SelectTrigger renders `role="combobox"` over the `.glass-wash`
+       surface; its 8%α `--glass-border-wash` field edge vanished on cream just
+       like the input pill, so the same `--surface-tint-15` lift makes the
+       trigger read as an enclosed control at rest. Scoped to the combobox role
+       so the lift reaches ONLY the Select trigger, not every `.glass-wash`
+       surface. */
+    .glass-wash[role="combobox"] {
+        border-color: var(--surface-tint-15);
+    }
+}

package/src/styles/glass/deep.css

@@ -0,0 +1,44 @@
+/* glass/deep.css — BB.W-DEEP-GLASS — the OPT-IN `.glass-deep` decoration.
+ *
+ * The deep-glass register: the maximal iOS-27 Liquid-Glass tier ABOVE the
+ * W-GLASS-CAL calm default (the Apple `saturate(1.8) blur(20px)` family, landed
+ * at the budget-clearing 16px / saturate 1.5; tokens/glass-deep.css). `.glass-deep`
+ * is the OPT-IN surface — a consumer adds it to a glass surface that wants the
+ * thick refractive liquid read (the hero glass, the dock, the CTA); the bare
+ * content default is UNCHANGED (the calm default is the user's call).
+ *
+ * ── The token-substitution model (the `.glass-opaque` precedent) ───────────
+ * `.glass-deep` is a DECORATION ON a base `.glass-*` rung, NOT a parallel solid/
+ * blur recipe. It mirrors `.glass-opaque` (ladder.css §opaque-escape — which only
+ * sets `--glass-level: 0`, a token re-point, never a competing `backdrop-filter`):
+ * `.glass-deep` re-points the floating-rung blur token to the deep family
+ * (`--glass-blur-floating: var(--glass-blur-deep)`), so the base `.glass-floating`
+ * rule's `backdrop-filter: var(--glass-blur-floating)` resolves to the DEEP blur —
+ * NO cascade fight, NO base-rule edit, the glass edge/rim/under-shadow + the W55
+ * tint axis + the a11y brackets all compose unchanged. The deep tier rides a base
+ * rung exactly as `.glass-opaque` does (the CardTier map is `deep →
+ * 'glass-floating glass-deep'`).
+ *
+ * Because the deep blur (glass-deep.css) COMPOSES `var(--glass-level)`, the a11y
+ * brackets (`prefers-reduced-transparency: reduce` / `prefers-contrast: more` set
+ * `--glass-level: 0` / 0.3 at :root, a11y-fallback.css) reach the deep plate for
+ * FREE — the deep blur collapses to blur(0) under reduced-transparency through the
+ * SAME level path (the opaque escape). The W55 bright-bucket darken reaches the
+ * deep surface by construction too: `.glass-deep` is composed WITH `.glass-floating`,
+ * which is already in the W55 `@container style(--glass-backdrop: light)` material
+ * group (ladder.css) AND self-engages the overlay-band darken — the deep tier
+ * inherits the legibility tint with no selector-list edit.
+ *
+ * @import-ed in glass.css AFTER ladder.css/surfaces.css (the same @layer components,
+ * source-order-after so the token re-point lands beside the rung it rides) and
+ * BEFORE the a11y @media brackets (which still win by the :root level re-point).
+ */
+@layer components {
+    /* The deep decoration: re-point the floating rung's blur token to the deep
+       family. The base `.glass-floating` rule (`backdrop-filter:
+       var(--glass-blur-floating)`) then paints the deep `blur(16px) saturate(1.5)`
+       at `--glass-depth: 1` — the Apple-deep register, opt-in. */
+    .glass-deep {
+        --glass-blur-floating: var(--glass-blur-deep);
+    }
+}

package/src/styles/glass/ladder.css

@@ -31,13 +31,21 @@
        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). */
+       strength ≤30%. oklab is the mwg-preferred tint space for the TINT mix here
+       (NEVER an `oklch(from …)` lightness-shift in the GLASS-TINT mix). The
+       `oklch(from var(--foreground) …)` relative-color recipe DID land its first
+       live consumer at BB.W-DARK-INK-WARM — the dark `--surface-tint-*` arm
+       (`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. */
     .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);
+        /* BB.W-GLASS-ACCENT — the rung border ink feeds the accent-composed
+           `--glass-border-accent` (rim group above); byte-identical at 0%. */
+        --glass-border-rung: var(--glass-border-wash);
+        border: 1px solid var(--glass-border-accent);
         box-shadow: var(--glass-material-rim), var(--glass-shadow-wash);
     }
 
@@ -57,7 +65,8 @@
         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);
+        --glass-border-rung: var(--glass-border-quiet);
+        border: 1px solid var(--glass-border-accent);
         box-shadow:
             var(--glass-material-rim),
             var(--glass-under-shadow-quiet),
@@ -68,7 +77,8 @@
         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);
+        --glass-border-rung: var(--glass-border-resting);
+        border: 1px solid var(--glass-border-accent);
         box-shadow:
             var(--glass-material-rim),
             var(--glass-under-shadow-default),
@@ -94,7 +104,8 @@
         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);
+        --glass-border-rung: var(--glass-border-floating);
+        border: 1px solid var(--glass-border-accent);
         box-shadow:
             var(--glass-material-rim),
             var(--glass-under-shadow-vivid),
@@ -108,7 +119,8 @@
         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);
+        --glass-border-rung: var(--glass-border-overlay);
+        border: 1px solid var(--glass-border-accent);
         box-shadow: var(--glass-material-rim), var(--glass-shadow-overlay);
     }
 
@@ -199,8 +211,35 @@
        `--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);
+        /* BC.W-ADAPTIVE-RECONCILE (the fourier-analysis-M Tier-1 #1 fold, CONTINUOUS half)
+           — the OVERLAY band SPECIFICALLY JOINS the continuous observer driver, the SAME
+           clamp the content tiers get. The dropdown/Dialog/Popover/Select-content plate
+           FLOORS to warm-cream when the measured backdrop is calm/dark, and darkens
+           CONTINUOUSLY only under a measured bright backdrop — NOT the binary `@container`
+           bucket jump, NOT a blanket unconditional darken (the retired 4.0.x 20% slab).
+           The `BC.W-AUDIT` pre-fix already closed the UNCONDITIONAL-darken half (the band
+           floored by default); THIS is the continuous earned-darken half. The MEASURED AA
+           bar (the overlay plate clears 4.5:1 WHILE α < 0.86) is GLASS-LEGIBILITY-
+           MEASURED's roster addition — the driver here, the bar there, 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)))
+            ),
+            var(--glass-tint-strength-aa)
+        );
+        /* BC.W-DIALOG-GLASS — the overlay band's muted caption keeps the on-glass MUTED
+           register on a CALM modal (the SAME `--on-glass-muted` the content tiers read on
+           their calm path — legible-AND-subordinate against the composited glass fill),
+           NOT an UNCONDITIONAL lift to full `--foreground` that blackened the caption on a
+           cream modal over a light page. The bright-bucket lift (@container --glass-
+           backdrop:light below) moves `--muted-foreground` to the contrast ink in LOCKSTEP
+           with `--foreground` only where the plate ACTUALLY darkens to AA — so a busy-
+           backdrop modal goes full ink, a calm modal keeps the muted register. */
+        --muted-foreground: var(--on-glass-muted);
+        --muted-foreground-strong: var(--on-glass-muted-strong);
     }
 
     /* BA.W-DARK-MATERIAL scope 7 — the plain CONTENT tiers self-engage the SUB-PERCEPTUAL
@@ -212,10 +251,52 @@
        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. */
+       A consumer opts a light-page card out via `--glass-tint-strength: 0%` on an ancestor.
+
+       BB.W-ON-GLASS-FG (N13) — the THIRD-STATE on-glass FOREGROUND re-point lands HERE,
+       BESIDE the BA seam (the SAME cascade context, the SAME content-tier set, NOT a new
+       competing layer). The calm-light floor keeps the page-muted --neutral-5 at HEAD —
+       but the muted ink is calibrated against the CANVAS, and on a TRANSLUCENT content
+       plate (the glass-first common case) it composites toward the lifted backdrop and
+       its contrast COLLAPSES (1.15-3.29:1 measured in dark). The re-point targets the
+       muted register at the COMPOSITED glass fill: --muted-foreground → --on-glass-muted
+       (+ the -strong twin), a register BETWEEN the page-muted and the bright-bucket full
+       ink (legible-AND-subordinate; the caption stays quieter than body --foreground).
+       This is NOT a fork of --glass-tint-* — it READS the seam context and expresses the
+       third state; it NEVER re-declares --glass-tint-ink/-strength-* (W-DARK-MATERIAL's
+       frozen bound). The BA bright-bucket lift (@container --glass-backdrop:light above,
+       --muted-foreground → --foreground) STILL WINS where the plate darkens — the
+       @container conditional overrides this unconditional :where() when it engages, so a
+       darkened plate goes full ink; this calm re-point is the calm-plate case ONLY. The
+       overlay band (:where(.glass-floating, .glass-overlay) above) is a DISJOINT selector
+       set (it keeps the full-ink lift), so neither path collides. The values auto-flip per
+       mode (the on-glass rungs carry their own light/dark per-mode arms in tokens). */
     :where(.glass-card, .glass-resting, .glass-quiet, .glass-wash) {
         --glass-tint-source: var(--glass-tint-ink);
-        --glass-tint-strength: var(--glass-tint-strength-floor);
+        /* BC.W-ADAPTIVE-RECONCILE — the CONTINUOUS observer-driven darken (the dead-knob
+           closed; req #7). The strength is no longer a flat floor: it is a clamp that
+           READS the observer's measured `--glass-backdrop-luma` and lerps from the calm
+           warm-cream floor toward the ≤24% AA ceiling as the backdrop brightens past the
+           `--glass-backdrop-luma-knee` (the iOS-27 dynamic-range shift, apple-ios27.md
+           §1.5). Over a calm/dark backdrop (luma ≤ knee, the `max(0, …)` ramp → 0) the
+           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). */
+        --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)))
+            ),
+            var(--glass-tint-strength-aa)
+        );
+        --muted-foreground: var(--on-glass-muted);
+        --muted-foreground-strong: var(--on-glass-muted-strong);
     }
 
     /* AX.W55 — the `contrast-color()` foreground-ink flip (Chrome 147+/Safari 26+).
@@ -257,14 +338,22 @@
                 --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));
-        }
+        /* BC.W-DIALOG-GLASS / BC.W-ADAPTIVE-RECONCILE (overlay-band arm) — the overlay
+           band's `contrast-color()` ink flip is now GATED in the bright bucket above
+           (the @container --glass-backdrop:light block already lists `.glass-floating,
+           .glass-overlay` alongside the content tiers), NOT here as an UNCONDITIONAL
+           flip. The retired unconditional `:where(.glass-floating, .glass-overlay)`
+           rule blackened the ink even on a CALM modal over a light page — a translucent
+           cream plate forced to pure-black `contrast-color(--card)`, harsh on the cream,
+           and `--muted-foreground` flipped to the same so captions lost their muted
+           register. Now: over a calm/dark backdrop the modal keeps the WARM-INK
+           `--foreground` (legible, not pure-black) + the muted caption register; only a
+           modal over a genuinely-bright/busy backdrop flips to the dark contrast ink
+           (where the plate ACTUALLY darkens to bright-bucket AA), the `--foreground`/
+           `--muted-foreground` lift moving in LOCKSTEP there (the scope-6 lockstep). The
+           overlay band STILL self-darkens UNCONDITIONALLY (the tint-strength clamp above,
+           it floats over unknown) — only the INK flips in the bright bucket. ONE
+           reconciled flip, not two forks (ladder.css stays the single source). */
         /* 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
@@ -332,7 +421,16 @@
             var(--glass-shadow-floating);
     }
 
-    /* Grain noise overlay — reuses paper texture SVG, no extra assets */
+    /* 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,
@@ -342,36 +440,44 @@
         position: absolute;
         inset: 0;
         border-radius: inherit;
-        background: var(--paper-clean-texture);
+        /* 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;
     }
 
-    /* (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);
+    /* 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,

package/src/styles/glass/material.css

@@ -105,23 +105,72 @@
            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%
+        /* BB.W-LENSING (scope 3) — the motion-reactive EDGE glint UNIFIED with the
+           centered catch-light disc on ONE `::before`. TWO background layers compose:
+           (TOP) the angle-keyed EDGE-anchored conic sweep — a warm-cream arc that
+           brightens the RIM where the pointer's `--specular-angle` grazes (the
+           glass-THICKNESS read iOS-27 fuses with the catch-light); (BOTTOM) the
+           existing pointer-position centered disc. BOTH ride the SAME `--specular-
+           intensity` cohort (the `opacity` below) + `plus-lighter` blend + warm-cream
+           core `hsl(40 35% 92%)` — NEVER a second color/blend fork. The conic is masked
+           to the rim band only (the `--glass-edge-glint-band` radial mask, scope 3),
+           so the glint is a bounded RIM ring, NOT a whole-plate wash (the AX.W52 D19
+           bounded-gleam discipline). The `--specular-angle` floor `0deg` sits the glint
+           at the top edge when unwired (static rest — no ambient drift, no blowout). */
+        /* BB.W-GLASS-ACCENT — the catch-light CORE COLOR composes the per-instance
+           chromatic accent. The warm-cream `hsl(40 35% 92%)` core resolves through
+           the ONE `--glass-specular-core` var, OKLab-mixed toward `var(--glass-
+           accent)` at `var(--glass-accent-strength)`. This tints the CORE only — it
+           is the COLOR axis; W-LENSING owns the GEOMETRY (the conic angle-keyed
+           edge-glint + the radial disc + the masks + the `plus-lighter` blend, all
+           BELOW, untouched). Tinting the ONE core tints BOTH the centered disc AND
+           the rim glint (they share the core), so the data hue reads at the glint
+           where the pointer grazes — the data-keyed colored catch-light. At
+           `--glass-accent-strength: 0%` + `--glass-accent: transparent` (the
+           `@property` defaults) the mix === `hsl(40 35% 92%)` byte-identical (the W2
+           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. */
+        --glass-specular-core: color-mix(
+            in oklab,
+            hsl(40 35% 92%),
+            var(--glass-accent) var(--glass-accent-strength)
         );
+        background:
+            conic-gradient(
+                from var(--specular-angle, 0deg) at 50% 50%,
+                transparent 0deg,
+                color-mix(in srgb, var(--glass-specular-core) 55%, transparent) 18deg,
+                transparent 60deg,
+                transparent 360deg
+            ),
+            radial-gradient(
+                circle var(--glass-specular-size, 36%) at var(--specular-x, 50%) var(--specular-y, 50%),
+                color-mix(in srgb, var(--glass-specular-core) 50%, transparent) 0%,
+                transparent 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%
-        );
+        /* 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
+           the angle-keyed glint reads as a THICKNESS rim, not a center wash; the centered
+           disc keeps its own-radius clip (AX.W52 D19). `mask-image` Baseline 2023-12-07;
+           a non-supporting engine ignores it and the `inset: 0` + in-paint falloff still
+           bound the gleam. */
+        mask-image:
+            radial-gradient(
+                circle closest-side at 50% 50%,
+                transparent calc(100% - var(--glass-edge-glint-band, 22%)),
+                black calc(100% - calc(var(--glass-edge-glint-band, 22%) * 0.5)),
+                black 100%
+            ),
+            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
@@ -235,4 +284,18 @@
         --specular-intensity: var(--glass-specular-intensity-active, 0.16);
     }
 
+    /* BB.W-LENSING (scope 2) — the `:active` LENS-SWELL is RETIRED (DDR-LENS-BAKE,
+       glass-refract.css header). The swell drove the displacement `scale` by mutating
+       the `--glass-refract` axis on the `--glass-btn-press-t` press drive (28 rest → 44
+       pressed). That depended on the var()-spliced head/`scale`/tail filter — which never
+       PARSED as a `backdrop-filter` (three tokens: `url("…") <n> url("…")`), so the lens
+       rendered `none` and the swell animated a value that reached NO filter. A CSS url()
+       string token cannot carry a substituted `var()` (the engine does not re-tokenise
+       inside a string), so a dynamic per-instance `scale` is structurally impossible in a
+       single self-contained data-URI — and the single token is mandatory for both parse
+       validity and bundler url()-rewrite safety. The `scale` is now BAKED at the §10
+       default (28); the resting lens read is PRESERVED (and now actually renders), the
+       press-depth animation is the deliberate tradeoff. The press squish + gleam lift on
+       the SAME `--glass-btn-press-t` drive (material gleam, above) carry the press read. */
+
 }