feat: DatamoshEffect heal params + Datamosh Scroll demo

.changeset/datamosh-intra-refresh.md

@@ -0,0 +1,7 @@
+---
+"@vfx-js/effects": minor
+---
+
+Add heal params to `DatamoshEffect` so the mosh can heal block by
+block like a real codec: `healRate` (random refresh chance per block per
+frame) and `healThreshold` (refresh blocks with bad motion matches).

packages/effects/src/datamosh.ts

@@ -7,14 +7,15 @@
 //
 // - disabled: every frame decoded as intra -> straight passthrough.
 // - enabled: frames decoded as inter -> motion-compensate the held
-//   accumulator + residual, never refreshing it from a clean frame, so
-//   motion keeps dragging stale texture around (the mosh).
+//   accumulator + residual, so motion keeps dragging stale texture around
+//   (the mosh). Only heal-refreshed blocks go back to the clean frame.
 //
 // Pipeline per frame (RGB path):
 //   capture  ctx.src        -> curRT
 //   ME       cur vs prev    -> mvRT   (one fragment per block)
 //   residual cur - mc(prev) -> resRT
 //   decode   intra ? cur : mc(accum, mv) + res -> accRT (persistent)
+//            (per-block intra refresh heals the mosh back to the source)
 //   display  accRT          -> ctx.target
 //   blit     cur            -> prevRT (persistent; next frame's reference)
 //
@@ -40,6 +41,8 @@ void main() {
 // (px) that best matches the current block, into .rg of a float RT.
 // A small length bias breaks ties toward (0,0) so flat blocks don't latch
 // onto spurious large vectors.
+// Also picks the block mode into .b (1 = intra): random refresh, or a
+// poor best match, like an encoder falling back to intra.
 const FRAG_ME = `#version 300 es
 precision highp float;
 out vec4 outMV;
@@ -48,6 +51,13 @@ uniform vec2 uResolution;   // [w, h] in px
 uniform float uBlock;       // block size in px
 uniform float uSearch;      // search radius, in steps
 uniform float uStep;        // px per step (coverage = uSearch * uStep px)
+uniform float uHealRate;
+uniform float uHealThreshold;
+uniform float uFrame;
+float hash(vec3 p) {
+    uvec3 q = uvec3(p) * uvec3(1597334673u, 3812015801u, 2798796415u);
+    return float((q.x ^ q.y ^ q.z) * 1597334673u) / 4294967295.0;
+}
 void main() {
     vec2 block = floor(gl_FragCoord.xy);
     vec2 base = block * uBlock;     // top-left pixel of this block
@@ -66,6 +76,7 @@ void main() {
 
     vec2 move = vec2(0.0);
     float bestSad = 1e9;
+    float bestRaw = 0.0;
     for (float by = -uSearch; by <= uSearch; by++) {
       for (float bx = -uSearch; bx <= uSearch; bx++) {
         vec2 cand = vec2(bx, by) * uStep;   // candidate displacement, px
@@ -74,15 +85,20 @@ void main() {
           vec3 cRef = texture(uRef, (base + off[k] + cand + 0.5) / uResolution).rgb;
           sad += dot(abs(cs[k] - cRef), vec3(1.0));
         }
+        float raw = sad;
         sad += length(cand) * 0.0025;   // prefer small motion on ties
         if (sad < bestSad) {
           bestSad = sad;
+          bestRaw = raw;
           move = cand;
         }
       }
     }
 
-    outMV = vec4(move, 0.0, 1.0);
+    // Mean abs diff per channel, 0..1.
+    float err = bestRaw / 27.0;
+    bool intra = hash(vec3(block, uFrame)) < uHealRate || err > uHealThreshold;
+    outMV = vec4(move, intra ? 1.0 : 0.0, 1.0);
 }
 `;
 
@@ -112,7 +128,7 @@ uniform vec2 uResolution;
 uniform bool uIntra;
 uniform bool uUseResidual;
 void main() {
-    if (uIntra) {
+    if (uIntra || texture(uMV, uv).b > 0.5) {
         outColor = vec4(texture(uVideo, uv).rgb, 1.0);
         return;
     }
@@ -195,7 +211,7 @@ uniform bool uIntra;
 uniform bool uUseResidual;
 void main() {
     // I-frame: passthrough the input
-    if (uIntra) {
+    if (uIntra || texture(uMV, uv).b > 0.5) {
         outColor = vec4(luma(texture(uVideo, uv).rgb), 0.0, 0.0, 1.0);
         return;
     }
@@ -225,7 +241,7 @@ uniform bool uIntra;
 uniform bool uUseResidual;
 void main() {
     // I-frame: passthrough the input
-    if (uIntra) {
+    if (uIntra || texture(uMV, uv).b > 0.5) {
         outColor = vec4(chroma(texture(uVideo, uv).rgb), 0.0, 1.0);
         return;
     }
@@ -294,6 +310,17 @@ export type DatamoshParams = {
     colorSpace: DatamoshColorSpace;
     /** Chroma saturation boost (YCbCr output). 1 = unchanged. */
     chromaGain: number;
+    /**
+     * Chance per block per frame to refresh from the clean frame (0..1).
+     * Ramp up to heal the mosh gradually.
+     * Works with `healThreshold`: a block refreshes if either one hits.
+     */
+    healRate: number;
+    /**
+     * Refresh blocks whose best motion match is worse than this.
+     * Mean abs diff per channel (0..1); 1 = never.
+     */
+    healThreshold: number;
     /** Stage shown on the canvas. */
     view: DatamoshView;
 };
@@ -306,6 +333,8 @@ const DEFAULT_PARAMS: DatamoshParams = {
     dup: 0,
     colorSpace: "ycbcr",
     chromaGain: 1,
+    healRate: 0,
+    healThreshold: 1,
     view: "output",
 };
 
@@ -336,6 +365,7 @@ export class DatamoshEffect implements Effect {
     #cw = 0;
     #ch = 0;
     #block = 0;
+    #frame = 0;
     // Re-seed when the color model flips (accumulators change meaning).
     #lastColorSpace: DatamoshColorSpace;
 
@@ -472,6 +502,9 @@ export class DatamoshEffect implements Effect {
                     uBlock: this.#block,
                     uSearch: this.params.searchRange,
                     uStep: this.params.searchStep,
+                    uHealRate: this.params.healRate,
+                    uHealThreshold: this.params.healThreshold,
+                    uFrame: this.#frame++ % 65536,
                 },
                 target: mv,
             });

packages/examples/src/works.ts

@@ -179,4 +179,15 @@ export const works: Work[] = [
             "A playground for the Figma shader effect ports: warp, slice shift, pixel stretch, pattern refraction, pixelate, dither, and colored edges. Pick an image and tweak every parameter live with Tweakpane.",
         url: "./works/figma-effects.html",
     },
+    {
+        id: "datamosh-scroll",
+        index: "16",
+        title: "Datamosh Scroll",
+        tags: ["effect-api", "Glitch", "Transition"],
+        year: "2026",
+        author: "AMAGI",
+        description:
+            "A day of skateboarding, told as a one-page scroll site. Every section change drops the keyframe: the next scene's motion drags the last one along until intra refresh heals it block by block.",
+        url: "./works/datamosh-scroll.html",
+    },
 ];