@mpgd/cli 0.28.1 → 0.30.0

package/dist/microsoft-store-pwa-release.d.ts

@@ -0,0 +1,58 @@
+import { type MicrosoftStorePwaReleaseEvidence } from './microsoft-store-pwa-e2e.js';
+/**
+* Release-evidence primitives shared by the build-time artifact writer and the
+* hosted-deployment verifier. Kept free of repo-internal imports so the public
+* CLI can verify deployments without the mpgd-kit checkout.
+*/
+export interface PrecacheEntry {
+  readonly url: string;
+  readonly source: string | Uint8Array;
+}
+export interface MicrosoftStorePwaProvenance {
+  readonly appVersion: string;
+  readonly buildId: string;
+  readonly sourceGitSha: string;
+  readonly kitGitSha: string;
+}
+export declare function assertMicrosoftStorePwaProvenance(input: MicrosoftStorePwaProvenance): MicrosoftStorePwaProvenance;
+export declare function createMicrosoftStorePwaRevision(input: {
+  readonly appVersion: string;
+  readonly buildId: string;
+  readonly sourceGitSha: string;
+  readonly kitGitSha: string;
+  readonly precacheEntries: readonly PrecacheEntry[];
+}): string;
+/**
+* Recompute a release revision by streaming each precached file through the
+* digest instead of materializing every payload in memory, for verifiers
+* that only have the artifact root and the recorded URL list.
+*/
+export declare function createMicrosoftStorePwaRevisionFromFiles(input: {
+  readonly appVersion: string;
+  readonly buildId: string;
+  readonly sourceGitSha: string;
+  readonly kitGitSha: string;
+  readonly precacheUrls: readonly string[];
+  readonly artifactRoot: string;
+}): string;
+export declare function createMicrosoftStorePwaReleaseEvidence(input: {
+  readonly pwaId: string;
+  readonly appVersion: string;
+  readonly buildId: string;
+  readonly sourceGitSha: string;
+  readonly kitGitSha: string;
+  readonly revision: string;
+  readonly precacheUrls: readonly string[];
+}): MicrosoftStorePwaReleaseEvidence;
+export declare function createMicrosoftStorePwaServiceWorker(evidence: MicrosoftStorePwaReleaseEvidence): string;
+export declare function readMicrosoftStorePwaReleaseEvidence(path: string): MicrosoftStorePwaReleaseEvidence;
+/**
+* Enumerate the precacheable files of a PWA artifact. Sourcemaps, the release
+* evidence document, and the service worker itself are excluded because the
+* release revision only covers the precached payload. Symbolic links are
+* rejected so callers cannot be tricked into hashing files outside the root.
+*/
+/** Enumerate only precache URLs without reading any payload bytes. */
+export declare function listPrecacheUrls(artifactRoot: string): readonly string[];
+export declare function listPrecacheEntries(artifactRoot: string): readonly PrecacheEntry[];
+export declare function requireGameSpecificPwaId(value: unknown): string;

package/dist/microsoft-store-pwa-release.js

@@ -0,0 +1,343 @@
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, statSync, } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+import { assertMicrosoftStorePwaPrecacheUrl, assertMicrosoftStorePwaReleaseEvidence, microsoftStorePwaCacheSchema, } from './microsoft-store-pwa-e2e.js';
+export function assertMicrosoftStorePwaProvenance(input) {
+    return {
+        appVersion: requireNonEmptyString(input.appVersion, 'PWA app version'),
+        buildId: requireNonEmptyString(input.buildId, 'PWA build ID'),
+        sourceGitSha: requireGitSha(input.sourceGitSha, 'PWA source Git SHA'),
+        kitGitSha: requireGitSha(input.kitGitSha, 'PWA kit Git SHA'),
+    };
+}
+export function createMicrosoftStorePwaRevision(input) {
+    const hash = createHash('sha256');
+    const release = {
+        appVersion: requireNonEmptyString(input.appVersion, 'PWA app version'),
+        buildId: requireNonEmptyString(input.buildId, 'PWA build ID'),
+        sourceGitSha: requireGitSha(input.sourceGitSha, 'PWA source Git SHA'),
+        kitGitSha: requireGitSha(input.kitGitSha, 'PWA kit Git SHA'),
+    };
+    updateRevisionField(hash, microsoftStorePwaCacheSchema);
+    updateRevisionField(hash, JSON.stringify(release));
+    for (const entry of normalizePrecacheEntries(input.precacheEntries)) {
+        updateRevisionField(hash, entry.url);
+        updateRevisionField(hash, entry.source);
+    }
+    return hash.digest('hex').slice(0, 16);
+}
+/**
+ * Recompute a release revision by streaming each precached file through the
+ * digest instead of materializing every payload in memory, for verifiers
+ * that only have the artifact root and the recorded URL list.
+ */
+export function createMicrosoftStorePwaRevisionFromFiles(input) {
+    const hash = createHash('sha256');
+    const release = {
+        appVersion: requireNonEmptyString(input.appVersion, 'PWA app version'),
+        buildId: requireNonEmptyString(input.buildId, 'PWA build ID'),
+        sourceGitSha: requireGitSha(input.sourceGitSha, 'PWA source Git SHA'),
+        kitGitSha: requireGitSha(input.kitGitSha, 'PWA kit Git SHA'),
+    };
+    updateRevisionField(hash, microsoftStorePwaCacheSchema);
+    updateRevisionField(hash, JSON.stringify(release));
+    const urls = [...input.precacheUrls]
+        .filter((url) => url !== './pwa-release.json' && !url.endsWith('.map'))
+        .map(assertMicrosoftStorePwaPrecacheUrl)
+        .sort(compareCodeUnits);
+    for (const url of urls) {
+        const file = resolve(input.artifactRoot, url.replace(/^\.\//u, ''));
+        if (!existsSync(file)) {
+            throw new Error(`PWA precache URL has no artifact file: ${url}`);
+        }
+        updateRevisionField(hash, url);
+        hash.update(`${String(statSync(file).size)}:`);
+        hashStreamInto(hash, file);
+    }
+    return hash.digest('hex').slice(0, 16);
+}
+function hashStreamInto(hash, file) {
+    const handle = openSync(file, 'r');
+    const chunk = Buffer.allocUnsafe(1024 * 1024);
+    try {
+        let read = readSync(handle, chunk, 0, chunk.length, null);
+        while (read > 0) {
+            hash.update(chunk.subarray(0, read));
+            read = readSync(handle, chunk, 0, chunk.length, null);
+        }
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+export function createMicrosoftStorePwaReleaseEvidence(input) {
+    const pwaId = requireGameSpecificPwaId(input.pwaId);
+    const revision = requireRevision(input.revision);
+    const cachePrefix = `mpgd-pwa-${createHash('sha256').update(pwaId).digest('hex').slice(0, 12)}-`;
+    return {
+        schemaVersion: 1,
+        cacheSchema: microsoftStorePwaCacheSchema,
+        pwaId,
+        appVersion: requireNonEmptyString(input.appVersion, 'PWA app version'),
+        buildId: requireNonEmptyString(input.buildId, 'PWA build ID'),
+        sourceGitSha: requireGitSha(input.sourceGitSha, 'PWA source Git SHA'),
+        kitGitSha: requireGitSha(input.kitGitSha, 'PWA kit Git SHA'),
+        configTarget: 'microsoft-store',
+        revision,
+        cachePrefix,
+        cacheNamePattern: `${cachePrefix}{scope}-${revision}`,
+        precacheUrls: normalizePrecacheUrls(input.precacheUrls),
+    };
+}
+export function createMicrosoftStorePwaServiceWorker(evidence) {
+    const revision = requireRevision(evidence.revision);
+    const cachePrefix = requireNonEmptyString(evidence.cachePrefix, 'PWA cache prefix');
+    const cacheNamePattern = requireNonEmptyString(evidence.cacheNamePattern, 'PWA cache name pattern');
+    const precacheUrls = normalizePrecacheUrls(evidence.precacheUrls);
+    if (cacheNamePattern !== `${cachePrefix}{scope}-${revision}`) {
+        throw new Error('PWA cache name pattern is inconsistent.');
+    }
+    return `'use strict';
+
+const CACHE_NAMESPACE = ${JSON.stringify(cachePrefix)};
+const CACHE_SCOPE = encodeURIComponent(self.registration.scope);
+const CACHE_PREFIX = CACHE_NAMESPACE + CACHE_SCOPE + '-';
+const CACHE_NAME = ${JSON.stringify(cacheNamePattern)}.replace('{scope}', CACHE_SCOPE);
+const PRECACHE_URLS = ${JSON.stringify(precacheUrls, null, 2)};
+const INDEX_URL = new URL('./index.html', self.registration.scope).href;
+const APP_BASE_URL = self.registration.scope;
+
+function escapeHtmlAttribute(value) {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('"', '"')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+async function normalizeCachedNavigationResponse(response) {
+  if (!response.redirected) {
+    return response;
+  }
+
+  // Static hosts commonly canonicalize /index.html to /. A redirected response
+  // can be stored by Cache API, but Chromium rejects it when a service worker
+  // later returns it for a navigation whose URL is different. Reconstructing
+  // clears Response.url, so inject an explicit deployment-scope base before
+  // returning the same-origin app shell for a nested SPA route.
+  const html = await response.text();
+  const headPattern = /<head(?:\\s[^>]*)?>/iu;
+
+  if (!headPattern.test(html)) {
+    throw new Error('Cached PWA app shell is missing a head element.');
+  }
+
+  const headers = new Headers(response.headers);
+  headers.delete('content-encoding');
+  headers.delete('content-length');
+  const base = '<base href="' + escapeHtmlAttribute(APP_BASE_URL) + '">';
+  return new Response(html.replace(headPattern, (head) => head + base), {
+    headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+}
+
+self.addEventListener('install', (event) => {
+  event.waitUntil((async () => {
+    const cache = await caches.open(CACHE_NAME);
+
+    try {
+      const requests = PRECACHE_URLS.map((url) => new Request(
+        new URL(url, self.registration.scope),
+        { cache: 'reload' },
+      ));
+      await cache.addAll(requests);
+    } catch (error) {
+      try {
+        await caches.delete(CACHE_NAME);
+      } catch {
+        // Preserve the original installation error when cleanup also fails.
+      }
+      throw error;
+    }
+  })());
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil((async () => {
+    const cacheNames = await caches.keys();
+    await Promise.all(
+      cacheNames
+        .filter((name) => name.startsWith(CACHE_PREFIX) && name !== CACHE_NAME)
+        .map((name) => caches.delete(name)),
+    );
+    await self.clients.claim();
+  })());
+});
+
+self.addEventListener('fetch', (event) => {
+  const request = event.request;
+
+  if (request.method !== 'GET') {
+    return;
+  }
+
+  const url = new URL(request.url);
+
+  if (url.origin !== self.location.origin) {
+    return;
+  }
+
+  if (request.mode === 'navigate') {
+    event.respondWith((async () => {
+      const cache = await caches.open(CACHE_NAME);
+      const cachedIndex = await cache.match(INDEX_URL);
+      return cachedIndex === undefined
+        ? fetch(request)
+        : normalizeCachedNavigationResponse(cachedIndex);
+    })());
+    return;
+  }
+
+  event.respondWith((async () => {
+    const cache = await caches.open(CACHE_NAME);
+    return await cache.match(request, { ignoreSearch: true }) ?? fetch(request);
+  })());
+});
+`;
+}
+export function readMicrosoftStorePwaReleaseEvidence(path) {
+    return assertMicrosoftStorePwaReleaseEvidence(readJsonFile(path));
+}
+/**
+ * Enumerate the precacheable files of a PWA artifact. Sourcemaps, the release
+ * evidence document, and the service worker itself are excluded because the
+ * release revision only covers the precached payload. Symbolic links are
+ * rejected so callers cannot be tricked into hashing files outside the root.
+ */
+/** Enumerate only precache URLs without reading any payload bytes. */
+export function listPrecacheUrls(artifactRoot) {
+    const files = [];
+    const pendingDirectories = [artifactRoot];
+    while (pendingDirectories.length > 0) {
+        const directory = pendingDirectories.pop();
+        if (directory === undefined) {
+            throw new Error('PWA artifact traversal lost its directory.');
+        }
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = resolve(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`PWA artifact must not contain symbolic links: ${path}`);
+            }
+            if (entry.isDirectory()) {
+                pendingDirectories.push(path);
+            }
+            else if (entry.isFile()) {
+                files.push(path);
+            }
+        }
+    }
+    return files
+        .filter((path) => !path.endsWith('.map')
+        && !path.endsWith(`${sep}pwa-release.json`)
+        && !path.endsWith(`${sep}service-worker.js`))
+        .map((path) => toPrecacheUrl(artifactRoot, path))
+        .sort(compareCodeUnits);
+}
+export function listPrecacheEntries(artifactRoot) {
+    const files = [];
+    const pendingDirectories = [artifactRoot];
+    while (pendingDirectories.length > 0) {
+        const directory = pendingDirectories.pop();
+        if (directory === undefined) {
+            throw new Error('PWA artifact traversal lost its directory.');
+        }
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = resolve(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`PWA artifact must not contain symbolic links: ${path}`);
+            }
+            if (entry.isDirectory()) {
+                pendingDirectories.push(path);
+            }
+            else if (entry.isFile()) {
+                files.push(path);
+            }
+        }
+    }
+    return files
+        .filter((path) => !path.endsWith('.map')
+        && !path.endsWith(`${sep}pwa-release.json`)
+        && !path.endsWith(`${sep}service-worker.js`))
+        .map((path) => ({
+        url: toPrecacheUrl(artifactRoot, path),
+        source: readFileSync(path),
+    }))
+        .sort((left, right) => compareCodeUnits(left.url, right.url));
+}
+function normalizePrecacheEntries(entries) {
+    const entriesByUrl = new Map();
+    for (const entry of entries) {
+        const url = assertMicrosoftStorePwaPrecacheUrl(entry.url);
+        if (entriesByUrl.has(url)) {
+            throw new Error(`Duplicate PWA precache URL: ${url}`);
+        }
+        if (typeof entry.source !== 'string' && !(entry.source instanceof Uint8Array)) {
+            throw new Error(`PWA precache source must be bytes or text: ${url}`);
+        }
+        entriesByUrl.set(url, entry.source);
+    }
+    return [...entriesByUrl.entries()]
+        .sort(([left], [right]) => compareCodeUnits(left, right))
+        .map(([url, source]) => ({ url, source }));
+}
+function normalizePrecacheUrls(urls) {
+    const normalized = urls.map(assertMicrosoftStorePwaPrecacheUrl);
+    if (new Set(normalized).size !== normalized.length) {
+        throw new Error('PWA precache URLs must be unique.');
+    }
+    return normalized.sort(compareCodeUnits);
+}
+function toPrecacheUrl(root, path) {
+    const portablePath = relative(root, path).split(sep).join('/');
+    return assertMicrosoftStorePwaPrecacheUrl(`./${portablePath}`);
+}
+export function requireGameSpecificPwaId(value) {
+    const pwaId = requireNonEmptyString(value, 'Microsoft Store PWA manifest id');
+    if (pwaId === '.' || pwaId === './' || pwaId === '/') {
+        throw new Error('Microsoft Store PWA manifest id must be game-specific.');
+    }
+    return pwaId;
+}
+function updateRevisionField(hash, value) {
+    const bytes = typeof value === 'string' ? Buffer.from(value, 'utf8') : value;
+    hash.update(`${String(bytes.byteLength)}:`);
+    hash.update(bytes);
+}
+function requireGitSha(value, label) {
+    const sha = requireNonEmptyString(value, label);
+    if (!/^[0-9a-f]{40}$/u.test(sha)) {
+        throw new Error(`${label} must be a full 40-character hexadecimal SHA.`);
+    }
+    return sha;
+}
+function requireRevision(value) {
+    const revision = requireNonEmptyString(value, 'PWA revision');
+    if (!/^[0-9a-f]{16}$/u.test(revision)) {
+        throw new Error('PWA revision must be a 16-character hexadecimal digest.');
+    }
+    return revision;
+}
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function readJsonFile(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}

package/dist/offline-playtest.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { decodeHTMLAttribute } from 'entities';
-import { build } from 'esbuild';
+import { build, transform } from 'esbuild';
 export const defaultOfflinePlaytestArtifactDir = 'artifacts/web-preview';
 export const defaultOfflinePlaytestOutputDir = 'artifacts/offline-playtest';
 export const defaultOfflinePlaytestMaximumBytes = 25 * 1024 * 1024;
@@ -530,7 +530,11 @@ async function bundleEntry(entryFile, context) {
         platform: 'browser',
         target: 'es2022',
         keepNames: true,
-        minify: true,
+        minifyWhitespace: true,
+        minifySyntax: true,
+        // Random deferred markers must not influence esbuild's short identifier choices.
+        // Keep their collision resistance; rename identifiers after resolving the markers.
+        minifyIdentifiers: false,
         metafile: true,
         sourcemap: false,
         legalComments: 'none',
@@ -542,7 +546,18 @@ async function bundleEntry(entryFile, context) {
         throw new Error('The offline playtest bundler did not produce JavaScript.');
     }
     recordRetainedBundledAssets(result.metafile, context);
-    const script = resolveDeferredJavaScriptAssets(scriptOutput.text, deferredAssets, context);
+    const resolvedScript = resolveDeferredJavaScriptAssets(scriptOutput.text, deferredAssets, context);
+    const { code: script } = await transform(resolvedScript, {
+        loader: 'js',
+        format: 'esm',
+        target: 'es2022',
+        keepNames: true,
+        minifyIdentifiers: true,
+        minifyWhitespace: true,
+        minifySyntax: false,
+        legalComments: 'none',
+        sourcemap: false,
+    });
     const stylesheetOutput = result.outputFiles.find((file) => file.path.endsWith('.css'));
     assertNoEntryImportMetaUrl(script);
     assertSupportedBundledRuntime(script);
@@ -1271,7 +1286,8 @@ function parseStaticElementConstructor(initializer, rawInitializer, allowAnyCrea
     if (constructor?.[2] === undefined) {
         const initializerCodePositions = createCodePositionMap(rawInitializer, true);
         const normalizedInitializer = maskNonCode(rawInitializer, initializerCodePositions).trim();
-        const createdElement = /^(?:(globalThis|self|window)\s*\.\s*)?document\s*\.\s*createElement\s*\(\s*\)\s*$/u.exec(normalizedInitializer);
+        // The code mask retains the opening quote of a literal so token boundaries survive.
+        const createdElement = /^(?:(globalThis|self|window)\s*\.\s*)?document\s*\.\s*createElement\s*\(\s*["'`]\s*\)\s*$/u.exec(normalizedInitializer);
         let openingParenthesis = -1;
         for (let index = 0; index < rawInitializer.length; index += 1) {
             if (rawInitializer[index] === '(' && initializerCodePositions[index] === 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.28.1",
+  "version": "0.30.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -53,17 +53,17 @@
     "ttsc": "0.18.4",
     "typescript": "7.0.2",
     "@mpgd/adapter-ait": "0.12.1",
-    "@mpgd/adapter-capacitor": "0.4.10",
-    "@mpgd/adapter-devvit": "0.9.6",
-    "@mpgd/adapter-verse8": "0.3.4",
+    "@mpgd/adapter-devvit": "0.9.7",
     "@mpgd/adapter-browser": "0.7.3",
+    "@mpgd/adapter-verse8": "0.3.5",
+    "@mpgd/adapter-capacitor": "0.4.10",
     "@mpgd/analytics": "0.3.12",
     "@mpgd/bridge": "0.9.0",
     "@mpgd/catalog": "0.7.2",
-    "@mpgd/game-services": "0.14.0",
-    "@mpgd/i18n": "0.6.0",
+    "@mpgd/game-services": "0.15.0",
+    "@mpgd/i18n": "0.6.1",
     "@mpgd/phaser-assets": "0.4.1",
-    "@mpgd/target-config": "0.14.0",
+    "@mpgd/target-config": "0.15.0",
     "@mpgd/platform": "0.12.0"
   },
   "main": "./dist/index.js",

package/templates/phaser-game/agent/game-manifest.json

@@ -36,6 +36,10 @@
       "id": "platform.gateway.bootstrap-intents",
       "owner": "src/main.ts"
     },
+    {
+      "id": "platform.ui.text-selection",
+      "owner": "src/platform/textSelection.ts"
+    },
     {
       "id": "runtime.viewport.orientation-policy",
       "owner": "src/main.ts"

package/templates/phaser-game/mpgd.game.json

@@ -5,6 +5,9 @@
       "backgroundColor": "#0f172a"
     }
   },
+  "ui": {
+    "textSelection": "disabled"
+  },
   "acceptance": {
     "gameplay": {
       "schemaVersion": 1,

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

@@ -1,6 +1,16 @@
+import gameProjectConfig from '../mpgd.game.json';
+
 import { renderEntryFailure } from './runtime/renderEntryFailure';
+import {
+  installTextSelectionPolicy,
+  resolveTextSelectionMode,
+} from './platform/textSelection';
 
 try {
+  installTextSelectionPolicy(
+    resolveTextSelectionMode((gameProjectConfig as { readonly ui?: unknown }).ui),
+  );
+
   if (__APP_TARGET__ === 'reddit') {
     await import('./platform/devvitEntrypoint');
   } else {

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

@@ -1,6 +1,16 @@
+import gameProjectConfig from '../mpgd.game.json';
+
 import { renderEntryFailure } from './runtime/renderEntryFailure';
+import {
+  installTextSelectionPolicy,
+  resolveTextSelectionMode,
+} from './platform/textSelection';
 
 try {
+  installTextSelectionPolicy(
+    resolveTextSelectionMode((gameProjectConfig as { readonly ui?: unknown }).ui),
+  );
+
   await import('./main');
 } catch (error) {
   renderEntryFailure(error);

package/templates/phaser-game/src/platform/textSelection.ts

@@ -0,0 +1,121 @@
+/**
+ * Game-wide text selection policy.
+ *
+ * Games render tap targets, not documents, so text selection is disabled
+ * globally by default and re-enabled only for input fields and elements that
+ * explicitly opt in through {@link markSelectable}.
+ *
+ * Under the disabled policy the stylesheet layers, in ascending precedence:
+ * default suppression, editable contenteditable hosts (any value except
+ * explicit `false`, descendants included), explicit non-editable islands, and
+ * finally form fields plus the {@link selectableElementClassName} opt-in.
+ * All selectors are :where() normalized, so game CSS can still override the
+ * policy for bespoke elements.
+ */
+
+export type TextSelectionMode = 'disabled' | 'enabled';
+
+/** Class that re-enables text selection on an element and its descendants. */
+export const selectableElementClassName = 'mpgd-selectable';
+
+const textSelectionStylesheetId = 'mpgd-text-selection-policy';
+
+export interface SelectableElement {
+  readonly classList: {
+    add(...tokens: string[]): void;
+    remove(...tokens: string[]): void;
+    contains(token: string): boolean;
+  };
+}
+
+/** Parse the `ui.textSelection` game setting, defaulting to disabled. */
+export function resolveTextSelectionMode(uiConfig: unknown): TextSelectionMode {
+  if (uiConfig === undefined) {
+    return 'disabled';
+  }
+
+  if (typeof uiConfig !== 'object' || uiConfig === null || Array.isArray(uiConfig)) {
+    throw new Error('mpgd.game.json ui must be an object when present.');
+  }
+
+  for (const key of Object.keys(uiConfig)) {
+    if (key !== 'textSelection') {
+      throw new Error(`mpgd.game.json ui.${key} is not supported.`);
+    }
+  }
+
+  const textSelection = (uiConfig as Record<string, unknown>).textSelection;
+
+  if (textSelection === undefined) {
+    return 'disabled';
+  }
+
+  if (textSelection !== 'disabled' && textSelection !== 'enabled') {
+    throw new Error("mpgd.game.json ui.textSelection must be 'disabled' or 'enabled'.");
+  }
+
+  return textSelection;
+}
+
+/** Build the stylesheet that enforces the selection policy. */
+export function buildTextSelectionStylesheet(mode: TextSelectionMode): string {
+  if (mode === 'enabled') {
+    return '/* mpgd: text selection enabled; browser default applies. */\n';
+  }
+
+  // Every selector is wrapped in :where() so all rules share zero specificity
+  // and source order defines the precedence:
+  // default suppression < editable hosts < explicit non-editable islands
+  // < form fields and the selectable opt-in utility.
+  return [
+    '*, *::before, *::after {',
+    '  -webkit-user-select: none;',
+    '  user-select: none;',
+    '  -webkit-touch-callout: none;',
+    '}',
+    ":where([contenteditable]:not([contenteditable='false'])),",
+    ":where([contenteditable]:not([contenteditable='false'])) * {",
+    '  -webkit-user-select: text;',
+    '  user-select: text;',
+    '  -webkit-touch-callout: default;',
+    '}',
+    ":where([contenteditable='false']), :where([contenteditable='false']) * {",
+    '  -webkit-user-select: none;',
+    '  user-select: none;',
+    '  -webkit-touch-callout: none;',
+    '}',
+    `:where(input, textarea, .${selectableElementClassName}),`,
+    `:where(input, textarea, .${selectableElementClassName}) * {`,
+    '  -webkit-user-select: text;',
+    '  user-select: text;',
+    '  -webkit-touch-callout: default;',
+    '}',
+  ].join('\n');
+}
+
+/** Install (or refresh) the global selection policy stylesheet. */
+export function installTextSelectionPolicy(mode: TextSelectionMode): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  let stylesheet = document.getElementById(textSelectionStylesheetId);
+
+  if (stylesheet === null) {
+    stylesheet = document.createElement('style');
+    stylesheet.id = textSelectionStylesheetId;
+    document.head.append(stylesheet);
+  }
+
+  stylesheet.textContent = buildTextSelectionStylesheet(mode);
+}
+
+/** Re-enable text selection for a specific UI element and its descendants. */
+export function markSelectable(element: SelectableElement): void {
+  element.classList.add(selectableElementClassName);
+}
+
+/** Withdraw a previous {@link markSelectable} opt-in. */
+export function unmarkSelectable(element: SelectableElement): void {
+  element.classList.remove(selectableElementClassName);
+}