@andresclua/perlindom 0.0.6 → 0.1.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.1.0] - 2026-11-07
+
+### Added
+- **`amplitude` option and property**: scales movement strength, clamped to [0, 1] (1 = free drift, 0 = pinned to the target or the base position); non-number values are treated as 1, no string/null coercion
+- **`reset()` method**: rewinds the noise path to the seed and returns the element to its own transform, keeping play/pause, `amplitude` and `target`; a no-op after `destroy()`
+- **`legacyNoise` option** (default `false`): `true` restores the pre-0.0.7 noise rows
+- **`pauseOffscreen` option** (default `true`): `false` keeps an instance stepping while offscreen
+- **`target` option and `setTarget`**: `target` is a `{x, y}` offset in px from the element's base position that `amplitude` pulls toward (amplitude 0 pins the element at the target); `setTarget` copies the object and turns non-finite coordinates into 0
+
+### Changed
+- **Noise sampling (behavior change)**: the two axes are now sampled at rows 0.5 and 100.5 instead of 0 and 100, where Perlin noise is flat on the lattice. Movement now reaches roughly ±1 of the range instead of ±0.5, and no longer sits nearly still at the start for some seeds (seed 42 used to take ~3.7 s). Pass `legacyNoise: true` to keep the previous movement exactly
+- **Shared loop**: all instances now share a single `requestAnimationFrame` loop
+- **Offscreen pause**: instances pause while their element's parent is outside the viewport (the parent, so an element's own drift cannot freeze it); changing `amplitude` or `target` still renders while paused
+- **Build output**: `dist` files are now `perlindom.es.js` and `perlindom.umd.js` (lowercase), matching `package.json` and `vite.config.js`; the entry path casing was fixed for case-sensitive filesystems
+
+### Removed
+- Internal instance fields `animate` and `raf` (undocumented; replaced by the shared loop)
+
 ## [0.0.6] - 2025-02-09
 
 ## Changed

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrés Clúa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/perlindom.es.js

@@ -0,0 +1,212 @@
+var C = (i) => {
+  throw TypeError(i);
+};
+var I = (i, t, e) => t.has(i) || C("Cannot " + e);
+var M = (i, t, e) => (I(i, t, "read from private field"), e ? e.call(i) : t.get(i)), B = (i, t, e) => t.has(i) ? C("Cannot add the same private member more than once") : t instanceof WeakSet ? t.add(i) : t.set(i, e), D = (i, t, e, s) => (I(i, t, "write to private field"), s ? s.call(i, e) : t.set(i, e), e), h = (i, t, e) => (I(i, t, "access private method"), e);
+const w = /* @__PURE__ */ new Set();
+let v = null;
+function G() {
+  v = null;
+  for (const i of [...w])
+    w.has(i) && (!i.onScreen && !i._dirty || (i._dirty = !1, i.step() === !1 && w.delete(i)));
+  w.size > 0 && v === null && (v = requestAnimationFrame(G));
+}
+function $(i) {
+  w.add(i), v === null && (v = requestAnimationFrame(G));
+}
+function Z(i) {
+  w.delete(i), w.size === 0 && v !== null && (cancelAnimationFrame(v), v = null);
+}
+const z = /* @__PURE__ */ new Map(), Y = /* @__PURE__ */ new WeakMap();
+let O = null;
+function V(i) {
+  if (typeof IntersectionObserver > "u" || !i.el || !i.pauseOffscreen || Y.has(i)) return;
+  O ?? (O = new IntersectionObserver((s) => {
+    for (const r of s) {
+      const a = z.get(r.target);
+      if (a) {
+        a.visible = r.isIntersecting;
+        for (const n of a.insts) n.onScreen = r.isIntersecting;
+      }
+    }
+  }));
+  const t = i.el.parentElement || i.el;
+  let e = z.get(t);
+  e || (e = { visible: !0, insts: /* @__PURE__ */ new Set() }, z.set(t, e), O.observe(t)), e.insts.add(i), Y.set(i, t), i.onScreen = e.visible;
+}
+function _(i) {
+  const t = Y.get(i);
+  if (!t) return;
+  Y.delete(i);
+  const e = z.get(t);
+  e && (e.insts.delete(i), e.insts.size === 0 && (z.delete(t), O.unobserve(t)));
+}
+var F, l, J, K, y, L, c, Q, U, S, X, E;
+const f = class f {
+  constructor({
+    element: t,
+    x: e = null,
+    y: s = null,
+    speed: r = 0.01,
+    seed: a = 0,
+    lerpSpeed: n = 0.1,
+    preserveBaseTranslation: o = !1,
+    // <-- si querés mantener la traslación base
+    amplitude: u = 1,
+    target: m = null,
+    // {x, y} en px, offset desde la posición base
+    legacyNoise: g = !1,
+    // true = sample noise at y=0/100 like <=0.0.6 (flat spots on one axis)
+    pauseOffscreen: R = !0
+    // false = keep stepping even when the parent box is out of view
+  }) {
+    B(this, c);
+    B(this, F, 1);
+    var b, x, T, d;
+    if (this._dirty = !1, this.pauseOffscreen = R !== !1, this._ny = g ? [0, 100] : [0.5, 100.5], this.amplitude = u, this.setTarget(m), this.el = t, this.xRange = e, this.yRange = s, this.speed = r, this.seed = a, this.time = a, this.isPlaying = !0, this.lerpFactor = 1, this.lerpSpeed = n, this.targetLerpFactor = 1, this.lastX = 0, this.lastY = 0, this.preserveBaseTranslation = o, this.hasPercentages = !!(e && (h(b = f, l, y).call(b, e.min) || h(x = f, l, y).call(x, e.max)) || s && (h(T = f, l, y).call(T, s.min) || h(d = f, l, y).call(d, s.max))), t) {
+      const p = window.getComputedStyle(t);
+      p.position === "static" && (t.style.position = "relative"), this.originalInlineTransform = t.style.transform || "", this.baseTransform = h(this, c, E).call(this, p.transform, this.preserveBaseTranslation), this.hasPercentages && (this.handleResize = this.handleResize.bind(this), window.addEventListener("resize", this.handleResize));
+    } else
+      this.originalInlineTransform = "", this.baseTransform = "";
+    this.onScreen = !0, this.init(a);
+  }
+  init(t) {
+    var e;
+    this._destroyed = !1, this.noise = h(this, c, Q).call(this, h(e = f, l, K).call(e, t)), this.isPlaying = !0, this.lerpFactor = 1, this.targetLerpFactor = 1, V(this), $(this);
+  }
+  // 0 = clavado en target (o 0,0), 1 = deriva libre; siempre clampeado a [0, 1], NaN cuenta como 1
+  get amplitude() {
+    return M(this, F);
+  }
+  set amplitude(t) {
+    const e = typeof t == "number" && !Number.isNaN(t) ? Math.min(1, Math.max(0, t)) : 1;
+    e !== M(this, F) && (this._dirty = !0), D(this, F, e);
+  }
+  setTarget(t) {
+    const e = this.target;
+    if (t === null || typeof t != "object")
+      this.target = null;
+    else {
+      const r = (a) => typeof a == "number" && Number.isFinite(a) ? a : 0;
+      this.target = { x: r(t.x), y: r(t.y) };
+    }
+    const s = this.target;
+    ((e == null ? void 0 : e.x) !== (s == null ? void 0 : s.x) || (e == null ? void 0 : e.y) !== (s == null ? void 0 : s.y)) && (this._dirty = !0);
+  }
+  // Permite refrescar el transform base si cambian clases/estilos en runtime
+  refreshBaseTransform(t = this.preserveBaseTranslation) {
+    if (!this.el) return;
+    const e = window.getComputedStyle(this.el);
+    this.baseTransform = h(this, c, E).call(this, e.transform, t);
+  }
+  // Handle window resize for percentage-based values
+  handleResize() {
+  }
+  pause() {
+    this.isPlaying && (this.targetLerpFactor = 0, this.isPlaying = !1);
+  }
+  play() {
+    this.isPlaying || (this.targetLerpFactor = 1, this.isPlaying = !0, this.lerpFactor === 0 && $(this));
+  }
+  // Un frame de este instance; devuelve false cuando queda totalmente pausado
+  step() {
+    var t, e, s, r, a, n, o, u, m, g, R, b;
+    if (this.lerpFactor !== this.targetLerpFactor && (this.lerpFactor = h(this, c, U).call(this, this.lerpFactor, this.targetLerpFactor, this.lerpSpeed), Math.abs(this.lerpFactor - this.targetLerpFactor) < 1e-3 && (this.lerpFactor = this.targetLerpFactor)), this.lerpFactor > 0) {
+      this.time += this.speed * this.lerpFactor;
+      const x = this.noise.perlin2(this.time, this._ny[0]), T = this.noise.perlin2(this.time, this._ny[1]);
+      if (this.el) {
+        let d, p, P, A;
+        if (this.hasPercentages) {
+          const j = this.el.parentElement || document.body, k = j.clientWidth, q = j.clientHeight;
+          this.xRange && (d = h(t = f, l, y).call(t, this.xRange.min) ? h(e = f, l, L).call(e, this.xRange.min, k) : this.xRange.min, p = h(s = f, l, y).call(s, this.xRange.max) ? h(r = f, l, L).call(r, this.xRange.max, k) : this.xRange.max), this.yRange && (P = h(a = f, l, y).call(a, this.yRange.min) ? h(n = f, l, L).call(n, this.yRange.min, q) : this.yRange.min, A = h(o = f, l, y).call(o, this.yRange.max) ? h(u = f, l, L).call(u, this.yRange.max, q) : this.yRange.max);
+        } else
+          d = (m = this.xRange) == null ? void 0 : m.min, p = (g = this.xRange) == null ? void 0 : g.max, P = (R = this.yRange) == null ? void 0 : R.min, A = (b = this.yRange) == null ? void 0 : b.max;
+        const N = h(this, c, S).call(this, this.xRange ? h(this, c, X).call(this, x, -1, 1, d, p) : 0, "x"), W = h(this, c, S).call(this, this.yRange ? h(this, c, X).call(this, T, -1, 1, P, A) : 0, "y");
+        this.lastX = N, this.lastY = W, this.el.style.transform = `translate3d(${N}px, ${W}px, 0) ${this.baseTransform}`.trim();
+      } else {
+        const d = h(this, c, S).call(this, this.xRange ? h(this, c, X).call(this, x, -1, 1, this.xRange.min, this.xRange.max) : 0, "x"), p = h(this, c, S).call(this, this.yRange ? h(this, c, X).call(this, T, -1, 1, this.yRange.min, this.yRange.max) : 0, "y");
+        this.lastX = d, this.lastY = p;
+      }
+    }
+    return this.lerpFactor > 0 || this.targetLerpFactor > 0;
+  }
+  // Back to the starting state, as if just created: the noise path rewinds to its seed and the
+  // element returns to its own transform (no drift). Keeps play/pause, amplitude and target.
+  reset() {
+    this._destroyed || (this.time = this.seed, this.lastX = 0, this.lastY = 0, this.el && (this.el.style.transform = this.originalInlineTransform || ""), this.isPlaying && $(this));
+  }
+  destroy() {
+    this._destroyed = !0, Z(this), _(this), this.el && (this.el.style.transform = this.originalInlineTransform || ""), this.hasPercentages && window.removeEventListener("resize", this.handleResize);
+  }
+};
+F = new WeakMap(), l = new WeakSet(), J = function(t) {
+  return function() {
+    let e = t += 1831565813;
+    return e = Math.imul(e ^ e >>> 15, e | 1), e ^= e + Math.imul(e ^ e >>> 7, e | 61), ((e ^ e >>> 14) >>> 0) / 4294967296;
+  };
+}, K = function(t = 0) {
+  var r;
+  const e = Array.from({ length: 256 }, (a, n) => n), s = h(r = f, l, J).call(r, t);
+  for (let a = 255; a > 0; a--) {
+    const n = Math.floor(s() * (a + 1));
+    [e[a], e[n]] = [e[n], e[a]];
+  }
+  return e.concat(e);
+}, y = function(t) {
+  return typeof t == "string" && t.endsWith("%");
+}, L = function(t, e) {
+  var r;
+  return h(r = f, l, y).call(r, t) ? parseFloat(t) / 100 * e : t;
+}, c = new WeakSet(), Q = function(t) {
+  const e = (n) => n * n * n * (n * (n * 6 - 15) + 10), s = (n, o, u) => o + n * (u - o), r = (n, o, u) => {
+    const m = n & 15, g = m < 8 ? o : u, R = m < 4 ? u : m === 12 || m === 14 ? o : 0;
+    return (m & 1 ? -g : g) + (m & 2 ? -R : R);
+  }, a = (n, o) => n & 1 ? -o : o;
+  return {
+    // Original 1D Perlin noise function
+    perlin1(n) {
+      const o = Math.floor(n) & 255;
+      n -= Math.floor(n);
+      const u = e(n);
+      return s(u, a(t[o], n), a(t[o + 1], n - 1));
+    },
+    // New 2D Perlin noise function
+    perlin2(n, o) {
+      const u = Math.floor(n) & 255, m = Math.floor(o) & 255;
+      n -= Math.floor(n), o -= Math.floor(o);
+      const g = e(n), R = e(o), b = t[u] + m, x = t[u + 1] + m, T = t[b], d = t[b + 1], p = t[x], P = t[x + 1];
+      return s(
+        R,
+        s(g, r(t[T], n, o), r(t[p], n - 1, o)),
+        s(g, r(t[d], n, o - 1), r(t[P], n - 1, o - 1))
+      );
+    }
+  };
+}, U = function(t, e, s) {
+  return t + s * (e - t);
+}, // target + (noise - target) * amplitude; amplitude 1 returns noise untouched (exact legacy values)
+S = function(t, e) {
+  var r;
+  if (M(this, F) === 1) return t;
+  const s = ((r = this.target) == null ? void 0 : r[e]) ?? 0;
+  return s + (t - s) * M(this, F);
+}, X = function(t, e, s, r, a) {
+  return (t - e) * (a - r) / (s - e) + r;
+}, // Quita o preserva la traslación del transform base en 2D según flag
+E = function(t, e = !1) {
+  if (!t || t === "none") return "";
+  try {
+    const s = new DOMMatrixReadOnly(t);
+    if (s.is2D) {
+      const r = e ? s.e : 0, a = e ? s.f : 0;
+      return `matrix(${s.a}, ${s.b}, ${s.c}, ${s.d}, ${r}, ${a})`;
+    } else
+      return t;
+  } catch {
+    return t;
+  }
+}, B(f, l);
+let H = f;
+export {
+  H as default
+};

package/dist/perlindom.umd.js

@@ -0,0 +1 @@
+(function(r,o){typeof exports=="object"&&typeof module<"u"?module.exports=o():typeof define=="function"&&define.amd?define(o):(r=typeof globalThis<"u"?globalThis:r||self,r.PerlinDOM=o())})(this,function(){"use strict";var H=r=>{throw TypeError(r)};var N=(r,o,d)=>o.has(r)||H("Cannot "+d);var X=(r,o,d)=>(N(r,o,"read from private field"),d?d.call(r):o.get(r)),I=(r,o,d)=>o.has(r)?H("Cannot add the same private member more than once"):o instanceof WeakSet?o.add(r):o.set(r,d),G=(r,o,d,M)=>(N(r,o,"write to private field"),M?M.call(r,d):o.set(r,d),d),h=(r,o,d)=>(N(r,o,"access private method"),d);var v,f,J,K,x,z,u,Q,U,B,Y,W;const r=new Set;let o=null;function d(){o=null;for(const c of[...r])r.has(c)&&(!c.onScreen&&!c._dirty||(c._dirty=!1,c.step()===!1&&r.delete(c)));r.size>0&&o===null&&(o=requestAnimationFrame(d))}function M(c){r.add(c),o===null&&(o=requestAnimationFrame(d))}function Z(c){r.delete(c),r.size===0&&o!==null&&(cancelAnimationFrame(o),o=null)}const L=new Map,A=new WeakMap;let $=null;function V(c){if(typeof IntersectionObserver>"u"||!c.el||!c.pauseOffscreen||A.has(c))return;$??($=new IntersectionObserver(s=>{for(const n of s){const a=L.get(n.target);if(a){a.visible=n.isIntersecting;for(const i of a.insts)i.onScreen=n.isIntersecting}}}));const t=c.el.parentElement||c.el;let e=L.get(t);e||(e={visible:!0,insts:new Set},L.set(t,e),$.observe(t)),e.insts.add(c),A.set(c,t),c.onScreen=e.visible}function _(c){const t=A.get(c);if(!t)return;A.delete(c);const e=L.get(t);e&&(e.insts.delete(c),e.insts.size===0&&(L.delete(t),$.unobserve(t)))}const m=class m{constructor({element:t,x:e=null,y:s=null,speed:n=.01,seed:a=0,lerpSpeed:i=.1,preserveBaseTranslation:l=!1,amplitude:g=1,target:p=null,legacyNoise:y=!1,pauseOffscreen:F=!0}){I(this,u);I(this,v,1);var T,w,P,R;if(this._dirty=!1,this.pauseOffscreen=F!==!1,this._ny=y?[0,100]:[.5,100.5],this.amplitude=g,this.setTarget(p),this.el=t,this.xRange=e,this.yRange=s,this.speed=n,this.seed=a,this.time=a,this.isPlaying=!0,this.lerpFactor=1,this.lerpSpeed=i,this.targetLerpFactor=1,this.lastX=0,this.lastY=0,this.preserveBaseTranslation=l,this.hasPercentages=!!(e&&(h(T=m,f,x).call(T,e.min)||h(w=m,f,x).call(w,e.max))||s&&(h(P=m,f,x).call(P,s.min)||h(R=m,f,x).call(R,s.max))),t){const b=window.getComputedStyle(t);b.position==="static"&&(t.style.position="relative"),this.originalInlineTransform=t.style.transform||"",this.baseTransform=h(this,u,W).call(this,b.transform,this.preserveBaseTranslation),this.hasPercentages&&(this.handleResize=this.handleResize.bind(this),window.addEventListener("resize",this.handleResize))}else this.originalInlineTransform="",this.baseTransform="";this.onScreen=!0,this.init(a)}init(t){var e;this._destroyed=!1,this.noise=h(this,u,Q).call(this,h(e=m,f,K).call(e,t)),this.isPlaying=!0,this.lerpFactor=1,this.targetLerpFactor=1,V(this),M(this)}get amplitude(){return X(this,v)}set amplitude(t){const e=typeof t=="number"&&!Number.isNaN(t)?Math.min(1,Math.max(0,t)):1;e!==X(this,v)&&(this._dirty=!0),G(this,v,e)}setTarget(t){const e=this.target;if(t===null||typeof t!="object")this.target=null;else{const n=a=>typeof a=="number"&&Number.isFinite(a)?a:0;this.target={x:n(t.x),y:n(t.y)}}const s=this.target;((e==null?void 0:e.x)!==(s==null?void 0:s.x)||(e==null?void 0:e.y)!==(s==null?void 0:s.y))&&(this._dirty=!0)}refreshBaseTransform(t=this.preserveBaseTranslation){if(!this.el)return;const e=window.getComputedStyle(this.el);this.baseTransform=h(this,u,W).call(this,e.transform,t)}handleResize(){}pause(){this.isPlaying&&(this.targetLerpFactor=0,this.isPlaying=!1)}play(){this.isPlaying||(this.targetLerpFactor=1,this.isPlaying=!0,this.lerpFactor===0&&M(this))}step(){var t,e,s,n,a,i,l,g,p,y,F,T;if(this.lerpFactor!==this.targetLerpFactor&&(this.lerpFactor=h(this,u,U).call(this,this.lerpFactor,this.targetLerpFactor,this.lerpSpeed),Math.abs(this.lerpFactor-this.targetLerpFactor)<.001&&(this.lerpFactor=this.targetLerpFactor)),this.lerpFactor>0){this.time+=this.speed*this.lerpFactor;const w=this.noise.perlin2(this.time,this._ny[0]),P=this.noise.perlin2(this.time,this._ny[1]);if(this.el){let R,b,S,E;if(this.hasPercentages){const k=this.el.parentElement||document.body,q=k.clientWidth,C=k.clientHeight;this.xRange&&(R=h(t=m,f,x).call(t,this.xRange.min)?h(e=m,f,z).call(e,this.xRange.min,q):this.xRange.min,b=h(s=m,f,x).call(s,this.xRange.max)?h(n=m,f,z).call(n,this.xRange.max,q):this.xRange.max),this.yRange&&(S=h(a=m,f,x).call(a,this.yRange.min)?h(i=m,f,z).call(i,this.yRange.min,C):this.yRange.min,E=h(l=m,f,x).call(l,this.yRange.max)?h(g=m,f,z).call(g,this.yRange.max,C):this.yRange.max)}else R=(p=this.xRange)==null?void 0:p.min,b=(y=this.xRange)==null?void 0:y.max,S=(F=this.yRange)==null?void 0:F.min,E=(T=this.yRange)==null?void 0:T.max;const j=h(this,u,B).call(this,this.xRange?h(this,u,Y).call(this,w,-1,1,R,b):0,"x"),D=h(this,u,B).call(this,this.yRange?h(this,u,Y).call(this,P,-1,1,S,E):0,"y");this.lastX=j,this.lastY=D,this.el.style.transform=`translate3d(${j}px, ${D}px, 0) ${this.baseTransform}`.trim()}else{const R=h(this,u,B).call(this,this.xRange?h(this,u,Y).call(this,w,-1,1,this.xRange.min,this.xRange.max):0,"x"),b=h(this,u,B).call(this,this.yRange?h(this,u,Y).call(this,P,-1,1,this.yRange.min,this.yRange.max):0,"y");this.lastX=R,this.lastY=b}}return this.lerpFactor>0||this.targetLerpFactor>0}reset(){this._destroyed||(this.time=this.seed,this.lastX=0,this.lastY=0,this.el&&(this.el.style.transform=this.originalInlineTransform||""),this.isPlaying&&M(this))}destroy(){this._destroyed=!0,Z(this),_(this),this.el&&(this.el.style.transform=this.originalInlineTransform||""),this.hasPercentages&&window.removeEventListener("resize",this.handleResize)}};v=new WeakMap,f=new WeakSet,J=function(t){return function(){let e=t+=1831565813;return e=Math.imul(e^e>>>15,e|1),e^=e+Math.imul(e^e>>>7,e|61),((e^e>>>14)>>>0)/4294967296}},K=function(t=0){var n;const e=Array.from({length:256},(a,i)=>i),s=h(n=m,f,J).call(n,t);for(let a=255;a>0;a--){const i=Math.floor(s()*(a+1));[e[a],e[i]]=[e[i],e[a]]}return e.concat(e)},x=function(t){return typeof t=="string"&&t.endsWith("%")},z=function(t,e){var n;return h(n=m,f,x).call(n,t)?parseFloat(t)/100*e:t},u=new WeakSet,Q=function(t){const e=i=>i*i*i*(i*(i*6-15)+10),s=(i,l,g)=>l+i*(g-l),n=(i,l,g)=>{const p=i&15,y=p<8?l:g,F=p<4?g:p===12||p===14?l:0;return(p&1?-y:y)+(p&2?-F:F)},a=(i,l)=>i&1?-l:l;return{perlin1(i){const l=Math.floor(i)&255;i-=Math.floor(i);const g=e(i);return s(g,a(t[l],i),a(t[l+1],i-1))},perlin2(i,l){const g=Math.floor(i)&255,p=Math.floor(l)&255;i-=Math.floor(i),l-=Math.floor(l);const y=e(i),F=e(l),T=t[g]+p,w=t[g+1]+p,P=t[T],R=t[T+1],b=t[w],S=t[w+1];return s(F,s(y,n(t[P],i,l),n(t[b],i-1,l)),s(y,n(t[R],i,l-1),n(t[S],i-1,l-1)))}}},U=function(t,e,s){return t+s*(e-t)},B=function(t,e){var n;if(X(this,v)===1)return t;const s=((n=this.target)==null?void 0:n[e])??0;return s+(t-s)*X(this,v)},Y=function(t,e,s,n,a){return(t-e)*(a-n)/(s-e)+n},W=function(t,e=!1){if(!t||t==="none")return"";try{const s=new DOMMatrixReadOnly(t);if(s.is2D){const n=e?s.e:0,a=e?s.f:0;return`matrix(${s.a}, ${s.b}, ${s.c}, ${s.d}, ${n}, ${a})`}else return t}catch{return t}},I(m,f);let O=m;return O});

package/package.json

@@ -1,15 +1,19 @@
 {
     "name": "@andresclua/perlindom",
     "private": false,
-    "version": "0.0.6",
+    "version": "0.1.0",
     "description": "A lightweight JavaScript library for creating smooth, organic animations for DOM elements using Perlin noise",
+    "homepage": "https://perlindom.js.org",
+    "repository": { "type": "git", "url": "git+https://github.com/andresclua/PerlinDOM.git" },
+    "bugs": "https://github.com/andresclua/PerlinDOM/issues",
+    "files": ["dist", "CHANGELOG.md"],
     "type": "module",
-    "main": "./dist/PerlinDOM.umd.js",
-    "module": "./dist/PerlinDOM.es.js",
+    "main": "./dist/perlindom.umd.js",
+    "module": "./dist/perlindom.es.js",
     "exports": {
         ".": {
-            "import": "./dist/PerlinDOM.es.js",
-            "require": "./dist/PerlinDOM.umd.js"
+            "import": "./dist/perlindom.es.js",
+            "require": "./dist/perlindom.umd.js"
         }
     },
     "keywords": [
@@ -24,9 +28,13 @@
     "scripts": {
         "dev": "vite",
         "build": "vite build",
-        "preview": "vite preview"
+        "build:lib": "vite build",
+        "build:site": "vite build --mode site",
+        "preview": "vite preview",
+        "test": "node --test 'tests/*.test.mjs'"
     },
     "devDependencies": {
+        "gsap": "^3.15.1",
         "sass": "^1.80.6",
         "vite": "^5.4.10"
     }

package/readme.md

@@ -12,11 +12,16 @@ A lightweight JavaScript library for creating smooth, organic animations on DOM
 - [Installation](#-installation)
 - [Quick Start](#-quick-start)
 - [Configuration](#-configuration)
+- [Amplitude and target](#-amplitude-and-target)
+- [Use with GSAP + ScrollTrigger](#-use-with-gsap--scrolltrigger)
 - [Examples](#-examples)
 - [Best Practices](#-best-practices)
 - [API Reference](#-api-reference)
 - [Troubleshooting](#-troubleshooting)
 - [Browser Compatibility](#-browser-compatibility)
+- [Live site](#-live-site)
+- [Contributing](#-contributing)
+- [Sponsor](#-sponsor)
 - [Changelog](#-changelog)
 - [License](#-license)
 
@@ -25,7 +30,8 @@ A lightweight JavaScript library for creating smooth, organic animations on DOM
 - **🌊 Organic Animations**: Natural movements using Perlin noise that avoid mechanical rigidity
 - **📱 Responsive Design**: Support for percentage-based values that adapt to container size
 - **🎯 Smart Positioning**: Automatically works from element's current position (CSS or inline styles)
-- **⚡ High Performance**: Uses `transform` and `requestAnimationFrame` for smooth 60fps animations
+- **⚡ High Performance**: Uses `transform` and one shared `requestAnimationFrame` loop for all instances; instances scrolled out of the viewport pause automatically
+- **🧲 Amplitude & Target**: Scale the drift from 0 to 1 and pin elements to a target position, ideal for scroll-driven effects
 - **🎛️ Full Control**: Play, pause, and destroy animations with smooth transitions
 - **📦 Lightweight**: Minimal footprint with zero dependencies
 - **🔧 Easy Integration**: Simple API that works with any DOM element
@@ -62,35 +68,85 @@ const animation = new PerlinDOM({
 // Control the animation
 animation.pause();  // Smooth pause
 animation.play();   // Resume
+animation.reset();  // Rewind to the start (same path again)
 animation.destroy(); // Clean up
 ```
 
-```css
-/* Your element needs positioning for transforms to work */
-.my-element {
-  position: relative; /* or absolute, or fixed */
-  /* PerlinDOM will animate from wherever this element is positioned */
-}
-```
+Instances start playing as soon as they are created. PerlinDOM sets `position: relative` itself if the element is `static`, and animates from wherever the element is laid out.
 
 ## ⚙️ Configuration
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `element` | `HTMLElement` | **required** | The DOM element to animate |
+| `element` | `HTMLElement \| null` | `undefined` | The DOM element to animate. Optional: with `null` only `lastX` / `lastY` are computed |
 | `x` | `Object \| null` | `null` | Horizontal movement: `{min: number, max: number}` |
 | `y` | `Object \| null` | `null` | Vertical movement: `{min: number, max: number}` |
 | `speed` | `number` | `0.01` | Animation speed (lower = slower) |
 | `seed` | `number` | `0` | Seed for reproducible patterns |
 | `lerpSpeed` | `number` | `0.1` | Transition smoothness for pause/play |
+| `preserveBaseTranslation` | `boolean` | `false` | Keep the element's CSS `translate` (e.g. `translate(-50%, -50%)`); by default it is dropped and only scale/rotate/skew are kept |
+| `amplitude` | `number` | `1` | Strength of the drift, clamped to `[0, 1]`; non-numbers become `1`. `1` = free drift, `0` = pinned to `target` (or the base position) |
+| `target` | `{x, y} \| null` | `null` | Offset in px from the element's base position that `amplitude` pulls toward. Coordinates that are not finite numbers become `0` |
+| `legacyNoise` | `boolean` | `false` | `true` keeps the old noise rows (0 / 100) for movement identical to 0.0.6 and earlier |
+| `pauseOffscreen` | `boolean` | `true` | Skip frames while the element's parent is outside the viewport. `false` keeps it running everywhere |
 
 ### Value Types
 
 - **Pixels**: `{ min: -50, max: 50 }` - Fixed pixel movement
-- **Percentages**: `{ min: '-10%', max: '10%' }` - Responsive to parent size
+- **Percentages**: `{ min: '-10%', max: '10%' }` - Relative to the parent's `clientWidth` / `clientHeight` (padding included), re-read every frame. They need an `element` (with `element: null` they produce `NaN`)
 - **Mixed**: `x: { min: '-5%', max: '5%' }, y: { min: -20, max: 20 }`
 - **Single Axis**: Set unused axis to `null`
 
+## 🎚️ Amplitude and Target
+
+`amplitude` scales how far the noise moves the element. `target` is where it settles as `amplitude` goes to `0`: an `{ x, y }` offset in px from the element's base position (the object is copied). Without a `target` the element settles on its base position.
+
+```javascript
+const dot = new PerlinDOM({
+  element: document.querySelector('.dot'),
+  x: { min: -120, max: 120 },
+  y: { min: -120, max: 120 },
+  target: { x: 40, y: -20 }
+});
+
+dot.amplitude = 0.5;               // half the drift, pulled toward the target
+dot.amplitude = 0;                 // pinned at { x: 40, y: -20 }
+dot.setTarget({ x: 0, y: 0 });     // move the target; setTarget(null) removes it
+dot.amplitude = 1;                 // free drift again
+```
+
+## 🎬 Use with GSAP + ScrollTrigger
+
+PerlinDOM owns the element's `transform`, so GSAP must not write `transform` (`x`, `y`, `scale`, ...) on the same element. Tween `amplitude` instead; to move an element with GSAP and drift it too, put PerlinDOM on a wrapper or a child.
+
+```javascript
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+import PerlinDOM from '@andresclua/perlindom';
+
+gsap.registerPlugin(ScrollTrigger);
+
+const shape = [{ x: 0, y: -80 }, { x: 70, y: 40 }, { x: -70, y: 40 }]; // one { x, y } per .dot
+
+const instances = [...document.querySelectorAll('.dot')].map((el, i) =>
+  new PerlinDOM({
+    element: el,
+    x: { min: -120, max: 120 },
+    y: { min: -120, max: 120 },
+    seed: i * 7919,
+    target: shape[i], // { x, y } offsets that draw your shape
+  })
+);
+
+const state = { amplitude: 1 };
+gsap.to(state, {
+  amplitude: 0,
+  ease: 'none',
+  scrollTrigger: { trigger: '.scene', start: 'top top', end: '+=1000', pin: true, scrub: 0.8 },
+  onUpdate: () => instances.forEach(inst => { inst.amplitude = state.amplitude; }),
+});
+```
+
 ## 📚 Examples
 
 ### 1. Basic Element Animation
@@ -104,7 +160,7 @@ animation.destroy(); // Clean up
   position: relative;
   left: 50%;
   top: 50%;
-  transform: translate(-50%, -50%);
+  transform: translate(-50%, -50%); /* centring translate */
 }
 ```
 
@@ -114,7 +170,8 @@ new PerlinDOM({
   x: { min: -20, max: 20 },
   y: { min: -15, max: 15 },
   speed: 0.008,
-  seed: 42
+  seed: 42,
+  preserveBaseTranslation: true // keep the centring translate
 });
 ```
 
@@ -140,13 +197,17 @@ const button = document.querySelector('.animated-button');
 let animation;
 
 button.addEventListener('mouseenter', () => {
-  animation = new PerlinDOM({
-    element: button.querySelector('.effect'),
-    x: { min: -5, max: 5 },
-    y: { min: -5, max: 5 },
-    speed: 0.02,
-    lerpSpeed: 0.15
-  });
+  if (!animation) {
+    animation = new PerlinDOM({
+      element: button.querySelector('.effect'),
+      x: { min: -5, max: 5 },
+      y: { min: -5, max: 5 },
+      speed: 0.02,
+      lerpSpeed: 0.15
+    });
+  } else {
+    animation.play();
+  }
 });
 
 button.addEventListener('mouseleave', () => {
@@ -218,24 +279,24 @@ updatePath();
 
 ### ✅ Do
 
-- **Use CSS for initial positioning**: Position elements with CSS classes rather than inline styles
-- **Set proper positioning**: Ensure elements have `position: relative`, `absolute`, or `fixed`
+- **Position with CSS, not with `translate`**: Use `left`/`top`, margins, grid or flex. A CSS `translate` is dropped unless you pass `preserveBaseTranslation: true`
+- **One instance per element**: Two instances on the same element overwrite each other's transform
 - **Use percentage values for responsive designs**: Great for mobile-friendly animations
 - **Choose appropriate speeds**: Start with `0.01` and adjust based on desired effect
 - **Clean up animations**: Call `destroy()` when removing elements from DOM
 
 ### ❌ Don't
 
-- **Don't rely on inline positioning**: PerlinDOM works from any position, but CSS is cleaner
-- **Don't use on static elements**: Transform won't work without proper positioning
-- **Don't forget to destroy**: Memory leaks can occur if animations aren't cleaned up
-- **Don't use extreme speeds**: Very high speeds can cause jittery animations
+- **Don't tween `transform` with another library on the same element**: PerlinDOM writes it every frame (see the GSAP recipe above)
+- **Don't forget to destroy**: A live instance keeps a reference to its element, so call `destroy()` before removing it
+- **Don't use extreme speeds**: Above about `0.05` the motion turns jittery
+- **Don't forget reduced motion**: PerlinDOM does not check `prefers-reduced-motion`, so skip creating instances when it is set
 
 ### 🎯 Performance Tips
 
 ```javascript
-// Good: Reuse animation instances
-const sharedAnimation = new PerlinDOM({...});
+// Good: Many instances are cheap, they all share one requestAnimationFrame loop
+// and pause on their own while scrolled out of view
 
 // Good: Use percentage values for responsive design
 x: { min: '-5%', max: '5%' }
@@ -252,17 +313,20 @@ animation.destroy();
 ### Constructor
 
 ```javascript
-new PerlinDOM(options)
+new PerlinDOM(options) // options: see Configuration
 ```
 
 ### Methods
 
 | Method | Description | Returns |
 |--------|-------------|---------|
-| `play()` | Start or resume animation | `void` |
+| `play()` | Resume after `pause()` (instances start playing on construction) | `void` |
 | `pause()` | Smoothly pause animation | `void` |
-| `destroy()` | Stop animation and clean up resources | `void` |
-| `init(seed?)` | Reinitialize with optional new seed | `void` |
+| `reset()` | Back to the starting state: the noise path rewinds to the seed and the element returns to its own transform. Keeps play/pause, `amplitude` and `target`; does nothing after `destroy()` | `void` |
+| `destroy()` | Stop animation, restore the original inline `transform` and clean up | `void` |
+| `init(seed?)` | Rebuild the noise from `seed` (without an argument: seed `0`, not the constructed seed; `time` is not reset) and restart playback, also after `destroy()` | `void` |
+| `setTarget({x, y} \| null)` | Set the target offset in px; non-finite coordinates become `0`, the object is copied, `null` removes it | `void` |
+| `refreshBaseTransform(preserveTranslation?)` | Re-read the element's CSS transform after classes or styles changed | `void` |
 
 ### Properties
 
@@ -273,22 +337,22 @@ new PerlinDOM(options)
 | `isPlaying` | `boolean` | Current animation state |
 | `speed` | `number` | Animation speed (writable) |
 | `lerpSpeed` | `number` | Transition speed (writable) |
+| `amplitude` | `number` | Drift strength, clamped to `[0, 1]`, non-numbers reset to `1` (writable) |
+| `target` | `{x, y} \| null` | Current target offset (set it with `setTarget()`) |
+| `xRange` / `yRange` | `Object \| null` | Movement ranges (writable; whether percentages are used is fixed at construction) |
 
 ## 🔧 Troubleshooting
 
 ### Common Issues
 
 **❓ Animation not visible**
-```css
-/* Ensure element has positioning */
-.my-element {
-  position: relative; /* or absolute/fixed */
-}
-```
+- Set at least one of `x` / `y`
+- The element must not be `display: inline` (e.g. a plain `<span>`): transforms do not apply to inline boxes. Use `inline-block` or `block`
+- Static positioning is not the problem: PerlinDOM sets `position: relative` itself
 
 **❓ Element jumps on initialization**
-- PerlinDOM automatically detects current position
-- If element has conflicting inline styles, consider moving to CSS
+- Usually a CSS `translate`, such as `translate(-50%, -50%)` for centring, which PerlinDOM drops by default
+- Pass `preserveBaseTranslation: true`, or centre with `left: calc(50% - half)` or margins
 
 **❓ Animation too fast/slow**
 ```javascript
@@ -300,7 +364,10 @@ speed: 0.1    // Fast
 
 **❓ Percentage values not working**
 - Ensure parent container has defined dimensions
-- PerlinDOM calculates percentages based on parent size
+- Percentages use the parent's `clientWidth` / `clientHeight`, and need an `element`
+
+**❓ Element stops moving while off screen**
+- Intended: instances pause while their element's parent is outside the viewport and resume when it returns (needs `IntersectionObserver`; without it everything keeps running). The parent is watched, not the element, so an element's own drift never pauses it. Changing `amplitude` or calling `setTarget()` still renders while paused. Pass `pauseOffscreen: false` to never pause
 
 **❓ Memory leaks**
 ```javascript
@@ -316,19 +383,23 @@ Monitor performance in DevTools:
 
 ## 🌐 Browser Compatibility
 
-PerlinDOM works in all modern browsers supporting:
+The npm build (`dist/`) targets browsers with native ES modules and ES2020: **Chrome 87+, Edge 88+, Firefox 78+, Safari 14+**. Importing the source file directly needs private class methods and `??=`: Chrome 85+, Edge 85+, Firefox 90+, Safari 15+.
+
+- `requestAnimationFrame`, `getComputedStyle` and CSS transforms are required
+- `DOMMatrixReadOnly` separates the CSS translate from scale/rotate/skew; without it the computed transform is used as it is
+- `IntersectionObserver` powers the offscreen pause; without it everything keeps running
+
+## 🔗 Live site
+
+Live site: **https://perlindom.js.org** · [API reference](https://perlindom.js.org/api.html) · [Examples](https://perlindom.js.org/examples.html) · [Showcase](https://perlindom.js.org/showcase.html) (add yours with a PR to `src/showcase.json`)
+
+## 🤝 Contributing
 
-- ✅ **ES6 Modules** (2015+)
-- ✅ **requestAnimationFrame** (IE10+)
-- ✅ **CSS Transforms** (IE9+)
-- ✅ **getComputedStyle** (IE9+)
+Bug reports, fixes and showcase entries are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, tests and how to add your project to the [showcase](https://perlindom.js.org/showcase.html).
 
-### Tested Browsers
+## 💜 Sponsor
 
-- Chrome 60+
-- Firefox 55+
-- Safari 12+
-- Edge 79+
+PerlinDOM is free and MIT licensed. If it saves you time, you can support its development through [GitHub Sponsors](https://github.com/sponsors/andresclua).
 
 ## 📝 Changelog