@routevn/creator-model 1.13.3 → 1.14.0

package/README.md

@@ -106,6 +106,22 @@ Design rules:
 - random ids across RouteVN should use `nanoid` with the RouteVN base58 variant;
   deterministic derived tokens such as partition hashes are a separate case
 
+## Animation Camera Tracks
+
+Animation resources may explicitly group synchronized position and scale tracks
+with `cameraTracks: ["update"]`, or `["prev", "next"]` for transitions.
+Each listed side must contain `x`, `y`, `scaleX`, and `scaleY` keyframe
+tracks with matching timing/easing and start-value presence, absolute values,
+and positive scales. Track initial values are optional; they must be numeric
+on all four tracks or omitted from all four to use the target's existing pose.
+Translation tracks cannot coexist with Camera on the same side.
+
+This authoring marker does not alter the runtime animation format. Existing
+animations without the marker remain separate tracks; no grouping is inferred.
+An update may use `cameraTracks: []` to remove grouping. Updates to animation
+data are validated with the resource's retained grouping unless it is replaced
+in the same command.
+
 ## Font Weight Metadata
 
 Font resources may store extracted weight capabilities in three flat fields:

package/package.json

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

package/src/model.js

@@ -408,7 +408,7 @@ const SAVE_LOAD_DATE_FORMATS = new Set([
   "DD MMM YYYY",
   "YYYY年MM月DD日",
 ]);
-export const SCHEMA_VERSION = 13;
+export const SCHEMA_VERSION = 14;
 const LAYOUT_CONTAINER_ELEMENT_TYPES = [
   "folder",
   "container",
@@ -2345,6 +2345,85 @@ const validateAnimationDefinition = ({ animation, path, errorFactory }) => {
   }
 };
 
+// Camera is an authored grouping of four synchronized runtime tween tracks.
+// No grouping is inferred for older animations that omit cameraTracks.
+const validateCameraTracks = ({ value, animation, path, errorFactory }) => {
+  if (value === undefined) return;
+  if (
+    !Array.isArray(value) ||
+    value.some((side) => !["update", "prev", "next"].includes(side)) ||
+    new Set(value).size !== value.length
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be an array of unique update, prev, or next sides`,
+    );
+  }
+  // Partial update payloads are checked against the merged resource below.
+  if (animation === undefined) return;
+  for (const side of value) {
+    const tween = side === "update" ? animation.tween : animation[side]?.tween;
+    const validSide =
+      animation.type === "update" ? side === "update" : side !== "update";
+    const properties = ["x", "y", "scaleX", "scaleY"];
+    const tracks = properties.map((property) => tween?.[property]);
+    if (
+      !validSide ||
+      tracks.some(
+        (track) =>
+          !Array.isArray(track?.keyframes) ||
+          (track.initialValue !== undefined &&
+            !Number.isFinite(track.initialValue)) ||
+          (track.initialValue !== undefined) !==
+            (tracks[0]?.initialValue !== undefined),
+      ) ||
+      tween.translateX !== undefined ||
+      tween.translateY !== undefined
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.${side} requires x, y, scaleX, and scaleY keyframe tracks with matching initial-value presence and no translation tracks`,
+      );
+    }
+    const reference = tracks[0].keyframes;
+    for (const [index, track] of tracks.entries()) {
+      if (
+        track.keyframes.length !== reference.length ||
+        track.keyframes.some((frame, frameIndex) => {
+          const other = reference[frameIndex];
+          return (
+            frame.relative === true ||
+            frame.duration !== other.duration ||
+            (frame.delay ?? 0) !== (other.delay ?? 0) ||
+            (frame.easing ?? "linear") !== (other.easing ?? "linear") ||
+            (frame.startValue !== undefined) !==
+              (other.startValue !== undefined)
+          );
+        })
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${path}.${side} requires synchronized absolute keyframes`,
+        );
+      }
+      if (
+        index >= 2 &&
+        ((track.initialValue !== undefined && track.initialValue <= 0) ||
+          track.keyframes.some(
+            (frame) =>
+              frame.value <= 0 ||
+              (frame.startValue !== undefined && frame.startValue <= 0),
+          ))
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${path}.${side} requires positive camera scales`,
+        );
+      }
+    }
+  }
+};
+
 const validateAnimationItems = ({ items, path, errorFactory }) => {
   for (const [itemId, item] of Object.entries(items)) {
     const itemPath = `${path}.${itemId}`;
@@ -2370,6 +2449,7 @@ const validateAnimationItems = ({ items, path, errorFactory }) => {
                 "tagIds",
                 "thumbnailFileId",
                 "preview",
+                "cameraTracks",
                 "animation",
               ],
         path: itemPath,
@@ -2452,6 +2532,13 @@ const validateAnimationItems = ({ items, path, errorFactory }) => {
           return result;
         }
       }
+      const cameraResult = validateCameraTracks({
+        value: item.cameraTracks,
+        animation: item.animation,
+        path: `${itemPath}.cameraTracks`,
+        errorFactory,
+      });
+      if (cameraResult?.valid === false) return cameraResult;
     }
   }
 };
@@ -12260,6 +12347,7 @@ const validateAnimationCreateData = ({ data, errorFactory }) => {
               "tagIds",
               "thumbnailFileId",
               "preview",
+              "cameraTracks",
               "animation",
             ],
       path: "payload.data",
@@ -12327,6 +12415,12 @@ const validateAnimationCreateData = ({ data, errorFactory }) => {
         return result;
       }
     }
+    return validateCameraTracks({
+      value: data.cameraTracks,
+      animation: data.animation,
+      path: "payload.data.cameraTracks",
+      errorFactory,
+    });
   }
 };
 
@@ -12340,6 +12434,7 @@ const validateAnimationUpdateData = ({ data, errorFactory }) => {
         "tagIds",
         "thumbnailFileId",
         "preview",
+        "cameraTracks",
         "animation",
       ],
       path: "payload.data",
@@ -12415,6 +12510,12 @@ const validateAnimationUpdateData = ({ data, errorFactory }) => {
       }
     }
   }
+  return validateCameraTracks({
+    value: data.cameraTracks,
+    animation: data.animation,
+    path: "payload.data.cameraTracks",
+    errorFactory,
+  });
 };
 
 const validateAudioEffectCreateData = ({ data, errorFactory }) => {
@@ -19066,6 +19167,9 @@ const COMMAND_DEFINITIONS = [
         if (payload.data.preview !== undefined) {
           nextAnimation.preview = structuredClone(payload.data.preview);
         }
+        if (payload.data.cameraTracks !== undefined) {
+          nextAnimation.cameraTracks = [...payload.data.cameraTracks];
+        }
         nextAnimation.animation = structuredClone(payload.data.animation);
       }
 
@@ -19135,6 +19239,13 @@ const COMMAND_DEFINITIONS = [
       }
 
       if (currentAnimation.type === "animation") {
+        const cameraResult = validateCameraTracks({
+          value: payload.data.cameraTracks ?? currentAnimation.cameraTracks,
+          animation: payload.data.animation ?? currentAnimation.animation,
+          path: "payload.data.cameraTracks",
+          errorFactory: createPreconditionValidationError,
+        });
+        if (cameraResult?.valid === false) return cameraResult;
         if (payload.data.animation !== undefined) {
           const result = validateAnimationMaskImageReferences({
             state,