@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/components/chat-background/element.ts

@@ -0,0 +1,31 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createChatBackground, type ChatBackgroundInstance } from './engine';
+
+/** <mk-chat-background energy="0" scale="1"></mk-chat-background> inside any positioned container. */
+export class MkChatBackgroundElement extends MkElement<ChatBackgroundInstance> {
+  static options: Record<string, OptionType> = {};
+  static get observedAttributes() {
+    return ['energy', 'scale'];
+  }
+
+  protected create() {
+    return createChatBackground(this, { energy: Number(this.getAttribute('energy')) || 0, scale: Number(this.getAttribute('scale')) || 1 });
+  }
+
+  // Energy changes every frame while recording: update the engine instead of rebuilding it.
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'energy') this.instance.setEnergy(Number(next) || 0);
+    if (name === 'scale') this.instance.setScale(Number(next) || 1);
+  }
+
+  setEnergy(energy: number) {
+    this.instance?.setEnergy(energy);
+  }
+
+  busy(on: boolean) {
+    this.instance?.busy(on);
+  }
+}
+
+export const defineChatBackground = () => defineElement('mk-chat-background', MkChatBackgroundElement);

package/src/components/chat-background/engine.ts

@@ -0,0 +1,108 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * Stepbro's PrettyBackground: two soft blobs (primary-container and
+ * tertiary-container, 800 px radial gradients, saturate 150 %) orbit behind the
+ * chat and a grain sits on top. Energy (0…1, e.g. the microphone's) speeds the
+ * orbits up (10 − 3.5·e s and 15 − 4.5·e s), brightens the blobs (.5 + .15·e) and
+ * scales them ((1 + .1·e)·scale). Onboarding's "busy" state pushes it to energy
+ * 1.6 and scale 1.8 in 0.8 s (power2.out) and back in 0.6 s (power2.inOut).
+ */
+
+export interface ChatBackgroundOptions {
+  energy?: number;
+  scale?: number;
+}
+
+export interface ChatBackgroundInstance extends Instance {
+  setEnergy(energy: number): void;
+  setScale(scale: number): void;
+  /** Onboarding's busy state: energy 1.6 / scale 1.8, or back to rest. */
+  busy(on: boolean): void;
+  readonly energy: number;
+  readonly scale: number;
+}
+
+const VARS = ['--mk-chat-orbit-1', '--mk-chat-orbit-2', '--mk-chat-blob-opacity', '--mk-chat-scale'];
+const instances = new WeakMap<Element, ChatBackgroundInstance>();
+
+/** The background instance running on `el` (steps and chat use it to drive the energy). */
+export const chatBackgroundOf = (el: Element | null | undefined) => (el ? (instances.get(el) ?? null) : null);
+
+export function createChatBackground(root: HTMLElement | null, options: ChatBackgroundOptions = {}): ChatBackgroundInstance {
+  if (!root) {
+    warnOnce('chat-background: missing root');
+    return inert({ setEnergy() {}, setScale() {}, busy() {}, energy: 0, scale: 1 });
+  }
+  registerMotion();
+  const scope = createScope();
+  const state = { energy: options.energy ?? 0, scale: options.scale ?? 1 };
+  let noise = root.querySelector<HTMLElement>(':scope > .mk-chat-background__noise');
+  if (!noise) {
+    noise = document.createElement('div');
+    noise.className = 'mk-chat-background__noise';
+    noise.setAttribute('aria-hidden', 'true');
+    root.append(noise);
+    const created = noise;
+    scope.add(() => created.remove());
+  }
+  scope.attr(root, 'aria-hidden', 'true');
+
+  const paint = () => {
+    const e = Math.max(0, state.energy);
+    root.style.setProperty('--mk-chat-orbit-1', `${Math.max(1, 10 - 3.5 * e).toFixed(3)}s`);
+    root.style.setProperty('--mk-chat-orbit-2', `${Math.max(1, 15 - 4.5 * e).toFixed(3)}s`);
+    root.style.setProperty('--mk-chat-blob-opacity', (0.5 + 0.15 * e).toFixed(3));
+    root.style.setProperty('--mk-chat-scale', ((1 + 0.1 * e) * state.scale).toFixed(3));
+  };
+  scope.add(() => {
+    gsap.killTweensOf(state);
+    for (const name of VARS) root.style.removeProperty(name);
+    if (root.getAttribute('style') === '') root.removeAttribute('style');
+  });
+  paint();
+
+  const instance: ChatBackgroundInstance = {
+    setEnergy(energy: number) {
+      state.energy = Number.isFinite(energy) ? energy : 0;
+      paint();
+    },
+    setScale(scale: number) {
+      state.scale = Number.isFinite(scale) ? scale : 1;
+      paint();
+    },
+    busy(on: boolean) {
+      const to = on ? { energy: 1.6, scale: 1.8 } : { energy: 0, scale: 1 };
+      gsap.killTweensOf(state);
+      if (reduced()) {
+        Object.assign(state, to);
+        paint();
+        return;
+      }
+      gsap.to(state, {
+        ...to,
+        duration: on ? TIMING.onboarding.busy : TIMING.onboarding.idle,
+        ease: on ? 'power2.out' : 'power2.inOut',
+        onUpdate: paint,
+      });
+    },
+    get energy() {
+      return state.energy;
+    },
+    get scale() {
+      return state.scale;
+    },
+    destroy() {
+      instances.delete(root);
+      scope.dispose();
+      delete root.dataset.mkReady;
+    },
+  };
+  instances.set(root, instance);
+  root.dataset.mkReady = '';
+  return instance;
+}

package/src/components/chat-background/react.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { useRef, type CSSProperties } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createChatBackground, type ChatBackgroundInstance } from './engine';
+
+export interface ChatBackgroundProps {
+  /** 0…1 (the microphone's, see audioEnergy); onboarding's busy state goes to 1.6. */
+  energy?: number;
+  scale?: number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/** Stepbro's chat background. Put it first inside a positioned container. */
+export function ChatBackground({ energy = 0, scale = 1, className, style }: ChatBackgroundProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<ChatBackgroundInstance | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createChatBackground(ref.current, { energy, scale });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // Created once; energy and scale are pushed below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setEnergy(energy);
+  }, [energy]);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setScale(scale);
+  }, [scale]);
+  return <div ref={ref} className={['mk-chat-background', className].filter(Boolean).join(' ')} style={style} />;
+}

package/src/components/cursor/README.md

@@ -0,0 +1,53 @@
+# cursor
+
+Dos cursores:
+
+- **`chip`** (Dousan Miao, por defecto): el cursor del sistema se queda. Sobre un elemento con `data-mk-cursor="Texto"` aparece un chip de cristal (`.mk-glass`) con el texto que sigue al puntero con un resorte (Motion 800/35) y entra desde `scale .8` (500/30). `data-mk-cursor-shape="circle"` lo convierte en un círculo de 96 px. Se queda a 10 px de los bordes de la ventana. El texto es del color acento sobre fondos claros y blanco sobre oscuros (luminancia `(299R + 587G + 114B) / 1000 > 180`, como Dousan).
+- **`dot`** (Siena Film Foundation): dentro de su zona un círculo sustituye al cursor y lo sigue (20 % de la distancia por frame) con una palabra (`text` o el `data-mk-cursor` de lo que hay debajo). Al presionar encoge a .7, la palabra cae y entran dos flechas (0.2–0.5 s, `easeOutQuint`). `data-mk-cursor-hide` lo oculta sobre enlaces o botones.
+
+Los dos se apagan en pantallas táctiles y con movimiento reducido.
+
+Origen: dousanmiao.com (cursor `kd`), siena.film (`[data-cursor]`, lerp .2).
+
+## HTML / Astro
+
+```html
+<!-- chip: una vez por página -->
+<mk-cursor></mk-cursor>
+<a href="/p/1" data-mk-cursor="View project" data-mk-cursor-shape="circle">…</a>
+<button data-mk-cursor="Copiar" data-mk-cursor-icon="content_copy">…</button>
+
+<!-- dot: dentro de su zona -->
+<section class="reel">
+  <mk-cursor variant="dot" text="Scroll" arrows="y"></mk-cursor>
+  <a href="/films/savoy" data-mk-cursor-hide>Savoy</a>
+</section>
+```
+
+Sin custom element: `createCursor(capa, { variant, zone, text, arrows })` sobre un `div` vacío.
+
+## React
+
+```tsx
+<Cursor />                                   // en el layout
+<section><Cursor variant="dot" text="Drag" arrows="x" /></section>
+```
+
+## API
+
+`createCursor(host, opciones)` → `{ visible, label, position, tone, update(), destroy }`.
+
+| Opción | Por defecto | |
+|---|---|---|
+| `variant` | `'chip'` | `'dot'` |
+| `zone` | chip: el documento; dot: el padre | dónde funciona |
+| `text` | — | dot: la palabra por defecto |
+| `arrows` | `'y'` | dot: `'x'`, `'none'` |
+
+## Variables CSS
+
+`--mk-cursor-light-ink` (texto del chip sobre claro; por defecto `primary`), `--mk-cursor-circle` (96px), `--mk-cursor-size` (88px), `--mk-cursor-fill`, `--mk-cursor-ink`.
+
+## Accesibilidad
+
+La capa es decorativa (`aria-hidden`, sin puntero); el texto del chip repite lo que el enlace ya dice, así que el enlace necesita su propio nombre accesible. El `dot` oculta el cursor del sistema solo en su zona.

package/src/components/cursor/cursor.css

@@ -0,0 +1,177 @@
+/* cursor — Dousan's glass chip and Siena's dot. The layer follows the pointer; the engine writes its transform. */
+.mk-cursor {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 2147483000;
+  pointer-events: none;
+  will-change: transform;
+}
+
+/* chip (Dousan): a .mk-glass label; ink follows the background under it. */
+.mk-cursor__chip {
+  --mk-glass-fg: #fff;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 16px;
+  font-family: var(--mk-font);
+  font-size: 0.875rem;
+  font-weight: 500;
+  line-height: 1;
+  white-space: nowrap;
+  transition: color 0.15s;
+}
+
+.mk-cursor__chip[data-mk-tone='light'] {
+  --mk-glass-fg: var(--mk-cursor-light-ink, var(--md-sys-color-primary));
+}
+
+.mk-cursor__chip--circle {
+  flex-direction: column;
+  justify-content: center;
+  width: var(--mk-cursor-circle, 96px);
+  height: var(--mk-cursor-circle, 96px);
+  padding: 8px;
+  line-height: 1.15;
+  text-align: center;
+  white-space: normal;
+}
+
+.mk-cursor__icon {
+  font-size: 0.875rem;
+}
+
+.mk-cursor__icon:empty {
+  display: none;
+}
+
+/* dot (Siena): a disc with a word and two arrows that slide in when pressed. */
+.mk-cursor--dot {
+  --mk-cursor-size: 88px;
+  transition: opacity 0.15s var(--mk-ease-quint);
+}
+
+.mk-cursor__dot {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  width: var(--mk-cursor-size);
+  height: var(--mk-cursor-size);
+  color: var(--mk-cursor-ink, var(--md-sys-color-background));
+}
+
+.mk-cursor--dot[data-mk-arrows='x'] .mk-cursor__dot {
+  flex-direction: row;
+}
+
+.mk-cursor__circle {
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  background: var(--mk-cursor-fill, var(--md-sys-color-on-background));
+  transition: transform 0.5s var(--mk-ease-quint);
+}
+
+.mk-cursor__text {
+  position: relative;
+  overflow: hidden;
+  font-family: var(--mk-font);
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 0.9;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.mk-cursor__word {
+  display: block;
+  transition: transform 0.5s var(--mk-ease-quint);
+}
+
+.mk-cursor__arrow {
+  position: relative;
+  display: grid;
+  overflow: hidden;
+}
+
+.mk-cursor__arrow > svg {
+  transition: transform 0.3s var(--mk-ease-quint);
+}
+
+.mk-cursor__arrow--start > svg {
+  transform: translateY(130%);
+}
+
+.mk-cursor__arrow--end > svg {
+  transform: translateY(-130%) rotate(180deg);
+}
+
+.mk-cursor--dot[data-mk-arrows='x'] .mk-cursor__arrow--start > svg {
+  transform: translateX(130%) rotate(-90deg);
+}
+
+.mk-cursor--dot[data-mk-arrows='x'] .mk-cursor__arrow--end > svg {
+  transform: translateX(-130%) rotate(90deg);
+}
+
+.mk-cursor[data-mk-pressed] .mk-cursor__circle {
+  transform: scale(0.7);
+}
+
+.mk-cursor[data-mk-pressed] .mk-cursor__word {
+  transform: translateY(150%);
+  transition-duration: 0.2s;
+}
+
+.mk-cursor[data-mk-pressed] .mk-cursor__arrow > svg {
+  transition-delay: 0.1s;
+}
+
+.mk-cursor[data-mk-pressed] .mk-cursor__arrow--start > svg {
+  transform: translateY(0);
+}
+
+.mk-cursor[data-mk-pressed] .mk-cursor__arrow--end > svg {
+  transform: translateY(0) rotate(180deg);
+}
+
+.mk-cursor--dot[data-mk-arrows='x'][data-mk-pressed] .mk-cursor__arrow--start > svg {
+  transform: translateX(0) rotate(-90deg);
+}
+
+.mk-cursor--dot[data-mk-arrows='x'][data-mk-pressed] .mk-cursor__arrow--end > svg {
+  transform: translateX(0) rotate(90deg);
+}
+
+.mk-cursor--dot[data-mk-hidden] {
+  opacity: 0;
+}
+
+.mk-cursor--dot[data-mk-hidden] .mk-cursor__circle {
+  transform: scale(0);
+}
+
+/* The dot replaces the system cursor inside its zone. */
+[data-mk-cursor-zone],
+[data-mk-cursor-zone] * {
+  cursor: none;
+}
+
+mk-cursor {
+  display: block;
+}
+
+@media (pointer: coarse), (prefers-reduced-motion: reduce) {
+  .mk-cursor {
+    display: none;
+  }
+
+  [data-mk-cursor-zone],
+  [data-mk-cursor-zone] * {
+    cursor: auto;
+  }
+}

package/src/components/cursor/element.ts

@@ -0,0 +1,23 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createCursor, type CursorInstance, type CursorOptions, type CursorVariant } from './engine';
+
+/**
+ * <mk-cursor></mk-cursor>                                   Dousan's glass chip (once per page)
+ * <mk-cursor variant="dot" text="Scroll" arrows="y"></mk-cursor>  Siena's dot, inside its parent
+ * zone="#hero" picks another zone.
+ */
+export class MkCursorElement extends MkElement<CursorInstance> {
+  static options: Record<string, OptionType> = { variant: 'string', text: 'string', arrows: 'string', zone: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    const zone = typeof options.zone === 'string' ? document.querySelector(options.zone) : undefined;
+    return createCursor(this, {
+      variant: options.variant as CursorVariant | undefined,
+      text: options.text as string | undefined,
+      arrows: options.arrows as CursorOptions['arrows'],
+      zone,
+    });
+  }
+}
+
+export const defineCursor = () => defineElement('mk-cursor', MkCursorElement);

package/src/components/cursor/engine.ts

@@ -0,0 +1,254 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { subscribe } from '../../core/loop';
+import { motionSpring } from '../../core/physics-spring';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { ICON_PATHS } from '../icons';
+
+/*
+ * Two cursors.
+ * chip (Dousan): the system cursor stays; over [data-mk-cursor="Label"] a glass
+ * chip with the label follows the pointer on a Motion 800/35 spring, popping in
+ * from scale .8 (500/30); data-mk-cursor-shape="circle" makes it a 96 px disc;
+ * it stays 10 px inside the window; its ink is the accent on light backgrounds
+ * and white on dark ones (Dousan's luminance test).
+ * dot (Siena): inside its zone a disc replaces the cursor and eases after it
+ * (lerp .2 a frame) with a word (data-mk-cursor or `text`); pressing shrinks it
+ * to .7, drops the word and slides two arrows in; [data-mk-cursor-hide] hides it.
+ * Off on touch screens and with reduced motion.
+ */
+
+export type CursorVariant = 'chip' | 'dot';
+
+export interface CursorOptions {
+  variant?: CursorVariant;
+  /** Where it works. chip: the document; dot: the host's parent. */
+  zone?: Element | null;
+  /** dot: the word when nothing under the pointer gives one. */
+  text?: string;
+  /** dot: arrows shown while pressed. */
+  arrows?: 'x' | 'y' | 'none';
+}
+
+export interface CursorInstance extends Instance {
+  readonly visible: boolean;
+  readonly label: string;
+  readonly position: { x: number; y: number };
+  readonly tone: 'light' | 'dark';
+  /** One frame (dt = 1 at 60 Hz); the shared ticker calls it. */
+  update(dt?: number): void;
+}
+
+const svg = (extra = '') =>
+  `<svg aria-hidden="true" width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"${extra}><path d="${ICON_PATHS.send}"/></svg>`;
+
+/** Dousan: the first background with alpha > .1 up the tree; light when (299R + 587G + 114B) / 1000 > 180. */
+function backgroundTone(el: Element | null): 'light' | 'dark' {
+  if (!el) return 'light';
+  if (el.closest('img, video, picture, canvas')) return 'dark';
+  for (let node: Element | null = el; node; node = node.parentElement) {
+    const match = getComputedStyle(node).backgroundColor.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+    if (!match) continue;
+    const alpha = match[4] === undefined ? 1 : parseFloat(match[4]);
+    if (alpha <= 0.1) continue;
+    const luminance = (Number(match[1]) * 299 + Number(match[2]) * 587 + Number(match[3]) * 114) / 1000;
+    return luminance > TIMING.cursor.light ? 'light' : 'dark';
+  }
+  return 'light';
+}
+
+export function createCursor(host: HTMLElement | null, options: CursorOptions = {}): CursorInstance {
+  const variant = options.variant ?? 'chip';
+  const idle = inert<CursorInstance>({ visible: false, label: '', position: { x: 0, y: 0 }, tone: 'light', update() {} });
+  if (!host) {
+    warnOnce('cursor: missing element');
+    return idle;
+  }
+  const coarse = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
+  if (coarse || reduced()) return idle;
+  registerMotion();
+  const scope = createScope();
+  const t = TIMING.cursor;
+  const zone = options.zone ?? (variant === 'dot' ? (host.parentElement ?? document.body) : document.documentElement);
+  scope.attr(host, 'class', [host.getAttribute('class'), 'mk-cursor', `mk-cursor--${variant}`].filter(Boolean).join(' '));
+  scope.attr(host, 'aria-hidden', 'true');
+
+  const pointer = { x: -100, y: -100, placed: false };
+  const position = { x: -100, y: -100 };
+  const velocity = { x: 0, y: 0 };
+  let visible = false;
+  let label = '';
+  let tone: 'light' | 'dark' = 'light';
+  const made: Element[] = [];
+
+  // ── Markup ────────────────────────────────────────────────────────────────
+  let chip: HTMLElement | null = null;
+  let chipLabel: HTMLElement | null = null;
+  let chipIcon: HTMLElement | null = null;
+  let word: HTMLElement | null = null;
+  const size = { width: 0, height: 0 };
+  if (variant === 'chip') {
+    chip = document.createElement('span');
+    chip.className = 'mk-cursor__chip mk-glass';
+    chip.innerHTML =
+      '<span class="mk-glass__shadow" aria-hidden="true"></span><span class="mk-cursor__icon mk-icon"></span><span class="mk-cursor__label"></span>';
+    chipIcon = chip.querySelector('.mk-cursor__icon');
+    chipLabel = chip.querySelector('.mk-cursor__label');
+    host.append(chip);
+    made.push(chip);
+    gsap.set(chip, { autoAlpha: 0, scale: 0.8 });
+  } else {
+    const arrows = options.arrows ?? 'y';
+    scope.attr(host, 'data-mk-arrows', arrows);
+    scope.attr(zone, 'data-mk-cursor-zone', '');
+    const dot = document.createElement('span');
+    dot.className = 'mk-cursor__dot';
+    dot.innerHTML =
+      arrows === 'none'
+        ? '<span class="mk-cursor__circle"></span><span class="mk-cursor__text"><span class="mk-cursor__word"></span></span>'
+        : `<span class="mk-cursor__circle"></span><span class="mk-cursor__arrow mk-cursor__arrow--start">${svg()}</span><span class="mk-cursor__text"><span class="mk-cursor__word"></span></span><span class="mk-cursor__arrow mk-cursor__arrow--end">${svg()}</span>`;
+    word = dot.querySelector('.mk-cursor__word');
+    if (word) word.textContent = options.text ?? '';
+    host.append(dot);
+    made.push(dot);
+    scope.attr(host, 'data-mk-hidden', '');
+  }
+
+  // ── Chip ──────────────────────────────────────────────────────────────────
+  const appear = motionSpring(...TIMING.springs.cursorAppear);
+  const showChip = (next: HTMLElement | null) => {
+    if (!chip || !chipLabel || !chipIcon) return;
+    const text = next?.dataset.mkCursor ?? '';
+    if (text) {
+      label = text;
+      chipLabel.textContent = text;
+      chipIcon.textContent = next?.dataset.mkCursorIcon ?? '';
+      chip.classList.toggle('mk-cursor__chip--circle', next?.dataset.mkCursorShape === 'circle');
+      const box = chip.getBoundingClientRect();
+      size.width = box.width;
+      size.height = box.height;
+    }
+    if (Boolean(text) === visible) return;
+    visible = Boolean(text);
+    if (!visible) label = '';
+    gsap.to(chip, {
+      autoAlpha: visible ? 1 : 0,
+      scale: visible ? 1 : 0.8,
+      duration: appear.duration,
+      ease: appear.ease,
+      overwrite: 'auto',
+    });
+  };
+
+  // ── Dot ───────────────────────────────────────────────────────────────────
+  let inZone = false;
+  let overHide = false;
+  const syncDot = () => scope.attr(host, 'data-mk-hidden', inZone && !overHide ? null : '');
+  const wordFor = (target: Element | null) => {
+    if (!word) return;
+    const source = target?.closest<HTMLElement>('[data-mk-cursor]');
+    word.textContent = source && zone.contains(source) ? (source.dataset.mkCursor ?? '') : (options.text ?? '');
+  };
+
+  // ── Events ────────────────────────────────────────────────────────────────
+  const place = (event: PointerEvent) => {
+    if (event.pointerType === 'touch') return;
+    pointer.x = event.clientX;
+    pointer.y = event.clientY;
+    if (!pointer.placed) {
+      pointer.placed = true;
+      if (variant === 'dot') {
+        position.x = pointer.x;
+        position.y = pointer.y;
+      }
+    }
+  };
+  scope.on(window, 'pointermove', (event) => place(event as PointerEvent), { passive: true });
+  const overTarget = variant === 'chip' ? document : zone;
+  scope.on(overTarget, 'pointerover', (event) => {
+    const target = event.target as Element | null;
+    if (variant === 'chip') {
+      const source = target?.closest<HTMLElement>('[data-mk-cursor]') ?? null;
+      showChip(source && zone.contains(source) ? source : null);
+      return;
+    }
+    overHide = Boolean(target?.closest('[data-mk-cursor-hide]'));
+    wordFor(target);
+    syncDot();
+  });
+  if (variant === 'dot') {
+    scope.on(zone, 'pointerenter', (event) => {
+      place(event as PointerEvent);
+      inZone = true;
+      visible = true;
+      syncDot();
+    });
+    scope.on(zone, 'pointerleave', () => {
+      inZone = false;
+      visible = false;
+      scope.attr(host, 'data-mk-pressed', null);
+      syncDot();
+    });
+    scope.on(zone, 'pointerdown', () => scope.attr(host, 'data-mk-pressed', ''));
+    scope.on(window, 'pointerup', () => scope.attr(host, 'data-mk-pressed', null));
+  }
+
+  // ── Frame ─────────────────────────────────────────────────────────────────
+  const [stiffness, damping] = TIMING.springs.cursorFollow;
+  const update = (dt = 1) => {
+    if (variant === 'chip') {
+      // Dousan keeps the chip inside the window, 10 px from its edges.
+      const halfW = size.width / 2 + t.gutter;
+      const halfH = size.height / 2 + t.gutter;
+      const tx = size.width ? Math.min(Math.max(pointer.x, halfW), innerWidth - halfW) : pointer.x;
+      const ty = size.height ? Math.min(Math.max(pointer.y, halfH), innerHeight - halfH) : pointer.y;
+      // Motion's spring, integrated in small steps.
+      const steps = Math.max(1, Math.ceil(dt * 4));
+      const h = dt / 60 / steps;
+      for (let i = 0; i < steps; i++) {
+        velocity.x += (stiffness * (tx - position.x) - damping * velocity.x) * h;
+        velocity.y += (stiffness * (ty - position.y) - damping * velocity.y) * h;
+        position.x += velocity.x * h;
+        position.y += velocity.y * h;
+      }
+      if (visible && typeof document.elementFromPoint === 'function') {
+        tone = backgroundTone(document.elementFromPoint(pointer.x, pointer.y));
+        if (chip && chip.dataset.mkTone !== tone) chip.dataset.mkTone = tone;
+      }
+    } else {
+      const step = 1 - Math.pow(1 - t.dotLerp, dt);
+      position.x += (pointer.x - position.x) * step;
+      position.y += (pointer.y - position.y) * step;
+    }
+    host.style.transform = `translate3d(${position.x.toFixed(2)}px, ${position.y.toFixed(2)}px, 0) translate(-50%, -50%)`;
+  };
+  scope.add(subscribe(update));
+  update(0);
+  host.dataset.mkReady = '';
+
+  return {
+    get visible() {
+      return visible;
+    },
+    get label() {
+      return label;
+    },
+    get position() {
+      return { ...position };
+    },
+    get tone() {
+      return tone;
+    },
+    update,
+    destroy() {
+      if (chip) gsap.killTweensOf(chip);
+      scope.dispose();
+      for (const node of made.splice(0)) node.remove();
+      host.style.removeProperty('transform');
+      if (host.getAttribute('style') === '') host.removeAttribute('style');
+      delete host.dataset.mkReady;
+    },
+  };
+}