@lovo/matter-react 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @lovo/matter-react
 
+## 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 @@
 
 React binding for **Matter** — shader components on WebGPU + Three.js TSL.
 
-This package wraps the engine ([`@lovo/matter`](https://www.npmjs.com/package/@lovo/matter)) with React-friendly primitives: a shared `<MatterScene>` canvas, a `useShaderMaterial` hook for `@react-three/fiber` integration, and input hooks (`useCursor`, `useScroll`).
+This package wraps the engine ([`@lovo/matter`](https://www.npmjs.com/package/@lovo/matter)) with React-friendly primitives: a shared `<ShaderScene>` canvas, a `useShaderMaterial` hook for `@react-three/fiber` integration, and input hooks (`useCursor`, `useScroll`).
 
 ## Install
 
@@ -17,21 +17,21 @@ npm install @lovo/matter @lovo/matter-react react three
 Matter components work in three configurations:
 
 1. **Drop-in** — each component manages its own canvas. Simplest path; one canvas per effect.
-2. **Shared scene** — wrap multiple Matter components in a single `<MatterScene>` to share one canvas (faster, layered effects).
+2. **Shared scene** — wrap multiple Matter components in a single `<ShaderScene>` to share one canvas (faster, layered effects).
 3. **Inside `@react-three/fiber`** — use `useShaderMaterial` directly inside a r3f `<Canvas>` you already own.
 
 ## Minimal usage (Mode 2: shared scene)
 
 ```tsx
-import { MatterScene } from '@lovo/matter-react'
+import { ShaderScene } from '@lovo/matter-react'
 // LinearGradient is copy-pasted into your project via @lovo/matter-cli
 import { LinearGradient } from '@/components/matter/linear-gradient'
 
 export default function Hero() {
   return (
-    <MatterScene>
+    <ShaderScene>
       <LinearGradient colors={['#0b0c2a', '#1d1f57', '#7d2dff']} angle={120} />
-    </MatterScene>
+    </ShaderScene>
   )
 }
 ```
@@ -52,6 +52,10 @@ The component lands in `src/components/matter/linear-gradient.tsx` and is yours
 
 <https://github.com/lovo-hq/matter>
 
+## Migration from 0.3.x
+
+`MatterScene`, `MatterMonitor`, `useMatterContext`, and related types have been renamed to `ShaderScene`, `ShaderMonitor`, `useShaderContext`, `ShaderContextValue`, etc. 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,32 +21,103 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   FallbackBoundary: () => FallbackBoundary,
-  MatterMonitor: () => MatterMonitor,
-  MatterScene: () => MatterScene,
+  ShaderMonitor: () => ShaderMonitor,
+  ShaderScene: () => ShaderScene,
   useAnimatableUniform: () => useAnimatableUniform,
   useCursor: () => useCursor,
-  useMatterContext: () => useMatterContext,
   useOverlayPass: () => useOverlayPass,
   useResize: () => useResize,
   useScroll: () => useScroll,
+  useShaderContext: () => useShaderContext,
   useShaderMaterial: () => useShaderMaterial,
   useStaticHint: () => useStaticHint
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/MatterScene.tsx
+// src/components/fallback-boundary/fallback-boundary.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function FallbackBoundary({ fallback, children }) {
+  const [mounted, setMounted] = (0, import_react.useState)(false);
+  (0, import_react.useEffect)(() => {
+    setMounted(true);
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: mounted ? children : fallback ?? null });
+}
+
+// src/components/shader-monitor/shader-monitor.tsx
+var import_react3 = require("react");
+
+// src/context/shader-context.ts
 var import_react2 = require("react");
-var import_three = require("three");
-var import_webgpu = require("three/webgpu");
-var import_tsl = require("three/tsl");
-var import_matter = require("@lovo/matter");
+var ShaderContext = (0, import_react2.createContext)(null);
 
-// src/matter-context.ts
-var import_react = require("react");
-var MatterContext = (0, import_react.createContext)(null);
+// src/components/shader-monitor/shader-monitor.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var anchorStyle = {
+  "top-left": { top: 8, left: 8 },
+  "top-right": { top: 8, right: 8 },
+  "bottom-left": { bottom: 8, left: 8 },
+  "bottom-right": { bottom: 8, right: 8 }
+};
+var baseStyle = {
+  position: "absolute",
+  zIndex: 10,
+  padding: "6px 8px",
+  borderRadius: 6,
+  background: "rgba(0, 0, 0, 0.6)",
+  color: "#fff",
+  font: "11px ui-monospace, monospace",
+  lineHeight: 1.4,
+  pointerEvents: "none",
+  whiteSpace: "pre"
+};
+function ShaderMonitor({ anchor = "top-right" }) {
+  const ctx = (0, import_react3.useContext)(ShaderContext);
+  const [stats, setStats] = (0, import_react3.useState)({ fps: 0, ticks: 0, frames: 0 });
+  const ticksRef = (0, import_react3.useRef)(0);
+  const fpsAccumRef = (0, import_react3.useRef)({ frames: 0, lastSampleAt: 0, fps: 0 });
+  (0, import_react3.useEffect)(() => {
+    if (!ctx) return;
+    const client = (tick) => {
+      ticksRef.current += 1;
+      const acc = fpsAccumRef.current;
+      acc.frames += 1;
+      if (acc.lastSampleAt === 0) acc.lastSampleAt = tick.now;
+      const dt = tick.now - acc.lastSampleAt;
+      if (dt >= 500) {
+        acc.fps = Math.round(acc.frames * 1e3 / dt);
+        acc.frames = 0;
+        acc.lastSampleAt = tick.now;
+      }
+      setStats({ fps: acc.fps, ticks: ticksRef.current, frames: acc.frames });
+    };
+    ctx.scheduler.add(client);
+    return () => ctx.scheduler.remove(client);
+  }, [ctx]);
+  if (!ctx) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { "data-testid": "matter-monitor", style: { ...baseStyle, ...anchorStyle[anchor] }, children: "no scene" });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { "data-testid": "matter-monitor", style: { ...baseStyle, ...anchorStyle[anchor] }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { "data-testid": "matter-monitor-fps", children: [
+      "fps: ",
+      stats.fps || "\u2014"
+    ] }),
+    "\n",
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { "data-testid": "matter-monitor-ticks", children: [
+      "ticks: ",
+      stats.ticks
+    ] })
+  ] });
+}
 
-// src/MatterScene.tsx
-var import_jsx_runtime = require("react/jsx-runtime");
+// src/components/shader-scene/shader-scene.tsx
+var import_matter = require("@lovo/matter");
+var import_react4 = require("react");
+var import_three = require("three");
+var import_tsl = require("three/tsl");
+var import_webgpu = require("three/webgpu");
+var import_jsx_runtime3 = require("react/jsx-runtime");
 var defaultStyle = {
   position: "absolute",
   inset: 0,
@@ -54,12 +125,12 @@ var defaultStyle = {
   width: "100%",
   height: "100%"
 };
-function MatterScene(props) {
+function ShaderScene(props) {
   const { children, fallback, className, style, maxDPR } = props;
-  const canvasRef = (0, import_react2.useRef)(null);
-  const [ctx, setCtx] = (0, import_react2.useState)(null);
-  const [error, setError] = (0, import_react2.useState)(null);
-  (0, import_react2.useEffect)(() => {
+  const canvasRef = (0, import_react4.useRef)(null);
+  const [ctx, setCtx] = (0, import_react4.useState)(null);
+  const [error, setError] = (0, import_react4.useState)(null);
+  (0, import_react4.useEffect)(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
     let cancelled = false;
@@ -75,14 +146,14 @@ function MatterScene(props) {
         const camera = new import_three.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
         camera.position.z = 1;
         const postProcessing = new import_webgpu.PostProcessing(renderer.three);
-        const scheduler = new import_matter.MatterScheduler();
+        const scheduler = new import_matter.FrameScheduler();
         const overlays = /* @__PURE__ */ new Map();
         const basePass = (0, import_tsl.pass)(scene, camera);
         const rebuildOutputNode = () => {
-          const transforms = Array.from(overlays.values());
-          postProcessing.outputNode = transforms.reduce(
+          const seed = basePass;
+          postProcessing.outputNode = Array.from(overlays.values()).reduce(
             (node, transform) => transform(node),
-            basePass
+            seed
           );
           postProcessing.needsUpdate = true;
         };
@@ -123,7 +194,7 @@ function MatterScene(props) {
       } catch (err) {
         if (cancelled) return;
         const e = err instanceof Error ? err : new Error(String(err));
-        console.error("[MatterScene] renderer init failed:", e);
+        console.error("[ShaderScene] renderer init failed:", e);
         setError(e);
       }
     };
@@ -135,9 +206,9 @@ function MatterScene(props) {
       setCtx(null);
     };
   }, [maxDPR]);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className, style: { ...defaultStyle, ...style }, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("canvas", { ref: canvasRef, style: { width: "100%", height: "100%", display: "block" } }),
-    error ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+  let content;
+  if (error) {
+    content = /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
       "div",
       {
         style: {
@@ -154,47 +225,67 @@ function MatterScene(props) {
           textAlign: "center"
         },
         children: [
-          "MatterScene init failed:",
+          "ShaderScene init failed:",
           "\n",
           error.message
         ]
       }
-    ) : ctx ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MatterContext.Provider, { value: ctx, children }) : fallback ?? null
+    );
+  } else if (ctx) {
+    content = /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ShaderContext.Provider, { value: ctx, children });
+  } else {
+    content = fallback ?? null;
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className, style: { ...defaultStyle, ...style }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("canvas", { ref: canvasRef, style: { width: "100%", height: "100%", display: "block" } }),
+    content
   ] });
 }
 
-// src/useMatterContext.ts
-var import_react3 = require("react");
-function useMatterContext() {
-  return (0, import_react3.useContext)(MatterContext);
+// src/hooks/use-animatable-uniform/use-animatable-uniform.ts
+var import_react5 = require("react");
+var import_tsl2 = require("three/tsl");
+var isSignal = (value) => {
+  if (typeof value !== "object" || value === null) return false;
+  return "get" in value && typeof value.get === "function" && "on" in value && typeof value.on === "function";
+};
+function useAnimatableUniform(value) {
+  const uniformNode = (0, import_react5.useMemo)(() => {
+    const initial = isSignal(value) ? value.get() : value;
+    return (0, import_tsl2.uniform)(initial);
+  }, []);
+  (0, import_react5.useEffect)(() => {
+    if (isSignal(value)) {
+      const unsub = value.on("change", (next) => {
+        uniformNode.value = next;
+      });
+      return unsub;
+    }
+    uniformNode.value = value;
+    return void 0;
+  }, [value, uniformNode]);
+  return uniformNode;
 }
 
-// src/useShaderMaterial.ts
-var import_react4 = require("react");
-var import_webgpu2 = require("three/webgpu");
-function useShaderMaterial(build) {
-  const material = (0, import_react4.useMemo)(() => {
-    const m = new import_webgpu2.MeshBasicNodeMaterial();
-    m.colorNode = build();
-    return m;
-  }, [build]);
-  (0, import_react4.useEffect)(() => {
-    return () => material.dispose();
-  }, [material]);
-  return material;
+// src/hooks/use-cursor/use-cursor.ts
+var import_matter2 = require("@lovo/matter");
+var import_react7 = require("react");
+
+// src/hooks/use-shader-context/use-shader-context.ts
+var import_react6 = require("react");
+function useShaderContext() {
+  return (0, import_react6.useContext)(ShaderContext);
 }
 
-// src/useCursor.ts
-var import_react5 = require("react");
-var import_matter2 = require("@lovo/matter");
+// src/hooks/use-cursor/use-cursor.ts
 var STUB_SIGNAL = {
   get: () => [0.5, 0.5],
   on: () => () => void 0
 };
 function useCursor(opts = {}) {
-  const ctx = useMatterContext();
-  const [input, setInput] = (0, import_react5.useState)(null);
-  (0, import_react5.useEffect)(() => {
+  const ctx = useShaderContext();
+  const [input, setInput] = (0, import_react7.useState)(null);
+  (0, import_react7.useEffect)(() => {
     const canvas = ctx?.renderer.three.domElement;
     const elementOpt = opts.element ?? (canvas instanceof HTMLElement ? canvas : void 0);
     const fresh = new import_matter2.CursorInput({ ...opts, element: elementOpt });
@@ -219,7 +310,7 @@ function useCursor(opts = {}) {
       };
     }
     return () => {
-      detach?.();
+      detach();
       fresh.dispose();
       setInput(null);
     };
@@ -227,16 +318,27 @@ function useCursor(opts = {}) {
   return input ?? STUB_SIGNAL;
 }
 
-// src/useResize.ts
-var import_react6 = require("react");
+// src/hooks/use-overlay-pass/use-overlay-pass.ts
+var import_react8 = require("react");
+function useOverlayPass(transform, deps) {
+  const ctx = useShaderContext();
+  (0, import_react8.useEffect)(() => {
+    if (!ctx) return;
+    const unregister = ctx.registerOverlay(transform);
+    return unregister;
+  }, [ctx, ...deps]);
+}
+
+// src/hooks/use-resize/use-resize.ts
+var import_react9 = require("react");
 var STUB_SIGNAL2 = {
   get: () => [0, 0, 1],
   on: () => () => void 0
 };
 function useResize() {
-  const ctx = useMatterContext();
-  const [signal, setSignal] = (0, import_react6.useState)(null);
-  (0, import_react6.useEffect)(() => {
+  const ctx = useShaderContext();
+  const [signal, setSignal] = (0, import_react9.useState)(null);
+  (0, import_react9.useEffect)(() => {
     if (!ctx) return void 0;
     const canvas = ctx.renderer.three.domElement;
     if (!(canvas instanceof HTMLCanvasElement)) return void 0;
@@ -296,15 +398,15 @@ function useResize() {
   return signal ?? STUB_SIGNAL2;
 }
 
-// src/useScroll.ts
-var import_react7 = require("react");
+// src/hooks/use-scroll/use-scroll.ts
+var import_react10 = require("react");
 var STUB_SIGNAL3 = {
   get: () => [0, 0],
   on: () => () => void 0
 };
 function useScroll() {
-  const [signal, setSignal] = (0, import_react7.useState)(null);
-  (0, import_react7.useEffect)(() => {
+  const [signal, setSignal] = (0, import_react10.useState)(null);
+  (0, import_react10.useEffect)(() => {
     if (typeof window === "undefined") return void 0;
     const compute = () => {
       const y = window.scrollY;
@@ -346,135 +448,42 @@ function useScroll() {
   return signal ?? STUB_SIGNAL3;
 }
 
-// src/useAnimatableUniform.ts
-var import_react8 = require("react");
-var import_tsl2 = require("three/tsl");
-var isSignal = (value) => {
-  return typeof value === "object" && value !== null && typeof value.get === "function" && typeof value.on === "function";
-};
-function useAnimatableUniform(value) {
-  const uniformNode = (0, import_react8.useMemo)(() => {
-    const initial = isSignal(value) ? value.get() : value;
-    return (0, import_tsl2.uniform)(initial);
-  }, []);
-  (0, import_react8.useEffect)(() => {
-    if (isSignal(value)) {
-      const unsub = value.on("change", (next) => {
-        ;
-        uniformNode.value = next;
-      });
-      return unsub;
-    }
-    ;
-    uniformNode.value = value;
-    return void 0;
-  }, [value, uniformNode]);
-  return uniformNode;
-}
-
-// src/useOverlayPass.ts
-var import_react9 = require("react");
-function useOverlayPass(transform, deps) {
-  const ctx = useMatterContext();
-  (0, import_react9.useEffect)(() => {
-    if (!ctx) return;
-    const unregister = ctx.registerOverlay(transform);
-    return unregister;
-  }, [ctx, ...deps]);
-}
-
-// src/FallbackBoundary.tsx
-var import_react10 = require("react");
-var import_jsx_runtime2 = require("react/jsx-runtime");
-function FallbackBoundary({ fallback, children }) {
-  const [mounted, setMounted] = (0, import_react10.useState)(false);
-  (0, import_react10.useEffect)(() => {
-    setMounted(true);
-  }, []);
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: mounted ? children : fallback ?? null });
-}
-
-// src/useStaticHint.ts
+// src/hooks/use-shader-material/use-shader-material.ts
 var import_react11 = require("react");
-function useStaticHint(hint) {
-  const ctx = useMatterContext();
+var import_webgpu2 = require("three/webgpu");
+function useShaderMaterial(build) {
+  const material = (0, import_react11.useMemo)(() => {
+    const m = new import_webgpu2.MeshBasicNodeMaterial();
+    m.colorNode = build();
+    return m;
+  }, [build]);
   (0, import_react11.useEffect)(() => {
-    if (!ctx) return;
-    ctx.scheduler.setIdle(hint);
-    return () => ctx.scheduler.setIdle(false);
-  }, [ctx, hint]);
+    return () => material.dispose();
+  }, [material]);
+  return material;
 }
 
-// src/MatterMonitor.tsx
+// src/hooks/use-static-hint/use-static-hint.ts
 var import_react12 = require("react");
-var import_jsx_runtime3 = require("react/jsx-runtime");
-var anchorStyle = {
-  "top-left": { top: 8, left: 8 },
-  "top-right": { top: 8, right: 8 },
-  "bottom-left": { bottom: 8, left: 8 },
-  "bottom-right": { bottom: 8, right: 8 }
-};
-var baseStyle = {
-  position: "absolute",
-  zIndex: 10,
-  padding: "6px 8px",
-  borderRadius: 6,
-  background: "rgba(0, 0, 0, 0.6)",
-  color: "#fff",
-  font: "11px ui-monospace, monospace",
-  lineHeight: 1.4,
-  pointerEvents: "none",
-  whiteSpace: "pre"
-};
-function MatterMonitor({ anchor = "top-right" }) {
-  const ctx = (0, import_react12.useContext)(MatterContext);
-  const [stats, setStats] = (0, import_react12.useState)({ fps: 0, ticks: 0, frames: 0 });
-  const ticksRef = (0, import_react12.useRef)(0);
-  const fpsAccumRef = (0, import_react12.useRef)({ frames: 0, lastSampleAt: 0, fps: 0 });
+function useStaticHint(hint) {
+  const ctx = useShaderContext();
   (0, import_react12.useEffect)(() => {
     if (!ctx) return;
-    const client = (tick) => {
-      ticksRef.current += 1;
-      const acc = fpsAccumRef.current;
-      acc.frames += 1;
-      if (acc.lastSampleAt === 0) acc.lastSampleAt = tick.now;
-      const dt = tick.now - acc.lastSampleAt;
-      if (dt >= 500) {
-        acc.fps = Math.round(acc.frames * 1e3 / dt);
-        acc.frames = 0;
-        acc.lastSampleAt = tick.now;
-      }
-      setStats({ fps: acc.fps, ticks: ticksRef.current, frames: acc.frames });
-    };
-    ctx.scheduler.add(client);
-    return () => ctx.scheduler.remove(client);
-  }, [ctx]);
-  if (!ctx) {
-    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { "data-testid": "matter-monitor", style: { ...baseStyle, ...anchorStyle[anchor] }, children: "no scene" });
-  }
-  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { "data-testid": "matter-monitor", style: { ...baseStyle, ...anchorStyle[anchor] }, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { "data-testid": "matter-monitor-fps", children: [
-      "fps: ",
-      stats.fps || "\u2014"
-    ] }),
-    "\n",
-    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { "data-testid": "matter-monitor-ticks", children: [
-      "ticks: ",
-      stats.ticks
-    ] })
-  ] });
+    ctx.scheduler.setIdle(hint);
+    return () => ctx.scheduler.setIdle(false);
+  }, [ctx, hint]);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FallbackBoundary,
-  MatterMonitor,
-  MatterScene,
+  ShaderMonitor,
+  ShaderScene,
   useAnimatableUniform,
   useCursor,
-  useMatterContext,
   useOverlayPass,
   useResize,
   useScroll,
+  useShaderContext,
   useShaderMaterial,
   useStaticHint
 });