@open-slot-ui/core 0.8.3 → 0.9.0

package/dist/index.cjs

@@ -437,12 +437,136 @@ function valueFitMaxWidth(digits, columnWidth) {
   return clampDigits(digits) * columnWidth + 64;
 }
 
+// src/format/currency.ts
+var CURRENCY_TABLE = Object.freeze({
+  // ── fiat — symbol BEFORE the amount ──────────────────────────────────────────
+  USD: { symbol: "$", decimals: 2 },
+  CAD: { symbol: "CA$", decimals: 2 },
+  JPY: { symbol: "\xA5", decimals: 0 },
+  EUR: { symbol: "\u20AC", decimals: 2 },
+  RUB: { symbol: "\u20BD", decimals: 2 },
+  CNY: { symbol: "CN\xA5", decimals: 2 },
+  PHP: { symbol: "\u20B1", decimals: 2 },
+  INR: { symbol: "\u20B9", decimals: 2 },
+  IDR: { symbol: "Rp", decimals: 0 },
+  KRW: { symbol: "\u20A9", decimals: 0 },
+  BRL: { symbol: "R$", decimals: 2 },
+  MXN: { symbol: "MX$", decimals: 2 },
+  TRY: { symbol: "\u20BA", decimals: 2 },
+  GBP: { symbol: "\xA3", decimals: 2 },
+  NGN: { symbol: "\u20A6", decimals: 2 },
+  TWD: { symbol: "NT$", decimals: 2 },
+  SGD: { symbol: "SG$", decimals: 2 },
+  MYR: { symbol: "RM", decimals: 2 },
+  CRC: { symbol: "\u20A1", decimals: 2 },
+  // three-decimal dinars/rials (1 unit = 1000 fils) — the >2-decimal path must format these
+  KWD: { symbol: "KD", decimals: 3 },
+  JOD: { symbol: "JD", decimals: 3 },
+  BHD: { symbol: "BD", decimals: 3 },
+  OMR: { symbol: "OMR", decimals: 3 },
+  TND: { symbol: "DT", decimals: 3 },
+  LYD: { symbol: "LD", decimals: 3 },
+  IQD: { symbol: "IQD", decimals: 3 },
+  // ── fiat — symbol AFTER the amount ───────────────────────────────────────────
+  DKK: { symbol: "kr", decimals: 2, symbolAfter: true },
+  NOK: { symbol: "kr", decimals: 2, symbolAfter: true },
+  PLN: { symbol: "z\u0142", decimals: 2, symbolAfter: true },
+  VND: { symbol: "\u20AB", decimals: 0, symbolAfter: true },
+  CLP: { symbol: "CLP", decimals: 0, symbolAfter: true },
+  ARS: { symbol: "ARS", decimals: 2, symbolAfter: true },
+  PEN: { symbol: "S/", decimals: 2, symbolAfter: true },
+  // ── crypto (8-dp, so sub-cent + high precision format correctly) ─────────────
+  BTC: { symbol: "\u20BF", decimals: 8 },
+  ETH: { symbol: "\u039E", decimals: 8 },
+  LTC: { symbol: "\u0141", decimals: 8 },
+  BCH: { symbol: "BCH", decimals: 8 },
+  DOGE: { symbol: "\xD0", decimals: 8 },
+  USDT: { symbol: "\u20AE", decimals: 2 },
+  USDC: { symbol: "USDC", decimals: 2 },
+  // ── Stake social coins — Gold Coins / Stake Cash (shown as GC / SC) ───────────
+  XGC: { symbol: "GC", decimals: 2, social: true },
+  XSC: { symbol: "SC", decimals: 2, social: true },
+  GC: { symbol: "GC", decimals: 2, social: true },
+  SC: { symbol: "SC", decimals: 2, social: true }
+});
+var upper = (code) => typeof code === "string" ? code.toUpperCase() : "";
+function isSocialCurrency(code) {
+  return CURRENCY_TABLE[upper(code)]?.social === true;
+}
+function resolveCurrency(code, overrides = {}) {
+  const info = CURRENCY_TABLE[upper(code)];
+  if (!info) {
+    return {
+      code: overrides.code ?? code,
+      decimals: clampDecimals(overrides.decimals ?? 2),
+      position: overrides.position ?? "suffix",
+      separator: overrides.separator ?? ",",
+      decimalChar: overrides.decimalChar ?? ".",
+      ...overrides.symbol ? { symbol: overrides.symbol, display: overrides.display ?? "symbol" } : {}
+    };
+  }
+  return {
+    // Social coins carry their DISPLAY code (XGC → "GC", XSC → "SC"); fiat/crypto keep
+    // their ISO code (the symbol is what's actually rendered under `display:'symbol'`).
+    code: overrides.code ?? (info.social ? info.symbol : code),
+    symbol: overrides.symbol ?? info.symbol,
+    display: overrides.display ?? "symbol",
+    position: overrides.position ?? (info.symbolAfter ? "suffix" : "prefix"),
+    decimals: clampDecimals(overrides.decimals ?? info.decimals),
+    separator: overrides.separator ?? ",",
+    decimalChar: overrides.decimalChar ?? "."
+  };
+}
+function neededDecimals(value, base) {
+  const b = clampDecimals(base);
+  if (!Number.isFinite(value) || value === 0) return b;
+  let scaled = Math.round(Math.abs(value) * 1e8);
+  let d = 8;
+  while (d > b && scaled % 10 === 0) {
+    scaled /= 10;
+    d--;
+  }
+  return d;
+}
+function formatAmountPrecise(value, spec, opts = {}) {
+  const base = clampDecimals(spec.decimals ?? 2);
+  const d = neededDecimals(value, base);
+  return d === base ? formatAmount(value, spec, opts) : formatAmount(value, { ...spec, decimals: d }, opts);
+}
+function formatAmount(value, spec, opts = {}) {
+  const decimals = clampDecimals(spec.decimals);
+  const sep = spec.separator ?? ",";
+  const dot = spec.decimalChar ?? ".";
+  const n = Number.isFinite(value) ? value : 0;
+  const fixed = Math.abs(n).toFixed(decimals);
+  const [int = "0", frac] = fixed.split(".");
+  const grouped = int.replace(/\B(?=(\d{3})+(?!\d))/g, sep);
+  const body = frac ? `${grouped}${dot}${frac}` : grouped;
+  const sign = n < 0 ? "-" : opts.signed ? "+" : "";
+  const number = `${sign}${body}`;
+  const symbolMode = spec.display === "symbol" && !!spec.symbol;
+  const affix = symbolMode ? spec.symbol : spec.code;
+  const prefix = (spec.position ?? "suffix") === "prefix";
+  const gap = symbolMode && prefix ? "" : " ";
+  return prefix ? `${affix}${gap}${number}` : `${number}${gap}${affix}`;
+}
+
 // src/controls/ValueDisplay.ts
 var ValueDisplay = class extends Control {
   states = { idle: { interactable: false } };
   value = new Signal(0);
   currency;
   label;
+  /**
+   * Show a value at the precision it ACTUALLY carries (default on): when the value has
+   * more fraction digits than the currency's native precision — a sub-unit win like a
+   * USD 0.01 bet × a ×0.2 face = 0.002, or the 999.982 balance it leaves behind — the
+   * display decimals bump just enough to reveal them ($0.002), and drop back to the
+   * native look (5.00) once the value is clean again. Set `false` for hard-fixed decimals.
+   */
+  autoPrecision = true;
+  /** The currency's NATIVE precision — what `autoPrecision` returns to on clean values. */
+  baseDecimals;
   /** Minimum odometer column width (0 = auto: sized tightly to the value, grows as it
    *  does). Read by the renderer at build time, so set it before mount (or declaratively
    *  via `controls.{id}.digits`). */
@@ -453,9 +577,11 @@ var ValueDisplay = class extends Control {
     this.currency = new Signal(
       c && typeof c.code === "string" ? { ...c, decimals: clampDecimals(c.decimals) } : { code: "USD", decimals: 2 }
     );
+    this.baseDecimals = this.currency.get().decimals;
     this.label = opts.label;
     this.digits = clampMinDigits(opts.digits ?? 0);
     if (opts.initial != null) this.value.set(opts.initial);
+    this.applyPrecision();
   }
   /** Set the minimum odometer column width (clamped 0..18; 0 = auto). Read by the
    *  renderer at build time, so set it before mount (or via `controls.{id}.digits`). */
@@ -466,14 +592,27 @@ var ValueDisplay = class extends Control {
    *  good value — malformed host data never throws into the render loop (P11). */
   set(amount) {
     this.value.set(safeAmount(amount, this.value.get()));
+    this.applyPrecision();
   }
   get() {
     return this.value.get();
   }
-  /** Keep the prior spec on malformed input; clamp decimals to 0..8 (P11). */
+  /** Keep the prior spec on malformed input; clamp decimals to 0..8 (P11). The given
+   *  decimals become the NATIVE precision (`autoPrecision` bumps above it as needed). */
   setCurrency(spec) {
     if (!spec || typeof spec.code !== "string") return;
-    this.currency.set({ ...spec, decimals: clampDecimals(spec.decimals) });
+    this.baseDecimals = clampDecimals(spec.decimals);
+    this.currency.set({ ...spec, decimals: this.baseDecimals });
+    this.applyPrecision();
+  }
+  /** Bump the display decimals to what the current value needs — never below the
+   *  currency's native precision — and drop back once the value is clean again.
+   *  No-op (and no signal churn) when the shown precision is already right. */
+  applyPrecision() {
+    if (!this.autoPrecision) return;
+    const want = neededDecimals(this.value.get(), this.baseDecimals);
+    const cur = this.currency.get();
+    if (cur.decimals !== want) this.currency.set({ ...cur, decimals: want });
   }
   /** Accent emphasis: the renderer tints the value in the theme accent while on.
    *  For "this number is modified" moments — e.g. a bet display showing the
@@ -1132,6 +1271,7 @@ var BLOCK_KINDS = [
   "subheading",
   "callout",
   "stat-grid",
+  "mode-stats",
   "steps",
   "table",
   "paytable",
@@ -1284,6 +1424,9 @@ function validateSpec(spec) {
         if (b.kind === "stat-grid" && (!b.items || b.items.length === 0)) {
           add("warn", `${p}.items`, "empty-grid", "a stat-grid block has no items");
         }
+        if (b.kind === "mode-stats" && !spec.facts?.modes?.length) {
+          add("warn", `${p}`, "mode-stats-no-facts", "a mode-stats block renders from spec.facts.modes, but no modes are declared");
+        }
         if (b.kind === "steps" && (!b.items || b.items.length === 0)) {
           add("warn", `${p}.items`, "empty-steps", "a steps block has no items");
         }
@@ -1479,6 +1622,10 @@ var openuiDefaults = {
   // reality check (RTS 13) — {{minutes}} is interpolated by open-ui's scheduler
   "openui.realityCheck.title": "Reality check",
   "openui.realityCheck.message": "You've been playing for {{minutes}} minutes. Take a moment before continuing.",
+  // Rules-completeness audit (the info menu's "forgotten declarations" card)
+  "openui.rulesAudit.title": "Rules incomplete",
+  "openui.rulesAudit.required": "Missing required information:",
+  "openui.rulesAudit.recommended": "Highly recommended:",
   // RGS error defaults (override via your messages dict or per-call)
   "openui.err.generic.title": "Something went wrong",
   "openui.err.generic.message": "Sorry, something went wrong. Please try again.",
@@ -1517,11 +1664,13 @@ var openuiSocialDefaults = {
   "openui.replay.costMultiplier": "Feature Multiplier",
   "openui.replay.payoutMultiplier": "Final Multiplier",
   "openui.err.insufficient.message": "You don't have enough balance for this play.",
-  "openui.err.limit.message": "A play limit has been reached. Please try again later."
+  "openui.err.limit.message": "A play limit has been reached. Please try again later.",
+  // The auto mode-stats grid's label words (used as their own keys at render time).
+  "Max win": "Max prize"
 };
 function interpolate(template, vars) {
   if (!vars) return template;
-  return template.replace(/\{\{(\w+)\}\}/g, (_m, k) => String(vars[k] ?? `{{${k}}}`));
+  return template.replace(/\{\{([\w.-]+)\}\}/g, (_m, k) => String(vars[k] ?? `{{${k}}}`));
 }
 var DictionaryTranslator = class {
   constructor(messages, locale, socialMessages = {}) {
@@ -1561,98 +1710,207 @@ function dictionary(messages, locale, socialMessages) {
   return new DictionaryTranslator(messages, locale, socialMessages);
 }
 
-// src/format/currency.ts
-var CURRENCY_TABLE = Object.freeze({
-  // ── fiat — symbol BEFORE the amount ──────────────────────────────────────────
-  USD: { symbol: "$", decimals: 2 },
-  CAD: { symbol: "CA$", decimals: 2 },
-  JPY: { symbol: "\xA5", decimals: 0 },
-  EUR: { symbol: "\u20AC", decimals: 2 },
-  RUB: { symbol: "\u20BD", decimals: 2 },
-  CNY: { symbol: "CN\xA5", decimals: 2 },
-  PHP: { symbol: "\u20B1", decimals: 2 },
-  INR: { symbol: "\u20B9", decimals: 2 },
-  IDR: { symbol: "Rp", decimals: 0 },
-  KRW: { symbol: "\u20A9", decimals: 0 },
-  BRL: { symbol: "R$", decimals: 2 },
-  MXN: { symbol: "MX$", decimals: 2 },
-  TRY: { symbol: "\u20BA", decimals: 2 },
-  GBP: { symbol: "\xA3", decimals: 2 },
-  NGN: { symbol: "\u20A6", decimals: 2 },
-  TWD: { symbol: "NT$", decimals: 2 },
-  SGD: { symbol: "SG$", decimals: 2 },
-  MYR: { symbol: "RM", decimals: 2 },
-  CRC: { symbol: "\u20A1", decimals: 2 },
-  // three-decimal dinars (1 unit = 1000 fils) — the >2-decimal path must format these
-  KWD: { symbol: "KD", decimals: 3 },
-  JOD: { symbol: "JD", decimals: 3 },
-  BHD: { symbol: "BD", decimals: 3 },
-  // ── fiat — symbol AFTER the amount ───────────────────────────────────────────
-  DKK: { symbol: "kr", decimals: 2, symbolAfter: true },
-  NOK: { symbol: "kr", decimals: 2, symbolAfter: true },
-  PLN: { symbol: "z\u0142", decimals: 2, symbolAfter: true },
-  VND: { symbol: "\u20AB", decimals: 0, symbolAfter: true },
-  CLP: { symbol: "CLP", decimals: 0, symbolAfter: true },
-  ARS: { symbol: "ARS", decimals: 2, symbolAfter: true },
-  PEN: { symbol: "S/", decimals: 2, symbolAfter: true },
-  // ── crypto (8-dp, so sub-cent + high precision format correctly) ─────────────
-  BTC: { symbol: "\u20BF", decimals: 8 },
-  ETH: { symbol: "\u039E", decimals: 8 },
-  LTC: { symbol: "\u0141", decimals: 8 },
-  BCH: { symbol: "BCH", decimals: 8 },
-  DOGE: { symbol: "\xD0", decimals: 8 },
-  USDT: { symbol: "\u20AE", decimals: 2 },
-  USDC: { symbol: "USDC", decimals: 2 },
-  // ── Stake social coins — Gold Coins / Stake Cash (shown as GC / SC) ───────────
-  XGC: { symbol: "GC", decimals: 2, social: true },
-  XSC: { symbol: "SC", decimals: 2, social: true },
-  GC: { symbol: "GC", decimals: 2, social: true },
-  SC: { symbol: "SC", decimals: 2, social: true }
-});
-var upper = (code) => typeof code === "string" ? code.toUpperCase() : "";
-function isSocialCurrency(code) {
-  return CURRENCY_TABLE[upper(code)]?.social === true;
-}
-function resolveCurrency(code, overrides = {}) {
-  const info = CURRENCY_TABLE[upper(code)];
-  if (!info) {
-    return {
-      code: overrides.code ?? code,
-      decimals: clampDecimals(overrides.decimals ?? 2),
-      position: overrides.position ?? "suffix",
-      separator: overrides.separator ?? ",",
-      decimalChar: overrides.decimalChar ?? ".",
-      ...overrides.symbol ? { symbol: overrides.symbol, display: overrides.display ?? "symbol" } : {}
-    };
+// src/spec/facts.ts
+function mergeFacts(base, add) {
+  const modes = [...base.modes ?? []];
+  for (const m of add.modes ?? []) {
+    const i = modes.findIndex((x) => x.id === m.id);
+    if (i < 0) modes.push({ ...m });
+    else {
+      const merged = { ...modes[i] };
+      for (const [k, v] of Object.entries(m)) if (v !== void 0) merged[k] = v;
+      modes[i] = merged;
+    }
   }
   return {
-    // Social coins carry their DISPLAY code (XGC → "GC", XSC → "SC"); fiat/crypto keep
-    // their ISO code (the symbol is what's actually rendered under `display:'symbol'`).
-    code: overrides.code ?? (info.social ? info.symbol : code),
-    symbol: overrides.symbol ?? info.symbol,
-    display: overrides.display ?? "symbol",
-    position: overrides.position ?? (info.symbolAfter ? "suffix" : "prefix"),
-    decimals: clampDecimals(overrides.decimals ?? info.decimals),
-    separator: overrides.separator ?? ",",
-    decimalChar: overrides.decimalChar ?? "."
+    ...modes.length ? { modes } : {},
+    freeSpins: add.freeSpins !== void 0 ? add.freeSpins : base.freeSpins,
+    volatility: add.volatility ?? base.volatility,
+    maxWinCapX: add.maxWinCapX ?? base.maxWinCapX
   };
 }
-function formatAmount(value, spec, opts = {}) {
-  const decimals = clampDecimals(spec.decimals);
-  const sep = spec.separator ?? ",";
-  const dot = spec.decimalChar ?? ".";
-  const n = Number.isFinite(value) ? value : 0;
-  const fixed = Math.abs(n).toFixed(decimals);
-  const [int = "0", frac] = fixed.split(".");
-  const grouped = int.replace(/\B(?=(\d{3})+(?!\d))/g, sep);
-  const body = frac ? `${grouped}${dot}${frac}` : grouped;
-  const sign = n < 0 ? "-" : opts.signed ? "+" : "";
-  const number = `${sign}${body}`;
-  const symbolMode = spec.display === "symbol" && !!spec.symbol;
-  const affix = symbolMode ? spec.symbol : spec.code;
-  const prefix = (spec.position ?? "suffix") === "prefix";
-  const gap = symbolMode && prefix ? "" : " ";
-  return prefix ? `${affix}${gap}${number}` : `${number}${gap}${affix}`;
+function formatRtp(rtp) {
+  return `${rtp.toFixed(2)}%`;
+}
+function formatTimes(x) {
+  return `${x.toLocaleString("en-US", { maximumFractionDigits: 2 })}\xD7`;
+}
+function modeStatsItems(facts, tr = (s) => s) {
+  const out = [];
+  for (const m of facts?.modes ?? []) {
+    if (m.rtp != null) out.push({ label: `${tr("RTP")} \xB7 ${tr(m.name)}`, value: formatRtp(m.rtp) });
+    if (m.maxWinX != null) out.push({ label: `${tr("Max win")} \xB7 ${tr(m.name)}`, value: formatTimes(m.maxWinX) });
+  }
+  if (facts?.volatility) out.push({ label: tr("Volatility"), value: tr(facts.volatility) });
+  if (facts?.maxWinCapX != null) out.push({ label: tr("Round cap"), value: formatTimes(facts.maxWinCapX) });
+  return out;
+}
+function factsVars(facts, extra) {
+  const vars = {};
+  for (const m of facts?.modes ?? []) {
+    if (!m.id) continue;
+    vars[`name.${m.id}`] = m.name;
+    if (m.rtp != null) vars[`rtp.${m.id}`] = formatRtp(m.rtp);
+    if (m.maxWinX != null) vars[`maxWin.${m.id}`] = formatTimes(m.maxWinX);
+    if (m.cost != null) vars[`cost.${m.id}`] = formatTimes(m.cost);
+  }
+  const fs = facts?.freeSpins;
+  if (fs) {
+    if (fs.count != null) vars["freeSpins.count"] = fs.count;
+    if (fs.retrigger != null) vars["freeSpins.retrigger"] = fs.retrigger ? "can" : "cannot";
+  }
+  if (facts?.volatility) vars["volatility"] = facts.volatility;
+  if (facts?.maxWinCapX != null) vars["maxWinCap"] = formatTimes(facts.maxWinCapX);
+  return extra ? { ...vars, ...extra } : vars;
+}
+function scanBlocks(blocks, resolve = (s) => s) {
+  const scan = { text: "", headings: "", covers: /* @__PURE__ */ new Set(), hasModeStats: false, hasLegal: false };
+  const addText = (t) => {
+    if (typeof t === "string" && t) scan.text += `
+${resolve(t)}`;
+  };
+  const walk = (list) => {
+    for (const b of list ?? []) {
+      for (const c of b.covers ?? []) scan.covers.add(c);
+      const anyB = b;
+      switch (b.kind) {
+        case "mode-stats":
+          scan.hasModeStats = true;
+          (b.extras ?? []).forEach((it) => {
+            addText(it.label);
+            addText(it.value);
+          });
+          break;
+        case "legal":
+          scan.hasLegal = true;
+          addText(b.text);
+          break;
+        case "heading":
+        case "subheading":
+          scan.headings += `
+${resolve(b.text)}`;
+          addText(b.text);
+          break;
+        case "text":
+          addText(b.text);
+          break;
+        case "callout":
+          addText(b.title);
+          addText(b.text);
+          break;
+        case "media":
+          addText(b.title);
+          addText(b.text);
+          break;
+        case "steps":
+          b.items.forEach(addText);
+          break;
+        case "table":
+          (b.columns ?? []).forEach(addText);
+          b.rows.forEach((r) => r.forEach(addText));
+          break;
+        case "paytable":
+          b.rows.forEach((r) => {
+            addText(r.symbol);
+            addText(r.payouts);
+          });
+          break;
+        case "cards":
+          b.items.forEach((it) => {
+            addText(it.title);
+            addText(it.text);
+          });
+          break;
+        case "stat-grid":
+          b.items.forEach((it) => {
+            addText(it.label);
+            addText(it.value);
+          });
+          break;
+        case "group":
+          addText(b.title);
+          walk(b.children);
+          break;
+        default:
+          addText(anyB.label);
+          addText(anyB.hint);
+          break;
+      }
+    }
+  };
+  walk(blocks);
+  return scan;
+}
+var escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function mentionsRtp(text, rtp) {
+  const s = String(rtp);
+  const [int = "", frac = ""] = s.split(".");
+  const body = frac ? `${escapeRe(int)}[.,]${escapeRe(frac)}0*` : `${escapeRe(int)}(?:[.,]0{1,2})?`;
+  return new RegExp(`\\b${body}\\s*%`).test(text);
+}
+function mentionsTimes(text, x) {
+  const digits = String(Math.trunc(Math.abs(x)));
+  let grouped = "";
+  for (let i = 0; i < digits.length; i++) {
+    if (i > 0 && (digits.length - i) % 3 === 0) grouped += "[,.\\s\\u00a0]?";
+    grouped += digits[i];
+  }
+  const frac = Math.abs(x) % 1 !== 0 ? `[.,]\\d+` : `(?:[.,]\\d+)?`;
+  return new RegExp(`\\b${grouped}${frac}\\s*[x\xD7]`, "i").test(text);
+}
+var mentionsName = (text, name) => text.toLowerCase().includes(name.toLowerCase());
+function auditRules(facts, rules, opts = {}) {
+  const out = [];
+  try {
+    const scan = scanBlocks(rules, opts.resolve);
+    const add = (level, code, topic, message) => {
+      out.push({ level, code, topic, message });
+    };
+    const covered = (topic) => scan.covers.has(topic);
+    for (const m of facts?.modes ?? []) {
+      const nameIn = mentionsName(scan.text, m.name);
+      if (m.rtp == null) {
+        add("required", "facts-missing-rtp", `rtp:${m.id}`, `\u201C${m.name}\u201D declares no RTP \u2014 set facts.modes[].rtp so the rules can state it.`);
+      } else if (!(scan.hasModeStats || covered(`rtp:${m.id}`) || nameIn && mentionsRtp(scan.text, m.rtp))) {
+        add("required", "rules-missing-rtp", `rtp:${m.id}`, `The RTP of \u201C${m.name}\u201D (${formatRtp(m.rtp)}) is not stated in the rules.`);
+      }
+      if (m.maxWinX == null) {
+        add("required", "facts-missing-maxwin", `maxwin:${m.id}`, `\u201C${m.name}\u201D declares no max win \u2014 set facts.modes[].maxWinX so the rules can state it.`);
+      } else if (!(scan.hasModeStats || covered(`maxwin:${m.id}`) || nameIn && mentionsTimes(scan.text, m.maxWinX))) {
+        add("required", "rules-missing-maxwin", `maxwin:${m.id}`, `The max win of \u201C${m.name}\u201D (${formatTimes(m.maxWinX)}) is not stated in the rules.`);
+      }
+      if (m.kind && m.kind !== "base" && !(covered(`feature:${m.id}`) || nameIn)) {
+        add("required", "rules-missing-feature", `feature:${m.id}`, `The configured feature \u201C${m.name}\u201D is not described in the rules.`);
+      }
+    }
+    const fs = facts?.freeSpins;
+    if (fs === void 0) {
+      if (facts?.modes?.length) {
+        add("recommended", "facts-missing-freespins", "freespins", "Free-spins info is highly recommended: declare facts.freeSpins { count, retrigger } \u2014 or freeSpins: false if the game has none.");
+      }
+    } else if (fs !== false) {
+      const fsIn = covered("freespins") || /free\s*spins?/i.test(scan.text);
+      if (!fsIn) {
+        add("recommended", "rules-missing-freespins", "freespins", "The rules never mention the free spins this game declares.");
+      } else {
+        if (fs.count != null && !covered("freespins:count") && !new RegExp(`\\b${fs.count}\\b[\\s\\S]{0,60}?spins?|spins?[\\s\\S]{0,60}?\\b${fs.count}\\b`, "i").test(scan.text)) {
+          add("recommended", "rules-missing-fs-count", "freespins:count", `State that the bonus awards exactly ${fs.count} free spins.`);
+        }
+        if (fs.retrigger != null && !covered("freespins:retrigger") && !/re-?trigger/i.test(scan.text)) {
+          add("recommended", "rules-missing-fs-retrigger", "freespins:retrigger", `State that free spins ${fs.retrigger ? "CAN" : "CANNOT"} be retriggered.`);
+        }
+      }
+    }
+    if (rules?.length && !scan.hasLegal && !/malfunction/i.test(scan.text)) {
+      add("recommended", "rules-missing-legal", "legal", "Add the platform legal disclaimer (a `legal` block).");
+    }
+    if (rules?.length && !covered("controls") && !/\bcontrols?\b/i.test(scan.headings)) {
+      add("recommended", "rules-missing-controls", "controls", 'Describe every interactive control (a \u201CControls\u201D section or covers: ["controls"]).');
+    }
+    out.sort((a, b) => a.level === b.level ? 0 : a.level === "required" ? -1 : 1);
+  } catch {
+  }
+  return out;
 }
 
 // src/OpenUI.ts
@@ -1704,6 +1962,11 @@ var OpenUI = class {
   replay = new Signal(false);
   /** Game name + version (shown in the menu footer; for support / certification). */
   gameInfo = {};
+  /** Declared GAME FACTS (modes + RTP/max win, free spins, volatility, cap) — seeded
+   *  from `spec.facts`, extended at runtime via {@link declareFacts} (the buy-feature
+   *  modal declares its configured features automatically). Drives the `mode-stats`
+   *  rules block + the rules-completeness audit in the info menu. */
+  facts = new Signal({});
   /** Minimum round duration (ms) from jurisdiction — stored for the GAME to enforce. */
   minimumRoundDuration = 0;
   /** Buy-feature confirm threshold, as a multiple of the base bet. A play (buy or
@@ -1711,6 +1974,13 @@ var OpenUI = class {
    *  — Stake requires that bet modes above 2× never activate on a single click. `0`
    *  (the default) = off. Set via `spec.buyFeature.confirmAboveCost` or a jurisdiction. */
   confirmBuyAboveCost = 0;
+  /** When autoplay stops while the balance can no longer cover the next round —
+   *  whether the built-in RG enforcement stopped it, the game's own pre-check did, or
+   *  the player pressed Stop already broke — pop the SAME insufficient-funds modal a
+   *  manual spin shows (ERR_IPB) instead of ending silently. A normal stop with funds
+   *  in hand shows nothing. Default on; `spec.autoplay.insufficientFundsNotice: false`
+   *  opts out. */
+  autoplayInsufficientNotice = true;
   sessionNet = 0;
   prevVolumes = null;
   /** The frozen UISpec `createUI` built this from, if any — authored = run = tested. */
@@ -1850,6 +2120,13 @@ var OpenUI = class {
     this.disposers.push(this.betStepper.index.subscribe(syncStepperButtons));
     this.bet.set(this.betStepper.value);
     syncStepperButtons();
+    this.disposers.push(
+      this.bus.on("autoplayStopped", () => {
+        if (!this.autoplayInsufficientNotice || this.replay.get()) return;
+        if (this.noticePanel.isOpen) return;
+        if (this.balance.get() < this.bet.get()) this.showRgsError("ERR_IPB");
+      })
+    );
     this.disposers.push(
       this.noticePanel.state.subscribe(() => {
         if (this.noticePanel.isOpen) return;
@@ -1940,6 +2217,12 @@ var OpenUI = class {
       if (this.autoplay.isActive && this.balance.get() < this.bet.get()) this.autoplay.stop();
     }
   }
+  /** Merge more game facts into {@link facts} (modes merge by id; defined incoming
+   *  fields win). The info menu re-audits + re-renders its rules automatically. */
+  declareFacts(add) {
+    if (!add || typeof add !== "object") return;
+    this.facts.set(mergeFacts(this.facts.get(), add));
+  }
   /** Reset the running session net + aggregates + timer (e.g. on a fresh session). */
   resetSession() {
     this.sessionNet = 0;
@@ -2273,6 +2556,12 @@ function walkBlock(b, src, out) {
         add(it.value);
       });
       break;
+    case "mode-stats":
+      (b.extras ?? []).forEach((it) => {
+        add(it.label);
+        add(it.value);
+      });
+      break;
     case "group":
       add(b.title);
       b.children.forEach((c, i) => walkBlock(c, `${src}.children[${i}]`, out));
@@ -2366,6 +2655,7 @@ function createUI(spec = {}, hooks = {}) {
   }
   if (typeof spec.rtp === "number") ui.rtp.set(spec.rtp);
   if (spec.game) ui.gameInfo = { name: spec.game.name, version: spec.game.version };
+  if (spec.facts) ui.declareFacts(spec.facts);
   if (spec.betLadder?.levels?.length) {
     ui.betStepper.setLevels(spec.betLadder.levels, spec.betLadder.index ?? 0);
     ui.bet.set(ui.betStepper.value);
@@ -2378,6 +2668,7 @@ function createUI(spec = {}, hooks = {}) {
   }
   if (spec.autoplay?.lossLimits) ui.autoplay.setLossLimitOptions(spec.autoplay.lossLimits);
   if (spec.autoplay?.winLimits) ui.autoplay.setWinLimitOptions(spec.autoplay.winLimits);
+  if (spec.autoplay?.insufficientFundsNotice === false) ui.autoplayInsufficientNotice = false;
   if (spec.turbo) {
     ui.turbo.setModes(resolveTurboModes(spec.turbo.modes));
     if (spec.turbo.index != null) ui.turbo.setIndex(spec.turbo.index);
@@ -2493,6 +2784,43 @@ function composeMenu(menu, opts = {}) {
   return out;
 }
 
+// src/spec/rulesDoc.ts
+function isRulesDoc(doc) {
+  if (!doc || typeof doc !== "object") return false;
+  const d = doc;
+  return d.version === 1 && Array.isArray(d.blocks);
+}
+var mergeLocaleMaps = (under, over) => {
+  const out = {};
+  for (const src of [under, over]) {
+    for (const [loc, map] of Object.entries(src ?? {})) out[loc] = { ...out[loc], ...map };
+  }
+  return out;
+};
+function applyRulesDoc(spec, doc) {
+  if (!isRulesDoc(doc)) return spec;
+  const messages = mergeLocaleMaps(doc.messages, spec.locale?.messages);
+  const socialMessages = mergeLocaleMaps(doc.socialMessages, spec.locale?.socialMessages);
+  return {
+    ...spec,
+    menu: { ...spec.menu, rules: doc.blocks },
+    locale: {
+      locale: spec.locale?.locale ?? "en",
+      messages: Object.keys(messages).length ? messages : { en: {} },
+      ...Object.keys(socialMessages).length ? { socialMessages } : {}
+    },
+    ...doc.facts ? { facts: mergeFacts(doc.facts, spec.facts ?? {}) } : {}
+  };
+}
+function auditRulesDoc(doc, opts = {}) {
+  if (!isRulesDoc(doc)) return [];
+  const facts = opts.facts ? mergeFacts(doc.facts ?? {}, opts.facts) : doc.facts;
+  const dict = doc.messages?.[opts.locale ?? "en"] ?? {};
+  const vars = factsVars(facts);
+  const resolve = (s) => (dict[s] ?? s).replace(/\{\{([\w.-]+)\}\}/g, (_m, k) => String(vars[k] ?? `{{${k}}}`));
+  return auditRules(facts, doc.blocks, { resolve });
+}
+
 // src/spec/defaultHudSpec.ts
 var defaultHudSpec = Object.freeze({
   meta: { id: "open-ui-reference-hud", version: 1 },
@@ -2582,6 +2910,12 @@ function buildBetLadder(cfg, divisor = API_AMOUNT_DIVISOR) {
   const found = levels.findIndex((v) => v >= want);
   return { levels, index: found < 0 ? 0 : found };
 }
+function resolveBetLadder(availableBets, defaultBet, fallback = [0.2, 0.5, 1, 2, 5, 10]) {
+  const levels = availableBets?.length ? availableBets.slice() : fallback.slice();
+  const exact = levels.indexOf(defaultBet);
+  const index = exact >= 0 ? exact : Math.max(0, levels.findIndex((b) => b >= defaultBet));
+  return { levels, index };
+}
 function clampBet(amount, cfg, divisor = API_AMOUNT_DIVISOR) {
   const min = (cfg.minBet ?? 0) / divisor;
   const max = (cfg.maxBet ?? Infinity) / divisor;
@@ -2624,6 +2958,9 @@ exports.TurboControl = TurboControl;
 exports.Turn = Turn;
 exports.ValueDisplay = ValueDisplay;
 exports.applyJurisdiction = applyJurisdiction;
+exports.applyRulesDoc = applyRulesDoc;
+exports.auditRules = auditRules;
+exports.auditRulesDoc = auditRulesDoc;
 exports.breakpointFor = breakpointFor;
 exports.buildBetLadder = buildBetLadder;
 exports.buildBlocks = buildBlocks;
@@ -2648,16 +2985,25 @@ exports.displayDigits = displayDigits;
 exports.effect = effect;
 exports.errorBlocks = errorBlocks;
 exports.extendTheme = extendTheme;
+exports.factsVars = factsVars;
 exports.findForbiddenPhrases = findForbiddenPhrases;
 exports.formatAmount = formatAmount;
+exports.formatAmountPrecise = formatAmountPrecise;
+exports.formatRtp = formatRtp;
+exports.formatTimes = formatTimes;
 exports.installResponsive = installResponsive;
 exports.integerDigits = integerDigits;
+exports.isRulesDoc = isRulesDoc;
 exports.isSafeColor = isSafeColor;
 exports.isSocialCurrency = isSocialCurrency;
 exports.landscapeDefaultLayouts = landscapeDefaultLayouts;
+exports.mergeFacts = mergeFacts;
+exports.modeStatsItems = modeStatsItems;
+exports.neededDecimals = neededDecimals;
 exports.openuiDefaults = openuiDefaults;
 exports.openuiSocialDefaults = openuiSocialDefaults;
 exports.portraitDefaultLayouts = portraitDefaultLayouts;
+exports.resolveBetLadder = resolveBetLadder;
 exports.resolveCurrency = resolveCurrency;
 exports.resolvePlacement = resolvePlacement;
 exports.resolveTheme = resolveTheme;