@mkbabb/glass-ui 3.13.0 → 4.0.1

package/src/styles/instrument-chassis.css

@@ -72,6 +72,28 @@
         --phase-color: var(--muted-foreground);
         --phase-color-label: var(--muted-foreground);
 
+        /* BB.W-PHASE-PALETTE (N18) — the `complete` phase ink is a CONSUMER
+           token, not a hardcoded brand metal. The four active phases
+           (ping/download/upload/jitter) already read a consumer-registerable
+           `--chart-{phase}` with a library `--viz-*` fallback (the bus carries
+           phase IDENTITY); `complete` was the one arm that pinned the gold
+           directly, so every completion gilded itself the moment the phase
+           flipped. `--phase-complete-color` (+ its WCAG-twin
+           `--phase-complete-color-label`) DEFAULT to the same gold the arm
+           hardcoded — an un-overriding consumer paints byte-identical gold (the
+           back-compat floor) — but a consumer (or any ancestor) overrides EITHER
+           on its host/preset to re-ink completion (its phase spectrum, an aurora
+           register, …), so gold is EARNED (the dock CTA + personal-best
+           garnish), never the chassis default leaking onto every completion.
+           The default lives at the chassis root (NOT :root/tokens.css) because
+           it is a chassis-phase register, scoped to the surface owning the bus —
+           the same home `--phase-color`'s idle default occupies above. It reads
+           `var(--color-gold)` / `var(--color-gold-dark)` (the existing mode-
+           resolved tokens, unedited), so it inherits the SAME .dark / light-dark
+           resolution the hardcoded form did. */
+        --phase-complete-color: var(--color-gold);
+        --phase-complete-color-label: var(--color-gold-dark, var(--color-gold));
+
         /* AV.W16 TW3 — inline-size container named `chassis` so the dial reflow
            below reads the chassis's OWN box, not the viewport (portable into a
            narrow host). */
@@ -146,6 +168,51 @@
         display: none;
     }
 
+    /* ─────────────────────────────────────────────────────────────
+       BA.W-ATLAS-RECONCILE C-3 — structure variant (SILVER MILLED-METAL register)
+
+       The cool polished-steel housing read: the engraved-bezel `::before` stroke
+       AND the structural twin-line grooves re-point from the warm-cream
+       `--surface-tint-*` default onto the `--silver` quad (gold's cool mirror).
+       The chassis reads as an INDUSTRIAL precision-instrument panel — the
+       cool-metal twin of the warm-gold "complete"-phase affirmation the chassis
+       ships BY DEFAULT (the `--phase-complete-color` consumer token's gold
+       default; BB.W-PHASE-PALETTE — a consumer may re-ink completion, but the
+       silver register's narration is of the warm-gold completion default).
+
+       The phase cascade (`[data-phase="…"]`) stays ORTHOGONAL — a `structure`
+       chassis still retints its phase fills on `data-phase`; only the
+       structure-metal recipe (bezel + grooves) forks here. Consumer #2 of the
+       silver quad (the atlas's structure surface is consumer #1).
+
+       The silver is the W-NO-GRAY NAMED cool-neutral exception (a brand METAL
+       identity, not a neutral — its very-low chroma reads as milled steel, the
+       cool hue distinguishes it from the warm glass plate).
+       ───────────────────────────────────────────────────────────── */
+    .instrument-chassis[data-variant="structure"] {
+        /* The milled-panel edge: the chassis border lifts off the resting glass
+           edge onto a hairline silver structure stroke. */
+        border-color: color-mix(in oklab, var(--color-silver-dark) 55%, transparent);
+    }
+
+    /* The engraved bezel re-tints to the cool silver catch (the polished sleeve
+       reads as steel, not warm-cream). */
+    .instrument-chassis[data-variant="structure"]::before {
+        border-color: color-mix(in oklab, var(--color-silver-light) 60%, transparent);
+    }
+    .dark .instrument-chassis[data-variant="structure"]::before {
+        border-color: color-mix(in oklab, var(--color-silver) 40%, transparent);
+    }
+
+    /* The structural grooves re-point to the silver twin-line: the catch reads
+       the light silver, the under-shadow the dark silver — a milled seam, not the
+       default warm twin-line. ONE re-point at the variant root; every
+       `<ChassisDivider>` inside a structure chassis inherits it. */
+    .instrument-chassis[data-variant="structure"] {
+        --twin-line-catch: color-mix(in oklab, var(--color-silver-light) 50%, transparent);
+        --twin-line-shadow: color-mix(in oklab, var(--color-silver-dark) 40%, transparent);
+    }
+
     /* Phase-color cascade — single property, full chassis-wide retint.
        `--phase-color-label` mirrors the cascade through the WCAG companion
        tokens (AC.W6c F1.V-04). The label register falls back to the canvas
@@ -178,8 +245,15 @@
         --phase-tint-amount: var(--phase-tint-peak);
     }
     .instrument-chassis[data-phase="complete"] {
-        --phase-color: var(--color-gold);
-        --phase-color-label: var(--color-gold-dark, var(--color-gold));
+        /* BB.W-PHASE-PALETTE — demoted onto the `--phase-complete-color`
+           consumer seam (the exact `var(--chart-{phase}, …)` idiom the four
+           active arms above run). The arm reads ONLY the consumer token; the
+           gold lives in the token's DEFAULT at the chassis root, not as a
+           hardcoded ink here (a clean break with a back-compat default, NOT a
+           back-compat alias — no `--color-gold` dual-read survives). The warmth
+           ramp stays: `--phase-tint-amount` is orthogonal to the ink choice. */
+        --phase-color: var(--phase-complete-color);
+        --phase-color-label: var(--phase-complete-color-label);
         --phase-tint-amount: var(--phase-tint-peak);
     }
 
@@ -341,4 +415,35 @@
             height: 1px;
         }
     }
+
+    /* BB.W-DESKTOP-RESERVE (B3) — the WIDE-AXIS (desktop) dial reserve, the
+       EXACT DISJOINT COMPLEMENT of the mobile `@container chassis (max-width:
+       44.9375rem)` reserve above: 44.9375rem ≈ 719px is the mobile ceiling, so
+       the desktop floor is 45rem ≈ 720px — the two container-query ranges share
+       no width, so a dial cell is reserved by exactly ONE branch at every box
+       width (no overlap, no gap, no competing `min-block-size`).
+
+       The mobile reflow reserves the dial box from frame 0; the wide box axis
+       had NO library reserve, so a `1fr` meter row collapsed to its pre-
+       hydration `<canvas>` intrinsic and grew on hydration, pushing the results
+       card + dock down (the desktop CLS the speedtest App.vue interim authored
+       a local `min-block-size: var(--chassis-max-block-size)` to cure — the
+       consumer interim this rung SUPERSEDES). The reserve is a STATIC
+       `min-block-size` — a frame-0 box reservation, NOT an animated height (no
+       per-frame layout, compositor-safe, `proof:no-layout-animation` holds: a
+       `min-block-size` reserve is never a `@keyframes`/`transition` target).
+
+       Token-first: `--instrument-dial-min-block-size-desktop` is the DESKTOP
+       DIAL a consumer overrides (default `var(--chassis-max-block-size)`, the
+       library's dock-adjusted dynamic-viewport guardrail, resolved at first
+       paint with no JS). The inline `var(--chassis-max-block-size)` fallback
+       carries the contract if the canonical token is unset. */
+    @container chassis (min-width: 45rem) {
+        .instrument-chassis .instrument-dial {
+            min-block-size: var(
+                --instrument-dial-min-block-size-desktop,
+                var(--chassis-max-block-size)
+            );
+        }
+    }
 }

package/src/styles/menu.css

@@ -0,0 +1,127 @@
+/* menu.css — the glass MENU-ROW + MENU-SECTION register (BA.W-MENU-GLASS).
+
+   The shared `menuItemVariants` CVA's `surface=glass` arm (the DEFAULT, glass-
+   first canon AX.W54) composes `.glass-menu-row`; all 13 menu/picker-family SFCs
+   inherit the glassy hover-lift register in ONE edit (no per-SFC menu-row CSS).
+
+   ── The cascade-trap pre-empt (the AZ dock-rail `@layer`-loses-to-utility trap) ──
+   `.interactive-item:hover` (utilities/base.css, `@layer components`) paints a flat
+   `color-mix(--accent 50%)` hover background. An UNLAYERED Tailwind `hover:bg-accent`
+   utility would win over BOTH (the trap). The CVA's glass arm therefore DROPS the
+   flat-accent utilities entirely — so the only background-painters on a glass row are
+   the `@layer components` `.interactive-item:hover` rule and these `.glass-menu-row`
+   rules. This file is `@import`-ed AFTER `utilities.css` in `index.css`, so at equal
+   specificity (0-1-1 for the `:hover`/`[data-highlighted]` selectors) and equal layer
+   (`components`) the recipe wins by SOURCE ORDER over `.interactive-item:hover` —
+   exactly the discipline `glass/surface-axis.css` uses ("@import-ed AFTER ladder.css
+   so the attr rules win by source order"). NEVER re-add an unlayered flat-accent
+   utility to the glass arm — it would re-introduce the trap.
+
+   ── The element-level tint discipline (substitution-vs-inheritance) ──
+   The row reads the ELEMENT-LEVEL glass-quiet oklab tint
+   `color-mix(in oklab, var(--glass-bg-quiet), var(--glass-tint-source) var(--glass-tint-strength))`
+   — the SAME seam `glass/ladder.css:58` / `glass/surfaces.css:19` compose — NOT the
+   pre-baked `--glass-bg-quiet` raw token. So the row darkens-over-light (W55 bright
+   bucket / `--glass-tint-strength` lift) AND lifts-over-dark per W-DARK-MATERIAL's
+   tint arm, in lockstep with every other glass surface. */
+@layer components {
+    /* ── .glass-menu-row — the glassy hover-lift menu/picker item ──────────────
+       Every visual axis reads a `--menu-row-*` knob so a consumer retunes via a
+       `:root` override. The REST state is transparent (the row sits on the
+       container's own `glass-floating` plate — DropdownMenuContent /
+       ContextMenuContent are already `glass-floating rounded-panel`); the glass
+       PLATE materializes on hover/focus/highlight. */
+    .glass-menu-row {
+        /* The glass-quiet plate the row paints AT THE ELEMENT on hover/highlight
+           (the element-level oklab tint — see header). Overridable. */
+        --menu-row-bg: color-mix(
+            in oklab,
+            var(--glass-bg-quiet),
+            var(--glass-tint-source) var(--glass-tint-strength)
+        );
+        /* The PRM-gated hover-lift travel (zeroed under reduce, below). */
+        --menu-row-lift: -1px;
+        /* The 44px WCAG-2.5.5 touch floor (the row never reflows below it). The
+           base is the CVA's own py rhythm; the clamp guarantees the floor. Reads
+           `--touch-target` (the 44px token declared UNCONDITIONALLY at :root —
+           offsets-sizing.css), NOT `--control-floor` (which is declared ONLY inside
+           the `@media (pointer: coarse)` block, so on a FINE pointer `var(--control-
+           floor)` resolves to the guaranteed-invalid initial value → 0px in the
+           max(), and the floor silently vanished — the live π caught the 36px row).
+           The `2.75rem` literal fallback covers a consumer who unsets the token. */
+        min-block-size: max(2rem, var(--touch-target, 2.75rem));
+
+        /* The lift transform rides the §6 spring register (`--spring-smooth`); the
+           surface props (background) ride the bezier `--ease-standard` via the
+           `.interactive-item` base transition (already declared there). The
+           explicit transform leg here pairs the spring with the lift. */
+        transition: translate var(--duration-fast) var(--spring-smooth);
+        translate: 0 0;
+    }
+
+    /* Hover / keyboard-focus / reka internal-highlight / sub-trigger-open all
+       reach the SAME glass register (Combobox/Command/Select parity — the CVA
+       routes all three input modes through `data-[highlighted]`). */
+    .glass-menu-row:hover:not([data-disabled]),
+    .glass-menu-row:focus:not([data-disabled]),
+    .glass-menu-row[data-highlighted]:not([data-disabled]),
+    .glass-menu-row[data-state="open"]:not([data-disabled]) {
+        background: var(--menu-row-bg);
+        color: var(--accent-foreground);
+        translate: 0 var(--menu-row-lift);
+    }
+
+    /* ── .glass-menu-section — the mono section-label + hairline row-group ──────
+       The "section caption + hairline over a row group" recipe (the slides gear
+       hand-built ~120 lines of). Folds onto `typography.css` `.section-label` (the
+       mono / √φ-caption / small-caps register) for the caption and `--border-
+       hairline` for the divider. Tokenized on `--menu-section-*` so a consumer
+       retunes via a `:root` override. ≥2 consumers: the library menu defaults
+       (the section caption a DropdownMenuLabel composes) + the in-repo demo menu
+       story (Unit 2 adoption); the slides DeckSettings is the named foreign
+       downstream consumer. */
+    .glass-menu-section {
+        /* The caption register (mono / small-caps / quiet ink) — the same
+           vocabulary `.section-label` carries, exposed as overridable knobs. */
+        --menu-section-font: var(--font-mono);
+        --menu-section-size: var(--type-caption);
+        --menu-section-color: var(--muted-foreground);
+        --menu-section-tracking: var(--type-tracking-caps);
+        /* The hairline divider over the group (the catch-light + under-shadow
+           pair). Default-off feather; the rule below paints it. */
+        --menu-section-hairline: var(--border-hairline);
+        /* The block rhythm above the group (a section is a deliberate break). */
+        --menu-section-gap: 0.375rem;
+
+        display: block;
+        margin-block-start: var(--menu-section-gap);
+        padding-block-start: var(--menu-section-gap);
+        /* The hairline reads as a top divider over the group via box-shadow (the
+           house hairline pattern — a whisper, not a hard 1px rule). */
+        box-shadow: var(--menu-section-hairline);
+    }
+
+    /* The section CAPTION — a mono small-caps label. Composes onto the label
+       element the section recipe wraps (or a nested `.glass-menu-section-label`);
+       the demo + library menu labels read this caption register. */
+    .glass-menu-section-label,
+    .glass-menu-section > [data-menu-section-label] {
+        font-family: var(--menu-section-font);
+        font-size: var(--menu-section-size);
+        color: var(--menu-section-color);
+        text-transform: uppercase;
+        letter-spacing: var(--menu-section-tracking);
+    }
+}
+
+/* ── PRM gate — no deform/lift under reduce ───────────────────────────────────
+   The hover-lift `translate` is the only motion the row introduces; under
+   `prefers-reduced-motion: reduce` it collapses to the identity (0) and the
+   transition is removed (the surface bg cross-fade is not motion). The glass
+   plate still materializes on hover — only the geometric lift is suppressed. */
+@media (prefers-reduced-motion: reduce) {
+    .glass-menu-row {
+        --menu-row-lift: 0px;
+        transition: none;
+    }
+}

package/src/styles/scroll-choreography.css

@@ -0,0 +1,300 @@
+/*
+ * scroll-choreography.css — the SOTA scroll-driven CHOREOGRAPHY register
+ * (BB.W-SCROLL-MOTION).
+ *
+ * Cascade rung AFTER scroll-driven.css. glass-ui owns the native scroll-driven
+ * SUBSTRATE (scroll-driven.css `scroll()`/`view()` + the `--demo-main-progress`
+ * named timeline + the `supportsCssTimeline` harden) but composes none of the
+ * CHOREOGRAPHY — the page-load BUILD, the section CASCADE, the scroll-PINNED
+ * fixed-stage-advances-time reveals + the smooth-scroll register. The award-winners
+ * hand-roll these on Lenis+GSAP (a 20-40KB JS dependency); glass-ui ships the
+ * NATIVE register — the platform now ships `scroll()`/`view()`/`timeline-scope`
+ * natively, off the compositor at 60fps (the no-net-dep fence; the 2026
+ * universal-support convergence). NO Lenis/GSAP/Locomotive dependency, ever.
+ *
+ *   .scroll-build   — the route-enter page-build (chrome -> hero -> body, a
+ *                     spring-clocked coupled-fade, @keyframes-on-mount [NOT a
+ *                     scroll timeline — the build fires on mount], PRM-snapped).
+ *   .scroll-cascade — the orchestrated section cascade (per-child view() timeline,
+ *                     the implicit stagger [NO setTimeout], the spring-clocked
+ *                     coupled transform+opacity build).
+ *   .scroll-pin     — the fixed-stage-advances-time scroll-pinned register
+ *                     (position: sticky stage + a named scroll-timeline linked via
+ *                     timeline-scope; the stage's internal phases advance with
+ *                     scroll progress, compositor channels only).
+ *   .smooth-scroll  — the native scroll-behavior: smooth opt-in (PRM-gated,
+ *                     zero runtime — a smooth-scroll under reduce is a vestibular
+ *                     concern, so the smooth interpolation is dropped under PRM).
+ *
+ * THE DISCIPLINE (mirrors scroll-driven.css EXACTLY — the exemplary outer-gate):
+ * the whole register sits under `@media (prefers-reduced-motion: no-preference)`
+ * so under PRM no scroll/build animation attaches at all and content renders in
+ * its terminal state (the `from` keyframe never applies because the animation
+ * never binds; the .scroll-pin stage shows its terminal phase, no sweep). The
+ * scroll-driven recipes sit under a second `@supports (animation-timeline: …)`
+ * gate so a non-supporting engine gets the STATIC layout (the .scroll-pin stage
+ * is a correct non-pinned read, never a broken silent stage).
+ *
+ * COMPOSITOR-ONLY (the proof:no-layout-animation floor BB.W-CARD-COMPOSITE): every
+ * @keyframes step + transition animates ONLY transform/translate/scale/opacity/
+ * clip-path — NEVER a layout-triggering property (no height/padding/inline-size/
+ * top/grid-template). The SPATIAL (transform) legs ride the per-spring `--spring-*`
+ * + the matching `--spring-*-duration` settle clock (P2/P4); the EFFECTS (opacity)
+ * legs ride the no-overshoot `--ease-out` bezier (P1/P3 — a fade must never
+ * overshoot). The spring tokens are READ-ONLY (the W-GLASS-CAL clock fence — this
+ * register THREADS them, it never re-tunes a spring value or a duration).
+ */
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * .scroll-build — the route-enter page-build.
+ *
+ * A MOUNT-driven entrance (route-enter), NOT a scroll-driven one — so it rides a
+ * plain `@keyframes ... animation` (NOT a `view()`/`scroll()` timeline; the build
+ * fires on first paint of the new route, not on scroll). It sits under the PRM
+ * no-preference gate ALONE (no `@supports (animation-timeline)` — it does not use a
+ * timeline, so it runs on every engine; under PRM it never binds, so the page
+ * mounts at its terminal state).
+ *
+ * The coordinated stagger: the .scroll-build container's direct children are the
+ * BEATS (chrome, hero, body), each delayed by `--scroll-build-step * --i` (the
+ * per-beat coordinated stagger — the page assembles chrome-first, then the hero,
+ * then the first section). `--i` is the beat index a consumer sets per child
+ * (0-based); the chassis sets it on the chrome/hero/section in reading order
+ * (W-HIERARCHY2 owns the ORDER; this register threads the entrance ON it).
+ * ─────────────────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+    @keyframes gl-page-build {
+        from {
+            opacity: 0;
+            /* SPATIAL leg — the build rise (a transform, compositor-only). */
+            transform: translateY(var(--scroll-build-rise, 1.5rem));
+        }
+        to {
+            opacity: 1;
+            transform: translateY(0);
+        }
+    }
+
+    /* The page-build container marks the entrance; the beats are its children. */
+    .scroll-build > * {
+        /* The coupled build: the SPATIAL transform rides the snappy spring settle
+           clock (P2/P4 — the page parts arrive with crisp gravity); the opacity is
+           a coupled leg in the SAME keyframe on the SAME clock so the fade tracks
+           the rise as ONE coherent glide (P3 — fade coupled to transform). The
+           no-overshoot bezier governs the FADE channel where the spring's
+           overshoot is not wanted: `--ease-out` is named on the build's title beat
+           (the hero <h1> — audacious type arrives with GRAVITY, not bounce, per
+           W-HIERARCHY2); the other beats ride the snappy spring. */
+        animation: gl-page-build var(--spring-snappy-duration, 0.34s)
+            var(--spring-snappy) both;
+        animation-delay: calc(var(--scroll-build-step, 90ms) * var(--i, 0));
+    }
+
+    /* The hero/title beat: the audacious-type-arrives-with-gravity register — the
+       no-overshoot `--ease-out` bezier (a strictly monotone settle, NO overshoot
+       past the terminal transform), the existing .story-hero-title--enter
+       discipline folded into the ONE entrance system. A consumer marks the hero
+       beat `.scroll-build-hero`. */
+    .scroll-build > .scroll-build-hero {
+        animation: gl-page-build 0.62s var(--ease-out, ease-out) both;
+    }
+}
+
+/* The EXPLICIT P6 carve — under prefers-reduced-motion: reduce the page-build DROPS
+   the spatial transform (no movement — the vestibular floor) but KEEPS a gentle
+   terminal fade-in (the EFFECTS channel survives per P6: fade-keeps, transform-
+   drops). This sits OUTSIDE the no-preference gate as the reduce-arm of the
+   coordinated build (mirroring the transitions.css fade-slide PRM arm — the
+   opacity leg alone under reduce). The build is mount-driven, so the no-preference
+   gate above never binds under reduce; this arm gives PRM users the coupled-FADE
+   terminal entrance with ZERO motion frames (no translateY), the genuine P6 read. */
+@media (prefers-reduced-motion: reduce) {
+    @keyframes gl-page-build-fade {
+        from {
+            opacity: 0;
+        }
+        to {
+            opacity: 1;
+        }
+    }
+    .scroll-build > * {
+        /* fade-keeps (opacity only), transform-DROPS (no translateY) — P6. */
+        animation: gl-page-build-fade var(--duration-fast, 0.16s) var(--ease-out, ease-out)
+            both;
+        animation-delay: 0s; /* no coordinated stagger under reduce — a single calm paint */
+    }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * .scroll-cascade — the orchestrated section cascade.
+ *
+ * Extends the bare `[data-scroll-reveal] > *` 6px fade into the SOTA coordinated
+ * build: the per-child `view()` timeline stays the implicit-stagger mechanism (each
+ * child owns its own timeline — NO setTimeout cascade), but the entrance is the
+ * spring-clocked coupled build (a deeper rise + a tighter reveal window). It sits
+ * under the PRM no-preference gate + the `@supports (animation-timeline: view())`
+ * gate (the scroll-driven.css discipline) — under PRM/non-support the sections
+ * render at their terminal state.
+ * ─────────────────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+    @supports ((animation-timeline: view()) and (animation-range: entry)) {
+        @keyframes gl-cascade-build {
+            from {
+                /* EFFECTS leg — the coupled fade (no overshoot). */
+                opacity: 0;
+                /* SPATIAL leg — the build rise (a transform, compositor-only). */
+                transform: translateY(var(--scroll-cascade-rise, 1.25rem));
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0);
+            }
+        }
+
+        .scroll-cascade > * {
+            /* The view()-timeline drives the build off each child's OWN entry into
+               the viewport (the implicit stagger). The progress-bound timeline maps
+               the entrance across the `animation-range` window; the keyframe's
+               coupled transform+opacity build is the orchestrated cascade (vs the
+               bare 6px reveal). `linear` is the right easing for a SCROLL-bound
+               progress map (the spring shaping lives in the section's own settle
+               where the build is mount-driven; a scroll-bound timeline reads
+               1:1 with scroll position — a spring on a scrubbed timeline reads as
+               a scrubbed spring, which is correct here as the linear progress map). */
+            animation: gl-cascade-build auto linear both;
+            animation-timeline: view(block);
+            animation-range: entry 0% entry var(--scroll-cascade-range-end, 45%);
+        }
+
+        /* The horizontal-scroller variant — a `view(inline)` axis. */
+        .scroll-cascade.scroll-cascade--inline > * {
+            animation-timeline: view(inline);
+        }
+
+        /* The OPT-IN column-stagger variant (the Codrops nuance — even columns
+           from top, odd from below). A GRID-surface flourish, NOT the default (the
+           proportion fence: a uniform vertical cascade is the calm StoryPage
+           default; the column-stagger is the front-door grid showcase). A consumer
+           sets `--col` (the column index) per child; even/odd rise from opposite
+           directions, offset by `--scroll-cascade-column-stagger`. */
+        @keyframes gl-cascade-build-col-even {
+            from {
+                opacity: 0;
+                transform: translateY(calc(-1 * var(--scroll-cascade-rise, 1.25rem)));
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0);
+            }
+        }
+        .scroll-cascade.scroll-cascade--columns > * {
+            animation-range: entry 0%
+                entry
+                calc(
+                    var(--scroll-cascade-range-end, 45%) +
+                        var(--scroll-cascade-column-stagger, 60ms) * 0
+                );
+        }
+        .scroll-cascade.scroll-cascade--columns > *:nth-child(even) {
+            animation-name: gl-cascade-build-col-even;
+        }
+    }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * .scroll-pin — the fixed-stage-advances-time scroll-pinned register.
+ *
+ * The SOTA "scrolling does not move the scene, it advances time inside it" model:
+ * a `.scroll-pin` tall container (the `--scroll-pin-stage-height` temporal space)
+ * holds a `.scroll-pin-stage` `position: sticky` element. The container declares
+ * a named `scroll-timeline`; the stage's internal phase animations bind to that
+ * named timeline via `timeline-scope` (so the stage animates against the
+ * CONTAINER'S scroll progress — the fixed stage advances time). The phase
+ * animations are compositor-only (transform/opacity/clip-path over the
+ * `animation-range` phase windows — the Codrops phased sequence: a reveal phase
+ * 0..45%, an expand phase 45..90%, a settle phase 90..100%).
+ *
+ * `timeline-scope` is the newest primitive — the `@supports` gate probes it (NOT
+ * just `scroll()`), so an engine with `scroll()`/`view()` but not `timeline-scope`
+ * gets the STATIC layout (a correct non-pinned read: the stage is a plain sticky
+ * element at its terminal phase, never a broken silent stage). In 2026
+ * `timeline-scope` ships alongside `scroll()`/`view()` (the universal-support
+ * convergence), so the CSS-only register is the ship; the JS fallback leaf (mirror
+ * useScrollProgress's dual-path single-writer) is BOOKED only on a material
+ * engine-gap reveal (the §Triumvirate support-matrix trigger) — never a JS scroll
+ * lib (the no-net-dep fence is binding either way).
+ * ─────────────────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: scroll()) and (timeline-scope: --gl-pin) {
+        @keyframes gl-pin-reveal {
+            from {
+                opacity: 0;
+                transform: translateY(var(--scroll-pin-lift, 2.5rem)) scale(0.96);
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0) scale(1);
+            }
+        }
+        @keyframes gl-pin-settle {
+            from {
+                transform: scale(1);
+                opacity: 1;
+            }
+            to {
+                /* The settle phase — a gentle compositor drift, never a layout move. */
+                transform: scale(1.02) translateY(calc(-1 * var(--scroll-pin-lift, 2.5rem)));
+                opacity: 1;
+            }
+        }
+
+        /* The tall temporal container declares a named scroll-timeline + exposes it
+           to descendants via timeline-scope (the fixed-stage-advances-time link). */
+        .scroll-pin {
+            position: relative;
+            block-size: var(--scroll-pin-stage-height, 320vh);
+            scroll-timeline-name: --gl-pin;
+            scroll-timeline-axis: block;
+            timeline-scope: --gl-pin;
+        }
+
+        /* The sticky stage — pinned to the viewport while the container scrolls
+           past; its phases advance against the container's --gl-pin timeline. */
+        .scroll-pin-stage {
+            position: sticky;
+            inset-block-start: 0;
+        }
+
+        /* Phase 1 — the reveal (0..45% of the container scroll). */
+        .scroll-pin-stage .scroll-pin-phase-reveal {
+            animation: gl-pin-reveal auto linear both;
+            animation-timeline: --gl-pin;
+            animation-range: 0% var(--scroll-pin-phase-reveal-end, 45%);
+        }
+
+        /* Phase 2 — the settle/expand (the reveal-end..expand-end window). */
+        .scroll-pin-stage .scroll-pin-phase-settle {
+            animation: gl-pin-settle auto linear both;
+            animation-timeline: --gl-pin;
+            animation-range: var(--scroll-pin-phase-reveal-end, 45%)
+                var(--scroll-pin-phase-expand-end, 90%);
+        }
+    }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * .smooth-scroll — the native smooth-scroll opt-in.
+ *
+ * The native `scroll-behavior: smooth` (CSS-first, zero runtime — NOT a JS rAF
+ * momentum loop, which IS Lenis and is the fence). An OPT-IN class the scroller
+ * (`<main>`, a `.scroll-pin` container) applies. PRM-GATED: under
+ * `prefers-reduced-motion: reduce` the smooth interpolation is DROPPED and the
+ * jump-scroll is correct (a smooth-scroll over an anchor-jump is a vestibular
+ * concern). A consumer wanting Lenis-grade momentum brings it in THEIR app (the
+ * presets-in-consumers discipline); the library ships the native register.
+ * ─────────────────────────────────────────────────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+    .smooth-scroll {
+        scroll-behavior: smooth;
+    }
+}