@lovo/matter 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,361 @@
+import { WebGPURenderer, Node } from 'three/webgpu';
+import { Color } from 'three';
+import { ShaderNodeObject } from 'three/tsl';
+export { cos, dot, length, max, min, mix, mod, normalize, sin, smoothstep, uniform, uv, vec2, vec3, vec4 } from 'three/tsl';
+
+type MatterBackend = 'webgpu' | 'webgl2';
+interface CreateRendererOptions {
+    /** Anti-alias the framebuffer. Default: true. */
+    antialias?: boolean;
+    /** Force WebGL2 even if WebGPU is available (useful for testing fallback). Default: false. */
+    forceWebGL?: boolean;
+    /** Clear color (hex, CSS string, or THREE.Color). Default: transparent. */
+    clearColor?: number | string | Color;
+    /** Clear alpha (0–1). Default: 0 (transparent). */
+    clearAlpha?: number;
+    /** Cap on devicePixelRatio. Default: 2. Pass Infinity to disable. */
+    maxDPR?: number;
+}
+interface MatterRenderer {
+    /** The underlying Three.js WebGPURenderer (which may be running on a WebGL2 backend). */
+    three: WebGPURenderer;
+    /** Which backend the renderer initialized with. */
+    backend: MatterBackend;
+    /** Tear down the renderer and release GPU resources. */
+    dispose: () => void;
+    /** Resize the renderer to the canvas's current client dimensions. */
+    resize: () => void;
+}
+/**
+ * Create a Matter renderer wrapping THREE.WebGPURenderer.
+ *
+ * Tries WebGPU first; falls back to WebGL2 automatically if WebGPU is
+ * unavailable on the host. The returned object exposes the underlying
+ * three renderer plus a small wrapper for resize and disposal.
+ */
+declare function createRenderer(canvas: HTMLCanvasElement, opts?: CreateRendererOptions): Promise<MatterRenderer>;
+
+interface SchedulerTick {
+    /** Seconds since the previous tick. 0 on the first call. */
+    delta: number;
+    /** Total seconds since the scheduler started its current run. */
+    elapsed: number;
+    /** The raw `performance.now()` timestamp the rAF callback received. */
+    now: number;
+}
+type SchedulerClient = (tick: SchedulerTick) => void;
+/**
+ * Batches `requestAnimationFrame` calls across all clients registered with
+ * a single scheduler. One scheduler is created per <MatterScene>; clients
+ * are typically a Three.js renderer's render call.
+ */
+declare class MatterScheduler {
+    private readonly clients;
+    private rafId;
+    private running;
+    private paused;
+    private idle;
+    private flushPending;
+    private startedAt;
+    private lastTickAt;
+    /** Activate the scheduler. The rAF loop starts on the first client added. */
+    start(): void;
+    /** Halt the rAF loop entirely. Use dispose() for permanent teardown. */
+    stop(): void;
+    /** Temporarily skip ticks without losing client registrations. */
+    pause(): void;
+    /** Resume after pause(). */
+    resume(): void;
+    /** Register a client to be called every frame. */
+    add(client: SchedulerClient): void;
+    /** Unregister a client. */
+    remove(client: SchedulerClient): void;
+    /** Permanent teardown: stop the loop and drop all clients. */
+    dispose(): void;
+    /**
+     * Mark the scheduler idle. The next tick still fires (a final flush so
+     * uniform changes that triggered the idle state are rendered), then the
+     * rAF loop halts. Use `requestRender()` or `setIdle(false)` to wake.
+     */
+    setIdle(idle: boolean): void;
+    /** Force a single tick while idle. Useful for prop-change invalidation. */
+    requestRender(): void;
+    private maybeQueue;
+    private cancel;
+    private readonly frame;
+}
+
+type Vec2 = readonly [number, number];
+interface CursorInputOptions {
+    /**
+     * Smoothing factor: 0 = no smoothing (snap to target instantly).
+     * 1 = max smoothing (essentially never reaches target).
+     * Sensible default: 0.1.
+     *
+     * Implementation: per-frame, value moves toward target by `(1 - smoothing) * delta * 60`,
+     * roughly meaning "at smoothing=0.1, ~90% of the gap is closed in 1 second at 60fps."
+     */
+    smoothing?: number;
+    /** Starting position. Default: [0.5, 0.5] (center). */
+    initial?: Vec2;
+    /** Listen on this target. Default: window. */
+    target?: EventTarget;
+    /**
+     * Element to normalize cursor coordinates against. Default: window viewport.
+     *
+     * When set, cursor x/y are in [0,1] across the element's bounding rect, with
+     * extrapolation outside (negative when left/above, >1 when right/below). This
+     * matches what shader UV space expects: a cursor at the canvas's top-left
+     * corner reads as (0, 0); at bottom-right as (1, 1); regardless of where the
+     * canvas sits in the viewport. Without this, components inside a partial-
+     * viewport scene (e.g. a 70vh hero section) see a cursor offset that scales
+     * with the canvas's vertical position on the page.
+     */
+    element?: {
+        getBoundingClientRect(): {
+            left: number;
+            top: number;
+            width: number;
+            height: number;
+        };
+    };
+}
+type ChangeListener = (value: Vec2) => void;
+/**
+ * Smoothed pointer tracker emitting a normalized (0..1) Vec2 position.
+ * Implements the MatterSignal protocol (`get()` + `on('change', cb)`)
+ * so it composes with Motion's `useTransform` and similar tools.
+ */
+declare class CursorInput {
+    private value;
+    private target;
+    private targetDirty;
+    private readonly smoothing;
+    private readonly listeners;
+    private readonly eventTarget;
+    private readonly element;
+    private readonly handleMouseMove;
+    private disposed;
+    constructor(opts?: CursorInputOptions);
+    /** Current smoothed position. Implements MatterSignal protocol. */
+    get(): Vec2;
+    /** Subscribe to change events. Returns an unsubscribe function. */
+    on(_event: 'change', cb: ChangeListener): () => void;
+    /**
+     * Advance the smoothing one tick. Called by the host scheduler; not
+     * typically called directly except in tests.
+     */
+    tick(delta: number): void;
+    /** Tear down listeners. */
+    dispose(): void;
+}
+
+type TSLNode = Node | ShaderNodeObject<Node>;
+interface ColorRampStop {
+    /** Color expressed as a TSL node (typically `vec3(r,g,b)`). */
+    color: TSLNode;
+    /** Position 0..1 along the ramp. */
+    position: number;
+}
+/**
+ * Multi-stop color interpolation. Given a t in [0..1] and N color stops at
+ * fixed positions, returns the smoothly-interpolated color.
+ *
+ * Falls back to the first/last stop's color outside the bracketing positions.
+ */
+declare function colorRamp(t: TSLNode, stops: ColorRampStop[]): TSLNode;
+
+/**
+ * 2D simplex noise sampled at a point. Returns a scalar TSL node in
+ * approximately [-1, 1] (MaterialX's mx_noise_float is roughly that range).
+ *
+ * @param p — Vec2 TSL node (typically `uv()` or a scaled/offset uv).
+ *
+ * Built on top of three's `mx_noise_float`; we wrap it so consumers have a
+ * stable import path through `@lovo/matter` and we can swap the
+ * implementation if a different noise primitive proves better in practice.
+ */
+declare function noise(p: TSLNode): TSLNode;
+
+interface FBMOptions {
+    /** Number of octaves to sum. JS-side number — fixed at TSL build time, not a uniform. Default: 4. */
+    octaves?: number;
+    /** Per-octave frequency multiplier. JS-side number. Default: 2. */
+    lacunarity?: number;
+    /** Per-octave amplitude multiplier. JS-side number. Default: 0.5. */
+    gain?: number;
+}
+/**
+ * Fractal Brownian Motion — sum of N octaves of 2D simplex noise.
+ *
+ * `octaves`, `lacunarity`, and `gain` are JavaScript numbers (NOT TSL
+ * uniforms) because the loop must be unrolled at TSL-build time — TSL has
+ * no dynamic-length loop primitive that maps cleanly to all backends.
+ * Animatable parameters that *do* survive on the GPU are the input UV
+ * (which the caller can scale/translate per frame) and `time`.
+ *
+ * @param p — Vec2 TSL node (UV-space position).
+ * @returns scalar TSL node, roughly [-1..1] but normalized closer to
+ *          [-0.5..0.5] when amplitude sums approach 1 with the default gain.
+ */
+declare function fbm(p: TSLNode, opts?: FBMOptions): TSLNode;
+
+/**
+ * 2D voronoi (Worley) noise — distance to the nearest jittered cell point,
+ * normalized roughly to [0, 1]. Higher values = farther from any cell point
+ * (cell interiors); lower values = near a cell boundary.
+ *
+ * Built on three's `mx_worley_noise_float`. Combine with `colorRamp` for
+ * a multi-color cellular pattern; threshold via `step`/`smoothstep` for
+ * hard cell shapes.
+ *
+ * @param p — Vec2 TSL node, typically `uv() * scale`.
+ */
+declare function voronoi(p: TSLNode): TSLNode;
+
+/**
+ * Quantize a scalar TSL node to `steps` discrete levels.
+ *
+ *   quantize(t, 4) → values in {0, 0.25, 0.5, 0.75, 1.0}
+ *
+ * `steps` is a JS-side number (loop-equivalent at TSL build time, baked in).
+ * If you need an animatable step count, rebuild the TSL fragment.
+ */
+declare function quantize(t: TSLNode, steps: number): TSLNode;
+
+/**
+ * Signed distance field for a circle centered at the origin.
+ *
+ *   sdfCircle(p, r) = length(p) - r
+ *
+ * Negative inside the circle, zero on the boundary, positive outside.
+ * Combine with `smoothstep(-edge, +edge, sdf)` to render a soft-edged disk.
+ *
+ * @param p — Vec2 TSL node (typically a UV-space offset from the center).
+ * @param radius — JS-side scalar OR a scalar TSL node.
+ */
+declare function sdfCircle(p: TSLNode, radius: TSLNode | number): TSLNode;
+
+/**
+ * Naive vector addition: returns `p + by`.
+ *
+ *   displace(p, by) = p + by
+ *
+ * Thin wrapper that names the spatial intent of shifting a sample point.
+ *
+ * **SDF caveat:** when using this to translate an SDF render, pass the
+ * NEGATED translation — `sdfCircle(displace(p, v.mul(-1)), r)` renders the
+ * disk at position `+v` because SDF translation evaluates as
+ * `length(p - center) - r`. Adding `+v` to the sample point shifts the
+ * rendered shape in the OPPOSITE direction.
+ *
+ * @param p — Vec2 TSL node (the position being displaced).
+ * @param by — Vec2 TSL node (the displacement vector).
+ */
+declare function displace(p: TSLNode, by: TSLNode): TSLNode;
+
+interface CursorRippleOptions {
+    /** Decay radius (UV space). Beyond this, the ripple is ~0. Default: 0.4. */
+    reach?: number;
+    /** Wavelength controls the ripple spacing. Default: 30. Larger = wider rings. */
+    frequency?: number;
+    /** Time multiplier on the wave phase. Default: 6. Larger = faster oscillation. */
+    speed?: number;
+    /** Output amplitude. Default: 0.5. Final result is in roughly [-amplitude, +amplitude]. */
+    amplitude?: number;
+}
+/**
+ * A radial ripple emanating from `center`. Returns a scalar TSL node in
+ * roughly [-amplitude, +amplitude] that decays to ~0 outside `reach`.
+ *
+ *   ripple = sin(d*frequency - time*speed) * amplitude * smoothstep(reach, 0, d)
+ *
+ * Compose into a wave field by adding it to the underlying base wave.
+ *
+ * Note: `frequency` / `speed` / `reach` / `amplitude` are JS-side numbers
+ * (baked into the TSL fragment at material-build time). The animatable
+ * cursor position is the only live uniform consumed.
+ *
+ * @param p — Vec2 TSL node (typically `uv()`).
+ * @param center — Vec2 TSL node (cursor uniform, in UV space).
+ */
+declare function cursorRipple(p: TSLNode, center: TSLNode, opts?: CursorRippleOptions): TSLNode;
+
+/**
+ * Engine-gated `time`: equals the TSL built-in `time` multiplied by the
+ * reduced-motion scale uniform. Components consuming `time` from `@lovo/matter`
+ * automatically respect `prefers-reduced-motion` and the policy override set
+ * via `setReducedMotionPolicy`.
+ *
+ * If you want raw uncapped time (e.g. for a debug overlay), import
+ * `time` from `three/tsl` directly.
+ */
+declare const time: ShaderNodeObject<Node>;
+
+type ReducedMotionPolicy = 'auto' | 'off' | 'slow' | 'paused';
+/**
+ * Public surface exposed to package consumers. `recompute` is intentionally
+ * absent — it is engine-internal and should not be callable from outside.
+ */
+interface ReducedMotionWatcher {
+    /** Current time scale: 0, 0.3, or 1. */
+    scale(): number;
+    /** Subscribe to scale changes. Returns unsubscribe. */
+    subscribe(cb: (scale: number) => void): () => void;
+    /** Tear down media-query listener. */
+    dispose(): void;
+}
+/**
+ * Override Matter's default behavior of honoring `prefers-reduced-motion`.
+ * - 'auto'   — follow the OS media query (default)
+ * - 'off'    — full speed regardless of OS setting
+ * - 'slow'   — 30% speed regardless of OS setting
+ * - 'paused' — 0 (animation effectively frozen) regardless of OS setting
+ */
+declare function setReducedMotionPolicy(policy: ReducedMotionPolicy): void;
+declare function getReducedMotionPolicy(): ReducedMotionPolicy;
+/**
+ * Create a watcher that tracks `prefers-reduced-motion: reduce` and the
+ * global Matter policy override. Strict-mode-safe — callers create+dispose
+ * one per mount cycle.
+ */
+declare function createReducedMotionWatcher(): ReducedMotionWatcher;
+/**
+ * Returns the engine-shared TSL uniform that `time` is multiplied by. Lazily
+ * initialized on first read; reused across all materials. Mutating `.value`
+ * imperatively when policy changes is safe — TSL re-reads the uniform every
+ * frame.
+ */
+declare function getReducedMotionTimeScale(): ShaderNodeObject<Node>;
+
+interface VisibilityWatcher {
+    isVisible(): boolean;
+    /** Subscribe to changes. Receives the new visibility state. Returns unsubscribe. */
+    subscribe(cb: (visible: boolean) => void): () => void;
+    dispose(): void;
+}
+/**
+ * Watch `document.visibilityState`. Strict-mode-safe — callers create+dispose
+ * one per mount cycle.
+ *
+ * SSR: if `document` is unavailable, returns a no-op watcher whose
+ * `isVisible()` always returns `true` and whose `subscribe` does nothing.
+ */
+declare function createVisibilityWatcher(): VisibilityWatcher;
+
+interface IntersectionWatcher {
+    isInView(): boolean;
+    /** Subscribe to changes. Receives the new in-view state. Returns unsubscribe. */
+    subscribe(cb: (inView: boolean) => void): () => void;
+    dispose(): void;
+}
+/**
+ * Watch a canvas's viewport intersection. Pauses tied to this watcher should
+ * be resumed when the canvas is *any* fraction visible. Strict-mode-safe.
+ *
+ * SSR: if `IntersectionObserver` is unavailable, returns a no-op watcher whose
+ * `isInView()` always returns `true` and whose `subscribe` does nothing.
+ */
+declare function createIntersectionWatcher(canvas: HTMLCanvasElement): IntersectionWatcher;
+
+export { type ColorRampStop, type CreateRendererOptions, CursorInput, type CursorInputOptions, type CursorRippleOptions, type FBMOptions, type IntersectionWatcher, type MatterBackend, type MatterRenderer, MatterScheduler, type ReducedMotionPolicy, type ReducedMotionWatcher, type SchedulerClient, type SchedulerTick, type TSLNode, type Vec2, type VisibilityWatcher, colorRamp, createIntersectionWatcher, createReducedMotionWatcher, createRenderer, createVisibilityWatcher, cursorRipple, displace, fbm, getReducedMotionPolicy, getReducedMotionTimeScale, noise, quantize, sdfCircle, setReducedMotionPolicy, time, voronoi };