@hyperframes/core 0.8.70 → 0.8.71

package/dist/vfx/displacementMap.frag.d.ts

@@ -1,13 +1,16 @@
 /**
  * `displacement-map` kernel — GLSL ES 3.00, capture `self`.
  *
- * **Scope (v1, recorded rather than implied):** every corpus instance points
- * its Displacement Map Layer at **the layer itself** (retro-wave `Main/Text`
- * → idx 5 = Text; `Logo Anim/Text Site` and `Logo Anim/Logo` likewise), so
- * `u_src` is both the source and the map and no second capture is needed. A
- * map that is a *different* layer is out of v1 — it needs a second source,
- * which is Phase 2b's `ref`-param shape; the exporter emits a structural
- * capability for it instead.
+ * **The map layer.** Every corpus instance points its Displacement Map Layer
+ * at **the layer itself** (retro-wave `Main/Text` → idx 5 = Text; `Logo Anim/
+ * Text Site` and `Logo Anim/Logo` likewise), so `u_src` is both the source and
+ * the map and no second capture is needed — that is what the `map` ref param
+ * being EMPTY means, and it stays the default. An external map layer is the
+ * same kernel reading `u_src2`: the exporter names that element in `map` and
+ * wraps it in its own `.hf-vfx-src` capture, and `u_hasSrc2` switches the
+ * sampler. The two inputs are read at the same `v_uv`, so an external map is
+ * scaled into the host's box (see `captureSource`), not placed in composition
+ * space.
  *
  * Per axis: `d = (channel(map) − 0.5) · 2 · max`, then sample `u_src` at
  * `uv + d/u_size` with **clamp-to-transparent** edges (Edge = Off, the only

package/dist/vfx/displacementMap.frag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"displacementMap.frag.d.ts","sourceRoot":"","sources":["../../src/vfx/displacementMap.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B;;;;CAI7B,CAAC;AAIX,eAAO,MAAM,qBAAqB,QA2CjC,CAAC"}
+{"version":3,"file":"displacementMap.frag.d.ts","sourceRoot":"","sources":["../../src/vfx/displacementMap.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B;;;;CAI7B,CAAC;AAIX,eAAO,MAAM,qBAAqB,QA+CjC,CAAC"}

package/dist/vfx/displacementMap.frag.js

@@ -1,13 +1,16 @@
 /**
  * `displacement-map` kernel — GLSL ES 3.00, capture `self`.
  *
- * **Scope (v1, recorded rather than implied):** every corpus instance points
- * its Displacement Map Layer at **the layer itself** (retro-wave `Main/Text`
- * → idx 5 = Text; `Logo Anim/Text Site` and `Logo Anim/Logo` likewise), so
- * `u_src` is both the source and the map and no second capture is needed. A
- * map that is a *different* layer is out of v1 — it needs a second source,
- * which is Phase 2b's `ref`-param shape; the exporter emits a structural
- * capability for it instead.
+ * **The map layer.** Every corpus instance points its Displacement Map Layer
+ * at **the layer itself** (retro-wave `Main/Text` → idx 5 = Text; `Logo Anim/
+ * Text Site` and `Logo Anim/Logo` likewise), so `u_src` is both the source and
+ * the map and no second capture is needed — that is what the `map` ref param
+ * being EMPTY means, and it stays the default. An external map layer is the
+ * same kernel reading `u_src2`: the exporter names that element in `map` and
+ * wraps it in its own `.hf-vfx-src` capture, and `u_hasSrc2` switches the
+ * sampler. The two inputs are read at the same `v_uv`, so an external map is
+ * scaled into the host's box (see `captureSource`), not placed in composition
+ * space.
  *
  * Per axis: `d = (channel(map) − 0.5) · 2 · max`, then sample `u_src` at
  * `uv + d/u_size` with **clamp-to-transparent** edges (Edge = Off, the only
@@ -48,6 +51,10 @@ uniform vec2 u_size;
 uniform float u_t;
 uniform float u_fps;
 uniform sampler2D u_src;
+uniform sampler2D u_src2;
+// 1 when the map ref named another element, 0 when the map is the layer
+// itself. Set by the runtime for every pass, from whether a ref resolved.
+uniform float u_hasSrc2;
 uniform float u_useH;
 uniform float u_maxH;
 uniform float u_useV;
@@ -75,7 +82,7 @@ float hfMapChannel(vec4 premultiplied, float selector) {
 }
 
 void main() {
-  vec4 mapTexel = texture(u_src, v_uv);
+  vec4 mapTexel = u_hasSrc2 > 0.5 ? texture(u_src2, v_uv) : texture(u_src, v_uv);
   float h = hfMapChannel(mapTexel, u_useH);
   float v = hfMapChannel(mapTexel, u_useV);
   vec2 d = vec2((h - 0.5) * 2.0 * u_maxH, (v - 0.5) * 2.0 * u_maxV);

package/dist/vfx/displacementMap.frag.js.map

@@ -1 +1 @@
-{"version":3,"file":"displacementMap.frag.js","sourceRoot":"","sources":["../../src/vfx/displacementMap.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,KAAK;CACJ,CAAC;AAEX,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,0BAA0B,CAAC;AAE3D,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CA+BQ,KAAK,KAAK,KAAK,KAAK,KAAK;;;;;;;;;;;;CAYrE,CAAC"}
+{"version":3,"file":"displacementMap.frag.js","sourceRoot":"","sources":["../../src/vfx/displacementMap.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,KAAK;CACJ,CAAC;AAEX,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,0BAA0B,CAAC;AAE3D,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CAmCQ,KAAK,KAAK,KAAK,KAAK,KAAK;;;;;;;;;;;;CAYrE,CAAC"}

package/dist/vfx/lumaMatte.frag.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `luma-matte` kernel — GLSL ES 3.00, capture `self` plus a `ref` second
+ * source.
+ *
+ * **What it ports.** Not a single After Effects effect: this is the runtime
+ * form of every matte the exporter cannot express as CSS — a track matte whose
+ * source layer is unsupported (`matte-source-unsupported:*`), a stencil or
+ * silhouette (`stencil-*`), and Set Matte. All of them are the same
+ * per-pixel operation, `out = src · coverage(matte)`, differing only in which
+ * element is the source and which is the matte. The exporter decides that by
+ * choosing which element the host wraps and which the `matte` ref names; a
+ * stencil is this kernel with the host's own content as the matte.
+ *
+ * **Coverage.** `src` arrives premultiplied, so scaling all four channels by a
+ * single coverage value is the whole operation — no unpremultiply/repremultiply
+ * round trip, and a coverage of 0 yields a genuinely empty pixel rather than a
+ * black one.
+ *
+ * - Alpha (1) / Alpha Inverted (2): the matte's alpha.
+ * - Luma (3) / Luma Inverted (4): the matte's luminance **composited over
+ *   black**, which is what the premultiplied texel already holds — a matte that
+ *   is 50 % grey at 50 % opacity reads as 0.25, matching After Effects, where a
+ *   luma matte's transparent regions are black rather than ignored.
+ *
+ * Rec.601 weights, shared with `displacement-map`'s Luminance channel selector
+ * so the two agree on what "luminance" means.
+ *
+ * **Out of scope in v1, recorded rather than implied:** the matte is sampled at
+ * the host's own `v_uv`, so the runtime captures it into the host's box (see
+ * `captureSource`). After Effects places a matte layer in composition space
+ * with its own transform; a matte whose box differs from the layer's is
+ * therefore stretched here, not positioned. Every corpus matte is a
+ * full-frame sibling of its layer, where the two agree.
+ */
+/** The `mode` enum, named once so the def, the shader and the reference agree. */
+export declare const LUMA_MATTE_MODES: {
+    readonly alpha: 1;
+    readonly alphaInverted: 2;
+    readonly luma: 3;
+    readonly lumaInverted: 4;
+};
+export declare const LUMA_MATTE_FRAG: string;
+//# sourceMappingURL=lumaMatte.frag.d.ts.map

package/dist/vfx/lumaMatte.frag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lumaMatte.frag.d.ts","sourceRoot":"","sources":["../../src/vfx/lumaMatte.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,kFAAkF;AAClF,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAEX,eAAO,MAAM,eAAe,QA4B3B,CAAC"}

package/dist/vfx/lumaMatte.frag.js

@@ -0,0 +1,73 @@
+/**
+ * `luma-matte` kernel — GLSL ES 3.00, capture `self` plus a `ref` second
+ * source.
+ *
+ * **What it ports.** Not a single After Effects effect: this is the runtime
+ * form of every matte the exporter cannot express as CSS — a track matte whose
+ * source layer is unsupported (`matte-source-unsupported:*`), a stencil or
+ * silhouette (`stencil-*`), and Set Matte. All of them are the same
+ * per-pixel operation, `out = src · coverage(matte)`, differing only in which
+ * element is the source and which is the matte. The exporter decides that by
+ * choosing which element the host wraps and which the `matte` ref names; a
+ * stencil is this kernel with the host's own content as the matte.
+ *
+ * **Coverage.** `src` arrives premultiplied, so scaling all four channels by a
+ * single coverage value is the whole operation — no unpremultiply/repremultiply
+ * round trip, and a coverage of 0 yields a genuinely empty pixel rather than a
+ * black one.
+ *
+ * - Alpha (1) / Alpha Inverted (2): the matte's alpha.
+ * - Luma (3) / Luma Inverted (4): the matte's luminance **composited over
+ *   black**, which is what the premultiplied texel already holds — a matte that
+ *   is 50 % grey at 50 % opacity reads as 0.25, matching After Effects, where a
+ *   luma matte's transparent regions are black rather than ignored.
+ *
+ * Rec.601 weights, shared with `displacement-map`'s Luminance channel selector
+ * so the two agree on what "luminance" means.
+ *
+ * **Out of scope in v1, recorded rather than implied:** the matte is sampled at
+ * the host's own `v_uv`, so the runtime captures it into the host's box (see
+ * `captureSource`). After Effects places a matte layer in composition space
+ * with its own transform; a matte whose box differs from the layer's is
+ * therefore stretched here, not positioned. Every corpus matte is a
+ * full-frame sibling of its layer, where the two agree.
+ */
+import { DISPLACEMENT_MAP_CONSTANTS } from "./displacementMap.frag.js";
+const { lumaR, lumaG, lumaB } = DISPLACEMENT_MAP_CONSTANTS;
+/** The `mode` enum, named once so the def, the shader and the reference agree. */
+export const LUMA_MATTE_MODES = {
+    alpha: 1,
+    alphaInverted: 2,
+    luma: 3,
+    lumaInverted: 4,
+};
+export const LUMA_MATTE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 v_uv;
+out vec4 fragColor;
+
+uniform vec2 u_size;
+uniform float u_t;
+uniform float u_fps;
+uniform sampler2D u_src;
+uniform sampler2D u_src2;
+uniform float u_mode;
+
+// The matte texel is premultiplied, so its rgb is already "over black" — the
+// composite After Effects reads a luma matte through.
+float hfCoverage(vec4 matte, float mode) {
+  if (mode < 1.5) return matte.a;
+  if (mode < 2.5) return 1.0 - matte.a;
+  float luma = dot(matte.rgb, vec3(${lumaR}, ${lumaG}, ${lumaB}));
+  if (mode < 3.5) return luma;
+  return 1.0 - luma;
+}
+
+void main() {
+  vec4 src = texture(u_src, v_uv);
+  vec4 matte = texture(u_src2, v_uv);
+  fragColor = src * clamp(hfCoverage(matte, u_mode), 0.0, 1.0);
+}
+`;
+//# sourceMappingURL=lumaMatte.frag.js.map

package/dist/vfx/lumaMatte.frag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lumaMatte.frag.js","sourceRoot":"","sources":["../../src/vfx/lumaMatte.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEpE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,0BAA0B,CAAC;AAE3D,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,CAAC;IACR,aAAa,EAAE,CAAC;IAChB,IAAI,EAAE,CAAC;IACP,YAAY,EAAE,CAAC;CACP,CAAC;AAEX,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;qCAkBM,KAAK,KAAK,KAAK,KAAK,KAAK;;;;;;;;;;CAU7D,CAAC"}

package/dist/vfx/noise.frag.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `noise` kernel — GLSL ES 3.00, capture `self`.
+ *
+ * A port of After Effects' `ADBE Noise`, decoded from `AEFX_Noise.metallib`
+ * (`docs/superpowers/specs/ae-metal-ir/AEFX_Noise.metallib.ll` in the exporter
+ * repo, helper `_Z5Noise8PixelRGBiifiiff`). The kernel is a pure integer hash of
+ * `(x, y, seed)` — no lookup table, no state between frames — so it ports
+ * exactly and stays seek-safe by construction.
+ *
+ * **What the IR says, read from the struct metadata rather than from prose.**
+ * `NoiseKernelValues` is `{ inDeviceFormat, inNoiseAmount, inUseColorNoise,
+ * inClipNoiseOutput, inRandomSeed_High, inRandomSeed_Low, inNoiseOffsetX,
+ * inNoiseOffsetY, … }`. So `ADBE Noise-0002` is **Use Color Noise**, a
+ * checkbox — not the "Noise Type (Uniform / Gaussian)" popup the deep dive
+ * guessed — and the two mystery seed floats are the halves of one 32-bit
+ * random seed. Both params are named here the way the metadata names them.
+ *
+ * Per channel:
+ *
+ *     seed32 = (uint(seedHigh) << 16) | (uint(seedLow) & 0xFFFF)
+ *     h      = jenkinsMix(a, y, seed32)          // Bob Jenkins' 1997 mix, verbatim
+ *     t2     = h  * 1103515245 + 12345
+ *     t4     = t2 * 12996205   + 12345
+ *     byte   = ((t4 >> 16) & 0xFF) ^ ((t2 >> 9) & 0x7F80)
+ *     noise  = amount · (byte / 32704 − 0.5)
+ *
+ * with `a = x` for monochrome noise and `a = 3x + channel` (R, G, B) for colour
+ * noise — four separate hash blocks in the IR, three of them consecutive in
+ * `3x`. `32704` is the reciprocal constant `0x3F00002000000000` spelled as a
+ * fraction. The noise is ADDED to the buffer's colour and, when Clip Result
+ * Values is on, all four channels are clamped to [0, 1] — alpha is clamped but
+ * never noised.
+ *
+ * **Interim seed (plan Task 2.7, pending the Task 4.3 probe).** What the CPU
+ * puts in `inRandomSeed_High`/`inRandomSeed_Low` per frame is still unknown —
+ * it is the effect's Random Seed combined with something frame-derived, which
+ * is why the noise animates with no keyframed property. Until the probe pins
+ * it, this kernel seeds the low half with the frame index and leaves the high
+ * half at zero, so the pattern is deterministic per frame and different between
+ * frames. Switching to the decoded packing is a change to two lines here and
+ * two in the reference; nothing else depends on it, and the tests assert the
+ * byte distribution and determinism rather than After Effects parity.
+ *
+ * **Pixel space.** `x` and `y` are integer pixel coordinates with y measured
+ * from the TOP, which is how After Effects indexes the buffer — the shader's
+ * `v_uv` is y-up, so the row is flipped back here. `inNoiseOffsetX/Y` (the
+ * layer's origin inside the source buffer) are not modelled: a HyperFrames host
+ * always captures its own box, so its origin is (0, 0).
+ *
+ * **Premultiplication.** The noise is added to the captured texel as it is,
+ * which is premultiplied — the literal port, and After Effects' own buffers are
+ * premultiplied too. The consequence is worth stating: on a layer with
+ * transparency the noise lands in the transparent region as well, exactly as
+ * the effect does in After Effects.
+ *
+ * **`rgb ≤ a` is enforced regardless of `Clip Result Values`, and that is a
+ * deliberate DEPARTURE from AE, not a port of it.** A valid premultiplied
+ * colour always has `rgb ≤ a` component-wise (it is `straightRgb · a`); adding
+ * noise to `src.rgb` can push it above `src.a` on a near-transparent texel,
+ * and `clamp(out4, 0, 1)` alone does not fix that — it clamps each channel to
+ * [0, 1] independently, never rgb to a. After Effects can carry that
+ * transient state through its float pipeline because everything downstream of
+ * it is float too; every render target this runtime writes is 8-bit RGBA
+ * (`GL_ATTRS`, `makePingTarget`), and an invalid premultiplied texel read back
+ * later (e.g. straight-alpha `rgb / a` for display) reads as a blown-out
+ * bright fringe rather than the visible defect After Effects itself never
+ * produces. So the clamp to `a` runs unconditionally, on both the `Clip
+ * Result Values` on and off paths.
+ *
+ * **`Clip Result Values` off is otherwise inert here, and that is a real,
+ * currently permanent limitation, not a bug to fix in this file.** Every
+ * render target in this runtime — the visible `.hf-vfx-out` canvas AND the
+ * ping-pong intermediates a multi-node chain reads between passes — is 8-bit
+ * `UNSIGNED_BYTE` RGBA, and the GL spec clamps a float fragment output to
+ * [0, 1] on conversion to a normalized integer target regardless of what the
+ * shader computes. `u_clipping = 0` therefore cannot produce an unclamped
+ * value anywhere in this pipeline today; it would take a floating-point
+ * render target (a real infrastructure change, not a one-line fix) to give it
+ * one. Recorded rather than silently accepted: a reviewer who mutates this
+ * shader and finds `u_clipping` untestable is finding a known limitation, not
+ * a fresh bug.
+ */
+/**
+ * The constants the reference has to agree with, named once. `byteScale` is
+ * `0x3F00002000000000` from the IR — (1 + 2⁻⁹) · 2⁻¹⁵, i.e. 1/32704.
+ */
+export declare const NOISE_CONSTANTS: {
+    readonly lcgMulA: 1103515245;
+    readonly lcgMulB: 12996205;
+    readonly lcgAdd: 12345;
+    readonly highMask: 32640;
+    readonly lowMask: 255;
+    readonly byteScale: 32704;
+};
+export declare const NOISE_FRAG: string;
+//# sourceMappingURL=noise.frag.d.ts.map

package/dist/vfx/noise.frag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noise.frag.d.ts","sourceRoot":"","sources":["../../src/vfx/noise.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAIX,eAAO,MAAM,UAAU,QAwEtB,CAAC"}

package/dist/vfx/noise.frag.js

@@ -0,0 +1,169 @@
+/**
+ * `noise` kernel — GLSL ES 3.00, capture `self`.
+ *
+ * A port of After Effects' `ADBE Noise`, decoded from `AEFX_Noise.metallib`
+ * (`docs/superpowers/specs/ae-metal-ir/AEFX_Noise.metallib.ll` in the exporter
+ * repo, helper `_Z5Noise8PixelRGBiifiiff`). The kernel is a pure integer hash of
+ * `(x, y, seed)` — no lookup table, no state between frames — so it ports
+ * exactly and stays seek-safe by construction.
+ *
+ * **What the IR says, read from the struct metadata rather than from prose.**
+ * `NoiseKernelValues` is `{ inDeviceFormat, inNoiseAmount, inUseColorNoise,
+ * inClipNoiseOutput, inRandomSeed_High, inRandomSeed_Low, inNoiseOffsetX,
+ * inNoiseOffsetY, … }`. So `ADBE Noise-0002` is **Use Color Noise**, a
+ * checkbox — not the "Noise Type (Uniform / Gaussian)" popup the deep dive
+ * guessed — and the two mystery seed floats are the halves of one 32-bit
+ * random seed. Both params are named here the way the metadata names them.
+ *
+ * Per channel:
+ *
+ *     seed32 = (uint(seedHigh) << 16) | (uint(seedLow) & 0xFFFF)
+ *     h      = jenkinsMix(a, y, seed32)          // Bob Jenkins' 1997 mix, verbatim
+ *     t2     = h  * 1103515245 + 12345
+ *     t4     = t2 * 12996205   + 12345
+ *     byte   = ((t4 >> 16) & 0xFF) ^ ((t2 >> 9) & 0x7F80)
+ *     noise  = amount · (byte / 32704 − 0.5)
+ *
+ * with `a = x` for monochrome noise and `a = 3x + channel` (R, G, B) for colour
+ * noise — four separate hash blocks in the IR, three of them consecutive in
+ * `3x`. `32704` is the reciprocal constant `0x3F00002000000000` spelled as a
+ * fraction. The noise is ADDED to the buffer's colour and, when Clip Result
+ * Values is on, all four channels are clamped to [0, 1] — alpha is clamped but
+ * never noised.
+ *
+ * **Interim seed (plan Task 2.7, pending the Task 4.3 probe).** What the CPU
+ * puts in `inRandomSeed_High`/`inRandomSeed_Low` per frame is still unknown —
+ * it is the effect's Random Seed combined with something frame-derived, which
+ * is why the noise animates with no keyframed property. Until the probe pins
+ * it, this kernel seeds the low half with the frame index and leaves the high
+ * half at zero, so the pattern is deterministic per frame and different between
+ * frames. Switching to the decoded packing is a change to two lines here and
+ * two in the reference; nothing else depends on it, and the tests assert the
+ * byte distribution and determinism rather than After Effects parity.
+ *
+ * **Pixel space.** `x` and `y` are integer pixel coordinates with y measured
+ * from the TOP, which is how After Effects indexes the buffer — the shader's
+ * `v_uv` is y-up, so the row is flipped back here. `inNoiseOffsetX/Y` (the
+ * layer's origin inside the source buffer) are not modelled: a HyperFrames host
+ * always captures its own box, so its origin is (0, 0).
+ *
+ * **Premultiplication.** The noise is added to the captured texel as it is,
+ * which is premultiplied — the literal port, and After Effects' own buffers are
+ * premultiplied too. The consequence is worth stating: on a layer with
+ * transparency the noise lands in the transparent region as well, exactly as
+ * the effect does in After Effects.
+ *
+ * **`rgb ≤ a` is enforced regardless of `Clip Result Values`, and that is a
+ * deliberate DEPARTURE from AE, not a port of it.** A valid premultiplied
+ * colour always has `rgb ≤ a` component-wise (it is `straightRgb · a`); adding
+ * noise to `src.rgb` can push it above `src.a` on a near-transparent texel,
+ * and `clamp(out4, 0, 1)` alone does not fix that — it clamps each channel to
+ * [0, 1] independently, never rgb to a. After Effects can carry that
+ * transient state through its float pipeline because everything downstream of
+ * it is float too; every render target this runtime writes is 8-bit RGBA
+ * (`GL_ATTRS`, `makePingTarget`), and an invalid premultiplied texel read back
+ * later (e.g. straight-alpha `rgb / a` for display) reads as a blown-out
+ * bright fringe rather than the visible defect After Effects itself never
+ * produces. So the clamp to `a` runs unconditionally, on both the `Clip
+ * Result Values` on and off paths.
+ *
+ * **`Clip Result Values` off is otherwise inert here, and that is a real,
+ * currently permanent limitation, not a bug to fix in this file.** Every
+ * render target in this runtime — the visible `.hf-vfx-out` canvas AND the
+ * ping-pong intermediates a multi-node chain reads between passes — is 8-bit
+ * `UNSIGNED_BYTE` RGBA, and the GL spec clamps a float fragment output to
+ * [0, 1] on conversion to a normalized integer target regardless of what the
+ * shader computes. `u_clipping = 0` therefore cannot produce an unclamped
+ * value anywhere in this pipeline today; it would take a floating-point
+ * render target (a real infrastructure change, not a one-line fix) to give it
+ * one. Recorded rather than silently accepted: a reviewer who mutates this
+ * shader and finds `u_clipping` untestable is finding a known limitation, not
+ * a fresh bug.
+ */
+/**
+ * The constants the reference has to agree with, named once. `byteScale` is
+ * `0x3F00002000000000` from the IR — (1 + 2⁻⁹) · 2⁻¹⁵, i.e. 1/32704.
+ */
+export const NOISE_CONSTANTS = {
+    lcgMulA: 1103515245,
+    lcgMulB: 12996205,
+    lcgAdd: 12345,
+    highMask: 0x7f80,
+    lowMask: 0xff,
+    byteScale: 32704,
+};
+const { lcgMulA, lcgMulB, lcgAdd, highMask, lowMask, byteScale } = NOISE_CONSTANTS;
+export const NOISE_FRAG = `#version 300 es
+precision highp float;
+// NOT decoration: a fragment shader's default integer precision is mediump,
+// and a mediump uint is only guaranteed 16 bits (ESSL 3.00 §4.5.2). Every step
+// below — the Jenkins mix, both LCG rounds — is defined by 32-bit wraparound,
+// so without this the hash is a different function on any implementation that
+// honours the minimum. ANGLE and SwiftShader both use 32-bit ints, which is
+// exactly why no test on this machine would catch it.
+precision highp int;
+
+in vec2 v_uv;
+out vec4 fragColor;
+
+uniform vec2 u_size;
+uniform float u_t;
+uniform float u_fps;
+uniform sampler2D u_src;
+uniform float u_amount;
+uniform float u_useColorNoise;
+uniform float u_clipping;
+
+// Bob Jenkins' 1997 integer mix, the six-round shift/xor/subtract sequence the
+// metallib runs verbatim. uint arithmetic wraps in GLSL ES 3.00, which is what
+// makes this bit-identical to the C original.
+uint hfJenkinsMix(uint a, uint b, uint c) {
+  a -= b; a -= c; a ^= (c >> 13u);
+  b -= c; b -= a; b ^= (a << 8u);
+  c -= a; c -= b; c ^= (b >> 13u);
+  a -= b; a -= c; a ^= (c >> 12u);
+  b -= c; b -= a; b ^= (a << 16u);
+  c -= a; c -= b; c ^= (b >> 5u);
+  a -= b; a -= c; a ^= (c >> 3u);
+  b -= c; b -= a; b ^= (a << 10u);
+  c -= a; c -= b; c ^= (b >> 15u);
+  return c;
+}
+
+// The hash's 15-bit output byte for one channel.
+float hfNoiseByte(uint a, uint y, uint seed) {
+  uint h = hfJenkinsMix(a, y, seed);
+  uint t2 = h * ${lcgMulA}u + ${lcgAdd}u;
+  uint t4 = t2 * ${lcgMulB}u + ${lcgAdd}u;
+  return float(((t4 >> 16u) & ${lowMask}u) ^ ((t2 >> 9u) & ${highMask}u));
+}
+
+void main() {
+  vec4 src = texture(u_src, v_uv);
+  vec2 px = floor(v_uv * u_size);
+  uint x = uint(max(px.x, 0.0));
+  // After Effects indexes rows from the top; v_uv is y-up.
+  uint y = uint(max(u_size.y - 1.0 - px.y, 0.0));
+  float frame = floor(u_t * u_fps + 0.5);
+  uint seed = uint(max(frame, 0.0)) & 0xFFFFu;
+
+  float amount = u_amount * 0.01;
+  vec3 nz;
+  if (u_useColorNoise > 0.5) {
+    uint a = x * 3u;
+    nz = vec3(hfNoiseByte(a, y, seed), hfNoiseByte(a + 1u, y, seed), hfNoiseByte(a + 2u, y, seed));
+  } else {
+    nz = vec3(hfNoiseByte(x, y, seed));
+  }
+  nz = amount * (nz / ${byteScale}.0 - 0.5);
+
+  vec4 out4 = vec4(src.rgb + nz, src.a);
+  // A valid premultiplied colour needs rgb <= a component-wise; noise on a
+  // near-transparent texel can push rgb above it, which our fixed 8-bit RGBA
+  // storage cannot carry safely the way AE's float pipeline can (see the doc
+  // comment above). This runs before, and independently of, u_clipping.
+  out4.rgb = min(out4.rgb, out4.a);
+  fragColor = u_clipping > 0.5 ? clamp(out4, 0.0, 1.0) : out4;
+}
+`;
+//# sourceMappingURL=noise.frag.js.map

package/dist/vfx/noise.frag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noise.frag.js","sourceRoot":"","sources":["../../src/vfx/noise.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,UAAU;IACnB,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,KAAK;IACb,QAAQ,EAAE,MAAM;IAChB,OAAO,EAAE,IAAI;IACb,SAAS,EAAE,KAAK;CACR,CAAC;AAEX,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,eAAe,CAAC;AAEnF,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAwCR,OAAO,OAAO,MAAM;mBACnB,OAAO,OAAO,MAAM;gCACP,OAAO,sBAAsB,QAAQ;;;;;;;;;;;;;;;;;;;;wBAoB7C,SAAS;;;;;;;;;;CAUhC,CAAC"}

package/dist/vfx/refs/lumaMatte.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CPU reference for the `luma-matte` kernel. Unlike `wave-warp`'s and
+ * `displacement-map`'s, which return the coordinate they sample, this one
+ * returns the colour: the kernel's whole decision is a per-pixel scale, and a
+ * caller with both texels can check it exactly.
+ *
+ * Both texels are **premultiplied**, matching the textures the runtime uploads.
+ */
+import { type HfVfxParamValues } from "../../vfx";
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** The shader's `hfCoverage`. */
+export declare function lumaMatteCoverageRef(matte: Rgba, mode: number): number;
+/**
+ * The colour the kernel paints. `t` is part of the call shape every kernel
+ * reference shares; a matte is time-invariant — its animation arrives as
+ * movement in the matte element itself.
+ */
+export declare function lumaMatteSampleRef(src: Rgba, matte: Rgba, t: number, params: HfVfxParamValues): Rgba;
+//# sourceMappingURL=lumaMatte.d.ts.map

package/dist/vfx/refs/lumaMatte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lumaMatte.d.ts","sourceRoot":"","sources":["../../../src/vfx/refs/lumaMatte.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAMtE,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,iCAAiC;AACjC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,IAAI,EACX,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,gBAAgB,GACvB,IAAI,CAKN"}

package/dist/vfx/refs/lumaMatte.js

@@ -0,0 +1,33 @@
+/**
+ * CPU reference for the `luma-matte` kernel. Unlike `wave-warp`'s and
+ * `displacement-map`'s, which return the coordinate they sample, this one
+ * returns the colour: the kernel's whole decision is a per-pixel scale, and a
+ * caller with both texels can check it exactly.
+ *
+ * Both texels are **premultiplied**, matching the textures the runtime uploads.
+ */
+import { normalizeVfxParams } from "../../vfx.js";
+import { DISPLACEMENT_MAP_CONSTANTS } from "../displacementMap.frag.js";
+import { LUMA_MATTE_MODES } from "../lumaMatte.frag.js";
+const { lumaR, lumaG, lumaB } = DISPLACEMENT_MAP_CONSTANTS;
+/** The shader's `hfCoverage`. */
+export function lumaMatteCoverageRef(matte, mode) {
+    if (mode < LUMA_MATTE_MODES.alphaInverted)
+        return matte.a;
+    if (mode < LUMA_MATTE_MODES.luma)
+        return 1 - matte.a;
+    const luma = matte.r * lumaR + matte.g * lumaG + matte.b * lumaB;
+    return mode < LUMA_MATTE_MODES.lumaInverted ? luma : 1 - luma;
+}
+/**
+ * The colour the kernel paints. `t` is part of the call shape every kernel
+ * reference shares; a matte is time-invariant — its animation arrives as
+ * movement in the matte element itself.
+ */
+export function lumaMatteSampleRef(src, matte, t, params) {
+    void t;
+    const n = normalizeVfxParams("luma-matte", params);
+    const coverage = Math.min(1, Math.max(0, lumaMatteCoverageRef(matte, Number(n["mode"]))));
+    return { r: src.r * coverage, g: src.g * coverage, b: src.b * coverage, a: src.a * coverage };
+}
+//# sourceMappingURL=lumaMatte.js.map

package/dist/vfx/refs/lumaMatte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lumaMatte.js","sourceRoot":"","sources":["../../../src/vfx/refs/lumaMatte.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAyB,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,0BAA0B,CAAC;AAS3D,iCAAiC;AACjC,MAAM,UAAU,oBAAoB,CAAC,KAAW,EAAE,IAAY;IAC5D,IAAI,IAAI,GAAG,gBAAgB,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC;IAC1D,IAAI,IAAI,GAAG,gBAAgB,CAAC,IAAI;QAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC;IACjE,OAAO,IAAI,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAS,EACT,KAAW,EACX,CAAS,EACT,MAAwB;IAExB,KAAK,CAAC,CAAC;IACP,MAAM,CAAC,GAAG,kBAAkB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1F,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC;AAChG,CAAC"}

package/dist/vfx/refs/noise.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CPU reference for the `noise` kernel — the same integer hash the shader
+ * runs, in 32-bit wrapping arithmetic. JavaScript's `>>> 0` and `Math.imul`
+ * reproduce C's `unsigned int` overflow exactly, which is the property the
+ * whole port rests on.
+ *
+ * Returns the noise OFFSET applied to a pixel, not the colour: the offset is
+ * the entirety of what the kernel computes, and the add-and-clip around it is
+ * two lines a caller can apply itself.
+ */
+import { type HfVfxParamValues } from "../../vfx";
+/** The hash's 15-bit output byte for one channel index `a`. */
+export declare function noiseByteRef(a: number, y: number, seed: number): number;
+/**
+ * The 32-bit seed the kernel hashes with. Interim, pending the Task 4.3 probe:
+ * the frame index goes in the low half and the high half is zero. The packing
+ * itself is the metallib's (`inRandomSeed_High` << 16 | `inRandomSeed_Low`), so
+ * the probe's answer replaces the arguments, not the shape.
+ */
+export declare function noiseSeedRef(t: number, fps: number): number;
+/**
+ * The per-channel noise offset the kernel adds at pixel `(x, y)` — `y` counted
+ * from the TOP of the layer, as After Effects indexes its buffer.
+ */
+export declare function noiseOffsetRef(p: {
+    x: number;
+    y: number;
+}, t: number, fps: number, params: HfVfxParamValues): {
+    r: number;
+    g: number;
+    b: number;
+};
+//# sourceMappingURL=noise.d.ts.map

package/dist/vfx/refs/noise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noise.d.ts","sourceRoot":"","sources":["../../../src/vfx/refs/noise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAsBtE,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3B,CAAC,EAAE,MAAM,EACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,gBAAgB,GACvB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAerC"}