@energy8platform/shell 0.6.6 → 0.7.1

package/src/core/state.ts

@@ -1,4 +1,5 @@
 import type { ShellConfig, ShellState } from './types';
+import { DEFAULT_MENU, seedMenuValues } from './menu';
 
 export function createInitialState(config: ShellConfig): ShellState {
   return {
@@ -16,10 +17,10 @@ export function createInitialState(config: ShellConfig): ShellState {
     bonus: null,
     activeFeature: null,
     volumes: {
-      master: clampVolume(config.volumes?.master),
       music: clampVolume(config.volumes?.music),
       sfx: clampVolume(config.volumes?.sfx),
     },
+    menu: seedMenuValues(config.menu ?? DEFAULT_MENU),
   };
 }
 

package/src/core/types.ts

@@ -1,11 +1,13 @@
+import type { MenuItem } from './menu';
+
 /** `freeSpins` and `bonus` are the SAME bar layout (host-driven hero + Total Win); `freeSpins` is
  *  kept as a back-compat alias for the common case (its readout is derived current/total), while
  *  `bonus` pairs with `setBonus()` to show a game-supplied label + value (adventure, hold-and-spin,
  *  respins — anything that isn't a plain free-spins counter). */
 export type ShellMode = 'base' | 'bonus' | 'freeSpins' | 'replay';
 
-/** The three independent volume sliders shown in the Settings overlay. */
-export type VolumeKey = 'master' | 'music' | 'sfx';
+/** The two independent volume sliders shown in the bar menu. */
+export type VolumeKey = 'music' | 'sfx';
 export type VolumeLevels = Record<VolumeKey, number>;
 
 export interface CurrencyConfig {
@@ -18,6 +20,9 @@ export interface CurrencyConfig {
    *  trimmed down to this many places so small wins keep their significant digits (e.g. 0.0673)
    *  while round amounts stay compact (e.g. 0.30). Everything else is shown at exactly this many. */
   minDecimals?: number;
+  /** Defaults to the platform convention: `{ thousands: ',', decimal: '.' }` → `€1,234.50`.
+   *  Override only for a jurisdiction that requires another convention — a comma decimal reads
+   *  as a thousands group to most players and inflates the perceived payout. */
   separator?: { thousands?: string; decimal?: string };
 }
 
@@ -250,8 +255,10 @@ export interface ShellConfig {
   onBonusBuy?: () => void;
   /** Initial Settings-overlay volume slider positions (each 0..1, defaults to 1 = 100%). The shell
    *  keeps them stateful across opens; read/update at runtime via `shell.getVolume()` /
-   *  `shell.setVolume()`, and listen to `settingChange` ({ key: 'master'|'music'|'sfx' }) to apply. */
+   *  `shell.setVolume()`, and listen to `settingChange` ({ key: 'music'|'sfx' }) to apply. */
   volumes?: Partial<VolumeLevels>;
+  /** Bar-menu items, in order. Omit for the default list (sound, music, sfx, ─, game info). */
+  menu?: MenuItem[];
 }
 
 /** ShellConfig after the controller applies defaults (version, isSocial, replay, theme). No mount. */
@@ -272,7 +279,7 @@ export type ResolvedShellConfig = Required<
     | 'replay'
   >
 > &
-  Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy' | 'volumes'>;
+  Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy' | 'volumes' | 'menu'>;
 
 export interface ShellState {
   mode: ShellMode;
@@ -295,9 +302,11 @@ export interface ShellState {
   /** The currently activated `feature` option (e.g. Ante), or null. Drives the
    *  effective-bet readout tint and the BUY BONUS → DISABLE toggle on the bar. */
   activeFeature: BonusOption | null;
-  /** Volume slider positions (0..1) surfaced in the Settings overlay. Stateful across opens so a
-   *  reopened overlay reflects the last-set positions instead of resetting to 100%. */
+  /** Volume slider positions (0..1) for the two sliders in the menu. */
   volumes: VolumeLevels;
+  /** Values of CUSTOM menu items, keyed by id. Seeded from the item list; preset values live in
+   *  their own homes (`soundOn`, `volumes`) and are reached through `getMenuValue`. */
+  menu: Record<string, boolean | number>;
 }
 
 export interface ShellEvents {

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

package/src/ui/html/HtmlRenderer.ts

@@ -4,7 +4,7 @@ import { SHELL_CSS, SHELL_ROOT_ID } from './shell.css';
 import { buildThemeVars } from './theme-css';
 import { countUp } from './motion-dom';
 import { renderBottomBar } from './components/BottomBar';
-import { openSettingsModal } from './components/Settings';
+import { openMenuPopover } from './components/Menu';
 import { openGameInfoModal } from './components/GameInfo';
 import { openBuyBonusOverlay } from './components/BuyBonus';
 import { openBetModal, openAutoplayModal } from './components/pickers';
@@ -35,7 +35,11 @@ export class HtmlRenderer implements ShellRenderer {
   private ro: ResizeObserver | null = null;
   private moneyAnims: Array<() => void> = [];
   private modalOnKey: ((e: KeyboardEvent) => boolean) | undefined;
+  private popoverPosition: (() => void) | null = null;
   private destroyed = false;
+  /** The scale factor last applied to the bar by applyFitScale() — exposed so the menu popover can
+   *  match it exactly (see getBarScale) rather than re-derive its own, possibly-disagreeing, value. */
+  private barScale = 1;
 
   /** MutationObserver for buy-bonus confirm fit — fires fitModals() when nodes are added
    *  inside the modalHost (e.g. the confirm dialog appended after the grid is open). */
@@ -81,6 +85,14 @@ export class HtmlRenderer implements ShellRenderer {
     this.barHost.innerHTML = '';
     this.barHost.appendChild(renderBottomBar(this.host));
     this.applyFitScale();
+    // renderBar() runs on every resize AND on ~20 other state changes (bet/win/turbo/mode/…), any of
+    // which can change barScale and/or the plate rect (e.g. a WIN pill appearing mid-autoplay
+    // retriggers the overflow-tightening branch). Only the resize hook used to reposition an open
+    // popover, so a live bar-content change while the menu was open left the card at the stale
+    // scale/position until the next resize. `popoverPosition` only reads plate/pointer/scale getters
+    // and writes card styles — no path back into renderBar() — so this cannot recurse; it's `null`
+    // whenever no popover is open (or a different overlay kind is), so this cannot throw either.
+    this.popoverPosition?.();
   }
 
   setLayout(): void {
@@ -102,13 +114,10 @@ export class HtmlRenderer implements ShellRenderer {
 
   closeOverlay(): void {
     this.modalOnKey = undefined;
+    this.popoverPosition = null;
     this.modalHost.innerHTML = '';
   }
 
-  refreshSoundIcon?(_on: boolean): void {
-    // Settings registers via host.setSoundRefresh; nothing extra here
-  }
-
   destroy(): Promise<void> {
     if (this.destroyed) return Promise.resolve();
     this.destroyed = true;
@@ -130,6 +139,11 @@ export class HtmlRenderer implements ShellRenderer {
   /** Trigger a bar fit-scale pass (used by tests that stub geometry after the initial render). */
   fitBar(): void { this.applyFitScale(); }
 
+  /** The scale factor applyFitScale() last applied to the bar — the menu popover multiplies its own
+   *  card by this SAME number so its typography/padding/row-heights carry the same visual weight
+   *  relationship the bar has, instead of ignoring the viewport like a fixed-px card would. */
+  getBarScale(): number { return this.barScale; }
+
   // ── private ────────────────────────────────────────────────────────────────
 
   private cancelMoneyAnims(): void {
@@ -139,8 +153,9 @@ export class HtmlRenderer implements ShellRenderer {
 
   private buildOverlay(req: OverlayRequest): { root: HTMLElement; onKey?: (e: KeyboardEvent) => boolean } | null {
     switch (req.kind) {
-      case 'settings': {
-        const root = openSettingsModal(this.host);
+      case 'menu': {
+        const { root, position } = openMenuPopover(this.host, this.root, () => this.getBarScale());
+        this.popoverPosition = position;
         return { root };
       }
       case 'gameInfo': {
@@ -183,6 +198,7 @@ export class HtmlRenderer implements ShellRenderer {
     this.modalHost.appendChild(el);
     this.modalOnKey = onKey;
     this.fitModals();
+    this.popoverPosition?.(); // measure + place now that the card is in the DOM
   }
 
   /** Uniformly scale every open centred card modal (.ge-sheet) down so it fits a short/narrow
@@ -229,13 +245,18 @@ export class HtmlRenderer implements ShellRenderer {
       let need = 0;
       for (const row of Array.from(bar.children) as HTMLElement[]) need = Math.max(need, row.scrollWidth);
       const avail = bar.clientWidth;
+      let s = 1;
       if (need > avail + 1 && avail > 0) {
+        s = Math.max(0.4, avail / need);
         host.style.transformOrigin = 'bottom left';
-        host.style.transform = `scale(${Math.max(0.4, avail / need).toFixed(4)})`;
+        host.style.transform = `scale(${s.toFixed(4)})`;
       }
+      this.barScale = s;
       return;
     }
+    let sApplied = 1;
     const zoomBar = (z: number): void => {
+      sApplied = z;
       const v = z < 0.999 ? z.toFixed(4) : '';
       const set = (el: Element | null): void => {
         if (!el) return;
@@ -252,6 +273,7 @@ export class HtmlRenderer implements ShellRenderer {
     if (bar.scrollWidth > bar.clientWidth + 1 && bar.scrollWidth > 0) {
       zoomBar(s * (bar.clientWidth / bar.scrollWidth));
     }
+    this.barScale = sApplied;
     this.fitReadouts();
   }
 
@@ -280,6 +302,7 @@ export class HtmlRenderer implements ShellRenderer {
       this.host.notifyResize(w, h);
       this.applyFitScale();
       this.fitModals();
+      this.popoverPosition?.(); // re-place the card if the surface itself resized
     });
     this.ro.observe(this.root);
   }

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

@@ -20,7 +20,7 @@ export function openGameInfoModal(host: ShellHost): GameInfoModal {
   const { root, body, scroll } = createOverlay({
     title: host.t('Game info'),
     onClose: () => host.actions.closeOverlay(),
-    onBack: () => { root.remove(); host.actions.openSettings(); },
+    onBack: () => { root.remove(); host.actions.openMenu(); },
   });
   root.dataset.ge = 'info-modal';
 

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

@@ -0,0 +1,153 @@
+import type { ShellHost } from '@/core/renderer';
+import { resolveMenu, type MenuRow } from '@/core/menu';
+import { createPopover } from '../primitives';
+import { icon, type IconName } from '../icons';
+
+/** The bar menu, as a light-dismiss popover anchored to the burger. Rows come from the core model,
+ *  so DOM and Pixi always show the same list in the same order. */
+export function openMenuPopover(
+  host: ShellHost,
+  surface: HTMLElement,
+  getScale: () => number,
+): { root: HTMLElement; position(): void } {
+  const pop = createPopover({
+    ge: 'menu-popover',
+    surface,
+    // Resolved lazily on every position() call, not captured once: HtmlRenderer's renderBar() (run
+    // on every resize, and on ~20 other state changes) rebuilds the bottom bar from scratch, so the
+    // plate/burger are brand-new elements after it — a captured reference would already be detached
+    // by the next position() call and the card would silently recentre with its arrow hidden.
+    // The plate is the bar's own plaque — the continuous dark panel wide, the controls row mobile
+    // (NOT the info pill below it) — so the card sits flush with the WHOLE bar, not just the burger.
+    plate: () => surface.querySelector(host.layout === 'mobile' ? '.ge-m-controls' : '.ge-bar-panel') as HTMLElement | null,
+    pointer: () => surface.querySelector('[data-ge="menu"]') as HTMLElement | null,
+    // Mobile only: the SPIN disc / FS counter is taller than `.ge-m-controls` and centred inside it
+    // (`align-items:center` over a shorter fixed-height row), so it pops above the row's own top edge
+    // — see createPopover's `plateOverflowTop` doc comment. Exactly one of the two (or neither, e.g. a
+    // replay with no free spins) is ever rendered, so a combined selector resolves to whichever is
+    // current. Wide's plate already contains its content, so this deliberately resolves to null there.
+    plateOverflowTop: () =>
+      host.layout === 'mobile'
+        ? (surface.querySelector('[data-ge="spin"], [data-ge="fs-counter"]') as HTMLElement | null)
+        : null,
+    scale: getScale,
+    onClose: () => host.actions.closeOverlay(),
+  });
+  const updaters: Record<string, (v: boolean | number) => void> = {};
+  for (const row of resolveMenu(host)) {
+    pop.body.appendChild(buildRow(host, row, updaters, () => pop.position()));
+  }
+  // Live updates while open (host.setMenuValue / setSound / setVolume); cleared by the controller.
+  host.setMenuRefresh((id, v) => updaters[id]?.(v));
+  return { root: pop.root, position: pop.position };
+}
+
+function glyph(name: IconName | undefined, cls: string): HTMLElement | null {
+  if (!name) return null;
+  const el = document.createElement('span');
+  el.className = cls;
+  el.innerHTML = icon(name);
+  return el;
+}
+
+function buildRow(
+  host: ShellHost,
+  row: MenuRow,
+  updaters: Record<string, (v: boolean | number) => void>,
+  reposition: () => void,
+): HTMLElement {
+  if (row.kind === 'separator') {
+    const sep = document.createElement('div');
+    sep.className = 'ge-pop-sep';
+    sep.dataset.ge = 'menu-sep';
+    return sep;
+  }
+  if (row.kind === 'button') {
+    // The row hook goes on a wrapper so both `menu-row-<id>` (order assertions) and
+    // `menu-item-<id>` (the clickable control) exist, as they do for toggle/range rows.
+    const wrap = document.createElement('div');
+    wrap.dataset.ge = `menu-row-${row.id}`;
+    const btn = document.createElement('button');
+    btn.className = 'ge-ov-row';
+    btn.dataset.ge = `menu-item-${row.id}`;
+    btn.disabled = row.disabled;
+    const label = document.createElement('span');
+    label.className = 'ge-grow';
+    label.textContent = row.label;
+    const ico = glyph(row.icon, 'ge-mi-icon');
+    const chev = row.chevron ? glyph('chevronRight', 'ge-mi-chev') : null;
+    for (const el of [ico, label, chev]) if (el) btn.appendChild(el);
+    btn.addEventListener('click', () => {
+      if (btn.disabled) return;
+      host.actions.closeOverlay();
+      row.select();
+    });
+    wrap.appendChild(btn);
+    return wrap;
+  }
+  if (row.kind === 'toggle') {
+    const el = document.createElement('div');
+    el.className = 'ge-ov-row';
+    el.classList.toggle('ge-disabled', row.disabled); // a <div> can't carry [disabled] itself
+    el.dataset.ge = `menu-row-${row.id}`;
+    const ico = glyph(row.icon(row.get()), 'ge-mi-icon');
+    const label = document.createElement('span');
+    label.className = 'ge-grow';
+    label.textContent = row.label;
+    const btn = document.createElement('button');
+    btn.className = 'ge-toggle';
+    btn.dataset.ge = `menu-item-${row.id}`;
+    btn.disabled = row.disabled;
+    btn.innerHTML = '<i></i>';
+    const paint = (v: boolean): void => {
+      btn.classList.toggle('ge-on', v);
+      btn.setAttribute('aria-pressed', String(v));
+      const next = row.icon(v);
+      if (ico && next) ico.innerHTML = icon(next);
+    };
+    paint(row.get());
+    btn.addEventListener('click', () => {
+      if (!btn.disabled) row.set(!row.get());
+    });
+    updaters[row.id] = (v) => paint(v === true);
+    if (ico) el.appendChild(ico);
+    el.append(label, btn);
+    return el;
+  }
+  // range
+  const el = document.createElement('div');
+  el.className = 'ge-ov-row ge-col';
+  el.classList.toggle('ge-disabled', row.disabled); // a <div> can't carry [disabled] itself
+  el.dataset.ge = `menu-row-${row.id}`;
+  const head = document.createElement('div');
+  head.className = 'ge-row-head';
+  const name = document.createElement('span');
+  name.textContent = row.label;
+  const val = document.createElement('span');
+  val.className = 'ge-val';
+  head.append(name, val);
+  const input = document.createElement('input');
+  input.type = 'range';
+  input.className = 'ge-slider';
+  input.dataset.ge = `menu-item-${row.id}`;
+  input.min = String(row.min);
+  input.max = String(row.max);
+  input.step = String(row.step);
+  input.disabled = row.disabled;
+  const paint = (v: number): void => {
+    input.value = String(v);
+    val.textContent = row.format(v);
+  };
+  paint(row.get());
+  input.addEventListener('input', () => {
+    const v = Number(input.value);
+    val.textContent = row.format(v);
+    row.set(v);
+  });
+  updaters[row.id] = (v) => {
+    paint(Number(v));
+    reposition();
+  };
+  el.append(head, input);
+  return el;
+}

package/src/ui/html/icons.ts

@@ -5,29 +5,30 @@
 // GraphicsContext.svg. To change an icon: edit icons.svg, then run
 // `node scripts/gen-icons-from-svg.mjs`.
 const SVGS: Record<string, string> = {
-  spin: `<g fill="currentColor" fill-rule="evenodd"><path d="M13.57 8.41C13.3 8.31 13.51 7.09 13.59 6.65C13.61 6.56 13.55 6.48 13.46 6.48C12.32 6.45 5.74 6.61 4.16 14.85C4.15 14.9 4 15.16 3.8 14.91C3.27 14.23 2.43 12.08 3.46 9.16C6.01 1.92 13 3.07 13.79 3.23C13.83 3.23 13.86 3.2 13.86 3.17C13.85 2.86 13.82 1.68 14.17 1.64C14.51 1.6 19.04 5.61 18.96 5.95C18.86 6.36 13.83 8.51 13.57 8.41Z"/><path d="M10.43 15.59C10.7 15.69 10.49 16.91 10.41 17.35C10.39 17.44 10.45 17.52 10.54 17.52C11.68 17.55 18.26 17.39 19.84 9.15C19.85 9.1 20 8.84 20.2 9.09C20.73 9.77 21.57 11.92 20.54 14.85C17.99 22.08 11 20.93 10.21 20.77C10.17 20.77 10.13 20.8 10.14 20.83C10.15 21.14 10.18 22.32 9.83 22.36C9.49 22.4 4.96 18.39 5.04 18.05C5.14 17.64 10.17 15.49 10.43 15.59Z"/></g>`,
-  turbo1: `<g fill="currentColor" fill-rule="evenodd"><path d="M17.81 2.62L14.41 8.21C14.15 8.64 14.46 9.2 14.97 9.2L18.84 9.21C19.42 9.21 19.72 9.9 19.32 10.31L8.02 22.19C7.89 22.33 7.72 22.4 7.53 22.4L7.53 22.4C7.08 22.39 6.77 21.93 6.93 21.5L9.91 13.91C10.08 13.48 9.76 13.01 9.29 13.01L5.11 13.06C4.61 13.06 4.28 12.53 4.53 12.09L10.07 1.94C10.19 1.73 10.41 1.6 10.65 1.6L17.26 1.62C17.77 1.62 18.08 2.18 17.81 2.62Z"/></g>`,
-  autoplay: `<g fill="currentColor" fill-rule="evenodd"><path d="M19.97 12.41C20.22 11.94 20.95 11.88 20.97 12.47C21.14 16.4 18.71 19.92 14.44 20.97C8.59 22.4 5.29 18.55 5.28 18.52C5.2 18.33 4.41 19.77 4.19 19.59C3.81 19.28 3.78 14.9 3.9 14.78C4.01 14.67 8.39 14.95 8.48 15.31C8.58 15.64 7.2 16.1 7.4 16.38C9.14 18.67 15.82 20.29 19.97 12.41Z"/><path d="M9.3 15.36L9.3 8.67C9.3 8.32 9.97 7.74 10.58 8.14C15.83 11.56 16 11.46 16.01 12.04C16.02 12.61 15.12 12.98 10.63 15.91C10.32 16.11 9.29 15.72 9.29 15.36Z"/><path d="M4.03 11.59C3.78 12.06 3.05 12.12 3.03 11.53C2.86 7.6 5.29 4.08 9.56 3.03C15.41 1.6 18.71 5.45 18.72 5.48C18.8 5.67 19.59 4.23 19.81 4.41C20.19 4.72 20.22 9.1 20.1 9.22C19.99 9.33 15.61 9.05 15.52 8.69C15.42 8.36 16.8 7.9 16.6 7.62C14.86 5.33 8.18 3.71 4.03 11.59Z"/></g>`,
+  spin: `<g fill="currentColor" fill-rule="evenodd"><path d="M13.57 8.41C13.3 8.31 13.51 7.09 13.59 6.65C13.61 6.56 13.55 6.48 13.46 6.48C12.32 6.45 5.74 6.61 4.16 14.85C4.15 14.9 4 15.16 3.8 14.91C3.27 14.23 2.43 12.08 3.46 9.16C6.01 1.92 13 3.07 13.79 3.23C13.83 3.23 13.86 3.2 13.86 3.17C13.85 2.86 13.82 1.68 14.17 1.64C14.51 1.6 19.04 5.61 18.96 5.95C18.86 6.36 13.83 8.51 13.57 8.41L13.57 8.41Z"/><path d="M10.43 15.59C10.7 15.69 10.49 16.91 10.41 17.35C10.39 17.44 10.45 17.52 10.54 17.52C11.68 17.55 18.26 17.39 19.84 9.15C19.85 9.1 20 8.84 20.2 9.09C20.73 9.77 21.57 11.92 20.54 14.85C17.99 22.08 11 20.93 10.21 20.77C10.17 20.77 10.13 20.8 10.14 20.83C10.15 21.14 10.18 22.32 9.83 22.36C9.49 22.4 4.96 18.39 5.04 18.05C5.14 17.64 10.17 15.49 10.43 15.59L10.43 15.59L10.43 15.59Z"/></g>`,
+  turbo1: `<g fill="currentColor" fill-rule="evenodd"><path d="M17.81 2.62L14.41 8.21C14.15 8.64 14.46 9.2 14.97 9.2L18.84 9.21C19.42 9.21 19.72 9.9 19.32 10.31L8.02 22.19C7.89 22.33 7.72 22.4 7.53 22.4L7.53 22.4C7.08 22.39 6.77 21.93 6.93 21.5L9.91 13.91C10.08 13.48 9.76 13.01 9.29 13.01L5.11 13.06C4.61 13.06 4.28 12.53 4.53 12.09L10.07 1.94C10.19 1.73 10.41 1.6 10.65 1.6L17.26 1.62C17.77 1.62 18.08 2.18 17.81 2.62L17.81 2.62Z"/></g>`,
+  autoplay: `<g fill="currentColor" fill-rule="evenodd"><path d="M19.97 12.41C20.22 11.94 20.95 11.88 20.97 12.47C21.14 16.4 18.71 19.92 14.44 20.97C8.59 22.4 5.29 18.55 5.28 18.52C5.2 18.33 4.41 19.77 4.19 19.59C3.81 19.28 3.78 14.9 3.9 14.78C4.01 14.67 8.39 14.95 8.48 15.31C8.58 15.64 7.2 16.1 7.4 16.38C9.14 18.67 15.82 20.29 19.97 12.41L19.97 12.41Z"/><path d="M9.3 15.36L9.3 8.67C9.3 8.32 9.97 7.74 10.58 8.14C15.83 11.56 16 11.46 16.01 12.04C16.02 12.61 15.12 12.98 10.63 15.91C10.32 16.11 9.29 15.72 9.29 15.36L9.3 15.36Z"/><path d="M4.03 11.59C3.78 12.06 3.05 12.12 3.03 11.53C2.86 7.6 5.29 4.08 9.56 3.03C15.41 1.6 18.71 5.45 18.72 5.48C18.8 5.67 19.59 4.23 19.81 4.41C20.19 4.72 20.22 9.1 20.1 9.22C19.99 9.33 15.61 9.05 15.52 8.69C15.42 8.36 16.8 7.9 16.6 7.62C14.86 5.33 8.18 3.71 4.03 11.59L4.03 11.59Z"/></g>`,
   stop: `<g fill="currentColor" fill-rule="evenodd"><rect x="1.6" y="1.6" width="20.8" height="20.8" rx="2.9"/></g>`,
   menu: `<g fill="currentColor" fill-rule="evenodd"><rect x="1.61" y="3.81" width="20.79" height="4.47" rx="2.23"/><rect x="1.6" y="9.77" width="20.79" height="4.46" rx="2.23"/><rect x="1.6" y="15.72" width="20.79" height="4.47" rx="2.23"/></g>`,
   minus: `<g fill="currentColor" fill-rule="evenodd"><rect x="1.6" y="9.86" width="20.8" height="4.28" rx="2.11"/></g>`,
-  plus: `<g fill="currentColor" fill-rule="evenodd"><path d="M19.72 14.37L13.84 14.37L13.84 20.33C13.84 21.48 12.89 22.4 11.74 22.36C10.61 22.36 9.7 21.45 9.7 20.33L9.7 14.37L3.67 14.37C2.52 14.37 1.6 13.42 1.63 12.27C1.63 11.15 2.55 10.23 3.67 10.23L9.7 10.23L9.7 4.28C9.71 1.61 13.83 1.6 13.84 4.28L13.84 10.23L19.72 10.23C22.39 10.24 22.4 14.36 19.72 14.37Z"/></g>`,
+  plus: `<g fill="currentColor" fill-rule="evenodd"><path d="M19.72 14.37L13.84 14.37L13.84 20.33C13.84 21.48 12.89 22.4 11.74 22.36C10.61 22.36 9.7 21.45 9.7 20.33L9.7 14.37L3.67 14.37C2.52 14.37 1.6 13.42 1.63 12.27C1.63 11.15 2.55 10.23 3.67 10.23L9.7 10.23L9.7 4.28C9.71 1.61 13.83 1.6 13.84 4.28L13.84 10.23L19.72 10.23C22.39 10.24 22.4 14.36 19.72 14.37L19.72 14.37Z"/></g>`,
   gift: `<rect x="4" y="9" width="16" height="11" rx="2" fill="currentColor"/><path d="M9 9c-1.35 -0.31 -2.18 -1.65 -1.87 -3s1.65 -2.18 3 -1.87c0.93 0.22 1.65 0.94 1.87 1.87c0.31 -1.35 1.65 -2.18 3 -1.87c1.35 0.31 2.18 1.65 1.87 3c-0.22 0.93 -0.94 1.65 -1.87 1.87h-6Z" fill="currentColor"/><rect x="11" y="9" width="2" height="11" fill="rgba(0,0,0,.35)"/>`,
-  info: `<g fill="currentColor" fill-rule="evenodd"><circle cx="11.98" cy="4.27" r="2.67"/><path d="M16.05 21.09L16.05 21.54C16.05 22.02 15.67 22.4 15.19 22.4L8.89 22.4C8.42 22.4 8.04 22.02 8.04 21.54L8.04 20.98C8.04 20.5 8.42 20.12 8.89 20.12L8.89 20.12C9.13 20.12 9.32 19.93 9.32 19.7L9.32 11.59C9.32 11.29 9.08 11.05 8.8 11.05C8.33 11.05 7.95 10.67 7.95 10.19L7.95 9.18C7.95 8.7 8.33 8.32 8.8 8.32L9.32 8.32C9.32 8.32 13.8 8.32 13.8 8.32C14.27 8.32 14.65 8.71 14.65 9.18L14.65 19.7C14.65 19.93 14.84 20.12 15.07 20.12L15.07 20.12C15.61 20.12 16.05 20.56 16.05 21.09Z"/></g>`,
-  soundOn: `<g fill="currentColor" fill-rule="evenodd"><path d="M1.6 15.04L1.6 9.18C1.6 8.75 1.95 8.4 2.38 8.4L5.03 8.4C5.21 8.4 5.39 8.36 5.56 8.28L11.6 5.26C12.12 5 12.73 5.38 12.73 5.96L12.73 18.27C12.73 18.85 12.12 19.22 11.6 18.96L5.56 15.94C5.39 15.86 5.22 15.82 5.03 15.82L2.38 15.82C1.95 15.82 1.6 15.47 1.6 15.04Z"/><path d="M16.01 12.11C16.04 12.36 15.67 14.7 14.7 15.23C13.92 15.42 13.54 14.77 13.86 14.1C14.89 12.56 14.88 11.66 13.86 10.13C13.54 9.46 13.92 8.8 14.7 8.99C15.67 9.53 16.06 11.81 16.01 12.11Z"/><path d="M19.15 12.12C19.2 12.51 18.6 16.4 17.3 17.05C16.32 17.54 15.99 16.87 16.42 15.81C17.8 13.4 17.59 9.93 16.42 8.41C15.73 7.5 16.34 6.58 17.26 7.18C18.74 8.15 19.21 11.64 19.15 12.12Z"/><path d="M22.4 12.16C22.16 15.18 21 17.95 19.71 18.82C18.73 19.48 18.22 18.42 18.93 17.32C20.96 14.17 21.92 9.95 18.9 6.29C18.13 5.35 19.35 4.52 20.11 5.48C21.43 7.14 22.33 9.14 22.4 12.16Z"/></g>`,
+  info: `<g fill="currentColor" fill-rule="evenodd"><circle cx="11.98" cy="4.27" r="2.67"/><path d="M16.05 21.09L16.05 21.54C16.05 22.02 15.67 22.4 15.19 22.4L8.89 22.4C8.42 22.4 8.04 22.02 8.04 21.54L8.04 20.98C8.04 20.5 8.42 20.12 8.89 20.12L8.89 20.12C9.13 20.12 9.32 19.93 9.32 19.7L9.32 11.59C9.32 11.29 9.08 11.05 8.8 11.05C8.33 11.05 7.95 10.67 7.95 10.19L7.95 9.18C7.95 8.7 8.33 8.32 8.8 8.32L13.8 8.32C14.27 8.32 14.65 8.71 14.65 9.18L14.65 19.7C14.65 19.93 14.84 20.12 15.07 20.12L15.07 20.12C15.61 20.12 16.05 20.56 16.05 21.09L16.05 21.09Z"/></g>`,
+  soundOn: `<g fill="currentColor" fill-rule="evenodd"><path d="M1.6 15.04L1.6 9.18C1.6 8.75 1.95 8.4 2.38 8.4L5.03 8.4C5.21 8.4 5.39 8.36 5.56 8.28L11.6 5.26C12.12 5 12.73 5.38 12.73 5.96L12.73 18.27C12.73 18.85 12.12 19.22 11.6 18.96L5.56 15.94C5.39 15.86 5.22 15.82 5.03 15.82L2.38 15.82C1.95 15.82 1.6 15.47 1.6 15.04L1.6 15.04Z"/><path d="M16.01 12.11C16.04 12.36 15.67 14.7 14.7 15.23C13.92 15.42 13.54 14.77 13.86 14.1C14.89 12.56 14.88 11.66 13.86 10.13C13.54 9.46 13.92 8.8 14.7 8.99C15.67 9.53 16.06 11.81 16.01 12.11Z"/><path d="M19.15 12.12C19.2 12.51 18.6 16.4 17.3 17.05C16.32 17.54 15.99 16.87 16.42 15.81C17.8 13.4 17.59 9.93 16.42 8.41C15.73 7.5 16.34 6.58 17.26 7.18C18.74 8.15 19.21 11.64 19.15 12.12L19.15 12.12Z"/><path d="M22.4 12.16C22.16 15.18 21 17.95 19.71 18.82C18.73 19.48 18.22 18.42 18.93 17.32C20.96 14.17 21.92 9.95 18.9 6.29C18.13 5.35 19.35 4.52 20.11 5.48C21.43 7.14 22.33 9.14 22.4 12.16L22.4 12.16Z"/></g>`,
   soundOff: `<g fill="currentColor" fill-rule="evenodd"><path d="M1.6 14.77L1.6 9.23C1.6 8.82 1.93 8.49 2.34 8.49L4.85 8.49C5.02 8.49 5.19 8.45 5.34 8.38L11.06 5.52C11.55 5.27 12.12 5.63 12.12 6.18L12.12 17.82C12.12 18.37 11.55 18.73 11.06 18.48L5.34 15.62C5.19 15.55 5.02 15.51 4.85 15.51L2.34 15.51C1.93 15.51 1.6 15.18 1.6 14.77Z"/><path d="M21.95 16.53C21.5 16.98 20.78 16.98 20.33 16.53L17.79 13.99L15.25 16.54C14.8 16.99 14.07 16.99 13.62 16.54C13.17 16.09 13.17 15.36 13.62 14.92L16.17 12.37L13.63 9.83C13.18 9.38 13.18 8.65 13.63 8.21C13.85 7.98 14.14 7.87 14.44 7.87C14.73 7.87 15.02 7.98 15.25 8.21L17.79 10.75L20.33 8.21C20.77 7.76 21.5 7.76 21.95 8.21C22.17 8.44 22.28 8.73 22.28 9.02C22.28 9.32 22.17 9.61 21.95 9.83L19.41 12.37L21.95 14.91C22.4 15.36 22.4 16.08 21.95 16.53Z"/></g>`,
-  close: `<g fill="currentColor" fill-rule="evenodd"><path d="M21.39 21.37C20.38 22.38 18.74 22.38 17.73 21.37L12.01 15.64L6.27 21.38C5.26 22.39 3.62 22.39 2.61 21.38C1.6 20.38 1.6 18.74 2.61 17.73L8.35 11.99L2.62 6.25C1.61 5.24 1.61 3.61 2.62 2.6C3.12 2.09 3.79 1.84 4.45 1.84C5.11 1.84 5.77 2.09 6.28 2.6L12.01 8.33L17.72 2.62C18.73 1.61 20.37 1.61 21.38 2.62C21.89 3.12 22.14 3.78 22.14 4.44C22.14 5.11 21.89 5.77 21.38 6.27L15.67 11.99L21.39 17.71C22.4 18.72 22.4 20.36 21.39 21.37Z"/></g>`,
-  back: `<g fill="currentColor" fill-rule="evenodd"><path d="M17.49 2.32L17.49 2.32C18.2 3.03 18.2 4.19 17.49 4.9L11.68 10.71C10.97 11.42 10.97 12.58 11.68 13.29L17.49 19.1C18.21 19.81 18.21 20.97 17.49 21.69L17.49 21.69C16.78 22.4 15.62 22.4 14.91 21.69L7.8 14.58L7.8 14.58C7.8 14.58 6.51 13.29 6.51 13.29C5.79 12.58 5.79 11.42 6.51 10.71L14.9 2.31C15.62 1.6 16.77 1.6 17.49 2.31Z"/></g>`,
-  chevronRight: `<g fill="currentColor" fill-rule="evenodd"><path d="M6.51 21.68L6.51 21.68C5.8 20.97 5.8 19.81 6.51 19.1L12.32 13.29C13.03 12.58 13.03 11.42 12.32 10.71L6.51 4.9C5.79 4.19 5.79 3.03 6.51 2.31L6.51 2.31C7.22 1.6 8.38 1.6 9.09 2.31L16.2 9.42L16.2 9.42C16.2 9.42 17.49 10.71 17.49 10.71C18.21 11.42 18.21 12.58 17.49 13.29L9.1 21.69C8.38 22.4 7.23 22.4 6.51 21.69Z"/></g>`,
+  close: `<g fill="currentColor" fill-rule="evenodd"><path d="M21.39 21.37C20.38 22.38 18.74 22.38 17.73 21.37L12.01 15.64L6.27 21.38C5.26 22.39 3.62 22.39 2.61 21.38C1.6 20.38 1.6 18.74 2.61 17.73L8.35 11.99L2.62 6.25C1.61 5.24 1.61 3.61 2.62 2.6C3.12 2.09 3.79 1.84 4.45 1.84C5.11 1.84 5.77 2.09 6.28 2.6L12.01 8.33L17.72 2.62C18.73 1.61 20.37 1.61 21.38 2.62C21.89 3.12 22.14 3.78 22.14 4.44C22.14 5.11 21.89 5.77 21.38 6.27L15.67 11.99L21.39 17.71C22.4 18.72 22.4 20.36 21.39 21.37L21.39 21.37Z"/></g>`,
+  back: `<g fill="currentColor" fill-rule="evenodd"><path d="M17.49 2.32L17.49 2.32C18.2 3.03 18.2 4.19 17.49 4.9L11.68 10.71C10.97 11.42 10.97 12.58 11.68 13.29L17.49 19.1C18.21 19.81 18.21 20.97 17.49 21.69L17.49 21.69C16.78 22.4 15.62 22.4 14.91 21.69L7.8 14.58L7.8 14.58L6.51 13.29C5.79 12.58 5.79 11.42 6.51 10.71L14.9 2.31C15.62 1.6 16.77 1.6 17.49 2.31L17.49 2.31Z"/></g>`,
+  chevronRight: `<g fill="currentColor" fill-rule="evenodd"><path d="M6.51 21.68L6.51 21.68C5.8 20.97 5.8 19.81 6.51 19.1L12.32 13.29C13.03 12.58 13.03 11.42 12.32 10.71L6.51 4.9C5.79 4.19 5.79 3.03 6.51 2.31L6.51 2.31C7.22 1.6 8.38 1.6 9.09 2.31L16.2 9.42L16.2 9.42L17.49 10.71C18.21 11.42 18.21 12.58 17.49 13.29L9.1 21.69C8.38 22.4 7.23 22.4 6.51 21.69L6.51 21.69Z"/></g>`,
   ticket: `<g transform="translate(12 12) scale(0.0354) translate(-518.2 -535.2)"><g transform="rotate(-15 512 512)"><path d="M250 392H774L774 462C739 474 720 504 720 536C720 568 739 598 774 610V680H250V610C285 598 304 568 304 536C304 504 285 474 250 462V392Z" fill="none" stroke="currentColor" stroke-width="52" stroke-linejoin="miter" stroke-linecap="square"/><path d="M562.9 408.3L441.5 553.9L506.9 546.3L472.9 664.1L604 504L528.9 514.3Z" fill="currentColor"/></g></g>`,
-  turbo2: `<g fill="currentColor" fill-rule="evenodd"><path d="M8.24 8.81L3.92 7.68C3.88 7.67 3.88 7.61 3.92 7.61L9.66 6.45C9.8 6.43 9.89 6.56 9.83 6.68L8.86 8.35C8.67 8.73 8.33 8.83 8.24 8.81Z"/><path d="M20.58 3.04L17.34 8.38C17.09 8.8 17.39 9.33 17.87 9.33L21.57 9.33C22.12 9.33 22.4 9.99 22.02 10.39L11.24 21.73C11.12 21.86 10.95 21.93 10.77 21.92L10.77 21.92C10.34 21.92 10.04 21.47 10.2 21.07L13.04 13.82C13.21 13.41 12.9 12.96 12.45 12.97L8.46 13.01C7.98 13.01 7.67 12.5 7.9 12.08L13.2 2.4C13.31 2.2 13.52 2.07 13.75 2.07L20.05 2.09C20.54 2.1 20.84 2.63 20.58 3.04Z"/><path d="M5.96 12.68L1.64 11.54C1.6 11.54 1.6 11.47 1.64 11.47L7.38 10.31C7.52 10.3 7.61 10.42 7.55 10.55L6.58 12.22C6.39 12.59 6.05 12.69 5.96 12.68Z"/><path d="M9.67 16.66L5.35 15.53C5.31 15.52 5.31 15.46 5.35 15.46L11.09 14.3C11.22 14.28 11.32 14.41 11.26 14.53L10.29 16.2C10.1 16.58 9.76 16.68 9.67 16.66Z"/></g>`,
-  turboOff: `<g fill="currentColor" fill-rule="evenodd"><path d="M17.81 2.62L14.41 8.21C14.15 8.64 14.46 9.2 14.97 9.2L18.84 9.21C19.42 9.21 19.72 9.9 19.32 10.31L8.02 22.19C7.89 22.33 7.72 22.4 7.53 22.4L7.53 22.4C7.08 22.39 6.77 21.93 6.93 21.5L9.91 13.91C10.08 13.48 9.76 13.01 9.29 13.01L5.11 13.06C4.61 13.06 4.28 12.53 4.53 12.09L10.07 1.94C10.19 1.73 10.41 1.6 10.65 1.6L17.26 1.62C17.77 1.62 18.08 2.18 17.81 2.62Z"/></g>`,
-  chevronUp: `<g fill="currentColor" fill-rule="evenodd"><path d="M21.68 17.49L21.68 17.49C20.97 18.2 19.81 18.2 19.1 17.49L13.29 11.68C12.58 10.97 11.42 10.97 10.71 11.68L4.9 17.49C4.19 18.21 3.03 18.21 2.31 17.49L2.31 17.49C1.6 16.78 1.6 15.62 2.31 14.91L9.42 7.8L9.42 7.8C9.42 7.8 10.71 6.51 10.71 6.51C11.42 5.79 12.58 5.79 13.29 6.51L21.69 14.9C22.4 15.62 22.4 16.77 21.69 17.49Z"/></g>`,
-  chevronDown: `<g fill="currentColor" fill-rule="evenodd"><path d="M2.32 6.51L2.32 6.51C3.03 5.8 4.19 5.8 4.9 6.51L10.71 12.32C11.42 13.03 12.58 13.03 13.29 12.32L19.1 6.51C19.82 5.79 20.97 5.79 21.69 6.51L21.69 6.51C22.4 7.22 22.4 8.38 21.69 9.09L14.58 16.19L14.58 16.2C14.58 16.2 13.29 17.49 13.29 17.49C12.58 18.21 11.42 18.21 10.71 17.49L2.31 9.1C1.6 8.38 1.6 7.23 2.31 6.51Z"/></g>`,
+  turbo2: `<g fill="currentColor" fill-rule="evenodd"><path d="M8.24 8.81L3.92 7.68C3.88 7.67 3.88 7.61 3.92 7.61L9.66 6.45C9.8 6.43 9.89 6.56 9.83 6.68L8.86 8.35C8.67 8.73 8.33 8.83 8.24 8.81L8.24 8.81Z"/><path d="M20.58 3.04L17.34 8.38C17.09 8.8 17.39 9.33 17.87 9.33L21.57 9.33C22.12 9.33 22.4 9.99 22.02 10.39L11.24 21.73C11.12 21.86 10.95 21.93 10.77 21.92L10.77 21.92C10.34 21.92 10.04 21.47 10.2 21.07L13.04 13.82C13.21 13.41 12.9 12.96 12.45 12.97L8.46 13.01C7.98 13.01 7.67 12.5 7.9 12.08L13.2 2.4C13.31 2.2 13.52 2.07 13.75 2.07L20.05 2.09C20.54 2.1 20.84 2.63 20.58 3.04L20.58 3.04Z"/><path d="M5.96 12.68L1.64 11.54C1.6 11.54 1.6 11.47 1.64 11.47L7.38 10.31C7.51 10.3 7.61 10.42 7.55 10.55L6.58 12.22C6.39 12.59 6.05 12.69 5.96 12.68L5.96 12.68Z"/><path d="M9.67 16.66L5.35 15.53C5.31 15.52 5.31 15.46 5.35 15.46L11.09 14.3C11.22 14.28 11.32 14.41 11.26 14.53L10.29 16.2C10.1 16.58 9.76 16.68 9.67 16.66L9.67 16.66Z"/></g>`,
+  turboOff: `<g fill="currentColor" fill-rule="evenodd"><path d="M17.81 2.62L14.41 8.21C14.15 8.64 14.46 9.2 14.97 9.2L18.84 9.21C19.42 9.21 19.72 9.9 19.32 10.31L8.02 22.19C7.89 22.33 7.72 22.4 7.53 22.4L7.53 22.4C7.08 22.39 6.77 21.93 6.93 21.5L9.91 13.91C10.08 13.48 9.76 13.01 9.29 13.01L5.11 13.06C4.61 13.06 4.28 12.53 4.53 12.09L10.07 1.94C10.19 1.73 10.41 1.6 10.65 1.6L17.26 1.62C17.77 1.62 18.08 2.18 17.81 2.62L17.81 2.62Z"/></g>`,
+  chevronUp: `<g fill="currentColor" fill-rule="evenodd"><path d="M21.68 17.49L21.68 17.49C20.97 18.2 19.81 18.2 19.1 17.49L13.29 11.68C12.58 10.97 11.42 10.97 10.71 11.68L4.9 17.49C4.19 18.21 3.03 18.21 2.31 17.49L2.31 17.49C1.6 16.78 1.6 15.62 2.31 14.91L9.42 7.8L9.42 7.8L10.71 6.51C11.42 5.79 12.58 5.79 13.29 6.51L21.69 14.9C22.4 15.62 22.4 16.77 21.69 17.49L21.69 17.49Z"/></g>`,
+  chevronDown: `<g fill="currentColor" fill-rule="evenodd"><path d="M2.32 6.51L2.32 6.51C3.03 5.8 4.19 5.8 4.9 6.51L10.71 12.32C11.42 13.03 12.58 13.03 13.29 12.32L19.1 6.51C19.82 5.79 20.97 5.79 21.69 6.51L21.69 6.51C22.4 7.22 22.4 8.38 21.69 9.09L14.58 16.19L14.58 16.2L13.29 17.49C12.58 18.21 11.42 18.21 10.71 17.49L2.31 9.1C1.6 8.38 1.6 7.23 2.31 6.51L2.32 6.51L2.32 6.51Z"/></g>`,
 };
 
-export type IconName = keyof typeof SVGS;
-export const ICON_NAMES = Object.keys(SVGS) as IconName[];
+export type { IconName } from '@/core/icon-names';
+import type { IconName } from '@/core/icon-names';
+export { ICON_NAMES } from '@/core/icon-names';
 
 /** Inline SVG string for an icon, sized to 1em (scale via font-size/width). */
 export function icon(name: IconName): string {

package/src/ui/html/primitives.ts

@@ -1,4 +1,5 @@
 import { icon } from './icons';
+import { placePopover, popoverWidth, POPOVER, type Rect } from '@/core/popover';
 
 /** 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. */
@@ -83,3 +84,144 @@ export function createOverlay(opts: OverlayOpts): { root: HTMLDivElement; body:
   root.append(head, scroll);
   return { root, body, scroll };
 }
+
+export interface PopoverOpts {
+  ge: string;
+  /** The shell root — the popover is placed in its coordinate space and clamped to it. */
+  surface: HTMLElement;
+  /** The plate: the bar's own plaque (`.ge-bar-panel` wide / `.ge-m-controls` mobile). Drives the
+   *  card's x, y, maxH and above/below flip, so the card sits flush with the WHOLE bar rather than
+   *  with whichever control opened it. Falls back to `pointer` when it can't be resolved (no plaque
+   *  found), and to a centred, arrow-less card when neither resolves. A function is re-resolved on
+   *  EVERY `position()` call rather than captured once — a renderer that rebuilds its DOM on
+   *  resize/re-render (e.g. HtmlRenderer's `renderBar()`) replaces the element, so a captured
+   *  reference would go stale and silently fall back to a centred card. Pass a resolver whenever the
+   *  element can be rebuilt out from under the popover. */
+  plate: HTMLElement | null | (() => HTMLElement | null);
+  /** The control the arrow points at (the burger button). Defaults to `plate` when omitted — the
+   *  historical single-rect behaviour, kept so every caller that only ever had one rect (i.e. every
+   *  caller before `plate`/`pointer` were split) keeps behaving exactly as it did before. Same
+   *  re-resolve-per-call rule as `plate`. */
+  pointer?: HTMLElement | null | (() => HTMLElement | null);
+  /** An element that visually pops out ABOVE the plate's own box — e.g. the mobile SPIN/FS hero,
+   *  taller than the `.ge-m-controls` row and vertically centred, so it overflows the row's own top
+   *  edge. When present (and its measured top is above the plate's), the plate rect's TOP edge is
+   *  extended upward to match it — bottom edge untouched — so `placePopover` sees the row's true
+   *  visual extent on the side that matters, instead of a card whose bottom (only `gap` above the
+   *  plate's own top) can clip the popped-out control's arc. Omit/return null when nothing pops out
+   *  (e.g. the wide layout, whose plate already contains its content) — a no-op. Same
+   *  re-resolve-per-call rule as `plate`/`pointer`. */
+  plateOverflowTop?: HTMLElement | null | (() => HTMLElement | null);
+  /** The scale factor the bar currently applies to itself (HtmlRenderer.applyFitScale's `s`). The
+   *  card matches it so its typography/padding/row-heights scale in lockstep with the bar chrome.
+   *  Defaults to 1 (no scaling) when omitted. */
+  scale?: () => number;
+  onClose: () => void;
+}
+
+/** 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
+ *  card is in the DOM and again on resize. */
+export function createPopover(opts: PopoverOpts): {
+  root: HTMLDivElement;
+  card: HTMLDivElement;
+  body: HTMLDivElement;
+  position(): void;
+} {
+  const root = document.createElement('div');
+  root.className = 'ge-pop-layer';
+  root.dataset.ge = opts.ge;
+  const card = document.createElement('div');
+  card.className = 'ge-pop';
+  card.dataset.ge = 'menu-card';
+  const body = document.createElement('div');
+  body.className = 'ge-pop-body';
+  const arrow = document.createElement('span');
+  arrow.className = 'ge-pop-arrow';
+  card.append(body, arrow);
+  root.appendChild(card);
+  // Clicks inside the card must not reach the dismiss layer.
+  card.addEventListener('pointerdown', (e) => e.stopPropagation());
+  root.addEventListener('pointerdown', opts.onClose);
+
+  const resolveEl = (v: HTMLElement | null | (() => HTMLElement | null) | undefined): HTMLElement | null =>
+    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). */
+  const rectOf = (el: HTMLElement | null, surfaceRect: DOMRect): Rect | null => {
+    if (!el) return null;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 && r.height <= 0) return null;
+    return { x: r.left - surfaceRect.left, y: r.top - surfaceRect.top, w: r.width, h: r.height };
+  };
+
+  const position = (): void => {
+    const surfaceRect = opts.surface.getBoundingClientRect();
+    const surface = { w: surfaceRect.width || opts.surface.clientWidth, h: surfaceRect.height || opts.surface.clientHeight };
+    if (surface.w <= 0 || surface.h <= 0) return;
+    const s = opts.scale?.() ?? 1;
+
+    // 1. Clear a prior run's constraints (transform + width + max-height + left) before measuring —
+    // otherwise scrollWidth/offsetHeight report the already-scaled/clamped box (not the natural
+    // content size) on every call after the first, and the card can shrink to fit a
+    // narrower/shorter surface but never grow back when the surface widens/grows again. An uncleared
+    // max-height is the worse of the two: placePopover positions a card sized for the STALE clamped
+    // height, then the un-clamped natural height (restored below) springs back afterward — so the
+    // rendered card can overlap the plate or run off the surface edge until reopened. The transform
+    // doesn't affect layout either way, but clearing it keeps every pass measuring the same way.
+    // `left` matters too: `.ge-pop` is absolutely positioned inside an `inset:0` layer, so with the
+    // previous pass's `left` still applied, its shrink-to-fit width is bounded by (layerWidth − left)
+    // instead of the card's true natural width. Invisible at scale 1; a scale below 1 lays the card
+    // out at up to 1/s its on-screen width, so a stale left — only ever a few hundred px — can clip it.
+    card.style.transform = '';
+    card.style.width = '';
+    card.style.maxHeight = '';
+    card.style.left = '0px';
+    const naturalW = card.scrollWidth || POPOVER.minW;
+
+    // 2. Resolve the ON-SCREEN width from the natural (unscaled) width scaled up to screen units,
+    // then set the LOCAL style.width so the card renders at that resolved width once scaled — and
+    // re-measure the height at that width (wrapping may have changed it).
+    const resolvedW = popoverWidth(surface.w, naturalW * s);
+    card.style.width = `${resolvedW / s}px`;
+    const naturalH = card.offsetHeight || POPOVER.minH;
+
+    // 3. Resolve plate/pointer in surface coordinates and place using SCREEN-space size —
+    // placePopover works in surface pixels throughout, so both the anchor rects and `size` here are
+    // screen units even though the card's own layout (width/height above) is still LOCAL/unscaled.
+    const plateEl = resolveEl(opts.plate);
+    const pointerEl = resolveEl(opts.pointer);
+    let plate = rectOf(plateEl, surfaceRect) ?? rectOf(pointerEl, surfaceRect);
+    // Extend the plate's TOP edge upward to a popped-out hero's true top (e.g. the mobile SPIN/FS
+    // control, taller than its row) — bottom edge untouched. Both rects are already in the SAME
+    // surface-coordinate space (post any bar-scale transform), so this is a plain coordinate compare,
+    // no separate unit conversion needed.
+    const overflowEl = resolveEl(opts.plateOverflowTop);
+    if (plate) {
+      const overflowRect = rectOf(overflowEl, surfaceRect);
+      if (overflowRect && overflowRect.y < plate.y) {
+        plate = { ...plate, h: plate.h + (plate.y - overflowRect.y), y: overflowRect.y };
+      }
+    }
+    const pointer = rectOf(pointerEl, surfaceRect);
+    const p = placePopover(plate, surface, { w: resolvedW, h: naturalH * s }, pointer);
+
+    // 4. Apply. maxHeight and the arrow's offset are LOCAL (unscaled) too, since both live inside the
+    // scaled card; transform-origin:top left keeps left/top (screen units) as the card's visual
+    // top-left regardless of `s`, and — since a transform doesn't affect layout — the next
+    // measurement pass stays clean without needing any extra bookkeeping.
+    card.style.left = `${p.x}px`;
+    card.style.top = `${p.y}px`;
+    card.style.maxHeight = `${p.maxH / s}px`;
+    card.style.transformOrigin = 'top left';
+    card.style.transform = Math.abs(s - 1) > 0.001 ? `scale(${s})` : '';
+    card.classList.toggle('ge-pop-below', p.below);
+    if (p.arrowX < 0) arrow.style.display = 'none';
+    else {
+      arrow.style.display = '';
+      arrow.style.left = `${p.arrowX / s}px`;
+    }
+  };
+  return { root, card, body, position };
+}

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

@@ -172,7 +172,10 @@ export const SHELL_CSS = SHELL_FONT_CSS + SHELL_DIGIT_FONT_CSS + `
   border-radius:16px; background:var(--shell-plaque-glass); color:#fff; font-size:14px; font-weight:600; }
 #${SHELL_ROOT_ID} .ge-ov-row .ge-grow { flex:1; text-align:left; }
 #${SHELL_ROOT_ID} button.ge-ov-row { cursor:pointer; font-family:inherit; transition:background .12s ease, color .12s ease; }
-#${SHELL_ROOT_ID} button.ge-ov-row:hover { background:var(--shell-plaque-glass-hover); color:var(--shell-accent); }
+#${SHELL_ROOT_ID} button.ge-ov-row:hover:not([disabled]) { background:var(--shell-plaque-glass-hover); color:var(--shell-accent); }
+/* disabled rows — mirrors Pixi's box.alpha = 0.5 for all three row kinds. A <button> row carries
+   the native attribute directly; a toggle/range row is a <div> wrapper, so it gets .ge-disabled. */
+#${SHELL_ROOT_ID} .ge-ov-row[disabled], #${SHELL_ROOT_ID} .ge-ov-row.ge-disabled { opacity:.5; cursor:default; }
 #${SHELL_ROOT_ID} .ge-ov-row.ge-col { flex-direction:column; align-items:stretch; gap:10px; }
 #${SHELL_ROOT_ID} .ge-ov-row .ge-row-head { display:flex; justify-content:space-between; align-items:center; }
 #${SHELL_ROOT_ID} .ge-ov-row .ge-row-head .ge-val { color:var(--shell-plaque-label); font-variant-numeric:tabular-nums; font-weight:700; }
@@ -183,6 +186,7 @@ export const SHELL_CSS = SHELL_FONT_CSS + SHELL_DIGIT_FONT_CSS + `
 #${SHELL_ROOT_ID} .ge-toggle i { position:absolute; top:2px; left:2px; width:20px; height:20px; border-radius:50%;
   background:#fff; transition:left .12s ease; }
 #${SHELL_ROOT_ID} .ge-toggle.ge-on i { left:20px; }
+#${SHELL_ROOT_ID} .ge-toggle:disabled { cursor:default; }
 /* sound on/off — speaker icon button (replaces the toggle) */
 #${SHELL_ROOT_ID} .ge-snd { pointer-events:auto; cursor:pointer; border:none; background:none; padding:0;
   width:36px; height:36px; display:flex; align-items:center; justify-content:center; font-size:24px;
@@ -191,6 +195,22 @@ export const SHELL_CSS = SHELL_FONT_CSS + SHELL_DIGIT_FONT_CSS + `
 #${SHELL_ROOT_ID} .ge-snd:hover { color:var(--shell-accent); }
 #${SHELL_ROOT_ID} .ge-snd:active { transform:scale(.92); }
 
+/* bar menu popover — light dismiss (no dim, no blur), card anchored to the burger */
+#${SHELL_ROOT_ID} .ge-pop-layer { position:absolute; inset:0; z-index:55; pointer-events:auto; }
+#${SHELL_ROOT_ID} .ge-pop { position:absolute; box-sizing:border-box; display:flex; flex-direction:column;
+  padding:8px; border-radius:18px; background:var(--shell-plaque-dark);
+  box-shadow:0 14px 38px rgba(0,0,0,.5); backdrop-filter:blur(12px) saturate(120%);
+  -webkit-backdrop-filter:blur(12px) saturate(120%); animation:ge-ov-in .12s ease-out; }
+#${SHELL_ROOT_ID} .ge-pop-body { overflow-y:auto; overflow-x:hidden; min-height:0; }
+#${SHELL_ROOT_ID} .ge-pop .ge-ov-row { padding:10px 12px; margin-bottom:6px; font-size:13px; }
+#${SHELL_ROOT_ID} .ge-pop .ge-ov-row:last-child { margin-bottom:0; }
+#${SHELL_ROOT_ID} .ge-pop-sep { height:1px; margin:6px 4px; background:var(--shell-plaque-line); opacity:.5; }
+#${SHELL_ROOT_ID} .ge-pop-arrow { position:absolute; bottom:-7px; width:14px; height:14px; margin-left:-7px;
+  background:var(--shell-plaque-dark); transform:rotate(45deg); border-radius:3px; }
+#${SHELL_ROOT_ID} .ge-pop.ge-pop-below .ge-pop-arrow { bottom:auto; top:-7px; }
+#${SHELL_ROOT_ID} .ge-pop .ge-mi-icon { flex:0 0 auto; width:20px; font-size:20px; display:flex; }
+#${SHELL_ROOT_ID} .ge-pop .ge-mi-chev { flex:0 0 auto; width:16px; font-size:16px; color:var(--shell-muted); display:flex; }
+
 /* game info — each section is its own glass plaque; body text sized for comfortable reading */
 #${SHELL_ROOT_ID} .ge-gi-sec { margin-bottom:12px; background:var(--shell-plaque-glass);
   border-radius:16px; padding:16px 18px; }