@mpgd/adapter-ait 0.5.2 → 0.6.0

package/dist/index.d.ts

@@ -3,6 +3,17 @@ import type { PlatformGateway } from '@mpgd/platform';
 export interface GamePlatformBridge {
   request(input: BridgeRequest): Promise<BridgeResponse>;
 }
+export interface AitSandboxStorage {
+  readonly getItem: (key: string) => string | null;
+  readonly setItem: (key: string, value: string) => void;
+  readonly removeItem?: (key: string) => void;
+}
+export interface CreateAitSandboxBridgeOptions {
+  /** Persistent browser storage used by local AIT playtests. Defaults to localStorage when available. */
+  readonly storage?: AitSandboxStorage | null;
+  /** Namespace for persisted sandbox values so they cannot collide with application-owned keys. */
+  readonly storageKeyPrefix?: string;
+}
 export declare function createAitPlatformGateway(input: {
   readonly appVersion: string;
   readonly buildId: string;
@@ -10,4 +21,4 @@ export declare function createAitPlatformGateway(input: {
   readonly fallbackBridge?: GamePlatformBridge;
 }): PlatformGateway;
 export { aitLifecyclePauseEvent, aitLifecycleResumeEvent, createAitLifecycleAdapter, dispatchAitLifecycleEvent, } from './lifecycle.js';
-export declare function createAitSandboxBridge(): GamePlatformBridge;
+export declare function createAitSandboxBridge(options?: CreateAitSandboxBridgeOptions): GamePlatformBridge;

package/dist/index.js

@@ -72,8 +72,18 @@ export { aitLifecyclePauseEvent, aitLifecycleResumeEvent, createAitLifecycleAdap
 function getBridge() {
     return globalThis.__GAME_PLATFORM_BRIDGE__;
 }
-export function createAitSandboxBridge() {
+export function createAitSandboxBridge(options = {}) {
     const storage = new Map();
+    let persistentStorage;
+    if (options.storage === undefined) {
+        persistentStorage = resolveAitSandboxBrowserStorage();
+    }
+    else {
+        persistentStorage = options.storage ?? undefined;
+    }
+    // PlatformGateway storage exposes load/save only. Sandbox callers should use stable,
+    // namespaced keys whose values are overwritten instead of creating an unbounded key stream.
+    const storageKeyPrefix = options.storageKeyPrefix ?? 'mpgd:ait-sandbox:';
     return {
         async request(input) {
             switch (input.method) {
@@ -167,41 +177,141 @@ export function createAitSandboxBridge() {
                     return ok(input, {});
                 case 'storage.load': {
                     const payload = input.payload;
-                    const found = payload.key !== undefined && storage.has(payload.key);
-                    const value = found && payload.key !== undefined
-                        ? cloneJsonValue(storage.get(payload.key))
-                        : undefined;
-                    return ok(input, !found
-                        ? { __mpgdBridgeProtocol: bridgeStorageLoadProtocol, found: false }
-                        : { __mpgdBridgeProtocol: bridgeStorageLoadProtocol, found: true, value });
+                    if (payload.key === undefined) {
+                        return ok(input, {
+                            __mpgdBridgeProtocol: bridgeStorageLoadProtocol,
+                            found: false,
+                        });
+                    }
+                    if (storage.has(payload.key)) {
+                        return ok(input, {
+                            __mpgdBridgeProtocol: bridgeStorageLoadProtocol,
+                            found: true,
+                            value: cloneJsonValue(storage.get(payload.key)),
+                        });
+                    }
+                    const persistent = loadPersistentSandboxValue(persistentStorage, `${storageKeyPrefix}${payload.key}`);
+                    // Browser storage access failures commonly remain blocked for the page lifetime. The
+                    // sandbox intentionally degrades once per bridge instead of retrying and logging on every
+                    // load. Production AIT storage uses the host bridge and is not affected by this fallback.
+                    if (!persistent.storageAvailable && persistentStorage !== undefined) {
+                        console.warn('[mpgd/adapter-ait] AIT sandbox persistent storage is unavailable; subsequent saves are memory-only and will not survive reloads.');
+                        persistentStorage = undefined;
+                    }
+                    if (persistent.found) {
+                        // Keep the hydrated cache detached from the returned parsed value. Callers may mutate
+                        // their result, while a later memory load must still model serialized storage.
+                        storage.set(payload.key, cloneJsonValue(persistent.value));
+                        return ok(input, {
+                            __mpgdBridgeProtocol: bridgeStorageLoadProtocol,
+                            found: true,
+                            value: persistent.value,
+                        });
+                    }
+                    return ok(input, {
+                        __mpgdBridgeProtocol: bridgeStorageLoadProtocol,
+                        found: false,
+                    });
                 }
                 case 'storage.save': {
                     const payload = input.payload;
                     if (payload.key !== undefined) {
-                        storage.set(payload.key, cloneJsonValue(payload.value));
+                        let serialized;
+                        let value;
+                        try {
+                            serialized = serializeJsonValue(payload.value);
+                            value = JSON.parse(serialized);
+                        }
+                        catch {
+                            return createSandboxBridgeError(input, 'STORAGE_SERIALIZATION_FAILED', 'AIT sandbox storage values must be JSON-serializable.');
+                        }
+                        try {
+                            savePersistentSandboxValue(persistentStorage, `${storageKeyPrefix}${payload.key}`, serialized);
+                        }
+                        catch {
+                            // The helper reports the original failure and the loss of reload durability. The
+                            // sandbox still honors its memory fallback so local gameplay can continue.
+                            persistentStorage = undefined;
+                        }
+                        storage.set(payload.key, value);
                     }
                     return ok(input, {});
                 }
                 default:
-                    return {
-                        id: input.id,
-                        ok: false,
-                        error: {
-                            code: 'UNSUPPORTED_METHOD',
-                            message: `Unsupported AIT sandbox method: ${input.method}`,
-                            retryable: false,
-                        },
-                    };
+                    return createSandboxBridgeError(input, 'UNSUPPORTED_METHOD', `Unsupported AIT sandbox method: ${input.method}`);
             }
         },
     };
 }
+function resolveAitSandboxBrowserStorage() {
+    try {
+        return globalThis.localStorage;
+    }
+    catch (error) {
+        reportAitSandboxStorageResolutionFailure(error);
+        return undefined;
+    }
+}
+function loadPersistentSandboxValue(storage, key) {
+    if (storage === undefined) {
+        return { found: false, storageAvailable: false };
+    }
+    let serialized;
+    try {
+        serialized = storage.getItem(key);
+    }
+    catch (error) {
+        return { found: false, storageAvailable: false };
+    }
+    if (serialized === null) {
+        return { found: false, storageAvailable: true };
+    }
+    try {
+        return {
+            found: true,
+            storageAvailable: true,
+            value: JSON.parse(serialized),
+        };
+    }
+    catch (error) {
+        console.warn(`[mpgd/adapter-ait] Removing corrupt sandbox storage value for key "${key}".`, error);
+        if (storage.removeItem === undefined) {
+            console.warn('[mpgd/adapter-ait] Corrupt sandbox storage cannot be removed; disabling persistent storage for this bridge.');
+            return { found: false, storageAvailable: false };
+        }
+        try {
+            storage.removeItem(key);
+        }
+        catch (cleanupError) {
+            console.warn('[mpgd/adapter-ait] Corrupt sandbox storage cleanup failed; disabling persistent storage for this bridge.', cleanupError);
+            return { found: false, storageAvailable: false };
+        }
+        return { found: false, storageAvailable: true };
+    }
+}
+function savePersistentSandboxValue(storage, key, serialized) {
+    if (storage === undefined) {
+        return;
+    }
+    try {
+        storage.setItem(key, serialized);
+    }
+    catch (error) {
+        console.warn('[mpgd/adapter-ait] AIT sandbox persistent storage save failed; subsequent saves are memory-only and will not survive reloads.', error);
+        throw error;
+    }
+}
+function reportAitSandboxStorageResolutionFailure(error) {
+}
 function cloneJsonValue(input) {
+    return JSON.parse(serializeJsonValue(input));
+}
+function serializeJsonValue(input) {
     const serialized = JSON.stringify(input);
     if (serialized === undefined) {
         throw new Error('AIT sandbox storage values must be JSON-serializable.');
     }
-    return JSON.parse(serialized);
+    return serialized;
 }
 function ok(input, data) {
     return {
@@ -210,3 +320,10 @@ function ok(input, data) {
         data,
     };
 }
+function createSandboxBridgeError(input, code, message, retryable = false) {
+    return {
+        id: input.id,
+        ok: false,
+        error: { code, message, retryable },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-ait",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Apps in Toss WebView platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -47,8 +47,8 @@
     "dist"
   ],
   "dependencies": {
-    "@mpgd/platform": "0.7.0",
-    "@mpgd/bridge": "0.6.1"
+    "@mpgd/bridge": "0.6.1",
+    "@mpgd/platform": "0.7.0"
   },
   "peerDependencies": {
     "@apps-in-toss/web-framework": ">=2.10.4 <3"