@mkbabb/glass-ui 4.0.0 → 4.0.1

package/dist/styles/dock/shell.css

@@ -87,13 +87,32 @@
            centered in its cell (≥1px slack/side at hover), the cell sits flush at the
            dock content edge, and the `--dock-padding-block` (≈6px) padding holds the
            plate ≥7px clear of the `contain: paint` border-box edge on the block axis.
-           So `contain: paint` is the NON-proximate second clip box (the lane's
+           So the `paint` clip axis is the NON-proximate second clip box (the lane's
            `probe-bottomdock-nocontain.png` forced-root probe proved the inner
-           scroll-port box was proximate, not this) and it is UNEDITED here — the
-           inset + freed cross axis suffice, no containment lift on the control-plate
-           band. The π readback (W-DOCK-GEOMETRY-DELTA.md) records the live
-           plate-inside-padding margin number that binds this verdict. */
-        contain: paint;
+           scroll-port box was proximate, not this) and the `paint` axis is RETAINED
+           here — the inset + freed cross axis suffice, no containment LIFT on the
+           control-plate band. (BB.W-PERF-PRODUCER A′-4 widens the value to
+           `contain: layout style paint` — the restyle-scope axes ALONGSIDE the paint
+           clip box, see below — but never lifts `paint`.) The π readback
+           (W-DOCK-GEOMETRY-DELTA.md) records the live plate-inside-padding margin
+           number that binds this verdict. */
+        /* BB.W-PERF-PRODUCER A′-4 — the `--dock-morph-t` restyle-scope narrowing.
+           The per-frame morph scalar write recomputes the inheriting `calc()` group
+           across the dock subtree (dock.css's 10-selector `:where()` consumers); add
+           the `layout` + `style` containment axes so a scalar write recomputes
+           layout/style WITHIN the dock subtree, not up the document (the value.js A′-4
+           ~13fps restyle-cost trace). RECONCILED with the existing axes: `paint`
+           (above, the BA.W-DOCK-GEOMETRY clip box) composes — `contain: layout style
+           paint` is the union, NEVER `size` (which `container-type: inline-size` carries
+           as `inline-size` ONLY on the OPT-IN `containerName` host below; the default
+           free-floating dock must stay shrink-to-fit, so `size`/`inline-size` is
+           DELIBERATELY excluded here — adding it would re-introduce the 3.3.0 sliver
+           regression the §99 comment documents). The morph-axis `overflow: clip`
+           (the reveal aperture) + the `.glass-dock-frame` rail-escape are UNAFFECTED:
+           `layout`/`style` containment scopes RECALC, it does not establish a paint
+           clip beyond the already-present `paint` axis. The `DOCK_SPRING` clock is
+           byte-fenced (the value.js letter) — this is restyle COST, not a re-tune. */
+        contain: layout style paint;
         display: inline-flex;
         align-items: center;
         /* AW.W1 — the dock does NOT establish a default inline-size container.
@@ -273,16 +292,19 @@
            shell above; the cross axis stays visible there. */
         padding: var(--dock-padding-block, 0.375rem);
         border-radius: var(--radius-dock);
-        /* AX.W01 — a vertical rail is ALWAYS-EXPANDED (no collapse↔expand morph),
-           so its root padding/background/border-color never morph; the prior
-           `padding/background/border-color var(--dock-motion-*)` transition arms
-           are DELETED (a residual root CSS-transition on the morph-chrome props is
-           the second-clock smell the single-scalar rebuild retires). The block-axis
-           (height) morph is owned by the inner `.dock-layer-stack` / DockLayerGroup
-           via the `--dock-morph-t` scalar (the size `calc()` above), never a CSS
-           transition here. KEPT: the DECORATIVE hover-scale + press-squish (the
-           individual `scale`/`transform`) and the box-shadow fade — these are
-           interaction polish on the static rail, NOT the morph. */
+        /* BB.W-DOCK-MORPH-FAMILY (f) — the stale "a vertical rail is ALWAYS-EXPANDED
+           (no collapse↔expand morph)" assumption is RETIRED (it was false since
+           vertical-collapse shipped: `alwaysExpanded` defaults FALSE, so a vertical
+           dock genuinely collapses its `block-size`). The vertical plate's
+           bg/border/padding/radius now MORPH on the SAME `--dock-expand-t` scalar
+           the horizontal chrome rides (the morph.css `.glass-dock.vertical` interp +
+           padding axis-inverse + the radius arm below) — the chrome follows the
+           box-size morph, no discrete snap. NO root CSS-transition on the morph-
+           chrome props is re-added (a `transition: padding/background/border-color`
+           arm is the second-clock smell the single-scalar rebuild forbids — the
+           `--dock-expand-t` interp is the single authority). KEPT: the DECORATIVE
+           hover-scale + press-squish (the individual `scale`/`transform`) and the
+           box-shadow fade — interaction polish on the rail, NOT the morph chrome. */
         transition:
             box-shadow var(--dock-motion-standard),
             transform var(--dock-motion-resize),
@@ -318,6 +340,22 @@
         border-radius: var(--radius-xl);
     }
 
+    /* BB.W-DOCK-MORPH-FAMILY (f) — the VERTICAL big-dock CARD radius MORPHS on the
+       SAME `--dock-expand-t` scalar the horizontal `.shape-card` rides (the radius
+       arm of the vertical chrome un-gate; it lives in shell.css beside the horizontal
+       arm, not morph.css). `--radius-pill` at expand-t 0 (collapsed), the finite
+       `--dock-card-radius` at expand-t 1 (expanded) — the radius follows the box-size
+       block morph, no discrete snap. The static `.shape-pill`/`.shape-rounded` rest
+       radii above are the rest endpoints for those shapes; this is the card shape's
+       interpolated radius (mirroring the horizontal `:not(.vertical).shape-card`). */
+    .glass-dock.vertical.shape-card {
+        border-radius: calc(
+            var(--radius-pill) +
+                (var(--dock-card-radius) - var(--radius-pill)) *
+                var(--dock-expand-t, 1)
+        );
+    }
+
     /* AW.W3b — horizontal-root shape rules. The `shape-*` class once bound ONLY under
        the vertical surface; on a horizontal dock the prop silently no-op'd (the root
        hardwired `--radius-dock` = `--radius-pill`). These rules close that

package/dist/styles/dock.css

@@ -67,6 +67,38 @@
     initial-value: 0;
 }
 
+/* BB.W-DOCK-MORPH-FAMILY (e) — the `@property`-registered dock-scale axis. The
+   dock-scale cascade is `--dock-scale: calc(var(--ui-scale) * var(--dock-local-scale,
+   1))` (tokens/sizing.css). UNregistered, that `calc()` substitutes ONCE at `:root`
+   against the `:root` identity `--dock-local-scale: 1`, so a consumer-scope
+   `--dock-local-scale` override is INHERITED but never RE-EVALUATED — the dock keeps
+   `--dock-scale: calc(1 * 1)` and stays at the unscaled base (the 3rd recurrence of
+   the AX.W55 substitution-vs-inheritance trap; the documented-but-broken `:root`
+   preset). Registering `--dock-local-scale` as an INHERITING `@property <number>`
+   makes a registered inheriting custom property re-substitute PER-ELEMENT, so a
+   `--dock-local-scale` override on ANY dock scope re-evaluates the `calc()` at that
+   scope and threads the whole geometry cascade (box·pad·gap·tab·tile·glyph) down in
+   lockstep — the `:root` preset made real (the `@property --dock-morph-t` house
+   idiom above is the precedent). `--dock-scale` itself is ALSO registered (the
+   derived axis) so its `calc()` re-resolves per-element when `--dock-local-scale`
+   shifts. ADDITIVE ONLY: `initial-value: 1` is the identity, so at the default
+   `--dock-local-scale: 1` the resolved `--dock-scale` is byte-IDENTICAL to HEAD (no
+   rung re-tune); the `@media (pointer: coarse)` re-declare (overflow.css) STAYS the
+   `:root`-equivalent re-resolve, and this registration is the complementary
+   non-`:root`-scope thread. DOCK_SPRING is untouched (this is a token registration,
+   not a clock). */
+@property --dock-local-scale {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 1;
+}
+
+@property --dock-scale {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 1;
+}
+
 @layer components {
     :where(
         .glass-dock,

package/dist/styles/drawer.css

@@ -1,21 +1,35 @@
 /*
- * drawer.css — Detented bottom-sheet grammar (AN.W3).
+ * drawer.css — Detented bottom-sheet grammar (AN.W3; BB.W-DRAWER-ABROGATE).
  *
- * vaul-vue owns the snap math (the spring transform between snap-points, the
- * drag-resistance overshoot, the `data-vaul-*` state attributes). glass-ui owns
- * the LOOK: the glass sheet surface, the rounded peek handle, the snap-stop
- * indicator rules, and the drag-resistance feel-tuning. This file is the
- * substrate so a consumer mounting `<Drawer mode="live-behind">` does not
- * re-author the three detents from scratch.
+ * THE HOUSE owns the snap math end-to-end now (vaul-vue ABROGATED). The Drawer
+ * family composes the reka `DialogRoot`/`DialogPortal`/`DialogContent` headless
+ * substrate (the SAME vueuse-free substrate every other compound wrapper binds),
+ * and the snap settle is driven by ONE house `SpringProgress` on the `DRAWER_SNAP`
+ * register (`useDrawerSnap.ts`, the §6 dock-morph `linear()` clock — NOT a bespoke
+ * `cubic-bezier(.32,.72,0,1)` transition; that was vaul's). The engine writes the
+ * `--glass-drawer-t` snap-fraction scalar (0 = closed/offscreen, 1 = the fullest
+ * detent) the content root reads as its translate; this file owns the LOOK: the
+ * glass sheet surface, the rounded peek handle, the snap-stop indicator rules, and
+ * the detent-fill geometry. This file is the substrate so a consumer mounting
+ * `<Drawer mode="live-behind">` does not re-author the three detents from scratch.
  *
  * Token-first — every visual axis reads a custom property. Consumers retune
  * the sheet by overriding the rungs below, never by editing this file.
  */
 
+/* The snap-fraction scalar the house `useDrawerSnap` engine writes per frame. The
+ * content root's inline `transform` reads it (DrawerContent.vue) — typed so the
+ * default (1 = fully open) keeps a no-snap content-sized sheet seated open. */
+@property --glass-drawer-t {
+    syntax: "<number>";
+    inherits: false;
+    initial-value: 1;
+}
+
 :root {
     /* Detent grammar knobs — overridable per-consumer */
     --drawer-handle-w: 2.25rem;
-    --drawer-handle-h: 0.3125rem; /* 5px — vaul's hit-target rhythm */
+    --drawer-handle-h: 0.3125rem; /* 5px — the iOS grip hit-target rhythm */
     --drawer-handle-color: var(--muted-foreground);
     --drawer-handle-opacity: 0.45;
     --drawer-handle-opacity-active: 0.85;
@@ -23,14 +37,15 @@
 }
 
 /*
- * The sheet surface. Replaces the prior inline-Tailwind triplet on
- * DrawerContent.vue so the glass tier + the snap transform feel live in one
+ * The sheet surface. The glass tier + the snap-translate feel live in one
  * token-driven place. The fixed/inset/z-index layout stays here too.
  *
- * NOTE: vaul-vue sets `transition: transform .5s cubic-bezier(.32,.72,0,1)` and
- * `touch-action: none` on `[data-vaul-drawer]` from its injected stylesheet —
- * that IS the drag-resistance spring curve. We do NOT override `transition` so
- * the snap feel is preserved; we layer border-radius + glass surface on top.
+ * NOTE: the snap motion is the house `useDrawerSnap` `SpringProgress` writing
+ * `--glass-drawer-t`, which the content root's inline `transform` reads (the §6
+ * doctrine — ONE motion vocabulary, no `transition: transform` curve injected on
+ * `[data-glass-drawer]`). `touch-action: none` on the handle keeps the drag gesture
+ * from scrolling the page. We layer border-radius + glass surface on top of the
+ * spring-driven translate.
  */
 .glass-drawer {
     position: fixed;
@@ -107,24 +122,26 @@
 }
 
 /*
- * Detented (snap-point) sheets fill the viewport height. vaul positions the
- * sheet by translating it DOWN by `innerHeight - (fraction * innerHeight)` —
- * so for a snap fraction to read as that fraction OF THE VIEWPORT, the sheet's
- * top must sit at the viewport top when fully open (offset 0). A `height: auto`
- * content sheet would instead translate off-screen. vaul tags the snap case via
- * `[data-vaul-snap-points=true]`; we fill height there and let the content
+ * Detented (snap-point) sheets fill the viewport height. The house engine positions
+ * the sheet by translating it along its drag axis by `(1 - --glass-drawer-t) * 100%`
+ * (DrawerContent.vue's inline transform) — so for a snap fraction to read as that
+ * fraction OF THE VIEWPORT, the sheet's top must sit at the viewport top when fully
+ * open (translate 0). A `height: auto` content sheet would instead translate
+ * off-screen. The content root tags the multi-detent case via
+ * `[data-glass-drawer-snap-points=true]`; we fill height there and let the content
  * scroll inside.
  */
-.glass-drawer[data-vaul-snap-points="true"] {
+.glass-drawer[data-glass-drawer-snap-points="true"] {
     height: 100%;
     max-height: 100%;
     margin-top: 0;
 }
 
-/* Live-behind direction variants — vaul tags the root with the drag axis.
-   Bottom is the default + the F-side pattern; the others ride the same surface
-   so a top/side live-behind sheet inherits the grammar. */
-.glass-drawer[data-vaul-drawer-direction="top"] {
+/* Direction variants — the content root tags itself with the drag axis
+   (`data-glass-drawer-direction`). Bottom is the default; the others ride the same
+   surface so a top/side sheet inherits the grammar. The side-lens (left/right) is
+   the BB-2 full-slide axis — it pins to its edge + fills the cross axis. */
+.glass-drawer[data-glass-drawer-direction="top"] {
     bottom: auto;
     top: 0;
     margin-top: 0;
@@ -134,11 +151,35 @@
     border-radius: 0 0 var(--radius-panel) var(--radius-panel);
 }
 
+.glass-drawer[data-glass-drawer-direction="left"],
+.glass-drawer[data-glass-drawer-direction="right"] {
+    inset-inline: auto;
+    inset-block: 0;
+    height: 100%;
+    max-height: 100%;
+    width: min(24rem, 92vw);
+    margin: 0;
+    border: 1px solid var(--glass-border-overlay);
+}
+
+.glass-drawer[data-glass-drawer-direction="left"] {
+    left: 0;
+    border-left: 0;
+    border-radius: 0 var(--radius-panel) var(--radius-panel) 0;
+}
+
+.glass-drawer[data-glass-drawer-direction="right"] {
+    right: 0;
+    border-right: 0;
+    border-radius: var(--radius-panel) 0 0 var(--radius-panel);
+}
+
 /*
  * Peek handle — the rounded grip at the top of the sheet. It is the visual
- * affordance the user drags to cycle peek → half → full. vaul-vue intensifies
- * the grip on `:active` via its own `[data-vaul-handle]` rules when the consumer
- * uses `<DrawerHandle>`; this is the glass-ui default grip for the common case.
+ * affordance the user drags to cycle peek → half → full. The house snap engine
+ * (`useDrawerSnap`) binds the pointer-drag gesture directly on this handle (the
+ * `[data-glass-drawer-handle]` element) and flags it `[data-dragging]` while a drag
+ * is in flight, so the grip intensifies "live" during the gesture.
  */
 .glass-drawer-handle {
     flex-shrink: 0;
@@ -160,10 +201,11 @@
         width var(--duration-fast) var(--ease-out);
 }
 
-/* While the sheet is being dragged vaul exposes the gesture; intensify the grip
-   so the affordance reads as "live". `:active` covers the pointer-held case for
-   the default grip; consumers using vaul's `<DrawerHandle>` get its own active
-   rule in addition. */
+/* While the sheet is being dragged the house engine flags the handle
+   `[data-dragging]`; intensify the grip so the affordance reads as "live".
+   `:active` covers the pointer-held case + `[data-dragging]` covers the captured
+   drag; the hover lift is the rest affordance. */
+.glass-drawer-handle[data-dragging] .glass-drawer-grip,
 .glass-drawer-handle:active .glass-drawer-grip,
 .glass-drawer:hover .glass-drawer-grip {
     opacity: var(--drawer-handle-opacity-active);
@@ -176,7 +218,8 @@
  * `.glass-drawer-snap-rule` to a separator element inside the sheet; it reads as
  * the detent boundary line without competing with the content. This is the
  * "snap-stop visual indicator" the spec asks for, expressed as an opt-in class
- * (the detents themselves are positional, owned by vaul; the RULE is the look).
+ * (the detents themselves are positional, owned by the house snap engine; the
+ * RULE is the look).
  */
 .glass-drawer-snap-rule {
     height: 1px;
@@ -185,8 +228,11 @@
     background-color: var(--drawer-snap-rule-color);
 }
 
-/* Reduced-motion — vaul's transform transition is its own; we only suppress the
-   grip's affordance animation so the handle does not pulse for PRM users. */
+/* Reduced-motion — the house `SpringProgress` snaps the detent deterministically
+   under `prefers-reduced-motion: reduce` (its `respectReducedMotion` jumps the
+   `--glass-drawer-t` scalar to target in one frame, zero motion frames); here we
+   only suppress the grip's affordance animation so the handle does not pulse for
+   PRM users. */
 @media (prefers-reduced-motion: reduce) {
     .glass-drawer-grip {
         transition: none;

package/dist/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/dist/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,7 +211,13 @@
        `--glass-tint-strength: 0%`. */
     :where(.glass-floating, .glass-overlay) {
         --glass-tint-source: var(--glass-tint-ink);
-        --glass-tint-strength: var(--glass-tint-strength-aa);
+        /* BC.W-AUDIT — the scope-7 completion: the overlay band JOINS the content-tier
+           sub-perceptual FLOOR by default (translucent warm glass), and the FULL AA
+           darken engages ONLY under the bright bucket (the @container --glass-backdrop:
+           light above). The prior unconditional AA (20% ink-ward) collapsed every
+           floating surface to grey over the common calm-light backdrop. The full glass
+           rebuild + the per-band muted/contrast reconciliation is BC. */
+        --glass-tint-strength: var(--glass-tint-strength-floor);
         --muted-foreground: var(--foreground);
     }
 
@@ -212,10 +230,31 @@
        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);
+        --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+).
@@ -332,7 +371,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 +390,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,