@idosgames/app-shell 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,23 @@
+# @idosgames/app-shell
+
+The **host runtime** for iDosGames composable modules. A project is one host shell plus N feature
+modules; this package is the shell — it owns the module registry, a shared event bus, a surface
+allocator, the imperative scene stage, and the React **Mode Router** that switches between modules.
+
+```ts
+import { createIDosGamesClient } from "@idosgames/core";
+import { mountHost } from "@idosgames/app-shell";
+import { modules } from "./modules";
+
+const client = createIDosGamesClient({ titleID, buildKey });
+await client.auth.loginWithDeviceID();
+mountHost({ container: document.getElementById("app")!, client, modules });
+```
+
+`mountHost` renders a nav-bar when ≥2 modules register a route and mode-switches between them (only
+the active mode's scene is mounted and ticking). Panels registered with `activeOnly: false` stay
+visible across every mode (e.g. a shared HUD).
+
+Modules are authored against [`@idosgames/module-sdk`](https://www.npmjs.com/package/@idosgames/module-sdk);
+shared React glue is [`@idosgames/react`](https://www.npmjs.com/package/@idosgames/react). React and
+ReactDOM are peer dependencies. See `docs/composable-modules-architecture.md` for the full design.

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';var client=require('react-dom/client'),react$1=require('@idosgames/react'),react=require('react'),jsxRuntime=require('react/jsx-runtime');function S(){let r=new Map;return {emit(n,t){let o=r.get(n);if(o)for(let s of [...o])s(t);},on(n,t){let o=t,s=r.get(n);return s||(s=new Set,r.set(n,s)),s.add(o),()=>{s.delete(o),s.size===0&&r.delete(n);}}}}var k={position:"absolute",inset:"0"};function g(r){return {request(n){let t=document.createElement("div");return t.dataset.surface=n,Object.assign(t.style,k),t.style.pointerEvents=n==="fullbleed-canvas"?"auto":"none",r.appendChild(t),{host:t,release(){t.remove();}}}}}function h(r,n){return r.map(t=>{let o={module:t,scenes:[],panels:[],routes:[]},s={client:n.client,events:n.events,surface:n.surface,registerScene:a=>o.scenes.push(a),registerPanel:a=>o.panels.push(a),registerRoute:a=>o.routes.push(a)};return t.setup(s),o})}var u=class{constructor(n){this.container=n;}container;hosts=new Map;active=new Set;ensureMounted(n){let t=this.hosts.get(n);return t||(t=document.createElement("div"),Object.assign(t.style,{position:"absolute",inset:"0"}),this.container.appendChild(t),this.hosts.set(n,t),n.mount({host:t})),t}setActive(n){let t=new Set(n);for(let o of this.active){if(t.has(o))continue;o.suspend?.();let s=this.hosts.get(o);s&&(s.style.display="none");}for(let o of t){if(this.active.has(o))continue;let s=this.ensureMounted(o);s.style.display="block",o.activate?.();}this.active=t;}destroy(){for(let[n,t]of this.hosts)n.destroy(),t.remove();this.hosts.clear(),this.active.clear();}};function E({registrations:r}){let n=react.useRef(null),t=react.useRef(null),o=react.useMemo(()=>r.flatMap(e=>e.routes.map(i=>({id:i.id,label:i.label,icon:i.icon,order:i.order??0,moduleId:e.module.id}))).sort((e,i)=>e.order-i.order),[r]),[s,a]=react.useState(()=>o[0]?.id??null);react.useEffect(()=>{s!==null&&o.some(e=>e.id===s)||a(o[0]?.id??null);},[o,s]);let c=react.useMemo(()=>o.find(e=>e.id===s)?.moduleId??null,[o,s]);react.useEffect(()=>{let e=n.current;if(!e)return;let i=t.current??=new u(e),y=r.find(R=>R.module.id===c)?.scenes??[];i.setActive(y);},[r,c]),react.useEffect(()=>()=>{t.current?.destroy(),t.current=null;},[]);let v=react.useMemo(()=>r.flatMap(e=>e.panels.filter(i=>i.activeOnly===false||e.module.id===c).map(i=>{let y=i.component;return {key:`${e.module.id}:${i.id}`,slot:i.slot,order:i.order??0,moduleId:e.module.id,component:jsxRuntime.jsx(y,{})}})).sort((e,i)=>e.order-i.order),[r,c]),d=e=>v.filter(i=>i.slot===e),p=r.length>0;return jsxRuntime.jsxs("div",{style:w,children:[jsxRuntime.jsx("div",{ref:n,style:z}),jsxRuntime.jsx("div",{style:A,children:d("overlay").map(e=>jsxRuntime.jsx("div",{style:m,children:e.component},e.key))}),jsxRuntime.jsx("div",{style:B,children:d("hud").map(e=>jsxRuntime.jsx("div",{style:m,children:e.component},e.key))}),jsxRuntime.jsx("div",{style:L,children:d("sidebar").map(e=>jsxRuntime.jsx("div",{style:m,children:e.component},e.key))}),o.length>1&&jsxRuntime.jsx("nav",{style:D,children:o.map(e=>jsxRuntime.jsxs("button",{type:"button",onClick:()=>a(e.id),style:e.id===s?T:P,children:[e.icon?`${e.icon} `:"",e.label]},e.id))}),d("modal").length>0&&jsxRuntime.jsx("div",{style:G,children:d("modal").map(e=>jsxRuntime.jsx("div",{style:m,children:e.component},e.key))}),!p&&jsxRuntime.jsx(H,{})]})}function H(){return jsxRuntime.jsxs("div",{style:N,children:[jsxRuntime.jsx("div",{style:{fontSize:40,marginBottom:12},children:"\u{1F9E9}"}),jsxRuntime.jsx("div",{style:{fontWeight:700,fontSize:18,marginBottom:6},children:"No modules installed"}),jsxRuntime.jsxs("div",{style:{opacity:.7,maxWidth:380,lineHeight:1.5},children:["Add a module under ",jsxRuntime.jsx("code",{children:"src/modules/"})," and register it in"," ",jsxRuntime.jsx("code",{children:"src/modules.ts"}),". The host shell will pick it up here."]})]})}var w={position:"absolute",inset:0,overflow:"hidden",color:"#fff",fontFamily:"system-ui, sans-serif"},z={position:"absolute",inset:0,zIndex:0},A={position:"absolute",inset:0,zIndex:1,pointerEvents:"none"},B={position:"absolute",top:0,left:0,right:0,zIndex:2,display:"flex",gap:12,padding:16,pointerEvents:"none"},L={position:"absolute",top:0,right:0,bottom:0,width:340,maxWidth:"40vw",zIndex:2,display:"flex",flexDirection:"column",gap:12,padding:16,overflowY:"auto",pointerEvents:"none"},D={position:"absolute",bottom:16,left:"50%",transform:"translateX(-50%)",zIndex:3,display:"flex",gap:8,padding:6,borderRadius:14,background:"rgba(20,18,40,0.72)",backdropFilter:"blur(6px)",pointerEvents:"auto"},P={border:"none",borderRadius:10,padding:"8px 16px",fontWeight:700,fontSize:14,color:"#cfc9ee",background:"transparent",cursor:"pointer"},T={...P,color:"#fff",background:"#6c5ce7"},G={position:"absolute",inset:0,zIndex:4,display:"flex",alignItems:"center",justifyContent:"center",background:"rgba(0,0,0,0.5)",pointerEvents:"none"},m={pointerEvents:"auto"},N={position:"absolute",inset:0,zIndex:1,display:"flex",flexDirection:"column",alignItems:"center",justifyContent:"center",textAlign:"center",padding:24};function $(r){let{container:n,client:t,modules:o}=r;n.style.position="relative";let s=document.createElement("div");Object.assign(s.style,{position:"absolute",inset:"0",zIndex:"0",pointerEvents:"none"});let a=document.createElement("div");Object.assign(a.style,{position:"absolute",inset:"0",zIndex:"1"}),n.append(s,a);let c=S(),v=g(s),d=h(o,{client:t,events:c,surface:v}),p=client.createRoot(a);return p.render(jsxRuntime.jsx(react$1.IDosGamesProvider,{client:t,children:jsxRuntime.jsx(react$1.StatusProvider,{children:jsxRuntime.jsx(E,{registrations:d})})})),{unmount(){p.unmount(),s.remove(),a.remove();}}}exports.HostShell=E;exports.SceneStage=u;exports.createSharedEventBus=S;exports.createSurfaceAllocator=g;exports.mountHost=$;exports.runModules=h;

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+import { IDosGamesClient, Module, EngineScene, UiPanel, RouteEntry, SharedEventBus, SurfaceAllocator } from '@idosgames/module-sdk';
+import { ReactNode } from 'react';
+
+interface HostHandle {
+    unmount(): void;
+}
+/**
+ * Mounts the host shell into `container` with the given modules, all driven by one shared,
+ * already-authenticated SDK client. This is the composable-module analog of the old per-template
+ * `mountBoardGame` — except the app owns it and the games are plugged in as modules.
+ *
+ * DOM layout inside `container`:
+ *   container (position: relative)
+ *   ├── surfaceLayer  — ad-hoc module surfaces, behind everything
+ *   └── reactHost     — the React tree (scenes render here, UI panels on top)
+ */
+declare function mountHost(options: {
+    container: HTMLElement;
+    client: IDosGamesClient;
+    modules: readonly Module[];
+}): HostHandle;
+
+interface ModuleRegistration {
+    module: Module;
+    scenes: EngineScene[];
+    panels: UiPanel[];
+    routes: RouteEntry[];
+}
+/** Shared services every module receives — created once per host session. */
+interface SharedServices {
+    client: IDosGamesClient;
+    events: SharedEventBus;
+    surface: SurfaceAllocator;
+}
+/** Install every module and return their collected registrations, in declaration order. */
+declare function runModules(modules: readonly Module[], shared: SharedServices): ModuleRegistration[];
+
+declare function HostShell({ registrations, }: {
+    registrations: readonly ModuleRegistration[];
+}): ReactNode;
+
+declare class SceneStage {
+    private readonly container;
+    private readonly hosts;
+    private active;
+    constructor(container: HTMLElement);
+    private ensureMounted;
+    /** Make exactly `scenes` the active set: suspend/hide the ones leaving, mount+activate the ones
+     *  entering. Idempotent — calling with the current set is a no-op. */
+    setActive(scenes: readonly EngineScene[]): void;
+    /** Permanent teardown: destroy every mounted scene and remove its host element. */
+    destroy(): void;
+}
+
+/** In-memory pub/sub shared by all modules for a host session. */
+declare function createSharedEventBus(): SharedEventBus;
+
+/** Creates an allocator whose surfaces are appended to `layer`. */
+declare function createSurfaceAllocator(layer: HTMLElement): SurfaceAllocator;
+
+export { type HostHandle, HostShell, type ModuleRegistration, SceneStage, type SharedServices, createSharedEventBus, createSurfaceAllocator, mountHost, runModules };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import { IDosGamesClient, Module, EngineScene, UiPanel, RouteEntry, SharedEventBus, SurfaceAllocator } from '@idosgames/module-sdk';
+import { ReactNode } from 'react';
+
+interface HostHandle {
+    unmount(): void;
+}
+/**
+ * Mounts the host shell into `container` with the given modules, all driven by one shared,
+ * already-authenticated SDK client. This is the composable-module analog of the old per-template
+ * `mountBoardGame` — except the app owns it and the games are plugged in as modules.
+ *
+ * DOM layout inside `container`:
+ *   container (position: relative)
+ *   ├── surfaceLayer  — ad-hoc module surfaces, behind everything
+ *   └── reactHost     — the React tree (scenes render here, UI panels on top)
+ */
+declare function mountHost(options: {
+    container: HTMLElement;
+    client: IDosGamesClient;
+    modules: readonly Module[];
+}): HostHandle;
+
+interface ModuleRegistration {
+    module: Module;
+    scenes: EngineScene[];
+    panels: UiPanel[];
+    routes: RouteEntry[];
+}
+/** Shared services every module receives — created once per host session. */
+interface SharedServices {
+    client: IDosGamesClient;
+    events: SharedEventBus;
+    surface: SurfaceAllocator;
+}
+/** Install every module and return their collected registrations, in declaration order. */
+declare function runModules(modules: readonly Module[], shared: SharedServices): ModuleRegistration[];
+
+declare function HostShell({ registrations, }: {
+    registrations: readonly ModuleRegistration[];
+}): ReactNode;
+
+declare class SceneStage {
+    private readonly container;
+    private readonly hosts;
+    private active;
+    constructor(container: HTMLElement);
+    private ensureMounted;
+    /** Make exactly `scenes` the active set: suspend/hide the ones leaving, mount+activate the ones
+     *  entering. Idempotent — calling with the current set is a no-op. */
+    setActive(scenes: readonly EngineScene[]): void;
+    /** Permanent teardown: destroy every mounted scene and remove its host element. */
+    destroy(): void;
+}
+
+/** In-memory pub/sub shared by all modules for a host session. */
+declare function createSharedEventBus(): SharedEventBus;
+
+/** Creates an allocator whose surfaces are appended to `layer`. */
+declare function createSurfaceAllocator(layer: HTMLElement): SurfaceAllocator;
+
+export { type HostHandle, HostShell, type ModuleRegistration, SceneStage, type SharedServices, createSharedEventBus, createSurfaceAllocator, mountHost, runModules };

package/dist/index.js

@@ -0,0 +1 @@
+import {createRoot}from'react-dom/client';import {IDosGamesProvider,StatusProvider}from'@idosgames/react';import {useRef,useMemo,useState,useEffect}from'react';import {jsx,jsxs}from'react/jsx-runtime';function S(){let r=new Map;return {emit(n,t){let o=r.get(n);if(o)for(let s of [...o])s(t);},on(n,t){let o=t,s=r.get(n);return s||(s=new Set,r.set(n,s)),s.add(o),()=>{s.delete(o),s.size===0&&r.delete(n);}}}}var k={position:"absolute",inset:"0"};function g(r){return {request(n){let t=document.createElement("div");return t.dataset.surface=n,Object.assign(t.style,k),t.style.pointerEvents=n==="fullbleed-canvas"?"auto":"none",r.appendChild(t),{host:t,release(){t.remove();}}}}}function h(r,n){return r.map(t=>{let o={module:t,scenes:[],panels:[],routes:[]},s={client:n.client,events:n.events,surface:n.surface,registerScene:a=>o.scenes.push(a),registerPanel:a=>o.panels.push(a),registerRoute:a=>o.routes.push(a)};return t.setup(s),o})}var u=class{constructor(n){this.container=n;}container;hosts=new Map;active=new Set;ensureMounted(n){let t=this.hosts.get(n);return t||(t=document.createElement("div"),Object.assign(t.style,{position:"absolute",inset:"0"}),this.container.appendChild(t),this.hosts.set(n,t),n.mount({host:t})),t}setActive(n){let t=new Set(n);for(let o of this.active){if(t.has(o))continue;o.suspend?.();let s=this.hosts.get(o);s&&(s.style.display="none");}for(let o of t){if(this.active.has(o))continue;let s=this.ensureMounted(o);s.style.display="block",o.activate?.();}this.active=t;}destroy(){for(let[n,t]of this.hosts)n.destroy(),t.remove();this.hosts.clear(),this.active.clear();}};function E({registrations:r}){let n=useRef(null),t=useRef(null),o=useMemo(()=>r.flatMap(e=>e.routes.map(i=>({id:i.id,label:i.label,icon:i.icon,order:i.order??0,moduleId:e.module.id}))).sort((e,i)=>e.order-i.order),[r]),[s,a]=useState(()=>o[0]?.id??null);useEffect(()=>{s!==null&&o.some(e=>e.id===s)||a(o[0]?.id??null);},[o,s]);let c=useMemo(()=>o.find(e=>e.id===s)?.moduleId??null,[o,s]);useEffect(()=>{let e=n.current;if(!e)return;let i=t.current??=new u(e),y=r.find(R=>R.module.id===c)?.scenes??[];i.setActive(y);},[r,c]),useEffect(()=>()=>{t.current?.destroy(),t.current=null;},[]);let v=useMemo(()=>r.flatMap(e=>e.panels.filter(i=>i.activeOnly===false||e.module.id===c).map(i=>{let y=i.component;return {key:`${e.module.id}:${i.id}`,slot:i.slot,order:i.order??0,moduleId:e.module.id,component:jsx(y,{})}})).sort((e,i)=>e.order-i.order),[r,c]),d=e=>v.filter(i=>i.slot===e),p=r.length>0;return jsxs("div",{style:w,children:[jsx("div",{ref:n,style:z}),jsx("div",{style:A,children:d("overlay").map(e=>jsx("div",{style:m,children:e.component},e.key))}),jsx("div",{style:B,children:d("hud").map(e=>jsx("div",{style:m,children:e.component},e.key))}),jsx("div",{style:L,children:d("sidebar").map(e=>jsx("div",{style:m,children:e.component},e.key))}),o.length>1&&jsx("nav",{style:D,children:o.map(e=>jsxs("button",{type:"button",onClick:()=>a(e.id),style:e.id===s?T:P,children:[e.icon?`${e.icon} `:"",e.label]},e.id))}),d("modal").length>0&&jsx("div",{style:G,children:d("modal").map(e=>jsx("div",{style:m,children:e.component},e.key))}),!p&&jsx(H,{})]})}function H(){return jsxs("div",{style:N,children:[jsx("div",{style:{fontSize:40,marginBottom:12},children:"\u{1F9E9}"}),jsx("div",{style:{fontWeight:700,fontSize:18,marginBottom:6},children:"No modules installed"}),jsxs("div",{style:{opacity:.7,maxWidth:380,lineHeight:1.5},children:["Add a module under ",jsx("code",{children:"src/modules/"})," and register it in"," ",jsx("code",{children:"src/modules.ts"}),". The host shell will pick it up here."]})]})}var w={position:"absolute",inset:0,overflow:"hidden",color:"#fff",fontFamily:"system-ui, sans-serif"},z={position:"absolute",inset:0,zIndex:0},A={position:"absolute",inset:0,zIndex:1,pointerEvents:"none"},B={position:"absolute",top:0,left:0,right:0,zIndex:2,display:"flex",gap:12,padding:16,pointerEvents:"none"},L={position:"absolute",top:0,right:0,bottom:0,width:340,maxWidth:"40vw",zIndex:2,display:"flex",flexDirection:"column",gap:12,padding:16,overflowY:"auto",pointerEvents:"none"},D={position:"absolute",bottom:16,left:"50%",transform:"translateX(-50%)",zIndex:3,display:"flex",gap:8,padding:6,borderRadius:14,background:"rgba(20,18,40,0.72)",backdropFilter:"blur(6px)",pointerEvents:"auto"},P={border:"none",borderRadius:10,padding:"8px 16px",fontWeight:700,fontSize:14,color:"#cfc9ee",background:"transparent",cursor:"pointer"},T={...P,color:"#fff",background:"#6c5ce7"},G={position:"absolute",inset:0,zIndex:4,display:"flex",alignItems:"center",justifyContent:"center",background:"rgba(0,0,0,0.5)",pointerEvents:"none"},m={pointerEvents:"auto"},N={position:"absolute",inset:0,zIndex:1,display:"flex",flexDirection:"column",alignItems:"center",justifyContent:"center",textAlign:"center",padding:24};function $(r){let{container:n,client:t,modules:o}=r;n.style.position="relative";let s=document.createElement("div");Object.assign(s.style,{position:"absolute",inset:"0",zIndex:"0",pointerEvents:"none"});let a=document.createElement("div");Object.assign(a.style,{position:"absolute",inset:"0",zIndex:"1"}),n.append(s,a);let c=S(),v=g(s),d=h(o,{client:t,events:c,surface:v}),p=createRoot(a);return p.render(jsx(IDosGamesProvider,{client:t,children:jsx(StatusProvider,{children:jsx(E,{registrations:d})})})),{unmount(){p.unmount(),s.remove(),a.remove();}}}export{E as HostShell,u as SceneStage,S as createSharedEventBus,g as createSurfaceAllocator,$ as mountHost,h as runModules};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@idosgames/app-shell",
+  "version": "0.1.0",
+  "description": "The host runtime for composable modules: module registry, shared event bus, surface allocator, scene stage, and the React Mode Router shell. A project seeds one host shell and plugs N modules into it.",
+  "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/app-shell"
+  },
+  "bugs": {
+    "url": "https://github.com/iDos-Games/iDosGamesSDK_TS/issues"
+  },
+  "keywords": [
+    "idosgames",
+    "sdk",
+    "host",
+    "shell",
+    "modules",
+    "plugin"
+  ],
+  "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"
+  },
+  "//": "react/react-dom are consumer-provided peers. @idosgames/* are real ranges pinned in step with those packages.",
+  "dependencies": {
+    "@idosgames/core": "^0.1.1",
+    "@idosgames/module-sdk": "^0.1.0",
+    "@idosgames/react": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1 || ^19.0.0",
+    "react-dom": "^18.3.1 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  }
+}