feat(ui): better types & runtime guarantees for filter data stored in konva node attrs

Author: psychedelicious

invokeai/frontend/web/src/features/controlLayers/konva/filters.ts

@@ -4,6 +4,7 @@
  */
 
 import { clamp } from 'es-toolkit/compat';
+import { zCurvesAdjustmentsLUTs, zSimpleAdjustmentsConfig } from 'features/controlLayers/store/types';
 import type Konva from 'konva';
 
 /**
@@ -24,25 +25,18 @@ export const LightnessToAlphaFilter = (imageData: ImageData): void => {
   }
 };
 
-type SimpleAdjustParams = {
-  brightness: number; // -1..1 (additive)
-  contrast: number; // -1..1 (scale around 128)
-  saturation: number; // -1..1
-  temperature: number; // -1..1 (blue<->yellow approx)
-  tint: number; // -1..1 (green<->magenta approx)
-  sharpness: number; // -1..1 (light unsharp mask)
-};
-
 /**
  * Per-layer simple adjustments filter (brightness, contrast, saturation, temp, tint, sharpness).
  *
  * Parameters are read from the Konva node attr `adjustmentsSimple` set by the adapter.
  */
 export const AdjustmentsSimpleFilter = function (this: Konva.Node, imageData: ImageData): void {
-  const params = (this?.getAttr?.('adjustmentsSimple') as SimpleAdjustParams | undefined) ?? null;
-  if (!params) {
+  const paramsRaw = this.getAttr('adjustmentsSimple');
+  const parseResult = zSimpleAdjustmentsConfig.safeParse(paramsRaw);
+  if (!parseResult.success) {
     return;
   }
+  const params = parseResult.data;
 
   const { brightness, contrast, saturation, temperature, tint, sharpness } = params;
 
@@ -172,19 +166,19 @@ export const buildCurveLUT = (points: Array<[number, number]>): number[] => {
   return lut;
 };
 
-type CurvesAdjustParams = {
-  master: number[];
-  r: number[];
-  g: number[];
-  b: number[];
-};
-
-// Curves filter: apply master curve, then per-channel curves
+/**
+ * Per-layer curves adjustments filter (master, r, g, b)
+ *
+ * Parameters are read from the Konva node attr `adjustmentsCurves` set by the adapter.
+ */
 export const AdjustmentsCurvesFilter = function (this: Konva.Node, imageData: ImageData): void {
-  const params = (this?.getAttr?.('adjustmentsCurves') as CurvesAdjustParams | undefined) ?? null;
-  if (!params) {
+  const paramsRaw = this.getAttr('adjustmentsCurves');
+  const parseResult = zCurvesAdjustmentsLUTs.safeParse(paramsRaw);
+  if (!parseResult.success) {
     return;
   }
+  const params = parseResult.data;
+
   const { master, r, g, b } = params;
   if (!master || !r || !g || !b) {
     return;

invokeai/frontend/web/src/features/controlLayers/store/canvasSlice.ts

@@ -28,7 +28,7 @@ import type {
   RasterLayerAdjustments,
   RegionalGuidanceRefImageState,
   RgbColor,
-  SimpleConfig,
+  SimpleAdjustmentsConfig,
 } from 'features/controlLayers/store/types';
 import {
   calculateNewSize,
@@ -148,7 +148,7 @@ const slice = createSlice({
     },
     rasterLayerAdjustmentsSimpleUpdated: (
       state,
-      action: PayloadAction<EntityIdentifierPayload<{ simple: Partial<SimpleConfig> }, 'raster_layer'>>
+      action: PayloadAction<EntityIdentifierPayload<{ simple: Partial<SimpleAdjustmentsConfig> }, 'raster_layer'>>
     ) => {
       const { entityIdentifier, simple } = action.payload;
       const layer = selectEntity(state, entityIdentifier);

invokeai/frontend/web/src/features/controlLayers/store/types.ts

@@ -378,31 +378,46 @@ const zControlLoRAConfig = z.object({
 });
 export type ControlLoRAConfig = z.infer<typeof zControlLoRAConfig>;
 
-const zSimpleConfig = z.object({
-  // All simple params normalized to [-1, 1] except sharpness [0, 1]
+/**
+ * All simple params normalized to `[-1, 1]` except sharpness `[0, 1]`.
+ *
+ * - Brightness: -1 (darken) to 1 (brighten)
+ * - Contrast: -1 (decrease contrast) to 1 (increase contrast)
+ * - Saturation: -1 (desaturate) to 1 (saturate)
+ * - Temperature: -1 (cooler/blue) to 1 (warmer/yellow)
+ * - Tint: -1 (greener) to 1 (more magenta)
+ * - Sharpness: 0 (no sharpening) to 1 (maximum sharpening)
+ */
+export const zSimpleAdjustmentsConfig = z.object({
   brightness: z.number().gte(-1).lte(1),
   contrast: z.number().gte(-1).lte(1),
   saturation: z.number().gte(-1).lte(1),
   temperature: z.number().gte(-1).lte(1),
   tint: z.number().gte(-1).lte(1),
   sharpness: z.number().gte(0).lte(1),
 });
-export type SimpleConfig = z.infer<typeof zSimpleConfig>;
+export type SimpleAdjustmentsConfig = z.infer<typeof zSimpleAdjustmentsConfig>;
 
 const zUint8 = z.number().int().min(0).max(255);
 const zChannelPoints = z.array(z.tuple([zUint8, zUint8])).min(2);
 const zChannelName = z.enum(['master', 'r', 'g', 'b']);
-const zCurvesConfig = z.record(zChannelName, zChannelPoints);
+const zCurvesAdjustmentsConfig = z.record(zChannelName, zChannelPoints);
 export type ChannelName = z.infer<typeof zChannelName>;
 export type ChannelPoints = z.infer<typeof zChannelPoints>;
 
+/**
+ * The curves adjustments are stored as LUTs in the Konva node attributes. Konva will use these values when applying
+ * the filter.
+ */
+export const zCurvesAdjustmentsLUTs = z.record(zChannelName, z.array(zUint8));
+
 const zRasterLayerAdjustments = z.object({
   version: z.literal(1),
   enabled: z.boolean(),
   collapsed: z.boolean(),
   mode: z.enum(['simple', 'curves']),
-  simple: zSimpleConfig,
-  curves: zCurvesConfig,
+  simple: zSimpleAdjustmentsConfig,
+  curves: zCurvesAdjustmentsConfig,
 });
 export type RasterLayerAdjustments = z.infer<typeof zRasterLayerAdjustments>;