@routevn/creator-model 1.1.9 → 1.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routevn/creator-model",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/model.js

@@ -1141,7 +1141,12 @@ const validateAnimationKeyframes = ({ keyframes, path, errorFactory }) => {
   }
 };
 
-const validateTweenProperty = ({ config, path, errorFactory }) => {
+const validateTweenProperty = ({
+  config,
+  path,
+  allowEmptyKeyframes = false,
+  errorFactory,
+}) => {
   {
     const result = validateAllowedKeys({
       value: config,
@@ -1181,6 +1186,13 @@ const validateTweenProperty = ({ config, path, errorFactory }) => {
       return result;
     }
   }
+
+  if (!allowEmptyKeyframes && config.keyframes.length === 0) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.keyframes must contain at least one keyframe`,
+    );
+  }
 };
 
 const validateTweenDefinition = ({
@@ -1188,6 +1200,7 @@ const validateTweenDefinition = ({
   allowedProperties,
   path,
   unsupportedMessage,
+  allowEmptyKeyframes = false,
   errorFactory,
 }) => {
   if (!isPlainObject(tween)) {
@@ -1215,6 +1228,7 @@ const validateTweenDefinition = ({
       const result = validateTweenProperty({
         config,
         path: propertyPath,
+        allowEmptyKeyframes,
         errorFactory,
       });
       if (result?.valid === false) {
@@ -1230,6 +1244,8 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
       value: mask,
       allowedKeys: [
         "kind",
+        "imageId",
+        "imageIds",
         "texture",
         "textures",
         "items",
@@ -1239,6 +1255,8 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
         "invert",
         "sample",
         "progress",
+        "progressDuration",
+        "progressEasing",
       ],
       path,
       errorFactory,
@@ -1273,6 +1291,13 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
     );
   }
 
+  if (mask.imageId !== undefined && !isNonEmptyString(mask.imageId)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.imageId must be a non-empty string when provided`,
+    );
+  }
+
   if (mask.textures !== undefined) {
     if (!Array.isArray(mask.textures) || mask.textures.length === 0) {
       return invalidFromErrorFactory(
@@ -1291,6 +1316,24 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
     }
   }
 
+  if (mask.imageIds !== undefined) {
+    if (!Array.isArray(mask.imageIds) || mask.imageIds.length === 0) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.imageIds must be a non-empty array when provided`,
+      );
+    }
+
+    for (const [index, imageId] of mask.imageIds.entries()) {
+      if (!isNonEmptyString(imageId)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${path}.imageIds[${index}] must be a non-empty string`,
+        );
+      }
+    }
+  }
+
   if (mask.items !== undefined) {
     if (!Array.isArray(mask.items) || mask.items.length === 0) {
       return invalidFromErrorFactory(
@@ -1305,7 +1348,7 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
       {
         const result = validateAllowedKeys({
           value: item,
-          allowedKeys: ["texture", "channel", "invert"],
+          allowedKeys: ["texture", "imageId", "channel", "invert"],
           path: itemPath,
           errorFactory,
         });
@@ -1314,10 +1357,33 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
         }
       }
 
-      if (!isNonEmptyString(item.texture)) {
+      if (
+        item.texture !== undefined &&
+        !isNonEmptyString(item.texture)
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.texture must be a non-empty string when provided`,
+        );
+      }
+
+      if (
+        item.imageId !== undefined &&
+        !isNonEmptyString(item.imageId)
+      ) {
         return invalidFromErrorFactory(
           errorFactory,
-          `${itemPath}.texture must be a non-empty string`,
+          `${itemPath}.imageId must be a non-empty string when provided`,
+        );
+      }
+
+      if (
+        !isNonEmptyString(item.texture) &&
+        !isNonEmptyString(item.imageId)
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath} must define texture or imageId`,
         );
       }
 
@@ -1388,17 +1454,45 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
     }
   }
 
-  if (mask.kind === "single" && !isNonEmptyString(mask.texture)) {
+  if (
+    mask.progressDuration !== undefined &&
+    (!isFiniteNumber(mask.progressDuration) || mask.progressDuration < 1)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.progressDuration must be a finite number greater than or equal to 1 when provided`,
+    );
+  }
+
+  if (
+    mask.progressEasing !== undefined &&
+    !ANIMATION_EASING_KEYS.includes(mask.progressEasing)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.progressEasing must be a supported Route Graphics easing`,
+    );
+  }
+
+  if (
+    mask.kind === "single" &&
+    !isNonEmptyString(mask.texture) &&
+    !isNonEmptyString(mask.imageId)
+  ) {
     return invalidFromErrorFactory(
       errorFactory,
-      `${path}.texture is required when ${path}.kind is 'single'`,
+      `${path}.texture or ${path}.imageId is required when ${path}.kind is 'single'`,
     );
   }
 
-  if (mask.kind === "sequence" && mask.textures === undefined) {
+  if (
+    mask.kind === "sequence" &&
+    mask.textures === undefined &&
+    mask.imageIds === undefined
+  ) {
     return invalidFromErrorFactory(
       errorFactory,
-      `${path}.textures is required when ${path}.kind is 'sequence'`,
+      `${path}.textures or ${path}.imageIds is required when ${path}.kind is 'sequence'`,
     );
   }
 
@@ -1513,6 +1607,7 @@ const validateAnimationDefinition = ({ animation, path, errorFactory }) => {
         allowedProperties: TRANSITION_TWEEN_PROPERTY_KEYS,
         path: `${path}.${side}.tween`,
         unsupportedMessage: "is not a supported transition tween property",
+        allowEmptyKeyframes: true,
         errorFactory,
       });
       if (result?.valid === false) {
@@ -1551,8 +1646,8 @@ const validateAnimationItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
-            : ["id", "type", "name", "animation"],
+            ? ["id", "type", "name", "description"]
+            : ["id", "type", "name", "description", "animation"],
         path: itemPath,
         errorFactory,
       });
@@ -1582,6 +1677,13 @@ const validateAnimationItems = ({ items, path, errorFactory }) => {
       );
     }
 
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
     if (item.type === "animation") {
       {
         const result = validateAnimationDefinition({
@@ -1613,11 +1715,12 @@ const validateFontItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
+            ? ["id", "type", "name", "description"]
             : [
                 "id",
                 "type",
                 "name",
+                "description",
                 "fileId",
                 "fontFamily",
                 "fileType",
@@ -1652,6 +1755,13 @@ const validateFontItems = ({ items, path, errorFactory }) => {
       );
     }
 
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
     if (item.type === "font") {
       if (!isNonEmptyString(item.fileId)) {
         return invalidFromErrorFactory(
@@ -1700,8 +1810,8 @@ const validateColorItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
-            : ["id", "type", "name", "hex"],
+            ? ["id", "type", "name", "description"]
+            : ["id", "type", "name", "description", "hex"],
         path: itemPath,
         errorFactory,
       });
@@ -1731,6 +1841,13 @@ const validateColorItems = ({ items, path, errorFactory }) => {
       );
     }
 
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
     if (item.type === "color" && !isHexColor(item.hex)) {
       return invalidFromErrorFactory(
         errorFactory,
@@ -1756,11 +1873,12 @@ const validateTransformItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
+            ? ["id", "type", "name", "description"]
             : [
                 "id",
                 "type",
                 "name",
+                "description",
                 "x",
                 "y",
                 "scaleX",
@@ -1798,6 +1916,13 @@ const validateTransformItems = ({ items, path, errorFactory }) => {
       );
     }
 
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
     if (item.type === "transform") {
       for (const key of [
         "x",
@@ -1861,8 +1986,8 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           variableType === "folder"
-            ? ["id", "type", "name"]
-            : ["id", "type", "name", "scope", "default", "value"],
+            ? ["id", "type", "name", "description"]
+            : ["id", "type", "name", "description", "scope", "default", "value"],
         path: itemPath,
         errorFactory,
       });
@@ -1892,6 +2017,13 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
       );
     }
 
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
     if (variableType !== "folder") {
       if (!VARIABLE_SCOPE_KEYS.includes(item.scope)) {
         return invalidFromErrorFactory(
@@ -1942,11 +2074,12 @@ const validateTextStyleItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
+            ? ["id", "type", "name", "description"]
             : [
                 "id",
                 "type",
                 "name",
+                "description",
                 "fontId",
                 "colorId",
                 "fontSize",
@@ -1991,6 +2124,13 @@ const validateTextStyleItems = ({ items, path, errorFactory }) => {
       );
     }
 
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
     if (item.type === "textStyle") {
       if (!isNonEmptyString(item.fontId)) {
         return invalidFromErrorFactory(
@@ -2121,11 +2261,12 @@ const validateCharacterSpriteItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
+            ? ["id", "type", "name", "description"]
             : [
                 "id",
                 "type",
                 "name",
+                "description",
                 "thumbnailFileId",
                 "fileId",
                 "fileType",
@@ -2162,6 +2303,13 @@ const validateCharacterSpriteItems = ({ items, path, errorFactory }) => {
       );
     }
 
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
     if (item.type === "image") {
       if (
         item.thumbnailFileId !== undefined &&
@@ -2907,7 +3055,7 @@ const validateCharacterItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
+            ? ["id", "type", "name", "description"]
             : [
                 "id",
                 "type",
@@ -2948,14 +3096,14 @@ const validateCharacterItems = ({ items, path, errorFactory }) => {
       );
     }
 
-    if (item.type === "character") {
-      if (item.description !== undefined && !isString(item.description)) {
-        return invalidFromErrorFactory(
-          errorFactory,
-          `${itemPath}.description must be a string when provided`,
-        );
-      }
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
 
+    if (item.type === "character") {
       if (item.shortcut !== undefined && !isString(item.shortcut)) {
         return invalidFromErrorFactory(
           errorFactory,
@@ -3048,7 +3196,7 @@ const validateLayoutItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
+            ? ["id", "type", "name", "description"]
             : [
                 "id",
                 "type",
@@ -3155,8 +3303,16 @@ const validateControlItems = ({ items, path, errorFactory }) => {
         value: item,
         allowedKeys:
           item.type === "folder"
-            ? ["id", "type", "name"]
-            : ["id", "type", "name", "thumbnailFileId", "elements", "keyboard"],
+            ? ["id", "type", "name", "description"]
+            : [
+                "id",
+                "type",
+                "name",
+                "description",
+                "thumbnailFileId",
+                "elements",
+                "keyboard",
+              ],
         path: itemPath,
         errorFactory,
       });
@@ -3186,6 +3342,13 @@ const validateControlItems = ({ items, path, errorFactory }) => {
       );
     }
 
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
     if (
       item.thumbnailFileId !== undefined &&
       !isNonEmptyString(item.thumbnailFileId)
@@ -3996,6 +4159,108 @@ const validateFileReference = ({
   return VALID_RESULT;
 };
 
+const validateImageReference = ({
+  state,
+  imageId,
+  path,
+  details = {},
+  errorFactory = createPreconditionValidationError,
+}) => {
+  if (imageId === undefined || imageId === null) {
+    return VALID_RESULT;
+  }
+
+  const image = state.images?.items?.[imageId];
+  if (!isPlainObject(image) || image.type === "folder") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must reference an existing non-folder image`,
+      details,
+    );
+  }
+
+  return VALID_RESULT;
+};
+
+const validateAnimationMaskImageReferences = ({
+  state,
+  animation,
+  path,
+  details = {},
+  errorFactory = createPreconditionValidationError,
+}) => {
+  if (
+    !isPlainObject(animation) ||
+    animation.type !== "transition" ||
+    !isPlainObject(animation.mask)
+  ) {
+    return VALID_RESULT;
+  }
+
+  const { mask } = animation;
+
+  if (mask.imageId !== undefined) {
+    const result = validateImageReference({
+      state,
+      imageId: mask.imageId,
+      path: `${path}.mask.imageId`,
+      details: {
+        ...details,
+        field: "imageId",
+        imageId: mask.imageId,
+      },
+      errorFactory,
+    });
+    if (!result.valid) {
+      return result;
+    }
+  }
+
+  if (Array.isArray(mask.imageIds)) {
+    for (const [index, imageId] of mask.imageIds.entries()) {
+      const result = validateImageReference({
+        state,
+        imageId,
+        path: `${path}.mask.imageIds[${index}]`,
+        details: {
+          ...details,
+          field: `imageIds[${index}]`,
+          imageId,
+        },
+        errorFactory,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+  }
+
+  if (Array.isArray(mask.items)) {
+    for (const [index, item] of mask.items.entries()) {
+      if (item?.imageId === undefined) {
+        continue;
+      }
+
+      const result = validateImageReference({
+        state,
+        imageId: item.imageId,
+        path: `${path}.mask.items[${index}].imageId`,
+        details: {
+          ...details,
+          field: `items[${index}].imageId`,
+          imageId: item.imageId,
+        },
+        errorFactory,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+  }
+
+  return VALID_RESULT;
+};
+
 export const assertInvariants = ({ state }) => {
   if (!isPlainObject(state)) {
     return invalidInvariant("state must be an object");
@@ -4225,6 +4490,23 @@ export const assertInvariants = ({ state }) => {
     }
   }
 
+  for (const [animationId, animation] of Object.entries(state.animations.items)) {
+    if (animation.type !== "animation") {
+      continue;
+    }
+
+    const result = validateAnimationMaskImageReferences({
+      state,
+      animation: animation.animation,
+      path: "animation",
+      details: { animationId },
+      errorFactory: createInvariantValidationError,
+    });
+    if (!result.valid) {
+      return result;
+    }
+  }
+
   for (const [characterId, character] of Object.entries(
     state.characters.items,
   )) {
@@ -5550,8 +5832,16 @@ const validateFontCreateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys:
         data.type === "folder"
-          ? ["type", "name"]
-          : ["type", "name", "fileId", "fontFamily", "fileType", "fileSize"],
+          ? ["type", "name", "description"]
+          : [
+              "type",
+              "name",
+              "description",
+              "fileId",
+              "fontFamily",
+              "fileType",
+              "fileSize",
+            ],
       path: "payload.data",
       errorFactory,
     });
@@ -5567,6 +5857,13 @@ const validateFontCreateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.type === "font") {
     if (!isNonEmptyString(data.fileId)) {
       return invalidFromErrorFactory(
@@ -5602,7 +5899,14 @@ const validateFontUpdateData = ({ data, errorFactory }) => {
   {
     const result = validateAllowedKeys({
       value: data,
-      allowedKeys: ["name", "fileId", "fontFamily", "fileType", "fileSize"],
+      allowedKeys: [
+        "name",
+        "description",
+        "fileId",
+        "fontFamily",
+        "fileType",
+        "fileSize",
+      ],
       path: "payload.data",
       errorFactory,
     });
@@ -5625,6 +5929,13 @@ const validateFontUpdateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.fileId !== undefined && !isNonEmptyString(data.fileId)) {
     return invalidFromErrorFactory(
       errorFactory,
@@ -5773,7 +6084,9 @@ const validateColorCreateData = ({ data, errorFactory }) => {
     const result = validateAllowedKeys({
       value: data,
       allowedKeys:
-        data.type === "folder" ? ["type", "name"] : ["type", "name", "hex"],
+        data.type === "folder"
+          ? ["type", "name", "description"]
+          : ["type", "name", "description", "hex"],
       path: "payload.data",
       errorFactory,
     });
@@ -5789,6 +6102,13 @@ const validateColorCreateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.type === "color" && !isHexColor(data.hex)) {
     return invalidFromErrorFactory(
       errorFactory,
@@ -5801,7 +6121,7 @@ const validateColorUpdateData = ({ data, errorFactory }) => {
   {
     const result = validateAllowedKeys({
       value: data,
-      allowedKeys: ["name", "hex"],
+      allowedKeys: ["name", "description", "hex"],
       path: "payload.data",
       errorFactory,
     });
@@ -5824,6 +6144,13 @@ const validateColorUpdateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.hex !== undefined && !isHexColor(data.hex)) {
     return invalidFromErrorFactory(
       errorFactory,
@@ -5852,8 +6179,8 @@ const validateAnimationCreateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys:
         data.type === "folder"
-          ? ["type", "name"]
-          : ["type", "name", "animation"],
+          ? ["type", "name", "description"]
+          : ["type", "name", "description", "animation"],
       path: "payload.data",
       errorFactory,
     });
@@ -5869,6 +6196,13 @@ const validateAnimationCreateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.type === "animation") {
     {
       const result = validateAnimationDefinition({
@@ -5887,7 +6221,7 @@ const validateAnimationUpdateData = ({ data, errorFactory }) => {
   {
     const result = validateAllowedKeys({
       value: data,
-      allowedKeys: ["name", "animation"],
+      allowedKeys: ["name", "description", "animation"],
       path: "payload.data",
       errorFactory,
     });
@@ -5910,6 +6244,13 @@ const validateAnimationUpdateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.animation !== undefined) {
     {
       const result = validateAnimationDefinition({
@@ -5944,10 +6285,11 @@ const validateTransformCreateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys:
         data.type === "folder"
-          ? ["type", "name"]
+          ? ["type", "name", "description"]
           : [
               "type",
               "name",
+              "description",
               "x",
               "y",
               "scaleX",
@@ -5971,6 +6313,13 @@ const validateTransformCreateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.type === "transform") {
     for (const key of [
       "x",
@@ -5997,6 +6346,7 @@ const validateTransformUpdateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys: [
         "name",
+        "description",
         "x",
         "y",
         "scaleX",
@@ -6027,6 +6377,13 @@ const validateTransformUpdateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   for (const key of [
     "x",
     "y",
@@ -6065,8 +6422,8 @@ const validateVariableCreateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys:
         data.type === "folder"
-          ? ["type", "name"]
-          : ["type", "name", "scope", "default", "value"],
+          ? ["type", "name", "description"]
+          : ["type", "name", "description", "scope", "default", "value"],
       path: "payload.data",
       errorFactory,
     });
@@ -6082,6 +6439,13 @@ const validateVariableCreateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.type !== "folder") {
     if (!VARIABLE_SCOPE_KEYS.includes(data.scope)) {
       return invalidFromErrorFactory(
@@ -6119,7 +6483,7 @@ const validateVariableUpdateData = ({ data, errorFactory }) => {
   {
     const result = validateAllowedKeys({
       value: data,
-      allowedKeys: ["name", "scope", "default", "value"],
+      allowedKeys: ["name", "description", "scope", "default", "value"],
       path: "payload.data",
       errorFactory,
     });
@@ -6142,6 +6506,13 @@ const validateVariableUpdateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.scope !== undefined && !VARIABLE_SCOPE_KEYS.includes(data.scope)) {
     return invalidFromErrorFactory(
       errorFactory,
@@ -6170,10 +6541,11 @@ const validateTextStyleCreateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys:
         data.type === "folder"
-          ? ["type", "name"]
+          ? ["type", "name", "description"]
           : [
               "type",
               "name",
+              "description",
               "fontId",
               "colorId",
               "fontSize",
@@ -6204,6 +6576,13 @@ const validateTextStyleCreateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.type === "textStyle") {
     {
       const result = validateTextStyleItems({
@@ -6229,6 +6608,7 @@ const validateTextStyleUpdateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys: [
         "name",
+        "description",
         "fontId",
         "colorId",
         "fontSize",
@@ -6266,6 +6646,13 @@ const validateTextStyleUpdateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   for (const key of ["fontId", "colorId", "strokeColorId"]) {
     if (data[key] !== undefined && !isNonEmptyString(data[key])) {
       return invalidFromErrorFactory(
@@ -6349,6 +6736,7 @@ const validateCharacterSpriteCreateData = ({ data, errorFactory }) => {
           : [
               "type",
               "name",
+              "description",
               "fileId",
               "thumbnailFileId",
               "fileType",
@@ -6371,6 +6759,13 @@ const validateCharacterSpriteCreateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (data.type === "image") {
     if (!isNonEmptyString(data.fileId)) {
       return invalidFromErrorFactory(
@@ -6416,13 +6811,6 @@ const validateCharacterSpriteCreateData = ({ data, errorFactory }) => {
         "payload.data.height must be a finite number when provided",
       );
     }
-
-    if (data.description !== undefined && !isString(data.description)) {
-      return invalidFromErrorFactory(
-        errorFactory,
-        "payload.data.description must be a string when provided",
-      );
-    }
   }
 };
 
@@ -6535,7 +6923,7 @@ const validateCharacterCreateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys:
         data.type === "folder"
-          ? ["type", "name"]
+          ? ["type", "name", "description"]
           : [
               "type",
               "name",
@@ -6561,14 +6949,14 @@ const validateCharacterCreateData = ({ data, errorFactory }) => {
     );
   }
 
-  if (data.type === "character") {
-    if (data.description !== undefined && !isString(data.description)) {
-      return invalidFromErrorFactory(
-        errorFactory,
-        "payload.data.description must be a string when provided",
-      );
-    }
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
 
+  if (data.type === "character") {
     if (data.shortcut !== undefined && !isString(data.shortcut)) {
       return invalidFromErrorFactory(
         errorFactory,
@@ -6705,7 +7093,7 @@ const validateLayoutCreateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys:
         data.type === "folder"
-          ? ["type", "name"]
+          ? ["type", "name", "description"]
           : [
               "type",
               "name",
@@ -6865,8 +7253,15 @@ const validateControlCreateData = ({ data, errorFactory }) => {
       value: data,
       allowedKeys:
         data.type === "folder"
-          ? ["type", "name"]
-          : ["type", "name", "thumbnailFileId", "elements", "keyboard"],
+          ? ["type", "name", "description"]
+          : [
+              "type",
+              "name",
+              "description",
+              "thumbnailFileId",
+              "elements",
+              "keyboard",
+            ],
       path: "payload.data",
       errorFactory,
     });
@@ -6882,6 +7277,13 @@ const validateControlCreateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (
     data.thumbnailFileId !== undefined &&
     !isNonEmptyString(data.thumbnailFileId)
@@ -6923,7 +7325,7 @@ const validateControlUpdateData = ({ data, errorFactory }) => {
   {
     const result = validateAllowedKeys({
       value: data,
-      allowedKeys: ["name", "keyboard", "thumbnailFileId"],
+      allowedKeys: ["name", "description", "keyboard", "thumbnailFileId"],
       path: "payload.data",
       errorFactory,
     });
@@ -6946,6 +7348,13 @@ const validateControlUpdateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
   if (
     data.thumbnailFileId !== undefined &&
     !isNonEmptyString(data.thumbnailFileId)
@@ -10611,6 +11020,19 @@ const COMMAND_DEFINITIONS = [
           );
         }
       }
+
+      if (payload.data.type === "animation") {
+        const result = validateAnimationMaskImageReferences({
+          state,
+          animation: payload.data.animation,
+          path: "payload.data.animation",
+          details: { animationId: payload.animationId },
+          errorFactory: createPreconditionValidationError,
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const nextAnimation = {
@@ -10619,6 +11041,10 @@ const COMMAND_DEFINITIONS = [
         name: payload.data.name,
       };
 
+      if (payload.data.description !== undefined) {
+        nextAnimation.description = payload.data.description;
+      }
+
       if (payload.data.type === "animation") {
         nextAnimation.animation = structuredClone(payload.data.animation);
       }
@@ -10685,6 +11111,19 @@ const COMMAND_DEFINITIONS = [
           "folder animation items cannot update animation fields",
         );
       }
+
+      if (payload.data.animation !== undefined) {
+        const result = validateAnimationMaskImageReferences({
+          state,
+          animation: payload.data.animation,
+          path: "payload.data.animation",
+          details: { animationId: payload.animationId },
+          errorFactory: createPreconditionValidationError,
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const currentAnimation = state.animations.items[payload.animationId];
@@ -11005,6 +11444,10 @@ const COMMAND_DEFINITIONS = [
         name: payload.data.name,
       };
 
+      if (payload.data.description !== undefined) {
+        nextFont.description = payload.data.description;
+      }
+
       if (payload.data.type === "font") {
         nextFont.fileId = payload.data.fileId;
         nextFont.fontFamily = payload.data.fontFamily;
@@ -11401,6 +11844,10 @@ const COMMAND_DEFINITIONS = [
         name: payload.data.name,
       };
 
+      if (payload.data.description !== undefined) {
+        nextColor.description = payload.data.description;
+      }
+
       if (payload.data.type === "color") {
         nextColor.hex = payload.data.hex;
       }
@@ -11678,6 +12125,11 @@ const COMMAND_DEFINITIONS = [
       id: payload.transformId,
       type: payload.data.type,
       name: payload.data.name,
+      ...(payload.data.description !== undefined
+        ? {
+            description: payload.data.description,
+          }
+        : {}),
       ...(payload.data.type === "transform"
         ? {
             x: payload.data.x,
@@ -11693,7 +12145,9 @@ const COMMAND_DEFINITIONS = [
     validateUpdateState: ({ payload, currentItem }) => {
       if (
         currentItem.type === "folder" &&
-        Object.keys(payload.data).some((key) => key !== "name")
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
       ) {
         return invalidPrecondition(
           "folder transform items cannot update transform fields",
@@ -11712,6 +12166,11 @@ const COMMAND_DEFINITIONS = [
       id: payload.variableId,
       type: payload.data.type,
       name: payload.data.name,
+      ...(payload.data.description !== undefined
+        ? {
+            description: payload.data.description,
+          }
+        : {}),
       ...(payload.data.type === "folder"
         ? {}
         : {
@@ -11723,7 +12182,9 @@ const COMMAND_DEFINITIONS = [
     validateUpdateState: ({ payload, currentItem }) => {
       if (
         currentItem.type === "folder" &&
-        Object.keys(payload.data).some((key) => key !== "name")
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
       ) {
         return invalidPrecondition(
           "folder variable items cannot update variable fields",
@@ -11795,7 +12256,9 @@ const COMMAND_DEFINITIONS = [
     validateUpdateState: ({ state, payload, currentItem }) => {
       if (
         currentItem.type === "folder" &&
-        Object.keys(payload.data).some((key) => key !== "name")
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
       ) {
         return invalidPrecondition(
           "folder text style items cannot update text style fields",
@@ -11831,14 +12294,14 @@ const COMMAND_DEFINITIONS = [
         name: payload.data.name,
       };
 
-      if (item.type !== "character") {
-        return item;
-      }
-
       if (payload.data.description !== undefined) {
         item.description = payload.data.description;
       }
 
+      if (item.type !== "character") {
+        return item;
+      }
+
       if (payload.data.shortcut !== undefined) {
         item.shortcut = payload.data.shortcut;
       }
@@ -11924,7 +12387,9 @@ const COMMAND_DEFINITIONS = [
     validateUpdateState: ({ state, payload, currentItem }) => {
       if (
         currentItem.type === "folder" &&
-        Object.keys(payload.data).some((key) => key !== "name")
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
       ) {
         return invalidPrecondition(
           "folder character items cannot update character fields",
@@ -11957,9 +12422,13 @@ const COMMAND_DEFINITIONS = [
       id: payload.layoutId,
       type: payload.data.type,
       name: payload.data.name,
-      ...(payload.data.type === "layout"
+      ...(payload.data.description !== undefined
         ? {
             description: payload.data.description,
+          }
+        : {}),
+      ...(payload.data.type === "layout"
+        ? {
             layoutType: payload.data.layoutType,
             isFragment: payload.data.isFragment,
             ...(payload.data.thumbnailFileId !== undefined
@@ -11988,7 +12457,9 @@ const COMMAND_DEFINITIONS = [
     validateUpdateState: ({ state, payload, currentItem }) => {
       if (
         currentItem.type === "folder" &&
-        Object.keys(payload.data).some((key) => key !== "name")
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
       ) {
         return invalidPrecondition(
           "folder layout items cannot update layout fields",
@@ -12018,6 +12489,11 @@ const COMMAND_DEFINITIONS = [
       id: payload.controlId,
       type: payload.data.type,
       name: payload.data.name,
+      ...(payload.data.description !== undefined
+        ? {
+            description: payload.data.description,
+          }
+        : {}),
       ...(payload.data.type === "control"
         ? {
             ...(payload.data.thumbnailFileId !== undefined
@@ -12051,7 +12527,9 @@ const COMMAND_DEFINITIONS = [
     validateUpdateState: ({ state, payload, currentItem }) => {
       if (
         currentItem.type === "folder" &&
-        Object.keys(payload.data).some((key) => key !== "name")
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
       ) {
         return invalidPrecondition(
           "folder control items cannot update control fields",
@@ -12273,7 +12751,9 @@ const COMMAND_DEFINITIONS = [
 
       if (
         currentItem.type === "folder" &&
-        Object.keys(payload.data).some((key) => key !== "name")
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
       ) {
         return invalidPrecondition(
           "folder sprite items cannot update image fields",