@makefully/adaptfully 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project are documented in this file.
 
+## 3.4.0 — 2026-06-25
+
+### Changed
+
+- Electron **`main.js`** allows same-app `file://` navigation while still opening external http(s) links in the system browser.
+- Steam builds (`steam-auth`) set renderer **`sandbox: false`** so the steamworks preload bridge can reach the main process; non-Steam Electron builds keep `sandbox: true`.
+
+## 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

package/README.md

@@ -101,7 +101,16 @@ 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`.
+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
 {
@@ -140,6 +149,7 @@ The renderer `steam-auth` plugin reads the Steam ID from that bridge. When Steam
 ```javascript
 import {
     prebuildPlatform,
+    createPackagerForPlatform,
     resolveHtmlInjections,
     runAdaptfullyStage,
     buildAdaptfullyInjection,
@@ -155,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).
@@ -373,7 +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` — controls template files added during prebuild |
+| `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

@@ -3,13 +3,20 @@ 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, getTemplatesDir, resolveRuntimeScript } from './paths.js';
+export { getPackageRoot, getRuntimeDir, resolveRuntimeScript } from './paths.js';
 export {
+    CapacitorPackager,
+    CordovaPackager,
+    ElectronPackager,
+    Packager,
     VALID_PACKAGERS,
+    WebPackager,
+    applyPackagerHtmlExtras,
     applyPackagerTemplates,
-    applyTemplateMarker,
+    buildElectronMain,
+    buildElectronPreload,
+    createPackagerForPlatform,
     resolvePlatformPackager,
-    resolvePackagerTemplateDir,
     usesSteamAuth,
     validatePlatformPackager,
 } from './packagers.js';

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,222 @@
+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 http(s) links in the system browser; allows same-app file:// navigation.
+ * @param {Electron.BrowserWindow} win
+ */
+function attachExternalLinkHandlers(win) {
+    win.webContents.setWindowOpenHandler(({url}) => {
+        if (url.startsWith('file:')) {
+            return {action: 'deny'};
+        }
+        shell.openExternal(url);
+        return {action: 'deny'};
+    });
+
+    win.webContents.on('will-navigate', (event, url) => {
+        if (url.startsWith('file:')) {
+            return;
+        }
+        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: __SANDBOX__`;
+
+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 : '';
+    const sandbox = withSteam ? 'false' : 'true';
+    const mainBody = ELECTRON_MAIN_BODY.replace('__SANDBOX__', sandbox);
+    return ELECTRON_MAIN_HEAD + steamInit + mainBody + 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

@@ -1,157 +1 @@
-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)');
-}
+export * from './packagers/index.js';

package/lib/node/paths.js

@@ -4,7 +4,6 @@ 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;
@@ -14,10 +13,6 @@ 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,7 +4,7 @@ import {
     adaptfullyInjectionForPlatform,
     injectAdaptfullyRegistrations,
 } from './registrations.js';
-import { applyPackagerTemplates } from './packagers.js';
+import { createPackagerForPlatform } from './packagers.js';
 import { copyRecursiveSync, emptyDirSync } from './fs-utils.js';
 
 /** @typedef {'prebuild' | 'build' | 'deploy'} AdaptfullyStage */
@@ -74,11 +74,13 @@ export function prebuildPlatform(deployFolder, platformKey, pkg, options = {}) {
     emptyDirSync(dest);
     copyRecursiveSync(source, dest);
 
-    applyPackagerTemplates(dest, platformKey, pkg, { log });
+    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/package.json

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

package/lib/templates/electron/main.js

@@ -1,104 +0,0 @@
-/* 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

@@ -1,14 +0,0 @@
-/* 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);
-}