@lovo/matter-react 0.1.0

package/dist/index.cjs

@@ -0,0 +1,445 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FallbackBoundary: () => FallbackBoundary,
+  MatterMonitor: () => MatterMonitor,
+  MatterScene: () => MatterScene,
+  useAnimatableUniform: () => useAnimatableUniform,
+  useCursor: () => useCursor,
+  useMatterContext: () => useMatterContext,
+  useResize: () => useResize,
+  useScroll: () => useScroll,
+  useShaderMaterial: () => useShaderMaterial,
+  useStaticHint: () => useStaticHint
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/MatterScene.tsx
+var import_react2 = require("react");
+var import_three = require("three");
+var import_matter = require("@lovo/matter");
+
+// src/matter-context.ts
+var import_react = require("react");
+var MatterContext = (0, import_react.createContext)(null);
+
+// src/MatterScene.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var defaultStyle = {
+  position: "absolute",
+  inset: 0,
+  display: "block",
+  width: "100%",
+  height: "100%"
+};
+function MatterScene(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 canvas = canvasRef.current;
+    if (!canvas) return;
+    let cancelled = false;
+    let cleanup = null;
+    const setup = async () => {
+      try {
+        const renderer = await (0, import_matter.createRenderer)(canvas, { maxDPR });
+        if (cancelled) {
+          renderer.dispose();
+          return;
+        }
+        const scene = new import_three.Scene();
+        const camera = new import_three.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
+        camera.position.z = 1;
+        const scheduler = new import_matter.MatterScheduler();
+        scheduler.add(() => renderer.three.render(scene, camera));
+        scheduler.start();
+        const visibility = (0, import_matter.createVisibilityWatcher)();
+        const intersection = (0, import_matter.createIntersectionWatcher)(canvas);
+        const updatePauseState = () => {
+          const shouldRun = visibility.isVisible() && intersection.isInView();
+          if (shouldRun) scheduler.resume();
+          else scheduler.pause();
+        };
+        updatePauseState();
+        const unsubVisibility = visibility.subscribe(updatePauseState);
+        const unsubIntersection = intersection.subscribe(updatePauseState);
+        const onResize = () => renderer.resize();
+        window.addEventListener("resize", onResize);
+        cleanup = () => {
+          unsubVisibility();
+          unsubIntersection();
+          visibility.dispose();
+          intersection.dispose();
+          window.removeEventListener("resize", onResize);
+          scheduler.dispose();
+          renderer.dispose();
+        };
+        setCtx({ renderer, scene, camera, scheduler });
+      } catch (err) {
+        if (cancelled) return;
+        const e = err instanceof Error ? err : new Error(String(err));
+        console.error("[MatterScene] renderer init failed:", e);
+        setError(e);
+      }
+    };
+    void setup();
+    return () => {
+      cancelled = true;
+      cleanup?.();
+      cleanup = null;
+      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)(
+      "div",
+      {
+        style: {
+          position: "absolute",
+          inset: 0,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          padding: "1rem",
+          color: "#fff",
+          background: "rgba(120, 30, 30, 0.85)",
+          font: "0.85rem ui-monospace, monospace",
+          whiteSpace: "pre-wrap",
+          textAlign: "center"
+        },
+        children: [
+          "MatterScene init failed:",
+          "\n",
+          error.message
+        ]
+      }
+    ) : ctx ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MatterContext.Provider, { value: ctx, children }) : fallback ?? null
+  ] });
+}
+
+// src/useMatterContext.ts
+var import_react3 = require("react");
+function useMatterContext() {
+  return (0, import_react3.useContext)(MatterContext);
+}
+
+// src/useShaderMaterial.ts
+var import_react4 = require("react");
+var import_webgpu = require("three/webgpu");
+function useShaderMaterial(build) {
+  const material = (0, import_react4.useMemo)(() => {
+    const m = new import_webgpu.MeshBasicNodeMaterial();
+    m.colorNode = build();
+    return m;
+  }, [build]);
+  (0, import_react4.useEffect)(() => {
+    return () => material.dispose();
+  }, [material]);
+  return material;
+}
+
+// src/useCursor.ts
+var import_react5 = require("react");
+var import_matter2 = require("@lovo/matter");
+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 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);
+    let detach = null;
+    if (ctx?.scheduler) {
+      const client = ({ delta }) => fresh.tick(delta);
+      ctx.scheduler.add(client);
+      detach = () => ctx.scheduler.remove(client);
+    } else {
+      let raf = null;
+      let lastNow = performance.now();
+      const loop = (now) => {
+        const delta = (now - lastNow) / 1e3;
+        lastNow = now;
+        fresh.tick(delta);
+        raf = requestAnimationFrame(loop);
+      };
+      raf = requestAnimationFrame(loop);
+      detach = () => {
+        if (raf !== null) cancelAnimationFrame(raf);
+      };
+    }
+    return () => {
+      detach?.();
+      fresh.dispose();
+      setInput(null);
+    };
+  }, [ctx]);
+  return input ?? STUB_SIGNAL;
+}
+
+// src/useResize.ts
+var import_react6 = 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)(() => {
+    if (!ctx) return void 0;
+    const canvas = ctx.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 emit = () => {
+      const next = [
+        canvas.clientWidth,
+        canvas.clientHeight,
+        typeof window !== "undefined" ? window.devicePixelRatio : 1
+      ];
+      if (next[0] === value[0] && next[1] === value[1] && next[2] === value[2]) return;
+      value = next;
+      for (const cb of listeners) cb(next);
+    };
+    const observer = new ResizeObserver(emit);
+    observer.observe(canvas);
+    let mql = null;
+    let mqlHandler = null;
+    const setupDprWatch = () => {
+      if (typeof window === "undefined") return;
+      const dpr = window.devicePixelRatio;
+      const next = window.matchMedia(`(resolution: ${dpr}dppx)`);
+      const handler = () => {
+        emit();
+        if (mql && mqlHandler) mql.removeEventListener("change", mqlHandler);
+        setupDprWatch();
+      };
+      next.addEventListener("change", handler);
+      mql = next;
+      mqlHandler = handler;
+    };
+    setupDprWatch();
+    return () => {
+      observer.disconnect();
+      if (mql && mqlHandler) mql.removeEventListener("change", mqlHandler);
+      mql = null;
+      mqlHandler = null;
+      listeners.clear();
+      setSignal(null);
+    };
+  }, [ctx]);
+  return signal ?? STUB_SIGNAL2;
+}
+
+// src/useScroll.ts
+var import_react7 = 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)(() => {
+    if (typeof window === "undefined") return void 0;
+    const compute = () => {
+      const y = 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];
+    };
+    let value = compute();
+    const listeners = /* @__PURE__ */ new Set();
+    const fresh = {
+      get: () => value,
+      on: (_event, cb) => {
+        listeners.add(cb);
+        return () => {
+          listeners.delete(cb);
+        };
+      }
+    };
+    setSignal(fresh);
+    let rafPending = false;
+    const onScroll = () => {
+      if (rafPending) return;
+      rafPending = true;
+      requestAnimationFrame(() => {
+        rafPending = false;
+        const next = compute();
+        if (next[0] === value[0] && next[1] === value[1]) return;
+        value = next;
+        for (const cb of listeners) cb(next);
+      });
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      listeners.clear();
+      setSignal(null);
+    };
+  }, []);
+  return signal ?? STUB_SIGNAL3;
+}
+
+// src/useAnimatableUniform.ts
+var import_react8 = require("react");
+var import_tsl = 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_tsl.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/FallbackBoundary.tsx
+var import_react9 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function FallbackBoundary({ fallback, children }) {
+  const [mounted, setMounted] = (0, import_react9.useState)(false);
+  (0, import_react9.useEffect)(() => {
+    setMounted(true);
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: mounted ? children : fallback ?? null });
+}
+
+// src/useStaticHint.ts
+var import_react10 = require("react");
+function useStaticHint(hint) {
+  const ctx = useMatterContext();
+  (0, import_react10.useEffect)(() => {
+    if (!ctx) return;
+    ctx.scheduler.setIdle(hint);
+    return () => ctx.scheduler.setIdle(false);
+  }, [ctx, hint]);
+}
+
+// src/MatterMonitor.tsx
+var import_react11 = 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_react11.useContext)(MatterContext);
+  const [stats, setStats] = (0, import_react11.useState)({ fps: 0, ticks: 0, frames: 0 });
+  const ticksRef = (0, import_react11.useRef)(0);
+  const fpsAccumRef = (0, import_react11.useRef)({ frames: 0, lastSampleAt: 0, fps: 0 });
+  (0, import_react11.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
+    ] })
+  ] });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FallbackBoundary,
+  MatterMonitor,
+  MatterScene,
+  useAnimatableUniform,
+  useCursor,
+  useMatterContext,
+  useResize,
+  useScroll,
+  useShaderMaterial,
+  useStaticHint
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/MatterScene.tsx","../src/matter-context.ts","../src/useMatterContext.ts","../src/useShaderMaterial.ts","../src/useCursor.ts","../src/useResize.ts","../src/useScroll.ts","../src/useAnimatableUniform.ts","../src/FallbackBoundary.tsx","../src/useStaticHint.ts","../src/MatterMonitor.tsx"],"sourcesContent":["// @lovo/matter-react — React binding for Matter.\n\nexport { MatterScene } from './MatterScene.js'\nexport type { MatterSceneProps } from './MatterScene.js'\n\nexport { useMatterContext } from './useMatterContext.js'\nexport type { MatterContextValue } from './matter-context.js'\n\nexport { useShaderMaterial } from './useShaderMaterial.js'\n\nexport { useCursor } from './useCursor.js'\nexport type { CursorSignal } from './useCursor.js'\n\nexport { useResize } from './useResize.js'\nexport type { ResizeSignal, ResizeValue } from './useResize.js'\n\nexport { useScroll } from './useScroll.js'\nexport type { ScrollSignal, ScrollValue } from './useScroll.js'\n\nexport { useAnimatableUniform } from './useAnimatableUniform.js'\nexport type { AnimatableProp, MatterSignal } from './useAnimatableUniform.js'\n\nexport { FallbackBoundary } from './FallbackBoundary.js'\nexport type { FallbackBoundaryProps } from './FallbackBoundary.js'\n\nexport { useStaticHint } from './useStaticHint.js'\n\nexport { MatterMonitor } from './MatterMonitor.js'\nexport type { MatterMonitorProps, MonitorAnchor } from './MatterMonitor.js'\n","'use client'\n\nimport { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react'\nimport { Scene, OrthographicCamera } from 'three'\nimport { createRenderer, MatterScheduler, createVisibilityWatcher, createIntersectionWatcher } from '@lovo/matter'\nimport { MatterContext, type MatterContextValue } from './matter-context.js'\n\nexport interface MatterSceneProps {\n  children?: ReactNode\n  /** Rendered server-side and during WebGPU init. Default: empty. */\n  fallback?: ReactNode\n  className?: string\n  style?: CSSProperties\n  /** Cap on devicePixelRatio. Default: 2. */\n  maxDPR?: number\n}\n\nconst defaultStyle: CSSProperties = {\n  position: 'absolute',\n  inset: 0,\n  display: 'block',\n  width: '100%',\n  height: '100%',\n}\n\n/**\n * Owns a canvas, a Three.js renderer (WebGPU + WebGL2 fallback), an\n * orthographic camera covering the canvas, an empty Scene, and a\n * MatterScheduler. Children consume these via useMatterContext().\n */\nexport function MatterScene(props: MatterSceneProps) {\n  const { children, fallback, className, style, maxDPR } = props\n  const canvasRef = useRef<HTMLCanvasElement>(null)\n  const [ctx, setCtx] = useState<MatterContextValue | null>(null)\n  const [error, setError] = useState<Error | null>(null)\n\n  useEffect(() => {\n    const canvas = canvasRef.current\n    if (!canvas) return\n\n    let cancelled = false\n    let cleanup: (() => void) | null = null\n\n    const setup = async () => {\n      try {\n        const renderer = await createRenderer(canvas, { maxDPR })\n        if (cancelled) {\n          renderer.dispose()\n          return\n        }\n        const scene = new Scene()\n        const camera = new OrthographicCamera(-1, 1, 1, -1, 0.1, 10)\n        camera.position.z = 1\n        const scheduler = new MatterScheduler()\n\n        scheduler.add(() => renderer.three.render(scene, camera))\n        scheduler.start()\n\n        const visibility = createVisibilityWatcher()\n        const intersection = createIntersectionWatcher(canvas)\n\n        const updatePauseState = () => {\n          const shouldRun = visibility.isVisible() && intersection.isInView()\n          if (shouldRun) scheduler.resume()\n          else scheduler.pause()\n        }\n        updatePauseState()\n\n        const unsubVisibility = visibility.subscribe(updatePauseState)\n        const unsubIntersection = intersection.subscribe(updatePauseState)\n\n        const onResize = () => renderer.resize()\n        window.addEventListener('resize', onResize)\n\n        cleanup = () => {\n          unsubVisibility()\n          unsubIntersection()\n          visibility.dispose()\n          intersection.dispose()\n          window.removeEventListener('resize', onResize)\n          scheduler.dispose()\n          renderer.dispose()\n        }\n\n        setCtx({ renderer, scene, camera, scheduler })\n      } catch (err) {\n        if (cancelled) return\n        const e = err instanceof Error ? err : new Error(String(err))\n        // eslint-disable-next-line no-console\n        console.error('[MatterScene] renderer init failed:', e)\n        setError(e)\n      }\n    }\n\n    void setup()\n    return () => {\n      cancelled = true\n      cleanup?.()\n      cleanup = null\n      setCtx(null)\n    }\n  }, [maxDPR])\n\n  return (\n    <div className={className} style={{ ...defaultStyle, ...style }}>\n      <canvas ref={canvasRef} style={{ width: '100%', height: '100%', display: 'block' }} />\n      {error ? (\n        <div\n          style={{\n            position: 'absolute',\n            inset: 0,\n            display: 'flex',\n            alignItems: 'center',\n            justifyContent: 'center',\n            padding: '1rem',\n            color: '#fff',\n            background: 'rgba(120, 30, 30, 0.85)',\n            font: '0.85rem ui-monospace, monospace',\n            whiteSpace: 'pre-wrap',\n            textAlign: 'center',\n          }}\n        >\n          MatterScene init failed:\n          {'\\n'}\n          {error.message}\n        </div>\n      ) : ctx ? (\n        <MatterContext.Provider value={ctx}>{children}</MatterContext.Provider>\n      ) : (\n        fallback ?? null\n      )}\n    </div>\n  )\n}\n","import { createContext } from 'react'\nimport type { Scene, Camera } from 'three'\nimport type { MatterRenderer, MatterScheduler } from '@lovo/matter'\n\nexport interface MatterContextValue {\n  renderer: MatterRenderer\n  scene: Scene\n  camera: Camera\n  scheduler: MatterScheduler\n}\n\nexport const MatterContext = createContext<MatterContextValue | null>(null)\n","import { useContext } from 'react'\nimport { MatterContext, type MatterContextValue } from './matter-context.js'\n\n/**\n * Read the matter scene context. Returns null when called outside a\n * <MatterScene>; useShaderMaterial and similar hooks check this and\n * auto-provision a scene if missing (auto-wrap behavior).\n */\nexport function useMatterContext(): MatterContextValue | null {\n  return useContext(MatterContext)\n}\n","'use client'\n\nimport { useEffect, useMemo } from 'react'\nimport { MeshBasicNodeMaterial } from 'three/webgpu'\nimport type { Node } from 'three/webgpu'\nimport type { ShaderNodeObject } from 'three/tsl'\n\n/** A TSL fragment that produces a color. Accept any Node or TSL-wrapped node. */\nexport type ColorTSL = Node | ShaderNodeObject<Node>\n\n/**\n * Bind a TSL color expression to a NodeMaterial. Returns the material;\n * caller is responsible for adding it to a mesh and disposing when done.\n *\n * The TSL fragment is computed once via `useMemo` and re-applied if the\n * factory function changes. For dynamic uniforms, mutate `.value` on the\n * uniform nodes — don't recreate the TSL fragment per render.\n */\nexport function useShaderMaterial(build: () => ColorTSL): MeshBasicNodeMaterial {\n  const material = useMemo(() => {\n    const m = new MeshBasicNodeMaterial()\n    m.colorNode = build() as Node\n    return m\n  }, [build])\n\n  useEffect(() => {\n    return () => material.dispose()\n  }, [material])\n\n  return material\n}\n","'use client'\n\nimport { useEffect, useState } from 'react'\nimport { CursorInput, type CursorInputOptions, type Vec2 } from '@lovo/matter'\nimport { useMatterContext } from './useMatterContext.js'\n\nexport interface CursorSignal {\n  /** Current smoothed cursor position (Vec2 in 0..1 viewport space). */\n  get(): Vec2\n  /** Subscribe to change events. Returns unsubscribe. */\n  on(event: 'change', cb: (value: Vec2) => void): () => void\n}\n\n// Inert stub returned on the first render before the lifecycle effect\n// has created the real CursorInput. Calling .on returns an unsub no-op.\nconst STUB_SIGNAL: CursorSignal = {\n  get: () => [0.5, 0.5] as const,\n  on: () => () => undefined,\n}\n\n/**\n * React wrapper for CursorInput. Auto-attaches to the parent <MatterScene>'s\n * scheduler if available; otherwise creates a free-running rAF tick.\n *\n * Lifecycle is in a single effect so React 19 Strict Mode's intentional\n * mount→unmount→mount cycle creates a *fresh* CursorInput per real mount\n * instead of disposing a long-lived one (which would silently break the\n * window mousemove listener and the smoothing tick).\n */\nexport function useCursor(opts: CursorInputOptions = {}): CursorSignal {\n  const ctx = useMatterContext()\n  const [input, setInput] = useState<CursorInput | null>(null)\n\n  useEffect(() => {\n    // Plumb the parent <MatterScene>'s canvas as the cursor's normalization\n    // element. Without this, cursor coords are viewport-normalized — fine for\n    // a full-page scene but visibly offset when the canvas sits inside a\n    // smaller wrapper (e.g., 70vh hero). DotField's cell tiling makes the\n    // mismatch obvious; LinearGradient mostly gets away with it. Caller can\n    // override by passing `opts.element` explicitly.\n    const canvas = ctx?.renderer.three.domElement\n    const elementOpt = opts.element ?? (canvas instanceof HTMLElement ? canvas : undefined)\n    const fresh = new CursorInput({ ...opts, element: elementOpt })\n    setInput(fresh)\n\n    let detach: (() => void) | null = null\n    if (ctx?.scheduler) {\n      const client = ({ delta }: { delta: number }) => fresh.tick(delta)\n      ctx.scheduler.add(client)\n      detach = () => ctx.scheduler.remove(client)\n    } else {\n      let raf: number | null = null\n      let lastNow = performance.now()\n      const loop = (now: number) => {\n        const delta = (now - lastNow) / 1000\n        lastNow = now\n        fresh.tick(delta)\n        raf = requestAnimationFrame(loop)\n      }\n      raf = requestAnimationFrame(loop)\n      detach = () => {\n        if (raf !== null) cancelAnimationFrame(raf)\n      }\n    }\n\n    return () => {\n      detach?.()\n      fresh.dispose()\n      setInput(null)\n    }\n    // We intentionally only re-create on ctx change, not opts (which is a\n    // fresh object literal each render). Smoothing tweaks during dev are\n    // applied by remounting the parent component.\n  }, [ctx])\n\n  return input ?? STUB_SIGNAL\n}\n","'use client'\n\nimport { useEffect, useState } from 'react'\nimport { useMatterContext } from './useMatterContext.js'\n\nexport type ResizeValue = readonly [width: number, height: number, dpr: number]\n\nexport interface ResizeSignal {\n  /** Current size in CSS pixels + devicePixelRatio. */\n  get(): ResizeValue\n  on(event: 'change', cb: (value: ResizeValue) => void): () => void\n}\n\n// Inert stub returned on the first render before the lifecycle effect has\n// observed the canvas. Subscribing to it returns a no-op unsubscribe.\nconst STUB_SIGNAL: ResizeSignal = {\n  get: () => [0, 0, 1] as const,\n  on: () => () => undefined,\n}\n\n/**\n * Track the parent <MatterScene>'s canvas size + DPR. Exposes a MatterSignal\n * that components can pass into a TSL uniform to make pixel-aware effects\n * (e.g., DotField's pixel-spacing math).\n *\n * Strict-Mode-safe: lifecycle is in one effect, so React 19's intentional\n * mount→unmount→mount cycle creates a fresh ResizeObserver per real mount\n * (CLAUDE.md gotcha #14).\n *\n * Falls back to the stub signal until the parent context is ready.\n */\nexport function useResize(): ResizeSignal {\n  const ctx = useMatterContext()\n  const [signal, setSignal] = useState<ResizeSignal | null>(null)\n\n  useEffect(() => {\n    if (!ctx) return undefined\n\n    const canvas = ctx.renderer.three.domElement\n    if (!(canvas instanceof HTMLCanvasElement)) return undefined\n\n    let value: ResizeValue = [\n      canvas.clientWidth,\n      canvas.clientHeight,\n      typeof window !== 'undefined' ? window.devicePixelRatio : 1,\n    ]\n    const listeners = new Set<(v: ResizeValue) => void>()\n    const fresh: ResizeSignal = {\n      get: () => value,\n      on: (_event, cb) => {\n        listeners.add(cb)\n        return () => {\n          listeners.delete(cb)\n        }\n      },\n    }\n    setSignal(fresh)\n\n    const emit = () => {\n      const next: ResizeValue = [\n        canvas.clientWidth,\n        canvas.clientHeight,\n        typeof window !== 'undefined' ? window.devicePixelRatio : 1,\n      ]\n      if (next[0] === value[0] && next[1] === value[1] && next[2] === value[2]) return\n      value = next\n      for (const cb of listeners) cb(next)\n    }\n\n    const observer = new ResizeObserver(emit)\n    observer.observe(canvas)\n\n    // Cross-browser DPR-change watch. matchMedia(`(resolution: <dpr>dppx)`)\n    // matches at the *current* DPR; when the user zooms the page the query\n    // stops matching, fires `change`, and we re-arm the watch at the new DPR.\n    // We track the current MQL + handler so we can fully detach in cleanup\n    // (the handler is captured by the listener — passing a fresh closure to\n    // removeEventListener wouldn't actually unregister it).\n    let mql: MediaQueryList | null = null\n    let mqlHandler: (() => void) | null = null\n    const setupDprWatch = () => {\n      if (typeof window === 'undefined') return\n      const dpr = window.devicePixelRatio\n      const next = window.matchMedia(`(resolution: ${dpr}dppx)`)\n      const handler = () => {\n        emit()\n        if (mql && mqlHandler) mql.removeEventListener('change', mqlHandler)\n        setupDprWatch()\n      }\n      next.addEventListener('change', handler)\n      mql = next\n      mqlHandler = handler\n    }\n    setupDprWatch()\n\n    return () => {\n      observer.disconnect()\n      if (mql && mqlHandler) mql.removeEventListener('change', mqlHandler)\n      mql = null\n      mqlHandler = null\n      listeners.clear()\n      setSignal(null)\n    }\n  }, [ctx])\n\n  return signal ?? STUB_SIGNAL\n}\n","'use client'\n\nimport { useEffect, useState } from 'react'\n\nexport type ScrollValue = readonly [scrollY: number, progress: number]\n\nexport interface ScrollSignal {\n  /** Current scroll Y (px) and normalized progress in [0,1]. */\n  get(): ScrollValue\n  on(event: 'change', cb: (value: ScrollValue) => void): () => void\n}\n\n// Inert stub returned during SSR + on the first client render before the\n// lifecycle effect attaches. Subscribing to it returns a no-op unsubscribe.\nconst STUB_SIGNAL: ScrollSignal = {\n  get: () => [0, 0] as const,\n  on: () => () => undefined,\n}\n\n/**\n * Track window scroll position. Exposes a MatterSignal of `[scrollY, progress]`\n * where `progress` is `scrollY / max(documentHeight - innerHeight, 1)` clamped\n * to [0, 1]. Listener is rAF-throttled and `passive: true` so it never blocks\n * scrolling.\n *\n * No v1 Tier 1 component consumes this hook; it ships so users can pass\n * `inputs={{ scroll: useScroll() }}` to any Matter component.\n *\n * Strict-Mode-safe: lifecycle is in one effect, so React 19's intentional\n * mount→unmount→mount cycle in dev creates a fresh listener pair per real\n * mount and tears down cleanly on each pseudo-unmount (CLAUDE.md gotcha #14).\n *\n * **Known limitation (v1):** `progress` is computed against whichever\n * `documentHeight` was current when the last scroll fired. If the page grows\n * after mount (async content, font load reflow, expanding panels) without\n * the user scrolling, the denominator goes stale. A future ResizeObserver/\n * MutationObserver pass would close the gap; deferred until a v1 component\n * consumes scroll input.\n */\nexport function useScroll(): ScrollSignal {\n  const [signal, setSignal] = useState<ScrollSignal | null>(null)\n\n  useEffect(() => {\n    if (typeof window === 'undefined') return undefined\n\n    const compute = (): ScrollValue => {\n      const y = window.scrollY\n      // For pages shorter than the viewport, `documentHeight - innerHeight` is\n      // <= 0; clamp to 1 to avoid div-by-zero. Progress stays at 0 in that\n      // case because scrollY is also 0.\n      const max = Math.max(document.documentElement.scrollHeight - window.innerHeight, 1)\n      const progress = Math.max(0, Math.min(1, y / max))\n      return [y, progress]\n    }\n\n    let value: ScrollValue = compute()\n    const listeners = new Set<(v: ScrollValue) => void>()\n    const fresh: ScrollSignal = {\n      get: () => value,\n      on: (_event, cb) => {\n        listeners.add(cb)\n        return () => {\n          listeners.delete(cb)\n        }\n      },\n    }\n    setSignal(fresh)\n\n    let rafPending = false\n    const onScroll = () => {\n      if (rafPending) return\n      rafPending = true\n      requestAnimationFrame(() => {\n        rafPending = false\n        const next = compute()\n        if (next[0] === value[0] && next[1] === value[1]) return\n        value = next\n        for (const cb of listeners) cb(next)\n      })\n    }\n    window.addEventListener('scroll', onScroll, { passive: true })\n\n    return () => {\n      window.removeEventListener('scroll', onScroll)\n      listeners.clear()\n      setSignal(null)\n    }\n  }, [])\n\n  return signal ?? STUB_SIGNAL\n}\n","'use client'\n\nimport { useEffect, useMemo } from 'react'\nimport { uniform } from 'three/tsl'\nimport type { ShaderNodeObject } from 'three/tsl'\nimport type { Node } from 'three/webgpu'\n\nexport interface MatterSignal<T> {\n  get(): T\n  on(event: 'change', cb: (value: T) => void): () => void\n}\n\nexport type AnimatableProp<T> = T | MatterSignal<T>\n\nconst isSignal = <T>(value: AnimatableProp<T>): value is MatterSignal<T> => {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as MatterSignal<T>).get === 'function' &&\n    typeof (value as MatterSignal<T>).on === 'function'\n  )\n}\n\n/**\n * Bind an AnimatableProp<T> to a TSL uniform. Plain values create a\n * static uniform that updates only when the prop changes (React render\n * path). Signals subscribe via .on('change') and write into the uniform\n * imperatively without re-rendering.\n */\nexport function useAnimatableUniform<T>(value: AnimatableProp<T>): ShaderNodeObject<Node> {\n  // Create the uniform once with the initial value; subsequent updates flow\n  // through the effect below (either via signal subscription or direct write).\n  const uniformNode = useMemo(() => {\n    const initial = isSignal(value) ? value.get() : value\n    return uniform(initial) as unknown as ShaderNodeObject<Node>\n  }, [])\n\n  useEffect(() => {\n    if (isSignal(value)) {\n      const unsub = value.on('change', (next) => {\n        ;(uniformNode as unknown as { value: T }).value = next\n      })\n      return unsub\n    }\n    ;(uniformNode as unknown as { value: T }).value = value\n    return undefined\n  }, [value, uniformNode])\n\n  return uniformNode\n}\n","'use client'\n\nimport { useEffect, useState, type ReactNode } from 'react'\n\nexport interface FallbackBoundaryProps {\n  /** Rendered until WebGPU/WebGL is available on the client. */\n  fallback?: ReactNode\n  children: ReactNode\n}\n\n/**\n * Render `fallback` until the component mounts on the client. Gates the\n * children behind client-only mounting so SSR/no-WebGPU users see a\n * sensible static placeholder rather than a flash of nothing.\n */\nexport function FallbackBoundary({ fallback, children }: FallbackBoundaryProps) {\n  const [mounted, setMounted] = useState(false)\n  useEffect(() => {\n    setMounted(true)\n  }, [])\n  return <>{mounted ? children : fallback ?? null}</>\n}\n","'use client'\n\nimport { useEffect } from 'react'\nimport { useMatterContext } from './useMatterContext.js'\n\n/**\n * Opt a component out of the rAF loop while it has no dynamic uniforms.\n *\n * When `hint` is true, the scheduler runs one final flush tick (so any\n * uniform changes since the last frame are rendered) and then halts the\n * rAF loop until either `hint` becomes false or another component in the\n * same scene calls `scheduler.requestRender()`.\n *\n * Use for components whose animation is fully derived from props that don't\n * include `time`, e.g. `<LinearGradient speed={0}>` with no `interactive`.\n */\nexport function useStaticHint(hint: boolean): void {\n  const ctx = useMatterContext()\n  useEffect(() => {\n    if (!ctx) return\n    ctx.scheduler.setIdle(hint)\n    return () => ctx.scheduler.setIdle(false)\n  }, [ctx, hint])\n}\n","'use client'\n\nimport { useEffect, useRef, useState, useContext, type CSSProperties } from 'react'\nimport { MatterContext } from './matter-context.js'\n\nexport type MonitorAnchor = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'\n\nconst anchorStyle: Record<MonitorAnchor, CSSProperties> = {\n  'top-left': { top: 8, left: 8 },\n  'top-right': { top: 8, right: 8 },\n  'bottom-left': { bottom: 8, left: 8 },\n  'bottom-right': { bottom: 8, right: 8 },\n}\n\nconst baseStyle: CSSProperties = {\n  position: 'absolute',\n  zIndex: 10,\n  padding: '6px 8px',\n  borderRadius: 6,\n  background: 'rgba(0, 0, 0, 0.6)',\n  color: '#fff',\n  font: '11px ui-monospace, monospace',\n  lineHeight: 1.4,\n  pointerEvents: 'none',\n  whiteSpace: 'pre',\n}\n\nexport interface MatterMonitorProps {\n  anchor?: MonitorAnchor\n}\n\n/**\n * Dev-only overlay that displays the current scene's FPS, tick count, and\n * paused/idle state. Reads from the surrounding `<MatterScene>` via context\n * and subscribes to its scheduler. Renders nothing useful if mounted outside\n * a scene.\n */\nexport function MatterMonitor({ anchor = 'top-right' }: MatterMonitorProps) {\n  const ctx = useContext(MatterContext)\n  const [stats, setStats] = useState({ fps: 0, ticks: 0, frames: 0 })\n  const ticksRef = useRef(0)\n  const fpsAccumRef = useRef({ frames: 0, lastSampleAt: 0, fps: 0 })\n\n  useEffect(() => {\n    if (!ctx) return\n    const client = (tick: { now: number }) => {\n      ticksRef.current += 1\n      const acc = fpsAccumRef.current\n      acc.frames += 1\n      if (acc.lastSampleAt === 0) acc.lastSampleAt = tick.now\n      const dt = tick.now - acc.lastSampleAt\n      if (dt >= 500) {\n        acc.fps = Math.round((acc.frames * 1000) / dt)\n        acc.frames = 0\n        acc.lastSampleAt = tick.now\n      }\n      setStats({ fps: acc.fps, ticks: ticksRef.current, frames: acc.frames })\n    }\n    ctx.scheduler.add(client)\n    return () => ctx.scheduler.remove(client)\n  }, [ctx])\n\n  if (!ctx) {\n    return (\n      <div data-testid=\"matter-monitor\" style={{ ...baseStyle, ...anchorStyle[anchor] }}>\n        no scene\n      </div>\n    )\n  }\n\n  return (\n    <div data-testid=\"matter-monitor\" style={{ ...baseStyle, ...anchorStyle[anchor] }}>\n      <span data-testid=\"matter-monitor-fps\">fps: {stats.fps || '—'}</span>\n      {'\\n'}\n      <span data-testid=\"matter-monitor-ticks\">ticks: {stats.ticks}</span>\n    </div>\n  )\n}\n"],"mappings":"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","names":["import_react","import_react","import_react","import_react","import_matter","import_react","STUB_SIGNAL","import_react","STUB_SIGNAL","import_react","import_react","import_jsx_runtime","import_react","import_react","import_jsx_runtime"]}

package/dist/index.d.cts

@@ -0,0 +1,164 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties } from 'react';
+import { Scene, Camera } from 'three';
+import { MatterRenderer, MatterScheduler, Vec2, CursorInputOptions } from '@lovo/matter';
+import { Node, MeshBasicNodeMaterial } from 'three/webgpu';
+import { ShaderNodeObject } from 'three/tsl';
+
+interface MatterSceneProps {
+    children?: ReactNode;
+    /** Rendered server-side and during WebGPU init. Default: empty. */
+    fallback?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Cap on devicePixelRatio. Default: 2. */
+    maxDPR?: number;
+}
+/**
+ * Owns a canvas, a Three.js renderer (WebGPU + WebGL2 fallback), an
+ * orthographic camera covering the canvas, an empty Scene, and a
+ * MatterScheduler. Children consume these via useMatterContext().
+ */
+declare function MatterScene(props: MatterSceneProps): react_jsx_runtime.JSX.Element;
+
+interface MatterContextValue {
+    renderer: MatterRenderer;
+    scene: Scene;
+    camera: Camera;
+    scheduler: MatterScheduler;
+}
+
+/**
+ * Read the matter scene context. Returns null when called outside a
+ * <MatterScene>; useShaderMaterial and similar hooks check this and
+ * auto-provision a scene if missing (auto-wrap behavior).
+ */
+declare function useMatterContext(): MatterContextValue | null;
+
+/** A TSL fragment that produces a color. Accept any Node or TSL-wrapped node. */
+type ColorTSL = Node | ShaderNodeObject<Node>;
+/**
+ * Bind a TSL color expression to a NodeMaterial. Returns the material;
+ * caller is responsible for adding it to a mesh and disposing when done.
+ *
+ * The TSL fragment is computed once via `useMemo` and re-applied if the
+ * factory function changes. For dynamic uniforms, mutate `.value` on the
+ * uniform nodes — don't recreate the TSL fragment per render.
+ */
+declare function useShaderMaterial(build: () => ColorTSL): MeshBasicNodeMaterial;
+
+interface CursorSignal {
+    /** Current smoothed cursor position (Vec2 in 0..1 viewport space). */
+    get(): Vec2;
+    /** Subscribe to change events. Returns unsubscribe. */
+    on(event: 'change', cb: (value: Vec2) => void): () => void;
+}
+/**
+ * React wrapper for CursorInput. Auto-attaches to the parent <MatterScene>'s
+ * scheduler if available; otherwise creates a free-running rAF tick.
+ *
+ * Lifecycle is in a single effect so React 19 Strict Mode's intentional
+ * mount→unmount→mount cycle creates a *fresh* CursorInput per real mount
+ * instead of disposing a long-lived one (which would silently break the
+ * window mousemove listener and the smoothing tick).
+ */
+declare function useCursor(opts?: CursorInputOptions): CursorSignal;
+
+type ResizeValue = readonly [width: number, height: number, dpr: number];
+interface ResizeSignal {
+    /** Current size in CSS pixels + devicePixelRatio. */
+    get(): ResizeValue;
+    on(event: 'change', cb: (value: ResizeValue) => void): () => void;
+}
+/**
+ * Track the parent <MatterScene>'s canvas size + DPR. Exposes a MatterSignal
+ * that components can pass into a TSL uniform to make pixel-aware effects
+ * (e.g., DotField's pixel-spacing math).
+ *
+ * Strict-Mode-safe: lifecycle is in one effect, so React 19's intentional
+ * mount→unmount→mount cycle creates a fresh ResizeObserver per real mount
+ * (CLAUDE.md gotcha #14).
+ *
+ * Falls back to the stub signal until the parent context is ready.
+ */
+declare function useResize(): ResizeSignal;
+
+type ScrollValue = readonly [scrollY: number, progress: number];
+interface ScrollSignal {
+    /** Current scroll Y (px) and normalized progress in [0,1]. */
+    get(): ScrollValue;
+    on(event: 'change', cb: (value: ScrollValue) => void): () => void;
+}
+/**
+ * Track window scroll position. Exposes a MatterSignal of `[scrollY, progress]`
+ * where `progress` is `scrollY / max(documentHeight - innerHeight, 1)` clamped
+ * to [0, 1]. Listener is rAF-throttled and `passive: true` so it never blocks
+ * scrolling.
+ *
+ * No v1 Tier 1 component consumes this hook; it ships so users can pass
+ * `inputs={{ scroll: useScroll() }}` to any Matter component.
+ *
+ * Strict-Mode-safe: lifecycle is in one effect, so React 19's intentional
+ * mount→unmount→mount cycle in dev creates a fresh listener pair per real
+ * mount and tears down cleanly on each pseudo-unmount (CLAUDE.md gotcha #14).
+ *
+ * **Known limitation (v1):** `progress` is computed against whichever
+ * `documentHeight` was current when the last scroll fired. If the page grows
+ * after mount (async content, font load reflow, expanding panels) without
+ * the user scrolling, the denominator goes stale. A future ResizeObserver/
+ * MutationObserver pass would close the gap; deferred until a v1 component
+ * consumes scroll input.
+ */
+declare function useScroll(): ScrollSignal;
+
+interface MatterSignal<T> {
+    get(): T;
+    on(event: 'change', cb: (value: T) => void): () => void;
+}
+type AnimatableProp<T> = T | MatterSignal<T>;
+/**
+ * Bind an AnimatableProp<T> to a TSL uniform. Plain values create a
+ * static uniform that updates only when the prop changes (React render
+ * path). Signals subscribe via .on('change') and write into the uniform
+ * imperatively without re-rendering.
+ */
+declare function useAnimatableUniform<T>(value: AnimatableProp<T>): ShaderNodeObject<Node>;
+
+interface FallbackBoundaryProps {
+    /** Rendered until WebGPU/WebGL is available on the client. */
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * Render `fallback` until the component mounts on the client. Gates the
+ * children behind client-only mounting so SSR/no-WebGPU users see a
+ * sensible static placeholder rather than a flash of nothing.
+ */
+declare function FallbackBoundary({ fallback, children }: FallbackBoundaryProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Opt a component out of the rAF loop while it has no dynamic uniforms.
+ *
+ * When `hint` is true, the scheduler runs one final flush tick (so any
+ * uniform changes since the last frame are rendered) and then halts the
+ * rAF loop until either `hint` becomes false or another component in the
+ * same scene calls `scheduler.requestRender()`.
+ *
+ * Use for components whose animation is fully derived from props that don't
+ * include `time`, e.g. `<LinearGradient speed={0}>` with no `interactive`.
+ */
+declare function useStaticHint(hint: boolean): void;
+
+type MonitorAnchor = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface MatterMonitorProps {
+    anchor?: MonitorAnchor;
+}
+/**
+ * Dev-only overlay that displays the current scene's FPS, tick count, and
+ * paused/idle state. Reads from the surrounding `<MatterScene>` via context
+ * and subscribes to its scheduler. Renders nothing useful if mounted outside
+ * a scene.
+ */
+declare function MatterMonitor({ anchor }: MatterMonitorProps): react_jsx_runtime.JSX.Element;
+
+export { type AnimatableProp, type CursorSignal, FallbackBoundary, type FallbackBoundaryProps, type MatterContextValue, MatterMonitor, type MatterMonitorProps, MatterScene, type MatterSceneProps, type MatterSignal, type MonitorAnchor, type ResizeSignal, type ResizeValue, type ScrollSignal, type ScrollValue, useAnimatableUniform, useCursor, useMatterContext, useResize, useScroll, useShaderMaterial, useStaticHint };