@routevn/creator-model 1.1.11 → 1.2.0

package/README.md

@@ -5,6 +5,9 @@ Shared RouteVN domain model package.
 Repo rules and contribution expectations are in
 [GUIDELINES.md](./GUIDELINES.md).
 
+Schema compatibility maintenance rules are in
+[docs/schema-compatibility.md](./docs/schema-compatibility.md).
+
 This repo is intended to be the single source of truth for:
 
 - state validation
@@ -79,6 +82,9 @@ Design rules:
 - pure functions whenever possible
 - command payload shape is validated separately from state-aware preconditions
 - `SCHEMA_VERSION` is the source of truth for persisted command schema versioning
+- `SCHEMA_VERSION` must stay aligned with the minor version from `package.json`
+- patch releases must not change persisted schema compatibility
+- `bun run test:compat` is the required compatibility gate for model changes
 - `processCommand()` is the authoritative state transition
 - model state should contain project-owned runtime data only
 - app-owned metadata like project id, name, and description should stay out of
@@ -190,6 +196,25 @@ YAML Puty specs use [tests/support/putyApi.js](./tests/support/putyApi.js) as a
 small adapter so the declarative `throws:` assertions can stay concise while the
 real public API returns `{ valid: ... }` result objects.
 
+Compatibility fixtures live under `tests/compat/schema-<n>/`.
+
+- `payloads/` fixtures are frozen command payload shapes for that schema version
+- `states/` fixtures are frozen persisted-state snapshots for that schema version
+- `streams/` fixtures are frozen command sequences for that schema version
+- current tests must continue to validate/replay every archived compatibility
+  fixture from the same or older schema versions
+- current schema payload coverage must include `minimal.yaml` and `full.yaml` for
+  every public command type
+
+See also:
+
+- [docs/schema-compatibility.md](./docs/schema-compatibility.md)
+
+Current animation update tween properties support either:
+
+- `keyframes`
+- `auto: { duration, easing }`
+
 ## Current Scope
 
 Currently implemented command types:
@@ -212,6 +237,10 @@ Currently implemented command types:
 - `image.update`
 - `image.delete`
 - `image.move`
+- `spritesheet.create`
+- `spritesheet.update`
+- `spritesheet.delete`
+- `spritesheet.move`
 - `sound.create`
 - `sound.update`
 - `sound.delete`
@@ -260,6 +289,14 @@ Currently implemented command types:
 - `layout.element.update`
 - `layout.element.delete`
 - `layout.element.move`
+- `control.create`
+- `control.update`
+- `control.delete`
+- `control.move`
+- `control.element.create`
+- `control.element.update`
+- `control.element.delete`
+- `control.element.move`
 
 The rest of the future command surface should be added only when full
 validation, preconditions, reducer behavior, and tests are added together.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routevn/creator-model",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -27,10 +27,13 @@
   },
   "scripts": {
     "test": "bunx vitest run",
+    "test:compat": "bunx vitest run tests/compatibility-fixtures.test.js",
     "test:watch": "bunx vitest",
-    "bench": "bun scripts/benchmark-process-command.js"
+    "bench": "bun scripts/benchmark-process-command.js",
+    "generate:compat-fixtures": "node scripts/generate-compat-fixtures.js"
   },
   "devDependencies": {
+    "js-yaml": "^4.1.0",
     "puty": "0.1.2",
     "vitest": "^3.2.1"
   }

package/src/model.js

@@ -21,6 +21,7 @@ const COLLECTION_KEYS = [
   "scenes",
   "files",
   "images",
+  "spritesheets",
   "sounds",
   "videos",
   "animations",
@@ -44,14 +45,23 @@ const normalizeStateCollections = (state) => {
     return state;
   }
 
-  if (state.controls !== undefined) {
+  const missingCollectionKeys = ["spritesheets", "controls"].filter(
+    (key) => state[key] === undefined,
+  );
+
+  if (missingCollectionKeys.length === 0) {
     return state;
   }
 
-  return {
+  const nextState = {
     ...state,
-    controls: createEmptyCollectionState(),
   };
+
+  missingCollectionKeys.forEach((key) => {
+    nextState[key] = createEmptyCollectionState();
+  });
+
+  return nextState;
 };
 const isString = (value) => typeof value === "string";
 const isHexColor = (value) =>
@@ -125,6 +135,7 @@ const LAYOUT_ELEMENT_BASE_TYPES = [
   "container",
   "rect",
   "sprite",
+  "spritesheet-animation",
   "text",
   "text-revealing",
   "slider",
@@ -853,6 +864,207 @@ const validateImageItems = ({ items, path, errorFactory }) => {
   }
 };
 
+const validateSpritesheetAnimationMap = ({
+  animations,
+  path,
+  errorFactory,
+}) => {
+  if (!isPlainObject(animations)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
+  }
+
+  for (const [animationName, animation] of Object.entries(animations)) {
+    const animationPath = `${path}.${animationName}`;
+
+    if (!isNonEmptyString(animationName)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${animationPath} must use a non-empty animation name`,
+      );
+    }
+
+    {
+      const result = validateAllowedKeys({
+        value: animation,
+        allowedKeys: ["frames", "animationSpeed", "loop"],
+        path: animationPath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!Array.isArray(animation.frames)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${animationPath}.frames must be an array`,
+      );
+    }
+
+    for (let index = 0; index < animation.frames.length; index += 1) {
+      const frame = animation.frames[index];
+      if (!Number.isInteger(frame) || frame < 0) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${animationPath}.frames.${index} must be an integer greater than or equal to 0`,
+        );
+      }
+    }
+
+    if (
+      animation.animationSpeed !== undefined &&
+      !isFiniteNumber(animation.animationSpeed)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${animationPath}.animationSpeed must be a finite number when provided`,
+      );
+    }
+
+    if (animation.loop !== undefined && typeof animation.loop !== "boolean") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${animationPath}.loop must be a boolean when provided`,
+      );
+    }
+  }
+
+  return VALID_RESULT;
+};
+
+const validateSpritesheetItems = ({ items, path, errorFactory }) => {
+  for (const [itemId, item] of Object.entries(items)) {
+    const itemPath = `${path}.${itemId}`;
+
+    if (item?.type !== "folder" && item?.type !== "spritesheet") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.type must be 'folder' or 'spritesheet'`,
+      );
+    }
+
+    {
+      const result = validateAllowedKeys({
+        value: item,
+        allowedKeys:
+          item.type === "folder"
+            ? ["id", "type", "name", "description"]
+            : [
+                "id",
+                "type",
+                "name",
+                "description",
+                "thumbnailFileId",
+                "fileId",
+                "fileType",
+                "fileSize",
+                "sheetWidth",
+                "sheetHeight",
+                "frameCount",
+                "width",
+                "height",
+                "jsonData",
+                "animations",
+              ],
+        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 (!isNonEmptyString(item.name)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.name must be a non-empty string`,
+      );
+    }
+
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
+    if (item.type === "spritesheet") {
+      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`,
+        );
+      }
+
+      if (item.fileType !== undefined && !isString(item.fileType)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.fileType must be a string when provided`,
+        );
+      }
+
+      for (const key of [
+        "fileSize",
+        "sheetWidth",
+        "sheetHeight",
+        "frameCount",
+        "width",
+        "height",
+      ]) {
+        if (item[key] !== undefined && !isFiniteNumber(item[key])) {
+          return invalidFromErrorFactory(
+            errorFactory,
+            `${itemPath}.${key} must be a finite number when provided`,
+          );
+        }
+      }
+
+      if (!isPlainObject(item.jsonData)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.jsonData must be an object`,
+        );
+      }
+
+      {
+        const result = validateSpritesheetAnimationMap({
+          animations: item.animations,
+          path: `${itemPath}.animations`,
+          errorFactory,
+        });
+        if (result?.valid === false) {
+          return result;
+        }
+      }
+    }
+  }
+};
+
 const validateSoundItems = ({ items, path, errorFactory }) => {
   for (const [itemId, item] of Object.entries(items)) {
     const itemPath = `${path}.${itemId}`;
@@ -1141,16 +1353,57 @@ const validateAnimationKeyframes = ({ keyframes, path, errorFactory }) => {
   }
 };
 
+const validateAutoTweenProperty = ({ auto, path, errorFactory }) => {
+  {
+    const result = validateAllowedKeys({
+      value: auto,
+      allowedKeys: ["duration", "easing"],
+      path,
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (!("duration" in auto)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.duration is required`,
+    );
+  }
+
+  if (!isFiniteNumber(auto.duration) || auto.duration < 1) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.duration must be a finite number >= 1`,
+    );
+  }
+
+  if (
+    auto.easing !== undefined &&
+    !ANIMATION_EASING_KEYS.includes(auto.easing)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.easing must be a supported Route Graphics easing`,
+    );
+  }
+};
+
 const validateTweenProperty = ({
   config,
   path,
   allowEmptyKeyframes = false,
+  allowAuto = false,
   errorFactory,
 }) => {
   {
     const result = validateAllowedKeys({
       value: config,
-      allowedKeys: ["initialValue", "keyframes"],
+      allowedKeys: allowAuto
+        ? ["initialValue", "keyframes", "auto"]
+        : ["initialValue", "keyframes"],
       path,
       errorFactory,
     });
@@ -1159,10 +1412,20 @@ const validateTweenProperty = ({
     }
   }
 
-  if (!("keyframes" in config)) {
+  const hasKeyframes = "keyframes" in config;
+  const hasAuto = "auto" in config;
+
+  if (!hasKeyframes && !hasAuto) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.keyframes or ${path}.auto is required`,
+    );
+  }
+
+  if (hasKeyframes && hasAuto) {
     return invalidFromErrorFactory(
       errorFactory,
-      `${path}.keyframes is required`,
+      `${path}.keyframes and ${path}.auto cannot both be defined`,
     );
   }
 
@@ -1176,6 +1439,28 @@ const validateTweenProperty = ({
     );
   }
 
+  if (hasAuto) {
+    if (config.initialValue !== undefined) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.initialValue is not supported when ${path}.auto is defined`,
+      );
+    }
+
+    {
+      const result = validateAutoTweenProperty({
+        auto: config.auto,
+        path: `${path}.auto`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    return;
+  }
+
   {
     const result = validateAnimationKeyframes({
       keyframes: config.keyframes,
@@ -1201,6 +1486,7 @@ const validateTweenDefinition = ({
   path,
   unsupportedMessage,
   allowEmptyKeyframes = false,
+  allowAuto = false,
   errorFactory,
 }) => {
   if (!isPlainObject(tween)) {
@@ -1229,6 +1515,7 @@ const validateTweenDefinition = ({
         config,
         path: propertyPath,
         allowEmptyKeyframes,
+        allowAuto,
         errorFactory,
       });
       if (result?.valid === false) {
@@ -1357,30 +1644,21 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
         }
       }
 
-      if (
-        item.texture !== undefined &&
-        !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)
-      ) {
+      if (item.imageId !== undefined && !isNonEmptyString(item.imageId)) {
         return invalidFromErrorFactory(
           errorFactory,
           `${itemPath}.imageId must be a non-empty string when provided`,
         );
       }
 
-      if (
-        !isNonEmptyString(item.texture) &&
-        !isNonEmptyString(item.imageId)
-      ) {
+      if (!isNonEmptyString(item.texture) && !isNonEmptyString(item.imageId)) {
         return invalidFromErrorFactory(
           errorFactory,
           `${itemPath} must define texture or imageId`,
@@ -1556,6 +1834,8 @@ const validateAnimationDefinition = ({ animation, path, errorFactory }) => {
         allowedProperties: UPDATE_TWEEN_PROPERTY_KEYS,
         path: `${path}.tween`,
         unsupportedMessage: "is not a supported update tween property",
+        allowEmptyKeyframes: true,
+        allowAuto: true,
         errorFactory,
       });
       if (result?.valid === false) {
@@ -1987,7 +2267,15 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
         allowedKeys:
           variableType === "folder"
             ? ["id", "type", "name", "description"]
-            : ["id", "type", "name", "description", "scope", "default", "value"],
+            : [
+                "id",
+                "type",
+                "name",
+                "description",
+                "scope",
+                "default",
+                "value",
+              ],
         path: itemPath,
         errorFactory,
       });
@@ -2487,6 +2775,8 @@ const validateLayoutElementData = ({
     "textStyle",
     "displaySpeed",
     "revealEffect",
+    "resourceId",
+    "animationName",
     "imageId",
     "hoverImageId",
     "clickImageId",
@@ -2608,6 +2898,8 @@ const validateLayoutElementData = ({
 
   for (const key of [
     "text",
+    "resourceId",
+    "animationName",
     "imageId",
     "hoverImageId",
     "clickImageId",
@@ -2634,6 +2926,28 @@ const validateLayoutElementData = ({
     }
   }
 
+  if (data.type === "spritesheet-animation") {
+    if (
+      (!allowPartial || data.resourceId !== undefined) &&
+      !isNonEmptyString(data.resourceId)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.resourceId must be a non-empty string`,
+      );
+    }
+
+    if (
+      (!allowPartial || data.animationName !== undefined) &&
+      !isNonEmptyString(data.animationName)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.animationName must be a non-empty string`,
+      );
+    }
+  }
+
   if (data.conditionalOverrides !== undefined) {
     if (!Array.isArray(data.conditionalOverrides)) {
       return invalidFromErrorFactory(
@@ -2983,6 +3297,8 @@ const validateLayoutElementItems = ({ items, path, errorFactory }) => {
           "textStyle",
           "displaySpeed",
           "revealEffect",
+          "resourceId",
+          "animationName",
           "imageId",
           "hoverImageId",
           "clickImageId",
@@ -3889,6 +4205,17 @@ const validateCollection = ({ collection, path }) => {
         return result;
       }
     }
+  } else if (path === "state.spritesheets") {
+    {
+      const result = validateSpritesheetItems({
+        items: collection.items,
+        path: `${path}.items`,
+        errorFactory: createStateValidationError,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
   } else if (path === "state.files") {
     {
       const result = validateFileItems({
@@ -4062,9 +4389,21 @@ const validateCollection = ({ collection, path }) => {
         return result;
       }
     }
-  } else if (path === "state.sounds") {
+  } else if (path === "state.spritesheets") {
     {
-      const result = validateSoundTreeFolderOwnership({
+      const result = validateGenericFolderOwnership({
+        nodes: collection.tree,
+        items: collection.items,
+        path: `${path}.tree`,
+        folderLabel: "folder spritesheet item",
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  } else if (path === "state.sounds") {
+    {
+      const result = validateSoundTreeFolderOwnership({
         nodes: collection.tree,
         items: collection.items,
         path: `${path}.tree`,
@@ -4418,6 +4757,43 @@ export const assertInvariants = ({ state }) => {
     }
   }
 
+  for (const [spritesheetId, spritesheet] of Object.entries(
+    state.spritesheets.items,
+  )) {
+    if (spritesheet.type !== "spritesheet") {
+      continue;
+    }
+
+    const result = validateFileReference({
+      state,
+      fileId: spritesheet.fileId,
+      path: "spritesheet.fileId",
+      details: { spritesheetId, fileId: spritesheet.fileId },
+      errorFactory: createInvariantValidationError,
+    });
+    if (!result.valid) {
+      return result;
+    }
+
+    if (spritesheet.thumbnailFileId === undefined) {
+      continue;
+    }
+
+    const thumbnailResult = validateFileReference({
+      state,
+      fileId: spritesheet.thumbnailFileId,
+      path: "spritesheet.thumbnailFileId",
+      details: {
+        spritesheetId,
+        thumbnailFileId: spritesheet.thumbnailFileId,
+      },
+      errorFactory: createInvariantValidationError,
+    });
+    if (!thumbnailResult.valid) {
+      return thumbnailResult;
+    }
+  }
+
   for (const [soundId, sound] of Object.entries(state.sounds.items)) {
     if (sound.type !== "sound") {
       continue;
@@ -4502,7 +4878,9 @@ export const assertInvariants = ({ state }) => {
     }
   }
 
-  for (const [animationId, animation] of Object.entries(state.animations.items)) {
+  for (const [animationId, animation] of Object.entries(
+    state.animations.items,
+  )) {
     if (animation.type !== "animation") {
       continue;
     }
@@ -4707,6 +5085,45 @@ export const assertInvariants = ({ state }) => {
     return VALID_RESULT;
   };
 
+  const assertSpritesheetAnimationReference = ({
+    ownerIdField,
+    ownerId,
+    ownerLabel,
+    elementId,
+    targetId,
+    animationName,
+  }) => {
+    const spritesheet = state.spritesheets?.items?.[targetId];
+    if (!isPlainObject(spritesheet) || spritesheet.type === "folder") {
+      return invalidInvariant(
+        `${ownerLabel} element resourceId must reference an existing non-folder spritesheet`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "resourceId",
+          targetId,
+        },
+      );
+    }
+
+    if (
+      !isNonEmptyString(animationName) ||
+      !isPlainObject(spritesheet.animations?.[animationName])
+    ) {
+      return invalidInvariant(
+        `${ownerLabel} element animationName must reference an existing spritesheet animation`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "animationName",
+          targetId: animationName,
+        },
+      );
+    }
+
+    return VALID_RESULT;
+  };
+
   const assertElementReferencesForCollection = ({
     items,
     ownerIdField,
@@ -4719,6 +5136,24 @@ export const assertInvariants = ({ state }) => {
       }
 
       for (const [elementId, element] of Object.entries(owner.elements.items)) {
+        if (
+          element.type === "spritesheet-animation" ||
+          element.resourceId !== undefined ||
+          element.animationName !== undefined
+        ) {
+          const result = assertSpritesheetAnimationReference({
+            ownerIdField,
+            ownerId,
+            ownerLabel,
+            elementId,
+            targetId: element.resourceId,
+            animationName: element.animationName,
+          });
+          if (!result.valid) {
+            return result;
+          }
+        }
+
         for (const field of [
           "imageId",
           "hoverImageId",
@@ -5459,6 +5894,233 @@ const validateImageUpdateData = ({ data, errorFactory }) => {
   }
 };
 
+const validateSpritesheetCreateData = ({ data, errorFactory }) => {
+  if (!isPlainObject(data)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data must be an object",
+    );
+  }
+
+  if (data.type !== "folder" && data.type !== "spritesheet") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.type must be 'folder' or 'spritesheet'",
+    );
+  }
+
+  {
+    const result = validateAllowedKeys({
+      value: data,
+      allowedKeys:
+        data.type === "folder"
+          ? ["type", "name", "description"]
+          : [
+              "type",
+              "name",
+              "description",
+              "thumbnailFileId",
+              "fileId",
+              "fileType",
+              "fileSize",
+              "sheetWidth",
+              "sheetHeight",
+              "frameCount",
+              "width",
+              "height",
+              "jsonData",
+              "animations",
+            ],
+      path: "payload.data",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (!isNonEmptyString(data.name)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.name must be a non-empty string",
+    );
+  }
+
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
+  if (data.type === "spritesheet") {
+    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",
+      );
+    }
+
+    if (data.fileType !== undefined && !isString(data.fileType)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.fileType must be a string when provided",
+      );
+    }
+
+    for (const key of [
+      "fileSize",
+      "sheetWidth",
+      "sheetHeight",
+      "frameCount",
+      "width",
+      "height",
+    ]) {
+      if (data[key] !== undefined && !isFiniteNumber(data[key])) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `payload.data.${key} must be a finite number`,
+        );
+      }
+    }
+
+    if (!isPlainObject(data.jsonData)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.jsonData must be an object",
+      );
+    }
+
+    {
+      const result = validateSpritesheetAnimationMap({
+        animations: data.animations,
+        path: "payload.data.animations",
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  }
+};
+
+const validateSpritesheetUpdateData = ({ data, errorFactory }) => {
+  {
+    const result = validateAllowedKeys({
+      value: data,
+      allowedKeys: [
+        "name",
+        "description",
+        "thumbnailFileId",
+        "fileId",
+        "fileType",
+        "fileSize",
+        "sheetWidth",
+        "sheetHeight",
+        "frameCount",
+        "width",
+        "height",
+        "jsonData",
+        "animations",
+      ],
+      path: "payload.data",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (Object.keys(data).length === 0) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data must include at least one updatable field",
+    );
+  }
+
+  if (data.name !== undefined && !isNonEmptyString(data.name)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.name must be a non-empty string when provided",
+    );
+  }
+
+  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)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.thumbnailFileId must be a non-empty string when provided",
+    );
+  }
+
+  if (data.fileId !== undefined && !isNonEmptyString(data.fileId)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.fileId must be a non-empty string when provided",
+    );
+  }
+
+  if (data.fileType !== undefined && !isString(data.fileType)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.fileType must be a string when provided",
+    );
+  }
+
+  for (const key of [
+    "fileSize",
+    "sheetWidth",
+    "sheetHeight",
+    "frameCount",
+    "width",
+    "height",
+  ]) {
+    if (data[key] !== undefined && !isFiniteNumber(data[key])) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `payload.data.${key} must be a finite number`,
+      );
+    }
+  }
+
+  if (data.jsonData !== undefined && !isPlainObject(data.jsonData)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.jsonData must be an object when provided",
+    );
+  }
+
+  if (data.animations !== undefined) {
+    const result = validateSpritesheetAnimationMap({
+      animations: data.animations,
+      path: "payload.data.animations",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+};
+
 const validateSoundCreateData = ({ data, errorFactory }) => {
   if (!isPlainObject(data)) {
     return invalidFromErrorFactory(
@@ -7432,6 +8094,42 @@ const validateVisualElementReferenceTargets = ({
   state,
   errorFactory,
 }) => {
+  if (
+    data.type === "spritesheet-animation" ||
+    data.resourceId !== undefined ||
+    data.animationName !== undefined
+  ) {
+    const spritesheet = state.spritesheets?.items?.[data.resourceId];
+    if (!isPlainObject(spritesheet) || spritesheet.type === "folder") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${ownerLabel} element resourceId must reference an existing non-folder spritesheet`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "resourceId",
+          targetId: data.resourceId,
+        },
+      );
+    }
+
+    if (
+      !isNonEmptyString(data.animationName) ||
+      !isPlainObject(spritesheet.animations?.[data.animationName])
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${ownerLabel} element animationName must reference an existing spritesheet animation`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "animationName",
+          targetId: data.animationName,
+        },
+      );
+    }
+  }
+
   if (data.imageId !== undefined) {
     const image = state.images.items[data.imageId];
     if (!isPlainObject(image) || image.type === "folder") {
@@ -8245,6 +8943,30 @@ const findReferencedFileUsage = ({ state, fileId }) => {
     }
   }
 
+  for (const [spritesheetId, spritesheet] of Object.entries(
+    state.spritesheets.items,
+  )) {
+    if (spritesheet.type !== "spritesheet") {
+      continue;
+    }
+
+    if (spritesheet.fileId === fileId) {
+      return {
+        kind: "spritesheet",
+        field: "fileId",
+        ownerId: spritesheetId,
+      };
+    }
+
+    if (spritesheet.thumbnailFileId === fileId) {
+      return {
+        kind: "spritesheet",
+        field: "thumbnailFileId",
+        ownerId: spritesheetId,
+      };
+    }
+  }
+
   for (const [soundId, sound] of Object.entries(state.sounds.items)) {
     if (sound.type !== "sound") {
       continue;
@@ -8438,6 +9160,108 @@ const COMMAND_DEFINITIONS = [
       }
     },
   }),
+  ...createFolderedCollectionCommandDefinitions({
+    familyName: "spritesheet",
+    collectionKey: "spritesheets",
+    idField: "spritesheetId",
+    itemLabel: "spritesheet item",
+    createDataValidator: validateSpritesheetCreateData,
+    updateDataValidator: validateSpritesheetUpdateData,
+    createItem: ({ payload }) => ({
+      id: payload.spritesheetId,
+      type: payload.data.type,
+      name: payload.data.name,
+      ...(payload.data.description !== undefined
+        ? {
+            description: payload.data.description,
+          }
+        : {}),
+      ...(payload.data.type === "spritesheet"
+        ? {
+            fileId: payload.data.fileId,
+            ...(payload.data.thumbnailFileId !== undefined
+              ? {
+                  thumbnailFileId: payload.data.thumbnailFileId,
+                }
+              : {}),
+            ...(payload.data.fileType !== undefined
+              ? {
+                  fileType: payload.data.fileType,
+                }
+              : {}),
+            ...(payload.data.fileSize !== undefined
+              ? {
+                  fileSize: payload.data.fileSize,
+                }
+              : {}),
+            ...(payload.data.sheetWidth !== undefined
+              ? {
+                  sheetWidth: payload.data.sheetWidth,
+                }
+              : {}),
+            ...(payload.data.sheetHeight !== undefined
+              ? {
+                  sheetHeight: payload.data.sheetHeight,
+                }
+              : {}),
+            ...(payload.data.frameCount !== undefined
+              ? {
+                  frameCount: payload.data.frameCount,
+                }
+              : {}),
+            ...(payload.data.width !== undefined
+              ? {
+                  width: payload.data.width,
+                }
+              : {}),
+            ...(payload.data.height !== undefined
+              ? {
+                  height: payload.data.height,
+                }
+              : {}),
+            jsonData: structuredClone(payload.data.jsonData),
+            animations: structuredClone(payload.data.animations),
+          }
+        : {}),
+    }),
+    validateCreateState: ({ state, payload }) => {
+      if (payload.data.type !== "spritesheet") {
+        return;
+      }
+
+      return validateReferencedFilesInData({
+        state,
+        data: payload.data,
+        fields: ["fileId", "thumbnailFileId"],
+        details: {
+          spritesheetId: payload.spritesheetId,
+        },
+      });
+    },
+    validateUpdateState: ({ state, payload, currentItem }) => {
+      if (
+        currentItem.type === "folder" &&
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
+      ) {
+        return invalidPrecondition(
+          "folder spritesheet items cannot update spritesheet fields",
+        );
+      }
+
+      if (currentItem.type === "spritesheet") {
+        return validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId", "thumbnailFileId"],
+          details: {
+            spritesheetId: payload.spritesheetId,
+          },
+        });
+      }
+    },
+  }),
   {
     type: "story.update",
     validatePayload: ({ payload }) => {
@@ -14133,8 +14957,10 @@ export const validateAgainstState = ({ state, command }) => {
 export const processCommand = ({ state, command }) => {
   return captureValidation(() => {
     const normalizedState = normalizeStateCollections(state);
-    const shouldMaterializeControls =
-      typeof command?.type === "string" && command.type.startsWith("control.");
+    const shouldMaterializeNormalizedState =
+      typeof command?.type === "string" &&
+      (command.type.startsWith("control.") ||
+        command.type.startsWith("spritesheet."));
 
     if (!isPlainObject(command)) {
       return invalidPrecondition("command must be an object");
@@ -14155,7 +14981,7 @@ export const processCommand = ({ state, command }) => {
 
     const nextState = definition.reduce({
       state: structuredClone(
-        shouldMaterializeControls ? normalizedState : state,
+        shouldMaterializeNormalizedState ? normalizedState : state,
       ),
       payload: command.payload,
     });
@@ -14165,7 +14991,7 @@ export const processCommand = ({ state, command }) => {
 
     const finalState =
       nextState === undefined
-        ? shouldMaterializeControls
+        ? shouldMaterializeNormalizedState
           ? normalizedState
           : state
         : nextState;