@energy8platform/shell 0.10.0 → 0.11.0

package/dist/pixi.cjs.js

@@ -1739,7 +1739,7 @@ function keyboardCapable(win = typeof window === 'undefined' ? undefined : windo
 
 // 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.10.0';
+const PACKAGE_VERSION = '0.11.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {
@@ -2225,6 +2225,66 @@ function placePopover(anchor, surface, size, pointer = null) {
     return { x, y, maxH, arrowX, below };
 }
 
+/**
+ * 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.
+ */
+const SCROLL_THUMB_MIN = 0.18;
+/** Resolve one axis of a scroll region into everything a renderer needs to draw its affordance. */
+function scrollHint(m) {
+    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,
+    };
+}
+function scrollEdge(h) {
+    if (!h.overflowing)
+        return 'none';
+    if (h.atStart)
+        return 'start';
+    return h.atEnd ? 'end' : 'mid';
+}
+
 const NO_INSET = { top: 0, right: 0, bottom: 0, left: 0 };
 /** Create a shell with an explicit renderer instance (custom or a built-in HtmlRenderer/PixiRenderer).
  *  Built-in renderers also have the createGameShell/createPixiShell sugar in /html and /pixi.
@@ -4150,11 +4210,207 @@ function SPIN_POP_MOBILE() {
     return (SPIN - M_CTRL_H) / 2; // 11
 }
 
+/** Thickness of the thumb, and how far it is inset from the edge it rides. */
+const THUMB_THICK = 4;
+const THUMB_INSET = 3;
+/** Shortest thumb we will draw in pixels — the fractional floor still degenerates on a tiny frame. */
+const THUMB_MIN_PX = 22;
+/** Depth of the edge scrim. */
+const SCRIM = 34;
+const SCRIM_ALPHA = 0.72;
+/** The overlay chrome — plaques, bar, backdrop — is scheme-independent in this shell (see
+ *  resolveTheme: those tokens are fixed, only the palette behind them flips). The affordance is
+ *  chrome, so it is a fixed neutral too: white marks over a tint of the same hue as the veil, which
+ *  makes the fade read as content dissolving INTO the overlay rather than as a grey band on top. */
+const SCRIM_TINT = 0x0c111c;
+const CUE_R = 11;
+const CUE_BOB = 4;
+const CUE_PERIOD = 1600; // ms
+/**
+ * The scrim's alpha ramp, densest AT the edge and clear by `depth` inward.
+ *
+ * Exported because the direction is the whole point and is easy to get backwards: an inverted ramp
+ * draws a hard-edged dark band floating over the content instead of a fade into the frame, and it
+ * looks deliberate enough that nobody questions it. The squared falloff keeps the outer half of the
+ * ramp faint, so the scrim reads as content thinning out rather than as a panel laid on top.
+ */
+function scrimRamp(depth) {
+    const slices = Math.max(1, Math.round(depth));
+    const thickness = depth / slices;
+    const out = [];
+    for (let i = 0; i < slices; i++) {
+        const offset = i * thickness;
+        const t = 1 - (offset + thickness / 2) / depth; // 1 at the edge → 0 at `depth`
+        out.push({ offset, thickness, alpha: SCRIM_ALPHA * t * t });
+    }
+    return out;
+}
+class ScrollAffordanceView extends pixi_js.Container {
+    thumb = new pixi_js.Graphics();
+    scrim = new pixi_js.Graphics();
+    cue = new pixi_js.Container();
+    ticker;
+    bounds = null;
+    cueOn = false;
+    // Once the region has moved the player knows the gesture; re-offering it on every return to the
+    // top would nag rather than inform.
+    cueRetired = false;
+    cueBaseY = 0;
+    elapsed = 0;
+    tick;
+    constructor(ticker) {
+        super();
+        this.ticker = ticker;
+        this.eventMode = 'none'; // decoration: never intercept the drag it is advertising
+        this.addChild(this.scrim, this.thumb, this.cue);
+        this.buildCue();
+        this.visible = false;
+    }
+    /** Where the thumb is drawn, in the parent's space — `null` when nothing is drawn. */
+    get thumbBounds() {
+        return this.visible ? this.bounds : null;
+    }
+    get cueVisible() {
+        return this.visible && this.cueOn;
+    }
+    /** Re-draw for a viewport and a hint. Cheap enough to call on every scroll frame. */
+    update(vp, hint) {
+        if (this.destroyed)
+            return;
+        if (!hint.overflowing) {
+            this.visible = false;
+            this.bounds = null;
+            this.showCue(false);
+            return;
+        }
+        this.visible = true;
+        // Any movement off the start retires the cue permanently.
+        if (!hint.atStart)
+            this.cueRetired = true;
+        this.drawThumb(vp, hint);
+        this.drawScrim(vp, hint);
+        this.placeCue(vp);
+        this.showCue(hint.atStart && !this.cueRetired);
+    }
+    drawThumb(vp, hint) {
+        const along = vp.axis === 'y' ? vp.h : vp.w;
+        const track = Math.max(0, along - THUMB_INSET * 2);
+        const len = Math.max(Math.min(track, THUMB_MIN_PX), track * hint.thumbSize);
+        // Recover the travel from the (possibly floored) length so the thumb still reaches both ends.
+        const travel = Math.max(0, track - len);
+        const progress = hint.thumbSize < 1 ? hint.thumbOffset / (1 - hint.thumbSize) : 0;
+        const at = THUMB_INSET + travel * progress;
+        this.bounds =
+            vp.axis === 'y'
+                ? { x: vp.x + vp.w - THUMB_INSET - THUMB_THICK, y: vp.y + at, w: THUMB_THICK, h: len }
+                : { x: vp.x + at, y: vp.y + vp.h - THUMB_INSET - THUMB_THICK, w: len, h: THUMB_THICK };
+        const b = this.bounds;
+        this.thumb.clear();
+        // A faint track behind the thumb: on a dark overlay a lone thumb can read as a stray highlight;
+        // with the groove behind it, it reads as a scrollbar.
+        if (vp.axis === 'y') {
+            this.thumb
+                .roundRect(b.x, vp.y + THUMB_INSET, THUMB_THICK, track, THUMB_THICK / 2)
+                .fill({ color: 0xffffff, alpha: 0.1 });
+        }
+        else {
+            this.thumb
+                .roundRect(vp.x + THUMB_INSET, b.y, track, THUMB_THICK, THUMB_THICK / 2)
+                .fill({ color: 0xffffff, alpha: 0.1 });
+        }
+        this.thumb.roundRect(b.x, b.y, b.w, b.h, THUMB_THICK / 2).fill({ color: 0xffffff, alpha: 0.55 });
+    }
+    /** Stacked 1px slices rather than a gradient fill: no texture, no backend-specific paths, and at
+     *  one device pixel per slice there is nothing left to band. */
+    drawScrim(vp, hint) {
+        this.scrim.clear();
+        const depth = Math.min(SCRIM, (vp.axis === 'y' ? vp.h : vp.w) / 3);
+        if (depth <= 0)
+            return;
+        for (const { offset, thickness, alpha } of scrimRamp(depth)) {
+            // `offset` is measured INWARD from whichever edge is being faded.
+            if (!hint.atEnd) {
+                if (vp.axis === 'y')
+                    this.scrim.rect(vp.x, vp.y + vp.h - offset - thickness, vp.w, thickness);
+                else
+                    this.scrim.rect(vp.x + vp.w - offset - thickness, vp.y, thickness, vp.h);
+                this.scrim.fill({ color: SCRIM_TINT, alpha });
+            }
+            if (!hint.atStart) {
+                if (vp.axis === 'y')
+                    this.scrim.rect(vp.x, vp.y + offset, vp.w, thickness);
+                else
+                    this.scrim.rect(vp.x + offset, vp.y, thickness, vp.h);
+                this.scrim.fill({ color: SCRIM_TINT, alpha });
+            }
+        }
+    }
+    buildCue() {
+        const disc = new pixi_js.Graphics();
+        disc.circle(0, 0, CUE_R).fill({ color: 0x0b0f18, alpha: 0.9 });
+        disc.circle(0, 0, CUE_R).stroke({ color: 0xffffff, alpha: 0.22, width: 1 });
+        const size = Math.round(CUE_R * 1.3);
+        const glyph = makeIcon('chevronDown', size, '#ffffff');
+        glyph.position.set(-size / 2, -size / 2);
+        this.cue.addChild(disc, glyph);
+        this.cue.visible = false;
+    }
+    placeCue(vp) {
+        // Bottom-centre for a vertical region; hugging the trailing edge for a horizontal one.
+        if (vp.axis === 'y') {
+            this.cue.x = vp.x + vp.w / 2;
+            this.cueBaseY = vp.y + vp.h - CUE_R - 6;
+        }
+        else {
+            this.cue.x = vp.x + vp.w - CUE_R - 6;
+            this.cueBaseY = vp.y + vp.h / 2;
+            this.cue.rotation = -Math.PI / 2; // chevron points the way the strip moves
+        }
+        this.cue.y = this.cueBaseY;
+    }
+    showCue(on) {
+        if (on === this.cueOn)
+            return;
+        this.cueOn = on;
+        this.cue.visible = on;
+        if (on)
+            this.startBob();
+        else
+            this.stopBob();
+    }
+    startBob() {
+        // A player who asked for stillness still needs the hint; they just do not need it moving.
+        if (this.tick || !this.ticker || prefersReducedMotion())
+            return;
+        this.elapsed = 0;
+        this.tick = (t) => {
+            this.elapsed += t.deltaMS;
+            const phase = (this.elapsed % CUE_PERIOD) / CUE_PERIOD;
+            this.cue.y = this.cueBaseY + Math.sin(phase * Math.PI * 2) * (CUE_BOB / 2) + CUE_BOB / 2;
+        };
+        this.ticker.add(this.tick);
+    }
+    stopBob() {
+        if (!this.tick)
+            return;
+        this.ticker?.remove(this.tick);
+        this.tick = undefined;
+        this.cue.y = this.cueBaseY;
+    }
+    destroy(options) {
+        this.stopBob();
+        super.destroy(options);
+    }
+}
+
 /** A vertically-scrolling viewport — mask + drag + mouse-wheel, the Pixi analogue of the
  *  overlay's `overflow-y:auto` scroll region. Add content to `.content`; call `refresh()`
  *  after content changes or a resize. */
 class ScrollBox extends pixi_js.Container {
     content = new pixi_js.Container();
+    /** The drawn "this scrolls" marks — thumb, edge scrim, chevron. Public so the overlay that owns
+     *  the box (and the tests) can read what a player would see. */
+    affordance;
     maskG = new pixi_js.Graphics();
     viewW = 0;
     viewH = 0;
@@ -4165,10 +4421,13 @@ class ScrollBox extends pixi_js.Container {
     moved = false;
     canvas;
     wheelHandler;
-    constructor(canvas) {
+    constructor(canvas, ticker) {
         super();
         this.canvas = canvas;
-        this.addChild(this.content);
+        this.affordance = new ScrollAffordanceView(ticker);
+        // Added AFTER content, and never masked: the marks describe the viewport, so clipping them to
+        // the content they describe would hide them exactly when the content overflows.
+        this.addChild(this.content, this.affordance);
         // maskG is added to the scene only while scrolling (see refresh) — a leftover unused mask
         // graphic renders as a white rect. (Masking does NOT gate pointer events to the content, despite
         // what an earlier version of this comment claimed — see the correction in refresh() below.)
@@ -4223,6 +4482,7 @@ class ScrollBox extends pixi_js.Container {
         }
         this.eventMode = scrollable ? 'static' : 'passive';
         this.setScroll(this.scrollY);
+        this.syncAffordance();
     }
     /** Max scrollable distance (0 when content fits) — exposed for tests. */
     get maxScrollY() {
@@ -4239,6 +4499,12 @@ class ScrollBox extends pixi_js.Container {
             return;
         this.scrollY = Math.max(0, Math.min(this.maxScroll, y)) || 0; // || 0 converts -0 to 0
         this.content.y = this.scrollY === 0 ? 0 : -this.scrollY;
+        this.syncAffordance();
+    }
+    syncAffordance() {
+        if (this.destroyed || this.affordance.destroyed)
+            return;
+        this.affordance.update({ x: 0, y: 0, w: this.viewW, h: this.viewH, axis: 'y' }, scrollHint({ scrollTop: this.scrollY, scrollHeight: this.viewH + this.maxScroll, clientHeight: this.viewH }));
     }
     onDown = (e) => {
         this.dragging = true;
@@ -4809,7 +5075,7 @@ class Overlay extends pixi_js.Container {
         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);
@@ -5532,6 +5798,10 @@ class BuyBonusOverlay extends pixi_js.Container {
     header = new pixi_js.Container();
     strip = new pixi_js.Container(); // cards live here (drag-scrollable when wide)
     stripMask = new pixi_js.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. */
+    scrollCue;
     footer = new pixi_js.Container();
     confirm;
     /** The bonus shown in the current confirm dialog (set by openConfirm, cleared by removeConfirm). */
@@ -5568,7 +5838,8 @@ class BuyBonusOverlay extends pixi_js.Container {
         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);
@@ -5601,6 +5872,7 @@ class BuyBonusOverlay extends pixi_js.Container {
             this.strip.position.x = this.dragBaseX + this.dragX;
         else
             this.strip.position.y = this.dragBaseY + this.dragX;
+        this.syncScrollCue();
     };
     onDragUp = () => {
         this.dragging = false;
@@ -5618,6 +5890,14 @@ class BuyBonusOverlay extends pixi_js.Container {
         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. */
+    syncScrollCue() {
+        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, h) {
         this.w = w;
@@ -7205,6 +7485,7 @@ exports.PACKAGE_VERSION = PACKAGE_VERSION;
 exports.POPOVER = POPOVER;
 exports.PixiRenderer = PixiRenderer;
 exports.SCHEMES = SCHEMES;
+exports.SCROLL_THUMB_MIN = SCROLL_THUMB_MIN;
 exports.ShellController = ShellController;
 exports.createI18n = createI18n;
 exports.createPixiShell = createPixiShell;
@@ -7218,6 +7499,8 @@ exports.removePixiShell = removePixiShell;
 exports.resolveConfig = resolveConfig;
 exports.resolveMenu = resolveMenu;
 exports.resolveTheme = resolveTheme;
+exports.scrollEdge = scrollEdge;
+exports.scrollHint = scrollHint;
 exports.seedMenuValues = seedMenuValues;
 exports.socialize = socialize;
 //# sourceMappingURL=pixi.cjs.js.map