@energy8platform/shell 0.7.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/shell",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Energy8 branded game shell — one logic core, pluggable html/pixi renderers behind a stable contract.",
   "type": "module",
   "main": "./dist/index.cjs.js",

package/src/core/ShellController.ts

@@ -5,6 +5,7 @@ import { formatCurrency } from './format';
 import { createI18n, type I18n } from './i18n';
 import { KeyboardController, type KeyboardHost } from './keyboard';
 import { DEFAULT_MENU, rangeBounds, seedMenuValues, type MenuItem, type MenuRangeItem } from './menu';
+import { keyboardCapable } from './device';
 import { PACKAGE_VERSION } from './version';
 import type {
   ShellConfig,
@@ -46,7 +47,10 @@ export function resolveConfig(config: ShellConfig): ResolvedShellConfig {
     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,
@@ -145,7 +149,11 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
         this.renderer.renderBar();
       },
       toggleAutoplay: () => {
-        if (this.state.autoplay.active) a.stopAutoplay();
+        // 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();
       },
       startAutoplay: (remaining) => {

package/src/core/bonusGroups.ts

@@ -0,0 +1,29 @@
+import type { BonusOption } from './types';
+
+/** 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. */
+export function groupBonusSlots(bonuses: readonly BonusOption[]): BonusOption[][] {
+  const slots: BonusOption[][] = [];
+  const byKey = new Map<string, BonusOption[]>();
+  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;
+}

package/src/core/device.ts

@@ -0,0 +1,37 @@
+/**
+ * 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).
+ */
+
+interface MediaQueryHost {
+  matchMedia?(query: string): { matches: boolean };
+}
+
+/** A touchscreen: the primary pointer is a finger, and nothing can hover. */
+const TOUCH_ONLY = '(pointer: coarse) and (hover: none)';
+
+export function keyboardCapable(
+  win: MediaQueryHost | undefined = typeof window === 'undefined' ? undefined : window,
+): boolean {
+  // 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;
+  }
+}

package/src/core/types.ts

@@ -40,6 +40,11 @@ export 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,
@@ -151,8 +156,13 @@ export interface AutoplayConfig {
 
 export 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). */

package/src/core/version.ts

@@ -1,3 +1,3 @@
 // 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. */
-export const PACKAGE_VERSION = '0.7.2';
+export const PACKAGE_VERSION = '0.9.0';

package/src/ui/html/components/BottomBar.ts

@@ -225,20 +225,32 @@ function betLocked(host: ShellHost): boolean {
   return host.state.busy || host.state.autoplay.active;
 }
 
-/** SPIN disc — rotates while busy; becomes a STOP + countdown while autoplay runs. */
+/**
+ * SPIN disc — rotates while busy; becomes a STOP + countdown while autoplay runs; becomes an
+ * autoplay glyph + the SAME countdown when a run was halted with spins still owed (a lost
+ * connection), where a tap resumes it. That third state is what a certification lab means by "after
+ * reconnection the counter is displayed correctly": the run stopped, but the spins the player asked
+ * for are still on screen and one tap away, instead of silently reset to zero.
+ */
 function spinButton(host: ShellHost): HTMLButtonElement {
   const { state } = host;
   const sp = document.createElement('button');
   sp.className = 'ge-shell-spin';
   sp.dataset.ge = 'spin';
+  const rem = state.autoplay.remaining;
+  const count = Number.isFinite(rem) ? String(rem) : '∞';
   if (state.autoplay.active) {
     sp.classList.add('ge-stop');
-    const rem = state.autoplay.remaining;
-    const label = Number.isFinite(rem) ? String(rem) : '∞';
-    sp.innerHTML = `<span class="ge-spin-stop">${icon('stop')}</span><span class="ge-spin-count">${label}</span>`;
+    sp.innerHTML = `<span class="ge-spin-stop">${icon('stop')}</span><span class="ge-spin-count">${count}</span>`;
     sp.addEventListener('click', () => {
       if (!sp.disabled) host.actions.stopAutoplay();
     });
+  } else if (rem > 0) {
+    sp.classList.add('ge-auto-paused');
+    sp.innerHTML = `<span class="ge-spin-auto">${icon('autoplay')}</span><span class="ge-spin-count">${count}</span>`;
+    sp.addEventListener('click', () => {
+      if (!sp.disabled) host.actions.startAutoplay(rem);
+    });
   } else {
     sp.innerHTML = icon('spin');
     if (state.busy) sp.classList.add('ge-spinning');
@@ -257,8 +269,11 @@ function autoButton(host: ShellHost): HTMLButtonElement {
   return b;
 }
 
+/** Same button, three jobs: stop a running run, retire a halted run's leftover count (which frees
+ *  the disc for a manual spin again), or open the picker. */
 function onAutoplay(host: ShellHost): void {
-  if (host.state.autoplay.active) host.actions.stopAutoplay();
+  const { active, remaining } = host.state.autoplay;
+  if (active || remaining > 0) host.actions.stopAutoplay();
   else host.actions.openAutoplayPicker();
 }
 

package/src/ui/html/components/GameInfo.ts

@@ -24,10 +24,15 @@ export function openGameInfoModal(host: ShellHost): GameInfoModal {
   });
   root.dataset.ge = 'info-modal';
 
-  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: GameInfoSection[] = [...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;

package/src/ui/html/shell.css.ts

@@ -57,6 +57,11 @@ export const SHELL_CSS = SHELL_FONT_CSS + SHELL_DIGIT_FONT_CSS + `
 /* the STOP glyph is a solid dark square, so the autoplay count is always pure white to read on it. */
 #${SHELL_ROOT_ID} .ge-spin-count { position:absolute; inset:0; display:flex; align-items:center; justify-content:center;
   font-size:22px; font-weight:800; line-height:1; font-variant-numeric:tabular-nums; color:#fff; }
+/* autoplay halted with spins still owed (a lost connection): the run is stopped, so no STOP square —
+   the auto glyph sits above the leftover count, both in the disc's own ink, and a tap resumes. */
+#${SHELL_ROOT_ID} .ge-shell-spin.ge-auto-paused { flex-direction:column; gap:1px; position:relative; }
+#${SHELL_ROOT_ID} .ge-auto-paused .ge-spin-auto { display:flex; font-size:.46em; line-height:0; }
+#${SHELL_ROOT_ID} .ge-auto-paused .ge-spin-count { position:static; inset:auto; color:inherit; font-size:20px; }
 
 /* BUY BONUS — round accent badge, 2-line label, text pulses + accent glow on hover */
 #${SHELL_ROOT_ID} .ge-shell-buybonus { pointer-events:auto; cursor:pointer; box-sizing:border-box;

package/src/ui/pixi/components/BottomBar.ts

@@ -13,9 +13,19 @@ import {
   FsHero,
   divider,
 } from '../primitives/widgets';
+import type { SpinAutoplayMode } from '../primitives/widgets';
 import type { IconName } from '../icons';
 
 // ── 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: {
+  autoplay: { active: boolean; remaining: number };
+}): SpinAutoplayMode {
+  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
@@ -296,8 +306,9 @@ export 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);
     } else if (showFsBlocks) {
@@ -373,8 +384,9 @@ export 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;
     } else if (showFsBlocks) {
@@ -569,13 +581,20 @@ export class BottomBar extends Container {
   private onTurbo(): void {
     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`. */
   private onAutoplay(): void {
-    if (this.host.state.autoplay.active) this.stopAutoplay();
+    const { active, remaining } = this.host.state.autoplay;
+    if (active || remaining > 0) this.stopAutoplay();
     else this.host.actions.openAutoplayPicker();
   }
   private stopAutoplay(): void {
     this.host.actions.stopAutoplay();
   }
+  /** Halted run, tapped: play out the spins it still owes. */
+  private resumeAutoplay(): void {
+    this.host.actions.startAutoplay(this.host.state.autoplay.remaining);
+  }
   private betLocked(): boolean {
     return this.host.state.busy || this.host.state.autoplay.active;
   }

package/src/ui/pixi/components/BuyBonus.ts

@@ -1,6 +1,7 @@
 import { Assets, Container, Graphics, Rectangle, Sprite, Text, Texture, type FederatedPointerEvent } from 'pixi.js';
 import type { PixiComponentContext, ShellLayer } from '../context';
 import type { BonusOption } from '@/core/types';
+import { groupBonusSlots } from '@/core/bonusGroups';
 import { betDir } from '@/core/keyboard';
 import { effectiveAccent, contrastText } from '@/core/colors';
 import { makeText } from '../text';
@@ -23,11 +24,15 @@ export function openBuyBonus(host: PixiComponentContext): ShellLayer | null {
   return new BuyBonusOverlay(host, bonuses);
 }
 
-/** Pairing of a rendered CardView with its bonus data (affordability included). */
+/** Pairing of a rendered CardView with its bonus data (affordability included). One entry per
+ *  OPTION — the members of a `groupedBy` slot each get an entry pointing at the shared group card,
+ *  so keyboard navigation walks every option even though they occupy one slot. */
 interface CardEntry {
   view: CardView;
   bonus: BonusOption;
   affordable: boolean;
+  /** Set on members of a grouped slot; flipping it brings this member's card to the front. */
+  group?: GroupCard;
 }
 
 class BuyBonusOverlay extends Container implements ShellLayer {
@@ -51,6 +56,9 @@ class BuyBonusOverlay extends Container implements ShellLayer {
   private cardEntries: CardEntry[] = [];
   /** Keyboard focus index into the affordable subset of cardEntries. -1 = none. */
   private 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. */
+  private groupIndex = new Map<string, number>();
   /** true when cards are stacked vertically (mobile, or a short landscape popout). */
   private stack = false;
   // Drag-scroll state. The drag is handled on the (unmasked) overlay, not the masked strip — a mask
@@ -169,7 +177,9 @@ class BuyBonusOverlay extends Container implements ShellLayer {
     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
@@ -182,16 +192,45 @@ class BuyBonusOverlay extends Container implements ShellLayer {
     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: CardView[] = [];
+    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 as string;
+      // 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: GroupCard = 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);
+            },
+          }) as BonusCard,
+      );
+      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) {
@@ -230,7 +269,7 @@ class BuyBonusOverlay extends Container implements ShellLayer {
   }
 
   // ── one card ──────────────────────────────────────────────────────────────
-  private buildCard(bonus: BonusOption, cardW: number, em: number, stack: boolean, areaH: number): CardView {
+  private buildCard(bonus: BonusOption, cardW: number, em: number, stack: boolean, areaH: number, nav?: CardNav): CardView {
     const accent = effectiveAccent(bonus);
     const ink = contrastText(accent);
     const price = bonus.priceMultiplier * this.host.state.bet;
@@ -264,6 +303,7 @@ class BuyBonusOverlay extends Container implements ShellLayer {
       enabled,
       ctaLabel: this.host.t(bonus.type === 'feature' ? 'Activate' : 'Buy'),
       onSelect: select,
+      nav,
     });
     void stack;
     void areaH;
@@ -392,12 +432,12 @@ class BuyBonusOverlay extends Container implements ShellLayer {
     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, () => {
+      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') this.host.actions.activateFeature(bonus);
         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);
@@ -430,14 +470,26 @@ class BuyBonusOverlay extends Container implements ShellLayer {
     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. */
+  private focusShownMember(group: GroupCard, index: number): void {
+    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. */
   private applyFocusRing(): void {
     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);
     }
   }
 
@@ -550,6 +602,68 @@ class CustomCard implements CardView {
   }
 }
 
+/** 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 implements CardView {
+  readonly node = new Container();
+  height = 0;
+  private cards: BonusCard[] = [];
+  private index = 0;
+  /** Reports the shown member back to the overlay, which keeps it across rebuilds. */
+  private onIndex: (index: number) => void;
+
+  constructor(onIndex: (index: number) => void) {
+    this.onIndex = onIndex;
+  }
+
+  setCards(cards: BonusCard[], index: number): void {
+    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: number, notify = true): void {
+    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: 1 | -1): void {
+    this.show(this.index + dir);
+  }
+
+  cardAt(index: number): CardView | undefined {
+    return this.cards[index];
+  }
+
+  /** Bring a specific member's card to the front (keyboard focus landing on that option). */
+  showCard(card: CardView): void {
+    const i = this.cards.findIndex((c) => c === card);
+    if (i >= 0 && i !== this.index) this.show(i);
+  }
+
+  setHeight(total: number): void {
+    this.height = total;
+    for (const c of this.cards) c.setHeight(total);
+  }
+}
+
+/** Carousel chrome for a card that shares its slot with other options (`groupedBy`): arrows either
+ *  side of the title and a dot per member under the description. */
+interface CardNav {
+  /** This member's position in the slot (drives which dot is lit). */
+  index: number;
+  count: number;
+  prevLabel: string;
+  nextLabel: string;
+  onStep: (dir: 1 | -1) => void;
+}
+
 interface BonusCardOpts {
   host: PixiComponentContext;
   bonus: BonusOption;
@@ -561,6 +675,7 @@ interface BonusCardOpts {
   enabled: boolean;
   ctaLabel: string;
   onSelect: () => void;
+  nav?: CardNav;
 }
 
 class BonusCard implements CardView {
@@ -587,9 +702,22 @@ class BonusCard implements CardView {
 
     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);
@@ -599,6 +727,13 @@ class BonusCard implements CardView {
     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
@@ -615,8 +750,9 @@ class BonusCard implements CardView {
     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';
@@ -672,6 +808,46 @@ class BonusCard implements CardView {
 }
 
 // ── shared card bits ─────────────────────────────────────────────────────────
+
+/** Tag a node so the shell (and its tests) can find it in the display tree. */
+function labelled<T extends Container>(label: string, node: T): T {
+  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: string, dir: 1 | -1, size: number, pad: number, accent: string, onStep: (dir: 1 | -1) => void): Container {
+  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: FederatedPointerEvent) => {
+    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: number, index: number, accent: string, r: number, gap: number): Container {
+  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: PixiComponentContext, bonus: BonusOption, accent: string, h: number): Container {
   const c = new Container();
   c.addChild(rectHit(h, h, 0)); // size anchor (transparent)

package/src/ui/pixi/components/GameInfo.ts

@@ -37,10 +37,15 @@ export function openGameInfo(host: PixiComponentContext): ShellLayer {
 
 function buildBody(host: PixiComponentContext, width: number): Container {
   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: GameInfoSection[] = [...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;