@lovo/matter-react 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,11 +1,35 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties, DependencyList } from 'react';
-import { Scene, Camera } from 'three';
-import { Node, MeshBasicNodeMaterial } from 'three/webgpu';
 import { ShaderNodeObject } from 'three/tsl';
-import { MatterRenderer, MatterScheduler, Vec2, CursorInputOptions } from '@lovo/matter';
+import { Node, MeshBasicNodeMaterial } from 'three/webgpu';
+import { Vec2, CursorInputOptions, GpuRenderer, FrameScheduler } from '@lovo/matter';
+import { Scene, Camera } from 'three';
+
+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;
 
-interface MatterSceneProps {
+type MonitorAnchor = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface ShaderMonitorProps {
+    anchor?: MonitorAnchor;
+}
+/**
+ * Dev-only overlay that displays the current scene's FPS, tick count, and
+ * paused/idle state. Reads from the surrounding `<ShaderScene>` via context
+ * and subscribes to its scheduler. Renders nothing useful if mounted outside
+ * a scene.
+ */
+declare function ShaderMonitor({ anchor }: ShaderMonitorProps): react_jsx_runtime.JSX.Element;
+
+interface ShaderSceneProps {
     children?: ReactNode;
     /** Rendered server-side and during WebGPU init. Default: empty. */
     fallback?: ReactNode;
@@ -17,37 +41,31 @@ interface MatterSceneProps {
 /**
  * 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().
+ * FrameScheduler. Children consume these via useShaderContext().
  */
-declare function MatterScene(props: MatterSceneProps): react_jsx_runtime.JSX.Element;
+declare function ShaderScene(props: ShaderSceneProps): react_jsx_runtime.JSX.Element;
 
-type OverlayTransform = (input: ShaderNodeObject<Node>) => ShaderNodeObject<Node>;
-interface MatterContextValue {
-    renderer: MatterRenderer;
-    scene: Scene;
-    camera: Camera;
-    scheduler: MatterScheduler;
-    registerOverlay: (transform: OverlayTransform) => () => void;
+interface AnimatableSignal<T> {
+    get(): T;
+    on(event: 'change', cb: (value: T) => void): () => void;
 }
-
-/**
- * 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>;
+type AnimatableProp<T> = T | AnimatableSignal<T>;
 /**
- * Bind a TSL color expression to a NodeMaterial. Returns the material;
- * caller is responsible for adding it to a mesh and disposing when done.
+ * 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.
  *
- * 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.
+ * Returns a chainable TSL node with `.value: T` exposed for callers that
+ * need to read the current uniform value imperatively (e.g., to compute
+ * derived JS-side math). The runtime object is a UniformNode<T>; we
+ * present it as `ShaderNodeObject<Node> & { value: T }` because TSL's
+ * generic invariance blocks the more precise type from flowing through
+ * downstream consumers like OverlayTransform.
  */
-declare function useShaderMaterial(build: () => ColorTSL): MeshBasicNodeMaterial;
+declare function useAnimatableUniform<T>(value: AnimatableProp<T>): ShaderNodeObject<Node> & {
+    value: T;
+};
 
 interface CursorSignal {
     /** Current smoothed cursor position (Vec2 in 0..1 viewport space). */
@@ -56,7 +74,7 @@ interface CursorSignal {
     on(event: 'change', cb: (value: Vec2) => void): () => void;
 }
 /**
- * React wrapper for CursorInput. Auto-attaches to the parent <MatterScene>'s
+ * React wrapper for CursorInput. Auto-attaches to the parent <ShaderScene>'s
  * scheduler if available; otherwise creates a free-running rAF tick.
  *
  * Lifecycle is in a single effect so React 19 Strict Mode's intentional
@@ -66,6 +84,38 @@ interface CursorSignal {
  */
 declare function useCursor(opts?: CursorInputOptions): CursorSignal;
 
+type OverlayTransform = (input: ShaderNodeObject<Node>) => ShaderNodeObject<Node>;
+interface ShaderContextValue {
+    renderer: GpuRenderer;
+    scene: Scene;
+    camera: Camera;
+    scheduler: FrameScheduler;
+    registerOverlay: (transform: OverlayTransform) => () => void;
+}
+
+/**
+ * Read the shader scene context. Returns null when called outside a
+ * <ShaderScene>; useShaderMaterial and similar hooks check this.
+ */
+declare function useShaderContext(): ShaderContextValue | null;
+
+/**
+ * Register a TSL transform as an overlay pass on the parent <ShaderScene>.
+ *
+ * The transform takes the "color so far" — base scene + any earlier
+ * overlays as a TSL vec4 node — and returns a modified vec4. Registration
+ * happens on mount; unregistration on unmount. The hook re-registers
+ * whenever any value in `deps` changes (useEffect semantics): use this
+ * for structural changes (e.g., a `mode: 'additive' | 'subtractive'`
+ * toggle) that swap the transform function itself. Uniforms captured
+ * inside the transform mutate in place, so uniform value changes do
+ * NOT need to be in deps.
+ *
+ * When called outside a <ShaderScene> provider, this hook is a no-op.
+ * Matches the existing useShaderContext convention.
+ */
+declare function useOverlayPass(transform: OverlayTransform, deps: DependencyList): void;
+
 type ResizeValue = readonly [width: number, height: number, dpr: number];
 interface ResizeSignal {
     /** Current size in CSS pixels + devicePixelRatio. */
@@ -73,7 +123,7 @@ interface ResizeSignal {
     on(event: 'change', cb: (value: ResizeValue) => void): () => void;
 }
 /**
- * Track the parent <MatterScene>'s canvas size + DPR. Exposes a MatterSignal
+ * Track the parent <ShaderScene>'s canvas size + DPR. Exposes an AnimatableSignal
  * that components can pass into a TSL uniform to make pixel-aware effects
  * (e.g., DotField's pixel-spacing math).
  *
@@ -92,7 +142,7 @@ interface ScrollSignal {
     on(event: 'change', cb: (value: ScrollValue) => void): () => void;
 }
 /**
- * Track window scroll position. Exposes a MatterSignal of `[scrollY, progress]`
+ * Track window scroll position. Exposes an AnimatableSignal 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.
@@ -113,47 +163,17 @@ interface ScrollSignal {
  */
 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>;
-
+/** A TSL fragment that produces a color. Accept any Node or TSL-wrapped node. */
+type ColorTSL = Node | ShaderNodeObject<Node>;
 /**
- * Register a TSL transform as an overlay pass on the parent <MatterScene>.
- *
- * The transform takes the "color so far" — base scene + any earlier
- * overlays as a TSL vec4 node — and returns a modified vec4. Registration
- * happens on mount; unregistration on unmount. The hook re-registers
- * whenever any value in `deps` changes (useEffect semantics): use this
- * for structural changes (e.g., a `mode: 'additive' | 'subtractive'`
- * toggle) that swap the transform function itself. Uniforms captured
- * inside the transform mutate in place, so uniform value changes do
- * NOT need to be in deps.
+ * Bind a TSL color expression to a NodeMaterial. Returns the material;
+ * caller is responsible for adding it to a mesh and disposing when done.
  *
- * When called outside a <MatterScene> provider, this hook is a no-op.
- * Matches the existing useMatterContext convention.
- */
-declare function useOverlayPass(transform: OverlayTransform, deps: DependencyList): void;
-
-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.
+ * 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 FallbackBoundary({ fallback, children }: FallbackBoundaryProps): react_jsx_runtime.JSX.Element;
+declare function useShaderMaterial(build: () => ColorTSL): MeshBasicNodeMaterial;
 
 /**
  * Opt a component out of the rAF loop while it has no dynamic uniforms.
@@ -168,16 +188,4 @@ declare function FallbackBoundary({ fallback, children }: FallbackBoundaryProps)
  */
 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 OverlayTransform, type ResizeSignal, type ResizeValue, type ScrollSignal, type ScrollValue, useAnimatableUniform, useCursor, useMatterContext, useOverlayPass, useResize, useScroll, useShaderMaterial, useStaticHint };
+export { type AnimatableProp, type AnimatableSignal, type CursorSignal, FallbackBoundary, type FallbackBoundaryProps, type MonitorAnchor, type OverlayTransform, type ResizeSignal, type ResizeValue, type ScrollSignal, type ScrollValue, type ShaderContextValue, ShaderMonitor, type ShaderMonitorProps, ShaderScene, type ShaderSceneProps, useAnimatableUniform, useCursor, useOverlayPass, useResize, useScroll, useShaderContext, useShaderMaterial, useStaticHint };