@energy8platform/shell 0.10.0 → 0.11.0

package/dist/html.cjs.js

@@ -1738,7 +1738,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) {
@@ -2224,6 +2224,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.
@@ -2427,6 +2487,68 @@ 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); }
 
@@ -2788,7 +2910,9 @@ 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 */
@@ -3224,6 +3348,113 @@ function applyBusy(host, bar) {
         buy.disabled = busy || auto || !host.state.buyBonusEnabled;
 }
 
+/** 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>';
+function attachScrollAffordance(el, opts = {}) {
+    const axis = opts.axis ?? 'y';
+    let cue = 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 = () => {
+        cue?.remove();
+        cue = null;
+    };
+    const showCue = () => {
+        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 = () => {
+        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 = () => {
+        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 = () => {
+        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.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() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            el.removeEventListener('scroll', onScroll);
+            ro?.disconnect();
+            delete el.dataset.scroll;
+            delete el.dataset.scrollAxis;
+            removeCue();
+        },
+    };
+}
+
 /** A centred CARD modal — frosted backdrop + opaque card with an accent title heading and an
  *  overlay ✕ in the top-right. The shared chrome for every centred modal (buy-bonus confirm,
  *  bet, autoplay, generic openModal). Append content to `body`; append full-bleed footer
@@ -3258,8 +3489,9 @@ function createCardModal(opts) {
     }
     return { root, card, body };
 }
-/** Full-screen overlay. Returns { root, body, scroll }; append content to body.
- *  The `scroll` element is the scrollable container (overflow-y: auto). */
+/** 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. */
 function createOverlay(opts) {
     const root = document.createElement('div');
     root.className = 'ge-shell-overlay';
@@ -3297,7 +3529,9 @@ function createOverlay(opts) {
     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 };
 }
 /** A light-dismiss popover: a transparent full-surface layer (closes on pointerdown) holding a
  *  card with an arrow that points at `pointer`. Append rows to `body`; call `position()` after the
@@ -3318,6 +3552,9 @@ function createPopover(opts) {
     // 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) => typeof v === 'function' ? v() : (v ?? null);
     /** A rect in surface coordinates, or null when unresolved/fully zero-sized (a zero-HEIGHT rect —
      *  e.g. a not-yet-laid-out anchor — is still considered valid, matching placePopover's own rule). */
@@ -3393,8 +3630,9 @@ function createPopover(opts) {
             arrow.style.display = '';
             arrow.style.left = `${p.arrowX / s}px`;
         }
+        affordance.sync();
     };
-    return { root, card, body, position };
+    return { root, card, body, affordance, position };
 }
 
 /** The bar menu, as a light-dismiss popover anchored to the burger. Rows come from the core model,
@@ -3545,7 +3783,7 @@ function buildRow(host, row, updaters, reposition) {
 const HOTKEYS_DEFAULT_ORDER = -0.5;
 const SVG_NS = 'http://www.w3.org/2000/svg';
 function openGameInfoModal(host) {
-    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(); },
@@ -3571,6 +3809,8 @@ function openGameInfoModal(host) {
         .sort((a, b) => a.k - b.k || a.i - b.i)
         .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 = () => Math.floor(scroll.clientHeight * 0.9) || Math.floor(540 * 0.9);
     const onKey = (e) => {
@@ -3963,10 +4203,13 @@ function openBuyBonusOverlay(host) {
     if (bonuses === false || bonuses.length === 0)
         return null;
     const st = { 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 = null;
     // Re-render the grid whenever the bet changes so every card's price stays live.
     const renderGrid = () => {
+        gridAffordance?.destroy();
         body.innerHTML = '';
         const grid = document.createElement('div');
         grid.className = 'ge-bb-grid';
@@ -3992,6 +4235,11 @@ function openBuyBonusOverlay(host) {
         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();
     root.appendChild(buildBetBar(host, renderGrid)); // thin bottom footer, only as tall as the pill
@@ -4322,6 +4570,9 @@ function buildSheet(opts) {
         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() {
         opts.onConfirm(selected);
         opts.onClose();
@@ -4825,6 +5076,7 @@ exports.HtmlRenderer = HtmlRenderer;
 exports.PACKAGE_VERSION = PACKAGE_VERSION;
 exports.POPOVER = POPOVER;
 exports.SCHEMES = SCHEMES;
+exports.SCROLL_THUMB_MIN = SCROLL_THUMB_MIN;
 exports.ShellController = ShellController;
 exports.createGameShell = createGameShell;
 exports.createI18n = createI18n;
@@ -4838,6 +5090,8 @@ exports.removeGameShell = removeGameShell;
 exports.resolveConfig = resolveConfig;
 exports.resolveMenu = resolveMenu;
 exports.resolveTheme = resolveTheme;
+exports.scrollEdge = scrollEdge;
+exports.scrollHint = scrollHint;
 exports.seedMenuValues = seedMenuValues;
 exports.socialize = socialize;
 //# sourceMappingURL=html.cjs.js.map