@open-slot-ui/core 0.4.2 → 0.5.1

package/dist/index.d.cts

@@ -188,6 +188,13 @@ declare function extendTheme(base: Theme, patch: DeepPartial<Theme>): Theme;
 type Orientation = 'landscape' | 'portrait';
 /** A named device bucket. Config can target these to restyle per device. */
 type Breakpoint = 'mobile' | 'tablet' | 'desktop';
+/** The uniformly-scaled DESIGN FRAME ("stage") rect, in screen pixels. */
+interface StageRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 interface ScreenState {
     width: number;
     height: number;
@@ -196,6 +203,15 @@ interface ScreenState {
     breakpoint: Breakpoint;
     /** Multiply reference-px sizes by this to fit the current screen. */
     scale: number;
+    /**
+     * The reference design frame, scaled UNIFORMLY by `scale` and placed in the viewport
+     * (letterboxed by `stageAnchor` when the aspect ratio differs). Every control anchors
+     * to THIS rect — not the raw screen — so the whole HUD scales as one homogeneous unit
+     * and the relative gaps between controls never change with aspect ratio. At the
+     * reference resolution `stage` exactly equals the screen, so authored layouts are
+     * pixel-identical there.
+     */
+    stage: StageRect;
 }
 interface LayoutConfig {
     /** Reference design resolution for landscape / portrait. */
@@ -212,6 +228,14 @@ interface LayoutConfig {
         mobile: number;
         tablet: number;
     };
+    /**
+     * Where the uniformly-scaled design frame sits in the viewport when the aspect ratio
+     * doesn't match the reference (i.e. how the letterbox margins are distributed), as
+     * `[x, y]` factors in `0..1`. `[0.5, 1]` (default) = bottom-centre: the bottom bar
+     * always hugs the screen bottom and any extra vertical room opens ABOVE (the reel
+     * area, filled by the game); horizontal slack splits evenly. `[0.5, 0.5]` centres it.
+     */
+    stageAnchor: [number, number];
 }
 declare const defaultLayoutConfig: LayoutConfig;
 /** Classify the shorter edge into a named device bucket. Pure, total. */
@@ -236,7 +260,16 @@ interface Placement {
     /** Rotation in radians (resolved from `LayoutSpec.rotation`, which is degrees). */
     rotation: number;
 }
-/** Resolve a control's layout against the current screen. Pure math. */
+/**
+ * Resolve a control's layout against the current screen. Pure math.
+ *
+ * Anchors to the uniformly-scaled `screen.stage` frame — NOT the raw screen — so the
+ * whole HUD scales as one homogeneous unit: the gap between two controls is always a
+ * fixed fraction of the (uniformly-scaled) frame, never a function of the viewport's
+ * aspect ratio. That's what stops a growing value or a narrow window from letting
+ * controls drift into each other. At the reference resolution `stage` equals the
+ * screen, so authored offsets land pixel-identically.
+ */
 declare function resolvePlacement(spec: LayoutSpec, screen: ScreenState): Placement;
 
 /**
@@ -800,6 +833,10 @@ declare class ReadoutControl extends Control {
     readonly value: Signal<number>;
     /** Whether a `'duration'` readout is currently advancing. */
     readonly running: Signal<boolean>;
+    /** Accent emphasis: the renderer tints the value in the theme accent while on — for
+     *  a MODIFIED readout (e.g. net position while a bet boost is active). Mirrors
+     *  {@link ValueDisplay.emphasized}. */
+    readonly emphasized: Signal<boolean>;
     readonly kind: ReadoutKind;
     readonly label?: string;
     readonly decimals: number;
@@ -809,6 +846,8 @@ declare class ReadoutControl extends Control {
     constructor(opts: ReadoutOptions);
     /** Never-reject: malformed input keeps the last good value (P11). */
     set(v: number): void;
+    /** Accent-tint the value ("this readout is modified"). Strict boolean. */
+    setEmphasis(on: boolean): void;
     get(): number;
     setCurrency(spec: CurrencySpec): void;
     /** Advance an elapsed-time readout by `deltaSec` (the renderer calls this each frame). */
@@ -1224,6 +1263,9 @@ declare class OpenUI {
     readonly spin: SpinControl;
     readonly balance: ValueDisplay;
     readonly bet: ValueDisplay;
+    /** Bonus "total win" readout — shown in the buy-feature slot during a bonus/free-
+     *  spins round (the renderer swaps it for the buy button). Same money logic as `bet`. */
+    readonly totalWin: ValueDisplay;
     readonly settingsButton: ButtonControl;
     readonly settingsPanel: PanelControl;
     readonly musicSlider: SliderControl;
@@ -1440,11 +1482,13 @@ type BlockSpec = {
     id: string;
     label?: string;
     initial?: number;
+    hint?: string;
 } | {
     kind: 'toggle';
     id: string;
     label?: string;
     on?: boolean;
+    hint?: string;
 } | {
     kind: 'button';
     id: string;
@@ -1452,18 +1496,21 @@ type BlockSpec = {
     action?: 'closePanel' | 'openPanel' | 'emit';
     target?: string;
     role?: string;
+    hint?: string;
 } | {
     kind: 'select';
     id: string;
     label?: string;
     options: SelectOption[];
     index?: number;
+    hint?: string;
 } | {
     kind: 'stepper';
     id: string;
     label?: string;
     levels: number[];
     index?: number;
+    hint?: string;
 } | {
     kind: 'value';
     id: string;
@@ -1712,6 +1759,60 @@ declare function resolveTurboModes(modes: TurboSpec['modes']): string[];
 declare function defineUI(spec: UISpec): UISpec;
 declare function createUI(spec?: UISpec, hooks?: HostHooks): OpenUI;
 
+/**
+ * Social-mode FORBIDDEN-PHRASE checker (Charter B8/P11). Stake US social/sweepstakes
+ * jurisdiction restricts gambling wording; a game must not surface "bet", "pay(table)",
+ * "funds", "cash", etc. anywhere in its copy. This scans the ENGLISH strings a game
+ * ships (menu blocks, rules, section titles, control labels/hints, the `en` dictionary,
+ * the game name) and reports every restricted phrase with a compliant replacement, so
+ * the classic "we shipped a *paytable* while `pay` is banned" slips through no longer.
+ *
+ * It's a lint, not a gate — never throws; `createUI` runs it automatically in social
+ * mode and forwards findings to `HostHooks.onDataIssue` (+ a console warning), and a
+ * game's own test can call {@link checkSocialPhrases} directly.
+ *
+ * See Stake's "Jurisdiction Requirements → forbidden phrases" for the authoritative
+ * list; this covers the common roots and their recommended replacements.
+ */
+
+interface ForbiddenMatch {
+    /** The restricted root that matched ("pay*", "bet", "funds", …). */
+    term: string;
+    /** The recommended compliant replacement. */
+    replacement: string;
+}
+interface SocialPhraseIssue {
+    /** Where the copy lives (e.g. `menu.rules[3]`, `locale.en["Paytable"]`). */
+    source: string;
+    /** The offending string. */
+    text: string;
+    /** Every restricted phrase found in it. */
+    matches: ForbiddenMatch[];
+}
+/** Every restricted phrase in `text` (empty when clean). Pure + total. */
+declare function findForbiddenPhrases(text: string): ForbiddenMatch[];
+/** A collected string. `text` is the base English (what renders with no social
+ *  override); `key` is the i18n key used to look up a social override — it defaults
+ *  to `text`, since a game's menu/rules copy doubles as its own key. */
+type Entry = {
+    source: string;
+    text: string;
+    key?: string;
+};
+/** Collect every English string a spec ships (menu/rules blocks, titles, labels+hints,
+ *  game name, the `en` dictionary) with a source path — the input to {@link checkSocialPhrases}. */
+declare function collectSocialCopy(spec: UISpec): Entry[];
+/**
+ * Scan a spec's English copy AS IT RENDERS IN SOCIAL MODE and return every restricted
+ * phrase. Each collected string is first resolved through the social dictionary
+ * (`locale.socialMessages.en` → built-in `openuiSocialDefaults` → the base text) —
+ * exactly like the translator does — so a game that already swaps "bet"/"pay(table)"
+ * for compliant wording in social mode is NOT flagged, while a phrase with NO social
+ * override (the classic slipped-through "paytable") IS. English by design: the check
+ * targets the base `en` copy that every jurisdiction review starts from.
+ */
+declare function checkSocialPhrases(spec: UISpec): SocialPhraseIssue[];
+
 /**
  * The responsive layer: re-apply per-device / per-orientation control overrides
  * every time the screen bucket changes. Pure assembly over the existing layout
@@ -1772,36 +1873,49 @@ declare class EventLog {
 /**
  * Currency display metadata + a pure formatter (Charter P11: data, not code).
  *
- * Stake Engine supports 35+ currencies — fiat (incl. zero-decimal JPY/KRW/VND…),
- * crypto, and the social coins XGC/XSC (shown as "GC"/"SC", never locale-formatted
- * as fiat). A host shouldn't have to hand-tune decimals for each, so this maps a
- * code → its display precision; anything unknown defaults to 2 (the common case).
- * The UI computes no money — it only formats what the game sets.
+ * This is the **Stake Engine currency table**: every code Stake supports, mapped to
+ * its display SYMBOL, minor-unit decimals, and symbol side (before/after the number).
+ * A game shouldn't hand-tune any of this — it either passes a full `CurrencySpec`, or
+ * just the CODE (`currency: 'CNY'`) and gets the Stake formatting for free
+ * ("I use the Stake currency formatter"). Unknown codes fall back to a 2-decimal,
+ * code-suffix spec so nothing ever breaks. The UI computes no money — it only formats
+ * what the game sets.
  */
 
 interface CurrencyInfo {
-    /** Fractional digits to show (JPY/KRW = 0, USD = 2, BTC = 8). */
+    /** The glyph shown to the player ("$", "CN¥", "GC"). */
+    symbol: string;
+    /** Fractional digits to show (JPY/KRW/IDR = 0, USD = 2, BTC = 8). */
     decimals: number;
-    /** Display code shown to the player when it differs from the code (XGC → "GC"). */
-    display?: string;
-    /** A social / sweepstakes coin — never formatted as a fiat currency. */
+    /** Symbol AFTER the number ("10,00 zł") rather than before ("$10.00"). Default before. */
+    symbolAfter?: boolean;
+    /** A social / sweepstakes coin (Gold Coins / Stake Cash) — never fiat wording. */
     social?: boolean;
 }
-/** Code → display info. Unknown codes fall back to 2 decimals (see {@link resolveCurrency}). */
+/**
+ * The Stake Engine supported-currency matrix (symbol · decimals · placement), 1:1 with
+ * the platform's `CurrencyMeta`. Symbol placement: prefix by default, SUFFIX for the
+ * few that render after the amount (DKK/PLN/VND/CLP/ARS/PEN). Crypto is included for
+ * completeness (8-dp with a symbol) so high-precision balances also format right.
+ */
 declare const CURRENCY_TABLE: Readonly<Record<string, CurrencyInfo>>;
-/** True if `code` is a Stake social/sweepstakes coin (display "GC"/"SC"). */
+/** True if `code` is a Stake social/sweepstakes coin (displayed "GC"/"SC"). */
 declare function isSocialCurrency(code: string): boolean;
 /**
- * Resolve a currency code to a complete, display-ready {@link CurrencySpec}: fills
- * decimals from the table (default 2) and maps social coins to their display code.
- * Anything in `overrides` wins, so a game can still hand-tune. Never throws.
+ * Resolve a currency code to a complete, display-ready {@link CurrencySpec} using the
+ * Stake table: fills the SYMBOL (rendered tight, `display:'symbol'`), its side
+ * (`position`), and the minor-unit `decimals`. Anything in `overrides` wins so a game
+ * can still hand-tune (e.g. force more decimals for sub-cent payouts). An unknown code
+ * degrades to a 2-decimal code-suffix spec. Never throws.
  */
 declare function resolveCurrency(code: string, overrides?: Partial<CurrencySpec>): CurrencySpec;
 /**
  * Format an amount (major units) per a {@link CurrencySpec}: grouped integer part,
- * fixed decimals, the code on the configured side. `signed` adds an explicit "+"
- * for non-negative values (negatives always show "-") — used by the net-position
- * readout. Pure + total: a malformed number renders as "0".
+ * fixed decimals, and the affix on the configured side. When `display:'symbol'` (and a
+ * symbol is set) the SYMBOL sits tight against the number (`CN¥1,234.56` · `1.234,56 zł`);
+ * otherwise the ISO code is spaced (`1,234.56 USD`). `signed` adds an explicit "+" for
+ * non-negative values (used by the net-position readout). Pure + total: a malformed
+ * number renders as "0".
  */
 declare function formatAmount(value: number, spec: CurrencySpec, opts?: {
     signed?: boolean;
@@ -1834,4 +1948,4 @@ declare function buildBetLadder(cfg: RgsBetConfig, divisor?: number): {
 /** Clamp a stake (major units) to the RGS min/max and snap to `stepBet`. Pure. */
 declare function clampBet(amount: number, cfg: RgsBetConfig, divisor?: number): number;
 
-export { API_AMOUNT_DIVISOR, type Anchor, AutoplayControl, type AutoplayLimits, type AutoplayMode, type AutoplayOptions, BLOCK_KINDS, type BlockFactory, type BlockSpec, type Breakpoint, type BuiltPanel, ButtonControl, type ButtonOptions, CURRENCY_TABLE, CardControl, type CardOptions, type ComposeMenuOptions, Control, type ControlOptions, type ControlOverride, ControlRegistry, type ControlSnapshot, type CurrencyInfo, type CurrencySpec, DEFAULT_MENU_TITLES, DEFAULT_NOTICE_ACTION, type DeepPartial, DictionaryTranslator, type Dispose, EventBus, EventLog, type EventLogOptions, type EventMap, Fade, type HostHooks, type JurisdictionConfig, type KnownControlId, LOCALE_LABELS, type LayoutConfig, type LayoutSpec, type LoggedEvent, type MenuSpec, type NoticeAction, type NoticeOptions, OpenUI, type OpenUIEvents, type OpenUIOptions, type Orientation, PanelControl, type PanelOptions, type PanelSpec, type PanelVariant, Parallel, type Placement, Pulse, RGS_ERROR_KEYS, ReadoutControl, type ReadoutKind, type ReadoutOptions, type RealityCheckOptions, type Rect, type ResponsiveKey, type ResponsiveOverride, type RgsBetConfig, type RgsErrorCode, type RgsErrorOptions, type ScreenState, SelectControl, type SelectControlOptions, type SelectOption, Sequence, Signal, SliderControl, type SliderOptions, type SpecIssue, SpinControl, type SpinPress, type SpinSpec, Squish, type StateDef, type StateMap, StepperControl, type StepperOptions, type Subscribable, type Theme, type ThemeChoice, type ThemeIssue, type ThemeOverrides, type ThemePreset, ToggleControl, type ToggleOptions, type Transition, type Translator, TurboControl, type TurboOptions, type TurboSpec, Turn, type UISpec, ValueDisplay, type ValueDisplayOptions, type ViewInspect, applyJurisdiction, breakpointFor, buildBetLadder, buildBlocks, buildPanel, buttonBlocks, clampBet, clampDecimals, clampDigits, clampMinDigits, composeMenu, computeScreen, createUI, defaultHudSpec, defaultLayout, defaultLayoutConfig, defaultTheme, defineUI, dictionary, displayDigits, effect, errorBlocks, extendTheme, formatAmount, installResponsive, integerDigits, isSafeColor, isSocialCurrency, landscapeDefaultLayouts, openuiDefaults, openuiSocialDefaults, portraitDefaultLayouts, resolveCurrency, resolvePlacement, resolveTheme, resolveTurboModes, safeAmount, sanitizeThemeOverrides, themePresets, validateSpec, valueFitMaxWidth };
+export { API_AMOUNT_DIVISOR, type Anchor, AutoplayControl, type AutoplayLimits, type AutoplayMode, type AutoplayOptions, BLOCK_KINDS, type BlockFactory, type BlockSpec, type Breakpoint, type BuiltPanel, ButtonControl, type ButtonOptions, CURRENCY_TABLE, CardControl, type CardOptions, type ComposeMenuOptions, Control, type ControlOptions, type ControlOverride, ControlRegistry, type ControlSnapshot, type CurrencyInfo, type CurrencySpec, DEFAULT_MENU_TITLES, DEFAULT_NOTICE_ACTION, type DeepPartial, DictionaryTranslator, type Dispose, EventBus, EventLog, type EventLogOptions, type EventMap, Fade, type ForbiddenMatch, type HostHooks, type JurisdictionConfig, type KnownControlId, LOCALE_LABELS, type LayoutConfig, type LayoutSpec, type LoggedEvent, type MenuSpec, type NoticeAction, type NoticeOptions, OpenUI, type OpenUIEvents, type OpenUIOptions, type Orientation, PanelControl, type PanelOptions, type PanelSpec, type PanelVariant, Parallel, type Placement, Pulse, RGS_ERROR_KEYS, ReadoutControl, type ReadoutKind, type ReadoutOptions, type RealityCheckOptions, type Rect, type ResponsiveKey, type ResponsiveOverride, type RgsBetConfig, type RgsErrorCode, type RgsErrorOptions, type ScreenState, SelectControl, type SelectControlOptions, type SelectOption, Sequence, Signal, SliderControl, type SliderOptions, type SocialPhraseIssue, type SpecIssue, SpinControl, type SpinPress, type SpinSpec, Squish, type StageRect, type StateDef, type StateMap, StepperControl, type StepperOptions, type Subscribable, type Theme, type ThemeChoice, type ThemeIssue, type ThemeOverrides, type ThemePreset, ToggleControl, type ToggleOptions, type Transition, type Translator, TurboControl, type TurboOptions, type TurboSpec, Turn, type UISpec, ValueDisplay, type ValueDisplayOptions, type ViewInspect, applyJurisdiction, breakpointFor, buildBetLadder, buildBlocks, buildPanel, buttonBlocks, checkSocialPhrases, clampBet, clampDecimals, clampDigits, clampMinDigits, collectSocialCopy, composeMenu, computeScreen, createUI, defaultHudSpec, defaultLayout, defaultLayoutConfig, defaultTheme, defineUI, dictionary, displayDigits, effect, errorBlocks, extendTheme, findForbiddenPhrases, formatAmount, installResponsive, integerDigits, isSafeColor, isSocialCurrency, landscapeDefaultLayouts, openuiDefaults, openuiSocialDefaults, portraitDefaultLayouts, resolveCurrency, resolvePlacement, resolveTheme, resolveTurboModes, safeAmount, sanitizeThemeOverrides, themePresets, validateSpec, valueFitMaxWidth };

package/dist/index.d.ts

@@ -188,6 +188,13 @@ declare function extendTheme(base: Theme, patch: DeepPartial<Theme>): Theme;
 type Orientation = 'landscape' | 'portrait';
 /** A named device bucket. Config can target these to restyle per device. */
 type Breakpoint = 'mobile' | 'tablet' | 'desktop';
+/** The uniformly-scaled DESIGN FRAME ("stage") rect, in screen pixels. */
+interface StageRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 interface ScreenState {
     width: number;
     height: number;
@@ -196,6 +203,15 @@ interface ScreenState {
     breakpoint: Breakpoint;
     /** Multiply reference-px sizes by this to fit the current screen. */
     scale: number;
+    /**
+     * The reference design frame, scaled UNIFORMLY by `scale` and placed in the viewport
+     * (letterboxed by `stageAnchor` when the aspect ratio differs). Every control anchors
+     * to THIS rect — not the raw screen — so the whole HUD scales as one homogeneous unit
+     * and the relative gaps between controls never change with aspect ratio. At the
+     * reference resolution `stage` exactly equals the screen, so authored layouts are
+     * pixel-identical there.
+     */
+    stage: StageRect;
 }
 interface LayoutConfig {
     /** Reference design resolution for landscape / portrait. */
@@ -212,6 +228,14 @@ interface LayoutConfig {
         mobile: number;
         tablet: number;
     };
+    /**
+     * Where the uniformly-scaled design frame sits in the viewport when the aspect ratio
+     * doesn't match the reference (i.e. how the letterbox margins are distributed), as
+     * `[x, y]` factors in `0..1`. `[0.5, 1]` (default) = bottom-centre: the bottom bar
+     * always hugs the screen bottom and any extra vertical room opens ABOVE (the reel
+     * area, filled by the game); horizontal slack splits evenly. `[0.5, 0.5]` centres it.
+     */
+    stageAnchor: [number, number];
 }
 declare const defaultLayoutConfig: LayoutConfig;
 /** Classify the shorter edge into a named device bucket. Pure, total. */
@@ -236,7 +260,16 @@ interface Placement {
     /** Rotation in radians (resolved from `LayoutSpec.rotation`, which is degrees). */
     rotation: number;
 }
-/** Resolve a control's layout against the current screen. Pure math. */
+/**
+ * Resolve a control's layout against the current screen. Pure math.
+ *
+ * Anchors to the uniformly-scaled `screen.stage` frame — NOT the raw screen — so the
+ * whole HUD scales as one homogeneous unit: the gap between two controls is always a
+ * fixed fraction of the (uniformly-scaled) frame, never a function of the viewport's
+ * aspect ratio. That's what stops a growing value or a narrow window from letting
+ * controls drift into each other. At the reference resolution `stage` equals the
+ * screen, so authored offsets land pixel-identically.
+ */
 declare function resolvePlacement(spec: LayoutSpec, screen: ScreenState): Placement;
 
 /**
@@ -800,6 +833,10 @@ declare class ReadoutControl extends Control {
     readonly value: Signal<number>;
     /** Whether a `'duration'` readout is currently advancing. */
     readonly running: Signal<boolean>;
+    /** Accent emphasis: the renderer tints the value in the theme accent while on — for
+     *  a MODIFIED readout (e.g. net position while a bet boost is active). Mirrors
+     *  {@link ValueDisplay.emphasized}. */
+    readonly emphasized: Signal<boolean>;
     readonly kind: ReadoutKind;
     readonly label?: string;
     readonly decimals: number;
@@ -809,6 +846,8 @@ declare class ReadoutControl extends Control {
     constructor(opts: ReadoutOptions);
     /** Never-reject: malformed input keeps the last good value (P11). */
     set(v: number): void;
+    /** Accent-tint the value ("this readout is modified"). Strict boolean. */
+    setEmphasis(on: boolean): void;
     get(): number;
     setCurrency(spec: CurrencySpec): void;
     /** Advance an elapsed-time readout by `deltaSec` (the renderer calls this each frame). */
@@ -1224,6 +1263,9 @@ declare class OpenUI {
     readonly spin: SpinControl;
     readonly balance: ValueDisplay;
     readonly bet: ValueDisplay;
+    /** Bonus "total win" readout — shown in the buy-feature slot during a bonus/free-
+     *  spins round (the renderer swaps it for the buy button). Same money logic as `bet`. */
+    readonly totalWin: ValueDisplay;
     readonly settingsButton: ButtonControl;
     readonly settingsPanel: PanelControl;
     readonly musicSlider: SliderControl;
@@ -1440,11 +1482,13 @@ type BlockSpec = {
     id: string;
     label?: string;
     initial?: number;
+    hint?: string;
 } | {
     kind: 'toggle';
     id: string;
     label?: string;
     on?: boolean;
+    hint?: string;
 } | {
     kind: 'button';
     id: string;
@@ -1452,18 +1496,21 @@ type BlockSpec = {
     action?: 'closePanel' | 'openPanel' | 'emit';
     target?: string;
     role?: string;
+    hint?: string;
 } | {
     kind: 'select';
     id: string;
     label?: string;
     options: SelectOption[];
     index?: number;
+    hint?: string;
 } | {
     kind: 'stepper';
     id: string;
     label?: string;
     levels: number[];
     index?: number;
+    hint?: string;
 } | {
     kind: 'value';
     id: string;
@@ -1712,6 +1759,60 @@ declare function resolveTurboModes(modes: TurboSpec['modes']): string[];
 declare function defineUI(spec: UISpec): UISpec;
 declare function createUI(spec?: UISpec, hooks?: HostHooks): OpenUI;
 
+/**
+ * Social-mode FORBIDDEN-PHRASE checker (Charter B8/P11). Stake US social/sweepstakes
+ * jurisdiction restricts gambling wording; a game must not surface "bet", "pay(table)",
+ * "funds", "cash", etc. anywhere in its copy. This scans the ENGLISH strings a game
+ * ships (menu blocks, rules, section titles, control labels/hints, the `en` dictionary,
+ * the game name) and reports every restricted phrase with a compliant replacement, so
+ * the classic "we shipped a *paytable* while `pay` is banned" slips through no longer.
+ *
+ * It's a lint, not a gate — never throws; `createUI` runs it automatically in social
+ * mode and forwards findings to `HostHooks.onDataIssue` (+ a console warning), and a
+ * game's own test can call {@link checkSocialPhrases} directly.
+ *
+ * See Stake's "Jurisdiction Requirements → forbidden phrases" for the authoritative
+ * list; this covers the common roots and their recommended replacements.
+ */
+
+interface ForbiddenMatch {
+    /** The restricted root that matched ("pay*", "bet", "funds", …). */
+    term: string;
+    /** The recommended compliant replacement. */
+    replacement: string;
+}
+interface SocialPhraseIssue {
+    /** Where the copy lives (e.g. `menu.rules[3]`, `locale.en["Paytable"]`). */
+    source: string;
+    /** The offending string. */
+    text: string;
+    /** Every restricted phrase found in it. */
+    matches: ForbiddenMatch[];
+}
+/** Every restricted phrase in `text` (empty when clean). Pure + total. */
+declare function findForbiddenPhrases(text: string): ForbiddenMatch[];
+/** A collected string. `text` is the base English (what renders with no social
+ *  override); `key` is the i18n key used to look up a social override — it defaults
+ *  to `text`, since a game's menu/rules copy doubles as its own key. */
+type Entry = {
+    source: string;
+    text: string;
+    key?: string;
+};
+/** Collect every English string a spec ships (menu/rules blocks, titles, labels+hints,
+ *  game name, the `en` dictionary) with a source path — the input to {@link checkSocialPhrases}. */
+declare function collectSocialCopy(spec: UISpec): Entry[];
+/**
+ * Scan a spec's English copy AS IT RENDERS IN SOCIAL MODE and return every restricted
+ * phrase. Each collected string is first resolved through the social dictionary
+ * (`locale.socialMessages.en` → built-in `openuiSocialDefaults` → the base text) —
+ * exactly like the translator does — so a game that already swaps "bet"/"pay(table)"
+ * for compliant wording in social mode is NOT flagged, while a phrase with NO social
+ * override (the classic slipped-through "paytable") IS. English by design: the check
+ * targets the base `en` copy that every jurisdiction review starts from.
+ */
+declare function checkSocialPhrases(spec: UISpec): SocialPhraseIssue[];
+
 /**
  * The responsive layer: re-apply per-device / per-orientation control overrides
  * every time the screen bucket changes. Pure assembly over the existing layout
@@ -1772,36 +1873,49 @@ declare class EventLog {
 /**
  * Currency display metadata + a pure formatter (Charter P11: data, not code).
  *
- * Stake Engine supports 35+ currencies — fiat (incl. zero-decimal JPY/KRW/VND…),
- * crypto, and the social coins XGC/XSC (shown as "GC"/"SC", never locale-formatted
- * as fiat). A host shouldn't have to hand-tune decimals for each, so this maps a
- * code → its display precision; anything unknown defaults to 2 (the common case).
- * The UI computes no money — it only formats what the game sets.
+ * This is the **Stake Engine currency table**: every code Stake supports, mapped to
+ * its display SYMBOL, minor-unit decimals, and symbol side (before/after the number).
+ * A game shouldn't hand-tune any of this — it either passes a full `CurrencySpec`, or
+ * just the CODE (`currency: 'CNY'`) and gets the Stake formatting for free
+ * ("I use the Stake currency formatter"). Unknown codes fall back to a 2-decimal,
+ * code-suffix spec so nothing ever breaks. The UI computes no money — it only formats
+ * what the game sets.
  */
 
 interface CurrencyInfo {
-    /** Fractional digits to show (JPY/KRW = 0, USD = 2, BTC = 8). */
+    /** The glyph shown to the player ("$", "CN¥", "GC"). */
+    symbol: string;
+    /** Fractional digits to show (JPY/KRW/IDR = 0, USD = 2, BTC = 8). */
     decimals: number;
-    /** Display code shown to the player when it differs from the code (XGC → "GC"). */
-    display?: string;
-    /** A social / sweepstakes coin — never formatted as a fiat currency. */
+    /** Symbol AFTER the number ("10,00 zł") rather than before ("$10.00"). Default before. */
+    symbolAfter?: boolean;
+    /** A social / sweepstakes coin (Gold Coins / Stake Cash) — never fiat wording. */
     social?: boolean;
 }
-/** Code → display info. Unknown codes fall back to 2 decimals (see {@link resolveCurrency}). */
+/**
+ * The Stake Engine supported-currency matrix (symbol · decimals · placement), 1:1 with
+ * the platform's `CurrencyMeta`. Symbol placement: prefix by default, SUFFIX for the
+ * few that render after the amount (DKK/PLN/VND/CLP/ARS/PEN). Crypto is included for
+ * completeness (8-dp with a symbol) so high-precision balances also format right.
+ */
 declare const CURRENCY_TABLE: Readonly<Record<string, CurrencyInfo>>;
-/** True if `code` is a Stake social/sweepstakes coin (display "GC"/"SC"). */
+/** True if `code` is a Stake social/sweepstakes coin (displayed "GC"/"SC"). */
 declare function isSocialCurrency(code: string): boolean;
 /**
- * Resolve a currency code to a complete, display-ready {@link CurrencySpec}: fills
- * decimals from the table (default 2) and maps social coins to their display code.
- * Anything in `overrides` wins, so a game can still hand-tune. Never throws.
+ * Resolve a currency code to a complete, display-ready {@link CurrencySpec} using the
+ * Stake table: fills the SYMBOL (rendered tight, `display:'symbol'`), its side
+ * (`position`), and the minor-unit `decimals`. Anything in `overrides` wins so a game
+ * can still hand-tune (e.g. force more decimals for sub-cent payouts). An unknown code
+ * degrades to a 2-decimal code-suffix spec. Never throws.
  */
 declare function resolveCurrency(code: string, overrides?: Partial<CurrencySpec>): CurrencySpec;
 /**
  * Format an amount (major units) per a {@link CurrencySpec}: grouped integer part,
- * fixed decimals, the code on the configured side. `signed` adds an explicit "+"
- * for non-negative values (negatives always show "-") — used by the net-position
- * readout. Pure + total: a malformed number renders as "0".
+ * fixed decimals, and the affix on the configured side. When `display:'symbol'` (and a
+ * symbol is set) the SYMBOL sits tight against the number (`CN¥1,234.56` · `1.234,56 zł`);
+ * otherwise the ISO code is spaced (`1,234.56 USD`). `signed` adds an explicit "+" for
+ * non-negative values (used by the net-position readout). Pure + total: a malformed
+ * number renders as "0".
  */
 declare function formatAmount(value: number, spec: CurrencySpec, opts?: {
     signed?: boolean;
@@ -1834,4 +1948,4 @@ declare function buildBetLadder(cfg: RgsBetConfig, divisor?: number): {
 /** Clamp a stake (major units) to the RGS min/max and snap to `stepBet`. Pure. */
 declare function clampBet(amount: number, cfg: RgsBetConfig, divisor?: number): number;
 
-export { API_AMOUNT_DIVISOR, type Anchor, AutoplayControl, type AutoplayLimits, type AutoplayMode, type AutoplayOptions, BLOCK_KINDS, type BlockFactory, type BlockSpec, type Breakpoint, type BuiltPanel, ButtonControl, type ButtonOptions, CURRENCY_TABLE, CardControl, type CardOptions, type ComposeMenuOptions, Control, type ControlOptions, type ControlOverride, ControlRegistry, type ControlSnapshot, type CurrencyInfo, type CurrencySpec, DEFAULT_MENU_TITLES, DEFAULT_NOTICE_ACTION, type DeepPartial, DictionaryTranslator, type Dispose, EventBus, EventLog, type EventLogOptions, type EventMap, Fade, type HostHooks, type JurisdictionConfig, type KnownControlId, LOCALE_LABELS, type LayoutConfig, type LayoutSpec, type LoggedEvent, type MenuSpec, type NoticeAction, type NoticeOptions, OpenUI, type OpenUIEvents, type OpenUIOptions, type Orientation, PanelControl, type PanelOptions, type PanelSpec, type PanelVariant, Parallel, type Placement, Pulse, RGS_ERROR_KEYS, ReadoutControl, type ReadoutKind, type ReadoutOptions, type RealityCheckOptions, type Rect, type ResponsiveKey, type ResponsiveOverride, type RgsBetConfig, type RgsErrorCode, type RgsErrorOptions, type ScreenState, SelectControl, type SelectControlOptions, type SelectOption, Sequence, Signal, SliderControl, type SliderOptions, type SpecIssue, SpinControl, type SpinPress, type SpinSpec, Squish, type StateDef, type StateMap, StepperControl, type StepperOptions, type Subscribable, type Theme, type ThemeChoice, type ThemeIssue, type ThemeOverrides, type ThemePreset, ToggleControl, type ToggleOptions, type Transition, type Translator, TurboControl, type TurboOptions, type TurboSpec, Turn, type UISpec, ValueDisplay, type ValueDisplayOptions, type ViewInspect, applyJurisdiction, breakpointFor, buildBetLadder, buildBlocks, buildPanel, buttonBlocks, clampBet, clampDecimals, clampDigits, clampMinDigits, composeMenu, computeScreen, createUI, defaultHudSpec, defaultLayout, defaultLayoutConfig, defaultTheme, defineUI, dictionary, displayDigits, effect, errorBlocks, extendTheme, formatAmount, installResponsive, integerDigits, isSafeColor, isSocialCurrency, landscapeDefaultLayouts, openuiDefaults, openuiSocialDefaults, portraitDefaultLayouts, resolveCurrency, resolvePlacement, resolveTheme, resolveTurboModes, safeAmount, sanitizeThemeOverrides, themePresets, validateSpec, valueFitMaxWidth };
+export { API_AMOUNT_DIVISOR, type Anchor, AutoplayControl, type AutoplayLimits, type AutoplayMode, type AutoplayOptions, BLOCK_KINDS, type BlockFactory, type BlockSpec, type Breakpoint, type BuiltPanel, ButtonControl, type ButtonOptions, CURRENCY_TABLE, CardControl, type CardOptions, type ComposeMenuOptions, Control, type ControlOptions, type ControlOverride, ControlRegistry, type ControlSnapshot, type CurrencyInfo, type CurrencySpec, DEFAULT_MENU_TITLES, DEFAULT_NOTICE_ACTION, type DeepPartial, DictionaryTranslator, type Dispose, EventBus, EventLog, type EventLogOptions, type EventMap, Fade, type ForbiddenMatch, type HostHooks, type JurisdictionConfig, type KnownControlId, LOCALE_LABELS, type LayoutConfig, type LayoutSpec, type LoggedEvent, type MenuSpec, type NoticeAction, type NoticeOptions, OpenUI, type OpenUIEvents, type OpenUIOptions, type Orientation, PanelControl, type PanelOptions, type PanelSpec, type PanelVariant, Parallel, type Placement, Pulse, RGS_ERROR_KEYS, ReadoutControl, type ReadoutKind, type ReadoutOptions, type RealityCheckOptions, type Rect, type ResponsiveKey, type ResponsiveOverride, type RgsBetConfig, type RgsErrorCode, type RgsErrorOptions, type ScreenState, SelectControl, type SelectControlOptions, type SelectOption, Sequence, Signal, SliderControl, type SliderOptions, type SocialPhraseIssue, type SpecIssue, SpinControl, type SpinPress, type SpinSpec, Squish, type StageRect, type StateDef, type StateMap, StepperControl, type StepperOptions, type Subscribable, type Theme, type ThemeChoice, type ThemeIssue, type ThemeOverrides, type ThemePreset, ToggleControl, type ToggleOptions, type Transition, type Translator, TurboControl, type TurboOptions, type TurboSpec, Turn, type UISpec, ValueDisplay, type ValueDisplayOptions, type ViewInspect, applyJurisdiction, breakpointFor, buildBetLadder, buildBlocks, buildPanel, buttonBlocks, checkSocialPhrases, clampBet, clampDecimals, clampDigits, clampMinDigits, collectSocialCopy, composeMenu, computeScreen, createUI, defaultHudSpec, defaultLayout, defaultLayoutConfig, defaultTheme, defineUI, dictionary, displayDigits, effect, errorBlocks, extendTheme, findForbiddenPhrases, formatAmount, installResponsive, integerDigits, isSafeColor, isSocialCurrency, landscapeDefaultLayouts, openuiDefaults, openuiSocialDefaults, portraitDefaultLayouts, resolveCurrency, resolvePlacement, resolveTheme, resolveTurboModes, safeAmount, sanitizeThemeOverrides, themePresets, validateSpec, valueFitMaxWidth };