@mkbabb/glass-ui 4.0.0 → 4.1.0

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;
+    }
+}

package/src/styles/scroll-chrome.css

@@ -0,0 +1,123 @@
+/*
+ * scroll-chrome.css — the scroll-driven floating-CHROME collapse recipe
+ * (BC.W-SCROLL-CHROME).
+ *
+ * Cascade rung AFTER scroll-choreography.css. Where scroll-choreography.css is the
+ * ENTRANCE register (the page-build / section-cascade / scroll-pinned reveals), this is
+ * the COLLAPSE-STATE recipe a floating chrome bar (a dock, a header) composes: scroll
+ * down and it SHRINKS smoothly into a compact form; scroll up and it EXPANDS back; on
+ * scroll-stop it SNAPS to the nearest state (the `useScrollChrome` JS machine owns the
+ * snap + the ramp value — this recipe is the compositor paint of `--chrome-collapse-t`).
+ *
+ *   .scroll-chrome — the chrome surface (a dock/header) reads `--chrome-collapse-t`
+ *                    (0 expanded → 1 collapsed; the @property reg in property-regs.css)
+ *                    for the COMPOSITOR shrink/quiet/shadow-lift ramp.
+ *
+ * COMPOSITOR-ONLY (the proof:no-layout-animation floor — motion-canon P5). The shrink is
+ * `transform: scale()/translateY()` — NEVER an animated `height`/`padding`/`width` (the
+ * box never reflows per scroll frame; the CDP Layout track stays flat). The quiet is
+ * `opacity` BOUNDED above a never-invisible floor (the NN/g pale-fade-into-content trap
+ * is the FORBIDDEN direction — the bar reads at EVERY collapse fraction). The
+ * SEPARATION/shadow LIFTS as content scrolls under (Apple "as text scrolls underneath,
+ * shadows become more prominent") — `box-shadow` is a paint prop, compositor-safe.
+ *
+ * THE BLUR STAYS CRISP (the W-DOCK-SHRINK-BLUR fence). The chrome's resting
+ * `backdrop-filter` blur is NOT animated by `--chrome-collapse-t` — a shrunken bar is
+ * crisp glass, not a blurry mess. The recipe touches ONLY transform/opacity/box-shadow;
+ * the surface's own `glass-*` tier owns the (untouched) backdrop blur.
+ *
+ * PERSISTENT BY DEFAULT (the iOS-27 lesson). `--chrome-collapse-t` rests at 0 (the
+ * @property initial-value), so a bare `.scroll-chrome` is byte-identical to the expanded
+ * chrome — it does NOT collapse until the `useScrollChrome` machine (opted in with
+ * `collapseOnScroll: true`) ramps the custom.
+ *
+ * PRM (the discrete-state-survives model, the useFadingScroll precedent). The transform/
+ * opacity RAMP sits inside the `@media (prefers-reduced-motion: no-preference)` outer
+ * gate (the scroll-choreography.css discipline) — under reduce the continuous ramp drops;
+ * the `useScrollChrome` machine snaps `--chrome-collapse-t` to a discrete 0/1 endpoint, so
+ * the DISCRETE collapsed/expanded state stays correct, instant, never half. The shadow
+ * lift sits OUTSIDE the gate (a paint cue, not a vestibular motion) so the lifted
+ * separation reads even under reduce.
+ */
+
+/* The tunable depth knobs — a consumer retunes the shrink/fade depth per chrome. */
+:root {
+    /* The shrink depth: at fully collapsed the chrome scales to (1 − this). 0.12 → a
+       compact 88% bar (a real shrink that still reads as the same bar). */
+    --chrome-shrink-depth: 0.12;
+    /* The rise (px) the chrome translates toward its anchor edge as it collapses. */
+    --chrome-rise-px: 6px;
+    /* The fade depth — BOUNDED LOW: at fully collapsed opacity floors at (1 − this).
+       0.28 → a 0.72 floor (the bar quiets but is NEVER invisible — the NN/g pale-fade
+       trap forbidden). A consumer that wants no quiet sets it 0. */
+    --chrome-fade-depth: 0.28;
+    /* The shadow-lift strength — the separation shadow grows from rest → this as content
+       scrolls under (Apple shadow-on-scroll). A paint prop, compositor-safe. */
+    --chrome-shadow-lift: 18%;
+}
+
+/* The shrink/quiet RAMP — the SPATIAL (transform) + the EFFECTS (opacity) channels. It
+   rides `--chrome-collapse-t` directly (no CSS transition — the JS scalar already glides
+   on the reader's tick; on a native-timeline engine the same custom rides
+   `animation-timeline: scroll(self)`, the native-ramp path). Inside the PRM no-preference
+   gate: under reduce the ramp drops and the chrome reads its discrete snapped endpoint. */
+@media (prefers-reduced-motion: no-preference) {
+    .scroll-chrome {
+        /* SPATIAL leg — scale toward the compact size + a small rise toward the anchor
+           edge. transform-origin at the top (a header anchors its top; a consumer dock
+           re-points the origin to its natural seat). Compositor-only — never height/pad. */
+        transform: scale(calc(1 - var(--chrome-collapse-t) * var(--chrome-shrink-depth)))
+            translateY(calc(var(--chrome-collapse-t) * var(--chrome-rise-px) * -1));
+        transform-origin: top center;
+        /* EFFECTS leg — the quiet, BOUNDED above the never-invisible floor (the bar reads
+           at every fraction; the `* fade-depth` caps the drop, opacity never reaches 0). */
+        opacity: calc(1 - var(--chrome-collapse-t) * var(--chrome-fade-depth));
+        /* will-change the compositor channels (NEVER a layout property). */
+        will-change: transform, opacity;
+    }
+}
+
+/* The shadow LIFT — OUTSIDE the PRM gate (a paint cue, not a vestibular motion): the
+   separation shadow strengthens as content scrolls under the chrome. `box-shadow` is a
+   paint prop (compositor-safe, in the proof:no-layout-animation paint set, NOT the reflow
+   set). The lift composes the house `--shadow-color: var(--foreground)` so it re-tints
+   light↔dark for free; the strength grows from a whisper at rest → `--chrome-shadow-lift`
+   at fully collapsed. */
+.scroll-chrome {
+    box-shadow: 0 calc(2px + var(--chrome-collapse-t) * 6px)
+        calc(8px + var(--chrome-collapse-t) * 12px)
+        color-mix(
+            in srgb,
+            var(--shadow-color)
+                calc(6% + var(--chrome-collapse-t) * var(--chrome-shadow-lift)),
+            transparent
+        );
+}
+
+/* The native-ramp path — on a `scroll()`-supporting engine the consumer can drive
+   `--chrome-collapse-t` off `animation-timeline: scroll(self)` directly (the
+   `useScrollProgress`/`--scroll-t` native precedent: the JS writer is inert, the CSS owns
+   the compositor ramp). The keyframe is the linear 0→1 map over the collapse range; the
+   consumer binds it on the chrome with its own `animation-range` (the collapse-px span).
+   The SNAP-to-state stays the JS leg (a snap is a discrete commit, not a continuous ramp —
+   it rides the `useScrollChrome` scroll-stop tick on every engine). PRM-gated + supports-
+   gated (a non-supporting engine reads the JS `collapseT` write, never this keyframe). */
+@media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: scroll()) {
+        @keyframes gl-chrome-collapse {
+            from {
+                --chrome-collapse-t: 0;
+            }
+            to {
+                --chrome-collapse-t: 1;
+            }
+        }
+        /* OPT-IN: a consumer adds `.scroll-chrome--native` to ride the compositor ramp
+           (it must set `animation-range` for its own collapse-px span; the
+           `useScrollChrome` machine's JS write is the cross-engine floor + the snap). */
+        .scroll-chrome--native {
+            animation: gl-chrome-collapse auto linear both;
+            animation-timeline: scroll(self block);
+        }
+    }
+}

package/src/styles/scroll-driven.css

@@ -70,3 +70,41 @@
         }
     }
 }
+
+/* ── ONCE latch (the virtualized/teleporting opt-in) — BC.W-MOTION-PRESETS.
+ * The continuous `[data-scroll-reveal]` recipe above re-fires its entrance EVERY
+ * time a child re-enters the entry range — correct for a calm cascade, WRONG for
+ * a virtualized/teleporting list where a row scrolls out + back (it re-plays the
+ * fade-lift). A native `view()` timeline cannot latch "play once" (the CSS limit),
+ * so `[data-scroll-reveal-once]` swaps the live-range animation for a one-shot
+ * `@keyframes` keyed off a `data-revealed` attr a tiny JS-assist IntersectionObserver
+ * sets on FIRST cross + then `unobserve`s — the SHIPPED `useStaggerReveal` `once`
+ * machinery (its `if (once) observer?.unobserve(el)` leg), reused, not re-authored.
+ *
+ * SINGLE WRITER — an element is `[data-scroll-reveal]` XOR `[data-scroll-reveal-once]`
+ * (never both): the continuous path rides the `view()` timeline, the once path rides
+ * the `[data-revealed]` attr. They never both drive the same child.
+ *
+ * The keyframe is the SAME fade-lift values as `gl-reveal-in` but runs FORWARD
+ * (`from` hidden → `to` shown) so the terminal state holds without a timeline; the
+ * `--spring-gentle` partial-sum settle is the convergence-reveal register a consumer
+ * pairs with `useStagger` for the N-term build-up. Same PRM outer gate as the
+ * continuous recipe (a flourish — under reduce the row paints in-place, no entrance). */
+@media (prefers-reduced-motion: no-preference) {
+    @keyframes gl-reveal-once {
+        from {
+            opacity: 0;
+            transform: translateY(var(--scroll-reveal-rise, 6px));
+        }
+        to {
+            opacity: 1;
+            transform: none;
+        }
+    }
+    [data-scroll-reveal-once] > * {
+        opacity: 0;
+    }
+    [data-scroll-reveal-once] > *[data-revealed] {
+        animation: gl-reveal-once var(--spring-gentle-duration) linear both;
+    }
+}

package/src/styles/segmented-tabs.css

@@ -36,8 +36,15 @@
 /* ── The PILL track (the glass material — DEFAULT) ── */
 .segmented-tabs {
     --bouncy-track-trim: 0.1875rem;
-    --bouncy-track-radius: 0.4375rem;
-    --bouncy-slider-radius: 0.3125rem;
+    /* BC.W-TABS-IOS — the iOS-27 stadium register. The pill reads the role-bearing
+       `--radius-tab` (= --radius-pill = 9999px) — on a short pill box this clamps to
+       half-height → a TRUE stadium end-cap (not the squared `0.3125rem` rounded-rect
+       the HEAD shipped). The TRACK corner is CONCENTRIC with the pill (Apple's
+       `.containerConcentric`): the pill radius + the trim inset, so a stadium pill
+       sits inside a near-stadium track. No breakpoint radius bump — a stadium does
+       not change radius across viewports (clean break, the 640px radius lines gone). */
+    --bouncy-slider-radius: var(--radius-tab);
+    --bouncy-track-radius: calc(var(--bouncy-slider-radius) + var(--bouncy-track-trim));
     /* The travel-squish axis — 1 at rest; useTabIndicator writes it transiently
        on selection, the indicator pairs it volume-preserving. */
     --stretch: 1;
@@ -53,7 +60,13 @@
     background: var(--glass-bg-quiet);
     backdrop-filter: var(--glass-blur-quiet);
     -webkit-backdrop-filter: var(--glass-blur-quiet);
-    box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--border) 24%, transparent);
+    /* BC.W-TABS-IOS — the track hairline re-points off the `--border` ring (which read
+       dark over the cream plate — the D2 "black bar" on the strip top edge) onto the
+       BC.W-BLACK-BAR directional rim register: a bright top catch-light + a faint warm
+       under-shadow. The track is a thin warm-glass quiet capsule with a lit top edge,
+       never a dark hairline. The pill (above) carries the SAME rim plus the lift shadow
+       so it reads FORWARD; the track carries only the rim. */
+    box-shadow: var(--glass-rim-top), var(--glass-rim-bottom);
 }
 
 /* ── The vertical orientation axis (the block stack) ── */
@@ -67,28 +80,40 @@
 
 @media (min-width: 640px) {
     .segmented-tabs {
+        /* BC.W-TABS-IOS — only the trim (pad) axis bumps at the wider breakpoint; the
+           radius is the viewport-invariant stadium (--radius-tab), so the corner
+           track-radius re-resolves concentric off the bigger trim by construction. */
         --bouncy-track-trim: 0.25rem;
-        --bouncy-track-radius: 0.5rem;
-        --bouncy-slider-radius: 0.375rem;
     }
 }
 
 /* ── The shared indicator body (the PILL plate) ── */
 .segmented-indicator {
     position: absolute;
-    /* BA.W-TABS — the active pill indicator rides the glass FLOATING tier (the
-       W-REGISTER-IOS "selected reads as glass" register), reading FORWARD of the
-       quiet-tier track. A glass tint, NEVER a saturated `--foreground` fill or an
-       opaque `bg-card`. */
-    background: var(--glass-bg-floating);
+    /* BC.W-TABS-IOS — the active pill is the iOS-27 / value.js DISTINCT LIFTED PLATE,
+       not a +30%-α same-hue brightness step. The fill reads the SHARED element-level
+       oklab-tinted floating pair (surfaces.css `:where(.btn-glass, .segmented-indicator)`)
+       — over a bright field it darkens-to-legible, over a calm field it stays
+       warm-cream/near-white (the W55 adaptive register reaching the pill, the "raised
+       near-white plate" the user pinned). The FORWARD-ness comes from the rim + lift
+       below, NOT from cranking the same-hue alpha. */
+    background: var(--glass-bg-floating-tinted);
     backdrop-filter: var(--glass-blur-floating);
     -webkit-backdrop-filter: var(--glass-blur-floating);
     z-index: 0;
     inset-block: var(--bouncy-track-trim);
     border-radius: var(--bouncy-slider-radius);
+    /* BC.W-TABS-IOS — the lifted-plate composite: the BC.W-BLACK-BAR directional rim
+       (bright top catch-light `--glass-rim-top` + warm bottom under-shadow
+       `--glass-rim-bottom` — the iOS-27 top-light/bottom-shadow thickness the track does
+       NOT carry, the FORWARD-ness device, NEVER the dark D2 hairline) PLUS a real layered
+       glass under-shadow (`--glass-shadow-floating`) lifting the plate ~2-3px off the
+       quiet track. Replaces the HEAD weak `0 1px 3px rgba(0,0,0,0.08)` + the 30%-border
+       dark ring (the same-hue low-contrast plate that read "not glassy"). */
     box-shadow:
-        0 1px 3px rgba(0, 0, 0, 0.08),
-        0 0 0 1px color-mix(in srgb, var(--border) 30%, transparent);
+        var(--glass-rim-top),
+        var(--glass-rim-bottom),
+        var(--glass-shadow-floating);
     /* The volume-preserving travel-squish: stretch along X, compress Y in
        inverse proportion. `transform-origin: center` → a symmetric width-flex
        as it travels (the indicator grows wider mid-travel, settles to fit). */
@@ -165,8 +190,10 @@
 
 @media (min-width: 640px) {
     .segmented-indicator {
+        /* BC.W-TABS-IOS — only the inset (trim) axis bumps; the radius stays the
+           viewport-invariant stadium (`--bouncy-slider-radius` = --radius-tab). The
+           HEAD `border-radius: 0.375rem` px-literal that squared the pill is GONE. */
         inset-block: 0.25rem;
-        border-radius: 0.375rem;
     }
     .segmented-tabs--vertical .segmented-indicator {
         inset-block: auto;
@@ -322,7 +349,16 @@
 
 .segmented-tabs--underline .segmented-tab {
     padding: 0.375rem 0.75rem;
-    font-size: inherit;
+    /* BC.W-UNDERLINE-TUNE — the audacious editorial label voice. The underline is
+       the PAPER/editorial material (BA.W-TABS), so its labels carry the √φ display
+       register, NOT the small 0.8125rem control size the PILL labels keep (the
+       two-voice fence — the pill is a compact control, the underline is an editorial
+       nav head). `--type-subheading` (1.272rem / 20.4px, the √φ rung) + the Apple
+       display tracking `--type-tracking-display` (−1.5%) are the BB.W-DISPLAY-TRACKING
+       ladder rungs CONSUMED here (never re-minted), the same pairing the semantic
+       display rungs ride. A confident editorial strip, not a default Tailwind row. */
+    font-size: var(--type-subheading);
+    letter-spacing: var(--type-tracking-display);
     border-radius: 0.25rem;
     /* The tab-text colour cross-fade rides the fast generic clock (the §6 doctrine
        — a colour shift is a bezier ease, never a spring), matching the pill tab
@@ -338,3 +374,34 @@
 .segmented-tabs--underline .segmented-tab:hover {
     color: color-mix(in oklab, var(--foreground) 70%, transparent);
 }
+
+/* ════════════════════════════════════════════════════════════════════════
+   BB.W-DRAG-MORPH — the `.glass-drag-lift` decoration (the pull affordance).
+
+   The `useDragMorph` consumer adds this class to the morph element while
+   `dragging` is true (the SegmentedTabs `:draggable` indicator; the
+   DockLayerGroup pull rail). It is the visual "this is grabbable + grabbed"
+   affordance — the GRAB cursor + a sub-perceptual `--glass-specular` catch-light
+   lift + the `will-change: transform` compositor hint that promotes the lozenge
+   to its own layer for the 1:1 follow. It carries NO transform itself (the
+   translate + squish are the primitive's own `translate`/`--stretch` writes, the
+   §6 compositor channels); this class only paints the affordance + the hint.
+
+   The grab cursor sits on the morph element AT REST too (a draggable indicator
+   reads grabbable before the grab), so `.glass-drag-grabbable` marks the rest
+   affordance and `.glass-drag-lift` adds the grabbing state. PRM does not gate
+   the cursor/hint (they are not motion); the lift is a static specular nudge. */
+.glass-drag-grabbable {
+    cursor: grab;
+    touch-action: none;
+}
+
+.glass-drag-lift {
+    cursor: grabbing;
+    /* Promote to its own compositor layer for the 1:1 follow (the translate write
+       is compositor-only; the hint keeps the plate off the main-thread paint). */
+    will-change: transform;
+    /* Sub-perceptual catch-light lift — the grabbed lozenge reads a hair brighter
+       at its specular edge (the W-GLASS-CAL specular register, disco-FREE). */
+    --glass-specular: 0.1;
+}