@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/recipes/fit-text/create-fit-text.ts

@@ -0,0 +1,55 @@
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/* Size a one-line element so it spans its parent's content box (giant "Portfolio" / footer words). */
+
+export interface FitTextOptions {
+  /** Fraction of the available width to use; leaves room for side bearings. */
+  safety?: number;
+}
+
+export interface FitTextInstance extends Instance {
+  refit(): void;
+}
+
+export function createFitText(el: HTMLElement | null, options: FitTextOptions = {}): FitTextInstance {
+  const parent = el?.parentElement;
+  if (!el || !parent) {
+    warnOnce('fit-text: element needs a parent');
+    return inert({ refit() {} });
+  }
+  const safety = Math.min(1, Math.max(0.5, options.safety ?? 0.995));
+  const scope = createScope();
+  const previousSize = el.style.fontSize;
+
+  const refit = () => {
+    const style = getComputedStyle(parent);
+    const available = parent.clientWidth - parseFloat(style.paddingLeft || '0') - parseFloat(style.paddingRight || '0');
+    el.style.fontSize = '100px';
+    const width = el.getBoundingClientRect().width;
+    if (width > 0 && available > 0) el.style.fontSize = `${(100 * available * safety) / width}px`;
+    else el.style.fontSize = previousSize;
+  };
+
+  // Refit on width changes only; the height change caused by fitting must not loop.
+  let lastWidth = -1;
+  scope
+    .observe(
+      new ResizeObserver(([entry]) => {
+        const width = entry?.contentRect.width ?? 0;
+        if (width === lastWidth) return;
+        lastWidth = width;
+        refit();
+      }),
+    )
+    .observe(parent);
+  refit();
+  el.dataset.mkReady = '';
+  scope.add(() => {
+    el.style.fontSize = previousSize;
+    if (!el.getAttribute('style')) el.removeAttribute('style');
+    delete el.dataset.mkReady;
+  });
+
+  return { refit, destroy: () => scope.dispose() };
+}

package/src/recipes/fit-text/fit-text.css

@@ -0,0 +1,6 @@
+/* fit-text — one line, measured as an inline box */
+[data-mk~="fit-text"],
+.mk-fit {
+  display: inline-block;
+  white-space: nowrap;
+}

package/src/recipes/flow/README.md

@@ -0,0 +1,46 @@
+# flow
+
+Los hijos del contenedor caen desde 20 px arriba, desenfocados 16 px, en 0.5 s y con 50 ms entre ellos.
+
+Origen: Stepbro — flowIn (apps Tasks y Money).
+
+## Vanilla / Astro
+
+```html
+<div data-mk="flow">
+  <p>Primer párrafo</p>
+  <p>Segundo párrafo</p>
+</div>
+```
+
+Con `autoInit()` (de `@yewdiel21/motion-kit/auto`) las opciones van como `data-mk-<opción>` en kebab-case. Sin `autoInit`: `createFlow(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+useFlow(ref);
+// o, sin contenedor: flowIn(elements, { stagger: .04 })
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `y` | `20` | px de caída |
+| `blur` | `16` | px de desenfoque inicial |
+| `duration` | `.5` | Segundos |
+| `stagger` | `.05` | Segundos entre hijos |
+| `delay` | `0` | Segundos |
+| `trigger` | `'scroll'` | 'scroll', 'load' o 'manual' |
+| `start` | `'top 88%'` | Inicio del ScrollTrigger |
+
+## Controles
+
+`play()`, `destroy()`; utilidad `flowIn(targets, options)`
+
+## CSS
+
+Curva `mk-flow` (`M0,0 C0.25,0.1 0.25,1 1,1`).
+
+Con `prefers-reduced-motion: reduce` la receta deja el contenido en su estado final, sin animar.

package/src/recipes/flow/create-flow.ts

@@ -0,0 +1,55 @@
+import { gsap, ScrollTrigger, registerMotion } from '../../core/gsap';
+import { flowIn, type FlowInOptions } from '../../motion/flow';
+import { entrances } from '../../core/reduced';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/* Stepbro flowIn on a container: its children drop in from 20 px above, blurred 16 px, 0.5 s, 50 ms apart. */
+
+export interface FlowOptions extends FlowInOptions {
+  trigger?: 'scroll' | 'load' | 'manual';
+  start?: string;
+}
+
+export interface FlowInstance extends Instance {
+  play(): void;
+}
+
+export { flowIn };
+
+/** Flow the container's children in, on scroll by default. */
+export function createFlow(container: HTMLElement | null, options: FlowOptions = {}): FlowInstance {
+  if (!container) {
+    warnOnce('flow: missing container');
+    return inert({ play() {} });
+  }
+  registerMotion();
+  const children = [...container.children] as HTMLElement[];
+  const animate = entrances() && children.length > 0;
+  const ctx = gsap.context(() => {});
+  let played = !animate;
+
+  const play = () => {
+    if (played) return;
+    played = true;
+    ctx.add(() => flowIn(children, options));
+  };
+
+  if (animate) {
+    ctx.add(() => {
+      gsap.set(children, { autoAlpha: 0 });
+      if (options.trigger === 'load') play();
+      else if (options.trigger !== 'manual') {
+        ScrollTrigger.create({ trigger: container, start: options.start ?? 'top 88%', end: 'max', once: true, onEnter: play });
+      }
+    });
+  }
+  container.dataset.mkReady = '';
+
+  return {
+    play,
+    destroy() {
+      ctx.revert();
+      delete container.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/frame-zoom/README.md

@@ -0,0 +1,29 @@
+# frame-zoom
+
+Un marco que se cierra como una ventana mientras cruza la pantalla: entra completo por abajo, a media pantalla va al 90 % y al irse por arriba llega al 80 %, con la imagen de dentro creciendo al revés (110 % → 130 %; en el móvil 95–100 % y 105–110 %). Sigue al scroll de la página sin retraso. `open(true)` lo devuelve completo (1 s `expo.out`), como el vídeo de Siena al abrirse.
+
+Origen: Siena Film Foundation, máscara del vídeo de película (marco `e·20 + 80 %`, imagen `130 − e·20 %`, `e = 1 − progreso` del rastreador de Siena, que va de `top bottom` a `bottom top`).
+
+## HTML / Astro
+
+```html
+<div data-mk="frame-zoom" class="frame" style="border-radius: 24px">
+  <video src="trailer.mp4" muted autoplay loop playsinline></video>
+</div>
+```
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const zoom = useFrameZoom(ref);
+<button onClick={() => zoom.current?.open(true)}>Ver</button>
+```
+
+## API
+
+`createFrameZoom(root, { start, end, lerp, scroll })` → `{ seek(p), open(on), state, destroy }`.
+
+## Accesibilidad
+
+Con movimiento reducido el marco queda completo y quieto. No es una entrada (no esconde nada), así que la red de seguridad de `MK_HEAD_SCRIPT` no lo apaga.

package/src/recipes/frame-zoom/create-frame-zoom.ts

@@ -0,0 +1,91 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { trackScroll, type ScrollTrack } from '../../core/scroll-track';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * Siena's video mask: the frame and the picture inside scale in opposite
+ * directions. With e = (1 − progress)·(1 − open) + open, the frame is
+ * (80 + 20e) % and the picture (130 − 20e) % (phones: 95 + 5e and 105 − 5e):
+ * full as it enters at the bottom, it closes like a window while it crosses the
+ * screen (Siena's tracker: top bottom → bottom top). open(true) brings it back
+ * to full (1 s expo.out).
+ */
+
+export interface FrameZoomOptions {
+  start?: string;
+  end?: string;
+  lerp?: number;
+  scroll?: boolean;
+}
+
+export interface FrameZoomInstance extends Instance {
+  seek(progress: number): void;
+  /** Full frame (true) or back to the scroll (false). */
+  open(on: boolean): void;
+  readonly state: { progress: number; open: number };
+}
+
+export function createFrameZoom(root: HTMLElement | null, options: FrameZoomOptions = {}): FrameZoomInstance {
+  const inner = (root?.firstElementChild as HTMLElement | null) ?? null;
+  if (!root || !inner) {
+    warnOnce('frame-zoom: needs a frame with a picture inside');
+    return inert({ seek() {}, open() {}, state: { progress: 0, open: 0 } });
+  }
+  const t = TIMING.frameZoom;
+  const { start = 'top bottom', end = 'bottom top', lerp = t.lerp, scroll = true } = options;
+  registerMotion();
+  const phone = typeof matchMedia === 'function' && matchMedia('(max-width: 767px)').matches;
+  const [outerBase, outerRange] = phone ? t.phoneOuter : t.outer;
+  const [innerBase, innerRange] = phone ? t.phoneInner : t.inner;
+  // Not an entrance: it hides nothing, so only reduced motion stills it.
+  const moving = !reduced();
+  const state = { progress: 0, open: 0 };
+  const originals = [root.style.transform, inner.style.transform, root.style.overflow];
+  root.style.overflow = 'clip';
+
+  const render = () => {
+    const e = moving ? (1 - state.progress) * (1 - state.open) + state.open : 1;
+    root.style.transform = `scale(${Number(((outerBase + outerRange * e) / 100).toFixed(4))})`;
+    inner.style.transform = `scale(${Number(((innerBase - innerRange * e) / 100).toFixed(4))})`;
+  };
+  let track: ScrollTrack | null = null;
+  if (moving && scroll)
+    track = trackScroll(root, {
+      start,
+      end,
+      lerp,
+      onUpdate: (value) => {
+        state.progress = value;
+        render();
+      },
+    });
+  else render();
+  root.dataset.mkReady = '';
+
+  return {
+    state,
+    seek(progress: number) {
+      if (track) track.set(progress);
+      else {
+        state.progress = Math.min(1, Math.max(0, progress));
+        render();
+      }
+    },
+    open(on: boolean) {
+      gsap.killTweensOf(state);
+      if (!moving) return;
+      gsap.to(state, { open: on ? 1 : 0, duration: t.open, ease: 'expo.out', onUpdate: render });
+    },
+    destroy() {
+      track?.destroy();
+      gsap.killTweensOf(state);
+      root.style.transform = originals[0]!;
+      inner.style.transform = originals[1]!;
+      root.style.overflow = originals[2]!;
+      for (const el of [root, inner]) if (el.getAttribute('style') === '') el.removeAttribute('style');
+      delete root.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/infinite-reel/README.md

@@ -0,0 +1,23 @@
+# infinite-reel
+
+Reel infinito horizontal o vertical con rueda, arrastre e inercia (Siena).
+
+```html
+<div class="mk-infinite-reel" data-mk="infinite-reel" aria-label="Películas">
+  <div data-mk-reel-track><article>Uno</article><article>Dos</article></div>
+</div>
+```
+
+```ts
+import { createInfiniteReel } from '@yewdiel21/motion-kit';
+import { useInfiniteReel } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const instance = createInfiniteReel(root);
+instance.destroy();
+```
+
+Opciones: `axis: 'x' | 'y'` (x), `speed` px/frame (0), `friction` (.95). `moveBy(px)`, `pause()`, `resume()`, `position`. Rueda, arrastre, flechas y Espacio cuando tiene foco. Copias con aria-hidden/inert y sin IDs. Movimiento reducido: scroll nativo sin copias, ticker ni inercia. Origen: Siena `siena.reel.horizontal/vertical`; adaptación DOM sin snap ni shaders del reel original.
+
+Vanilla declarativo: `autoInit(root)`. React: `useInfiniteReel(ref, options, deps)` devuelve una ref a la instancia; se destruye al desmontar. Con movimiento reducido no se ejecuta movimiento decorativo. `destroy()` restaura atributos y estilos y quita listeners, observers y nodos generados.
+
+Desde 0.8.0. Parámetros investigados en `REA - Dousan OFFFICE Siena/`; implementación propia, sin código ni assets de esos sitios.

package/src/recipes/infinite-reel/create-infinite-reel.ts

@@ -0,0 +1,140 @@
+import { whileVisible } from '../../core/loop';
+import { wrap } from '../../core/math';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, type Instance } from '../../core/types';
+
+export interface InfiniteReelOptions { speed?: number; friction?: number; axis?: 'x' | 'y'; }
+export interface InfiniteReelInstance extends Instance {
+  moveBy(pixels: number): void;
+  pause(): void;
+  resume(): void;
+  readonly position: number;
+}
+
+export function createInfiniteReel(root: HTMLElement | null, options: InfiniteReelOptions = {}): InfiniteReelInstance {
+  const track = root?.querySelector<HTMLElement>('[data-mk-reel-track]');
+  if (!root || !track) return inert({ moveBy() {}, pause() {}, resume() {}, position: 0 });
+  const scope = createScope();
+  const still = reduced();
+  const vertical = options.axis === 'y';
+  scope.attr(root, 'data-mk-axis', vertical ? 'y' : 'x');
+  scope.attr(root, 'tabindex', root.getAttribute('tabindex') ?? '0');
+  scope.attr(track, 'style', track.getAttribute('style'));
+  const copies: HTMLElement[] = [];
+  let length = 0;
+  let position = 0;
+  let velocity = 0;
+  let paused = false;
+  let focused = false;
+  let drag: { point: number; id: number; moved: number } | null = null;
+  let suppressClick = false;
+  const coordinate = (event: PointerEvent) => vertical ? event.clientY : event.clientX;
+  const draw = () => {
+    if (still) {
+      if (vertical) root.scrollTop = position;
+      else root.scrollLeft = position;
+      return;
+    }
+    [track, ...copies].forEach((group, index) => {
+      const offset = index * length - position;
+      group.style.transform = vertical ? `translateY(${offset}px)` : `translateX(${offset}px)`;
+    });
+  };
+  const measure = () => {
+    copies.splice(0).forEach((copy) => copy.remove());
+    const rect = track.getBoundingClientRect();
+    length = vertical ? track.scrollHeight || rect.height : track.scrollWidth || rect.width;
+    if (!still && length > 0) {
+      const viewport = root.getBoundingClientRect();
+      const count = Math.min(30, Math.ceil((vertical ? viewport.height : viewport.width) / length) + 1);
+      for (let index = 0; index < count; index++) {
+        const copy = track.cloneNode(true) as HTMLElement;
+        copy.removeAttribute('id');
+        copy.removeAttribute('data-mk-reel-track');
+        copy.removeAttribute('data-mk');
+        copy.setAttribute('data-mk-reel-copy', '');
+        copy.setAttribute('aria-hidden', 'true');
+        copy.setAttribute('inert', '');
+        copy.querySelectorAll('[id]').forEach((child) => child.removeAttribute('id'));
+        copy.querySelectorAll('[data-mk]').forEach((child) => child.removeAttribute('data-mk'));
+        root.append(copy);
+        copies.push(copy);
+      }
+    }
+    position = length > 0 ? wrap(position, length) : 0;
+    draw();
+  };
+  const moveBy = (pixels: number) => {
+    if (scope.disposed || !Number.isFinite(pixels) || length <= 0) return;
+    position = wrap(position + pixels, length);
+    draw();
+  };
+  scope.on(root, 'wheel', (event) => {
+    if (still || !length) return;
+    event.preventDefault();
+    const units = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? (vertical ? root.clientHeight : root.clientWidth) : 1;
+    velocity += (vertical ? event.deltaY : event.deltaX || event.deltaY) * units * TIMING.infiniteReel.wheel;
+  }, { passive: false });
+  scope.on(root, 'pointerdown', (event) => {
+    if (event.button !== 0 || drag || still) return;
+    velocity = 0;
+    suppressClick = false;
+    drag = { point: coordinate(event), id: event.pointerId, moved: 0 };
+  });
+  scope.on(window, 'pointermove', (event) => {
+    if (!drag || event.pointerId !== drag.id) return;
+    const delta = drag.point - coordinate(event);
+    drag.moved += Math.abs(delta);
+    drag.point = coordinate(event);
+    if (drag.moved > TIMING.infiniteReel.dragThreshold) {
+      suppressClick = true;
+      root.setPointerCapture?.(event.pointerId);
+      moveBy(delta);
+      velocity = delta;
+    }
+  });
+  const release = (event: PointerEvent) => {
+    if (!drag || drag.id !== event.pointerId) return;
+    drag = null;
+    if (root.hasPointerCapture?.(event.pointerId)) root.releasePointerCapture(event.pointerId);
+  };
+  scope.on(window, 'pointerup', release);
+  scope.on(window, 'pointercancel', (event) => { velocity = 0; release(event); });
+  scope.on(root, 'lostpointercapture', release);
+  scope.on(root, 'click', (event) => {
+    if (suppressClick) { event.preventDefault(); event.stopPropagation(); suppressClick = false; }
+  }, true);
+  scope.on(root, 'focusin', () => { focused = true; });
+  scope.on(root, 'focusout', (event) => { focused = root.contains(event.relatedTarget as Node | null); });
+  scope.on(root, 'keydown', (event) => {
+    if (event.target !== root) return;
+    const next = vertical ? 'ArrowDown' : 'ArrowRight';
+    const previous = vertical ? 'ArrowUp' : 'ArrowLeft';
+    if (![next, previous, ' '].includes(event.key)) return;
+    event.preventDefault();
+    moveBy((event.key === previous ? -1 : 1) * length / Math.max(1, track.children.length));
+  });
+  if (typeof ResizeObserver === 'function') {
+    const observer = scope.observe(new ResizeObserver(measure));
+    observer.observe(root);
+    observer.observe(track);
+  }
+  scope.on(window, 'resize', measure);
+  scope.on(track, 'load', measure, true);
+  const scroll = { left: root.scrollLeft, top: root.scrollTop };
+  scope.add(() => {
+    copies.forEach((copy) => copy.remove());
+    if (drag && root.hasPointerCapture?.(drag.id)) root.releasePointerCapture(drag.id);
+    root.scrollLeft = scroll.left;
+    root.scrollTop = scroll.top;
+  });
+  measure();
+  if (!still) scope.add(whileVisible(root, (dt) => {
+    if (paused || focused || drag || document.hidden) return;
+    moveBy(((options.speed ?? 0) + velocity) * dt);
+    velocity *= Math.pow(Math.max(0, Math.min(0.999, options.friction ?? TIMING.infiniteReel.friction)), dt);
+  }));
+  return { moveBy, pause() { paused = true; }, resume() { paused = false; }, get position() { return position; }, destroy: () => scope.dispose() };
+}

package/src/recipes/infinite-reel/infinite-reel.css

@@ -0,0 +1,8 @@
+.mk-infinite-reel { position: relative; width: 100%; min-width: 0; overflow: hidden; touch-action: pan-y; cursor: grab; }
+.mk-infinite-reel:active { cursor: grabbing; }
+.mk-infinite-reel [data-mk-reel-track], .mk-infinite-reel [data-mk-reel-copy] { display: flex; width: max-content; gap: 16px; padding-right: 16px; will-change: transform; }
+.mk-infinite-reel [data-mk-reel-copy] { position: absolute; top: 0; left: 0; pointer-events: none; }
+.mk-infinite-reel [data-mk-reel-track] > *, .mk-infinite-reel [data-mk-reel-copy] > * { flex: none; }
+.mk-infinite-reel[data-mk-axis='y'] { height: 400px; touch-action: pan-x; }
+.mk-infinite-reel[data-mk-axis='y'] [data-mk-reel-track], .mk-infinite-reel[data-mk-axis='y'] [data-mk-reel-copy] { flex-direction: column; width: 100%; padding-right: 0; padding-bottom: 16px; }
+@media (prefers-reduced-motion: reduce) { .mk-infinite-reel { overflow: auto; cursor: auto; } }

package/src/recipes/letters/README.md

@@ -0,0 +1,30 @@
+# letters
+
+Letras que juegan:
+
+- **`scale`**: al pasar el ratón por la palabra cada letra crece (`scale 1.3`, sube 5 px) con un resorte con rebote (Motion 300/10), 30 ms después de la anterior; vuelve igual al salir.
+- **`blink`**: cada letra pasa a un color pastel y vuelve (0.6 s, `ease-in-out`) con retardos desordenados (.1, .6, .2, 1, .4, 1.2, .15, .8, .3 s), dos veces. Arranca 0.6 s después de crearse y al pasar el ratón.
+
+Origen: Dousan Miao, el titular de la portada («impactful»: `hero-letters-blink`, `hero-scale-letters`).
+
+## HTML / Astro
+
+```html
+<h1>I design <span data-mk="letters" data-mk-effect="blink">impactful</span> products</h1>
+<span data-mk="letters" data-mk-effect="scale">Dousan</span>
+```
+
+## React
+
+```tsx
+const ref = useRef<HTMLSpanElement>(null);
+useLetters(ref, { effect: 'blink', colors: ['#FFD6FF', '#C8B6FF'] });
+```
+
+## API
+
+`createLetters(el, { effect, colors, autoplay })` → `{ play(), destroy }`. `colors` por defecto: los pastel de Dousan (`#FFD6FF #E7C6FF #C8B6FF #B8C0FF #BBD0FF`).
+
+## Accesibilidad
+
+La palabra conserva su texto en `aria-label`. Con movimiento reducido no se parte ni se mueve.

package/src/recipes/letters/create-letters.ts

@@ -0,0 +1,113 @@
+import { gsap, EASE, SplitText, registerMotion } from '../../core/gsap';
+import { motionSpring } from '../../core/physics-spring';
+import { entrances } from '../../core/reduced';
+import { clearStyles } from '../../core/styles';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * Dousan's hero words. 'scale': on hover every letter springs up (scale 1.3,
+ * y −5 px, Motion 300/10), 30 ms after the previous one, and back on leave.
+ * 'blink': every letter flashes a pastel and returns (0.6 s, ease-in-out) with
+ * Dousan's scattered delays, twice; it plays 0.6 s after start and on hover.
+ */
+
+export interface LettersOptions {
+  effect?: 'scale' | 'blink';
+  /** Blink colours (default Dousan's pastels). */
+  colors?: string[];
+  /** Blink once 0.6 s after start (default true). */
+  autoplay?: boolean;
+}
+
+export interface LettersInstance extends Instance {
+  /** Blink now (the scale effect follows the pointer). */
+  play(): void;
+}
+
+const PASTELS = ['#FFD6FF', '#E7C6FF', '#C8B6FF', '#B8C0FF', '#BBD0FF'];
+const ORDER = [0, 2, 1, 4, 3, 0, 2, 1, 4];
+
+export function createLetters(el: HTMLElement | null, options: LettersOptions = {}): LettersInstance {
+  if (!el) {
+    warnOnce('letters: missing element');
+    return inert({ play() {} });
+  }
+  const t = TIMING.letters;
+  const { effect = 'scale', colors = PASTELS, autoplay = true } = options;
+  if (!entrances()) {
+    el.dataset.mkReady = '';
+    return {
+      play() {},
+      destroy() {
+        delete el.dataset.mkReady;
+      },
+    };
+  }
+  registerMotion();
+  const split = SplitText.create(el, { type: 'words,chars', wordsClass: 'mk-letters-word', charsClass: 'mk-letter', aria: 'auto' });
+  const chars = split.chars as HTMLElement[];
+  const cleanups: Array<() => void> = [];
+  const spring = motionSpring(...TIMING.springs.letters);
+
+  const lift = (up: boolean) => {
+    chars.forEach((char, index) =>
+      gsap.to(char, {
+        scale: up ? t.scale : 1,
+        y: up ? t.y : 0,
+        duration: spring.duration,
+        ease: spring.ease,
+        delay: index * t.step,
+        overwrite: true,
+      }),
+    );
+  };
+
+  const blink = () => {
+    chars.forEach((char, index) => {
+      gsap.killTweensOf(char, 'color');
+      clearStyles([char], ['color']);
+      const own = getComputedStyle(char).color;
+      const pastel = colors[ORDER[index % ORDER.length]! % colors.length]!;
+      gsap.to(char, {
+        keyframes: [
+          { color: pastel, duration: t.blink / 2, ease: EASE.inOut },
+          { color: own, duration: t.blink / 2, ease: EASE.inOut },
+        ],
+        delay: t.blinkDelays[index % t.blinkDelays.length],
+        repeat: 1,
+        repeatDelay: t.blinkRepeatDelay,
+        onComplete: () => clearStyles([char], ['color']),
+      });
+    });
+  };
+
+  if (effect === 'scale') {
+    const enter = () => lift(true);
+    const leave = () => lift(false);
+    el.addEventListener('pointerenter', enter);
+    el.addEventListener('pointerleave', leave);
+    cleanups.push(() => {
+      el.removeEventListener('pointerenter', enter);
+      el.removeEventListener('pointerleave', leave);
+    });
+  } else {
+    el.addEventListener('pointerenter', blink);
+    cleanups.push(() => el.removeEventListener('pointerenter', blink));
+    if (autoplay) {
+      const call = gsap.delayedCall(t.blinkStart, blink);
+      cleanups.push(() => call.kill());
+    }
+  }
+  el.dataset.mkReady = '';
+
+  return {
+    play: effect === 'blink' ? blink : () => lift(true),
+    destroy() {
+      for (const cleanup of cleanups.splice(0)) cleanup();
+      gsap.killTweensOf(chars);
+      split.revert();
+      delete el.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/marquee/README.md

@@ -0,0 +1,32 @@
+# marquee
+
+Una banda infinita: el primer hijo (el grupo) se copia hasta llenar la banda más una vez y cada copia se desplaza su propio tamaño en bucle lineal, sin cortes. Velocidad: 2 s por elemento del grupo (cuenta hasta 14).
+
+Origen: Siena Film Foundation, marquesina vertical de la página de película. Siena la usa en vertical; aquí el eje por defecto es horizontal (`axis: 'y'` para la de Siena).
+
+## HTML / Astro
+
+```html
+<div data-mk="marquee" class="logos">
+  <ul><li>Docaviv</li><li>Sundance</li><li>IDFA</li></ul>
+</div>
+<div data-mk="marquee" data-mk-axis="y" data-mk-reverse style="height: 300px">…</div>
+```
+
+Separa los elementos con `--mk-marquee-gap` o con margen dentro del grupo, no con `gap` en el contenedor.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const marquee = useMarquee(ref, { axis: 'x', speed: 2 });
+// marquee.current?.refresh() si cambia el contenido
+```
+
+## API
+
+`createMarquee(root, { axis, speed, reverse })` → `{ refresh(), destroy }`. Variables: `--mk-marquee-duration` (la escribe el motor), `--mk-marquee-gap`.
+
+## Accesibilidad
+
+Las copias llevan `aria-hidden` e `inert`: lectores y teclado encuentran el grupo una sola vez. Con movimiento reducido no hay copias ni movimiento.