@lovo/matter 0.5.0 → 1.0.0

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). */
@@ -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
@@ -258,7 +314,27 @@ declare function cursorRipple(p: TSLNode, center: TSLNode, opts?: CursorRippleOp
 
 declare const elapsedTime: ShaderNodeObject<Node>;
 
-declare function filmGrain(intensity: ShaderNodeObject<Node> | number, timeOffset?: ShaderNodeObject<Node> | number): ShaderNodeObject<Node>;
+type TSLScalar = TSLNode | number;
+declare function grain(intensity: TSLScalar, timeOffset?: TSLScalar): ShaderNodeObject<Node>;
+
+/**
+ * Add a sub-LSB ordered dither to break up 8-bit quantization banding (most
+ * visible on smooth gradients and on wide-gamut/P3 output, where the same 256
+ * levels span a wider gamut so each step is a coarser perceptual jump).
+ *
+ * `amount` is the noise magnitude in the color's units (default ~1/255, roughly
+ * one 8-bit step). The dither is an ordered Bayer 8x8 pattern keyed on the
+ * per-pixel `screenCoordinate`, so the grain is a crisp one device-pixel cell
+ * regardless of geometry or zoom, and is deterministic (no temporal shimmer —
+ * important for static scenes).
+ *
+ * For correctness the dither belongs in display-encoded space, immediately
+ * before 8-bit quantization. In a Matter-managed scene that placement is handled
+ * for you (`ShaderScene` applies it as a final output stage after the color
+ * transfer). This primitive is the entry point for Mode 2 (your own r3f canvas),
+ * where you apply it to your shader's output yourself.
+ */
+declare function dither(color: TSLNode, amount?: number): ShaderNodeObject<Node>;
 
 type ReducedMotionPolicy = 'auto' | 'off' | 'slow' | 'paused';
 /**
@@ -294,7 +370,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;
@@ -380,4 +456,4 @@ declare class FrameScheduler {
     private readonly frame;
 }
 
-export { type ColorRampStop, type CreateRendererOptions, CursorInput, type CursorInputOptions, type CursorRippleOptions, type FractalNoiseOptions, FrameScheduler, type GpuBackend, type GpuRenderer, type IntersectionWatcher, type ReducedMotionPolicy, type ReducedMotionWatcher, type SchedulerClient, type SchedulerTick, type TSLNode, type Vector2, type VisibilityWatcher, colorRamp, createIntersectionWatcher, createReducedMotionWatcher, createRenderer, createVisibilityWatcher, cursorRipple, displace, elapsedTime, filmGrain, fractalNoise, getReducedMotionPolicy, getReducedMotionTimeScale, quantize, setReducedMotionPolicy, signedDistanceFieldCircle, simplexNoise, 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, fractalNoise, getReducedMotionPolicy, getReducedMotionTimeScale, grain, mixColor, oklabToLinearSrgb, oklchToLinearSrgb, parseColorString, quantize, setReducedMotionPolicy, signedDistanceFieldCircle, simplexNoise, srgbChannelToLinear, voronoi };

package/dist/index.js

@@ -1,13 +1,51 @@
 // src/runtime/create-renderer/create-renderer.ts
-import { Color } from "three";
+import { Color, Vector2 } from "three";
 import { WebGPURenderer } from "three/webgpu";
+
+// src/runtime/create-renderer/gamut.ts
+import { ColorManagement, SRGBColorSpace } from "three";
+import {
+  DisplayP3ColorSpace,
+  DisplayP3ColorSpaceImpl,
+  LinearDisplayP3ColorSpace,
+  LinearDisplayP3ColorSpaceImpl
+} from "three/examples/jsm/math/ColorSpaces.js";
+ColorManagement.define({
+  [DisplayP3ColorSpace]: DisplayP3ColorSpaceImpl,
+  [LinearDisplayP3ColorSpace]: LinearDisplayP3ColorSpaceImpl
+});
+function gamutToColorSpace(gamut) {
+  return gamut === "p3" ? DisplayP3ColorSpace : SRGBColorSpace;
+}
+function hasWebGpuBackendInternals(backend) {
+  if (typeof backend !== "object" || backend === null) return false;
+  if (!("device" in backend) || !("context" in backend)) return false;
+  const { device, context } = backend;
+  return typeof device === "object" && device !== null && typeof context === "object" && context !== null && "configure" in context && typeof context.configure === "function";
+}
+function applyCanvasGamut(renderer, backend, gamut) {
+  if (gamut !== "p3" || backend !== "webgpu") return;
+  if (typeof navigator === "undefined" || !("gpu" in navigator)) return;
+  const webGpuBackend = renderer.backend;
+  if (!hasWebGpuBackendInternals(webGpuBackend)) return;
+  webGpuBackend.context.configure({
+    device: webGpuBackend.device,
+    format: navigator.gpu.getPreferredCanvasFormat(),
+    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+    alphaMode: "premultiplied",
+    colorSpace: "display-p3"
+  });
+}
+
+// src/runtime/create-renderer/create-renderer.ts
 async function createRenderer(canvas, opts = {}) {
   const {
     antialias = true,
     forceWebGL = false,
     clearColor = 0,
     clearAlpha = 0,
-    maxDPR = 2
+    maxDPR = 2,
+    gamut = "srgb"
   } = opts;
   const three = new WebGPURenderer({
     canvas,
@@ -15,19 +53,24 @@ async function createRenderer(canvas, opts = {}) {
     forceWebGL
   });
   await three.init();
+  three.outputColorSpace = gamutToColorSpace(gamut);
   three.setPixelRatio(Math.min(window.devicePixelRatio, maxDPR));
   const resolvedClearColor = clearColor instanceof Color ? clearColor : new Color(clearColor);
   three.setClearColor(resolvedClearColor, clearAlpha);
+  const rendererSize = new Vector2();
   const resize = () => {
     const canvasWidth = canvas.clientWidth;
     const canvasHeight = canvas.clientHeight;
-    if (canvas.width !== canvasWidth * three.getPixelRatio() || canvas.height !== canvasHeight * three.getPixelRatio()) {
+    if (canvasWidth === 0 || canvasHeight === 0) return;
+    three.getSize(rendererSize);
+    if (rendererSize.width !== canvasWidth || rendererSize.height !== canvasHeight) {
       three.setSize(canvasWidth, canvasHeight, false);
     }
   };
   resize();
   const isWebGL = "isWebGLBackend" in three.backend && three.backend.isWebGLBackend === true;
   const backend = forceWebGL || isWebGL ? "webgl2" : "webgpu";
+  applyCanvasGamut(three, backend, gamut);
   return {
     three,
     backend,
@@ -114,23 +157,359 @@ var clamp01 = (value) => Math.max(0, Math.min(1, value));
 var lerp = (startValue, endValue, blendFactor) => startValue + (endValue - startValue) * blendFactor;
 
 // src/primitives/color-ramp/color-ramp.ts
-import { mix, vec3 } from "three/tsl";
-import { clamp, div, sub } from "three/tsl";
-function colorRamp(t, stops) {
+import { clamp as clamp3, div, sub, vec3 as vec37 } from "three/tsl";
+
+// src/primitives/color-space/hue.ts
+import { mod, sign, step } from "three/tsl";
+var EQUAL_HUE_EPSILON = 1e-6;
+var shortestArcHue = (h1, h2, t, period) => {
+  const half = period / 2;
+  const delta = mod(h2.sub(h1).add(half), period).sub(half);
+  return h1.add(delta.mul(t));
+};
+var longestArcHue = (h1, h2, t, period) => {
+  const half = period / 2;
+  const short = mod(h2.sub(h1).add(half), period).sub(half);
+  const delta = short.sub(sign(short).mul(period));
+  return h1.add(delta.mul(t));
+};
+var increasingArcHue = (h1, h2, t, period) => {
+  const delta = mod(h2.sub(h1), period);
+  return h1.add(delta.mul(t));
+};
+var decreasingArcHue = (h1, h2, t, period) => {
+  const up = mod(h2.sub(h1), period);
+  const delta = up.sub(step(EQUAL_HUE_EPSILON, up).mul(period));
+  return h1.add(delta.mul(t));
+};
+var hueArcInterpolators = {
+  shorter: shortestArcHue,
+  longer: longestArcHue,
+  increasing: increasingArcHue,
+  decreasing: decreasingArcHue
+};
+
+// src/primitives/color-space/hsl.ts
+import { abs, clamp, fract, max, min, mix as mix2, step as step3, vec3, vec4 } from "three/tsl";
+
+// src/primitives/color-space/transfer.ts
+import { mix, pow, step as step2 } from "three/tsl";
+function srgbChannelToLinear(channel) {
+  return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+}
+function srgbToLinear(srgb) {
+  const value = pow(srgb, 1);
+  const lowSegment = value.div(12.92);
+  const highSegment = pow(value.add(0.055).div(1.055), 2.4);
+  return mix(lowSegment, highSegment, step2(0.04045, value));
+}
+function linearToSrgb(linear) {
+  const value = pow(linear, 1);
+  const lowSegment = value.mul(12.92);
+  const highSegment = pow(value, 1 / 2.4).mul(1.055).sub(0.055);
+  return mix(lowSegment, highSegment, step2(31308e-7, value));
+}
+
+// src/primitives/color-space/hsl.ts
+var EPSILON = 1e-10;
+function gammaRgbHue(c) {
+  const p = mix2(vec4(c.b, c.g, -1 / 3, 2 / 3), vec4(c.g, c.b, 0, -1 / 3), step3(c.b, c.g));
+  const q = mix2(vec4(p.x, p.y, p.w, c.r), vec4(c.r, p.y, p.z, p.x), step3(p.x, c.r));
+  const chroma = q.x.sub(min(q.w, q.y));
+  return abs(q.z.add(q.w.sub(q.y).div(chroma.mul(6).add(EPSILON))));
+}
+function gammaRgbToHsl(c) {
+  const maxChannel = max(c.r, max(c.g, c.b));
+  const minChannel = min(c.r, min(c.g, c.b));
+  const lightness = maxChannel.add(minChannel).mul(0.5);
+  const chroma = maxChannel.sub(minChannel);
+  const saturation = chroma.div(abs(lightness.mul(2).sub(1)).oneMinus().add(EPSILON));
+  return vec3(gammaRgbHue(c), saturation, lightness);
+}
+function hslToGammaRgb(hsl) {
+  const hue = hsl.x;
+  const saturation = hsl.y;
+  const lightness = hsl.z;
+  const chroma = abs(lightness.mul(2).sub(1)).oneMinus().mul(saturation);
+  const ramp = abs(
+    fract(vec3(hue).add(vec3(1, 2 / 3, 1 / 3))).mul(6).sub(vec3(3))
+  );
+  const hueRgb = clamp(ramp.sub(vec3(1)), 0, 1);
+  return hueRgb.sub(0.5).mul(chroma).add(lightness);
+}
+var hslSpace = {
+  // Clamp into sRGB before the gamma transfer: HSL is an sRGB-gamut concept, and
+  // the sRGB OETF's pow() can't be WGSL const-evaluated on the negative channels
+  // of an out-of-sRGB (wide-gamut) stop color — that crashed the shader compile.
+  fromLinear: (rgb) => gammaRgbToHsl(linearToSrgb(clamp(rgb, 0, 1))),
+  toLinear: (hsl) => srgbToLinear(hslToGammaRgb(hsl)),
+  lerp: (a, b, t, hue) => vec3(hue(a.x, b.x, t, 1), mix2(a.y, b.y, t), mix2(a.z, b.z, t))
+};
+
+// src/primitives/color-space/hsv.ts
+import { abs as abs2, clamp as clamp2, fract as fract2, min as min2, mix as mix3, step as step4, vec3 as vec32, vec4 as vec42 } from "three/tsl";
+var EPSILON2 = 1e-10;
+function gammaRgbToHsv(c) {
+  const p = mix3(vec42(c.b, c.g, -1 / 3, 2 / 3), vec42(c.g, c.b, 0, -1 / 3), step4(c.b, c.g));
+  const q = mix3(vec42(p.x, p.y, p.w, c.r), vec42(c.r, p.y, p.z, p.x), step4(p.x, c.r));
+  const chroma = q.x.sub(min2(q.w, q.y));
+  const hue = abs2(q.z.add(q.w.sub(q.y).div(chroma.mul(6).add(EPSILON2))));
+  const saturation = chroma.div(q.x.add(EPSILON2));
+  return vec32(hue, saturation, q.x);
+}
+function hsvToGammaRgb(hsv) {
+  const hue = hsv.x;
+  const saturation = hsv.y;
+  const value = hsv.z;
+  const ramp = abs2(
+    fract2(vec32(hue).add(vec32(1, 2 / 3, 1 / 3))).mul(6).sub(vec32(3))
+  );
+  return mix3(vec32(1), clamp2(ramp.sub(vec32(1)), 0, 1), saturation).mul(value);
+}
+var hsvSpace = {
+  // Clamp into sRGB before the gamma transfer: HSV is an sRGB-gamut concept, and
+  // the sRGB OETF's pow() can't be WGSL const-evaluated on the negative channels
+  // of an out-of-sRGB (wide-gamut) stop color — that crashed the shader compile.
+  fromLinear: (rgb) => gammaRgbToHsv(linearToSrgb(clamp2(rgb, 0, 1))),
+  toLinear: (hsv) => srgbToLinear(hsvToGammaRgb(hsv)),
+  lerp: (a, b, t, hue) => vec32(hue(a.x, b.x, t, 1), mix3(a.y, b.y, t), mix3(a.z, b.z, t))
+};
+
+// src/primitives/color-space/lch.ts
+import { atan2, cbrt, cos, length, mix as mix4, sin, step as step5, vec2, vec3 as vec33 } from "three/tsl";
+var TWO_PI = Math.PI * 2;
+var WHITE_X = 0.95047;
+var WHITE_Y = 1;
+var WHITE_Z = 1.08883;
+var EPSILON3 = 216 / 24389;
+var KAPPA = 24389 / 27;
+function labForward(ratio) {
+  const linearPart = ratio.mul(KAPPA).add(16).div(116);
+  const cubeRootPart = cbrt(ratio);
+  return mix4(linearPart, cubeRootPart, step5(EPSILON3, ratio));
+}
+function labInverse(f) {
+  const cubed = f.mul(f).mul(f);
+  const linearPart = f.mul(116).sub(16).div(KAPPA);
+  return mix4(linearPart, cubed, step5(EPSILON3, cubed));
+}
+function linearToLch(rgb) {
+  const r = rgb.r;
+  const g = rgb.g;
+  const b = rgb.b;
+  const x = r.mul(0.4123907993).add(g.mul(0.3575843394)).add(b.mul(0.1804807884));
+  const y = r.mul(0.2126390059).add(g.mul(0.7151686788)).add(b.mul(0.0721923154));
+  const z = r.mul(0.0193308187).add(g.mul(0.1191947798)).add(b.mul(0.9505321522));
+  const fx = labForward(x.div(WHITE_X));
+  const fy = labForward(y.div(WHITE_Y));
+  const fz = labForward(z.div(WHITE_Z));
+  const lightness = fy.mul(116).sub(16);
+  const greenRed = fx.sub(fy).mul(500);
+  const blueYellow = fy.sub(fz).mul(200);
+  const chroma = length(vec2(greenRed, blueYellow));
+  const hue = atan2(blueYellow, greenRed);
+  return vec33(lightness, chroma, hue);
+}
+function lchToLinear(lch) {
+  const lightness = lch.x;
+  const chroma = lch.y;
+  const hue = lch.z;
+  const greenRed = chroma.mul(cos(hue));
+  const blueYellow = chroma.mul(sin(hue));
+  const fy = lightness.add(16).div(116);
+  const fx = fy.add(greenRed.div(500));
+  const fz = fy.sub(blueYellow.div(200));
+  const x = labInverse(fx).mul(WHITE_X);
+  const y = labInverse(fy).mul(WHITE_Y);
+  const z = labInverse(fz).mul(WHITE_Z);
+  const r = x.mul(3.2409699419).sub(y.mul(1.5373831776)).sub(z.mul(0.4986107603));
+  const g = x.mul(-0.9692436363).add(y.mul(1.8759675015)).add(z.mul(0.0415550574));
+  const b = x.mul(0.0556300797).sub(y.mul(0.2039769589)).add(z.mul(1.0569715142));
+  return vec33(r, g, b);
+}
+var lchSpace = {
+  fromLinear: linearToLch,
+  toLinear: lchToLinear,
+  lerp: (a, b, t, hue) => vec33(mix4(a.x, b.x, t), mix4(a.y, b.y, t), hue(a.z, b.z, t, TWO_PI))
+};
+
+// src/primitives/color-space/linear.ts
+import { mix as mix5, vec3 as vec34 } from "three/tsl";
+var linearSpace = {
+  fromLinear: (rgb) => vec34(rgb),
+  toLinear: (coords) => vec34(coords),
+  lerp: (a, b, t) => mix5(a, b, t)
+};
+
+// src/primitives/color-space/oklab.ts
+import { cbrt as cbrt2, mix as mix6, vec3 as vec35 } from "three/tsl";
+function linearToOklab(rgb) {
+  const r = rgb.r;
+  const g = rgb.g;
+  const b = rgb.b;
+  const longCone = r.mul(0.4122214708).add(g.mul(0.5363325363)).add(b.mul(0.0514459929));
+  const mediumCone = r.mul(0.2119034982).add(g.mul(0.6806995451)).add(b.mul(0.1073969566));
+  const shortCone = r.mul(0.0883024619).add(g.mul(0.2817188376)).add(b.mul(0.6299787005));
+  const longRoot = cbrt2(longCone);
+  const mediumRoot = cbrt2(mediumCone);
+  const shortRoot = cbrt2(shortCone);
+  const lightness = longRoot.mul(0.2104542553).add(mediumRoot.mul(0.793617785)).sub(shortRoot.mul(0.0040720468));
+  const greenRed = longRoot.mul(1.9779984951).sub(mediumRoot.mul(2.428592205)).add(shortRoot.mul(0.4505937099));
+  const blueYellow = longRoot.mul(0.0259040371).add(mediumRoot.mul(0.7827717662)).sub(shortRoot.mul(0.808675766));
+  return vec35(lightness, greenRed, blueYellow);
+}
+function oklabToLinear(lab) {
+  const lightness = lab.x;
+  const greenRed = lab.y;
+  const blueYellow = lab.z;
+  const longRoot = lightness.add(greenRed.mul(0.3963377774)).add(blueYellow.mul(0.2158037573));
+  const mediumRoot = lightness.sub(greenRed.mul(0.1055613458)).sub(blueYellow.mul(0.0638541728));
+  const shortRoot = lightness.sub(greenRed.mul(0.0894841775)).sub(blueYellow.mul(1.291485548));
+  const longCone = longRoot.mul(longRoot).mul(longRoot);
+  const mediumCone = mediumRoot.mul(mediumRoot).mul(mediumRoot);
+  const shortCone = shortRoot.mul(shortRoot).mul(shortRoot);
+  const r = longCone.mul(4.0767416621).sub(mediumCone.mul(3.3077115913)).add(shortCone.mul(0.2309699292));
+  const g = longCone.mul(-1.2684380046).add(mediumCone.mul(2.6097574011)).sub(shortCone.mul(0.3413193965));
+  const b = longCone.mul(-0.0041960863).sub(mediumCone.mul(0.7034186147)).add(shortCone.mul(1.707614701));
+  return vec35(r, g, b);
+}
+var oklabSpace = {
+  fromLinear: linearToOklab,
+  toLinear: oklabToLinear,
+  lerp: (a, b, t) => mix6(a, b, t)
+};
+
+// src/primitives/color-space/oklch.ts
+import { atan2 as atan22, cos as cos2, length as length2, mix as mix7, sin as sin2, vec2 as vec22, vec3 as vec36 } from "three/tsl";
+var TWO_PI2 = Math.PI * 2;
+function linearToOklch(rgb) {
+  const lab = linearToOklab(rgb);
+  const lightness = lab.x;
+  const greenRed = lab.y;
+  const blueYellow = lab.z;
+  const chroma = length2(vec22(greenRed, blueYellow));
+  const hue = atan22(blueYellow, greenRed);
+  return vec36(lightness, chroma, hue);
+}
+function oklchToLinear(lch) {
+  const lightness = lch.x;
+  const chroma = lch.y;
+  const hue = lch.z;
+  const greenRed = chroma.mul(cos2(hue));
+  const blueYellow = chroma.mul(sin2(hue));
+  return oklabToLinear(vec36(lightness, greenRed, blueYellow));
+}
+var oklchSpace = {
+  fromLinear: linearToOklch,
+  toLinear: oklchToLinear,
+  lerp: (a, b, t, hue) => vec36(mix7(a.x, b.x, t), mix7(a.y, b.y, t), hue(a.z, b.z, t, TWO_PI2))
+};
+
+// src/primitives/color-space/registry.ts
+var colorSpaces = {
+  linear: linearSpace,
+  oklab: oklabSpace,
+  oklch: oklchSpace,
+  lch: lchSpace,
+  hsl: hslSpace,
+  hsv: hsvSpace
+};
+
+// src/primitives/color-ramp/color-ramp.ts
+function colorRamp(t, stops, colorSpace = "linear", hueInterpolation = "shorter") {
+  const space = colorSpaces[colorSpace];
+  const hue = hueArcInterpolators[hueInterpolation];
   const first = stops[0];
-  if (first === void 0) return vec3(0, 0, 0);
-  if (stops.length === 1) return mix(first.color, first.color, 0);
-  let result = mix(first.color, first.color, 0);
+  if (first === void 0) return vec37(0, 0, 0);
+  const firstCoords = space.fromLinear(vec37(first.color));
+  if (stops.length === 1) return space.toLinear(firstCoords);
+  let resultCoords = firstCoords;
   for (let i = 1; i < stops.length; i += 1) {
     const previousStop = stops[i - 1];
     const next = stops[i];
     if (previousStop === void 0 || next === void 0) continue;
     const positionSpan = next.position - previousStop.position;
     if (positionSpan <= 0) continue;
-    const localT = clamp(div(sub(t, previousStop.position), positionSpan), 0, 1);
-    result = mix(result, next.color, localT);
+    const localT = clamp3(div(sub(t, previousStop.position), positionSpan), 0, 1);
+    const nextCoords = space.fromLinear(vec37(next.color));
+    resultCoords = space.lerp(resultCoords, nextCoords, localT, hue);
+  }
+  return space.toLinear(resultCoords);
+}
+
+// src/primitives/color-space/mix-color.ts
+import { vec3 as vec38 } from "three/tsl";
+function mixColor(colorA, colorB, t, colorSpace = "oklab", hueInterpolation = "shorter") {
+  const space = colorSpaces[colorSpace];
+  const hue = hueArcInterpolators[hueInterpolation];
+  const a = space.fromLinear(vec38(colorA));
+  const b = space.fromLinear(vec38(colorB));
+  return space.toLinear(space.lerp(a, b, t, hue));
+}
+
+// src/primitives/color-space/cpu-convert.ts
+function oklabToLinearSrgb(lightness, greenRed, blueYellow) {
+  const longRoot = lightness + 0.3963377774 * greenRed + 0.2158037573 * blueYellow;
+  const mediumRoot = lightness - 0.1055613458 * greenRed - 0.0638541728 * blueYellow;
+  const shortRoot = lightness - 0.0894841775 * greenRed - 1.291485548 * blueYellow;
+  const longCone = longRoot * longRoot * longRoot;
+  const mediumCone = mediumRoot * mediumRoot * mediumRoot;
+  const shortCone = shortRoot * shortRoot * shortRoot;
+  const red = 4.0767416621 * longCone - 3.3077115913 * mediumCone + 0.2309699292 * shortCone;
+  const green = -1.2684380046 * longCone + 2.6097574011 * mediumCone - 0.3413193965 * shortCone;
+  const blue = -0.0041960863 * longCone - 0.7034186147 * mediumCone + 1.707614701 * shortCone;
+  return [red, green, blue];
+}
+function oklchToLinearSrgb(lightness, chroma, hueDegrees) {
+  const hueRadians = hueDegrees * Math.PI / 180;
+  const greenRed = chroma * Math.cos(hueRadians);
+  const blueYellow = chroma * Math.sin(hueRadians);
+  return oklabToLinearSrgb(lightness, greenRed, blueYellow);
+}
+function parseComponent(token, scale) {
+  const trimmed = token.trim();
+  if (trimmed.endsWith("%")) {
+    return parseFloat(trimmed.slice(0, -1)) / 100 * scale;
   }
-  return result;
+  return parseFloat(trimmed);
+}
+function functionArgs(input, prefix) {
+  const inner = input.slice(prefix.length, input.lastIndexOf(")"));
+  const beforeAlpha = inner.split("/")[0] ?? "";
+  return beforeAlpha.trim().split(/[\s,]+/).filter((token) => token.length > 0);
+}
+function parseColorString(input) {
+  const value = input.trim();
+  if (value.startsWith("#")) {
+    const hex = value.slice(1);
+    return [
+      srgbChannelToLinear(parseInt(hex.slice(0, 2), 16) / 255),
+      srgbChannelToLinear(parseInt(hex.slice(2, 4), 16) / 255),
+      srgbChannelToLinear(parseInt(hex.slice(4, 6), 16) / 255)
+    ];
+  }
+  if (value.startsWith("oklch(")) {
+    const [lightnessToken, chromaToken, hueToken] = functionArgs(value, "oklch(");
+    if (lightnessToken === void 0 || chromaToken === void 0 || hueToken === void 0) {
+      throw new Error(`Invalid oklch() color: "${input}"`);
+    }
+    const lightness = parseComponent(lightnessToken, 1);
+    const chroma = parseComponent(chromaToken, 0.4);
+    const hueDegrees = parseFloat(hueToken.replace(/deg$/, ""));
+    return oklchToLinearSrgb(lightness, chroma, hueDegrees);
+  }
+  if (value.startsWith("oklab(")) {
+    const [lightnessToken, aToken, bToken] = functionArgs(value, "oklab(");
+    if (lightnessToken === void 0 || aToken === void 0 || bToken === void 0) {
+      throw new Error(`Invalid oklab() color: "${input}"`);
+    }
+    return oklabToLinearSrgb(
+      parseComponent(lightnessToken, 1),
+      parseComponent(aToken, 0.4),
+      parseComponent(bToken, 0.4)
+    );
+  }
+  throw new Error(`Unsupported color syntax: "${input}". Use #rrggbb, oklch(...), or oklab(...).`);
 }
 
 // src/primitives/noise/noise.ts
@@ -176,9 +555,9 @@ function quantize(t, steps) {
 }
 
 // src/primitives/sdf-circle/sdf-circle.ts
-import { length } from "three/tsl";
+import { length as length3 } from "three/tsl";
 function signedDistanceFieldCircle(p, radius) {
-  return length(p).sub(radius);
+  return length3(p).sub(radius);
 }
 
 // src/primitives/displace/displace.ts
@@ -188,7 +567,7 @@ function displace(p, by) {
 }
 
 // src/primitives/cursor-ripple/cursor-ripple.ts
-import { length as length2, sin, smoothstep, sub as sub2 } from "three/tsl";
+import { length as length4, sin as sin3, smoothstep, sub as sub2 } from "three/tsl";
 
 // src/primitives/time/time.ts
 import { time as _builtinTime } from "three/tsl";
@@ -289,20 +668,41 @@ function cursorRipple(p, center, opts = {}) {
   const frequency = opts.frequency ?? 30;
   const speed = opts.speed ?? 6;
   const amplitude = opts.amplitude ?? 0.5;
-  const d = length2(sub2(p, center));
-  const wave = sin(d.mul(frequency).sub(elapsedTime.mul(speed)));
+  const d = length4(sub2(p, center));
+  const wave = sin3(d.mul(frequency).sub(elapsedTime.mul(speed)));
   const decay = smoothstep(reach, 0, d);
   return wave.mul(amplitude).mul(decay);
 }
 
-// src/primitives/film-grain/film-grain.ts
-import { hash, mul as mul2, screenCoordinate } from "three/tsl";
-function filmGrain(intensity, timeOffset = 0) {
+// src/primitives/grain/grain.ts
+import { float, hash, screenCoordinate } from "three/tsl";
+function grain(intensity, timeOffset = 0) {
   const pixel = screenCoordinate.xy.floor();
-  const seed = pixel.x.toUint().mul(1973).add(pixel.y.toUint().mul(9277)).add(mul2(timeOffset, 26699).toUint());
+  const column = pixel.x.toUint();
+  const row = pixel.y.toUint();
+  const frameHash = hash(float(timeOffset)).mul(16777215).toUint();
+  const rowHash = hash(row.add(frameHash)).mul(16777215).toUint();
+  const seed = column.add(rowHash);
   return hash(seed).sub(0.5).mul(intensity);
 }
 
+// src/primitives/dither/dither.ts
+import { floor, fract as fract3, screenCoordinate as screenCoordinate2, vec2 as vec23, vec3 as vec39, vec4 as vec43 } from "three/tsl";
+function bayer2(coord) {
+  const cell = floor(coord);
+  return fract3(cell.x.mul(0.5).add(cell.y.mul(cell.y).mul(0.75)));
+}
+function bayer4(coord) {
+  return bayer2(coord.mul(0.5)).mul(0.25).add(bayer2(coord));
+}
+function bayer8(coord) {
+  return bayer4(coord.mul(0.5)).mul(0.25).add(bayer2(coord));
+}
+function dither(color, amount = 1 / 255) {
+  const threshold = bayer8(vec23(screenCoordinate2.xy)).sub(0.5);
+  return vec43(vec39(color).add(threshold.mul(amount)), vec43(color).a);
+}
+
 // src/runtime/visibility/visibility.ts
 function createVisibilityWatcher() {
   if (typeof document === "undefined") {
@@ -381,7 +781,7 @@ var FrameScheduler = class {
   // Reference-counted idle voting. The scheduler is idle only when at least
   // one component has voted idle AND no component has voted animated. This
   // prevents a static component (e.g. LinearGradient speed=0) from halting
-  // the loop while an animated overlay (e.g. FilmGrain) is still running.
+  // the loop while an animated overlay (e.g. Grain) is still running.
   idleVotes = 0;
   animatedVotes = 0;
   /** True when all participating components prefer idle and none need animation. */
@@ -513,15 +913,21 @@ export {
   createVisibilityWatcher,
   cursorRipple,
   displace,
+  dither,
   elapsedTime,
-  filmGrain,
   fractalNoise,
   getReducedMotionPolicy,
   getReducedMotionTimeScale,
+  grain,
+  mixColor,
+  oklabToLinearSrgb,
+  oklchToLinearSrgb,
+  parseColorString,
   quantize,
   setReducedMotionPolicy,
   signedDistanceFieldCircle,
   simplexNoise,
+  srgbChannelToLinear,
   voronoi
 };
 //# sourceMappingURL=index.js.map