@routevn/creator-model 1.0.0 → 1.0.2

package/package.json

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

package/src/model.js

@@ -18,6 +18,7 @@ import {
 
 const COLLECTION_KEYS = [
   "scenes",
+  "files",
   "images",
   "sounds",
   "videos",
@@ -32,6 +33,33 @@ const COLLECTION_KEYS = [
 ];
 const ROOT_KEYS = ["project", "story", ...COLLECTION_KEYS];
 const isString = (value) => typeof value === "string";
+const FILE_ITEM_TYPES = [
+  "image",
+  "image-thumbnail",
+  "audio",
+  "audio-waveform",
+  "video",
+  "video-thumbnail",
+  "font",
+];
+const IMAGE_FILE_REFERENCE_TYPES = {
+  fileId: ["image"],
+  thumbnailFileId: ["image-thumbnail"],
+};
+const SOUND_FILE_REFERENCE_TYPES = {
+  fileId: ["audio"],
+  waveformDataFileId: ["audio-waveform"],
+};
+const VIDEO_FILE_REFERENCE_TYPES = {
+  fileId: ["video"],
+  thumbnailFileId: ["video-thumbnail"],
+};
+const FONT_FILE_REFERENCE_TYPES = {
+  fileId: ["font"],
+};
+const CHARACTER_FILE_REFERENCE_TYPES = {
+  fileId: ["image"],
+};
 const isHexColor = (value) =>
   typeof value === "string" && /^#[0-9a-fA-F]{6}$/.test(value);
 const LIVE_TWEEN_PROPERTY_KEYS = [
@@ -104,7 +132,7 @@ const LAYOUT_ELEMENT_BASE_TYPES = [
   "container-ref-choice-item",
   "container-ref-dialogue-line",
 ];
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 const LAYOUT_CONTAINER_ELEMENT_TYPES = [
   "folder",
   "container",
@@ -482,6 +510,79 @@ const validateLineItems = ({ items, path, errorFactory }) => {
   }
 };
 
+const validateFileItems = ({ items, path, errorFactory }) => {
+  for (const [itemId, item] of Object.entries(items)) {
+    const itemPath = `${path}.${itemId}`;
+
+    if (item?.type !== "folder" && !FILE_ITEM_TYPES.includes(item?.type)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.type must be 'folder' or a supported file type`,
+      );
+    }
+
+    {
+      const result = validateAllowedKeys({
+        value: item,
+        allowedKeys:
+          item.type === "folder"
+            ? ["id", "type", "name"]
+            : ["id", "type", "mimeType", "size", "sha256"],
+        path: itemPath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!isNonEmptyString(item.id)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.id must be a non-empty string`,
+      );
+    }
+
+    if (item.id !== itemId) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.id must match item key '${itemId}'`,
+      );
+    }
+
+    if (item.type === "folder") {
+      if (!isNonEmptyString(item.name)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.name must be a non-empty string`,
+        );
+      }
+      continue;
+    }
+
+    if (!isNonEmptyString(item.mimeType)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.mimeType must be a non-empty string`,
+      );
+    }
+
+    if (!isFiniteNumber(item.size)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.size must be a finite number`,
+      );
+    }
+
+    if (!isNonEmptyString(item.sha256)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.sha256 must be a non-empty string`,
+      );
+    }
+  }
+};
+
 const validateImageItems = ({ items, path, errorFactory }) => {
   for (const [itemId, item] of Object.entries(items)) {
     const itemPath = `${path}.${itemId}`;
@@ -501,6 +602,7 @@ const validateImageItems = ({ items, path, errorFactory }) => {
                 "type",
                 "name",
                 "description",
+                "thumbnailFileId",
                 "fileId",
                 "fileType",
                 "fileSize",
@@ -534,6 +636,16 @@ const validateImageItems = ({ items, path, errorFactory }) => {
     }
 
     if (item.type === "image") {
+      if (
+        item.thumbnailFileId !== undefined &&
+        !isNonEmptyString(item.thumbnailFileId)
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.thumbnailFileId must be a non-empty string when provided`,
+        );
+      }
+
       if (!isNonEmptyString(item.fileId)) {
         return invalidFromErrorFactory(errorFactory, `${itemPath}.fileId must be a non-empty string`);
       }
@@ -1737,6 +1849,7 @@ const validateLayoutElementData = ({
     "variableId",
     "$when",
     "click",
+    "rightClick",
     "change",
   ];
 
@@ -1870,6 +1983,10 @@ const validateLayoutElementData = ({
     return invalidFromErrorFactory(errorFactory, `${path}.click must be an object when provided`);
   }
 
+  if (data.rightClick !== undefined && !isPlainObject(data.rightClick)) {
+    return invalidFromErrorFactory(errorFactory, `${path}.rightClick must be an object when provided`);
+  }
+
   if (data.change !== undefined && !isPlainObject(data.change)) {
     return invalidFromErrorFactory(errorFactory, `${path}.change must be an object when provided`);
   }
@@ -1921,6 +2038,7 @@ const validateLayoutElementItems = ({ items, path, errorFactory }) => {
           "variableId",
           "$when",
           "click",
+          "rightClick",
           "change",
         ],
         path: itemPath,
@@ -2577,6 +2695,17 @@ const validateCollection = ({ collection, path }) => {
         return result;
       }
     }
+  } else if (path === "state.files") {
+    {
+      const result = validateFileItems({
+        items: collection.items,
+        path: `${path}.items`,
+        errorFactory: createStateValidationError,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
   } else if (path === "state.sounds") {
     {
       const result = validateSoundItems({
@@ -2784,6 +2913,7 @@ const validateCollection = ({ collection, path }) => {
       }
     }
   } else if (
+    path === "state.files" ||
     path === "state.transforms" ||
     path === "state.variables" ||
     path === "state.textStyles" ||
@@ -2813,6 +2943,53 @@ const validateCollection = ({ collection, path }) => {
   }
 };
 
+const validateFileReference = ({
+  state,
+  fileId,
+  path,
+  allowedTypes,
+  details = {},
+  errorFactory = createPreconditionValidationError,
+}) => {
+  if (fileId === undefined || fileId === null) {
+    return VALID_RESULT;
+  }
+
+  const expectedTypeMessage =
+    Array.isArray(allowedTypes) && allowedTypes.length > 0
+      ? `${path} must reference an existing non-folder file with type ${allowedTypes
+          .map((type) => `'${type}'`)
+          .join(" or ")}`
+      : `${path} must reference an existing non-folder file`;
+  const file = state.files?.items?.[fileId];
+  if (!isPlainObject(file) || file.type === "folder") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      expectedTypeMessage,
+      Array.isArray(allowedTypes) && allowedTypes.length > 0
+        ? {
+            ...details,
+            expectedFileTypes: [...allowedTypes],
+          }
+        : details,
+    );
+  }
+
+  if (Array.isArray(allowedTypes) && allowedTypes.length > 0 && !allowedTypes.includes(file.type)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      expectedTypeMessage,
+      {
+        ...details,
+        expectedFileTypes: [...allowedTypes],
+        actualFileType: file.type,
+      },
+    );
+  }
+
+  return VALID_RESULT;
+};
+
 export const assertInvariants = ({ state }) => {
   if (!isPlainObject(state)) {
     return invalidInvariant("state must be an object");
@@ -2924,6 +3101,166 @@ export const assertInvariants = ({ state }) => {
     }
   }
 
+  for (const [imageId, image] of Object.entries(state.images.items)) {
+    if (image.type !== "image") {
+      continue;
+    }
+
+    {
+      const result = validateFileReference({
+        state,
+        fileId: image.fileId,
+        path: "image.fileId",
+        allowedTypes: IMAGE_FILE_REFERENCE_TYPES.fileId,
+        details: { imageId, fileId: image.fileId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+
+    if (image.thumbnailFileId !== undefined) {
+      const result = validateFileReference({
+        state,
+        fileId: image.thumbnailFileId,
+        path: "image.thumbnailFileId",
+        allowedTypes: IMAGE_FILE_REFERENCE_TYPES.thumbnailFileId,
+        details: { imageId, thumbnailFileId: image.thumbnailFileId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+  }
+
+  for (const [soundId, sound] of Object.entries(state.sounds.items)) {
+    if (sound.type !== "sound") {
+      continue;
+    }
+
+    {
+      const result = validateFileReference({
+        state,
+        fileId: sound.fileId,
+        path: "sound.fileId",
+        allowedTypes: SOUND_FILE_REFERENCE_TYPES.fileId,
+        details: { soundId, fileId: sound.fileId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+
+    if (sound.waveformDataFileId !== undefined && sound.waveformDataFileId !== null) {
+      const result = validateFileReference({
+        state,
+        fileId: sound.waveformDataFileId,
+        path: "sound.waveformDataFileId",
+        allowedTypes: SOUND_FILE_REFERENCE_TYPES.waveformDataFileId,
+        details: { soundId, waveformDataFileId: sound.waveformDataFileId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+  }
+
+  for (const [videoId, video] of Object.entries(state.videos.items)) {
+    if (video.type !== "video") {
+      continue;
+    }
+
+    {
+      const result = validateFileReference({
+        state,
+        fileId: video.fileId,
+        path: "video.fileId",
+        allowedTypes: VIDEO_FILE_REFERENCE_TYPES.fileId,
+        details: { videoId, fileId: video.fileId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+
+    {
+      const result = validateFileReference({
+        state,
+        fileId: video.thumbnailFileId,
+        path: "video.thumbnailFileId",
+        allowedTypes: VIDEO_FILE_REFERENCE_TYPES.thumbnailFileId,
+        details: { videoId, thumbnailFileId: video.thumbnailFileId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+  }
+
+  for (const [fontId, font] of Object.entries(state.fonts.items)) {
+    if (font.type !== "font") {
+      continue;
+    }
+
+    const result = validateFileReference({
+      state,
+      fileId: font.fileId,
+      path: "font.fileId",
+      allowedTypes: FONT_FILE_REFERENCE_TYPES.fileId,
+      details: { fontId, fileId: font.fileId },
+      errorFactory: createInvariantValidationError,
+    });
+    if (!result.valid) {
+      return result;
+    }
+  }
+
+  for (const [characterId, character] of Object.entries(state.characters.items)) {
+    if (character.type !== "character") {
+      continue;
+    }
+
+    if (character.fileId !== undefined) {
+      const result = validateFileReference({
+        state,
+        fileId: character.fileId,
+        path: "character.fileId",
+        allowedTypes: CHARACTER_FILE_REFERENCE_TYPES.fileId,
+        details: { characterId, fileId: character.fileId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+
+    for (const [spriteId, sprite] of Object.entries(
+      character.sprites?.items || {},
+    )) {
+      if (sprite.type !== "image") {
+        continue;
+      }
+
+      const result = validateFileReference({
+        state,
+        fileId: sprite.fileId,
+        path: "character.sprite.fileId",
+        allowedTypes: CHARACTER_FILE_REFERENCE_TYPES.fileId,
+        details: { characterId, spriteId, fileId: sprite.fileId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+  }
+
   const assertImageReference = ({ layoutId, elementId, field, targetId }) => {
     const image = state.images.items[targetId];
     if (!isPlainObject(image) || image.type === "folder") {
@@ -3397,6 +3734,7 @@ const validateImageCreateData = ({ data, errorFactory }) => {
               "type",
               "name",
               "description",
+              "thumbnailFileId",
               "fileId",
               "fileType",
               "fileSize",
@@ -3422,6 +3760,16 @@ const validateImageCreateData = ({ data, errorFactory }) => {
   }
 
   if (data.type === "image") {
+    if (
+      data.thumbnailFileId !== undefined &&
+      !isNonEmptyString(data.thumbnailFileId)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.thumbnailFileId must be a non-empty string when provided",
+      );
+    }
+
     if (!isNonEmptyString(data.fileId)) {
       return invalidFromErrorFactory(errorFactory, "payload.data.fileId must be a non-empty string");
     }
@@ -3902,6 +4250,108 @@ const validateFontUpdateData = ({ data, errorFactory }) => {
   }
 };
 
+const validateFileCreateData = ({ data, errorFactory }) => {
+  if (!isPlainObject(data)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data must be an object",
+    );
+  }
+
+  if (data.type !== "folder" && !FILE_ITEM_TYPES.includes(data.type)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.type must be 'folder' or a supported file type",
+    );
+  }
+
+  {
+    const result = validateAllowedKeys({
+      value: data,
+      allowedKeys:
+        data.type === "folder"
+          ? ["type", "name"]
+          : ["type", "mimeType", "size", "sha256"],
+      path: "payload.data",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (data.type === "folder") {
+    if (!isNonEmptyString(data.name)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.name must be a non-empty string",
+      );
+    }
+    return;
+  }
+
+  if (!isNonEmptyString(data.mimeType)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.mimeType must be a non-empty string",
+    );
+  }
+
+  if (!isFiniteNumber(data.size)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.size must be a finite number",
+    );
+  }
+
+  if (!isNonEmptyString(data.sha256)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.sha256 must be a non-empty string",
+    );
+  }
+};
+
+const validateReferencedFilesInData = ({
+  state,
+  data,
+  fields,
+  fieldTypes = {},
+  nullableFields = [],
+  details = {},
+  errorFactory = createPreconditionValidationError,
+}) => {
+  for (const field of fields) {
+    const fileId = data[field];
+
+    if (fileId === undefined) {
+      continue;
+    }
+
+    if (fileId === null && nullableFields.includes(field)) {
+      continue;
+    }
+
+    const result = validateFileReference({
+      state,
+      fileId,
+      path: `payload.data.${field}`,
+      allowedTypes: fieldTypes[field],
+      details: {
+        ...details,
+        field,
+        fileId,
+      },
+      errorFactory,
+    });
+    if (!result.valid) {
+      return result;
+    }
+  }
+
+  return VALID_RESULT;
+};
+
 const validateColorCreateData = ({ data, errorFactory }) => {
   if (!isPlainObject(data)) {
     return invalidFromErrorFactory(errorFactory, "payload.data must be an object");
@@ -5092,6 +5542,8 @@ const createFolderedCollectionCommandDefinitions = ({
   }),
   validateCreateState = () => {},
   validateUpdateState = () => {},
+  validateDeleteState = () => {},
+  includeUpdate = true,
 }) => {
   const existingMessage = `payload.${idField} must reference an existing ${itemLabel}`;
   const duplicateMessage = `payload.${idField} must not already exist`;
@@ -5220,68 +5672,72 @@ const createFolderedCollectionCommandDefinitions = ({
         return state;
       },
     },
-    {
-      type: `${familyName}.update`,
-      validatePayload: ({ payload }) => {
-        let result = captureValidation(() =>
-          validateExactKeys({
-            value: payload,
-            expectedKeys: [idField, "data"],
-            path: "payload",
-            errorFactory: createPayloadValidationError,
-          }),
-        );
-        if (!result.valid) {
-          return result;
-        }
-
-        if (!isNonEmptyString(payload[idField])) {
-          return invalidPayload(
-            `payload.${idField} must be a non-empty string`,
-          );
-        }
-
-        result = captureValidation(() =>
-          updateDataValidator({
-            data: payload.data,
-            errorFactory: createPayloadValidationError,
-          }),
-        );
-        if (!result.valid) {
-          return result;
-        }
-
-        return VALID_RESULT;
-      },
-      validateAgainstState: ({ state, payload }) => {
-        const currentItem = state[collectionKey].items[payload[idField]];
-        if (!isPlainObject(currentItem)) {
-          return invalidPrecondition(existingMessage);
-        }
-
-        const result = captureValidation(() =>
-          validateUpdateState({
-            state,
-            payload,
-            currentItem,
-          }),
-        );
-        if (!result.valid) {
-          return result;
-        }
-
-        return VALID_RESULT;
-      },
-      reduce: ({ state, payload }) => {
-        const currentItem = state[collectionKey].items[payload[idField]];
-        state[collectionKey].items[payload[idField]] = updateItem({
-          state,
-          payload,
-          currentItem,
-        });
-        return state;
-      },
-    },
+    ...(includeUpdate
+      ? [
+          {
+            type: `${familyName}.update`,
+            validatePayload: ({ payload }) => {
+              let result = captureValidation(() =>
+                validateExactKeys({
+                  value: payload,
+                  expectedKeys: [idField, "data"],
+                  path: "payload",
+                  errorFactory: createPayloadValidationError,
+                }),
+              );
+              if (!result.valid) {
+                return result;
+              }
+
+              if (!isNonEmptyString(payload[idField])) {
+                return invalidPayload(
+                  `payload.${idField} must be a non-empty string`,
+                );
+              }
+
+              result = captureValidation(() =>
+                updateDataValidator({
+                  data: payload.data,
+                  errorFactory: createPayloadValidationError,
+                }),
+              );
+              if (!result.valid) {
+                return result;
+              }
+
+              return VALID_RESULT;
+            },
+            validateAgainstState: ({ state, payload }) => {
+              const currentItem = state[collectionKey].items[payload[idField]];
+              if (!isPlainObject(currentItem)) {
+                return invalidPrecondition(existingMessage);
+              }
+
+              const result = captureValidation(() =>
+                validateUpdateState({
+                  state,
+                  payload,
+                  currentItem,
+                }),
+              );
+              if (!result.valid) {
+                return result;
+              }
+
+              return VALID_RESULT;
+            },
+            reduce: ({ state, payload }) => {
+              const currentItem = state[collectionKey].items[payload[idField]];
+              state[collectionKey].items[payload[idField]] = updateItem({
+                state,
+                payload,
+                currentItem,
+              });
+              return state;
+            },
+          },
+        ]
+      : []),
     {
       type: `${familyName}.delete`,
       validatePayload: ({ payload }) => {
@@ -5320,6 +5776,16 @@ const createFolderedCollectionCommandDefinitions = ({
           }
         }
 
+        const result = captureValidation(() =>
+          validateDeleteState({
+            state,
+            payload,
+          }),
+        );
+        if (!result.valid) {
+          return result;
+        }
+
         return VALID_RESULT;
       },
       reduce: ({ state, payload }) => {
@@ -5479,6 +5945,143 @@ const getCharacterSpriteCollection = ({ state, characterId }) =>
 const getLayoutElementCollection = ({ state, layoutId }) =>
   state.layouts.items[layoutId]?.elements;
 
+const findReferencedFileUsage = ({ state, fileId }) => {
+  for (const [imageId, image] of Object.entries(state.images.items)) {
+    if (image.type !== "image") {
+      continue;
+    }
+
+    if (image.fileId === fileId) {
+      return {
+        kind: "image",
+        field: "fileId",
+        ownerId: imageId,
+      };
+    }
+
+    if (image.thumbnailFileId === fileId) {
+      return {
+        kind: "image",
+        field: "thumbnailFileId",
+        ownerId: imageId,
+      };
+    }
+  }
+
+  for (const [soundId, sound] of Object.entries(state.sounds.items)) {
+    if (sound.type !== "sound") {
+      continue;
+    }
+
+    if (sound.fileId === fileId) {
+      return {
+        kind: "sound",
+        field: "fileId",
+        ownerId: soundId,
+      };
+    }
+
+    if (sound.waveformDataFileId === fileId) {
+      return {
+        kind: "sound",
+        field: "waveformDataFileId",
+        ownerId: soundId,
+      };
+    }
+  }
+
+  for (const [videoId, video] of Object.entries(state.videos.items)) {
+    if (video.type !== "video") {
+      continue;
+    }
+
+    if (video.fileId === fileId) {
+      return {
+        kind: "video",
+        field: "fileId",
+        ownerId: videoId,
+      };
+    }
+
+    if (video.thumbnailFileId === fileId) {
+      return {
+        kind: "video",
+        field: "thumbnailFileId",
+        ownerId: videoId,
+      };
+    }
+  }
+
+  for (const [fontId, font] of Object.entries(state.fonts.items)) {
+    if (font.type !== "font") {
+      continue;
+    }
+
+    if (font.fileId === fileId) {
+      return {
+        kind: "font",
+        field: "fileId",
+        ownerId: fontId,
+      };
+    }
+  }
+
+  for (const [characterId, character] of Object.entries(state.characters.items)) {
+    if (character.type !== "character") {
+      continue;
+    }
+
+    if (character.fileId === fileId) {
+      return {
+        kind: "character",
+        field: "fileId",
+        ownerId: characterId,
+      };
+    }
+
+    for (const [spriteId, sprite] of Object.entries(
+      character.sprites?.items || {},
+    )) {
+      if (sprite.type !== "image") {
+        continue;
+      }
+
+      if (sprite.fileId === fileId) {
+        return {
+          kind: "character.sprite",
+          field: "fileId",
+          ownerId: spriteId,
+          characterId,
+        };
+      }
+    }
+  }
+
+  return null;
+};
+
+const collectDeletedFileIds = ({ state, fileIds }) => {
+  const deletedIds = new Set();
+
+  for (const fileId of fileIds) {
+    const node = findTreeNode({
+      nodes: state.files.tree,
+      nodeId: fileId,
+    });
+
+    if (!node) {
+      deletedIds.add(fileId);
+      continue;
+    }
+
+    for (const deletedId of collectTreeDescendantIds({ node })) {
+      deletedIds.add(deletedId);
+    }
+  }
+
+  return deletedIds;
+};
+
 const COMMAND_DEFINITIONS = [
   {
     type: "project.create",
@@ -5503,6 +6106,51 @@ const COMMAND_DEFINITIONS = [
     validateAgainstState: () => {},
     reduce: ({ payload }) => structuredClone(payload.state),
   },
+  ...createFolderedCollectionCommandDefinitions({
+    familyName: "file",
+    collectionKey: "files",
+    idField: "fileId",
+    itemLabel: "file item",
+    createDataValidator: validateFileCreateData,
+    updateDataValidator: () => VALID_RESULT,
+    includeUpdate: false,
+    createItem: ({ payload }) =>
+      payload.data.type === "folder"
+        ? {
+            id: payload.fileId,
+            type: "folder",
+            name: payload.data.name,
+          }
+        : {
+            id: payload.fileId,
+            type: payload.data.type,
+            mimeType: payload.data.mimeType,
+            size: payload.data.size,
+            sha256: payload.data.sha256,
+          },
+    validateDeleteState: ({ state, payload }) => {
+      for (const fileId of collectDeletedFileIds({
+        state,
+        fileIds: payload.fileIds,
+      })) {
+        const usage = findReferencedFileUsage({ state, fileId });
+        if (!usage) {
+          continue;
+        }
+
+        return invalidPrecondition(
+          `payload.fileIds cannot delete a referenced file`,
+          {
+            fileId,
+            referenceKind: usage.kind,
+            referenceField: usage.field,
+            referenceOwnerId: usage.ownerId,
+            ...(usage.characterId ? { characterId: usage.characterId } : {}),
+          },
+        );
+      }
+    },
+  }),
   {
     type: "story.update",
     validatePayload: ({ payload }) => {
@@ -6849,6 +7497,21 @@ const COMMAND_DEFINITIONS = [
           );
         }
       }
+
+      if (payload.data.type === "image") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId", "thumbnailFileId"],
+          fieldTypes: IMAGE_FILE_REFERENCE_TYPES,
+          details: {
+            imageId: payload.imageId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const nextImage = {
@@ -6863,6 +7526,9 @@ const COMMAND_DEFINITIONS = [
 
       if (payload.data.type === "image") {
         nextImage.fileId = payload.data.fileId;
+        if (payload.data.thumbnailFileId !== undefined) {
+          nextImage.thumbnailFileId = payload.data.thumbnailFileId;
+        }
         if (payload.data.fileType !== undefined) {
           nextImage.fileType = payload.data.fileType;
         }
@@ -6936,6 +7602,7 @@ const COMMAND_DEFINITIONS = [
       if (
         currentImage.type === "folder" &&
         (payload.data.fileId !== undefined ||
+          payload.data.thumbnailFileId !== undefined ||
           payload.data.fileType !== undefined ||
           payload.data.fileSize !== undefined ||
           payload.data.width !== undefined ||
@@ -6945,6 +7612,21 @@ const COMMAND_DEFINITIONS = [
           "folder image items cannot update file fields",
         );
       }
+
+      if (currentImage.type === "image") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId", "thumbnailFileId"],
+          fieldTypes: IMAGE_FILE_REFERENCE_TYPES,
+          details: {
+            imageId: payload.imageId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const currentImage = state.images.items[payload.imageId];
@@ -7249,6 +7931,22 @@ const COMMAND_DEFINITIONS = [
           );
         }
       }
+
+      if (payload.data.type === "sound") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId", "waveformDataFileId"],
+          fieldTypes: SOUND_FILE_REFERENCE_TYPES,
+          nullableFields: ["waveformDataFileId"],
+          details: {
+            soundId: payload.soundId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const nextSound = {
@@ -7345,6 +8043,22 @@ const COMMAND_DEFINITIONS = [
           "folder sound items cannot update file fields",
         );
       }
+
+      if (currentSound.type === "sound") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId", "waveformDataFileId"],
+          fieldTypes: SOUND_FILE_REFERENCE_TYPES,
+          nullableFields: ["waveformDataFileId"],
+          details: {
+            soundId: payload.soundId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const currentSound = state.sounds.items[payload.soundId];
@@ -7649,6 +8363,21 @@ const COMMAND_DEFINITIONS = [
           );
         }
       }
+
+      if (payload.data.type === "video") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId", "thumbnailFileId"],
+          fieldTypes: VIDEO_FILE_REFERENCE_TYPES,
+          details: {
+            videoId: payload.videoId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const nextVideo = {
@@ -7747,6 +8476,21 @@ const COMMAND_DEFINITIONS = [
           "folder video items cannot update file fields",
         );
       }
+
+      if (currentVideo.type === "video") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId", "thumbnailFileId"],
+          fieldTypes: VIDEO_FILE_REFERENCE_TYPES,
+          details: {
+            videoId: payload.videoId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const currentVideo = state.videos.items[payload.videoId];
@@ -8431,6 +9175,21 @@ const COMMAND_DEFINITIONS = [
           );
         }
       }
+
+      if (payload.data.type === "font") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId"],
+          fieldTypes: FONT_FILE_REFERENCE_TYPES,
+          details: {
+            fontId: payload.fontId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const nextFont = {
@@ -8517,6 +9276,21 @@ const COMMAND_DEFINITIONS = [
           "folder font items cannot update font fields",
         );
       }
+
+      if (currentFont.type === "font") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId"],
+          fieldTypes: FONT_FILE_REFERENCE_TYPES,
+          details: {
+            fontId: payload.fontId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const currentFont = state.fonts.items[payload.fontId];
@@ -9294,7 +10068,50 @@ const COMMAND_DEFINITIONS = [
 
       return item;
     },
-    validateUpdateState: ({ payload, currentItem }) => {
+    validateCreateState: ({ state, payload }) => {
+      if (payload.data.type !== "character") {
+        return;
+      }
+
+      if (payload.data.fileId !== undefined) {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId"],
+          fieldTypes: CHARACTER_FILE_REFERENCE_TYPES,
+          details: {
+            characterId: payload.characterId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
+
+      for (const [spriteId, sprite] of Object.entries(
+        payload.data.sprites?.items || {},
+      )) {
+        if (sprite.type !== "image") {
+          continue;
+        }
+
+        const result = validateFileReference({
+          state,
+          fileId: sprite.fileId,
+          path: "payload.data.sprites.items.*.fileId",
+          allowedTypes: CHARACTER_FILE_REFERENCE_TYPES.fileId,
+          details: {
+            characterId: payload.characterId,
+            spriteId,
+            fileId: sprite.fileId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
+    },
+    validateUpdateState: ({ state, payload, currentItem }) => {
       if (
         currentItem.type === "folder" &&
         Object.keys(payload.data).some((key) => key !== "name")
@@ -9303,6 +10120,21 @@ const COMMAND_DEFINITIONS = [
           "folder character items cannot update character fields",
         );
       }
+
+      if (currentItem.type === "character") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId"],
+          fieldTypes: CHARACTER_FILE_REFERENCE_TYPES,
+          details: {
+            characterId: payload.characterId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
   }),
   ...createFolderedCollectionCommandDefinitions({
@@ -9446,6 +10278,22 @@ const COMMAND_DEFINITIONS = [
           );
         }
       }
+
+      if (payload.data.type === "image") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId"],
+          fieldTypes: CHARACTER_FILE_REFERENCE_TYPES,
+          details: {
+            characterId: payload.characterId,
+            spriteId: payload.spriteId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const collection = getCharacterSpriteCollection({
@@ -9538,6 +10386,22 @@ const COMMAND_DEFINITIONS = [
           "folder sprite items cannot update image fields",
         );
       }
+
+      if (currentItem.type === "image") {
+        const result = validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId"],
+          fieldTypes: CHARACTER_FILE_REFERENCE_TYPES,
+          details: {
+            characterId: payload.characterId,
+            spriteId: payload.spriteId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
     },
     reduce: ({ state, payload }) => {
       const collection = getCharacterSpriteCollection({