@energy8platform/shell 0.8.0 → 0.9.0

package/dist/pixi.d.ts

@@ -305,8 +305,13 @@ interface AutoplayConfig {
 }
 interface ShellFeatures {
     turbo: 0 | 1 | 2 | 3;
-    /** Master keyboard-shortcut switch. Defaults to `true`; set `false` to disable ALL hotkeys
-     *  (overrides `spacebar` and any future hotkey). */
+    /** Master keyboard-shortcut switch: `false` disables ALL hotkeys (overrides `spacebar` and any
+     *  future hotkey) AND hides the Hotkeys section of Game Info, including one the game supplied
+     *  itself — a keycap chart for keys that do nothing is worse than no chart.
+     *
+     *  Left unset, the shell measures the client (`core/device.ts`): a touchscreen has no keys to
+     *  press, so it gets neither the shortcuts nor the chart. Set it explicitly when you know better
+     *  than the media query — which is what the host does with the platform's `device` field. */
     hotkeys?: boolean;
     /** Spacebar starts a spin in base mode. Defaults to `true`; set `false` to disable the
      *  keyboard shortcut (e.g. jurisdictions that forbid quick-spin keys). */
@@ -638,7 +643,7 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.8.0";
+    readonly engineVersion = "0.9.0";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
@@ -783,7 +788,7 @@ interface I18n {
 declare function createI18n(opts: I18nOptions): I18n;
 
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-declare const PACKAGE_VERSION = "0.8.0";
+declare const PACKAGE_VERSION = "0.9.0";
 
 /** A shell: the renderer-agnostic controller plus the surface facade (safeArea/barHeight/setVisible)
  *  an embedding host reads. `createShell`, `createGameShell` and `createPixiShell` all return this. */

package/dist/pixi.esm.js

@@ -1690,9 +1690,41 @@ class KeyboardController {
     }
 }
 
+/**
+ * Can the player in front of this client actually press a key?
+ *
+ * The shell documents its shortcuts in a Hotkeys section and binds Spacebar to spin. On a phone
+ * neither is reachable, and showing a keycap chart to someone holding a touchscreen is a promise
+ * the game can't keep — a certification lab reads it as a feature offered where it doesn't work.
+ *
+ * The question is deliberately NOT "is the layout narrow" (a portrait desktop window still has a
+ * keyboard) and NOT "is there a touchscreen" (a touch laptop has both). It is: what does the
+ * PRIMARY pointer look like, and can it hover? Coarse-and-hoverless is a touchscreen, and a
+ * touchscreen is the one case where the keys genuinely aren't there.
+ *
+ * A tablet with a keyboard case answers "coarse, no hover" too and loses the chart. That is the
+ * right side to be wrong on: the chart is a convenience, and the keys keep working for anyone who
+ * has them — the media query only decides what the shell ADVERTISES (hosts can still say outright,
+ * via `features.hotkeys`, and the platform's own `device` field does exactly that).
+ */
+/** A touchscreen: the primary pointer is a finger, and nothing can hover. */
+const TOUCH_ONLY = '(pointer: coarse) and (hover: none)';
+function keyboardCapable(win = typeof window === 'undefined' ? undefined : window) {
+    // No window (SSR, node tests) or a browser too old for matchMedia: assume a keyboard rather than
+    // silently stripping shortcuts from a desktop we simply failed to measure.
+    if (typeof win?.matchMedia !== 'function')
+        return true;
+    try {
+        return !win.matchMedia(TOUCH_ONLY).matches;
+    }
+    catch {
+        return true;
+    }
+}
+
 // AUTO-GENERATED by scripts/gen-version.mjs — do not edit. Mirrors package.json "version".
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-const PACKAGE_VERSION = '0.8.0';
+const PACKAGE_VERSION = '0.9.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {
@@ -1706,7 +1738,10 @@ function resolveConfig(config) {
         win: config.win,
         mode: config.mode,
         gameInfo: config.gameInfo,
-        features: config.features,
+        // `hotkeys` unset means "decide for me": a touchscreen has no keys to press, so the shell
+        // neither binds them nor advertises them there. A host that knows better — the platform's own
+        // `device` field, a jurisdiction rule — says so outright and that wins. See core/device.ts.
+        features: { ...config.features, hotkeys: config.features.hotkeys ?? keyboardCapable() },
         theme: config.theme,
         onBonusBuy: config.onBonusBuy,
         volumes: config.volumes,
@@ -1800,7 +1835,11 @@ class ShellController extends EventEmitter {
                 this.renderer.renderBar();
             },
             toggleAutoplay: () => {
-                if (this.state.autoplay.active)
+                // A halted run (stopped, but with spins still owed after a lost connection) counts as
+                // "autoplay is on screen": the toggle retires its leftover count, exactly as it stops a
+                // running one. Resuming those spins is the disc's job, not this one's.
+                const { active, remaining } = this.state.autoplay;
+                if (active || remaining > 0)
                     a.stopAutoplay();
                 else
                     this.openAutoplayPicker();
@@ -3087,6 +3126,7 @@ class SpinDisc extends Container {
     rotTick;
     onSpin;
     onStop;
+    onResume;
     constructor(opts) {
         super();
         this.size = opts.size ?? 84;
@@ -3095,6 +3135,7 @@ class SpinDisc extends Container {
         this.ticker = opts.ticker;
         this.onSpin = opts.onSpin;
         this.onStop = opts.onStop;
+        this.onResume = opts.onResume ?? opts.onSpin;
         this.disc = new Graphics();
         this.glyph = makeIcon('spin', this.glyphSize, this.tokens.btnInk);
         this.glyph.position.set((this.size - this.glyphSize) / 2, (this.size - this.glyphSize) / 2);
@@ -3115,6 +3156,8 @@ class SpinDisc extends Container {
                 return;
             if (this.mode === 'stop')
                 this.onStop();
+            else if (this.mode === 'resume')
+                this.onResume();
             else
                 this.onSpin();
         });
@@ -3126,9 +3169,10 @@ class SpinDisc extends Container {
         drawDisc(this.disc, this.size, this.tokens.btn, 4);
         const glyphColor = hot ? this.tokens.accent : this.tokens.btnInk;
         this.glyph.setColor(glyphColor);
-        // the count sits ON the solid (btnInk) STOP square, so it must be light to read
+        // the count sits ON the solid (btnInk) STOP square, so it must be light to read; halted, it
+        // sits on the bare disc instead and takes the disc's own ink.
         if (this.countText)
-            this.countText.style.fill = '#ffffff';
+            this.countText.style.fill = this.mode === 'resume' ? this.tokens.btnInk : '#ffffff';
         // Disabled (mid-spin / can't spin): darken OPAQUELY (≈ filter:grayscale(.4) brightness(.62))
         // with a dark veil over the disc — not alpha, which would let the bright board show through and
         // read as a translucent/missing button (what looked "transparent" while spinning).
@@ -3137,32 +3181,45 @@ class SpinDisc extends Container {
             this.dim.circle(this.size / 2, this.size / 2, this.size / 2 - 1.5).fill({ color: 0x000000, alpha: 0.4 });
         }
     }
-    /** STOP glyph + remaining-count, when autoplay runs. */
-    setAutoplay(active, remaining) {
-        if (active) {
-            this.mode = 'stop';
-            this.stopRotation();
-            // STOP glyph at the disc's full size (like SPIN); the count is centred on top of it.
-            this.glyph.visible = false;
-            this.stopGlyph();
-            if (!this.countText) {
-                this.countText = makeText('', { size: 22, weight: '800', color: '#ffffff', align: 'center', family: NUM_FONT_FAMILY });
-                this.addChild(this.countText); // added after the STOP glyph → renders on top of it
-            }
-            const label = Number.isFinite(remaining) ? String(remaining) : '∞';
-            setText(this.countText, label);
-            this.countText.position.set((this.size - this.countText.width) / 2, (this.size - this.countText.height) / 2);
-        }
-        else {
+    /** STOP glyph + remaining-count while autoplay runs; auto glyph + the same count once it halts. */
+    setAutoplay(mode, remaining) {
+        if (mode === 'off') {
             this.mode = 'spin';
             this.glyph.visible = true;
             this.removeStopGlyph();
+            this.removeAutoGlyph();
             if (this.countText) {
                 this.removeChild(this.countText);
                 this.countText.destroy();
                 this.countText = undefined;
             }
+            this.paint();
+            return;
+        }
+        const running = mode === 'running';
+        this.mode = running ? 'stop' : 'resume';
+        this.stopRotation();
+        this.glyph.visible = false;
+        // Running: a solid STOP square at the disc's full size (like SPIN), count centred on top of it.
+        // Halted: the auto glyph, smaller and lifted, with the count under it — no dark square, because
+        // nothing is running to stop, and a white count would have nothing to read against.
+        if (running) {
+            this.removeAutoGlyph();
+            this.stopGlyph();
+        }
+        else {
+            this.removeStopGlyph();
+            this.autoGlyph();
+        }
+        if (!this.countText) {
+            this.countText = makeText('', { size: 22, weight: '800', color: '#ffffff', align: 'center', family: NUM_FONT_FAMILY });
+            this.addChild(this.countText); // added after the glyph → renders on top of it
         }
+        setText(this.countText, Number.isFinite(remaining) ? String(remaining) : '∞');
+        const cy = running
+            ? (this.size - this.countText.height) / 2
+            : this.size * 0.56; // sits under the lifted auto glyph
+        this.countText.position.set((this.size - this.countText.width) / 2, cy);
         this.paint();
     }
     stopGlyphView;
@@ -3180,6 +3237,22 @@ class SpinDisc extends Container {
             this.stopGlyphView = undefined;
         }
     }
+    autoGlyphView;
+    autoGlyph() {
+        if (this.autoGlyphView)
+            return;
+        const size = this.glyphSize * 0.42;
+        this.autoGlyphView = makeIcon('autoplay', size, this.tokens.btnInk);
+        this.autoGlyphView.position.set((this.size - size) / 2, this.size * 0.2);
+        this.addChild(this.autoGlyphView);
+    }
+    removeAutoGlyph() {
+        if (this.autoGlyphView) {
+            this.removeChild(this.autoGlyphView);
+            this.autoGlyphView.destroy();
+            this.autoGlyphView = undefined;
+        }
+    }
     setBusy(busy) {
         this._busy = busy;
         if (busy && this.mode === 'spin')
@@ -3410,6 +3483,13 @@ function divider(tokens, height = 30) {
 }
 
 // ── design constants (mirror the DOM `.ge-bar-panel` / mobile rules) ──────────
+/** Which of the disc's three faces the autoplay state calls for — see `SpinAutoplayMode`. A run
+ *  that halted with spins still owed (`!active && remaining > 0`) keeps its counter on the disc. */
+function autoplayDiscMode(state) {
+    if (state.autoplay.active)
+        return 'running';
+    return state.autoplay.remaining > 0 ? 'paused' : 'off';
+}
 const BAR_H = 68; // continuous dark panel height
 const SPIN = 84; // hero disc — pops above/below the bar
 const SPIN_POP = (SPIN - BAR_H) / 2; // 8 — how far the disc sticks out top/bottom
@@ -3658,9 +3738,9 @@ class BottomBar extends Container {
                 ticker: this.host.ticker,
                 onSpin: () => this.host.actions.spin(),
                 onStop: () => this.stopAutoplay(),
+                onResume: () => this.resumeAutoplay(),
             });
-            if (state.autoplay.active)
-                this.spin.setAutoplay(true, state.autoplay.remaining);
+            this.spin.setAutoplay(autoplayDiscMode(state), state.autoplay.remaining);
             if (state.busy)
                 this.spin.setBusy(true);
             spinWrap.add(this.spin);
@@ -3732,9 +3812,9 @@ class BottomBar extends Container {
                 ticker: this.host.ticker,
                 onSpin: () => this.host.actions.spin(),
                 onStop: () => this.stopAutoplay(),
+                onResume: () => this.resumeAutoplay(),
             });
-            if (state.autoplay.active)
-                this.spin.setAutoplay(true, state.autoplay.remaining);
+            this.spin.setAutoplay(autoplayDiscMode(state), state.autoplay.remaining);
             if (state.busy)
                 this.spin.setBusy(true);
             hero = this.spin;
@@ -3929,8 +4009,11 @@ class BottomBar extends Container {
     onTurbo() {
         this.host.actions.cycleTurbo();
     }
+    /** Same button, three jobs: stop a running run, retire a halted run's leftover count (freeing the
+     *  disc for a manual spin again), or open the picker. Mirrors the DOM bar's `onAutoplay`. */
     onAutoplay() {
-        if (this.host.state.autoplay.active)
+        const { active, remaining } = this.host.state.autoplay;
+        if (active || remaining > 0)
             this.stopAutoplay();
         else
             this.host.actions.openAutoplayPicker();
@@ -3938,6 +4021,10 @@ class BottomBar extends Container {
     stopAutoplay() {
         this.host.actions.stopAutoplay();
     }
+    /** Halted run, tapped: play out the spins it still owes. */
+    resumeAutoplay() {
+        this.host.actions.startAutoplay(this.host.state.autoplay.remaining);
+    }
     betLocked() {
         return this.host.state.busy || this.host.state.autoplay.active;
     }
@@ -4824,10 +4911,15 @@ function openGameInfo(host) {
 }
 function buildBody(host, width) {
     const col = new FlexBox({ direction: 'column', align: 'stretch', gap: 12 });
-    const rawSections = host.config.gameInfo.sections ?? [];
-    // Auto-inject a hotkeys section unless the game already provides one or features.hotkeys === false.
+    const allSections = host.config.gameInfo.sections ?? [];
+    // Auto-inject a hotkeys section unless the game already provides one. With hotkeys off — a
+    // jurisdiction that forbids them, or a touchscreen that has no keys at all (see core/device.ts) —
+    // there is no keyboard surface to document, and a game-supplied section is dropped along with the
+    // auto-injected one: a keycap chart for keys the player cannot press is a promise the game breaks.
+    const keys = host.config.features.hotkeys !== false;
+    const rawSections = keys ? allSections : allSections.filter((s) => s.type !== 'hotkeys');
     const sectionsWithHotkeys = [...rawSections];
-    if (host.config.features.hotkeys !== false && !rawSections.some((s) => s.type === 'hotkeys')) {
+    if (keys && !rawSections.some((s) => s.type === 'hotkeys')) {
         sectionsWithHotkeys.push({ type: 'hotkeys', order: HOTKEYS_DEFAULT_ORDER });
     }
     const sections = sectionsWithHotkeys;