@lovo/matter 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { WebGPURenderer, Node } from 'three/webgpu';
 import { Color } from 'three';
+import { WebGPURenderer, Node } from 'three/webgpu';
 import { ShaderNodeObject } from 'three/tsl';
 
-type MatterBackend = 'webgpu' | 'webgl2';
+type GpuBackend = 'webgpu' | 'webgl2';
 interface CreateRendererOptions {
     /** Anti-alias the framebuffer. Default: true. */
     antialias?: boolean;
@@ -15,11 +15,11 @@ interface CreateRendererOptions {
     /** Cap on devicePixelRatio. Default: 2. Pass Infinity to disable. */
     maxDPR?: number;
 }
-interface MatterRenderer {
+interface GpuRenderer {
     /** The underlying Three.js WebGPURenderer (which may be running on a WebGL2 backend). */
     three: WebGPURenderer;
     /** Which backend the renderer initialized with. */
-    backend: MatterBackend;
+    backend: GpuBackend;
     /** Tear down the renderer and release GPU resources. */
     dispose: () => void;
     /** Resize the renderer to the canvas's current client dimensions. */
@@ -32,57 +32,7 @@ interface MatterRenderer {
  * 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;
-}
+declare function createRenderer(canvas: HTMLCanvasElement, opts?: CreateRendererOptions): Promise<GpuRenderer>;
 
 type Vec2 = readonly [number, number];
 interface CursorInputOptions {
@@ -122,7 +72,7 @@ interface CursorInputOptions {
 type ChangeListener = (value: Vec2) => void;
 /**
  * Smoothed pointer tracker emitting a normalized (0..1) Vec2 position.
- * Implements the MatterSignal protocol (`get()` + `on('change', cb)`)
+ * Implements the AnimatableSignal protocol (`get()` + `on('change', cb)`)
  * so it composes with Motion's `useTransform` and similar tools.
  */
 declare class CursorInput {
@@ -136,7 +86,7 @@ declare class CursorInput {
     private readonly handleMouseMove;
     private disposed;
     constructor(opts?: CursorInputOptions);
-    /** Current smoothed position. Implements MatterSignal protocol. */
+    /** Current smoothed position. Implements AnimatableSignal protocol. */
     get(): Vec2;
     /** Subscribe to change events. Returns an unsubscribe function. */
     on(_event: 'change', cb: ChangeListener): () => void;
@@ -308,6 +258,39 @@ declare function cursorRipple(p: TSLNode, center: TSLNode, opts?: CursorRippleOp
 
 declare const time: ShaderNodeObject<Node>;
 
+/**
+ * Hash-based film grain — chaotic, uncorrelated per-pixel noise sampled
+ * from `uvNode`. The output is *centered* around zero so it acts as a
+ * brightness-preserving texture overlay (half the pixels brighten by up
+ * to `intensity`, half darken, mean unchanged). ADD the result to a color.
+ *
+ *   filmGrain(uv, k)        → static grain
+ *   filmGrain(uv, k, time)  → twinkling grain. Pass a quantized time node
+ *                             (e.g. `time.mul(speed).mul(60).floor()`) so
+ *                             the grain re-randomizes at a controllable
+ *                             "shutter rate" instead of every frame.
+ *
+ * Recipe:
+ *
+ *   base = vec2(uv·c1, uv·c2) + timeOffset
+ *   hash = fract(sin(base) * 43758.5453)
+ *   out  = (length(hash) - 0.765) * intensity
+ *
+ * `c1 = (2127.1, 81.17)` and `c2 = (1269.5, 283.37)` are arbitrary
+ * near-prime constants that produce visually-uncorrelated noise. `0.765`
+ * is the empirical mean of `length(vec2(u, v))` for uniform u, v ∈ [0, 1),
+ * computed once so we don't have to subtract it at runtime per pixel.
+ *
+ * For a film-stock look (darkens as grain rises — silver-emulsion
+ * physics) subtract the result from the color instead of adding.
+ *
+ * @param uvNode      vec2 TSL node, typically `uv()`.
+ * @param intensity   number or TSL node in [0, 1]; scales the grain.
+ * @param timeOffset  optional number or TSL node added to each sample
+ *                    before hashing. `0` (default) → static grain.
+ */
+declare function filmGrain(uvNode: ShaderNodeObject<Node>, intensity: ShaderNodeObject<Node> | number, timeOffset?: ShaderNodeObject<Node> | number): ShaderNodeObject<Node>;
+
 type ReducedMotionPolicy = 'auto' | 'off' | 'slow' | 'paused';
 /**
  * Public surface exposed to package consumers. `recompute` is intentionally
@@ -374,4 +357,54 @@ interface IntersectionWatcher {
  */
 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 };
+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 <ShaderScene>; clients
+ * are typically a Three.js renderer's render call.
+ */
+declare class FrameScheduler {
+    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;
+}
+
+export { type ColorRampStop, type CreateRendererOptions, CursorInput, type CursorInputOptions, type CursorRippleOptions, type FBMOptions, FrameScheduler, type GpuBackend, type GpuRenderer, type IntersectionWatcher, type ReducedMotionPolicy, type ReducedMotionWatcher, type SchedulerClient, type SchedulerTick, type TSLNode, type Vec2, type VisibilityWatcher, colorRamp, createIntersectionWatcher, createReducedMotionWatcher, createRenderer, createVisibilityWatcher, cursorRipple, displace, fbm, filmGrain, getReducedMotionPolicy, getReducedMotionTimeScale, noise, quantize, sdfCircle, setReducedMotionPolicy, time, voronoi };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { WebGPURenderer, Node } from 'three/webgpu';
 import { Color } from 'three';
+import { WebGPURenderer, Node } from 'three/webgpu';
 import { ShaderNodeObject } from 'three/tsl';
 
-type MatterBackend = 'webgpu' | 'webgl2';
+type GpuBackend = 'webgpu' | 'webgl2';
 interface CreateRendererOptions {
     /** Anti-alias the framebuffer. Default: true. */
     antialias?: boolean;
@@ -15,11 +15,11 @@ interface CreateRendererOptions {
     /** Cap on devicePixelRatio. Default: 2. Pass Infinity to disable. */
     maxDPR?: number;
 }
-interface MatterRenderer {
+interface GpuRenderer {
     /** The underlying Three.js WebGPURenderer (which may be running on a WebGL2 backend). */
     three: WebGPURenderer;
     /** Which backend the renderer initialized with. */
-    backend: MatterBackend;
+    backend: GpuBackend;
     /** Tear down the renderer and release GPU resources. */
     dispose: () => void;
     /** Resize the renderer to the canvas's current client dimensions. */
@@ -32,57 +32,7 @@ interface MatterRenderer {
  * 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;
-}
+declare function createRenderer(canvas: HTMLCanvasElement, opts?: CreateRendererOptions): Promise<GpuRenderer>;
 
 type Vec2 = readonly [number, number];
 interface CursorInputOptions {
@@ -122,7 +72,7 @@ interface CursorInputOptions {
 type ChangeListener = (value: Vec2) => void;
 /**
  * Smoothed pointer tracker emitting a normalized (0..1) Vec2 position.
- * Implements the MatterSignal protocol (`get()` + `on('change', cb)`)
+ * Implements the AnimatableSignal protocol (`get()` + `on('change', cb)`)
  * so it composes with Motion's `useTransform` and similar tools.
  */
 declare class CursorInput {
@@ -136,7 +86,7 @@ declare class CursorInput {
     private readonly handleMouseMove;
     private disposed;
     constructor(opts?: CursorInputOptions);
-    /** Current smoothed position. Implements MatterSignal protocol. */
+    /** Current smoothed position. Implements AnimatableSignal protocol. */
     get(): Vec2;
     /** Subscribe to change events. Returns an unsubscribe function. */
     on(_event: 'change', cb: ChangeListener): () => void;
@@ -308,6 +258,39 @@ declare function cursorRipple(p: TSLNode, center: TSLNode, opts?: CursorRippleOp
 
 declare const time: ShaderNodeObject<Node>;
 
+/**
+ * Hash-based film grain — chaotic, uncorrelated per-pixel noise sampled
+ * from `uvNode`. The output is *centered* around zero so it acts as a
+ * brightness-preserving texture overlay (half the pixels brighten by up
+ * to `intensity`, half darken, mean unchanged). ADD the result to a color.
+ *
+ *   filmGrain(uv, k)        → static grain
+ *   filmGrain(uv, k, time)  → twinkling grain. Pass a quantized time node
+ *                             (e.g. `time.mul(speed).mul(60).floor()`) so
+ *                             the grain re-randomizes at a controllable
+ *                             "shutter rate" instead of every frame.
+ *
+ * Recipe:
+ *
+ *   base = vec2(uv·c1, uv·c2) + timeOffset
+ *   hash = fract(sin(base) * 43758.5453)
+ *   out  = (length(hash) - 0.765) * intensity
+ *
+ * `c1 = (2127.1, 81.17)` and `c2 = (1269.5, 283.37)` are arbitrary
+ * near-prime constants that produce visually-uncorrelated noise. `0.765`
+ * is the empirical mean of `length(vec2(u, v))` for uniform u, v ∈ [0, 1),
+ * computed once so we don't have to subtract it at runtime per pixel.
+ *
+ * For a film-stock look (darkens as grain rises — silver-emulsion
+ * physics) subtract the result from the color instead of adding.
+ *
+ * @param uvNode      vec2 TSL node, typically `uv()`.
+ * @param intensity   number or TSL node in [0, 1]; scales the grain.
+ * @param timeOffset  optional number or TSL node added to each sample
+ *                    before hashing. `0` (default) → static grain.
+ */
+declare function filmGrain(uvNode: ShaderNodeObject<Node>, intensity: ShaderNodeObject<Node> | number, timeOffset?: ShaderNodeObject<Node> | number): ShaderNodeObject<Node>;
+
 type ReducedMotionPolicy = 'auto' | 'off' | 'slow' | 'paused';
 /**
  * Public surface exposed to package consumers. `recompute` is intentionally
@@ -374,4 +357,54 @@ interface IntersectionWatcher {
  */
 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 };
+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 <ShaderScene>; clients
+ * are typically a Three.js renderer's render call.
+ */
+declare class FrameScheduler {
+    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;
+}
+
+export { type ColorRampStop, type CreateRendererOptions, CursorInput, type CursorInputOptions, type CursorRippleOptions, type FBMOptions, FrameScheduler, type GpuBackend, type GpuRenderer, type IntersectionWatcher, type ReducedMotionPolicy, type ReducedMotionWatcher, type SchedulerClient, type SchedulerTick, type TSLNode, type Vec2, type VisibilityWatcher, colorRamp, createIntersectionWatcher, createReducedMotionWatcher, createRenderer, createVisibilityWatcher, cursorRipple, displace, fbm, filmGrain, getReducedMotionPolicy, getReducedMotionTimeScale, noise, quantize, sdfCircle, setReducedMotionPolicy, time, voronoi };