@polymorphism-tech/morph-spec 8.28.0 → 8.29.0

package/framework/standards/frontend/scroll-driven/frame-scrub.md

@@ -0,0 +1,287 @@
+# Canvas Frame Scrub — Scroll-Driven Video
+
+> **Scope:** frontend-scroll-driven
+> **Layer:** 3
+> **Keywords:** frame-scrub, canvas, scroll-driven video, scrubbing, ffmpeg, apple-style, poster fallback
+> **Load When:** ui-designer active, or the brief says scroll controls a video
+
+**Verified against:** GSAP 3.13 ScrollTrigger + Lenis 1.x + ffmpeg 6.x, shipped to production. Last-verified: 2026-08-21.
+
+---
+
+Reference for building a hero (or any section) where scrolling advances a video frame by frame, drawn into a `<canvas>`. This is the Apple product-page mechanic. It covers why canvas beats `<video>`, frame extraction with ffmpeg, the focal-point cover draw, the resize-on-visible bug, cache busting, the mobile poster fallback, and how to verify the result with motion instead of a still.
+
+---
+
+## Section 1: Canvas, Not `<video currentTime>`
+
+Two failure modes rule out driving a `<video>` element from scroll position:
+
+1. **`<video currentTime>` is unreliable on iOS Safari.** Decode throttling and autoplay restrictions make seeking stutter, and swapping the source can flash a black frame.
+2. **An autoplaying `<video>` is not a scroll animation at all.** It reads as a demo running by itself rather than something the user drives. If the requirement is "scroll controls the video", a looping autoplay video does not satisfy it.
+
+A canvas fed by a preloaded image sequence works cross-browser and never flashes.
+
+A self-playing ambient loop is the exception, not the default: use it only for a secondary background plane, never for the primary hero.
+
+---
+
+## Section 2: Frame Extraction
+
+Extract the approved `.mp4` into a JPG sequence:
+
+```bash
+ffmpeg -i source.mp4 -vf "fps=30,scale=1280:-1" -q:v 5 frames/frame_%03d.jpg
+```
+
+| Knob | Guidance |
+|---|---|
+| Duration and fps | 4 to 10s at 30fps yields roughly 120 to 300 frames. Around 145 is a good balance of smooth and light. |
+| `-q:v` | 5 balances quality against weight. |
+| Numbering | `%03d` (frame_001) matches the 1-based `framePath` contract in Section 4. |
+| Format | JPG is the safe default (fast decode, universal). If the sequence gets heavy (tens of MB), also try WebP via `-c:v libwebp -q:v 70`, which usually cuts total weight at similar quality. |
+
+**Treat total sequence weight as a performance budget.** It shows up directly in Lighthouse. If it is too heavy, cut frame count (120 instead of 145) or resolution before cutting quality.
+
+**Mirror the footage when the subject collides with the copy.** If the subject sits on the side where text goes, flip it during extraction:
+
+```bash
+ffmpeg -i source.mp4 -vf "hflip,fps=30,scale=1664:-1" -q:v 5 frames/frame_%03d.jpg
+```
+
+**Always extract a poster.** Pick a frame with the subject well composed and save it as `poster.jpg`. It backs the mobile and reduced-motion paths.
+
+---
+
+## Section 3: Cache Busting Is Mandatory
+
+Re-extracting frames (for example going from 480p to 1080p) while keeping the same filenames means the browser serves the stale ones and nothing appears to change.
+
+Always version the frame URL and bump `N` on every re-extraction:
+
+```js
+const framePath = (i) => `/hero-frames/frame_${String(i).padStart(3, '0')}.jpg?v=2`
+```
+
+---
+
+## Section 4: The Component
+
+```jsx
+import { useEffect, useRef } from 'react'
+import { gsap, prefersReducedMotion } from '../lib/motion'
+
+/**
+ * props:
+ *   frameCount  number of extracted frames
+ *   framePath   (i) => url for frame i (1-based). ALWAYS cache-busted with ?v=N
+ *   focusX/Y    0..1 focal point preserved when cover-cropping. default 0.5
+ *   poster      static poster url (mobile + reduced-motion + fallback)
+ */
+export default function ScrollScrub({
+  frameCount, framePath, focusX = 0.5, focusY = 0.5,
+  poster, posterAlt = '', className = 'scrub', children,
+}) {
+  const sectionRef = useRef(null)
+  const canvasRef = useRef(null)
+
+  useEffect(() => {
+    // Mobile and reduced-motion never scrub. See Section 6.
+    const smallScreen = typeof window !== 'undefined'
+      && window.matchMedia('(max-width: 860px)').matches
+    if (prefersReducedMotion || smallScreen) return
+
+    const canvas = canvasRef.current
+    const ctx = canvas.getContext('2d')
+    const images = []
+    let loaded = 0, failed = false, current = -1
+    const state = { frame: 0 }
+    const dpr = Math.min(window.devicePixelRatio || 1, 2)
+
+    // Cover with a focal point: keeps the subject visible when the cover crop
+    // eats the edges (16:9 footage in a wide, short viewport).
+    const drawCover = (img, cw, ch) => {
+      const ir = img.width / img.height
+      const cr = cw / ch
+      let dw, dh, dx, dy
+      if (ir > cr) { dh = ch; dw = ch * ir; dy = 0; dx = (cw - dw) * focusX }
+      else { dw = cw; dh = cw / ir; dx = 0; dy = (ch - dh) * focusY }
+      ctx.drawImage(img, dx, dy, dw, dh)
+    }
+
+    const draw = (idx, force) => {
+      const i = Math.max(0, Math.min(frameCount - 1, Math.round(idx)))
+      if (i === current && !force) return
+      current = i
+      const img = images[i]
+      const r = canvas.getBoundingClientRect()
+      if (img && img.complete && img.naturalWidth) drawCover(img, r.width, r.height)
+    }
+
+    const resize = () => {
+      const r = canvas.getBoundingClientRect()
+      canvas.width = Math.max(1, Math.floor(r.width * dpr))
+      canvas.height = Math.max(1, Math.floor(r.height * dpr))
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+      draw(current < 0 ? 0 : current, true)
+    }
+
+    // Preload every frame before scrubbing.
+    for (let i = 0; i < frameCount; i++) {
+      const img = new Image()
+      img.onload = () => {
+        loaded++
+        // See Section 5: resize once the canvas is actually visible.
+        if (loaded === 1) { canvas.style.display = 'block'; resize() }
+      }
+      img.onerror = () => { failed = true }
+      img.src = framePath(i + 1)
+      images[i] = img
+    }
+
+    const ctxGsap = gsap.context(() => {
+      gsap.to(state, {
+        frame: frameCount - 1,
+        ease: 'none',
+        snap: 'frame',
+        scrollTrigger: {
+          trigger: sectionRef.current,
+          start: 'top top', end: 'bottom bottom', scrub: 0.4,
+        },
+        onUpdate: () => { if (!failed) draw(state.frame) },
+      })
+    }, sectionRef)
+
+    window.addEventListener('resize', resize)
+    const t = setTimeout(resize, 60) // first measurement after layout settles
+    return () => {
+      clearTimeout(t)
+      window.removeEventListener('resize', resize)
+      ctxGsap.revert()
+    }
+  }, [])
+
+  return (
+    <section className={className} ref={sectionRef}>
+      <div className={`${className}__sticky`}>
+        <div className={`${className}__fallback`}><img src={poster} alt={posterAlt} /></div>
+        {/* starts hidden so resize-on-visible fires correctly */}
+        <canvas className={`${className}__canvas`} ref={canvasRef} style={{ display: 'none' }} />
+        <div className={`${className}__scrim`} />
+        <div className={`${className}__copy`}>{children}</div>
+      </div>
+    </section>
+  )
+}
+```
+
+Use one instance per scrub section, varying `framePath`, `focusX/focusY` and the overlaid copy.
+
+---
+
+## Section 5: The 1x1 Canvas Bug
+
+**Symptom:** the whole section renders as one stretched color or blur instead of the footage.
+
+**Cause:** if the section starts outside the viewport with `display:none`, the initial resize runs while `getBoundingClientRect()` returns 0. The canvas becomes 1x1 and then draws a single pixel stretched to full size.
+
+**Fix (already in the component):** keep the canvas hidden, and on the first loaded frame set `display:block` and re-run `resize()` with real measurements.
+
+If it reappears, the section is almost certainly being measured while hidden.
+
+---
+
+## Section 6: Responsive and Reduced Motion
+
+**Mobile does not scrub.** Landscape footage crops badly in portrait, and downloading dozens of 1080p frames costs 10 to 25 MB. The section collapses to a static 100vh poster.
+
+```css
+.scrub { position: relative; height: 320vh; }  /* height is the scrub duration */
+.scrub__sticky { position: sticky; top: 0; height: 100vh; overflow: hidden; }
+.scrub__fallback { position: absolute; inset: 0; }
+.scrub__fallback img { width: 100%; height: 100%; object-fit: cover; }
+.scrub__canvas { position: absolute; inset: 0; width: 100%; height: 100%; }
+.scrub__copy { position: relative; z-index: 3; }
+
+@media (max-width: 860px) {
+  .scrub { height: 100vh; }
+  .scrub__sticky { position: relative; }
+  .scrub__canvas { display: none !important; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .scrub { height: 100vh; }
+  .scrub__sticky { position: relative; }
+  .scrub__canvas { display: none !important; }
+}
+```
+
+The JS guard and the CSS guard must agree. The component returns early on the same conditions the media queries cover.
+
+---
+
+## Section 7: Text Beats Over the Scrub
+
+Copy that enters and exits at scroll milestones uses a separate GSAP timeline on the same trigger. Positions are fractions of the timeline (0 to 1):
+
+```js
+const tl = gsap.timeline({
+  scrollTrigger: { trigger: sectionRef.current, start: 'top top', end: 'bottom bottom', scrub: 0.4 },
+})
+// pointerEvents tracks each beat so a beat is never clickable while invisible
+tl.to(beat1Ref.current, { opacity: 0, yPercent: -18, duration: 0.16 }, 0.24)
+tl.set(beat1Ref.current, { pointerEvents: 'none' }, 0.24)
+tl.set(beat2Ref.current, { pointerEvents: 'auto' }, 0.40)
+tl.fromTo(beat2Ref.current, { opacity: 0, yPercent: 18 }, { opacity: 1, yPercent: 0, duration: 0.12 }, 0.40)
+tl.to(beat2Ref.current, { opacity: 0, yPercent: -18, duration: 0.12 }, 0.62)
+tl.set(beat2Ref.current, { pointerEvents: 'none' }, 0.62)
+```
+
+**An invisible beat still swallows clicks.** The beats stack in the same area with `position: absolute` and differ only by opacity, so without `pointer-events` the beat that sits last in the DOM wins the hit test even at `opacity: 0`. The visible beat renders fine and its CTA is simply dead. Set the resting state in CSS as well, so the first paint is correct before the timeline runs:
+
+```css
+.hero-beat--2, .hero-beat--3 { opacity: 0; pointer-events: none; }
+```
+
+**Check what else is `position: fixed` over the hero.** A cookie banner or a floating bar at a high z-index intercepts the CTA until it is dismissed, and on mobile it can take 250 to 270px of height. Push the beats up while the bar is on screen instead of lowering its z-index, and write the selector so it survives a library that hides the node with an inline style rather than removing it from the DOM:
+
+```css
+body:has(.cookie-bar:not([style*="display: none"])) .hero-beat { bottom: clamp(190px, 24vh, 260px); }
+```
+
+Text over footage needs a directional scrim plus text-shadow to stay readable. See `frontend/design-system/premium-finish.md`.
+
+---
+
+## Section 8: Verify With Motion, Never With a Still
+
+**This is the highest-leverage check in the whole build.** A static screenshot does not reveal a broken scrub: the canvas can be 1x1 drawing garbage, or the frames can be ignoring scroll entirely, and the screenshot still looks plausible.
+
+Drive the scroll and capture the sequence, using the exposed Lenis instance (see `frontend/scroll-driven/smooth-scroll.md`):
+
+```js
+// browser console, or via Playwright / Chrome DevTools MCP
+const lenis = window.__lenis
+const H = document.body.scrollHeight - innerHeight
+for (const p of [0, .15, .3, .45, .6, .8, 1]) {
+  lenis.scrollTo(H * p, { immediate: true })
+  await new Promise(r => setTimeout(r, 350))  // let scrub:0.4 settle
+  // screenshot here
+}
+```
+
+The `setTimeout` matters: `scrub: 0.4` does not jump instantly, so without the wait you photograph the previous frame.
+
+Confirm three things: different frames appear at different scroll positions, the subject stays framed, and the copy stays legible over every captured frame.
+
+---
+
+## Checklist
+
+- [ ] Frames extracted with explicit fps, scale and `-q:v`; total weight measured
+- [ ] Poster frame extracted and wired to the fallback
+- [ ] `framePath` carries a `?v=N` cache-bust, bumped on every re-extraction
+- [ ] Canvas starts hidden and resizes on the first loaded frame
+- [ ] `focusX/focusY` set so the cover crop keeps the subject
+- [ ] Mobile and reduced-motion collapse to the poster in both JS and CSS
+- [ ] Inactive text beats carry `pointer-events: none` in the CSS and in the timeline
+- [ ] Verified by driving the scroll and comparing frames, not with a single screenshot

package/framework/standards/frontend/scroll-driven/scroll-components.md

@@ -0,0 +1,256 @@
+# Scroll Components — Interaction Toolbox
+
+> **Scope:** frontend-scroll-driven
+> **Layer:** 3
+> **Keywords:** pinned gallery, horizontal scroll, modal, lightbox, parallax, count-up, reveal, scroll progress, accordion
+> **Load When:** ui-designer active, or building a scroll-driven marketing page
+
+**Verified against:** GSAP 3.13 (ScrollTrigger, matchMedia, context) + React 18 + Lenis 1.x, shipped to production. Last-verified: 2026-08-21.
+
+---
+
+A toolbox of scroll-driven interaction patterns, not a mandatory list. Pick what the page needs. Every recipe assumes the wiring in `frontend/scroll-driven/smooth-scroll.md` (shared motion registry, Lenis on the GSAP ticker, `window.__lenis` exposed) and cleans itself up on unmount.
+
+The frame-scrub hero is documented separately in `frontend/scroll-driven/frame-scrub.md`.
+
+---
+
+## Section 1: useReveal (The Base Brick)
+
+Most content (headings, paragraphs, cards) needs nothing more than this. Use `.d1 .d2 .d3` to stagger siblings.
+
+```jsx
+export function useReveal() {
+  useEffect(() => {
+    if (prefersReducedMotion) return
+    const els = gsap.utils.toArray('.reveal')
+    const ctx = gsap.context(() => {
+      els.forEach((el) => gsap.fromTo(el,
+        { opacity: 0, y: 28 },
+        { opacity: 1, y: 0, duration: 0.9, ease: 'power3.out',
+          scrollTrigger: { trigger: el, start: 'top 88%', once: true } },
+      ))
+    })
+    return () => ctx.revert()
+  }, [])
+}
+```
+
+```css
+.reveal { will-change: opacity, transform; }
+.reveal.d1 { transition-delay: .08s } .reveal.d2 { transition-delay: .16s } .reveal.d3 { transition-delay: .24s }
+@media (prefers-reduced-motion: reduce) {
+  .reveal { opacity: 1 !important; transform: none !important; }
+}
+```
+
+`once: true` matters: re-revealing on every pass reads as nervous, not premium.
+
+**If you implement this with `IntersectionObserver` instead of ScrollTrigger, keep `threshold: 0`.** A threshold is a fraction of the observed element's own area, so a block taller than the viewport (a long photo grid, a tall editorial section) never reaches 15 percent visible at once. The callback never fires, the element keeps `opacity: 0` forever, and it still occupies its full height in the layout: the page shows a large blank gap and nothing in the console. Use `threshold: 0` with a `rootMargin`, which fires as soon as the first pixel enters, whatever the element's height. The ScrollTrigger version above is immune because `start: 'top 88%'` measures the element's top against the viewport, not its area.
+
+---
+
+## Section 2: Pinned Horizontal Gallery
+
+A section that pins to the viewport and slides cards horizontally as the user scrolls vertically. Desktop only; on mobile it falls back to normal vertical scrolling via CSS.
+
+```jsx
+useEffect(() => {
+  const mm = gsap.matchMedia()
+  mm.add('(min-width: 861px) and (prefers-reduced-motion: no-preference)', () => {
+    const section = sectionRef.current, track = trackRef.current
+    section.classList.add('lines--horizontal')
+    const distance = () => Math.max(0, track.scrollWidth - window.innerWidth)
+    const tween = gsap.to(track, {
+      x: () => -distance(),
+      ease: 'none',
+      scrollTrigger: {
+        trigger: section, start: 'top top', end: () => `+=${distance()}`,
+        scrub: 0.5, pin: true, anticipatePin: 1, invalidateOnRefresh: true,
+      },
+    })
+    return () => {
+      section.classList.remove('lines--horizontal')
+      gsap.set(track, { x: 0 })
+      tween.scrollTrigger?.kill(); tween.kill()
+    }
+  })
+  return () => mm.revert()
+}, [])
+```
+
+`invalidateOnRefresh: true` is required here: without it the travel distance stays frozen at the first measurement and the pin ends in the wrong place after a resize.
+
+To lengthen the journey and give cards more breathing room, increase the track gap or padding. `scrollWidth` grows and the pin lasts longer.
+
+---
+
+## Section 3: Expanding Modal
+
+A card that opens into a detail panel. The entry pattern is: mount the node, then add the `.in` class on the next frame so the CSS transition fires.
+
+```jsx
+const [active, setActive] = useState(null)
+const [shown, setShown] = useState(false)
+
+const open = (i) => {
+  setActive(i)
+  requestAnimationFrame(() => setShown(true))
+  window.__lenis?.stop()
+}
+const close = () => {
+  setShown(false)
+  window.__lenis?.start()
+  setTimeout(() => setActive(null), 380)   // matches the CSS transition
+}
+
+useEffect(() => {
+  if (active === null) return
+  const onKey = (e) => { if (e.key === 'Escape') close() }
+  window.addEventListener('keydown', onKey)
+  return () => window.removeEventListener('keydown', onKey)
+}, [active])
+```
+
+**Render overlays outside any pinned section.** A pin applies a `transform` to its container, which becomes the containing block for `position: fixed` and breaks the overlay. Put the modal in a fragment as a sibling of the section.
+
+**Mark the scrollable panel `data-lenis-prevent`.** Stopping the smooth scroller is not enough: while stopped it calls `preventDefault()` on any `touchmove` that reaches it, so a panel with `overflow-y: auto` scrolls with the wheel and is frozen under a finger. Whatever sits at the bottom of the panel, usually the CTA, becomes unreachable on a phone. See `frontend/scroll-driven/smooth-scroll.md`, Section 3.
+
+```jsx
+<div className="lmodal__panel" data-lenis-prevent>
+```
+
+```css
+.lmodal { position: fixed; inset: 0; z-index: 300; display: grid; place-items: center;
+  background: rgba(0,0,0,0); backdrop-filter: blur(0px);
+  transition: background .38s, backdrop-filter .38s; }
+.lmodal.in { background: rgba(0,0,0,.6); backdrop-filter: blur(6px); }
+.lmodal__panel { opacity: 0; transform: translateY(24px) scale(.98);
+  transition: opacity .38s, transform .38s cubic-bezier(.2,.7,.2,1); }
+.lmodal.in .lmodal__panel { opacity: 1; transform: none; }
+```
+
+---
+
+## Section 4: Fullscreen Lightbox
+
+Same `.in` pattern, plus arrow-key navigation and a paused scroller.
+
+```jsx
+const go = (dir) => setLb((i) => (i + dir + PHOTOS.length) % PHOTOS.length)
+
+useEffect(() => {
+  if (lb === null) return
+  const onKey = (e) => {
+    if (e.key === 'Escape') close()
+    else if (e.key === 'ArrowRight') go(1)
+    else if (e.key === 'ArrowLeft') go(-1)
+  }
+  window.addEventListener('keydown', onKey)
+  return () => window.removeEventListener('keydown', onKey)
+}, [lb])
+```
+
+Grid items that open the lightbox need `role="button"`, `tabIndex={0}` and an `onKeyDown` handling Enter and Space, plus a zoom affordance on hover.
+
+---
+
+## Section 5: Parallax Drift
+
+Images move at slightly different speeds to suggest depth. Subtle wins: 5 to 8 percent of drift is enough.
+
+```jsx
+mm.add('(prefers-reduced-motion: no-preference)', () => {
+  const imgs = gsap.utils.toArray(gridRef.current.querySelectorAll('img'))
+  const tweens = imgs.map((img, i) => {
+    const from = i % 2 === 0 ? -5 : 5
+    return gsap.fromTo(img, { yPercent: from }, {
+      yPercent: -from, ease: 'none',
+      scrollTrigger: { trigger: img.closest('figure'), start: 'top bottom', end: 'bottom top', scrub: true },
+    })
+  })
+  return () => {
+    tweens.forEach((t) => { t.scrollTrigger?.kill(); t.kill() })
+    ScrollTrigger.refresh()
+  }
+})
+```
+
+Give the `<figure>` `overflow: hidden` and scale the image slightly above 100 percent so the drift never exposes an edge.
+
+---
+
+## Section 6: Count-Up
+
+For a rating or statistic. Animate a plain object and write the text on each update.
+
+```jsx
+const obj = { v: 0 }
+gsap.to(obj, {
+  v: 4.9, duration: 1.6, ease: 'power2.out',
+  scrollTrigger: { trigger: el, start: 'top 85%', once: true },
+  onUpdate: () => { el.textContent = obj.v.toFixed(1).replace('.', ',') },
+})
+```
+
+Format for the locale at write time (the decimal comma above is pt-BR). Never animate a number the business cannot back up.
+
+---
+
+## Section 7: Persistent Elements
+
+**Slim translucent nav** that gains a background once scrolled:
+
+```jsx
+const [solid, setSolid] = useState(false)
+useEffect(() => {
+  const onScroll = () => setSolid(window.scrollY > 40)
+  window.addEventListener('scroll', onScroll, { passive: true })
+  return () => window.removeEventListener('scroll', onScroll)
+}, [])
+```
+
+**Scroll progress bar** that prefers the smooth scroller when present:
+
+```jsx
+useEffect(() => {
+  const onScroll = () => {
+    const h = document.documentElement.scrollHeight - innerHeight
+    if (ref.current) ref.current.style.transform = `scaleX(${h > 0 ? scrollY / h : 0})`
+  }
+  const l = window.__lenis
+  l ? l.on('scroll', onScroll) : window.addEventListener('scroll', onScroll, { passive: true })
+  onScroll()
+  return () => { l ? l.off('scroll', onScroll) : window.removeEventListener('scroll', onScroll) }
+}, [])
+```
+
+Transform-based progress (`scaleX` with `transform-origin: 0 50%`) stays on the compositor. Animating `width` does not.
+
+---
+
+## Section 8: Accordion
+
+Use native `<details>`. It provides toggle, keyboard support and accessibility for free.
+
+```css
+.faq__item summary { cursor: pointer; list-style: none; display: flex;
+  justify-content: space-between; align-items: center; }
+.faq__item summary::-webkit-details-marker { display: none; }
+.faq__item .faq__icon { transition: transform .3s; }
+.faq__item[open] .faq__icon { transform: rotate(45deg); }
+```
+
+Native `<details>` cannot animate its own height. If height animation is required, drive the inner content with GSAP rather than replacing the element with a custom widget.
+
+---
+
+## Section 9: Cross-Cutting Rules
+
+These apply to every recipe above:
+
+- **Pause the scroller on overlays.** `window.__lenis?.stop()` on open, `.start()` on close, or the background scrolls behind the overlay. Add `data-lenis-prevent` to the panel that scrolls inside it, or touch scrolling stays dead while the scroller is stopped.
+- **Overlays live outside pinned sections.** A pin's `transform` breaks `position: fixed` inside it.
+- **Anything clickable that is not a `<button>` or `<a>`** gets `role="button"`, `tabIndex={0}` and Enter/Space handling. Escape closes overlays. `:focus-visible` stays visible.
+- **Every effect has a static fallback under reduced motion.** Scrub and parallax simply do not mount.
+- **Every effect reverts on cleanup** via `gsap.context()` or `matchMedia()`, or hot reloads duplicate triggers.

package/framework/standards/frontend/scroll-driven/smooth-scroll.md

@@ -0,0 +1,148 @@
+# Smooth Scroll — Lenis + GSAP ScrollTrigger
+
+> **Scope:** frontend-scroll-driven
+> **Layer:** 3
+> **Keywords:** lenis, smooth-scroll, scrolltrigger, raf, gsap ticker, window.__lenis, HMR, scroll wiring
+> **Load When:** ui-designer active, or the project uses smooth scrolling with scroll-driven animation
+
+**Verified against:** Lenis 1.x + GSAP 3.13 ScrollTrigger + Vite 5, shipped to production. Last-verified: 2026-08-21.
+
+---
+
+Wiring guide for pairing a smooth-scroll library with scroll-driven animation. Getting this wrong produces animations that lag behind the scroll, triggers that measure the wrong positions, and sections that silently die after a few hot reloads. Covers the RAF handoff, why the instance must be exposed globally, refresh timing, and the HMR staleness trap.
+
+**Which motion stack this is.** Reach for GSAP plus ScrollTrigger plus Lenis when the scroll position drives the scene: frame scrubs, pinned sequences, parallax, progress. For component-level motion in a regular app or product UI (enter and exit, gestures, mount and unmount transitions), use Motion for React and see `frontend/nextjs/motion-patterns.md`. The two can coexist on a page but never on the same element, because both write inline styles and will fight for control. On a page running Lenis, scroll reveals belong to `useReveal` in `frontend/scroll-driven/scroll-components.md`, not to `whileInView`: two libraries observing the same scroll produce two sources of truth for when an element is visible.
+
+---
+
+## Section 1: Central Motion Registry
+
+Register plugins once, in a single module every component imports from. Never register inside `useEffect` or a loop.
+
+```js
+// lib/motion.js
+import { gsap } from 'gsap'
+import { ScrollTrigger } from 'gsap/ScrollTrigger'
+
+gsap.registerPlugin(ScrollTrigger)
+
+export const prefersReducedMotion =
+  typeof window !== 'undefined' && window.matchMedia &&
+  window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+export { gsap, ScrollTrigger }
+```
+
+Exporting `prefersReducedMotion` from the same module keeps every effect checking the same value instead of re-querying `matchMedia` with slightly different strings.
+
+---
+
+## Section 2: The RAF Handoff
+
+Lenis and GSAP each want to own the animation frame. Running both tickers independently makes scrub visibly lag the scroll. Drive Lenis from the GSAP ticker instead:
+
+```js
+useEffect(() => {
+  if (prefersReducedMotion) return
+
+  const lenis = new Lenis({
+    duration: 1.1,
+    easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
+    smoothWheel: true,
+  })
+
+  lenis.on('scroll', ScrollTrigger.update)
+
+  // See Section 3.
+  if (typeof window !== 'undefined') window.__lenis = lenis
+
+  const tick = (time) => lenis.raf(time * 1000)
+  gsap.ticker.add(tick)
+  gsap.ticker.lagSmoothing(0)
+
+  // Recalculate once fonts and images have settled.
+  const onLoad = () => ScrollTrigger.refresh()
+  window.addEventListener('load', onLoad)
+
+  return () => {
+    window.removeEventListener('load', onLoad)
+    gsap.ticker.remove(tick)
+    lenis.destroy()
+  }
+}, [])
+```
+
+Three details carry weight:
+
+- **`lenis.on('scroll', ScrollTrigger.update)`** keeps triggers in sync with smoothed position rather than raw native scroll.
+- **`gsap.ticker.lagSmoothing(0)`** disables GSAP's frame-drop compensation, which otherwise fights the smooth scroller after a stall.
+- **`ScrollTrigger.refresh()` on `load`** fixes trigger positions measured before webfonts and images changed the layout height.
+
+---
+
+## Section 3: Expose the Instance on `window`
+
+Set `window.__lenis` deliberately. It is not a debugging leftover, it serves two production needs:
+
+1. **Overlays must stop the scroll.** Modals and lightboxes call `window.__lenis?.stop()` on open and `.start()` on close, otherwise the page scrolls behind the overlay.
+2. **Verification needs to drive the scroll.** Automated checks (Playwright, Chrome DevTools MCP) use `lenis.scrollTo(y, { immediate: true })` to step through scroll positions and capture what actually renders. See `frontend/scroll-driven/frame-scrub.md`, Section 8.
+
+Consumers must use optional chaining (`window.__lenis?.stop()`), because under reduced motion the instance is never created.
+
+**`stop()` alone breaks touch scrolling inside the overlay.** The smooth scroller listens to `touchmove` globally, and while stopped it calls `preventDefault()` on any touch that bubbles up to it. An overlay panel with `overflow-y: auto` scrolls fine with a mouse wheel and is completely frozen on a phone, which usually hides whatever sits at the bottom of the panel, such as the CTA. Mark the scrollable element with the opt-out attribute Lenis provides for exactly this case:
+
+```jsx
+<div className="modal__panel" data-lenis-prevent>
+  {/* long content, native overflow-y: auto */}
+</div>
+```
+
+Wheel and touch are separate code paths here, so a desktop check does not cover this. Verify the overlay on a touch viewport.
+
+---
+
+## Section 4: The HMR Staleness Trap
+
+**Symptom:** after many hot reloads in dev, pins stop holding, scrubs freeze, a pinned horizontal gallery stops locking.
+
+**Cause:** ScrollTrigger accumulates stale instances across reloads. In most cases the code is fine.
+
+**First response:** do a full page reload (F5) before debugging. It clears the accumulated state. Concluding that a section is broken based on a hot-reloaded page wastes real time.
+
+**Defenses in code:**
+
+- `invalidateOnRefresh: true` on any trigger whose measurements depend on viewport size (pinned horizontal distance, computed end values).
+- Wrap every effect in `gsap.context()` or `gsap.matchMedia()` and revert it on cleanup, so hot reloads cannot duplicate triggers.
+- Call `ScrollTrigger.refresh()` on `load` and after killing responsive tweens.
+
+```js
+useEffect(() => {
+  const ctx = gsap.context(() => {
+    // tweens and triggers here
+  }, scopeRef)
+  return () => ctx.revert()   // non-negotiable
+}, [])
+```
+
+---
+
+## Section 5: Reduced Motion
+
+Under `prefers-reduced-motion: reduce`, do not instantiate the smooth scroller at all. Native scrolling is the accessible baseline, and every scroll-driven effect must have a static fallback rather than a degraded animation.
+
+This means `window.__lenis` is `undefined` in that path, which is exactly why Section 3 requires optional chaining.
+
+---
+
+## Checklist
+
+- [ ] Plugins registered once in a shared `lib/motion` module
+- [ ] Lenis driven from `gsap.ticker`, not its own RAF loop
+- [ ] `lagSmoothing(0)` set
+- [ ] `ScrollTrigger.update` bound to the Lenis scroll event
+- [ ] `ScrollTrigger.refresh()` called on window `load`
+- [ ] `window.__lenis` exposed, and every consumer uses optional chaining
+- [ ] Every effect wrapped in `gsap.context()` / `matchMedia()` with revert on cleanup
+- [ ] `invalidateOnRefresh: true` on viewport-dependent triggers
+- [ ] Scrollable overlay panels marked `data-lenis-prevent` and verified on a touch viewport
+- [ ] Smooth scroller not instantiated under reduced motion