@struq/skill 0.3.0 → 0.4.1

package/skills/struq/references/direction.md

@@ -1,188 +0,0 @@
-# Direction: plan everything before the first component
-
-Award-tier sites are decided before they are built. The logo, the one idea the site is about, the two typefaces, the palette, the icon family, the arc and the showpieces are made once, together, so every later choice can be checked against them. A build that discovers its direction while coding ends up with a Tailwind default and a nice hero.
-
-This file is the orchestrator for **Build**, **Redesign** and the planning half of **Directed**. It runs seven phases, numbered 0 to 6, with one gate between planning and building. It writes one contract file, `STRUQ.md` in the project root, and that file is the only plan artifact: there is no second plan block, no separate brief document, no parallel folder for a normal build.
-
-## The phases
-
-| # | Phase | Output (a section of STRUQ.md) | Procedure | Skip when |
-|---|---|---|---|---|
-| 0 | **Intake** | header (Mode, Stack), MATERIALS | this file §1, with [brief-router.md](brief-router.md) §1 and §1b | never |
-| 1 | **Brand** | BRAND | [brand.md](brand.md) | a brand exists (extract it, §2) |
-| 2 | **Concept** | CONCEPT | this file §3; the tension from [brief-router.md](brief-router.md) §1 | never |
-| 3 | **System** | SYSTEM | this file §4 (sole owner of type, palette, icons, imagery, motion) | never |
-| 4 | **Site plan** | PLAN | [brief-router.md](brief-router.md) §2 | never |
-| Gate | **Approval** | one message: summary, materials request, "Akkoord?" | this file §5 | never: it is the one stop, and there is no second |
-| 5 | **Build** | the site | [../SKILL.md](../SKILL.md) workflow steps 2 to 7 | |
-| 6 | **Verify** | VERIFY | [../SKILL.md](../SKILL.md) workflow step 8 | never |
-
-Phases 0 to 4 together are workflow step 1, **Direction**, in [../SKILL.md](../SKILL.md). Directed mode (`/struq direct`) runs phases 0 to 3 here, then hands over to [../cinematic/README.md](../cinematic/README.md), whose lean outputs are appended to the same STRUQ.md as a DIRECTION section.
-
-**Scale the ceremony to the job.** A one-page site for an existing brand runs phases 0, 2, 3 and 4 in a few minutes. A new company with no name runs all of them. Never ask a question the brief already answers; never skip a phase because it feels obvious. Write the obvious answer down, because the later phases read it.
-
-## 1. Intake
-
-**One stop, not two.** With a usable brief, do not block here. Run the extraction in [brief-router.md](brief-router.md) §1 silently, record what exists under MATERIALS, record what is missing (and how each gap is handled) under MATERIALS and ASSUMPTIONS, and carry on to the gate. The request for materials goes inside the single gate message (§5). Block early only when the wizard trigger conditions in [brief-router.md](brief-router.md) §1b hold: no usable brief, a request to be guided, or no answer to "who buys" and "what are they afraid of".
-
-What MATERIALS tracks:
-
-- Name and logo (files, not descriptions)
-- Brand colors and fonts, if any are fixed
-- Real copy, or at least the facts: what it is, who it is for, what it costs, where it is
-- Photos, product shots, video, 3D models
-- Real numbers (clients, years, results) and real quotes, with permission
-- An existing site (switch to Redesign: [triage.md](triage.md))
-- One or two sites whose feel they envy
-
-**Never invent proof.** Testimonials, client logos, stats and awards that do not exist are left out, not faked.
-
-**Never write in a real person's or brand's voice.** On a site named after a real person or a real business:
-
-- No first person attributed to them ("I make those decisions...") and no quotes in their name. Write in the studio's or the site's third-person voice.
-- No biography, training, process or sourcing stated as fact ("trained as a production thrower", "eats at the restaurant before drawing", "clay dug in Alentejo") unless the brief says it.
-- No catalogue facts: invented works, sizes, glazes, materials, prices, editions, sold-out states, stockists or client names.
-
-When the layout needs that copy to exist, draft it as plain layout copy and list every drafted claim under ASSUMPTIONS ("Studio paragraph: drafted, replace with Ana's words"; "Work index: 8 entries drafted as layout copy, no prices, no client names"). A portfolio with no work list gets its entries drafted the same way, titled as layout copy, never as the record. The gate message names the drafts so the client can replace them.
-
-**No real imagery yet.** Plan for it instead of papering over it:
-
-- Media-led showpieces work from the first build: the beeldbank pack supplies the photos. Never stage one on empty frames.
-- Every missing image becomes a shot-list line (subject, grade, ratio) under PLAN `Assets to produce`, so it can be shot, sourced or generated later ([imagery.md](imagery.md) §4).
-- In the build, every image slot is filled from the Struq beeldbank pack ([struq-imagery.md](struq-imagery.md)), automatically and without asking: the images are CC0. A frame is never empty and never a placeholder.
-
-## 2. Brand
-
-If there is no name or no logo, run [brand.md](brand.md). It produces a name shortlist with one recommendation, a wordmark and a mark as SVG, a favicon set, and one voice line; the OG image is built later, once routes exist ([seo.md](seo.md) §3). If a brand exists, extract it instead: logo file, the exact colors, the fonts, how they write. Existing brand assets always beat the preset; the preset still supplies the token structure they pour into.
-
-| What exists | Run |
-|---|---|
-| Nothing | [brand.md](brand.md) in full |
-| A name, no logo, no brand | [brand.md](brand.md) §1 and §3 to §5: skip naming |
-| **A named brand (colours, a font, a voice) but no logo file** | Skip [brand.md](brand.md) §1 and §2: never rename, never reposition. Draw a **provisional** wordmark from the brand's own face ([brand.md](brand.md) §3), write it to the same paths (`brand/logo.svg`, `brand/mark.svg`) so the real logo drops in, and record it under ASSUMPTIONS: "Logo: provisional wordmark from <face>, replace with the brand file" |
-| A full brand with logo files | Extract only; no [brand.md](brand.md) |
-
-**Person-named sites skip naming.** Portfolios, studios named after a person, practices and clinics use the person's name. If the name is unknown, write a placeholder, record it under ASSUMPTIONS, skip [brand.md](brand.md) §2 and go straight to the wordmark (§3 there).
-
-## 3. Concept
-
-The concept is what makes the site feel authored instead of assembled. Write three lines:
-
-- **Idea:** one sentence the whole site is about, specific to this client. Not "modern and clean"; "every page is a quiet room with one object in it" or "the site moves like a slow pan across a construction drawing".
-- **Tension:** what the visitor needs to feel (convince) and what the site must never signal (never). From [brief-router.md](brief-router.md) §1 question 2.
-- **Motif:** the one recurring visual device that carries the idea through the page. A line that draws through every section, a frame that every image sits in, a numeral system, a crop direction, a mark that morphs. One motif, used everywhere, beats five effects used once.
-
-Every later decision gets checked against these three lines. If a showpiece or effect does not serve the idea or the motif, it goes.
-
-## 4. System
-
-This section is the only place SYSTEM is decided. Other files point here.
-
-**Read budget.** During planning, read only the Decide-here section at the top of [typography.md](typography.md) and of [iconography.md](iconography.md), the token contract and the one chosen preset in [vibe-presets.md](vibe-presets.md), and the grade table in [imagery.md](imagery.md) §1. Two more reads are planning reads, not build reads, when they apply: the preset's **hero entrance** recipe ([page-entrances.md](page-entrances.md) for `match-cut-hero` and `clip-line-hero`, on any site), and, when the brief asks for 3D, the **WebGL plan** ([webgl-r3f.md](webgl-r3f.md) §1 and [webgl-scenes.md](webgl-scenes.md) §5: poster, gate, touch fallback, and the "No model file yet" ladder in §4). Read the full files during the build (workflow step 2), not now.
-
-Decide in this order:
-
-0. **Niche.** Buyer, genre and preset from [brief-router.md](brief-router.md) §2 step 1, plus the one borrowed field (TYPE or PALETTE) if any.
-1. **Type.** Exactly two faces: display (run light, 300 to 400, unless the concept is a declared heavy genre) and text. Take a pairing id from the brand's temperament per [typography.md](typography.md) Decide here: Signature (S1 to S7) first, Extended (E1 to E6) only when no Signature temperament fits. "Unsure" is not a temperament and never a reason to take S1. Name the faces, the role weights, the source and the license, the **one signature move** ([typography.md](typography.md) §5) and the **hero entrance** (the preset's named entrance, or a declared different one).
-2. **Palette.** Surface ladder (four steps), ink tiers (ink, muted, faint), one accent and the line color, written as tokens. Existing brand colors pour into this structure. Add the radius. [vibe-presets.md](vibe-presets.md)
-
-   **Brand colours onto the ladder.** A brand's colour names are not token names: brand "ink" usually means the brand's dark, while `--color-ink` is the *text* colour. Map by role, never by name:
-
-   | Brand colour | On a light preset | On a dark preset |
-   |---|---|---|
-   | The brand's dark | `ink` (text), and the inverted surfaces | `surface-0` (the page); `ink` becomes an off-white |
-   | The brand's light | `surface-0` (the page) | `ink` (text) |
-   | The brand's accent | `accent` | `accent` |
-
-   Derive the rest of the ladder from the mapped pair (surfaces step toward the ink, muted and faint tiers mixed from ink). Check the accent against `surface-0`: 4.5:1 or better and it may be text (links); 3:1 or better and it may set large type and UI; below that it is fills and rules only. Write which under SYSTEM.
-3. **Icons.** One icon family for the whole site, chosen by the order in [iconography.md](iconography.md) §2: the brand's own set, else Struq Icons. Name the package, the stroke and how its accent maps to the palette.
-4. **Imagery.** One grade, the declared ratio set (2 to 3), grain yes or no. [imagery.md](imagery.md)
-5. **Scroll and motion.** Lenis lerp (or native, with the reason). Motion is the baseline MOTION line in [../SKILL.md](../SKILL.md) by default: write "baseline". Any other duration band or ease pair, including the alternative pairs in [feel-layer.md](feel-layer.md) §3, is an allowed deviation only when it is written here with its reason.
-
-## 5. The gate
-
-Write `STRUQ.md` (template below), then send one message with: the name, the idea line, the two typefaces and pairing id, the signature move and hero entrance, the palette as hex, the icon family, the arc as one line, the showpiece ids, the open assumptions, and the materials request. End it with exactly this:
-
-> **Akkoord? Heb je een logo, foto's of echte cijfers, stuur ze nu.**
-
-Apply edits and new materials to the file; do not re-interview. This is the only stop between the brief and the build (the wizard in [brief-router.md](brief-router.md) §1b is the one exception, and it runs before this gate, not instead of it).
-
-If the user said "just build it", or the run is non-interactive, write the file, state the assumptions at the top and continue.
-
-## 6. During the build
-
-`STRUQ.md` is the contract. Before each workflow step, re-read the section it depends on. If a decision has to change during the build (a font does not have the weight, an asset is missing), change it **in the file first**, with one line under LOG saying why, then change the code. A site that drifts from its own plan is how a directed build turns back into a template.
-
-After verify, append the score and the open issues under VERIFY.
-
-## STRUQ.md template
-
-```markdown
-# STRUQ.md: <project name>
-
-Mode: build | redesign | directed
-Stack: <Next.js | Vite> <installed major> · React <major> · Tailwind <major> · GSAP <x.y> · Lenis <major> · three <0.x> (if used), read from package.json (setup.md §0); Vite translations per stack-targets.md
-
-## MATERIALS
-Have: <logo, copy, photos, numbers, quotes>
-Missing: <list, with how each gap is handled>
-References: <sites the client envies, and what to take from each>
-
-## BRAND
-Name: <name> (shortlist and rationale in brand/NAMING.md, if generated)
-Logo: brand/logo.svg (wordmark), brand/mark.svg (mark), app/icon.svg, app/apple-icon.png
-OG: app/opengraph-image.tsx, plus one per shared route (seo.md §3)
-Voice: <one line, e.g. "plain, certain, a little dry; short sentences; no exclamation marks">
-
-## CONCEPT
-Idea: <one sentence>
-Tension: convince <...> / never signal <...>
-Motif: <the one recurring device>
-
-## SYSTEM
-Niche: <buyer + business model> · genre <Portfolio | Studio | Product launch | Campaign>
-  · preset <Soft Modern | Warm Editorial | Dark Cinematic | Luxury Minimal | Brutalist (genre appendix, declared genre only)>
-  [+ borrowed TYPE or PALETTE from <preset>]
-Display: <face> <weight> (<source>, <license>) · pairing <S1 to S7 | E1 to E6>
-Text: <face> <weights> (<source>, <license>)
-Signature move: <weight-in | soft-scrub | type-mask-media | fit-width-wordmark | cropped display>
-Hero entrance: <the preset's named entrance, or a declared different one>
-Palette: <light | dark> · --surface-0 #... --surface-1 #... --surface-2 #... --surface-3 #...
-  --ink #... --ink-muted #... --ink-faint #... (non-text only) --accent #... --line <...>
-Radius: <n>px
-Icons: <family, package, stroke> (default: Struq Icons, @struq/icons, strokeWidth 1.5, accent = --color-accent)
-Imagery: <grade>, ratios <2 to 3>, grain <opacity | none>
-Scroll: Lenis lerp <the preset's stated value | native, because ...> on gsap.ticker
-Motion: baseline | deviations: <each one, with its reason>
-
-## PLAN
-Pages: <list with slugs>
-Arc (home): <numbered rows: section [beat] note, spacing role>; proof form; grid-breaks
-Reveals: headlines <...> · blocks <...> · images <...> · svg <moment | none>
-Showpieces: <showpiece ids, arc row, mobile fallback> (1 to 2, breathers on both sides; a showpiece is its own density class, page-architecture.md §3)
-System recipes: <system ids: line-rise-hero, route-curtain, fullscreen-menu ...>
-Transitions: <route-curtain variant | none>, loader <yes | no>
-WebGL: <none | the moment, its poster, its fallback>
-Copy budget: <per section>
-Assets to produce: <shot list: subject, grade, ratio, source>
-
-## PRESERVED (redesign only)
-- <what will not be touched: brand color, copy, component primitives>
-
-## ASSUMPTIONS
-- <every decision made without the user's input>
-- <every drafted claim: copy in a real person's or brand's name, catalogue entries, a provisional logo, a 3D stand-in>
-
-## LOG
-- <date> <decision changed and why>
-- <date> <API>: installed <pkg major> differs from the skill's code; adapted to <change> (setup.md §0)
-
-## VERIFY
-Server: next start on :<port>, port owner confirmed
-Viewports: 390, 768, 1440, 1920
-Score: <n>/100 · LCP <s> (element) CLS <n> INP <ms | field data pending> · first-load JS <n> kB gzip
-Motion: pins engaged slow and fast <ok>, descender test <ok>, frame trace <ok>
-Open: <issues>
-```
-
-Directed mode appends `## DIRECTION` after PLAN, per [../cinematic/README.md](../cinematic/README.md).

package/skills/struq/references/feel-layer.md

@@ -1,107 +0,0 @@
-# The Feel Layer: Values You'd Actually Ship
-
-Techniques are copyable; feel is in the numbers. Two builds can run the same code and one feels like Locomotive while the other feels like a tutorial. The delta is lerp values, scrub smoothing, ease pairing, and duration scale. This file is the tuning reference for everything else in the skill.
-
----
-
-## 1. Lenis: the scroll's personality
-
-Lenis interpolates real scroll position toward the target each frame. `lerp` is the fraction covered per frame: **lower = floatier, heavier; higher = tighter, more direct.** This single number sets the personality of the entire site, because every scrub-tied effect inherits it.
-
-| lerp | Feel | Ship it for |
-|---|---|---|
-| 0.05-0.07 | syrup-heavy, luxurious, slightly defiant | luxury/fashion one-pagers, short narrative scrolls. Risky: long pages feel slow to operate |
-| **0.09-0.11** | **weighted but obedient (the default)** | **portfolios, studios, most marketing** |
-| 0.12-0.16 | light glide, barely-smoothed | content-heavy marketing, editorial with lots of reading |
-| (no Lenis) | native | dashboards, docs, apps: smoothing a tool insults the user |
-
-Decision rule: the more *reading* per viewport, the higher the lerp; the more *imagery*, the more floor you can afford. Alternative: `duration: 1.2` + `easing` (Lenis's time-based mode) instead of `lerp`. Same idea, easier to reason about as "a scroll impulse takes ~1.2s to settle." Pick one mode, don't set both.
-
-Always:
-- `autoRaf: false` + GSAP ticker + `lagSmoothing(0)` ([setup.md](setup.md)): two clocks = micro-jitter on every scrub.
-- `anchors: true` so in-page links still work.
-- Under `prefers-reduced-motion`, keep Lenis mounted and gate the motion it drives (pins, parallax, scrub showpieces) in `matchMedia` branches, as [setup.md](setup.md) §2 and §4 wire it. Returning early from the provider makes native scroll look like a broken setup.
-
----
-
-## 2. Scrub: direct drive vs. smoothed
-
-`scrub: true` = value locks to scroll position exactly. `scrub: <n>` = value *chases* scroll position over ~n seconds: scroll stops, animation eases into place.
-
-| Value | Feel | Use for |
-|---|---|---|
-| `true` | mechanical 1:1, instant stop | things that must feel *attached*: hero departure, progress bars, curtains the user "drags," marquee drift |
-| `0.5-1` | weighted, settles after the hand stops | **default for transforms**: parallax layers, pinned sequences, horizontal scroll |
-| `1.5-2.5` | cinematic float, noticeable lag | large background media, ambient/atmospheric layers |
-| `>3` | detached, reads as broken | nothing |
-
-Two interacting smoothings: Lenis already smooths the scroll *input*; scrub smooths the *output* on top. Lenis at 0.1 + `scrub: 1` is the classic pairing. If you stack Lenis 0.06 + scrub 2.5, the page feels drunk. Rule: **lower Lenis lerp → lower scrub numbers.**
-
-Mixed rates in one section are the pro move: hero title at `scrub: true` (attached), background media at `scrub: 1.5` (floating behind it). The differential *is* the depth.
-
----
-
-## 3. Ease pairing: the system, not the menu
-
-Full curve table lives in [transitions.md](transitions.md). The shipping system:
-
-**The default system is the baseline MOTION line in [../SKILL.md](../SKILL.md), and these are the same numbers:**
-
-| Role | Ease | GSAP name | CSS |
-|---|---|---|---|
-| Entrances | expo-out | `expo.out` | `cubic-bezier(0.16, 1, 0.3, 1)` |
-| Exits | power2-in (cubic-in) | `power2.in` | `cubic-bezier(0.32, 0, 0.67, 0)` |
-| Position swaps (A to B moves) | quart-in-out | `power3.inOut` | `cubic-bezier(0.76, 0, 0.24, 1)` |
-| Curtains and panels | quint-in-out | `power4.inOut` | `cubic-bezier(0.83, 0, 0.17, 1)` |
-
-GSAP's names are offset by one from the classic curve names: `power1` = quad, `power2` = cubic, `power3` = quart, `power4` = quint.
-
-**Allowed deviations, recorded in STRUQ.md SYSTEM with a reason.** A preset or concept may swap the pair; it is never a silent per-component choice:
-- *Kinetic*: `power4.out` (quint-out) entrances + `back.out(1.4)` accents (crisp, springy)
-- *Editorial-calm*: `power3.out` (quart-out) entrances + `power2.inOut` moves (nothing shouts)
-
-Then three rules:
-1. Entrances out-ease, exits in-ease (`power2.in`), A→B moves in-out. Never the reverse.
-2. Scrubbed tweens: `ease: "none"` for tracking values; segment eases (power2) only *inside* scrubbed timelines for phase swaps.
-3. `back`/`elastic` are accent spices: ≤1 element type per page (toast, badge, magnetic return). Two springy things = toy.
-
----
-
-## 4. Duration & stagger scale
-
-Durations scale with **visual mass** (size × contrast of the change), not importance. A 90vw image takes 1.2s; a 14px tag takes 0.25s; same duration on both makes one feel sluggish and the other twitchy.
-
-| Tier | Duration | Examples |
-|---|---|---|
-| Micro | 0.2 to 0.3s | press, toggles, underline, tag slide |
-| Standard UI | 0.3 to 0.6s | dropdowns, card hovers, accordion, text swap |
-| Reveal | 0.6 to 1.0s | section entrances, split lines, masked images |
-| Hero and cinematic | 1.0 to 1.6s | hero entrance, page curtain + content rise, full-bleed media |
-| Over 1.6s | n/a | only multi-part timelines; a single tween this long = user waiting |
-
-These bands are the baseline's, number for number. A different band is a deviation and goes into STRUQ.md SYSTEM with its reason.
-
-Exits run about 60% of their entrance's duration (leaving is decisive; see [transitions.md](transitions.md) §4).
-
-Stagger:
-
-| each | Feel | Use |
-|---|---|---|
-| 0.02-0.04 | texture: perceived as one rich motion | chars, long lists (12+) |
-| **0.06-0.1** | **readable rhythm (the default)** | cards, lines, nav items |
-| 0.12-0.18 | deliberate, editorial | 2-4 big blocks |
-| >0.2 | queueing: last item enters embarrassingly late | avoid; for n items keep `each × n ≤ ~0.8s` |
-
-`stagger: { each: 0.08, from: "center" | "edges" | "random" }`: vary the origin by composition (centered logo walls from `"center"`, grids from `"start"`, particle-ish textures `"random"`).
-
----
-
-## 5. The 60-second feel audit
-
-Scroll the build top to bottom once, then:
-
-1. **Stop scrolling abruptly mid-section.** Do scrubbed layers settle softly (good) or freeze instantly (raise scrub) or keep drifting awkwardly (lower it)?
-2. **Watch one entrance.** Can you see it *end*? If you can't perceive the deceleration tail, the ease or duration is too timid. This is the #1 "feels like a template" cause even when the technique is right.
-3. **Count layers in a hover.** One moving layer = cheap, two or three = choreography.
-4. **Flick-scroll the whole page.** Does the site stay composed (Lenis + scrub doing their job) or strobe with triggered animations firing everywhere? If strobing: too many `once` reveals triggered too late (move starts earlier, e.g. `top 85%`).
-5. **Is anything moving that the user didn't cause?** Autonomous looping motion (except one deliberate marquee/ambient element) drains the premium feel. Agency motion is overwhelmingly *response*, not *activity*.

package/skills/struq/references/gsap-api.md

@@ -1,293 +0,0 @@
-# GSAP API: the 15% this skill actually uses
-
-This is not a GSAP manual. It's the exact API surface the technique files rely on, so the skill needs no external reference. Everything imports from the `@/lib/gsap` registry ([setup.md](setup.md) §1); every animating component follows the `useGSAP` rules ([setup.md](setup.md) §3).
-
----
-
-## 1. Tweens & timelines
-
-```ts
-gsap.to(target,     { x: 100, duration: 0.8, ease: "expo.out" });   // current → values
-gsap.from(target,   { y: 48, autoAlpha: 0 });                        // values → current (SSR HTML is the final state; prefer this)
-gsap.fromTo(target, { yPercent: -8 }, { yPercent: 8, ease: "none" }); // explicit both ends
-gsap.set(target,    { autoAlpha: 0 });                               // instant, no tween
-```
-
-- `target` = element, ref `.current`, selector string (scoped inside `useGSAP`), or array.
-- **`autoAlpha`** = opacity + `visibility`. Use it instead of `opacity` for entrances so hidden elements can't intercept clicks.
-- **Stagger object:** `stagger: { each: 0.08, from: "start" | "center" | "edges" | "end" | "random", grid: [rows, cols] }`. Plain `stagger: 0.08` = shorthand for `each`.
-- **`gsap.defaults({ ease, duration })`**: set once in the registry so every tween starts agency-grade.
-
-**Timelines** sequence tweens; the *position parameter* (third argument) is the craft:
-
-```ts
-const tl = gsap.timeline({ defaults: { ease: "expo.out", duration: 1 } });
-tl.from(a, {...})            // starts at 0
-  .from(b, {...}, "-=0.4")   // overlaps: starts 0.4s before previous ends
-  .from(c, {...}, "<")       // starts WITH the previous tween
-  .from(d, {...}, "<0.15")   // 0.15s after the previous tween's START
-  .from(e, {...}, "+=0.2");  // gap: 0.2s after everything ends
-```
-
-Overlapping (`-=` / `<`) reads as one composed gesture; strict sequencing reads as a PowerPoint build ([scroll-reveals.md](scroll-reveals.md)).
-
----
-
-## 2. useGSAP (the React hook)
-
-```tsx
-const { contextSafe } = useGSAP(() => {
-  gsap.from(".card", { y: 40, autoAlpha: 0, stagger: 0.08 }); // ".card" scoped to container
-}, { scope: container });
-
-const onHover = contextSafe(() => gsap.to(".dot", { scale: 1.4 })); // event-handler tweens MUST be wrapped
-```
-
-Everything created inside is auto-killed on unmount (no leaked ScrollTriggers after route changes). Full rules (`"use client"`, scope ref, animate-`from`, no `window` at module scope): [setup.md](setup.md) §3.
-
----
-
-## 3. ScrollTrigger
-
-```ts
-gsap.to(target, {
-  ...,
-  scrollTrigger: {
-    trigger: container.current,
-    start: "top 78%",          // "[trigger-edge] [viewport-edge]"
-    end: "bottom top",         // or "+=250%" (2.5 viewports of scroll-room), or a function
-    scrub: 1,                  // true = locked 1:1; number = seconds of catch-up (feel-layer.md §2)
-    pin: true,                 // freeze the trigger while the scroll distance plays out
-    once: true,                // entrances fire once; scrub effects may repeat
-    snap: { snapTo: 1 / (n - 1), duration: 0.4, ease: "power2.inOut" }, // stepped content only
-    invalidateOnRefresh: true, // re-run function-based values on refresh/resize
-    onUpdate: (self) => { progress.current = self.progress; }, // 0 to 1; mutate refs, never setState
-  },
-});
-// Standalone (no tween): ScrollTrigger.create({ trigger, start, end, scrub, onUpdate })
-```
-
-**The pinning rules (each one is a real failure when skipped):**
-
-1. **Pinning re-parents** the trigger into a generated pin-spacer, so measure and position accordingly; `pinSpacing: false` only when a following section should slide over the pinned one.
-2. **Function-based distances** for anything measured: `x: () => -getDistance()` and `end: () => "+=" + getDistance()`, plus `invalidateOnRefresh: true`. Otherwise resize breaks the mapping.
-3. **`ScrollTrigger.refresh()`** after layout settles (fonts/images loaded, entrance finished). Triggers measured against a mid-animation layout are wrong ([page-entrances.md](page-entrances.md)).
-4. **Never `anticipatePin` with smooth scroll.** Lenis feeds it a smoothed velocity, the prediction overshoots, and the pin engages a frame early then corrects: a visible jerk at the handoff. Full diagnosis: [pinning-scrub.md](pinning-scrub.md) §2.
-5. **One trigger per concern**, not per element: stagger ten cards from one trigger on the parent.
-6. **Never pin on touch.** The matchMedia + scroll-snap fallback in [pinning-scrub.md](pinning-scrub.md) §4 is the law.
-
-Pin symptoms (a jerk, a jump, a snap on first engage, a pin that lands in the wrong place), each with cause, fix and check: [pitfalls.md](pitfalls.md) §2.
-
----
-
-## 4. gsap.matchMedia: responsive + reduced-motion, declaratively
-
-```ts
-const mm = gsap.matchMedia();
-mm.add({
-  motionOK:  "(prefers-reduced-motion: no-preference)",
-  isDesktop: "(min-width: 768px)",
-}, (ctx) => {
-  const { motionOK, isDesktop } = ctx.conditions!;
-  if (!motionOK) return;               // SSR markup is already the final state
-  if (isDesktop) { /* pin/scrub here */ }
-});
-// Or one combined query: mm.add("(min-width: 768px) and (prefers-reduced-motion: no-preference)", () => {...});
-```
-
-Everything created inside a branch **auto-reverts** when the condition stops matching (rotate, resize, OS setting change). No stale pins, nothing to clean up by hand. Never `if (window.innerWidth < 768)` at setup time: it doesn't revert.
-
----
-
-## 5. quickTo: per-frame pointer effects
-
-```ts
-const xTo = gsap.quickTo(el, "x", { duration: 0.4, ease: "power3.out" });
-el.addEventListener("mousemove", (e) => xTo(computeX(e))); // call the function, per frame, cheaply
-```
-
-Pre-compiles one reusable tween per property. For anything updating every frame (magnetic buttons, cursor followers, hide-on-scroll headers): never `setState` per mousemove (React render per frame) and never `gsap.to` per event (allocates a tween per pixel). This is also why those effects stay on GSAP's ticker, not a Motion spring loop: the one-clock rule (see the decision table in [SKILL.md](../SKILL.md)).
-
----
-
-## 6. SplitText (GSAP 3.13 or later)
-
-```ts
-SplitText.create(el, {
-  type: "lines",            // "lines" | "words" | "chars" (chars: short display words only)
-  mask: "lines",            // wraps each line in an overflow-clipped element: the whole effect
-  autoSplit: true,          // re-splits on font load / resize
-  onSplit: (self) =>        // animation MUST live here so re-splits re-run it
-    gsap.from(self.lines, { yPercent: 110, stagger: 0.09, ease: "expo.out", duration: 1.1 }),
-});
-```
-
-Do **not** use the old `new SplitText()` + manual resize listeners. Accessibility is automatic (`aria-label` set on the parent). Craft details (leading, descenders, the scrub variant): [scroll-reveals.md](scroll-reveals.md) §3. SplitText typography choreography in depth: [typography.md](typography.md).
-
----
-
-## 7. Flip: expand-to-detail / shared-element morphs
-
-```ts
-const state = Flip.getState(".card, .card img");  // 1. measure
-container.classList.toggle("expanded");           // 2. change the DOM/layout however you like
-Flip.from(state, {                                // 3. animate FROM the old positions
-  duration: 0.6, ease: "power4.inOut",
-  absolute: true,   // see §7.1: REQUIRES a positioned + height-pinned container
-  nested: true,     // when parents AND children both move
-});
-```
-
-Reach for Flip when the morph must coordinate with scroll or a timeline (card→modal, grid↔list, thumbnail→hero); a simple React-state list→detail swap is Motion `layoutId` territory ([transitions.md](transitions.md) §3, and the decision table in [SKILL.md](../SKILL.md)).
-
-### 7.1 The four Flip failures: read before writing any Flip
-
-Flip has a reputation for "layout shift that nothing fixes" and for fighting the
-page. It is almost always one of these four, and they compound, so fixing one and
-still seeing a jump does **not** mean you were wrong; it means there were two.
-Work the list in order.
-
-**1. `absolute: true` collapses the container.**
-`absolute: true` sets every target to `position: absolute` for the tween's
-duration. If the container derives its height from those in-flow children (any
-CSS grid with `grid-auto-rows`, any auto-height flex/block wrapper), it now has
-zero in-flow children and its height collapses to `0`, then snaps back. Everything
-below lurches up and slams down.
-
-> The older note that `absolute: true` "prevents reflow fighting" is only half
-> true: it prevents *sibling* reflow, and causes *container* collapse. It is not
-> a free win. It is a trade that you must pay for with the two fixes below.
-
-**2. No positioned ancestor → items escape the container.**
-Absolutely-positioned targets resolve offsets against the nearest *positioned*
-ancestor. If the container is not `position: relative`, tiles fly out of its
-coordinate space and render **on top of the next section**. This looks like a
-z-index bug and is not one. Symptom: content overlapping the section below, not
-just shifting.
-
-**3. The height release races the stagger.**
-With `stagger`, the last item lands at `duration + stagger.amount`, and stays
-`position: absolute` until then. Pin the height for only `duration` and it
-releases while items are still out of flow → the same collapse, but *only at the
-very end* of the animation. Symptom: the tween looks perfect, then jumps on the
-final beat.
-
-**4. A CSS `transition` on a property Flip tweens.**
-`Flip.getState(el, { props: 'filter' })` makes GSAP write `filter` inline every
-frame. A CSS `transition: filter …` on the same element re-animates every one of
-those writes. Two systems own one property; the result is mushy, laggy, or stuck.
-Same for `transition: all`. **Never** transition a property you pass to `props`,
-and never use `transition: all` on a Flip target.
-
-### 7.2 The rock-solid pattern (React)
-
-Covers all four. Measure the old height *before* the re-render, pin, tween the
-container in lockstep with the staggered items, release only after the last one
-lands.
-
-```tsx
-const DURATION = 0.8;
-const STAGGER = 0.18;   // shared, so the height tween can never drift out of sync
-
-const gridRef = useRef<HTMLDivElement>(null);
-const flipState = useRef<Flip.FlipState | null>(null);
-const prevHeight = useRef(0);
-
-// Capture in the EVENT HANDLER, before React re-renders.
-const handleChange = (next: Id) => {
-  const grid = gridRef.current;
-  if (grid && !window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
-    prevHeight.current = grid.getBoundingClientRect().height;   // old height
-    flipState.current = Flip.getState(grid.querySelectorAll('[data-flip]'));
-  }
-  setActive(next);
-};
-
-useLayoutEffect(() => {
-  const state = flipState.current;
-  flipState.current = null;
-  if (!state) return;
-  const grid = gridRef.current;
-  if (!grid) return;
-
-  const from = prevHeight.current;
-  const to = grid.getBoundingClientRect().height;  // measure BEFORE pinning
-  gsap.set(grid, { height: from });
-
-  const flip = Flip.from(state, {
-    duration: DURATION, ease: 'power3.inOut', absolute: true,
-    stagger: { amount: STAGGER, from: 'start' },
-  });
-
-  // Outlast the stagger (failure #3).
-  const height = gsap.to(grid, {
-    height: to,
-    duration: DURATION + STAGGER,
-    ease: 'power3.inOut',
-    onComplete: () => gsap.set(grid, { clearProps: 'height' }),
-  });
-
-  return () => { flip.kill(); height.kill(); gsap.set(grid, { clearProps: 'height' }); };
-}, [active]);
-```
-
-```css
-.grid {
-  position: relative;   /* REQUIRED: failure #2 */
-  display: grid;
-  grid-auto-rows: …;
-}
-.grid > [data-flip] {
-  /* Do NOT transition any property passed to Flip's `props` (failure #4).
-     Opacity is safe here only because Flip never touches it. */
-  transition: opacity 0.6s var(--ease-out);
-}
-```
-
-**Ordering rule:** all measurement happens before any `gsap.set` that mutates
-layout. Never `set(height:'auto')` → measure → tween *after* `Flip.from` has
-captured target geometry; that mutates layout mid-flight and silently corrupts
-the capture.
-
-### 7.3 `scale: true` is a trade, not a default
-
-`scale: true` fakes resizing with `transform: scale`, which is cheaper, but it
-**distorts children**: `object-fit: cover` images stretch, text warps, borders and
-radii scale non-uniformly.
-
-- Items that genuinely change dimensions (bento tile `span 1` → `span 2`, card →
-  modal): **omit `scale`.** Let Flip tween width/height. Correctness beats cheap.
-- Uniform items that only *move* (reordering a same-size grid), or brief/small
-  morphs where distortion is imperceptible: `scale: true` is a fine win.
-
-### 7.4 Verifying Flip
-
-**Typecheck and lint cannot see any of these failures.** A fully broken Flip
-passes `tsc --noEmit` and ESLint clean, which is exactly how a wrong fix survives
-review and reaches the user. Flip is only verified by watching it: click the
-control and confirm (a) nothing below the container moves, (b) no item overlaps
-the next section, (c) the final beat lands without a jump. Check the last one
-specifically; failure #3 hides until the very end.
-
----
-
-## 8. The `ease: "none"` rule
-
-Anything **scrubbed** tracks scroll linearly. Scroll itself is the easing; an ease on top feels broken:
-
-- Scrub-tied values (parallax drift, marquee, the horizontal-scroll track, continuous dial): `ease: "none"`.
-- **Every tween whose trigger uses `containerAnimation`** (triggers inside a moving horizontal track): `ease: "none"` on the track tween, or the trigger math breaks.
-- The exception: *segment* eases (`power2.out`/`power2.in`) **inside** a scrubbed timeline for phase swaps. Each swap keeps shape while the timeline as a whole stays scroll-locked ([pinning-scrub.md](pinning-scrub.md) §1).
-
----
-
-## 9. DrawSVG & MorphSVG (pointer)
-
-Both plugins are free (no token) and register in the `@/lib/gsap` module alongside `Flip` ([setup.md](setup.md) §1). The two one-liners the other files rely on:
-
-```ts
-gsap.from(path, { drawSVG: 0 });             // self-drawing stroke
-gsap.to("#shapeA", { morphSVG: "#shapeB" }); // shape-to-shape morph
-```
-
-Full DrawSVG and MorphSVG recipes live in [svg-motion.md](svg-motion.md).