@energy8platform/game-engine 0.28.0 → 0.30.0

package/src/host/createSlotGame.ts

@@ -8,6 +8,7 @@ import type { CreateSlotGameOptions, SlotGameHandle } from './types';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
 import type { ShellMode } from '@energy8platform/shell/pixi';
 import type { SceneApi, SlotSceneController } from './sceneController';
+import type { FreeSpinsView } from './freeSpinsCounter';
 
 /**
  * One-call slot bootstrap: preboot → (optional Stake bridge) → GameApplication
@@ -37,7 +38,18 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         availableClose: false,
         title: shell.t('Something went wrong'),
         body: shell.t(message),
-        actions: [{ title: shell.t('Reload'), on: () => { try { location.reload(); } catch { /* non-browser */ } } }],
+        actions: [
+          {
+            title: shell.t('Reload'),
+            on: () => {
+              try {
+                location.reload();
+              } catch {
+                /* non-browser */
+              }
+            },
+          },
+        ],
       });
       return;
     }
@@ -61,7 +73,9 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     const launch = classifyStakeLaunch(location.href);
     if (launch === 'blocked') {
       fatal('Invalid game server address. Please relaunch the game from the lobby.');
-      throw new Error('createSlotGame: refusing to run — Stake launch with a missing or invalid rgs_url');
+      throw new Error(
+        'createSlotGame: refusing to run — Stake launch with a missing or invalid rgs_url',
+      );
     }
     isStakeNow = launch === 'stake';
     if (isStakeNow) {
@@ -149,7 +163,8 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // ACK the result AFTER the scene animates it (the scene calls host.ack()). On Stake this
     // triggers /wallet/end-round so a winning round settles post-animation instead of staying
     // open and blocking the next spin.
-    ack: (raw) => game.platformSession!.playAck(raw as import('@energy8platform/platform-core').PlayResultData),
+    ack: (raw) =>
+      game.platformSession!.playAck(raw as import('@energy8platform/platform-core').PlayResultData),
   });
 
   if (opts.shell) {
@@ -187,7 +202,9 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       try {
         const { lookupCurrency } = await import('@energy8platform/stake-bridge');
         currencyMeta = lookupCurrency(opts.model.spec.currency);
-      } catch { /* stake-bridge not installed — resolveCurrency falls back to the code */ }
+      } catch {
+        /* stake-bridge not installed — resolveCurrency falls back to the code */
+      }
     }
     const runtime = {
       balance,
@@ -209,14 +226,18 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       const cc = config?.currency as { code?: string; symbol?: string } | undefined;
       console.info(
         `[e8] currency → bridge.code=${cc?.code ?? '∅'} bridge.symbol=${cc?.symbol ?? '∅'} ` +
-        `| spec=${opts.model.spec.currency ?? '∅'} ` +
-        `| RESOLVED.symbol=${runtime.currency?.symbol ?? '∅'} pos=${runtime.currency?.position ?? '∅'}`,
+          `| spec=${opts.model.spec.currency ?? '∅'} ` +
+          `| RESOLVED.symbol=${runtime.currency?.symbol ?? '∅'} pos=${runtime.currency?.position ?? '∅'}`,
       );
     }
     // pixi-shell mounts its root onto the engine's unscaled, screen-space UI layer (above the
     // scaled world/scene root) so the control bar fills the real screen, not the letterboxed game.
     // The host adds the mount target (`app`) + parent; buildShellConfig produces everything else.
-    const pixiShellCfg: import('@energy8platform/shell/pixi').PixiShellConfig = { ...buildShellConfig(opts.shell, opts.model, runtime), app: game.app, parent: game.uiLayer };
+    const pixiShellCfg: import('@energy8platform/shell/pixi').PixiShellConfig = {
+      ...buildShellConfig(opts.shell, opts.model, runtime),
+      app: game.app,
+      parent: game.uiLayer,
+    };
     // The game may swap in its own shell (a custom renderer over the same core) via shellFactory;
     // default is the built-in Pixi shell. The host drives whichever it gets through the Shell contract.
     shell = (opts.shellFactory ?? createPixiShell)(pixiShellCfg);
@@ -229,21 +250,34 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // async win credit (/wallet/end-round, after the final ack) paints when it lands. `balanceGate`
     // is the single source for both the displayed balance and `ensureAffordable`.
     const balanceGate = createBalanceGate((b) => shell!.setBalance(b), balance);
-    ps?.on('balanceUpdate', (d: { balance: number }) => { balanceGate.onBalance(d.balance); });
+    ps?.on('balanceUpdate', (d: { balance: number }) => {
+      balanceGate.onBalance(d.balance);
+    });
 
     // Live turbo level (0..3) — read fresh on each ctx.turbo access so a mid-round toggle is honoured.
     let currentTurbo = shell.state.turbo;
-    shell.on('turboChange', (level: number) => { currentTurbo = level; gameScene()?.onTurboChanged?.(level); });
+    shell.on('turboChange', (level: number) => {
+      currentTurbo = level;
+      gameScene()?.onTurboChanged?.(level);
+    });
     // Double-tap-to-skip is a game-level option (default on), set once via createSlotGame({ skipGesture }).
     const skipEnabled = opts.skipGesture ?? true;
 
     // Shell settings → engine state. Sound/volume map onto the AudioManager.
     shell.on('settingChange', ({ key, value }: { key: string; value: unknown }) => {
       switch (key) {
-        case 'sound': value ? game.audio.unmuteAll() : game.audio.muteAll(); break;
-        case 'master': game.audio.setMasterVolume(Number(value)); break;
-        case 'music': game.audio.setVolume('music', Number(value)); break;
-        case 'sfx': game.audio.setVolume('sfx', Number(value)); break;
+        case 'sound':
+          value ? game.audio.unmuteAll() : game.audio.muteAll();
+          break;
+        case 'master':
+          game.audio.setMasterVolume(Number(value));
+          break;
+        case 'music':
+          game.audio.setVolume('music', Number(value));
+          break;
+        case 'sfx':
+          game.audio.setVolume('sfx', Number(value));
+          break;
       }
     });
 
@@ -267,11 +301,21 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     sceneApi = {
       audio: createSceneAudio(game.audio),
       overlay: overlayCtl.overlay,
-      shell: { get safeArea() { return shell!.safeArea; } },
+      shell: {
+        get safeArea() {
+          return shell!.safeArea;
+        },
+      },
       formatAmount: (v) => shell!.formatWin(v),
-      get bet() { return currentBet; },
-      get mode() { return opts.model.modeMap['spin'] ?? 'BASE'; },
-      get turbo() { return currentTurbo; },
+      get bet() {
+        return currentBet;
+      },
+      get mode() {
+        return opts.model.modeMap['spin'] ?? 'BASE';
+      },
+      get turbo() {
+        return currentTurbo;
+      },
     };
 
     const roleOf = (action: string) => opts.model.spec.actions[action]?.role;
@@ -284,7 +328,9 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       action,
       mode: opts.model.modeMap[action] ?? action.toUpperCase(),
       formatAmount: (v) => shell!.formatWin(v),
-      get turbo() { return currentTurbo; },
+      get turbo() {
+        return currentTurbo;
+      },
     });
     // Play-error + connection handling. A play rejection is classified into a player-facing modal
     // (ACTIVE_SESSION_EXISTS → Reload, etc.) instead of a misleading reconnect overlay; the reconnect
@@ -300,12 +346,33 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         title: shell!.t(v.title),
         body: shell!.t(v.body),
         actions: v.reload
-          ? [{ title: shell!.t('Reload'), on: () => { try { window.location.reload(); } catch { /* non-browser */ } } }]
-          : [{ title: shell!.t('OK'), on: () => { playErrorOpen = false; } }],
+          ? [
+              {
+                title: shell!.t('Reload'),
+                on: () => {
+                  try {
+                    window.location.reload();
+                  } catch {
+                    /* non-browser */
+                  }
+                },
+              },
+            ]
+          : [
+              {
+                title: shell!.t('OK'),
+                on: () => {
+                  playErrorOpen = false;
+                },
+              },
+            ],
       });
     };
     ps?.on('connectionStateChanged', (s: { status: string }) => {
-      if (s.status === 'restored') { if (!playErrorOpen) shell!.closeModal(); return; }
+      if (s.status === 'restored') {
+        if (!playErrorOpen) shell!.closeModal();
+        return;
+      }
       if (playErrorOpen) return; // a play-error modal owns the screen — don't mask it with "reconnecting"
       shell!.openModal({
         availableClose: false,
@@ -327,7 +394,10 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     const skip = createDoubleTapSkip({
       enabled: () => skipEnabled,
       active: () => presenting,
-      onSkip: () => { currentSegmentAbort?.abort(); gameScene()?.onSkip?.(); },
+      onSkip: () => {
+        currentSegmentAbort?.abort();
+        gameScene()?.onSkip?.();
+      },
     });
     // Listen for taps on the scene root (game.worldRoot — the scaled scene container). The shell
     // lives on the sibling uiLayer, so its bar taps never reach worldRoot — taps here are the play area.
@@ -346,9 +416,9 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         return () => document.removeEventListener('visibilitychange', cb);
       },
       onHidden: () => {
-        game.app.ticker.stop();    // freezes tweens, onUpdate, in-flight onSpin animation
-        game.audio.duckMusic(0);   // silence music (ducked to 0; restored on resume)
-        stopAutoplay();            // hold autoplay — don't start the next auto-round
+        game.app.ticker.stop(); // freezes tweens, onUpdate, in-flight onSpin animation
+        game.audio.duckMusic(0); // silence music (ducked to 0; restored on resume)
+        stopAutoplay(); // hold autoplay — don't start the next auto-round
         gameScene()?.onPause?.();
       },
       onVisible: () => {
@@ -358,6 +428,28 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       },
     });
 
+    /** Push a bonus segment's readout to the shell bar. Default (no `opts.bonus`) = the free-spins
+     *  counter (label 'Free spins', value current/total). With `opts.bonus`, the game supplies the
+     *  label + value string (adventure / hold-and-spin / respins) and we drive the generic 'bonus'
+     *  hero instead — the shell stays free of any per-game bonus concept. */
+    const applyBonusReadout = (result: T, view: FreeSpinsView, mode: string): void => {
+      const b = opts.bonus;
+      if (!b) {
+        shell!.setFreeSpins(view);
+        return;
+      }
+      const label = typeof b.label === 'function' ? b.label(mode) : (b.label ?? 'Free spins');
+      const value = b.readout
+        ? b.readout(result, { view, mode })
+        : view.current == null
+          ? String(view.total)
+          : `${view.current} / ${view.total}`;
+      shell!.setBonus({ label, value, totalWin: view.totalWin });
+    };
+    /** The mode entered via setMode for a bonus — 'bonus' when the game customises the readout,
+     *  else 'freeSpins' (the back-compat default the shell already renders). */
+    const bonusShellMode: ShellMode = opts.bonus ? 'bonus' : 'freeSpins';
+
     /** Drive a full round (trigger + drain) against the current scene. HUD readouts (win + balance)
      *  update only AFTER each onSpin(), per the HUD-timing requirement. */
     const playRound = (action: string) => {
@@ -367,6 +459,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       // (growing on retriggers) + cumulative win per spin. `inBonus` gates the per-spin counter so
       // the trigger segment (rendered by onSpin before onEnterMode) doesn't count as a free spin.
       let inBonus = false;
+      let bonusMode = ''; // the mode string captured on bonus-enter, reused for each settled spin
       let prevWin = 0; // cumulative win up to the previous segment — the WIN readout shows the delta
       const fsCounter = createFreeSpinsCounter();
       shell!.setBusy(true); // block re-spin / spacebar while the round plays out
@@ -376,13 +469,18 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       return runRound<T>(
         {
           // Suppress the debit paint from play() until this segment's afterPresent (HUD timing).
-          play: (a, b, rid) => { balanceGate.beginPlay(); return slotPlay.play(a, b, rid); },
+          play: (a, b, rid) => {
+            balanceGate.beginPlay();
+            return slotPlay.play(a, b, rid);
+          },
           ack: slotPlay.ack,
           scene,
           context: makeContext,
           roleOf,
           // Hand the host the per-segment AbortController so a double-tap can skip the live segment.
-          beforeSegment: (ac) => { currentSegmentAbort = ac; },
+          beforeSegment: (ac) => {
+            currentSegmentAbort = ac;
+          },
           onSpinStart: () => scene.onSpinStart?.(),
           onSpinEnd: (last, ctx) => scene.onSpinEnd?.(last, ctx),
           afterPresent: (r) => {
@@ -391,12 +489,22 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
             shell!.setWin(r.totalWin - prevWin);
             prevWin = r.totalWin;
             balanceGate.afterPresent();
-            if (inBonus) shell!.setFreeSpins(fsCounter.spin(r.freeSpins?.awarded ?? 0, r.totalWin));
+            if (inBonus)
+              applyBonusReadout(
+                r,
+                fsCounter.spin(r.freeSpins?.awarded ?? 0, r.totalWin),
+                bonusMode,
+              );
           },
           onEnterMode: async (trigger, ctx) => {
             inBonus = true;
-            shell!.setMode('freeSpins');
-            shell!.setFreeSpins(fsCounter.enter(trigger.freeSpins?.awarded ?? trigger.freeSpins?.total ?? 0));
+            bonusMode = ctx.mode;
+            shell!.setMode(bonusShellMode);
+            applyBonusReadout(
+              trigger,
+              fsCounter.enter(trigger.freeSpins?.awarded ?? trigger.freeSpins?.total ?? 0),
+              bonusMode,
+            );
             await scene.onEnterMode?.(trigger, ctx);
           },
           onExitMode: async (last, ctx) => {
@@ -406,7 +514,12 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
           },
         },
         action,
-      ).catch(showPlayError).finally(() => { presenting = false; shell!.setBusy(false); });
+      )
+        .catch(showPlayError)
+        .finally(() => {
+          presenting = false;
+          shell!.setBusy(false);
+        });
     };
 
     /**
@@ -444,9 +557,15 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       let prevWin = 0; // cumulative win up to the previous segment — WIN readout shows the delta
       const applySegment = async (): Promise<void> => {
         // A recovered open round with remaining segments is a bonus → show FS mode + counter.
-        if (!inBonus && !r.complete) { inBonus = true; shell!.setMode('freeSpins'); }
+        if (!inBonus && !r.complete) {
+          inBonus = true;
+          shell!.setMode(bonusShellMode);
+        }
         if (animate) await scene.onSpin(r, ctx);
-        if (inBonus) { const v = fsView(raw, r.totalWin); if (v) shell!.setFreeSpins(v); }
+        if (inBonus) {
+          const v = fsView(raw, r.totalWin);
+          if (v) applyBonusReadout(r, v, ctx.mode);
+        }
         shell!.setWin(r.totalWin - prevWin); // THIS spin's win, not the cumulative bonus total
         prevWin = r.totalWin;
         ps!.playAck(raw); // settles via /wallet/end-round on the FINAL segment
@@ -455,8 +574,11 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       try {
         await applySegment();
         while (!r.complete && r.nextActions && r.nextActions.length > 0) {
-          raw = (await ps.play({ action: r.nextActions[0], bet: ctx.bet, roundId: r.roundId })) as
-            import('@energy8platform/platform-core').PlayResultData;
+          raw = (await ps.play({
+            action: r.nextActions[0],
+            bet: ctx.bet,
+            roundId: r.roundId,
+          })) as import('@energy8platform/platform-core').PlayResultData;
           r = enrichRoundMeta(opts.normalize(raw), raw);
           await applySegment();
         }
@@ -468,13 +590,18 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
 
     if (mode === 'base') {
       let activeFeature: string | null = null;
-      shell.on('featureActivate', ({ id }: { id: string }) => { activeFeature = id; });
-      shell.on('featureDeactivate', ({ id: _id }: { id: string }) => { activeFeature = null; });
+      shell.on('featureActivate', ({ id }: { id: string }) => {
+        activeFeature = id;
+      });
+      shell.on('featureDeactivate', ({ id: _id }: { id: string }) => {
+        activeFeature = null;
+      });
 
       const { stakeForAction } = await import('./shellConfig');
       // Guard a play: if the stake exceeds the balance, show a shell modal and DON'T play.
       const ensureAffordable = (action: string): boolean => {
-        if (stakeForAction(opts.model, action, currentBet) <= balanceGate.balance + 1e-9) return true;
+        if (stakeForAction(opts.model, action, currentBet) <= balanceGate.balance + 1e-9)
+          return true;
         shell!.openModal({
           availableClose: true,
           title: shell!.t('Insufficient balance'),
@@ -489,7 +616,10 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         if (!ensureAffordable(action)) return;
         void playRound(action);
       });
-      shell.on('betChange', (bet: number) => { currentBet = bet; gameScene()?.onBetChanged?.(bet); });
+      shell.on('betChange', (bet: number) => {
+        currentBet = bet;
+        gameScene()?.onBetChanged?.(bet);
+      });
       shell.on('buyBonusSelect', ({ id }: { id: string }) => {
         if (!ensureAffordable(id)) return;
         void playRound(id);
@@ -519,7 +649,11 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         if (resumeOffered || !shell || !gameScene()) return;
         resumeOffered = true;
         let snap: import('@energy8platform/platform-core').PlayResultData | null = null;
-        try { snap = await ps?.getState() ?? null; } catch { snap = null; }
+        try {
+          snap = (await ps?.getState()) ?? null;
+        } catch {
+          snap = null;
+        }
         if (!snap) return;
         shell.openModal({
           availableClose: false,
@@ -527,13 +661,25 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
           body: shell.t('You have an unfinished round. Continue it or finish it now?'),
           actions: [
             // Continue: replay the round from the start with animation, then settle.
-            { title: shell.t('Continue'), on: () => { void resumeDrain(snap!, true); } },
+            {
+              title: shell.t('Continue'),
+              on: () => {
+                void resumeDrain(snap!, true);
+              },
+            },
             // Finish: fast-forward the remaining segments (no animation) to settle the win now.
-            { title: shell.t('Finish'), on: () => { void resumeDrain(snap!, false); } },
+            {
+              title: shell.t('Finish'),
+              on: () => {
+                void resumeDrain(snap!, false);
+              },
+            },
           ],
         });
       };
-      game.scenes.on('change', () => { void offerResume(); });
+      game.scenes.on('change', () => {
+        void offerResume();
+      });
       void offerResume();
     } else {
       const stakeMode = stakeBridge?.replayMode ?? 'BASE';

package/src/host/overlayController.ts

@@ -10,6 +10,9 @@ interface OverlayDeps {
 
 interface ActiveOverlay {
   layer: Container;
+  /** The scene-owned content container from `build` — re-laid-out on resize. */
+  content: Container;
+  onResize: OverlayShowOptions['onResize'];
   resolve(): void;
   timer: ReturnType<typeof setTimeout> | null;
   dim: number;
@@ -58,7 +61,7 @@ export function createOverlayController(deps: OverlayDeps): {
 
       return new Promise<void>((resolve) => {
         const dimValue = opts.dim ?? 0.0001;
-        current = { layer, resolve, timer: null, dim: dimValue };
+        current = { layer, content, onResize: opts.onResize, resolve, timer: null, dim: dimValue };
         const closeOn = opts.closeOn ?? 'tap';
         if (closeOn === 'tap') hit.on('pointertap', teardown);
         if (typeof opts.autoCloseMs === 'number') {
@@ -75,6 +78,7 @@ export function createOverlayController(deps: OverlayDeps): {
       if (!current) return;
       const hit = current.layer.getChildAt(0) as Graphics;
       hit.clear().rect(0, 0, w, h).fill({ color: 0x000000, alpha: current.dim });
+      current.onResize?.(current.content, { width: w, height: h });
     },
     destroy(): void { teardown(); },
   };

package/src/host/sceneController.ts

@@ -30,6 +30,10 @@ export interface SceneAudio {
 export interface OverlayShowOptions {
   /** Draw the overlay content into `container` (sized to the canvas). */
   build(container: Container, size: { width: number; height: number }): void;
+  /** Re-layout the same `container` when the canvas resizes while the overlay is open.
+   *  Receives the content container from `build` and the new size. Optional — omit for
+   *  overlays that self-center or don't care about resize. */
+  onResize?(container: Container, size: { width: number; height: number }): void;
   /** Auto-close after N ms (combine with closeOn — whichever fires first). */
   autoCloseMs?: number;
   /** Dismiss on a single tap. Default 'tap'. Set false to require an explicit close(). */

package/src/host/types.ts

@@ -7,7 +7,27 @@ import type { AudioConfig, ScaleMode, Orientation, SceneConstructor } from '../t
 import type { BookAdapter, AdapterModule, StakeBridge } from '@energy8platform/stake-bridge';
 import type { GameApplication } from '../core';
 import type { SlotShellOptions } from './shellConfig';
-import type { SlotSpinResultBase, SlotResultNormalizer } from '@energy8platform/platform-core/slot-result';
+import type {
+  SlotSpinResultBase,
+  SlotResultNormalizer,
+} from '@energy8platform/platform-core/slot-result';
+import type { FreeSpinsView } from './freeSpinsCounter';
+
+/** Turns a bonus segment into the bar readout for games whose bonus ISN'T a plain free-spins
+ *  counter (adventure, hold-and-spin, respins). The shell shows a host-driven hero + Total Win in
+ *  ANY bonus; this only customises the label + counter VALUE. Omit `bonus` entirely and the host
+ *  falls back to the free-spins default (label 'Free spins', value current/total, retrigger-aware). */
+export interface BonusReadoutConfig<T extends SlotSpinResultBase = SlotSpinResultBase> {
+  /** Bar label (localized by the shell, so a game i18n entry is honoured). A string, or a function
+   *  of the current mode (e.g. `m => m === 'ADVENTURE' ? 'Adventure' : 'Free spins'`).
+   *  Default: 'Free spins'. */
+  label?: string | ((mode: string) => string);
+  /** Format the counter VALUE string from the settled segment. `view` is the host's default
+   *  free-spins counter (current/total, retrigger-aware) — use it for the common case, or ignore it
+   *  and read your own fields off `result` (respins left, coins collected, a multiplier).
+   *  Default: `view.current == null ? String(view.total) : `${view.current} / ${view.total}``. */
+  readout?: (result: T, ctx: { view: FreeSpinsView; mode: string }) => string;
+}
 
 export interface StakeIntegration {
   /** The game's BookAdapter (or its module). modeMap + gameId come from the model. */
@@ -58,6 +78,9 @@ export interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinRe
   dev?: boolean;
   stake?: StakeIntegration;
   shell?: SlotShellOptions;
+  /** Customise the bonus bar readout for games whose bonus isn't plain free spins (adventure,
+   *  hold-and-spin, respins). Omit for the free-spins default. See `BonusReadoutConfig`. */
+  bonus?: BonusReadoutConfig<T>;
   /** Override how the control-bar shell is built. The host resolves the full shell config (theme,
    *  features, gameInfo, currency, balance) and the Pixi mount (`app`/`parent`) and hands it to this
    *  factory; return any `Shell` — e.g. `createShell({ renderer: new MyRenderer(...), ...config })`