@energy8platform/shell 0.7.2 → 0.9.0

package/dist/pixi.d.ts

@@ -162,6 +162,11 @@ interface BonusOption$1 {
     priceMultiplier: number;
     /** Per-option accent override. Falls back to the type default (bonus → purple, feature → gold). */
     accentColor?: string;
+    /** Options sharing a `groupedBy` key occupy ONE card slot and are flipped through with arrows —
+     *  e.g. four same-priced Ante variants that each swap the character, its art and its volatility.
+     *  Pixi shell only; the DOM shell ignores the key and keeps a card per option. Options with a
+     *  `custom` renderer are never grouped. */
+    groupedBy?: string;
     /** Override the card UI. Return the card's inner content; the shell keeps the grid wrapper,
      *  accent vars and live re-pricing, and runs the normal buy flow when you call `ctx.select()`.
      *  Core uses `unknown`; each renderer re-exports a typed alias (ui/html → HTMLElement,
@@ -300,8 +305,13 @@ interface AutoplayConfig {
 }
 interface ShellFeatures {
     turbo: 0 | 1 | 2 | 3;
-    /** Master keyboard-shortcut switch. Defaults to `true`; set `false` to disable ALL hotkeys
-     *  (overrides `spacebar` and any future hotkey). */
+    /** Master keyboard-shortcut switch: `false` disables ALL hotkeys (overrides `spacebar` and any
+     *  future hotkey) AND hides the Hotkeys section of Game Info, including one the game supplied
+     *  itself — a keycap chart for keys that do nothing is worse than no chart.
+     *
+     *  Left unset, the shell measures the client (`core/device.ts`): a touchscreen has no keys to
+     *  press, so it gets neither the shortcuts nor the chart. Set it explicitly when you know better
+     *  than the media query — which is what the host does with the platform's `device` field. */
     hotkeys?: boolean;
     /** Spacebar starts a spin in base mode. Defaults to `true`; set `false` to disable the
      *  keyboard shortcut (e.g. jurisdictions that forbid quick-spin keys). */
@@ -633,7 +643,7 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.7.2";
+    readonly engineVersion = "0.9.0";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
@@ -778,7 +788,7 @@ interface I18n {
 declare function createI18n(opts: I18nOptions): I18n;
 
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-declare const PACKAGE_VERSION = "0.7.2";
+declare const PACKAGE_VERSION = "0.9.0";
 
 /** A shell: the renderer-agnostic controller plus the surface facade (safeArea/barHeight/setVisible)
  *  an embedding host reads. `createShell`, `createGameShell` and `createPixiShell` all return this. */

package/dist/pixi.esm.js

@@ -1690,9 +1690,41 @@ class KeyboardController {
     }
 }
 
+/**
+ * Can the player in front of this client actually press a key?
+ *
+ * The shell documents its shortcuts in a Hotkeys section and binds Spacebar to spin. On a phone
+ * neither is reachable, and showing a keycap chart to someone holding a touchscreen is a promise
+ * the game can't keep — a certification lab reads it as a feature offered where it doesn't work.
+ *
+ * The question is deliberately NOT "is the layout narrow" (a portrait desktop window still has a
+ * keyboard) and NOT "is there a touchscreen" (a touch laptop has both). It is: what does the
+ * PRIMARY pointer look like, and can it hover? Coarse-and-hoverless is a touchscreen, and a
+ * touchscreen is the one case where the keys genuinely aren't there.
+ *
+ * A tablet with a keyboard case answers "coarse, no hover" too and loses the chart. That is the
+ * right side to be wrong on: the chart is a convenience, and the keys keep working for anyone who
+ * has them — the media query only decides what the shell ADVERTISES (hosts can still say outright,
+ * via `features.hotkeys`, and the platform's own `device` field does exactly that).
+ */
+/** A touchscreen: the primary pointer is a finger, and nothing can hover. */
+const TOUCH_ONLY = '(pointer: coarse) and (hover: none)';
+function keyboardCapable(win = typeof window === 'undefined' ? undefined : window) {
+    // No window (SSR, node tests) or a browser too old for matchMedia: assume a keyboard rather than
+    // silently stripping shortcuts from a desktop we simply failed to measure.
+    if (typeof win?.matchMedia !== 'function')
+        return true;
+    try {
+        return !win.matchMedia(TOUCH_ONLY).matches;
+    }
+    catch {
+        return true;
+    }
+}
+
 // AUTO-GENERATED by scripts/gen-version.mjs — do not edit. Mirrors package.json "version".
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-const PACKAGE_VERSION = '0.7.2';
+const PACKAGE_VERSION = '0.9.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {
@@ -1706,7 +1738,10 @@ function resolveConfig(config) {
         win: config.win,
         mode: config.mode,
         gameInfo: config.gameInfo,
-        features: config.features,
+        // `hotkeys` unset means "decide for me": a touchscreen has no keys to press, so the shell
+        // neither binds them nor advertises them there. A host that knows better — the platform's own
+        // `device` field, a jurisdiction rule — says so outright and that wins. See core/device.ts.
+        features: { ...config.features, hotkeys: config.features.hotkeys ?? keyboardCapable() },
         theme: config.theme,
         onBonusBuy: config.onBonusBuy,
         volumes: config.volumes,
@@ -1800,7 +1835,11 @@ class ShellController extends EventEmitter {
                 this.renderer.renderBar();
             },
             toggleAutoplay: () => {
-                if (this.state.autoplay.active)
+                // A halted run (stopped, but with spins still owed after a lost connection) counts as
+                // "autoplay is on screen": the toggle retires its leftover count, exactly as it stops a
+                // running one. Resuming those spins is the disc's job, not this one's.
+                const { active, remaining } = this.state.autoplay;
+                if (active || remaining > 0)
                     a.stopAutoplay();
                 else
                     this.openAutoplayPicker();
@@ -3087,6 +3126,7 @@ class SpinDisc extends Container {
     rotTick;
     onSpin;
     onStop;
+    onResume;
     constructor(opts) {
         super();
         this.size = opts.size ?? 84;
@@ -3095,6 +3135,7 @@ class SpinDisc extends Container {
         this.ticker = opts.ticker;
         this.onSpin = opts.onSpin;
         this.onStop = opts.onStop;
+        this.onResume = opts.onResume ?? opts.onSpin;
         this.disc = new Graphics();
         this.glyph = makeIcon('spin', this.glyphSize, this.tokens.btnInk);
         this.glyph.position.set((this.size - this.glyphSize) / 2, (this.size - this.glyphSize) / 2);
@@ -3115,6 +3156,8 @@ class SpinDisc extends Container {
                 return;
             if (this.mode === 'stop')
                 this.onStop();
+            else if (this.mode === 'resume')
+                this.onResume();
             else
                 this.onSpin();
         });
@@ -3126,9 +3169,10 @@ class SpinDisc extends Container {
         drawDisc(this.disc, this.size, this.tokens.btn, 4);
         const glyphColor = hot ? this.tokens.accent : this.tokens.btnInk;
         this.glyph.setColor(glyphColor);
-        // the count sits ON the solid (btnInk) STOP square, so it must be light to read
+        // the count sits ON the solid (btnInk) STOP square, so it must be light to read; halted, it
+        // sits on the bare disc instead and takes the disc's own ink.
         if (this.countText)
-            this.countText.style.fill = '#ffffff';
+            this.countText.style.fill = this.mode === 'resume' ? this.tokens.btnInk : '#ffffff';
         // Disabled (mid-spin / can't spin): darken OPAQUELY (≈ filter:grayscale(.4) brightness(.62))
         // with a dark veil over the disc — not alpha, which would let the bright board show through and
         // read as a translucent/missing button (what looked "transparent" while spinning).
@@ -3137,32 +3181,45 @@ class SpinDisc extends Container {
             this.dim.circle(this.size / 2, this.size / 2, this.size / 2 - 1.5).fill({ color: 0x000000, alpha: 0.4 });
         }
     }
-    /** STOP glyph + remaining-count, when autoplay runs. */
-    setAutoplay(active, remaining) {
-        if (active) {
-            this.mode = 'stop';
-            this.stopRotation();
-            // STOP glyph at the disc's full size (like SPIN); the count is centred on top of it.
-            this.glyph.visible = false;
-            this.stopGlyph();
-            if (!this.countText) {
-                this.countText = makeText('', { size: 22, weight: '800', color: '#ffffff', align: 'center', family: NUM_FONT_FAMILY });
-                this.addChild(this.countText); // added after the STOP glyph → renders on top of it
-            }
-            const label = Number.isFinite(remaining) ? String(remaining) : '∞';
-            setText(this.countText, label);
-            this.countText.position.set((this.size - this.countText.width) / 2, (this.size - this.countText.height) / 2);
-        }
-        else {
+    /** STOP glyph + remaining-count while autoplay runs; auto glyph + the same count once it halts. */
+    setAutoplay(mode, remaining) {
+        if (mode === 'off') {
             this.mode = 'spin';
             this.glyph.visible = true;
             this.removeStopGlyph();
+            this.removeAutoGlyph();
             if (this.countText) {
                 this.removeChild(this.countText);
                 this.countText.destroy();
                 this.countText = undefined;
             }
+            this.paint();
+            return;
         }
+        const running = mode === 'running';
+        this.mode = running ? 'stop' : 'resume';
+        this.stopRotation();
+        this.glyph.visible = false;
+        // Running: a solid STOP square at the disc's full size (like SPIN), count centred on top of it.
+        // Halted: the auto glyph, smaller and lifted, with the count under it — no dark square, because
+        // nothing is running to stop, and a white count would have nothing to read against.
+        if (running) {
+            this.removeAutoGlyph();
+            this.stopGlyph();
+        }
+        else {
+            this.removeStopGlyph();
+            this.autoGlyph();
+        }
+        if (!this.countText) {
+            this.countText = makeText('', { size: 22, weight: '800', color: '#ffffff', align: 'center', family: NUM_FONT_FAMILY });
+            this.addChild(this.countText); // added after the glyph → renders on top of it
+        }
+        setText(this.countText, Number.isFinite(remaining) ? String(remaining) : '∞');
+        const cy = running
+            ? (this.size - this.countText.height) / 2
+            : this.size * 0.56; // sits under the lifted auto glyph
+        this.countText.position.set((this.size - this.countText.width) / 2, cy);
         this.paint();
     }
     stopGlyphView;
@@ -3180,6 +3237,22 @@ class SpinDisc extends Container {
             this.stopGlyphView = undefined;
         }
     }
+    autoGlyphView;
+    autoGlyph() {
+        if (this.autoGlyphView)
+            return;
+        const size = this.glyphSize * 0.42;
+        this.autoGlyphView = makeIcon('autoplay', size, this.tokens.btnInk);
+        this.autoGlyphView.position.set((this.size - size) / 2, this.size * 0.2);
+        this.addChild(this.autoGlyphView);
+    }
+    removeAutoGlyph() {
+        if (this.autoGlyphView) {
+            this.removeChild(this.autoGlyphView);
+            this.autoGlyphView.destroy();
+            this.autoGlyphView = undefined;
+        }
+    }
     setBusy(busy) {
         this._busy = busy;
         if (busy && this.mode === 'spin')
@@ -3410,6 +3483,13 @@ function divider(tokens, height = 30) {
 }
 
 // ── design constants (mirror the DOM `.ge-bar-panel` / mobile rules) ──────────
+/** Which of the disc's three faces the autoplay state calls for — see `SpinAutoplayMode`. A run
+ *  that halted with spins still owed (`!active && remaining > 0`) keeps its counter on the disc. */
+function autoplayDiscMode(state) {
+    if (state.autoplay.active)
+        return 'running';
+    return state.autoplay.remaining > 0 ? 'paused' : 'off';
+}
 const BAR_H = 68; // continuous dark panel height
 const SPIN = 84; // hero disc — pops above/below the bar
 const SPIN_POP = (SPIN - BAR_H) / 2; // 8 — how far the disc sticks out top/bottom
@@ -3658,9 +3738,9 @@ class BottomBar extends Container {
                 ticker: this.host.ticker,
                 onSpin: () => this.host.actions.spin(),
                 onStop: () => this.stopAutoplay(),
+                onResume: () => this.resumeAutoplay(),
             });
-            if (state.autoplay.active)
-                this.spin.setAutoplay(true, state.autoplay.remaining);
+            this.spin.setAutoplay(autoplayDiscMode(state), state.autoplay.remaining);
             if (state.busy)
                 this.spin.setBusy(true);
             spinWrap.add(this.spin);
@@ -3732,9 +3812,9 @@ class BottomBar extends Container {
                 ticker: this.host.ticker,
                 onSpin: () => this.host.actions.spin(),
                 onStop: () => this.stopAutoplay(),
+                onResume: () => this.resumeAutoplay(),
             });
-            if (state.autoplay.active)
-                this.spin.setAutoplay(true, state.autoplay.remaining);
+            this.spin.setAutoplay(autoplayDiscMode(state), state.autoplay.remaining);
             if (state.busy)
                 this.spin.setBusy(true);
             hero = this.spin;
@@ -3929,8 +4009,11 @@ class BottomBar extends Container {
     onTurbo() {
         this.host.actions.cycleTurbo();
     }
+    /** Same button, three jobs: stop a running run, retire a halted run's leftover count (freeing the
+     *  disc for a manual spin again), or open the picker. Mirrors the DOM bar's `onAutoplay`. */
     onAutoplay() {
-        if (this.host.state.autoplay.active)
+        const { active, remaining } = this.host.state.autoplay;
+        if (active || remaining > 0)
             this.stopAutoplay();
         else
             this.host.actions.openAutoplayPicker();
@@ -3938,6 +4021,10 @@ class BottomBar extends Container {
     stopAutoplay() {
         this.host.actions.stopAutoplay();
     }
+    /** Halted run, tapped: play out the spins it still owes. */
+    resumeAutoplay() {
+        this.host.actions.startAutoplay(this.host.state.autoplay.remaining);
+    }
     betLocked() {
         return this.host.state.busy || this.host.state.autoplay.active;
     }
@@ -4824,10 +4911,15 @@ function openGameInfo(host) {
 }
 function buildBody(host, width) {
     const col = new FlexBox({ direction: 'column', align: 'stretch', gap: 12 });
-    const rawSections = host.config.gameInfo.sections ?? [];
-    // Auto-inject a hotkeys section unless the game already provides one or features.hotkeys === false.
+    const allSections = host.config.gameInfo.sections ?? [];
+    // Auto-inject a hotkeys section unless the game already provides one. With hotkeys off — a
+    // jurisdiction that forbids them, or a touchscreen that has no keys at all (see core/device.ts) —
+    // there is no keyboard surface to document, and a game-supplied section is dropped along with the
+    // auto-injected one: a keycap chart for keys the player cannot press is a promise the game breaks.
+    const keys = host.config.features.hotkeys !== false;
+    const rawSections = keys ? allSections : allSections.filter((s) => s.type !== 'hotkeys');
     const sectionsWithHotkeys = [...rawSections];
-    if (host.config.features.hotkeys !== false && !rawSections.some((s) => s.type === 'hotkeys')) {
+    if (keys && !rawSections.some((s) => s.type === 'hotkeys')) {
         sectionsWithHotkeys.push({ type: 'hotkeys', order: HOTKEYS_DEFAULT_ORDER });
     }
     const sections = sectionsWithHotkeys;
@@ -5377,6 +5469,34 @@ function imageBox(url, w, h) {
     return c;
 }
 
+/** Collapse buy-bonus options that share a `groupedBy` key into one slot. A slot with more than one
+ *  member is rendered by the pixi shell as a single card with arrows (the DOM shell ignores the key
+ *  and keeps a card per option).
+ *
+ *  A group takes the position of its FIRST member, so the strip order stays predictable however the
+ *  members are scattered through the array. Options with a game-supplied `custom` renderer never
+ *  join a group — the shell has no layout for their interior and could not place arrows over it. */
+function groupBonusSlots(bonuses) {
+    const slots = [];
+    const byKey = new Map();
+    for (const bonus of bonuses) {
+        const key = bonus.groupedBy;
+        if (!key || bonus.custom) {
+            slots.push([bonus]);
+            continue;
+        }
+        const open = byKey.get(key);
+        if (open) {
+            open.push(bonus);
+            continue;
+        }
+        const slot = [bonus];
+        byKey.set(key, slot);
+        slots.push(slot);
+    }
+    return slots;
+}
+
 /** Below this frame height (px), a wide/landscape popout (e.g. Popout S 400×225) stacks its cards
  *  vertically and scrolls — like mobile — so descriptions stay readable instead of shrinking to a
  *  ~4px floor. Wide + taller frames (Popout L and up) keep the centred horizontal row. */
@@ -5410,6 +5530,9 @@ class BuyBonusOverlay extends Container {
     cardEntries = [];
     /** Keyboard focus index into the affordable subset of cardEntries. -1 = none. */
     focusIndex = -1;
+    /** Which member each `groupedBy` slot is showing, kept across rebuilds (bet steps, resizes) so a
+     *  flipped-to variant doesn't snap back to the first one under the player. */
+    groupIndex = new Map();
     /** true when cards are stacked vertically (mobile, or a short landscape popout). */
     stack = false;
     // Drag-scroll state. The drag is handled on the (unmasked) overlay, not the masked strip — a mask
@@ -5528,7 +5651,9 @@ class BuyBonusOverlay extends Container {
         const top = this.headerH + 6;
         const areaH = this.h - top - this.footerH - 6;
         const gap = 14;
-        const n = Math.max(1, this.bonuses.length);
+        // Grouped options share ONE slot (a carousel card), so the width fit counts SLOTS, not options.
+        const slots = groupBonusSlots(this.bonuses);
+        const n = Math.max(1, slots.length);
         // The whole card is laid out in `em`; pick the largest em that fits BOTH dimensions of the
         // available area, so the card is always fully visible (no horizontal clip, CTA never under the
         // footer). emH keeps the card height within the band between header and footer; emW makes the
@@ -5540,16 +5665,44 @@ class BuyBonusOverlay extends Container {
             : (this.w - 48 - (n - 1) * gap) / (18 * n); // row: N cards + gaps fit the frame width
         const em = stack ? Math.min(12, emW) : clamp(4, Math.min(emH, emW), 12);
         const cardW = Math.min(18 * em, this.w - 48);
-        const cards = this.bonuses.map((b) => this.buildCard(b, cardW, em, stack, areaH));
+        const cards = [];
+        this.cardEntries = [];
+        for (const slot of slots) {
+            if (slot.length === 1) {
+                const view = this.buildCard(slot[0], cardW, em, stack, areaH);
+                cards.push(view);
+                this.cardEntries.push({ view, bonus: slot[0], affordable: this.isAffordable(slot[0]) });
+                continue;
+            }
+            // Carousel slot: every member is built (the slot sizes to the tallest and flipping costs
+            // nothing), but only the current one is visible.
+            const key = slot[0].groupedBy;
+            // Flipping the card also moves keyboard focus onto the shown member: one cursor, not two
+            // (otherwise the next rebuild would snap the card back to whatever the focus still pointed at).
+            const group = new GroupCard((i) => {
+                this.groupIndex.set(key, i);
+                this.focusShownMember(group, i);
+            });
+            const members = slot.map((b, i) => this.buildCard(b, cardW, em, stack, areaH, {
+                index: i,
+                count: slot.length,
+                prevLabel: `bb-nav-prev:${key}`,
+                nextLabel: `bb-nav-next:${key}`,
+                onStep: (dir) => {
+                    if (this.dragged)
+                        return; // a scroll gesture, not a tap
+                    group.step(dir);
+                },
+            }));
+            group.setCards(members, this.groupIndex.get(key) ?? 0);
+            cards.push(group);
+            for (let i = 0; i < slot.length; i++) {
+                this.cardEntries.push({ view: members[i], bonus: slot[i], affordable: this.isAffordable(slot[i]), group });
+            }
+        }
         const cardH = Math.max(...cards.map((c) => c.height));
         for (const c of cards)
             c.setHeight(cardH);
-        // Rebuild card entries for keyboard navigation
-        this.cardEntries = this.bonuses.map((b, i) => ({
-            view: cards[i],
-            bonus: b,
-            affordable: this.isAffordable(b),
-        }));
         // Restore or init keyboard focus on the first affordable card
         const affordable = this.cardEntries.filter((e) => e.affordable);
         if (affordable.length > 0) {
@@ -5590,7 +5743,7 @@ class BuyBonusOverlay extends Container {
         }
     }
     // ── one card ──────────────────────────────────────────────────────────────
-    buildCard(bonus, cardW, em, stack, areaH) {
+    buildCard(bonus, cardW, em, stack, areaH, nav) {
         const accent = effectiveAccent(bonus);
         const ink = contrastText(accent);
         const price = bonus.priceMultiplier * this.host.state.bet;
@@ -5626,6 +5779,7 @@ class BuyBonusOverlay extends Container {
             enabled,
             ctaLabel: this.host.t(bonus.type === 'feature' ? 'Activate' : 'Buy'),
             onSelect: select,
+            nav,
         });
         return card;
     }
@@ -5744,7 +5898,7 @@ class BuyBonusOverlay extends Container {
         // the buttons keep the card silhouette without a mask blocking their pointer events.
         const half = cardW / 2;
         const r = 1.3 * em;
-        card.addChild(footerButton(this.host, this.host.t('Cancel'), 'ghost', half, ctaH, 0, y, () => this.removeConfirm(), undefined, r, 0), footerButton(this.host, this.host.t(bonus.type === 'feature' ? 'Activate' : 'Buy'), accent, half, ctaH, half, y, () => {
+        card.addChild(footerButton(this.host, this.host.t('Cancel'), 'ghost', half, ctaH, 0, y, () => this.removeConfirm(), undefined, r, 0), labelled('bb-confirm-ok', footerButton(this.host, this.host.t(bonus.type === 'feature' ? 'Activate' : 'Buy'), accent, half, ctaH, half, y, () => {
             if (!this.isAffordable(bonus))
                 return;
             if (bonus.type === 'feature')
@@ -5752,7 +5906,7 @@ class BuyBonusOverlay extends Container {
             else
                 this.host.actions.selectBuyBonus(bonus.id);
             this.host.closeLayer();
-        }, ink, 0, r));
+        }, ink, 0, r)));
         card.position.set((this.w - cardW) / 2, (this.h - cardH) / 2);
         layer.addChild(card);
         // close X pinned to screen corner
@@ -5778,14 +5932,28 @@ class BuyBonusOverlay extends Container {
         this.buildCards();
         this.buildFooter();
     }
+    /** Move keyboard focus onto the member a carousel slot just flipped to. Skipped when that member
+     *  can't be bought at the current bet — focus only ever sits on affordable cards. */
+    focusShownMember(group, index) {
+        const card = group.cardAt(index);
+        const at = this.cardEntries.filter((ce) => ce.affordable).findIndex((ce) => ce.group === group && ce.view === card);
+        if (at < 0)
+            return;
+        this.focusIndex = at;
+        this.applyFocusRing();
+    }
     /** Apply or clear the focus ring on affordable cards. */
     applyFocusRing() {
         const affordable = this.cardEntries.filter((ce) => ce.affordable);
         for (let i = 0; i < affordable.length; i++) {
-            const view = affordable[i].view;
-            if (view instanceof BonusCard) {
-                view.setFocused(i === this.focusIndex);
-            }
+            const entry = affordable[i];
+            const focused = i === this.focusIndex;
+            // Focusing a member of a carousel slot brings it to the front — the keyboard walks options,
+            // and the card follows.
+            if (focused && entry.group)
+                entry.group.showCard(entry.view);
+            if (entry.view instanceof BonusCard)
+                entry.view.setFocused(focused);
         }
     }
     /** Two-phase keyboard handler.
@@ -5894,6 +6062,55 @@ class CustomCard {
         this.height = total; // the game owns its own layout; we only record the slot height
     }
 }
+/** One slot shared by several options (`groupedBy`) — e.g. four same-priced Ante characters. Every
+ *  member card is built (the slot sizes to the tallest, and flipping is then just a visibility
+ *  swap, so the card never resizes under the player); one is visible at a time. */
+class GroupCard {
+    node = new Container();
+    height = 0;
+    cards = [];
+    index = 0;
+    /** Reports the shown member back to the overlay, which keeps it across rebuilds. */
+    onIndex;
+    constructor(onIndex) {
+        this.onIndex = onIndex;
+    }
+    setCards(cards, index) {
+        this.cards = cards;
+        for (const c of cards)
+            this.node.addChild(c.node);
+        this.height = Math.max(...cards.map((c) => c.height));
+        this.show(index, false); // restoring a remembered position is not a player action
+    }
+    /** Flip to member `i`, wrapping around in both directions. */
+    show(i, notify = true) {
+        const n = this.cards.length;
+        if (n === 0)
+            return;
+        this.index = ((i % n) + n) % n;
+        for (let k = 0; k < n; k++)
+            this.cards[k].node.visible = k === this.index;
+        if (notify)
+            this.onIndex(this.index);
+    }
+    step(dir) {
+        this.show(this.index + dir);
+    }
+    cardAt(index) {
+        return this.cards[index];
+    }
+    /** Bring a specific member's card to the front (keyboard focus landing on that option). */
+    showCard(card) {
+        const i = this.cards.findIndex((c) => c === card);
+        if (i >= 0 && i !== this.index)
+            this.show(i);
+    }
+    setHeight(total) {
+        this.height = total;
+        for (const c of this.cards)
+            c.setHeight(total);
+    }
+}
 class BonusCard {
     node = new Container();
     height = 0;
@@ -5915,9 +6132,22 @@ class BonusCard {
         const volColor = opts.enabled ? accent : 'rgba(255,255,255,.4)';
         const top = new Container();
         let y = 1.25 * em;
-        const title = makeText(bonus.title, { size: 1.3 * em, weight: '800', color: titleColor, letterSpacing: 1.3 * em * 0.04, upper: true, align: 'center', wrapWidth: innerW });
+        // With arrows the title has to clear them on both sides, or a long name wraps under the glyphs.
+        const arrowSz = 1.5 * em;
+        const arrowPad = 0.45 * em;
+        const titleW = opts.nav ? innerW - 2 * (arrowSz + 2 * arrowPad) : innerW;
+        const title = makeText(bonus.title, { size: 1.3 * em, weight: '800', color: titleColor, letterSpacing: 1.3 * em * 0.04, upper: true, align: 'center', wrapWidth: titleW });
         title.position.set((cardW - title.width) / 2, y);
         top.addChild(title);
+        if (opts.nav) {
+            const boxSz = arrowSz + 2 * arrowPad;
+            const rowY = y + (title.height - boxSz) / 2;
+            const prev = arrowButton(opts.nav.prevLabel, -1, arrowSz, arrowPad, accent, opts.nav.onStep);
+            const next = arrowButton(opts.nav.nextLabel, 1, arrowSz, arrowPad, accent, opts.nav.onStep);
+            prev.position.set(0.6 * em, rowY);
+            next.position.set(cardW - 0.6 * em - boxSz, rowY);
+            top.addChild(prev, next);
+        }
         y += title.height + 0.75 * em;
         const thumb = thumbNode(host, bonus, accent, 6.2 * em);
         thumb.position.set((cardW - 6.2 * em) / 2, y);
@@ -5927,6 +6157,13 @@ class BonusCard {
         desc.position.set((cardW - desc.width) / 2, y);
         top.addChild(desc);
         y += desc.height;
+        if (opts.nav) {
+            y += 0.7 * em;
+            const dots = dotRow(opts.nav.count, opts.nav.index, accent, 0.24 * em, 0.5 * em);
+            dots.position.set((cardW - dots.width) / 2, y);
+            top.addChild(dots);
+            y += 0.48 * em;
+        }
         this.topH = y;
         // bottom block: volatility + price
         let by = 0;
@@ -5941,7 +6178,8 @@ class BonusCard {
         this.bottomBlock.addChild(priceText);
         by += priceText.height;
         this.bottomH = by;
-        this.cta = ctaButton(host, opts.ctaLabel, accent, opts.ink, cardW, this.ctaH, opts.enabled, opts.onSelect, 1.4 * em);
+        this.cta = labelled(`bb-cta:${bonus.id}`, ctaButton(host, opts.ctaLabel, accent, opts.ink, cardW, this.ctaH, opts.enabled, opts.onSelect, 1.4 * em));
+        this.node.label = `bb-card:${bonus.id}`;
         this.node.addChild(this.bg, top, this.bottomBlock, this.cta);
         if (opts.enabled) {
             this.node.eventMode = 'static';
@@ -5992,6 +6230,43 @@ class BonusCard {
     }
 }
 // ── shared card bits ─────────────────────────────────────────────────────────
+/** Tag a node so the shell (and its tests) can find it in the display tree. */
+function labelled(label, node) {
+    node.label = label;
+    return node;
+}
+/** One carousel arrow. `stopPropagation` keeps the tap off the card underneath, which would
+ *  otherwise open the confirm dialog for the member being flipped away from. */
+function arrowButton(label, dir, size, pad, accent, onStep) {
+    const b = new Container();
+    b.label = label;
+    const glyph = makeIcon('chevronRight', size, '#ffffff');
+    if (dir === -1)
+        glyph.spin = Math.PI; // no chevronLeft in the set — the glyph spins about its centre
+    glyph.position.set(pad, pad);
+    b.addChild(rectHit(size + pad * 2, size + pad * 2), glyph);
+    b.eventMode = 'static';
+    b.cursor = 'pointer';
+    b.on('pointerover', () => glyph.setColor(accent));
+    b.on('pointerout', () => glyph.setColor('#ffffff'));
+    b.on('pointertap', (e) => {
+        e.stopPropagation();
+        onStep(dir);
+    });
+    return b;
+}
+/** Position indicator for a carousel slot: one dot per member, the current one in the accent. */
+function dotRow(count, index, accent, r, gap) {
+    const c = new Container();
+    for (let i = 0; i < count; i++) {
+        const dot = new Graphics();
+        const on = i === index;
+        dot.circle(r, r, r).fill(on ? accent : 'rgba(255,255,255,.28)');
+        dot.position.set(i * (2 * r + gap), 0);
+        c.addChild(dot);
+    }
+    return c;
+}
 function thumbNode(host, bonus, accent, h) {
     const c = new Container();
     c.addChild(rectHit(h, h, 0)); // size anchor (transparent)