@energy8platform/shell 0.6.5 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/shell",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Energy8 branded game shell — one logic core, pluggable html/pixi renderers behind a stable contract.",
   "type": "module",
   "main": "./dist/index.cjs.js",

package/src/core/ShellController.ts

@@ -4,6 +4,7 @@ import { resolveTheme, type ShellTokens } from './theme';
 import { formatCurrency } from './format';
 import { createI18n, type I18n } from './i18n';
 import { KeyboardController, type KeyboardHost } from './keyboard';
+import { DEFAULT_MENU, rangeBounds, seedMenuValues, type MenuItem, type MenuRangeItem } from './menu';
 import { PACKAGE_VERSION } from './version';
 import type {
   ShellConfig,
@@ -49,6 +50,7 @@ export function resolveConfig(config: ShellConfig): ResolvedShellConfig {
     theme: config.theme,
     onBonusBuy: config.onBonusBuy,
     volumes: config.volumes,
+    menu: config.menu,
     version: config.version ?? '1.0.0',
     isSocial: config.isSocial ?? false,
     replay: config.replay ?? config.mode === 'replay',
@@ -71,8 +73,9 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   private i18n: I18n;
   private kbd?: KeyboardController;
   private overlay: OverlayHandle | null = null;
-  private soundRefresh: ((on: boolean) => void) | null = null;
-  private volumeRefresh: ((key: VolumeKey, value: number) => void) | null = null;
+  private menuItems: MenuItem[];
+  private menuRefresh: ((id: string, value: boolean | number) => void) | null = null;
+  private overlayKind: OverlayRequest['kind'] | null = null;
   private prevBalance: number;
   private prevWin: number;
   private destroyed = false;
@@ -84,6 +87,7 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     this.config = resolveConfig(config);
     this.i18n = createI18n({ language: this.config.language, isSocial: this.config.isSocial });
     this.state = createInitialState(this.config);
+    this.menuItems = this.config.menu ?? DEFAULT_MENU;
     this.tokens = resolveTheme(this.config.theme);
     this.prevBalance = this.state.balance;
     this.prevWin = this.state.win;
@@ -219,14 +223,21 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   private show(req: OverlayRequest): void {
     this.closeModal();
     this.overlay = this.renderer.openOverlay(req) ?? null;
+    this.overlayKind = this.overlay ? req.kind : null;
   }
+  /** Open the bar menu. Called again while it is open, it closes it — the burger toggles. */
   openMenu(): void {
+    if (this.overlayKind === 'menu') {
+      this.closeModal();
+      return;
+    }
     this.emit('menuOpen');
-    this.openSettings();
+    this.show({ kind: 'menu' });
   }
+  /** @deprecated The Settings overlay is gone — this opens the bar menu. */
   openSettings(): void {
     this.emit('settingsOpen');
-    this.show({ kind: 'settings' });
+    this.openMenu();
   }
   openInfo(): void {
     this.emit('infoOpen');
@@ -256,8 +267,8 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   closeModal(): void {
     if (!this.overlay) return;
     this.overlay = null;
-    this.soundRefresh = null;
-    this.volumeRefresh = null;
+    this.overlayKind = null;
+    this.menuRefresh = null;
     this.renderer.closeOverlay();
   }
 
@@ -265,11 +276,7 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   setSound(on: boolean): void {
     this.soundOn = on;
     this.emit('settingChange', { key: 'sound', value: on });
-    this.soundRefresh?.(on);
-    this.renderer.refreshSoundIcon?.(on);
-  }
-  setSoundRefresh(fn: ((on: boolean) => void) | null): void {
-    this.soundRefresh = fn;
+    this.menuRefresh?.('sound', on);
   }
 
   // ── volume ─────────────────────────────────────────────────────────────────
@@ -277,16 +284,56 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     return this.state.volumes[key];
   }
   /** Set a volume slider (0..1). Shared by the slider control (drag) and game code (public API):
-   *  clamps, stores so a reopened Settings overlay reflects it, emits `settingChange`, and
-   *  live-updates the slider if the overlay is currently open. */
+   *  clamps, stores so a reopened menu popover reflects it, emits `settingChange`, and
+   *  live-updates the slider if the menu is currently open. */
   setVolume(key: VolumeKey, value: number): void {
     const v = Math.max(0, Math.min(1, value));
     this.state.volumes[key] = v;
     this.emit('settingChange', { key, value: v });
-    this.volumeRefresh?.(key, v);
+    this.menuRefresh?.(key, v);
   }
-  setVolumeRefresh(fn: ((key: VolumeKey, value: number) => void) | null): void {
-    this.volumeRefresh = fn;
+
+  // ── menu ───────────────────────────────────────────────────────────────────
+  get menu(): MenuItem[] {
+    return this.menuItems;
+  }
+  /** Replace the item list. Values of ids already in state are kept; new ids are seeded. */
+  setMenu(items: MenuItem[]): void {
+    this.menuItems = items;
+    this.state.menu = seedMenuValues(items, this.state.menu);
+    if (this.overlayKind === 'menu') this.show({ kind: 'menu' });
+  }
+  getMenuValue(id: string): boolean | number | undefined {
+    if (id === 'sound') return this.soundOn;
+    if (id === 'music' || id === 'sfx') return this.state.volumes[id];
+    return this.state.menu[id];
+  }
+  /** Set a menu value. Presets route to their own homes so there is never a second copy. */
+  setMenuValue(id: string, value: boolean | number): void {
+    if (id === 'sound') {
+      this.setSound(value !== false);
+      return;
+    }
+    if (id === 'music' || id === 'sfx') {
+      this.setVolume(id, Number(value));
+      return;
+    }
+    const next = typeof value === 'number' ? this.clampRange(id, value) : value;
+    this.state.menu[id] = next;
+    this.emit('settingChange', { key: id, value: next });
+    this.menuRefresh?.(id, next);
+  }
+  setMenuRefresh(fn: ((id: string, value: boolean | number) => void) | null): void {
+    this.menuRefresh = fn;
+  }
+  /** Clamp to the declared bounds of a custom `range` item (a non-range id passes through). */
+  private clampRange(id: string, value: number): number {
+    const item = this.menuItems.find((i) => (i as { id?: string }).id === id) as
+      | MenuRangeItem
+      | undefined;
+    if (!item || (item as { type?: string }).type !== 'range') return value;
+    const { min, max } = rangeBounds(item);
+    return Math.max(min, Math.min(max, value));
   }
 
   // ── features ─────────────────────────────────────────────────────────────────
@@ -304,9 +351,9 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   }
 
   // ── game-facing public API (mirrors GameShell/PixiGameShell) ───────────────────
-  private money(field: 'balance' | 'win', from: number, to: number): void {
+  private money(field: 'balance' | 'win', from: number, to: number, durationMs?: number): void {
     this.renderer.renderBar();
-    if (to !== from) this.renderer.animateMoney(field, from, to);
+    if (to !== from) this.renderer.animateMoney(field, from, to, durationMs);
   }
   setBalance(n: number): void {
     const from = this.prevBalance;
@@ -316,8 +363,10 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   }
   /** Set the WIN readout. Counts up/down from the previous value by default. Pass
    *  `{ animate: false }` to SNAP instantly (renderBar cancels any in-flight count-up) — used by the
-   *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong. */
-  setWin(n: number, opts?: { animate?: boolean }): void {
+   *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong.
+   *  `{ durationMs }` shortens/lengthens the count-up (default 450ms) — a scene reporting a win per
+   *  cascade step passes its step length so each count-up finishes before the next step lands. */
+  setWin(n: number, opts?: { animate?: boolean; durationMs?: number }): void {
     const from = this.prevWin;
     this.state.win = n;
     this.prevWin = n;
@@ -325,7 +374,7 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
       this.renderer.renderBar(); // instant repaint from state; cancels running money anims
       return;
     }
-    this.money('win', from, n);
+    this.money('win', from, n, opts?.durationMs);
   }
   setBet(n: number): void {
     this.state.bet = n;
@@ -392,6 +441,11 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   destroy(): Promise<void> {
     if (this.destroyed) return Promise.resolve();
     this.destroyed = true;
+    // With the menu (or any overlay) open at teardown, `menuRefresh` / `overlay` / `overlayKind`
+    // would otherwise survive the renderer's destroy — so a later setVolume()/setSound() call
+    // invokes a stale row updater against already-destroyed Pixi Graphics (or a detached DOM node)
+    // and throws. Run BEFORE the renderer teardown below, while it can still close cleanly.
+    this.closeModal();
     if (typeof document !== 'undefined') {
       this.kbd?.detach();
       document.removeEventListener('pointerdown', this.pullFocus, true);

package/src/core/icon-names.ts

@@ -0,0 +1,30 @@
+// AUTO-GENERATED from ../../icons.svg by scripts/gen-icons-from-svg.mjs — do not edit by hand.
+// Sharp monochrome icon set: each glyph is a 24×24 viewBox fragment using currentColor
+// (hollow shapes use fill-rule="evenodd"). Coordinates are baked into the 24×24 space (no
+// <g transform>), so the same fragment renders identically in the DOM <svg> and in Pixi's
+// GraphicsContext.svg. To change an icon: edit icons.svg, then run
+// `node scripts/gen-icons-from-svg.mjs`.
+// The single glyph-name union, shared by core (menu items) and both renderers.
+export const ICON_NAMES = [
+  'spin',
+  'turbo1',
+  'autoplay',
+  'stop',
+  'menu',
+  'minus',
+  'plus',
+  'gift',
+  'info',
+  'soundOn',
+  'soundOff',
+  'close',
+  'back',
+  'chevronRight',
+  'ticket',
+  'turbo2',
+  'turboOff',
+  'chevronUp',
+  'chevronDown',
+] as const;
+
+export type IconName = (typeof ICON_NAMES)[number];

package/src/core/index.ts

@@ -28,6 +28,10 @@ export { ShellController, resolveConfig } from './ShellController';
 export type { CreateShellOptions } from './ShellController';
 export * from './renderer';
 export * from './types';
+export { DEFAULT_MENU, resolveMenu, seedMenuValues, rangeBounds, isPresetId } from './menu';
+export type { MenuItem, MenuRow, MenuHost, MenuPresetId } from './menu';
+export { placePopover, popoverWidth, POPOVER } from './popover';
+export type { PopoverPlacement, Rect as PopoverRect } from './popover';
 export { resolveTheme, SCHEMES, DEFAULT_ACCENT } from './theme';
 export type { ShellTokens } from './theme';
 export { createI18n, socialize, normalizeLang } from './i18n';

package/src/core/menu.ts

@@ -0,0 +1,301 @@
+import { ICON_NAMES, type IconName } from './icon-names';
+
+/** Built-in presets: the id alone is enough — the shell knows the label, icon and behaviour. */
+export type MenuPresetId = 'sound' | 'music' | 'sfx' | 'gameInfo';
+const PRESET_IDS: readonly string[] = ['sound', 'music', 'sfx', 'gameInfo'];
+
+export function isPresetId(id: string): id is MenuPresetId {
+  return PRESET_IDS.includes(id);
+}
+
+interface MenuItemBase {
+  id: string;
+  /** Overrides the preset/default label. Run through the shell translator. */
+  label?: string;
+  icon?: IconName;
+  disabled?: boolean;
+}
+
+export type MenuPresetItem = { id: MenuPresetId } & Omit<MenuItemBase, 'id'>;
+export type MenuToggleItem = { type: 'toggle'; value?: boolean; onChange?(v: boolean): void } & MenuItemBase;
+export type MenuRangeItem = {
+  type: 'range';
+  min?: number;
+  max?: number;
+  step?: number;
+  value?: number;
+  /** Right-hand readout. Defaults to percent for a 0..1 range, else the raw number. */
+  format?(v: number): string;
+  onChange?(v: number): void;
+} & MenuItemBase;
+export type MenuButtonItem = { type: 'button'; chevron?: boolean; onSelect?(): void } & MenuItemBase;
+export type MenuSeparatorItem = { type: 'separator' };
+
+export type MenuItem =
+  | MenuPresetItem
+  | MenuToggleItem
+  | MenuRangeItem
+  | MenuButtonItem
+  | MenuSeparatorItem;
+
+/** The rows shown when `ShellConfig.menu` is omitted — today's Settings content, minus master. */
+export const DEFAULT_MENU: MenuItem[] = [
+  { id: 'sound' },
+  { id: 'music' },
+  { id: 'sfx' },
+  { type: 'separator' },
+  { id: 'gameInfo' },
+];
+
+/** What `resolveMenu` reads. `ShellController` satisfies it; tests can supply a small literal. */
+export interface MenuHost {
+  readonly menu: MenuItem[];
+  t(text: string): string;
+  getMenuValue(id: string): boolean | number | undefined;
+  setMenuValue(id: string, value: boolean | number): void;
+  readonly actions: { openInfo(): void };
+}
+
+/** A row, ready to draw: no preset knowledge left, no config shapes, just kind + accessors. */
+export type MenuRow =
+  | { kind: 'separator' }
+  | {
+      kind: 'toggle';
+      id: string;
+      label: string;
+      disabled: boolean;
+      /** Glyph for the current value (the sound preset swaps speaker on/off). */
+      icon(value: boolean): IconName | undefined;
+      get(): boolean;
+      set(value: boolean): void;
+    }
+  | {
+      kind: 'range';
+      id: string;
+      label: string;
+      icon?: IconName;
+      disabled: boolean;
+      min: number;
+      max: number;
+      step: number;
+      get(): number;
+      set(value: number): void;
+      format(value: number): string;
+    }
+  | {
+      kind: 'button';
+      id: string;
+      label: string;
+      icon?: IconName;
+      disabled: boolean;
+      chevron: boolean;
+      select(): void;
+    };
+
+const isSeparator = (i: MenuItem): i is MenuSeparatorItem =>
+  (i as { type?: string }).type === 'separator';
+
+/** Range bounds with defaults: 0..1 like a volume slider, step = a twentieth of the span. */
+export function rangeBounds(item: { min?: number; max?: number; step?: number }): {
+  min: number;
+  max: number;
+  step: number;
+} {
+  const min = item.min ?? 0;
+  const max = item.max ?? 1;
+  const derivedStep = (max - min) / 20;
+  // A declared `step` must be a genuinely positive number. `??` alone doesn't catch this: an
+  // explicit 0 (or a negative value) is not null/undefined, so it would sail through unchanged —
+  // and a renderer's position math divides by it (Pixi's fromUnit: `(raw-min)/step`), turning the
+  // slider's value into NaN, which then reaches `state.menu` and the `settingChange` payload.
+  const step = item.step != null && item.step > 0 ? item.step : derivedStep;
+  return { min, max, step };
+}
+
+/** Initial values for CUSTOM items (presets keep their own homes). Values already in `prev` win, so
+ *  a later `setMenu()` with the same ids does not reset what the player has changed. */
+export function seedMenuValues(
+  items: MenuItem[],
+  prev: Record<string, boolean | number> = {},
+): Record<string, boolean | number> {
+  const out: Record<string, boolean | number> = {};
+  for (const item of items) {
+    if (isSeparator(item)) continue;
+    const type = (item as { type?: string }).type;
+    if (!type || isPresetId(item.id)) continue;
+    // A previous value only carries over when its runtime type still matches this item's kind.
+    // Without this guard, reconfiguring the same id from a toggle to a range (or back) would seed
+    // a boolean into a slider's position math (or a stale number into a checkbox) — a legitimate
+    // reconfiguration, not a config error, so it falls through to the item's own default instead
+    // of warning.
+    const prevValue = prev[item.id];
+    if (type === 'toggle') {
+      out[item.id] = typeof prevValue === 'boolean' ? prevValue : ((item as MenuToggleItem).value ?? false);
+    } else if (type === 'range') {
+      const r = item as MenuRangeItem;
+      out[item.id] = typeof prevValue === 'number' ? prevValue : (r.value ?? rangeBounds(r).min);
+    }
+  }
+  return out;
+}
+
+const percent = (v: number): string => `${Math.round(v * 100)}%`;
+
+function safeIcon(name: string | undefined): IconName | undefined {
+  return name && (ICON_NAMES as readonly string[]).includes(name) ? (name as IconName) : undefined;
+}
+
+/** Every drop/collision warning goes through here so the message style stays uniform. */
+function warn(message: string): void {
+  console.warn(`[shell] ${message}`);
+}
+
+/** Expand the configured list into render-ready rows. A config mistake — an unknown preset id, an
+ *  unrecognized custom `type`, or an invalid range span — is dropped with one warning rather than
+ *  silently misbehaving: a typo must be visible, not silently invisible. A custom id that collides
+ *  with a reserved preset id also warns, but keeps its row (see `custom()`). */
+export function resolveMenu(host: MenuHost): MenuRow[] {
+  const rows: MenuRow[] = [];
+  for (const item of host.menu) {
+    if (isSeparator(item)) {
+      rows.push({ kind: 'separator' });
+      continue;
+    }
+    const type = (item as { type?: string }).type;
+    if (!type) {
+      const row = preset(host, item as MenuPresetItem);
+      if (row) rows.push(row);
+      else warn(`unknown menu preset id "${item.id}" — item skipped`);
+      continue;
+    }
+    const row = custom(host, item as MenuToggleItem | MenuRangeItem | MenuButtonItem, type);
+    if (row) rows.push(row);
+  }
+  return rows;
+}
+
+function preset(host: MenuHost, item: MenuPresetItem): MenuRow | null {
+  const disabled = item.disabled ?? false;
+  const label = host.t(item.label ?? DEFAULT_LABELS[item.id] ?? item.id);
+  switch (item.id) {
+    case 'sound':
+      return {
+        kind: 'toggle',
+        id: 'sound',
+        label,
+        disabled,
+        icon: (v) => safeIcon(item.icon) ?? (v ? 'soundOn' : 'soundOff'),
+        get: () => host.getMenuValue('sound') !== false,
+        set: (v) => host.setMenuValue('sound', v),
+      };
+    case 'music':
+    case 'sfx': {
+      const id = item.id;
+      return {
+        kind: 'range',
+        id,
+        label,
+        icon: safeIcon(item.icon),
+        disabled,
+        min: 0,
+        max: 1,
+        step: 0.05,
+        get: () => Number(host.getMenuValue(id) ?? 1),
+        set: (v) => host.setMenuValue(id, v),
+        format: percent,
+      };
+    }
+    case 'gameInfo':
+      return {
+        kind: 'button',
+        id: 'gameInfo',
+        label,
+        icon: safeIcon(item.icon) ?? 'info',
+        disabled,
+        chevron: true,
+        select: () => host.actions.openInfo(),
+      };
+    default:
+      return null;
+  }
+}
+
+const DEFAULT_LABELS: Record<string, string> = {
+  sound: 'Sound',
+  music: 'Music',
+  sfx: 'SFX',
+  gameInfo: 'Game info',
+};
+
+function custom(
+  host: MenuHost,
+  item: MenuToggleItem | MenuRangeItem | MenuButtonItem,
+  type: string,
+): MenuRow | null {
+  // Same store, different semantics: the real preset's get() and a custom row's get() disagree
+  // (see the preset cases below vs. the toggle case here). Routing does not change — Task 4's
+  // ShellHost is what actually owns the value — this warning just makes the clash visible.
+  if (isPresetId(item.id)) {
+    warn(`menu item id "${item.id}" collides with a built-in preset id — preset ids are reserved`);
+  }
+  const disabled = item.disabled ?? false;
+  const label = host.t(item.label ?? item.id);
+  const icon = safeIcon(item.icon);
+  if (type === 'toggle') {
+    const it = item as MenuToggleItem;
+    return {
+      kind: 'toggle',
+      id: it.id,
+      label,
+      disabled,
+      icon: () => icon,
+      get: () => host.getMenuValue(it.id) === true,
+      set: (v) => {
+        host.setMenuValue(it.id, v);
+        it.onChange?.(v);
+      },
+    };
+  }
+  if (type === 'range') {
+    const it = item as MenuRangeItem;
+    const { min, max, step } = rangeBounds(it);
+    if (max <= min) {
+      // A renderer's position math ((value - min) / (max - min)) turns this into Infinity/NaN —
+      // drop the row instead, exactly like an unknown preset id.
+      warn(`menu item "${it.id}" has invalid range bounds (min ${min}, max ${max}) — item skipped`);
+      return null;
+    }
+    return {
+      kind: 'range',
+      id: it.id,
+      label,
+      icon,
+      disabled,
+      min,
+      max,
+      step,
+      get: () => Number(host.getMenuValue(it.id) ?? min),
+      set: (v) => {
+        host.setMenuValue(it.id, v);
+        it.onChange?.(v);
+      },
+      format: it.format ?? (min === 0 && max === 1 ? percent : (v) => String(v)),
+    };
+  }
+  if (type === 'button') {
+    const it = item as MenuButtonItem;
+    return {
+      kind: 'button',
+      id: it.id,
+      label,
+      icon,
+      disabled,
+      chevron: it.chevron ?? false,
+      select: () => it.onSelect?.(),
+    };
+  }
+  // Neither toggle, range, nor button — a typo'd `type` used to fall through to an unconditional
+  // button row with no onSelect. Drop it visibly instead.
+  warn(`menu item "${item.id}" has unknown type "${type}" — item skipped`);
+  return null;
+}

package/src/core/popover.ts

@@ -0,0 +1,81 @@
+/** Geometry for the bar-menu popover. Pure math over rectangles so the DOM and Pixi renderers
+ *  place it identically — the renderers only supply measured sizes and apply the result. */
+
+export interface Rect { x: number; y: number; w: number; h: number }
+export interface Surface { w: number; h: number }
+
+export interface PopoverPlacement {
+  /** Top-left of the popover card, in surface coordinates. */
+  x: number;
+  y: number;
+  /** True space on the chosen side, in surface coordinates; may be less than minH on a very short surface. The row list scrolls inside it. */
+  maxH: number;
+  /** Arrow centre, relative to the card's left edge. `-1` when there is no anchor to point at. */
+  arrowX: number;
+  /** True when the card opens below the anchor (arrow flips to the top edge). */
+  below: boolean;
+}
+
+export const POPOVER = {
+  /** Keep-out from the surface edges. */
+  margin: 8,
+  /** Space between the anchor and the card. */
+  gap: 8,
+  /** Minimum distance from the arrow tip to either rounded corner. */
+  arrowInset: 14,
+  /** A card shorter than this does not fit — flip to the other side instead. */
+  minH: 120,
+  minW: 220,
+  maxW: 320,
+} as const;
+
+const clamp = (v: number, lo: number, hi: number): number => Math.max(lo, Math.min(hi, v));
+
+/** Card width: content width clamped to [minW, maxW] and never wider than the surface. */
+export function popoverWidth(surfaceW: number, contentW: number): number {
+  const hi = Math.min(POPOVER.maxW, surfaceW - POPOVER.margin * 2);
+  return Math.max(0, clamp(contentW, Math.min(POPOVER.minW, hi), hi));
+}
+
+/** Place the card above the `anchor` (below if it does not fit), left-aligned to it and clamped
+ *  inside the surface. `anchor === null` (no bar / hidden shell) centres it, arrow off.
+ *
+ *  `anchor` drives PLACEMENT (x, y, maxH, below) — normally the bar's whole plaque ("plate"), so the
+ *  card sits flush with the bar as a whole rather than with whichever control opened it. `pointer` is
+ *  the (optional) rect the ARROW points at — normally the burger button, which can sit anywhere
+ *  inside the plate. Defaults to `anchor` when omitted, so every caller that only ever had one rect
+ *  (i.e. every caller before `pointer` existed) keeps behaving exactly as it did before. */
+export function placePopover(
+  anchor: Rect | null,
+  surface: Surface,
+  size: { w: number; h: number },
+  pointer: Rect | null = null,
+): PopoverPlacement {
+  const { margin, gap, arrowInset, minH } = POPOVER;
+  if (!anchor) {
+    const maxH = Math.max(0, surface.h - margin * 2);
+    const h = Math.min(size.h, maxH);
+    const rawY = (surface.h - h) / 2;
+    const y = clamp(rawY, margin, Math.max(margin, surface.h - h - margin));
+    return {
+      x: Math.max(margin, (surface.w - size.w) / 2),
+      y,
+      maxH,
+      arrowX: -1,
+      below: false,
+    };
+  }
+  const spaceAbove = anchor.y - gap - margin;
+  const spaceBelow = surface.h - (anchor.y + anchor.h) - gap - margin;
+  // Prefer above; flip only when the card would be squeezed below its usable minimum AND there is
+  // genuinely more room on the other side.
+  const below = spaceAbove < Math.min(size.h, minH) && spaceBelow > spaceAbove;
+  const maxH = Math.max(0, below ? spaceBelow : spaceAbove);
+  const h = Math.min(size.h, maxH);
+  const x = clamp(anchor.x, margin, Math.max(margin, surface.w - size.w - margin));
+  const rawY = below ? anchor.y + anchor.h + gap : anchor.y - gap - h;
+  const y = clamp(rawY, margin, Math.max(margin, surface.h - h - margin));
+  const arrowAnchor = pointer ?? anchor;
+  const arrowX = clamp(arrowAnchor.x + arrowAnchor.w / 2 - x, arrowInset, Math.max(arrowInset, size.w - arrowInset));
+  return { x, y, maxH, arrowX, below };
+}