@lovo/matter 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @lovo/matter
 
+## 0.5.0
+
+### Minor Changes
+
+- c67eb98: Rename engine exports to spelled-out, domain-accurate names (breaking).
+
+  - `fbm` → `fractalNoise` (and `FBMOptions` → `FractalNoiseOptions`)
+  - `noise` → `simplexNoise`
+  - `sdfCircle` → `signedDistanceFieldCircle`
+  - `time` → `elapsedTime`
+  - `Vec2` → `Vector2`
+
+  `TSLNode`, `voronoi`, `colorRamp`, `quantize`, `displace`, `cursorRipple`, and `filmGrain` are unchanged.
+
+  **Migration:** one-pass find-and-replace in your imports and call sites. No behavioral changes.
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -15,18 +15,18 @@ npm install @lovo/matter three
 
 ## What's inside
 
-- **TSL primitives**: `fbm`, `voronoi`, `colorRamp`, `quantize`, and a handful of others — composable shader fragments for procedural visuals.
+- **TSL primitives**: `fractalNoise`, `voronoi`, `colorRamp`, `quantize`, and a handful of others — composable shader fragments for procedural visuals.
 - **Renderer**: thin wrapper around `WebGPURenderer` that handles canvas resize, DPR, and `setClearColor`.
 - **Scheduler**: visibility/intersection-aware render loop that pauses when the canvas is off-screen or the tab is hidden.
 
 ## Minimal usage
 
 ```typescript
-import { fbm, colorRamp } from '@lovo/matter'
+import { fractalNoise, colorRamp } from '@lovo/matter'
 import { uv, vec3, time } from 'three/tsl'
 
 // Inside your TSL fragment graph:
-const noise = fbm(uv().mul(4).add(time.mul(0.1)))
+const noise = fractalNoise(uv().mul(4).add(time.mul(0.1)))
 const color = colorRamp(noise, [
   { stop: 0.0, color: vec3(0.05, 0.05, 0.1) },
   { stop: 1.0, color: vec3(0.3, 0.5, 0.95) },

package/dist/index.cjs

@@ -29,15 +29,15 @@ __export(index_exports, {
   createVisibilityWatcher: () => createVisibilityWatcher,
   cursorRipple: () => cursorRipple,
   displace: () => displace,
-  fbm: () => fbm,
+  elapsedTime: () => elapsedTime,
   filmGrain: () => filmGrain,
+  fractalNoise: () => fractalNoise,
   getReducedMotionPolicy: () => getReducedMotionPolicy,
   getReducedMotionTimeScale: () => getReducedMotionTimeScale,
-  noise: () => noise,
   quantize: () => quantize,
-  sdfCircle: () => sdfCircle,
   setReducedMotionPolicy: () => setReducedMotionPolicy,
-  time: () => time,
+  signedDistanceFieldCircle: () => signedDistanceFieldCircle,
+  simplexNoise: () => simplexNoise,
   voronoi: () => voronoi
 });
 module.exports = __toCommonJS(index_exports);
@@ -63,10 +63,10 @@ async function createRenderer(canvas, opts = {}) {
   const resolvedClearColor = clearColor instanceof import_three.Color ? clearColor : new import_three.Color(clearColor);
   three.setClearColor(resolvedClearColor, clearAlpha);
   const resize = () => {
-    const w = canvas.clientWidth;
-    const h = canvas.clientHeight;
-    if (canvas.width !== w * three.getPixelRatio() || canvas.height !== h * three.getPixelRatio()) {
-      three.setSize(w, h, false);
+    const canvasWidth = canvas.clientWidth;
+    const canvasHeight = canvas.clientHeight;
+    if (canvas.width !== canvasWidth * three.getPixelRatio() || canvas.height !== canvasHeight * three.getPixelRatio()) {
+      three.setSize(canvasWidth, canvasHeight, false);
     }
   };
   resize();
@@ -100,16 +100,19 @@ var CursorInput = class {
     this.element = element;
     this.handleMouseMove = (e) => {
       if (!(e instanceof MouseEvent)) return;
-      const me = e;
+      const mouseEvent = e;
       if (this.element) {
-        const r = this.element.getBoundingClientRect();
-        const w = r.width || 1;
-        const h = r.height || 1;
-        this.target = [(me.clientX - r.left) / w, (me.clientY - r.top) / h];
+        const elementRect = this.element.getBoundingClientRect();
+        const elementWidth = elementRect.width || 1;
+        const elementHeight = elementRect.height || 1;
+        this.target = [
+          (mouseEvent.clientX - elementRect.left) / elementWidth,
+          (mouseEvent.clientY - elementRect.top) / elementHeight
+        ];
       } else {
-        const w = typeof window !== "undefined" && window.innerWidth || 1;
-        const h = typeof window !== "undefined" && window.innerHeight || 1;
-        this.target = [me.clientX / w, me.clientY / h];
+        const viewportWidth = typeof window !== "undefined" && window.innerWidth || 1;
+        const viewportHeight = typeof window !== "undefined" && window.innerHeight || 1;
+        this.target = [mouseEvent.clientX / viewportWidth, mouseEvent.clientY / viewportHeight];
       }
       this.targetDirty = true;
     };
@@ -120,9 +123,9 @@ var CursorInput = class {
     return this.value;
   }
   /** Subscribe to change events. Returns an unsubscribe function. */
-  on(_event, cb) {
-    this.listeners.add(cb);
-    return () => this.listeners.delete(cb);
+  on(_eventType, changeListener) {
+    this.listeners.add(changeListener);
+    return () => this.listeners.delete(changeListener);
   }
   /**
    * Advance the smoothing one tick. Called by the host scheduler; not
@@ -151,8 +154,8 @@ var CursorInput = class {
     this.listeners.clear();
   }
 };
-var clamp01 = (n) => Math.max(0, Math.min(1, n));
-var lerp = (a, b, t) => a + (b - a) * t;
+var clamp01 = (value) => Math.max(0, Math.min(1, value));
+var lerp = (startValue, endValue, blendFactor) => startValue + (endValue - startValue) * blendFactor;
 
 // src/primitives/color-ramp/color-ramp.ts
 var import_tsl = require("three/tsl");
@@ -163,12 +166,12 @@ function colorRamp(t, stops) {
   if (stops.length === 1) return (0, import_tsl.mix)(first.color, first.color, 0);
   let result = (0, import_tsl.mix)(first.color, first.color, 0);
   for (let i = 1; i < stops.length; i += 1) {
-    const prev = stops[i - 1];
+    const previousStop = stops[i - 1];
     const next = stops[i];
-    if (prev === void 0 || next === void 0) continue;
-    const span = next.position - prev.position;
-    if (span <= 0) continue;
-    const localT = (0, import_tsl2.clamp)((0, import_tsl2.div)((0, import_tsl2.sub)(t, prev.position), span), 0, 1);
+    if (previousStop === void 0 || next === void 0) continue;
+    const positionSpan = next.position - previousStop.position;
+    if (positionSpan <= 0) continue;
+    const localT = (0, import_tsl2.clamp)((0, import_tsl2.div)((0, import_tsl2.sub)(t, previousStop.position), positionSpan), 0, 1);
     result = (0, import_tsl.mix)(result, next.color, localT);
   }
   return result;
@@ -176,26 +179,26 @@ function colorRamp(t, stops) {
 
 // src/primitives/noise/noise.ts
 var import_tsl3 = require("three/tsl");
-function noise(p) {
+function simplexNoise(p) {
   return (0, import_tsl3.mx_noise_float)(p);
 }
 
 // src/primitives/fbm/fbm.ts
 var import_tsl4 = require("three/tsl");
-function fbm(p, opts = {}) {
+function fractalNoise(p, opts = {}) {
   const octaves = opts.octaves ?? 4;
   const lacunarity = opts.lacunarity ?? 2;
   const gain = opts.gain ?? 0.5;
-  let sum = noise(p);
-  let amp = 1;
-  let freq = 1;
-  let total = amp;
+  let sum = simplexNoise(p);
+  let amplitude = 1;
+  let frequency = 1;
+  let total = amplitude;
   for (let i = 1; i < octaves; i += 1) {
-    freq *= lacunarity;
-    amp *= gain;
-    total += amp;
-    const pAtFreq = (0, import_tsl4.add)((0, import_tsl4.mul)(p, freq), i * 100);
-    const layer = noise(pAtFreq).mul(amp);
+    frequency *= lacunarity;
+    amplitude *= gain;
+    total += amplitude;
+    const pAtFreq = (0, import_tsl4.add)((0, import_tsl4.mul)(p, frequency), i * 100);
+    const layer = simplexNoise(pAtFreq).mul(amplitude);
     sum = sum.add(layer);
   }
   return sum.div(total);
@@ -212,13 +215,13 @@ function quantize(t, steps) {
   if (steps <= 1) {
     return t.mul(0);
   }
-  const denom = steps - 1;
-  return t.mul(denom).add(0.5).floor().div(denom);
+  const denominator = steps - 1;
+  return t.mul(denominator).add(0.5).floor().div(denominator);
 }
 
 // src/primitives/sdf-circle/sdf-circle.ts
 var import_tsl6 = require("three/tsl");
-function sdfCircle(p, radius) {
+function signedDistanceFieldCircle(p, radius) {
   return (0, import_tsl6.length)(p).sub(radius);
 }
 
@@ -243,7 +246,7 @@ var state = {
 function setReducedMotionPolicy(policy) {
   if (state.policy === policy) return;
   state.policy = policy;
-  for (const w of state.watchers) w.recompute();
+  for (const watcher of state.watchers) watcher.recompute();
 }
 function getReducedMotionPolicy() {
   return state.policy;
@@ -264,8 +267,8 @@ function createReducedMotionWatcher() {
   if (typeof matchMedia !== "function") {
     return {
       scale: () => computeScale(false),
-      subscribe: (cb) => {
-        void cb;
+      subscribe: (listener) => {
+        void listener;
         return () => {
         };
       },
@@ -274,33 +277,33 @@ function createReducedMotionWatcher() {
       }
     };
   }
-  const mql = matchMedia("(prefers-reduced-motion: reduce)");
-  const subs = /* @__PURE__ */ new Set();
-  let last = computeScale(mql.matches);
+  const mediaQueryList = matchMedia("(prefers-reduced-motion: reduce)");
+  const subscriptions = /* @__PURE__ */ new Set();
+  let lastComputedScale = computeScale(mediaQueryList.matches);
   const onChange = () => {
-    const next = computeScale(mql.matches);
-    if (next !== last) {
-      last = next;
-      for (const cb of subs) cb(next);
+    const next = computeScale(mediaQueryList.matches);
+    if (next !== lastComputedScale) {
+      lastComputedScale = next;
+      for (const listener of subscriptions) listener(next);
     }
   };
-  mql.addEventListener("change", onChange);
+  mediaQueryList.addEventListener("change", onChange);
   const watcher = {
-    scale: () => last,
-    subscribe(cb) {
-      subs.add(cb);
-      return () => subs.delete(cb);
+    scale: () => lastComputedScale,
+    subscribe(listener) {
+      subscriptions.add(listener);
+      return () => subscriptions.delete(listener);
     },
     recompute() {
-      const next = computeScale(mql.matches);
-      if (next !== last) {
-        last = next;
-        for (const cb of subs) cb(next);
+      const next = computeScale(mediaQueryList.matches);
+      if (next !== lastComputedScale) {
+        lastComputedScale = next;
+        for (const listener of subscriptions) listener(next);
       }
     },
     dispose() {
-      mql.removeEventListener("change", onChange);
-      subs.clear();
+      mediaQueryList.removeEventListener("change", onChange);
+      subscriptions.clear();
       state.watchers.delete(watcher);
     }
   };
@@ -322,7 +325,7 @@ function getReducedMotionTimeScale() {
 }
 
 // src/primitives/time/time.ts
-var time = import_tsl9.time.mul(getReducedMotionTimeScale());
+var elapsedTime = import_tsl9.time.mul(getReducedMotionTimeScale());
 
 // src/primitives/cursor-ripple/cursor-ripple.ts
 function cursorRipple(p, center, opts = {}) {
@@ -331,19 +334,17 @@ function cursorRipple(p, center, opts = {}) {
   const speed = opts.speed ?? 6;
   const amplitude = opts.amplitude ?? 0.5;
   const d = (0, import_tsl10.length)((0, import_tsl10.sub)(p, center));
-  const wave = (0, import_tsl10.sin)(d.mul(frequency).sub(time.mul(speed)));
+  const wave = (0, import_tsl10.sin)(d.mul(frequency).sub(elapsedTime.mul(speed)));
   const decay = (0, import_tsl10.smoothstep)(reach, 0, d);
   return wave.mul(amplitude).mul(decay);
 }
 
 // src/primitives/film-grain/film-grain.ts
 var import_tsl11 = require("three/tsl");
-function filmGrain(uvNode, intensity, timeOffset = 0) {
-  const HASH_C1 = (0, import_tsl11.vec2)(2127.1, 81.17);
-  const HASH_C2 = (0, import_tsl11.vec2)(1269.5, 283.37);
-  const base = (0, import_tsl11.vec2)(uvNode.dot(HASH_C1).add(timeOffset), uvNode.dot(HASH_C2).add(timeOffset));
-  const hash = (0, import_tsl11.fract)((0, import_tsl11.sin)(base).mul(43758.5453));
-  return (0, import_tsl11.length)(hash).sub(0.765).mul(intensity);
+function filmGrain(intensity, timeOffset = 0) {
+  const pixel = import_tsl11.screenCoordinate.xy.floor();
+  const seed = pixel.x.toUint().mul(1973).add(pixel.y.toUint().mul(9277)).add((0, import_tsl11.mul)(timeOffset, 26699).toUint());
+  return (0, import_tsl11.hash)(seed).sub(0.5).mul(intensity);
 }
 
 // src/runtime/visibility/visibility.ts
@@ -357,21 +358,21 @@ function createVisibilityWatcher() {
       }
     };
   }
-  const subs = /* @__PURE__ */ new Set();
+  const subscriptions = /* @__PURE__ */ new Set();
   const onChange = () => {
-    const v = document.visibilityState === "visible";
-    for (const cb of subs) cb(v);
+    const isVisible = document.visibilityState === "visible";
+    for (const listener of subscriptions) listener(isVisible);
   };
   document.addEventListener("visibilitychange", onChange);
   return {
     isVisible: () => document.visibilityState === "visible",
-    subscribe(cb) {
-      subs.add(cb);
-      return () => subs.delete(cb);
+    subscribe(listener) {
+      subscriptions.add(listener);
+      return () => subscriptions.delete(listener);
     },
     dispose() {
       document.removeEventListener("visibilitychange", onChange);
-      subs.clear();
+      subscriptions.clear();
     }
   };
 }
@@ -387,27 +388,27 @@ function createIntersectionWatcher(canvas) {
       }
     };
   }
-  const subs = /* @__PURE__ */ new Set();
+  const subscriptions = /* @__PURE__ */ new Set();
   let inView = true;
-  const obs = new IntersectionObserver(
+  const observer = new IntersectionObserver(
     (entries) => {
-      const next = entries.some((e) => e.isIntersecting);
+      const next = entries.some((entry) => entry.isIntersecting);
       if (next === inView) return;
       inView = next;
-      for (const cb of subs) cb(inView);
+      for (const listener of subscriptions) listener(inView);
     },
     { threshold: 0 }
   );
-  obs.observe(canvas);
+  observer.observe(canvas);
   return {
     isInView: () => inView,
-    subscribe(cb) {
-      subs.add(cb);
-      return () => subs.delete(cb);
+    subscribe(listener) {
+      subscriptions.add(listener);
+      return () => subscriptions.delete(listener);
     },
     dispose() {
-      obs.disconnect();
-      subs.clear();
+      observer.disconnect();
+      subscriptions.clear();
     }
   };
 }
@@ -418,10 +419,19 @@ var FrameScheduler = class {
   rafId = null;
   running = false;
   paused = false;
-  idle = false;
   flushPending = false;
   startedAt = 0;
   lastTickAt = 0;
+  // Reference-counted idle voting. The scheduler is idle only when at least
+  // one component has voted idle AND no component has voted animated. This
+  // prevents a static component (e.g. LinearGradient speed=0) from halting
+  // the loop while an animated overlay (e.g. FilmGrain) is still running.
+  idleVotes = 0;
+  animatedVotes = 0;
+  /** True when all participating components prefer idle and none need animation. */
+  get idle() {
+    return this.idleVotes > 0 && this.animatedVotes === 0;
+  }
   /** Activate the scheduler. The rAF loop starts on the first client added. */
   start() {
     this.running = true;
@@ -457,19 +467,39 @@ var FrameScheduler = class {
     this.clients.clear();
   }
   /**
-   * Mark the scheduler idle. The next tick still fires (a final flush so
-   * uniform changes that triggered the idle state are rendered), then the
-   * rAF loop halts. Use `requestRender()` or `setIdle(false)` to wake.
+   * Cast a vote on whether the scheduler should be idle.
+   *
+   * `setIdle(true)` increments the idle-vote count; the returned cleanup
+   * decrements it. `setIdle(false)` increments the animated-vote count;
+   * its cleanup decrements that. The scheduler halts (after one flush tick)
+   * only when `idleVotes > 0 && animatedVotes === 0`.
+   *
+   * Callers are responsible for calling the returned cleanup on unmount.
+   * Use `requestRender()` or cast a `setIdle(false)` vote to wake the loop
+   * without permanently registering an animated preference.
    */
   setIdle(idle) {
-    if (this.idle === idle) return;
-    this.idle = idle;
     if (idle) {
-      this.flushPending = true;
-      this.maybeQueue();
+      const wasIdle = this.idle;
+      this.idleVotes += 1;
+      const nowIdle = this.idle;
+      if (!wasIdle && nowIdle) this.onBecameIdle();
+      return () => {
+        const prevIdle = this.idle;
+        this.idleVotes = Math.max(0, this.idleVotes - 1);
+        const afterIdle = this.idle;
+        if (prevIdle && !afterIdle) this.onBecameAnimated();
+      };
     } else {
-      this.flushPending = false;
-      this.maybeQueue();
+      const wasIdle = this.idle;
+      this.animatedVotes += 1;
+      if (wasIdle) this.onBecameAnimated();
+      return () => {
+        const prevIdle = this.idle;
+        this.animatedVotes = Math.max(0, this.animatedVotes - 1);
+        const nowIdle = this.idle;
+        if (!prevIdle && nowIdle) this.onBecameIdle();
+      };
     }
   }
   /** Force a single tick while idle. Useful for prop-change invalidation. */
@@ -478,6 +508,14 @@ var FrameScheduler = class {
     this.flushPending = true;
     this.maybeQueue();
   }
+  onBecameIdle() {
+    this.flushPending = true;
+    this.maybeQueue();
+  }
+  onBecameAnimated() {
+    this.flushPending = false;
+    this.maybeQueue();
+  }
   maybeQueue() {
     if (this.rafId !== null) return;
     if (!this.running) return;
@@ -520,15 +558,15 @@ var FrameScheduler = class {
   createVisibilityWatcher,
   cursorRipple,
   displace,
-  fbm,
+  elapsedTime,
   filmGrain,
+  fractalNoise,
   getReducedMotionPolicy,
   getReducedMotionTimeScale,
-  noise,
   quantize,
-  sdfCircle,
   setReducedMotionPolicy,
-  time,
+  signedDistanceFieldCircle,
+  simplexNoise,
   voronoi
 });
 //# sourceMappingURL=index.cjs.map