refactor: make mask renderer dispatch explicit

Made-with: Cursor

apps/web/src/masks/definitions/cinematic-bars.ts

@@ -71,7 +71,7 @@ function buildBandPath({
 	return path;
 }
 
-export const cinematicBarsMaskDefinition: MaskDefinition<RectangleMaskParams> = {
+export const cinematicBarsMaskDefinition: MaskDefinition<"cinematic-bars"> = {
 	type: "cinematic-bars",
 	name: "Cinematic Bars",
 	features: {
@@ -94,8 +94,10 @@ export const cinematicBarsMaskDefinition: MaskDefinition<RectangleMaskParams> =
 	},
 	computeParamUpdate: computeBoxMaskParamUpdate,
 	renderer: {
+		body: {
+			kind: "fillPath",
 			buildPath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const centerX = width / 2 + params.centerX * width;
 				const centerY = height / 2 + params.centerY * height;
 				const maskWidth = Math.max(params.width * width, width);
@@ -110,8 +112,11 @@ export const cinematicBarsMaskDefinition: MaskDefinition<RectangleMaskParams> =
 					rotationRad,
 				});
 			},
+		},
+		stroke: {
+			kind: "strokeFromPath",
 			buildStrokePath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const centerX = width / 2 + params.centerX * width;
 				const centerY = height / 2 + params.centerY * height;
 				const rotationRad = (params.rotation * Math.PI) / 180;
@@ -123,7 +128,10 @@ export const cinematicBarsMaskDefinition: MaskDefinition<RectangleMaskParams> =
 				return buildBandPath({
 					centerX,
 					centerY,
-				halfWidth: Math.max((Math.max(params.width * width, width) / 2) + offset, 1),
+					halfWidth: Math.max(
+						Math.max(params.width * width, width) / 2 + offset,
+						1,
+					),
 					halfHeight: Math.max(
 						(Math.max(params.height, 0.01) * height) / 2 + offset,
 						1,
@@ -132,4 +140,5 @@ export const cinematicBarsMaskDefinition: MaskDefinition<RectangleMaskParams> =
 				});
 			},
 		},
+	},
 };

apps/web/src/masks/definitions/custom.ts

@@ -308,7 +308,7 @@ function computeCustomMaskParamUpdate({
 	};
 }
 
-export const customMaskDefinition: MaskDefinition<CustomMaskParams> = {
+export const customMaskDefinition: MaskDefinition<"custom"> = {
 	type: "custom",
 	name: "Custom",
 	features: {
@@ -447,8 +447,10 @@ export const customMaskDefinition: MaskDefinition<CustomMaskParams> = {
 		return params.closed;
 	},
 	renderer: {
+		body: {
+			kind: "fillPath",
 			buildPath({ resolvedParams, width, height }) {
-			const params = resolvedParams as CustomMaskParams;
+				const params = resolvedParams;
 				const points = params.path;
 				if (!params.closed) {
 					return new Path2D();
@@ -470,8 +472,11 @@ export const customMaskDefinition: MaskDefinition<CustomMaskParams> = {
 					closed: true,
 				});
 			},
+		},
+		stroke: {
+			kind: "renderStroke",
 			renderStroke({ resolvedParams, ctx, width, height }) {
-			const params = resolvedParams as CustomMaskParams;
+				const params = resolvedParams;
 				if (!params.closed) {
 					return;
 				}
@@ -514,6 +519,7 @@ export const customMaskDefinition: MaskDefinition<CustomMaskParams> = {
 				ctx.restore();
 			},
 		},
+	},
 };
 
 export function appendPointToCustomMask({

apps/web/src/masks/definitions/diamond.ts

@@ -1,4 +1,4 @@
-import type { MaskDefinition, RectangleMaskParams } from "@/masks/types";
+import type { MaskDefinition } from "@/masks/types";
 import {
 	BOX_LIKE_MASK_PARAMS,
 	buildBoxMaskInteraction,
@@ -45,7 +45,7 @@ function buildDiamondPath({
 	return path;
 }
 
-export const diamondMaskDefinition: MaskDefinition<RectangleMaskParams> = {
+export const diamondMaskDefinition: MaskDefinition<"diamond"> = {
 	type: "diamond",
 	name: "Diamond",
 	features: {
@@ -68,8 +68,10 @@ export const diamondMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 	},
 	computeParamUpdate: computeBoxMaskParamUpdate,
 	renderer: {
+		body: {
+			kind: "fillPath",
 			buildPath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				return buildDiamondPath({
@@ -80,8 +82,11 @@ export const diamondMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 					rotationRad,
 				});
 			},
+		},
+		stroke: {
+			kind: "strokeFromPath",
 			buildStrokePath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				const offset = getStrokeOffset({
@@ -97,4 +102,5 @@ export const diamondMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 				});
 			},
 		},
+	},
 };

apps/web/src/masks/definitions/ellipse.ts

@@ -1,4 +1,4 @@
-import type { MaskDefinition, RectangleMaskParams } from "@/masks/types";
+import type { MaskDefinition } from "@/masks/types";
 import {
 	BOX_LIKE_MASK_PARAMS,
 	buildBoxMaskInteraction,
@@ -8,7 +8,7 @@ import {
 	getStrokeOffset,
 } from "./box-like";
 
-export const ellipseMaskDefinition: MaskDefinition<RectangleMaskParams> = {
+export const ellipseMaskDefinition: MaskDefinition<"ellipse"> = {
 	type: "ellipse",
 	name: "Ellipse",
 	features: {
@@ -35,8 +35,10 @@ export const ellipseMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 	},
 	computeParamUpdate: computeBoxMaskParamUpdate,
 	renderer: {
+		body: {
+			kind: "fillPath",
 			buildPath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				const path = new Path2D();
@@ -51,8 +53,11 @@ export const ellipseMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 				);
 				return path;
 			},
+		},
+		stroke: {
+			kind: "strokeFromPath",
 			buildStrokePath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				const offset = getStrokeOffset({
@@ -72,4 +77,5 @@ export const ellipseMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 				return path;
 			},
 		},
+	},
 };

apps/web/src/masks/definitions/heart.ts

@@ -1,4 +1,4 @@
-import type { MaskDefinition, RectangleMaskParams } from "@/masks/types";
+import type { MaskDefinition } from "@/masks/types";
 import {
 	BOX_LIKE_MASK_PARAMS,
 	buildBoxMaskInteraction,
@@ -78,7 +78,7 @@ function buildHeartPath({
 	return path;
 }
 
-export const heartMaskDefinition: MaskDefinition<RectangleMaskParams> = {
+export const heartMaskDefinition: MaskDefinition<"heart"> = {
 	type: "heart",
 	name: "Heart",
 	features: {
@@ -110,8 +110,10 @@ export const heartMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 	},
 	computeParamUpdate: computeBoxMaskParamUpdate,
 	renderer: {
+		body: {
+			kind: "fillPath",
 			buildPath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				return buildHeartPath({
@@ -122,8 +124,11 @@ export const heartMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 					rotationRad,
 				});
 			},
+		},
+		stroke: {
+			kind: "strokeFromPath",
 			buildStrokePath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				const offset = getStrokeOffset({
@@ -139,4 +144,5 @@ export const heartMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 				});
 			},
 		},
+	},
 };

apps/web/src/masks/definitions/index.ts

@@ -1,5 +1,8 @@
-import type { BaseMaskParams, MaskDefinition } from "@/masks/types";
+import {
-import { masksRegistry, type MaskIconProps } from "../registry";
+	masksRegistry,
+	type MaskDefinitionForRegistration,
+	type MaskIconProps,
+} from "../registry";
 import { cinematicBarsMaskDefinition } from "./cinematic-bars";
 import { customMaskDefinition } from "./custom";
 import { diamondMaskDefinition } from "./diamond";
@@ -20,11 +23,11 @@ import {
 	TextFontIcon,
 } from "@hugeicons/core-free-icons";
 
-function registerDefaultMask<TParams extends BaseMaskParams>({
+function registerDefaultMask({
 	definition,
 	icon,
 }: {
-	definition: MaskDefinition<TParams>;
+	definition: MaskDefinitionForRegistration;
 	icon: MaskIconProps;
 }) {
 	if (masksRegistry.has(definition.type)) {

apps/web/src/masks/definitions/rectangle.ts

@@ -1,4 +1,4 @@
-import type { MaskDefinition, RectangleMaskParams } from "@/masks/types";
+import type { MaskDefinition } from "@/masks/types";
 import {
 	BOX_LIKE_MASK_PARAMS,
 	buildBoxMaskInteraction,
@@ -45,7 +45,7 @@ function buildRectanglePath({
 	return path;
 }
 
-export const rectangleMaskDefinition: MaskDefinition<RectangleMaskParams> = {
+export const rectangleMaskDefinition: MaskDefinition<"rectangle"> = {
 	type: "rectangle",
 	name: "Rectangle",
 	features: {
@@ -65,8 +65,10 @@ export const rectangleMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 	},
 	computeParamUpdate: computeBoxMaskParamUpdate,
 	renderer: {
+		body: {
+			kind: "fillPath",
 			buildPath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				return buildRectanglePath({
@@ -77,8 +79,11 @@ export const rectangleMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 					rotationRad,
 				});
 			},
+		},
+		stroke: {
+			kind: "strokeFromPath",
 			buildStrokePath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				const offset = getStrokeOffset({
@@ -94,4 +99,5 @@ export const rectangleMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 				});
 			},
 		},
+	},
 };

apps/web/src/masks/definitions/split.ts

@@ -71,11 +71,11 @@ export function getSplitMaskStrokeSegment({
 	width,
 	height,
 }: {
-	resolvedParams: unknown;
+	resolvedParams: SplitMaskParams;
 	width: number;
 	height: number;
 }): [{ x: number; y: number }, { x: number; y: number }] | null {
-	const { centerX, centerY, rotation } = resolvedParams as SplitMaskParams;
+	const { centerX, centerY, rotation } = resolvedParams;
 	const { normalX, normalY, lineX, lineY } = splitLineGeometry({
 		centerX,
 		centerY,
@@ -180,7 +180,7 @@ function computeSplitMaskParamUpdate({
 	return {};
 }
 
-export const splitMaskDefinition: MaskDefinition<SplitMaskParams> = {
+export const splitMaskDefinition: MaskDefinition<"split"> = {
 	type: "split",
 	name: "Split",
 	features: {
@@ -267,9 +267,10 @@ export const splitMaskDefinition: MaskDefinition<SplitMaskParams> = {
 		},
 	],
 	renderer: {
-		renderMaskHandlesFeather: true,
+		body: {
-		renderMask({ resolvedParams, ctx, width, height, feather }) {
+			kind: "drawWithFeather",
-			const { centerX, centerY, rotation } = resolvedParams as SplitMaskParams;
+			drawWithFeather({ resolvedParams, ctx, width, height, feather }) {
+				const { centerX, centerY, rotation } = resolvedParams;
 				const { normalX, normalY, lineX, lineY } = splitLineGeometry({
 					centerX,
 					centerY,
@@ -293,8 +294,9 @@ export const splitMaskDefinition: MaskDefinition<SplitMaskParams> = {
 				ctx.fillRect(0, 0, width, height);
 			},
 
+			opaqueFastPath: {
 				buildPath({ resolvedParams, width, height }) {
-			const { centerX, centerY, rotation } = resolvedParams as SplitMaskParams;
+					const { centerX, centerY, rotation } = resolvedParams;
 					const { normalX, normalY, lineX, lineY } = splitLineGeometry({
 						centerX,
 						centerY,
@@ -370,6 +372,10 @@ export const splitMaskDefinition: MaskDefinition<SplitMaskParams> = {
 					path.closePath();
 					return path;
 				},
+			},
+		},
+		stroke: {
+			kind: "strokeFromPath",
 			buildStrokePath({ resolvedParams, width, height }) {
 				const segment = getSplitMaskStrokeSegment({
 					resolvedParams,
@@ -387,4 +393,5 @@ export const splitMaskDefinition: MaskDefinition<SplitMaskParams> = {
 				return path;
 			},
 		},
+	},
 };

apps/web/src/masks/definitions/star.ts

@@ -1,4 +1,4 @@
-import type { MaskDefinition, RectangleMaskParams } from "@/masks/types";
+import type { MaskDefinition } from "@/masks/types";
 import {
 	BOX_LIKE_MASK_PARAMS,
 	buildBoxMaskInteraction,
@@ -85,7 +85,7 @@ function buildOverlayStarPath({
 	return `${segments.join(" ")} Z`;
 }
 
-export const starMaskDefinition: MaskDefinition<RectangleMaskParams> = {
+export const starMaskDefinition: MaskDefinition<"star"> = {
 	type: "star",
 	name: "Star",
 	features: {
@@ -108,8 +108,10 @@ export const starMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 	},
 	computeParamUpdate: computeBoxMaskParamUpdate,
 	renderer: {
+		body: {
+			kind: "fillPath",
 			buildPath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				return buildStarPath({
@@ -120,8 +122,11 @@ export const starMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 					rotationRad,
 				});
 			},
+		},
+		stroke: {
+			kind: "strokeFromPath",
 			buildStrokePath({ resolvedParams, width, height }) {
-			const params = resolvedParams as RectangleMaskParams;
+				const params = resolvedParams;
 				const { centerX, centerY, maskWidth, maskHeight, rotationRad } =
 					getBoxLikeGeometry({ params, width, height });
 				const offset = getStrokeOffset({
@@ -137,4 +142,5 @@ export const starMaskDefinition: MaskDefinition<RectangleMaskParams> = {
 				});
 			},
 		},
+	},
 };

apps/web/src/masks/definitions/text.ts

@@ -205,7 +205,7 @@ function computeTextMaskParamUpdate({
 	return {};
 }
 
-export const textMaskDefinition: MaskDefinition<TextMaskParams> = {
+export const textMaskDefinition: MaskDefinition<"text"> = {
 	type: "text",
 	name: "Text",
 	features: {
@@ -370,8 +370,10 @@ export const textMaskDefinition: MaskDefinition<TextMaskParams> = {
 		return params.content.trim().length > 0;
 	},
 	renderer: {
-		renderMask({ resolvedParams, ctx, width, height }) {
+		body: {
-			const params = resolvedParams as TextMaskParams;
+			kind: "drawOpaque",
+			drawOpaque({ resolvedParams, ctx, width, height }) {
+				const params = resolvedParams;
 				const { layout } = measureTextMask({ params, height });
 
 				ctx.save();
@@ -391,8 +393,11 @@ export const textMaskDefinition: MaskDefinition<TextMaskParams> = {
 				});
 				ctx.restore();
 			},
+		},
+		stroke: {
+			kind: "renderStroke",
 			renderStroke({ resolvedParams, ctx, width, height }) {
-			const params = resolvedParams as TextMaskParams;
+				const params = resolvedParams;
 				const { layout } = measureTextMask({ params, height });
 
 				ctx.save();
@@ -435,4 +440,5 @@ export const textMaskDefinition: MaskDefinition<TextMaskParams> = {
 				ctx.restore();
 			},
 		},
+	},
 };

apps/web/src/masks/index.ts

@@ -5,6 +5,35 @@ import { generateUUID } from "@/utils/id";
 export { masksRegistry } from "./registry";
 export { registerDefaultMasks } from "./definitions";
 
+type MaskWithoutId = Mask extends infer TMask
+	? TMask extends Mask
+		? Omit<TMask, "id">
+		: never
+	: never;
+
+function withMaskId({ mask, id }: { mask: MaskWithoutId; id: string }): Mask {
+	switch (mask.type) {
+		case "split":
+			return { ...mask, id };
+		case "cinematic-bars":
+			return { ...mask, id };
+		case "rectangle":
+			return { ...mask, id };
+		case "ellipse":
+			return { ...mask, id };
+		case "heart":
+			return { ...mask, id };
+		case "diamond":
+			return { ...mask, id };
+		case "star":
+			return { ...mask, id };
+		case "text":
+			return { ...mask, id };
+		case "custom":
+			return { ...mask, id };
+	}
+}
+
 export function buildDefaultMaskInstance({
 	maskType,
 	elementSize,
@@ -14,5 +43,8 @@ export function buildDefaultMaskInstance({
 }): Mask {
 	const definition = masksRegistry.get(maskType);
 	const context: MaskDefaultContext = { elementSize };
-	return { ...definition.buildDefault(context), id: generateUUID() } as Mask;
+	return withMaskId({
+		mask: definition.buildDefault(context),
+		id: generateUUID(),
+	});
 }

apps/web/src/masks/registry.ts

@@ -2,11 +2,11 @@ import { MAX_FEATHER } from "@/masks/feather";
 import type { ParamDefinition } from "@/params";
 import type {
 	BaseMaskParams,
+	Mask,
 	MaskDefaultContext,
 	MaskDefinition,
-	MaskInteractionResult,
+	MaskParamUpdateArgs,
-	MaskSnapArgs,
+	MaskRenderer,
-	MaskSnapResult,
 	MaskType,
 } from "@/masks/types";
 import type { HugeiconsIconProps } from "@hugeicons/react";
@@ -17,6 +17,16 @@ export type MaskIconProps = {
 	strokeWidth?: number;
 };
 
+type RegisteredMaskWithoutId = Mask extends infer TMask
+	? TMask extends Mask
+		? Omit<TMask, "id">
+		: never
+	: never;
+
+export type MaskDefinitionForRegistration = {
+	[TType in MaskType]: MaskDefinition<TType>;
+}[MaskType];
+
 const BASE_MASK_PARAM_DEFINITIONS: ParamDefinition<
 	keyof BaseMaskParams & string
 >[] = [
@@ -50,28 +60,15 @@ const BASE_MASK_PARAM_DEFINITIONS: ParamDefinition<
 export interface RegisteredMaskDefinition {
 	type: MaskType;
 	name: string;
-	features: MaskDefinition<BaseMaskParams>["features"];
+	features: MaskDefinition["features"];
 	params: ParamDefinition<string>[];
-	renderer: MaskDefinition<BaseMaskParams>["renderer"];
+	renderer: MaskRenderer<BaseMaskParams>;
-	interaction: {
+	interaction: MaskDefinition["interaction"];
-		getInteraction(args: {
+	isActive?(params: BaseMaskParams): boolean;
-			params: BaseMaskParams;
+	buildDefault(context: MaskDefaultContext): RegisteredMaskWithoutId;
-			bounds: Parameters<
-				MaskDefinition<BaseMaskParams>["interaction"]["getInteraction"]
-			>[0]["bounds"];
-			displayScale: number;
-			scaleX: number;
-			scaleY: number;
-		}): MaskInteractionResult;
-		snap?(args: MaskSnapArgs<BaseMaskParams>): MaskSnapResult<BaseMaskParams>;
-	};
-	isActive?: (params: BaseMaskParams) => boolean;
-	buildDefault(
-		context: MaskDefaultContext,
-	): ReturnType<MaskDefinition<BaseMaskParams>["buildDefault"]>;
 	computeParamUpdate(
-		args: Parameters<MaskDefinition<BaseMaskParams>["computeParamUpdate"]>[0],
+		args: MaskParamUpdateArgs<BaseMaskParams>,
-	): ReturnType<MaskDefinition<BaseMaskParams>["computeParamUpdate"]>;
+	): ReturnType<MaskDefinition["computeParamUpdate"]>;
 	icon: MaskIconProps;
 }
 
@@ -83,11 +80,11 @@ export class MasksRegistry extends DefinitionRegistry<
 		super("mask");
 	}
 
-	registerMask<TParams extends BaseMaskParams>({
+	registerMask({
 		definition,
 		icon,
 	}: {
-		definition: MaskDefinition<TParams>;
+		definition: MaskDefinitionForRegistration;
 		icon: MaskIconProps;
 	}): void {
 		const withBaseParams: RegisteredMaskDefinition = {
@@ -96,23 +93,10 @@ export class MasksRegistry extends DefinitionRegistry<
 			features: definition.features,
 			params: [...definition.params, ...BASE_MASK_PARAM_DEFINITIONS],
 			renderer: definition.renderer,
-			interaction: {
+			interaction: definition.interaction,
-				getInteraction(args) {
+			isActive: definition.isActive,
-					return definition.interaction.getInteraction(args as never);
+			buildDefault: definition.buildDefault,
-				},
+			computeParamUpdate: definition.computeParamUpdate,
-				snap: definition.interaction.snap
-					? (args) => definition.interaction.snap?.(args as never) as never
-					: undefined,
-			},
-			isActive: definition.isActive
-				? (params) => definition.isActive?.(params as TParams) ?? true
-				: undefined,
-			buildDefault(context) {
-				return definition.buildDefault(context);
-			},
-			computeParamUpdate(args) {
-				return definition.computeParamUpdate(args as never);
-			},
 			icon,
 		};
 		this.register({

apps/web/src/masks/types.ts

@@ -131,32 +131,50 @@ export type Mask =
 	| TextMask
 	| CustomMask;
 
-export interface MaskRenderer {
+export type MaskByType<TType extends MaskType> = Extract<Mask, { type: TType }>;
-	buildPath?: (params: {
+export type MaskParamsByType<TType extends MaskType> =
-		resolvedParams: unknown;
+	MaskByType<TType>["params"];
+
+type MaskPathArgs<TParams extends BaseMaskParams> = {
+	resolvedParams: TParams;
 	width: number;
 	height: number;
-	}) => Path2D;
+};
-	buildStrokePath?: (params: {
+
-		resolvedParams: unknown;
+type MaskDrawArgs<TParams extends BaseMaskParams> = MaskPathArgs<TParams> & {
-		width: number;
-		height: number;
-	}) => Path2D;
-	/** Renders the feathered mask directly onto ctx, bypassing JFA. */
-	renderMask?: (params: {
-		resolvedParams: unknown;
 	ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
-		width: number;
+};
-		height: number;
+
-		feather: number;
+export type MaskBody<TParams extends BaseMaskParams = BaseMaskParams> =
-	}) => void;
+	| {
-	renderMaskHandlesFeather?: boolean;
+			kind: "fillPath";
-	renderStroke?: (params: {
+			buildPath(args: MaskPathArgs<TParams>): Path2D;
-		resolvedParams: unknown;
+	  }
-		ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+	| {
-		width: number;
+			kind: "drawOpaque";
-		height: number;
+			drawOpaque(args: MaskDrawArgs<TParams>): void;
-	}) => void;
+	  }
+	| {
+			kind: "drawWithFeather";
+			drawWithFeather(args: MaskDrawArgs<TParams> & { feather: number }): void;
+			opaqueFastPath?: {
+				buildPath(args: MaskPathArgs<TParams>): Path2D;
+			};
+	  };
+
+export type MaskStroke<TParams extends BaseMaskParams = BaseMaskParams> =
+	| {
+			kind: "strokeFromPath";
+			buildStrokePath(args: MaskPathArgs<TParams>): Path2D;
+	  }
+	| {
+			kind: "renderStroke";
+			renderStroke(args: MaskDrawArgs<TParams>): void;
+	  };
+
+export interface MaskRenderer<TParams extends BaseMaskParams = BaseMaskParams> {
+	body: MaskBody<TParams>;
+	stroke?: MaskStroke<TParams>;
 }
 
 export interface MaskFeatures {
@@ -282,17 +300,17 @@ export interface MaskInteractionDefinition<
 	snap?(args: MaskSnapArgs<TParams>): MaskSnapResult<TParams>;
 }
 
-export interface MaskDefinition<
+export interface MaskDefinition<TType extends MaskType = MaskType> {
-	TParams extends BaseMaskParams = BaseMaskParams,
+	type: TType;
-> {
-	type: MaskType;
 	name: string;
 	features: MaskFeatures;
-	params: ParamDefinition<keyof TParams & string>[];
+	params: ParamDefinition<keyof MaskParamsByType<TType> & string>[];
-	renderer: MaskRenderer;
+	renderer: MaskRenderer<MaskParamsByType<TType>>;
-	interaction: MaskInteractionDefinition<TParams>;
+	interaction: MaskInteractionDefinition<MaskParamsByType<TType>>;
 	/** When defined and returning false, the mask is not applied and the element renders fully visible. */
-	isActive?: (params: TParams) => boolean;
+	isActive?(params: MaskParamsByType<TType>): boolean;
-	buildDefault(context: MaskDefaultContext): Omit<Mask, "id">;
+	buildDefault(context: MaskDefaultContext): Omit<MaskByType<TType>, "id">;
-	computeParamUpdate(args: MaskParamUpdateArgs<TParams>): Partial<TParams>;
+	computeParamUpdate(
+		args: MaskParamUpdateArgs<MaskParamsByType<TType>>,
+	): Partial<MaskParamsByType<TType>>;
 }

apps/web/src/services/renderer/compositor/frame-descriptor.ts

@@ -396,23 +396,16 @@ function buildMaskArtifacts({
 		return { mask: null, strokeLayer: null };
 	}
 
-	let feather = mask.params.feather;
+	const { body } = definition.renderer;
-	const canRenderMaskDirectly = Boolean(definition.renderer.renderMask);
+	const usesOpaqueFastPath =
-	const shouldRenderMaskDirectly =
+		body.kind === "drawWithFeather" &&
-		canRenderMaskDirectly &&
+		mask.params.feather === 0 &&
-		(!definition.renderer.buildPath ||
+		Boolean(body.opaqueFastPath);
-			(mask.params.feather > 0 &&
+	const feather = body.kind === "drawWithFeather" ? 0 : mask.params.feather;
-				definition.renderer.renderMaskHandlesFeather));
-	if (
-		shouldRenderMaskDirectly &&
-		definition.renderer.renderMaskHandlesFeather
-	) {
-		feather = 0;
-	}
 
 	const maskTextureId = `${path}:mask`;
 	const { width: canvasWidth, height: canvasHeight } = renderer;
-	const maskContentHash = `mask:${mask.type}:${JSON.stringify(mask.params)}:${transformHash(transform)}:${canvasWidth}x${canvasHeight}:direct=${shouldRenderMaskDirectly}`;
+	const maskContentHash = `mask:${mask.type}:${JSON.stringify(mask.params)}:${transformHash(transform)}:${canvasWidth}x${canvasHeight}:body=${body.kind}:fastPath=${usesOpaqueFastPath}`;
 	const drawMask: TextureCanvasDrawFn = (ctx) => {
 		const { canvas: elementMaskCanvas, context: elementMaskCtx } =
 			createCanvasSurface({
@@ -420,16 +413,28 @@ function buildMaskArtifacts({
 				height: Math.round(transform.height),
 			});
 
-		if (shouldRenderMaskDirectly && definition.renderer.renderMask) {
+		switch (body.kind) {
-			definition.renderer.renderMask({
+			case "fillPath": {
+				const path2d = body.buildPath({
+					resolvedParams: mask.params,
+					width: transform.width,
+					height: transform.height,
+				});
+				elementMaskCtx.fillStyle = "white";
+				elementMaskCtx.fill(path2d);
+				break;
+			}
+			case "drawOpaque":
+				body.drawOpaque({
 					resolvedParams: mask.params,
 					ctx: elementMaskCtx,
 					width: Math.round(transform.width),
 					height: Math.round(transform.height),
-				feather: mask.params.feather,
 				});
-		} else if (definition.renderer.buildPath) {
+				break;
-			const path2d = definition.renderer.buildPath({
+			case "drawWithFeather":
+				if (usesOpaqueFastPath && body.opaqueFastPath) {
+					const path2d = body.opaqueFastPath.buildPath({
 						resolvedParams: mask.params,
 						width: transform.width,
 						height: transform.height,
@@ -437,7 +442,15 @@ function buildMaskArtifacts({
 					elementMaskCtx.fillStyle = "white";
 					elementMaskCtx.fill(path2d);
 				} else {
-			return;
+					body.drawWithFeather({
+						resolvedParams: mask.params,
+						ctx: elementMaskCtx,
+						width: Math.round(transform.width),
+						height: Math.round(transform.height),
+						feather: mask.params.feather,
+					});
+				}
+				break;
 		}
 
 		drawTransformedCanvas({ ctx, source: elementMaskCanvas, transform });
@@ -451,45 +464,38 @@ function buildMaskArtifacts({
 		draw: drawMask,
 	});
 
-	const hasStroke =
+	const stroke = definition.renderer.stroke;
-		mask.params.strokeWidth > 0 &&
+	const hasStroke = mask.params.strokeWidth > 0 && Boolean(stroke);
-		(definition.renderer.renderStroke ||
-			definition.renderer.buildStrokePath ||
-			definition.renderer.buildPath);
 	let strokeLayer: FrameItemDescriptor | null = null;
-	if (hasStroke) {
+	if (hasStroke && stroke) {
 		const strokeTextureId = `${path}:mask-stroke`;
-		const strokeContentHash = `stroke:${mask.type}:${JSON.stringify(mask.params)}:${transformHash(transform)}:${canvasWidth}x${canvasHeight}`;
+		const strokeContentHash = `stroke:${mask.type}:${JSON.stringify(mask.params)}:${transformHash(transform)}:${canvasWidth}x${canvasHeight}:stroke=${stroke.kind}`;
 		const drawStroke: TextureCanvasDrawFn = (ctx) => {
 			const { canvas: strokeCanvas, context: strokeCtx } = createCanvasSurface({
 				width: Math.round(transform.width),
 				height: Math.round(transform.height),
 			});
 
-			if (definition.renderer.renderStroke) {
+			switch (stroke.kind) {
-				definition.renderer.renderStroke({
+				case "renderStroke":
+					stroke.renderStroke({
 						resolvedParams: mask.params,
 						ctx: strokeCtx,
 						width: transform.width,
 						height: transform.height,
 					});
-			} else {
+					break;
-				const strokePath =
+				case "strokeFromPath": {
-					definition.renderer.buildStrokePath?.({
+					const strokePath = stroke.buildStrokePath({
 						resolvedParams: mask.params,
 						width: transform.width,
 						height: transform.height,
-					}) ??
+					});
-					definition.renderer.buildPath?.({
-						resolvedParams: mask.params,
-						width: transform.width,
-						height: transform.height,
-					}) ??
-					null;
-				if (!strokePath) return;
 					strokeCtx.strokeStyle = mask.params.strokeColor;
 					strokeCtx.lineWidth = mask.params.strokeWidth;
 					strokeCtx.stroke(strokePath);
+					break;
+				}
 			}
 
 			drawTransformedCanvas({ ctx, source: strokeCanvas, transform });