@3xhaust/oh-my-design 0.16.1

package/core/motion/energy.ts

@@ -0,0 +1,188 @@
+import { inflateSync } from 'node:zlib';
+import type { EnergyCurve, FrameEnergy } from '../types.ts';
+
+// ── Minimal PNG decoder ──────────────────────────────────────────────────────
+//
+// Playwright viewport screenshots are always non-interlaced 8-bit RGB (color type 2)
+// or RGBA (color type 6). This narrow scope — four filter equations plus zlib inflate —
+// handles that exact case in ~80 lines without a pngjs dependency.
+//
+// Interlaced PNGs, palette PNGs, and bit depths other than 8 throw immediately.
+// Those formats never appear in Playwright output; if one did, the caller's try/catch
+// turns the failure into a null result rather than breaking capture.
+
+const PNG_SIG = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+function paethPredictor(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+
+/**
+ * Decode an 8-bit RGB or RGBA PNG buffer into a flat pixel array.
+ *
+ * Supports color types 2 (RGB) and 6 (RGBA), bit depth 8, non-interlaced only —
+ * exactly what Playwright viewport screenshots produce.
+ */
+export function decodePng(data: Buffer): {
+  width: number;
+  height: number;
+  pixels: Uint8Array;
+  channels: number;
+} {
+  for (let i = 0; i < 8; i++) {
+    if (data[i] !== PNG_SIG[i]) throw new Error('not a PNG: bad signature');
+  }
+
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  let channels = 0;
+  const idatChunks: Buffer[] = [];
+
+  while (offset + 12 <= data.length) {
+    const chunkLen = data.readUInt32BE(offset);
+    const type = data.subarray(offset + 4, offset + 8).toString('ascii');
+    const chunk = data.subarray(offset + 8, offset + 8 + chunkLen);
+    offset += 12 + chunkLen; // length(4) + type(4) + data(N) + crc(4)
+
+    if (type === 'IHDR') {
+      width = chunk.readUInt32BE(0);
+      height = chunk.readUInt32BE(4);
+      const bitDepth = chunk[8]!;
+      const colorType = chunk[9]!;
+      const interlace = chunk[12]!;
+      if (bitDepth !== 8) throw new Error(`unsupported PNG bit depth: ${bitDepth} (only 8 supported)`);
+      if (colorType === 2) channels = 3;
+      else if (colorType === 6) channels = 4;
+      else throw new Error(`unsupported PNG color type: ${colorType} (only RGB=2 and RGBA=6 supported)`);
+      if (interlace !== 0) throw new Error('interlaced PNG not supported');
+    } else if (type === 'IDAT') {
+      idatChunks.push(chunk);
+    } else if (type === 'IEND') {
+      break;
+    }
+  }
+
+  if (width === 0 || height === 0 || channels === 0) {
+    throw new Error('PNG IHDR not found or has zero dimensions');
+  }
+
+  const stride = width * channels;
+  const raw = inflateSync(Buffer.concat(idatChunks));
+  const pixels = new Uint8Array(width * height * channels);
+  let srcOff = 0;
+
+  for (let y = 0; y < height; y++) {
+    const filterType = raw[srcOff++]!;
+    const dstRow = y * stride;
+
+    for (let x = 0; x < stride; x++) {
+      const rawVal = raw[srcOff + x]! & 0xff;
+      const a = x >= channels ? pixels[dstRow + x - channels]! : 0;
+      const b = y > 0 ? pixels[dstRow - stride + x]! : 0;
+      const c = (x >= channels && y > 0) ? pixels[dstRow - stride + x - channels]! : 0;
+
+      let val: number;
+      switch (filterType) {
+        case 0: val = rawVal; break;                                            // None
+        case 1: val = (rawVal + a) & 0xff; break;                              // Sub
+        case 2: val = (rawVal + b) & 0xff; break;                              // Up
+        case 3: val = (rawVal + Math.floor((a + b) / 2)) & 0xff; break;        // Average
+        case 4: val = (rawVal + paethPredictor(a, b, c)) & 0xff; break;        // Paeth
+        default: throw new Error(`unknown PNG filter type: ${filterType}`);
+      }
+      pixels[dstRow + x] = val;
+    }
+    srcOff += stride;
+  }
+
+  return { width, height, pixels, channels };
+}
+
+const round4 = (v: number): number => Math.round(v * 10000) / 10000;
+
+/**
+ * Compute per-interval pixel-difference energy from a sequence of PNG frame buffers.
+ *
+ * Energy = fraction of pixels whose max per-channel RGB difference exceeds
+ * `diffThreshold` (default 10, scale 0–255). Alpha is ignored — only the visible RGB
+ * signal is compared.
+ *
+ * Region summary: the frame is split into three equal vertical thirds (top / mid / bottom).
+ * `regionFractions[i]` is the fraction of that third's pixels that changed — answering
+ * "where did the motion happen" without requiring layout data.
+ *
+ * IMPORTANT: this function sees ALL pixel-level motion, including GSAP and rAF-driven
+ * libraries that `document.getAnimations()` cannot detect. Where
+ * `ir.meta.motion.animatedProperties` may read as [] for a GSAP-only page, a non-zero
+ * energy curve confirms motion occurred — closing the getAnimations() blind spot documented
+ * on MotionMeasurement and Invariants.animatedProperties.
+ *
+ * Pure and deterministic: given the same PNG buffers and threshold it always returns the
+ * same result. Safe to call in unit tests with synthetic buffers.
+ *
+ * @param buffers   Ordered PNG buffers, earliest frame first. Fewer than 2 → empty pairs.
+ * @param diffThreshold  Per-channel difference threshold (0–255, default 10).
+ */
+export function computeEnergy(buffers: Buffer[], diffThreshold = 10): EnergyCurve {
+  const frames = buffers.map((b) => decodePng(b));
+  const pairs: FrameEnergy[] = [];
+
+  for (let i = 0; i + 1 < frames.length; i++) {
+    const a = frames[i]!;
+    const b = frames[i + 1]!;
+
+    // Dimension mismatch: treat as fully changed (conservative, not a normal case).
+    if (a.width !== b.width || a.height !== b.height) {
+      pairs.push({ pairIndex: i, changedFraction: 1, regionFractions: [1, 1, 1] });
+      continue;
+    }
+
+    const { width, height, channels } = a;
+    const totalPixels = width * height;
+    const thirdH = Math.floor(height / 3);
+    // Bottom region absorbs any remainder from the floor.
+    const regionTotal = [thirdH * width, thirdH * width, (height - 2 * thirdH) * width];
+    const regionChanged = [0, 0, 0];
+    let totalChanged = 0;
+
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const idx = (y * width + x) * channels;
+        let maxDiff = 0;
+        // Compare RGB channels only — ignore alpha (channel index 3) even if present.
+        const rgbChannels = Math.min(3, channels);
+        for (let ch = 0; ch < rgbChannels; ch++) {
+          const diff = Math.abs((a.pixels[idx + ch]! & 0xff) - (b.pixels[idx + ch]! & 0xff));
+          if (diff > maxDiff) maxDiff = diff;
+        }
+        if (maxDiff > diffThreshold) {
+          totalChanged++;
+          const region = y < thirdH ? 0 : y < thirdH * 2 ? 1 : 2;
+          regionChanged[region]!++;
+        }
+      }
+    }
+
+    const changedFraction = round4(totalChanged / Math.max(totalPixels, 1));
+    const regionFractions: [number, number, number] = [
+      round4(regionChanged[0]! / Math.max(regionTotal[0]!, 1)),
+      round4(regionChanged[1]! / Math.max(regionTotal[1]!, 1)),
+      round4(regionChanged[2]! / Math.max(regionTotal[2]!, 1)),
+    ];
+
+    pairs.push({ pairIndex: i, changedFraction, regionFractions });
+  }
+
+  const peakEnergy = pairs.length > 0
+    ? round4(Math.max(...pairs.map((p) => p.changedFraction)))
+    : 0;
+
+  return { frames: buffers.length, pairs, peakEnergy };
+}

package/core/motion/recipes/image-hover-distortion.md

@@ -0,0 +1,198 @@
+# Image hover distortion
+
+An image hover distortion applies a CSS filter shift, clip-path animation, or both when
+the user hovers an image — desaturating it toward monochrome, applying a blur that
+clears on hover, or using a clip-path polygon that contracts to reveal the image at full
+quality. No WebGL, no canvas: the entire effect is CSS, which means it degrades cleanly
+and runs at composited speed.
+
+## When it earns its place / When it does not
+
+Condition: a gallery or portfolio grid where the hover state deepens engagement before
+the user clicks. The distortion frames the hover moment as a discovery — the image
+reveals itself to the pointer. Effective on showpiece pages where the image is a subject,
+not a container. `expressive.md`: "A gallery or portfolio grid where the hover state
+deepens engagement with a piece before the user clicks."
+
+Condition against: product images where accuracy matters — e-commerce, documentation,
+any context where the image is evidence rather than atmosphere. Distorting a product
+photo misleads the user about what they are buying or reading. Also: navigation
+thumbnails where the user needs to read text overlaid on the image — the distortion
+degrades the legibility of the label. Also: images that are already small (below ~200px
+in either dimension); clip-path animation at small sizes produces visible aliasing.
+
+The effect must complete within 150ms for hover onset and 200ms to settle, per
+`core/theory/motion.md`: "The distortion must complete in under 150ms for hover onset
+and under 200ms to settle. Anything slower reads as broken."
+
+## Parameters
+
+```css
+:root {
+  /* Filter applied in the resting state (before hover).
+     Greyscale + slight desaturation is a common pre-hover treatment. */
+  --distort-filter-rest:  grayscale(0.6) brightness(0.9);
+
+  /* Filter in the hover state. Identity = no filter effect. */
+  --distort-filter-hover: grayscale(0) brightness(1);
+
+  /* Duration for filter transitions. Under 150ms for immediate hover onset. */
+  --distort-filter-duration: 120ms;
+  --distort-filter-ease: var(--ease-out-circ);
+
+  /* Clip-path inset values: resting (slightly cropped) vs. hover (full reveal). */
+  --distort-clip-rest:  inset(8% round 4px);
+  --distort-clip-hover: inset(0%  round 0px);
+
+  /* Duration for clip-path transition. Can be slightly longer than filter. */
+  --distort-clip-duration: 200ms;
+  --distort-clip-ease: var(--ease-out-expo);
+}
+```
+
+## Implementation
+
+```html
+<figure class="gallery-item">
+  <div class="image-distort">
+    <img src="work-1.jpg" alt="Case study: Meridian brand identity" loading="lazy">
+  </div>
+  <figcaption>Meridian</figcaption>
+</figure>
+```
+
+```css
+.image-distort {
+  overflow: hidden;
+  /* Contain the clip-path change. */
+  border-radius: 4px;
+}
+
+.image-distort img {
+  display: block;
+  width: 100%;
+  aspect-ratio: 4 / 3;
+  object-fit: cover;
+
+  /* Apply both filter and clip-path in resting state. */
+  filter: var(--distort-filter-rest);
+  clip-path: var(--distort-clip-rest);
+
+  transition:
+    filter   var(--distort-filter-duration) var(--distort-filter-ease),
+    clip-path var(--distort-clip-duration)  var(--distort-clip-ease);
+
+  /* Both filter and clip-path are composited via the GPU; no layout is triggered. */
+  will-change: filter, clip-path;
+}
+
+/* Hover state: full reveal. */
+.image-distort:hover img,
+.image-distort:focus-within img {
+  filter: var(--distort-filter-hover);
+  clip-path: var(--distort-clip-hover);
+}
+
+/* Scale variant: subtle zoom instead of clip-path. Use one or the other. */
+.image-distort--scale img {
+  transform: scale(1.04);
+  clip-path: none;
+  transition:
+    filter    var(--distort-filter-duration) var(--distort-filter-ease),
+    transform var(--distort-clip-duration)   var(--distort-clip-ease);
+}
+
+.image-distort--scale:hover img,
+.image-distort--scale:focus-within img {
+  filter: var(--distort-filter-hover);
+  transform: scale(1);
+}
+```
+
+## React
+
+```tsx
+import { motion } from 'framer-motion';
+
+const imageVariants = {
+  rest: {
+    filter: 'grayscale(0.6) brightness(0.9)',
+    clipPath: 'inset(8% round 4px)',
+    transition: { duration: 0.12, ease: [0, 0.55, 0.45, 1] }, // ease-out-circ
+  },
+  hover: {
+    filter: 'grayscale(0) brightness(1)',
+    clipPath: 'inset(0% round 0px)',
+    transition: {
+      filter:   { duration: 0.12, ease: [0, 0.55, 0.45, 1] },
+      clipPath: { duration: 0.20, ease: [0.16, 1, 0.3, 1] }, // ease-out-expo
+    },
+  },
+};
+
+function GalleryItem({
+  src,
+  alt,
+  caption,
+}: {
+  src: string;
+  alt: string;
+  caption: string;
+}) {
+  return (
+    <motion.figure initial="rest" whileHover="hover" style={{ margin: 0 }}>
+      <div style={{ overflow: 'hidden', borderRadius: 4 }}>
+        <motion.img
+          src={src}
+          alt={alt}
+          variants={imageVariants}
+          style={{ display: 'block', width: '100%', aspectRatio: '4/3', objectFit: 'cover' }}
+          loading="lazy"
+        />
+      </div>
+      <figcaption>{caption}</figcaption>
+    </motion.figure>
+  );
+}
+```
+
+## Reduced-motion variant
+
+In reduced-motion context, the hover state is still distinct — but achieved with an
+instant opacity or border change rather than an animated filter or clip-path transition.
+The image is always fully visible; no distortion is applied.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .image-distort img {
+    filter: none;
+    clip-path: none;
+    transition: none;
+    will-change: auto;
+  }
+
+  /* Provide a non-motion hover signal: a simple opacity change. */
+  .image-distort:hover img,
+  .image-distort:focus-within img {
+    opacity: 0.85;
+  }
+}
+```
+
+## Performance note
+
+`filter` and `clip-path` are both GPU-composited when the element has a CSS transform
+or `will-change` applied. The `will-change: filter, clip-path` declaration here is
+justified because these properties actively animate on hover. Unlike `will-change:
+transform` applied broadly, hover-scoped `will-change` promotes the layer only for the
+duration of the interaction — the browser manages this correctly.
+
+Do not animate `border-radius` on the image itself — this causes the browser to
+recalculate the clip geometry on every frame. Use `clip-path: inset(... round ...)` to
+achieve rounded corners within a clip-path animation; this stays off-thread. Wrap the
+image in `overflow: hidden` on the parent to handle the visual boundary.
+
+`clip-path` animation between two `inset()` values is well-supported and smooth. Avoid
+animating between two `polygon()` clip-paths unless the polygon point count is identical
+in both states — mismatched polygon point counts cause the browser to interpolate via a
+cross-fade rather than a smooth morph, which defeats the purpose of the animation.

package/core/motion/recipes/magnetic-hover.md

@@ -0,0 +1,229 @@
+# Magnetic hover
+
+A magnetic hover element attracts the pointer toward its centre as the cursor approaches
+within a defined radius, then snaps back when the cursor exits. The element appears to
+pull the cursor toward it; the cursor appears to pull the element. The effect reads as
+weight and responsiveness in the same gesture.
+
+## When it earns its place / When it does not
+
+Condition: a primary interactive element on a showpiece page — a CTA button, a large
+navigation target, a signature link — where the interaction itself is part of the
+experience. The magnet makes the element feel alive and responsive in a way that goes
+beyond hover states. Portfolio sites, agency landing pages, campaign microsites where
+the cursor is a live instrument.
+
+Condition against: any context with more than two or three magnetic elements on screen
+simultaneously — multiple magnets competing for the cursor's attention cancel each other
+out and the effect reads as chaotic rather than deliberate. Also: buttons in utility UI
+where click precision matters (the magnet shifts the perceived centre of the target and
+can cause misclicks). Also: mobile devices — there is no pointer to attract.
+
+The technique requires JavaScript because CSS cannot read pointer coordinates. It must
+be scoped with `@media (pointer: fine)` so it never activates on touch devices.
+
+## Parameters
+
+```css
+:root {
+  /* How far (in px) from the element's edge the magnetic field begins. */
+  --magnetic-radius: 80px;
+
+  /* Maximum displacement of the element's centre, as a fraction of the element's
+     half-width/half-height. 0.3 = moves up to 30% of its own size. */
+  --magnetic-strength: 0.4;
+
+  /* Duration of the snap-back when the cursor exits the field. */
+  --magnetic-return-duration: 600ms;
+  --magnetic-return-ease: var(--ease-out-expo);
+
+  /* Duration of the active tracking (while cursor is in field). Near-instant
+     so it reads as direct response, not as lag. */
+  --magnetic-follow-duration: 120ms;
+  --magnetic-follow-ease: var(--ease-out-circ);
+}
+```
+
+## Implementation
+
+```html
+<div class="magnetic-zone" data-magnetic>
+  <button class="cta-button">Get started</button>
+</div>
+```
+
+```css
+.cta-button {
+  transition:
+    transform var(--magnetic-follow-duration, 120ms) var(--magnetic-follow-ease, ease-out);
+  /* will-change is appropriate here: this element is tracked every pointermove
+     while the cursor is in the field. Limit to one or two elements. */
+  will-change: transform;
+}
+
+.cta-button.is-returning {
+  transition:
+    transform var(--magnetic-return-duration, 600ms) var(--magnetic-return-ease, cubic-bezier(0.16, 1, 0.3, 1));
+}
+
+/* Magnetic is desktop-only. On touch, this is a standard button. */
+@media (pointer: coarse) {
+  .cta-button {
+    transition: none;
+    will-change: auto;
+  }
+}
+```
+
+```js
+// Only run on pointer-fine devices.
+if (window.matchMedia('(pointer: fine)').matches) {
+  document.querySelectorAll('[data-magnetic]').forEach(attachMagnet);
+}
+
+function attachMagnet(zone) {
+  const el = zone.querySelector('button, a, [data-magnetic-target]') ?? zone;
+
+  // Read strength from CSS custom property.
+  const strength = parseFloat(
+    getComputedStyle(document.documentElement)
+      .getPropertyValue('--magnetic-strength')
+  ) || 0.4;
+
+  const radius = parseFloat(
+    getComputedStyle(document.documentElement)
+      .getPropertyValue('--magnetic-radius')
+  ) || 80;
+
+  function onMove(e) {
+    const rect = zone.getBoundingClientRect();
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const dx = e.clientX - cx;
+    const dy = e.clientY - cy;
+    const dist = Math.hypot(dx, dy);
+    const fieldRadius = Math.max(rect.width, rect.height) / 2 + radius;
+
+    if (dist < fieldRadius) {
+      el.classList.remove('is-returning');
+      const pull = (1 - dist / fieldRadius) * strength;
+      const x = dx * pull;
+      const y = dy * pull;
+      el.style.transform = `translate(${x}px, ${y}px)`;
+    } else {
+      release();
+    }
+  }
+
+  function release() {
+    el.classList.add('is-returning');
+    el.style.transform = '';
+    // Remove is-returning after transition completes.
+    el.addEventListener('transitionend', () => el.classList.remove('is-returning'), { once: true });
+  }
+
+  zone.addEventListener('pointermove', onMove, { passive: true });
+  zone.addEventListener('pointerleave', release, { passive: true });
+}
+```
+
+## React
+
+```tsx
+import { useRef, useCallback, useEffect } from 'react';
+import { motion, useSpring, useTransform } from 'framer-motion';
+
+function MagneticButton({
+  children,
+  strength = 0.4,
+  radius = 80,
+}: {
+  children: React.ReactNode;
+  strength?: number;
+  radius?: number;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  // Spring physics give the magnet a more physical feel than a CSS transition.
+  const springConfig = { stiffness: 300, damping: 20, mass: 0.5 };
+  const x = useSpring(0, springConfig);
+  const y = useSpring(0, springConfig);
+
+  const onMove = useCallback((e: React.PointerEvent) => {
+    if (!ref.current) return;
+    const rect = ref.current.getBoundingClientRect();
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const dx = e.clientX - cx;
+    const dy = e.clientY - cy;
+    const dist = Math.hypot(dx, dy);
+    const fieldRadius = Math.max(rect.width, rect.height) / 2 + radius;
+    const pull = Math.max(0, (1 - dist / fieldRadius) * strength);
+    x.set(dx * pull);
+    y.set(dy * pull);
+  }, [strength, radius, x, y]);
+
+  const onLeave = useCallback(() => {
+    x.set(0);
+    y.set(0);
+  }, [x, y]);
+
+  return (
+    <div
+      ref={ref}
+      onPointerMove={onMove}
+      onPointerLeave={onLeave}
+      style={{ display: 'inline-block' }}
+    >
+      <motion.div style={{ x, y }}>
+        {children}
+      </motion.div>
+    </div>
+  );
+}
+```
+
+## Reduced-motion variant
+
+In reduced-motion context, the magnetic behaviour is disabled entirely. The element
+is a standard button with a straightforward hover state. No transform tracking,
+no pointer-move listener.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .cta-button {
+    transition: none !important;
+    transform: none !important;
+    will-change: auto;
+  }
+}
+```
+
+In JS, guard the setup:
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+const pointerFine = window.matchMedia('(pointer: fine)').matches;
+
+if (pointerFine && !prefersReduced) {
+  document.querySelectorAll('[data-magnetic]').forEach(attachMagnet);
+}
+```
+
+## Performance note
+
+The pointer-move handler updates `transform: translate()` — a compositor-only property.
+The `will-change: transform` on the magnetic element is justified here: the element
+is actively animating on every pointer-move event while the cursor is within the field.
+This is not speculative `will-change`; it is applied to an element that is known to
+animate continuously during a user interaction.
+
+Limit magnetic elements to one or two per page. Each active magnetic element with
+`will-change: transform` occupies a compositor layer; more than three simultaneous
+layers on this pattern consumes measurable GPU memory on mobile hardware — even though
+the magnet never activates on mobile, the CSS `will-change` still promotes the layer
+on all breakpoints unless scoped with `@media (pointer: fine)`.
+
+The `{ passive: true }` flag on `pointermove` is critical — without it, the browser
+cannot optimise scroll performance because it must wait for the handler to confirm it
+will not call `preventDefault()`.