paper-motion 0.1.0 → 0.2.1

package/runtime/core.js

@@ -0,0 +1,269 @@
+// paper-motion core: the pure helpers (math, easing, springs, keyframes, noise, color, text split, shapes).
+// Browser-safe on its own: no shaders, no location, no scene. The moves import from here, so they run anywhere
+// (the render engine, the site's live player). index.js re-exports all of it as 'paper-motion'.
+
+const resolveEl = (el) => (typeof el === 'string' ? document.querySelector(el) : el);
+
+/* Math, timing, easing                                                */
+/* ------------------------------------------------------------------ */
+
+export const clamp = (v, a = 0, b = 1) => Math.min(b, Math.max(a, v));
+export const lerp = (a, b, p) => a + (b - a) * p;
+export const invlerp = (a, b, v) => (b === a ? 0 : (v - a) / (b - a));
+export const remap = (v, a, b, c, d, doClamp = true) => lerp(c, d, doClamp ? clamp(invlerp(a, b, v)) : invlerp(a, b, v));
+export const smoothstep = (e0, e1, x) => { const p = clamp((x - e0) / (e1 - e0)); return p * p * (3 - 2 * p); };
+export const fract = (x) => x - Math.floor(x);
+export const TAU = Math.PI * 2;
+
+/** 0..1 progress of t through [start, end], eased. */
+export const progress = (t, start, end, easing = ease.linear) => easing(clamp(invlerp(start, end, t)));
+
+/** Progress for item i of a staggered group. */
+export const stagger = (t, i, { start = 0, each = 0.08, duration = 0.8, easing } = {}) =>
+  progress(t, start + i * each, start + i * each + duration, easing);
+
+/** 0..1 phase of t in a cycle of `period` seconds. */
+export const phase = (t, period) => fract(t / period);
+/** Sine oscillator in -1..1. Use period = duration / n for perfect loops. */
+export const osc = (t, period, offset = 0) => Math.sin(TAU * (t / period + offset));
+
+/**
+ * Keyframes: keys(t, [[0, 0], [2, 1, ease.outExpo], [5, '#ff0044']])
+ * Values: numbers, arrays of numbers, or hex colors (mixed in OKLab).
+ * The easing on a key applies to the segment arriving at that key.
+ */
+export function keys(t, frames) {
+  if (t <= frames[0][0]) return frames[0][1];
+  for (let i = 1; i < frames.length; i++) {
+    const [t1, v1, e = ease.inOutCubic] = frames[i];
+    const [t0, v0] = frames[i - 1];
+    if (t <= t1) return mix(v0, v1, e(invlerp(t0, t1, t)));
+  }
+  return frames[frames.length - 1][1];
+}
+
+export function mix(a, b, p) {
+  if (typeof a === 'number') return lerp(a, b, p);
+  if (Array.isArray(a)) return a.map((v, i) => mix(v, b[i], p));
+  if (typeof a === 'string') return mixColor(a, b, p);
+  return p < 0.5 ? a : b;
+}
+
+const c1 = 1.70158, c3 = c1 + 1;
+export const ease = {
+  linear: (x) => x,
+  inSine: (x) => 1 - Math.cos((x * Math.PI) / 2),
+  outSine: (x) => Math.sin((x * Math.PI) / 2),
+  inOutSine: (x) => -(Math.cos(Math.PI * x) - 1) / 2,
+  inQuad: (x) => x * x,
+  outQuad: (x) => 1 - (1 - x) ** 2,
+  inOutQuad: (x) => (x < 0.5 ? 2 * x * x : 1 - (-2 * x + 2) ** 2 / 2),
+  inCubic: (x) => x ** 3,
+  outCubic: (x) => 1 - (1 - x) ** 3,
+  inOutCubic: (x) => (x < 0.5 ? 4 * x ** 3 : 1 - (-2 * x + 2) ** 3 / 2),
+  inQuart: (x) => x ** 4,
+  outQuart: (x) => 1 - (1 - x) ** 4,
+  inOutQuart: (x) => (x < 0.5 ? 8 * x ** 4 : 1 - (-2 * x + 2) ** 4 / 2),
+  inQuint: (x) => x ** 5,
+  outQuint: (x) => 1 - (1 - x) ** 5,
+  inOutQuint: (x) => (x < 0.5 ? 16 * x ** 5 : 1 - (-2 * x + 2) ** 5 / 2),
+  inExpo: (x) => (x === 0 ? 0 : 2 ** (10 * x - 10)),
+  outExpo: (x) => (x === 1 ? 1 : 1 - 2 ** (-10 * x)),
+  inOutExpo: (x) => (x === 0 ? 0 : x === 1 ? 1 : x < 0.5 ? 2 ** (20 * x - 10) / 2 : (2 - 2 ** (-20 * x + 10)) / 2),
+  inCirc: (x) => 1 - Math.sqrt(1 - x * x),
+  outCirc: (x) => Math.sqrt(1 - (x - 1) ** 2),
+  inOutCirc: (x) => (x < 0.5 ? (1 - Math.sqrt(1 - (2 * x) ** 2)) / 2 : (Math.sqrt(1 - (-2 * x + 2) ** 2) + 1) / 2),
+  outBack: (x) => 1 + c3 * (x - 1) ** 3 + c1 * (x - 1) ** 2,
+  inOutBack: (x) => { const c2 = c1 * 1.525; return x < 0.5 ? ((2 * x) ** 2 * ((c2 + 1) * 2 * x - c2)) / 2 : ((2 * x - 2) ** 2 * ((c2 + 1) * (x * 2 - 2) + c2) + 2) / 2; },
+  /** CSS-style cubic-bezier(x1, y1, x2, y2). */
+  bezier(x1, y1, x2, y2) {
+    const A = (a, b) => 1 - 3 * b + 3 * a, B = (a, b) => 3 * b - 6 * a, C = (a) => 3 * a;
+    const calc = (t, a, b) => ((A(a, b) * t + B(a, b)) * t + C(a)) * t;
+    const slope = (t, a, b) => 3 * A(a, b) * t * t + 2 * B(a, b) * t + C(a);
+    return (x) => {
+      if (x <= 0 || x >= 1) return x;
+      let t = x;
+      for (let i = 0; i < 8; i++) { const s = slope(t, x1, x2); if (Math.abs(s) < 1e-6) break; t -= (calc(t, x1, x2) - x) / s; }
+      return calc(clamp(t), y1, y2);
+    };
+  },
+};
+
+// After Effects-style curves (graph editor feel)
+ease.easy = ease.bezier(0.33, 0, 0.67, 1);        // AE "Easy Ease" (33% influence)
+ease.smooth = ease.bezier(0.65, 0, 0.35, 1);      // stronger in/out, motion-design default
+ease.snappy = ease.bezier(0.16, 1, 0.3, 1);       // fast start, long soft landing (≈ expo out)
+ease.anticipate = ease.bezier(0.36, -0.35, 0.3, 1); // tiny pull-back before moving
+
+/**
+ * Physical spring, analytic (deterministic). Returns 0→1 with overshoot for
+ * seconds `dt` since the spring was released (negative dt → 0).
+ * Lower damping = more bounce. stiffness 170 / damping 26 is a crisp UI spring.
+ */
+export function spring(dt, { stiffness = 170, damping = 20, mass = 1 } = {}) {
+  if (dt <= 0) return 0;
+  const w0 = Math.sqrt(stiffness / mass), zeta = damping / (2 * Math.sqrt(stiffness * mass));
+  if (zeta < 1) {
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);
+    return 1 - Math.exp(-zeta * w0 * dt) * (Math.cos(wd * dt) + ((zeta * w0) / wd) * Math.sin(wd * dt));
+  }
+  return 1 - Math.exp(-w0 * dt) * (1 + w0 * dt);
+}
+
+/* ------------------------------------------------------------------ */
+/* Randomness and noise (seeded, deterministic)                        */
+/* ------------------------------------------------------------------ */
+
+export function rng(seed = 1) {
+  let a = typeof seed === 'string' ? [...seed].reduce((h, c) => Math.imul(h ^ c.charCodeAt(0), 16777619), 2166136261) : seed >>> 0;
+  const next = () => {
+    a |= 0; a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  return {
+    next,
+    range: (lo, hi) => lo + (hi - lo) * next(),
+    int: (lo, hi) => Math.floor(lo + (hi - lo + 1) * next()),
+    pick: (arr) => arr[Math.floor(next() * arr.length)],
+    sign: () => (next() < 0.5 ? -1 : 1),
+  };
+}
+
+const hash3 = (x, y, z) => {
+  let h = Math.imul(x, 374761393) ^ Math.imul(y, 668265263) ^ Math.imul(z, 2147483647);
+  h = Math.imul(h ^ (h >>> 13), 1274126177);
+  return ((h ^ (h >>> 16)) >>> 0) / 4294967295;
+};
+/** Smooth 3D value noise in 0..1. noise(x), noise(x, y), noise(x, y, z). */
+export function noise(x, y = 0, z = 0) {
+  const xi = Math.floor(x), yi = Math.floor(y), zi = Math.floor(z);
+  const xf = x - xi, yf = y - yi, zf = z - zi;
+  const u = xf * xf * (3 - 2 * xf), v = yf * yf * (3 - 2 * yf), w = zf * zf * (3 - 2 * zf);
+  const n = (a, b, c) => hash3(xi + a, yi + b, zi + c);
+  const x00 = lerp(n(0, 0, 0), n(1, 0, 0), u), x10 = lerp(n(0, 1, 0), n(1, 1, 0), u);
+  const x01 = lerp(n(0, 0, 1), n(1, 0, 1), u), x11 = lerp(n(0, 1, 1), n(1, 1, 1), u);
+  return lerp(lerp(x00, x10, v), lerp(x01, x11, v), w);
+}
+/** Fractal noise (octaves of value noise), 0..1. */
+export function fbm(x, y = 0, z = 0, octaves = 4) {
+  let s = 0, amp = 0.5, f = 1, norm = 0;
+  for (let i = 0; i < octaves; i++) { s += amp * noise(x * f, y * f, z * f); norm += amp; amp *= 0.5; f *= 2; }
+  return s / norm;
+}
+
+/* ------------------------------------------------------------------ */
+/* Color (OKLab mixing)                                                */
+/* ------------------------------------------------------------------ */
+
+function hexToRgb(hex) {
+  let h = hex.replace('#', '');
+  if (h.length <= 4) h = [...h].map((c) => c + c).join('');
+  const n = parseInt(h.slice(0, 6), 16);
+  const a = h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1;
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255, a];
+}
+const toLin = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+const toSrgb = (c) => Math.round(255 * clamp(c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055));
+function rgbToOklab([r, g, b]) {
+  r = toLin(r); g = toLin(g); b = toLin(b);
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s];
+}
+function oklabToRgb([L, A, B]) {
+  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3;
+  return [toSrgb(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s), toSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s), toSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)];
+}
+/** Perceptual color mix of two hex colors -> hex. */
+export function mixColor(a, b, p) {
+  const A = hexToRgb(a), B = hexToRgb(b);
+  const [r, g, bl] = oklabToRgb(mix(rgbToOklab(A), rgbToOklab(B), p));
+  const al = lerp(A[3], B[3], p);
+  const hx = (n) => n.toString(16).padStart(2, '0');
+  return `#${hx(r)}${hx(g)}${hx(bl)}${al < 1 ? hx(Math.round(al * 255)) : ''}`;
+}
+
+/* ------------------------------------------------------------------ */
+/* Typography                                                          */
+/* ------------------------------------------------------------------ */
+
+/** Wrap each word or char of an element in spans for staggered motion. Returns the spans. */
+export function split(el, by = 'chars') {
+  el = resolveEl(el);
+  const text = el.textContent;
+  el.textContent = '';
+  el.setAttribute('aria-label', text);
+  const out = [];
+  const words = text.split(/(\s+)/);
+  for (const w of words) {
+    if (/^\s+$/.test(w)) { el.appendChild(document.createTextNode(w)); continue; }
+    const ws = document.createElement('span');
+    ws.style.display = 'inline-block';
+    ws.style.whiteSpace = 'pre';
+    if (by === 'words') { ws.textContent = w; out.push(ws); }
+    else for (const ch of w) { const c = document.createElement('span'); c.style.display = 'inline-block'; c.textContent = ch; ws.appendChild(c); out.push(c); }
+    el.appendChild(ws);
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* Shapes                                                              */
+/* ------------------------------------------------------------------ */
+
+/**
+ * SVG path `d` for a hand-cut rounded rectangle: the "organic" shape language.
+ * Deterministic for a given seed, so a shape keeps its edges across frames and renders.
+ * @param {number} w,h          size in px
+ * @param {object} [o]
+ * @param {number} [o.radius]   corner radius in px (default 24)
+ * @param {number} [o.wobble]   edge irregularity in px (default 0.6% of the short side; keep it low)
+ * @param {number} [o.seed]     changes the irregularity, not its amount
+ */
+export function organicPath(w, h, { radius = 24, wobble, seed = 1 } = {}) {
+  const amp = wobble ?? Math.min(w, h) * 0.014;
+  // draw on a box inset by the wobble, so the shape never leaves w×h (and never gets clipped flat)
+  const W0 = w, H0 = h; w -= amp * 2; h -= amp * 2;
+  const r = Math.min(radius, w / 2, h / 2);
+  const per = 2 * (w + h - 4 * r) + 2 * Math.PI * r;
+  const n = Math.max(16, Math.round(per / 40));
+  const pt = (d) => {
+    // walk the rounded-rect perimeter clockwise from the top-left corner's end
+    const segs = [[w - 2 * r, 'top'], [Math.PI * r / 2, 'tr'], [h - 2 * r, 'right'], [Math.PI * r / 2, 'br'], [w - 2 * r, 'bottom'], [Math.PI * r / 2, 'bl'], [h - 2 * r, 'left'], [Math.PI * r / 2, 'tl']];
+    for (const [len, k] of segs) {
+      if (d > len) { d -= len; continue; }
+      const a = r ? d / r : 0;
+      switch (k) {
+        case 'top': return [r + d, 0, 0, -1];
+        case 'tr': return [w - r + r * Math.sin(a), r - r * Math.cos(a), Math.sin(a), -Math.cos(a)];
+        case 'right': return [w, r + d, 1, 0];
+        case 'br': return [w - r + r * Math.cos(a), h - r + r * Math.sin(a), Math.cos(a), Math.sin(a)];
+        case 'bottom': return [w - r - d, h, 0, 1];
+        case 'bl': return [r - r * Math.sin(a), h - r + r * Math.cos(a), -Math.sin(a), Math.cos(a)];
+        case 'left': return [0, h - r - d, -1, 0];
+        default: return [r - r * Math.cos(a), r - r * Math.sin(a), -Math.cos(a), -Math.sin(a)];
+      }
+    }
+    return [r, 0, 0, -1];
+  };
+  const P = Array.from({ length: n }, (_, i) => {
+    const [x, y, nx, ny] = pt((i / n) * per);
+    const o = amp * (noise(i * 0.55, seed * 7.13) * 2 - 1);
+    return [x + nx * o + amp, y + ny * o + amp];
+  });
+  void W0; void H0;
+  // closed Catmull-Rom through the points, as cubic Béziers
+  let d = `M${P[0][0].toFixed(2)},${P[0][1].toFixed(2)}`;
+  for (let i = 0; i < n; i++) {
+    const p0 = P[(i - 1 + n) % n], p1 = P[i], p2 = P[(i + 1) % n], p3 = P[(i + 2) % n];
+    const c1 = [p1[0] + (p2[0] - p0[0]) / 6, p1[1] + (p2[1] - p0[1]) / 6];
+    const c2 = [p2[0] - (p3[0] - p1[0]) / 6, p2[1] - (p3[1] - p1[1]) / 6];
+    d += `C${c1[0].toFixed(2)},${c1[1].toFixed(2)} ${c2[0].toFixed(2)},${c2[1].toFixed(2)} ${p2[0].toFixed(2)},${p2[1].toFixed(2)}`;
+  }
+  return d + 'Z';
+}

package/runtime/index.js

@@ -323,269 +323,12 @@ function child(parent) {
 }
 
 /* ------------------------------------------------------------------ */
-/* Math, timing, easing                                                */
 /* ------------------------------------------------------------------ */
-
-export const clamp = (v, a = 0, b = 1) => Math.min(b, Math.max(a, v));
-export const lerp = (a, b, p) => a + (b - a) * p;
-export const invlerp = (a, b, v) => (b === a ? 0 : (v - a) / (b - a));
-export const remap = (v, a, b, c, d, doClamp = true) => lerp(c, d, doClamp ? clamp(invlerp(a, b, v)) : invlerp(a, b, v));
-export const smoothstep = (e0, e1, x) => { const p = clamp((x - e0) / (e1 - e0)); return p * p * (3 - 2 * p); };
-export const fract = (x) => x - Math.floor(x);
-export const TAU = Math.PI * 2;
-
-/** 0..1 progress of t through [start, end], eased. */
-export const progress = (t, start, end, easing = ease.linear) => easing(clamp(invlerp(start, end, t)));
-
-/** Progress for item i of a staggered group. */
-export const stagger = (t, i, { start = 0, each = 0.08, duration = 0.8, easing } = {}) =>
-  progress(t, start + i * each, start + i * each + duration, easing);
-
-/** 0..1 phase of t in a cycle of `period` seconds. */
-export const phase = (t, period) => fract(t / period);
-/** Sine oscillator in -1..1. Use period = duration / n for perfect loops. */
-export const osc = (t, period, offset = 0) => Math.sin(TAU * (t / period + offset));
-
-/**
- * Keyframes: keys(t, [[0, 0], [2, 1, ease.outExpo], [5, '#ff0044']])
- * Values: numbers, arrays of numbers, or hex colors (mixed in OKLab).
- * The easing on a key applies to the segment arriving at that key.
- */
-export function keys(t, frames) {
-  if (t <= frames[0][0]) return frames[0][1];
-  for (let i = 1; i < frames.length; i++) {
-    const [t1, v1, e = ease.inOutCubic] = frames[i];
-    const [t0, v0] = frames[i - 1];
-    if (t <= t1) return mix(v0, v1, e(invlerp(t0, t1, t)));
-  }
-  return frames[frames.length - 1][1];
-}
-
-export function mix(a, b, p) {
-  if (typeof a === 'number') return lerp(a, b, p);
-  if (Array.isArray(a)) return a.map((v, i) => mix(v, b[i], p));
-  if (typeof a === 'string') return mixColor(a, b, p);
-  return p < 0.5 ? a : b;
-}
-
-const c1 = 1.70158, c3 = c1 + 1;
-export const ease = {
-  linear: (x) => x,
-  inSine: (x) => 1 - Math.cos((x * Math.PI) / 2),
-  outSine: (x) => Math.sin((x * Math.PI) / 2),
-  inOutSine: (x) => -(Math.cos(Math.PI * x) - 1) / 2,
-  inQuad: (x) => x * x,
-  outQuad: (x) => 1 - (1 - x) ** 2,
-  inOutQuad: (x) => (x < 0.5 ? 2 * x * x : 1 - (-2 * x + 2) ** 2 / 2),
-  inCubic: (x) => x ** 3,
-  outCubic: (x) => 1 - (1 - x) ** 3,
-  inOutCubic: (x) => (x < 0.5 ? 4 * x ** 3 : 1 - (-2 * x + 2) ** 3 / 2),
-  inQuart: (x) => x ** 4,
-  outQuart: (x) => 1 - (1 - x) ** 4,
-  inOutQuart: (x) => (x < 0.5 ? 8 * x ** 4 : 1 - (-2 * x + 2) ** 4 / 2),
-  inQuint: (x) => x ** 5,
-  outQuint: (x) => 1 - (1 - x) ** 5,
-  inOutQuint: (x) => (x < 0.5 ? 16 * x ** 5 : 1 - (-2 * x + 2) ** 5 / 2),
-  inExpo: (x) => (x === 0 ? 0 : 2 ** (10 * x - 10)),
-  outExpo: (x) => (x === 1 ? 1 : 1 - 2 ** (-10 * x)),
-  inOutExpo: (x) => (x === 0 ? 0 : x === 1 ? 1 : x < 0.5 ? 2 ** (20 * x - 10) / 2 : (2 - 2 ** (-20 * x + 10)) / 2),
-  inCirc: (x) => 1 - Math.sqrt(1 - x * x),
-  outCirc: (x) => Math.sqrt(1 - (x - 1) ** 2),
-  inOutCirc: (x) => (x < 0.5 ? (1 - Math.sqrt(1 - (2 * x) ** 2)) / 2 : (Math.sqrt(1 - (-2 * x + 2) ** 2) + 1) / 2),
-  outBack: (x) => 1 + c3 * (x - 1) ** 3 + c1 * (x - 1) ** 2,
-  inOutBack: (x) => { const c2 = c1 * 1.525; return x < 0.5 ? ((2 * x) ** 2 * ((c2 + 1) * 2 * x - c2)) / 2 : ((2 * x - 2) ** 2 * ((c2 + 1) * (x * 2 - 2) + c2) + 2) / 2; },
-  /** CSS-style cubic-bezier(x1, y1, x2, y2). */
-  bezier(x1, y1, x2, y2) {
-    const A = (a, b) => 1 - 3 * b + 3 * a, B = (a, b) => 3 * b - 6 * a, C = (a) => 3 * a;
-    const calc = (t, a, b) => ((A(a, b) * t + B(a, b)) * t + C(a)) * t;
-    const slope = (t, a, b) => 3 * A(a, b) * t * t + 2 * B(a, b) * t + C(a);
-    return (x) => {
-      if (x <= 0 || x >= 1) return x;
-      let t = x;
-      for (let i = 0; i < 8; i++) { const s = slope(t, x1, x2); if (Math.abs(s) < 1e-6) break; t -= (calc(t, x1, x2) - x) / s; }
-      return calc(clamp(t), y1, y2);
-    };
-  },
-};
-
-// After Effects-style curves (graph editor feel)
-ease.easy = ease.bezier(0.33, 0, 0.67, 1);        // AE "Easy Ease" (33% influence)
-ease.smooth = ease.bezier(0.65, 0, 0.35, 1);      // stronger in/out, motion-design default
-ease.snappy = ease.bezier(0.16, 1, 0.3, 1);       // fast start, long soft landing (≈ expo out)
-ease.anticipate = ease.bezier(0.36, -0.35, 0.3, 1); // tiny pull-back before moving
-
-/**
- * Physical spring, analytic (deterministic). Returns 0→1 with overshoot for
- * seconds `dt` since the spring was released (negative dt → 0).
- * Lower damping = more bounce. stiffness 170 / damping 26 is a crisp UI spring.
- */
-export function spring(dt, { stiffness = 170, damping = 20, mass = 1 } = {}) {
-  if (dt <= 0) return 0;
-  const w0 = Math.sqrt(stiffness / mass), zeta = damping / (2 * Math.sqrt(stiffness * mass));
-  if (zeta < 1) {
-    const wd = w0 * Math.sqrt(1 - zeta * zeta);
-    return 1 - Math.exp(-zeta * w0 * dt) * (Math.cos(wd * dt) + ((zeta * w0) / wd) * Math.sin(wd * dt));
-  }
-  return 1 - Math.exp(-w0 * dt) * (1 + w0 * dt);
-}
-
+/* Helpers (core.js: math, easing, springs, noise, color, text, shapes) */
 /* ------------------------------------------------------------------ */
-/* Randomness and noise (seeded, deterministic)                        */
-/* ------------------------------------------------------------------ */
-
-export function rng(seed = 1) {
-  let a = typeof seed === 'string' ? [...seed].reduce((h, c) => Math.imul(h ^ c.charCodeAt(0), 16777619), 2166136261) : seed >>> 0;
-  const next = () => {
-    a |= 0; a = (a + 0x6d2b79f5) | 0;
-    let t = Math.imul(a ^ (a >>> 15), 1 | a);
-    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-  return {
-    next,
-    range: (lo, hi) => lo + (hi - lo) * next(),
-    int: (lo, hi) => Math.floor(lo + (hi - lo + 1) * next()),
-    pick: (arr) => arr[Math.floor(next() * arr.length)],
-    sign: () => (next() < 0.5 ? -1 : 1),
-  };
-}
-
-const hash3 = (x, y, z) => {
-  let h = Math.imul(x, 374761393) ^ Math.imul(y, 668265263) ^ Math.imul(z, 2147483647);
-  h = Math.imul(h ^ (h >>> 13), 1274126177);
-  return ((h ^ (h >>> 16)) >>> 0) / 4294967295;
-};
-/** Smooth 3D value noise in 0..1. noise(x), noise(x, y), noise(x, y, z). */
-export function noise(x, y = 0, z = 0) {
-  const xi = Math.floor(x), yi = Math.floor(y), zi = Math.floor(z);
-  const xf = x - xi, yf = y - yi, zf = z - zi;
-  const u = xf * xf * (3 - 2 * xf), v = yf * yf * (3 - 2 * yf), w = zf * zf * (3 - 2 * zf);
-  const n = (a, b, c) => hash3(xi + a, yi + b, zi + c);
-  const x00 = lerp(n(0, 0, 0), n(1, 0, 0), u), x10 = lerp(n(0, 1, 0), n(1, 1, 0), u);
-  const x01 = lerp(n(0, 0, 1), n(1, 0, 1), u), x11 = lerp(n(0, 1, 1), n(1, 1, 1), u);
-  return lerp(lerp(x00, x10, v), lerp(x01, x11, v), w);
-}
-/** Fractal noise (octaves of value noise), 0..1. */
-export function fbm(x, y = 0, z = 0, octaves = 4) {
-  let s = 0, amp = 0.5, f = 1, norm = 0;
-  for (let i = 0; i < octaves; i++) { s += amp * noise(x * f, y * f, z * f); norm += amp; amp *= 0.5; f *= 2; }
-  return s / norm;
-}
 
-/* ------------------------------------------------------------------ */
-/* Color (OKLab mixing)                                                */
-/* ------------------------------------------------------------------ */
-
-function hexToRgb(hex) {
-  let h = hex.replace('#', '');
-  if (h.length <= 4) h = [...h].map((c) => c + c).join('');
-  const n = parseInt(h.slice(0, 6), 16);
-  const a = h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1;
-  return [(n >> 16) & 255, (n >> 8) & 255, n & 255, a];
-}
-const toLin = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
-const toSrgb = (c) => Math.round(255 * clamp(c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055));
-function rgbToOklab([r, g, b]) {
-  r = toLin(r); g = toLin(g); b = toLin(b);
-  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
-  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
-  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
-  return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s];
-}
-function oklabToRgb([L, A, B]) {
-  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3;
-  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3;
-  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3;
-  return [toSrgb(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s), toSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s), toSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)];
-}
-/** Perceptual color mix of two hex colors -> hex. */
-export function mixColor(a, b, p) {
-  const A = hexToRgb(a), B = hexToRgb(b);
-  const [r, g, bl] = oklabToRgb(mix(rgbToOklab(A), rgbToOklab(B), p));
-  const al = lerp(A[3], B[3], p);
-  const hx = (n) => n.toString(16).padStart(2, '0');
-  return `#${hx(r)}${hx(g)}${hx(bl)}${al < 1 ? hx(Math.round(al * 255)) : ''}`;
-}
-
-/* ------------------------------------------------------------------ */
-/* Typography                                                          */
-/* ------------------------------------------------------------------ */
-
-/** Wrap each word or char of an element in spans for staggered motion. Returns the spans. */
-export function split(el, by = 'chars') {
-  el = resolveEl(el);
-  const text = el.textContent;
-  el.textContent = '';
-  el.setAttribute('aria-label', text);
-  const out = [];
-  const words = text.split(/(\s+)/);
-  for (const w of words) {
-    if (/^\s+$/.test(w)) { el.appendChild(document.createTextNode(w)); continue; }
-    const ws = document.createElement('span');
-    ws.style.display = 'inline-block';
-    ws.style.whiteSpace = 'pre';
-    if (by === 'words') { ws.textContent = w; out.push(ws); }
-    else for (const ch of w) { const c = document.createElement('span'); c.style.display = 'inline-block'; c.textContent = ch; ws.appendChild(c); out.push(c); }
-    el.appendChild(ws);
-  }
-  return out;
-}
-
-/* ------------------------------------------------------------------ */
-/* Shapes                                                              */
-/* ------------------------------------------------------------------ */
-
-/**
- * SVG path `d` for a hand-cut rounded rectangle: the "organic" shape language.
- * Deterministic for a given seed, so a shape keeps its edges across frames and renders.
- * @param {number} w,h          size in px
- * @param {object} [o]
- * @param {number} [o.radius]   corner radius in px (default 24)
- * @param {number} [o.wobble]   edge irregularity in px (default 0.6% of the short side; keep it low)
- * @param {number} [o.seed]     changes the irregularity, not its amount
- */
-export function organicPath(w, h, { radius = 24, wobble, seed = 1 } = {}) {
-  const amp = wobble ?? Math.min(w, h) * 0.014;
-  // draw on a box inset by the wobble, so the shape never leaves w×h (and never gets clipped flat)
-  const W0 = w, H0 = h; w -= amp * 2; h -= amp * 2;
-  const r = Math.min(radius, w / 2, h / 2);
-  const per = 2 * (w + h - 4 * r) + 2 * Math.PI * r;
-  const n = Math.max(16, Math.round(per / 40));
-  const pt = (d) => {
-    // walk the rounded-rect perimeter clockwise from the top-left corner's end
-    const segs = [[w - 2 * r, 'top'], [Math.PI * r / 2, 'tr'], [h - 2 * r, 'right'], [Math.PI * r / 2, 'br'], [w - 2 * r, 'bottom'], [Math.PI * r / 2, 'bl'], [h - 2 * r, 'left'], [Math.PI * r / 2, 'tl']];
-    for (const [len, k] of segs) {
-      if (d > len) { d -= len; continue; }
-      const a = r ? d / r : 0;
-      switch (k) {
-        case 'top': return [r + d, 0, 0, -1];
-        case 'tr': return [w - r + r * Math.sin(a), r - r * Math.cos(a), Math.sin(a), -Math.cos(a)];
-        case 'right': return [w, r + d, 1, 0];
-        case 'br': return [w - r + r * Math.cos(a), h - r + r * Math.sin(a), Math.cos(a), Math.sin(a)];
-        case 'bottom': return [w - r - d, h, 0, 1];
-        case 'bl': return [r - r * Math.sin(a), h - r + r * Math.cos(a), -Math.sin(a), Math.cos(a)];
-        case 'left': return [0, h - r - d, -1, 0];
-        default: return [r - r * Math.cos(a), r - r * Math.sin(a), -Math.cos(a), -Math.sin(a)];
-      }
-    }
-    return [r, 0, 0, -1];
-  };
-  const P = Array.from({ length: n }, (_, i) => {
-    const [x, y, nx, ny] = pt((i / n) * per);
-    const o = amp * (noise(i * 0.55, seed * 7.13) * 2 - 1);
-    return [x + nx * o + amp, y + ny * o + amp];
-  });
-  void W0; void H0;
-  // closed Catmull-Rom through the points, as cubic Béziers
-  let d = `M${P[0][0].toFixed(2)},${P[0][1].toFixed(2)}`;
-  for (let i = 0; i < n; i++) {
-    const p0 = P[(i - 1 + n) % n], p1 = P[i], p2 = P[(i + 1) % n], p3 = P[(i + 2) % n];
-    const c1 = [p1[0] + (p2[0] - p0[0]) / 6, p1[1] + (p2[1] - p0[1]) / 6];
-    const c2 = [p2[0] - (p3[0] - p1[0]) / 6, p2[1] - (p3[1] - p1[1]) / 6];
-    d += `C${c1[0].toFixed(2)},${c1[1].toFixed(2)} ${c2[0].toFixed(2)},${c2[1].toFixed(2)} ${p2[0].toFixed(2)},${p2[1].toFixed(2)}`;
-  }
-  return d + 'Z';
-}
+export * from './core.js';
+import { clamp, lerp, invlerp, progress, ease, keys, mix, mixColor, spring, rng, noise, split } from './core.js';
 
 /* ------------------------------------------------------------------ */
 /* Live shaders (web pages, not scenes)                                */

package/runtime/kit.js

@@ -0,0 +1,98 @@
+// paper-motion/kit: the small helpers the moves share (geometry, springs, effect layers, live copies).
+// A move copied into a project with `pamo add` imports them from here, so the copy stays short and editable.
+import { ease, clamp, lerp, progress, spring, split } from './core.js';
+
+export const E = (p, curve = ease.inOutCubic) => curve(clamp(p));
+
+export const words = (el) => {
+  if (!el._pmWords) {
+    // keep <br> line breaks: split each text run into words, leave the breaks where they were
+    const parts = [...el.childNodes].flatMap((n) => (n.nodeName === 'BR' ? ['\n'] : (n.textContent ?? '').split(/(\s+)/)));
+    el.textContent = '';
+    el._pmWords = parts.map((w) => {
+      if (w === '\n') { el.append(document.createElement('br')); return null; }
+      if (!w) return null;
+      if (/^\s+$/.test(w)) { el.append(w); return null; }
+      const outer = Object.assign(document.createElement('span'), { style: 'display:inline-block;overflow:hidden;vertical-align:bottom;padding-bottom:0.08em;margin-bottom:-0.08em' });
+      const inner = Object.assign(document.createElement('span'), { textContent: w, style: 'display:inline-block' });
+      outer.append(inner); el.append(outer);
+      return inner;
+    }).filter(Boolean);
+  }
+  return el._pmWords;
+};
+
+export const chars = (el) => (el._labChars ??= split(el, 'chars'));
+
+export const hash = (a, b) => { const x = Math.sin(a * 12.9898 + b * 78.233) * 43758.5453; return x - Math.floor(x); };
+
+// integer edges: half-pixel edges of neighbouring rects leave faint seams
+export const rects = (list) => list.map(([x, y, w, h]) => { const x0 = Math.floor(x), y0 = Math.floor(y), x1 = Math.ceil(x + w), y1 = Math.ceil(y + h); return `M${x0} ${y0}H${x1}V${y1}H${x0}Z`; }).join('');
+
+export const clipTo = (el, d) => { const v = d ? `path('${d}')` : 'inset(100%)'; el.style.clipPath = v; el.style.webkitClipPath = v; };
+
+export const size = (a, b) => [a.offsetWidth || b.offsetWidth, a.offsetHeight || b.offsetHeight];
+
+/** A horizontal-only blur (an SVG filter shared per id), for motion blur on fast pushes. */
+export function hblur(id, std) {
+  let f = document.getElementById(id);
+  if (!f) {
+    const NS = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(NS, 'svg');
+    svg.setAttribute('width', 0); svg.setAttribute('height', 0); svg.style.position = 'absolute';
+    svg.innerHTML = `<filter id="${id}" x="-30%" y="0" width="160%" height="100%" color-interpolation-filters="sRGB"><feGaussianBlur stdDeviation="0 0"/></filter>`;
+    document.body.append(svg);
+    f = svg.querySelector('filter');
+  }
+  f.firstElementChild.setAttribute('stdDeviation', `${std} 0`);
+  return `url(#${id})`;
+}
+
+export const dims = (el) => [el.offsetWidth, el.offsetHeight];
+
+/** Children that are content (not effect layers added by these moves). */
+export const items = (el) => [...el.children].filter((c) => !c.classList.contains('pm-fx'));
+
+export const show = (a, b, p) => { a.style.opacity = p >= 1 ? 0 : 1; b.style.opacity = p > 0 ? 1 : 0; };
+
+/** A spring released at progress `start`, in the transition's seconds. */
+export const sp = (p, start, duration, o = {}) => spring((p - start) * duration, { stiffness: 200, damping: 18, ...o });
+
+/** Eases any value onto 1 over the last stretch, so a spring lands exactly at p = 1. */
+export const settle = (v, p, from = 0.85) => lerp(v, 1, progress(p, from, 1));
+
+export const blur = (px) => (px > 0.3 ? `blur(${px}px)` : 'none');
+
+export const orig = (el, prop) => ((el._pmOrig ??= {})[prop] ??= { inline: el.style[prop], computed: getComputedStyle(el)[prop] });
+
+export const rgba = (c) => { const v = (c.match(/[\d.]+/g) ?? ['0', '0', '0', '0']).map(Number); return [v[0], v[1], v[2], v[3] ?? 1]; };
+
+export const mixRgba = (c1, c2, q) => { const x = rgba(c1), y = rgba(c2); return `rgba(${[0, 1, 2].map((i) => Math.round(lerp(x[i], y[i], q))).join(',')},${lerp(x[3], y[3], q)})`; };
+
+/** Layout rect of `el` relative to `root` (transforms ignored, so it is stable while things move). */
+export function rectIn(el, root) { let x = 0, y = 0, n = el; while (n && n !== root) { x += n.offsetLeft; y += n.offsetTop; n = n.offsetParent; } return { x, y, w: el.offsetWidth, h: el.offsetHeight }; }
+
+export const lerpRect = (r1, r2, q) => ({ x: lerp(r1.x, r2.x, q), y: lerp(r1.y, r2.y, q), w: lerp(r1.w, r2.w, q), h: lerp(r1.h, r2.h, q) });
+
+/** An effect layer owned by `host`, made once and restyled every frame. */
+export function layer(host, key, css) {
+  const k = `_pmFx_${key}`;
+  let d = host[k];
+  if (!d) { d = host[k] = document.createElement('div'); d.className = 'pm-fx'; host.append(d); }
+  d.style.cssText = `position:absolute;pointer-events:none;${css}`;
+  return d;
+}
+
+export const hide = (host, ...keys) => { for (const k of keys) { const d = host[`_pmFx_${k}`]; if (d) d.style.display = 'none'; } };
+
+export const resetAll = (...els) => { for (const e of els) for (const k of ['transform', 'opacity', 'filter', 'clipPath', 'transformOrigin']) e.style[k] = ''; };
+
+/** Live copies of `el` drawn into `host` (for moves that cut a component into pieces). */
+export function copy(el) {
+  const c = el.cloneNode(true);
+  c.querySelectorAll('.pm-fx').forEach((x) => x.remove());
+  Object.assign(c.style, { position: 'absolute', left: '0', top: '0', right: 'auto', bottom: 'auto', width: `${el.offsetWidth}px`, height: `${el.offsetHeight}px`, margin: '0', transform: 'none', opacity: '1', clipPath: 'none', filter: 'none', zIndex: 'auto' });
+  return c;
+}
+
+export const partsOf = (el) => new Map([...el.querySelectorAll('[data-part]')].map((e) => [e.dataset.part, e]));

package/runtime/moves/bar-reveal.js

@@ -0,0 +1,19 @@
+import { ease, progress } from '../core.js';
+
+/** A solid bar grows over the line, then pulls away to the other side, leaving the text behind it. */
+export function barReveal(el, t, { start = 0, duration = 0.8, color = '#fff', curve = ease.inOutQuart } = {}) {
+  if (!el._labBar) {
+    const content = document.createElement('span');
+    content.append(...el.childNodes);
+    const bar = document.createElement('span');
+    Object.assign(bar.style, { position: 'absolute', inset: '0.06em -0.04em', background: color });
+    el.style.position = 'relative'; el.style.display = 'inline-block';
+    el.append(content, bar);
+    el._labBar = { content, bar };
+  }
+  const { content, bar } = el._labBar, half = start + duration / 2;
+  const a = curve(progress(t, start, half)), b = curve(progress(t, half, start + duration));
+  bar.style.transformOrigin = t < half ? '0 50%' : '100% 50%';
+  bar.style.transform = `scaleX(${t < half ? a : 1 - b})`;
+  content.style.opacity = t >= half ? 1 : 0;
+}

package/runtime/moves/blur-in.js

@@ -0,0 +1,7 @@
+import { ease, progress } from '../core.js';
+
+/** Text comes into focus from a blur. */
+export function blurIn(el, t, { start = 0, duration = 0.8, blur = 14, curve = ease.outCubic } = {}) {
+  const q = curve(progress(t, start, start + duration));
+  el.style.filter = `blur(${(1 - q) * blur}px)`; el.style.opacity = q;
+}