Reserve choice render layer

docs/RouteEngine.md

@@ -698,9 +698,10 @@ behavior.
 | `40`        | `CHARACTER`                | Engine character layer   |
 | `50`        | `VISUAL_BEHIND_DIALOGUE`   | Before dialogue          |
 | `60`        | `DIALOGUE`                 | Engine dialogue/UI layer |
-| `70`        | `VISUAL_FOREGROUND`        | Above story UI/layouts   |
+| `70`        | `CHOICE`                   | Engine choice UI layer   |
+| `80`        | `VISUAL_FOREGROUND`        | Above choice/UI/layouts  |
 
-Visual items can use `10`, `30`, `50`, or `70`. Layer `70` is still below
+Visual items can use `10`, `30`, `50`, or `80`. Layer `80` is still below
 screen transitions, overlay stack entries, and confirm dialogs. JavaScript
 callers can use the exported `RENDER_LAYER`, `VISUAL_LAYER`, and
 `DEFAULT_VISUAL_LAYER` constants when generating project data.
@@ -793,7 +794,7 @@ visual:
     - id: vignette
       resourceId: vignette
       transformId: fullscreen
-      layer: 70
+      layer: 80
       opacity: 0.8
 ```
 

package.json

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

spec/projectDataSchema.test.js

@@ -475,7 +475,7 @@ describe("projectData schema", () => {
               id: "vignette",
               resourceId: "vignette",
               transformId: "fullscreen",
-              layer: 70,
+              layer: 80,
             },
           ],
         },
@@ -484,7 +484,7 @@ describe("projectData schema", () => {
     expect(validatePresentationActions.errors).toBeNull();
   });
 
-  it("rejects arbitrary visual layer values", () => {
+  it("rejects non-visual layer values", () => {
     expect(
       validatePresentationActions({
         visual: {
@@ -498,6 +498,20 @@ describe("projectData schema", () => {
         },
       }),
     ).toBe(false);
+
+    expect(
+      validatePresentationActions({
+        visual: {
+          items: [
+            {
+              id: "vignette",
+              resourceId: "vignette",
+              layer: 70,
+            },
+          ],
+        },
+      }),
+    ).toBe(false);
   });
 
   it("accepts animation playback continuity in presentation action payloads", () => {

spec/renderLayers.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_VISUAL_LAYER,
+  RENDER_LAYER,
+  VISUAL_LAYER,
+  VISUAL_LAYER_VALUES,
+} from "../src/renderLayers.js";
+
+describe("render layer constants", () => {
+  it("reserves choice above dialogue and keeps foreground visuals above choice", () => {
+    expect(RENDER_LAYER).toMatchObject({
+      VISUAL_BEHIND_BACKGROUND: 10,
+      BACKGROUND: 20,
+      VISUAL_BEHIND_CHARACTER: 30,
+      CHARACTER: 40,
+      VISUAL_BEHIND_DIALOGUE: 50,
+      DIALOGUE: 60,
+      CHOICE: 70,
+      VISUAL_FOREGROUND: 80,
+    });
+    expect(VISUAL_LAYER.FOREGROUND).toBe(80);
+    expect(VISUAL_LAYER_VALUES).toEqual([10, 30, 50, 80]);
+    expect(DEFAULT_VISUAL_LAYER).toBe(50);
+  });
+});

spec/system/constructPresentationState.spec.yaml

@@ -681,7 +681,7 @@ in:
             layer: 30
           - id: "vignette"
             resourceId: "effect-vignette"
-            layer: 70
+            layer: 80
 out:
   visual:
     items:
@@ -690,7 +690,7 @@ out:
         layer: 30
       - id: "vignette"
         resourceId: "effect-vignette"
-        layer: 70
+        layer: 80
 ---
 case: character item opacity and blur persist across omitted character action
 in:

spec/system/constructRenderState.spec.yaml

@@ -134,7 +134,7 @@ in:
             - id: "foreground"
               resourceId: "foregroundImage"
               transformId: "visualTransform"
-              layer: 70
+              layer: 80
             - id: "defaultBehindDialogue"
               resourceId: "defaultImage"
               transformId: "visualTransform"
@@ -156,6 +156,11 @@ in:
             resourceId: "dialogueUi"
           content:
             - text: "Layered"
+        choice:
+          resourceId: "choiceUi"
+          items:
+            - id: "go"
+              content: "Go"
         layout:
           resourceId: "storyLayout"
       resources:
@@ -210,6 +215,10 @@ in:
             elements:
               - id: "dialogue-box"
                 type: "container"
+          choiceUi:
+            elements:
+              - id: "choice-box"
+                type: "container"
           storyLayout:
             elements:
               - id: "story-layout"
@@ -308,6 +317,8 @@ out:
           scaleY: 1
         - id: "dialogue-box"
           type: "container"
+        - id: "choice-box"
+          type: "container"
         - id: "layout-storyLayout"
           type: "container"
           x: 0

spec/system/renderState/addVisuals.spec.yaml

@@ -1933,7 +1933,7 @@ in:
           - id: "foreground"
             resourceId: "foregroundImage"
             transformId: "transform1"
-            layer: 70
+            layer: 80
           - id: "defaultLayer"
             resourceId: "defaultImage"
             transformId: "transform1"
@@ -2055,7 +2055,7 @@ out:
                 value: 0
   audio: []
 ---
-case: invalid visual layer should throw clear error
+case: reserved choice layer should throw clear error for visuals
 in:
   - elements:
       - id: "story"
@@ -2071,7 +2071,7 @@ in:
           - id: "fog"
             resourceId: "fogImage"
             transformId: "transform1"
-            layer: 20
+            layer: 70
     resources:
       images:
         fogImage:
@@ -2085,4 +2085,4 @@ in:
           rotation: 0
           scaleX: 1
           scaleY: 1
-throws: 'Visual item "fog" layer must be one of: 10, 30, 50, 70.'
+throws: 'Visual item "fog" layer must be one of: 10, 30, 50, 80.'

src/renderLayers.js

@@ -5,7 +5,8 @@ export const RENDER_LAYER = Object.freeze({
   CHARACTER: 40,
   VISUAL_BEHIND_DIALOGUE: 50,
   DIALOGUE: 60,
-  VISUAL_FOREGROUND: 70,
+  CHOICE: 70,
+  VISUAL_FOREGROUND: 80,
 });
 
 export const VISUAL_LAYER = Object.freeze({

src/schemas/presentationActions.yaml

@@ -318,7 +318,7 @@ properties:
                 - 10
                 - 30
                 - 50
-                - 70
+                - 80
               description: Numeric render layer for the visual item. Defaults to 50. Same-layer items preserve array order.
             opacity:
               type: number

vt/specs/visual/layers.yaml

@@ -7,7 +7,7 @@ description: |
   - layer 10 visuals render before the background layer
   - layer 30 visuals render between background and character
   - layer 50 visuals render between character and dialogue
-  - layer 70 visuals render above dialogue and normal story layouts
+  - layer 80 visuals render above choice, dialogue, and normal story layouts
   - same-layer visuals preserve authored item order
 skipInitialScreenshot: true
 steps:
@@ -142,6 +142,15 @@ resources:
           width: 1680
           height: 240
           colorId: fg10
+    choiceUi:
+      elements:
+        - id: choice-panel
+          type: rect
+          x: 320
+          y: 860
+          width: 1280
+          height: 90
+          colorId: fg30
     storyLayout:
       elements:
         - id: layout-panel
@@ -253,7 +262,7 @@ story:
                     - id: foreground
                       resourceId: foregroundLayer
                       transformId: fullScreen
-                      layer: 70
+                      layer: 80
                     - id: behindDialogueOne
                       resourceId: behindDialogueLayerOne
                       transformId: fullScreen
@@ -275,6 +284,11 @@ story:
                     resourceId: dialogueUi
                   content:
                     - text: Layered visuals
+                choice:
+                  resourceId: choiceUi
+                  items:
+                    - id: confirm
+                      content: Confirm
                 layout:
                   resourceId: storyLayout
             - id: characterOverlapVisuals
@@ -293,7 +307,7 @@ story:
                     - id: overlapForeground
                       resourceId: overlapForeground
                       transformId: fullScreen
-                      layer: 70
+                      layer: 80
                     - id: overlapBehindDialogueFirst
                       resourceId: overlapBehindDialogueFirst
                       transformId: fullScreen

vt/specs/visual/opacity-blur.yaml

@@ -62,7 +62,7 @@ story:
                     - id: glow
                       resourceId: visual-sprite
                       transformId: visual-center
-                      layer: 70
+                      layer: 80
                       opacity: 0.45
                       blur:
                         x: 6

vt/specs/visual/transform-overrides.yaml

@@ -56,7 +56,7 @@ story:
                     - id: logo
                       resourceId: logo
                       transformId: visual-left
-                      layer: 70
+                      layer: 80
             - id: visualTransformPatched
               actions:
                 visual: