@idosgames/module-sdk 0.6.0 → 0.8.0

package/dist/index.cjs

@@ -1 +1 @@
-'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;
+'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,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=c.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=>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[r,n]of Object.entries(e)){let o=t?`${t}.${r}`:r;if(typeof n=="string"){if(!c.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(!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';
 
@@ -276,6 +276,171 @@ interface FeatureRegistry {
     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;
+}
+
+/** One piece of work on the loading screen. Call `done()` exactly once, also on failure. */
+interface LoadingTask {
+    /**
+     * Progress 0..1 when it is known (a bar appears), `null` when it is not (just the spinner). An
+     * optional new label replaces the current one ("Building terrain…", "Loading textures…").
+     */
+    progress(value: number | null, label?: string): void;
+    done(): void;
+}
+interface LoadingReporter {
+    /**
+     * Show the loading screen until `done()`. Quick work never flashes it: the screen appears only if
+     * the work is still running a moment later. `label` — what is loading, in the player's language.
+     */
+    begin(label?: string): LoadingTask;
+    /** The loading screen while `work` runs; resolves or rejects with it. */
+    track<T>(work: Promise<T>, label?: string): Promise<T>;
+    /**
+     * For work that BLOCKS the page (synchronous generation, a big parse): shows the screen at once,
+     * waits until it is painted, then calls `work`. Calling heavy synchronous code straight after
+     * `begin()` would freeze the page before the screen ever appears.
+     */
+    run<T>(work: () => T | Promise<T>, label?: string): Promise<T>;
+}
+
+/**
+ * How important it is — decides the colour, the icon, the sound and how long a toast stays:
+ *   info     — neutral news;                          success — something the player did worked;
+ *   warning  — needs attention, nothing is lost yet;  error   — something failed (say what to do);
+ *   reward   — the player received something.
+ */
+type NotificationLevel = "info" | "success" | "warning" | "error" | "reward";
+interface NotificationAction {
+    /** What `alert()` resolves with when this button is pressed. Defaults to the label. */
+    id?: string;
+    label: string;
+    /** The main action — drawn as the coloured button. At most one. */
+    primary?: boolean;
+    /** Open this screen (a feature id, e.g. "quests") on press. */
+    openFeature?: string;
+    /** Called on press, before the notification closes. */
+    onPress?: () => void;
+}
+interface NotificationInput {
+    level?: NotificationLevel;
+    /** A short headline. Optional for toasts, recommended for alerts. */
+    title?: string;
+    /** The text, already in the player's language. */
+    message?: string;
+    /**
+     * An icon instead of the level's own: a UI-kit glyph name ("trophy", "gift", "chest"…), an emoji
+     * or an image URL.
+     */
+    icon?: string;
+    /** A picture: a thumbnail on a toast, a large image on an alert (an item, a banner, an avatar). */
+    image?: string;
+    /**
+     * The system it belongs to — a feature id ("quests", "store"). Shows that screen's name and icon on
+     * the notification, and a tap on the toast opens it. `ctx.notifications` fills in the calling
+     * module's own id; pass `null` for none.
+     */
+    source?: string | null;
+    /**
+     * The same key replaces a notification that is still shown instead of adding one more ("Saving…"
+     * → "Saved", the same error again). Identical toasts without a key are merged into one "×2".
+     */
+    key?: string;
+    /** Toast only: how long it stays, ms. `0` — until the player closes it. Default by level. */
+    duration?: number;
+    /** Buttons. A toast shows the first one; an alert all of them (default: a single "OK"). */
+    actions?: NotificationAction[];
+}
+interface AppNotifications {
+    /** A toast. A bare string is an info toast. Returns its id (for `dismiss`). */
+    toast(notification: NotificationInput | string): string;
+    /**
+     * An alert window, queued behind any other. Resolves with the pressed action's id, or `null` when
+     * the player closed it without choosing.
+     */
+    alert(notification: NotificationInput): Promise<string | null>;
+    /** Take a toast or a waiting alert away (an alert resolves with `null`). */
+    dismiss(id: string): void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -328,10 +493,19 @@ interface ModuleManifest {
      */
     type?: "template" | "feature";
     /**
-     * Part of the standard set: the platform installs this module into EVERY new project together with
-     * the base (login + lobby) — the shop, heroes, leaderboards… A creator removes it like any module.
+     * 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. */
@@ -431,6 +605,12 @@ interface ModuleContext {
      * rather than a mode of its own; `open(id)` opens another module's screen. See `FeatureDefinition`.
      */
     features: FeatureRegistry;
+    /**
+     * 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.
@@ -455,6 +635,18 @@ interface ModuleContext {
      * @see ModuleAgentApi
      */
     exposeToAgent(api: ModuleAgentApi): void;
+    /**
+     * The app's loading screen (see `LoadingReporter`): `ctx.loading.track(work, "Building the world…")`
+     * for any long work of the module, so the player never faces a still screen wondering whether the
+     * app froze. The host shows it by itself while a scene starts — this is for the module's own work.
+     */
+    loading: LoadingReporter;
+    /**
+     * The app's notifications (see `AppNotifications`): `ctx.notifications.toast({ level: "success",
+     * message })` for news, `alert({ … })` for what the player must answer. Never draw your own banner:
+     * one look, one queue, one sound for the whole app. The module's own id is the default `source`.
+     */
+    notifications: AppNotifications;
 }
 /**
  * A module's debug surface for the agent: read its state, drive it with named actions.
@@ -509,8 +701,18 @@ interface SceneMountContext {
 interface EngineScene {
     /** Preferred host surface. Defaults to `"fullbleed-canvas"` when omitted. */
     readonly surface?: SurfaceKind;
-    /** Create the renderer and attach to the host element. Called once. */
+    /**
+     * Create the renderer and attach to the host element. Called once. The host shows its loading
+     * screen BEFORE calling it and lets it paint, so heavy synchronous work here (generating terrain,
+     * building meshes) never looks like a frozen app.
+     */
     mount(ctx: SceneMountContext): void;
+    /**
+     * Resolves when the scene is really playable (the world is built, the save is loaded). The host
+     * keeps its loading screen up until then. Omit it when the first frame after `mount` is already
+     * the game — the host then hides the screen after that frame.
+     */
+    ready?(): Promise<void>;
     /** This scene became the active mode — resume RAF / re-acquire input. */
     activate?(): void;
     /** This scene was hidden — pause RAF / release input. Not destroyed; may re-activate. */
@@ -600,4 +802,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 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 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 AppNotifications, 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 LoadingReporter, type LoadingTask, 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 NotificationAction, type NotificationInput, type NotificationLevel, 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';
 
@@ -276,6 +276,171 @@ interface FeatureRegistry {
     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;
+}
+
+/** One piece of work on the loading screen. Call `done()` exactly once, also on failure. */
+interface LoadingTask {
+    /**
+     * Progress 0..1 when it is known (a bar appears), `null` when it is not (just the spinner). An
+     * optional new label replaces the current one ("Building terrain…", "Loading textures…").
+     */
+    progress(value: number | null, label?: string): void;
+    done(): void;
+}
+interface LoadingReporter {
+    /**
+     * Show the loading screen until `done()`. Quick work never flashes it: the screen appears only if
+     * the work is still running a moment later. `label` — what is loading, in the player's language.
+     */
+    begin(label?: string): LoadingTask;
+    /** The loading screen while `work` runs; resolves or rejects with it. */
+    track<T>(work: Promise<T>, label?: string): Promise<T>;
+    /**
+     * For work that BLOCKS the page (synchronous generation, a big parse): shows the screen at once,
+     * waits until it is painted, then calls `work`. Calling heavy synchronous code straight after
+     * `begin()` would freeze the page before the screen ever appears.
+     */
+    run<T>(work: () => T | Promise<T>, label?: string): Promise<T>;
+}
+
+/**
+ * How important it is — decides the colour, the icon, the sound and how long a toast stays:
+ *   info     — neutral news;                          success — something the player did worked;
+ *   warning  — needs attention, nothing is lost yet;  error   — something failed (say what to do);
+ *   reward   — the player received something.
+ */
+type NotificationLevel = "info" | "success" | "warning" | "error" | "reward";
+interface NotificationAction {
+    /** What `alert()` resolves with when this button is pressed. Defaults to the label. */
+    id?: string;
+    label: string;
+    /** The main action — drawn as the coloured button. At most one. */
+    primary?: boolean;
+    /** Open this screen (a feature id, e.g. "quests") on press. */
+    openFeature?: string;
+    /** Called on press, before the notification closes. */
+    onPress?: () => void;
+}
+interface NotificationInput {
+    level?: NotificationLevel;
+    /** A short headline. Optional for toasts, recommended for alerts. */
+    title?: string;
+    /** The text, already in the player's language. */
+    message?: string;
+    /**
+     * An icon instead of the level's own: a UI-kit glyph name ("trophy", "gift", "chest"…), an emoji
+     * or an image URL.
+     */
+    icon?: string;
+    /** A picture: a thumbnail on a toast, a large image on an alert (an item, a banner, an avatar). */
+    image?: string;
+    /**
+     * The system it belongs to — a feature id ("quests", "store"). Shows that screen's name and icon on
+     * the notification, and a tap on the toast opens it. `ctx.notifications` fills in the calling
+     * module's own id; pass `null` for none.
+     */
+    source?: string | null;
+    /**
+     * The same key replaces a notification that is still shown instead of adding one more ("Saving…"
+     * → "Saved", the same error again). Identical toasts without a key are merged into one "×2".
+     */
+    key?: string;
+    /** Toast only: how long it stays, ms. `0` — until the player closes it. Default by level. */
+    duration?: number;
+    /** Buttons. A toast shows the first one; an alert all of them (default: a single "OK"). */
+    actions?: NotificationAction[];
+}
+interface AppNotifications {
+    /** A toast. A bare string is an info toast. Returns its id (for `dismiss`). */
+    toast(notification: NotificationInput | string): string;
+    /**
+     * An alert window, queued behind any other. Resolves with the pressed action's id, or `null` when
+     * the player closed it without choosing.
+     */
+    alert(notification: NotificationInput): Promise<string | null>;
+    /** Take a toast or a waiting alert away (an alert resolves with `null`). */
+    dismiss(id: string): void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -328,10 +493,19 @@ interface ModuleManifest {
      */
     type?: "template" | "feature";
     /**
-     * Part of the standard set: the platform installs this module into EVERY new project together with
-     * the base (login + lobby) — the shop, heroes, leaderboards… A creator removes it like any module.
+     * 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. */
@@ -431,6 +605,12 @@ interface ModuleContext {
      * rather than a mode of its own; `open(id)` opens another module's screen. See `FeatureDefinition`.
      */
     features: FeatureRegistry;
+    /**
+     * 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.
@@ -455,6 +635,18 @@ interface ModuleContext {
      * @see ModuleAgentApi
      */
     exposeToAgent(api: ModuleAgentApi): void;
+    /**
+     * The app's loading screen (see `LoadingReporter`): `ctx.loading.track(work, "Building the world…")`
+     * for any long work of the module, so the player never faces a still screen wondering whether the
+     * app froze. The host shows it by itself while a scene starts — this is for the module's own work.
+     */
+    loading: LoadingReporter;
+    /**
+     * The app's notifications (see `AppNotifications`): `ctx.notifications.toast({ level: "success",
+     * message })` for news, `alert({ … })` for what the player must answer. Never draw your own banner:
+     * one look, one queue, one sound for the whole app. The module's own id is the default `source`.
+     */
+    notifications: AppNotifications;
 }
 /**
  * A module's debug surface for the agent: read its state, drive it with named actions.
@@ -509,8 +701,18 @@ interface SceneMountContext {
 interface EngineScene {
     /** Preferred host surface. Defaults to `"fullbleed-canvas"` when omitted. */
     readonly surface?: SurfaceKind;
-    /** Create the renderer and attach to the host element. Called once. */
+    /**
+     * Create the renderer and attach to the host element. Called once. The host shows its loading
+     * screen BEFORE calling it and lets it paint, so heavy synchronous work here (generating terrain,
+     * building meshes) never looks like a frozen app.
+     */
     mount(ctx: SceneMountContext): void;
+    /**
+     * Resolves when the scene is really playable (the world is built, the save is loaded). The host
+     * keeps its loading screen up until then. Omit it when the first frame after `mount` is already
+     * the game — the host then hides the screen after that frame.
+     */
+    ready?(): Promise<void>;
     /** This scene became the active mode — resume RAF / re-acquire input. */
     activate?(): void;
     /** This scene was hidden — pause RAF / release input. Not destroyed; may re-activate. */
@@ -600,4 +802,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 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 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 AppNotifications, 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 LoadingReporter, type LoadingTask, 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 NotificationAction, type NotificationInput, type NotificationLevel, 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 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};
+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,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=c.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=>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[r,n]of Object.entries(e)){let o=t?`${t}.${r}`:r;if(typeof n=="string"){if(!c.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(!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,6 +1,6 @@
 {
   "name": "@idosgames/module-sdk",
-  "version": "0.6.0",
+  "version": "0.8.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",