@lovo/matter-react 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -2,47 +2,28 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties, DependencyList } from 'react';
 import { ShaderNodeObject } from 'three/tsl';
 import { Node, MeshBasicNodeMaterial } from 'three/webgpu';
-import { Vec2, CursorInputOptions, GpuRenderer, FrameScheduler } from '@lovo/matter';
+import { Vector2, 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;
 
-type MonitorAnchor = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+type ShaderMonitorAnchor = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 interface ShaderMonitorProps {
-    anchor?: MonitorAnchor;
+    anchor?: ShaderMonitorAnchor;
 }
-/**
- * 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;
     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
- * FrameScheduler. Children consume these via useShaderContext().
- */
 declare function ShaderScene(props: ShaderSceneProps): react_jsx_runtime.JSX.Element;
 
 interface AnimatableSignal<T> {
@@ -50,142 +31,46 @@ interface AnimatableSignal<T> {
     on(event: 'change', cb: (value: T) => void): () => void;
 }
 type AnimatableProp<T> = T | AnimatableSignal<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.
- *
- * 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 useAnimatableUniform<T>(value: AnimatableProp<T>): ShaderNodeObject<Node> & {
     value: T;
 };
 
 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;
+    get(): Vector2;
+    on(event: 'change', cb: (value: Vector2) => void): () => void;
 }
-/**
- * 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
- * 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 OverlayTransform = (input: ShaderNodeObject<Node>) => ShaderNodeObject<Node>;
+type PostProcessTransform = (input: ShaderNodeObject<Node>) => ShaderNodeObject<Node>;
 interface ShaderContextValue {
     renderer: GpuRenderer;
     scene: Scene;
     camera: Camera;
     scheduler: FrameScheduler;
-    registerOverlay: (transform: OverlayTransform) => () => void;
+    registerOverlay: (transform: PostProcessTransform) => () => 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;
+declare function usePostProcessPass(transform: PostProcessTransform, deps: DependencyList): void;
 
 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 <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).
- *
- * 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 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.
- *
- * 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;
 
-/** 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;
 
-/**
- * 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;
+declare function useStaticSceneHint(isStatic: boolean): void;
 
-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 };
+export { type AnimatableProp, type AnimatableSignal, type CursorSignal, FallbackBoundary, type FallbackBoundaryProps, type PostProcessTransform, type ResizeSignal, type ResizeValue, type ScrollSignal, type ScrollValue, type ShaderContextValue, ShaderMonitor, type ShaderMonitorAnchor, type ShaderMonitorProps, ShaderScene, type ShaderSceneProps, useAnimatableUniform, useCursor, usePostProcessPass, useResize, useScroll, useShaderContext, useShaderMaterial, useStaticSceneHint };

package/dist/index.d.ts

@@ -2,47 +2,28 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties, DependencyList } from 'react';
 import { ShaderNodeObject } from 'three/tsl';
 import { Node, MeshBasicNodeMaterial } from 'three/webgpu';
-import { Vec2, CursorInputOptions, GpuRenderer, FrameScheduler } from '@lovo/matter';
+import { Vector2, 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;
 
-type MonitorAnchor = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+type ShaderMonitorAnchor = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 interface ShaderMonitorProps {
-    anchor?: MonitorAnchor;
+    anchor?: ShaderMonitorAnchor;
 }
-/**
- * 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;
     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
- * FrameScheduler. Children consume these via useShaderContext().
- */
 declare function ShaderScene(props: ShaderSceneProps): react_jsx_runtime.JSX.Element;
 
 interface AnimatableSignal<T> {
@@ -50,142 +31,46 @@ interface AnimatableSignal<T> {
     on(event: 'change', cb: (value: T) => void): () => void;
 }
 type AnimatableProp<T> = T | AnimatableSignal<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.
- *
- * 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 useAnimatableUniform<T>(value: AnimatableProp<T>): ShaderNodeObject<Node> & {
     value: T;
 };
 
 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;
+    get(): Vector2;
+    on(event: 'change', cb: (value: Vector2) => void): () => void;
 }
-/**
- * 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
- * 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 OverlayTransform = (input: ShaderNodeObject<Node>) => ShaderNodeObject<Node>;
+type PostProcessTransform = (input: ShaderNodeObject<Node>) => ShaderNodeObject<Node>;
 interface ShaderContextValue {
     renderer: GpuRenderer;
     scene: Scene;
     camera: Camera;
     scheduler: FrameScheduler;
-    registerOverlay: (transform: OverlayTransform) => () => void;
+    registerOverlay: (transform: PostProcessTransform) => () => 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;
+declare function usePostProcessPass(transform: PostProcessTransform, deps: DependencyList): void;
 
 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 <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).
- *
- * 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 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.
- *
- * 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;
 
-/** 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;
 
-/**
- * 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;
+declare function useStaticSceneHint(isStatic: boolean): void;
 
-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 };
+export { type AnimatableProp, type AnimatableSignal, type CursorSignal, FallbackBoundary, type FallbackBoundaryProps, type PostProcessTransform, type ResizeSignal, type ResizeValue, type ScrollSignal, type ScrollValue, type ShaderContextValue, ShaderMonitor, type ShaderMonitorAnchor, type ShaderMonitorProps, ShaderScene, type ShaderSceneProps, useAnimatableUniform, useCursor, usePostProcessPass, useResize, useScroll, useShaderContext, useShaderMaterial, useStaticSceneHint };