@mkbabb/glass-ui 4.0.1 → 4.2.0

package/dist/styles/scroll-choreography.css

@@ -19,9 +19,11 @@
  *                     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).
+ *                     (position: sticky stage; the stage's internal phases advance
+ *                     against a spring-damped `--pin-t` the keyframes.js scroll spine
+ *                     `useScrollPin` writes per scroll tick — EVERY engine, no
+ *                     `animation-timeline`. The dead `--gl-pin` named scroll-timeline
+ *                     is EXCISED — BD.W-SCROLL-LIQUID-ENGINE).
  *   .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).
@@ -31,9 +33,10 @@
  * 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).
+ * `view()`-cascade recipe sits under a second `@supports (animation-timeline: …)`
+ * gate so a non-supporting engine gets the STATIC cascade layout. The .scroll-pin
+ * register needs NO `@supports` gate — its `--pin-t` is JS-written by `useScrollPin`
+ * on every engine; under PRM the composable zeroes the scrub (1:1, no drift).
  *
  * COMPOSITOR-ONLY (the proof:no-layout-animation floor BB.W-CARD-COMPOSITE): every
  * @keyframes step + transition animates ONLY transform/translate/scale/opacity/
@@ -45,6 +48,39 @@
  * register THREADS them, it never re-tunes a spring value or a duration).
  */
 
+/* ─────────────────────────────────────────────────────────────────────────────
+ * BD.W-SCROLL-LIQUID-ENGINE — the liquid-weight scroll tokens.
+ *
+ * The `--ease-scroll-spring` is the compositor spring-scrub the cascade rides
+ * (ZERO JS). The pin-phase fractions are the calc-friendly window bounds the
+ * `--pin-t` recipes read (a NUMBER, not the `%` the dead `animation-range` used).
+ * All golden-proportioned (1/φ family). The liquid-weight scrub itself is a JS-side
+ * param of `useScrollScene`/`useScrollPin` (the φ-derived defaults live in the
+ * composables, PRM → 0 inside them). The cartoon-punch deps
+ * (`--motion-weight`/`--ease-cartoon-punch`/`--shadow-cartoon-md`) SHIP today and are
+ * consumed via `var(…, fallback)` so the recipes stay GREEN. */
+:root {
+    /* The spring-shaped compositor cascade ease — the `--spring-gentle` twin
+       (ζ ≈ 0.85, a `springLinearStops` `linear()` stop-set). Degrades to the
+       no-overshoot `--ease-out` where `linear()` is unsupported (Safari < 17.2 —
+       the house precedent). `--spring-gentle` SHIPS (scheme-motion.css). */
+    --ease-scroll-spring: var(--spring-gentle, var(--ease-out, ease-out));
+    /* The pin reveal/expand windows as 0..1 fractions (the `--pin-t` recipes read
+       a NUMBER for the calc, not the `%` the dead timeline used). 1/φ² + 0.9. */
+    --scroll-pin-phase-reveal-end-frac: 0.382;
+    --scroll-pin-phase-expand-end-frac: 0.9;
+    /* The volume-preserving squash depth — 1 − 1/φ⁴. */
+    --scroll-pin-squash-floor: 0.944;
+}
+
+@supports not (animation-timing-function: linear(0, 1)) {
+    :root {
+        /* Where `linear()` is unsupported the spring twin cannot resolve — fall to
+           the no-overshoot settle bezier (a scrubbed spring without the stop-set). */
+        --ease-scroll-spring: var(--ease-out, ease-out);
+    }
+}
+
 /* ─────────────────────────────────────────────────────────────────────────────
  * .scroll-build — the route-enter page-build.
  *
@@ -160,8 +196,15 @@
                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;
+               a scrubbed spring, which is correct here as the linear progress map).
+
+               BD.W-SCROLL-LIQUID-ENGINE: the easing is the spring-shaped
+               `--ease-scroll-spring` (a `springLinearStops` `linear()` twin of
+               `--spring-gentle`, ζ ≈ 0.85) — each card's scroll-scrubbed entrance
+               reads with spring WEIGHT (a hair of overshoot at the end of its
+               range), ZERO JS (the platform carries it on the compositor). The
+               Safari-degrade-to-cel-slam arm lives in the entrance-reveal scope. */
+            animation: gl-cascade-build auto var(--ease-scroll-spring, linear) both;
             animation-timeline: view(block);
             animation-range: entry 0% entry var(--scroll-cascade-range-end, 45%);
         }
@@ -202,83 +245,97 @@
 }
 
 /* ─────────────────────────────────────────────────────────────────────────────
- * .scroll-pin — the fixed-stage-advances-time scroll-pinned register.
+ * .scroll-pin — the fixed-stage-advances-time scroll-pinned register, RE-INVENTED
+ * on a JS-written `--pin-t` (BD.W-SCROLL-LIQUID-ENGINE).
+ *
+ * THE DEFECT (excised, no alias): the prior register bound the phase reveals to a
+ * named `scroll-timeline: --gl-pin` declared on `.scroll-pin` + `timeline-scope:
+ * --gl-pin`. A named scroll-timeline measures the DECLARING element's OWN scroll
+ * progress — but `.scroll-pin` is `overflow: visible` with zero internal scroll
+ * extent, so it is NOT a scroll port: `--gl-pin`'s `currentTime` was permanently
+ * `null` and the bound `gl-pin-reveal` animation parked at its `from` keyframe
+ * forever (dead on EVERY engine, including those that fully support the native
+ * feature — structural deadness, not a Safari degrade).
  *
- * 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%).
+ * THE FIX (every engine, no `animation-timeline`, no `@supports` gate): the stage
+ * is plain `position: sticky` + `contain: layout paint` (bounded recalc); the
+ * phases read a SPRING-DAMPED `--pin-t ∈ [0, 1]` that `useScrollPin` (the
+ * keyframes.js scroll spine — `SpringProgress` over the ONE `createScrollReader`)
+ * writes off the REAL scroll port per coalesced tick. The reveal arrives with
+ * inertia, overshoots (ζ ≈ 0.85), then settles — the cartoon-slam felt register.
+ * Works on Safari 15+ with no timeline primitive.
  *
- * `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).
+ * Liquid weight is the DEFAULT here (the §L4 no-stiff-snap law): `useScrollPin`'s
+ * `SpringProgress` keeps converging AFTER the finger lifts. PRM zeroes the scrub
+ * (the pin scrub → 0 under reduce inside the composable) so `--pin-t` tracks
+ * scroll 1:1 with no interpolated drift — the vestibular floor.
  * ─────────────────────────────────────────────────────────────────────────── */
-@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 typed pin progress register — `inherits: true` so the sticky stage + the
+   phase children read the `--pin-t` written on the `.scroll-pin` container; a typed
+   `@property` makes the calc cheaper + lets an optional native cosmetic-parallax leg
+   composite it. Registered OUTSIDE the PRM gate (a custom property is inert — it only
+   drives motion through the recipes below, which ARE PRM-gated). */
+@property --pin-t {
+    syntax: "<number>";
+    inherits: true;
+    initial-value: 0;
+}
 
-        /* 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;
-        }
+.scroll-pin {
+    position: relative;
+    block-size: var(--scroll-pin-stage-height, 320vh);
+}
 
-        /* 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%);
-        }
+.scroll-pin-stage {
+    position: sticky;
+    inset-block-start: 0;
+    /* Bounded main-thread recalc — the `--pin-t` write is a style recalc on this
+       isolated subtree, NOT a reflow (translate/scale/opacity don't reflow). */
+    contain: layout paint;
+}
 
-        /* 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%);
-        }
+@media (prefers-reduced-motion: no-preference) {
+    /* Phase 1 — the reveal. Reads `--pin-t` mapped across the reveal window
+       (0 .. --scroll-pin-phase-reveal-end-frac). The lift + squash ride the
+       compositor longhands (`translate`/`scale` — NEVER the `transform` shorthand,
+       which would fold a centering translate; the longhands stack independently).
+       The squash floor is volume-preserving (a hair of squash on entry). */
+    .scroll-pin-stage .scroll-pin-phase-reveal {
+        --t: clamp(
+            0,
+            calc(var(--pin-t, 0) / var(--scroll-pin-phase-reveal-end-frac, 0.382)),
+            1
+        );
+        opacity: var(--t);
+        translate: 0 calc((1 - var(--t)) * var(--scroll-pin-lift, 2.5rem));
+        scale: calc(
+            var(--scroll-pin-squash-floor, 0.944) +
+                (1 - var(--scroll-pin-squash-floor, 0.944)) * var(--t)
+        );
+        /* will-change scoped to the active phase — added while the pin is in range,
+           never the full 320vh lifetime (the audit's transient-promotion rule). */
+        will-change: transform, opacity;
+    }
+
+    /* Phase 2 — the settle/drift. Reads the reveal-end..expand-end window of
+       `--pin-t`; a gentle compositor drift as the reader continues past, never a
+       layout move. */
+    .scroll-pin-stage .scroll-pin-phase-settle {
+        --t: clamp(
+            0,
+            calc(
+                (var(--pin-t, 0) - var(--scroll-pin-phase-reveal-end-frac, 0.382)) /
+                    (
+                        var(--scroll-pin-phase-expand-end-frac, 0.9) -
+                            var(--scroll-pin-phase-reveal-end-frac, 0.382)
+                    )
+            ),
+            1
+        );
+        opacity: 1;
+        translate: 0 calc(var(--t) * -1 * var(--scroll-pin-lift, 2.5rem));
+        scale: calc(1 + 0.02 * var(--t));
     }
 }
 

package/dist/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/dist/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;
+    }
+}