Keep background render targets stable across swaps

package.json

@@ -1,6 +1,6 @@
 {
   "name": "route-engine-js",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A lightweight Visual Novel engine built in JavaScript for creating interactive narrative games with branching storylines",
   "repository": {
     "type": "git",

spec/constructRenderState.backgroundTransitionTargets.test.js

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { constructPresentationState } from "../src/stores/constructPresentationState.js";
+import { constructRenderState } from "../src/stores/constructRenderState.js";
+import { normalizePersistentPresentationState } from "../src/util.js";
+
+const createResources = () => ({
+  images: {
+    bg1: {
+      fileId: "bg-old.png",
+      width: 1920,
+      height: 1080,
+    },
+    bg2: {
+      fileId: "bg-new.png",
+      width: 1920,
+      height: 1080,
+    },
+  },
+  videos: {},
+  layouts: {
+    bgLayout: {
+      elements: [],
+    },
+  },
+  animations: {
+    maskTransition: {
+      type: "transition",
+      prev: {
+        tween: {
+          alpha: {
+            initialValue: 1,
+            keyframes: [{ duration: 1000, value: 0 }],
+          },
+        },
+      },
+      next: {
+        tween: {
+          alpha: {
+            initialValue: 0,
+            keyframes: [{ duration: 1000, value: 1 }],
+          },
+        },
+      },
+    },
+  },
+  transforms: {},
+  characters: {},
+  controls: {},
+  colors: {},
+  fonts: {},
+  sectionTransitions: {},
+  sounds: {},
+  sprites: {},
+  spritesheets: {},
+  textStyles: {},
+  variables: {},
+});
+
+const createPresentationPair = (nextBackground) => {
+  const previousPresentationState = normalizePersistentPresentationState(
+    constructPresentationState([
+      {
+        background: {
+          resourceId: "bg1",
+        },
+      },
+    ]),
+  );
+
+  const presentationState = constructPresentationState([
+    previousPresentationState,
+    {
+      background: nextBackground,
+    },
+  ]);
+
+  return {
+    previousPresentationState,
+    presentationState,
+  };
+};
+
+describe("constructRenderState background transition targets", () => {
+  it("keeps a stable background target id for same-type background swaps", () => {
+    const resources = createResources();
+    const { previousPresentationState, presentationState } =
+      createPresentationPair({
+        resourceId: "bg2",
+        animations: {
+          resourceId: "maskTransition",
+        },
+      });
+
+    const renderState = constructRenderState({
+      presentationState,
+      previousPresentationState,
+      resources,
+    });
+
+    const story = renderState.elements.find((element) => element.id === "story");
+    expect(story.children).toContainEqual(
+      expect.objectContaining({
+        id: "bg-cg-background-sprite",
+        type: "sprite",
+        src: "bg-new.png",
+      }),
+    );
+    expect(renderState.animations).toEqual([
+      expect.objectContaining({
+        id: "bg-cg-animation-transition",
+        type: "transition",
+        targetId: "bg-cg-background-sprite",
+      }),
+    ]);
+  });
+
+  it("falls back to separate transition targets when background render kinds change", () => {
+    const resources = createResources();
+    const { previousPresentationState, presentationState } =
+      createPresentationPair({
+        resourceId: "bgLayout",
+        animations: {
+          resourceId: "maskTransition",
+        },
+      });
+
+    const renderState = constructRenderState({
+      presentationState,
+      previousPresentationState,
+      resources,
+    });
+
+    expect(renderState.animations).toEqual([
+      expect.objectContaining({
+        id: "bg-cg-animation-out",
+        type: "transition",
+        targetId: "bg-cg-background-sprite",
+      }),
+      expect.objectContaining({
+        id: "bg-cg-animation-in",
+        type: "transition",
+        targetId: "bg-cg-background-container",
+      }),
+    ]);
+  });
+});

spec/system/constructRenderState.spec.yaml

@@ -23,7 +23,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-mainBackground"
+        - id: "bg-cg-background-container"
           type: "container"
           children:
             - type: "container"
@@ -79,7 +79,7 @@ out:
               y: 0
               width: 100
               height: 100
-        - id: "bg-cg-bgImage"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -131,12 +131,12 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-oldBg"
+        - id: "bg-cg-background-container"
           type: "container"
           children:
             - type: "container"
               id: "old-container"
-        - id: "bg-cg-newBg"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5

spec/system/renderState/addBackgroundOrCg.spec.yaml

@@ -30,7 +30,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -78,7 +78,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0
@@ -152,7 +152,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -168,7 +168,7 @@ out:
   animations:
     - id: "bg-cg-animation-in"
       type: "transition"
-      targetId: "bg-cg-bg1"
+      targetId: "bg-cg-background-sprite"
       next:
         tween:
           alpha:
@@ -246,7 +246,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -314,7 +314,7 @@ out:
           src: "old.jpg"
           width: 1920
           height: 1080
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -330,7 +330,7 @@ out:
   animations:
     - id: "bg-cg-animation-update"
       type: "update"
-      targetId: "bg-cg-bg1"
+      targetId: "bg-cg-background-sprite"
       tween:
         alpha:
           initialValue: 1
@@ -507,7 +507,7 @@ out:
         - id: "existingChild"
           type: "text"
           content: "Hello"
-        - id: "bg-cg-bg2"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -525,7 +525,7 @@ out:
       type: "existing"
     - id: "bg-cg-animation-in"
       type: "transition"
-      targetId: "bg-cg-bg2"
+      targetId: "bg-cg-background-sprite"
       next:
         tween:
           x:
@@ -575,7 +575,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bgLayout"
+        - id: "bg-cg-background-container"
           type: "container"
           children:
             - id: "bg-label"
@@ -631,7 +631,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bgLayout"
+        - id: "bg-cg-background-container"
           type: "container"
           x: 400
           y: 250
@@ -679,7 +679,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-coloredLayout"
+        - id: "bg-cg-background-container"
           type: "container"
           children:
             - id: "bg-panel"
@@ -720,7 +720,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-imageLayout"
+        - id: "bg-cg-background-container"
           type: "container"
           children:
             - id: "bg-image"
@@ -767,7 +767,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -783,7 +783,7 @@ out:
   animations:
     - id: "bg-cg-animation-in"
       type: "transition"
-      targetId: "bg-cg-bg1"
+      targetId: "bg-cg-background-sprite"
       next:
         tween:
           alpha:
@@ -836,7 +836,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -852,7 +852,7 @@ out:
   animations:
     - id: "bg-cg-animation-in"
       type: "transition"
-      targetId: "bg-cg-bg1"
+      targetId: "bg-cg-background-sprite"
       prev:
         tween:
           alpha:
@@ -914,7 +914,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -930,7 +930,7 @@ out:
   animations:
     - id: "bg-cg-animation-transition"
       type: "transition"
-      targetId: "bg-cg-bg1"
+      targetId: "bg-cg-background-sprite"
       prev:
         tween:
           alpha:
@@ -985,7 +985,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -1001,7 +1001,7 @@ out:
   animations:
     - id: "bg-cg-animation-update"
       type: "update"
-      targetId: "bg-cg-bg1"
+      targetId: "bg-cg-background-sprite"
       tween:
         alpha:
           initialValue: 0.2
@@ -1045,7 +1045,7 @@ out:
       x: 0
       y: 0
       children:
-        - id: "bg-cg-bg1"
+        - id: "bg-cg-background-sprite"
           type: "sprite"
           alpha: 1
           anchorX: 0.5
@@ -1061,7 +1061,7 @@ out:
   animations:
     - id: "bg-cg-animation-update"
       type: "update"
-      targetId: "bg-cg-bg1"
+      targetId: "bg-cg-background-sprite"
       tween:
         alpha:
           initialValue: 0