@idosgames/module-sdk 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -1 +1 @@
-'use strict';var S=/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*@[1-9]\d*$/;function x(e){return typeof e=="string"&&S.test(e)}function M(e){let t=e.indexOf(":");return t<0?"":e.slice(0,t)}var l=/^(string|number|boolean)(\[\])?(\?)?$/;function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function c(e,t){return e==="number"?typeof t=="number"&&Number.isFinite(t):typeof t===e}function f(e,t,r){if(!u(t))return `${r||"payload"} must be an object`;for(let[n,o]of Object.entries(e)){let i=r?`${r}.${n}`:n,a=t[n];if(typeof o!="string"){let p=f(o,a,i);if(p)return p;continue}let d=l.exec(o);if(!d)return `${i}: invalid descriptor "${o}"`;let[,s="",g,m]=d;if(a===void 0){if(m)continue;return `${i} is missing`}if(g){if(!Array.isArray(a))return `${i} must be ${s}[]`;if(!a.every(p=>c(s,p)))return `${i} must contain only ${s} values`;continue}if(!c(s,a))return `${i} must be a ${s}`}return null}function y(e,t){for(let[r,n]of Object.entries(e)){let o=t?`${t}.${r}`:r;if(typeof n=="string"){if(!l.test(n))throw new Error(`shape(): field "${o}" has invalid type "${n}" \u2014 use "string" | "number" | "boolean", optionally with "[]" and/or a trailing "?"`)}else if(u(n))y(n,o);else throw new Error(`shape(): field "${o}" must be a type string or an object`)}}function h(e){return y(e,""),{descriptor:e,check:t=>f(e,t,"")}}function v(e,t){if(!x(e))throw new Error(`defineTopic(): "${e}" is not a valid topic name \u2014 expected "<module-id>:<event>@<major>", e.g. "idle-rpg:character-upgraded@1"`);return {name:e,shape:t}}var E={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var T=["currency-bar","wallet","status","account","menu"];function w(e){return typeof e=="string"&&T.includes(e)}function R(e){return e}exports.SHARED_UI_ROLES=T;exports.TOPIC_NAME_RE=S;exports.defineModule=R;exports.defineTopic=v;exports.hostTopics=E;exports.isSharedUiRole=w;exports.isTopicName=x;exports.shape=h;exports.topicNamespace=M;
+'use strict';var x=/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*@[1-9]\d*$/;function S(e){return typeof e=="string"&&x.test(e)}function T(e){let t=e.indexOf(":");return t<0?"":e.slice(0,t)}var c=/^(string|number|boolean)(\[\])?(\?)?$/;function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function l(e,t){return e==="number"?typeof t=="number"&&Number.isFinite(t):typeof t===e}function f(e,t,o){if(!u(t))return `${o||"payload"} must be an object`;for(let[n,r]of Object.entries(e)){let i=o?`${o}.${n}`:n,a=t[n];if(typeof r!="string"){let p=f(r,a,i);if(p)return p;continue}let d=c.exec(r);if(!d)return `${i}: invalid descriptor "${r}"`;let[,s="",g,m]=d;if(a===void 0){if(m)continue;return `${i} is missing`}if(g){if(!Array.isArray(a))return `${i} must be ${s}[]`;if(!a.every(p=>l(s,p)))return `${i} must contain only ${s} values`;continue}if(!l(s,a))return `${i} must be a ${s}`}return null}function y(e,t){for(let[o,n]of Object.entries(e)){let r=t?`${t}.${o}`:o;if(typeof n=="string"){if(!c.test(n))throw new Error(`shape(): field "${r}" has invalid type "${n}" \u2014 use "string" | "number" | "boolean", optionally with "[]" and/or a trailing "?"`)}else if(u(n))y(n,r);else throw new Error(`shape(): field "${r}" must be a type string or an object`)}}function h(e){return y(e,""),{descriptor:e,check:t=>f(e,t,"")}}function v(e,t){if(!S(e))throw new Error(`defineTopic(): "${e}" is not a valid topic name \u2014 expected "<module-id>:<event>@<major>", e.g. "idle-rpg:character-upgraded@1"`);return {name:e,shape:t}}var b={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var M=["currency-bar","wallet","status","account","menu","modes"];function R(e){return typeof e=="string"&&M.includes(e)}function D(e){return e}exports.SHARED_UI_ROLES=M;exports.TOPIC_NAME_RE=x;exports.defineModule=D;exports.defineTopic=v;exports.hostTopics=b;exports.isSharedUiRole=R;exports.isTopicName=S;exports.shape=h;exports.topicNamespace=T;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { IDosGamesClient } from '@idosgames/core';
+import { RealtimeSession, IDosGamesClient } from '@idosgames/core';
 export { IDosGamesClient, SdkEvents } from '@idosgames/core';
 import { ComponentType } from 'react';
 
@@ -111,7 +111,7 @@ interface ModuleEventsManifest {
  * each one has to mean the same thing across the whole catalog. A new role is a minor release of
  * this package; anything that does not fit a role is plain events + SDK data.
  */
-declare const SHARED_UI_ROLES: readonly ["currency-bar", "wallet", "status", "account", "menu"];
+declare const SHARED_UI_ROLES: readonly ["currency-bar", "wallet", "status", "account", "menu", "modes"];
 type SharedUiRole = (typeof SHARED_UI_ROLES)[number];
 /** Static declaration on a module (`Module.sharedUi`). */
 interface ModuleSharedUi {
@@ -125,8 +125,8 @@ interface ModuleSharedUi {
     /**
      * Roles this module draws INSIDE ITS OWN MODE while nobody `provides` them for everybody — a
      * template with a full-screen UI (bottom tab bar) puts "Log out" and the player's ID into its own
-     * header instead of having the host float them over its layout. Only "account" and "menu" are
-     * host-drawn, so those are the roles this matters for: the host hides its floating copy while this
+     * header instead of having the host float them over its layout. Only "account", "menu" and "modes"
+     * are host-drawn, so those are the roles this matters for: the host hides its floating copy while this
      * module's mode is on screen and keeps drawing it in every other mode. `shouldDraw` of every module
      * is unchanged.
      */
@@ -215,7 +215,7 @@ interface FeatureScreenProps {
     close(): void;
 }
 interface FeatureDefinition {
-    /** Unique across the game — conventionally the owning module's id without "-ui" ("store"). */
+    /** Unique across the game — conventionally the owning module's id ("store"). */
     id: string;
     /** Menu label, already in the player's language. */
     label: string;
@@ -228,17 +228,27 @@ interface FeatureDefinition {
     primary?: boolean;
     /** The screen. Rendered by the presenter, inside the kit provider and the client provider. */
     Screen: ComponentType<FeatureScreenProps>;
+    /**
+     * Whether the title has something for this screen yet. Default `true`. A screen that depends on
+     * title data (a shop without offers is an empty tab) registers with `false` and calls
+     * `setAvailable(id, true)` once it has checked — so the tab never flashes in and out.
+     */
+    available?: boolean;
 }
-/** A registered feature plus its live badge. */
+/** A registered feature plus its live badge and availability. */
 interface FeatureEntry extends FeatureDefinition {
     badge: number;
     /** The module that registered it. */
     moduleId: string;
+    /** Menus list only available features; `open()` of an unavailable one is refused. */
+    available: boolean;
+    /** Why it is hidden, in plain words — shown to the AI Coder's agent, never to players. */
+    unavailableReason?: string;
 }
 /**
  * Shows a feature's screen. The menu owner registers one; the most recent presenter wins, and
  * unregistering hands the job back to the previous one (the lobby unmounts when the player switches
- * to another mode → the HUD's ☰ or the host's button presents again).
+ * to a game → the host's window presents again).
  */
 type FeaturePresenter = (id: string, args?: Record<string, unknown>) => boolean;
 /** `ctx.features` — the registry of the game's features, shared by every module of the session. */
@@ -248,16 +258,105 @@ interface FeatureRegistry {
     /** Features in registration order (menus sort them themselves). */
     list(): FeatureEntry[];
     get(id: string): FeatureEntry | undefined;
-    /** Opens a feature's screen through the current presenter. `false` — no such feature or no presenter. */
+    /**
+     * Opens a feature's screen through the current presenter. `false` — no such feature, it is not
+     * available on this title, or no presenter.
+     */
     open(id: string, args?: Record<string, unknown>): boolean;
     /** The "something to claim" counter of a feature; 0 hides it. */
     setBadge(id: string, count: number): void;
+    /**
+     * Show or hide a feature by what the title has (see `FeatureDefinition.available`). `reason` says
+     * why it is hidden ("no store offers configured on the title") — the agent reads it.
+     */
+    setAvailable(id: string, available: boolean, reason?: string): void;
     /** Called on every registration, removal and badge change. */
     subscribe(listener: () => void): () => void;
     /** For menu owners: become the one who shows screens. Returns an unregister function. */
     setPresenter(presenter: FeaturePresenter): () => void;
 }
 
+/** A room setting the host picks when creating a room for the game (guest mode, cheats…). */
+interface MultiplayerSetting {
+    /** Key in `MultiplayerRoom.settings`. */
+    id: string;
+    /** Label, already in the player's language. */
+    label: string;
+    /** A choice of options, or an on/off switch. */
+    kind: "choice" | "toggle";
+    /** For `choice`: value + label of every option. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Value when the host does not change it. */
+    default: string | boolean;
+}
+/** What a game declares about playing online (`ctx.multiplayer.registerGame`). */
+interface MultiplayerGame {
+    /** The game's mode (its route id) — the room's game and where "Play" takes the room. */
+    mode: string;
+    /** Label of the game in the rooms screen; defaults to the route's label. */
+    label?: string;
+    /**
+     * Who connects to whom: `"Host"` (star — the host links to everyone, the others only to the host)
+     * or `"Mesh"` (everyone to everyone). Default `"Mesh"`.
+     */
+    topology?: "Host" | "Mesh";
+    /**
+     * `"P2P"` — the game has its own chat over the DataChannels, the lobby draws none;
+     * `"ServerRelay"` (default) — the lobby's room chat goes through the server.
+     */
+    chatMode?: "P2P" | "ServerRelay";
+    /** Most players in one room (the title's limit caps it). Default 8. */
+    maxPlayers?: number;
+    /**
+     * A player may join a room whose game is already running — the rooms screen lets them in and
+     * `start` gets called for them right away (the game's own "late joiner" path). Default `false`.
+     */
+    joinInProgress?: boolean;
+    /** Room settings the host picks on creation; the game reads them in `room.settings`. */
+    settings?: MultiplayerSetting[];
+    /**
+     * The room goes into this game: switch the game to network play over `room.session`. Called on
+     * EVERY member's device (the host's first) — after the app switched to the game's mode.
+     */
+    start(room: MultiplayerRoom): void | Promise<void>;
+}
+/** The room handed to a game. */
+interface MultiplayerRoom {
+    /** The live session — links, messages, members, host changes. Opened by the rooms system. */
+    readonly session: RealtimeSession;
+    /** The game's mode. */
+    readonly mode: string;
+    /** Whether this player created the game (the host at start). Live host: `session.hostId`. */
+    readonly isHost: boolean;
+    /** The room's settings as the host picked them (defaults filled in). */
+    readonly settings: Readonly<Record<string, string | boolean>>;
+    /**
+     * The game joins a running room (`joinInProgress`) rather than starting together with it.
+     */
+    readonly lateJoin: boolean;
+    /** Leave the room for good: closes the session and the rooms screen forgets it. */
+    leave(): Promise<void>;
+}
+/** What `ctx.features.open("multiplayer", args)` understands. */
+interface MultiplayerScreenArgs {
+    /** Show only this game's rooms and preselect it in "Create a room". */
+    mode?: string;
+    /** Open straight on "Create a room" (a game's "Open for friends"). */
+    create?: boolean;
+}
+/** `ctx.multiplayer` — the host's registry of games that play online, shared by every module. */
+interface MultiplayerRegistry {
+    /** A game declares that it plays online. Returns an unregister function. */
+    registerGame(game: MultiplayerGame): () => void;
+    getGame(mode: string): MultiplayerGame | undefined;
+    listGames(): MultiplayerGame[];
+    /** Called when a game is registered or removed. */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -309,6 +408,20 @@ interface ModuleManifest {
      * `"feature"`.
      */
     type?: "template" | "feature";
+    /**
+     * Part of the base: the platform installs this system into EVERY new project together with the base
+     * (sign-in + the lobby) — only profile, inventory, invite, friends, quests and mailbox (owner's rule
+     * 29.09.2026). Every other module is installed only when it is needed: a game brings the ones it
+     * `uses`, the AI Coder installs any other one as soon as the task needs what it `provides`. A creator removes it like any module.
+     */
+    inBase?: boolean;
+    /**
+     * A game's modules: catalog ids of the systems this game plugs into (`ctx.multiplayer` →
+     * `"multiplayer"`, `ctx.content` → `"workshop"`, …). The platform installs them together with the game
+     * — a new title on this game gets them, and so does a project the AI Coder adds the game to.
+     * `npm run check` makes a module that registers in `ctx.multiplayer` / `ctx.content` list them.
+     */
+    uses?: string[];
     /** Overrides the catalog display name; defaults to `ModuleMeta.name` from `module.ts`. */
     name?: string;
     /** One-line pitch shown on the catalog card. */
@@ -409,8 +522,20 @@ interface ModuleContext {
      */
     features: FeatureRegistry;
     /**
-     * Switch the host to another mode (a route id registered by any module) — e.g. the Workshop opens a
-     * world and hands the screen to the game. Unknown ids are ignored.
+     * Games that play online and the rooms system that runs them (see `MultiplayerGame`). A game
+     * registers here (`registerGame`) and takes the room in `start`; it never creates or joins rooms
+     * itself. Without the multiplayer system installed nothing ever calls `start`.
+     */
+    multiplayer: MultiplayerRegistry;
+    /**
+     * The app's modes — every route any module registered, and which one is on screen. The lobby
+     * builds its "Play" buttons from it; a game can tell whether a lobby exists to return to.
+     */
+    modes: ModeRegistry;
+    /**
+     * Switch the host to another mode (a route id registered by any module) — e.g. the lobby starts a
+     * game, the Workshop opens a world and hands the screen to the game. Unknown ids are ignored. Called
+     * inside `setup()` it picks the mode the app starts in.
      */
     navigate(modeId: string): void;
     /**
@@ -535,6 +660,30 @@ interface RouteEntry {
     icon?: string;
     order?: number;
 }
+/** A mode of the app as every module sees it (`ctx.modes`): a registered route plus its owner. */
+interface ModeEntry {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Resolved order (0 when the route gave none); the list is sorted by it. */
+    order: number;
+    /** The module that registered the route. */
+    moduleId: string;
+    /** That module's `meta.type` — a lobby offers "Play" for `game` modes. */
+    moduleType: ModuleType;
+}
+/** `ctx.modes` — the modes of the app, live. Switch with `ctx.navigate(id)`. */
+interface ModeRegistry {
+    /**
+     * Every mode, sorted by `order`. Filled once every module's `setup()` has run — read it at render
+     * time or subscribe, not inside `setup()`.
+     */
+    list(): ModeEntry[];
+    /** The mode on screen; `null` until the app is shown. */
+    current(): string | null;
+    /** Called when the list or the current mode changes. Returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
 /**
  * @deprecated The pre-0.2 string-topic bus. `ctx.events` is now `ModuleEvents` (typed topic tokens,
  * see `defineTopic`); this type stays only so older code that named it still compiles.
@@ -547,4 +696,4 @@ interface SharedEventBus<Events extends Record<string, unknown> = Record<string,
 /** Identity helper that pins a module literal to the `Module` type for editor help and errors. */
 declare function defineModule(module: Module): Module;
 
-export { type CapturedContent, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type FeatureDefinition, type FeatureEntry, type FeatureGroup, type FeaturePresenter, type FeatureRegistry, type FeatureScreenProps, type InferShape, type LocalContentItem, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };
+export { type CapturedContent, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type FeatureDefinition, type FeatureEntry, type FeatureGroup, type FeaturePresenter, type FeatureRegistry, type FeatureScreenProps, type InferShape, type LocalContentItem, type ModeEntry, type ModeRegistry, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type MultiplayerGame, type MultiplayerRegistry, type MultiplayerRoom, type MultiplayerScreenArgs, type MultiplayerSetting, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { IDosGamesClient } from '@idosgames/core';
+import { RealtimeSession, IDosGamesClient } from '@idosgames/core';
 export { IDosGamesClient, SdkEvents } from '@idosgames/core';
 import { ComponentType } from 'react';
 
@@ -111,7 +111,7 @@ interface ModuleEventsManifest {
  * each one has to mean the same thing across the whole catalog. A new role is a minor release of
  * this package; anything that does not fit a role is plain events + SDK data.
  */
-declare const SHARED_UI_ROLES: readonly ["currency-bar", "wallet", "status", "account", "menu"];
+declare const SHARED_UI_ROLES: readonly ["currency-bar", "wallet", "status", "account", "menu", "modes"];
 type SharedUiRole = (typeof SHARED_UI_ROLES)[number];
 /** Static declaration on a module (`Module.sharedUi`). */
 interface ModuleSharedUi {
@@ -125,8 +125,8 @@ interface ModuleSharedUi {
     /**
      * Roles this module draws INSIDE ITS OWN MODE while nobody `provides` them for everybody — a
      * template with a full-screen UI (bottom tab bar) puts "Log out" and the player's ID into its own
-     * header instead of having the host float them over its layout. Only "account" and "menu" are
-     * host-drawn, so those are the roles this matters for: the host hides its floating copy while this
+     * header instead of having the host float them over its layout. Only "account", "menu" and "modes"
+     * are host-drawn, so those are the roles this matters for: the host hides its floating copy while this
      * module's mode is on screen and keeps drawing it in every other mode. `shouldDraw` of every module
      * is unchanged.
      */
@@ -215,7 +215,7 @@ interface FeatureScreenProps {
     close(): void;
 }
 interface FeatureDefinition {
-    /** Unique across the game — conventionally the owning module's id without "-ui" ("store"). */
+    /** Unique across the game — conventionally the owning module's id ("store"). */
     id: string;
     /** Menu label, already in the player's language. */
     label: string;
@@ -228,17 +228,27 @@ interface FeatureDefinition {
     primary?: boolean;
     /** The screen. Rendered by the presenter, inside the kit provider and the client provider. */
     Screen: ComponentType<FeatureScreenProps>;
+    /**
+     * Whether the title has something for this screen yet. Default `true`. A screen that depends on
+     * title data (a shop without offers is an empty tab) registers with `false` and calls
+     * `setAvailable(id, true)` once it has checked — so the tab never flashes in and out.
+     */
+    available?: boolean;
 }
-/** A registered feature plus its live badge. */
+/** A registered feature plus its live badge and availability. */
 interface FeatureEntry extends FeatureDefinition {
     badge: number;
     /** The module that registered it. */
     moduleId: string;
+    /** Menus list only available features; `open()` of an unavailable one is refused. */
+    available: boolean;
+    /** Why it is hidden, in plain words — shown to the AI Coder's agent, never to players. */
+    unavailableReason?: string;
 }
 /**
  * Shows a feature's screen. The menu owner registers one; the most recent presenter wins, and
  * unregistering hands the job back to the previous one (the lobby unmounts when the player switches
- * to another mode → the HUD's ☰ or the host's button presents again).
+ * to a game → the host's window presents again).
  */
 type FeaturePresenter = (id: string, args?: Record<string, unknown>) => boolean;
 /** `ctx.features` — the registry of the game's features, shared by every module of the session. */
@@ -248,16 +258,105 @@ interface FeatureRegistry {
     /** Features in registration order (menus sort them themselves). */
     list(): FeatureEntry[];
     get(id: string): FeatureEntry | undefined;
-    /** Opens a feature's screen through the current presenter. `false` — no such feature or no presenter. */
+    /**
+     * Opens a feature's screen through the current presenter. `false` — no such feature, it is not
+     * available on this title, or no presenter.
+     */
     open(id: string, args?: Record<string, unknown>): boolean;
     /** The "something to claim" counter of a feature; 0 hides it. */
     setBadge(id: string, count: number): void;
+    /**
+     * Show or hide a feature by what the title has (see `FeatureDefinition.available`). `reason` says
+     * why it is hidden ("no store offers configured on the title") — the agent reads it.
+     */
+    setAvailable(id: string, available: boolean, reason?: string): void;
     /** Called on every registration, removal and badge change. */
     subscribe(listener: () => void): () => void;
     /** For menu owners: become the one who shows screens. Returns an unregister function. */
     setPresenter(presenter: FeaturePresenter): () => void;
 }
 
+/** A room setting the host picks when creating a room for the game (guest mode, cheats…). */
+interface MultiplayerSetting {
+    /** Key in `MultiplayerRoom.settings`. */
+    id: string;
+    /** Label, already in the player's language. */
+    label: string;
+    /** A choice of options, or an on/off switch. */
+    kind: "choice" | "toggle";
+    /** For `choice`: value + label of every option. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Value when the host does not change it. */
+    default: string | boolean;
+}
+/** What a game declares about playing online (`ctx.multiplayer.registerGame`). */
+interface MultiplayerGame {
+    /** The game's mode (its route id) — the room's game and where "Play" takes the room. */
+    mode: string;
+    /** Label of the game in the rooms screen; defaults to the route's label. */
+    label?: string;
+    /**
+     * Who connects to whom: `"Host"` (star — the host links to everyone, the others only to the host)
+     * or `"Mesh"` (everyone to everyone). Default `"Mesh"`.
+     */
+    topology?: "Host" | "Mesh";
+    /**
+     * `"P2P"` — the game has its own chat over the DataChannels, the lobby draws none;
+     * `"ServerRelay"` (default) — the lobby's room chat goes through the server.
+     */
+    chatMode?: "P2P" | "ServerRelay";
+    /** Most players in one room (the title's limit caps it). Default 8. */
+    maxPlayers?: number;
+    /**
+     * A player may join a room whose game is already running — the rooms screen lets them in and
+     * `start` gets called for them right away (the game's own "late joiner" path). Default `false`.
+     */
+    joinInProgress?: boolean;
+    /** Room settings the host picks on creation; the game reads them in `room.settings`. */
+    settings?: MultiplayerSetting[];
+    /**
+     * The room goes into this game: switch the game to network play over `room.session`. Called on
+     * EVERY member's device (the host's first) — after the app switched to the game's mode.
+     */
+    start(room: MultiplayerRoom): void | Promise<void>;
+}
+/** The room handed to a game. */
+interface MultiplayerRoom {
+    /** The live session — links, messages, members, host changes. Opened by the rooms system. */
+    readonly session: RealtimeSession;
+    /** The game's mode. */
+    readonly mode: string;
+    /** Whether this player created the game (the host at start). Live host: `session.hostId`. */
+    readonly isHost: boolean;
+    /** The room's settings as the host picked them (defaults filled in). */
+    readonly settings: Readonly<Record<string, string | boolean>>;
+    /**
+     * The game joins a running room (`joinInProgress`) rather than starting together with it.
+     */
+    readonly lateJoin: boolean;
+    /** Leave the room for good: closes the session and the rooms screen forgets it. */
+    leave(): Promise<void>;
+}
+/** What `ctx.features.open("multiplayer", args)` understands. */
+interface MultiplayerScreenArgs {
+    /** Show only this game's rooms and preselect it in "Create a room". */
+    mode?: string;
+    /** Open straight on "Create a room" (a game's "Open for friends"). */
+    create?: boolean;
+}
+/** `ctx.multiplayer` — the host's registry of games that play online, shared by every module. */
+interface MultiplayerRegistry {
+    /** A game declares that it plays online. Returns an unregister function. */
+    registerGame(game: MultiplayerGame): () => void;
+    getGame(mode: string): MultiplayerGame | undefined;
+    listGames(): MultiplayerGame[];
+    /** Called when a game is registered or removed. */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -309,6 +408,20 @@ interface ModuleManifest {
      * `"feature"`.
      */
     type?: "template" | "feature";
+    /**
+     * Part of the base: the platform installs this system into EVERY new project together with the base
+     * (sign-in + the lobby) — only profile, inventory, invite, friends, quests and mailbox (owner's rule
+     * 29.09.2026). Every other module is installed only when it is needed: a game brings the ones it
+     * `uses`, the AI Coder installs any other one as soon as the task needs what it `provides`. A creator removes it like any module.
+     */
+    inBase?: boolean;
+    /**
+     * A game's modules: catalog ids of the systems this game plugs into (`ctx.multiplayer` →
+     * `"multiplayer"`, `ctx.content` → `"workshop"`, …). The platform installs them together with the game
+     * — a new title on this game gets them, and so does a project the AI Coder adds the game to.
+     * `npm run check` makes a module that registers in `ctx.multiplayer` / `ctx.content` list them.
+     */
+    uses?: string[];
     /** Overrides the catalog display name; defaults to `ModuleMeta.name` from `module.ts`. */
     name?: string;
     /** One-line pitch shown on the catalog card. */
@@ -409,8 +522,20 @@ interface ModuleContext {
      */
     features: FeatureRegistry;
     /**
-     * Switch the host to another mode (a route id registered by any module) — e.g. the Workshop opens a
-     * world and hands the screen to the game. Unknown ids are ignored.
+     * Games that play online and the rooms system that runs them (see `MultiplayerGame`). A game
+     * registers here (`registerGame`) and takes the room in `start`; it never creates or joins rooms
+     * itself. Without the multiplayer system installed nothing ever calls `start`.
+     */
+    multiplayer: MultiplayerRegistry;
+    /**
+     * The app's modes — every route any module registered, and which one is on screen. The lobby
+     * builds its "Play" buttons from it; a game can tell whether a lobby exists to return to.
+     */
+    modes: ModeRegistry;
+    /**
+     * Switch the host to another mode (a route id registered by any module) — e.g. the lobby starts a
+     * game, the Workshop opens a world and hands the screen to the game. Unknown ids are ignored. Called
+     * inside `setup()` it picks the mode the app starts in.
      */
     navigate(modeId: string): void;
     /**
@@ -535,6 +660,30 @@ interface RouteEntry {
     icon?: string;
     order?: number;
 }
+/** A mode of the app as every module sees it (`ctx.modes`): a registered route plus its owner. */
+interface ModeEntry {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Resolved order (0 when the route gave none); the list is sorted by it. */
+    order: number;
+    /** The module that registered the route. */
+    moduleId: string;
+    /** That module's `meta.type` — a lobby offers "Play" for `game` modes. */
+    moduleType: ModuleType;
+}
+/** `ctx.modes` — the modes of the app, live. Switch with `ctx.navigate(id)`. */
+interface ModeRegistry {
+    /**
+     * Every mode, sorted by `order`. Filled once every module's `setup()` has run — read it at render
+     * time or subscribe, not inside `setup()`.
+     */
+    list(): ModeEntry[];
+    /** The mode on screen; `null` until the app is shown. */
+    current(): string | null;
+    /** Called when the list or the current mode changes. Returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
 /**
  * @deprecated The pre-0.2 string-topic bus. `ctx.events` is now `ModuleEvents` (typed topic tokens,
  * see `defineTopic`); this type stays only so older code that named it still compiles.
@@ -547,4 +696,4 @@ interface SharedEventBus<Events extends Record<string, unknown> = Record<string,
 /** Identity helper that pins a module literal to the `Module` type for editor help and errors. */
 declare function defineModule(module: Module): Module;
 
-export { type CapturedContent, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type FeatureDefinition, type FeatureEntry, type FeatureGroup, type FeaturePresenter, type FeatureRegistry, type FeatureScreenProps, type InferShape, type LocalContentItem, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };
+export { type CapturedContent, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type FeatureDefinition, type FeatureEntry, type FeatureGroup, type FeaturePresenter, type FeatureRegistry, type FeatureScreenProps, type InferShape, type LocalContentItem, type ModeEntry, type ModeRegistry, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type MultiplayerGame, type MultiplayerRegistry, type MultiplayerRoom, type MultiplayerScreenArgs, type MultiplayerSetting, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };

package/dist/index.js

@@ -1 +1 @@
-var S=/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*@[1-9]\d*$/;function x(e){return typeof e=="string"&&S.test(e)}function M(e){let t=e.indexOf(":");return t<0?"":e.slice(0,t)}var l=/^(string|number|boolean)(\[\])?(\?)?$/;function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function c(e,t){return e==="number"?typeof t=="number"&&Number.isFinite(t):typeof t===e}function f(e,t,r){if(!u(t))return `${r||"payload"} must be an object`;for(let[n,o]of Object.entries(e)){let i=r?`${r}.${n}`:n,a=t[n];if(typeof o!="string"){let p=f(o,a,i);if(p)return p;continue}let d=l.exec(o);if(!d)return `${i}: invalid descriptor "${o}"`;let[,s="",g,m]=d;if(a===void 0){if(m)continue;return `${i} is missing`}if(g){if(!Array.isArray(a))return `${i} must be ${s}[]`;if(!a.every(p=>c(s,p)))return `${i} must contain only ${s} values`;continue}if(!c(s,a))return `${i} must be a ${s}`}return null}function y(e,t){for(let[r,n]of Object.entries(e)){let o=t?`${t}.${r}`:r;if(typeof n=="string"){if(!l.test(n))throw new Error(`shape(): field "${o}" has invalid type "${n}" \u2014 use "string" | "number" | "boolean", optionally with "[]" and/or a trailing "?"`)}else if(u(n))y(n,o);else throw new Error(`shape(): field "${o}" must be a type string or an object`)}}function h(e){return y(e,""),{descriptor:e,check:t=>f(e,t,"")}}function v(e,t){if(!x(e))throw new Error(`defineTopic(): "${e}" is not a valid topic name \u2014 expected "<module-id>:<event>@<major>", e.g. "idle-rpg:character-upgraded@1"`);return {name:e,shape:t}}var E={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var T=["currency-bar","wallet","status","account","menu"];function w(e){return typeof e=="string"&&T.includes(e)}function R(e){return e}export{T as SHARED_UI_ROLES,S as TOPIC_NAME_RE,R as defineModule,v as defineTopic,E as hostTopics,w as isSharedUiRole,x as isTopicName,h as shape,M as topicNamespace};
+var x=/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*@[1-9]\d*$/;function S(e){return typeof e=="string"&&x.test(e)}function T(e){let t=e.indexOf(":");return t<0?"":e.slice(0,t)}var c=/^(string|number|boolean)(\[\])?(\?)?$/;function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function l(e,t){return e==="number"?typeof t=="number"&&Number.isFinite(t):typeof t===e}function f(e,t,o){if(!u(t))return `${o||"payload"} must be an object`;for(let[n,r]of Object.entries(e)){let i=o?`${o}.${n}`:n,a=t[n];if(typeof r!="string"){let p=f(r,a,i);if(p)return p;continue}let d=c.exec(r);if(!d)return `${i}: invalid descriptor "${r}"`;let[,s="",g,m]=d;if(a===void 0){if(m)continue;return `${i} is missing`}if(g){if(!Array.isArray(a))return `${i} must be ${s}[]`;if(!a.every(p=>l(s,p)))return `${i} must contain only ${s} values`;continue}if(!l(s,a))return `${i} must be a ${s}`}return null}function y(e,t){for(let[o,n]of Object.entries(e)){let r=t?`${t}.${o}`:o;if(typeof n=="string"){if(!c.test(n))throw new Error(`shape(): field "${r}" has invalid type "${n}" \u2014 use "string" | "number" | "boolean", optionally with "[]" and/or a trailing "?"`)}else if(u(n))y(n,r);else throw new Error(`shape(): field "${r}" must be a type string or an object`)}}function h(e){return y(e,""),{descriptor:e,check:t=>f(e,t,"")}}function v(e,t){if(!S(e))throw new Error(`defineTopic(): "${e}" is not a valid topic name \u2014 expected "<module-id>:<event>@<major>", e.g. "idle-rpg:character-upgraded@1"`);return {name:e,shape:t}}var b={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var M=["currency-bar","wallet","status","account","menu","modes"];function R(e){return typeof e=="string"&&M.includes(e)}function D(e){return e}export{M as SHARED_UI_ROLES,x as TOPIC_NAME_RE,D as defineModule,v as defineTopic,b as hostTopics,R as isSharedUiRole,S as isTopicName,h as shape,T as topicNamespace};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@idosgames/module-sdk",
-  "version": "0.5.0",
-  "description": "The composable-module contract for the iDosGames host shell: Module / ModuleContext types plus tiny authoring helpers. Framework-neutral at runtime — a module can be a game (Three/Phaser), a plain app, or an AI app.",
+  "version": "0.7.0",
+  "description": "The composable-module contract for the iDosGames host shell: Module / ModuleContext types plus tiny authoring helpers. Framework-neutral at runtime — a module can be a game (Three/Phaser), a plain app, or an AI app.",
   "type": "module",
   "license": "MIT",
   "author": "iDos Games",
@@ -44,7 +44,7 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
-  "//": "@idosgames/core is a real range, not '*': a published contract must name the version of core whose IDosGamesClient/SdkEvents shapes it references. Bump in step with core (see RELEASING.md). react is an OPTIONAL peer — the contract references React's ComponentType type only (a UI panel is a React component), which is erased at build, so a runtime-only module needs no React.",
+  "//": "@idosgames/core is a real range, not '*': a published contract must name the version of core whose IDosGamesClient/SdkEvents shapes it references. Bump in step with core (see RELEASING.md). react is an OPTIONAL peer — the contract references React's ComponentType type only (a UI panel is a React component), which is erased at build, so a runtime-only module needs no React.",
   "dependencies": {
     "@idosgames/core": "^0.19.0"
   },