@idosgames/react 0.2.11 → 0.4.0

package/dist/ui/index.d.ts

@@ -0,0 +1,918 @@
+import { ReactNode, CSSProperties, MouseEvent } from 'react';
+import { IDosGamesClient, ResourceConsume, ResourceGrant } from '@idosgames/core';
+
+/** Interface sound events. Components of the kit play theirs by themselves. */
+declare const UI_SOUND_EVENTS: readonly ["click", "tab", "open", "close", "reward", "coin", "purchase", "claim", "error", "notify", "lootbox", "levelUp", "countTick"];
+type UiSoundEvent = (typeof UI_SOUND_EVENTS)[number];
+/** One synthesized note: frequency (Hz), start and length (seconds), waveform, loudness, glide. */
+interface SynthNote {
+    freq: number;
+    /** Start, seconds from the moment the sound is played. */
+    at?: number;
+    /** Length, seconds. */
+    dur: number;
+    wave?: "sine" | "square" | "triangle" | "sawtooth";
+    /** 0..1, before the master volume. */
+    gain?: number;
+    /** Glide to this frequency by the end of the note. */
+    slideTo?: number;
+}
+/** A burst of filtered noise — the "whoosh" and "shine" parts. */
+interface SynthNoise {
+    at?: number;
+    dur: number;
+    gain?: number;
+    /** Band-pass centre, Hz. */
+    freq?: number;
+    /** Glide of the band-pass centre by the end. */
+    slideTo?: number;
+}
+interface SynthPreset {
+    notes?: SynthNote[];
+    noise?: SynthNoise[];
+}
+/**
+ * What plays on an event:
+ *  - the name of a built-in preset ("coin"), possibly of ANOTHER event — `click: "tab"`;
+ *  - your own synthesized preset;
+ *  - a file (`{ url }`, any format the browser plays) with its own volume;
+ *  - `false` — silence for this event.
+ */
+type UiSoundSpec = UiSoundEvent | {
+    synth: SynthPreset;
+    volume?: number;
+} | {
+    url: string;
+    volume?: number;
+} | false;
+interface UiThemeConfig {
+    /** Background gradient of full screens, top → bottom. */
+    bgTop: string;
+    bgBottom: string;
+    panel: string;
+    panelDeep: string;
+    panelEdge: string;
+    text: string;
+    textDim: string;
+    gold: string;
+    goldDeep: string;
+    green: string;
+    greenDeep: string;
+    blue: string;
+    blueDeep: string;
+    red: string;
+    redDeep: string;
+    shadow: string;
+    /** Dim of the screen behind a popup. */
+    backdrop: string;
+    /** Text colour on a filled button of each tone. */
+    onGreen: string;
+    onGold: string;
+    onBlue: string;
+    onRed: string;
+    /** `text-shadow` of text on screens and panels: the casual dark outline on light text, none on dark. */
+    textOutline: string;
+    /** Thin line/border on a panel (dividers, outlines of chips). */
+    line: string;
+    /** Recessed background of counters, round icon buttons. */
+    well: string;
+    /** Softer recess: tab strips, progress-bar tracks. */
+    wellSoft: string;
+    /** Inner shadow of a recess. */
+    wellShadow: string;
+    /** The hard edge under buttons and active tabs (the "3D" press). */
+    edge: string;
+    /** Soft glow at the top of full screens. */
+    glow: string;
+    /** `box-shadow` of panels and cards: a hard casual drop on dark themes, a soft one on light. */
+    panelShadow: string;
+    /** Corner radius of panels and cards, px. */
+    radius: number;
+    /** Corner radius of buttons, px. */
+    buttonRadius: number;
+    font: string;
+    /** Frame colours by item rarity id; an unknown rarity uses `Common`. */
+    rarity: Record<string, string>;
+}
+interface UiMotionConfig {
+    /** false — no animations at all, only instant appearance. */
+    enabled: boolean;
+    /** 1 = default; 2 = twice as fast; 0.5 = twice as slow. */
+    speed: number;
+    /** Strength of overshoots and bounces: 0 = none, 1 = default, 2 = cartoonish. */
+    intensity: number;
+    /** Reward icons fly to the balance counters. */
+    rewardFlight: boolean;
+    /** Particle bursts on claims and purchases. */
+    particles: boolean;
+    /** Lists appear item by item. */
+    stagger: boolean;
+    /** Follow the system "reduce motion" setting. */
+    respectReducedMotion: boolean;
+}
+interface UiSoundConfig {
+    enabled: boolean;
+    /** Master volume 0..1 (the player's own volume multiplies it). */
+    volume: number;
+    /** Per event; a missing event plays its built-in preset. */
+    events: Partial<Record<UiSoundEvent, UiSoundSpec>>;
+}
+interface UiKitConfig {
+    theme: UiThemeConfig;
+    motion: UiMotionConfig;
+    sound: UiSoundConfig;
+}
+/** What `src/ui.config.ts` exports: any subset, deep. */
+type UiKitConfigInput = {
+    theme?: Partial<Omit<UiThemeConfig, "rarity">> & {
+        rarity?: Record<string, string>;
+    };
+    motion?: Partial<UiMotionConfig>;
+    sound?: Partial<Omit<UiSoundConfig, "events">> & {
+        events?: Partial<Record<UiSoundEvent, UiSoundSpec>>;
+    };
+};
+/** Typed helper for `src/ui.config.ts`: `export default defineUiConfig({ … })`. */
+declare function defineUiConfig(config: UiKitConfigInput): UiKitConfigInput;
+/** The default look: the casual mobile-game style of the Board Survival Unity project. */
+declare const DEFAULT_UI_CONFIG: UiKitConfig;
+/**
+ * Defaults ← project config, field by field. Out-of-range numbers are clamped (speed 0.1..5,
+ * intensity 0..3, volume 0..1) — a typo must not freeze or deafen the whole interface.
+ */
+declare function resolveUiConfig(input?: UiKitConfigInput | null): UiKitConfig;
+/** Durations (ms) of the three animation speeds, after the speed multiplier. 0 when motion is off. */
+declare function motionDurations(motion: UiMotionConfig, reduced: boolean): {
+    fast: number;
+    normal: number;
+    slow: number;
+};
+/** The player's own settings (profile screen), kept per device. They multiply the project's config. */
+interface UiPlayerPrefs {
+    muted: boolean;
+    /** 0..1, multiplies the config volume. */
+    volume: number;
+    /** The player asked for less motion. */
+    reducedMotion: boolean;
+}
+declare const DEFAULT_PLAYER_PREFS: UiPlayerPrefs;
+/** Reads stored prefs; anything unreadable falls back to the defaults. */
+declare function parsePlayerPrefs(raw: string | null | undefined): UiPlayerPrefs;
+/** Effective loudness of one sound: config × player × per-sound volume; 0 when muted or disabled. */
+declare function effectiveVolume(sound: UiSoundConfig, prefs: UiPlayerPrefs, specVolume?: number): number;
+
+/** Built-in presets, one per event. Short and soft — interface sounds must not tire the ear. */
+declare const SOUND_PRESETS: Record<UiSoundEvent, SynthPreset>;
+/** What an event resolves to after the project's config: a preset, a file, or nothing. */
+type ResolvedSound = {
+    kind: "synth";
+    preset: SynthPreset;
+    volume: number;
+} | {
+    kind: "file";
+    url: string;
+    volume: number;
+} | {
+    kind: "none";
+};
+/**
+ * Resolves an event through the config: a preset name may point at ANOTHER event's preset
+ * (`click: "tab"`), one hop only — a loop of names ends in the built-in preset of the event.
+ */
+declare function resolveSound(event: UiSoundEvent, sound: UiSoundConfig): ResolvedSound;
+declare class UiSoundEngine {
+    private config;
+    private prefs;
+    private ctx;
+    private unlocked;
+    private readonly buffers;
+    private readonly lastPlayed;
+    private detach;
+    constructor(config: UiSoundConfig, prefs: UiPlayerPrefs);
+    update(config: UiSoundConfig, prefs: UiPlayerPrefs): void;
+    /** Listens for the first gesture that allows audio. Safe to call more than once. */
+    attach(target?: EventTarget): void;
+    dispose(): void;
+    play(event: UiSoundEvent): void;
+    private context;
+    private playSynth;
+    private playFile;
+}
+
+type NotificationLevel = "info" | "success" | "warning" | "error" | "reward";
+interface NotificationAction {
+    id?: string;
+    label: string;
+    primary?: boolean;
+    openFeature?: string;
+    onPress?: () => void;
+}
+interface NotificationInput {
+    level?: NotificationLevel;
+    title?: string;
+    message?: string;
+    icon?: string;
+    image?: string;
+    source?: string | null;
+    key?: string;
+    duration?: number;
+    actions?: NotificationAction[];
+}
+/** What the kit can say about a `source`: its name and icon, and how to open it. */
+interface NotificationSource {
+    label: string;
+    icon?: string;
+    open?: () => void;
+}
+interface ShownNotification {
+    readonly id: string;
+    readonly kind: "toast" | "alert";
+    readonly level: NotificationLevel;
+    readonly input: NotificationInput;
+    /** Identical toasts merged into this one. */
+    readonly count: number;
+    /** Bumps when the content is replaced (same key) or merged — the view restarts its timer. */
+    readonly revision: number;
+}
+/** How long a toast stays by default, ms: errors and warnings long enough to be read. */
+declare const TOAST_DURATION: Record<NotificationLevel, number>;
+declare class NotificationStore {
+    private toastList;
+    private alertQueue;
+    private readonly waiting;
+    private readonly listeners;
+    private nextId;
+    private player;
+    private resolver;
+    /** Toasts on screen, newest last. */
+    get toasts(): readonly ShownNotification[];
+    /** The alert on screen (the head of the queue) and how many wait behind it. */
+    get currentAlert(): ShownNotification | null;
+    get queued(): number;
+    readonly subscribe: (listener: () => void) => (() => void);
+    /** The kit plays each notification's sound through this. */
+    setPlayer(play: ((event: UiSoundEvent) => void) | null): void;
+    /** The host tells the kit what a `source` id is (the feature registry). */
+    setSourceResolver(resolve: ((id: string) => NotificationSource | null) | null): void;
+    source(id: string | null | undefined): NotificationSource | null;
+    toast(input: NotificationInput | string): string;
+    alert(input: NotificationInput): Promise<string | null>;
+    /** Close a toast, or an alert with the pressed action (`null` — closed without choosing). */
+    dismiss(id: string, actionId?: string | null): void;
+    /** Everything away (logout): waiting alerts resolve with `null`. */
+    clear(): void;
+    /** The sound of a level (the view plays an alert's when it comes on screen). */
+    play(level: NotificationLevel): void;
+    private emit;
+}
+declare function createNotificationStore(): NotificationStore;
+
+type ResourceKind = "currency" | "item" | "token" | "other";
+interface ResourceLine {
+    kind: ResourceKind;
+    /**
+     * Currency id or item id. For a token — "{System}:{entity}": "TimedEvent:star_festival",
+     * "Season:main", "Quest:daily", "Leaderboard:weekly" (see `tokenName` / `tokenGlyph`).
+     */
+    id: string;
+    amount: number;
+}
+type BundleEntry = {
+    Type?: string | null;
+    CurrencyID?: string | null;
+    ItemID?: string | null;
+    Amount?: number | null;
+} | null;
+/** An event token of a bundle; a server response adds what was actually applied (`Applied`, after caps). */
+type BundleToken = {
+    Address?: {
+        Type?: string | null;
+        EntityID?: string | null;
+    } | null;
+    Amount?: number | null;
+    Applied?: number | null;
+} | null;
+type Bundle = {
+    Entries?: BundleEntry[] | null;
+    EventTokens?: BundleToken[] | null;
+} | null | undefined;
+/**
+ * Lines of one bundle (`{ Entries, EventTokens }`), repeats merged, non-positive amounts dropped.
+ * Event tokens (event stars, season status, quest and rating points) are lines too: a reward that
+ * pays them must say so, otherwise the player gets them without ever seeing it.
+ */
+declare function bundleLines(bundle: Bundle): ResourceLine[];
+/** Token system and entity of a token line: "Season:main" → { system: "Season", entity: "main" }. */
+declare function tokenParts(line: ResourceLine): {
+    system: string;
+    entity: string;
+};
+/** Glyph of a token line: event stars, season trophy, quest points, rating crown. */
+declare function tokenGlyph(line: ResourceLine): string;
+/**
+ * Name of a token line. An event's token carries the publisher's own name ("Festival stars") in the
+ * title config; the other systems have none, so the kit names them. `client` null → the kit's word.
+ */
+declare function tokenName(line: ResourceLine, client: IDosGamesClient | null): string;
+/** Merges repeated lines of the same resource: a bundle may list one currency twice. */
+declare function mergeLines(lines: ResourceLine[]): ResourceLine[];
+/** What a grant gives (the Standard bundle — premium tiers are the server's business). */
+declare function grantLines(grant: ResourceGrant | null | undefined): ResourceLine[];
+/** What a price costs. Empty = free. */
+declare function costLines(cost: ResourceConsume | null | undefined): ResourceLine[];
+/** Lines of what a server response granted (`data.Resources.Grant`), when it reports them. */
+declare function grantedBy(data: unknown): ResourceLine[];
+/** Whether the player's balances cover a price (items are the server's check). */
+declare function canAfford(price: ResourceLine[], balances: Record<string, {
+    Amount?: number;
+} | null | undefined> | null | undefined): boolean;
+/** 1234 → "1 234", 1_250_000 → "1.25M" — balances must fit a chip. */
+declare function formatAmount(value: number): string;
+/** Countdown "3h 05m" / "12m 09s" / "2d 4h" to a server timestamp, from `nowMs` (server-corrected). */
+declare function countdown(targetUtc: string | null | undefined, nowMs: number): string | null;
+/**
+ * Three layouts, by the width of the screen's OWN box (not the window — in a mix it sits beside a
+ * sidebar or under a HUD): phone < 640px, tablet < 1024px, desktop from 1024px.
+ */
+type Layout = "phone" | "tablet" | "desktop";
+declare const TABLET_MIN_PX = 640;
+declare const DESKTOP_MIN_PX = 1024;
+declare function layoutFor(widthPx: number): Layout;
+/**
+ * A section of the title configuration. `getSection` holds only what a feature fetched on its own
+ * (GetDefinitions); the full config the client loads at sign-in lives in `titlePublicConfiguration`.
+ * Reading only the first left screens empty on titles that had everything (found 27.09.2026).
+ */
+declare function configSection<T>(client: IDosGamesClient, key: string): T | undefined;
+interface ItemDefinitionView {
+    ItemID?: string;
+    CatalogID?: string;
+    DisplayName?: string | null;
+    Description?: string | null;
+    ImagePath?: string | null;
+    Tags?: string[] | null;
+    ItemClass?: string | null;
+    IsStackable?: boolean;
+    Metadata?: {
+        RarityID?: string | null;
+    } | null;
+}
+interface ItemSection {
+    Catalogs?: Record<string, {
+        Items?: Record<string, ItemDefinitionView | null> | null;
+    } | null> | null;
+}
+interface CurrencySection {
+    VirtualCurrencies?: Record<string, {
+        CurrencyID?: string;
+        DisplayName?: string | null;
+        ImagePath?: string | null;
+    } | null> | null;
+}
+/** All item definitions of the title, across catalogs, by item id. */
+declare function itemDefinitions(section: ItemSection | undefined): Map<string, ItemDefinitionView>;
+declare const RARITY_ORDER: string[];
+/** 0 = rarest. Unknown rarities sort last. */
+declare function rarityRank(rarity: string | null | undefined): number;
+/** Group items by `group`, keeping the order of first appearance. */
+declare function groupBy<T>(items: readonly T[], key: (item: T) => string): Array<{
+    key: string;
+    items: T[];
+}>;
+
+interface Point {
+    x: number;
+    y: number;
+}
+interface Flight {
+    key: number;
+    line: ResourceLine;
+    /** Layer-relative, px. */
+    from: Point;
+    to: Point;
+    delayMs: number;
+    durationMs: number;
+    /** The counter this icon flies to (its data-resource-counter value). */
+    target: string;
+}
+interface Burst {
+    key: number;
+    at: Point;
+}
+type Listener = () => void;
+/** How many icons fly for an amount: a few for small rewards, never a swarm. */
+declare function iconsFor(amount: number): number;
+/** The counter an icon of this line flies to, in order of preference. */
+declare function counterKeys(line: ResourceLine): string[];
+declare class FxStore {
+    private listeners;
+    private nextKey;
+    private motion;
+    private player;
+    private layerEl;
+    /** In-flight icons per counter. */
+    private readonly holds;
+    /** Counters held from the moment a reward was celebrated until its icons take off. */
+    private readonly reserved;
+    flights: Flight[];
+    bursts: Burst[];
+    /** Bumps on every change — the snapshot `useFx` compares. */
+    version: number;
+    subscribe: (listener: Listener) => (() => void);
+    setMotion(motion: UiMotion): void;
+    setPlayer(play: (event: UiSoundEvent) => void): void;
+    setLayer(el: HTMLElement | null): void;
+    /** Icons still flying to this counter (or about to — a reward being celebrated). */
+    holding(target: string): number;
+    /**
+     * Holds the balance counters of a reward the moment it is celebrated. The server has already
+     * answered and the state already has the new balance — without this the number would jump while
+     * the "You got" popup is still open, before a single coin flew.
+     */
+    reserve(lines: ResourceLine[]): void;
+    /** Drops what `reserve` held and no flight took over (no counter on screen, flights off). */
+    release(lines: ResourceLine[]): void;
+    /**
+     * Sends reward icons from `origin` (a popup's icon, the claim button) to their counters. Lines
+     * without a counter on screen, or with flights switched off, are skipped — the counter then
+     * simply updates when the state does.
+     */
+    fly(lines: ResourceLine[], origin: (line: ResourceLine) => DOMRect | null): void;
+    /** One icon landed. The last one of its counter releases it and bumps it. */
+    arrive(key: number): void;
+    /** A burst of particles around an element (claims, purchases). */
+    burst(el: Element | null | undefined): void;
+    private changed;
+}
+
+interface UiMotion {
+    /** Animations on (config on, system and player did not ask for less motion). */
+    on: boolean;
+    durations: {
+        fast: number;
+        normal: number;
+        slow: number;
+    };
+    intensity: number;
+    rewardFlight: boolean;
+    particles: boolean;
+    stagger: boolean;
+}
+interface CelebrateOptions {
+    /** Title of the popup (default "You got"). */
+    title?: string;
+    /** Called after the popup closed and the rewards flew away. */
+    onDone?: () => void;
+    /** Sound of the popup (default "reward"). */
+    sound?: UiSoundEvent;
+}
+interface UiKitValue {
+    config: UiKitConfig;
+    prefs: UiPlayerPrefs;
+    setPrefs(patch: Partial<UiPlayerPrefs>): void;
+    motion: UiMotion;
+    play(event: UiSoundEvent): void;
+    /** Where popups render. `null` outside a provider (they render in place then). */
+    layer: HTMLElement | null;
+    fx: FxStore;
+    /** "You got" popup for what an action granted; rewards fly to their counters when it closes. */
+    celebrate(lines: ResourceLine[], options?: CelebrateOptions): void;
+    /**
+     * A short info/error/success toast — kept for the screens written before `notify`; new code uses
+     * `notify.toast({ level, title, message, … })`.
+     */
+    toast(message: string, kind?: "info" | "error" | "success"): void;
+    /** The app's notifications: toasts and alert windows (see ./notifications). */
+    notify: KitNotify;
+    /** Present when there is a provider — a module may render differently without one. */
+    provided: boolean;
+}
+declare function useUiKit(): UiKitValue;
+/** `play("coin")` — for sounds the kit's components do not already make. */
+declare function useSound(): (event: UiSoundEvent) => void;
+declare function useMotion(): UiMotion;
+/** The player's own settings (profile screen): mute, volume, less motion. */
+declare function usePlayerPrefs(): [
+    UiPlayerPrefs,
+    (patch: Partial<UiPlayerPrefs>) => void
+];
+/** Shows the shared "You got" popup; rewards fly to the balance counters when it closes. */
+declare function useCelebrate(): UiKitValue["celebrate"];
+declare function useToast(): UiKitValue["toast"];
+/**
+ * The app's notifications from a React screen — the same system as a module's `ctx.notifications`:
+ * `const notify = useNotify(); notify.toast({ level: "success", title: "Saved" })`,
+ * `await notify.alert({ level: "warning", title, message, actions: [...] })`.
+ */
+declare function useNotify(): KitNotify;
+/** `useNotify()` — the shape of the module contract's `AppNotifications`. */
+interface KitNotify {
+    toast(notification: NotificationInput | string): string;
+    alert(notification: NotificationInput): Promise<string | null>;
+    dismiss(id: string): void;
+}
+interface UiKitProviderProps {
+    /** What the project's `src/ui.config.ts` exports; omitted → the defaults. */
+    config?: UiKitConfigInput | null;
+    children: ReactNode;
+    /**
+     * Renders the popup of `celebrate()` and the toast. The host passes the kit's own (see
+     * KitOverlays); separated so the provider does not import every component.
+     */
+    overlays?: (state: KitOverlayState) => ReactNode;
+    /**
+     * The notification store. The host passes the one it also hands to the modules' `ctx.notifications`,
+     * so both reach the same toasts and queue; omitted → the provider keeps its own.
+     */
+    notifications?: NotificationStore;
+}
+/** What the overlays render: the pending celebration and toast. */
+interface KitOverlayState {
+    celebration: {
+        lines: ResourceLine[];
+        options?: CelebrateOptions;
+    } | null;
+    finishCelebration(): void;
+    /** Toasts and alert windows to draw. */
+    notifications: NotificationStore;
+}
+declare function UiKitProvider({ config: input, children, overlays, notifications, }: UiKitProviderProps): ReactNode;
+
+declare function renderKitOverlays(state: KitOverlayState): ReactNode;
+
+type UiLanguage = "en" | "ru";
+declare function pickLanguage(): UiLanguage;
+/**
+ * A module's string table: `const t = makeT(EN, RU)`, then `t("buy")`. The Russian table must have
+ * every key of the English one (the type says so), so a missing translation is a compile error.
+ */
+declare function makeT<K extends string>(en: Record<K, string>, ru: Record<K, string>, language?: UiLanguage): (key: K) => string;
+/**
+ * The word for a count, from a table entry of forms split by "|": English "lot|lots", Russian
+ * "лот|лота|лотов" (one / few / many — 1, 2–4, 5+). `plural(21, t("lots"))` → "лот".
+ */
+declare function plural(n: number, forms: string, language?: UiLanguage): string;
+declare const EN: {
+    readonly close: "Close";
+    readonly back: "Back";
+    readonly confirm: "Confirm";
+    readonly cancel: "Cancel";
+    readonly youGot: "You got";
+    readonly great: "Great!";
+    readonly loading: "Loading…";
+    readonly ok: "OK";
+    readonly loadingNamed: "Loading {name}…";
+    readonly stillLoading: "Still loading — the first start can take a little longer";
+    readonly retry: "Retry";
+    readonly error: "Something went wrong";
+    readonly notEnough: "Not enough resources";
+    readonly offline: "No connection. Retrying…";
+    readonly more: "More";
+    readonly menu: "Menu";
+    readonly nothingHere: "Nothing here yet";
+    readonly economy: "Economy";
+    readonly events: "Activities";
+    readonly social: "Social";
+    readonly profile: "Profile";
+    readonly other: "Other";
+    readonly free: "Free";
+    readonly claim: "Claim";
+    readonly claimAll: "Claim all";
+    readonly tokenEvent: "Event points";
+    readonly tokenSeason: "Season status";
+    readonly tokenQuest: "Quest points";
+    readonly tokenScore: "Rating points";
+};
+type UiStringKey = keyof typeof EN;
+/** Strings of the kit itself. */
+declare const uiT: (key: "close" | "claim" | "error" | "events" | "other" | "back" | "confirm" | "cancel" | "youGot" | "great" | "loading" | "ok" | "loadingNamed" | "stillLoading" | "retry" | "notEnough" | "offline" | "more" | "menu" | "nothingHere" | "economy" | "social" | "profile" | "free" | "claimAll" | "tokenEvent" | "tokenSeason" | "tokenQuest" | "tokenScore") => string;
+/** Turns a server error into words the player understands; long texts are cut. */
+declare function errorText(error: string | null | undefined): string;
+
+declare const GLYPHS: readonly ["coin", "gem", "potion", "scroll", "sword", "shield", "crown", "gift", "bag", "box", "trophy", "calendar", "star", "check", "lock", "shop", "chest", "quest", "user", "logout", "copy", "hero", "hammer", "market", "flame", "ticket", "friends", "chat", "link", "swords", "gear", "globe", "sound", "mute", "bell", "bulb", "menu", "close", "back", "plus", "energy", "heart", "offer", "clock", "trash", "edit"];
+type Glyph = (typeof GLYPHS)[number];
+declare function isGlyph(value: string): value is Glyph;
+/** Glyph for a currency id: gems for "premium-looking" ids, energy for dice/energy, coins for the rest. */
+declare function currencyGlyph(currencyID: string): Glyph;
+/** Glyph for an item by its tags or class (first known wins), else a box. */
+declare function itemGlyph(tags: readonly string[] | null | undefined, itemClass?: string | null): Glyph;
+/** A glyph by name, an image by URL ("https://…", "/…", "data:…"), or any other text (an emoji). */
+declare function Icon({ glyph, size, color, }: {
+    glyph: Glyph | string;
+    size?: number;
+    color?: string;
+}): ReactNode;
+
+/** CSS variables of a resolved config, to put on the kit root. */
+declare function themeVars(config: UiKitConfig, reducedMotion: boolean): CSSProperties;
+/** Shorthands for inline styles, so components never spell a variable name twice. */
+declare const v: {
+    readonly bgTop: "var(--idos-ui-bg-top)";
+    readonly bgBottom: "var(--idos-ui-bg-bottom)";
+    readonly panel: "var(--idos-ui-panel)";
+    readonly panelDeep: "var(--idos-ui-panel-deep)";
+    readonly panelEdge: "var(--idos-ui-panel-edge)";
+    readonly text: "var(--idos-ui-text)";
+    readonly textDim: "var(--idos-ui-text-dim)";
+    readonly gold: "var(--idos-ui-gold)";
+    readonly goldDeep: "var(--idos-ui-gold-deep)";
+    readonly green: "var(--idos-ui-green)";
+    readonly greenDeep: "var(--idos-ui-green-deep)";
+    readonly blue: "var(--idos-ui-blue)";
+    readonly blueDeep: "var(--idos-ui-blue-deep)";
+    readonly red: "var(--idos-ui-red)";
+    readonly redDeep: "var(--idos-ui-red-deep)";
+    readonly shadow: "var(--idos-ui-shadow)";
+    readonly backdrop: "var(--idos-ui-backdrop)";
+    readonly onGreen: "var(--idos-ui-on-green)";
+    readonly onGold: "var(--idos-ui-on-gold)";
+    readonly onBlue: "var(--idos-ui-on-blue)";
+    readonly onRed: "var(--idos-ui-on-red)";
+    readonly onGreenOutline: "var(--idos-ui-on-green-outline)";
+    readonly onGoldOutline: "var(--idos-ui-on-gold-outline)";
+    readonly onBlueOutline: "var(--idos-ui-on-blue-outline)";
+    readonly onRedOutline: "var(--idos-ui-on-red-outline)";
+    readonly textOutline: "var(--idos-ui-text-outline)";
+    readonly line: "var(--idos-ui-line)";
+    readonly well: "var(--idos-ui-well)";
+    readonly wellSoft: "var(--idos-ui-well-soft)";
+    readonly wellShadow: "var(--idos-ui-well-shadow)";
+    readonly edge: "var(--idos-ui-edge)";
+    readonly glow: "var(--idos-ui-glow)";
+    readonly panelShadow: "var(--idos-ui-panel-shadow)";
+    readonly radius: "var(--idos-ui-radius)";
+    readonly buttonRadius: "var(--idos-ui-button-radius)";
+    readonly font: "var(--idos-ui-font)";
+    readonly fast: "var(--idos-ui-fast)";
+    readonly normal: "var(--idos-ui-normal)";
+    readonly slow: "var(--idos-ui-slow)";
+};
+/**
+ * Bold text in the theme's text colour with the casual "outline" for readability over art — the
+ * outline is a theme token (`textOutline`): on light text a dark outline, on dark text none, so a
+ * light theme's dark letters never get a dark double.
+ */
+declare const outlined: CSSProperties;
+/** The glossy card every panel uses. */
+declare const panel: CSSProperties;
+/** Full-screen background of a screen. */
+declare const screenBackground: string;
+/** A recessed chip/slot (balances, round icon buttons). */
+declare const well: CSSProperties;
+/** Easing with an overshoot — the "pop" of casual games. */
+declare const EASE_POP = "cubic-bezier(.2, .9, .3, 1.25)";
+declare const EASE_OUT = "cubic-bezier(.2, .8, .2, 1)";
+declare const EASE_IN = "cubic-bezier(.5, 0, .75, .2)";
+/**
+ * Keyframes and the few class-based effects inline styles cannot express. Overshoots are written as
+ * `calc(1 + X * var(--idos-ui-k))`, so `motion.intensity` 0 flattens them and 2 doubles them.
+ */
+declare const KIT_CSS = "\n@keyframes idos-pop-in { 0% { transform: scale(.7); opacity: 0 } 65% { transform: scale(calc(1 + .06 * var(--idos-ui-k, 1))); opacity: 1 } 100% { transform: scale(1); opacity: 1 } }\n@keyframes idos-pop-out { 0% { transform: scale(1); opacity: 1 } 30% { transform: scale(calc(1 + .03 * var(--idos-ui-k, 1))) } 100% { transform: scale(.75); opacity: 0 } }\n@keyframes idos-fade-in { from { opacity: 0 } to { opacity: 1 } }\n@keyframes idos-fade-out { from { opacity: 1 } to { opacity: 0 } }\n@keyframes idos-rise-in { from { transform: translateY(14px); opacity: 0 } to { transform: none; opacity: 1 } }\n@keyframes idos-drop-in { 0% { transform: translateY(-16px) scale(.97); opacity: 0 } 70% { transform: translateY(calc(2px * var(--idos-ui-k, 1))); opacity: 1 } 100% { transform: none; opacity: 1 } }\n@keyframes idos-drop-out { from { transform: none; opacity: 1 } to { transform: translateY(-10px) scale(.97); opacity: 0 } }\n@keyframes idos-timer { from { transform: scaleX(1) } to { transform: scaleX(0) } }\n@keyframes idos-sheet-in { 0% { transform: translateY(100%) } 75% { transform: translateY(calc(-2% * var(--idos-ui-k, 1))) } 100% { transform: none } }\n@keyframes idos-sheet-out { from { transform: none } to { transform: translateY(100%) } }\n@keyframes idos-window-in { from { transform: translateY(24px) scale(.98); opacity: 0 } to { transform: none; opacity: 1 } }\n@keyframes idos-window-out { from { transform: none; opacity: 1 } to { transform: translateY(24px) scale(.98); opacity: 0 } }\n@keyframes idos-bounce { 0%, 100% { transform: translateY(0) } 50% { transform: translateY(calc(-5px * var(--idos-ui-k, 1))) } }\n@keyframes idos-shine { 0% { transform: translateX(-120%) skewX(-20deg) } 60%, 100% { transform: translateX(220%) skewX(-20deg) } }\n@keyframes idos-spin { to { transform: rotate(360deg) } }\n@keyframes idos-glow { 0%, 100% { box-shadow: 0 0 0 0 transparent } 50% { box-shadow: 0 0 18px 4px color-mix(in srgb, var(--idos-ui-gold) 55%, transparent) } }\n@keyframes idos-pulse { 0%, 100% { transform: scale(1) } 50% { transform: scale(calc(1 + .18 * var(--idos-ui-k, 1))) } }\n@keyframes idos-bump { 0% { transform: scale(1) } 40% { transform: scale(calc(1 + .22 * var(--idos-ui-k, 1))) } 100% { transform: scale(1) } }\n@keyframes idos-shake { 0%, 100% { transform: rotate(0) } 20% { transform: rotate(calc(-9deg * var(--idos-ui-k, 1))) } 40% { transform: rotate(calc(8deg * var(--idos-ui-k, 1))) } 60% { transform: rotate(calc(-6deg * var(--idos-ui-k, 1))) } 80% { transform: rotate(calc(4deg * var(--idos-ui-k, 1))) } }\n@keyframes idos-star { 0% { transform: scale(0) rotate(-40deg) } 60% { transform: scale(calc(1 + .15 * var(--idos-ui-k, 1))) rotate(8deg) } 100% { transform: scale(1) rotate(0) } }\n@keyframes idos-rays { to { transform: rotate(360deg) } }\n.idos-press { transition: transform var(--idos-ui-fast) ease, filter var(--idos-ui-fast) ease; -webkit-tap-highlight-color: transparent; touch-action: manipulation }\n.idos-press:not(:disabled):hover { filter: brightness(1.07) }\n.idos-press:not(:disabled):active { transform: translateY(3px) scale(.96); filter: brightness(.95); transition-duration: 40ms }\n.idos-shine { position: relative; overflow: hidden }\n.idos-shine::after { content: \"\"; position: absolute; top: 0; bottom: 0; width: 40%; left: 0; pointer-events: none;\n  background: linear-gradient(90deg, transparent, rgba(255,255,255,.28), transparent);\n  animation: idos-shine calc(var(--idos-ui-slow) * 6) ease-in-out infinite }\n.idos-bounce { animation: idos-bounce calc(var(--idos-ui-slow) * 2.1) ease-in-out infinite }\n.idos-glow { animation: idos-glow calc(var(--idos-ui-slow) * 3) ease-in-out infinite }\n.idos-pulse { animation: idos-pulse calc(var(--idos-ui-slow) * 2) ease-in-out infinite }\n.idos-bump { animation: idos-bump var(--idos-ui-normal) ease-out }\n.idos-scroll { scrollbar-width: thin; scrollbar-color: var(--idos-ui-panel-edge) transparent; overscroll-behavior: contain }\n.idos-scroll::-webkit-scrollbar { width: 6px; height: 6px }\n.idos-scroll::-webkit-scrollbar-thumb { background: var(--idos-ui-panel-edge); border-radius: 3px }\n[data-idos-motion=\"off\"] .idos-shine::after, [data-idos-motion=\"off\"] .idos-bounce, [data-idos-motion=\"off\"] .idos-glow, [data-idos-motion=\"off\"] .idos-pulse, [data-idos-motion=\"off\"] .idos-bump { animation: none }\n";
+
+/** The layout for the element's current width, following it as it resizes. */
+declare function useLayout(ref: {
+    current: HTMLElement | null;
+}): Layout;
+/** Layout of the whole game (the kit layer covers it). */
+declare function useGameLayout(): Layout;
+/**
+ * Keeps something on screen until its exit animation has played: `open` false → `closing` true for
+ * the exit duration, then `mounted` false. With motion off the exit is instant.
+ */
+declare function usePresence(open: boolean, exitMs: number): {
+    mounted: boolean;
+    closing: boolean;
+};
+/** Ticks a number towards its new value — balances "count" like in the Unity HUD. */
+declare function useAnimatedNumber(target: number, durationMs?: number, onTick?: () => void): number;
+/**
+ * The value a counter shows: frozen while reward icons fly to it (so it ticks when they LAND), then
+ * animated to the real amount with a tick sound.
+ */
+declare function useCounterValue(counterKey: string, amount: number): number;
+interface Catalog {
+    items: Map<string, ItemDefinitionView>;
+    currencies: NonNullable<CurrencySection["VirtualCurrencies"]>;
+    /** The publisher's text through the title's localization, when it is a localization key. */
+    localize(text: string | null | undefined): string;
+    currencyName(id: string): string;
+    itemName(id: string): string;
+    /** Glyph or image for a resource line: the title's ImagePath when set, else a fitting glyph. */
+    iconOf(line: ResourceLine): Glyph | string;
+    rarityColor(rarity: string | null | undefined): string;
+}
+/** Names and icons of the title's currencies and items, from the configuration the client loaded. */
+declare function useCatalog(): Catalog;
+/** The player's currency balances (id → amount), live; only currencies the title defines. */
+declare function useBalances(): Array<[string, number]>;
+/** Re-renders every `ms` — for countdowns. */
+declare function useNow(ms?: number): number;
+
+type ButtonTone = "green" | "gold" | "blue" | "red" | "grey";
+/** Text colour and its outline on a filled surface of each tone (theme tokens `onGreen`, …). */
+declare const ON_TONE: Record<ButtonTone, {
+    color: string;
+    textShadow: string;
+}>;
+/**
+ * A surface filled with a tone of the theme (a hero banner, "your row", a highlighted day). Inside it
+ * the text tokens are re-pointed to the tone's own text colour and outline, so everything laid out in
+ * it — `outlined` text, dim captions, chips — reads correctly on it in ANY theme: white on a
+ * saturated tone, dark ink on a pastel one. Never hard-code a banner colour in a module: pick a tone.
+ */
+declare function toneSurface(tone: ButtonTone): CSSProperties;
+declare function buttonStyle(tone: ButtonTone, disabled?: boolean, size?: "sm" | "md" | "lg"): CSSProperties;
+interface ButtonProps {
+    children: ReactNode;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    tone?: ButtonTone;
+    size?: "sm" | "md" | "lg";
+    disabled?: boolean;
+    busy?: boolean;
+    /** A reward is waiting: shine + gentle bounce. */
+    attract?: boolean;
+    style?: CSSProperties;
+    className?: string;
+    /** Sound of the press; `false` — silent (default "click"). */
+    sound?: "click" | "tab" | false;
+    title?: string;
+    "data-tutorial-anchor"?: string;
+}
+declare function Button({ children, onClick, tone, size, disabled, busy, attract, style, className, sound, title, ...rest }: ButtonProps): ReactNode;
+/** Round icon button (close, back, menu). */
+declare function IconButton({ glyph, onClick, label, size, tone, style, badge, }: {
+    glyph: Glyph | string;
+    onClick: () => void;
+    label: string;
+    size?: number;
+    tone?: ButtonTone;
+    style?: CSSProperties;
+    badge?: number;
+}): ReactNode;
+declare function Spinner({ size }: {
+    size?: number;
+}): ReactNode;
+/** Red "N" on a button — something to claim (Unity ButtonAlertBadge). Hidden at 0. */
+declare function Badge({ count, dot, style, }: {
+    count: number;
+    dot?: boolean;
+    style?: CSSProperties;
+}): ReactNode;
+/** Icon + amount, as drawn on prices, rewards and balances. */
+declare function ResourceBadge({ line, size, big, dim, }: {
+    line: ResourceLine;
+    size?: number;
+    big?: boolean;
+    dim?: boolean;
+}): ReactNode;
+/** Name of a resource line for the player: currency and item names from the config, token names by system. */
+declare function resourceName(line: ResourceLine, catalog: {
+    currencyName(id: string): string;
+    itemName(id: string): string;
+    localize(text: string): string;
+}, client: Parameters<typeof tokenName>[1]): string;
+/** A row of resource badges (a price, a reward). */
+declare function ResourceList({ lines, size, gap, dimIf, }: {
+    lines: ResourceLine[];
+    size?: number;
+    gap?: number;
+    dimIf?: (line: ResourceLine) => boolean;
+}): ReactNode;
+/**
+ * A balance chip that reward icons fly to (`data-resource-counter`): it holds its value while they
+ * fly and ticks up when they land. Put it wherever the player sees a balance.
+ */
+declare function ResourceCounter({ currencyID, amount, size, onClick, }: {
+    currencyID: string;
+    amount: number;
+    size?: number;
+    onClick?: () => void;
+}): ReactNode;
+/** Item tile: rarity frame, icon, count badge, optional level. */
+declare function ItemTile({ itemID, count, level, onClick, size, selected, dim, }: {
+    itemID: string;
+    count?: number;
+    level?: number;
+    onClick?: () => void;
+    size?: number;
+    selected?: boolean;
+    dim?: boolean;
+}): ReactNode;
+/** Rounded progress bar with the value written on it; the fill slides when the value changes. */
+declare function ProgressBar({ value, max, tone, label, height, }: {
+    value: number;
+    max: number;
+    tone?: "green" | "gold" | "blue";
+    label?: string;
+    height?: number;
+}): ReactNode;
+declare function SectionTitle({ children, right, }: {
+    children: ReactNode;
+    right?: ReactNode;
+}): ReactNode;
+declare function EmptyState({ glyph, text, action, }: {
+    glyph: Glyph | string;
+    text: string;
+    action?: ReactNode;
+}): ReactNode;
+declare function Center({ children, minHeight, }: {
+    children: ReactNode;
+    minHeight?: number;
+}): ReactNode;
+/** Countdown text to a timestamp ("Refreshes in 3h 05m"); nothing when it passed. */
+declare function Timer({ at, now, label, }: {
+    at: string | null | undefined;
+    now: number;
+    label?: string;
+}): ReactNode;
+interface TabItem<T extends string> {
+    id: T;
+    label: string;
+    glyph?: Glyph | string;
+    badge?: number;
+}
+/** Segmented tabs (sections of one screen). Scrolls sideways when they do not fit. */
+declare function Tabs<T extends string>({ tabs, value, onChange, style, }: {
+    tabs: TabItem<T>[];
+    value: T;
+    onChange: (id: T) => void;
+    style?: CSSProperties;
+}): ReactNode;
+/** Staggered entrance of the i-th item of a list (off when motion or stagger is off). */
+declare function useStagger(): (index: number) => CSSProperties;
+/** A glossy card; `highlight` gives it a gold frame (something to claim). */
+declare function Card({ children, style, highlight, onClick, }: {
+    children: ReactNode;
+    style?: CSSProperties;
+    highlight?: boolean;
+    onClick?: () => void;
+}): ReactNode;
+
+/** Closes the popup this component is in, with its exit animation. */
+declare function usePopupClose(): () => void;
+/** Renders into the kit layer; in place when there is no provider. */
+declare function KitPortal({ children }: {
+    children: ReactNode;
+}): ReactNode;
+interface PopupProps {
+    children: ReactNode;
+    /** Called after the exit animation. Without it the popup cannot be dismissed by the player. */
+    onClose?: () => void;
+    /** Controlled visibility; the popup plays its exit before unmounting. Default true. */
+    open?: boolean;
+    title?: ReactNode;
+    /** Max width on tablet/desktop, px (default 400). */
+    width?: number;
+    /** "auto" — a bottom sheet on a phone, a centred popup elsewhere (default); "center" — always centred. */
+    variant?: "auto" | "center" | "sheet";
+    /** Backdrop and Escape close it (default true when onClose is set). */
+    dismissible?: boolean;
+    /** Plays "open" on mount (default true). */
+    sound?: boolean;
+    /** Extra style of the panel. */
+    panelStyle?: CSSProperties;
+    /** Opened by itself, not by the player: waits for the auto-popups that asked before it. */
+    queued?: boolean;
+}
+declare function Popup({ children, onClose, open, title, width, variant, dismissible, sound, panelStyle, queued, }: PopupProps): ReactNode;
+/** A yes/no question: the confirm button runs `onConfirm` (may be async — it shows a spinner). */
+declare function ConfirmPopup({ title, children, confirmLabel, tone, onConfirm, onClose, }: {
+    title: ReactNode;
+    children?: ReactNode;
+    confirmLabel?: ReactNode;
+    tone?: "green" | "gold" | "red" | "blue";
+    onConfirm: () => Promise<boolean | void> | boolean | void;
+    onClose: () => void;
+}): ReactNode;
+/**
+ * A full-screen window over the game — how a feature's screen opens from the ☰ menu or the host's
+ * floating button. Header with the title and a close (or back) button; the body scrolls.
+ */
+declare function Window({ title, icon, onClose, children, open, back, balances, }: {
+    title: ReactNode;
+    icon?: string;
+    onClose: () => void;
+    children: ReactNode;
+    open?: boolean;
+    back?: boolean;
+    /** Balance counters in the header — the window covers the game's own, and rewards fly to these. */ balances?: boolean;
+}): ReactNode;
+
+interface FeatureMenuItem {
+    id: string;
+    label: string;
+    icon?: string;
+    group?: string;
+    order?: number;
+    badge?: number;
+}
+declare function sortFeatures<T extends FeatureMenuItem>(items: readonly T[]): T[];
+declare function FeatureGrid({ items, onOpen, }: {
+    items: readonly FeatureMenuItem[];
+    onOpen: (id: string) => void;
+}): ReactNode;
+
+/** The theme tone of each level: colour of its badge, its stripe, its main button. */
+declare const LEVEL_TONE: Record<NotificationLevel, ButtonTone>;
+
+export { Badge, type Burst, Button, type ButtonProps, type ButtonTone, Card, type Catalog, type CelebrateOptions, Center, ConfirmPopup, type CurrencySection, DEFAULT_PLAYER_PREFS, DEFAULT_UI_CONFIG, DESKTOP_MIN_PX, EASE_IN, EASE_OUT, EASE_POP, EmptyState, FeatureGrid, type FeatureMenuItem, type Flight, FxStore, GLYPHS, type Glyph, Icon, IconButton, type ItemDefinitionView, type ItemSection, ItemTile, KIT_CSS, type KitNotify, type KitOverlayState, KitPortal, LEVEL_TONE, type Layout, type NotificationAction, type NotificationInput, type NotificationLevel, type NotificationSource, NotificationStore, ON_TONE, type Point, Popup, type PopupProps, ProgressBar, RARITY_ORDER, type ResolvedSound, ResourceBadge, ResourceCounter, type ResourceKind, type ResourceLine, ResourceList, SOUND_PRESETS, SectionTitle, type ShownNotification, Spinner, type SynthNoise, type SynthNote, type SynthPreset, TABLET_MIN_PX, TOAST_DURATION, type TabItem, Tabs, Timer, UI_SOUND_EVENTS, type UiKitConfig, type UiKitConfigInput, UiKitProvider, type UiKitProviderProps, type UiKitValue, type UiLanguage, type UiMotion, type UiMotionConfig, type UiPlayerPrefs, type UiSoundConfig, UiSoundEngine, type UiSoundEvent, type UiSoundSpec, type UiStringKey, type UiThemeConfig, Window, bundleLines, buttonStyle, canAfford, configSection, costLines, countdown, counterKeys, createNotificationStore, currencyGlyph, defineUiConfig, effectiveVolume, errorText, formatAmount, grantLines, grantedBy, groupBy, iconsFor, isGlyph, itemDefinitions, itemGlyph, layoutFor, makeT, mergeLines, motionDurations, outlined, panel, parsePlayerPrefs, pickLanguage, plural, rarityRank, renderKitOverlays, resolveSound, resolveUiConfig, resourceName, screenBackground, sortFeatures, themeVars, tokenGlyph, tokenName, tokenParts, toneSurface, uiT, useAnimatedNumber, useBalances, useCatalog, useCelebrate, useCounterValue, useGameLayout, useLayout, useMotion, useNotify, useNow, usePlayerPrefs, usePopupClose, usePresence, useSound, useStagger, useToast, useUiKit, v, well };