Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(types): phase 2 discriminated effect unions and capability-safe layer ports

okanasl89bead143ad5
diff --git a/packages/core/src/effects/index.ts b/packages/core/src/effects/index.ts
index a67476c4..69e2c153 100644
--- a/packages/core/src/effects/index.ts
+++ b/packages/core/src/effects/index.ts
@@ -17,8 +17,15 @@ export type EffectConfig<T extends object> = {
[K in keyof T]: EffectConfigValue<T[K]>;
};
-export abstract class Effect<TConfig extends object = Record<string, unknown>> {
- public abstract readonly op: string;
+export type EffectDomain = "visual" | "audio" | "both";
+
+export abstract class Effect<
+ TConfig extends object = Record<string, unknown>,
+ TOp extends string = string,
+ TDomain extends EffectDomain = "visual",
+> {
+ public abstract readonly op: TOp;
+ public readonly domain: TDomain = "visual" as TDomain;
public readonly signals: {
[K in keyof TConfig]: WritableSignal<TConfig[K]> | Signal<TConfig[K]>;
};
@@ -27,7 +34,9 @@ export abstract class Effect<TConfig extends object = Record<string, unknown>> {
constructor(initialConfig: TConfig) {
this.config = { ...initialConfig };
- this.signals = {} as any;
+ this.signals = {} as {
+ [K in keyof TConfig]: WritableSignal<TConfig[K]> | Signal<TConfig[K]>;
+ };
for (const [key, val] of Object.entries(initialConfig)) {
if (isSignal(val)) {
@@ -39,6 +48,7 @@ export abstract class Effect<TConfig extends object = Record<string, unknown>> {
// Proxy for seamless property access and mutation:
// e.g. `vignette.strength -= 0.1` updates `signals.strength.value`
+ // biome-ignore lint/correctness/noConstructorReturn: Effect proxies dynamic signal properties on the instance
return new Proxy(this, {
get(target, prop, receiver) {
if (typeof prop === "string" && prop in target.signals) {
diff --git a/packages/framefields/src/effects/classes.ts b/packages/framefields/src/effects/classes.ts
index 6505dd36..09a090d6 100644
--- a/packages/framefields/src/effects/classes.ts
+++ b/packages/framefields/src/effects/classes.ts
@@ -26,8 +26,9 @@ export interface LevelsProps {
blue?: LevelChannel;
}
-export class Levels extends Effect<LevelsProps> {
- public readonly op = "Levels";
+export class Levels extends Effect<LevelsProps, "Levels", "visual"> {
+ public readonly op = "Levels" as const;
+ public override readonly domain = "visual" as const;
public declare master: LevelChannel;
public declare red: LevelChannel;
@@ -62,8 +63,9 @@ export interface FilmGrainProps {
highlights?: EffectProp<number>;
}
-export class FilmGrain extends Effect<FilmGrainProps> {
- public readonly op = "FilmGrain";
+export class FilmGrain extends Effect<FilmGrainProps, "FilmGrain", "visual"> {
+ public readonly op = "FilmGrain" as const;
+ public override readonly domain = "visual" as const;
public declare strength: number;
public declare size: number;
@@ -89,8 +91,13 @@ export class FilmGrain extends Effect<FilmGrainProps> {
}
}
-export class CustomEffect extends Effect<Record<string, unknown>> {
+export class CustomEffect extends Effect<
+ Record<string, unknown>,
+ string,
+ "visual"
+> {
public readonly op: string;
+ public override readonly domain = "visual" as const;
constructor(opName: string, config: Record<string, unknown> = {}) {
super(config);
@@ -121,8 +128,13 @@ export interface AudioSignalExtractorProps {
nodeId?: string;
}
-export class AudioSignalExtractor extends Effect<AudioSignalExtractorProps> {
- public readonly op = "AudioSignalExtractor";
+export class AudioSignalExtractor extends Effect<
+ AudioSignalExtractorProps,
+ "AudioSignalExtractor",
+ "audio"
+> {
+ public readonly op = "AudioSignalExtractor" as const;
+ public override readonly domain = "audio" as const;
public declare extractionMode: AudioSignalExtractorProps["extractionMode"];
public declare attackMs: number;
@@ -197,8 +209,9 @@ export interface CurvesProps {
satVsSat?: CurvesChannelPoint[];
}
-export class Curves extends Effect<CurvesProps> {
- public readonly op = "Curves";
+export class Curves extends Effect<CurvesProps, "Curves", "visual"> {
+ public readonly op = "Curves" as const;
+ public override readonly domain = "visual" as const;
public declare curveType: CurvesProps["curveType"];
public declare master: CurvesChannelPoint[];
@@ -270,8 +283,13 @@ export interface SelectiveColorProps {
blacks?: Partial<SelectiveColorAdjustment>;
}
-export class SelectiveColor extends Effect<SelectiveColorProps> {
- public readonly op = "SelectiveColor";
+export class SelectiveColor extends Effect<
+ SelectiveColorProps,
+ "SelectiveColor",
+ "visual"
+> {
+ public readonly op = "SelectiveColor" as const;
+ public override readonly domain = "visual" as const;
public declare method: "Relative" | "Absolute";
public declare reds: SelectiveColorAdjustment;
@@ -319,8 +337,13 @@ export interface GradientMapProps {
opacity?: EffectProp<number>;
}
-export class GradientMap extends Effect<GradientMapProps> {
- public readonly op = "GradientMap";
+export class GradientMap extends Effect<
+ GradientMapProps,
+ "GradientMap",
+ "visual"
+> {
+ public readonly op = "GradientMap" as const;
+ public override readonly domain = "visual" as const;
public declare stops: GradientMapStop[];
public declare smooth: boolean;
@@ -353,8 +376,13 @@ export interface ShadowsHighlightsProps {
midtoneContrast?: EffectProp<number>;
}
-export class ShadowsHighlights extends Effect<ShadowsHighlightsProps> {
- public readonly op = "ShadowsHighlights";
+export class ShadowsHighlights extends Effect<
+ ShadowsHighlightsProps,
+ "ShadowsHighlights",
+ "visual"
+> {
+ public readonly op = "ShadowsHighlights" as const;
+ public override readonly domain = "visual" as const;
public declare shadowAmount: number;
public declare shadowTonalWidth: number;
@@ -385,8 +413,9 @@ export interface ApplyLUTProps {
intensity?: EffectProp<number>;
}
-export class ApplyLUT extends Effect<ApplyLUTProps> {
- public readonly op = "ApplyLUT";
+export class ApplyLUT extends Effect<ApplyLUTProps, "ApplyLUT", "visual"> {
+ public readonly op = "ApplyLUT" as const;
+ public override readonly domain = "visual" as const;
public declare lutUrl: string;
public declare intensity: number;
@@ -406,8 +435,13 @@ export interface UnsharpMaskProps {
threshold?: EffectProp<number>;
}
-export class UnsharpMask extends Effect<UnsharpMaskProps> {
- public readonly op = "UnsharpMask";
+export class UnsharpMask extends Effect<
+ UnsharpMaskProps,
+ "UnsharpMask",
+ "visual"
+> {
+ public readonly op = "UnsharpMask" as const;
+ public override readonly domain = "visual" as const;
public declare amount: number;
public declare radius: number;
@@ -429,8 +463,9 @@ export interface HighPassProps {
monochrome?: boolean;
}
-export class HighPass extends Effect<HighPassProps> {
- public readonly op = "HighPass";
+export class HighPass extends Effect<HighPassProps, "HighPass", "visual"> {
+ public readonly op = "HighPass" as const;
+ public override readonly domain = "visual" as const;
public declare radius: number;
public declare contrastBoost: number;
@@ -466,8 +501,13 @@ export interface HalftoneScreenProps {
opacity?: EffectProp<number>;
}
-export class HalftoneScreen extends Effect<HalftoneScreenProps> {
- public readonly op = "HalftoneScreen";
+export class HalftoneScreen extends Effect<
+ HalftoneScreenProps,
+ "HalftoneScreen",
+ "visual"
+> {
+ public readonly op = "HalftoneScreen" as const;
+ public override readonly domain = "visual" as const;
public declare mode: HalftoneMode;
public declare dotShape: HalftoneDotShape;
@@ -514,8 +554,13 @@ export interface TileOffsetProps {
edgeMode?: TileOffsetEdgeMode;
}
-export class TileOffset extends Effect<TileOffsetProps> {
- public readonly op = "TileOffset";
+export class TileOffset extends Effect<
+ TileOffsetProps,
+ "TileOffset",
+ "visual"
+> {
+ public readonly op = "TileOffset" as const;
+ public override readonly domain = "visual" as const;
public declare offsetX: number;
public declare offsetY: number;
@@ -541,8 +586,13 @@ export interface MotionBlurProps {
depthAware?: boolean;
}
-export class MotionBlur extends Effect<MotionBlurProps> {
- public readonly op = "MotionBlur";
+export class MotionBlur extends Effect<
+ MotionBlurProps,
+ "MotionBlur",
+ "visual"
+> {
+ public readonly op = "MotionBlur" as const;
+ public override readonly domain = "visual" as const;
public declare shutterAngle: number;
public declare samples: number;
@@ -570,8 +620,9 @@ export interface SSAOProps {
blurRadius?: EffectProp<number>;
}
-export class SSAO extends Effect<SSAOProps> {
- public readonly op = "SSAO";
+export class SSAO extends Effect<SSAOProps, "SSAO", "visual"> {
+ public readonly op = "SSAO" as const;
+ public override readonly domain = "visual" as const;
public declare radius: number;
public declare bias: number;
@@ -600,8 +651,9 @@ export interface PBRGlassProps {
tintColor?: EffectProp<string>;
}
-export class PBRGlass extends Effect<PBRGlassProps> {
- public readonly op = "PBRGlass";
+export class PBRGlass extends Effect<PBRGlassProps, "PBRGlass", "visual"> {
+ public readonly op = "PBRGlass" as const;
+ public override readonly domain = "visual" as const;
public declare ior: number;
public declare roughness: number;
@@ -631,8 +683,13 @@ export interface DepthOfFieldProps {
quality?: "low" | "medium" | "high" | "ultra";
}
-export class DepthOfField extends Effect<DepthOfFieldProps> {
- public readonly op = "DepthOfField";
+export class DepthOfField extends Effect<
+ DepthOfFieldProps,
+ "DepthOfField",
+ "visual"
+> {
+ public readonly op = "DepthOfField" as const;
+ public override readonly domain = "visual" as const;
public declare focusDistance: number;
public declare focalLength: number;
@@ -663,8 +720,9 @@ export interface CropProps {
mode?: "cropped" | "rest";
}
-export class Crop extends Effect<CropProps> {
- public readonly op = "Crop";
+export class Crop extends Effect<CropProps, "Crop", "visual"> {
+ public readonly op = "Crop" as const;
+ public override readonly domain = "visual" as const;
public declare cropType: "rect" | "path";
public declare leftPercentage: number;
@@ -733,8 +791,9 @@ export interface VisionProps {
* On-device vision: tracks objects, segments instances, estimates pose and mattes people on
* the rendered frame, feeding reactive signals. Models download lazily on first use.
*/
-export class Vision extends Effect<VisionProps> {
- public readonly op = "Vision";
+export class Vision extends Effect<VisionProps, "Vision", "visual"> {
+ public readonly op = "Vision" as const;
+ public override readonly domain = "visual" as const;
public declare enableDetection?: boolean;
public declare enableSegmentation?: boolean;
@@ -789,8 +848,9 @@ export interface Relight3DProps {
normalMap?: unknown;
}
-export class Relight3D extends Effect<Relight3DProps> {
- public readonly op = "Relight3D";
+export class Relight3D extends Effect<Relight3DProps, "Relight3D", "visual"> {
+ public readonly op = "Relight3D" as const;
+ public override readonly domain = "visual" as const;
public declare lightType: Relight3DProps["lightType"];
public declare intensity: number;
@@ -842,8 +902,13 @@ export interface DeflickerProps {
windowSize?: number;
}
-export class TemporalDeflicker extends Effect<DeflickerProps> {
- public readonly op = "TemporalDeflicker";
+export class TemporalDeflicker extends Effect<
+ DeflickerProps,
+ "TemporalDeflicker",
+ "visual"
+> {
+ public readonly op = "TemporalDeflicker" as const;
+ public override readonly domain = "visual" as const;
public declare blendWeight: number;
public declare disocclusionThreshold: number;
@@ -872,8 +937,9 @@ export interface ModulateProps {
sepia?: EffectProp<number>;
}
-export class Modulate extends Effect<ModulateProps> {
- public readonly op = "Modulate";
+export class Modulate extends Effect<ModulateProps, "Modulate", "visual"> {
+ public readonly op = "Modulate" as const;
+ public override readonly domain = "visual" as const;
public declare hue: number;
public declare brightness: number;
@@ -894,3 +960,63 @@ export class Modulate extends Effect<ModulateProps> {
});
}
}
+
+export type HandWrittenVisualEffect =
+ | Levels
+ | FilmGrain
+ | CustomEffect
+ | Curves
+ | SelectiveColor
+ | GradientMap
+ | ShadowsHighlights
+ | ApplyLUT
+ | UnsharpMask
+ | HighPass
+ | HalftoneScreen
+ | TileOffset
+ | MotionBlur
+ | SSAO
+ | PBRGlass
+ | DepthOfField
+ | Crop
+ | Vision
+ | Relight3D
+ | TemporalDeflicker
+ | Modulate;
+
+export type HandWrittenAudioEffect = AudioSignalExtractor;
+
+export type AnyVisualEffect =
+ | AnyGeneratedVisualEffect
+ | HandWrittenVisualEffect;
+export type AnyAudioEffect = AnyGeneratedAudioEffect | HandWrittenAudioEffect;
+export type AnyEffect = AnyVisualEffect | AnyAudioEffect;
+export type EffectOp = AnyEffect["op"];
+
+export interface EffectConfigMap extends GeneratedEffectConfigMap {
+ Levels: LevelsProps;
+ FilmGrain: FilmGrainProps;
+ AudioSignalExtractor: AudioSignalExtractorProps;
+ Curves: CurvesProps;
+ SelectiveColor: SelectiveColorProps;
+ GradientMap: GradientMapProps;
+ ShadowsHighlights: ShadowsHighlightsProps;
+ ApplyLUT: ApplyLUTProps;
+ UnsharpMask: UnsharpMaskProps;
+ HighPass: HighPassProps;
+ HalftoneScreen: HalftoneScreenProps;
+ TileOffset: TileOffsetProps;
+ MotionBlur: MotionBlurProps;
+ SSAO: SSAOProps;
+ PBRGlass: PBRGlassProps;
+ DepthOfField: DepthOfFieldProps;
+ Crop: CropProps;
+ Vision: VisionProps;
+ Relight3D: Relight3DProps;
+ TemporalDeflicker: DeflickerProps;
+ Modulate: ModulateProps;
+}
+
+export type EffectPropsFor<O extends EffectOp> = O extends keyof EffectConfigMap
+ ? EffectConfigMap[O]
+ : Record<string, unknown>;
diff --git a/packages/framefields/src/effects/generated/classes.ts b/packages/framefields/src/effects/generated/classes.ts
index 38ea6695..90791c26 100644
--- a/packages/framefields/src/effects/generated/classes.ts
+++ b/packages/framefields/src/effects/generated/classes.ts
@@ -476,8 +476,9 @@ const asciiDefaults: AsciiProps = {
invert: false,
};
-export class Ascii extends Effect<AsciiProps> {
- public readonly op = "Ascii";
+export class Ascii extends Effect<AsciiProps, "Ascii", "visual"> {
+ public readonly op = "Ascii" as const;
+ public override readonly domain = "visual" as const;
public declare cellSize: number;
public declare colorMode: "mono" | "source" | "green";
@@ -539,8 +540,13 @@ const audioCompressorDefaults: AudioCompressorProps = {
makeupGain: 0,
};
-export class AudioCompressor extends Effect<AudioCompressorProps> {
- public readonly op = "AudioCompressor";
+export class AudioCompressor extends Effect<
+ AudioCompressorProps,
+ "AudioCompressor",
+ "audio"
+> {
+ public readonly op = "AudioCompressor" as const;
+ public override readonly domain = "audio" as const;
public declare threshold: number;
public declare ratio: number;
@@ -601,8 +607,9 @@ const audioDelayDefaults: AudioDelayProps = {
pingPong: false,
};
-export class AudioDelay extends Effect<AudioDelayProps> {
- public readonly op = "AudioDelay";
+export class AudioDelay extends Effect<AudioDelayProps, "AudioDelay", "audio"> {
+ public readonly op = "AudioDelay" as const;
+ public override readonly domain = "audio" as const;
public declare delayTime: number;
public declare feedback: number;
@@ -654,8 +661,9 @@ const audioFadeDefaults: AudioFadeProps = {
fadeOutCurve: "linear",
};
-export class AudioFade extends Effect<AudioFadeProps> {
- public readonly op = "AudioFade";
+export class AudioFade extends Effect<AudioFadeProps, "AudioFade", "audio"> {
+ public readonly op = "AudioFade" as const;
+ public override readonly domain = "audio" as const;
public declare fadeInDuration: number;
public declare fadeOutDuration: number;
@@ -715,8 +723,13 @@ const audioNoiseGateDefaults: AudioNoiseGateProps = {
range: -80,
};
-export class AudioNoiseGate extends Effect<AudioNoiseGateProps> {
- public readonly op = "AudioNoiseGate";
+export class AudioNoiseGate extends Effect<
+ AudioNoiseGateProps,
+ "AudioNoiseGate",
+ "audio"
+> {
+ public readonly op = "AudioNoiseGate" as const;
+ public override readonly domain = "audio" as const;
public declare threshold: number;
public declare attack: number;
@@ -769,8 +782,13 @@ const audioParametricEqDefaults: AudioParametricEqProps = {
q: 1,
};
-export class AudioParametricEq extends Effect<AudioParametricEqProps> {
- public readonly op = "AudioParametricEq";
+export class AudioParametricEq extends Effect<
+ AudioParametricEqProps,
+ "AudioParametricEq",
+ "audio"
+> {
+ public readonly op = "AudioParametricEq" as const;
+ public override readonly domain = "audio" as const;
public declare type:
| "lowShelf"
@@ -836,8 +854,13 @@ const audioReverbDefaults: AudioReverbProps = {
width: 1,
};
-export class AudioReverb extends Effect<AudioReverbProps> {
- public readonly op = "AudioReverb";
+export class AudioReverb extends Effect<
+ AudioReverbProps,
+ "AudioReverb",
+ "audio"
+> {
+ public readonly op = "AudioReverb" as const;
+ public override readonly domain = "audio" as const;
public declare roomSize: number;
public declare damping: number;
@@ -940,8 +963,9 @@ const blurDefaults: BlurBaseProps = {
};
/** @internal Extended by `effects/custom/blur.ts`, which exports `Blur`. */
-export class BlurBase extends Effect<BlurBaseProps> {
- public readonly op = "Blur";
+export class BlurBase extends Effect<BlurBaseProps, "Blur", "visual"> {
+ public readonly op = "Blur" as const;
+ public override readonly domain = "visual" as const;
public declare blurType:
| "Gaussian"
@@ -1047,8 +1071,13 @@ const cameraParallax3DDefaults: CameraParallax3DProps = {
depthInvert: false,
};
-export class CameraParallax3D extends Effect<CameraParallax3DProps> {
- public readonly op = "CameraParallax3D";
+export class CameraParallax3D extends Effect<
+ CameraParallax3DProps,
+ "CameraParallax3D",
+ "visual"
+> {
+ public readonly op = "CameraParallax3D" as const;
+ public override readonly domain = "visual" as const;
public declare motionPreset:
| "Custom"
@@ -1098,8 +1127,13 @@ const channelMergerDefaults: ChannelMergerProps = {
defaultChannel4: 1,
};
-export class ChannelMerger extends Effect<ChannelMergerProps> {
- public readonly op = "ChannelMerger";
+export class ChannelMerger extends Effect<
+ ChannelMergerProps,
+ "ChannelMerger",
+ "visual"
+> {
+ public readonly op = "ChannelMerger" as const;
+ public override readonly domain = "visual" as const;
public declare colorSpace: "RGBA" | "HSLA" | "CMYK" | "LAB";
public declare defaultChannel4: number;
@@ -1128,8 +1162,13 @@ const channelSplitterDefaults: ChannelSplitterProps = {
colorSpace: "RGBA",
};
-export class ChannelSplitter extends Effect<ChannelSplitterProps> {
- public readonly op = "ChannelSplitter";
+export class ChannelSplitter extends Effect<
+ ChannelSplitterProps,
+ "ChannelSplitter",
+ "visual"
+> {
+ public readonly op = "ChannelSplitter" as const;
+ public override readonly domain = "visual" as const;
public declare colorSpace: "RGBA" | "HSLA" | "CMYK" | "LAB";
@@ -1171,8 +1210,13 @@ const colorBalanceDefaults: ColorBalanceProps = {
preserveLuminosity: true,
};
-export class ColorBalance extends Effect<ColorBalanceProps> {
- public readonly op = "ColorBalance";
+export class ColorBalance extends Effect<
+ ColorBalanceProps,
+ "ColorBalance",
+ "visual"
+> {
+ public readonly op = "ColorBalance" as const;
+ public override readonly domain = "visual" as const;
public declare shadows: Partial<TonalShift>;
public declare midtones: Partial<TonalShift>;
@@ -1236,8 +1280,9 @@ const colorKeyDefaults: ColorKeyProps = {
spillSuppressionType: "Desaturate",
};
-export class ColorKey extends Effect<ColorKeyProps> {
- public readonly op = "ColorKey";
+export class ColorKey extends Effect<ColorKeyProps, "ColorKey", "visual"> {
+ public readonly op = "ColorKey" as const;
+ public override readonly domain = "visual" as const;
public declare keyColor: string;
public declare similarity: number;
@@ -1298,8 +1343,9 @@ const contourDefaults: ContourProps = {
smoothing: 2,
};
-export class Contour extends Effect<ContourProps> {
- public readonly op = "Contour";
+export class Contour extends Effect<ContourProps, "Contour", "visual"> {
+ public readonly op = "Contour" as const;
+ public override readonly domain = "visual" as const;
public declare levels: number;
public declare lineWidth: number;
@@ -1319,8 +1365,9 @@ export interface CornerPinProps {
const cornerPinDefaults: CornerPinProps = {};
-export class CornerPin extends Effect<CornerPinProps> {
- public readonly op = "CornerPin";
+export class CornerPin extends Effect<CornerPinProps, "CornerPin", "visual"> {
+ public readonly op = "CornerPin" as const;
+ public override readonly domain = "visual" as const;
public declare points: CornerPinPointsItem[] | undefined;
@@ -1405,8 +1452,9 @@ const cRTDefaults: CRTProps = {
chroma: 0,
};
-export class CRT extends Effect<CRTProps> {
- public readonly op = "CRT";
+export class CRT extends Effect<CRTProps, "CRT", "visual"> {
+ public readonly op = "CRT" as const;
+ public override readonly domain = "visual" as const;
public declare scanlines: number;
public declare lineCount: number;
@@ -1456,8 +1504,9 @@ const datamoshDefaults: DatamoshProps = {
warmup: 48,
};
-export class Datamosh extends Effect<DatamoshProps> {
- public readonly op = "Datamosh";
+export class Datamosh extends Effect<DatamoshProps, "Datamosh", "visual"> {
+ public readonly op = "Datamosh" as const;
+ public override readonly domain = "visual" as const;
public declare keyframes: number[];
public declare strength: number;
@@ -1509,8 +1558,13 @@ const displacementMapDefaults: DisplacementMapProps = {
wrapMode: "Clamp",
};
-export class DisplacementMap extends Effect<DisplacementMapProps> {
- public readonly op = "DisplacementMap";
+export class DisplacementMap extends Effect<
+ DisplacementMapProps,
+ "DisplacementMap",
+ "visual"
+> {
+ public readonly op = "DisplacementMap" as const;
+ public override readonly domain = "visual" as const;
public declare strengthX: number;
public declare strengthY: number;
@@ -1574,8 +1628,9 @@ const ditherDefaults: DitherProps = {
light: "#f2efe6",
};
-export class Dither extends Effect<DitherProps> {
- public readonly op = "Dither";
+export class Dither extends Effect<DitherProps, "Dither", "visual"> {
+ public readonly op = "Dither" as const;
+ public override readonly domain = "visual" as const;
public declare mode: "bayer" | "noise" | "halftone";
public declare levels: number;
@@ -1608,8 +1663,13 @@ const extractLUTDefaults: ExtractLUTProps = {
samplePoints: 150,
};
-export class ExtractLUT extends Effect<ExtractLUTProps> {
- public readonly op = "ExtractLUT";
+export class ExtractLUT extends Effect<
+ ExtractLUTProps,
+ "ExtractLUT",
+ "visual"
+> {
+ public readonly op = "ExtractLUT" as const;
+ public override readonly domain = "visual" as const;
public declare strategy: "deterministic" | "statistical";
public declare samplePoints: number;
@@ -1674,8 +1734,9 @@ const flipDefaults: FlipProps = {
symmetry: "none",
};
-export class Flip extends Effect<FlipProps> {
- public readonly op = "Flip";
+export class Flip extends Effect<FlipProps, "Flip", "visual"> {
+ public readonly op = "Flip" as const;
+ public override readonly domain = "visual" as const;
public declare horizontal: boolean;
public declare vertical: boolean;
@@ -1727,8 +1788,9 @@ const gooeyDefaults: GooeyProps = {
softness: 0.04,
};
-export class Gooey extends Effect<GooeyProps> {
- public readonly op = "Gooey";
+export class Gooey extends Effect<GooeyProps, "Gooey", "visual"> {
+ public readonly op = "Gooey" as const;
+ public override readonly domain = "visual" as const;
public declare radius: number;
public declare threshold: number;
@@ -1772,8 +1834,13 @@ const iridescenceDefaults: IridescenceProps = {
mode: "relief",
};
-export class Iridescence extends Effect<IridescenceProps> {
- public readonly op = "Iridescence";
+export class Iridescence extends Effect<
+ IridescenceProps,
+ "Iridescence",
+ "visual"
+> {
+ public readonly op = "Iridescence" as const;
+ public override readonly domain = "visual" as const;
public declare strength: number;
public declare scale: number;
@@ -1833,8 +1900,13 @@ const kaleidoscopeDefaults: KaleidoscopeProps = {
zoom: 1,
};
-export class Kaleidoscope extends Effect<KaleidoscopeProps> {
- public readonly op = "Kaleidoscope";
+export class Kaleidoscope extends Effect<
+ KaleidoscopeProps,
+ "Kaleidoscope",
+ "visual"
+> {
+ public readonly op = "Kaleidoscope" as const;
+ public override readonly domain = "visual" as const;
public declare segments: number;
public declare rotation: number;
@@ -1892,8 +1964,9 @@ const kenBurnsDefaults: KenBurnsProps = {
aspectRatio: "input",
};
-export class KenBurns extends Effect<KenBurnsProps> {
- public readonly op = "KenBurns";
+export class KenBurns extends Effect<KenBurnsProps, "KenBurns", "visual"> {
+ public readonly op = "KenBurns" as const;
+ public override readonly domain = "visual" as const;
public declare keyframes: KenBurnsKeyframesItem[];
public declare motionBlurSize: number;
@@ -2043,8 +2116,13 @@ const layerStyleDefaults: LayerStyleProps = {
},
};
-export class LayerStyle extends Effect<LayerStyleProps> {
- public readonly op = "LayerStyle";
+export class LayerStyle extends Effect<
+ LayerStyleProps,
+ "LayerStyle",
+ "visual"
+> {
+ public readonly op = "LayerStyle" as const;
+ public override readonly domain = "visual" as const;
public declare dropShadow: Partial<LayerStyleDropShadow>;
public declare innerShadow: Partial<LayerStyleInnerShadow>;
@@ -2104,8 +2182,9 @@ const liquifyDefaults: LiquifyProps = {
operations: [],
};
-export class Liquify extends Effect<LiquifyProps> {
- public readonly op = "Liquify";
+export class Liquify extends Effect<LiquifyProps, "Liquify", "visual"> {
+ public readonly op = "Liquify" as const;
+ public override readonly domain = "visual" as const;
public declare operations: LiquifyOperationsItem[];
@@ -2197,8 +2276,9 @@ const maskMathDefaults: MaskMathProps = {
outputFormat: "WhiteWithAlpha",
};
-export class MaskMath extends Effect<MaskMathProps> {
- public readonly op = "MaskMath";
+export class MaskMath extends Effect<MaskMathProps, "MaskMath", "visual"> {
+ public readonly op = "MaskMath" as const;
+ public override readonly domain = "visual" as const;
public declare operation:
| "Union"
@@ -2250,8 +2330,9 @@ const meshWarpDefaults: MeshWarpProps = {
rows: 3,
};
-export class MeshWarp extends Effect<MeshWarpProps> {
- public readonly op = "MeshWarp";
+export class MeshWarp extends Effect<MeshWarpProps, "MeshWarp", "visual"> {
+ public readonly op = "MeshWarp" as const;
+ public override readonly domain = "visual" as const;
public declare cols: number;
public declare rows: number;
@@ -2357,8 +2438,13 @@ const noiseGeneratorDefaults: NoiseGeneratorProps = {
fps: 30,
};
-export class NoiseGenerator extends Effect<NoiseGeneratorProps> {
- public readonly op = "NoiseGenerator";
+export class NoiseGenerator extends Effect<
+ NoiseGeneratorProps,
+ "NoiseGenerator",
+ "visual"
+> {
+ public readonly op = "NoiseGenerator" as const;
+ public override readonly domain = "visual" as const;
public declare noiseType: "Perlin" | "Simplex" | "Voronoi";
public declare outputType: "Image" | "Video";
@@ -2438,8 +2524,9 @@ const opArtDefaults: OpArtProps = {
colorB: "#f5f5f5",
};
-export class OpArt extends Effect<OpArtProps> {
- public readonly op = "OpArt";
+export class OpArt extends Effect<OpArtProps, "OpArt", "visual"> {
+ public readonly op = "OpArt" as const;
+ public override readonly domain = "visual" as const;
public declare pattern: "stripes" | "rings" | "checker" | "waves";
public declare frequency: number;
@@ -2488,8 +2575,9 @@ const paintDefaults: PaintProps = {
backgroundColor: "#ffffff",
};
-export class Paint extends Effect<PaintProps> {
- public readonly op = "Paint";
+export class Paint extends Effect<PaintProps, "Paint", "visual"> {
+ public readonly op = "Paint" as const;
+ public override readonly domain = "visual" as const;
public declare width: number;
public declare height: number;
@@ -2549,8 +2637,9 @@ const painterlyDefaults: PainterlyProps = {
saturation: 1.05,
};
-export class Painterly extends Effect<PainterlyProps> {
- public readonly op = "Painterly";
+export class Painterly extends Effect<PainterlyProps, "Painterly", "visual"> {
+ public readonly op = "Painterly" as const;
+ public override readonly domain = "visual" as const;
public declare style: "oil" | "watercolor";
public declare radius: number;
@@ -2640,8 +2729,9 @@ const patchHealDefaults: PatchHealProps = {
mode: "SeamlessHeal",
};
-export class PatchHeal extends Effect<PatchHealProps> {
- public readonly op = "PatchHeal";
+export class PatchHeal extends Effect<PatchHealProps, "PatchHeal", "visual"> {
+ public readonly op = "PatchHeal" as const;
+ public override readonly domain = "visual" as const;
public declare patches: PatchHealPatchesItem[] | undefined;
public declare centerX: number;
@@ -2692,8 +2782,9 @@ const pixelateDefaults: PixelateProps = {
gap: 0,
};
-export class Pixelate extends Effect<PixelateProps> {
- public readonly op = "Pixelate";
+export class Pixelate extends Effect<PixelateProps, "Pixelate", "visual"> {
+ public readonly op = "Pixelate" as const;
+ public override readonly domain = "visual" as const;
public declare size: number;
public declare shape: "square" | "circle" | "diamond";
@@ -2754,8 +2845,9 @@ const posterizeDefaults: PosterizeProps = {
pixelSize: 1,
};
-export class Posterize extends Effect<PosterizeProps> {
- public readonly op = "Posterize";
+export class Posterize extends Effect<PosterizeProps, "Posterize", "visual"> {
+ public readonly op = "Posterize" as const;
+ public override readonly domain = "visual" as const;
public declare levels: number;
public declare palette:
@@ -2889,8 +2981,13 @@ const proceduralVFXDefaults: ProceduralVFXProps = {
fps: 30,
};
-export class ProceduralVFX extends Effect<ProceduralVFXProps> {
- public readonly op = "ProceduralVFX";
+export class ProceduralVFX extends Effect<
+ ProceduralVFXProps,
+ "ProceduralVFX",
+ "visual"
+> {
+ public readonly op = "ProceduralVFX" as const;
+ public override readonly domain = "visual" as const;
public declare effectType:
| "Smoke"
@@ -2983,8 +3080,13 @@ const refineEdgeDefaults: RefineEdgeProps = {
outputMode: "Composite",
};
-export class RefineEdge extends Effect<RefineEdgeProps> {
- public readonly op = "RefineEdge";
+export class RefineEdge extends Effect<
+ RefineEdgeProps,
+ "RefineEdge",
+ "visual"
+> {
+ public readonly op = "RefineEdge" as const;
+ public override readonly domain = "visual" as const;
public declare decontaminateAmount: number;
public declare radius: number;
@@ -3115,8 +3217,13 @@ const refractionCaustics3DDefaults: RefractionCaustics3DProps = {
depthScale: 1,
};
-export class RefractionCaustics3D extends Effect<RefractionCaustics3DProps> {
- public readonly op = "RefractionCaustics3D";
+export class RefractionCaustics3D extends Effect<
+ RefractionCaustics3DProps,
+ "RefractionCaustics3D",
+ "visual"
+> {
+ public readonly op = "RefractionCaustics3D" as const;
+ public override readonly domain = "visual" as const;
public declare ior: number;
public declare dispersion: number;
@@ -3234,8 +3341,13 @@ const resizerScalerDefaults: ResizerScalerProps = {
anchorY: "center",
};
-export class ResizerScaler extends Effect<ResizerScalerProps> {
- public readonly op = "ResizerScaler";
+export class ResizerScaler extends Effect<
+ ResizerScalerProps,
+ "ResizerScaler",
+ "visual"
+> {
+ public readonly op = "ResizerScaler" as const;
+ public override readonly domain = "visual" as const;
public declare aspectRatioPreset:
| "9:16"
@@ -3301,8 +3413,9 @@ const rGBSplitDefaults: RGBSplitProps = {
radial: false,
};
-export class RGBSplit extends Effect<RGBSplitProps> {
- public readonly op = "RGBSplit";
+export class RGBSplit extends Effect<RGBSplitProps, "RGBSplit", "visual"> {
+ public readonly op = "RGBSplit" as const;
+ public override readonly domain = "visual" as const;
public declare amount: number;
public declare angle: number;
@@ -3341,8 +3454,9 @@ const rotateDefaults: RotateProps = {
scale: 1,
};
-export class Rotate extends Effect<RotateProps> {
- public readonly op = "Rotate";
+export class Rotate extends Effect<RotateProps, "Rotate", "visual"> {
+ public readonly op = "Rotate" as const;
+ public override readonly domain = "visual" as const;
public declare angle: number;
public declare fit: "cover" | "contain" | "fill";
@@ -3366,8 +3480,13 @@ const stereoPanningDefaults: StereoPanningProps = {
pan: 0,
};
-export class StereoPanning extends Effect<StereoPanningProps> {
- public readonly op = "StereoPanning";
+export class StereoPanning extends Effect<
+ StereoPanningProps,
+ "StereoPanning",
+ "audio"
+> {
+ public readonly op = "StereoPanning" as const;
+ public override readonly domain = "audio" as const;
public declare pan: number;
@@ -3423,8 +3542,9 @@ const toonDefaults: ToonProps = {
saturation: 1.15,
};
-export class Toon extends Effect<ToonProps> {
- public readonly op = "Toon";
+export class Toon extends Effect<ToonProps, "Toon", "visual"> {
+ public readonly op = "Toon" as const;
+ public override readonly domain = "visual" as const;
public declare levels: number;
public declare edgeThreshold: number;
@@ -3498,8 +3618,9 @@ const trailsDefaults: TrailsProps = {
warmup: 60,
};
-export class Trails extends Effect<TrailsProps> {
- public readonly op = "Trails";
+export class Trails extends Effect<TrailsProps, "Trails", "visual"> {
+ public readonly op = "Trails" as const;
+ public override readonly domain = "visual" as const;
public declare decay: number;
public declare mode: "blend" | "over" | "add" | "max";
@@ -3563,8 +3684,9 @@ const vignetteDefaults: VignetteProps = {
centerY: 0.5,
};
-export class Vignette extends Effect<VignetteProps> {
- public readonly op = "Vignette";
+export class Vignette extends Effect<VignetteProps, "Vignette", "visual"> {
+ public readonly op = "Vignette" as const;
+ public override readonly domain = "visual" as const;
public declare strength: number;
public declare radius: number;
diff --git a/packages/framefields/src/effects/generated/index.ts b/packages/framefields/src/effects/generated/index.ts
index 93db17a6..d0156e34 100644
--- a/packages/framefields/src/effects/generated/index.ts
+++ b/packages/framefields/src/effects/generated/index.ts
@@ -113,3 +113,105 @@ export {
} from "./classes.js";
export { effectMeta } from "./meta.js";
export { effectFactories } from "./registry.js";
+
+/** Discriminated unions of all generated effects by domain. */
+export type AnyGeneratedVisualEffect =
+ | Ascii
+ | Blur
+ | CameraParallax3D
+ | ChannelMerger
+ | ChannelSplitter
+ | ColorBalance
+ | ColorKey
+ | Contour
+ | CornerPin
+ | CRT
+ | Datamosh
+ | DisplacementMap
+ | Dither
+ | ExtractLUT
+ | Flip
+ | Gooey
+ | Iridescence
+ | Kaleidoscope
+ | KenBurns
+ | LayerStyle
+ | Liquify
+ | MaskMath
+ | MeshWarp
+ | NoiseGenerator
+ | OpArt
+ | Paint
+ | Painterly
+ | PatchHeal
+ | Pixelate
+ | Posterize
+ | ProceduralVFX
+ | RefineEdge
+ | RefractionCaustics3D
+ | ResizerScaler
+ | RGBSplit
+ | Rotate
+ | Toon
+ | Trails
+ | Vignette;
+export type AnyGeneratedAudioEffect =
+ | AudioCompressor
+ | AudioDelay
+ | AudioFade
+ | AudioNoiseGate
+ | AudioParametricEq
+ | AudioReverb
+ | StereoPanning;
+export type AnyGeneratedEffect =
+ | AnyGeneratedVisualEffect
+ | AnyGeneratedAudioEffect;
+
+export interface GeneratedEffectConfigMap {
+ Ascii: AsciiProps;
+ AudioCompressor: AudioCompressorProps;
+ AudioDelay: AudioDelayProps;
+ AudioFade: AudioFadeProps;
+ AudioNoiseGate: AudioNoiseGateProps;
+ AudioParametricEq: AudioParametricEqProps;
+ AudioReverb: AudioReverbProps;
+ Blur: BlurProps;
+ CameraParallax3D: CameraParallax3DProps;
+ ChannelMerger: ChannelMergerProps;
+ ChannelSplitter: ChannelSplitterProps;
+ ColorBalance: ColorBalanceProps;
+ ColorKey: ColorKeyProps;
+ Contour: ContourProps;
+ CornerPin: CornerPinProps;
+ CRT: CRTProps;
+ Datamosh: DatamoshProps;
+ DisplacementMap: DisplacementMapProps;
+ Dither: DitherProps;
+ ExtractLUT: ExtractLUTProps;
+ Flip: FlipProps;
+ Gooey: GooeyProps;
+ Iridescence: IridescenceProps;
+ Kaleidoscope: KaleidoscopeProps;
+ KenBurns: KenBurnsProps;
+ LayerStyle: LayerStyleProps;
+ Liquify: LiquifyProps;
+ MaskMath: MaskMathProps;
+ MeshWarp: MeshWarpProps;
+ NoiseGenerator: NoiseGeneratorProps;
+ OpArt: OpArtProps;
+ Paint: PaintProps;
+ Painterly: PainterlyProps;
+ PatchHeal: PatchHealProps;
+ Pixelate: PixelateProps;
+ Posterize: PosterizeProps;
+ ProceduralVFX: ProceduralVFXProps;
+ RefineEdge: RefineEdgeProps;
+ RefractionCaustics3D: RefractionCaustics3DProps;
+ ResizerScaler: ResizerScalerProps;
+ RGBSplit: RGBSplitProps;
+ Rotate: RotateProps;
+ StereoPanning: StereoPanningProps;
+ Toon: ToonProps;
+ Trails: TrailsProps;
+ Vignette: VignetteProps;
+}
diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.ts
index 2394c381..e2eebe28 100644
--- a/packages/framefields/src/index.ts
+++ b/packages/framefields/src/index.ts
@@ -202,6 +202,9 @@ import { inputStore, mediaDecoderCache } from "@framefields/webgpu-renderers";
import { buildChart, type ChartOptions } from "./chart.js";
import { ClipVision, type ClipVisionOptions } from "./clip-vision.js";
import {
+ type AnyAudioEffect,
+ type AnyEffect,
+ type AnyVisualEffect,
ApplyLUT,
type ApplyLUTProps,
Blur,
@@ -283,7 +286,7 @@ export interface SectionOptions {
readonly id?: string;
readonly position?: "absolute" | "relative";
readonly source?: string | MediaNode;
- readonly effects?: Effect<object>[];
+ readonly effects?: AnyVisualEffect[];
readonly padding?: number;
readonly borderRadius?: number;
readonly borderColor?: string;
@@ -304,13 +307,13 @@ export interface SectionOptions {
readonly children?: LayoutNode[];
}
-export type SectionNode = AnimatableNode<BoxNode> & {
- readonly innerMedia: AnimatableNode<MediaNode>;
- // Any effect, whatever its config shape (Blur, FilmGrain, …).
- readonly effects: Effect<object>[];
- addEffect(effect: Effect<object>): SectionNode;
- withEffect(effect: Effect<object>): SectionNode;
- withEffects(effects: Effect<object>[]): SectionNode;
+export type SectionNode = AnimatableNode<BoxNode, "visual"> & {
+ readonly innerMedia: AnimatableNode<MediaNode, "hybrid">;
+ // Any visual effect, whatever its config shape (Blur, FilmGrain, …).
+ readonly effects: AnyVisualEffect[];
+ addEffect(effect: AnyVisualEffect): SectionNode;
+ withEffect(effect: AnyVisualEffect): SectionNode;
+ withEffects(effects: AnyVisualEffect[]): SectionNode;
};
export type TrackedRegionOptions = SectionOptions;
@@ -691,6 +694,14 @@ export {
PersonTrack,
type PoseKeypointName,
} from "./clip-vision.js";
+export type {
+ AnyAudioEffect,
+ AnyEffect,
+ AnyVisualEffect,
+ EffectConfigMap,
+ EffectOp,
+ EffectPropsFor,
+} from "./effects/index.js";
export {
ApplyLUT,
type ApplyLUTProps,
@@ -1170,12 +1181,12 @@ export class Composition {
private readonly _clipVision = new Map<string, ClipVision>();
private _visionConfig?: VisionProps;
private _visionBundle?: VisionBundle;
- private _effects: Effect<object>[] = [];
+ private _effects: AnyEffect[] = [];
/**
* Applies a whole-composition post-processing effect or vision pipeline.
*/
- public apply(effect: Effect<object>): this {
+ public apply(effect: AnyEffect): this {
if (effect instanceof Vision) {
this.withVision(effect);
return this;
@@ -2102,7 +2113,21 @@ export class Composition {
* Layer helpers for constructing composition nodes with clean URL/path strings.
*/
-export type AnimatableNode<T extends LayoutNode> = T & {
+export type NodeCapability = "visual" | "audio" | "hybrid";
+
+export type CompatibleEffect<TCap extends NodeCapability> =
+ TCap extends "hybrid"
+ ? AnyEffect
+ : TCap extends "visual"
+ ? AnyVisualEffect
+ : TCap extends "audio"
+ ? AnyAudioEffect
+ : Effect<object>;
+
+export type AnimatableNode<
+ T extends LayoutNode = LayoutNode,
+ TCap extends NodeCapability = "visual",
+> = T & {
glass?: Record<string, unknown>;
audioDeform?: MeshAudioDeformConfig | Record<string, unknown>;
crop?: CropProps | Crop;
@@ -2117,7 +2142,7 @@ export type AnimatableNode<T extends LayoutNode> = T & {
| { tracks: AnimationTrack[] }
| LayerAnimation[]
)[]
- ): AnimatableNode<T>;
+ ): AnimatableNode<T, TCap>;
pinToLandmark(
target:
| LandmarkCoordinateSignals
@@ -2129,7 +2154,7 @@ export type AnimatableNode<T extends LayoutNode> = T & {
screenY?: number;
},
options?: PinToLandmarkOptions,
- ): AnimatableNode<T>;
+ ): AnimatableNode<T, TCap>;
pinToObject(
target:
| ObjectTrackSignals
@@ -2142,7 +2167,7 @@ export type AnimatableNode<T extends LayoutNode> = T & {
screenY?: number;
},
options?: PinToObjectOptions,
- ): AnimatableNode<T>;
+ ): AnimatableNode<T, TCap>;
/**
* Track matte: `matte` (any layer) masks this one by its alpha or
* brightness. It is laid out like a sibling (same parent) and timed with
@@ -2150,22 +2175,22 @@ export type AnimatableNode<T extends LayoutNode> = T & {
* the matte for wipes and reveals: text through a sliding box, video
* inside type, an iris circle.
*/
- withMatte(matte: LayoutNode, mode?: MatteMode): AnimatableNode<T>;
+ withMatte(matte: LayoutNode, mode?: MatteMode): AnimatableNode<T, TCap>;
/** Alias of {@link withMatte}. */
- withMask(mask: LayoutNode, mode?: MatteMode): AnimatableNode<T>;
- withPbrGlass(options?: Record<string, unknown>): AnimatableNode<T>;
+ withMask(mask: LayoutNode, mode?: MatteMode): AnimatableNode<T, TCap>;
+ withPbrGlass(options?: Record<string, unknown>): AnimatableNode<T, TCap>;
deformWithAudio(
config?: MeshAudioDeformConfig | Record<string, unknown>,
- ): AnimatableNode<T>;
- withCrop(cropConfig: CropProps | Crop): AnimatableNode<T>;
+ ): AnimatableNode<T, TCap>;
+ withCrop(cropConfig: CropProps | Crop): AnimatableNode<T, TCap>;
/** Runs vision on this node's rendered output (see `Vision` for options and modes). */
- withVision(config?: VisionProps | Vision): AnimatableNode<T>;
- withRelighting(options?: NormalRelightingOptions): AnimatableNode<T>;
- relight(options?: NormalRelightingOptions): AnimatableNode<T>;
- withDeflicker(options?: DeflickerOptions): AnimatableNode<T>;
- apply(effect: Effect<object>): AnimatableNode<T>;
- withEffect(effect: Effect<object>): AnimatableNode<T>;
- withEffects(effects: Effect<object>[]): AnimatableNode<T>;
+ withVision(config?: VisionProps | Vision): AnimatableNode<T, TCap>;
+ withRelighting(options?: NormalRelightingOptions): AnimatableNode<T, TCap>;
+ relight(options?: NormalRelightingOptions): AnimatableNode<T, TCap>;
+ withDeflicker(options?: DeflickerOptions): AnimatableNode<T, TCap>;
+ apply(effect: CompatibleEffect<TCap>): AnimatableNode<T, TCap>;
+ withEffect(effect: CompatibleEffect<TCap>): AnimatableNode<T, TCap>;
+ withEffects(effects: CompatibleEffect<TCap>[]): AnimatableNode<T, TCap>;
section(
targetOrOptions?: ObjectTrackSignals | SectionOptions,
options?: SectionOptions,
@@ -2173,15 +2198,18 @@ export type AnimatableNode<T extends LayoutNode> = T & {
blurRegion(
trackTarget: ObjectTrackSignals,
options?: Partial<BlurProps>,
- ): AnimatableNode<T>;
+ ): AnimatableNode<T, TCap>;
withBlurRegion(
trackTarget: ObjectTrackSignals,
options?: Partial<BlurProps>,
- ): AnimatableNode<T>;
+ ): AnimatableNode<T, TCap>;
};
-function withAnimation<T extends LayoutNode>(node: T): AnimatableNode<T> {
- const target = node as AnimatableNode<T>;
+function withAnimation<
+ T extends LayoutNode,
+ TCap extends NodeCapability = "visual",
+>(node: T): AnimatableNode<T, TCap> {
+ const target = node as AnimatableNode<T, TCap>;
Object.defineProperty(target, "animate", {
value: (
...anims: (
@@ -2470,7 +2498,7 @@ export const Layer = {
video: (
src: string,
options: Partial<MediaNode> = {},
- ): AnimatableNode<MediaNode> =>
+ ): AnimatableNode<MediaNode, "hybrid"> =>
withAnimation({
id: options.id ?? autoId("video"),
kind: "media",
@@ -2482,7 +2510,7 @@ export const Layer = {
image: (
src: string,
options: Partial<MediaNode> = {},
- ): AnimatableNode<MediaNode> => {
+ ): AnimatableNode<MediaNode, "visual"> => {
if (typeof src === "string") {
if (
/\.(json|lottie)(\?.*)?$/i.test(src) ||
@@ -2513,7 +2541,7 @@ export const Layer = {
svg: (
src: string,
options: Partial<MediaNode> = {},
- ): AnimatableNode<MediaNode> =>
+ ): AnimatableNode<MediaNode, "visual"> =>
withAnimation({
id: options.id ?? autoId("svg"),
kind: "media",
@@ -2525,7 +2553,7 @@ export const Layer = {
lottie: (
src: string,
options: Partial<MediaNode> = {},
- ): AnimatableNode<MediaNode> =>
+ ): AnimatableNode<MediaNode, "visual"> =>
withAnimation({
id: options.id ?? autoId("lottie"),
kind: "media",
@@ -2537,7 +2565,7 @@ export const Layer = {
audio: (
src: string,
options: Partial<MediaNode> = {},
- ): AnimatableNode<MediaNode> =>
+ ): AnimatableNode<MediaNode, "audio"> =>
withAnimation({
id: options.id ?? autoId("audio"),
kind: "media",
@@ -2553,7 +2581,7 @@ export const Layer = {
| (string | TextSpan)[]
| Partial<TextNode>,
maybeOptions: Partial<TextNode> = {},
- ): AnimatableNode<TextNode> => {
+ ): AnimatableNode<TextNode, "visual"> => {
const isArray = Array.isArray(contentOrOptions);
const isObj =
!isArray &&
diff --git a/packages/framefields/src/type-safety.test.ts b/packages/framefields/src/type-safety.test.ts
index 6d587761..3ff2ff78 100644
--- a/packages/framefields/src/type-safety.test.ts
+++ b/packages/framefields/src/type-safety.test.ts
@@ -1,6 +1,14 @@
import { describe, expect, expectTypeOf, it } from "vitest";
import {
type AnimatableNode,
+ type AnyAudioEffect,
+ type AnyEffect,
+ type AnyVisualEffect,
+ AudioCompressor,
+ AudioDelay,
+ Blur,
+ type CompatibleEffect,
+ FilmGrain,
type Fps,
type FrameIndex,
fps,
@@ -12,9 +20,11 @@ import {
isFrameIndex,
isNormalized,
Layer,
+ Levels,
type MediaNode,
type Milliseconds,
ms,
+ type NodeCapability,
type NodeId,
type Normalized,
nodeId,
@@ -88,10 +98,82 @@ describe("Type Safety & Branded Types (Phase 1)", () => {
it("preserves typed AnimatableNode without index signature", () => {
const video = Layer.video("sample.mp4");
- expectTypeOf(video).toMatchTypeOf<AnimatableNode<MediaNode>>();
+ expectTypeOf(video).toMatchTypeOf<AnimatableNode<MediaNode, "hybrid">>();
// Verify apply method accepts typed Effect instances
const withEff = video.apply(new Vignette({ strength: 10 }));
- expectTypeOf(withEff).toMatchTypeOf<AnimatableNode<MediaNode>>();
+ expectTypeOf(withEff).toMatchTypeOf<AnimatableNode<MediaNode, "hybrid">>();
+ });
+});
+
+describe("Discriminated Effects & Port Capabilities (Phase 2)", () => {
+ it("distinguishes visual and audio effects by op and domain", () => {
+ const blur = new Blur({ strength: 10 });
+ expect(blur.op).toBe("Blur");
+ expect(blur.domain).toBe("visual");
+ expectTypeOf(blur.op).toEqualTypeOf<"Blur">();
+ expectTypeOf(blur.domain).toEqualTypeOf<"visual">();
+
+ const compressor = new AudioCompressor({ threshold: -18 });
+ expect(compressor.op).toBe("AudioCompressor");
+ expect(compressor.domain).toBe("audio");
+ expectTypeOf(compressor.op).toEqualTypeOf<"AudioCompressor">();
+ expectTypeOf(compressor.domain).toEqualTypeOf<"audio">();
+
+ const levels = new Levels();
+ expect(levels.op).toBe("Levels");
+ expect(levels.domain).toBe("visual");
+ expectTypeOf(levels.op).toEqualTypeOf<"Levels">();
+ expectTypeOf(levels.domain).toEqualTypeOf<"visual">();
+ });
+
+ it("narrows effect instances within AnyEffect discriminated union", () => {
+ const effect: AnyEffect = new AudioDelay({ delayTime: 0.12 });
+
+ if (effect.domain === "audio") {
+ expectTypeOf(effect).toMatchTypeOf<AnyAudioEffect>();
+ } else {
+ expectTypeOf(effect).toMatchTypeOf<AnyVisualEffect>();
+ }
+
+ if (effect.op === "AudioDelay") {
+ expect(effect.delayTime).toBe(0.12);
+ }
+ });
+
+ it("enforces capability-safe apply on layers", () => {
+ expectTypeOf<NodeCapability>().toEqualTypeOf<
+ "visual" | "audio" | "hybrid"
+ >();
+
+ const audioLayer = Layer.audio("soundtrack.mp3");
+ expectTypeOf<Parameters<typeof audioLayer.apply>[0]>().toEqualTypeOf<
+ CompatibleEffect<"audio">
+ >();
+
+ const imageLayer = Layer.image("banner.png");
+ expectTypeOf<Parameters<typeof imageLayer.apply>[0]>().toEqualTypeOf<
+ CompatibleEffect<"visual">
+ >();
+
+ const videoLayer = Layer.video("clip.mp4");
+ expectTypeOf<Parameters<typeof videoLayer.apply>[0]>().toEqualTypeOf<
+ CompatibleEffect<"hybrid">
+ >();
+
+ // Video accepts both visual and audio effects
+ const v1 = videoLayer.apply(new Blur({ strength: 5 }));
+ const v2 = v1.apply(new AudioCompressor({ threshold: -12 }));
+ expect(v2.effects?.length).toBe(2);
+
+ // Audio accepts audio effects
+ const a1 = audioLayer.apply(new AudioCompressor());
+ const a2 = a1.apply(new AudioDelay({ delayTime: 0.05 }));
+ expect(a2.effects?.length).toBe(2);
+
+ // Image accepts visual effects
+ const img1 = imageLayer.apply(new FilmGrain({ strength: 10 }));
+ const img2 = img1.apply(new Vignette({ strength: 40 }));
+ expect(img2.effects?.length).toBe(2);
});
});
diff --git a/plugins/framefields/skills/framefields-effects/references/effects-catalog.md b/plugins/framefields/skills/framefields-effects/references/effects-catalog.md
index 00030fff..837292ad 100644
--- a/plugins/framefields/skills/framefields-effects/references/effects-catalog.md
+++ b/plugins/framefields/skills/framefields-effects/references/effects-catalog.md
@@ -3,7 +3,7 @@
> Generated by `pnpm run sync:effects-catalog` from the node schemas (via `pnpm run generate:effects`) and `packages/framefields/src/effects/classes.ts`.
> Do not edit by hand — a stale catalog fails `pnpm run check:plugins`.
-67 effect classes are available from the package root and the `/effects` subpath:
+46 effect classes are available from the package root and the `/effects` subpath:
```ts
import { Blur, Curves, FilmGrain } from "framefields";
@@ -67,27 +67,6 @@ Set `FRAMEFIELDS_STRICT_PROPS=1` to make an unknown prop or an out-of-range valu
| `Toon` | `Toon` | `levels`, `edgeThreshold`, `edgeWidth`, `edgeColor`, `saturation` |
| `Trails` | `Trails` | `decay`, `mode`, `zoom`, `rotation`, `offsetX`, `offsetY`, `hueShift`, `warmup` |
| `Vignette` | `Vignette` | `strength`, `radius`, `softness`, `roundness`, `centerX`, `centerY` |
-| `Levels` | `Levels` | `master`, `red`, `green`, `blue` |
-| `FilmGrain` | `FilmGrain` | `strength`, `size`, `monochrome`, `animated`, `speed`, `shadows`, `midtones`, `highlights` |
-| `AudioSignalExtractor` | `AudioSignalExtractor` | `extractionMode`, `attackMs`, `releaseMs`, `sensitivity`, `noiseFloorDb`, `dynamicRangeDb`, `autoRange`, `smoothing`, `curve`, `beatThreshold`, `beatDecayMs`, `previewMode`, `nodeId` |
-| `Curves` | `Curves` | `curveType`, `master`, `red`, `green`, `blue`, `hueVsHue`, `hueVsSat`, `lumVsSat`, `satVsSat` |
-| `SelectiveColor` | `SelectiveColor` | `method`, `reds`, `yellows`, `greens`, `cyans`, `blues`, `magentas`, `whites`, `neutrals`, `blacks` |
-| `GradientMap` | `GradientMap` | `stops`, `smooth`, `dither`, `opacity` |
-| `ShadowsHighlights` | `ShadowsHighlights` | `shadowAmount`, `shadowTonalWidth`, `shadowRadius`, `highlightAmount`, `highlightTonalWidth`, `highlightRadius`, `colorCorrection`, `midtoneContrast` |
-| `ApplyLUT` | `ApplyLUT` | `lutUrl`, `intensity` |
-| `UnsharpMask` | `UnsharpMask` | `amount`, `radius`, `threshold` |
-| `HighPass` | `HighPass` | `radius`, `contrastBoost`, `monochrome` |
-| `HalftoneScreen` | `HalftoneScreen` | `mode`, `dotShape`, `frequency`, `angle`, `contrast`, `dotColor`, `paperColor`, `smooth`, `invert`, `cyanAngle`, `magentaAngle`, `yellowAngle`, `blackAngle`, `opacity` |
-| `TileOffset` | `TileOffset` | `offsetX`, `offsetY`, `wrap`, `edgeMode` |
-| `MotionBlur` | `MotionBlur` | `shutterAngle`, `samples`, `maxVelocity`, `shutterCurve`, `depthAware` |
-| `SSAO` | `SSAO` | `radius`, `bias`, `intensity`, `kernelSamples`, `blurRadius` |
-| `PBRGlass` | `PBRGlass` | `ior`, `roughness`, `transmission`, `dispersion`, `fresnelPower`, `tintColor` |
-| `DepthOfField` | `DepthOfField` | `focusDistance`, `focalLength`, `aperture`, `maxBlur`, `quality` |
-| `Crop` | `Crop` | `cropType`, `leftPercentage`, `topPercentage`, `widthPercentage`, `heightPercentage`, `roundness`, `pathPoints`, `mode` |
-| `Vision` | `Vision` | `enableDetection`, `enableSegmentation`, `enablePose`, `enableMatte`, `classes`, `confidence`, `variant`, `mode`, `matteSource`, `maxMissedFrames`, `modelsDir`, `baseUrl`, `maskThreshold`, `featherRadius`, `keyBackground`, `backgroundKeyThreshold`, `visionBundle` |
-| `Relight3D` | `Relight3D` | `lightType`, `intensity`, `lightPosX`, `lightPosY`, `lightPosZ`, `lightRadius`, `spotConeAngle`, `specularRoughness`, `specularStrength`, `metallic`, `ambientIntensity`, `volumetricDensity`, `depthScale`, `depthInvert`, `lightColor`, `ambientColor`, `normalMap` |
-| `TemporalDeflicker` | `TemporalDeflicker` | `blendWeight`, `disocclusionThreshold`, `maxMotionPixels`, `scale`, `windowSize` |
-| `Modulate` | `Modulate` | `hue`, `brightness`, `contrast`, `exposure`, `saturation`, `sepia` |
## Prop defaults
@@ -892,393 +871,6 @@ new Vignette({ strength: 50, radius: 1, softness: 0.5 });
| `centerX` | `EffectProp<number>` | `0.5` | Range 0 to 1. The X coordinate of the vignette center. |
| `centerY` | `EffectProp<number>` | `0.5` | Range 0 to 1. The Y coordinate of the vignette center. |
-### Levels
-
-```ts
-import { Levels } from "framefields/effects";
-
-new Levels({ /* props */ });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `master` | `LevelChannel` | `{ ...defaultChannel }` |
-| `red` | `LevelChannel` | `{ ...defaultChannel }` |
-| `green` | `LevelChannel` | `{ ...defaultChannel }` |
-| `blue` | `LevelChannel` | `{ ...defaultChannel }` |
-
-### FilmGrain
-
-```ts
-import { FilmGrain } from "framefields/effects";
-
-new FilmGrain({ strength: 15, size: 1.5, monochrome: true });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `strength` | `EffectProp<number>` | `15` |
-| `size` | `EffectProp<number>` | `1.5` |
-| `monochrome` | `boolean` | `true` |
-| `animated` | `boolean` | `true` |
-| `speed` | `EffectProp<number>` | `50` |
-| `shadows` | `EffectProp<number>` | `0.2` |
-| `midtones` | `EffectProp<number>` | `1.0` |
-| `highlights` | `EffectProp<number>` | `0.2` |
-
-### AudioSignalExtractor
-
-```ts
-import { AudioSignalExtractor } from "framefields/effects";
-
-new AudioSignalExtractor({ extractionMode: "rms_envelope", attackMs: 10, releaseMs: 120 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `extractionMode` | `\| "rms_envelope" \| "transient_beat" \| "sub_bass" \| "bass" \| "mid" \| "high" \| "spectral_flux"` | `"rms_envelope"` |
-| `attackMs` | `number` | `10` |
-| `releaseMs` | `number` | `120` |
-| `sensitivity` | `number` | `1.0` |
-| `noiseFloorDb` | `number` | `-48` |
-| `dynamicRangeDb` | `number` | `48` |
-| `autoRange` | `boolean` | `true` |
-| `smoothing` | `number` | `0.15` |
-| `curve` | `"linear" \| "exponential" \| "logarithmic" \| "square" \| "smoothstep"` | `"linear"` |
-| `beatThreshold` | `number` | `0.08` |
-| `beatDecayMs` | `number` | `80` |
-| `previewMode` | `"waveform" \| "envelope" \| "beat_markers" \| "spectrum"` | `"envelope"` |
-| `nodeId` | `string` | `"audio_extractor"` |
-
-### Curves
-
-```ts
-import { Curves } from "framefields/effects";
-
-new Curves({ curveType: "rgb" });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `curveType` | `"rgb" \| "hue-vs-hue" \| "hue-vs-sat" \| "lum-vs-sat" \| "sat-vs-sat"` | `"rgb"` |
-| `master` | `CurvesChannelPoint[]` | — |
-| `red` | `CurvesChannelPoint[]` | — |
-| `green` | `CurvesChannelPoint[]` | — |
-| `blue` | `CurvesChannelPoint[]` | — |
-| `hueVsHue` | `CurvesChannelPoint[]` | — |
-| `hueVsSat` | `CurvesChannelPoint[]` | — |
-| `lumVsSat` | `CurvesChannelPoint[]` | — |
-| `satVsSat` | `CurvesChannelPoint[]` | — |
-
-### SelectiveColor
-
-```ts
-import { SelectiveColor } from "framefields/effects";
-
-new SelectiveColor({ method: "Relative" });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `method` | `"Relative" \| "Absolute"` | `"Relative"` |
-| `reds` | `Partial<SelectiveColorAdjustment>` | — |
-| `yellows` | `Partial<SelectiveColorAdjustment>` | — |
-| `greens` | `Partial<SelectiveColorAdjustment>` | — |
-| `cyans` | `Partial<SelectiveColorAdjustment>` | — |
-| `blues` | `Partial<SelectiveColorAdjustment>` | — |
-| `magentas` | `Partial<SelectiveColorAdjustment>` | — |
-| `whites` | `Partial<SelectiveColorAdjustment>` | — |
-| `neutrals` | `Partial<SelectiveColorAdjustment>` | — |
-| `blacks` | `Partial<SelectiveColorAdjustment>` | — |
-
-### GradientMap
-
-```ts
-import { GradientMap } from "framefields/effects";
-
-new GradientMap({ stops: defaultStops, smooth: true, dither: true });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `stops` | `GradientMapStop[]` | `defaultStops` |
-| `smooth` | `boolean` | `true` |
-| `dither` | `boolean` | `true` |
-| `opacity` | `EffectProp<number>` | `1.0` |
-
-### ShadowsHighlights
-
-```ts
-import { ShadowsHighlights } from "framefields/effects";
-
-new ShadowsHighlights({ shadowAmount: 0, shadowTonalWidth: 50, shadowRadius: 30 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `shadowAmount` | `EffectProp<number>` | `0` |
-| `shadowTonalWidth` | `EffectProp<number>` | `50` |
-| `shadowRadius` | `EffectProp<number>` | `30` |
-| `highlightAmount` | `EffectProp<number>` | `0` |
-| `highlightTonalWidth` | `EffectProp<number>` | `50` |
-| `highlightRadius` | `EffectProp<number>` | `30` |
-| `colorCorrection` | `EffectProp<number>` | `0` |
-| `midtoneContrast` | `EffectProp<number>` | `0` |
-
-### ApplyLUT
-
-```ts
-import { ApplyLUT } from "framefields/effects";
-
-new ApplyLUT({ lutUrl: "", intensity: 1.0 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `lutUrl` | `string` | `""` |
-| `intensity` | `EffectProp<number>` | `1.0` |
-
-### UnsharpMask
-
-```ts
-import { UnsharpMask } from "framefields/effects";
-
-new UnsharpMask({ amount: 100, radius: 1.5, threshold: 3 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `amount` | `EffectProp<number>` | `100` |
-| `radius` | `EffectProp<number>` | `1.5` |
-| `threshold` | `EffectProp<number>` | `3` |
-
-### HighPass
-
-```ts
-import { HighPass } from "framefields/effects";
-
-new HighPass({ radius: 3.0, contrastBoost: 1.0, monochrome: true });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `radius` | `EffectProp<number>` | `3.0` |
-| `contrastBoost` | `EffectProp<number>` | `1.0` |
-| `monochrome` | `boolean` | `true` |
-
-### HalftoneScreen
-
-```ts
-import { HalftoneScreen } from "framefields/effects";
-
-new HalftoneScreen({ mode: "Monochrome", dotShape: "Circle", frequency: 30 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `mode` | `HalftoneMode` | `"Monochrome"` |
-| `dotShape` | `HalftoneDotShape` | `"Circle"` |
-| `frequency` | `EffectProp<number>` | `30` |
-| `angle` | `EffectProp<number>` | `45` |
-| `contrast` | `EffectProp<number>` | `1.0` |
-| `dotColor` | `string` | `"#000000"` |
-| `paperColor` | `string` | `"#ffffff"` |
-| `smooth` | `boolean` | `true` |
-| `invert` | `boolean` | `false` |
-| `cyanAngle` | `EffectProp<number>` | `15` |
-| `magentaAngle` | `EffectProp<number>` | `75` |
-| `yellowAngle` | `EffectProp<number>` | `0` |
-| `blackAngle` | `EffectProp<number>` | `45` |
-| `opacity` | `EffectProp<number>` | `1.0` |
-
-### TileOffset
-
-```ts
-import { TileOffset } from "framefields/effects";
-
-new TileOffset({ offsetX: 0, offsetY: 0, wrap: true });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `offsetX` | `EffectProp<number>` | `0` |
-| `offsetY` | `EffectProp<number>` | `0` |
-| `wrap` | `boolean` | `true` |
-| `edgeMode` | `TileOffsetEdgeMode` | `"wrap"` |
-
-### MotionBlur
-
-```ts
-import { MotionBlur } from "framefields/effects";
-
-new MotionBlur({ shutterAngle: 180, samples: 16, maxVelocity: 64 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `shutterAngle` | `EffectProp<number>` | `180` |
-| `samples` | `EffectProp<number>` | `16` |
-| `maxVelocity` | `EffectProp<number>` | `64` |
-| `shutterCurve` | `"box" \| "gaussian" \| "triangle"` | `"gaussian"` |
-| `depthAware` | `boolean` | `true` |
-
-### SSAO
-
-```ts
-import { SSAO } from "framefields/effects";
-
-new SSAO({ radius: 45, bias: 0.025, intensity: 1.5 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `radius` | `EffectProp<number>` | `45` |
-| `bias` | `EffectProp<number>` | `0.025` |
-| `intensity` | `EffectProp<number>` | `1.5` |
-| `kernelSamples` | `EffectProp<number>` | `16` |
-| `blurRadius` | `EffectProp<number>` | `4` |
-
-### PBRGlass
-
-```ts
-import { PBRGlass } from "framefields/effects";
-
-new PBRGlass({ ior: 1.49, roughness: 0.15, transmission: 0.92 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `ior` | `EffectProp<number>` | `1.49` |
-| `roughness` | `EffectProp<number>` | `0.15` |
-| `transmission` | `EffectProp<number>` | `0.92` |
-| `dispersion` | `EffectProp<number>` | `0.015` |
-| `fresnelPower` | `EffectProp<number>` | `5.0` |
-| `tintColor` | `EffectProp<string>` | `"#ffffff"` |
-
-### DepthOfField
-
-```ts
-import { DepthOfField } from "framefields/effects";
-
-new DepthOfField({ focusDistance: 500, focalLength: 50, aperture: 2.8 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `focusDistance` | `EffectProp<number>` | `500` |
-| `focalLength` | `EffectProp<number>` | `50` |
-| `aperture` | `EffectProp<number>` | `2.8` |
-| `maxBlur` | `EffectProp<number>` | `16` |
-| `quality` | `"low" \| "medium" \| "high" \| "ultra"` | `"high"` |
-
-### Crop
-
-```ts
-import { Crop } from "framefields/effects";
-
-new Crop({ cropType: "rect", leftPercentage: 0, topPercentage: 0 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `cropType` | `"rect" \| "path"` | `"rect"` |
-| `leftPercentage` | `EffectProp<number>` | `0` |
-| `topPercentage` | `EffectProp<number>` | `0` |
-| `widthPercentage` | `EffectProp<number>` | `100` |
-| `heightPercentage` | `EffectProp<number>` | `100` |
-| `roundness` | `EffectProp<number>` | `0` |
-| `pathPoints` | `{ x: number; y: number }[]` | — |
-| `mode` | `"cropped" \| "rest"` | — |
-
-### Vision
-
-```ts
-import { Vision } from "framefields/effects";
-
-new Vision({ confidence: 0.3, variant: "s", mode: "passthrough" });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `enableDetection` | `boolean` | — |
-| `enableSegmentation` | `boolean` | — |
-| `enablePose` | `boolean` | — |
-| `enableMatte` | `boolean` | — |
-| `classes` | `readonly string[]` | — |
-| `confidence` | `number` | `0.3` |
-| `variant` | `"t" \| "s" \| "m"` | `"s"` |
-| `mode` | `\| "passthrough" \| "mask" \| "matte" \| "crop" \| "skeleton" \| "boxes" \| "tracking"` | `"passthrough"` |
-| `matteSource` | `"instance" \| "selfie"` | `"instance"` |
-| `maxMissedFrames` | `number` | — |
-| `modelsDir` | `string` | — |
-| `baseUrl` | `string` | — |
-| `maskThreshold` | `number` | — |
-| `featherRadius` | `number` | — |
-| `keyBackground` | `boolean` | — |
-| `backgroundKeyThreshold` | `number` | — |
-| `visionBundle` | `unknown` | — |
-
-### Relight3D
-
-```ts
-import { Relight3D } from "framefields/effects";
-
-new Relight3D({ lightType: "Point", intensity: 1.0, lightPosX: 0.5 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `lightType` | `"Point" \| "Spot" \| "Directional" \| "Rim"` | `"Point"` |
-| `intensity` | `EffectProp<number>` | `1.0` |
-| `lightPosX` | `EffectProp<number>` | `0.5` |
-| `lightPosY` | `EffectProp<number>` | `0.5` |
-| `lightPosZ` | `EffectProp<number>` | `0.3` |
-| `lightRadius` | `EffectProp<number>` | `0.8` |
-| `spotConeAngle` | `EffectProp<number>` | `45` |
-| `specularRoughness` | `EffectProp<number>` | `0.35` |
-| `specularStrength` | `EffectProp<number>` | `0.7` |
-| `metallic` | `EffectProp<number>` | `0.0` |
-| `ambientIntensity` | `EffectProp<number>` | `0.4` |
-| `volumetricDensity` | `EffectProp<number>` | `0.2` |
-| `depthScale` | `EffectProp<number>` | `1.0` |
-| `depthInvert` | `boolean` | `false` |
-| `lightColor` | `string` | `"#ffffff"` |
-| `ambientColor` | `string` | `"#ffffff"` |
-| `normalMap` | `unknown` | — |
-
-### TemporalDeflicker
-
-```ts
-import { TemporalDeflicker } from "framefields/effects";
-
-new TemporalDeflicker({ blendWeight: 0.35, disocclusionThreshold: 0.15, maxMotionPixels: 64.0 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `blendWeight` | `EffectProp<number>` | `0.35` |
-| `disocclusionThreshold` | `EffectProp<number>` | `0.15` |
-| `maxMotionPixels` | `EffectProp<number>` | `64.0` |
-| `scale` | `number` | `0.5` |
-| `windowSize` | `number` | `2` |
-
-### Modulate
-
-```ts
-import { Modulate } from "framefields/effects";
-
-new Modulate({ hue: 0, brightness: 1.0, contrast: 1.0 });
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `hue` | `EffectProp<number>` | `0` |
-| `brightness` | `EffectProp<number>` | `1.0` |
-| `contrast` | `EffectProp<number>` | `1.0` |
-| `exposure` | `EffectProp<number>` | `0.0` |
-| `saturation` | `EffectProp<number>` | `1.0` |
-| `sepia` | `EffectProp<number>` | `0.0` |
-
## Node packages
Beyond these classes, the engine ships node plugins under `nodes/` (audio DSP, generators,
diff --git a/scripts/generate-effects.mts b/scripts/generate-effects.mts
index e1f790e4..c0a12642 100644
--- a/scripts/generate-effects.mts
+++ b/scripts/generate-effects.mts
@@ -508,13 +508,20 @@ function emitClasses(effects: EffectModel[], ctx: Context): string {
}
out.push("};", "");
+ const domain = effect.manifest.kind === "audio" ? "audio" : "visual";
if (effect.manifest.custom) {
out.push(
`/** @internal Extended by \`effects/custom/${customFile(effect)}\`, which exports \`${effect.className}\`. */`,
);
}
- out.push(`export class ${name} extends Effect<${props}> {`);
- out.push(`\tpublic readonly op = ${literal(effect.op)};`, "");
+ out.push(
+ `export class ${name} extends Effect<${props}, ${literal(effect.op)}, ${literal(domain)}> {`,
+ );
+ out.push(`\tpublic readonly op = ${literal(effect.op)} as const;`);
+ out.push(
+ `\tpublic override readonly domain = ${literal(domain)} as const;`,
+ "",
+ );
for (const field of effect.fields) {
const type = field.valueType + (field.hasDefault ? "" : " | undefined");
out.push(`\tpublic declare ${key(field.key)}: ${type};`);
@@ -585,6 +592,13 @@ function emitIndex(effects: EffectModel[], ctx: Context): string {
const interfaces = [...ctx.interfaces.keys()]
.sort()
.map((name) => `type ${name}`);
+ const visualEffects = effects.filter((e) => e.manifest.kind !== "audio");
+ const audioEffects = effects.filter((e) => e.manifest.kind === "audio");
+ const visualUnion =
+ visualEffects.map((e) => e.className).join(" | ") || "never";
+ const audioUnion =
+ audioEffects.map((e) => e.className).join(" | ") || "never";
+
return [
BANNER,
...importsFor(effects, "export"),
@@ -594,6 +608,15 @@ function emitIndex(effects: EffectModel[], ctx: Context): string {
'export { effectMeta } from "./meta.js";',
'export { effectFactories } from "./registry.js";',
"",
+ "/** Discriminated unions of all generated effects by domain. */",
+ `export type AnyGeneratedVisualEffect = ${visualUnion};`,
+ `export type AnyGeneratedAudioEffect = ${audioUnion};`,
+ "export type AnyGeneratedEffect = AnyGeneratedVisualEffect | AnyGeneratedAudioEffect;",
+ "",
+ "export interface GeneratedEffectConfigMap {",
+ ...effects.map((e) => `\t${literal(e.op)}: ${e.className}Props;`),
+ "}",
+ "",
].join("\n");
}