@energy8platform/shell 0.10.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/shell",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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/index.ts

@@ -38,3 +38,6 @@ export { createI18n, socialize, normalizeLang } from './i18n';
 export { DISCLAIMER_LINES } from './locales';
 export type { Lang, I18n, I18nOptions } from './i18n';
 export { PACKAGE_VERSION } from './version';
+
+export { scrollHint, scrollEdge, SCROLL_THUMB_MIN } from './scrollHint';
+export type { ScrollHint, ScrollMetrics, ScrollEdge } from './scrollHint';

package/src/core/keyboard.ts

@@ -1,4 +1,5 @@
 import type { ShellState } from './types';
+import { bonusBuyLocked } from './state';
 
 export interface KeyboardHost {
   readonly state: ShellState;
@@ -153,7 +154,12 @@ export class KeyboardController {
           if (h.turboLevels > 0 && !s.replay) { h.cycleTurbo(); return; }
           break;
         case 'KeyB':
-          if (h.buyBonusEnabled && s.mode === 'base' && !s.replay) { h.openBuyBonus(); return; }
+          // `bonusBuyLocked` is the same predicate the bar's coin uses. Without it this hotkey
+          // reached past a disabled coin and opened the overlay mid-round.
+          if (h.buyBonusEnabled && s.mode === 'base' && !s.replay && !bonusBuyLocked(s)) {
+            h.openBuyBonus();
+            return;
+          }
           break;
         case 'KeyI':
           h.openInfo(); return;

package/src/core/scrollHint.ts

@@ -0,0 +1,91 @@
+/**
+ * What a scrollable region should ADVERTISE about itself.
+ *
+ * A slot in a Stake popout is 400×225. At that size the game-info overlay holds twelve screens of
+ * content, the buy-bonus switches to a vertical card stack, and the menu popover hides its last
+ * row — all of them scroll, and (before this module) none of them said so. macOS makes it worse:
+ * overlay scrollbars stay invisible until something is already scrolling, so the very affordance a
+ * player needs BEFORE they touch anything is the one the OS withholds. A certification reviewer
+ * reads that as content the player can't reach.
+ *
+ * The maths lives here, apart from both renderers, for one reason: the DOM shell reads
+ * `scrollTop`/`scrollHeight` while the Pixi shell tracks its own offset against a mask, and those
+ * two must never disagree about whether a fade belongs at the bottom edge. Renderers decide how a
+ * thumb LOOKS; this decides when there is one and where it sits.
+ */
+
+/** Fractions of a pixel are layout rounding, not reachable content. */
+const EPSILON = 1;
+
+/** Landing within half a pixel of an edge counts as arriving: a browser settles a flung scroll on
+ *  199.5 of 200, and a fade left glowing over content the player has already reached reads as a
+ *  bug. */
+const EDGE_EPSILON = 0.5;
+
+/**
+ * Shortest thumb we will draw, as a fraction of its track.
+ *
+ * The honest ratio for game info at Popout S is 8% — an 18px speck on a 226px track, which reads
+ * as a rendering artifact rather than a scrollbar. Floored at 18% it stays recognisably a thumb,
+ * and it still travels the whole track, so the position it reports remains truthful even though
+ * its length no longer is. That is the right trade: length is decoration, position is information.
+ */
+export const SCROLL_THUMB_MIN = 0.18;
+
+/** One axis of a scroll region. Named for the Y axis because that is the common case; the
+ *  buy-bonus strip passes its width metrics through the same fields. */
+export interface ScrollMetrics {
+  scrollTop: number;
+  scrollHeight: number;
+  clientHeight: number;
+}
+
+export interface ScrollHint {
+  /** There is content past an edge — draw the affordance at all. */
+  overflowing: boolean;
+  /** Nothing above/left of the viewport: suppress the leading fade. */
+  atStart: boolean;
+  /** Nothing below/right of the viewport: suppress the trailing fade and the chevron. */
+  atEnd: boolean;
+  /** Thumb length as a fraction of the track, in `[SCROLL_THUMB_MIN, 1]`. */
+  thumbSize: number;
+  /** Thumb's leading edge as a fraction of the track, in `[0, 1 - thumbSize]`. */
+  thumbOffset: number;
+  /** Scrollable distance in pixels — 0 when the content fits. */
+  maxScroll: number;
+}
+
+/** Resolve one axis of a scroll region into everything a renderer needs to draw its affordance. */
+export function scrollHint(m: ScrollMetrics): ScrollHint {
+  const view = Math.max(0, m.clientHeight);
+  const content = Math.max(0, m.scrollHeight);
+  const maxScroll = Math.max(0, content - view);
+
+  if (maxScroll <= EPSILON || view <= 0) {
+    // Both edges are "the edge" when there is nowhere to go — callers gate every fade on the
+    // matching flag, so a region that fits draws nothing without needing to check `overflowing`.
+    return { overflowing: false, atStart: true, atEnd: true, thumbSize: 1, thumbOffset: 0, maxScroll: 0 };
+  }
+
+  const at = Math.max(0, Math.min(maxScroll, m.scrollTop));
+  const thumbSize = Math.min(1, Math.max(SCROLL_THUMB_MIN, view / content));
+  const progress = at / maxScroll;
+  return {
+    overflowing: true,
+    atStart: at <= EDGE_EPSILON,
+    atEnd: maxScroll - at <= EDGE_EPSILON,
+    thumbSize,
+    thumbOffset: progress * (1 - thumbSize),
+    maxScroll,
+  };
+}
+
+/** The three-state tag both renderers put on a scroll region, so CSS and tests can name it.
+ *  `none` when the content fits — the attribute is removed rather than set to it. */
+export type ScrollEdge = 'none' | 'start' | 'mid' | 'end';
+
+export function scrollEdge(h: ScrollHint): ScrollEdge {
+  if (!h.overflowing) return 'none';
+  if (h.atStart) return 'start';
+  return h.atEnd ? 'end' : 'mid';
+}

package/src/core/state.ts

@@ -41,3 +41,18 @@ export function nextTurbo(current: number, maxLevels: number): number {
   if (maxLevels <= 0) return 0;
   return current >= maxLevels ? 0 : current + 1;
 }
+
+/**
+ * Is a bonus buy unavailable right now?
+ *
+ * The three RUNTIME locks, in one place because they used to be in three: both bottom bars spelled
+ * them out for the coin, and the Shift+B hotkey spelled out a different, shorter set — so the
+ * keyboard opened the buy-bonus overlay mid-round and let a player stake a second bet on top of a
+ * round already in flight. A predicate the bars and the hotkey share cannot drift apart again.
+ *
+ * Runtime only. Whether the feature EXISTS at all is a config question (`features.buyBonus`), and
+ * whether this particular surface should offer it (mode, replay) belongs to the caller.
+ */
+export function bonusBuyLocked(s: ShellState): boolean {
+  return s.busy || s.autoplay.active || !s.buyBonusEnabled;
+}

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.10.0';
+export const PACKAGE_VERSION = '0.11.1';

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

@@ -2,6 +2,7 @@ import type { ShellHost } from '@/core/renderer';
 import { effectiveAccent } from '@/core/colors';
 import { icon, type IconName } from '../icons';
 import { BUY_BONUS_ART, BUY_BONUS_SOCIAL_ART, BUY_BONUS_DISABLED_ART } from '../../buy-bonus-art';
+import { bonusBuyLocked } from '@/core/state';
 
 /** A floating labelled money readout (balance/win/bet). */
 function readout(ge: string, label: string, value: string): HTMLElement {
@@ -295,5 +296,5 @@ function applyBusy(host: ShellHost, bar: HTMLElement): void {
   if (betVal) betVal.classList.toggle('ge-disabled', lockBet);
   const buy = bar.querySelector('[data-ge="buybonus"]') as HTMLButtonElement | null;
   // disabled for the whole autoplay run (not just per-spin busy) so it doesn't flicker/pulse
-  if (buy) buy.disabled = busy || auto || !host.state.buyBonusEnabled;
+  if (buy) buy.disabled = bonusBuyLocked(host.state);
 }

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

@@ -3,6 +3,7 @@ import type { BonusOption } from '@/core/types';
 import { betDir } from '@/core/keyboard';
 import { effectiveAccent, contrastText } from '@/core/colors';
 import { createOverlay, createCardModal } from '../primitives';
+import { attachScrollAffordance, type ScrollAffordance } from '../scroll-affordance';
 import { icon, type IconName } from '../icons';
 
 /** Mutable state shared between the overlay DOM and the onKey handler. */
@@ -21,11 +22,15 @@ export function openBuyBonusOverlay(host: ShellHost): { root: HTMLElement; onKey
 
   const st: OverlayState = { focusIndex: -1, confirmBonus: undefined };
 
-  const { root, body } = createOverlay({ title: host.t('Buy bonus'), onClose: () => host.actions.closeOverlay() });
+  const { root, body, affordance } = createOverlay({ title: host.t('Buy bonus'), onClose: () => host.actions.closeOverlay() });
   root.dataset.ge = 'buybonus-overlay';
 
+  // The strip's own X-scroll affordance, rebuilt with the grid it describes.
+  let gridAffordance: ScrollAffordance | null = null;
+
   // Re-render the grid whenever the bet changes so every card's price stays live.
   const renderGrid = (): void => {
+    gridAffordance?.destroy();
     body.innerHTML = '';
     const grid = document.createElement('div'); grid.className = 'ge-bb-grid';
     // Card count drives the width-fit clamp in CSS (each card is 18em; N cards must fit the frame
@@ -46,6 +51,11 @@ export function openBuyBonusOverlay(host: ShellHost): { root: HTMLElement; onKey
     } else {
       st.focusIndex = -1;
     }
+    // Two axes, two affordances. Below a ~340px frame the CSS stacks the cards and the OVERLAY
+    // scrolls vertically (see the ge-bb-frame container query); above it the STRIP scrolls
+    // horizontally. Each is attached unconditionally and stays silent on the axis that fits.
+    gridAffordance = attachScrollAffordance(grid, { axis: 'x', cue: false });
+    affordance.sync();
   };
 
   renderGrid();

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

@@ -17,7 +17,7 @@ export interface GameInfoModal {
 }
 
 export function openGameInfoModal(host: ShellHost): GameInfoModal {
-  const { root, body, scroll } = createOverlay({
+  const { root, body, scroll, affordance } = createOverlay({
     title: host.t('Game info'),
     onClose: () => host.actions.closeOverlay(),
     onBack: () => { root.remove(); host.actions.openMenu(); },
@@ -46,6 +46,8 @@ export function openGameInfoModal(host: ShellHost): GameInfoModal {
     .forEach(({ s }) => body.appendChild(renderSection(host, s)));
 
   body.appendChild(versionFooter(host));
+  // The body is filled after createOverlay returned, so its first honest measurement is here.
+  affordance.sync();
 
   const LINE = 60;
   const PAGE = (): number => Math.floor(scroll.clientHeight * 0.9) || Math.floor(540 * 0.9);

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

@@ -1,5 +1,6 @@
 import type { ShellHost } from '@/core/renderer';
 import { createCardModal } from '../primitives';
+import { attachScrollAffordance } from '../scroll-affordance';
 
 interface Choice { id: string; label: string }
 
@@ -71,6 +72,9 @@ function buildSheet(opts: SheetOpts): Sheet {
     chips.push(chip); grid.appendChild(chip);
   }
   ui.body.appendChild(grid);
+  // A long bet ladder is capped at 50vh and scrolls; in a 225px popout that cap bites after two
+  // rows. The cue hangs off the card, which holds still while the grid moves.
+  attachScrollAffordance(grid, { cueHost: ui.card });
 
   function doConfirm(): void {
     opts.onConfirm(selected);

package/src/ui/html/primitives.ts

@@ -1,5 +1,6 @@
 import { icon } from './icons';
 import { placePopover, popoverWidth, POPOVER, type Rect } from '@/core/popover';
+import { attachScrollAffordance, type ScrollAffordance } from './scroll-affordance';
 
 /** Render a (possibly socialised) two-word label across two lines — the BUY BONUS badge.
  *  Shared so the bottom-bar button and the Game-info control legend break identically. */
@@ -53,9 +54,12 @@ export interface OverlayOpts {
   onBack?: () => void;
 }
 
-/** Full-screen overlay. Returns { root, body, scroll }; append content to body.
- *  The `scroll` element is the scrollable container (overflow-y: auto). */
-export function createOverlay(opts: OverlayOpts): { root: HTMLDivElement; body: HTMLDivElement; scroll: HTMLDivElement } {
+/** Full-screen overlay. Returns { root, body, scroll, affordance }; append content to body.
+ *  The `scroll` element is the scrollable container (overflow-y: auto); `affordance` marks it as
+ *  scrollable once it overflows — call `affordance.sync()` after filling or resizing the body. */
+export function createOverlay(opts: OverlayOpts): {
+  root: HTMLDivElement; body: HTMLDivElement; scroll: HTMLDivElement; affordance: ScrollAffordance;
+} {
   const root = document.createElement('div');
   root.className = 'ge-shell-overlay';
   const head = document.createElement('div');
@@ -82,7 +86,9 @@ export function createOverlay(opts: OverlayOpts): { root: HTMLDivElement; body:
   const body = document.createElement('div'); body.className = 'ge-ov-body';
   scroll.appendChild(body);
   root.append(head, scroll);
-  return { root, body, scroll };
+  // The cue is hosted on `root`, not on `scroll`: `scroll` is the element that moves.
+  const affordance = attachScrollAffordance(scroll, { cueHost: root });
+  return { root, body, scroll, affordance };
 }
 
 export interface PopoverOpts {
@@ -126,6 +132,7 @@ export function createPopover(opts: PopoverOpts): {
   root: HTMLDivElement;
   card: HTMLDivElement;
   body: HTMLDivElement;
+  affordance: ScrollAffordance;
   position(): void;
 } {
   const root = document.createElement('div');
@@ -143,6 +150,9 @@ export function createPopover(opts: PopoverOpts): {
   // Clicks inside the card must not reach the dismiss layer.
   card.addEventListener('pointerdown', (e) => e.stopPropagation());
   root.addEventListener('pointerdown', opts.onClose);
+  // The card clamps itself to `maxHeight` in position(), so the body's overflow is only knowable
+  // after that runs — hence the sync at the end of position().
+  const affordance = attachScrollAffordance(body, { cueHost: card });
 
   const resolveEl = (v: HTMLElement | null | (() => HTMLElement | null) | undefined): HTMLElement | null =>
     typeof v === 'function' ? v() : (v ?? null);
@@ -222,6 +232,7 @@ export function createPopover(opts: PopoverOpts): {
       arrow.style.display = '';
       arrow.style.left = `${p.arrowX / s}px`;
     }
+    affordance.sync();
   };
-  return { root, card, body, position };
+  return { root, card, body, affordance, position };
 }

package/src/ui/html/scroll-affordance.ts

@@ -0,0 +1,144 @@
+import { scrollHint, scrollEdge } from '@/core/scrollHint';
+
+/**
+ * Make a scrollable region say so.
+ *
+ * The DOM half of the affordance. It writes two dataset marks the stylesheet reads —
+ * `data-scroll="start|mid|end"` and `data-scroll-axis` — and owns the one part CSS alone cannot do:
+ * a chevron that appears on an overflowing region and retires once the player has scrolled.
+ *
+ * The cue is a SIBLING of the scroller, not a child. A child would scroll away with the content on
+ * the very first drag, which is precisely when it still has something to say.
+ */
+
+export type ScrollAxis = 'y' | 'x';
+
+export interface ScrollAffordanceOpts {
+  /** Which axis overflows. `x` is the buy-bonus card strip; everything else is `y`. */
+  axis?: ScrollAxis;
+  /** Where the chevron is appended. Defaults to the scroller's parent, which is what every shell
+   *  surface wants — pass one explicitly when the parent is itself clipped. */
+  cueHost?: HTMLElement | null;
+  /** Draw the chevron at all (default true). The buy-bonus card strip opts out: it already carries
+   *  its own ‹ › arrows, and a second, differently-shaped hint for the same gesture reads as two
+   *  controls rather than one. The thumb and the edge fade still apply. */
+  cue?: boolean;
+}
+
+export interface ScrollAffordance {
+  /** Re-measure and repaint the marks. Call after content or size changes; `scroll` is automatic. */
+  sync(): void;
+  /** Detach listeners and restore the element. */
+  destroy(): void;
+}
+
+/** Cue diameter, mirrored in the stylesheet. Kept here because the cue is positioned in JS. */
+const CUE_SIZE = 22;
+const CUE_GAP = 6;
+
+/** The chevron glyph, inline so it needs no icon-set entry and no font. */
+const CUE_SVG =
+  '<svg viewBox="0 0 24 24" width="100%" height="100%" fill="none" stroke="currentColor" ' +
+  'stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M5 9l7 7 7-7"/></svg>';
+
+export function attachScrollAffordance(el: HTMLElement, opts: ScrollAffordanceOpts = {}): ScrollAffordance {
+  const axis: ScrollAxis = opts.axis ?? 'y';
+  let cue: HTMLElement | null = null;
+  // Once the player scrolls they have discovered the gesture; re-offering it every time they
+  // return to the top would nag rather than inform.
+  let cueRetired = false;
+  let destroyed = false;
+
+  if (axis === 'x') el.dataset.scrollAxis = 'x';
+
+  const removeCue = (): void => {
+    cue?.remove();
+    cue = null;
+  };
+
+  const showCue = (): void => {
+    if (cue || cueRetired || opts.cue === false) return;
+    const host = opts.cueHost ?? el.parentElement;
+    if (!host) return;
+    cue = document.createElement('div');
+    cue.className = 'ge-scroll-cue';
+    cue.setAttribute('aria-hidden', 'true');
+    cue.innerHTML = CUE_SVG;
+    host.appendChild(cue);
+    positionCue();
+  };
+
+  /** Pin the cue to the bottom of the SCROLLER, not of its host. The buy-bonus overlay hangs a bet
+   *  bar below its scroll region, and a cue pinned to the host's bottom edge lands on top of it. */
+  const positionCue = (): void => {
+    if (!cue) return;
+    const size = cue.offsetWidth || CUE_SIZE;
+    if (axis === 'x') {
+      cue.style.left = `${el.offsetLeft + el.offsetWidth - size - CUE_GAP}px`;
+      cue.style.top = `${el.offsetTop + (el.offsetHeight - size) / 2}px`;
+    } else {
+      cue.style.left = `${el.offsetLeft + (el.offsetWidth - size) / 2}px`;
+      cue.style.top = `${el.offsetTop + el.offsetHeight - size - CUE_GAP}px`;
+    }
+  };
+
+  const sync = (): void => {
+    if (destroyed) return;
+    const h =
+      axis === 'x'
+        ? scrollHint({ scrollTop: el.scrollLeft, scrollHeight: el.scrollWidth, clientHeight: el.clientWidth })
+        : scrollHint({ scrollTop: el.scrollTop, scrollHeight: el.scrollHeight, clientHeight: el.clientHeight });
+    const edge = scrollEdge(h);
+    if (edge === 'none') {
+      delete el.dataset.scroll;
+      removeCue();
+      return;
+    }
+    el.dataset.scroll = edge;
+    if (edge === 'start') {
+      showCue();
+      positionCue(); // the scroller can move/resize under a cue that is already up
+    } else {
+      removeCue();
+    }
+  };
+
+  // Retirement is keyed off actual MOVEMENT, not off the event. A browser also fires `scroll` when
+  // content reflows under a pinned offset, and a hint dismissed by a reflow the player never caused
+  // is a hint they never saw.
+  let lastPos = axis === 'x' ? el.scrollLeft : el.scrollTop;
+  const onScroll = (): void => {
+    const pos = axis === 'x' ? el.scrollLeft : el.scrollTop;
+    if (pos !== lastPos) {
+      lastPos = pos;
+      cueRetired = true;
+      removeCue();
+    }
+    sync();
+  };
+  el.addEventListener('scroll', onScroll, { passive: true });
+
+  // Content in these regions is built asynchronously (fonts, images, a rebuilt body on resize), so
+  // a single sync at mount would measure the wrong thing. ResizeObserver is absent in jsdom.
+  const RO = (globalThis as { ResizeObserver?: typeof ResizeObserver }).ResizeObserver;
+  const ro = typeof RO === 'function' ? new RO(() => sync()) : null;
+  if (ro) {
+    ro.observe(el);
+    if (el.firstElementChild) ro.observe(el.firstElementChild);
+  }
+
+  sync();
+
+  return {
+    sync,
+    destroy(): void {
+      if (destroyed) return;
+      destroyed = true;
+      el.removeEventListener('scroll', onScroll);
+      ro?.disconnect();
+      delete el.dataset.scroll;
+      delete el.dataset.scrollAxis;
+      removeCue();
+    },
+  };
+}

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

@@ -168,6 +168,68 @@ export const SHELL_CSS = SHELL_FONT_CSS + SHELL_DIGIT_FONT_CSS + `
   transition:background .12s ease, color .12s ease; }
 #${SHELL_ROOT_ID} .ge-ov-nav:hover { background:var(--shell-plaque-glass); color:var(--shell-accent); }
 #${SHELL_ROOT_ID} .ge-ov-scroll { flex:1 1 auto; min-height:0; overflow-y:auto; overflow-x:hidden; }
+
+/* ═══ scroll affordance — "there is more, and you can reach it" ═══════════════════════════════
+   A Stake popout is 400×225. Game info holds twelve screens there, buy-bonus stacks its cards, and
+   the menu popover hides its last row. All of them scrolled already; none of them said so, and
+   Stake rejected the build for it. macOS is the aggravating factor — its overlay scrollbars stay
+   invisible until something is ALREADY scrolling, so the one moment a player needs the hint is the
+   one moment the OS withholds it. Styling the scrollbar at all opts out of that behaviour.
+
+   Three layers, all keyed off data-scroll (written by attachScrollAffordance):
+     1. a persistent thumb — the standing "this scrolls" mark;
+     2. a mask fade at whichever edge hides content — the mask applies to the element's own box, so
+        it does NOT travel with the content the way a child gradient would;
+     3. a chevron, shown only in the start state and retired for good on the first scroll.
+   The end state deliberately gets no trailing fade: there is nothing left below to hint at. */
+/* Order matters here, and not for cascade reasons. Chromium honours the STANDARD scrollbar
+   properties when they are present and then ignores ::-webkit-scrollbar entirely — and on macOS the
+   standard properties leave the scrollbar in overlay mode, i.e. invisible until it is already
+   moving. Defining ::-webkit-scrollbar with a width is what switches that scroller to a classic,
+   always-painted, still-draggable scrollbar. So the standard properties are quarantined behind an
+   @supports that only Firefox (which has no ::-webkit-scrollbar) satisfies. */
+@supports not selector(::-webkit-scrollbar) {
+  #${SHELL_ROOT_ID} [data-scroll] { scrollbar-width:thin;
+    scrollbar-color:var(--shell-scrollbar,rgba(255,255,255,.34)) transparent; } }
+#${SHELL_ROOT_ID} [data-scroll]::-webkit-scrollbar { width:6px; height:6px; }
+#${SHELL_ROOT_ID} [data-scroll]::-webkit-scrollbar-track { background:transparent; }
+#${SHELL_ROOT_ID} [data-scroll]::-webkit-scrollbar-thumb { border-radius:999px;
+  background:var(--shell-scrollbar,rgba(255,255,255,.34)); }
+#${SHELL_ROOT_ID} [data-scroll]::-webkit-scrollbar-thumb:hover { background:var(--shell-accent); }
+/* Vertical fade. The stop pair is the same on both edges; only which edges are opaque changes.
+   mask-composite-free on purpose — a single multi-stop gradient handles the two-edge case. */
+#${SHELL_ROOT_ID} [data-scroll="start"]:not([data-scroll-axis="x"]) {
+  -webkit-mask-image:linear-gradient(to bottom, #000 calc(100% - 34px), transparent 100%);
+          mask-image:linear-gradient(to bottom, #000 calc(100% - 34px), transparent 100%); }
+#${SHELL_ROOT_ID} [data-scroll="mid"]:not([data-scroll-axis="x"]) {
+  -webkit-mask-image:linear-gradient(to bottom, transparent 0, #000 22px, #000 calc(100% - 34px), transparent 100%);
+          mask-image:linear-gradient(to bottom, transparent 0, #000 22px, #000 calc(100% - 34px), transparent 100%); }
+#${SHELL_ROOT_ID} [data-scroll="end"]:not([data-scroll-axis="x"]) {
+  -webkit-mask-image:linear-gradient(to bottom, transparent 0, #000 22px);
+          mask-image:linear-gradient(to bottom, transparent 0, #000 22px); }
+/* Horizontal fade — the buy-bonus card strip. */
+#${SHELL_ROOT_ID} [data-scroll="start"][data-scroll-axis="x"] {
+  -webkit-mask-image:linear-gradient(to right, #000 calc(100% - 30px), transparent 100%);
+          mask-image:linear-gradient(to right, #000 calc(100% - 30px), transparent 100%); }
+#${SHELL_ROOT_ID} [data-scroll="mid"][data-scroll-axis="x"] {
+  -webkit-mask-image:linear-gradient(to right, transparent 0, #000 20px, #000 calc(100% - 30px), transparent 100%);
+          mask-image:linear-gradient(to right, transparent 0, #000 20px, #000 calc(100% - 30px), transparent 100%); }
+#${SHELL_ROOT_ID} [data-scroll="end"][data-scroll-axis="x"] {
+  -webkit-mask-image:linear-gradient(to right, transparent 0, #000 20px);
+          mask-image:linear-gradient(to right, transparent 0, #000 20px); }
+/* The chevron. Its host is whatever box CONTAINS the scroller (overlay root / popover card), so it
+   holds still while the content moves under it. */
+#${SHELL_ROOT_ID} .ge-scroll-cue { position:absolute; left:0; top:0; z-index:2;
+  width:22px; height:22px; padding:3px; box-sizing:border-box;
+  display:flex; align-items:center; justify-content:center; pointer-events:none;
+  border-radius:50%; color:#fff; background:var(--shell-plaque-dark);
+  box-shadow:0 2px 10px rgba(0,0,0,.45); animation:ge-scroll-cue 1.6s ease-in-out infinite; }
+@keyframes ge-scroll-cue {
+  0%,100% { transform:translateY(0); opacity:.85; }
+  50%     { transform:translateY(4px); opacity:1; } }
+/* A player who has asked for stillness still needs the hint — keep the chevron, drop the bob. */
+@media (prefers-reduced-motion: reduce) {
+  #${SHELL_ROOT_ID} .ge-scroll-cue { animation:none; opacity:.95; } }
 #${SHELL_ROOT_ID} .ge-ov-body { max-width:800px; margin:0 auto; box-sizing:border-box;
   padding:clamp(6px,2vh,16px) clamp(16px,4vw,24px) clamp(16px,4vh,28px); }
 
@@ -529,7 +591,9 @@ export const SHELL_CSS = SHELL_FONT_CSS + SHELL_DIGIT_FONT_CSS + `
    card's font-size is the one knob (clamped for readability); everything inside is em-relative so
    the whole card scales as a unit. GameShell.fitModal() still transform-scales it down as a
    backstop for very short popouts. */
-#${SHELL_ROOT_ID} .ge-modal-card { font-size:clamp(11px, 2cqmin, 15px); width:100%; max-width:28em; box-sizing:border-box;
+/* position:relative is here for the scroll cue: the card is the cue's containing block, so a
+   capped, scrolling chip grid hints at its bottom edge rather than the screen's. */
+#${SHELL_ROOT_ID} .ge-modal-card { position:relative; font-size:clamp(11px, 2cqmin, 15px); width:100%; max-width:28em; box-sizing:border-box;
   overflow:hidden; transform-origin:center center; background:var(--shell-plaque-solid); border-radius:1.3em;
   display:flex; flex-direction:column; }
 /* ✕ pinned to the overlay corner (the screen), not the card */

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

@@ -15,6 +15,7 @@ import {
 } from '../primitives/widgets';
 import type { SpinAutoplayMode } from '../primitives/widgets';
 import type { IconName } from '../icons';
+import { bonusBuyLocked } from '@/core/state';
 
 // ── 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
@@ -425,7 +426,12 @@ export class BottomBar extends Container {
     if (config.features.turbo > 0) {
       this.turboBtn = makeTurboButton(this.host, state.turbo, () => this.onTurbo(), 40, 22);
     }
-    const buy = isBase ? (this.buildBuy(M_BUY, 9, 2) ?? undefined) : undefined;
+    // On `this`, not a local: applyBusy() guards every line with `if (this.<control>)`, so a coin
+    // kept in a local is drawn, laid out, tappable — and unreachable by every lock there is.
+    // That is exactly how a phone player could tap SPIN and open buy-bonus on the round in
+    // flight. (Safe for layout: applyFit() hands mobile to applyFitMobile() before it touches
+    // `this.buy` for the wide bar's positioning.)
+    this.buy = isBase ? (this.buildBuy(M_BUY, 9, 2) ?? undefined) : undefined;
 
     // level 1 — controls bar (dark)
     const controls = new FlexBox({
@@ -445,7 +451,7 @@ export class BottomBar extends Container {
       if (this.autoBtn) lz.add(this.autoBtn);
       const rz = new FlexBox({ direction: 'row', align: 'center', gap: SIDE, justify: 'end' });
       if (this.turboBtn) rz.add(this.turboBtn);
-      if (buy) rz.add(buy);
+      if (this.buy) rz.add(this.buy);
       const zw = Math.max(lz.measureSize().w, rz.measureSize().w);
       lz.setLayoutSize(zw, undefined);
       rz.setLayoutSize(zw, undefined);
@@ -608,7 +614,7 @@ export class BottomBar extends Container {
     if (this.betDown) this.betDown.disabled = lockBet || i <= 0;
     if (this.spin) this.spin.disabled = state.busy && !auto;
     if (this.autoBtn) this.autoBtn.disabled = state.busy && !auto;
-    if (this.buy) this.buy.disabled = state.busy || auto || !state.buyBonusEnabled;
+    if (this.buy) this.buy.disabled = bonusBuyLocked(state);
     if (this.betReadout && lockBet) {
       this.betReadout.eventMode = 'none';
       this.betReadout.cursor = 'default';

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

@@ -10,6 +10,8 @@ import { navButton } from '../primitives/overlay';
 import { clamp } from '../primitives/overlay';
 import { attachHover } from '../primitives/widgets';
 import { roundedPath } from '../primitives/flex';
+import { ScrollAffordanceView } from '../primitives/scroll-affordance';
+import { scrollHint } from '@/core/scrollHint';
 
 /** 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
@@ -43,6 +45,10 @@ class BuyBonusOverlay extends Container implements ShellLayer {
   private header = new Container();
   private strip = new Container(); // cards live here (drag-scrollable when wide)
   private stripMask = new Graphics();
+  /** "the strip moves" — the drawn marks over the card band. Unmasked and outside `strip`, so a
+   *  drag moves the cards under it while the marks hold still. Public for the same reason
+   *  ScrollBox.affordance is: it is the only readable account of what a player sees here. */
+  readonly scrollCue: ScrollAffordanceView;
   private footer = new Container();
   private confirm?: Container;
   /** The bonus shown in the current confirm dialog (set by openConfirm, cleared by removeConfirm). */
@@ -80,7 +86,8 @@ class BuyBonusOverlay extends Container implements ShellLayer {
     super();
     this.host = host;
     this.bonuses = bonuses;
-    this.addChild(this.veil, this.strip, this.header, this.footer);
+    this.scrollCue = new ScrollAffordanceView(host.ticker);
+    this.addChild(this.veil, this.strip, this.scrollCue, this.header, this.footer);
     this.veil.eventMode = 'static';
     this.strip.mask = this.stripMask;
     this.addChild(this.stripMask);
@@ -108,6 +115,7 @@ class BuyBonusOverlay extends Container implements ShellLayer {
     this.dragX = Math.max(-this.dragMax, Math.min(0, this.dragBase + (cur - this.dragFrom)));
     if (this.dragAxis === 'x') this.strip.position.x = this.dragBaseX + this.dragX;
     else this.strip.position.y = this.dragBaseY + this.dragX;
+    this.syncScrollCue();
   };
   private onDragUp = (): void => {
     this.dragging = false;
@@ -126,6 +134,17 @@ class BuyBonusOverlay extends Container implements ShellLayer {
     this.dragging = false;
     this.strip.eventMode = 'auto'; // visual-only; its children (cards) are still hit-tested in-band
     this.strip.position.set(baseX, baseY);
+    this.syncScrollCue();
+  }
+
+  /** Re-draw the band's scroll marks from the current drag state. `dragX` runs [-dragMax, 0] as the
+   *  strip is pulled, so the scroll position is its negation. */
+  private syncScrollCue(): void {
+    if (this.destroyed || this.scrollCue.destroyed) return;
+    this.scrollCue.update(
+      { x: 0, y: this.bandTop, w: this.w, h: this.bandH, axis: this.dragAxis },
+      scrollHint({ scrollTop: -this.dragX, scrollHeight: this.bandH + this.dragMax, clientHeight: this.bandH }),
+    );
   }
 
   resize(w: number, h: number): void {

package/src/ui/pixi/primitives/overlay.ts

@@ -72,7 +72,7 @@ export class Overlay extends Container implements ShellLayer {
     this.host = host;
     this.opts = opts;
     this.tag = opts.tag;
-    this.scroll = new ScrollBox(host.canvas);
+    this.scroll = new ScrollBox(host.canvas, host.ticker);
     this.addChild(this.veil, this.scroll, this.header);
     this.veil.eventMode = 'static'; // swallow clicks to the game behind
     this.resize(host.screenW, host.screenH);