@mpgd/adapter-capacitor 0.4.11 → 0.5.0

package/README.md

@@ -0,0 +1,225 @@
+# @mpgd/adapter-capacitor
+
+The base adapter uses `@mpgd/capacitor-game-services` for bounded local JSON
+storage and a small fail-closed bridge. It does **not** install a store, ad,
+identity, leaderboard, or push SDK. Pass separately installed modules through
+`createCapacitorPlatformGateway({ providers })`; each module declares its
+owned bridge methods, provider features, and current availability. Duplicate
+method/feature registrations and attempts to replace base storage are errors.
+
+```ts
+import {
+  createCapacitorPlatformGateway,
+  type CapacitorServiceProvider,
+} from '@mpgd/adapter-capacitor';
+
+export function createGameGateway(providers: readonly CapacitorServiceProvider[]) {
+  return createCapacitorPlatformGateway({
+    target: 'android',
+    appVersion: '1.0.0',
+    buildId: 'game-build',
+    providers,
+    classifyIncomingUrl(url) {
+      const incoming = new URL(url);
+      // Replace this example scheme with one registered by your native host.
+      if (incoming.protocol !== 'mygame:') return null;
+      if (incoming.hostname === 'oauth') return 'oauth';
+      if (incoming.hostname === 'game') return 'game';
+      return null;
+    },
+  });
+}
+```
+
+`getCapabilities()` reports a fresh boolean snapshot and optional
+`providerAvailability` detail. The possible states are `unsupported`,
+`configuration-required`, `action-required`, `temporarily-unavailable`, and
+`available`. A target's `features` configuration is an upper bound, **not**
+proof that a provider is installed or ready. `nativeIap` describes one-time
+purchases; `subscriptionIap` is separate. Rewarded, interstitial, and banner
+ads and native versus remote leaderboards remain distinct. Target-config
+applies the configured upper bound to this live provider state.
+
+When native and remote leaderboard routes coexist, the target-config wrapper
+selects a `route` on score/open calls; direct adapter callers can request
+`route: 'remote'` to use the base remote bridge instead of the native provider.
+When one ads provider handles multiple formats, pass `format` to `ads.preload`
+so its readiness check cannot use an available format for an unavailable one.
+
+Provider initialization failures and availability reads stalled beyond three
+seconds leave the base bridge and local guest boot available. A registered
+provider never silently falls back for purchase, ad, or native leaderboard
+operations; an explicit remote leaderboard route is a separate path. Errors
+retain a stable code and retry hint. The
+provider bridge must return a method-shaped response. In particular, an ad
+`rewardGranted: true` result requires a backend ledger entry. A native callback
+alone is evidence, not a grant. Game-specific product, consent, entitlement,
+and identity policy belongs to the consuming game and its backend.
+
+The source tests and installed-tarball consumer validate composition, types,
+error paths, and fallback behavior. They do not establish that any optional
+SDK works on a physical device or that a store/ad setup is release-ready.
+
+`gateway.secureCredentials` uses dedicated native Keychain/Keystore methods for
+opaque session credentials. Its absence or a native error must not be hidden by
+writing the secret into `gateway.storage`. Keys are bounded, values are
+size-limited, and malformed bridge responses fail closed. This is a storage
+boundary, not proof of server authentication: an installation ID or local
+`playerId` is never a server principal by itself.
+
+## App lifecycle and native entry
+
+The adapter uses the official Capacitor App plugin for foreground state,
+Android back navigation, and incoming URLs. Install `@capacitor/app` in the
+native shell and run `cap sync` so the native plugin is present. The reference
+shell and generated game template include it. A `classifyIncomingUrl` callback
+must explicitly return `game` or `oauth`; unknown URLs are discarded rather
+than being delivered to gameplay. Register your URL scheme or App/Universal
+Links in the native host separately. See the [Capacitor App API](https://capacitorjs.com/docs/apis/app).
+
+`lifecycle.onPause` and `onResume` deduplicate App and web visibility events.
+Purchases, ads, and identity upgrades keep execution paused until their
+provider operation settles. Use `beginExternalActivity` for other external UI.
+On Android, a back handler returns `true` if the game consumed the event;
+otherwise the adapter navigates browser history when possible or exits the
+app. Cold URLs are read through `getInitialGameUrl` or
+`getInitialOAuthRedirect`; warm URLs use separate `onGameUrlOpen` and
+`onOAuthRedirect` callbacks. OAuth responses never enter the game-link
+callback. Call `lifecycle.dispose()` when the host tears down this gateway;
+the adapter removes only its own listener handles, never every App listener.
+
+Save progress at checkpoints and transaction boundaries. A pause callback can
+request a best-effort save, but neither pause nor back is guaranteed to run
+before the operating system terminates a process. The lifecycle tests use an
+injected App API and do not claim device-level lifecycle verification.
+
+For example, let the game's checkpoint flow own durability; the native pause
+event is only an additional opportunity to flush the latest checkpoint:
+
+```ts
+import type { PlatformGateway } from '@mpgd/platform';
+
+export function attachCheckpointSaving(
+  gateway: PlatformGateway,
+  saveCheckpoint: () => Promise<void>,
+): () => void {
+  return gateway.lifecycle.onPause(() => {
+    void saveCheckpoint().catch((error: unknown) => {
+      console.error('Best-effort pause save failed.', error);
+    });
+  });
+}
+
+// The game also awaits saveCheckpoint() at level and transaction boundaries;
+// it must never defer its only save until a close, back, or pause event.
+```
+
+## Scoped native JSON HTTP
+
+`createCapacitorNativeJsonTransport` uses the explicit `CapacitorHttp.request`
+helper from `@capacitor/core`; it does not enable global `fetch` or XHR patching.
+Use it with the HTTP JSON path of `createGameServicesRuntime`, not the oRPC
+path. The game imports only public kit APIs:
+
+```ts
+import { createCapacitorNativeJsonTransport } from '@mpgd/adapter-capacitor';
+import { createGameServicesRuntime } from '@mpgd/game-services/runtime';
+
+const baseUrl = 'https://api.example.com';
+const httpTransport = createCapacitorNativeJsonTransport({
+  target: 'android',
+  baseUrl,
+  allowedOrigin: 'https://api.example.com',
+});
+const runtime = createGameServicesRuntime({
+  gateway,
+  playerId,
+  authorityMode: 'production',
+  baseUrl,
+  transport: 'http',
+  httpTransport,
+  getHeaders: () => ({ authorization: `Bearer ${currentAccessToken()}` }),
+});
+```
+
+The game supplies its real gateway, player ID, and token resolver. The native
+transport permits only its configured HTTPS origin and relative JSON API paths;
+it rejects 3xx responses and changed routes while tolerating equivalent native
+URL encoding of the same path or query. It requests
+`disableRedirects: true` from Capacitor. A native implementation that ignored
+that option could have followed a redirect before JS sees the result, so
+redirect and credential handling still require native integration testing.
+The transport owns `Accept: application/json` and POST `Content-Type`; callers
+supplying either header are rejected instead of having it silently rewritten.
+It supports GET and POST JSON only, not streaming, file uploads, or arbitrary
+Fetch semantics. `AbortSignal` and the overall timeout stop the
+JS wait; they do **not** prove the native request or server operation was
+canceled. Reconcile purchases and reward claims before retrying them.
+
+Request size is checked before calling the native bridge. The response size
+limit is checked **after** Capacitor returns data to JS; it is not a native
+receive-memory cap. The injected Http tests and platform staging builds cover
+the contract, not real network behavior on both physical OSes. See the
+[Capacitor HTTP API](https://capacitorjs.com/docs/apis/http) for the native
+helper and its redirect/timeout options.
+
+## Usable viewport and native occupied surfaces
+
+`gateway.viewport` reports the full WebView size and separate safe-area,
+system-bar, keyboard, and named occupied-surface measurements in **CSS pixels**.
+Pass the state to `resolveTargetViewportUsableArea` from `@mpgd/target-config`;
+it takes the furthest intrusion per edge rather than summing overlapping
+safe-area, system-bar, keyboard, and banner values. The default host reads the
+starter's `--mpgd-safe-area-*` CSS variables, Capacitor SystemBars'
+`--safe-area-inset-*` fallback, and `visualViewport` changes. On Android,
+SystemBars injects fallback CSS variables for older WebViews whose CSS `env`
+safe-area values are incorrect. The injected `--safe-area-inset-*` values must
+be valid CSS lengths on `documentElement` (`:root`); putting them only on
+`body` or a nested container does not update the root aliases. See the
+[SystemBars API](https://capacitorjs.com/docs/apis/system-bars).
+Keyboard behavior also depends on the native [Keyboard resize mode](https://capacitorjs.com/docs/apis/keyboard),
+so inspect the actual device layout before promising a particular inset.
+
+Choose **one layout owner**. The starter's existing CSS padding already
+reserves safe-area space; do not apply `usableArea.contentBounds` to that
+already-padded `#game` element. For a JS-owned full-viewport canvas and DOM
+overlay, remove the host's safe-area padding and apply the same rectangle to
+both elements:
+
+```ts
+import { resolveTargetViewportUsableArea } from '@mpgd/target-config';
+import type { PlatformGateway } from '@mpgd/platform';
+
+export function mountUsableViewport(
+  gateway: PlatformGateway,
+  canvasHost: HTMLElement,
+  overlayHost: HTMLElement,
+): () => void {
+  const viewport = gateway.viewport;
+  if (viewport === undefined) return () => undefined;
+  const apply = () => {
+    const state = viewport.getState();
+    const bounds = resolveTargetViewportUsableArea(state, state).contentBounds;
+    for (const element of [canvasHost, overlayHost]) {
+      element.style.position = 'absolute';
+      element.style.left = `${bounds.x}px`;
+      element.style.top = `${bounds.y}px`;
+      element.style.width = `${bounds.width}px`;
+      element.style.height = `${bounds.height}px`;
+    }
+  };
+  apply();
+  return viewport.onChange(apply);
+}
+
+// Call the returned unsubscribe during game teardown. lifecycle.dispose()
+// tears down the gateway-owned native viewport listeners.
+```
+
+Future banner providers can call `createCapacitorViewport()` and pass that
+controller to `createCapacitorPlatformGateway({ viewport })`, then report
+actual `surfaceId` bounds with `setOccupiedSurface`. For physical-pixel
+measurements, the provider supplies `pixelsPerCssPixel`; the game never guesses
+device pixel ratio. A caller-injected controller remains caller-owned and must
+be disposed separately. Tests cover layout, rotation, multiple surfaces, and
+unsubscribe, but do not establish physical-device inset or keyboard accuracy.

package/dist/app-events.d.ts

@@ -0,0 +1,23 @@
+import { type AppPlugin } from '@capacitor/app';
+import type { LifecycleAdapter } from '@mpgd/platform';
+export type CapacitorIncomingUrlKind = 'game' | 'oauth';
+export interface CapacitorVisibilitySource {
+  readonly hidden: boolean;
+  addEventListener(type: 'visibilitychange', listener: () => void): void;
+  removeEventListener(type: 'visibilitychange', listener: () => void): void;
+}
+export type CapacitorAppEventsApi = Pick<AppPlugin, 'addListener' | 'getState' | 'getLaunchUrl' | 'exitApp'>;
+export interface CreateCapacitorAppEventsInput {
+  readonly target: 'android' | 'ios';
+  readonly app?: CapacitorAppEventsApi;
+  readonly visibility?: CapacitorVisibilitySource | null;
+  /** Return null for URLs that this game does not own. Never default OAuth to game. */
+  readonly classifyIncomingUrl?: (url: string) => CapacitorIncomingUrlKind | null;
+  readonly historyBack?: () => void;
+  readonly onError?: (error: unknown) => void;
+}
+/**
+* Owns only handles it registers. Disposing during an awaited addListener
+* removes the eventual handle without touching another gateway's listeners.
+*/
+export declare function createCapacitorAppEvents(input: CreateCapacitorAppEventsInput): LifecycleAdapter;

package/dist/app-events.js

@@ -0,0 +1,332 @@
+import { App } from '@capacitor/app';
+const maxWarmUrlsBeforeInitial = 32;
+// Covers a near-simultaneous duplicate from getLaunchUrl and appUrlOpen, not a later tap.
+const coldUrlDedupeWindowMs = 2_000;
+function defaultVisibility() {
+    return typeof document === 'undefined' ? null : document;
+}
+/**
+ * Owns only handles it registers. Disposing during an awaited addListener
+ * removes the eventual handle without touching another gateway's listeners.
+ */
+export function createCapacitorAppEvents(input) {
+    const app = input.app ?? App;
+    const visibility = input.visibility === undefined ? defaultVisibility() : input.visibility;
+    const pauseCallbacks = new Set();
+    const resumeCallbacks = new Set();
+    const gameUrlCallbacks = new Set();
+    const oauthCallbacks = new Set();
+    const backHandlers = [];
+    const handles = [];
+    const warmUrlsBeforeInitial = new Set();
+    let disposed = false;
+    let initialResolved = false;
+    let appActive = true;
+    let visibilityActive = visibility?.hidden !== true;
+    let currentActive = true;
+    let transitionVersion = 0;
+    let stateEvents = 0;
+    let externalActivities = 0;
+    let backInProgress = false;
+    let startFailureReported = false;
+    let recentColdUrl;
+    let recentColdUntil = 0;
+    let startPromise;
+    let backPromise;
+    let initialPromise;
+    const reportError = (error) => {
+        try {
+            if (input.onError !== undefined) {
+                input.onError(error);
+            }
+            else {
+                console.error('Capacitor app event failed.', error);
+            }
+        }
+        catch {
+            // Reporting must not replace the original listener or registration error.
+        }
+    };
+    function emit(callbacks, version) {
+        for (const callback of [...callbacks]) {
+            // A callback can open or close external UI and reenter reconcile().
+            // Never continue an older resume/pause emission after that transition.
+            if (disposed || version !== transitionVersion) {
+                return;
+            }
+            try {
+                callback();
+            }
+            catch (error) {
+                reportError(error);
+            }
+        }
+    }
+    function reconcile() {
+        if (disposed) {
+            return;
+        }
+        const active = appActive && visibilityActive && externalActivities === 0;
+        if (active === currentActive) {
+            return;
+        }
+        currentActive = active;
+        transitionVersion += 1;
+        emit(active ? resumeCallbacks : pauseCallbacks, transitionVersion);
+    }
+    function classify(url) {
+        try {
+            const kind = input.classifyIncomingUrl?.(url);
+            return kind === 'game' || kind === 'oauth' ? kind : null;
+        }
+        catch (error) {
+            reportError(error);
+            return null;
+        }
+    }
+    function dispatchWarmUrl(url) {
+        if (disposed || url.trim() === '') {
+            return;
+        }
+        if (url === recentColdUrl && Date.now() <= recentColdUntil) {
+            // Capacitor can deliver the same launch through getLaunchUrl and
+            // appUrlOpen. Suppress only that immediate duplicate, not a later tap.
+            recentColdUrl = undefined;
+            return;
+        }
+        const kind = classify(url);
+        if (kind === null) {
+            return;
+        }
+        const callbacks = kind === 'game' ? gameUrlCallbacks : oauthCallbacks;
+        if (!initialResolved && callbacks.size > 0) {
+            // Keep enough recent entries to suppress a cold/warm duplicate without
+            // retaining an unbounded history when the host never requests cold URLs.
+            if (warmUrlsBeforeInitial.size >= maxWarmUrlsBeforeInitial) {
+                const oldest = warmUrlsBeforeInitial.values().next().value;
+                if (oldest !== undefined) {
+                    warmUrlsBeforeInitial.delete(oldest);
+                }
+            }
+            warmUrlsBeforeInitial.add(url);
+        }
+        const event = { url, source: 'warm' };
+        for (const callback of [...callbacks]) {
+            try {
+                callback(event);
+            }
+            catch (error) {
+                reportError(error);
+            }
+        }
+    }
+    async function own(registration) {
+        const handle = await registration;
+        if (disposed) {
+            await handle.remove();
+        }
+        else {
+            handles.push(handle);
+        }
+    }
+    function onVisibilityChange() {
+        visibilityActive = visibility?.hidden !== true;
+        reconcile();
+    }
+    function start() {
+        if (disposed) {
+            return Promise.reject(new Error('Capacitor app events are disposed.'));
+        }
+        if (startPromise !== undefined) {
+            return startPromise;
+        }
+        visibility?.addEventListener('visibilitychange', onVisibilityChange);
+        onVisibilityChange();
+        const beforeRead = stateEvents;
+        startPromise = Promise.all([
+            own(app.addListener('appStateChange', ({ isActive }) => {
+                stateEvents += 1;
+                appActive = isActive;
+                reconcile();
+            })),
+            own(app.addListener('appUrlOpen', ({ url }) => dispatchWarmUrl(url))),
+            app.getState().then(({ isActive }) => {
+                if (!disposed && stateEvents === beforeRead) {
+                    appActive = isActive;
+                    reconcile();
+                }
+            }),
+        ]).then(() => undefined);
+        return startPromise;
+    }
+    function startForSubscription() {
+        void start().catch((error) => {
+            if (startFailureReported) {
+                return;
+            }
+            startFailureReported = true;
+            reportError(error);
+        });
+    }
+    async function dispatchBack(event) {
+        for (const handler of [...backHandlers].reverse()) {
+            try {
+                if (await handler(event)) {
+                    return;
+                }
+                if (disposed) {
+                    return;
+                }
+            }
+            catch (error) {
+                reportError(error);
+            }
+        }
+        if (disposed) {
+            return;
+        }
+        if (event.canGoBack) {
+            if (input.historyBack !== undefined) {
+                input.historyBack();
+            }
+            else if (typeof history !== 'undefined') {
+                history.back();
+            }
+        }
+        else {
+            await app.exitApp();
+        }
+    }
+    function startBackListener() {
+        if (input.target !== 'android' || backPromise !== undefined || disposed) {
+            return;
+        }
+        backPromise = own(app.addListener('backButton', (event) => {
+            if (backInProgress || disposed) {
+                return;
+            }
+            backInProgress = true;
+            void dispatchBack(event).catch(reportError).finally(() => {
+                backInProgress = false;
+            });
+        }));
+        void backPromise.catch(reportError);
+    }
+    function subscribe(callbacks, callback) {
+        if (disposed) {
+            return () => { };
+        }
+        callbacks.add(callback);
+        startForSubscription();
+        return () => {
+            callbacks.delete(callback);
+        };
+    }
+    function getInitial() {
+        if (initialPromise !== undefined) {
+            return initialPromise;
+        }
+        startForSubscription();
+        initialPromise = app.getLaunchUrl().then((launch) => {
+            initialResolved = true;
+            const url = launch?.url;
+            const seenWarm = url === undefined ? false : warmUrlsBeforeInitial.has(url);
+            warmUrlsBeforeInitial.clear();
+            if (disposed || url === undefined || url.trim() === '' || seenWarm) {
+                return null;
+            }
+            const kind = classify(url);
+            if (kind === null) {
+                return null;
+            }
+            recentColdUrl = url;
+            recentColdUntil = Date.now() + coldUrlDedupeWindowMs;
+            return { kind, event: { url, source: 'cold' } };
+        }, (error) => {
+            initialResolved = true;
+            warmUrlsBeforeInitial.clear();
+            throw error;
+        });
+        return initialPromise;
+    }
+    async function dispose() {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        visibility?.removeEventListener('visibilitychange', onVisibilityChange);
+        pauseCallbacks.clear();
+        resumeCallbacks.clear();
+        gameUrlCallbacks.clear();
+        oauthCallbacks.clear();
+        backHandlers.length = 0;
+        warmUrlsBeforeInitial.clear();
+        recentColdUrl = undefined;
+        // Pending registrations remove themselves in own() if they later resolve.
+        // Teardown must not hang on an SDK registration that never does.
+        await Promise.allSettled(handles.splice(0).map((handle) => handle.remove()));
+    }
+    return {
+        onPause(callback) {
+            // start() may synchronously emit the first pause while subscribing.
+            const alreadyPaused = !disposed && currentActive === false;
+            const unsubscribe = subscribe(pauseCallbacks, callback);
+            if (alreadyPaused) {
+                try {
+                    callback();
+                }
+                catch (error) {
+                    reportError(error);
+                }
+            }
+            return unsubscribe;
+        },
+        onResume(callback) {
+            return subscribe(resumeCallbacks, callback);
+        },
+        onBackButton(handler) {
+            if (disposed || input.target !== 'android') {
+                return () => { };
+            }
+            backHandlers.push(handler);
+            startBackListener();
+            return () => {
+                const index = backHandlers.indexOf(handler);
+                if (index >= 0) {
+                    backHandlers.splice(index, 1);
+                }
+            };
+        },
+        onGameUrlOpen(callback) {
+            return subscribe(gameUrlCallbacks, callback);
+        },
+        onOAuthRedirect(callback) {
+            return subscribe(oauthCallbacks, callback);
+        },
+        async getInitialGameUrl() {
+            const initial = await getInitial();
+            return initial?.kind === 'game' ? initial.event : null;
+        },
+        async getInitialOAuthRedirect() {
+            const initial = await getInitial();
+            return initial?.kind === 'oauth' ? initial.event : null;
+        },
+        beginExternalActivity() {
+            if (disposed) {
+                return () => { };
+            }
+            externalActivities += 1;
+            reconcile();
+            let released = false;
+            return () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+                externalActivities -= 1;
+                reconcile();
+            };
+        },
+        dispose,
+    };
+}

package/dist/index.d.ts

@@ -1,11 +1,20 @@
-import { type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
-import type { PlatformGateway, PlatformTarget } from '@mpgd/platform';
-export interface NativeBridge {
-  request(input: BridgeRequest): Promise<BridgeResponse>;
-}
+import { type PlatformGateway, type PlatformTarget, type ViewportAdapter } from '@mpgd/platform';
+import { type CapacitorAppEventsApi, type CapacitorIncomingUrlKind, type CapacitorVisibilitySource } from './app-events.js';
+import { type CapacitorServiceProvider, type NativeBridge } from './providers.js';
+export { createCapacitorProviderRegistry, type CapacitorServiceProvider, type NativeBridge, } from './providers.js';
+export { createCapacitorAppEvents, type CapacitorAppEventsApi, type CapacitorIncomingUrlKind, type CapacitorVisibilitySource, } from './app-events.js';
+export { CapacitorNativeHttpError, createCapacitorNativeJsonTransport, type CapacitorJsonRequest, type CapacitorJsonResponse, type CapacitorNativeHttpErrorCode, type CapacitorNativeJsonTransport, type CreateCapacitorNativeJsonTransportInput, } from './native-http.js';
+export { createCapacitorViewport, type CapacitorViewportBaseState, type CapacitorOccupiedSurfaceInput, type CapacitorViewportController, type CapacitorViewportHost, } from './viewport.js';
 export declare function createCapacitorPlatformGateway(input: {
   readonly target: Extract<PlatformTarget, 'android' | 'ios'>;
   readonly appVersion: string;
   readonly buildId: string;
   readonly bridge?: NativeBridge;
+  readonly providers?: readonly CapacitorServiceProvider[];
+  readonly app?: CapacitorAppEventsApi;
+  readonly visibility?: CapacitorVisibilitySource | null;
+  readonly classifyIncomingUrl?: (url: string) => CapacitorIncomingUrlKind | null;
+  readonly historyBack?: () => void;
+  readonly onAppEventError?: (error: unknown) => void;
+  readonly viewport?: ViewportAdapter;
 }): PlatformGateway;