@energy8platform/shell 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/shell",
-  "version": "0.8.0",
+  "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/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

@@ -156,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.8.0';
+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/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;

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

@@ -362,8 +362,20 @@ export interface SpinDiscOpts {
   ticker: Ticker;
   onSpin: () => void;
   onStop: () => void;
+  /** Tapped in the halted-autoplay state — resume the run with the count still on the disc. */
+  onResume?: () => void;
 }
 
+/**
+ * What the disc is showing:
+ *  - `off` — an ordinary SPIN disc;
+ *  - `running` — STOP glyph over the live countdown;
+ *  - `paused` — a run halted with spins still owed (a lost connection). The count stays put and a
+ *    tap resumes; clearing it is the autoplay button's job. Certification asks for exactly this:
+ *    the run stops, and after reconnection the counter is still there and still correct.
+ */
+export type SpinAutoplayMode = 'off' | 'running' | 'paused';
+
 export class SpinDisc extends Container implements Sizable {
   private size: number;
   private glyphSize: number;
@@ -375,13 +387,14 @@ export class SpinDisc extends Container implements Sizable {
   private glyph: IconView;
   private dim = new Graphics();
   private countText?: Text;
-  private mode: 'spin' | 'stop' = 'spin';
+  private mode: 'spin' | 'stop' | 'resume' = 'spin';
   private _busy = false;
   private _disabled = false;
   private hovering = false;
   private rotTick?: (t: Ticker) => void;
   private onSpin: () => void;
   private onStop: () => void;
+  private onResume: () => void;
 
   constructor(opts: SpinDiscOpts) {
     super();
@@ -391,6 +404,7 @@ export class SpinDisc extends Container implements Sizable {
     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);
@@ -409,6 +423,7 @@ export class SpinDisc extends Container implements Sizable {
     attachPress(this, 0.94, () => {
       if (this._disabled) return;
       if (this.mode === 'stop') this.onStop();
+      else if (this.mode === 'resume') this.onResume();
       else this.onSpin();
     });
   }
@@ -420,8 +435,10 @@ export class SpinDisc extends Container implements Sizable {
     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
-    if (this.countText) this.countText.style.fill = '#ffffff';
+    // 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 = 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).
@@ -431,31 +448,44 @@ export class SpinDisc extends Container implements Sizable {
     }
   }
 
-  /** STOP glyph + remaining-count, when autoplay runs. */
-  setAutoplay(active: boolean, remaining: number): void {
-    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: SpinAutoplayMode, remaining: number): void {
+    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();
   }
 
@@ -475,6 +505,22 @@ export class SpinDisc extends Container implements Sizable {
     }
   }
 
+  private autoGlyphView?: IconView;
+  private autoGlyph(): void {
+    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);
+  }
+  private removeAutoGlyph(): void {
+    if (this.autoGlyphView) {
+      this.removeChild(this.autoGlyphView);
+      this.autoGlyphView.destroy();
+      this.autoGlyphView = undefined;
+    }
+  }
+
   setBusy(busy: boolean): void {
     this._busy = busy;
     if (busy && this.mode === 'spin') this.startRotation();