@idosgames/module-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iDos Games
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @idosgames/module-sdk
+
+The composable-module **contract** for the iDosGames host shell. A module is a self-contained
+feature — a game (Three/Phaser), a plain app, or an AI app — that plugs into the host: it declares a
+`Module` manifest and, in `setup(ctx)`, registers what it contributes (a rendered `EngineScene`,
+React `UiPanel`s, a nav route). Framework-neutral at runtime — React and `@idosgames/core` are
+referenced as types only, so a renderer-less module pulls in neither.
+
+```ts
+import { defineModule } from "@idosgames/module-sdk";
+
+export const myModule = defineModule({
+  id: "my-game",
+  meta: { name: "My Game", type: "game", genre: "arcade", engine: "three" },
+  setup(ctx) {
+    ctx.registerScene(scene); // mount/activate/suspend/destroy
+    ctx.registerPanel(panel); // React UI in a host slot
+    ctx.registerRoute({ id: "my-game", label: "Play", icon: "🎮" });
+  },
+});
+```
+
+Key types: `Module`, `ModuleContext`, `EngineScene`, `SceneMountContext`, `UiPanel`, `SurfaceAllocator`,
+`RouteEntry`, `SharedEventBus`. The host runtime is [`@idosgames/app-shell`](https://www.npmjs.com/package/@idosgames/app-shell);
+shared React glue is [`@idosgames/react`](https://www.npmjs.com/package/@idosgames/react).
+
+See the full design in `docs/composable-modules-architecture.md`, or load the `idosgames-module-contract`
+skill (via the `@idosgames/mcp` server).

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';function t(e){return e}exports.defineModule=t;

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+import { IDosGamesClient } from '@idosgames/core';
+export { IDosGamesClient, SdkEvents } from '@idosgames/core';
+import { ComponentType } from 'react';
+
+/** What a module is, for catalog/UI purposes. Not every module is a game. */
+type ModuleType = "game" | "app" | "ai-app";
+/**
+ * Rendering family a module needs a surface for. `"dom"` means no GPU renderer — a pure
+ * React/DOM module (an app or AI app). The host mode-switches between different engines and may,
+ * later, compose modules of the same engine family.
+ */
+type ModuleEngine = "three" | "phaser" | "dom";
+interface ModuleMeta {
+    /** Human-readable name shown in the catalog and nav. */
+    name: string;
+    type: ModuleType;
+    /** Genre tag for games ("board", "idle-rpg", "sandbox", …). Optional for non-games. */
+    genre?: string;
+    engine: ModuleEngine;
+}
+/**
+ * The manifest a module exports. The host calls `setup` exactly once, passing shared services;
+ * the module registers its scene/panels/routes and returns nothing.
+ */
+interface Module {
+    /** Stable unique id — also the mode id the nav switches by. */
+    id: string;
+    meta: ModuleMeta;
+    setup(ctx: ModuleContext): void;
+}
+/** Services the host injects into every module at `setup` time. */
+interface ModuleContext {
+    /** The one shared, already-authenticated SDK client. Modules never create their own. */
+    client: IDosGamesClient;
+    /** Cross-module bus — e.g. an idle module emits "gold:granted", a board module reacts. */
+    events: SharedEventBus;
+    /** Requests host-managed DOM surfaces (canvas hosts, HUD slots) when a module needs one directly. */
+    surface: SurfaceAllocator;
+    /** Register a rendered scene (Three/Phaser/custom). The host drives its lifecycle. */
+    registerScene(scene: EngineScene): void;
+    /** Register a React UI panel placed into one of the host's slots. */
+    registerPanel(panel: UiPanel): void;
+    /** Register a nav / mode entry so the player can switch to this module. */
+    registerRoute(entry: RouteEntry): void;
+}
+/** Where on screen a surface lives. The host's layout decides actual placement. */
+type SurfaceKind = "fullbleed-canvas" | "sidebar-panel" | "overlay" | "hud-slot";
+interface SurfaceHandle {
+    /** The DOM element the module renders into. */
+    readonly host: HTMLElement;
+    /** Release the surface and remove the element (module teardown). */
+    release(): void;
+}
+/** Hands out host-managed DOM surfaces for modules that mount into the DOM directly. */
+interface SurfaceAllocator {
+    request(kind: SurfaceKind): SurfaceHandle;
+}
+/** Passed to `EngineScene.mount`. An object (not a bare element) so it can grow — e.g. a
+ *  host-shared renderer in the composition era — without breaking the contract. */
+interface SceneMountContext {
+    /** The element this scene attaches its canvas/DOM to. */
+    host: HTMLElement;
+}
+/**
+ * A rendered scene the host drives. In the Mode Router model the scene owns its renderer but MUST
+ * stop its RAF loop on `suspend` and resume on `activate` — only one engine is visible at a time.
+ */
+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. */
+    mount(ctx: SceneMountContext): 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. */
+    suspend?(): void;
+    /** Optional per-frame tick if the module opts into the host's shared loop. */
+    update?(deltaMs: number): void;
+    /** Permanent teardown — dispose GPU resources, remove listeners. */
+    destroy(): void;
+}
+/** Named region of the host layout a panel renders into. */
+type PanelSlot = "hud" | "sidebar" | "overlay" | "modal";
+interface UiPanel {
+    /** Unique within the module. */
+    id: string;
+    slot: PanelSlot;
+    /** React component rendered by the host inside the shared provider stack. Takes no props —
+     *  it reads shared state through the host's hooks (`useIDosGamesClient`, etc.). */
+    component: ComponentType;
+    /** Render only while this module's mode is active. Defaults to `true`. A shared HUD that must
+     *  stay visible across modes sets this `false`. */
+    activeOnly?: boolean;
+    /** Sort order within the slot; lower renders first. */
+    order?: number;
+}
+/** A nav / mode entry contributed to the host's mode router. */
+interface RouteEntry {
+    /** Mode id — conventionally the owning module's `id`. The host switches modes by this. */
+    id: string;
+    label: string;
+    /** Optional icon (emoji or short glyph the host nav renders). */
+    icon?: string;
+    order?: number;
+}
+/**
+ * Typed pub/sub shared by every module. Defaults to an open `Record<string, unknown>` topic map;
+ * a host may parameterize it with a known event map for stronger typing.
+ */
+interface SharedEventBus<Events extends Record<string, unknown> = Record<string, unknown>> {
+    emit<K extends keyof Events & string>(topic: K, payload: Events[K]): void;
+    /** Subscribe; returns an unsubscribe function. */
+    on<K extends keyof Events & string>(topic: K, handler: (payload: Events[K]) => void): () => void;
+}
+/** Identity helper that pins a module literal to the `Module` type for editor help and errors. */
+declare function defineModule(module: Module): Module;
+
+export { type EngineScene, type Module, type ModuleContext, type ModuleEngine, type ModuleMeta, type ModuleType, type PanelSlot, type RouteEntry, type SceneMountContext, type SharedEventBus, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, type UiPanel, defineModule };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import { IDosGamesClient } from '@idosgames/core';
+export { IDosGamesClient, SdkEvents } from '@idosgames/core';
+import { ComponentType } from 'react';
+
+/** What a module is, for catalog/UI purposes. Not every module is a game. */
+type ModuleType = "game" | "app" | "ai-app";
+/**
+ * Rendering family a module needs a surface for. `"dom"` means no GPU renderer — a pure
+ * React/DOM module (an app or AI app). The host mode-switches between different engines and may,
+ * later, compose modules of the same engine family.
+ */
+type ModuleEngine = "three" | "phaser" | "dom";
+interface ModuleMeta {
+    /** Human-readable name shown in the catalog and nav. */
+    name: string;
+    type: ModuleType;
+    /** Genre tag for games ("board", "idle-rpg", "sandbox", …). Optional for non-games. */
+    genre?: string;
+    engine: ModuleEngine;
+}
+/**
+ * The manifest a module exports. The host calls `setup` exactly once, passing shared services;
+ * the module registers its scene/panels/routes and returns nothing.
+ */
+interface Module {
+    /** Stable unique id — also the mode id the nav switches by. */
+    id: string;
+    meta: ModuleMeta;
+    setup(ctx: ModuleContext): void;
+}
+/** Services the host injects into every module at `setup` time. */
+interface ModuleContext {
+    /** The one shared, already-authenticated SDK client. Modules never create their own. */
+    client: IDosGamesClient;
+    /** Cross-module bus — e.g. an idle module emits "gold:granted", a board module reacts. */
+    events: SharedEventBus;
+    /** Requests host-managed DOM surfaces (canvas hosts, HUD slots) when a module needs one directly. */
+    surface: SurfaceAllocator;
+    /** Register a rendered scene (Three/Phaser/custom). The host drives its lifecycle. */
+    registerScene(scene: EngineScene): void;
+    /** Register a React UI panel placed into one of the host's slots. */
+    registerPanel(panel: UiPanel): void;
+    /** Register a nav / mode entry so the player can switch to this module. */
+    registerRoute(entry: RouteEntry): void;
+}
+/** Where on screen a surface lives. The host's layout decides actual placement. */
+type SurfaceKind = "fullbleed-canvas" | "sidebar-panel" | "overlay" | "hud-slot";
+interface SurfaceHandle {
+    /** The DOM element the module renders into. */
+    readonly host: HTMLElement;
+    /** Release the surface and remove the element (module teardown). */
+    release(): void;
+}
+/** Hands out host-managed DOM surfaces for modules that mount into the DOM directly. */
+interface SurfaceAllocator {
+    request(kind: SurfaceKind): SurfaceHandle;
+}
+/** Passed to `EngineScene.mount`. An object (not a bare element) so it can grow — e.g. a
+ *  host-shared renderer in the composition era — without breaking the contract. */
+interface SceneMountContext {
+    /** The element this scene attaches its canvas/DOM to. */
+    host: HTMLElement;
+}
+/**
+ * A rendered scene the host drives. In the Mode Router model the scene owns its renderer but MUST
+ * stop its RAF loop on `suspend` and resume on `activate` — only one engine is visible at a time.
+ */
+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. */
+    mount(ctx: SceneMountContext): 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. */
+    suspend?(): void;
+    /** Optional per-frame tick if the module opts into the host's shared loop. */
+    update?(deltaMs: number): void;
+    /** Permanent teardown — dispose GPU resources, remove listeners. */
+    destroy(): void;
+}
+/** Named region of the host layout a panel renders into. */
+type PanelSlot = "hud" | "sidebar" | "overlay" | "modal";
+interface UiPanel {
+    /** Unique within the module. */
+    id: string;
+    slot: PanelSlot;
+    /** React component rendered by the host inside the shared provider stack. Takes no props —
+     *  it reads shared state through the host's hooks (`useIDosGamesClient`, etc.). */
+    component: ComponentType;
+    /** Render only while this module's mode is active. Defaults to `true`. A shared HUD that must
+     *  stay visible across modes sets this `false`. */
+    activeOnly?: boolean;
+    /** Sort order within the slot; lower renders first. */
+    order?: number;
+}
+/** A nav / mode entry contributed to the host's mode router. */
+interface RouteEntry {
+    /** Mode id — conventionally the owning module's `id`. The host switches modes by this. */
+    id: string;
+    label: string;
+    /** Optional icon (emoji or short glyph the host nav renders). */
+    icon?: string;
+    order?: number;
+}
+/**
+ * Typed pub/sub shared by every module. Defaults to an open `Record<string, unknown>` topic map;
+ * a host may parameterize it with a known event map for stronger typing.
+ */
+interface SharedEventBus<Events extends Record<string, unknown> = Record<string, unknown>> {
+    emit<K extends keyof Events & string>(topic: K, payload: Events[K]): void;
+    /** Subscribe; returns an unsubscribe function. */
+    on<K extends keyof Events & string>(topic: K, handler: (payload: Events[K]) => void): () => void;
+}
+/** Identity helper that pins a module literal to the `Module` type for editor help and errors. */
+declare function defineModule(module: Module): Module;
+
+export { type EngineScene, type Module, type ModuleContext, type ModuleEngine, type ModuleMeta, type ModuleType, type PanelSlot, type RouteEntry, type SceneMountContext, type SharedEventBus, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, type UiPanel, defineModule };

package/dist/index.js

@@ -0,0 +1 @@
+function t(e){return e}export{t as defineModule};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@idosgames/module-sdk",
+  "version": "0.1.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",
+  "homepage": "https://github.com/iDos-Games/iDosGamesSDK_TS#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iDos-Games/iDosGamesSDK_TS.git",
+    "directory": "packages/module-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/iDos-Games/iDosGamesSDK_TS/issues"
+  },
+  "keywords": [
+    "idosgames",
+    "sdk",
+    "module",
+    "plugin",
+    "gamedev"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "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.",
+  "dependencies": {
+    "@idosgames/core": "^0.1.1"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7"
+  }
+}