@makefully/adaptfully 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project are documented in this file.
 
+## 3.2.0 — 2026-06-16
+
+### Added
+
+- **`config.platforms.<platform>.packager`** — `web` (default), `electron`, `cordova`, or `capacitor`. Controls which template files are added during prebuild.
+- **`lib/templates/`** — packager-specific templates (starting with `electron/main.js` and `electron/preload.js`).
+- Electron prebuild writes **`main.js`** automatically. When **`steam-auth`** is registered, Adaptfully also writes **`preload.js`** with steamworks.js init and overlay setup in `main.js`.
+- **`steam-auth` requires `packager: "electron"`** — prebuild throws if steam-auth is used on a non-electron platform or without `config.steamId`.
+
+## 3.1.1 — 2026-06-16
+
+### Added
+
+- **steam-auth** integrates with [steamworks.js](https://github.com/ceifa/steamworks.js): reads Steam ID and persona name from shell-provided bridges (`__ADAPTFULLY_STEAMWORKS__`, `steamworks`, `electronAPI`).
+- Steam auth supports `autoLogin()` and `supportsAutoLogin()` when the Steam client is available.
+
 ## 3.1.0 — 2026-06-18
 
 ### Added

package/README.md

@@ -65,7 +65,7 @@ storage.getObject('currentGame');
 | Plugin key | Registration | Runtime |
 |------------|--------------|---------|
 | `google-auth` | `adaptfully.register('auth', adaptfully.auth.Google)` | Web, Android, iOS |
-| `steam-auth` | `adaptfully.register('auth', adaptfully.auth.Steam)` | Steam / Electron |
+| `steam-auth` | `adaptfully.register('auth', adaptfully.auth.Steam)` | Steam / Electron (via [steamworks.js](https://github.com/ceifa/steamworks.js)) |
 | `dev-auth` | `adaptfully.register('auth', adaptfully.auth.Dev)` | Local dev (test user) |
 
 Use plugin keys in `config.platforms.<platform>.registrations`. Custom deploy scripts use a path relative to the deploy folder instead:
@@ -101,6 +101,40 @@ Standard plugin keys load bundled Adaptfully runtime scripts and emit an inline
 
 Wrapfully builders (`steam`, `win`, `mac`, `android`, etc.) map to platform keys via defaults (`win` → `steam`) or an explicit `builders` array on the platform config.
 
+Each platform entry may set a **`packager`** (`web`, `electron`, `cordova`, or eventually `capacitor`). Defaults to **`web`** — copy deploy and inject HTML only. **`electron`** adds `main.js` from `lib/templates/electron/` during prebuild. **`steam-auth` requires `packager: "electron"`** and `config.steamId`.
+
+```json
+{
+  "config": {
+    "steamId": 719140,
+    "platforms": {
+      "web": {
+        "packager": "web",
+        "registrations": { "auth": "google-auth" }
+      },
+      "steam": {
+        "packager": "electron",
+        "registrations": { "auth": "steam-auth" }
+      }
+    }
+  }
+}
+```
+
+#### Steam auth (`steam-auth`)
+
+When `steam-auth` is registered on an **`electron`** platform, Adaptfully prebuild writes:
+
+- **`main.js`** — Electron shell with Steam overlay enabled and a preload script wired in
+- **`preload.js`** — initializes [steamworks.js](https://github.com/ceifa/steamworks.js) with `config.steamId` and exposes `window.__ADAPTFULLY_STEAMWORKS__`
+
+The renderer `steam-auth` plugin reads the Steam ID from that bridge. When Steam is available, `autoLogin()` succeeds immediately with `{ id: steamId64, email: '' }`. Optional config keys:
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `autoLoginStorageKey` | `lastLoggedIn` | Storage key written with the Steam ID on login |
+| `steamReadyTimeoutMs` | `10000` | Max wait when a bridge exists but identity is not yet ready |
+
 ### Node API
 
 ```javascript
@@ -306,6 +340,7 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
         }
       },
       "steam": {
+        "packager": "electron",
         "registrations": {
           "auth": "steam-auth",
           "storage": "javascript/adaptfully-bridge.js"
@@ -338,6 +373,7 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
 | `platforms` | Prebuild | Per-platform registration maps (see [Adaptfully runtime](#adaptfully-runtime)) |
 | `platforms.<name>.builder` | Build/deploy | Override Wrapfully builder for a platform (default: `web` → `webapp`, others match platform key) |
 | `platforms.<name>.builders` | wrapfully-deploy | Map additional Wrapfully builder names to a platform |
+| `platforms.<name>.packager` | Prebuild | `web` (default), `electron`, `cordova`, or `capacitor` — controls template files added during prebuild |
 | `properties` | Cordova | Cordova config.xml entries (plugins, allow-navigation, etc.) |
 
 ### `wrapfully.json`

package/lib/node/index.js

@@ -3,7 +3,16 @@ export { loadProjectConfig, resolveServerUrl } from './config.js';
 export { send } from './deploy.js';
 export { adaptfullyFromCli, runAdaptfullyStage } from './pipeline.js';
 export { prebuildPlatform, prebuildOutputDir, resolveHtmlInjections } from './prebuild.js';
-export { getPackageRoot, getRuntimeDir, resolveRuntimeScript } from './paths.js';
+export { getPackageRoot, getRuntimeDir, getTemplatesDir, resolveRuntimeScript } from './paths.js';
+export {
+    VALID_PACKAGERS,
+    applyPackagerTemplates,
+    applyTemplateMarker,
+    resolvePlatformPackager,
+    resolvePackagerTemplateDir,
+    usesSteamAuth,
+    validatePlatformPackager,
+} from './packagers.js';
 export {
     STANDARD_PLUGINS,
     DEFAULT_BUILDER_PLATFORMS,

package/lib/node/packagers.js

@@ -0,0 +1,157 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getTemplatesDir } from './paths.js';
+
+/** @typedef {'web' | 'electron' | 'cordova' | 'capacitor'} PackagerName */
+
+/** @type {PackagerName[]} */
+export const VALID_PACKAGERS = ['web', 'electron', 'cordova', 'capacitor'];
+
+const STEAM_INIT = `const path = require('path');
+
+try {
+    require('steamworks.js').electronEnableSteamOverlay();
+} catch (err) {
+    console.error('Steam overlay unavailable:', err);
+}
+`;
+
+const STEAM_PRELOAD = `,
+                preload: path.join(__dirname, 'preload.js')`;
+
+/**
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ * @returns {PackagerName}
+ */
+export function resolvePlatformPackager(platformKey, pkg) {
+    const platform = pkg.config?.platforms?.[platformKey];
+    const packager = platform?.packager ?? 'web';
+    return /** @type {PackagerName} */ (packager);
+}
+
+/**
+ * @param {Record<string, string>} registrations
+ */
+export function usesSteamAuth(registrations) {
+    return Object.values(registrations).includes('steam-auth');
+}
+
+/**
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ */
+export function validatePlatformPackager(platformKey, pkg) {
+    const platform = pkg.config?.platforms?.[platformKey];
+    const packager = resolvePlatformPackager(platformKey, pkg);
+
+    if (!VALID_PACKAGERS.includes(packager)) {
+        throw new Error(
+            `Invalid packager "${packager}" for platform "${platformKey}". `
+            + `Expected one of: ${VALID_PACKAGERS.join(', ')}`,
+        );
+    }
+
+    const registrations = platform?.registrations ?? {};
+    if (usesSteamAuth(registrations) && packager !== 'electron') {
+        throw new Error(
+            `Platform "${platformKey}" uses steam-auth but packager is "${packager}". `
+            + 'Set config.platforms.' + platformKey + '.packager to "electron".',
+        );
+    }
+
+    if (usesSteamAuth(registrations) && !pkg.config?.steamId) {
+        throw new Error(
+            `Platform "${platformKey}" uses steam-auth but config.steamId is not set.`,
+        );
+    }
+}
+
+/**
+ * @param {string} content
+ * @param {string} markerName
+ * @param {string} replacement
+ */
+export function applyTemplateMarker(content, markerName, replacement) {
+    const pattern = new RegExp(
+        `/\\* adaptfully-${markerName} \\*/[\\s\\S]*?/\\* /adaptfully-${markerName} \\*/`,
+        'g',
+    );
+    return content.replace(pattern, replacement);
+}
+
+/**
+ * @param {PackagerName} packager
+ */
+export function resolvePackagerTemplateDir(packager) {
+    return path.join(getTemplatesDir(), packager);
+}
+
+/**
+ * @param {string} dest Prebuild output directory
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ * @param {{ log?: (message: string) => void }} [options]
+ */
+export function applyPackagerTemplates(dest, platformKey, pkg, options = {}) {
+    const log = options.log ?? (() => {});
+    const packager = resolvePlatformPackager(platformKey, pkg);
+
+    validatePlatformPackager(platformKey, pkg);
+
+    if (packager === 'web') {
+        return;
+    }
+
+    const templateDir = resolvePackagerTemplateDir(packager);
+    if (!fs.existsSync(templateDir)) {
+        throw new Error(
+            `Packager "${packager}" has no templates yet (missing ${templateDir}).`,
+        );
+    }
+
+    if (packager === 'electron') {
+        applyElectronTemplates(dest, platformKey, pkg, templateDir, log);
+    }
+}
+
+/**
+ * @param {string} dest
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ * @param {string} templateDir
+ * @param {(message: string) => void} log
+ */
+function applyElectronTemplates(dest, platformKey, pkg, templateDir, log) {
+    const registrations = pkg.config?.platforms?.[platformKey]?.registrations ?? {};
+    const withSteam = usesSteamAuth(registrations);
+    const mainTemplatePath = path.join(templateDir, 'main.js');
+
+    if (!fs.existsSync(mainTemplatePath)) {
+        throw new Error(`Electron packager template missing: ${mainTemplatePath}`);
+    }
+
+    let mainContent = fs.readFileSync(mainTemplatePath, 'utf8');
+
+    if (withSteam) {
+        mainContent = applyTemplateMarker(mainContent, 'steam-init', STEAM_INIT);
+        mainContent = applyTemplateMarker(mainContent, 'steam-preload', STEAM_PRELOAD);
+
+        const preloadTemplatePath = path.join(templateDir, 'preload.js');
+        if (!fs.existsSync(preloadTemplatePath)) {
+            throw new Error(`Electron steam-auth template missing: ${preloadTemplatePath}`);
+        }
+
+        const preloadContent = fs.readFileSync(preloadTemplatePath, 'utf8')
+            .replace(/\{\{STEAM_APP_ID\}\}/g, String(pkg.config.steamId));
+
+        fs.writeFileSync(path.join(dest, 'preload.js'), preloadContent);
+        log('adaptfully: write preload.js (steam-auth)');
+    } else {
+        mainContent = applyTemplateMarker(mainContent, 'steam-init', '');
+        mainContent = applyTemplateMarker(mainContent, 'steam-preload', '');
+    }
+
+    fs.writeFileSync(path.join(dest, 'main.js'), mainContent);
+    log('adaptfully: write main.js (electron)');
+}

package/lib/node/paths.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
 const RUNTIME_DIR = path.join(PACKAGE_ROOT, 'lib', 'runtime');
+const TEMPLATES_DIR = path.join(PACKAGE_ROOT, 'lib', 'templates');
 
 export function getPackageRoot() {
     return PACKAGE_ROOT;
@@ -13,6 +14,10 @@ export function getRuntimeDir() {
     return RUNTIME_DIR;
 }
 
+export function getTemplatesDir() {
+    return TEMPLATES_DIR;
+}
+
 export function resolveRuntimeScript(relativePath) {
     return path.join(RUNTIME_DIR, relativePath);
 }

package/lib/node/prebuild.js

@@ -4,6 +4,7 @@ import {
     adaptfullyInjectionForPlatform,
     injectAdaptfullyRegistrations,
 } from './registrations.js';
+import { applyPackagerTemplates } from './packagers.js';
 import { copyRecursiveSync, emptyDirSync } from './fs-utils.js';
 
 /** @typedef {'prebuild' | 'build' | 'deploy'} AdaptfullyStage */
@@ -73,6 +74,8 @@ export function prebuildPlatform(deployFolder, platformKey, pkg, options = {}) {
     emptyDirSync(dest);
     copyRecursiveSync(source, dest);
 
+    applyPackagerTemplates(dest, platformKey, pkg, { log });
+
     const injection = adaptfullyInjectionForPlatform(platformKey, pkg, { log });
     if (injection) {
         for (const relativePath of resolveHtmlInjections(pkg)) {

package/lib/runtime/auth/steam-auth.js

@@ -1,40 +1,226 @@
 /* global window */
 
 /**
- * Steam auth plugin — placeholder for Electron / NW.js Steam deployments.
- * Wire Steamworks login here; games only talk to adaptfully.get('auth').
+ * Steam auth via steamworks.js. Adaptfully prebuild writes Electron main.js and
+ * preload.js (when packager is "electron") to expose __ADAPTFULLY_STEAMWORKS__.
+ * Fallback bridges: window.steamworks, window.electronAPI, etc.
  */
 (function registerSteamAuth(ns) {
-    const { getStorage } = ns.auth.helpers;
+    const { configValue, getStorage } = ns.auth.helpers;
+
+    const DEFAULT_AUTO_LOGIN_KEY = 'lastLoggedIn';
+    const READY_POLL_MS = 50;
+    const READY_TIMEOUT_MS = 10000;
+
+    function normalizeSteamId(value) {
+        if (value == null || value === '') {
+            return '';
+        }
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        return String(value);
+    }
+
+    function readSyncIdentity(client) {
+        if (!client?.localplayer) {
+            return null;
+        }
+
+        try {
+            const steamId = client.localplayer.getSteamId?.();
+            const id = normalizeSteamId(steamId?.steamId64 ?? steamId);
+            if (!id) {
+                return null;
+            }
+
+            const name = client.localplayer.getName?.() || '';
+            return {
+                id,
+                email: '',
+                displayName: name,
+            };
+        } catch {
+            return null;
+        }
+    }
+
+    async function readAsyncIdentity(bridge) {
+        if (!bridge) {
+            return null;
+        }
+
+        try {
+            let steamIdRaw = bridge.getSteamId?.();
+            if (steamIdRaw && typeof steamIdRaw.then === 'function') {
+                steamIdRaw = await steamIdRaw;
+            }
+
+            const id = normalizeSteamId(steamIdRaw?.steamId64 ?? steamIdRaw);
+            if (!id) {
+                return null;
+            }
+
+            let name = '';
+            if (typeof bridge.getSteamName === 'function') {
+                name = await bridge.getSteamName();
+            } else if (typeof bridge.getName === 'function') {
+                const resolved = bridge.getName();
+                name = resolved && typeof resolved.then === 'function' ? await resolved : resolved;
+            }
+
+            return {
+                id,
+                email: '',
+                displayName: name || '',
+            };
+        } catch {
+            return null;
+        }
+    }
+
+    function resolveSteamworksClient() {
+        if (typeof window.__ADAPTFULLY_STEAMWORKS__ !== 'undefined') {
+            return window.__ADAPTFULLY_STEAMWORKS__;
+        }
+        if (window.steamworks?.localplayer) {
+            return window.steamworks;
+        }
+        if (window.steamworksClient?.localplayer) {
+            return window.steamworksClient;
+        }
+        return null;
+    }
+
+    function resolveAsyncBridge() {
+        if (window.electronAPI?.getSteamId) {
+            return window.electronAPI;
+        }
+        if (window.adaptfullySteam?.getSteamId) {
+            return window.adaptfullySteam;
+        }
+        return null;
+    }
 
     class SteamAuthPlugin {
         constructor() {
             this.name = 'steam';
             this.user = null;
             this.authenticated = false;
+            this.online = false;
+            this.#client = null;
+        }
+
+        /** @type {object | null} */
+        #client;
+
+        supportsAutoLogin() {
+            return true;
+        }
+
+        #autoLoginStorageKey() {
+            return configValue('autoLoginStorageKey', DEFAULT_AUTO_LOGIN_KEY);
+        }
+
+        #persistLogin(user) {
+            const storage = getStorage();
+            storage?.set(this.#autoLoginStorageKey(), user.id);
+        }
+
+        #applyIdentity(identity) {
+            if (!identity?.id) {
+                this.user = null;
+                this.authenticated = false;
+                this.online = false;
+                return false;
+            }
+
+            this.user = {
+                id: identity.id,
+                email: identity.email || '',
+                displayName: identity.displayName || '',
+            };
+            this.authenticated = true;
+            this.online = true;
+            this.#persistLogin(this.user);
+            return true;
+        }
+
+        async #resolveIdentity() {
+            const client = this.#client ?? resolveSteamworksClient();
+            if (client) {
+                this.#client = client;
+                return readSyncIdentity(client);
+            }
+
+            return readAsyncIdentity(resolveAsyncBridge());
+        }
+
+        #hasSteamBridge() {
+            return !!(resolveSteamworksClient() || resolveAsyncBridge());
         }
 
         whenReady(done) {
-            done();
+            if (!this.#hasSteamBridge()) {
+                this.online = false;
+                done({ error: 'Steamworks client not available' });
+                return;
+            }
+
+            const started = Date.now();
+            const timeoutMs = Number(configValue('steamReadyTimeoutMs', READY_TIMEOUT_MS)) || READY_TIMEOUT_MS;
+
+            const finish = async () => {
+                const identity = await this.#resolveIdentity();
+                if (identity) {
+                    this.#applyIdentity(identity);
+                    done();
+                    return;
+                }
+
+                if (Date.now() - started >= timeoutMs) {
+                    this.online = false;
+                    done({ error: 'Steamworks client not available' });
+                    return;
+                }
+
+                window.setTimeout(finish, READY_POLL_MS);
+            };
+
+            finish();
         }
 
-        login(callback) {
-            callback({ authenticated: this.authenticated, user: this.getUser() });
+        #complete(callback) {
+            callback({
+                authenticated: this.authenticated,
+                user: this.getUser(),
+            });
         }
 
-        autoLogin(callback) {
-            callback({ authenticated: this.authenticated, user: this.getUser() });
+        login(callback) {
+            this.#resolveIdentity()
+                .then((identity) => {
+                    this.#applyIdentity(identity);
+                    this.#complete(callback);
+                })
+                .catch(() => {
+                    this.user = null;
+                    this.authenticated = false;
+                    this.online = false;
+                    this.#complete(callback);
+                });
         }
 
-        supportsAutoLogin() {
-            return false;
+        autoLogin(callback) {
+            this.login(callback);
         }
 
         logout(callback) {
             const storage = getStorage();
             this.user = null;
             this.authenticated = false;
-            storage?.remove('lastLoggedIn');
+            this.online = false;
+            storage?.remove(this.#autoLoginStorageKey());
             callback();
         }
 
@@ -42,12 +228,20 @@
             if (!this.authenticated || !this.user) {
                 return null;
             }
-            return { id: this.user.id, email: this.user.email || '' };
+            return {
+                id: this.user.id,
+                email: this.user.email || '',
+            };
         }
 
         isAuthenticated() {
             return !!this.authenticated;
         }
+
+        /** @returns {object | null} Initialized steamworks.js client, when exposed synchronously */
+        getSteamworksClient() {
+            return this.#client ?? resolveSteamworksClient();
+        }
     }
 
     ns.auth.Steam = () => new SteamAuthPlugin();

package/lib/templates/electron/main.js

@@ -0,0 +1,104 @@
+/* eslint-disable no-sync */
+/* global process, require */
+const
+    {app, shell, BrowserWindow, Menu} = require('electron'),
+    fs = require('fs');
+
+/* adaptfully-steam-init */
+/* /adaptfully-steam-init */
+
+/**
+ * Creates window.
+ */
+function createWindow () {
+    // Create the browser window.
+    const
+        debugMode = false,
+        lastState = (function () {
+            let state = null;
+
+            try {
+                state = JSON.parse(fs.readFileSync(app.getPath('userData') + '/window-state.json', 'utf8'));
+            } catch (e) {}
+
+            return state || {
+                bounds: {
+                    width: 800,
+                    height: 600
+                },
+                maximized: false,
+                fullscreen: false
+            };
+        })(),
+        win = new BrowserWindow({
+            backgroundColor: '#E4378E',
+            width: lastState.bounds.width,
+            height: lastState.bounds.height,
+            minWidth: 200,
+            minHeight: 100,
+            webPreferences: {
+                devTools: debugMode,
+                nodeIntegration: false,
+                contextIsolation: true
+                /* adaptfully-steam-preload */
+                /* /adaptfully-steam-preload */
+            },
+            show: false
+        });
+
+    if (lastState.maximized) {
+        win.maximize();
+    }
+    if (lastState.fullscreen) {
+        win.setFullScreen(true);
+    }
+
+    if (!debugMode) {
+        Menu.setApplicationMenu(null);
+    }
+
+    win.once('ready-to-show', () => { // helps prevent flicker-loading
+        win.show();
+    });
+
+    // and load the index.html of the app.
+    win.loadFile('index.html');
+
+    win.webContents.on('will-navigate', (event, url) => {
+        event.preventDefault();
+        shell.openExternal(url);
+    });
+
+
+    //win.webContents.openDevTools();
+
+    win.on('close', () => {
+        fs.writeFileSync(app.getPath('userData') + '/window-state.json', JSON.stringify({
+            bounds: win.getNormalBounds(),
+            maximized: win.isMaximized(),
+            fullscreen: win.isFullScreen()
+        }));
+    });
+}
+
+// This method will be called when Electron has finished
+// initialization and is ready to create browser windows.
+// Some APIs can only be used after this event occurs.
+app.whenReady().then(createWindow);
+
+// Quit when all windows are closed.
+app.on('window-all-closed', () => {
+    // On macOS it is common for applications and their menu bar
+    // to stay active until the user quits explicitly with Cmd + Q
+    if (process.platform !== 'darwin') {
+        app.quit();
+    }
+});
+
+app.on('activate', () => {
+    // On macOS it's common to re-create a window in the app when the
+    // dock icon is clicked and there are no other windows open.
+    if (BrowserWindow.getAllWindows().length === 0) {
+        createWindow();
+    }
+});

package/lib/templates/electron/preload.js

@@ -0,0 +1,14 @@
+/* global require */
+const { contextBridge } = require('electron');
+
+let steamClient = null;
+
+try {
+    steamClient = require('steamworks.js').init({{STEAM_APP_ID}});
+} catch (err) {
+    console.error('Steamworks init failed:', err);
+}
+
+if (steamClient) {
+    contextBridge.exposeInMainWorld('__ADAPTFULLY_STEAMWORKS__', steamClient);
+}

package/package.json

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