@routevn/creator-model 1.7.2 → 1.8.0

package/package.json

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

package/src/model.js

@@ -392,7 +392,7 @@ const LAYOUT_ELEMENT_BASE_TYPES = [
   "container-ref-confirm-dialog-ok",
   "container-ref-confirm-dialog-cancel",
 ];
-export const SCHEMA_VERSION = 7;
+export const SCHEMA_VERSION = 8;
 const LAYOUT_CONTAINER_ELEMENT_TYPES = [
   "folder",
   "container",
@@ -404,6 +404,18 @@ const LAYOUT_CONTAINER_ELEMENT_TYPES = [
   "container-ref-confirm-dialog-ok",
   "container-ref-confirm-dialog-cancel",
 ];
+const LAYOUT_TEXT_CONTENT_ELEMENT_TYPES = [
+  "text",
+  "text-revealing",
+  "text-ref-character-name",
+  "text-revealing-ref-dialogue-content",
+  "text-ref-choice-item-content",
+  "text-ref-save-load-slot-date",
+  "text-ref-dialogue-line-character-name",
+  "text-ref-dialogue-line-content",
+  "text-ref-history-line-character-name",
+  "text-ref-history-line-content",
+];
 const DOMAIN_ERROR_KIND_BY_NAME = {
   PayloadValidationError: "payload",
   PreconditionValidationError: "precondition",
@@ -496,6 +508,15 @@ const isVariableReferenceTarget = (state, variableId) => {
   return isPlainObject(variable) && variable.type !== "folder";
 };
 
+const isStringVariableReferenceTarget = (state, variableId) => {
+  const variable = state.variables.items[variableId];
+  return (
+    isPlainObject(variable) &&
+    variable.type === "variable" &&
+    variable.variableType === "string"
+  );
+};
+
 const LAYOUT_ITEM_TARGET_SET = new Set(["item.savedAt"]);
 const LAYOUT_DIALOGUE_TARGET_SET = new Set(["dialogue.characterId"]);
 const RUNTIME_TARGET_DOT_PATTERN = /^runtime\.([A-Za-z_$][A-Za-z0-9_$]*)$/;
@@ -3410,6 +3431,251 @@ const validateLayoutElementBlur = ({ blur, path, errorFactory }) => {
   }
 };
 
+const LAYOUT_TEXT_REVEAL_INDICATOR_ELEMENT_TYPES = [
+  "text-revealing",
+  "text-revealing-ref-dialogue-content",
+];
+
+const validateLayoutTextRevealIndicatorVisual = ({
+  visual,
+  path,
+  errorFactory,
+}) => {
+  if (!isPlainObject(visual)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be an object when provided`,
+    );
+  }
+
+  {
+    const result = validateAllowedKeys({
+      value: visual,
+      allowedKeys: [
+        "kind",
+        "imageId",
+        "resourceId",
+        "animationName",
+        "width",
+        "height",
+        "offsetX",
+        "offsetY",
+      ],
+      path,
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  const kind =
+    visual.kind === "spritesheet" ||
+    visual.resourceId !== undefined ||
+    visual.animationName !== undefined
+      ? "spritesheet"
+      : "image";
+
+  if (
+    visual.kind !== undefined &&
+    visual.kind !== "image" &&
+    visual.kind !== "spritesheet"
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.kind must be 'image' or 'spritesheet' when provided`,
+    );
+  }
+
+  if (kind === "image" && !isNonEmptyString(visual.imageId)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.imageId must be a non-empty string`,
+    );
+  }
+
+  if (kind === "spritesheet") {
+    if (!isNonEmptyString(visual.resourceId)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.resourceId must be a non-empty string`,
+      );
+    }
+
+    if (!isNonEmptyString(visual.animationName)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.animationName must be a non-empty string`,
+      );
+    }
+  }
+
+  for (const key of ["width", "height"]) {
+    if (
+      visual[key] !== undefined &&
+      (!isFiniteNumber(visual[key]) || visual[key] <= 0)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.${key} must be a finite number greater than 0 when provided`,
+      );
+    }
+  }
+
+  for (const key of ["offsetX", "offsetY"]) {
+    if (visual[key] !== undefined && !isFiniteNumber(visual[key])) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.${key} must be a finite number when provided`,
+      );
+    }
+  }
+};
+
+const validateLayoutTextRevealIndicator = ({
+  indicator,
+  path,
+  errorFactory,
+}) => {
+  if (!isPlainObject(indicator)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be an object when provided`,
+    );
+  }
+
+  {
+    const result = validateAllowedKeys({
+      value: indicator,
+      allowedKeys: ["revealing", "complete", "offsetX", "offsetY"],
+      path,
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  for (const key of ["revealing", "complete"]) {
+    if (indicator[key] !== undefined) {
+      const result = validateLayoutTextRevealIndicatorVisual({
+        visual: indicator[key],
+        path: `${path}.${key}`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  }
+
+  for (const key of ["offsetX", "offsetY"]) {
+    if (indicator[key] !== undefined && !isFiniteNumber(indicator[key])) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.${key} must be a finite number when provided`,
+      );
+    }
+  }
+};
+
+const validateLayoutTextContent = ({ content, path, errorFactory }) => {
+  if (!Array.isArray(content)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be an array when provided`,
+    );
+  }
+
+  for (let index = 0; index < content.length; index += 1) {
+    const item = content[index];
+    const itemPath = `${path}[${index}]`;
+
+    if (!isPlainObject(item)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath} must be an object`,
+      );
+    }
+
+    {
+      const result = validateAllowedKeys({
+        value: item,
+        allowedKeys: ["text", "reference"],
+        path: itemPath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    const hasText = Object.hasOwn(item, "text");
+    const hasReference = Object.hasOwn(item, "reference");
+
+    if (hasText === hasReference) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath} must include exactly one of text or reference`,
+      );
+    }
+
+    if (hasText) {
+      if (!isString(item.text)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.text must be a string`,
+        );
+      }
+      continue;
+    }
+
+    if (!isPlainObject(item.reference)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.reference must be an object`,
+      );
+    }
+
+    {
+      const result = validateAllowedKeys({
+        value: item.reference,
+        allowedKeys: ["resourceId"],
+        path: `${itemPath}.reference`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!isNonEmptyString(item.reference.resourceId)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.reference.resourceId must be a non-empty string`,
+      );
+    }
+  }
+};
+
+const getLayoutTextContentReferenceEntries = (content) => {
+  if (!Array.isArray(content)) {
+    return [];
+  }
+
+  const entries = [];
+  for (let index = 0; index < content.length; index += 1) {
+    const resourceId = content[index]?.reference?.resourceId;
+    if (resourceId !== undefined) {
+      entries.push({
+        index,
+        resourceId,
+      });
+    }
+  }
+  return entries;
+};
+
 const validateLayoutElementData = ({
   data,
   path,
@@ -3438,9 +3704,11 @@ const validateLayoutElementData = ({
     "fill",
     "border",
     "text",
+    "content",
     "textStyle",
     "displaySpeed",
     "revealEffect",
+    "indicator",
     "resourceId",
     "animationName",
     "imageId",
@@ -3619,6 +3887,52 @@ const validateLayoutElementData = ({
     }
   }
 
+  if (data.content !== undefined) {
+    {
+      const result = validateLayoutTextContent({
+        content: data.content,
+        path: `${path}.content`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (
+      data.type !== undefined &&
+      !LAYOUT_TEXT_CONTENT_ELEMENT_TYPES.includes(data.type)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.content can only be provided for text elements`,
+      );
+    }
+  }
+
+  if (data.indicator !== undefined) {
+    {
+      const result = validateLayoutTextRevealIndicator({
+        indicator: data.indicator,
+        path: `${path}.indicator`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (
+      data.type !== undefined &&
+      !LAYOUT_TEXT_REVEAL_INDICATOR_ELEMENT_TYPES.includes(data.type)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.indicator can only be provided for text revealing elements`,
+      );
+    }
+  }
+
   for (const key of [
     "text",
     "resourceId",
@@ -4134,9 +4448,11 @@ const validateLayoutElementItems = ({ items, path, errorFactory }) => {
           "fill",
           "border",
           "text",
+          "content",
           "textStyle",
           "displaySpeed",
           "revealEffect",
+          "indicator",
           "resourceId",
           "animationName",
           "particleId",
@@ -4254,6 +4570,7 @@ const validateCharacterItems = ({ items, path, errorFactory }) => {
                 "tagIds",
                 "spriteGroups",
                 "shortcut",
+                "nameVariableId",
                 "fileId",
                 "sprites",
               ],
@@ -4326,6 +4643,16 @@ const validateCharacterItems = ({ items, path, errorFactory }) => {
         );
       }
 
+      if (
+        item.nameVariableId !== undefined &&
+        !isNonEmptyString(item.nameVariableId)
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.nameVariableId must be a non-empty string when provided`,
+        );
+      }
+
       if (item.fileId !== undefined && !isNonEmptyString(item.fileId)) {
         return invalidFromErrorFactory(
           errorFactory,
@@ -4781,6 +5108,13 @@ const applyCharacterUpdate = ({ currentItem, data }) => {
     }
   }
 
+  if (
+    Object.hasOwn(data, "nameVariableId") &&
+    (data.nameVariableId === undefined || data.nameVariableId === "")
+  ) {
+    delete nextItem.nameVariableId;
+  }
+
   return nextItem;
 };
 
@@ -6495,6 +6829,28 @@ const validateTransformPreviewImageReferences = ({
   return VALID_RESULT;
 };
 
+const validateStringVariableReference = ({
+  state,
+  variableId,
+  path,
+  details = {},
+  errorFactory = createPreconditionValidationError,
+}) => {
+  if (variableId === undefined || variableId === null || variableId === "") {
+    return VALID_RESULT;
+  }
+
+  if (!isStringVariableReferenceTarget(state, variableId)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must reference an existing string variable`,
+      details,
+    );
+  }
+
+  return VALID_RESULT;
+};
+
 export const assertInvariants = ({ state }) => {
   if (!isPlainObject(state)) {
     return invalidInvariant("state must be an object");
@@ -6909,6 +7265,19 @@ export const assertInvariants = ({ state }) => {
       }
     }
 
+    if (character.nameVariableId !== undefined) {
+      const result = validateStringVariableReference({
+        state,
+        variableId: character.nameVariableId,
+        path: "character.nameVariableId",
+        details: { characterId, variableId: character.nameVariableId },
+        errorFactory: createInvariantValidationError,
+      });
+      if (!result.valid) {
+        return result;
+      }
+    }
+
     {
       const result = validateTagIdsAgainstScope({
         state,
@@ -7358,15 +7727,16 @@ export const assertInvariants = ({ state }) => {
     elementId,
     targetId,
     animationName,
+    fieldPrefix = "",
   }) => {
     const spritesheet = state.spritesheets?.items?.[targetId];
     if (!isPlainObject(spritesheet) || spritesheet.type === "folder") {
       return invalidInvariant(
-        `${ownerLabel} element resourceId must reference an existing non-folder spritesheet`,
+        `${ownerLabel} element ${fieldPrefix}resourceId must reference an existing non-folder spritesheet`,
         {
           [ownerIdField]: ownerId,
           elementId,
-          field: "resourceId",
+          field: `${fieldPrefix}resourceId`,
           targetId,
         },
       );
@@ -7377,11 +7747,11 @@ export const assertInvariants = ({ state }) => {
       !isPlainObject(spritesheet.animations?.[animationName])
     ) {
       return invalidInvariant(
-        `${ownerLabel} element animationName must reference an existing spritesheet animation`,
+        `${ownerLabel} element ${fieldPrefix}animationName must reference an existing spritesheet animation`,
         {
           [ownerIdField]: ownerId,
           elementId,
-          field: "animationName",
+          field: `${fieldPrefix}animationName`,
           targetId: animationName,
         },
       );
@@ -7480,6 +7850,43 @@ export const assertInvariants = ({ state }) => {
           }
         }
 
+        for (const stateName of ["revealing", "complete"]) {
+          const visual = element.indicator?.[stateName];
+          if (
+            visual?.kind === "spritesheet" ||
+            visual?.resourceId !== undefined ||
+            visual?.animationName !== undefined
+          ) {
+            const result = assertSpritesheetAnimationReference({
+              ownerIdField,
+              ownerId,
+              ownerLabel,
+              elementId,
+              targetId: visual.resourceId,
+              animationName: visual.animationName,
+              fieldPrefix: `indicator.${stateName}.`,
+            });
+            if (!result.valid) {
+              return result;
+            }
+            continue;
+          }
+
+          if (visual?.imageId !== undefined) {
+            const result = assertImageReference({
+              ownerIdField,
+              ownerId,
+              ownerLabel,
+              elementId,
+              field: `indicator.${stateName}.imageId`,
+              targetId: visual.imageId,
+            });
+            if (!result.valid) {
+              return result;
+            }
+          }
+        }
+
         for (const field of ["hoverSoundId", "clickSoundId"]) {
           if (element[field] !== undefined) {
             const result = assertSoundReference({
@@ -7577,6 +7984,23 @@ export const assertInvariants = ({ state }) => {
           }
         }
 
+        for (const {
+          index,
+          resourceId,
+        } of getLayoutTextContentReferenceEntries(element.content)) {
+          if (!isVariableReferenceTarget(state, resourceId)) {
+            return invalidInvariant(
+              `${ownerLabel} element content.${index}.reference.resourceId must reference an existing non-folder variable`,
+              {
+                [ownerIdField]: ownerId,
+                elementId,
+                field: `content.${index}.reference.resourceId`,
+                targetId: resourceId,
+              },
+            );
+          }
+        }
+
         if (element.variableId !== undefined) {
           const result = assertVariableReference({
             ownerIdField,
@@ -10639,6 +11063,7 @@ const validateCharacterCreateData = ({ data, errorFactory }) => {
               "tagIds",
               "spriteGroups",
               "shortcut",
+              "nameVariableId",
               "fileId",
               "sprites",
             ],
@@ -10694,6 +11119,16 @@ const validateCharacterCreateData = ({ data, errorFactory }) => {
       );
     }
 
+    if (
+      data.nameVariableId !== undefined &&
+      !isNonEmptyString(data.nameVariableId)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.nameVariableId must be a non-empty string when provided",
+      );
+    }
+
     if (data.fileId !== undefined && !isNonEmptyString(data.fileId)) {
       return invalidFromErrorFactory(
         errorFactory,
@@ -10735,6 +11170,7 @@ const validateCharacterUpdateData = ({ data, errorFactory }) => {
         "tagIds",
         "spriteGroups",
         "shortcut",
+        "nameVariableId",
         "fileId",
       ],
       path: "payload.data",
@@ -10773,6 +11209,17 @@ const validateCharacterUpdateData = ({ data, errorFactory }) => {
     );
   }
 
+  if (
+    data.nameVariableId !== undefined &&
+    data.nameVariableId !== "" &&
+    !isNonEmptyString(data.nameVariableId)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.nameVariableId must be a non-empty string when provided",
+    );
+  }
+
   {
     const result = validateOptionalUniqueIdArray({
       value: data.tagIds,
@@ -11298,6 +11745,36 @@ const validateVisualElementReferenceTargets = ({
     );
   }
 
+  if (
+    data.indicator !== undefined &&
+    !LAYOUT_TEXT_REVEAL_INDICATOR_ELEMENT_TYPES.includes(data.type)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${ownerLabel} element indicator can only be provided for text revealing elements`,
+      {
+        [ownerIdField]: ownerId,
+        elementId,
+        field: "indicator",
+      },
+    );
+  }
+
+  if (
+    data.content !== undefined &&
+    !LAYOUT_TEXT_CONTENT_ELEMENT_TYPES.includes(data.type)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${ownerLabel} element content can only be provided for text elements`,
+      {
+        [ownerIdField]: ownerId,
+        elementId,
+        field: "content",
+      },
+    );
+  }
+
   if (
     data.type === "spritesheet-animation" ||
     data.resourceId !== undefined ||
@@ -11398,6 +11875,66 @@ const validateVisualElementReferenceTargets = ({
     }
   }
 
+  for (const stateName of ["revealing", "complete"]) {
+    const visual = data.indicator?.[stateName];
+    if (
+      visual?.kind === "spritesheet" ||
+      visual?.resourceId !== undefined ||
+      visual?.animationName !== undefined
+    ) {
+      const spritesheet = state.spritesheets?.items?.[visual.resourceId];
+      if (!isPlainObject(spritesheet) || spritesheet.type === "folder") {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${ownerLabel} element indicator.${stateName}.resourceId must reference an existing non-folder spritesheet`,
+          {
+            [ownerIdField]: ownerId,
+            elementId,
+            field: `indicator.${stateName}.resourceId`,
+            targetId: visual.resourceId,
+          },
+        );
+      }
+
+      if (
+        !isNonEmptyString(visual.animationName) ||
+        !isPlainObject(spritesheet.animations?.[visual.animationName])
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${ownerLabel} element indicator.${stateName}.animationName must reference an existing spritesheet animation`,
+          {
+            [ownerIdField]: ownerId,
+            elementId,
+            field: `indicator.${stateName}.animationName`,
+            targetId: visual.animationName,
+          },
+        );
+      }
+
+      continue;
+    }
+
+    const imageId = visual?.imageId;
+    if (imageId === undefined) {
+      continue;
+    }
+
+    const image = state.images.items[imageId];
+    if (!isPlainObject(image) || image.type === "folder") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${ownerLabel} element indicator.${stateName}.imageId must reference an existing non-folder image`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: `indicator.${stateName}.imageId`,
+          targetId: imageId,
+        },
+      );
+    }
+  }
+
   if (data.hoverSoundId !== undefined) {
     const sound = state.sounds.items[data.hoverSoundId];
     if (!isPlainObject(sound) || sound.type === "folder") {
@@ -11625,6 +12162,23 @@ const validateVisualElementReferenceTargets = ({
     }
   }
 
+  for (const { index, resourceId } of getLayoutTextContentReferenceEntries(
+    data.content,
+  )) {
+    if (!isVariableReferenceTarget(state, resourceId)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${ownerLabel} element content.${index}.reference.resourceId must reference an existing non-folder variable`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: `content.${index}.reference.resourceId`,
+          targetId: resourceId,
+        },
+      );
+    }
+  }
+
   if (data.variableId !== undefined) {
     if (!isVariableReferenceTarget(state, data.variableId)) {
       return invalidFromErrorFactory(
@@ -17072,6 +17626,10 @@ const COMMAND_DEFINITIONS = [
         item.fileId = payload.data.fileId;
       }
 
+      if (payload.data.nameVariableId !== undefined) {
+        item.nameVariableId = payload.data.nameVariableId;
+      }
+
       assignOptionalTagIds({
         target: item,
         tagIds: payload.data.tagIds,
@@ -17112,6 +17670,21 @@ const COMMAND_DEFINITIONS = [
         }
       }
 
+      {
+        const result = validateStringVariableReference({
+          state,
+          variableId: payload.data.nameVariableId,
+          path: "payload.data.nameVariableId",
+          details: {
+            characterId: payload.characterId,
+            variableId: payload.data.nameVariableId,
+          },
+        });
+        if (!result.valid) {
+          return result;
+        }
+      }
+
       {
         const result = validateTagIdsAgainstScope({
           state,
@@ -17217,6 +17790,21 @@ const COMMAND_DEFINITIONS = [
           return result;
         }
 
+        if (Object.hasOwn(payload.data, "nameVariableId")) {
+          const variableResult = validateStringVariableReference({
+            state,
+            variableId: payload.data.nameVariableId,
+            path: "payload.data.nameVariableId",
+            details: {
+              characterId: payload.characterId,
+              variableId: payload.data.nameVariableId,
+            },
+          });
+          if (!variableResult.valid) {
+            return variableResult;
+          }
+        }
+
         {
           const tagResult = validateTagIdsAgainstScope({
             state,
@@ -17617,6 +18205,16 @@ const COMMAND_DEFINITIONS = [
             "payload.parentId must reference a folder sprite item",
           );
         }
+
+        const parentNode = findTreeNode({
+          nodes: collection.tree,
+          nodeId: parentId,
+        });
+        if (!parentNode) {
+          return invalidPrecondition(
+            "payload.parentId must reference a folder sprite item in the tree",
+          );
+        }
       }
 
       if (payload.positionTargetId !== undefined) {
@@ -17626,6 +18224,16 @@ const COMMAND_DEFINITIONS = [
           );
         }
 
+        const targetNode = findTreeNode({
+          nodes: collection.tree,
+          nodeId: payload.positionTargetId,
+        });
+        if (!targetNode) {
+          return invalidPrecondition(
+            "payload.positionTargetId must reference an existing sprite item in the tree",
+          );
+        }
+
         const targetParentId = getNodeParentId({
           tree: collection.tree,
           nodeId: payload.positionTargetId,
@@ -17957,6 +18565,11 @@ const COMMAND_DEFINITIONS = [
         nodes: collection.tree,
         nodeId: payload.spriteId,
       });
+      if (!currentNode) {
+        return invalidPrecondition(
+          "payload.spriteId must reference an existing sprite item in the tree",
+        );
+      }
 
       if (payload.parentId !== undefined && payload.parentId !== null) {
         const parentItem = collection.items[payload.parentId];
@@ -17966,6 +18579,16 @@ const COMMAND_DEFINITIONS = [
           );
         }
 
+        const parentNode = findTreeNode({
+          nodes: collection.tree,
+          nodeId: payload.parentId,
+        });
+        if (!parentNode) {
+          return invalidPrecondition(
+            "payload.parentId must reference a folder sprite item in the tree",
+          );
+        }
+
         const descendantIds = new Set(
           collectTreeDescendantIds({
             node: currentNode,
@@ -17992,6 +18615,16 @@ const COMMAND_DEFINITIONS = [
           );
         }
 
+        const targetNode = findTreeNode({
+          nodes: collection.tree,
+          nodeId: payload.positionTargetId,
+        });
+        if (!targetNode) {
+          return invalidPrecondition(
+            "payload.positionTargetId must reference an existing sprite item in the tree",
+          );
+        }
+
         const targetParentId = getNodeParentId({
           tree: collection.tree,
           nodeId: payload.positionTargetId,