@nodetool-ai/gpu 0.8.3 → 0.8.4-a24.1

package/dist/.nodetool-build-stamp

@@ -1 +1 @@
-2026-10-12T12:29:47.616Z
+2026-10-16T07:29:05.468Z

package/dist/shaders/filters/grain/v1/module.d.ts

@@ -1,36 +1,39 @@
 /**
- * `filters.grain@1` — film grain as a multiplicative gain wobble.
+ * `filters.grain@1` — film grain modelled on exposed stock.
  *
- * **Multiplied, not added.** The input is premultiplied, so `rgb <= a` holds on
- * every pixel and adding noise would break it: a translucent layer would come
- * back with channels brighter than its own alpha, which reads as a bright
- * fringe once it composites. A scalar gain preserves the invariant (the same
- * reason `filters.vignette@1` may scale), and it is also closer to how exposed
- * stock behaves — grain bites in the midtones and leaves black black, because
- * there is nothing there to modulate.
+ * **Bell-shaped, clumped, two octaves.** Each lattice point draws roughly
+ * Gaussian noise (three hashes summed), and smooth value noise interpolates
+ * between points, so `size` grows soft clumps rather than square blocks. A
+ * second octave at twice the frequency adds the fine layer real grain has.
  *
- * **Reproducible.** The pattern is a hash of the grain cell and `seed`, with no
+ * **Follows exposure.** The noise is added to the straight colour and weighted
+ * by luma: zero in pure black, strongest through shadows and midtones, thinner
+ * in the highlights. The result is clamped to 0..1 and premultiplied again, so
+ * `rgb <= a` holds by construction on a translucent layer.
+ *
+ * **Reproducible.** The pattern is a hash of the lattice and `seed`, with no
  * clock and no RNG state, so two renders of the same frame are byte-identical
  * and a cached render can be handed back. A host that wants the pattern to roll
- * passes the frame's own time as the seed.
+ * passes the frame's own time as the seed; the shader folds it into a small
+ * exact integer so large frame times keep their precision.
  */
 import * as d from "typegpu/data";
 export declare const GrainParams: d.WgslStruct<{
-    /** Gain wobble, 0..1. 0 leaves the picture untouched. */
+    /** Grain strength, 0..1. 1 is a 0.15 deviation in midtones. 0 is a no-op. */
     amount: d.F32;
-    /** Grain cell size in source pixels. 1 is per-pixel. */
+    /** Grain clump size in source pixels. 1 is per-pixel; larger is softer, coarser stock. */
     size: d.F32;
-    /** 0 = one gain for the pixel (monochrome), 1 = per-channel colour noise. */
+    /** 0 = one noise value for the pixel (monochrome), 1 = per-channel colour noise. */
     colorAmount: d.F32;
     /** Rolls the pattern. Same seed, same grain. */
     seed: d.F32;
 }>;
 export declare const filtersGrainV1: import("../../../../module.js").ShaderModule<d.WgslStruct<{
-    /** Gain wobble, 0..1. 0 leaves the picture untouched. */
+    /** Grain strength, 0..1. 1 is a 0.15 deviation in midtones. 0 is a no-op. */
     amount: d.F32;
-    /** Grain cell size in source pixels. 1 is per-pixel. */
+    /** Grain clump size in source pixels. 1 is per-pixel; larger is softer, coarser stock. */
     size: d.F32;
-    /** 0 = one gain for the pixel (monochrome), 1 = per-channel colour noise. */
+    /** 0 = one noise value for the pixel (monochrome), 1 = per-channel colour noise. */
     colorAmount: d.F32;
     /** Rolls the pattern. Same seed, same grain. */
     seed: d.F32;

package/dist/shaders/filters/grain/v1/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../../../src/shaders/filters/grain/v1/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAGlC,eAAO,MAAM,WAAW;IACtB,yDAAyD;;IAEzD,wDAAwD;;IAExD,6EAA6E;;IAE7E,gDAAgD;;EAEhD,CAAC;AAQH,eAAO,MAAM,cAAc;IAhBzB,yDAAyD;;IAEzD,wDAAwD;;IAExD,6EAA6E;;IAE7E,gDAAgD;;GAoFhD,CAAC"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../../../src/shaders/filters/grain/v1/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAGlC,eAAO,MAAM,WAAW;IACtB,6EAA6E;;IAE7E,0FAA0F;;IAE1F,oFAAoF;;IAEpF,gDAAgD;;EAEhD,CAAC;AAQH,eAAO,MAAM,cAAc;IAhBzB,6EAA6E;;IAE7E,0FAA0F;;IAE1F,oFAAoF;;IAEpF,gDAAgD;;GA0IhD,CAAC"}

package/dist/shaders/filters/grain/v1/module.js

@@ -1,28 +1,31 @@
 /**
- * `filters.grain@1` — film grain as a multiplicative gain wobble.
+ * `filters.grain@1` — film grain modelled on exposed stock.
  *
- * **Multiplied, not added.** The input is premultiplied, so `rgb <= a` holds on
- * every pixel and adding noise would break it: a translucent layer would come
- * back with channels brighter than its own alpha, which reads as a bright
- * fringe once it composites. A scalar gain preserves the invariant (the same
- * reason `filters.vignette@1` may scale), and it is also closer to how exposed
- * stock behaves — grain bites in the midtones and leaves black black, because
- * there is nothing there to modulate.
+ * **Bell-shaped, clumped, two octaves.** Each lattice point draws roughly
+ * Gaussian noise (three hashes summed), and smooth value noise interpolates
+ * between points, so `size` grows soft clumps rather than square blocks. A
+ * second octave at twice the frequency adds the fine layer real grain has.
  *
- * **Reproducible.** The pattern is a hash of the grain cell and `seed`, with no
+ * **Follows exposure.** The noise is added to the straight colour and weighted
+ * by luma: zero in pure black, strongest through shadows and midtones, thinner
+ * in the highlights. The result is clamped to 0..1 and premultiplied again, so
+ * `rgb <= a` holds by construction on a translucent layer.
+ *
+ * **Reproducible.** The pattern is a hash of the lattice and `seed`, with no
  * clock and no RNG state, so two renders of the same frame are byte-identical
  * and a cached render can be handed back. A host that wants the pattern to roll
- * passes the frame's own time as the seed.
+ * passes the frame's own time as the seed; the shader folds it into a small
+ * exact integer so large frame times keep their precision.
  */
 import tgpu from "typegpu";
 import * as d from "typegpu/data";
 import { defineModule } from "../../../../module.js";
 export const GrainParams = d.struct({
-    /** Gain wobble, 0..1. 0 leaves the picture untouched. */
+    /** Grain strength, 0..1. 1 is a 0.15 deviation in midtones. 0 is a no-op. */
     amount: d.f32,
-    /** Grain cell size in source pixels. 1 is per-pixel. */
+    /** Grain clump size in source pixels. 1 is per-pixel; larger is softer, coarser stock. */
     size: d.f32,
-    /** 0 = one gain for the pixel (monochrome), 1 = per-channel colour noise. */
+    /** 0 = one noise value for the pixel (monochrome), 1 = per-channel colour noise. */
     colorAmount: d.f32,
     /** Rolls the pattern. Same seed, same grain. */
     seed: d.f32
@@ -58,9 +61,45 @@ fn hash31(p: vec3f) -> f32 {
   return fract((p3.x + p3.y) * p3.z);
 }
 
-/** Signed noise in [-1, 1] for one grain cell and channel. */
-fn grainAt(cell: vec2f, seed: f32, channel: f32) -> f32 {
-  return hash31(vec3f(cell.x, cell.y, seed + channel * 19.19)) * 2.0 - 1.0;
+/**
+ * Approximately Gaussian noise with unit deviation at one lattice point: the
+ * sum of three uniform hashes (Irwin-Hall), centred and rescaled. Real grain is
+ * the sum of many silver crystals, so its density is bell-shaped, not flat.
+ */
+fn gaussAt(cell: vec2f, seed: f32) -> f32 {
+  let a = hash31(vec3f(cell.x, cell.y, seed));
+  let b = hash31(vec3f(cell.x + 57.0, cell.y + 57.0, seed));
+  let c = hash31(vec3f(cell.x + 113.0, cell.y + 113.0, seed));
+  return (a + b + c - 1.5) * 2.0;
+}
+
+/**
+ * Smooth value noise over the grain lattice. Interpolating between lattice
+ * points turns a large size into soft clumps instead of hard square blocks. At
+ * integer coordinates the weights are exactly zero, so size 1 returns the
+ * lattice value itself: fine, per-pixel grain.
+ */
+fn valueNoise(p: vec2f, seed: f32) -> f32 {
+  let i = floor(p);
+  let f = p - i;
+  let u = f * f * (vec2f(3.0) - 2.0 * f);
+  let n00 = gaussAt(i, seed);
+  let n10 = gaussAt(i + vec2f(1.0, 0.0), seed);
+  let n01 = gaussAt(i + vec2f(0.0, 1.0), seed);
+  let n11 = gaussAt(i + vec2f(1.0, 1.0), seed);
+  return mix(mix(n00, n10, u.x), mix(n01, n11, u.x), u.y);
+}
+
+/**
+ * Two octaves: the clump at the chosen size and a finer layer at twice the
+ * frequency. The doubling and the fixed offset keep every floored coordinate an
+ * exact float, so the CPU mirror can reproduce the lattice bit for bit.
+ */
+fn grainAt(p: vec2f, seed: f32, channel: f32) -> f32 {
+  let s = seed + channel * 19.19;
+  let coarse = valueNoise(p, s);
+  let fine = valueNoise(p * 2.0 + vec2f(17.0, 29.0), s + 7.0);
+  return (coarse + 0.5 * fine) * 0.8944;
 }
 
 @compute @workgroup_size(16, 16, 1)
@@ -70,24 +109,42 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   let coords = vec2<i32>(i32(gid.x), i32(gid.y));
   let v = layout.$.params;
   let color = textureLoad(layout.$.source, coords, 0);
+  if (color.a <= 0.0) {
+    textureStore(layout.$.outputTexture, coords, color);
+    return;
+  }
 
-  // Quantize to grain cells so size coarsens the stock instead of just
-  // reseeding it. Sub-pixel sizes collapse back to per-pixel.
-  let cell = floor(vec2f(f32(gid.x), f32(gid.y)) / max(v.size, 1.0));
+  // Fold the seed into a small exact integer, then turn it into a whole-pixel
+  // shift of the lattice. Frame-time seeds run into the hundreds of thousands,
+  // where f32 hashing loses the bits that make consecutive frames differ.
+  let folded = v.seed - 8192.0 * floor(v.seed / 8192.0);
+  let shift = floor(vec2f(
+    hash31(vec3f(folded, 1.7, 9.2)),
+    hash31(vec3f(folded, 4.1, 3.3))
+  ) * 512.0);
+  let p = vec2f(f32(gid.x), f32(gid.y)) / max(v.size, 1.0) + shift;
 
-  let mono = grainAt(cell, v.seed, 0.0);
-  let perChannel = vec3f(
-    grainAt(cell, v.seed, 1.0),
-    grainAt(cell, v.seed, 2.0),
-    grainAt(cell, v.seed, 3.0)
-  );
-  let n = mix(vec3f(mono), perChannel, clamp(v.colorAmount, 0.0, 1.0));
+  let mono = grainAt(p, folded, 0.0);
+  var n = vec3f(mono);
+  if (v.colorAmount > 0.0) {
+    let perChannel = vec3f(
+      grainAt(p, folded, 1.0),
+      grainAt(p, folded, 2.0),
+      grainAt(p, folded, 3.0)
+    );
+    n = mix(n, perChannel, clamp(v.colorAmount, 0.0, 1.0));
+  }
 
-  let gain = vec3f(1.0) + n * clamp(v.amount, 0.0, 1.0);
-  // Saturating against alpha rather than 1.0 is what keeps rgb <= a when the
-  // gain runs above 1 on an already-bright premultiplied pixel.
-  let rgb = clamp(color.rgb * gain, vec3f(0.0), vec3f(color.a)); // premul: ok
-  textureStore(layout.$.outputTexture, coords, vec4<f32>(rgb, color.a));
+  // Work on the straight colour: grain follows exposure, not coverage.
+  let straight = color.rgb / color.a;
+  let luma = dot(straight, vec3f(0.2126, 0.7152, 0.0722));
+  // Film response: nothing to expose in pure black, strongest through the
+  // shadows and midtones, thinning out toward the highlights.
+  let response = clamp(luma * 6.0, 0.0, 1.0) * (1.0 - 0.65 * luma * luma);
+  let sigma = clamp(v.amount, 0.0, 1.0) * 0.15 * response;
+  let grained = clamp(straight + n * sigma, vec3f(0.0), vec3f(1.0));
+  // Re-premultiplying a value in 0..1 keeps rgb <= a by construction.
+  textureStore(layout.$.outputTexture, coords, vec4<f32>(grained * color.a, color.a));
 }
 `,
     io: {

package/dist/shaders/filters/grain/v1/module.js.map

@@ -1 +1 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../../../../../src/shaders/filters/grain/v1/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,yDAAyD;IACzD,MAAM,EAAE,CAAC,CAAC,GAAG;IACb,wDAAwD;IACxD,IAAI,EAAE,CAAC,CAAC,GAAG;IACX,6EAA6E;IAC7E,WAAW,EAAE,CAAC,CAAC,GAAG;IAClB,gDAAgD;IAChD,IAAI,EAAE,CAAC,CAAC,GAAG;CACZ,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC;IAClC,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;IAC5B,aAAa,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE;IAC/C,MAAM,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;CACjC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;IACzC,EAAE,EAAE,eAAe;IACnB,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,UAAU;IACnB,QAAQ,EAAE,SAAS;IACnB,0EAA0E;IAC1E,iDAAiD;IACjD,SAAS,EAAE,eAAe;IAC1B,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,WAAW;IACnB,aAAa,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IAC9D,OAAO,EAAE;QACP,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE;QACvD,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE;QACnD,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE;QAC5D,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;KACxB;IACD,MAAM;IACN,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC1B,IAAI,EAAE,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsClB;IACC,EAAE,EAAE;QACF,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,UAAU,EAAE,MAAM;gBAClB,KAAK,EAAE,eAAe;gBACtB,YAAY,EAAE,CAAC,YAAY,CAAC;aAC7B;SACF;QACD,MAAM,EAAE;YACN,UAAU,EAAE,MAAM;YAClB,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,gBAAgB;SAC7B;QACD,GAAG,EAAE,gBAAgB;KACtB;CACF,CAAC,CAAC"}
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../../../../src/shaders/filters/grain/v1/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,6EAA6E;IAC7E,MAAM,EAAE,CAAC,CAAC,GAAG;IACb,0FAA0F;IAC1F,IAAI,EAAE,CAAC,CAAC,GAAG;IACX,oFAAoF;IACpF,WAAW,EAAE,CAAC,CAAC,GAAG;IAClB,gDAAgD;IAChD,IAAI,EAAE,CAAC,CAAC,GAAG;CACZ,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC;IAClC,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;IAC5B,aAAa,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE;IAC/C,MAAM,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;CACjC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;IACzC,EAAE,EAAE,eAAe;IACnB,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,UAAU;IACnB,QAAQ,EAAE,SAAS;IACnB,0EAA0E;IAC1E,iDAAiD;IACjD,SAAS,EAAE,eAAe;IAC1B,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,WAAW;IACnB,aAAa,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IAC9D,OAAO,EAAE;QACP,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE;QACvD,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE;QACnD,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE;QAC5D,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;KACxB;IACD,MAAM;IACN,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC1B,IAAI,EAAE,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4FlB;IACC,EAAE,EAAE;QACF,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,UAAU,EAAE,MAAM;gBAClB,KAAK,EAAE,eAAe;gBACtB,YAAY,EAAE,CAAC,YAAY,CAAC;aAC7B;SACF;QACD,MAAM,EAAE;YACN,UAAU,EAAE,MAAM;YAClB,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,gBAAgB;SAC7B;QACD,GAAG,EAAE,gBAAgB;KACtB;CACF,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodetool-ai/gpu",
-  "version": "0.8.3",
+  "version": "0.8.4-a24.1",
   "description": "Canonical blend-mode catalog and shared WGSL blend functions for NodeTool compositors (sketch, timeline, Compositor node)",
   "type": "module",
   "engines": {
@@ -15,10 +15,8 @@
     "lint": "node ../../scripts/run-tsc.mjs --noEmit"
   },
   "dependencies": {
-    "@nodetool-ai/protocol": "0.8.3",
-    "typegpu": "^0.11.6"
-  },
-  "optionalDependencies": {
+    "@nodetool-ai/protocol": "0.8.4-a24.1",
+    "typegpu": "^0.11.6",
     "webgpu": "^0.4.0"
   },
   "devDependencies": {