@struq/skill 0.3.0 → 0.4.0

package/skills/struq/references/pinning-scrub.md

@@ -1,340 +0,0 @@
-# Pinning & Scrub-Tied Sequences
-
-The showpiece category. A pinned, scrubbed section is where a site stops being a page and becomes a sequence, but it's also the easiest place to wreck UX. Budget: **1 to 2 pinned sequences per site.** Three or more and scrolling feels hijacked. For named, ready-made showpiece recipes with ids, see [showcase.md](showcase.md).
-
-Core concept first, because everything here is one idea: **`scrub` ties timeline progress to scroll position** (scroll = the playhead), and **`pin` freezes an element while the scroll distance plays out**. Triggered tweens fire once and play on their own clock; scrubbed timelines move when the user moves and stop when they stop. That hand-connection is the feel difference between an award site and a slideshow.
-
-All snippets assume [setup.md](setup.md). `scrub: true` vs `scrub: 1` is a feel decision; see [feel-layer.md](feel-layer.md).
-
-**A pin that jerks, jumps, snaps or lands in the wrong place** is one of a short list of causes (`anticipatePin` with Lenis, stale measurements, a transformed ancestor, `vh` on mobile, a pin in a flex or grid parent, nested pins). Work through [pitfalls.md](pitfalls.md) §2 before tuning `scrub`.
-
----
-
-## 1. Pinned scrub timeline (the workhorse)
-
-**Term:** Pinned sequence / scroll-told story.
-**Mechanic:** A one-screen (`100svh`) section pins; the user scrolls "through" an invisible distance (`end: "+=250%"` → 2.5 viewport-heights of scroll) while a timeline scrubs across phases: text swaps, media transforms, layers move. Scroll distance, not time, is the duration unit.
-
-**When:** Product walkthroughs, process steps, one cinematic brand moment.
-**Overkill when:** the content is just three paragraphs. Pinning 3 viewports of scroll to read 40 words is hostage-taking.
-**Cost:** Pinning re-parents into a pin-spacer and recalculates on resize; transforms inside are cheap. The real cost is UX: always check the section is skippable in <3 swipes on mobile, and skip pinning entirely under `prefers-reduced-motion`.
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-const PHASES = [
-  { kicker: "01", title: "Research", body: "We start in the field, not in Figma." },
-  { kicker: "02", title: "Systems", body: "Design tokens before screens." },
-  { kicker: "03", title: "Craft", body: "Motion and microcopy get design reviews too." },
-];
-
-// ONE gate for the layout switch and the pin. Touch, small screens, reduced motion and
-// no-JS all get the stacked list the server rendered.
-const GATE = "(min-width: 768px) and (prefers-reduced-motion: no-preference)";
-
-export function ProcessSequence() {
-  const container = useRef<HTMLElement>(null);
-
-  useGSAP(
-    () => {
-      const mm = gsap.matchMedia();
-
-      mm.add(GATE, () => {
-        const section = container.current!;
-        const phases = gsap.utils.toArray<HTMLElement>("[data-phase]");
-
-        // Switch the stacked list into a stage, then hide the later phases with GSAP.
-        // matchMedia reverts the gsap.set and runs the returned cleanup when the gate
-        // stops matching, so the list comes back by itself.
-        section.dataset.mode = "rig";
-        gsap.set(phases.slice(1), { yPercent: 30, autoAlpha: 0 });
-
-        const tl = gsap.timeline({
-          scrollTrigger: {
-            trigger: section,
-            start: "top top",
-            end: "+=250%",          // 2.5 viewports of scroll-room: ~0.8 per phase
-            pin: true,
-            scrub: 1,                // 1s catch-up smoothing, see feel-layer.md
-            // snap: phases feel like steps? snap to them. Continuous story? omit.
-            snap: { snapTo: 1 / (phases.length - 1), duration: 0.4, ease: "power2.inOut" },
-          },
-        });
-
-        phases.forEach((phase, i) => {
-          if (i === 0) return; // phase 0 is the resting state
-          tl.to(phases[i - 1], { yPercent: -30, autoAlpha: 0, ease: "power2.in", duration: 0.4 })
-            .to(phase,
-              { yPercent: 0, autoAlpha: 1, ease: "power2.out", duration: 0.4 },
-              "<0.15" // overlap: new phase starts before old one is fully gone
-            );
-        });
-
-        // A continuous element that evolves across ALL phases sells the sequence
-        tl.fromTo("[data-dial]", { rotate: 0 }, { rotate: 270, ease: "none", duration: tl.duration() }, 0);
-
-        return () => { delete section.dataset.mode; };
-      });
-    },
-    { scope: container }
-  );
-
-  // Server markup = a readable stacked list. data-mode="rig" (motion branch only) turns it
-  // into the pinned stage: the phases stack absolutely and the section takes one screen.
-  return (
-    <section
-      ref={container}
-      className="group/seq relative bg-surface-1 py-[8rem]
-                 data-[mode=rig]:h-[100svh] data-[mode=rig]:overflow-hidden data-[mode=rig]:py-0"
-    >
-      <div className="grid grid-cols-12 items-center gap-y-16 px-6 group-data-[mode=rig]/seq:h-full">
-        <ol className="relative col-span-12 space-y-16 md:col-span-5 md:col-start-2
-                       group-data-[mode=rig]/seq:h-full group-data-[mode=rig]/seq:space-y-0">
-          {PHASES.map((p) => (
-            <li key={p.kicker} data-phase
-                className="flex flex-col justify-center group-data-[mode=rig]/seq:absolute group-data-[mode=rig]/seq:inset-0">
-              <h3 className="font-display text-h2">{p.title}</h3>
-              <p className="text-body mt-6 max-w-[36ch] text-ink-muted">{p.body}</p>
-            </li>
-          ))}
-        </ol>
-        <div data-dial aria-hidden
-             className="col-span-4 col-start-8 aspect-square rounded-full border border-line max-md:hidden" />
-      </div>
-    </section>
-  );
-}
-```
-
-Craft notes:
-- **`ease: "none"` for anything that should track scroll linearly** (the dial); eases *inside* a scrubbed timeline still apply within their segment, so entrance/exit phases keep `power2` and each swap has shape.
-- **One continuous element** (`data-dial`) spanning the whole timeline is what makes it feel like a sequence rather than a slide deck.
-- **`"<0.15"` overlap** between exit and entrance: gapless storytelling.
-- The `01/02/03` kickers here are fine. Ordinal numbering *inside one stepped component* is real content, distinct from the page-wide numbered-everything tell ([anti-patterns.md](anti-patterns.md) §16). Don't let this pattern leak numerals onto every other section.
-- Snap is for stepped content; omit for continuous narratives. Never snap with distances under ~80% per phase (fights the user's thumb).
-- **Server markup is the final, readable state.** Nothing is hidden with an inline `style={{ opacity: 0 }}` or a CSS class: the later phases are hidden by `gsap.set` inside the motion branch, so reduced motion, touch, a failed bundle and no-JS all read the three phases as a list. The layout switch is a data attribute set in the same branch, so the list and the pin can never disagree.
-- **One `GATE` string** for every decision about this section (the layout switch, the pin, and a canvas if one joins it, [webgl-r3f.md](webgl-r3f.md) §1). Two queries drift: a fine-pointer tablet ends up with a pin and no stage, or a stage and no pin.
-
-**Cheap tell:** content swaps via `opacity` crossfade fired at thresholds (`toggleActions`), no pin: a slideshow that happens near scroll. Or: pinned for 6 viewports with one sentence. **Instead:** Pinned, scrubbed, phases overlapping, one element evolving continuously, ≤2.5 viewports.
-
----
-
-## 2. Horizontal scroll section
-
-**Term:** Horizontal scroll-jack (the respectable kind).
-**Mechanic:** A pinned viewport-height section translates a wide flex row on `x` as the user scrolls vertically. Vertical input, horizontal travel. The pin distance equals the hidden width, so scroll speed maps 1:1 to lateral movement. This 1:1 mapping is why it feels natural where `scroll-snap` carousels feel like a different widget.
-
-**When:** Galleries, project indexes, timeline content that is *genuinely sequential*.
-**Overkill when:** the content would work as a grid. Horizontal scroll must be earned by content with an axis. Never put critical info (pricing, CTA) inside one.
-**Cost:** Transforms only, so cheap. But images off-screen still load; lazy-load panels 3+. On touch, 1:1 vertical→horizontal is fine; *nested* horizontal sections are not: one per page.
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-export function WorkGallery({ projects }: { projects: { title: string; meta: string; img: string }[] }) {
-  const container = useRef<HTMLElement>(null);
-  const track = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      const getDistance = () => track.current!.scrollWidth - window.innerWidth;
-
-      const scrollTween = gsap.to(track.current, {
-        x: () => -getDistance(),            // function-based: recalcs on refresh/resize
-        ease: "none",                       // scroll IS the ease; easing here feels broken
-        scrollTrigger: {
-          trigger: container.current,
-          start: "top top",
-          end: () => `+=${getDistance()}`,  // pin distance = hidden width → 1:1 feel
-          pin: true,
-          scrub: 1,
-          invalidateOnRefresh: true,
-          // Do NOT add anticipatePin here when Lenis (or any smooth scroll) is on.
-          // See craft note below: it jumps the frame at the pin handoff.
-        },
-      });
-
-      // Per-panel parallax inside the horizontal world: containerAnimation
-      gsap.utils.toArray<HTMLElement>("[data-panel] img").forEach((img) => {
-        gsap.fromTo(img, { xPercent: -8 }, {
-          xPercent: 8,
-          ease: "none",
-          scrollTrigger: {
-            trigger: img.parentElement,
-            containerAnimation: scrollTween, // triggers measured inside the moving track
-            start: "left right",
-            end: "right left",
-            scrub: true,
-          },
-        });
-      });
-    },
-    { scope: container }
-  );
-
-  return (
-    <section ref={container} className="overflow-hidden bg-surface-0">
-      <div ref={track} className="flex h-[100svh] w-max items-center gap-[6vw] px-[8vw]">
-        <div className="w-[28vw] shrink-0">
-          <h2 className="font-display text-h2">Selected<br />work</h2>
-        </div>
-        {projects.map((p, i) => (
-          <article key={p.title} data-panel className="w-[42vw] shrink-0">
-            <div className="overflow-hidden">
-              <img src={p.img} alt="" loading={i > 1 ? "lazy" : undefined}
-                   className="aspect-[4/3] w-full scale-110 object-cover" />
-            </div>
-            <p className="text-small mt-4 flex items-baseline justify-between text-ink-muted">
-              <span>{p.title}</span><span className="tabular-nums">{p.meta}</span>
-            </p>
-          </article>
-        ))}
-      </div>
-    </section>
-  );
-}
-```
-
-Craft notes:
-- **Function-based `x` and `end` + `invalidateOnRefresh`**: without these, resize breaks the mapping and the section over/under-scrolls.
-- **`containerAnimation`** is the GSAP-only feature that makes triggers work *inside* the moving track (per-panel parallax, reveals as panels enter). This is why Motion isn't the tool here.
-- Varying panel widths (`28vw` intro, `42vw` projects) beats uniform cards, the same asymmetry rule as vertical layout.
-- **Never `anticipatePin` with smooth scroll.** `anticipatePin` pins *early* by predicting scroll velocity, but Lenis feeds it a **smoothed** velocity, so the prediction overshoots and the pin engages a frame too early, then corrects. The result is a visible jump at the exact vertical→horizontal handoff that reads as "jagged, not eased in," worst on a fast scroll-in. It exists to hide native-scroll pin latency; smooth scroll already removes that latency, so it only adds jitter. The fix for a jagged handoff is almost always **remove `anticipatePin`** (not tuning `scrub`). If the *first* scroll-in specifically snaps, the cause is stale pin positions: add the delayed initial `lenis.resize()` + `ScrollTrigger.refresh()` from [setup.md](setup.md) §2, not `anticipatePin`.
-- Mobile fallback: **never pin on touch**. The exact matchMedia pattern is §4 below. Pinned horizontal on small phones is a common award-site sin.
-
-**Cheap tell:** `overflow-x-auto` with `scroll-snap` and visible scrollbar presented as the showpiece; or a horizontal section where panels are identical-width cards 1 to 12. **Instead:** Pinned 1:1 mapping, mixed panel widths, parallax inside panels, native fallback on mobile.
-
----
-
-## 3. Scrub-tied hero (no pin)
-
-**Term:** Departure scrub.
-**Mechanic:** The hero reacts to the first hundreds of scroll pixels: headline drifts up faster than scroll, media scales and dims, the lead line fades. No pinning; the page just *leaves* cinematically instead of sliding away as a rigid block.
-
-**When:** Every hero. This is the cheapest scrub win on the page. Do it even when you do nothing else from this file.
-**Cost:** Trivial.
-
-```tsx
-useGSAP(
-  () => {
-    const tl = gsap.timeline({
-      scrollTrigger: {
-        trigger: container.current,
-        start: "top top",
-        end: "bottom top",   // while the hero leaves the viewport
-        scrub: true,          // direct tie; departure should feel attached to the hand
-      },
-    });
-
-    tl.to("[data-hero-title]", { yPercent: -40, ease: "none" }, 0)        // rises faster than page
-      .to("[data-hero-media]", { scale: 1.12, ease: "none" }, 0)           // grows as it leaves
-      .to("[data-hero-veil]",  { autoAlpha: 0.55, ease: "none" }, 0)       // dims under a veil div
-      .to("[data-hero-meta]",  { autoAlpha: 0, yPercent: -100, ease: "none" }, 0);
-  },
-  { scope: container }
-);
-```
-
-Different elements at different rates = instant depth (full multi-layer treatment in [depth-parallax.md](depth-parallax.md)). Dim with a `data-hero-veil` overlay div, not `filter: brightness()`: opacity composites cheaply, scrubbed filters don't.
-
-**Cheap tell:** hero scrolls away as one static raster. **Instead:** Title, media, veil, and meta leave at four different speeds, tied to the hand.
-
----
-
-## 4. The touch fallback: pin on desktop, swipe on touch (the exact pattern)
-
-Pinning fights native touch scroll; every pinned/horizontal section MUST branch.
-The contract: **one markup tree**, authored so the touch experience is pure
-CSS (scroll-snap), with the pin added *only* inside a desktop
-`gsap.matchMedia()` branch. matchMedia reverts the ScrollTriggers automatically
-when the viewport crosses the breakpoint: no stale pins, nothing to clean up
-by hand.
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-export function Showcase({ items }: { items: { id: string; title: string }[] }) {
-  const container = useRef<HTMLElement>(null);
-  const track = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      const mm = gsap.matchMedia();
-
-      // Desktop + motion-OK ONLY: the pinned 1:1 horizontal scrub (§2).
-      mm.add("(min-width: 768px) and (prefers-reduced-motion: no-preference)", () => {
-        const getDistance = () => track.current!.scrollWidth - window.innerWidth;
-        gsap.to(track.current, {
-          x: () => -getDistance(),
-          ease: "none",
-          scrollTrigger: {
-            trigger: container.current,
-            start: "top top",
-            end: () => `+=${getDistance()}`,
-            pin: true,
-            scrub: 1,
-            invalidateOnRefresh: true,
-          },
-        });
-      });
-
-      // Touch/small/reduced: NO branch needed. The markup below is already a
-      // native scroll-snap carousel via the max-md: utilities. No JS, nothing
-      // fighting the user's thumb.
-    },
-    { scope: container }
-  );
-
-  return (
-    <section ref={container} className="overflow-hidden">
-      {/* One tree serves both modes: the max-md: snap utilities are inert on
-          desktop (where the pin translates the track), and the md: width is
-          inert on mobile (where the track scrolls natively). */}
-      <div
-        ref={track}
-        className="flex items-center gap-[5vw] px-[8vw]
-                   max-md:snap-x max-md:snap-mandatory max-md:overflow-x-auto
-                   md:h-[100svh] md:w-max"
-      >
-        {items.map((item) => (
-          <article key={item.id} className="w-[82vw] shrink-0 snap-center md:w-[42vw]">
-            {/* … */}
-          </article>
-        ))}
-      </div>
-    </section>
-  );
-}
-```
-
-What makes this the *correct* shape (each is a common failure when improvised):
-- **The touch path is CSS-only.** If the fallback also needs JS, it can race the
-  matchMedia revert. Scroll-snap markup that's simply *inert* under the desktop
-  pin can't break.
-- **Both conditions in one query** (`min-width` AND `no-preference`), so
-  reduced-motion desktop users get the native carousel too, not the pin.
-- **Function-based `x`/`end` + `invalidateOnRefresh`** so crossing the
-  breakpoint (rotate, window resize) re-measures instead of over/under-scrolling.
-- For *vertically stacked* pinned sequences (§1-style phase swaps), the touch
-  fallback is a plain stacked list: keep the phases `relative` in normal flow on
-  mobile and only position them `absolute` inside the desktop branch. Same
-  principle: the mobile layout must work with zero JS.
-
----
-
-## When *not* to pin: the self-check
-
-1. Would the content lose meaning as a normal section? If no → don't pin.
-2. Is the pin distance ≤ 2.5 viewports? If no → cut phases.
-3. Is there already a pinned section on this page? If yes → strong justification or cut.
-4. Mobile + reduced-motion fallbacks written (§4)? Not optional.
-5. Does anything *continuous* evolve across the pin? If it's only discrete swaps → maybe it's just a stepped section with reveals, not a pin.

package/skills/struq/references/pitfalls.md

@@ -1,290 +0,0 @@
-# Pitfalls: the bugs that recur on every GSAP build
-
-Symptom first. Find what you see in the index, read the cause, apply the fix, run the check. Every entry here has shipped in a real build at least once, usually because the recipe looked right in a static screenshot. Most of them are invisible to a typecheck, a green build and a reduced-motion screenshot; they only show with motion on, at a real scroll speed, at both 390 and 1440.
-
-Read this file before the first tween (workflow step 6) and again at verify (step 8). The rules behind it live in [setup.md](setup.md) §5; this file is how they fail.
-
-| What you see | Go to |
-|---|---|
-| The tail of g, y, p, j, q or a comma is cut off; an italic last letter loses its right edge | §1 |
-| A pinned section jerks, jumps, snaps or lands in the wrong place | §2 |
-| A section is an empty band with motion on, but fine under reduced motion | §3.1 |
-| A Tailwind offset (`translate-y-16`, `scale-95`) is gone on an animated element | §3.2 |
-| A timed entrance (match cut, hold, intro) fires over an empty frame or behind the loader | §3.3 |
-| The hero flashes unsplit, then jumps into lines | §3.4 |
-| Two animations fight over one element (a menu that half-closes, a jittering object) | §3.5 |
-| A footer, CTA, frame or row is blank in a reduced-motion, no-JS or settled capture | §3.6 |
-| Bars, lines or display type run past their frame at 390 or 1920 | §3.7 |
-
----
-
-## 1. Descender clipping
-
-**The 10-second check.** Temporarily set the text of every masked component (split headlines, the hero, the menu links, a clip-line hero, any reveal wrapper) to **`Gyp, jq.`** at its real display size, plus one line that ends in the pairing's italic accent. Screenshot at 390 and 1440, mid-animation and at rest. Every tail and the comma must be whole, and the italic's last stroke must not be sliced vertically. Then put the copy back.
-
-### 1.1 SplitText line masks at leading under 1
-
-- **Symptom:** descenders of a split headline are cut flat during and after the rise; at rest the line looks underlined by nothing.
-- **Cause:** `mask: "lines"` wraps each line in an `overflow: clip` box exactly one line-height tall. Display leading is 0.92 to 1.0, so the glyphs are taller than the box.
-- **Fix:** pad the mask and pull the margin back, so the clip box grows and the layout does not move:
-
-  ```css
-  /* globals.css: class = linesClass + "-mask" */
-  .split-line-mask { padding-block: 0.1em; margin-block: -0.1em; }
-  ```
-
-- **Verify:** the 10-second check on every `SplitText` with `mask: "lines"` ([scroll-reveals.md](scroll-reveals.md) §3, [typography.md](typography.md) "Fonts and SplitText").
-
-### 1.2 `overflow: hidden` or `clip` on a parent, or a reveal wrapper sized to the line
-
-- **Symptom:** same clipping, but on text that is not split: a menu link, a card title inside an image frame, a text-swap button label.
-- **Cause:** a hand-built mask (`overflow-hidden` on an `li`, a `h-[1em]` wrapper, a fixed-height button) clips at the line box, or a section-level `overflow-hidden` sits flush with the last line.
-- **Fix:** every hand-built mask carries the same padding pulled back with a negative margin: `className="-my-[0.1em] overflow-hidden py-[0.1em]"` ([nav-header.md](nav-header.md) §3). Never size a mask with a fixed height in `em` or `px`; let padding and leading size it. A section that needs `overflow-hidden` for a bleed keeps at least `0.2em` between its edge and the last line of display type.
-- **Verify:** the 10-second check on each hand-built mask, including the menu open state.
-
-### 1.3 Clip-path insets
-
-- **Symptom:** a `clip-path` wipe (`clip-line-hero`, a curtain over a headline) slices descenders while open, or leaves them cut when finished.
-- **Cause:** `inset()` clips to the element's border box, and a heading's box at leading 0.92 is shorter than its ink.
-- **Fix:** padding pulled back on the clipped element (`-my-[0.1em] py-[0.1em]`) so its box contains the ink, and `clearProps: "clipPath"` when the wipe ends so nothing clips the glyphs at rest ([page-entrances.md](page-entrances.md), `clip-line-hero`).
-- **Verify:** the 10-second check, mid-wipe and after.
-
-### 1.4 Italic overhang on the right
-
-- **Symptom:** the last letter of an italic accent word (Fraunces italic, Cormorant italic, Newsreader italic) loses a sliver of its right side, most visible on f, y and d.
-- **Cause:** italic glyphs lean past their advance width. Any horizontal clip (a line mask, `overflow-clip` on the heading, a clip-path inset at 0) cuts the overhang.
-- **Fix:** inline padding pulled back, on the mask and on any clipped heading that can end in italic:
-
-  ```css
-  .split-line-mask { padding-inline: 0.08em; margin-inline: -0.08em; } /* 0.12em for Cormorant */
-  ```
-
-- **Verify:** the italic line of the 10-second check, ending the line on the italic word.
-
-### 1.5 Tight display leading inside overflow containers
-
-- **Symptom:** an oversized line (`scrub-headline`, a cropped display, ghost type) loses its descenders at the section's bottom edge or its accents at the top.
-- **Cause:** the section is `overflow-clip` for the run-off, and the line's ink extends past its leading box into the clip.
-- **Fix:** vertical padding on the section at least `0.25em` of the display size above and below the line (`py-[14rem]` in [typography.md](typography.md) `scrub-headline`), and the crop only on the axis the design crops (`overflow-x-clip`, not `overflow-clip`, when only the horizontal run-off is wanted).
-- **Verify:** screenshot the line at the scrub's start, middle and end.
-
-### 1.6 The wordmark viewBox
-
-- **Symptom:** the logo's descender (a g, a y, a p) is cut, or the logo sits too high next to the nav links.
-- **Cause:** a hand-written or exported `viewBox` from the baseline to the cap height instead of the real ink bounds.
-- **Fix:** generate the outline with the script in [brand.md](brand.md) §3, whose `viewBox` hugs the ink including descenders; never edit the viewBox by hand to "fix" alignment. Align the logo by its box in CSS.
-- **Verify:** the logo at nav size and at its largest use, on both surfaces.
-
-### 1.7 Text inside pinned or transformed containers
-
-- **Symptom:** text that was whole before the pin is clipped while pinned, or a scaled card clips its own title.
-- **Cause:** the pin-spacer and a scaled or transformed parent with `overflow-hidden` both create a new clip box; a `scale: 0.92` recede ([depth-parallax.md](depth-parallax.md) §3) shrinks the box while the text keeps its leading.
-- **Fix:** keep the clip on the media frame, not on the text's container; put text outside the scaled element or give the container the padding from 1.2.
-- **Verify:** the 10-second check with the section pinned and mid-recede.
-
----
-
-## 2. Jarring pins
-
-**The check for every pinned section:** with motion on, scroll into it slowly, then again with one fast flick, then scroll back up through it. The pin must engage without a jump, hold without drifting, release without a jump, and the content after it must start where it should. At 390 and on touch there must be no pin at all, and the content must still read. Then reload mid-page and repeat.
-
-### 2.1 A jerk at the moment the pin engages
-
-- **Cause:** `anticipatePin` with Lenis. It predicts from a smoothed velocity, overshoots, and pins a frame early, then corrects.
-- **Fix:** delete `anticipatePin` on every smooth-scrolled page. It exists to hide native-scroll latency that Lenis already removes ([pinning-scrub.md](pinning-scrub.md) §2).
-- **Verify:** the fast flick into the pin.
-
-### 2.2 Scrub feels laggy, mushy or jittery
-
-- **Cause:** scrub smoothing stacked on Lenis smoothing (`scrub: 2` or more on lerp 0.1 reads as lag), or `scrub: true` on a jumpy native scroll.
-- **Fix:** pair them: Lenis lerp 0.09 to 0.11 with `scrub: 1` for showpieces, `scrub: true` for departure scrubs that must feel attached to the hand ([feel-layer.md](feel-layer.md) §2). Never raise `scrub` to hide a jump; find the jump's cause below.
-- **Verify:** stop scrolling mid-pin: the timeline should settle within about a second and then stand still.
-
-### 2.3 The pin starts or ends in the wrong place, or jumps after something loads
-
-- **Cause:** stale measurements. Triggers were measured before webfonts swapped, images got their height, an entrance finished, a route changed or a split re-ran. Horizontal tracks measured once overscroll after any resize.
-- **Fix:** refresh after the layout settles, and make every measured distance a function:
-
-  ```ts
-  // after fonts, and once more after the first-load entrance or route reveal
-  document.fonts.ready.then(() => ScrollTrigger.refresh());
-
-  gsap.to(track, {
-    x: () => -(track.scrollWidth - window.innerWidth),           // function: recomputed on refresh
-    ease: "none",
-    scrollTrigger: {
-      trigger: section, start: "top top", pin: true, scrub: 1,
-      end: () => `+=${track.scrollWidth - window.innerWidth}`,
-      invalidateOnRefresh: true,                                   // re-run the functions on refresh
-    },
-  });
-  ```
-
-  Give every image an aspect ratio (width and height, or `fill` in a sized frame) so late loads cannot move a trigger. The providers already refresh once after mount ([setup.md](setup.md) §2) and the zone template refreshes after its entrance ([page-entrances.md](page-entrances.md)); a component that changes layout after that (an accordion, a late split) calls `ScrollTrigger.refresh()` itself.
-- **Verify:** hard reload, scroll straight to the pin; then navigate to the page from another route and do it again. Both must engage at the same spot.
-
-### 2.4 The pin jumps on mobile when the URL bar shows or hides
-
-- **Cause:** `100vh` changes with the browser chrome, and ScrollTrigger refreshes on that resize mid-scroll.
-- **Fix:** size one-screen sections with `svh` (`h-[100svh]`, `min-h-[100svh]`), never `h-screen` or `100vh`, and set `ScrollTrigger.config({ ignoreMobileResize: true })` once in the scroll provider ([setup.md](setup.md) §2). Pins are off on touch anyway (2.12); this protects the sections that remain one screen tall.
-- **Verify:** at 390 in a device emulator, scroll down and back up so the URL bar collapses and returns.
-
-### 2.5 The pinned element shifts sideways, scrolls away, or will not stick
-
-- **Cause:** an ancestor with a `transform`, `filter`, `perspective`, `contain: paint` or `will-change: transform` becomes the containing block for `position: fixed`, so the pinned element is fixed to that ancestor instead of the viewport. The usual culprit is a page wrapper left with an inline transform by an entrance, or a smooth-scroll wrapper.
-- **Fix:** clear the ancestor's transform after its entrance (`clearProps: "all"`, [page-entrances.md](page-entrances.md)) and never leave `will-change` on a wrapper. If the ancestor must keep its transform, restructure so the pinned section is not inside it, or set `pinReparent: true` on the trigger (it moves the element to `<body>` while pinned; styles scoped by the old parent then stop applying, so check it).
-- **Verify:** in devtools, walk up from the pinned element: no ancestor may have a computed `transform` other than `none` while pinned.
-
-### 2.6 A pin inside a flex or grid parent collapses or misaligns
-
-- **Cause:** the pin-spacer replaces a flex or grid item; while pinned the element is `position: fixed` and loses the width the track gave it, or the spacer takes a different track size.
-- **Fix:** pin a block-level element that is a direct child of the page flow (the section, or a full-width wrapper inside it), and put the flex or grid layout *inside* the pinned element. In [webgl-scenes.md](webgl-scenes.md) §0 the `outer` section holds the spacer and the inner `wrap` is pinned for the same reason.
-- **Verify:** compare a screenshot just before the pin engages with one while pinned: nothing may change width.
-
-### 2.7 The next section slides under or over the pin unexpectedly
-
-- **Cause:** `pinSpacing: false`, which removes the spacer so the following content scrolls up under the pinned element.
-- **Fix:** leave `pinSpacing` at its default. Use `false` only when the overlap is the design (a sticky stack, a section that should slide over the pinned one), and then give the following section a surface and a z-index on purpose.
-- **Verify:** the release: the next section must start below the pin's end, or overlap it exactly as designed.
-
-### 2.8 Nested pins
-
-- **Cause:** a pinned section inside another pinned section, or a pin inside a horizontal track. Each pin re-parents and measures against a layout the other is changing.
-- **Fix:** one pin per section tree. Inside a pinned horizontal track, use `containerAnimation` for per-panel triggers ([pinning-scrub.md](pinning-scrub.md) §2), never another pin.
-- **Verify:** search the code for `pin:` and confirm no two pinned elements are ancestors of each other.
-
-### 2.9 A pin directly under the hero
-
-- **Cause:** the pin starts while the hero is still leaving, so the departure scrub and the pin compete for the same scroll distance, and the visitor meets a locked scroll before anything has earned it.
-- **Fix:** a breather between the hero and any showpiece ([page-architecture.md](page-architecture.md) §3, [showcase.md](showcase.md) Never).
-- **Verify:** the arc in STRUQ.md: no showpiece in the row after the hero, unless it is the hero.
-
-### 2.10 A snap on first engage after a fast scroll
-
-- **Cause:** `snap` fires as soon as scrolling stops; after a fast flick into a stepped pin, the stop lands near a phase boundary and the snap yanks the timeline to the next phase. Stale pin positions (2.3) make it worse.
-- **Fix:** snap only stepped content whose phases are at least about 80% of a viewport apart, and give it a beat and no momentum:
-
-  ```ts
-  snap: { snapTo: 1 / (phases - 1), duration: { min: 0.2, max: 0.5 }, delay: 0.15, ease: "power2.inOut", inertia: false },
-  ```
-
-  If it still yanks, remove `snap`: a continuous scrub never needs it.
-- **Verify:** the fast flick into the pin, then stop: the phase that settles is the one in view, with no second move.
-
-### 2.11 The 3D scene freezes halfway through a pinned shot
-
-- **Cause:** the offscreen-pause trigger sits on the pinned element, measured against its unpinned box, so it toggles inactive mid-pin.
-- **Fix:** put the pause trigger on the never-pinned outer section with `refreshPriority: -1` ([webgl-scenes.md](webgl-scenes.md) §0).
-- **Verify:** scroll through the whole pinned shot: the scene keeps rendering to the end.
-
-### 2.12 Reduced motion, touch and no-JS: the content must still read
-
-- **Cause:** pinned layouts authored as the default markup (phases `absolute` and hidden with inline `opacity: 0`), with motion added on top.
-- **Fix:** the server markup is the readable fallback (a stacked list, a native scroll-snap row). The pin, the stage layout and the hidden phases exist only inside one `gsap.matchMedia()` gate, set with `gsap.set` and a data attribute that matchMedia reverts ([pinning-scrub.md](pinning-scrub.md) §1 and §4). One `GATE` string decides the pin, the layout and any canvas.
-- **Verify:** emulate `prefers-reduced-motion: reduce`, then 390 with touch, then JavaScript disabled: every phase's text is visible in all three.
-
----
-
-## 3. Animation owners collide
-
-### 3.1 Content stuck at opacity 0: a CSS transition and GSAP on the same property
-
-- **Symptom:** a revealed list or grid is an empty band with motion on. Devtools shows one tween at progress 1, `y` back at 0, but inline `opacity: 0; visibility: hidden` forever. Reduced-motion screenshots look perfect, because no tween runs.
-- **Cause:** the element GSAP animates also carries a CSS `transition-*` on a property GSAP writes. The usual source is a sibling-dim hover (`transition-opacity duration-500`) on the same `li` that `[data-reveal]` targets. The browser transitions every inline value GSAP writes, so the `from` tween reads a half-transitioned style and resolves its end value as 0.
-- **Fix:** one owner per property per element. Reveal the wrapper, transition the child:
-
-  ```tsx
-  // The li is the GSAP target: no transition, no opacity class.
-  <li data-reveal className="group">
-    {/* The hover dim lives one level in. */}
-    <a href={href} className="block transition-opacity duration-500
-                              group-hover/list:opacity-40 group-hover/list:hover:opacity-100">
-      {children}
-    </a>
-  </li>
-  ```
-
-  The same applies to `transition-transform` and `transition-all` on anything GSAP moves ([micro-interactions.md](micro-interactions.md) §3b, [scroll-reveals.md](scroll-reveals.md) §1).
-- **Verify:** search the code: no element with `data-reveal` (or any GSAP target class) has a `transition-` class. Then scroll the page with motion on and check every revealed group ends visible.
-
-### 3.2 A Tailwind offset vanished: `translate: none`
-
-- **Symptom:** a staggered column offset (`lg:translate-y-16`), a `scale-95` rest state or a `rotate-2` tilt is gone on an element that animates, while the code still claims it.
-- **Cause:** Tailwind (v4 or later) writes `translate-*`, `scale-*` and `rotate-*` to the individual CSS `translate`, `scale` and `rotate` properties. GSAP sets those properties to `none` inline on every element it transforms and puts its own values in `transform`, so the utility is erased.
-- **Fix:** offset with layout, or on a wrapper, or inside the tween:
-
-  ```tsx
-  // padding or margin, never translate, on a GSAP target
-  <li data-reveal className="lg:even:mt-16">...</li>
-
-  // or the offset on a static wrapper, the reveal on the child
-  <div className="lg:translate-y-16"><article data-reveal>...</article></div>
-  ```
-
-  For an element that must rest transformed, express the rest state in GSAP (`gsap.set(el, { yPercent: -50 })`) rather than in a utility.
-- **Verify:** compare the motion-on screenshot with the reduced-motion one: the offsets must match.
-
-### 3.3 A timed entrance fires before the image paints, or behind the loader
-
-- **Symptom:** a match-cut hero shows an empty dark frame, then the type; the cut never reads. Or an intro plays behind the loader curtain and is over when it lifts. Static screenshots never show it.
-- **Cause:** the hold starts on mount (`gsap.timeline({ delay: 1 })`) while the photo is still downloading, or the entrance starts before the thing it waits for. A delay set later with `tl.delay(1)` is ignored by `tl.play()`.
-- **Fix:** start the hold from the event it depends on, with a `delayedCall`, and a fallback:
-
-  ```ts
-  const tl = gsap.timeline({ paused: true });   // the cut itself
-  let started = false;
-  const start = (hold: number) => {
-    if (started) return;
-    started = true;
-    gsap.delayedCall(hold, () => { tl.play(); });
-  };
-  img.addEventListener("load", () => start(1), { once: true });
-  if (img.complete && img.naturalWidth > 0) start(1); // cached
-  gsap.delayedCall(2.5, () => start(0));               // never arrived: go straight to the type
-  ```
-
-  With a loader, start it from the loader's exit ([loaders.md](loaders.md)). The full recipe, including the LCP cost of holding: [page-entrances.md](page-entrances.md) `match-cut-hero`.
-- **Verify:** the frame trace in [performance.md](performance.md) §8: the hold frame must be the photo, at 1440 and at 390, on a throttled network.
-
-### 3.4 The hero flashes unsplit, then jumps
-
-- **Cause:** the split runs after first paint and nothing hides the h1 in between.
-- **Fix:** the pre-split guard in [typography.md](typography.md) `line-rise-hero` (a CSS rule that hides the hero only while motion is allowed, lifted by a `data-ready` attribute in the same tick as the split), plus the `<noscript>` override.
-- **Verify:** the first frames of the trace: the hero is either hidden or split, never plain then split.
-
-### 3.5 Two animations write the same property
-
-- **Symptom:** a menu that half-closes when Escape is pressed during its entrance; a 3D object that jitters between two rotations; a header that stutters between hidden and shown.
-- **Cause:** two timelines, or GSAP and Motion, or scroll and pointer, writing one property on one element.
-- **Fix:** kill the running timeline before starting its opposite (keep it in a ref, [nav-header.md](nav-header.md) §3b); nest groups so scroll and pointer each own one ([webgl-scenes.md](webgl-scenes.md) §4, product-rig); use `quickTo` for anything that reverses mid-gesture; never GSAP and Motion on the same property ([../SKILL.md](../SKILL.md), GSAP vs Motion).
-- **Verify:** trigger the reverse mid-animation (Escape during the menu entrance, a direction flip mid-scroll): the motion reverses cleanly.
-
-### 3.6 A section renders empty: a blank footer, an empty frame, a CTA with nothing in it
-
-This is the most common way an ambitious build loses craft points to a plain one: the plain build has no reveals, so it never shows an empty state.
-
-- **Symptom:** in a full-page capture, a reduced-motion capture or mid-scroll, a whole region is blank: the footer, a CTA panel, a media frame, a list row. The reveal never ran, or ran and was reverted.
-- **Cause:** the element starts hidden in CSS or from a `gsap.set` outside `matchMedia`, so the reduced-motion and no-JS branches never show it; a ScrollTrigger whose start is never reached (a footer-reveal or the last section of the page, where `top 80%` cannot happen); a reveal keyed to an element that a pin or a footer-reveal moved; a drawn SVG or canvas that waits for an event that never fires.
-- **Fix:** final state is the default and hidden state is set only inside the motion branch (`gsap.from` inside `mm.add("(prefers-reduced-motion: no-preference)")`, [setup.md](setup.md) §4); triggers near the end of the page use `start: "top bottom"` or fire on load when the section is already in view (`ScrollTrigger.isInViewport`); anything drawn or loaded gets a visible fallback until it is ready.
-- **Verify:** three captures, each read region by region for anything blank that should hold content: a full page with `reducedMotion: 'reduce'`, a full page with JavaScript disabled, and the motion-on scroll sequence after each step settles (wait for the longest reveal). An empty region in any of them fails verify.
-
-### 3.7 Something overruns its frame
-
-- **Symptom:** data bars run past their axis, a drawn line leaves its container, a wordmark or display line pushes past the viewport at 1920.
-- **Cause:** values scaled to a fixed width while the frame is fluid; an axis that does not cover the data's range; display clamps without a max.
-- **Fix:** scale from the measured container (or `%` of it), make the axis cover the data's max, and keep display type inside its clamp ceiling ([typography.md](typography.md)).
-- **Verify:** look at the edges of every frame at 390 and 1920.
-
----
-
-## 4. The pitfall pass at verify
-
-Run it on the production server ([performance.md](performance.md) §8), motion on, at 390 and 1440:
-
-1. The descender test from §1 on every masked component, including the menu and the italic accent.
-2. Every pinned section through the check at the top of §2: slow, fast flick, back up, reload mid-page, then reduced motion, touch and no-JS.
-3. A search for `transition-` and `translate-`, `scale-`, `rotate-` utilities on GSAP targets (§3.1, §3.2).
-4. The frame trace of the first 3 seconds, read frame by frame (§3.3, §3.4).
-5. The empty-region check: reduced-motion full page, no-JS full page, and the settled scroll sequence, each with no blank region that should hold content (§3.6); then the frame edges at 390 and 1920 (§3.7).
-
-Write the result on the `Motion:` line under VERIFY in STRUQ.md.