@mpgd/game-runtime 0.1.0

package/dist/actions/index.js

@@ -0,0 +1,321 @@
+import { observe } from '../observers.js';
+import { createGameUiBridge, } from '../ui/index.js';
+/** Scheduling/preflight rejection, distinct from a service result or external exception. */
+export class GameActionExecutionError extends Error {
+    code;
+    constructor(code) {
+        super(`Game action cannot start: ${code}`);
+        this.code = code;
+        this.name = 'GameActionExecutionError';
+    }
+}
+const purchaseSources = {
+    shop: true,
+    stage_fail: true,
+    result: true,
+    event: true,
+};
+/** Bind one coordinator to one runtime/client (including its player identity), above all screens. */
+export function createGameActionCoordinator(options) {
+    const { execution, client, onObserverError } = options;
+    const capacity = options.maxRememberedKeys ?? 1024;
+    if (!Number.isSafeInteger(capacity) || capacity < 1 || capacity > 10000) {
+        throw new RangeError('maxRememberedKeys must be an integer from 1 to 10000.');
+    }
+    const history = new Map();
+    let current;
+    let last;
+    let nextId = 0;
+    let disposed = false;
+    let needsReconciliation = false;
+    function isDisposed() {
+        return disposed || execution.getSnapshot().status === 'destroyed';
+    }
+    function reserve(kind, supplied, canStart) {
+        if (isDisposed()) {
+            throw new GameActionExecutionError('disposed');
+        }
+        const key = supplied.idempotencyKey;
+        const productId = kind === 'purchase' ? supplied.productId : undefined;
+        const source = kind === 'purchase' ? supplied.source : undefined;
+        const placementId = kind === 'rewarded-ad'
+            ? supplied.placementId
+            : undefined;
+        if (typeof key !== 'string' || key.trim() === ''
+            || (kind === 'purchase' && (typeof productId !== 'string' || productId.trim() === ''
+                || !Object.hasOwn(purchaseSources, source ?? '')))
+            || (kind === 'rewarded-ad' && (typeof placementId !== 'string' || placementId.trim() === ''))) {
+            throw new GameActionExecutionError('invalid-input');
+        }
+        // Copy only the flat public input; later caller mutation cannot change this invocation.
+        const input = Object.freeze(kind === 'purchase'
+            ? { productId, source, idempotencyKey: key }
+            : { placementId, idempotencyKey: key });
+        const fingerprint = JSON.stringify([kind, productId, source, placementId]);
+        const prior = history.get(key);
+        if (prior !== undefined && prior !== fingerprint) {
+            throw new GameActionExecutionError('key-conflict');
+        }
+        if (current !== undefined && current.key === key) {
+            return current;
+        }
+        if (last !== undefined && last.key === key) {
+            return last;
+        }
+        if (prior !== undefined) {
+            throw new GameActionExecutionError('already-completed');
+        }
+        if (needsReconciliation) {
+            throw new GameActionExecutionError('reconciliation-required');
+        }
+        if (current !== undefined) {
+            throw new GameActionExecutionError('busy');
+        }
+        if (history.size >= capacity) {
+            throw new GameActionExecutionError('history-full');
+        }
+        const id = ++nextId;
+        const bridge = createGameUiBridge({
+            initialSnapshot: Object.freeze({ kind, status: 'running', operationId: id }),
+            ...(onObserverError === undefined ? {} : { onListenerError: onObserverError }),
+        });
+        let resolve;
+        let reject;
+        const promise = new Promise((done, fail) => {
+            resolve = done;
+            reject = fail;
+        });
+        // A nested observer can join without attaching a rejection handler of its own.
+        void promise.catch(() => { });
+        let started = false;
+        let block;
+        let invoked = false;
+        function finish(status) {
+            flight.settled = true;
+            if (invoked && (status === 'pending' || status === 'exception')) {
+                needsReconciliation = true;
+            }
+            current = undefined;
+            if (invoked) {
+                last = flight;
+            }
+            else {
+                history.delete(key);
+            }
+            // Reentrant release observers can start another operation; only this flight is touched below.
+            bridge.setSnapshot(invoked
+                ? Object.freeze({ kind, status, operationId: id })
+                : Object.freeze({ kind, status: 'idle' }));
+            observe(() => block?.release(), onObserverError);
+            bridge.destroy();
+        }
+        function progress(value) {
+            if (flight.settled || value.kind !== kind) {
+                return;
+            }
+            // Whitelist fields: ports cannot leak raw receipts/responses through additional properties.
+            const base = { kind, sequence: value.sequence };
+            let safe;
+            switch (value.phase) {
+                case 'platform-result':
+                case 'completed':
+                    safe = Object.freeze({
+                        ...base,
+                        phase: value.phase,
+                        status: value.status,
+                    });
+                    break;
+                case 'server-result':
+                    safe = Object.freeze({
+                        ...base,
+                        phase: value.phase,
+                        accepted: value.accepted,
+                    });
+                    break;
+                case 'exception':
+                    safe = Object.freeze({
+                        ...base,
+                        phase: value.phase,
+                        at: value.at,
+                    });
+                    break;
+                default:
+                    safe = Object.freeze({ ...base, phase: value.phase });
+            }
+            bridge.setSnapshot(Object.freeze({ kind, status: 'running', operationId: id, progress: safe }));
+        }
+        const flight = {
+            id, key, promise, bridge, settled: false,
+            start() {
+                if (started) {
+                    return;
+                }
+                started = true;
+                void (async () => {
+                    try {
+                        if (isDisposed() || !canStart()) {
+                            throw new GameActionExecutionError('disposed');
+                        }
+                        block = execution.acquireBlock({ reason: `action:${kind}`, channels: ['simulation', 'gameplay-input'] });
+                        if (isDisposed() || !canStart()) {
+                            throw new GameActionExecutionError('disposed');
+                        }
+                        invoked = true;
+                        const result = await (kind === 'purchase'
+                            ? client.purchase(input, { onProgress: (value) => observe(() => progress(value), onObserverError) })
+                            : client.claimRewardedAd(input, { onProgress: (value) => observe(() => progress(value), onObserverError) }));
+                        finish(result.status);
+                        resolve(result);
+                    }
+                    catch (error) {
+                        finish('exception');
+                        reject(error);
+                    }
+                })();
+            },
+        };
+        history.set(key, fingerprint);
+        current = flight;
+        return flight;
+    }
+    function makeController(kind) {
+        if (isDisposed()) {
+            throw new GameActionExecutionError('disposed');
+        }
+        let ownerDisposed = false;
+        let snapshot = Object.freeze({ kind, status: 'idle' });
+        const bridge = createGameUiBridge({
+            initialSnapshot: snapshot,
+            ...(onObserverError === undefined ? {} : { onListenerError: onObserverError }),
+        });
+        let trackedId;
+        let detach = () => { };
+        function execute(input, attach) {
+            try {
+                if (ownerDisposed) {
+                    throw new GameActionExecutionError('disposed');
+                }
+                const flight = reserve(kind, input, () => !ownerDisposed);
+                if (trackedId !== flight.id) {
+                    detach();
+                    trackedId = flight.id;
+                    const update = (value) => {
+                        if (trackedId !== flight.id) {
+                            return;
+                        }
+                        snapshot = value;
+                        if (flight.settled) {
+                            detach();
+                            detach = () => { };
+                        }
+                        if (!ownerDisposed) {
+                            bridge.setSnapshot(value);
+                        }
+                    };
+                    if (!flight.settled) {
+                        detach = flight.bridge.subscribeSnapshot(update);
+                    }
+                    update(flight.bridge.getSnapshot());
+                }
+                observe(() => attach?.(flight), onObserverError);
+                flight.start();
+                return flight.promise;
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        }
+        return Object.freeze({
+            execute,
+            getSnapshot: () => snapshot,
+            subscribe(listener) {
+                if (ownerDisposed) {
+                    throw new GameActionExecutionError('disposed');
+                }
+                return bridge.subscribeSnapshot(listener);
+            },
+            isDisposed: () => ownerDisposed,
+            dispose() {
+                ownerDisposed = true;
+                bridge.destroy();
+                // Keep the current flight observer until settlement so its authoritative result remains readable.
+            },
+            bindScope(scope, projection) {
+                if (ownerDisposed || scope.isDisposed()) {
+                    throw new GameActionExecutionError('disposed');
+                }
+                let viewDisposed = false;
+                let viewId;
+                let detachView = () => { };
+                const dispose = () => {
+                    viewDisposed = true;
+                    detachView();
+                };
+                const release = scope.own(dispose);
+                return Object.freeze({
+                    dispose: release,
+                    execute(input) {
+                        if (viewDisposed || scope.isDisposed()) {
+                            return Promise.reject(new GameActionExecutionError('disposed'));
+                        }
+                        return execute(input, (flight) => {
+                            if (viewId === flight.id || viewDisposed || scope.isDisposed()) {
+                                return;
+                            }
+                            detachView();
+                            viewId = flight.id;
+                            const update = (value) => {
+                                if (viewDisposed || scope.isDisposed() || viewId !== flight.id) {
+                                    return;
+                                }
+                                if (flight.settled) {
+                                    detachView();
+                                    detachView = () => { };
+                                }
+                                observe(() => {
+                                    scope.setSnapshot(projection.snapshot(value));
+                                }, onObserverError);
+                                const projectEvent = projection.event;
+                                if (value.status !== 'running' && value.status !== 'idle'
+                                    && !viewDisposed && !scope.isDisposed() && viewId === flight.id && projectEvent !== undefined) {
+                                    observe(() => {
+                                        scope.emit(projectEvent(value));
+                                    }, onObserverError);
+                                }
+                            };
+                            if (!flight.settled) {
+                                detachView = flight.bridge.subscribeSnapshot(update);
+                            }
+                            update(flight.bridge.getSnapshot());
+                        });
+                    },
+                });
+            },
+        });
+    }
+    return Object.freeze({
+        createPurchaseController: () => makeController('purchase'),
+        createRewardedAdController: () => makeController('rewarded-ad'),
+        getAvailability() {
+            if (isDisposed()) {
+                return 'disposed';
+            }
+            if (current !== undefined) {
+                return 'busy';
+            }
+            if (needsReconciliation) {
+                return 'reconciliation-required';
+            }
+            return history.size >= capacity ? 'history-full' : 'ready';
+        },
+        dispose() {
+            disposed = true;
+        },
+    });
+}
+export function createPurchaseActionController(input) {
+    return input.coordinator.createPurchaseController();
+}
+export function createRewardedAdActionController(input) {
+    return input.coordinator.createRewardedAdController();
+}

package/dist/channels.d.ts

@@ -0,0 +1,2 @@
+export declare const executionChannels: readonly ["simulation", "gameplay-input", "rendering", "audio"];
+export type ExecutionChannel = (typeof executionChannels)[number];

package/dist/channels.js

@@ -0,0 +1,3 @@
+export const executionChannels = Object.freeze([
+    'simulation', 'gameplay-input', 'rendering', 'audio',
+]);

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { type ExecutionChannel } from './channels.js';
+import { type ObserverErrorHandler } from './observers.js';
+export type { ExecutionChannel } from './channels.js';
+export type { ObserverErrorHandler } from './observers.js';
+export interface ExecutionBlockInput {
+  readonly reason: string;
+  readonly channels: readonly ExecutionChannel[];
+}
+export interface ExecutionBlockInfo extends ExecutionBlockInput {
+  /** Diagnostic identifier, local to this controller. It cannot release a block. */
+  readonly id: number;
+}
+export interface ExecutionBlock {
+  readonly info: ExecutionBlockInfo;
+  release(): void;
+}
+export interface GameExecutionSnapshot {
+  readonly status: 'active' | 'destroyed';
+  /** Increments once per acquisition, first release, or first destruction, including diagnostic-only changes. */
+  readonly version: number;
+  /** True means blocked. Destroyed snapshots fail closed on every channel. */
+  readonly blocked: Readonly<Record<ExecutionChannel, boolean>>;
+  readonly blocks: readonly ExecutionBlockInfo[];
+}
+export type ExecutionListener = (snapshot: GameExecutionSnapshot) => void | Promise<void>;
+export interface GameExecutionController {
+  acquireBlock(input: ExecutionBlockInput): ExecutionBlock;
+  getSnapshot(): GameExecutionSnapshot;
+  /** Does not deliver the initial snapshot. Read it explicitly after subscribing. */
+  subscribe(listener: ExecutionListener): () => void;
+  destroy(): void;
+}
+export declare function createGameExecutionController(options?: {
+  readonly onListenerError?: ObserverErrorHandler;
+}): GameExecutionController;

package/dist/index.js

@@ -0,0 +1,122 @@
+import { executionChannels } from './channels.js';
+import { observe } from './observers.js';
+export function createGameExecutionController(options = {}) {
+    const onError = options.onListenerError;
+    const blocks = new Map();
+    const subscriptions = new Set();
+    const queue = [];
+    let nextId = 0;
+    let destroyed = false;
+    let delivering = false;
+    let snapshot = makeSnapshot(0);
+    function assertActive() {
+        if (destroyed) {
+            throw new Error('Game execution controller is destroyed.');
+        }
+    }
+    function makeSnapshot(version) {
+        const blocked = {
+            simulation: destroyed,
+            'gameplay-input': destroyed,
+            rendering: destroyed,
+            audio: destroyed,
+        };
+        for (const block of blocks.values()) {
+            for (const channel of block.channels) {
+                blocked[channel] = true;
+            }
+        }
+        return Object.freeze({
+            status: destroyed ? 'destroyed' : 'active',
+            version,
+            blocked: Object.freeze(blocked),
+            blocks: Object.freeze([...blocks.values()]),
+        });
+    }
+    function publish() {
+        snapshot = makeSnapshot(snapshot.version + 1);
+        queue.push({ snapshot, recipients: [...subscriptions] });
+        if (delivering) {
+            return;
+        }
+        delivering = true;
+        try {
+            for (let cursor = 0; cursor < queue.length; cursor += 1) {
+                const delivery = queue[cursor];
+                if (delivery === undefined) {
+                    continue;
+                }
+                for (const subscription of delivery.recipients) {
+                    // Destruction supersedes all queued active deliveries, including this round.
+                    if (subscription.active && (!destroyed || delivery.snapshot.status === 'destroyed')) {
+                        observe(() => subscription.listener(delivery.snapshot), onError);
+                    }
+                }
+            }
+        }
+        finally {
+            queue.length = 0;
+            delivering = false;
+            if (destroyed) {
+                subscriptions.clear();
+            }
+        }
+    }
+    return Object.freeze({
+        acquireBlock(input) {
+            assertActive();
+            // Copy and validate all caller-controlled data before mutating state.
+            const reason = input.reason;
+            const requested = input.channels;
+            if (typeof reason !== 'string' || reason.trim().length === 0) {
+                throw new TypeError('Block reason must be a non-empty string.');
+            }
+            if (!Array.isArray(requested) || requested.length === 0) {
+                throw new TypeError('At least one execution channel is required.');
+            }
+            const selected = [...new Set(requested)];
+            if (selected.some((channel) => !executionChannels.includes(channel))) {
+                throw new TypeError('Unknown execution channel.');
+            }
+            // Input getters/iterators may have reentered the controller.
+            assertActive();
+            const info = Object.freeze({
+                id: ++nextId,
+                reason,
+                channels: Object.freeze(selected),
+            });
+            blocks.set(info.id, info);
+            const token = Object.freeze({
+                info,
+                release() {
+                    if (!destroyed && blocks.delete(info.id)) {
+                        publish();
+                    }
+                },
+            });
+            publish();
+            return token;
+        },
+        getSnapshot: () => snapshot,
+        subscribe(listener) {
+            assertActive();
+            if (typeof listener !== 'function') {
+                throw new TypeError('Execution listener must be a function.');
+            }
+            const subscription = { listener, active: true };
+            subscriptions.add(subscription);
+            return () => {
+                subscription.active = false;
+                subscriptions.delete(subscription);
+            };
+        },
+        destroy() {
+            if (destroyed) {
+                return;
+            }
+            destroyed = true;
+            blocks.clear();
+            publish();
+        },
+    });
+}

package/dist/observers.d.ts

@@ -0,0 +1,3 @@
+/** Observation must never change the outcome of the operation being observed. */
+export type ObserverErrorHandler = (error: unknown) => void | Promise<void>;
+export declare function observe(callback: () => void | Promise<void>, onError?: ObserverErrorHandler): void;

package/dist/observers.js

@@ -0,0 +1,22 @@
+export function observe(callback, onError) {
+    const report = (error) => {
+        try {
+            const result = onError?.(error);
+            if (result !== undefined) {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+        catch {
+            // An error observer has no authority to fail a business operation.
+        }
+    };
+    try {
+        const result = callback();
+        if (result !== undefined) {
+            void Promise.resolve(result).catch(report);
+        }
+    }
+    catch (error) {
+        report(error);
+    }
+}

package/dist/phaser/index.d.ts

@@ -0,0 +1,26 @@
+import type Phaser from 'phaser';
+import type { GameExecutionController, GameExecutionSnapshot } from '../index.js';
+export interface GameplayAudioSink {
+  getMuted(): boolean;
+  setMuted(muted: boolean): void;
+}
+/** Only this scene's built-in pointer, keyboard, and gamepad plugins are affected. */
+export type GameplayScene = Pick<Phaser.Scene, 'sys' | 'input'>;
+export interface PhaserGameRuntimeBinding {
+  dispose(): void;
+}
+export type UnsupportedPhaserExecutionState = 'simulation-requires-input-block' | 'audio-sink-missing';
+export interface BindPhaserGameSceneInput {
+  readonly controller: GameExecutionController;
+  readonly scene: GameplayScene;
+  readonly resetInput: () => void;
+  readonly renderingPolicy: 'visibility';
+  readonly audio?: GameplayAudioSink;
+  readonly uiScope?: {
+    dispose(): void;
+  };
+  /** Phaser pause also suspends input: simulation-only blocking cannot preserve active input. */
+  readonly onUnsupportedState: (snapshot: GameExecutionSnapshot, reason: UnsupportedPhaserExecutionState) => void | Promise<void>;
+  readonly onError?: (error: unknown) => void | Promise<void>;
+}
+export declare function bindPhaserGameScene(input: BindPhaserGameSceneInput): PhaserGameRuntimeBinding;