@lovo/matter 0.4.1 → 0.6.0

package/dist/index.d.cts

@@ -1,6 +1,9 @@
 import { Color } from 'three';
 import { WebGPURenderer, Node } from 'three/webgpu';
-import { ShaderNodeObject } from 'three/tsl';
+import { ShaderNodeObject, uniform } from 'three/tsl';
+
+/** The output color gamut the renderer encodes its framebuffer for. */
+type OutputGamut = 'srgb' | 'p3';
 
 type GpuBackend = 'webgpu' | 'webgl2';
 interface CreateRendererOptions {
@@ -14,6 +17,8 @@ interface CreateRendererOptions {
     clearAlpha?: number;
     /** Cap on devicePixelRatio. Default: 2. Pass Infinity to disable. */
     maxDPR?: number;
+    /** Output color gamut the framebuffer is encoded for. Default: 'srgb'. */
+    gamut?: OutputGamut;
 }
 interface GpuRenderer {
     /** The underlying Three.js WebGPURenderer (which may be running on a WebGL2 backend). */
@@ -34,7 +39,7 @@ interface GpuRenderer {
  */
 declare function createRenderer(canvas: HTMLCanvasElement, opts?: CreateRendererOptions): Promise<GpuRenderer>;
 
-type Vec2 = readonly [number, number];
+type Vector2 = readonly [number, number];
 interface CursorInputOptions {
     /**
      * Smoothing factor: 0 = no smoothing (snap to target instantly).
@@ -46,7 +51,7 @@ interface CursorInputOptions {
      */
     smoothing?: number;
     /** Starting position. Default: [0.5, 0.5] (center). */
-    initial?: Vec2;
+    initial?: Vector2;
     /** Listen on this target. Default: window. */
     target?: EventTarget;
     /**
@@ -69,7 +74,7 @@ interface CursorInputOptions {
         };
     };
 }
-type ChangeListener = (value: Vec2) => void;
+type ChangeListener = (value: Vector2) => void;
 /**
  * Smoothed pointer tracker emitting a normalized (0..1) Vec2 position.
  * Implements the AnimatableSignal protocol (`get()` + `on('change', cb)`)
@@ -87,9 +92,9 @@ declare class CursorInput {
     private disposed;
     constructor(opts?: CursorInputOptions);
     /** Current smoothed position. Implements AnimatableSignal protocol. */
-    get(): Vec2;
+    get(): Vector2;
     /** Subscribe to change events. Returns an unsubscribe function. */
-    on(_event: 'change', cb: ChangeListener): () => void;
+    on(_eventType: 'change', changeListener: ChangeListener): () => void;
     /**
      * Advance the smoothing one tick. Called by the host scheduler; not
      * typically called directly except in tests.
@@ -99,6 +104,16 @@ declare class CursorInput {
     dispose(): void;
 }
 
+/** Interpolation space for blending colors. Always converts via linear-sRGB. */
+type ColorSpace = 'linear' | 'oklab' | 'oklch' | 'lch' | 'hsl' | 'hsv';
+/**
+ * Which way around the hue wheel cylindrical spaces (oklch/lch/hsl/hsv)
+ * interpolate — the CSS Color 4 `hue-interpolation-method` keywords.
+ * `shorter`/`longer` pick the arc by length; `increasing`/`decreasing` pick it
+ * by direction (and keep multi-stop ramps marching one way around the wheel).
+ */
+type HueInterpolation = 'shorter' | 'longer' | 'increasing' | 'decreasing';
+
 /**
  * Canonical TSL-node *input* shape used throughout `@lovo/matter`.
  *
@@ -112,7 +127,7 @@ declare class CursorInput {
  */
 type TSLNode = Node | ShaderNodeObject<Node>;
 interface ColorRampStop {
-    /** Color expressed as a TSL node (typically `vec3(r,g,b)`). */
+    /** Color expressed as a TSL node (typically `vec3(r,g,b)`), in linear-sRGB. */
     color: TSLNode;
     /** Position 0..1 along the ramp. */
     position: number;
@@ -121,9 +136,50 @@ interface ColorRampStop {
  * Multi-stop color interpolation. Given a t in [0..1] and N color stops at
  * fixed positions, returns the smoothly-interpolated color.
  *
+ * `colorSpace` controls the interpolation space (default `'linear'` — a plain
+ * per-channel mix that preserves the input values). Stops are converted into
+ * the space up front, the nested-mix chain runs IN that space, and the result
+ * is converted back to linear-sRGB once at the end.
+ *
+ * `hueInterpolation` chooses which way around the wheel cylindrical spaces
+ * travel (default `'shorter'`); it's inert for rectangular spaces (linear/oklab).
+ *
  * Falls back to the first/last stop's color outside the bracketing positions.
  */
-declare function colorRamp(t: TSLNode, stops: ColorRampStop[]): ShaderNodeObject<Node>;
+declare function colorRamp(t: TSLNode, stops: ColorRampStop[], colorSpace?: ColorSpace, hueInterpolation?: HueInterpolation): ShaderNodeObject<Node>;
+
+/**
+ * Blend two linear-sRGB colors in `colorSpace`: convert both endpoints into the
+ * space, interpolate, convert back to linear-sRGB. `hueInterpolation` chooses
+ * the hue-wheel direction for cylindrical spaces (default `'shorter'`; inert for
+ * rectangular spaces). The result is NOT clamped — extended (out-of-sRGB) values
+ * are preserved so a wide-gamut (P3) output can display them; an sRGB output
+ * clamps per-channel at the framebuffer, identical to the prior behavior.
+ */
+declare function mixColor(colorA: TSLNode, colorB: TSLNode, t: TSLNode, colorSpace?: ColorSpace, hueInterpolation?: HueInterpolation): ShaderNodeObject<Node>;
+
+/**
+ * OKLab (L, a, b) -> extended linear-sRGB. CPU mirror of the TSL `oklabToLinear`
+ * in `oklab.ts` (same M2^-1 / cube / M1^-1 matrices). The result is NOT clamped:
+ * colors outside sRGB return channels below 0 or above 1, which a wide-gamut
+ * output can render and an sRGB output clamps at the framebuffer.
+ */
+declare function oklabToLinearSrgb(lightness: number, greenRed: number, blueYellow: number): [number, number, number];
+/** OKLch (L, C, h-in-degrees) -> extended linear-sRGB. */
+declare function oklchToLinearSrgb(lightness: number, chroma: number, hueDegrees: number): [number, number, number];
+/**
+ * Parse a color string to **extended** linear-sRGB. Accepts `#rrggbb`,
+ * `oklab(L a b)`, and `oklch(L C H)` (CSS Color 4 syntax: L/C may be percentages,
+ * H may carry a `deg` suffix, an optional `/ alpha` is parsed and dropped).
+ * Throws on any other syntax.
+ */
+declare function parseColorString(input: string): [number, number, number];
+
+/**
+ * sRGB-encoded channel in [0,1] -> linear-sRGB. Standard sRGB EOTF.
+ * Mirrors three's `convertSRGBToLinear` (e.g. 0.5 -> 0.21404114).
+ */
+declare function srgbChannelToLinear(channel: number): number;
 
 /**
  * 2D simplex noise sampled at a point. Returns a scalar TSL node in
@@ -138,9 +194,9 @@ declare function colorRamp(t: TSLNode, stops: ColorRampStop[]): ShaderNodeObject
  * Returns `ShaderNodeObject<Node>` (chainable) rather than the broader
  * `TSLNode` union, so callers can `.add(...)`/`.mul(...)` without casting.
  */
-declare function noise(p: TSLNode): ShaderNodeObject<Node>;
+declare function simplexNoise(p: TSLNode): ShaderNodeObject<Node>;
 
-interface FBMOptions {
+interface FractalNoiseOptions {
     /** 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. */
@@ -171,7 +227,7 @@ interface FBMOptions {
  * @returns scalar TSL node, normalized to roughly [-1..1] regardless of
  *          octave count thanks to the amplitude-sum division at the end.
  */
-declare function fbm(p: TSLNode, opts?: FBMOptions): ShaderNodeObject<Node>;
+declare function fractalNoise(p: TSLNode, opts?: FractalNoiseOptions): ShaderNodeObject<Node>;
 
 /**
  * 2D voronoi (Worley) noise — distance to the nearest jittered cell point,
@@ -209,7 +265,7 @@ declare function quantize(t: ShaderNodeObject<Node>, steps: number): ShaderNodeO
  * @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): ShaderNodeObject<Node>;
+declare function signedDistanceFieldCircle(p: TSLNode, radius: TSLNode | number): ShaderNodeObject<Node>;
 
 /**
  * Naive vector addition: returns `p + by`.
@@ -256,40 +312,26 @@ interface CursorRippleOptions {
  */
 declare function cursorRipple(p: TSLNode, center: TSLNode, opts?: CursorRippleOptions): ShaderNodeObject<Node>;
 
-declare const time: ShaderNodeObject<Node>;
+declare const elapsedTime: ShaderNodeObject<Node>;
+
+type TSLScalar = TSLNode | number;
+declare function filmGrain(intensity: TSLScalar, timeOffset?: TSLScalar): 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.
+ * Add sub-LSB dither to break up 8-bit quantization banding (most visible on
+ * wide-gamut/P3 output, where the same 256 levels span a wider gamut).
+ *
+ * `coord` is a per-pixel coordinate (pass `uv()`); `amount` is the noise
+ * magnitude in the color's units (default ~1/255, roughly one 8-bit step). Uses a
+ * triangular PDF (difference of two hashes) for flatter, less "gritty" noise than
+ * uniform white noise.
+ *
+ * SPIKE NOTE: applied here in linear-sRGB working space (before the renderer's
+ * output transfer), so the effective dither is uneven across tones (over-dithers
+ * shadows, under-dithers highlights). The correct home is a final output pass
+ * after color-space conversion; this is good enough to evaluate the banding fix.
  */
-declare function filmGrain(uvNode: ShaderNodeObject<Node>, intensity: ShaderNodeObject<Node> | number, timeOffset?: ShaderNodeObject<Node> | number): ShaderNodeObject<Node>;
+declare function dither(color: TSLNode, coord: TSLNode, amount?: number): ShaderNodeObject<Node>;
 
 type ReducedMotionPolicy = 'auto' | 'off' | 'slow' | 'paused';
 /**
@@ -325,7 +367,7 @@ declare function createReducedMotionWatcher(): ReducedMotionWatcher;
  * imperatively when policy changes is safe — TSL re-reads the uniform every
  * frame.
  */
-declare function getReducedMotionTimeScale(): ShaderNodeObject<Node>;
+declare function getReducedMotionTimeScale(): ReturnType<typeof uniform<number>>;
 
 interface VisibilityWatcher {
     isVisible(): boolean;
@@ -358,28 +400,23 @@ interface IntersectionWatcher {
 declare function createIntersectionWatcher(canvas: HTMLCanvasElement): IntersectionWatcher;
 
 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;
+    private idleVotes;
+    private animatedVotes;
+    /** True when all participating components prefer idle and none need animation. */
+    get idle(): boolean;
     /** Activate the scheduler. The rAF loop starts on the first client added. */
     start(): void;
     /** Halt the rAF loop entirely. Use dispose() for permanent teardown. */
@@ -395,16 +432,25 @@ declare class FrameScheduler {
     /** 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.
+     * Cast a vote on whether the scheduler should be idle.
+     *
+     * `setIdle(true)` increments the idle-vote count; the returned cleanup
+     * decrements it. `setIdle(false)` increments the animated-vote count;
+     * its cleanup decrements that. The scheduler halts (after one flush tick)
+     * only when `idleVotes > 0 && animatedVotes === 0`.
+     *
+     * Callers are responsible for calling the returned cleanup on unmount.
+     * Use `requestRender()` or cast a `setIdle(false)` vote to wake the loop
+     * without permanently registering an animated preference.
      */
-    setIdle(idle: boolean): void;
+    setIdle(idle: boolean): () => void;
     /** Force a single tick while idle. Useful for prop-change invalidation. */
     requestRender(): void;
+    private onBecameIdle;
+    private onBecameAnimated;
     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 };
+export { type ColorRampStop, type ColorSpace, type CreateRendererOptions, CursorInput, type CursorInputOptions, type CursorRippleOptions, type FractalNoiseOptions, FrameScheduler, type GpuBackend, type GpuRenderer, type HueInterpolation, type IntersectionWatcher, type OutputGamut, type ReducedMotionPolicy, type ReducedMotionWatcher, type SchedulerClient, type SchedulerTick, type TSLNode, type Vector2, type VisibilityWatcher, colorRamp, createIntersectionWatcher, createReducedMotionWatcher, createRenderer, createVisibilityWatcher, cursorRipple, displace, dither, elapsedTime, filmGrain, fractalNoise, getReducedMotionPolicy, getReducedMotionTimeScale, mixColor, oklabToLinearSrgb, oklchToLinearSrgb, parseColorString, quantize, setReducedMotionPolicy, signedDistanceFieldCircle, simplexNoise, srgbChannelToLinear, voronoi };

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import { Color } from 'three';
 import { WebGPURenderer, Node } from 'three/webgpu';
-import { ShaderNodeObject } from 'three/tsl';
+import { ShaderNodeObject, uniform } from 'three/tsl';
+
+/** The output color gamut the renderer encodes its framebuffer for. */
+type OutputGamut = 'srgb' | 'p3';
 
 type GpuBackend = 'webgpu' | 'webgl2';
 interface CreateRendererOptions {
@@ -14,6 +17,8 @@ interface CreateRendererOptions {
     clearAlpha?: number;
     /** Cap on devicePixelRatio. Default: 2. Pass Infinity to disable. */
     maxDPR?: number;
+    /** Output color gamut the framebuffer is encoded for. Default: 'srgb'. */
+    gamut?: OutputGamut;
 }
 interface GpuRenderer {
     /** The underlying Three.js WebGPURenderer (which may be running on a WebGL2 backend). */
@@ -34,7 +39,7 @@ interface GpuRenderer {
  */
 declare function createRenderer(canvas: HTMLCanvasElement, opts?: CreateRendererOptions): Promise<GpuRenderer>;
 
-type Vec2 = readonly [number, number];
+type Vector2 = readonly [number, number];
 interface CursorInputOptions {
     /**
      * Smoothing factor: 0 = no smoothing (snap to target instantly).
@@ -46,7 +51,7 @@ interface CursorInputOptions {
      */
     smoothing?: number;
     /** Starting position. Default: [0.5, 0.5] (center). */
-    initial?: Vec2;
+    initial?: Vector2;
     /** Listen on this target. Default: window. */
     target?: EventTarget;
     /**
@@ -69,7 +74,7 @@ interface CursorInputOptions {
         };
     };
 }
-type ChangeListener = (value: Vec2) => void;
+type ChangeListener = (value: Vector2) => void;
 /**
  * Smoothed pointer tracker emitting a normalized (0..1) Vec2 position.
  * Implements the AnimatableSignal protocol (`get()` + `on('change', cb)`)
@@ -87,9 +92,9 @@ declare class CursorInput {
     private disposed;
     constructor(opts?: CursorInputOptions);
     /** Current smoothed position. Implements AnimatableSignal protocol. */
-    get(): Vec2;
+    get(): Vector2;
     /** Subscribe to change events. Returns an unsubscribe function. */
-    on(_event: 'change', cb: ChangeListener): () => void;
+    on(_eventType: 'change', changeListener: ChangeListener): () => void;
     /**
      * Advance the smoothing one tick. Called by the host scheduler; not
      * typically called directly except in tests.
@@ -99,6 +104,16 @@ declare class CursorInput {
     dispose(): void;
 }
 
+/** Interpolation space for blending colors. Always converts via linear-sRGB. */
+type ColorSpace = 'linear' | 'oklab' | 'oklch' | 'lch' | 'hsl' | 'hsv';
+/**
+ * Which way around the hue wheel cylindrical spaces (oklch/lch/hsl/hsv)
+ * interpolate — the CSS Color 4 `hue-interpolation-method` keywords.
+ * `shorter`/`longer` pick the arc by length; `increasing`/`decreasing` pick it
+ * by direction (and keep multi-stop ramps marching one way around the wheel).
+ */
+type HueInterpolation = 'shorter' | 'longer' | 'increasing' | 'decreasing';
+
 /**
  * Canonical TSL-node *input* shape used throughout `@lovo/matter`.
  *
@@ -112,7 +127,7 @@ declare class CursorInput {
  */
 type TSLNode = Node | ShaderNodeObject<Node>;
 interface ColorRampStop {
-    /** Color expressed as a TSL node (typically `vec3(r,g,b)`). */
+    /** Color expressed as a TSL node (typically `vec3(r,g,b)`), in linear-sRGB. */
     color: TSLNode;
     /** Position 0..1 along the ramp. */
     position: number;
@@ -121,9 +136,50 @@ interface ColorRampStop {
  * Multi-stop color interpolation. Given a t in [0..1] and N color stops at
  * fixed positions, returns the smoothly-interpolated color.
  *
+ * `colorSpace` controls the interpolation space (default `'linear'` — a plain
+ * per-channel mix that preserves the input values). Stops are converted into
+ * the space up front, the nested-mix chain runs IN that space, and the result
+ * is converted back to linear-sRGB once at the end.
+ *
+ * `hueInterpolation` chooses which way around the wheel cylindrical spaces
+ * travel (default `'shorter'`); it's inert for rectangular spaces (linear/oklab).
+ *
  * Falls back to the first/last stop's color outside the bracketing positions.
  */
-declare function colorRamp(t: TSLNode, stops: ColorRampStop[]): ShaderNodeObject<Node>;
+declare function colorRamp(t: TSLNode, stops: ColorRampStop[], colorSpace?: ColorSpace, hueInterpolation?: HueInterpolation): ShaderNodeObject<Node>;
+
+/**
+ * Blend two linear-sRGB colors in `colorSpace`: convert both endpoints into the
+ * space, interpolate, convert back to linear-sRGB. `hueInterpolation` chooses
+ * the hue-wheel direction for cylindrical spaces (default `'shorter'`; inert for
+ * rectangular spaces). The result is NOT clamped — extended (out-of-sRGB) values
+ * are preserved so a wide-gamut (P3) output can display them; an sRGB output
+ * clamps per-channel at the framebuffer, identical to the prior behavior.
+ */
+declare function mixColor(colorA: TSLNode, colorB: TSLNode, t: TSLNode, colorSpace?: ColorSpace, hueInterpolation?: HueInterpolation): ShaderNodeObject<Node>;
+
+/**
+ * OKLab (L, a, b) -> extended linear-sRGB. CPU mirror of the TSL `oklabToLinear`
+ * in `oklab.ts` (same M2^-1 / cube / M1^-1 matrices). The result is NOT clamped:
+ * colors outside sRGB return channels below 0 or above 1, which a wide-gamut
+ * output can render and an sRGB output clamps at the framebuffer.
+ */
+declare function oklabToLinearSrgb(lightness: number, greenRed: number, blueYellow: number): [number, number, number];
+/** OKLch (L, C, h-in-degrees) -> extended linear-sRGB. */
+declare function oklchToLinearSrgb(lightness: number, chroma: number, hueDegrees: number): [number, number, number];
+/**
+ * Parse a color string to **extended** linear-sRGB. Accepts `#rrggbb`,
+ * `oklab(L a b)`, and `oklch(L C H)` (CSS Color 4 syntax: L/C may be percentages,
+ * H may carry a `deg` suffix, an optional `/ alpha` is parsed and dropped).
+ * Throws on any other syntax.
+ */
+declare function parseColorString(input: string): [number, number, number];
+
+/**
+ * sRGB-encoded channel in [0,1] -> linear-sRGB. Standard sRGB EOTF.
+ * Mirrors three's `convertSRGBToLinear` (e.g. 0.5 -> 0.21404114).
+ */
+declare function srgbChannelToLinear(channel: number): number;
 
 /**
  * 2D simplex noise sampled at a point. Returns a scalar TSL node in
@@ -138,9 +194,9 @@ declare function colorRamp(t: TSLNode, stops: ColorRampStop[]): ShaderNodeObject
  * Returns `ShaderNodeObject<Node>` (chainable) rather than the broader
  * `TSLNode` union, so callers can `.add(...)`/`.mul(...)` without casting.
  */
-declare function noise(p: TSLNode): ShaderNodeObject<Node>;
+declare function simplexNoise(p: TSLNode): ShaderNodeObject<Node>;
 
-interface FBMOptions {
+interface FractalNoiseOptions {
     /** 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. */
@@ -171,7 +227,7 @@ interface FBMOptions {
  * @returns scalar TSL node, normalized to roughly [-1..1] regardless of
  *          octave count thanks to the amplitude-sum division at the end.
  */
-declare function fbm(p: TSLNode, opts?: FBMOptions): ShaderNodeObject<Node>;
+declare function fractalNoise(p: TSLNode, opts?: FractalNoiseOptions): ShaderNodeObject<Node>;
 
 /**
  * 2D voronoi (Worley) noise — distance to the nearest jittered cell point,
@@ -209,7 +265,7 @@ declare function quantize(t: ShaderNodeObject<Node>, steps: number): ShaderNodeO
  * @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): ShaderNodeObject<Node>;
+declare function signedDistanceFieldCircle(p: TSLNode, radius: TSLNode | number): ShaderNodeObject<Node>;
 
 /**
  * Naive vector addition: returns `p + by`.
@@ -256,40 +312,26 @@ interface CursorRippleOptions {
  */
 declare function cursorRipple(p: TSLNode, center: TSLNode, opts?: CursorRippleOptions): ShaderNodeObject<Node>;
 
-declare const time: ShaderNodeObject<Node>;
+declare const elapsedTime: ShaderNodeObject<Node>;
+
+type TSLScalar = TSLNode | number;
+declare function filmGrain(intensity: TSLScalar, timeOffset?: TSLScalar): 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.
+ * Add sub-LSB dither to break up 8-bit quantization banding (most visible on
+ * wide-gamut/P3 output, where the same 256 levels span a wider gamut).
+ *
+ * `coord` is a per-pixel coordinate (pass `uv()`); `amount` is the noise
+ * magnitude in the color's units (default ~1/255, roughly one 8-bit step). Uses a
+ * triangular PDF (difference of two hashes) for flatter, less "gritty" noise than
+ * uniform white noise.
+ *
+ * SPIKE NOTE: applied here in linear-sRGB working space (before the renderer's
+ * output transfer), so the effective dither is uneven across tones (over-dithers
+ * shadows, under-dithers highlights). The correct home is a final output pass
+ * after color-space conversion; this is good enough to evaluate the banding fix.
  */
-declare function filmGrain(uvNode: ShaderNodeObject<Node>, intensity: ShaderNodeObject<Node> | number, timeOffset?: ShaderNodeObject<Node> | number): ShaderNodeObject<Node>;
+declare function dither(color: TSLNode, coord: TSLNode, amount?: number): ShaderNodeObject<Node>;
 
 type ReducedMotionPolicy = 'auto' | 'off' | 'slow' | 'paused';
 /**
@@ -325,7 +367,7 @@ declare function createReducedMotionWatcher(): ReducedMotionWatcher;
  * imperatively when policy changes is safe — TSL re-reads the uniform every
  * frame.
  */
-declare function getReducedMotionTimeScale(): ShaderNodeObject<Node>;
+declare function getReducedMotionTimeScale(): ReturnType<typeof uniform<number>>;
 
 interface VisibilityWatcher {
     isVisible(): boolean;
@@ -358,28 +400,23 @@ interface IntersectionWatcher {
 declare function createIntersectionWatcher(canvas: HTMLCanvasElement): IntersectionWatcher;
 
 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;
+    private idleVotes;
+    private animatedVotes;
+    /** True when all participating components prefer idle and none need animation. */
+    get idle(): boolean;
     /** Activate the scheduler. The rAF loop starts on the first client added. */
     start(): void;
     /** Halt the rAF loop entirely. Use dispose() for permanent teardown. */
@@ -395,16 +432,25 @@ declare class FrameScheduler {
     /** 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.
+     * Cast a vote on whether the scheduler should be idle.
+     *
+     * `setIdle(true)` increments the idle-vote count; the returned cleanup
+     * decrements it. `setIdle(false)` increments the animated-vote count;
+     * its cleanup decrements that. The scheduler halts (after one flush tick)
+     * only when `idleVotes > 0 && animatedVotes === 0`.
+     *
+     * Callers are responsible for calling the returned cleanup on unmount.
+     * Use `requestRender()` or cast a `setIdle(false)` vote to wake the loop
+     * without permanently registering an animated preference.
      */
-    setIdle(idle: boolean): void;
+    setIdle(idle: boolean): () => void;
     /** Force a single tick while idle. Useful for prop-change invalidation. */
     requestRender(): void;
+    private onBecameIdle;
+    private onBecameAnimated;
     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 };
+export { type ColorRampStop, type ColorSpace, type CreateRendererOptions, CursorInput, type CursorInputOptions, type CursorRippleOptions, type FractalNoiseOptions, FrameScheduler, type GpuBackend, type GpuRenderer, type HueInterpolation, type IntersectionWatcher, type OutputGamut, type ReducedMotionPolicy, type ReducedMotionWatcher, type SchedulerClient, type SchedulerTick, type TSLNode, type Vector2, type VisibilityWatcher, colorRamp, createIntersectionWatcher, createReducedMotionWatcher, createRenderer, createVisibilityWatcher, cursorRipple, displace, dither, elapsedTime, filmGrain, fractalNoise, getReducedMotionPolicy, getReducedMotionTimeScale, mixColor, oklabToLinearSrgb, oklchToLinearSrgb, parseColorString, quantize, setReducedMotionPolicy, signedDistanceFieldCircle, simplexNoise, srgbChannelToLinear, voronoi };