@yewdiel21/motion-kit 0.9.1 → 0.10.0

package/src/recipes/action-button/README.md

@@ -0,0 +1,31 @@
+# action-button
+
+Botones con sombra firme inspirados en Don't Look Up y etiquetas en máscara inspiradas en la ficha A24.
+
+## HTML / Astro
+
+```html
+<button class="mk-action-button" data-mk="action-button" data-mk-variant="primary">Empezar</button>
+<button class="mk-action-button" data-mk="action-button" data-mk-variant="film">
+  <span data-mk-action-label>Ver trailer ↗</span>
+</button>
+```
+
+```ts
+const button = createActionButton(element, {
+  variant: 'icon', toggle: true,
+  onPressedChange: value => console.log(value),
+});
+button.setPressed(true);
+button.destroy();
+```
+
+React: `useActionButton(ref, options, deps?)`. Conserva botones/enlaces semánticos escritos por el consumidor; la receta no ejecuta navegación ni reproduce sonidos. Variantes: `primary`, `secondary`, `icon`, `stepper`, `film`. Las variantes también pueden usarse sólo con CSS mediante `data-mk-action-variant`; `film` necesita el motor para duplicar su etiqueta marcada.
+
+## Movimiento / accesibilidad
+
+Press 130ms ease-out, color150ms ease. Hover baja3px y reduce sombra; active5×6px. Film usa clip.4s/translate.35s/scale.3s y copia retrasada75ms. Es una adaptación reusable; no reproduce todos los overrides particulares del juego original ni su lógica económica.
+
+`toggle` es opt-in y usa `aria-pressed`; controles disabled y `aria-disabled` no cambian el estado. Un icono necesita `aria-label`. La copia rolling tiene `aria-hidden`, el nodo original se conserva. Focus visible explícito. Reduced-motion elimina las transiciones y la duplicación visual; los gestos de botón siguen indicando estado. `destroy()` restaura nodos/atributos y retira listeners.
+
+Tokens: `--mk-action-ink`, `--mk-action-paper`, `--mk-action-lift`, `--mk-action-tilt`, `--mk-action-focus`, `--mk-film-font`.

package/src/recipes/action-button/action-button.css

@@ -0,0 +1,113 @@
+.mk-action-button {
+  --mk-action-ink: var(--mk-text, #171713);
+  --mk-action-paper: var(--mk-surface, #f7f5ee);
+  --mk-action-lift: 5px;
+  --mk-action-tilt: -1.2deg;
+  appearance: none;
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: .6em;
+  min-height: 44px;
+  padding: .65em 1.5em;
+  border: 3px solid var(--mk-action-paper);
+  border-radius: 24px 30px 22px 28px / 30px 22px 28px 24px;
+  background: var(--mk-action-ink);
+  color: var(--mk-action-paper);
+  box-shadow: var(--mk-action-lift) calc(var(--mk-action-lift) + 1px) 0 var(--mk-action-ink);
+  transform: rotate(var(--mk-action-tilt));
+  font: 700 .85rem/1.15 var(--mk-font, sans-serif);
+  letter-spacing: .045em;
+  text-transform: uppercase;
+  text-decoration: none;
+  cursor: pointer;
+  touch-action: manipulation;
+  transition: transform 130ms ease-out, box-shadow 130ms ease-out, background-color 150ms ease, color 150ms ease, border-color 150ms ease;
+}
+.mk-action-button[data-mk-action-variant="secondary"],
+.mk-action-button[data-mk-action-variant="icon"] {
+  --mk-action-tilt: 1.1deg;
+  background: var(--mk-action-paper);
+  border-color: var(--mk-action-ink);
+  color: var(--mk-action-ink);
+}
+.mk-action-button[data-mk-action-variant="icon"] {
+  width: 44px;
+  padding: 8px;
+  border-radius: 16px 20px 15px 19px / 20px 15px 19px 16px;
+}
+.mk-action-button svg { width: 1.25em; height: 1.25em; flex: none; }
+.mk-action-button[data-mk-action-variant="stepper"] {
+  --mk-action-tilt: 0deg;
+  min-width: 44px;
+  padding: .5em;
+  border: 2px solid var(--mk-action-ink);
+  border-radius: 11px;
+  background: var(--mk-action-paper);
+  color: var(--mk-action-ink);
+  box-shadow: none;
+}
+.mk-action-button[data-mk-action-variant="film"] {
+  --mk-action-tilt: 0deg;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  color: inherit;
+  box-shadow: none;
+  padding: .5em 0;
+  font-family: var(--mk-film-font, Georgia, serif);
+  font-size: 1.25rem;
+}
+.mk-action-button[data-mk-action-variant="film"]::before,
+.mk-action-button[data-mk-action-variant="film"]::after {
+  content: "";
+  position: absolute;
+  inset: 0 0 auto;
+  height: 1px;
+  background: currentColor;
+  transition: transform .4s cubic-bezier(.32,.72,0,1);
+}
+.mk-action-button[data-mk-action-variant="film"]::after { inset: auto 0 0; }
+[data-mk-action-label] { display: inline-grid; overflow: clip; }
+.mk-action-button__line, .mk-action-button__copy {
+  grid-area: 1 / 1;
+  transition: clip-path .4s cubic-bezier(.32,.72,0,1), translate .35s cubic-bezier(.32,.72,0,1), scale .3s cubic-bezier(.34,2.27,.64,1);
+}
+.mk-action-button__line { clip-path: inset(0); transform-origin: bottom; }
+.mk-action-button__copy { clip-path: inset(0 0 100%); translate: 0 -.25em; scale: 1.05; transform-origin: top; }
+@media (hover: hover) {
+  .mk-action-button:not(:disabled):not([aria-disabled="true"]):hover {
+    transform: rotate(var(--mk-action-tilt)) translate(3px, 3px);
+    box-shadow: 2px 3px 0 var(--mk-action-ink);
+  }
+  .mk-action-button:is([data-mk-action-variant="secondary"], [data-mk-action-variant="icon"], [data-mk-action-variant="stepper"]):not(:disabled):not([aria-disabled="true"]):hover {
+    background: var(--mk-action-ink);
+    border-color: var(--mk-action-paper);
+    color: var(--mk-action-paper);
+  }
+  .mk-action-button[data-mk-action-variant="stepper"]:not(:disabled):not([aria-disabled="true"]):hover { transform: none; box-shadow: none; }
+}
+.mk-action-button:not(:disabled):not([aria-disabled="true"]):active,
+.mk-action-button[aria-pressed="true"] {
+  transform: rotate(var(--mk-action-tilt)) translate(var(--mk-action-lift), calc(var(--mk-action-lift) + 1px));
+  box-shadow: 0 0 0 var(--mk-action-ink);
+}
+.mk-action-button[aria-pressed="true"] { background: var(--mk-action-ink); color: var(--mk-action-paper); }
+.mk-action-button[aria-pressed="true"]:not(:disabled):not([aria-disabled="true"]):hover { transform: rotate(var(--mk-action-tilt)) translate(var(--mk-action-lift), calc(var(--mk-action-lift) + 1px)); box-shadow: none; }
+.mk-action-button[data-mk-action-variant="stepper"]:not(:disabled):not([aria-disabled="true"]):active { transform: translateY(1px); box-shadow: none; }
+.mk-action-button[data-mk-action-variant="film"]:is(:hover, :focus-visible):not(:disabled):not([aria-disabled="true"]) {
+  transform: scale(1.03) rotate(-.75deg);
+  box-shadow: none;
+}
+.mk-action-button[data-mk-action-variant="film"]:is(:hover, :focus-visible):not(:disabled):not([aria-disabled="true"]) .mk-action-button__line { clip-path: inset(100% 0 0); translate: 0 .25em; scale: .95; }
+.mk-action-button[data-mk-action-variant="film"]:is(:hover, :focus-visible):not(:disabled):not([aria-disabled="true"]) .mk-action-button__copy { clip-path: inset(0); translate: 0; scale: 1; transition-delay: 75ms; }
+.mk-action-button[data-mk-action-variant="film"]:active:not(:disabled) { transform: scale(.97); }
+.mk-action-button:focus-visible { outline: 3px solid var(--mk-action-focus, #356bdf); outline-offset: 7px; }
+.mk-action-button:disabled, .mk-action-button[aria-disabled="true"] { opacity: .35; cursor: default; }
+@media (prefers-reduced-motion: reduce) {
+  .mk-action-button, .mk-action-button *, .mk-action-button::before, .mk-action-button::after { transition: none; }
+  .mk-action-button[data-mk-action-variant="film"]:is(:hover, :focus-visible):not(:disabled):not([aria-disabled="true"]) { transform: none; }
+  .mk-action-button[data-mk-action-variant="film"]:is(:hover, :focus-visible):not(:disabled):not([aria-disabled="true"]) .mk-action-button__line { clip-path: none; translate: none; scale: 1; }
+  .mk-action-button__copy { display: none; }
+}

package/src/recipes/action-button/create-action-button.ts

@@ -0,0 +1,56 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export type ActionButtonVariant = 'primary' | 'secondary' | 'icon' | 'stepper' | 'film';
+export interface ActionButtonOptions {
+  variant?: ActionButtonVariant;
+  /** Toggle aria-pressed on activation. Ordinary action buttons leave it unset. */
+  toggle?: boolean;
+  pressed?: boolean;
+  onPressedChange?: (pressed: boolean) => void;
+}
+export interface ActionButtonInstance extends Instance {
+  setPressed(pressed: boolean): void;
+  readonly pressed: boolean;
+}
+
+/** Drawn press buttons and a masked rolling-label film variant. Uses native activation. */
+export function createActionButton(root: HTMLElement | null, options: ActionButtonOptions = {}): ActionButtonInstance {
+  if (!root) return inert({ setPressed() {}, pressed: false });
+  const scope = createScope();
+  const variant = options.variant ?? (root.getAttribute('data-mk-action-variant') as ActionButtonVariant | null) ?? 'primary';
+  scope.attr(root, 'data-mk-action-variant', variant);
+  scope.attr(root, 'data-mk-action-ready', '');
+  const label = root.querySelector<HTMLElement>('[data-mk-action-label]');
+  if (label && variant === 'film') {
+    const nodes = [...label.childNodes];
+    const line = document.createElement('span');
+    line.className = 'mk-action-button__line';
+    line.append(...nodes);
+    const copy = document.createElement('span');
+    copy.className = 'mk-action-button__copy';
+    copy.setAttribute('aria-hidden', 'true');
+    // Plain text prevents duplicate interactive controls or IDs inside the label.
+    copy.textContent = line.textContent;
+    label.append(line, copy);
+    scope.add(() => { label.replaceChildren(...nodes); });
+  }
+  let pressed = options.pressed ?? root.getAttribute('aria-pressed') === 'true';
+  if (options.toggle || options.pressed !== undefined) scope.attr(root, 'aria-pressed', String(pressed));
+  const setPressed = (next: boolean) => {
+    if (scope.disposed || next === pressed) return;
+    pressed = next;
+    scope.attr(root, 'aria-pressed', String(pressed));
+    options.onPressedChange?.(pressed);
+    root.dispatchEvent(new CustomEvent('mk:action-change', { bubbles: true, detail: { pressed } }));
+  };
+  scope.on(root, 'click', (event) => {
+    if (event.defaultPrevented) return;
+    if (root.hasAttribute('disabled') || root.getAttribute('aria-disabled') === 'true') {
+      event.preventDefault();
+      return;
+    }
+    if (options.toggle) setPressed(!pressed);
+  });
+  return { setPressed, get pressed() { return pressed; }, destroy: () => scope.dispose() };
+}

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/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/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; }
+}