@mpgd/cli 0.34.0 → 0.36.0

package/dist/testflight-submission.js

@@ -0,0 +1,462 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, copyFileSync, createReadStream, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ReleaseProcessError, runReleaseProcess } from './deploy-process.js';
+export const pinnedAscVersion = '5.5.0';
+const sha256Pattern = /^[0-9a-f]{64}$/u;
+const teamIdPattern = /^[A-Z0-9]{10}$/u;
+const apiKeyIdPattern = /^[A-Z0-9]{10}$/u;
+const ascIdPattern = /^[A-Za-z0-9][A-Za-z0-9-]*$/u;
+const marketingVersionPattern = /^\d+(?:\.\d+){0,2}$/u;
+const uploadTimeoutMs = 12 * 60 * 1000;
+const lookupTimeoutMs = 60_000;
+const maxJsonBytes = 1024 * 1024;
+export class IosSubmissionUncertainError extends Error {
+    uploadId;
+    constructor(uploadId) {
+        super(`iOS upload ${uploadId} was committed but its local checkpoint failed; inspect remote state before retry.`);
+        this.uploadId = uploadId;
+        this.name = 'IosSubmissionUncertainError';
+    }
+}
+/** Verify and use exactly the pinned asc release, with isolated environment auth. */
+export async function submitVerifiedIosBuild(input) {
+    if (process.platform !== 'darwin') {
+        throw new Error('Signed iOS IPA verification requires macOS.');
+    }
+    const tempRoot = mkdtempSync(path.join(tmpdir(), 'mpgd-asc-session-'));
+    try {
+        if (!path.isAbsolute(input.ascBinary)) {
+            throw new Error('asc binary must be an absolute file path.');
+        }
+        const binary = path.join(tempRoot, 'asc');
+        copyFileSync(input.ascBinary, binary);
+        chmodSync(binary, 0o700);
+        await verifyPinnedAscBinary(binary);
+        const stagedIpa = path.join(tempRoot, 'release.ipa');
+        copyFileSync(input.ipaFile, stagedIpa);
+        const stagedInput = { ...input, ipaFile: stagedIpa };
+        const resolvedPreflight = await preflight(stagedInput);
+        const { inspectSignedIosIpa } = await import(new URL('./ios-ipa-inspection.js', import.meta.url).href);
+        inspectSignedIosIpa(stagedIpa, {
+            expectedBundleId: input.bundleId,
+            expectedMarketingVersion: resolvedPreflight.marketingVersion,
+            expectedBuildNumber: resolvedPreflight.buildNumber,
+            expectedTeamId: input.record.inspectedTeamId ?? '',
+        });
+        const environment = isolatedAscEnvironment(input, tempRoot);
+        const runner = async (args, timeoutMs) => {
+            const result = await runReleaseProcess({
+                command: binary,
+                args: [...args, '--output', 'json'],
+                cwd: tempRoot,
+                environment,
+                timeoutMs,
+                maxOutputBytes: maxJsonBytes,
+                captureMachineStdout: true,
+                secretValues: [input.apiKeyId, input.apiIssuerId, input.apiPrivateKeyBase64],
+                signal: input.signal,
+            });
+            if (result.truncated || result.machineStdout === undefined) {
+                throw new Error('asc JSON output was truncated or unavailable.');
+            }
+            try {
+                return JSON.parse(result.machineStdout);
+            }
+            catch {
+                throw new Error('asc returned invalid JSON.');
+            }
+        };
+        return await submitVerifiedIosBuildResolved(stagedInput, runner, resolvedPreflight);
+    }
+    finally {
+        rmSync(tempRoot, { recursive: true, force: true });
+    }
+}
+/** Internal mock boundary used by credential-free submission tests. */
+export async function submitVerifiedIosBuildWithRunner(input, run) {
+    return submitVerifiedIosBuildResolved(input, run, await preflight(input));
+}
+async function submitVerifiedIosBuildResolved(input, run, { marketingVersion, buildNumber }) {
+    const base = {
+        appStoreAppId: input.appStoreAppId,
+        bundleId: input.bundleId,
+        marketingVersion,
+        buildNumber,
+        internalGroupId: input.internalGroupId,
+    };
+    const app = await run(['apps', 'view', '--id', input.appStoreAppId], lookupTimeoutMs);
+    if (!isRecord(app) || !isRecord(app.data) || app.data.id !== input.appStoreAppId
+        || app.data.type !== 'apps' || !isRecord(app.data.attributes)
+        || app.data.attributes.bundleId !== input.bundleId) {
+        throw new Error('App Store Connect app ID does not match the verified IPA bundle ID.');
+    }
+    const groupsResponse = await run([
+        'testflight',
+        'groups',
+        'list',
+        '--app',
+        input.appStoreAppId,
+        '--internal',
+        '--id',
+        input.internalGroupId,
+        '--paginate',
+    ], lookupTimeoutMs);
+    if (!findInternalGroup(groupsResponse, input.internalGroupId)) {
+        throw new Error('Configured TestFlight group is not an internal group of this app.');
+    }
+    let uploadId = input.resumeUploadId;
+    if (uploadId === undefined && input.resumeBuildId === undefined) {
+        const before = await lookupBuild(input, marketingVersion, buildNumber, run);
+        if (before !== undefined) {
+            return {
+                ...base,
+                status: 'unknown',
+                buildId: before.id,
+                detail: 'A build already uses this app version and build number; do not reupload.',
+            };
+        }
+        const existingUploads = await lookupUploadIds(input, marketingVersion, buildNumber, run);
+        if (existingUploads.length > 0) {
+            return {
+                ...base,
+                status: 'unknown',
+                ...(existingUploads.length === 1 ? { uploadId: existingUploads[0] } : {}),
+                detail: 'An upload already exists for this app version and build number; reconcile it before retry.',
+            };
+        }
+        let upload;
+        try {
+            upload = await run([
+                'builds', 'upload', '--app', input.appStoreAppId,
+                '--ipa', input.ipaFile, '--platform', 'IOS',
+                '--version', marketingVersion, '--build-number', buildNumber,
+                '--checksum',
+            ], uploadTimeoutMs);
+        }
+        catch (error) {
+            const observed = await lookupBuild(input, marketingVersion, buildNumber, run).catch(() => undefined);
+            return {
+                ...base,
+                status: 'unknown',
+                ...(observed === undefined ? {} : { buildId: observed.id }),
+                detail: `Upload result was not confirmed${failureReason(error)}; inspect App Store Connect before retry.`,
+            };
+        }
+        try {
+            uploadId = assertUploadResult(upload, statSync(input.ipaFile).size);
+        }
+        catch {
+            const observed = await lookupBuild(input, marketingVersion, buildNumber, run).catch(() => undefined);
+            return {
+                ...base,
+                status: 'unknown',
+                ...(observed === undefined ? {} : { buildId: observed.id }),
+                detail: 'Upload output was invalid; inspect App Store Connect before retry.',
+            };
+        }
+        try {
+            await input.onUploadCommitted?.(uploadId);
+        }
+        catch {
+            throw new IosSubmissionUncertainError(uploadId);
+        }
+    }
+    else if (uploadId !== undefined) {
+        const matches = (await lookupUploadIds(input, marketingVersion, buildNumber, run))
+            .filter((id) => id === uploadId);
+        if (matches.length !== 1) {
+            return {
+                ...base,
+                status: 'unknown',
+                uploadId,
+                detail: 'Checkpointed upload is not uniquely visible for this app and version.',
+            };
+        }
+    }
+    const uploadReference = uploadId === undefined ? {} : { uploadId };
+    let build;
+    try {
+        build = await lookupBuild(input, marketingVersion, buildNumber, run);
+    }
+    catch (error) {
+        return {
+            ...base,
+            status: input.resumeBuildId === undefined ? 'uploaded' : 'unknown',
+            ...uploadReference,
+            ...(input.resumeBuildId === undefined ? {} : { buildId: input.resumeBuildId }),
+            detail: `Upload committed; build processing lookup is temporarily unavailable${failureReason(error)}.`,
+        };
+    }
+    if (input.resumeBuildId !== undefined && build?.id !== input.resumeBuildId) {
+        return {
+            ...base,
+            status: 'unknown',
+            ...uploadReference,
+            buildId: input.resumeBuildId,
+            detail: 'Checkpointed build ID does not match the reserved App Store build.',
+        };
+    }
+    if (build === undefined) {
+        return {
+            ...base,
+            status: 'uploaded',
+            ...uploadReference,
+            detail: 'Upload committed; build is not yet discoverable.',
+        };
+    }
+    if (build.processingState === 'PROCESSING') {
+        return { ...base, status: 'processing', ...uploadReference, buildId: build.id };
+    }
+    if (build.processingState === 'FAILED' || build.processingState === 'INVALID') {
+        return {
+            ...base,
+            status: 'failed',
+            ...uploadReference,
+            buildId: build.id,
+            detail: `App Store Connect reported ${build.processingState}.`,
+        };
+    }
+    if (build.processingState !== 'VALID') {
+        return {
+            ...base,
+            status: 'unknown',
+            ...uploadReference,
+            buildId: build.id,
+            detail: 'App Store Connect returned an unknown processing state.',
+        };
+    }
+    try {
+        const added = await run(['builds', 'add-groups', '--build-id', build.id, '--group', input.internalGroupId], lookupTimeoutMs);
+        assertGroupAssignment(added, build.id, input.internalGroupId);
+    }
+    catch (error) {
+        const operatorAction = error instanceof ReleaseProcessError
+            && error.reason === 'exit'
+            && /export compliance|encryption declaration|account agreement|tax and banking/iu
+                .test(error.output);
+        const status = operatorAction ? 'action-required' : 'unknown';
+        return {
+            ...base,
+            status,
+            ...uploadReference,
+            buildId: build.id,
+            detail: `Build is processed, but internal group assignment needs inspection${failureReason(error)}.`,
+        };
+    }
+    let membershipFailure;
+    try {
+        const memberships = await run(['testflight', 'groups', 'list', '--build-id', build.id, '--internal'], lookupTimeoutMs);
+        if (findInternalGroup(memberships, input.internalGroupId)) {
+            return { ...base, status: 'testflight-ready', ...uploadReference, buildId: build.id };
+        }
+    }
+    catch (error) {
+        membershipFailure = error;
+        // Membership can be queried again by explicit build ID.
+    }
+    return {
+        ...base,
+        status: 'unknown',
+        ...uploadReference,
+        buildId: build.id,
+        detail: `Group assignment response was not confirmed by a membership read${failureReason(membershipFailure)}.`,
+    };
+}
+async function lookupUploadIds(input, marketingVersion, buildNumber, run) {
+    const response = await run([
+        'builds',
+        'uploads',
+        'list',
+        '--app',
+        input.appStoreAppId,
+        '--cf-bundle-short-version',
+        marketingVersion,
+        '--cf-bundle-version',
+        buildNumber,
+        '--platform',
+        'IOS',
+        '--paginate',
+    ], lookupTimeoutMs);
+    const items = readDataArray(response, 'builds uploads list');
+    if (items.some((item) => !isRecord(item) || item.type !== 'buildUploads'
+        || typeof item.id !== 'string' || !ascIdPattern.test(item.id)
+        || !isRecord(item.attributes)
+        || typeof item.attributes.cfBundleShortVersionString !== 'string'
+        || typeof item.attributes.cfBundleVersion !== 'string'
+        || typeof item.attributes.platform !== 'string')) {
+        throw new Error('asc builds uploads list returned a malformed upload.');
+    }
+    return items.filter((item) => isRecord(item) && isRecord(item.attributes)
+        && item.attributes.cfBundleShortVersionString === marketingVersion
+        && item.attributes.cfBundleVersion === buildNumber
+        && item.attributes.platform === 'IOS')
+        .map((item) => item.id);
+}
+async function lookupBuild(input, marketingVersion, buildNumber, run) {
+    const response = await run([
+        'builds',
+        'list',
+        '--app',
+        input.appStoreAppId,
+        '--version',
+        marketingVersion,
+        '--build-number',
+        buildNumber,
+        '--platform',
+        'IOS',
+        '--paginate',
+    ], lookupTimeoutMs);
+    const items = readDataArray(response, 'builds list');
+    if (items.some((item) => !isRecord(item) || item.type !== 'builds'
+        || typeof item.id !== 'string' || item.id === ''
+        || !isRecord(item.attributes) || typeof item.attributes.version !== 'string'
+        || typeof item.attributes.processingState !== 'string')) {
+        throw new Error('asc builds list returned a malformed build.');
+    }
+    const matching = items.filter((item) => item
+        .attributes.version === buildNumber);
+    if (matching.length > 1) {
+        throw new Error('App Store Connect returned multiple builds for the reserved version.');
+    }
+    const item = matching[0];
+    if (item === undefined) {
+        return undefined;
+    }
+    if (!isRecord(item) || typeof item.id !== 'string' || item.id === ''
+        || !isRecord(item.attributes) || typeof item.attributes.processingState !== 'string') {
+        throw new Error('asc builds list returned a malformed build.');
+    }
+    return { id: item.id, processingState: item.attributes.processingState };
+}
+function findInternalGroup(response, groupId) {
+    return readDataArray(response, 'TestFlight groups list').some((value) => isRecord(value)
+        && value.type === 'betaGroups' && value.id === groupId
+        && isRecord(value.attributes) && value.attributes.isInternalGroup === true);
+}
+function readDataArray(response, command) {
+    if (!isRecord(response) || !Array.isArray(response.data)) {
+        throw new Error(`asc ${command} returned an invalid JSON schema.`);
+    }
+    return response.data;
+}
+function assertUploadResult(value, expectedBytes) {
+    if (!isRecord(value) || typeof value.uploadId !== 'string' || value.uploadId === ''
+        || typeof value.fileId !== 'string' || value.fileId === ''
+        || value.uploaded !== true || value.fileSize !== expectedBytes
+        || (Array.isArray(value.operations) && value.operations.length > 0)) {
+        throw new Error('asc upload result was not a confirmed, redacted committed upload.');
+    }
+    return value.uploadId;
+}
+function assertGroupAssignment(value, buildId, groupId) {
+    if (!isRecord(value) || value.action !== 'added' || value.buildId !== buildId
+        || !Array.isArray(value.groupIds)
+        || value.groupIds.some((id) => typeof id !== 'string'
+            || id !== groupId)) {
+        throw new Error('asc returned an invalid TestFlight group assignment.');
+    }
+}
+function failureReason(error) {
+    return error instanceof ReleaseProcessError ? ` (${error.reason})` : '';
+}
+async function preflight(input) {
+    const version = input.record.platformVersion;
+    const buildNumber = version.buildNumber;
+    const marketingVersion = version.marketingVersion;
+    if (input.record.target !== 'ios' || input.bundleId !== input.record.inspectedAppId
+        || !teamIdPattern.test(input.record.inspectedTeamId ?? '')
+        || !/^[1-9]\d*$/u.test(String(buildNumber))
+        || typeof marketingVersion !== 'string'
+        || !marketingVersionPattern.test(marketingVersion)
+        || !/^\d+$/u.test(input.appStoreAppId)
+        || !ascIdPattern.test(input.internalGroupId)
+        || (input.resumeUploadId !== undefined && !ascIdPattern.test(input.resumeUploadId))
+        || (input.resumeUploadId === undefined) !== (input.resumeArtifactSha256 === undefined)
+        || (input.resumeArtifactSha256 !== undefined
+            && input.resumeArtifactSha256 !== input.record.artifactSha256)
+        || !sha256Pattern.test(input.record.artifactSha256)
+        || !input.ipaFile.endsWith('.ipa') || !existsSync(input.ipaFile)
+        || !statSync(input.ipaFile).isFile()) {
+        throw new Error('TestFlight submission requires a matching verified iOS IPA build record.');
+    }
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(input.ipaFile)) {
+        hash.update(chunk);
+    }
+    if (hash.digest('hex') !== input.record.artifactSha256) {
+        throw new Error('TestFlight IPA bytes differ from the immutable build record.');
+    }
+    return { marketingVersion, buildNumber: String(buildNumber) };
+}
+export function isolatedAscEnvironment(input, directory, source = process.env) {
+    if (!apiKeyIdPattern.test(input.apiKeyId)
+        || input.apiIssuerId.trim() === '' || input.apiPrivateKeyBase64.trim() === '') {
+        throw new Error('App Store Connect API credentials are incomplete.');
+    }
+    // asc only needs network/locale process settings, never Git, registry, or signing secrets.
+    const inheritedNames = [
+        'PATH',
+        'LANG',
+        'LC_ALL',
+        'LC_CTYPE',
+        'TZ',
+        'HTTPS_PROXY',
+        'HTTP_PROXY',
+        'NO_PROXY',
+        'https_proxy',
+        'http_proxy',
+        'no_proxy',
+        'SSL_CERT_FILE',
+        'CURL_CA_BUNDLE',
+    ];
+    const environment = Object.fromEntries(inheritedNames.flatMap((name) => {
+        const value = source[name];
+        return value === undefined ? [] : [[name, value]];
+    }));
+    return {
+        ...environment,
+        HOME: directory,
+        CFFIXED_USER_HOME: directory,
+        XDG_CONFIG_HOME: directory,
+        TMPDIR: directory,
+        TMP: directory,
+        TEMP: directory,
+        ASC_TELEMETRY_DISABLED: '1',
+        ASC_BYPASS_KEYCHAIN: '1',
+        ASC_STRICT_AUTH: '1',
+        ASC_KEY_ID: input.apiKeyId,
+        ASC_ISSUER_ID: input.apiIssuerId,
+        ASC_PRIVATE_KEY_B64: input.apiPrivateKeyBase64,
+        ASC_TIMEOUT: '60s',
+        ASC_UPLOAD_TIMEOUT: '10m',
+    };
+}
+/** The package consumes one reviewed asc pin; it does not trust PATH or version text. */
+export async function verifyPinnedAscBinary(binary, pinFile = fileURLToPath(new URL('./asc-pin.json', import.meta.url))) {
+    if (!path.isAbsolute(binary) || !existsSync(binary) || !statSync(binary).isFile()) {
+        throw new Error('asc binary must be an existing absolute file.');
+    }
+    const pin = JSON.parse(readFileSync(pinFile, 'utf8'));
+    const host = `${process.platform}-${process.arch}`;
+    if (!isRecord(pin) || pin.version !== pinnedAscVersion
+        || !isRecord(pin.assets) || !isRecord(pin.assets[host])) {
+        throw new Error('No reviewed asc binary pin exists for this host.');
+    }
+    const expected = pin.assets[host].sha256;
+    if (typeof expected !== 'string' || !sha256Pattern.test(expected)) {
+        throw new Error('Reviewed asc binary pin is malformed.');
+    }
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(realpathSync(binary))) {
+        hash.update(chunk);
+    }
+    if (hash.digest('hex') !== expected) {
+        throw new Error('asc binary checksum differs from the reviewed 5.5.0 pin.');
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -40,32 +40,39 @@
     "mpgd": "./dist/bin.js"
   },
   "dependencies": {
+    "@googleapis/androidpublisher": "42.0.0",
     "@gunshi/plugin-completion": "^0.35.1",
     "@gunshi/plugin-i18n": "^0.35.1",
     "@gunshi/resources": "^0.35.1",
     "@xmldom/xmldom": "0.9.12",
+    "acorn": "8.17.0",
     "entities": "^8.0.0",
     "esbuild": "^0.28.1",
     "gunshi": "^0.35.1",
+    "semver": "^7.8.5",
+    "sharp": "0.35.3",
+    "typia": "13.0.2",
     "undici": "^7.28.0",
-    "@mpgd/phaser-assets": "0.7.0"
+    "vite": "8.1.3",
+    "@mpgd/catalog": "0.7.6",
+    "@mpgd/phaser-assets": "0.7.0",
+    "@mpgd/target-config": "0.17.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/semver": "^7.8.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.12.5",
-    "@mpgd/adapter-browser": "0.7.6",
-    "@mpgd/adapter-devvit": "0.9.11",
-    "@mpgd/adapter-capacitor": "0.5.0",
-    "@mpgd/adapter-verse8": "0.3.9",
+    "@mpgd/adapter-ait": "0.12.6",
+    "@mpgd/adapter-browser": "0.7.7",
+    "@mpgd/adapter-capacitor": "0.6.0",
+    "@mpgd/adapter-devvit": "0.9.12",
+    "@mpgd/adapter-verse8": "0.3.10",
+    "@mpgd/analytics": "0.4.0",
     "@mpgd/bridge": "0.10.0",
-    "@mpgd/catalog": "0.7.5",
-    "@mpgd/i18n": "0.6.4",
-    "@mpgd/platform": "0.13.0",
-    "@mpgd/target-config": "0.16.0",
-    "@mpgd/analytics": "0.3.15",
-    "@mpgd/game-services": "0.16.0"
+    "@mpgd/game-services": "0.17.0",
+    "@mpgd/i18n": "0.6.5",
+    "@mpgd/platform": "0.14.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/phaser-game/README.md

@@ -149,17 +149,32 @@ preview, Apps in Toss, Devvit, Android, and iOS bundles.
 ## Viewport And Controls
 
 The starter computes an initial viewport snapshot with `@mpgd/target-config`.
-Measure the game container first, then fall back to `visualViewport` or
-`window.innerWidth`:
+`measureTargetViewport` measures the game container first, then falls back to
+`visualViewport` or the window. It returns `null` while every surface is still
+zero-sized (a hidden iframe, a collapsed embed or a background tab before
+layout), so the starter waits for the first usable size instead of failing
+viewport validation:
 
 ```ts
-import { resolveTargetViewportSnapshot } from '@mpgd/target-config';
-
-const measured = measureGameViewport();
+import {
+  measureTargetViewport,
+  resolveTargetViewportSnapshot,
+  waitForTargetViewportMeasurement,
+} from '@mpgd/target-config';
+
+const measured = await waitForTargetViewportMeasurement({
+  measure: () =>
+    measureTargetViewport({
+      container: document.querySelector<HTMLElement>('#game'),
+      visualViewport: window.visualViewport,
+      window,
+    }),
+  // Call the listener on resize, visualViewport resize, visibilitychange and a
+  // ResizeObserver on #game; return a function that removes those listeners.
+  subscribe: subscribeToGameViewportChanges,
+});
 const viewport = resolveTargetViewportSnapshot({
-  width: measured.width,
-  height: measured.height,
-  source: measured.source,
+  ...measured,
   runtime: runtime.config.runtime,
   orientationPolicy: {
     mode: 'prefer-landscape',

package/templates/phaser-game/src/main.ts

@@ -4,7 +4,10 @@ import { createAnalyticsReporter, createBufferedAnalyticsSink } from '@mpgd/anal
 import { resolveTargetMpgdLocale, type Locale } from '@mpgd/i18n';
 import type { IdentitySession, LaunchIntent, PlatformGateway } from '@mpgd/platform';
 import {
+  measureTargetViewport,
   resolveTargetViewportSnapshot,
+  waitForTargetViewportMeasurement,
+  type TargetViewportMeasurement,
   type TargetViewportOrientationPolicy,
 } from '@mpgd/target-config';
 
@@ -36,8 +39,13 @@ async function bootstrap(): Promise<void> {
     const orientationPolicy = {
       mode: 'prefer-landscape',
     } as const satisfies TargetViewportOrientationPolicy;
+    // A hidden iframe or background tab can boot at 0x0; wait for layout instead of failing.
+    const measurement = await waitForTargetViewportMeasurement({
+      measure: measureGameViewport,
+      subscribe: subscribeToGameViewportChanges,
+    });
     const viewport = resolveTargetViewportSnapshot({
-      ...measureGameViewport(),
+      ...measurement,
       runtime: runtime.config.runtime,
       orientationPolicy,
     });
@@ -152,40 +160,33 @@ function renderBootstrapError(error: unknown, locale: Locale): void {
 }
 
 /** Measure the game surface before falling back to browser viewport geometry. */
-function measureGameViewport(): {
-  readonly width: number;
-  readonly height: number;
-  readonly source: 'container' | 'visual-viewport' | 'window';
-} {
+function measureGameViewport(): TargetViewportMeasurement | null {
+  return measureTargetViewport({
+    container: document.querySelector<HTMLElement>('#game'),
+    visualViewport: window.visualViewport,
+    window,
+  });
+}
+
+/** Notify when the game surface may have gained a size or become visible. */
+function subscribeToGameViewportChanges(listener: () => void): () => void {
   const container = document.querySelector<HTMLElement>('#game');
-  const rect = container?.getBoundingClientRect();
-
-  if (rect !== undefined && rect.width > 0 && rect.height > 0) {
-    return {
-      width: rect.width,
-      height: rect.height,
-      source: 'container',
-    };
-  }
+  const observer =
+    container === null || typeof ResizeObserver !== 'function'
+      ? undefined
+      : new ResizeObserver(listener);
 
-  const visualViewport = window.visualViewport;
-
-  if (
-    visualViewport !== undefined &&
-    visualViewport !== null &&
-    visualViewport.width > 0 &&
-    visualViewport.height > 0
-  ) {
-    return {
-      width: visualViewport.width,
-      height: visualViewport.height,
-      source: 'visual-viewport',
-    };
+  if (container !== null) {
+    observer?.observe(container);
   }
-
-  return {
-    width: window.innerWidth,
-    height: window.innerHeight,
-    source: 'window',
+  window.addEventListener('resize', listener);
+  window.visualViewport?.addEventListener('resize', listener);
+  document.addEventListener('visibilitychange', listener);
+
+  return () => {
+    observer?.disconnect();
+    window.removeEventListener('resize', listener);
+    window.visualViewport?.removeEventListener('resize', listener);
+    document.removeEventListener('visibilitychange', listener);
   };
 }