@mkbabb/glass-ui 4.0.1 → 4.2.0

package/src/styles/jubilance.css

@@ -0,0 +1,65 @@
+/* jubilance.css — BE.W-CELEBRATE-BURST — the earned glass-petal radial-bloom recipe.
+ *
+ * THE PETAL IS THE SURFACE'S OWN GLASS (CB4 / warm-cream identity). `.glass-celebration-
+ * petal` paints the warm-cream frosted glass material via the EXACT element-level oklab
+ * tint seam `glass/ladder.css` composes — `color-mix(in oklab, var(--glass-bg-floating),
+ * var(--glass-tint-source) var(--glass-tint-strength))` — so the petal reads as the
+ * surface's OWN glass, NOT a saturated confetti color. There is NO disco-grain, NO `✦`
+ * glyph, NO sparkle-sweep (the §6 calm register, the disco-fenced floor).
+ *
+ * THE :tone OPT-IN (the hue-keyed burst). `useCelebrationBurst({ tone })` writes
+ * `--glass-accent` onto each petal (the W-GLASS-ACCENT rim-tint seam); the catch-light
+ * core reads `--glass-specular-core` which ALREADY OKLab-mixes toward `--glass-accent ×
+ * --glass-accent-strength` (material.css) — so a download-complete petal blooms
+ * `--viz-download` through the SHARED specular cohort, never a second fork. At the default
+ * (no tone) `--glass-accent` is transparent → the warm-cream identity (the no-op floor).
+ *
+ * COMPOSITOR-ONLY (CB3 / proof:no-layout-animation). The recipe paints a static frosted
+ * pill; the per-frame motion (translate/scale/opacity/filter) is the JS rAF step's inline
+ * writes (compositor channels ONLY — never a layout property). The recipe carries NO
+ * layout-animating transition.
+ *
+ * PRM-STATIC (the vestibular floor). Under reduce the JS `burst()` spawns NO drifting
+ * petals (the prefersReducedMotion() branch fires only the destination chip-bloom-in
+ * cascade) — so there are no petals to carve here; the destination cascade is PRM-carved
+ * by the EXISTING icon-chip-reveal `animation: none` rule (icon-chip.css), re-used not
+ * re-authored. */
+
+@layer components {
+    /* The short-lived overlay container the JS appends to the origin's offsetParent (one
+       DOM write, removed on settle). It is a zero-size anchor at the origin center; the
+       petals position-absolute off it. */
+    .glass-celebration-overlay {
+        position: absolute;
+        pointer-events: none;
+    }
+
+    /* The earned glass petal — the surface's OWN warm-cream frosted glass material. */
+    .glass-celebration-petal {
+        /* The petal footprint — a small pill, tokenized for the one-knob retune. */
+        --celebration-petal-size: 10px;
+        position: absolute;
+        inline-size: var(--celebration-petal-size);
+        block-size: var(--celebration-petal-size);
+        border-radius: var(--radius-pill, 9999px);
+        pointer-events: none;
+        /* THE WARM-CREAM GLASS (CB4) — the EXACT element-level oklab tint seam ladder.css
+           composes for every glass rung. NOT a saturated bg-<hue>/raw-Tailwind confetti
+           color: the petal reads as the surface's own frosted glass. */
+        background: color-mix(
+            in oklab,
+            var(--glass-bg-floating, color-mix(in oklab, var(--card), white 8%)),
+            var(--glass-tint-source, transparent) var(--glass-tint-strength, 0%)
+        );
+        /* A sub-perceptual warm-cream catch-light — reads the SHARED --glass-specular-core
+           (which carries the --glass-accent :tone opt-in via material.css's oklab mix), a
+           soft inner gleam so the petal reads as lit glass, never a flat slab. NO second
+           specular fork, NO disco. */
+        box-shadow:
+            inset 0 0 0 0.5px
+                color-mix(in oklab, var(--glass-specular-core, hsl(40 35% 92%)) 40%, transparent),
+            0 1px 3px color-mix(in oklab, var(--foreground), transparent 86%);
+        /* will-change promotes ONLY the compositor channels the JS step writes. */
+        will-change: transform, opacity, filter;
+    }
+}

package/src/styles/motion/morph-field.css

@@ -0,0 +1,229 @@
+/* motion/morph-field.css — BD.W-MORPH-FIELD-WELD — the ONE morph-field RECIPE.
+ *
+ * The body / neck / waist recipe + the DEDICATED squish channel every `useMorphField`
+ * consumer paints over. The weld JS (useMorphField.ts) writes the drive-derived custom
+ * properties once per frame (`--morph-squish`, `--morph-neck-girth`, `--morph-neck-gap`,
+ * `--morph-k`, `--morph-waist`, `--morph-specular-angle`); this sheet projects them onto
+ * the body + neck silhouettes. The MORPH_SIGNATURES rows live in the JS (motion-named
+ * DATA); this sheet is signature-agnostic — it paints whatever the masses carry.
+ *
+ * THE DEDICATED SQUISH CHANNEL (the dock-core hardening fence). The volume-preserving
+ * squish writes `--morph-squish`, NEVER `--stretch` (the 6-JS-owner + the
+ * `--dock-morph-max-stretch:1.14` clobber). A morph that ALSO rides --stretch (the dock
+ * collapse) keeps its own channel; the weld owns this one. Registered @property so a bare
+ * var() INTERPOLATES the ramp (the --dock-morph-t precedent).
+ *
+ * DETERMINISM (motion-canon P5 / the M5 scalar-binding). Every axis below is
+ * `f(var(--morph-*))` (the weld's drive-derived writes) — NEVER a CSS animation/transition
+ * with its own clock. A frame at a given drive value is byte-reproducible. Compositor-only
+ * (transform / scale / clip-path / opacity / --* — ZERO animated layout property).
+ *
+ * THE CARTOON PUNCH (welded IN, gated on the SHIPPED Band-0 tokens). The body squash rides
+ * `--morph-squish × --motion-weight`; the ink cast rides the `--shadow-cartoon-*` rung
+ * (never a hex literal, never an animated box-shadow); the neck specular-sweep lags the
+ * geometry (follow-through). `--motion-weight` and `--ease-cartoon-punch` are SHIPPED (P1,
+ * scheme-motion.css), so the punch is LIVE (not skipped); PRM zeroes --motion-weight → the
+ * squash/arc/cast collapse in ONE assignment.
+ *
+ * CROSS-ENGINE (§L7). The goo `<filter>` is the ONE `<GooFilter>` mount's REGULAR
+ * `filter:url(#…)` (NEVER backdrop-filter — bug 245510), applied on a SIBLING goo LAYER,
+ * never an ANCESTOR of glass (an ancestor filter kills backdrop-filter on descendants in
+ * both engines). The clip-path hourglass waist is the Tier-C cross-engine FLOOR under the
+ * filter — a concave waist on BOTH engines before any blur fuses it. The filter is gated to
+ * `[data-morphing]` (never a steady-state re-blur — the Safari budget fence). */
+
+/* The dedicated squish channel + the neck-drive channels — typed INHERITING @property so a
+   bare var() INTERPOLATES (the --dock-morph-t/--neck-t precedent). The weld writes them on
+   the host; descendant bodies + neck read the inheriting values. */
+@property --morph-squish {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 1;
+}
+@property --morph-neck-girth {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 0;
+}
+@property --morph-k {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 1;
+}
+@property --morph-waist {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 1;
+}
+@property --morph-specular-angle {
+    syntax: "<angle>";
+    inherits: true;
+    initial-value: 0deg;
+}
+
+@layer components {
+    /* The morph FIELD host — the sibling goo LAYER the filter applies to (never an
+       ancestor of glass). The weld writes the drive-derived channels here; the bodies +
+       neck live under it and read the inheriting values. The filter engages ONLY while the
+       morph is in-flight (`[data-morphing]`) — crisp at rest, gooey during the merge. */
+    .morph-field {
+        position: relative;
+        pointer-events: none;
+        /* isolation keeps the blur/threshold scoped to the masses, not the page behind. */
+        isolation: isolate;
+        filter: none;
+    }
+    /* Gate the goo filter to the in-flight window — the §L7 Safari budget fence (no
+       steady-state re-blur). The weld sets `[data-morphing]` on the host (or the consumer
+       does). The filter id is the consumer's tuned instance off the ONE <GooFilter> mount
+       (`url(#glass-goo)` / `url(#pager-goo)` / `url(#dock-morph-goo)` / `url(#morph-goo)`),
+       passed via `--morph-goo-filter`. The REGULAR filter property (Safari-correct). */
+    [data-morphing].morph-field,
+    [data-morphing] .morph-field {
+        filter: var(--morph-goo-filter, url(#morph-goo));
+    }
+
+    /* A morph BODY — a warm-cream domed-droplet mass the weld translates/squashes. The fill
+       is the SAME six-layer warm-glass register the whole library reads (NEVER gray — the
+       transparent-plate bug the showcase had is exactly this fill being absent). The
+       transform is written INLINE by the weld (translate + scale); this sheet supplies the
+       resting silhouette + fill + the cast. */
+    .morph-body {
+        position: absolute;
+        border-radius: 999px;
+        /* the warm-cream domed droplet — a soft radial so the goo threshold reads a domed
+           mass, not a flat slab; transmissive (~0.55-0.80 α) so the colorful field reads
+           THROUGH it. Reads the shared --glass-* cohort (warm-cream identity, both modes). */
+        background: radial-gradient(
+            120% 120% at 50% 38%,
+            var(--glass-bg-floating, color-mix(in oklab, var(--card), white 8%)) 0%,
+            var(--glass-bg-resting, var(--card)) 62%,
+            color-mix(in oklab, var(--card), var(--foreground) 6%) 100%
+        );
+        /* a 1px inner catch-light rim (the §3 defined edge) — the crisp metaball rim. */
+        box-shadow: inset 0 1px 0 0 color-mix(in oklab, white 22%, transparent);
+        overflow: clip;
+        transform-origin: center;
+        will-change: transform;
+    }
+
+    /* The welling NECK — the concave-throat filament between the two outermost bodies. Its
+       girth WELLS on `--morph-neck-girth` (peak mid, ~0 at the ends → no ghost throat at
+       rest) and its clip-path carves the structural hourglass waist (the Tier-C floor, both
+       engines, BEFORE the filter fuses it). The weld writes its transform inline (translate
+       + scaleX span + scaleY girth); this sheet supplies the fill + the waist clip + the
+       specular sweep. */
+    .morph-neck {
+        position: absolute;
+        border-radius: 999px;
+        background: radial-gradient(
+            130% 130% at 50% 40%,
+            var(--glass-bg-floating, color-mix(in oklab, var(--card), white 8%)) 0%,
+            var(--glass-bg-resting, var(--card)) 70%,
+            color-mix(in oklab, var(--card), var(--foreground) 6%) 100%
+        );
+        /* THE CONCAVE WAIST — the clip-path hourglass pinches the throat toward the
+           centerline as the gap-fraction k narrows (the structural local-minimum waist read
+           on BOTH engines before the blur). The inset GROWS from the rim as the waist
+           tightens (`1 - --morph-waist`), `round 999px` so the throat is a gel capsule. */
+        --neck-pinch: calc((1 - clamp(0, var(--morph-waist, 1), 1)) * 42%);
+        clip-path: inset(var(--neck-pinch) 0 var(--neck-pinch) 0 round 999px);
+        /* the neck is visible EXACTLY while it wells (the opacity is the girth). */
+        opacity: var(--morph-neck-girth, 0);
+        transform-origin: center;
+        overflow: clip;
+        will-change: transform, clip-path, opacity;
+    }
+
+    /* THE NECK SPECULAR-SWEEP (follow-through) — a moving catch-light bending along the
+       throat as it stretches, reading the SHARED --glass-specular-core cohort (NO fork).
+       The conic angle LAGS the geometry (`--morph-specular-angle` carries the 60° trail the
+       weld writes). plus-lighter additive; a non-supporting engine degrades to a plain warm
+       overlay. */
+    .morph-neck::after {
+        content: "";
+        position: absolute;
+        inset: 0;
+        border-radius: 999px;
+        pointer-events: none;
+        background: conic-gradient(
+            from var(--morph-specular-angle, 0deg) at 50% 50%,
+            transparent 0deg,
+            color-mix(
+                in srgb,
+                var(--glass-specular-core, hsl(40 35% 92%)) 55%,
+                transparent
+            ) 18deg,
+            transparent 60deg,
+            transparent 360deg
+        );
+        opacity: calc(
+            var(--glass-specular-intensity-rest, 0.12) +
+                clamp(0, var(--morph-neck-girth, 0), 1) * 0.18
+        );
+        mix-blend-mode: plus-lighter;
+        will-change: opacity;
+    }
+
+    /* THE 1940s INK CAST (solid drawing — the most ALIVE detail). A `::after` caster on the
+       FIELD that slides OPPOSITE the morph motion and DEEPENS mid-merge, pooling darkest at
+       the thinnest waist (the mass is heaviest where the neck is thinnest). On the REAL
+       `--shadow-cartoon-*` rung (never a hex, never an animated box-shadow — a compositor
+       translate of a soft radial). Gated on `--motion-weight` so PRM zeroes it. */
+    .morph-field::after {
+        content: "";
+        position: absolute;
+        inset: 0;
+        z-index: -1;
+        pointer-events: none;
+        border-radius: inherit;
+        /* the cast plane reads the cartoon shadow rung (the cards.css cohort) — a soft warm
+           ink pool that deepens as the waist thins. No hex; reads --shadow-color. */
+        background: radial-gradient(
+            60% 40% at 50% 60%,
+            color-mix(
+                    in srgb,
+                    var(--shadow-color, var(--foreground))
+                        calc(
+                            (18% + (1 - clamp(0, var(--morph-waist, 1), 1)) * 22%) *
+                                var(--motion-weight, 0)
+                        ),
+                    transparent
+                )
+                0%,
+            transparent 72%
+        );
+        /* slide OPPOSITE the morph — the cast trails the mass. The offset is the neck girth
+           × weight (deepest at mid-merge), on the cross axis. Compositor translate only. */
+        translate: 0
+            calc(var(--morph-neck-girth, 0) * 6px * var(--motion-weight, 0));
+        will-change: transform, background;
+    }
+
+    /* PRM (motion-canon P6 / §L5) — the goo layer drops, the neck never paints, the cast +
+       sweep are static-off; --motion-weight 0 (the :root PRM carve in scheme-motion.css)
+       already zeroes the squash/arc/cast amplitude. The morph still CONFIRMS (the weld's
+       seat() places one resting mass at the endpoint). */
+    @media (prefers-reduced-motion: reduce) {
+        [data-morphing].morph-field,
+        [data-morphing] .morph-field {
+            filter: none;
+        }
+        .morph-neck,
+        .morph-neck::after,
+        .morph-field::after {
+            display: none;
+        }
+    }
+
+    /* @supports floor — no `filter:url()` (the WebKit teardrop floor / a gap engine): the
+       clip-path hourglass waist on .morph-neck is the structural cross-engine FLOOR; the
+       bodies + the welling neck still read as a metaball via the clip-path waist alone (no
+       filter fuse). The morph degrades by SOFTENING, never to a non-morph crossfade. */
+    @supports not (filter: url("#morph-goo")) {
+        [data-morphing].morph-field,
+        [data-morphing] .morph-field {
+            filter: none;
+        }
+    }
+}

package/src/styles/paper.css

@@ -1,29 +1,68 @@
 /*
- * paper.css — Paper-texture primitives
+ * paper.css — Paper-texture primitives (BD.W-PAPER-MORPHISM, the texture+blend
+ * redesign — the grain/grit must be PLAINLY VISIBLE; if you squint, it FAILS).
  *
  * Two composable Tailwind `@utility` declarations:
- *   - paper-underpaint: fixed, app-root, fullscreen SVG turbulence at z-index -1
- *   - paper-grain-overlay: ::after overlay for individual surfaces
+ *   - paper-underpaint: fixed, app-root, fullscreen tooth texture at z-index -1
+ *   - paper-grain-overlay: ::after tooth overlay for individual surfaces
  *
- * Texture: feTurbulence baseFrequency 0.65, 4 octaves, desaturated via
- * feColorMatrix, blended multiply (light) / soft-light (dark). Tiles ~60px.
+ * THE FIX (the headline): the prior `feTurbulence bf=0.65 4-oct` + `feBlend
+ * multiply in2=SourceGraphic` cloud was a self-cancelling no-op — a fine cloud
+ * averaged to grey on hiDPI, and `overlay`/`soft-light` collapse to IDENTITY
+ * against a near-white cream wash (L≈0.98) / near-black ink wash (the blends only
+ * bite mid-grey backdrops; the paper register lives on the poles). Measured std
+ * 0.02–0.86 — invisible by math.
+ *
+ * THE TEXTURE — `--paper-grain-tooth`: a COARSE anisotropic grey-RGB speckle
+ * (`baseFrequency='0.04 0.09'` = grain direction, 2 octaves), KEEP the RGB
+ * (`feColorMatrix saturate=0` → grey, never zero it), per-channel
+ * `feComponentTransfer` slope-1.8/intercept-(-0.4) CONTRAST-STRETCH (the
+ * letterpress bite) + `feFuncA slope=0 intercept=1` (FULL OPAQUE alpha — the
+ * grey speckle is painted straight, the blend carries the darken/lighten; NOT the
+ * lens-A luminance→alpha matrix that gives a near-empty texture). `<filter
+ * color-interpolation-filters='sRGB'>` pins sRGB (identical Chrome↔Safari,
+ * deterministic seed). NO `feBlend` mud op. Tile 140px (coarse tooth reads as
+ * STRUCTURE, survives hiDPI, divides cleanly DPR 1/2/3).
+ *
+ * THE BLEND LAW (the decisive, physically-true move): `multiply` (light — ink
+ * sinks into the paper's pits → darken) / `screen` (dark — fiber catches light →
+ * lighten). Baseline, sRGB-safe, identical both engines. Plain per-mode arms.
+ *
+ * THE ALPHA: `--paper-grain-opacity` re-calibrated to the JND floor (light 0.22 /
+ * dark 0.16 — glass-fx.css / dark-arm.css; the inversion the measurements force:
+ * multiply on cream is gentle → MORE, screen on ink bites hard → LESS).
+ *
+ * The LIBRARY FENCE: `--glass-grain-opacity` (0.025/0.045) is BYTE-UNTOUCHED — the
+ * calm glass identity stands; paper is loud, glass is a whisper. That separation
+ * IS the design.
  */
 
+/* The ONE coarse-tooth texture — DRY single source, both utilities resolve it.
+   Painted onto a rect at full alpha (`feFuncA slope=0 intercept=1`); the
+   mix-blend-mode carries the visibility. sRGB-pinned, deterministic seed. */
+:root {
+    --paper-grain-tooth: url("data:image/svg+xml,%3Csvg width='140' height='140' viewBox='0 0 140 140' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='t' x='0' y='0' width='100%25' height='100%25' color-interpolation-filters='sRGB'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.04 0.09' numOctaves='2' seed='7' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3CfeComponentTransfer%3E%3CfeFuncR type='linear' slope='1.8' intercept='-0.4'/%3E%3CfeFuncG type='linear' slope='1.8' intercept='-0.4'/%3E%3CfeFuncB type='linear' slope='1.8' intercept='-0.4'/%3E%3CfeFuncA type='linear' slope='0' intercept='1'/%3E%3C/feComponentTransfer%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23t)'/%3E%3C/svg%3E");
+    --paper-grain-tile: 140px;
+}
+
 @utility paper-underpaint {
     position: fixed;
     inset: 0;
     z-index: -1;
     pointer-events: none;
-    background-image: url("data:image/svg+xml,%3Csvg width='60' height='60' viewBox='0 0 60 60' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='4' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3CfeBlend mode='multiply' in2='SourceGraphic'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='1'/%3E%3C/svg%3E");
+    background-image: var(--paper-grain-tooth);
     background-repeat: repeat;
-    background-size: 60px 60px;
-    opacity: var(--glass-grain-opacity);
+    background-size: var(--paper-grain-tile) var(--paper-grain-tile);
+    opacity: var(--paper-grain-opacity, var(--glass-grain-opacity));
+    /* LIGHT: ink sinks into the cream → multiply darkens the valleys. */
     mix-blend-mode: multiply;
 }
 
 :where(.dark) .paper-underpaint,
 .dark .paper-underpaint {
-    mix-blend-mode: soft-light;
+    /* DARK: fiber catches light off the ink → screen lifts (NOT soft-light, which
+       collapses to identity on the near-black pole — the self-cancelling defect). */
+    mix-blend-mode: screen;
 }
 
 @utility paper-grain-overlay {
@@ -36,23 +75,200 @@
         inset: 0;
         border-radius: inherit;
         pointer-events: none;
-        background-image: url("data:image/svg+xml,%3Csvg width='60' height='60' viewBox='0 0 60 60' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='4' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3CfeBlend mode='multiply' in2='SourceGraphic'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='1'/%3E%3C/svg%3E");
+        background-image: var(--paper-grain-tooth);
         background-repeat: repeat;
-        background-size: 60px 60px;
-        opacity: var(--glass-grain-opacity);
-        mix-blend-mode: overlay;
+        background-size: var(--paper-grain-tile) var(--paper-grain-tile);
+        opacity: var(--paper-grain-opacity, var(--glass-grain-opacity));
+        /* LIGHT tooth: multiply — the physically-true ink-into-pits darken (NOT
+           overlay, which is identity on the L≈0.98 cream pole). */
+        mix-blend-mode: multiply;
     }
 }
 
 :where(.dark) .paper-grain-overlay::after,
 .dark .paper-grain-overlay::after {
-    mix-blend-mode: soft-light;
+    /* DARK tooth: screen — fiber catches light off the ink (NOT soft-light). */
+    mix-blend-mode: screen;
+}
+
+/* ═══════════════════════════════════════════════════════════════════════
+   BD.W-PAGE-FIELD / BD.W-GLASS-FIELD — the WARM COLORFUL FIELD register
+   ───────────────────────────────────────────────────────────────────────
+   The single highest-leverage piece: it turns the gray storybook WARM. A
+   per-route four-layer technicolor CEL (amber key → terracotta mid → sand
+   bounce + a warm over-glaze toward the --glass-key corner) PLUS a wide
+   low-chroma BASE WASH that raises the floor everywhere, painted at FIELD
+   lightness (L 0.90-0.93 light / 0.28-0.34 dark — where the gamut admits
+   REAL chroma, NOT the gamut-bound L0.98 plate) OVER the decoupled
+   --neutral-0 floor (KEEP-NEUTRAL, untouched, never deleted).
+
+   ONE primitive, TWO acceptance floors (glass-floor ~0.012 composite-behind-
+   glass + field-floor 0.045 ground). The library glass material is BYTE-
+   UNTOUCHED — it finally has a backdrop worthy of it.
+
+   THE WARM-BOUND IS A PAINT INVARIANT: --field-h clamps the route's
+   --field-h-raw to [25,95] IN THE CSS calc, so an inline raw:210 CANNOT
+   paint teal/navy. The teal/navy purge is enforced at the paint layer.
+
+   OPT-IN: the warm stops only render under `[data-paper-field]` (the demo
+   chassis sets it per glass route) — the calm neutral underpaint stays the
+   default for solid-chrome routes; --neutral-0 stays decoupled + calm.
+
+   CROSS-ENGINE: pure compositor CSS — radial/conic-gradient + oklch() +
+   transform only. NO backdrop-filter:url, NO SVG goo, NO trig. oklch ≥ Safari
+   15.4, @property ≥ 16.4, gradients/transform forever. The WebKit premultiply-
+   toward-black desaturation hole is dodged: every warm 0-alpha stop is an
+   explicit `oklch(L C H / 0)` warm color, NEVER bare `transparent`.
+   ═══════════════════════════════════════════════════════════════════════ */
+
+/* The warm-bound: clamp the route's raw hue request to [25,95]. A DISTINCT
+   var (NOT self-referential `--field-h: max(var(--field-h),…)` which is a
+   no-op) — the route writes --field-h-raw, the field resolves --field-h.
+   Set on the field element itself so the clamp resolves even when the chassis
+   writes --field-h-raw on an ancestor. */
+.paper-field {
+    --field-h: clamp(25, var(--field-h-raw, 62), 95);
+}
+
+/* The warm-cel GROUND — a dedicated fixed plane the chassis mounts UNDER the
+   grain (the grain `.paper-underpaint` rides on top at its 0.22 multiply
+   opacity; the field paints true at full opacity / normal blend, so the grain
+   does NOT crush the pigment). ONE <PaperBackdrop field> component emits both,
+   stacked — one backdrop mount, grain on top, warm field below. */
+.paper-field {
+    position: fixed;
+    inset: 0;
+    /* one step BELOW the grain underpaint (the chassis mounts the grain at
+       -z-10) so the grain rides ON TOP of the warm field — one backdrop, two
+       stacked planes. Still above the page floor (content is z 0+). */
+    z-index: -11;
+    pointer-events: none;
+    /* L4 warm over-glaze — a faint cel sheen brightest toward the upper-right
+       --glass-key corner (cel coherence: field + glass rim/cast share ONE key).
+       --glass-key is a KEYWORD (upper-right), so the glaze is positioned by a
+       fixed `at`/`from` matching it — NEVER a `-58deg`/keyword-as-angle bug. */
+    background:
+        conic-gradient(
+            from -45deg at 78% 22%,
+            oklch(0.96 0.05 calc(var(--field-h) + 6) / calc(0.30 * var(--field-intensity))),
+            oklch(0.96 0.05 calc(var(--field-h) + 6) / 0) 28%,
+            oklch(0.96 0.05 calc(var(--field-h) + 6) / 0) 72%,
+            oklch(0.96 0.05 calc(var(--field-h) + 6) / calc(0.18 * var(--field-intensity)))
+        ),
+        /* the wide warm BASE WASH — raises the floor EVERYWHERE (no flat gap). */
+        radial-gradient(
+            120% 100% at 50% 50%,
+            oklch(0.91 0.075 calc(var(--field-h) + 8) / calc(0.50 * var(--field-intensity))),
+            oklch(0.91 0.075 calc(var(--field-h) + 8) / 0) 100%
+        ),
+        /* L3 sand fill-light bounce (bottom-right). */
+        radial-gradient(
+            95% 80% at 80% 88%,
+            oklch(0.88 0.115 calc(var(--field-h) + 30) / calc(0.90 * var(--field-intensity))),
+            oklch(0.88 0.115 calc(var(--field-h) + 30) / 0) 70%
+        ),
+        /* L2 terracotta saturated mid (right band, where the cards sit). */
+        radial-gradient(
+            95% 78% at 78% 30%,
+            oklch(0.85 0.145 calc(var(--field-h) - 24) / calc(0.90 * var(--field-intensity))),
+            oklch(0.85 0.145 calc(var(--field-h) - 24) / 0) 72%
+        ),
+        /* L1 amber key mass (densest pigment, top-left toward the key-light). */
+        radial-gradient(
+            100% 84% at 24% 20%,
+            oklch(0.87 0.155 calc(var(--field-h)) / calc(0.95 * var(--field-intensity))),
+            oklch(0.87 0.155 calc(var(--field-h)) / 0) 75%
+        ),
+        var(--neutral-0); /* L0 the KEEP-NEUTRAL solid floor — decoupled. */
+}
+
+/* DARK: warm-LUMINOUS — lower L, KEEP chroma; NEVER gray-charcoal. Plain
+   ancestor `.dark .x` (a scoped :global(.dark) silently drops; this is a
+   non-scoped global stylesheet so a plain `.dark` ancestor is correct). */
+.dark .paper-field {
+    background:
+        conic-gradient(
+            from -45deg at 78% 22%,
+            oklch(0.42 0.05 calc(var(--field-h) + 6) / calc(0.30 * var(--field-intensity))),
+            oklch(0.42 0.05 calc(var(--field-h) + 6) / 0) 28%,
+            oklch(0.42 0.05 calc(var(--field-h) + 6) / 0) 72%,
+            oklch(0.42 0.05 calc(var(--field-h) + 6) / calc(0.18 * var(--field-intensity)))
+        ),
+        radial-gradient(
+            120% 100% at 50% 50%,
+            oklch(0.30 0.055 calc(var(--field-h) + 8) / calc(0.50 * var(--field-intensity))),
+            oklch(0.30 0.055 calc(var(--field-h) + 8) / 0) 100%
+        ),
+        radial-gradient(
+            95% 80% at 80% 88%,
+            oklch(0.34 0.085 calc(var(--field-h) + 30) / calc(0.90 * var(--field-intensity))),
+            oklch(0.34 0.085 calc(var(--field-h) + 30) / 0) 70%
+        ),
+        radial-gradient(
+            95% 78% at 78% 30%,
+            oklch(0.33 0.10 calc(var(--field-h) - 24) / calc(0.90 * var(--field-intensity))),
+            oklch(0.33 0.10 calc(var(--field-h) - 24) / 0) 72%
+        ),
+        radial-gradient(
+            100% 84% at 24% 20%,
+            oklch(0.36 0.11 calc(var(--field-h)) / calc(0.95 * var(--field-intensity))),
+            oklch(0.36 0.11 calc(var(--field-h)) / 0) 75%
+        ),
+        var(--neutral-0);
+}
+
+/* The CARTOON DRIFT — liquid-weight on the ground: anticipation (pull-back) →
+   arc sweep (translate + rotate on ONE curve) → follow-through overshoot, baked
+   by --ease-cartoon-punch (DEPEND on BD.W-CARTOON-PUNCH, no literal-cubic dup).
+   Rides a `::before` copy of the bg (the field plane has a FREE ::before, no
+   collision with the grain). The warm stops survive PRM; only the drift
+   freezes. */
+.paper-field::before {
+    content: "";
+    position: absolute;
+    inset: -28%;
+    background: inherit;
+    opacity: 0.72;
+    pointer-events: none;
+    animation: field-cel-drift 42s
+        var(--ease-cartoon-punch, cubic-bezier(0.5, -0.2, 0.4, 1.2)) infinite
+        alternate;
+    will-change: transform;
+    content-visibility: auto;
+}
+
+@keyframes field-cel-drift {
+    /* independent translate:/scale:/rotate: LONGHANDS — a `transform: scale()`
+       shorthand would clobber the translate centering (build-trap e). */
+    from {
+        translate: -1.5% 1%;
+        scale: 1;
+        rotate: -1.2deg;
+    }
+    to {
+        translate: 2.5% -2.5%;
+        scale: 1.07;
+        rotate: 2.4deg;
+    }
 }
 
 /* ═══════════════════════════════════════════════
    A11y — respect user motion + transparency preferences
    ═══════════════════════════════════════════════ */
+@media (prefers-reduced-motion: reduce) {
+    /* the drift freezes — the warm field STAYS (it is content, not motion). */
+    .paper-field::before {
+        animation: none;
+    }
+}
+
 @media (prefers-reduced-transparency: reduce) {
+    /* the warm stops drop to 0-alpha; the decoupled --neutral-0 floor shows
+       (the calm opaque legibility floor). The field is a transmissive
+       enhancement, NEVER a legibility dependency. */
+    .paper-field {
+        --field-intensity: 0;
+    }
     .paper-underpaint,
     .paper-grain-overlay::after {
         opacity: 0;