@makefully/adaptfully 5.1.0 → 5.1.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.1.1 — 2026-11-05
+
+### Added
+
+- **`host.onEnvironment()`** — `car-host` forwards Capacitor CarGames `environment` events (`phone`, `android_auto`, `aaos`) and re-queries `getEnvironment()` on activity resume so a game can restore phone UI while Android Auto stays connected.
+
 ## 5.1.0 — 2026-11-05
 
 ### Added

package/docs/host.md

@@ -18,6 +18,7 @@ host.onPause((paused) => { /* mute / pause gameplay */ });
 host.onCaptionsMuted?.((muted) => { /* … */ });
 host.onVolume?.('music', (level) => { /* 0–1 */ });
 host.onUxRestrictions?.((info) => { /* car only */ });
+host.onEnvironment?.((environment) => { /* car: phone | android_auto | aaos */ });
 
 host.setFeatures({ sound: true, captions: true });
 host.notifyProgress(0.5, { stage: 'assets' });
@@ -77,7 +78,7 @@ Requires Capacitor packager + `platforms.<key>.carGames` (see Wrapfully README
 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.
+4. Prefer `host.getEnvironment()` / `host.onEnvironment()` over sniffing user agents when you need Auto vs phone vs AAOS. `onEnvironment` fires when the activity moves between the car display and the phone, including while Android Auto stays connected. Resume also re-queries `getEnvironment()`.
 
 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.
 

package/lib/runtime/host/_helpers.js

@@ -5,7 +5,7 @@
  *
  * 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?),
+ *   onUxRestrictions?(cb), onEnvironment?(cb), setFeatures(features), notifyLoaded(), notifyProgress(p, detail?),
  *   notifyEndGame?(payload?), send(event, data?)
  */
 (function registerHostHelpers(ns) {

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

@@ -5,6 +5,7 @@
  * Requires Wrapfully `platforms.<key>.carGames` and `@makefully/capacitor-car-games`.
  *
  * Maps Cap App pause/resume + CarGames UX restrictions → onPause.
+ * Forwards CarGames `environment` (and re-queries it on resume) → onEnvironment.
  */
 (function registerCarHost(ns) {
     const { helpers } = ns.host;
@@ -38,8 +39,10 @@
             sfx: [],
         };
         const uxListeners = [];
+        const environmentListeners = [];
         let features = null;
         let paused = false;
+        let environment = null;
         /** @type {Array<() => void>} */
         const cleanups = [];
 
@@ -52,13 +55,50 @@
             helpers.emit(pauseListeners, paused);
         }
 
+        function emitEnvironment(next) {
+            const value = next ? String(next) : 'phone';
+            if (value === environment) {
+                return;
+            }
+            environment = value;
+            helpers.emit(environmentListeners, value);
+        }
+
+        function readPluginEnvironment(result) {
+            if (result && typeof result === 'object' && result.environment) {
+                return String(result.environment);
+            }
+            return String(result || 'phone');
+        }
+
+        function refreshEnvironment() {
+            const car = resolveCarGamesPlugin();
+            if (!car || typeof car.getEnvironment !== 'function') {
+                emitEnvironment('phone');
+                return Promise.resolve('phone');
+            }
+            return Promise.resolve(car.getEnvironment())
+                .then((result) => {
+                    const value = readPluginEnvironment(result);
+                    emitEnvironment(value);
+                    return value;
+                })
+                .catch(() => {
+                    emitEnvironment('phone');
+                    return 'phone';
+                });
+        }
+
         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));
+                const resumeHandle = app.addListener('resume', () => {
+                    setPaused(false);
+                    refreshEnvironment();
+                });
                 cleanups.push(() => {
                     pauseHandle?.then?.((h) => h?.remove?.());
                     pauseHandle?.remove?.();
@@ -80,6 +120,9 @@
                         setPaused(true);
                     }
                 });
+                const environmentHandle = car.addListener('environment', (event) => {
+                    emitEnvironment(event?.environment || 'phone');
+                });
                 cleanups.push(() => {
                     pauseHandle?.then?.((h) => h?.remove?.());
                     pauseHandle?.remove?.();
@@ -88,6 +131,10 @@
                     uxHandle?.then?.((h) => h?.remove?.());
                     uxHandle?.remove?.();
                 });
+                cleanups.push(() => {
+                    environmentHandle?.then?.((h) => h?.remove?.());
+                    environmentHandle?.remove?.();
+                });
             }
         }
 
@@ -129,18 +176,11 @@
             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');
+                return refreshEnvironment();
+            },
+
+            onEnvironment(cb) {
+                return helpers.subscribe(environmentListeners, cb);
             },
 
             onPause(cb) {

package/package.json

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