@struq/skill 0.2.2 → 0.4.0

package/skills/struq/references/performance.md

@@ -1,235 +0,0 @@
-# Performance: cinematic and fast
-
-An award-tier site that stutters or takes four seconds to show its hero is not award-tier. The motion in this skill is cheap when it runs on one clock and animates transforms; what actually makes these sites slow is **assets**: a 40MB hero video, PNG photography, an unoptimized GLB, six font files. Fix assets first, then code.
-
-Run this in two places: on every build before verify, and first thing on a redesign of an existing project (existing projects are almost always carrying badly optimized media).
-
-## 1. Budgets
-
-| Asset | Budget | Notes |
-|---|---|---|
-| Hero image | 250KB at 1920w (AVIF or WebP) | the LCP element on most pages; preload it |
-| Content image | 150KB at 1440w | lazy below the first viewport |
-| Hero or ambient video loop | 2 to 4MB, 6 to 12s, no audio | always a poster; WebM first, MP4 fallback |
-| Any single video | 10MB max | longer content belongs on a video host |
-| GLB model | 1 to 3MB after compression | Draco or meshopt geometry, KTX2 or WebP textures |
-| Fonts | 2 families, 4 files max, about 150KB total | WOFF2, subset, variable where possible |
-| JavaScript on first load | about 250KB gzipped for the route, measured (§8) | three.js and R3F never in it; lazy island only |
-
-**Where the 250KB goes** (measured on a dry run with a recent Next.js and React, three.js correctly excluded: 244KB gzipped for `/`): the framework runtime (React, React DOM, the Next.js client and router) is roughly 150 to 190KB of it and is not yours to cut; GSAP core, ScrollTrigger, SplitText and DrawSVG are about 49KB; Lenis about 6KB; the rest is your components. Over budget, cut in this order: GSAP plugins registered but unused (MorphSVG and Flip are the usual passengers, [setup.md](setup.md) §1), Motion on a page where nothing uses it, Radix primitives imported into the root layout instead of the component that opens them, then heavy client components that could stay server components. The framework share moves with each major, so measure on the installed versions and write the number under VERIFY; never quote this table as the measurement.
-
-Targets on a mid-range phone profile: **LCP under 2.5s, CLS under 0.1, INP under 200ms**. Record them under VERIFY in STRUQ.md ([direction.md](direction.md)).
-
-## 2. Audit an existing project (redesign mode, step one)
-
-```bash
-# the 25 heaviest files under public/ and any asset folders
-find public assets -type f \( -iname "*.mp4" -o -iname "*.mov" -o -iname "*.webm" -o -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.webp" -o -iname "*.avif" -o -iname "*.gif" -o -iname "*.svg" -o -iname "*.glb" -o -iname "*.gltf" -o -iname "*.ttf" -o -iname "*.otf" -o -iname "*.woff" -o -iname "*.woff2" \) -printf "%s\t%p\n" 2>/dev/null | sort -rn | head -25 | awk -F'\t' '{printf "%8.1f KB  %s\n", $1/1024, $2}'
-
-# what a video actually is: codec, size, fps, duration, bitrate, audio
-ffprobe -v error -show_entries stream=codec_type,codec_name,width,height,r_frame_rate:format=duration,bit_rate,size -of compact input.mp4
-```
-
-(On macOS, `find -printf` is unavailable: use `du -k` over the same globs.)
-
-List every file over budget with its role (hero, ambient, content, poster), then fix them in this order: videos, images, models, fonts. Replace references in code to point at the optimized files; never optimize in place over the source.
-
-## 3. Video with ffmpeg
-
-Decorative and hero loops: strip audio, cap at 30fps, never upscale, trim to the loop.
-
-```bash
-# WebM (VP9), primary source. CRF 32 to 36 for ambient, 28 to 32 for a hero that people look at.
-ffmpeg -i input.mov -t 10 -an -vf "scale='min(1920,iw)':-2,fps=30" \
-  -c:v libvpx-vp9 -crf 32 -b:v 0 -pix_fmt yuv420p -row-mt 1 -deadline good -cpu-used 2 \
-  public/media/hero.webm
-
-# MP4 (H.264), fallback. faststart so playback starts before the download ends.
-ffmpeg -i input.mov -t 10 -an -vf "scale='min(1920,iw)':-2,fps=30" \
-  -c:v libx264 -preset slow -crf 24 -profile:v high -pix_fmt yuv420p -movflags +faststart \
-  public/media/hero.mp4
-
-# Mobile variant: same commands with min(1080,iw) and one CRF step higher.
-
-# Poster from a representative frame (pick the second, never a black first frame)
-ffmpeg -ss 2.5 -i input.mov -frames:v 1 -vf "scale='min(1920,iw)':-2" -c:v libwebp -quality 80 public/media/hero-poster.webp
-```
-
-```tsx
-<video autoPlay muted loop playsInline preload="metadata" poster="/media/hero-poster.webp">
-  <source src="/media/hero.webm" type="video/webm" />
-  <source src="/media/hero.mp4" type="video/mp4" />
-</video>
-```
-
-- Under `prefers-reduced-motion` or Save-Data, show the poster and do not autoplay.
-- Pause offscreen loops (IntersectionObserver); keep one decoding video per viewport.
-- A scroll-scrubbed video sequence is better as a WebP frame sequence on a canvas than as `currentTime` scrubbing, which stutters on most browsers: `ffmpeg -i input.mov -vf "fps=24,scale='min(1440,iw)':-2" -c:v libwebp -quality 75 frames/%04d.webp`, then cap the count (120 to 180 frames).
-
-## 4. Images
-
-Use `next/image` for everything it can serve: it negotiates AVIF and WebP and resizes per `sizes`. Set `images.formats = ["image/avif", "image/webp"]` in `next.config`. What it cannot fix is a 12MB source in the repo, so normalize sources first:
-
-```bash
-# one-off with sharp-cli: cap sources at 2400w and convert to high-quality WebP
-npx sharp-cli -i "assets/raw/*.{jpg,png}" -o public/images/ resize 2400 --withoutEnlargement -f webp -q 82
-```
-
-- The LCP hint on exactly one image, the LCP image of that page: `preload` or `priority`, whichever the installed `next/image` declares ([setup.md](setup.md) §0, Known API shifts). Never `fetchPriority="high"` without `loading="eager"`; on a lazy image the hint does nothing.
-- `sizes` on every large image, matching the layout (`(min-width: 1024px) 50vw, 100vw`).
-- Width and height, or `fill` inside a sized frame, on every image: that is CLS.
-- PNG only for real transparency that WebP cannot carry; GIF never (convert to a muted video loop).
-- The grade from [imagery.md](imagery.md) is applied before export, not with CSS filters at runtime.
-
-## 5. 3D models and textures
-
-```bash
-# one command: dedupe, weld, meshopt geometry, WebP textures capped at 2048,
-# with the scene graph kept intact
-npx @gltf-transform/cli optimize input.glb public/models/product.glb \
-  --compress meshopt --texture-compress webp --texture-size 2048 \
-  --flatten false --join false
-```
-
-- `--flatten false --join false` keep the node hierarchy and names. The defaults flatten the scene and merge meshes, which drops the node names that rigs, `useGLTF` lookups and per-part animation target. Drop the two flags only for a static, single-object model that nothing addresses by name.
-- drei's `useGLTF` takes meshopt as a boolean and ships its own decoder: `useGLTF(url, true, true)` (Draco on, meshopt on). The Draco decoder is fetched only for a Draco-compressed file; self-host it once with `useGLTF.setDecoderPath("/draco/")` at module level in the island. See [webgl-scenes.md](webgl-scenes.md) §1.
-- Textures are usually the weight, not geometry: 2048 max on desktop, 1024 for mobile variants.
-- Every model loads when its island mounts. `useGLTF.preload` buys nothing inside the lazy island (it runs only when the island chunk loads), and calling it from the section pulls three into the page bundle; the poster covers the wait.
-- Always ship the poster image that stands in before and instead of the canvas ([webgl-r3f.md](webgl-r3f.md)).
-
-## 6. Fonts
-
-- Two families, WOFF2 only, variable files where they exist. `next/font` self-hosts and subsets Google fonts automatically; for local files subset to the languages used.
-- Preload the display and the body face, nothing else.
-- `adjustFontFallback` (default in `next/font`) to keep CLS near zero when the face swaps.
-- The TTF kept for OG images lives outside `public/` so it is never shipped to browsers ([seo.md](seo.md)).
-
-## 7. Code
-
-- **Lazy WebGL.** three.js, R3F, Drei and postprocessing load only inside the island, via `next/dynamic` with `ssr: false`. They must never appear in the first-load bundle.
-- **One clock.** Lenis, ScrollTrigger and R3F all on `gsap.ticker` ([setup.md](setup.md)); a second requestAnimationFrame loop is a performance bug, not a style choice.
-- **Animate transforms and opacity only.** Never `top`, `left`, `width`, `height` or `filter: blur()` on scroll. `clip-path` and masks are fine for reveals.
-- **No React state per frame.** Scroll and pointer values go to refs, CSS variables or uniforms ([webgl-r3f.md](webgl-r3f.md) §3).
-- **`will-change` only while animating**, set and cleared by the timeline, never globally.
-- **Clean up.** Every `useGSAP` scope reverts on unmount; route changes must not leave ScrollTriggers, tickers or canvases alive ([route-transitions.md](route-transitions.md)).
-- **Register only the GSAP plugins in use.**
-
-## 8. Verify
-
-1. **Build for production and serve it** (`next build && next start -p <port>`, or `vite build && vite preview --port <port>`). Never measure or shoot the dev server. **Confirm the port belongs to the server you just started:** before starting, `lsof -i :<port>` (Windows: `netstat -ano | findstr :<port>`) shows nothing; after, it shows the PID of that production process. A dev server left running on the same port answers every request silently, and `next start` then fails with `EADDRINUSE` in a log nobody reads.
-2. **First-load JS.** Turbopack builds print no per-route "First Load JS" table, so measure it from the served HTML. The script also proves three.js is absent on touch and arrives lazily on desktop:
-
-   ```js
-   // scripts/firstload.mjs: node scripts/firstload.mjs http://localhost:<port>
-   import { gzipSync } from "node:zlib";
-   import { chromium } from "playwright";
-
-   const base = process.argv[2];
-   const html = await (await fetch(base + "/")).text();
-   const srcs = [...new Set([...html.matchAll(/<script[^>]+src="([^"]+)"/g)].map((m) => m[1]))];
-   const THREE = /WebGLRenderer|WebGL2RenderingContext|react-three-fiber/;
-   let raw = 0, gz = 0;
-   const hits = [];
-   for (const s of srcs) {
-     const buf = Buffer.from(await (await fetch(new URL(s, base))).arrayBuffer());
-     raw += buf.length; gz += gzipSync(buf).length;
-     if (THREE.test(buf.toString("utf8"))) hits.push(s);
-   }
-   console.log(`first-load: ${srcs.length} scripts, ${(raw / 1024).toFixed(1)} kB raw, ${(gz / 1024).toFixed(1)} kB gzip`);
-   console.log(`three.js in first load: ${hits.length ? hits.join(", ") : "none"}`);
-
-   const browser = await chromium.launch({ args: ["--use-angle=swiftshader", "--enable-unsafe-swiftshader"] });
-   for (const [name, opts] of [
-     ["desktop", { viewport: { width: 1440, height: 900 } }],
-     ["phone", { viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true }],
-   ]) {
-     const page = await browser.newPage(opts);
-     const js = [];
-     page.on("response", async (r) => {
-       if (!r.url().endsWith(".js")) return;
-       try { const b = await r.body(); js.push({ kb: b.length / 1024, three: THREE.test(b.toString("utf8")) }); } catch {}
-     });
-     await page.goto(base, { waitUntil: "networkidle" });
-     await page.waitForTimeout(1500);
-     const lazy = js.filter((j) => j.three);
-     console.log(`${name}: ${js.length} JS files; three.js chunks ${lazy.length} (${lazy.reduce((a, b) => a + b.kb, 0).toFixed(1)} kB raw)`);
-     await page.close();
-   }
-   await browser.close();
-   ```
-
-3. **LCP and CLS: an in-page probe** under 4x CPU and a throttled network (about 1.6 Mbps down, 150ms latency), mobile 390 and desktop 1440. It names the LCP element, which is the number that matters: with a hidden split hero or a match cut, the LCP element is whatever appears last, and on an unthrottled local server the figure is meaningless (a text hero measures 150ms locally).
-
-   ```js
-   // scripts/vitals.mjs: node scripts/vitals.mjs http://localhost:<port>
-   import { chromium } from "playwright";
-
-   const base = process.argv[2];
-   const browser = await chromium.launch();
-   for (const [label, opts] of [
-     ["mobile 390", { viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true }],
-     ["desktop 1440", { viewport: { width: 1440, height: 900 } }],
-   ]) {
-     const ctx = await browser.newContext(opts);
-     const page = await ctx.newPage();
-     const cdp = await ctx.newCDPSession(page);
-     await cdp.send("Emulation.setCPUThrottlingRate", { rate: 4 });
-     await cdp.send("Network.enable");
-     await cdp.send("Network.emulateNetworkConditions", {
-       offline: false, latency: 150, downloadThroughput: (1.6 * 1024 * 1024) / 8, uploadThroughput: (750 * 1024) / 8,
-     });
-     await page.addInitScript(() => {
-       const v = { lcp: 0, cls: 0, el: "" };
-       Object.assign(window, { __vitals: v });
-       new PerformanceObserver((list) => {
-         for (const e of list.getEntries()) {
-           v.lcp = e.startTime;
-           const el = e.element;
-           v.el = el ? `${el.tagName} ${(el.getAttribute("src") ?? el.textContent ?? "").slice(0, 60)}` : "";
-         }
-       }).observe({ type: "largest-contentful-paint", buffered: true });
-       new PerformanceObserver((list) => {
-         for (const e of list.getEntries()) if (!e.hadRecentInput) v.cls += e.value;
-       }).observe({ type: "layout-shift", buffered: true });
-     });
-     await page.goto(base, { waitUntil: "load" });
-     await page.waitForTimeout(5000);           // let timed entrances finish: their content is often the LCP
-     await page.mouse.wheel(0, 600);            // LCP stops recording at the first input
-     await page.waitForTimeout(500);
-     const v = await page.evaluate(() => window.__vitals);
-     console.log(`${label}: LCP ${(v.lcp / 1000).toFixed(2)}s (${v.el.trim()}), CLS ${v.cls.toFixed(3)}`);
-     await ctx.close();
-   }
-   await browser.close();
-   ```
-
-   Lighthouse (or PageSpeed Insights on the deploy) on the home page and one inner page is the second opinion. Lab tools report TBT, not INP: INP needs field data (PageSpeed's CrUX panel once the site has traffic) or a manual interaction trace in the performance panel (click the menu, a hover scene and a form control; read the longest interaction). Until then write "INP: field data pending" with the TBT number.
-4. **Frame trace for timed entrances.** A PNG at rest cannot show a hold that fires over an empty frame, a split hero that flashes unsplit, or a reveal stuck at opacity 0. Capture the first 3 seconds and look at the frames in order:
-
-   ```js
-   // scripts/trace.mjs: node scripts/trace.mjs http://localhost:<port>  (writes shots/trace-<w>-NN.png)
-   import { mkdirSync } from "node:fs";
-   import { chromium } from "playwright";
-
-   const base = process.argv[2];
-   mkdirSync("shots", { recursive: true });
-   const browser = await chromium.launch();
-   for (const [w, h, mobile] of [[1440, 900, false], [390, 844, true]]) {
-     const page = await browser.newPage({ viewport: { width: w, height: h }, isMobile: mobile, hasTouch: mobile });
-     const t0 = Date.now();
-     await page.goto(base, { waitUntil: "commit" });
-     for (let i = 0; i < 15; i++) {
-       await page.screenshot({ path: `shots/trace-${w}-${String(i).padStart(2, "0")}.png` }).catch(() => {});
-       console.log(`${w} frame ${i}: ${Date.now() - t0}ms`);
-       await page.waitForTimeout(200);
-     }
-     await page.close();
-   }
-   await browser.close();
-   ```
-
-   Each entrance must do what its recipe says: the hold frame of a match cut is the photo ([page-entrances.md](page-entrances.md)), the split hero never shows unsplit, nothing stays invisible ([pitfalls.md](pitfalls.md) §3).
-5. Scroll the full page with the browser's performance panel recording: no long tasks during scroll, frames steady through the pinned showpiece.
-6. Re-run the size listing from §2 on the output: nothing over budget without a written reason in STRUQ.md.
-
-The scripts use the `playwright` package (`npm i -D playwright`, then `npx playwright install chromium`); any harness browser tool that can throttle, observe and screenshot does the same job.

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

@@ -1,341 +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">
-              <span className="eyebrow text-eyebrow text-ink-muted">{p.kicker}</span>
-              <h3 className="font-display text-h2 mt-4">{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="eyebrow text-eyebrow">{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, eyebrow 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.