@idosgames/mcp 0.1.24 → 0.1.25

package/registry/modules/inventory.json

@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/invite.json

@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/leaderboard.json

@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/lootboxes.json

@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/mailbox.json

@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/marketplace.json

@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/mini-game.json

@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/multiplayer.json

@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/premium.json

@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/profile.json

@@ -8,15 +8,14 @@
   "catalog": {
     "type": "feature",
     "inBase": true,
-    "summary": "Profile and settings for any game: name and ID, sound, volume and motion, language, tutorials, log out and account deletion.",
-    "description": "A ready profile screen (Unity Alikhan/Username, UI/HUD/Settings, Runtime/UI/Consent, Localization) for ANY game, built on the @idosgames/react/ui kit. The player's name (rename in a popup with the server's rules: 3–24 characters, trimmed) and ID with copy; settings: sound on/off, volume and 'fewer animations' — the kit's player prefs, kept on this device and applied to every screen at once — the game's language (the title's languages, when there are two or more). Buttons: Tutorials (when tutorials is installed), Log out (confirmed) and Delete account — a popup that unlocks only after the player types the confirmation word, then deletes this game's data for the player. Registers the 'profile' feature; the lobby's profile button opens it. No title settings needed.",
+    "summary": "Profile and settings for any game: name and ID, sound, volume and motion, language, tutorials and log out.",
+    "description": "A ready profile screen (Unity Alikhan/Username, UI/HUD/Settings, Runtime/UI/Consent, Localization) for ANY game, built on the @idosgames/react/ui kit. The player's name (rename in a popup with the server's rules: 3–24 characters, trimmed) and ID with copy; settings: sound on/off, volume and 'fewer animations' — the kit's player prefs, kept on this device and applied to every screen at once — the game's language (the title's languages, when there are two or more). Buttons: Tutorials (when tutorials is installed) and Log out (confirmed). Registers the 'profile' feature; the lobby's profile button opens it. No title settings needed.",
     "provides": [
       "player name and ID",
       "rename popup",
       "sound, volume and fewer animations",
       "language picker",
-      "log out",
-      "account deletion with confirmation"
+      "log out"
     ],
     "tags": [
       "profile",
@@ -32,27 +31,27 @@
       "name": "iDos Games",
       "url": "https://idosgames.com"
     },
-    "version": "0.1.2"
+    "version": "0.1.3"
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },
-  "contentHash": "bcb4c2b1d773155f758fb2cde1ae7cf4a70f98b7bc50b37bfba2e9b83fc0d101",
+  "contentHash": "868e0639ef9ac1cbc88a506c3ecd81c481823c71c11004c25dfcce6dc8ba921d",
   "files": [
     {
       "path": "i18n.ts",
-      "content": "import { makeT } from \"@idosgames/react/ui\";\n\nconst EN = {\n  title: \"Profile\",\n  playerID: \"Player ID\",\n  copied: \"Copied\",\n  rename: \"Change name\",\n  newName: \"New name\",\n  save: \"Save\",\n  nameShort: \"At least 3 characters\",\n  nameLong: \"At most 24 characters\",\n  renamed: \"Name changed\",\n  settings: \"Settings\",\n  sound: \"Sound\",\n  volume: \"Volume\",\n  motion: \"Fewer animations\",\n  language: \"Language\",\n  tutorials: \"Tutorials\",\n  logout: \"Log out\",\n  logoutAsk:\n    \"Log out of this device? A guest account is lost unless it is linked.\",\n  delete: \"Delete account\",\n  deleteAsk:\n    \"This deletes your progress in this game for good. Type the word to confirm:\",\n  deleteWord: \"DELETE\",\n  deleted: \"Account deleted\",\n  on: \"On\",\n  off: \"Off\",\n  guest: \"Guest\",\n  wallets: \"Wallets\",\n  unlink: \"Unlink\",\n  unlinkTitle: \"Unlink the wallet?\",\n  unlinkAsk:\n    \"The wallet will be taken off this account. For 7 days it cannot be linked to another account; you can link it back here at any time. If the game is played with a wallet, it closes until you link one.\",\n  unlinked: \"Wallet unlinked\",\n  unlinkLogin: \"You sign in with this wallet — it cannot be unlinked.\",\n  unlinkTooMany:\n    \"Too many wallets unlinked this week. Try again in a few days.\",\n  unlinkMissing: \"This wallet is no longer linked.\",\n  loginWallet: \"Sign-in wallet\",\n} as const;\n\nexport const t = makeT<keyof typeof EN>(EN, {\n  title: \"Профиль\",\n  playerID: \"ID игрока\",\n  copied: \"Скопировано\",\n  rename: \"Сменить имя\",\n  newName: \"Новое имя\",\n  save: \"Сохранить\",\n  nameShort: \"Минимум 3 символа\",\n  nameLong: \"Максимум 24 символа\",\n  renamed: \"Имя изменено\",\n  settings: \"Настройки\",\n  sound: \"Звук\",\n  volume: \"Громкость\",\n  motion: \"Меньше анимации\",\n  language: \"Язык\",\n  tutorials: \"Обучение\",\n  logout: \"Выйти\",\n  logoutAsk:\n    \"Выйти на этом устройстве? Гостевой аккаунт без привязки будет потерян.\",\n  delete: \"Удалить аккаунт\",\n  deleteAsk:\n    \"Весь ваш прогресс в этой игре будет удалён навсегда. Чтобы подтвердить, введите слово:\",\n  deleteWord: \"УДАЛИТЬ\",\n  deleted: \"Аккаунт удалён\",\n  on: \"Вкл\",\n  off: \"Выкл\",\n  guest: \"Гость\",\n  wallets: \"Кошельки\",\n  unlink: \"Отвязать\",\n  unlinkTitle: \"Отвязать кошелёк?\",\n  unlinkAsk:\n    \"Кошелёк будет снят с этого аккаунта. 7 дней его нельзя привязать к другому аккаунту, а к этому — можно вернуть в любой момент. Если в игру играют с кошельком, она закроется, пока вы не привяжете другой.\",\n  unlinked: \"Кошелёк отвязан\",\n  unlinkLogin: \"Вы входите этим кошельком — его нельзя отвязать.\",\n  unlinkTooMany:\n    \"На этой неделе отвязано слишком много кошельков. Попробуйте через несколько дней.\",\n  unlinkMissing: \"Этот кошелёк уже не привязан.\",\n  loginWallet: \"Кошелёк входа\",\n});\n"
+      "content": "import { makeT } from \"@idosgames/react/ui\";\n\nconst EN = {\n  title: \"Profile\",\n  playerID: \"Player ID\",\n  copied: \"Copied\",\n  rename: \"Change name\",\n  newName: \"New name\",\n  save: \"Save\",\n  nameShort: \"At least 3 characters\",\n  nameLong: \"At most 24 characters\",\n  renamed: \"Name changed\",\n  settings: \"Settings\",\n  sound: \"Sound\",\n  volume: \"Volume\",\n  motion: \"Fewer animations\",\n  language: \"Language\",\n  tutorials: \"Tutorials\",\n  logout: \"Log out\",\n  logoutAsk:\n    \"Log out of this device? A guest account is lost unless it is linked.\",\n  on: \"On\",\n  off: \"Off\",\n  guest: \"Guest\",\n  wallets: \"Wallets\",\n  unlink: \"Unlink\",\n  unlinkTitle: \"Unlink the wallet?\",\n  unlinkAsk:\n    \"The wallet will be taken off this account. For 7 days it cannot be linked to another account; you can link it back here at any time. If the game is played with a wallet, it closes until you link one.\",\n  unlinked: \"Wallet unlinked\",\n  unlinkLogin: \"You sign in with this wallet — it cannot be unlinked.\",\n  unlinkTooMany:\n    \"Too many wallets unlinked this week. Try again in a few days.\",\n  unlinkMissing: \"This wallet is no longer linked.\",\n  loginWallet: \"Sign-in wallet\",\n} as const;\n\nexport const t = makeT<keyof typeof EN>(EN, {\n  title: \"Профиль\",\n  playerID: \"ID игрока\",\n  copied: \"Скопировано\",\n  rename: \"Сменить имя\",\n  newName: \"Новое имя\",\n  save: \"Сохранить\",\n  nameShort: \"Минимум 3 символа\",\n  nameLong: \"Максимум 24 символа\",\n  renamed: \"Имя изменено\",\n  settings: \"Настройки\",\n  sound: \"Звук\",\n  volume: \"Громкость\",\n  motion: \"Меньше анимации\",\n  language: \"Язык\",\n  tutorials: \"Обучение\",\n  logout: \"Выйти\",\n  logoutAsk:\n    \"Выйти на этом устройстве? Гостевой аккаунт без привязки будет потерян.\",\n  on: \"Вкл\",\n  off: \"Выкл\",\n  guest: \"Гость\",\n  wallets: \"Кошельки\",\n  unlink: \"Отвязать\",\n  unlinkTitle: \"Отвязать кошелёк?\",\n  unlinkAsk:\n    \"Кошелёк будет снят с этого аккаунта. 7 дней его нельзя привязать к другому аккаунту, а к этому — можно вернуть в любой момент. Если в игру играют с кошельком, она закроется, пока вы не привяжете другой.\",\n  unlinked: \"Кошелёк отвязан\",\n  unlinkLogin: \"Вы входите этим кошельком — его нельзя отвязать.\",\n  unlinkTooMany:\n    \"На этой неделе отвязано слишком много кошельков. Попробуйте через несколько дней.\",\n  unlinkMissing: \"Этот кошелёк уже не привязан.\",\n  loginWallet: \"Кошелёк входа\",\n});\n"
     },
     {
       "path": "index.ts",
-      "content": "// @idosgames/mod-profile — Profile for any game: name, ID, language, sound and motion settings, log out and account deletion.\n\nexport { profileModule } from \"./module\";\n"
+      "content": "// @idosgames/mod-profile — Profile for any game: name, ID, language, sound and motion settings and log out.\n\nexport { profileModule } from \"./module\";\n"
     },
     {
       "path": "model.ts",
-      "content": "// Pure helpers of the profile screen (Unity Alikhan/Username, UI/HUD/Settings): the name rules the\n// server applies, the volume as a percentage, and the typed word that unlocks account deletion.\n// Covered by model.test.ts.\n\nexport const NAME_MIN = 3;\nexport const NAME_MAX = 24;\n\n/** The server trims and wants 3–24 characters; `null` = fine. */\nexport function nameProblem(name: string): \"short\" | \"long\" | null {\n  const n = name.trim().length;\n  if (n < NAME_MIN) return \"short\";\n  if (n > NAME_MAX) return \"long\";\n  return null;\n}\n\nexport function volumePercent(volume: number | null | undefined): number {\n  return Math.round(Math.min(1, Math.max(0, Number(volume ?? 1))) * 100);\n}\n\n/** Deleting an account can't be undone — the player types the word to unlock the button. */\nexport function deleteUnlocked(typed: string, word: string): boolean {\n  return typed.trim().toUpperCase() === word.toUpperCase();\n}\n\n/** \"0x1234…abcd\" — enough to recognise a wallet without a line-wide hash. */\nexport function shortAddress(address: string | null | undefined): string {\n  const a = (address ?? \"\").trim();\n  return a.length > 14 ? `${a.slice(0, 6)}…${a.slice(-4)}` : a;\n}\n\n/** The server's refusal of an unlink → the key of a sentence the player understands; null — show as is. */\nexport function unlinkRefusal(\n  code: string | null | undefined,\n): \"unlinkLogin\" | \"unlinkTooMany\" | \"unlinkMissing\" | null {\n  switch (code) {\n    case \"WALLET_IS_LOGIN_WALLET\":\n      return \"unlinkLogin\";\n    case \"WALLET_CHANGES_TOO_FREQUENT\":\n      return \"unlinkTooMany\";\n    case \"WALLET_NOT_LINKED\":\n      return \"unlinkMissing\";\n    default:\n      return null;\n  }\n}\n\n/** Languages the title offers, in its order; the picker shows them only when there are two or more. */\nexport function languageChoices(\n  locales:\n    | ReadonlyArray<{\n        Locale?: string | null;\n        DisplayName?: string | null;\n        Order?: number | null;\n      }>\n    | null\n    | undefined,\n): Array<{ id: string; name: string }> {\n  return [...(locales ?? [])]\n    .filter((l) => l.Locale)\n    .sort((a, b) => Number(a.Order ?? 0) - Number(b.Order ?? 0))\n    .map((l) => ({ id: l.Locale!, name: l.DisplayName || l.Locale! }));\n}\n"
+      "content": "// Pure helpers of the profile screen (Unity Alikhan/Username, UI/HUD/Settings): the name rules the\n// server applies and the volume as a percentage.\n// Covered by model.test.ts.\n\nexport const NAME_MIN = 3;\nexport const NAME_MAX = 24;\n\n/** The server trims and wants 3–24 characters; `null` = fine. */\nexport function nameProblem(name: string): \"short\" | \"long\" | null {\n  const n = name.trim().length;\n  if (n < NAME_MIN) return \"short\";\n  if (n > NAME_MAX) return \"long\";\n  return null;\n}\n\nexport function volumePercent(volume: number | null | undefined): number {\n  return Math.round(Math.min(1, Math.max(0, Number(volume ?? 1))) * 100);\n}\n\n/** \"0x1234…abcd\" — enough to recognise a wallet without a line-wide hash. */\nexport function shortAddress(address: string | null | undefined): string {\n  const a = (address ?? \"\").trim();\n  return a.length > 14 ? `${a.slice(0, 6)}…${a.slice(-4)}` : a;\n}\n\n/** The server's refusal of an unlink → the key of a sentence the player understands; null — show as is. */\nexport function unlinkRefusal(\n  code: string | null | undefined,\n): \"unlinkLogin\" | \"unlinkTooMany\" | \"unlinkMissing\" | null {\n  switch (code) {\n    case \"WALLET_IS_LOGIN_WALLET\":\n      return \"unlinkLogin\";\n    case \"WALLET_CHANGES_TOO_FREQUENT\":\n      return \"unlinkTooMany\";\n    case \"WALLET_NOT_LINKED\":\n      return \"unlinkMissing\";\n    default:\n      return null;\n  }\n}\n\n/** Languages the title offers, in its order; the picker shows them only when there are two or more. */\nexport function languageChoices(\n  locales:\n    | ReadonlyArray<{\n        Locale?: string | null;\n        DisplayName?: string | null;\n        Order?: number | null;\n      }>\n    | null\n    | undefined,\n): Array<{ id: string; name: string }> {\n  return [...(locales ?? [])]\n    .filter((l) => l.Locale)\n    .sort((a, b) => Number(a.Order ?? 0) - Number(b.Order ?? 0))\n    .map((l) => ({ id: l.Locale!, name: l.DisplayName || l.Locale! }));\n}\n"
     },
     {
       "path": "module.ts",
@@ -60,11 +59,11 @@
     },
     {
       "path": "ProfileScreen.tsx",
-      "content": "import { useCallback, useEffect, useState, type ReactNode } from \"react\";\nimport type { PlayAccessWallet } from \"@idosgames/core\";\nimport type {\n  FeatureRegistry,\n  FeatureScreenProps,\n} from \"@idosgames/module-sdk\";\nimport { useIDosGamesClient, useUserState } from \"@idosgames/react\";\nimport {\n  Button,\n  ConfirmPopup,\n  Icon,\n  Popup,\n  Tabs,\n  errorText,\n  outlined,\n  panel,\n  usePlayerPrefs,\n  useToast,\n  useUiKit,\n  v,\n} from \"@idosgames/react/ui\";\nimport {\n  deleteUnlocked,\n  languageChoices,\n  nameProblem,\n  shortAddress,\n  unlinkRefusal,\n  volumePercent,\n} from \"./model\";\nimport { t } from \"./i18n\";\n\n// Profile and settings (Unity Alikhan/Username, UI/HUD/Settings, Runtime/UI/Consent, Localization):\n// the name and ID, sound, volume and motion (kept on this device), the game's language, tutorials,\n// linked wallets, logging out and deleting the account. Renaming, unlinking a wallet and deleting are\n// popups. No analytics switch (owner's decision 29.09.2026): anonymous analytics stays on as the SDK\n// ships it (client.analytics).\n\nexport function makeProfileScreen(features: FeatureRegistry) {\n  return function ProfileScreen(_: FeatureScreenProps): ReactNode {\n    const client = useIDosGamesClient();\n    const state = useUserState();\n    const toast = useToast();\n    const kit = useUiKit();\n    const [prefs, setPrefs] = usePlayerPrefs();\n    const [name, setName] = useState<string | null>(null);\n    const [renaming, setRenaming] = useState(false);\n    const [ask, setAsk] = useState<\"logout\" | \"delete\" | null>(null);\n    const [locale, setLocale] = useState(client.localization.locale ?? \"\");\n    const id = client.auth.context?.userID ?? \"\";\n    const shown = name ?? state?.PublicData?.Username ?? t(\"guest\");\n    const languages = languageChoices(client.localization.locales);\n\n    const switchLanguage = async (next: string) => {\n      const res = await client.localization.setLocale(next);\n      if (!res.ok) return toast(errorText(res.error), \"error\");\n      setLocale(res.data);\n    };\n\n    return (\n      <div\n        style={{\n          display: \"grid\",\n          gridTemplateColumns: \"minmax(0, 1fr)\",\n          gap: 12,\n          maxWidth: 560,\n          margin: \"0 auto\",\n          width: \"100%\",\n        }}\n      >\n        <div\n          style={{\n            ...panel,\n            padding: 16,\n            display: \"grid\",\n            justifyItems: \"center\",\n            gap: 8,\n          }}\n        >\n          <div\n            style={{\n              width: 84,\n              height: 84,\n              borderRadius: \"50%\",\n              display: \"grid\",\n              placeItems: \"center\",\n              background: `linear-gradient(180deg, ${v.blue}, ${v.blueDeep})`,\n              border: `3px solid color-mix(in srgb, ${v.text} 70%, transparent)`,\n              ...outlined,\n              fontSize: 36,\n            }}\n          >\n            {(shown.trim()[0] ?? \"?\").toUpperCase()}\n          </div>\n          <div style={{ ...outlined, fontSize: 20 }}>{shown}</div>\n          <Button\n            size=\"sm\"\n            tone=\"blue\"\n            onClick={() => setRenaming(true)}\n            data-tutorial-anchor=\"profile:rename\"\n          >\n            <Icon glyph=\"edit\" size={16} /> {t(\"rename\")}\n          </Button>\n          <div\n            style={{\n              display: \"flex\",\n              alignItems: \"center\",\n              gap: 6,\n              maxWidth: \"100%\",\n            }}\n          >\n            <span style={{ ...outlined, fontSize: 11, color: v.textDim }}>\n              {t(\"playerID\")}\n            </span>\n            <span\n              style={{\n                fontFamily: \"monospace\",\n                fontSize: 12,\n                overflow: \"hidden\",\n                textOverflow: \"ellipsis\",\n              }}\n            >\n              {id}\n            </span>\n            <button\n              type=\"button\"\n              aria-label={t(\"playerID\")}\n              onClick={() =>\n                void navigator.clipboard\n                  ?.writeText(id)\n                  .then(() => toast(t(\"copied\")))\n              }\n              style={{\n                background: \"none\",\n                border: \"none\",\n                cursor: \"pointer\",\n                padding: 2,\n              }}\n            >\n              <Icon glyph=\"copy\" size={16} />\n            </button>\n          </div>\n        </div>\n\n        <div style={{ ...panel, padding: 12, display: \"grid\", gap: 12 }}>\n          <div style={{ ...outlined, fontSize: 14, color: v.textDim }}>\n            {t(\"settings\")}\n          </div>\n          <Toggle\n            glyph={prefs.muted ? \"mute\" : \"sound\"}\n            label={t(\"sound\")}\n            value={!prefs.muted}\n            onChange={(on) => {\n              setPrefs({ muted: !on });\n              if (on) kit.play(\"click\");\n            }}\n          />\n          <div\n            style={{ display: \"grid\", gap: 4, opacity: prefs.muted ? 0.5 : 1 }}\n          >\n            <div\n              style={{\n                display: \"flex\",\n                justifyContent: \"space-between\",\n                ...outlined,\n                fontSize: 13,\n              }}\n            >\n              <span>{t(\"volume\")}</span>\n              <span>{volumePercent(prefs.volume)}%</span>\n            </div>\n            <input\n              type=\"range\"\n              min={0}\n              max={100}\n              step={5}\n              disabled={prefs.muted}\n              value={volumePercent(prefs.volume)}\n              onChange={(e) =>\n                setPrefs({ volume: Number(e.target.value) / 100 })\n              }\n              onPointerUp={() => kit.play(\"coin\")}\n              style={{ width: \"100%\", accentColor: v.gold }}\n            />\n          </div>\n          <Toggle\n            glyph=\"flame\"\n            label={t(\"motion\")}\n            value={prefs.reducedMotion}\n            onChange={(on) => setPrefs({ reducedMotion: on })}\n          />\n          {languages.length > 1 ? (\n            <div style={{ display: \"grid\", gap: 6 }}>\n              <div style={{ ...outlined, fontSize: 13 }}>{t(\"language\")}</div>\n              <Tabs\n                tabs={languages.map((l) => ({ id: l.id, label: l.name }))}\n                value={\n                  languages.find((l) => locale.startsWith(l.id))?.id ??\n                  languages[0]!.id\n                }\n                onChange={(l) => void switchLanguage(l)}\n              />\n            </div>\n          ) : null}\n        </div>\n\n        <WalletsSection />\n\n        {features.get(\"tutorials\") ? (\n          <Button tone=\"blue\" onClick={() => features.open(\"tutorials\")}>\n            <Icon glyph=\"bulb\" size={18} /> {t(\"tutorials\")}\n          </Button>\n        ) : null}\n        <Button tone=\"grey\" onClick={() => setAsk(\"logout\")}>\n          <Icon glyph=\"logout\" size={18} /> {t(\"logout\")}\n        </Button>\n        <Button tone=\"red\" onClick={() => setAsk(\"delete\")}>\n          <Icon glyph=\"trash\" size={18} /> {t(\"delete\")}\n        </Button>\n\n        {renaming ? (\n          <RenamePopup\n            current={shown}\n            onClose={() => setRenaming(false)}\n            onDone={(n) => {\n              setName(n);\n              setRenaming(false);\n            }}\n          />\n        ) : null}\n        {ask === \"logout\" ? (\n          <ConfirmPopup\n            title={t(\"logout\")}\n            tone=\"red\"\n            onClose={() => setAsk(null)}\n            // Only the logout: the host returns to the sign-in screen on \"auth:loggedOut\" by itself.\n            // A page reload here blanked the AI Coder's live preview (its files arrive by message\n            // and do not survive one) and restarted the whole app for nothing.\n            onConfirm={() => client.auth.logout()}\n          >\n            <div style={{ ...outlined, fontSize: 14, textAlign: \"center\" }}>\n              {t(\"logoutAsk\")}\n            </div>\n          </ConfirmPopup>\n        ) : null}\n        {ask === \"delete\" ? <DeletePopup onClose={() => setAsk(null)} /> : null}\n      </div>\n    );\n  };\n}\n\nfunction Toggle({\n  glyph,\n  label,\n  value,\n  onChange,\n}: {\n  glyph: \"sound\" | \"mute\" | \"flame\" | \"globe\";\n  label: string;\n  value: boolean;\n  onChange: (on: boolean) => void;\n}): ReactNode {\n  return (\n    <button\n      type=\"button\"\n      role=\"switch\"\n      aria-checked={value}\n      onClick={() => onChange(!value)}\n      style={{\n        display: \"flex\",\n        alignItems: \"center\",\n        gap: 10,\n        background: \"none\",\n        border: \"none\",\n        color: v.text,\n        cursor: \"pointer\",\n        padding: 0,\n        textAlign: \"left\",\n      }}\n    >\n      <Icon glyph={glyph} size={24} />\n      <span style={{ flex: 1, ...outlined, fontSize: 14 }}>{label}</span>\n      <span\n        style={{\n          width: 52,\n          height: 30,\n          borderRadius: 15,\n          background: value ? v.green : v.wellSoft,\n          boxShadow: `inset 0 0 0 1px ${v.line}`,\n          position: \"relative\",\n          transition: \"background .2s\",\n        }}\n      >\n        <span\n          style={{\n            position: \"absolute\",\n            top: 3,\n            left: value ? 25 : 3,\n            width: 24,\n            height: 24,\n            borderRadius: \"50%\",\n            background: \"#fff\",\n            transition: \"left .2s\",\n            boxShadow: \"0 2px 4px rgba(0,0,0,.3)\",\n          }}\n        />\n      </span>\n    </button>\n  );\n}\n\n/**\n * Wallets linked by signature, each with \"Unlink\" (`client.auth.unlinkWallet`). Hidden while there are\n * none. The wallet an account signs in with has no button: the server refuses it (`CanUnlink`).\n */\nfunction WalletsSection(): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const [wallets, setWallets] = useState<PlayAccessWallet[]>([]);\n  const [asking, setAsking] = useState<PlayAccessWallet | null>(null);\n\n  const load = useCallback(async () => {\n    const res = await client.blockchain.getPlayAccess();\n    if (res.ok) setWallets(res.data.LinkedWallets ?? []);\n  }, [client]);\n  useEffect(() => {\n    void load();\n  }, [load]);\n\n  // The popup shows the spinner and closes itself when this resolves.\n  const unlink = async (wallet: PlayAccessWallet) => {\n    const res = await client.auth.unlinkWallet(wallet.NetworkID ?? \"\");\n    if (!res.ok) {\n      const known = unlinkRefusal(res.error);\n      toast(known ? t(known) : errorText(res.error), \"error\");\n    } else toast(t(\"unlinked\"), \"success\");\n    await load();\n  };\n\n  if (wallets.length === 0) return null;\n  return (\n    <div style={{ ...panel, padding: 12, display: \"grid\", gap: 10 }}>\n      <div style={{ ...outlined, fontSize: 14, color: v.textDim }}>\n        {t(\"wallets\")}\n      </div>\n      {wallets.map((w) => (\n        <div\n          key={`${w.NetworkID}:${w.Address}`}\n          style={{\n            display: \"flex\",\n            alignItems: \"center\",\n            gap: 10,\n            minWidth: 0,\n          }}\n        >\n          <Icon glyph=\"link\" size={22} />\n          <div style={{ flex: 1, minWidth: 0, display: \"grid\" }}>\n            <span\n              style={{\n                fontFamily: \"monospace\",\n                fontSize: 13,\n                overflow: \"hidden\",\n                textOverflow: \"ellipsis\",\n              }}\n            >\n              {shortAddress(w.Address)}\n            </span>\n            <span style={{ ...outlined, fontSize: 11, color: v.textDim }}>\n              {(w.NetworkID ?? \"\").toUpperCase()}\n              {w.CanUnlink === false ? ` · ${t(\"loginWallet\")}` : \"\"}\n            </span>\n          </div>\n          {w.CanUnlink !== false ? (\n            <Button size=\"sm\" tone=\"grey\" onClick={() => setAsking(w)}>\n              {t(\"unlink\")}\n            </Button>\n          ) : null}\n        </div>\n      ))}\n      {asking ? (\n        <ConfirmPopup\n          title={t(\"unlinkTitle\")}\n          confirmLabel={t(\"unlink\")}\n          tone=\"red\"\n          onClose={() => setAsking(null)}\n          onConfirm={() => unlink(asking)}\n        >\n          <div\n            style={{\n              fontFamily: \"monospace\",\n              fontSize: 14,\n              textAlign: \"center\",\n            }}\n          >\n            {shortAddress(asking.Address)}\n          </div>\n          <div\n            style={{\n              ...outlined,\n              fontSize: 13,\n              textAlign: \"center\",\n              lineHeight: 1.4,\n            }}\n          >\n            {t(\"unlinkAsk\")}\n          </div>\n        </ConfirmPopup>\n      ) : null}\n    </div>\n  );\n}\n\nfunction RenamePopup({\n  current,\n  onClose,\n  onDone,\n}: {\n  current: string;\n  onClose: () => void;\n  onDone: (name: string) => void;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const [value, setValue] = useState(current);\n  const [busy, setBusy] = useState(false);\n  const problem = nameProblem(value);\n  const save = async () => {\n    if (problem) return;\n    setBusy(true);\n    const res = await client.user.changeUsername(value.trim());\n    setBusy(false);\n    if (!res.ok) return toast(errorText(res.error), \"error\");\n    toast(t(\"renamed\"), \"success\");\n    // The SDK does not patch the cached name — the screen shows the server's answer.\n    onDone(res.data.Username ?? value.trim());\n  };\n  return (\n    <Popup title={t(\"rename\")} onClose={onClose} width={400}>\n      <input\n        value={value}\n        autoFocus\n        maxLength={40}\n        onChange={(e) => setValue(e.target.value)}\n        onKeyDown={(e) => e.key === \"Enter\" && void save()}\n        placeholder={t(\"newName\")}\n        style={{\n          ...panel,\n          padding: \"12px 14px\",\n          fontSize: 16,\n          color: v.text,\n          outline: \"none\",\n        }}\n      />\n      {problem ? (\n        <div style={{ ...outlined, fontSize: 12, color: v.red }}>\n          {problem === \"short\" ? t(\"nameShort\") : t(\"nameLong\")}\n        </div>\n      ) : null}\n      <Button\n        tone=\"green\"\n        disabled={!!problem}\n        busy={busy}\n        onClick={() => void save()}\n      >\n        {t(\"save\")}\n      </Button>\n    </Popup>\n  );\n}\n\nfunction DeletePopup({ onClose }: { onClose: () => void }): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const [typed, setTyped] = useState(\"\");\n  const [busy, setBusy] = useState(false);\n  const word = t(\"deleteWord\");\n  const remove = async () => {\n    setBusy(true);\n    const res = await client.user.deleteUserAccount();\n    setBusy(false);\n    if (!res.ok) return toast(errorText(res.error), \"error\");\n    // Logout first: it clears the app's notifications, and \"deleted\" must be seen on the\n    // sign-in screen the host returns to.\n    client.auth.logout();\n    toast(t(\"deleted\"));\n  };\n  return (\n    <Popup title={t(\"delete\")} onClose={onClose} width={420}>\n      <div style={{ ...outlined, fontSize: 14, textAlign: \"center\" }}>\n        {t(\"deleteAsk\")} <span style={{ color: v.red }}>{word}</span>\n      </div>\n      <input\n        value={typed}\n        onChange={(e) => setTyped(e.target.value)}\n        placeholder={word}\n        style={{\n          ...panel,\n          padding: \"12px 14px\",\n          fontSize: 16,\n          color: v.text,\n          outline: \"none\",\n          textAlign: \"center\",\n        }}\n      />\n      <Button\n        tone=\"red\"\n        disabled={!deleteUnlocked(typed, word)}\n        busy={busy}\n        onClick={() => void remove()}\n      >\n        {t(\"delete\")}\n      </Button>\n    </Popup>\n  );\n}\n"
+      "content": "import { useCallback, useEffect, useState, type ReactNode } from \"react\";\nimport type { PlayAccessWallet } from \"@idosgames/core\";\nimport type {\n  FeatureRegistry,\n  FeatureScreenProps,\n} from \"@idosgames/module-sdk\";\nimport { useIDosGamesClient, useUserState } from \"@idosgames/react\";\nimport {\n  Button,\n  ConfirmPopup,\n  Icon,\n  Popup,\n  Tabs,\n  errorText,\n  outlined,\n  panel,\n  usePlayerPrefs,\n  useToast,\n  useUiKit,\n  v,\n} from \"@idosgames/react/ui\";\nimport {\n  languageChoices,\n  nameProblem,\n  shortAddress,\n  unlinkRefusal,\n  volumePercent,\n} from \"./model\";\nimport { t } from \"./i18n\";\n\n// Profile and settings (Unity Alikhan/Username, UI/HUD/Settings, Runtime/UI/Consent, Localization):\n// the name and ID, sound, volume and motion (kept on this device), the game's language, tutorials,\n// linked wallets and logging out. Renaming and unlinking a wallet are popups. No \"Delete account\"\n// button (owner's decision 03.10.2026) — `client.user.deleteUserAccount()` stays in the SDK. No analytics switch (owner's decision 29.09.2026): anonymous analytics stays on as the SDK\n// ships it (client.analytics).\n\nexport function makeProfileScreen(features: FeatureRegistry) {\n  return function ProfileScreen(_: FeatureScreenProps): ReactNode {\n    const client = useIDosGamesClient();\n    const state = useUserState();\n    const toast = useToast();\n    const kit = useUiKit();\n    const [prefs, setPrefs] = usePlayerPrefs();\n    const [name, setName] = useState<string | null>(null);\n    const [renaming, setRenaming] = useState(false);\n    const [ask, setAsk] = useState<\"logout\" | null>(null);\n    const [locale, setLocale] = useState(client.localization.locale ?? \"\");\n    const id = client.auth.context?.userID ?? \"\";\n    const shown = name ?? state?.PublicData?.Username ?? t(\"guest\");\n    const languages = languageChoices(client.localization.locales);\n\n    const switchLanguage = async (next: string) => {\n      const res = await client.localization.setLocale(next);\n      if (!res.ok) return toast(errorText(res.error), \"error\");\n      setLocale(res.data);\n    };\n\n    return (\n      <div\n        style={{\n          display: \"grid\",\n          gridTemplateColumns: \"minmax(0, 1fr)\",\n          gap: 12,\n          maxWidth: 560,\n          margin: \"0 auto\",\n          width: \"100%\",\n        }}\n      >\n        <div\n          style={{\n            ...panel,\n            padding: 16,\n            display: \"grid\",\n            justifyItems: \"center\",\n            gap: 8,\n          }}\n        >\n          <div\n            style={{\n              width: 84,\n              height: 84,\n              borderRadius: \"50%\",\n              display: \"grid\",\n              placeItems: \"center\",\n              background: `linear-gradient(180deg, ${v.blue}, ${v.blueDeep})`,\n              border: `3px solid color-mix(in srgb, ${v.text} 70%, transparent)`,\n              ...outlined,\n              fontSize: 36,\n            }}\n          >\n            {(shown.trim()[0] ?? \"?\").toUpperCase()}\n          </div>\n          <div style={{ ...outlined, fontSize: 20 }}>{shown}</div>\n          <Button\n            size=\"sm\"\n            tone=\"blue\"\n            onClick={() => setRenaming(true)}\n            data-tutorial-anchor=\"profile:rename\"\n          >\n            <Icon glyph=\"edit\" size={16} /> {t(\"rename\")}\n          </Button>\n          <div\n            style={{\n              display: \"flex\",\n              alignItems: \"center\",\n              gap: 6,\n              maxWidth: \"100%\",\n            }}\n          >\n            <span style={{ ...outlined, fontSize: 11, color: v.textDim }}>\n              {t(\"playerID\")}\n            </span>\n            <span\n              style={{\n                fontFamily: \"monospace\",\n                fontSize: 12,\n                overflow: \"hidden\",\n                textOverflow: \"ellipsis\",\n              }}\n            >\n              {id}\n            </span>\n            <button\n              type=\"button\"\n              aria-label={t(\"playerID\")}\n              onClick={() =>\n                void navigator.clipboard\n                  ?.writeText(id)\n                  .then(() => toast(t(\"copied\")))\n              }\n              style={{\n                background: \"none\",\n                border: \"none\",\n                cursor: \"pointer\",\n                padding: 2,\n              }}\n            >\n              <Icon glyph=\"copy\" size={16} />\n            </button>\n          </div>\n        </div>\n\n        <div style={{ ...panel, padding: 12, display: \"grid\", gap: 12 }}>\n          <div style={{ ...outlined, fontSize: 14, color: v.textDim }}>\n            {t(\"settings\")}\n          </div>\n          <Toggle\n            glyph={prefs.muted ? \"mute\" : \"sound\"}\n            label={t(\"sound\")}\n            value={!prefs.muted}\n            onChange={(on) => {\n              setPrefs({ muted: !on });\n              if (on) kit.play(\"click\");\n            }}\n          />\n          <div\n            style={{ display: \"grid\", gap: 4, opacity: prefs.muted ? 0.5 : 1 }}\n          >\n            <div\n              style={{\n                display: \"flex\",\n                justifyContent: \"space-between\",\n                ...outlined,\n                fontSize: 13,\n              }}\n            >\n              <span>{t(\"volume\")}</span>\n              <span>{volumePercent(prefs.volume)}%</span>\n            </div>\n            <input\n              type=\"range\"\n              min={0}\n              max={100}\n              step={5}\n              disabled={prefs.muted}\n              value={volumePercent(prefs.volume)}\n              onChange={(e) =>\n                setPrefs({ volume: Number(e.target.value) / 100 })\n              }\n              onPointerUp={() => kit.play(\"coin\")}\n              style={{ width: \"100%\", accentColor: v.gold }}\n            />\n          </div>\n          <Toggle\n            glyph=\"flame\"\n            label={t(\"motion\")}\n            value={prefs.reducedMotion}\n            onChange={(on) => setPrefs({ reducedMotion: on })}\n          />\n          {languages.length > 1 ? (\n            <div style={{ display: \"grid\", gap: 6 }}>\n              <div style={{ ...outlined, fontSize: 13 }}>{t(\"language\")}</div>\n              <Tabs\n                tabs={languages.map((l) => ({ id: l.id, label: l.name }))}\n                value={\n                  languages.find((l) => locale.startsWith(l.id))?.id ??\n                  languages[0]!.id\n                }\n                onChange={(l) => void switchLanguage(l)}\n              />\n            </div>\n          ) : null}\n        </div>\n\n        <WalletsSection />\n\n        {features.get(\"tutorials\") ? (\n          <Button tone=\"blue\" onClick={() => features.open(\"tutorials\")}>\n            <Icon glyph=\"bulb\" size={18} /> {t(\"tutorials\")}\n          </Button>\n        ) : null}\n        <Button tone=\"grey\" onClick={() => setAsk(\"logout\")}>\n          <Icon glyph=\"logout\" size={18} /> {t(\"logout\")}\n        </Button>\n\n        {renaming ? (\n          <RenamePopup\n            current={shown}\n            onClose={() => setRenaming(false)}\n            onDone={(n) => {\n              setName(n);\n              setRenaming(false);\n            }}\n          />\n        ) : null}\n        {ask === \"logout\" ? (\n          <ConfirmPopup\n            title={t(\"logout\")}\n            tone=\"red\"\n            onClose={() => setAsk(null)}\n            // Only the logout: the host returns to the sign-in screen on \"auth:loggedOut\" by itself.\n            // A page reload here blanked the AI Coder's live preview (its files arrive by message\n            // and do not survive one) and restarted the whole app for nothing.\n            onConfirm={() => client.auth.logout()}\n          >\n            <div style={{ ...outlined, fontSize: 14, textAlign: \"center\" }}>\n              {t(\"logoutAsk\")}\n            </div>\n          </ConfirmPopup>\n        ) : null}\n      </div>\n    );\n  };\n}\n\nfunction Toggle({\n  glyph,\n  label,\n  value,\n  onChange,\n}: {\n  glyph: \"sound\" | \"mute\" | \"flame\" | \"globe\";\n  label: string;\n  value: boolean;\n  onChange: (on: boolean) => void;\n}): ReactNode {\n  return (\n    <button\n      type=\"button\"\n      role=\"switch\"\n      aria-checked={value}\n      onClick={() => onChange(!value)}\n      style={{\n        display: \"flex\",\n        alignItems: \"center\",\n        gap: 10,\n        background: \"none\",\n        border: \"none\",\n        color: v.text,\n        cursor: \"pointer\",\n        padding: 0,\n        textAlign: \"left\",\n      }}\n    >\n      <Icon glyph={glyph} size={24} />\n      <span style={{ flex: 1, ...outlined, fontSize: 14 }}>{label}</span>\n      <span\n        style={{\n          width: 52,\n          height: 30,\n          borderRadius: 15,\n          background: value ? v.green : v.wellSoft,\n          boxShadow: `inset 0 0 0 1px ${v.line}`,\n          position: \"relative\",\n          transition: \"background .2s\",\n        }}\n      >\n        <span\n          style={{\n            position: \"absolute\",\n            top: 3,\n            left: value ? 25 : 3,\n            width: 24,\n            height: 24,\n            borderRadius: \"50%\",\n            background: \"#fff\",\n            transition: \"left .2s\",\n            boxShadow: \"0 2px 4px rgba(0,0,0,.3)\",\n          }}\n        />\n      </span>\n    </button>\n  );\n}\n\n/**\n * Wallets linked by signature, each with \"Unlink\" (`client.auth.unlinkWallet`). Hidden while there are\n * none. The wallet an account signs in with has no button: the server refuses it (`CanUnlink`).\n */\nfunction WalletsSection(): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const [wallets, setWallets] = useState<PlayAccessWallet[]>([]);\n  const [asking, setAsking] = useState<PlayAccessWallet | null>(null);\n\n  const load = useCallback(async () => {\n    const res = await client.blockchain.getPlayAccess();\n    if (res.ok) setWallets(res.data.LinkedWallets ?? []);\n  }, [client]);\n  useEffect(() => {\n    void load();\n  }, [load]);\n\n  // The popup shows the spinner and closes itself when this resolves.\n  const unlink = async (wallet: PlayAccessWallet) => {\n    const res = await client.auth.unlinkWallet(wallet.NetworkID ?? \"\");\n    if (!res.ok) {\n      const known = unlinkRefusal(res.error);\n      toast(known ? t(known) : errorText(res.error), \"error\");\n    } else toast(t(\"unlinked\"), \"success\");\n    await load();\n  };\n\n  if (wallets.length === 0) return null;\n  return (\n    <div style={{ ...panel, padding: 12, display: \"grid\", gap: 10 }}>\n      <div style={{ ...outlined, fontSize: 14, color: v.textDim }}>\n        {t(\"wallets\")}\n      </div>\n      {wallets.map((w) => (\n        <div\n          key={`${w.NetworkID}:${w.Address}`}\n          style={{\n            display: \"flex\",\n            alignItems: \"center\",\n            gap: 10,\n            minWidth: 0,\n          }}\n        >\n          <Icon glyph=\"link\" size={22} />\n          <div style={{ flex: 1, minWidth: 0, display: \"grid\" }}>\n            <span\n              style={{\n                fontFamily: \"monospace\",\n                fontSize: 13,\n                overflow: \"hidden\",\n                textOverflow: \"ellipsis\",\n              }}\n            >\n              {shortAddress(w.Address)}\n            </span>\n            <span style={{ ...outlined, fontSize: 11, color: v.textDim }}>\n              {(w.NetworkID ?? \"\").toUpperCase()}\n              {w.CanUnlink === false ? ` · ${t(\"loginWallet\")}` : \"\"}\n            </span>\n          </div>\n          {w.CanUnlink !== false ? (\n            <Button size=\"sm\" tone=\"grey\" onClick={() => setAsking(w)}>\n              {t(\"unlink\")}\n            </Button>\n          ) : null}\n        </div>\n      ))}\n      {asking ? (\n        <ConfirmPopup\n          title={t(\"unlinkTitle\")}\n          confirmLabel={t(\"unlink\")}\n          tone=\"red\"\n          onClose={() => setAsking(null)}\n          onConfirm={() => unlink(asking)}\n        >\n          <div\n            style={{\n              fontFamily: \"monospace\",\n              fontSize: 14,\n              textAlign: \"center\",\n            }}\n          >\n            {shortAddress(asking.Address)}\n          </div>\n          <div\n            style={{\n              ...outlined,\n              fontSize: 13,\n              textAlign: \"center\",\n              lineHeight: 1.4,\n            }}\n          >\n            {t(\"unlinkAsk\")}\n          </div>\n        </ConfirmPopup>\n      ) : null}\n    </div>\n  );\n}\n\nfunction RenamePopup({\n  current,\n  onClose,\n  onDone,\n}: {\n  current: string;\n  onClose: () => void;\n  onDone: (name: string) => void;\n}): ReactNode {\n  const client = useIDosGamesClient();\n  const toast = useToast();\n  const [value, setValue] = useState(current);\n  const [busy, setBusy] = useState(false);\n  const problem = nameProblem(value);\n  const save = async () => {\n    if (problem) return;\n    setBusy(true);\n    const res = await client.user.changeUsername(value.trim());\n    setBusy(false);\n    if (!res.ok) return toast(errorText(res.error), \"error\");\n    toast(t(\"renamed\"), \"success\");\n    // The SDK does not patch the cached name — the screen shows the server's answer.\n    onDone(res.data.Username ?? value.trim());\n  };\n  return (\n    <Popup title={t(\"rename\")} onClose={onClose} width={400}>\n      <input\n        value={value}\n        autoFocus\n        maxLength={40}\n        onChange={(e) => setValue(e.target.value)}\n        onKeyDown={(e) => e.key === \"Enter\" && void save()}\n        placeholder={t(\"newName\")}\n        style={{\n          ...panel,\n          padding: \"12px 14px\",\n          fontSize: 16,\n          color: v.text,\n          outline: \"none\",\n        }}\n      />\n      {problem ? (\n        <div style={{ ...outlined, fontSize: 12, color: v.red }}>\n          {problem === \"short\" ? t(\"nameShort\") : t(\"nameLong\")}\n        </div>\n      ) : null}\n      <Button\n        tone=\"green\"\n        disabled={!!problem}\n        busy={busy}\n        onClick={() => void save()}\n      >\n        {t(\"save\")}\n      </Button>\n    </Popup>\n  );\n}\n"
     },
     {
       "path": "module.meta.json",
-      "content": "{\n  \"id\": \"profile\",\n  \"type\": \"feature\",\n  \"inBase\": true,\n  \"summary\": \"Profile and settings for any game: name and ID, sound, volume and motion, language, tutorials, log out and account deletion.\",\n  \"description\": \"A ready profile screen (Unity Alikhan/Username, UI/HUD/Settings, Runtime/UI/Consent, Localization) for ANY game, built on the @idosgames/react/ui kit. The player's name (rename in a popup with the server's rules: 3–24 characters, trimmed) and ID with copy; settings: sound on/off, volume and 'fewer animations' — the kit's player prefs, kept on this device and applied to every screen at once — the game's language (the title's languages, when there are two or more). Buttons: Tutorials (when tutorials is installed), Log out (confirmed) and Delete account — a popup that unlocks only after the player types the confirmation word, then deletes this game's data for the player. Registers the 'profile' feature; the lobby's profile button opens it. No title settings needed.\",\n  \"provides\": [\n    \"player name and ID\",\n    \"rename popup\",\n    \"sound, volume and fewer animations\",\n    \"language picker\",\n    \"log out\",\n    \"account deletion with confirmation\"\n  ],\n  \"tags\": [\n    \"profile\",\n    \"settings\",\n    \"account\",\n    \"sound\",\n    \"language\",\n    \"privacy\",\n    \"ui\",\n    \"screen\"\n  ],\n  \"author\": {\n    \"name\": \"iDos Games\",\n    \"url\": \"https://idosgames.com\"\n  },\n  \"version\": \"0.1.2\"\n}\n"
+      "content": "{\n  \"id\": \"profile\",\n  \"type\": \"feature\",\n  \"inBase\": true,\n  \"summary\": \"Profile and settings for any game: name and ID, sound, volume and motion, language, tutorials and log out.\",\n  \"description\": \"A ready profile screen (Unity Alikhan/Username, UI/HUD/Settings, Runtime/UI/Consent, Localization) for ANY game, built on the @idosgames/react/ui kit. The player's name (rename in a popup with the server's rules: 3–24 characters, trimmed) and ID with copy; settings: sound on/off, volume and 'fewer animations' — the kit's player prefs, kept on this device and applied to every screen at once — the game's language (the title's languages, when there are two or more). Buttons: Tutorials (when tutorials is installed) and Log out (confirmed). Registers the 'profile' feature; the lobby's profile button opens it. No title settings needed.\",\n  \"provides\": [\n    \"player name and ID\",\n    \"rename popup\",\n    \"sound, volume and fewer animations\",\n    \"language picker\",\n    \"log out\"\n  ],\n  \"tags\": [\n    \"profile\",\n    \"settings\",\n    \"account\",\n    \"sound\",\n    \"language\",\n    \"privacy\",\n    \"ui\",\n    \"screen\"\n  ],\n  \"author\": {\n    \"name\": \"iDos Games\",\n    \"url\": \"https://idosgames.com\"\n  },\n  \"version\": \"0.1.3\"\n}\n"
     }
   ]
 }

package/registry/modules/pvp.json

@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/quests.json

@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/rewards.json

@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/season.json

@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/store.json

@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/tutorials.json

@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/modules/voxelcraft.json

@@ -70,7 +70,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "three": "0.185.1"
   },
   "contentHash": "8aa30c0f20465efb1cfc3d03041e01c68d9d622ec121cff83fc6a5562ad94166",

package/registry/modules/workshop.json

@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@idosgames/core": "0.21.0",
-    "@idosgames/module-sdk": "0.8.2",
+    "@idosgames/module-sdk": "0.9.0",
     "@idosgames/react": "0.4.4",
     "react": "19.2.7"
   },

package/registry/skills/idosgames-compose-modules.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-compose-modules",
   "description": "Put an iDosGames app together from the base and modules — the systems (shop, heroes, leaderboards, quests, chests, multiplayer…) as lobby tabs, one or several games behind \"Play\", progress shared across them. Use this whenever a developer wants to COMBINE or MERGE modules into a single title, add or remove a system, add a second game, switch between the lobby and game modes, share currency/inventory across modules, or asks how the lobby, \"Play\", ctx.modes, activeOnly panels, the shared-UI roles (sharedUi, shouldDraw, the \"modes\" role), typed cross-module events (defineTopic/shape) or host-level shared state work. Builds on idosgames-getting-started (scaffolding) and idosgames-module-contract (a single module).",
-  "content": "---\nname: idosgames-compose-modules\ndescription: >-\n  Put an iDosGames app together from the base and modules — the systems (shop, heroes, leaderboards,\n  quests, chests, multiplayer…) as lobby tabs, one or several games behind \"Play\", progress shared across them. Use this\n  whenever a developer wants to COMBINE or MERGE modules into a single title, add or remove a system,\n  add a second game, switch between the lobby and game modes, share currency/inventory across modules,\n  or asks how the lobby, \"Play\", ctx.modes, activeOnly panels, the shared-UI roles (sharedUi,\n  shouldDraw, the \"modes\" role), typed cross-module events (defineTopic/shape) or host-level shared\n  state work. Builds on idosgames-getting-started (scaffolding) and idosgames-module-contract (a single\n  module).\n---\n\n# Putting an app together: the base + modules\n\nEvery project is **the base + modules**. The base (`src/base/`, from the host scaffold) is sign-in and\nthe lobby; everything else is a module in `src/modules/<id>/`:\n\n- **systems** (`type: feature`) — one per player-facing module of the engine: store, premium (VIP),\n  character, inventory, lootboxes, boosts, leaderboard, rewards (daily), quests, collections, craft,\n  marketplace, deals, events, coop-events, season, friends, chat, invite, pvp, multiplayer, profile,\n  tutorials, workshop, ai, mailbox. Each registers its screen as a **feature** → a tab of the lobby.\n  The base installs only six of them into every new project (`inBase: true`: profile, inventory,\n  invite, friends, quests, mailbox); every other system is installed only when the app needs it — a game\n  brings the ones it lists in `uses`, and you install any other one as soon as the task needs what\n  it `provides` (InstallModule / `get_module`) — the user does not have to name the module; reuse it\n  instead of writing that feature again. Never install one the task does not need.\n- **games** (`type: template`) — board-game, idle-rpg, voxelcraft, mini-game, or the game's own. Each\n  registers a **route** → a \"Play\" button in the lobby. A game that plugs into a system lists it in\n  `uses` in its module.meta.json (`ctx.multiplayer` → `\"multiplayer\"`, `ctx.content` → `\"workshop\"`;\n  `npm run check` enforces those two) — install those together with the game.\n\n## Register modules\n\n```ts\n// src/modules.ts — the platform regenerates it; by hand it is imports + the array\nexport const modules: Module[] = [\n  storeModule, // systems: lobby tabs\n  characterModule,\n  leaderboardModule,\n  boardGameModule, // games: \"Play\"\n  idleRpgModule,\n];\n```\n\n`src/main.tsx` mounts `[baseModule, ...modules]`. After sign-in the player lands in the lobby\n(`src/app.config.ts` `start` can send them straight into a game). \"Play\" switches the host to the\ngame's mode: only the active mode's scene is mounted and ticking; the rest are suspended (their RAF\nstops). This is why two different engines (Three + Phaser) live in one project — they never render\nat the same time. Over a game the base draws only a small \"To the lobby\" button.\n\n- A system tab is hidden while the title has nothing for it (no store offers, no heroes…): the module\n  registers with `available: false` and calls `ctx.features.setAvailable(id, ok, reason)`.\n- `ctx.modes.list()` / `current()` / `subscribe()` — every mode (id, label, icon, module, module type);\n  the lobby builds \"Play\" from the `game` ones. Switch with `ctx.navigate(id)` (`\"lobby\"` is the base).\n- Open another system's screen by id: `ctx.features.open(\"store\")` — from a game too (the host shows\n  it in a window while the lobby is off screen). Never import another module.\n\n## Share progress across modes (the merge)\n\nShared state lives in the ONE SDK client, not in any module. Every module reads/writes the same\n`client` (currency, inventory, characters), so progress carries across modes automatically:\n\n- Gold earned idle in the RPG mode is spendable in the Board mode and in the shop — same\n  `client.currency`, same cache. No cross-module plumbing needed for durable state.\n- For live cross-module signals (not durable state), use `ctx.events` with a **typed topic** — see\n  \"Signals between modules\" below.\n- Modules never import each other's files or `src/base/`. The client and the event bus are the seams\n  between them — which is what keeps a module reusable in another game. Code several of THIS game's\n  modules need (shared types, the game's UI kit, helpers) goes to `src/shared/`, which never imports a\n  module (see idosgames-project-structure).\n\n## Shared chrome: roles, and the base takes them\n\nBalances, the crypto wallet, the status line, \"Log out\" / player ID, the menu of features and the\nswitch between modes are **shared-UI roles** (`currency-bar | wallet | status | account | menu |\nmodes`). A module that draws one for EVERY mode declares it statically on the module object —\nthe base does:\n\n```ts\ndefineModule({\n  id: \"base\",\n  meta: { name: \"Base\", type: \"app\", engine: \"dom\" },\n  sharedUi: {\n    provides: [\"currency-bar\", \"wallet\", \"account\", \"menu\", \"modes\"],\n  },\n  setup(ctx) {\n    /* the lobby: balances, wallet, profile, tabs, \"Play\" */\n  },\n});\n```\n\nThe host resolves role owners from these declarations BEFORE any `setup()` — the first provider wins,\na conflict is warned — and every module asks `ctx.sharedUi.shouldDraw(role)`. A game draws its own\ncopy only while nobody took the role. So:\n\n- Next to the base a game hides its own balances and wallet by itself. Do NOT edit a catalog game to\n  remove them: it does that itself, and an edit marks it customized (no more catalog updates).\n- `status` — the line of a game's own actions (\"Rolling…\") — stays with each game.\n- A game installed without a base stays complete — nobody owns a role, it draws everything, and the\n  host draws its own nav of routes, ☰ and \"Log out\" (those are the host-drawn roles `modes`, `menu`,\n  `account`).\n- A new module that needs, say, the balance bar but does not draw it declares\n  `sharedUi: { requires: [\"currency-bar\"] }`; with no provider installed the host warns.\n\n**Layout is the host's job.** A game's overlay fills the screen under the base's small button; a\nscene's own DOM HUD can keep clear of host chrome with the CSS variables on the host root —\n`top: calc(var(--idos-safe-top, 0px) + 8px)`, `bottom: calc(var(--idos-safe-bottom, 0px) + 8px)`\n(voxelcraft's hotbar does this). Both are 0 when nothing is pinned. `hud`-slot panels are wrapped in\n`display: contents`, so a panel can stretch (`flex: 1`) and decide its own pointer-events: let clicks\nthrough to the game, take them only on controls.\n\n## Signals between modules (typed topics)\n\nA topic is a token passed by value: the name carries the major version, the payload is a flat JSON\nshape — one artifact that gives the TS type, the runtime check and the catalog entry.\n\n```ts\n// idle-rpg/events.ts — the EMITTER owns the topic\nimport { defineTopic, shape } from \"@idosgames/module-sdk\";\nexport const characterUpgraded = defineTopic(\n  \"idle-rpg:character-upgraded@1\",\n  shape({ characterId: \"string\", level: \"number\" }),\n);\n// setup(): hand the panel a callback that does\n//   ctx.events.emit(characterUpgraded, { characterId, level });\n```\n\n```ts\n// board-game/events.ts — the LISTENER keeps its OWN copy (copied from the catalog), never an import.\n// Optional: idle-rpg may not be installed. Only the fields this module reads.\nexport const idleCharacterUpgraded = defineTopic(\n  \"idle-rpg:character-upgraded@1\",\n  shape({ level: \"number\" }),\n);\n// setup() — NOT a panel effect (activeOnly panels unmount with their mode and miss events):\nctx.events.on(idleCharacterUpgraded, ({ level }) =>\n  news.push(`Idle RPG hero reached Lv ${level}`),\n);\n```\n\nDeclare both sides in `module.meta.json` — the catalog and the agent read this, not your code:\n\n```json\n\"events\": {\n  \"emits\": [{ \"topic\": \"idle-rpg:character-upgraded@1\", \"when\": \"a hero levelled up\",\n              \"payload\": { \"characterId\": \"string\", \"level\": \"number\" } }],\n  \"listens\": [{ \"topic\": \"idle-rpg:character-upgraded@1\", \"why\": \"news chip in the board HUD\" }]\n}\n```\n\nRules:\n\n- Name `<your-module-id>:<event>@<major>`. Emit only into your own namespace — the host drops an\n  emit into another module's namespace with `console.error`; `host:` is reserved. The only topics\n  you import are `hostTopics` from `@idosgames/module-sdk` (`hostTopics.modeChanged` =\n  `host:mode-changed@1 { from?: string; to: string }`, sent on every mode switch).\n- Shape leaves: `\"string\" | \"number\" | \"boolean\"`, with `\"[]\"` and/or a trailing `\"?\"`; nested\n  objects allowed. Payloads are plain JSON — no functions, class instances or engine objects.\n- An incompatible change is a NEW topic `@2` (send both during the transition); within a major, only\n  add fields. A listener whose fields are missing is skipped (one `console.warn`), never crashed.\n- An event is a signal, not state, and is never replayed — \"what exists now\" is SDK data or\n  `ctx.sharedUi`. No request/response between modules: if you need an answer, it is data.\n- A throwing handler does not stop other listeners or reach the emitter; the host removes every\n  subscription on logout, so re-login does not double handlers.\n- In the AI editor's preview, `gameState` returns the last 50 events, who listens to what, and hints\n  like \"board-game listens to x@1 but only x@2 is emitted\".\n- A game's OWN modules may keep shared topic tokens in `src/shared/events/` and import them on both\n  sides — still declare them in each `module.meta.json`.\n\n## Reference app\n\nThe base + the systems + `board-game` + `idle-rpg`:\n\n- sign-in → the lobby: balances, wallet and profile on top, the systems as tabs, \"Play\" with two games;\n- \"Play\" → one engine scene mounted at a time; the base's button returns to the lobby;\n- the games hide their own balances and wallet (the lobby has them); their status lines stay theirs;\n- currency changed in one mode is immediately visible in the others and in the lobby; levelling a hero\n  in Idle RPG shows a news chip on the board (`idle-rpg:character-upgraded@1`).\n\nTo pull the modules, use `get_module {id}` for each (MCP) and register them as above. Adjust layouts\nper module (a full-bleed overlay UI vs a docked side panel) — see each module's RootPanel.\n",
+  "content": "---\nname: idosgames-compose-modules\ndescription: >-\n  Put an iDosGames app together from the base and modules — the systems (shop, heroes, leaderboards,\n  quests, chests, multiplayer…) as lobby tabs, one or several games behind \"Play\", progress shared across them. Use this\n  whenever a developer wants to COMBINE or MERGE modules into a single title, add or remove a system,\n  add a second game, switch between the lobby and game modes, share currency/inventory across modules,\n  or asks how the lobby, \"Play\", ctx.modes, activeOnly panels, the shared-UI roles (sharedUi,\n  shouldDraw, the \"modes\" role), typed cross-module events (defineTopic/shape) or host-level shared\n  state work. Builds on idosgames-getting-started (scaffolding) and idosgames-module-contract (a single\n  module).\n---\n\n# Putting an app together: the base + modules\n\nEvery project is **the base + modules**. The base (`src/base/`, from the host scaffold) is sign-in and\nthe lobby; everything else is a module in `src/modules/<id>/`:\n\n- **systems** (`type: feature`) — one per player-facing module of the engine: store, premium (VIP),\n  character, inventory, lootboxes, boosts, leaderboard, rewards (daily), quests, collections, craft,\n  marketplace, deals, events, coop-events, season, friends, chat, invite, pvp, multiplayer, profile,\n  tutorials, workshop, ai, mailbox. Each registers its screen as a **feature** → a tab of the lobby.\n  The base installs only six of them into every new project (`inBase: true`: profile, inventory,\n  invite, friends, quests, mailbox); every other system is installed only when the app needs it — a game\n  brings the ones it lists in `uses`, and you install any other one as soon as the task needs what\n  it `provides` (InstallModule / `get_module`) — the user does not have to name the module; reuse it\n  instead of writing that feature again. Never install one the task does not need.\n- **games** (`type: template`) — board-game, idle-rpg, voxelcraft, mini-game, or the game's own. Each\n  registers a **route** → a \"Play\" button in the lobby. A game that plugs into a system lists it in\n  `uses` in its module.meta.json (`ctx.multiplayer` → `\"multiplayer\"`, `ctx.content` → `\"workshop\"`;\n  `npm run check` enforces those two) — install those together with the game.\n\n## Register modules\n\n```ts\n// src/modules.ts — the platform regenerates it; by hand it is imports + the array\nexport const modules: Module[] = [\n  storeModule, // systems: lobby tabs\n  characterModule,\n  leaderboardModule,\n  boardGameModule, // games: \"Play\"\n  idleRpgModule,\n];\n```\n\n`src/main.tsx` mounts `[baseModule, ...modules]`. After sign-in the player lands in the game inside\nthe lobby (`src/app.config.ts` `start`: `\"game\"` — the default, `\"lobby\"`, or a game's mode id). \"Play\" switches the host to the\ngame's mode: only the active mode's scene is mounted and ticking; the rest are suspended (their RAF\nstops). This is why two different engines (Three + Phaser) live in one project — they never render\nat the same time. The game sits INSIDE the lobby: over it the base keeps the balances on top and the\ntabs at the bottom (host panel slots `header`/`footer` — the game is laid out between them, it does\nnothing for it); \"Play\" is the game, any other tab opens that screen. A game with its own bar to the\nsystems hides it when `ctx.sharedUi.shouldDraw(\"menu\")` is false (idle-rpg does).\n\n- A system tab is hidden while the title has nothing for it (no store offers, no heroes…): the module\n  registers with `available: false` and calls `ctx.features.setAvailable(id, ok, reason)`.\n- `ctx.modes.list()` / `current()` / `subscribe()` — every mode (id, label, icon, module, module type);\n  the lobby builds \"Play\" from the `game` ones. Switch with `ctx.navigate(id)` (`\"lobby\"` is the base).\n- Open another system's screen by id: `ctx.features.open(\"store\")` — from a game too (the host shows\n  it in a window while the lobby is off screen). Never import another module.\n\n## Share progress across modes (the merge)\n\nShared state lives in the ONE SDK client, not in any module. Every module reads/writes the same\n`client` (currency, inventory, characters), so progress carries across modes automatically:\n\n- Gold earned idle in the RPG mode is spendable in the Board mode and in the shop — same\n  `client.currency`, same cache. No cross-module plumbing needed for durable state.\n- For live cross-module signals (not durable state), use `ctx.events` with a **typed topic** — see\n  \"Signals between modules\" below.\n- Modules never import each other's files or `src/base/`. The client and the event bus are the seams\n  between them — which is what keeps a module reusable in another game. Code several of THIS game's\n  modules need (shared types, the game's UI kit, helpers) goes to `src/shared/`, which never imports a\n  module (see idosgames-project-structure).\n\n## Shared chrome: roles, and the base takes them\n\nBalances, the crypto wallet, the status line, \"Log out\" / player ID, the menu of features and the\nswitch between modes are **shared-UI roles** (`currency-bar | wallet | status | account | menu |\nmodes`). A module that draws one for EVERY mode declares it statically on the module object —\nthe base does:\n\n```ts\ndefineModule({\n  id: \"base\",\n  meta: { name: \"Base\", type: \"app\", engine: \"dom\" },\n  sharedUi: {\n    provides: [\"currency-bar\", \"wallet\", \"account\", \"menu\", \"modes\"],\n  },\n  setup(ctx) {\n    /* the lobby: balances, wallet, profile, tabs, \"Play\" */\n  },\n});\n```\n\nThe host resolves role owners from these declarations BEFORE any `setup()` — the first provider wins,\na conflict is warned — and every module asks `ctx.sharedUi.shouldDraw(role)`. A game draws its own\ncopy only while nobody took the role. So:\n\n- Next to the base a game hides its own balances and wallet by itself. Do NOT edit a catalog game to\n  remove them: it does that itself, and an edit marks it customized (no more catalog updates).\n- `status` — the line of a game's own actions (\"Rolling…\") — stays with each game.\n- A game installed without a base stays complete — nobody owns a role, it draws everything, and the\n  host draws its own nav of routes, ☰ and \"Log out\" (those are the host-drawn roles `modes`, `menu`,\n  `account`).\n- A new module that needs, say, the balance bar but does not draw it declares\n  `sharedUi: { requires: [\"currency-bar\"] }`; with no provider installed the host warns.\n\n**Layout is the host's job.** A game's overlay fills the screen under the base's small button; a\nscene's own DOM HUD can keep clear of host chrome with the CSS variables on the host root —\n`top: calc(var(--idos-safe-top, 0px) + 8px)`, `bottom: calc(var(--idos-safe-bottom, 0px) + 8px)`\n(voxelcraft's hotbar does this). Both are 0 when nothing is pinned. `hud`-slot panels are wrapped in\n`display: contents`, so a panel can stretch (`flex: 1`) and decide its own pointer-events: let clicks\nthrough to the game, take them only on controls.\n\n## Signals between modules (typed topics)\n\nA topic is a token passed by value: the name carries the major version, the payload is a flat JSON\nshape — one artifact that gives the TS type, the runtime check and the catalog entry.\n\n```ts\n// idle-rpg/events.ts — the EMITTER owns the topic\nimport { defineTopic, shape } from \"@idosgames/module-sdk\";\nexport const characterUpgraded = defineTopic(\n  \"idle-rpg:character-upgraded@1\",\n  shape({ characterId: \"string\", level: \"number\" }),\n);\n// setup(): hand the panel a callback that does\n//   ctx.events.emit(characterUpgraded, { characterId, level });\n```\n\n```ts\n// board-game/events.ts — the LISTENER keeps its OWN copy (copied from the catalog), never an import.\n// Optional: idle-rpg may not be installed. Only the fields this module reads.\nexport const idleCharacterUpgraded = defineTopic(\n  \"idle-rpg:character-upgraded@1\",\n  shape({ level: \"number\" }),\n);\n// setup() — NOT a panel effect (activeOnly panels unmount with their mode and miss events):\nctx.events.on(idleCharacterUpgraded, ({ level }) =>\n  news.push(`Idle RPG hero reached Lv ${level}`),\n);\n```\n\nDeclare both sides in `module.meta.json` — the catalog and the agent read this, not your code:\n\n```json\n\"events\": {\n  \"emits\": [{ \"topic\": \"idle-rpg:character-upgraded@1\", \"when\": \"a hero levelled up\",\n              \"payload\": { \"characterId\": \"string\", \"level\": \"number\" } }],\n  \"listens\": [{ \"topic\": \"idle-rpg:character-upgraded@1\", \"why\": \"news chip in the board HUD\" }]\n}\n```\n\nRules:\n\n- Name `<your-module-id>:<event>@<major>`. Emit only into your own namespace — the host drops an\n  emit into another module's namespace with `console.error`; `host:` is reserved. The only topics\n  you import are `hostTopics` from `@idosgames/module-sdk` (`hostTopics.modeChanged` =\n  `host:mode-changed@1 { from?: string; to: string }`, sent on every mode switch).\n- Shape leaves: `\"string\" | \"number\" | \"boolean\"`, with `\"[]\"` and/or a trailing `\"?\"`; nested\n  objects allowed. Payloads are plain JSON — no functions, class instances or engine objects.\n- An incompatible change is a NEW topic `@2` (send both during the transition); within a major, only\n  add fields. A listener whose fields are missing is skipped (one `console.warn`), never crashed.\n- An event is a signal, not state, and is never replayed — \"what exists now\" is SDK data or\n  `ctx.sharedUi`. No request/response between modules: if you need an answer, it is data.\n- A throwing handler does not stop other listeners or reach the emitter; the host removes every\n  subscription on logout, so re-login does not double handlers.\n- In the AI editor's preview, `gameState` returns the last 50 events, who listens to what, and hints\n  like \"board-game listens to x@1 but only x@2 is emitted\".\n- A game's OWN modules may keep shared topic tokens in `src/shared/events/` and import them on both\n  sides — still declare them in each `module.meta.json`.\n\n## Reference app\n\nThe base + the systems + `board-game` + `idle-rpg`:\n\n- sign-in → the lobby: balances, wallet and profile on top, the systems as tabs, \"Play\" with two games;\n- the game inside the lobby → one engine scene mounted at a time; the lobby's tabs stay around it;\n- the games hide their own balances and wallet (the lobby has them); their status lines stay theirs;\n- currency changed in one mode is immediately visible in the others and in the lobby; levelling a hero\n  in Idle RPG shows a news chip on the board (`idle-rpg:character-upgraded@1`).\n\nTo pull the modules, use `get_module {id}` for each (MCP) and register them as above. Adjust layouts\nper module (a full-bleed overlay UI vs a docked side panel) — see each module's RootPanel.\n",
   "references": []
 }

package/registry/skills/idosgames-getting-started.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-getting-started",
   "description": "Start a new game or app on the iDosGames composable-module architecture: scaffold the base (sign-in + the lobby on the host shell) and plug in modules — the systems (shop, heroes, leaderboards…) and the games (board-game, idle-rpg, voxelcraft, mini-game, …). Use this whenever a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and idosgames-compose-modules (merging several) and idosgames-project-structure (where code goes as the project grows). If pulling modules over MCP, use the @idosgames/mcp tools get_host_scaffold / get_module / get_manifest.",
-  "content": "---\nname: idosgames-getting-started\ndescription: >-\n  Start a new game or app on the iDosGames composable-module architecture: scaffold the base (sign-in\n  + the lobby on the host shell) and plug in modules — the systems (shop, heroes, leaderboards…) and\n  the games (board-game, idle-rpg, voxelcraft, mini-game, …). Use this whenever\n  a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a\n  project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or\n  src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and\n  idosgames-compose-modules (merging several) and idosgames-project-structure (where code goes as\n  the project grows). If pulling modules over MCP, use the @idosgames/mcp\n  tools get_host_scaffold / get_module / get_manifest.\n---\n\n# Getting started (iDosGames composable modules)\n\nAn iDosGames project is **one host shell + N feature modules**. The host owns everything that exists\nonce — the SDK client, login, the React root, the screen, a module registry, and a Mode Router that\nswitches between modules. A module is a library (a game or app) that plugs into the host; it never\ncreates the client, logs in, or owns the root.\n\n## Runtime packages (npm)\n\n- `@idosgames/core` — the SDK client (`createIDosGamesClient`): auth, currency, store, characters,\n  blockchain, ~28 services. See the per-service skills (currency-system, store-system, …). Its\n  **central cache** `client.cache` decides every read: the login brings the title config (by version)\n  and the player's state (by each container's `Rev`) in ONE call; afterwards read state through\n  `client.cache.ensureState([...containers])`, definitions through `getDefinitions()` (served from the\n  config cache), server views through their service (cached by policy) — never re-fetch on start-up.\n  The server views the game reads ride on that same login call (`ClientState.Views`): the client\n  option `loginViews` — `\"auto\"` (default, what the game read last time), `\"all\"`, `\"none\"` or a list.\n- `@idosgames/module-sdk` — the module contract types (`Module`, `ModuleContext`, `EngineScene`,\n  `UiPanel`). See idosgames-module-contract.\n- `@idosgames/react` — shared React glue (`IDosGamesProvider`, `useIDosGamesClient`, `useUserState`,\n  `StatusProvider`, `createControllerContext`).\n- `@idosgames/app-shell` — the host runtime (`mountHost`, the Mode Router, the module registry).\n- `@idosgames/wallet` — optional wallet bridge (EVM/Solana) for on-chain deposits/withdrawals.\n\nInstall the exact versions from `get_manifest` (MCP) or the registry `index.json` `runtimePackages`.\n\n## Project shape\n\n```\nIDOS.md                    # the project guide every agent reads first (short, evergreen)\nAGENTS.md, CLAUDE.md       # pointers to IDOS.md for external tools\ndocs/feature-history/      # one file per game system + README.md index (the project's memory)\nindex.html                 # mounts #app\nsrc/main.tsx               # creates ONE client and calls mountHost({container, client, modules})\nsrc/modules.ts             # the registry: export const modules: Module[] = [ … ] — imports + array only\nsrc/modules/{id}/          # each module's source + its module.meta.json (from get_module)\n```\n\nPlatform-created projects also carry `idos.modules.lock.json` (which modules came from the catalog,\nwith file fingerprints) — it is platform-owned; don't edit it. Where new code goes as the game grows,\nand how the project documents itself, is **idosgames-project-structure**.\n\n`src/main.tsx` (host-owned) is the only place that creates the client — but it does **not** sign in.\n`mountHost` owns sign-in: it replays a previous session (`autoLogin`) and renders the login screen\nwhen there is nothing to replay. Calling a `login*` method here skips that screen for good, taking\n\"switch account\" and wallet sign-in with it:\n\n```ts\nconst client = createIDosGamesClient({ titleID, buildKey, throttleMs: 0 });\n// Do NOT log in here — the host does it.\nmountHost({\n  container: app,\n  client,\n  modules, // from ./modules\n  renderLogin, // optional: your own screen; omitted = a plain guest-only default\n});\n```\n\nWhether a returning player is signed back in silently is the login screen's business, not the\nhost's: it calls `client.auth.setRememberSession(remember)` before a `login*` method. See the\nauthentication skill.\n\n`src/modules.ts` registers what the project composes:\n\n```ts\nimport type { Module } from \"@idosgames/module-sdk\";\nimport { boardGameModule } from \"./modules/board-game\";\nexport const modules: Module[] = [boardGameModule];\n```\n\n## Steps to scaffold\n\n1. **Base** — write the host scaffold to the project root (`get_host_scaffold`, or copy\n   `templates/base`): sign-in and the lobby in `src/base/`, `src/app.config.ts` (start in the lobby or\n   a game), an empty `src/modules.ts` → an empty lobby.\n2. **Bind the Title** — open `src/idos.title.ts` and set `IDOS_TITLE_ID` to the game's canonical\n   Title id (and `IDOS_BUILD_KEY` if the title enforces one). This file is the project's single\n   centralized identity — it is the highest-priority source and the only channel a packaged mobile\n   build, iframe embed, or shared link has. On platform-created projects the platform generates it;\n   on a manually scaffolded project **you fill it yourself**. Do NOT bind the title via `.env.local`\n   (`VITE_IDOS_TITLE_ID`) — that is a local-dev fallback for the raw template only, and it does not\n   travel with the code.\n3. **Pick modules** — `list_modules` / `search`, then `get_module {id}` for each. Write its files\n   into `src/modules/{id}/`. The base's systems are the modules with `inBase: true` (profile,\n   inventory, invite, friends, quests, mailbox); add the game(s) with the modules each game `uses`, and any\n   other system (shop, VIP, leaderboards…) only when the app needs it.\n4. **Register** — for each module add `import { {camelCase(id)}Module } from \"./modules/{id}\"` and\n   push it into the `modules` array (e.g. `board-game` → `boardGameModule`). Then add the module to\n   the \"Installed modules\" block of `IDOS.md` (one line: ``- `board-game` (0.1.0) — src/modules/board-game/``)\n   — on platform projects the platform maintains that block itself.\n5. **Install deps** — the union of `runtimePackages` + each module's `dependencies`. Modules bring\n   their own engine (three, phaser); the host brings react/react-dom/app-shell.\n6. **Run** — sign-in → the lobby: the systems' screens are its tabs (a tab hides itself while the\n   title has nothing for it), every game gets a \"Play\" button, and a small button over a game returns\n   to the lobby. The lobby draws the balances and the wallet; games hide their own copies by\n   themselves (`sharedUi` roles).\n\nTo combine multiple genres into one game, see **idosgames-compose-modules**. To write or edit a\nmodule, see **idosgames-module-contract**.\n\n## Where state lives (decide this before writing the first save)\n\nThe project is client-side code in the player's browser. `localStorage`, module fields, and React\nstate are **not storage** — nothing there survives a device change, and nothing there is trusted.\n\n1. **A dedicated module owns it?** Use that module. Currencies, inventory, quests, characters,\n   leaderboards, store purchases each have a service that enforces the rules server-side.\n2. **Otherwise, per-player data → `client.userCustomData`** — buckets `Private`/`Public` are\n   client-writable (settings, cosmetics), `ReadOnly`/`Internal` are server-only. Anything a player\n   could cheat by editing goes in the server-only buckets. See **user-custom-data**.\n3. **Shared by all players → `client.titleCustomData`** (event state, global counters, server\n   thresholds, feature toggles). Read-only for clients. See **title-custom-data**.\n4. **Writing any of the server-only data, or any rule the player must not be able to fake** →\n   a CloudCode handler, called with `client.cloudCode.execute(...)`. See **cloud-code**.\n\n## Two MCP surfaces: game CODE vs. a Title's live DATA\n\nThe platform exposes **two independent MCP servers** — don't confuse them:\n\n- **`@idosgames/mcp`** (this one) serves the **CODE registry**. Use it to WRITE a game's source:\n  `get_host_scaffold`, `list_modules` / `search` / `get_module`, `get_manifest`, `list_skills` /\n  `get_skill`. Transport: stdio (`npx -y @idosgames/mcp`). Its registry is bundled offline; to use the\n  hosted copy set `IDOSGAMES_REGISTRY_URL=https://cloud.idosgames.com/drive/registry/latest` — a **base**\n  the loader appends `/index.json`, `/modules/{id}.json`, etc. to (the base itself is not fetchable on\n  R2; open `.../latest/index.json` to browse the catalog). Read-only, no auth. It never reads or changes\n  a live Title's data.\n- **The Title-configuration MCP** (a separate backend server) owns a **live Title's DATA**. Use it to\n  read/write the Title's `TitlePublicConfiguration` (`get_<field>` / `save_<field>`, or the whole\n  model) and to generate assets (`generate_image` / `generate_audio` / `generate_text` /\n  `generate_three_d` / `generate_video`). Transport: HTTP JSON-RPC at\n  `POST https://site.idosgames.com/api/v2/mcp`; every tool call takes a `title_id` argument.\n  Authorization is **OAuth 2.1** — there is no API key and nothing to paste. Connect it as a plain\n  HTTP MCP server with **no headers**: your client gets a `401`, discovers the authorization\n  server, registers itself, and opens a browser where the publisher picks which Titles and which\n  permissions to grant. The token lives in your client's own credential store, so committed config\n  holds only the URL:\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"idosgames-title\": {\n        \"type\": \"http\",\n        \"url\": \"https://site.idosgames.com/api/v2/mcp\"\n      }\n    }\n  }\n  ```\n\n  Permissions the publisher can grant: `config:read`, `config:write`, `cloudcode:write`,\n  `ai:generate`. A grant is scoped to the Titles ticked on the consent screen, and the publisher\n  can revoke it any time from **Connected apps** in the dashboard. If a call comes back\n  `SCOPE_NOT_ALLOWED` or `TITLE_NOT_ALLOWED`, the token is fine — that permission or that Title\n  simply was not granted; ask the publisher to re-authorize rather than retrying.\n\n  Configuring a **fresh (empty) Title** so a game can actually run against it (currencies → game\n  loop → bots) is its own checklist: see **idosgames-title-bootstrap**.\n\nRule of thumb: **game CODE → `@idosgames/mcp`; a Title's live config DATA and generated ASSETS → the\nbackend `v2/mcp` server.** Scaffolding a project and configuring/populating the Title it runs as are\ntwo different jobs on two different servers — connect the one that matches the task (or both).\n",
+  "content": "---\nname: idosgames-getting-started\ndescription: >-\n  Start a new game or app on the iDosGames composable-module architecture: scaffold the base (sign-in\n  + the lobby on the host shell) and plug in modules — the systems (shop, heroes, leaderboards…) and\n  the games (board-game, idle-rpg, voxelcraft, mini-game, …). Use this whenever\n  a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a\n  project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or\n  src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and\n  idosgames-compose-modules (merging several) and idosgames-project-structure (where code goes as\n  the project grows). If pulling modules over MCP, use the @idosgames/mcp\n  tools get_host_scaffold / get_module / get_manifest.\n---\n\n# Getting started (iDosGames composable modules)\n\nAn iDosGames project is **one host shell + N feature modules**. The host owns everything that exists\nonce — the SDK client, login, the React root, the screen, a module registry, and a Mode Router that\nswitches between modules. A module is a library (a game or app) that plugs into the host; it never\ncreates the client, logs in, or owns the root.\n\n## Runtime packages (npm)\n\n- `@idosgames/core` — the SDK client (`createIDosGamesClient`): auth, currency, store, characters,\n  blockchain, ~28 services. See the per-service skills (currency-system, store-system, …). Its\n  **central cache** `client.cache` decides every read: the login brings the title config (by version)\n  and the player's state (by each container's `Rev`) in ONE call; afterwards read state through\n  `client.cache.ensureState([...containers])`, definitions through `getDefinitions()` (served from the\n  config cache), server views through their service (cached by policy) — never re-fetch on start-up.\n  The server views the game reads ride on that same login call (`ClientState.Views`): the client\n  option `loginViews` — `\"auto\"` (default, what the game read last time), `\"all\"`, `\"none\"` or a list.\n- `@idosgames/module-sdk` — the module contract types (`Module`, `ModuleContext`, `EngineScene`,\n  `UiPanel`). See idosgames-module-contract.\n- `@idosgames/react` — shared React glue (`IDosGamesProvider`, `useIDosGamesClient`, `useUserState`,\n  `StatusProvider`, `createControllerContext`).\n- `@idosgames/app-shell` — the host runtime (`mountHost`, the Mode Router, the module registry).\n- `@idosgames/wallet` — optional wallet bridge (EVM/Solana) for on-chain deposits/withdrawals.\n\nInstall the exact versions from `get_manifest` (MCP) or the registry `index.json` `runtimePackages`.\n\n## Project shape\n\n```\nIDOS.md                    # the project guide every agent reads first (short, evergreen)\nAGENTS.md, CLAUDE.md       # pointers to IDOS.md for external tools\ndocs/feature-history/      # one file per game system + README.md index (the project's memory)\nindex.html                 # mounts #app\nsrc/main.tsx               # creates ONE client and calls mountHost({container, client, modules})\nsrc/modules.ts             # the registry: export const modules: Module[] = [ … ] — imports + array only\nsrc/modules/{id}/          # each module's source + its module.meta.json (from get_module)\n```\n\nPlatform-created projects also carry `idos.modules.lock.json` (which modules came from the catalog,\nwith file fingerprints) — it is platform-owned; don't edit it. Where new code goes as the game grows,\nand how the project documents itself, is **idosgames-project-structure**.\n\n`src/main.tsx` (host-owned) is the only place that creates the client — but it does **not** sign in.\n`mountHost` owns sign-in: it replays a previous session (`autoLogin`) and renders the login screen\nwhen there is nothing to replay. Calling a `login*` method here skips that screen for good, taking\n\"switch account\" and wallet sign-in with it:\n\n```ts\nconst client = createIDosGamesClient({ titleID, buildKey, throttleMs: 0 });\n// Do NOT log in here — the host does it.\nmountHost({\n  container: app,\n  client,\n  modules, // from ./modules\n  renderLogin, // optional: your own screen; omitted = a plain guest-only default\n});\n```\n\nWhether a returning player is signed back in silently is the login screen's business, not the\nhost's: it calls `client.auth.setRememberSession(remember)` before a `login*` method. See the\nauthentication skill.\n\n`src/modules.ts` registers what the project composes:\n\n```ts\nimport type { Module } from \"@idosgames/module-sdk\";\nimport { boardGameModule } from \"./modules/board-game\";\nexport const modules: Module[] = [boardGameModule];\n```\n\n## Steps to scaffold\n\n1. **Base** — write the host scaffold to the project root (`get_host_scaffold`, or copy\n   `templates/base`): sign-in and the lobby in `src/base/`, `src/app.config.ts` (start in the lobby or\n   a game), an empty `src/modules.ts` → an empty lobby.\n2. **Bind the Title** — open `src/idos.title.ts` and set `IDOS_TITLE_ID` to the game's canonical\n   Title id (and `IDOS_BUILD_KEY` if the title enforces one). This file is the project's single\n   centralized identity — it is the highest-priority source and the only channel a packaged mobile\n   build, iframe embed, or shared link has. On platform-created projects the platform generates it;\n   on a manually scaffolded project **you fill it yourself**. Do NOT bind the title via `.env.local`\n   (`VITE_IDOS_TITLE_ID`) — that is a local-dev fallback for the raw template only, and it does not\n   travel with the code.\n3. **Pick modules** — `list_modules` / `search`, then `get_module {id}` for each. Write its files\n   into `src/modules/{id}/`. The base's systems are the modules with `inBase: true` (profile,\n   inventory, invite, friends, quests, mailbox); add the game(s) with the modules each game `uses`, and any\n   other system (shop, VIP, leaderboards…) only when the app needs it.\n4. **Register** — for each module add `import { {camelCase(id)}Module } from \"./modules/{id}\"` and\n   push it into the `modules` array (e.g. `board-game` → `boardGameModule`). Then add the module to\n   the \"Installed modules\" block of `IDOS.md` (one line: ``- `board-game` (0.1.0) — src/modules/board-game/``)\n   — on platform projects the platform maintains that block itself.\n5. **Install deps** — the union of `runtimePackages` + each module's `dependencies`. Modules bring\n   their own engine (three, phaser); the host brings react/react-dom/app-shell.\n6. **Run** — sign-in → the game inside the lobby: the lobby's balances on top, its tabs at the\n   bottom — \"Play\" is the game, the systems' screens are the other tabs (a tab hides itself while the\n   title has nothing for it). The lobby draws the balances and the wallet; games hide their own copies by\n   themselves (`sharedUi` roles).\n\nTo combine multiple genres into one game, see **idosgames-compose-modules**. To write or edit a\nmodule, see **idosgames-module-contract**.\n\n## Where state lives (decide this before writing the first save)\n\nThe project is client-side code in the player's browser. `localStorage`, module fields, and React\nstate are **not storage** — nothing there survives a device change, and nothing there is trusted.\n\n1. **A dedicated module owns it?** Use that module. Currencies, inventory, quests, characters,\n   leaderboards, store purchases each have a service that enforces the rules server-side.\n2. **Otherwise, per-player data → `client.userCustomData`** — buckets `Private`/`Public` are\n   client-writable (settings, cosmetics), `ReadOnly`/`Internal` are server-only. Anything a player\n   could cheat by editing goes in the server-only buckets. See **user-custom-data**.\n3. **Shared by all players → `client.titleCustomData`** (event state, global counters, server\n   thresholds, feature toggles). Read-only for clients. See **title-custom-data**.\n4. **Writing any of the server-only data, or any rule the player must not be able to fake** →\n   a CloudCode handler, called with `client.cloudCode.execute(...)`. See **cloud-code**.\n\n## Two MCP surfaces: game CODE vs. a Title's live DATA\n\nThe platform exposes **two independent MCP servers** — don't confuse them:\n\n- **`@idosgames/mcp`** (this one) serves the **CODE registry**. Use it to WRITE a game's source:\n  `get_host_scaffold`, `list_modules` / `search` / `get_module`, `get_manifest`, `list_skills` /\n  `get_skill`. Transport: stdio (`npx -y @idosgames/mcp`). Its registry is bundled offline; to use the\n  hosted copy set `IDOSGAMES_REGISTRY_URL=https://cloud.idosgames.com/drive/registry/latest` — a **base**\n  the loader appends `/index.json`, `/modules/{id}.json`, etc. to (the base itself is not fetchable on\n  R2; open `.../latest/index.json` to browse the catalog). Read-only, no auth. It never reads or changes\n  a live Title's data.\n- **The Title-configuration MCP** (a separate backend server) owns a **live Title's DATA**. Use it to\n  read/write the Title's `TitlePublicConfiguration` (`get_<field>` / `save_<field>`, or the whole\n  model) and to generate assets (`generate_image` / `generate_audio` / `generate_text` /\n  `generate_three_d` / `generate_video`). Transport: HTTP JSON-RPC at\n  `POST https://site.idosgames.com/api/v2/mcp`; every tool call takes a `title_id` argument.\n  Authorization is **OAuth 2.1** — there is no API key and nothing to paste. Connect it as a plain\n  HTTP MCP server with **no headers**: your client gets a `401`, discovers the authorization\n  server, registers itself, and opens a browser where the publisher picks which Titles and which\n  permissions to grant. The token lives in your client's own credential store, so committed config\n  holds only the URL:\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"idosgames-title\": {\n        \"type\": \"http\",\n        \"url\": \"https://site.idosgames.com/api/v2/mcp\"\n      }\n    }\n  }\n  ```\n\n  Permissions the publisher can grant: `config:read`, `config:write`, `cloudcode:write`,\n  `ai:generate`. A grant is scoped to the Titles ticked on the consent screen, and the publisher\n  can revoke it any time from **Connected apps** in the dashboard. If a call comes back\n  `SCOPE_NOT_ALLOWED` or `TITLE_NOT_ALLOWED`, the token is fine — that permission or that Title\n  simply was not granted; ask the publisher to re-authorize rather than retrying.\n\n  Configuring a **fresh (empty) Title** so a game can actually run against it (currencies → game\n  loop → bots) is its own checklist: see **idosgames-title-bootstrap**.\n\nRule of thumb: **game CODE → `@idosgames/mcp`; a Title's live config DATA and generated ASSETS → the\nbackend `v2/mcp` server.** Scaffolding a project and configuring/populating the Title it runs as are\ntwo different jobs on two different servers — connect the one that matches the task (or both).\n",
   "references": []
 }

package/registry/skills/idosgames-module-contract.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-module-contract",
   "description": "Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk: the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route registration, and the shared controller-box bridge between an imperative scene and React panels. Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg, voxelcraft, mini-game, store, character, workshop…), or asks about defineModule, registerScene/registerPanel/registerRoute, ctx.features (register / open / setBadge / setAvailable), ctx.modes, activate/suspend, SceneMountContext, sharedUi / ctx.sharedUi.shouldDraw, ctx.events / defineTopic, ctx.content / ContentTypeHandler (letting the Workshop publish and open the game's content), ctx.multiplayer / registerGame (playing online through the lobby's rooms system), ctx.navigate, the --idos-safe-* layout variables, or the {camelCase(id)}Module export convention.",
-  "content": "---\nname: idosgames-module-contract\ndescription: >-\n  Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk:\n  the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route\n  registration, and the shared controller-box bridge between an imperative scene and React panels.\n  Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg,\n  voxelcraft, mini-game, store, character, workshop…), or asks about defineModule,\n  registerScene/registerPanel/registerRoute, ctx.features (register / open / setBadge / setAvailable),\n  ctx.modes,\n  activate/suspend, SceneMountContext, sharedUi / ctx.sharedUi.shouldDraw, ctx.events / defineTopic,\n  ctx.content / ContentTypeHandler (letting the Workshop publish and open the game's content),\n  ctx.multiplayer / registerGame (playing online through the lobby's rooms system),\n  ctx.navigate, the --idos-safe-* layout variables, or the {camelCase(id)}Module export convention.\n---\n\n# The module contract (@idosgames/module-sdk)\n\nA module is a manifest the host installs once. It exports `{camelCase(id)}Module` from its\n`index.ts` (e.g. `board-game` → `boardGameModule`, `idle-rpg` → `idleRpgModule`) — the host seeder\nderives the import name from the id, so this convention is required.\n\n```ts\nimport { defineModule } from \"@idosgames/module-sdk\";\n\nexport const boardGameModule = defineModule({\n  id: \"board-game\",\n  meta: { name: \"Board Game\", type: \"game\", genre: \"board\", engine: \"three\" }, // engine: three|phaser|dom\n  setup(ctx) {\n    // ctx.client (shared, authed) · ctx.events (typed cross-module bus) · ctx.sharedUi · ctx.surface\n    ctx.registerScene(createScene(box)); // rendered engine scene (optional)\n    ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: RootPanel }); // React UI (optional)\n    ctx.registerRoute({ id: \"board-game\", label: \"Board\", icon: \"🎲\" }); // a mode → the lobby's \"Play\"\n  },\n});\n```\n\nTwo kinds of module plug into the base (`src/base/` — sign-in and the lobby):\n\n- a **game** (`meta.type: \"game\"`) registers a route: the lobby shows a \"Play\" button for it, and\n  over it the base draws only a small \"To the lobby\" button;\n- a **system** (`meta.type: \"app\"`) registers a feature — its screen becomes a lobby tab:\n  `ctx.features.register({ id, label, icon, group, order, primary?, available?, Screen })`. A tab\n  that depends on title data registers with `available: false` and calls\n  `ctx.features.setAvailable(id, ok, reason)` once it knows (details: **idosgames-ui-kit**).\n\n`ctx.modes.list()` / `current()` / `subscribe()` — every mode (id, label, icon, module, module type),\nfilled once all modules are installed (read it at render time, not inside `setup()`).\n`ctx.navigate(id)` switches (`\"lobby\"` is the base); called inside `setup()` it picks the mode the app\nstarts in. `ctx.features.open(id, args)` from a game (the lobby not on screen) switches to the lobby\nand opens that tab there.\n\n`ctx.multiplayer` — a game that plays online registers itself (`registerGame({ mode, topology,\nchatMode, maxPlayers, joinInProgress, settings, start(room) })`) and takes the room the lobby's\nrooms system hands it on \"Play\"; it never creates or joins rooms (skill **multiplayer-realtime**).\n\nOptional static field: `sharedUi: { provides?: SharedUiRole[]; requires?: SharedUiRole[] }` — see\n\"Shared chrome\" below.\n\n`meta.type` is `game | app | ai-app`; `meta.engine` is `three | phaser | dom` (`dom` = no renderer —\na pure React/DOM app module). `setup` is called ONCE with `ctx: ModuleContext`.\n\n## EngineScene (the rendered part)\n\nA scene mounts into a bare `HTMLElement` (framework-free — this is why a vanilla Three game like\nvoxelcraft fits). The host's Mode Router drives it; only the active mode runs.\n\n```ts\nconst scene: EngineScene = {\n  surface: \"fullbleed-canvas\",\n  mount(ctx: SceneMountContext) {\n    controller = new Controller(ctx.host);\n    box.set(controller);\n  },\n  activate() {\n    controller?.setRunning(true);\n  }, // became the active mode → resume RAF\n  suspend() {\n    controller?.setRunning(false);\n  }, // hidden → stop RAF (invariant: only active ticks)\n  destroy() {\n    controller?.destroy();\n  }, // permanent teardown\n};\n```\n\n`mount` takes a context object (not a bare element) so it can grow — e.g. a host-shared renderer in\nthe composition era — without breaking the contract. A scene MUST stop its RAF on `suspend`.\n\n### Loading — never a still screen\n\nA scene's FIRST start goes behind the app's loading screen by itself: the host shows it (themed,\n\"Loading «<mode>»…\"), lets it paint, THEN calls `mount` — so heavy synchronous work in `mount`\n(generating terrain, building meshes) never looks like a frozen app. The screen goes away after the\nfirst frame, or — when the scene has more to do — when its optional `ready(): Promise<void>` resolves\n(voxelcraft: the last played world restored from storage). Never draw your own start-up spinner.\n\nLong work AFTER the start goes through `ctx.loading` — the same screen:\n\n- `await ctx.loading.track(fetchWorld(), \"Loading the world…\")` — async work;\n- `await ctx.loading.run(() => buildWorld(seed), \"Building the world…\")` — work that BLOCKS the page:\n  the screen is shown and painted first (calling heavy code right after `begin()` freezes the page\n  before the screen appears);\n- `const task = ctx.loading.begin(\"…\"); task.progress(0.4, \"Textures…\"); task.done();` — with progress.\n\n### Notifications — `ctx.notifications`\n\nThe app's one system of toasts and alert windows (the UI kit draws them, themed): never draw a banner\nof your own. `ctx.notifications.toast({ level, title, message, icon, image, source, key, actions })`\n— `level`: `info | success | warning | error | reward`; `source` defaults to the module's id (the\ntoast shows that screen's name and a tap opens it). `await ctx.notifications.alert({ level, title,\nmessage, actions: [{ id: \"go\", label: \"Open\", primary: true, openFeature: \"season\" }, { label: \"Later\" }] })`\nresolves with the pressed action's id (`null` — closed). React screens: `useNotify()` from the kit.\n\nA module that registers a scene MUST also publish its debug surface — `ctx.exposeToAgent({ state,\nactions, describeActions })` — and must NOT gate controls on Pointer Lock (unavailable in the\npreview's cross-origin iframe). Nothing inside a `<canvas>` is observable from the DOM, so without\nthe surface neither the AI Coder nor a human reviewer can tell what the game is doing. See the\n`idosgames-agent-debug-surface` skill.\n\n### `capture()` — the frame for \"Take a shot and share\"\n\nidosgames.com has a **Shot** button under the game: it asks the game for one frame, puts the\nplatform's branding and a QR code on it and offers to post it. A scene answers through the optional\n`capture?(): Promise<Blob | null>`. The host (`@idosgames/app-shell`) wires the request itself —\na module only has to return a picture of its active scene.\n\n**Implement it in any scene that renders to a canvas.** Without it the host falls back to reading\nthe `<canvas>` from outside, and for WebGL that is a trap: a renderer created WITHOUT\n`preserveDrawingBuffer` (the default, and the right default — the flag costs memory and a copy every\nframe) has already cleared its buffer by the time anyone reads it, so `toBlob()` returns a **fully\nblack** image and reports nothing. The host rejects single-colour frames, so the player gets the\ngame's cover instead of their moment.\n\nRender and read in the SAME tick:\n\n```ts\n// three.js\ncapture() {\n  return new Promise((resolve) => {\n    renderer.render(scene, camera);          // draw now…\n    renderer.domElement.toBlob(resolve, \"image/png\"); // …and read before the buffer is cleared\n  });\n},\n\n// Phaser — use its own snapshot, it handles the timing\ncapture() {\n  return new Promise((resolve) => {\n    setTimeout(() => resolve(null), 1500); // no frame came (context lost) → answer \"no\", don't hang\n    game.loop.wake();                       // a sleeping loop never draws again → snapshot never fires\n    game.renderer.snapshot((image) => {\n      if (!(image instanceof HTMLImageElement)) return resolve(null);\n      const c = document.createElement(\"canvas\");\n      c.width = image.naturalWidth || image.width;\n      c.height = image.naturalHeight || image.height;\n      c.getContext(\"2d\")?.drawImage(image, 0, 0);\n      c.toBlob(resolve, \"image/png\");\n    });\n  });\n},\n```\n\nAlways answer — with a Blob or `null`. A `capture()` that never settles makes the site wait out its\ntimeout before it falls back, and the player stares at a spinner.\n\nReturn `null` when there is nothing worth showing (loading, no scene yet) — the site then uses the\ncover. Only the scene is captured, not the React panels over it: a shot for a feed reads better\nwithout the HUD. DOM-only modules (no canvas) simply omit `capture`. Working references:\n`modules/board-game` and `modules/voxelcraft` (three), `modules/idle-rpg` (Phaser).\n\n## UiPanel (the React part)\n\nPanels are React components the host renders inside its provider stack (client + status already\nprovided). Use `@idosgames/react` hooks (`useIDosGamesClient`, `useUserState`) — do NOT re-create\nproviders.\n\n- `slot`: `hud | sidebar | overlay | modal`.\n- `activeOnly` (default true): show only while this module's mode is active. Set `false` for shared\n  chrome that stays across every mode (e.g. a persistent HUD).\n- `overlay`/`sidebar` layers sit between the shared HUD and the nav (the host measures both), so a\n  panel positioned `absolute` inside its layer never ends up under them. Things drawn outside the\n  layers use `var(--idos-safe-top, 0px)` / `var(--idos-safe-bottom, 0px)`.\n- A `hud` panel's wrapper is `display: contents`: the panel is a direct flex child of the HUD row\n  (can `flex: 1`) and must set `pointer-events: auto` only on its controls.\n\n## Shared chrome (`sharedUi`)\n\nRoles: `currency-bar` (virtual-currency balances), `wallet` (crypto wallet entry — `LazyWalletPanel`),\n`status` (the `useStatus()` line), `account` (Log out + player ID), `menu` (the menu of features),\n`modes` (the switch between modes). The base takes `currency-bar`, `wallet`, `account`, `menu` and\n`modes` — its lobby draws them; `status` stays with each game. A module that draws one for every\nmode declares `sharedUi: { provides: [...] }` on the module object — statically, so the host resolves\nowners before any `setup()` and the answer never depends on module order.\n\n**Rule for templates: yield every role you draw yourself.** Read it once in `setup()` and close over\nthe answer (it is fixed for the session):\n\n```ts\nsetup(ctx) {\n  const chrome = {\n    wallet: ctx.sharedUi.shouldDraw(\"wallet\"),\n    balances: ctx.sharedUi.shouldDraw(\"currency-bar\"),\n    status: ctx.sharedUi.shouldDraw(\"status\"),\n  };\n  ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: makeRootPanel(box, chrome) });\n}\n```\n\nHide only the SHARED pieces — genre UI (the board's stage/tile/cycle chips) always stays. Never\nwrap your UI in your own `<StatusProvider>`: the host provides ONE, and a nested one would swallow\nyour messages so the shared status line never sees them. A module that needs a role but does not\ndraw it declares `sharedUi: { requires: [\"currency-bar\"] }`. `ctx.sharedUi.ownerOf(role)` names the\nprovider (or `null`). A full-screen mode (its own bottom tab bar) that shows the player ID and\n\"Log out\" in its own header declares `sharedUi: { drawsOwn: [\"account\"] }` and draws them only while\n`shouldDraw(\"account\")`: the host then hides its floating bottom-left copy while that mode is on\nscreen (it would cover the tab bar) and keeps it in the other modes. `drawsOwn` takes no role —\nwith the base installed the lobby draws the account and the mode hides its copy.\n\n## Events (`ctx.events`)\n\nTyped topic tokens — `defineTopic(\"<your-id>:<event>@1\", shape({ … }))` from\n`@idosgames/module-sdk`; emit only your own namespace; to listen to another module, copy its topic\nand payload descriptor from the catalog into your own `defineTopic` (never import it); declare both\nin `module.meta.json` (`events.emits` / `events.listens`). **Subscribe in `setup()`**, not in a panel\neffect — `activeOnly` panels unmount with their mode and miss events; store what arrives in a small\nstore the panel reads. Full rules and examples: **idosgames-compose-modules** (\"Signals between\nmodules\"). The string overloads (`emit(\"x\", …)`) are deprecated.\n\n## Content types (`ctx.content`) and switching modes (`ctx.navigate`)\n\nA game whose players make things (worlds, levels, skins) registers a **content type handler** so the\nshared Workshop module can publish and open them — the Workshop never imports the game:\n\n```ts\nsetup(ctx) {\n  ctx.content.registerType({\n    type: \"voxelcraft.world\",   // = a key of Workshop.ContentTypes in the title config\n    label: \"VoxelCraft world\",\n    icon: \"⛏️\",\n    modeId: \"voxelcraft\",        // route to switch to after open()\n    async listLocal() { return saves.map((s) => ({ id: s.id, name: s.name, updatedAt: s.at })); },\n    async capture(localId) {     // roles/MIME types must fit the title's content type config\n      return { files: [{ role: \"main\", contentType: \"application/json\", data: json }],\n               thumbnail: { contentType: \"image/webp\", data: webp }, suggestedTitle: name };\n    },\n    async open(content) { importSave(content.files[0].data); },\n  });\n}\n```\n\nHandlers registered in `setup()` are removed with the module; `registerType` returns an unregister\nfunction for anything dynamic. `ctx.navigate(modeId)` switches the host to another module's route\n(the Workshop uses it to jump into the game after `open`); an unknown id is ignored. Details:\n**workshop-system**.\n\n## Bridging scene ↔ panel\n\nThe scene creates its controller at `mount` (needs the canvas), but panels render before that. Share\nit with a one-slot observable and read it with `useSyncExternalStore`:\n\n```ts\nexport function createControllerBox<T>() {\n  /* get/set/subscribe */\n}\n// panel: const controller = useSyncExternalStore(box.subscribe, box.get); if (!controller) return <Loading/>;\n```\n\nFor the module's controller React context use the shared factory instead of hand-writing it:\n\n```ts\nexport const [BoardControllerProvider, useBoardController] =\n  createControllerContext<BoardController>(\"BoardController\"); // from @idosgames/react\n```\n\n## Layout and boundaries\n\nA module is one folder, `src/modules/<id>/`. It imports only its own files, the game's shared code\nin `src/shared/` and npm packages — never another module's files or host files. Talk to other\nmodules through the shared `ctx.client` (durable state) and `ctx.events` (live signals, typed\ntopics `<module-id>:<event>@<major>` declared in `module.meta.json`). A module shipped in the catalog is fully self-contained — it never uses\n`src/shared/`, so it installs into any game; a game's own module may use it, and its shared code is\ncopied into it when it is published for other creators.\n\n```\nsrc/modules/<id>/\n  index.ts           export { <camelCaseId>Module } from \"./module\";\n  module.ts          defineModule({ … })\n  module.meta.json   manifest: type (template|feature), summary, provides, tags, version, author\n  components/  game/  data/  react/   — as needed\n```\n\nEvery module carries its own `module.meta.json` (the `ModuleManifest` shape), including a game's own\nmodules. The full standard — where a new feature goes, file size, documentation — is\n**idosgames-project-structure**.\n\n## Dependencies\n\nDeclare only the module's UNIQUE deps (e.g. `phaser` for idle-rpg, `three` for board/voxel) plus the\nshared baseline (react, @idosgames/*). The platform pins shared libs identically across modules; two\nmodules must not request different versions of one package (the build allowlist rejects it).\n\nStudy a real module via `get_module {id}` (MCP) before writing a new one.\n",
+  "content": "---\nname: idosgames-module-contract\ndescription: >-\n  Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk:\n  the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route\n  registration, and the shared controller-box bridge between an imperative scene and React panels.\n  Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg,\n  voxelcraft, mini-game, store, character, workshop…), or asks about defineModule,\n  registerScene/registerPanel/registerRoute, ctx.features (register / open / setBadge / setAvailable),\n  ctx.modes,\n  activate/suspend, SceneMountContext, sharedUi / ctx.sharedUi.shouldDraw, ctx.events / defineTopic,\n  ctx.content / ContentTypeHandler (letting the Workshop publish and open the game's content),\n  ctx.multiplayer / registerGame (playing online through the lobby's rooms system),\n  ctx.navigate, the --idos-safe-* layout variables, or the {camelCase(id)}Module export convention.\n---\n\n# The module contract (@idosgames/module-sdk)\n\nA module is a manifest the host installs once. It exports `{camelCase(id)}Module` from its\n`index.ts` (e.g. `board-game` → `boardGameModule`, `idle-rpg` → `idleRpgModule`) — the host seeder\nderives the import name from the id, so this convention is required.\n\n```ts\nimport { defineModule } from \"@idosgames/module-sdk\";\n\nexport const boardGameModule = defineModule({\n  id: \"board-game\",\n  meta: { name: \"Board Game\", type: \"game\", genre: \"board\", engine: \"three\" }, // engine: three|phaser|dom\n  setup(ctx) {\n    // ctx.client (shared, authed) · ctx.events (typed cross-module bus) · ctx.sharedUi · ctx.surface\n    ctx.registerScene(createScene(box)); // rendered engine scene (optional)\n    ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: RootPanel }); // React UI (optional)\n    ctx.registerRoute({ id: \"board-game\", label: \"Board\", icon: \"🎲\" }); // a mode → the lobby's \"Play\"\n  },\n});\n```\n\nTwo kinds of module plug into the base (`src/base/` — sign-in and the lobby):\n\n- a **game** (`meta.type: \"game\"`) registers a route: it is the lobby's \"Play\" tab — the base keeps\n  its balances and tabs around the game through the host's `header`/`footer` panel slots (the app's\n  frame: the canvas and every other slot are laid out between them, so a game needs nothing for it);\n- a **system** (`meta.type: \"app\"`) registers a feature — its screen becomes a lobby tab:\n  `ctx.features.register({ id, label, icon, group, order, primary?, available?, Screen })`. A tab\n  that depends on title data registers with `available: false` and calls\n  `ctx.features.setAvailable(id, ok, reason)` once it knows (details: **idosgames-ui-kit**).\n\n`ctx.modes.list()` / `current()` / `subscribe()` — every mode (id, label, icon, module, module type),\nfilled once all modules are installed (read it at render time, not inside `setup()`).\n`ctx.navigate(id)` switches (`\"lobby\"` is the base); called inside `setup()` it picks the mode the app\nstarts in. `ctx.features.open(id, args)` from a game (the lobby not on screen) switches to the lobby\nand opens that tab there.\n\n`ctx.multiplayer` — a game that plays online registers itself (`registerGame({ mode, topology,\nchatMode, maxPlayers, joinInProgress, settings, start(room) })`) and takes the room the lobby's\nrooms system hands it on \"Play\"; it never creates or joins rooms (skill **multiplayer-realtime**).\n\nOptional static field: `sharedUi: { provides?: SharedUiRole[]; requires?: SharedUiRole[] }` — see\n\"Shared chrome\" below.\n\n`meta.type` is `game | app | ai-app`; `meta.engine` is `three | phaser | dom` (`dom` = no renderer —\na pure React/DOM app module). `setup` is called ONCE with `ctx: ModuleContext`.\n\n## EngineScene (the rendered part)\n\nA scene mounts into a bare `HTMLElement` (framework-free — this is why a vanilla Three game like\nvoxelcraft fits). The host's Mode Router drives it; only the active mode runs.\n\n```ts\nconst scene: EngineScene = {\n  surface: \"fullbleed-canvas\",\n  mount(ctx: SceneMountContext) {\n    controller = new Controller(ctx.host);\n    box.set(controller);\n  },\n  activate() {\n    controller?.setRunning(true);\n  }, // became the active mode → resume RAF\n  suspend() {\n    controller?.setRunning(false);\n  }, // hidden → stop RAF (invariant: only active ticks)\n  destroy() {\n    controller?.destroy();\n  }, // permanent teardown\n};\n```\n\n`mount` takes a context object (not a bare element) so it can grow — e.g. a host-shared renderer in\nthe composition era — without breaking the contract. A scene MUST stop its RAF on `suspend`.\n\n### Loading — never a still screen\n\nA scene's FIRST start goes behind the app's loading screen by itself: the host shows it (themed,\n\"Loading «<mode>»…\"), lets it paint, THEN calls `mount` — so heavy synchronous work in `mount`\n(generating terrain, building meshes) never looks like a frozen app. The screen goes away after the\nfirst frame, or — when the scene has more to do — when its optional `ready(): Promise<void>` resolves\n(voxelcraft: the last played world restored from storage). Never draw your own start-up spinner.\n\nLong work AFTER the start goes through `ctx.loading` — the same screen:\n\n- `await ctx.loading.track(fetchWorld(), \"Loading the world…\")` — async work;\n- `await ctx.loading.run(() => buildWorld(seed), \"Building the world…\")` — work that BLOCKS the page:\n  the screen is shown and painted first (calling heavy code right after `begin()` freezes the page\n  before the screen appears);\n- `const task = ctx.loading.begin(\"…\"); task.progress(0.4, \"Textures…\"); task.done();` — with progress.\n\n### Notifications — `ctx.notifications`\n\nThe app's one system of toasts and alert windows (the UI kit draws them, themed): never draw a banner\nof your own. `ctx.notifications.toast({ level, title, message, icon, image, source, key, actions })`\n— `level`: `info | success | warning | error | reward`; `source` defaults to the module's id (the\ntoast shows that screen's name and a tap opens it). `await ctx.notifications.alert({ level, title,\nmessage, actions: [{ id: \"go\", label: \"Open\", primary: true, openFeature: \"season\" }, { label: \"Later\" }] })`\nresolves with the pressed action's id (`null` — closed). React screens: `useNotify()` from the kit.\n\nA module that registers a scene MUST also publish its debug surface — `ctx.exposeToAgent({ state,\nactions, describeActions })` — and must NOT gate controls on Pointer Lock (unavailable in the\npreview's cross-origin iframe). Nothing inside a `<canvas>` is observable from the DOM, so without\nthe surface neither the AI Coder nor a human reviewer can tell what the game is doing. See the\n`idosgames-agent-debug-surface` skill.\n\n### `capture()` — the frame for \"Take a shot and share\"\n\nidosgames.com has a **Shot** button under the game: it asks the game for one frame, puts the\nplatform's branding and a QR code on it and offers to post it. A scene answers through the optional\n`capture?(): Promise<Blob | null>`. The host (`@idosgames/app-shell`) wires the request itself —\na module only has to return a picture of its active scene.\n\n**Implement it in any scene that renders to a canvas.** Without it the host falls back to reading\nthe `<canvas>` from outside, and for WebGL that is a trap: a renderer created WITHOUT\n`preserveDrawingBuffer` (the default, and the right default — the flag costs memory and a copy every\nframe) has already cleared its buffer by the time anyone reads it, so `toBlob()` returns a **fully\nblack** image and reports nothing. The host rejects single-colour frames, so the player gets the\ngame's cover instead of their moment.\n\nRender and read in the SAME tick:\n\n```ts\n// three.js\ncapture() {\n  return new Promise((resolve) => {\n    renderer.render(scene, camera);          // draw now…\n    renderer.domElement.toBlob(resolve, \"image/png\"); // …and read before the buffer is cleared\n  });\n},\n\n// Phaser — use its own snapshot, it handles the timing\ncapture() {\n  return new Promise((resolve) => {\n    setTimeout(() => resolve(null), 1500); // no frame came (context lost) → answer \"no\", don't hang\n    game.loop.wake();                       // a sleeping loop never draws again → snapshot never fires\n    game.renderer.snapshot((image) => {\n      if (!(image instanceof HTMLImageElement)) return resolve(null);\n      const c = document.createElement(\"canvas\");\n      c.width = image.naturalWidth || image.width;\n      c.height = image.naturalHeight || image.height;\n      c.getContext(\"2d\")?.drawImage(image, 0, 0);\n      c.toBlob(resolve, \"image/png\");\n    });\n  });\n},\n```\n\nAlways answer — with a Blob or `null`. A `capture()` that never settles makes the site wait out its\ntimeout before it falls back, and the player stares at a spinner.\n\nReturn `null` when there is nothing worth showing (loading, no scene yet) — the site then uses the\ncover. Only the scene is captured, not the React panels over it: a shot for a feed reads better\nwithout the HUD. DOM-only modules (no canvas) simply omit `capture`. Working references:\n`modules/board-game` and `modules/voxelcraft` (three), `modules/idle-rpg` (Phaser).\n\n## UiPanel (the React part)\n\nPanels are React components the host renders inside its provider stack (client + status already\nprovided). Use `@idosgames/react` hooks (`useIDosGamesClient`, `useUserState`) — do NOT re-create\nproviders.\n\n- `slot`: `hud | sidebar | overlay | modal`.\n- `activeOnly` (default true): show only while this module's mode is active. Set `false` for shared\n  chrome that stays across every mode (e.g. a persistent HUD).\n- `overlay`/`sidebar` layers sit between the shared HUD and the nav (the host measures both), so a\n  panel positioned `absolute` inside its layer never ends up under them. Things drawn outside the\n  layers use `var(--idos-safe-top, 0px)` / `var(--idos-safe-bottom, 0px)`.\n- A `hud` panel's wrapper is `display: contents`: the panel is a direct flex child of the HUD row\n  (can `flex: 1`) and must set `pointer-events: auto` only on its controls.\n\n## Shared chrome (`sharedUi`)\n\nRoles: `currency-bar` (virtual-currency balances), `wallet` (crypto wallet entry — `LazyWalletPanel`),\n`status` (the `useStatus()` line), `account` (Log out + player ID), `menu` (the menu of features),\n`modes` (the switch between modes). The base takes `currency-bar`, `wallet`, `account`, `menu` and\n`modes` — its lobby draws them; `status` stays with each game. A module that draws one for every\nmode declares `sharedUi: { provides: [...] }` on the module object — statically, so the host resolves\nowners before any `setup()` and the answer never depends on module order.\n\n**Rule for templates: yield every role you draw yourself.** Read it once in `setup()` and close over\nthe answer (it is fixed for the session):\n\n```ts\nsetup(ctx) {\n  const chrome = {\n    wallet: ctx.sharedUi.shouldDraw(\"wallet\"),\n    balances: ctx.sharedUi.shouldDraw(\"currency-bar\"),\n    status: ctx.sharedUi.shouldDraw(\"status\"),\n  };\n  ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: makeRootPanel(box, chrome) });\n}\n```\n\nHide only the SHARED pieces — genre UI (the board's stage/tile/cycle chips) always stays. Never\nwrap your UI in your own `<StatusProvider>`: the host provides ONE, and a nested one would swallow\nyour messages so the shared status line never sees them. A module that needs a role but does not\ndraw it declares `sharedUi: { requires: [\"currency-bar\"] }`. `ctx.sharedUi.ownerOf(role)` names the\nprovider (or `null`). A full-screen mode (its own bottom tab bar) that shows the player ID and\n\"Log out\" in its own header declares `sharedUi: { drawsOwn: [\"account\"] }` and draws them only while\n`shouldDraw(\"account\")`: the host then hides its floating bottom-left copy while that mode is on\nscreen (it would cover the tab bar) and keeps it in the other modes. `drawsOwn` takes no role —\nwith the base installed the lobby draws the account and the mode hides its copy.\n\n## Events (`ctx.events`)\n\nTyped topic tokens — `defineTopic(\"<your-id>:<event>@1\", shape({ … }))` from\n`@idosgames/module-sdk`; emit only your own namespace; to listen to another module, copy its topic\nand payload descriptor from the catalog into your own `defineTopic` (never import it); declare both\nin `module.meta.json` (`events.emits` / `events.listens`). **Subscribe in `setup()`**, not in a panel\neffect — `activeOnly` panels unmount with their mode and miss events; store what arrives in a small\nstore the panel reads. Full rules and examples: **idosgames-compose-modules** (\"Signals between\nmodules\"). The string overloads (`emit(\"x\", …)`) are deprecated.\n\n## Content types (`ctx.content`) and switching modes (`ctx.navigate`)\n\nA game whose players make things (worlds, levels, skins) registers a **content type handler** so the\nshared Workshop module can publish and open them — the Workshop never imports the game:\n\n```ts\nsetup(ctx) {\n  ctx.content.registerType({\n    type: \"voxelcraft.world\",   // = a key of Workshop.ContentTypes in the title config\n    label: \"VoxelCraft world\",\n    icon: \"⛏️\",\n    modeId: \"voxelcraft\",        // route to switch to after open()\n    async listLocal() { return saves.map((s) => ({ id: s.id, name: s.name, updatedAt: s.at })); },\n    async capture(localId) {     // roles/MIME types must fit the title's content type config\n      return { files: [{ role: \"main\", contentType: \"application/json\", data: json }],\n               thumbnail: { contentType: \"image/webp\", data: webp }, suggestedTitle: name };\n    },\n    async open(content) { importSave(content.files[0].data); },\n  });\n}\n```\n\nHandlers registered in `setup()` are removed with the module; `registerType` returns an unregister\nfunction for anything dynamic. `ctx.navigate(modeId)` switches the host to another module's route\n(the Workshop uses it to jump into the game after `open`); an unknown id is ignored. Details:\n**workshop-system**.\n\n## Bridging scene ↔ panel\n\nThe scene creates its controller at `mount` (needs the canvas), but panels render before that. Share\nit with a one-slot observable and read it with `useSyncExternalStore`:\n\n```ts\nexport function createControllerBox<T>() {\n  /* get/set/subscribe */\n}\n// panel: const controller = useSyncExternalStore(box.subscribe, box.get); if (!controller) return <Loading/>;\n```\n\nFor the module's controller React context use the shared factory instead of hand-writing it:\n\n```ts\nexport const [BoardControllerProvider, useBoardController] =\n  createControllerContext<BoardController>(\"BoardController\"); // from @idosgames/react\n```\n\n## Layout and boundaries\n\nA module is one folder, `src/modules/<id>/`. It imports only its own files, the game's shared code\nin `src/shared/` and npm packages — never another module's files or host files. Talk to other\nmodules through the shared `ctx.client` (durable state) and `ctx.events` (live signals, typed\ntopics `<module-id>:<event>@<major>` declared in `module.meta.json`). A module shipped in the catalog is fully self-contained — it never uses\n`src/shared/`, so it installs into any game; a game's own module may use it, and its shared code is\ncopied into it when it is published for other creators.\n\n```\nsrc/modules/<id>/\n  index.ts           export { <camelCaseId>Module } from \"./module\";\n  module.ts          defineModule({ … })\n  module.meta.json   manifest: type (template|feature), summary, provides, tags, version, author\n  components/  game/  data/  react/   — as needed\n```\n\nEvery module carries its own `module.meta.json` (the `ModuleManifest` shape), including a game's own\nmodules. The full standard — where a new feature goes, file size, documentation — is\n**idosgames-project-structure**.\n\n## Dependencies\n\nDeclare only the module's UNIQUE deps (e.g. `phaser` for idle-rpg, `three` for board/voxel) plus the\nshared baseline (react, @idosgames/*). The platform pins shared libs identically across modules; two\nmodules must not request different versions of one package (the build allowlist rejects it).\n\nStudy a real module via `get_module {id}` (MCP) before writing a new one.\n",
   "references": []
 }