@makefully/adaptfully 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to this project are documented in this file.
 
+## 3.3.0 — 2026-06-23
+
+### Added
+
+- **Packager classes** — `Packager`, `WebPackager`, `ElectronPackager`, `CordovaPackager`, and `CapacitorPackager` encapsulate per-packager prebuild behavior behind a shared API (`validate`, `applyTemplates`, `applyHtmlExtras`, `prebuild`).
+- **`createPackagerForPlatform(platformKey, pkg, options)`** — factory that resolves the configured packager and returns an instance. Options include `platforms` (target platform keys, e.g. `ios` + `android` for Cordova) and `platformKey` (active prebuild platform).
+- **Plugin detection** — `collectUsedPlugins()` and `usesPlugin(id)` inspect standard Adaptfully auth/storage registrations across targeted platforms so packagers can adapt output (e.g. Electron injects steamworks init when `steam-auth` is registered).
+- **Cordova prebuild** — writes `cordova.js` stub, injects CSP/viewport meta tags and `game-config.js` script tags into HTML.
+- **`buildElectronMain()` / `buildElectronPreload()`** — exported helpers that compose Electron shell files (used by `ElectronPackager` and available for tests or extensions).
+
+### Changed
+
+- Prebuild runs packager work through a single `packager.prebuild(dest, htmlPaths)` call instead of separate template/HTML helper functions.
+- Electron **`main.js`** and **`preload.js`** are composed from embedded strings in `ElectronPackager` rather than read from disk templates.
+- **`web`** packager writes **`game-config.js`** during prebuild when the platform key is **`uwp`**.
+
+### Removed
+
+- **`lib/templates/`** — packager output is generated in code; no template files are shipped with the package.
+- **`getTemplatesDir()`**, **`resolvePackagerTemplateDir()`**, and **`applyTemplateMarker()`** from the public API.
+
+## 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,11 +101,55 @@ 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 `capacitor`). Defaults to **`web`** — copy deploy and inject HTML only. Packagers are implemented as classes (`WebPackager`, `ElectronPackager`, `CordovaPackager`, `CapacitorPackager`) that handle prebuild output for their target platforms.
+
+| Packager | Prebuild adds |
+|----------|---------------|
+| `web` | `game-config.js` for **`uwp`** platform prebuilds |
+| `electron` | `main.js` (Electron shell); `preload.js` when **`steam-auth`** is registered |
+| `cordova` | `cordova.js` stub, `game-config.js`, CSP/viewport HTML extras |
+| `capacitor` | `game-config.js` (more Capacitor-specific output planned) |
+
+**`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
 import {
     prebuildPlatform,
+    createPackagerForPlatform,
     resolveHtmlInjections,
     runAdaptfullyStage,
     buildAdaptfullyInjection,
@@ -121,6 +165,7 @@ import {
 ```
 
 - **`prebuildPlatform(deployFolder, platformKey, pkg)`** — copy `deploy/` to `output/<platform>-prebuild/` and inject registrations into `config.htmlInjections` (default: `index.html`).
+- **`createPackagerForPlatform(platformKey, pkg, { platforms, log })`** — get a packager instance for custom prebuild or future build/deploy integration. The instance exposes `usesPlugin('steam-auth')`, `collectUsedPlugins()`, and `prebuild(dest, htmlPaths)`.
 - **`resolveRegistrationAssets(registrations)`** — resolve runtime script paths, inline registration JS, and external script tags for a registration map (useful for Vite dev servers).
 - **`runAdaptfullyStage('prebuild' | 'build' | 'deploy', platformKey, options)`** — run a pipeline stage programmatically.
 - **`platform.autoLogin(callback)`** — restore a prior session without UI when the auth plugin supports it (Google uses `lastLoggedIn` in storage and a cached OAuth token).
@@ -306,6 +351,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 +384,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` — selects the packager class that adds platform-specific files during prebuild |
 | `properties` | Cordova | Cordova config.xml entries (plugins, allow-navigation, etc.) |
 
 ### `wrapfully.json`

package/lib/node/index.js

@@ -4,6 +4,22 @@ 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 {
+    CapacitorPackager,
+    CordovaPackager,
+    ElectronPackager,
+    Packager,
+    VALID_PACKAGERS,
+    WebPackager,
+    applyPackagerHtmlExtras,
+    applyPackagerTemplates,
+    buildElectronMain,
+    buildElectronPreload,
+    createPackagerForPlatform,
+    resolvePlatformPackager,
+    usesSteamAuth,
+    validatePlatformPackager,
+} from './packagers.js';
 export {
     STANDARD_PLUGINS,
     DEFAULT_BUILDER_PLATFORMS,

package/lib/node/packagers/base.js

@@ -0,0 +1,303 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { STANDARD_PLUGINS } from '../registrations.js';
+
+/** @typedef {import('../registrations.js').RegistrationMap} RegistrationMap */
+/** @typedef {'web' | 'electron' | 'cordova' | 'capacitor'} PackagerName */
+
+/** @type {PackagerName[]} */
+export const VALID_PACKAGERS = ['web', 'electron', 'cordova', 'capacitor'];
+
+const PACKAGER_MARKER = '<!-- adaptfully-packager -->';
+const PACKAGER_END_MARKER = '<!-- /adaptfully-packager -->';
+
+/**
+ * @typedef {Object} PackagerOptions
+ * @property {string[]} [platforms] Platform keys this packager targets (e.g. ios + android for Cordova)
+ * @property {string} [platformKey] Active platform for a single prebuild run
+ * @property {(message: string) => void} [log]
+ */
+
+/**
+ * @param {string} value
+ */
+function isDeployPath(value) {
+    return value.startsWith('/') || value.startsWith('./') || value.includes('/');
+}
+
+/**
+ * @param {string} platformKey
+ */
+function gameConfigPlatform(platformKey) {
+    if (platformKey === 'uwp') {
+        return 'ms';
+    }
+    return platformKey;
+}
+
+/**
+ * @param {string} dest
+ * @param {string} platformKey
+ * @param {{ name: string, version: string, config?: { title?: string } }} pkg
+ * @param {(message: string) => void} log
+ */
+function writeGameConfig(dest, platformKey, pkg, log) {
+    const content = `window.gameConfig = ${JSON.stringify({
+        title: pkg.config?.title,
+        version: pkg.version,
+        id: pkg.name,
+        platform: gameConfigPlatform(platformKey),
+    }, null, 4)};`;
+
+    fs.writeFileSync(path.join(dest, 'game-config.js'), content);
+    log('adaptfully: write game-config.js');
+}
+
+/**
+ * @param {string} html
+ * @param {string} injection
+ */
+function injectPackagerExtras(html, injection) {
+    if (!injection) {
+        return html;
+    }
+
+    const markerPattern = new RegExp(
+        `${escapeRegExp(PACKAGER_MARKER)}[\\s\\S]*?${escapeRegExp(PACKAGER_END_MARKER)}\\n?`,
+    );
+
+    if (markerPattern.test(html)) {
+        return html.replace(markerPattern, injection);
+    }
+
+    if (html.includes(PACKAGER_MARKER)) {
+        return html.replace(PACKAGER_MARKER, `${injection}${PACKAGER_MARKER}`);
+    }
+
+    if (html.includes('<!-- adaptfully -->')) {
+        return html.replace('<!-- adaptfully -->', `${injection}<!-- adaptfully -->`);
+    }
+
+    if (html.includes('<!-- scripts -->')) {
+        return html.replace('<!-- scripts -->', `${injection}<!-- scripts -->`);
+    }
+
+    if (html.includes('</head>')) {
+        return html.replace('</head>', `${injection}</head>`);
+    }
+
+    throw new Error(
+        'Cannot inject packager extras: HTML needs '
+        + '<!-- adaptfully-packager -->…<!-- /adaptfully-packager -->, '
+        + '<!-- adaptfully -->, <!-- scripts -->, or </head>',
+    );
+}
+
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export class Packager {
+    /** @type {PackagerName} */
+    static id = 'web';
+
+    /** @type {string[]} */
+    static defaultPlatforms = [];
+
+    /**
+     * @param {object} pkg
+     * @param {PackagerOptions} [options]
+     */
+    constructor(pkg, options = {}) {
+        this.pkg = pkg;
+        this.log = options.log ?? (() => {});
+        this.platformKey = options.platformKey ?? null;
+
+        const configured = Packager.resolveConfiguredPlatforms(this.constructor.id, pkg);
+        if (options.platforms?.length) {
+            this.platforms = [...options.platforms];
+        } else if (configured.length) {
+            this.platforms = configured;
+        } else {
+            this.platforms = [...this.constructor.defaultPlatforms];
+        }
+
+        if (this.platformKey && !this.platforms.includes(this.platformKey)) {
+            this.platforms.push(this.platformKey);
+        }
+    }
+
+    /** @returns {PackagerName} */
+    get name() {
+        return /** @type {PackagerName} */ (this.constructor.id);
+    }
+
+    /**
+     * @param {PackagerName} packagerId
+     * @param {{ config?: { platforms?: Record<string, { packager?: string }> } }} pkg
+     * @returns {string[]}
+     */
+    static resolveConfiguredPlatforms(packagerId, pkg) {
+        const platforms = pkg.config?.platforms ?? {};
+        return Object.entries(platforms)
+            .filter(([, config]) => (config?.packager ?? 'web') === packagerId)
+            .map(([key]) => key);
+    }
+
+    /**
+     * @param {string} platformKey
+     * @param {{ config?: { platforms?: Record<string, { packager?: string }> } }} pkg
+     * @returns {PackagerName}
+     */
+    static resolvePlatformPackager(platformKey, pkg) {
+        const platform = pkg.config?.platforms?.[platformKey];
+        const packager = platform?.packager ?? 'web';
+        return /** @type {PackagerName} */ (packager);
+    }
+
+    /**
+     * Merged registrations from every platform in {@link this.platforms}.
+     * @returns {RegistrationMap}
+     */
+    collectRegistrations() {
+        /** @type {RegistrationMap} */
+        const merged = {};
+        for (const key of this.platforms) {
+            const registrations = this.pkg.config?.platforms?.[key]?.registrations ?? {};
+            Object.assign(merged, registrations);
+        }
+        return merged;
+    }
+
+    /**
+     * Registrations for the active prebuild platform, or merged when none is set.
+     * @returns {RegistrationMap}
+     */
+    getActiveRegistrations() {
+        if (this.platformKey) {
+            return this.pkg.config?.platforms?.[this.platformKey]?.registrations ?? {};
+        }
+        return this.collectRegistrations();
+    }
+
+    /**
+     * Standard Adaptfully plugin ids (auth, storage, etc.) used across targeted platforms.
+     * Custom deploy paths are excluded.
+     * @returns {Set<string>}
+     */
+    collectUsedPlugins() {
+        const plugins = new Set();
+        for (const key of this.platforms) {
+            const registrations = this.pkg.config?.platforms?.[key]?.registrations ?? {};
+            for (const value of Object.values(registrations)) {
+                if (typeof value === 'string' && !isDeployPath(value) && STANDARD_PLUGINS[value]) {
+                    plugins.add(value);
+                }
+            }
+        }
+        return plugins;
+    }
+
+    /**
+     * @param {string} pluginId Standard plugin id (e.g. steam-auth, dev-auth, localStorage)
+     * @param {{ scope?: 'active' | 'all' }} [options]
+     */
+    usesPlugin(pluginId, options = {}) {
+        const registrations = options.scope === 'all'
+            ? this.collectRegistrations()
+            : this.getActiveRegistrations();
+        return Object.values(registrations).includes(pluginId);
+    }
+
+    validate() {
+        if (!VALID_PACKAGERS.includes(this.name)) {
+            throw new Error(
+                `Invalid packager "${this.name}". Expected one of: ${VALID_PACKAGERS.join(', ')}`,
+            );
+        }
+
+        if (this.usesPlugin('steam-auth', { scope: 'all' }) && this.name !== 'electron') {
+            const platformLabel = this.platformKey ?? this.platforms[0] ?? 'unknown';
+            throw new Error(
+                `Platform "${platformLabel}" uses steam-auth but packager is "${this.name}". `
+                + `Set config.platforms.${platformLabel}.packager to "electron".`,
+            );
+        }
+    }
+
+    needsGameConfig() {
+        return false;
+    }
+
+    /**
+     * @param {string[]} headExtras
+     * @param {string[]} bodyScripts
+     * @returns {string}
+     */
+    formatHtmlInjection(headExtras, bodyScripts) {
+        if (headExtras.length === 0 && bodyScripts.length === 0) {
+            return '';
+        }
+
+        let block = `${PACKAGER_MARKER}\n`;
+        for (const extra of headExtras) {
+            block += `${extra}\n`;
+        }
+        for (const script of bodyScripts) {
+            block += `${script}\n`;
+        }
+        block += `${PACKAGER_END_MARKER}\n`;
+        return block;
+    }
+
+    /** @param {string} dest */
+    applyTemplates(dest) {
+        if (this.needsGameConfig() && this.platformKey) {
+            writeGameConfig(dest, this.platformKey, this.pkg, this.log);
+        }
+    }
+
+    /** @returns {string} */
+    buildHtmlInjection() {
+        const bodyScripts = [];
+        if (this.needsGameConfig()) {
+            bodyScripts.push('<script src="game-config.js"></script>');
+        }
+        return this.formatHtmlInjection([], bodyScripts);
+    }
+
+    /**
+     * @param {string} dest
+     * @param {string[]} htmlPaths
+     */
+    applyHtmlExtras(dest, htmlPaths) {
+        const injection = this.buildHtmlInjection();
+        if (!injection) {
+            return;
+        }
+
+        for (const relativePath of htmlPaths) {
+            const htmlPath = path.join(dest, relativePath);
+            if (!fs.existsSync(htmlPath)) {
+                throw new Error(`htmlInjections file not found in deploy output: ${relativePath}`);
+            }
+
+            const html = fs.readFileSync(htmlPath, 'utf8');
+            const updated = injectPackagerExtras(html, injection);
+            if (updated !== html) {
+                this.log(`adaptfully: inject packager extras into ${relativePath}`);
+                fs.writeFileSync(htmlPath, updated);
+            }
+        }
+    }
+
+    /**
+     * @param {string} dest
+     * @param {string[]} htmlPaths
+     */
+    prebuild(dest, htmlPaths) {
+        this.validate();
+        this.applyTemplates(dest);
+        this.applyHtmlExtras(dest, htmlPaths);
+    }
+}

package/lib/node/packagers/capacitor.js

@@ -0,0 +1,13 @@
+import { Packager } from './base.js';
+
+export class CapacitorPackager extends Packager {
+    /** @type {'capacitor'} */
+    static id = 'capacitor';
+
+    /** @type {string[]} */
+    static defaultPlatforms = ['ios', 'android'];
+
+    needsGameConfig() {
+        return true;
+    }
+}

package/lib/node/packagers/cordova.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Packager } from './base.js';
+
+const CORDOVA_CSP = '<meta http-equiv="Content-Security-Policy" content="default-src * \'self\' data: gap: \'unsafe-inline\' \'unsafe-eval\'; style-src * \'self\' \'unsafe-inline\' \'unsafe-eval\' gap:; script-src * \'self\' \'unsafe-inline\' \'unsafe-eval\' gap:; frame-src *;" />';
+
+const CORDOVA_VIEWPORT = '<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />';
+
+const CORDOVA_STUB = `/**
+ * Stub for non-Cordova environments. Cordova replaces this at runtime on device builds.
+ */
+window.cordova = null;
+`;
+
+export class CordovaPackager extends Packager {
+    /** @type {'cordova'} */
+    static id = 'cordova';
+
+    /** @type {string[]} */
+    static defaultPlatforms = ['ios', 'android'];
+
+    needsGameConfig() {
+        return true;
+    }
+
+    /** @param {string} dest */
+    applyTemplates(dest) {
+        fs.writeFileSync(path.join(dest, 'cordova.js'), CORDOVA_STUB);
+        this.log('adaptfully: write cordova.js');
+
+        super.applyTemplates(dest);
+    }
+
+    buildHtmlInjection() {
+        const headExtras = [CORDOVA_CSP, CORDOVA_VIEWPORT];
+        const bodyScripts = ['<script src="cordova.js"></script>'];
+
+        if (this.needsGameConfig()) {
+            bodyScripts.push('<script src="game-config.js"></script>');
+        }
+
+        return this.formatHtmlInjection(headExtras, bodyScripts);
+    }
+}

package/lib/node/packagers/electron.js

@@ -0,0 +1,214 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Packager } from './base.js';
+
+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')`;
+
+const ELECTRON_MAIN_HEAD = `/* eslint-disable no-sync */
+/* global process, require */
+const
+    {app, shell, BrowserWindow, Menu} = require('electron'),
+    fs = require('fs');
+
+`;
+
+const ELECTRON_MAIN_BODY = `
+/**
+ * Opens external URLs in the system browser and blocks in-app navigation.
+ * @param {Electron.BrowserWindow} win
+ */
+function attachExternalLinkHandlers(win) {
+    win.webContents.setWindowOpenHandler(({url}) => {
+        shell.openExternal(url);
+        return {action: 'deny'};
+    });
+
+    win.webContents.on('will-navigate', (event, url) => {
+        event.preventDefault();
+        shell.openExternal(url);
+    });
+}
+
+/**
+ * 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,
+                sandbox: true`;
+
+const ELECTRON_MAIN_TAIL = `
+            },
+            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');
+
+    attachExternalLinkHandlers(win);
+
+    //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();
+    }
+});
+`;
+
+const ELECTRON_PRELOAD_HEAD = `/* global require */
+const { contextBridge } = require('electron');
+
+let steamClient = null;
+
+try {
+    steamClient = require('steamworks.js').init(`;
+
+const ELECTRON_PRELOAD_TAIL = `);
+} catch (err) {
+    console.error('Steamworks init failed:', err);
+}
+
+if (steamClient) {
+    contextBridge.exposeInMainWorld('__ADAPTFULLY_STEAMWORKS__', steamClient);
+}
+`;
+
+/**
+ * @param {boolean} withSteam
+ */
+export function buildElectronMain(withSteam) {
+    const steamInit = withSteam ? STEAM_INIT : '';
+    const steamPreload = withSteam ? STEAM_PRELOAD : '';
+    return ELECTRON_MAIN_HEAD + steamInit + ELECTRON_MAIN_BODY + steamPreload + ELECTRON_MAIN_TAIL;
+}
+
+/**
+ * @param {number | string} steamAppId
+ */
+export function buildElectronPreload(steamAppId) {
+    return ELECTRON_PRELOAD_HEAD + steamAppId + ELECTRON_PRELOAD_TAIL;
+}
+
+export class ElectronPackager extends Packager {
+    /** @type {'electron'} */
+    static id = 'electron';
+
+    /** @type {string[]} */
+    static defaultPlatforms = ['steam'];
+
+    validate() {
+        super.validate();
+
+        if (this.usesPlugin('steam-auth') && !this.pkg.config?.steamId) {
+            const platformLabel = this.platformKey ?? this.platforms.join(', ');
+            throw new Error(
+                `Platform "${platformLabel}" uses steam-auth but config.steamId is not set.`,
+            );
+        }
+    }
+
+    needsGameConfig() {
+        return true;
+    }
+
+    /** @param {string} dest */
+    applyTemplates(dest) {
+        this.writeElectronMain(dest);
+        super.applyTemplates(dest);
+    }
+
+    /** @param {string} dest */
+    writeElectronMain(dest) {
+        const withSteam = this.usesPlugin('steam-auth');
+        const mainContent = buildElectronMain(withSteam);
+
+        if (withSteam) {
+            fs.writeFileSync(
+                path.join(dest, 'preload.js'),
+                buildElectronPreload(this.pkg.config.steamId),
+            );
+            this.log('adaptfully: write preload.js (steam-auth)');
+        }
+
+        fs.writeFileSync(path.join(dest, 'main.js'), mainContent);
+        this.log('adaptfully: write main.js (electron)');
+    }
+}

package/lib/node/packagers/index.js

@@ -0,0 +1,107 @@
+import { CapacitorPackager } from './capacitor.js';
+import { CordovaPackager } from './cordova.js';
+import { ElectronPackager, buildElectronMain, buildElectronPreload } from './electron.js';
+import { Packager, VALID_PACKAGERS } from './base.js';
+import { WebPackager } from './web.js';
+
+export { Packager, VALID_PACKAGERS } from './base.js';
+export { WebPackager } from './web.js';
+export { ElectronPackager, buildElectronMain, buildElectronPreload } from './electron.js';
+export { CordovaPackager } from './cordova.js';
+export { CapacitorPackager } from './capacitor.js';
+
+/** @typedef {import('./base.js').PackagerName} PackagerName */
+
+/** @type {Record<PackagerName, typeof Packager>} */
+const PACKAGER_REGISTRY = {
+    web: WebPackager,
+    electron: ElectronPackager,
+    cordova: CordovaPackager,
+    capacitor: CapacitorPackager,
+};
+
+/**
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ * @param {{ log?: (message: string) => void, platforms?: string[] }} [options]
+ * @returns {Packager}
+ */
+export function createPackagerForPlatform(platformKey, pkg, options = {}) {
+    const packagerId = Packager.resolvePlatformPackager(platformKey, pkg);
+
+    if (!VALID_PACKAGERS.includes(packagerId)) {
+        throw new Error(
+            `Invalid packager "${packagerId}" for platform "${platformKey}". `
+            + `Expected one of: ${VALID_PACKAGERS.join(', ')}`,
+        );
+    }
+
+    const PackagerClass = PACKAGER_REGISTRY[packagerId];
+    return new PackagerClass(pkg, {
+        ...options,
+        platformKey,
+    });
+}
+
+/**
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { packager?: string }> } }} pkg
+ * @returns {PackagerName}
+ */
+export function resolvePlatformPackager(platformKey, pkg) {
+    return Packager.resolvePlatformPackager(platformKey, pkg);
+}
+
+/**
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ */
+export function validatePlatformPackager(platformKey, pkg) {
+    createPackagerForPlatform(platformKey, pkg).validate();
+}
+
+/**
+ * @param {Record<string, string>} registrations
+ */
+export function usesSteamAuth(registrations) {
+    return Object.values(registrations).includes('steam-auth');
+}
+
+/**
+ * @param {string} dest
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { packager?: string, registrations?: Record<string, string> }>, steamId?: number } }} pkg
+ * @param {{ log?: (message: string) => void, platforms?: string[] }} [options]
+ */
+export function applyPackagerTemplates(dest, platformKey, pkg, options = {}) {
+    createPackagerForPlatform(platformKey, pkg, options).applyTemplates(dest);
+}
+
+/**
+ * @param {string} dest
+ * @param {string} platformKey
+ * @param {{ config?: { platforms?: Record<string, { packager?: string }> } }} pkg
+ * @param {string[]} htmlPaths
+ * @param {{ log?: (message: string) => void, platforms?: string[] }} [options]
+ */
+export function applyPackagerHtmlExtras(dest, platformKey, pkg, htmlPaths, options = {}) {
+    createPackagerForPlatform(platformKey, pkg, options).applyHtmlExtras(dest, htmlPaths);
+}
+
+/**
+ * @param {PackagerName} packager
+ * @param {string} platformKey
+ */
+export function needsGameConfig(packager, platformKey) {
+    const instance = new PACKAGER_REGISTRY[packager]({}, { platformKey });
+    return instance.needsGameConfig();
+}
+
+/**
+ * @param {PackagerName} packager
+ * @param {string} platformKey
+ */
+export function buildPackagerHtmlInjection(packager, platformKey) {
+    const instance = new PACKAGER_REGISTRY[packager]({}, { platformKey });
+    return instance.buildHtmlInjection();
+}

package/lib/node/packagers/web.js

@@ -0,0 +1,13 @@
+import { Packager } from './base.js';
+
+export class WebPackager extends Packager {
+    /** @type {'web'} */
+    static id = 'web';
+
+    /** @type {string[]} */
+    static defaultPlatforms = ['web', 'uwp', 'pwa'];
+
+    needsGameConfig() {
+        return this.platformKey === 'uwp';
+    }
+}

package/lib/node/packagers.js

@@ -0,0 +1 @@
+export * from './packagers/index.js';

package/lib/node/prebuild.js

@@ -4,6 +4,7 @@ import {
     adaptfullyInjectionForPlatform,
     injectAdaptfullyRegistrations,
 } from './registrations.js';
+import { createPackagerForPlatform } from './packagers.js';
 import { copyRecursiveSync, emptyDirSync } from './fs-utils.js';
 
 /** @typedef {'prebuild' | 'build' | 'deploy'} AdaptfullyStage */
@@ -73,9 +74,13 @@ export function prebuildPlatform(deployFolder, platformKey, pkg, options = {}) {
     emptyDirSync(dest);
     copyRecursiveSync(source, dest);
 
+    const packager = createPackagerForPlatform(platformKey, pkg, { log });
+    const htmlInjections = resolveHtmlInjections(pkg);
+    packager.prebuild(dest, htmlInjections);
+
     const injection = adaptfullyInjectionForPlatform(platformKey, pkg, { log });
     if (injection) {
-        for (const relativePath of resolveHtmlInjections(pkg)) {
+        for (const relativePath of htmlInjections) {
             const htmlPath = path.join(dest, relativePath);
             if (!fs.existsSync(htmlPath)) {
                 throw new Error(`htmlInjections file not found in deploy output: ${relativePath}`);

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/package.json

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