@yewdiel21/motion-kit 0.9.0 → 0.10.0

package/src/components/trailer/engine.ts

@@ -0,0 +1,189 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { createDialog } from '../dialog/engine';
+
+export interface TrailerOptions {
+  triggers?: boolean | string;
+  autoplay?: boolean;
+  closeOnBackdrop?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+export interface TrailerInstance extends Instance {
+  open(origin?: HTMLElement | null): void;
+  close(): void;
+  toggle(origin?: HTMLElement | null): void;
+  play(): Promise<boolean>;
+  pause(): void;
+  seek(seconds: number): void;
+  setVolume(volume: number): void;
+  readonly isOpen: boolean;
+}
+const time = (value: number) => {
+  const seconds = Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+  return `${Math.floor(seconds / 60).toString().padStart(2, '0')}:${(seconds % 60).toString().padStart(2, '0')}`;
+};
+
+/** Native modal + consumer-owned video, with optional accessible custom transport controls. */
+export function createTrailer(root: HTMLElement | null, options: TrailerOptions = {}): TrailerInstance {
+  const video = root?.querySelector<HTMLVideoElement>('video');
+  if (!root || !video || root.tagName !== 'DIALOG') return inert({ open() {}, close() {}, toggle() {}, play: async () => false, pause() {}, seek() {}, setVolume() {}, isOpen: false });
+  const scope = createScope();
+  const get = <T extends HTMLElement>(name: string) => root.querySelector<T>(`[data-mk-trailer-${name}]`);
+  const playButton = get<HTMLButtonElement>('play');
+  const muteButton = get<HTMLButtonElement>('mute');
+  const fullButton = get<HTMLButtonElement>('fullscreen');
+  // The Fullscreen API rejects HTMLDialogElement. A consumer can wrap media and
+  // transport in a stage; otherwise fullscreen just the native video element.
+  const fullTarget = get<HTMLElement>('stage') ?? video;
+  const captionsButton = get<HTMLButtonElement>('captions');
+  const seekInput = get<HTMLInputElement>('seek');
+  const volumeInput = get<HTMLInputElement>('volume');
+  const output = get<HTMLElement>('time');
+  const status = get<HTMLElement>('status');
+  const originalText = [output, status].filter((el): el is HTMLElement => !!el).map(el => [el, el.textContent] as const);
+  scope.add(() => originalText.forEach(([el, text]) => { el.textContent = text; }));
+  scope.attr(root, 'data-mk-trailer-ready', '');
+  scope.attr(root, 'data-mk-trailer-state', 'paused');
+  const controls = video.controls;
+  // Keep the browser's controls unless the consumer supplied a complete transport.
+  if (playButton && muteButton && seekInput && (!video.querySelector('track') || captionsButton)) video.controls = false;
+  scope.add(() => { video.controls = controls; });
+  for (const input of [seekInput, volumeInput]) {
+    if (!input) continue;
+    const initialValue = input.value;
+    scope.add(() => { input.value = initialValue; });
+    scope.attr(input, 'min', '0');
+    scope.attr(input, 'max', '1');
+    scope.attr(input, 'step', input === volumeInput ? '.01' : '.1');
+    scope.attr(input, 'aria-label', input.getAttribute('aria-label') ?? (input === volumeInput ? 'Volumen' : 'Posición del video'));
+  }
+  if (status) scope.attr(status, 'role', 'status');
+  const tell = (message: string) => { if (!scope.disposed && status) status.textContent = message; };
+  const sync = () => {
+    if (scope.disposed) return;
+    const duration = Number.isFinite(video.duration) ? Math.max(0, video.duration) : 0;
+    scope.attr(root, 'data-mk-trailer-state', video.ended ? 'ended' : video.paused ? 'paused' : 'playing');
+    if (playButton) {
+      scope.attr(playButton, 'aria-label', video.paused || video.ended ? 'Reproducir' : 'Pausar');
+      scope.attr(playButton, 'aria-pressed', String(!video.paused && !video.ended));
+    }
+    if (muteButton) {
+      scope.attr(muteButton, 'aria-label', video.muted ? 'Activar sonido' : 'Silenciar');
+      scope.attr(muteButton, 'aria-pressed', String(video.muted));
+    }
+    if (seekInput) {
+      scope.attr(seekInput, 'max', String(duration || 1));
+      scope.attr(seekInput, 'disabled', duration ? null : '');
+      scope.attr(seekInput, 'aria-valuetext', `${time(video.currentTime)} de ${time(duration)}`);
+      seekInput.value = String(Number.isFinite(video.currentTime) ? video.currentTime : 0);
+    }
+    if (volumeInput) volumeInput.value = String(video.muted ? 0 : video.volume);
+    if (captionsButton) {
+      scope.attr(captionsButton, 'disabled', video.textTracks.length ? null : '');
+      scope.attr(captionsButton, 'aria-pressed', String(video.textTracks[0]?.mode === 'showing'));
+    }
+    if (output) output.textContent = `${time(video.currentTime)} / ${time(duration)}`;
+  };
+  let playRequest = 0;
+  let wantsPlayback = false;
+  const pause = () => { if (!scope.disposed) { wantsPlayback = false; ++playRequest; video.pause(); sync(); } };
+  const play = async () => {
+    if (scope.disposed) return false;
+    wantsPlayback = true;
+    const request = ++playRequest;
+    try {
+      await video.play();
+      if (scope.disposed || request !== playRequest) {
+        // A stale request must not pause a newer play after a quick close/reopen.
+        if (scope.disposed || !wantsPlayback) video.pause();
+        return false;
+      }
+      tell('');
+      sync();
+      return true;
+    } catch {
+      if (scope.disposed || request !== playRequest) return false;
+      wantsPlayback = false;
+      tell('No se pudo reproducir el video. Revisa la fuente y vuelve a intentarlo.');
+      sync();
+      return false;
+    }
+  };
+  const seek = (seconds: number) => {
+    if (scope.disposed || !Number.isFinite(seconds) || !Number.isFinite(video.duration) || video.duration <= 0) return;
+    video.currentTime = Math.max(0, Math.min(video.duration, seconds));
+    sync();
+  };
+  const setVolume = (volume: number) => {
+    if (scope.disposed || !Number.isFinite(volume)) return;
+    video.volume = Math.max(0, Math.min(1, volume));
+    video.muted = volume <= 0;
+    sync();
+  };
+  const exitFullscreen = () => {
+    if (document.fullscreenElement !== fullTarget) return;
+    void document.exitFullscreen?.().catch(() => {});
+  };
+  const dialog = createDialog(root, {
+    triggers: options.triggers,
+    closeOnBackdrop: options.closeOnBackdrop ?? true,
+    drag: false,
+    autoResize: false,
+    animateContent: false,
+    onOpen: () => { sync(); if (options.autoplay) void play(); options.onOpen?.(); },
+    onClose: () => { ++playRequest; pause(); exitFullscreen(); options.onClose?.(); },
+  });
+  if (playButton) scope.on(playButton, 'click', () => video.paused || video.ended ? void play() : pause());
+  if (muteButton) scope.on(muteButton, 'click', () => { video.muted = !video.muted; sync(); });
+  if (seekInput) scope.on(seekInput, 'input', () => seek(Number(seekInput.value)));
+  if (volumeInput) scope.on(volumeInput, 'input', () => setVolume(Number(volumeInput.value)));
+  if (captionsButton) scope.on(captionsButton, 'click', () => {
+    const track = video.textTracks[0];
+    if (track) track.mode = track.mode === 'showing' ? 'hidden' : 'showing';
+    sync();
+  });
+  const fullscreen = async () => {
+    if (scope.disposed) return;
+    try {
+      if (document.fullscreenElement === fullTarget) await document.exitFullscreen?.();
+      else if (fullTarget.requestFullscreen) {
+        await fullTarget.requestFullscreen();
+        if (scope.disposed || !dialog.isOpen) exitFullscreen();
+      }
+      else tell('La pantalla completa no está disponible en este navegador.');
+    } catch { tell('No se pudo abrir la pantalla completa.'); }
+  };
+  if (fullButton) {
+    scope.attr(fullButton, 'aria-label', 'Pantalla completa');
+    scope.on(fullButton, 'click', () => { void fullscreen(); });
+    scope.on(document, 'fullscreenchange', () => {
+      scope.attr(fullButton, 'aria-label', document.fullscreenElement === fullTarget ? 'Salir de pantalla completa' : 'Pantalla completa');
+    });
+  }
+  for (const event of ['loadedmetadata', 'durationchange', 'timeupdate', 'play', 'pause', 'ended', 'volumechange']) scope.on(video, event, sync);
+  scope.on(video, 'error', () => { tell('El video no está disponible.'); scope.attr(root, 'data-mk-trailer-state', 'error'); });
+  scope.on(root, 'keydown', (event) => {
+    if (!dialog.isOpen || (event.target instanceof Element && event.target.closest('button, input, select, textarea, a, [contenteditable]'))) return;
+    if (event.key === ' ' || event.key.toLowerCase() === 'k') { event.preventDefault(); video.paused ? void play() : pause(); }
+    else if (event.key === 'ArrowRight' || event.key === 'ArrowLeft') { event.preventDefault(); seek(video.currentTime + (event.key === 'ArrowRight' ? 5 : -5)); }
+    else if (event.key.toLowerCase() === 'm') { video.muted = !video.muted; sync(); }
+  });
+  sync();
+  return {
+    open: (origin) => { if (!scope.disposed) dialog.open(origin); },
+    close: () => { if (!scope.disposed) dialog.close(); },
+    toggle: (origin) => { if (!scope.disposed) dialog.toggle(origin); },
+    play, pause, seek, setVolume,
+    get isOpen() { return dialog.isOpen; },
+    destroy() {
+      if (scope.disposed) return;
+      wantsPlayback = false;
+      ++playRequest;
+      video.pause();
+      exitFullscreen();
+      dialog.destroy();
+      scope.dispose();
+    },
+  };
+}

package/src/components/trailer/react.tsx

@@ -0,0 +1,16 @@
+'use client';
+import { useRef, type DialogHTMLAttributes } from 'react';
+import { useRecipe } from '../../react/use-recipe';
+import { createTrailer, type TrailerOptions } from './engine';
+
+export interface TrailerProps extends Omit<DialogHTMLAttributes<HTMLDialogElement>, 'open' | 'onClose'> {
+  options?: TrailerOptions;
+}
+/** Consumer supplies <video>, optional controls and tracks; no remote media is injected. */
+export function Trailer({ options, className, children, ...props }: TrailerProps) {
+  const ref = useRef<HTMLDialogElement>(null);
+  useRecipe(ref, createTrailer, options);
+  return <dialog {...props} ref={ref} className={['mk-trailer', className].filter(Boolean).join(' ')}>{children}</dialog>;
+}
+
+export { useTrailer } from '../../react/use-trailer';

package/src/components/trailer/trailer.css

@@ -0,0 +1,36 @@
+.mk-trailer {
+  --mk-trailer-ink: #f6f3e8;
+  --mk-trailer-paper: #131816;
+  width: min(1100px, calc(100vw - 32px));
+  max-width: none;
+  max-height: calc(100dvh - 32px);
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  color: var(--mk-trailer-ink);
+  background: var(--mk-trailer-paper);
+  overflow: auto;
+  margin: auto;
+}
+.mk-trailer::backdrop { background: rgb(4 10 7 / .8); }
+.mk-trailer__header { display: flex; align-items: center; justify-content: space-between; gap: 20px; padding: 16px 20px; }
+.mk-trailer__title { font: 500 .75rem/1.5 var(--mk-font-mono, monospace); text-transform: uppercase; letter-spacing: .16em; margin: 0; }
+.mk-trailer video { display: block; width: 100%; aspect-ratio: 16 / 9; object-fit: contain; background: #060b08; }
+.mk-trailer [data-mk-trailer-stage]:fullscreen { display: flex; flex-direction: column; justify-content: center; width: 100%; height: 100%; background: var(--mk-trailer-paper); color: var(--mk-trailer-ink); }
+.mk-trailer [data-mk-trailer-stage]:fullscreen video { max-height: calc(100dvh - 90px); }
+.mk-trailer__controls { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; padding: 10px 20px 16px; font: .7rem/1.5 var(--mk-font-mono, monospace); }
+.mk-trailer button { display: grid; place-items: center; min-width: 44px; min-height: 44px; border: 1px solid currentColor; color: inherit; background: transparent; cursor: pointer; font: inherit; }
+.mk-trailer button:hover { background: rgb(255 255 255 / .12); }
+.mk-trailer button:focus-visible, .mk-trailer input:focus-visible { outline: 2px solid #e5ff96; outline-offset: 4px; }
+.mk-trailer button svg { width: 18px; height: 18px; fill: currentColor; }
+.mk-trailer [data-mk-trailer-seek] { flex: 1; min-width: 70px; accent-color: #d6f2ac; }
+.mk-trailer [data-mk-trailer-volume] { width: 72px; accent-color: #d6f2ac; }
+.mk-trailer [data-mk-trailer-time] { white-space: nowrap; }
+.mk-trailer [data-mk-trailer-status] { padding: 0 20px; font: .8rem/1.5 var(--mk-font, sans-serif); }
+.mk-trailer [data-mk-trailer-status]:empty { display: none; }
+.mk-trailer__pause-icon, .mk-trailer__sound-off { display: none; }
+.mk-trailer [data-mk-trailer-play][aria-pressed="true"] .mk-trailer__play-icon,
+.mk-trailer [data-mk-trailer-mute][aria-pressed="true"] .mk-trailer__sound-on { display: none; }
+.mk-trailer [data-mk-trailer-play][aria-pressed="true"] .mk-trailer__pause-icon,
+.mk-trailer [data-mk-trailer-mute][aria-pressed="true"] .mk-trailer__sound-off { display: block; }
+@media (max-width: 540px) { .mk-trailer [data-mk-trailer-volume] { display: none; } .mk-trailer__controls { gap: 8px; padding-inline: 12px; } .mk-trailer [data-mk-trailer-seek] { flex-basis: 100%; order: -1; } }

package/src/core/channels.ts

@@ -1,7 +1,7 @@
 import { gsap } from 'gsap';
 
 /**
- * Stepbro's per-property motion channels (ported from Kayro's spring-channels):
+ * per-property motion channels:
  * each value moves toward its target either on a spring (stiffness, damping, an
  * initial kick) or on an eased duration, all stepped on GSAP's ticker. Used by
  * surfaces that grow out of a control (liquid dialog, toasts) and floating windows.
@@ -25,7 +25,7 @@ export const easeOut = (t: number) => 1 - (1 - t) * (1 - t);
 export const easeOutCubic = (t: number) => 1 - (1 - t) ** 3;
 export const easeInCubic = (t: number) => t * t * t;
 
-/** A cubic-bezier as a function of progress (Stepbro's `cr.bezier`). */
+/** A cubic-bezier as a function of progress. */
 export function bezier(x1: number, y1: number, x2: number, y2: number) {
   const at = (t: number, a: number, b: number) => {
     const u = 1 - t;
@@ -154,7 +154,7 @@ export function channels<K extends string>(start: Record<K, number>, onChange: (
   };
 }
 
-/** A damped spring as an ease function of progress (Stepbro's `Vw`). */
+/** A damped spring as an ease function of progress. */
 export function springEase(ratio: number, velocity = 0) {
   const damping = Math.min(Math.max(ratio, 0.05), 0.999);
   const stiffness = 5.6;

package/src/core/curves.ts

@@ -1,4 +1,4 @@
-/** Stepbro's curve paths (CustomEase SVG syntax). */
+/** curve paths (CustomEase SVG syntax). */
 export const PATHS = {
   /** The signature: a strong deceleration that is not a plain ease-out. */
   signature: 'M0,0 C0.308,0.19 0.107,0.633 0.288,0.866 0.382,0.987 0.656,1 1,1',
@@ -9,7 +9,7 @@ export const PATHS = {
 } as const;
 
 /**
- * A damped spring sampled as an ease path (Stepbro's `FA`): `ratio` below 1
+ * A damped spring sampled as an ease path: `ratio` below 1
  * overshoots and settles, `velocity` is the starting speed.
  */
 export function springPath(ratio: number, velocity = 0, steps = 72): string {
@@ -28,7 +28,7 @@ export function springPath(ratio: number, velocity = 0, steps = 72): string {
 }
 
 /**
- * Stepbro's own linear() sampling of the signature curve (its backdrop tint),
+ * own linear() sampling of the signature curve (its backdrop tint),
  * for CSS and the Web Animations API.
  */
 export const SIGNATURE_LINEAR =

package/src/core/dates.ts

@@ -0,0 +1,98 @@
+/*
+ * Calendar date helpers on local dates (no time zone maths): the calendar and
+ * slot-picker components share them. Days are compared by their YYYY-MM-DD key.
+ */
+
+export type DateInput = Date | string | number;
+
+/** Local midnight of a date; "2026-10-23" is read as a local day, not UTC. */
+export function toDate(input: DateInput | null | undefined, fallback = new Date()): Date {
+  if (input instanceof Date) return Number.isNaN(input.getTime()) ? startOfDay(fallback) : startOfDay(input);
+  if (typeof input === 'string') {
+    const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input.trim());
+    if (day) return new Date(Number(day[1]), Number(day[2]) - 1, Number(day[3]));
+  }
+  if (typeof input === 'string' || typeof input === 'number') {
+    const parsed = new Date(input);
+    if (!Number.isNaN(parsed.getTime())) return startOfDay(parsed);
+  }
+  return startOfDay(fallback);
+}
+
+/** A full date-time (events keep their hour). */
+export function toDateTime(input: DateInput): Date | null {
+  if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : input;
+  if (typeof input === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(input.trim())) return toDate(input);
+  const parsed = new Date(input);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+export const startOfDay = (date: Date) => new Date(date.getFullYear(), date.getMonth(), date.getDate());
+
+export const addDays = (date: Date, days: number) => new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
+
+/** Same day number in another month, clamped to that month's length (Jan 31 + 1 → Feb 28/29). */
+export function addMonths(date: Date, months: number): Date {
+  const target = new Date(date.getFullYear(), date.getMonth() + months, 1);
+  const last = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+  return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), last));
+}
+
+export const startOfMonth = (date: Date) => new Date(date.getFullYear(), date.getMonth(), 1);
+
+export function startOfWeek(date: Date, firstDay = 0): Date {
+  const shift = (date.getDay() - firstDay + 7) % 7;
+  return addDays(startOfDay(date), -shift);
+}
+
+export const sameDay = (a: Date | null | undefined, b: Date | null | undefined) =>
+  !!a && !!b && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+
+export const sameMonth = (a: Date, b: Date) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/** YYYY-MM-DD of the local day. */
+export const dayKey = (date: Date) => `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+
+/** The weeks shown for a month: from the week of the 1st to the week of the last day (4–6 rows). */
+export function monthWeeks(date: Date, firstDay = 0): Date[][] {
+  const first = startOfMonth(date);
+  const last = new Date(date.getFullYear(), date.getMonth() + 1, 0);
+  const weeks: Date[][] = [];
+  for (let start = startOfWeek(first, firstDay); start <= last; start = addDays(start, 7)) {
+    weeks.push(Array.from({ length: 7 }, (_, i) => addDays(start, i)));
+  }
+  return weeks;
+}
+
+export const weekDays = (date: Date, firstDay = 0) => Array.from({ length: 7 }, (_, i) => addDays(startOfWeek(date, firstDay), i));
+
+/** Weekday names in display order, e.g. ["dom", "lun", …] for es with firstDay 0. */
+export function weekdayNames(locale: string, firstDay = 0, width: 'long' | 'short' | 'narrow' = 'short'): string[] {
+  const format = safeFormat(locale, { weekday: width });
+  // 2024-09-01 was a Sunday.
+  return Array.from({ length: 7 }, (_, i) => format.format(new Date(2024, 8, 1 + ((firstDay + i) % 7))));
+}
+
+export function safeFormat(locale: string | undefined, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  try {
+    return new Intl.DateTimeFormat(locale, options);
+  } catch {
+    return new Intl.DateTimeFormat(undefined, options);
+  }
+}
+
+export const capitalize = (text: string) => text.charAt(0).toLocaleUpperCase() + text.slice(1);
+
+/** Options given as JSON text (data-mk-* attributes through autoInit) become values. */
+export function fromJson<T>(value: T | string | undefined): T | undefined {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+export const clampFirstDay =(n: unknown) => (Number.isInteger(n) && (n as number) >= 0 && (n as number) <= 6 ? (n as number) : 0);

package/src/core/gsap.ts

@@ -5,10 +5,10 @@ import { CustomEase } from 'gsap/CustomEase';
 import { Flip } from 'gsap/Flip';
 import { PATHS, springPath } from './curves';
 
-/** Spencer's elastic overshoot; close to the `--mk-ease-elastic` CSS curve. */
+/** elastic overshoot; close to the `--mk-ease-elastic` CSS curve. */
 export const ELASTIC = 'elastic.out(1, 0.45)';
 
-/** Custom eases registered by `registerMotion()` (Stepbro curves). Use the names as GSAP `ease` values. */
+/** Custom eases registered by `registerMotion()`. Use the names as GSAP `ease` values. */
 export const EASE = {
   signature: 'mk-signature',
   flow: 'mk-flow',

package/src/core/loop.ts

@@ -12,7 +12,7 @@ function tick(_time: number, deltaMs: number) {
   subscribers.forEach((fn) => fn(dt));
 }
 
-/** One shared ticker callback for every recipe (spencergabor.com's single rAF loop). */
+/** One shared ticker callback for every recipe. */
 export function subscribe(fn: Tick): () => void {
   if (!subscribers.size) gsap.ticker.add(tick);
   subscribers.add(fn);

package/src/core/math.ts

@@ -1,6 +1,6 @@
 export const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v));
 export const lerp = (a: number, b: number, t: number) => (1 - t) * a + t * b;
-/** Spencer's frame-rate independent smoothing: lerp by 1 - e^(-lambda·dt). */
+/** frame-rate independent smoothing: lerp by 1 - e^(-lambda·dt). */
 export const damp = (a: number, b: number, lambda: number, dt: number) => lerp(a, b, 1 - Math.exp(-lambda * dt));
 export const wrap = (v: number, length: number) => ((v % length) + length) % length;
 export function mapRange(v: number, inMin: number, inMax: number, outMin: number, outMax: number, clamped = false) {

package/src/core/physics-spring.ts

@@ -1,8 +1,8 @@
 /*
  * Motion/Framer's physical spring — stiffness, damping and mass, released from
- * rest at 0 toward 1 — the way Dousan declares its motion (400/10, 260/18…).
+ * rest at 0 toward 1, with parameter pairs such as (400/10, 260/18…).
  * motionSpring() gives a GSAP ease plus the time it takes to settle;
- * springLinear() samples it as a CSS linear(). Stepbro's own springs (FA)
+ * springLinear() samples it as a CSS linear(). Ratio-based springs
  * stay in springPath / springEase.
  */
 

package/src/core/scroll-track.ts

@@ -3,10 +3,8 @@ import { whileVisible } from './loop';
 /*
  * How far an element has travelled through the viewport, 0 → 1, between two
  * ScrollTrigger-style positions ("<element edge> <viewport line>"), read from
- * its box every frame while it is near the screen. Siena's trackers read a
- * smooth-scrolled position (Lenis, .1 a frame); on a page that scrolls natively
- * the effects follow it exactly (lerp 1), so a picture never drifts behind its
- * frame — pass lerp .1 to smooth the effect alone. Parallax, depth grid and
+ * its box every frame while it is near the screen. Native scroll is followed
+ * exactly with lerp 1; pass lerp .1 to smooth the effect alone. Parallax, depth grid and
  * frame zoom render from it.
  */
 

package/src/core/spring.ts

@@ -6,7 +6,7 @@ export interface Spring {
   update(dt?: number): void;
 }
 
-/** Spencer Gabor's spring (stiffness .05, friction .8), normalised so dt = 1 is one 60 Hz frame. */
+/** spring (stiffness .05, friction .8), normalised so dt = 1 is one 60 Hz frame. */
 export function createSpring(stiffness = 0.05, friction = 0.8): Spring {
   const current = { x: 0, y: 0 };
   const target = { x: 0, y: 0 };

package/src/core/timing.ts

@@ -1,8 +1,7 @@
 /**
- * Every Stepbro duration in one place (seconds, like GSAP, unless the name says
+ * Every duration in one place (seconds, like GSAP, unless the name says
  * ms). Recipes and components take their defaults from here, so a timing is
- * changed once. Sources: Stepbro replication kit, tasks/especificacion-replicacion.json
- * and money/replication-catalog.json.
+ * changed once.
  */
 export const TIMING = Object.freeze({
   flow: 0.5,
@@ -104,9 +103,9 @@ export const TIMING = Object.freeze({
     charsDelay: 0.225,
     charsStagger: 0.02,
   }),
-  /** Dousan's glass (CSS): surface/shadow transitions, ring and shine. */
+  /** glass (CSS): surface/shadow transitions, ring and shine. */
   glass: Object.freeze({ hover: 0.4, ring: 0.5 }),
-  /** Stepbro's utility animations (css/effects/anim.css), by name. */
+  /** utility animations (css/effects/anim.css), by name. */
   effects: Object.freeze({
     out: 0.5,
     'out-left': 0.5,
@@ -119,7 +118,7 @@ export const TIMING = Object.freeze({
     wipe: 0.7,
     'progress-in': 1,
   }),
-  /** Dousan's success confetti, per 60 fps frame. */
+  /** success confetti, per 60 fps frame. */
   confetti: Object.freeze({
     count: 45,
     speed: [2, 8] as const,
@@ -130,9 +129,9 @@ export const TIMING = Object.freeze({
     drag: 0.98,
     spin: 2.5,
   }),
-  /** Dousan's project sheet. */
+  /** project sheet. */
   sheet: Object.freeze({ open: 0.72, close: 0.72, underlayScale: 0.98, underlayOpacity: 0.4 }),
-  /** Dousan's springs as Motion declares them: [stiffness, damping]. */
+  /** Physical spring pairs: [stiffness, damping]. */
   springs: Object.freeze({
     press: [400, 10] as const,
     success: [260, 18] as const,
@@ -144,13 +143,13 @@ export const TIMING = Object.freeze({
     bentoRepel: [300, 25] as const,
     dockPill: [380, 30] as const,
   }),
-  /** OFFFICE's masked type (Siena's case titles start at 120 %). */
+  /** masked type. */
   maskText: Object.freeze({ duration: 1.2, delay: 0.1, stagger: 0.02, exitStagger: 0.002, y: 100, threshold: 0.8 }),
-  /** Siena's reveal group (rules, fades, rises). */
+  /** reveal group (rules, fades, rises). */
   cascade: Object.freeze({ duration: 1.2, step: 0.03, rise: 200, threshold: 0.3 }),
-  /** Siena's slot title: each letter turns 8–14 times inside a 2 s expo.out envelope. */
+  /** slot title: each letter turns 8–14 times inside a 2 s expo.out envelope. */
   textRoll: Object.freeze({ duration: 2, stagger: 0.04, turns: [8, 14] as const, interval: 6000, quietMs: 1000 }),
-  /** Dousan's hero letters: scale on hover, pastel blink. */
+  /** hero letters: scale on hover, pastel blink. */
   letters: Object.freeze({
     scale: 1.3,
     y: -5,
@@ -160,9 +159,9 @@ export const TIMING = Object.freeze({
     blinkRepeatDelay: 0.1,
     blinkDelays: [0.1, 0.6, 0.2, 1, 0.4, 1.2, 0.15, 0.8, 0.3] as const,
   }),
-  /** Siena's image parallax. */
+  /** image parallax. */
   parallax: Object.freeze({ travel: 10, scale: 1.2, strongScale: 1.3, lerp: 1 }),
-  /** Siena's About grid gathering from depth. */
+  /** About grid gathering from depth. */
   depthGrid: Object.freeze({
     perspective: 600,
     distance: 900,
@@ -173,7 +172,7 @@ export const TIMING = Object.freeze({
     stagger: 0.15,
     lerp: 1,
   }),
-  /** Siena's video mask: the frame and the picture inside scale in opposite directions. */
+  /** video mask: the frame and the picture inside scale in opposite directions. */
   frameZoom: Object.freeze({
     outer: [80, 20] as const,
     inner: [130, 20] as const,
@@ -182,19 +181,19 @@ export const TIMING = Object.freeze({
     open: 1,
     lerp: 1,
   }),
-  /** Siena's marquee: seconds per item, at most 14 counted. */
+  /** marquee: seconds per item, at most 14 counted. */
   marquee: Object.freeze({ perItem: 2, maxItems: 14 }),
-  /** Dousan's glass chip and Siena's dot cursor. */
+  /** glass chip and dot cursor. */
   cursor: Object.freeze({ gutter: 10, circle: 96, dotLerp: 0.2, light: 180 }),
-  /** iyo.ai's floating navbar: enters from −300 % over 1.8 s; rows follow 0.15 s + 0.025 s each. */
+  /** floating navbar: enters from −300 % over 1.8 s; rows follow 0.15 s + 0.025 s each. */
   island: Object.freeze({ entrance: 1.8, offset: -300, delay: 0.15, step: 0.025, focus: 150 }),
-  /** iyo.ai's product dock: spread for 1.6 s on load; tablet range re-checked 250 ms after a resize. */
+  /** product dock: spread for 1.6 s on load; tablet range re-checked 250 ms after a resize. */
   cardDock: Object.freeze({ intro: 1600, resizeDebounce: 250 }),
-  /** iyo.ai's phone cards: 5 s a card, 2 s wait after a touch, 0.5 s after it shows. */
+  /** phone cards: 5 s a card, 2 s wait after a touch, 0.5 s after it shows. */
   snapStrip: Object.freeze({ interval: 5000, resume: 2000, delay: 500 }),
-  /** iyo.ai's fill-text: letters from .2, 0.5 s each, 0.1 s apart, top 90 % → centre 40 %. */
+  /** fill-text: letters from .2, 0.5 s each, 0.1 s apart, top 90 % → centre 40 %. */
   fillText: Object.freeze({ from: 0.2, duration: 0.5, stagger: 0.1, start: 'top 90%', end: 'center 40%' }),
-  /** iyo.ai's particle hero (adapted): fade in 1 s after 0.3 s, morph cycles, pointer push. */
+  /** particle hero: fade in 1 s after 0.3 s, morph cycles, pointer push. */
   particleHero: Object.freeze({ fadeIn: 1, fadeDelay: 0.3, size: 128, pointSize: 1.7, maxDpr: 1.5, stillSteps: 110 }),
   ticketMenu: Object.freeze({ open: 0.9, content: 1.1, stagger: 0.02, from: 150 }),
   infiniteReel: Object.freeze({ friction: 0.95, wheel: 0.05, dragThreshold: 5 }),