@flighthq/effects 0.1.0 → 0.2.1-next.410.a23f189

package/dist/renderEffectInputs.js.map

@@ -1 +1 @@
-{"version":3,"file":"renderEffectInputs.js","sourceRoot":"","sources":["../src/renderEffectInputs.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,wFAAwF;AACxF,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CAAC,MAA8B;IAClE,OAAO,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,4FAA4F;AAC5F,6FAA6F;AAC7F,MAAM,UAAU,oBAAoB;IAClC,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,+FAA+F;AAC/F,+FAA+F;AAC/F,mGAAmG;AACnG,mFAAmF;AACnF,MAAM,oBAAoB,GAA2D;IACnF,kBAAkB,EAAE,CAAC,KAAK,CAAC;IAC3B,WAAW,EAAE,CAAC,KAAK,CAAC;IACpB,uBAAuB,EAAE,CAAC,OAAO,CAAC;IAClC,sBAAsB,EAAE,CAAC,QAAQ,CAAC;IAClC,oBAAoB,EAAE,CAAC,OAAO,CAAC;IAC/B,gBAAgB,EAAE,CAAC,QAAQ,CAAC;IAC5B,oBAAoB,EAAE,CAAC,OAAO,CAAC;IAC/B,UAAU,EAAE,CAAC,OAAO,CAAC;IACrB,SAAS,EAAE,CAAC,OAAO,CAAC;IACpB,SAAS,EAAE,CAAC,UAAU,CAAC;IACvB,eAAe,EAAE,CAAC,OAAO,CAAC;IAC1B,aAAa,EAAE,CAAC,KAAK,CAAC;IACtB,qBAAqB,EAAE,CAAC,OAAO,CAAC;CACjC,CAAC;AAEF,8FAA8F;AAC9F,iFAAiF;AACjF,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,oBAAoB;IACpB,wBAAwB;IACxB,aAAa;IACb,yBAAyB;IACzB,0BAA0B;IAC1B,wBAAwB;IACxB,oBAAoB;IACpB,2BAA2B;IAC3B,4BAA4B;IAC5B,kBAAkB;IAClB,sBAAsB;IACtB,WAAW;IACX,oBAAoB;IACpB,uBAAuB;IACvB,oBAAoB;IACpB,cAAc;IACd,gBAAgB;IAChB,qBAAqB;IACrB,iBAAiB;IACjB,YAAY;IACZ,cAAc;IACd,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,qBAAqB;IACrB,cAAc;IACd,gBAAgB;IAChB,gBAAgB;IAChB,sBAAsB;IACtB,iBAAiB;IACjB,qBAAqB;IACrB,wBAAwB;IACxB,kBAAkB;IAClB,eAAe;IACf,yBAAyB;IACzB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,iBAAiB;IACjB,sBAAsB;IACtB,aAAa;IACb,eAAe;IACf,cAAc;IACd,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,WAAW;IACX,iBAAiB;IACjB,eAAe;IACf,gBAAgB;IAChB,uBAAuB;IACvB,oBAAoB;CACrB,CAAC"}
+{"version":3,"file":"renderEffectInputs.js","sourceRoot":"","sources":["../src/renderEffectInputs.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,wFAAwF;AACxF,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CAAC,MAA8B;IAClE,OAAO,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,4FAA4F;AAC5F,6FAA6F;AAC7F,MAAM,UAAU,oBAAoB;IAClC,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,+FAA+F;AAC/F,+FAA+F;AAC/F,mGAAmG;AACnG,mFAAmF;AACnF,MAAM,oBAAoB,GAA2D;IACnF,kBAAkB,EAAE,CAAC,KAAK,CAAC;IAC3B,WAAW,EAAE,CAAC,KAAK,CAAC;IACpB,uBAAuB,EAAE,CAAC,OAAO,CAAC;IAClC,sBAAsB,EAAE,CAAC,QAAQ,CAAC;IAClC,oBAAoB,EAAE,CAAC,OAAO,CAAC;IAC/B,gBAAgB,EAAE,CAAC,QAAQ,CAAC;IAC5B,oBAAoB,EAAE,CAAC,OAAO,CAAC;IAC/B,UAAU,EAAE,CAAC,OAAO,CAAC;IACrB,SAAS,EAAE,CAAC,OAAO,CAAC;IACpB,SAAS,EAAE,CAAC,UAAU,CAAC;IACvB,eAAe,EAAE,CAAC,OAAO,CAAC;IAC1B,aAAa,EAAE,CAAC,KAAK,CAAC;IACtB,qBAAqB,EAAE,CAAC,OAAO,CAAC;CACjC,CAAC;AAEF,8FAA8F;AAC9F,iFAAiF;AACjF,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,oBAAoB;IACpB,wBAAwB;IACxB,aAAa;IACb,aAAa;IACb,aAAa;IACb,YAAY;IACZ,yBAAyB;IACzB,wBAAwB;IACxB,2BAA2B;IAC3B,sBAAsB;IACtB,mBAAmB;IACnB,WAAW;IACX,oBAAoB;IACpB,uBAAuB;IACvB,oBAAoB;IACpB,cAAc;IACd,kBAAkB;IAClB,qBAAqB;IACrB,iBAAiB;IACjB,YAAY;IACZ,cAAc;IACd,eAAe;IACf,qBAAqB;IACrB,oBAAoB;IACpB,gBAAgB;IAChB,iBAAiB;IACjB,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;IAChB,sBAAsB;IACtB,iBAAiB;IACjB,cAAc;IACd,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,yBAAyB;IACzB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,iBAAiB;IACjB,sBAAsB;IACtB,eAAe;IACf,cAAc;IACd,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,WAAW;IACX,iBAAiB;IACjB,eAAe;IACf,gBAAgB;IAChB,uBAAuB;IACvB,oBAAoB;CACrB,CAAC"}

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@flighthq/effects",
-  "version": "0.1.0",
+  "version": "0.2.1-next.410.a23f189",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/effects"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,7 +32,7 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.1.0"
+    "@flighthq/types": "0.2.1-next.410.a23f189"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/bevelEffect.test.ts

@@ -0,0 +1,14 @@
+import { createBevelEffect } from './bevelEffect';
+
+describe('createBevelEffect', () => {
+  it('tags the intent type', () => {
+    expect(createBevelEffect().kind).toBe('BevelEffect');
+  });
+
+  it('carries options', () => {
+    expect(createBevelEffect({ sourceMode: 'knockout', strength: 2 })).toMatchObject({
+      sourceMode: 'knockout',
+      strength: 2,
+    });
+  });
+});

package/src/blendEffect.test.ts

@@ -0,0 +1,23 @@
+import { AdvancedBlendMode } from '@flighthq/types';
+
+import { createBlendEffect } from './blendEffect';
+
+describe('createBlendEffect', () => {
+  it('builds a BlendEffect carrying the requested mode', () => {
+    const effect = createBlendEffect(AdvancedBlendMode.Overlay);
+    expect(effect.kind).toBe('BlendEffect');
+    expect(effect.mode).toBe('Overlay');
+  });
+
+  it('spreads backdropKey and opacity options', () => {
+    const effect = createBlendEffect(AdvancedBlendMode.SoftLight, { backdropKey: 'scene.backdrop', opacity: 0.5 });
+    expect(effect.backdropKey).toBe('scene.backdrop');
+    expect(effect.opacity).toBe(0.5);
+  });
+
+  it('leaves backdropKey and opacity undefined when omitted', () => {
+    const effect = createBlendEffect(AdvancedBlendMode.Hue);
+    expect(effect.backdropKey).toBeUndefined();
+    expect(effect.opacity).toBeUndefined();
+  });
+});

package/src/blendModeMath.test.ts

@@ -0,0 +1,160 @@
+import { AdvancedBlendMode } from '@flighthq/types';
+
+import {
+  blendNonSeparableRgb,
+  getAdvancedBlendRgb,
+  getSeparableBlendChannel,
+  isNonSeparableBlendMode,
+} from './blendModeMath';
+
+const LUM = (r: number, g: number, b: number): number => 0.3 * r + 0.59 * g + 0.11 * b;
+const SAT = (r: number, g: number, b: number): number => Math.max(r, g, b) - Math.min(r, g, b);
+
+describe('blendNonSeparableRgb', () => {
+  it('Luminosity replaces backdrop luma with source luma, preserving backdrop hue/sat', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    const cb: [number, number, number] = [0.8, 0.2, 0.4];
+    const cs: [number, number, number] = [0.5, 0.5, 0.5];
+    blendNonSeparableRgb(AdvancedBlendMode.Luminosity, cb[0], cb[1], cb[2], cs[0], cs[1], cs[2], out);
+    // Result luma equals the source's luma.
+    expect(LUM(out[0], out[1], out[2])).toBeCloseTo(LUM(cs[0], cs[1], cs[2]), 5);
+    // Backdrop saturation is preserved (chroma range unchanged) since no channel clipped.
+    expect(SAT(out[0], out[1], out[2])).toBeCloseTo(SAT(cb[0], cb[1], cb[2]), 5);
+  });
+
+  it('Color takes source hue+sat with backdrop luma', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    const cb: [number, number, number] = [0.2, 0.2, 0.2]; // gray backdrop, luma 0.2
+    const cs: [number, number, number] = [0.9, 0.1, 0.1];
+    blendNonSeparableRgb(AdvancedBlendMode.Color, cb[0], cb[1], cb[2], cs[0], cs[1], cs[2], out);
+    expect(LUM(out[0], out[1], out[2])).toBeCloseTo(LUM(cb[0], cb[1], cb[2]), 5);
+  });
+
+  it('Hue takes source hue, backdrop sat and luma', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    const cb: [number, number, number] = [0.4, 0.5, 0.6];
+    const cs: [number, number, number] = [0.9, 0.2, 0.2];
+    blendNonSeparableRgb(AdvancedBlendMode.Hue, cb[0], cb[1], cb[2], cs[0], cs[1], cs[2], out);
+    expect(LUM(out[0], out[1], out[2])).toBeCloseTo(LUM(cb[0], cb[1], cb[2]), 5);
+    expect(SAT(out[0], out[1], out[2])).toBeCloseTo(SAT(cb[0], cb[1], cb[2]), 5);
+  });
+
+  it('Saturation takes source sat, backdrop hue and luma', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    const cb: [number, number, number] = [0.4, 0.5, 0.6];
+    const cs: [number, number, number] = [0.9, 0.2, 0.2]; // sat 0.7
+    blendNonSeparableRgb(AdvancedBlendMode.Saturation, cb[0], cb[1], cb[2], cs[0], cs[1], cs[2], out);
+    expect(SAT(out[0], out[1], out[2])).toBeCloseTo(SAT(cs[0], cs[1], cs[2]), 5);
+    expect(LUM(out[0], out[1], out[2])).toBeCloseTo(LUM(cb[0], cb[1], cb[2]), 5);
+  });
+
+  it('keeps every channel in 0..1 after gamut clipping', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    blendNonSeparableRgb(AdvancedBlendMode.Color, 0.95, 0.95, 0.95, 1, 0, 0, out);
+    for (const c of out) {
+      expect(c).toBeGreaterThanOrEqual(0);
+      expect(c).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('falls through to the source triple for an unknown mode', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    blendNonSeparableRgb('acme.Nope', 0.1, 0.2, 0.3, 0.7, 0.8, 0.9, out);
+    expect(out).toEqual([0.7, 0.8, 0.9]);
+  });
+});
+
+describe('getAdvancedBlendRgb', () => {
+  it('falls through to the source triple for a non-advanced mode', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    // A fixed-function mode name is not an AdvancedBlendMode, so it takes the separable Normal path.
+    getAdvancedBlendRgb('Multiply', 0.5, 0.5, 0.5, 0.2, 0.3, 0.4, out);
+    expect(out).toEqual([0.2, 0.3, 0.4]);
+  });
+
+  it('computes Difference per channel', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    getAdvancedBlendRgb(AdvancedBlendMode.Difference, 0.8, 0.5, 0.2, 0.3, 0.5, 0.9, out);
+    expect(out[0]).toBeCloseTo(0.5, 5);
+    expect(out[1]).toBeCloseTo(0, 5);
+    expect(out[2]).toBeCloseTo(0.7, 5);
+  });
+
+  it('routes HSL modes through the non-separable path', () => {
+    const out: [number, number, number] = [0, 0, 0];
+    getAdvancedBlendRgb(AdvancedBlendMode.Luminosity, 0.8, 0.2, 0.4, 0.5, 0.5, 0.5, out);
+    expect(LUM(out[0], out[1], out[2])).toBeCloseTo(0.5, 5);
+  });
+});
+
+describe('getSeparableBlendChannel', () => {
+  it('Overlay equals HardLight with operands swapped', () => {
+    const cb = 0.6;
+    const cs = 0.3;
+    expect(getSeparableBlendChannel(AdvancedBlendMode.Overlay, cb, cs)).toBeCloseTo(
+      getSeparableBlendChannel(AdvancedBlendMode.HardLight, cs, cb),
+      6,
+    );
+  });
+
+  it('Difference is the absolute channel distance', () => {
+    expect(getSeparableBlendChannel(AdvancedBlendMode.Difference, 0.8, 0.3)).toBeCloseTo(0.5, 6);
+  });
+
+  it('Exclusion(x, 0.5) collapses to 0.5 regardless of backdrop', () => {
+    expect(getSeparableBlendChannel(AdvancedBlendMode.Exclusion, 0.2, 0.5)).toBeCloseTo(0.5, 6);
+    expect(getSeparableBlendChannel(AdvancedBlendMode.Exclusion, 0.9, 0.5)).toBeCloseTo(0.5, 6);
+  });
+
+  it('ColorDodge clamps to white when source is 1 and stays 0 for a black backdrop', () => {
+    expect(getSeparableBlendChannel(AdvancedBlendMode.ColorDodge, 0.4, 1)).toBe(1);
+    expect(getSeparableBlendChannel(AdvancedBlendMode.ColorDodge, 0, 0.5)).toBe(0);
+    expect(getSeparableBlendChannel(AdvancedBlendMode.ColorDodge, 0.25, 0.5)).toBeCloseTo(0.5, 6);
+  });
+
+  it('ColorBurn clamps to black when source is 0 and stays 1 for a white backdrop', () => {
+    expect(getSeparableBlendChannel(AdvancedBlendMode.ColorBurn, 0.6, 0)).toBe(0);
+    expect(getSeparableBlendChannel(AdvancedBlendMode.ColorBurn, 1, 0.5)).toBe(1);
+    expect(getSeparableBlendChannel(AdvancedBlendMode.ColorBurn, 0.75, 0.5)).toBeCloseTo(0.5, 6);
+  });
+
+  it('SoftLight leaves the backdrop unchanged for a mid-gray source', () => {
+    expect(getSeparableBlendChannel(AdvancedBlendMode.SoftLight, 0.6, 0.5)).toBeCloseTo(0.6, 6);
+  });
+
+  it('HardLight over a 0.5 source is a straight overlay of the backdrop', () => {
+    // cs = 0.5 sits on the branch boundary; both branches agree there.
+    expect(getSeparableBlendChannel(AdvancedBlendMode.HardLight, 0.4, 0.5)).toBeCloseTo(0.4, 6);
+  });
+
+  it('returns the source channel (Normal) for an unknown mode', () => {
+    expect(getSeparableBlendChannel('acme.Nope', 0.2, 0.7)).toBe(0.7);
+  });
+});
+
+describe('isNonSeparableBlendMode', () => {
+  it('is true only for the four HSL modes', () => {
+    for (const mode of [
+      AdvancedBlendMode.Hue,
+      AdvancedBlendMode.Saturation,
+      AdvancedBlendMode.Color,
+      AdvancedBlendMode.Luminosity,
+    ]) {
+      expect(isNonSeparableBlendMode(mode)).toBe(true);
+    }
+  });
+
+  it('is false for the separable modes', () => {
+    for (const mode of [
+      AdvancedBlendMode.Overlay,
+      AdvancedBlendMode.HardLight,
+      AdvancedBlendMode.SoftLight,
+      AdvancedBlendMode.Difference,
+      AdvancedBlendMode.Exclusion,
+      AdvancedBlendMode.ColorDodge,
+      AdvancedBlendMode.ColorBurn,
+    ]) {
+      expect(isNonSeparableBlendMode(mode)).toBe(false);
+    }
+  });
+});

package/src/blurDownsample.test.ts

@@ -0,0 +1,46 @@
+import { getBlurDownsampleLevel, getBlurResidualSigma } from './blurDownsample';
+
+describe('getBlurDownsampleLevel', () => {
+  it('stays at full resolution at or below the max sigma threshold', () => {
+    expect(getBlurDownsampleLevel(1)).toBe(0);
+    expect(getBlurDownsampleLevel(2)).toBe(0);
+    expect(getBlurDownsampleLevel(4)).toBe(0);
+  });
+
+  it('adds one level per doubling of sigma past the threshold', () => {
+    expect(getBlurDownsampleLevel(8)).toBe(1);
+    expect(getBlurDownsampleLevel(16)).toBe(2);
+    expect(getBlurDownsampleLevel(32)).toBe(3);
+  });
+
+  it('rounds a partial doubling up to the next level', () => {
+    // sigma 5 → log2(5/4) ≈ 0.32 → ceil → level 1.
+    expect(getBlurDownsampleLevel(5)).toBe(1);
+  });
+
+  it('returns 0 for non-positive sigma', () => {
+    expect(getBlurDownsampleLevel(0)).toBe(0);
+    expect(getBlurDownsampleLevel(-4)).toBe(0);
+  });
+
+  it('never leaves a residual sigma above the threshold', () => {
+    for (const sigma of [4, 5, 8, 13, 16, 40, 100]) {
+      const level = getBlurDownsampleLevel(sigma);
+      expect(getBlurResidualSigma(sigma, level)).toBeLessThanOrEqual(4);
+    }
+  });
+});
+
+describe('getBlurResidualSigma', () => {
+  it('divides sigma by 2^level', () => {
+    expect(getBlurResidualSigma(8, 1)).toBe(4);
+    expect(getBlurResidualSigma(16, 2)).toBe(4);
+    expect(getBlurResidualSigma(4, 0)).toBe(4);
+    expect(getBlurResidualSigma(32, 3)).toBe(4);
+  });
+
+  it('returns 0 for non-positive sigma', () => {
+    expect(getBlurResidualSigma(0, 2)).toBe(0);
+    expect(getBlurResidualSigma(-8, 1)).toBe(0);
+  });
+});

package/src/blurEffect.test.ts

@@ -0,0 +1,17 @@
+import { createBlurEffect } from './blurEffect';
+
+describe('createBlurEffect', () => {
+  it('sets the kind', () => {
+    expect(createBlurEffect().kind).toBe('BlurEffect');
+  });
+
+  it('defaults to no options beyond kind', () => {
+    expect(createBlurEffect()).toEqual({ kind: 'BlurEffect' });
+  });
+
+  it('carries through blurX and blurY', () => {
+    const effect = createBlurEffect({ blurX: 6, blurY: 3 });
+    expect(effect.blurX).toBe(6);
+    expect(effect.blurY).toBe(3);
+  });
+});

package/src/boxBlurMath.test.ts

@@ -0,0 +1,96 @@
+import { computeBoxBlurPassRadius, computeBoxBlurRadius, computeGaussianSigmaForBlurRadius } from './boxBlurMath';
+
+describe('computeBoxBlurPassRadius', () => {
+  // Combined variance of n box passes of radius rᵢ is Σ (rᵢ² + rᵢ) / 3; the effective σ is its
+  // square root. These assert the construction tracks the target σ rather than overshooting.
+  const effectiveSigma = (radii: ReadonlyArray<number>): number =>
+    Math.sqrt(radii.reduce((sum, r) => sum + (r * r + r) / 3, 0));
+
+  const passRadii = (sigma: number, passes: number): number[] =>
+    Array.from({ length: passes }, (_unused, pass) => computeBoxBlurPassRadius(sigma, passes, pass));
+
+  it('returns 0 for every pass when sigma is 0', () => {
+    expect(passRadii(0, 3)).toEqual([0, 0, 0]);
+  });
+
+  it('returns 0 for every pass when sigma is negative', () => {
+    expect(passRadii(-1, 2)).toEqual([0, 0]);
+  });
+
+  it('uses at most two distinct box sizes', () => {
+    expect(new Set(passRadii(12, 3)).size).toBeLessThanOrEqual(2);
+  });
+
+  it('is non-decreasing in pass index', () => {
+    const radii = passRadii(4, 3);
+    for (let i = 1; i < radii.length; i++) {
+      expect(radii[i]).toBeGreaterThanOrEqual(radii[i - 1]);
+    }
+  });
+
+  it('approximates the target sigma within a few percent without overshooting', () => {
+    for (const sigma of [4, 8, 12]) {
+      const sigmaEff = effectiveSigma(passRadii(sigma, 3));
+      expect(sigmaEff).toBeGreaterThan(sigma * 0.9);
+      expect(sigmaEff).toBeLessThanOrEqual(sigma * 1.02);
+    }
+  });
+
+  it('does not overshoot the way a single repeated rounded radius does', () => {
+    // The uniform approach rounds 3.53 up to 4 → σ_eff ≈ 4.47 for σ=4, n=3.
+    const naiveRadius = computeBoxBlurRadius(4, 3);
+    const naiveSigma = effectiveSigma([naiveRadius, naiveRadius, naiveRadius]);
+    const splitSigma = effectiveSigma(passRadii(4, 3));
+    expect(naiveSigma).toBeGreaterThan(4); // documents the overshoot
+    expect(Math.abs(splitSigma - 4)).toBeLessThan(Math.abs(naiveSigma - 4));
+  });
+});
+
+describe('computeBoxBlurRadius', () => {
+  it('returns 0 for sigma 0', () => {
+    expect(computeBoxBlurRadius(0, 1)).toBe(0);
+  });
+
+  it('returns 0 for negative sigma', () => {
+    expect(computeBoxBlurRadius(-4, 1)).toBe(0);
+  });
+
+  it('returns a positive radius for positive sigma', () => {
+    expect(computeBoxBlurRadius(4, 1)).toBeGreaterThan(0);
+  });
+
+  it('returns a smaller radius for more passes at the same sigma', () => {
+    const r1 = computeBoxBlurRadius(10, 1);
+    const r3 = computeBoxBlurRadius(10, 3);
+    expect(r3).toBeLessThan(r1);
+  });
+
+  it('returns radius 6 for sigma 4 with 1 pass', () => {
+    // round((-1 + sqrt(1 + 12·16/1)) / 2) = round((-1 + sqrt(193)) / 2) ≈ round(6.44) = 6
+    expect(computeBoxBlurRadius(4, 1)).toBe(6);
+  });
+});
+
+describe('computeGaussianSigmaForBlurRadius', () => {
+  it('returns 0 for radius 0', () => {
+    expect(computeGaussianSigmaForBlurRadius(0, 1)).toBe(0);
+  });
+
+  it('returns 0 for negative radius', () => {
+    expect(computeGaussianSigmaForBlurRadius(-1, 1)).toBe(0);
+  });
+
+  it('returns 0 for non-positive passes', () => {
+    expect(computeGaussianSigmaForBlurRadius(4, 0)).toBe(0);
+  });
+
+  it('returns a positive sigma for positive radius and passes', () => {
+    expect(computeGaussianSigmaForBlurRadius(6, 1)).toBeGreaterThan(0);
+  });
+
+  it('produces a larger sigma for more passes at the same radius', () => {
+    const s1 = computeGaussianSigmaForBlurRadius(4, 1);
+    const s3 = computeGaussianSigmaForBlurRadius(4, 3);
+    expect(s3).toBeGreaterThan(s1);
+  });
+});

package/src/compositeEffect.test.ts

@@ -0,0 +1,21 @@
+import { CompositeOperator } from '@flighthq/types';
+
+import { createCompositeEffect } from './compositeEffect';
+
+describe('createCompositeEffect', () => {
+  it('builds a CompositeEffect carrying the requested operator', () => {
+    const effect = createCompositeEffect(CompositeOperator.DestinationOut);
+    expect(effect.kind).toBe('CompositeEffect');
+    expect(effect.operator).toBe('DestinationOut');
+  });
+
+  it('spreads the backdropKey option', () => {
+    const effect = createCompositeEffect(CompositeOperator.DestinationIn, { backdropKey: 'scene.backdrop' });
+    expect(effect.backdropKey).toBe('scene.backdrop');
+  });
+
+  it('leaves backdropKey undefined when omitted', () => {
+    const effect = createCompositeEffect(CompositeOperator.Xor);
+    expect(effect.backdropKey).toBeUndefined();
+  });
+});

package/src/compositeOperatorMath.test.ts

@@ -0,0 +1,45 @@
+import { CompositeOperator } from '@flighthq/types';
+
+import { getCompositeOperatorFactors } from './compositeOperatorMath';
+
+function factors(operator: CompositeOperator, as: number, ab: number): [number, number] {
+  const out: [number, number] = [0, 0];
+  getCompositeOperatorFactors(operator, as, ab, out);
+  return out;
+}
+
+describe('getCompositeOperatorFactors', () => {
+  it('gives source-over its canonical [1, 1 - as]', () => {
+    expect(factors(CompositeOperator.SourceOver, 0.6, 0.4)).toEqual([1, 1 - 0.6]);
+  });
+
+  it('erases (DestinationOut) by keeping only the backdrop scaled by 1 - as', () => {
+    expect(factors(CompositeOperator.DestinationOut, 0.75, 1)).toEqual([0, 1 - 0.75]);
+  });
+
+  it('masks (DestinationIn) by keeping only the backdrop scaled by as', () => {
+    expect(factors(CompositeOperator.DestinationIn, 0.75, 1)).toEqual([0, 0.75]);
+  });
+
+  it('copies the source and drops the backdrop', () => {
+    expect(factors(CompositeOperator.Copy, 0.3, 0.9)).toEqual([1, 0]);
+  });
+
+  it('clears both contributions', () => {
+    expect(factors(CompositeOperator.Clear, 0.3, 0.9)).toEqual([0, 0]);
+  });
+
+  it('xors to the mutually-uncovered regions', () => {
+    expect(factors(CompositeOperator.Xor, 0.5, 0.25)).toEqual([1 - 0.25, 1 - 0.5]);
+  });
+
+  it('falls through to source-over for an unknown (vendor) operator', () => {
+    expect(factors('acme.custom', 0.6, 0.4)).toEqual([1, 1 - 0.6]);
+  });
+
+  it('is alias-safe writing into a supplied out array', () => {
+    const out: [number, number] = [9, 9];
+    getCompositeOperatorFactors(CompositeOperator.DestinationOver, 0.2, 0.8, out);
+    expect(out).toEqual([1 - 0.8, 1]);
+  });
+});

package/src/convolutionEffect.test.ts

@@ -0,0 +1,20 @@
+import { createConvolutionEffect } from './convolutionEffect';
+
+describe('createConvolutionEffect', () => {
+  it('tags the intent type', () => {
+    expect(createConvolutionEffect({ matrix: [1], matrixX: 1, matrixY: 1 }).kind).toBe('ConvolutionEffect');
+  });
+
+  it('carries required fields', () => {
+    const matrix = [0, 1, 0, 1, -4, 1, 0, 1, 0];
+    const effect = createConvolutionEffect({ matrix, matrixX: 3, matrixY: 3 });
+    expect(effect.matrixX).toBe(3);
+    expect(effect.matrixY).toBe(3);
+    expect(effect.matrix).toBe(matrix);
+  });
+
+  it('carries optional fields', () => {
+    const effect = createConvolutionEffect({ matrix: [1], matrixX: 1, matrixY: 1, bias: 8, preserveAlpha: false });
+    expect(effect).toMatchObject({ bias: 8, preserveAlpha: false });
+  });
+});

package/src/dropShadowEffect.test.ts

@@ -0,0 +1,14 @@
+import { createDropShadowEffect } from './dropShadowEffect';
+
+describe('createDropShadowEffect', () => {
+  it('tags the intent type', () => {
+    expect(createDropShadowEffect().kind).toBe('DropShadowEffect');
+  });
+
+  it('carries options', () => {
+    expect(createDropShadowEffect({ sourceMode: 'knockout', strength: 2 })).toMatchObject({
+      sourceMode: 'knockout',
+      strength: 2,
+    });
+  });
+});

package/src/gaussianKernel.test.ts

@@ -0,0 +1,80 @@
+import { computeGaussianKernelWeights, getGaussianKernelSize } from './gaussianKernel';
+
+describe('computeGaussianKernelWeights', () => {
+  const sumOf = (weights: ReadonlyArray<number>): number => weights.reduce((total, weight) => total + weight, 0);
+
+  it('produces weights that sum to exactly 1 across several sigmas', () => {
+    for (const sigma of [0.75, 1, 2, 3.5, 6]) {
+      const out: number[] = [];
+      computeGaussianKernelWeights(sigma, out);
+      expect(sumOf(out)).toBeCloseTo(1, 12);
+    }
+  });
+
+  it('produces a symmetric kernel', () => {
+    const out: number[] = [];
+    computeGaussianKernelWeights(2, out);
+    for (let i = 0; i < out.length; i++) {
+      expect(out[i]).toBeCloseTo(out[out.length - 1 - i], 12);
+    }
+  });
+
+  it('makes the center weight the maximum', () => {
+    const out: number[] = [];
+    computeGaussianKernelWeights(2.5, out);
+    const center = (out.length - 1) / 2;
+    for (let i = 0; i < out.length; i++) {
+      expect(out[center]).toBeGreaterThanOrEqual(out[i]);
+    }
+  });
+
+  it('matches the closed-form Gaussian ratio between taps', () => {
+    // w[center+d] / w[center] = exp(-d^2 / (2 sigma^2)), independent of the normalization constant.
+    const sigma = 2;
+    const out: number[] = [];
+    computeGaussianKernelWeights(sigma, out);
+    const center = (out.length - 1) / 2;
+    for (const d of [1, 2, 3]) {
+      const expectedRatio = Math.exp(-(d * d) / (2 * sigma * sigma));
+      expect(out[center + d] / out[center]).toBeCloseTo(expectedRatio, 12);
+    }
+  });
+
+  it('sizes out to getGaussianKernelSize and reuses the array', () => {
+    const out: number[] = [9, 9, 9, 9, 9, 9, 9, 9, 9, 9];
+    computeGaussianKernelWeights(2, out);
+    expect(out.length).toBe(getGaussianKernelSize(2));
+  });
+
+  it('returns the identity kernel for non-positive sigma', () => {
+    const out: number[] = [];
+    computeGaussianKernelWeights(0, out);
+    expect(out).toEqual([1]);
+    computeGaussianKernelWeights(-3, out);
+    expect(out).toEqual([1]);
+  });
+
+  it('returns out', () => {
+    const out: number[] = [];
+    expect(computeGaussianKernelWeights(1.5, out)).toBe(out);
+  });
+});
+
+describe('getGaussianKernelSize', () => {
+  it('is radius*2+1 with radius = ceil(3*sigma)', () => {
+    expect(getGaussianKernelSize(1)).toBe(2 * 3 + 1);
+    expect(getGaussianKernelSize(2)).toBe(2 * 6 + 1);
+    expect(getGaussianKernelSize(2.5)).toBe(2 * Math.ceil(7.5) + 1);
+  });
+
+  it('is always odd', () => {
+    for (const sigma of [0.5, 1, 1.7, 4, 9]) {
+      expect(getGaussianKernelSize(sigma) % 2).toBe(1);
+    }
+  });
+
+  it('returns 1 for non-positive sigma', () => {
+    expect(getGaussianKernelSize(0)).toBe(1);
+    expect(getGaussianKernelSize(-2)).toBe(1);
+  });
+});

package/src/gradientBevelEffect.test.ts

@@ -0,0 +1,21 @@
+import { createGradientBevelEffect } from './gradientBevelEffect';
+
+describe('createGradientBevelEffect', () => {
+  it('tags the intent type', () => {
+    expect(createGradientBevelEffect({ colors: [0xff0000, 0x00ff00], alphas: [1, 1], ratios: [0, 255] }).kind).toBe(
+      'GradientBevelEffect',
+    );
+  });
+
+  it('carries options', () => {
+    expect(
+      createGradientBevelEffect({
+        colors: [0xff0000, 0x00ff00],
+        alphas: [1, 1],
+        ratios: [0, 255],
+        sourceMode: 'hide',
+        strength: 2,
+      }),
+    ).toMatchObject({ sourceMode: 'hide', strength: 2 });
+  });
+});

package/src/gradientGlowEffect.test.ts

@@ -0,0 +1,21 @@
+import { createGradientGlowEffect } from './gradientGlowEffect';
+
+describe('createGradientGlowEffect', () => {
+  it('tags the intent type', () => {
+    expect(createGradientGlowEffect({ colors: [0xff0000, 0x00ff00], alphas: [1, 1], ratios: [0, 255] }).kind).toBe(
+      'GradientGlowEffect',
+    );
+  });
+
+  it('carries options', () => {
+    expect(
+      createGradientGlowEffect({
+        colors: [0xff0000, 0x00ff00],
+        alphas: [1, 1],
+        ratios: [0, 255],
+        sourceMode: 'knockout',
+        strength: 2,
+      }),
+    ).toMatchObject({ sourceMode: 'knockout', strength: 2 });
+  });
+});

package/src/innerGlowEffect.test.ts

@@ -0,0 +1,15 @@
+import { createInnerGlowEffect } from './innerGlowEffect';
+
+describe('createInnerGlowEffect', () => {
+  it('tags the intent type', () => {
+    expect(createInnerGlowEffect().kind).toBe('InnerGlowEffect');
+  });
+
+  it('carries options', () => {
+    expect(createInnerGlowEffect({ strength: 2 })).toMatchObject({ strength: 2 });
+  });
+
+  it('carries source mode', () => {
+    expect(createInnerGlowEffect({ sourceMode: 'hide' })).toMatchObject({ sourceMode: 'hide' });
+  });
+});

package/src/innerShadowEffect.test.ts

@@ -0,0 +1,15 @@
+import { createInnerShadowEffect } from './innerShadowEffect';
+
+describe('createInnerShadowEffect', () => {
+  it('tags the intent type', () => {
+    expect(createInnerShadowEffect().kind).toBe('InnerShadowEffect');
+  });
+
+  it('carries options', () => {
+    expect(createInnerShadowEffect({ strength: 2 })).toMatchObject({ strength: 2 });
+  });
+
+  it('carries source mode', () => {
+    expect(createInnerShadowEffect({ sourceMode: 'hide' })).toMatchObject({ sourceMode: 'hide' });
+  });
+});