@idosgames/module-sdk 0.10.1 → 0.12.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 b(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 T={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=T;exports.isSharedUiRole=R;exports.isTopicName=S;exports.shape=h;exports.topicNamespace=b;
+'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 M(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 T={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var b=["currency-bar","wallet","status","account","menu","modes"];function R(e){return typeof e=="string"&&b.includes(e)}function D(e){return e}exports.SHARED_UI_ROLES=b;exports.TOPIC_NAME_RE=x;exports.defineModule=D;exports.defineTopic=v;exports.hostTopics=T;exports.isSharedUiRole=R;exports.isTopicName=S;exports.shape=h;exports.topicNamespace=M;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { RealtimeSession, IDosGamesClient } from '@idosgames/core';
+import { RealtimeSession, VoiceController, IDosGamesClient } from '@idosgames/core';
 export { IDosGamesClient, SdkEvents } from '@idosgames/core';
 import { ComponentType } from 'react';
 
@@ -217,8 +217,12 @@ interface FeatureScreenProps {
 interface FeatureDefinition {
     /** Unique across the game — conventionally the owning module's id ("store"). */
     id: string;
-    /** Menu label, already in the player's language. */
-    label: string;
+    /**
+     * Menu label in the player's language. Prefer a function (`label: () => t("title")`): the lobby
+     * calls it on every render, so the tab follows the language switch (UI kit `setLanguage`) without
+     * a reload. A plain string stays as registered.
+     */
+    label: string | (() => string);
     /** Glyph name of @idosgames/react/ui ("shop", "hero"…), an emoji, or an image URL. */
     icon?: string;
     group?: FeatureGroup;
@@ -236,7 +240,9 @@ interface FeatureDefinition {
     available?: boolean;
 }
 /** A registered feature plus its live badge and availability. */
-interface FeatureEntry extends FeatureDefinition {
+interface FeatureEntry extends Omit<FeatureDefinition, "label"> {
+    /** The label now — a function label is called on every read. */
+    readonly label: string;
     badge: number;
     /** The module that registered it. */
     moduleId: string;
@@ -339,6 +345,13 @@ interface MultiplayerRoom {
     readonly lateJoin: boolean;
     /** Leave the room for good: closes the session and the rooms screen forgets it. */
     leave(): Promise<void>;
+    /**
+     * The room's voice chat, or `null` when the room has none. The rooms system owns it and draws its
+     * controls (the mic button over the game included); a game reads it for its own touches — who is
+     * speaking (`isSpeaking`, `on("change")`), a talking player's marker, proximity volume
+     * (`setPeerVolume` by distance).
+     */
+    readonly voice: VoiceController | null;
 }
 /** What `ctx.features.open("multiplayer", args)` understands. */
 interface MultiplayerScreenArgs {
@@ -357,6 +370,84 @@ interface MultiplayerRegistry {
     subscribe(listener: () => void): () => void;
 }
 
+/** A button under the showcase or on the "Play" card. */
+interface LobbyHeroAction {
+    id: string;
+    /** Already in the player's language. */
+    label: string;
+    /** Glyph name of @idosgames/react/ui ("edit", "star"…), an emoji, or an image URL. */
+    icon?: string;
+    /** Pressed. Omit when the button only opens `menu`. */
+    run?(): void;
+    /** A short list shown when the button is pressed (an emote picker) — each entry runs on its own. */
+    menu?: LobbyHeroAction[];
+    disabled?: boolean;
+}
+/** What the lobby lays out around the showcase. Read through `view()`, redrawn on `subscribe`. */
+interface LobbyHeroView {
+    /** Big name under the showcase (the character's name). */
+    title?: string;
+    /** A line under it. */
+    subtitle?: string;
+    /** Buttons under the name ("Edit", "Emote"). */
+    actions?: LobbyHeroAction[];
+    /**
+     * The card next to "Play" — WHAT will be played: a caption ("World"), a name ("Island"), buttons
+     * to change it ("Change", "New"). Omitted — "Play" alone.
+     */
+    play?: {
+        caption?: string;
+        title?: string;
+        actions?: LobbyHeroAction[];
+        /** Overflow menu of the card ("⋯": download, upload…). */
+        more?: LobbyHeroAction[];
+    };
+}
+/** Handed to `mount`: where on the host the main figure should stand. */
+interface LobbyHeroStage {
+    /**
+     * The free spot between the lobby's interface where the figure should stand, in CSS pixels of the
+     * host element (it moves with the layout — read it every frame). `null` — not laid out yet.
+     */
+    spot(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+}
+interface LobbyHeroDefinition {
+    /** The game mode "Play" starts (a route id of the game). */
+    mode: string;
+    /**
+     * Put the showcase into `host` — an element filling the lobby's home behind its interface. Called
+     * when the home is shown, the returned function when it is left (stop the render loop there). The
+     * same hero may be mounted again later.
+     */
+    mount(host: HTMLElement, stage: LobbyHeroStage): () => void;
+    /** The current texts and buttons. Cheap — called on every redraw. */
+    view(): LobbyHeroView;
+    /** Called by the hero whenever `view()` would answer differently. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * "Play" was pressed: return false to stay in the lobby (nothing to play yet). Default: switch to
+     * `mode`.
+     */
+    beforePlay?(): boolean;
+}
+/** `ctx.lobby` — the app's lobby as seen by a module. */
+interface LobbyRegistry {
+    /** Put this game's showcase on the lobby's home. Returns the unregister function. */
+    setHero(hero: LobbyHeroDefinition): () => void;
+    /** The hero on the home now (the lobby reads it). */
+    hero(): LobbyHeroDefinition | null;
+    subscribe(listener: () => void): () => void;
+    /** Whether the app has a lobby to return to (the base is installed). */
+    available(): boolean;
+    /** Go to the lobby — a game's "To the lobby" in its pause menu. False — there is no lobby. */
+    open(): boolean;
+}
+
 /** One piece of work on the loading screen. Call `done()` exactly once, also on failure. */
 interface LoadingTask {
     /**
@@ -441,6 +532,32 @@ interface AppNotifications {
     dismiss(id: string): void;
 }
 
+/** The room's voices, as the recording takes them (the multiplayer system provides this). */
+interface RecordingVoiceSource {
+    /** This player's microphone track (silent while not transmitting); null — mic off. */
+    mic(): MediaStreamTrack | null;
+    /** Other players' voice tracks. */
+    others(): MediaStreamTrack[];
+    /** The publisher allows other players' voices in videos (`Multiplayer.RecordVoices`). */
+    recordOthers(): boolean;
+    /** Called when tracks come or go (a player joined, the mic went on). */
+    subscribe(listener: () => void): () => void;
+}
+/** `ctx.clips`. */
+interface ClipsRegistry {
+    /**
+     * A bright moment right now. `weight` 1–10 (default 5): how much it is worth showing — a boss
+     * kill 8, a level-up 4. Close marks merge into one clip (their weights add up).
+     */
+    mark(name: string, weight?: number): void;
+    /** The multiplayer system registers the room's voices here; `null` when the room is gone. */
+    setVoiceSource(source: RecordingVoiceSource | null): void;
+    /** This player is making a long recording right now. */
+    isRecording(): boolean;
+    /** Called when `isRecording` changes. */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -629,6 +746,12 @@ interface ModuleContext {
      * builds its "Play" buttons from it; a game can tell whether a lobby exists to return to.
      */
     modes: ModeRegistry;
+    /**
+     * The app's lobby: a game puts its showcase on the lobby's home (`setHero` — its character on a
+     * pedestal, "Play" next to it) and sends the player back to it from its pause menu (`open`). See
+     * `LobbyHeroDefinition`.
+     */
+    lobby: LobbyRegistry;
     /**
      * 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
@@ -660,6 +783,12 @@ interface ModuleContext {
      * one look, one queue, one sound for the whole app. The module's own id is the default `source`.
      */
     notifications: AppNotifications;
+    /**
+     * The platform's video recording (see `ClipsRegistry`): a game marks bright moments
+     * (`ctx.clips.mark("boss_down", 8)`) — they become the player's "Best moments" clips on
+     * idosgames.com. A no-op anywhere else.
+     */
+    clips: ClipsRegistry;
 }
 /**
  * A module's debug surface for the agent: read its state, drive it with named actions.
@@ -752,6 +881,21 @@ interface EngineScene {
      * host falls back to reading the canvas itself, which is correct for 2D canvases.
      */
     capture?(): Promise<Blob | null>;
+    /**
+     * Where the action is right now, 0–1 on both axes of the canvas (the player, the explosion) — for
+     * the platform's video recording: a vertical (TikTok) cut of a landscape game follows this point
+     * instead of cutting the middle. Called a few times a second; keep it cheap. Omit — the centre.
+     */
+    focus?(): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * The game's own sound as a MediaStream, for the platform's video recording — e.g. a
+     * `MediaStreamAudioDestinationNode` your audio graph also feeds (Three.js: `listener.context`).
+     * Omit — videos carry the voices but not the game's sound.
+     */
+    audio?(): MediaStream | null;
     /** Permanent teardown — dispose GPU resources, remove listeners. */
     destroy(): void;
 }
@@ -790,9 +934,15 @@ interface RouteEntry {
      * A game that lives INSIDE the lobby: the base keeps the lobby's balances on top and its tabs at
      * the bottom around it, "Play" is this game, and the app starts in it after sign-in (idle-rpg).
      * Without it (the default) a game takes the whole screen, launched by "Play" in the lobby, with a
-     * small button back (voxelcraft, board-game).
+     * small button back (board-game).
      */
     inLobby?: boolean;
+    /**
+     * A full-screen game with its OWN way back to the lobby (a pause menu with "To the lobby" that
+     * calls `ctx.lobby.open()` — voxelcraft): the base does not draw its round button back over it.
+     * The game must then offer that way on every device (a pause button on touch screens).
+     */
+    ownExit?: boolean;
 }
 /** A mode of the app as every module sees it (`ctx.modes`): a registered route plus its owner. */
 interface ModeEntry {
@@ -807,6 +957,8 @@ interface ModeEntry {
     moduleType: ModuleType;
     /** The route's `inLobby`: the game sits inside the lobby rather than taking the whole screen. */
     inLobby?: boolean;
+    /** The route's `ownExit`: the game leads back to the lobby itself — no button back over it. */
+    ownExit?: boolean;
 }
 /** `ctx.modes` — the modes of the app, live. Switch with `ctx.navigate(id)`. */
 interface ModeRegistry {
@@ -832,4 +984,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 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 };
+export { type AppNotifications, type CapturedContent, type ClipsRegistry, 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 LobbyHeroAction, type LobbyHeroDefinition, type LobbyHeroStage, type LobbyHeroView, type LobbyRegistry, 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 RecordingVoiceSource, 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 { RealtimeSession, IDosGamesClient } from '@idosgames/core';
+import { RealtimeSession, VoiceController, IDosGamesClient } from '@idosgames/core';
 export { IDosGamesClient, SdkEvents } from '@idosgames/core';
 import { ComponentType } from 'react';
 
@@ -217,8 +217,12 @@ interface FeatureScreenProps {
 interface FeatureDefinition {
     /** Unique across the game — conventionally the owning module's id ("store"). */
     id: string;
-    /** Menu label, already in the player's language. */
-    label: string;
+    /**
+     * Menu label in the player's language. Prefer a function (`label: () => t("title")`): the lobby
+     * calls it on every render, so the tab follows the language switch (UI kit `setLanguage`) without
+     * a reload. A plain string stays as registered.
+     */
+    label: string | (() => string);
     /** Glyph name of @idosgames/react/ui ("shop", "hero"…), an emoji, or an image URL. */
     icon?: string;
     group?: FeatureGroup;
@@ -236,7 +240,9 @@ interface FeatureDefinition {
     available?: boolean;
 }
 /** A registered feature plus its live badge and availability. */
-interface FeatureEntry extends FeatureDefinition {
+interface FeatureEntry extends Omit<FeatureDefinition, "label"> {
+    /** The label now — a function label is called on every read. */
+    readonly label: string;
     badge: number;
     /** The module that registered it. */
     moduleId: string;
@@ -339,6 +345,13 @@ interface MultiplayerRoom {
     readonly lateJoin: boolean;
     /** Leave the room for good: closes the session and the rooms screen forgets it. */
     leave(): Promise<void>;
+    /**
+     * The room's voice chat, or `null` when the room has none. The rooms system owns it and draws its
+     * controls (the mic button over the game included); a game reads it for its own touches — who is
+     * speaking (`isSpeaking`, `on("change")`), a talking player's marker, proximity volume
+     * (`setPeerVolume` by distance).
+     */
+    readonly voice: VoiceController | null;
 }
 /** What `ctx.features.open("multiplayer", args)` understands. */
 interface MultiplayerScreenArgs {
@@ -357,6 +370,84 @@ interface MultiplayerRegistry {
     subscribe(listener: () => void): () => void;
 }
 
+/** A button under the showcase or on the "Play" card. */
+interface LobbyHeroAction {
+    id: string;
+    /** Already in the player's language. */
+    label: string;
+    /** Glyph name of @idosgames/react/ui ("edit", "star"…), an emoji, or an image URL. */
+    icon?: string;
+    /** Pressed. Omit when the button only opens `menu`. */
+    run?(): void;
+    /** A short list shown when the button is pressed (an emote picker) — each entry runs on its own. */
+    menu?: LobbyHeroAction[];
+    disabled?: boolean;
+}
+/** What the lobby lays out around the showcase. Read through `view()`, redrawn on `subscribe`. */
+interface LobbyHeroView {
+    /** Big name under the showcase (the character's name). */
+    title?: string;
+    /** A line under it. */
+    subtitle?: string;
+    /** Buttons under the name ("Edit", "Emote"). */
+    actions?: LobbyHeroAction[];
+    /**
+     * The card next to "Play" — WHAT will be played: a caption ("World"), a name ("Island"), buttons
+     * to change it ("Change", "New"). Omitted — "Play" alone.
+     */
+    play?: {
+        caption?: string;
+        title?: string;
+        actions?: LobbyHeroAction[];
+        /** Overflow menu of the card ("⋯": download, upload…). */
+        more?: LobbyHeroAction[];
+    };
+}
+/** Handed to `mount`: where on the host the main figure should stand. */
+interface LobbyHeroStage {
+    /**
+     * The free spot between the lobby's interface where the figure should stand, in CSS pixels of the
+     * host element (it moves with the layout — read it every frame). `null` — not laid out yet.
+     */
+    spot(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+}
+interface LobbyHeroDefinition {
+    /** The game mode "Play" starts (a route id of the game). */
+    mode: string;
+    /**
+     * Put the showcase into `host` — an element filling the lobby's home behind its interface. Called
+     * when the home is shown, the returned function when it is left (stop the render loop there). The
+     * same hero may be mounted again later.
+     */
+    mount(host: HTMLElement, stage: LobbyHeroStage): () => void;
+    /** The current texts and buttons. Cheap — called on every redraw. */
+    view(): LobbyHeroView;
+    /** Called by the hero whenever `view()` would answer differently. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * "Play" was pressed: return false to stay in the lobby (nothing to play yet). Default: switch to
+     * `mode`.
+     */
+    beforePlay?(): boolean;
+}
+/** `ctx.lobby` — the app's lobby as seen by a module. */
+interface LobbyRegistry {
+    /** Put this game's showcase on the lobby's home. Returns the unregister function. */
+    setHero(hero: LobbyHeroDefinition): () => void;
+    /** The hero on the home now (the lobby reads it). */
+    hero(): LobbyHeroDefinition | null;
+    subscribe(listener: () => void): () => void;
+    /** Whether the app has a lobby to return to (the base is installed). */
+    available(): boolean;
+    /** Go to the lobby — a game's "To the lobby" in its pause menu. False — there is no lobby. */
+    open(): boolean;
+}
+
 /** One piece of work on the loading screen. Call `done()` exactly once, also on failure. */
 interface LoadingTask {
     /**
@@ -441,6 +532,32 @@ interface AppNotifications {
     dismiss(id: string): void;
 }
 
+/** The room's voices, as the recording takes them (the multiplayer system provides this). */
+interface RecordingVoiceSource {
+    /** This player's microphone track (silent while not transmitting); null — mic off. */
+    mic(): MediaStreamTrack | null;
+    /** Other players' voice tracks. */
+    others(): MediaStreamTrack[];
+    /** The publisher allows other players' voices in videos (`Multiplayer.RecordVoices`). */
+    recordOthers(): boolean;
+    /** Called when tracks come or go (a player joined, the mic went on). */
+    subscribe(listener: () => void): () => void;
+}
+/** `ctx.clips`. */
+interface ClipsRegistry {
+    /**
+     * A bright moment right now. `weight` 1–10 (default 5): how much it is worth showing — a boss
+     * kill 8, a level-up 4. Close marks merge into one clip (their weights add up).
+     */
+    mark(name: string, weight?: number): void;
+    /** The multiplayer system registers the room's voices here; `null` when the room is gone. */
+    setVoiceSource(source: RecordingVoiceSource | null): void;
+    /** This player is making a long recording right now. */
+    isRecording(): boolean;
+    /** Called when `isRecording` changes. */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -629,6 +746,12 @@ interface ModuleContext {
      * builds its "Play" buttons from it; a game can tell whether a lobby exists to return to.
      */
     modes: ModeRegistry;
+    /**
+     * The app's lobby: a game puts its showcase on the lobby's home (`setHero` — its character on a
+     * pedestal, "Play" next to it) and sends the player back to it from its pause menu (`open`). See
+     * `LobbyHeroDefinition`.
+     */
+    lobby: LobbyRegistry;
     /**
      * 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
@@ -660,6 +783,12 @@ interface ModuleContext {
      * one look, one queue, one sound for the whole app. The module's own id is the default `source`.
      */
     notifications: AppNotifications;
+    /**
+     * The platform's video recording (see `ClipsRegistry`): a game marks bright moments
+     * (`ctx.clips.mark("boss_down", 8)`) — they become the player's "Best moments" clips on
+     * idosgames.com. A no-op anywhere else.
+     */
+    clips: ClipsRegistry;
 }
 /**
  * A module's debug surface for the agent: read its state, drive it with named actions.
@@ -752,6 +881,21 @@ interface EngineScene {
      * host falls back to reading the canvas itself, which is correct for 2D canvases.
      */
     capture?(): Promise<Blob | null>;
+    /**
+     * Where the action is right now, 0–1 on both axes of the canvas (the player, the explosion) — for
+     * the platform's video recording: a vertical (TikTok) cut of a landscape game follows this point
+     * instead of cutting the middle. Called a few times a second; keep it cheap. Omit — the centre.
+     */
+    focus?(): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * The game's own sound as a MediaStream, for the platform's video recording — e.g. a
+     * `MediaStreamAudioDestinationNode` your audio graph also feeds (Three.js: `listener.context`).
+     * Omit — videos carry the voices but not the game's sound.
+     */
+    audio?(): MediaStream | null;
     /** Permanent teardown — dispose GPU resources, remove listeners. */
     destroy(): void;
 }
@@ -790,9 +934,15 @@ interface RouteEntry {
      * A game that lives INSIDE the lobby: the base keeps the lobby's balances on top and its tabs at
      * the bottom around it, "Play" is this game, and the app starts in it after sign-in (idle-rpg).
      * Without it (the default) a game takes the whole screen, launched by "Play" in the lobby, with a
-     * small button back (voxelcraft, board-game).
+     * small button back (board-game).
      */
     inLobby?: boolean;
+    /**
+     * A full-screen game with its OWN way back to the lobby (a pause menu with "To the lobby" that
+     * calls `ctx.lobby.open()` — voxelcraft): the base does not draw its round button back over it.
+     * The game must then offer that way on every device (a pause button on touch screens).
+     */
+    ownExit?: boolean;
 }
 /** A mode of the app as every module sees it (`ctx.modes`): a registered route plus its owner. */
 interface ModeEntry {
@@ -807,6 +957,8 @@ interface ModeEntry {
     moduleType: ModuleType;
     /** The route's `inLobby`: the game sits inside the lobby rather than taking the whole screen. */
     inLobby?: boolean;
+    /** The route's `ownExit`: the game leads back to the lobby itself — no button back over it. */
+    ownExit?: boolean;
 }
 /** `ctx.modes` — the modes of the app, live. Switch with `ctx.navigate(id)`. */
 interface ModeRegistry {
@@ -832,4 +984,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 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 };
+export { type AppNotifications, type CapturedContent, type ClipsRegistry, 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 LobbyHeroAction, type LobbyHeroDefinition, type LobbyHeroStage, type LobbyHeroView, type LobbyRegistry, 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 RecordingVoiceSource, 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 b(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 T={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,T as hostTopics,R as isSharedUiRole,S as isTopicName,h as shape,b 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 M(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 T={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var b=["currency-bar","wallet","status","account","menu","modes"];function R(e){return typeof e=="string"&&b.includes(e)}function D(e){return e}export{b as SHARED_UI_ROLES,x as TOPIC_NAME_RE,D as defineModule,v as defineTopic,T as hostTopics,R as isSharedUiRole,S as isTopicName,h as shape,M as topicNamespace};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idosgames/module-sdk",
-  "version": "0.10.1",
+  "version": "0.12.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",
@@ -46,7 +46,7 @@
   },
   "//": "@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.21.0"
+    "@idosgames/core": "^0.22.0"
   },
   "peerDependencies": {
     "react": "^18.3.1 || ^19.0.0"