@idosgames/mcp 0.1.20 → 0.1.22

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\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: 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",
   "references": []
 }

package/registry/skills/idosgames-project-structure.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-project-structure",
   "description": "The layout standard for an iDosGames game project (host shell + composable modules) and how it grows without turning into a mess: where a new feature goes (a catalog module, an existing module, or a new module), the folder layout inside a module, module boundaries (no cross-module imports), the game's shared code in src/shared/, module.meta.json, src/modules.ts being platform-generated, idos.modules.lock.json and customized catalog modules, file size, and project documentation (IDOS.md vs docs/feature-history/). Use this BEFORE creating a module, creating or changing src/shared/, moving code between files or folders, adding a system that spans several modules, or writing project documentation.",
-  "content": "---\nname: idosgames-project-structure\ndescription: >-\n  The layout standard for an iDosGames game project (host shell + composable modules) and how it\n  grows without turning into a mess: where a new feature goes (a catalog module, an existing module,\n  or a new module), the folder layout inside a module, module boundaries (no cross-module imports),\n  the game's shared code in src/shared/, module.meta.json, src/modules.ts being platform-generated,\n  idos.modules.lock.json and customized catalog modules, file size, and project documentation\n  (IDOS.md vs docs/feature-history/). Use this BEFORE creating a module, creating or changing\n  src/shared/, moving code between files or folders, adding a system that spans several modules, or\n  writing project documentation.\n---\n\n# Project structure (iDosGames game projects)\n\n## The project at a glance\n\n```\nIDOS.md                    project guide every agent reads first — short, evergreen\nAGENTS.md, CLAUDE.md       pointers to IDOS.md for external tools (Cursor, Codex, Claude Code…)\nidos.modules.lock.json     platform-owned: catalog modules, their versions and file fingerprints\ndocs/feature-history/      one file per game system + README.md index\npackage.json · vite.config.ts · tsconfig.json · index.html\nsrc/\n  main.tsx                 the host: ONE SDK client + mountHost([baseModule, ...modules])\n  app.config.ts            what happens after sign-in (start) and the lobby's tab order\n  ui.config.ts             the look, animations and sounds of every screen\n  base/                    THE BASE: login/ (sign-in), lobby/ (tabs, balances, wallet, profile, \"Play\"),\n                           module.ts (baseModule) — ordinary project code\n  modules.ts               the composition list — generated by the platform\n  idos.title.ts            the project's identity — generated, never edit\n  config.ts                title / environment resolution — platform-owned, never edit\n  env.ts                   build-time values (.env.local)\n  shared/                  optional: code two or more of THIS game's modules need\n    ui/  types/  utils/\n  modules/\n    <id>/                  one folder per module: the catalog's systems and games, the game's own\n```\n\nSign-in and the lobby are the base; everything else the game does lives in a module — a **system**\n(its screen is a lobby tab: shop, heroes, leaderboards…) or a **game** (its mode gets a \"Play\"\nbutton). Ready-made catalog modules and the game's own modules\nshare the one `src/modules/` folder — where a module came from is recorded in\n`idos.modules.lock.json`, not in its path, because a catalog template becomes the creator's code the\nmoment they start changing it. `src/shared/` is the one place for code several of the game's own\nmodules use; there is no project-level `utils/` or `components/` besides it.\n\n## Where does a new feature go?\n\nDecide in this order:\n\n1. **The catalog already has it** → install that module (the AI editor's InstallModule, or\n   `get_module` over MCP) and adapt it. Don't rebuild what exists.\n2. **It extends an existing module's gameplay** (a new tile type in the board game, a new enemy in\n   the idle RPG) → change that module, inside its folder.\n3. **It is its own mode, screen or system** (a shop, a clan screen, a mini-game, a quest board) → a\n   **new module** `src/modules/<feature-id>/`.\n4. **It is the lobby, sign-in or chrome everybody shares.** Balances, the wallet, the profile, the\n   tabs and \"Play\" are the base (`src/base/`) — change it there; games hide their own copies of the\n   balances and wallet by themselves. Other UI shown over every mode → a panel with\n   `activeOnly: false`. See **idosgames-compose-modules**.\n5. **It is code two or more of the game's modules need** (a shared type, the game's UI kit, a\n   formatting helper) → `src/shared/` (see below).\n\nBetween 2 and 3: if it would get its own lobby tab or \"Play\" button, or could be switched off on its\nown, it is its own module.\n\n## Inside a module\n\n```\nsrc/modules/<id>/\n  index.ts           export { <camelCaseId>Module } from \"./module\";\n  module.ts          defineModule({ id, meta, setup(ctx) { … } })\n  module.meta.json   manifest: type, summary, provides, tags, version, author\n  components/        React panels and UI pieces\n  game/              engine and simulation (engine subfolders are fine: game/phaser/, game/three/)\n  data/              static tables and tuning (levels, tiles, item lists)\n  react/             hooks, contexts, the scene↔panel controller bridge\n```\n\n- The folder id is kebab-case `[a-z0-9-]`, at most 64 characters. The export name is derived from it\n  — `daily-quests` → `dailyQuestsModule` — and the platform registers the module by that exact name.\n- Create only the folders you need; a small module can be `index.ts` + `module.ts` + one component.\n- `voxelcraft` is a ported vanilla game with its own layout — leave it as it is. New modules follow\n  the layout above.\n\n### module.meta.json\n\n```json\n{\n  \"id\": \"daily-quests\",\n  \"type\": \"feature\",\n  \"summary\": \"One-line pitch shown in the Modules dialog.\",\n  \"description\": \"What it does, in a few sentences.\",\n  \"provides\": [\"daily quest board\", \"streak rewards\"],\n  \"tags\": [\"quests\", \"retention\"],\n  \"version\": \"0.1.0\",\n  \"author\": { \"name\": \"…\" },\n  \"events\": {\n    \"emits\": [\n      {\n        \"topic\": \"daily-quests:quest-completed@1\",\n        \"when\": \"a quest's reward was claimed\",\n        \"payload\": { \"questId\": \"string\" }\n      }\n    ],\n    \"listens\": [\n      {\n        \"topic\": \"idle-rpg:character-upgraded@1\",\n        \"why\": \"progress 'level a hero' quests\"\n      }\n    ]\n  }\n}\n```\n\n`type` is `template` (a complete game to start from) or `feature` (a capability added to a game).\n`events` declares every `defineTopic(...)` the module uses — its own topics under `emits` (with the\nsame payload descriptor it passes to `shape()`), other modules' under `listens`; omit it when the\nmodule has none.\n`provides` is what an agent matches a request against — keep it accurate. Every module carries this\nfile, the game's own included: it is how a module shows up in the Modules dialog, and what lets it be\npublished to the shared catalog for other creators later.\n\n### Register it\n\n`src/modules.ts` has exactly this shape — imports plus the array, nothing else:\n\n```ts\nimport type { Module } from \"@idosgames/module-sdk\";\nimport { boardGameModule } from \"./modules/board-game\";\nimport { dailyQuestsModule } from \"./modules/daily-quests\";\n\nexport const modules: Module[] = [boardGameModule, dailyQuestsModule];\n```\n\nThe platform regenerates this file whenever modules are installed or removed; any other code in it is\nlost. Array order is mount order (and nav order).\n\n## Module boundaries\n\nA module imports only:\n\n- files inside its own folder;\n- `src/shared/` — the game's shared code;\n- npm packages (`@idosgames/*`, `react`, `three`, `phaser`, …).\n\nNever another module's files (`../board-game/…`) and never host files (`../../main`, `../../config`).\nModules are mixed into different games — a module that reaches into its neighbours breaks the moment\none of them is removed or replaced. Cooperate instead through:\n\n- **Durable shared state** (currency, inventory, characters, progress) → the ONE SDK client every\n  module receives as `ctx.client`. Gold earned in one mode is spendable in another with no plumbing.\n- **Live signals** → `ctx.events` with typed topics `<module-id>:<event>@<major>`\n  (`defineTopic(\"idle-rpg:character-upgraded@1\", shape({ … }))`), declared in `module.meta.json`.\n  The emitter doesn't know who listens; a listener keeps its own copy of the topic. Topics shared by\n  several of THIS game's own modules can live in `src/shared/events/` and be imported on both sides.\n- **Code several modules need** → `src/shared/`.\n- **Logic that must be shared and trusted** → it belongs on the server (SDK services, CloudCode),\n  not in a client file.\n\n## src/shared/ — the game's shared code\n\nFor code that two or more of THIS game's own modules need.\n\n- **Created on demand.** Code only one module needs stays inside that module; move it to\n  `src/shared/` when a second module needs it, not in advance.\n- **One-way dependency.** Modules import from `src/shared/`; `src/shared/` NEVER imports a module.\n  Otherwise every module using the shared code silently drags another module in with it.\n- **No game state, no game logic.** Types, constants, the game's UI components and theme, pure\n  helpers. Progress and data go through the SDK client, signals through `ctx.events`.\n- **Organised by purpose:** `src/shared/ui/`, `src/shared/types/`, `src/shared/utils/` — not one pile.\n- **Catalog modules never depend on it.** A module that ships in the catalog must install into any\n  game, so it is fully self-contained. A game's own module that imports `src/shared/` is tied to this\n  game — fine for your own game; when you publish such a module, its shared code is copied into it\n  (the Modules dialog marks these modules \"uses shared code\").\n\n## Catalog modules you change\n\nA module installed from the catalog is source in your project — change it freely. At install the\nplatform records its file fingerprints in `idos.modules.lock.json`; once any file differs, the module\ncounts as **customized**, and updating it from the catalog is refused until the user confirms\noverwriting their changes in the Modules dialog. An agent never forces that overwrite. Write down\nnon-obvious customizations in `docs/feature-history/` so the next person knows why the module differs\nfrom the catalog.\n\n## Files\n\n- Keep files focused. When a change adds a new responsibility to a file past ~400 lines, move that\n  part into its own file — as part of that change, not as a separate drive-by refactor.\n- `src/idos.title.ts`, `src/config.ts` and `idos.modules.lock.json` are platform-owned: never edit\n  them. The platform's build packs its own `idos.title.ts` and `config.ts` over the project's, so\n  an edit there never reaches the game anyway.\n- Never read the title or the environment from the URL: a link is editable by anyone. Use\n  `client.titleID` (or `ctx.titleId` in a module's `setup()`).\n\n## Documentation\n\n- **IDOS.md** — the always-loaded guide: what the game is (\"This game\"), layout, conventions,\n  \"never do X\" constraints, lasting user preferences. Short and evergreen; change a line when a fact\n  changes. The \"Installed modules\" block is maintained by the platform.\n- **docs/feature-history/<slug>.md** — one file per game system or feature: what was built, why,\n  and the decisions and constraints the code does not show. Update the system's file when it\n  changes, and give every file ONE line in `docs/feature-history/README.md`:\n  `- [Title](slug.md) — one-line gist`.\n- Never append a feature write-up to IDOS.md. It is loaded on every run, so every paragraph there is\n  paid for by all future work — that is exactly how instruction files bloat.\n- Feature-history entries are not loaded automatically: open the relevant one before changing that\n  system.\n",
+  "content": "---\nname: idosgames-project-structure\ndescription: >-\n  The layout standard for an iDosGames game project (host shell + composable modules) and how it\n  grows without turning into a mess: where a new feature goes (a catalog module, an existing module,\n  or a new module), the folder layout inside a module, module boundaries (no cross-module imports),\n  the game's shared code in src/shared/, module.meta.json, src/modules.ts being platform-generated,\n  idos.modules.lock.json and customized catalog modules, file size, and project documentation\n  (IDOS.md vs docs/feature-history/). Use this BEFORE creating a module, creating or changing\n  src/shared/, moving code between files or folders, adding a system that spans several modules, or\n  writing project documentation.\n---\n\n# Project structure (iDosGames game projects)\n\n## The project at a glance\n\n```\nIDOS.md                    project guide every agent reads first — short, evergreen\nAGENTS.md, CLAUDE.md       pointers to IDOS.md for external tools (Cursor, Codex, Claude Code…)\nidos.modules.lock.json     platform-owned: catalog modules, their versions and file fingerprints\ndocs/feature-history/      one file per game system + README.md index\npackage.json · vite.config.ts · tsconfig.json · index.html\nsrc/\n  main.tsx                 the host: ONE SDK client + mountHost([baseModule, ...modules])\n  app.config.ts            what happens after sign-in (start) and the lobby's tab order\n  ui.config.ts             the look, animations and sounds of every screen\n  base/                    THE BASE: login/ (sign-in), lobby/ (tabs, balances, wallet, profile, \"Play\"),\n                           module.ts (baseModule) — ordinary project code\n  modules.ts               the composition list — generated by the platform\n  idos.title.ts            the project's identity — generated, never edit\n  config.ts                title / environment resolution — platform-owned, never edit\n  env.ts                   build-time values (.env.local)\n  shared/                  optional: code two or more of THIS game's modules need\n    ui/  types/  utils/\n  modules/\n    <id>/                  one folder per module: the catalog's systems and games, the game's own\n```\n\nSign-in and the lobby are the base; everything else the game does lives in a module — a **system**\n(its screen is a lobby tab: shop, heroes, leaderboards…) or a **game** (its mode gets a \"Play\"\nbutton). Ready-made catalog modules and the game's own modules\nshare the one `src/modules/` folder — where a module came from is recorded in\n`idos.modules.lock.json`, not in its path, because a catalog template becomes the creator's code the\nmoment they start changing it. `src/shared/` is the one place for code several of the game's own\nmodules use; there is no project-level `utils/` or `components/` besides it.\n\n## Where does a new feature go?\n\nDecide in this order:\n\n1. **The catalog already has it** → install that module (the AI editor's InstallModule, or\n   `get_module` over MCP) and adapt it. Don't rebuild what exists.\n2. **It extends an existing module's gameplay** (a new tile type in the board game, a new enemy in\n   the idle RPG) → change that module, inside its folder.\n3. **It is its own mode, screen or system** (a shop, a clan screen, a mini-game, a quest board) → a\n   **new module** `src/modules/<feature-id>/`.\n4. **It is the lobby, sign-in or chrome everybody shares.** Balances, the wallet, the profile, the\n   tabs and \"Play\" are the base (`src/base/`) — change it there; games hide their own copies of the\n   balances and wallet by themselves. Other UI shown over every mode → a panel with\n   `activeOnly: false`. See **idosgames-compose-modules**.\n5. **It is code two or more of the game's modules need** (a shared type, the game's UI kit, a\n   formatting helper) → `src/shared/` (see below).\n\nBetween 2 and 3: if it would get its own lobby tab or \"Play\" button, or could be switched off on its\nown, it is its own module.\n\n## Inside a module\n\n```\nsrc/modules/<id>/\n  index.ts           export { <camelCaseId>Module } from \"./module\";\n  module.ts          defineModule({ id, meta, setup(ctx) { … } })\n  module.meta.json   manifest: type, summary, provides, tags, version, author\n  components/        React panels and UI pieces\n  game/              engine and simulation (engine subfolders are fine: game/phaser/, game/three/)\n  data/              static tables and tuning (levels, tiles, item lists)\n  react/             hooks, contexts, the scene↔panel controller bridge\n```\n\n- The folder id is kebab-case `[a-z0-9-]`, at most 64 characters. The export name is derived from it\n  — `daily-quests` → `dailyQuestsModule` — and the platform registers the module by that exact name.\n- Create only the folders you need; a small module can be `index.ts` + `module.ts` + one component.\n- `voxelcraft` is a ported vanilla game with its own layout — leave it as it is. New modules follow\n  the layout above.\n\n### module.meta.json\n\n```json\n{\n  \"id\": \"daily-quests\",\n  \"type\": \"feature\",\n  \"summary\": \"One-line pitch shown in the Modules dialog.\",\n  \"description\": \"What it does, in a few sentences.\",\n  \"provides\": [\"daily quest board\", \"streak rewards\"],\n  \"tags\": [\"quests\", \"retention\"],\n  \"version\": \"0.1.0\",\n  \"author\": { \"name\": \"…\" },\n  \"events\": {\n    \"emits\": [\n      {\n        \"topic\": \"daily-quests:quest-completed@1\",\n        \"when\": \"a quest's reward was claimed\",\n        \"payload\": { \"questId\": \"string\" }\n      }\n    ],\n    \"listens\": [\n      {\n        \"topic\": \"idle-rpg:character-upgraded@1\",\n        \"why\": \"progress 'level a hero' quests\"\n      }\n    ]\n  }\n}\n```\n\n`type` is `template` (a complete game to start from) or `feature` (a capability added to a game).\n`events` declares every `defineTopic(...)` the module uses — its own topics under `emits` (with the\nsame payload descriptor it passes to `shape()`), other modules' under `listens`; omit it when the\nmodule has none.\n`provides` is what an agent matches a request against — keep it accurate. Every module carries this\nfile, the game's own included: it is how a module shows up in the Modules dialog, and what lets it be\npublished to the shared catalog for other creators later.\n\n### Register it\n\n`src/modules.ts` has exactly this shape — imports plus the array, nothing else:\n\n```ts\nimport type { Module } from \"@idosgames/module-sdk\";\nimport { boardGameModule } from \"./modules/board-game\";\nimport { dailyQuestsModule } from \"./modules/daily-quests\";\n\nexport const modules: Module[] = [boardGameModule, dailyQuestsModule];\n```\n\nThe platform regenerates this file whenever modules are installed or removed; any other code in it is\nlost. Array order is mount order (and nav order).\n\n## Module boundaries\n\nA module imports only:\n\n- files inside its own folder;\n- `src/shared/` — the game's shared code;\n- npm packages (`@idosgames/*`, `react`, `three`, `phaser`, …).\n\nNever another module's files (`../board-game/…`) and never host files (`../../main`, `../../config`).\nModules are mixed into different games — a module that reaches into its neighbours breaks the moment\none of them is removed or replaced. Cooperate instead through:\n\n- **Durable shared state** (currency, inventory, characters, progress) → the ONE SDK client every\n  module receives as `ctx.client`. Gold earned in one mode is spendable in another with no plumbing.\n- **Live signals** → `ctx.events` with typed topics `<module-id>:<event>@<major>`\n  (`defineTopic(\"idle-rpg:character-upgraded@1\", shape({ … }))`), declared in `module.meta.json`.\n  The emitter doesn't know who listens; a listener keeps its own copy of the topic. Topics shared by\n  several of THIS game's own modules can live in `src/shared/events/` and be imported on both sides.\n- **Code several modules need** → `src/shared/`.\n- **Logic that must be shared and trusted** → it belongs on the server (SDK services, CloudCode),\n  not in a client file.\n\n## src/shared/ — the game's shared code\n\nFor code that two or more of THIS game's own modules need.\n\n- **Created on demand.** Code only one module needs stays inside that module; move it to\n  `src/shared/` when a second module needs it, not in advance.\n- **One-way dependency.** Modules import from `src/shared/`; `src/shared/` NEVER imports a module.\n  Otherwise every module using the shared code silently drags another module in with it.\n- **No game state, no game logic.** Types, constants, the game's UI components and theme, pure\n  helpers. Progress and data go through the SDK client, signals through `ctx.events`.\n- **Organised by purpose:** `src/shared/ui/`, `src/shared/types/`, `src/shared/utils/` — not one pile.\n- **Catalog modules never depend on it.** A module that ships in the catalog must install into any\n  game, so it is fully self-contained. A game's own module that imports `src/shared/` is tied to this\n  game — fine for your own game; when you publish such a module, its shared code is copied into it\n  (the Modules dialog marks these modules \"uses shared code\").\n\n## Catalog modules you change\n\nA module installed from the catalog is source in your project — change it freely. At install the\nplatform records its file fingerprints in `idos.modules.lock.json`; once any file differs, the module\ncounts as **customized**, and updating it from the catalog is refused until the user confirms\noverwriting their changes in the Modules dialog. An agent never forces that overwrite. Write down\nnon-obvious customizations in `docs/feature-history/` so the next person knows why the module differs\nfrom the catalog.\n\n## Files\n\n- Keep files focused. When a change adds a new responsibility to a file past ~400 lines, move that\n  part into its own file — as part of that change, not as a separate drive-by refactor.\n- `src/idos.title.ts`, `src/config.ts` and `idos.modules.lock.json` are platform-owned: never edit\n  them. The platform's build packs its own `idos.title.ts` and `config.ts` over the project's, so\n  an edit there never reaches the game anyway.\n- Never read the title or the environment from the URL: a link is editable by anyone. Use\n  `client.titleID` (or `ctx.titleId` in a module's `setup()`).\n\n## Documentation\n\n- **IDOS.md** — the always-loaded guide: what the game is (\"This game\"), layout, conventions,\n  \"never do X\" constraints, lasting user preferences. Short and evergreen; change a line when a fact\n  changes. The \"Installed modules\" block is maintained by the platform.\n- **docs/feature-history/<slug>.md** — one file per game system: ONLY what a later session must take\n  into account and cannot see in the code — why it is designed this way, a non-obvious constraint, a\n  decision the user made, a rule for how the system must be changed. Test: \"would a new session\n  working on this system go wrong without knowing this?\" If not, write nothing. Ordinary edits (a\n  restyle, a bug fix, a text or balance tweak, a routine new screen) get no entry, and it is never a\n  log of what was done. Update the system's file when such a fact changes, and give every file ONE\n  line in `docs/feature-history/README.md`: `- [Title](slug.md) — one-line gist`.\n- Never append a feature write-up to IDOS.md. It is loaded on every run, so every paragraph there is\n  paid for by all future work — that is exactly how instruction files bloat.\n- Feature-history entries are not loaded automatically: open the relevant one before changing that\n  system.\n",
   "references": []
 }

package/registry/skills/idosgames-ui-kit.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-ui-kit",
   "description": "Build and restyle game screens with the iDosGames UI kit (@idosgames/react/ui) and the ready system modules (store, character, inventory, …): change colours, animations and sounds in ONE file (src/ui.config.ts), install a shop / VIP / heroes / inventory / chests / boosts / leaderboard / daily rewards / quests / collections / craft / marketplace / offers / events / team event / season / friends / chat / invite / arena / multiplayer rooms / profile / tutorials / workshop / AI studio system instead of writing it, open another module's screen with ctx.features.open, register a new screen (a lobby tab) with ctx.features.register and hide it while the title has no data (setAvailable), split a dense screen into popups (Popup, ConfirmPopup, bottom sheet on a phone), play UI sounds, celebrate a reward (icons fly to the balance counters), mark elements for tutorial hints (data-tutorial-anchor), and read the player's sound / motion prefs. Use this whenever the user asks to change how the game's interface looks, sounds or animates, to add or build a game screen or menu, a popup, a reward animation, a bottom navigation, a \"More\" menu, a settings screen, or touches @idosgames/react/ui, defineUiConfig, ui.config.ts, ctx.features, FeatureScreenProps, useCelebrate, usePlayerPrefs, Popup, Tabs or ResourceList.",
-  "content": "---\nname: idosgames-ui-kit\ndescription: >-\n  Build and restyle game screens with the iDosGames UI kit (@idosgames/react/ui) and the ready\n  system modules (store, character, inventory, …): change colours, animations and sounds in ONE file (src/ui.config.ts),\n  install a shop / VIP / heroes / inventory / chests / boosts / leaderboard / daily rewards / quests /\n  collections / craft / marketplace / offers / events / team event / season / friends / chat / invite /\n  arena / multiplayer rooms / profile / tutorials / workshop / AI studio system instead of writing it, open another module's screen with ctx.features.open, register a new screen (a lobby\n  tab) with ctx.features.register and hide it while the title has no data (setAvailable), split a dense screen into popups (Popup, ConfirmPopup, bottom sheet on a\n  phone), play UI sounds, celebrate a reward (icons fly to the balance counters), mark elements for\n  tutorial hints (data-tutorial-anchor), and read the player's sound / motion prefs. Use this\n  whenever the user asks to change how the game's interface looks, sounds or animates, to add or\n  build a game screen or menu, a popup, a reward animation, a bottom navigation, a \"More\" menu, a\n  settings screen, or touches @idosgames/react/ui, defineUiConfig, ui.config.ts, ctx.features,\n  FeatureScreenProps, useCelebrate, usePlayerPrefs, Popup, Tabs or ResourceList.\n---\n\n# The UI kit and the system modules\n\nThe app's interface is the base's lobby (`src/base/`) plus **system modules**, all on one **UI kit**:\n\n- `@idosgames/react/ui` — the kit: components (buttons, tabs, popups, resource lists, item tiles,\n  progress bars, timers), the reward popup, toasts, UI sounds (synthesized, no files), animations,\n  and the player's own sound / motion prefs.\n- system modules — the platform's systems, each a whole `feature` module (its screen = a lobby\n  tab, its client logic, its demo settings). The base installs six of them into every new project\n  (`inBase`: profile, inventory, invite, friends, quests, mailbox); the rest are installed only when the app\n  needs them (a game's `uses`, or a task that needs what they `provide`). ONE system per player-facing module of the engine\n  (`API/Client/v2/<Module>`) — the owner's rule since 29.09.2026. The module id is the feature id:\n\n| Module        | Engine module  | Screen                                                        |\n| ------------- | -------------- | ------------------------------------------------------------- |\n| `store`       | Store+Purchase | shop: stores as tabs, offers, purchase popup                  |\n| `premium`     | Premium        | VIP passes: benefits, timer, free trial, buy / extend         |\n| `character`   | Character      | heroes: gear slots, \"Equip best\", stats, ranks, skins         |\n| `inventory`   | Item           | items by rarity, item card (always shown, even with no items) |\n| `lootboxes`   | Lootbox        | chests: every way to open, ×1 / ×10, opening animation        |\n| `boosts`      | TimedBoost     | running boosts + global happy hours, activate a boost         |\n| `leaderboard` | Leaderboard    | tables, my place, rank rewards, last cycle's prize            |\n| `rewards`     | Reward         | daily login calendar, greeting popup                          |\n| `quests`      | Quest          | quests by cycle, details, claim all, points track             |\n| `collections` | Collection     | album of sets, packs, chests for points, card trades          |\n| `craft`       | Craft          | recipes, contract popup                                       |\n| `marketplace` | Marketplace    | lots, auctions, selling, trades                               |\n| `deals`       | DealOffer      | special offers, auto-popup of a new deal                      |\n| `events`      | TimedEvent     | limited-time events, milestones, VIP prize                    |\n| `coop-events` | CoopEvent      | team event: join a group, spin to build, team prize           |\n| `season`      | Season         | season tiers, VIP prize                                       |\n| `friends`     | Social         | friends, requests, suggestions, news                          |\n| `chat`        | Chat           | channels, private chats                                       |\n| `invite`      | Referral       | own code and link, friend's code, rewards (always shown)      |\n| `pvp`         | Match          | duels, strategy, fight replay                                 |\n| `multiplayer` | Multiplayer    | rooms: list, create / join by code, ready, chat, host \"Play\"  |\n| `profile`     | User           | name, sound, language, consent, delete account                |\n| `tutorials`   | Tutorial       | hint overlay + replay list                                    |\n| `workshop`    | Workshop       | players' and the publisher's content: catalog, publish        |\n| `ai`          | AI             | AI studio: the title's AI features for players, history       |\n\nNot a system on purpose: Currency, Authentication, Blockchain (the base — balances, sign-in,\nwallet); GameLoop (the `board-game` game); CommunityMarketing (idosgames.com only); Mailbox and\nAdvertising (no client handler / no web ad network); Analytics, Experiment, Push, Localization,\nCloudCode, DataCollections, TitleCustomData, UserCustomData (services the systems and games call).\n\nHand-offs between systems go through `ctx.features.open(id, args)`: inventory → `character`\n(`{ itemInstanceID }`) and → `lootboxes` (`{ itemID }` of a chest or key); events / season →\n`premium` (`{ premiumID }`). Multiplayer: the `multiplayer` system owns the rooms; a game registers\nin `ctx.multiplayer` and takes the room in `start(room)` (skill **multiplayer-realtime**); the lobby\nshows \"With friends\" next to such a game's \"Play\".\n\n**Need one of these? Install the module — don't write the screen.** Every screen follows the\nserver's rules and ships demo title settings (`title-seed.json`). The app does not need one → remove it\nfrom `src/modules.ts`, its tab is gone. The lobby itself (tabs, balances, wallet, profile, \"Play\") is\nthe base, `src/base/lobby/`.\n\n## Change the look, animations and sounds — only in `src/ui.config.ts`\n\n```ts\nimport { defineUiConfig } from \"@idosgames/react/ui\";\n\nexport default defineUiConfig({\n  theme: {\n    bgTop: \"#10263f\",\n    panel: \"#1b3a5c\",\n    gold: \"#ffcc33\",\n    radius: 12,\n    rarity: { Mythic: \"#ff3df5\" },\n  },\n  motion: { speed: 1.5, intensity: 0.5, particles: false },\n  sound: {\n    volume: 0.4,\n    events: {\n      click: \"tab\",\n      countTick: false,\n      reward: { url: \"https://…/win.mp3\" },\n    },\n  },\n});\n```\n\n- Every field is optional; what you leave out keeps its default. The host passes the file to\n  `mountHost({ ui })`, and every module on the kit follows it at once.\n- ⚠ **Never restyle a catalog module by editing it.** An edited module is marked \"customized\" and\n  stops getting catalog updates. Colours, radii, fonts, animation speed and sounds are all here.\n- Theme tokens: `bgTop`, `bgBottom`, `panel`, `panelDeep`, `panelEdge`, `text`, `textDim`, `gold`,\n  `goldDeep`, `green`, `greenDeep`, `blue`, `blueDeep`, `red`, `shadow`, `backdrop`, `radius`,\n  `buttonRadius`, `font`, `rarity` (rarity id → frame colour).\n- Motion: `enabled`, `speed` (2 = twice as fast), `intensity` (0 = no bounce), `rewardFlight`,\n  `particles`, `stagger`, `respectReducedMotion`.\n- Sound events: `click`, `tab`, `open`, `close`, `reward`, `coin`, `purchase`, `claim`, `error`,\n  `notify`, `lootbox`, `levelUp`, `countTick`. Each: another event's name, `{ url }`, `{ synth: {\nnotes: [{ freq, dur, wave }] } }` or `false`.\n- The PLAYER's own sound / volume / \"fewer animations\" live on the device (the profile module draws\n  them):\n  `const [prefs, setPrefs] = usePlayerPrefs()` → `{ muted, volume, reducedMotion }`.\n\n## Features: screens that find each other\n\nA module registers a **feature**; whoever draws the menu shows it — the base's lobby as tabs (phone:\n4 + \"More\", tablet: more, desktop: a side rail; the base takes the shared-UI role `\"menu\"`), or the\nhost's floating ☰ when nobody takes the role. Tab order and main tabs can be overridden in\n`src/app.config.ts` (`lobby.order`, `lobby.primary`).\n\n```ts\n// module.ts\nsetup(ctx) {\n  ctx.features.register({\n    id: \"forge\", label: \"Forge\", icon: \"hammer\", group: \"economy\", order: 60,\n    primary: false,          // true = a main tab of the lobby\n    Screen: ForgeScreen,     // (props: FeatureScreenProps) => ReactNode; props.args, props.close()\n    available: false,        // hidden until the title has something for it — see below\n  });\n  // Badge (\"something to claim\"): ctx.features.setBadge(\"forge\", 2)\n  // The title has forge recipes → show the tab; the reason is for the AI Coder's agent only:\n  ctx.features.setAvailable(\"forge\", hasRecipes(configSection(ctx.client, \"Craft\")), \"no forge recipes\");\n}\n```\n\n- Open another module's screen without importing it: `ctx.features.open(\"store\")`,\n  `ctx.features.open(\"chat\", { userID })`. It returns `false` when the module is not installed or its\n  tab is hidden (`ctx.features.get(\"store\")?.available`). From a game (the lobby is off screen) the\n  host shows the screen in a window.\n- A screen that depends on title data registers with `available: false` and calls\n  `ctx.features.setAvailable(id, ok, reason)` once it knows — from the client config\n  (`configSection(client, \"Store\")`) or a read it makes anyway (a badge watcher); no extra request\n  at start-up: every module's first reads arrive together and brush the per-player rate limit.\n- Groups: `economy`, `events`, `social`, `profile`. Icons are kit glyph names (`shop`, `hero`,\n  `bag`, `trophy`, `gift`, `hammer`, `market`, `offer`, `flame`, `friends`, `chat`, `link`,\n  `swords`, `user`, `bulb`, …) or an image URL.\n- Something that must be on screen all the time (a daily auto-popup, a badge watcher, an overlay) is\n  a panel: `ctx.registerPanel({ id, slot: \"modal\", activeOnly: false, component })`.\n\n## Building a screen on the kit\n\nKeep the screen a short list; put every detail in a **popup**.\n\n```tsx\nimport {\n  Button,\n  Popup,\n  ResourceList,\n  Tabs,\n  useCelebrate,\n  useToast,\n  useUiKit,\n  errorText,\n  grantedBy,\n  panel,\n  outlined,\n  v,\n} from \"@idosgames/react/ui\";\n\nfunction ForgeScreen(): ReactNode {\n  const [open, setOpen] = useState<string | null>(null);\n  return (\n    <div\n      style={{\n        display: \"grid\",\n        gridTemplateColumns: \"minmax(0, 1fr)\",\n        gap: 12,\n      }}\n    >\n      {/* rows… onClick={() => setOpen(id)} */}\n      {open ? (\n        <Popup title=\"Forge\" onClose={() => setOpen(null)} width={420}>\n          …\n        </Popup>\n      ) : null}\n    </div>\n  );\n}\n```\n\n- `Popup` is a bottom sheet on a phone and a centred window elsewhere (`variant=\"center\"` forces\n  centred); it animates in and out and plays open/close sounds. Close from inside with\n  `usePopupClose()`. `ConfirmPopup` for yes/no. A popup that opens BY ITSELF (not on a tap) passes\n  `queued` — auto-popups then show one at a time instead of stacking.\n- `useCelebrate()(lines)` shows \"You got\" and flies the icons to any element marked\n  `data-resource-counter=\"{currencyID}\"` (the lobby's balances are). Build the lines\n  from a response with `grantedBy(data)`; a reward with premium (VIP) bundles needs them added.\n- `useUiKit().play(\"claim\")`, `useUiKit().fx.burst(element)` — a sound and a particle burst.\n- `useToast()(text, \"error\")` for refusals; show `errorText(res.error)`, never re-check server rules.\n- Lines of resources: `grantLines(grant)`, `costLines(cost)`, `bundleLines(bundle)`,\n  `canAfford(lines, balances)`, `<ResourceList lines={…} />`. Names and icons: `useCatalog()`.\n- Words: `makeT(EN, RU)` for your strings, `plural(n, \"лот|лота|лотов\")` for counts.\n- ⚠ A root `display: grid` with a wide child (a row of tabs) grows past a phone screen — give it\n  `gridTemplateColumns: \"minmax(0, 1fr)\"`.\n\n## Tutorial hints\n\nThe `tutorials` module highlights any element marked `data-tutorial-anchor=\"…\"` — the lobby's tabs\nare `tab:{featureID}`, its profile button `lobby:profile`, its wallet `lobby:wallet`, a game's \"Play\"\nbutton `play:{modeID}`. Mark the controls of your own screen the same\nway; the publisher points tutorial steps at them in LiveOps (Tutorial → step → AnchorID).\n",
+  "content": "---\nname: idosgames-ui-kit\ndescription: >-\n  Build and restyle game screens with the iDosGames UI kit (@idosgames/react/ui) and the ready\n  system modules (store, character, inventory, …): change colours, animations and sounds in ONE file (src/ui.config.ts),\n  install a shop / VIP / heroes / inventory / chests / boosts / leaderboard / daily rewards / quests /\n  collections / craft / marketplace / offers / events / team event / season / friends / chat / invite /\n  arena / multiplayer rooms / profile / tutorials / workshop / AI studio system instead of writing it, open another module's screen with ctx.features.open, register a new screen (a lobby\n  tab) with ctx.features.register and hide it while the title has no data (setAvailable), split a dense screen into popups (Popup, ConfirmPopup, bottom sheet on a\n  phone), play UI sounds, celebrate a reward (icons fly to the balance counters), mark elements for\n  tutorial hints (data-tutorial-anchor), and read the player's sound / motion prefs. Use this\n  whenever the user asks to change how the game's interface looks, sounds or animates, to add or\n  build a game screen or menu, a popup, a reward animation, a bottom navigation, a \"More\" menu, a\n  settings screen, or touches @idosgames/react/ui, defineUiConfig, ui.config.ts, ctx.features,\n  FeatureScreenProps, useCelebrate, usePlayerPrefs, Popup, Tabs or ResourceList.\n---\n\n# The UI kit and the system modules\n\nThe app's interface is the base's lobby (`src/base/`) plus **system modules**, all on one **UI kit**:\n\n- `@idosgames/react/ui` — the kit: components (buttons, tabs, popups, resource lists, item tiles,\n  progress bars, timers), the reward popup, toasts, UI sounds (synthesized, no files), animations,\n  and the player's own sound / motion prefs.\n- system modules — the platform's systems, each a whole `feature` module (its screen = a lobby\n  tab, its client logic, its demo settings). The base installs six of them into every new project\n  (`inBase`: profile, inventory, invite, friends, quests, mailbox); the rest are installed only when the app\n  needs them (a game's `uses`, or a task that needs what they `provide`). ONE system per player-facing module of the engine\n  (`API/Client/v2/<Module>`) — the owner's rule since 29.09.2026. The module id is the feature id:\n\n| Module        | Engine module  | Screen                                                        |\n| ------------- | -------------- | ------------------------------------------------------------- |\n| `store`       | Store+Purchase | shop: stores as tabs, offers, purchase popup                  |\n| `premium`     | Premium        | VIP passes: benefits, timer, free trial, buy / extend         |\n| `character`   | Character      | heroes: gear slots, \"Equip best\", stats, ranks, skins         |\n| `inventory`   | Item           | items by rarity, item card (always shown, even with no items) |\n| `lootboxes`   | Lootbox        | chests: every way to open, ×1 / ×10, opening animation        |\n| `boosts`      | TimedBoost     | running boosts + global happy hours, activate a boost         |\n| `leaderboard` | Leaderboard    | tables, my place, rank rewards, last cycle's prize            |\n| `rewards`     | Reward         | daily login calendar, greeting popup                          |\n| `quests`      | Quest          | quests by cycle, details, claim all, points track             |\n| `collections` | Collection     | album of sets, packs, chests for points, card trades          |\n| `craft`       | Craft          | recipes, contract popup                                       |\n| `marketplace` | Marketplace    | lots, auctions, selling, trades                               |\n| `deals`       | DealOffer      | special offers, auto-popup of a new deal                      |\n| `events`      | TimedEvent     | limited-time events, milestones, VIP prize                    |\n| `coop-events` | CoopEvent      | team event: join a group, spin to build, team prize           |\n| `season`      | Season         | season tiers, VIP prize                                       |\n| `friends`     | Social         | friends, requests, suggestions, news                          |\n| `chat`        | Chat           | channels, private chats                                       |\n| `invite`      | Referral       | own code and link, friend's code, rewards (always shown)      |\n| `pvp`         | Match          | duels, strategy, fight replay                                 |\n| `multiplayer` | Multiplayer    | rooms: list, create / join by code, ready, chat, host \"Play\"  |\n| `profile`     | User           | name, sound, language, consent, delete account                |\n| `tutorials`   | Tutorial       | hint overlay + replay list                                    |\n| `workshop`    | Workshop       | players' and the publisher's content: catalog, publish        |\n| `ai`          | AI             | AI studio: the title's AI features for players, history       |\n\nNot a system on purpose: Currency, Authentication, Blockchain (the base — balances, sign-in,\nwallet); GameLoop (the `board-game` game); CommunityMarketing (idosgames.com only); Mailbox and\nAdvertising (no client handler / no web ad network); Analytics, Experiment, Push, Localization,\nCloudCode, DataCollections, TitleCustomData, UserCustomData (services the systems and games call).\n\nHand-offs between systems go through `ctx.features.open(id, args)`: inventory → `character`\n(`{ itemInstanceID }`) and → `lootboxes` (`{ itemID }` of a chest or key); events / season →\n`premium` (`{ premiumID }`). Multiplayer: the `multiplayer` system owns the rooms; a game registers\nin `ctx.multiplayer` and takes the room in `start(room)` (skill **multiplayer-realtime**); the lobby\nshows \"With friends\" next to such a game's \"Play\".\n\n**Need one of these? Install the module — don't write the screen.** Every screen follows the\nserver's rules and ships demo title settings (`title-seed.json`). The app does not need one → remove it\nfrom `src/modules.ts`, its tab is gone. The lobby itself (tabs, balances, wallet, profile, \"Play\") is\nthe base, `src/base/lobby/`.\n\n## Change the look, animations and sounds — only in `src/ui.config.ts`\n\n```ts\nimport { defineUiConfig } from \"@idosgames/react/ui\";\n\nexport default defineUiConfig({\n  theme: {\n    bgTop: \"#10263f\",\n    panel: \"#1b3a5c\",\n    gold: \"#ffcc33\",\n    radius: 12,\n    rarity: { Mythic: \"#ff3df5\" },\n  },\n  motion: { speed: 1.5, intensity: 0.5, particles: false },\n  sound: {\n    volume: 0.4,\n    events: {\n      click: \"tab\",\n      countTick: false,\n      reward: { url: \"https://…/win.mp3\" },\n    },\n  },\n});\n```\n\n- Every field is optional; what you leave out keeps its default. The host passes the file to\n  `mountHost({ ui })`, and every module on the kit follows it at once.\n- ⚠ **Never restyle a catalog module by editing it.** An edited module is marked \"customized\" and\n  stops getting catalog updates. Colours, radii, fonts, animation speed and sounds are all here.\n- **One theme for the WHOLE app:** sign-in (`src/base/login/`), the lobby, every system and the host's\n  own screens all draw from these tokens. A new look — even a light theme — is an edit of this file\n  ONLY: never recolour `LoginScreen.tsx`, the logo, icons or `index.html` by hand (the logo and the\n  sign-in icons are painted with the theme's colours, the page background follows `bgBottom`).\n- Theme tokens: `bgTop`, `bgBottom`, `panel`, `panelDeep`, `panelEdge`, `text`, `textDim`, `gold`,\n  `goldDeep`, `green`, `greenDeep`, `blue`, `blueDeep`, `red`, `redDeep`, `shadow`, `backdrop`,\n  `radius`, `buttonRadius`, `font`, `rarity` (rarity id → frame colour).\n- **Derived tokens — usually leave them out.** They are computed from the colours above: set a light\n  `panel` and dark `text`, and the dark text outline disappears (`textOutline`), lines and recesses\n  turn faint-dark instead of white/black (`line`, `well`, `wellSoft`, `wellShadow`, `edge`), cards get a\n  soft shadow (`panelShadow`), and buttons of a pastel tone get dark text (`onGreen`, `onGold`,\n  `onBlue`, `onRed`). Set one only to override the computed value.\n- A light theme is just colours:\n  `theme: { bgTop: \"#f4fcf8\", bgBottom: \"#d9f0e6\", panel: \"#ffffff\", panelDeep: \"#f1faf5\",\npanelEdge: \"#bfe6d3\", text: \"#1f3b30\", textDim: \"#5f7d71\", green: \"#7ee0b5\", greenDeep: \"#4cc493\" }`.\n- Motion: `enabled`, `speed` (2 = twice as fast), `intensity` (0 = no bounce), `rewardFlight`,\n  `particles`, `stagger`, `respectReducedMotion`.\n- Sound events: `click`, `tab`, `open`, `close`, `reward`, `coin`, `purchase`, `claim`, `error`,\n  `notify`, `lootbox`, `levelUp`, `countTick`. Each: another event's name, `{ url }`, `{ synth: {\nnotes: [{ freq, dur, wave }] } }` or `false`.\n- The PLAYER's own sound / volume / \"fewer animations\" live on the device (the profile module draws\n  them):\n  `const [prefs, setPrefs] = usePlayerPrefs()` → `{ muted, volume, reducedMotion }`.\n\n## Features: screens that find each other\n\nA module registers a **feature**; whoever draws the menu shows it — the base's lobby as tabs (phone:\n4 + \"More\", tablet: more, desktop: a side rail; the base takes the shared-UI role `\"menu\"`), or the\nhost's floating ☰ when nobody takes the role. Tab order and main tabs can be overridden in\n`src/app.config.ts` (`lobby.order`, `lobby.primary`).\n\n```ts\n// module.ts\nsetup(ctx) {\n  ctx.features.register({\n    id: \"forge\", label: \"Forge\", icon: \"hammer\", group: \"economy\", order: 60,\n    primary: false,          // true = a main tab of the lobby\n    Screen: ForgeScreen,     // (props: FeatureScreenProps) => ReactNode; props.args, props.close()\n    available: false,        // hidden until the title has something for it — see below\n  });\n  // Badge (\"something to claim\"): ctx.features.setBadge(\"forge\", 2)\n  // The title has forge recipes → show the tab; the reason is for the AI Coder's agent only:\n  ctx.features.setAvailable(\"forge\", hasRecipes(configSection(ctx.client, \"Craft\")), \"no forge recipes\");\n}\n```\n\n- Open another module's screen without importing it: `ctx.features.open(\"store\")`,\n  `ctx.features.open(\"chat\", { userID })`. It returns `false` when the module is not installed or its\n  tab is hidden (`ctx.features.get(\"store\")?.available`). From a game (the lobby is off screen) the\n  host shows the screen in a window.\n- A screen that depends on title data registers with `available: false` and calls\n  `ctx.features.setAvailable(id, ok, reason)` once it knows — from the client config\n  (`configSection(client, \"Store\")`) or a read it makes anyway (a badge watcher); no extra request\n  at start-up: every module's first reads arrive together and brush the per-player rate limit.\n- Groups: `economy`, `events`, `social`, `profile`. Icons are kit glyph names (`shop`, `hero`,\n  `bag`, `trophy`, `gift`, `hammer`, `market`, `offer`, `flame`, `friends`, `chat`, `link`,\n  `swords`, `user`, `bulb`, …) or an image URL.\n- Something that must be on screen all the time (a daily auto-popup, a badge watcher, an overlay) is\n  a panel: `ctx.registerPanel({ id, slot: \"modal\", activeOnly: false, component })`.\n\n## Building a screen on the kit\n\nKeep the screen a short list; put every detail in a **popup**.\n\n```tsx\nimport {\n  Button,\n  Popup,\n  ResourceList,\n  Tabs,\n  useCelebrate,\n  useToast,\n  useUiKit,\n  errorText,\n  grantedBy,\n  panel,\n  outlined,\n  v,\n} from \"@idosgames/react/ui\";\n\nfunction ForgeScreen(): ReactNode {\n  const [open, setOpen] = useState<string | null>(null);\n  return (\n    <div\n      style={{\n        display: \"grid\",\n        gridTemplateColumns: \"minmax(0, 1fr)\",\n        gap: 12,\n      }}\n    >\n      {/* rows… onClick={() => setOpen(id)} */}\n      {open ? (\n        <Popup title=\"Forge\" onClose={() => setOpen(null)} width={420}>\n          …\n        </Popup>\n      ) : null}\n    </div>\n  );\n}\n```\n\n- `Popup` is a bottom sheet on a phone and a centred window elsewhere (`variant=\"center\"` forces\n  centred); it animates in and out and plays open/close sounds. Close from inside with\n  `usePopupClose()`. `ConfirmPopup` for yes/no. A popup that opens BY ITSELF (not on a tap) passes\n  `queued` — auto-popups then show one at a time instead of stacking.\n- `useCelebrate()(lines)` shows \"You got\" and flies the icons to any element marked\n  `data-resource-counter=\"{currencyID}\"` (the lobby's balances are). Build the lines\n  from a response with `grantedBy(data)`; a reward with premium (VIP) bundles needs them added.\n- `useUiKit().play(\"claim\")`, `useUiKit().fx.burst(element)` — a sound and a particle burst.\n- **Notifications — `useNotify()`** (the same system as a module's `ctx.notifications`):\n  `notify.toast({ level: \"success\", title: \"Saved\" })` — a toast at the top that goes by itself;\n  `await notify.alert({ level: \"warning\", title, message, actions })` — a window the player must\n  answer, queued one at a time. Levels `info | success | warning | error | reward` pick the colour,\n  icon, sound and how long a toast stays (errors longest). `icon` (a glyph, emoji or URL), `image` (a\n  thumbnail / a big picture in the window), `source` (a feature id — its name on the card, a tap opens\n  it), `key` (the same key replaces instead of stacking; identical toasts merge into \"×2\"),\n  `duration` (`0` — until closed), `actions`. Refusals: `notify.toast({ level: \"error\", message:\nerrorText(res.error) })`; never re-check server rules. `useToast()(text, kind)` is the old short\n  form of the same thing.\n- Lines of resources: `grantLines(grant)`, `costLines(cost)`, `bundleLines(bundle)`,\n  `canAfford(lines, balances)`, `<ResourceList lines={…} />`. Names and icons: `useCatalog()`.\n- Words: `makeT(EN, RU)` for your strings, `plural(n, \"лот|лота|лотов\")` for counts.\n- ⚠ A root `display: grid` with a wide child (a row of tabs) grows past a phone screen — give it\n  `gridTemplateColumns: \"minmax(0, 1fr)\"`.\n- ⚠ **No colour literals in a screen** (`\"#fff\"`, `\"rgba(0,0,0,.3)\"`, `\"#5a3fd0\"`): they break the\n  moment the theme changes (white text on a light panel, a black stripe under a pastel button). Use\n  the tokens: text `v.text` / `v.textDim` (or `...outlined`), surfaces `panel` / `well` / `v.wellSoft`,\n  lines `v.line`, dimming `v.backdrop`. A coloured banner, \"your row\", a highlighted day →\n  `...toneSurface(\"blue\" | \"green\" | \"gold\" | \"red\")`: it fills with that tone AND switches the text\n  inside it to the tone's own readable colour. Text on a filled button — `ON_TONE[tone]`. A blend:\n  `` `color-mix(in srgb, ${v.gold} 20%, transparent)` ``.\n\n## Tutorial hints\n\nThe `tutorials` module highlights any element marked `data-tutorial-anchor=\"…\"` — the lobby's tabs\nare `tab:{featureID}`, its profile button `lobby:profile`, its wallet `lobby:wallet`, a game's \"Play\"\nbutton `play:{modeID}`. Mark the controls of your own screen the same\nway; the publisher points tutorial steps at them in LiveOps (Tutorial → step → AnchorID).\n",
   "references": []
 }