@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/components/toast/toast.css

@@ -0,0 +1,114 @@
+/* toast — Stepbro's deck at the top of the screen, above dialogs (top layer when popovers exist). */
+.mk-toaster {
+  position: fixed;
+  inset: 16px 0 auto;
+  z-index: 2147483000;
+  width: 100%;
+  height: 0;
+  margin: 0;
+  padding: 0;
+  overflow: visible;
+  border: 0;
+  background: transparent;
+  pointer-events: none;
+}
+
+.mk-toaster:popover-open {
+  display: block;
+}
+
+mk-toaster {
+  display: contents;
+}
+
+.mk-toast {
+  --mk-toast-bg: var(--mk-surface-4);
+  --mk-toast-radius: 20px;
+  position: absolute;
+  top: 0;
+  left: 50%;
+  max-width: min(420px, calc(100vw - 32px));
+  transform-origin: 50% 0;
+  touch-action: none;
+  pointer-events: auto;
+}
+
+.mk-toast__shell {
+  overflow: hidden;
+  border-radius: var(--mk-toast-radius);
+  background: var(--mk-toast-bg);
+  box-shadow: 0 12px 32px -12px rgb(0 0 0 / 0.35);
+  color: var(--mk-text);
+}
+
+.mk-toast__body {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: 48px;
+  padding: 8px 8px 8px 16px;
+  font-family: var(--mk-font);
+  font-size: var(--md-sys-typescale-label-large-size);
+  font-weight: var(--md-sys-typescale-label-large-weight);
+  letter-spacing: var(--md-sys-typescale-label-large-tracking);
+  white-space: nowrap;
+}
+
+.mk-toast__icon {
+  display: grid;
+  flex: none;
+  place-items: center;
+  color: var(--mk-accent);
+}
+
+.mk-toast[data-mk-tone='error'] .mk-toast__icon {
+  color: var(--mk-error);
+}
+
+.mk-toast[data-mk-tone='info'] .mk-toast__icon {
+  color: var(--mk-muted);
+}
+
+.mk-toast__message {
+  flex: 1;
+}
+
+.mk-toast__action {
+  flex: none;
+  height: 32px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: var(--mk-radius-full);
+  background: transparent;
+  color: var(--mk-accent);
+  font: inherit;
+  cursor: pointer;
+}
+
+.mk-toast__action:hover {
+  background: color-mix(in srgb, currentColor 10%, transparent);
+}
+
+.mk-toast__dismiss {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: var(--mk-muted);
+  cursor: pointer;
+}
+
+.mk-toast__dismiss:hover {
+  background: color-mix(in srgb, currentColor 12%, transparent);
+  color: var(--mk-text);
+}
+
+.mk-toast :is(.mk-toast__action, .mk-toast__dismiss):focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 1px;
+}

package/src/core/channels.ts

@@ -0,0 +1,165 @@
+import { gsap } from 'gsap';
+
+/**
+ * Stepbro's per-property motion channels (ported from Kayro's spring-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.
+ */
+
+export type Channel =
+  | { type: 'spring'; stiffness: number; damping: number; mass?: number; velocity?: number; direction?: number }
+  | { type: 'ease'; duration: number; ease: (progress: number) => number };
+
+export interface ChannelState {
+  current: number;
+  origin: number;
+  target: number;
+  velocity: number;
+  elapsed: number;
+  active: boolean;
+  config: Channel | null;
+}
+
+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`). */
+export function bezier(x1: number, y1: number, x2: number, y2: number) {
+  const at = (t: number, a: number, b: number) => {
+    const u = 1 - t;
+    return 3 * u * u * t * a + 3 * u * t * t * b + t * t * t;
+  };
+  return (progress: number) => {
+    if (progress <= 0 || progress >= 1) return Math.min(1, Math.max(0, progress));
+    let low = 0;
+    let high = 1;
+    let t = progress;
+    for (let step = 0; step < 24; step += 1) {
+      const x = at(t, x1, x2);
+      if (Math.abs(x - progress) < 1e-5) break;
+      if (x < progress) low = t;
+      else high = t;
+      t = (low + high) / 2;
+    }
+    return at(t, y1, y2);
+  };
+}
+
+export const spring = (stiffness: number, damping: number, extra: { mass?: number; velocity?: number; direction?: number } = {}): Channel => ({
+  type: 'spring',
+  stiffness,
+  damping,
+  ...extra,
+});
+
+export const eased = (duration: number, ease: (progress: number) => number): Channel => ({ type: 'ease', duration, ease });
+
+export const createChannelState = (value: number): ChannelState => ({
+  current: value,
+  origin: value,
+  target: value,
+  velocity: 0,
+  elapsed: 0,
+  active: false,
+  config: null,
+});
+
+/** Advance one channel by `seconds`. Pure: exported for tests and custom loops. */
+export function stepChannel(channel: ChannelState, seconds: number) {
+  const config = channel.config;
+  if (!channel.active || !config) return;
+  if (config.type === 'spring') {
+    // Sub-steps of at most 1/60 s keep stiff springs stable; a long frame is capped.
+    const time = Math.min(0.064, Math.max(0, seconds));
+    const steps = Math.max(1, Math.ceil(time / (1 / 60) - 1e-9));
+    const step = time / steps;
+    for (let index = 0; index < steps; index += 1) {
+      const force = -config.stiffness * (channel.current - channel.target) - config.damping * channel.velocity;
+      channel.velocity += (force / (config.mass ?? 1)) * step;
+      channel.current += channel.velocity * step;
+    }
+    if (Math.abs(channel.velocity) <= 0.01 && Math.abs(channel.target - channel.current) <= 0.01) {
+      channel.current = channel.target;
+      channel.velocity = 0;
+      channel.active = false;
+    }
+  } else {
+    channel.elapsed += Math.max(0, seconds);
+    const progress = Math.min(1, channel.elapsed / config.duration);
+    channel.current = progress >= 1 ? channel.target : channel.origin + (channel.target - channel.origin) * config.ease(progress);
+    if (progress >= 1) channel.active = false;
+  }
+}
+
+/** Animate named values toward targets, each on its own channel, calling `onChange` per frame. */
+export function channels<K extends string>(start: Record<K, number>, onChange: (name: K, value: number) => void) {
+  const names = Object.keys(start) as K[];
+  const state = Object.fromEntries(names.map((name) => [name, createChannelState(start[name])])) as Record<K, ChannelState>;
+  let last = 0;
+  let resolveDone: (() => void) | null = null;
+
+  const tick = () => {
+    const now = performance.now();
+    const elapsed = Math.max(0, (now - last) / 1000);
+    last = now;
+    let running = false;
+    for (const name of names) {
+      const channel = state[name];
+      if (!channel.active) continue;
+      stepChannel(channel, elapsed);
+      onChange(name, channel.current);
+      running ||= channel.active;
+    }
+    if (!running) {
+      gsap.ticker.remove(tick);
+      resolveDone?.();
+      resolveDone = null;
+    }
+  };
+
+  return {
+    state,
+    /** Start moving; resolves when every channel has settled (or `stop()` is called). */
+    animate(targets: Partial<Record<K, number>>, configs: Partial<Record<K, Channel>>): Promise<void> {
+      for (const name of Object.keys(targets) as K[]) {
+        const channel = state[name];
+        const config = configs[name];
+        if (!channel || !config) continue;
+        channel.config = config;
+        channel.origin = channel.current;
+        channel.target = targets[name] as number;
+        channel.elapsed = 0;
+        if (config.type === 'spring' && config.velocity) {
+          const sign = config.direction !== undefined ? Math.sign(config.direction) : Math.sign(channel.target - channel.current);
+          channel.velocity = Math.abs(config.velocity) * sign;
+        }
+        channel.active = channel.target !== channel.current || channel.velocity !== 0;
+      }
+      last = performance.now();
+      gsap.ticker.remove(tick);
+      gsap.ticker.add(tick);
+      resolveDone?.();
+      return new Promise((resolve) => {
+        resolveDone = resolve;
+      });
+    },
+    stop() {
+      gsap.ticker.remove(tick);
+      for (const name of names) state[name].active = false;
+      resolveDone?.();
+      resolveDone = null;
+    },
+  };
+}
+
+/** A damped spring as an ease function of progress (Stepbro's `Vw`). */
+export function springEase(ratio: number, velocity = 0) {
+  const damping = Math.min(Math.max(ratio, 0.05), 0.999);
+  const stiffness = 5.6;
+  const frequency = (stiffness / damping) * Math.sqrt(1 - damping * damping);
+  const phase = (velocity - stiffness) / frequency;
+  return (progress: number) =>
+    progress >= 1 ? 1 : 1 + Math.exp(-stiffness * progress) * (-Math.cos(frequency * progress) + phase * Math.sin(frequency * progress));
+}

package/src/core/curves.ts

@@ -0,0 +1,35 @@
+/** Stepbro's 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',
+  /** Lists and steps entering (`flowSoft`, also `numberSoft`). */
+  flow: 'M0,0 C0.25,0.1 0.25,1 1,1',
+  /** A conversation scrolling to its newest message. */
+  chatScroll: 'M0,0 C0.308,0.19 0.318,0.567 0.5,0.8 0.593,0.921 0.656,1 1,1',
+} as const;
+
+/**
+ * A damped spring sampled as an ease path (Stepbro's `FA`): `ratio` below 1
+ * overshoots and settles, `velocity` is the starting speed.
+ */
+export function springPath(ratio: number, velocity = 0, steps = 72): string {
+  const damping = Math.min(Math.max(ratio, 0.05), 0.999);
+  const stiffness = 5.6;
+  const frequency = (stiffness / damping) * Math.sqrt(1 - damping * damping);
+  const phase = (velocity - stiffness) / frequency;
+  const at = (time: number) =>
+    1 + Math.exp(-stiffness * time) * (-Math.cos(frequency * time) + phase * Math.sin(frequency * time));
+  let path = 'M0,0';
+  for (let step = 1; step <= steps; step += 1) {
+    const time = step / steps;
+    path += ` L${time.toFixed(4)},${(step === steps ? 1 : at(time)).toFixed(4)}`;
+  }
+  return path;
+}
+
+/**
+ * Stepbro's own linear() sampling of the signature curve (its backdrop tint),
+ * for CSS and the Web Animations API.
+ */
+export const SIGNATURE_LINEAR =
+  'linear(0 0%, .017 2.5%, .037 5%, .061 7.5%, .091 10%, .13 12.5%, .184 15%, .275 17.5%, .562 20%, .733 22.5%, .803 25%, .848 27.5%, .88 30%, .902 32.5%, .942 40%, .97 50%, .985 60%, .993 70%, .998 80%, 1 90%, 1 100%)';

package/src/core/frame.ts

@@ -0,0 +1,12 @@
+/** requestAnimationFrame with a timer fallback (tests, old WebViews). Returns a cancel function. */
+export function requestFrame(fn: (time: number) => void): () => void {
+  if (typeof requestAnimationFrame === 'function') {
+    const id = requestAnimationFrame(fn);
+    return () => cancelAnimationFrame(id);
+  }
+  const id = setTimeout(() => fn(Date.now()), 16);
+  return () => clearTimeout(id);
+}
+
+/** Resolves on the next frame, after the framework has painted a DOM change. */
+export const nextFrame = () => new Promise<void>((resolve) => requestFrame(() => resolve()));

package/src/core/gsap.ts

@@ -0,0 +1,65 @@
+import { gsap } from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+import { SplitText } from 'gsap/SplitText';
+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. */
+export const ELASTIC = 'elastic.out(1, 0.45)';
+
+/** Custom eases registered by `registerMotion()` (Stepbro curves). Use the names as GSAP `ease` values. */
+export const EASE = {
+  signature: 'mk-signature',
+  flow: 'mk-flow',
+  /** A closing surface's fade (`.56,.27,0,1`). Kept from v0.1; same curve as `fadeAway`. */
+  close: 'mk-close',
+  fadeAway: 'mk-fade-away',
+  /** A closing surface's blur (`.37,.35,0,1`). */
+  blurAway: 'mk-blur-away',
+  chatScroll: 'mk-chat-scroll',
+  /** Items travelling to a new place in a list (spring ratio .52). */
+  layoutReflow: 'mk-layout-reflow',
+  /** A dragged item landing in its slot (spring ratio .62). */
+  sortableLand: 'mk-sortable-land',
+  slot: 'mk-slot',
+  slotResize: 'mk-slot-resize',
+  liquidSize: 'mk-liquid-size',
+  swatch: 'mk-swatch',
+  swatchLight: 'mk-swatch-light',
+  sheet: 'mk-sheet',
+  inOut: 'mk-in-out',
+} as const;
+
+const CURVES: Record<keyof typeof EASE, string> = {
+  signature: PATHS.signature,
+  flow: PATHS.flow,
+  close: '.56,.27,0,1',
+  fadeAway: '.56,.27,0,1',
+  blurAway: '.37,.35,0,1',
+  chatScroll: PATHS.chatScroll,
+  layoutReflow: springPath(0.52),
+  sortableLand: springPath(0.62),
+  slot: '.34,1.56,.64,1',
+  slotResize: '.2,0,0,1',
+  liquidSize: '.8,.3,.5,.8',
+  swatch: '.38,.49,0,1.5',
+  swatchLight: '.11,1,0,1',
+  sheet: '.16,1,.3,1',
+  inOut: '.42,0,.58,1',
+};
+
+let registered = false;
+
+/** Register plugins and eases once. Safe to call from every recipe and during SSR (no-op). */
+export function registerMotion() {
+  if (typeof window === 'undefined') return;
+  // Cancels the MK_HEAD_SCRIPT safety net: JS owns the entrance states from here on.
+  document.documentElement.classList.add('mk-ready');
+  if (registered) return;
+  registered = true;
+  gsap.registerPlugin(ScrollTrigger, SplitText, CustomEase, Flip);
+  for (const key of Object.keys(EASE) as Array<keyof typeof EASE>) CustomEase.create(EASE[key], CURVES[key]);
+}
+
+export { gsap, ScrollTrigger, SplitText, CustomEase, Flip };

package/src/core/loop.ts

@@ -0,0 +1,44 @@
+import { gsap } from 'gsap';
+
+/** Called every frame with dt = 1 at 60 Hz. */
+export type Tick = (dt: number) => void;
+
+const subscribers = new Set<Tick>();
+const FRAME_MS = 1000 / 60;
+
+function tick(_time: number, deltaMs: number) {
+  // Capped so a backgrounded tab does not explode the springs.
+  const dt = Math.min(deltaMs / FRAME_MS, 3);
+  subscribers.forEach((fn) => fn(dt));
+}
+
+/** One shared ticker callback for every recipe (spencergabor.com's single rAF loop). */
+export function subscribe(fn: Tick): () => void {
+  if (!subscribers.size) gsap.ticker.add(tick);
+  subscribers.add(fn);
+  return () => {
+    subscribers.delete(fn);
+    if (!subscribers.size) gsap.ticker.remove(tick);
+  };
+}
+
+/** Run `fn` every frame only while `el` is near the viewport. */
+export function whileVisible(el: Element, fn: Tick, rootMargin = '100px'): () => void {
+  let stop: (() => void) | null = null;
+  const io = new IntersectionObserver(
+    ([entry]) => {
+      if (entry?.isIntersecting) stop ??= subscribe(fn);
+      else {
+        stop?.();
+        stop = null;
+      }
+    },
+    { rootMargin },
+  );
+  io.observe(el);
+  return () => {
+    io.disconnect();
+    stop?.();
+    stop = null;
+  };
+}

package/src/core/math.ts

@@ -0,0 +1,9 @@
+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). */
+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) {
+  const t = (v - inMin) / (inMax - inMin);
+  return lerp(outMin, outMax, clamped ? clamp(t, 0, 1) : t);
+}

package/src/core/physics-spring.ts

@@ -0,0 +1,59 @@
+/*
+ * 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…).
+ * motionSpring() gives a GSAP ease plus the time it takes to settle;
+ * springLinear() samples it as a CSS linear(). Stepbro's own springs (FA)
+ * stay in springPath / springEase.
+ */
+
+const REST = 0.001;
+const STEP = 1 / 240;
+const LIMIT = 10;
+
+export interface MotionSpring {
+  /** Progress 0…1 over `duration` → position (overshoots when bouncy). */
+  ease: (progress: number) => number;
+  /** Seconds until it stays within 0.1 % of the target. */
+  duration: number;
+}
+
+function position(stiffness: number, damping: number, mass: number) {
+  const w0 = Math.sqrt(stiffness / mass);
+  const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+  if (zeta < 1) {
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);
+    return (t: number) => 1 - Math.exp(-zeta * w0 * t) * (Math.cos(wd * t) + ((zeta * w0) / wd) * Math.sin(wd * t));
+  }
+  if (zeta === 1) return (t: number) => 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+  const root = Math.sqrt(zeta * zeta - 1);
+  const r1 = -w0 * (zeta - root);
+  const r2 = -w0 * (zeta + root);
+  return (t: number) => 1 - (r2 * Math.exp(r1 * t) - r1 * Math.exp(r2 * t)) / (r2 - r1);
+}
+
+const springs = new Map<string, MotionSpring>();
+
+export function motionSpring(stiffness: number, damping: number, mass = 1): MotionSpring {
+  const key = `${stiffness}/${damping}/${mass}`;
+  const known = springs.get(key);
+  if (known) return known;
+  const x = position(Math.max(stiffness, 1e-6), Math.max(damping, 0), Math.max(mass, 1e-6));
+  let settled = 0;
+  for (let i = 0; i * STEP <= LIMIT; i++) if (Math.abs(x(i * STEP) - 1) > REST) settled = (i + 1) * STEP;
+  const duration = Math.round(Math.min(settled, LIMIT) * 1000) / 1000;
+  const spring: MotionSpring = {
+    ease: (progress) => (progress <= 0 ? 0 : progress >= 1 ? 1 : x(progress * duration)),
+    duration,
+  };
+  springs.set(key, spring);
+  return spring;
+}
+
+/** Seconds a Motion spring takes to settle. */
+export const springDuration = (stiffness: number, damping: number, mass = 1) => motionSpring(stiffness, damping, mass).duration;
+
+/** The spring as a CSS linear() easing (pair it with springDuration). */
+export function springLinear(stiffness: number, damping: number, mass = 1, points = 40) {
+  const { ease } = motionSpring(stiffness, damping, mass);
+  return `linear(${Array.from({ length: points + 1 }, (_, i) => Number(ease(i / points).toFixed(4))).join(', ')})`;
+}

package/src/core/pointer.ts

@@ -0,0 +1,63 @@
+import { gsap } from 'gsap';
+
+/** Live pointer position (viewport px) plus movement accumulated since the last frame. */
+export const pointer = { x: 0, y: 0, active: false };
+
+let mx = 0;
+let my = 0;
+let lastX: number | null = null;
+let lastY: number | null = null;
+let users = 0;
+
+function onMove(e: PointerEvent) {
+  if (lastX !== null && lastY !== null) {
+    mx += e.clientX - lastX;
+    my += e.clientY - lastY;
+  }
+  lastX = pointer.x = e.clientX;
+  lastY = pointer.y = e.clientY;
+  pointer.active = true;
+}
+
+function onOut(e: PointerEvent) {
+  if (e.relatedTarget) return;
+  pointer.active = false;
+  lastX = lastY = null;
+}
+
+/** Start tracking (reference-counted). Call the returned function when the recipe is destroyed. */
+export function bindPointer(): () => void {
+  if (users++ === 0) {
+    addEventListener('pointermove', onMove, { passive: true });
+    document.addEventListener('pointerout', onOut);
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--users > 0) return;
+    removeEventListener('pointermove', onMove);
+    document.removeEventListener('pointerout', onOut);
+    pointer.active = false;
+    lastX = lastY = null;
+    mx = my = 0;
+  };
+}
+
+let frameMovement = { mx: 0, my: 0 };
+let movementFrame = -1;
+
+/**
+ * Pointer movement since the previous animation frame. Every caller in the same
+ * frame gets the same value (two recipes on a page both feel the pointer); the
+ * next frame starts again from what moved since.
+ */
+export function takeMovement() {
+  const frame = gsap.ticker.frame;
+  if (frame !== movementFrame) {
+    movementFrame = frame;
+    frameMovement = { mx, my };
+    mx = my = 0;
+  }
+  return frameMovement;
+}

package/src/core/reduced.ts

@@ -0,0 +1,21 @@
+/** `prefers-reduced-motion: reduce`. Always false during SSR. */
+export function reduced(): boolean {
+  return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * Entrance animations run only with motion allowed and when the head safety net
+ * (see MK_HEAD_SCRIPT) has not given up on JavaScript.
+ */
+export function entrances(): boolean {
+  if (reduced()) return false;
+  return !(typeof document !== 'undefined' && document.documentElement.classList.contains('mk-failed'));
+}
+
+/**
+ * Inline this in <head> (before CSS paints). It enables the hidden entrance states
+ * (`.mk-js`) and reveals everything again (`.mk-failed`) if no recipe has started
+ * within 2.5 s — e.g. the bundle failed to load.
+ */
+export const MK_HEAD_SCRIPT =
+  "(function(){var r=document.documentElement;r.classList.add('mk-js');setTimeout(function(){if(!r.classList.contains('mk-ready'))r.classList.add('mk-failed')},2500)})();";

package/src/core/scope.ts

@@ -0,0 +1,70 @@
+import type { Cleanup } from './types';
+
+export interface Scope {
+  /** Register any cleanup; returns it for convenience. */
+  add(fn: Cleanup): Cleanup;
+  /** addEventListener that is removed on dispose. */
+  on<K extends keyof HTMLElementEventMap>(
+    target: EventTarget,
+    type: K | (string & {}),
+    listener: (event: HTMLElementEventMap[K]) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void;
+  /** Disconnects the observer on dispose and returns it. */
+  observe<O extends { disconnect(): void }>(observer: O): O;
+  /** setTimeout that is cleared on dispose. */
+  timeout(fn: () => void, ms: number): void;
+  /** Set (or remove, with null) an attribute; dispose puts the original value back. */
+  attr(el: Element, name: string, value: string | null): void;
+  /** Run every cleanup once, newest first. */
+  dispose(): void;
+  readonly disposed: boolean;
+}
+
+/** Collects the side effects of one recipe instance so `destroy()` can undo all of them. */
+export function createScope(): Scope {
+  const cleanups: Cleanup[] = [];
+  const originals = new Map<Element, Map<string, string | null>>();
+  let disposed = false;
+  return {
+    add(fn) {
+      cleanups.push(fn);
+      return fn;
+    },
+    on(target, type, listener, options) {
+      target.addEventListener(type, listener as EventListener, options);
+      cleanups.push(() => target.removeEventListener(type, listener as EventListener, options));
+    },
+    observe(observer) {
+      cleanups.push(() => observer.disconnect());
+      return observer;
+    },
+    timeout(fn, ms) {
+      const id = setTimeout(fn, ms);
+      cleanups.push(() => clearTimeout(id));
+    },
+    attr(el, name, value) {
+      let saved = originals.get(el);
+      if (!saved) originals.set(el, (saved = new Map()));
+      if (!saved.has(name)) {
+        saved.set(name, el.getAttribute(name));
+        cleanups.push(() => {
+          const original = saved.get(name);
+          if (original === null || original === undefined) el.removeAttribute(name);
+          else el.setAttribute(name, original);
+        });
+      }
+      if (value === null) el.removeAttribute(name);
+      else el.setAttribute(name, value);
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const fn of cleanups.reverse()) fn();
+      cleanups.length = 0;
+    },
+    get disposed() {
+      return disposed;
+    },
+  };
+}