@lovo/matter-react 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @lovo/matter-react
 
+## 0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- 35274c3: Rename ambiguous `@lovo/matter-react` public exports to clearer names (BREAKING, pre-1.0):
+
+  - `useOverlayPass` → `usePostProcessPass` (and the paired type `OverlayTransform` → `PostProcessTransform`)
+  - `useStaticHint` → `useStaticSceneHint`
+  - `MonitorAnchor` (type) → `ShaderMonitorAnchor`
+
+  Migration: update imports and call sites to the new names. Behavior is unchanged.
+
 ## 0.4.1
 
 ## 0.4.0
@@ -23,13 +37,13 @@
   **New: `useOverlayPass(transform, deps)` hook**
 
   ```ts
-  import { useOverlayPass, useAnimatableUniform } from "@lovo/matter-react";
+  import { useAnimatableUniform, useOverlayPass } from '@lovo/matter-react';
 
   export function MyOverlay({ intensity }) {
     const intensityU = useAnimatableUniform(intensity);
     useOverlayPass(
       (input) => input.mul(intensityU), // takes upstream pixel, returns modified pixel
-      [intensityU]
+      [intensityU],
     );
     return null;
   }

package/README.md

@@ -38,7 +38,7 @@ export default function Hero() {
 
 ## Getting components
 
-Polished drop-in components (`<LinearGradient>`, `<Aurora>`, `<DotField>`, `<NoiseField>`, `<MeshGradient>`, `<Waves>`) ship via the shadcn-style copy-paste CLI. Install it once:
+Polished drop-in components (`<LinearGradient>`, `<Aurora>`, `<DotField>`, `<SimplexNoise>`, `<MeshGradient>`, `<Waves>`) ship via the shadcn-style copy-paste CLI. Install it once:
 
 ```bash
 npm install -D @lovo/matter-cli

package/dist/index.cjs

@@ -25,12 +25,13 @@ __export(index_exports, {
   ShaderScene: () => ShaderScene,
   useAnimatableUniform: () => useAnimatableUniform,
   useCursor: () => useCursor,
-  useOverlayPass: () => useOverlayPass,
+  useDisplayGamut: () => useDisplayGamut,
+  usePostProcessPass: () => usePostProcessPass,
   useResize: () => useResize,
   useScroll: () => useScroll,
   useShaderContext: () => useShaderContext,
   useShaderMaterial: () => useShaderMaterial,
-  useStaticHint: () => useStaticHint
+  useStaticSceneHint: () => useStaticSceneHint
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -73,29 +74,29 @@ var baseStyle = {
   whiteSpace: "pre"
 };
 function ShaderMonitor({ anchor = "top-right" }) {
-  const ctx = (0, import_react3.useContext)(ShaderContext);
+  const shaderContext = (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) => {
+    if (!shaderContext) return;
+    const schedulerTickHandler = (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;
+      const fpsAccumulator = fpsAccumRef.current;
+      fpsAccumulator.frames += 1;
+      if (fpsAccumulator.lastSampleAt === 0) fpsAccumulator.lastSampleAt = tick.now;
+      const deltaTimeSinceLastSample = tick.now - fpsAccumulator.lastSampleAt;
+      if (deltaTimeSinceLastSample >= 500) {
+        fpsAccumulator.fps = Math.round(fpsAccumulator.frames * 1e3 / deltaTimeSinceLastSample);
+        fpsAccumulator.frames = 0;
+        fpsAccumulator.lastSampleAt = tick.now;
       }
-      setStats({ fps: acc.fps, ticks: ticksRef.current, frames: acc.frames });
+      setStats({ fps: fpsAccumulator.fps, ticks: ticksRef.current, frames: fpsAccumulator.frames });
     };
-    ctx.scheduler.add(client);
-    return () => ctx.scheduler.remove(client);
-  }, [ctx]);
-  if (!ctx) {
+    shaderContext.scheduler.add(schedulerTickHandler);
+    return () => shaderContext.scheduler.remove(schedulerTickHandler);
+  }, [shaderContext]);
+  if (!shaderContext) {
     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: [
@@ -112,11 +113,44 @@ function ShaderMonitor({ anchor = "top-right" }) {
 }
 
 // src/components/shader-scene/shader-scene.tsx
+var import_react5 = require("react");
 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");
+
+// src/hooks/use-display-gamut/use-display-gamut.ts
+var import_react4 = require("react");
+var P3_QUERY = "(color-gamut: p3)";
+function detectGamut() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "srgb";
+  }
+  return window.matchMedia(P3_QUERY).matches ? "p3" : "srgb";
+}
+function useDisplayGamut(preference) {
+  const [resolved, setResolved] = (0, import_react4.useState)(
+    () => preference === "auto" ? detectGamut() : preference
+  );
+  (0, import_react4.useEffect)(() => {
+    if (preference !== "auto") {
+      setResolved(preference);
+      return;
+    }
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+      setResolved("srgb");
+      return;
+    }
+    const mediaQuery = window.matchMedia(P3_QUERY);
+    const update = () => setResolved(mediaQuery.matches ? "p3" : "srgb");
+    update();
+    mediaQuery.addEventListener("change", update);
+    return () => mediaQuery.removeEventListener("change", update);
+  }, [preference]);
+  return resolved;
+}
+
+// src/components/shader-scene/shader-scene.tsx
 var import_jsx_runtime3 = require("react/jsx-runtime");
 var defaultStyle = {
   position: "absolute",
@@ -126,18 +160,21 @@ var defaultStyle = {
   height: "100%"
 };
 function ShaderScene(props) {
-  const { children, fallback, className, style, maxDPR } = props;
-  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 { children, fallback, className, style, maxDPR, gamut = "auto" } = props;
+  const resolvedGamut = useDisplayGamut(gamut);
+  const canvasRef = (0, import_react5.useRef)(null);
+  const [shaderContext, setShaderContext] = (0, import_react5.useState)(null);
+  const [error, setError] = (0, import_react5.useState)(null);
+  const [firstFramePainted, setFirstFramePainted] = (0, import_react5.useState)(false);
+  (0, import_react5.useEffect)(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
     let cancelled = false;
     let cleanup = null;
+    let firstPaintRaf = null;
     const setup = async () => {
       try {
-        const renderer = await (0, import_matter.createRenderer)(canvas, { maxDPR });
+        const renderer = await (0, import_matter.createRenderer)(canvas, { maxDPR, gamut: resolvedGamut });
         if (cancelled) {
           renderer.dispose();
           return;
@@ -148,12 +185,11 @@ function ShaderScene(props) {
         const postProcessing = new import_webgpu.PostProcessing(renderer.three);
         const scheduler = new import_matter.FrameScheduler();
         const overlays = /* @__PURE__ */ new Map();
-        const basePass = (0, import_tsl.pass)(scene, camera);
+        const basePassNode = (0, import_tsl.vec4)((0, import_tsl.pass)(scene, camera));
         const rebuildOutputNode = () => {
-          const seed = basePass;
           postProcessing.outputNode = Array.from(overlays.values()).reduce(
-            (node, transform) => transform(node),
-            seed
+            (currentPipeline, transform) => transform(currentPipeline),
+            basePassNode
           );
           postProcessing.needsUpdate = true;
         };
@@ -167,7 +203,18 @@ function ShaderScene(props) {
             rebuildOutputNode();
           };
         };
-        scheduler.add(() => postProcessing.render());
+        let firstPaintSignaled = false;
+        const renderFrame = () => {
+          postProcessing.render();
+          if (!firstPaintSignaled && (scene.children.length > 0 || overlays.size > 0)) {
+            firstPaintSignaled = true;
+            firstPaintRaf = requestAnimationFrame(() => {
+              firstPaintRaf = null;
+              if (!cancelled) setFirstFramePainted(true);
+            });
+          }
+        };
+        scheduler.add(renderFrame);
         scheduler.start();
         const visibility = (0, import_matter.createVisibilityWatcher)();
         const intersection = (0, import_matter.createIntersectionWatcher)(canvas);
@@ -179,33 +226,38 @@ function ShaderScene(props) {
         updatePauseState();
         const unsubVisibility = visibility.subscribe(updatePauseState);
         const unsubIntersection = intersection.subscribe(updatePauseState);
-        const onResize = () => renderer.resize();
-        window.addEventListener("resize", onResize);
+        const resizeObserver = new ResizeObserver(() => renderer.resize());
+        resizeObserver.observe(canvas);
         cleanup = () => {
           unsubVisibility();
           unsubIntersection();
           visibility.dispose();
           intersection.dispose();
-          window.removeEventListener("resize", onResize);
+          resizeObserver.disconnect();
           scheduler.dispose();
           renderer.dispose();
         };
-        setCtx({ renderer, scene, camera, scheduler, registerOverlay });
-      } catch (err) {
+        setShaderContext({ renderer, scene, camera, scheduler, registerOverlay });
+      } catch (caughtError) {
         if (cancelled) return;
-        const e = err instanceof Error ? err : new Error(String(err));
-        console.error("[ShaderScene] renderer init failed:", e);
-        setError(e);
+        const normalizedError = caughtError instanceof Error ? caughtError : new Error(String(caughtError));
+        console.error("[ShaderScene] renderer init failed:", normalizedError);
+        setError(normalizedError);
       }
     };
     void setup();
     return () => {
       cancelled = true;
+      if (firstPaintRaf !== null) {
+        cancelAnimationFrame(firstPaintRaf);
+        firstPaintRaf = null;
+      }
       cleanup?.();
       cleanup = null;
-      setCtx(null);
+      setShaderContext(null);
+      setFirstFramePainted(false);
     };
-  }, [maxDPR]);
+  }, [maxDPR, resolvedGamut]);
   let content;
   if (error) {
     content = /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
@@ -231,10 +283,11 @@ function ShaderScene(props) {
         ]
       }
     );
-  } else if (ctx) {
-    content = /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ShaderContext.Provider, { value: ctx, children });
   } else {
-    content = fallback ?? null;
+    content = /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
+      shaderContext && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ShaderContext.Provider, { value: shaderContext, children }),
+      !firstFramePainted && (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" } }),
@@ -243,18 +296,18 @@ function ShaderScene(props) {
 }
 
 // src/hooks/use-animatable-uniform/use-animatable-uniform.ts
-var import_react5 = require("react");
+var import_react6 = 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 uniformNode = (0, import_react6.useMemo)(() => {
     const initial = isSignal(value) ? value.get() : value;
     return (0, import_tsl2.uniform)(initial);
   }, []);
-  (0, import_react5.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (isSignal(value)) {
       const unsub = value.on("change", (next) => {
         uniformNode.value = next;
@@ -268,13 +321,13 @@ function useAnimatableUniform(value) {
 }
 
 // src/hooks/use-cursor/use-cursor.ts
+var import_react8 = require("react");
 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");
+var import_react7 = require("react");
 function useShaderContext() {
-  return (0, import_react6.useContext)(ShaderContext);
+  return (0, import_react7.useContext)(ShaderContext);
 }
 
 // src/hooks/use-cursor/use-cursor.ts
@@ -283,81 +336,91 @@ var STUB_SIGNAL = {
   on: () => () => void 0
 };
 function useCursor(opts = {}) {
-  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 });
-    setInput(fresh);
+  const shaderContext = useShaderContext();
+  const [input, setInput] = (0, import_react8.useState)(null);
+  (0, import_react8.useEffect)(() => {
+    const canvas = shaderContext?.renderer.three.domElement;
+    const resolvedElement = opts.element ?? (canvas instanceof HTMLElement ? canvas : void 0);
+    const newCursorInput = new import_matter2.CursorInput({ ...opts, element: resolvedElement });
+    setInput(newCursorInput);
     let detach = null;
-    if (ctx?.scheduler) {
-      const client = ({ delta }) => fresh.tick(delta);
-      ctx.scheduler.add(client);
-      detach = () => ctx.scheduler.remove(client);
+    if (shaderContext?.scheduler) {
+      const schedulerTickHandler = ({ delta }) => newCursorInput.tick(delta);
+      shaderContext.scheduler.add(schedulerTickHandler);
+      detach = () => shaderContext.scheduler.remove(schedulerTickHandler);
     } else {
-      let raf = null;
+      let animationFrameId = null;
       let lastNow = performance.now();
       const loop = (now) => {
         const delta = (now - lastNow) / 1e3;
         lastNow = now;
-        fresh.tick(delta);
-        raf = requestAnimationFrame(loop);
+        newCursorInput.tick(delta);
+        animationFrameId = requestAnimationFrame(loop);
       };
-      raf = requestAnimationFrame(loop);
+      animationFrameId = requestAnimationFrame(loop);
       detach = () => {
-        if (raf !== null) cancelAnimationFrame(raf);
+        if (animationFrameId !== null) cancelAnimationFrame(animationFrameId);
       };
     }
     return () => {
       detach();
-      fresh.dispose();
+      newCursorInput.dispose();
       setInput(null);
     };
-  }, [ctx]);
+  }, [shaderContext]);
   return input ?? STUB_SIGNAL;
 }
 
 // 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);
+var import_react9 = require("react");
+function usePostProcessPass(transform, deps) {
+  const shaderContext = useShaderContext();
+  (0, import_react9.useEffect)(() => {
+    if (!shaderContext) return;
+    const unregister = shaderContext.registerOverlay(transform);
     return unregister;
-  }, [ctx, ...deps]);
+  }, [shaderContext, ...deps]);
+}
+
+// src/hooks/use-resize/use-resize.ts
+var import_react10 = require("react");
+
+// src/internal/create-signal.ts
+function createSignal(getValue) {
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    listeners,
+    signal: {
+      get: getValue,
+      on: (_event, listener) => {
+        listeners.add(listener);
+        return () => {
+          listeners.delete(listener);
+        };
+      }
+    }
+  };
 }
 
 // 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 = useShaderContext();
-  const [signal, setSignal] = (0, import_react9.useState)(null);
-  (0, import_react9.useEffect)(() => {
-    if (!ctx) return void 0;
-    const canvas = ctx.renderer.three.domElement;
+  const shaderContext = useShaderContext();
+  const [signal, setSignal] = (0, import_react10.useState)(null);
+  (0, import_react10.useEffect)(() => {
+    if (!shaderContext) return void 0;
+    const canvas = shaderContext.renderer.three.domElement;
     if (!(canvas instanceof HTMLCanvasElement)) return void 0;
     let value = [
       canvas.clientWidth,
       canvas.clientHeight,
       typeof window !== "undefined" ? window.devicePixelRatio : 1
     ];
-    const listeners = /* @__PURE__ */ new Set();
-    const fresh = {
-      get: () => value,
-      on: (_event, cb) => {
-        listeners.add(cb);
-        return () => {
-          listeners.delete(cb);
-        };
-      }
-    };
-    setSignal(fresh);
+    const { signal: newSignal, listeners } = createSignal(() => value);
+    setSignal(newSignal);
     const emit = () => {
       const next = [
         canvas.clientWidth,
@@ -366,66 +429,59 @@ function useResize() {
       ];
       if (next[0] === value[0] && next[1] === value[1] && next[2] === value[2]) return;
       value = next;
-      for (const cb of listeners) cb(next);
+      for (const listener of listeners) listener(next);
     };
     const observer = new ResizeObserver(emit);
     observer.observe(canvas);
-    let mql = null;
-    let mqlHandler = null;
+    let mediaQueryList = null;
+    let mediaQueryListener = null;
     const setupDprWatch = () => {
       if (typeof window === "undefined") return;
       const dpr = window.devicePixelRatio;
-      const next = window.matchMedia(`(resolution: ${dpr}dppx)`);
-      const handler = () => {
+      const nextMediaQueryList = window.matchMedia(`(resolution: ${dpr}dppx)`);
+      const nextMediaQueryListener = () => {
         emit();
-        if (mql && mqlHandler) mql.removeEventListener("change", mqlHandler);
+        if (mediaQueryList && mediaQueryListener)
+          mediaQueryList.removeEventListener("change", mediaQueryListener);
         setupDprWatch();
       };
-      next.addEventListener("change", handler);
-      mql = next;
-      mqlHandler = handler;
+      nextMediaQueryList.addEventListener("change", nextMediaQueryListener);
+      mediaQueryList = nextMediaQueryList;
+      mediaQueryListener = nextMediaQueryListener;
     };
     setupDprWatch();
     return () => {
       observer.disconnect();
-      if (mql && mqlHandler) mql.removeEventListener("change", mqlHandler);
-      mql = null;
-      mqlHandler = null;
+      if (mediaQueryList && mediaQueryListener)
+        mediaQueryList.removeEventListener("change", mediaQueryListener);
+      mediaQueryList = null;
+      mediaQueryListener = null;
       listeners.clear();
       setSignal(null);
     };
-  }, [ctx]);
+  }, [shaderContext]);
   return signal ?? STUB_SIGNAL2;
 }
 
 // src/hooks/use-scroll/use-scroll.ts
-var import_react10 = require("react");
+var import_react11 = require("react");
 var STUB_SIGNAL3 = {
   get: () => [0, 0],
   on: () => () => void 0
 };
 function useScroll() {
-  const [signal, setSignal] = (0, import_react10.useState)(null);
-  (0, import_react10.useEffect)(() => {
+  const [signal, setSignal] = (0, import_react11.useState)(null);
+  (0, import_react11.useEffect)(() => {
     if (typeof window === "undefined") return void 0;
     const compute = () => {
-      const y = window.scrollY;
+      const scrollYPosition = window.scrollY;
       const max = Math.max(document.documentElement.scrollHeight - window.innerHeight, 1);
-      const progress = Math.max(0, Math.min(1, y / max));
-      return [y, progress];
+      const progress = Math.max(0, Math.min(1, scrollYPosition / max));
+      return [scrollYPosition, progress];
     };
     let value = compute();
-    const listeners = /* @__PURE__ */ new Set();
-    const fresh = {
-      get: () => value,
-      on: (_event, cb) => {
-        listeners.add(cb);
-        return () => {
-          listeners.delete(cb);
-        };
-      }
-    };
-    setSignal(fresh);
+    const { signal: newSignal, listeners } = createSignal(() => value);
+    setSignal(newSignal);
     let rafPending = false;
     const onScroll = () => {
       if (rafPending) return;
@@ -435,7 +491,7 @@ function useScroll() {
         const next = compute();
         if (next[0] === value[0] && next[1] === value[1]) return;
         value = next;
-        for (const cb of listeners) cb(next);
+        for (const listener of listeners) listener(next);
       });
     };
     window.addEventListener("scroll", onScroll, { passive: true });
@@ -449,29 +505,28 @@ function useScroll() {
 }
 
 // src/hooks/use-shader-material/use-shader-material.ts
-var import_react11 = require("react");
+var import_react12 = require("react");
 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;
+  const material = (0, import_react12.useMemo)(() => {
+    const nodeMaterial = new import_webgpu2.MeshBasicNodeMaterial();
+    nodeMaterial.colorNode = build();
+    return nodeMaterial;
   }, [build]);
-  (0, import_react11.useEffect)(() => {
+  (0, import_react12.useEffect)(() => {
     return () => material.dispose();
   }, [material]);
   return material;
 }
 
 // src/hooks/use-static-hint/use-static-hint.ts
-var import_react12 = require("react");
-function useStaticHint(hint) {
-  const ctx = useShaderContext();
-  (0, import_react12.useEffect)(() => {
-    if (!ctx) return;
-    ctx.scheduler.setIdle(hint);
-    return () => ctx.scheduler.setIdle(false);
-  }, [ctx, hint]);
+var import_react13 = require("react");
+function useStaticSceneHint(isStatic) {
+  const shaderContext = useShaderContext();
+  (0, import_react13.useEffect)(() => {
+    if (!shaderContext) return;
+    return shaderContext.scheduler.setIdle(isStatic);
+  }, [shaderContext, isStatic]);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -480,11 +535,12 @@ function useStaticHint(hint) {
   ShaderScene,
   useAnimatableUniform,
   useCursor,
-  useOverlayPass,
+  useDisplayGamut,
+  usePostProcessPass,
   useResize,
   useScroll,
   useShaderContext,
   useShaderMaterial,
-  useStaticHint
+  useStaticSceneHint
 });
 //# sourceMappingURL=index.cjs.map