@makefully/adaptfully 5.0.7 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.1.0 — 2026-11-05
+
+### Added
+
+- **Host registrations** — `springroll-host`, `car-host`, and `noop-host` expose a shared `adaptfully.get('host')` contract (pause, features, loaded/progress, environment) so games can target SpringrollContainer and Capacitor car shells without branching on Bellhop vs Cap plugins. See [`docs/host.md`](docs/host.md).
+- **`platforms.<name>.carGames`** — control field (`true` or `{ androidAuto, automotive }`) required when registering `car-host`; validated by the Capacitor packager.
+
+## 5.0.8 — 2026-10-22
+
+### Fixed
+
+- **Scoped package gameIds** — `buildGameId()` / `sanitizeFsSegment()` flatten `@scope/name` (and `\`) so Yap `gameId`, extract/prebuild folder segments, and saved zip/report names stay single path segments (e.g. `makefully-fancifully-0.1.0`).
+
 ## 5.0.7 — 2026-10-07
 
 ### Added

package/README.md

@@ -141,6 +141,16 @@ Games should call `adaptfully.has('analytics')` before `get` during rollout if o
 | `social-auth` | `adaptfully.register('auth', adaptfully.auth.Social)` | Capacitor (via [@capgo/capacitor-social-login](https://github.com/Cap-go/capacitor-social-login)) |
 | `dev-auth` | `adaptfully.register('auth', adaptfully.auth.Dev)` | Local / testing |
 
+### Host plugins
+
+| Plugin key | Registration | Runtime |
+|------------|--------------|---------|
+| `springroll-host` | `adaptfully.register('host', adaptfully.host.Springroll())` | SpringrollContainer / Bellhop |
+| `car-host` | `adaptfully.register('host', adaptfully.host.Car())` | Capacitor parked games (Android Auto / AAOS; requires `carGames`) |
+| `noop-host` | `adaptfully.register('host', adaptfully.host.Noop())` | Local / no shell |
+
+See [`docs/host.md`](docs/host.md) for the shared host contract and SpringRoll migration notes.
+
 Use plugin keys in `config.platforms.<platform>.registrations`. Custom deploy scripts use a path relative to the deploy folder instead:
 
 ```json
@@ -459,10 +469,12 @@ Place two layered PNG files in `./assets/meta/` (packaged as `meta/` in the zip)
 |------|---------|
 | `icon-foreground.png` | Foreground layer (typically the character or subject) |
 | `icon-background.png` | Background layer (typically the scene or environment) |
+| `promo-horizontal.png` | Optional landscape Open Graph / share image (recommended **1200×630**). Also used for landscape Apple startup images when present. |
+| `twitter-card.png` (or `.jpg`) | Optional still for X/Twitter **player** cards when `config.twitterCard` is `"player"` (recommended square matching `twitterPlayer` size, e.g. **480×480**). |
 
 The build server composites the foreground over the background, applies a binding/logo overlay, and generates the icon sizes each platform needs.
 
-**Recommended format:** 1536×1536 pixel square PNGs for both files. Images with other dimensions are scaled to 1536×1536 automatically, but matching the target size produces the sharpest results.
+**Recommended format:** 1536×1536 pixel square PNGs for both icon layers. Images with other dimensions are scaled to 1536×1536 automatically, but matching the target size produces the sharpest results.
 
 Missing icons do not fail the Adaptfully client: check the `WARNING missing layered icon(s)` log line and replace the placeholders before a store release.
 
@@ -520,7 +532,9 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
 | `publisherEmailAddress` | Optional | Contact email |
 | `scope` | Web/PWA | Base URL scope for the web app |
 | `themeColor` | Capacitor, Electron, UWP, web | Loading screen / theme color |
-| `twitterId` | Web | Twitter handle for meta tags |
+| `twitterId` | Web/PWA | X/Twitter `@handle` for meta tags (`twitter:site`; **required** when `twitterCard` is `"player"`) |
+| `twitterCard` | Web/PWA | Optional `"player"` for X player cards; default is summary large image |
+| `twitterPlayer` | Web/PWA | Optional `{ url?, width?, height?, image? }` for player cards (defaults: `og:url`, 480×480, `meta/twitter-card.*` or promo) |
 | `deployFolder` | Client | Neutral deploy directory staged before prebuild (default: `deploy`) |
 | `htmlInjections` | Prebuild | Deploy-relative HTML paths to inject (default: `["index.html"]`) |
 | `outputFolder` | Client | Prebuild output root (default: `output`) |
@@ -530,7 +544,8 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
 | `platforms.<name>.packager` | Prebuild | `web` (default), `electron`, or `capacitor` — selects the packager class that adds platform-specific files during prebuild |
 | `platforms.<name>.steamId` | Electron + steam-auth | Steamworks app ID baked into `preload.js` (client). Upload app IDs belong in the Steam deployment `manifest.json` |
 | `platforms.<name>.socialLogin` | Capacitor + social-auth | Capgo provider config (`providers`, `google.webClientId`, `apple.clientId`, optional `defaultProvider`) |
-| `platforms.<name>.<configField>` | Build/deploy | Overrides the matching top-level `config.*` default for that platform only (e.g. `platforms.android.packageName`, `platforms.ios.title`). Does not apply to control fields: `packager`, `registrations`, `builder`, `builders`, `deployments`, `steamId`, `socialLogin`, `steamworks` |
+| `platforms.<name>.carGames` | Capacitor + car-host | `true` (Android Auto + AAOS) or `{ androidAuto?, automotive? }` — Wrapfully patches parked-game Android requisites |
+| `platforms.<name>.<configField>` | Build/deploy | Overrides the matching top-level `config.*` default for that platform only (e.g. `platforms.android.packageName`, `platforms.ios.title`). Does not apply to control fields: `packager`, `registrations`, `builder`, `builders`, `deployments`, `steamId`, `socialLogin`, `steamworks`, `carGames` |
 
 Top-level `config.*` values are **defaults**. Any non-control field on `config.platforms.<name>` overrides the default when that platform is built or deployed. Example:
 

package/docs/credentials/README.md

@@ -14,6 +14,8 @@ They do not cover which OS builds the artifact.
 | Android | [android.md](./android.md) | `assets/meta/deployments/android/` |
 | Steam | [steam.md](./steam.md) | `assets/meta/deployments/steam/` |
 
+For Android Auto / AAOS parked games (`carGames` + `host: car-host`), see [android.md](./android.md#cars-android-auto--aaos-parked-games) and [`docs/host.md`](../host.md).
+
 ## Helpers
 
 | Command | Writes |

package/docs/credentials/android.md

@@ -117,6 +117,27 @@ Copy the downloaded key to `assets/meta/deployments/android/google.json`. Ensure
 - [ ] For Play uploads: `google.json` is present and the service account can access the app
 - [ ] Credential paths are gitignored
 
+## Cars (Android Auto / AAOS parked games)
+
+Optional. Enable on the Capacitor android platform:
+
+```json
+"platforms": {
+  "android": {
+    "packager": "capacitor",
+    "carGames": true,
+    "registrations": {
+      "host": "car-host"
+    }
+  }
+}
+```
+
+- `carGames: true` → both Auto + AAOS; or `{ "androidAuto": true, "automotive": true|false }`.
+- Register `host: "car-host"` and pause audio on `adaptfully.get('host').onPause` — see [`docs/host.md`](../host.md).
+- Wrapfully patches `CAR_LAUNCHER`, `appCategory="game"`, and automotive `uses-feature` (`required="false"` on the mobile track).
+- In Play Console, add **Android Auto** and **Android Automotive OS** form factors, upload to a testing track, and test with the Desktop Head Unit (DHU) + AAOS emulator before open testing.
+
 ## Notes
 
 - Prefer **project-owned** keystores so debug installs stay reproducible across machines.

package/docs/host.md

@@ -0,0 +1,92 @@
+# Host bridge (`adaptfully.get('host')`)
+
+Games should talk to the **platform shell** through Adaptfully’s `host` registration instead of branching on SpringRoll Bellhop vs Capacitor plugins. Two shells share one contract today; more can be added later.
+
+## Contract
+
+```js
+const host = adaptfully.get('host');
+
+host.kind; // 'springroll' | 'car' | 'noop'
+
+await host.getEnvironment();
+// springroll → 'springroll'
+// car → 'phone' | 'android_auto' | 'aaos'
+// noop → window.gameConfig.platform || 'web'
+
+host.onPause((paused) => { /* mute / pause gameplay */ });
+host.onCaptionsMuted?.((muted) => { /* … */ });
+host.onVolume?.('music', (level) => { /* 0–1 */ });
+host.onUxRestrictions?.((info) => { /* car only */ });
+
+host.setFeatures({ sound: true, captions: true });
+host.notifyProgress(0.5, { stage: 'assets' });
+host.notifyLoaded();
+host.notifyEndGame?.();
+host.send('custom-event', payload); // escape hatch
+```
+
+Mirror of the SpringRoll / SpringrollContainer vocabulary (`features`, `loaded`, `progress` / `loading`, `endGame`, `pause`, volumes, `captionsMuted`).
+
+## Plugins
+
+| Plugin key | Registration | Shell |
+|------------|--------------|--------|
+| `springroll-host` | `adaptfully.host.Springroll()` | [SpringrollContainer](https://www.npmjs.com/package/springroll-container) / Bellhop (iframe host) |
+| `car-host` | `adaptfully.host.Car()` | Capacitor + Wrapfully `@makefully/capacitor-car-games` |
+| `noop-host` | `adaptfully.host.Noop()` | No shell I/O (local web) |
+
+### SpringRoll (`springroll-host`)
+
+After you create a `springroll.Application`, bind it:
+
+```js
+const app = new Application({ features: { sound: true } });
+const host = adaptfully.get('host');
+host.bind(app);
+host.onPause((paused) => audio.setPaused(paused));
+// … load assets …
+host.notifyLoaded();
+```
+
+`bind` wires `Application.state.pause` / volumes / captions and forwards `notify*` through `app.container.send` (same path Platypus, Alma Adventure, and Fancifully use with SpringRoll).
+
+### Car / parked games (`car-host`)
+
+Requires Capacitor packager + `platforms.<key>.carGames` (see Wrapfully README → Android → Car games, and [Android credentials](./credentials/android.md)).
+
+```json
+"android": {
+  "packager": "capacitor",
+  "carGames": true,
+  "registrations": {
+    "host": "car-host",
+    "storage": "localStorage"
+  }
+}
+```
+
+`carGames: true` enables **Android Auto + AAOS**. Object form selects subsets:
+
+```json
+"carGames": { "androidAuto": true, "automotive": false }
+```
+
+**Parked-game obligations (developer):**
+
+1. Pause gameplay **and audio** when `host.onPause(true)` (activity pause, leave car display, or AAOS UX restrictions).
+2. Do not resume audio until `onPause(false)` / parked again.
+3. Layout for car aspect ratios (avoid heavy pillarboxing on landscape Auto).
+4. Prefer `host.getEnvironment()` over sniffing user agents when you need Auto vs phone vs AAOS.
+
+Wrapfully patches the Android manifest (`CAR_LAUNCHER`, `appCategory="game"`, optional automotive feature) and installs the Cap plugin. Play Console form-factor opt-in (Android Auto + Automotive OS) remains a manual Console step.
+
+### Migrating from raw SpringRoll
+
+| Before | After |
+|--------|--------|
+| `app.state.pause.subscribe(...)` | `host.onPause(...)` after `host.bind(app)` |
+| `app.container.send('loaded')` | `host.notifyLoaded()` |
+| `app.container.send('progress', n)` | `host.notifyProgress(n)` |
+
+You can keep constructing `Application` yourself; the host adapter does not replace SpringRoll, it wraps it.

package/lib/node/artifacts.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import {buildGameId, sanitizeFsSegment} from './fs-name.js';
 
 const
     MANIFEST_NAME = 'wrapfully-build.json',
@@ -28,7 +29,7 @@ export function buildOutputDir(pkg, outputRoot = 'output') {
 export function resolveExtractRoot(outputRoot, platformKey) {
     const root = path.resolve(outputRoot);
     if (platformKey) {
-        return path.join(root, platformKey);
+        return path.join(root, sanitizeFsSegment(platformKey));
     }
     return root;
 }
@@ -95,8 +96,8 @@ export function resolveBuildArtifactDir(pkg, options = {}) {
         throw new Error(`Unable to read ${manifestPath}`);
     }
 
-    const gameId = `${pkg.name}-${pkg.version}`;
-    if (manifest.gameId && manifest.gameId !== gameId) {
+    const gameId = buildGameId(pkg.name, pkg.version);
+    if (manifest.gameId && sanitizeFsSegment(manifest.gameId) !== gameId) {
         throw new Error(
             `Build artifact is for "${manifest.gameId}" but package.json is ${gameId}. `
             + 'Run a fresh build or pass --artifact <path>.',

package/lib/node/car-games.js

@@ -0,0 +1,39 @@
+/**
+ * Normalize platforms.<key>.carGames for Cap parked-game (Android Auto / AAOS) builds.
+ *
+ * - true  → both androidAuto + automotive
+ * - object → per-flag booleans (missing key = false)
+ * - falsy → disabled
+ *
+ * @param {unknown} value
+ * @returns {{ enabled: boolean, androidAuto: boolean, automotive: boolean }}
+ */
+export function resolveCarGames(value) {
+    if (value === true) {
+        return { enabled: true, androidAuto: true, automotive: true };
+    }
+
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { enabled: false, androidAuto: false, automotive: false };
+    }
+
+    const androidAuto = value.androidAuto === true;
+    const automotive = value.automotive === true;
+    return {
+        enabled: androidAuto || automotive,
+        androidAuto,
+        automotive,
+    };
+}
+
+/**
+ * @param {string | null | undefined} platformKey
+ * @param {{ config?: { platforms?: Record<string, { carGames?: unknown }>, carGames?: unknown } }} pkg
+ * @returns {unknown}
+ */
+export function resolvePlatformCarGames(platformKey, pkg) {
+    if (platformKey && pkg?.config?.platforms?.[platformKey]?.carGames !== undefined) {
+        return pkg.config.platforms[platformKey].carGames;
+    }
+    return pkg?.config?.carGames;
+}

package/lib/node/deploy.js

@@ -14,6 +14,7 @@ import {
     resolveEncryptPublicKey,
 } from './choreCrypto.js';
 import {extractZipFile, fileLooksLikeZip} from './unzip-file.js';
+import {buildGameId} from './fs-name.js';
 
 const POLL_MS = 5000;
 
@@ -382,7 +383,7 @@ export async function send (
         } else {
             const destZip = path.join(
                 extractRoot,
-                `${pkg.name}-${pkg.version}-${stage}-${family}.zip`,
+                `${buildGameId(pkg.name, pkg.version)}-${stage}-${family}.zip`,
             );
 
             await pipeline(

package/lib/node/fs-name.js

@@ -0,0 +1,29 @@
+/**
+ * Make a single filesystem / URL path segment safe.
+ * Strips `@`, turns `/` and `\` into `-`, and removes other Windows-illegal chars
+ * so scoped npm names like `@makefully/fancifully` stay flat.
+ *
+ * @param {unknown} value
+ * @param {string} [fallback='app']
+ * @returns {string}
+ */
+export function sanitizeFsSegment(value, fallback = 'app') {
+    const cleaned = String(value ?? '')
+        .replace(/@/g, '')
+        .replace(/[/\\]+/g, '-')
+        .replace(/[<>:"|?*\u0000-\u001f]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+
+    return cleaned || fallback;
+}
+
+/**
+ * Build the Adaptfully/Wrapfully gameId from package name + version.
+ * @param {string} name
+ * @param {string} version
+ * @returns {string}
+ */
+export function buildGameId(name, version) {
+    return sanitizeFsSegment(`${name}-${version}`, 'app');
+}

package/lib/node/index.js

@@ -1,4 +1,5 @@
 export { buildOutputDir, clearStaleBuildExtract, parsePlatformList, resolveBuildArtifactDir, resolveExtractRoot } from './artifacts.js';
+export { buildGameId, sanitizeFsSegment } from './fs-name.js';
 export { createArchive, createDeployArchive, createReleaseArchive, createSourceArchive } from './archive.js';
 export { loadProjectConfig, resolveServerUrl } from './config.js';
 export {
@@ -7,6 +8,10 @@ export {
     resolveConfigForBuild,
     resolvePlatformConfig,
 } from './platform-config.js';
+export {
+    resolveCarGames,
+    resolvePlatformCarGames,
+} from './car-games.js';
 export { send } from './deploy.js';
 export {
     appendMetaIcons,

package/lib/node/packagers/base.js

@@ -298,6 +298,14 @@ export class Packager {
                 + `Set config.platforms.${platformLabel}.packager to "capacitor".`,
             );
         }
+
+        if (this.usesPlugin('car-host', { scope: 'all' }) && this.name !== 'capacitor') {
+            const platformLabel = this.platformKey ?? this.platforms[0] ?? 'unknown';
+            throw new Error(
+                `Platform "${platformLabel}" uses car-host but packager is "${this.name}". `
+                + `Set config.platforms.${platformLabel}.packager to "capacitor".`,
+            );
+        }
     }
 
     needsGameConfig() {

package/lib/node/packagers/capacitor.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Packager } from './base.js';
 import { resolvePlatformConfig } from '../platform-config.js';
+import { resolveCarGames, resolvePlatformCarGames } from '../car-games.js';
 
 const CAPACITOR_CSP = '<meta http-equiv="Content-Security-Policy" content="default-src * \'self\' data: blob: \'unsafe-inline\' \'unsafe-eval\'; style-src * \'self\' \'unsafe-inline\'; script-src * \'self\' \'unsafe-inline\' \'unsafe-eval\'; connect-src *; img-src * data: blob:; media-src * data: blob:; frame-src *;" />';
 
@@ -123,6 +124,19 @@ export class CapacitorPackager extends Packager {
             );
             validateSocialLoginConfig(config);
         }
+
+        if (this.usesPlugin('car-host')) {
+            const carGames = resolveCarGames(
+                resolvePlatformCarGames(this.platformKey, this.pkg),
+            );
+            if (!carGames.enabled) {
+                const platformLabel = this.platformKey ?? this.platforms.join(', ');
+                throw new Error(
+                    `Platform "${platformLabel}" uses car-host but platforms.${platformLabel}.carGames `
+                    + 'is not set (use true or { androidAuto, automotive }).',
+                );
+            }
+        }
     }
 
     needsGameConfig() {

package/lib/node/pipeline.js

@@ -19,6 +19,7 @@ import { googlePublishFromCli } from './google-publish.js';
 import { applePublishFromCli } from './apple-publish.js';
 import { androidKeystoreFromCli } from './android-keystore.js';
 import { appleSigningFromCli } from './apple-signing.js';
+import { buildGameId } from './fs-name.js';
 
 /** @typedef {'prebuild' | 'build' | 'deploy' | 'release'} AdaptfullyStage */
 
@@ -99,7 +100,7 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
         return { prebuiltDir, platformKey, buildSpec, extractRoot };
     }
 
-    const gameId = `${pkg.name}-${pkg.version}`;
+    const gameId = buildGameId(pkg.name, pkg.version);
     const contents = JSON.stringify(pkg);
     /** @type {{ deploymentKey: string, stage: string, family: string }[]} */
     const sent = [];

package/lib/node/platform-config.js

@@ -11,6 +11,7 @@ export const PLATFORM_CONTROL_KEYS = new Set([
     'steamId',
     'socialLogin',
     'steamworks',
+    'carGames',
 ]);
 
 /**

package/lib/node/prebuild.js

@@ -6,6 +6,7 @@ import {
 } from './registrations.js';
 import { createPackagerForPlatform } from './packagers.js';
 import { copyRecursiveSync, emptyDirSync } from './fs-utils.js';
+import { sanitizeFsSegment } from './fs-name.js';
 
 /** @typedef {'prebuild' | 'build' | 'deploy'} AdaptfullyStage */
 
@@ -38,7 +39,7 @@ export function resolveHtmlInjections(pkg) {
  */
 export function prebuildOutputDir(platformKey, pkg, outputRoot = 'output') {
     const outputFolder = pkg.config?.outputFolder || outputRoot;
-    return path.resolve(outputFolder, `${platformKey}-prebuild`);
+    return path.resolve(outputFolder, `${sanitizeFsSegment(platformKey)}-prebuild`);
 }
 
 /**

package/lib/node/registrations.js

@@ -46,6 +46,18 @@ export const STANDARD_PLUGINS = {
         scripts: ['core.js', 'analytics/_helpers.js', 'analytics/noop.js'],
         registration: (key) => `adaptfully.register('${key}', adaptfully.analytics.Noop());`,
     },
+    'springroll-host': {
+        scripts: ['core.js', 'host/_helpers.js', 'host/springroll-host.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.host.Springroll());`,
+    },
+    'car-host': {
+        scripts: ['core.js', 'host/_helpers.js', 'host/car-host.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.host.Car());`,
+    },
+    'noop-host': {
+        scripts: ['core.js', 'host/_helpers.js', 'host/noop-host.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.host.Noop());`,
+    },
 };
 
 /** Default Wrapfully builder → config.platforms key */

package/lib/node/report.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import {buildGameId} from './fs-name.js';
 
 /**
  * @param {string} builder
@@ -9,7 +10,7 @@ import path from 'node:path';
 export function printBuildReport(builder, pkg, options = {}) {
     const extractRoot = path.resolve(options.extractRoot || './output');
     const statusPath = path.join(extractRoot, 'wrapfully-status.json');
-    const legacyPath = path.join(extractRoot, `${pkg.name}-${pkg.version}-${builder}.txt`);
+    const legacyPath = path.join(extractRoot, `${buildGameId(pkg.name, pkg.version)}-${builder}.txt`);
 
     let status = null;
     if (fs.existsSync(statusPath)) {

package/lib/runtime/host/_helpers.js

@@ -0,0 +1,87 @@
+/* global window */
+
+/**
+ * Shared helpers for Adaptfully host adapters (SpringRoll, Cap car shell, noop).
+ *
+ * Host contract (stable surface games should prefer over raw SpringRoll / Cap plugins):
+ *   kind, getEnvironment(), onPause(cb), onCaptionsMuted?(cb), onVolume?(ch, cb),
+ *   onUxRestrictions?(cb), setFeatures(features), notifyLoaded(), notifyProgress(p, detail?),
+ *   notifyEndGame?(payload?), send(event, data?)
+ */
+(function registerHostHelpers(ns) {
+    ns.host = ns.host || {};
+
+    /**
+     * @param {Array<(value: unknown) => void>} listeners
+     * @param {unknown} value
+     */
+    function emit(listeners, value) {
+        for (const listener of [...listeners]) {
+            try {
+                listener(value);
+            } catch (err) {
+                console.warn('adaptfully.host listener error', err);
+            }
+        }
+    }
+
+    /**
+     * @param {Array<(value: unknown) => void>} listeners
+     * @param {(value: unknown) => void} cb
+     * @returns {() => void}
+     */
+    function subscribe(listeners, cb) {
+        if (typeof cb !== 'function') {
+            return () => {};
+        }
+        listeners.push(cb);
+        return () => {
+            const index = listeners.indexOf(cb);
+            if (index >= 0) {
+                listeners.splice(index, 1);
+            }
+        };
+    }
+
+    /**
+     * Subscribe to a SpringRoll-style Property (`subscribe` → unsubscribe handle).
+     * @param {{ subscribe?: (fn: (v: unknown) => void) => unknown } | null | undefined} prop
+     * @param {(v: unknown) => void} fn
+     * @returns {() => void}
+     */
+    function subscribeProperty(prop, fn) {
+        if (!prop || typeof prop.subscribe !== 'function') {
+            return () => {};
+        }
+        const result = prop.subscribe(fn);
+        if (typeof result === 'function') {
+            return result;
+        }
+        if (result && typeof result.unsubscribe === 'function') {
+            return () => result.unsubscribe();
+        }
+        return () => {};
+    }
+
+    /**
+     * @returns {string}
+     */
+    function environmentFromGameConfig() {
+        try {
+            const platform = window.gameConfig?.platform;
+            if (platform != null && String(platform).length > 0) {
+                return String(platform);
+            }
+        } catch {
+            // ignore
+        }
+        return 'web';
+    }
+
+    ns.host.helpers = {
+        emit,
+        subscribe,
+        subscribeProperty,
+        environmentFromGameConfig,
+    };
+}(window.adaptfully));

package/lib/runtime/host/car-host.js

@@ -0,0 +1,219 @@
+/* global window */
+
+/**
+ * Capacitor car shell host (Android Auto / AAOS parked games).
+ * Requires Wrapfully `platforms.<key>.carGames` and `@makefully/capacitor-car-games`.
+ *
+ * Maps Cap App pause/resume + CarGames UX restrictions → onPause.
+ */
+(function registerCarHost(ns) {
+    const { helpers } = ns.host;
+
+    function resolveCarGamesPlugin() {
+        const plugins = window.Capacitor?.Plugins;
+        if (plugins?.CarGames) {
+            return plugins.CarGames;
+        }
+        if (window.CarGames) {
+            return window.CarGames;
+        }
+        return null;
+    }
+
+    function resolveAppPlugin() {
+        const plugins = window.Capacitor?.Plugins;
+        if (plugins?.App) {
+            return plugins.App;
+        }
+        return null;
+    }
+
+    ns.host.Car = function carHostFactory() {
+        const pauseListeners = [];
+        const captionsListeners = [];
+        const volumeListeners = {
+            sound: [],
+            music: [],
+            vo: [],
+            sfx: [],
+        };
+        const uxListeners = [];
+        let features = null;
+        let paused = false;
+        /** @type {Array<() => void>} */
+        const cleanups = [];
+
+        function setPaused(next) {
+            const value = Boolean(next);
+            if (value === paused) {
+                return;
+            }
+            paused = value;
+            helpers.emit(pauseListeners, paused);
+        }
+
+        function attachNativeListeners() {
+            const car = resolveCarGamesPlugin();
+            const app = resolveAppPlugin();
+
+            if (app && typeof app.addListener === 'function') {
+                const pauseHandle = app.addListener('pause', () => setPaused(true));
+                const resumeHandle = app.addListener('resume', () => setPaused(false));
+                cleanups.push(() => {
+                    pauseHandle?.then?.((h) => h?.remove?.());
+                    pauseHandle?.remove?.();
+                });
+                cleanups.push(() => {
+                    resumeHandle?.then?.((h) => h?.remove?.());
+                    resumeHandle?.remove?.();
+                });
+            }
+
+            if (car && typeof car.addListener === 'function') {
+                const pauseHandle = car.addListener('pause', (event) => {
+                    const value = event?.paused;
+                    setPaused(value !== false);
+                });
+                const uxHandle = car.addListener('uxRestrictions', (event) => {
+                    helpers.emit(uxListeners, event || {});
+                    if (event && event.requiresDistractionOptimization === true) {
+                        setPaused(true);
+                    }
+                });
+                cleanups.push(() => {
+                    pauseHandle?.then?.((h) => h?.remove?.());
+                    pauseHandle?.remove?.();
+                });
+                cleanups.push(() => {
+                    uxHandle?.then?.((h) => h?.remove?.());
+                    uxHandle?.remove?.();
+                });
+            }
+        }
+
+        attachNativeListeners();
+
+        function send(event, data) {
+            const car = resolveCarGamesPlugin();
+            if (!car) {
+                return;
+            }
+            if (event === 'features' && typeof car.setFeatures === 'function') {
+                car.setFeatures({ features: data });
+                return;
+            }
+            if (event === 'loaded' && typeof car.notifyLoaded === 'function') {
+                car.notifyLoaded();
+                return;
+            }
+            if (event === 'progress' && typeof car.notifyProgress === 'function') {
+                car.notifyProgress({
+                    progress: data,
+                });
+                return;
+            }
+            if (event === 'loading' && typeof car.notifyProgress === 'function') {
+                car.notifyProgress(typeof data === 'object' ? data : { progress: data });
+                return;
+            }
+            if (event === 'endGame' && typeof car.notifyEndGame === 'function') {
+                car.notifyEndGame(data ?? {});
+                return;
+            }
+            if (typeof car.send === 'function') {
+                car.send({ event, data });
+            }
+        }
+
+        return {
+            kind: 'car',
+
+            getEnvironment() {
+                const car = resolveCarGamesPlugin();
+                if (car && typeof car.getEnvironment === 'function') {
+                    return Promise.resolve(car.getEnvironment())
+                        .then((result) => {
+                            if (result && typeof result === 'object' && result.environment) {
+                                return String(result.environment);
+                            }
+                            return String(result || 'phone');
+                        })
+                        .catch(() => 'phone');
+                }
+                return Promise.resolve('phone');
+            },
+
+            onPause(cb) {
+                const unsub = helpers.subscribe(pauseListeners, cb);
+                if (typeof cb === 'function') {
+                    cb(paused);
+                }
+                return unsub;
+            },
+
+            onCaptionsMuted(cb) {
+                return helpers.subscribe(captionsListeners, cb);
+            },
+
+            onVolume(channel, cb) {
+                const list = volumeListeners[channel];
+                if (!list) {
+                    return () => {};
+                }
+                return helpers.subscribe(list, cb);
+            },
+
+            onUxRestrictions(cb) {
+                return helpers.subscribe(uxListeners, cb);
+            },
+
+            setFeatures(next) {
+                features = next && typeof next === 'object' ? { ...next } : next;
+                if (features != null) {
+                    send('features', features);
+                }
+            },
+
+            notifyLoaded() {
+                send('loaded');
+            },
+
+            notifyProgress(progress, detail) {
+                const clamped = Math.max(0, Math.min(1, Number(progress) || 0));
+                send('progress', clamped);
+                if (detail != null) {
+                    send('loading', typeof detail === 'object'
+                        ? { ...detail, progress: clamped }
+                        : { progress: clamped, detail });
+                }
+            },
+
+            notifyEndGame(payload) {
+                send('endGame', payload);
+            },
+
+            send,
+
+            destroy() {
+                for (const cleanup of cleanups) {
+                    try {
+                        cleanup();
+                    } catch {
+                        // ignore
+                    }
+                }
+                cleanups.length = 0;
+            },
+
+            /** @internal */
+            _getState() {
+                return {
+                    features,
+                    paused,
+                    pauseListeners: pauseListeners.length,
+                    hasCarPlugin: Boolean(resolveCarGamesPlugin()),
+                };
+            },
+        };
+    };
+}(window.adaptfully));

package/lib/runtime/host/noop-host.js

@@ -0,0 +1,62 @@
+/* global window */
+
+/**
+ * No-op host — same surface as springroll-host / car-host, no shell I/O.
+ * Use for local web or platforms without a container.
+ */
+(function registerNoopHost(ns) {
+    const { helpers } = ns.host;
+
+    ns.host.Noop = function noopHostFactory() {
+        const pauseListeners = [];
+        const captionsListeners = [];
+        const volumeListeners = {
+            sound: [],
+            music: [],
+            vo: [],
+            sfx: [],
+        };
+        let features = null;
+
+        return {
+            kind: 'noop',
+
+            getEnvironment() {
+                return Promise.resolve(helpers.environmentFromGameConfig());
+            },
+
+            onPause(cb) {
+                return helpers.subscribe(pauseListeners, cb);
+            },
+
+            onCaptionsMuted(cb) {
+                return helpers.subscribe(captionsListeners, cb);
+            },
+
+            onVolume(channel, cb) {
+                const list = volumeListeners[channel];
+                if (!list) {
+                    return () => {};
+                }
+                return helpers.subscribe(list, cb);
+            },
+
+            setFeatures(next) {
+                features = next && typeof next === 'object' ? { ...next } : next;
+            },
+
+            notifyLoaded() {},
+
+            notifyProgress(_progress, _detail) {},
+
+            notifyEndGame(_payload) {},
+
+            send(_event, _data) {},
+
+            /** @internal */
+            _getState() {
+                return { features, pauseListeners: pauseListeners.length };
+            },
+        };
+    };
+}(window.adaptfully));

package/lib/runtime/host/springroll-host.js

@@ -0,0 +1,154 @@
+/* global window */
+
+/**
+ * SpringRoll / SpringrollContainer host adapter.
+ * Speaks the Bellhop vocabulary via Application.state + container.send.
+ *
+ * After creating a springroll.Application, call host.bind(app) so pause/volumes
+ * wire to Application.state and notify* go through app.container.
+ */
+(function registerSpringrollHost(ns) {
+    const { helpers } = ns.host;
+
+    const VOLUME_CHANNELS = ['sound', 'music', 'vo', 'sfx'];
+
+    /**
+     * @param {object | null | undefined} app SpringRoll Application-like
+     */
+    function containerOf(app) {
+        return app?.container || null;
+    }
+
+    ns.host.Springroll = function springrollHostFactory(options = {}) {
+        /** @type {object | null} */
+        let app = options.app || null;
+        const pauseListeners = [];
+        const captionsListeners = [];
+        /** @type {Record<string, Array<(v: unknown) => void>>} */
+        const volumeListeners = {
+            sound: [],
+            music: [],
+            vo: [],
+            sfx: [],
+        };
+        /** @type {Array<() => void>} */
+        let propertyUnsubs = [];
+        let features = options.features || null;
+
+        function tearDownProperties() {
+            for (const unsub of propertyUnsubs) {
+                try {
+                    unsub();
+                } catch {
+                    // ignore
+                }
+            }
+            propertyUnsubs = [];
+        }
+
+        function wireProperties() {
+            tearDownProperties();
+            if (!app?.state) {
+                return;
+            }
+
+            propertyUnsubs.push(helpers.subscribeProperty(app.state.pause, (v) => {
+                helpers.emit(pauseListeners, Boolean(v));
+            }));
+            propertyUnsubs.push(helpers.subscribeProperty(app.state.captionsMuted, (v) => {
+                helpers.emit(captionsListeners, Boolean(v));
+            }));
+
+            for (const channel of VOLUME_CHANNELS) {
+                const propName = `${channel}Volume`;
+                propertyUnsubs.push(helpers.subscribeProperty(app.state[propName], (v) => {
+                    helpers.emit(volumeListeners[channel], Number(v));
+                }));
+            }
+        }
+
+        if (app) {
+            wireProperties();
+        }
+
+        function send(event, data) {
+            const container = containerOf(app);
+            if (container && typeof container.send === 'function') {
+                container.send(event, data);
+            }
+        }
+
+        return {
+            kind: 'springroll',
+
+            /**
+             * Attach a SpringRoll Application (required for pause/volumes/notify*).
+             * @param {object} application
+             */
+            bind(application) {
+                app = application || null;
+                wireProperties();
+                if (features != null) {
+                    send('features', features);
+                }
+                return this;
+            },
+
+            getEnvironment() {
+                return Promise.resolve('springroll');
+            },
+
+            onPause(cb) {
+                return helpers.subscribe(pauseListeners, cb);
+            },
+
+            onCaptionsMuted(cb) {
+                return helpers.subscribe(captionsListeners, cb);
+            },
+
+            onVolume(channel, cb) {
+                const list = volumeListeners[channel];
+                if (!list) {
+                    return () => {};
+                }
+                return helpers.subscribe(list, cb);
+            },
+
+            setFeatures(next) {
+                features = next && typeof next === 'object' ? { ...next } : next;
+                if (features != null) {
+                    send('features', features);
+                }
+            },
+
+            notifyLoaded() {
+                send('loaded');
+            },
+
+            notifyProgress(progress, detail) {
+                const clamped = Math.max(0, Math.min(1, Number(progress) || 0));
+                send('progress', clamped);
+                if (detail != null) {
+                    send('loading', typeof detail === 'object'
+                        ? { ...detail, progress: clamped }
+                        : { progress: clamped, detail });
+                }
+            },
+
+            notifyEndGame(payload) {
+                send('endGame', payload);
+            },
+
+            send,
+
+            /** @internal */
+            _getState() {
+                return {
+                    bound: Boolean(app),
+                    features,
+                    pauseListeners: pauseListeners.length,
+                };
+            },
+        };
+    };
+}(window.adaptfully));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/adaptfully",
-    "version": "5.0.7",
+    "version": "5.1.0",
     "description": "Platform abstraction and Wrapfully deploy client for Makefully games",
     "type": "module",
     "main": "./lib/node/index.js",