Crate: configurable animation model + desktop picker (#65)

* Crate: configurable animation model + desktop picker

Closes #16, closes #17.

shared/crate.ts defines five variants (reel, spin, flip, burst, instant) with
their durations. reel is first and is the default - it is what every existing
store already plays, so an operator who never opens this setting sees no change.

normalizeCrateAnimation coerces anything - an old config, a hand-edited json, a
renderer sending nonsense - to a real variant and never throws. A bad animation
value must not stop a player receiving what they paid for.

The setting is per-server store config, not a global app preference: the people
who see it are the players buying from that server's panel, not the operator at
the desktop. It is carried on StorePublic too, because the panel plays it from
the buyer-facing payload.

Desktop picker sits in the Store tab with a plain-language description of each
variant (including how long it takes). Panel rendering of the new variants is
the next slice.

* Review fix: handle a failed animation save, and show what was actually stored

The picker updated state optimistically and awaited with no catch: a failed IPC
left the UI claiming a setting the server never took, and rejected the promise
into nothing. It now reverts on failure and adopts the value the main side
returns, which is the coerced one.

Author: CaYatur

src/main/ipc/register.ts

@@ -412,6 +412,9 @@ export function registerIpc(): void {
     balances: economy.listBalances(id),
     categories: economy.listCategories(id)
   }))
+  H(IPC.storeCrateAnimation, (_e, id: string, animation: string) =>
+    economy.setCrateAnimation(id, animation)
+  )
   H(IPC.economyUpsertCategory, (_e, id: string, category: EconomyCategory) =>
     economy.upsertCategory(id, category)
   )

src/main/smoke.ts

@@ -14,6 +14,12 @@ import * as siteMod from './web/site'
 import { pickSiteLang } from './web/siteLang'
 import type { LedgerEntry, Product } from '@shared/web'
 import { categoryName, filterLedger, ledgerSummary } from '@shared/economy'
+import {
+  CRATE_ANIMATIONS,
+  DEFAULT_CRATE_ANIMATION,
+  crateDuration,
+  normalizeCrateAnimation
+} from '@shared/crate'
 import { getProvider } from './core/versions'
 import { createServer } from './core/createServer'
 import { pickForgeRunJar } from './core/serverDetect'
@@ -3516,6 +3522,37 @@ export async function runWebSmoke(): Promise<void> {
       return fail('a deleted category should fall back to its raw id')
     }
     console.log('WEB-SMOKE: economy categories OK (validated on write, history not rewritten on delete)')
+
+    // Crate animation (#16): a bad value must never stop a player receiving
+    // what they paid for, so every path coerces to a real animation.
+    if (normalizeCrateAnimation('spin') !== 'spin') return fail('a valid animation was rejected')
+    for (const bad of [undefined, null, '', 'nope', 42, {}, []]) {
+      if (normalizeCrateAnimation(bad) !== DEFAULT_CRATE_ANIMATION) {
+        return fail('a bad animation did not fall back to the default: ' + String(bad))
+      }
+    }
+    if (crateDuration('instant') !== 0) return fail('instant should have no wait')
+    if (crateDuration('garbage') !== crateDuration(DEFAULT_CRATE_ANIMATION)) {
+      return fail('an unknown animation should time like the default')
+    }
+    if (CRATE_ANIMATIONS[0].id !== DEFAULT_CRATE_ANIMATION) {
+      return fail('the default should be the first option in the picker')
+    }
+    // Round-trip through the store, including the buyer-facing payload - the
+    // panel plays the animation from publicStore, not from the admin config.
+    const anSrv = 'crate-smoke-server'
+    if (economy.getStoreConfig(anSrv).crateAnimation !== DEFAULT_CRATE_ANIMATION) {
+      return fail('a fresh store should default its animation')
+    }
+    if (economy.setCrateAnimation(anSrv, 'flip') !== 'flip') return fail('set did not return the value')
+    if (economy.getStoreConfig(anSrv).crateAnimation !== 'flip') return fail('animation did not persist')
+    if (economy.publicStore(anSrv).crateAnimation !== 'flip') {
+      return fail('the buyer-facing store must carry the animation')
+    }
+    if (economy.setCrateAnimation(anSrv, 'not-real') !== DEFAULT_CRATE_ANIMATION) {
+      return fail('an invalid animation must be coerced, not stored')
+    }
+    console.log('WEB-SMOKE: crate animation OK (coerced on every path, reaches the buyer payload)')
   } catch (e) {
     return fail('exception: ' + String(e))
   } finally {

src/main/store/economy.ts

@@ -5,6 +5,8 @@ import { processManager } from '../core/processManager'
 import * as rcon from '../core/rcon'
 import { log } from '../logger'
 import { DEFAULT_CATEGORIES } from '@shared/economy'
+import { DEFAULT_CRATE_ANIMATION, normalizeCrateAnimation } from '@shared/crate'
+import type { CrateAnimation } from '@shared/crate'
 import type {
   BuyResult,
   CrateReward,
@@ -19,6 +21,7 @@ import type {
 
 interface StoreState {
   currency: string
+  crateAnimation: CrateAnimation
   products: Product[]
   /** Economy categories - independent of `products` (#13). */
   categories: EconomyCategory[]
@@ -51,6 +54,7 @@ function getStore(serverId: string): StoreState {
   if (!stores[serverId]) {
     stores[serverId] = {
       currency: 'Coins',
+      crateAnimation: DEFAULT_CRATE_ANIMATION,
       products: [],
       categories: DEFAULT_CATEGORIES.map((c) => ({ ...c })),
       balances: {},
@@ -66,6 +70,9 @@ function getStore(serverId: string): StoreState {
   if (!Array.isArray(stores[serverId].categories)) {
     stores[serverId].categories = DEFAULT_CATEGORIES.map((c) => ({ ...c }))
   }
+  // ...and files that predate configurable crate animations. Normalised on read
+  // so a hand-edited json cannot leave the panel with an animation it cannot play.
+  stores[serverId].crateAnimation = normalizeCrateAnimation(stores[serverId].crateAnimation)
   return stores[serverId]
 }
 
@@ -196,7 +203,11 @@ function toPublic(p: Product): ProductPublic {
 }
 export function publicStore(serverId: string): StorePublic {
   const st = getStore(serverId)
-  return { currency: st.currency, products: st.products.map(toPublic) }
+  return {
+    currency: st.currency,
+    products: st.products.map(toPublic),
+    crateAnimation: st.crateAnimation
+  }
 }
 export function getBalance(serverId: string, mcName: string): number {
   return getStore(serverId).balances[mcName] ?? 0
@@ -208,12 +219,18 @@ export function getTxns(serverId: string, mcName: string): Txn[] {
 // ---- admin (trusted: desktop, or web users with 'store' scope) ----
 export function getStoreConfig(serverId: string): StoreConfig {
   const st = getStore(serverId)
-  return { currency: st.currency, products: st.products }
+  return { currency: st.currency, products: st.products, crateAnimation: st.crateAnimation }
 }
 export function setCurrency(serverId: string, currency: string): void {
   getStore(serverId).currency = currency.trim() || 'Coins'
   save()
 }
+export function setCrateAnimation(serverId: string, animation: unknown): CrateAnimation {
+  const st = getStore(serverId)
+  st.crateAnimation = normalizeCrateAnimation(animation)
+  save()
+  return st.crateAnimation
+}
 export function upsertProduct(serverId: string, product: Product): Product {
   const st = getStore(serverId)
   const clean: Product = {

src/main/web/server.ts

@@ -526,6 +526,11 @@ async function handlePanel(req: IncomingMessage, res: ServerResponse): Promise<v
         return sendJson(res, 400, { error: String((e as Error)?.message ?? e) })
       }
     }
+    if (rest === 'admin/crate-animation' && method === 'POST') {
+      if (!gate('store')) return
+      const b = (await readBody(req).catch(() => ({}))) as { animation?: string }
+      return sendJson(res, 200, { animation: economy.setCrateAnimation(id, b.animation) })
+    }
     if (rest === 'admin/category' && method === 'POST') {
       if (!gate('store')) return
       const b = (await readBody(req).catch(() => ({}))) as EconomyCategory

src/preload/index.ts

@@ -134,6 +134,7 @@ const api: MsmsApi = {
     ipcRenderer.invoke(IPC.storeAddBalance, id, mcName, amount, reason, category),
   setStoreBalance: (id, mcName, amount, reason, category) =>
     ipcRenderer.invoke(IPC.storeSetBalance, id, mcName, amount, reason, category),
+  setCrateAnimation: (id, animation) => ipcRenderer.invoke(IPC.storeCrateAnimation, id, animation),
   upsertEconomyCategory: (id, category) =>
     ipcRenderer.invoke(IPC.economyUpsertCategory, id, category),
   deleteEconomyCategory: (id, categoryId) =>

src/renderer/src/locales/en.ts

@@ -730,6 +730,17 @@ export default {
     newCategory: 'New category name',
     catAll: 'All categories',
     catNone: 'Uncategorised',
+    crateAnimation: 'Crate opening animation',
+    anim_reel: 'Reel (horizontal scroll)',
+    anim_spin: 'Slot machine (vertical spin)',
+    anim_flip: 'Card flip',
+    anim_burst: 'Quick burst',
+    anim_instant: 'Instant (no animation)',
+    animDesc_reel: 'The classic sideways-scrolling strip that slows to a stop on the reward. About 4 seconds.',
+    animDesc_spin: 'A vertical column spins like a slot machine and lands on the reward. About 3 seconds.',
+    animDesc_flip: 'Face-down cards flip over one by one until the reward is revealed. About 3 seconds.',
+    animDesc_burst: 'A short shuffle, then the reward pops in. Under 2 seconds — good for busy stores.',
+    animDesc_instant: 'No animation at all; the reward is shown immediately. Best for slow devices.',
     ledger: 'Balance log',
     noLedger: 'No balance changes yet.',
     noLedgerMatch: 'No entries match this filter.',

src/renderer/src/locales/tr.ts

@@ -734,6 +734,17 @@ const tr: typeof en = {
     newCategory: 'Yeni kategori adı',
     catAll: 'Tüm kategoriler',
     catNone: 'Kategorisiz',
+    crateAnimation: 'Sandık açma animasyonu',
+    anim_reel: 'Şerit (yatay kayma)',
+    anim_spin: 'Slot makinesi (dikey dönüş)',
+    anim_flip: 'Kart çevirme',
+    anim_burst: 'Hızlı patlama',
+    anim_instant: 'Anında (animasyonsuz)',
+    animDesc_reel: 'Yavaşlayarak ödülün üzerinde duran klasik yatay şerit. Yaklaşık 4 saniye.',
+    animDesc_spin: 'Dikey bir sütun slot makinesi gibi döner ve ödülde durur. Yaklaşık 3 saniye.',
+    animDesc_flip: 'Kapalı kartlar ödül çıkana kadar tek tek çevrilir. Yaklaşık 3 saniye.',
+    animDesc_burst: 'Kısa bir karıştırma, ardından ödül belirir. 2 saniyenin altında — yoğun mağazalar için.',
+    animDesc_instant: 'Hiç animasyon yok; ödül anında gösterilir. Yavaş cihazlar için en iyisi.',
     ledger: 'Bakiye günlüğü',
     noLedger: 'Henüz bakiye değişikliği yok.',
     noLedgerMatch: 'Bu filtreyle eşleşen kayıt yok.',

src/renderer/src/views/StoreView.tsx

@@ -15,6 +15,8 @@ import {
 } from 'lucide-react'
 import { useStore } from '../store'
 import { categoryName, filterLedger, ledgerSummary } from '@shared/economy'
+import { CRATE_ANIMATIONS, DEFAULT_CRATE_ANIMATION } from '@shared/crate'
+import type { CrateAnimation } from '@shared/crate'
 import type { LedgerKind } from '@shared/economy'
 import type {
   Product,
@@ -48,6 +50,7 @@ export function StoreView(): JSX.Element {
   const [section, setSection] = useState<'economy' | 'store'>('economy')
   const [balCategory, setBalCategory] = useState('')
   const [newCat, setNewCat] = useState('')
+  const [crateAnim, setCrateAnim] = useState<CrateAnimation>(DEFAULT_CRATE_ANIMATION)
   const [edit, setEdit] = useState<Product | null>(null)
   const [cmdText, setCmdText] = useState('')
 
@@ -62,6 +65,7 @@ export function StoreView(): JSX.Element {
     const d = await window.msms.getStore(id)
     setData(d)
     setCurrency(d.currency)
+    setCrateAnim(d.crateAnimation ?? DEFAULT_CRATE_ANIMATION)
     setLedger(await window.msms.getStoreLedger(id))
   }
   useEffect(() => {
@@ -120,6 +124,20 @@ export function StoreView(): JSX.Element {
     toast('success', 'store.saved')
     void load()
   }
+  const saveCrateAnimation = async (animation: CrateAnimation): Promise<void> => {
+    const previous = crateAnim
+    setCrateAnim(animation)
+    try {
+      // Trust what was actually stored, not what was asked for - the main side
+      // coerces an unknown value, and the picker must not claim otherwise.
+      const saved = await window.msms.setCrateAnimation(id, animation)
+      setCrateAnim(saved)
+      toast('success', 'store.saved')
+    } catch (e) {
+      setCrateAnim(previous)
+      toast('error', String((e as Error)?.message ?? e))
+    }
+  }
   const addCategory = async (): Promise<void> => {
     const name = newCat.trim()
     if (!name) return
@@ -175,6 +193,27 @@ export function StoreView(): JSX.Element {
             <Check size={14} /> {t('common.save')}
           </button>
         </div>
+
+        {/* Per-server, because the people who see it are the players buying
+            from this server's panel - not the operator at the desktop (#17). */}
+        <div className="field" style={{ marginTop: 14, marginBottom: 0, maxWidth: 420 }}>
+          <label>
+            <Gift size={13} style={{ verticalAlign: -2, marginRight: 5 }} />
+            {t('store.crateAnimation')}
+          </label>
+          <select
+            className="input"
+            value={crateAnim}
+            onChange={(e) => void saveCrateAnimation(e.target.value as CrateAnimation)}
+          >
+            {CRATE_ANIMATIONS.map((a) => (
+              <option key={a.id} value={a.id}>
+                {t(`store.anim_${a.id}`)}
+              </option>
+            ))}
+          </select>
+          <p className="hint" style={{ marginBottom: 0 }}>{t(`store.animDesc_${crateAnim}`)}</p>
+        </div>
       </div>
 
       <div style={{ display: section === 'economy' ? undefined : 'none' }}>

src/shared/crate.ts

@@ -0,0 +1,49 @@
+/**
+ * Crate opening animations (#16).
+ *
+ * The animation is per-server store config, not a global app preference: the
+ * people who see it are the players buying from that server's panel, not the
+ * operator sitting at the desktop app.
+ */
+
+export type CrateAnimation = 'reel' | 'spin' | 'flip' | 'burst' | 'instant'
+
+export interface CrateAnimationMeta {
+  id: CrateAnimation
+  /** How long the animation runs before the reward is announced, in ms. */
+  durationMs: number
+}
+
+/**
+ * Order is the order shown in the picker. `reel` stays first and is the
+ * default: it is what every existing store already plays, so an operator who
+ * never touches this setting sees no change.
+ */
+export const CRATE_ANIMATIONS: CrateAnimationMeta[] = [
+  { id: 'reel', durationMs: 4000 },
+  { id: 'spin', durationMs: 3200 },
+  { id: 'flip', durationMs: 2800 },
+  { id: 'burst', durationMs: 1600 },
+  { id: 'instant', durationMs: 0 }
+]
+
+export const DEFAULT_CRATE_ANIMATION: CrateAnimation = 'reel'
+
+const IDS = CRATE_ANIMATIONS.map((a) => a.id)
+
+/**
+ * Pure: coerce anything (an old config, a hand-edited json, a renderer that
+ * sent nonsense) to a real animation. Never throws - a bad value must not stop
+ * a player from receiving what they paid for, so it degrades to the default.
+ */
+export function normalizeCrateAnimation(value: unknown): CrateAnimation {
+  return typeof value === 'string' && (IDS as string[]).includes(value)
+    ? (value as CrateAnimation)
+    : DEFAULT_CRATE_ANIMATION
+}
+
+/** Pure: how long the panel should wait before announcing the reward. */
+export function crateDuration(animation: unknown): number {
+  const id = normalizeCrateAnimation(animation)
+  return CRATE_ANIMATIONS.find((a) => a.id === id)?.durationMs ?? 4000
+}

src/shared/ipc.ts

@@ -54,6 +54,7 @@ import type {
   LedgerEntry,
   EconomyCategory
 } from './web'
+import type { CrateAnimation } from './crate'
 
 /** request/response channels (renderer -> main via invoke). */
 export const IPC = {
@@ -182,6 +183,7 @@ export const IPC = {
   storeAddBalance: 'store:add-balance',
   storeSetBalance: 'store:set-balance',
   storeLedger: 'store:ledger',
+  storeCrateAnimation: 'store:crate-animation',
   economyUpsertCategory: 'economy:upsert-category',
   economyDeleteCategory: 'economy:delete-category',
 
@@ -395,6 +397,7 @@ export interface MsmsApi {
     reason?: string,
     category?: string
   ): Promise<number>
+  setCrateAnimation(id: string, animation: CrateAnimation): Promise<CrateAnimation>
   upsertEconomyCategory(id: string, category: EconomyCategory): Promise<EconomyCategory>
   deleteEconomyCategory(id: string, categoryId: string): Promise<void>
   getStoreLedger(id: string, mcName?: string): Promise<LedgerEntry[]>