burger Sea sub-btn: first-draw --priYl glow handoff (phase 3/3) — TDD

Final slice of the Sea sub-btn rollout (phase 1 = .active wiring 3ae85b9; phase 2 = modal extraction + CONT DRAW 6fbeed7). Adds a --priYl + --ninUser glow that rides the affordance chain to teach the user where to click pre-first-draw.

## The handoff chain

  burger  →  click  →  sea_btn  →  click  →  .sea-select  →  click  →  end

- Modal close (Esc / backdrop / DEL guard-OK) restarts the cycle on the burger.
- Burger fan close w/o sea_btn click ALSO restarts on the burger.
- AUTO DRAW guard-OK ends the cycle permanently (user found the path).
- `#id_sea_action_btn` data-state → 'gate-view' (last card landed via ANY path — AUTO DRAW or manual FLIP) ALSO ends permanently.

## SCSS

`static_src/scss/_burger.scss` — `.glow-handoff` on burger / sea_btn = --priYl color + border + --ninUser glow.
`static_src/scss/_gameboard.scss` — `.glow-handoff` on .sea-select = --terUser border + --ninUser glow (no font-color change per spec).

## Server side

`apps/gameboard/views.py` — new `sea_first_draw_pending = show_picker and not hand_non_empty`. True when picker is active w. an empty hand (paid-draw entry, or page reload of a freshly-entered picker). The FREE-DRAW → picker transition fires client-side w. show_picker=False on the rendered template, so the FREE DRAW JS handler seeds the burger glow itself in that path.

`templates/apps/gameboard/_partials/_burger.html` — `#id_burger_btn` conditionally renders `class="glow-handoff"` when `sea_first_draw_pending`.

`templates/apps/gameboard/my_sea.html` — FREE DRAW transition handler adds `.glow-handoff` to burger at the same SEAT_ANIM_MS moment data-phase swaps to 'picker' (covers the client-side path).

## JS state machine

`templates/apps/gameboard/my_sea.html` — new inline IIFE owns the .glow-handoff transitions:
- `burger.click` → if .glow-handoff on burger, transfer to sea_btn.
- `sea_btn.click` → if .glow-handoff on sea_btn, transfer to .sea-select.
- `.sea-select.click` → end this cycle (just clear the glow; cycle restarts on next modal open).
- AUTO DRAW guard-OK (via doc-level click listener) → sets `autoDrawConfirmed`.
- Modal `hidden`-attr observer: AUTO DRAW path → endPermanently; any other close (Esc / backdrop / DEL) → startOnBurger (skip if glow already permanently ended).
- Burger `class`-attr observer: fan closes (`.active` removed) while glow on sea_btn → restart on burger.
- `#id_sea_action_btn` `data-state`-attr observer: flips to 'gate-view' (last card landed via ANY path — AUTO DRAW finishing OR manual FLIP filling the final slot) → endPermanently.

The data-state observer makes the "stop glowing when all slots filled" guarantee async + decoupled from how the cards arrived.

## CONT DRAW polish (drag-in from prior commit's spec gap)

`apps/gameboard/views.py` — `show_cont_draw` now additionally requires `bool(active_draw.hand)` (at least one card drawn). Pre-draw NVM-to-landing falls through to the existing 3-way state machine (PAID DRAW / GATE VIEW / FREE DRAW) instead of misleading w. CONT DRAW that lands back on an empty picker.

## Tests (4 new ITs)

`apps/gameboard/tests/integrated/test_views.py::MySeaViewTest`:
- `test_burger_renders_glow_handoff_class_when_sea_first_draw_pending` — paid-draw entry to picker w. empty hand → burger has .glow-handoff.
- `test_burger_omits_glow_handoff_when_hand_non_empty` — mid-draw → no .glow-handoff.
- `test_burger_omits_glow_handoff_on_landing` — landing → no .glow-handoff (FREE DRAW handler seeds client-side instead).
- `test_force_landing_hides_cont_draw_when_hand_empty` — pre-first-draw NVM → no CONT DRAW.

(JS state-machine behaviour is verified visually; not Jasmine-tested since the IIFE lives inline on my_sea.html, not as a separate module.)

## Verification

All 1374 IT+UT green (+4 from Phase 3). Visual verification of glow handoff + hand-complete auto-end confirmed.

Code architected by Disco DeDisco <discodedisco@outlook.com>
Git commit message Co-Authored-By:
Claude Sonnet 4.6 <noreply@anthropic.com>

src/apps/gameboard/tests/integrated/test_views.py

@@ -1157,6 +1157,84 @@ class MySeaViewTest(TestCase):
         self.assertNotContains(response, 'id="id_my_sea_cont_draw_btn"')
         self.assertContains(response, 'id="id_draw_sea_btn"')
 
+    def test_burger_renders_glow_handoff_class_when_sea_first_draw_pending(self):
+        """When picker phase is active + hand is still empty (paid-draw
+        entry, or page reload of an empty picker), the burger btn renders
+        w. .glow-handoff so the first-draw nudge cycle starts on it.
+        Picker w. an empty hand requires the paid-draw context — the
+        FREE-DRAW client-side transition seeds the class via JS instead
+        (see my_sea.html DRAW SEA handler)."""
+        from apps.epic.models import personal_sig_cards
+        from apps.gameboard.models import MySeaDraw
+        from apps.lyric.models import Token
+        from datetime import timedelta
+        from django.utils import timezone
+        sig = personal_sig_cards(self.user)[0]
+        self.user.significator = sig
+        self.user.save(update_fields=["significator"])
+        free_tok = Token.objects.create(
+            user=self.user, token_type=Token.FREE,
+            expires_at=timezone.now() + timedelta(days=30),
+        )
+        MySeaDraw.objects.create(
+            user=self.user, spread="situation-action-outcome",
+            significator_id=sig.id, hand=[],
+            deposit_token_id=free_tok.pk,
+            deposit_reserved_at=timezone.now(),
+        )
+        response = self.client.get(reverse("my_sea") + "?phase=picker")
+        # Burger btn rendered w. .glow-handoff (server-side seed)
+        self.assertContains(
+            response,
+            '<button id="id_burger_btn" type="button" aria-label="Open burger menu" aria-expanded="false" class="glow-handoff">',
+        )
+
+    def test_burger_omits_glow_handoff_when_hand_non_empty(self):
+        """Mid-draw picker (hand has at least 1 card) — first-draw nudge
+        is over, burger renders w/o .glow-handoff."""
+        from apps.epic.models import personal_sig_cards, TarotCard
+        from apps.gameboard.models import MySeaDraw
+        sig = personal_sig_cards(self.user)[0]
+        self.user.significator = sig
+        self.user.save(update_fields=["significator"])
+        card = TarotCard.objects.exclude(pk=sig.pk).first()
+        MySeaDraw.objects.create(
+            user=self.user, spread="situation-action-outcome",
+            significator_id=sig.id,
+            hand=[{"position": "lay", "card_id": card.id,
+                   "reversed": False, "polarity": "gravity"}],
+        )
+        response = self.client.get(reverse("my_sea"))
+        self.assertNotContains(response, 'class="glow-handoff"')
+
+    def test_burger_omits_glow_handoff_on_landing(self):
+        """Landing phase (no sig, or sig w/o draw) — burger renders w/o
+        glow. FREE DRAW transition adds the class client-side; server-
+        rendered state stays clean to avoid a flash before user interaction."""
+        from apps.epic.models import personal_sig_cards
+        sig = personal_sig_cards(self.user)[0]
+        self.user.significator = sig
+        self.user.save(update_fields=["significator"])
+        response = self.client.get(reverse("my_sea"))
+        self.assertNotContains(response, 'class="glow-handoff"')
+
+    def test_force_landing_hides_cont_draw_when_hand_empty(self):
+        """`?phase=landing` w. an active draw row BUT no cards yet → CONT
+        DRAW absent (nothing to continue — picker hasn't started). The
+        landing's existing 3-way state machine takes over (PAID DRAW when
+        deposit reserved, GATE VIEW for in-cooldown no-deposit, etc.)."""
+        from apps.epic.models import personal_sig_cards
+        from apps.gameboard.models import MySeaDraw
+        sig = personal_sig_cards(self.user)[0]
+        self.user.significator = sig
+        self.user.save(update_fields=["significator"])
+        MySeaDraw.objects.create(
+            user=self.user, spread="situation-action-outcome",
+            significator_id=sig.id, hand=[],
+        )
+        response = self.client.get(reverse("my_sea") + "?phase=landing")
+        self.assertNotContains(response, 'id="id_my_sea_cont_draw_btn"')
+
     def test_force_landing_hides_cont_draw_when_hand_complete(self):
         """`?phase=landing` w. a complete hand → CONT DRAW absent (nothing
         to continue). GATE VIEW takes over via the existing landing state

src/apps/gameboard/views.py

@@ -283,8 +283,10 @@ def my_sea(request):
     show_picker = (hand_non_empty or (phase_param and show_paid_draw)) \
                   and not force_landing
     show_cont_draw = (
-        force_landing and active_draw is not None
+        force_landing
-        and not active_draw.is_hand_complete
+        and active_draw is not None
+        and bool(active_draw.hand)            # at least 1 card drawn
+        and not active_draw.is_hand_complete  # but not all
     )
 
     # Per-position lookup for the template — keyed by the position slug
@@ -367,6 +369,13 @@ def my_sea(request):
         # `show_picker and not hand_complete`; that locked DEL + GATE VIEW
         # behind an inactive btn once all cards landed.
         "sea_btn_active": show_picker,
+        # Phase 3 of the Sea sub-btn rollout — pre-first-draw glow handoff.
+        # True when picker phase is active + hand still empty (paid-draw
+        # entry, or page reload of an empty picker). The fresh DRAW SEA
+        # → picker transition happens client-side w. show_picker=False on
+        # the rendered template, so the FREE-DRAW JS handler ALSO sets the
+        # glow on burger in that path.
+        "sea_first_draw_pending": show_picker and not hand_non_empty,
         "show_paid_draw": show_paid_draw,
         "show_gate_view": show_gate_view,
         "deposit_reserved": deposit_reserved,

src/static_src/scss/_burger.scss

@@ -164,6 +164,25 @@
     .burger-fan-icon--off { display: inline-block; }
 }
 
+// ── First-draw glow handoff (phase 3 of the Sea sub-btn rollout) ─────
+//
+// Pre-first-draw nudge for the my-sea picker: a --priYl + --ninUser glow
+// rides the affordance chain to teach the user where to click.
+//
+//   burger  →  click  →  sea_btn  →  click  →  .sea-select  →  click  →  end
+//
+// Modal close (Esc / backdrop / DEL) w/o AUTO DRAW restarts the cycle on
+// the burger. AUTO DRAW's guard-OK ends the cycle permanently (the user
+// has actually drawn — they've found the path). Owner: my_sea.html JS.
+#id_burger_btn.glow-handoff,
+#id_sea_btn.glow-handoff {
+    color: rgba(var(--priYl), 1);
+    border-color: rgba(var(--priYl), 1);
+    box-shadow:
+        0 0 0.5rem 0.1rem rgba(var(--ninUser), 0.75),
+        0 0 1.2rem 0.3rem rgba(var(--ninUser), 0.35);
+}
+
 // Burger hides when bud_panel is open — LANDSCAPE only. In portrait the
 // burger sits ABOVE the bud panel (bottom:4.2rem vs panel at bottom:0.5
 // + height:3rem); no visual conflict. In landscape they share the

src/static_src/scss/_gameboard.scss

@@ -710,6 +710,16 @@ body.page-gameboard {
     cursor: default;
 }
 
+// Third hop of the first-draw glow handoff (see _burger.scss for the
+// full chain). .sea-select gets a --terUser border + --ninUser glow but
+// NOT the font-color change — its current spread text reads normally.
+.sea-select.glow-handoff {
+    border-color: rgba(var(--terUser), 1);
+    box-shadow:
+        0 0 0.5rem 0.1rem rgba(var(--ninUser), 0.75),
+        0 0 1.2rem 0.3rem rgba(var(--ninUser), 0.35);
+}
+
 // ── My Sea spread modal (Phase 2 of the burger Sea sub-btn rollout) ──
 //
 // Holds the .sea-form-col chrome (spread combobox + AUTO DRAW + DEL).

src/templates/apps/gameboard/_partials/_burger.html

@@ -8,7 +8,7 @@
 {# sub-btns are inactive; clicking an inactive sub-btn flashes a brief    #}
 {# --priRd glow (twice, fast cadence) — burger-btn.js owns the delegated #}
 {# click + flash.                                                         #}
-<button id="id_burger_btn" type="button" aria-label="Open burger menu" aria-expanded="false">
+<button id="id_burger_btn" type="button" aria-label="Open burger menu" aria-expanded="false"{% if sea_first_draw_pending %} class="glow-handoff"{% endif %}>
     <i class="fa-solid fa-burger"></i>
 </button>
 <div id="id_burger_fan" aria-hidden="true">

src/templates/apps/gameboard/my_sea.html

@@ -1009,6 +1009,12 @@
                             // + GATE VIEW stay reachable inside the modal.
                             var seaBtn = document.getElementById('id_sea_btn');
                             if (seaBtn) seaBtn.classList.add('active');
+                            // Phase 3 — the FREE DRAW path enters the picker
+                            // w. an empty hand → first-draw pending. Start
+                            // the glow handoff on the burger so the user
+                            // knows where to click next.
+                            var burgerBtn = document.getElementById('id_burger_btn');
+                            if (burgerBtn) burgerBtn.classList.add('glow-handoff');
                         }, SEAT_ANIM_MS);
                     });
                 }
@@ -1149,5 +1155,120 @@
             });
         }());
         </script>
+
+        {# Phase 3 — first-draw glow handoff state machine. Owner of the     #}
+        {# .glow-handoff transitions across burger → sea_btn → sea-select →  #}
+        {# end. Modal close w/o AUTO DRAW restarts at burger. AUTO DRAW      #}
+        {# guard-OK ends the cycle permanently. The initial glow on burger   #}
+        {# is set either server-side (see sea_first_draw_pending below) OR   #}
+        {# client-side in the FREE DRAW handler that transitions data-phase  #}
+        {# to 'picker'.                                                       #}
+        <script>
+        (function () {
+            var burgerBtn = document.getElementById('id_burger_btn');
+            var seaBtn = document.getElementById('id_sea_btn');
+            var modal = document.getElementById('id_sea_spread_modal');
+            if (!burgerBtn || !seaBtn || !modal) return;
+
+            var seaSelect = modal.querySelector('.sea-select');
+            var actionBtn = document.getElementById('id_sea_action_btn');
+            if (!seaSelect || !actionBtn) return;
+
+            var glowDone = false;
+            var autoDrawConfirmed = false;
+            // Set by ANY guard-YES (AUTO DRAW or DEL). Distinguishes "user
+            // confirmed a destructive action" from "user dismissed the
+            // modal w/o action". Latter restarts the glow on burger; former
+            // doesn't — a page redirect is en route (DEL) or AUTO DRAW
+            // anim is taking over (endPermanently). Without this flag, DEL
+            // briefly flashed burger w. glow before the post-DEL redirect.
+            var guardYesClosing = false;
+
+            function startOnBurger() {
+                if (glowDone) return;
+                burgerBtn.classList.add('glow-handoff');
+                seaBtn.classList.remove('glow-handoff');
+                seaSelect.classList.remove('glow-handoff');
+            }
+
+            function endPermanently() {
+                glowDone = true;
+                burgerBtn.classList.remove('glow-handoff');
+                seaBtn.classList.remove('glow-handoff');
+                seaSelect.classList.remove('glow-handoff');
+            }
+
+            // burger click → glow hands off to sea_btn (only if burger had it)
+            burgerBtn.addEventListener('click', function () {
+                if (glowDone) return;
+                if (!burgerBtn.classList.contains('glow-handoff')) return;
+                burgerBtn.classList.remove('glow-handoff');
+                seaBtn.classList.add('glow-handoff');
+            });
+
+            // sea_btn click → glow hands off to .sea-select (modal opens too,
+            // owned by the Phase 2 IIFE above — both run in target phase, no
+            // ordering coupling).
+            seaBtn.addEventListener('click', function () {
+                if (glowDone) return;
+                if (!seaBtn.classList.contains('glow-handoff')) return;
+                seaBtn.classList.remove('glow-handoff');
+                seaSelect.classList.add('glow-handoff');
+            });
+
+            // .sea-select click → cycle ends (this round). Glow doesn't move
+            // anywhere; it just clears. Cycle restarts if modal closes w/o
+            // AUTO DRAW (see MutationObserver below).
+            seaSelect.addEventListener('click', function () {
+                if (glowDone) return;
+                seaSelect.classList.remove('glow-handoff');
+            });
+
+            // AUTO DRAW guard-OK → mark the next modal-close as the permanent
+            // end (the draw is about to happen — user found the path).
+            document.addEventListener('click', function (e) {
+                if (!e.target.closest('#id_guard_portal .guard-yes')) return;
+                if (actionBtn.dataset.state === 'auto-draw') {
+                    autoDrawConfirmed = true;
+                }
+            });
+
+            // Modal close handler — observes the `hidden` attribute. If the
+            // close was triggered by AUTO DRAW guard-OK, end the cycle for
+            // good. Otherwise restart on burger so the user gets another
+            // nudge cycle the next time they open the modal.
+            var observer = new MutationObserver(function (mutations) {
+                for (var i = 0; i < mutations.length; i++) {
+                    var m = mutations[i];
+                    if (m.attributeName !== 'hidden') continue;
+                    if (!modal.hasAttribute('hidden')) continue;
+                    if (autoDrawConfirmed) {
+                        endPermanently();
+                        autoDrawConfirmed = false;
+                    } else if (!glowDone) {
+                        startOnBurger();
+                    }
+                }
+            });
+            observer.observe(modal, {attributes: true, attributeFilter: ['hidden']});
+
+            // Hand-complete observer — end the glow permanently when ALL
+            // slots are filled, regardless of how (AUTO DRAW or manual
+            // FLIP). #id_sea_action_btn's data-state flips to 'gate-view'
+            // at that exact moment (see the picker IIFE _setComplete).
+            // Async + decoupled from guard-YES tracking — works for both
+            // the AUTO DRAW path AND the all-manual-FLIP path.
+            var actionObserver = new MutationObserver(function (mutations) {
+                for (var i = 0; i < mutations.length; i++) {
+                    var m = mutations[i];
+                    if (m.attributeName !== 'data-state') continue;
+                    if (actionBtn.dataset.state === 'gate-view') {
+                        endPermanently();
+                    }
+                }
+            });
+            actionObserver.observe(actionBtn, {attributes: true, attributeFilter: ['data-state']});
+        }());
+        </script>
     </div>
 {% endblock content %}