@lovo/matter 0.6.0 → 2.0.0

package/dist/index.d.ts

@@ -314,24 +314,42 @@ declare function cursorRipple(p: TSLNode, center: TSLNode, opts?: CursorRippleOp
 
 declare const elapsedTime: ShaderNodeObject<Node>;
 
+/**
+ * Zero the renderer's animation clock so the next rendered frame is t=0.
+ *
+ * `elapsedTime` (and three's built-in `time`) accumulate real frame deltas from
+ * the moment the renderer starts, which includes a nondeterministic WebGPU
+ * init + shader-compile warmup. Resetting the per-renderer `nodeFrame` clock
+ * makes every shader start from a fixed phase, so the first visible frame
+ * matches the deterministic poster/snapshot frame.
+ *
+ * Per-renderer by construction: each ShaderScene owns one renderer, so resetting
+ * here isolates scenes from one another. No-ops safely if three's internal
+ * shape ever changes.
+ */
+declare function resetRendererClock(renderer: WebGPURenderer): void;
+
 type TSLScalar = TSLNode | number;
-declare function filmGrain(intensity: TSLScalar, timeOffset?: TSLScalar): ShaderNodeObject<Node>;
+declare function grain(intensity: TSLScalar, timeOffset?: TSLScalar): ShaderNodeObject<Node>;
 
 /**
- * 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.
+ * 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, coord: TSLNode, amount?: number): ShaderNodeObject<Node>;
+declare function dither(color: TSLNode, amount?: number): ShaderNodeObject<Node>;
 
 type ReducedMotionPolicy = 'auto' | 'off' | 'slow' | 'paused';
 /**
@@ -453,4 +471,4 @@ declare class FrameScheduler {
     private readonly frame;
 }
 
-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 };
+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, resetRendererClock, setReducedMotionPolicy, signedDistanceFieldCircle, simplexNoise, srgbChannelToLinear, voronoi };

package/dist/index.js

@@ -674,25 +674,55 @@ function cursorRipple(p, center, opts = {}) {
   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/runtime/clock/reset-clock.ts
+function getNodeFrame(renderer) {
+  const candidate = renderer;
+  if (!(typeof candidate === "object" && candidate !== null && "_nodes" in candidate)) {
+    return void 0;
+  }
+  const nodes = candidate._nodes;
+  if (!(typeof nodes === "object" && nodes !== null && "nodeFrame" in nodes)) {
+    return void 0;
+  }
+  const frame = nodes.nodeFrame;
+  if (typeof frame !== "object" || frame === null) return void 0;
+  return frame;
+}
+function resetRendererClock(renderer) {
+  const nodeFrame = getNodeFrame(renderer);
+  if (!nodeFrame) return;
+  nodeFrame.time = 0;
+  nodeFrame.deltaTime = 0;
+  nodeFrame.lastTime = void 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 { dot, fract as fract3, sin as sin4, vec2 as vec23, vec3 as vec39 } from "three/tsl";
-function hash21(coord) {
-  return fract3(sin4(dot(coord, vec23(12.9898, 78.233))).mul(43758.5453));
+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, coord, amount = 1 / 255) {
-  const pixelCoord = vec23(coord);
-  const firstHash = hash21(pixelCoord);
-  const secondHash = hash21(pixelCoord.add(vec23(0.5, 0.5)));
-  const triangularNoise = firstHash.sub(secondHash).mul(0.5);
-  return vec39(color).add(triangularNoise.mul(amount));
+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
@@ -773,7 +803,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. */
@@ -907,15 +937,16 @@ export {
   displace,
   dither,
   elapsedTime,
-  filmGrain,
   fractalNoise,
   getReducedMotionPolicy,
   getReducedMotionTimeScale,
+  grain,
   mixColor,
   oklabToLinearSrgb,
   oklchToLinearSrgb,
   parseColorString,
   quantize,
+  resetRendererClock,
   setReducedMotionPolicy,
   signedDistanceFieldCircle,
   simplexNoise,