@nerdev/skillset 0.2.1

package/skills/ui/animaxxing/references/recipes/speak-in.md

@@ -0,0 +1,181 @@
+# Recipe: speak in
+
+Failure contract: apply [effect restoration](../effect-restoration.md) when adapting this module. The framework controller chooses recovery timing; this effect must undo even partial setup.
+
+A paragraph arrives one word at a time at roughly the pace you would say it: short words quickly, long words a beat longer, a full stop earns a pause. Ordinary words each get one of a handful of small entrances; words marked for emphasis are split further into letters and given a bigger one, and may be left with a finish: `broken` (each letter at its own weight and width on the variable axis) or `tilt`.
+
+The framework skill's controller calls `speakIn` during intro at the chosen position in its sequence; this module never decides when. Keep the returned `revert` for as long as the finishes should persist, and call it on outro or unmount. Use for short display copy such as a hero subhead; leave ordinary reading text immediately readable.
+
+Dependencies: `gsap`, `gsap/SplitText`. A variable font supporting the configured weight range for the `broken` finish (400-800 in the example). Adapt that range to the loaded face, or omit `broken` / use `tilt` for a static face; keep its existing font.
+
+Setup: follow [stable typography for character animation](../text-stability.md#stable-typography-for-character-animation) before creating splits; keep that target CSS after revert and under reduced motion. Apply it only to persistent emphasis elements receiving inner character splits, not the entire paragraph. Verify the split-to-unsplit boundary with the [cleanup checks](../verification.md#splittext-cleanup-stability).
+
+```ts
+import gsap from "gsap";
+import { SplitText } from "gsap/SplitText";
+
+gsap.registerPlugin(SplitText);
+
+/* Swap for the project's helper if it has one. */
+function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined") return true;
+  const choice = document.documentElement.dataset.motion;
+  if (choice === "reduced") return true;
+  if (choice === "full") return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/** Seconds a word takes to arrive, before adding time per letter. */
+const WORD_BASE = 0.06;
+/** Extra seconds per letter, so long words take longer to say. */
+const PER_LETTER = 0.008;
+/** Breath after a sentence ends. */
+const SENTENCE_PAUSE = 0.65;
+/** Extra beat around an emphasized word. */
+const EMPHASIS_HOLD = 0.1;
+/** Seconds the settle into a finish takes, after the letters have landed. */
+const FINISH_TIME = 0.22;
+
+const rnd = gsap.utils.random;
+
+type WordIn = (word: HTMLElement) => gsap.core.Tween;
+type LettersIn = (chars: HTMLElement[]) => gsap.core.Tween;
+
+const WORD_INS: WordIn[] = [
+  (w) => gsap.fromTo(w, { y: 16, autoAlpha: 0 }, { y: 0, autoAlpha: 1, duration: 0.4, ease: "power3.out" }),
+  (w) => gsap.fromTo(w, { y: -12, autoAlpha: 0 }, { y: 0, autoAlpha: 1, duration: 0.35, ease: "power2.out" }),
+  (w) => gsap.fromTo(w, { scale: 0.6, autoAlpha: 0, transformOrigin: "50% 100%" }, { scale: 1, autoAlpha: 1, duration: 0.45, ease: "back.out(2)" }),
+  (w) => gsap.fromTo(w, { filter: "blur(8px)", autoAlpha: 0 }, { filter: "blur(0px)", autoAlpha: 1, duration: 0.45, ease: "power2.out" }),
+  (w) => gsap.fromTo(w, { x: -14, autoAlpha: 0 }, { x: 0, autoAlpha: 1, duration: 0.35, ease: "power3.out" }),
+  (w) => gsap.fromTo(w, { rotationX: -80, autoAlpha: 0, transformOrigin: "50% 100%" }, { rotationX: 0, autoAlpha: 1, duration: 0.45, ease: "power3.out" }),
+];
+
+const LETTERS_INS: LettersIn[] = [
+  // Tumble: letters drop from above and bounce into place.
+  (chars) => gsap.fromTo(chars, { y: -40, autoAlpha: 0 }, { y: 0, autoAlpha: 1, duration: 0.6, ease: "bounce.out", stagger: 0.04 }),
+  // Stamp: letters shrink down from oversized.
+  (chars) => gsap.fromTo(chars, { scale: 2.2, autoAlpha: 0 }, { scale: 1, autoAlpha: 1, duration: 0.35, ease: "power4.out", stagger: 0.035 }),
+  // Pop: letters spring in from nothing with a twist.
+  (chars) =>
+    gsap.fromTo(
+      chars,
+      { scale: 0, rotation: () => rnd(-30, 30), autoAlpha: 0 },
+      { scale: 1, rotation: 0, autoAlpha: 1, duration: 0.7, ease: "elastic.out(1, 0.45)", stagger: 0.05 },
+    ),
+  // Cascade: letters rise and straighten one after another.
+  (chars) => gsap.fromTo(chars, { y: 24, rotation: -12, autoAlpha: 0 }, { y: 0, rotation: 0, autoAlpha: 1, duration: 0.5, ease: "back.out(1.7)", stagger: 0.035 }),
+];
+
+const normalize = (text: string) => text.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+
+export type Finish = "broken" | "tilt";
+export type Emphasis = string | { word: string; finish?: Finish; /** Degrees for `tilt`, clockwise positive. Random when omitted. */ angle?: number };
+export type SpeakOptions = {
+  /** Words that get the letter-level entrance, matched ignoring case and punctuation. */
+  emphasis?: Emphasis[];
+  /** Seconds of silence before the first word. */
+  delay?: number;
+};
+
+function settle(timeline: gsap.core.Timeline, word: HTMLElement, chars: HTMLElement[], finish: Finish, angle?: number) {
+  if (finish === "broken") {
+    // Each letter lands somewhere on the 400 to 800 axis and stretches or narrows a little to match.
+    timeline.to(
+      chars,
+      { fontWeight: () => rnd(400, 800, 10), scaleX: () => rnd(0.85, 1.2), transformOrigin: "50% 100%", duration: FINISH_TIME, ease: "power2.out", stagger: 0.015 },
+      ">",
+    );
+  } else {
+    timeline.to(
+      word,
+      { rotation: angle ?? rnd(2.5, 5) * (Math.random() < 0.5 ? -1 : 1), transformOrigin: "50% 100%", duration: FINISH_TIME, ease: "power2.out" },
+      ">",
+    );
+  }
+}
+
+/**
+ * Builds the entrance and returns it with a revert that puts the paragraph's
+ * markup back. The element should start hidden; the timeline reveals it as
+ * the first word lands. `words` are the split words, for the outro to throw.
+ */
+export function speakIn(
+  el: HTMLElement,
+  { emphasis = [], delay = 0 }: SpeakOptions = {},
+): { timeline: gsap.core.Timeline; words: HTMLElement[]; revert: () => void } {
+  const timeline = gsap.timeline();
+  if (prefersReducedMotion()) {
+    timeline.set(el, { autoAlpha: 1 });
+    return { timeline, words: [], revert: () => {} };
+  }
+
+  const wanted = new Map<string, { finish?: Finish; angle?: number }>(
+    emphasis.map((e) =>
+      typeof e === "string"
+        ? [normalize(e), {}]
+        : [normalize(e.word), { ...(e.finish && { finish: e.finish }), ...(e.angle !== undefined && { angle: e.angle }) }],
+    ),
+  );
+  const split = SplitText.create(el, { type: "words" });
+  const words = split.words as HTMLElement[];
+  const letterSplits: SplitText[] = [];
+
+  gsap.set(words, { autoAlpha: 0 });
+  timeline.set(el, { autoAlpha: 1 }, 0);
+
+  let t = delay;
+  let wordIndex = 0;
+  let lettersIndex = Math.floor(Math.random() * LETTERS_INS.length);
+  let lastWordIn = -1;
+  for (const word of words) {
+    const text = word.textContent ?? "";
+    const letters = normalize(text).length;
+
+    if (wanted.has(normalize(text))) {
+      const inner = SplitText.create(word, { type: "chars" });
+      letterSplits.push(inner);
+      const chars = inner.chars as HTMLElement[];
+      gsap.set(chars, { autoAlpha: 0 });
+      const enter = LETTERS_INS[lettersIndex % LETTERS_INS.length];
+      lettersIndex++;
+      timeline.set(word, { autoAlpha: 1 }, t);
+      if (enter) timeline.add(enter(chars), t);
+      const spec = wanted.get(normalize(text));
+      if (spec?.finish) settle(timeline, word, chars, spec.finish, spec.angle);
+      t += WORD_BASE + PER_LETTER * letters + EMPHASIS_HOLD;
+    } else {
+      // Never the same entrance twice in a row.
+      let pick = Math.floor(Math.random() * WORD_INS.length);
+      if (pick === lastWordIn) pick = (pick + 1) % WORD_INS.length;
+      lastWordIn = pick;
+      const enter = WORD_INS[pick];
+      if (enter) timeline.add(enter(word), t);
+      t += WORD_BASE + PER_LETTER * letters;
+    }
+    wordIndex++;
+    if (/[.!?]$/.test(text.trim()) && wordIndex < words.length) t += SENTENCE_PAUSE;
+  }
+
+  return {
+    timeline,
+    words,
+    revert: () => {
+      for (const inner of letterSplits) inner.revert();
+      split.revert();
+    },
+  };
+}
+```
+
+## Wiring
+
+```ts
+// Hero subhead, marked data-speak-intro and hidden by the pre-paint rule:
+const EMPHASIS = ["low", "rizz", { word: "cooked", finish: "broken" }, "negative", "aura", "agents", "animate"];
+const spoken = speakIn(subhead, { emphasis: EMPHASIS, delay: 0.3 }); // starts after the letters land
+// Keep `spoken` alive while the page idles so the finishes persist.
+// On outro: blastOff({ ..., words: spoken.words, ... }) then spoken.revert() once the outro is done with.
+// On unmount: spoken.timeline.kill(); spoken.revert();
+```
+
+A `set(el, { autoAlpha: 0 })` before calling `speakIn` is the initial state when the pre-paint CSS rule is not in use.

package/skills/ui/animaxxing/references/recipes/split-entrances.md

@@ -0,0 +1,345 @@
+# Recipe: split entrances
+
+Failure contract: apply [effect restoration](../effect-restoration.md) when adapting this module. The framework controller chooses recovery timing. this effect must undo even partial setup.
+
+The framework skill's controller calls these during intro and outro. this module never decides when. Each builder returns a timeline the controller can compose, kill, or await. Display type only.
+
+Dependencies: `gsap`, `gsap/SplitText` (free because 3.13). `scrambleIn`/`Out` also need `gsap/ScrambleTextPlugin`. `charsWeightWave` needs a variable face covering its configured `WEIGHT` endpoints (400-800 in the example). adjust those and the midpoint choice to the loaded axis, or select a transform-only recipe. No font family is prescribed.
+
+Setup: use [stable typography for character animation](../text-stability.md#stable-typography-for-character-animation) before creating splits. keep that target CSS after revert and under reduced motion. For confirmed clipped ink, use the optional `charMaskClass` with the [targeted mask CSS](../text-stability.md#apparent-weight-change-from-clipped-glyph-ink). verify both hidden endpoints after expanding masks. Verify the split-to-unsplit boundary with the [cleanup checks](../verification.md#splittext-cleanup-stability).
+
+```ts
+import gsap from "gsap";
+import { SplitText } from "gsap/SplitText";
+
+gsap.registerPlugin(SplitText);
+
+/* Swap for the project's helper if it has one. */
+function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined") return true;
+  const choice = document.documentElement.dataset.motion;
+  if (choice === "reduced") return true;
+  if (choice === "full") return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+const DURATION = { micro: 0.14, component: 0.2, page: 0.28 } as const;
+const EASE = { entrance: "power2.out", exit: "power2.in", shift: "power2.inOut" } as const;
+const STAGGER = { tight: 0.03, loose: 0.05 } as const;
+const WEIGHT = { rest: 400, display: 800 } as const;
+
+export type MotionOptions = {
+  delay?: number;
+  onComplete?: () => void;
+  /** One CSS class token for confirmed character-mask clipping; no default padding. */
+  charMaskClass?: string;
+};
+export type SplitRunner = (target: HTMLElement | null, options?: MotionOptions) => gsap.core.Timeline;
+
+function build(options: MotionOptions): gsap.core.Timeline {
+  const timeline = gsap.timeline({ delay: options.delay ?? 0, defaults: { overwrite: "auto" } });
+  if (options.onComplete) timeline.eventCallback("onComplete", options.onComplete);
+  return timeline;
+}
+
+/**
+ * Splits, runs `choreograph`, and puts the element back together afterwards.
+ * The settled state is applied first so an interrupted run cannot leave text
+ * stranded mid-flight. `aria: "auto"` labels the element with the original
+ * string and hides the pieces, so a screen reader hears the sentence.
+ */
+function withSplit(
+  element: HTMLElement | null,
+  options: MotionOptions,
+  config: SplitText.Vars,
+  choreograph: (split: SplitText, tl: gsap.core.Timeline) => void,
+  settled: gsap.TweenVars = { autoAlpha: 1 },
+): gsap.core.Timeline {
+  const tl = build(options);
+  if (!element) return tl;
+  if (prefersReducedMotion()) return tl.set(element, settled);
+
+  const split = SplitText.create(element, { aria: "auto", ...config });
+  if (config.mask === "chars" && options.charMaskClass) {
+    for (const mask of split.masks) mask.classList.add(options.charMaskClass);
+  }
+  tl.set(element, { autoAlpha: 1 });
+  choreograph(split, tl);
+  tl.eventCallback("onComplete", () => {
+    const previous = options.onComplete;
+    split.revert();
+    previous?.();
+  });
+  return tl;
+}
+
+/** Pins each character to the width it needs at its heaviest, so the weight axis can move without reflow. */
+function pinWidths(chars: Element[], atWeight: number): void {
+  for (const char of chars) {
+    const element = char as HTMLElement;
+    const previous = element.style.fontWeight;
+    element.style.fontWeight = String(atWeight);
+    const { width } = element.getBoundingClientRect();
+    element.style.fontWeight = previous;
+    element.style.display = "inline-block";
+    element.style.width = `${width}px`;
+    element.style.textAlign = "center";
+  }
+}
+
+/** Characters rise behind masks. Requires persistent target CSS from the stable typography reference. */
+export const charsRiseIn: SplitRunner = (element, options = {}) =>
+  withSplit(element, options, { type: "chars", mask: "chars", smartWrap: true }, (split, tl) => {
+    tl.from(split.chars, { yPercent: 115, duration: 0.5, ease: "power3.out", stagger: STAGGER.tight });
+  });
+
+/** Characters spring up with an elastic settle. Unmasked: the overshoot would clip. */
+export const charsSpringIn: SplitRunner = (element, options = {}) =>
+  withSplit(element, options, { type: "chars", smartWrap: true }, (split, tl) => {
+    tl.from(split.chars, {
+      yPercent: 115,
+      autoAlpha: 0,
+      duration: 1.1,
+      ease: "elastic.out(1, 0.5)",
+      stagger: STAGGER.tight,
+    });
+  });
+
+/** And back down, in the same order. */
+export const charsFallOut: SplitRunner = (element, options = {}) =>
+  withSplit(
+    element,
+    options,
+    { type: "chars", mask: "chars", smartWrap: true },
+    (split, tl) => {
+      tl.to(split.chars, { yPercent: -115, duration: DURATION.component, ease: "power2.in", stagger: STAGGER.tight }).set(
+        element,
+        { autoAlpha: 0 },
+      );
+    },
+    { autoAlpha: 0 },
+  );
+
+/** Characters arrive out of order, like a dealer flicking cards. */
+export const charsCascadeIn: SplitRunner = (element, options = {}) =>
+  withSplit(element, options, { type: "chars", smartWrap: true }, (split, tl) => {
+    tl.from(split.chars, {
+      autoAlpha: 0,
+      y: -18,
+      rotation: () => gsap.utils.random(-14, 14),
+      duration: 0.45,
+      ease: "back.out(1.8)",
+      stagger: { each: 0.02, from: "random" },
+    });
+  });
+
+export const charsCascadeOut: SplitRunner = (element, options = {}) =>
+  withSplit(
+    element,
+    options,
+    { type: "chars", smartWrap: true },
+    (split, tl) => {
+      tl.to(split.chars, {
+        autoAlpha: 0,
+        y: 18,
+        rotation: () => gsap.utils.random(-14, 14),
+        duration: DURATION.component,
+        ease: "power2.in",
+        stagger: { each: 0.015, from: "random" },
+      }).set(element, { autoAlpha: 0 });
+    },
+    { autoAlpha: 0 },
+  );
+
+/** Each character tips over its own top edge. */
+export const charsFlipIn: SplitRunner = (element, options = {}) =>
+  withSplit(element, options, { type: "chars", smartWrap: true }, (split, tl) => {
+    tl.from(split.chars, {
+      autoAlpha: 0,
+      rotationX: -90,
+      transformOrigin: "50% 0%",
+      transformPerspective: 600,
+      duration: 0.5,
+      ease: "back.out(1.4)",
+      stagger: STAGGER.tight,
+    });
+  });
+
+export const charsFlipOut: SplitRunner = (element, options = {}) =>
+  withSplit(
+    element,
+    options,
+    { type: "chars", smartWrap: true },
+    (split, tl) => {
+      tl.to(split.chars, {
+        autoAlpha: 0,
+        rotationX: 90,
+        transformOrigin: "50% 100%",
+        transformPerspective: 600,
+        duration: DURATION.component,
+        ease: "power2.in",
+        stagger: STAGGER.tight,
+      }).set(element, { autoAlpha: 0 });
+    },
+    { autoAlpha: 0 },
+  );
+
+/** Characters converge from wherever they were thrown. */
+export const charsScatterIn: SplitRunner = (element, options = {}) =>
+  withSplit(element, options, { type: "chars", smartWrap: true }, (split, tl) => {
+    tl.from(split.chars, {
+      autoAlpha: 0,
+      x: () => gsap.utils.random(-120, 120),
+      y: () => gsap.utils.random(-60, 60),
+      rotation: () => gsap.utils.random(-45, 45),
+      scale: 0.6,
+      duration: 0.6,
+      ease: "power3.out",
+      stagger: { each: 0.012, from: "center" },
+    });
+  });
+
+export const charsScatterOut: SplitRunner = (element, options = {}) =>
+  withSplit(
+    element,
+    options,
+    { type: "chars", smartWrap: true },
+    (split, tl) => {
+      tl.to(split.chars, {
+        autoAlpha: 0,
+        x: () => gsap.utils.random(-120, 120),
+        y: () => gsap.utils.random(-60, 60),
+        rotation: () => gsap.utils.random(-45, 45),
+        scale: 0.6,
+        duration: DURATION.page,
+        ease: "power2.in",
+        stagger: { each: 0.012, from: "edges" },
+      }).set(element, { autoAlpha: 0 });
+    },
+    { autoAlpha: 0 },
+  );
+
+/**
+ * A weight wave through the line: each character dips to the far end of the
+ * axis and comes back. Widths are pinned first so letters breathe in place.
+ */
+export const charsWeightWave: SplitRunner = (element, options = {}) => {
+  const settledWeight = element ? Number(getComputedStyle(element).fontWeight) || WEIGHT.rest : WEIGHT.rest;
+  const farWeight = settledWeight >= 600 ? WEIGHT.rest : WEIGHT.display;
+  return withSplit(
+    element,
+    options,
+    { type: "chars", smartWrap: true },
+    (split, tl) => {
+      pinWidths(split.chars, Math.max(settledWeight, farWeight));
+      tl.fromTo(
+        split.chars,
+        { fontWeight: settledWeight },
+        { fontWeight: farWeight, duration: 0.3, ease: EASE.shift, stagger: { each: 0.03, from: "start" } },
+      ).to(
+        split.chars,
+        { fontWeight: settledWeight, duration: 0.4, ease: EASE.shift, stagger: { each: 0.03, from: "start" } },
+        0.18,
+      );
+    },
+    { autoAlpha: 1 },
+  );
+};
+
+/** Words swing in from alternating sides. */
+export const wordsSlideIn: SplitRunner = (element, options = {}) =>
+  withSplit(element, options, { type: "words" }, (split, tl) => {
+    tl.from(split.words, {
+      autoAlpha: 0,
+      x: (index: number) => (index % 2 === 0 ? -40 : 40),
+      duration: DURATION.page,
+      ease: EASE.entrance,
+      stagger: STAGGER.loose,
+    });
+  });
+
+export const wordsSlideOut: SplitRunner = (element, options = {}) =>
+  withSplit(
+    element,
+    options,
+    { type: "words" },
+    (split, tl) => {
+      tl.to(split.words, {
+        autoAlpha: 0,
+        x: (index: number) => (index % 2 === 0 ? 40 : -40),
+        duration: DURATION.component,
+        ease: EASE.exit,
+        stagger: STAGGER.tight,
+      }).set(element, { autoAlpha: 0 });
+    },
+    { autoAlpha: 0 },
+  );
+
+/** Whole lines wiped up behind masks. The most editorial of the family. */
+export const linesMaskIn: SplitRunner = (element, options = {}) =>
+  withSplit(element, options, { type: "lines", mask: "lines" }, (split, tl) => {
+    tl.from(split.lines, { yPercent: 110, duration: DURATION.page, ease: "power3.out", stagger: STAGGER.loose });
+  });
+
+export const linesMaskOut: SplitRunner = (element, options = {}) =>
+  withSplit(
+    element,
+    options,
+    { type: "lines", mask: "lines" },
+    (split, tl) => {
+      tl.to(split.lines, { yPercent: -110, duration: DURATION.component, ease: "power2.in", stagger: STAGGER.tight }).set(
+        element,
+        { autoAlpha: 0 },
+      );
+    },
+    { autoAlpha: 0 },
+  );
+```
+
+## Scramble
+
+Needs `ScrambleTextPlugin` registered. Display only: reading text must never look like it types.
+
+```ts
+export const scrambleIn: SplitRunner = (element, options = {}) => {
+  const tl = build(options);
+  if (!element) return tl;
+  const text = element.textContent ?? "";
+  if (prefersReducedMotion()) return tl.set(element, { autoAlpha: 1 });
+  return tl.set(element, { autoAlpha: 1 }).to(element, {
+    duration: 0.9,
+    ease: "none",
+    scrambleText: { text, chars: "01{}/<>()=;", speed: 0.6, revealDelay: 0.15 },
+  });
+};
+
+export const scrambleOut: SplitRunner = (element, options = {}) => {
+  const tl = build(options);
+  if (!element) return tl;
+  if (prefersReducedMotion()) return tl.set(element, { autoAlpha: 0 });
+  const text = element.textContent ?? "";
+  return tl
+    .to(element, { duration: 0.5, ease: "none", scrambleText: { text: text.replace(/\S/g, "0"), chars: "01{}/<>()=;", speed: 0.8 } })
+    .to(element, { autoAlpha: 0, duration: DURATION.micro, ease: EASE.exit })
+    .call(() => { element.textContent = text; });
+};
+```
+
+## Wiring
+
+```ts
+// In the framework skill's page controller, after required fonts are ready:
+// heading has the persistent character-headline class from the typography reference.
+// Keep that CSS when withSplit calls split.revert(); smartWrap/mask do not fix kerning.
+const intro = gsap.timeline();
+// Omit charMaskClass unless clipping is confirmed; CSS lives in the typography reference.
+// A CSS Modules caller can pass styles.titleCharMask as the class token.
+const headlineOptions = { charMaskClass: "title-char-mask" };
+intro.add(charsRiseIn(heading, headlineOptions), 0);
+intro.add(linesMaskIn(lede), 0.2);
+// The outro is the paired exit, in reverse order:
+const outro = gsap.timeline();
+outro.add(linesMaskOut(lede), 0).add(charsFallOut(heading, headlineOptions), 0.05);
+```
+
+Give a split heading its own pre-paint hiding rule rather than marking it as a page item too, or the page's stagger and the split is rise will fight over one element.

package/skills/ui/animaxxing/references/recipes/wave.md

@@ -0,0 +1,144 @@
+# Recipe: the wave
+
+Failure contract: apply [effect restoration](../effect-restoration.md) when adapting this module. The framework controller chooses recovery timing; this effect must undo even partial setup.
+
+Splits a heading into letters and, every few seconds, ripples a small move across them left to right, one letter at a time, the way a crowd does the wave. Each pass uses a different move, and every letter ends exactly where it started, so the text never drifts. An optional ambient effect for display text.
+
+The framework skill's controller calls `startWave` at settled (on `idle`) and the returned stop function on outro and unmount; this module never decides when.
+
+Dependencies: `gsap`, `gsap/SplitText`. A variable font supporting the configured weight range for weight moves; no particular font family is required. The example rests at 800 and dips through 400-500. Adapt those weights to the target's actual resting weight and axis, or omit the three weight moves for a static face; keep its existing font.
+
+Setup: follow [stable typography for character animation](../text-stability.md#stable-typography-for-character-animation) before creating splits; keep that target CSS after revert and under reduced motion. Verify the split-to-unsplit boundary with the [cleanup checks](../verification.md#splittext-cleanup-stability).
+
+```ts
+import gsap from "gsap";
+import { SplitText } from "gsap/SplitText";
+
+gsap.registerPlugin(SplitText);
+
+/* Swap for the project's helper if it has one. */
+function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined") return true;
+  const choice = document.documentElement.dataset.motion;
+  if (choice === "reduced") return true;
+  if (choice === "full") return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/** Delay between neighbouring letters starting their move. */
+const RIPPLE = 0.03;
+/** Each letter is back at rest this many seconds after it starts. */
+const LETTER_TIME = 0.25;
+
+const rnd = gsap.utils.random;
+type Move = (chars: HTMLElement[]) => gsap.core.Timeline;
+
+/**
+ * One out-and-back tween per letter, staggered along the line. The repeat
+ * and yoyo live inside the stagger so each letter turns around on its own
+ * schedule; at the top level they would send the wave back in reverse.
+ */
+function ripple(chars: HTMLElement[], vars: gsap.TweenVars, ease = "sine.inOut") {
+  return gsap
+    .timeline()
+    .to(chars, { ...vars, duration: LETTER_TIME / 2, ease, stagger: { each: RIPPLE, yoyo: true, repeat: 1 } })
+    .set(chars, { clearProps: "transform,opacity,fontWeight" });
+}
+
+/** A one-way tween per letter for moves that end where they began anyway. */
+function sweep(chars: HTMLElement[], vars: gsap.TweenVars, ease = "power2.inOut") {
+  return gsap
+    .timeline()
+    .to(chars, { ...vars, duration: LETTER_TIME, ease, stagger: RIPPLE })
+    .set(chars, { clearProps: "transform,opacity,fontWeight" });
+}
+
+/** The heading sits at 800, so every weight move is a dip away from bold and back. */
+const MOVES: Move[] = [
+  // Hop: each letter lifts and lands.
+  (chars) => ripple(chars, { y: -14 }, "power2.out"),
+  // Breathe: a swell from the baseline.
+  (chars) => ripple(chars, { scale: 1.07, transformOrigin: "50% 100%" }),
+  // Lean: a nod to the right and back.
+  (chars) => ripple(chars, { rotation: 7, transformOrigin: "50% 100%" }),
+  // Flip: a full turn about the vertical axis, no perspective, so the letter folds to a line and back.
+  (chars) => sweep(chars, { rotationY: 360, transformOrigin: "50% 50%" }),
+  // Lighten: the weight axis eases down to medium and back.
+  (chars) => ripple(chars, { fontWeight: 500 }),
+  // Hairline: weight drops to the floor while the letter stretches to keep its footprint.
+  (chars) => ripple(chars, { fontWeight: 400, scaleX: 1.14, transformOrigin: "50% 100%" }, "power2.inOut"),
+  // Ink: weight snaps to thin, then fills back in to bold.
+  (chars) =>
+    gsap
+      .timeline()
+      .fromTo(chars, { fontWeight: 400 }, { fontWeight: 800, duration: LETTER_TIME, ease: "power2.out", stagger: RIPPLE, immediateRender: false })
+      .set(chars, { clearProps: "fontWeight" }),
+  // Shear: a quick italic slant.
+  (chars) => ripple(chars, { skewX: 12 }, "power2.inOut"),
+  // Squash: pressed flat and released.
+  (chars) => ripple(chars, { scaleY: 0.82, transformOrigin: "50% 100%" }, "power2.inOut"),
+  // Twist: each letter swells with its own small twist, then back.
+  (chars) => ripple(chars, { scale: 1.1, rotation: () => rnd(-12, 12), transformOrigin: "50% 50%" }, "power2.inOut"),
+];
+
+/** Pins each letter to its resting width so weight changes cannot reflow the line. */
+function pinWidths(chars: HTMLElement[]): void {
+  const widths = chars.map((char) => char.getBoundingClientRect().width);
+  chars.forEach((char, i) => {
+    char.style.display = "inline-block";
+    char.style.width = `${widths[i] ?? 0}px`;
+    char.style.textAlign = "center";
+  });
+}
+
+export type WaveOptions = {
+  /** Seconds from the start of one wave to the start of the next. */
+  period?: number;
+};
+
+/**
+ * Starts waving the heading's letters. Returns a stop function; pass
+ * `keepSplit` when another animation is about to split the same element
+ * and needs the current markup left in place.
+ */
+export function startWave(heading: HTMLElement, { period = 4 }: WaveOptions = {}): (keepSplit?: boolean) => void {
+  if (prefersReducedMotion()) return () => {};
+  const split = SplitText.create(heading, { type: "chars,words" });
+  const chars = split.chars as HTMLElement[];
+  chars.sort((a, b) => a.getBoundingClientRect().left - b.getBoundingClientRect().left);
+  pinWidths(chars);
+  gsap.set(chars, { willChange: "transform, opacity" });
+
+  // Shuffle so each cycle plays in a fresh order, never repeating one across the seam.
+  let deck = gsap.utils.shuffle([...MOVES]);
+  let index = 0;
+  let current: gsap.core.Timeline | undefined;
+
+  const wave = () => {
+    const move = deck[index];
+    index++;
+    if (index >= deck.length) {
+      deck = gsap.utils.shuffle([...MOVES]);
+      if (deck[0] === move && deck.length > 1) deck.push(deck.shift() as Move);
+      index = 0;
+    }
+    current?.kill();
+    current = move ? move(chars) : undefined;
+  };
+
+  const clock = gsap.delayedCall(period, () => {
+    wave();
+    clock.restart(true);
+  });
+
+  return (keepSplit = false) => {
+    clock.kill();
+    current?.kill();
+    if (!keepSplit) split.revert();
+  };
+}
+```
+
+## Controller contract
+
+`startWave(heading, { period: 1.5 })` returns a stop function. The owner invokes it only after other heading splits are released, and stops it before another effect takes the heading. Use the normal stop path to revert the split; `keepSplit` requires an explicit owner for the retained markup. The controller supplies visibility and resize signals.