From 75017ed29571d25fdd0524b48122ffee6a1d2418 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Tue, 18 Nov 2025 14:36:12 -0500
Subject: [PATCH 01/32] feat: Add overlay option for image node

---
 branching_xblock/branching_xblock.py          | 49 +++++++++++++++++--
 .../static/css/branching_xblock.css           | 44 +++++++++++++++++
 branching_xblock/static/css/studio_editor.css | 15 ++++++
 .../static/handlebars/node-block.handlebars   |  6 +++
 .../static/js/src/branching_xblock.js         | 22 +++++++--
 .../static/js/src/studio_editor.js            | 38 +++++++++++++-
 6 files changed, 166 insertions(+), 8 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 5f10458..75238af 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -1,5 +1,6 @@
 """Branching Scenario XBlock."""
 import json
+import logging
 import os
 import uuid
 from typing import Any, Optional
@@ -13,6 +14,8 @@
 
 resource_loader = ResourceLoader(__name__)
 
+logger = logging.getLogger(__name__)
+
 
 class BranchingXBlock(XBlock):
     """
@@ -114,7 +117,14 @@ def get_node(self, node_id):
         """
         Get a node by its ID.
         """
-        return self.scenario_data.get("nodes", {}).get(node_id)
+        node = self.scenario_data.get("nodes", {}).get(node_id)
+        if node is None:
+            return None
+        if "overlay_text" not in node:
+            # ensure older scenarios expose the flag downstream
+            node = {**node, "overlay_text": False}
+            self.scenario_data.setdefault("nodes", {})[node_id] = node
+        return node
 
     def get_current_node(self) -> Optional[dict[str, Any]]:
         """
@@ -129,6 +139,27 @@ def is_end_node(self, node_id):
         node = self.get_node(node_id)
         return bool(node) and not node.get("choices")
 
+    def get_choice(self, node, choice_index):
+        """
+        Validate and return a choice from a node.
+        """
+        try:
+            return node["choices"][choice_index]
+        except (IndexError, KeyError, TypeError):
+            return None
+
+    def can_undo(self):
+        """
+        Check if undo is allowed and possible.
+        """
+        return self.enable_undo and len(self.history) > 0
+
+    def get_previous_node_id(self):
+        """
+        Get last node from history.
+        """
+        return self.history[-1] if self.history else None
+
     def validate_scenario(self):
         """
         Check for common configuration errors.
@@ -211,8 +242,7 @@ def studio_view(self, context=None):
             get_site_configuration_value("branching_xblock", "AUTHORING_HELP_HTML") or ""
         )
         init_data = {
-            "nodes": self.scenario_data.get("nodes", {}),
-            "start_node_id": self.scenario_data.get("start_node_id"),
+            "nodes":       self.scenario_data.get("nodes", []),
             "enable_undo": bool(self.enable_undo),
             "enable_scoring": bool(self.enable_scoring),
             "enable_hints": bool(self.enable_hints),
@@ -225,8 +255,17 @@ def studio_view(self, context=None):
         return frag
 
     def _get_state(self):
+        nodes = self.scenario_data.get("nodes", {})
+        nodes_with_defaults = {
+            node_id: {
+                **node,
+                "overlay_text": bool(node.get("overlay_text", False)),
+            }
+            for node_id, node in nodes.items()
+        }
+
         return {
-            "nodes":           self.scenario_data.get("nodes", {}),
+            "nodes":           nodes_with_defaults,
             "start_node_id":   self.scenario_data.get("start_node_id"),
             "enable_undo":     bool(self.enable_undo),
             "enable_scoring":  bool(self.enable_scoring),
@@ -323,6 +362,7 @@ def studio_submit(self, data, suffix=''):
                 },
                 'choices': raw.get('choices', []),
                 'hint':     raw.get('hint', ''),
+                'overlay_text': bool(raw.get('overlay_text', False)),
                 'transcript_url': raw.get('transcript_url', ''),
             })
 
@@ -359,6 +399,7 @@ def studio_submit(self, data, suffix=''):
                 'media':    node['media'],
                 'choices':  cleaned,
                 'hint': node.get('hint', ''),
+                'overlay_text': bool(node.get('overlay_text', False)),
                 'transcript_url': node.get('transcript_url', ''),
             })
 
diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 4322065..73bd075 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -26,6 +26,50 @@
     align-self: center;
 }
 
+.branching-scenario .media-overlay {
+    position: relative;
+    width: 100%;
+    max-width: 100%;
+    display: inline-block;
+}
+
+.branching-scenario .media-overlay img {
+    width: 100%;
+    height: auto;
+    display: block;
+    object-fit: cover;
+    border-radius: 0.5rem;
+}
+
+.branching-scenario .media-overlay__text {
+    position: absolute;
+    left: 50%;
+    bottom: 1.25rem;
+    transform: translateX(-50%);
+    width: calc(100% - 3rem);
+    max-width: 90%;
+    background: rgba(8, 36, 73, 0.85);
+    color: #fff;
+    padding: 1rem 1.5rem;
+    border-radius: 0.5rem;
+    font-size: 1.05rem;
+    line-height: 1.5;
+    box-shadow: 0 8px 20px rgba(0, 0, 0, 0.3);
+}
+
+.branching-scenario .media-overlay__text p {
+    margin: 0;
+}
+
+@media (max-width: 768px) {
+    .branching-scenario .media-overlay__text {
+        position: static;
+        transform: none;
+        width: 100%;
+        margin-top: 0.75rem;
+    }
+}
+
 .branching-scenario .node-media img,
 .branching-scenario .node-media video,
 .branching-scenario .node-media iframe {
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index c907de3..9528af0 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -239,3 +239,18 @@
     margin-top: 0.25em;
     font-style: italic;
 }
+
+.overlay-text-control {
+    margin-bottom: 1em;
+}
+
+.overlay-text-control.is-hidden {
+    display: none;
+}
+
+.overlay-text-toggle {
+    display: flex;
+    align-items: center;
+    gap: 0.5em;
+    font-weight: 600;
+}
diff --git a/branching_xblock/static/handlebars/node-block.handlebars b/branching_xblock/static/handlebars/node-block.handlebars
index 7e74891..661f816 100644
--- a/branching_xblock/static/handlebars/node-block.handlebars
+++ b/branching_xblock/static/handlebars/node-block.handlebars
@@ -22,6 +22,12 @@
       </label>
     </div>
   </label>
+  <div class="overlay-text-control {{#unless (eq node.media.type 'image')}}is-hidden{{/unless}}">
+    <label class="overlay-text-toggle">
+      <input type="checkbox" class="overlay-text-checkbox" {{#if node.overlay_text}}checked{{/if}}>
+      Overlay text on image
+    </label>
+  </div>
   <label>Hint:<br/>
     <textarea class="node-hint">{{node.hint}}</textarea>
   </label>
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index 5d3f82f..34611c4 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -89,6 +89,9 @@ function BranchingXBlock(runtime, element) {
 
         const media = (node && node.media) || {};
         const mediaUrl = media.url || '';
+        const contentHtml = (node && node.content) || '';
+        const overlayEnabled = Boolean(node?.overlay_text && media.type === 'image');
+
         const $media = $el.find('[data-role="media"]');
         const $transcript = $el.find('[data-role="transcript"]');
         const setTranscript = (href) => {
@@ -98,7 +101,16 @@ function BranchingXBlock(runtime, element) {
                 $transcript.prop('hidden', true).empty();
             }
         };
-        if (media.type === 'image') {
+        if (media.type === 'image' && overlayEnabled) {
+            $media.html(`
+                <div class="media-overlay">
+                    <img src="${media.url}" alt=""/>
+                    <div class="media-overlay__text">
+                        ${contentHtml}
+                    </div>
+                </div>
+            `);
+        } else if (media.type === 'image') {
             $media.html(`<img src="${mediaUrl}" alt=""/>`);
             setTranscript(null);
         } else if (media.type === 'audio') {
@@ -121,8 +133,12 @@ function BranchingXBlock(runtime, element) {
             setTranscript(null);
         }
         // Content
-        const nodeContent = (node && node.content) || '';
-        $el.find('[data-role="content"]').html(nodeContent);
+        const $content = $el.find('[data-role="content"]');
+        if (overlayEnabled) {
+            $content.empty();
+        } else {
+            $content.html(contentHtml);
+        }
 
         // Hint
         const nodeId = node?.id || null;
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index f8de786..daec06f 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -19,6 +19,16 @@ function BranchingStudioEditor(runtime, element, data) {
     return `temp-${i}`;
   };
 
+  function loadState() {
+      return $.ajax({
+        type: 'POST',
+        url: runtime.handlerUrl(element, 'get_current_state'),
+        data: '{}',
+        contentType: 'application/json; charset=utf-8',
+        dataType: 'json'
+      });
+  }
+
   function render(state) {
     $editor.empty();
     $errors.empty();
@@ -31,6 +41,7 @@ function BranchingStudioEditor(runtime, element, data) {
         media: {type: '', url: ''},
         choices: [],
         hint: '',
+        overlay_text: false,
         transcript_url: ''
       });
     }
@@ -38,6 +49,7 @@ function BranchingStudioEditor(runtime, element, data) {
     $editor.append(Templates['settings-panel'](state));
 
     nodes.forEach((node, idx) => {
+
       const options = nodes.map((n, j) => ({
         id: n.id,
         label: `Node ${j+1}`
@@ -118,6 +130,18 @@ function BranchingStudioEditor(runtime, element, data) {
     });
   }
 
+  function toggleOverlayControl($node) {
+    const type = $node.find('.media-type').val();
+    const $control = $node.find('.overlay-text-control');
+    const $checkbox = $node.find('.overlay-text-checkbox');
+    if (type === 'image') {
+      $control.removeClass('is-hidden');
+    } else {
+      $control.addClass('is-hidden');
+      $checkbox.prop('checked', false);
+    }
+  }
+
   function bindInteractions() {
     $editor.find('.btn-delete-node').off('click').on('click', function() {
       $(this).closest('.node-block').remove();
@@ -161,6 +185,7 @@ function BranchingStudioEditor(runtime, element, data) {
           media:   { type: '', url: '' },
           choices: [],
           hint:    '',
+          overlay_text: false,
           transcript_url: ''
         },
         idx
@@ -172,6 +197,15 @@ function BranchingStudioEditor(runtime, element, data) {
       updateChoiceUI();
       updateTranscriptVisibility($newNode);
     });
+
+    $editor.find('.media-type').off('change.overlay').on('change.overlay', function() {
+      const $node = $(this).closest('.node-block');
+      toggleOverlayControl($node);
+    });
+
+    $editor.find('.node-block').each(function() {
+      toggleOverlayControl($(this));
+    });
   }
 
   function bindActions() {
@@ -195,6 +229,7 @@ function BranchingStudioEditor(runtime, element, data) {
         const mediaType = $n.find('.media-type').val();
         const choices = [];
         const nodeHint = $n.find('.node-hint').val()?.trim() || '';
+        const overlayEnabled = $n.find('.overlay-text-checkbox').is(':checked');
         const transcriptUrl = $n.find('.transcript-url').val()?.trim() || '';
 
         $n.find('.choice-row').each(function() {
@@ -212,6 +247,7 @@ function BranchingStudioEditor(runtime, element, data) {
               media:  { type: mediaType, url: mediaUrl },
               choices,
               hint: nodeHint,
+              overlay_text: overlayEnabled,
               transcript_url: transcriptUrl
           });
         }
@@ -243,5 +279,5 @@ function BranchingStudioEditor(runtime, element, data) {
     });
   }
 
-  render(data || {});
+  loadState().then(render);
 }

From 06e40d3209259a73323ef4176c3b2b6bd6a5aff4 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Tue, 18 Nov 2025 15:15:56 -0500
Subject: [PATCH 02/32] refactor: change choices to radio single choice

---
 .../static/css/branching_xblock.css           | 122 +++++++++++++-----
 branching_xblock/static/css/studio_editor.css |   6 +
 .../static/handlebars/node-block.handlebars   |   1 +
 .../static/html/branching_xblock.html         |  19 ++-
 .../static/js/src/branching_xblock.js         |  66 +++++++---
 5 files changed, 156 insertions(+), 58 deletions(-)

diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 73bd075..282eaf8 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -182,66 +182,118 @@
 
 
 .branching-scenario .choices {
+    padding: 1.5em 1em;
+}
+
+.branching-scenario .choices-heading {
+    font-size: 1.15rem;
+    font-weight: 600;
+    margin-bottom: 1rem;
+    color: #1f2a37;
+}
+
+.branching-scenario .choices-form {
     display: flex;
-    flex-wrap: wrap;
-    gap: 0.75em;
-    padding: 1em;
-    justify-content: flex-start;
+    flex-direction: column;
+    gap: 1rem;
 }
 
-/* inline mode keeps the natural width */
-.branching-scenario .choices-inline {
-    flex-wrap: wrap;
+.branching-scenario .choices-list {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+}
+
+.branching-scenario .choice-option {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.75rem;
+    border: 1px solid #d6d6d6;
+    border-radius: 8px;
+    padding: 0.9rem 1rem;
+    background-color: #fff;
+    transition: border-color 0.2s ease, box-shadow 0.2s ease, background-color 0.2s ease;
+    cursor: pointer;
+}
+
+.branching-scenario .choice-option:hover,
+.branching-scenario .choice-option:focus-within {
+    border-color: #3b82f6;
+    box-shadow: 0 0 0 2px rgba(59, 130, 246, 0.2);
+}
+
+.branching-scenario .choice-option.is-selected {
+    border-color: #0f62a1;
+    box-shadow: 0 0 0 2px rgba(15, 98, 161, 0.25);
+    background-color: #f0f7ff;
+}
+
+.branching-scenario .choice-option__input {
+    margin-top: 0.2rem;
+    width: 1.1rem;
+    height: 1.1rem;
+}
+
+.branching-scenario .choice-option__text {
+    flex: 1;
+    font-size: 1rem;
+    color: #1f2a37;
+}
+
+.branching-scenario .choice-actions {
+    display: flex;
     justify-content: space-between;
     align-items: center;
+    gap: 1rem;
+    flex-wrap: wrap;
 }
 
-.branching-scenario .choices .choice-button {
+.choice-submit-button {
+    border: none;
+    background-color: #0f62a1;
     color: #fff;
-    border: 1px solid #0e6aa6;
     border-radius: 6px;
-    padding: 0.65em 1.4em;
+    padding: 0.7rem 1.5rem;
     font-size: 1rem;
-    font-weight: 400;
+    font-weight: 600;
     cursor: pointer;
-    background-color: #0075b4;
-    background-image: none !important;
-    box-shadow: none !important;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    flex-wrap: wrap;
-    gap: 0.35em;
-    line-height: 1.3;
-    white-space: normal;
-    text-align: center;
-    min-width: 6rem;
-    max-width: 100%;
-    flex: 0 1 18rem;
+    transition: background-color 0.2s ease;
 }
 
-.branching-scenario .choices-inline .choice-button {
-    flex: 0 0 auto;
+.choice-submit-button:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
 }
 
-.branching-scenario .choices .choice-button:hover,
-.branching-scenario .choices .choice-button:focus {
-    background-color: #005f94;
-    border-color: #0a5278;
-    text-decoration: none;
+.choice-submit-button:not(:disabled):hover,
+.choice-submit-button:not(:disabled):focus {
+    background-color: #0c4f83;
 }
 
 .undo-button {
-    border: none;
+    border: 1px solid #4a5568;
     border-radius: 4px;
     padding: 0.6em 1.2em;
     font-size: 1em;
     cursor: pointer;
-    background-image: none !important;
-    margin-left: 1em;
+    background: transparent;
+    color: #1f2a37;
 }
 
 .score-display {
     padding: 1em 1em;
     font-size: small;
 }
+
+@media (max-width: 600px) {
+    .branching-scenario .choice-actions {
+        flex-direction: column-reverse;
+        align-items: stretch;
+    }
+
+    .undo-button,
+    .choice-submit-button {
+        width: 100%;
+        text-align: center;
+    }
+}
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index 9528af0..1c27505 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -254,3 +254,9 @@
     gap: 0.5em;
     font-weight: 600;
 }
+
+.overlay-text-help {
+    margin: 0.5em 0 0;
+    font-size: 0.85em;
+    color: #555;
+}
diff --git a/branching_xblock/static/handlebars/node-block.handlebars b/branching_xblock/static/handlebars/node-block.handlebars
index 661f816..9652af2 100644
--- a/branching_xblock/static/handlebars/node-block.handlebars
+++ b/branching_xblock/static/handlebars/node-block.handlebars
@@ -27,6 +27,7 @@
       <input type="checkbox" class="overlay-text-checkbox" {{#if node.overlay_text}}checked{{/if}}>
       Overlay text on image
     </label>
+    <p class="overlay-text-help">If left unchecked, text will appear outside the image.</p>
   </div>
   <label>Hint:<br/>
     <textarea class="node-hint">{{node.hint}}</textarea>
diff --git a/branching_xblock/static/html/branching_xblock.html b/branching_xblock/static/html/branching_xblock.html
index 1dbd793..92f5799 100644
--- a/branching_xblock/static/html/branching_xblock.html
+++ b/branching_xblock/static/html/branching_xblock.html
@@ -11,11 +11,20 @@
                 <div data-role="hint" class="node-hint px-2 py-3"></div>
             </details>
         </div>
-        <div class="choices" data-role="choices"></div>
-
-        <button class="undo-button action-secondary btn-secondary" data-role="undo" style="display: none;">
-            <i class="fa fa-undo" aria-hidden="true"></i>&nbsp;Undo
-        </button>
+        <div class="choices" data-role="choices">
+            <h3 class="choices-heading" data-role="choice-heading">Choose Next Step:</h3>
+            <form class="choices-form" data-role="choice-form">
+                <div class="choices-list" data-role="choice-list"></div>
+                <div class="choice-actions">
+                    <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo" style="display: none;">
+                        Go Back
+                    </button>
+                    <button type="submit" class="choice-submit-button action-primary" data-role="submit-choice" disabled>
+                        Submit
+                    </button>
+                </div>
+            </form>
+        </div>
 
         <div class="score-display" data-role="score" style="display: none;"></div>
     </div>
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index 34611c4..6dca839 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -3,6 +3,7 @@ function BranchingXBlock(runtime, element) {
 
     let currentHintNodeId = null;
     let isHintVisible = false;
+    let selectedChoiceIndex = null;
 
     const MEDIA_FILE_REGEX = /\.(mp4|webm|ogg|mp3|wav)(\?|#|$)/i;
 
@@ -160,19 +161,36 @@ function BranchingXBlock(runtime, element) {
         }
 
         // Choices
-        const $choices = $el.find('[data-role="choices"]').empty();
+        const $choiceForm = $el.find('[data-role="choice-form"]');
+        const $choiceList = $el.find('[data-role="choice-list"]').empty();
+        const $submitButton = $el.find('[data-role="submit-choice"]').prop('disabled', true);
         const choices = node.choices || [];
+        const canUndo = state.enable_undo && state.history.length > 0;
+        selectedChoiceIndex = null;
         choices.forEach((choice, idx) => {
-            $('<button>')
-            .addClass('choice-button bg-primary')
-            .text(choice.text)
-            .attr('data-choice-index', idx)
-            .appendTo($choices);
+            const choiceId = `choice-${node.id || 'node'}-${idx}`;
+            const $label = $('<label>')
+                .addClass('choice-option')
+                .attr('for', choiceId);
+            const $input = $('<input>')
+                .attr({
+                    type: 'radio',
+                    name: 'branching-choice',
+                    id: choiceId,
+                    value: idx,
+                })
+                .addClass('choice-option__input');
+            const $text = $('<span>')
+                .addClass('choice-option__text')
+                .text(choice.text || `Choice ${idx + 1}`);
+            $label.append($input).append($text);
+            $choiceList.append($label);
         });
+        const hasChoices = choices.length > 0;
+        $el.find('[data-role="choice-heading"]').toggle(hasChoices);
+        $submitButton.closest('.choice-actions').toggle(hasChoices || canUndo);
+        $submitButton.toggle(hasChoices);
 
-        $choices.addClass('choices-inline');
-
-        const canUndo = state.enable_undo && state.history.length > 0;
         $el.find('.undo-button').toggle(canUndo);
 
         const $score = $el.find('[data-role="score"]');
@@ -198,15 +216,27 @@ function BranchingXBlock(runtime, element) {
         setHintVisibility(this.open);
     });
 
-    // Handle a choice click
-    $el.on('click', '.choice-button', function() {
-      const idx = +$(this).attr('data-choice-index');
-      $.ajax({
-        url: runtime.handlerUrl(element, 'select_choice'),
-        type: 'POST',
-        data: JSON.stringify({ choice_index: idx }),
-        contentType: 'application/json'
-      }).done(refreshView);
+    $el.on('change', 'input[name="branching-choice"]', function() {
+        selectedChoiceIndex = Number(this.value);
+        $el.find('[data-role="submit-choice"]').prop('disabled', false);
+        $el.find('.choice-option').removeClass('is-selected');
+        $(this).closest('.choice-option').addClass('is-selected');
+    });
+
+    $el.on('submit', '[data-role="choice-form"]', function(event) {
+        event.preventDefault();
+        if (selectedChoiceIndex === null) {
+            return;
+        }
+        $.ajax({
+            url: runtime.handlerUrl(element, 'select_choice'),
+            type: 'POST',
+            data: JSON.stringify({ choice_index: selectedChoiceIndex }),
+            contentType: 'application/json'
+        }).done(() => {
+            selectedChoiceIndex = null;
+            refreshView();
+        });
     });
 
     $el.on('click', '.undo-button', function() {

From e35a6cffc0379c18873f06a116f446c5d2fe794e Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Tue, 18 Nov 2025 15:26:10 -0500
Subject: [PATCH 03/32] fix: button appearance

---
 branching_xblock/static/css/branching_xblock.css   | 5 +++++
 branching_xblock/static/css/studio_editor.css      | 1 -
 branching_xblock/static/html/branching_xblock.html | 2 +-
 branching_xblock/static/js/src/branching_xblock.js | 8 +++++---
 4 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 282eaf8..26acc23 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -280,6 +280,11 @@
     color: #1f2a37;
 }
 
+.undo-button.is-disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
 .score-display {
     padding: 1em 1em;
     font-size: small;
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index 1c27505..9614d1f 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -252,7 +252,6 @@
     display: flex;
     align-items: center;
     gap: 0.5em;
-    font-weight: 600;
 }
 
 .overlay-text-help {
diff --git a/branching_xblock/static/html/branching_xblock.html b/branching_xblock/static/html/branching_xblock.html
index 92f5799..c4f2964 100644
--- a/branching_xblock/static/html/branching_xblock.html
+++ b/branching_xblock/static/html/branching_xblock.html
@@ -16,7 +16,7 @@ <h3 class="choices-heading" data-role="choice-heading">Choose Next Step:</h3>
             <form class="choices-form" data-role="choice-form">
                 <div class="choices-list" data-role="choice-list"></div>
                 <div class="choice-actions">
-                    <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo" style="display: none;">
+                    <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo">
                         Go Back
                     </button>
                     <button type="submit" class="choice-submit-button action-primary" data-role="submit-choice" disabled>
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index 6dca839..0025a24 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -188,10 +188,12 @@ function BranchingXBlock(runtime, element) {
         });
         const hasChoices = choices.length > 0;
         $el.find('[data-role="choice-heading"]').toggle(hasChoices);
-        $submitButton.closest('.choice-actions').toggle(hasChoices || canUndo);
-        $submitButton.toggle(hasChoices);
+        const disableSubmit = !hasChoices || selectedChoiceIndex === null;
+        $submitButton.prop('disabled', disableSubmit);
 
-        $el.find('.undo-button').toggle(canUndo);
+        $el.find('.undo-button')
+            .prop('disabled', !canUndo)
+            .toggleClass('is-disabled', !canUndo);
 
         const $score = $el.find('[data-role="score"]');
         const isLeaf = choices.length === 0;

From 3f6f5466a1f2b02b61e2a6a9fe4ffc06d08b5cdf Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 29 Jan 2026 11:19:52 -0500
Subject: [PATCH 04/32] refactor: replace hint settings with reset option

---
 branching_xblock/branching_xblock.py          | 32 +++++++++++++++----
 .../static/css/branching_xblock.css           | 11 +++++++
 .../handlebars/settings-panel.handlebars      |  4 +--
 .../static/html/branching_xblock.html         |  3 ++
 .../static/js/src/branching_xblock.js         | 25 ++++++++++++---
 .../static/js/src/studio_editor.js            | 16 +++++-----
 6 files changed, 70 insertions(+), 21 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 75238af..f975675 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -68,10 +68,10 @@ class BranchingXBlock(XBlock):
         help="Enable scoring for gradebook integration"
     )
 
-    enable_hints = Boolean(
+    enable_reset_activity = Boolean(
         default=False,
-        scope=Scope.settings,
-        help="Allow learners to reveal hints for each node"
+        scope=Scope.content,
+        help="Allow learners to reset the activity"
     )
 
     max_score = Float(
@@ -245,7 +245,7 @@ def studio_view(self, context=None):
             "nodes":       self.scenario_data.get("nodes", []),
             "enable_undo": bool(self.enable_undo),
             "enable_scoring": bool(self.enable_scoring),
-            "enable_hints": bool(self.enable_hints),
+            "enable_reset_activity": bool(self.enable_reset_activity),
             "max_score":   self.max_score,
             "display_name": self.display_name,
             "authoring_help_html": authoring_help_html,
@@ -269,7 +269,7 @@ def _get_state(self):
             "start_node_id":   self.scenario_data.get("start_node_id"),
             "enable_undo":     bool(self.enable_undo),
             "enable_scoring":  bool(self.enable_scoring),
-            "enable_hints":    bool(self.enable_hints),
+            "enable_reset_activity": bool(self.enable_reset_activity),
             "max_score":       self.max_score,
             "display_name":    self.display_name,
             "current_node":    self.get_current_node(),
@@ -333,6 +333,26 @@ def undo_choice(self, data, suffix=''):
         self.has_completed = False
         return {"success": True, **self._get_state()}
 
+    @XBlock.json_handler
+    def reset_activity(self, data, suffix=''):
+        """
+        Reset learner state to the start node.
+        """
+        if not self.enable_reset_activity:
+            return {"success": False, "error": "Reset not allowed"}
+
+        self.current_node_id = None
+        self.history = []
+        self.has_completed = False
+
+        if self.enable_scoring:
+            self.score = 0.0
+            self.publish_grade()
+
+        self.start_node()
+        self.runtime.publish(self, "completion", {"completion": 0.0})
+        return {"success": True, **self._get_state()}
+
     @XBlock.json_handler
     def studio_submit(self, data, suffix=''):
         """
@@ -411,7 +431,7 @@ def studio_submit(self, data, suffix=''):
         }
         self.enable_undo = bool(payload.get('enable_undo', self.enable_undo))
         self.enable_scoring = bool(payload.get('enable_scoring', self.enable_scoring))
-        self.enable_hints = bool(payload.get('enable_hints', self.enable_hints))
+        self.enable_reset_activity = bool(payload.get('enable_reset_activity', self.enable_reset_activity))
         self.max_score = float(payload.get('max_score', self.max_score))
         self.display_name = payload.get('display_name', self.display_name)
 
diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 26acc23..e5554aa 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -285,6 +285,16 @@
     cursor: not-allowed;
 }
 
+.reset-button {
+    border: 1px solid #4a5568;
+    border-radius: 4px;
+    padding: 0.6em 1.2em;
+    font-size: 1em;
+    cursor: pointer;
+    background: transparent;
+    color: #1f2a37;
+}
+
 .score-display {
     padding: 1em 1em;
     font-size: small;
@@ -297,6 +307,7 @@
     }
 
     .undo-button,
+    .reset-button,
     .choice-submit-button {
         width: 100%;
         text-align: center;
diff --git a/branching_xblock/static/handlebars/settings-panel.handlebars b/branching_xblock/static/handlebars/settings-panel.handlebars
index fbe3616..e0f1a70 100644
--- a/branching_xblock/static/handlebars/settings-panel.handlebars
+++ b/branching_xblock/static/handlebars/settings-panel.handlebars
@@ -12,8 +12,8 @@
     Enable scoring
   </label>
   <label>
-    <input type="checkbox" name="enable_hints" {{#if enable_hints}}checked{{/if}}/>
-    Allow learners to reveal hints
+    <input type="checkbox" name="enable_reset_activity" {{#if enable_reset_activity}}checked{{/if}}/>
+    Enable reset activity
   </label>
   <label>
     Max Score:
diff --git a/branching_xblock/static/html/branching_xblock.html b/branching_xblock/static/html/branching_xblock.html
index c4f2964..b85cbc0 100644
--- a/branching_xblock/static/html/branching_xblock.html
+++ b/branching_xblock/static/html/branching_xblock.html
@@ -19,6 +19,9 @@ <h3 class="choices-heading" data-role="choice-heading">Choose Next Step:</h3>
                     <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo">
                         Go Back
                     </button>
+                    <button type="button" class="reset-button action-secondary btn-secondary" data-role="reset-activity" style="display: none;">
+                        Reset Activity
+                    </button>
                     <button type="submit" class="choice-submit-button action-primary" data-role="submit-choice" disabled>
                         Submit
                     </button>
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index 0025a24..410efc5 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -111,6 +111,7 @@ function BranchingXBlock(runtime, element) {
                     </div>
                 </div>
             `);
+            setTranscript(null);
         } else if (media.type === 'image') {
             $media.html(`<img src="${mediaUrl}" alt=""/>`);
             setTranscript(null);
@@ -150,8 +151,9 @@ function BranchingXBlock(runtime, element) {
         const $hintContainer = $el.find('[data-role="hint-container"]');
         const $hintDetails = $hintContainer.find('[data-role="hint-collapsible"]');
         const $hint = $hintDetails.find('[data-role="hint"]');
-        if (state.enable_hints && node && node.hint) {
-            $hint.html(`<strong>Hint:</strong> ${node.hint}`);
+        const hintText = (node && node.hint ? String(node.hint) : '').trim();
+        if (node && hintText) {
+            $hint.html(`<strong>Hint:</strong> ${hintText}`);
             $hintDetails.prop('hidden', false);
             setHintVisibility(isHintVisible);
         } else {
@@ -187,16 +189,19 @@ function BranchingXBlock(runtime, element) {
             $choiceList.append($label);
         });
         const hasChoices = choices.length > 0;
+        const isLeaf = !hasChoices;
+        const showReset = Boolean(state.enable_reset_activity && isLeaf);
         $el.find('[data-role="choice-heading"]').toggle(hasChoices);
-        const disableSubmit = !hasChoices || selectedChoiceIndex === null;
-        $submitButton.prop('disabled', disableSubmit);
+        $submitButton.toggle(hasChoices);
+        $submitButton.prop('disabled', !hasChoices || selectedChoiceIndex === null);
+        $el.find('.choice-actions').toggle(hasChoices || canUndo || showReset);
 
         $el.find('.undo-button')
             .prop('disabled', !canUndo)
             .toggleClass('is-disabled', !canUndo);
 
         const $score = $el.find('[data-role="score"]');
-        const isLeaf = choices.length === 0;
+        $el.find('[data-role="reset-activity"]').toggle(showReset);
         if (isLeaf && state.enable_scoring) {
             $score.text(`Score: ${state.score}/${state.max_score}`).show();
         } else {
@@ -251,6 +256,16 @@ function BranchingXBlock(runtime, element) {
         }).done(refreshView);
     });
 
+    $el.on('click', '[data-role="reset-activity"]', function() {
+        $.ajax({
+          url: runtime.handlerUrl(element, 'reset_activity'),
+          type: 'POST',
+          data: JSON.stringify({}),
+          contentType: 'application/json',
+          dataType: 'json'
+        }).done(refreshView);
+    });
+
     // Initial load
     refreshView();
 
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index daec06f..a2a874c 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -213,14 +213,14 @@ function BranchingStudioEditor(runtime, element, data) {
     const $settings = $editor.find('.settings');
 
     $saveBtn.off('click').on('click', function() {
-      const payload = {
-          nodes: [],
-          enable_undo:    $settings.find('[name="enable_undo"]').is(':checked'),
-          enable_scoring: $settings.find('[name="enable_scoring"]').is(':checked'),
-          enable_hints:   $settings.find('[name="enable_hints"]').is(':checked'),
-          max_score:      parseFloat($settings.find('[name="max_score"]').val()) || 0,
-          display_name:   $settings.find('[name="display_name"]').val()?.trim() || ''
-      };
+	      const payload = {
+	          nodes: [],
+	          enable_undo:    $settings.find('[name="enable_undo"]').is(':checked'),
+	          enable_scoring: $settings.find('[name="enable_scoring"]').is(':checked'),
+	          enable_reset_activity: $settings.find('[name="enable_reset_activity"]').is(':checked'),
+	          max_score:      parseFloat($settings.find('[name="max_score"]').val()) || 0,
+	          display_name:   $settings.find('[name="display_name"]').val()?.trim() || ''
+	      };
 
       $editor.find('.node-block').each(function() {
         const $n = $(this);

From 62f601b553b69927a990f117548916ef270b5561 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 29 Jan 2026 14:52:06 -0500
Subject: [PATCH 05/32] refactor: updated studio editor

---
 branching_xblock/branching_xblock.py          |  49 +-
 branching_xblock/static/css/studio_editor.css | 181 +++++-
 .../static/handlebars/node-editor.handlebars  |  55 ++
 .../handlebars/node-list-item.handlebars      |   9 +
 .../static/handlebars/nodes-step.handlebars   |  12 +
 .../handlebars/settings-step.handlebars       |  56 ++
 .../static/html/branching_xblock_edit.html    |  10 +-
 .../static/js/src/studio_editor.js            | 513 +++++++++++-------
 8 files changed, 674 insertions(+), 211 deletions(-)
 create mode 100644 branching_xblock/static/handlebars/node-editor.handlebars
 create mode 100644 branching_xblock/static/handlebars/node-list-item.handlebars
 create mode 100644 branching_xblock/static/handlebars/nodes-step.handlebars
 create mode 100644 branching_xblock/static/handlebars/settings-step.handlebars

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index f975675..4cfabfc 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -74,6 +74,24 @@ class BranchingXBlock(XBlock):
         help="Allow learners to reset the activity"
     )
 
+    background_image_url = String(
+        default="",
+        scope=Scope.content,
+        help="Background image URL used for image nodes"
+    )
+
+    background_image_alt_text = String(
+        default="",
+        scope=Scope.content,
+        help="Alt text for the background image"
+    )
+
+    background_image_is_decorative = Boolean(
+        default=False,
+        scope=Scope.content,
+        help="Whether the background image is decorative"
+    )
+
     max_score = Float(
         default=100.0,
         scope=Scope.content,
@@ -224,7 +242,13 @@ def studio_view(self, context=None):
         frag.add_javascript_url(
             self.runtime.local_resource_url(self, 'public/js/vendor/handlebars.js')
         )
-        for tpl in ['settings-panel', 'node-block', 'choice-row']:
+        for tpl in [
+            'settings-step',
+            'nodes-step',
+            'node-list-item',
+            'node-editor',
+            'choice-row',
+        ]:
             html = resource_loader.load_unicode(f'static/handlebars/{tpl}.handlebars')
             frag.add_javascript(f"""
                 (function() {{
@@ -270,6 +294,9 @@ def _get_state(self):
             "enable_undo":     bool(self.enable_undo),
             "enable_scoring":  bool(self.enable_scoring),
             "enable_reset_activity": bool(self.enable_reset_activity),
+            "background_image_url": self.background_image_url,
+            "background_image_alt_text": self.background_image_alt_text,
+            "background_image_is_decorative": bool(self.background_image_is_decorative),
             "max_score":       self.max_score,
             "display_name":    self.display_name,
             "current_node":    self.get_current_node(),
@@ -360,6 +387,23 @@ def studio_submit(self, data, suffix=''):
         """
         payload = data
         raw_nodes = payload.get('nodes', [])
+        background_image_url = (payload.get('background_image_url') or '').strip()
+        background_image_alt_text = (payload.get('background_image_alt_text') or '').strip()
+        background_image_is_decorative = bool(payload.get('background_image_is_decorative', False))
+
+        if len(raw_nodes) > 30:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {"nodes_json": ["Too many nodes (max 30)."]}
+            }
+
+        if background_image_url and not background_image_is_decorative and not background_image_alt_text:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {"nodes_json": ["Background image alt text is required unless the image is marked decorative."]}
+            }
 
         # 1) Assign real IDs and build id_map
         id_map = {}
@@ -434,6 +478,9 @@ def studio_submit(self, data, suffix=''):
         self.enable_reset_activity = bool(payload.get('enable_reset_activity', self.enable_reset_activity))
         self.max_score = float(payload.get('max_score', self.max_score))
         self.display_name = payload.get('display_name', self.display_name)
+        self.background_image_url = background_image_url
+        self.background_image_alt_text = background_image_alt_text
+        self.background_image_is_decorative = background_image_is_decorative
 
         # 4) Validate & respond
         errors = self.validate_scenario()
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index 9614d1f..5c60da0 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -7,9 +7,19 @@
     padding: 1em;
 }
 
+.branching-editor-step[hidden] {
+    display: none !important;
+}
+
+.xblock-actions [hidden] {
+    display: none !important;
+}
+
 .xblock-actions {
     display: flex;
-    justify-content: space-between;
+    justify-content: flex-start;
+    align-items: center;
+    gap: 1em;
     padding: 0.75em 1em;
     border-top: 1px solid #e0e0e0;
     background: #fff;
@@ -19,6 +29,175 @@
     box-shadow: 0 -2px 6px rgba(0, 0, 0, 0.05);
 }
 
+.xblock-actions [data-role="back"],
+.xblock-actions [data-role="cancel"] {
+    background: none;
+    border: none;
+    padding: 0;
+    color: #0f62a1;
+    text-decoration: none;
+}
+
+.xblock-actions [data-role="back"]:hover,
+.xblock-actions [data-role="cancel"]:hover {
+    text-decoration: underline;
+}
+
+.bx-wizard {
+    max-width: 980px;
+}
+
+.bx-step-title {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin: 0 0 1rem;
+}
+
+.bx-section-title {
+    font-size: 1rem;
+    font-weight: 600;
+    margin: 1.5rem 0 0.5rem;
+}
+
+.bx-help {
+    margin: 0 0 1rem;
+    font-size: 0.9em;
+    color: #555;
+}
+
+.bx-field {
+    display: block;
+    margin-bottom: 1rem;
+}
+
+.bx-field__label {
+    font-weight: 600;
+    margin-bottom: 0.35rem;
+}
+
+.bx-input,
+.bx-select,
+.bx-textarea {
+    width: 100%;
+    box-sizing: border-box;
+}
+
+.bx-textarea {
+    min-height: 8em;
+    resize: vertical;
+}
+
+.bx-checkbox {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin: 0.5rem 0;
+}
+
+.bx-checkbox--nested {
+    margin: 0.25rem 0 0.5rem;
+}
+
+.bx-nodes-step {
+    display: flex;
+    gap: 1rem;
+    min-height: 520px;
+}
+
+.bx-nodes-sidebar {
+    width: 220px;
+    flex: none;
+    border-right: 1px solid #e0e0e0;
+    padding-right: 1rem;
+}
+
+.bx-btn {
+    border: 1px solid #0f62a1;
+    border-radius: 4px;
+    padding: 0.5rem 0.75rem;
+    cursor: pointer;
+}
+
+.bx-btn--primary {
+    background: #0f62a1;
+    color: #fff;
+}
+
+.bx-btn--primary:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+.bx-btn--secondary {
+    background: #28a745;
+    border-color: #28a745;
+    color: #fff;
+    margin: 0.5rem 0;
+}
+
+.bx-node-limit {
+    margin: 0.5rem 0 1rem;
+    font-size: 0.85em;
+    color: #666;
+}
+
+.bx-node-list {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+}
+
+.bx-node-list-item {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    border: 1px solid transparent;
+    border-radius: 4px;
+    padding: 0.4rem 0.5rem;
+}
+
+.bx-node-list-item.is-selected {
+    background: #f3f4f6;
+    border-color: #e5e7eb;
+}
+
+.bx-node-list-item__select {
+    background: none;
+    border: none;
+    padding: 0;
+    text-align: left;
+    cursor: pointer;
+    flex: 1;
+}
+
+.bx-node-list-item__delete {
+    background: none;
+    border: none;
+    cursor: pointer;
+    opacity: 0.7;
+}
+
+.bx-node-list-item__delete:hover {
+    opacity: 1;
+}
+
+.bx-nodes-main {
+    flex: 1;
+    padding-left: 0.5rem;
+}
+
+.bx-node-editor-inner .bx-help {
+    margin-top: 0.35rem;
+}
+
+.bx-choices .choices-container {
+    margin-top: 0.75rem;
+}
+
+.is-hidden {
+    display: none !important;
+}
+
 .xblock-actions .action-item {
     margin: 0 0.25em;
 }
diff --git a/branching_xblock/static/handlebars/node-editor.handlebars b/branching_xblock/static/handlebars/node-editor.handlebars
new file mode 100644
index 0000000..5927cfb
--- /dev/null
+++ b/branching_xblock/static/handlebars/node-editor.handlebars
@@ -0,0 +1,55 @@
+<div class="bx-node-editor-inner" data-node-id="{{id}}">
+  <h2 class="bx-step-title">Node {{number}}</h2>
+
+  <label class="bx-field">
+    <div class="bx-field__label">Content</div>
+    <textarea class="bx-textarea" data-role="node-content">{{content}}</textarea>
+  </label>
+
+  <label class="bx-field">
+    <div class="bx-field__label">Media</div>
+    <select class="bx-select" data-role="media-type">
+      <option value="" {{#unless media.type}}selected{{/unless}}>None</option>
+      <option value="image" {{#if (eq media.type 'image')}}selected{{/if}}>Image</option>
+      <option value="video" {{#if (eq media.type 'video')}}selected{{/if}}>Video</option>
+      <option value="audio" {{#if (eq media.type 'audio')}}selected{{/if}}>Audio</option>
+    </select>
+  </label>
+
+  <label class="bx-field {{#unless show_media_url}}is-hidden{{/unless}}" data-role="media-url-field">
+    <div class="bx-field__label">URL</div>
+    <input type="text" class="bx-input" data-role="media-url" placeholder="URL" value="{{media.url}}" />
+    <div class="bx-help">Supports direct media files (.mp4/.webm/.mp3) or links from YouTube, Vimeo, Panopto.</div>
+  </label>
+
+  <label class="bx-field {{#unless show_transcript}}is-hidden{{/unless}}" data-role="transcript-url-field">
+    <div class="bx-field__label">Transcript URL</div>
+    <input type="text" class="bx-input" data-role="transcript-url" placeholder="https://..." value="{{transcript_url}}" />
+  </label>
+
+  <div class="overlay-text-control {{#unless show_overlay}}is-hidden{{/unless}}" data-role="overlay-text-control">
+    <label class="overlay-text-toggle">
+      <input type="checkbox" class="overlay-text-checkbox" data-role="overlay-text" {{#if overlay_text}}checked{{/if}}>
+      Overlay text on image
+    </label>
+    <p class="overlay-text-help">If left unchecked, text will appear outside the image.</p>
+  </div>
+
+  <label class="bx-checkbox">
+    <input type="checkbox" data-role="no-branches" {{#if no_branches}}checked{{/if}} />
+    <span>This node has no branches</span>
+  </label>
+
+  <label class="bx-field">
+    <div class="bx-field__label">Hint</div>
+    <textarea class="bx-textarea" data-role="node-hint">{{hint}}</textarea>
+  </label>
+
+  <div class="bx-choices {{#if no_branches}}is-hidden{{/if}}" data-role="choices-section">
+    <h3 class="bx-section-title">Choices</h3>
+    <button type="button" class="bx-btn bx-btn--secondary" data-role="add-choice">Add Choice</button>
+    <div class="bx-help">Choices with blank node targets will be discarded.</div>
+    <div class="choices-container" data-role="choices-container"></div>
+  </div>
+</div>
+
diff --git a/branching_xblock/static/handlebars/node-list-item.handlebars b/branching_xblock/static/handlebars/node-list-item.handlebars
new file mode 100644
index 0000000..3784ecf
--- /dev/null
+++ b/branching_xblock/static/handlebars/node-list-item.handlebars
@@ -0,0 +1,9 @@
+<div class="bx-node-list-item {{#if is_selected}}is-selected{{/if}}" data-node-id="{{id}}">
+  <button type="button" class="bx-node-list-item__select" data-role="select-node" data-node-id="{{id}}">
+    Node {{number}}
+  </button>
+  <button type="button" class="bx-node-list-item__delete" data-role="delete-node" data-node-id="{{id}}" aria-label="Delete node">
+    🗑
+  </button>
+</div>
+
diff --git a/branching_xblock/static/handlebars/nodes-step.handlebars b/branching_xblock/static/handlebars/nodes-step.handlebars
new file mode 100644
index 0000000..d17a56e
--- /dev/null
+++ b/branching_xblock/static/handlebars/nodes-step.handlebars
@@ -0,0 +1,12 @@
+<div class="bx-wizard bx-nodes-step">
+  <div class="bx-nodes-sidebar">
+    <button type="button" class="bx-btn bx-btn--primary" data-role="add-node">+ Add node</button>
+    <div class="bx-node-limit">Max 30 nodes</div>
+    <div class="bx-node-list" data-role="node-list"></div>
+  </div>
+
+  <div class="bx-nodes-main">
+    <div class="bx-node-editor" data-role="node-editor"></div>
+  </div>
+</div>
+
diff --git a/branching_xblock/static/handlebars/settings-step.handlebars b/branching_xblock/static/handlebars/settings-step.handlebars
new file mode 100644
index 0000000..fc76006
--- /dev/null
+++ b/branching_xblock/static/handlebars/settings-step.handlebars
@@ -0,0 +1,56 @@
+<div class="bx-wizard bx-settings-step">
+  <h2 class="bx-step-title">Settings</h2>
+
+  <label class="bx-field">
+    <div class="bx-field__label">Display Name</div>
+    <input type="text" name="display_name" value="{{display_name}}" class="bx-input" />
+  </label>
+
+  <label class="bx-checkbox">
+    <input type="checkbox" name="enable_undo" {{#if enable_undo}}checked{{/if}} />
+    <span>Let learners try the previous node again</span>
+  </label>
+
+  <label class="bx-checkbox">
+    <input type="checkbox" name="enable_reset_activity" {{#if enable_reset_activity}}checked{{/if}} />
+    <span>Let learners reset the activity</span>
+  </label>
+
+  <label class="bx-checkbox">
+    <input type="checkbox" name="enable_scoring" {{#if enable_scoring}}checked{{/if}} />
+    <span>Include a grade report at the end of the activity</span>
+  </label>
+
+  <h3 class="bx-section-title">Background image</h3>
+  <p class="bx-help">
+    This image will appear in the background of any nodes with “Image” as the media type.
+  </p>
+
+  <label class="bx-field">
+    <div class="bx-field__label">Image URL</div>
+    <input
+      type="text"
+      name="background_image_url"
+      class="bx-input"
+      placeholder="URL"
+      value="{{background_image_url}}"
+    />
+  </label>
+
+  <div class="bx-field">
+    <div class="bx-field__label">Alt text</div>
+    <label class="bx-checkbox bx-checkbox--nested">
+      <input type="checkbox" name="background_image_is_decorative" {{#if background_image_is_decorative}}checked{{/if}} />
+      <span>Decorative image</span>
+    </label>
+    <input
+      type="text"
+      name="background_image_alt_text"
+      class="bx-input"
+      placeholder="Alt text"
+      value="{{background_image_alt_text}}"
+      {{#if background_image_is_decorative}}disabled{{/if}}
+    />
+  </div>
+</div>
+
diff --git a/branching_xblock/static/html/branching_xblock_edit.html b/branching_xblock/static/html/branching_xblock_edit.html
index 1b77928..122734d 100644
--- a/branching_xblock/static/html/branching_xblock_edit.html
+++ b/branching_xblock/static/html/branching_xblock_edit.html
@@ -1,12 +1,14 @@
 <div class="wrapper-comp-settings is-active editor-with-buttons">
-  <!-- Editor UI placeholder -->
-  <div class="branching-scenario-editor"></div>
+  <div class="branching-editor-step" data-role="step-settings"></div>
+  <div class="branching-editor-step" data-role="step-nodes" hidden></div>
 
   <!-- Error messages get injected here -->
   <div class="errors" style="color:red;"></div>
 </div>
 
 <div class="xblock-actions">
-  <button type="button" class="action-primary save-button">Save</button>
-  <button type="button" class="action-secondary cancel-button">Cancel</button>
+  <button type="button" class="action-primary" data-role="continue">Continue</button>
+  <button type="button" class="action-primary" data-role="save" hidden>Save</button>
+  <button type="button" class="action-secondary" data-role="back" hidden>Back</button>
+  <button type="button" class="action-secondary" data-role="cancel">Cancel</button>
 </div>
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index a2a874c..7c0f9b7 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -1,16 +1,19 @@
 function BranchingStudioEditor(runtime, element, data) {
   const Templates = {};
-  ['settings-panel','node-block','choice-row'].forEach(name => {
+  ['settings-step', 'nodes-step', 'node-list-item', 'node-editor', 'choice-row'].forEach(name => {
     const src = document.getElementById(name+'-tpl').innerHTML;
     Templates[name] = Handlebars.compile(src);
   });
   Handlebars.registerHelper('inc', value => parseInt(value,10) + 1);
   Handlebars.registerHelper('eq', (a,b) => a === b);
   const $root       = $(element);
-  const $editor     = $root.find('.branching-scenario-editor');
+  const $stepSettings = $root.find('[data-role="step-settings"]');
+  const $stepNodes = $root.find('[data-role="step-nodes"]');
   const $errors     = $root.find('.errors');
-  const $saveBtn    = $root.find('.save-button');
-  const $cancelBtn  = $root.find('.cancel-button');
+  const $continueBtn = $root.find('[data-role="continue"]');
+  const $saveBtn = $root.find('[data-role="save"]');
+  const $backBtn = $root.find('[data-role="back"]');
+  const $cancelBtn  = $root.find('[data-role="cancel"]');
 
   this.uniqueIdCount = 0;
 
@@ -19,6 +22,13 @@ function BranchingStudioEditor(runtime, element, data) {
     return `temp-${i}`;
   };
 
+  const wizard = {
+    currentStep: 'settings',
+    selectedNodeId: null,
+    draftSettings: {},
+    draftNodes: [],
+  };
+
   function loadState() {
       return $.ajax({
         type: 'POST',
@@ -29,231 +39,215 @@ function BranchingStudioEditor(runtime, element, data) {
       });
   }
 
-  function render(state) {
-    $editor.empty();
-    $errors.empty();
+  function normalizeNode(raw) {
+    return {
+      id: raw?.id || uniqueId(),
+      content: raw?.content || '',
+      media: {
+        type: raw?.media?.type || '',
+        url: raw?.media?.url || '',
+      },
+      choices: Array.isArray(raw?.choices) ? raw.choices.map(c => ({
+        text: c?.text || '',
+        target_node_id: c?.target_node_id || '',
+      })) : [],
+      hint: raw?.hint || '',
+      overlay_text: Boolean(raw?.overlay_text),
+      transcript_url: raw?.transcript_url || '',
+    };
+  }
 
-    const nodes = Object.values(state.nodes || {});
+  function normalizeInitialState(state) {
+    const nodes = Object.values(state?.nodes || {}).map(normalizeNode);
     if (!nodes.length) {
-      nodes.push({
-        id: uniqueId(),
-        content: '',
-        media: {type: '', url: ''},
-        choices: [],
-        hint: '',
-        overlay_text: false,
-        transcript_url: ''
-      });
+      nodes.push(normalizeNode({}));
     }
-
-    $editor.append(Templates['settings-panel'](state));
-
-    nodes.forEach((node, idx) => {
-
-      const options = nodes.map((n, j) => ({
-        id: n.id,
-        label: `Node ${j+1}`
-      })).filter(opt => opt.id !== node.id);
-
-      const html = Templates['node-block']({ node, idx });
-
-      const $nodeEl = $(html);
-      (node.choices||[]).forEach((choice,i) => {
-        const ch = Templates['choice-row']({ choice, i, options });
-        $nodeEl.find('.choices-container').append(ch);
-      });
-      $editor.append($nodeEl);
-    });
-
-    $editor.append(
-      '<button type="button" class="btn-add-node">Add Node</button>'
-    );
-
-    bindInteractions();
-    bindActions();
-    updateTranscriptVisibility();
+    wizard.draftNodes = nodes;
+    wizard.selectedNodeId = nodes[0].id;
+    wizard.draftSettings = {
+      display_name: state?.display_name || '',
+      enable_undo: Boolean(state?.enable_undo),
+      enable_scoring: Boolean(state?.enable_scoring),
+      enable_reset_activity: Boolean(state?.enable_reset_activity),
+      background_image_url: state?.background_image_url || '',
+      background_image_alt_text: state?.background_image_alt_text || '',
+      background_image_is_decorative: Boolean(state?.background_image_is_decorative),
+    };
   }
 
-  function updateChoiceUI() {
-    const options = {};
-      $editor.find('.node-block').map((j, nb) => {
-        options[$(nb).data('node-id')] = `Node ${j+1}`;
-      });
-
-    $editor.find('.choice-target').each((_, choice) => {
-      const currentNodeId = $(choice).closest('.node-block').data('node-id');
-      const availableIds = Object.keys(options).filter(opt => opt !== currentNodeId);
+  function showStep(step) {
+    wizard.currentStep = step;
+    const showSettings = step === 'settings';
+    $stepSettings.attr('hidden', !showSettings);
+    $stepNodes.attr('hidden', showSettings);
+    $continueBtn.attr('hidden', !showSettings);
+    $saveBtn.attr('hidden', showSettings);
+    $backBtn.attr('hidden', showSettings);
+  }
 
-      let seenIds = [];
+  function nodeIndexById(nodeId) {
+    return wizard.draftNodes.findIndex(n => n.id === nodeId);
+  }
 
-      const selected = choice.selectedIndex;
-      $(choice).find('option').each((index, option) => {
-        const $option = $(option);
-        const val = $option.val();
-        if (availableIds.includes(val)) {
-          // Update display text, as the node label may have changed
-          $option.text(options[val]);
-        } else {
-          // the node was deleted, so remove the option
-          $option.remove();
-          // if the selected option was removed, unselect (otherwise another will be selected, which is confusing)
-          if (selected == index) {
-            choice.selectedIndex = -1;
-          }
-        }
-        seenIds.push(val);
-      });
+  function currentNode() {
+    const idx = nodeIndexById(wizard.selectedNodeId);
+    return idx >= 0 ? wizard.draftNodes[idx] : null;
+  }
 
-      // add any new nodes
-      for (const nodeId of availableIds) {
-        if (!seenIds.includes(nodeId)) {
-          const $option = $('<option>');
-          $option.val(nodeId);
-          $option.text(options[nodeId]);
-          $(choice).append($option);
-        }
-      }
+  function nodeOptions(excludeNodeId) {
+    return wizard.draftNodes
+      .map((n, idx) => ({ id: n.id, label: `Node ${idx + 1}` }))
+      .filter(opt => opt.id !== excludeNodeId);
+  }
 
-    });
+  function renderSettings() {
+    $stepSettings.html(Templates['settings-step'](wizard.draftSettings));
   }
 
-  function updateTranscriptVisibility($scope) {
-    const $target = $scope ? $scope.find('.media-type') : $editor.find('.media-type');
-    $target.each(function() {
-      const type = $(this).val();
-      const $field = $(this).closest('label').find('.transcript-field');
-      if (type === 'audio' || type === 'video') {
-        $field.show();
-      } else {
-        $field.hide();
-      }
+  function renderNodeList() {
+    const $list = $stepNodes.find('[data-role="node-list"]').empty();
+    wizard.draftNodes.forEach((n, idx) => {
+      $list.append(Templates['node-list-item']({
+        id: n.id,
+        number: idx + 1,
+        is_selected: n.id === wizard.selectedNodeId,
+      }));
     });
+
+    const atLimit = wizard.draftNodes.length >= 30;
+    $stepNodes.find('[data-role="add-node"]').prop('disabled', atLimit);
   }
 
-  function toggleOverlayControl($node) {
-    const type = $node.find('.media-type').val();
-    const $control = $node.find('.overlay-text-control');
-    const $checkbox = $node.find('.overlay-text-checkbox');
-    if (type === 'image') {
-      $control.removeClass('is-hidden');
-    } else {
-      $control.addClass('is-hidden');
-      $checkbox.prop('checked', false);
+  function renderNodeEditor() {
+    const node = currentNode();
+    const idx = nodeIndexById(wizard.selectedNodeId);
+    if (!node || idx < 0) {
+      $stepNodes.find('[data-role="node-editor"]').empty();
+      return;
     }
-  }
 
-  function bindInteractions() {
-    $editor.find('.btn-delete-node').off('click').on('click', function() {
-      $(this).closest('.node-block').remove();
-      $editor.find('.node-block').each((i, el) => {
-          $(el).attr('data-node-idx', i)
-               .find('.node-title').text(`Node ${i+1}`);
-      });
-      updateChoiceUI();
+    const mediaType = node.media?.type || '';
+    const showMediaUrl = Boolean(mediaType);
+    const showTranscript = mediaType === 'audio' || mediaType === 'video';
+    const showOverlay = mediaType === 'image';
+    const noBranches = !Array.isArray(node.choices) || node.choices.length === 0;
+
+    const html = Templates['node-editor']({
+      ...node,
+      number: idx + 1,
+      show_media_url: showMediaUrl,
+      show_transcript: showTranscript,
+      show_overlay: showOverlay,
+      no_branches: noBranches,
     });
-
-    $editor.find('.media-type').off('change').on('change', function() {
-      updateTranscriptVisibility($(this).closest('.node-block'));
+    const $editor = $stepNodes.find('[data-role="node-editor"]').html(html);
+    const $choices = $editor.find('[data-role="choices-container"]').empty();
+    const options = nodeOptions(node.id);
+    (node.choices || []).forEach((choice, i) => {
+      $choices.append(Templates['choice-row']({ choice, i, options }));
     });
+  }
 
-    $editor.off('click', '.btn-add-choice').on('click', '.btn-add-choice', function() {
-      const $container = $(this).closest('.choices-container');
-      const currentNodeId = $(this).closest('.node-block').data('node-id');
-      const options = $editor.find('.node-block').map((j, nb) => ({
-        id:  $(nb).data('node-id'),
-        label: `Node ${j+1}`
-      })).get().filter(opt => opt.id !== currentNodeId);
-      const newIndex = $container.find('.choice-row').length;
-      const html = Templates['choice-row']({
-        choice: { text: '', target_node_id: '' },
-        i: newIndex,
-        options
-      });
-      $container.append(html);
-    });
+  function renderNodesStep() {
+    $stepNodes.html(Templates['nodes-step']({}));
+    renderNodeList();
+    renderNodeEditor();
+  }
 
-  $editor.off('click', '.btn-delete-choice').on('click', '.btn-delete-choice', function() {
-    $(this).closest('.choice-row').remove();
-  });
+  function renderAll() {
+    $errors.empty();
+    renderSettings();
+    renderNodesStep();
+    showStep(wizard.currentStep);
+  }
 
-    $editor.find('.btn-add-node').off('click').on('click', function() {
-      const idx = $editor.find('.node-block').length;
-      const nodeContext = {
-        node: {
-          id:      uniqueId(),
-          content: '',
-          media:   { type: '', url: '' },
-          choices: [],
-          hint:    '',
-          overlay_text: false,
-          transcript_url: ''
-        },
-        idx
-      };
-      const html = Templates['node-block'](nodeContext);
-      const $newNode = $(html);
-      $(this).before($newNode);
-      bindInteractions();
-      updateChoiceUI();
-      updateTranscriptVisibility($newNode);
-    });
+  function syncSettingsFromDom() {
+    const $s = $stepSettings;
+    wizard.draftSettings.display_name = $s.find('[name="display_name"]').val()?.trim() || '';
+    wizard.draftSettings.enable_undo = $s.find('[name="enable_undo"]').is(':checked');
+    wizard.draftSettings.enable_reset_activity = $s.find('[name="enable_reset_activity"]').is(':checked');
+    wizard.draftSettings.enable_scoring = $s.find('[name="enable_scoring"]').is(':checked');
+    wizard.draftSettings.background_image_url = $s.find('[name="background_image_url"]').val()?.trim() || '';
+    wizard.draftSettings.background_image_is_decorative = $s.find('[name="background_image_is_decorative"]').is(':checked');
+    wizard.draftSettings.background_image_alt_text = $s.find('[name="background_image_alt_text"]').val()?.trim() || '';
+  }
 
-    $editor.find('.media-type').off('change.overlay').on('change.overlay', function() {
-      const $node = $(this).closest('.node-block');
-      toggleOverlayControl($node);
-    });
+  function syncCurrentNodeFromDom() {
+    const node = currentNode();
+    if (!node) {
+      return;
+    }
+    const $e = $stepNodes.find('.bx-node-editor-inner');
+    node.content = $e.find('[data-role="node-content"]').val() || '';
+    node.hint = $e.find('[data-role="node-hint"]').val() || '';
+
+    const mediaType = $e.find('[data-role="media-type"]').val() || '';
+    const mediaUrl = $e.find('[data-role="media-url"]').val()?.trim() || '';
+    const transcriptUrl = $e.find('[data-role="transcript-url"]').val()?.trim() || '';
+    node.media.type = mediaType;
+    node.media.url = mediaType ? mediaUrl : '';
+    node.transcript_url = (mediaType === 'audio' || mediaType === 'video') ? transcriptUrl : '';
+    node.overlay_text = mediaType === 'image' ? $e.find('[data-role="overlay-text"]').is(':checked') : false;
+
+    const noBranches = $e.find('[data-role="no-branches"]').is(':checked');
+    if (noBranches) {
+      node.choices = [];
+      return;
+    }
 
-    $editor.find('.node-block').each(function() {
-      toggleOverlayControl($(this));
+    const choices = [];
+    $e.find('.choice-row').each(function() {
+      const $row = $(this);
+      const text = $row.find('.choice-text').val()?.trim() || '';
+      const target = $row.find('.choice-target').val()?.trim() || '';
+      if (text || target) {
+        choices.push({ text, target_node_id: target });
+      }
     });
+    node.choices = choices;
+  }
+
+  function showErrors(res) {
+    const errs = (res.field_errors || {}).nodes_json || [res.message];
+    $errors.empty();
+    errs.forEach(msg => $errors.append($('<div>').text(msg)));
   }
 
   function bindActions() {
+    $continueBtn.off('click').on('click', function() {
+      syncSettingsFromDom();
+      showStep('nodes');
+    });
 
-    const $settings = $editor.find('.settings');
+    $backBtn.off('click').on('click', function() {
+      syncCurrentNodeFromDom();
+      showStep('settings');
+    });
 
     $saveBtn.off('click').on('click', function() {
-	      const payload = {
-	          nodes: [],
-	          enable_undo:    $settings.find('[name="enable_undo"]').is(':checked'),
-	          enable_scoring: $settings.find('[name="enable_scoring"]').is(':checked'),
-	          enable_reset_activity: $settings.find('[name="enable_reset_activity"]').is(':checked'),
-	          max_score:      parseFloat($settings.find('[name="max_score"]').val()) || 0,
-	          display_name:   $settings.find('[name="display_name"]').val()?.trim() || ''
-	      };
-
-      $editor.find('.node-block').each(function() {
-        const $n = $(this);
-        const content = $n.find('.node-content').val()?.trim() || '';
-        const mediaUrl = $n.find('.media-url').val()?.trim() || '';
-        const mediaType = $n.find('.media-type').val();
-        const choices = [];
-        const nodeHint = $n.find('.node-hint').val()?.trim() || '';
-        const overlayEnabled = $n.find('.overlay-text-checkbox').is(':checked');
-        const transcriptUrl = $n.find('.transcript-url').val()?.trim() || '';
-
-        $n.find('.choice-row').each(function() {
-          const $c = $(this);
-          const text   = $c.find('.choice-text').val()?.trim() || '';
-          const target = $c.find('.choice-target').val()?.trim() || '';
-          if (text && target) {
-              choices.push({ text: text, target_node_id: target });
-          }
-        });
-        if (content || mediaUrl || choices.length || transcriptUrl) {
-          payload.nodes.push({
-              id:     $n.data('node-id'),
-              content,
-              media:  { type: mediaType, url: mediaUrl },
-              choices,
-              hint: nodeHint,
-              overlay_text: overlayEnabled,
-              transcript_url: transcriptUrl
-          });
-        }
-      });
-      runtime.notify('save', { state: 'start' });
+      syncSettingsFromDom();
+      syncCurrentNodeFromDom();
+
+      const payload = {
+        nodes: wizard.draftNodes.map(n => ({
+          id: n.id,
+          content: (n.content || '').trim(),
+          media: { type: n.media?.type || '', url: (n.media?.url || '').trim() },
+          choices: Array.isArray(n.choices) ? n.choices.filter(c => c?.text && c?.target_node_id) : [],
+          hint: (n.hint || '').trim(),
+          overlay_text: Boolean(n.overlay_text),
+          transcript_url: (n.transcript_url || '').trim(),
+        })),
+        enable_undo: Boolean(wizard.draftSettings.enable_undo),
+        enable_scoring: Boolean(wizard.draftSettings.enable_scoring),
+        enable_reset_activity: Boolean(wizard.draftSettings.enable_reset_activity),
+        display_name: wizard.draftSettings.display_name || '',
+        background_image_url: wizard.draftSettings.background_image_url || '',
+        background_image_alt_text: wizard.draftSettings.background_image_alt_text || '',
+        background_image_is_decorative: Boolean(wizard.draftSettings.background_image_is_decorative),
+      };
 
+      runtime.notify('save', { state: 'start' });
       $.ajax({
         type: 'POST',
         url: runtime.handlerUrl(element, 'studio_submit'),
@@ -261,15 +255,13 @@ function BranchingStudioEditor(runtime, element, data) {
         contentType: 'application/json; charset=utf-8'
       }).done(function(res) {
         if (res.result === 'success') {
-            runtime.notify('save',  { state: 'end' });
-            runtime.notify('cancel', {});
+          runtime.notify('save',  { state: 'end' });
+          runtime.notify('cancel', {});
         } else {
-            const errs = (res.field_errors || {}).nodes_json || [res.message];
-            $errors.empty();
-            errs.forEach(msg => $errors.append($('<div>').text(msg)));
+          showErrors(res);
         }
       }).fail(function() {
-          $errors.text('Error saving scenario');
+        $errors.text('Error saving scenario');
       });
     });
 
@@ -279,5 +271,116 @@ function BranchingStudioEditor(runtime, element, data) {
     });
   }
 
-  loadState().then(render);
+  function bindInteractions() {
+    $root.off('change.bx-settings input.bx-settings', '[data-role="step-settings"] input, [data-role="step-settings"] textarea');
+    $root.on('change.bx-settings input.bx-settings', '[data-role="step-settings"] input, [data-role="step-settings"] textarea', function() {
+      syncSettingsFromDom();
+      const decorative = wizard.draftSettings.background_image_is_decorative;
+      const $alt = $stepSettings.find('[name="background_image_alt_text"]');
+      $alt.prop('disabled', decorative);
+      if (decorative) {
+        $alt.val('');
+        wizard.draftSettings.background_image_alt_text = '';
+      }
+    });
+
+    $root.off('click.bx-nodes', '[data-role="add-node"]');
+    $root.on('click.bx-nodes', '[data-role="add-node"]', function() {
+      if (wizard.draftNodes.length >= 30) {
+        return;
+      }
+      syncCurrentNodeFromDom();
+      const node = normalizeNode({});
+      wizard.draftNodes.push(node);
+      wizard.selectedNodeId = node.id;
+      renderNodeList();
+      renderNodeEditor();
+    });
+
+    $root.off('click.bx-nodes', '[data-role="select-node"]');
+    $root.on('click.bx-nodes', '[data-role="select-node"]', function() {
+      const nodeId = $(this).data('node-id');
+      if (!nodeId || nodeId === wizard.selectedNodeId) {
+        return;
+      }
+      syncCurrentNodeFromDom();
+      wizard.selectedNodeId = nodeId;
+      renderNodeList();
+      renderNodeEditor();
+    });
+
+    $root.off('click.bx-nodes', '[data-role="delete-node"]');
+    $root.on('click.bx-nodes', '[data-role="delete-node"]', function() {
+      const nodeId = $(this).data('node-id');
+      if (!nodeId) {
+        return;
+      }
+      syncCurrentNodeFromDom();
+
+      wizard.draftNodes = wizard.draftNodes.filter(n => n.id !== nodeId);
+      wizard.draftNodes.forEach(n => {
+        n.choices = (n.choices || []).filter(c => c.target_node_id !== nodeId);
+      });
+
+      if (!wizard.draftNodes.length) {
+        const node = normalizeNode({});
+        wizard.draftNodes = [node];
+        wizard.selectedNodeId = node.id;
+      } else if (wizard.selectedNodeId === nodeId) {
+        wizard.selectedNodeId = wizard.draftNodes[0].id;
+      }
+
+      renderNodeList();
+      renderNodeEditor();
+    });
+
+    $root.off('change.bx-node', '[data-role="media-type"]');
+    $root.on('change.bx-node', '[data-role="media-type"]', function() {
+      syncCurrentNodeFromDom();
+      renderNodeEditor();
+    });
+
+    $root.off('change.bx-node', '[data-role="no-branches"]');
+    $root.on('change.bx-node', '[data-role="no-branches"]', function() {
+      syncCurrentNodeFromDom();
+      renderNodeEditor();
+    });
+
+    $root.off('click.bx-node', '[data-role="add-choice"]');
+    $root.on('click.bx-node', '[data-role="add-choice"]', function() {
+      const node = currentNode();
+      if (!node) {
+        return;
+      }
+      syncCurrentNodeFromDom();
+      node.choices = Array.isArray(node.choices) ? node.choices : [];
+      node.choices.push({ text: '', target_node_id: '' });
+      renderNodeEditor();
+    });
+
+    $root.off('click.bx-node', '.btn-delete-choice');
+    $root.on('click.bx-node', '.btn-delete-choice', function() {
+      const node = currentNode();
+      if (!node) {
+        return;
+      }
+      const idx = Number($(this).closest('.choice-row').data('choice-idx'));
+      syncCurrentNodeFromDom();
+      if (!Number.isNaN(idx)) {
+        node.choices.splice(idx, 1);
+      }
+      renderNodeEditor();
+    });
+  }
+
+  function init() {
+    bindActions();
+    bindInteractions();
+    loadState().then(function(state) {
+      normalizeInitialState(state || {});
+      renderAll();
+    });
+  }
+
+  init();
 }

From 8e9ab8fcc810ae85dbce06bdbc7503a36c00c265 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Fri, 30 Jan 2026 12:23:51 -0500
Subject: [PATCH 06/32] feat: composite images + styling

---
 branching_xblock/branching_xblock.py          | 25 +++++++-
 .../static/css/branching_xblock.css           | 55 +++++++++++++++++
 branching_xblock/static/css/studio_editor.css |  2 -
 .../static/handlebars/node-editor.handlebars  | 12 +++-
 .../static/js/src/branching_xblock.js         | 60 ++++++++++++++-----
 .../static/js/src/studio_editor.js            | 32 +++++++++-
 6 files changed, 165 insertions(+), 21 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 4cfabfc..b81942e 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -138,9 +138,22 @@ def get_node(self, node_id):
         node = self.scenario_data.get("nodes", {}).get(node_id)
         if node is None:
             return None
+        changed = False
         if "overlay_text" not in node:
-            # ensure older scenarios expose the flag downstream
             node = {**node, "overlay_text": False}
+            changed = True
+
+        if "left_image_url" not in node:
+            media = node.get("media") or {}
+            left_fallback = media.get("url", "") if (media.get("type") == "image") else ""
+            node = {**node, "left_image_url": left_fallback}
+            changed = True
+
+        if "right_image_url" not in node:
+            node = {**node, "right_image_url": ""}
+            changed = True
+
+        if changed:
             self.scenario_data.setdefault("nodes", {})[node_id] = node
         return node
 
@@ -284,6 +297,12 @@ def _get_state(self):
             node_id: {
                 **node,
                 "overlay_text": bool(node.get("overlay_text", False)),
+                "left_image_url": (
+                    node.get("left_image_url")
+                    if node.get("left_image_url") is not None
+                    else (node.get("media") or {}).get("url", "")
+                ),
+                "right_image_url": node.get("right_image_url", "") or "",
             }
             for node_id, node in nodes.items()
         }
@@ -424,6 +443,8 @@ def studio_submit(self, data, suffix=''):
                     'type': raw.get('media', {}).get('type', ''),
                     'url':  raw.get('media', {}).get('url', '')
                 },
+                'left_image_url': raw.get('left_image_url', ''),
+                'right_image_url': raw.get('right_image_url', ''),
                 'choices': raw.get('choices', []),
                 'hint':     raw.get('hint', ''),
                 'overlay_text': bool(raw.get('overlay_text', False)),
@@ -464,6 +485,8 @@ def studio_submit(self, data, suffix=''):
                 'choices':  cleaned,
                 'hint': node.get('hint', ''),
                 'overlay_text': bool(node.get('overlay_text', False)),
+                'left_image_url': (node.get('left_image_url', '') or '').strip(),
+                'right_image_url': (node.get('right_image_url', '') or '').strip(),
                 'transcript_url': node.get('transcript_url', ''),
             })
 
diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index e5554aa..448cc26 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -26,6 +26,61 @@
     align-self: center;
 }
 
+.branching-scenario .bx-image-composite {
+    position: relative;
+    width: 100%;
+    max-width: 100%;
+    border-radius: 0.5rem;
+    background-size: cover;
+    background-position: center;
+    background-repeat: no-repeat;
+    padding: 0.75rem;
+    box-sizing: border-box;
+}
+
+.branching-scenario .bx-image-composite--bg-only {
+    padding: 0;
+    aspect-ratio: 16 / 9;
+}
+
+.branching-scenario .bx-image-composite__fg {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.75rem;
+    align-items: center;
+}
+
+.branching-scenario .bx-image-composite__img {
+    width: 100%;
+    height: auto;
+    display: block;
+    object-fit: cover;
+    border-radius: 0.5rem;
+}
+
+.branching-scenario .bx-image-composite__overlay {
+    position: absolute;
+    left: 50%;
+    bottom: 1.25rem;
+    transform: translateX(-50%);
+    width: calc(100% - 3rem);
+    max-width: 90%;
+}
+
+@media (max-width: 768px) {
+    .branching-scenario .bx-image-composite__fg {
+        grid-template-columns: 1fr;
+    }
+
+    .branching-scenario .bx-image-composite__overlay {
+        position: static;
+        transform: none;
+        width: 100%;
+        max-width: 100%;
+        margin-top: 0.75rem;
+    }
+}
+
 .branching-scenario .media-overlay {
     position: relative;
     width: 100%;
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index 5c60da0..9f4a7fd 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -48,7 +48,6 @@
 }
 
 .bx-step-title {
-    font-size: 1.25rem;
     font-weight: 600;
     margin: 0 0 1rem;
 }
@@ -71,7 +70,6 @@
 }
 
 .bx-field__label {
-    font-weight: 600;
     margin-bottom: 0.35rem;
 }
 
diff --git a/branching_xblock/static/handlebars/node-editor.handlebars b/branching_xblock/static/handlebars/node-editor.handlebars
index 5927cfb..387bc70 100644
--- a/branching_xblock/static/handlebars/node-editor.handlebars
+++ b/branching_xblock/static/handlebars/node-editor.handlebars
@@ -16,6 +16,17 @@
     </select>
   </label>
 
+  <div class="{{#unless is_image}}is-hidden{{/unless}}" data-role="image-url-fields">
+    <label class="bx-field">
+      <div class="bx-field__label">Left image URL</div>
+      <input type="text" class="bx-input" data-role="left-image-url" placeholder="URL" value="{{left_image_url}}" />
+    </label>
+    <label class="bx-field">
+      <div class="bx-field__label">Right image URL</div>
+      <input type="text" class="bx-input" data-role="right-image-url" placeholder="URL" value="{{right_image_url}}" />
+    </label>
+  </div>
+
   <label class="bx-field {{#unless show_media_url}}is-hidden{{/unless}}" data-role="media-url-field">
     <div class="bx-field__label">URL</div>
     <input type="text" class="bx-input" data-role="media-url" placeholder="URL" value="{{media.url}}" />
@@ -52,4 +63,3 @@
     <div class="choices-container" data-role="choices-container"></div>
   </div>
 </div>
-
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index 410efc5..86fecc3 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -78,7 +78,7 @@ function BranchingXBlock(runtime, element) {
         const $summary = $details.find('[data-role="hint-summary"]');
         $details.prop('open', isHintVisible);
         if ($summary.length) {
-            $summary.text(isHintVisible ? 'Hide hint' : 'Show hint');
+            $summary.text(isHintVisible ? 'Hide' : 'Show hint');
         }
     }
 
@@ -92,6 +92,11 @@ function BranchingXBlock(runtime, element) {
         const mediaUrl = media.url || '';
         const contentHtml = (node && node.content) || '';
         const overlayEnabled = Boolean(node?.overlay_text && media.type === 'image');
+        const backgroundImageUrl = state?.background_image_url || '';
+        const leftImageUrl = (node?.left_image_url !== undefined && node?.left_image_url !== null)
+            ? node.left_image_url
+            : (mediaUrl || '');
+        const rightImageUrl = node?.right_image_url || '';
 
         const $media = $el.find('[data-role="media"]');
         const $transcript = $el.find('[data-role="transcript"]');
@@ -102,18 +107,45 @@ function BranchingXBlock(runtime, element) {
                 $transcript.prop('hidden', true).empty();
             }
         };
-        if (media.type === 'image' && overlayEnabled) {
-            $media.html(`
-                <div class="media-overlay">
-                    <img src="${media.url}" alt=""/>
-                    <div class="media-overlay__text">
-                        ${contentHtml}
-                    </div>
-                </div>
-            `);
-            setTranscript(null);
-        } else if (media.type === 'image') {
-            $media.html(`<img src="${mediaUrl}" alt=""/>`);
+        if (media.type === 'image') {
+            const $composite = $('<div>').addClass('bx-image-composite');
+            if (backgroundImageUrl) {
+                $composite.css('background-image', `url("${backgroundImageUrl}")`);
+            }
+
+            const hasForeground = Boolean(leftImageUrl || rightImageUrl);
+            if (!hasForeground && backgroundImageUrl) {
+                $composite.addClass('bx-image-composite--bg-only');
+            } else if (hasForeground) {
+                const $fg = $('<div>').addClass('bx-image-composite__fg');
+                if (leftImageUrl) {
+                    $fg.append(
+                        $('<img>')
+                            .addClass('bx-image-composite__img bx-image-composite__img--left')
+                            .attr('src', leftImageUrl)
+                            .attr('alt', '')
+                    );
+                }
+                if (rightImageUrl) {
+                    $fg.append(
+                        $('<img>')
+                            .addClass('bx-image-composite__img bx-image-composite__img--right')
+                            .attr('src', rightImageUrl)
+                            .attr('alt', '')
+                    );
+                }
+                $composite.append($fg);
+            }
+
+            if (overlayEnabled) {
+                $composite.append(
+                    $('<div>')
+                        .addClass('media-overlay__text bx-image-composite__overlay')
+                        .html(contentHtml)
+                );
+            }
+
+            $media.empty().append($composite);
             setTranscript(null);
         } else if (media.type === 'audio') {
             $media.html(`<audio src="${mediaUrl}" controls />`);
@@ -136,7 +168,7 @@ function BranchingXBlock(runtime, element) {
         }
         // Content
         const $content = $el.find('[data-role="content"]');
-        if (overlayEnabled) {
+        if (overlayEnabled && media.type === 'image') {
             $content.empty();
         } else {
             $content.html(contentHtml);
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index 7c0f9b7..c4b80b5 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -54,6 +54,8 @@ function BranchingStudioEditor(runtime, element, data) {
       hint: raw?.hint || '',
       overlay_text: Boolean(raw?.overlay_text),
       transcript_url: raw?.transcript_url || '',
+      left_image_url: raw?.left_image_url ?? null,
+      right_image_url: raw?.right_image_url ?? null,
     };
   }
 
@@ -127,18 +129,29 @@ function BranchingStudioEditor(runtime, element, data) {
     }
 
     const mediaType = node.media?.type || '';
-    const showMediaUrl = Boolean(mediaType);
+    const isImage = mediaType === 'image';
+    const showMediaUrl = Boolean(mediaType) && !isImage;
     const showTranscript = mediaType === 'audio' || mediaType === 'video';
     const showOverlay = mediaType === 'image';
     const noBranches = !Array.isArray(node.choices) || node.choices.length === 0;
 
+    const leftImageUrl = isImage
+      ? (node.left_image_url ?? node.media?.url ?? '')
+      : '';
+    const rightImageUrl = isImage
+      ? (node.right_image_url ?? '')
+      : '';
+
     const html = Templates['node-editor']({
       ...node,
       number: idx + 1,
+      is_image: isImage,
       show_media_url: showMediaUrl,
       show_transcript: showTranscript,
       show_overlay: showOverlay,
       no_branches: noBranches,
+      left_image_url: leftImageUrl,
+      right_image_url: rightImageUrl,
     });
     const $editor = $stepNodes.find('[data-role="node-editor"]').html(html);
     const $choices = $editor.find('[data-role="choices-container"]').empty();
@@ -185,10 +198,18 @@ function BranchingStudioEditor(runtime, element, data) {
     const mediaUrl = $e.find('[data-role="media-url"]').val()?.trim() || '';
     const transcriptUrl = $e.find('[data-role="transcript-url"]').val()?.trim() || '';
     node.media.type = mediaType;
-    node.media.url = mediaType ? mediaUrl : '';
+    node.media.url = (mediaType && mediaType !== 'image') ? mediaUrl : '';
     node.transcript_url = (mediaType === 'audio' || mediaType === 'video') ? transcriptUrl : '';
     node.overlay_text = mediaType === 'image' ? $e.find('[data-role="overlay-text"]').is(':checked') : false;
 
+    if (mediaType === 'image') {
+      node.left_image_url = $e.find('[data-role="left-image-url"]').val()?.trim() || '';
+      node.right_image_url = $e.find('[data-role="right-image-url"]').val()?.trim() || '';
+    } else {
+      node.left_image_url = '';
+      node.right_image_url = '';
+    }
+
     const noBranches = $e.find('[data-role="no-branches"]').is(':checked');
     if (noBranches) {
       node.choices = [];
@@ -232,10 +253,15 @@ function BranchingStudioEditor(runtime, element, data) {
         nodes: wizard.draftNodes.map(n => ({
           id: n.id,
           content: (n.content || '').trim(),
-          media: { type: n.media?.type || '', url: (n.media?.url || '').trim() },
+          media: {
+            type: n.media?.type || '',
+            url: (n.media?.type === 'image') ? '' : (n.media?.url || '').trim(),
+          },
           choices: Array.isArray(n.choices) ? n.choices.filter(c => c?.text && c?.target_node_id) : [],
           hint: (n.hint || '').trim(),
           overlay_text: Boolean(n.overlay_text),
+          left_image_url: (n.left_image_url || '').trim(),
+          right_image_url: (n.right_image_url || '').trim(),
           transcript_url: (n.transcript_url || '').trim(),
         })),
         enable_undo: Boolean(wizard.draftSettings.enable_undo),

From d074d83dc8325f792e0473847e3986a97c7c0216 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 5 Feb 2026 14:18:36 -0500
Subject: [PATCH 07/32] fix: styling changes

---
 branching_xblock/static/css/studio_editor.css | 492 +++++++-----------
 1 file changed, 193 insertions(+), 299 deletions(-)

diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index 9f4a7fd..233371e 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -1,12 +1,3 @@
-.wrapper-comp-settings {
-    max-height: calc(100vh - 160px);
-    overflow-y: auto;
-    background: #fff;
-    border: 1px solid #ddd;
-    border-radius: 4px;
-    padding: 1em;
-}
-
 .branching-editor-step[hidden] {
     display: none !important;
 }
@@ -15,164 +6,173 @@
     display: none !important;
 }
 
-.xblock-actions {
-    display: flex;
-    justify-content: flex-start;
-    align-items: center;
-    gap: 1em;
-    padding: 0.75em 1em;
-    border-top: 1px solid #e0e0e0;
-    background: #fff;
-    position: sticky;
-    bottom: 0;
-    z-index: 1;
-    box-shadow: 0 -2px 6px rgba(0, 0, 0, 0.05);
+.is-hidden {
+    display: none !important;
 }
 
-.xblock-actions [data-role="back"],
-.xblock-actions [data-role="cancel"] {
-    background: none;
-    border: none;
-    padding: 0;
-    color: #0f62a1;
-    text-decoration: none;
+.bx-wizard {
+    width: 100%;
+    max-width: none;
+    padding: 5rem;
 }
 
-.xblock-actions [data-role="back"]:hover,
-.xblock-actions [data-role="cancel"]:hover {
-    text-decoration: underline;
+.bx-step-title {
+    margin: 0 0 12px;
+    font-size: 20px;
+    font-weight: 600;
+    line-height: 1.2;
+    color: #1f2933;
 }
 
-.bx-wizard {
-    max-width: 980px;
+.bx-settings-step .bx-step-title {
+    margin-bottom: 12px;
+    font-size: 19px;
 }
 
-.bx-step-title {
+.bx-settings-step .bx-section-title {
+    margin: 12px 0;
+    font-size: 19px;
     font-weight: 600;
-    margin: 0 0 1rem;
+    line-height: 1.2;
+    color: #1f2933;
+    padding-top: 15px;
 }
 
 .bx-section-title {
-    font-size: 1rem;
-    font-weight: 600;
-    margin: 1.5rem 0 0.5rem;
+    margin: 18px 0 10px;
+    font-size: 14px;
+    font-weight: 500;
+    line-height: 1.3;
+    color: #1f2933;
 }
 
 .bx-help {
-    margin: 0 0 1rem;
-    font-size: 0.9em;
-    color: #555;
+    margin: 0 0 12px;
+    font-size: 14px;
+    line-height: 1.4;
+    color: #5b6570;
 }
 
 .bx-field {
     display: block;
-    margin-bottom: 1rem;
+    margin-bottom: 12px;
 }
 
 .bx-field__label {
-    margin-bottom: 0.35rem;
+    margin-bottom: 4px;
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 1.3;
+    color: #303842;
 }
 
-.bx-input,
-.bx-select,
-.bx-textarea {
+.branching-editor-step .bx-input,
+.branching-editor-step .bx-select,
+.branching-editor-step .bx-textarea {
     width: 100%;
+    max-width: 700px;
+    min-height: 40px;
+    border: 1px solid #c8cdd3;
+    border-radius: 0;
+    background: #fff;
     box-sizing: border-box;
+    padding: 8px 10px;
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 1.3;
+    color: #1f2933;
 }
 
-.bx-textarea {
-    min-height: 8em;
+.branching-editor-step .bx-textarea {
+    max-width: 700px;
+    min-height: 112px;
     resize: vertical;
 }
 
 .bx-checkbox {
     display: flex;
     align-items: center;
-    gap: 0.5rem;
-    margin: 0.5rem 0;
+    gap: 8px;
+    margin: 10px 0;
+}
+
+.bx-checkbox input[type="checkbox"] {
+    width: 18px;
+    height: 18px;
+    margin: 0;
+}
+
+.branching-editor-step .bx-checkbox span {
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 1.3;
+    color: #303842;
 }
 
 .bx-checkbox--nested {
-    margin: 0.25rem 0 0.5rem;
+    margin: 2px 0 8px;
 }
 
 .bx-nodes-step {
     display: flex;
-    gap: 1rem;
+    gap: 14px;
     min-height: 520px;
 }
 
 .bx-nodes-sidebar {
-    width: 220px;
+    width: 240px;
     flex: none;
-    border-right: 1px solid #e0e0e0;
-    padding-right: 1rem;
-}
-
-.bx-btn {
-    border: 1px solid #0f62a1;
-    border-radius: 4px;
-    padding: 0.5rem 0.75rem;
-    cursor: pointer;
-}
-
-.bx-btn--primary {
-    background: #0f62a1;
-    color: #fff;
-}
-
-.bx-btn--primary:disabled {
-    opacity: 0.5;
-    cursor: not-allowed;
-}
-
-.bx-btn--secondary {
-    background: #28a745;
-    border-color: #28a745;
-    color: #fff;
-    margin: 0.5rem 0;
+    border-right: 1px solid #e5e7eb;
+    padding-right: 14px;
 }
 
 .bx-node-limit {
-    margin: 0.5rem 0 1rem;
-    font-size: 0.85em;
-    color: #666;
+    margin: 8px 0 12px;
+    font-size: 13px;
+    color: #6b7280;
 }
 
 .bx-node-list {
     display: flex;
     flex-direction: column;
-    gap: 0.25rem;
+    gap: 8px;
 }
 
 .bx-node-list-item {
     display: flex;
     align-items: center;
     justify-content: space-between;
+    min-height: 40px;
+    padding: 0 10px;
     border: 1px solid transparent;
-    border-radius: 4px;
-    padding: 0.4rem 0.5rem;
+    border-radius: 0;
 }
 
 .bx-node-list-item.is-selected {
     background: #f3f4f6;
-    border-color: #e5e7eb;
+    border-color: #f3f4f6;
 }
 
 .bx-node-list-item__select {
-    background: none;
-    border: none;
+    flex: 1;
+    border: 0;
+    background: transparent;
     padding: 0;
     text-align: left;
     cursor: pointer;
-    flex: 1;
+    font-size: 13px;
+    line-height: 1.3;
+    color: #1f2933;
 }
 
 .bx-node-list-item__delete {
-    background: none;
-    border: none;
+    border: 0;
+    background: transparent;
     cursor: pointer;
-    opacity: 0.7;
+    font-size: 14px;
+    line-height: 1;
+    color: #6b7280;
+    opacity: 0.9;
 }
 
 .bx-node-list-item__delete:hover {
@@ -181,258 +181,152 @@
 
 .bx-nodes-main {
     flex: 1;
-    padding-left: 0.5rem;
+    padding-left: 0;
 }
 
 .bx-node-editor-inner .bx-help {
-    margin-top: 0.35rem;
+    margin-top: 4px;
 }
 
 .bx-choices .choices-container {
-    margin-top: 0.75rem;
-}
-
-.is-hidden {
-    display: none !important;
-}
-
-.xblock-actions .action-item {
-    margin: 0 0.25em;
-}
-
-.settings {
-    display: flex;
-    flex-direction: column;
-    gap: 0.75em;
-    margin-bottom: 1.5em;
-}
-
-.settings label {
-    font-size: 1em;
-    font-weight: bold;
-}
-
-.settings .display-name-row {
-    display: flex;
-    align-items: center;
-    gap: 0.75em;
-    font-size: 1em;
-    font-weight: 600;
+    margin-top: 10px;
 }
 
-.settings .display-name-row input[name="display_name"] {
-    min-width: 220px;
-}
-
-.bx-authoring-help {
-    border: 1px solid #d0d0d0;
-    border-radius: 4px;
-    background: #f8f9fa;
-    padding: 1em;
-    align-self: flex-start;
-    width: 100%;
-    max-width: 800px;
-    box-sizing: content-box;
-}
-
-.bx-authoring-help summary {
+.choice-row {
     display: flex;
     align-items: center;
-    gap: 0.5em;
-    font-weight: 600;
-    cursor: pointer;
-    user-select: none;
-    padding: 0.25em 0;
-    color: #1d4ed8;
-}
-
-.bx-authoring-help summary::-webkit-details-marker {
-    display: none;
-}
-
-.bx-authoring-help summary::after {
-    content: "▾";
-    margin-left: auto;
-    transform: rotate(0deg);
-    transition: transform 150ms ease-in-out;
+    gap: 8px;
+    margin: 8px 0;
 }
 
-.bx-authoring-help[open] summary::after {
-    transform: rotate(180deg);
-}
-
-.bx-authoring-help summary:hover {
-    color: #1d4ed8;
-}
-
-.bx-authoring-help summary:focus-visible {
-    outline: 2px solid #1d4ed8;
-    outline-offset: 2px;
+.choice-row input.choice-text {
+    flex: 0 1 320px;
+    width: 320px;
+    max-width: 320px;
+    min-height: 40px;
+    border: 1px solid #c8cdd3;
+    border-radius: 0;
+    padding: 8px 10px;
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 1.3;
 }
 
-.bx-authoring-help-body {
-    margin-top: 0.5em;
-    font-style: normal;
+.choice-row select.choice-target {
+    flex: none;
+    width: 170px;
+    min-height: 40px;
+    border: 1px solid #c8cdd3;
+    border-radius: 0;
+    padding: 8px 10px;
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 1.3;
 }
 
-.node-block {
-    max-width: 800px;
-    background: #f9f9f9;
-    border: 1px solid #ccc;
+.choice-row .btn-delete-choice {
+    min-width: 34px;
+    min-height: 34px;
+    border: 0;
     border-radius: 4px;
-    padding: 1em;
-    margin-bottom: 1em;
-}
-
-.node-block label {
-    display: block;
-    margin-bottom: 1em;
-}
-
-.node-header .btn-delete-node {
-    background-color: #dc3545;
+    background: #dc3545;
     color: #fff;
-    border: none;
-    border-radius: 4px;
-    padding: 0.4em 0.8em;
-    font-size: 0.9em;
+    font-size: 14px;
+    line-height: 1;
     cursor: pointer;
 }
 
-.node-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-}
-
-.node-block .node-content {
-    width: 100%;
-    min-height: 8em;
-    padding: 0.5em;
-    box-sizing: border-box;
-    resize: vertical;
-}
-
-.node-block .media-type {
-    display: inline-block;
-    width: auto;
-    max-width: 200px;
-    margin-top: 0.25em;
-}
-
-.node-block .media-url {
-    display: block;
-    margin-top: 0.5em;
-    width: 100%;
-    box-sizing: border-box;
-}
-
-.node-block .transcript-field {
-    margin-top: 0.5em;
-}
-
-.node-block .transcript-label {
-    display: flex;
-    flex-direction: column;
-    gap: 0.35em;
-}
-
-.node-block .transcript-url {
-    width: 100%;
-    box-sizing: border-box;
-}
-
-.choices-container {
-    margin-top: 1em;
+.choice-row .btn-delete-choice:hover {
+    opacity: 0.9;
 }
 
-.choices-container::before {
-    content: "Choices";
-    display: block;
-    font-weight: bold;
-    margin-bottom: 0.5em;
+.overlay-text-control {
+    margin-bottom: 8px;
 }
 
-.choice-row {
+.overlay-text-toggle {
     display: flex;
     align-items: center;
-    gap: 0.5em;
-    margin-bottom: 0.75em;
-    margin-top: 0.75em;
+    gap: 6px;
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 1.3;
+    color: #303842;
 }
 
-.choice-row input.choice-text {
-    flex: 1;
-}
-
-.choice-row select.choice-target {
-    flex: none;
-    width: 200px;
+.overlay-text-help {
+    margin: 4px 0 0;
+    font-size: 12px;
+    line-height: 1.3;
+    color: #6b7280;
 }
 
-.choice-row .btn-delete-choice {
-    background-color: #dc3545;
-    color: #fff;
-    border: none;
-    border-radius: 4px;
-    padding: 0.3em 0.6em;
-    font-size: 0.9em;
+.bx-btn {
+    border: 1px solid #006fb9;
+    border-radius: 6px;
+    padding: 6px 10px;
+    font-size: 14px;
+    font-weight: 500;
+    line-height: 1.2;
     cursor: pointer;
-    flex: none;
-    line-height: 1;
 }
 
-.choice-row .btn-delete-choice:hover {
-    opacity: 0.85;
-}
-
-.btn-add-choice,
-.btn-add-node {
-    display: inline-block;
-    background-color: #007bff;
+.bx-btn--primary {
+    background: #006fb9;
+    border-color: #006fb9;
     color: #fff;
-    border: none;
-    border-radius: 4px;
-    padding: 0.6em 1.2em;
-    font-size: 1em;
-    cursor: pointer;
-    margin-top: 0.75em;
-    margin-bottom: 0.75em;
 }
 
-.btn-add-choice {
-    background-color: #28a745;
-}
-
-.btn-add-choice:hover,
-.btn-add-node:hover,
-.choice-row .btn-delete-choice:hover {
-    opacity: 0.85;
+.bx-btn--primary:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
 }
 
-.editor-note {
-    font-size: 0.75em;
-    color: #555;
-    margin-top: 0.25em;
-    font-style: italic;
+.bx-btn--secondary {
+    background: #37a94a;
+    border-color: #37a94a;
+    color: #fff;
+    margin: 8px 0 6px;
 }
 
-.overlay-text-control {
-    margin-bottom: 1em;
+.xblock-actions {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    gap: 14px;
+    padding: 10px 14px;
+    background: #fff;
+    position: sticky;
+    bottom: 0;
+    z-index: 20;
+    border-top: 1px solid #e5e7eb;
+    box-shadow: 0 -2px 8px rgba(0, 0, 0, 0.06);
 }
 
-.overlay-text-control.is-hidden {
-    display: none;
+.xblock-actions .action-primary {
+    min-height: 36px;
+    border: 1px solid #006fb9;
+    border-radius: 6px;
+    background: #006fb9;
+    color: #fff;
+    padding: 6px 12px;
+    font-size: 14px;
+    font-weight: 500;
+    line-height: 1.2;
 }
 
-.overlay-text-toggle {
-    display: flex;
-    align-items: center;
-    gap: 0.5em;
+.xblock-actions .action-secondary {
+    min-height: 36px;
+    border: 0;
+    background: transparent;
+    color: #0a6fb5;
+    padding: 0;
+    text-decoration: none;
+    font-size: 14px;
+    font-weight: 500;
+    line-height: 1.2;
 }
 
-.overlay-text-help {
-    margin: 0.5em 0 0;
-    font-size: 0.85em;
-    color: #555;
+.xblock-actions .action-secondary:hover {
+    text-decoration: underline;
 }

From 5e0a83fc46a3ee163a6ff7a72bc2c7b76238b024 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Fri, 6 Feb 2026 15:21:06 -0500
Subject: [PATCH 08/32] feat: Add scores to each choice

---
 branching_xblock/branching_xblock.py          | 107 +++++++++++++++---
 branching_xblock/static/css/studio_editor.css |  12 ++
 .../static/handlebars/choice-row.handlebars   |  10 ++
 .../static/js/src/studio_editor.js            |  30 +++--
 4 files changed, 134 insertions(+), 25 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index b81942e..61e889b 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -116,6 +116,12 @@ class BranchingXBlock(XBlock):
         help="Accumulated score (if scoring enabled)"
     )
 
+    score_history = List(
+        scope=Scope.user_state,
+        default=[],
+        help="Awarded points per selected choice, used for undo/reset"
+    )
+
     has_completed = Boolean(
         scope=Scope.user_state,
         default=False,
@@ -138,25 +144,53 @@ def get_node(self, node_id):
         node = self.scenario_data.get("nodes", {}).get(node_id)
         if node is None:
             return None
-        changed = False
         if "overlay_text" not in node:
             node = {**node, "overlay_text": False}
-            changed = True
 
         if "left_image_url" not in node:
             media = node.get("media") or {}
             left_fallback = media.get("url", "") if (media.get("type") == "image") else ""
             node = {**node, "left_image_url": left_fallback}
-            changed = True
 
         if "right_image_url" not in node:
             node = {**node, "right_image_url": ""}
-            changed = True
 
-        if changed:
-            self.scenario_data.setdefault("nodes", {})[node_id] = node
+        node_choices = node.get("choices", []) or []
+        normalized_choices = []
+        for choice in node_choices:
+            score = self._coerce_choice_score(choice.get("score", 0))
+            if score is None:
+                score = 0
+            normalized_choices.append({**choice, "score": score})
+        if normalized_choices != node_choices:
+            node = {**node, "choices": normalized_choices}
         return node
 
+    @staticmethod
+    def _coerce_choice_score(raw_score):
+        """
+        Parse and validate choice score.
+        """
+        if isinstance(raw_score, bool):
+            return None
+        if isinstance(raw_score, int):
+            score = raw_score
+        elif isinstance(raw_score, float):
+            if not raw_score.is_integer():
+                return None
+            score = int(raw_score)
+        elif isinstance(raw_score, str):
+            stripped = raw_score.strip()
+            if not stripped or not stripped.lstrip('-').isdigit():
+                return None
+            score = int(stripped)
+        else:
+            try:
+                score = int(raw_score)
+            except (TypeError, ValueError):
+                return None
+        return score if 0 <= score <= 100 else None
+
     def get_current_node(self) -> Optional[dict[str, Any]]:
         """
         Get the learner's current node.
@@ -293,8 +327,17 @@ def studio_view(self, context=None):
 
     def _get_state(self):
         nodes = self.scenario_data.get("nodes", {})
-        nodes_with_defaults = {
-            node_id: {
+        nodes_with_defaults = {}
+        for node_id, node in nodes.items():
+            normalized_choices = []
+            for choice in (node.get("choices", []) or []):
+                score = self._coerce_choice_score(choice.get("score", 0))
+                normalized_choices.append({
+                    **choice,
+                    "score": score if score is not None else 0,
+                })
+
+            nodes_with_defaults[node_id] = {
                 **node,
                 "overlay_text": bool(node.get("overlay_text", False)),
                 "left_image_url": (
@@ -303,9 +346,8 @@ def _get_state(self):
                     else (node.get("media") or {}).get("url", "")
                 ),
                 "right_image_url": node.get("right_image_url", "") or "",
+                "choices": normalized_choices,
             }
-            for node_id, node in nodes.items()
-        }
 
         return {
             "nodes":           nodes_with_defaults,
@@ -320,6 +362,7 @@ def _get_state(self):
             "display_name":    self.display_name,
             "current_node":    self.get_current_node(),
             "history":         list(self.history),
+            "score_history":   list(self.score_history),
             "has_completed":   bool(self.has_completed),
             "score":           self.score,
         }
@@ -349,13 +392,21 @@ def select_choice(self, data, suffix=''):
         target_node = self.get_node(target_node_id)
         if not target_node:
             return {"success": False, "error": f"Target node {target_node_id} not found"}
+
+        awarded_points = 0
+        if self.enable_scoring:
+            awarded_points = self._coerce_choice_score(choice.get("score", 0))
+            if awarded_points is None:
+                awarded_points = 0
+            self.score += awarded_points
+            self.score_history.append(float(awarded_points))
+
         if self.enable_undo:
             self.history.append(self.current_node_id)
         self.current_node_id = target_node_id
         if self.is_end_node(target_node_id):
             self.has_completed = True
             if self.enable_scoring:
-                self.score = self.max_score
                 self.publish_grade()
             self.runtime.publish(self, "completion", {"completion": 1.0})
 
@@ -372,8 +423,9 @@ def undo_choice(self, data, suffix=''):
         prev_node_id = self.history.pop()
         self.current_node_id = prev_node_id
 
-        if self.has_completed and self.enable_scoring:
-            self.score = 0.0
+        if self.enable_scoring:
+            awarded_points = self.score_history.pop() if self.score_history else 0.0
+            self.score = max(0.0, self.score - awarded_points)
             self.publish_grade()
 
         self.has_completed = False
@@ -392,6 +444,7 @@ def reset_activity(self, data, suffix=''):
         self.has_completed = False
 
         if self.enable_scoring:
+            self.score_history = []
             self.score = 0.0
             self.publish_grade()
 
@@ -427,6 +480,7 @@ def studio_submit(self, data, suffix=''):
         # 1) Assign real IDs and build id_map
         id_map = {}
         staged = []
+        score_errors = []
         for raw in raw_nodes:
             old_id = raw.get('id', '')
             # new ID if temp or missing
@@ -469,13 +523,23 @@ def studio_submit(self, data, suffix=''):
             for raw in node['choices']:
                 text = raw.get('text', '').strip()
                 targ = raw.get('target_node_id', '').strip()
+                has_choice_values = bool(text or targ)
+                if not has_choice_values:
+                    continue
+
+                score = self._coerce_choice_score(raw.get('score', 0))
+                if score is None:
+                    score_errors.append(
+                        f"Choice score must be an integer between 0 and 100 in node {node['id']}."
+                    )
+                    continue
                 # map through id_map if it was a temp ID
                 real_target = id_map.get(targ, targ)
-                if text or real_target:
-                    cleaned.append({
-                        'text': text,
-                        'target_node_id': real_target
-                    })
+                cleaned.append({
+                    'text': text,
+                    'target_node_id': real_target,
+                    'score': score,
+                })
 
             final.append({
                 'id':       node['id'],
@@ -490,6 +554,13 @@ def studio_submit(self, data, suffix=''):
                 'transcript_url': node.get('transcript_url', ''),
             })
 
+        if score_errors:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {"nodes_json": score_errors}
+            }
+
         # 3) Persist scenario_data & settings
         nodes_dict = {node['id']: node for node in final}
         self.scenario_data = {
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index 233371e..ad2cc9b 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -212,6 +212,18 @@
     line-height: 1.3;
 }
 
+.choice-row input.choice-score {
+    flex: none;
+    width: 88px;
+    min-height: 40px;
+    border: 1px solid #c8cdd3;
+    border-radius: 0;
+    padding: 8px 10px;
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 1.3;
+}
+
 .choice-row select.choice-target {
     flex: none;
     width: 170px;
diff --git a/branching_xblock/static/handlebars/choice-row.handlebars b/branching_xblock/static/handlebars/choice-row.handlebars
index 81ed2cf..9dea5bc 100644
--- a/branching_xblock/static/handlebars/choice-row.handlebars
+++ b/branching_xblock/static/handlebars/choice-row.handlebars
@@ -1,5 +1,15 @@
 <div class="choice-row" data-choice-idx="{{i}}">
   <input class="choice-text" value="{{choice.text}}" placeholder="Choice text"/>
+  <input
+    class="choice-score"
+    type="number"
+    min="0"
+    max="100"
+    step="1"
+    value="{{choice.score}}"
+    placeholder="Score"
+    aria-label="Choice score"
+  />
   <select class="choice-target">
     {{#each options}}
       <option value="{{this.id}}" {{#if (eq this.id ../choice.target_node_id)}}selected{{/if}}>{{this.label}}</option>
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index c4b80b5..8bca2a8 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -40,6 +40,15 @@ function BranchingStudioEditor(runtime, element, data) {
   }
 
   function normalizeNode(raw) {
+    const normalizeChoice = (choice) => {
+      const parsedScore = Number.parseInt(choice?.score, 10);
+      return {
+        text: choice?.text || '',
+        target_node_id: choice?.target_node_id || '',
+        score: Number.isNaN(parsedScore) ? 0 : parsedScore,
+      };
+    };
+
     return {
       id: raw?.id || uniqueId(),
       content: raw?.content || '',
@@ -47,10 +56,7 @@ function BranchingStudioEditor(runtime, element, data) {
         type: raw?.media?.type || '',
         url: raw?.media?.url || '',
       },
-      choices: Array.isArray(raw?.choices) ? raw.choices.map(c => ({
-        text: c?.text || '',
-        target_node_id: c?.target_node_id || '',
-      })) : [],
+      choices: Array.isArray(raw?.choices) ? raw.choices.map(normalizeChoice) : [],
       hint: raw?.hint || '',
       overlay_text: Boolean(raw?.overlay_text),
       transcript_url: raw?.transcript_url || '',
@@ -221,8 +227,10 @@ function BranchingStudioEditor(runtime, element, data) {
       const $row = $(this);
       const text = $row.find('.choice-text').val()?.trim() || '';
       const target = $row.find('.choice-target').val()?.trim() || '';
+      const parsedScore = Number.parseInt($row.find('.choice-score').val(), 10);
+      const score = Number.isNaN(parsedScore) ? 0 : parsedScore;
       if (text || target) {
-        choices.push({ text, target_node_id: target });
+        choices.push({ text, target_node_id: target, score });
       }
     });
     node.choices = choices;
@@ -257,7 +265,15 @@ function BranchingStudioEditor(runtime, element, data) {
             type: n.media?.type || '',
             url: (n.media?.type === 'image') ? '' : (n.media?.url || '').trim(),
           },
-          choices: Array.isArray(n.choices) ? n.choices.filter(c => c?.text && c?.target_node_id) : [],
+          choices: Array.isArray(n.choices)
+            ? n.choices
+              .filter(c => c?.text && c?.target_node_id)
+              .map(c => ({
+                text: c.text,
+                target_node_id: c.target_node_id,
+                score: Number.isNaN(Number.parseInt(c.score, 10)) ? 0 : Number.parseInt(c.score, 10),
+              }))
+            : [],
           hint: (n.hint || '').trim(),
           overlay_text: Boolean(n.overlay_text),
           left_image_url: (n.left_image_url || '').trim(),
@@ -380,7 +396,7 @@ function BranchingStudioEditor(runtime, element, data) {
       }
       syncCurrentNodeFromDom();
       node.choices = Array.isArray(node.choices) ? node.choices : [];
-      node.choices.push({ text: '', target_node_id: '' });
+      node.choices.push({ text: '', target_node_id: '', score: 0 });
       renderNodeEditor();
     });
 

From cbc7212f8cd51d5cd5f1e4229e790416b0bb859e Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Mon, 9 Feb 2026 10:03:13 -0500
Subject: [PATCH 09/32] fix: update styling

---
 branching_xblock/static/css/studio_editor.css | 90 ++++++++++++-------
 .../static/handlebars/choice-row.handlebars   | 43 +++++----
 .../static/handlebars/node-editor.handlebars  |  4 +-
 3 files changed, 87 insertions(+), 50 deletions(-)

diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index ad2cc9b..dcfb58e 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -189,69 +189,97 @@
 }
 
 .bx-choices .choices-container {
-    margin-top: 10px;
+    margin-top: 8px;
+}
+
+.bx-choices-help {
+    margin: 0 0 8px;
+    font-size: 12px;
+    line-height: 1.3;
+    color: #6b7280;
 }
 
 .choice-row {
     display: flex;
-    align-items: center;
-    gap: 8px;
-    margin: 8px 0;
+    flex-wrap: wrap;
+    align-items: flex-end;
+    gap: 10px;
+    margin: 0 0 10px;
 }
 
-.choice-row input.choice-text {
-    flex: 0 1 320px;
-    width: 320px;
-    max-width: 320px;
-    min-height: 40px;
-    border: 1px solid #c8cdd3;
-    border-radius: 0;
-    padding: 8px 10px;
-    font-size: 14px;
-    font-weight: 400;
-    line-height: 1.3;
+.choice-col {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
 }
 
-.choice-row input.choice-score {
+.choice-col--text {
+    flex: 1 1 360px;
+    min-width: 260px;
+    max-width: 420px;
+}
+
+.choice-col--score {
     flex: none;
     width: 88px;
-    min-height: 40px;
-    border: 1px solid #c8cdd3;
-    border-radius: 0;
-    padding: 8px 10px;
-    font-size: 14px;
-    font-weight: 400;
-    line-height: 1.3;
 }
 
-.choice-row select.choice-target {
+.choice-col--target {
     flex: none;
-    width: 170px;
-    min-height: 40px;
+    width: 180px;
+}
+
+.choice-col__label {
+    font-size: 12px;
+    line-height: 1.2;
+    color: #303842;
+}
+
+.choice-row input.choice-text,
+.choice-row input.choice-score,
+.choice-row select.choice-target {
+    width: 100%;
+    min-height: 36px;
+    height: 36px;
+    box-sizing: border-box;
     border: 1px solid #c8cdd3;
-    border-radius: 0;
-    padding: 8px 10px;
+    border-radius: 4px;
+    padding: 7px 10px;
     font-size: 14px;
     font-weight: 400;
     line-height: 1.3;
+    color: #303842;
+    background: #fff;
 }
 
 .choice-row .btn-delete-choice {
-    min-width: 34px;
-    min-height: 34px;
+    width: 36px;
+    min-width: 36px;
+    min-height: 36px;
     border: 0;
     border-radius: 4px;
     background: #dc3545;
     color: #fff;
-    font-size: 14px;
+    font-size: 18px;
     line-height: 1;
     cursor: pointer;
+    margin-bottom: 0;
 }
 
 .choice-row .btn-delete-choice:hover {
     opacity: 0.9;
 }
 
+.bx-choices .bx-btn--secondary {
+    min-height: 36px;
+    border-radius: 4px;
+    padding: 7px 12px;
+    font-size: 13px;
+    line-height: 1.3;
+    margin: 4px 0 0;
+}
+
 .overlay-text-control {
     margin-bottom: 8px;
 }
diff --git a/branching_xblock/static/handlebars/choice-row.handlebars b/branching_xblock/static/handlebars/choice-row.handlebars
index 9dea5bc..7d162d0 100644
--- a/branching_xblock/static/handlebars/choice-row.handlebars
+++ b/branching_xblock/static/handlebars/choice-row.handlebars
@@ -1,19 +1,28 @@
 <div class="choice-row" data-choice-idx="{{i}}">
-  <input class="choice-text" value="{{choice.text}}" placeholder="Choice text"/>
-  <input
-    class="choice-score"
-    type="number"
-    min="0"
-    max="100"
-    step="1"
-    value="{{choice.score}}"
-    placeholder="Score"
-    aria-label="Choice score"
-  />
-  <select class="choice-target">
-    {{#each options}}
-      <option value="{{this.id}}" {{#if (eq this.id ../choice.target_node_id)}}selected{{/if}}>{{this.label}}</option>
-    {{/each}}
-  </select>
-  <button type="button" class="btn-delete-choice">x</button>
+  <div class="choice-col choice-col--text">
+    <label class="choice-col__label">Choice text</label>
+    <input class="choice-text" value="{{choice.text}}" placeholder="Choice text"/>
+  </div>
+  <div class="choice-col choice-col--score">
+    <label class="choice-col__label">Score</label>
+    <input
+      class="choice-score"
+      type="number"
+      min="0"
+      max="100"
+      step="1"
+      value="{{choice.score}}"
+      placeholder="0"
+      aria-label="Choice score"
+    />
+  </div>
+  <div class="choice-col choice-col--target">
+    <label class="choice-col__label">Destination*</label>
+    <select class="choice-target">
+      {{#each options}}
+        <option value="{{this.id}}" {{#if (eq this.id ../choice.target_node_id)}}selected{{/if}}>{{this.label}}</option>
+      {{/each}}
+    </select>
+  </div>
+  <button type="button" class="btn-delete-choice" aria-label="Delete choice">×</button>
 </div>
diff --git a/branching_xblock/static/handlebars/node-editor.handlebars b/branching_xblock/static/handlebars/node-editor.handlebars
index 387bc70..6f678ea 100644
--- a/branching_xblock/static/handlebars/node-editor.handlebars
+++ b/branching_xblock/static/handlebars/node-editor.handlebars
@@ -58,8 +58,8 @@
 
   <div class="bx-choices {{#if no_branches}}is-hidden{{/if}}" data-role="choices-section">
     <h3 class="bx-section-title">Choices</h3>
-    <button type="button" class="bx-btn bx-btn--secondary" data-role="add-choice">Add Choice</button>
-    <div class="bx-help">Choices with blank node targets will be discarded.</div>
+    <div class="bx-help bx-choices-help">When learner selects a choice, its score is added to their total score.</div>
     <div class="choices-container" data-role="choices-container"></div>
+    <button type="button" class="bx-btn bx-btn--secondary" data-role="add-choice">Add Choice</button>
   </div>
 </div>

From aa9b8a410595575971008d47c41afdd46d074796 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Mon, 9 Feb 2026 11:24:22 -0500
Subject: [PATCH 10/32] fix: hide choices only if no branches flag is selected

---
 branching_xblock/static/js/src/studio_editor.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index 8bca2a8..ba5b934 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -57,6 +57,7 @@ function BranchingStudioEditor(runtime, element, data) {
         url: raw?.media?.url || '',
       },
       choices: Array.isArray(raw?.choices) ? raw.choices.map(normalizeChoice) : [],
+      no_branches: Boolean(raw?.no_branches),
       hint: raw?.hint || '',
       overlay_text: Boolean(raw?.overlay_text),
       transcript_url: raw?.transcript_url || '',
@@ -139,7 +140,7 @@ function BranchingStudioEditor(runtime, element, data) {
     const showMediaUrl = Boolean(mediaType) && !isImage;
     const showTranscript = mediaType === 'audio' || mediaType === 'video';
     const showOverlay = mediaType === 'image';
-    const noBranches = !Array.isArray(node.choices) || node.choices.length === 0;
+    const noBranches = Boolean(node.no_branches);
 
     const leftImageUrl = isImage
       ? (node.left_image_url ?? node.media?.url ?? '')
@@ -217,6 +218,7 @@ function BranchingStudioEditor(runtime, element, data) {
     }
 
     const noBranches = $e.find('[data-role="no-branches"]').is(':checked');
+    node.no_branches = noBranches;
     if (noBranches) {
       node.choices = [];
       return;
@@ -395,6 +397,7 @@ function BranchingStudioEditor(runtime, element, data) {
         return;
       }
       syncCurrentNodeFromDom();
+      node.no_branches = false;
       node.choices = Array.isArray(node.choices) ? node.choices : [];
       node.choices.push({ text: '', target_node_id: '', score: 0 });
       renderNodeEditor();

From e36d8ab745b28cc228a02f576366159898534f9e Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Mon, 9 Feb 2026 12:28:54 -0500
Subject: [PATCH 11/32] feat: add soft delete for nodes

---
 branching_xblock/branching_xblock.py          |  56 +++++-
 branching_xblock/static/css/studio_editor.css | 115 ++++++++++++
 .../static/handlebars/node-editor.handlebars  |  17 +-
 .../handlebars/node-list-item.handlebars      |  20 ++-
 .../static/html/branching_xblock_edit.html    |   1 +
 .../static/js/src/studio_editor.js            | 167 ++++++++++++++++--
 6 files changed, 347 insertions(+), 29 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 61e889b..fc65ae4 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -459,17 +459,11 @@ def studio_submit(self, data, suffix=''):
         """
         payload = data
         raw_nodes = payload.get('nodes', [])
+        deleted_node_ids = set(payload.get('deleted_node_ids', []))
         background_image_url = (payload.get('background_image_url') or '').strip()
         background_image_alt_text = (payload.get('background_image_alt_text') or '').strip()
         background_image_is_decorative = bool(payload.get('background_image_is_decorative', False))
 
-        if len(raw_nodes) > 30:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": ["Too many nodes (max 30)."]}
-            }
-
         if background_image_url and not background_image_is_decorative and not background_image_alt_text:
             return {
                 "result": "error",
@@ -505,9 +499,50 @@ def studio_submit(self, data, suffix=''):
                 'transcript_url': raw.get('transcript_url', ''),
             })
 
+        resolved_deleted_node_ids = {
+            id_map.get(node_id, node_id)
+            for node_id in deleted_node_ids
+        }
+        node_number_by_id = {
+            node['id']: index + 1
+            for index, node in enumerate(staged)
+        }
+
+        reference_errors = []
+        seen_reference_errors = set()
+        for node in staged:
+            if node['id'] in resolved_deleted_node_ids:
+                continue
+            source_node_number = node_number_by_id.get(node['id'])
+            for raw_choice in node['choices']:
+                target_node_id = id_map.get((raw_choice.get('target_node_id') or '').strip(), (raw_choice.get('target_node_id') or '').strip())
+                if not target_node_id or target_node_id not in resolved_deleted_node_ids:
+                    continue
+                target_node_number = node_number_by_id.get(target_node_id)
+                if source_node_number and target_node_number:
+                    error_message = (
+                        f"Cannot delete Node {target_node_number} because it is referenced by Node {source_node_number}."
+                    )
+                else:
+                    error_message = (
+                        "Cannot delete a node that is still referenced by another node."
+                    )
+                if error_message not in seen_reference_errors:
+                    seen_reference_errors.add(error_message)
+                    reference_errors.append(error_message)
+
+        if reference_errors:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {"nodes_json": reference_errors}
+            }
+
         # 2) Remap choice targets & clean arrays
         final = []
         for node in staged:
+            if node['id'] in resolved_deleted_node_ids:
+                continue
             # filter out completely blank nodes
             has_content = bool(node['content'].strip())
             has_media = bool(node['media']['url'].strip())
@@ -561,6 +596,13 @@ def studio_submit(self, data, suffix=''):
                 "field_errors": {"nodes_json": score_errors}
             }
 
+        if len(final) > 30:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {"nodes_json": ["Too many nodes (max 30)."]}
+            }
+
         # 3) Persist scenario_data & settings
         nodes_dict = {node['id']: node for node in final}
         self.scenario_data = {
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index dcfb58e..e9cd30a 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -153,6 +153,16 @@
     border-color: #f3f4f6;
 }
 
+.bx-node-list-item.is-pending-delete {
+    background: #f9fafb;
+    border-color: #e5e7eb;
+}
+
+.bx-node-list-item.is-pending-delete .bx-node-list-item__select {
+    color: #6b7280;
+    text-decoration: line-through;
+}
+
 .bx-node-list-item__select {
     flex: 1;
     border: 0;
@@ -165,6 +175,21 @@
     color: #1f2933;
 }
 
+.bx-node-list-item__error {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 16px;
+    height: 16px;
+    border-radius: 50%;
+    margin-right: 6px;
+    font-size: 10px;
+    font-weight: 700;
+    line-height: 1;
+    color: #fff;
+    background: #dc3545;
+}
+
 .bx-node-list-item__delete {
     border: 0;
     background: transparent;
@@ -175,10 +200,81 @@
     opacity: 0.9;
 }
 
+.bx-node-list-item__delete .fa {
+    font-size: 14px;
+    line-height: 1;
+}
+
 .bx-node-list-item__delete:hover {
     opacity: 1;
 }
 
+.bx-node-list-item__delete.is-restore {
+    color: #303842;
+}
+
+.bx-node-editor-header {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-bottom: 12px;
+}
+
+.bx-node-editor-header .bx-step-title {
+    margin-bottom: 0;
+}
+
+.bx-node-error-banner {
+    display: flex;
+    align-items: flex-start;
+    gap: 8px;
+    margin: 0 0 12px;
+    padding: 10px 12px;
+    border: 1px solid #f5c2c7;
+    border-radius: 4px;
+    background: #f8d7da;
+    color: #842029;
+    max-width: 675px;
+}
+
+.bx-node-error-banner__icon {
+    flex: none;
+    margin-top: 1px;
+    font-size: 14px;
+    line-height: 1.2;
+    color: #d23228;
+}
+
+.bx-node-error-banner__content {
+    min-width: 0;
+}
+
+.bx-node-error-banner__title {
+    font-size: 13px;
+    font-weight: 600;
+    line-height: 1.4;
+}
+
+.bx-node-error-banner__detail {
+    margin-top: 2px;
+    font-size: 13px;
+    font-weight: 400;
+    line-height: 1.35;
+}
+
+.bx-pending-delete-badge {
+    display: inline-flex;
+    align-items: center;
+    min-height: 18px;
+    border-radius: 999px;
+    background: #dc3545;
+    color: #fff;
+    padding: 1px 8px;
+    font-size: 11px;
+    font-weight: 600;
+    line-height: 1.2;
+}
+
 .bx-nodes-main {
     flex: 1;
     padding-left: 0;
@@ -343,6 +439,25 @@
     box-shadow: 0 -2px 8px rgba(0, 0, 0, 0.06);
 }
 
+.xblock-actions__warning {
+    margin-left: auto;
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 11px;
+    line-height: 1.2;
+    color: #7c5e00;
+    padding: 0;
+}
+
+.xblock-actions__warning::before {
+    content: "\f071";
+    font-family: FontAwesome;
+    font-size: 11px;
+    line-height: 1;
+    color: #c08a00;
+}
+
 .xblock-actions .action-primary {
     min-height: 36px;
     border: 1px solid #006fb9;
diff --git a/branching_xblock/static/handlebars/node-editor.handlebars b/branching_xblock/static/handlebars/node-editor.handlebars
index 6f678ea..26bc1d5 100644
--- a/branching_xblock/static/handlebars/node-editor.handlebars
+++ b/branching_xblock/static/handlebars/node-editor.handlebars
@@ -1,5 +1,20 @@
 <div class="bx-node-editor-inner" data-node-id="{{id}}">
-  <h2 class="bx-step-title">Node {{number}}</h2>
+  {{#if node_error_detail}}
+    <div class="bx-node-error-banner" role="alert">
+      <span class="fa fa-exclamation-circle bx-node-error-banner__icon" aria-hidden="true"></span>
+      <div class="bx-node-error-banner__content">
+        <div class="bx-node-error-banner__title">You can't delete this node</div>
+        <div class="bx-node-error-banner__detail">{{node_error_detail}}</div>
+      </div>
+    </div>
+  {{/if}}
+
+  <div class="bx-node-editor-header">
+    <h2 class="bx-step-title">Node {{number}}</h2>
+    {{#if is_pending_delete}}
+      <span class="bx-pending-delete-badge">Pending deletion</span>
+    {{/if}}
+  </div>
 
   <label class="bx-field">
     <div class="bx-field__label">Content</div>
diff --git a/branching_xblock/static/handlebars/node-list-item.handlebars b/branching_xblock/static/handlebars/node-list-item.handlebars
index 3784ecf..fba3298 100644
--- a/branching_xblock/static/handlebars/node-list-item.handlebars
+++ b/branching_xblock/static/handlebars/node-list-item.handlebars
@@ -1,9 +1,21 @@
-<div class="bx-node-list-item {{#if is_selected}}is-selected{{/if}}" data-node-id="{{id}}">
+<div class="bx-node-list-item {{#if is_selected}}is-selected{{/if}} {{#if is_pending_delete}}is-pending-delete{{/if}} {{#if has_errors}}has-errors{{/if}}" data-node-id="{{id}}">
   <button type="button" class="bx-node-list-item__select" data-role="select-node" data-node-id="{{id}}">
     Node {{number}}
   </button>
-  <button type="button" class="bx-node-list-item__delete" data-role="delete-node" data-node-id="{{id}}" aria-label="Delete node">
-    🗑
+  {{#if has_errors}}
+    <span class="bx-node-list-item__error" aria-label="Node has errors">!</span>
+  {{/if}}
+  <button
+    type="button"
+    class="bx-node-list-item__delete {{#if is_pending_delete}}is-restore{{/if}}"
+    data-role="toggle-delete-node"
+    data-node-id="{{id}}"
+    aria-label="{{#if is_pending_delete}}Restore node{{else}}Delete node{{/if}}"
+  >
+    {{#if is_pending_delete}}
+      <span class="fa fa-undo" aria-hidden="true"></span>
+    {{else}}
+      <span class="fa fa-trash-o" aria-hidden="true"></span>
+    {{/if}}
   </button>
 </div>
-
diff --git a/branching_xblock/static/html/branching_xblock_edit.html b/branching_xblock/static/html/branching_xblock_edit.html
index 122734d..52e5c9a 100644
--- a/branching_xblock/static/html/branching_xblock_edit.html
+++ b/branching_xblock/static/html/branching_xblock_edit.html
@@ -11,4 +11,5 @@
   <button type="button" class="action-primary" data-role="save" hidden>Save</button>
   <button type="button" class="action-secondary" data-role="back" hidden>Back</button>
   <button type="button" class="action-secondary" data-role="cancel">Cancel</button>
+  <div class="xblock-actions__warning" data-role="pending-delete-summary" hidden></div>
 </div>
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index ba5b934..3d0d39e 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -14,6 +14,7 @@ function BranchingStudioEditor(runtime, element, data) {
   const $saveBtn = $root.find('[data-role="save"]');
   const $backBtn = $root.find('[data-role="back"]');
   const $cancelBtn  = $root.find('[data-role="cancel"]');
+  const $pendingDeleteSummary = $root.find('[data-role="pending-delete-summary"]');
 
   this.uniqueIdCount = 0;
 
@@ -27,6 +28,7 @@ function BranchingStudioEditor(runtime, element, data) {
     selectedNodeId: null,
     draftSettings: {},
     draftNodes: [],
+    showDeleteValidationErrors: false,
   };
 
   function loadState() {
@@ -58,6 +60,7 @@ function BranchingStudioEditor(runtime, element, data) {
       },
       choices: Array.isArray(raw?.choices) ? raw.choices.map(normalizeChoice) : [],
       no_branches: Boolean(raw?.no_branches),
+      pending_delete: false,
       hint: raw?.hint || '',
       overlay_text: Boolean(raw?.overlay_text),
       transcript_url: raw?.transcript_url || '',
@@ -92,6 +95,8 @@ function BranchingStudioEditor(runtime, element, data) {
     $continueBtn.attr('hidden', !showSettings);
     $saveBtn.attr('hidden', showSettings);
     $backBtn.attr('hidden', showSettings);
+    updateFooterUi();
+    updateClientValidationUi();
   }
 
   function nodeIndexById(nodeId) {
@@ -109,6 +114,108 @@ function BranchingStudioEditor(runtime, element, data) {
       .filter(opt => opt.id !== excludeNodeId);
   }
 
+  function activeNodes() {
+    return wizard.draftNodes.filter(node => !node.pending_delete);
+  }
+
+  function pendingDeleteNodes() {
+    return wizard.draftNodes.filter(node => node.pending_delete);
+  }
+
+  function nodeNumberById(nodeId) {
+    const idx = wizard.draftNodes.findIndex(node => node.id === nodeId);
+    return idx >= 0 ? idx + 1 : null;
+  }
+
+  function buildClientValidation() {
+    const errors = [];
+    const seenErrors = new Set();
+    const nodeErrorDetailsById = new Map();
+    const nodeErrorIds = new Set();
+    const pendingDeleteIds = new Set(pendingDeleteNodes().map(node => node.id));
+    const active = activeNodes();
+
+    if (!active.length) {
+      errors.push('At least one active node is required.');
+    }
+
+    active.forEach((sourceNode) => {
+      (sourceNode.choices || []).forEach((choice) => {
+        const targetNodeId = (choice?.target_node_id || '').trim();
+        if (!targetNodeId || !pendingDeleteIds.has(targetNodeId)) {
+          return;
+        }
+        const sourceNumber = nodeNumberById(sourceNode.id);
+        const targetNumber = nodeNumberById(targetNodeId);
+        let message;
+        if (sourceNumber && targetNumber) {
+          message = `Cannot delete Node ${targetNumber} because it is referenced by Node ${sourceNumber}.`;
+          if (!seenErrors.has(message)) {
+            seenErrors.add(message);
+            errors.push(message);
+          }
+        } else {
+          message = 'Cannot delete a node that is still referenced by another node.';
+          if (!seenErrors.has(message)) {
+            seenErrors.add(message);
+            errors.push(message);
+          }
+        }
+        nodeErrorIds.add(sourceNode.id);
+        nodeErrorIds.add(targetNodeId);
+        if (!nodeErrorDetailsById.has(targetNodeId)) {
+          if (sourceNumber && targetNumber) {
+            nodeErrorDetailsById.set(
+              targetNodeId,
+              `Node ${targetNumber} is referenced by Node ${sourceNumber}.`
+            );
+          } else {
+            nodeErrorDetailsById.set(
+              targetNodeId,
+              'This node is still referenced by another node in this scenario.'
+            );
+          }
+        }
+      });
+    });
+
+    return { errors, nodeErrorIds, nodeErrorDetailsById };
+  }
+
+  function updateFooterUi() {
+    const pendingCount = pendingDeleteNodes().length;
+    if (wizard.currentStep !== 'nodes' || pendingCount === 0) {
+      $pendingDeleteSummary.attr('hidden', true).text('');
+      return;
+    }
+    const nodeWord = pendingCount === 1 ? 'node' : 'nodes';
+    $pendingDeleteSummary
+      .attr('hidden', false)
+      .text(`${pendingCount} ${nodeWord} will be deleted when you save.`);
+  }
+
+  function updateClientValidationUi() {
+    const validation = buildClientValidation();
+    if (wizard.showDeleteValidationErrors) {
+      wizard.validationErrors = validation.errors;
+      wizard.validationNodeErrorIds = validation.nodeErrorIds;
+      wizard.validationNodeErrorDetailsById = validation.nodeErrorDetailsById;
+      const generalErrors = validation.errors.filter(msg => msg === 'At least one active node is required.');
+      if (wizard.currentStep === 'nodes' && generalErrors.length) {
+        $errors.empty();
+        generalErrors.forEach(msg => $errors.append($('<div>').text(msg)));
+      } else {
+        $errors.empty();
+      }
+    } else {
+      wizard.validationErrors = [];
+      wizard.validationNodeErrorIds = new Set();
+      wizard.validationNodeErrorDetailsById = new Map();
+      $errors.empty();
+    }
+    $saveBtn.prop('disabled', false);
+  }
+
   function renderSettings() {
     $stepSettings.html(Templates['settings-step'](wizard.draftSettings));
   }
@@ -120,10 +227,12 @@ function BranchingStudioEditor(runtime, element, data) {
         id: n.id,
         number: idx + 1,
         is_selected: n.id === wizard.selectedNodeId,
+        is_pending_delete: Boolean(n.pending_delete),
+        has_errors: wizard.validationNodeErrorIds?.has(n.id),
       }));
     });
 
-    const atLimit = wizard.draftNodes.length >= 30;
+    const atLimit = activeNodes().length >= 30;
     $stepNodes.find('[data-role="add-node"]').prop('disabled', atLimit);
   }
 
@@ -157,6 +266,8 @@ function BranchingStudioEditor(runtime, element, data) {
       show_transcript: showTranscript,
       show_overlay: showOverlay,
       no_branches: noBranches,
+      is_pending_delete: Boolean(node.pending_delete),
+      node_error_detail: wizard.validationNodeErrorDetailsById?.get(node.id) || '',
       left_image_url: leftImageUrl,
       right_image_url: rightImageUrl,
     });
@@ -179,6 +290,8 @@ function BranchingStudioEditor(runtime, element, data) {
     renderSettings();
     renderNodesStep();
     showStep(wizard.currentStep);
+    updateFooterUi();
+    updateClientValidationUi();
   }
 
   function syncSettingsFromDom() {
@@ -258,6 +371,15 @@ function BranchingStudioEditor(runtime, element, data) {
     $saveBtn.off('click').on('click', function() {
       syncSettingsFromDom();
       syncCurrentNodeFromDom();
+      const validation = buildClientValidation();
+      if (validation.errors.length) {
+        wizard.showDeleteValidationErrors = true;
+        updateClientValidationUi();
+        renderNodeList();
+        renderNodeEditor();
+        return;
+      }
+      wizard.showDeleteValidationErrors = false;
 
       const payload = {
         nodes: wizard.draftNodes.map(n => ({
@@ -282,6 +404,9 @@ function BranchingStudioEditor(runtime, element, data) {
           right_image_url: (n.right_image_url || '').trim(),
           transcript_url: (n.transcript_url || '').trim(),
         })),
+        deleted_node_ids: wizard.draftNodes
+          .filter(node => node.pending_delete)
+          .map(node => node.id),
         enable_undo: Boolean(wizard.draftSettings.enable_undo),
         enable_scoring: Boolean(wizard.draftSettings.enable_scoring),
         enable_reset_activity: Boolean(wizard.draftSettings.enable_reset_activity),
@@ -303,9 +428,11 @@ function BranchingStudioEditor(runtime, element, data) {
           runtime.notify('cancel', {});
         } else {
           showErrors(res);
+          $saveBtn.prop('disabled', false);
         }
       }).fail(function() {
         $errors.text('Error saving scenario');
+        $saveBtn.prop('disabled', false);
       });
     });
 
@@ -330,7 +457,7 @@ function BranchingStudioEditor(runtime, element, data) {
 
     $root.off('click.bx-nodes', '[data-role="add-node"]');
     $root.on('click.bx-nodes', '[data-role="add-node"]', function() {
-      if (wizard.draftNodes.length >= 30) {
+      if (activeNodes().length >= 30) {
         return;
       }
       syncCurrentNodeFromDom();
@@ -339,6 +466,8 @@ function BranchingStudioEditor(runtime, element, data) {
       wizard.selectedNodeId = node.id;
       renderNodeList();
       renderNodeEditor();
+      updateFooterUi();
+      updateClientValidationUi();
     });
 
     $root.off('click.bx-nodes', '[data-role="select-node"]');
@@ -347,47 +476,49 @@ function BranchingStudioEditor(runtime, element, data) {
       if (!nodeId || nodeId === wizard.selectedNodeId) {
         return;
       }
+      const node = wizard.draftNodes.find(n => n.id === nodeId);
+      if (!node) {
+        return;
+      }
       syncCurrentNodeFromDom();
       wizard.selectedNodeId = nodeId;
       renderNodeList();
       renderNodeEditor();
+      updateFooterUi();
+      updateClientValidationUi();
     });
 
-    $root.off('click.bx-nodes', '[data-role="delete-node"]');
-    $root.on('click.bx-nodes', '[data-role="delete-node"]', function() {
+    $root.off('click.bx-nodes', '[data-role="toggle-delete-node"]');
+    $root.on('click.bx-nodes', '[data-role="toggle-delete-node"]', function() {
       const nodeId = $(this).data('node-id');
       if (!nodeId) {
         return;
       }
       syncCurrentNodeFromDom();
-
-      wizard.draftNodes = wizard.draftNodes.filter(n => n.id !== nodeId);
-      wizard.draftNodes.forEach(n => {
-        n.choices = (n.choices || []).filter(c => c.target_node_id !== nodeId);
-      });
-
-      if (!wizard.draftNodes.length) {
-        const node = normalizeNode({});
-        wizard.draftNodes = [node];
-        wizard.selectedNodeId = node.id;
-      } else if (wizard.selectedNodeId === nodeId) {
-        wizard.selectedNodeId = wizard.draftNodes[0].id;
+      const node = wizard.draftNodes.find(n => n.id === nodeId);
+      if (!node) {
+        return;
       }
-
+      node.pending_delete = !node.pending_delete;
+      wizard.showDeleteValidationErrors = false;
+      updateClientValidationUi();
       renderNodeList();
       renderNodeEditor();
+      updateFooterUi();
     });
 
     $root.off('change.bx-node', '[data-role="media-type"]');
     $root.on('change.bx-node', '[data-role="media-type"]', function() {
       syncCurrentNodeFromDom();
       renderNodeEditor();
+      updateClientValidationUi();
     });
 
     $root.off('change.bx-node', '[data-role="no-branches"]');
     $root.on('change.bx-node', '[data-role="no-branches"]', function() {
       syncCurrentNodeFromDom();
       renderNodeEditor();
+      updateClientValidationUi();
     });
 
     $root.off('click.bx-node', '[data-role="add-choice"]');
@@ -401,6 +532,7 @@ function BranchingStudioEditor(runtime, element, data) {
       node.choices = Array.isArray(node.choices) ? node.choices : [];
       node.choices.push({ text: '', target_node_id: '', score: 0 });
       renderNodeEditor();
+      updateClientValidationUi();
     });
 
     $root.off('click.bx-node', '.btn-delete-choice');
@@ -415,6 +547,7 @@ function BranchingStudioEditor(runtime, element, data) {
         node.choices.splice(idx, 1);
       }
       renderNodeEditor();
+      updateClientValidationUi();
     });
   }
 

From fdb2ad9f7257a4675d2f8b6d3171f94478bf2257 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Tue, 10 Feb 2026 11:40:24 -0500
Subject: [PATCH 12/32] feat: Add save validation for fields

---
 branching_xblock/static/css/studio_editor.css | 36 +++++++++-
 .../static/handlebars/choice-row.handlebars   |  6 +-
 .../static/handlebars/node-editor.handlebars  |  5 +-
 .../static/html/branching_xblock_edit.html    |  1 +
 .../static/js/src/studio_editor.js            | 72 +++++++++++++++++--
 5 files changed, 113 insertions(+), 7 deletions(-)

diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index e9cd30a..4967873 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -83,6 +83,21 @@
     color: #1f2933;
 }
 
+.branching-editor-step .bx-input.is-error,
+.branching-editor-step .bx-select.is-error,
+.choice-row .choice-target.is-error {
+    border-color: #d23228;
+    box-shadow: inset 0 0 0 1px #d23228;
+}
+
+.bx-field-error,
+.choice-field-error {
+    margin-top: 4px;
+    font-size: 11px;
+    line-height: 1.2;
+    color: #d23228;
+}
+
 .branching-editor-step .bx-textarea {
     max-width: 700px;
     min-height: 112px;
@@ -298,7 +313,7 @@
 .choice-row {
     display: flex;
     flex-wrap: wrap;
-    align-items: flex-end;
+    align-items: flex-start;
     gap: 10px;
     margin: 0 0 10px;
 }
@@ -361,6 +376,7 @@
     line-height: 1;
     cursor: pointer;
     margin-bottom: 0;
+    margin-top: 20px;
 }
 
 .choice-row .btn-delete-choice:hover {
@@ -458,6 +474,24 @@
     color: #c08a00;
 }
 
+.xblock-actions__error {
+    margin-left: auto;
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 11px;
+    line-height: 1.2;
+    color: #d23228;
+}
+
+.xblock-actions__error::before {
+    content: "\f06a";
+    font-family: FontAwesome;
+    font-size: 11px;
+    line-height: 1;
+    color: #d23228;
+}
+
 .xblock-actions .action-primary {
     min-height: 36px;
     border: 1px solid #006fb9;
diff --git a/branching_xblock/static/handlebars/choice-row.handlebars b/branching_xblock/static/handlebars/choice-row.handlebars
index 7d162d0..77fbf7a 100644
--- a/branching_xblock/static/handlebars/choice-row.handlebars
+++ b/branching_xblock/static/handlebars/choice-row.handlebars
@@ -18,11 +18,15 @@
   </div>
   <div class="choice-col choice-col--target">
     <label class="choice-col__label">Destination*</label>
-    <select class="choice-target">
+    <select class="choice-target {{#if destination_error}}is-error{{/if}}">
+      <option value="" {{#unless choice.target_node_id}}selected{{/unless}}>Select node</option>
       {{#each options}}
         <option value="{{this.id}}" {{#if (eq this.id ../choice.target_node_id)}}selected{{/if}}>{{this.label}}</option>
       {{/each}}
     </select>
+    {{#if destination_error}}
+      <div class="choice-field-error">{{destination_error}}</div>
+    {{/if}}
   </div>
   <button type="button" class="btn-delete-choice" aria-label="Delete choice">×</button>
 </div>
diff --git a/branching_xblock/static/handlebars/node-editor.handlebars b/branching_xblock/static/handlebars/node-editor.handlebars
index 26bc1d5..5d7de6b 100644
--- a/branching_xblock/static/handlebars/node-editor.handlebars
+++ b/branching_xblock/static/handlebars/node-editor.handlebars
@@ -34,7 +34,10 @@
   <div class="{{#unless is_image}}is-hidden{{/unless}}" data-role="image-url-fields">
     <label class="bx-field">
       <div class="bx-field__label">Left image URL</div>
-      <input type="text" class="bx-input" data-role="left-image-url" placeholder="URL" value="{{left_image_url}}" />
+      <input type="text" class="bx-input {{#if left_image_url_error}}is-error{{/if}}" data-role="left-image-url" placeholder="URL" value="{{left_image_url}}" />
+      {{#if left_image_url_error}}
+        <div class="bx-field-error">{{left_image_url_error}}</div>
+      {{/if}}
     </label>
     <label class="bx-field">
       <div class="bx-field__label">Right image URL</div>
diff --git a/branching_xblock/static/html/branching_xblock_edit.html b/branching_xblock/static/html/branching_xblock_edit.html
index 52e5c9a..1edd3d2 100644
--- a/branching_xblock/static/html/branching_xblock_edit.html
+++ b/branching_xblock/static/html/branching_xblock_edit.html
@@ -11,5 +11,6 @@
   <button type="button" class="action-primary" data-role="save" hidden>Save</button>
   <button type="button" class="action-secondary" data-role="back" hidden>Back</button>
   <button type="button" class="action-secondary" data-role="cancel">Cancel</button>
+  <div class="xblock-actions__error" data-role="save-validation-summary" hidden></div>
   <div class="xblock-actions__warning" data-role="pending-delete-summary" hidden></div>
 </div>
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index 3d0d39e..af0a718 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -15,6 +15,7 @@ function BranchingStudioEditor(runtime, element, data) {
   const $backBtn = $root.find('[data-role="back"]');
   const $cancelBtn  = $root.find('[data-role="cancel"]');
   const $pendingDeleteSummary = $root.find('[data-role="pending-delete-summary"]');
+  const $saveValidationSummary = $root.find('[data-role="save-validation-summary"]');
 
   this.uniqueIdCount = 0;
 
@@ -29,6 +30,8 @@ function BranchingStudioEditor(runtime, element, data) {
     draftSettings: {},
     draftNodes: [],
     showDeleteValidationErrors: false,
+    showFieldValidationErrors: false,
+    validationFieldErrorsByNodeId: new Map(),
   };
 
   function loadState() {
@@ -132,6 +135,7 @@ function BranchingStudioEditor(runtime, element, data) {
     const seenErrors = new Set();
     const nodeErrorDetailsById = new Map();
     const nodeErrorIds = new Set();
+    const fieldErrorsByNodeId = new Map();
     const pendingDeleteIds = new Set(pendingDeleteNodes().map(node => node.id));
     const active = activeNodes();
 
@@ -179,12 +183,46 @@ function BranchingStudioEditor(runtime, element, data) {
       });
     });
 
-    return { errors, nodeErrorIds, nodeErrorDetailsById };
+    active.forEach((node) => {
+      const nodeFieldErrors = {};
+
+      if (node.media?.type === 'image') {
+        const leftImageUrl = (node.left_image_url || '').trim();
+        const rightImageUrl = (node.right_image_url || '').trim();
+        if (!leftImageUrl && !rightImageUrl) {
+          nodeFieldErrors.left_image_url = 'Please enter a valid URL';
+        }
+      }
+
+      const choiceDestinationByIndex = {};
+      (node.choices || []).forEach((choice, index) => {
+        const choiceText = (choice?.text || '').trim();
+        const choiceTarget = (choice?.target_node_id || '').trim();
+        if (choiceText && !choiceTarget) {
+          choiceDestinationByIndex[index] = 'Required field';
+        }
+      });
+
+      if (Object.keys(choiceDestinationByIndex).length > 0) {
+        nodeFieldErrors.choiceDestinationByIndex = choiceDestinationByIndex;
+      }
+
+      if (Object.keys(nodeFieldErrors).length > 0) {
+        fieldErrorsByNodeId.set(node.id, nodeFieldErrors);
+        nodeErrorIds.add(node.id);
+        errors.push(`Node ${nodeNumberById(node.id)} has required fields missing.`);
+      }
+    });
+
+    return { errors, nodeErrorIds, nodeErrorDetailsById, fieldErrorsByNodeId };
   }
 
   function updateFooterUi() {
+    if (!wizard.showFieldValidationErrors) {
+      $saveValidationSummary.attr('hidden', true).text('');
+    }
     const pendingCount = pendingDeleteNodes().length;
-    if (wizard.currentStep !== 'nodes' || pendingCount === 0) {
+    if (wizard.currentStep !== 'nodes' || pendingCount === 0 || wizard.showFieldValidationErrors) {
       $pendingDeleteSummary.attr('hidden', true).text('');
       return;
     }
@@ -196,10 +234,11 @@ function BranchingStudioEditor(runtime, element, data) {
 
   function updateClientValidationUi() {
     const validation = buildClientValidation();
-    if (wizard.showDeleteValidationErrors) {
+    if (wizard.showDeleteValidationErrors || wizard.showFieldValidationErrors) {
       wizard.validationErrors = validation.errors;
       wizard.validationNodeErrorIds = validation.nodeErrorIds;
       wizard.validationNodeErrorDetailsById = validation.nodeErrorDetailsById;
+      wizard.validationFieldErrorsByNodeId = validation.fieldErrorsByNodeId;
       const generalErrors = validation.errors.filter(msg => msg === 'At least one active node is required.');
       if (wizard.currentStep === 'nodes' && generalErrors.length) {
         $errors.empty();
@@ -207,13 +246,23 @@ function BranchingStudioEditor(runtime, element, data) {
       } else {
         $errors.empty();
       }
+      if (wizard.currentStep === 'nodes' && validation.errors.length > 0) {
+        $saveValidationSummary
+          .attr('hidden', false)
+          .text("We weren't able to save your selections. Please fix the errors shown and try again.");
+      } else {
+        $saveValidationSummary.attr('hidden', true).text('');
+      }
     } else {
       wizard.validationErrors = [];
       wizard.validationNodeErrorIds = new Set();
       wizard.validationNodeErrorDetailsById = new Map();
+      wizard.validationFieldErrorsByNodeId = new Map();
+      $saveValidationSummary.attr('hidden', true).text('');
       $errors.empty();
     }
     $saveBtn.prop('disabled', false);
+    updateFooterUi();
   }
 
   function renderSettings() {
@@ -257,6 +306,7 @@ function BranchingStudioEditor(runtime, element, data) {
     const rightImageUrl = isImage
       ? (node.right_image_url ?? '')
       : '';
+    const currentNodeFieldErrors = wizard.validationFieldErrorsByNodeId?.get(node.id) || {};
 
     const html = Templates['node-editor']({
       ...node,
@@ -268,14 +318,21 @@ function BranchingStudioEditor(runtime, element, data) {
       no_branches: noBranches,
       is_pending_delete: Boolean(node.pending_delete),
       node_error_detail: wizard.validationNodeErrorDetailsById?.get(node.id) || '',
+      left_image_url_error: currentNodeFieldErrors.left_image_url || '',
       left_image_url: leftImageUrl,
       right_image_url: rightImageUrl,
     });
     const $editor = $stepNodes.find('[data-role="node-editor"]').html(html);
     const $choices = $editor.find('[data-role="choices-container"]').empty();
     const options = nodeOptions(node.id);
+    const choiceDestinationErrors = currentNodeFieldErrors.choiceDestinationByIndex || {};
     (node.choices || []).forEach((choice, i) => {
-      $choices.append(Templates['choice-row']({ choice, i, options }));
+      $choices.append(Templates['choice-row']({
+        choice,
+        i,
+        options,
+        destination_error: choiceDestinationErrors[i] || '',
+      }));
     });
   }
 
@@ -374,12 +431,14 @@ function BranchingStudioEditor(runtime, element, data) {
       const validation = buildClientValidation();
       if (validation.errors.length) {
         wizard.showDeleteValidationErrors = true;
+        wizard.showFieldValidationErrors = true;
         updateClientValidationUi();
         renderNodeList();
         renderNodeEditor();
         return;
       }
       wizard.showDeleteValidationErrors = false;
+      wizard.showFieldValidationErrors = false;
 
       const payload = {
         nodes: wizard.draftNodes.map(n => ({
@@ -501,6 +560,7 @@ function BranchingStudioEditor(runtime, element, data) {
       }
       node.pending_delete = !node.pending_delete;
       wizard.showDeleteValidationErrors = false;
+      wizard.showFieldValidationErrors = false;
       updateClientValidationUi();
       renderNodeList();
       renderNodeEditor();
@@ -510,6 +570,7 @@ function BranchingStudioEditor(runtime, element, data) {
     $root.off('change.bx-node', '[data-role="media-type"]');
     $root.on('change.bx-node', '[data-role="media-type"]', function() {
       syncCurrentNodeFromDom();
+      wizard.showFieldValidationErrors = false;
       renderNodeEditor();
       updateClientValidationUi();
     });
@@ -517,6 +578,7 @@ function BranchingStudioEditor(runtime, element, data) {
     $root.off('change.bx-node', '[data-role="no-branches"]');
     $root.on('change.bx-node', '[data-role="no-branches"]', function() {
       syncCurrentNodeFromDom();
+      wizard.showFieldValidationErrors = false;
       renderNodeEditor();
       updateClientValidationUi();
     });
@@ -531,6 +593,7 @@ function BranchingStudioEditor(runtime, element, data) {
       node.no_branches = false;
       node.choices = Array.isArray(node.choices) ? node.choices : [];
       node.choices.push({ text: '', target_node_id: '', score: 0 });
+      wizard.showFieldValidationErrors = false;
       renderNodeEditor();
       updateClientValidationUi();
     });
@@ -546,6 +609,7 @@ function BranchingStudioEditor(runtime, element, data) {
       if (!Number.isNaN(idx)) {
         node.choices.splice(idx, 1);
       }
+      wizard.showFieldValidationErrors = false;
       renderNodeEditor();
       updateClientValidationUi();
     });

From d33cb3d9a00489b0c0637f835c445121fc635c0b Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Tue, 10 Feb 2026 13:38:59 -0500
Subject: [PATCH 13/32] fix: disable leaf flag if choices are added

---
 branching_xblock/static/handlebars/node-editor.handlebars | 2 +-
 branching_xblock/static/js/src/studio_editor.js           | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/branching_xblock/static/handlebars/node-editor.handlebars b/branching_xblock/static/handlebars/node-editor.handlebars
index 5d7de6b..3db13ca 100644
--- a/branching_xblock/static/handlebars/node-editor.handlebars
+++ b/branching_xblock/static/handlebars/node-editor.handlebars
@@ -65,7 +65,7 @@
   </div>
 
   <label class="bx-checkbox">
-    <input type="checkbox" data-role="no-branches" {{#if no_branches}}checked{{/if}} />
+    <input type="checkbox" data-role="no-branches" {{#if no_branches}}checked{{/if}} {{#if has_choices}}disabled{{/if}} />
     <span>This node has no branches</span>
   </label>
 
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index af0a718..b001b0c 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -298,7 +298,8 @@ function BranchingStudioEditor(runtime, element, data) {
     const showMediaUrl = Boolean(mediaType) && !isImage;
     const showTranscript = mediaType === 'audio' || mediaType === 'video';
     const showOverlay = mediaType === 'image';
-    const noBranches = Boolean(node.no_branches);
+    const hasChoices = Array.isArray(node.choices) && node.choices.length > 0;
+    const noBranches = Boolean(node.no_branches) && !hasChoices;
 
     const leftImageUrl = isImage
       ? (node.left_image_url ?? node.media?.url ?? '')
@@ -315,6 +316,7 @@ function BranchingStudioEditor(runtime, element, data) {
       show_media_url: showMediaUrl,
       show_transcript: showTranscript,
       show_overlay: showOverlay,
+      has_choices: hasChoices,
       no_branches: noBranches,
       is_pending_delete: Boolean(node.pending_delete),
       node_error_detail: wizard.validationNodeErrorDetailsById?.get(node.id) || '',

From 982c931b47dc2a152e23aae27ca3f74bd212a7ff Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Tue, 10 Feb 2026 15:42:06 -0500
Subject: [PATCH 14/32] feat: display unlinked nodes

---
 branching_xblock/static/css/studio_editor.css  |  5 +++++
 .../handlebars/node-list-item.handlebars       |  2 +-
 .../static/js/src/studio_editor.js             | 18 ++++++++++++++++++
 3 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index 4967873..c1e1274 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -190,6 +190,11 @@
     color: #1f2933;
 }
 
+.bx-node-list-item__meta {
+    font-size: 11px;
+    color: #d23228;
+}
+
 .bx-node-list-item__error {
     display: inline-flex;
     align-items: center;
diff --git a/branching_xblock/static/handlebars/node-list-item.handlebars b/branching_xblock/static/handlebars/node-list-item.handlebars
index fba3298..4ec8d91 100644
--- a/branching_xblock/static/handlebars/node-list-item.handlebars
+++ b/branching_xblock/static/handlebars/node-list-item.handlebars
@@ -1,6 +1,6 @@
 <div class="bx-node-list-item {{#if is_selected}}is-selected{{/if}} {{#if is_pending_delete}}is-pending-delete{{/if}} {{#if has_errors}}has-errors{{/if}}" data-node-id="{{id}}">
   <button type="button" class="bx-node-list-item__select" data-role="select-node" data-node-id="{{id}}">
-    Node {{number}}
+    Node {{number}}{{#if is_unlinked}} <span class="bx-node-list-item__meta">(unlinked node)</span>{{/if}}
   </button>
   {{#if has_errors}}
     <span class="bx-node-list-item__error" aria-label="Node has errors">!</span>
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index b001b0c..d762c79 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -270,14 +270,32 @@ function BranchingStudioEditor(runtime, element, data) {
   }
 
   function renderNodeList() {
+    const incomingReferenceCounts = new Map();
+    wizard.draftNodes.forEach(node => incomingReferenceCounts.set(node.id, 0));
+
+    activeNodes().forEach((sourceNode) => {
+      (sourceNode.choices || []).forEach((choice) => {
+        const targetNodeId = (choice?.target_node_id || '').trim();
+        if (!targetNodeId || !incomingReferenceCounts.has(targetNodeId)) {
+          return;
+        }
+        incomingReferenceCounts.set(
+          targetNodeId,
+          (incomingReferenceCounts.get(targetNodeId) || 0) + 1
+        );
+      });
+    });
+
     const $list = $stepNodes.find('[data-role="node-list"]').empty();
     wizard.draftNodes.forEach((n, idx) => {
+      const isUnlinked = !n.pending_delete && idx > 0 && (incomingReferenceCounts.get(n.id) || 0) === 0;
       $list.append(Templates['node-list-item']({
         id: n.id,
         number: idx + 1,
         is_selected: n.id === wizard.selectedNodeId,
         is_pending_delete: Boolean(n.pending_delete),
         has_errors: wizard.validationNodeErrorIds?.has(n.id),
+        is_unlinked: isUnlinked,
       }));
     });
 

From ab2770cbad7f0d481c39ef2df74447fc8891d6ef Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Fri, 6 Feb 2026 10:25:06 -0500
Subject: [PATCH 15/32] feat: replace hint settings with reset option

---
 branching_xblock/static/css/branching_xblock.css   | 10 ++++++++++
 branching_xblock/static/html/branching_xblock.html |  4 ++--
 branching_xblock/static/js/src/branching_xblock.js |  3 +++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 448cc26..3147433 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -350,6 +350,16 @@
     color: #1f2a37;
 }
 
+.reset-button {
+    border: 1px solid #4a5568;
+    border-radius: 4px;
+    padding: 0.6em 1.2em;
+    font-size: 1em;
+    cursor: pointer;
+    background: transparent;
+    color: #1f2a37;
+}
+
 .score-display {
     padding: 1em 1em;
     font-size: small;
diff --git a/branching_xblock/static/html/branching_xblock.html b/branching_xblock/static/html/branching_xblock.html
index b85cbc0..7b02ec8 100644
--- a/branching_xblock/static/html/branching_xblock.html
+++ b/branching_xblock/static/html/branching_xblock.html
@@ -16,11 +16,11 @@ <h3 class="choices-heading" data-role="choice-heading">Choose Next Step:</h3>
             <form class="choices-form" data-role="choice-form">
                 <div class="choices-list" data-role="choice-list"></div>
                 <div class="choice-actions">
-                    <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo">
+                    <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo" style="display: none;">
                         Go Back
                     </button>
                     <button type="button" class="reset-button action-secondary btn-secondary" data-role="reset-activity" style="display: none;">
-                        Reset Activity
+                        Reset
                     </button>
                     <button type="submit" class="choice-submit-button action-primary" data-role="submit-choice" disabled>
                         Submit
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index 86fecc3..bcf1810 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -232,6 +232,9 @@ function BranchingXBlock(runtime, element) {
             .prop('disabled', !canUndo)
             .toggleClass('is-disabled', !canUndo);
 
+        const showReset = Boolean(state.enable_reset_activity);
+        $el.find('[data-role="reset-activity"]').toggle(showReset);
+
         const $score = $el.find('[data-role="score"]');
         $el.find('[data-role="reset-activity"]').toggle(showReset);
         if (isLeaf && state.enable_scoring) {

From 8e5d707c84b34d57359b1372d82767f9f44166b0 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Fri, 6 Feb 2026 10:44:03 -0500
Subject: [PATCH 16/32] fix: update styling

---
 .../static/css/branching_xblock.css            | 18 ++++++++++--------
 .../static/js/src/branching_xblock.js          |  5 ++++-
 2 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 3147433..43d5f2c 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -350,14 +350,16 @@
     color: #1f2a37;
 }
 
-.reset-button {
-    border: 1px solid #4a5568;
-    border-radius: 4px;
-    padding: 0.6em 1.2em;
-    font-size: 1em;
-    cursor: pointer;
-    background: transparent;
-    color: #1f2a37;
+.reset-button:hover,
+.reset-button:focus {
+    background: #fff7ed;
+    border-color: #9a3412;
+    color: #9a3412;
+}
+
+.reset-button:focus-visible {
+    outline: 2px solid #ea580c;
+    outline-offset: 2px;
 }
 
 .score-display {
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index bcf1810..3c09baa 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -232,7 +232,10 @@ function BranchingXBlock(runtime, element) {
             .prop('disabled', !canUndo)
             .toggleClass('is-disabled', !canUndo);
 
-        const showReset = Boolean(state.enable_reset_activity);
+        const isAtStartNode = Boolean(
+            state.current_node && state.current_node.id === state.start_node_id
+        );
+        const showReset = Boolean(state.enable_reset_activity && !isAtStartNode);
         $el.find('[data-role="reset-activity"]').toggle(showReset);
 
         const $score = $el.find('[data-role="score"]');

From c05093ed8d46f3d353a71bd2532544acc626f46e Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Fri, 6 Feb 2026 11:23:18 -0500
Subject: [PATCH 17/32] fix: update tests

---
 tests/test_branching_xblock.py | 102 ++++++++++++++++++++++++++++++++-
 1 file changed, 101 insertions(+), 1 deletion(-)

diff --git a/tests/test_branching_xblock.py b/tests/test_branching_xblock.py
index 97594ae..25b0123 100644
--- a/tests/test_branching_xblock.py
+++ b/tests/test_branching_xblock.py
@@ -118,6 +118,29 @@ def test_studio_submit_creates_scenario(rf, block):
     assert block.max_score == 77
 
 
+def test_studio_submit_persists_enable_reset_activity(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Start node",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+                "transcript_url": "",
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": False,
+        "enable_reset_activity": True,
+        "max_score": 0,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+    assert result["result"] == "success"
+    assert block.enable_reset_activity is True
+
+
 def test_studio_submit_persists_display_name(rf, block):
     payload = {
         "nodes": [
@@ -256,6 +279,52 @@ def test_undo_choice_honors_enable_undo(rf, block):
     assert resp_fail["success"] is False
 
 
+def test_reset_activity_requires_enable_reset_activity(rf, block):
+    block.scenario_data = {
+        "nodes": {"start": {"id": "start", "type": "start", "choices": []}},
+        "start_node_id": "start",
+    }
+    block.enable_reset_activity = False
+    req = rf.post("/", data=json.dumps({}), content_type="application/json")
+    resp = block.reset_activity(req)
+    result = json.loads(resp.body.decode("utf-8"))
+    assert result["success"] is False
+    assert result["error"] == "Reset not allowed"
+
+
+def test_reset_activity_clears_progress_and_score(rf, block):
+    block.scenario_data = {
+        "nodes": {
+            "start": {
+                "id": "start",
+                "type": "start",
+                "choices": [{"text": "Next", "target_node_id": "end"}],
+            },
+            "end": {"id": "end", "type": "end", "choices": []},
+        },
+        "start_node_id": "start",
+    }
+    block.enable_reset_activity = True
+    block.enable_scoring = True
+    block.current_node_id = "end"
+    block.history = ["start"]
+    block.has_completed = True
+    block.score = 42.0
+    req = rf.post("/", data=json.dumps({}), content_type="application/json")
+
+    resp = block.reset_activity(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["success"] is True
+    assert block.current_node_id == "start"
+    assert block.history == []
+    assert block.has_completed is False
+    assert block.score == 0.0
+    assert result["current_node"]["id"] == "start"
+    assert result["has_completed"] is False
+    assert result["score"] == 0.0
+
+
 def test_get_current_state_includes_expected_fields(rf, block):
     """
     get_current_state should return a dict containing:
@@ -273,7 +342,14 @@ def test_get_current_state_includes_expected_fields(rf, block):
     resp = block.get_current_state(req)
     state = json.loads(resp.body.decode('utf-8'))
     assert isinstance(state["nodes"], dict)
-    for key in ("current_node", "history", "has_completed", "score"):
+    for key in (
+        "current_node",
+        "history",
+        "has_completed",
+        "score",
+        "start_node_id",
+        "enable_reset_activity",
+    ):
         assert key in state
 
 
@@ -303,3 +379,27 @@ def fake_initialize_js(_self, name, init_data):
 
     assert calls["name"] == "BranchingStudioEditor"
     assert calls["init_data"]["authoring_help_html"] == "<p>Help</p>"
+
+
+def test_studio_view_includes_enable_reset_activity_in_init_data(block):
+    calls = {}
+
+    def fake_initialize_js(_self, name, init_data):
+        calls["name"] = name
+        calls["init_data"] = init_data
+
+    block.enable_reset_activity = True
+
+    with mock.patch(
+        "branching_xblock.branching_xblock.Fragment.initialize_js",
+        autospec=True,
+        side_effect=fake_initialize_js,
+    ), mock.patch.object(
+        block.runtime,
+        "local_resource_url",
+        return_value="http://example.com/handlebars.js",
+    ):
+        block.studio_view({})
+
+    assert calls["name"] == "BranchingStudioEditor"
+    assert calls["init_data"]["enable_reset_activity"] is True

From a44a9710220d34180e2c55a93a9fce17de77f517 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Wed, 11 Feb 2026 11:37:17 -0500
Subject: [PATCH 18/32] fix: refactoring errors

---
 branching_xblock/static/css/branching_xblock.css   |  8 ++++----
 branching_xblock/static/html/branching_xblock.html |  4 ++--
 branching_xblock/static/js/src/branching_xblock.js | 11 ++++-------
 3 files changed, 10 insertions(+), 13 deletions(-)

diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 43d5f2c..59032bf 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -341,13 +341,13 @@
 }
 
 .reset-button {
-    border: 1px solid #4a5568;
+    border: 1px solid #9a3412;
     border-radius: 4px;
     padding: 0.6em 1.2em;
     font-size: 1em;
     cursor: pointer;
-    background: transparent;
-    color: #1f2a37;
+    background: #ffffff;
+    color: #9a3412;
 }
 
 .reset-button:hover,
@@ -358,7 +358,7 @@
 }
 
 .reset-button:focus-visible {
-    outline: 2px solid #ea580c;
+    outline: 2px solid #9a3412;
     outline-offset: 2px;
 }
 
diff --git a/branching_xblock/static/html/branching_xblock.html b/branching_xblock/static/html/branching_xblock.html
index 7b02ec8..47dd381 100644
--- a/branching_xblock/static/html/branching_xblock.html
+++ b/branching_xblock/static/html/branching_xblock.html
@@ -16,13 +16,13 @@ <h3 class="choices-heading" data-role="choice-heading">Choose Next Step:</h3>
             <form class="choices-form" data-role="choice-form">
                 <div class="choices-list" data-role="choice-list"></div>
                 <div class="choice-actions">
-                    <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo" style="display: none;">
+                    <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo">
                         Go Back
                     </button>
                     <button type="button" class="reset-button action-secondary btn-secondary" data-role="reset-activity" style="display: none;">
                         Reset
                     </button>
-                    <button type="submit" class="choice-submit-button action-primary" data-role="submit-choice" disabled>
+                    <button type="submit" class="choice-submit-button action-primary btn-primary" data-role="submit-choice" disabled>
                         Submit
                     </button>
                 </div>
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index 3c09baa..a01d5cb 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -222,7 +222,10 @@ function BranchingXBlock(runtime, element) {
         });
         const hasChoices = choices.length > 0;
         const isLeaf = !hasChoices;
-        const showReset = Boolean(state.enable_reset_activity && isLeaf);
+        const isAtStartNode = Boolean(
+            state.current_node && state.current_node.id === state.start_node_id
+        );
+        const showReset = Boolean(state.enable_reset_activity && !isAtStartNode);
         $el.find('[data-role="choice-heading"]').toggle(hasChoices);
         $submitButton.toggle(hasChoices);
         $submitButton.prop('disabled', !hasChoices || selectedChoiceIndex === null);
@@ -231,15 +234,9 @@ function BranchingXBlock(runtime, element) {
         $el.find('.undo-button')
             .prop('disabled', !canUndo)
             .toggleClass('is-disabled', !canUndo);
-
-        const isAtStartNode = Boolean(
-            state.current_node && state.current_node.id === state.start_node_id
-        );
-        const showReset = Boolean(state.enable_reset_activity && !isAtStartNode);
         $el.find('[data-role="reset-activity"]').toggle(showReset);
 
         const $score = $el.find('[data-role="score"]');
-        $el.find('[data-role="reset-activity"]').toggle(showReset);
         if (isLeaf && state.enable_scoring) {
             $score.text(`Score: ${state.score}/${state.max_score}`).show();
         } else {

From 15e2995dc8e1b4535b5b798a27ff8149ba0ea8dd Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 12 Feb 2026 11:43:36 -0500
Subject: [PATCH 19/32] fix: Prevent cyclic nodes

Needed as we are scoring per choice and
cyclic nodes can result in score loops
making highest score unbound
---
 branching_xblock/branching_xblock.py          | 57 ++++++++++++++
 .../static/handlebars/node-editor.handlebars  |  4 +-
 .../static/js/src/studio_editor.js            | 74 ++++++++++++++++++-
 3 files changed, 133 insertions(+), 2 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index fc65ae4..27ac4ce 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -191,6 +191,39 @@ def _coerce_choice_score(raw_score):
                 return None
         return score if 0 <= score <= 100 else None
 
+    @staticmethod
+    def _find_cycle_node_ids(nodes):
+        """
+        Return node IDs that participate in a directed cycle.
+        """
+        state = {}
+        stack = []
+        cycle_node_ids = set()
+
+        def visit(node_id):
+            state[node_id] = 1
+            stack.append(node_id)
+            node = nodes.get(node_id, {})
+            for choice in node.get("choices", []) or []:
+                target_node_id = choice.get("target_node_id")
+                if target_node_id not in nodes:
+                    continue
+                target_state = state.get(target_node_id, 0)
+                if target_state == 0:
+                    visit(target_node_id)
+                elif target_state == 1:
+                    if target_node_id in stack:
+                        cycle_start_index = stack.index(target_node_id)
+                        cycle_node_ids.update(stack[cycle_start_index:])
+            stack.pop()
+            state[node_id] = 2
+
+        for node_id in nodes:
+            if state.get(node_id, 0) == 0:
+                visit(node_id)
+
+        return cycle_node_ids
+
     def get_current_node(self) -> Optional[dict[str, Any]]:
         """
         Get the learner's current node.
@@ -247,6 +280,14 @@ def validate_scenario(self):
                 if not self.get_node(choice["target_node_id"]):
                     errors.append(f"Invalid target {choice['target_node_id']} in node {node['id']}")
 
+        cycle_node_ids = self._find_cycle_node_ids(nodes)
+        if cycle_node_ids:
+            sorted_cycle_ids = ", ".join(sorted(cycle_node_ids))
+            errors.append(
+                f"Circular path detected in nodes: {sorted_cycle_ids}. "
+                "Remove one of the links in this loop."
+            )
+
         return errors
 
     def publish_grade(self):
@@ -605,6 +646,22 @@ def studio_submit(self, data, suffix=''):
 
         # 3) Persist scenario_data & settings
         nodes_dict = {node['id']: node for node in final}
+        cycle_node_ids = self._find_cycle_node_ids(nodes_dict)
+        if cycle_node_ids:
+            sorted_cycle_ids = ", ".join(sorted(cycle_node_ids))
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {
+                    "nodes_json": [
+                        (
+                            "Circular path detected in nodes: "
+                            f"{sorted_cycle_ids}. Remove one of the links in this loop."
+                        )
+                    ]
+                }
+            }
+
         self.scenario_data = {
             'nodes': nodes_dict,
             'start_node_id': final[0]['id'] if final else None
diff --git a/branching_xblock/static/handlebars/node-editor.handlebars b/branching_xblock/static/handlebars/node-editor.handlebars
index 3db13ca..3d026a7 100644
--- a/branching_xblock/static/handlebars/node-editor.handlebars
+++ b/branching_xblock/static/handlebars/node-editor.handlebars
@@ -3,7 +3,9 @@
     <div class="bx-node-error-banner" role="alert">
       <span class="fa fa-exclamation-circle bx-node-error-banner__icon" aria-hidden="true"></span>
       <div class="bx-node-error-banner__content">
-        <div class="bx-node-error-banner__title">You can't delete this node</div>
+        <div class="bx-node-error-banner__title">
+          {{#if node_error_title}}{{node_error_title}}{{else}}You can't delete this node{{/if}}
+        </div>
         <div class="bx-node-error-banner__detail">{{node_error_detail}}</div>
       </div>
     </div>
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index d762c79..e698852 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -32,8 +32,48 @@ function BranchingStudioEditor(runtime, element, data) {
     showDeleteValidationErrors: false,
     showFieldValidationErrors: false,
     validationFieldErrorsByNodeId: new Map(),
+    validationNodeErrorTitlesById: new Map(),
   };
 
+  function findCycleNodeIds(nodes) {
+    const state = new Map();
+    const stack = [];
+    const cycleNodeIds = new Set();
+    const nodeById = new Map(nodes.map(node => [node.id, node]));
+
+    function visit(nodeId) {
+      state.set(nodeId, 1);
+      stack.push(nodeId);
+      const node = nodeById.get(nodeId);
+      (node?.choices || []).forEach((choice) => {
+        const targetNodeId = (choice?.target_node_id || '').trim();
+        if (!targetNodeId || !nodeById.has(targetNodeId)) {
+          return;
+        }
+        const targetState = state.get(targetNodeId) || 0;
+        if (targetState === 0) {
+          visit(targetNodeId);
+          return;
+        }
+        if (targetState === 1) {
+          const cycleStartIndex = stack.indexOf(targetNodeId);
+          if (cycleStartIndex >= 0) {
+            stack.slice(cycleStartIndex).forEach(cycleId => cycleNodeIds.add(cycleId));
+          }
+        }
+      });
+      stack.pop();
+      state.set(nodeId, 2);
+    }
+
+    nodes.forEach((node) => {
+      if ((state.get(node.id) || 0) === 0) {
+        visit(node.id);
+      }
+    });
+    return cycleNodeIds;
+  }
+
   function loadState() {
       return $.ajax({
         type: 'POST',
@@ -134,6 +174,7 @@ function BranchingStudioEditor(runtime, element, data) {
     const errors = [];
     const seenErrors = new Set();
     const nodeErrorDetailsById = new Map();
+    const nodeErrorTitlesById = new Map();
     const nodeErrorIds = new Set();
     const fieldErrorsByNodeId = new Map();
     const pendingDeleteIds = new Set(pendingDeleteNodes().map(node => node.id));
@@ -168,6 +209,7 @@ function BranchingStudioEditor(runtime, element, data) {
         nodeErrorIds.add(sourceNode.id);
         nodeErrorIds.add(targetNodeId);
         if (!nodeErrorDetailsById.has(targetNodeId)) {
+          nodeErrorTitlesById.set(targetNodeId, "You can't delete this node");
           if (sourceNumber && targetNumber) {
             nodeErrorDetailsById.set(
               targetNodeId,
@@ -214,7 +256,34 @@ function BranchingStudioEditor(runtime, element, data) {
       }
     });
 
-    return { errors, nodeErrorIds, nodeErrorDetailsById, fieldErrorsByNodeId };
+    const cycleNodeIds = findCycleNodeIds(active);
+    if (cycleNodeIds.size > 0) {
+      const cycleNodeNumbers = Array.from(cycleNodeIds)
+        .map(nodeId => nodeNumberById(nodeId))
+        .filter(number => number !== null)
+        .sort((a, b) => a - b);
+      const cycleNodeLabel = cycleNodeNumbers.length
+        ? cycleNodeNumbers.map(number => `Node ${number}`).join(', ')
+        : 'one or more nodes';
+
+      errors.push(
+        `Circular path detected: ${cycleNodeLabel} links back through branching choices. Remove one of the links in this loop.`
+      );
+      cycleNodeIds.forEach((nodeId) => {
+        nodeErrorIds.add(nodeId);
+        if (!nodeErrorDetailsById.has(nodeId)) {
+          const nodeNumber = nodeNumberById(nodeId);
+          const prefix = nodeNumber ? `Node ${nodeNumber}` : 'This node';
+          nodeErrorTitlesById.set(nodeId, 'Circular path detected');
+          nodeErrorDetailsById.set(
+            nodeId,
+            `${prefix} links back through branching choices. Remove one of the links in this loop.`
+          );
+        }
+      });
+    }
+
+    return { errors, nodeErrorIds, nodeErrorDetailsById, nodeErrorTitlesById, fieldErrorsByNodeId };
   }
 
   function updateFooterUi() {
@@ -238,6 +307,7 @@ function BranchingStudioEditor(runtime, element, data) {
       wizard.validationErrors = validation.errors;
       wizard.validationNodeErrorIds = validation.nodeErrorIds;
       wizard.validationNodeErrorDetailsById = validation.nodeErrorDetailsById;
+      wizard.validationNodeErrorTitlesById = validation.nodeErrorTitlesById;
       wizard.validationFieldErrorsByNodeId = validation.fieldErrorsByNodeId;
       const generalErrors = validation.errors.filter(msg => msg === 'At least one active node is required.');
       if (wizard.currentStep === 'nodes' && generalErrors.length) {
@@ -257,6 +327,7 @@ function BranchingStudioEditor(runtime, element, data) {
       wizard.validationErrors = [];
       wizard.validationNodeErrorIds = new Set();
       wizard.validationNodeErrorDetailsById = new Map();
+      wizard.validationNodeErrorTitlesById = new Map();
       wizard.validationFieldErrorsByNodeId = new Map();
       $saveValidationSummary.attr('hidden', true).text('');
       $errors.empty();
@@ -337,6 +408,7 @@ function BranchingStudioEditor(runtime, element, data) {
       has_choices: hasChoices,
       no_branches: noBranches,
       is_pending_delete: Boolean(node.pending_delete),
+      node_error_title: wizard.validationNodeErrorTitlesById?.get(node.id) || '',
       node_error_detail: wizard.validationNodeErrorDetailsById?.get(node.id) || '',
       left_image_url_error: currentNodeFieldErrors.left_image_url || '',
       left_image_url: leftImageUrl,

From cd5b7c65a84b80cbb4de2d805da1c0fc68d69543 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Fri, 13 Feb 2026 11:16:11 -0500
Subject: [PATCH 20/32] feat: compute maximum attainable score in scenario

Using topo+dp to find max path sum
---
 branching_xblock/branching_xblock.py | 91 +++++++++++++++++++++++++++-
 1 file changed, 90 insertions(+), 1 deletion(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 27ac4ce..f6ad1d7 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -3,6 +3,7 @@
 import logging
 import os
 import uuid
+from collections import deque
 from typing import Any, Optional
 
 from web_fragments.fragment import Fragment
@@ -224,6 +225,91 @@ def visit(node_id):
 
         return cycle_node_ids
 
+    def _compute_max_attainable_score(self, nodes, start_node_id):
+        """
+        Compute the maximum total score over all reachable start-to-leaf paths.
+        """
+        if not start_node_id or start_node_id not in nodes:
+            return 0.0
+
+        # Phase 1: collect only nodes reachable from the start node.
+        # This intentionally ignores orphan/disconnected nodes so they do not
+        # affect the grade denominator.
+        reachable = set()
+        pending = deque([start_node_id])
+        while pending:
+            node_id = pending.popleft()
+            if node_id in reachable:
+                continue
+            reachable.add(node_id)
+            node = nodes.get(node_id, {})
+            for choice in node.get("choices", []) or []:
+                target_node_id = choice.get("target_node_id")
+                if target_node_id in nodes and target_node_id not in reachable:
+                    pending.append(target_node_id)
+
+        # Phase 2: compute indegree on the reachable subgraph only.
+        # We use indegree + queue to process nodes in topological order,
+        # which is valid because cycles are blocked by save-time validation.
+        indegree = {node_id: 0 for node_id in reachable}
+        for node_id in reachable:
+            node = nodes.get(node_id, {})
+            for choice in node.get("choices", []) or []:
+                target_node_id = choice.get("target_node_id")
+                if target_node_id in reachable:
+                    indegree[target_node_id] += 1
+
+        topo_queue = deque([node_id for node_id, degree in indegree.items() if degree == 0])
+        # best[node_id] stores the highest score found so far to reach node_id.
+        # We seed start at 0 and then relax outgoing edges.
+        best = {node_id: None for node_id in reachable}
+        best[start_node_id] = 0
+
+        while topo_queue:
+            node_id = topo_queue.popleft()
+            node_score = best[node_id]
+            node = nodes.get(node_id, {})
+
+            for choice in node.get("choices", []) or []:
+                target_node_id = choice.get("target_node_id")
+                if target_node_id not in reachable:
+                    continue
+
+                choice_score = self._coerce_choice_score(choice.get("score", 0))
+                choice_score = 0 if choice_score is None else choice_score
+                if node_score is not None:
+                    # Dynamic-programming relaxation:
+                    # if this path gives a higher total for target, keep it.
+                    candidate = node_score + choice_score
+                    prev_best = best[target_node_id]
+                    best[target_node_id] = candidate if prev_best is None else max(prev_best, candidate)
+
+                indegree[target_node_id] -= 1
+                if indegree[target_node_id] == 0:
+                    topo_queue.append(target_node_id)
+
+        # Phase 3: evaluate only leaf nodes (no outgoing reachable targets).
+        # Max attainable score is defined as best start->leaf path sum.
+        leaf_scores = []
+        for node_id in reachable:
+            node = nodes.get(node_id, {})
+            outgoing_targets = [
+                choice.get("target_node_id")
+                for choice in (node.get("choices", []) or [])
+                if choice.get("target_node_id") in reachable
+            ]
+            if not outgoing_targets and best[node_id] is not None:
+                leaf_scores.append(best[node_id])
+
+        # Defensive fallback: if no reachable leaf is detected, return the best
+        # finite score encountered (or 0). This keeps behavior predictable even
+        # for malformed graph edge-cases.
+        if not leaf_scores:
+            finite_scores = [score for score in best.values() if score is not None]
+            return float(max(finite_scores)) if finite_scores else 0.0
+
+        return float(max(leaf_scores))
+
     def get_current_node(self) -> Optional[dict[str, Any]]:
         """
         Get the learner's current node.
@@ -669,7 +755,10 @@ def studio_submit(self, data, suffix=''):
         self.enable_undo = bool(payload.get('enable_undo', self.enable_undo))
         self.enable_scoring = bool(payload.get('enable_scoring', self.enable_scoring))
         self.enable_reset_activity = bool(payload.get('enable_reset_activity', self.enable_reset_activity))
-        self.max_score = float(payload.get('max_score', self.max_score))
+        self.max_score = self._compute_max_attainable_score(
+            nodes_dict,
+            final[0]['id'] if final else None,
+        )
         self.display_name = payload.get('display_name', self.display_name)
         self.background_image_url = background_image_url
         self.background_image_alt_text = background_image_alt_text

From c53152d51c291eb4524e6473705d2506f8786c43 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Fri, 13 Feb 2026 13:27:09 -0500
Subject: [PATCH 21/32] feat: Add grade-range slider

---
 branching_xblock/branching_xblock.py          | 102 +++++++++
 branching_xblock/static/css/studio_editor.css | 111 ++++++++++
 .../handlebars/settings-step.handlebars       |   7 +-
 .../static/js/src/studio_editor.js            | 193 ++++++++++++++++++
 4 files changed, 412 insertions(+), 1 deletion(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index f6ad1d7..5c27d82 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -99,6 +99,15 @@ class BranchingXBlock(XBlock):
         help="Score awarded when scenario is completed (if scoring enabled)"
     )
 
+    grade_ranges = List(
+        default=[
+            {"label": "Fail", "start": 0, "end": 49},
+            {"label": "Pass", "start": 50, "end": 100},
+        ],
+        scope=Scope.content,
+        help="Grade range segments for end-of-activity grade report"
+    )
+
     current_node_id = String(
         scope=Scope.user_state,
         default=None,
@@ -310,6 +319,86 @@ def _compute_max_attainable_score(self, nodes, start_node_id):
 
         return float(max(leaf_scores))
 
+    @staticmethod
+    def _default_grade_ranges():
+        return [
+            {"label": "Fail", "start": 0, "end": 49},
+            {"label": "Pass", "start": 50, "end": 100},
+        ]
+
+    @staticmethod
+    def _validate_grade_ranges(grade_ranges):
+        if not isinstance(grade_ranges, list) or len(grade_ranges) < 2:
+            return "Grade ranges must contain at least two contiguous segments."
+
+        expected_start = 0
+        for index, grade_range in enumerate(grade_ranges):
+            if not isinstance(grade_range, dict):
+                return f"Grade range {index + 1} is invalid."
+
+            start = grade_range.get("start")
+            end = grade_range.get("end")
+            label = str(grade_range.get("label", "")).strip()
+
+            if label == "":
+                return f"Grade range {index + 1} label is required."
+            if not isinstance(start, int) or not isinstance(end, int):
+                return f"Grade range {index + 1} bounds must be integers."
+            if start < 0 or end > 100:
+                return f"Grade range {index + 1} bounds must be between 0 and 100."
+            if end < start:
+                return f"Grade range {index + 1} has invalid bounds."
+            if start != expected_start:
+                return f"Grade range {index + 1} must start at {expected_start}."
+
+            expected_start = end + 1
+
+        if grade_ranges[-1]["end"] != 100:
+            return "Final grade range must end at 100."
+        return None
+
+    def _normalize_grade_ranges(self, raw_grade_ranges, strict=False):
+        defaults = self._default_grade_ranges()
+        if not isinstance(raw_grade_ranges, list):
+            if strict:
+                return None, "Grade ranges payload is invalid."
+            return defaults, None
+
+        normalized = []
+        for index, item in enumerate(raw_grade_ranges):
+            if not isinstance(item, dict):
+                if strict:
+                    return None, f"Grade range {index + 1} is invalid."
+                return defaults, None
+
+            label = str(item.get("label", "")).strip()
+            if not label:
+                if strict:
+                    return None, f"Grade range {index + 1} label is required."
+                label = defaults[index]["label"] if index < len(defaults) else f"Grade {index + 1}"
+
+            try:
+                start = int(item.get("start"))
+                end = int(item.get("end"))
+            except (TypeError, ValueError):
+                if strict:
+                    return None, f"Grade range {index + 1} bounds must be integers."
+                return defaults, None
+
+            normalized.append({
+                "label": label,
+                "start": start,
+                "end": end,
+            })
+
+        error = self._validate_grade_ranges(normalized)
+        if error:
+            if strict:
+                return None, error
+            return defaults, None
+
+        return normalized, None
+
     def get_current_node(self) -> Optional[dict[str, Any]]:
         """
         Get the learner's current node.
@@ -445,6 +534,7 @@ def studio_view(self, context=None):
             "enable_scoring": bool(self.enable_scoring),
             "enable_reset_activity": bool(self.enable_reset_activity),
             "max_score":   self.max_score,
+            "grade_ranges": self._normalize_grade_ranges(self.grade_ranges)[0],
             "display_name": self.display_name,
             "authoring_help_html": authoring_help_html,
         }
@@ -486,6 +576,7 @@ def _get_state(self):
             "background_image_alt_text": self.background_image_alt_text,
             "background_image_is_decorative": bool(self.background_image_is_decorative),
             "max_score":       self.max_score,
+            "grade_ranges":    self._normalize_grade_ranges(self.grade_ranges)[0],
             "display_name":    self.display_name,
             "current_node":    self.get_current_node(),
             "history":         list(self.history),
@@ -590,6 +681,10 @@ def studio_submit(self, data, suffix=''):
         background_image_url = (payload.get('background_image_url') or '').strip()
         background_image_alt_text = (payload.get('background_image_alt_text') or '').strip()
         background_image_is_decorative = bool(payload.get('background_image_is_decorative', False))
+        grade_ranges, grade_ranges_error = self._normalize_grade_ranges(
+            payload.get('grade_ranges', self.grade_ranges),
+            strict=True,
+        )
 
         if background_image_url and not background_image_is_decorative and not background_image_alt_text:
             return {
@@ -597,6 +692,12 @@ def studio_submit(self, data, suffix=''):
                 "message": "Validation errors",
                 "field_errors": {"nodes_json": ["Background image alt text is required unless the image is marked decorative."]}
             }
+        if grade_ranges_error:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {"nodes_json": [grade_ranges_error]}
+            }
 
         # 1) Assign real IDs and build id_map
         id_map = {}
@@ -763,6 +864,7 @@ def studio_submit(self, data, suffix=''):
         self.background_image_url = background_image_url
         self.background_image_alt_text = background_image_alt_text
         self.background_image_is_decorative = background_image_is_decorative
+        self.grade_ranges = grade_ranges
 
         # 4) Validate & respond
         errors = self.validate_scenario()
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index c1e1274..a07a17c 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -128,6 +128,117 @@
     margin: 2px 0 8px;
 }
 
+.bx-grade-range {
+    margin: 14px 0 18px;
+    max-width: 700px;
+    border: 1px solid #d8dde3;
+    background: #f8f9fa;
+    padding: 10px 12px 12px;
+    border-radius: 4px;
+}
+
+.bx-grade-range__title {
+    margin: 0 0 4px;
+    font-size: 14px;
+    font-weight: 600;
+    line-height: 1.3;
+    color: #303842;
+}
+
+.bx-settings-step .bx-grade-range__title {
+    padding-top: 0;
+    margin-top: 0;
+}
+
+.bx-grade-range__help {
+    margin: 0 0 6px;
+    font-size: 12px;
+    line-height: 1.35;
+    color: #5b6570;
+}
+
+.bx-grade-range__track-wrap {
+    width: 100%;
+}
+
+.bx-grade-range__track {
+    position: relative;
+    height: 36px;
+    border: 1px solid #a9b4bf;
+    border-radius: 2px;
+    overflow: hidden;
+    background: #fff;
+    margin-top: 6px;
+}
+
+.bx-grade-range__segment {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: flex-end;
+    padding-right: 10px;
+    gap: 2px;
+    overflow: hidden;
+}
+
+.bx-grade-range__segment--fail {
+    background: #f4c7c3;
+}
+
+.bx-grade-range__segment--pass {
+    background: #c3da8a;
+}
+
+.bx-grade-range__segment-label {
+    font-size: 10px;
+    font-weight: 600;
+    line-height: 1;
+    color: #3f4750;
+}
+
+.bx-grade-range__segment-range {
+    font-size: 9px;
+    font-weight: 500;
+    line-height: 1;
+    color: #4e5965;
+}
+
+.bx-grade-range__ticks {
+    display: flex;
+    justify-content: space-between;
+    margin-top: 8px;
+}
+
+.bx-grade-range__tick {
+    font-size: 10px;
+    line-height: 1;
+    color: #7a8591;
+}
+
+.bx-grade-range__handle {
+    position: absolute;
+    top: 50%;
+    width: 1px;
+    height: 36px;
+    transform: translate(-50%, -50%);
+    border: 0;
+    border-radius: 0;
+    background: #5d6671;
+    cursor: ew-resize;
+    padding: 0;
+    z-index: 2;
+    box-shadow: none;
+}
+
+.bx-grade-range__handle:focus-visible {
+    outline: 2px solid #0a6fb5;
+    outline-offset: 1px;
+}
+
 .bx-nodes-step {
     display: flex;
     gap: 14px;
diff --git a/branching_xblock/static/handlebars/settings-step.handlebars b/branching_xblock/static/handlebars/settings-step.handlebars
index fc76006..d5bb3c2 100644
--- a/branching_xblock/static/handlebars/settings-step.handlebars
+++ b/branching_xblock/static/handlebars/settings-step.handlebars
@@ -21,6 +21,12 @@
     <span>Include a grade report at the end of the activity</span>
   </label>
 
+  <div class="bx-grade-range {{#unless enable_scoring}}is-hidden{{/unless}}" data-role="grade-range-section">
+    <h3 class="bx-section-title bx-grade-range__title">Specify Grade Range</h3>
+    <p class="bx-help bx-grade-range__help">Adjust the scale to set percentage ranges for each grade.</p>
+    <div class="bx-grade-range__slider" data-role="grade-range-slider"></div>
+  </div>
+
   <h3 class="bx-section-title">Background image</h3>
   <p class="bx-help">
     This image will appear in the background of any nodes with “Image” as the media type.
@@ -53,4 +59,3 @@
     />
   </div>
 </div>
-
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index e698852..7b0ef32 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -74,6 +74,124 @@ function BranchingStudioEditor(runtime, element, data) {
     return cycleNodeIds;
   }
 
+  function defaultGradeRanges() {
+    return [
+      { label: 'Fail', start: 0, end: 49 },
+      { label: 'Pass', start: 50, end: 100 },
+    ];
+  }
+
+  function normalizeGradeRanges(rawGradeRanges) {
+    if (!Array.isArray(rawGradeRanges) || rawGradeRanges.length < 2) {
+      return defaultGradeRanges();
+    }
+    const normalized = [];
+    for (let index = 0; index < rawGradeRanges.length; index += 1) {
+      const gradeRange = rawGradeRanges[index] || {};
+      const label = String(gradeRange.label || '').trim() || `Grade ${index + 1}`;
+      const start = Number.parseInt(gradeRange.start, 10);
+      const end = Number.parseInt(gradeRange.end, 10);
+      if (
+        Number.isNaN(start) || Number.isNaN(end) ||
+        start < 0 || end > 100 || end < start
+      ) {
+        return defaultGradeRanges();
+      }
+      normalized.push({ label, start, end });
+    }
+
+    let expectedStart = 0;
+    for (let index = 0; index < normalized.length; index += 1) {
+      const gradeRange = normalized[index];
+      if (gradeRange.start !== expectedStart) {
+        return defaultGradeRanges();
+      }
+      expectedStart = gradeRange.end + 1;
+    }
+    if (normalized[normalized.length - 1].end !== 100) {
+      return defaultGradeRanges();
+    }
+    return normalized;
+  }
+
+  function boundaryBounds(boundaryIndex, gradeRanges) {
+    const lower = boundaryIndex === 0 ? 0 : gradeRanges[boundaryIndex - 1].end + 1;
+    const upper = boundaryIndex === (gradeRanges.length - 2)
+      ? 99
+      : gradeRanges[boundaryIndex + 1].end - 1;
+    return { lower, upper };
+  }
+
+  function setBoundaryValue(boundaryIndex, requestedValue) {
+    const gradeRanges = wizard.draftSettings.grade_ranges || defaultGradeRanges();
+    const current = gradeRanges[boundaryIndex];
+    const next = gradeRanges[boundaryIndex + 1];
+    if (!current || !next) {
+      return;
+    }
+    const { lower, upper } = boundaryBounds(boundaryIndex, gradeRanges);
+    const clamped = Math.max(lower, Math.min(upper, requestedValue));
+    current.end = clamped;
+    next.start = clamped + 1;
+    wizard.draftSettings.grade_ranges = gradeRanges;
+  }
+
+  function renderGradeRangeSlider() {
+    const $section = $stepSettings.find('[data-role="grade-range-section"]');
+    if (!$section.length) {
+      return;
+    }
+    const show = Boolean(wizard.draftSettings.enable_scoring);
+    $section.toggleClass('is-hidden', !show);
+    if (!show) {
+      return;
+    }
+
+    wizard.draftSettings.grade_ranges = normalizeGradeRanges(wizard.draftSettings.grade_ranges);
+    const gradeRanges = wizard.draftSettings.grade_ranges;
+    const percentPerPoint = 100 / 101;
+    const $slider = $section.find('[data-role="grade-range-slider"]').empty();
+    const $trackWrap = $('<div class="bx-grade-range__track-wrap"></div>');
+    const $ticks = $('<div class="bx-grade-range__ticks"></div>');
+    for (let value = 0; value <= 100; value += 10) {
+      $ticks.append($('<span class="bx-grade-range__tick"></span>').text(String(value)));
+    }
+
+    const $track = $('<div class="bx-grade-range__track" data-role="grade-track"></div>');
+    gradeRanges.forEach((gradeRange, index) => {
+      const width = gradeRange.end - gradeRange.start + 1;
+      const isFail = index === 0;
+      const $segment = $('<div class="bx-grade-range__segment"></div>')
+        .toggleClass('bx-grade-range__segment--fail', isFail)
+        .toggleClass('bx-grade-range__segment--pass', !isFail)
+        .css({
+          left: `${gradeRange.start * percentPerPoint}%`,
+          width: `${width * percentPerPoint}%`,
+        });
+      $segment.append($('<div class="bx-grade-range__segment-label"></div>').text(gradeRange.label));
+      $segment.append(
+        $('<div class="bx-grade-range__segment-range"></div>').text(`${gradeRange.start}-${gradeRange.end}`)
+      );
+      $track.append($segment);
+    });
+
+    for (let boundaryIndex = 0; boundaryIndex < gradeRanges.length - 1; boundaryIndex += 1) {
+      const boundaryValue = gradeRanges[boundaryIndex].end;
+      const $handle = $('<button type="button" class="bx-grade-range__handle" data-role="grade-boundary-handle"></button>')
+        .attr('data-boundary-index', boundaryIndex)
+        .attr('role', 'slider')
+        .attr('aria-label', `Grade boundary ${boundaryIndex + 1}`)
+        .attr('aria-valuemin', boundaryBounds(boundaryIndex, gradeRanges).lower)
+        .attr('aria-valuemax', boundaryBounds(boundaryIndex, gradeRanges).upper)
+        .attr('aria-valuenow', boundaryValue)
+        .css('left', `${(boundaryValue + 1) * percentPerPoint}%`);
+      $track.append($handle);
+    }
+
+    $trackWrap.append($track).append($ticks);
+    $slider.append($trackWrap);
+  }
+
   function loadState() {
       return $.ajax({
         type: 'POST',
@@ -127,6 +245,7 @@ function BranchingStudioEditor(runtime, element, data) {
       background_image_url: state?.background_image_url || '',
       background_image_alt_text: state?.background_image_alt_text || '',
       background_image_is_decorative: Boolean(state?.background_image_is_decorative),
+      grade_ranges: normalizeGradeRanges(state?.grade_ranges),
     };
   }
 
@@ -338,6 +457,7 @@ function BranchingStudioEditor(runtime, element, data) {
 
   function renderSettings() {
     $stepSettings.html(Templates['settings-step'](wizard.draftSettings));
+    renderGradeRangeSlider();
   }
 
   function renderNodeList() {
@@ -452,6 +572,7 @@ function BranchingStudioEditor(runtime, element, data) {
     wizard.draftSettings.background_image_url = $s.find('[name="background_image_url"]').val()?.trim() || '';
     wizard.draftSettings.background_image_is_decorative = $s.find('[name="background_image_is_decorative"]').is(':checked');
     wizard.draftSettings.background_image_alt_text = $s.find('[name="background_image_alt_text"]').val()?.trim() || '';
+    wizard.draftSettings.grade_ranges = normalizeGradeRanges(wizard.draftSettings.grade_ranges);
   }
 
   function syncCurrentNodeFromDom() {
@@ -565,6 +686,11 @@ function BranchingStudioEditor(runtime, element, data) {
         background_image_url: wizard.draftSettings.background_image_url || '',
         background_image_alt_text: wizard.draftSettings.background_image_alt_text || '',
         background_image_is_decorative: Boolean(wizard.draftSettings.background_image_is_decorative),
+        grade_ranges: (wizard.draftSettings.grade_ranges || []).map((gradeRange) => ({
+          label: String(gradeRange.label || '').trim(),
+          start: Number.parseInt(gradeRange.start, 10),
+          end: Number.parseInt(gradeRange.end, 10),
+        })),
       };
 
       runtime.notify('save', { state: 'start' });
@@ -604,6 +730,73 @@ function BranchingStudioEditor(runtime, element, data) {
         $alt.val('');
         wizard.draftSettings.background_image_alt_text = '';
       }
+      renderGradeRangeSlider();
+    });
+
+    $root.off('mousedown.bx-grade-range', '[data-role="grade-boundary-handle"]');
+    $root.on('mousedown.bx-grade-range', '[data-role="grade-boundary-handle"]', function(event) {
+      event.preventDefault();
+      const boundaryIndex = Number($(this).attr('data-boundary-index'));
+      if (Number.isNaN(boundaryIndex)) {
+        return;
+      }
+
+      function applyDrag(clientX) {
+        const $track = $stepSettings.find('[data-role="grade-track"]');
+        if (!$track.length) {
+          return;
+        }
+        const bounds = $track[0].getBoundingClientRect();
+        if (bounds.width <= 0) {
+          return;
+        }
+        const ratio = Math.max(0, Math.min(1, (clientX - bounds.left) / bounds.width));
+        const requestedValue = Math.round(ratio * 100);
+        setBoundaryValue(boundaryIndex, requestedValue);
+        renderGradeRangeSlider();
+      }
+
+      function stopDrag() {
+        $(document).off('mousemove.bx-grade-range-drag');
+        $(document).off('mouseup.bx-grade-range-drag');
+      }
+
+      applyDrag(event.clientX);
+      $(document).on('mousemove.bx-grade-range-drag', function(moveEvent) {
+        applyDrag(moveEvent.clientX);
+      });
+      $(document).on('mouseup.bx-grade-range-drag', function() {
+        stopDrag();
+      });
+    });
+
+    $root.off('keydown.bx-grade-range', '[data-role="grade-boundary-handle"]');
+    $root.on('keydown.bx-grade-range', '[data-role="grade-boundary-handle"]', function(event) {
+      const boundaryIndex = Number($(this).attr('data-boundary-index'));
+      if (Number.isNaN(boundaryIndex)) {
+        return;
+      }
+      const gradeRanges = wizard.draftSettings.grade_ranges || defaultGradeRanges();
+      const currentBoundary = gradeRanges[boundaryIndex]?.end;
+      if (typeof currentBoundary !== 'number') {
+        return;
+      }
+      const bounds = boundaryBounds(boundaryIndex, gradeRanges);
+      let nextValue = currentBoundary;
+      if (event.key === 'ArrowLeft' || event.key === 'ArrowDown') {
+        nextValue = currentBoundary - 1;
+      } else if (event.key === 'ArrowRight' || event.key === 'ArrowUp') {
+        nextValue = currentBoundary + 1;
+      } else if (event.key === 'Home') {
+        nextValue = bounds.lower;
+      } else if (event.key === 'End') {
+        nextValue = bounds.upper;
+      } else {
+        return;
+      }
+      event.preventDefault();
+      setBoundaryValue(boundaryIndex, nextValue);
+      renderGradeRangeSlider();
     });
 
     $root.off('click.bx-nodes', '[data-role="add-node"]');

From 549df1b1ed9ab67563e870e1c5f406fc6c10d19e Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Tue, 17 Feb 2026 13:39:44 -0500
Subject: [PATCH 22/32] feat: Final grade report

---
 branching_xblock/branching_xblock.py          |  59 +++
 .../static/css/branching_xblock.css           | 339 +++++++++++++++++-
 .../static/html/branching_xblock.html         |  59 +++
 .../static/js/src/branching_xblock.js         |  96 ++++-
 4 files changed, 549 insertions(+), 4 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 5c27d82..c60cacb 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -132,6 +132,12 @@ class BranchingXBlock(XBlock):
         help="Awarded points per selected choice, used for undo/reset"
     )
 
+    choice_history = List(
+        scope=Scope.user_state,
+        default=[],
+        help="Selected choice records used for final report details"
+    )
+
     has_completed = Boolean(
         scope=Scope.user_state,
         default=False,
@@ -399,6 +405,49 @@ def _normalize_grade_ranges(self, raw_grade_ranges, strict=False):
 
         return normalized, None
 
+    def _build_grade_report(self):
+        """
+        Compute learner-facing grade report data from current score state.
+        """
+        normalized_ranges, _ = self._normalize_grade_ranges(self.grade_ranges)
+        safe_ranges = normalized_ranges or self._default_grade_ranges()
+
+        max_score = float(self.max_score or 0.0)
+        current_score = max(0.0, float(self.score or 0.0))
+        percentage = 0.0
+        if max_score > 0.0:
+            percentage = (current_score / max_score) * 100.0
+        percentage = max(0.0, min(100.0, percentage))
+        rounded_percentage = int(round(percentage))
+
+        matched_index = 0
+        matched_range = safe_ranges[0]
+        for index, grade_range in enumerate(safe_ranges):
+            if grade_range["start"] <= rounded_percentage <= grade_range["end"]:
+                matched_index = index
+                matched_range = grade_range
+                break
+
+        detailed_scores = []
+        for entry in (self.choice_history or []):
+            choice_text = str(entry.get("choice_text", "")).strip()
+            if not choice_text:
+                continue
+            points = self._coerce_choice_score(entry.get("awarded_points", 0))
+            detailed_scores.append({
+                "choice_text": choice_text,
+                "awarded_points": points if points is not None else 0,
+            })
+
+        return {
+            "score": current_score,
+            "max_score": max_score,
+            "percentage": rounded_percentage,
+            "grade_label": matched_range.get("label", ""),
+            "is_pass_style": matched_index != 0,
+            "detailed_scores": detailed_scores,
+        }
+
     def get_current_node(self) -> Optional[dict[str, Any]]:
         """
         Get the learner's current node.
@@ -581,8 +630,10 @@ def _get_state(self):
             "current_node":    self.get_current_node(),
             "history":         list(self.history),
             "score_history":   list(self.score_history),
+            "choice_history":  list(self.choice_history),
             "has_completed":   bool(self.has_completed),
             "score":           self.score,
+            "grade_report":    self._build_grade_report(),
         }
 
     @XBlock.json_handler
@@ -618,6 +669,11 @@ def select_choice(self, data, suffix=''):
                 awarded_points = 0
             self.score += awarded_points
             self.score_history.append(float(awarded_points))
+            self.choice_history.append({
+                "source_node_id": self.current_node_id,
+                "choice_text": (choice.get("text") or "").strip(),
+                "awarded_points": awarded_points,
+            })
 
         if self.enable_undo:
             self.history.append(self.current_node_id)
@@ -644,6 +700,8 @@ def undo_choice(self, data, suffix=''):
         if self.enable_scoring:
             awarded_points = self.score_history.pop() if self.score_history else 0.0
             self.score = max(0.0, self.score - awarded_points)
+            if self.choice_history:
+                self.choice_history.pop()
             self.publish_grade()
 
         self.has_completed = False
@@ -663,6 +721,7 @@ def reset_activity(self, data, suffix=''):
 
         if self.enable_scoring:
             self.score_history = []
+            self.choice_history = []
             self.score = 0.0
             self.publish_grade()
 
diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 59032bf..ba73ac7 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -325,6 +325,23 @@
     background-color: #0c4f83;
 }
 
+.show-report-button {
+    border: none;
+    background-color: #0f62a1;
+    color: #fff;
+    border-radius: 6px;
+    padding: 0.7rem 1.5rem;
+    font-size: 1rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: background-color 0.2s ease;
+}
+
+.show-report-button:hover,
+.show-report-button:focus {
+    background-color: #0c4f83;
+}
+
 .undo-button {
     border: 1px solid #4a5568;
     border-radius: 4px;
@@ -367,6 +384,274 @@
     font-size: small;
 }
 
+.grade-report {
+    margin: 1.5rem auto;
+    max-width: 1082px;
+    border-radius: 6px;
+    background: #001731;
+    color: #ffffff;
+    padding: 2rem;
+}
+
+.grade-report__title {
+    margin: 0 0 0.25rem;
+    font-size: 1.375rem;
+    line-height: 1.27;
+    font-weight: 700;
+    color: #ffffff;
+}
+
+.grade-report__subtitle {
+    margin: 0 0 1.5rem;
+    color: #ffffff;
+    font-size: 0.875rem;
+    line-height: 1.7;
+}
+
+.grade-report__summary-card {
+    background: #ffffff;
+    border-radius: 14px;
+    padding: 1.75rem 1.9rem 1.65rem;
+    margin-bottom: 1.85rem;
+}
+
+.grade-report__section-title {
+    margin: 0 0 1.2rem;
+    font-size: 1.375rem;
+    line-height: 1.27;
+    font-weight: 700;
+    color: #3b3a3a;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.7rem;
+}
+
+.grade-report__section-icon {
+    width: 38px;
+    height: 38px;
+    border-radius: 999px;
+    background: #d6e1df;
+    color: #3f4346;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.grade-report__section-icon .fa {
+    width: 22px;
+    height: 22px;
+    font-size: 22px;
+    line-height: 1;
+}
+
+.grade-report__summary {
+    display: grid;
+    grid-template-columns: 1fr 1fr 260px;
+    gap: 1.6rem;
+    align-items: center;
+    min-height: 0;
+}
+
+.grade-report__metric {
+    background: #ffffff;
+    color: #1f2a37;
+    border-radius: 12px;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.15), 0 1px 4px rgba(0, 0, 0, 0.15);
+    padding: 1.35rem 1.5rem;
+    min-height: 148px;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+}
+
+.grade-report__metric--score {
+    --report-score-color: #15803d;
+    background: #f2faf7;
+}
+
+.grade-report__metric--max {
+    background: #f2f1f1;
+}
+
+.grade-report__metric-label {
+    font-size: 0.875rem;
+    line-height: 1.35;
+    color: #454545;
+    margin-bottom: 0.65rem;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.35rem;
+}
+
+.grade-report__metric-label-icon {
+    width: 0.95rem;
+    height: 0.95rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: #7a7a7a;
+}
+
+.grade-report__metric-label-icon .fa {
+    font-size: 0.95rem;
+    line-height: 1;
+}
+
+.grade-report__metric-value {
+    font-size: 3.125rem;
+    line-height: 1.1;
+    font-weight: 700;
+}
+
+.grade-report__metric--score .grade-report__metric-value {
+    color: var(--report-score-color);
+}
+
+.grade-report__metric--score.is-fail {
+    --report-score-color: #b91c1c;
+    background: #fcf1f4;
+}
+
+.grade-report__metric--score .grade-report__metric-label-icon {
+    color: var(--report-score-color);
+}
+
+.grade-report__metric--max .grade-report__metric-value {
+    color: #4b5563;
+}
+
+.grade-report__percent {
+    --report-percent-color: #15803d;
+    width: 210px;
+    height: 210px;
+    border-radius: 999px;
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--report-percent-color);
+    border: none;
+}
+
+.grade-report__percent.is-fail {
+    --report-percent-color: #b91c1c;
+}
+
+.grade-report__percent-ring {
+    width: 100%;
+    height: 100%;
+    transform: rotate(-90deg);
+}
+
+.grade-report__percent-track,
+.grade-report__percent-progress {
+    fill: none;
+    stroke-width: 7;
+}
+
+.grade-report__percent-track {
+    stroke: #d6ddde;
+}
+
+.grade-report__percent-progress {
+    stroke: var(--report-percent-color);
+    stroke-linecap: round;
+    transition: stroke-dashoffset 0.2s ease;
+}
+
+.grade-report__percent-content {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+}
+
+.grade-report__percent-value {
+    font-size: 3.75rem;
+    line-height: 1;
+    font-weight: 700;
+    letter-spacing: -0.02em;
+}
+
+.grade-report__percent-label {
+    font-size: 0.875rem;
+    line-height: 1.35;
+    margin-top: 0.35rem;
+    color: #3f3d3d;
+}
+
+.grade-report__details {
+    background: #ffffff;
+    color: #1f2a37;
+    border-radius: 14px;
+    padding: 1.4rem 1.2rem 1.15rem;
+    margin-bottom: 1.6rem;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.15), 0 1px 4px rgba(0, 0, 0, 0.15);
+}
+
+.grade-report__details-title {
+    margin: 0 0 1.1rem;
+    font-size: 1.375rem;
+    line-height: 1.27;
+    font-weight: 700;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.7rem;
+}
+
+.grade-report__details-header,
+.grade-report__details-row {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 1rem;
+    align-items: start;
+}
+
+.grade-report__details-header {
+    font-size: 0.875rem;
+    line-height: 1.35;
+    color: #000000;
+    font-weight: 700;
+    padding: 0.45rem 1rem;
+    background: #f2f0ef;
+    border-bottom: none;
+    border-radius: 2px;
+}
+
+.grade-report__details-row {
+    font-size: 0.875rem;
+    line-height: 1.7;
+    padding: 0.62rem 1rem;
+    border-bottom: 1px solid #f2f0ef;
+}
+
+.grade-report__details-row:last-child {
+    border-bottom: none;
+}
+
+.grade-report__details-score {
+    font-weight: 500;
+    font-size: 0.75rem;
+    line-height: 1.67;
+    background: #e1dddb;
+    color: #000000;
+    border-radius: 6px;
+    min-width: 54px;
+    text-align: center;
+    padding: 0.15rem 0.7rem;
+}
+
+.grade-report__details-row--empty {
+    display: block;
+    color: #6b7280;
+}
+
+.grade-report [data-role="reset-activity-report"] {
+    margin-top: 0.35rem;
+}
+
 @media (max-width: 600px) {
     .branching-scenario .choice-actions {
         flex-direction: column-reverse;
@@ -375,8 +660,60 @@
 
     .undo-button,
     .reset-button,
-    .choice-submit-button {
+    .choice-submit-button,
+    .show-report-button {
         width: 100%;
         text-align: center;
     }
+
+    .grade-report__summary {
+        grid-template-columns: 1fr;
+    }
+
+    .grade-report__percent {
+        width: 150px;
+        height: 150px;
+        margin: 0 auto;
+    }
+
+    .grade-report {
+        padding: 1.1rem;
+    }
+
+    .grade-report__metric-value {
+        font-size: 2.3rem;
+    }
+
+    .grade-report__percent-value {
+        font-size: 2.5rem;
+    }
+
+    .grade-report__title {
+        font-size: 1.8rem;
+    }
+
+    .grade-report__subtitle {
+        font-size: 0.95rem;
+    }
+
+    .grade-report__section-title,
+    .grade-report__details-title {
+        font-size: 1.2rem;
+    }
+
+    .grade-report__metric-label,
+    .grade-report__details-header,
+    .grade-report__details-row {
+        font-size: 1rem;
+    }
+
+    .grade-report__details-score {
+        font-size: 0.85rem;
+        min-width: 36px;
+    }
+
+    .grade-report__percent-label {
+        font-size: 1.1rem;
+    }
+
 }
diff --git a/branching_xblock/static/html/branching_xblock.html b/branching_xblock/static/html/branching_xblock.html
index 47dd381..4f7b79c 100644
--- a/branching_xblock/static/html/branching_xblock.html
+++ b/branching_xblock/static/html/branching_xblock.html
@@ -22,6 +22,9 @@ <h3 class="choices-heading" data-role="choice-heading">Choose Next Step:</h3>
                     <button type="button" class="reset-button action-secondary btn-secondary" data-role="reset-activity" style="display: none;">
                         Reset
                     </button>
+                    <button type="button" class="show-report-button action-primary btn-primary" data-role="show-report" style="display: none;">
+                        Show Report
+                    </button>
                     <button type="submit" class="choice-submit-button action-primary btn-primary" data-role="submit-choice" disabled>
                         Submit
                     </button>
@@ -30,5 +33,61 @@ <h3 class="choices-heading" data-role="choice-heading">Choose Next Step:</h3>
         </div>
 
         <div class="score-display" data-role="score" style="display: none;"></div>
+        <div class="grade-report" data-role="grade-report" hidden>
+            <h3 class="grade-report__title">Activity Complete!</h3>
+            <p class="grade-report__subtitle">Let's take a look at this report below to see how you performed.</p>
+
+            <div class="grade-report__summary-card">
+                <h4 class="grade-report__section-title">
+                    <span class="grade-report__section-icon" aria-hidden="true">
+                        <span class="fa fa-graduation-cap" aria-hidden="true"></span>
+                    </span>
+                    Your Grade
+                </h4>
+                <div class="grade-report__summary">
+                    <div class="grade-report__metric grade-report__metric--score">
+                        <div class="grade-report__metric-label">
+                            <span class="grade-report__metric-label-icon" aria-hidden="true">
+                                <span class="fa fa-trophy" data-role="report-score-icon" aria-hidden="true"></span>
+                            </span>
+                            Your Score
+                        </div>
+                        <div class="grade-report__metric-value" data-role="report-score">0</div>
+                    </div>
+                    <div class="grade-report__metric grade-report__metric--max">
+                        <div class="grade-report__metric-label">Highest Possible Score</div>
+                        <div class="grade-report__metric-value" data-role="report-max-score">0</div>
+                    </div>
+                    <div class="grade-report__percent" data-role="report-percent-pill">
+                        <svg class="grade-report__percent-ring" viewBox="0 0 120 120" aria-hidden="true" focusable="false">
+                            <circle class="grade-report__percent-track" cx="60" cy="60" r="48"></circle>
+                            <circle class="grade-report__percent-progress" data-role="report-percent-circle" cx="60" cy="60" r="48"></circle>
+                        </svg>
+                        <div class="grade-report__percent-content">
+                            <div class="grade-report__percent-value" data-role="report-percent">0%</div>
+                            <div class="grade-report__percent-label" data-role="report-grade-label"></div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            <div class="grade-report__details">
+                <h4 class="grade-report__details-title">
+                    <span class="grade-report__section-icon" aria-hidden="true">
+                        <span class="fa fa-line-chart" aria-hidden="true"></span>
+                    </span>
+                    Detailed Score
+                </h4>
+                <div class="grade-report__details-header">
+                    <span>Your Selections</span>
+                    <span>Score</span>
+                </div>
+                <div class="grade-report__details-rows" data-role="report-details"></div>
+            </div>
+
+            <button type="button" class="action-primary btn-primary" data-role="reset-activity-report" style="display: none;">
+                Reset Activity
+            </button>
+        </div>
     </div>
 </div>
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index a01d5cb..40df02d 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -4,6 +4,7 @@ function BranchingXBlock(runtime, element) {
     let currentHintNodeId = null;
     let isHintVisible = false;
     let selectedChoiceIndex = null;
+    let isReportVisible = false;
 
     const MEDIA_FILE_REGEX = /\.(mp4|webm|ogg|mp3|wav)(\?|#|$)/i;
 
@@ -82,6 +83,61 @@ function BranchingXBlock(runtime, element) {
         }
     }
 
+    function renderGradeReport(reportData, showResetInReport) {
+        const $report = $el.find('[data-role="grade-report"]');
+        const score = Number(reportData?.score || 0);
+        const maxScore = Number(reportData?.max_score || 0);
+        const percentage = Number(reportData?.percentage || 0);
+        const gradeLabel = String(reportData?.grade_label || '').trim();
+        const isPassStyle = Boolean(reportData?.is_pass_style);
+        const details = Array.isArray(reportData?.detailed_scores) ? reportData.detailed_scores : [];
+
+        $report.find('[data-role="report-score"]').text(String(Math.round(score)));
+        $report.find('[data-role="report-max-score"]').text(String(Math.round(maxScore)));
+        $report.find('[data-role="report-percent"]').text(`${percentage}%`);
+        $report.find('[data-role="report-grade-label"]').text(gradeLabel);
+        const boundedPercentage = Math.max(0, Math.min(100, percentage));
+        const $percentPill = $report.find('[data-role="report-percent-pill"]');
+        $percentPill
+            .toggleClass('is-fail', !isPassStyle);
+        const $scoreMetric = $report.find('.grade-report__metric--score');
+        $scoreMetric
+            .toggleClass('is-fail', !isPassStyle);
+        const $scoreIcon = $report.find('[data-role="report-score-icon"]');
+        $scoreIcon
+            .toggleClass('fa-trophy', isPassStyle)
+            .toggleClass('fa-exclamation-triangle', !isPassStyle);
+        const $percentCircle = $report.find('[data-role="report-percent-circle"]');
+        if ($percentCircle.length) {
+            const radius = Number($percentCircle.attr('r')) || 48;
+            const circumference = 2 * Math.PI * radius;
+            const offset = circumference * (1 - (boundedPercentage / 100));
+            $percentCircle.css({
+                strokeDasharray: circumference,
+                strokeDashoffset: offset,
+            });
+        }
+        $report.find('[data-role="reset-activity-report"]').toggle(showResetInReport);
+
+        const $details = $report.find('[data-role="report-details"]').empty();
+        if (!details.length) {
+            $details.append(
+                $('<div class="grade-report__details-row grade-report__details-row--empty"></div>')
+                    .text('No scored selections were recorded for this attempt.')
+            );
+            return;
+        }
+
+        details.forEach((entry) => {
+            const text = String(entry.choice_text || '').trim();
+            const points = Number(entry.awarded_points || 0);
+            const $row = $('<div class="grade-report__details-row"></div>');
+            $row.append($('<span class="grade-report__details-text"></span>').text(text || 'Untitled choice'));
+            $row.append($('<span class="grade-report__details-score"></span>').text(String(points)));
+            $details.append($row);
+        });
+    }
+
     function updateView(state) {
         const node = state.current_node || state.nodes[state.start_node_id] || {};
 
@@ -179,6 +235,7 @@ function BranchingXBlock(runtime, element) {
         if (nodeId !== currentHintNodeId) {
             currentHintNodeId = nodeId;
             isHintVisible = false;
+            isReportVisible = false;
         }
         const $hintContainer = $el.find('[data-role="hint-container"]');
         const $hintDetails = $hintContainer.find('[data-role="hint-collapsible"]');
@@ -226,18 +283,42 @@ function BranchingXBlock(runtime, element) {
             state.current_node && state.current_node.id === state.start_node_id
         );
         const showReset = Boolean(state.enable_reset_activity && !isAtStartNode);
+        const showReport = Boolean(isLeaf && state.enable_scoring);
+        if (!showReport) {
+            isReportVisible = false;
+        }
         $el.find('[data-role="choice-heading"]').toggle(hasChoices);
         $submitButton.toggle(hasChoices);
         $submitButton.prop('disabled', !hasChoices || selectedChoiceIndex === null);
-        $el.find('.choice-actions').toggle(hasChoices || canUndo || showReset);
+        $el.find('[data-role="show-report"]').toggle(showReport);
+        $el.find('.choice-actions').toggle(hasChoices || canUndo || showReset || showReport);
 
         $el.find('.undo-button')
             .prop('disabled', !canUndo)
             .toggleClass('is-disabled', !canUndo);
         $el.find('[data-role="reset-activity"]').toggle(showReset);
 
+        const $report = $el.find('[data-role="grade-report"]');
+        const reportMode = Boolean(showReport && isReportVisible);
+        $report.prop('hidden', !reportMode);
+        if (reportMode) {
+            renderGradeReport(state.grade_report || {}, showReset);
+            $el.find('[data-role="content"]').hide();
+            $el.find('[data-role="media"]').hide();
+            $el.find('[data-role="transcript"]').hide();
+            $el.find('[data-role="hint-container"]').hide();
+            $el.find('[data-role="choices"]').hide();
+            $el.find('[data-role="score"]').hide();
+        } else {
+            $el.find('[data-role="content"]').show();
+            $el.find('[data-role="media"]').show();
+            $el.find('[data-role="transcript"]').show();
+            $el.find('[data-role="hint-container"]').show();
+            $el.find('[data-role="choices"]').show();
+        }
+
         const $score = $el.find('[data-role="score"]');
-        if (isLeaf && state.enable_scoring) {
+        if (!reportMode && isLeaf && state.enable_scoring) {
             $score.text(`Score: ${state.score}/${state.max_score}`).show();
         } else {
             $score.hide();
@@ -260,6 +341,7 @@ function BranchingXBlock(runtime, element) {
 
     $el.on('change', 'input[name="branching-choice"]', function() {
         selectedChoiceIndex = Number(this.value);
+        isReportVisible = false;
         $el.find('[data-role="submit-choice"]').prop('disabled', false);
         $el.find('.choice-option').removeClass('is-selected');
         $(this).closest('.choice-option').addClass('is-selected');
@@ -277,11 +359,13 @@ function BranchingXBlock(runtime, element) {
             contentType: 'application/json'
         }).done(() => {
             selectedChoiceIndex = null;
+            isReportVisible = false;
             refreshView();
         });
     });
 
     $el.on('click', '.undo-button', function() {
+        isReportVisible = false;
         $.ajax({
           url: runtime.handlerUrl(element, 'undo_choice'),
           type: 'POST',
@@ -291,7 +375,13 @@ function BranchingXBlock(runtime, element) {
         }).done(refreshView);
     });
 
-    $el.on('click', '[data-role="reset-activity"]', function() {
+    $el.on('click', '[data-role="show-report"]', function() {
+        isReportVisible = true;
+        refreshView();
+    });
+
+    $el.on('click', '[data-role="reset-activity"], [data-role="reset-activity-report"]', function() {
+        isReportVisible = false;
         $.ajax({
           url: runtime.handlerUrl(element, 'reset_activity'),
           type: 'POST',

From a46658b4de9561fd83873b7b59ad22390a390307 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 19 Feb 2026 10:32:52 -0500
Subject: [PATCH 23/32] fix: clean up + fix regressions

---
 branching_xblock/branching_xblock.py          | 36 +++++--------------
 .../static/css/branching_xblock.css           | 17 +++++++--
 .../static/js/src/branching_xblock.js         | 16 ++++++---
 3 files changed, 34 insertions(+), 35 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index c60cacb..4938128 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -1,6 +1,5 @@
 """Branching Scenario XBlock."""
 import json
-import logging
 import os
 import uuid
 from collections import deque
@@ -15,8 +14,6 @@
 
 resource_loader = ResourceLoader(__name__)
 
-logger = logging.getLogger(__name__)
-
 
 class BranchingXBlock(XBlock):
     """
@@ -461,27 +458,6 @@ def is_end_node(self, node_id):
         node = self.get_node(node_id)
         return bool(node) and not node.get("choices")
 
-    def get_choice(self, node, choice_index):
-        """
-        Validate and return a choice from a node.
-        """
-        try:
-            return node["choices"][choice_index]
-        except (IndexError, KeyError, TypeError):
-            return None
-
-    def can_undo(self):
-        """
-        Check if undo is allowed and possible.
-        """
-        return self.enable_undo and len(self.history) > 0
-
-    def get_previous_node_id(self):
-        """
-        Get last node from history.
-        """
-        return self.history[-1] if self.history else None
-
     def validate_scenario(self):
         """
         Check for common configuration errors.
@@ -719,10 +695,10 @@ def reset_activity(self, data, suffix=''):
         self.history = []
         self.has_completed = False
 
+        self.score_history = []
+        self.choice_history = []
+        self.score = 0.0
         if self.enable_scoring:
-            self.score_history = []
-            self.choice_history = []
-            self.score = 0.0
             self.publish_grade()
 
         self.start_node()
@@ -832,7 +808,11 @@ def studio_submit(self, data, suffix=''):
                 continue
             # filter out completely blank nodes
             has_content = bool(node['content'].strip())
-            has_media = bool(node['media']['url'].strip())
+            has_media = bool(
+                (node['media']['url'] or '').strip()
+                or (node.get('left_image_url', '') or '').strip()
+                or (node.get('right_image_url', '') or '').strip()
+            )
             has_choices = any(
                 (c.get('text', '').strip() or c.get('target_node_id', '').strip())
                 for c in node['choices']
diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index ba73ac7..2c60ebb 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -31,19 +31,29 @@
     width: 100%;
     max-width: 100%;
     border-radius: 0.5rem;
-    background-size: cover;
-    background-position: center;
-    background-repeat: no-repeat;
+    overflow: hidden;
     padding: 0.75rem;
     box-sizing: border-box;
 }
 
+.branching-scenario .bx-image-composite__bg {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    display: block;
+    z-index: 0;
+}
+
 .branching-scenario .bx-image-composite--bg-only {
     padding: 0;
     aspect-ratio: 16 / 9;
 }
 
 .branching-scenario .bx-image-composite__fg {
+    position: relative;
+    z-index: 1;
     display: grid;
     grid-template-columns: repeat(2, minmax(0, 1fr));
     gap: 0.75rem;
@@ -60,6 +70,7 @@
 
 .branching-scenario .bx-image-composite__overlay {
     position: absolute;
+    z-index: 1;
     left: 50%;
     bottom: 1.25rem;
     transform: translateX(-50%);
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index 40df02d..b4c2118 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -149,6 +149,8 @@ function BranchingXBlock(runtime, element) {
         const contentHtml = (node && node.content) || '';
         const overlayEnabled = Boolean(node?.overlay_text && media.type === 'image');
         const backgroundImageUrl = state?.background_image_url || '';
+        const backgroundImageAltText = state?.background_image_alt_text || '';
+        const backgroundImageIsDecorative = Boolean(state?.background_image_is_decorative);
         const leftImageUrl = (node?.left_image_url !== undefined && node?.left_image_url !== null)
             ? node.left_image_url
             : (mediaUrl || '');
@@ -166,7 +168,15 @@ function BranchingXBlock(runtime, element) {
         if (media.type === 'image') {
             const $composite = $('<div>').addClass('bx-image-composite');
             if (backgroundImageUrl) {
-                $composite.css('background-image', `url("${backgroundImageUrl}")`);
+                const $backgroundImage = $('<img>')
+                    .addClass('bx-image-composite__bg')
+                    .attr('src', backgroundImageUrl);
+                if (backgroundImageIsDecorative) {
+                    $backgroundImage.attr('alt', '').attr('aria-hidden', 'true');
+                } else {
+                    $backgroundImage.attr('alt', backgroundImageAltText);
+                }
+                $composite.append($backgroundImage);
             }
 
             const hasForeground = Boolean(leftImageUrl || rightImageUrl);
@@ -279,9 +289,7 @@ function BranchingXBlock(runtime, element) {
         });
         const hasChoices = choices.length > 0;
         const isLeaf = !hasChoices;
-        const isAtStartNode = Boolean(
-            state.current_node && state.current_node.id === state.start_node_id
-        );
+        const isAtStartNode = Boolean(node && node.id === state.start_node_id);
         const showReset = Boolean(state.enable_reset_activity && !isAtStartNode);
         const showReport = Boolean(isLeaf && state.enable_scoring);
         if (!showReport) {

From f797f27c02eb18ad3b7558d68d6a3b2b56cc8e31 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 19 Feb 2026 10:37:58 -0500
Subject: [PATCH 24/32] fix: Add test cases

---
 tests/test_branching_xblock.py | 338 ++++++++++++++++++++++++++++++++-
 1 file changed, 332 insertions(+), 6 deletions(-)

diff --git a/tests/test_branching_xblock.py b/tests/test_branching_xblock.py
index 25b0123..aa98ec1 100644
--- a/tests/test_branching_xblock.py
+++ b/tests/test_branching_xblock.py
@@ -83,7 +83,7 @@ def test_studio_submit_creates_scenario(rf, block):
                 "id": "temp-1",
                 "content": "First node",
                 "media": {"type": "image", "url": "http://img"},
-                "choices": [{"text": "Go to 2", "target_node_id": "temp-2"}],
+                "choices": [{"text": "Go to 2", "target_node_id": "temp-2", "score": 77}],
                 "transcript_url": ""
             },
             {
@@ -96,7 +96,7 @@ def test_studio_submit_creates_scenario(rf, block):
         ],
         "enable_undo": True,
         "enable_scoring": True,
-        "max_score": 77
+        "max_score": 0
     }
     req = rf.post(
         "/", data=json.dumps(payload), content_type="application/json"
@@ -118,6 +118,60 @@ def test_studio_submit_creates_scenario(rf, block):
     assert block.max_score == 77
 
 
+def test_studio_submit_computes_max_score_from_best_path(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Start",
+                "media": {"type": "", "url": ""},
+                "choices": [
+                    {"text": "to A", "target_node_id": "temp-2", "score": 10},
+                    {"text": "to B", "target_node_id": "temp-3", "score": 20},
+                ],
+                "transcript_url": "",
+            },
+            {
+                "id": "temp-2",
+                "content": "A",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to End1", "target_node_id": "temp-4", "score": 30}],
+                "transcript_url": "",
+            },
+            {
+                "id": "temp-3",
+                "content": "B",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to End2", "target_node_id": "temp-5", "score": 15}],
+                "transcript_url": "",
+            },
+            {
+                "id": "temp-4",
+                "content": "End 1",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+                "transcript_url": "",
+            },
+            {
+                "id": "temp-5",
+                "content": "End 2",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+                "transcript_url": "",
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": True,
+        "max_score": 0,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "success"
+    assert block.max_score == pytest.approx(40.0)
+
+
 def test_studio_submit_persists_enable_reset_activity(rf, block):
     payload = {
         "nodes": [
@@ -141,6 +195,59 @@ def test_studio_submit_persists_enable_reset_activity(rf, block):
     assert block.enable_reset_activity is True
 
 
+def test_studio_submit_persists_grade_ranges(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Start node",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+                "transcript_url": "",
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": True,
+        "grade_ranges": [
+            {"label": "Fail", "start": 0, "end": 59},
+            {"label": "Pass", "start": 60, "end": 100},
+        ],
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+    assert result["result"] == "success"
+    assert block.grade_ranges == [
+        {"label": "Fail", "start": 0, "end": 59},
+        {"label": "Pass", "start": 60, "end": 100},
+    ]
+
+
+def test_studio_submit_rejects_invalid_grade_ranges(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Start node",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+                "transcript_url": "",
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": True,
+        "grade_ranges": [
+            {"label": "Fail", "start": 0, "end": 49},
+            {"label": "Pass", "start": 70, "end": 100},
+        ],
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+    assert result["result"] == "error"
+    assert any("Grade range" in error for error in result["field_errors"]["nodes_json"])
+
+
 def test_studio_submit_persists_display_name(rf, block):
     payload = {
         "nodes": [
@@ -164,6 +271,34 @@ def test_studio_submit_persists_display_name(rf, block):
     assert block.display_name == "My Branching Scenario"
 
 
+def test_studio_submit_preserves_image_only_node(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "",
+                "media": {"type": "image", "url": ""},
+                "left_image_url": "https://example.com/left.png",
+                "right_image_url": "",
+                "choices": [],
+                "transcript_url": "",
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": False,
+        "max_score": 0,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "success"
+    nodes = block.scenario_data["nodes"]
+    assert len(nodes) == 1
+    saved_node = next(iter(nodes.values()))
+    assert saved_node["left_image_url"] == "https://example.com/left.png"
+
+
 def test_get_current_state_includes_display_name(rf, block):
     block.scenario_data = {
         "nodes": {"X": {"id": "X", "type": "start", "choices": []}},
@@ -204,6 +339,88 @@ def test_studio_submit_fails_on_invalid_target(rf, block):
     assert any("Invalid target does-not-exist" in e for e in errs)
 
 
+def test_studio_submit_rejects_cycle(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Node A",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to B", "target_node_id": "temp-2"}],
+            },
+            {
+                "id": "temp-2",
+                "content": "Node B",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to A", "target_node_id": "temp-1"}],
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": False,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "error"
+    errs = result["field_errors"]["nodes_json"]
+    assert any("Circular path detected" in error for error in errs)
+
+
+def test_studio_submit_rejects_self_loop(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Node A",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "loop", "target_node_id": "temp-1"}],
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": False,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "error"
+    errs = result["field_errors"]["nodes_json"]
+    assert any("Circular path detected" in error for error in errs)
+
+
+def test_studio_submit_accepts_acyclic_graph(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Node A",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to B", "target_node_id": "temp-2"}],
+            },
+            {
+                "id": "temp-2",
+                "content": "Node B",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to C", "target_node_id": "temp-3"}],
+            },
+            {
+                "id": "temp-3",
+                "content": "Node C",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": False,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "success"
+
+
 def test_lazy_initialize_and_select_choice(rf, block):
     """
     On the very first select_choice, current_node_id should be
@@ -227,12 +444,12 @@ def test_lazy_initialize_and_select_choice(rf, block):
 
 def test_select_choice_scores_and_completes(rf, block):
     """
-    If enable_scoring is True, selecting the last branch
-    should set has_completed and award max_score.
+    If enable_scoring is True, selecting a branch should
+    add that branch's score and complete when ending node is reached.
     """
     block.scenario_data = {
         "nodes": {
-            "A": {"id": "A", "type": "start", "choices": [{"text": "→ B", "target_node_id": "B"}]},
+            "A": {"id": "A", "type": "start", "choices": [{"text": "→ B", "target_node_id": "B", "score": 12}]},
             "B": {"id": "B", "type": "end",   "choices": []}
         },
         "start_node_id": "A"
@@ -246,7 +463,14 @@ def test_select_choice_scores_and_completes(rf, block):
     assert result["success"] is True
     assert block.current_node_id == "B"
     assert block.has_completed is True
-    assert block.score == pytest.approx(block.max_score)
+    assert block.score == pytest.approx(12.0)
+    assert block.choice_history == [
+        {
+            "source_node_id": "A",
+            "choice_text": "→ B",
+            "awarded_points": 12,
+        }
+    ]
 
 
 def test_undo_choice_honors_enable_undo(rf, block):
@@ -279,6 +503,30 @@ def test_undo_choice_honors_enable_undo(rf, block):
     assert resp_fail["success"] is False
 
 
+def test_undo_choice_reverts_choice_history(rf, block):
+    block.scenario_data = {
+        "nodes": {
+            "start": {
+                "id": "start",
+                "type": "start",
+                "choices": [{"text": "to end", "target_node_id": "end", "score": 10}],
+            },
+            "end": {"id": "end", "type": "end", "choices": []},
+        },
+        "start_node_id": "start",
+    }
+    block.enable_undo = True
+    block.enable_scoring = True
+
+    choose_req = rf.post("/", data=json.dumps({"choice_index": 0}), content_type="application/json")
+    block.select_choice(choose_req)
+    assert len(block.choice_history) == 1
+
+    undo_req = rf.post("/", data=json.dumps({}), content_type="application/json")
+    block.undo_choice(undo_req)
+    assert block.choice_history == []
+
+
 def test_reset_activity_requires_enable_reset_activity(rf, block):
     block.scenario_data = {
         "nodes": {"start": {"id": "start", "type": "start", "choices": []}},
@@ -310,6 +558,7 @@ def test_reset_activity_clears_progress_and_score(rf, block):
     block.history = ["start"]
     block.has_completed = True
     block.score = 42.0
+    block.choice_history = [{"source_node_id": "start", "choice_text": "Next", "awarded_points": 42}]
     req = rf.post("/", data=json.dumps({}), content_type="application/json")
 
     resp = block.reset_activity(req)
@@ -320,11 +569,60 @@ def test_reset_activity_clears_progress_and_score(rf, block):
     assert block.history == []
     assert block.has_completed is False
     assert block.score == 0.0
+    assert block.choice_history == []
     assert result["current_node"]["id"] == "start"
     assert result["has_completed"] is False
     assert result["score"] == 0.0
 
 
+def test_reset_activity_clears_scoring_state_when_scoring_disabled(rf, block):
+    block.scenario_data = {
+        "nodes": {
+            "start": {"id": "start", "type": "start", "choices": []},
+        },
+        "start_node_id": "start",
+    }
+    block.enable_reset_activity = True
+    block.enable_scoring = False
+    block.current_node_id = "start"
+    block.history = ["start"]
+    block.has_completed = True
+    block.score = 12.0
+    block.score_history = [12.0]
+    block.choice_history = [{"source_node_id": "start", "choice_text": "A", "awarded_points": 12}]
+
+    req = rf.post("/", data=json.dumps({}), content_type="application/json")
+    resp = block.reset_activity(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["success"] is True
+    assert block.score == 0.0
+    assert block.score_history == []
+    assert block.choice_history == []
+
+
+def test_get_current_state_includes_grade_report_data(rf, block):
+    block.grade_ranges = [
+        {"label": "Fail", "start": 0, "end": 49},
+        {"label": "Pass", "start": 50, "end": 100},
+    ]
+    block.max_score = 200
+    block.score = 160
+    block.choice_history = [
+        {"source_node_id": "n1", "choice_text": "Choice 1", "awarded_points": 80},
+        {"source_node_id": "n2", "choice_text": "Choice 2", "awarded_points": 80},
+    ]
+    req = rf.post("/", data=json.dumps({}), content_type="application/json")
+    resp = block.get_current_state(req)
+    state = json.loads(resp.body.decode("utf-8"))
+
+    assert "grade_report" in state
+    assert state["grade_report"]["percentage"] == 80
+    assert state["grade_report"]["grade_label"] == "Pass"
+    assert state["grade_report"]["is_pass_style"] is True
+    assert state["grade_report"]["detailed_scores"][0]["choice_text"] == "Choice 1"
+
+
 def test_get_current_state_includes_expected_fields(rf, block):
     """
     get_current_state should return a dict containing:
@@ -349,6 +647,7 @@ def test_get_current_state_includes_expected_fields(rf, block):
         "score",
         "start_node_id",
         "enable_reset_activity",
+        "grade_ranges",
     ):
         assert key in state
 
@@ -403,3 +702,30 @@ def fake_initialize_js(_self, name, init_data):
 
     assert calls["name"] == "BranchingStudioEditor"
     assert calls["init_data"]["enable_reset_activity"] is True
+
+
+def test_studio_view_includes_grade_ranges_in_init_data(block):
+    calls = {}
+
+    def fake_initialize_js(_self, name, init_data):
+        calls["name"] = name
+        calls["init_data"] = init_data
+
+    block.grade_ranges = [
+        {"label": "Fail", "start": 0, "end": 59},
+        {"label": "Pass", "start": 60, "end": 100},
+    ]
+
+    with mock.patch(
+        "branching_xblock.branching_xblock.Fragment.initialize_js",
+        autospec=True,
+        side_effect=fake_initialize_js,
+    ), mock.patch.object(
+        block.runtime,
+        "local_resource_url",
+        return_value="http://example.com/handlebars.js",
+    ):
+        block.studio_view({})
+
+    assert calls["name"] == "BranchingStudioEditor"
+    assert calls["init_data"]["grade_ranges"] == block.grade_ranges

From acc3151fc7589e4ebf2f82c1cc7954bab9d57468 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 19 Feb 2026 12:53:48 -0500
Subject: [PATCH 25/32] fix: CI errors

---
 branching_xblock/branching_xblock.py | 187 ++++++++++++++++-----------
 1 file changed, 108 insertions(+), 79 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 4938128..db43ab7 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -331,6 +331,9 @@ def _default_grade_ranges():
 
     @staticmethod
     def _validate_grade_ranges(grade_ranges):
+        """
+        Validate contiguous grade range segments from 0 through 100.
+        """
         if not isinstance(grade_ranges, list) or len(grade_ranges) < 2:
             return "Grade ranges must contain at least two contiguous segments."
 
@@ -361,6 +364,9 @@ def _validate_grade_ranges(grade_ranges):
         return None
 
     def _normalize_grade_ranges(self, raw_grade_ranges, strict=False):
+        """
+        Normalize grade ranges and optionally fail on invalid payloads.
+        """
         defaults = self._default_grade_ranges()
         if not isinstance(raw_grade_ranges, list):
             if strict:
@@ -568,6 +574,9 @@ def studio_view(self, context=None):
         return frag
 
     def _get_state(self):
+        """
+        Build the learner-facing runtime state payload.
+        """
         nodes = self.scenario_data.get("nodes", {})
         nodes_with_defaults = {}
         for node_id, node in nodes.items():
@@ -705,72 +714,38 @@ def reset_activity(self, data, suffix=''):
         self.runtime.publish(self, "completion", {"completion": 0.0})
         return {"success": True, **self._get_state()}
 
-    @XBlock.json_handler
-    def studio_submit(self, data, suffix=''):
+    @staticmethod
+    def _build_staged_nodes(raw_nodes):
         """
-        Handle studio editor save.
+        Assign stable IDs and normalize raw studio node payloads.
         """
-        payload = data
-        raw_nodes = payload.get('nodes', [])
-        deleted_node_ids = set(payload.get('deleted_node_ids', []))
-        background_image_url = (payload.get('background_image_url') or '').strip()
-        background_image_alt_text = (payload.get('background_image_alt_text') or '').strip()
-        background_image_is_decorative = bool(payload.get('background_image_is_decorative', False))
-        grade_ranges, grade_ranges_error = self._normalize_grade_ranges(
-            payload.get('grade_ranges', self.grade_ranges),
-            strict=True,
-        )
-
-        if background_image_url and not background_image_is_decorative and not background_image_alt_text:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": ["Background image alt text is required unless the image is marked decorative."]}
-            }
-        if grade_ranges_error:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": [grade_ranges_error]}
-            }
-
-        # 1) Assign real IDs and build id_map
         id_map = {}
         staged = []
-        score_errors = []
         for raw in raw_nodes:
             old_id = raw.get('id', '')
-            # new ID if temp or missing
-            if old_id.startswith('temp-') or not old_id:
-                new_id = f"node-{uuid.uuid4().hex[:6]}"
-            else:
-                new_id = old_id
+            new_id = f"node-{uuid.uuid4().hex[:6]}" if old_id.startswith('temp-') or not old_id else old_id
             id_map[old_id] = new_id
-            # carry forward content & media, but keep raw choices for next step
             staged.append({
                 'id': new_id,
                 'content': raw.get('content', ''),
                 'media': {
                     'type': raw.get('media', {}).get('type', ''),
-                    'url':  raw.get('media', {}).get('url', '')
+                    'url': raw.get('media', {}).get('url', ''),
                 },
                 'left_image_url': raw.get('left_image_url', ''),
                 'right_image_url': raw.get('right_image_url', ''),
                 'choices': raw.get('choices', []),
-                'hint':     raw.get('hint', ''),
+                'hint': raw.get('hint', ''),
                 'overlay_text': bool(raw.get('overlay_text', False)),
                 'transcript_url': raw.get('transcript_url', ''),
             })
+        return id_map, staged
 
-        resolved_deleted_node_ids = {
-            id_map.get(node_id, node_id)
-            for node_id in deleted_node_ids
-        }
-        node_number_by_id = {
-            node['id']: index + 1
-            for index, node in enumerate(staged)
-        }
-
+    @staticmethod
+    def _collect_reference_errors(staged, id_map, resolved_deleted_node_ids, node_number_by_id):
+        """
+        Collect errors for attempts to delete nodes still referenced by active choices.
+        """
         reference_errors = []
         seen_reference_errors = set()
         for node in staged:
@@ -778,35 +753,33 @@ def studio_submit(self, data, suffix=''):
                 continue
             source_node_number = node_number_by_id.get(node['id'])
             for raw_choice in node['choices']:
-                target_node_id = id_map.get((raw_choice.get('target_node_id') or '').strip(), (raw_choice.get('target_node_id') or '').strip())
+                raw_target = (raw_choice.get('target_node_id') or '').strip()
+                target_node_id = id_map.get(raw_target, raw_target)
                 if not target_node_id or target_node_id not in resolved_deleted_node_ids:
                     continue
                 target_node_number = node_number_by_id.get(target_node_id)
                 if source_node_number and target_node_number:
                     error_message = (
-                        f"Cannot delete Node {target_node_number} because it is referenced by Node {source_node_number}."
+                        f"Cannot delete Node {target_node_number} because it is "
+                        f"referenced by Node {source_node_number}."
                     )
                 else:
-                    error_message = (
-                        "Cannot delete a node that is still referenced by another node."
-                    )
+                    error_message = "Cannot delete a node that is still referenced by another node."
                 if error_message not in seen_reference_errors:
                     seen_reference_errors.add(error_message)
                     reference_errors.append(error_message)
+        return reference_errors
 
-        if reference_errors:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": reference_errors}
-            }
-
-        # 2) Remap choice targets & clean arrays
+    def _build_final_nodes(self, staged, resolved_deleted_node_ids, id_map):
+        """
+        Remap targets, drop blank nodes, and validate choice scores.
+        """
         final = []
+        score_errors = []
         for node in staged:
             if node['id'] in resolved_deleted_node_ids:
                 continue
-            # filter out completely blank nodes
+
             has_content = bool(node['content'].strip())
             has_media = bool(
                 (node['media']['url'] or '').strip()
@@ -814,47 +787,103 @@ def studio_submit(self, data, suffix=''):
                 or (node.get('right_image_url', '') or '').strip()
             )
             has_choices = any(
-                (c.get('text', '').strip() or c.get('target_node_id', '').strip())
-                for c in node['choices']
+                (choice.get('text', '').strip() or choice.get('target_node_id', '').strip())
+                for choice in node['choices']
             )
             if not (has_content or has_media or has_choices):
                 continue
 
-            # remap and clean
-            cleaned = []
-            for raw in node['choices']:
-                text = raw.get('text', '').strip()
-                targ = raw.get('target_node_id', '').strip()
-                has_choice_values = bool(text or targ)
-                if not has_choice_values:
+            cleaned_choices = []
+            for raw_choice in node['choices']:
+                text = raw_choice.get('text', '').strip()
+                target_node_id = raw_choice.get('target_node_id', '').strip()
+                if not (text or target_node_id):
                     continue
 
-                score = self._coerce_choice_score(raw.get('score', 0))
+                score = self._coerce_choice_score(raw_choice.get('score', 0))
                 if score is None:
                     score_errors.append(
                         f"Choice score must be an integer between 0 and 100 in node {node['id']}."
                     )
                     continue
-                # map through id_map if it was a temp ID
-                real_target = id_map.get(targ, targ)
-                cleaned.append({
+                cleaned_choices.append({
                     'text': text,
-                    'target_node_id': real_target,
+                    'target_node_id': id_map.get(target_node_id, target_node_id),
                     'score': score,
                 })
 
             final.append({
-                'id':       node['id'],
-                'type':     'start' if not final else 'normal',
-                'content':  node['content'],
-                'media':    node['media'],
-                'choices':  cleaned,
+                'id': node['id'],
+                'type': 'start' if not final else 'normal',
+                'content': node['content'],
+                'media': node['media'],
+                'choices': cleaned_choices,
                 'hint': node.get('hint', ''),
                 'overlay_text': bool(node.get('overlay_text', False)),
                 'left_image_url': (node.get('left_image_url', '') or '').strip(),
                 'right_image_url': (node.get('right_image_url', '') or '').strip(),
                 'transcript_url': node.get('transcript_url', ''),
             })
+        return final, score_errors
+
+    @XBlock.json_handler
+    def studio_submit(self, data, suffix=''):
+        """
+        Handle studio editor save.
+        """
+        payload = data
+        raw_nodes = payload.get('nodes', [])
+        deleted_node_ids = set(payload.get('deleted_node_ids', []))
+        background_image_url = (payload.get('background_image_url') or '').strip()
+        background_image_alt_text = (payload.get('background_image_alt_text') or '').strip()
+        background_image_is_decorative = bool(payload.get('background_image_is_decorative', False))
+        grade_ranges, grade_ranges_error = self._normalize_grade_ranges(
+            payload.get('grade_ranges', self.grade_ranges),
+            strict=True,
+        )
+
+        if background_image_url and not background_image_is_decorative and not background_image_alt_text:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {
+                    "nodes_json": [
+                        "Background image alt text is required unless the image is marked decorative."
+                    ]
+                }
+            }
+        if grade_ranges_error:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {"nodes_json": [grade_ranges_error]}
+            }
+
+        id_map, staged = self._build_staged_nodes(raw_nodes)
+
+        resolved_deleted_node_ids = {
+            id_map.get(node_id, node_id)
+            for node_id in deleted_node_ids
+        }
+        node_number_by_id = {
+            node['id']: index + 1
+            for index, node in enumerate(staged)
+        }
+
+        reference_errors = self._collect_reference_errors(
+            staged,
+            id_map,
+            resolved_deleted_node_ids,
+            node_number_by_id,
+        )
+        if reference_errors:
+            return {
+                "result": "error",
+                "message": "Validation errors",
+                "field_errors": {"nodes_json": reference_errors}
+            }
+
+        final, score_errors = self._build_final_nodes(staged, resolved_deleted_node_ids, id_map)
 
         if score_errors:
             return {

From aa3e3e7cc871f0dccedeb7b7e78778ece50adf81 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Fri, 27 Feb 2026 15:36:55 -0500
Subject: [PATCH 26/32] refactor: cleanup redundant functions and improve
 validation flow

- move studio save validation to a single backend validation path
- return structured field/global/node errors for UI rendering
- remove frontend normalization/coercion and rely on backend responses
---
 branching_xblock/branching_xblock.py          | 748 +++++++++++-------
 .../static/handlebars/choice-row.handlebars   |   5 +-
 .../handlebars/settings-step.handlebars       |  13 +-
 .../static/js/src/studio_editor.js            | 457 ++++-------
 tests/test_branching_xblock.py                | 280 ++++++-
 5 files changed, 928 insertions(+), 575 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index db43ab7..5b06227 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -14,6 +14,10 @@
 
 resource_loader = ResourceLoader(__name__)
 
+DFS_STATE_UNVISITED = 0
+DFS_STATE_VISITING = 1
+DFS_STATE_VISITED = 2
+
 
 class BranchingXBlock(XBlock):
     """
@@ -142,45 +146,142 @@ class BranchingXBlock(XBlock):
     )
 
     has_custom_completion = True
+    _normalized_nodes_ref: Optional[dict[str, Any]] = None
 
-    def start_node(self):
+    def start_node(self) -> None:
         """
         Set initial current_node_id if not set.
         """
         if not self.current_node_id and self.scenario_data["start_node_id"]:
             self.current_node_id = self.scenario_data["start_node_id"]
 
-    def get_node(self, node_id):
+    def get_node(self, node_id: str) -> Optional[dict[str, Any]]:
         """
         Get a node by its ID.
         """
-        node = self.scenario_data.get("nodes", {}).get(node_id)
-        if node is None:
+        nodes = self.scenario_data.get("nodes", {})
+        if not isinstance(nodes, dict):
             return None
-        if "overlay_text" not in node:
-            node = {**node, "overlay_text": False}
 
-        if "left_image_url" not in node:
-            media = node.get("media") or {}
-            left_fallback = media.get("url", "") if (media.get("type") == "image") else ""
-            node = {**node, "left_image_url": left_fallback}
+        node = nodes.get(node_id)
+        if not isinstance(node, dict):
+            return None
+
+        return node
+
+    def _normalize_scenario_nodes(self) -> None:
+        """
+        Normalize stored scenario node payloads once per nodes object.
+        """
+        nodes = self.scenario_data.get("nodes", {})
+        if nodes is self._normalized_nodes_ref:
+            return
+
+        if not isinstance(nodes, dict):
+            self.scenario_data = {**self.scenario_data, "nodes": {}}
+            self._normalized_nodes_ref = self.scenario_data["nodes"]
+            return
+
+        normalized_nodes: dict[str, dict[str, Any]] = {}
+        changed = False
+        for node_id, node in nodes.items():
+            if not isinstance(node, dict):
+                changed = True
+                continue
+
+            normalized_node, node_changed = self._normalize_scenario_node(node)
+            if node_changed:
+                changed = True
+
+            normalized_nodes[node_id] = normalized_node
+
+        if changed:
+            self.scenario_data = {**self.scenario_data, "nodes": normalized_nodes}
+            nodes = self.scenario_data.get("nodes", {})
+
+        self._normalized_nodes_ref = nodes
+
+    def _normalize_scenario_node(self, node: dict[str, Any]) -> tuple[dict[str, Any], bool]:
+        """
+        Normalize one stored node payload for backward-compatible authoring reads.
+        """
+        normalized_node = dict(node)
+        changed = False
 
-        if "right_image_url" not in node:
-            node = {**node, "right_image_url": ""}
+        if "overlay_text" not in normalized_node:
+            normalized_node["overlay_text"] = False
+            changed = True
+
+        if "left_image_url" not in normalized_node:
+            media = normalized_node.get("media") or {}
+            normalized_node["left_image_url"] = (
+                media.get("url", "") if (media.get("type") == "image") else ""
+            )
+            changed = True
+
+        if "right_image_url" not in normalized_node:
+            normalized_node["right_image_url"] = ""
+            changed = True
+
+        raw_choices = normalized_node.get("choices", [])
+        choices_were_invalid = not isinstance(raw_choices, list)
+        if choices_were_invalid:
+            raw_choices = []
+            changed = True
 
-        node_choices = node.get("choices", []) or []
         normalized_choices = []
-        for choice in node_choices:
-            score = self._coerce_choice_score(choice.get("score", 0))
-            if score is None:
-                score = 0
-            normalized_choices.append({**choice, "score": score})
-        if normalized_choices != node_choices:
-            node = {**node, "choices": normalized_choices}
-        return node
+        for raw_choice in raw_choices:
+            normalized_choice, choice_changed = self._normalize_choice_score(raw_choice)
+            if normalized_choice is None:
+                changed = True
+                continue
+            normalized_choices.append(normalized_choice)
+            if choice_changed:
+                changed = True
+
+        if choices_were_invalid or normalized_choices != raw_choices:
+            normalized_node["choices"] = normalized_choices
+            changed = True
+
+        if normalized_node != node:
+            changed = True
 
-    @staticmethod
-    def _coerce_choice_score(raw_score):
+        return normalized_node, changed
+
+    def _normalize_choice_score(self, raw_choice: Any) -> tuple[Optional[dict[str, Any]], bool]:
+        """
+        Normalize one choice object's score shape for authoring reads.
+        """
+        if not isinstance(raw_choice, dict):
+            return None, True
+
+        choice = dict(raw_choice)
+        changed = False
+        raw_score = choice.get("score")
+
+        if raw_score is None:
+            if choice.get("score") != 0:
+                choice["score"] = 0
+                changed = True
+        elif isinstance(raw_score, str):
+            stripped_score = raw_score.strip()
+            if not stripped_score:
+                choice["score"] = 0
+                changed = True
+            else:
+                score = self._parse_choice_score(raw_score)
+                if score is not None and choice.get("score") != score:
+                    choice["score"] = score
+                    changed = True
+        else:
+            score = self._parse_choice_score(raw_score)
+            if score is not None and choice.get("score") != score:
+                choice["score"] = score
+                changed = True
+
+        return choice, changed
+
+    def _parse_choice_score(self, raw_score: Any) -> Optional[int]:
         """
         Parse and validate choice score.
         """
@@ -204,8 +305,7 @@ def _coerce_choice_score(raw_score):
                 return None
         return score if 0 <= score <= 100 else None
 
-    @staticmethod
-    def _find_cycle_node_ids(nodes):
+    def _find_cycle_node_ids(self, nodes: dict[str, dict[str, Any]]) -> set[str]:
         """
         Return node IDs that participate in a directed cycle.
         """
@@ -213,31 +313,35 @@ def _find_cycle_node_ids(nodes):
         stack = []
         cycle_node_ids = set()
 
-        def visit(node_id):
-            state[node_id] = 1
+        def visit(node_id: str) -> None:
+            state[node_id] = DFS_STATE_VISITING
             stack.append(node_id)
             node = nodes.get(node_id, {})
             for choice in node.get("choices", []) or []:
                 target_node_id = choice.get("target_node_id")
                 if target_node_id not in nodes:
                     continue
-                target_state = state.get(target_node_id, 0)
-                if target_state == 0:
+                target_state = state.get(target_node_id, DFS_STATE_UNVISITED)
+                if target_state == DFS_STATE_UNVISITED:
                     visit(target_node_id)
-                elif target_state == 1:
+                elif target_state == DFS_STATE_VISITING:
                     if target_node_id in stack:
                         cycle_start_index = stack.index(target_node_id)
                         cycle_node_ids.update(stack[cycle_start_index:])
             stack.pop()
-            state[node_id] = 2
+            state[node_id] = DFS_STATE_VISITED
 
         for node_id in nodes:
-            if state.get(node_id, 0) == 0:
+            if state.get(node_id, DFS_STATE_UNVISITED) == DFS_STATE_UNVISITED:
                 visit(node_id)
 
         return cycle_node_ids
 
-    def _compute_max_attainable_score(self, nodes, start_node_id):
+    def _compute_max_attainable_score(
+        self,
+        nodes: dict[str, dict[str, Any]],
+        start_node_id: Optional[str],
+    ) -> float:
         """
         Compute the maximum total score over all reachable start-to-leaf paths.
         """
@@ -287,8 +391,7 @@ def _compute_max_attainable_score(self, nodes, start_node_id):
                 if target_node_id not in reachable:
                     continue
 
-                choice_score = self._coerce_choice_score(choice.get("score", 0))
-                choice_score = 0 if choice_score is None else choice_score
+                choice_score = choice.get("score", 0)
                 if node_score is not None:
                     # Dynamic-programming relaxation:
                     # if this path gives a higher total for target, keep it.
@@ -322,15 +425,7 @@ def _compute_max_attainable_score(self, nodes, start_node_id):
 
         return float(max(leaf_scores))
 
-    @staticmethod
-    def _default_grade_ranges():
-        return [
-            {"label": "Fail", "start": 0, "end": 49},
-            {"label": "Pass", "start": 50, "end": 100},
-        ]
-
-    @staticmethod
-    def _validate_grade_ranges(grade_ranges):
+    def _validate_grade_ranges(self, grade_ranges: Any) -> Optional[str]:
         """
         Validate contiguous grade range segments from 0 through 100.
         """
@@ -363,57 +458,11 @@ def _validate_grade_ranges(grade_ranges):
             return "Final grade range must end at 100."
         return None
 
-    def _normalize_grade_ranges(self, raw_grade_ranges, strict=False):
-        """
-        Normalize grade ranges and optionally fail on invalid payloads.
-        """
-        defaults = self._default_grade_ranges()
-        if not isinstance(raw_grade_ranges, list):
-            if strict:
-                return None, "Grade ranges payload is invalid."
-            return defaults, None
-
-        normalized = []
-        for index, item in enumerate(raw_grade_ranges):
-            if not isinstance(item, dict):
-                if strict:
-                    return None, f"Grade range {index + 1} is invalid."
-                return defaults, None
-
-            label = str(item.get("label", "")).strip()
-            if not label:
-                if strict:
-                    return None, f"Grade range {index + 1} label is required."
-                label = defaults[index]["label"] if index < len(defaults) else f"Grade {index + 1}"
-
-            try:
-                start = int(item.get("start"))
-                end = int(item.get("end"))
-            except (TypeError, ValueError):
-                if strict:
-                    return None, f"Grade range {index + 1} bounds must be integers."
-                return defaults, None
-
-            normalized.append({
-                "label": label,
-                "start": start,
-                "end": end,
-            })
-
-        error = self._validate_grade_ranges(normalized)
-        if error:
-            if strict:
-                return None, error
-            return defaults, None
-
-        return normalized, None
-
-    def _build_grade_report(self):
+    def _build_grade_report(self) -> dict[str, Any]:
         """
         Compute learner-facing grade report data from current score state.
         """
-        normalized_ranges, _ = self._normalize_grade_ranges(self.grade_ranges)
-        safe_ranges = normalized_ranges or self._default_grade_ranges()
+        safe_ranges = self.grade_ranges
 
         max_score = float(self.max_score or 0.0)
         current_score = max(0.0, float(self.score or 0.0))
@@ -436,10 +485,12 @@ def _build_grade_report(self):
             choice_text = str(entry.get("choice_text", "")).strip()
             if not choice_text:
                 continue
-            points = self._coerce_choice_score(entry.get("awarded_points", 0))
+            points = entry.get("awarded_points", 0)
+            if not isinstance(points, int):
+                points = 0
             detailed_scores.append({
                 "choice_text": choice_text,
-                "awarded_points": points if points is not None else 0,
+                "awarded_points": points,
             })
 
         return {
@@ -457,46 +508,112 @@ def get_current_node(self) -> Optional[dict[str, Any]]:
         """
         return self.get_node(self.current_node_id) if self.current_node_id else None
 
-    def is_end_node(self, node_id):
+    def is_end_node(self, node_id: str) -> bool:
         """
         Check if node is a leaf node.
         """
         node = self.get_node(node_id)
         return bool(node) and not node.get("choices")
 
-    def validate_scenario(self):
+    def validate_scenario(self, payload: dict[str, Any]) -> dict[str, Any]:
         """
-        Check for common configuration errors.
+        Validate studio payload and return structured validation results.
         """
-        errors = []
-        nodes = self.scenario_data.get("nodes", {})
+        validation_errors = {
+            "node_input_errors": {},
+            "settings_field_errors": {},
+            "global_errors": [],
+            "node_action_errors": {},
+        }
+
+        raw_nodes = payload.get('nodes', [])
+        deleted_node_ids = set(payload.get('deleted_node_ids', []))
+        background_image_url = (payload.get('background_image_url') or '').strip()
+        background_image_alt_text = (payload.get('background_image_alt_text') or '').strip()
+        background_image_is_decorative = bool(payload.get('background_image_is_decorative', False))
+        grade_ranges = payload.get('grade_ranges', self.grade_ranges)
+        grade_ranges_error = self._validate_grade_ranges(grade_ranges)
+
+        if background_image_url and not background_image_is_decorative and not background_image_alt_text:
+            validation_errors["settings_field_errors"]["background_image_alt_text"] = (
+                "Background image alt text is required unless the image is decorative."
+            )
+        if grade_ranges_error:
+            validation_errors["settings_field_errors"]["grade_ranges"] = grade_ranges_error
+
+        id_map, staged = self._build_staged_nodes(raw_nodes)
+        staged_node_ids = {node["id"] for node in staged}
+
+        resolved_deleted_node_ids = {
+            id_map.get(node_id, node_id)
+            for node_id in deleted_node_ids
+        }
+        node_number_by_id = {
+            node['id']: index + 1
+            for index, node in enumerate(staged)
+        }
+
+        self._validate_references(
+            staged=staged,
+            id_map=id_map,
+            resolved_deleted_node_ids=resolved_deleted_node_ids,
+            node_number_by_id=node_number_by_id,
+            staged_node_ids=staged_node_ids,
+            validation_errors=validation_errors,
+        )
+        final = self._build_final_nodes(staged, resolved_deleted_node_ids, id_map, validation_errors)
 
-        if not nodes:
-            errors.append("At least one node is required")
-            return errors
+        if len(final) > 30:
+            self._add_global_error(validation_errors, "Too many nodes (max 30).")
 
-        # Check start node exists
-        start_id = self.scenario_data.get("start_node_id")
-        if start_id not in nodes:
-            errors.append("Start node ID does not exist")
+        if not final:
+            self._add_global_error(validation_errors, "At least one node is required")
 
-        # Check all choice targets exist
-        for node in nodes.values():
-            for choice in node.get("choices", []):
-                if not self.get_node(choice["target_node_id"]):
-                    errors.append(f"Invalid target {choice['target_node_id']} in node {node['id']}")
+        client_id_by_node_id = {
+            node["id"]: node.get("client_id", node["id"])
+            for node in final
+        }
+
+        nodes_dict = {
+            node['id']: {
+                key: value
+                for key, value in node.items()
+                if key != "client_id"
+            }
+            for node in final
+        }
 
-        cycle_node_ids = self._find_cycle_node_ids(nodes)
+        cycle_node_ids = self._find_cycle_node_ids(nodes_dict)
         if cycle_node_ids:
-            sorted_cycle_ids = ", ".join(sorted(cycle_node_ids))
-            errors.append(
-                f"Circular path detected in nodes: {sorted_cycle_ids}. "
-                "Remove one of the links in this loop."
+            sorted_cycle_ids = sorted(cycle_node_ids)
+            sorted_cycle_labels = ", ".join(sorted_cycle_ids)
+            self._add_global_error(
+                validation_errors,
+                (
+                    "Circular path detected in nodes: "
+                    f"{sorted_cycle_labels}. Remove one of the links in this loop."
+                ),
             )
+            for node_id in sorted_cycle_ids:
+                client_node_id = client_id_by_node_id.get(node_id, node_id)
+                self._add_node_error(
+                    validation_errors,
+                    node_client_id=client_node_id,
+                    title="Circular path detected",
+                    detail="This node links back through branching choices. Remove one link in the loop.",
+                )
 
-        return errors
+        return {
+            "validation_errors": validation_errors,
+            "nodes_dict": nodes_dict,
+            "start_node_id": final[0]['id'] if final else None,
+            "background_image_url": background_image_url,
+            "background_image_alt_text": background_image_alt_text,
+            "background_image_is_decorative": background_image_is_decorative,
+            "grade_ranges": grade_ranges,
+        }
 
-    def publish_grade(self):
+    def publish_grade(self) -> None:
         """
         Send score to gradebook.
         """
@@ -507,14 +624,14 @@ def publish_grade(self):
                 {"value": self.score, "max_value": self.max_score}
             )
 
-    def resource_string(self, path):
+    def resource_string(self, path: str) -> str:
         """
         Retrieve string contents for the file path.
         """
         path = os.path.join('static', path)
         return resource_loader.load_unicode(path)
 
-    def student_view(self, context=None):
+    def student_view(self, context: Optional[dict[str, Any]] = None) -> Fragment:
         """
         Create primary view of the BranchingXBlock, shown to students when viewing courses.
         """
@@ -525,10 +642,11 @@ def student_view(self, context=None):
         frag.initialize_js('BranchingXBlock')
         return frag
 
-    def studio_view(self, context=None):
+    def studio_view(self, context: Optional[dict[str, Any]] = None) -> Fragment:
         """
         Studio editor view shown to course authors.
         """
+        self._normalize_scenario_nodes()
         html = self.resource_string("html/branching_xblock_edit.html")
         frag = Fragment(html)
 
@@ -565,7 +683,7 @@ def studio_view(self, context=None):
             "enable_scoring": bool(self.enable_scoring),
             "enable_reset_activity": bool(self.enable_reset_activity),
             "max_score":   self.max_score,
-            "grade_ranges": self._normalize_grade_ranges(self.grade_ranges)[0],
+            "grade_ranges": self.grade_ranges,
             "display_name": self.display_name,
             "authoring_help_html": authoring_help_html,
         }
@@ -573,35 +691,14 @@ def studio_view(self, context=None):
         frag.initialize_js('BranchingStudioEditor', init_data)
         return frag
 
-    def _get_state(self):
+    def _get_state(self) -> dict[str, Any]:
         """
         Build the learner-facing runtime state payload.
         """
         nodes = self.scenario_data.get("nodes", {})
-        nodes_with_defaults = {}
-        for node_id, node in nodes.items():
-            normalized_choices = []
-            for choice in (node.get("choices", []) or []):
-                score = self._coerce_choice_score(choice.get("score", 0))
-                normalized_choices.append({
-                    **choice,
-                    "score": score if score is not None else 0,
-                })
-
-            nodes_with_defaults[node_id] = {
-                **node,
-                "overlay_text": bool(node.get("overlay_text", False)),
-                "left_image_url": (
-                    node.get("left_image_url")
-                    if node.get("left_image_url") is not None
-                    else (node.get("media") or {}).get("url", "")
-                ),
-                "right_image_url": node.get("right_image_url", "") or "",
-                "choices": normalized_choices,
-            }
 
         return {
-            "nodes":           nodes_with_defaults,
+            "nodes":           nodes,
             "start_node_id":   self.scenario_data.get("start_node_id"),
             "enable_undo":     bool(self.enable_undo),
             "enable_scoring":  bool(self.enable_scoring),
@@ -610,7 +707,7 @@ def _get_state(self):
             "background_image_alt_text": self.background_image_alt_text,
             "background_image_is_decorative": bool(self.background_image_is_decorative),
             "max_score":       self.max_score,
-            "grade_ranges":    self._normalize_grade_ranges(self.grade_ranges)[0],
+            "grade_ranges":    self.grade_ranges,
             "display_name":    self.display_name,
             "current_node":    self.get_current_node(),
             "history":         list(self.history),
@@ -622,14 +719,14 @@ def _get_state(self):
         }
 
     @XBlock.json_handler
-    def get_current_state(self, data, suffix=''):
+    def get_current_state(self, data: dict[str, Any], suffix: str = '') -> dict[str, Any]:
         """
         Fetch current state of the XBlock.
         """
         return self._get_state()
 
     @XBlock.json_handler
-    def select_choice(self, data, suffix=''):
+    def select_choice(self, data: dict[str, Any], suffix: str = '') -> dict[str, Any]:
         """
         Handle choice selection.
         """
@@ -649,9 +746,13 @@ def select_choice(self, data, suffix=''):
 
         awarded_points = 0
         if self.enable_scoring:
-            awarded_points = self._coerce_choice_score(choice.get("score", 0))
-            if awarded_points is None:
+            raw_score = choice.get("score", 0)
+            if raw_score is None or (isinstance(raw_score, str) and not raw_score.strip()):
                 awarded_points = 0
+            else:
+                awarded_points = self._parse_choice_score(raw_score)
+                if awarded_points is None:
+                    return {"success": False, "error": "Invalid choice score"}
             self.score += awarded_points
             self.score_history.append(float(awarded_points))
             self.choice_history.append({
@@ -672,7 +773,7 @@ def select_choice(self, data, suffix=''):
         return {"success": True, **self._get_state()}
 
     @XBlock.json_handler
-    def undo_choice(self, data, suffix=''):
+    def undo_choice(self, data: dict[str, Any], suffix: str = '') -> dict[str, Any]:
         """
         Handle undo choice.
         """
@@ -693,7 +794,7 @@ def undo_choice(self, data, suffix=''):
         return {"success": True, **self._get_state()}
 
     @XBlock.json_handler
-    def reset_activity(self, data, suffix=''):
+    def reset_activity(self, data: dict[str, Any], suffix: str = '') -> dict[str, Any]:
         """
         Reset learner state to the start node.
         """
@@ -714,19 +815,26 @@ def reset_activity(self, data, suffix=''):
         self.runtime.publish(self, "completion", {"completion": 0.0})
         return {"success": True, **self._get_state()}
 
-    @staticmethod
-    def _build_staged_nodes(raw_nodes):
+    def _build_staged_nodes(
+        self,
+        raw_nodes: list[Any],
+    ) -> tuple[dict[str, str], list[dict[str, Any]]]:
         """
         Assign stable IDs and normalize raw studio node payloads.
         """
         id_map = {}
         staged = []
         for raw in raw_nodes:
-            old_id = raw.get('id', '')
+            if not isinstance(raw, dict):
+                continue
+            raw_old_id = raw.get('id')
+            old_id = raw_old_id.strip() if isinstance(raw_old_id, str) else ''
             new_id = f"node-{uuid.uuid4().hex[:6]}" if old_id.startswith('temp-') or not old_id else old_id
-            id_map[old_id] = new_id
+            if old_id:
+                id_map[old_id] = new_id
             staged.append({
                 'id': new_id,
+                'client_id': old_id or new_id,
                 'content': raw.get('content', ''),
                 'media': {
                     'type': raw.get('media', {}).get('type', ''),
@@ -734,52 +842,185 @@ def _build_staged_nodes(raw_nodes):
                 },
                 'left_image_url': raw.get('left_image_url', ''),
                 'right_image_url': raw.get('right_image_url', ''),
-                'choices': raw.get('choices', []),
+                'choices': raw.get('choices', []) if isinstance(raw.get('choices'), list) else [],
                 'hint': raw.get('hint', ''),
                 'overlay_text': bool(raw.get('overlay_text', False)),
                 'transcript_url': raw.get('transcript_url', ''),
             })
         return id_map, staged
 
-    @staticmethod
-    def _collect_reference_errors(staged, id_map, resolved_deleted_node_ids, node_number_by_id):
+    def _has_validation_errors(self, validation_errors: dict[str, Any]) -> bool:
+        """Return True when any validation bucket contains an error."""
+        return any(bool(value) for value in validation_errors.values())
+
+    def _add_global_error(self, validation_errors: dict[str, Any], message: str) -> None:
+        errors = validation_errors["global_errors"]
+        if message not in errors:
+            errors.append(message)
+
+    def _add_node_field_error(
+        self,
+        validation_errors: dict[str, Any],
+        *,
+        node_client_id: str,
+        field_name: str,
+        message: str,
+    ) -> None:
+        """Attach field-level validation error to a node."""
+        node_errors = validation_errors["node_input_errors"].setdefault(node_client_id, {})
+        if field_name not in node_errors:
+            node_errors[field_name] = message
+
+    def _add_node_indexed_error(
+        self,
+        validation_errors: dict[str, Any],
+        *,
+        node_client_id: str,
+        field_name: str,
+        index: int,
+        message: str,
+    ) -> None:
+        """Attach a per-index validation error (for repeated node fields like choices)."""
+        node_errors = validation_errors["node_input_errors"].setdefault(node_client_id, {})
+        indexed_errors = node_errors.setdefault(field_name, {})
+        key = str(index)
+        if key not in indexed_errors:
+            indexed_errors[key] = message
+
+    def _add_node_error(
+        self,
+        validation_errors: dict[str, Any],
+        *,
+        node_client_id: str,
+        title: str,
+        detail: str,
+    ) -> None:
+        """Attach a node-level action error shown as a title/detail callout."""
+        node_errors = validation_errors["node_action_errors"]
+        if node_client_id not in node_errors:
+            node_errors[node_client_id] = {"title": title, "detail": detail}
+
+    def _error_response(self, validation_errors: dict[str, Any]) -> dict[str, Any]:
+        """Build a structured validation error response for studio save."""
+        field_errors = {
+            key: value
+            for key, value in validation_errors.items()
+            if value
+        }
+        return {
+            "result": "error",
+            "message": "Validation errors",
+            "field_errors": field_errors,
+        }
+
+    def _validate_references(
+        self,
+        *,
+        staged: list[dict[str, Any]],
+        id_map: dict[str, str],
+        resolved_deleted_node_ids: set[str],
+        node_number_by_id: dict[str, int],
+        staged_node_ids: set[str],
+        validation_errors: dict[str, Any],
+    ) -> None:
         """
-        Collect errors for attempts to delete nodes still referenced by active choices.
+        Validate references to deleted/missing nodes and missing destinations.
         """
-        reference_errors = []
-        seen_reference_errors = set()
+        client_id_by_id = {
+            node["id"]: node.get("client_id", node["id"])
+            for node in staged
+        }
         for node in staged:
             if node['id'] in resolved_deleted_node_ids:
                 continue
+            node_client_id = node.get("client_id", node["id"])
             source_node_number = node_number_by_id.get(node['id'])
-            for raw_choice in node['choices']:
+            for choice_index, raw_choice in enumerate(node['choices']):
+                if not isinstance(raw_choice, dict):
+                    continue
+                choice_text = (raw_choice.get('text') or '').strip()
                 raw_target = (raw_choice.get('target_node_id') or '').strip()
+                if choice_text and not raw_target:
+                    self._add_node_indexed_error(
+                        validation_errors,
+                        node_client_id=node_client_id,
+                        field_name="choiceDestinationByIndex",
+                        index=choice_index,
+                        message="Required field",
+                    )
+                    continue
+                if not raw_target:
+                    continue
+
                 target_node_id = id_map.get(raw_target, raw_target)
-                if not target_node_id or target_node_id not in resolved_deleted_node_ids:
+                target_node_client_id = client_id_by_id.get(target_node_id, target_node_id)
+
+                if target_node_id not in staged_node_ids:
+                    source_label = (
+                        f"Node {source_node_number}"
+                        if source_node_number
+                        else node_client_id
+                    )
+                    invalid_target_msg = (
+                        f"Invalid target {raw_target} in {source_label}"
+                    )
+                    self._add_global_error(validation_errors, invalid_target_msg)
+                    self._add_node_indexed_error(
+                        validation_errors,
+                        node_client_id=node_client_id,
+                        field_name="choiceDestinationByIndex",
+                        index=choice_index,
+                        message="Selected destination is invalid.",
+                    )
                     continue
+
+                if target_node_id not in resolved_deleted_node_ids:
+                    continue
+
                 target_node_number = node_number_by_id.get(target_node_id)
                 if source_node_number and target_node_number:
                     error_message = (
                         f"Cannot delete Node {target_node_number} because it is "
                         f"referenced by Node {source_node_number}."
                     )
+                    detail_message = (
+                        f"Node {target_node_number} is referenced by Node {source_node_number}."
+                    )
                 else:
                     error_message = "Cannot delete a node that is still referenced by another node."
-                if error_message not in seen_reference_errors:
-                    seen_reference_errors.add(error_message)
-                    reference_errors.append(error_message)
-        return reference_errors
-
-    def _build_final_nodes(self, staged, resolved_deleted_node_ids, id_map):
+                    detail_message = "This node is still referenced by another node in this scenario."
+
+                self._add_global_error(validation_errors, error_message)
+                self._add_node_indexed_error(
+                    validation_errors,
+                    node_client_id=node_client_id,
+                    field_name="choiceDestinationByIndex",
+                    index=choice_index,
+                    message=error_message,
+                )
+                self._add_node_error(
+                    validation_errors,
+                    node_client_id=target_node_client_id,
+                    title="You can't delete this node",
+                    detail=detail_message,
+                )
+
+    def _build_final_nodes(
+        self,
+        staged: list[dict[str, Any]],
+        resolved_deleted_node_ids: set[str],
+        id_map: dict[str, str],
+        validation_errors: dict[str, Any],
+    ) -> list[dict[str, Any]]:
         """
-        Remap targets, drop blank nodes, and validate choice scores.
+        Remap targets, drop blank nodes, and validate per-node fields.
         """
         final = []
-        score_errors = []
         for node in staged:
             if node['id'] in resolved_deleted_node_ids:
                 continue
 
+            node_client_id = node.get("client_id", node["id"])
             has_content = bool(node['content'].strip())
             has_media = bool(
                 (node['media']['url'] or '').strip()
@@ -787,23 +1028,53 @@ def _build_final_nodes(self, staged, resolved_deleted_node_ids, id_map):
                 or (node.get('right_image_url', '') or '').strip()
             )
             has_choices = any(
-                (choice.get('text', '').strip() or choice.get('target_node_id', '').strip())
+                (
+                    isinstance(choice, dict)
+                    and (choice.get('text', '').strip() or choice.get('target_node_id', '').strip())
+                )
                 for choice in node['choices']
             )
             if not (has_content or has_media or has_choices):
                 continue
 
+            left_image_url = (node.get('left_image_url', '') or '').strip()
+            right_image_url = (node.get('right_image_url', '') or '').strip()
+            if node.get("media", {}).get("type") == "image" and not left_image_url and not right_image_url:
+                self._add_node_field_error(
+                    validation_errors,
+                    node_client_id=node_client_id,
+                    field_name="left_image_url",
+                    message="Please enter a valid URL",
+                )
+
             cleaned_choices = []
-            for raw_choice in node['choices']:
+            for choice_index, raw_choice in enumerate(node['choices']):
+                if not isinstance(raw_choice, dict):
+                    self._add_node_indexed_error(
+                        validation_errors,
+                        node_client_id=node_client_id,
+                        field_name="choiceScoreByIndex",
+                        index=choice_index,
+                        message="Score must be an integer between 0 and 100.",
+                    )
+                    continue
                 text = raw_choice.get('text', '').strip()
                 target_node_id = raw_choice.get('target_node_id', '').strip()
                 if not (text or target_node_id):
                     continue
 
-                score = self._coerce_choice_score(raw_choice.get('score', 0))
+                raw_score = raw_choice.get('score', 0)
+                if raw_score is None or (isinstance(raw_score, str) and raw_score.strip() == ''):
+                    score = 0
+                else:
+                    score = self._parse_choice_score(raw_score)
                 if score is None:
-                    score_errors.append(
-                        f"Choice score must be an integer between 0 and 100 in node {node['id']}."
+                    self._add_node_indexed_error(
+                        validation_errors,
+                        node_client_id=node_client_id,
+                        field_name="choiceScoreByIndex",
+                        index=choice_index,
+                        message="Score must be an integer between 0 and 100.",
                     )
                     continue
                 cleaned_choices.append({
@@ -814,140 +1085,57 @@ def _build_final_nodes(self, staged, resolved_deleted_node_ids, id_map):
 
             final.append({
                 'id': node['id'],
+                'client_id': node_client_id,
                 'type': 'start' if not final else 'normal',
                 'content': node['content'],
                 'media': node['media'],
                 'choices': cleaned_choices,
                 'hint': node.get('hint', ''),
                 'overlay_text': bool(node.get('overlay_text', False)),
-                'left_image_url': (node.get('left_image_url', '') or '').strip(),
-                'right_image_url': (node.get('right_image_url', '') or '').strip(),
+                'left_image_url': left_image_url,
+                'right_image_url': right_image_url,
                 'transcript_url': node.get('transcript_url', ''),
             })
-        return final, score_errors
+        return final
 
     @XBlock.json_handler
-    def studio_submit(self, data, suffix=''):
+    def studio_submit(self, data: dict[str, Any], suffix: str = '') -> dict[str, Any]:
         """
         Handle studio editor save.
         """
         payload = data
-        raw_nodes = payload.get('nodes', [])
-        deleted_node_ids = set(payload.get('deleted_node_ids', []))
-        background_image_url = (payload.get('background_image_url') or '').strip()
-        background_image_alt_text = (payload.get('background_image_alt_text') or '').strip()
-        background_image_is_decorative = bool(payload.get('background_image_is_decorative', False))
-        grade_ranges, grade_ranges_error = self._normalize_grade_ranges(
-            payload.get('grade_ranges', self.grade_ranges),
-            strict=True,
-        )
-
-        if background_image_url and not background_image_is_decorative and not background_image_alt_text:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {
-                    "nodes_json": [
-                        "Background image alt text is required unless the image is marked decorative."
-                    ]
-                }
-            }
-        if grade_ranges_error:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": [grade_ranges_error]}
-            }
-
-        id_map, staged = self._build_staged_nodes(raw_nodes)
-
-        resolved_deleted_node_ids = {
-            id_map.get(node_id, node_id)
-            for node_id in deleted_node_ids
-        }
-        node_number_by_id = {
-            node['id']: index + 1
-            for index, node in enumerate(staged)
-        }
-
-        reference_errors = self._collect_reference_errors(
-            staged,
-            id_map,
-            resolved_deleted_node_ids,
-            node_number_by_id,
-        )
-        if reference_errors:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": reference_errors}
-            }
+        validation_result = self.validate_scenario(payload)
+        validation_errors = validation_result["validation_errors"]
+        nodes_dict = validation_result["nodes_dict"]
+        start_node_id = validation_result["start_node_id"]
 
-        final, score_errors = self._build_final_nodes(staged, resolved_deleted_node_ids, id_map)
-
-        if score_errors:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": score_errors}
-            }
-
-        if len(final) > 30:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": ["Too many nodes (max 30)."]}
-            }
+        if self._has_validation_errors(validation_errors):
+            return self._error_response(validation_errors)
 
         # 3) Persist scenario_data & settings
-        nodes_dict = {node['id']: node for node in final}
-        cycle_node_ids = self._find_cycle_node_ids(nodes_dict)
-        if cycle_node_ids:
-            sorted_cycle_ids = ", ".join(sorted(cycle_node_ids))
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {
-                    "nodes_json": [
-                        (
-                            "Circular path detected in nodes: "
-                            f"{sorted_cycle_ids}. Remove one of the links in this loop."
-                        )
-                    ]
-                }
-            }
-
         self.scenario_data = {
             'nodes': nodes_dict,
-            'start_node_id': final[0]['id'] if final else None
+            'start_node_id': start_node_id,
         }
+        self._normalized_nodes_ref = nodes_dict
         self.enable_undo = bool(payload.get('enable_undo', self.enable_undo))
         self.enable_scoring = bool(payload.get('enable_scoring', self.enable_scoring))
         self.enable_reset_activity = bool(payload.get('enable_reset_activity', self.enable_reset_activity))
         self.max_score = self._compute_max_attainable_score(
             nodes_dict,
-            final[0]['id'] if final else None,
+            start_node_id,
         )
         self.display_name = payload.get('display_name', self.display_name)
-        self.background_image_url = background_image_url
-        self.background_image_alt_text = background_image_alt_text
-        self.background_image_is_decorative = background_image_is_decorative
-        self.grade_ranges = grade_ranges
-
-        # 4) Validate & respond
-        errors = self.validate_scenario()
-        if errors:
-            return {
-                "result": "error",
-                "message": "Validation errors",
-                "field_errors": {"nodes_json": errors}
-            }
+        self.background_image_url = validation_result["background_image_url"]
+        self.background_image_alt_text = validation_result["background_image_alt_text"]
+        self.background_image_is_decorative = validation_result["background_image_is_decorative"]
+        self.grade_ranges = validation_result["grade_ranges"]
+
         return {"result": "success"}
 
     # TO-DO: change this to create the scenarios you'd like to see in the
     # workbench while developing your XBlock.
-    @staticmethod
-    def workbench_scenarios():
+    def workbench_scenarios(self) -> list[tuple[str, str]]:
         """
         Create canned scenario for display in the workbench.
         """
diff --git a/branching_xblock/static/handlebars/choice-row.handlebars b/branching_xblock/static/handlebars/choice-row.handlebars
index 77fbf7a..542b430 100644
--- a/branching_xblock/static/handlebars/choice-row.handlebars
+++ b/branching_xblock/static/handlebars/choice-row.handlebars
@@ -6,7 +6,7 @@
   <div class="choice-col choice-col--score">
     <label class="choice-col__label">Score</label>
     <input
-      class="choice-score"
+      class="choice-score {{#if score_error}}is-error{{/if}}"
       type="number"
       min="0"
       max="100"
@@ -15,6 +15,9 @@
       placeholder="0"
       aria-label="Choice score"
     />
+    {{#if score_error}}
+      <div class="choice-field-error">{{score_error}}</div>
+    {{/if}}
   </div>
   <div class="choice-col choice-col--target">
     <label class="choice-col__label">Destination*</label>
diff --git a/branching_xblock/static/handlebars/settings-step.handlebars b/branching_xblock/static/handlebars/settings-step.handlebars
index d5bb3c2..d604218 100644
--- a/branching_xblock/static/handlebars/settings-step.handlebars
+++ b/branching_xblock/static/handlebars/settings-step.handlebars
@@ -25,6 +25,9 @@
     <h3 class="bx-section-title bx-grade-range__title">Specify Grade Range</h3>
     <p class="bx-help bx-grade-range__help">Adjust the scale to set percentage ranges for each grade.</p>
     <div class="bx-grade-range__slider" data-role="grade-range-slider"></div>
+    {{#if grade_ranges_error}}
+      <div class="bx-field-error">{{grade_ranges_error}}</div>
+    {{/if}}
   </div>
 
   <h3 class="bx-section-title">Background image</h3>
@@ -37,10 +40,13 @@
     <input
       type="text"
       name="background_image_url"
-      class="bx-input"
+      class="bx-input {{#if background_image_url_error}}is-error{{/if}}"
       placeholder="URL"
       value="{{background_image_url}}"
     />
+    {{#if background_image_url_error}}
+      <div class="bx-field-error">{{background_image_url_error}}</div>
+    {{/if}}
   </label>
 
   <div class="bx-field">
@@ -52,10 +58,13 @@
     <input
       type="text"
       name="background_image_alt_text"
-      class="bx-input"
+      class="bx-input {{#if background_image_alt_text_error}}is-error{{/if}}"
       placeholder="Alt text"
       value="{{background_image_alt_text}}"
       {{#if background_image_is_decorative}}disabled{{/if}}
     />
+    {{#if background_image_alt_text_error}}
+      <div class="bx-field-error">{{background_image_alt_text_error}}</div>
+    {{/if}}
   </div>
 </div>
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index 7b0ef32..3b7edcb 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -24,96 +24,24 @@ function BranchingStudioEditor(runtime, element, data) {
     return `temp-${i}`;
   };
 
+  // Keep editor state in a draft model, then sync to/from DOM on transitions.
+  // This prevents partial DOM edits from immediately mutating persisted data.
   const wizard = {
     currentStep: 'settings',
     selectedNodeId: null,
     draftSettings: {},
     draftNodes: [],
-    showDeleteValidationErrors: false,
-    showFieldValidationErrors: false,
-    validationFieldErrorsByNodeId: new Map(),
+    settingsFieldErrors: {},
+    validationErrors: [],
+    validationNodeErrorIds: new Set(),
+    validationNodeErrorDetailsById: new Map(),
     validationNodeErrorTitlesById: new Map(),
+    validationFieldErrorsByNodeId: new Map(),
   };
 
-  function findCycleNodeIds(nodes) {
-    const state = new Map();
-    const stack = [];
-    const cycleNodeIds = new Set();
-    const nodeById = new Map(nodes.map(node => [node.id, node]));
-
-    function visit(nodeId) {
-      state.set(nodeId, 1);
-      stack.push(nodeId);
-      const node = nodeById.get(nodeId);
-      (node?.choices || []).forEach((choice) => {
-        const targetNodeId = (choice?.target_node_id || '').trim();
-        if (!targetNodeId || !nodeById.has(targetNodeId)) {
-          return;
-        }
-        const targetState = state.get(targetNodeId) || 0;
-        if (targetState === 0) {
-          visit(targetNodeId);
-          return;
-        }
-        if (targetState === 1) {
-          const cycleStartIndex = stack.indexOf(targetNodeId);
-          if (cycleStartIndex >= 0) {
-            stack.slice(cycleStartIndex).forEach(cycleId => cycleNodeIds.add(cycleId));
-          }
-        }
-      });
-      stack.pop();
-      state.set(nodeId, 2);
-    }
-
-    nodes.forEach((node) => {
-      if ((state.get(node.id) || 0) === 0) {
-        visit(node.id);
-      }
-    });
-    return cycleNodeIds;
-  }
-
-  function defaultGradeRanges() {
-    return [
-      { label: 'Fail', start: 0, end: 49 },
-      { label: 'Pass', start: 50, end: 100 },
-    ];
-  }
-
-  function normalizeGradeRanges(rawGradeRanges) {
-    if (!Array.isArray(rawGradeRanges) || rawGradeRanges.length < 2) {
-      return defaultGradeRanges();
-    }
-    const normalized = [];
-    for (let index = 0; index < rawGradeRanges.length; index += 1) {
-      const gradeRange = rawGradeRanges[index] || {};
-      const label = String(gradeRange.label || '').trim() || `Grade ${index + 1}`;
-      const start = Number.parseInt(gradeRange.start, 10);
-      const end = Number.parseInt(gradeRange.end, 10);
-      if (
-        Number.isNaN(start) || Number.isNaN(end) ||
-        start < 0 || end > 100 || end < start
-      ) {
-        return defaultGradeRanges();
-      }
-      normalized.push({ label, start, end });
-    }
-
-    let expectedStart = 0;
-    for (let index = 0; index < normalized.length; index += 1) {
-      const gradeRange = normalized[index];
-      if (gradeRange.start !== expectedStart) {
-        return defaultGradeRanges();
-      }
-      expectedStart = gradeRange.end + 1;
-    }
-    if (normalized[normalized.length - 1].end !== 100) {
-      return defaultGradeRanges();
-    }
-    return normalized;
-  }
-
+  // ---------------------------
+  // Grade range slider helpers
+  // ---------------------------
   function boundaryBounds(boundaryIndex, gradeRanges) {
     const lower = boundaryIndex === 0 ? 0 : gradeRanges[boundaryIndex - 1].end + 1;
     const upper = boundaryIndex === (gradeRanges.length - 2)
@@ -123,7 +51,10 @@ function BranchingStudioEditor(runtime, element, data) {
   }
 
   function setBoundaryValue(boundaryIndex, requestedValue) {
-    const gradeRanges = wizard.draftSettings.grade_ranges || defaultGradeRanges();
+    const gradeRanges = wizard.draftSettings.grade_ranges;
+    if (!Array.isArray(gradeRanges) || gradeRanges.length < 2) {
+      return;
+    }
     const current = gradeRanges[boundaryIndex];
     const next = gradeRanges[boundaryIndex + 1];
     if (!current || !next) {
@@ -147,8 +78,10 @@ function BranchingStudioEditor(runtime, element, data) {
       return;
     }
 
-    wizard.draftSettings.grade_ranges = normalizeGradeRanges(wizard.draftSettings.grade_ranges);
     const gradeRanges = wizard.draftSettings.grade_ranges;
+    if (!Array.isArray(gradeRanges) || gradeRanges.length < 2) {
+      return;
+    }
     const percentPerPoint = 100 / 101;
     const $slider = $section.find('[data-role="grade-range-slider"]').empty();
     const $trackWrap = $('<div class="bx-grade-range__track-wrap"></div>');
@@ -192,6 +125,9 @@ function BranchingStudioEditor(runtime, element, data) {
     $slider.append($trackWrap);
   }
 
+  // ---------------------------
+  // Initial state hydration
+  // ---------------------------
   function loadState() {
       return $.ajax({
         type: 'POST',
@@ -202,15 +138,12 @@ function BranchingStudioEditor(runtime, element, data) {
       });
   }
 
-  function normalizeNode(raw) {
-    const normalizeChoice = (choice) => {
-      const parsedScore = Number.parseInt(choice?.score, 10);
-      return {
-        text: choice?.text || '',
-        target_node_id: choice?.target_node_id || '',
-        score: Number.isNaN(parsedScore) ? 0 : parsedScore,
-      };
-    };
+  function buildDraftNode(raw) {
+    const buildDraftChoice = (choice) => ({
+      text: choice?.text || '',
+      target_node_id: choice?.target_node_id || '',
+      score: choice?.score,
+    });
 
     return {
       id: raw?.id || uniqueId(),
@@ -219,7 +152,7 @@ function BranchingStudioEditor(runtime, element, data) {
         type: raw?.media?.type || '',
         url: raw?.media?.url || '',
       },
-      choices: Array.isArray(raw?.choices) ? raw.choices.map(normalizeChoice) : [],
+      choices: Array.isArray(raw?.choices) ? raw.choices.map(buildDraftChoice) : [],
       no_branches: Boolean(raw?.no_branches),
       pending_delete: false,
       hint: raw?.hint || '',
@@ -230,10 +163,10 @@ function BranchingStudioEditor(runtime, element, data) {
     };
   }
 
-  function normalizeInitialState(state) {
-    const nodes = Object.values(state?.nodes || {}).map(normalizeNode);
+  function hydrateInitialState(state) {
+    const nodes = Object.values(state?.nodes || {}).map(buildDraftNode);
     if (!nodes.length) {
-      nodes.push(normalizeNode({}));
+      nodes.push(buildDraftNode({}));
     }
     wizard.draftNodes = nodes;
     wizard.selectedNodeId = nodes[0].id;
@@ -245,10 +178,13 @@ function BranchingStudioEditor(runtime, element, data) {
       background_image_url: state?.background_image_url || '',
       background_image_alt_text: state?.background_image_alt_text || '',
       background_image_is_decorative: Boolean(state?.background_image_is_decorative),
-      grade_ranges: normalizeGradeRanges(state?.grade_ranges),
+      grade_ranges: state?.grade_ranges,
     };
   }
 
+  // ---------------------------
+  // Step navigation + selectors
+  // ---------------------------
   function showStep(step) {
     wizard.currentStep = step;
     const showSettings = step === 'settings';
@@ -284,133 +220,19 @@ function BranchingStudioEditor(runtime, element, data) {
     return wizard.draftNodes.filter(node => node.pending_delete);
   }
 
-  function nodeNumberById(nodeId) {
-    const idx = wizard.draftNodes.findIndex(node => node.id === nodeId);
-    return idx >= 0 ? idx + 1 : null;
-  }
-
-  function buildClientValidation() {
-    const errors = [];
-    const seenErrors = new Set();
-    const nodeErrorDetailsById = new Map();
-    const nodeErrorTitlesById = new Map();
-    const nodeErrorIds = new Set();
-    const fieldErrorsByNodeId = new Map();
-    const pendingDeleteIds = new Set(pendingDeleteNodes().map(node => node.id));
-    const active = activeNodes();
-
-    if (!active.length) {
-      errors.push('At least one active node is required.');
-    }
-
-    active.forEach((sourceNode) => {
-      (sourceNode.choices || []).forEach((choice) => {
-        const targetNodeId = (choice?.target_node_id || '').trim();
-        if (!targetNodeId || !pendingDeleteIds.has(targetNodeId)) {
-          return;
-        }
-        const sourceNumber = nodeNumberById(sourceNode.id);
-        const targetNumber = nodeNumberById(targetNodeId);
-        let message;
-        if (sourceNumber && targetNumber) {
-          message = `Cannot delete Node ${targetNumber} because it is referenced by Node ${sourceNumber}.`;
-          if (!seenErrors.has(message)) {
-            seenErrors.add(message);
-            errors.push(message);
-          }
-        } else {
-          message = 'Cannot delete a node that is still referenced by another node.';
-          if (!seenErrors.has(message)) {
-            seenErrors.add(message);
-            errors.push(message);
-          }
-        }
-        nodeErrorIds.add(sourceNode.id);
-        nodeErrorIds.add(targetNodeId);
-        if (!nodeErrorDetailsById.has(targetNodeId)) {
-          nodeErrorTitlesById.set(targetNodeId, "You can't delete this node");
-          if (sourceNumber && targetNumber) {
-            nodeErrorDetailsById.set(
-              targetNodeId,
-              `Node ${targetNumber} is referenced by Node ${sourceNumber}.`
-            );
-          } else {
-            nodeErrorDetailsById.set(
-              targetNodeId,
-              'This node is still referenced by another node in this scenario.'
-            );
-          }
-        }
-      });
-    });
-
-    active.forEach((node) => {
-      const nodeFieldErrors = {};
-
-      if (node.media?.type === 'image') {
-        const leftImageUrl = (node.left_image_url || '').trim();
-        const rightImageUrl = (node.right_image_url || '').trim();
-        if (!leftImageUrl && !rightImageUrl) {
-          nodeFieldErrors.left_image_url = 'Please enter a valid URL';
-        }
-      }
-
-      const choiceDestinationByIndex = {};
-      (node.choices || []).forEach((choice, index) => {
-        const choiceText = (choice?.text || '').trim();
-        const choiceTarget = (choice?.target_node_id || '').trim();
-        if (choiceText && !choiceTarget) {
-          choiceDestinationByIndex[index] = 'Required field';
-        }
-      });
-
-      if (Object.keys(choiceDestinationByIndex).length > 0) {
-        nodeFieldErrors.choiceDestinationByIndex = choiceDestinationByIndex;
-      }
-
-      if (Object.keys(nodeFieldErrors).length > 0) {
-        fieldErrorsByNodeId.set(node.id, nodeFieldErrors);
-        nodeErrorIds.add(node.id);
-        errors.push(`Node ${nodeNumberById(node.id)} has required fields missing.`);
-      }
-    });
-
-    const cycleNodeIds = findCycleNodeIds(active);
-    if (cycleNodeIds.size > 0) {
-      const cycleNodeNumbers = Array.from(cycleNodeIds)
-        .map(nodeId => nodeNumberById(nodeId))
-        .filter(number => number !== null)
-        .sort((a, b) => a - b);
-      const cycleNodeLabel = cycleNodeNumbers.length
-        ? cycleNodeNumbers.map(number => `Node ${number}`).join(', ')
-        : 'one or more nodes';
-
-      errors.push(
-        `Circular path detected: ${cycleNodeLabel} links back through branching choices. Remove one of the links in this loop.`
-      );
-      cycleNodeIds.forEach((nodeId) => {
-        nodeErrorIds.add(nodeId);
-        if (!nodeErrorDetailsById.has(nodeId)) {
-          const nodeNumber = nodeNumberById(nodeId);
-          const prefix = nodeNumber ? `Node ${nodeNumber}` : 'This node';
-          nodeErrorTitlesById.set(nodeId, 'Circular path detected');
-          nodeErrorDetailsById.set(
-            nodeId,
-            `${prefix} links back through branching choices. Remove one of the links in this loop.`
-          );
-        }
-      });
-    }
-
-    return { errors, nodeErrorIds, nodeErrorDetailsById, nodeErrorTitlesById, fieldErrorsByNodeId };
+  // Reset all rendered validation state before a fresh server response is applied.
+  function clearValidationState() {
+    wizard.settingsFieldErrors = {};
+    wizard.validationErrors = [];
+    wizard.validationNodeErrorIds = new Set();
+    wizard.validationNodeErrorDetailsById = new Map();
+    wizard.validationNodeErrorTitlesById = new Map();
+    wizard.validationFieldErrorsByNodeId = new Map();
   }
 
   function updateFooterUi() {
-    if (!wizard.showFieldValidationErrors) {
-      $saveValidationSummary.attr('hidden', true).text('');
-    }
     const pendingCount = pendingDeleteNodes().length;
-    if (wizard.currentStep !== 'nodes' || pendingCount === 0 || wizard.showFieldValidationErrors) {
+    if (wizard.currentStep !== 'nodes' || pendingCount === 0 || wizard.validationErrors.length > 0) {
       $pendingDeleteSummary.attr('hidden', true).text('');
       return;
     }
@@ -420,34 +242,56 @@ function BranchingStudioEditor(runtime, element, data) {
       .text(`${pendingCount} ${nodeWord} will be deleted when you save.`);
   }
 
-  function updateClientValidationUi() {
-    const validation = buildClientValidation();
-    if (wizard.showDeleteValidationErrors || wizard.showFieldValidationErrors) {
-      wizard.validationErrors = validation.errors;
-      wizard.validationNodeErrorIds = validation.nodeErrorIds;
-      wizard.validationNodeErrorDetailsById = validation.nodeErrorDetailsById;
-      wizard.validationNodeErrorTitlesById = validation.nodeErrorTitlesById;
-      wizard.validationFieldErrorsByNodeId = validation.fieldErrorsByNodeId;
-      const generalErrors = validation.errors.filter(msg => msg === 'At least one active node is required.');
-      if (wizard.currentStep === 'nodes' && generalErrors.length) {
-        $errors.empty();
-        generalErrors.forEach(msg => $errors.append($('<div>').text(msg)));
-      } else {
-        $errors.empty();
+  // Map backend structured errors into the editor's view model. This is the
+  // canonical validation bridge from API contract -> per-field/per-node UI state.
+  function applyServerValidation(res) {
+    clearValidationState();
+
+    const fieldErrors = (res && res.field_errors) || {};
+    const nodeFieldErrors = fieldErrors.node_input_errors || fieldErrors.node_field_errors || {};
+    const nodeErrors = fieldErrors.node_action_errors || fieldErrors.node_errors || {};
+    const settingsFieldErrors = fieldErrors.settings_field_errors || {};
+    const globalErrors = Array.isArray(fieldErrors.global_errors) ? fieldErrors.global_errors : [];
+
+    Object.entries(nodeFieldErrors).forEach(([nodeId, nodeFieldError]) => {
+      if (!nodeFieldError || typeof nodeFieldError !== 'object') {
+        return;
       }
-      if (wizard.currentStep === 'nodes' && validation.errors.length > 0) {
-        $saveValidationSummary
-          .attr('hidden', false)
-          .text("We weren't able to save your selections. Please fix the errors shown and try again.");
-      } else {
-        $saveValidationSummary.attr('hidden', true).text('');
+      wizard.validationFieldErrorsByNodeId.set(nodeId, nodeFieldError);
+      wizard.validationNodeErrorIds.add(nodeId);
+    });
+
+    Object.entries(nodeErrors).forEach(([nodeId, nodeError]) => {
+      if (!nodeError || typeof nodeError !== 'object') {
+        return;
       }
+      if (nodeError.title) {
+        wizard.validationNodeErrorTitlesById.set(nodeId, nodeError.title);
+      }
+      if (nodeError.detail) {
+        wizard.validationNodeErrorDetailsById.set(nodeId, nodeError.detail);
+      }
+      wizard.validationNodeErrorIds.add(nodeId);
+    });
+
+    wizard.settingsFieldErrors = settingsFieldErrors;
+    wizard.validationErrors = globalErrors.slice();
+  }
+
+  // Render top-level summary area when any backend validation errors exist.
+  function updateClientValidationUi() {
+    const hasInlineFieldErrors =
+      Object.keys(wizard.settingsFieldErrors || {}).length > 0
+      || (wizard.validationFieldErrorsByNodeId && wizard.validationFieldErrorsByNodeId.size > 0)
+      || (wizard.validationNodeErrorIds && wizard.validationNodeErrorIds.size > 0);
+
+    if (wizard.validationErrors.length > 0 || hasInlineFieldErrors) {
+      $errors.empty();
+      wizard.validationErrors.forEach(msg => $errors.append($('<div>').text(msg)));
+      $saveValidationSummary
+        .attr('hidden', false)
+        .text("We weren't able to save your selections. Please fix the errors shown and try again.");
     } else {
-      wizard.validationErrors = [];
-      wizard.validationNodeErrorIds = new Set();
-      wizard.validationNodeErrorDetailsById = new Map();
-      wizard.validationNodeErrorTitlesById = new Map();
-      wizard.validationFieldErrorsByNodeId = new Map();
       $saveValidationSummary.attr('hidden', true).text('');
       $errors.empty();
     }
@@ -455,8 +299,16 @@ function BranchingStudioEditor(runtime, element, data) {
     updateFooterUi();
   }
 
+  // ---------------------------
+  // Render functions
+  // ---------------------------
   function renderSettings() {
-    $stepSettings.html(Templates['settings-step'](wizard.draftSettings));
+    $stepSettings.html(Templates['settings-step']({
+      ...wizard.draftSettings,
+      background_image_url_error: wizard.settingsFieldErrors.background_image_url || '',
+      background_image_alt_text_error: wizard.settingsFieldErrors.background_image_alt_text || '',
+      grade_ranges_error: wizard.settingsFieldErrors.grade_ranges || '',
+    }));
     renderGradeRangeSlider();
   }
 
@@ -538,12 +390,14 @@ function BranchingStudioEditor(runtime, element, data) {
     const $choices = $editor.find('[data-role="choices-container"]').empty();
     const options = nodeOptions(node.id);
     const choiceDestinationErrors = currentNodeFieldErrors.choiceDestinationByIndex || {};
+    const choiceScoreErrors = currentNodeFieldErrors.choiceScoreByIndex || {};
     (node.choices || []).forEach((choice, i) => {
       $choices.append(Templates['choice-row']({
         choice,
         i,
         options,
         destination_error: choiceDestinationErrors[i] || '',
+        score_error: choiceScoreErrors[i] || '',
       }));
     });
   }
@@ -554,6 +408,7 @@ function BranchingStudioEditor(runtime, element, data) {
     renderNodeEditor();
   }
 
+  // Full rerender used on initial load and after major state transitions.
   function renderAll() {
     $errors.empty();
     renderSettings();
@@ -563,7 +418,11 @@ function BranchingStudioEditor(runtime, element, data) {
     updateClientValidationUi();
   }
 
+  // ---------------------------
+  // DOM -> draft synchronization
+  // ---------------------------
   function syncSettingsFromDom() {
+    // Pull settings fields into draft state before navigation/save.
     const $s = $stepSettings;
     wizard.draftSettings.display_name = $s.find('[name="display_name"]').val()?.trim() || '';
     wizard.draftSettings.enable_undo = $s.find('[name="enable_undo"]').is(':checked');
@@ -572,10 +431,10 @@ function BranchingStudioEditor(runtime, element, data) {
     wizard.draftSettings.background_image_url = $s.find('[name="background_image_url"]').val()?.trim() || '';
     wizard.draftSettings.background_image_is_decorative = $s.find('[name="background_image_is_decorative"]').is(':checked');
     wizard.draftSettings.background_image_alt_text = $s.find('[name="background_image_alt_text"]').val()?.trim() || '';
-    wizard.draftSettings.grade_ranges = normalizeGradeRanges(wizard.draftSettings.grade_ranges);
   }
 
   function syncCurrentNodeFromDom() {
+    // Pull the currently open node editor inputs into draft state.
     const node = currentNode();
     if (!node) {
       return;
@@ -612,8 +471,8 @@ function BranchingStudioEditor(runtime, element, data) {
       const $row = $(this);
       const text = $row.find('.choice-text').val()?.trim() || '';
       const target = $row.find('.choice-target').val()?.trim() || '';
-      const parsedScore = Number.parseInt($row.find('.choice-score').val(), 10);
-      const score = Number.isNaN(parsedScore) ? 0 : parsedScore;
+      const rawScore = $row.find('.choice-score').val();
+      const score = rawScore;
       if (text || target) {
         choices.push({ text, target_node_id: target, score });
       }
@@ -621,12 +480,22 @@ function BranchingStudioEditor(runtime, element, data) {
     node.choices = choices;
   }
 
+  // Apply backend validation and move user to the most relevant step.
   function showErrors(res) {
-    const errs = (res.field_errors || {}).nodes_json || [res.message];
-    $errors.empty();
-    errs.forEach(msg => $errors.append($('<div>').text(msg)));
+    applyServerValidation(res);
+    renderSettings();
+    renderNodeList();
+    renderNodeEditor();
+    if (Object.keys(wizard.settingsFieldErrors).length > 0) {
+      showStep('settings');
+    } else {
+      showStep('nodes');
+    }
   }
 
+  // ---------------------------
+  // Button actions
+  // ---------------------------
   function bindActions() {
     $continueBtn.off('click').on('click', function() {
       syncSettingsFromDom();
@@ -639,19 +508,12 @@ function BranchingStudioEditor(runtime, element, data) {
     });
 
     $saveBtn.off('click').on('click', function() {
+      // Save pipeline: sync draft state and submit full payload for backend-
+      // only validation. Frontend renders structured field errors from server.
       syncSettingsFromDom();
       syncCurrentNodeFromDom();
-      const validation = buildClientValidation();
-      if (validation.errors.length) {
-        wizard.showDeleteValidationErrors = true;
-        wizard.showFieldValidationErrors = true;
-        updateClientValidationUi();
-        renderNodeList();
-        renderNodeEditor();
-        return;
-      }
-      wizard.showDeleteValidationErrors = false;
-      wizard.showFieldValidationErrors = false;
+      clearValidationState();
+      updateClientValidationUi();
 
       const payload = {
         nodes: wizard.draftNodes.map(n => ({
@@ -662,14 +524,15 @@ function BranchingStudioEditor(runtime, element, data) {
             url: (n.media?.type === 'image') ? '' : (n.media?.url || '').trim(),
           },
           choices: Array.isArray(n.choices)
-            ? n.choices
-              .filter(c => c?.text && c?.target_node_id)
-              .map(c => ({
-                text: c.text,
-                target_node_id: c.target_node_id,
-                score: Number.isNaN(Number.parseInt(c.score, 10)) ? 0 : Number.parseInt(c.score, 10),
-              }))
-            : [],
+                ? n.choices
+                  // Keep partially filled choices so backend can return field-level validation.
+                  .filter(c => (c?.text || '').trim() || (c?.target_node_id || '').trim())
+                  .map(c => ({
+                    text: c.text,
+                    target_node_id: c.target_node_id,
+                    score: c.score,
+                  }))
+                : [],
           hint: (n.hint || '').trim(),
           overlay_text: Boolean(n.overlay_text),
           left_image_url: (n.left_image_url || '').trim(),
@@ -687,13 +550,13 @@ function BranchingStudioEditor(runtime, element, data) {
         background_image_alt_text: wizard.draftSettings.background_image_alt_text || '',
         background_image_is_decorative: Boolean(wizard.draftSettings.background_image_is_decorative),
         grade_ranges: (wizard.draftSettings.grade_ranges || []).map((gradeRange) => ({
-          label: String(gradeRange.label || '').trim(),
-          start: Number.parseInt(gradeRange.start, 10),
-          end: Number.parseInt(gradeRange.end, 10),
+          label: gradeRange.label,
+          start: gradeRange.start,
+          end: gradeRange.end,
         })),
       };
 
-      runtime.notify('save', { state: 'start' });
+      $saveBtn.prop('disabled', true);
       $.ajax({
         type: 'POST',
         url: runtime.handlerUrl(element, 'studio_submit'),
@@ -701,14 +564,23 @@ function BranchingStudioEditor(runtime, element, data) {
         contentType: 'application/json; charset=utf-8'
       }).done(function(res) {
         if (res.result === 'success') {
-          runtime.notify('save',  { state: 'end' });
+          // Trigger Studio's global saving animation only for successful saves.
+          runtime.notify('save', { state: 'start' });
+          runtime.notify('save', { state: 'end' });
           runtime.notify('cancel', {});
         } else {
+          // Keep Studio editor open for backend validation errors so
+          // structured field errors can be shown inline.
           showErrors(res);
           $saveBtn.prop('disabled', false);
         }
       }).fail(function() {
+        // Keep editor open on transport/server failures and surface a
+        // top-level message for retry.
         $errors.text('Error saving scenario');
+        $saveValidationSummary
+          .attr('hidden', false)
+          .text("We weren't able to save your selections. Please try again.");
         $saveBtn.prop('disabled', false);
       });
     });
@@ -719,10 +591,16 @@ function BranchingStudioEditor(runtime, element, data) {
     });
   }
 
+  // ---------------------------
+  // Fine-grained interactions
+  // ---------------------------
   function bindInteractions() {
+    // Settings inputs update draft settings live and clear stale server errors.
     $root.off('change.bx-settings input.bx-settings', '[data-role="step-settings"] input, [data-role="step-settings"] textarea');
     $root.on('change.bx-settings input.bx-settings', '[data-role="step-settings"] input, [data-role="step-settings"] textarea', function() {
       syncSettingsFromDom();
+      clearValidationState();
+      updateClientValidationUi();
       const decorative = wizard.draftSettings.background_image_is_decorative;
       const $alt = $stepSettings.find('[name="background_image_alt_text"]');
       $alt.prop('disabled', decorative);
@@ -776,7 +654,10 @@ function BranchingStudioEditor(runtime, element, data) {
       if (Number.isNaN(boundaryIndex)) {
         return;
       }
-      const gradeRanges = wizard.draftSettings.grade_ranges || defaultGradeRanges();
+      const gradeRanges = wizard.draftSettings.grade_ranges;
+      if (!Array.isArray(gradeRanges) || gradeRanges.length < 2) {
+        return;
+      }
       const currentBoundary = gradeRanges[boundaryIndex]?.end;
       if (typeof currentBoundary !== 'number') {
         return;
@@ -799,15 +680,17 @@ function BranchingStudioEditor(runtime, element, data) {
       renderGradeRangeSlider();
     });
 
+    // Node list actions.
     $root.off('click.bx-nodes', '[data-role="add-node"]');
     $root.on('click.bx-nodes', '[data-role="add-node"]', function() {
       if (activeNodes().length >= 30) {
         return;
       }
       syncCurrentNodeFromDom();
-      const node = normalizeNode({});
+      const node = buildDraftNode({});
       wizard.draftNodes.push(node);
       wizard.selectedNodeId = node.id;
+      clearValidationState();
       renderNodeList();
       renderNodeEditor();
       updateFooterUi();
@@ -826,6 +709,7 @@ function BranchingStudioEditor(runtime, element, data) {
       }
       syncCurrentNodeFromDom();
       wizard.selectedNodeId = nodeId;
+      clearValidationState();
       renderNodeList();
       renderNodeEditor();
       updateFooterUi();
@@ -844,18 +728,18 @@ function BranchingStudioEditor(runtime, element, data) {
         return;
       }
       node.pending_delete = !node.pending_delete;
-      wizard.showDeleteValidationErrors = false;
-      wizard.showFieldValidationErrors = false;
+      clearValidationState();
       updateClientValidationUi();
       renderNodeList();
       renderNodeEditor();
       updateFooterUi();
     });
 
+    // Node editor actions.
     $root.off('change.bx-node', '[data-role="media-type"]');
     $root.on('change.bx-node', '[data-role="media-type"]', function() {
       syncCurrentNodeFromDom();
-      wizard.showFieldValidationErrors = false;
+      clearValidationState();
       renderNodeEditor();
       updateClientValidationUi();
     });
@@ -863,7 +747,7 @@ function BranchingStudioEditor(runtime, element, data) {
     $root.off('change.bx-node', '[data-role="no-branches"]');
     $root.on('change.bx-node', '[data-role="no-branches"]', function() {
       syncCurrentNodeFromDom();
-      wizard.showFieldValidationErrors = false;
+      clearValidationState();
       renderNodeEditor();
       updateClientValidationUi();
     });
@@ -878,7 +762,7 @@ function BranchingStudioEditor(runtime, element, data) {
       node.no_branches = false;
       node.choices = Array.isArray(node.choices) ? node.choices : [];
       node.choices.push({ text: '', target_node_id: '', score: 0 });
-      wizard.showFieldValidationErrors = false;
+      clearValidationState();
       renderNodeEditor();
       updateClientValidationUi();
     });
@@ -894,17 +778,18 @@ function BranchingStudioEditor(runtime, element, data) {
       if (!Number.isNaN(idx)) {
         node.choices.splice(idx, 1);
       }
-      wizard.showFieldValidationErrors = false;
+      clearValidationState();
       renderNodeEditor();
       updateClientValidationUi();
     });
   }
 
+  // Bootstrap flow: wire handlers first, then hydrate + render.
   function init() {
     bindActions();
     bindInteractions();
     loadState().then(function(state) {
-      normalizeInitialState(state || {});
+      hydrateInitialState(state || {});
       renderAll();
     });
   }
diff --git a/tests/test_branching_xblock.py b/tests/test_branching_xblock.py
index aa98ec1..ffa945c 100644
--- a/tests/test_branching_xblock.py
+++ b/tests/test_branching_xblock.py
@@ -82,7 +82,9 @@ def test_studio_submit_creates_scenario(rf, block):
             {
                 "id": "temp-1",
                 "content": "First node",
-                "media": {"type": "image", "url": "http://img"},
+                "media": {"type": "image", "url": ""},
+                "left_image_url": "http://img",
+                "right_image_url": "",
                 "choices": [{"text": "Go to 2", "target_node_id": "temp-2", "score": 77}],
                 "transcript_url": ""
             },
@@ -169,7 +171,120 @@ def test_studio_submit_computes_max_score_from_best_path(rf, block):
     result = json.loads(resp.body.decode("utf-8"))
 
     assert result["result"] == "success"
-    assert block.max_score == pytest.approx(40.0)
+    assert block.max_score == 40.0
+
+
+def test_studio_submit_rejects_invalid_choice_score(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Start",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to B", "target_node_id": "temp-2", "score": "1.5"}],
+                "transcript_url": "",
+            },
+            {
+                "id": "temp-2",
+                "content": "End",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+                "transcript_url": "",
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": True,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "error"
+    assert (
+        result["field_errors"]["node_input_errors"]["temp-1"]["choiceScoreByIndex"]["0"]
+        == "Score must be an integer between 0 and 100."
+    )
+    assert "nodes_json" not in result["field_errors"]
+
+
+def test_studio_submit_normalizes_choice_score_from_string(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Start",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to B", "target_node_id": "temp-2", "score": "7"}],
+                "transcript_url": "",
+            },
+            {
+                "id": "temp-2",
+                "content": "End",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+                "transcript_url": "",
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": True,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "success"
+    saved_nodes = block.scenario_data["nodes"]
+    first_node = next(node for node in saved_nodes.values() if node["choices"])
+    assert first_node["choices"][0]["score"] == 7
+    assert block.max_score == 7.0
+
+
+def test_normalize_scenario_nodes_preserves_non_empty_invalid_scores(block):
+    block.scenario_data = {
+        "nodes": {
+            "A": {
+                "id": "A",
+                "type": "start",
+                "choices": [
+                    {"text": "to B", "target_node_id": "B", "score": "1.5"},
+                    {"text": "to B", "target_node_id": "B", "score": "101"},
+                ],
+            },
+            "B": {"id": "B", "type": "end", "choices": []},
+        },
+        "start_node_id": "A",
+    }
+
+    block._normalize_scenario_nodes()
+    node_a = block.scenario_data["nodes"]["A"]
+    assert node_a["choices"][0]["score"] == "1.5"
+    assert node_a["choices"][1]["score"] == "101"
+
+
+def test_normalize_scenario_nodes_defaults_empty_scores_to_zero(block):
+    block.scenario_data = {
+        "nodes": {
+            "A": {
+                "id": "A",
+                "type": "start",
+                "choices": [
+                    {"text": "to B", "target_node_id": "B"},
+                    {"text": "to B", "target_node_id": "B", "score": ""},
+                    {"text": "to B", "target_node_id": "B", "score": "   "},
+                    {"text": "to B", "target_node_id": "B", "score": None},
+                ],
+            },
+            "B": {"id": "B", "type": "end", "choices": []},
+        },
+        "start_node_id": "A",
+    }
+
+    block._normalize_scenario_nodes()
+    node_a = block.scenario_data["nodes"]["A"]
+    assert node_a["choices"][0]["score"] == 0
+    assert node_a["choices"][1]["score"] == 0
+    assert node_a["choices"][2]["score"] == 0
+    assert node_a["choices"][3]["score"] == 0
 
 
 def test_studio_submit_persists_enable_reset_activity(rf, block):
@@ -245,7 +360,7 @@ def test_studio_submit_rejects_invalid_grade_ranges(rf, block):
     resp = block.studio_submit(req)
     result = json.loads(resp.body.decode("utf-8"))
     assert result["result"] == "error"
-    assert any("Grade range" in error for error in result["field_errors"]["nodes_json"])
+    assert "Grade range" in result["field_errors"]["settings_field_errors"]["grade_ranges"]
 
 
 def test_studio_submit_persists_display_name(rf, block):
@@ -335,7 +450,7 @@ def test_studio_submit_fails_on_invalid_target(rf, block):
     resp = block.studio_submit(req)
     result = json.loads(resp.body.decode('utf-8'))
     assert result["result"] == "error"
-    errs = result["field_errors"]["nodes_json"]
+    errs = result["field_errors"]["global_errors"]
     assert any("Invalid target does-not-exist" in e for e in errs)
 
 
@@ -363,8 +478,13 @@ def test_studio_submit_rejects_cycle(rf, block):
     result = json.loads(resp.body.decode("utf-8"))
 
     assert result["result"] == "error"
-    errs = result["field_errors"]["nodes_json"]
+    errs = result["field_errors"]["global_errors"]
     assert any("Circular path detected" in error for error in errs)
+    node_errors = result["field_errors"]["node_action_errors"]
+    assert node_errors["temp-1"]["title"] == "Circular path detected"
+    assert "links back through branching choices" in node_errors["temp-1"]["detail"]
+    assert node_errors["temp-2"]["title"] == "Circular path detected"
+    assert "links back through branching choices" in node_errors["temp-2"]["detail"]
 
 
 def test_studio_submit_rejects_self_loop(rf, block):
@@ -385,10 +505,110 @@ def test_studio_submit_rejects_self_loop(rf, block):
     result = json.loads(resp.body.decode("utf-8"))
 
     assert result["result"] == "error"
-    errs = result["field_errors"]["nodes_json"]
+    errs = result["field_errors"]["global_errors"]
     assert any("Circular path detected" in error for error in errs)
 
 
+def test_studio_submit_rejects_missing_choice_destination(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Node A",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "Go somewhere", "target_node_id": "", "score": 10}],
+            },
+            {
+                "id": "temp-2",
+                "content": "Node B",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+            },
+        ],
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "error"
+    assert (
+        result["field_errors"]["node_input_errors"]["temp-1"]["choiceDestinationByIndex"]["0"]
+        == "Required field"
+    )
+
+
+def test_studio_submit_rejects_deleting_referenced_node_with_node_action_errors(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Node A",
+                "media": {"type": "", "url": ""},
+                "choices": [{"text": "to B", "target_node_id": "temp-2", "score": 5}],
+            },
+            {
+                "id": "temp-2",
+                "content": "Node B",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+            },
+        ],
+        "deleted_node_ids": ["temp-2"],
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "error"
+    assert any("Cannot delete Node" in error for error in result["field_errors"]["global_errors"])
+    node_errors = result["field_errors"]["node_action_errors"]
+    assert node_errors["temp-2"]["title"] == "You can't delete this node"
+    assert "referenced by Node" in node_errors["temp-2"]["detail"]
+
+
+def test_studio_submit_rejects_image_node_without_any_image_urls(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Node A",
+                "media": {"type": "image", "url": ""},
+                "left_image_url": "",
+                "right_image_url": "",
+                "choices": [],
+            },
+        ],
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "error"
+    assert result["field_errors"]["node_input_errors"]["temp-1"]["left_image_url"] == "Please enter a valid URL"
+
+
+def test_studio_submit_rejects_missing_background_alt_text_with_structured_field_error(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": "temp-1",
+                "content": "Start",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+            },
+        ],
+        "background_image_url": "https://example.com/bg.png",
+        "background_image_alt_text": "",
+        "background_image_is_decorative": False,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "error"
+    assert "background_image_alt_text" in result["field_errors"]["settings_field_errors"]
+
+
 def test_studio_submit_accepts_acyclic_graph(rf, block):
     payload = {
         "nodes": [
@@ -421,6 +641,31 @@ def test_studio_submit_accepts_acyclic_graph(rf, block):
     assert result["result"] == "success"
 
 
+def test_studio_submit_handles_non_string_node_id(rf, block):
+    payload = {
+        "nodes": [
+            {
+                "id": 123,
+                "content": "Start",
+                "media": {"type": "", "url": ""},
+                "choices": [],
+            },
+        ],
+        "enable_undo": False,
+        "enable_scoring": False,
+    }
+    req = rf.post("/", data=json.dumps(payload), content_type="application/json")
+    resp = block.studio_submit(req)
+    result = json.loads(resp.body.decode("utf-8"))
+
+    assert result["result"] == "success"
+    saved_nodes = block.scenario_data["nodes"]
+    assert len(saved_nodes) == 1
+    node_id = next(iter(saved_nodes.keys()))
+    assert isinstance(node_id, str)
+    assert node_id.startswith("node-")
+
+
 def test_lazy_initialize_and_select_choice(rf, block):
     """
     On the very first select_choice, current_node_id should be
@@ -473,6 +718,29 @@ def test_select_choice_scores_and_completes(rf, block):
     ]
 
 
+def test_select_choice_rejects_boolean_score_values(rf, block):
+    block.scenario_data = {
+        "nodes": {
+            "A": {"id": "A", "type": "start", "choices": [{"text": "→ B", "target_node_id": "B", "score": True}]},
+            "B": {"id": "B", "type": "end", "choices": []},
+        },
+        "start_node_id": "A",
+    }
+    block.enable_scoring = True
+    req = rf.post(
+        "/", data=json.dumps({"choice_index": 0}), content_type="application/json"
+    )
+    resp = block.select_choice(req)
+    result = json.loads(resp.body.decode('utf-8'))
+
+    assert result["success"] is False
+    assert result["error"] == "Invalid choice score"
+    assert block.current_node_id == "A"
+    assert block.has_completed is False
+    assert block.score == pytest.approx(0.0)
+    assert block.choice_history == []
+
+
 def test_undo_choice_honors_enable_undo(rf, block):
     """
     - With enable_undo=False, undo_choice should fail.

From 8fbc77f814d98e9892c6456ffd02f280c8e64b1d Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 5 Mar 2026 13:49:20 -0500
Subject: [PATCH 27/32] fix: minor fixes

---
 branching_xblock/branching_xblock.py          |  19 ++-
 .../static/js/src/studio_editor.js            | 148 +++++++++---------
 2 files changed, 92 insertions(+), 75 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 5b06227..68947e6 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -171,7 +171,24 @@ def get_node(self, node_id: str) -> Optional[dict[str, Any]]:
 
     def _normalize_scenario_nodes(self) -> None:
         """
-        Normalize stored scenario node payloads once per nodes object.
+        Normalize authoring payload shape for already-persisted scenario nodes.
+
+        Studio can load node data that was saved before newer authoring fields
+        (e.g. `overlay_text`, `left_image_url`, `right_image_url`, normalized
+        `choices[*].score`) existed. Without this pass, the editor can receive
+        inconsistent node objects and fail to render/update reliably.
+
+        What this does:
+        - Ensures `scenario_data["nodes"]` is a dict.
+        - Drops malformed non-dict nodes/choices.
+        - Fills missing node keys required by the current editor schema.
+        - Normalizes choice score shape for editor reads.
+        - Writes back only when changes are needed.
+        - Runs once per `nodes` object via `_normalized_nodes_ref`.
+
+        Removal plan:
+        Once all persisted scenario data is guaranteed to follow the current
+        schema, this can be deleted.
         """
         nodes = self.scenario_data.get("nodes", {})
         if nodes is self._normalized_nodes_ref:
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index 3b7edcb..be989a1 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -26,7 +26,7 @@ function BranchingStudioEditor(runtime, element, data) {
 
   // Keep editor state in a draft model, then sync to/from DOM on transitions.
   // This prevents partial DOM edits from immediately mutating persisted data.
-  const wizard = {
+  const editorState = {
     currentStep: 'settings',
     selectedNodeId: null,
     draftSettings: {},
@@ -51,7 +51,7 @@ function BranchingStudioEditor(runtime, element, data) {
   }
 
   function setBoundaryValue(boundaryIndex, requestedValue) {
-    const gradeRanges = wizard.draftSettings.grade_ranges;
+    const gradeRanges = editorState.draftSettings.grade_ranges;
     if (!Array.isArray(gradeRanges) || gradeRanges.length < 2) {
       return;
     }
@@ -64,7 +64,7 @@ function BranchingStudioEditor(runtime, element, data) {
     const clamped = Math.max(lower, Math.min(upper, requestedValue));
     current.end = clamped;
     next.start = clamped + 1;
-    wizard.draftSettings.grade_ranges = gradeRanges;
+    editorState.draftSettings.grade_ranges = gradeRanges;
   }
 
   function renderGradeRangeSlider() {
@@ -72,13 +72,13 @@ function BranchingStudioEditor(runtime, element, data) {
     if (!$section.length) {
       return;
     }
-    const show = Boolean(wizard.draftSettings.enable_scoring);
+    const show = Boolean(editorState.draftSettings.enable_scoring);
     $section.toggleClass('is-hidden', !show);
     if (!show) {
       return;
     }
 
-    const gradeRanges = wizard.draftSettings.grade_ranges;
+    const gradeRanges = editorState.draftSettings.grade_ranges;
     if (!Array.isArray(gradeRanges) || gradeRanges.length < 2) {
       return;
     }
@@ -168,9 +168,9 @@ function BranchingStudioEditor(runtime, element, data) {
     if (!nodes.length) {
       nodes.push(buildDraftNode({}));
     }
-    wizard.draftNodes = nodes;
-    wizard.selectedNodeId = nodes[0].id;
-    wizard.draftSettings = {
+    editorState.draftNodes = nodes;
+    editorState.selectedNodeId = nodes[0].id;
+    editorState.draftSettings = {
       display_name: state?.display_name || '',
       enable_undo: Boolean(state?.enable_undo),
       enable_scoring: Boolean(state?.enable_scoring),
@@ -186,7 +186,7 @@ function BranchingStudioEditor(runtime, element, data) {
   // Step navigation + selectors
   // ---------------------------
   function showStep(step) {
-    wizard.currentStep = step;
+    editorState.currentStep = step;
     const showSettings = step === 'settings';
     $stepSettings.attr('hidden', !showSettings);
     $stepNodes.attr('hidden', showSettings);
@@ -198,41 +198,41 @@ function BranchingStudioEditor(runtime, element, data) {
   }
 
   function nodeIndexById(nodeId) {
-    return wizard.draftNodes.findIndex(n => n.id === nodeId);
+    return editorState.draftNodes.findIndex(n => n.id === nodeId);
   }
 
   function currentNode() {
-    const idx = nodeIndexById(wizard.selectedNodeId);
-    return idx >= 0 ? wizard.draftNodes[idx] : null;
+    const idx = nodeIndexById(editorState.selectedNodeId);
+    return idx >= 0 ? editorState.draftNodes[idx] : null;
   }
 
   function nodeOptions(excludeNodeId) {
-    return wizard.draftNodes
+    return editorState.draftNodes
       .map((n, idx) => ({ id: n.id, label: `Node ${idx + 1}` }))
       .filter(opt => opt.id !== excludeNodeId);
   }
 
   function activeNodes() {
-    return wizard.draftNodes.filter(node => !node.pending_delete);
+    return editorState.draftNodes.filter(node => !node.pending_delete);
   }
 
   function pendingDeleteNodes() {
-    return wizard.draftNodes.filter(node => node.pending_delete);
+    return editorState.draftNodes.filter(node => node.pending_delete);
   }
 
   // Reset all rendered validation state before a fresh server response is applied.
   function clearValidationState() {
-    wizard.settingsFieldErrors = {};
-    wizard.validationErrors = [];
-    wizard.validationNodeErrorIds = new Set();
-    wizard.validationNodeErrorDetailsById = new Map();
-    wizard.validationNodeErrorTitlesById = new Map();
-    wizard.validationFieldErrorsByNodeId = new Map();
+    editorState.settingsFieldErrors = {};
+    editorState.validationErrors = [];
+    editorState.validationNodeErrorIds = new Set();
+    editorState.validationNodeErrorDetailsById = new Map();
+    editorState.validationNodeErrorTitlesById = new Map();
+    editorState.validationFieldErrorsByNodeId = new Map();
   }
 
   function updateFooterUi() {
     const pendingCount = pendingDeleteNodes().length;
-    if (wizard.currentStep !== 'nodes' || pendingCount === 0 || wizard.validationErrors.length > 0) {
+    if (editorState.currentStep !== 'nodes' || pendingCount === 0 || editorState.validationErrors.length > 0) {
       $pendingDeleteSummary.attr('hidden', true).text('');
       return;
     }
@@ -257,8 +257,8 @@ function BranchingStudioEditor(runtime, element, data) {
       if (!nodeFieldError || typeof nodeFieldError !== 'object') {
         return;
       }
-      wizard.validationFieldErrorsByNodeId.set(nodeId, nodeFieldError);
-      wizard.validationNodeErrorIds.add(nodeId);
+      editorState.validationFieldErrorsByNodeId.set(nodeId, nodeFieldError);
+      editorState.validationNodeErrorIds.add(nodeId);
     });
 
     Object.entries(nodeErrors).forEach(([nodeId, nodeError]) => {
@@ -266,28 +266,28 @@ function BranchingStudioEditor(runtime, element, data) {
         return;
       }
       if (nodeError.title) {
-        wizard.validationNodeErrorTitlesById.set(nodeId, nodeError.title);
+        editorState.validationNodeErrorTitlesById.set(nodeId, nodeError.title);
       }
       if (nodeError.detail) {
-        wizard.validationNodeErrorDetailsById.set(nodeId, nodeError.detail);
+        editorState.validationNodeErrorDetailsById.set(nodeId, nodeError.detail);
       }
-      wizard.validationNodeErrorIds.add(nodeId);
+      editorState.validationNodeErrorIds.add(nodeId);
     });
 
-    wizard.settingsFieldErrors = settingsFieldErrors;
-    wizard.validationErrors = globalErrors.slice();
+    editorState.settingsFieldErrors = settingsFieldErrors;
+    editorState.validationErrors = globalErrors.slice();
   }
 
   // Render top-level summary area when any backend validation errors exist.
   function updateClientValidationUi() {
     const hasInlineFieldErrors =
-      Object.keys(wizard.settingsFieldErrors || {}).length > 0
-      || (wizard.validationFieldErrorsByNodeId && wizard.validationFieldErrorsByNodeId.size > 0)
-      || (wizard.validationNodeErrorIds && wizard.validationNodeErrorIds.size > 0);
+      Object.keys(editorState.settingsFieldErrors || {}).length > 0
+      || (editorState.validationFieldErrorsByNodeId && editorState.validationFieldErrorsByNodeId.size > 0)
+      || (editorState.validationNodeErrorIds && editorState.validationNodeErrorIds.size > 0);
 
-    if (wizard.validationErrors.length > 0 || hasInlineFieldErrors) {
+    if (editorState.validationErrors.length > 0 || hasInlineFieldErrors) {
       $errors.empty();
-      wizard.validationErrors.forEach(msg => $errors.append($('<div>').text(msg)));
+      editorState.validationErrors.forEach(msg => $errors.append($('<div>').text(msg)));
       $saveValidationSummary
         .attr('hidden', false)
         .text("We weren't able to save your selections. Please fix the errors shown and try again.");
@@ -304,17 +304,17 @@ function BranchingStudioEditor(runtime, element, data) {
   // ---------------------------
   function renderSettings() {
     $stepSettings.html(Templates['settings-step']({
-      ...wizard.draftSettings,
-      background_image_url_error: wizard.settingsFieldErrors.background_image_url || '',
-      background_image_alt_text_error: wizard.settingsFieldErrors.background_image_alt_text || '',
-      grade_ranges_error: wizard.settingsFieldErrors.grade_ranges || '',
+      ...editorState.draftSettings,
+      background_image_url_error: editorState.settingsFieldErrors.background_image_url || '',
+      background_image_alt_text_error: editorState.settingsFieldErrors.background_image_alt_text || '',
+      grade_ranges_error: editorState.settingsFieldErrors.grade_ranges || '',
     }));
     renderGradeRangeSlider();
   }
 
   function renderNodeList() {
     const incomingReferenceCounts = new Map();
-    wizard.draftNodes.forEach(node => incomingReferenceCounts.set(node.id, 0));
+    editorState.draftNodes.forEach(node => incomingReferenceCounts.set(node.id, 0));
 
     activeNodes().forEach((sourceNode) => {
       (sourceNode.choices || []).forEach((choice) => {
@@ -330,14 +330,14 @@ function BranchingStudioEditor(runtime, element, data) {
     });
 
     const $list = $stepNodes.find('[data-role="node-list"]').empty();
-    wizard.draftNodes.forEach((n, idx) => {
+    editorState.draftNodes.forEach((n, idx) => {
       const isUnlinked = !n.pending_delete && idx > 0 && (incomingReferenceCounts.get(n.id) || 0) === 0;
       $list.append(Templates['node-list-item']({
         id: n.id,
         number: idx + 1,
-        is_selected: n.id === wizard.selectedNodeId,
+        is_selected: n.id === editorState.selectedNodeId,
         is_pending_delete: Boolean(n.pending_delete),
-        has_errors: wizard.validationNodeErrorIds?.has(n.id),
+        has_errors: editorState.validationNodeErrorIds?.has(n.id),
         is_unlinked: isUnlinked,
       }));
     });
@@ -348,7 +348,7 @@ function BranchingStudioEditor(runtime, element, data) {
 
   function renderNodeEditor() {
     const node = currentNode();
-    const idx = nodeIndexById(wizard.selectedNodeId);
+    const idx = nodeIndexById(editorState.selectedNodeId);
     if (!node || idx < 0) {
       $stepNodes.find('[data-role="node-editor"]').empty();
       return;
@@ -368,7 +368,7 @@ function BranchingStudioEditor(runtime, element, data) {
     const rightImageUrl = isImage
       ? (node.right_image_url ?? '')
       : '';
-    const currentNodeFieldErrors = wizard.validationFieldErrorsByNodeId?.get(node.id) || {};
+    const currentNodeFieldErrors = editorState.validationFieldErrorsByNodeId?.get(node.id) || {};
 
     const html = Templates['node-editor']({
       ...node,
@@ -380,8 +380,8 @@ function BranchingStudioEditor(runtime, element, data) {
       has_choices: hasChoices,
       no_branches: noBranches,
       is_pending_delete: Boolean(node.pending_delete),
-      node_error_title: wizard.validationNodeErrorTitlesById?.get(node.id) || '',
-      node_error_detail: wizard.validationNodeErrorDetailsById?.get(node.id) || '',
+      node_error_title: editorState.validationNodeErrorTitlesById?.get(node.id) || '',
+      node_error_detail: editorState.validationNodeErrorDetailsById?.get(node.id) || '',
       left_image_url_error: currentNodeFieldErrors.left_image_url || '',
       left_image_url: leftImageUrl,
       right_image_url: rightImageUrl,
@@ -413,7 +413,7 @@ function BranchingStudioEditor(runtime, element, data) {
     $errors.empty();
     renderSettings();
     renderNodesStep();
-    showStep(wizard.currentStep);
+    showStep(editorState.currentStep);
     updateFooterUi();
     updateClientValidationUi();
   }
@@ -424,13 +424,13 @@ function BranchingStudioEditor(runtime, element, data) {
   function syncSettingsFromDom() {
     // Pull settings fields into draft state before navigation/save.
     const $s = $stepSettings;
-    wizard.draftSettings.display_name = $s.find('[name="display_name"]').val()?.trim() || '';
-    wizard.draftSettings.enable_undo = $s.find('[name="enable_undo"]').is(':checked');
-    wizard.draftSettings.enable_reset_activity = $s.find('[name="enable_reset_activity"]').is(':checked');
-    wizard.draftSettings.enable_scoring = $s.find('[name="enable_scoring"]').is(':checked');
-    wizard.draftSettings.background_image_url = $s.find('[name="background_image_url"]').val()?.trim() || '';
-    wizard.draftSettings.background_image_is_decorative = $s.find('[name="background_image_is_decorative"]').is(':checked');
-    wizard.draftSettings.background_image_alt_text = $s.find('[name="background_image_alt_text"]').val()?.trim() || '';
+    editorState.draftSettings.display_name = $s.find('[name="display_name"]').val()?.trim() || '';
+    editorState.draftSettings.enable_undo = $s.find('[name="enable_undo"]').is(':checked');
+    editorState.draftSettings.enable_reset_activity = $s.find('[name="enable_reset_activity"]').is(':checked');
+    editorState.draftSettings.enable_scoring = $s.find('[name="enable_scoring"]').is(':checked');
+    editorState.draftSettings.background_image_url = $s.find('[name="background_image_url"]').val()?.trim() || '';
+    editorState.draftSettings.background_image_is_decorative = $s.find('[name="background_image_is_decorative"]').is(':checked');
+    editorState.draftSettings.background_image_alt_text = $s.find('[name="background_image_alt_text"]').val()?.trim() || '';
   }
 
   function syncCurrentNodeFromDom() {
@@ -486,7 +486,7 @@ function BranchingStudioEditor(runtime, element, data) {
     renderSettings();
     renderNodeList();
     renderNodeEditor();
-    if (Object.keys(wizard.settingsFieldErrors).length > 0) {
+    if (Object.keys(editorState.settingsFieldErrors).length > 0) {
       showStep('settings');
     } else {
       showStep('nodes');
@@ -516,7 +516,7 @@ function BranchingStudioEditor(runtime, element, data) {
       updateClientValidationUi();
 
       const payload = {
-        nodes: wizard.draftNodes.map(n => ({
+        nodes: editorState.draftNodes.map(n => ({
           id: n.id,
           content: (n.content || '').trim(),
           media: {
@@ -539,17 +539,17 @@ function BranchingStudioEditor(runtime, element, data) {
           right_image_url: (n.right_image_url || '').trim(),
           transcript_url: (n.transcript_url || '').trim(),
         })),
-        deleted_node_ids: wizard.draftNodes
+        deleted_node_ids: editorState.draftNodes
           .filter(node => node.pending_delete)
           .map(node => node.id),
-        enable_undo: Boolean(wizard.draftSettings.enable_undo),
-        enable_scoring: Boolean(wizard.draftSettings.enable_scoring),
-        enable_reset_activity: Boolean(wizard.draftSettings.enable_reset_activity),
-        display_name: wizard.draftSettings.display_name || '',
-        background_image_url: wizard.draftSettings.background_image_url || '',
-        background_image_alt_text: wizard.draftSettings.background_image_alt_text || '',
-        background_image_is_decorative: Boolean(wizard.draftSettings.background_image_is_decorative),
-        grade_ranges: (wizard.draftSettings.grade_ranges || []).map((gradeRange) => ({
+        enable_undo: Boolean(editorState.draftSettings.enable_undo),
+        enable_scoring: Boolean(editorState.draftSettings.enable_scoring),
+        enable_reset_activity: Boolean(editorState.draftSettings.enable_reset_activity),
+        display_name: editorState.draftSettings.display_name || '',
+        background_image_url: editorState.draftSettings.background_image_url || '',
+        background_image_alt_text: editorState.draftSettings.background_image_alt_text || '',
+        background_image_is_decorative: Boolean(editorState.draftSettings.background_image_is_decorative),
+        grade_ranges: (editorState.draftSettings.grade_ranges || []).map((gradeRange) => ({
           label: gradeRange.label,
           start: gradeRange.start,
           end: gradeRange.end,
@@ -601,12 +601,12 @@ function BranchingStudioEditor(runtime, element, data) {
       syncSettingsFromDom();
       clearValidationState();
       updateClientValidationUi();
-      const decorative = wizard.draftSettings.background_image_is_decorative;
+      const decorative = editorState.draftSettings.background_image_is_decorative;
       const $alt = $stepSettings.find('[name="background_image_alt_text"]');
       $alt.prop('disabled', decorative);
       if (decorative) {
         $alt.val('');
-        wizard.draftSettings.background_image_alt_text = '';
+        editorState.draftSettings.background_image_alt_text = '';
       }
       renderGradeRangeSlider();
     });
@@ -654,7 +654,7 @@ function BranchingStudioEditor(runtime, element, data) {
       if (Number.isNaN(boundaryIndex)) {
         return;
       }
-      const gradeRanges = wizard.draftSettings.grade_ranges;
+      const gradeRanges = editorState.draftSettings.grade_ranges;
       if (!Array.isArray(gradeRanges) || gradeRanges.length < 2) {
         return;
       }
@@ -688,8 +688,8 @@ function BranchingStudioEditor(runtime, element, data) {
       }
       syncCurrentNodeFromDom();
       const node = buildDraftNode({});
-      wizard.draftNodes.push(node);
-      wizard.selectedNodeId = node.id;
+      editorState.draftNodes.push(node);
+      editorState.selectedNodeId = node.id;
       clearValidationState();
       renderNodeList();
       renderNodeEditor();
@@ -700,15 +700,15 @@ function BranchingStudioEditor(runtime, element, data) {
     $root.off('click.bx-nodes', '[data-role="select-node"]');
     $root.on('click.bx-nodes', '[data-role="select-node"]', function() {
       const nodeId = $(this).data('node-id');
-      if (!nodeId || nodeId === wizard.selectedNodeId) {
+      if (!nodeId || nodeId === editorState.selectedNodeId) {
         return;
       }
-      const node = wizard.draftNodes.find(n => n.id === nodeId);
+      const node = editorState.draftNodes.find(n => n.id === nodeId);
       if (!node) {
         return;
       }
       syncCurrentNodeFromDom();
-      wizard.selectedNodeId = nodeId;
+      editorState.selectedNodeId = nodeId;
       clearValidationState();
       renderNodeList();
       renderNodeEditor();
@@ -723,7 +723,7 @@ function BranchingStudioEditor(runtime, element, data) {
         return;
       }
       syncCurrentNodeFromDom();
-      const node = wizard.draftNodes.find(n => n.id === nodeId);
+      const node = editorState.draftNodes.find(n => n.id === nodeId);
       if (!node) {
         return;
       }

From 855077c773186cda38eac8aa199173208b172839 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Wed, 11 Mar 2026 11:55:55 -0400
Subject: [PATCH 28/32] fix: Refine score handling and validation feedback

---
 branching_xblock/branching_xblock.py          | 71 +++++++------------
 .../static/js/src/branching_xblock.js         | 17 +++--
 tests/test_branching_xblock.py                | 42 ++++++-----
 3 files changed, 59 insertions(+), 71 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 68947e6..27c638d 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -7,7 +7,7 @@
 
 from web_fragments.fragment import Fragment
 from xblock.core import XBlock
-from xblock.fields import Boolean, Dict, Float, List, Scope, String
+from xblock.fields import Boolean, Dict, Integer, List, Scope, String
 from xblock.utils.resources import ResourceLoader
 
 from .compat import get_site_configuration_value, sanitize_html
@@ -94,8 +94,8 @@ class BranchingXBlock(XBlock):
         help="Whether the background image is decorative"
     )
 
-    max_score = Float(
-        default=100.0,
+    max_score = Integer(
+        default=100,
         scope=Scope.content,
         help="Score awarded when scenario is completed (if scoring enabled)"
     )
@@ -121,12 +121,6 @@ class BranchingXBlock(XBlock):
         help="Path history for undo functionality"
     )
 
-    score = Float(
-        scope=Scope.user_state,
-        default=0.0,
-        help="Accumulated score (if scoring enabled)"
-    )
-
     score_history = List(
         scope=Scope.user_state,
         default=[],
@@ -358,12 +352,12 @@ def _compute_max_attainable_score(
         self,
         nodes: dict[str, dict[str, Any]],
         start_node_id: Optional[str],
-    ) -> float:
+    ) -> int:
         """
         Compute the maximum total score over all reachable start-to-leaf paths.
         """
         if not start_node_id or start_node_id not in nodes:
-            return 0.0
+            return 0
 
         # Phase 1: collect only nodes reachable from the start node.
         # This intentionally ignores orphan/disconnected nodes so they do not
@@ -438,9 +432,9 @@ def _compute_max_attainable_score(
         # for malformed graph edge-cases.
         if not leaf_scores:
             finite_scores = [score for score in best.values() if score is not None]
-            return float(max(finite_scores)) if finite_scores else 0.0
+            return max(finite_scores) if finite_scores else 0
 
-        return float(max(leaf_scores))
+        return max(leaf_scores)
 
     def _validate_grade_ranges(self, grade_ranges: Any) -> Optional[str]:
         """
@@ -481,8 +475,8 @@ def _build_grade_report(self) -> dict[str, Any]:
         """
         safe_ranges = self.grade_ranges
 
-        max_score = float(self.max_score or 0.0)
-        current_score = max(0.0, float(self.score or 0.0))
+        max_score = int(self.max_score or 0)
+        current_score = self._current_score()
         percentage = 0.0
         if max_score > 0.0:
             percentage = (current_score / max_score) * 100.0
@@ -519,6 +513,16 @@ def _build_grade_report(self) -> dict[str, Any]:
             "detailed_scores": detailed_scores,
         }
 
+    def _current_score(self) -> int:
+        """
+        Compute the learner's accumulated score from score history.
+        """
+        total = 0
+        for awarded_points in (self.score_history or []):
+            if isinstance(awarded_points, int):
+                total += awarded_points
+        return max(0, total)
+
     def get_current_node(self) -> Optional[dict[str, Any]]:
         """
         Get the learner's current node.
@@ -603,14 +607,6 @@ def validate_scenario(self, payload: dict[str, Any]) -> dict[str, Any]:
         cycle_node_ids = self._find_cycle_node_ids(nodes_dict)
         if cycle_node_ids:
             sorted_cycle_ids = sorted(cycle_node_ids)
-            sorted_cycle_labels = ", ".join(sorted_cycle_ids)
-            self._add_global_error(
-                validation_errors,
-                (
-                    "Circular path detected in nodes: "
-                    f"{sorted_cycle_labels}. Remove one of the links in this loop."
-                ),
-            )
             for node_id in sorted_cycle_ids:
                 client_node_id = client_id_by_node_id.get(node_id, node_id)
                 self._add_node_error(
@@ -638,7 +634,7 @@ def publish_grade(self) -> None:
             self.runtime.publish(
                 self,
                 "grade",
-                {"value": self.score, "max_value": self.max_score}
+                {"value": self._current_score(), "max_value": self.max_score}
             )
 
     def resource_string(self, path: str) -> str:
@@ -731,7 +727,7 @@ def _get_state(self) -> dict[str, Any]:
             "score_history":   list(self.score_history),
             "choice_history":  list(self.choice_history),
             "has_completed":   bool(self.has_completed),
-            "score":           self.score,
+            "score":           self._current_score(),
             "grade_report":    self._build_grade_report(),
         }
 
@@ -770,8 +766,7 @@ def select_choice(self, data: dict[str, Any], suffix: str = '') -> dict[str, Any
                 awarded_points = self._parse_choice_score(raw_score)
                 if awarded_points is None:
                     return {"success": False, "error": "Invalid choice score"}
-            self.score += awarded_points
-            self.score_history.append(float(awarded_points))
+            self.score_history.append(awarded_points)
             self.choice_history.append({
                 "source_node_id": self.current_node_id,
                 "choice_text": (choice.get("text") or "").strip(),
@@ -801,8 +796,8 @@ def undo_choice(self, data: dict[str, Any], suffix: str = '') -> dict[str, Any]:
         self.current_node_id = prev_node_id
 
         if self.enable_scoring:
-            awarded_points = self.score_history.pop() if self.score_history else 0.0
-            self.score = max(0.0, self.score - awarded_points)
+            if self.score_history:
+                self.score_history.pop()
             if self.choice_history:
                 self.choice_history.pop()
             self.publish_grade()
@@ -824,7 +819,6 @@ def reset_activity(self, data: dict[str, Any], suffix: str = '') -> dict[str, An
 
         self.score_history = []
         self.choice_history = []
-        self.score = 0.0
         if self.enable_scoring:
             self.publish_grade()
 
@@ -973,15 +967,6 @@ def _validate_references(
                 target_node_client_id = client_id_by_id.get(target_node_id, target_node_id)
 
                 if target_node_id not in staged_node_ids:
-                    source_label = (
-                        f"Node {source_node_number}"
-                        if source_node_number
-                        else node_client_id
-                    )
-                    invalid_target_msg = (
-                        f"Invalid target {raw_target} in {source_label}"
-                    )
-                    self._add_global_error(validation_errors, invalid_target_msg)
                     self._add_node_indexed_error(
                         validation_errors,
                         node_client_id=node_client_id,
@@ -996,24 +981,18 @@ def _validate_references(
 
                 target_node_number = node_number_by_id.get(target_node_id)
                 if source_node_number and target_node_number:
-                    error_message = (
-                        f"Cannot delete Node {target_node_number} because it is "
-                        f"referenced by Node {source_node_number}."
-                    )
                     detail_message = (
                         f"Node {target_node_number} is referenced by Node {source_node_number}."
                     )
                 else:
-                    error_message = "Cannot delete a node that is still referenced by another node."
                     detail_message = "This node is still referenced by another node in this scenario."
 
-                self._add_global_error(validation_errors, error_message)
                 self._add_node_indexed_error(
                     validation_errors,
                     node_client_id=node_client_id,
                     field_name="choiceDestinationByIndex",
                     index=choice_index,
-                    message=error_message,
+                    message="Selected destination is invalid.",
                 )
                 self._add_node_error(
                     validation_errors,
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index b4c2118..b1d7554 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -5,6 +5,7 @@ function BranchingXBlock(runtime, element) {
     let isHintVisible = false;
     let selectedChoiceIndex = null;
     let isReportVisible = false;
+    let currentState = null;
 
     const MEDIA_FILE_REGEX = /\.(mp4|webm|ogg|mp3|wav)(\?|#|$)/i;
 
@@ -139,6 +140,7 @@ function BranchingXBlock(runtime, element) {
     }
 
     function updateView(state) {
+        currentState = state;
         const node = state.current_node || state.nodes[state.start_node_id] || {};
 
         // Active node
@@ -364,11 +366,12 @@ function BranchingXBlock(runtime, element) {
             url: runtime.handlerUrl(element, 'select_choice'),
             type: 'POST',
             data: JSON.stringify({ choice_index: selectedChoiceIndex }),
-            contentType: 'application/json'
-        }).done(() => {
+            contentType: 'application/json',
+            dataType: 'json'
+        }).done((state) => {
             selectedChoiceIndex = null;
             isReportVisible = false;
-            refreshView();
+            updateView(state);
         });
     });
 
@@ -380,12 +383,14 @@ function BranchingXBlock(runtime, element) {
           data: JSON.stringify({}),
           contentType: 'application/json',
           dataType: 'json'
-        }).done(refreshView);
+        }).done(updateView);
     });
 
     $el.on('click', '[data-role="show-report"]', function() {
         isReportVisible = true;
-        refreshView();
+        if (currentState) {
+            updateView(currentState);
+        }
     });
 
     $el.on('click', '[data-role="reset-activity"], [data-role="reset-activity-report"]', function() {
@@ -396,7 +401,7 @@ function BranchingXBlock(runtime, element) {
           data: JSON.stringify({}),
           contentType: 'application/json',
           dataType: 'json'
-        }).done(refreshView);
+        }).done(updateView);
     });
 
     // Initial load
diff --git a/tests/test_branching_xblock.py b/tests/test_branching_xblock.py
index ffa945c..608cf1c 100644
--- a/tests/test_branching_xblock.py
+++ b/tests/test_branching_xblock.py
@@ -69,7 +69,7 @@ def test_get_current_state_empty(rf, block):
     assert state["nodes"] == {}
     assert state["current_node"] is None
     assert state["has_completed"] is False
-    assert state["score"] == 0.0
+    assert state["score"] == 0
 
 
 def test_studio_submit_creates_scenario(rf, block):
@@ -171,7 +171,7 @@ def test_studio_submit_computes_max_score_from_best_path(rf, block):
     result = json.loads(resp.body.decode("utf-8"))
 
     assert result["result"] == "success"
-    assert block.max_score == 40.0
+    assert block.max_score == 40
 
 
 def test_studio_submit_rejects_invalid_choice_score(rf, block):
@@ -236,7 +236,7 @@ def test_studio_submit_normalizes_choice_score_from_string(rf, block):
     saved_nodes = block.scenario_data["nodes"]
     first_node = next(node for node in saved_nodes.values() if node["choices"])
     assert first_node["choices"][0]["score"] == 7
-    assert block.max_score == 7.0
+    assert block.max_score == 7
 
 
 def test_normalize_scenario_nodes_preserves_non_empty_invalid_scores(block):
@@ -450,8 +450,10 @@ def test_studio_submit_fails_on_invalid_target(rf, block):
     resp = block.studio_submit(req)
     result = json.loads(resp.body.decode('utf-8'))
     assert result["result"] == "error"
-    errs = result["field_errors"]["global_errors"]
-    assert any("Invalid target does-not-exist" in e for e in errs)
+    assert (
+        result["field_errors"]["node_input_errors"]["temp-1"]["choiceDestinationByIndex"]["0"]
+        == "Selected destination is invalid."
+    )
 
 
 def test_studio_submit_rejects_cycle(rf, block):
@@ -478,8 +480,6 @@ def test_studio_submit_rejects_cycle(rf, block):
     result = json.loads(resp.body.decode("utf-8"))
 
     assert result["result"] == "error"
-    errs = result["field_errors"]["global_errors"]
-    assert any("Circular path detected" in error for error in errs)
     node_errors = result["field_errors"]["node_action_errors"]
     assert node_errors["temp-1"]["title"] == "Circular path detected"
     assert "links back through branching choices" in node_errors["temp-1"]["detail"]
@@ -505,8 +505,9 @@ def test_studio_submit_rejects_self_loop(rf, block):
     result = json.loads(resp.body.decode("utf-8"))
 
     assert result["result"] == "error"
-    errs = result["field_errors"]["global_errors"]
-    assert any("Circular path detected" in error for error in errs)
+    node_errors = result["field_errors"]["node_action_errors"]
+    assert node_errors["temp-1"]["title"] == "Circular path detected"
+    assert "links back through branching choices" in node_errors["temp-1"]["detail"]
 
 
 def test_studio_submit_rejects_missing_choice_destination(rf, block):
@@ -560,7 +561,10 @@ def test_studio_submit_rejects_deleting_referenced_node_with_node_action_errors(
     result = json.loads(resp.body.decode("utf-8"))
 
     assert result["result"] == "error"
-    assert any("Cannot delete Node" in error for error in result["field_errors"]["global_errors"])
+    assert (
+        result["field_errors"]["node_input_errors"]["temp-1"]["choiceDestinationByIndex"]["0"]
+        == "Selected destination is invalid."
+    )
     node_errors = result["field_errors"]["node_action_errors"]
     assert node_errors["temp-2"]["title"] == "You can't delete this node"
     assert "referenced by Node" in node_errors["temp-2"]["detail"]
@@ -708,7 +712,8 @@ def test_select_choice_scores_and_completes(rf, block):
     assert result["success"] is True
     assert block.current_node_id == "B"
     assert block.has_completed is True
-    assert block.score == pytest.approx(12.0)
+    assert block.score_history == [12]
+    assert result["score"] == 12
     assert block.choice_history == [
         {
             "source_node_id": "A",
@@ -737,7 +742,8 @@ def test_select_choice_rejects_boolean_score_values(rf, block):
     assert result["error"] == "Invalid choice score"
     assert block.current_node_id == "A"
     assert block.has_completed is False
-    assert block.score == pytest.approx(0.0)
+    assert block.score_history == []
+    assert result.get("score", 0) == 0
     assert block.choice_history == []
 
 
@@ -825,7 +831,7 @@ def test_reset_activity_clears_progress_and_score(rf, block):
     block.current_node_id = "end"
     block.history = ["start"]
     block.has_completed = True
-    block.score = 42.0
+    block.score_history = [42]
     block.choice_history = [{"source_node_id": "start", "choice_text": "Next", "awarded_points": 42}]
     req = rf.post("/", data=json.dumps({}), content_type="application/json")
 
@@ -836,11 +842,11 @@ def test_reset_activity_clears_progress_and_score(rf, block):
     assert block.current_node_id == "start"
     assert block.history == []
     assert block.has_completed is False
-    assert block.score == 0.0
+    assert block.score_history == []
     assert block.choice_history == []
     assert result["current_node"]["id"] == "start"
     assert result["has_completed"] is False
-    assert result["score"] == 0.0
+    assert result["score"] == 0
 
 
 def test_reset_activity_clears_scoring_state_when_scoring_disabled(rf, block):
@@ -855,8 +861,7 @@ def test_reset_activity_clears_scoring_state_when_scoring_disabled(rf, block):
     block.current_node_id = "start"
     block.history = ["start"]
     block.has_completed = True
-    block.score = 12.0
-    block.score_history = [12.0]
+    block.score_history = [12]
     block.choice_history = [{"source_node_id": "start", "choice_text": "A", "awarded_points": 12}]
 
     req = rf.post("/", data=json.dumps({}), content_type="application/json")
@@ -864,7 +869,6 @@ def test_reset_activity_clears_scoring_state_when_scoring_disabled(rf, block):
     result = json.loads(resp.body.decode("utf-8"))
 
     assert result["success"] is True
-    assert block.score == 0.0
     assert block.score_history == []
     assert block.choice_history == []
 
@@ -875,7 +879,7 @@ def test_get_current_state_includes_grade_report_data(rf, block):
         {"label": "Pass", "start": 50, "end": 100},
     ]
     block.max_score = 200
-    block.score = 160
+    block.score_history = [80, 80]
     block.choice_history = [
         {"source_node_id": "n1", "choice_text": "Choice 1", "awarded_points": 80},
         {"source_node_id": "n2", "choice_text": "Choice 2", "awarded_points": 80},

From ab9c9963c333c0d2c8ad3fb15a2100047cf03444 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Wed, 11 Mar 2026 15:33:56 -0400
Subject: [PATCH 29/32] fix: inconsistent validation errors

---
 branching_xblock/branching_xblock.py            |  2 +-
 branching_xblock/static/css/studio_editor.css   |  4 ++--
 branching_xblock/static/js/src/studio_editor.js | 11 ++++++++++-
 tests/test_branching_xblock.py                  |  2 +-
 4 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 27c638d..34767d7 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -992,7 +992,7 @@ def _validate_references(
                     node_client_id=node_client_id,
                     field_name="choiceDestinationByIndex",
                     index=choice_index,
-                    message="Selected destination is invalid.",
+                    message="Selected destination is pending deletion.",
                 )
                 self._add_node_error(
                     validation_errors,
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index a07a17c..b8a9286 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -576,7 +576,7 @@
     display: inline-flex;
     align-items: center;
     gap: 6px;
-    font-size: 11px;
+    font-size: 13px;
     line-height: 1.2;
     color: #7c5e00;
     padding: 0;
@@ -595,7 +595,7 @@
     display: inline-flex;
     align-items: center;
     gap: 6px;
-    font-size: 11px;
+    font-size: 13px;
     line-height: 1.2;
     color: #d23228;
 }
diff --git a/branching_xblock/static/js/src/studio_editor.js b/branching_xblock/static/js/src/studio_editor.js
index be989a1..1e2e056 100644
--- a/branching_xblock/static/js/src/studio_editor.js
+++ b/branching_xblock/static/js/src/studio_editor.js
@@ -242,6 +242,12 @@ function BranchingStudioEditor(runtime, element, data) {
       .text(`${pendingCount} ${nodeWord} will be deleted when you save.`);
   }
 
+  function firstErroredNodeId() {
+    return editorState.draftNodes.find(
+      (node) => editorState.validationNodeErrorIds?.has(node.id)
+    )?.id || null;
+  }
+
   // Map backend structured errors into the editor's view model. This is the
   // canonical validation bridge from API contract -> per-field/per-node UI state.
   function applyServerValidation(res) {
@@ -483,6 +489,10 @@ function BranchingStudioEditor(runtime, element, data) {
   // Apply backend validation and move user to the most relevant step.
   function showErrors(res) {
     applyServerValidation(res);
+    const erroredNodeId = firstErroredNodeId();
+    if (erroredNodeId && !editorState.validationNodeErrorIds?.has(editorState.selectedNodeId)) {
+      editorState.selectedNodeId = erroredNodeId;
+    }
     renderSettings();
     renderNodeList();
     renderNodeEditor();
@@ -709,7 +719,6 @@ function BranchingStudioEditor(runtime, element, data) {
       }
       syncCurrentNodeFromDom();
       editorState.selectedNodeId = nodeId;
-      clearValidationState();
       renderNodeList();
       renderNodeEditor();
       updateFooterUi();
diff --git a/tests/test_branching_xblock.py b/tests/test_branching_xblock.py
index 608cf1c..08a363d 100644
--- a/tests/test_branching_xblock.py
+++ b/tests/test_branching_xblock.py
@@ -563,7 +563,7 @@ def test_studio_submit_rejects_deleting_referenced_node_with_node_action_errors(
     assert result["result"] == "error"
     assert (
         result["field_errors"]["node_input_errors"]["temp-1"]["choiceDestinationByIndex"]["0"]
-        == "Selected destination is invalid."
+        == "Selected destination is pending deletion."
     )
     node_errors = result["field_errors"]["node_action_errors"]
     assert node_errors["temp-2"]["title"] == "You can't delete this node"

From c1540a9bc366fdc84b53f4a2428aadc572ac7193 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Wed, 11 Mar 2026 15:59:50 -0400
Subject: [PATCH 30/32] fix: adjust styling

---
 .../static/css/branching_xblock.css           | 19 +++++++++++++
 .../static/handlebars/node-editor.handlebars  |  2 +-
 .../static/html/branching_xblock.html         | 28 +++++++++++--------
 3 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 2c60ebb..8cdc901 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -314,6 +314,19 @@
     flex-wrap: wrap;
 }
 
+.branching-scenario .choice-actions__secondary,
+.branching-scenario .choice-actions__primary {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    flex-wrap: wrap;
+}
+
+.branching-scenario .choice-actions__primary {
+    margin-left: auto;
+    justify-content: flex-end;
+}
+
 .choice-submit-button {
     border: none;
     background-color: #0f62a1;
@@ -669,6 +682,12 @@
         align-items: stretch;
     }
 
+    .branching-scenario .choice-actions__secondary,
+    .branching-scenario .choice-actions__primary {
+        width: 100%;
+        margin-left: 0;
+    }
+
     .undo-button,
     .reset-button,
     .choice-submit-button,
diff --git a/branching_xblock/static/handlebars/node-editor.handlebars b/branching_xblock/static/handlebars/node-editor.handlebars
index 3d026a7..6900328 100644
--- a/branching_xblock/static/handlebars/node-editor.handlebars
+++ b/branching_xblock/static/handlebars/node-editor.handlebars
@@ -78,7 +78,7 @@
 
   <div class="bx-choices {{#if no_branches}}is-hidden{{/if}}" data-role="choices-section">
     <h3 class="bx-section-title">Choices</h3>
-    <div class="bx-help bx-choices-help">When learner selects a choice, its score is added to their total score.</div>
+    <div class="bx-help bx-choices-help">When a learner selects a choice, the score assigned to that choice is added to the total score.</div>
     <div class="choices-container" data-role="choices-container"></div>
     <button type="button" class="bx-btn bx-btn--secondary" data-role="add-choice">Add Choice</button>
   </div>
diff --git a/branching_xblock/static/html/branching_xblock.html b/branching_xblock/static/html/branching_xblock.html
index 4f7b79c..c2585ca 100644
--- a/branching_xblock/static/html/branching_xblock.html
+++ b/branching_xblock/static/html/branching_xblock.html
@@ -16,18 +16,22 @@ <h3 class="choices-heading" data-role="choice-heading">Choose Next Step:</h3>
             <form class="choices-form" data-role="choice-form">
                 <div class="choices-list" data-role="choice-list"></div>
                 <div class="choice-actions">
-                    <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo">
-                        Go Back
-                    </button>
-                    <button type="button" class="reset-button action-secondary btn-secondary" data-role="reset-activity" style="display: none;">
-                        Reset
-                    </button>
-                    <button type="button" class="show-report-button action-primary btn-primary" data-role="show-report" style="display: none;">
-                        Show Report
-                    </button>
-                    <button type="submit" class="choice-submit-button action-primary btn-primary" data-role="submit-choice" disabled>
-                        Submit
-                    </button>
+                    <div class="choice-actions__secondary">
+                        <button type="button" class="undo-button action-secondary btn-secondary" data-role="undo">
+                            Go Back
+                        </button>
+                        <button type="button" class="reset-button action-secondary btn-secondary" data-role="reset-activity" style="display: none;">
+                            Reset
+                        </button>
+                    </div>
+                    <div class="choice-actions__primary">
+                        <button type="button" class="show-report-button action-primary btn-primary" data-role="show-report" style="display: none;">
+                            Show Report
+                        </button>
+                        <button type="submit" class="choice-submit-button action-primary btn-primary" data-role="submit-choice" disabled>
+                            Submit
+                        </button>
+                    </div>
                 </div>
             </form>
         </div>

From b1bfc1add02bef25d76d9f66ec7945c89e521686 Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <13742492+pkulkark@users.noreply.github.com>
Date: Thu, 12 Mar 2026 10:26:07 -0400
Subject: [PATCH 31/32] fix: minor fixes

Co-authored-by: Samuel Allan <samuel.allan@fastmail.com>
---
 branching_xblock/branching_xblock.py               | 6 +-----
 branching_xblock/static/js/src/branching_xblock.js | 2 ++
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/branching_xblock/branching_xblock.py b/branching_xblock/branching_xblock.py
index 34767d7..d3e82fb 100644
--- a/branching_xblock/branching_xblock.py
+++ b/branching_xblock/branching_xblock.py
@@ -517,11 +517,7 @@ def _current_score(self) -> int:
         """
         Compute the learner's accumulated score from score history.
         """
-        total = 0
-        for awarded_points in (self.score_history or []):
-            if isinstance(awarded_points, int):
-                total += awarded_points
-        return max(0, total)
+        return sum(self.score_history)
 
     def get_current_node(self) -> Optional[dict[str, Any]]:
         """
diff --git a/branching_xblock/static/js/src/branching_xblock.js b/branching_xblock/static/js/src/branching_xblock.js
index b1d7554..c4127a8 100644
--- a/branching_xblock/static/js/src/branching_xblock.js
+++ b/branching_xblock/static/js/src/branching_xblock.js
@@ -390,6 +390,8 @@ function BranchingXBlock(runtime, element) {
         isReportVisible = true;
         if (currentState) {
             updateView(currentState);
+        } else {
+            refreshView();
         }
     });
 

From 2f3b7a00db2b96f4a19e679227705a5dd02a547a Mon Sep 17 00:00:00 2001
From: Pooja Kulkarni <pooja@opencraft.com>
Date: Thu, 12 Mar 2026 10:46:19 -0400
Subject: [PATCH 32/32] fix: adjust button styling

---
 .../static/css/branching_xblock.css           |  4 ++--
 branching_xblock/static/css/studio_editor.css | 22 ++++++++++++++-----
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/branching_xblock/static/css/branching_xblock.css b/branching_xblock/static/css/branching_xblock.css
index 8cdc901..3fb5bf2 100644
--- a/branching_xblock/static/css/branching_xblock.css
+++ b/branching_xblock/static/css/branching_xblock.css
@@ -332,8 +332,8 @@
     background-color: #0f62a1;
     color: #fff;
     border-radius: 6px;
-    padding: 0.7rem 1.5rem;
-    font-size: 1rem;
+    padding: 11px 24px;
+    font-size: 16px;
     font-weight: 600;
     cursor: pointer;
     transition: background-color 0.2s ease;
diff --git a/branching_xblock/static/css/studio_editor.css b/branching_xblock/static/css/studio_editor.css
index b8a9286..98c00c7 100644
--- a/branching_xblock/static/css/studio_editor.css
+++ b/branching_xblock/static/css/studio_editor.css
@@ -610,14 +610,26 @@
 
 .xblock-actions .action-primary {
     min-height: 36px;
-    border: 1px solid #006fb9;
+    border: none;
     border-radius: 6px;
-    background: #006fb9;
+    background: #0f62a1;
     color: #fff;
-    padding: 6px 12px;
-    font-size: 14px;
-    font-weight: 500;
+    padding: 0.7rem 1.5rem;
+    font-size: 1rem;
+    font-weight: 600;
     line-height: 1.2;
+    cursor: pointer;
+    transition: background-color 0.2s ease;
+}
+
+.xblock-actions .action-primary:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+.xblock-actions .action-primary:not(:disabled):hover,
+.xblock-actions .action-primary:not(:disabled):focus {
+    background-color: #0c4f83;
 }
 
 .xblock-actions .action-secondary {