@lovo/matter 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @lovo/matter
 
+## 0.4.1
+
+### Patch Changes
+
+- b4ecdda: Reorganize engine source into kebab-case module folders under `inputs/`, `primitives/`, and `runtime/` (matching `matter-react` and `registry` layout). No public API changes.
+
+## 0.4.0
+
+### Minor Changes
+
+- 1c69220: Rename public API symbols to domain-accurate names.
+
+  New primary names: `FrameScheduler`, `GpuRenderer`, `GpuBackend` (`@lovo/matter`); `ShaderScene`, `ShaderSceneProps`, `ShaderContext`, `ShaderContextValue`, `useShaderContext`, `ShaderMonitor`, `ShaderMonitorProps`, `AnimatableSignal` (`@lovo/matter-react`).
+
+  Old names (`MatterScheduler`, `MatterRenderer`, `MatterBackend`, `MatterScene`, `MatterSceneProps`, `MatterContext`, `MatterContextValue`, `useMatterContext`, `MatterMonitor`, `MatterMonitorProps`, `MatterSignal`, `MatterBackend`) are deprecated with `@deprecated` JSDoc and continue to work. They will be removed no earlier than 0.5.0.
+
+  **Migration:** Replace old names with new in your imports and JSX. A one-pass find-and-replace is sufficient — no behavioral changes.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,7 @@
 
 Framework-agnostic engine for **Matter** — React shader components on WebGPU + Three.js TSL.
 
-This package contains the TSL primitives, the renderer, and the scheduler. It has no React dependency. If you're using React, install [`@lovo/matter-react`](https://www.npmjs.com/package/@lovo/matter-react) alongside this package — it adds React-friendly wrappers (a shared `<MatterScene>`, input hooks, and `@react-three/fiber` integration) on top of this engine.
+This package contains the TSL primitives, the renderer, and the scheduler. It has no React dependency. If you're using React, install [`@lovo/matter-react`](https://www.npmjs.com/package/@lovo/matter-react) alongside this package — it adds React-friendly wrappers (a shared `<ShaderScene>`, input hooks, and `@react-three/fiber` integration) on top of this engine.
 
 ## Install
 
@@ -39,6 +39,10 @@ For polished drop-in components like `<LinearGradient>` and `<Aurora>`, install
 
 Full docs and live demos: <https://github.com/lovo-hq/matter>
 
+## Migration from 0.3.x
+
+`MatterScheduler`, `MatterRenderer`, and `MatterBackend` have been renamed to `FrameScheduler`, `GpuRenderer`, and `GpuBackend`. The old names are deprecated and still work — remove them at your leisure before 0.5.0.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/index.cjs

@@ -21,7 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CursorInput: () => CursorInput,
-  MatterScheduler: () => MatterScheduler,
+  FrameScheduler: () => FrameScheduler,
   colorRamp: () => colorRamp,
   createIntersectionWatcher: () => createIntersectionWatcher,
   createReducedMotionWatcher: () => createReducedMotionWatcher,
@@ -42,9 +42,9 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/runtime/createRenderer.ts
-var import_webgpu = require("three/webgpu");
+// src/runtime/create-renderer/create-renderer.ts
 var import_three = require("three");
+var import_webgpu = require("three/webgpu");
 async function createRenderer(canvas, opts = {}) {
   const {
     antialias = true,
@@ -70,7 +70,8 @@ async function createRenderer(canvas, opts = {}) {
     }
   };
   resize();
-  const backend = forceWebGL || three.backend?.isWebGLBackend ? "webgl2" : "webgpu";
+  const isWebGL = "isWebGLBackend" in three.backend && three.backend.isWebGLBackend === true;
+  const backend = forceWebGL || isWebGL ? "webgl2" : "webgpu";
   return {
     three,
     backend,
@@ -79,105 +80,7 @@ async function createRenderer(canvas, opts = {}) {
   };
 }
 
-// src/runtime/MatterScheduler.ts
-var MatterScheduler = class {
-  clients = /* @__PURE__ */ new Set();
-  rafId = null;
-  running = false;
-  paused = false;
-  idle = false;
-  flushPending = false;
-  startedAt = 0;
-  lastTickAt = 0;
-  /** Activate the scheduler. The rAF loop starts on the first client added. */
-  start() {
-    this.running = true;
-    this.paused = false;
-    this.maybeQueue();
-  }
-  /** Halt the rAF loop entirely. Use dispose() for permanent teardown. */
-  stop() {
-    this.running = false;
-    this.cancel();
-  }
-  /** Temporarily skip ticks without losing client registrations. */
-  pause() {
-    this.paused = true;
-  }
-  /** Resume after pause(). */
-  resume() {
-    this.paused = false;
-    if (this.running) this.maybeQueue();
-  }
-  /** Register a client to be called every frame. */
-  add(client) {
-    this.clients.add(client);
-    if (this.running) this.maybeQueue();
-  }
-  /** Unregister a client. */
-  remove(client) {
-    this.clients.delete(client);
-  }
-  /** Permanent teardown: stop the loop and drop all clients. */
-  dispose() {
-    this.stop();
-    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.
-   */
-  setIdle(idle) {
-    if (this.idle === idle) return;
-    this.idle = idle;
-    if (idle) {
-      this.flushPending = true;
-      this.maybeQueue();
-    } else {
-      this.flushPending = false;
-      this.maybeQueue();
-    }
-  }
-  /** Force a single tick while idle. Useful for prop-change invalidation. */
-  requestRender() {
-    if (!this.idle) return;
-    this.flushPending = true;
-    this.maybeQueue();
-  }
-  maybeQueue() {
-    if (this.rafId !== null) return;
-    if (!this.running) return;
-    if (this.clients.size === 0) return;
-    if (this.idle && !this.flushPending) return;
-    this.rafId = requestAnimationFrame(this.frame);
-  }
-  cancel() {
-    if (this.rafId !== null) {
-      cancelAnimationFrame(this.rafId);
-      this.rafId = null;
-    }
-  }
-  frame = (now) => {
-    this.rafId = null;
-    if (!this.running || this.paused) return;
-    if (this.startedAt === 0) {
-      this.startedAt = now;
-      this.lastTickAt = now;
-    }
-    const delta = (now - this.lastTickAt) / 1e3;
-    const elapsed = (now - this.startedAt) / 1e3;
-    this.lastTickAt = now;
-    const tick = { delta, elapsed, now };
-    for (const client of this.clients) {
-      client(tick);
-    }
-    this.flushPending = false;
-    this.maybeQueue();
-  };
-};
-
-// src/inputs/CursorInput.ts
+// src/inputs/cursor-input/cursor-input.ts
 var CursorInput = class {
   value;
   target;
@@ -196,6 +99,7 @@ var CursorInput = class {
     this.eventTarget = target ?? (typeof window !== "undefined" ? window : new EventTarget());
     this.element = element;
     this.handleMouseMove = (e) => {
+      if (!(e instanceof MouseEvent)) return;
       const me = e;
       if (this.element) {
         const r = this.element.getBoundingClientRect();
@@ -211,7 +115,7 @@ var CursorInput = class {
     };
     this.eventTarget.addEventListener("mousemove", this.handleMouseMove);
   }
-  /** Current smoothed position. Implements MatterSignal protocol. */
+  /** Current smoothed position. Implements AnimatableSignal protocol. */
   get() {
     return this.value;
   }
@@ -250,16 +154,18 @@ var CursorInput = class {
 var clamp01 = (n) => Math.max(0, Math.min(1, n));
 var lerp = (a, b, t) => a + (b - a) * t;
 
-// src/primitives/colorRamp.ts
+// src/primitives/color-ramp/color-ramp.ts
 var import_tsl = require("three/tsl");
 var import_tsl2 = require("three/tsl");
 function colorRamp(t, stops) {
-  if (stops.length === 0) return (0, import_tsl.vec3)(0, 0, 0);
-  if (stops.length === 1) return stops[0].color;
-  let result = stops[0].color;
-  for (let i = 1; i < stops.length; i++) {
+  const first = stops[0];
+  if (first === void 0) return (0, import_tsl.vec3)(0, 0, 0);
+  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 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);
@@ -268,13 +174,13 @@ function colorRamp(t, stops) {
   return result;
 }
 
-// src/primitives/noise.ts
+// src/primitives/noise/noise.ts
 var import_tsl3 = require("three/tsl");
 function noise(p) {
   return (0, import_tsl3.mx_noise_float)(p);
 }
 
-// src/primitives/fbm.ts
+// src/primitives/fbm/fbm.ts
 var import_tsl4 = require("three/tsl");
 function fbm(p, opts = {}) {
   const octaves = opts.octaves ?? 4;
@@ -284,7 +190,7 @@ function fbm(p, opts = {}) {
   let amp = 1;
   let freq = 1;
   let total = amp;
-  for (let i = 1; i < octaves; i++) {
+  for (let i = 1; i < octaves; i += 1) {
     freq *= lacunarity;
     amp *= gain;
     total += amp;
@@ -295,13 +201,13 @@ function fbm(p, opts = {}) {
   return sum.div(total);
 }
 
-// src/primitives/voronoi.ts
+// src/primitives/voronoi/voronoi.ts
 var import_tsl5 = require("three/tsl");
 function voronoi(p) {
   return (0, import_tsl5.mx_worley_noise_float)(p);
 }
 
-// src/primitives/quantize.ts
+// src/primitives/quantize/quantize.ts
 function quantize(t, steps) {
   if (steps <= 1) {
     return t.mul(0);
@@ -310,25 +216,25 @@ function quantize(t, steps) {
   return t.mul(denom).add(0.5).floor().div(denom);
 }
 
-// src/primitives/sdfCircle.ts
+// src/primitives/sdf-circle/sdf-circle.ts
 var import_tsl6 = require("three/tsl");
 function sdfCircle(p, radius) {
   return (0, import_tsl6.length)(p).sub(radius);
 }
 
-// src/primitives/displace.ts
+// src/primitives/displace/displace.ts
 var import_tsl7 = require("three/tsl");
 function displace(p, by) {
   return (0, import_tsl7.add)(p, by);
 }
 
-// src/primitives/cursorRipple.ts
+// src/primitives/cursor-ripple/cursor-ripple.ts
 var import_tsl10 = require("three/tsl");
 
-// src/primitives/time.ts
+// src/primitives/time/time.ts
 var import_tsl9 = require("three/tsl");
 
-// src/runtime/reducedMotion.ts
+// src/runtime/reduced-motion/reduced-motion.ts
 var import_tsl8 = require("three/tsl");
 var state = {
   policy: "auto",
@@ -415,10 +321,10 @@ function getReducedMotionTimeScale() {
   return globalScaleUniform;
 }
 
-// src/primitives/time.ts
+// src/primitives/time/time.ts
 var time = import_tsl9.time.mul(getReducedMotionTimeScale());
 
-// src/primitives/cursorRipple.ts
+// src/primitives/cursor-ripple/cursor-ripple.ts
 function cursorRipple(p, center, opts = {}) {
   const reach = opts.reach ?? 0.4;
   const frequency = opts.frequency ?? 30;
@@ -430,7 +336,7 @@ function cursorRipple(p, center, opts = {}) {
   return wave.mul(amplitude).mul(decay);
 }
 
-// src/primitives/filmGrain.ts
+// 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);
@@ -440,7 +346,7 @@ function filmGrain(uvNode, intensity, timeOffset = 0) {
   return (0, import_tsl11.length)(hash).sub(0.765).mul(intensity);
 }
 
-// src/runtime/visibility.ts
+// src/runtime/visibility/visibility.ts
 function createVisibilityWatcher() {
   if (typeof document === "undefined") {
     return {
@@ -470,7 +376,7 @@ function createVisibilityWatcher() {
   };
 }
 
-// src/runtime/intersection.ts
+// src/runtime/intersection/intersection.ts
 function createIntersectionWatcher(canvas) {
   if (typeof IntersectionObserver === "undefined") {
     return {
@@ -505,10 +411,108 @@ function createIntersectionWatcher(canvas) {
     }
   };
 }
+
+// src/runtime/frame-scheduler/frame-scheduler.ts
+var FrameScheduler = class {
+  clients = /* @__PURE__ */ new Set();
+  rafId = null;
+  running = false;
+  paused = false;
+  idle = false;
+  flushPending = false;
+  startedAt = 0;
+  lastTickAt = 0;
+  /** Activate the scheduler. The rAF loop starts on the first client added. */
+  start() {
+    this.running = true;
+    this.paused = false;
+    this.maybeQueue();
+  }
+  /** Halt the rAF loop entirely. Use dispose() for permanent teardown. */
+  stop() {
+    this.running = false;
+    this.cancel();
+  }
+  /** Temporarily skip ticks without losing client registrations. */
+  pause() {
+    this.paused = true;
+  }
+  /** Resume after pause(). */
+  resume() {
+    this.paused = false;
+    if (this.running) this.maybeQueue();
+  }
+  /** Register a client to be called every frame. */
+  add(client) {
+    this.clients.add(client);
+    if (this.running) this.maybeQueue();
+  }
+  /** Unregister a client. */
+  remove(client) {
+    this.clients.delete(client);
+  }
+  /** Permanent teardown: stop the loop and drop all clients. */
+  dispose() {
+    this.stop();
+    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.
+   */
+  setIdle(idle) {
+    if (this.idle === idle) return;
+    this.idle = idle;
+    if (idle) {
+      this.flushPending = true;
+      this.maybeQueue();
+    } else {
+      this.flushPending = false;
+      this.maybeQueue();
+    }
+  }
+  /** Force a single tick while idle. Useful for prop-change invalidation. */
+  requestRender() {
+    if (!this.idle) return;
+    this.flushPending = true;
+    this.maybeQueue();
+  }
+  maybeQueue() {
+    if (this.rafId !== null) return;
+    if (!this.running) return;
+    if (this.clients.size === 0) return;
+    if (this.idle && !this.flushPending) return;
+    this.rafId = requestAnimationFrame(this.frame);
+  }
+  cancel() {
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+  }
+  frame = (now) => {
+    this.rafId = null;
+    if (!this.running || this.paused) return;
+    if (this.startedAt === 0) {
+      this.startedAt = now;
+      this.lastTickAt = now;
+    }
+    const delta = (now - this.lastTickAt) / 1e3;
+    const elapsed = (now - this.startedAt) / 1e3;
+    this.lastTickAt = now;
+    const tick = { delta, elapsed, now };
+    for (const client of this.clients) {
+      client(tick);
+    }
+    this.flushPending = false;
+    this.maybeQueue();
+  };
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CursorInput,
-  MatterScheduler,
+  FrameScheduler,
   colorRamp,
   createIntersectionWatcher,
   createReducedMotionWatcher,