@energy8platform/shell 0.7.1 → 0.8.0

package/dist/html.cjs.js

@@ -1693,7 +1693,7 @@ class KeyboardController {
 
 // 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.1';
+const PACKAGE_VERSION = '0.8.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {

package/dist/html.d.ts

@@ -160,6 +160,11 @@ interface BonusOption {
     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,
@@ -631,7 +636,7 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.7.1";
+    readonly engineVersion = "0.8.0";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
@@ -776,7 +781,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.1";
+declare const PACKAGE_VERSION = "0.8.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/html.esm.js

@@ -1691,7 +1691,7 @@ class KeyboardController {
 
 // 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.1';
+const PACKAGE_VERSION = '0.8.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {

package/dist/index.cjs.js

@@ -1667,7 +1667,7 @@ class KeyboardController {
 
 // 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.1';
+const PACKAGE_VERSION = '0.8.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {

package/dist/index.d.ts

@@ -160,6 +160,11 @@ interface BonusOption {
     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,
@@ -631,7 +636,7 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.7.1";
+    readonly engineVersion = "0.8.0";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
@@ -776,7 +781,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.1";
+declare const PACKAGE_VERSION = "0.8.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/index.esm.js

@@ -1665,7 +1665,7 @@ class KeyboardController {
 
 // 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.1';
+const PACKAGE_VERSION = '0.8.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {

package/dist/pixi.cjs.js

@@ -1694,7 +1694,7 @@ class KeyboardController {
 
 // 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.1';
+const PACKAGE_VERSION = '0.8.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {
@@ -2326,7 +2326,22 @@ function prefersReducedMotion() {
 }
 const easeOutCubic = (p) => 1 - Math.pow(1 - p, 3);
 
-/** Tween 0→1 on the Pixi ticker. Returns a canceler. Skips to the end when motion is reduced. */
+/**
+ * Tween 0→1 on the Pixi ticker. Returns a canceler. Skips to the end when motion is reduced.
+ *
+ * CONTRACT — when motion is reduced (or `duration <= 0`) this tween does NOT animate: it applies
+ * the final value and calls `onComplete` SYNCHRONOUSLY, before returning. Callers depend on that
+ * (`PixiRenderer.destroy` resolves its teardown promise from `onComplete`, and must not wait on a
+ * ticker that may already be stopped), so it must stay synchronous.
+ *
+ * The consequence for callers: `onComplete` is NOT an async boundary. An `onComplete` that starts
+ * another tween is then direct recursion with no unwind — tween → onComplete → tween → … until
+ * `RangeError: Maximum call stack size exceeded`. That shipped once: the CTA pulse loop
+ * (`widgets.ts` startPulse) restarted itself from `onComplete`, so every player running the OS
+ * "reduce motion" setting crashed the instant the buy-bonus panel painted its hovered CTA. Any
+ * looping animation must therefore check `prefersReducedMotion()` and not loop — which is also
+ * what reduced motion is asking for.
+ */
 function tween(ticker, opts) {
     const ease = opts.ease ?? easeOutCubic;
     if (prefersReducedMotion() || opts.duration <= 0) {
@@ -3298,6 +3313,15 @@ class BuyBonusBadge extends pixi_js.Container {
     startPulse() {
         if (this.pulseCancel)
             return;
+        // A pulse is exactly the kind of looping decoration "reduce motion" asks us to drop — and
+        // under it `tween` has nothing to animate anyway: it snaps to the end and calls `onComplete`
+        // SYNCHRONOUSLY (see its contract), which this loop would answer by starting another one, and
+        // another, with no unwind — `RangeError: Maximum call stack size exceeded`. That was a live
+        // Stake crash: with the OS "reduce motion" setting on, opening the buy-bonus panel painted its
+        // hovered CTA and killed the game, so the player could never buy. Now the button simply sits
+        // still at scale 1.
+        if (prefersReducedMotion())
+            return;
         // both the label (anchor 0.5) and the icon (pivot centred) scale around their centre
         const loop = () => {
             this.pulseCancel = tween(this.ticker, {
@@ -5355,6 +5379,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. */
@@ -5388,6 +5440,9 @@ class BuyBonusOverlay extends pixi_js.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
@@ -5506,7 +5561,9 @@ class BuyBonusOverlay extends pixi_js.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
@@ -5518,16 +5575,44 @@ class BuyBonusOverlay extends pixi_js.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) {
@@ -5568,7 +5653,7 @@ class BuyBonusOverlay extends pixi_js.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;
@@ -5604,6 +5689,7 @@ class BuyBonusOverlay extends pixi_js.Container {
             enabled,
             ctaLabel: this.host.t(bonus.type === 'feature' ? 'Activate' : 'Buy'),
             onSelect: select,
+            nav,
         });
         return card;
     }
@@ -5722,7 +5808,7 @@ class BuyBonusOverlay extends pixi_js.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')
@@ -5730,7 +5816,7 @@ class BuyBonusOverlay extends pixi_js.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
@@ -5756,14 +5842,28 @@ class BuyBonusOverlay extends pixi_js.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.
@@ -5872,6 +5972,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 pixi_js.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 pixi_js.Container();
     height = 0;
@@ -5893,9 +6042,22 @@ class BonusCard {
         const volColor = opts.enabled ? accent : 'rgba(255,255,255,.4)';
         const top = new pixi_js.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);
@@ -5905,6 +6067,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;
@@ -5919,7 +6088,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';
@@ -5970,6 +6140,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 pixi_js.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 pixi_js.Container();
+    for (let i = 0; i < count; i++) {
+        const dot = new pixi_js.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 pixi_js.Container();
     c.addChild(rectHit(h, h, 0)); // size anchor (transparent)