@yewdiel21/motion-kit 0.9.0 → 0.10.0

package/src/recipes/editorial-reveal/README.md

@@ -0,0 +1,35 @@
+# editorial-reveal
+
+Composición de títulos enmascarados, tarjetas, CTA con flecha duplicada, cursor decorativo y grupos de contacto escalonados. Referencia conductual: CoMinVi. Reutiliza `mask-text`, `cascade`, `parallax` y `contrast` sin copiar assets ni código de la referencia.
+
+```html
+<section class="mk-editorial-reveal" data-mk="editorial-reveal">
+  <header data-mk-editorial-header>Estudio</header>
+  <section data-mk-tone="light">
+    <h1 data-mk-editorial-title>Un nuevo punto de vista.</h1>
+    <a href="/story" data-mk-editorial-card>
+      <img data-mk-editorial-card-image src="/your-image.webp" alt="Paisaje">
+      <h2>Explorar la historia</h2>
+    </a>
+    <a href="/story" data-mk-editorial-button><span data-mk-editorial-button-content>Leer</span></a>
+  </section>
+  <div data-mk-editorial-group>
+    <h2 data-mk-cascade="rise">Conversemos</h2>
+    <label data-mk-cascade="fade">Correo <input type="email"></label>
+  </div>
+  <span data-mk-editorial-cursor hidden>Leer ↗</span>
+</section>
+```
+
+```ts
+import { createEditorialReveal } from '@yewdiel21/motion-kit';
+import { useEditorialReveal } from '@yewdiel21/motion-kit/react';
+const motion = createEditorialReveal(root, { trigger: 'manual' });
+motion.play(); motion.reset(); motion.destroy();
+```
+
+Opciones: `trigger` (`scroll` por defecto, `load`, `manual`), `duration` 1.2 s, `stagger` .03 s, `y` 110 %, `ease` curva `(0.6,0,0,1)`, `hoverDuration` .5 s, `buttonShift` 2.25 em, `imageScale` 1.04 y `parallax` true. Los grupos mantienen el easing `expo.out` de `cascade`; la curva de referencia se aplica a títulos, CTA e imágenes. La entrada se reproduce una vez. `reset()` permite repetirla manualmente.
+
+Marca un marco opcional con `[data-mk-editorial-image]` y su hijo con `[data-mk-parallax-target]` para un parallax de intensidad .25. El header observa únicamente las secciones de su propia instancia. El estado de tarjeta se activa tanto con puntero como con foco; el cursor es decorativo, se oculta en touch y con movimiento reducido, y nunca sustituye al cursor del sistema. Sin JavaScript el contenido sigue visible.
+
+Con movimiento reducido el título queda entero, las entradas no ocultan campos y las interacciones conservan sus estados sin desplazamiento. `destroy()` es idempotente y restaura atributos/estilos propios y los helpers. El formulario, navegación y assets son responsabilidad de quien compone el contenido.

package/src/recipes/editorial-reveal/create-editorial-reveal.ts

@@ -0,0 +1,91 @@
+import { gsap, CustomEase, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { createMaskText } from '../mask-text/create-mask-text';
+import { createCascade } from '../cascade/create-cascade';
+import { createParallax } from '../parallax/create-parallax';
+import { createContrast } from '../contrast/create-contrast';
+
+export interface EditorialRevealOptions {
+  trigger?: 'scroll' | 'load' | 'manual';
+  /** Title and staged groups, seconds. Reference default 1.2. */
+  duration?: number;
+  stagger?: number;
+  /** Title pieces' start offset, percent. Reference default 110. */
+  y?: number;
+  ease?: string;
+  hoverDuration?: number;
+  /** Duplicate label/arrow content moves by this many em. */
+  buttonShift?: number;
+  imageScale?: number;
+  parallax?: boolean;
+}
+export interface EditorialRevealInstance extends Instance { play(): void; reset(): void; }
+let nextScope = 0;
+
+/** Editorial composition: masked headings, staged contact groups, restrained image/card motion and keyboard-equivalent buttons. */
+export function createEditorialReveal(root: HTMLElement | null, options: EditorialRevealOptions = {}): EditorialRevealInstance {
+  if (!root) return inert({ play() {}, reset() {} });
+  registerMotion();
+  const scope = createScope();
+  const context = gsap.context(() => {}, root);
+  const trigger = options.trigger ?? 'scroll';
+  const duration = options.duration ?? 1.2;
+  const stagger = options.stagger ?? .03;
+  const hoverDuration = options.hoverDuration ?? .5;
+  const ease = options.ease ?? 'mk-editorial-reference';
+  CustomEase.create('mk-editorial-reference', 'M0,0 C0.6,0 0,1 1,1');
+  // Helpers restore their own nodes; these snapshots also preserve caller inline styles/readiness.
+  const preserve = (el: HTMLElement) => ['style', 'data-mk-ready', 'aria-label'].forEach(name => scope.attr(el, name, el.getAttribute(name)));
+  preserve(root);
+  root.querySelectorAll<HTMLElement>('[data-mk-editorial-title],[data-mk-editorial-group],[data-mk-cascade],[data-mk-editorial-image],[data-mk-parallax-target],[data-mk-editorial-header],[data-mk-editorial-card-image],[data-mk-editorial-button-content]').forEach(preserve);
+  const titles = [...root.querySelectorAll<HTMLElement>('[data-mk-editorial-title]')].map(el => createMaskText(el, { by: 'lines', trigger, once: true, y: options.y ?? 110, duration, stagger, ease, delay: 0 }));
+  const groups = [...root.querySelectorAll<HTMLElement>('[data-mk-editorial-group]')].map(el => createCascade(el, { trigger, duration, step: stagger, once: true }));
+  const images = options.parallax === false ? [] : [...root.querySelectorAll<HTMLElement>('[data-mk-editorial-image]')].map(el => createParallax(el, { amount: .25 }));
+  const header = root.querySelector<HTMLElement>('[data-mk-editorial-header]');
+  const sections = [...root.querySelectorAll<HTMLElement>('[data-mk-tone]')];
+  const scopeId = String(++nextScope);
+  sections.forEach(el => scope.attr(el, 'data-mk-editorial-scope', scopeId));
+  const contrast = header ? createContrast(header, { sections: `[data-mk-editorial-scope="${scopeId}"]` }) : null;
+  scope.add(() => { titles.forEach(instance => instance.destroy()); groups.forEach(instance => instance.destroy()); images.forEach(instance => instance.destroy()); contrast?.destroy(); context.revert(); });
+  root.querySelectorAll<HTMLElement>('[data-mk-editorial-button]').forEach(button => {
+    const content = button.querySelector<HTMLElement>('[data-mk-editorial-button-content]');
+    if (!content) return;
+    let pointerInside = false;
+    const render = () => {
+      const active = pointerInside || button.contains(root.ownerDocument.activeElement);
+      context.add(() => gsap.to(content, { x: active && !reduced() ? `${options.buttonShift ?? 2.25}em` : '0em', duration: reduced() ? 0 : hoverDuration, ease, overwrite: true }));
+    };
+    scope.on(button, 'pointerenter', () => { pointerInside = true; render(); });
+    scope.on(button, 'pointerleave', () => { pointerInside = false; render(); });
+    scope.on(button, 'focusin', render);
+    scope.on(button, 'focusout', () => { scope.timeout(render, 0); });
+  });
+  const cursor = root.querySelector<HTMLElement>('[data-mk-editorial-cursor]');
+  if (cursor) { preserve(cursor); scope.attr(cursor, 'aria-hidden', 'true'); scope.attr(cursor, 'hidden', ''); }
+  root.querySelectorAll<HTMLElement>('[data-mk-editorial-card]').forEach(card => {
+    const image = card.querySelector<HTMLElement>('[data-mk-editorial-card-image]');
+    let pointerInside = false;
+    const render = () => {
+      const active = pointerInside || card.contains(root.ownerDocument.activeElement);
+      scope.attr(card, 'data-mk-editorial-active', active ? '' : null);
+      if (image) context.add(() => gsap.to(image, { scale: active && !reduced() ? options.imageScale ?? 1.04 : 1, duration: reduced() ? 0 : hoverDuration, ease, overwrite: true }));
+    };
+    scope.on(card, 'pointerenter', event => { pointerInside = true; render(); if (cursor && !reduced() && event.pointerType !== 'touch') scope.attr(cursor, 'hidden', null); });
+    scope.on(card, 'pointerleave', () => { pointerInside = false; render(); if (cursor) scope.attr(cursor, 'hidden', ''); });
+    scope.on(card, 'pointermove', event => {
+      if (!cursor || reduced() || event.pointerType === 'touch') return;
+      const rect = root.getBoundingClientRect();
+      cursor.style.transform = `translate(${event.clientX - rect.left + 16}px, ${event.clientY - rect.top + 16}px)`;
+    });
+    scope.on(card, 'focusin', render);
+    scope.on(card, 'focusout', () => { scope.timeout(render, 0); });
+  });
+  scope.attr(root, 'data-mk-ready', '');
+  return {
+    play() { if (!scope.disposed) { titles.forEach(instance => instance.play()); groups.forEach(instance => instance.play()); } },
+    reset() { if (!scope.disposed) { titles.forEach(instance => instance.hide()); groups.forEach(instance => instance.reset()); } },
+    destroy() { scope.dispose(); },
+  };
+}

package/src/recipes/editorial-reveal/editorial-reveal.css

@@ -0,0 +1,17 @@
+.mk-editorial-reveal { position: relative; isolation: isolate; color: var(--mk-text); }
+.mk-editorial-reveal [data-mk-editorial-image], .mk-editorial-reveal [data-mk-editorial-card] { overflow: clip; border-radius: 12px; }
+.mk-editorial-reveal [data-mk-editorial-image] > :is(img,video,picture) { display: block; width: 100%; height: 100%; object-fit: cover; }
+.mk-editorial-reveal [data-mk-editorial-card] { display: grid; gap: 20px; padding: 24px; background: var(--mk-surface-2); color: inherit; text-decoration: none; transition: background-color .5s cubic-bezier(.6, 0, 0, 1), color .5s cubic-bezier(.6, 0, 0, 1); }
+.mk-editorial-reveal [data-mk-editorial-card][data-mk-editorial-active] { background: var(--mk-accent); color: var(--mk-on-accent); }
+.mk-editorial-reveal [data-mk-editorial-card-image] { width: 100%; aspect-ratio: 4 / 3; object-fit: cover; border-radius: 8px; }
+.mk-editorial-reveal [data-mk-editorial-button] { display: inline-flex; overflow: clip; align-items: center; padding: 12px 18px; border: 1px solid var(--mk-outline-soft); border-radius: 8px; background: var(--mk-text); color: var(--mk-surface); text-decoration: none; font: inherit; cursor: pointer; }
+.mk-editorial-reveal [data-mk-editorial-button-content] { position: relative; display: flex; align-items: center; gap: 1em; padding-inline-end: 2.25em; }
+.mk-editorial-reveal [data-mk-editorial-button-content]::before, .mk-editorial-reveal [data-mk-editorial-button-content]::after { content: '↗'; position: absolute; inset-block-start: 0; }
+.mk-editorial-reveal [data-mk-editorial-button-content]::before { inset-inline-start: -2.25em; }
+.mk-editorial-reveal [data-mk-editorial-button-content]::after { inset-inline-end: 0; }
+.mk-editorial-reveal [data-mk-editorial-cursor] { pointer-events: none; position: absolute; z-index: 3; inset: 0 auto auto 0; width: max-content; height: max-content; padding: 10px 14px; border-radius: 30px; background: var(--mk-text); color: var(--mk-surface); font-size: .75rem; }
+.mk-editorial-reveal [hidden] { display: none !important; }
+.mk-editorial-reveal [data-mk-editorial-header][data-mk-on='dark'] { color: var(--mk-surface); }
+.mk-editorial-reveal :is(a,button,input,textarea):focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+.mk-editorial-reveal [data-mk-editorial-group] [data-mk-cascade='rise'] { position: relative; }
+@media (prefers-reduced-motion: reduce) { .mk-editorial-reveal *, .mk-editorial-reveal *::after, .mk-editorial-reveal *::before { animation: none !important; transition: none !important; } }

package/src/recipes/fill-text/README.md

@@ -2,7 +2,7 @@
 
 Un texto cuyas letras empiezan al 20 % y se rellenan una tras otra ligadas al scroll: desde que el borde superior del texto llega al 90 % de la pantalla hasta que su centro llega al 40 % (cada letra 0.5 s de una línea de tiempo lineal, 0.1 s entre letras).
 
-Origen: iyo.ai, módulo `fill-text` (`GM`): SplitText `words, chars`, `autoAlpha .2 → 1`, `stagger .1`, `ease: linear`, ScrollTrigger con `scrub` de `top 90%` a `center 40%`. Aquí sigue al scroll con `trackScroll` y lee el texto completo a los lectores de pantalla (iyo usaba `aria: none`).
+Divide el texto en palabras y caracteres: opacidad .2 → 1, stagger .1 y avance de scroll entre `top 90%` y `center 40%`. El texto completo sigue accesible a lectores de pantalla.
 
 ## HTML / Astro
 

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

@@ -5,7 +5,7 @@ import { TIMING } from '../../core/timing';
 import { inert, warnOnce, type Instance } from '../../core/types';
 
 /*
- * iyo.ai's fill-text: the letters start at 20 % and fill in one after another,
+ * fill-text: the letters start at 20 % and fill in one after another,
  * tied to the scroll, from when the text's top reaches 90 % of the screen until
  * its centre reaches 40 % (each letter 0.5 s of a linear timeline, 0.1 s apart).
  */

package/src/recipes/film-hero/README.md

@@ -0,0 +1,23 @@
+# film-hero
+
+Hero editorial de cine: líneas ascendentes, reglas que se trazan, imagen/video con escala y parallax dentro del contenedor de scroll. Componer con `action-button`, `details` y `trailer` para una ficha completa. La demo incluye créditos, premios, un selector de siguiente producción y medios locales originales.
+
+```html
+<section class="mk-film-hero" data-mk="film-hero">
+  <h1 class="mk-film-hero__title">
+    <span class="mk-film-hero__mask"><span data-mk-film-line>Una historia</span></span>
+  </h1>
+  <span data-mk-film-rule></span>
+  <div class="mk-film-hero__visual">
+    <img class="mk-film-hero__media" src="/mi-imagen.jpg" alt="…" />
+  </div>
+</section>
+```
+
+`createFilmHero(root, { duration:.7, stagger:.08, parallax:.12, scale:1.08, edge:'organic', scroller })` → `replay()`, `refresh()`, `destroy()`. React: `useFilmHero(ref, options, deps?)`. Para demos/paneles con scroll, marcar el contenedor `data-mk-scroll-root` o pasar `scroller`; no requiere scroll global ni Lenis. `edge:'straight'` conserva el recorte rectangular.
+
+Las líneas se marcan explícitamente; no cambia el HTML del título ni duplica su nombre accesible. Reduced-motion deja visibles texto/reglas y desactiva parallax. Sin JavaScript el contenido sigue visible. El observer, rAF pendiente, listeners, GSAP y estilos se revierten con `destroy()`.
+
+El borde `organic` es un polígono CSS estático **aproximado**. El A24 original usa un algoritmo procedural con ruido, respuesta al cursor y disolución al scroll, además de un disco Three para la siguiente producción. Esta receta no incluye ese algoritmo ni afirma equivalencia. El disco CSS de la demo es otra aproximación decorativa. Las duraciones .7/.9s y stagger proceden de las fuentes inspeccionadas; `power3.out` reemplaza la curva custom del original. No incluye assets ni tipografías de A24.
+
+Tokens: `--mk-film-ink`, `--mk-film-paper`, `--mk-film-font`; el motor escribe y restaura `--mk-film-shift`/`--mk-film-scale`.

package/src/recipes/film-hero/create-film-hero.ts

@@ -0,0 +1,65 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { entrances, reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface FilmHeroOptions {
+  duration?: number;
+  stagger?: number;
+  /** Media travel as a fraction of the hero height. 0 disables parallax. */
+  parallax?: number;
+  scale?: number;
+  edge?: 'organic' | 'straight';
+  /** Scrollable demo panels and nested page shells can supply their own scroll root. */
+  scroller?: HTMLElement | Window;
+}
+export interface FilmHeroInstance extends Instance { replay(): void; refresh(): void; }
+
+/** Editorial line reveals with scoped, scroll-driven media. Organic edge is an approximation. */
+export function createFilmHero(root: HTMLElement | null, options: FilmHeroOptions = {}): FilmHeroInstance {
+  if (!root) return inert({ replay() {}, refresh() {} });
+  const scope = createScope();
+  scope.attr(root, 'data-mk-film-ready', '');
+  scope.attr(root, 'data-mk-film-edge', options.edge ?? 'organic');
+  scope.attr(root, 'style', root.getAttribute('style'));
+  const still = reduced();
+  const lines = [...root.querySelectorAll<HTMLElement>('[data-mk-film-line]')];
+  const rules = [...root.querySelectorAll<HTMLElement>('[data-mk-film-rule]')];
+  [...lines, ...rules].forEach(element => scope.attr(element, 'style', element.getAttribute('style')));
+  let timeline: gsap.core.Timeline | null = null;
+  const context = gsap.context(() => {}, root);
+  const replay = () => {
+    if (scope.disposed || !entrances()) return;
+    registerMotion();
+    context.add(() => {
+      timeline?.kill();
+      timeline = gsap.timeline();
+      if (lines.length) timeline.fromTo(lines, { yPercent: 120 }, { yPercent: 0, duration: options.duration ?? .7, stagger: options.stagger ?? .08, ease: 'power3.out' }, 0);
+      if (rules.length) timeline.fromTo(rules, { scaleX: 0, transformOrigin: 'left center' }, { scaleX: 1, duration: .9, stagger: .06, ease: 'power3.out' }, .08);
+    });
+  };
+  replay();
+  const scroller = options.scroller ?? root.closest<HTMLElement>('[data-mk-scroll-root]') ?? window;
+  let frame = 0;
+  const refresh = () => {
+    if (scope.disposed || still) return;
+    const rect = root.getBoundingClientRect();
+    const view = scroller instanceof HTMLElement ? scroller.getBoundingClientRect() : { top: 0, height: window.innerHeight };
+    const progress = Math.max(0, Math.min(1, (view.top - rect.top) / Math.max(1, rect.height)));
+    root.style.setProperty('--mk-film-shift', `${(progress * rect.height * (options.parallax ?? .12)).toFixed(2)}px`);
+    root.style.setProperty('--mk-film-scale', String((options.scale ?? 1.08) - progress * Math.max(0, (options.scale ?? 1.08) - 1)));
+  };
+  if (!still) {
+    const schedule = () => {
+      if (frame) return;
+      frame = requestAnimationFrame(() => { frame = 0; refresh(); });
+    };
+    scope.on(scroller, 'scroll', schedule, { passive: true });
+    scope.on(window, 'resize', schedule, { passive: true });
+    if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(schedule)).observe(root);
+    scope.add(() => cancelAnimationFrame(frame));
+    refresh();
+  }
+  scope.add(() => { timeline?.kill(); context.revert(); });
+  return { replay, refresh, destroy: () => scope.dispose() };
+}

package/src/recipes/film-hero/film-hero.css

@@ -0,0 +1,29 @@
+.mk-film-hero {
+  --mk-film-ink: var(--mk-text, #191b18);
+  --mk-film-paper: var(--mk-surface, #f4f1e8);
+  --mk-film-font: Georgia, 'Times New Roman', serif;
+  position: relative;
+  isolation: isolate;
+  color: var(--mk-film-ink);
+  background: var(--mk-film-paper);
+  overflow: clip;
+}
+.mk-film-hero__credits { padding: clamp(20px, 5cqw, 64px); text-align: center; }
+.mk-film-hero__eyebrow { font: 500 .65rem/1.5 var(--mk-font-mono, monospace); text-transform: uppercase; letter-spacing: .18em; }
+.mk-film-hero__title { margin: .2em 0 .35em; font: 400 clamp(3.5rem, 10cqw, 8rem)/.82 var(--mk-film-font); letter-spacing: -.065em; text-transform: uppercase; }
+.mk-film-hero__mask { display: block; overflow: clip; padding-bottom: .08em; margin-bottom: -.08em; }
+[data-mk-film-line] { display: block; }
+[data-mk-film-rule] { display: block; height: 1px; border: 0; background: currentColor; margin: 16px 0; }
+.mk-film-hero__metadata { display: grid; gap: 0; margin: 24px 0 0; font: .8rem/1.5 var(--mk-font, sans-serif); }
+.mk-film-hero__metadata > div { display: flex; align-items: baseline; justify-content: space-between; gap: 20px; padding: 8px 0; border-top: 1px solid currentColor; }
+.mk-film-hero__metadata dt { font: .6rem/1.5 var(--mk-font-mono, monospace); text-transform: uppercase; letter-spacing: .14em; }
+.mk-film-hero__metadata dd { margin: 0; text-align: right; }
+.mk-film-hero__visual { position: relative; min-height: clamp(260px, 45cqw, 540px); display: grid; place-items: center; overflow: clip; color: #fffdf1; background: #243c36; }
+.mk-film-hero__media { position: absolute; inset: -8% 0; width: 100%; height: 116%; object-fit: cover; transform: translateY(var(--mk-film-shift, 0px)) scale(var(--mk-film-scale, 1)); transform-origin: center; }
+.mk-film-hero__visual::after { content: ''; position: absolute; inset: 0; pointer-events: none; background: linear-gradient(transparent, #00120c66); }
+.mk-film-hero__caption { position: relative; z-index: 1; padding: 48px 24px; text-align: center; }
+.mk-film-hero__caption blockquote { font: 400 clamp(2.25rem, 6cqw, 5.5rem)/.95 var(--mk-film-font); letter-spacing: -.04em; margin: 0 0 24px; text-transform: uppercase; }
+.mk-film-hero[data-mk-film-edge="organic"] .mk-film-hero__visual {
+  clip-path: polygon(0 7%, 9% 8%, 20% 5%, 32% 2%, 43% 0, 54% 2%, 68% 6%, 82% 8%, 93% 6%, 100% 4%, 100% 100%, 0 100%);
+}
+@media (prefers-reduced-motion: reduce) { .mk-film-hero__media { transform: none; } }

package/src/recipes/fit-text/README.md

@@ -2,8 +2,6 @@
 
 Ajusta el tamaño de una línea de texto para que ocupe exactamente el ancho de contenido de su padre; se reajusta al cambiar el ancho.
 
-Origen: portfolio — "Portfolio" y "Contacto" a ancho completo.
-
 ## Vanilla / Astro
 
 ```html

package/src/recipes/flow/README.md

@@ -2,8 +2,6 @@
 
 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

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

@@ -3,7 +3,7 @@ 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. */
+/* 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';

package/src/recipes/font-cycle/README.md

@@ -0,0 +1,11 @@
+# font-cycle
+
+Caras tipográficas alternadas por carácter, con copia enmascarada que entra al hover y al foco. Adaptación de la tipografía de Mat Voyce; el original también superpone GIFs. No incluye fuentes ni ilustraciones del sitio.
+
+```html
+<button class="mk-font-cycle" data-mk="font-cycle" data-mk-font-alternate="Georgia, serif">Explore</button>
+```
+
+`createFontCycle(root, { faces, text, duration: .6, stagger: .035, overlaySrc })` devuelve `play()`, `reset()`, `active`, `destroy()`. Duraciones en segundos, ease `power3.out`. `faces` es una tupla de `{ family?, axes?: { wght: 500, wdth: 75 }, weight?, style? }`; cada carácter alterna las dos caras. Los ejes que no admita la fuente no tienen efecto. `overlaySrc` (o `data-mk-font-overlay`) es una imagen decorativa propia, opcional.
+
+React: `useFontCycle(ref, options, deps)`. La receta administra los hijos del elemento mientras está montada; no cambies sus hijos durante ese intervalo. Una copia accesible conserva el texto sin duplicar letras. El foco activa el mismo efecto que hover; con movimiento reducido el cambio es inmediato y no se muestra la imagen animada. `destroy()` restaura los nodos y atributos originales.

package/src/recipes/font-cycle/create-font-cycle.ts

@@ -0,0 +1,126 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { splitGraphemes } from '../../core/split';
+import { inert, type Instance } from '../../core/types';
+
+export interface FontCycleFace {
+  /** A font supplied by the application. No font files are downloaded by this recipe. */
+  family?: string;
+  axes?: Readonly<Record<string, number>>;
+  weight?: number;
+  style?: 'normal' | 'italic' | 'oblique';
+}
+
+export interface FontCycleOptions {
+  text?: string;
+  /** Alternated per character; the second face rolls in on hover or focus. */
+  faces?: readonly [FontCycleFace, FontCycleFace];
+  /** Seconds per character. */
+  duration?: number;
+  /** Seconds between characters. */
+  stagger?: number;
+  /** Optional decorative artwork owned by the consumer. Hidden with reduced motion. */
+  overlaySrc?: string;
+}
+
+export interface FontCycleInstance extends Instance {
+  play(): void;
+  reset(): void;
+  readonly active: boolean;
+}
+
+function applyFace(element: HTMLElement, face: FontCycleFace) {
+  if (face.family) element.style.fontFamily = face.family;
+  if (face.weight !== undefined) element.style.fontWeight = String(face.weight);
+  if (face.style) element.style.fontStyle = face.style;
+  const axes = Object.entries(face.axes ?? {}).filter(([tag, value]) => /^[\w ]{4}$/.test(tag) && Number.isFinite(value));
+  if (axes.length) element.style.fontVariationSettings = axes.map(([tag, value]) => `"${tag}" ${value}`).join(', ');
+}
+
+/** Alternating variable-font faces in a masked, reversible character roll. */
+export function createFontCycle(root: HTMLElement | null, options: FontCycleOptions = {}): FontCycleInstance {
+  if (!root || typeof document === 'undefined') return inert({ play() {}, reset() {}, active: false });
+  registerMotion();
+  const scope = createScope();
+  const original = [...root.childNodes];
+  const text = options.text ?? root.textContent ?? '';
+  const faces = options.faces ?? [
+    { weight: 500, axes: { wght: 500, wdth: 75 } },
+    { family: root.dataset.mkFontAlternate, weight: 900, axes: { wght: 900, wdth: 125 } },
+  ];
+  const duration = Math.max(0, options.duration ?? 0.6);
+  const stagger = Math.max(0, options.stagger ?? 0.035);
+  const tracks: HTMLElement[] = [];
+  let animation: gsap.core.Tween | undefined;
+  let active = false;
+  let hovered = false;
+  let focused = false;
+
+  const copy = document.createElement('span');
+  copy.className = 'mk-font-cycle__accessible';
+  copy.textContent = text;
+  const visual = document.createElement('span');
+  visual.className = 'mk-font-cycle__visual';
+  visual.setAttribute('aria-hidden', 'true');
+  for (const [index, letter] of splitGraphemes(text, Number.MAX_SAFE_INTEGER).entries()) {
+    const character = document.createElement('span');
+    character.className = 'mk-font-cycle__char';
+    const track = document.createElement('span');
+    track.className = 'mk-font-cycle__track';
+    for (let side = 0; side < 2; side++) {
+      const face = document.createElement('span');
+      face.className = 'mk-font-cycle__face';
+      face.textContent = letter === ' ' ? '\u00a0' : letter;
+      applyFace(face, faces[(index + side) % 2]!);
+      const sizer = face.cloneNode(true) as HTMLElement;
+      sizer.className = 'mk-font-cycle__sizer';
+      character.append(sizer);
+      track.append(face);
+    }
+    character.append(track);
+    visual.append(character);
+    tracks.push(track);
+  }
+  root.replaceChildren(copy, visual);
+  const overlaySrc = options.overlaySrc ?? root.dataset.mkFontOverlay;
+  if (overlaySrc) {
+    const overlay = document.createElement('img');
+    overlay.className = 'mk-font-cycle__overlay';
+    overlay.alt = '';
+    overlay.setAttribute('aria-hidden', 'true');
+    scope.attr(root, 'data-mk-font-overlay-ready', null);
+    const loaded = () => {
+      if (!scope.disposed) scope.attr(root, 'data-mk-font-overlay-ready', overlay.naturalWidth > 0 ? '' : null);
+    };
+    scope.on(overlay, 'load', loaded);
+    scope.on(overlay, 'error', () => {
+      if (!scope.disposed) scope.attr(root, 'data-mk-font-overlay-ready', null);
+    });
+    overlay.src = overlaySrc;
+    root.append(overlay);
+    if (overlay.complete) loaded();
+  }
+  scope.add(() => root.replaceChildren(...original));
+  scope.attr(root, 'class', `${root.className} mk-font-cycle`.trim());
+  scope.attr(root, 'data-mk-ready', '');
+
+  const setActive = (next: boolean) => {
+    if (scope.disposed || next === active) return;
+    active = next;
+    scope.attr(root, 'data-mk-active', next ? '' : null);
+    animation?.kill();
+    if (reduced() || duration === 0) gsap.set(tracks, { yPercent: next ? -50 : 0 });
+    else animation = gsap.to(tracks, { yPercent: next ? -50 : 0, duration, stagger, ease: 'power3.out', overwrite: true });
+  };
+  scope.on(root, 'mouseenter', () => { hovered = true; setActive(true); });
+  scope.on(root, 'mouseleave', () => { hovered = false; setActive(focused); });
+  scope.on(root, 'focusin', () => { focused = true; setActive(true); });
+  scope.on(root, 'focusout', (event) => {
+    if (event.relatedTarget instanceof Node && root.contains(event.relatedTarget)) return;
+    focused = false;
+    setActive(hovered);
+  });
+  scope.add(() => animation?.kill());
+  return { play: () => setActive(true), reset: () => setActive(false), get active() { return active; }, destroy: () => scope.dispose() };
+}

package/src/recipes/font-cycle/font-cycle.css

@@ -0,0 +1,36 @@
+.mk-font-cycle {
+  position: relative;
+  display: inline-block;
+  color: inherit;
+  font-family: var(--mk-font, sans-serif);
+  isolation: isolate;
+}
+.mk-font-cycle__accessible {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+.mk-font-cycle__visual { display: inline-flex; white-space: pre; }
+.mk-font-cycle__char {
+  position: relative;
+  display: inline-grid;
+  overflow: hidden;
+  line-height: 1.12;
+  vertical-align: bottom;
+}
+.mk-font-cycle__sizer { grid-area: 1 / 1; visibility: hidden; padding-inline: .035em; }
+.mk-font-cycle__track { position: absolute; inset: 0 0 auto; display: flex; flex-direction: column; will-change: transform; }
+.mk-font-cycle__face { display: block; flex: none; text-align: center; padding-inline: .035em; }
+.mk-font-cycle__overlay { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; pointer-events: none; opacity: 0; }
+.mk-font-cycle[data-mk-active][data-mk-font-overlay-ready] .mk-font-cycle__overlay { opacity: 1; }
+.mk-font-cycle[data-mk-active][data-mk-font-overlay-ready] .mk-font-cycle__visual { opacity: 0; }
+.mk-font-cycle:focus-visible { outline: 2px solid var(--mk-accent, currentColor); outline-offset: .15em; }
+@media (prefers-reduced-motion: reduce) {
+  .mk-font-cycle__track { will-change: auto; }
+  .mk-font-cycle[data-mk-active][data-mk-font-overlay-ready] .mk-font-cycle__visual { opacity: 1; }
+  .mk-font-cycle[data-mk-active][data-mk-font-overlay-ready] .mk-font-cycle__overlay { display: none; }
+}

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

@@ -1,8 +1,6 @@
 # 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`).
+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`).
 
 ## HTML / Astro
 

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

@@ -5,11 +5,11 @@ 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
+ * 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
+ * screen. open(true) brings it back
  * to full (1 s expo.out).
  */
 

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

@@ -0,0 +1,16 @@
+# image-zoom
+
+Contrazoom inspirado en las categorías de [Bernice](https://bernicebakery.com/collections/cakes). Marco 1→1.1 e imagen 1.2→1 en 1 s con cubic-bezier(.28,.71,0,.98).
+
+```html
+<a class="mk-image-zoom" data-mk="image-zoom" href="/collection">
+  <span data-mk-zoom-frame style="border-radius:50%;width:10rem;height:10rem">
+    <img src="/image.jpg" width="400" height="400" alt="Descripción" />
+  </span>
+  <strong>Colección</strong>
+</a>
+```
+
+`createImageZoom(root,{duration:1,frameScale:1.1,imageScale:1.2})`, `autoInit()`, `useImageZoom(ref,options,deps)`. API `open(boolean)`, `active`, `destroy()`.
+
+Hover/focus revelan el mismo efecto. Root puede contener imagen, video o picture dentro de frame. Para marcado distinto usar `data-mk-zoom-image` en el elemento que escala (evitar marcar también su padre). Variables: `--mk-zoom-duration`, `--mk-zoom-frame-scale`, `--mk-zoom-image-scale`, `--mk-zoom-ease`. Sin transformaciones bajo movimiento reducido; las imágenes siguen accesibles.

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

@@ -0,0 +1,27 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface ImageZoomOptions { duration?: number; frameScale?: number; imageScale?: number; }
+export interface ImageZoomInstance extends Instance { open(active: boolean): void; readonly active: boolean; }
+
+/** Counter-zoom: the clipped frame grows as the picture inside settles to 1×. */
+export function createImageZoom(root: HTMLElement | null, options: ImageZoomOptions = {}): ImageZoomInstance {
+  if (!root) return inert({ open() {}, active: false });
+  const scope = createScope();
+  let active = false;
+  let pointer = false;
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'data-mk-ready', '');
+  const setVariable = (name: string, value: number | undefined, suffix = '') => {
+    if (Number.isFinite(value)) root.style.setProperty(name, `${Math.max(0, value!)}${suffix}`);
+  };
+  setVariable('--mk-zoom-duration', options.duration, 's');
+  setVariable('--mk-zoom-frame-scale', options.frameScale);
+  setVariable('--mk-zoom-image-scale', options.imageScale);
+  const set = (on: boolean) => { if (!scope.disposed) { active = on; scope.attr(root, 'data-mk-active', on ? '' : null); } };
+  scope.on(root, 'pointerenter', () => { pointer = true; set(true); });
+  scope.on(root, 'pointerleave', () => { pointer = false; if (!root.contains(document.activeElement)) set(false); });
+  scope.on(root, 'focusin', () => set(true));
+  scope.on(root, 'focusout', (event) => { if (!pointer && !root.contains((event as FocusEvent).relatedTarget as Node | null)) set(false); });
+  return { open: set, get active() { return active; }, destroy: () => scope.dispose() };
+}

package/src/recipes/image-zoom/image-zoom.css

@@ -0,0 +1,7 @@
+.mk-image-zoom { --mk-zoom-duration: 1s; --mk-zoom-frame-scale: 1.1; --mk-zoom-image-scale: 1.2; --mk-zoom-ease: cubic-bezier(.28,.71,0,.98); color: inherit; text-decoration: none; }
+.mk-image-zoom [data-mk-zoom-frame] { display: block; overflow: hidden; border-radius: inherit; transition: transform var(--mk-zoom-duration) var(--mk-zoom-ease); }
+.mk-image-zoom [data-mk-zoom-frame] > :is(img,video,picture), .mk-image-zoom [data-mk-zoom-image] { display: block; width: 100%; height: 100%; object-fit: cover; transform: scale(var(--mk-zoom-image-scale)); transition: transform var(--mk-zoom-duration) var(--mk-zoom-ease); }
+.mk-image-zoom:is(:hover,:focus-within,[data-mk-active]) [data-mk-zoom-frame] { transform: scale(var(--mk-zoom-frame-scale)); }
+.mk-image-zoom:is(:hover,:focus-within,[data-mk-active]) [data-mk-zoom-frame] > :is(img,video,picture), .mk-image-zoom:is(:hover,:focus-within,[data-mk-active]) [data-mk-zoom-image] { transform: scale(1); }
+.mk-image-zoom:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 5px; }
+@media (prefers-reduced-motion: reduce) { .mk-image-zoom [data-mk-zoom-frame], .mk-image-zoom [data-mk-zoom-frame] > :is(img,video,picture), .mk-image-zoom [data-mk-zoom-image] { transform: none !important; transition: none; } }

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

@@ -1,6 +1,6 @@
 # infinite-reel
 
-Reel infinito horizontal o vertical con rueda, arrastre e inercia (Siena).
+Reel infinito horizontal o vertical con rueda, arrastre e inercia.
 
 ```html
 <div class="mk-infinite-reel" data-mk="infinite-reel" aria-label="Películas">
@@ -16,8 +16,8 @@ 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.
+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.
 
 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.
+Desde 0.8.0.

package/src/recipes/joined-cta/README.md

@@ -0,0 +1,13 @@
+# joined-cta
+
+CTA inspirado en [Silvia Sguotti](https://silviasguotti.design/): tres cápsulas que se desplazan, giran y se unen. El CSS público declara .5 s ease-in-out.
+
+```html
+<button type="button" class="mk-joined-cta" data-mk="joined-cta" aria-label="Keep in touch">
+  <span>KEEP</span><span>IN</span><span>TOUCH</span>
+</button>
+```
+
+`createJoinedCta(root,{duration:.5})`, `autoInit()`, o `useJoinedCta(ref,options,deps)`. Se puede usar un enlace real en lugar del botón. API `expand()`, `collapse()`, `expanded`, `destroy()`.
+
+Hover y foco equivalentes. En touch o pantallas <=420px se presenta una cápsula legible sin giro. Movimiento reducido conserva el cambio de estado instantáneo. Variables: `--mk-joined-duration`, `--mk-joined-bg`, `--mk-joined-color`. El contenido debe tener exactamente tres spans. No incluye navegación ni envío de correo.