@mkbabb/glass-ui 4.1.0 → 5.0.0

package/src/styles/animations.css

@@ -1,18 +1,7 @@
 /* Shared @keyframes — global animations used across projects */
 
-/* ── Floating panel entrance ── */
-@keyframes floating-panel-in {
-    from {
-        opacity: 0;
-        filter: blur(4px);
-        scale: 0.96;
-    }
-    to {
-        opacity: 1;
-        filter: blur(0);
-        scale: 1;
-    }
-}
+/* (BI.W-GLASS-DEDUP — the `floating-panel-in` entrance @keyframes retired with
+   floating-panel.css / `--animate-floating-panel-in`; FAM-9 clean break.) */
 
 /* ── Collapsible (reka-ui) ── */
 @keyframes collapsible-open {
@@ -301,6 +290,57 @@
     }
 }
 
+/* ── .glass-reveal EXIT (BG.W-OVERLAY-ENTER-PAINT / F5.R1) ──────────────────
+ *
+ * The reka-portaled-overlay (Dialog/Popover/DropdownMenu/…) EXIT MUST be a
+ * @keyframes animation, NOT a CSS transition. reka-ui's `usePresence` gates the
+ * unmount on `getComputedStyle(node).animationName`: it dispatches ANIMATION_OUT
+ * and awaits `animationstart`/`animationend`, with NO `transitionend` path — so a
+ * transition-only exit is torn down (~11ms, <1 frame) before it can paint (the
+ * paint-judge FAIL: Dialog+Popover exit painted 0 frames). The Sheet exit paints
+ * only because its `sheet-animate` (`animate-out`) is a keyframe reka can await;
+ * this gives the `.glass-reveal` recipe (glass/reveal.css) the SAME kind.
+ *
+ * `glass-reveal-out` is the enter bloom REVERSED: scale 1 → (0.88 × squish),
+ * opacity 1 → 0, filter blur(0) → blur — the SAME three coupled channels, on the
+ * no-overshoot `--ease-out` clock (a closing surface must never overshoot past
+ * gone, §6/W-MOTION-CANON P2). NO `translate` (the base/Dialog has none; a side
+ * popover's slide-out stays a transition — a different property that coexists,
+ * never clobbering a center Dialog's `-translate-x-1/2 -translate-y-1/2`). The
+ * `to` values MIRROR the `.glass-reveal[data-state="closed"]` static end-state so
+ * a non-supporting engine still lands correctly. Compositor-only (scale/opacity/
+ * filter — the proof:no-layout-animation floor). The custom-property `var()`s
+ * resolve on the animated `.glass-reveal` element (they are declared on its base
+ * rule). */
+@keyframes glass-reveal-out {
+    from {
+        scale: 1 1;
+        opacity: 1;
+        filter: blur(0);
+    }
+    to {
+        scale: calc(var(--glass-reveal-enter-scale, 0.88) * var(--lq-stretch-x, 1.06))
+            calc(var(--glass-reveal-enter-scale, 0.88) * var(--lq-stretch-y, 0.945));
+        opacity: 0;
+        filter: blur(var(--glass-reveal-blur, 4px));
+    }
+}
+
+/* The reduced-motion EXIT — fade ONLY (no transform/blur frames, the vestibular
+ * floor, WCAG 2.3.3). Still a keyframe reka can await (a transition-only fade
+ * would be torn down the same way, and the surface would vanish rather than fade),
+ * so the fade PAINTS under `prefers-reduced-motion: reduce`. The reveal.css PRM
+ * carve swaps `animation-name` to this while snapping scale/translate/filter to
+ * their endpoints. */
+@keyframes glass-reveal-out-reduced {
+    from {
+        opacity: 1;
+    }
+    to {
+        opacity: 0;
+    }
+}
+
 /* ── §TOP-LAYER ENTRY/EXIT (AQ.W5 §Design 2) ───────────────────────────────
  *
  * A pure-CSS entry/exit grammar for NATIVE top-layer surfaces — `[popover]`
@@ -342,16 +382,21 @@
            leg, glass/reveal.css). */
         filter: blur(var(--top-layer-enter-blur, 4px));
         transition-property: opacity, scale, filter, display, overlay;
-        /* BA.W-GLASS-CAL Unit 3 — the enter rides the bouncy spring's OWN settle
-           clock (`--spring-bouncy-duration`, the 2%-band envelope settle) rather
-           than the generic `--duration-normal`, so the emphatic dialog/popover
-           entrance bounce reads fully instead of being clipped at 0.3s. The blur
-           decongest rides the no-overshoot `--ease-out` (EFFECTS), the scale the
-           bouncy spring (SPATIAL) — the W-MOTION-CANON split. */
-        transition-duration: var(--spring-bouncy-duration),
-            var(--spring-bouncy-duration), var(--spring-bouncy-duration),
-            var(--spring-bouncy-duration), var(--spring-bouncy-duration);
-        transition-timing-function: var(--spring-bouncy), var(--spring-bouncy),
+        /* BI.W-REGISTER-TABLE — the FOURTH register RETIRED: the native `.glass-top-layer`
+           @starting-style enter is FOLDED onto the `enter-overlay` register bundle (the
+           SAME register the reka portaled overlays ride via `.glass-reveal` — one enter
+           grammar, no fourth recipe). It gains the register CLOCK (`--enter-overlay-clock`
+           = the parity-fixed --spring-snappy-duration) + spring (`--enter-overlay-spring`);
+           the scale/blur re-point to the register via the `--top-layer-enter-*` tokens
+           (scroll-tokens.css). The prior BA.W-GLASS-CAL bouncy-own-clock is superseded —
+           the native dialog/popover enter now matches the reka Dialog enter. The blur
+           decongest keeps the no-overshoot `--ease-out` (EFFECTS), the scale the register
+           spring (SPATIAL) — the W-MOTION-CANON split. HoverPopover (the live consumer)
+           re-points onto the register by inheriting the folded recipe. */
+        transition-duration: var(--enter-overlay-clock),
+            var(--enter-overlay-clock), var(--enter-overlay-clock),
+            var(--enter-overlay-clock), var(--enter-overlay-clock);
+        transition-timing-function: var(--enter-overlay-spring), var(--enter-overlay-spring),
             var(--ease-out), linear, linear;
         transition-behavior: allow-discrete;
     }
@@ -393,6 +438,20 @@
             var(--background) calc(var(--top-layer-backdrop-dim, 0.5) * 100%),
             transparent
         );
+        /* SCRIM COUPLES TO LAUNCH (BG.W-OVERLAY-ENTER-PAINT / F5.R1) — the ENTER dim
+           rides its OWN launch-coupled clock (`--top-layer-backdrop-in`, a fast
+           no-overshoot `--ease-out`) so the scrim reaches ≥80% of its target dim
+           within ~100ms of launch, coupled to the panel window rather than trailing
+           the panel on the slower `--duration-normal`/`--ease-standard` clock (the
+           HEAD defect: the scrim decoupled + dimmed over ~400ms AFTER the panel
+           seated). This ENTER transition is read from the [open] after-change state;
+           the base `::backdrop` transition stays the EXIT clock — released cleanly
+           WITH the panel, no overshoot past gone. The `@starting-style` from-state
+           makes the dim interpolate from transparent (the discrete allow-discrete
+           display/overlay legs stay). */
+        transition: display var(--top-layer-backdrop-in, 0.15s) allow-discrete,
+                    overlay var(--top-layer-backdrop-in, 0.15s) allow-discrete,
+                    background-color var(--top-layer-backdrop-in, 0.15s) var(--ease-out);
         @starting-style {
             background-color: color-mix(in srgb, var(--background) 0%, transparent);
         }

package/src/styles/card-scroll.css

@@ -0,0 +1,189 @@
+/* ─────────────────────────────────────────────────────────────────────────────
+ * card-scroll.css — the EXTERNALIZED <CardHeader shrink> scroll-choreography
+ * (BG.W-SCROLL-SHRINK-UNIFY — the card scroll-shrink lifted out of the
+ * CardHeader.vue <style scoped> block into ONE global, un-hashed home).
+ *
+ * WHY EXTERNAL (the encapsulation restore): the choreography WAS a scoped SFC
+ * block whose @keyframes names were Vue-scope-HASHED and whose slotted-content
+ * lanes needed the :slotted() escape. Externalized here it is un-hashed AND
+ * reaches the light-DOM slotted <CardTitle>/<CardDescription> via a PLAIN
+ * descendant selector (a GLOBAL file carries no data-v-… scope hash, so the
+ * plain `.card-header--shrink > [data-slot=…]` is the CORRECT form — it matches
+ * the slotted child with no hash to require).
+ *
+ * THE DRY FOLD (the UNIFY): the lane-2 title SCALE leg is shared with the
+ * page/hero large-title collapse (demo/stories/story-hero.css) via ONE
+ * @keyframes title-collapse — the card supplies --title-collapse-scale: 0.695
+ * (= --card-title-shrink-ratio), the page/hero supply 0.82. Only the SCALE leg
+ * is shared (a byte-identical scale-only keyframe); the hero keeps its OWN
+ * translate leg (story-hero-shrink-lift). NOT "one keyframe family" — one shared
+ * scale keyframe + per-surface translate.
+ *
+ * COMPOSITOR-ONLY (BB.W-CARD-COMPOSITE — the proof:no-layout-animation floor):
+ * every lane animates scale / transform / opacity ONLY — ZERO reflow per scroll
+ * frame (the A'-3 CLS 1.03 defect made structurally impossible). The scrub ease
+ * is the NO-OVERSHOOT --card-shrink-ease (re-pointed OFF the retired
+ * --ease-cartoon-punch — a scroll SCRUB must be monotonic; an anticipation-pop /
+ * overshoot on a scrub is the §12-LAWS proportion fence: cartoon-punch belongs
+ * on STATE-CHANGE beats, never a scroll scrub, and a non-monotonic curve breaks
+ * the monotonic-scrub bar).
+ *
+ * PRM is the OUTER gate (§Scope 4): the whole
+ * @supports (animation-timeline: scroll()) block sits under
+ * prefers-reduced-motion: no-preference, so under reduce NO scroll animation
+ * binds AT ALL and the header renders in its terminal rest state (full top
+ * space, full title size, full description visibility). No JS fallback + no
+ * `animation-duration: 0.01ms` stub is needed — the outer gate is the primary
+ * AND complete contract.
+ *
+ * REQUIRED ANCESTOR: `.card-scroll-host` on the scroll-overflow ancestor (the
+ * <ScrollCard> owns it) emits the --card-scroll named scroll-timeline. Without
+ * that host the named timeline never emits and the choreography sits idle.
+ * ───────────────────────────────────────────────────────────────────────────── */
+
+.card-header--shrink {
+    /* --card-title-shrink-ratio is the lane-2 scale ratio pinned from the resolved
+       type tokens at the default scale: --type-prose floor (18px) ÷ --type-heading
+       (25.9px) ≈ 0.695. A STATIC scalar (NEVER a per-frame font-size re-measure);
+       --type-prose is a clamp() so the ratio cannot be CSS-divided live — it is the
+       pinned reference knob. It feeds the shared @keyframes title-collapse via
+       --title-collapse-scale (a consumer whose --ui-scale moves the tokens off this
+       ratio overrides --card-title-shrink-ratio, a NAMED knob — never a fallback to a
+       font-size animation). */
+    --card-title-shrink-ratio: 0.695;
+    --title-collapse-scale: var(--card-title-shrink-ratio);
+    /* the scrub ease is NO-OVERSHOOT: a scroll scrub maps scroll → animation-progress
+       monotonically, so the timing function must be strictly monotone (the retired
+       --ease-cartoon-punch anticipation/overshoot made the title scale up-then-down
+       past a scroll point — the non-monotonic-scrub defect). */
+    --card-shrink-ease: var(--ease-out, linear);
+    /* the stuck-header backplate reads a KEYED warm-glass floating plate (the same
+       --glass-tint-* warm-admit seam the card body reads — the W55 tinted floating
+       rung). Card-LOCAL re-point of --card-header-bg (the shared shadow.css token is
+       READ-ONLY); a consumer override on the host still wins (higher specificity /
+       inline). */
+    --card-header-bg: color-mix(
+        in oklab,
+        var(--glass-bg-floating),
+        var(--glass-tint-source) var(--glass-tint-strength)
+    );
+    position: relative;
+    transform-origin: top;
+}
+
+/* lane 4 base — the stuck-header background is a scroll-driven LIFT, not a static
+   tint. A ::before BACKPLATE carries the --card-header-bg tint and fades
+   opacity: 0 → 1 on the --card-scroll timeline, so a stuck header reads transparent
+   over the body at scroll-top and lifts to the painted tint as it sticks. The
+   opacity channel is compositor-safe; the backplate sits BEHIND the slotted content
+   (z-index 0), so it never occludes the title/description. */
+.card-header--shrink::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    z-index: 0;
+    background: var(--card-header-bg);
+    opacity: 0;
+    border-radius: inherit;
+    pointer-events: none;
+}
+
+/* the slotted content sits ABOVE the scroll-driven backplate. */
+.card-header--shrink > * {
+    position: relative;
+    z-index: 1;
+}
+
+/* lane-3 base: the description is a transform-collapsible block. transform-origin:
+   top so the scaleY collapse retires it UPWARD (toward the title), not toward its
+   own center. */
+.card-header--shrink > [data-slot="card-description"] {
+    transform-origin: top;
+    will-change: transform, opacity;
+}
+
+/* ── The keyframes (un-hashed, global) — every step animates a compositor-safe
+   channel ONLY (scale / transform / opacity), the proof:no-layout-animation floor. ── */
+
+/* THE SHARED scale keyframe (BG.W-SCROLL-SHRINK-UNIFY) — the card title lane AND the
+   page/hero large-title collapse both ride this ONE keyframe, each supplying its own
+   --title-collapse-scale (card 0.695 / page-hero 0.82). The `scale:` LONGHAND (not the
+   `transform` shorthand) so it stacks independently of any per-surface `translate`
+   leg — the scroll-choreography.css `.scroll-pin` longhand idiom. transform-origin is
+   set per-consumer on the animated element (left top on the card title). */
+@keyframes title-collapse {
+    to {
+        scale: var(--title-collapse-scale, 0.82);
+    }
+}
+
+/* lane 1 — header content compress: the header content slides up via translateY so
+   the top breathing room visually compresses; the header BOX keeps its layout size
+   (no padding reflow). */
+@keyframes card-header-shrink {
+    from {
+        transform: translateY(0);
+    }
+    to {
+        transform: translateY(-0.5rem);
+    }
+}
+
+/* lane 4 — the scroll-driven header background LIFT (opacity on the backplate). */
+@keyframes card-header-bg-lift {
+    from {
+        opacity: 0;
+    }
+    to {
+        opacity: 1;
+    }
+}
+
+/* lane 3 — description retire: opacity fade + scaleY collapse (origin top), the
+   real-estate reclaim COMPOSITED (never a grid-template-rows relayout). */
+@keyframes card-desc-shrink {
+    from {
+        opacity: 1;
+        transform: scaleY(1);
+    }
+    to {
+        opacity: 0;
+        transform: scaleY(0);
+    }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: scroll()) {
+        /* lane 1 — header content compress. */
+        .card-header--shrink {
+            animation: card-header-shrink var(--card-shrink-ease) both;
+            animation-timeline: --card-scroll;
+            animation-range: 0px 120px;
+        }
+
+        /* lane 4 — the scroll-driven header background LIFT. */
+        .card-header--shrink::before {
+            animation: card-header-bg-lift var(--card-shrink-ease) both;
+            animation-timeline: --card-scroll;
+            animation-range: 0px 120px;
+        }
+
+        /* lane 2 — title shrink-in-place via the SHARED title-collapse SCALE keyframe;
+           the text run lays out ONCE at --type-heading, the scroll-timeline only
+           composites the scale (transform-origin left top anchors the leading edge). */
+        .card-header--shrink > [data-slot="card-title"] {
+            animation: title-collapse var(--card-shrink-ease) both;
+            animation-timeline: --card-scroll;
+            animation-range: 0px 120px;
+            transform-origin: left top;
+        }
+
+        /* lane 3 — description retire (opacity fade + scaleY collapse), the faster
+           0..80px cliff (description retires before the header fully settles). */
+        .card-header--shrink > [data-slot="card-description"] {
+            animation: card-desc-shrink var(--card-shrink-ease) both;
+            animation-timeline: --card-scroll;
+            animation-range: 0px 80px;
+        }
+    }
+}

package/src/styles/cards.css

@@ -6,11 +6,149 @@
  * only the 5-rung glass ladder. */
 
 @layer components {
-    /* Paper texture overlay */
+    /* ── BD.W-CARD-MATERIAL-FLOOR — the card-surface warm tint-seam enrollment ──
+       The §4 leg-(a) material floor, reconciled to the SHIPPED `--glass-tint-*`
+       seam (NOT a fork, NOT a global re-tint). The card's glass/cartoon surfaces
+       ride the `.glass-${tier}` ladder rung, whose fill is already
+       `color-mix(in oklab, --glass-bg-${tier}, --glass-tint-source --glass-tint-
+       strength)` (ladder.css) — so the card reaches the warm floor by setting a
+       CARD-LOCAL non-zero `--glass-tint-strength` (the global default at
+       surface-axis.css:83 stays `0%`, so the 6 other seam-readers — drawer / menu /
+       veil / jubilance / .btn-glass / .segmented-indicator — are byte-unchanged:
+       the blast-radius bite). `--glass-tint-source` defaults to `var(--card)` (a
+       warm cream, glass-fx.css:158), so the floor is warm by construction in BOTH
+       modes. The card clears the warm-chroma floor (C ≥ 0.02 warm) in the MATERIAL
+       itself — before the field even lands, and on a dead ground (print / reduced-
+       transparency), the "far too gray" verdict closes at the material layer.
+
+       SCOPE — `[data-surface]` is `glass` or `cartoon` (NOT `veil`: veil owns its
+       own `--veil-bg` tint seam below; NOT `opaque`: the solid `--card` plate is
+       already warm-cream). The strength is set on the host so it inherits into the
+       rung's `color-mix`. This is a card-local re-point of the SHIPPED seam — DRY,
+       no second compositing axis, the ladder rung does the mix. */
+    [data-slot="card"]:where(
+        [data-surface="glass"],
+        [data-surface="cartoon"]
+    ) {
+        --glass-tint-strength: 8%;
+        /* BD.W-CARD-CEL-MOTION (§3.1) — the defined-edge border-ink floor. The
+           ladder rung's `--glass-border-resting`/`-quiet` ink is 4% warm
+           (glass.css:331-332) — it vanishes cream-on-cream (K3 RED). Floor the
+           card's own border-ink UP to ≥8% warm-ink so the cel reads as a defined
+           SHAPE (WCAG 1.4.11 non-text). `--glass-border-rung` is the per-rung ink
+           the accent-composed `--glass-border-accent` reads (ladder.css /
+           surfaces.css); re-pointing it card-locally floors the border WITHOUT
+           forking the rim (the keyed two-stop rim from `--glass-material-rim` is
+           CONSUMED unchanged — the card does NOT re-mint a rim). Warm (the
+           `--foreground` mix is warm-cream in both modes); the `.dark` ink lifts
+           off the near-black field through the same `--foreground` flip. */
+        --glass-border-rung: color-mix(in srgb, var(--foreground) 9%, transparent);
+    }
+
+    /* BD.W-CARD-CEL-MOTION (§3.2) — the inner catch-light over the field. A faint
+       `screen`-blended warm catch sits where the upper-right `--glass-key` sun
+       hits, lifting the cel off the field (the §3 layer-4 catch, coherent with the
+       rim + cast — ONE key). It rides the host `background-image` stack ALONGSIDE
+       the field underlayer (both are static gradients in the same longhand; the
+       catch is the FIRST layer so it sits over the warm underlayer), so it adds NO
+       pseudo (`::before` = moving specular, `::after` = grain — both occupied).
+       `screen` lifts only where there is light, never darkening — and it is below
+       content + clipped to the host radius, so it never washes the text column
+       (the K-AA carve). Under `prefers-contrast: more` the screen blend is dropped
+       (the catch is decoration, the edge is the legibility asset). */
+    [data-slot="card"][data-surface="glass"]:not(.paper-grid) {
+        /* F2.R1 W-DARK-READABILITY-REPAIR — the blend is TOKENIZED so the dark arm
+           (tokens/dark-arm.css, the `--card-field-floor-blend` re-point) swaps the
+           light `screen` LIFT for a dark `normal` SINK. In dark the near-white amber
+           key screen-blended into a hot in-card lamp (value.js card-lighting-forensics
+           artifact 1); the dark arm blends NORMAL so the warm underlayer sinks INTO the
+           deep plate instead of lifting it toward the cream label. Light default is
+           byte-identical (unset token → the `screen, normal` fallback). */
+        background-blend-mode: var(--card-field-floor-blend, screen, normal);
+    }
+    @media (prefers-contrast: more) {
+        [data-slot="card"][data-surface="glass"]:not(.paper-grid) {
+            background-blend-mode: normal;
+        }
+    }
+
+    /* ── BD.W-CARD-FIELD-FLOOR — the orphan-card static warm field underlayer ──
+       The §2 leg-(b) structural contract, card-local fallback. The COMMON case is
+       ancestor-supplied: the page mounts ONE global `[data-paper-field]` plane
+       (AppShell) behind every route, and the card composites over it. The ORPHAN
+       case is a card in an OCCLUDING context an ancestor field cannot reach (a
+       dialog / drawer / portal that paints its own opaque ground over the page
+       field) — there the card mounts its OWN cheap static warm underlayer so it is
+       NEVER gray-over-nothing wherever it is dropped.
+
+       MECHANISM — ONE static `radial-gradient` on the host `background-image`
+       longhand (the proven `.paper-grid` coexistence seam: a later
+       `background-image` COEXISTS with the glass tier's `background:` shorthand
+       fill — paints OVER the translucent color, UNDER content + UNDER both
+       pseudos, clipped to the host `border-radius` by construction). Zero JS, one
+       compositor-cached paint, PRM-static. The warm 0-alpha stops are explicit
+       `oklch(L C H / 0)` (NEVER bare `transparent` — the WebKit black-premultiply
+       hole, build-trap-(d)).
+
+       THE NO-DOUBLE-PAINT GATE (the presence-BEHIND check, NOT `closest()`): the
+       fallback paints ONLY when NO `[data-paper-field]` ancestor is present — `:where(
+       [data-paper-field]) &` switches it OFF under the global field, so a card over
+       the page field reads the page field (no local underlayer), and a 50-card grid
+       under ONE ancestor field is ONE field paint, not N. A `cartoon`/`opaque`
+       card already carries a defined edge + warm fill, so the orphan field is the
+       glass-surface case; `surface="glass"` only (the orphan glass card is the one
+       that reads gray-over-nothing). The `.paper-grid` document register is EXCLUDED
+       by selector (it sets its own grid `background-image` underlayer — a grid card
+       opts out of the warm-field fallback, not a `background-image: none` race). */
+    [data-slot="card"][data-surface="glass"]:not(.paper-grid) {
+        /* TWO static layers in ONE longhand (blended by the `background-blend-mode`
+           above — `screen, normal`): (1) the upper-right KEYED catch-light (warm,
+           `screen`-blended so it only LIFTS — the §3 catch), then (2) the warm cel
+           UNDERLAYER (one radial, amber-key toward the upper-right `--glass-key`,
+           the field fallback). Both fade to a warm 0-alpha — NEVER bare
+           `transparent` (the WebKit black-premultiply hole, build-trap-(d)). */
+        /* F2.R1 W-DARK-READABILITY-REPAIR — TOKENIZED so the dark arm swaps the two
+           hot light-amber screen radials (L≈0.9-0.96) for ONE damped warm-DARK sink
+           (tokens/dark-arm.css `--card-field-floor-image`). Light default is the two
+           radials below (unset token → byte-identical light paint). Machine-locked by
+           `proof:glass` dark-legibility DL1 (the composited hot-zone label clears AA +
+           APCA over the dark plate). */
+        background-image: var(
+            --card-field-floor-image,
+            radial-gradient(
+                60% 55% at 80% 16%,
+                oklch(0.96 0.04 78 / 0.5),
+                oklch(0.96 0.04 78 / 0) 72%
+            ),
+            radial-gradient(
+                120% 110% at 78% 22%,
+                oklch(0.9 0.075 72 / 0.5),
+                oklch(0.9 0.075 72 / 0) 70%
+            )
+        );
+    }
+
+    /* The presence-behind gate — under an ancestor field, the card reads the REAL
+       field (the page plane transmits through the translucent fill), so the local
+       fallback is switched OFF (no double paint). A 50-card grid under ONE ancestor
+       field is ONE field paint, not N local underlayers. */
+    :where([data-paper-field])
+        [data-slot="card"][data-surface="glass"]:not(.paper-grid) {
+        background-image: none;
+    }
+
+    /* Paper texture overlay — a PAPER surface reads the ONE warm raster tooth
+       (BG.W-PAPER-TEXTURE-UNIFY), not the grey `--paper-clean-texture` whisper.
+       The tooth carries its warmth at SOURCE, so the `background-blend-mode`
+       multiply (light) / screen (dark) sinks/lifts the WARM fiber into the plate.
+       Reads the paper tile period (`--paper-grain-tile`), not the 200px glass-
+       grain whisper size. The `--paper-clean-texture` name is retained only for
+       the disjoint GLASS-grain system (glass/grain-overlay.css / dock/shell.css)
+       — the register fence (paper is warm material, glass is a neutral whisper). */
     .paper-texture {
-        background-image: var(--paper-clean-texture);
+        background-image: var(--paper-grain-tooth);
         background-repeat: repeat;
-        background-size: var(--paper-texture-size);
+        background-size: var(--paper-grain-tile);
         background-blend-mode: multiply;
     }
 
@@ -182,13 +320,114 @@
        a card surface that often hosts portaled content; `translate: 0` at rest
        mints the stacking context once. Longhand maps `translate(x, y)` 1:1. */
     translate: 0;
+    position: relative;
+    /* BD.W-CARTOON-CASTER — the LOUD register carries `--motion-weight: 1` in the
+       SAME recipe (the loud-register coupling: so the punch is never accidentally
+       muted to ~+13.6% by inheriting the rest 0.618 — the BD.W-CARTOON-PUNCH
+       loud-register guard's concrete pass-subject). The press ramp ALIASES the
+       existing `--card-press-t` (the host's `useLiquidPress` already drives it for
+       every `pressable` card) — NO second press var, NO Card press-driver rewrite. */
+    --motion-weight: 1;
+    --cartoon-press-t: var(--card-press-t, 0);
     transition:
-        translate var(--duration-normal) var(--spring-smooth),
+        translate var(--duration-normal) var(--ease-cartoon-punch),
+        scale var(--duration-normal) var(--ease-cartoon-punch),
         box-shadow var(--duration-normal) var(--ease-standard);
 
-    &:hover:not(:disabled) {
+    /* BD.W-CARTOON-CASTER — the hover RE-POINTS the existing rule onto the punch
+       curve (was --spring-smooth) and guards `:not(:active)` so the press squash wins;
+       the object lifts a hair UP-RIGHT (toward the upper-right `--glass-key`) and the
+       cast deepens to the lg rung (the gap opens). ONE hover rule, no double-declare. */
+    &:hover:not(:active):not(:disabled) {
         translate: var(--lift-sm) var(--lift-sm);
+        /* BD.W-CARD-CEL-MOTION (§5) — the cel lifts toward the light with a
+           sub-perceptual VOL-PRESERVING scale (X·Y ≈ 1: 1.015 × 0.985 ≈ 1.0): the
+           cel rising toward its sun reads as PEELING off the field, not a flat
+           sticker slide. Composes the existing `scale` transition (declared above)
+           on the punch curve. The press squash (`scale: 1.04 0.94`) wins via
+           `:not(:active)`. */
+        scale: 1.015 0.985;
         box-shadow: var(--shadow-cartoon-lg);
+        & .cartoon-cast {
+            box-shadow: var(--shadow-cartoon-lg);
+        }
+    }
+
+    /* BD.W-CARTOON-CASTER — the press is a NON-uniform SQUASH (H5): widen X, compress
+       Y — real squash & stretch, NOT a uniform shrink. The CSS `:active` is the no-JS
+       floor; `useLiquidPress` drives `--card-press-t` 0→1 for the continuous
+       interruptible press the inert caster rides. */
+    &:active:not(:disabled) {
+        scale: 1.04 0.94;
+    }
+}
+
+/* ── BD.W-CARTOON-CASTER — the inert-child moving cel cast ───────────────────────
+   The cast rides an INERT `<span class="cartoon-cast" aria-hidden>` child the Card
+   emits when `surface="cartoon"` — NOT a `::before`/`::after` pseudo (both are
+   OCCUPIED on the real glass carrier: `::before` is the moving-specular catch-light,
+   `::after` is the grain overlay; the H2 hardening). The child is a self-contained
+   ink-plate the body floats above: it carries the SAME shipped `--shadow-cartoon-md`
+   box-shadow (set ONCE per state-flip — NEVER animated, the §L7 paint-fence) and
+   MOVES on the compositor via `translate`/`scale` only.
+
+   The cast travels DOWN-LEFT (opposite the upper-right `--glass-key`, coherent with
+   the shadow.css cel-ink geometry) as the body lifts, and SPREADS as the gap opens.
+   ONE scalar drive: `--cartoon-press-t × --motion-weight` (the `:root` PRM carve
+   zeroes `--motion-weight` → travel/spread collapse to rest). It LAGS the body
+   (~1.15× slower transition) → the ink recoils LATE on release (follow-through /
+   overlapping action). The `--cartoon-cast-dx/dy` drag-track deltas are 0 at rest
+   (the opt-in `useCartoonCast` DOM bridge is future — labeled honestly). */
+.cartoon-cast {
+    position: absolute;
+    inset: 0;
+    z-index: -1; /* behind the cel face, in front of the page */
+    border-radius: inherit;
+    pointer-events: none;
+    box-shadow: var(--shadow-cartoon-md);
+    /* the derived offset + spread — read `--motion-weight × --cartoon-press-t`. The
+       sign is DOWN-LEFT (negative X, positive Y) to match the upper-right key. */
+    --cast-travel: calc(6px * var(--motion-weight) * var(--cartoon-press-t));
+    --cast-spread: calc(1 + 0.18 * var(--motion-weight) * var(--cartoon-press-t));
+    translate:
+        calc(-1 * var(--cast-travel) + var(--cartoon-cast-dx))
+        calc(var(--cast-travel) + var(--cartoon-cast-dy));
+    scale: var(--cast-spread);
+    /* the caster LAGS the body (~1.15×) → the late ink recoil on release. */
+    transition:
+        translate calc(var(--duration-normal) * 1.15) var(--ease-cartoon-punch),
+        scale calc(var(--duration-normal) * 1.15) var(--ease-cartoon-punch),
+        --cartoon-cast-dx var(--duration-normal) var(--ease-cartoon-punch),
+        --cartoon-cast-dy var(--duration-normal) var(--ease-cartoon-punch);
+    will-change: translate, scale;
+}
+
+/* ── BI.W-SHADOW-GRAMMAR (Law 4) — the offset-stamp requires a CARD silhouette ──
+   The hard 0-blur `--shadow-cartoon-*` offset stamp is a card-silhouette grammar: on
+   a CARD it tucks under the corner radius, but on a CAPSULE/PILL host the hard
+   directional stamp pokes off the stadium along the bottom-left arc = the lopsided
+   crescent (UF-A8/A9 — the loud `primary-audacious`/`gold-audacious` `-audacious`
+   CTAs, ss-08/ss-26). So the `.btn-punch` pill cast RE-POINTS the inert child's stamp
+   to a SOFT radius-following drop (`--shadow-lg`): the punch WEIGHT re-lands on the
+   soft drop + the press-squish + the specular gleam (the BD.W-CARTOON-PUNCH weight
+   SURVIVES — the ratified judgment), WITHOUT the hard offset crescent. The cast still
+   TRAVELS down-left on press (`--cartoon-press-t` drives translate/scale over the soft
+   drop) — the caster punch, minus the crescent. The hard offset stamp stays legal ONLY
+   under a card-radius ancestor (`.cartoon-surface`, the Card `surface="cartoon"`
+   register above). Law-4 GREEN condition of proof:geometry-grammar. */
+.btn-punch .cartoon-cast {
+    box-shadow: var(--shadow-lg);
+}
+
+/* BD.W-CARTOON-CASTER — PRM/PRT carve. Under reduced-motion `--motion-weight: 0`
+   zeroes travel/spread/squash/lag in ONE assignment (every `calc(… * --motion-weight)`
+   collapses to rest); the transition is killed. The static bold cel STAMP persists
+   (identity/legibility — only the TRAVEL/PUNCH is removed). */
+@media (prefers-reduced-motion: reduce) {
+    .cartoon-surface,
+    .cartoon-cast {
+        --motion-weight: 0;
+        transition: none;
     }
 }