@idosgames/mcp 0.1.18 → 0.1.20

package/registry/modules/marketplace.json

@@ -0,0 +1,71 @@
+{
+  "id": "marketplace",
+  "meta": {
+    "name": "Marketplace",
+    "type": "app",
+    "engine": "dom"
+  },
+  "catalog": {
+    "type": "feature",
+    "summary": "Marketplace screen for any game: player listings and auctions, selling, bids, direct trades, claims and history.",
+    "description": "A ready player marketplace (Unity Alikhan/Marketplace) for ANY game, built on the @idosgames/react/ui kit and client.marketplace. Tabs: the market (items grouped with their cheapest price), my lots, my bids, direct trades, things to claim and history. Everything detailed is a popup: an item's offers (cheapest listing first, then auctions ending soonest), one offer (buy, bid with the engine's minimum next bid, cancel your own), selling (pick an item — only tradable, never a worn one — then listing or auction, amount, price in a currency tradable between players, duration and the commission), and incoming trades (accept / decline). The server holds the escrow and settles every trade. Registers the 'marketplace' feature; its badge counts things to claim and trades waiting. Ships title-seed.json: listings and auctions for currencies with a 5% commission.",
+    "provides": [
+      "player marketplace screen",
+      "listings and auctions",
+      "sell popup with price and duration",
+      "bids with the minimum next bid",
+      "direct trades",
+      "claims and history",
+      "marketplace badge",
+      "demo marketplace rules"
+    ],
+    "tags": [
+      "marketplace",
+      "trading",
+      "auction",
+      "listing",
+      "p2p",
+      "ui",
+      "screen",
+      "economy"
+    ],
+    "author": {
+      "name": "iDos Games",
+      "url": "https://idosgames.com"
+    },
+    "version": "0.1.0"
+  },
+  "dependencies": {
+    "@idosgames/core": "0.19.1",
+    "@idosgames/module-sdk": "0.7.0",
+    "@idosgames/react": "0.3.0",
+    "react": "19.2.7"
+  },
+  "contentHash": "1996992148c6539aacebc78427829df8c778879e3a89d7ca5d948f081c2bd4e0",
+  "files": [
+    {
+      "path": "i18n.ts",
+      "content": "import { makeT } from \"@idosgames/react/ui\";\n\nconst EN = {\n  title: \"Market\",\n  market: \"Market\",\n  myLots: \"My lots\",\n  myBids: \"My bids\",\n  trades: \"Trades\",\n  claims: \"To claim\",\n  history: \"History\",\n  sell: \"Sell\",\n  lots: \"lot|lots\",\n  auctions: \"auction|auctions\",\n  buy: \"Buy\",\n  bid: \"Bid\",\n  yourBid: \"Your bid\",\n  currentBid: \"Current bid\",\n  startingBid: \"Starting bid\",\n  leading: \"You lead\",\n  endsIn: \"Ends in\",\n  listing: \"Fixed price\",\n  auction: \"Auction\",\n  price: \"Price\",\n  amount: \"Amount\",\n  duration: \"Duration\",\n  hours: \"h\",\n  commission: \"Commission\",\n  create: \"Put up for sale\",\n  cancel: \"Take back\",\n  claim: \"Claim\",\n  claimAll: \"Claim all\",\n  accept: \"Accept\",\n  decline: \"Decline\",\n  gift: \"Gift\",\n  wants: \"Wants\",\n  from: \"From\",\n  pickItem: \"Pick an item\",\n  nothingToSell: \"Nothing to sell — tradable items you own appear here.\",\n  noTradableCurrency:\n    \"No currency of this game can be traded between players yet.\",\n  empty: \"Nothing here yet.\",\n  closed: \"The market is closed right now.\",\n  disabled: \"No marketplace in this game. Enable it in LiveOps → Marketplace.\",\n  sold: \"Sold\",\n  bought: \"Bought\",\n  seller: \"Seller\",\n  you: \"You\",\n  auctionRuns: \"The auction runs to its end — come back to claim the proceeds.\",\n} as const;\n\nexport const t = makeT<keyof typeof EN>(EN, {\n  title: \"Рынок\",\n  market: \"Рынок\",\n  myLots: \"Мои лоты\",\n  myBids: \"Мои ставки\",\n  trades: \"Обмены\",\n  claims: \"К получению\",\n  history: \"История\",\n  sell: \"Продать\",\n  lots: \"лот|лота|лотов\",\n  auctions: \"аукцион|аукциона|аукционов\",\n  buy: \"Купить\",\n  bid: \"Ставка\",\n  yourBid: \"Ваша ставка\",\n  currentBid: \"Текущая ставка\",\n  startingBid: \"Начальная ставка\",\n  leading: \"Вы лидируете\",\n  endsIn: \"До конца\",\n  listing: \"Фиксированная цена\",\n  auction: \"Аукцион\",\n  price: \"Цена\",\n  amount: \"Количество\",\n  duration: \"Срок\",\n  hours: \"ч\",\n  commission: \"Комиссия\",\n  create: \"Выставить\",\n  cancel: \"Снять\",\n  claim: \"Забрать\",\n  claimAll: \"Забрать всё\",\n  accept: \"Принять\",\n  decline: \"Отклонить\",\n  gift: \"Подарок\",\n  wants: \"Просит\",\n  from: \"От\",\n  pickItem: \"Выберите предмет\",\n  nothingToSell:\n    \"Продавать нечего — здесь появятся ваши предметы, которыми можно торговать.\",\n  noTradableCurrency:\n    \"В этой игре пока нет валюты, которой игроки могут торговать между собой.\",\n  empty: \"Пока пусто.\",\n  closed: \"Рынок сейчас закрыт.\",\n  disabled: \"Рынка в этой игре нет. Включите его в LiveOps → Marketplace.\",\n  sold: \"Продано\",\n  bought: \"Куплено\",\n  seller: \"Продавец\",\n  you: \"Вы\",\n  auctionRuns: \"Аукцион идёт до конца — возвращайтесь забрать выручку.\",\n});\n"
+    },
+    {
+      "path": "index.ts",
+      "content": "// @idosgames/mod-marketplace — Marketplace screen for any game: browse lots by item, buy and bid, sell your items as listings or auctions, direct trades, claims and history.\n\nexport { marketplaceModule } from \"./module\";\n"
+    },
+    {
+      "path": "MarketplaceScreen.tsx",
+      "content": "import { useCallback, useEffect, useState, type ReactNode } from \"react\";\nimport type {\n  MarketplaceDefinitions,\n  MarketplaceGroupedOfferView,\n  MarketplaceHistoryEntryView,\n  MarketplaceMyStateResponse,\n  MarketplaceOfferView,\n} from \"@idosgames/core\";\nimport type {\n  FeatureRegistry,\n  FeatureScreenProps,\n} from \"@idosgames/module-sdk\";\nimport { useIDosGamesClient, useUserState } from \"@idosgames/react\";\nimport {\n  Button,\n  Card,\n  Center,\n  EmptyState,\n  Icon,\n  IconButton,\n  ItemTile,\n  Popup,\n  ResourceList,\n  Spinner,\n  Tabs,\n  Timer,\n  bundleLines,\n  canAfford,\n  errorText,\n  formatAmount,\n  grantedBy,\n  outlined,\n  panel,\n  plural,\n  useCatalog,\n  useCelebrate,\n  useNow,\n  usePopupClose,\n  useSound,\n  useStagger,\n  useToast,\n  v,\n  type ItemDefinitionView,\n} from \"@idosgames/react/ui\";\nimport {\n  auctionDurations,\n  commissionPercent,\n  listingDurations,\n  minNextBid,\n  offerPrice,\n  groupCounts,\n  priceBundle,\n  sellableItems,\n  sortOffers,\n  tradableCurrencies,\n  type SellableItem,\n} from \"./model\";\nimport { t } from \"./i18n\";\n\n// The marketplace (Unity Alikhan/Marketplace): a window of tabs — the market by item, my lots, my\n// bids, trades, things to claim, history — and everything with detail in popups: an item's lots, one\n// lot (buy / bid / take back), and selling (pick an item → listing or auction → price and duration).\n// The server holds every escrow and settles every trade.\n\ntype Tab = \"market\" | \"mine\" | \"bids\" | \"trades\" | \"claims\" | \"history\";\n\nexport function makeMarketplaceScreen(features: FeatureRegistry) {\n  return function MarketplaceScreen(_: FeatureScreenProps): ReactNode {\n    return <Marketplace features={features} />;\n  };\n}\n\nfunction Marketplace({ features }: { features: FeatureRegistry }): ReactNode {\n  const client = useIDosGamesClient();\n  const [defs, setDefs] = useState<{\n    defs: MarketplaceDefinitions | null;\n    open: boolean;\n  } | null>(null);\n  const [mine, setMine] = useState<MarketplaceMyStateResponse | null>(null);\n  const [tab, setTab] = useState<Tab>(\"market\");\n  const [selling, setSelling] = useState(false);\n  const [offer, setOffer] = useState<MarketplaceOfferView | null>(null);\n  const [itemID, setItemID] = useState<string | null>(null);\n  const [version, setVersion] = useState(0);\n\n  const loadMine = useCallback(async () => {\n    const res = await client.marketplace.getMyState();\n    if (res.ok) {\n      setMine(res.data);\n      features.setBadge(\n        \"marketplace\",\n        (res.data.Claimables?.length ?? 0) +\n          (res.data.IncomingTrades?.length ?? 0),\n      );\n    }\n  }, [client, features]);\n\n  useEffect(() => {\n    void client.marketplace.getDefinitions().then((res) =>\n      setDefs(\n        res.ok\n          ? {\n              defs: res.data.Definitions ?? null,\n              open:\n                res.data.IsOpenNow !== false && res.data.GatePassed !== false,\n            }\n          : { defs: null, open: false },\n      ),\n    );\n    void client.user.getUserInventory();\n    void loadMine();\n  }, [client, loadMine]);\n\n  const refresh = () => {\n    setVersion((n) => n + 1);\n    void loadMine();\n  };\n\n  if (!defs)\n    return (\n      <Center>\n        <Spinner />\n      </Center>\n    );\n  if (!defs.defs || defs.defs.Enabled === false)\n    return <EmptyState glyph=\"market\" text={t(\"disabled\")} />;\n\n  const tabs: Array<{ id: Tab; label: string; badge?: number }> = [\n    { id: \"market\", label: t(\"market\") },\n    { id: \"mine\", label: t(\"myLots\"), badge: 0 },\n    { id: \"bids\", label: t(\"myBids\") },\n    ...((mine?.IncomingTrades?.length ?? 0) +\n      (mine?.OutgoingTrades?.length ?? 0) >\n    0\n      ? [\n          {\n            id: \"trades\" as const,\n            label: t(\"trades\"),\n            badge: mine?.IncomingTrades?.length ?? 0,\n          },\n        ]\n      : []),\n    { id: \"claims\", label: t(\"claims\"), badge: mine?.Claimables?.length ?? 0 },\n    { id: \"history\", label: t(\"history\") },\n  ];\n\n  return (\n    // minmax(0, 1fr): the tab row scrolls instead of widening the column past the screen.\n    <div\n      style={{\n        display: \"grid\",\n        gridTemplateColumns: \"minmax(0, 1fr)\",\n        gap: 14,\n      }}\n    >\n      {!defs.open ? (\n        <div\n          style={{\n            ...panel,\n            padding: 10,\n            ...outlined,\n            fontSize: 13,\n            textAlign: \"center\",\n            color: v.gold,\n          }}\n        >\n          {t(\"closed\")}\n        </div>\n      ) : null}\n      <div style={{ display: \"flex\", gap: 10, alignItems: \"center\" }}>\n        <div style={{ flex: 1, minWidth: 0 }}>\n          <Tabs tabs={tabs} value={tab} onChange={setTab} />\n        </div>\n        <Button\n          tone=\"gold\"\n          size=\"sm\"\n          disabled={!defs.open}\n          onClick={() => setSelling(true)}\n          data-tutorial-anchor=\"market:sell\"\n        >\n          <Icon glyph=\"plus\" size={16} /> {t(\"sell\")}\n        </Button>\n      </div>\n      <div key={`${tab}:${version}`}>\n        {tab === \"market\" ? <MarketTab onPick={setItemID} /> : null}\n        {tab === \"mine\" ? (\n          <OfferList\n            offers={[...(mine?.MyOffers ?? []), ...(mine?.MyBuyOrders ?? [])]}\n            onPick={setOffer}\n          />\n        ) : null}\n        {tab === \"bids\" ? (\n          <OfferList offers={mine?.MyLeadingBids ?? []} onPick={setOffer} />\n        ) : null}\n        {tab === \"trades\" ? <Trades mine={mine} onDone={refresh} /> : null}\n        {tab === \"claims\" ? (\n          <Claims offers={mine?.Claimables ?? []} onDone={refresh} />\n        ) : null}\n        {tab === \"history\" ? <History /> : null}\n      </div>\n      {itemID ? (\n        <ItemOffersPopup\n          itemID={itemID}\n          version={version}\n          onPick={(o) => setOffer(o)}\n          onClose={() => setItemID(null)}\n        />\n      ) : null}\n      {offer ? (\n        <OfferPopup\n          offer={offer}\n          defs={defs.defs}\n          onDone={refresh}\n          onClose={() => setOffer(null)}\n        />\n      ) : null}\n      {selling ? (\n        <SellPopup\n          defs={defs.defs}\n          onDone={refresh}\n          onClose={() => setSelling(false)}\n        />\n      ) : null}\n    </div>\n  );\n}\n\n// ── Market ───────────────────────────────────────────────────────────────────────────────────\n\nfunction MarketTab({\n  onPick,\n}: {\n  onPick: (itemID: string) => void;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const catalog = useCatalog();\n  const stagger = useStagger();\n  const [groups, setGroups] = useState<MarketplaceGroupedOfferView[] | null>(\n    null,\n  );\n  useEffect(() => {\n    void client.marketplace\n      .getGroupedOffers()\n      .then((res) => setGroups(res.ok ? (res.data.Groups ?? []) : []));\n  }, [client]);\n  if (!groups)\n    return (\n      <Center>\n        <Spinner />\n      </Center>\n    );\n  const items = groups.filter((g) => g.GoodsItemID);\n  if (items.length === 0)\n    return <EmptyState glyph=\"market\" text={t(\"empty\")} />;\n  return (\n    <div style={{ display: \"grid\", gap: 8 }}>\n      {items.map((g, i) => (\n        <Card\n          key={g.GoodsItemID!}\n          onClick={() => onPick(g.GoodsItemID!)}\n          style={{\n            display: \"flex\",\n            alignItems: \"center\",\n            gap: 12,\n            padding: 10,\n            ...stagger(i),\n          }}\n        >\n          <ItemTile itemID={g.GoodsItemID!} size={56} />\n          <div style={{ flex: 1, minWidth: 0 }}>\n            <div style={{ ...outlined, fontSize: 15 }}>\n              {catalog.itemName(g.GoodsItemID!)}\n            </div>\n            <div style={{ ...outlined, fontSize: 12, color: v.textDim }}>\n              {countsLine(groupCounts(g))}\n            </div>\n          </div>\n        </Card>\n      ))}\n    </div>\n  );\n}\n\nfunction countsLine({\n  listings,\n  auctions,\n}: {\n  listings: number;\n  auctions: number;\n}): string {\n  return [\n    listings > 0\n      ? `${formatAmount(listings)} ${plural(listings, t(\"lots\"))}`\n      : \"\",\n    auctions > 0\n      ? `${formatAmount(auctions)} ${plural(auctions, t(\"auctions\"))}`\n      : \"\",\n  ]\n    .filter(Boolean)\n    .join(\" · \");\n}\n\nfunction OfferRow({\n  offer,\n  onPick,\n  index,\n}: {\n  offer: MarketplaceOfferView;\n  onPick: (o: MarketplaceOfferView) => void;\n  index: number;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const catalog = useCatalog();\n  const stagger = useStagger();\n  const now = useNow();\n  const me = client.auth.context?.userID;\n  const auction = offer.OfferType === \"Auction\";\n  const bid = Number(\n    offer.Auction?.CurrentBid ?? offer.Auction?.StartingBid ?? 0,\n  );\n  const bidLine = offer.Auction?.BidCurrencyID\n    ? [\n        {\n          kind: \"currency\" as const,\n          id: offer.Auction.BidCurrencyID,\n          amount: bid,\n        },\n      ]\n    : [];\n  return (\n    <Card\n      onClick={() => onPick(offer)}\n      highlight={auction && offer.Auction?.CurrentBidderID === me}\n      style={{\n        display: \"flex\",\n        alignItems: \"center\",\n        gap: 12,\n        padding: 10,\n        ...stagger(index),\n      }}\n    >\n      {offer.GoodsItemID ? (\n        <ItemTile\n          itemID={offer.GoodsItemID}\n          count={Number(offer.GoodsAmount ?? 1)}\n          size={52}\n        />\n      ) : (\n        <Icon glyph=\"coin\" size={40} />\n      )}\n      <div style={{ flex: 1, minWidth: 0, display: \"grid\", gap: 2 }}>\n        <span style={{ ...outlined, fontSize: 14 }}>\n          {offer.GoodsItemID\n            ? catalog.itemName(offer.GoodsItemID)\n            : offer.GoodsCurrencyID}\n        </span>\n        <span style={{ ...outlined, fontSize: 12, color: v.textDim }}>\n          {auction\n            ? t(\"auction\")\n            : offer.OfferType === \"Listing\"\n              ? t(\"listing\")\n              : offer.OfferType}{\" \"}\n          ·{\" \"}\n          {offer.CreatorUserID === me\n            ? t(\"you\")\n            : (offer.CreatorPublicData?.Username ??\n              `${t(\"seller\")} ${String(offer.CreatorUserID ?? \"\").slice(-4)}`)}\n        </span>\n        {offer.ExpiresAt ? (\n          <Timer at={offer.ExpiresAt} now={now} label={t(\"endsIn\")} />\n        ) : null}\n      </div>\n      <ResourceList lines={auction ? bidLine : offerPrice(offer)} size={18} />\n    </Card>\n  );\n}\n\nfunction OfferList({\n  offers,\n  onPick,\n}: {\n  offers: MarketplaceOfferView[];\n  onPick: (o: MarketplaceOfferView) => void;\n}): ReactNode {\n  if (offers.length === 0)\n    return <EmptyState glyph=\"market\" text={t(\"empty\")} />;\n  return (\n    <div style={{ display: \"grid\", gap: 8 }}>\n      {offers.map((o, i) => (\n        <OfferRow key={o.OfferID ?? i} offer={o} onPick={onPick} index={i} />\n      ))}\n    </div>\n  );\n}\n\n// `version` bumps after any trade on the screen: the list re-reads, so a bought or withdrawn lot leaves it.\nfunction ItemOffersPopup({\n  itemID,\n  version,\n  onPick,\n  onClose,\n}: {\n  itemID: string;\n  version: number;\n  onPick: (o: MarketplaceOfferView) => void;\n  onClose: () => void;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const catalog = useCatalog();\n  const [offers, setOffers] = useState<MarketplaceOfferView[] | null>(null);\n  useEffect(() => {\n    void client.marketplace\n      .getOffersByItem(itemID)\n      .then((res) =>\n        setOffers(res.ok ? sortOffers(res.data.Offers ?? []) : []),\n      );\n  }, [client, itemID, version]);\n  return (\n    <Popup title={catalog.itemName(itemID)} onClose={onClose} width={480}>\n      {offers === null ? (\n        <Center minHeight={120}>\n          <Spinner />\n        </Center>\n      ) : (\n        <OfferList offers={offers} onPick={onPick} />\n      )}\n    </Popup>\n  );\n}\n\n// ── One lot ──────────────────────────────────────────────────────────────────────────────────\n\nfunction OfferPopup({\n  offer,\n  defs,\n  onDone,\n  onClose,\n}: {\n  offer: MarketplaceOfferView;\n  defs: MarketplaceDefinitions;\n  onDone: () => void;\n  onClose: () => void;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const catalog = useCatalog();\n  const state = useUserState();\n  const now = useNow();\n  const me = client.auth.context?.userID;\n  const own = offer.CreatorUserID === me;\n  const auction = offer.OfferType === \"Auction\";\n  const ended = offer.ExpiresAt\n    ? new Date(offer.ExpiresAt).getTime() <= now\n    : false;\n  const balances = state?.InventoryV2?.VirtualCurrencies as\n    Record<string, { Amount?: number }> | undefined;\n  const price = offerPrice(offer);\n  const [bid, setBid] = useState(minNextBid(offer, defs));\n  const bidLine = offer.Auction?.BidCurrencyID\n    ? [\n        {\n          kind: \"currency\" as const,\n          id: offer.Auction.BidCurrencyID,\n          amount: bid,\n        },\n      ]\n    : [];\n\n  return (\n    <Popup\n      title={\n        offer.GoodsItemID ? catalog.itemName(offer.GoodsItemID) : t(\"market\")\n      }\n      onClose={onClose}\n    >\n      <div style={{ display: \"grid\", justifyItems: \"center\", gap: 8 }}>\n        {offer.GoodsItemID ? (\n          <ItemTile\n            itemID={offer.GoodsItemID}\n            count={Number(offer.GoodsAmount ?? 1)}\n            size={96}\n          />\n        ) : null}\n        <div style={{ ...outlined, fontSize: 13, color: v.textDim }}>\n          {auction ? t(\"auction\") : t(\"listing\")} ·{\" \"}\n          {own ? t(\"you\") : (offer.CreatorPublicData?.Username ?? t(\"seller\"))}\n        </div>\n        {offer.ExpiresAt ? (\n          <Timer at={offer.ExpiresAt} now={now} label={t(\"endsIn\")} />\n        ) : null}\n        {auction ? (\n          <div style={{ display: \"grid\", justifyItems: \"center\", gap: 4 }}>\n            <span style={{ ...outlined, fontSize: 13, color: v.textDim }}>\n              {offer.Auction?.CurrentBidderID\n                ? t(\"currentBid\")\n                : t(\"startingBid\")}\n            </span>\n            <ResourceList\n              lines={\n                offer.Auction?.BidCurrencyID\n                  ? [\n                      {\n                        kind: \"currency\",\n                        id: offer.Auction.BidCurrencyID,\n                        amount: Number(\n                          offer.Auction.CurrentBid ??\n                            offer.Auction.StartingBid ??\n                            0,\n                        ),\n                      },\n                    ]\n                  : []\n              }\n              size={24}\n            />\n            {offer.Auction?.CurrentBidderID === me ? (\n              <span style={{ ...outlined, fontSize: 13, color: v.green }}>\n                {t(\"leading\")}\n              </span>\n            ) : null}\n          </div>\n        ) : (\n          <ResourceList lines={price} size={24} />\n        )}\n      </div>\n      {own ? (\n        auction ? (\n          ended ? (\n            <Act\n              label={t(\"claim\")}\n              tone=\"gold\"\n              run={() => client.marketplace.claimAuction(offer.OfferID!)}\n              onDone={onDone}\n            />\n          ) : (\n            // An auction runs to its end: bids are escrowed, so the seller cannot pull it.\n            <div\n              style={{\n                ...outlined,\n                fontSize: 13,\n                color: v.textDim,\n                textAlign: \"center\",\n              }}\n            >\n              {t(\"auctionRuns\")}\n            </div>\n          )\n        ) : (\n          <Act\n            label={t(\"cancel\")}\n            tone=\"grey\"\n            run={() => client.marketplace.cancelListing(offer.OfferID!)}\n            onDone={onDone}\n          />\n        )\n      ) : auction ? (\n        ended ? (\n          <Act\n            label={t(\"claim\")}\n            tone=\"gold\"\n            run={() => client.marketplace.claimAuction(offer.OfferID!)}\n            onDone={onDone}\n          />\n        ) : (\n          <>\n            <Stepper\n              value={bid}\n              min={minNextBid(offer, defs)}\n              onChange={setBid}\n            />\n            <Act\n              label={\n                <>\n                  {t(\"bid\")} <ResourceList lines={bidLine} size={18} />\n                </>\n              }\n              tone=\"gold\"\n              disabled={!canAfford(bidLine, balances)}\n              run={() => client.marketplace.placeBid(offer.OfferID!, bid)}\n              onDone={onDone}\n              sound=\"purchase\"\n            />\n          </>\n        )\n      ) : (\n        <Act\n          label={\n            <>\n              {t(\"buy\")} <ResourceList lines={price} size={18} />\n            </>\n          }\n          tone=\"gold\"\n          disabled={!canAfford(price, balances)}\n          run={() => client.marketplace.buy(offer.OfferID!)}\n          onDone={onDone}\n          sound=\"purchase\"\n          celebrateGoods={offer}\n        />\n      )}\n    </Popup>\n  );\n}\n\ntype Result =\n  { ok: true; data: unknown } | { ok: false; error?: string | null };\n\n/** A button that runs one marketplace call, then closes the popup and celebrates what came in. */\nfunction Act({\n  label,\n  tone,\n  run,\n  onDone,\n  disabled = false,\n  sound = \"claim\",\n  celebrateGoods,\n}: {\n  label: ReactNode;\n  tone: \"gold\" | \"grey\" | \"green\" | \"red\";\n  run: () => Promise<Result>;\n  onDone: () => void;\n  disabled?: boolean;\n  sound?: \"claim\" | \"purchase\";\n  celebrateGoods?: MarketplaceOfferView;\n}): ReactNode {\n  const close = usePopupClose();\n  const celebrate = useCelebrate();\n  const toast = useToast();\n  const play = useSound();\n  const [busy, setBusy] = useState(false);\n  return (\n    <Button\n      tone={tone}\n      size=\"lg\"\n      disabled={disabled}\n      busy={busy}\n      onClick={() => {\n        setBusy(true);\n        void run().then((res) => {\n          setBusy(false);\n          if (!res.ok) return toast(errorText(res.error), \"error\");\n          play(sound);\n          close();\n          onDone();\n          const granted = grantedBy(res.data);\n          if (granted.length > 0) celebrate(granted);\n          else if (celebrateGoods?.GoodsItemID)\n            celebrate([\n              {\n                kind: \"item\",\n                id: celebrateGoods.GoodsItemID,\n                amount: Number(celebrateGoods.GoodsAmount ?? 1),\n              },\n            ]);\n        });\n      }}\n    >\n      {label}\n    </Button>\n  );\n}\n\nfunction Stepper({\n  value,\n  min,\n  onChange,\n  max,\n}: {\n  value: number;\n  min: number;\n  onChange: (n: number) => void;\n  max?: number;\n}): ReactNode {\n  const clamp = (n: number) =>\n    Math.max(min, max !== undefined ? Math.min(max, n) : n);\n  const step = Math.max(1, Math.round(value * 0.1));\n  return (\n    <div\n      style={{\n        display: \"flex\",\n        alignItems: \"center\",\n        gap: 8,\n        justifyContent: \"center\",\n      }}\n    >\n      <IconButton\n        glyph=\"back\"\n        label=\"-\"\n        onClick={() => onChange(clamp(value - step))}\n        size={36}\n      />\n      <input\n        type=\"number\"\n        inputMode=\"numeric\"\n        value={value}\n        min={min}\n        max={max}\n        onChange={(e) =>\n          onChange(clamp(Math.floor(Number(e.target.value) || min)))\n        }\n        style={{\n          width: 110,\n          textAlign: \"center\",\n          padding: \"8px 10px\",\n          borderRadius: 12,\n          border: `2px solid ${v.panelEdge}`,\n          background: \"rgba(0,0,0,.3)\",\n          color: v.text,\n          fontFamily: v.font,\n          fontSize: 18,\n          fontWeight: 800,\n        }}\n      />\n      <IconButton\n        glyph=\"plus\"\n        label=\"+\"\n        onClick={() => onChange(clamp(value + step))}\n        size={36}\n      />\n    </div>\n  );\n}\n\n// ── Trades, claims, history ──────────────────────────────────────────────────────────────────\n\nfunction Trades({\n  mine,\n  onDone,\n}: {\n  mine: MarketplaceMyStateResponse | null;\n  onDone: () => void;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const catalog = useCatalog();\n  const toast = useToast();\n  const celebrate = useCelebrate();\n  const incoming = mine?.IncomingTrades ?? [];\n  const outgoing = mine?.OutgoingTrades ?? [];\n  const answer = async (offer: MarketplaceOfferView, accept: boolean) => {\n    const res = await client.marketplace.respondDirectTrade(\n      offer.OfferID!,\n      accept,\n    );\n    if (!res.ok) return toast(errorText(res.error), \"error\");\n    if (accept && offer.GoodsItemID)\n      celebrate([\n        {\n          kind: \"item\",\n          id: offer.GoodsItemID,\n          amount: Number(offer.GoodsAmount ?? 1),\n        },\n      ]);\n    onDone();\n  };\n  if (incoming.length + outgoing.length === 0)\n    return <EmptyState glyph=\"swords\" text={t(\"empty\")} />;\n  return (\n    <div style={{ display: \"grid\", gap: 8 }}>\n      {incoming.map((o) => (\n        <Card key={o.OfferID!} highlight style={{ display: \"grid\", gap: 8 }}>\n          <div style={{ display: \"flex\", alignItems: \"center\", gap: 10 }}>\n            {o.GoodsItemID ? (\n              <ItemTile itemID={o.GoodsItemID} size={52} />\n            ) : null}\n            <div style={{ flex: 1 }}>\n              <div style={{ ...outlined, fontSize: 14 }}>\n                {o.GoodsItemID ? catalog.itemName(o.GoodsItemID) : \"\"}\n              </div>\n              <div style={{ ...outlined, fontSize: 12, color: v.textDim }}>\n                {t(\"from\")}{\" \"}\n                {o.CreatorPublicData?.Username ??\n                  String(o.CreatorUserID ?? \"\").slice(-6)}{\" \"}\n                ·{\" \"}\n                {bundleLines(o.Price as never).length ? t(\"wants\") : t(\"gift\")}\n              </div>\n            </div>\n            <ResourceList lines={bundleLines(o.Price as never)} />\n          </div>\n          <div\n            style={{ display: \"grid\", gridTemplateColumns: \"1fr 1fr\", gap: 8 }}\n          >\n            <Button tone=\"grey\" size=\"sm\" onClick={() => void answer(o, false)}>\n              {t(\"decline\")}\n            </Button>\n            <Button tone=\"green\" size=\"sm\" onClick={() => void answer(o, true)}>\n              {t(\"accept\")}\n            </Button>\n          </div>\n        </Card>\n      ))}\n      {outgoing.map((o, i) => (\n        <OfferRow\n          key={o.OfferID!}\n          offer={o}\n          index={i}\n          onPick={() =>\n            void client.marketplace\n              .cancelDirectTrade(o.OfferID!)\n              .then(() => onDone())\n          }\n        />\n      ))}\n    </div>\n  );\n}\n\nfunction Claims({\n  offers,\n  onDone,\n}: {\n  offers: MarketplaceOfferView[];\n  onDone: () => void;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const celebrate = useCelebrate();\n  const toast = useToast();\n  const [busy, setBusy] = useState<string | null>(null);\n  const claim = async (offer: MarketplaceOfferView | null) => {\n    setBusy(offer?.OfferID ?? \"all\");\n    const res = offer\n      ? offer.OfferType === \"Auction\"\n        ? await client.marketplace.claimAuction(offer.OfferID!)\n        : await client.marketplace.claimBack(offer.OfferID!)\n      : await client.marketplace.claimBack();\n    setBusy(null);\n    if (!res.ok) return toast(errorText(res.error), \"error\");\n    celebrate(grantedBy(res.data));\n    onDone();\n  };\n  if (offers.length === 0) return <EmptyState glyph=\"gift\" text={t(\"empty\")} />;\n  return (\n    <div style={{ display: \"grid\", gap: 8 }}>\n      {offers.length > 1 ? (\n        <Button\n          tone=\"gold\"\n          attract\n          busy={busy === \"all\"}\n          onClick={() => void claim(null)}\n        >\n          {t(\"claimAll\")}\n        </Button>\n      ) : null}\n      {offers.map((o, i) => (\n        <div\n          key={o.OfferID!}\n          style={{\n            display: \"grid\",\n            gridTemplateColumns: \"1fr auto\",\n            gap: 8,\n            alignItems: \"center\",\n          }}\n        >\n          <OfferRow offer={o} index={i} onPick={() => void claim(o)} />\n          <Button\n            tone=\"gold\"\n            size=\"sm\"\n            busy={busy === o.OfferID}\n            onClick={() => void claim(o)}\n          >\n            {t(\"claim\")}\n          </Button>\n        </div>\n      ))}\n    </div>\n  );\n}\n\nfunction History(): ReactNode {\n  const client = useIDosGamesClient();\n  const catalog = useCatalog();\n  const stagger = useStagger();\n  const me = client.auth.context?.userID;\n  const [entries, setEntries] = useState<MarketplaceHistoryEntryView[] | null>(\n    null,\n  );\n  useEffect(() => {\n    void client.marketplace\n      .getHistory()\n      .then((res) => setEntries(res.ok ? (res.data.Entries ?? []) : []));\n  }, [client]);\n  if (!entries)\n    return (\n      <Center>\n        <Spinner />\n      </Center>\n    );\n  if (entries.length === 0)\n    return <EmptyState glyph=\"clock\" text={t(\"empty\")} />;\n  return (\n    <div style={{ display: \"grid\", gap: 8 }}>\n      {entries.map((e, i) => (\n        <Card\n          key={e.OfferID ?? i}\n          style={{\n            display: \"flex\",\n            alignItems: \"center\",\n            gap: 10,\n            padding: 10,\n            ...stagger(i),\n          }}\n        >\n          {e.GoodsItemID ? (\n            <ItemTile\n              itemID={e.GoodsItemID}\n              count={Number(e.GoodsAmount ?? 1)}\n              size={48}\n            />\n          ) : null}\n          <div style={{ flex: 1 }}>\n            <div style={{ ...outlined, fontSize: 14 }}>\n              {e.GoodsItemID ? catalog.itemName(e.GoodsItemID) : \"\"}\n            </div>\n            <div\n              style={{\n                ...outlined,\n                fontSize: 12,\n                color: e.SellerUserID === me ? v.green : v.gold,\n              }}\n            >\n              {e.SellerUserID === me ? t(\"sold\") : t(\"bought\")}\n            </div>\n          </div>\n          <ResourceList lines={bundleLines(e.PricePaid as never)} size={16} />\n        </Card>\n      ))}\n    </div>\n  );\n}\n\n// ── Selling ──────────────────────────────────────────────────────────────────────────────────\n\nfunction SellPopup({\n  defs,\n  onDone,\n  onClose,\n}: {\n  defs: MarketplaceDefinitions;\n  onDone: () => void;\n  onClose: () => void;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const state = useUserState();\n  const catalog = useCatalog();\n  const [picked, setPicked] = useState<SellableItem | null>(null);\n  const items = catalog.items as Map<\n    string,\n    ItemDefinitionView & { CatalogID?: string; IsTradable?: boolean | null }\n  >;\n  const sellable = sellableItems(state?.InventoryV2 as never, items);\n  const currencies = tradableCurrencies(catalog.currencies as never);\n  const [kind, setKind] = useState<\"listing\" | \"auction\">(\"listing\");\n  const [amount, setAmount] = useState(1);\n  const [currency, setCurrency] = useState(currencies[0] ?? \"CO\");\n  const [price, setPrice] = useState(100);\n  const durations =\n    kind === \"listing\" ? listingDurations(defs) : auctionDurations(defs);\n  const [hours, setHours] = useState(durations[0] ?? 24);\n  const auctionsOn = defs.Auctions?.Enabled !== false;\n\n  if (!picked)\n    return (\n      <Popup title={t(\"pickItem\")} onClose={onClose} width={480}>\n        {currencies.length === 0 ? (\n          <EmptyState glyph=\"market\" text={t(\"noTradableCurrency\")} />\n        ) : sellable.length === 0 ? (\n          <EmptyState glyph=\"market\" text={t(\"nothingToSell\")} />\n        ) : (\n          <div\n            style={{\n              display: \"flex\",\n              flexWrap: \"wrap\",\n              gap: 10,\n              justifyContent: \"center\",\n            }}\n          >\n            {sellable.map((s) => (\n              <ItemTile\n                key={s.itemID}\n                itemID={s.itemID}\n                count={s.amount}\n                size={72}\n                onClick={() => setPicked(s)}\n              />\n            ))}\n          </div>\n        )}\n      </Popup>\n    );\n\n  const create = () =>\n    kind === \"listing\"\n      ? client.marketplace.createListing(\n          picked.itemID,\n          picked.catalogID,\n          picked.instances.length ? 1 : amount,\n          priceBundle(currency, price) as never,\n          hours,\n          picked.instances.length ? [picked.instances[0]!] : undefined,\n        )\n      : client.marketplace.createAuction(\n          picked.itemID,\n          picked.catalogID,\n          picked.instances.length ? 1 : amount,\n          \"VirtualCurrency\" as never,\n          price,\n          hours,\n          {\n            bidCurrencyID: currency,\n            itemInstanceIDs: picked.instances.length\n              ? [picked.instances[0]!]\n              : undefined,\n          },\n        );\n\n  return (\n    <Popup\n      title={catalog.itemName(picked.itemID)}\n      onClose={onClose}\n      width={440}\n    >\n      <div style={{ display: \"grid\", justifyItems: \"center\" }}>\n        <ItemTile\n          itemID={picked.itemID}\n          count={picked.instances.length ? 1 : amount}\n          size={88}\n        />\n      </div>\n      {auctionsOn ? (\n        <Tabs\n          tabs={[\n            { id: \"listing\", label: t(\"listing\") },\n            { id: \"auction\", label: t(\"auction\") },\n          ]}\n          value={kind}\n          onChange={(k) => {\n            setKind(k);\n            setHours(\n              (k === \"listing\"\n                ? listingDurations(defs)\n                : auctionDurations(defs))[0] ?? 24,\n            );\n          }}\n        />\n      ) : null}\n      {picked.instances.length === 0 && picked.amount > 1 ? (\n        <Field label={t(\"amount\")}>\n          <Stepper\n            value={amount}\n            min={1}\n            max={picked.amount}\n            onChange={setAmount}\n          />\n        </Field>\n      ) : null}\n      <Field label={kind === \"listing\" ? t(\"price\") : t(\"startingBid\")}>\n        {currencies.length > 1 ? (\n          <Tabs\n            tabs={currencies.map((c) => ({\n              id: c,\n              label: catalog.currencyName(c),\n              glyph: catalog.iconOf({ kind: \"currency\", id: c, amount: 0 }),\n            }))}\n            value={currency}\n            onChange={setCurrency}\n          />\n        ) : null}\n        <Stepper value={price} min={1} onChange={setPrice} />\n      </Field>\n      <Field label={t(\"duration\")}>\n        <Tabs\n          tabs={durations.map((h) => ({\n            id: String(h),\n            label: `${h} ${t(\"hours\")}`,\n          }))}\n          value={String(hours)}\n          onChange={(h) => setHours(Number(h))}\n        />\n      </Field>\n      {commissionPercent(defs) > 0 ? (\n        <div\n          style={{\n            ...outlined,\n            fontSize: 12,\n            color: v.textDim,\n            textAlign: \"center\",\n          }}\n        >\n          {t(\"commission\")}: {commissionPercent(defs)}%\n        </div>\n      ) : null}\n      <Act label={t(\"create\")} tone=\"gold\" run={create} onDone={onDone} />\n    </Popup>\n  );\n}\n\nfunction Field({\n  label,\n  children,\n}: {\n  label: string;\n  children: ReactNode;\n}): ReactNode {\n  return (\n    <div style={{ display: \"grid\", gap: 6 }}>\n      <div style={{ ...outlined, fontSize: 13, color: v.textDim }}>{label}</div>\n      {children}\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "model.ts",
+      "content": "// Pure helpers of the marketplace screen (Unity Alikhan/Marketplace) — covered by model.test.ts.\n// The server holds the escrow and settles every trade; these only decide what the screen shows.\n\nimport type {\n  MarketplaceDefinitions,\n  MarketplaceOfferView,\n} from \"@idosgames/core\";\nimport {\n  bundleLines,\n  type ItemDefinitionView,\n  type ResourceLine,\n} from \"@idosgames/react/ui\";\n\n/** The price of a listing, as lines. */\nexport function offerPrice(offer: MarketplaceOfferView): ResourceLine[] {\n  return bundleLines(offer.Price as never);\n}\n\n/** The single currency of a price (listings are priced in one currency in this screen). */\nexport function priceAmount(offer: MarketplaceOfferView): number {\n  return offerPrice(offer)[0]?.amount ?? 0;\n}\n\n/** Offers for one item, cheapest listing first, then auctions ending soonest. */\nexport function sortOffers(\n  offers: MarketplaceOfferView[],\n): MarketplaceOfferView[] {\n  const listings = offers\n    .filter((o) => o.OfferType === \"Listing\")\n    .sort((a, b) => priceAmount(a) - priceAmount(b));\n  const auctions = offers\n    .filter((o) => o.OfferType === \"Auction\")\n    .sort((a, b) =>\n      String(a.ExpiresAt ?? \"\").localeCompare(String(b.ExpiresAt ?? \"\")),\n    );\n  return [\n    ...listings,\n    ...auctions,\n    ...offers.filter(\n      (o) => o.OfferType !== \"Listing\" && o.OfferType !== \"Auction\",\n    ),\n  ];\n}\n\n/** The lowest bid the server accepts next: the current bid plus the configured step (or the start). */\nexport function minNextBid(\n  offer: MarketplaceOfferView,\n  defs: MarketplaceDefinitions | null | undefined,\n): number {\n  const a = offer.Auction;\n  const current = Number(a?.CurrentBid ?? 0);\n  if (!a || current <= 0 || !a.CurrentBidderID)\n    return Math.max(1, Number(a?.StartingBid ?? 1));\n  // The engine's rule: step = max(ceil(current × fraction), MinBidStepAbsolute); 0.05 = 5%.\n  const fraction = Number(defs?.Auctions?.MinBidStepPercent ?? 0.05);\n  const abs = Number(defs?.Auctions?.MinBidStepAbsolute ?? 0);\n  const step = Math.max(1, abs, Math.ceil(current * fraction));\n  return current + step;\n}\n\n/** Durations the title allows for a listing (hours), with a sane fallback. */\nexport function listingDurations(\n  defs: MarketplaceDefinitions | null | undefined,\n): number[] {\n  const allowed = (defs?.Listings?.AllowedDurationsHours ?? []).filter(\n    (h) => h > 0,\n  );\n  return allowed.length > 0 ? [...allowed].sort((a, b) => a - b) : [24, 72];\n}\n\n/** Durations for an auction within the title's bounds. */\nexport function auctionDurations(\n  defs: MarketplaceDefinitions | null | undefined,\n): number[] {\n  const min = Math.max(1, Number(defs?.Auctions?.MinDurationHours ?? 1));\n  const max = Math.max(min, Number(defs?.Auctions?.MaxDurationHours ?? 72));\n  return [...new Set([min, Math.min(max, 24), max])]\n    .filter((h) => h >= min && h <= max)\n    .sort((a, b) => a - b);\n}\n\n/** Commission the seller pays, in percent for display. The config holds a FRACTION (0.05 = 5%). */\nexport function commissionPercent(\n  defs: MarketplaceDefinitions | null | undefined,\n): number {\n  return Math.round(Number(defs?.Commission?.Percent ?? 0.05) * 1000) / 10;\n}\n\nexport interface SellableItem {\n  itemID: string;\n  catalogID: string;\n  amount: number;\n  /** Unstackable: instance ids the player can put up (not equipped). */\n  instances: string[];\n}\n\n/** Owned items the player may sell: tradable definitions, instances that are not worn. */\nexport function sellableItems(\n  inventory:\n    | {\n        Items?: Record<\n          string,\n          { StackableAmount?: number; TotalAmount?: number } | null\n        > | null;\n        UnstackableItems?: Record<\n          string,\n          { ItemID?: string; EquippedSlot?: unknown } | null\n        > | null;\n      }\n    | null\n    | undefined,\n  items: Map<\n    string,\n    ItemDefinitionView & { CatalogID?: string; IsTradable?: boolean | null }\n  >,\n): SellableItem[] {\n  const out = new Map<string, SellableItem>();\n  for (const [id, t] of Object.entries(inventory?.Items ?? {})) {\n    const def = items.get(id);\n    if (!def || def.IsTradable === false || def.IsStackable === false) continue;\n    const amount = Number(t?.StackableAmount ?? t?.TotalAmount ?? 0);\n    if (amount > 0)\n      out.set(id, {\n        itemID: id,\n        catalogID: def.CatalogID ?? \"Item\",\n        amount,\n        instances: [],\n      });\n  }\n  for (const [instanceID, inst] of Object.entries(\n    inventory?.UnstackableItems ?? {},\n  )) {\n    if (!inst?.ItemID || inst.EquippedSlot) continue;\n    const def = items.get(inst.ItemID);\n    if (!def || def.IsTradable === false) continue;\n    const entry = out.get(inst.ItemID) ?? {\n      itemID: inst.ItemID,\n      catalogID: def.CatalogID ?? \"Item\",\n      amount: 0,\n      instances: [],\n    };\n    entry.instances.push(instanceID);\n    entry.amount = entry.instances.length;\n    out.set(inst.ItemID, entry);\n  }\n  return [...out.values()].sort((a, b) => a.itemID.localeCompare(b.itemID));\n}\n\n/** Listings and auctions of a market group. The server fills CountsByType (the *Count fields are\n *  optional mirrors of it), so both are read. */\nexport function groupCounts(g: {\n  CountsByType?: Partial<Record<string, number>> | null;\n  ListingCount?: number | null;\n  AuctionCount?: number | null;\n}): { listings: number; auctions: number } {\n  return {\n    listings: Number(g.ListingCount ?? g.CountsByType?.Listing ?? 0),\n    auctions: Number(g.AuctionCount ?? g.CountsByType?.Auction ?? 0),\n  };\n}\n\n/** Currencies a lot can be priced in: the engine refuses one not tradable between players. */\nexport function tradableCurrencies(\n  currencies: Record<\n    string,\n    { Permissions?: { IsTradable?: boolean | null } | null } | null | undefined\n  >,\n): string[] {\n  return Object.entries(currencies)\n    .filter(([, c]) => c?.Permissions?.IsTradable === true)\n    .map(([id]) => id);\n}\n\n/** A price bundle of one currency. */\nexport function priceBundle(\n  currencyID: string,\n  amount: number,\n): {\n  Entries: Array<{\n    Type: \"VirtualCurrency\";\n    CurrencyID: string;\n    Amount: number;\n  }>;\n} {\n  return {\n    Entries: [\n      {\n        Type: \"VirtualCurrency\",\n        CurrencyID: currencyID,\n        Amount: Math.max(1, Math.floor(amount)),\n      },\n    ],\n  };\n}\n\n/** Badge of the marketplace: things to claim + incoming trades waiting for an answer. */\nexport function marketplaceBadge(\n  state:\n    | { Claimables?: unknown[] | null; IncomingTrades?: unknown[] | null }\n    | null\n    | undefined,\n): number {\n  return (\n    (state?.Claimables?.length ?? 0) + (state?.IncomingTrades?.length ?? 0)\n  );\n}\n\n/** Whether the title's marketplace is set up and not switched off — else the lobby hides the tab. */\nexport function hasTitleData(\n  section: { Enabled?: boolean | null } | null | undefined,\n): boolean {\n  return section != null && section.Enabled !== false;\n}\n"
+    },
+    {
+      "path": "module.ts",
+      "content": "import { createElement, useEffect } from \"react\";\nimport {\n  defineModule,\n  type FeatureRegistry,\n  type Module,\n} from \"@idosgames/module-sdk\";\nimport { useIDosGamesClient } from \"@idosgames/react\";\nimport { configSection } from \"@idosgames/react/ui\";\nimport { makeMarketplaceScreen } from \"./MarketplaceScreen\";\nimport { hasTitleData, marketplaceBadge } from \"./model\";\nimport { t } from \"./i18n\";\n\n// The marketplace as a feature of the game. Badge: things to claim (won lots, expired escrow) and\n// incoming trades waiting for an answer — read once at start and after every marketplace action.\nexport const marketplaceModule: Module = defineModule({\n  id: \"marketplace\",\n  meta: { name: \"Marketplace\", type: \"app\", engine: \"dom\" },\n  setup(ctx) {\n    ctx.features.register({\n      id: \"marketplace\",\n      label: t(\"title\"),\n      icon: \"market\",\n      group: \"economy\",\n      order: 70,\n      available: false,\n      Screen: makeMarketplaceScreen(ctx.features),\n    });\n    ctx.features.setAvailable(\n      \"marketplace\",\n      hasTitleData(\n        configSection<{ Enabled?: boolean | null }>(ctx.client, \"Marketplace\"),\n      ),\n      \"the marketplace is not set up on the title, or switched off\",\n    );\n    ctx.registerPanel({\n      id: \"badge\",\n      slot: \"modal\",\n      activeOnly: false,\n      component: makeBadgeWatcher(ctx.features),\n    });\n    ctx.exposeToAgent({\n      state: () => ({ ui: \"dom\", feature: \"marketplace\" }),\n      describeActions: {},\n    });\n  },\n});\n\nfunction makeBadgeWatcher(features: FeatureRegistry) {\n  return function MarketplaceBadge() {\n    const client = useIDosGamesClient();\n    useEffect(() => {\n      // A title without the section has no marketplace — no request at all.\n      if (!configSection(client, \"Marketplace\")) return;\n      const check = () =>\n        void client.marketplace\n          .getMyState()\n          .then(\n            (res) =>\n              res.ok &&\n              features.setBadge(\"marketplace\", marketplaceBadge(res.data)),\n          );\n      check();\n      const id = setInterval(check, 5 * 60_000);\n      return () => clearInterval(id);\n    }, [client]);\n    return createElement(\"span\", { hidden: true });\n  };\n}\n"
+    },
+    {
+      "path": "module.meta.json",
+      "content": "{\n  \"id\": \"marketplace\",\n  \"type\": \"feature\",\n  \"summary\": \"Marketplace screen for any game: player listings and auctions, selling, bids, direct trades, claims and history.\",\n  \"description\": \"A ready player marketplace (Unity Alikhan/Marketplace) for ANY game, built on the @idosgames/react/ui kit and client.marketplace. Tabs: the market (items grouped with their cheapest price), my lots, my bids, direct trades, things to claim and history. Everything detailed is a popup: an item's offers (cheapest listing first, then auctions ending soonest), one offer (buy, bid with the engine's minimum next bid, cancel your own), selling (pick an item — only tradable, never a worn one — then listing or auction, amount, price in a currency tradable between players, duration and the commission), and incoming trades (accept / decline). The server holds the escrow and settles every trade. Registers the 'marketplace' feature; its badge counts things to claim and trades waiting. Ships title-seed.json: listings and auctions for currencies with a 5% commission.\",\n  \"provides\": [\n    \"player marketplace screen\",\n    \"listings and auctions\",\n    \"sell popup with price and duration\",\n    \"bids with the minimum next bid\",\n    \"direct trades\",\n    \"claims and history\",\n    \"marketplace badge\",\n    \"demo marketplace rules\"\n  ],\n  \"tags\": [\n    \"marketplace\",\n    \"trading\",\n    \"auction\",\n    \"listing\",\n    \"p2p\",\n    \"ui\",\n    \"screen\",\n    \"economy\"\n  ],\n  \"author\": {\n    \"name\": \"iDos Games\",\n    \"url\": \"https://idosgames.com\"\n  },\n  \"version\": \"0.1.0\"\n}\n"
+    }
+  ]
+}

package/registry/modules/mini-game.json

@@ -0,0 +1,69 @@
+{
+  "id": "mini-game",
+  "meta": {
+    "name": "Mini-game",
+    "type": "game",
+    "engine": "dom",
+    "genre": "casual"
+  },
+  "catalog": {
+    "type": "template",
+    "summary": "The smallest complete game: a 15-second 'catch the stars' round launched from the lobby's Play button, with a leaderboard score.",
+    "description": "A tiny game of its own mode (React/DOM, no engine): tap as many stars as you can in 15 seconds, gold stars are worth 3. The score goes to the title's leaderboard, and a round counts for quests that ask for games_played, for timed events that pay for the 'play_round' action and for season chains open to clients. The platform gives it to a new title when no other game fits the idea — it shows where a game plugs into the base (sign-in → lobby → Play) and is meant to be replaced by the real game. No demo settings of its own: it plays on the base's world.",
+    "provides": [
+      "a small tap game launched from the lobby",
+      "score submitted to the leaderboard",
+      "rounds counted by quests, events and the season",
+      "placeholder game to replace with the real one"
+    ],
+    "tags": [
+      "starter",
+      "mini-game",
+      "casual",
+      "tap",
+      "leaderboard"
+    ],
+    "author": {
+      "name": "iDos Games",
+      "url": "https://idosgames.com"
+    },
+    "version": "0.1.0"
+  },
+  "dependencies": {
+    "@idosgames/core": "0.19.1",
+    "@idosgames/module-sdk": "0.7.0",
+    "@idosgames/react": "0.3.0",
+    "react": "19.2.7"
+  },
+  "contentHash": "26089593df1b939aee3317743caeda47f82971bfd85dbd73eb9e95a9bc5e3d5c",
+  "files": [
+    {
+      "path": "i18n.ts",
+      "content": "import { makeT } from \"@idosgames/react/ui\";\n\n// Strings of the mini-game. The leaderboard's name is the publisher's word (title config).\n\nconst EN = {\n  title: \"Star catch\",\n  play: \"Play\",\n  playAgain: \"Play again\",\n  tapStars: \"Tap the stars!\",\n  timeLeft: \"Time\",\n  score: \"Score\",\n  yourScore: \"Your score\",\n  submitted: \"Submitted to the leaderboard\",\n  seasonStatus: \"season status\",\n  toTable: \"Leaderboard\",\n  best: \"Tap as many stars as you can in 15 seconds. Gold stars are worth 3.\",\n} as const;\n\nexport type StringKey = keyof typeof EN;\n\nexport const t = makeT<StringKey>(EN, {\n  title: \"Ловец звёзд\",\n  play: \"Играть\",\n  playAgain: \"Ещё раз\",\n  tapStars: \"Ловите звёзды!\",\n  timeLeft: \"Время\",\n  score: \"Очки\",\n  yourScore: \"Ваш результат\",\n  submitted: \"Результат отправлен в таблицу\",\n  seasonStatus: \"статуса сезона\",\n  toTable: \"Таблица лидеров\",\n  best: \"Поймайте как можно больше звёзд за 15 секунд. Золотая — 3 очка.\",\n});\n"
+    },
+    {
+      "path": "index.ts",
+      "content": "// @idosgames/mod-mini-game — \"Star catch\", the smallest complete game module: a 15-second tap round\n// launched from the lobby's Play button, with a leaderboard score.\n//\n// Primary export is the module manifest; the pieces are exported too, so a project can reuse the\n// round inside its own game after copying this into src/modules/.\n\nexport { miniGameModule } from \"./module\";\nexport { makeMiniGamePanel } from \"./MiniGamePanel\";\nexport { MiniGame } from \"./MiniGame\";\nexport * from \"./model\";\n"
+    },
+    {
+      "path": "MiniGame.tsx",
+      "content": "import { useEffect, useRef, useState, type ReactNode } from \"react\";\nimport {\n  Button,\n  Icon,\n  outlined,\n  panel,\n  useSound,\n  v,\n} from \"@idosgames/react/ui\";\nimport { t } from \"./i18n\";\n\n// \"Tap the stars\": a 15-second round that produces a score for the leaderboard. Deliberately tiny —\n// the placeholder a project replaces with its real game, keeping the same contract: play, then hand\n// the score to onFinish (the play screen submits it and reports the round to quests).\n\nconst ROUND_MS = 15_000;\nconst SPAWN_MS = 520;\nconst LIFE_MS = 1_150;\n\ninterface Star {\n  id: number;\n  x: number;\n  y: number;\n  golden: boolean;\n  bornAt: number;\n}\n\nexport function MiniGame({\n  onFinish,\n  onCancel,\n  height = 380,\n}: {\n  onFinish: (score: number) => void;\n  onCancel: () => void;\n  height?: number;\n}): ReactNode {\n  const play = useSound();\n  const [stars, setStars] = useState<Star[]>([]);\n  const [score, setScore] = useState(0);\n  const [leftMs, setLeftMs] = useState(ROUND_MS);\n  const [pops, setPops] = useState<\n    Array<{ id: number; x: number; y: number; value: number }>\n  >([]);\n  const scoreRef = useRef(0);\n  const nextId = useRef(1);\n  const finished = useRef(false);\n  // Latest callback without restarting the round when the parent re-renders.\n  const finish = useRef(onFinish);\n  finish.current = onFinish;\n\n  useEffect(() => {\n    const started = performance.now();\n    const spawn = setInterval(() => {\n      const now = performance.now();\n      setStars((list) => [\n        ...list.filter((s) => now - s.bornAt < LIFE_MS),\n        {\n          id: nextId.current++,\n          x: 8 + Math.random() * 78,\n          y: 10 + Math.random() * 72,\n          golden: Math.random() < 0.15,\n          bornAt: now,\n        },\n      ]);\n    }, SPAWN_MS);\n    const clock = setInterval(() => {\n      const left = Math.max(0, ROUND_MS - (performance.now() - started));\n      setLeftMs(left);\n      if (left === 0 && !finished.current) {\n        finished.current = true;\n        clearInterval(spawn);\n        clearInterval(clock);\n        finish.current(scoreRef.current);\n      }\n    }, 100);\n    return () => {\n      clearInterval(spawn);\n      clearInterval(clock);\n    };\n  }, []);\n\n  const hit = (star: Star) => {\n    const value = star.golden ? 3 : 1;\n    play(star.golden ? \"coin\" : \"countTick\");\n    scoreRef.current += value;\n    setScore(scoreRef.current);\n    setStars((list) => list.filter((s) => s.id !== star.id));\n    const popID = nextId.current++;\n    setPops((list) => [...list, { id: popID, x: star.x, y: star.y, value }]);\n    setTimeout(\n      () => setPops((list) => list.filter((p) => p.id !== popID)),\n      600,\n    );\n  };\n\n  return (\n    <div\n      style={{\n        ...panel,\n        position: \"relative\",\n        height: `min(${height}px, 70vh)`,\n        minHeight: 300,\n        overflow: \"hidden\",\n        background:\n          \"radial-gradient(circle at 50% 30%, #3b47b8 0%, #151a52 75%)\",\n        touchAction: \"manipulation\",\n        userSelect: \"none\",\n      }}\n    >\n      <div\n        style={{\n          position: \"absolute\",\n          top: 10,\n          left: 12,\n          right: 12,\n          display: \"flex\",\n          justifyContent: \"space-between\",\n          zIndex: 2,\n        }}\n      >\n        <span style={{ ...outlined, fontSize: 18 }}>\n          {t(\"score\")}: {score}\n        </span>\n        <span\n          style={{\n            ...outlined,\n            fontSize: 18,\n            color: leftMs < 4000 ? v.red : v.text,\n          }}\n        >\n          {t(\"timeLeft\")}: {Math.ceil(leftMs / 1000)}\n        </span>\n      </div>\n      <div\n        style={{\n          position: \"absolute\",\n          top: 40,\n          left: 0,\n          right: 0,\n          textAlign: \"center\",\n          ...outlined,\n          fontSize: 14,\n          color: v.textDim,\n          opacity: score === 0 ? 1 : 0,\n          transition: \"opacity .4s\",\n        }}\n      >\n        {t(\"tapStars\")}\n      </div>\n      {stars.map((s) => (\n        <button\n          key={s.id}\n          type=\"button\"\n          aria-label=\"star\"\n          onPointerDown={() => hit(s)}\n          style={{\n            position: \"absolute\",\n            left: `${s.x}%`,\n            top: `${s.y}%`,\n            width: 56,\n            height: 56,\n            marginLeft: -28,\n            marginTop: -28,\n            border: \"none\",\n            background: \"none\",\n            padding: 0,\n            cursor: \"pointer\",\n            animation: `idos-star ${v.normal} ease-out`,\n          }}\n        >\n          <Icon\n            glyph=\"star\"\n            size={s.golden ? 56 : 44}\n            color={s.golden ? \"#ffe066\" : \"#fff27a\"}\n          />\n        </button>\n      ))}\n      {pops.map((p) => (\n        <span\n          key={p.id}\n          style={{\n            position: \"absolute\",\n            left: `${p.x}%`,\n            top: `${p.y}%`,\n            ...outlined,\n            fontSize: 22,\n            color: v.gold,\n            pointerEvents: \"none\",\n            animation: \"idos-rise-in .6s ease reverse\",\n          }}\n        >\n          +{p.value}\n        </span>\n      ))}\n      <div\n        style={{\n          position: \"absolute\",\n          bottom: 10,\n          left: 0,\n          right: 0,\n          display: \"flex\",\n          justifyContent: \"center\",\n        }}\n      >\n        <Button tone=\"grey\" size=\"sm\" onClick={onCancel}>\n          ✕\n        </Button>\n      </div>\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "MiniGamePanel.tsx",
+      "content": "import {\n  useCallback,\n  useState,\n  type ComponentType,\n  type ReactNode,\n} from \"react\";\nimport type { IDosGamesClient } from \"@idosgames/core\";\nimport type { FeatureRegistry } from \"@idosgames/module-sdk\";\nimport { useIDosGamesClient } from \"@idosgames/react\";\nimport {\n  Button,\n  Icon,\n  configSection,\n  errorText,\n  formatAmount,\n  outlined,\n  panel,\n  screenBackground,\n  useCatalog,\n  useGameLayout,\n  useToast,\n  useUiKit,\n  v,\n} from \"@idosgames/react/ui\";\nimport { MiniGame } from \"./MiniGame\";\nimport {\n  GAMES_PLAYED_METRIC,\n  PLAY_ROUND_ACTION,\n  ROUND_STATUS,\n  eventsCountingRounds,\n  pickLeaderboard,\n  questsCountGames,\n  seasonChainsForRounds,\n  type LeaderboardSection,\n  type QuestSection,\n  type SeasonSection,\n  type TimedEventSection,\n} from \"./model\";\nimport { t } from \"./i18n\";\n\n// The mini-game's mode — the whole screen while it is on (the lobby's \"Play\" starts it, the base's\n// round button top-left returns to the lobby). A round submits its score to the title's leaderboard,\n// reports itself to quests that count rounds, and feeds the events and seasons that pay for a round;\n// the table itself is the leaderboard module's screen (\"Leaderboard\" opens it through ctx.features).\n\nexport function makeMiniGamePanel(features: FeatureRegistry): ComponentType {\n  return function MiniGamePanel(): ReactNode {\n    return (\n      <div\n        className=\"idos-scroll\"\n        style={{\n          position: \"absolute\",\n          inset: 0,\n          overflowY: \"auto\",\n          background: screenBackground,\n          fontFamily: v.font,\n          color: v.text,\n          // Room for the base's \"To the lobby\" button in the top-left corner.\n          padding: \"64px 14px 24px\",\n          pointerEvents: \"auto\",\n        }}\n      >\n        <div style={{ maxWidth: 760, margin: \"0 auto\" }}>\n          <Round features={features} />\n        </div>\n      </div>\n    );\n  };\n}\n\nfunction Round({ features }: { features: FeatureRegistry }): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const kit = useUiKit();\n  const layout = useGameLayout();\n  const [playing, setPlaying] = useState(false);\n  const [result, setResult] = useState<number | null>(null);\n  const [bonus, setBonus] = useState<string[]>([]);\n  const catalog = useCatalog();\n  const board = pickLeaderboard(\n    configSection<LeaderboardSection>(client, \"Leaderboard\"),\n  );\n\n  const finish = useCallback(\n    async (score: number) => {\n      setPlaying(false);\n      setResult(score);\n      kit.play(score > 0 ? \"levelUp\" : \"notify\");\n      if (board && score > 0) {\n        const res = await client.leaderboard.submitScore(\n          board.LeaderboardID,\n          score,\n        );\n        if (!res.ok) toast(errorText(res.error), \"error\");\n      }\n      // One round played — only if a quest counts rounds (otherwise the server refuses the metric).\n      if (questsCountGames(configSection<QuestSection>(client, \"Quest\")))\n        await client.quest.addQuestProgress(GAMES_PLAYED_METRIC, 1);\n      if (score > 0) setBonus(await rewardRound(client, catalog.localize));\n    },\n    [client, board, toast, kit, catalog],\n  );\n\n  if (playing)\n    return (\n      <MiniGame\n        height={layout === \"desktop\" ? 560 : layout === \"tablet\" ? 480 : 380}\n        onFinish={(s) => void finish(s)}\n        onCancel={() => setPlaying(false)}\n      />\n    );\n\n  return (\n    <div\n      className=\"idos-shine\"\n      style={{\n        ...panel,\n        padding: 20,\n        display: \"grid\",\n        gap: 12,\n        justifyItems: \"center\",\n        background: \"linear-gradient(180deg, #5a3fd0 0%, #25207a 100%)\",\n        maxWidth: 520,\n        margin: \"0 auto\",\n      }}\n    >\n      <div className=\"idos-bounce\">\n        <Icon glyph=\"star\" size={72} />\n      </div>\n      <div\n        style={{\n          ...outlined,\n          fontSize: 15,\n          textAlign: \"center\",\n          color: v.textDim,\n        }}\n      >\n        {t(\"best\")}\n      </div>\n      {result !== null ? (\n        <div\n          style={{\n            ...outlined,\n            fontSize: 18,\n            color: v.gold,\n            animation: `idos-pop-in ${v.slow} ease-out both`,\n          }}\n        >\n          {t(\"yourScore\")}: {formatAmount(result)}\n          {result > 0 && board ? (\n            <div\n              style={{ fontSize: 13, color: v.textDim, textAlign: \"center\" }}\n            >\n              {t(\"submitted\")}\n            </div>\n          ) : null}\n          {bonus.map((line) => (\n            <div\n              key={line}\n              style={{ fontSize: 14, color: v.green, textAlign: \"center\" }}\n            >\n              {line}\n            </div>\n          ))}\n        </div>\n      ) : null}\n      <Button\n        attract\n        size=\"lg\"\n        style={{ minWidth: 180 }}\n        onClick={() => {\n          setResult(null);\n          setBonus([]);\n          setPlaying(true);\n        }}\n        data-tutorial-anchor=\"play:start\"\n      >\n        ▶ {result === null ? t(\"play\") : t(\"playAgain\")}\n      </Button>\n      {board && features.get(\"leaderboard\")?.available ? (\n        <Button\n          tone=\"blue\"\n          size=\"sm\"\n          onClick={() =>\n            features.open(\"leaderboard\", {\n              leaderboardID: board.LeaderboardID,\n            })\n          }\n        >\n          <Icon glyph=\"trophy\" size={18} /> {t(\"toTable\")}\n        </Button>\n      ) : null}\n    </div>\n  );\n}\n\n/**\n * A round's share of the title's live-ops: tokens of every active event that pays for a round (a\n * client-safe CustomAction, capped per day by the event) and status in every season chain open to\n * clients. Returns what was granted, for the result card. Best-effort: a refusal (a cap reached,\n * no active season) just grants nothing.\n */\nasync function rewardRound(\n  client: IDosGamesClient,\n  localize: (text: string | null | undefined) => string,\n): Promise<string[]> {\n  const lines: string[] = [];\n  const eventIDs = eventsCountingRounds(\n    configSection<TimedEventSection>(client, \"TimedEvent\"),\n  );\n  if (eventIDs.length > 0) {\n    const active = await client.timedEvent.getActiveEvents();\n    for (const e of active.ok ? (active.data.ActiveEvents ?? []) : []) {\n      if (\n        !e.TimedEventID ||\n        !eventIDs.includes(e.TimedEventID) ||\n        e.CanEarn === false ||\n        !e.Type\n      )\n        continue;\n      const res = await client.timedEvent.grantTokens(\n        e.Type,\n        e.TimedEventID,\n        \"CustomAction\",\n        undefined,\n        undefined,\n        { ActionName: PLAY_ROUND_ACTION },\n      );\n      const op = res.ok\n        ? (res.data.Grant?.Standard?.EventTokens?.[0] as\n            { Applied?: number; Amount?: number } | undefined)\n        : undefined;\n      const amount = Number(op?.Applied ?? op?.Amount ?? 0);\n      if (amount > 0)\n        lines.push(\n          `+${formatAmount(amount)} ${localize(e.Content?.Token?.DisplayName ?? e.Content?.DisplayName ?? e.TimedEventID)}`,\n        );\n    }\n  }\n  for (const chain of seasonChainsForRounds(\n    configSection<SeasonSection>(client, \"Season\"),\n  )) {\n    const res = await client.season.grantStatusTokens(chain, ROUND_STATUS);\n    if (res.ok && Number(res.data.AmountGranted ?? 0) > 0)\n      lines.push(\n        `+${formatAmount(Number(res.data.AmountGranted))} ${t(\"seasonStatus\")}`,\n      );\n  }\n  return lines;\n}\n"
+    },
+    {
+      "path": "model.ts",
+      "content": "// Pure helpers of the mini-game — covered by model.test.ts.\n\n/** Metric the mini-game reports once per finished round. A quest counts it only if it asks for it. */\nexport const GAMES_PLAYED_METRIC = \"games_played\";\n\n/** Leaderboard the mini-game submits to when the title has it; otherwise the first enabled one. */\nexport const PREFERRED_LEADERBOARD = \"weekly_score\";\n\nexport interface LeaderboardSection {\n  Definitions?: Record<\n    string,\n    {\n      LeaderboardID?: string;\n      DisplayName?: string | null;\n      IsEnabled?: boolean | null;\n      ScoreSources?: unknown[] | null;\n    } | null\n  > | null;\n}\n\n/**\n * The leaderboard the mini-game plays for: the preferred id if enabled, else the first enabled one.\n * A board fed by its own sources (invites, purchases…) is not a score table — the server fills it\n * and refuses a submitted score, so the mini-game never picks it.\n */\nexport function pickLeaderboard(\n  section: LeaderboardSection | undefined,\n): { LeaderboardID: string; DisplayName?: string | null } | null {\n  const defs = Object.entries(section?.Definitions ?? {})\n    .map(([id, def]) =>\n      def ? { ...def, LeaderboardID: def.LeaderboardID ?? id } : null,\n    )\n    .filter(\n      (\n        d,\n      ): d is {\n        LeaderboardID: string;\n        DisplayName?: string | null;\n        IsEnabled?: boolean | null;\n      } => d !== null && d.IsEnabled !== false,\n    )\n    .filter(\n      (d) =>\n        ((d as { ScoreSources?: unknown[] | null }).ScoreSources ?? [])\n          .length === 0,\n    );\n  return (\n    defs.find((d) => d.LeaderboardID === PREFERRED_LEADERBOARD) ??\n    defs.sort((a, b) => a.LeaderboardID.localeCompare(b.LeaderboardID))[0] ??\n    null\n  );\n}\n\nexport interface QuestSection {\n  Quests?: Record<\n    string,\n    {\n      Objectives?: Record<\n        string,\n        { MetricID?: string | null; Source?: string } | null\n      > | null;\n    } | null\n  > | null;\n}\n\n/** Whether some quest counts the mini-game's rounds — only then is the metric worth reporting. */\nexport function questsCountGames(section: QuestSection | undefined): boolean {\n  return Object.values(section?.Quests ?? {}).some((q) =>\n    Object.values(q?.Objectives ?? {}).some(\n      (o) =>\n        o?.MetricID === GAMES_PLAYED_METRIC &&\n        (o.Source ?? \"ClientApi\") === \"ClientApi\",\n    ),\n  );\n}\n\n// ── A round feeds the title's events and seasons ─────────────────────────────────────────────\n// Found in the config, so the mini-game needs neither the events nor the season module installed.\n\n/** The CustomAction a round of the mini-game reports to timed events. */\nexport const PLAY_ROUND_ACTION = \"play_round\";\n/** Status a round grants to every season chain open to clients. */\nexport const ROUND_STATUS = 10;\n\nexport interface TimedEventSection {\n  Definitions?: Record<\n    string,\n    {\n      Content?: EventContentView | null;\n      Events?: Array<{ Content?: EventContentView | null } | null> | null;\n    } | null\n  > | null;\n}\ntype EventContentView = {\n  TokenSources?: Array<{\n    SourceType?: string | null;\n    Params?: Record<string, string> | null;\n  } | null> | null;\n};\n\nfunction countsRounds(content: EventContentView | null | undefined): boolean {\n  return (content?.TokenSources ?? []).some(\n    (s) =>\n      s?.SourceType === \"CustomAction\" &&\n      s.Params?.ActionName === PLAY_ROUND_ACTION,\n  );\n}\n\n/** Events (by id) whose token sources pay for a round — own content or any phase of a chain. */\nexport function eventsCountingRounds(\n  section: TimedEventSection | undefined,\n): string[] {\n  return Object.entries(section?.Definitions ?? {})\n    .filter(\n      ([, d]) =>\n        d &&\n        (countsRounds(d.Content) ||\n          (d.Events ?? []).some((p) => countsRounds(p?.Content))),\n    )\n    .map(([id]) => id);\n}\n\nexport interface SeasonSection {\n  Chains?: Record<\n    string,\n    { GrantTokensAccessMode?: string | null } | null\n  > | null;\n}\n\n/**\n * Season chains the client may grant status to. Only an explicit \"Both\" / \"ClientOnly\" opens a\n * chain: the engine's default is ServerOnly, so a missing field means \"server only\" too.\n */\nexport function seasonChainsForRounds(\n  section: SeasonSection | undefined,\n): string[] {\n  return Object.entries(section?.Chains ?? {})\n    .filter(\n      ([, c]) =>\n        c?.GrantTokensAccessMode === \"Both\" ||\n        c?.GrantTokensAccessMode === \"ClientOnly\",\n    )\n    .map(([id]) => id);\n}\n"
+    },
+    {
+      "path": "module.ts",
+      "content": "import { defineModule, type Module } from \"@idosgames/module-sdk\";\nimport { makeMiniGamePanel } from \"./MiniGamePanel\";\nimport { t } from \"./i18n\";\n\n// The smallest complete game module: a mode of its own (a route + one full-screen panel, no scene)\n// that the base's lobby offers as \"Play\". It is what a new title gets when no other game fits the idea\n// — the placeholder the real game replaces, with the same contract: register a route, draw the mode,\n// and leave the lobby, balances and wallet to the base.\nexport const miniGameModule: Module = defineModule({\n  id: \"mini-game\",\n  meta: {\n    name: \"Mini-game\",\n    type: \"game\",\n    genre: \"casual\",\n    engine: \"dom\",\n  },\n  setup(ctx) {\n    ctx.registerRoute({ id: \"mini-game\", label: t(\"title\"), icon: \"⭐\" });\n    ctx.registerPanel({\n      id: \"round\",\n      slot: \"overlay\",\n      component: makeMiniGamePanel(ctx.features),\n    });\n\n    // The round is ordinary React in the DOM: an agent reads it and presses its buttons like a person.\n    ctx.exposeToAgent({\n      state: () => ({ ui: \"dom\", mode: ctx.modes.current() }),\n      describeActions: {},\n    });\n  },\n});\n"
+    },
+    {
+      "path": "module.meta.json",
+      "content": "{\n  \"id\": \"mini-game\",\n  \"type\": \"template\",\n  \"summary\": \"The smallest complete game: a 15-second 'catch the stars' round launched from the lobby's Play button, with a leaderboard score.\",\n  \"description\": \"A tiny game of its own mode (React/DOM, no engine): tap as many stars as you can in 15 seconds, gold stars are worth 3. The score goes to the title's leaderboard, and a round counts for quests that ask for games_played, for timed events that pay for the 'play_round' action and for season chains open to clients. The platform gives it to a new title when no other game fits the idea — it shows where a game plugs into the base (sign-in → lobby → Play) and is meant to be replaced by the real game. No demo settings of its own: it plays on the base's world.\",\n  \"provides\": [\n    \"a small tap game launched from the lobby\",\n    \"score submitted to the leaderboard\",\n    \"rounds counted by quests, events and the season\",\n    \"placeholder game to replace with the real one\"\n  ],\n  \"tags\": [\"starter\", \"mini-game\", \"casual\", \"tap\", \"leaderboard\"],\n  \"author\": {\n    \"name\": \"iDos Games\",\n    \"url\": \"https://idosgames.com\"\n  },\n  \"version\": \"0.1.0\"\n}\n"
+    }
+  ]
+}

package/registry/modules/multiplayer.json

@@ -0,0 +1,74 @@
+{
+  "id": "multiplayer",
+  "meta": {
+    "name": "Multiplayer",
+    "type": "app",
+    "engine": "dom"
+  },
+  "catalog": {
+    "type": "feature",
+    "summary": "The rooms system for any game: open rooms of the app's online games, public or private rooms by invite, members, ready and chat — the host takes the whole room into a game.",
+    "description": "A ready multiplayer lobby (engine Multiplayer) for ANY game, built on the @idosgames/react/ui kit, client.multiplayer and RealtimeSession (@idosgames/core/realtime). It OWNS the player's room and its WebRTC session: the rooms of the games this app plays online (each room remembers its game), 'Create a room' for one of them (name, 2/4/8 players, public or private with an invite code, the game's own room settings), joining by invite, members (host, ready, offline), 'Ready', the room chat (server relay, when the game has no chat of its own), removing a member and leaving. The host's 'Play' takes the whole room into the game: every device switches to the game's mode and the game gets the room in its start() — games never create, list or join rooms themselves. A game plays online by registering in ctx.multiplayer (registerGame: topology, chat mode, room size, joinInProgress for late joiners, room settings, start(room)); the lobby then draws 'With friends' next to its 'Play'. Opened with { mode } the screen shows one game's rooms, with { mode, create: true } straight on 'Create'. Registers the 'multiplayer' feature, shown while multiplayer is on for the title and the app has a game that plays online. Ships title-seed.json: multiplayer on, up to 8 players per room.",
+    "provides": [
+      "multiplayer rooms lobby",
+      "rooms of one game",
+      "public and private rooms by invite",
+      "room settings of the game",
+      "room members with ready and host",
+      "room chat",
+      "host starts the game for the whole room",
+      "late joiners into a running game"
+    ],
+    "tags": [
+      "multiplayer",
+      "rooms",
+      "lobby",
+      "realtime",
+      "social",
+      "ui",
+      "screen"
+    ],
+    "author": {
+      "name": "iDos Games",
+      "url": "https://idosgames.com"
+    },
+    "version": "0.1.0"
+  },
+  "dependencies": {
+    "@idosgames/core": "0.19.1",
+    "@idosgames/module-sdk": "0.7.0",
+    "@idosgames/react": "0.3.0",
+    "react": "19.2.7"
+  },
+  "contentHash": "b318338a4342f30fd665899803aa10ce32764cc1afb3b709b297e5bf329cdeb7",
+  "files": [
+    {
+      "path": "i18n.ts",
+      "content": "import { makeT } from \"@idosgames/react/ui\";\n\nconst EN = {\n  title: \"Multiplayer\",\n  create: \"Create a room\",\n  byCode: \"By invite\",\n  open: \"Open rooms\",\n  roomsOf: \"Rooms:\",\n  noRooms: \"No open rooms — create one and invite friends.\",\n  noGames: \"No game here plays online yet.\",\n  room: \"Room\",\n  roomName: \"Room name\",\n  invitePlaceholder: \"Invite: room ID or ID:code\",\n  invite: \"Invite\",\n  copied: \"Copied!\",\n  players: \"Players\",\n  join: \"Join\",\n  public: \"Anyone can join\",\n  private: \"Private — by invite\",\n  members: \"In the room\",\n  you: \"you\",\n  player: \"Player\",\n  kick: \"Remove\",\n  ready: \"Ready\",\n  notReady: \"Not ready\",\n  waitHost: \"The host starts the game.\",\n  play: \"Play\",\n  backToGame: \"Back to the game\",\n  inProgress: \"The game in this room has already started.\",\n  noGame: \"This app does not have the room's game.\",\n  startFailed: \"The game could not start the room.\",\n  message: \"Message\",\n  send: \"Send\",\n  noChat: \"Say hi to the room!\",\n  leave: \"Leave the room\",\n} as const;\n\nexport const t = makeT<keyof typeof EN>(EN, {\n  title: \"Мультиплеер\",\n  create: \"Создать комнату\",\n  byCode: \"По приглашению\",\n  open: \"Открытые комнаты\",\n  roomsOf: \"Комнаты:\",\n  noRooms: \"Открытых комнат нет — создайте свою и позовите друзей.\",\n  noGames: \"Здесь пока нет игр для игры по сети.\",\n  room: \"Комната\",\n  roomName: \"Название комнаты\",\n  invitePlaceholder: \"Приглашение: ID комнаты или ID:код\",\n  invite: \"Приглашение\",\n  copied: \"Скопировано!\",\n  players: \"Игроков\",\n  join: \"Войти\",\n  public: \"Может войти любой\",\n  private: \"Закрытая — по приглашению\",\n  members: \"В комнате\",\n  you: \"вы\",\n  player: \"Игрок\",\n  kick: \"Убрать\",\n  ready: \"Готов\",\n  notReady: \"Не готов\",\n  waitHost: \"Игру запускает хост.\",\n  play: \"Играть\",\n  backToGame: \"Вернуться в игру\",\n  inProgress: \"Игра в этой комнате уже началась.\",\n  noGame: \"В этом приложении нет игры этой комнаты.\",\n  startFailed: \"Игра не смогла принять комнату.\",\n  message: \"Сообщение\",\n  send: \"Отправить\",\n  noChat: \"Поздоровайтесь с комнатой!\",\n  leave: \"Выйти из комнаты\",\n});\n"
+    },
+    {
+      "path": "index.ts",
+      "content": "// @idosgames/mod-multiplayer — The rooms system for any game: rooms of the app's online games, public or private rooms by invite, members, ready and chat - the host takes the whole room into a game.\n\nexport { multiplayerModule } from \"./module\";\n"
+    },
+    {
+      "path": "model.ts",
+      "content": "// Pure helpers of the rooms system — covered by model.test.ts. No React, no network.\n\nimport type { MultiplayerGame } from \"@idosgames/module-sdk\";\n\n/** The title's Multiplayer section, as far as the rooms system cares. */\nexport interface MultiplayerSection {\n  SystemState?: { Enabled?: boolean | null } | null;\n  MaxPlayersPerRoom?: number | null;\n  MemberTimeoutMs?: number | null;\n}\n\nexport interface RoomMember {\n  UserID?: string | null;\n  Username?: string | null;\n  Ready?: boolean | null;\n  IsHost?: boolean | null;\n  LastSeenMs?: number | null;\n  State?: Record<string, string> | null;\n}\n\nexport interface MemberRow {\n  userID: string;\n  name: string;\n  host: boolean;\n  ready: boolean;\n  online: boolean;\n  me: boolean;\n}\n\n/** The room's members: host first, then by name; a member silent past the timeout is offline. */\nexport function memberRows(\n  members: Iterable<RoomMember> | null | undefined,\n  me: string | null | undefined,\n  hostId: string | null | undefined,\n  nowMs: number,\n  timeoutMs: number,\n): MemberRow[] {\n  return [...(members ?? [])]\n    .filter((m): m is RoomMember & { UserID: string } => !!m?.UserID)\n    .map((m) => ({\n      userID: m.UserID,\n      name: m.Username || m.UserID,\n      host: hostId ? m.UserID === hostId : m.IsHost === true,\n      ready: m.Ready === true,\n      online: !m.LastSeenMs || nowMs - m.LastSeenMs <= timeoutMs,\n      me: m.UserID === me,\n    }))\n    .sort(\n      (a, b) => Number(b.host) - Number(a.host) || a.name.localeCompare(b.name),\n    );\n}\n\n// ── The host's member state: the game's settings and \"the game started\" ─────────────────────\n//\n// The server keeps a small string map per member. The host's map carries the room's settings\n// (`set:<id>`) from the moment the room is created, and `start` once \"Play\" is pressed — so a player\n// who joins later reads both from the snapshot, and a guest who missed the DataChannel message still\n// learns about the start from the next member refresh.\n\nexport const START_KEY = \"start\";\nconst SETTING_PREFIX = \"set:\";\n\n/** The room's settings as the host's member state stores them. */\nexport function settingsToState(\n  settings: Record<string, string | boolean>,\n): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [id, value] of Object.entries(settings))\n    out[SETTING_PREFIX + id] =\n      typeof value === \"boolean\" ? (value ? \"1\" : \"0\") : value;\n  return out;\n}\n\n/** The room's settings read back from the host's member state, defaults filled in from the game. */\nexport function settingsFromState(\n  game: Pick<MultiplayerGame, \"settings\"> | undefined,\n  state: Record<string, string> | null | undefined,\n): Record<string, string | boolean> {\n  const out: Record<string, string | boolean> = {};\n  for (const field of game?.settings ?? []) {\n    const raw = state?.[SETTING_PREFIX + field.id];\n    out[field.id] =\n      raw === undefined\n        ? field.default\n        : field.kind === \"toggle\"\n          ? raw === \"1\"\n          : field.options?.some((o) => o.value === raw)\n            ? raw\n            : field.default;\n  }\n  return out;\n}\n\n/** Default settings of a game (what \"Create a room\" starts with). */\nexport function defaultSettings(\n  game: Pick<MultiplayerGame, \"settings\"> | undefined,\n): Record<string, string | boolean> {\n  return settingsFromState(game, null);\n}\n\n/** The game mode the host started for the room (null — still in the lobby). */\nexport function startedMode(\n  host: RoomMember | null | undefined,\n): string | null {\n  return host?.State?.[START_KEY] || null;\n}\n\n// ── The lobby's own DataChannel message ──────────────────────────────────────────────────────\n//\n// \"Play\" reaches guests at once over the links the lobby already opened (the member-state poll of a\n// guest is slow on purpose). The game owns the channels only after it started, and the host sends\n// this before any game message, on the ordered channel — so a game never sees it.\n\nconst START_TAG = \"idos.lobby.start\";\n\nexport function encodeStart(mode: string): Uint8Array {\n  return new TextEncoder().encode(JSON.stringify({ t: START_TAG, mode }));\n}\n\n/** The mode a lobby start message carries, or null for anything else. */\nexport function decodeStart(data: Uint8Array): string | null {\n  if (data.length > 256 || data[0] !== 0x7b) return null;\n  try {\n    const msg = JSON.parse(new TextDecoder().decode(data)) as {\n      t?: unknown;\n      mode?: unknown;\n    };\n    return msg.t === START_TAG && typeof msg.mode === \"string\"\n      ? msg.mode\n      : null;\n  } catch {\n    return null;\n  }\n}\n\n// ── Rooms list ───────────────────────────────────────────────────────────────────────────────\n\nexport interface ListedRoom {\n  RoomID?: string | null;\n  Name?: string | null;\n  Mode?: string | null;\n  MemberCount?: number | null;\n  MaxPlayers?: number | null;\n}\n\n/** Rooms the player can see: only those of a game this app has; of one game when asked. */\nexport function visibleRooms(\n  rooms: ListedRoom[],\n  games: string[],\n  onlyMode: string | null | undefined,\n): ListedRoom[] {\n  return rooms.filter(\n    (r) =>\n      !!r.RoomID &&\n      !!r.Mode &&\n      games.includes(r.Mode) &&\n      (!onlyMode || r.Mode === onlyMode),\n  );\n}\n\n/** A join code the way players type it: letters and digits, upper case. */\nexport function cleanCode(value: string): string {\n  return value\n    .toUpperCase()\n    .replace(/[^A-Z0-9]/g, \"\")\n    .slice(0, 12);\n}\n\n/** A fresh private-room code: six letters and digits without look-alikes. */\nexport function newCode(random: () => number = Math.random): string {\n  const abc = \"ABCDEFGHJKLMNPQRSTUVWXYZ23456789\";\n  let out = \"\";\n  for (let i = 0; i < 6; i++) out += abc[Math.floor(random() * abc.length)];\n  return out;\n}\n\n/** Whether multiplayer is on for the title. */\nexport function hasTitleData(section: MultiplayerSection | undefined): boolean {\n  return !!section && section.SystemState?.Enabled !== false;\n}\n"
+    },
+    {
+      "path": "module.ts",
+      "content": "import { defineModule, type Module } from \"@idosgames/module-sdk\";\nimport { configSection } from \"@idosgames/react/ui\";\nimport { makeMultiplayerScreen } from \"./MultiplayerScreen\";\nimport { hasTitleData, type MultiplayerSection } from \"./model\";\nimport { createRooms } from \"./rooms\";\nimport { t } from \"./i18n\";\n\n// The rooms system of the app: the lobby tab with the rooms, and the owner of the player's room and\n// its connection. Games that play online register in `ctx.multiplayer` and take the room in `start`;\n// they never create or join rooms. The tab shows while multiplayer is on for the title AND the app has\n// a game that plays online. No badge and no startup request.\nexport const multiplayerModule: Module = defineModule({\n  id: \"multiplayer\",\n  meta: { name: \"Multiplayer\", type: \"app\", engine: \"dom\" },\n  setup(ctx) {\n    const rooms = createRooms({\n      client: ctx.client,\n      games: ctx.multiplayer,\n      navigate: (mode) => ctx.navigate(mode),\n    });\n    ctx.features.register({\n      id: \"multiplayer\",\n      label: t(\"title\"),\n      icon: \"globe\",\n      group: \"social\",\n      order: 75,\n      available: false,\n      Screen: makeMultiplayerScreen({\n        rooms,\n        games: ctx.multiplayer,\n        modes: ctx.modes,\n      }),\n    });\n    const on = hasTitleData(\n      configSection<MultiplayerSection>(ctx.client, \"Multiplayer\"),\n    );\n    // Games register in their own setup() — before or after this one: follow the registry.\n    const refresh = () =>\n      ctx.features.setAvailable(\n        \"multiplayer\",\n        on && ctx.multiplayer.listGames().length > 0,\n        on\n          ? \"no game of the app plays online (ctx.multiplayer.registerGame)\"\n          : \"multiplayer is off on the title (Multiplayer.SystemState.Enabled)\",\n      );\n    refresh();\n    ctx.multiplayer.subscribe(refresh);\n    ctx.exposeToAgent({\n      state: () => {\n        const s = rooms.get();\n        return {\n          ui: \"dom\",\n          feature: \"multiplayer\",\n          games: ctx.multiplayer.listGames().map((g) => g.mode),\n          room: s.session\n            ? {\n                id: s.session.roomId,\n                mode: s.session.mode,\n                host: s.session.isHost,\n                members: s.session.members.size,\n                started: s.started,\n              }\n            : null,\n        };\n      },\n      describeActions: {},\n    });\n  },\n});\n"
+    },
+    {
+      "path": "MultiplayerScreen.tsx",
+      "content": "import {\n  useCallback,\n  useEffect,\n  useMemo,\n  useState,\n  useSyncExternalStore,\n  type ReactNode,\n} from \"react\";\nimport type { RoomListItem } from \"@idosgames/core\";\nimport type {\n  FeatureScreenProps,\n  ModeRegistry,\n  MultiplayerGame,\n  MultiplayerRegistry,\n} from \"@idosgames/module-sdk\";\nimport { useIDosGamesClient } from \"@idosgames/react\";\nimport {\n  Button,\n  Card,\n  Center,\n  EmptyState,\n  Icon,\n  Popup,\n  SectionTitle,\n  Spinner,\n  configSection,\n  errorText,\n  outlined,\n  panel,\n  useNow,\n  usePopupClose,\n  useStagger,\n  useToast,\n  v,\n} from \"@idosgames/react/ui\";\nimport {\n  cleanCode,\n  defaultSettings,\n  memberRows,\n  newCode,\n  settingsFromState,\n  visibleRooms,\n  type MultiplayerSection,\n} from \"./model\";\nimport type { Rooms } from \"./rooms\";\nimport { t } from \"./i18n\";\n\n// The rooms system's screen (a lobby tab): the rooms of the games this app plays online, \"Create a\n// room\" for one of them, joining by code — and, once in a room, its members, \"Ready\", the room chat and\n// the host's \"Play\", which takes the whole room into the game. Opened with `{ mode }` it shows one\n// game's rooms (the lobby's \"With friends\"); with `{ mode, create: true }` straight on \"Create\" (a\n// game's \"Open for friends\").\n\nexport interface ScreenDeps {\n  rooms: Rooms;\n  games: MultiplayerRegistry;\n  modes: ModeRegistry;\n}\n\nconst useGames = (games: MultiplayerRegistry) =>\n  useSyncExternalStore(games.subscribe, games.listGames, games.listGames);\n\nexport function makeMultiplayerScreen(deps: ScreenDeps) {\n  return function MultiplayerScreen({ args }: FeatureScreenProps): ReactNode {\n    const state = useSyncExternalStore(\n      deps.rooms.subscribe,\n      deps.rooms.get,\n      deps.rooms.get,\n    );\n    const mode = typeof args?.mode === \"string\" ? args.mode : null;\n    return state.session ? (\n      <Room deps={deps} />\n    ) : (\n      <Rooms deps={deps} mode={mode} create={args?.create === true} />\n    );\n  };\n}\n\n/** A game's label: its own, else its route's. */\nfunction gameLabel(\n  game: MultiplayerGame | undefined,\n  modes: ModeRegistry,\n  mode: string | null | undefined,\n): string {\n  return (\n    game?.label ?? modes.list().find((m) => m.id === mode)?.label ?? mode ?? \"\"\n  );\n}\n\n// ── The list of rooms ────────────────────────────────────────────────────────────────────────\n\nfunction Rooms({\n  deps,\n  mode,\n  create,\n}: {\n  deps: ScreenDeps;\n  mode: string | null;\n  create: boolean;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const stagger = useStagger();\n  const games = useGames(deps.games);\n  const [rooms, setRooms] = useState<RoomListItem[] | null>(null);\n  const [busy, setBusy] = useState<string | null>(null);\n  const [popup, setPopup] = useState<\"create\" | \"code\" | null>(\n    create ? \"create\" : null,\n  );\n  const modesList = useMemo(() => games.map((g) => g.mode), [games]);\n\n  const load = useCallback(async () => {\n    const res = await client.multiplayer.listRooms(0, 50);\n    setRooms(res.ok ? (res.data.Rooms ?? []) : []);\n  }, [client]);\n  useEffect(() => {\n    void load();\n    const id = setInterval(() => void load(), 5_000);\n    return () => clearInterval(id);\n  }, [load]);\n\n  const join = async (roomID: string, code?: string) => {\n    setBusy(roomID);\n    const error = await deps.rooms.join(roomID, code);\n    setBusy(null);\n    if (error)\n      toast(\n        error === \"inProgress\" ? t(\"inProgress\") : errorText(error),\n        \"error\",\n      );\n  };\n\n  const shown = visibleRooms(rooms ?? [], modesList, mode);\n  const title = mode\n    ? `${t(\"roomsOf\")} ${gameLabel(deps.games.getGame(mode), deps.modes, mode)}`\n    : t(\"open\");\n\n  return (\n    <div style={{ display: \"grid\", gap: 12 }}>\n      <div style={{ display: \"flex\", gap: 8 }}>\n        <Button\n          tone=\"green\"\n          attract\n          onClick={() => setPopup(\"create\")}\n          style={{ flex: 1 }}\n          data-tutorial-anchor=\"multiplayer:create\"\n        >\n          <Icon glyph=\"plus\" size={18} /> {t(\"create\")}\n        </Button>\n        <Button tone=\"blue\" onClick={() => setPopup(\"code\")}>\n          {t(\"byCode\")}\n        </Button>\n      </div>\n      <SectionTitle>{title}</SectionTitle>\n      {!rooms ? (\n        <Center>\n          <Spinner />\n        </Center>\n      ) : shown.length === 0 ? (\n        <EmptyState glyph=\"globe\" text={t(\"noRooms\")} />\n      ) : (\n        shown.map((r, i) => (\n          <Card\n            key={r.RoomID}\n            style={{\n              display: \"grid\",\n              gridTemplateColumns: \"auto 1fr auto\",\n              alignItems: \"center\",\n              gap: 12,\n              ...stagger(i),\n            }}\n          >\n            <Icon glyph=\"globe\" size={34} />\n            <div style={{ minWidth: 0 }}>\n              <div style={{ ...outlined, fontSize: 15 }}>\n                {r.Name || t(\"room\")}\n              </div>\n              <div style={{ ...outlined, fontSize: 12, color: v.textDim }}>\n                {gameLabel(\n                  deps.games.getGame(r.Mode ?? \"\"),\n                  deps.modes,\n                  r.Mode,\n                )}{\" \"}\n                · {t(\"players\")}: {r.MemberCount ?? 0} / {r.MaxPlayers ?? 8}\n              </div>\n            </div>\n            <Button\n              tone=\"green\"\n              size=\"sm\"\n              busy={busy === r.RoomID}\n              disabled={(r.MemberCount ?? 0) >= (r.MaxPlayers ?? 8)}\n              onClick={() => void join(r.RoomID ?? \"\")}\n            >\n              {t(\"join\")}\n            </Button>\n          </Card>\n        ))\n      )}\n      {popup === \"create\" ? (\n        <Popup title={t(\"create\")} onClose={() => setPopup(null)} width={420}>\n          <CreateForm deps={deps} games={games} preset={mode} />\n        </Popup>\n      ) : popup === \"code\" ? (\n        <Popup title={t(\"byCode\")} onClose={() => setPopup(null)} width={400}>\n          <CodeForm onJoin={(id, code) => void join(id, code)} />\n        </Popup>\n      ) : null}\n    </div>\n  );\n}\n\nconst input = {\n  ...panel,\n  padding: \"10px 12px\",\n  color: \"#fff\",\n  fontSize: 15,\n  width: \"100%\",\n  boxSizing: \"border-box\" as const,\n};\n\nfunction CreateForm({\n  deps,\n  games,\n  preset,\n}: {\n  deps: ScreenDeps;\n  games: MultiplayerGame[];\n  preset: string | null;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const close = usePopupClose();\n  const [mode, setMode] = useState(\n    games.find((g) => g.mode === preset)?.mode ?? games[0]?.mode ?? \"\",\n  );\n  const game = games.find((g) => g.mode === mode);\n  const cap = Math.min(\n    Number(\n      configSection<MultiplayerSection>(client, \"Multiplayer\")\n        ?.MaxPlayersPerRoom ?? 8,\n    ),\n    game?.maxPlayers ?? 8,\n  );\n  const sizes = [2, 4, 8].filter((n) => n <= cap);\n  const [name, setName] = useState(\"\");\n  const [max, setMax] = useState(sizes[sizes.length - 1] ?? 2);\n  const [priv, setPriv] = useState(false);\n  const [settings, setSettings] = useState(() => defaultSettings(game));\n  const [busy, setBusy] = useState(false);\n  useEffect(() => setSettings(defaultSettings(game)), [mode]);\n\n  if (!game) return <EmptyState glyph=\"globe\" text={t(\"noGames\")} />;\n\n  const create = async () => {\n    setBusy(true);\n    const error = await deps.rooms.create({\n      name: name.trim() || t(\"room\"),\n      mode,\n      maxPlayers: max,\n      private: priv,\n      joinCode: newCode(),\n      settings,\n    });\n    setBusy(false);\n    if (error) return toast(errorText(error), \"error\");\n    close();\n  };\n\n  return (\n    <div style={{ display: \"grid\", gap: 10 }}>\n      {games.length > 1 ? (\n        <div style={{ display: \"flex\", gap: 6, flexWrap: \"wrap\" }}>\n          {games.map((g) => (\n            <Button\n              key={g.mode}\n              size=\"sm\"\n              tone={g.mode === mode ? \"gold\" : \"grey\"}\n              onClick={() => setMode(g.mode)}\n            >\n              {gameLabel(g, deps.modes, g.mode)}\n            </Button>\n          ))}\n        </div>\n      ) : null}\n      <input\n        value={name}\n        maxLength={40}\n        placeholder={t(\"roomName\")}\n        onChange={(e) => setName(e.target.value)}\n        style={input}\n      />\n      <div\n        style={{\n          display: \"flex\",\n          alignItems: \"center\",\n          gap: 8,\n          ...outlined,\n          fontSize: 14,\n        }}\n      >\n        {t(\"players\")}:\n        {sizes.map((n) => (\n          <Button\n            key={n}\n            size=\"sm\"\n            tone={max === n ? \"gold\" : \"grey\"}\n            onClick={() => setMax(n)}\n          >\n            {n}\n          </Button>\n        ))}\n      </div>\n      <Button\n        tone={priv ? \"gold\" : \"grey\"}\n        size=\"sm\"\n        onClick={() => setPriv(!priv)}\n      >\n        <Icon glyph=\"lock\" size={16} /> {priv ? t(\"private\") : t(\"public\")}\n      </Button>\n      {(game.settings ?? []).map((field) =>\n        field.kind === \"toggle\" ? (\n          <Button\n            key={field.id}\n            size=\"sm\"\n            tone={settings[field.id] === true ? \"gold\" : \"grey\"}\n            onClick={() =>\n              setSettings({\n                ...settings,\n                [field.id]: settings[field.id] !== true,\n              })\n            }\n          >\n            {settings[field.id] === true ? \"✓ \" : \"\"}\n            {field.label}\n          </Button>\n        ) : (\n          <div key={field.id} style={{ display: \"grid\", gap: 6 }}>\n            <span style={{ ...outlined, fontSize: 13, color: v.textDim }}>\n              {field.label}\n            </span>\n            <div style={{ display: \"flex\", gap: 6, flexWrap: \"wrap\" }}>\n              {(field.options ?? []).map((o) => (\n                <Button\n                  key={o.value}\n                  size=\"sm\"\n                  tone={settings[field.id] === o.value ? \"gold\" : \"grey\"}\n                  onClick={() =>\n                    setSettings({ ...settings, [field.id]: o.value })\n                  }\n                >\n                  {o.label}\n                </Button>\n              ))}\n            </div>\n          </div>\n        ),\n      )}\n      <Button tone=\"green\" busy={busy} onClick={() => void create()}>\n        {t(\"create\")}\n      </Button>\n    </div>\n  );\n}\n\nfunction CodeForm({\n  onJoin,\n}: {\n  onJoin: (roomID: string, code: string) => void;\n}): ReactNode {\n  const close = usePopupClose();\n  const [invite, setInvite] = useState(\"\");\n  // An invite is \"<room id>:<code>\" (what the room screen shows for copying); a bare id works too.\n  const [roomId, code = \"\"] = invite.trim().split(\":\");\n  return (\n    <div style={{ display: \"grid\", gap: 10 }}>\n      <input\n        value={invite}\n        placeholder={t(\"invitePlaceholder\")}\n        onChange={(e) => setInvite(e.target.value)}\n        style={input}\n      />\n      <Button\n        tone=\"green\"\n        disabled={!roomId}\n        onClick={() => {\n          close();\n          onJoin(roomId ?? \"\", cleanCode(code));\n        }}\n      >\n        {t(\"join\")}\n      </Button>\n    </div>\n  );\n}\n\n// ── In a room ────────────────────────────────────────────────────────────────────────────────\n\nfunction Room({ deps }: { deps: ScreenDeps }): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const now = useNow();\n  const state = useSyncExternalStore(\n    deps.rooms.subscribe,\n    deps.rooms.get,\n    deps.rooms.get,\n  );\n  const [text, setText] = useState(\"\");\n  const [busy, setBusy] = useState(false);\n  const session = state.session!;\n  const game = deps.games.getGame(session.mode ?? \"\");\n  const timeout = Number(\n    configSection<MultiplayerSection>(client, \"Multiplayer\")?.MemberTimeoutMs ??\n      15_000,\n  );\n  const rows = memberRows(\n    session.members.values(),\n    session.selfId,\n    session.hostId,\n    now,\n    timeout,\n  );\n  const me = rows.find((r) => r.me);\n  const nameOf = (id: string) =>\n    rows.find((r) => r.userID === id)?.name ?? t(\"player\");\n  const settings = settingsFromState(\n    game,\n    session.members.get(session.hostId)?.State,\n  );\n  const invite = `${session.roomId}${state.joinCode ? `:${state.joinCode}` : \"\"}`;\n\n  const act = async (run: () => Promise<string | null>) => {\n    setBusy(true);\n    const error = await run();\n    setBusy(false);\n    if (error) toast(errorText(error), \"error\");\n  };\n\n  return (\n    <div style={{ display: \"grid\", gap: 12 }}>\n      <div style={{ ...panel, padding: 12, display: \"grid\", gap: 4 }}>\n        <div style={{ ...outlined, fontSize: 17 }}>\n          {gameLabel(game, deps.modes, session.mode)}\n        </div>\n        <div style={{ ...outlined, fontSize: 12, color: v.textDim }}>\n          {t(\"players\")}: {rows.length}\n          {(game?.settings ?? []).map((f) => {\n            const value = settings[f.id];\n            const shown =\n              f.kind === \"toggle\"\n                ? value === true\n                  ? f.label\n                  : null\n                : `${f.label}: ${f.options?.find((o) => o.value === value)?.label ?? value}`;\n            return shown ? ` · ${shown}` : null;\n          })}\n        </div>\n        <button\n          type=\"button\"\n          className=\"idos-press\"\n          onClick={() =>\n            void navigator.clipboard\n              ?.writeText(invite)\n              .then(() => toast(t(\"copied\")))\n          }\n          style={{\n            border: \"none\",\n            background: \"none\",\n            padding: 0,\n            textAlign: \"left\",\n            cursor: \"pointer\",\n            ...outlined,\n            fontSize: 12,\n            color: v.gold,\n          }}\n        >\n          <Icon glyph=\"copy\" size={14} /> {t(\"invite\")}: {invite}\n        </button>\n      </div>\n\n      {state.started ? (\n        <Button\n          tone=\"gold\"\n          size=\"lg\"\n          attract\n          onClick={() => deps.rooms.resume()}\n        >\n          {t(\"backToGame\")}\n        </Button>\n      ) : null}\n      {state.error ? (\n        <div style={{ ...outlined, fontSize: 13, color: v.red }}>\n          {t(state.error === \"noGame\" ? \"noGame\" : \"startFailed\")}\n        </div>\n      ) : null}\n\n      <SectionTitle>{t(\"members\")}</SectionTitle>\n      {rows.map((m) => (\n        <Card\n          key={m.userID}\n          highlight={m.me}\n          style={{\n            display: \"flex\",\n            alignItems: \"center\",\n            gap: 10,\n            opacity: m.online ? 1 : 0.5,\n          }}\n        >\n          <Icon glyph={m.host ? \"crown\" : \"user\"} size={24} />\n          <span style={{ ...outlined, fontSize: 14, flex: 1 }}>\n            {m.me ? `${m.name} (${t(\"you\")})` : m.name}\n          </span>\n          {m.ready ? <Icon glyph=\"check\" size={20} /> : null}\n          {session.isHost && !m.me && !state.started ? (\n            <Button\n              tone=\"grey\"\n              size=\"sm\"\n              onClick={() => void act(() => deps.rooms.kick(m.userID))}\n            >\n              {t(\"kick\")}\n            </Button>\n          ) : null}\n        </Card>\n      ))}\n\n      {state.started ? null : session.isHost ? (\n        <Button\n          tone=\"gold\"\n          size=\"lg\"\n          attract\n          busy={busy}\n          disabled={!game}\n          onClick={() => void act(() => deps.rooms.start())}\n          data-tutorial-anchor=\"multiplayer:play\"\n        >\n          {t(\"play\")} · {gameLabel(game, deps.modes, session.mode)}\n        </Button>\n      ) : (\n        <>\n          <Button\n            tone={me?.ready ? \"grey\" : \"green\"}\n            busy={busy}\n            onClick={() => void act(() => deps.rooms.setReady(!me?.ready))}\n          >\n            {me?.ready ? t(\"notReady\") : t(\"ready\")}\n          </Button>\n          <div\n            style={{\n              ...outlined,\n              fontSize: 12,\n              color: v.textDim,\n              textAlign: \"center\",\n            }}\n          >\n            {t(\"waitHost\")}\n          </div>\n        </>\n      )}\n\n      {session.chatMode === \"ServerRelay\" ? (\n        <div style={{ ...panel, padding: 10, display: \"grid\", gap: 8 }}>\n          <div\n            style={{\n              display: \"grid\",\n              gap: 4,\n              maxHeight: 180,\n              overflowY: \"auto\",\n            }}\n          >\n            {state.chat.length === 0 ? (\n              <div style={{ ...outlined, fontSize: 12, color: v.textDim }}>\n                {t(\"noChat\")}\n              </div>\n            ) : (\n              state.chat.map((c, i) => (\n                <div key={i} style={{ fontSize: 13, color: \"#fff\" }}>\n                  <b>{nameOf(c.from)}:</b> {c.text}\n                </div>\n              ))\n            )}\n          </div>\n          <div style={{ display: \"flex\", gap: 8 }}>\n            <input\n              value={text}\n              maxLength={200}\n              placeholder={t(\"message\")}\n              onChange={(e) => setText(e.target.value)}\n              onKeyDown={(e) => {\n                if (e.key !== \"Enter\") return;\n                const msg = text;\n                setText(\"\");\n                void act(() => deps.rooms.sendChat(msg));\n              }}\n              style={{ ...input, flex: 1 }}\n            />\n            <Button\n              tone=\"blue\"\n              size=\"sm\"\n              onClick={() => {\n                const msg = text;\n                setText(\"\");\n                void act(() => deps.rooms.sendChat(msg));\n              }}\n            >\n              {t(\"send\")}\n            </Button>\n          </div>\n        </div>\n      ) : null}\n\n      <Button tone=\"grey\" size=\"sm\" onClick={() => void deps.rooms.leave()}>\n        {t(\"leave\")}\n      </Button>\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "rooms.ts",
+      "content": "import type { IDosGamesClient } from \"@idosgames/core\";\nimport { RealtimeSession } from \"@idosgames/core/realtime\";\nimport type {\n  MultiplayerRegistry,\n  MultiplayerRoom,\n} from \"@idosgames/module-sdk\";\nimport {\n  START_KEY,\n  decodeStart,\n  encodeStart,\n  settingsFromState,\n  settingsToState,\n  startedMode,\n} from \"./model\";\n\n// The player's room, owned by the module rather than by its screen: it has to outlive the screen —\n// the room goes into a game and comes back to the lobby, and the session (with its WebRTC links) is\n// the same all along. The screen only draws this state and calls these actions.\n//\n// Start protocol: the host writes `start = <mode>` into its member state (for late joiners and for a\n// guest who missed the message) and sends a start message over the links the lobby already opened\n// (instant, before any game message on the ordered channel). Every device then switches to the game's\n// mode and hands the room to the game's `start`. From that moment the game owns the channels.\n\nexport interface ChatLine {\n  from: string;\n  text: string;\n  at: number;\n}\n\nexport interface RoomsState {\n  session: RealtimeSession | null;\n  /** The private room's code — known to its creator (to share it) and to whoever typed it. */\n  joinCode: string | null;\n  /** The game the room went into (null — still in the lobby). */\n  started: string | null;\n  chat: ChatLine[];\n  /** A problem to show (a game the app does not have, a start that failed). */\n  error: string | null;\n}\n\nexport interface RoomsDeps {\n  client: IDosGamesClient;\n  games: MultiplayerRegistry;\n  navigate: (modeId: string) => void;\n}\n\n/** Test seam: how sessions are opened. */\nexport interface SessionFactory {\n  create: typeof RealtimeSession.create;\n  join: typeof RealtimeSession.join;\n}\n\nexport interface CreateOptions {\n  name: string;\n  mode: string;\n  maxPlayers: number;\n  private: boolean;\n  joinCode: string;\n  settings: Record<string, string | boolean>;\n}\n\nexport function createRooms(\n  deps: RoomsDeps,\n  factory: SessionFactory = {\n    create: (...a) => RealtimeSession.create(...a),\n    join: (...a) => RealtimeSession.join(...a),\n  },\n) {\n  let state: RoomsState = {\n    session: null,\n    joinCode: null,\n    started: null,\n    chat: [],\n    error: null,\n  };\n  const listeners = new Set<() => void>();\n  let offs: Array<() => void> = [];\n  const set = (patch: Partial<RoomsState>) => {\n    state = { ...state, ...patch };\n    for (const l of listeners) l();\n  };\n\n  const reset = () => {\n    for (const off of offs.splice(0)) off();\n    set({\n      session: null,\n      joinCode: null,\n      started: null,\n      chat: [],\n      error: null,\n    });\n  };\n\n  /** Hand the room to the game — once per room. */\n  const enter = (mode: string, lateJoin: boolean) => {\n    const session = state.session;\n    if (!session || state.started) return;\n    const game = deps.games.getGame(mode);\n    if (!game) {\n      set({ error: \"noGame\" });\n      return;\n    }\n    const host = session.members.get(session.hostId);\n    const room: MultiplayerRoom = {\n      session,\n      mode,\n      isHost: session.isHost,\n      settings: settingsFromState(game, host?.State),\n      lateJoin,\n      leave: () => api.leave(),\n    };\n    set({ started: mode, error: null });\n    deps.navigate(mode);\n    // After the switch: the game's scene becomes active on the next render.\n    setTimeout(() => {\n      void Promise.resolve(game.start(room)).catch(() =>\n        set({ error: \"startFailed\" }),\n      );\n    }, 0);\n  };\n\n  const attach = (session: RealtimeSession, joinCode: string | null) => {\n    for (const off of offs.splice(0)) off();\n    set({ session, joinCode, started: null, chat: [], error: null });\n    offs = [\n      session.on(\"message\", ({ from, data }) => {\n        if (state.started || from !== session.hostId) return;\n        const mode = decodeStart(data);\n        if (mode) enter(mode, false);\n      }),\n      session.on(\"membersUpdated\", () => {\n        const mode = startedMode(session.members.get(session.hostId));\n        if (mode && !state.started) enter(mode, false);\n        else set({});\n      }),\n      session.on(\"hostChanged\", () => set({})),\n      session.on(\"chat\", ({ from, text }) =>\n        set({\n          chat: [...state.chat, { from, text, at: Date.now() }].slice(-100),\n        }),\n      ),\n      session.on(\"roomClosed\", () => reset()),\n      session.on(\"removed\", () => reset()),\n    ];\n  };\n\n  const api = {\n    get: () => state,\n    subscribe(listener: () => void) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n\n    /** Create a room for a game — this player hosts it. */\n    async create(o: CreateOptions): Promise<string | null> {\n      const game = deps.games.getGame(o.mode);\n      if (!game) return \"noGame\";\n      const res = await factory.create(deps.client, o.name, {\n        topology: game.topology ?? \"Mesh\",\n        chatMode: game.chatMode ?? \"ServerRelay\",\n        maxPlayers: o.maxPlayers,\n        visibility: o.private ? \"Private\" : \"Public\",\n        joinCode: o.private ? o.joinCode : undefined,\n        mode: o.mode,\n      });\n      if (!res.ok) return res.error;\n      attach(res.data, o.private ? o.joinCode : null);\n      // The settings live in the host's member state: whoever joins reads them from the snapshot.\n      const saved = await deps.client.multiplayer.setMemberState(\n        res.data.roomId,\n        undefined,\n        settingsToState(o.settings),\n      );\n      if (!saved.ok) return saved.error;\n      await res.data.refreshMembers();\n      return null;\n    },\n\n    /** Join a room; into its game right away when the game is running and lets players in. */\n    async join(roomId: string, joinCode?: string): Promise<string | null> {\n      const res = await factory.join(\n        deps.client,\n        roomId,\n        joinCode || undefined,\n      );\n      if (!res.ok) return res.error;\n      const session = res.data;\n      attach(session, joinCode || null);\n      const running = startedMode(session.members.get(session.hostId));\n      if (running) {\n        if (deps.games.getGame(running)?.joinInProgress) enter(running, true);\n        else {\n          await api.leave();\n          return \"inProgress\";\n        }\n      }\n      return null;\n    },\n\n    async setReady(ready: boolean): Promise<string | null> {\n      const s = state.session;\n      if (!s) return null;\n      const res = await deps.client.multiplayer.setMemberState(s.roomId, ready);\n      return res.ok ? null : res.error;\n    },\n\n    async sendChat(text: string): Promise<string | null> {\n      const s = state.session;\n      if (!s || !text.trim()) return null;\n      const res = await deps.client.multiplayer.sendChat(s.roomId, text.trim());\n      return res.ok ? null : res.error;\n    },\n\n    /** The host takes the whole room into its game. */\n    async start(): Promise<string | null> {\n      const s = state.session;\n      const mode = s?.mode;\n      if (!s || !mode || !s.isHost) return null;\n      const host = s.members.get(s.selfId);\n      const res = await deps.client.multiplayer.setMemberState(s.roomId, true, {\n        ...(host?.State ?? {}),\n        [START_KEY]: mode,\n      });\n      if (!res.ok) return res.error;\n      s.broadcast(\"rel\", encodeStart(mode));\n      enter(mode, false);\n      return null;\n    },\n\n    /** Back to the running game from the lobby (the room is still on). */\n    resume() {\n      if (state.started) deps.navigate(state.started);\n    },\n\n    async kick(userId: string): Promise<string | null> {\n      const s = state.session;\n      if (!s) return null;\n      const res = await s.kick(userId);\n      return res.ok ? null : res.error;\n    },\n\n    async leave(): Promise<void> {\n      const s = state.session;\n      reset();\n      await s?.leave();\n    },\n  };\n  return api;\n}\n\nexport type Rooms = ReturnType<typeof createRooms>;\n"
+    },
+    {
+      "path": "module.meta.json",
+      "content": "{\n  \"id\": \"multiplayer\",\n  \"type\": \"feature\",\n  \"summary\": \"The rooms system for any game: open rooms of the app's online games, public or private rooms by invite, members, ready and chat — the host takes the whole room into a game.\",\n  \"description\": \"A ready multiplayer lobby (engine Multiplayer) for ANY game, built on the @idosgames/react/ui kit, client.multiplayer and RealtimeSession (@idosgames/core/realtime). It OWNS the player's room and its WebRTC session: the rooms of the games this app plays online (each room remembers its game), 'Create a room' for one of them (name, 2/4/8 players, public or private with an invite code, the game's own room settings), joining by invite, members (host, ready, offline), 'Ready', the room chat (server relay, when the game has no chat of its own), removing a member and leaving. The host's 'Play' takes the whole room into the game: every device switches to the game's mode and the game gets the room in its start() — games never create, list or join rooms themselves. A game plays online by registering in ctx.multiplayer (registerGame: topology, chat mode, room size, joinInProgress for late joiners, room settings, start(room)); the lobby then draws 'With friends' next to its 'Play'. Opened with { mode } the screen shows one game's rooms, with { mode, create: true } straight on 'Create'. Registers the 'multiplayer' feature, shown while multiplayer is on for the title and the app has a game that plays online. Ships title-seed.json: multiplayer on, up to 8 players per room.\",\n  \"provides\": [\n    \"multiplayer rooms lobby\",\n    \"rooms of one game\",\n    \"public and private rooms by invite\",\n    \"room settings of the game\",\n    \"room members with ready and host\",\n    \"room chat\",\n    \"host starts the game for the whole room\",\n    \"late joiners into a running game\"\n  ],\n  \"tags\": [\n    \"multiplayer\",\n    \"rooms\",\n    \"lobby\",\n    \"realtime\",\n    \"social\",\n    \"ui\",\n    \"screen\"\n  ],\n  \"author\": {\n    \"name\": \"iDos Games\",\n    \"url\": \"https://idosgames.com\"\n  },\n  \"version\": \"0.1.0\"\n}\n"
+    }
+  ]
+}

package/registry/modules/premium.json

@@ -0,0 +1,67 @@
+{
+  "id": "premium",
+  "meta": {
+    "name": "VIP",
+    "type": "app",
+    "engine": "dom"
+  },
+  "catalog": {
+    "type": "feature",
+    "summary": "VIP for any game: premium passes with benefits, until when the player holds one, a free trial and buying with in-game currency.",
+    "description": "A ready VIP screen (Unity PremiumPopUp) for ANY game, built on the @idosgames/react/ui kit and client.premium. Every premium pass of the title, lowest tier first: its name, benefits and duration, a timer while the player holds it, a one-time free trial, and buying (or extending) it with currencies or items. A pass paid in a store (real money) is the platform's checkout and is not sold here. Events and season send the player here for their VIP prizes (ctx.features.open('premium', { premiumID }) marks that pass). Registers the 'premium' feature; its badge shows a free trial waiting. The demo pass comes with the base's settings.",
+    "provides": [
+      "VIP passes screen",
+      "free VIP trial",
+      "buy or extend VIP with in-game currency",
+      "VIP timer",
+      "badge for a free trial"
+    ],
+    "tags": [
+      "vip",
+      "premium",
+      "subscription",
+      "monetization",
+      "ui",
+      "screen",
+      "economy"
+    ],
+    "author": {
+      "name": "iDos Games",
+      "url": "https://idosgames.com"
+    },
+    "version": "0.1.0"
+  },
+  "dependencies": {
+    "@idosgames/core": "0.19.1",
+    "@idosgames/module-sdk": "0.7.0",
+    "@idosgames/react": "0.3.0",
+    "react": "19.2.7"
+  },
+  "contentHash": "ec99b4243633026ae61d43679fca7b37731033cd262bae6f5cc17479d1e67e7a",
+  "files": [
+    {
+      "path": "i18n.ts",
+      "content": "import { makeT } from \"@idosgames/react/ui\";\n\nconst EN = {\n  title: \"VIP\",\n  active: \"VIP is active!\",\n  activeFor: \"Active for\",\n  days: \"days\",\n  trial: \"Try free\",\n  buy: \"Buy\",\n  extend: \"Extend\",\n  noPasses: \"No VIP in this game yet. Add it in LiveOps → Premium.\",\n} as const;\n\nexport const t = makeT<keyof typeof EN>(EN, {\n  title: \"VIP\",\n  active: \"VIP активен!\",\n  activeFor: \"Действует ещё\",\n  days: \"дн.\",\n  trial: \"Попробовать бесплатно\",\n  buy: \"Купить\",\n  extend: \"Продлить\",\n  noPasses: \"VIP в этой игре пока нет. Добавьте его в LiveOps → Premium.\",\n});\n"
+    },
+    {
+      "path": "index.ts",
+      "content": "// @idosgames/mod-premium — VIP for any game: the title's premium passes with their benefits, a free trial and buying a pass with in-game currency.\n\nexport { premiumModule } from \"./module\";\n"
+    },
+    {
+      "path": "model.ts",
+      "content": "// Pure helpers of the VIP screen — covered by model.test.ts. The server is the authority on what a\n// player holds; these only decide what the screen draws.\n\nimport { costLines, type ResourceLine } from \"@idosgames/react/ui\";\n\nexport interface PremiumDefinitionView {\n  PremiumID?: string | null;\n  DisplayName?: string | null;\n  Tier?: number | null;\n  DurationDays?: number | null;\n  TrialDurationDays?: number | null;\n  Benefits?: Record<string, string> | null;\n  PriceOptions?: Record<\n    string,\n    { OptionID?: string | null; Cost?: unknown } | null\n  > | null;\n}\n\n/** The title's Premium section, as far as the VIP screen cares. */\nexport interface PremiumSection {\n  Definitions?: Record<string, PremiumDefinitionView | null> | null;\n}\n\n/** The player's premium state (UserState.Premium). */\nexport interface PremiumStateView {\n  Subscriptions?: Record<\n    string,\n    { ExpirationDate?: string | null } | null | undefined\n  > | null;\n  ActivatedTrialIDs?: string[] | null;\n}\n\nexport interface PassRow {\n  premiumID: string;\n  name: string;\n  tier: number;\n  durationDays: number;\n  benefits: string[];\n  /** Ways to buy with currencies/items (a pass paid in a store is the platform's checkout). */\n  options: Array<{ id: string; price: ResourceLine[] }>;\n  /** Until when the player holds it (ISO), null — not held. */\n  activeUntil: string | null;\n  /** A free trial the player has not used yet (and does not hold the pass now). */\n  trialDays: number;\n}\n\n/** Every pass of the title, lowest tier first, with the player's state. */\nexport function passRows(\n  section: PremiumSection | null | undefined,\n  state: PremiumStateView | null | undefined,\n  nowMs: number,\n): PassRow[] {\n  const rows: PassRow[] = [];\n  for (const [id, def] of Object.entries(section?.Definitions ?? {})) {\n    if (!def) continue;\n    const premiumID = def.PremiumID || id;\n    const until = state?.Subscriptions?.[premiumID]?.ExpirationDate ?? null;\n    const active = !!until && new Date(until).getTime() > nowMs ? until : null;\n    const trialUsed = (state?.ActivatedTrialIDs ?? []).includes(premiumID);\n    rows.push({\n      premiumID,\n      name: def.DisplayName || premiumID,\n      tier: Number(def.Tier ?? 0),\n      durationDays: Number(def.DurationDays ?? 0),\n      benefits: Object.values(def.Benefits ?? {}).filter(Boolean),\n      options: Object.entries(def.PriceOptions ?? {})\n        .filter(([, o]) => o)\n        .map(([oid, o]) => ({\n          id: o?.OptionID || oid,\n          price: costLines(o?.Cost as never).filter((l) => l.kind !== \"other\"),\n        }))\n        .filter((o) => o.price.length > 0),\n      activeUntil: active,\n      trialDays:\n        !active && !trialUsed\n          ? Math.max(0, Number(def.TrialDurationDays ?? 0))\n          : 0,\n    });\n  }\n  return rows.sort(\n    (a, b) => a.tier - b.tier || a.premiumID.localeCompare(b.premiumID),\n  );\n}\n\n/** Badge: free trials waiting to be taken. */\nexport function premiumBadge(rows: PassRow[]): number {\n  return rows.filter((r) => r.trialDays > 0).length;\n}\n\n/** Whether the title has a pass — until it does, the lobby hides the tab. */\nexport function hasTitleData(section: PremiumSection | undefined): boolean {\n  return Object.values(section?.Definitions ?? {}).some(Boolean);\n}\n"
+    },
+    {
+      "path": "module.ts",
+      "content": "import { defineModule, type Module } from \"@idosgames/module-sdk\";\nimport { configSection } from \"@idosgames/react/ui\";\nimport { PremiumScreen, makePremiumWatcher } from \"./PremiumScreen\";\nimport { hasTitleData, type PremiumSection } from \"./model\";\nimport { t } from \"./i18n\";\n\n// VIP as a feature of the game. Events and season send the player here for their VIP prizes\n// (features.open(\"premium\", { premiumID })). Badge: a free trial waiting.\nexport const premiumModule: Module = defineModule({\n  id: \"premium\",\n  meta: { name: \"VIP\", type: \"app\", engine: \"dom\" },\n  setup(ctx) {\n    ctx.features.register({\n      id: \"premium\",\n      label: t(\"title\"),\n      icon: \"crown\",\n      group: \"economy\",\n      order: 12,\n      available: false,\n      Screen: PremiumScreen,\n    });\n    const enabled = hasTitleData(\n      configSection<PremiumSection>(ctx.client, \"Premium\"),\n    );\n    ctx.features.setAvailable(\n      \"premium\",\n      enabled,\n      \"no premium pass on the title (Premium)\",\n    );\n    if (enabled)\n      ctx.registerPanel({\n        id: \"badge\",\n        slot: \"modal\",\n        activeOnly: false,\n        component: makePremiumWatcher(ctx.features),\n      });\n    ctx.exposeToAgent({\n      state: () => ({ ui: \"dom\", feature: \"premium\" }),\n      describeActions: {},\n    });\n  },\n});\n"
+    },
+    {
+      "path": "PremiumScreen.tsx",
+      "content": "import {\n  useEffect,\n  useRef,\n  useState,\n  type CSSProperties,\n  type ReactNode,\n} from \"react\";\nimport type {\n  FeatureRegistry,\n  FeatureScreenProps,\n} from \"@idosgames/module-sdk\";\nimport { useIDosGamesClient, useUserState } from \"@idosgames/react\";\nimport {\n  Button,\n  Card,\n  EmptyState,\n  Icon,\n  ResourceList,\n  Timer,\n  canAfford,\n  configSection,\n  errorText,\n  outlined,\n  panel,\n  useCatalog,\n  useNow,\n  useStagger,\n  useToast,\n  useUiKit,\n  v,\n} from \"@idosgames/react/ui\";\nimport {\n  passRows,\n  premiumBadge,\n  type PassRow,\n  type PremiumSection,\n  type PremiumStateView,\n} from \"./model\";\nimport { t } from \"./i18n\";\n\n// VIP (Unity PremiumPopUp): every premium pass of the title, lowest tier first — what it gives, how\n// long it lasts, until when the player holds it, a free trial once, and buying it with in-game\n// currency. A pass paid in a store (real money) is the platform's checkout, not sold here. Other\n// systems (events, season) send the player here for their VIP prizes:\n// `features.open(\"premium\", { premiumID })` — that pass is marked.\n\nexport function PremiumScreen({ args }: FeatureScreenProps): ReactNode {\n  const client = useIDosGamesClient();\n  const state = useUserState();\n  const now = useNow();\n  const stagger = useStagger();\n  const wanted = typeof args?.premiumID === \"string\" ? args.premiumID : null;\n  const rows = passRows(\n    configSection<PremiumSection>(client, \"Premium\"),\n    state?.Premium as PremiumStateView | undefined,\n    now,\n  );\n  // Fresh state on open: a pass may have run out since the last read.\n  useEffect(() => {\n    void client.premium.getUserState();\n  }, [client]);\n\n  if (rows.length === 0)\n    return <EmptyState glyph=\"crown\" text={t(\"noPasses\")} />;\n  return (\n    <div style={{ display: \"grid\", gap: 12 }}>\n      {rows.map((row, i) => (\n        <PassCard\n          key={row.premiumID}\n          row={row}\n          marked={row.premiumID === wanted}\n          style={stagger(i)}\n        />\n      ))}\n    </div>\n  );\n}\n\nfunction PassCard({\n  row,\n  marked,\n  style,\n}: {\n  row: PassRow;\n  marked: boolean;\n  style: CSSProperties;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const state = useUserState();\n  const catalog = useCatalog();\n  const now = useNow();\n  const toast = useToast();\n  const kit = useUiKit();\n  const ref = useRef<HTMLDivElement>(null);\n  const [busy, setBusy] = useState<string | null>(null);\n  const balances = state?.InventoryV2?.VirtualCurrencies as\n    Record<string, { Amount?: number }> | undefined;\n\n  useEffect(() => {\n    if (marked) ref.current?.scrollIntoView({ block: \"center\" });\n  }, [marked]);\n\n  const done = (res: { ok: true } | { ok: false; error: string }) => {\n    setBusy(null);\n    if (!res.ok) return toast(errorText(res.error), \"error\");\n    kit.play(\"purchase\");\n    kit.fx.burst(ref.current);\n    toast(t(\"active\"), \"success\");\n  };\n  const trial = async () => {\n    setBusy(\"trial\");\n    const res = await client.premium.activateTrial(\n      row.premiumID,\n      crypto.randomUUID(),\n    );\n    done(res);\n  };\n  const buy = async (optionID: string) => {\n    setBusy(optionID);\n    const res = await client.premium.purchaseItemOrCurrency(\n      row.premiumID,\n      crypto.randomUUID(),\n      optionID,\n    );\n    done(res);\n  };\n\n  return (\n    <div ref={ref}>\n      <Card\n        highlight={marked}\n        style={{\n          display: \"grid\",\n          gap: 10,\n          background: \"linear-gradient(180deg, #8a5a12 0%, #4a2d06 100%)\",\n          ...style,\n        }}\n      >\n        <div style={{ display: \"flex\", alignItems: \"center\", gap: 12 }}>\n          <div className=\"idos-bounce\">\n            <Icon glyph=\"crown\" size={52} />\n          </div>\n          <div style={{ flex: 1, minWidth: 0 }}>\n            <div style={{ ...outlined, fontSize: 17 }}>\n              {catalog.localize(row.name)}\n            </div>\n            {row.activeUntil ? (\n              <Timer at={row.activeUntil} now={now} label={t(\"activeFor\")} />\n            ) : row.durationDays > 0 ? (\n              <div style={{ ...outlined, fontSize: 13, color: v.textDim }}>\n                {row.durationDays} {t(\"days\")}\n              </div>\n            ) : null}\n          </div>\n          {row.activeUntil ? <Icon glyph=\"check\" size={30} /> : null}\n        </div>\n        {row.benefits.length > 0 ? (\n          <div style={{ display: \"grid\", gap: 4 }}>\n            {row.benefits.map((b, i) => (\n              <div\n                key={i}\n                style={{\n                  ...panel,\n                  padding: 8,\n                  display: \"flex\",\n                  gap: 8,\n                  alignItems: \"center\",\n                  ...outlined,\n                  fontSize: 13,\n                }}\n              >\n                <Icon glyph=\"check\" size={18} /> {catalog.localize(b)}\n              </div>\n            ))}\n          </div>\n        ) : null}\n        {row.trialDays > 0 ? (\n          <Button\n            tone=\"green\"\n            attract\n            busy={busy === \"trial\"}\n            onClick={() => void trial()}\n            data-tutorial-anchor={`premium:trial:${row.premiumID}`}\n          >\n            {t(\"trial\")} · {row.trialDays} {t(\"days\")}\n          </Button>\n        ) : null}\n        {row.options.map((o) => {\n          const affordable = canAfford(o.price, balances);\n          return (\n            <Button\n              key={o.id}\n              tone=\"gold\"\n              attract={affordable && !row.activeUntil}\n              disabled={!affordable}\n              busy={busy === o.id}\n              onClick={() => void buy(o.id)}\n              data-tutorial-anchor={`premium:buy:${row.premiumID}`}\n            >\n              {row.activeUntil ? t(\"extend\") : t(\"buy\")}{\" \"}\n              <ResourceList\n                lines={o.price}\n                size={18}\n                dimIf={() => !affordable}\n              />\n            </Button>\n          );\n        })}\n      </Card>\n    </div>\n  );\n}\n\n/** Badge: a free trial waiting — from the config and the cached state, no request of its own. */\nexport function makePremiumWatcher(features: FeatureRegistry) {\n  return function PremiumBadge(): ReactNode {\n    const client = useIDosGamesClient();\n    const state = useUserState();\n    useEffect(() => {\n      features.setBadge(\n        \"premium\",\n        premiumBadge(\n          passRows(\n            configSection<PremiumSection>(client, \"Premium\"),\n            state?.Premium as PremiumStateView | undefined,\n            Date.now(),\n          ),\n        ),\n      );\n    }, [client, state?.Premium]);\n    return null;\n  };\n}\n"
+    },
+    {
+      "path": "module.meta.json",
+      "content": "{\n  \"id\": \"premium\",\n  \"type\": \"feature\",\n  \"summary\": \"VIP for any game: premium passes with benefits, until when the player holds one, a free trial and buying with in-game currency.\",\n  \"description\": \"A ready VIP screen (Unity PremiumPopUp) for ANY game, built on the @idosgames/react/ui kit and client.premium. Every premium pass of the title, lowest tier first: its name, benefits and duration, a timer while the player holds it, a one-time free trial, and buying (or extending) it with currencies or items. A pass paid in a store (real money) is the platform's checkout and is not sold here. Events and season send the player here for their VIP prizes (ctx.features.open('premium', { premiumID }) marks that pass). Registers the 'premium' feature; its badge shows a free trial waiting. The demo pass comes with the base's settings.\",\n  \"provides\": [\n    \"VIP passes screen\",\n    \"free VIP trial\",\n    \"buy or extend VIP with in-game currency\",\n    \"VIP timer\",\n    \"badge for a free trial\"\n  ],\n  \"tags\": [\n    \"vip\",\n    \"premium\",\n    \"subscription\",\n    \"monetization\",\n    \"ui\",\n    \"screen\",\n    \"economy\"\n  ],\n  \"author\": {\n    \"name\": \"iDos Games\",\n    \"url\": \"https://idosgames.com\"\n  },\n  \"version\": \"0.1.0\"\n}\n"
+    }
+  ]
+}