@makefully/adaptfully 5.1.2 → 5.3.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.3.0 — 2026-11-11
+
+### Added
+
+- **Store-assets upload ledger** — `lib/node/store-assets-ledger.js` owns `meta/store-assets/upload-ledger.json` (sequenced SHA-256 set skip for Play/ASC listing sync).
+- **Opt-in listing deploys** — `adaptfully deploy <platform> --deployment *-listing` may target keys not in the platform release fan-out; assets-only zips skip the prior AAB/IPA tree and package `credentialsFrom` sibling folders under `meta/deployments/`.
+
+## 5.2.0 — 2026-11-11
+
+### Added
+
+- **`device-auth`** — PIN/QR limited-input auth plugin; TV starts/polls, companion completes on the web deploy. See [`docs/device-auth.md`](docs/device-auth.md).
+- **`tv-host`** — lean-back host with Back key + `onDeviceAuth` for PIN/QR chrome.
+- **Web packager** — default platforms include `webos` / `lgtv`; builder family resolves `webos` even with `packager: "web"`.
+
 ## 5.1.2 — 2026-11-10
 
 ### Fixed

package/docs/device-auth.md

@@ -0,0 +1,67 @@
+# Device auth (PIN / QR)
+
+`device-auth` is an Adaptfully auth plugin for limited-input shells (LG webOS TV, etc.). The TV build only **starts** and **polls** a short-lived session. Companion Google (or other) sign-in happens on the game’s **existing web deploy**, not inside the TV package.
+
+## Registration
+
+```json
+"lgtv": {
+  "packager": "web",
+  "builder": "webos",
+  "registrations": {
+    "auth": "device-auth",
+    "host": "tv-host",
+    "config": "javascript/adaptfully-bridge.js"
+  }
+}
+```
+
+## Config keys
+
+| Key | Purpose |
+|-----|---------|
+| `deviceAuthStartUrl` | `POST` mint session |
+| `deviceAuthPollUrl` | `GET` poll (`?device_code=`) |
+| `deviceAuthCompanionBase` | Fallback QR/base URL if start omits `verificationUrl` |
+
+## HTTP protocol
+
+### `POST start`
+
+Response:
+
+```json
+{
+  "deviceCode": "opaque-poll-token",
+  "userCode": "AB12CD",
+  "expiresIn": 600,
+  "interval": 2000,
+  "verificationUrl": "https://game.example/tv-login.html?code=AB12CD"
+}
+```
+
+### `GET poll?device_code=…`
+
+```json
+{ "status": "pending" }
+```
+
+```json
+{ "status": "approved", "user": { "id": "provider-subject", "email": "a@b.co" } }
+```
+
+Also: `expired`, `denied`.
+
+### `POST complete`
+
+Body: `user_code` or `device_code`, plus `plusId`, `email`, optional `user_id`.
+
+## Companion helpers
+
+Optional page script: `lib/runtime/auth/device-auth-companion.js`  
+(`adaptfully.auth.deviceCompanion.readCodeFromLocation()` / `.complete(...)`).
+
+## Events
+
+`window` CustomEvent `adaptfully:device-auth` with `detail.phase` of `pending` | `approved` | `expired` | `denied` | `error`.  
+`tv-host` forwards these via `onDeviceAuth(cb)`.

package/lib/node/archive.js

@@ -163,20 +163,37 @@ export function createArchive(deployFolder, contents, options = {}) {
 }
 
 /**
- * Prior artifact zip plus one deployment folder for /deploy.
+ * Prior artifact zip plus deployment folder(s) for /deploy.
+ * Always packages non-deployment meta (including store-assets) from META_DIR.
  *
  * @param {string} artifactPath
- * @param {string} publishDir
+ * @param {string} publishDir Primary deployment folder (…/meta/deployments/<key>)
  * @param {string} [contents]
- * @param {{ log?: (message: string) => void }} [options]
+ * @param {{ log?: (message: string) => void, deploymentDirs?: string[], includeArtifact?: boolean }} [options]
  */
 export function createDeployArchive(artifactPath, publishDir, contents, options = {}) {
     const
         zip = archiver('zip', { zlib: { level: 0 } }),
-        log = options.log ?? console.log;
+        log = options.log ?? console.log,
+        includeArtifact = options.includeArtifact !== false,
+        extraDirs = Array.isArray(options.deploymentDirs) ? options.deploymentDirs : [];
+
+    if (includeArtifact && artifactPath && fs.existsSync(artifactPath)) {
+        zip.directory(toPosixDir(artifactPath), false);
+    }
 
-    zip.directory(toPosixDir(artifactPath), false);
-    appendMeta(zip, publishDir, [], { log });
+    // Prefer meta/deployments/<key> packaging (not legacy meta/publish) so
+    // credentialsFrom sibling keys resolve under the same layout Wrapfully reads.
+    const dirs = [];
+    if (publishDir) {
+        dirs.push(publishDir);
+    }
+    for (const dir of extraDirs) {
+        if (dir && !dirs.includes(dir)) {
+            dirs.push(dir);
+        }
+    }
+    appendMeta(zip, null, dirs, { log });
 
     if (contents) {
         zip.append(contents, { name: 'package.json' });

package/lib/node/deploy.js

@@ -227,6 +227,7 @@ export async function submitWrapfullyChore ({
  *   platformKey?: string,
  *   deploymentKey?: string,
  *   artifactPath?: string,
+ *   includeArtifact?: boolean,
  *   accessToken?: string,
  *   encrypt?: boolean,
  *   encryptPublicKey?: string,
@@ -273,7 +274,11 @@ export async function send (
         if (!options.deploymentKey) {
             throw new Error('deploy stage requires options.deploymentKey');
         }
-        archiveStream = createDeployArchive(options.artifactPath, options.publishDir, contents, {log});
+        archiveStream = createDeployArchive(options.artifactPath, options.publishDir, contents, {
+            log,
+            deploymentDirs: options.deploymentDirs,
+            includeArtifact: options.includeArtifact !== false,
+        });
     } else if (stage === 'release') {
         archiveStream = createReleaseArchive(deployFolder, contents, options.deploymentDirs ?? [], {log});
     } else {

package/lib/node/index.js

@@ -115,3 +115,20 @@ export {
     runAppleSigning,
     runOpenssl,
 } from './apple-signing.js';
+export {
+    LEDGER_FILENAME,
+    LEDGER_VERSION,
+    emptyLedger,
+    ledgerFileExists,
+    ledgerMatchesSet,
+    ledgerPath,
+    listOrderedImageFiles,
+    makeSetKey,
+    readLedger,
+    recordSetSuccess,
+    sequencesEqual,
+    sha256Buffer,
+    sha256File,
+    sha256Sequence,
+    writeLedger,
+} from './store-assets-ledger.js';

package/lib/node/packagers/web.js

@@ -5,11 +5,11 @@ export class WebPackager extends Packager {
     static id = 'web';
 
     /** @type {string[]} */
-    static defaultPlatforms = ['web', 'uwp', 'pwa'];
+    static defaultPlatforms = ['web', 'uwp', 'pwa', 'webos', 'lgtv'];
 
     needsGameConfig() {
-        // Stamp version/platform for all web-family routes (web, uwp, pwa) so
-        // analytics resolveAppVersion() matches electron/capacitor builds.
+        // Stamp version/platform for all web-family routes (web, uwp, pwa, webos)
+        // so analytics resolveAppVersion() matches electron/capacitor builds.
         return true;
     }
 }

package/lib/node/pipeline.js

@@ -1,3 +1,5 @@
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { loadProjectConfig, resolveServerUrl, resolveAccessToken, resolveEncryptFlag } from './config.js';
 import { send } from './deploy.js';
@@ -21,6 +23,28 @@ import { androidKeystoreFromCli } from './android-keystore.js';
 import { appleSigningFromCli } from './apple-signing.js';
 import { buildGameId } from './fs-name.js';
 
+/**
+ * @param {string} deploymentDir
+ * @returns {object | null}
+ */
+function readDeploymentManifest(deploymentDir) {
+    try {
+        const raw = fs.readFileSync(path.join(deploymentDir, 'manifest.json'), 'utf8');
+        return JSON.parse(raw);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Listing sync deployers do not need the prior AAB/IPA artifact tree.
+ * @param {string | null | undefined} type
+ * @returns {boolean}
+ */
+function isListingDeployerType(type) {
+    return type === 'google-listing' || type === 'apple-listing';
+}
+
 /** @typedef {'prebuild' | 'build' | 'deploy' | 'release'} AdaptfullyStage */
 
 const VALID_STAGES = new Set(['prebuild', 'build', 'deploy', 'release']);
@@ -66,11 +90,17 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
         ?? resolveExtractRoot(outputRoot, platformKey);
 
     if (options.deployment) {
+        const publishDir = resolvePublishDir(options.deployment);
+        const exists = fs.existsSync(publishDir);
         if (!deployments.includes(options.deployment)) {
-            throw new Error(
-                `Deployment "${options.deployment}" is not configured for platform "${platformKey}". `
-                + `Available deployments: ${deployments.join(', ')}`,
-            );
+            // Deploy stage may target opt-in keys (e.g. android-listing) that are
+            // intentionally omitted from the platform's release fan-out list.
+            if (stage !== 'deploy' || !exists) {
+                throw new Error(
+                    `Deployment "${options.deployment}" is not configured for platform "${platformKey}". `
+                    + `Available deployments: ${deployments.join(', ')}`,
+                );
+            }
         }
         deployments = [options.deployment];
     } else if (stage === 'build') {
@@ -83,10 +113,19 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
 
     let artifactPath = options.artifactPath;
     if (stage === 'deploy' && !artifactPath) {
-        artifactPath = resolveBuildArtifactDir(pkg, {
-            outputRoot: options.outputRoot,
-            platformKey,
-        });
+        const primaryKey = deployments[0];
+        const primaryManifest = primaryKey
+            ? readDeploymentManifest(resolvePublishDir(primaryKey))
+            : null;
+        if (isListingDeployerType(primaryManifest?.type)) {
+            // Assets-only: meta/store-assets + deployment folders; skip heavy binary tree.
+            artifactPath = fs.mkdtempSync(path.join(os.tmpdir(), 'adaptfully-listing-'));
+        } else {
+            artifactPath = resolveBuildArtifactDir(pkg, {
+                outputRoot: options.outputRoot,
+                platformKey,
+            });
+        }
     }
 
     const prebuiltDir = stage === 'deploy'
@@ -153,9 +192,25 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
     for (const deploymentKey of deployments) {
         const publishDir = deploymentKey === 'zip' ? undefined : resolvePublishDir(deploymentKey);
         const wrapStage = stage === 'deploy' ? 'deploy' : 'build';
-        const deploymentDirs = wrapStage === 'build'
+        /** @type {string[]} */
+        let deploymentDirs = wrapStage === 'build'
             ? resolveBuildCredentialDirs(platformKey, pkg)
             : [];
+        let includeArtifact = true;
+
+        if (wrapStage === 'deploy' && publishDir) {
+            const manifest = readDeploymentManifest(publishDir);
+            if (isListingDeployerType(manifest?.type)) {
+                includeArtifact = Boolean(options.artifactPath);
+                deploymentDirs = [];
+                if (manifest?.credentialsFrom) {
+                    const sibling = resolvePublishDir(String(manifest.credentialsFrom));
+                    if (fs.existsSync(sibling)) {
+                        deploymentDirs.push(sibling);
+                    }
+                }
+            }
+        }
 
         log(
             `adaptfully: ${stage} ${platformKey} → `
@@ -165,9 +220,13 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
 
         if (deploymentDirs.length) {
             log(
-                `adaptfully: build signing credentials → ${
-                    deploymentDirs.map((dir) => path.resolve(dir)).join(', ')
-                }`,
+                wrapStage === 'deploy'
+                    ? `adaptfully: listing credentialsFrom → ${
+                        deploymentDirs.map((dir) => path.resolve(dir)).join(', ')
+                    }`
+                    : `adaptfully: build signing credentials → ${
+                        deploymentDirs.map((dir) => path.resolve(dir)).join(', ')
+                    }`,
             );
         }
         log(`adaptfully: extract → ${extractRoot}`);
@@ -187,6 +246,7 @@ export async function runAdaptfullyStage(stage, platformKey, options) {
                 deploymentDirs,
                 deploymentKey: wrapStage === 'deploy' ? deploymentKey : undefined,
                 artifactPath,
+                includeArtifact,
             },
         );
 

package/lib/node/registrations.js

@@ -30,6 +30,10 @@ export const STANDARD_PLUGINS = {
         scripts: ['core.js', 'platform.js', 'auth/_helpers.js', 'auth/dev-auth.js'],
         registration: (key) => `adaptfully.register('${key}', adaptfully.auth.Dev);`,
     },
+    'device-auth': {
+        scripts: ['core.js', 'platform.js', 'auth/_helpers.js', 'auth/device-auth.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.auth.Device);`,
+    },
     localStorage: {
         scripts: ['core.js', 'storage/_helpers.js', 'storage/local-storage.js'],
         registration: (key) => `adaptfully.register('${key}', adaptfully.storage.LocalStorage());`,
@@ -58,6 +62,10 @@ export const STANDARD_PLUGINS = {
         scripts: ['core.js', 'host/_helpers.js', 'host/noop-host.js'],
         registration: (key) => `adaptfully.register('${key}', adaptfully.host.Noop());`,
     },
+    'tv-host': {
+        scripts: ['core.js', 'host/_helpers.js', 'host/tv-host.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.host.Tv());`,
+    },
 };
 
 /** Default Wrapfully builder → config.platforms key */
@@ -77,6 +85,8 @@ export const DEFAULT_BUILDER_PLATFORMS = {
     'ios-sim': 'ios',
     webapp: 'web',
     uwp: 'uwp',
+    webos: 'lgtv',
+    'webos-dev': 'lgtv',
 };
 
 const ADAPTFULLY_MARKER = '<!-- adaptfully -->';
@@ -402,6 +412,9 @@ export function resolveFamilyFromTarget(target) {
     if (target === 'pwa') {
         return 'pwa';
     }
+    if (target === 'webos' || target === 'webos-dev') {
+        return 'webos';
+    }
     if (target === 'webapp' || target === 'web') {
         return 'webapp';
     }
@@ -419,6 +432,9 @@ export function resolveFamily(targets, packager) {
     if (targets.length === 1 && targets[0] === 'pwa') {
         return 'pwa';
     }
+    if (targets.length === 1 && (targets[0] === 'webos' || targets[0] === 'webos-dev')) {
+        return 'webos';
+    }
 
     if (packager === 'electron') {
         return 'electron';

package/lib/node/store-assets-ledger.js

@@ -0,0 +1,194 @@
+/**
+ * Upload ledger for store listing image sets (Play, ASC, future platforms).
+ * Lives at assets/meta/store-assets/upload-ledger.json (zip: meta/store-assets/…).
+ *
+ * Set key: `{platform}/{locale}/{slot}` e.g. google/en-US/phoneScreenshots
+ */
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const LEDGER_FILENAME = 'upload-ledger.json';
+export const LEDGER_VERSION = 1;
+
+/**
+ * @param {string} storeAssetsRoot Absolute path to store-assets (…/meta/store-assets)
+ * @returns {string}
+ */
+export function ledgerPath(storeAssetsRoot) {
+    return path.join(storeAssetsRoot, LEDGER_FILENAME);
+}
+
+/**
+ * @param {string} platform
+ * @param {string} locale
+ * @param {string} slot
+ * @returns {string}
+ */
+export function makeSetKey(platform, locale, slot) {
+    return `${platform}/${locale}/${slot}`;
+}
+
+/**
+ * @param {string | Buffer | Uint8Array} data
+ * @returns {string}
+ */
+export function sha256Buffer(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+export async function sha256File(filePath) {
+    const hash = crypto.createHash('sha256');
+    const handle = await fsp.open(filePath, 'r');
+    try {
+        const stream = handle.createReadStream();
+        for await (const chunk of stream) {
+            hash.update(chunk);
+        }
+    } finally {
+        await handle.close();
+    }
+    return hash.digest('hex');
+}
+
+/**
+ * Ordered SHA-256 for each path (display / upload order).
+ * @param {string[]} filePaths Absolute paths
+ * @returns {Promise<string[]>}
+ */
+export async function sha256Sequence(filePaths) {
+    const out = [];
+    for (const filePath of filePaths) {
+        out.push(await sha256File(filePath));
+    }
+    return out;
+}
+
+/**
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {boolean}
+ */
+export function sequencesEqual(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * @returns {{ version: number, sets: Record<string, object> }}
+ */
+export function emptyLedger() {
+    return { version: LEDGER_VERSION, sets: {} };
+}
+
+/**
+ * @param {string} storeAssetsRoot
+ * @returns {Promise<{ version: number, sets: Record<string, object> }>}
+ */
+export async function readLedger(storeAssetsRoot) {
+    const file = ledgerPath(storeAssetsRoot);
+    try {
+        const raw = await fsp.readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object') {
+            return emptyLedger();
+        }
+        const sets = parsed.sets && typeof parsed.sets === 'object' ? parsed.sets : {};
+        return { version: Number(parsed.version) || LEDGER_VERSION, sets };
+    } catch (err) {
+        if (err && (err.code === 'ENOENT' || err instanceof SyntaxError)) {
+            return emptyLedger();
+        }
+        throw err;
+    }
+}
+
+/**
+ * @param {string} storeAssetsRoot
+ * @param {{ version?: number, sets: Record<string, object> }} ledger
+ * @returns {Promise<void>}
+ */
+export async function writeLedger(storeAssetsRoot, ledger) {
+    await fsp.mkdir(storeAssetsRoot, { recursive: true });
+    const payload = {
+        version: ledger.version || LEDGER_VERSION,
+        sets: ledger.sets || {},
+    };
+    await fsp.writeFile(ledgerPath(storeAssetsRoot), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * @param {{ version: number, sets: Record<string, object> }} ledger
+ * @param {string} setKey
+ * @param {string[]} sequence
+ * @param {boolean} [force]
+ * @returns {boolean} true when local sequence matches last successful upload
+ */
+export function ledgerMatchesSet(ledger, setKey, sequence, force = false) {
+    if (force) {
+        return false;
+    }
+    const entry = ledger?.sets?.[setKey];
+    if (!entry || !Array.isArray(entry.sha256Sequence)) {
+        return false;
+    }
+    return sequencesEqual(entry.sha256Sequence, sequence);
+}
+
+/**
+ * Record a successful upload for one set. Does not touch other sets.
+ * @param {{ version: number, sets: Record<string, object> }} ledger
+ * @param {string} setKey
+ * @param {{ sha256Sequence: string[], assetIds?: string[], uploadedAt?: string }} update
+ */
+export function recordSetSuccess(ledger, setKey, update) {
+    if (!ledger.sets) {
+        ledger.sets = {};
+    }
+    ledger.sets[setKey] = {
+        sha256Sequence: [...update.sha256Sequence],
+        uploadedAt: update.uploadedAt || new Date().toISOString(),
+        ...(Array.isArray(update.assetIds) ? { assetIds: [...update.assetIds] } : {}),
+    };
+}
+
+/**
+ * Sync-friendly: list image files in a directory in alphanumeric order.
+ * @param {string} dir
+ * @returns {Promise<string[]>} Absolute paths
+ */
+export async function listOrderedImageFiles(dir) {
+    let names;
+    try {
+        names = await fsp.readdir(dir);
+    } catch (err) {
+        if (err && err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+    const images = names
+        .filter((name) => /\.(png|jpe?g|webp)$/i.test(name))
+        .sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+    return images.map((name) => path.join(dir, name));
+}
+
+/**
+ * @param {string} storeAssetsRoot
+ * @returns {boolean}
+ */
+export function ledgerFileExists(storeAssetsRoot) {
+    return fs.existsSync(ledgerPath(storeAssetsRoot));
+}

package/lib/runtime/auth/device-auth-companion.js

@@ -0,0 +1,69 @@
+/* global fetch, window */
+
+/**
+ * Optional helpers for a web companion page that completes device-auth sessions.
+ * Not registered as an Adaptfully plugin — include on the companion page only.
+ *
+ * Usage:
+ *   const code = adaptfully.auth.deviceCompanion.readCodeFromLocation();
+ *   await adaptfully.auth.deviceCompanion.complete({
+ *     completeUrl, deviceCode or userCode, plusId, email, userId?
+ *   });
+ */
+(function registerDeviceAuthCompanion(ns) {
+    ns.auth = ns.auth || {};
+
+    /**
+     * @returns {string}
+     */
+    function readCodeFromLocation() {
+        try {
+            const params = new URLSearchParams(window.location.search || '');
+            return String(params.get('code') || params.get('user_code') || params.get('pin') || '').trim();
+        } catch {
+            return '';
+        }
+    }
+
+    /**
+     * @param {{
+     *   completeUrl: string,
+     *   deviceCode?: string,
+     *   userCode?: string,
+     *   plusId: string,
+     *   email: string,
+     *   userId?: string,
+     * }} options
+     */
+    async function complete(options) {
+        const completeUrl = String(options?.completeUrl || '').trim();
+        if (!completeUrl) {
+            throw new Error('deviceCompanion.complete requires completeUrl');
+        }
+        const body = {
+            device_code: options.deviceCode || undefined,
+            user_code: options.userCode || undefined,
+            plusId: options.plusId,
+            email: options.email,
+            user_id: options.userId || undefined,
+        };
+        const response = await fetch(completeUrl, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`device-login complete failed (${response.status}): ${text}`);
+        }
+        return response.json().catch(() => ({ ok: true }));
+    }
+
+    ns.auth.deviceCompanion = {
+        readCodeFromLocation,
+        complete,
+    };
+}(window.adaptfully || (window.adaptfully = {})));

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

@@ -0,0 +1,335 @@
+/* global fetch, window */
+
+/**
+ * Device / PIN / QR auth for limited-input shells (LG webOS TV, etc.).
+ *
+ * TV build starts a short-lived session and polls. Companion sign-in happens on
+ * the game's existing web deploy (not in the TV package).
+ *
+ * Config (adaptfully config / game-config):
+ *   deviceAuthStartUrl      POST → { deviceCode, userCode, expiresIn, interval?, verificationUrl }
+ *   deviceAuthPollUrl       GET  → { status, user? }  (append ?device_code=)
+ *   deviceAuthCompanionBase optional base for QR if start omits verificationUrl
+ *
+ * Events: window 'adaptfully:device-auth' CustomEvent with detail
+ *   { phase: 'pending'|'approved'|'expired'|'denied'|'error', userCode?, verificationUrl?, qrUrl?, expiresIn?, error? }
+ *
+ *   adaptfully.register('auth', adaptfully.auth.Device);
+ */
+(function registerDeviceAuth(ns) {
+    const { configValue, getStorage } = ns.auth.helpers;
+
+    const DEFAULT_AUTO_LOGIN_KEY = 'lastLoggedIn';
+    const DEFAULT_USER_KEY = 'adaptfully_device_auth_user';
+    const DEFAULT_INTERVAL_MS = 2000;
+
+    class DeviceAuthPlugin {
+        constructor() {
+            this.name = 'device';
+            this.user = null;
+            this.authenticated = false;
+            this._pending = null;
+            this._pollTimer = null;
+            this._loginInFlight = false;
+        }
+
+        supportsAutoLogin() {
+            return true;
+        }
+
+        supportsLogout() {
+            return true;
+        }
+
+        requiresEmail() {
+            return true;
+        }
+
+        #autoLoginStorageKey() {
+            return configValue('autoLoginStorageKey', DEFAULT_AUTO_LOGIN_KEY);
+        }
+
+        #userStorageKey() {
+            return configValue('deviceAuthUserKey', DEFAULT_USER_KEY);
+        }
+
+        #startUrl() {
+            return String(configValue('deviceAuthStartUrl', '') || '').trim();
+        }
+
+        #pollUrl() {
+            return String(configValue('deviceAuthPollUrl', '') || '').trim();
+        }
+
+        #companionBase() {
+            return String(configValue('deviceAuthCompanionBase', '') || '').trim();
+        }
+
+        #emit(detail) {
+            try {
+                window.dispatchEvent(new CustomEvent('adaptfully:device-auth', { detail }));
+            } catch {
+                // ignore
+            }
+        }
+
+        #persistUser(user) {
+            const storage = getStorage();
+            if (!storage || !user?.id) {
+                return;
+            }
+            storage.set(this.#autoLoginStorageKey(), user.id);
+            try {
+                storage.set(this.#userStorageKey(), JSON.stringify({
+                    id: user.id,
+                    email: user.email || '',
+                }));
+            } catch {
+                // ignore
+            }
+        }
+
+        #clearPersisted() {
+            const storage = getStorage();
+            storage?.remove(this.#autoLoginStorageKey());
+            storage?.remove(this.#userStorageKey());
+        }
+
+        #readPersistedUser() {
+            const storage = getStorage();
+            const raw = storage?.get?.(this.#userStorageKey());
+            if (!raw || typeof raw !== 'string') {
+                return null;
+            }
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed?.id) {
+                    return {
+                        id: String(parsed.id),
+                        email: String(parsed.email || ''),
+                    };
+                }
+            } catch {
+                // ignore
+            }
+            return null;
+        }
+
+        #stopPoll() {
+            if (this._pollTimer != null) {
+                window.clearTimeout(this._pollTimer);
+                this._pollTimer = null;
+            }
+            this._pending = null;
+        }
+
+        #buildVerificationUrl(deviceCode, userCode, fromServer) {
+            if (fromServer) {
+                return String(fromServer);
+            }
+            const base = this.#companionBase();
+            if (!base) {
+                return '';
+            }
+            const join = base.includes('?') ? '&' : '?';
+            const code = encodeURIComponent(deviceCode || userCode || '');
+            return `${base}${join}code=${code}`;
+        }
+
+        whenReady(done) {
+            if (!this.#startUrl() || !this.#pollUrl()) {
+                done({
+                    error: 'device-auth: deviceAuthStartUrl and deviceAuthPollUrl are required',
+                });
+                return;
+            }
+            done();
+        }
+
+        login(callback) {
+            if (this.authenticated && this.user?.id) {
+                callback({ authenticated: true, user: this.getUser() });
+                return;
+            }
+            if (this._loginInFlight) {
+                return;
+            }
+            this.#stopPoll();
+            this._loginInFlight = true;
+
+            fetch(this.#startUrl(), {
+                method: 'POST',
+                headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+                body: '{}',
+            })
+                .then((response) => {
+                    if (!response.ok) {
+                        throw new Error(`device-login start failed (${response.status})`);
+                    }
+                    return response.json();
+                })
+                .then((data) => {
+                    const deviceCode = data.deviceCode || data.device_code;
+                    const userCode = data.userCode || data.user_code;
+                    const expiresIn = Number(data.expiresIn || data.expires_in || 600);
+                    const intervalMs = Math.max(
+                        1000,
+                        Number(data.interval || data.intervalMs || DEFAULT_INTERVAL_MS),
+                    );
+                    const verificationUrl = this.#buildVerificationUrl(
+                        deviceCode,
+                        userCode,
+                        data.verificationUrl || data.verification_url,
+                    );
+
+                    if (!deviceCode || !userCode) {
+                        throw new Error('device-login start missing deviceCode/userCode');
+                    }
+
+                    this._pending = {
+                        deviceCode,
+                        userCode,
+                        verificationUrl,
+                        expiresAt: Date.now() + (expiresIn * 1000),
+                        intervalMs,
+                        callback,
+                    };
+
+                    this.#emit({
+                        phase: 'pending',
+                        userCode,
+                        verificationUrl,
+                        qrUrl: verificationUrl,
+                        expiresIn,
+                        deviceCode,
+                    });
+
+                    this.#schedulePoll();
+                })
+                .catch((err) => {
+                    this._loginInFlight = false;
+                    this.#emit({
+                        phase: 'error',
+                        error: err?.message || String(err),
+                    });
+                    callback({ authenticated: false, user: null });
+                });
+        }
+
+        #schedulePoll() {
+            const pending = this._pending;
+            if (!pending) {
+                return;
+            }
+            this._pollTimer = window.setTimeout(() => this.#pollOnce(), pending.intervalMs);
+        }
+
+        #pollOnce() {
+            const pending = this._pending;
+            if (!pending) {
+                return;
+            }
+
+            if (Date.now() > pending.expiresAt) {
+                this.#stopPoll();
+                this._loginInFlight = false;
+                this.#emit({ phase: 'expired', userCode: pending.userCode });
+                pending.callback({ authenticated: false, user: null });
+                return;
+            }
+
+            const url = new URL(this.#pollUrl(), window.location.href);
+            url.searchParams.set('device_code', pending.deviceCode);
+
+            fetch(url.toString(), { headers: { Accept: 'application/json' } })
+                .then((response) => {
+                    if (!response.ok) {
+                        throw new Error(`device-login poll failed (${response.status})`);
+                    }
+                    return response.json();
+                })
+                .then((data) => {
+                    const status = String(data.status || '').toLowerCase();
+                    if (status === 'approved' && data.user?.id) {
+                        const user = {
+                            id: String(data.user.id),
+                            email: String(data.user.email || ''),
+                        };
+                        this.user = user;
+                        this.authenticated = true;
+                        this.#persistUser(user);
+                        this.#emit({
+                            phase: 'approved',
+                            userCode: pending.userCode,
+                            user,
+                        });
+                        const cb = pending.callback;
+                        this.#stopPoll();
+                        this._loginInFlight = false;
+                        cb({ authenticated: true, user: this.getUser() });
+                        return;
+                    }
+                    if (status === 'expired' || status === 'denied') {
+                        this.#emit({
+                            phase: status,
+                            userCode: pending.userCode,
+                        });
+                        const cb = pending.callback;
+                        this.#stopPoll();
+                        this._loginInFlight = false;
+                        cb({ authenticated: false, user: null });
+                        return;
+                    }
+                    this.#schedulePoll();
+                })
+                .catch((err) => {
+                    console.warn('[adaptfully device-auth] poll error', err);
+                    this.#schedulePoll();
+                });
+        }
+
+        autoLogin(callback) {
+            const stored = this.#readPersistedUser();
+            if (stored?.id) {
+                this.user = stored;
+                this.authenticated = true;
+                callback({ authenticated: true, user: this.getUser() });
+                return;
+            }
+            callback({ authenticated: false, user: null });
+        }
+
+        logout(callback) {
+            this.#stopPoll();
+            this._loginInFlight = false;
+            this.authenticated = false;
+            this.user = null;
+            this.#clearPersisted();
+            callback();
+        }
+
+        getUser() {
+            if (!this.authenticated || !this.user) {
+                return null;
+            }
+            return { id: this.user.id, email: this.user.email };
+        }
+
+        isAuthenticated() {
+            return !!this.authenticated;
+        }
+
+        /** Cancel an in-progress PIN/QR login without logging out a restored session. */
+        cancelLogin() {
+            const pending = this._pending;
+            this.#stopPoll();
+            this._loginInFlight = false;
+            if (pending?.callback) {
+                this.#emit({ phase: 'denied', userCode: pending.userCode });
+                pending.callback({ authenticated: false, user: null });
+            }
+        }
+    }
+
+    ns.auth.Device = () => new DeviceAuthPlugin();
+}(window.adaptfully));

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

@@ -0,0 +1,123 @@
+/* global window */
+
+/**
+ * Lean-back TV host (LG webOS and similar).
+ * Handles Back key → history/back listeners and exposes environment "tv".
+ * Listen for adaptfully:device-auth to render PIN/QR chrome in the game UI.
+ *
+ *   adaptfully.register('host', adaptfully.host.Tv);
+ */
+(function registerTvHost(ns) {
+    const { helpers } = ns.host;
+
+    ns.host.Tv = function tvHostFactory() {
+        const pauseListeners = [];
+        const captionsListeners = [];
+        const volumeListeners = {
+            sound: [],
+            music: [],
+            vo: [],
+            sfx: [],
+        };
+        const backListeners = [];
+        const deviceAuthListeners = [];
+        let features = null;
+        /** @type {Array<() => void>} */
+        const cleanups = [];
+
+        function onKeyDown(event) {
+            const key = event.key || '';
+            const keyCode = event.keyCode || event.which;
+            // webOS Back / Escape / browser Back
+            const isBack = key === 'Backspace'
+                || key === 'Escape'
+                || key === 'XF86Back'
+                || keyCode === 461
+                || keyCode === 27
+                || keyCode === 8;
+            if (!isBack) {
+                return;
+            }
+            if (backListeners.length === 0) {
+                return;
+            }
+            event.preventDefault();
+            event.stopPropagation();
+            helpers.emit(backListeners, { key, keyCode });
+        }
+
+        function onDeviceAuth(event) {
+            helpers.emit(deviceAuthListeners, event?.detail || null);
+        }
+
+        window.addEventListener('keydown', onKeyDown, true);
+        window.addEventListener('adaptfully:device-auth', onDeviceAuth);
+        cleanups.push(() => window.removeEventListener('keydown', onKeyDown, true));
+        cleanups.push(() => window.removeEventListener('adaptfully:device-auth', onDeviceAuth));
+
+        return {
+            kind: 'tv',
+
+            getEnvironment() {
+                return Promise.resolve('tv');
+            },
+
+            onPause(cb) {
+                return helpers.subscribe(pauseListeners, cb);
+            },
+
+            onCaptionsMuted(cb) {
+                return helpers.subscribe(captionsListeners, cb);
+            },
+
+            onVolume(channel, cb) {
+                const list = volumeListeners[channel];
+                if (!list) {
+                    return () => {};
+                }
+                return helpers.subscribe(list, cb);
+            },
+
+            /** Magix Remote / webOS Back */
+            onBack(cb) {
+                return helpers.subscribe(backListeners, cb);
+            },
+
+            /** Forwarded adaptfully:device-auth detail for PIN/QR UI */
+            onDeviceAuth(cb) {
+                return helpers.subscribe(deviceAuthListeners, cb);
+            },
+
+            setFeatures(next) {
+                features = next && typeof next === 'object' ? { ...next } : next;
+            },
+
+            notifyLoaded() {},
+
+            notifyProgress(_progress, _detail) {},
+
+            notifyEndGame(_payload) {},
+
+            send(_event, _data) {},
+
+            dispose() {
+                while (cleanups.length) {
+                    try {
+                        cleanups.pop()();
+                    } catch {
+                        // ignore
+                    }
+                }
+            },
+
+            /** @internal */
+            _getState() {
+                return {
+                    features,
+                    backListeners: backListeners.length,
+                    deviceAuthListeners: deviceAuthListeners.length,
+                };
+            },
+        };
+    };
+}(window.adaptfully));

package/package.json

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